한글판 DirectX 8.0 Ver 1.0(2002.08.12) - by dxk(,dex,덱스 케이)

이 헬프 파일은 DirectX 8.0의 한글 버전 입니다.

이 파일은 MS사가 직접 제작한 것이 아닙니다. 제가 개인적으로 번역기로 돌린 것입니다.^^;;;;

DirectX의 한글판 도큐먼트만 없다는 것이 어찌 분한지....ㅡ.ㅡ;;;

거의 사용하지도 않는 일본은 일본어 도큐먼트가 있는디...쉬파....국력이 약하다보니....MS에서 왕 무시 하죠.ㅠ.ㅠ;;;(될 수 있으면 논문도 영어로만 쓰지 말고 꼭 한글로도 씁시다.)

그러니 부족함이 많더라도 양해 바랍니다.

현재 DirectX 를 사용하는 분들께 작은 도움이 된다면 좋겠습니다.

참고로 이화일은 절대 비상업용의 목적으로 사용되어져야 합니다. 개인적인 공부를 위해서만 사용되어 져야 합니다.

상업용 목적으로 무단 배포를 금합니다.

그리고 제가 개인 홈페이지가 없기 때문에 아래의 사이트를 임시 거처로 정합니다. 홈페이지 주인에게 허락 받았을 뿐 홈피 주인과는 전혀 무관합니다.

http://www.spirit3d.net

앞으로도 시간이 된다면 지속적인 오역을 잡아 가도록 하겠습니다.

기타 문의나 오역 신고는 http://www.spirit3d.net 의 자유 게시판에서 해주시기 바랍니다.

만든이 dxk(또는 dex,덱스 케이)

이메일 : dx-kor@hanmail.net

임시 홈페이지:http://www.spirit3d.net

2002년 8월 12일


법적 정보

DirectX 8
프로그래머 레퍼런스

본서에 기재되어 있는 정보는, URL 및 인터넷 Web 사이트의 참조도 포함해, 예고없이 변경되는 일이 있습니다. 본서로 예로서 취하는 기업, 조직, 제품, 인물, 및 이벤트는 모두 가공의 것입니다. 실재의 기업, 조직, 제품, 인물, 또는 이벤트와의 관련성을 시사하는 것이 아닙니다. 본서의 사용해서는, 손님의 책임에 대해, 적용되는 모든 저작권법에 따라 주세요. 저작권법에 따를 권리의 제한내에 머무르지 않고, 또, 사용 목적에 관계없이, Microsoft Corporation 로부터의 서면에 의한 허가없이, 본서의 일부 또는 전부를 무단으로 복제하거나 검색 시스템에 저장 또는 도입하거나 혹은 어떠한 형식이나 수단 (전자적, 기계적, 복사, 녹음, 그 외)에서도 전달할 수 없습니다.

Microsoft 는, 본서의 내용에 관련하는 특허, 특허 신청, 상표, 저작권, 그 외의 지적 소유권을 가지는 경우가 있습니다. Microsoft 로부터의 라이센스 계약 문서로 명시적으로 규정되어 있지 않은 한, 본서를 입수해도 Microsoft 로부터 상기 특허, 상표, 저작권, 그 외의 지적 소유권의 어느 라이센스를 취득한 것으로도 되지 않습니다.

© 1995-2000 Microsoft Corporation.All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT, ActiveX, Direct3D, DirectAnimation, DirectDraw, DirectInput, DirectMusic, DirectPlay, DirectShow, DirectSound, DirectX, Natural, 및 Win32 는, 미국 및 그 외의 각국에 있어서의 Microsoft Corporation 의 등록상표 또는 상표입니다.

Roland GS Sound Set/Microsoft (R) 1996 Roland Corporation U.S.

Roland 는 Roland Corporation 의 등록상표입니다.

본서에 기재되어 있는 실재의 회사명 및 제품명은, 각사의 상표입니다.

주 : 이 API 를 이행 하는 통신 디바이스의 메이커는, 1996 년의 통신법 제 255 조 (Section 255 of the Telecommunications Act)에 준거하고 있을 필요가 있습니다.

저작권에 관한 주의

특별한 주의 Roland GS Sound Set/Microsoft, 즉 "샘플 세트" 에는 로우 랜드 사운드 캔버스 사운드 세트가 짜넣어지고 있습니다. 미국 Roland Corporation 는, 샘플 세트와 거기에 관련하는 모든 저작권을 보유하고 있습니다. 게다가 샘플 세트의 사용은, Microsoft 의 operating system 제품 및 어플리케이션 제품에서만 허가되고 있습니다.

Microsoft 의 사용 허락 계약서의 조항으로, 샘플 세트에 관해서 미국 Roland Corporation 또는 Microsoft 에 의해 명백하게 허가되어 있지 않을 권리는, 모두 로우 랜드가 보유합니다.

샘플 세트의 재반포는, Microsoft operating system 제품의 통합 컴퍼넌트로서 Microsoft 의 사용 허락 계약서의 조항에 따라, 소프트웨어 어플리케이션과 함께 실시하는 경우에게만 인정됩니다. 샘플 세트를 그 외의 용도에 사용하는 경우는, 미국 Roland Corporation 로부터의 다른 서면에 의한 허가가 필요합니다.

미국 Roland Corporation 의 법적 권한을 가지는 대표자에 의한 서면에 의한 사전 승인 없고, 샘플 세트를 하드웨어 ROM 또는 같은 디바이스로, 사용, 복사, 또는 재반포할 수 없습니다. 또, 샘플 세트를 어떠한 악기와 함께 재반포할 수 없습니다. "악기" 란, 라이센스 된 Microsoft operating system를 실행하고 있는 컴퓨터에 직접 접속하지 않아도, 음악의 사운드를 생성할 수가 있는 디바이스입니다. 어떠한 환경에 있어도, 샘플 세트를 수정하는 것은 허가되고 있지 않습니다.

Built on 2000년 11월 18일


DirectX 8.0 의 소개

Microsoft® DirectX® 는, 게임 및 그 외의 하이 퍼포먼스인 멀티미디어 어플리케이션을 생성하기 위한 하위 레벨의 어플리케이션 프로그래밍 인터페이스 (API)세트이다. Microsoft® DirectX® 는, 2 차원 (2D)과 3 차원 (3D)의 그래픽스, 사운드 이펙트와 뮤직, 입력 디바이스, 멀티 플레이어 게임등의 네트워크 어플리케이션을 지원 한다.

이 문서에서는, DirectX 8.0 에 관한 개요를 기술한다. 설명하는 주제는, 다음과 같다.

  • DirectX 8.0 의 신기능
  • DirectX 8.0 문서의 사용법
  • DirectX 8.0 의 컴퍼넌트
  • DirectX 툴
  • C 또는 C++ 에 의한 DirectX 프로그래밍
  • 참고 자료


DirectX 8.0 의 신기능

Microsoft® DirectX® 8.0 으로 지원 되고 있는 신기능의 몇개인가를 이하에 나타낸다.

DirectDraw 와 Direct3D 의 완전한 통합
Microsoft DirectDraw® 와 Microsoft Direct3D® 는 단일의 DirectX Graphics 컴퍼넌트에 통합되었다. API 는 크게 변경되어 보다 한층 사용하기 쉽게 되어, 최신의 그래픽스 하드웨어가 지원 되게 되었다.
DirectMusic 와 DirectSound 의 통합의 강화
Microsoft DirectMusic® 와 Microsoft DirectSound® 의 통합이, DirectX 7.0 보다 강화되었다. 웨이브 파일이나 리소스를 DirectMusic 로더로 로드해, MIDI 노트와 동기 되는 DirectMusic 퍼포먼스로 연주할 수 있게 되었다.
DirectPlay 의 업데이트
Microsoft DirectPlay® 컴퍼넌트는 크게 확장되어 기능이 증가해 게다가 한층 더 사용하기 쉽게 되었다. 특히 DirectPlay 에서는, 플레이어 사이의 음성 통신이 지원 되게 되었다.
DirectInput 의 업데이트
Microsoft DirectInput® 에 주요한 기능이 추가되었다. 그것은, 액션 매핑이다. 액션 매핑을 사용 하면, 특정의 디바이스 오브젝트에 의존하지 않고 , 입력 액션과 입력 디바이스간의 접속을 확립할 수 있다. 그 때문에, 입력 루프가 간단하게 되어, 커스텀 게임 드라이버, 커스텀 디바이스 프로 filer, 및 게임의 커스텀 구성 유저 인터페이스의 필요성이 저하한다.
DirectShow 가 DirectX 에 포함되었다
Microsoft DirectShow® 는 현재 DirectX 의 일부이며, 이 릴리스용으로 갱신되었다.
디버그 빌드가 이용 가능
DirectX 컨트롤 패널 어플리케이션을 사용 하면,DirectInput, Direct3D, 및 DirectMusic 의 디버그 빌드와 리테일 빌드를 바꿀 수가 있다. 이 기능을 유효하게 하려면 , SDK 를 인스톨 할 경우에 디버그 옵션을 선택한다. 이 옵션을 선택 하면, 시스템에는 DLL 의 디버그 버젼과 리테일 버젼이 인스톨 된다. 리테일 옵션을 선택했을 경우는, DLL 의 리테일 버젼만이 인스톨 된다.


DirectX 8.0 문서의 사용법

이하의 표기는 설명이나 간단한 코드외, 메소드, 함수, 및 그 외의 API 요소의 구문으로 사용된다.

표기 | 의미
Italic text (이탤릭 캐릭터 라인) | 플레이스홀더 또는 변수를 나타낸다. 여기에는 실제의 값을 넣을 필요가 있다. 예를 들어, 본문에 SetCursorPos(X, Y)라고 쓰여지고 있었을 경우, 실제의 코드에서는 X 및 Y 의 부분에는 구체적인 값을 넣지 않으면 안 된다.
Bold text (굵은 글씨 캐릭터 라인) | 프로그래밍 인터페이스나 언어등으로의 함수, 프로시저, 구조체, 매크로, 인터페이스, 메소드, 데이터형, 및 그 외의 키워드를 나타낸다.
[] | 생략 가능한 파라미터를 나타낸다.
... | 직전의 항목을 반복해 기술할 수 있는 것을 나타낸다.
FULL BOLD CAPITALS (모두 굵은 글씨의 대문자) | 많은 형태 (타입)와 구조체의 이름에 사용된다.
FULL CAPITALS (모두 대문자) | 열거값, 플래그, 및 정수에 사용된다.
monospace (물건 스페이스) | 코드예와 구문의 스페이스에 사용된다.
. . . | 샘플 어플리케이션에서의 생략 부분을 나타낸다.


DirectX 8.0 의 컴퍼넌트

Microsoft® DirectX® 8.0 은 이하의 컴퍼넌트로 구성된다.

  • DirectX Graphics 는, DirectX 의 이전버전의 Microsoft DirectDraw® 컴퍼넌트와 Microsoft Direct3D® 컴퍼넌트가 결합된 단일의 API 이며, 모든 그래픽스 프로그래밍에 사용할 수 있다. 컴퍼넌트에는, 많은 그래픽스 프로그래밍 작업을 간단하게 하는 Direct3DX 유틸리티 라이브러리가 포함된다.
  • DirectX Audio 는, 이전버전의 DirectX 의 Microsoft DirectSound® 컴퍼넌트와 DirectMusic® 컴퍼넌트가 결합된 단일의 API 이며, 모든 오디오 프로그래밍에 사용할 수 있다.
  • Microsoft DirectInput® 는, force feedback 테크놀러지의 풀 지원 등, 다양한 입력 디바이스를 지원 하고 있다.
  • Microsoft DirectPlay® 는, 멀티 플레이어용 네트워크 게임을 지원 한다.
  • Microsoft DirectShow® 는, 멀티미디어 스트림의 고품질인 캡춰 및 재생을 제공한다.
  • Microsoft DirectSetup 는, 복수의 DirectX 컴퍼넌트를 한 번에 인스톨 할 수 있도록(듯이)하기 위한 간단한 API 이다.


DirectX 툴

이하의 툴은, Microsoft® DirectX® 어플리케이션의 개발과 트러블 슈팅에 이용할 수 있다.

  • DirectX Caps Viewer
  • DirectX 컨트롤 패널 어플리케이션
  • DirectX Diagnostic Tool


DirectX Caps Viewer

설명

DirectX Caps Viewer 툴은, Microsoft® DirectX® 의 모든 컴퍼넌트의 디바이스와 기능을 열거한다.

패스

실행 가능 파일 : (SDK 루트) \Bin\DXUtils\DXCapsViewer.exe

유저즈 가이드

트리 뷰로 주제를 선택한다. 우측의 페인에 정보가 표시된다.


DirectX 컨트롤 패널 어플리케이션

SDK 와 함께 인스톨 되는 Microsoft® DirectX® 컨트롤 패널 유틸리티를 사용 하면, DirectX 컴퍼넌트의 프로퍼티를 조사하거나 변경할 수가 있다. 이 유틸리티에는, 각 DirectX 컴퍼넌트용의 탭이 포함된다. 이 유틸리티를 사용하면(자), 다음과 같은 작업이 가능하다.

  • DirectX 컴퍼넌트의 버젼 정보를 취득한다.
  • 개발 프로세스로 트러블 슈팅에 도움이 되는 디버그 출력 레벨 및 디버그 설정을 변경한다.
  • DirectX 컴퍼넌트의 특정의 드라이버 및 하드웨어 지원 정보를 표시한다.
  • Microsoft Direct3D®, DirectMusic®, 및 DirectInput® 의 런타임을 디버그 버젼과 리테일 버젼의 사이에 바꾼다.


DirectX Diagnostic Tool

설명

Microsoft® DirectX® Diagnostic Tool 는, 컴퍼넌트가 정상적으로 기능하고 있을지 어떨지를 테스트할 뿐만 아니라, 시스템과 시스템에 인스톨 되고 있는 DirectX 컴퍼넌트의 정보를 수집한다. DirectX SDK 와 함께 인스톨 되는 이 툴의 특별 버젼을 사용하는 것으로, 개발자는 DirectX 개발 팀에 문제를 직접 보고할 수 있다.

패스

실행 가능 파일 : (Windows 루트) \System32\Dxdiag.exe

유저즈 가이드

DirectX Diagnostic Tool 헬프 파일을 표시하려면 ,[Help] 버튼을 클릭한다.


C 또는 C++ 에 의한 DirectX 프로그래밍

보통, C 또는 C++ 에 의한 Microsoft® DirectX® 어플리케이션 개발에는, 종래의 프로그래밍 기법이 사용된다. 다만, DirectX 프로그래밍에는, 종래의 프로그래밍과 다른 특수한 요소가 몇개인가 있다. 여기에서는, DirectX 고유의 토픽에 대해 간단하게 설명해, DirectX 어플리케이션의 컴파일 및 디버그의 가이드 라인을 나타낸다.

  • COM 의 사용법
  • 콜백 함수의 사용법
  • 버젼 체크
  • DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일
  • DirectX 어플리케이션의 디버그


COM 의 사용법

컴퍼넌트 오브젝트 모델 (COM)은, 다양한 어플리케이션으로 사용되고 있는 객체 지향 프로그래밍 모델의 1 개이다. 보통, Microsoft® DirectX® 런타임은 COM 대응 오브젝트의 형식을 취한다. 이 때문에, 모든 DirectX 개발자는, COM 의 원리와 프로그래밍 기법에 관한 기본적 지식이 최저한 필요하다. 다만, 일반적으로 COM 는 복잡하고 어렵다고 여겨지고 있지만, 대부분의 DirectX 어플리케이션으로 요구되는 COM 프로그래밍은 간단해 이해하기 쉽다.

COM 프로그래밍은 크고 2 개의 종류로 분류된다.

  • 기존의 COM 오브젝트를 사용하는 경우. 이것은, C++ 오브젝트를 사용하는 경우와 난이도적으로 큰 차이는 없다.
  • 독자적인 COM 오브젝트를 이행 하는 경우. 이것에는, 복잡하고 어려운 작업이 필요한 경우가 있다. COM 가 복잡하다고 말해지는 것은, 이 종류의 COM 프로그래밍에 기인한다.

대부분의 DirectX 어플리케이션은, DirectX 에 준비되어 있는 COM 오브젝트만을 사용하고 있다. 독자적인 COM 오브젝트를 이행 할 필요는 없다. 즉, 대부분의 DirectX 개발자가 관련되는 것은, 최초의 간단한 종류의 COM 프로그래밍만으로 좋게 된다.

여기에서는, DirectX 에 준비되어 있는 COM 오브젝트의 사용법에 대해 간단하게 설명한다. 여기서의 설명은, 주로, COM 프로그래밍 경험이 적은 개발자를 대상으로 하고 있다. COM 오브젝트의 상세 및 독자적인 COM 오브젝트의 이행 방법에 대해서는, 「참고 자료」를 참조할것.

  • COM 오브젝트란
  • COM 오브젝트의 생성
  • COM 인터페이스의 사용법
  • COM 오브젝트의 수명의 관리
  • C 에 의한 COM 오브젝트에의 액세스
  • 매크로에 의한 DirectX COM 메소드의 호출
  • DirectX COM 문서의 표기 규칙
  • IUnknown 인터페이스


COM 오브젝트란

COM 오브젝트는, 기본적으로, 1 개(살) 또는 복수의 태스크를 실행하기 위해서 어플리케이션으로 사용되는 블랙 박스와 같은 것이다. DLL 로서 이행 하는 것이 가장 일반적이다. 종래의 DLL 같이, COM 오브젝트가 지원 하고 있는 모든 처리는, 오브젝트에 의해 공개되고 있는 메소드를 어플리케이션으로부터 호출하는 것에 의해 실행할 수 있다. 어플리케이션이 COM 오브젝트와 교환하는 방법은, C++ 오브젝트와 교환하는 방법과 닮아 있다. 다만, 이러한 사이에는 몇개의 현저한 차이점이 있다.

  • COM 오브젝트는, C++ 오브젝트보다 캡슐화의 방법이 엄밀하다. 오브젝트를 생성 한 것 만으로는, 공개의 메소드를 호출할 수 없다. COM 오브젝트의 공개 메소드는, 1 개(살) 또는 복수의 인터페이스에 그룹화 된다. 메소드를 사용하려면 , 오브젝트를 생성 해, 그 오브젝트에 적절한 인터페이스를 취득할 필요가 있다. 보통, 각 인터페이스에는 관련성이 있는 일련의 메소드가 포함되어 있어 이러한 메소드가 오브젝트의 특정의 기능에의 액세스를 제공한다. 예를 들어,IDirect3DCubeTexture8 인터페이스에는, 큐브 텍스쳐 리소스를 조작하는 메소드군이 포함되어 있다. 인터페이스에 속하지 않는 메소드에는 액세스 할 수 없다.
  • COM 오브젝트와 C++ 오브젝트는, 생성 방법이 다르다. COM 오브젝트를 생성 하는 방법은 다수 있지만, 모든 방법으로 COM 고유의 기법이 이용된다. Microsoft® DirectX® API 에는, 다양한 헬퍼 함수 및 메소드가 포함되어 있어 이것들을 사용하는 것에 의해, 대부분의 DirectX 오브젝트를 간단하게 생성 할 수 있다.
  • 오브젝트의 수명을 제어하려면 , COM 고유의 기법을 이용할 필요가 있다.
  • COM 오브젝트는 명시적으로 로드할 필요가 없다. 보통, COM 오브젝트는 DLL 에 포함되어 있다. 그러나, COM 오브젝트를 사용하기 위해서, DLL 또는 정적 라이브러리에의 링크를 명시적으로 로드할 필요는 없다. 오브젝트를 생성 하려면 , 각 오브젝트에 할당할 수 있고 있는 일의의 등록이 끝난 식별자를 사용한다. COM 에 의해 올바른 DLL 가 자동적으로 로드 된다.
  • COM 는 바이너리 사양이다. COM 오브젝트는, 다양한 언어로 기술할 수 있어 다양한 언어로 액세스 할 수 있다. 오브젝트의 원시 코드에 대해 알 필요는 없다. 예를 들어, Microsoft Visual Basic® 어플리케이션에서는, C++ 로 기술된 COM 오브젝트가 매우 일반적으로 사용된다.

오브젝트와 인터페이스

오브젝트와 인터페이스의 차이를 이해하는 것은 중요한 것이다. 오브젝트는, 일상적으로, 그 주가 되는 인터페이스의 이름으로 불리는 일도 있다. 그러나, 엄밀하게는, 이 2 개의 용어는 의미가 다르다.

  • 1 개의 오브젝트가 복수의 인터페이스를 공개하고 있는 경우가 있다. 예를 들어, 모든 오브젝트는 IUnknown 인터페이스를 공개할 필요가 있어, 보통, 각 오브젝트는 이 밖에도 1 개(살) 이상의 인터페이스를 공개하고 있다. 1 개의 오브젝트가 다수의 인터페이스를 공개할 수도 있다. 메소드를 사용하려면 , 그 메소드의 오브젝트를 생성 할 뿐만 아니라, 올바른 인터페이스를 취득할 필요가 있다.
  • 복수의 오브젝트가 같은 인터페이스를 공개하고 있는 경우가 있다. 인터페이스는, 특정의 일련의 조작을 실행하는 메소드의 집합이다. 인터페이스의 정의에 의해 지정되는 것은, 그 인터페이스에 속하는 메소드의 구문과 일반적인 기능 뿐이다. COM 오브젝트는, 특정의 일련의 조작을 지원 하는 수단으로서 적절한 인터페이스를 공개한다. 전문성이 높고, 공개하고 있는 오브젝트가 1 개만의 인터페이스도 있다. 그 외의 인터페이스는 다양한 환경에서 이용할 수 있어 다수의 오브젝트에 의해 공개되고 있다. 그 극단적인 예가 IUnknown 인터페이스이다. 이 인터페이스는, 모든 COM 오브젝트가 공개해야 한다.

주 인터페이스를 공개하는 오브젝트는, 반드시, 그 인터페이스 정의에 포함되는 모든 메소드를 지원 해야 한다. 바꾸어 말하면, 메소드를 호출하면나무에, 그것이 존재할지 어떨지를 걱정할 필요는 없다. 다만, 각 메소드의 이행 방법은 오브젝트에 따라서 다른 경우가 있다. 예를 들어, 최종적인 결과는 같아도, 오브젝트에 의해, 사용하는 알고리즘이 다른 경우가 있다. 또, 메소드의 모든 기능이 지원 되고 있다고 하는 보증은 없다. 오브젝트가 일반적인 인터페이스를 공개 하면 와, 그 인터페이스에 속하는 메소드군의 서브 세트를 지원 하는 것만으로 좋은 경우가 있다. 이 때, 지원되어 있지 않은 메소드도 정상적으로 호출할 수가 있지만, E_NOTIMPL 가 돌려주어진다. 오브젝트의 문서를 참조해, 각 오브젝트에서의 인터페이스의 이행 상태를 확인하는 것을 권한다.

COM 표준에서는, 공개 끝난 인터페이스 정의는 변경할 수 없게 되어 있다. 예를 들어, 기존의 인터페이스에 새로운 메소드를 추가할 수 없다. 인터페이스를 변경하는 것이 아니라, 새로운 인터페이스를 생성 할 필요가 있다. 인터페이스에 반드시 포함하지 않으면 안 되는 메소드등의 제약은 없지만, 새로운 세대의 인터페이스에는, 그 바탕으로 되어 있는 인터페이스의 모든 메소드와 추가되는 새로운 메소드를 포함하는 것이 일반적이다.

1 개의 인터페이스에 복수의 세대가 존재하는 일도 드물지 않다. 보통, 어느 세대라도 본질적으로 전체적으로는 같은 태스크를 실행하지만, 세부가 차이가 난다. 많은 경우, 오브젝트는 모든 세대의 인터페이스를 공개한다. 이것에 의해, 낡은 어플리케이션에서는, 오브젝트의 낡은 인터페이스를 계속해 사용해, 새로운 어플리케이션에서는, 새로운 인터페이스의 기능을 이용할 수가 있다. 보통, 1 살의 패밀리에 속하는 인터페이스에는 모두 같은 이름이 사용되어 거기에 세대를 나타내는 정수가 부가된다. 예를 들어, 초대의 인터페이스의 이름이 IMyInterface 이었다고 하면(자), 다음의 2 세대의 이름은 IMyInterface2 및 IMyInterface3 가 된다. Microsoft DirectX® 에서는, 보통, 각 세대의 인터페이스의 이름에 DirectX 의 버젼 번호를 사용하고 있다.

GUID

글로벌 유니크 식별자 (GUID)는, COM 프로그래밍 모델의 주요한 부분의 1 개이다. GUID 를 가장 간단하게 설명 하면, GUID 는 128 비트의 구조체이다. 다만, GUID 를 생성 하면나무는, 그 밖에 같은 GUID 가 존재하지 않는 것이 보증되지 않으면 안 된다. COM 는, 주로 다음의 2 개의 목적으로 GUID 를 사용한다.

  • 특정의 COM 오브젝트를 식별하기 위해(때문에). COM 오브젝트에 할당할 수 있었던 GUID 를 클래스 ID (CLSID)라고 부른다. CLSID 는, 관련지을 수 있고 있는 COM 오브젝트의 인스턴스를 생성 할 경우에 사용된다.
  • 특정의 COM 인터페이스를 식별하기 위해(때문에). COM 인터페이스에 할당할 수 있었던 GUID 를 인터페이스 ID (IID)라고 부른다. IID 는, 오브젝트로부터 특정의 인터페이스를 요구할 경우에 사용된다. 공개하고 있는 오브젝트가 달라도, 같은 인터페이스이면, IID 도 같다.

주 보통, 문서로 오브젝트나 인터페이스를 부를 때는, 알기 쉽게 IDirect3D8 등의 설명적인 이름이 사용된다. 문서에서는, 문맥에 의해 무엇을 나타내고 있는지를 알므로, 혼동 될 걱정은 거의 없다. 다만, 엄밀하게 말하면, 같은 설명적 이름을 가지는 오브젝트 또는 인터페이스가 그 밖에 존재하지 않는다고 하는 보증은 없다. 특정의 오브젝트 또는 인터페이스를 틀림없이 나타낼 수가 있는 유일한 방법은, GUID 에 의하는 것이다.

GUID 는 구조체이지만, 등가인 캐릭터 라인으로서 표현되는 일도 있다. GUID 의 캐릭터 라인 형식에서는,"{VVVVVVVV-WWWW-XXXX-YYYY-ZZZZZZZZZZZZ}" 라고 하는 포맷이 일반적이다. 각 문자는, 16 진표기의 정수이다. 예를 들어,IDirect3D8 인터페이스의 IID 를 캐릭터 라인 형식에서 나타내면(자) 다음과 같이 된다.

{1DD9E8DA-1C77-4D40-B0CF-98FEFDFF9512}

실제의 GUID 는 사용하기 어렵고, 오입력하기 쉽기 때문에, 보통은, GUID 와 함께 등가인 이름도 준비된다. CoCreateInstance 등의 함수를 호출하면나무에, 실제의 구조체 대신에 이 이름을 사용할 수 있다. 관습적인 명명 규칙으로서 인터페이스 및 오브젝트의 설명적인 이름의 선두에는, 각각 IID_ 및 CLSID_ 를 붙일 수 있다. 예를 들어,IDirect3D8 인터페이스의 IID 는 IID_IDirect3D8 가 된다.

HRESULT 값

모든 COM 메소드는, HRESULT 로 불리는 32 비트의 정수를 돌려준다. 대부분의 메소드에서는, HRESULT 는 기본적으로 1 개의 구조체를 형성해, 다음의 2 개의 독립한 정보를 포함하고 있다.

  • 메소드가 성공했는지, 실패했는지.
  • 메소드로 지원 되고 있는 조작의 결과에 관한 상세 정보.

일부의 메소드는, Winerror.h 에 표준 세트로서 정의되고 있는 값만을 HRESULT 값으로서 돌려준다. 다만, 메소드는, 보다 전문적인 정보를 나타내는 커스텀 HRESULT 값도 돌려줄 수가 있다. 보통, 이러한 값은, 메소드의 레퍼런스 페이지에 기재되어 있다.

주 메소드의 레퍼런스 페이지의 리스트에 기재되어 있는 HRESULT 값은, 돌려주어질 가능성이 있는 값의 서브 세트 뿐인 경우가 많다. 보통, 이 리스트에는, 메소드 고유의 값과 메소드 고유의 의미를 가지는 표준의 값만이 기재되어 있다. 문서에 명시적으로 기재되지 않아도, 메소드로부터는, 다양한 표준의 HRESULT 값이 돌려주어질 가능성이 있다.

HRESULT 값은 에러 정보를 돌려주기 위해서(때문에) 사용되는 경우가 많지만, 이것들을 에러 코드라고 봐서는 안 된다. HRESULT 값에는, 값상세 정보를 포함한 비트와 정부를 나타내는 비트가 독립해 저장 되고 있기 (위해)때문에, 정부를 나타내는 코드를 몇개에서도 포함할 수가 있다. 관습에 의해, 성공 코드에는 S_ 라고 하는 프리픽스를 붙일 수 있어 실패를 나타내는 코드에는 E_ 라고 하는 프리픽스를 붙일 수 있다. 예를 들어, 가장 일반적으로 사용되는 코드에 S_OK 및 E_FAIL 가 있다. 각각, 단지 성공 또는 실패를 나타내고 있다.

COM 메소드가 정부를 나타내는 다양한 코드를 돌려준다고 하는 것은, HRESULT 값의 테스트 방법으로 주의가 필요한 것을 의미한다. 예를 들어, 문서에 기재되어 있는 반환값을 사용해, 성공의 경우는 S_OK 가 돌려주어져 실패의 경우는 E_FAIL 가 돌려주어진다고 하는 가설에 근거해 테스트를 실시했다고 한다. 그러나, 메소드로부터는, 이외의 실패 또는 성공을 나타내는 코드가 돌려주어질 가능성도 있다. 다음의 코드는, 단순한 테스트를 이용했을 경우의 위험성을 나타내고 있다. hr 는, 메소드에 의해 돌려주어진 HRESULT 값이다.

if(hr == E_FAIL)
  {
    //실패시의 처리를 실시한다.
  }
else
  {
    //성공시의 처리를 실시한다.
  }

메소드가 실패를 나타내기 위해서(때문에) 돌려주는 값이 E_FAIL 뿐인 한, 이 테스트는 올바르게 기능한다. 그러나, 메소드로부터, E_NOTIMPL 나 E_INVALIDARG 등의 에러값이 돌려주어질 가능성도 있다. 이러한 값은 성공으로서 해석되어 어플리케이션으로 에러가 발생하는 원인이 된다.

메소드의 호출의 결과에 관한 상세한 정보가 필요한 경우는, 관계가 있는 각 HRESULT 값을 테스트할 필요가 있다. 그러나, 필요한 정보가, 성공인가 실패인가만의 경우도 있다. HRESULT 값이 성공을 나타내고 있는지 실패를 나타내고 있는지를 테스트하는 강력한 방법으로서 Winerror.h 에 정의되고 있는 다음의 매크로의 어느 쪽인가에 HRESULT 값을 건네줄 수가 있다.

  • SUCCEEDED 매크로는, 성공을 나타내는 코드에 대해서는 TRUE 를 돌려주어, 실패를 나타내는 코드에 대해서는 FALSE 를 돌려준다.
  • FAILED 매크로는, 실패를 나타내는 코드에 대해서는 TRUE 를 돌려주어, 성공을 나타내는 코드에 대해서는 FALSE 를 돌려준다.

FAILED 매크로를 사용하면(자), 전술의 코드를 다음과 같이 수정할 수 있다.

if(FAILED(hr))
  {
    //실패시의 처리를 실시한다.
  }
else
  {
    //성공시의 처리를 실시한다.
  }

이 코드는, E_NOTIMPL 나 E_INVALIDARG 를 실패로서 올바르게 처리한다.

대부분의 COM 메소드는 구조화 된 HRESULT 값을 돌려주지만, 일부의 소수의 메소드에서는 HRESULT 를 사용해 단순한 1 개의 정수를 돌려준다. 이러한 메소드는, 비명시적으로 항상 성공한다. 이런 종류의 HRESULT 를 SUCCESS 매크로에 건네주면(자), 매크로로부터는 반드시 TRUE 가 돌려주어진다. 일반적으로 사용되는 예로서IUnknown::Release 메소드가 있다. 이 메소드는, 오브젝트의 reference count 를 1 두개감소 해, 현재의 참조 카운트를 돌려준다. 참조 카운트의 설명에 대해서는, 「COM 오브젝트의 수명의 관리」를 참조할것.

포인터의 주소

COM 메소드의 레퍼런스 페이지를 참조 하면, 다음과 같은 표기가 발견된다.

HRESULT CreateDevice(
  ...,
  IDirect3DDevice8** ppReturnedDeviceInterface
);

COM 에서는, C 나 C++ 에서도 사용되는 보통의 포인터 외에, 이제(벌써) 1 개(살)별의 레벨의 간접적 호출이 사용되는 일이 있다. 이 제 2 의 레벨의 간접적 호출은, 타입의 선언의 뒤에 계속되는 "**" 으로 나타나 보통, 변수명에는 "pp" 라고 하는 프리픽스가 붙는다. 전술의 예의 ppReturnedDeviceInterface 파라미터는, 일반적으로,IDirect3DDevice8 인터페이스에의 「포인터의 주소」라고 불린다.

C++ 와 달리, COM 오브젝트의 메소드에 직접 액세스 할 것은 없다. 그 대신해, 메소드를 공개하고 있는 인터페이스에의 포인터를 취득할 필요가 있다. 메소드를 호출하면나무는, C++ 의 메소드에의 포인터를 호출하면 귀로 동일한 구문을 사용한다. 예를 들어,IMyInterface::DoSomething 메소드를 호출하려면 , 다음과 같은 구문의 사용한다.

IMyInterface *pMyIface;
...
pMyIface->DoSomething(...);

간접적 호출에 제 2 의 레벨이 필요한 것은, 인터페이스 포인터를 직접 생성 하지 않기 때문이다. 전술의 CreateDevice 메소드와 같은, 다양한 메소드의 1 개를 호출하지 않으면 안 된다. 이러한 메소드를 사용해 인터페이스 포인터를 취득하려면 , 목적의 인터페이스에의 포인터를 변수로서 선언해, 그 변수의 주소를 메소드에 건네준다. 즉, 포인터의 주소를 메소드에 건네준다. 메소드가 돌아왔을 때, 변수는 요구된 인터페이스를 가리키고 있다. 이 포인터를 사용 하면, 그 인터페이스의 임의의 메소드를 호출할 수가 있다. 인터페이스 포인터의 사용법의 상세한 것에 대하여는, 「COM 인터페이스의 사용법」을 참조할것.


COM 오브젝트의 생성

COM 오브젝트를 생성 하는 방법은 몇개인가 있다. Microsoft® DirectX® 프로그래밍에서는, 다음의 2 개의 방법이 가장 일반적으로 사용되고 있다.

  • 직접, 오브젝트의 CLSID 를 CoCreateInstance 함수에 건네준다. 이 함수는, 건네받은 오브젝트의 인스턴스를 생성 해, 지정된 인터페이스에의 포인터를 돌려준다.
  • 간접적으로, 오브젝트를 생성 하는 DirectX 메소드 또는 함수를 호출한다. 불려 간 메소드가 오브젝트를 생성 해, 그 오브젝트의 인터페이스를 돌려준다. 이 방법으로 오브젝트를 생성 하는 경우, 보통은, 돌려주어지는 인터페이스를 지정할 수 없다.

오브젝트를 생성 할 때는,CoInitialize 함수를 호출해 미리 COM 를 초기화해 둘 필요가 있다. 간접적으로 오브젝트를 생성 하는 경우는, 오브젝트 생성 메소드에 의해 이 처리를 한다. CoCreateInstance 를 사용해 오브젝트를 생성 할 필요가 있는 경우는, 명시적으로 CoInitialize 를 호출하지 않으면 안 된다. 오브젝트의 생성을 종료하면(자),CoUninitialize 를 호출해 COM 를 미초기화할 필요가 있다. CoInitialize 를 호출하면(자), 반드시 대응하는 CoUninitialize 를 호출하지 않으면 안 된다. COM 를 명시적으로 초기화할 필요가 있는 어플리케이션에서는, 스타트 업 루틴으로 COM 를 초기화해, 클린업 루틴으로 미초기화하는 것이 일반적이다.

CoCreateInstance 로 COM 오브젝트의 새로운 인스턴스를 생성 하려면 , 오브젝트의 CLSID 가 필요하다. 공개되고 있는 CLSID 는, 레퍼런스 문서 또는 해당하는 헤더 파일에 기술되고 있다. CLSID 가 공개되어 있지 않은 경우는, 그 오브젝트를 직접 생성 할 수 없다.

CoCreateInstance 함수에는 5 개의 파라미터가 있다. DirectX 로 사용하는 COM 오브젝트를 생성 하는 경우는, 보통, 다음의 파라미터를 설정한다.

  • rclsid. 이 파라미터에는, 생성 하는 오브젝트의 CLSID 를 설정한다.
  • pUnkOuter. 이 파라미터는 NULL 로 설정한다. 이 파라미터는, 오브젝트를 결합할 경우에만 사용된다. 결합의 상세한 것에 대하여는, 「참고 자료」를 참조할것.
  • dwClsContext. 이 파라미터는, CLSCTX_INPROC_SERVER 로 설정한다. 이 설정은, 오브젝트가 DLL 로서 이행 되어 어플리케이션의 처리의 일부로서 실행되는 것을 나타낸다.
  • riid. 이 파라미터에는, 요구하는 인터페이스의 IID 를 설정한다. 이 함수는, 오브젝트를 생성 해, 요구된 인터페이스에의 포인터를 ppv 파라미터에 돌려준다.
  • ppv. 이 파라미터에는, 함수가 돌아왔을 때에 riid 에 의해 지정된 인터페이스로 설정되는 포인터의 주소를 설정한다. 이 변수가 요구된 인터페이스에의 포인터로서 선언해, 파라미터 리스트내의 포인터에의 참조를 (LPVOID *)로서 캐스트 한다.

예를 들어, 다음의 코드는,DirectPlay8 오브젝트의 새로운 인스턴스를 생성 해,IDirectPlay8Peer 인터페이스에의 포인터를 변수 g_pDP 에 돌려주고 있다. 에러가 발생 하면, 메시지 박스가 표시되어, 어플리케이션이 종료한다.

IDirectPlay8Peer*  g_pDP = NULL;
...
CoInitialize( NULL );
...
hr = CoCreateInstance( CLSID_DirectPlay8, NULL, CLSCTX_INPROC_SERVER,
                         IID_IDirectPlay8Peer, (LPVOID*) &g_pDP );

if( FAILED( hr ) )
  {
    MessageBox( NULL, TEXT("Failed Creating IDirectPlay8Peer.  "),
                  TEXT("DirectPlay Sample"), MB_OK | MB_ICONERROR );
    return FALSE;
  }

보통은, 오브젝트를 간접적으로 생성 하는 (분)편이 매우 간단하다. 오브젝트 생성 메소드에 인터페이스 포인터의 주소를 건네주는 것만으로 좋다. 후는, 메소드에 의해 오브젝트가 생성 되어, 인터페이스 포인터가 돌려주어진다. 보통, 간접적인 방법으로 오브젝트를 생성 하는 경우는, 메소드에 의해 돌려주어지는 인터페이스를 선택할 수 없다. 다만, 오브젝트의 생성 방법에 대해, 다양한 사항을 지정할 수 있다. 예를 들어, 다음의 코드는, 전술의 IDirect3D8::CreateDevice 메소드를 호출해, 디스플레이 어댑터를 나타내는 디바이스 오브젝트를 생성 하고 있다. 이 메소드는, 오브젝트의 IDirect3DDevice8 인터페이스에의 포인터를 돌려준다. 최초의 4 개의 파라미터는, 오브젝트를 생성 하기 위해서 필요한 각종의 정보를 지정해, 5 번째의 파라미터는 인터페이스 포인터를 받는다. 상세한 것에 대하여는, 레퍼런스 문서를 참조할것.

IDirect3DDevice8 *g_pd3dDevice = NULL;
...
if( FAILED( g_pD3D->CreateDevice(D3DADAPTER_DEFAULT,
                                 3DDEVTYPE_HAL,
                                 hWnd,
                                 D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                                 &d3dpp,
                                 &g_pd3dDevice )))
  return E_FAIL;


COM 인터페이스의 사용법

오브젝트를 생성 하면, 생성 메소드로부터 인터페이스 포인터가 돌려주어진다. 이 포인터를 사용 하면, 그 인터페이스의 임의의 메소드에 액세스 할 수 있다. 포인터에 사용하는 구문은, C++ 의 메소드의 경우와 같다. 다음의 코드는, 전의 주제로 가리킨 예의 확장이다. 이 예에서는,DirectPlay8 오브젝트의 생성 후,CoCreateInstance 로부터 돌려주어진 IDirectPlay8Peer 인터페이스 포인터를 사용해 IDirectPlay8Peer::Initialize 메소드를 호출해, 오브젝트를 초기화하고 있다. 알기 쉽게, 에러 수정 코드는 생략 되어 있다.

IDirectPlay8Peer*  g_pDP = NULL;
...
CoInitialize( NULL );
...
hr = CoCreateInstance( CLSID_DirectPlay8, NULL, CLSCTX_INPROC_SERVER,
                         IID_IDirectPlay8Peer, (LPVOID*) &g_pDP );
hr = g_pDP->Initialize( NULL, DirectPlayMessageHandler, 0 );


추가의 인터페이스의 요구

보통은, 생성 메소드로부터 받는 인터페이스 포인터만으로 용무는 충분하다. 실제, 오브젝트가 공개하는 인터페이스가 IUnknown 이외에는 1 개(살) 뿐인 일도 적지 않다. 그러나, 많은 오브젝트는 복수의 인터페이스를 공개한다. 이 때문에, 복수의 인터페이스에의 포인터가 필요하게 되는 경우도 있다. 생성 메소드에 의해 돌려주어지는 인터페이스 외에도 인터페이스가 필요한 경우, 새로운 오브젝트를 생성 할 필요는 없다. 오브젝트의 IUnknown::QueryInterface 메소드를 사용해 다른 인터페이스 포인터를 요구할 수 있다.

CoCreateInstance 로 오브젝트를 생성 했을 경우는,IUnknown 인터페이스 포인터를 요구한 후,IUnknown::QueryInterface 를 호출하는 것에 의해, 필요한 모든 인터페이스를 요구할 수 있다. 다만, 이 방법은, 필요한 인터페이스가 1 개만의 경우는 불편하다. 또, 오브젝트 생성 메소드를 사용하지 않는 경우는, 돌려주는 인터페이스 포인터를 지정할 수 없기 때문에, 전혀 기능하지 않는다. 실제로는, 모든 COM 인터페이스는 IUnknown 인터페이스를 계승 또는 확장하고 있으므로, 보통은, 명시적인 IUnknown 포인터를 취득할 필요는 없다.

인터페이스의 확장은, C++ 의 클래스의 계승을 닮아 있다. 아이 인터페이스는, 친인터페이스의 모든 메소드와 아이 독자적인 메소드를 공개한다. 실제, 「확장」대신에 「계승」이라고 하는 표현을 사용하는 일도 많다. 다만, 계승은 오브젝트 내부에서 행해지는 것이다. 어플리케이션이 오브젝트의 인터페이스를 계승 또는 확장할 수 없다. 그러나, 아이 인터페이스를 사용하면(자), 아이와 부모의 양쪽 모두의 인터페이스의 모든 메소드를 호출할 수가 있다.

모든 인터페이스는 IUnknown 의 아이이다. 이 때문에, 오브젝트에 대해서 취득해 어느 인터페이스를 사용해도,QueryInterface 를 호출할 수가 있다. QueryInterface 를 호출하는 경우는, 요구하는 인터페이스의 IID 와 인터페이스 포인터의 주소를 지정할 필요가 있다. 메소드로부터 돌아올 때, 이 포인터에 인터페이스 포인터가 저장 된다. 예를 들어, 다음의 코드는 IDirectSound8::CreateSoundBuffer 를 호출해 프라이머리 사운드 버퍼 오브젝트를 생성 하고 있다. 이 오브젝트는, 복수의 인터페이스를 공개한다. CreateSoundBuffer 메소드는 IDirectSoundBuffer8 인터페이스를 돌려준다. 다음의 코드에서는,IDirectSoundBuffer8 인터페이스를 사용해 QueryInterface 를 호출하는 것에 의해,IDirectSound3DListener8 인터페이스를 요구하고 있다.

IDirectSoundBuffer8* pDSBPrimary = NULL;
IDirectSound3DListener8* pDSListener;
...
if(FAILED(hr = g_pDS->CreateSoundBuffer( &dsbd, &pDSBPrimary, NULL )))
  return hr;

if(FAILED(hr = pDSBPrimary->QueryInterface(IID_IDirectSound3DListener8,
                                           (LPVOID *) &pDSListener)))
  return hr;


COM 오브젝트의 수명의 관리

오브젝트가 생성 되면(자), 시스템에 의해 필요한 메모리 리소스를 할당할 수 있다. 필요가 없어진 오브젝트는 파기해야 한다. 오브젝트를 파기하면, 시스템은, 그 만큼의 메모리를 다른 목적으로 이용할 수 있다. C++ 오브젝트에서는,new 및 delete 의 각 연산자를 사용해 오브젝트의 수명을 직접 제어할 수 있다. COM 에서는, 오브젝트를 직접 생성 하거나 파기할 수 없다. 이것은, 같은 오브젝트를 복수의 어플리케이션이 사용하고 있을 가능성이 있기 때문이다. 복수의 어플리케이션으로 사용되고 있는 오브젝트를 1 개의 어플리케이션이 파기 하면, 다른 어플리케이션에서는 높은 확률로 에러가 발생한다. COM 에서는, 「참조 카운트」라고 하는 시스템을 사용해 오브젝트의 수명을 제어하고 있다.

오브젝트의 참조 카운트는, 그 오브젝트의 몇개의 인터페이스가 요구된 회수를 나타낸다. 인터페이스가 요구될 때마다, 참조 카운트는 인크리먼트(increment) 된다. 어플리케이션이 필요의 없어진 인터페이스를 해방 하면, 참조 카운트는 감소 된다. 오브젝트는, 참조 카운트가 0 이 되지 않는 이상 메모리상에 보관 유지된다. 참조 카운트가 0 이 되면(자), 그 오브젝트 자체에 의해 자동적으로 파기된다. 오브젝트의 참조 카운트에 대해 알 필요는 없다. 오브젝트의 인터페이스의 취득 및 해방을 올바르게 가고 있는 한, 오브젝트의 수명은 적절히 제어된다.

주 COM 프로그래밍에서는 참조 카운트를 올바르게 처리하는 것이 매우 중요하다. 이 처리를 올바르게 실시하지 않으면 메모리 누수가 낳기 쉬워진다. COM 프로그래머가 가장 무릅쓰기 쉬운 미스의 1 개가, 인터페이스의 해방하는 것을 잊고이다. 인터페이스가 해방되지 않으면 참조 카운트가 언제까지나 0 이 되지 않고, 오브젝트는 반영구적으로 메모리에 남아 있게 된다.

참조 카운트의 인크리먼트(increment)와 감소

새로운 인터페이스 포인터를 취득 하면나무는, 반드시 IUnknown::AddRef 를 호출해 참조 카운트를 인크리먼트(increment) 할 필요가 있다. 다만, 보통, 어플리케이션으로 이 메소드를 호출할 필요는 없다. 오브젝트 생성 메소드 또는 IUnknown::QueryInterface 를 호출해 인터페이스 포인터를 취득했을 경우는, 오브젝트에 의해 자동적으로 참조 카운트가 인크리먼트(increment) 된다. 그러나, 기존의 포인터를 카피하는 등, 그 외의 방법으로 인터페이스 포인터를 취득했을 경우는,IUnknown::AddRef 를 명시적으로 호출할 필요가 있다. 이것을 실시하지 않으면 원의 인터페이스 포인터를 해방했을 때에, 그 포인터의 카피를 계속해 사용할 필요가 있어도, 오브젝트가 파기되는 경우가 있다.

참조 카운트를 인크리먼트(increment) 했던 것이 어플리케이션일까 오브젝트일까에 관계없이, 모든 인터페이스 포인터는 어플리케이션에 의해 해방해야 한다. 인터페이스 포인터가 불필요하게 되었을 경우는,IUnknown::Release 를 호출해 참조 카운트를 감소 한다. 모든 인터페이스 포인터에 대해, 초기화시에 NULL 로 설정해, 해방시에 다시 NULL 로 설정하는 것이 일반적이다. 이것에 의해, 클린 업 코드로, 모든 인터페이스 코드를 테스트할 수 있다. NULL 가 아닌 포인터는 아직 액티브하고, 어플리케이션을 종료하기 전에 해방할 필요가 있다.

다음의 코드는, 「추가의 인터페이스의 요구」로 설명한 샘플을, 참조 카운트의 처리 방법을 나타내기 위해서(때문에) 확장한 것이다.

IDirectSoundBuffer8* pDSBPrimary = NULL;
IDirectSound3DListener8* pDSListener = NULL;
IDirectSound3DListener8* pDSListener2 = NULL;
...
//오브젝트를 생성 해, 추가의 인터페이스를 취득한다.
//오브젝트에 의해 참조 카운트가 인크리먼트(increment) 된다.
if(FAILED(hr = g_pDS->CreateSoundBuffer( &dsbd, &pDSBPrimary, NULL )))
  return hr;

if(FAILED(hr=pDSBPrimary->QueryInterface(IID_IDirectSound3DListener8,
                                           (LPVOID *) &pDSListener)))
  return hr;

//IDirectSound3DListener8 인터페이스 포인터의 카피를 생성 한다.
//AddRef 를 호출해 참조 카운트를 인크리먼트(increment) 한다. 이것에 의해,
//사용중의 오브젝트가 파기되는 것을 막을 수가 있다.
pDSListener2 = pDSListener;
pDSListener2->AddRef();
...
//클린 업 코드. 포인터가 아직 액티브한지 어떤지를 확인한다.
//액티브하면, Release 를 호출해 인터페이스를 해방한다.
if(pDSBPrimary ! = NULL)
{
  pDSBPrimary->Release();
  pDSBPrimary = NULL;
}
if(pDSListener ! = NULL)
{
  pDSListener->Release();
  pDSListener = NULL;
}
if(pDSListener2 ! = NULL)
{
  pDSListener2->Release();
  pDSListener2 = NULL;
}


C 에 의한 COM 오브젝트에의 액세스

COM 프로그래밍으로 가장 일반적으로 사용되고 있는 언어는 C++ 이지만, C 에서도 COM 오브젝트에 액세스 할 수 있다. C 를 사용한 방법은, 조작은 직접적이지만, 복잡한 구문이 필요하게 된다.

  • 모든 메소드로, 파라미터 리스트의 최초로 파라미터가 1 개 추가되고 있다. 이 파라미터에는, 인터페이스 포인터를 설정할 필요가 있다.
  • 오브젝트의 vtable 를 명시적으로 참조할 필요가 있다.

모든 COM 오브젝트에는 각각 vtable 가 있어, 이 안에는, 그 오브젝트가 공개하고 있는 메소드에의 포인터의 리스트가 포함되어 있다. 인터페이스 포인터는 vtable 내의 장소를 나타내고 있다. 거기에는, 불려 간 메소드에의 포인터가 저장 되고 있다. 이 문서외의 장소에서는, vtable 에 대해서는 설명되어 있지 않다. 이것은, C++ 에서는, vtable 는 기본적으로 비가시이니까이다. 다만, C 로 COM 메소드를 호출하는 경우는, 간접적 호출의 레벨을 1 개 추가해, vtable 를 명시적으로 참조할 필요가 있다.

다음의 코드는, C++ 에서의 호출해 규칙을 사용해 IDirectPlay8Peer::Initialize 메소드를 호출하는 방법을 나타내고 있다.

g_pDP->Initialize( NULL, DirectPlayMessageHandler, 0 );

C 로 같은 메소드를 호출하려면 , 다음의 구문을 사용한다. vtable 포인터의 이름은 lpVtbl 와 표기된다.

g_pDP->lpVtbl->Initialize(g_pDP, NULL, DirectPlayMessageHandler, 0);

컴퍼넌트에 따라서는, 헤더 파일에, 호출용의 올바른 표기로 변환하는 매크로가 정의되고 있는 경우도 있다. 상세한 것에 대하여는, 「매크로에 의한 DirectX COM 메소드의 호출」을 참조할것.


매크로에 의한 DirectX COM 메소드의 호출

Microsoft® DirectX® 인터페이스가 많게는, 어플리케이션으로 보다 간단하게 메소드를 사용할 수 있도록(듯이), 각 메소드용으로 정의된 매크로가 준비되어 있다. 이러한 매크로는, 인터페이스의 선언과 같은 헤더 파일로 정의되고 있다. 매크로는, C 와 C++ 의 양쪽 모두의 어플리케이션으로 사용할 수 있도록(듯이) 설계되고 있다. C++ 매크로를 사용하려면 , _cplusplus 를 정의할 필요가 있다. 이것을 정의하지 않는 경우는, C 매크로가 사용된다. 매크로의 구문은 어느 쪽의 언어에서도 같지만, 헤더 파일에 포함되는 일련의 매크로 정의는 달라, 각각의 적절한 호출 표기가 사용된다.

예를 들어, d3d.h 헤더 파일내의 다음의 코드에서는,IDirect3D8::GetAdapterIdentifier 메소드에 대한 C 와 C++ 양쪽 모두의 매크로가 정의되고 있다.

#if ! defined(__cplusplus) || defined(CINTERFACE)

...
#define IDirect3D8_GetAdapterIdentifier(p, a, b, c) (p) ->lpVtbl->GetAdapterIdentifier(p, a, b, c)
...
#else
...
#define IDirect3D8_GetAdapterIdentifier(p, a, b, c) (p) ->GetAdapterIdentifier(a, b, c)
...

#endif

이러한 매크로의 어느쪽이든을 사용하려면 , 우선, 관련지을 수 있고 있는 인터페이스에의 포인터를 취득할 필요가 있다. 매크로의 최초의 파라미터에, 이 포인터를 설정한다. 그 외의 파라미터는, 메소드의 파라미터에 대응하고 있다. 매크로의 반환값은, 메소드에 의해 돌려주어지는 HRESULT 값이다. 다음의 코드는, 매크로를 사용해 IDirect3D8::GetAdapterIdentifier  메소드를 호출하고 있다. pD3D 는,IDirect3D8  인터페이스에의 포인터이다.

hr = IDirect3D8_GetAdapterIdentifier(pD3D,
                                     Adapter,
                                     dwFlags,
                                     pIdentifier);


DirectX COM 문서의 표기 규칙

편의상, DirectX COM 문서에서는, COM 메소드 및 인터페이스에 동등의 C++ 클래스의 이름이 사용된다. 따라서,IDirectPlay8Peer 인터페이스의 Initialize 메소드는,IDirectPlay8Peer::Initialize 와 같이 표기된다. 이러한 표기 규칙을 사용하는 주된 이유는, 같은 이름으로 기능이나 구문은 완전히 다른 메소드가, 복수가 다른 인터페이스에 의해 공개되는 경우가 있기 때문이다. 예를 들어, 많은 인터페이스에 Init 메소드 또는 Initialize 메소드가 포함되지만, 그 기능이나 파라미터는 완전히 다르다. C++ 의 클래스명을 사용하는 것은, 메소드를 일의에 식별하는 편리한 방법이다.

보통, 텍스트나 샘플 코드에서는, COM 메소드를 호출하면나무에 C++ 의 표기 규칙을 사용한다. C++ 의 메소드 호출을 등가인 C 의 호출로 변환하는 방법에 대해서는, 「C 에 의한 COM 오브젝트에의 액세스」를 참조할것.


IUnknown 인터페이스

COM 오브젝트는 모두,IUnknown 라고 하는 인터페이스를 지원 한다. 이 인터페이스는, 오브젝트의 수명을 제어하는 기능 및 오브젝트에 이행 되는 것 외의 인터페이스를 취득하는 기능을 Microsoft® DirectX® 에 제공한다. IUnknown 는, 다음의 3 개의 메소드를 가진다.

  • AddRef . 인터페이스 또는 다른 어플리케이션이 오브젝트에 바인드 해 왔을 때에, 오브젝트의 참조 카운트를 1 두개인크리먼트(increment) 한다.
  • QueryInterface . 특정의 인터페이스에의 포인터를 요구하는 것으로써, 오브젝트가 지원 하고 있는 기능에 대해 문의한다.
  • Release . 오브젝트의 참조 카운트를 1 두개감소 한다. 참조 카운트가 0 이 되면(자), 그 오브젝트는 해방된다.

AddRef 메소드와 Release 메소드는, 오브젝트의 참조 카운트를 관리한다. 예를 들어, Microsoft Direct3D® 오브젝트를 생성 했다고 한다. 생성 직후, 이 오브젝트의 참조 카운트는 1 으로 설정된다. 이 오브젝트의 인터페이스에의 포인터를 돌려주는 함수를 생성 하는 경우는, 돌려주는 포인터를 사용해 AddRef 를 호출해, 포인터를 돌려줄 때마다 참조 카운트를 인크리먼트(increment) 해 두도록(듯이) 해야 한다. 또,AddRef 를 호출했을 경우는, 반드시 대응하는 Release 를 호출하지 않으면 안 된다. 포인터를 파기하려면 , 그 전에 그 포인터를 사용해 Release 를 호출하지 않으면 안 된다. 오브젝트의 참조 카운트가 0 이 되면(자), 오브젝트는 파기되어 그 오브젝트에의 인터페이스는 모두 무효가 된다.

QueryInterface 메소드는, 오브젝트가 지정된 인터페이스를 지원 하고 있을지 어떨지를 조사한다. 목적의 인터페이스가 지원 되고 있었을 경우는, 그 인터페이스에의 포인터가 돌려주어진다. 이 포인터를 취득할 수 있으면(자), 그 인터페이스가 가지는 각종 메소드를 사용해 오브젝트와 교환할 수 있게 된다. 정상적으로 인터페이스에의 포인터가 돌려주어졌을 경우,QueryInterface 는 그 내부에서 AddRef 를 호출해 참조 카운트를 인크리먼트(increment) 하고 있다. 이 때문에,QueryInterface 에 의해 취득한 포인터를 파기 하면나무는, 그 전에 어플리케이션으로부터 Release 를 호출해 참조 카운트를 감소 해 두지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows NT 3.1 이후가 필요.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Unknwn.h 로 선언.


IUnknown::AddRef

오브젝트의 참조 카운트를 1 만 증가시킨다.

ULONG AddRef();

파라미터

파라미터 없음.

반환값

새로운 참조 카운트값을 돌려준다. 이 값은, 진단 및 테스트만을 목적으로 한 값이다.

주의

오브젝트를 생성 하면, 생성 한 오브젝트의 참조 카운트는 1 으로 설정된다. 그 후, 어플리케이션이 그 오브젝트의 인터페이스를 취득하는지, 또는 AddRef 메소드를 호출할 때마다, 오브젝트의 참조 카운트는 1 두개증가한다. Release 메소드를 호출하면, 오브젝트의 참조 카운트는 1 만 감소한다.

동작환경

Windows NT/2000 : Windows NT 3.1 이후가 필요.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Unknwn.h 로 선언.


IUnknown::QueryInterface

오브젝트가 특정의 COM 인터페이스를 지원 하고 있을지 어떨지를 판별한다. 인터페이스가 지원 되고 있었을 경우는, 오브젝트의 참조 카운트가 1 만 증가한다. 어플리케이션은, 이 메소드의 호출해 직후부터 그 인터페이스를 사용할 수 있게 된다.

HRESULT QueryInterface(
  REFIID riid,
  LPVOID* ppvObj
);

파라미터

riid
요구하는 인터페이스의 참조 식별자.
ppvObj
목적의 인터페이스가 지원 되고 있었을 경우에, 인터페이스에의 포인터가 저장 되는 포인터 변수의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는, E_NOINTERFACE 또는 E_POINTER 를 돌려준다. 또, 컴퍼넌트안에는, 이러한 에러값에 대한 개별의 정의를 헤더 파일에 저장 하고 있는 것도 있다. 예를 들어, Microsoft® DirectInput® 에서는 DIERR_NOINTERFACE 와 E_NOINTERFACE 는 같은 값이다.

주의

이 메소드의 호출에 의해 취득한 인터페이스를 실제로 사용할 필요가 없는 경우는, 취득한 인터페이스의 Release 메소드를 호출해 인터페이스를 해방해야 한다. QueryInterface 메소드에 의해, Microsoft 및 써드파티 각사는, 기존의 기능이나 장래 추가되는 기능과 충돌하는 일 없이 오브젝트를 확장할 수 있게 된다.

동작환경

Windows NT/2000 : Windows NT 3.1 이후가 필요.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Unknwn.h 로 선언.


IUnknown::Release

오브젝트의 참조 카운트를 1 만 감소시킨다.

ULONG Release();

파라미터

파라미터 없음.

반환값

새로운 참조 카운트값을 돌려준다. 이 값은, 진단 및 테스트만을 목적으로 한 값이다.

주의

오브젝트는, 참조 카운트가 0 이 되면(자) 해방된다. AddRef 메소드를 호출하면, 오브젝트의 참조 카운트는 1 만 증가한다.

IUnknown::AddRef 또는 IUnknown::QueryInterface 를 호출했는지, 또는 Direct3DCreate8 등의 오브젝트 생성 함수를 호출해 명시적으로 생성 한 인터페이스가 있는 경우는, 반드시 이 메소드를 호출해 인터페이스를 해방해야 한다. 인터페이스만을 해방하는데 필요한 처리는, 이 메소드의 호출이다.

동작환경

Windows NT/2000 : Windows NT 3.1 이후가 필요.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Unknwn.h 로 선언.


콜백 함수의 사용법

콜백 함수는 기본적으로 이벤트 핸들러의 1 개로, 어플리케이션에 의해 이행 되어, 시스템에 의해 불려 간다. 보통, Microsoft® Windows® 어플리케이션에는 복수의 콜백 함수가 이행 되고 있어 각각 다른 그룹의 이벤트의 처리에 사용된다. 이벤트가 발생 하면, 시스템은 적절한 콜백 함수를 호출해 어플리케이션에 통지한다. 또, 보통, 콜백 함수는 파라미터 리스트를 보관 유지하고 있어, 시스템은 이 리스트를 사용해 이벤트에 관한 상세 정보를 어플리케이션에 건네준다. 콜백 함수의 가장 일반적인 예는 윈도우 프로시저이다. 이 함수는, 시스템이 윈도우를 소유하는 어플리케이션에 Windows 메세지를 건네줄 때 사용된다.

Microsoft DirectX® 에서는, 콜백 함수를 다양한 목적으로 사용하고 있다. 예를 들어, 시스템은 복수의 디바이스를 지원 하고 있다. Microsoft DirectInput® 는 각 디바이스를 디바이스 오브젝트로 나타낸다. 디바이스 오브젝트에는, 그 디바이스의 기능에 관한 상세 정보가 포함되어 있다. 보통, 어플리케이션이 유저의 입력을 올바르게 처리하려면 , 이용 가능한 디바이스를 열거해, 디바이스 오브젝트를 조사할 필요가 있다. 이 열거를 실행하려면 ,DIEnumDeviceObjectsCallback 콜백 함수를 이행 해야 한다.

열거를 실행하기 위한 최초의 처리는,IDirectInputDevice8::EnumObjects 의 호출이다. 다음에,DIEnumDeviceObjectsCallback 콜백 함수에의 포인터를 메소드에 건네준다. 시스템은, 각 디바이스에 대해서 1 회씩 이 함수를 호출해, 디바이스의 기능에 관한 정보를 포함한 DIDEVICEOBJECTINSTANCE 구조체를 건네준다. 콜백 함수는, 이 정보를 처리한 후, 다음의 디바이스 오브젝트를 요구하는 경우는 DIENUM_CONTINUE 를 돌려주어, 열거를 정지하는 경우는 DIENUM_STOP 를 돌려준다.

상세한 것에 대하여는, 「콜백 함수의 이행」을 참조할것.

DirectX 에서는, 그 밖에도 다양한 콜백 함수가 다양한 목적을 위해서(때문에) 사용된다. 상세한 것에 대하여는, 각 DirectX 컴퍼넌트의 문서를 참조할것.


콜백 함수의 이행

콜백 함수에는 다양한 목적 및 용도가 있다. 이 때문에, 보통의 함수와 같이, 콜백 함수에 대해서도, 각 함수의 주제로 설명한다. 다만, 콜백 함수의 레퍼런스는, 보통의 API 의 레퍼런스와 달리, 그 함수를 이행 하는 방법을 나타내는 템플릿이 되어 있다. 콜백 함수의 레퍼런스는, 다음의 정보를 제공한다.

  • 함수의 사용법
  • 함수의 구문
  • 각 파라미터에 저장 되는 정보의 설명
  • 돌려주어질 가능성이 있는 반환값의 설명

콜백 함수는,CALLBACK 형 또는 WINAPI 형으로서 선언한다. 어느 쪽의 타입을 사용해도 괜찮다. 함수명은 자유롭게 붙일 수 있다. 문서로 사용되고 있는 이름은, 콜백 함수의 단순한 편의 위에의 라벨이다.

레퍼런스의 설명에 따라 함수를 이행 한다. 이행 방법의 자세한 것은, 각 함수나 어플리케이션의 요건에 따라서 다르다. 다양한 콜백 함수의 이행 방법의 예에 대해서는, 샘플 코드를 참조할것.

함수에의 포인터를 적절한 Microsoft® DirectX® 컴퍼넌트에 건네준다. DirectX 컴퍼넌트는, 이 함수 포인터를 사용해 함수를 호출한다. 이 포인터의 건네주는 방법은, 함수에 따라서 다르므로, 상세한 것에 대하여는 각 함수의 레퍼런스를 참조할것.

다음의 코드는, Microsoft DirectInput® Joystick 샘플의 일부이다. 이 코드에는, 죠이스틱의 축을 열거하기 위해서 사용되는 DIEnumDeviceObjectsCallback 의 이행의 기본적인 요소가 포함되어 있다.

//함수의 선언.
BOOL CALLBACK EnumAxesCallback( const DIDEVICEOBJECTINSTANCE* pdidoi,
                                VOID* pContext );
...
//IDirectInputDevice8::EnumObjects 메소드를 호출해
//DirectInput 에의 함수 포인터를 건네준다.
if ( FAILED( hr = g_pJoystick->EnumObjects( EnumAxesCallback,
                                           (VOID*) hDlg,
                                            DIDFT_AXIS )));
...
//함수의 이행.
BOOL CALLBACK EnumAxesCallback( const DIDEVICEOBJECTINSTANCE* pdidoi,
                                VOID* pContext )
{
//2 개의 파라미터로 건네받은 정보를 처리한다.
//다음의 디바이스 오브젝트를 요구하는 경우는 DIENUM_CONTINUE 를 돌려준다.
//열거를 정지하는 경우는 DIENUM_STOP 를 돌려준다.
}


버젼 체크

어플리케이션에서는, 시스템으로 현재 이용 가능한 Microsoft® DirectX® 의 버젼 정보가 필요하게 되는 경우가 있다. 예를 들어, 시스템에 낡은 버젼의 DirectX 가 존재하는 경우, 어플리케이션은 그 버젼에 기능의 범위를 맞추는지, 최신의 버젼을 인스톨 할 필요가 생기는 일이 있다.

DirectX 의 버젼 번호를 직접 취득하는 방법은 없다. 다만, 각 버젼은, 고유의 오브젝트 및 인터페이스를 포함하고 있다. DirectX 의 모든 버젼은, 이전의 모든 버젼을 지원 하고 있다. 이 때문에, 특정의 버젼 고유의 인터페이스 및 오브젝트는, 그것들을 도입한 버젼과 모든 후속 버젼으로 지원 된다. 따라서, 필요한 버젼이 이용 가능한가 어떤가를 조사하려면 , 그 버젼 고유의 오브젝트 또는 인터페이스가 존재할지 어떨지를 테스트 하면이야 있고. 그러한 오브젝트 또는 인터페이스가 존재하는 한, 그것보다 새로운 버젼의 DirectX 를 사용하고 있어도, 어플리케이션은 정상적으로 기능한다.

예를 들어, 버젼 6.1 의 지원이 필요하다라고 한다. Microsoft DirectMusic® 오브젝트 (CLSID_DirectMusic)는, DirectX Version 6.1 으로부터 도입된 오브젝트이다. DirectMusic 오브젝트의 존재는,CoCreateInstance 를 사용해 이 오브젝트의 생성을 시도하는 것에 의해 테스트할 수 있다. 성공했을 경우는, 버젼 6.1 이후가 인스톨 되고 있으므로, DirectX 6.1 의 모든 기능을 사용할 수 있다.

여기에서는, 각 버젼 고유의 인터페이스 및 오브젝트의 상세한 리스트는 가리키지 않기 때문에, DirectX 소프트웨어 개발 킷의 샘플의 섹션을 참조할것. 샘플의 1 개의 GetDXVersion 라고 하는 함수에는, DirectX 의 모든 버젼에 관한 테스트가 포함되어 있다. GetDXVersion 는, 그 시스템에 존재하는 DirectX 의 버젼에 대응하는 정수를 돌려준다. 이 정수가 필요한 버젼의 번호와 같은가, 그것보다 크면, 어플리케이션은 정상적으로 실행된다. 샘플 코드는, SDK 의 루트 폴더의 \Samples\Multimedia\DXMisc\GetDXVer 에 있다.

상세한 것에 대하여는, 「 operating system의 버젼의 체크」를 참조할것.


operating system의 버젼의 체크

어플리케이션에서는, Microsoft® DirectX® 의 버젼 뿐만이 아니라, 그것이 실행되고 있는 operating system나 인스톨 되고 있는 서비스 팩의 정보가 필요하게 되는 경우가 있다. operating system의 버젼을 조사하려면 , Microsoft Windows® 함수의 GetVersionEx 를 사용 하면이야 있고. 이 함수는, 다음의 각종 정보를 포함한 OSVERSIONINFO 구조체를 돌려준다.

  • 그 시스템이 Microsoft Windows NT® 베이스나 Windows 95/98/ME 인가
  • 메이저 버젼 번호 및 마이너 버젼 번호
  • 서비스 팩 번호 (Windows NT 베이스의 시스템의 경우)

어플리케이션이 대응하고 있는 가장 낡은 operating system에 대해 조사하는 것이 일반적이다. 그 버젼 이후가 인스톨 되고 있으면, 인스톨 한 어플리케이션은 정상적으로 실행된다.

주 GetVersionEx 에 의해 돌려주어지는 operating system 정보는, DirectX 의 존재 또는 버젼 번호를 조사하는 테스트에는 사용할 수 없다. 특히, 시스템이 Windows NT 베이스이다고 해도, DirectX 가 존재하지 않다고는 할 수 없다. 예를 들어, Windows 2000 operating system에는 DirectX 7.0 이후가 포함되어 있다. Windows NT 베이스의 operating system의 향후의 버젼에서도, DirectX 의 버젼이 포함되는 것이라고 예측된다. DirectX 의 존재와 버젼 번호는, 전의 주제로 설명한 순서로 조사할 필요가 있다.

다음의 샘플 함수는,GetVersionEx 를 사용해 operating system의 버젼을 테스트하는 방법을 나타내고 있다. 인스톨 되고 있는 버젼이 파라미터 리스트로 지정되고 있는 버젼 이후이면, 함수는 TRUE 를 돌려준다. 이 경우, 인스톨 한 어플리케이션은 정상적으로 실행된다. 그 이외의 경우, 함수는 FALSE 를 돌려준다. 이것은, 어플리케이션을 인스톨 해도 올바르게 실행되지 않는 것을 의미한다.

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

BOOL bIsWindowsVersionOK(   DWORD dwWin9xMajor, DWORD dwWin9xMinor,
                            DWORD dwWinNTMajor, DWORD dwWinNTMinor, WORD wWinNTSPMajor )
{
    OSVERSIONINFO           osvi;

    // OSVERSIONINFO 구조체를 초기화한다.
    ZeroMemory( &osvi, sizeof( osvi ) );
    osvi.dwOSVersionInfoSize = sizeof( osvi );

    GetVersionEx( &osvi );  // 이 함수가 성공했다고 가정한다.

    // 코드의 패스를 NT 의 경우와 Win9x 의 경우로 나눈다.
    if( osvi.dwPlatformId == VER_PLATFORM_WIN32_WINDOWS )
    {
        // 메이저 버젼을 체크한다.
        if( osvi.dwMajorVersion > dwWin9xMajor )
            return TRUE;
        else if( osvi.dwMajorVersion == dwWin9xMajor )
        {
            // 마이너 버젼을 체크한다.
            if( osvi.dwMinorVersion >= dwWin9xMinor )
                return TRUE;
        }
    }
    else if( osvi.dwPlatformId == VER_PLATFORM_WIN32_NT )
    {
        // 메이저 버젼을 체크한다.
        if( osvi.dwMajorVersion > dwWinNTMajor )
            return TRUE;
        else if( osvi.dwMajorVersion == dwWinNTMajor )
        {
            // 마이너 버젼을 체크한다.
            if( osvi.dwMinorVersion > dwWinNTMinor )
                return TRUE;
            else if( osvi.dwMinorVersion == dwWinNTMinor )
            {
                // 서비스 팩을 체크한다.
                DWORD dwServicePack = 0;

                if( osvi.szCSDVersion )
                {
                    _stscanf(   osvi.szCSDVersion,
                                _T("Service Pack %d"),
                                &dwServicePack );
                }
                return ( dwServicePack >= wWinNTSPMajor );
            }
        }
    }
    return FALSE;
}


DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일

여기에서는, Microsoft® DirectX® 어플리케이션의 컴파일시에 고려해야 할 점에 대해 설명한다. DirectX 8.0 은, Microsoft Visual C++ 5.0 SP3 이후만을 지원 한다.

  • 컴파일의 준비
  • 컴퍼넌트의 버젼 정수


컴파일의 준비

이 SDK 에 포함되어 있는 각 샘플에는, 샘플용의 원시 파일, 프로젝트 리소스, 링커등의 설정 정보를 기술한 Microsoft® Visual C++® 의 프로젝트 파일 (DSP 파일)이 준비되어 있다. 그러나, 샘플을 확실히 컴파일 해, 링크하려면 , 샘플을 컴파일 하는 개발자가 약간 설정 작업을 실시하지 않으면 안 되는 경우도 있다. 또, 새로운 프로젝트를 생성 하기 위한(해), 그 프로젝트용의 설정 정보를 개발자가 스스로 준비해야 하는 경우도 있다. 여기에서는, Microsoft DirectX® 의 샘플에도, 개발자가 독자적으로 개발하는 DirectX 어플리케이션에도 해당하는 내용을 설명한다.

Visual C++ 로 프로젝트 파일을 연 후, 어플리케이션을 컴파일 하기 전에 몇개의 설정값을 체크해야 한다. 이후의 설명은, Microsoft Visual C++ 5 및 6 에 유효하다.

주 이후의 설명에서는 디폴트의 인스톨 패스 (C:\Mssdk\Include 및 C:\Mssdk\Lib)를 사용해, 파일의 장소를 기술한다. 인스톨 패스는 다른 경우도 있다.

인클루드 파일의 검색 패스

헤더 파일의 패스가 올바른 일, 및 DirectX 의 헤더 파일의 디렉토리가 컴파일러에 최초로 검색되는 패스가 되어 있는 것을 확인하는 것. 인클루드 패스를 확인하려면 ,［툴］ 메뉴의 ［옵션］ 을 클릭해,［디렉토리］ 탭을 클릭한다. 이것에 의해, 다음과 같은 다이알로그 박스가 표시된다.

여기서 리스트의 선두에 표시되고 있는 패스가, 최신의 DirectX 의 헤더 파일을 두고 있는 폴더로 되어 있지 않으면 안 된다. 이 디폴트 패스는, C:\Mssdk\Include 이다. 이 패스가 표시되어 있지 않은 경우는, 그것을 리스트에 추가해,［디렉토리］ 탭내의 툴바 컨트롤을 사용해 그 패스를 리스트의 선두에 이동하는 것.

링커의 검색 패스

링커가 링크 라이브러리를 검색할 때에 사용하는 검색 패스와 그 검색순서를 확인하는 것. 링크의 검색 패스의 리스트도,[디렉토리] 탭으로 확인할 수 있다. 이것을 실시하려면 ,[툴] 메뉴의 [옵션] 을 클릭해,[디렉토리] 탭을 클릭한다. 다이알로그 박스가 표시되면(자),［표시하는 디렉토리］ 드롭 다운 리스트 박스의 ［라이브러리 파일］ 을 클릭한다. 이것에 의해 표시된 리스트의 선두의 패스가, 최신의 DirectX 의 링크 라이브러리를 두고 있는 폴더로 되어 있지 않으면 안 된다. 이 디폴트 패스는, C:\Mssdk\Lib 이다.

프로젝트의 링크 라이브러리

샘플과 함께 제공된 프로젝트 파일을 사용하는 경우는, 이 설정을 확인할 필요는 없다. 이 설정값은 프로젝트 파일내에서 지정되고 있다. 새로운 어플리케이션을 컴파일 하는 경우는,[프로젝트] 메뉴의 [설정] 을 클릭한다. 이것에 의해, 다음과 같은 다이알로그 박스가 표시된다.

어플리케이션이 적절한 표준 DirectX 링크 라이브러리에 링크되는 일도 확인해야 한다.


컴퍼넌트의 버젼 정수

Microsoft® DirectX® 의 이전의 버젼과의 호환성을 보관 유지하기 위해(때문에), 몇개의 DirectX 컴퍼넌트는 헤더 파일에 다양한 API 요소를 정의하고 있다. 보통, 영향을 받는 요소는, 버젼 고유의 구조체의 능력이나 플래그 세트이다. 몇개의 헤더 파일 부분은, 프리프로세서가 불필요한 정의를 제외하는 프리프로세서 조건문으로 둘러싸여 있다. 정의가 끝난 정수의 값은, 컴퍼넌트의 특정의 버젼을 나타내고 있다. 값이 정의되어 있지 않은 경우는, 헤더 파일을 기술할 경우에 사용된 DirectX 의 버젼을 식별하는 값이 설정된다. Microsoft Direct3D® 의 헤더 파일 (D3D8.h)의 예를 다음에 나타낸다.

#ifndef DIRECT3D_VERSION
#define DIRECT3D_VERSION         0x0800
#endif  //DIRECT3D_VERSION

이러한 정수에 다른 값을 정의 하면, 낡은 버젼의 컴퍼넌트로 새로운 버젼의 헤더 파일을 사용할 수 있다. 예를 들어, DirectX 7.0 버젼의 D3D 의 컴파일에 최신의 헤더 파일을 사용하려면 , DIRECT3D_VERSION 에 0x0700 를 정의한다.


DirectX 어플리케이션의 디버그

여기에서는, C 및 C++ 어플리케이션의 디버그에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 디버그용과 리테일용의 DLL
  • DirectX 8.0 에러 처리 유틸리티 라이브러리


디버그용과 리테일용의 DLL

Microsoft® DirectX® SDK 인스톨 프로그램은, DirectX 동적 링크 라이브러리 (DLL)의 디버그 빌드 또는 리테일 빌드의 몇개의 인스톨 옵션을 제공한다.

C++ 로 소프트웨어를 개발하고 있는 경우는, DLL 의 디버그 버젼을 인스톨 하면이야 있고. 이 옵션을 선택 하면, 시스템에는 DLL 의 디버그 버젼과 리테일 버젼이 인스톨 된다. 리테일 옵션을 선택했을 경우는, DLL 의 리테일 버젼만이 인스톨 된다. DLL 의 디버그 버젼에는 내부 데이터 구조를 검증하는 추가 코드가 있어, 프로그램의 실행중에 (Microsoft Win32® OutputDebugString 함수를 사용해) 디버그의 에러 메세지를 출력한다. 에러가 발생 하면, 문제의 상세가 디버그 출력된다. DLL 의 디버그 버젼은 리테일 버젼보다 동작이 늦지만, 어플리케이션의 디버그에는 리테일 버젼보다 도움이 된다. 어플리케이션을 출하하는 경우는, 리테일 버젼을 출하하는 것.

DirectX 컨트롤 패널 유틸리티를 사용 하면, DirectInput®, Direct3D®, 및 DirectMusic® 의 디버그 빌드와 리테일 빌드를 바꿀 수가 있다. 이 기능을 유효하게 하려면 , SDK 를 인스톨 할 경우에 디버그 옵션을 선택한다.

디버그 메세지를 확인하려면 , 윈도우내나 리모트 컴퓨터에 디버그 출력이 표시되도록, 시스템의 구성을 설정한다. Microsoft Visual C++® 등의 개발 환경에서는, 이 설정이 가능하다. 설정 방법법에 대해서는, 개발 환경에 대한 문서를 참조할것.

디버그용의 빌드를 사용하는 경우는, 디버거가 관련하는 상징적 정보를 확실히 찾아낼 수 있도록(듯이) 하기 위해서, 이하에 나타내는 장소에 심볼 파일을 놓아두지 않으면 안 된다.

OS | 디버거 | . pdb 파일의 장소 | . dbg 파일의 장소
Windows® 95, Windows 98 | Visual C++ | 바이너리와 같은 디렉토리 | 바이너리와 같은 디렉토리
Windows® NT, Windows 2000 | Visual C++ | 바이너리와 같은 디렉토리 | %SystemRoot%\Symbols\<binary extension>\
Windows NT, Windows 2000 | NTSD/KD | %SystemRoot%\Symbols\<binary extension>\ | %SystemRoot%\Symbols\<binary extension>\

주 Microsoft Windows NT 및 Windows 2000 로 Visual C++ 개발 시스템을 사용해 디버그 하는 경우는, 개발툴의 WIN32API Splitsym 를 사용해서는 안 된다. WIN32API Splitsym 는, 프라이빗 상징적 정보를 <binary>.dbg 파일로부터 바이너리 extension의 심볼 디렉토리 (%SystemRoot%\Symbols\Dll\ 등)에 카피해, 바이너리 디렉토리로부터는 원의 파일을 삭제해 버린다. Visual C++ 를 사용하려면 , 프라이빗 상징적 정보의 파일 (<binary>.dbg)이 바이노리필드와 같은 디렉토리에 놓여져 있을 필요가 있다. 따라서, 디버그용의 빌드를 사용하는 경우는, 프라이빗 상징적 정보의 카피만을 실시해, 삭제를 실시해서는 안 된다. 이것이 문제가 되는 것은, Windows NT 및 Windows 2000 로 Visual C++ 를 사용하는 경우 뿐이다. 그 외의 디버그 정보에 대해서는, Visual C++ 의 문서 및 Windows 2000 Driver Development Kit (DDK)의 문서를 참조할것.


DirectX 8.0 에러 처리 유틸리티 라이브러리

Microsoft® DirectX® 8.0 SDK 에는, 어플리케이션의 디버그 작업을 간이화 하기 위해서, 2 개의 유틸리티 함수와 각종의 매크로가 준비되어 있다. 이러한 함수 및 매크로는 Dxerr8.lib 라이브러리에 포함되어 있다. 선언은 Dxerr8.h 로 행해진다.

  • DirectX 8.0 에러 처리 함수
  • DirectX 8.0 에러 처리 매크로


DirectX 8.0 에러 처리 함수

다음의 함수 및 매크로는, DirectX 에러 처리 유틸리티 라이브러리에 포함되어 있다.

  • DXGetErrorString8
  • DXTrace


DXGetErrorString8

Microsoft® DirectX® 의 에러 코드에 관련지을 수 있고 있는 이름을 돌려준다.

TCHAR* DXGetErrorString8(
  HRESULT hr
);

파라미터

hr
[in] DirectX 메소드에 의해 돌려주어지는 HRESULT 값. 에러 코드 전용.

반환값

성공했을 경우는, 지정된 에러 코드의 이름을 포함한 캐릭터 라인에의 포인터를 돌려준다. Unicode 가 설정되어 있는 경우,DXGetErrorString8 는 Unicode 의 캐릭터 라인을 돌려준다. 그 이외의 경우는, ANSI 캐릭터 라인을 돌려준다.

주의

이 함수는, Microsoft Direct3D®, D3DX, DirectPlay®, DirectInput®, DirectMusic®, 또는 DirectSound® 의 메소드로부터의 DirectX 에러 메세지와 등가인 텍스트를 취득한다. 예를 들어,hr 를 0x88768686 로 설정했을 경우,DXGetErrorString8 는 D3DERR_DEVICELOST 를 돌려준다.

1 개의 에러 코드가 복수의 텍스트 캐릭터 라인에 대응하고 있는 경우,DXGetErrorString8 는 범용적인 캐릭터 라인을 돌려준다. 예를 들어, 메모리 부족을 나타내는 DirectX 에러 코드는, DIERR_OUTOFMEMORY 등 다수 있지만, 이것들은 모두 같은 값에 대응 붙일 수 있다. hr 를 이러한 코드의 어느 쪽인가에 설정했을 경우,DXGetErrorString8 는 E_OUTOFMEMORY 를 돌려준다.

동작환경

Windows NT/2000 : Windows® 2000 이 필요.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
버젼 : DirectX 8.0 이 필요.
헤더 : Dxerr8.h 로 선언.
임포트 라이브러리 : Dxerr8.lib 를 사용.


DXTrace

메시지 박스를 표시해,DXGetErrorString8 에 에러 코드를 건네준다.

HRESULT DXTrace(
  char *strFile,
  DWORD dwLine,
  HRESULT hr,
  TCHAR *strMsg,
  BOOL bPopMsgBox
);

파라미터

strFile
[in] 현재의 파일의 이름에의 포인터. 이 파라미터는, __FILE__ 매크로를 사용해 간단하게 설정할 수 있다.
dwLine
[in] 행 번호. 이 파라미터는, __LINE__ 매크로를 사용해 간단하게 설정할 수 있다.
hr
[in] 에러 코드가 저장 되고 있는 HRESULT. 이 값은,DXGetErrorString8 에게 건네져, 등가인 이름에 변환된다.
strMsg
[in] 파일명, 행 번호, HRESULT 와 함께 표시되는 옵션의 메세지에의 포인터.
bPopMsgBox
[in] 메시지 박스를 표시할지 어떨지를 지정한다. bPopMsgBox 를 TRUE 로 설정해,hr 를 0 이외의 값으로 설정 하면, 메시지 박스에, 최초의 4 개의 파라미터의 값이 표시된다. bPopMsgBox 를 FALSE 로 설정 하면, 정보가 디버거에게 건네진다.

반환값

성공했을 경우는 0 을 돌려주어, 실패했을 경우는 0 이외의 값을 돌려준다.

동작환경

Windows NT/2000 : Windows® 2000 이 필요.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
버젼 : DirectX® 8.0 이 필요.
헤더 : Dxerr8.h 로 선언.
임포트 라이브러리 : Dxerr8.lib 를 사용.


DirectX 8.0 에러 처리 매크로

다음의 매크로를 사용하면(자),DXTrace 함수를 간단하게 사용할 수 있다.

  • DXTRACE_MSG
  • DXTRACE_ERR
  • DXTRACE_ERR_NOMSGBOX


DXTRACE_MSG

캐릭터 라인을 디버거에 건네준다.

HRESULT DXTRACE_MSG(
  char *str,
);

파라미터

str
디버거에게 건네지는 캐릭터 라인에의 포인터.

반환값

성공했을 경우는 0 을 돌려주어, 실패했을 경우는 0 이외의 값을 돌려준다.

주의

캐릭터 라인과 함께, 파일명 및 행 번호를 지정한다. 매크로의 선언은 다음과 같이 된다.

DXTRACE_MSG(str) DXTrace( __FILE__, (DWORD) __LINE__, 0, str, FALSE )

동작환경

Windows NT/2000 : Windows® 2000 이 필요.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
버젼 : DirectX® 8.0 이 필요.
헤더 : Dxerr8.h 로 선언.


DXTRACE_ERR

메시지 박스에 에러 정보를 표시한다.

HRESULT DXTRACE_ERR(
  char *str,
  HRESULT hr
);

파라미터

str
메시지 박스에 표시되는 캐릭터 라인에의 포인터.
hr
에러 코드를 포함한 HRESULT. 이 값은,DXGetErrorString8 에게 건네져, 등가인 이름에 변환된다.

반환값

성공했을 경우는 0 을 돌려주어, 실패했을 경우는 0 이외의 값을 돌려준다.

주의

캐릭터 라인 및 에러명과 함께, 파일명 및 행 번호를 지정한다. 매크로의 선언은 다음과 같이 된다.

DXTRACE_ERR(str, hr) DXTrace(__FILE__, (DWORD) __LINE__, hr, str, TRUE )

동작환경

Windows NT/2000 : Windows® 2000 이 필요.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
버젼 : DirectX® 8.0 이 필요.
헤더 : Dxerr8.h 로 선언.


DXTRACE_ERR_NOMSGBOX

에러 정보를 디버거에 건네준다.

HRESULT DXTRACE_ERR_NOMSGBOX(
  char *str,
  HRESULT hr
);

파라미터

str
디버거에게 건네지는 캐릭터 라인에의 포인터.
hr
에러 코드를 포함한 HRESULT. 이 값은,DXGetErrorString8 에게 건네져, 등가인 이름에 변환된다.

반환값

성공했을 경우는 0 을 돌려주어, 실패했을 경우는 0 이외의 값을 돌려준다.

주의

캐릭터 라인 및 에러명과 함께, 파일명 및 행 번호를 지정한다. 매크로의 선언은 다음과 같이 된다.

DXTRACE_ERR_NOMSGBOX(str, hr) DXTrace(__FILE__, (DWORD) __LINE__, hr, str, FALSE)

동작환경

Windows NT/2000 : Windows® 2000 이 필요.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
버젼 : DirectX® 8.0 이 필요.
헤더 : Dxerr8.h 로 선언.


참고 자료

Microsoft Windows® 프로그래밍에 관한 일반 정보, 및 Microsoft® DirectX® 를 설명할 경우에 사용한 그래픽스나 멀티미디어의 개념이나 용어에 대해서는, 이하의 자료를 참조할것.

  • Bradley Bargen 및 Peter Donnelly 저, 「Inside DirectX」, Microsoft Press® 사부터 1998 년에 출판.
  • Durand R. Begault 저, 「3-D Sound for Virtual Reality and Multimedia」, Academic Press 사부터 1994 년에 출판.
  • James Blinn 저, 「Jim Blinn's Corner:A Trip Down the Graphics Pipeline」, Morgan Kaufmann 사부터 1996 년에 출판.
  • Charles Dodge 및 Thomas A. Jerse 저, 「Computer Music:Synthesis, Composition, and Performance」, Schirmer Books 사부터 1997 년에 출판 ( 제 2 판).
  • James D. Foley 저, 「Computer Graphics:Principles and Practice」, Addison-Wesley 사부터 1991 년에 출판 ( 제 2 판).
  • Donald Hearn 및 M. Pauline Baker 저, 「Computer Graphics」, Prentice-Hall 사부터 1986 년에 출판.
  • Tim Kientzle 저, 「A Programmer's Guide to Sound」, Addison-Wesley Developers Press 사부터 1998 년에 출판.
  • Peter J. Kovach 저, 「Inside Direct3D」, Microsoft Press 사부터 2000 년에 출판.
  • Charles Petzold 저, 「Programming Windows 98」, Microsoft Press 사부터 1998 년에 출판 ( 제 5 판).
  • Nigel Thompson 저, 「3D Graphics Programming for Windows 95」, Microsoft Press 사부터 1996 년에 출판.
  • Alan H. Watt 및 Mark Watt 저, 「Advanced Animation and Rendering Techniques」, Addison-Wesley 사부터 1992 년에 출판.

COM 에 관한 개념이나 용어의 상세한 것에 대하여는, 이하의 자료를 참조할것.

  • Kraig Brockschmidt 저, 「Inside OLE 2」, Microsoft Press 사부터 1995 년에 출판 ( 제 2 판).
  • Dale E. Rogerson 저, 「Inside COM」,Microsoft Press 사부터 1997 년에 출판.


DirectX Graphics

여기에서는, Microsoft® DirectX® Graphics 어플리케이션 프로그래밍 인터페이스 (API)의 사용법에 대해 설명한다.

DirectX 외의 컴퍼넌트와 같게, DirectX Graphics 는 C, C++, 및 Microsoft Visual Basic® 로 사용할 수 있다.

DirectX Graphics 의 헬프의 구성에 대해서는, 「도로지도」를 참조할것.


도로지도

Microsoft® DirectX® Graphics 에 대해서는, 이하의 주제로 설명한다.

DirectX Graphics 의 신기능 . DirectX 8.0 의 이 컴퍼넌트의 신기능. 이전에 Microsoft Direct3D® 또는 Microsoft DirectDraw® 를 사용했던 적이 있는 경우는, DirectX 7.0 으로부터 큰폭으로 변경되고 있으므로, 최초로 이 토픽을 읽는 것을 추천 한다.

DirectX Graphics 의 개요 . DirectX Graphics 및 어플리케이션으로 실행할 수 있는 처리의 개요와 몇개의 중요한 포인트 및 필요한 배경 정보.

DirectX Graphics 에 대해 . 기본적인 구조를 자세하게 설명한다. 여기에서는, 어플리케이션으로 버텍스 라이팅이나 텍스쳐 매핑을 이행 하는 방법은 설명하지 않지만, 상세를 학습할 때에 API 의 구조의 이해에 도움이 될 것이다.

DirectX Graphics 의 사용법 . API 의 사용법의 가이드이다. 이 주제의 목차를 참고로 해, 특정의 정보가 필요하게 되었을 때에 대상이 되는 개소를 참조할 수 있다. 이 주제는, 레퍼런스 주제와 조합해 사용하는 것.

DirectX Graphics 의 고도의 주제 . 어플리케이션으로 DirectX Graphics 의 능력을 최대한으로 활용하는 어플리케이션을 생성하기 위한 정보이다.

프로그래밍의 힌트 및 툴 . DirectX Graphics 어플리케이션의 컴파일, 디버그, 및 최적화에 관한 다양한 정보를 제공한다. 또, 여기에서는, DirectX 8.0 이전의 드라이버를 사용하는 경우에 발생하는 문제에 대해서도 설명한다.

DirectX Graphics C/C++ 튜토리얼 . 기본적인 기능을 단계적으로 이행 하는 튜토리얼이다. 실천적으로 DirectX Graphics 를 이해할 수가 있다.

DirectX Graphics C/C++ 샘플 . 필요한 샘플 코드를 찾아내기 위한, SDK 의 샘플 어플리케이션에 대한 가이드.

Direct3D C/C++ 레퍼런스 . Microsoft Direct3D® 헤더 파일로 선언 떠날 수 있어 모든 API 요소에 대해 자세하게 설명한다.

Direct3DX C/C++ 레퍼런스 . Direct3DX 유틸리티 라이브러리 헤더 파일로 선언 떠날 수 있어 모든 API 요소에 대해 자세하게 설명한다.

Direct3DX 쉐이더 어셈블러 레퍼런스 . Direct3DX 버텍스 쉐이더 및 픽셀 쉐이더 어셈블러에 대한 자세한 레퍼런스이다.

이펙트 파일 형식 . 이펙트 파일의 포맷에 대해 설명한다. 일련의 파라미터 선언 및 다양한 테크닉에 관한 정보로 구성된다.

X 파일 C/C++ 레퍼런스 . Dxfile.h 로 선언 떠날 수 있어 모든 API 요소에 대해 자세하게 설명한다.

X 파일 포맷 레퍼런스 . DirectX (. x) 파일 포맷에 대해 자세하게 설명한다.


DirectX Graphics 의 신기능

Microsoft® DirectX® 8.0 에서는, 구릴리스의 DirectX 의 오브젝트와 인터페이스를 공개 및 지원 하는 것으로써, 후방 호환성을 유지하고 있다. 다만, DirectX 8.0 의 새로운 Microsoft Direct3D® API 인터페이스의 일부로서 많은 신기능 및 퍼포먼스의 확장이 추가되고 있다.

DirectDraw 와 Direct3D 의 완전한 통합
어플리케이션의 초기화가 간단하게 되어, 데이터의 할당과 관리의 퍼포먼스가 향상하고 있어, 메모리의 사용량이 줄어들고 있다. 또, 그래픽스 API 의 통합에 의해, 복수의 버텍스 입력 스트림의 패러렐화가 가능하게 되어, 렌더링의 유연성이 더하고 있다.
프로그램 가능한 버텍스 처리 언어
커스텀 쉐이더를 생성 해, 애니메이션의 morphing나 트이닝, 행렬 팔레트의 스키닝, 유저 정의의 라이팅 모델, 일반적인 환경 매핑, 수속 지오메트리, 및 개발자가 정의하는 그 외의 알고리즘등을 실현할 수 있다.
프로그램 가능한 픽셀 처리 언어
커스텀 하드웨어 쉐이더를 생성 해, 텍스쳐를 결합하는 일반적인 식, 픽셀 단위의 라이팅 (범프 맵핑), 포토 리얼한 스펙큐러 이펙트를 위한 픽셀 단위의 환경 매핑, 및 개발자가 정의하는 그 외의 알고리즘등을 실현할 수 있다.
멀티 샘플링 렌더링의 지원
풀 스크린 anti-aliasing 및 모션브라나 피사계 깊이등의 멀티 샘플링 이펙트가 가능하게 된다.
포인트 스프라이트
불꽃, 폭발, 비, 눈등의 입자 시스템의 고성능 렌더링이 가능하게 된다.
3D 볼륨 텍스쳐
픽셀 단위의 라이팅의 범위 감쇠나 볼륨 대기 이펙트가 가능하게 되어, 한층 더 복잡한 지오메트리에 적용할 수 있다.
고차원 프리미티브의 지원
3D 컨텐츠의 외관이 향상해, 주요한 3D authoring tool로부터의 컨텐츠의 매핑이 용이하게 된다.
한층 더 고도의 테크놀러지
(다양한 Direct3D 기법을 사용해) 스키닝 된 메쉬를 Direct3D 에 export하기 위한 3D 컨텐츠 생성 툴 플러그 인, 멀티 resolution의 상세 레벨 (LOD) 지오메트리, 고차원 표면 데이터 등.
인덱스 첨부 버텍스 블렌딩
지오메트리 블렌딩의 지원이 확장되어 버텍스 블렌딩에 사용하는 행렬을, 행렬 인덱스를 사용해 참조할 수 있다.
Direct3DX 유틸리티 라이브러리의 확장
Direct3DX 유틸리티 라이브러리에 다양한 신기능이 추가되었다. Direct3DX 유틸리티 라이브러리는, Direct3D 위에의 헬퍼층에서, 3D 그래픽스의 개발자가 처리해야 할 일반적인 태스크를 용이하게 한다. 스키닝라이브라리, 메쉬의 처리의 지원, 버텍스 쉐이더나 픽셀 쉐이더를 어셈블(assemble)하기 위한 함수등이 포함된다. Microsoft DirectX® 5.0 으로 최초로 도입된 D3D_OVERLOADS 에 의해 제공되고 있던 기능은, Direct3DX 유틸리티 라이브러리에 이동되었던 것에 주의 해야 한다.


DirectX Graphics 의 개요

여기에서는, Microsoft® DirectX® Graphics API 에 대해 소개해, 기술과 서비스에 관한 고도의 개요를 기술한다.

  • DirectX Graphics 의 기능
  • DirectX Graphics 의 기초지식


DirectX Graphics 의 기능

Microsoft® Direct3D® 는, Microsoft Windows® 탑재의 컴퓨터상에서 세계에 통용되는 게임이나 인터랙티브 3D 그래픽스를 사용할 수 있도록(듯이) 하는 것을 목적으로 설계되고 있다. 3D 비디오 디스플레이 하드웨어에의 디바이스에 의존한 액세스를, 디바이스에 의존하지 않는 방법으로 실시할 수가 있는 드로잉(Drawing) 인터페이스이다.

Direct3D 는, 게임이나 그 외의 고성능 멀티미디어 어플리케이션을 Windows operating system에 이식할 필요가 있는 개발자에게는 이상적인 하위 레벨 3D API 이다. Direct3D 는, 가속기 하드웨어와 하위 레벨로 교환하는 어플리케이션을 위한 방법으로, 디바이스에는 의존하지 않는다.

Direct3D 는, Windows 그래픽스 디바이스 인터페이스 (GDI)와의 호환성을 유지하면서 디스플레이 디바이스에의 직접 액세스를 제공하는 소프트웨어 디바이스이며, 게임이나 3D 그래픽스 패키지등의 Windows 서브 시스템 소프트웨어로부터, 특정의 디스플레이 디바이스의 기능에 디바이스에 의존하지 않고 액세스 하는 방법을 제공한다.

Direct3D 는, Windows 95 나 그 이후의 버젼, 및 Windows 2000 이 동작하는 컴퓨터상에, 최상급의 게임 그래픽스를 제공한다.

다음에 나타내는 것은, Direct3D 의 최신 기능이다.

  • 바꾸고 가능한 깊이 버퍼링 (Z 버퍼 또는 W 버퍼를 사용).
  • 플랫 및 gouraud shading.
  • 복수의 광원과 라이트 타입.
  • MIP Mapping 등, 머트리얼 및 텍스쳐의 완전 지원.
  • 강력한 소프트웨어 에뮬레이션 드라이버.
  • 트랜스 폼과 클리핑.
  • 하드웨어비의존성.
  • Windows 95, Windows 98, Windows ME, 및 Windows 2000 의 완전 지원.
  • Intel 의 MMX 아키텍쳐, Intel 의 Streaming Single-Instruction, Multiple-Data (SIMD) Extensions (SSE)®, 및 AMD® 의 3DNow® 아키텍쳐.
  • 하드웨어 추상 계층 (HAL)의 지원. 이 지원에 의해 제공되는, 디스플레이 하드웨어에 직접 작용하는 일관성이 있는 인터페이스에 의해, 최대의 퍼포먼스를 얻을 수 있다.
  • 풀 스크린 어플리케이션에서의 복수의백 버퍼에 의한페이지후립핑의 지원. 상세한 것에 대하여는, 「페이지후립핑과 백 버퍼링」을 참조할것.
  • 윈도우 또는 풀 스크린 어플리케이션에서의 클리핑의 지원.
  • 3D 에서의 Z 버퍼의 지원.
  • 이미지신축 하드웨어에의 액세스.
  • 표준 및 개량형 디스플레이 디바이스 메모리 영역에의 동시 액세스.
  • 그 외의 기능으로서 배타적 하드웨어 액세스, 및 해상도의 변환등이 있다.

이러한 기능을 조합하면, 표준적인 Windows GDI 베이스의 어플리케이션이나 MS-DOS 어플리케이션에 대해, 간단하게 그 성능을 향상시킬 수가 있다.

Direct3D 의 월드 관리는, 버텍스, 다각형, 및 이것들을 제어하는 커멘드에 근거해 행해진다. 이것에 의해, 트랜스 폼, 라이팅, 라스터화 3D 그래픽스 파이프라인에 직접 액세스 할 수 있다. 하드웨어 가속화를 이용해 렌더링 할 수 없는 경우, Direct3D 는 강력한 소프트웨어 에뮬레이션 기능을 제공한다.

Direct3D 에서는, 심플하고 직접적인 메소드를 사용해 3D 신을 설정 및 렌더링 할 수 있다. 렌더링 메소드의 주요 세트는 DrawPrimitive 메소드로 불린다. 이러한 메소드에 의해, 어플리케이션에서는 메소드의 호출을 1 회 실시하는 것만으로, 장면의 1 개 또는 복수의 오브젝트를 렌더링 할 수 있다. 이러한 메소드의 상세한 것에 대하여는, 「프리미티브의 렌더링」을 참조할것.

Direct3D 에서는, 3D 하드웨어에의 접속 시에 발생하는 오버헤드가 낮다. 다만, 이 접속을 실현하기 위해서(때문에)는 상당한 작업을 필요로 한다. 트랜스 폼이나 라이팅을 실행하려면 명시적인 호출을 실시하지 않으면 안되어, 필요한 행렬은 모두 제공해, 존재하는 하드웨어의 종류나 그 기능을 조사할 필요도 있다.


DirectX Graphics 의 기초지식

여기에서는, Microsoft® Direct3D® 에 의한 그래픽스 프로그래밍의 개요를 설명한다. 여기서 설명하는 개개의 개념은, 기술적이 아닌 개요로 시작되어, DirectDraw 가 그것을 어떻게 지원 할까에 임해서 다소의 구체적 설명을 더하면서 설명한다.

여기서의 개요를 읽기에 즈음해서는, 그래픽스의 전문가일 필요는 없다. 실제, 그래픽스에 대해 자세한 경우는, 여기서의 설명을 읽지 않고 , 보다 상세한 주제인 「DirectX Graphics 의 사용법」에 앞서 상관없다. 이하의 주제를 다 읽으면, 기본적인 DirectDraw 그래픽스 프로그래밍의 개념을 충분히 이해할 수가 있다.

설명하는 주제는, 다음과 같다

  • 3D 좌표계와 지오메트리
  • 쉐이딩의 기법
  • 행렬과 트랜스 폼
  • 벡터, 버텍스, 및 쿠오타니온
  • 표면의 카피
  • 페이지후립핑과 백 버퍼링
  • 직사각형


3D 좌표계와 지오메트리

Microsoft® Direct3D® 어플리케이션을 프로그래밍 하려면 , 3D 지오메트리 원리에 대해 이해하고 있을 필요가 있다. 여기에서는, 3D 신의 생성에 대해 가장 중요한 지오메트리 원리에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 3D 좌표계
  • 3D 프리미티브
  • 삼각형 라스터화 룰

이러한 주제를 참조하면, Direct3D 어플리케이션으로 이용하는 기본 개념에 대해 충분히 이해할 수 있다. 이러한 주제의 상세한 것에 대하여는, 「참고 자료」를 참조할것.


3D 좌표계

일반적으로, 3D 그래픽스 어플리케이션에서는 데카르트 좌표계의 왼손 좌표계와 오른손 좌표계의 어느 쪽인지를 사용한다. 어느 쪽의 좌표계에서도, x 축의 정방향은 우측이며, y 축의 정방향은 윗쪽이다. z 축의 정방향은, x 축의 정방향에 왼손 또는 오른손의 손가락을 향해 그것을 y 축의 정의 방향으로 회전한 방향이 된다. 엄지의 방향, 앞 또는 안쪽이, 이 좌표계에서의 z 축의 정방향이다. 다음의 그림은, 이것들 2 개의 좌표 시스템을 나타내고 있다.

Microsoft® Direct3D® 는 왼손 좌표계를 사용한다. 오른손 좌표계에 근거하는 어플리케이션을 이식하는 경우는, Direct3D 에 건네주는 데이터에 2 개의 변경을 더할 필요가 있다.

  • 삼각형의 버텍스의 순서를 반전해, 시스템이 전부터 시계회전에 더듬을 수 있도록(듯이) 한다. 즉, 버텍스가 v0, v1, v2 이라고 하면, Direct3D 에 v0, v2, v1 로서 건네준다.
  • 뷰 행렬을 사용해, 월드 공간을 z 축방향으로 -1 만일 수 있는 스케일링 한다. 그 때문에(위해)는, 뷰 행렬에 사용하는 D3DMATRIX 구조체의 _31,_32,_33, 및 _34 의 각 멤버의 부호를 반전한다

직교좌표의 결정방식에 상당하는 좌표계를 취득하려면 ,D3DXMatrixPerspectiveRH 함수 및 D3DXMatrixOrthoRH 함수를 사용해, 투영 트랜스 폼을 정의한다. 다만, 대응하는 D3DXMatrixLookAtRH 함수를 사용하는 경우는, 배면 카링의 순서를 반대로 해, 그 순서로 큐브 맵을 레이아웃 하도록(듯이) 주의 해야 한다.

왼손 좌표계와 오른손 좌표계는 가장 자주(잘) 사용되는 좌표계 시스템이지만, 3D 소프트웨어에서는, 이러한 좌표계 시스템 이외에도 다양한 좌표계가 사용되는 일이 있다. 예를 들어, 3D 모델링 어플리케이션에서는, y 축이 뷰아의 앞 또는 안쪽을 가리켜, z 축이 윗쪽을 가리키고 있는 좌표계가 사용되는 일도 드물지 않다. 이 경우, 오른손 좌표계는, 어느 축 (x, y, 또는 z)의 정방향도 뷰아에 가까워질 방향으로서 정의된다. 왼손 좌표계는, 어느 축 (x, y, 또는 z)의 정방향도 뷰아로부터 멀어질 방향으로서 정의된다. z 축이 윗쪽을 가리키고 있는 왼손 좌표계를 사용한 모델링 어플리케이션을 이식하는 경우는, 이미 설명한 순서에 가세해 버텍스 데이터를 모두 회전할 필요가 있다.

3D 좌표계로 정의된 오브젝트에 대해 중요한 조작은, 평행이동, 회전, 및 스케일링이다. 이러한 기본적인 트랜스 폼을 조합해 트랜스 폼 행렬을 생성 할 수 있다. 상세한 것에 대하여는, 「3D 트랜스 폼」을 참조할것.

이러한 조작을 조합할 때, 그 결과는 그 조작의 순서에 의존하는 것, 즉 행렬을 곱셈하는 순서가 중요한 것으로 주의한다.


3D 프리미티브

3D 원시적이다고는, 단일의 3D 원가요소를 형성하는 버텍스의 집합이다. 가장 단순한 프리미티브는, 3D 좌표계에 있는 포인트의 집합이다. 이것을포인트 리스트라고 부른다.

많은 경우, 3D 프리미티브는 다각형이다. 다각형이란, 적어도 3 개의 버텍스가 연결된 닫은 3D 도형이다. 가장 단순한 다각형은 삼각형이다. 삼각형의 3 개의 버텍스는 모두 동일 평면상에 있기 (위해)때문에, Microsoft® Direct3D® 에서는 삼각형을 사용해 대부분의 다각형을 형성한다. 같은 평면상에 없는 버텍스의 렌더링은 비효율적이다. 삼각형을 조합해 크고 복잡한 다각형이나 메쉬를 형성할 수 있다.

다음의 그림은 입방체를 나타내고 있다. 2 개의 삼각형으로 입방체의 각면이 형성되고 있다. 삼각형의 집합 전체로 1 개의 큐브 프리미티브가 형성되고 있다. 프리미티브의 표면에 텍스쳐와 머트리얼을 적용해, 프리미티브를 단일의 솔리드 폼과 같이 표시할 수 있다. 상세한 것에 대하여는, 「머트리얼」 및 「텍스쳐」를 참조할것.

또, 삼각형을 사용해, 표면이 매끄러운 커브와 같이 보이는 프리미티브를 생성 할 수 있다. 다음의 그림은, 삼각형으로 구(공)을 시뮬레이트 하는 방법을 나타내고 있다. 머트리얼을 적용 하면, 구(공)은 렌더링 했을 때에 곡면으로 보인다. 이것은, 특히 gouraud shading를 사용하는 경우에 들어맞는다. 상세한 것에 대하여는, 「gouraud shading」를 참조할것.


삼각형 라스터화 룰

버텍스로 지정된 점은 스크린 위에의 픽셀과 정확하게 일치하지 않는 것이 많다. 이 경우, Microsoft® Direct3D® 는 삼각형 라스터화 룰을 적용해, 어느 픽셀이 주어진 삼각형에 들어맞을까를 결정한다.

Direct3D 에서는, 지오메트리를 전부 칠하는데, 좌상 필링 변환을 사용한다. 이 변환은, GDI 및 OpenGL 의 직사각형에 사용하는 변환과 같다. Direct3D 에서는, 픽셀의 중심이 중요한 포인트이다. 픽셀의 중심이 삼각형의 내부에 있는 경우, 그 픽셀은 그 삼각형의 일부이다. 픽셀의 중심은 정수 좌표에 있다.

여기서 설명하는, Direct3D 의 삼각형 라스터화 룰이, 이용 가능한 모든 하드웨어에 들어맞는다고는 할 수 없다. 현재의 하드웨어를 조사해 보면, 이 룰의 이행에 대해 약간의 차이가 발견되는 일도 있다.

다음의 그림은, 좌상의 모퉁이가 (0, 0)로 우하의 모퉁이가 (5, 5)의 직사각형을 나타내고 있다. 이 직사각형은, 예상되는 대로 25 픽셀을 차지하고 있다. 직사각형의 폭은, 오른쪽에서 왼쪽을 감산한 값으로 정의된다. 높이는, 아래에서 위를 감산한 값으로 정의된다.

좌상 필링 변환에서는,위는 수평 스팬의 수직 위치 좌표를 나타내,왼쪽은 있는 스팬내의 픽셀의 수평 위치 좌표를 나타낸다. 엣지는, 수평이 아닌 한 위에의 엣지에서는 있을 수 없다. 일반적으로, 대부분의 삼각형에서는 왼쪽 엣지와 오른쪽 엣지가 있는 것만으로 있다.

좌상 필링 변환에 의해, 삼각형이 픽셀의 중심을 통과 하면나무의 Direct3D 의 처리가 정해진다. 다음의 그림은, 버텍스가 (0, 0), (5, 0), (5, 5)의 삼각형과 버텍스가 (0, 5), (0, 0), (5, 5)의 삼각형을 나타내고 있다. 이 경우, 전자의 삼각형은 15 픽셀 (흑으로 표시)을 차지하지만, 후자의 삼각형은 10 픽셀 (회색으로 표시) 밖에 차지하지 않는다. 공유하고 있는 엣지가 전자의 삼각형의 왼쪽의 엣지이니까이다.

예를 들어, 좌상의 모퉁이가 (0.5, 0.5)로 우하의 모퉁이가 (2.5, 4.5)의 직사각형을 정의하는 경우, 이 직사각형의 중심 포인트는 (1.5, 2.5)이 된다. Direct3D 래스터라이저로 이 직사각형을라스터화하면(자), 각 픽셀의 중심은 분명하게 4 개의 삼각형의 각각의 내부에 존재해, 좌상 필링 변환은 불필요하게 된다. 다음의 그림에 이것을 나타낸다. 직사각형 내부에 있는 픽셀에는, Direct3D 가 그 픽셀을 넣는 삼각형에 대응한 라벨을 붙일 수 있고 있다.

위에의 예의 직사각형을 좌상의 모퉁이가 (1.0, 1.0), 우하의 모퉁이가 (3.0, 5.0), 중심 포인트가 (2.0, 3.0)가 되도록(듯이) 이동 하면, Direct3D 는 좌상 필링 변환을 적용한다. 다음의 그림에 나타내도록(듯이), 이 직사각형 내부의 픽셀의 대부분은, 2 개(살) 이상의 삼각형의 사이의 경계를 걸친다.

어느 쪽의 직사각형에서도, 같은 픽셀이 영향을 받는다.


쉐이딩의 기법

여기에서는, 3D 다각형의 쉐이딩을 제어하기 위해서 Microsoft® Direct3D® 로 사용하는 기법에 대해 설명한다.

  • 쉐이딩 모드
  • 쉐이딩 모드의 비교
  • 쉐이딩 모드의 설정
  • 면법선 벡터와 버텍스 법선 벡터
  • 삼각형 보간 요소


쉐이딩 모드

다각형의 렌더링에 사용하는 쉐이딩 모드는, 다각형의 표시에 큰 영향을 준다. 쉐이딩 모드에 의해, 다각형의 면의 포인트의 색과 라이팅의 강도가 정해진다. Microsoft® Direct3D® 는, 다음의 2 개의 쉐이딩 모드를 지원 하고 있다.

  • flat shading
  • gouraud shading


flat shading

flat shading 모드에서는, Direct3D 렌더링 파이프라인은, 다각형의 최초의 버텍스에 있어서의 머트리얼의 색을 다각형 전체의 색으로서 사용해, 다각형을 렌더링 한다. flat shading로 렌더링 한 3D 오브젝트에서는, 동일 평면상에 없는 다각형의 사이에 날카로운 엣지가 나타난다.

다음의 그림은, flat shading로 렌더링 한 티폿트를 나타내고 있다. 각 다각형의 윤곽이 분명히 보인다. flat shading는, 계산 부하의 가장 적은 쉐이딩이다.


gouraud shading

Microsoft® Direct3D® 에서는, 다각형을 gouraud shading로 렌더링 하면 와, 버텍스의 법선 파라미터 및 라이팅 파라미터를 사용해 각 버텍스의 색을 계산한다. 다음에, 다각형의 면에 걸쳐서 색을 보간 한다. 보간은 선형으로 행해진다. 예를 들어, 버텍스 1 의 색의 빨강 성분이 0.8 으로 버텍스 2 의 빨강 성분이 0.4 의 경우, Direct3D 의 라이팅 모듈은, gouraud shading 모드 및 RGB 칼라 모델을 사용해, 2 개의 버텍스의 사이의 선의 중간점에 해당하는 픽셀에 0.6 의 빨강 성분을 할당한다.

다음의 그림은 gouraud shading를 나타내고 있다. 이 티폿트는, 다수의 평탄한 삼각형의 다각형으로 구성되어 있다. 그러나, gouraud shading를 사용 하면, 이 오브젝트의 표면은 매끄러운 곡면과 같이 된다.

gouraud shading 모드로, 날카로운 엣지를 가지는 오브젝트를 표시할 수도 있다.

상세한 것에 대하여는, 「면법선 벡터와 버텍스 법선 벡터」를 참조할것.


쉐이딩 모드의 비교

flat shading 모드의 경우, 다음의 피라미드는 인접하는 면의 사이에 날카로운 엣지가 있도록 표시된다. 다만, gouraud shading의 경우, 쉐이딩값은 엣지간에 보간 되어 최종적인 외관은 만곡 표면이 된다.

gouraud shading 모드에서는, flat shading 모드의 경우보다, 평탄한 표면에서도 보다 리얼 보인다. flat shading 모드의 경우, 표면의 색은 한결같지만, gouraud shading 모드에서는 면전체로 라이팅을 적절히 약하게 할 수가 있다. 이 효과는, 근처에 포인트 광원이 있는 경우에 특별히 확실한다.

gouraud shading는, flat shading로 나타나는 다각형간의 날카로운 엣지를 매끄럽게 한다. 다만, gouraud shading에서는,마하 밴드가 생긴다. 마하 밴드란, 인접하는 다각형으로 색이나 빛이 순조롭게 브렌드되어 있지 않은 띠를 가리킨다. 오브젝트의 다각형의 수를 늘리거나 스크린 해상도를 높이거나 어플리케이션의 색깊이를 올리는 것으로, 어플리케이션측에서 마하 밴드를 줄일 수가 있다.

gouraud shading에서는, 작은 부분에서 미스가 생기는 일이 있다. 다음의 그림에 예를 나타낸다. 여기에서는, spotlight가 1 매의 다각형의 표면에만 맞힐 수 있고 있다.

이 경우, gouraud shading가 버텍스간을 보간 하는 것으로부터 spotlight가 모두 없어져 전혀 spotlight가 존재하지 않는 것처럼 면이 렌더링 되고 있다.


쉐이딩 모드의 설정

Microsoft® Direct3D® 에서는, 한 번에 1 개의 쉐이딩 모드 밖에 선택할 수 없다. 디폴트에서는, gouraud shading가 선택되고 있다. C++ 에서는,IDirect3DDevice8::SetRenderState 메소드를 호출해 쉐이딩 모드를 변경할 수 있다. State 파라미터를 D3DRS_SHADEMODE 로 설정한다. State 파라미터에는 D3DSHADEMODE 열거의 멤버를 설정할 필요가 있다. 다음의 샘플 코드는, Direct3D 어플리케이션의 현재의 쉐이딩 모드를, flat shading 모드 또는 gouraud shading 모드로 설정하는 방법을 나타내고 있다.

// flat shading로 설정한다.
// 이 코드에서는, pDev 가 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이다고 한다.
hr = pDev->SetRenderState(D3DRS_SHADEMODE, D3DSHADE_FLAT);
if(FAILED(hr))
{
    // 에러 처리 코드.
}

// gouraud shading로 설정한다. 이것이 Direct3D 의 디폴트값이다.
hr = pDev->SetRenderState(D3DRS_SHADEMODE,
                            D3DSHADE_GOURAUD);
if(FAILED(hr))
{
    // 에러 처리 코드.
}


면법선 벡터와 버텍스 법선 벡터

메쉬의 각면에는, 수직의 법선 벡터가 있다. 법선 벡터의 방향은, 버텍스가 정의되고 있는 순서와 좌표계가 왼손 좌표계나 오른손 좌표계 등에 의해서 정해진다. 면의 법선 벡터는 면의 전면으로부터 멀어질 방향으로 향한다. Microsoft®Direct3D® 에서는, 면의 전면만 표시된다. 전면이란, 각 버텍스가 시계회전의 순서에 정의된 면이다.

전면 이외의 면은 배면이다. Direct3D 에서는, 배면이 항상 렌더링 되는 것은 아니다. 이것을 배면카링이라고 말한다. 카링모드를 변경하면 배면을 렌더링 할 수 있다. 상세한 것에 대하여는, 「카링스테이트」를 참조할것.

Direct3D 어플리케이션에서는 면법선을 지정할 필요는 없다. 필요한 때는 시스템으로 자동적으로 계산된다. 시스템에서는, flat shading 모드로 면법선을 사용한다. gouraud shading 모드에서는 버텍스 법선을 사용한다. 또, Direct3D 는 라이팅 이펙트와 텍스쳐 이펙트의 제어에도 버텍스 법선을 사용한다.

gouraud shading를 다각형에 적용 하면 와, Direct3D 에서는 버텍스 법선을 사용해 광원과 표면간의 각도를 계산한다. Direct3D 에서는, 버텍스의 색과 강도의 값을 계산해, 프리미티브의 표면 전체의 모든 포인트에 대해서 이 값을 보간 한다. Direct3D 에서는, 이 각도를 사용해 라이팅의 강도의 값을 계산한다. 각도가 큰 만큼, 표면을 비추는 빛이 약해진다.

평탄한 오브젝트를 생성 하는 경우, 다음의 그림에 나타내도록(듯이), 버텍스 법선을 표면에 대해서 수직으로 설정한다. 2 개의 삼각형으로 구성되는 평탄한 표면이 정의되고 있다.

그러나, 보통은 오브젝트가 삼각형 스트립으로 구성되어 그러한 삼각형이 동일 평면상에 없는 것이 많다. 스트립의 모든 삼각형 전체에 매끄러운 쉐이딩을 베풀려면 , 우선 버텍스에 관계 붙일 수 있고 있는 각 다각형의 표면에 대해, 면법선 벡터를 계산하는 것이 간단하다. 버텍스 법선은, 그 주위의 각 표면의 법선으로부터의 각도가 동일해지도록(듯이) 설정할 수 있다. 다만, 이 방법은 프리미티브가 복잡한 경우에는 효율적이 아닌 것이 있다.

이 방법에 대해 다음의 그림으로 설명한다. 이 그림에서는, S1 와 S2 의 2 개의 표면이 있어, 위로부터 보면(자) 엣지가 겹치고 있다. S1 와 S2 의 법선 벡터는 청색으로 가리킨다. 버텍스 법선 벡터는 적색으로 가리킨다. S1 의 면법선과 버텍스 법선 벡터가 이루는 각도는, S2 의 면법선과 버텍스 법선이 이루는 각도와 같다. 이것들 2 개의 표면에 라이트를 대어 gouraud shading으로 음영을 붙이면(자), 표면간의 엣지의 음영이 매끄럽게 되어 둥그스름을 띤다.

버텍스 법선이, 관계 붙일 수 있고 있는 표면중 1 개(살)에 기울고 있는 경우, 광원과 면의 각도에 응해 표면 위에의점에 대한 빛의 강도가 증가 또는 감소한다. 이 예를 다음의 그림으로 가리킨다. 이 그림에서도, 표면의 엣지는 겹치고 있다. 버텍스 법선은 S1 (분)편에 기울고 있으므로, S1 와 광원의 각도는, 버텍스 법선과 2 개의 면법선의 각도가 동일한 경우보다 작아진다.

gouraud shading를 사용해, 날카로운 엣지가 있는 오브젝트를 3D 신에 표시할 수 있다. 이 때문에는, 다음의 그림에 나타내도록(듯이), 날카로운 엣지가 필요한, 면의 교점의 위치 좌표 2 개의 버텍스로써 각각의 면과 같은 법선 벡터가 필요하다.

DrawPrimitive 메소드를 사용해 장면을 렌더링 하는 경우, 엣지가 날카로운 오브젝트는, 삼각형 스트립은 아니고 삼각형 리스트로서 정의한다. 오브젝트를 삼각형 스트립으로서 정의 하면, Direct3D 에서는 그 오브젝트를 복수의 삼각형의 면으로 구성된 단일의 다각형으로서 취급한다. gouraud shading는, 다각형의 면전체 및 인접하는 면과의 사이의 양쪽 모두에 적용된다. 그 결과, 오브젝트의 면의 경계가 매끄럽게 쉐이딩 된다. 삼각형 리스트는, 일련의 독립한 삼각형의 면으로부터 구성되는 다각형이므로, Direct3D 에서는 다각형의 각면에 gouraud shading이 적용된다. 다만, 면과 면의 경계에는 gouraud shading는 적용되지 않는다. 삼각형 리스트의 복수의 삼각형이 인접하고 있는 경우, 그 삼각형의 사이에는 날카로운 엣지가 표시된다.

또, 엣지가 날카로운 오브젝트를 렌더링 하면 와, flat shading로 변경하는 방법도 있다. 이것은 컴퓨터에는 가장 효율적이지만, gouraud shading를 적용한 오브젝트보다 리얼리티가 부족한 오브젝트가 장면에 표시될 가능성이 있다.


삼각형 보간 요소

시스템에서는, 면을 렌더링 하면나무 삼각형 전체로 삼각형의 버텍스의 특성을 보간 한다. 삼각형 보간 요소는 다음과 같다.

  • 색
  • 스펙큐러
  • 알파

다음 표에 나타내도록(듯이), 이러한 삼각형 보간 요소는 모두, 현재의 쉐이딩 모드에 의해 바뀐다.

쉐이딩 모드 | 설명
플랫 | 보간은 행해지지 않는다. 그 대신해, 삼각형의 최초의 버텍스의 색이 면전체에 적용된다.
굿 로 | 선형 보간이 3 개의 버텍스 모든 사이에 실행된다.

색보간 요소와 스펙큐러 보간 요소의 처리는 칼라 모델에 따라서 다르다. RGB 칼라 모델의 경우, 시스템에서는 적색, 녹색, 및 청색 성분을 사용해 보간을 실시한다. 흑백 모델, 즉 램프 모델의 경우, 시스템에서는 버텍스의 색의 청색 성분만 사용한다.

색의 알파 성분은, 다른 보간 요소로서 다루어진다. 이유는, 텍스쳐 블렌딩과 점묘의 2 개가 다른 방법으로, 디바이스 드라이버가 투명화를 실행하기 위해(때문에)이다.

D3DCAPS8 구조체의 ShadeCaps 멤버를 사용해, 현재의 드라이버가 지원 하고 있는 보간의 종류를 결정한다.


행렬과 트랜스 폼

Microsoft® Direct3D® 의 행렬을 사용해, 월드 트랜스 폼, 뷰 트랜스 폼, 및 투영 트랜스 폼을 정의한다. 3D 그래픽스의 프로그래밍 미경험자는, 여기의 내용을 학습해 프로그램을 시작하기 위해서(때문에) 중요한 개념을 이해해 둘 필요가 있다. 3D 프로그래밍의 경험자는, 여기의 내용은 생략 하거나 이하의 토픽에 대해 간단하게 대충 훑어보는 것만으로 좋다.

  • 행렬
  • 3D 트랜스 폼


행렬

Microsoft® Direct3D® 에서는, 행렬은 4 × 4 동차 행렬로 나타내져D3DMATRIX 구조체로 정의된다.

D3DMATRIX 구조체 (D3DXMATRIX )의 Direct3DX 유틸리티 라이브러리에는, 외모 ("()") 연산자가 이행 되고 있다. 이 연산자는, C++ 프로그래머에 대해서 행렬중의 값에 액세스 하는 편리한 방법을 제공한다. 이름으로 구조체 멤버를 참조할 필요는 없고, 행 및 열번호로 멤버를 참조할 수 있어 필요에 따라서 이 번호를 인덱스로서 사용할 수 있다. 이 인덱스는 0 으로부터 시작되어, 예를 들어, 3 행 2 열의 요소는 M(2, 1)가 된다.

여기서의 설명은, 유저가 Direct3D 로 작업을 실시하기 위해서(때문에) 충분한 행렬에 대한 기본적인 지식을 습득하고 있는 것을 전제로 하고 있다. 상세한 것에 대하여는, 「3D 트랜스 폼」을 참조할것.


3D 트랜스 폼

Microsoft®Direct3D® 에서는, 행렬을 사용해 3D 트랜스 폼을 실시한다. 여기에서는, 행렬이 3D 트랜스 폼을 생성 하는 방법, 트랜스 폼에 자주(잘) 사용되는 행렬, 및 행렬을 조합해 복수의 트랜스 폼을 실시하는 단일의 행렬을 생성하는 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 3D 트랜스 폼에 대해
  • 평행이동
  • 회전
  • 스케일링
  • 행렬 연결

Direct3D 에서의 트랜스 폼의 상세한 것에 대하여는, 「Direct3D 렌더링 파이프라인」을 참조할것.


3D 트랜스 폼에 대해

3D 그래픽스를 처리하는 어플리케이션에서는, 지오메트리 트랜스 폼을 사용해 다음 일이 생긴다.

  • 오브젝트의 위치 좌표를 다른 오브젝트와의 상대 위치 좌표로 나타낸다.
  • 오브젝트를 회전, 및 사이즈를 변경한다.
  • 위치 좌표 시점, 뷰 방향, 및 퍼스펙티브를 변경한다.

4 × 4 행렬을 사용 하면, 임의의 포인트를 다른 포인트에 트랜스 폼 할 수 있다. 다음의 예에서는, 행렬을 사용해 포인트 (x, y, z)를 재차 트랜스 폼 해, 새로운 포인트 (x', y', z')를 생성한다.

(x, y, z)에 대한 다음의 조작과 행렬을 실행해 포인트 (x', y', z')를 생성한다.

가장 일반적인 트랜스 폼은, 평행이동, 회전, 및 스케일링이다. 이러한 효과를 생성하는 행렬을 조합해 단일의 행렬을 생성 해, 몇개의 트랜스 폼을 동시에 계산할 수 있다. 예를 들어, 일련의 점을 평행이동 해 회전시키는 단일의 행렬을 생성 할 수 있다. 상세한 것에 대하여는, 「행렬 연결」을 참조할것.

행렬은, 행과 열의 순서로 기술한다. 버텍스를 각 축으로 대해 균일하게 스케일링 하는 (한결같은 스케일링으로 불린다) 행렬은, 수학적으로는 다음과 같이 표기된다.

C++ 의 경우, Microsoft® Direct3D® 에서는,D3DMATRIX 구조체를 사용해 행렬을 2 차원 배열로서 선언한다. 다음의 예는, 한결같은 스케일링을 실시하는 행렬로서 기능하도록(듯이) D3DMATRIX 구조체를 초기화하는 방법을 나타내고 있다.

// 이 예에서는, s 는 float 형의 변수이다

D3DMATRIX scale = {
    s,               0.0f,            0.0f,            0.0f,
    0.0f,            s,               0.0f,            0.0f,
    0.0f,            0.0f,            s,               0.0f,
    0.0f,            0.0f,            0.0f,            1.0f
};


평행이동

다음의 트랜스 폼은, 포인트 (x, y, z)를 새로운 포인트 (x', y', z')에 평행이동 한다.

C++ 에서는, 독자적인 평행이동 행렬을 생성 할 수 있다. 다음의 예는, 버텍스를 평행이동하기 위한 행렬을 생성 하는 함수의 원시 코드를 나타내고 있다.

D3DXMATRIX Translate(const float dx, const float dy, const float dz) {
    D3DXMATRIX ret;

    D3DXMatrixIdentity(&ret);  // Direct3DX 에 의해 이행 된다.
    ret(3, 0) = dx;
    ret(3, 1) = dy;
    ret(3, 2) = dz;
    return ret;
}    // 평행이동 종료.

간편화하기 (위해)때문에, Direct3DX 유틸리티 라이브러리에 의해 D3DXMatrixTranslation 함수가 제공된다.


회전

여기에서는, 왼손 좌표계의 트랜스 폼에 대해 설명한다. 따라서, 지금까지의 트랜스 폼 행렬과는 다른 경우도 있다. 상세한 것에 대하여는, 「3D 좌표계」를 참조할것.

다음의 트랜스 폼은, 포인트 (x, y, z)를 x 축을 중심으로 회전해 새로운 포인트 (x', y', z')를 생성한다.

다음의 트랜스 폼은, 포인트를 y 축을 중심으로 회전한다.

다음의 트랜스 폼은, 포인트를 z 축을 중심으로 회전한다.

이러한 행렬의 예에서는, 그리스 문자 시타 (θ)는, 회전 각도를 라디안 단위로 나타내고 있다. 각도는, 회전축을 중심으로 해 원점 방향을 향한 시계회전으로 측정한 것이다.

C++ 어플리케이션에서는, Direct3DX 유틸리티 라이브러리에 의해 제공되는 D3DXMatrixRotationX 함수,D3DXMatrixRotationY 함수, 및 D3DXMatrixRotationZ 함수를 사용해 회전 행렬을 생성 한다. 다음의 코드는,D3DXMatrixRotationX 함수의 코드이다.

D3DXMATRIX* WINAPI D3DXMatrixRotationX
    ( D3DXMATRIX *pOut, float angle )
{
#if DBG
    if(! pOut)
        return NULL;
#endif

    float sin, cos;
    sincosf(angle, &sin, &cos);  // 각도의 sin 와 cos 를 결정한다.

    pOut->_11 = 1.0f; pOut->_12 =  0.0f;   pOut->_13 = 0.0f; pOut->_14 = 0.0f;
    pOut->_21 = 0.0f; pOut->_22 =  cos;    pOut->_23 = sin;  pOut->_24 = 0.0f;
    pOut->_31 = 0.0f; pOut->_32 = -sin;    pOut->_33 = cos;  pOut->_34 = 0.0f;
    pOut->_41 = 0.0f; pOut->_42 =  0.0f;   pOut->_43 = 0.0f; pOut->_44 = 1.0f;

    return pOut;
}


스케일링

다음의 트랜스 폼은, x, y, 및 z 방향의 임의의 값으로 포인트 (x, y, z)를 새로운 포인트 (x', y', z')에 스케일링 한다.


행렬 연결

행렬을 사용하는 이점의 1 개는, 복수의 행렬을 곱셈해 그러한 이펙트를 조합할 수가 있다고 하는 것이다. 즉, 모델을 회전해, 다음에 다른 위치 좌표에 평행이동 하는 경우, 2 개의 행렬을 적용할 필요는 없다. 그 대신해, 회전 행렬과 평행이동 행렬을 곱셈해, 모든 이펙트를 가지는 합성 행렬을 생성한다. 이 처리는행렬 연결로 불려 다음의 공식에서 기술할 수 있다.

이 공식에서는,C 는 생성 하는 합성 행렬로,M1 ~ Mn 하행열 C 에 포함되는 개개의 트랜스 폼이다. 대부분의 경우, 2 개(살) 또는 3 개의 행렬을 연결하지만, 수에 제한은 없다.

D3DXMatrixMultiply 함수를 사용해, 행렬의 곱셈을 실행한다.

행렬의 곱셈이 실행되는 순서는 중요하다. 위에의 공식은, 행렬 연결의 "왼쪽에서 오른쪽" 규칙을 반영하고 있다. 즉, 합성 행렬을 생성 하기 위해서 사용하는 행렬의 시각 이펙트는, 왼쪽에서 오른쪽의 순서로 나타난다. 일반적인 월드 트랜스 폼 행렬의 예를 다음에 나타낸다. 상투적인 "비확인 비행물체의 총칭" 용의 월드 트랜스 폼 행렬을 생성 하면 가정한다. 이 비확인 비행물체의 총칭을 중심 (모델 공간 의 y 축)을 축으로 회전시켜, 신내의 다른 장소에 평행이동 하고 싶다고 한다. 이 효과를 실현하려면 , 다음의 식과 같이, 우선 회전 행렬을 생성 해, 다음에 이 행렬을 평행이동 행렬로 곱한다.

이 공식에서는,Ry 는 y 축을 중심으로 회전하는 행렬로,Tw 는 월드 좌표의 임의의 위치 좌표에의 평행이동이다.

이러한 행렬을 곱셈하는 순서는 중요하다. 2 개의 스칼라값을 곱셈하는 경우와는 달라, 행렬의 곱셈은 가환적이지 않다. 평행이동 행렬과 회전 행렬을 역의 순서로 곱셈 하면, 비확인 비행물체의 총칭이 월드 공간 위치 좌표로 이동하고 나서, 월드 좌표의 원점을 중심으로 회전 하면 말하는 이펙트가 생겨 버린다.

어떠한 행렬을 생성 하는 경우에서도, 기대 대로의 이펙트를 실현하기 위해서(때문에)는 "왼쪽에서 오른쪽" 규칙을 잊어서는 안된다.


벡터, 버텍스, 및 쿠오타니온

Microsoft® Direct3D® 에서는, 버텍스에 의해 위치와 방향이 나타내진다. 프리미티브의 각 버텍스는, 위치를 나타내는 벡터, 색, 텍스쳐 좌표, 및 방향을 나타내는법선 벡터에 의해 기술된다.

쿠오타니온은, 3 컴퍼넌트 벡터를 정의하는 [x, y, z] 값에 제 4 의 요소를 추가한다. 쿠오타니온은, 3D 회전으로 일반적으로 사용되는 행렬 메소드에 대신하는 것이다. 쿠오타니온은, 3D 공간내의 축과 그 축을 중심으로 하는 회전을 나타낸다. 예를 들어, 1 개의 쿠오타니온으로 축 (1,1,2)과 1 라디안의 회전을 나타낼 수가 있다. 쿠오타니온은 중요한 정보도 전하지만, 그 진가는, 쿠오타니온상에서 실행할 수 있는 2 개의 처리, 합성과 보간으로 발휘된다.

쿠오타니온의 합성은, 결합 처리에 유사한다. 2 개의 쿠오타니온의 합성은, 이하와 같이 설명할 수가 있다.

1 개의 지오메트리에 대한 2 개의 쿠오타니온의 합성이란,"지오메트리를 axis2 를 중심으로 rotation2 만 회전한 후에, axis1 을 중심으로 rotation1 만 회전하는" 것이다. 이 경우 Q 는, 지오메트리에 q2 를 적용한 후에 q1 을 적용한 결과 생성된 단일축을 중심으로 하는 회전을 나타낸다.

쿠오타니온의 보간을 사용하면, 어플리케이션은 있는 축과 방향으로부터 다른 축과 방향까지의 매끄럽고 적절한 패스를 계산할 수가 있다. 따라서, q1 으로부터 q2 의 사이를 보간 하면, 어느 방향으로부터 다른 방향에 간단하게 애니메이션 할 수가 있다.

합성과 보간을 조합하면(자), 지오메트리의 일견 복잡할 것 같은 조작을 간단하게 실행할 수 있다. 예를 들어, 일정한 방향으로 회전시키고 싶은 지오메트리가 있다고 한다. axis2 를 중심으로 r2о 만 회전한 후에, axis1 을 중심으로 r1о 만 회전하는 것은 알고 있지만, 최종적인 쿠오타니온은 모른다고 한다. 이 경우, 합성에 의해 지오메트리 위에의 2 개의 회전을 결합하면, 그 결과적으로, 단일의 쿠오타니온이 생성된다. 그리고, 원의 쿠오타니온과 합성된 쿠오타니온의 사이를 보간 해, 쿠오타니온으로부터 쿠오타니온에 매끄러운 트란지션을 실현할 수 있다.

Direct3DX 유틸리티 라이브러리에는, 쿠오타니온의 조작에 도움이 되는 함수가 있다. 예를 들어,D3DXQuaternionRotationAxis 함수는, 회전의 축을 정의하는 벡터에 회전값을 가산해, 그 결과를 D3DXQUATERNION 구조체에 의해 정의되는 쿠오타니온에 돌려준다. 게다가D3DXQuaternionMultiply 함수는 쿠오타니온을 합성해,D3DXQuaternionSlerp 는 2 개의 쿠오타니온간에 구(공)장상에서 선형 보간을 실행한다.

Direct3D 어플리케이션에서는, 이하의 함수를 사용해 쿠오타니온의 조작을 단순화 할 수가 있다.

  • D3DXQuaternionBaryCentric
  • D3DXQuaternionConjugate
  • D3DXQuaternionDot
  • D3DXQuaternionExp
  • D3DXQuaternionIdentity
  • D3DXQuaternionInverse
  • D3DXQuaternionIsIdentity
  • D3DXQuaternionLength
  • D3DXQuaternionLengthSq
  • D3DXQuaternionLn
  • D3DXQuaternionMultiply
  • D3DXQuaternionNormalize
  • D3DXQuaternionRotationAxis
  • D3DXQuaternionRotationMatrix
  • D3DXQuaternionRotationYawPitchRoll
  • D3DXQuaternionSlerp
  • D3DXQuaternionSquad
  • D3DXQuaternionToAxisAngle

Direct3D 어플리케이션에서는, 이하의 함수를 사용해 3 컴퍼넌트 벡터의 조작을 단순화 할 수가 있다.

  • D3DXVec3Add
  • D3DXVec3BaryCentric
  • D3DXVec3CatmullRom
  • D3DXVec3Cross
  • D3DXVec3Dot
  • D3DXVec3Hermite
  • D3DXVec3Length
  • D3DXVec3LengthSq
  • D3DXVec3Lerp
  • D3DXVec3Maximize
  • D3DXVec3Minimize
  • D3DXVec3Normalize
  • D3DXVec3Project
  • D3DXVec3Scale
  • D3DXVec3Subtract
  • D3DXVec3Transform
  • D3DXVec3TransformCoord
  • D3DXVec3TransformNormal
  • D3DXVec3Unproject

그 외, Direct3DX 유틸리티 라이브러리의산술 함수에는,2 컴퍼넌트 벡터나 4 컴퍼넌트 벡터에 의한 처리를 단순화하기 위한 함수가, 다수 준비되어 있다.


표면의 카피

이 소총탄 (blit )이란, 비트 소총탄 (bit block transfer)여, 데이터의 블록을 메모리내가 있는 장소로부터 다른 장소에 전송 하는 프로세스를 가리킨다. 소총탄에 의한 디바이스 드라이버 인터페이스 (DDI)는, 픽셀수의 큰 직사각형을 프레임 단위로 이동할 때의 주요 메카니즘, 즉 카피 주체의 IDirect3DDevice8::Present 메소드의 배후에 있는 메카니즘으로서 Microsoft® DirectX® 8.0 에서도 계속해 사용되고 있다. 소총탄 처리에 있어서의 artwork의 이동은,IDirect3DDevice8::UpdateTexture 메소드에 의해 실행된다. DirectX 8.0 에서는, artwork는 픽셀의 직사각형 서브 세트를 카피하는 IDirect3DDevice8::CopyRects 메소드를 사용해 카피할 수도 있다.

주 DirectX 8.0 으로 제공되는 D3DX 함수에 의해, artwork를 파일로부터 로드하거나 색의 변경을 적용하거나 artwork의 사이즈를 변경하거나 할 수가 있다. 사용할 수 있는 함수의 상세한 것에 대하여는, 「텍스쳐 함수」를 참조할것.


페이지후립핑과 백 버퍼링

페이지후립핑은, 멀티미디어나 애니메이션, 게임등의 소프트웨어로 주로 사용된다. 소후트웨아페이지후립핑은, 종이의 다발을 사용해 애니메이션을 생성 하는 방법으로 유사한다. 페이지 마다 형태를 조금씩 바꾸어 드로잉(Drawing) 해, 종이를 재빠르게 톡톡 넘겨 애니메이션과 같이 보이는 방법이다.

소프트웨어에서의 페이지후립핑은, 이 프로세스와 자주(잘) 비슷하다. Microsoft® Direct3D® 에서는, 디바이스의 프로퍼티인 스왑 체인을 개입시켜, 페이지후립핑 기능을 이행 한다. 최초로, 애니메이션 작가의 종이를 다음의 페이지에 플립 하도록(듯이), 스크린에 플립 하는 일련의 Direct3D 버퍼를 셋업 한다. 최초의 버퍼는 칼라 프런트 버퍼로 불려 배후의 버퍼는백 버퍼로 불린다. 어플리케이션은 백 버퍼에 기입해, 다음에 칼라 프런트 버퍼를 플립 해 백 버퍼를 스크린에 표시한다. 시스템이 이미지를 표시하고 있는 동안, 소프트웨어는 다시 백 버퍼에 기입한다. 이 프로세스는 애니메이션의 사이 계속되어, 재빠르게 효율적으로 이미지를 애니메이션 시킨다.

Direct3D 는, 비교적 단순한 더블 버퍼 스킴 (1 개의 백 버퍼를 가지는 칼라 프런트 버퍼)으로부터, 추가의 백 버퍼를 부가했던 것보다 고도의 스킴까지,페이지후립핑 스킴 의 셋업을 용이하게 한다.


직사각형

Microsoft® Direct3D® 및 Microsoft Windows® 프로그래밍으로부터, 스크린 위에의 오브젝트는 경계 직사각형으로 참조된다. 경계 직사각형의 구석은 항상 화면의 구석과 평행이기 (위해)때문에, 직사각형은 맨 왼쪽 위쪽과 우하각의 2 점으로써 기술된다. 대부분의 어플리케이션에서는, 스크린에의 소총탄이나히트 검출을 실시하기 위해서(때문에) 이용되는 경계 직사각형의 정보 전달에 RECT 구조체가 사용된다.

RECT 구조체의 정의를 이하에 나타낸다.

typedef struct tagRECT {
    LONG    left;    // 이것은, 좌상의 모퉁이의 x 좌표.
    LONG    top;     // 이것은, 좌상의 모퉁이의 y 좌표.
    LONG    right;   // 이것은, 우하의 모퉁이의 x 좌표.
    LONG    bottom;  // 이것은, 우하의 모퉁이의 y 좌표.
} RECT, *PRECT, NEAR *NPRECT, FAR *LPRECT;

위의예로, left 및 top 멤버는, 경계 직사각형의 맨 왼쪽 위쪽의 x 좌표와 y 좌표를 나타낸다. 같이 right 및 bottom 멤버는, 우하각의 좌표를 구성한다. 다음의 그림은, 이러한 값을 시각적으로 설명하고 있다.

효율, 일관성, 편리한 사용등을 (위해)때문에에, 모든 Direct3D Presentation 함수는 직사각형 범위를 사용한다.


DirectX Graphics 에 대해

여기에서는, Microsoft® DirectX® Graphics 의 기본적 없음 쌍에 대해 설명한다.

  • Direct3D 아키텍쳐
  • Direct3D 렌더링 파이프라인


Direct3D 아키텍쳐

여기에서는, Microsoft® Direct3D® 컴퍼넌트와 그 외의 Microsoft DirectX® 컴퍼넌트, operating system, 및 시스템 하드웨어와의 관계에 대해 설명한다. 설명하는 주제는, 다음과 같다

  • Direct3D 아키텍쳐의 개요
  • 하드웨어 추상 계층
  • 시스템의 통합


Direct3D 아키텍쳐의 개요

Microsoft® Direct3D® 아키텍쳐의 프로그램 가능한 부분은, 버텍스 쉐이더 및 픽셀 쉐이더의 2 개이다. 버텍스 쉐이더는 버텍스 어셈블리의 전에 불려 가 버텍스를 처리한다. 픽셀 쉐이더는 DrawPrimitive 의 호출의 뒤에 불려 가 픽셀을 처리한다.

다음의 단순한 그림에, Direct3D 아키텍쳐를 나타낸다. 이것은 아키텍쳐의 일부이다. Direct3D 에서는 8 개의 텍스쳐 및 텍스쳐 좌표를 지원 하고 있다.

위에의도에 나타내도록(듯이), 버텍스 버퍼는 버텍스 데이터를 버텍스 쉐이더에 스트리밍 한다. 버텍스 쉐이더는, Direct3DX 버텍스 쉐이더 어셈블러에 의해 정의되고 있는 명령을 사용해, 지오메트리 처리를 실행한다.

버텍스 쉐이더에 스트리밍 되는 데이터는, 버텍스 버퍼에 저장 되고 있을 필요는 없지만, 저장 되고 있으면 이상적이다. 버텍스 어셈블리의 다음에, 어셈블(assemble) 된 버텍스 데이터는 DrawPrimitive 메소드를 사용해 드로잉(Drawing) 된다. 이 시점에서, 드로잉(Drawing) 된 프리미티브의 각 픽셀 (위치, 색, 텍스쳐, 및 텍스쳐 좌표등)은, 픽셀 쉐이더에게 건네진다. 픽셀 쉐이더는, Direct3DX 픽셀 쉐이더 어셈블러에 의해 정의되고 있는 명령을 사용해, 픽셀 처리를 실행한다.

픽셀을 처리하는 픽셀 쉐이더 스테이지에의 입력에는, 텍스쳐 표면 및 표면의 샘플링을 제어하는 관련하는 텍스쳐 좌표가 포함된다. 출력 픽셀은 frame buffer에게 건네진다.

Direct3D 의 프로그램 가능한 부분의 아키텍쳐의 상세한 것에 대하여는, 「버텍스 쉐이더 아키텍쳐」 및 「픽셀 쉐이더 아키텍쳐」를 참조할것.

버텍스 쉐이더 및 픽셀 쉐이더를 렌더링 파이프라인에 짜넣는 방법의 상세한 것에 대하여는, 「Direct3D 렌더링 파이프라인」을 참조할것.


버텍스 쉐이더 아키텍쳐

다음의 그림은, 버텍스 쉐이더 아키텍쳐를 나타내고 있다.

버텍스 데이터에의 데이터는, 버텍스 데이터 스트림으로부터 취득되어 정수 데이터는 버텍스 쉐이더 선언자에 의해 로드 된다. 상세한 것에 대하여는, 「버텍스 쉐이더 어셈블러 레퍼런스」를 참조할것.


픽셀 쉐이더 아키텍쳐

다음의 그림은, 픽셀 쉐이더 아키텍쳐를 나타내고 있다.

픽셀 쉐이더에의 데이터는 클립 공간 버텍스 (동차 좌표)이다. 디퓨즈 및 스펙큐러색은, 칼라 레지스터의 값 (v0 및 v1)으로부터 취득된다. 텍스쳐 좌표 및 설정된 텍스쳐는, 텍스쳐 설정 스테이지 및 버텍스 데이터의 텍스쳐 레지스터 (t0, t1, t2, 및 t3)의 값으로부터 취득된다. 상세한 것에 대하여는, 「픽셀 쉐이더 어셈블러 레퍼런스」를 참조할것.


하드웨어 추상 계층

Microsoft® Direct3D® 는, 하드웨어 추상 계층 (HAL)에 의해 디바이스의 독립성을 제공한다. HAL 는, 디바이스 메이커로부터 제공되는 디바이스 고유의 인터페이스로, Direct3D 는 그것을 사용해 디스플레이 하드웨어를 직접 동작시킨다. 어플리케이션은, HAL 와는 결코 상호작용 하지 않는다. 오히려 HAL 의 제공하는 인프라를 사용해, Direct3D 는 어플리케이션이 그래픽스를 표시하기 위해서 사용하는 인터페이스나 메소드의 일관한 세트를 공개한다. 디바이스 메이커는, Microsoft Windows® 의 아래에서는 16 비트 코드, 32 비트 코드의 편성으로 HAL 를 이행 한다. Windows NT® 및 Windows 2000 의 아래에서는, HAL 는 항상 32 비트 코드로 이행 된다. HAL 는, 디스플레이 드라이버의 일부에서 만나거나 드라이버의 생성자가 정의하는 프라이빗 인터페이스로부터 디스플레이 드라이버와 통신하는 개별의 DLL 가 될 수도 있다.

Direct3D HAL 는, 팁 메이커, 보드 제작자, 또는 OEM 업자에 의해 이행 된다. HAL 는, 디바이스 의존의 코드를 이행 하는 것만으로, 에뮬레이션은 실시하지 않는다. 어느 기능이 하드웨어에 의해 실행되지 않는다고 해도, HAL 는 그것을 하드웨어 능력이라고 봐 보고하지 않는다. 게다가 HAL 는 파라미터를 확인하지 않기 때문에, HAL 가 기동되기 전에 Direct3D 가 이 파라미터를 확인한다.

DirectX 8.0 에서는, HAL 는 3 종류의 버텍스 처리 모드를 가질 수가 있다. 소프트웨어 버텍스 처리, 하드웨어 버텍스 처리, 및 동일 디바이스에서의 혼합 버텍스 처리이다. 퓨어 디바이스 타입은 HAL 디바이스의 일종이다. 퓨어 디바이스 타입은 하드웨어에 의한 버텍스 처리만을 지원 해, 어플리케이션을 조회할 수 있는 것은 디바이스 스테이트의 작은 서브 세트에 한정된다. 게다가 퓨어 디바이스는, 최소 레벨의 능력을 갖춘 어댑터에서만 사용할 수 있다.


시스템의 통합

다음의 그림은, Microsoft® Direct3D® 와 그래픽스 디바이스 인터페이스 (GDI), 하드웨어 추상 계층 (HAL), 및 하드웨어와의 관계를 나타내고 있다.

전의 그림에 나타내도록(듯이), Direct3D 어플리케이션은 GDI 어플리케이션과 함께 존재해, 이것들은 그래픽 카드용의 디바이스 드라이버를 개입시켜 그래픽스 하드웨어에 액세스 한다. GDI 과는 달리, Direct3D 는, HAL 디바이스가 선택되고 있을 때 하드웨어 기능을 이용할 수 있다. HAL 디바이스는, 그래픽 카드로 지원 되는 기능 세트에 근거해, 하드웨어 가속화를 제공한다. 디바이스에 태스크의 능력이 있을지 어떨지를 실행시에 판단하기 위한 Direct3D 메소드를 이용할 수 있다.

소프트웨어 디바이스는, DirectX 8.0 기능 세트 전체를 지원 하고 있는 것은 아니지만, 어플리케이션이 항상, 어느 시스템에 대해도, 동작하고 있는 디바이스를 찾아낼 수가 있도록(듯이) 하고 있다. 다만, 많은 경우, 소프트웨어 디바이스상에서 실행되는 어플리케이션에서는, 저하한 기능에서도 실행되는 대로 준비할 필요가 있다. 소프트웨어 디바이스의 능력은, 하드웨어 디바이스의 능력과 같은 방법으로 조사할 수가 있다.

Direct3D 로 지원 되는 디바이스의 상세한 것에 대하여는, 「디바이스의 종류」를 참조할것.


Direct3D 렌더링 파이프라인

Microsoft® Direct3D® 렌더링 파이프라인은, 버텍스 트랜스 폼 및 라이팅 파이프라인, 및 픽셀 및 텍스쳐 블렌딩 파이프라인의 동작을 지정하는 일련의 처리 스테이지이다.

3D 어플리케이션을 설계 하면 와, 편리성을 고려해 미크론으로부터 파섹까지, 모든 단위로 월드를 정의할 수 있다. 어플리케이션은, 이 월드의 기술을 Direct3D 에 건네준다. 이 기술에는, 월드내에 있는 모든 오브젝트의 사이즈와 상대 위치 좌표, 및 뷰아의 위치 좌표와 방향이 포함된다. Direct3D 는, 이 기술 (버텍스)을 스크린 위에의 일련의 픽셀로 변환한다. 이 처리의 최초의 스텝 (지오메트리의 2D 화면에의 변환)을, 지오메트리 파이프라인 또는 트랜스 폼 파이프라인이라고 부른다. 버텍스를 처리한 후, 픽셀 데이터를 사용해 멀티 텍스쳐 처리 및 fog 블렌딩이 실행된다. 다음에, 알파, 스텐실, 및 깊이 테스트가 실행된다. 마지막으로, frame buffer 블렌딩이 래스터라이저에 의해 실행된다.

이하의 주제에서는, 주로 Direct3D 에 있어서의 완전한 렌더링 파이프라인에 대해 설명한다. 또, 중요한 개념에 대해, 및 이러한 개념에 대응하는 Direct3D API 의 개념에 대해서도 해설한다. 고정 기능 처리의 주제에서는, 구버젼의 Microsoft DirectX® 를 사용하고 있던 개발자이면 이미 이해하고 있는 방법에 대해 설명한다. 따라서, 프로그램 가능 (프로시저) 처리의 주제에서는, Microsoft DirectX 8.0 의 버텍스 처리와 픽셀 처리로 사용되는 새로운 프로시저 모델에 대해 설명한다.

  • 고정 기능에 의한 버텍스 처리와 픽셀 처리
  • 프로그램 가능한 버텍스 처리와 픽셀 처리
  • 버텍스 프로세서에의 버텍스 데이터의 제시


고정 기능에 의한 버텍스 처리와 픽셀 처리

지오메트리의 고정 기능에 의한 지오메트리 파이프라인을 실행하는 것은, Microsoft® Direct3D® 의 트랜스 폼 엔진이다. 이것은, 월드내의 모델과 뷰아를 검출해, 스크린상에 표시할 수 있도록(듯이) 버텍스를 투영 해, 버텍스를 뷰 포토에 잘라낸다. 또, 트랜스 폼 엔진은, 라이팅 계산을 실행해 각 버텍스의 디퓨즈 및 스펙큐러 성분을 결정한다.

지오메트리 파이프라인은, 버텍스를 입력으로서 받는다. 트랜스 폼 엔진은, 버텍스에 3 개의 트랜스 폼 (월드 트랜스 폼, 뷰 트랜스 폼, 및 투영 트랜스 폼)을 적용해, 결과를 클립 해, 그 모든 것을 래스터라이저에 건네준다. 다음의 그림은, 일련의 스텝을 나타내고 있다.

파이프라인의 최초의 단계에 있어 트랜스 폼은 적용되지 않고, 모델의 버텍스는 모두 로컬 좌표계 (이것은 로컬 원점과 방향이다)에 대해서 선언된다. 이 좌표 방향을 일반적으로모델 공간이라고 불러, 개개의 로컬 좌표는모델 좌표라고 부른다.

지오메트리 파이프라인에서는, 최초로 로컬 좌표계의 모델의 버텍스가, 장면의 모든 오브젝트로 사용하는 좌표계에 트랜스 폼 된다. 버텍스를 월드 좌표계로 재차 다시 하는 것 를,월드 트랜스 폼이라고 부른다. 이 새로운 방향은, 보통은월드 공간으로 불려 월드 공간의 각 버텍스는,월드 좌표를 사용해 선언된다.

다음에, 3D 월드를 기술하는 버텍스를 카메라에 대한 상대 위치 좌표로 다시 정의한다. 즉, 어플리케이션은 장면의 시점 (카메라의 위치)을 선택해, 월드 공간은 시점의 위치와 방향에 맞추어 재정의된다. 즉, 월드 공간이카메라 공간에 트랜스 폼 된다. 이것이뷰 트랜스 폼이다.

다음의 단계에서는,투영 트랜스 폼을 한다. 파이프라인에 있어서의 이 단계에서는, 보통, 먼 오브젝트보다 가까이의 오브젝트가 크게 보이도록(듯이) 하는 등, 뷰아로부터의 거리를 기준에 오브젝트가 스케일링 되어, 장면에 깊이가 태어난다. 알기 쉽게 하기 위해서, 이 문서에서는, 투영 트랜스 폼 후의 버텍스가 존재하는 공간을,투영 공간이라고 부르기로 한다. 그래픽스 관련의 서적에서는, 투영 공간을, 원근 보정 후 동차 공간이라고 부르는 경우도 있다. 모든 투영 트랜스 폼에 의해 장면의 오브젝트의 사이즈가 스케일링 된다고는 할 수 없다. 이러한 투영은, 아핀 투영 또는 정사영으로 불리는 일도 있다.

파이프라인의 마지막 단계에서는, 스크린상에서 안보이는 버텍스가 모두 삭제된다. 이것에 의해, 래스터라이저는, 안보이는 오브젝트에 관해서 색과 쉐이딩의 계산을 실행할 필요가 없어진다. 이 처리는 클리핑으로 불린다. 클리핑이 완료 하면, 나머지의 버텍스는 뷰 포토 파라미터에 따라 스케일링 되어 화면 좌표계에 트랜스 폼 된다. 그 결과, 이러한 버텍스는, 장면이 라스터화 되었을 때에 스크린에 표시되어스크린 공간에 존재하게 된다.

고정 버텍스 처리와 픽셀 처리 파이프라인에 대해서는, 이하의 주제로 나누어 설명한다.

  • 트랜스 폼 및 라이팅 엔진
  • 뷰 포토와 클리핑
  • 라스터화


트랜스 폼 및 라이팅 엔진

이하의 주제에서는, 고정 기능에 의한 트랜스 폼 및 라이팅 엔진의 각 컴퍼넌트의 구조를 자세하게 설명한다.

  • 월드 트랜스 폼
  • 뷰 트랜스 폼
  • 투영 트랜스 폼
  • 라이팅 엔진
  • Direct3D 의 라이팅에 있어서의 수학적 계산


월드 트랜스 폼

여기에서는, 월드 트랜스 폼에 대한 기본적인 개념을 소개해, Microsoft® Direct3D® 어플리케이션으로 월드 트랜스 폼 행렬을 설정하는 방법에 대해 자세하게 설명한다. 설명하는 주제는 다음과 같다.

  • 월드 트랜스 폼이란
  • 월드 행렬의 설정


월드 트랜스 폼이란

월드 트랜스 폼에서는, 버텍스가 모델의 로컬 원점에 대해서 정의되는 모델 공간으로부터, 버텍스가 장면내의 모든 오브젝트에 공통되는 원점에 대해서 정의되는월드 공간에 좌표를 트랜스 폼 한다. 기본적으로는, 월드 트랜스 폼에 의해 모델이 월드에 배치되는 것으로부터, 이러한 이름이 붙어 있다. 다음의 그림은, 월드 좌표계와 모델의 로컬 좌표계의 관계를 나타내고 있다.

월드 트랜스 폼에서는, 평행이동, 회전, 및 스케일링을 어떻게 조합해도 사용할 수 있다. 트랜스 폼의 수학 위에의 설명에 대해서는, 「3D 트랜스 폼」을 참조할것.


월드 행렬의 설정

다른 모든 트랜스 폼과 같이, 일련의 트랜스 폼 행렬을, 개개의 효과를 모두 포함한 단일의 행렬에 연결하는 것으로 월드 트랜스 폼을 생성 한다. 간단한 예에서는, 어느 모델이 월드 원점에 있어, 그 로컬 좌표축이 월드 공간과 같은 방향으로 정의되고 있는 경우, 월드 행렬은 단위행렬이다. 한층 더 일반적으로는, 월드 행렬은 월드 공간에의 평행이동을 조합한 것이어, 필요에 따라서 모델을 1 회 또는 몇번이나 회전할 수가 있다.

다음의 예는, C++ 로 기술된 가공의 3D 모델 클래스에 관한 것이다. 여기에서는, Direct3DX 유틸리티 라이브러리에 포함되는 헬퍼 함수를 사용해, 모델을 방향 짓는 회전을 3 회 실시해, 한층 더 월드 공간에서의 위치 좌표를 기준에 그 모델을 재배치하는 평행이동을 실시하는 월드 행렬을 생성 한다.

/*
* 이 예에서는, 다음의 변수는
* 유효하고, 초기화되고 있으면(자) 가정한다.
 *
* 변수 m_xPos, m_yPos, m_zPos 는 모델의
* 월드 좌표에서의 위치를 저장 한다.
 *
* 변수 m_fPitch, m_fYaw, 및 m_fRoll 는 부동 소수점수(실수)로,
* 피치, 요, 및 롤 (라디안 단위)에서의
* 모델의 방향을 저장 한다.
 */

void C3DModel::MakeWorldMatrix( D3DXMATRIX* pMatWorld )
{
    D3DXMATRIX MatTemp;  // 회전용의 Temp 행렬.
    D3DXMATRIX MatRot;   // 최종적인 회전 행렬.
                         // pMatWorld 에 적용된다.

    // 왼쪽에서 오른쪽으로 행렬을 연결해,
    // 오브젝트의 월드 위치 좌표에 평행이동을 적용한 후,
    // 회전을 적용한다.
    D3DXMatrixTranslation(pMatWorld, m_xPos, m_yPos, m_zPos);
    D3DXMatrixIdentity(&MatRot);

    // 여기서, 월드 행렬에 향해 변수를 적용한다.
    if(m_fPitch || m_fYaw || m_fRoll) {
        // 회전 행렬을 생성 해, 조합한다.
        D3DXMatrixRotationX(&MatTemp, m_fPitch);         // 피치.
        D3DXMatrixMultiply(&MatRot, &MatRot, &MatTemp);
        D3DXMatrixRotationY(&MatTemp, m_fYaw);           // 요.
        D3DXMatrixMultiply(&MatRot, &MatRot, &MatTemp);
        D3DXMatrixRotationZ(&MatTemp, m_fRoll);          // 롤.
        D3DXMatrixMultiply(&MatRot, &MatRot, &MatTemp);

        // 회전 행렬을 적용해, 월드 행렬을 완성한다.
        D3DXMatrixMultiply(pMatWorld, &MatRot, pMatWorld);
    }
}

월드 트랜스 폼 행렬을 준비할 수 있으면(자), 이 행렬을 설정하기 위해서 IDirect3DDevice8::SetTransform 메소드를 호출해, 제 1 파라미터에 D3DTS_WORLD 매크로를 지정한다. 상세한 것에 대하여는, 「트랜스 폼의 설정」을 참조할것.

주 Microsoft® Direct3D® 에서는, 설정된 월드 행렬 및 뷰 행렬을 사용해, 몇개의 내부 데이터 구조를 구축한다. 새로운 월드 행렬 또는 뷰 행렬을 설정할 때마다, 관계하는 내부 구조가 재계산된다. 이러한 행렬을 프레임 마다 수천회도 설정하는 등 빈번하게 설정 하면, 다대한 계산 부하가 발생한다. 필요한 계산을 최소한으로 억제하려면 , 월드 행렬로서 설정하는 월드 뷰 행렬에 월드 행렬 및 뷰 행렬을 연결한 후, 뷰 행렬을 단위행렬로 설정한다. 필요에 따라서 월드 행렬을 수정, 연결, 및 리셋 할 수 있도록(듯이), 월드 행렬 및 뷰 행렬의 각 캐쉬 카피는 보관 유지해 두는 것. 이 문서의 Direct3D 의 샘플에서는, 간결한 것을 우선해, 이 최적화는 거의 이용하지 않았다.


뷰 트랜스 폼

여기에서는, 뷰 트랜스 폼의 기본적인 개념을 소개해, Microsoft® Direct3D® 어플리케이션으로 뷰 트랜스 폼 행렬을 설정하는 방법에 대해 자세하게 설명한다. 설명하는 주제는, 다음과 같다.

  • 뷰 트랜스 폼이란
  • 뷰 행렬의 설정


뷰 트랜스 폼이란

뷰 트랜스 폼이란, 월드 공간에 시점을 배치해, 버텍스를카메라 공간에 트랜스 폼 하는 처리이다. 카메라 공간에서는, 카메라 (즉 시점)는 원점에 있어, z 축의 정방무카이를 향한다. Microsoft® Direct3D® 에서는 왼손 좌표계를 사용하기 위해(때문에), z 는 장면의 정방무카이를 향한다. 뷰 행렬은, 월드내의 오브젝트를 카메라의 위치 (카메라 공간의 원점)와 방향의 주위에 재배치한다.

뷰 행렬은 많은 방법으로 생성 할 수 있다. 모든 방법에 대해, 카메라는 월드 공간내에서 몇개의 논리 위치 좌표와 방향을 가진다. 이러한 위치 좌표와 방향은, 장면내의 모델에 적용하는 뷰 행렬을 생성 할 때의 시점이 된다. 뷰 행렬은, 오브젝트를 평행이동 및 회전해, 카메라를 원점으로 한 카메라 공간내에 위치 좌표 붙인다. 뷰 행렬을 생성 하는 방법으로서는, 평행이동 행렬과 각 축으로 대하는 회전 행렬을 조합하는 방법이 있다. 이 방법에서는, 다음의 일반적인 행렬식이 적용된다.

이 식에서는,V 는 생성 하는 뷰 행렬,T 는 오브젝트를 월드내에 재배치하는 평행이동 행렬,Rx ~ Rz 는 x, y, 및 z 축으로 따라 오브젝트를 회전하는 회전 행렬이다. 이 평행이동 행렬과 회전 행렬은, 월드 공간에 있어서의 카메라의 논리 위치 좌표와 방향에 근거하고 있다. 따라서, 월드에 있어 카메라의 논리 위치 좌표가 <10, 20,100> 의 경우, 평행이동 행렬은, x 축으로 따라 -10 단위, y 축으로 따라 -20 단위, z 축으로 따라 -100 단위만 오브젝트를 평행이동 하게 된다. 이 식에 있어서의 회전 행렬은, 카메라의 방향에 근거하고 있어 카메라 공간의 축이 월드 공간으로부터 어느 정도 회전하는지를 나타낸다. 예를 들어, 위에의 예의 카메라가 바로 밑을 향하고 있는 경우, 다음의 그림에 나타내도록(듯이), 카메라 공간의 z 축은 월드 공간의 z 축으로부터 90о (π/2 라디안)만 어긋나 있다.

회전 행렬은, 매그니튜드는 같지만 방향이 역의 회전을, 장면내의 모델에 적용한다. 이 카메라에 대한 뷰 행렬은, x 축을 중심으로 했다 -90о의 회전을 포함한다. 회전 행렬과 평행이동 행렬을 조합하는 것으로, 장면내의 오브젝트의 위치 좌표와 방향을 조정하는 뷰 행렬을 생성 해, 오브젝트의 위쪽에 카메라를 두어 모델을 위로부터 내려다 볼 수가 있다.

다른 방법으로서 복잡한 뷰 행렬을 직접 생성 하는 방법도 있다. D3DXMatrixLookAtLH 및 D3DXMatrixLookAtRH 헬퍼 함수에서는, 이 방법이 사용된다. 이 방법에서는, 카메라의 월드 공간에 있어서의 위치 좌표와 장면내의 주시점을 사용해, 카메라 공간의 좌표축의 방향을 기술하는 벡터를 파생시킨다. 주시점으로부터 카메라 위치 좌표를 감산해, 카메라의 방향 벡터 (벡터 n) 용의 벡터를 생성한다. 다음에, 벡터 n 와 월드 공간의 y 축의 외 츠무를 잡아, 정규화해, 우측향벡터 (벡터 u)를 생성한다. 다음에, 벡터 u 와 n 의 외 츠무를 잡아, 윗방향 벡터 (벡터 v)를 결정한다. 우측향 (u), 윗방향 (v), 및 뷰 방향 (n)의 벡터는, 월드 공간에 있어서의 카메라 공간의 좌표축의 방향을 기술한다. x, y, z 의 평행이동 계수는, 카메라 위치 좌표와 u,v,n 벡터의 사이의 내적의 음수를 취해 계산한다.

이러한 값을 다음의 행렬에 넣어, 뷰 행렬을 생성한다.

이 행렬에서는,u,v,n 는 각각 윗방향, 우측향, 뷰 방향의 벡터이며,c 는 카메라의 월드 공간 위치 좌표이다. 이 행렬에는, 월드 공간을 카메라 공간에 평행이동과 회전하기 위해서 필요한 요소가 모두 저장 된다. 이 행렬을 생성 한 후, z 축을 중심으로 하는 회전 행렬을 생성 해, 카메라를 회전할 수가 있다.

이 방법의 이행에 대해서는, 「뷰 행렬의 설정」을 참조할것.


뷰 행렬의 설정

D3DXMatrixLookAtLH 및 D3DXMatrixLookAtRH 헬퍼 함수는, 카메라 위치 좌표 및 주시점에 근거해 뷰 행렬을 생성 한다. 이러한 함수는,D3DXVec3Cross ,D3DXVec3Dot ,D3DXVec3Normalize , 및 D3DXVec3Subtract 헬퍼 함수를 사용한다.

다음의 코드는,D3DXMatrixLookAtLH 함수를 나타내고 있다.

D3DXMATRIX* WINAPI D3DXMatrixLookAtLH
    ( D3DXMATRIX *pOut, const D3DXVECTOR3 *pEye, const D3DXVECTOR3 *pAt,
      const D3DXVECTOR3 *pUp )
{
#if DBG
    if(! pOut || ! pEye || ! pAt || ! pUp)
        return NULL;
#endif

    D3DXVECTOR3 XAxis, YAxis, ZAxis;

    // 깊이를 나타내는 z 축벡터를 취득한다.
    // 시점으로부터 주시점까지의 차이이다. 이것은
    // 주시할 방향 (+z)이다.
    D3DXVec3Subtract(&ZAxis, pAt, pEye);

    // z 축벡터를 정규화한다.
    D3DXVec3Normalize(&ZAxis, &ZAxis);

    // 주시할 방향과 pUp 벡터의 외적으로부터
    // 직교축을 계산한다.
    D3DXVec3Cross(&XAxis, pUp, &ZAxis);
    D3DXVec3Normalize(&XAxis, &XAxis);
    D3DXVec3Cross(&YAxis, &ZAxis, &XAxis);

    // 행렬의 구축을 시작 한다. 최초의 3 개의 행에는,
    // 뷰를 회전해 주시점을 향하기 위한 벡터가 포함된다.
    // point. // 4 번째의 행에는 평행이동의 값이 포함된다.
    // 시점을 중심으로 한 회전을 한다.
    pOut->_11 = XAxis.x;
    pOut->_21 = XAxis.y;
    pOut->_31 = XAxis.z;
    pOut->_41 = -D3DXVec3Dot(&XAxis, pEye);

    pOut->_12 = YAxis.x;
    pOut->_22 = YAxis.y;
    pOut->_32 = YAxis.z;
    pOut->_42 = -D3DXVec3Dot(&YAxis, pEye);

    pOut->_13 = ZAxis.x;
    pOut->_23 = ZAxis.y;
    pOut->_33 = ZAxis.z;
    pOut->_43 = -D3DXVec3Dot(&ZAxis, pEye);

    pOut->_14 = 0.0f;
    pOut->_24 = 0.0f;
    pOut->_34 = 0.0f;
    pOut->_44 = 1.0f;

    return pOut;
}

월드 트랜스 폼의 경우와 같이,IDirect3DDevice8::SetTransform 메소드를 호출해 뷰 트랜스 폼을 설정해, 제 1 파라미터에 D3DTS_VIEW 플래그를 지정한다. 상세한 것에 대하여는, 「트랜스 폼의 설정」을 참조할것.

퍼포먼스의 최적화에 관한 주 Microsoft® Direct3D® 에서는, 설정된 월드 행렬 및 뷰 행렬을 사용해, 몇개의 내부 데이터 구조를 구축한다. 새로운 월드 행렬 또는 뷰 행렬을 설정할 때마다, 관계하는 내부 구조가 재계산된다. 이러한 행렬을 프레임 마다 20,000 회나 설정하는 등 빈번하게 설정 하면, 다대한 계산 부하가 발생한다. 필요한 계산을 최소한으로 억제하려면 , 월드 행렬로서 설정하는 월드 뷰 행렬에 월드 행렬 및 뷰 행렬을 연결한 후, 뷰 행렬을 단위행렬로 설정한다. 월드 행렬 및 뷰 행렬의 각 캐쉬 카피는 보관 유지해 두는 것. 필요에 따라서 월드 행렬을 수정, 연결, 및 리셋 할 수 있다. Direct3D 의 샘플에서는, 간결한 것을 우선해, 이 최적화는 거의 이용하지 않았다.


투영 트랜스 폼

투영 트랜스 폼은, 카메라의 내부를 제어하는 것으로 생각할 수가 있다. 즉, 투영 트랜스 폼은, 카메라의 렌즈를 선택하는 것에 비슷하다. 이 트랜스 폼은, 3 종류의 트랜스 폼 중(안)에서 가장 복잡하다. 투영 트랜스 폼에 대해서는, 이하의 주제로 나누어 설명한다.

  • 시추대
  • 투영 트랜스 폼이란
  • 투영 행렬의 설정
  • W 버퍼에 유효한 투영 행렬


시추대

시추대란, 뷰 포토의 카메라에 대해서 상대적으로 배치된 장면내의 3D 입체이다. 이 입체의 형태는,카메라 공간으로부터 스크린에 모델을 투영 하는 방법으로 영향을 준다. 가장 일반적인 투영은, 퍼스펙티브 투영이다. 이 투영에서는, 카메라의 근처에 있는 오브젝트가, 카메라의 멀리 있는 오브젝트보다 크게 표시된다. 퍼스펙티브 뷰의 경우, 시추대와는 첨단에 카메라가 있는 피라미드라고 생각하면(자) 알기 쉽다. 이 피라미드는, 전방 및 후방 클립면에 해당된다. 전방 및 후방 클립면의 사이에 있는 피라미드내의 입체가 시추대이다. 오브젝트는, 이 입체내에 있을 때 마셔 볼 수가 있다.

시추대는, 어두운 방 중(안)에서 정방형의 창으로부터 밖을 보고 있는 상황을 상상 하면 알기 쉽다. 별도인 표현을 하면, 전방 클립면은 창이며, 후방 클립면은 시야를 최종적으로 차단하는 것, 예를 들어, 거리의 고층빌딩, 먼 곳의 산맥, 또는 완전한 무의 공간이다. 시추대의 내부 (창으로부터 최종적으로 차단하는 것까지의 사이)에 있는 것은 모두 볼 수가 있어 그 이외의 것은 볼 수가 없다.

시추대는, z 좌표로 지정되는 전방 및 후방 클립면의 사이의 거리와 FOV (시야)로 정의된다.

이 그림에서는, 변수 D 는, 카메라로부터, 지오메트리 파이프라인의 마지막 부분 (뷰 트랜스 폼)에서 정의된 공간의 원점까지의 거리이다. 이 공간의 주위에 시추대의 한계를 설정한다. 이 변수 D 를 사용해 투영 행렬을 생성 하는 방법에 대해서는, 「투영 트랜스 폼이란」을 참조할것.


투영 트랜스 폼이란

투영 행렬이란, 일반적으로, 스케일링 퍼스펙티브 투영이다. 투영 트랜스 폼에서는 시추대를 입방체에 트랜스 폼 한다. 시추대의 가까이의 구석은 먼 구석보다 작기 때문에, 이 트랜스 폼에는 카메라의 가까이의 오브젝트를 확대한다고 하는 효과가 있어, 이것에 의해 장면에 원근감이 태어난다.

시추대에서는, 투영 트랜스 폼에 필요한 카메라와 뷰 트랜스 폼에 의해 정의되는 공간의 원점의 사이의 거리가,D 로서 정의된다. 퍼스펙티브 투영을 정의하는 행렬에서는, 다음과 같이, 최초로 이 변수 D 를 사용한다.

뷰 행렬은, 카메라를 장면의 원점에 배치한다. 투영 행렬에서는 (0, 0, -D)에 카메라를 배치할 필요가 있으므로, 투영 행렬은 다음의 행렬을 사용해 벡터를 z 방향으로 -D 만 평행이동 한다.

이것들 2 개의 행렬을 곱셈 하면, 다음과 같은 합성 행렬이 생긴다.

다음의 그림은, 퍼스펙티브 트랜스 폼이 시추대를 새로운 좌표 공간으로 변환하는 방법을 나타내고 있다. 시추대가 입방체가 되는 것, 및 장면의 우상각에 있던 원점이 중심으로 이동하는 것에 주목한다.

퍼스펙티브 트랜스 폼에서는, x 방향과 y 방향의 한계는 -1 과 1 이다. z 방향의 한계는, 전방면 도착해 0 으로, 후방면에 대해서는 1 이다.

이 행렬은, 카메라로부터 전방의 클립면까지의 거리에 근거해 오브젝트를 평행이동 및 스케일링 한다. 그러나, 이 행렬은 시야 (FOV)를 고려하지 않고, 먼 오브젝트에 대해서 생성하는 z 값은 거의 같아서, 깊이 비교가 곤란하게 된다. 이 문제를 해결하기 위해서, 다음의 행렬은, 뷰 포토의 어스펙트비(가로세로 비율)을 고려해 버텍스를 조정해, 어스펙트비(가로세로 비율)을 퍼스펙티브 투영에 맞춘다.

이 행렬에서는,Zn 는 전방의 클립면의 z 값이다. 변수 w,h, 및 Q 의 의미는, 다음과 같다. FOVw 및 FOVh 는, 뷰 포토의 수평 방향 및 수직 방향의 시야를 나타낸다 (라디안 단위).

어플리케이션에서는, 시야 각도를 사용해 x 와 y 의 배율을 정의하는 것은, 뷰 포토의 수평 치수와 수직 치수 (카메라 공간의 것)를 사용하는데 비교해 불편한 경우가 있다. 수학의 연습 문제로서 다음에 나타내는 w 와 h 용의 2 개의 식에서는 뷰 포토의 치수를 사용하고 있다. 이러한 식은 위에의 공식과 동등하다.

이러한 식에서는,Zn 는 전방의 클립면의 위치 좌표를 나타내, 변수 Vw 와 Vh 는 카메라 공간에서의 뷰 포토의 폭과 높이를 나타내고 있다.

C++ 어플리케이션에서는, 폭과 높이의 치수는,D3DVIEWPORT8 구조체의 Width 및 Height 멤버에 직접 대응한다.

어느 식을 사용하는 경우에서도,Zn 를 가능한 한 큰 값으로 설정하는 것이 중요하다. 이유는, 카메라에 극단적으로 가까운 z 값은 큰폭으로는 변화하지 않기 때문에이다. 이것에 의해, 16 비트의 z 버퍼를 사용하는 깊이 비교는 약간 복잡하게 된다.

월드 트랜스 폼 및 뷰 트랜스 폼과 같이,IDirect3DDevice8::SetTransform 메소드를 호출해 투영 트랜스 폼을 설정한다. 상세한 것에 대하여는, 「트랜스 폼의 설정」을 참조할것.


투영 행렬의 설정

C++ 로 기술된, 다음의 ProjectionMatrix 샘플 함수는, 수평 및 수직 시야의 각도 외에, 전방 및 후방 클립면을 설정하는 4 개의 입력 파라미터를 받는다. 이 코드는, 「투영 트랜스 폼이란」으로 가리키는 코드 와 유사한다. 시야는 pi 라디안 미만으로 할 필요가 있다.

D3DMATRIX
ProjectionMatrix(const float near_plane, // 가까이의 클립면까지의
                                         // 거리
                 const float far_plane,  // 먼 클립면까지의
                                         // 거리
                 const float fov_horiz,  // 수평 방향의 시야의
                                         // 각도 (라디안 단위).
                 const float fov_vert)   // 수직 방향의 시야의
                                         // 각도 (라디안 단위).
{
    float    h, w, Q;

    w = (float) 1/tan(fov_horiz*0. 5);  // 1/tan(x) == cot(x)
    h = (float) 1/tan(fov_vert*0. 5);   // 1/tan(x) == cot(x)
    Q = far_plane/(far_plane - near_plane);

    D3DMATRIX ret;
    ZeroMemory(&ret, sizeof(ret));

    ret(0, 0) = w;
    ret(1, 1) = h;
    ret(2, 2) = Q;
    ret(3, 2) = -Q*near_plane;
    ret(2, 3) = 1;
    return ret;
}   // ProjectionMatrix 의 최후.

행렬을 생성 한 후는,IDirect3DDevice8::SetTransform 메소드를 호출해 그 행렬을 설정해, 제 1 파라미터에 D3DTRANSFORMSTATE_PROJECTION 를 지정할 필요가 있다. 상세한 것에 대하여는, 「트랜스 폼의 설정」을 참조할것.

다만, Direct3DX 유틸리티 라이브러리에는, 투영 행렬을 설정하는 다음의 함수가 준비되어 있다.

  • D3DXMatrixPerspectiveLH
  • D3DXMatrixPerspectiveRH
  • D3DXMatrixPerspectiveFovLH
  • D3DXMatrixPerspectiveFovRH
  • D3DXMatrixPerspectiveOffCenterLH
  • D3DXMatrixPerspectiveOffCenterRH


W 버퍼에 유효한 투영 행렬

Microsoft® Direct3D® 에서는, 월드 행렬, 뷰 행렬, 및 투영 행렬에 의해 트랜스 폼 된 버텍스의 W 요소를 이용해, 깊이 버퍼 또는 fog 이펙트의 계산을 깊이를 베이스로 실행할 수 있다. 이러한 계산에서는, 투영 행렬에 의해 W 를 월드 공간 Z 로 대응하는 W 에 정규화할 필요가 있다. 즉, 투영 행렬에 1 이 아닌 (3,4) 계수가 포함되는 경우, (3,4) 계수의 역수를 사용해 모든 계수를 스케일링 하는 것으로, 적절한 행렬을 생성 해야 한다. 대응하고 있지 않는 행렬을 사용 하면, fog 이펙트와 깊이 버퍼가 올바르게 적용되지 않는다. 투영 트랜스 폼과는으로 추천 하는 투영 행렬은,w 베이스의 계산에 대응하고 있다.

다음의 그림은, 대응하고 있지 않는 투영 행렬, 및 같은 행렬을 스케일링 해 시점과의 상대 fog가 유효하게 되도록(듯이) 한 행렬을 나타내고 있다.

위에의도에서는, 모든 변수가 제로 이외의 값이다고 한다. 시점과의 상대 fog의 상세한 것에 대하여는, 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것. w 베이스의 깊이 버퍼링에 대해서는, 「깊이 버퍼란」을 참조할것.

주 Direct3D 에서는, 현재 설정되어 있는 투영 행렬이 w 베이스의 심도계산에 사용된다. 따라서, 어플리케이션으로 Direct3D 트랜스 폼 파이프라인을 사용하지 않는 경우여도, 희망의 w 베이스 기능을 취득하기 위해서 적절한 투영 행렬을 설정해 둘 필요가 있다.


라이팅 엔진

여기에서는, Microsoft® Direct3D® 라이팅 엔진의 개요에 대해 설명한다. 설명하는 주제는, 다음과 같다

  • 라이팅 엔진의 유효/무효
  • 라이트의 칼라 타입과 소스
  • fog 이펙트

라이팅 엔진의 내부 동작의 상세한 것에 대하여는, 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.


라이팅 엔진의 유효/무효

디폴트에서는, Microsoft® Direct3D® 는, 모든 버텍스에 대해서 라이팅 계산을 실행한다. 이 계산은, 버텍스 법선을 가지지 않는 버텍스에 대해서도 실행되는 구릴리스의 Microsoft DirectX® 에서는, 버텍스 법선을 가지는 버텍스 에 대해서만 라이팅이 실행되었다. 다만,D3DRS_LIGHTING 렌더링 스테이트를 사용해 라이팅을 무효로 할 수 있다. IDirect3DDevice8::SetRenderState 메소드를 호출해, 제 1 파라미터로서 D3DRS_LIGHTING 를 건네주어, 제 2 파라미터로서 TRUE 또는 FALSE 를 건네준다. 스테이트를 TRUE 로 설정 하면 라이팅이 유효하게 되어 (디폴트), FALSE 를 설정 하면 무효가 된다.


라이트의 칼라 타입과 소스

Microsoft® Direct3D® 의 광원은, 서로 독립해 라이팅 계산의 계수로서 일하는 개개의 라이팅 컴퍼넌트로서 디퓨즈색, 앰비언트색, 및 스펙큐러색을 발한다. 같이 시스템이 렌더링 하는 버텍스는, 그 버텍스 포맷에 의해 정의된 개별의 디퓨즈색, 앰비언트색, 스펙큐러색, 및 에미션(emission)색을 사용한다.

C++ 어플리케이션의 경우, 이러한 버텍스 칼라는,D3DRS_COLORVERTEX 렌더링 스테이트를 TRUE 로 설정했을 때에 마셔, 시스템에 의해 사용된다. 버텍스 칼라 소스는 선택 가능하다. 즉, 실행시에 라이팅식의 버텍스 칼라 부분의 소스를 선택하도록(듯이) 설정할 수 있다. D3DRS_AMBIENTMATERIALSOURCE ,D3DRS_DIFFUSEMATERIALSOURCE , 및 D3DRS_SPECULARMATERIALSOURCE 렌더링 스테이트는, 라이팅 계산 시에 시스템이 드로잉(Drawing) 하는 색의 칼라 소스를 제어한다. 각 렌더링 스테이트는,D3DMATERIALCOLORSOURCE 열거형의 멤버로 설정할 수 있다. 이것은, 칼라 소스로서 현재의 머트리얼을 사용하는지, 또는 버텍스의 색을 사용하는지를 지정하는 값을 정의한다.


fog 이펙트

Microsoft® Direct3D® 의 트랜스 폼 & 라이팅 엔진에서는, 라이팅중에 fog 이펙트를 생성 할 수 있다. 이러한 fog는, fog 정보가, 라스터화 되는 버텍스의 알파 성분에 배치되는 것으로부터, 보통은 버텍스 fog로 불린다.

상세한 것에 대하여는, 「fog」 및 「버텍스 fog」를 참조할것.


Direct3D 의 라이팅에 있어서의 수학적 계산

여기에서는, Microsoft® Direct3D® 라이팅 엔진의 구조 및 이행의 상세를 설명한다. Direct3D 는, 자연광의 행동을 평가해 라이팅을 모델화한다. Direct3D 라이팅 모델은, 라이트의 색, 라이트의 진행 방향과 거리, 뷰아의 위치 좌표, 및 머트리얼의 특성을 감시해, 면의 각 버텍스로써 2 개의 색성분을 계산한다. Direct3D 는, 이러한 색성분을 사용해, 면의 픽셀을 라스터화할 때 드로잉(Drawing) 하는 색을 계산한다.

주 모든 계산은 모델 공간에서 행해진다. 월드 행렬의 역행열을 사용해 카메라 위치 좌표와 함께 라이트의 위치 좌표와 방향을 모델 공간에 트랜스 폼 해, 다음에 역트랜스 폼 한다. 그 결과, 월드 행렬 또는 뷰 행렬에 의해 한결같지 않은 스케일링이 생기는 경우는, 최종적인 라이팅이 부정확하게 되는 일이 있다.

여기에서는, 디퓨즈 성분과 스펙큐러 성분을 제공하기 위해서 Direct3D 로 사용하는 공식으로 붙어 기술적 관점으로부터 설명한다. Direct3D 방법을 이해하면, Direct3D 라이팅 모델이 요망에 맞을지 어떨지를 보다 정확하게 판단할 수 있게 된다. Direct3D 라이팅 모델은, 정확함, 효율성, 및 편리한 사용을 목표로 해 설계되고 있다. 그러나, Direct3D 로 사용하는 공식이 요구에 맞지 않는 경우는, Direct3D 라이팅 모듈은 사용하지 않고, 독자적인 라이팅 모델을 이행 할 수도 있다. 설명하는 주제는, 다음과 같다

  • 라이팅 표기
  • 카메라 공간 트랜스 폼
  • 기본적인 라이팅 공식
  • 디퓨즈 공식
  • 스펙큐러 공식
  • 거리의 증가에 의한 라이트의 감쇠
  • 반사율 모델
  • spotlight 폴 오프 모델

이 공식에서 사용되는 파라미터를, 다음 표에 나타낸다. 각 표에는, 대응하는 디폴트값, 형태, 및 허용값의 범위를 나타낸다.

다음의 표는, 위치 파라미터를 나타내고 있다.

파라미터 | 디폴트값 | 형 | 설명
Pe | (0,0,0) | D3DVECTOR | 카메라 공간에서의 카메라의 위치 좌표.
Po | N/A | D3DVECTOR | 카메라 공간에 있어서의 현재의 모델 원점 (0,0,0,1)의 위치. 이것은 Mw*Mv 행렬의 4 행 째이다.
Mw | N/A | D3DMATRIX | D3DTRANSFORMSTATE_VIEW 에 의해 설정되는 월드 행렬.
Mv | N/A | D3DMATRIX | D3DTRANSFORMSTATE_VIEW 에 의해 설정되는 뷰 행렬.
Mwv | N/A | D3DMATRIX | Mw*Mv.
Halfway | N/A | D3DVECTOR | 정규화된 벡터. 스펙큐러 반사를 계산하기 위해서 사용된다.
La | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | 라이트 스테이트의 앰비언트색. D3DRENDERSTATE_AMBIENT 에 의해 설정된다.
V | N/A | D3DVECTOR | 카메라 공간에서의 버텍스의 위치 좌표.
N | N/A | D3DVECTOR | 카메라 공간에서의 정규화된 버텍스의 법선.
Vcd | N/A | D3DCOLORVALUE | 버텍스의 디퓨즈색.
Vcs | N/A | D3DCOLORVALUE | 버텍스의 스펙큐러색.

다음의 표는, 머트리얼 파라미터를 나타내고 있다.

파라미터 | 디폴트값 | 형 | 설명
Ma | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | 앰비언트색.
Md | (255, 255, 255, 255) | D3DCOLORVALUE | 디퓨즈색.
Ms | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | 스펙큐러색.
Me | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | 에미션(emission)색.
Mp | 0.0 | D3DVALUE | 스펙큐러 지수. 범위 : (-∞, +∞)

다음의 표는, 광원 i 파라미터를 나타내고 있다.

파라미터 | 디폴트값 | 형 | 설명
LpI | (0.0, 0.0, 0.0) | D3DVECTOR | 카메라 공간에서의 위치 좌표.
LdI | (0.0, 0.0, 1.0) | D3DVECTOR | 카메라 공간에서의 라이트에게로의 방향.
LrI | 0.0 | D3DVALUE | 거리의 범위. 범위 : [0.0, D3DLIGHT_RANGE_MAX].
LcaI | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | 앰비언트색.
LcsI | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | 스펙큐러색.
LcI | (1.0, 1.0, 1.0, 0.0) | D3DCOLORVALUE | 디퓨즈색.
att0I | 0.0 | D3DVALUE | 고정 감쇠 계수. 범위 : (0, +∞)
att1I | 0.0 | D3DVALUE | 선형 감쇠 계수. 범위 : (0, +∞)
att2I | 0.0 | D3DVALUE | 2 차 감쇠 계수. 범위 : (0, +∞)
falloffI | 0.0 | D3DVALUE | 폴 오프 계수. 범위 : (-∞, +∞)
thetaI | 0.0 | D3DVALUE | spotlight의 본영 각도 (라디안 단위). 범위 : [0, π)
phiI | 0.0 | D3DVALUE | spotlight의 반영 각도 (라디안 단위). 범위 : [thetaI, π).


라이팅 표기

라이팅 공식에서는 다음 표기를 사용한다.

D3DCOLORVALUE 컴퍼넌트의 범위는 (-∞, +∞)이다.

· - 내적은 d1 · d2 = max{d1·d2, 0} 으로서 정의된다.

norm(P) - 단위벡터, 또는 벡터의 정규화

V1V2 - 포인트 V1 으로부터 포인트 V2 에의 벡터

M-1- 역행열

MT- 전치행렬

V1 / V2. V1 및 V2 는 D3DVECTOR 형이다. 이 형태는 벡터 (V1.x / V2.x, V1.y / V2.y , V1.z / V2.z)와 동등하다.

V1 * V2. V1 및 V2 는 D3DVECTOR 형이다. 이 형태는 벡터 (V1.x * V2.x, V1.y * V2.y , V1.z * V2.z)와 동등하다.


카메라 공간 트랜스 폼

카메라 공간의 버텍스는, 오브젝트의 버텍스에 Mwv 행렬을 곱셈하는 것에 의해 계산된다.

v = Vobject * Mwv

카메라 공간의 법선은, 오브젝트의 법선에 역전치행렬 Mwv 를 곱셈해, 그 결과를 정규화하는 것에 의해 계산된다.

N = Nobject * (Mwv-1)T

D3DRENDERSTATE_NORMALIZENORMALS 가 TRUE 로 설정되어 있는 경우, 법선은 카메라 공간에의 트랜스 폼의 뒤, 정규화된다.

N = norm(N)

카메라 공간에서의 라이트의 위치 좌표 (Lpi)는, 광원의 위치 좌표에 Mv 를 곱셈하는 것에 의해 계산된다.

Lpi = Lporiginal * Mv

D3DLIGHT_DIRECTIONAL 라이트의 카메라 공간에서의 라이트에게로의 방향은, 광원의 위치 좌표에 Mv 행렬을 곱셈해, 그 결과를 정규화해 부정하는 것에 의해 계산된다.

Ldi = -norm(Ldi original * Mv)

D3DLIGHT_POINT 및 D3DLIGHT_SPOT 의 경우는, 라이트에게로의 방향은 다음과 같이 계산된다.

Ldi = norm(VLpi)


기본적인 라이팅 공식

라이팅 스테이지의 출력은, RGBA 포맷에서의 디퓨즈 (D) 색 및 스펙큐러 (s) 색이다. 라이팅은 다음의 2 개의 스테이트의 언젠가이다.

1. 라이팅 오프 (D3DRENDERSTATE_LIGHTING 가 FALSE 로 설정되어 있다). 이 스테이트에서는, 버텍스 칼라는 다음과 같이 계산된다.

D3DRENDERSTATE_COLORVETEX 는 무시된다.

디퓨즈 버텍스 칼라가 존재하는 경우, 출력 디퓨즈색은 버텍스의 디퓨즈색에 동일하다. 그 이외의 경우는, 디퓨즈색은 디폴트의 디퓨즈색 (255,255,255,255)에 동일하다. 출력 디퓨즈색은 [0, 255] 의 범위에 스케일링 및 클램프 된다.

스펙큐러 버텍스 칼라가 존재하는 경우, 출력 스펙큐러색은 버텍스의 스펙큐러색에 동일하다. 그 이외의 경우는, 스펙큐러색은 디폴트의 스펙큐러색 (0,0,0,0)에 동일하다. 출력 스펙큐러색은 [0, 255] 의 범위에 스케일링 및 클램프 된다.

2. 라이팅 온 (D3DRENDERSTATE_LIGHTING 가 TRUE 로 설정되어 있다). 이 스테이트에서는, Direct3D 는 이하의 공식으로 따라서 버텍스 칼라를 계산한다.

버텍스에 법선이 존재하지 않는 경우, 라이팅의 식에서 내적에 의존하는 부분은 0 으로 설정된다. 라이팅이 계산된다.

라이팅이 카메라 공간에서 행해진다.

alpha 성분은 다음의 라이팅의 식에서는 사용되지 않는다.


디퓨즈 공식

여기에서는, 디퓨즈 라이팅의 공식으로 대해 설명한다.

D3DRENDERSTATE_SPECULARENABLE 가 FALSE 로 설정되어 있는 경우, 스펙큐러 성분은 (0, 0, 0, 0)으로 설정된다. 그 이외의 경우는, 다음과 같이 계산된다.

여기서


스펙큐러 공식

여기에서는, 스펙큐러 라이팅의 공식으로 대해 설명한다.

hi 는 법선과 라이트에게로의 방향의 사이의 중간 벡터이다.

hi = norm(norm(Vpe) + Ldi)). D3DRENDERSTATE_LOCALVIEWER = TRUE 의 경우

hi = norm((0,0,-1) + Ldi)). D3DRENDERSTATE_LOCALVIEWER = FALSE 의 경우

rhoi = norm(Ldi) • norm(VLpi)

di 는 버텍스로부터 라이트 i 까지의 거리로, 다음과 같이 계산된다.

모든 라이트가 처리되어 개별적으로 보간 된 후, 디퓨즈 성분 및 스펙큐러 성분은 0 ~ 255 에 클램프 된다.


거리의 증가에 의한 라이트의 감쇠

Microsoft® Direct3D® 에서는, 라이트로 비추어진 버텍스와 광원의 사이의 거리를, 라이트의 위치 좌표와 버텍스의 사이의 벡터의 매그니튜드에 의해 결정한다. 이것을 다음의 공식에서 나타낸다.

이 공식에서는,D 는 계산하는 거리,V 는 라이트로 비추어진 버텍스의 위치 좌표,L 는 광원의 위치 좌표이다. D 가 라이트의 범위 (즉,D3DLIGHT8 구조체의 Range 멤버)보다 큰 경우, Direct3D 는 그 이상 감쇠 계산을 실행하지 않고, 라이팅 이펙트를 버텍스에 적용하지 않게 된다. 거리가 라이팅의 범위내에 있는 경우는, Direct3D 는 이하의 공식을 적용해, 거리의 증가에 수반하는 포인트 라이트 및 spotlight의 라이트의 감쇠를 계산한다. 디레크쇼나르라이트는 감쇠하지 않는다.

이 감쇠 공식에서는,A 는 계산한 전감쇠,D 는 광원으로부터 버텍스까지의 거리이다. dvAttenuation0,dvAttenuation1, 및 dvAttenuation2 의 값은, 라이트 오브젝트의 D3DLIGHT8 구조체의 멤버에 의해 지정되는, 라이트의 감쇠 정수이다. 대응하는 멤버는 각각,Attenuation0,Attenuation1, 및 Attenuation2 이다.

감쇠 정수는 공식에서는 계수가 된다. 이러한 계수에 간단한 조정을 더하는 것으로, 다양한 감쇠 커브를 생성할 수 있다. Attenuation0 를 1.0 으로 설정해, 감쇠하지 않는 빛을 생성 할 수 있다 (다만, 범위에 의한 제한이 있다). 또, 여러가지 값을 시험해 봐, 다양한 감쇠 이펙트를 낼 수가 있다.

라이팅의 최대 범위에 있어서의 감쇠는 0.0 은 아니다. 라이팅의 범위내에서 라이팅이 돌연 나타나는 것을 방지하기 위해서, 어플리케이션에서는 라이팅의 범위를 늘릴 수가 있다. 또, 어플리케이션으로, 라이팅 범위에 있어서의 감쇠 계수가 0.0 에 가까워지도록(듯이) 감쇠 정수를 설정할 수 있다. 감쇠값을 라이팅의 색의 적, 초록, 및 파랑 성분으로 곱셈해, 라이팅의 강도를 빛이 버텍스까지 진행되는 거리의 계수로서 정할 수가 있다.

라이팅 감쇠를 계산한 후, Direct3D 에서는, spotlight 이펙트 (적용하는 경우), 표면으로부터의 빛의 반사 각도, 및 현재의 머트리얼의 반사율을 고려해, 그 버텍스에 대한 디퓨즈 성분과 스펙큐러 성분을 산출한다. 상세한 것에 대하여는, 「spotlight 폴 오프 모델」 및 「반사율 모델」을 참조할것.


반사율 모델

모든 감쇠 이펙트로 라이팅 강도를 조정한 후, Microsoft® Direct3D® 에서는 버텍스 법선과 입사빛의 방향의 각도를 가정해, 버텍스로부터 반사하는 잔광의 양을 계산한다. 디레크쇼나르라이트에서는 이 순서는 실행되지 않는다. 거리가 증가해도 빛이 감쇠하지 않기 때문이다.

Direct3D 에서는 디퓨즈와 스펙큐러의 2 종류의 반사를 고려해, 다른 공식을 사용해 각 라이팅으로 반사하는 빛의 양을 결정한다. 반사하는 라이팅의 양을 계산한 후, Direct3D 는 이러한 새로운 값을, 현재의 머트리얼의 디퓨즈 반사율 프로퍼티와 스펙큐러 반사율 프로퍼티에 적용한다. 이 결과적으로 생기는 칼라값은, gouraud shading와 스펙큐러 하이라이트 생성을 위해서(때문에) 래스터라이저가 사용하는 디퓨즈 성분과 스펙큐러 성분이다.

디퓨즈 반사 모델

Microsoft Direct3D 에서는, 다음의 공식을 사용해 디퓨즈 반사 계수를 계산한다.

이 공식에서는,Rd 는 디퓨즈 반사 계수,D 는 라이트가 버텍스로 향할 방향,N 는 버텍스 법선이다. 벡터 D 는 정규화된다. 벡터 N 는,D3DRS_NORMALIZENORMALS 렌더링 스테이트가 유효하게 되어 있는 경우에게만 정규화된다. 라이팅의 방향 벡터에 -1 를 곱해 역벡터로 해, 방향 벡터와 버텍스 법선의 사이의 적정한 관계부를 생성 한다. 이 공식의 결과는 -1. 0 ~ 1.0 의 범위의 값이다. 이 값은 0.0 ~ 1.0 의 범위에 제한되어 버텍스로부터 반사되는 라이팅의 강도를 조정하기 위해서 사용된다.

디퓨즈 반사 계수를 계산한 다음에, 그 결과를 다음과 같은 디퓨즈 반사 공식으로 적용해, 그 버텍스에 있어서의 디퓨즈 성분이 결정된다. 다음의 공식은, 앰비언트 반사와 디퓨즈 반사를 조합해 버텍스에 있어서의 디퓨즈 성분을 생성 한다.

이 공식에서는,Dv 는 버텍스에 대해서 계산되는 디퓨즈 성분,Ia 는 장면내의 앰비언트 라이트, 및 A 는 거리와 spotlight 이펙트를 위해서(때문에) 감쇠한 광원의 라이팅 강도 (spotlight 폴 오프 모델로 곱셈된,거리의 증가에 의한 라이트의 감쇠)이다. 변수 L 는 라이팅의 프로퍼티를 나타내,V 엔트리는 버텍스 칼라를 나타낸다. 여기서, 각각 적용되고 있는 첨자 a,d, 및 e 는, 색의 종류의 앰비언트 (ambient), 디퓨즈 (diffuse), 또는 에미션(emission) (emissive)를 나타낸다. 공식에서 가리키도록(듯이), 우선 IaVa + Ve 가 계산되어 모든 액티브한 라이팅의 A(RdVdLd + VaLa) 가 가산된다.

D3DRS_COLORVERTEX 렌더링 스테이트가 유효하게 되어 있는 경우,D3DRS_AMBIENTMATERIALSOURCE 및 D3DRS_DIFFUSEMATERIALSOURCE 렌더링 스테이트로 설정된 값에 근거해 V 의 색이 선택된다. 이러한 렌더링 스테이트를 D3DMATERIALCOLORSOURCE 열거형의 멤버로 설정해, 현재의 머트리얼인가, 버텍스의 색을 칼라 소스로서 사용한다.

상세한 것에 대하여는, 「스펙큐러 반사 모델」을 참조할것.

스펙큐러 반사 모델

스펙큐러 반사를 모델화하려면 , 빛의 진행 방향 뿐만이 아니라, 시점으로부터의 시선의 방향도 시스템에 알릴 필요가 있다. 시스템에서는 Phong 스펙큐러 반사 모델의 간이 버젼을 사용한다. 이 모델에서는,중간 벡터를 사용해 스펙큐러 반사 강도를 개산 한다. 중간 벡터는, 광원에의 벡터와 시점에의 벡터의 사이의 중간에 존재한다. Microsoft Direct3D 에서는, 어플리케이션은,D3DRS_LOCALVIEWER 렌더링 스테이트에서 제어하는 2 종류의 방법을 사용해 중간 벡터를 계산할 수 있다. D3DRS_LOCALVIEWER 를 TRUE 로 설정 하면, 시스템에서는 라이팅의 방향 벡터에 가세해, 카메라의 위치 좌표와 버텍스의 위치 좌표를 사용해 중간 벡터를 계산한다. 다음의 공식은 이 계산을 나타낸다.

이 공식에서는,norm 는 입력 벡터를 정규화하는 연산자,VC 는 위치 좌표로부터 시점 또는 눈의 위치 좌표에의 벡터,Ld 는 라이팅의 방향 벡터이다.

이 방법으로 중간 벡터를 결정하는 경우는, 계산 부하가 커지는 일이 있다. 이 대신에, D3DRS_LOCALVIEWER 를 FALSE 로 설정할 수도 있다. 이 경우, z 축의 무한 먼 곳에 시점이 존재 하면 해 처리된다. 이 설정은 계산 부하는 적지만, 정확함으로 뒤떨어진다. 따라서, 이 방법은, 정사영을 사용하는 어플리케이션에 최적이다. D3DRS_LOCALVIEWER 를 FALSE 로 설정했을 경우, Direct3D 에서는 다음의 공식을 사용해 중간 벡터를 계산한다.

이 공식은 최초의 공식으로 유사하고 있지만, 벡터 VC 를 계산하는 대신에, z 축위에의 무한 먼 곳에 있는 시점을 나타내는 벡터 I (0, 0, -1)를 사용하고 있다.

중간 벡터 H 를 요구한 후, 시스템은 다음의 공식을 사용해 스펙큐러 반사를 계산한다.

이 공식에서는,Rs 는 스펙큐러 반사율,N 는 버텍스 법선,H 는 중간 벡터,p 는 현재의 머트리얼의 스펙큐러 반사 강도 (머트리얼의 D3DMATERIAL8 구조체의 Power 멤버로 지정)이다. 벡터 H 는 정규화된다. 벡터 N 는,D3DRS_NORMALIZENORMALS 렌더링 스테이트가 유효하게 되어 있는 경우에게만 정규화된다.

디퓨즈 반사 공식과 같이, 이 공식의 결과는 -1. 0 ~ 1.0 의 범위의 값이며, 이 값은 0.0 ~ 1.0 의 범위에 제한되어 버텍스로부터 반사되는 라이팅을 계산하기 위해서 사용된다. 또, 디퓨즈 반사 모델과 같이, 그 버텍스에 있어서의 스펙큐러 성분을 요구하는 공식으로 그 결과가 적용된다.

이 공식에서는,Sv 는 계산되는 스펙큐러색이다. A 는, 거리 및 spotlight 이펙트를 위해서(때문에) 감쇠한 단일의 광원으로부터의 라이트이다. 상세한 것에 대하여는, 「거리의 증가에 의한 라이트의 감쇠」 및 「spotlight 폴 오프 모델」을 참조할것. 변수 Rs 는 이전에 계산된 스펙큐러 반사율,Vs 는 버텍스의 스펙큐러 성분,Ls 는 스펙큐러 라이트의 색이다.

D3DRS_COLORVERTEX 렌더링 스테이트가 유효하게 되어 있는 경우,D3DRS_SPECULARMATERIALSOURCE 렌더링 스테이트의 값에 근거해 V 의 칼라 소스가 선택된다. 이 렌더링 스테이트를 D3DMATERIALCOLORSOURCE 열거형의 멤버로 설정해, 현재의 머트리얼인가, 버텍스의 색성분의 어느쪽이든을 칼라 소스로서 사용할 수 있다.

상세한 것에 대하여는, 「디퓨즈 반사 모델」을 참조할것.


spotlight 폴 오프 모델

spotlight는, 밝은 내부 콘 및 외부 콘의 2 개의 부분을 가지는 빛의 콘을 방사한다. 라이팅은, 내부 콘의 안쪽이 가장 밝고, 외부 콘의 외측에는 라이팅이 존재하지 않는다. 라이팅의 강도는, 이 2 개의 영역의 사이에 감쇠한다. 일반적으로, 이러한 감쇠를폴 오프라고 부른다.

버텍스를 비추는 빛의 양은, 버텍스가 내부 콘의 안쪽에 있는지, 외부 콘의 안쪽에 있을까에 따라서 다르다. Microsoft® Direct3D® 는, spotlight의 방향 벡터 (L)와 버텍스로부터 spotlight에의 벡터 (D)의 내적을 계산한다. 이 값은, 2 개의 벡터가 이루는 각도의 코사인에 동일하고, 라이팅의 콘 각도와 비교할 수 있는 버텍스 위치 좌표를 나타내므로, 내부 콘 또는 외부 콘의 어느 쪽으로 버텍스가 있을까를 판단하는데 도움이 된다. 다음의 그림은, 이것들 2 개의 벡터의 사이의 관계를 나타내고 있다.

시스템은, 이 값을 spotlight의 내부 및 외부 콘의 각도의 코사인과 비교한다. spotlight의 D3DLIGHT8 구조체의 Theta 및 Phi 멤버는, 내부 및 외부 콘의 각도의 합계를 나타낸다. 감쇠는, 전콘 각도에 걸쳐서는 아니고, 라이팅의 중심으로부터 버텍스가 떨어지는 것에 의해 생기기 (위해)때문에, Direct3D 는 콘 각도를 반으로 나누고 나서 코사인을 계산한다.

벡터 L 와 D 의 내적이 외부 콘의 각도의 코사인 이하의 경우, 버텍스는 외부 콘의 외측에 존재해, 라이팅으로 비추어지지 않다. L 와 D 의 내적이 내부 콘 각도의 코사인보다 큰 경우, 버텍스는 내부 콘의 안쪽에 존재해, 최대량의 라이팅으로 비추어진다 (다만, 거리의 증가에 의한 감쇠를 고려한다). 버텍스가 2 개의 영역의 사이에 있는 경우, Direct3D 는 다음의 공식을 사용해 버텍스에 있어서의 라이팅의 폴 오프를 계산한다.

이 공식에서는,If 는 라이팅이 맞는 버텍스에 있어서의 폴 오프 후의 빛의 강도, a 는 벡터 L 와 D 가 이루는 각도,f 는 외부 콘의 각도의 반의 각도, q 는 내부 콘의 각도의 반의 각도,p 는 spotlight의 폴 오프 프로퍼티 (D3DLIGHT8 구조체의 Falloff)이다. 이 공식에서는, 버텍스에 있어서의 빛의 강도를 정하는 0.0 ~ 1.0 의 값을 요구해, 라이트의 폴 오프를 나타낸다. 라이팅으로부터 버텍스까지의 거리의 계수로서 감쇠도 적용된다. p 값은,D3DLIGHT8 구조체의 Falloff 멤버에 대응해, 폴 오프 커브의 형상을 제어한다. 다음의 그림은,Falloff 값에 의해 폴 오프 커브가 어떻게 변화하는지를 나타내고 있다.

Falloff 값이 변화해도 실제의 라이팅에게 주는 영향은 적어,Falloff 값이 1.0 이외 때에 형성되는 폴 오프 커브로 약간의 퍼포먼스 저하가 생길 뿐이다. 이러한 이유에 의해, 보통, 이 값은 1.0 으로 설정된다.

상세한 것에 대하여는, 「거리의 증가에 의한 라이트의 감쇠」를 참조할것.


뷰 포토와 클리핑

여기에서는, 지오메트리 파이프라인의 마지막 단계의 클리핑에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 뷰 포토란
  • 뷰 포토 직사각형
  • 클리핑 볼륨
  • 뷰 포토의 스케일링
  • 뷰 포토의 사용법

Microsoft® Direct3D® 에서는, 뷰 포토 파라미터세트를 사용하는 것으로, 디바이스에 클리핑을 이행 한다.


뷰 포토란

개념상, 뷰 포토와는 3D 신이 투영 되는 2D 직사각형이다. Microsoft® Direct3D® 의 경우, 이 직사각형은, 렌더링 타겟으로서 사용되는 Direct3D 표면내의 좌표로서 존재한다. 투영 트랜스 폼은, 뷰 포토에 사용되는 좌표계에 버텍스를 트랜스 폼 한다.

Direct3D 로 뷰 포토를 사용해, 어플리케이션으로 다음의 기능을 지정한다.

  • 렌더링이 한정되는 스크린 공간 뷰 포토
  • 장면이 렌더링 되는 렌더링 타겟 표면의 깊이값의 범위 (보통은 0.0 ~ 1.0)


뷰 포토 직사각형

C++ 의 뷰 포토 직사각형은,D3DVIEWPORT8 구조체를 사용해 정의한다. D3DVIEWPORT8 구조체는,IDirect3DDevice8 인터페이스가 공개하는 다음의 뷰 포토 조작 메소드로 사용된다.

  • IDirect3DDevice8::GetViewport
  • IDirect3DDevice8::SetViewport

D3DVIEWPORT8 구조체에는 X,Y,Width, 및 Height 의 4 개의 멤버가 있다. 이것들을 사용해, 장면이 렌더링 되는 렌더링 타겟 표면 영역을 정의한다. 이러한 값은, 다음의 그림에 나타내도록(듯이), 전송처의 직사각형, 즉 뷰 포토 직사각형에 대응한다.

D3DVIEWPORT8 구조체의 X,Y,Width, 및 Height 멤버로 지정하는 값은, 렌더링 타겟 표면의 맨 왼쪽 위쪽으로부터의 화면 좌표이다. 이 구조체는, 장면이 렌더링 되는 깊이 범위를 나타내는 2 개의 추가 멤버 MinZ 및 MaxZ 를 정의한다.

Microsoft® Direct3D® 에서는, 뷰 포토의 클리핑 볼륨의 범위는, X 방향에 대해서는 -1. 0 ~ 1.0, Y 방향에 대해서는 1.0 ~ -1. 0 으로 상정하고 있다. 이 값은, 과거의 어플리케이션으로 가장 자주(잘) 사용된 설정값이다. 투영 트랜스 폼때, 클리핑을 실시하기 전에 뷰 포토의 어스펙트비(가로세로 비율)을 조정할 수가 있다. 이 태스크에 대해서는, 「투영 트랜스 폼」으로 설명한다.

주 D3DVIEWPORT8 구조체의 MinZ 및 MaxZ 멤버는, 장면이 렌더링 되는 깊이 범위를 나타내, 클리핑에는 사용되지 않는다. 대부분의 어플리케이션에서는, 이 멤버를 0.0 으로 1.0 으로 설정해, 깊이 버퍼내의 깊이값의 전범위에 렌더링 하고 있다. 경우에 따라서는, 다른 깊이 범위를 사용해 특수 효과를 얻을 수도 있다. 예를 들어, 게임의 헤드 업 디스플레이를 렌더링 하는 경우, 양쪽 모두의 값을 0.0 으로 설정해 foreground의 장면내의 오브젝트를 강제적으로 렌더링 하거나 양쪽 모두의 값을 1.0 으로 설정해 항상 백그라운드에 존재할 필요가 있는 오브젝트를 렌더링 할 수 있다.


클리핑 볼륨

투영 행렬의 결과에 의해, 투영 공간에서의 클리핑 볼륨이 정해진다. Microsoft® Direct3D® 는, 다음과 같이 해, 투영 공간의 클리핑 볼륨을 정의한다.

이 식에서는,Xc,Yc,Zc, 및 Wc 는, 투영 트랜스 폼의 적용 후의 버텍스 좌표를 나타낸다. 클리핑이 유효한 경우 (디폴트 설정), 이러한 범위외에 x, y, 또는 z 요소를 가지는 버텍스가 클리핑 된다.

버텍스 버퍼를 제외해, 어플리케이션에서는,D3DRS_CLIPPING 렌더링 스테이트를 사용해 클리핑을 유효 또는 무효로 한다. 버텍스 버퍼의 클리핑 정보는 처리중에 생성된다. 상세한 것에 대하여는, 「버텍스의 처리」를 참조할것.

Direct3D 는 버텍스 버퍼의 프리미티브의 트랜스 폼 된 버텍스를 클리핑 하지 않는다. 다만,IDirect3DDevice8::ProcessVertices 에 의하는 것은 제외하다. 독자적인 트랜스 폼을 실행할 때에, Direct3D 로 클리핑을 실시할 필요가 있는 경우는, 버텍스 버퍼를 사용해서는 안된다. 이 경우, 어플리케이션이 데이터를 암벽 횡단 해 트랜스 폼 해, Direct3D 가 재차 데이터를 암벽 횡단 해 클리핑 한 후, 드라이버가 데이터를 렌더링 하므로, 효율적은 아니다. 따라서, 어플리케이션이 데이터를 트랜스 폼 하는 경우는, 데이터의 클리핑도 실시해야 하는 것이다.


뷰 포토의 스케일링

뷰 포토용의 D3DVIEWPORT8 구조체의 x,y,Width, 및 Height 멤버에 치수를 지정해, 렌더링 타겟 표면의 뷰 포토의 위치 좌표 및 크기를 정의한다. 이러한 값은, 렌더링 타겟 표면의 맨 왼쪽 위쪽으로부터의 화면 좌표이다.

Microsoft® Direct3D® 에서는, 뷰 포토의 위치 좌표와 치수를 사용해 버텍스를 스케일링 해, 렌더링 하는 장면을 타겟 표면 위에의 적절한 위치 좌표에 배치한다. 내부적으로는, Direct3D 는, 각 버텍스에 적용되는 행렬에 이러한 값을 삽입하고 있다.

이 행렬은, 뷰 포토의 치수 및 지정의 깊이 범위에 따라 버텍스를 스케일링 해, 그 버텍스를 렌더링 타겟 표면의 적절한 위치 좌표에 평행이동 한다. 또, 이 행렬은, y 가 하부에 증가하는 맨 왼쪽 위쪽의 스크린 원점을 반영하기 위해서 y 좌표를 반전한다. 이 행렬을 적용한 후도, 버텍스는 동차이다. 즉, 버텍스는 여전히 [x, y, z, w] 버텍스로서 존재하므로, 래스터라이저에 보내기 전에 버텍스를 비동차에 트랜스 폼 해야 한다. 이것은, 「라스터화」로 설명하도록(듯이), 단순한 나눗셈에 의해 실시한다.

주 뷰 포토 스케일링 행렬은, 버텍스를 스케일링 하는 D3DVIEWPORT8 구조체의 MinZ 및 MaxZ 멤버를 짜넣어 깊이 범위 [MinZ, MaxZ] 를 맞춘다. 이것은, 이러한 멤버가 클리핑에 사용되고 있던 구릴리스의 Microsoft DirectX 의 시멘틱스와는 다르다.

상세한 것에 대하여는, 「뷰 포토 직사각형」 및 「클리핑 볼륨」을 참조할것. 어플리케이션에서는, 보통,MinZ 및 MaxZ 를 각각 0.0 및 1.0 으로 설정해 깊이 범위 전체에의 렌더링을 실행한다. 다만, 다른 값을 설정해 어떠한 이펙트를 얻을 수도 있다. 양쪽 모두의 값을 0.0 으로 설정해 모든 오브젝트를 강제적으로 foreground에 렌더링 하거나 양쪽 모두의 값을 1.0 으로 설정해 모든 오브젝트를 백그라운드에 렌더링 할 수가 있다.


뷰 포토의 사용법

여기에서는, 뷰 포토의 조작에 대해 자세하게 설명한다. 설명하는 주제는, 다음과 같다.

  • 뷰 포토 클리핑 볼륨의 설정
  • 뷰 포토의 클리어
  • 버텍스의 메뉴얼 트랜스 폼


뷰 포토 클리핑 볼륨의 설정

렌더링 디바이스에 대해서 뷰 포토 파라미터를 설정하기 위한 조건은, 뷰 포토의 클리핑 볼륨을 설정하는 것 뿐이다. 이 때문에는, 클리핑 볼륨과 렌더링 타겟 표면용의 클리핑값을 초기화 및 설정한다. 뷰 포토는, 일반적으로는, 렌더링 타겟 표면의 전영역에 렌더링 하도록(듯이) 설정되지만, 반드시 그렇게 할 필요는 없다.

C++ 로 이것을 실현하려면 ,D3DVIEWPORT8 구조체의 멤버를 다음과 같이 설정한다.

D3DVIEWPORT8 viewData = { 0, 0, width, height, 0.0f, 1.0f };

D3DVIEWPORT8 구조체에 값을 설정한 후,IDirect3DDevice8::SetViewport 메소드를 호출해 디바이스에 뷰 포토 파라미터를 적용한다. 다음의 코드는, 이 호출을 나타내고 있다.

HRESULT hr;

hr = pd3dDevice->SetViewport(&viewData);
if(FAILED(hr))
    return hr;

이 호출이 성공하면(자), 뷰 포토 파라미터가 설정되어 다음번 렌더링 메소드를 호출했을 때에 이 뷰 포토 파라미터가 유효하게 된다. 뷰 포토 파라미터는,D3DVIEWPORT8 구조체의 값을 갱신해, 재차 SetViewport 를 호출하는 것만으로 변경할 수 있다.

주 D3DVIEWPORT8 구조체의 MinZ 및 MaxZ 멤버는, 장면이 렌더링 되는 깊이 범위를 나타내, 클리핑에는 사용되지 않는다. 대부분의 어플리케이션에서는, 이 멤버를 0.0 으로 1.0 으로 설정해, 깊이 버퍼내의 깊이값의 전범위에 렌더링 하고 있다. 경우에 따라서는, 다른 깊이 범위를 사용해 특수 효과를 얻을 수도 있다. 예를 들어, 게임의 헤드 업 디스플레이를 렌더링 하는 경우, 양쪽 모두의 값을 0.0 으로 설정해 foreground의 장면내의 오브젝트를 강제적으로 렌더링 하거나 양쪽 모두의 값을 1.0 으로 설정해 항상 백그라운드에 존재할 필요가 있는 오브젝트를 렌더링 할 수가 있다.


뷰 포토의 클리어

뷰 포토를 클리어 하면, 렌더링 타겟 표면 위에의 뷰 포토 직사각형의 내용과 깊이 버퍼 표면 및 스텐실 버퍼 표면 (지정되고 있는 경우)의 직사각형의 내용이 리셋 된다. 보통은, 새로운 프레임을 렌더링 하기 전에 뷰 포토를 클리어 해, 쓰레기를 표시하지 않고 , 그래픽스등의 데이터가 새로운 렌더링 오브젝트를 받아들일 준비를 갖춘다.

C++ 에서는, 뷰 포토를 클리어 하는,IDirect3DDevice8 인터페이스의 IDirect3DDevice8::Clear 메소드를 사용할 수 있다. 이 메소드는, 클리어 하는 표면 위에의 영역을 정의하는 1 개(살) 또는 복수의 직사각형을 받는다. 렌더링 하는 장면에 뷰 포토 직사각형 전체의 이동이 포함되어 있는 경우 (예를 들어, 대면형의 원근법을 사용하는 게임), 각 프레임의 뷰 포토 전체를 클리어 할 수가 있다. 이 경우는,Count 파라미터를 1 으로 설정해,pRects 파라미터를 뷰 포토 영역 전체에 이르는 단일의 직사각형의 주소로 설정한다. 보다 편리한 방법으로서pRects 파라미터를 NULL 로 설정해,Count 파라미터를 0 으로 설정해, 뷰 포토 직사각형 전체의 클리어를 나타낼 수가 있다.

Clear 메소드는 다양한 사용 방법이 있어, 깊이 버퍼내의 스텐실 비트를 클리어 할 수도 있다. Flags 파라미터는, 렌더링 타겟 및 관계하는 깊이 버퍼 또는 스텐실 버퍼의 클리어 방법을 지정하는 3 개의 플래그를 받는다. 이 파라미터에 D3DCLEAR_TARGET 플래그를 지정 하면, 이 메소드는 Color 파라미터로 지정한 임의의 RGBA 색 (머트리얼 칼라는 아니다)을 사용해 뷰 포토를 클리어 한다. D3DCLEAR_ZBUFFER 플래그를 지정 하면, 이 메소드는 z 파라미터로 지정한 임의의 깊이에 따라 깊이 버퍼를 클리어 한다. 0.0 은 가장 가까운 거리를 나타내, 1.0 은 가장 먼 거리를 나타낸다. D3DCLEAR_STENCIL 플래그를 지정 하면, 이 메소드는 스텐실 비트를 Stencil 파라미터로 지정한 값에 리셋 한다. 지정할 수 있는 값은 0 ~ 2n-1 까지의 정수이다. 여기서,n 는 스텐실 버퍼의 비트 깊이를 나타낸다.

주 Microsoft® DirectX® 5.0 에서는, 배경 머트리얼은 관련지을 수 있었던 텍스쳐를 가질 수가 있었으므로, 뷰 포토를 클리어 한 후, 단순한 색은 아니고 텍스쳐를 표시할 수 있었다. 이 기능은 거의 사용되는 것이 없고, 특히 효과적도 아니었다. DirectX 6.0 이후의 인터페이스는, 텍스쳐 핸들을 받지 않게 되어, 뷰 포토를 클리어 한 후에 텍스쳐를 표시할 수 없다. 따라서, 어플리케이션에서는 수동으로 배경을 드로잉(Drawing) 해야 한다. 그 결과, 렌더링 타겟 표면의 뷰 포토를 클리어 할 필요는 거의 없어졌다. 어플리케이션으로 깊이 버퍼를 클리어 하는 것만으로, 렌더링 타겟 표면 위에의 모든 픽셀이 덧쓰기된다.

경우에 따라서는, 렌더링 타겟 표면과 깊이 버퍼 표면의 일부에게만 렌더링 하는 일이 있다. 클리어 메소드는, 1 회의 호출로 표면의 복수의 영역을 클리어 할 수도 있다. 이것을 실시하려면 ,Count 파라미터에 클리어 하는 직사각형의 수를 지정해,pRects 파라미터에 직사각형의 배열내의 최초의 요소의 주소를 지정한다.


버텍스의 메뉴얼 트랜스 폼

Microsoft® Direct3D® 어플리케이션에서는, 3 종류의 버텍스를 사용할 수 있다. 버텍스 포맷의 상세한 것에 대하여는, 「버텍스 포맷」을 참조할것.

트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스
어플리케이션으로 라이팅과 트랜스 폼을 적용하지 않는 버텍스. 라이팅 파라미터나 트랜스 폼 행렬을 지정해도, 이러한 값은 Direct3D 가 계산한다.
트랜스폼 되지 않은 라이팅 끝난 버텍스
어플리케이션으로 라이팅은 적용하지만, 트랜스 폼은 적용하지 않는 버텍스.
트랜스 폼이 끝난 라이팅 끝난 버텍스
어플리케이션으로 라이팅과 트랜스 폼의 양쪽 모두를 적용하는 버텍스.

버텍스 버퍼를 사용해, 단순한 버텍스 타입을 복잡한 버텍스 타입으로 바꿀 수가 있다. 버텍스 버퍼란, 고속의 렌더링을 실행하기 위해서 버텍스를 정리해 저장 해 배치처리하기 위한 오브젝트로, 프로세서 고유의 기능을 이용하도록(듯이) 최적화할 수 있다. 버텍스 트랜스 폼을 실행하려면 ,IDirect3DDevice8::ProcessVertices 메소드를 사용한다. ProcessVertices 는 트랜스폼 되지 않은의 버텍스만 받지만, 옵션으로서 버텍스에의 라이팅의 적용과 클리핑이 가능하다. 라이팅은 ProcessVertices 를 호출했을 때에 적용되지만, 클리핑이 실행되는 것은 렌더링 때이다.

버텍스를 처리한 후, 특별한 렌더링 메소드를 사용해 버텍스를 렌더링 하거나 버텍스 버퍼 메모리를 잠그어 버텍스에 직접 액세스 할 수가 있다. 버텍스 버퍼의 사용의 상세한 것에 대하여는, 「버텍스 버퍼」를 참조할것.


라스터화

Microsoft® Direct3D® 지오메트리 파이프라인에서의 처리가 종료 하면, 버텍스는 렌더링 타겟 표면의 뷰 포토에 적합하도록(듯이) 트랜스 폼, 클리핑, 및 스케일링 되어 스크린상에 드로잉(Drawing) 하기 위해서 래스터라이저에 보낼 준비가 거의 완료한 것이 된다. 그러나, 이 시점에서는 아직 버텍스는 동차이며, 래스터라이저는 버텍스를 x, y, z 의 위치 좌표와 동차 W 의 역수 (RHW)라고 하는 형태로 받으려고 한다. Direct3D 는 x, y, z 좌표를 w 좌표로 나눗셈 하는 것으로써, 이 동차 버텍스를 비동차 버텍스로 변환한다. 그 후, 다음의 식에 나타내도록(듯이), w 좌표를 반전하는 것으로 RHW 값을 산출한다.

산출한 값은, 표시를 위해서(때문에) 래스터라이저에게 건네진다. 래스터라이저는 x 좌표와 y 좌표를 버텍스의 화면 좌표로서 사용해, z 버퍼링이 가능한 경우는 z 좌표를 깊이 버퍼의 깊이 비교에 사용한다. RHW 값은, fog 계산, 퍼스펙티브 보정 텍스쳐 매핑, 및 w 버퍼링 (깊이 버퍼링의 다른 방법)에 사용된다.


프로그램 가능한 버텍스 처리와 픽셀 처리

Microsoft® DirectX® 8.0 에는, 고도의 프로그램 가능성을 가지는, 새로운 그래픽스 파이프라인이 준비되어 있다. 다음의 그림에, 프로그램 가능한 버텍스 및 픽셀 파이프라인의 주된 컴퍼넌트 및 데이터 플로우를 나타낸다. 트랜스 폼 및 라이팅 엔진과 DirectX 6.0 및 7.0 의 멀티 텍스쳐 링 모듈은, 프로그램 가능한 파이프라인에 대해 버텍스 및 픽셀 쉐이더에 의해 옮겨놓을 수 있다.

이 파이프라인의 최초의 새로운 부분은, 고차원 프리미티브 모듈로, 베쥬 및 B 스플라인등의 고차원 프리미티브를 테셀레이트 한다. 버텍스 쉐이더는, 버텍스 데이터에 대해서 지오메트리 연산을 실행하기 위해서 사용되는 프로그램 가능 모듈이다. 버텍스 쉐이더는, 표준적인 트랜스 폼이나 라이팅 등, 다양한 기능을 실행할 수 있다. 픽셀 쉐이더는, 프로그램 가능한 픽셀 프로세서이다. 픽셀 쉐이더는, 색 및 알파 블렌딩 처리 및 텍스쳐 애드레싱 처리를 제어한다.

프로그램 가능한 쉐이더의 개요에 대해서는, 「프로시저 쉐이더의 개요」를 참조할것.

DirectX 8.0 으로 이전의 버젼의 Microsoft Direct3D® 파이프라인의 비교에 대해서는, 「지오메트리 파이프라인에의 버텍스 쉐이더의 편입」을 참조할것.

파이프라인의 프로그램 가능하지 않는 (DirectX 6.0 및 7.0 으로부터 변경되어 있지 않다) 부분에 대해서는, 「뷰 포토와 클리핑」 및 「라스터화」를 참조할것.


프로시저 쉐이더의 개요

Microsoft® Direct3D® for Microsoft DirectX® 8.0 에서는, 버텍스 트랜스 폼 및 라이팅 파이프라인과 픽셀 텍스쳐 블렌딩 파이프라인의 동작을 지정하기 위해서 프로시저 모델을 사용한다. 프로그램 모델 베이스의 구문을 사용해 하드웨어의 동작을 지정하는 것에는, 많은 이점이 있다.

우선, 프로시저 모델에서는, 보다 일반적인 구문을 사용해 공통의 조작을 지정할 수 있다. 고정 기능 API 에서는, 프로그램 가능하다고는 대조적으로, 표현할 필요가 있는 수많은 처리에 대해 모드, 플래그등을 정의해야 한다. 게다가 하드웨어의 능력이 향상 하면 (색, 텍스쳐, 버텍스 스트림등이 증가 하면), 데이터 입력수로 곱셈된 조작의 토큰 공간이 복잡하게 된다. 한편, 프로그램 가능한 모델에서는, 적절한 색 및 적절한 텍스쳐를 라이팅 모델의 적절한 부분에 적용하는 등의 간단한 처리를, 직접적인 방법으로 실행할 수 있다. 사용 가능한 모든 모드를 검색할 필요가 없고, 머신의 아키텍쳐를 이해해, 실행하는 적절한 알고리즘을 지정하는 것만으로 끝난다.

예를 들어, 다음과 같은 기존의 기능을 지원 할 수 있다.

  • 기본적인 지오메트리 트랜스 폼
  • 단순한 라이팅 모델
  • 스키닝용의 버텍스 블렌딩
  • 버텍스 morphing (트이닝)
  • 텍스쳐 트랜스 폼
  • 텍스쳐 생성
  • 환경 매핑

다음에, 프로시저 모델은, 새로운 처리를 개발하기 위한 간단한 메카니즘을 제공한다. 실행할 필요가 있는 처리의 대부분이, 현재의 API 에서는 지원되어 있지 않은 것이 있다. 많은 경우, 이것은 하드웨어의 능력의 제한에 의하는 것은 아니고, API 의 제한에 의하는 것이다. 일반적으로, 이러한 처리는, 고정 기능의 API 를 API 의 설계자가 예상하지 않은 방법으로 억지로 사용해, 같은 동작을 추출하는 것보다도, 단순하고, 고속으로 있다.

일반적으로 이행 되는 것이 예상되는 새로운 기능에는, 다음과 같은 것이 있다.

  • 행렬 팔레트의 스키닝. 메쉬 근처 8 ~ 10 의 뼈를 사용한 캐릭터 애니메이션.
  • 이방성 라이팅. 현재, 참조 테이블의 텍스쳐의 코스트만으로 실행할 수 있는 라이팅.
  • Membrane 쉐이더. 풍선, 피부등의 쉐이더 (1/cos(시점과 법선의 내적)).
  • Kubelka-Munk 쉐이더. 표면을 관통하는 라이트를 고려하는 쉐이더.
  • 프로시저 지오메트리. 프로시저 지오메트리 (구(공))를 사용해 메쉬 합성해, 피부아래의 근육을 시뮬레이트 한다.
  • 디스프레이스먼트맙핑. 늘어놓거나 반복할 수 있는 물결의 패턴이나 혹을 사용해 메쉬를 변경한다.

제 3 에, 프로시저 모델은 스케이라비리티와 발전성을 제공한다. 하드웨어의 능력은 급속히 발전 계속 하고 있어, 프로그램에 의한 표현은 매우 측정할 수 있는의로, 같은 API 에 의한 프로그램이 그 발전에 맞추어 고층화가 가능하다. 다음의 처리에 의해, 새로운 기능 및 능력을 간단하게 공개해, 추가할 수가 있다.

  • 새로운 명령을 추가한다
  • 새로운 데이터 입력을 추가한다
  • 고정 기능으로부터 파이프라인의 프로그램 가능한 부분에 새로운 기능을 추가한다

코드는, 복잡한 처리를 표현하기 위한 최적인 스케일링 프로퍼티를 가지는 표현이다. 게다가 프로그램 가능한 쉐이더에 추가된 새로운 기능에 대해, Direct3D 내부에서 변경해야 하는 코드는 매우 적다.

제 4 에, 프로시저 모델은 쉽게 친숙 해지다. 소프트웨어 개발자에게 있어서는, 하드웨어보다 프로그래밍이 이해하기 쉽다. 소프트웨어 개발자의 요구를 채우는 API 는, 하드웨어의 기능을 코드 패러다임(paradigm)에 매핑 해야 하는 것이다.

제 5 에, 프로시저 모델은, 포토 리얼 렌더링의 유산을 계승하고 있다. 고급 지향의 포토 리얼 렌더링에서는, 오랜 세월에 걸쳐서, 프로그램 가능한 쉐이더가 사용되어 왔다. 일반적으로, 이 분야는 퍼포먼스의 제약을 받지 않기 때문에, 프로그램 가능한 쉐이더에 의해, 렌더링 기술의 타협이 없는, 궁극의 목표가 표현된다.

마지막으로, 프로시저 모델에 의해, 하드웨어에의 직접적인 매핑이 가능하게 된다. 최신의 3D 하드웨어는, 적어도 버텍스 처리 스테이지에서는, 실제로는 꽤 프로그램 가능하다. API 에 의한 프로그램 가능성에 의해, 어플리케이션이 직접 이 하드웨어에 매핑 할 수 있도록(듯이) 한다. 이것에 의해, 요건에 응해 하드웨어 리소스를 관리할 수 있다. 실행할 수 있는 레지스터나 명령이 제한되고 있는 경우, 그 모든 기능을 가지는 고정 기능의 이행을 개별적으로 유효하게 하는 것은 곤란하다. 공유 리소스를 필요로 하는 많은 기능을 한 번에 유효하게 하면, 예기치 않은 방법으로 동작을 정지하는 경우가 있다. 프로그램 가능한 API 모델에서는, DirectX 의 전통에 따라, 어플리케이션 개발자가 직접 하드웨어를 조작해, 이러한 제한을 의식하지 않고 끝나도록(듯이) 해, 이 문제를 회피하고 있다.


지오메트리 파이프라인에의 버텍스 쉐이더의 편입

처리중에, 프로그램 가능한 버텍스 쉐이더는, Microsoft® Direct3D® 지오메트리 파이프라인의 트랜스 폼 및 라이팅 모듈을 옮겨놓는다. 실질적으로, 트랜스 폼 및 라이팅 처리에 관한 스테이트 정보는 무시된다. 다만, 버텍스 쉐이더가 무효로, 고정 기능에 의한 처리하러 돌아왔을 경우는, 현재의 스테이트 설정이 모두 적용된다.

고차원 프리미티브의 테셀레이션은 모두, 버텍스 쉐이더의 실행전에 실시할 필요가 있다. 쉐이더의 처리의 뒤에 표면 테셀레이션을 실행하는 이행 환경에서는, 어플리케이션 및 쉐이더 코드가 모르는 방법으로 실행해야 한다. 시멘틱스 정보는, 보통, 쉐이더의 전에는 제공되지 않기 때문에, 특수한 토큰을 사용해, 다른 모든 컴퍼넌트가 상대적으로 보간 되는 베이스 위치를 나타내는 입력 스트림 컴퍼넌트를 식별한다. 보간 할 수 없는 데이터 채널은 지원 되지 않는다.

출력으로는, 버텍스 쉐이더는 동차 클립 공간에 버텍스의 위치 좌표를 생성해야 한다. 생성할 수 있는 추가 데이터에는, 텍스쳐 좌표, 색, fog 계수등이 있다.

표준적인 그래픽스 파이프라인은, 다음의 태스크를 포함해, 쉐이더 마다 버텍스 출력을 처리한다.

  • 프리미티브 어셈블리
  • 시추대 및 클립면에 대한 클리핑
  • 동차 나눗셈
  • 뷰 포토의 스케일링
  • 배면 및 뷰 포토의 카링
  • 삼각형의 셋업
  • 라스터화

DirectX 8.0 버텍스 쉐이더의 클리핑 공간은, DirectX 7.0 및 DirectX 8.0 의 고정 기능에 의한 버텍스 처리와 같다. 상세한 것에 대하여는, 「클리핑 볼륨」을 참조할것.

프로그램 가능한 지오메트리는, Direct3D 어플리케이션 프로그래밍 인터페이스 (API) 내의 모드이다. 유효하게 되어 있는 경우, 버텍스 파이프라인을 부분적으로 옮겨놓는다. 무효가 되어 있는 경우, API 는 DirectX 6.0 및 7.0 에서의 동작과 같은 보통의 제어를 실시한다. 버텍스 쉐이더의 실행은, 내부의 Direct3D 스테이트를 변경하지 않고, Direct3D 스테이트는 쉐이더에서는 사용할 수 없다.

pFunction 파라미터를 NULL 로 한 IDirect3DDevice8::CreateVertexShader 의 호출은, 고정 기능에 의한 파이프라인의 쉐이더를 생성 하기 위해서 사용된다. pFunction 가 NULL 가 아닌 경우는, 쉐이더는 프로그램 가능하게 된다. IDirect3DDevice8::SetVertexShader 의 호출은, 현재의 액티브 쉐이더를 설정해, 렌더링 파이프라인이 프로그램에 의한 버텍스 처리와 고정 기능 버텍스 처리의 머지않아를 사용하는지를 정의한다.


버텍스 프로세서에의 버텍스 데이터의 제시

다음의 몇개의 포맷을 사용해, 버텍스 데이터를 버텍스 프로세서에 제시할 수 있다.

  • 종래의 FVF 포맷
  • 프로그램 가능한 스트림 모델

주 선택하는 버텍스 데이터 형식은, 사용되는 버텍스 처리 방법 (고정 기능과 프로그램 가능)과는 독립하고 있어, 어느 편성도 가능하다. 예를 들어, 고정 기능 트랜스 폼과 라이팅 파이프라인으로 스트림을 사용해, 프로그램 가능한 버텍스 쉐이더로 FVF 버텍스를 사용할 수 있다.


종래의 FVF 포맷

종래의 FVF 포맷을 사용하려면 , 다음의 샘플 코드에 나타내도록(듯이),IDirect3DDevice8::SetVertexShader 메소드를 호출하면나무에, 핸들은 아니고 FVF 를 사용한다.

g_d3dDevice->SetVertexShader( CUSTOM_FVF );

여기에서는, 종래의 FVF 포맷의 타입에 대해 설명한다.

  • Vertex 형 레가시타이프
  • LVertex 형 레가시타이프
  • TLVertex 형 레가시타이프


Vertex 형 레가시타이프

여기에서는, 위치, 법선, 및 텍스쳐 좌표를 가지는 버텍스를 초기화 및 사용하기 위해서 필요한 스텝에 대해 설명한다.

최초의 스텝에서는, 다음의 샘플 코드에 나타내도록(듯이), 커스텀 버텍스 타입과 FVF 를 정의한다.

struct Vertex
{
    FLOAT x, y, z;
    FLOAT nx, ny, nz;
    FLOAT tu, tv;
};

const DWORD VertexFVF = ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_TEX1 );

다음의 스텝에서는,IDirect3DDevice8::CreateVertexBuffer 메소드를 호출해, 4 개의 버텍스를 거두는데 충분한 영역을 확보한 버텍스 버퍼를 생성 한다. 이것을, 다음의 샘플 코드에 나타낸다.

g_d3dDevice->CreateVertexBuffer(
                 4*sizeof(Vertex), VertexFVF,
                 D3DUSAGE_WRITEONLY,
                 D3DPOOL_DEFAULT, &pBigSquareVB);

다음의 스텝에서는, 각 버텍스의 값을 처리한다. 이것을, 다음의 샘플 코드에 나타낸다.

Vertex * v;
pBigSquareVB->Lock( 0, 0, (BYTE**) &v, 0 );

v[0]. x  = 0.0f;  v[0]. y  = 10.0;  v[0]. z  = 10.0f;
v[0]. nx = 0.0f;  v[0]. ny = 1.0f;  v[0]. nz = 0.0f;
v[0]. tu = 0.0f;  v[0]. tv = 0.0f;

v[1]. x  = 0.0f;  v[1]. y  = 0.0f;  v[1]. z  = 10.0f;
v[1]. nx = 0.0f;  v[1]. ny = 1.0f;  v[1]. nz = 0.0f;
v[1]. tu = 0.0f;  v[1]. tv = 0.0f;

v[2]. x  = 10.0f; v[2]. y  = 10.0f; v[2]. z  = 10.0f;
v[2]. nx = 0.0f;  v[2]. ny = 1.0f;  v[2]. nz = 0.0f;
v[2]. tu = 0.0f;  v[2]. tv = 0.0f;

v[3]. x  = 0.0f; v[3]. y  = 10.0f;  v[3]. z = 10.0f;
v[3]. nx = 0.0f; v[3]. ny = 1.0f;   v[3]. nz = 0.0f;
v[3]. tu = 0.0f; v[3]. tv = 0.0f;

pBigSquareVB->Unlock();

버텍스 버퍼는 초기화되어 렌더링 할 준비가 되어 있다. 다음의 샘플 코드는, 레가시 FVF 를 사용해 정방형을 드로잉(Drawing) 하는 방법을 나타내고 있다.

g_d3dDevice->SetVertexShader( VertexFVF );
g_d3dDevice->SetStreamSource( 0, pBigSquareVB, 4*sizeof(Vertex) );
g_d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0 , 2);

FVF 를 IDirect3DDevice8::SetVertexShader 메소드에 건네주어, 레가시 FVF 가 사용되는 것, 및 스트림 0 만이 유효한 스트림인 것을 Direct3D 에 지시한다.


LVertex 형 레가시타이프

여기에서는, 위치, 디퓨즈색, 스펙큐러색, 및 텍스쳐 좌표를 가지는 버텍스를 초기화 및 사용하기 위해서 필요한 스텝에 대해 설명한다.

최초의 스텝에서는, 다음의 샘플 코드에 나타내도록(듯이), 커스텀 버텍스 타입과 FVF 를 정의한다.

struct LVertex
{
    FLOAT    x, y, z;
    D3DCOLOR specular, diffuse;
    FLOAT    tu, tv;
};

const DWORD VertexFVF = (D3DFVF_XYZ | D3DFVF_DIFFUSE |
                         D3DFVF_SPECULAR | D3DFVF_TEX1 );

다음의 스텝에서는,IDirect3DDevice8::CreateVertexBuffer 메소드를 호출해, 4 개의 버텍스를 거두는데 충분한 영역을 확보한 버텍스 버퍼를 생성 한다. 이것을, 다음의 샘플 코드에 나타낸다.

g_d3dDevice->CreateVertexBuffer(
                 4*sizeof(LVertex), VertexFVF,
                 D3DUSAGE_WRITEONLY,
                 D3DPOOL_DEFAULT, &pBigSquareVB);

다음의 스텝에서는, 각 버텍스의 값을 처리한다. 이것을, 다음의 샘플 코드에 나타낸다.

LVertex * v;
pBigSquareVB->Lock( 0, 0, (BYTE**) &v, 0 );

v[0]. x  = 0.0f;  v[0]. y  = 10.0;  v[0]. z  = 10.0f;
v[0]. diffuse  = 0xffff0000;
v[0]. specular = 0xff00ff00;
v[0]. tu = 0.0f;  v[0]. tv = 0.0f;

v[1]. x  = 0.0f;  v[1]. y  = 0.0f;  v[1]. z  = 10.0f;
v[1]. diffuse  = 0xff00ff00;
v[1]. specular = 0xff00ffff;
v[1]. tu = 0.0f;  v[1]. tv = 0.0f;

v[2]. x  = 10.0f; v[2]. y  = 10.0f; v[2]. z  = 10.0f;
v[2]. diffuse  = 0xffff00ff;
v[2]. specular = 0xff000000;
v[2]. tu = 0.0f;  v[2]. tv = 0.0f;

v[3]. x  = 0.0f; v[3]. y  = 10.0f;  v[3]. z = 10.0f;
v[3]. diffuse  = 0xffffff00;
v[3]. specular = 0xffff0000;
v[3]. tu = 0.0f; v[3]. tv = 0.0f;

pBigSquareVB->Unlock();

버텍스 버퍼는 초기화되어 렌더링 할 준비가 되어 있다. 다음의 샘플 코드는, 레가시 FVF 를 사용해 정방형을 드로잉(Drawing) 하는 방법을 나타내고 있다.

g_d3dDevice->SetVertexShader( VertexFVF );
g_d3dDevice->SetStreamSource( 0, pBigSquareVB, 4*sizeof(LVertex) );
g_d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0 , 2);

FVF 를 IDirect3DDevice8::SetVertexShader 메소드에 건네주어, 레가시 FVF 가 사용되는 것, 및 스트림 0 만이 유효한 스트림인 것을 Direct3D 에 지시한다.


TLVertex 형 레가시타이프

여기에서는, 트랜스 폼이 끝난 위치, 디퓨즈색, 스펙큐러색, 및 텍스쳐 좌표를 가지는 버텍스를 초기화 및 사용하기 위해서 필요한 스텝에 대해 설명한다.

최초의 스텝에서는, 다음의 샘플 코드에 나타내도록(듯이), 커스텀 버텍스 타입과 FVF 를 정의한다.

struct TLVertex
{
    FLOAT    x, y, z, rhw;
    D3DCOLOR specular, diffuse;
    FLOAT    tu, tv;
};

const DWORD VertexFVF = (D3DFVF_XYZRHW | D3DFVF_DIFFUSE |
                         D3DFVF_SPECULAR | D3DFVF_TEX1 );

다음의 스텝에서는,IDirect3DDevice8::CreateVertexBuffer 메소드를 호출해, 4 개의 버텍스를 거두는데 충분한 영역을 확보한 버텍스 버퍼를 생성 한다. 이것을, 다음의 샘플 코드에 나타낸다.

g_d3dDevice->CreateVertexBuffer(
                 4*sizeof(TLVertex), VertexFVF,
                 D3DUSAGE_WRITEONLY,
                 D3DPOOL_DEFAULT, &pBigSquareVB);

다음의 스텝에서는, 각 버텍스의 값을 처리한다. 이것을, 다음의 샘플 코드에 나타낸다.

TLVertex * v;
pBigSquareVB->Lock( 0, 0, (BYTE**) &v, 0 );

v[0]. x  = 0.0f;  v[0]. y  = 10.0;  v[0]. z  = 10.0f; v[0]. rhw = 1.0f;
v[0]. diffuse  = 0xffff0000;
v[0]. specular = 0xff00ff00;
v[0]. tu = 0.0f;  v[0]. tv = 0.0f;

v[1]. x  = 0.0f;  v[1]. y  = 0.0f;  v[1]. z  = 10.0f; v[1]. rhw = 1.0f;
v[1]. diffuse  = 0xff00ff00;
v[1]. specular = 0xff00ffff;
v[1]. tu = 0.0f;  v[1]. tv = 0.0f;

v[2]. x  = 10.0f; v[2]. y  = 10.0f; v[2]. z  = 10.0f; v[2]. rhw = 1.0f;
v[2]. diffuse  = 0xffff00ff;
v[2]. specular = 0xff000000;
v[2]. tu = 0.0f;  v[2]. tv = 0.0f;

v[3]. x  = 0.0f; v[3]. y  = 10.0f;  v[3]. z = 10.0f; v[3]. rhw = 1.0f;
v[3]. diffuse  = 0xffffff00;
v[3]. specular = 0xffff0000;
v[3]. tu = 0.0f; v[3]. tv = 0.0f;

pBigSquareVB->Unlock();

버텍스 버퍼는 초기화되어 렌더링 할 준비가 되어 있다. 다음의 샘플 코드는, 레가시 FVF 를 사용해 정방형을 드로잉(Drawing) 하는 방법을 나타내고 있다.

g_d3dDevice->SetVertexShader( VertexFVF );
g_d3dDevice->SetStreamSource( 0, pBigSquareVB, 4*sizeof(TLVertex) );
g_d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0 , 2);

FVF 를 IDirect3DDevice8::SetVertexShader 메소드에 건네주어, 레가시 FVF 가 사용되는 것, 및 스트림 0 만이 유효한 스트림인 것을 Direct3D 에 지시한다.


프로그램 가능한 스트림 모델

여기에서는, 프로그램 가능한 스트림 모델로 사용할 수 있는 쉐이더에 대해 설명한다.

  • 칼라 버텍스 쉐이더
  • 싱글 텍스쳐 쉐이더
  • 멀티 텍스쳐 쉐이더


칼라 버텍스 쉐이더

여기에서는, 위치와 디피즈색을 가지는 단순한 버텍스 쉐이더를 초기화 및 사용하기 위해서 필요한 스텝에 대해 설명한다.

최초의 스텝에서는, 위치와 색을 저장 하는 구조체를 선언한다. 이것을, 다음의 샘플 코드에 나타낸다.

struct XYZBuff
{
    FLOAT x, y, z;
    D3DCOLOR color;
};

struct ColBuf
{
    D3DCOLOR color;
};

#define XYZBUFF (D3DFVF_XYZ)
#define COLBUFF (D3DFVF_DIFFUSE)

다음의 스텝에서는,버텍스 쉐이더 선언을 생성 한다. 이것을, 다음의 샘플 코드에 나타낸다.

DWORD decl[] =
{
    D3DVSD_STREAM(0),
    D3DVSD_REG( D3DVSDE_POSITION, D3DVSDT_FLOAT3 ),
    D3DVSD_STREAM(1),
    D3DVSD_REG( D3DVSDE_DIFFUSE, D3DVSDT_D3DCOLOR),
    D3DVSD_END()
};

다음의 스텝에서는,IDirect3DDevice8::CreateVertexShader 메소드를 호출해 버텍스 쉐이더를 생성 한다.

g_d3dDevice->CreateVertexShader( decl, NULL, &vShader, 0);

CreateVertexShader 의 제 2 파라미터에 NULL 를 건네주어, 이 버텍스 쉐이더로 고정 기능 파이프라인을 사용하는 것을 Direct3D 에 지시한다.

버텍스 버퍼와 버텍스 쉐이더는, 생성 후는 언제라도 사용할 수 있다. 다음의 샘플 코드는, 버텍스 쉐이더의 설정 방법법, 스트림 소스의 설정 방법법, 및 새로운 버텍스 쉐이더를 사용하는 삼각형 리스트의 드로잉(Drawing) 방법을 나타내고 있다.

g_d3dDevice->SetVertexShader( &vShader );
g_d3dDevice->SetStreamSource( 0, xyzbuf, 4 * sizeof(FLOAT));
g_d3dDevice->SetStreamSource( 1, colbuf, 2 * sizeof(FLOAT));
g_d3dDevice->SetIndices( pIB, 0 );
g_d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0, max - min + 1, 0, count / 3 );


싱글 텍스쳐 쉐이더

여기에서는, 위치와 텍스쳐 좌표를 가지는 단순한 버텍스 쉐이더를 초기화 및 사용하기 위해서 필요한 스텝에 대해 설명한다.

최초의 스텝에서는, 위치와 텍스쳐 좌표를 저장 하는 구조체를 선언한다. 이것을, 다음의 샘플 코드에 나타낸다.

struct XYZBuff
{
    D3DVALUE x, y, z;
};

struct TEX0Buff
{
    D3DVALUE tu, tv;
};

#define XYZBUFF  (D3DFVF_XYZ)
#define TEX0BUFF (D3DFVF_TEX1)

다음의 스텝에서는,버텍스 쉐이더 선언을 생성 한다. 이것을, 다음의 샘플 코드에 나타낸다.

DWORD decl[] =
{
    D3DVSD_STREAM(0),
    D3DVSD_REG( D3DVSDE_POSITION, D3DVSDT_FLOAT3 ),
    D3DVSD_STREAM(1),
    D3DVSD_REG( D3DVSDE_TEXCOORD0, D3DVSDT_FLOAT2 ),
    D3DVSD_END()
};

다음의 스텝에서는,IDirect3DDevice8::CreateVertexShader 메소드를 호출해 버텍스 쉐이더를 생성 한다.

g_d3dDevice->CreateVertexShader( decl, NULL, &vShader, 0);

CreateVertexShader 의 제 2 파라미터에 NULL 를 건네주어, 이 버텍스 쉐이더로 고정 기능 파이프라인을 사용하는 것을 Direct3D 에 지시한다.

버텍스 버퍼와 버텍스 쉐이더는, 생성 후는 언제라도 사용할 수 있다. 다음의 샘플 코드는, 버텍스 쉐이더의 설정 방법법, 스트림 소스의 설정 방법법, 및 새로운 버텍스 쉐이더를 사용하는 삼각형 리스트의 드로잉(Drawing) 방법을 나타내고 있다.

g_d3dDevice->SetVertexShader( &vShader );
g_d3dDevice->SetStreamSource( 0, xyzbuf, 4 * sizeof(FLOAT));
g_d3dDevice->SetStreamSource( 1, tex0buf, 2 * sizeof(FLOAT));
g_d3dDevice->SetIndices( pIB, 0 );
g_d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0, max - min + 1, 0, count / 3 );


멀티 텍스쳐 쉐이더

여기에서는, 위치와 복수의 텍스쳐 좌표를 가지는 단순한 버텍스 쉐이더를 초기화 및 사용하기 위해서 필요한 스텝에 대해 설명한다.

최초의 스텝에서는, 위치와 색을 저장 하는 구조체를 선언한다. 이것을, 다음의 샘플 코드에 나타낸다.

struct XYZBuff
{
    D3DVALUE x, y, z;
};

struct Tex0Buff
{
    D3DVALUE tu, tv;
};

struct Tex1Buff
{
    D3DVALUE tu2, tv2;
};

#define XYZBUFF (D3DFVF_XYZ)
#define TEX0BUFF (D3DFVF_TEX1)
#define TEX1BUFF (D3DFVF_TEX1)

다음의 스텝에서는,버텍스 쉐이더 선언을 생성 한다. 이것을, 다음의 샘플 코드에 나타낸다.

DWORD decl[] =
{
    D3DVSD_STREAM(0),
    D3DVSD_REG( D3DVSDE_POSITION, D3DVSDT_FLOAT3 ),
    D3DVSD_STREAM(1),
    D3DVSD_REG( D3DVSDE_TEXCOORD0, D3DVSDT_FLOAT2),
    D3DVSD_STREAM(2),
    D3DVSD_REG( D3DVSDE_TEXCOORD1, D3DVSDT_FLOAT2),
    D3DVSD_END()
};

다음의 스텝에서는,IDirect3DDevice8::CreateVertexShader 메소드를 호출해 버텍스 쉐이더를 생성 한다.

g_d3dDevice->CreateVertexShader( decl, NULL, &vShader, 0);

CreateVertexShader 의 제 2 파라미터에 NULL 를 건네주어, 이 버텍스 쉐이더로 고정 기능 파이프라인을 사용하는 것을 Direct3D 에 지시한다.

버텍스 버퍼와 버텍스 쉐이더는, 생성 후는 언제라도 사용할 수 있다. 다음의 샘플 코드는, 버텍스 쉐이더의 설정 방법법, 스트림 소스의 설정 방법법, 및 새로운 버텍스 쉐이더를 사용하는 삼각형 리스트의 드로잉(Drawing) 방법을 나타내고 있다.

g_d3dDevice->SetVertexShader( &vShader );
g_d3dDevice->SetStreamSource( 0, xyzbuf, 4 * sizeof(FLOAT));
g_d3dDevice->SetStreamSource( 1, tex0buf, 2 * sizeof(FLOAT));
g_d3dDevice->SetStreamSource( 2, tex1buf, 2 * sizeof(FLOAT));
g_d3dDevice->SetIndices( pIB, 0 );
g_d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0, max - min + 1, 0, count / 3 );


DirectX Graphics 의 사용법

여기에서는, 어플리케이션 개발에 있어서의 Microsoft® Direct3D® 및 Direct3DX 의 API 의 사용 방법에 대해 설명한다.

설명하는 주제는, 다음과 같다.

  • Direct3D 오브젝트
  • Direct3D 디바이스
  • Direct3D 리소스
  • 표면
  • 라이트
  • 머트리얼
  • 버텍스 포맷
  • 텍스쳐
  • 깊이 버퍼
  • 스텐실 버퍼
  • 버텍스 버퍼
  • 인덱스 버퍼
  • 테크놀러지와 특수 효과

개요에 대해서는, 「DirectX Graphics 의 기초지식」을 참조할것.

데이터 플로우의 일반적 메카니즘이나 구성의 상세한 것에 대하여는, 「DirectX Graphics 에 대하며」를 참조할것.

프로그램 가능한 쉐이더 등 고도의 기능에 대해서는, 「DirectX Graphics 의 고도의 주제」를 참조할것.


Direct3D 오브젝트

여기에서는, Microsoft® Direct3D® 오브젝트에 대해 설명한다.

  • Direct3D 오브젝트란
  • Direct3D 에의 액세스


Direct3D 오브젝트란

Microsoft® Direct3D® 는, COM 오브젝트와 인터페이스에 의해 이행 된다. C++ 로 기술된 어플리케이션으로부터는 이러한 인터페이스와 오브젝트에 직접 액세스 할 수 있지만, Microsoft Visual Basic® 어플리케이션의 경우는, Visual Basic 어플리케이션으로부터 DirectX 런타임에 데이터를 배치하는, Microsoft DirectX® for Visual Basic 클래스로서 나타나는 코드 계층과의 상호 처리를 실시한다.

Direct3D 오브젝트는, 어플리케이션으로 최초로 생성 되어 마지막에 해방되는 오브젝트이다. Direct3D 디바이스의 능력을 열거 및 취득하는 함수에는, Direct3D 오브젝트를 개입시켜 액세스 할 수 있다. 따라서, 어플리케이션은 디바이스를 생성 하지 않지는 디바이스의 선택이 가능하다.


Direct3D 에의 액세스

C++ 로 기술된 Microsoft® Direct3D® 어플리케이션에서는, 기동시에, Direct3D 의 기능을 이용하기 위해서 IDirect3D8 인터페이스에의 포인터를 취득해야 한다.

다음의 코드는,Direct3DCreate8 함수에 의한 Direct3D 인터페이스에의 포인터의 취득 방법을 나타내고 있다.

LPDIRECT3D8 g_pD3D = NULL;

    if( NULL == (g_pD3D = Direct3DCreate8(D3D_SDK_VERSION)))
        return E_FAIL;

Direct3DDevice 오브젝트로부터, 디바이스를 생성 한 Direct3D 오브젝트로 이동하려면 ,IDirect3DDevice8::GetDirect3D 메소드를 사용한다.


Direct3D 디바이스

여기에서는, Microsoft® Direct3D® 디바이스의 개요에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • Direct3D 디바이스란
  • 디바이스의 종류
  • 디바이스로 지원 되는 프리미티브의 종류
  • 디바이스의 사용법
  • 디바이스 스테이트
  • 소실한 디바이스


Direct3D 디바이스란

Microsoft® Direct3D® 디바이스란, Direct3D 의 렌더링 컴퍼넌트이다. 이것은 렌더링 스테이트를 캡슐화해 보존한다. 게다가 Direct3D 디바이스는, 트랜스 폼 & 라이팅 처리를 실행해, 표면에 화면을 rasterize 한다. 다음의 그림에 나타내도록(듯이), Direct3D 디바이스의 아키텍쳐는, 트랜스 폼, 라이팅, 및 라스터화 모듈로부터 구성된다.

Direct3D 디바이스의 트랜스 폼 & 라이팅 모듈을 사용하지 않고 , 어플리케이션 독자적인 트랜스 폼 & 라이팅 모델을 사용할 수도 있다. 상세한 것에 대하여는, 「버텍스 쉐이더」를 참조할것.


디바이스의 종류

여기에서는, Microsoft® Direct3D® 디바이스, 및 디바이스의 각 타입에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 디바이스의 종류에 대해
  • HAL 디바이스
  • 레퍼런스 디바이스
  • 플러그 가능한 소프트웨어 디바이스
  • 디바이스의 동작


디바이스의 종류에 대해

Microsoft® Direct3D® 가 현재 지원 하고 있는 Direct3D 의 주요 디바이스는, 주로 3 종류로 나눌 수 있다. 하드웨어 가속화에 의한 라스터화와 쉐이딩, 하드웨어와 소프트웨어 양쪽 모두에 의한 버텍스 처리를 실시하는, 하드웨어 추상 계층 (HAL) 디바이스, 레퍼런스 디바이스, 그리고 소프트웨어에 의한 라스터화를 제공하는 플러그 가능한 소프트웨어 디바이스의 3 종류이다.

이것들 3 개의 디바이스는, 3 개의 별개의 드라이버라고 볼 수가 있다. 소프트웨어 디바이스와 레퍼런스 디바이스는, 소프트웨어 드라이버로 나타내져 HAL 디바이스는, 하드웨어 드라이버로 나타내진다. 이러한 디바이스를 유효 활용하는 가장 일반적인 방법은, HAL 디바이스를 출하용 어플리케이션에 사용해, 레퍼런스 디바이스를 기능 테스트에 사용하는 것이다. 이러한 레퍼런스 드라이버는, 써드파티에 의해 제공되어 특정의 디바이스 (예를 들어, 아직 릴리스되어 있지 않은 개발중의 하드웨어)를 에뮤레이트 한다.

어플리케이션이 생성 하는 Direct3D 디바이스는, 어플리케이션이 동작하는 하드웨어의 기능에 대응하고 있지 않으면 안 된다. Direct3D 에서는, 컴퓨터에 인스톨 되고 있는 3D 하드웨어에 액세스 하는지, 소프트웨어로 3D 하드웨어 기능을 에뮤레이트 할까의 몇개의 방법으로, 렌더링 기능을 이용한다. 따라서, Direct3D 는, 하드웨어 액세스용 및 소프트웨어 에뮬레이션용의 양쪽 모두의 디바이스를 갖추고 있다.

하드웨어 가속화 디바이스는, 소프트웨어 에뮬레이션 디바이스보다 한층 더 높은 퍼포먼스를 실현한다. HAL 디바이스는, Direct3D 를 지원 하는 모든 그래픽 어댑터로 사용할 수 있다. 대부분의 경우, 어플리케이션이 대상으로 하는 것은, 어떠한 하드웨어 가속화를 갖추어 소프트웨어 에뮬레이션에 의해 로앤드 컴퓨터의 기능을 사용할 수 있는 컴퓨터이다.

레퍼런스 디바이스를 제외해, 소프트웨어 디바이스는, 항상 하드웨어 디바이스와 같은 기능을 지원 하고 있는 것은 아니다. 어플리케이션은, 디바이스 기능을 조사해, 지원 되고 있는 기능을 확인할 필요가 있다.

Microsoft DirectX® 8.0 에 의해 제공되는 소프트웨어 디바이스 및 레퍼런스 디바이스의 동작은 HAL 디바이스의 동작과 같고, HAL 디바이스용으로 생성 된 어플리케이션 코드는, 수정없이 그대로 사용할 수 있다. 제공되는 소프트웨어 디바이스 및 레퍼런스 디바이스의 동작은 HAL 디바이스의 동작과 같지만, 디바이스의 능력은 다르다. 또, 특정의 소프트웨어 디바이스에서는, 몇 안 되는 기능 세트 밖에 이행 할 수 없는 것도 있으므로 주의 해야 한다.


HAL 디바이스

프라이머리 디바이스는 하드웨어 추상 계층 (HAL) 디바이스이며, 이 디바이스는, 하드웨어 가속화에 의한 라스터화와 소프트웨어 및 하드웨어의 양쪽 모두에 의한 버텍스 처리를 지원 한다. 어플리케이션이 동작하는 컴퓨터에, Microsoft® Direct3D® 를 지원 하는 디스플레이 어댑터가 장착되고 있는 경우, 어플리케이션에서는 그 어댑터를 3D 처리에 사용할 필요가 있다. Direct3D 의 HAL 디바이스는, 하드웨어의 트랜스 폼, 라이팅, 및 라스터화 모듈을 모두 또는 그 일부를 이행 한다.

어플리케이션은, 3D 카드로 직접 액세스 하는 것은 아니다. 어플리케이션은, Direct3D 함수 및 메소드를 호출한다. Direct3D 는, HAL 를 개입시켜 하드웨어에 액세스 한다. 어플리케이션이 동작하는 컴퓨터가 HAL 에 대응하고 있는 경우는, HAL 디바이스를 사용하는 것으로 최고의 퍼포먼스를 실현할 수 있다.

C++ 로 HAL 디바이스를 생성 하려면 ,IDirect3D8::CreateDevice 메소드를 호출해, 디바이스 타입으로서 정수 D3DDEVTYPE_HAL 를 건네준다. 상세한 것에 대하여는, 「디바이스의 생성」을 참조할것.

주 : 하드웨어 디바이스는 8 비트의 렌더링 타겟 표면에는 렌더링 할 수 없다.


레퍼런스 디바이스

Microsoft® Direct3D® 는, 레퍼런스 디바이스 또는 레퍼런스 래스터라이저로 불리는 추가 디바이스를 지원 하고 있다. 소프트웨어 디바이스와는 달라, 레퍼런스 래스터라이저는 모든 Direct3D 기능을 지원 하고 있다. 이러한 기능은 처리 속도보다 정밀도를 중시해 소프트웨어에 이행 되고 있기 (위해)때문에, 결과를 얻을 수 있기까지는 시간이 걸린다. 레퍼런스 래스터라이저는, 이용 가능한 경우는 특별한 CPU 명령을 충분히 이용하지만, 시판 어플리케이션은 대상으로 하지 않았다. 레퍼런스 래스터라이저는, 기능 테스트나 데먼스트레이션에게만 사용한다.

C++ 로 레퍼런스 디바이스를 생성 하려면 ,IDirect3D8::CreateDevice 메소드를 호출해, 디바이스 타입으로서 정수 D3DDEVTYPE_REF 를 건네준다. 상세한 것에 대하여는, 「디바이스의 생성」을 참조할것.


플러그 가능한 소프트웨어 디바이스

유저의 컴퓨터가 3D 조작용의 특별한 하드웨어 가속화를 갖추지 않은 경우, 어플리케이션은 소프트웨어로 3D 하드웨어를 에뮤레이트 할 수 있다. 소프트웨어 라스터화 디바이스는, 소프트웨어로 칼라 3D 하드웨어의 기능을 에뮤레이트 한다. 소프트웨어 디바이스는 소프트웨어 에뮬레이션이므로, 하드웨어 추상 계층 (HAL) 디바이스보다 실행 속도가 늦다. 다만, 소프트웨어 디바이스는, 유저의 CPU 로 지원 되고 있는 특별한 명령을 이용해 퍼포먼스를 향상시킨다. 지원 되는 명령 세트에는, 몇개의 AMD 프로세서의 AMD 3D-Now! 명령 세트나, 많은 Intel 프로세서로 지원 되는 MMX 명령 세트등이 있다. Microsoft® Direct3D 에서는, 3D-Now! 명령 세트를 사용해 트랜스 폼 & 라이팅 처리를 고속화해, MMX 명령 세트를 사용해 라스터화를 고속화한다.

Direct3D® 의 소프트웨어 라스터화는, 플러그 가능한 소프트웨어 디바이스에 의해 제공된다. 이 디바이스는, Direct3D 인터페이스를 개입시켜 각종 소프트웨어 래스터라이저에의 액세스를 가능하게 한다. 소프트웨어 디바이스는, 어플리케이션에 의해 로드 되어, Direct3D 오브젝트에 등록된다. 이 시점에서, 소프트웨어 디바이스를 사용해 렌더링을 실행하는 Direct3DDevice 오브젝트를 생성 할 수 있다.

Direct3D 소프트웨어 디바이스는, 하드웨어 디바이스 드라이버 인터페이스 (DDI)에 유사하는 인터페이스를 개입시켜 Direct3D 와 통신한다.

Direct3D DDK 에는, 플러그 가능한 소프트웨어 디바이스를 개발하기 위한 문서와 헤더가 준비되어 있다.


디바이스의 동작

Microsoft® Direct3D® 에서는, 디바이스의 종류에 가세해, 디바이스의 동작도 지정할 수 있다. IDirect3D8::CreateDevice 메소드에서는, 1 개(살) 또는 복수의 동작 플래그를 조합해 Direct3D 디바이스의 글로벌인 동작을 제어할 수 있다. 이러한 동작에 의해 Direct3D 의 런타임 부분에서 보관 유지되는 것과 보관 유지되지 않는 것이 지정되어 디바이스의 종류에 의해 사용하는 드라이버가 지정된다. 디바이스 동작의 편성안에는 유효하지 않은 것도 있지만, 모든 디바이스의 종류로 모든 디바이스의 동작을 사용할 수 있다. 예를 들어, D3DCREATE_PUREDEVICE 로 생성 된 디바이스에 D3DDEVTYPE_SW 를 지정할 수 있다.


디바이스로 지원 되는 프리미티브의 종류

Microsoft® Direct3D® 디바이스에서는, 이하의 타입의 프리미티브를 생성 및 조작할 수 있다.

  • 포인트 리스트
  • 선리스트
  • 선스트립
  • 삼각형 리스트
  • 삼각형 스트립
  • 삼각형 팬

C++ 어플리케이션의 프리미티브는,IDirect3DDevice8 인터페이스의 렌더링 메소드를 사용해 렌더링 할 수 있다. 상세한 것에 대하여는, 「렌더링」을 참조할것.

인덱스 첨부 프리미티브 렌더링 메소드를 사용해, 포인트 리스트를 렌더링 할 수 없다.


포인트 리스트

포인트 리스트란, 개개의 포인트로서 렌더링 되는 버텍스의 집합이다. 어플리케이션에서는, 별의 필드 또는 다각형의 표면 위에의 점선에, 3D 신의 포인트 리스트를 사용할 수 있다.

다음의 그림은, 렌더링 되는 포인트 리스트를 나타내고 있다.

포인트 리스트에는 머트리얼과 텍스쳐를 적용할 수 있다. 머트리얼 또는 텍스쳐의 색은, 드로잉(Drawing) 된 포인트에서만 표시되어 포인트와 포인트의 사이에는 표시되지 않는다.

다음의 코드는, 포인트 리스트에 대해서 버텍스를 생성 하는 방법을 나타내고 있다.

struct CUSTOMVERTEX
{
    float x, y, z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5. 0, -5. 0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5. 0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5. 0, 0.0},
    {20.0,  5.0, 0.0}
};

다음의 코드는,IDirect3DDevice8::DrawPrimitive 를 사용해, 포인트 리스트를 렌더링 하는 방법을 나타내고 있다.

//
// d3dDevice 는, IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
//
d3dDevice->DrawPrimitive( D3DPT_POINTLIST, 0, 6 );


선리스트

선리스트란, 개개의 직선의 선분의 리스트이다. 선리스트는, 3D 신으로 진눈깨비나 큰 비를 표현 하면나무 등에 편리하다. 어플리케이션에서는, 버텍스의 배열에 값을 설정하는 것으로 선리스트를 생성 한다. 선리스트의 버텍스의 수는, 2 이상의 짝수가 아니면 안된다.

다음의 그림은, 렌더링 되는 선리스트를 나타내고 있다.

선리스트에는 머트리얼과 텍스쳐를 적용할 수 있다. 머트리얼 또는 텍스쳐의 색은, 드로잉(Drawing) 된 선에 따라서만 표시되어 선과 선의 사이에는 표시되지 않는다.

다음의 코드는, 선리스트에 대해서 버텍스를 생성 하는 방법을 나타내고 있다.

struct CUSTOMVERTEX
{
    float x, y, z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5. 0, -5. 0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5. 0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5. 0, 0.0},
    {20.0,  5.0, 0.0}
};

다음의 코드는,IDirect3DDevice8::DrawPrimitive 를 사용해, 선리스트를 렌더링 하는 방법을 나타내고 있다.

//
// d3dDevice 는, IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
//
d3dDevice->DrawPrimitive( D3DPT_LINELIST, 0, 3 );


선스트립

선스트립이란, 선분 끼리를 결합한 것으로부터 구성되는 원시적이다. 선스트립을 사용해, 닫지 않은 다각형을 생성 할 수 있다. 닫은 다각형이란, 마지막 버텍스가 최초의 버텍스와 선분으로 결합되고 있는 다각형이다. 선스트립에 근거해 다각형을 생성 하는 경우, 그 다각형의 버텍스가 동일 평면상에 있다고는 할 수 없다.

다음의 그림은, 렌더링 되는 선스트립을 나타내고 있다.

다음의 코드는, 선스트립에 대해서 버텍스를 생성 하는 방법을 나타내고 있다.

struct CUSTOMVERTEX
{
    float x, y, z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5. 0, -5. 0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5. 0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5. 0, 0.0},
    {20.0,  5.0, 0.0}
};

다음의 코드는,IDirect3DDevice8::DrawPrimitive 를 사용해, 선스트립을 렌더링 하는 방법을 나타내고 있다.

//
// d3dDevice 는, IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
//
d3dDevice->DrawPrimitive( D3DPT_LINESTRIP, 0, 5 );


삼각형 리스트

삼각형 리스트란, 개개의 삼각형의 리스트이다. 삼각형은 서로 인접하고 있어도 떨어져 있어도 괜찮다. 삼각형 리스트에는, 적어도 3 개의 버텍스가 필요하다. 버텍스의 총수는 3 의 배수가 아니면 안된다.

독립한 요소로부터 구성되는 오브젝트의 생성에는, 삼각형 리스트를 사용한다. 예를 들어, 3D 게임에서 전자력계벽을 생성 하려면 , 단독의 작은 삼각형을 다수 모은 리스트를 지정한다. 다음에, 이 삼각형 리스트에 머트리얼이나 텍스쳐를 적용해, 미츠를 출발하고 있도록(듯이) 보이게 한다. 벽의 삼각형 각각이 빛나 보이게 된다. 플레이어가 전자력계라고는 이렇게 보일 것이라고 기대 하면 우리에, 벽의 배후의 장면이 삼각형의 사이의 틈새를 통해 부분적으로 보이게 된다.

또, 삼각형 리스트는, gouraud shading로 음영을 붙인, 날카로운 엣지를 가지는 프리미티브를 생성 할 경우에 편리하다. 「면법선 벡터와 버텍스 법선 벡터」를 참조할것.

다음의 그림은, 렌더링 되는 삼각형 리스트를 나타내고 있다.

다음의 코드는, 삼각형 리스트에 대해서 버텍스를 생성 하는 방법을 나타내고 있다.

struct CUSTOMVERTEX
{
    float x, y, z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5. 0, -5. 0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5. 0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5. 0, 0.0},
    {20.0,  5.0, 0.0}

};

다음의 코드는,IDirect3DDevice8::DrawPrimitive 를 사용해, 삼각형 리스트를 렌더링 하는 방법을 나타내고 있다.

//
// d3dDevice 는, IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
//
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, 2 );


삼각형 스트립

삼각형 스트립이란, 일련의 결합된 삼각형이다. 삼각형은 결합되고 있기 (위해)때문에, 각 삼각형에 대해서 3 개의 버텍스 모든 것을 어플리케이션으로 반복해 지정할 필요는 없다. 예를 들어, 다음의 삼각형 스트립을 정의하는 경우, 필요한 것은 7 개의 버텍스 뿐이다.

시스템에서는, 버텍스의 v1, v2, v3 를 사용해 최초의 삼각형을, v2, v4, v3 를 사용해 2 번째의 삼각형을, v3, v4, v5 를 사용해 3 번째의 삼각형을, v4, v6, v5 를 사용해 4 번째의 삼각형을, 이라고 하는 순서로 드로잉(Drawing) 해 나간다. 2 번째와 4 번째의 삼각형의 버텍스가 순서 대로가 아닌 것에 주의한다. 이것은, 모든 삼각형이 시계회전의 방향으로 드로잉(Drawing) 되는 것을 보증하기 위해서 필요하다.

3D 신의 대부분의 오브젝트는 삼각형 스트립으로 구성되어 있다. 이것은, 삼각형 스트립을 사용해 복잡한 오브젝트를 지정 하면, 메모리를 효율적으로 이용해 처리 시간을 단축할 수 있기 때문이다.

다음의 그림은, 렌더링 되는 삼각형 스트립을 나타내고 있다.

다음의 코드는, 삼각형 스트립에 대해서 버텍스를 생성 하는 방법을 나타내고 있다.

struct CUSTOMVERTEX
{
    float x, y, z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5. 0, -5. 0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5. 0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5. 0, 0.0},
    {20.0,  5.0, 0.0}
};

다음의 코드는,IDirect3DDevice8::DrawPrimitive 를 사용해, 삼각형 스트립을 렌더링 하는 방법을 나타내고 있다.

//
// d3dDevice 는, IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
//
d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0, 5 );


삼각형 팬

삼각형 팬이란, 다음의 그림에 나타내도록(듯이), 모든 삼각형이 1 개의 버텍스를 공유 하면 말하는 점을 제외해서는, 삼각형 스트립에 유사한 것이다.

시스템에서는, 버텍스 v2, v3, v1 를 사용해 최초의 삼각형을, v3, v4, v1 를 사용해 2 번째의 삼각형을, v4, v5, v1 를 사용해 3 번째의 삼각형을, 이라고 하는 순서로 드로잉(Drawing) 해 나간다. flat shading가 유효한 경우, 삼각형은 최초의 버텍스의 색으로 쉐이딩 된다.

다음의 그림은, 렌더링 되는 삼각형 팬을 나타내고 있다.

다음의 코드는, 삼각형 팬에 대해서 버텍스를 생성 하는 방법을 나타내고 있다.

struct CUSTOMVERTEX
{
    float x, y, z;
};

CUSTOMVERTEX Vertices[] =
{
    { 0.0, 0.0, 0.0},
    {-5. 0, -5. 0, 0.0},
    {-3. 0,  7.0, 0.0},
    { 0.0, 10.0, 0.0},
    { 3.0,  7.0, 0.0},
    { 5.0,  5.0, 0.0},
};

다음의 코드는,IDirect3DDevice8::DrawPrimitive 를 사용해, 삼각형 팬을 렌더링 하는 방법을 나타내고 있다.

//
// d3dDevice 는, IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
//
d3dDevice->DrawPrimitive( D3DPT_TRIANGLEFAN, 0, 4 );


디바이스의 사용법

여기에서는, 어플리케이션에 있어서의 Microsoft® Direct3D® 디바이스의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 하드웨어 지원의 판정
  • 디바이스의 선택
  • 디바이스의 생성
  • 트랜스 폼의 설정
  • 버텍스 데이터의 처리
  • 마우스 커서의 조작
  • 렌더링


하드웨어 지원의 판정

Direct3D 에서는, 다음의 기능에 의해 하드웨어 지원을 판정한다.

IDirect3D8::CheckDeviceFormat
표면 포맷이, 텍스쳐로서 사용할 수 있을지 어떨지, 텍스쳐와 렌더링 타겟으로서 사용할 수 있을지 어떨지, 및 스텐실 버퍼로서 사용할 수 있을지 어떨지를 검증하기 위해서 사용한다. 게다가 깊이 버퍼 포맷 지원과 스텐실 버퍼 포맷 지원을 검증하는 경우에도, 이 메소드를 사용한다.
IDirect3D8::CheckDeviceType
디바이스가, 하드웨어 가속화를 실행할 수 있을지 어떨지, 프레젠테이션의 스왑 체인을 생성 할 수 있을지 어떨지, 현재의 디스플레이 포맷에 렌더링 할 수 있을지 어떨지를 검증하기 위해서 사용한다.
IDirect3D8::CheckDepthStencilMatch
스텐실 버퍼 포맷이 렌더링 타겟 포맷과 호환성이 있을지 어떨지를 검증하기 위해서 사용한다. 이 메소드를 호출하기 전에, 어플리케이션으로부터 스텐실과 렌더링 타겟의 양쪽 모두의 포맷에 대해서 CheckDeviceFormat 를 호출할 필요가 있는 것에 주의 해야 한다.


디바이스의 선택

어플리케이션은, 지원 되고 있는 Microsoft® Direct3D® 디바이스 타입을 하드웨어에 조회해 검출할 수 있다. 여기에서는, 디스플레이 어댑터의 열거와 Direct3D 디바이스의 선택에 관련되는 기본 태스크에 대해 설명한다.

어플리케이션은, 적절한 Direct3D 디바이스를 선택하기 위한 일련의 태스크를 실행할 필요가 있다. 이하의 스텝은, 풀 스크린 어플리케이션의 태스크이다. 많은 경우, 윈도우 어플리케이션에서는 이러한 스텝의 대부분을 생략 할 수 있다.

  1. 최초로, 어플리케이션은 시스템 위에의 디스플레이 어댑터를 열거할 필요가 있다. 어댑터는, 하드웨어의 물리적 부품이다. 듀얼 헤드 디스플레이의 경우와 같이, 그래픽 카드에 복수의 어댑터가 탑재되고 있는 경우도 있으므로 주의 해야 한다. 멀티 모니터 지원에 관련하지 않는 어플리케이션에서는, 이 스텝을 무시해, 스텝 2 로 IDirect3D8::EnumAdapterModes 메소드에 D3DADAPTER_DEFAULT 를 건네준다.
  2. 어플리케이션은, 어댑터 마다 EnumAdapterModes 를 호출해, 그 어댑터가 지원 하는 디스플레이 모드를 열거한다.
  3. 필요에 따라서,IDirect3D8::CheckDeviceType 를 호출해, 열거된 각 디스플레이 모드에 하드웨어 가속화가 존재할지 어떨지를 체크한다. 이것에 대해서는, 다음의 코드에 나타낸다. 이것은 CheckDeviceType 로 사용할 수 있는 방법의 1 개에 지나지 않는다. 상세한 것에 대하여는, 「하드웨어 지원의 판정」을 참조할것.
    D3DPRESENT_PARAMETERS Params;
// D3DPRESENT_PARAMETERS 멤버의 값을 초기화한다.

Params.BackBufferFormat = D3DFMT_X1R5G5B5;

if(FAILED(m_pD3D->CheckDeviceType(Device.m_uAdapter,
                                  Device.m_DevType,
                                  Params.BackBufferFormat, Params.BackBufferFormat,
                                  FALSE)))
        return E_FAIL;
  4. 어플리케이션은 IDirect3D8::GetDeviceCaps 메소드를 호출해, 이 어댑터의 디바이스에 필요한 레벨의 능력이 있는지 체크한다. 이 메소드에 의해, 필요한 능력을 지원 하고 있지 않는 디바이스가 선택 대상에서 제외해진다. GetDeviceCaps 에 의해 돌려주어지는 디바이스 능력은,CheckDeviceType 로 검증된 모든 디스플레이 모드에 대해, 디바이스 마다 일정하는 것이 보증되고 있다.
  5. 디바이스는 항상, 그 디바이스가 지원 하는 포맷으로서 열거된 디스플레이 모드의 포맷을 가지는 표면에 렌더링 한다. 다른 포맷의 표면에 렌더링 하는 경우는,IDirect3D8::CheckDeviceFormat 를 호출한다. 디바이스가 그 포맷에 렌더링 할 수 있는 경우는,GetDeviceCaps 가 돌려주는 모든 능력이 적용 가능하다라고 하는 것이 보증된다.
  6. 마지막으로,IDirect3D8::CheckDeviceMultiSampleType 메소드를 사용해, 렌더링 포맷으로 풀 신 anti-aliasing등의 멀티 샘플링 테크닉이 지원 되고 있는지 어떤지를 판정할 수 있다.

위의 스텝을 완료 하면, 어플리케이션에서는, 처리할 수 있는 디스플레이 모드의 리스트가 완성한다. 마지막 스텝에서는, 디바이스가 액세스 가능한 메모리에, 필요한 수의 버퍼와 anti-aliasing를 확보할 수 있는 스페이스가 있을지 어떨지를 검증한다. 이 테스트를 필요로 하는 이유는, 모드와 멀티 샘플의 편성에 의해 소비되는 메모리량이, 실제로 검증하는 이외 방법에서는 예측 불가능하기 때문에이다. 게다가 디스플레이 어댑터의 아키텍쳐에 따라서는, 일정량의 디바이스 액세스 가능한 메모리가 준비되어 있지 않은 것이 있다. 즉, 풀 스크린 모드로 이행할 때 비디오 메모리 장해가 발생했을 경우는, 어플리케이션이 리포트할 필요가 있다. 일반적으로는, 어플리케이션이 유저에게 제공하는 모드 리스트로부터 풀 스크린 모드를 삭제하는지, 또는 사용하는 백 버퍼의 수를 줄이거나 메모리 소비의 적은 멀티 샘플 테크닉을 사용해, 메모리 소비량의 삭감을 꾀한다.

윈도우 어플리케이션에서도 같은 일련의 태스크를 실행한다.

  1. 윈도우의 클라이언트 영역에 맞는 데스크탑 직사각형을 결정한다.
  2. 어댑터를 열거해, 클라이언트 영역에 맞는 모니터를 사용하는 어댑터를 찾는다. 클라이언트 영역이 복수의 어댑터에 의해 소유되고 있는 경우는, 각 어댑터를 개별적으로 구동하는 방법인가, 1 개의 어댑터를 구동해, 프레젠테이션시에는 Direct3D 에 의해 디바이스로부터 디바이스에 픽셀을 전송 하는 방법인지를 선택할 수 있다. 또 전술의 2 개의 스텝을 무시해, D3DADAPTER_DEFAULT 를 어댑터를 사용하는 방법도 있다. 이 방법에서는, 윈도우가 세칸다리모니타상에 배치되면(자) 처리 속도가 늦어지는 경우가 있다.
  3. 어플리케이션은, 데스크탑 모드중에 CheckDeviceType 를 호출해, 디바이스가 지정된 포맷의 백 버퍼에의 렌더링을 지원 할 수 있을지 어떨지를 판정해야 한다. 다음의 코드에 나타내도록(듯이),IDirect3D8::GetAdapterDisplayMode 를 사용해, 데스크탑의 디스플레이 포맷을 판정할 수가 있다.
    D3DPRESENT_PARAMETERS Params;
// D3DPRESENT_PARAMETERS 멤버의 값을 초기화한다.

// 현재의 디스플레이 모드를 사용한다.
D3DDISPLAYMODE mode;

if(FAILED(m_pD3D->GetAdapterDisplayMode(Device.m_uAdapter , &mode)))
        return E_FAIL;

Params.BackBufferFormat = mode.Format;

if(FAILED(m_pD3D->CheckDeviceType(Device.m_uAdapter, Device.m_DevType,
Params.BackBufferFormat, Params.BackBufferFormat, FALSE)))
       return E_FAIL;


디바이스의 생성

주 지정의 Microsoft® Direct3D® 오브젝트에 의해 생성 된 렌더링 디바이스는, 모두 같은 물리 리소스를 공유한다. 단일의 Direct3D 오브젝트로부터 복수의 렌더링 디바이스를 생성 하는 것은 가능하지만, 이것들은 모두 같은 하드웨어를 공유하기 위해(때문에), 퍼포먼스가 크게 저하한다.

C++ 어플리케이션으로 Direct3D 디바이스를 생성 하려면 , 「Direct3D 에의 액세스」로 설명하도록(듯이), 우선 Direct3D 오브젝트를 생성 할 필요가 있다.

우선, Direct3D 디바이스의 생성에 사용하는 D3DPRESENT_PARAMETERS 구조체의 값을 초기화한다. 다음의 코드는, VSYNC 에서만 백 버퍼가 프런트 버퍼에 플립 되는 윈도우 어플리케이션을 지정한다.

LPDIRECT3DDEVICE8 d3dDevice = NULL;

D3DPRESENT_PARAMETERS d3dpp;

ZeroMemory( &d3dpp, sizeof(d3dpp) );
d3dpp.Windowed   = TRUE;
d3dpp.SwapEffect = D3DSWAPEFFECT_COPY_VSYNC;

다음에, Direct3D 디바이스를 생성 한다. 다음의 IDirect3D8::CreateDevice 호출은, 디폴트 어댑터, 하드웨어 추상 계층 (HAL) 디바이스, 및 소프트웨어 버텍스 처리를 지정한다.

if( FAILED( g_pD3D->CreateDevice( D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd,
                                  D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                                      &d3dpp, &d3dDevice ) ) )
    return E_FAIL;

디바이스의 생성, 해방, 또는 리셋을 위한 호출은, 포커스 윈도우의 윈도우 프로시저와 같은 thread에서만 실시하도록(듯이) 주의 해야 한다.

디바이스 생성 후는, 그 스테이트를 설정한다.


트랜스 폼의 설정

C++ 에서는, Direct3DDevice8.SetTransform 메소드를 호출해 트랜스 폼을 적용한다. 예를 들어, 뷰 트랜스 폼을 설정하려면 , 다음과 같은 코드를 사용한다.

HRESULT    hr;
D3DMATRIX  view;

// 뷰 행렬에 데이터를 설정한다.

hr = pDev->SetTransform(D3DTS_VIEW, &view);

if(FAILED(hr))
{
    // 에러 처리 코드.
}

SetTransform 를 호출하는 경우, 제 1 파라미터로 설정할 수 있는 값은 몇개인가 있지만, 일반적으로는, D3DTS_WORLD, D3DTS_VIEW, 및 D3DTS_PROJECTION 를 설정한다. 이러한 트랜스 폼 스테이트는,D3DTRANSFORMSTATETYPE 열거형에 정의되고 있다. 이 열거에는 D3DTS_TEXTURE1 로부터 D3DTS_TEXTURE7 까지의 스테이트도 포함된다. 이것들을 사용해, 텍스쳐 좌표에 트랜스 폼을 적용할 수 있다.


버텍스 데이터의 처리

IDirect3DDevice8 인터페이스는, 소프트웨어와 하드웨어 양쪽 모두에서의 버텍스 처리를 지원 한다. 일반적으로, 소프트웨어와 하드웨어의 버텍스 처리에 관한 디바이스 능력은 같지 않다. 하드웨어의 능력은, 디스플레이 어댑터나 드라이버에 따라서 다르지만, 소프트웨어의 능력은 일정한다.

다음의 플래그는, 하드웨어 추상 계층 (HAL) 디바이스 및 레퍼런스 디바이스의 버텍스 처리 동작을 제어한다.

  • D3DCREATE_SOFTWARE_VERTEXPROCESSING
  • D3DCREATE_HARDWARE_VERTEXPROCESSING
  • D3DCREATE_MIXED_VERTEXPROCESSING

IDirect3D8::CreateDevice 를 호출하면나무는, 몇개의 버텍스 처리 동작 플래그를 지정한다. 믹스 모드 플래그에서는, 디바이스는 소프트웨어와 하드웨어 양쪽 모두의 버텍스 처리가 가능하게 된다. 1 개의 디바이스에 대해서, 한 번에 1 개의 버텍스 처리 플래그 밖에 설정할 수 없다. 퓨어 디바이스 (D3DCREATE_PUREDEVICE)를 생성 하면나무는, D3DCREATE_HARDWARE_VERTEXPROCESSING 플래그가 필요해서 주의 해야 한다.

단일 디바이스상에 2 개의 버텍스 처리 능력이 존재하지 않게 하기 위한(해), 실행시에는 하드웨어 버텍스 처리 능력만을 조회할 수 있다. 소프트웨어의 버텍스 처리 기능은 고정되어 실행시에 조회할 수 없다.

디바이스의 하드웨어 버텍스 처리 능력을 판정하려면 ,D3DCAPS8 구조체의 VertexProcessingCaps 멤버를 조사한다. 소프트웨어 버텍스 처리에 대해서는, 이하의 능력이 지원 되고 있다.

  • D3DVTXPCAPS_DIRECTIONALLIGHTS
  • D3DVTXPCAPS_LOCALVIEWER
  • D3DVTXPCAPS_MATERIALSOURCE7
  • D3DVTXPCAPS_POSITIONALLIGHTS
  • D3DVTXPCAPS_TEXGEN
  • D3DVTXPCAPS_TWEENING

또, 다음의 표는, 소프트웨어 버텍스 처리 모드의 디바이스에 대해서,D3DCAPS8 구조체의 멤버로 설정되는 값을 나타내고 있다.

멤버 | 소프트웨어 버텍스 처리 능력
MaxActiveLights | 제한 없음
MaxUserClipPlanes | 6
MaxVertexBlendMatrices | 4
MaxStreams | 16
MaxVertexIndex | 0xFFFFFFFF

소프트웨어 버텍스 처리에서는, 제한 없음의 라이트수나 프로그램 가능한 버텍스 쉐이더 등, 보증 끝난 버텍스 처리 능력 세트가 제공된다. 소프트웨어 버텍스 처리와 하드웨어 버텍스 처리는,HAL 디바이스 (하드웨어 버텍스 처리와 소프트웨어 버텍스 처리의 양쪽 모두를 지원 하는 유일한 디바이스 타입)를 사용해 언제라도 바꿀 수가 있다. 유일한 요건으로서 소프트웨어 버텍스 처리에 사용하는 버텍스 버퍼는, 시스템 메모리내에 할당할 수 있지 않으면 안 된다.

주 하드웨어 버텍스 처리의 퍼포먼스는, 소프트웨어 버텍스 처리의 퍼포먼스에 필적한다. 이 때문에, 동일 디바이스 타입내에서 버텍스 처리를 위한 하드웨어 에뮬레이션 기능과 소프트웨어 에뮬레이션 기능의 양쪽 모두를 제공 하면이야 있고. 이것은 라스터화에는 적용되지 않는다. 라스터화에서는, 호스트 프로세서에 의한 처리 속도는 그래픽스 전용 하드웨어보다 저속이다. 따라서, 하드웨어 에뮬레이션과 소프트웨어 에뮬레이션의 라스터화의 양쪽 모두를 단일 디바이스 타입내에서 제공할 것은 없다. 단일 디바이스내의 런타임과 하드웨어 (드라이버)에 중복 하는 기능은, 소프트웨어 버텍스 처리뿐이다. 따라서, 다른 디바이스 능력은 모두, 드라이버에 의해 제공되는 잠재적으로 다른 기능이다.


마우스 커서의 조작

마우스 커서 메소드에 의해, 어플리케이션은, 화면을 저장 하는 표면을 제공하는 것에 의해 칼라 커서를 지정할 수 있다. 어플리케이션의 frame rate가 저속의 경우, 이 커서는 디스플레이 레이트의 반이상의 간격으로 시스템에 의해 갱신된다. 다만, 커서의 갱신 빈도는, 모니터의 refresh rate보다 짧아질 것은 없다.

마우스 커서의 위치는 시스템 커서에 결합되고 있는 (현재의 디스플레이 모드의 공간상의 해상도에 맞추어 적당 스케일링 된다)가, 어플리케이션에 의해 명시적으로 이동할 수가 있다. 이것은, Microsoft®Win32® API 지원 시스템 마우스 커서의 동작에 유사하고 있다. Microsoft® Direct3D® 어플리케이션에 있어서의 마우스 커서의 사용 방법에 대해서는, 이하의 레퍼런스 주제를 참조할것.

  • IDirect3DDevice8::ShowCursor
  • IDirect3DDevice8::SetCursorPosition
  • IDirect3DDevice8::SetCursorProperties

하드웨어의 이행, 또는 IDirect3DDevice8::Present 를 호출했을 때에 하드웨어 가속화에 의한 소총탄 처리를 실행하는 Direct3D 런타임에 의해, Direct3D 에서는 마우스를 지원 하고 있다.


렌더링

어플리케이션에서는, 일련의 DrawPrimitive 의 메소드를 사용해 3D 신을 렌더링 한다. DrawPrimitive 에 의한 렌더링에 대해서는, 다음의 주제로 나누어 설명한다.

  • 표면의 클리어
  • 장면의 시작과 엔딩
  • 장면의 프레젠테이션
  • 프리미티브의 렌더링


표면의 클리어

장면의 오브젝트를 렌더링 하기 전에, 렌더링 타겟 표면의 뷰 포토 또는 뷰 포토의 서브 세트를 클리어 한다. 뷰 포토를 클리어 하면, 시스템은 렌더링 타겟 표면의 드로잉(Drawing) 부분, 및 어태치 된 깊이 버퍼 또는 스텐실 버퍼를 지정의 스테이트로 설정한다. 그 결과, 재차 렌더링 하는 표면의 영역이 리셋 되어 깊이 버퍼와 스텐실 버퍼를 사용하고 있는 경우는, 그 대응하는 영역이 리셋 된다. 렌더링 타겟 표면을 클리어 하면, 지정한 영역을 디폴트의 색이나 텍스쳐로 설정할 수 있다. 깊이 버퍼 및 스텐실 버퍼에 대해서는, 깊이 및 스텐실값을 설정할 수 있다.

뷰 포토의 클리어에는,IDirect3DDevice8::Clear 메소드를 사용한다.

이 메소드의 사용 방법에 대해서는, 「뷰 포토의 클리어」를 참조할것.

최적화에 관한 주의 렌더링 타겟 표면의 전영역에 이르는 장면을 렌더링 하는 어플리케이션으로, 퍼포먼스를 개선하려면 , 렌더링 타겟은 아니고, 어태치 된 깊이 및 스텐실 버퍼 표면 (있는 경우)을 클리어 한다. 이 경우, 깊이 버퍼를 클리어 하면, Microsoft® Direct3D® 는 다음에 렌더링 하는 프레임에 렌더링 타겟을 재기입하는 것으로, 렌더링 타겟으로 대하는 명시적인 클리어 처리를 장황하게 한다. 다만, 렌더링 타겟 표면의 일부에게만 렌더링 하는 경우는, 명시적인 클리어 처리가 필요하다.


장면의 시작과 엔딩

C++ 로 기술된 어플리케이션에서는,IDirect3DDevice8::BeginScene 메소드를 호출해, Microsoft® Direct3D® 에 장면의 렌더링의 시작을 알린다. BeginScene 를 호출하면, 시스템은 그 내부 데이터 구조 및 렌더링 스테이트의 가용성과 유효성을 체크한다. 또, 장면이 진행중인 것을 전하는 내부 플래그를 설정한다. 장면의 시작 후는, 다양한 렌더링 메소드를 호출해 프리미티브를 렌더링 하거나 장면의 오브젝트를 구성하는 버텍스를 개별적으로 렌더링 할 수가 있다. 장면의 처리중이 아닐 때에 렌더링 메소드를 호출하려고 하면 실패한다. 상세한 것에 대하여는, 「프리미티브의 렌더링」을 참조할것.

장면이 완료하면(자),IDirect3DDevice8::EndScene 메소드를 호출한다. EndScene 메소드는, 캐쉬되고 있는 데이터를 플래시 해, 렌더링 표면의 완전성을 검증해, 장면이 진행중인 것을 전하는 내부 플래그를 클리어 한다.

렌더링 메소드는 모두,BeginScene 메소드를 호출하고 나서 EndScene 메소드를 호출할 때까지 에 실행해야 한다. 표면이 없어지는지, 또는 내부 에러가 발생 하면, 장면의 메소드는 에러값을 돌려준다. BeginScene 메소드가 실패했을 경우, 장면은 시작 되지 않고, 거기에 계속되는 EndScene 의 호출도 실패한다.

이러한 케이스를 이하에 정리한다.

  • BeginScene 가 어떠한 에러를 돌려주었을 경우, 장면은 정상적으로 시작되어 있지 않기 때문에,EndScene 를 호출해서는 안 된다.
  • BeginScene 는 성공했지만 장면의 렌더링중에 에러가 발생했을 경우,EndScene 를 호출할 필요가 있다.
  • 어떠한 이유로써 EndScene 가 실패했을 경우는, 이것을 재차 호출할 필요는 없다.

예를 들어, 다음에 나타내는 것은, 단순한 장면을 처리하는 코드이다.

HRESULT hr;

if(SUCCEEDED(pDevice->BeginScene()))
{
    // 장면의 시작에 성공했을 경우만,
    // 프리미티브를 렌더링 한다.

    // 장면을 닫는다.
    hr = pDevice->EndScene();
    if(FAILED(hr))
        return hr;
}

장면을 묻을 수 없다. 즉, 다음의 장면을 렌더링 하려면 , 현재 렌더링중의 장면을 완료할 필요가 있다. BeginScene 가 불려 가지 않았는데 EndScene 를 호출했을 경우, 에러가 돌려주어진다. 같이 전의 장면이 EndScene 메소드로 아직 완료하고 있지 않을 때에 BeginScene 를 호출하면, 에러가 발생한다.

장면의 렌더링중 (BeginScene 를 호출하고 나서 EndScene 를 호출할 때까지 ), 렌더링 타겟이나 텍스쳐등의 Direct3D 표면에 대해서 GDI 함수를 호출해서는 안 된다. 이 함수를 호출하려고 하면, GDI 조작의 결과가 표시되지 않게 될 가능성이 있다. 어플리케이션으로 GDI 함수를 사용하는 경우는, 장면 함수의 밖에서 모든 GDI 의 호출을 실시하도록(듯이) 한다.


장면의 프레젠테이션

여기에서는, 프레젠테이션 API (어플리케이션 프로그래밍 인터페이스)와 디스플레이에의 장면의 프레젠테이션에 관한 문제에 대해 설명한다.

설명하는 주제는, 다음과 같다.

  • 장면의 프레젠테이션의 개요
  • 윈도우 모드의 멀티 뷰
  • 멀티 모니터 처리
  • 깊이 버퍼의 조작
  • 칼라 프런트 버퍼에의 액세스


장면의 프레젠테이션의 개요

프레젠테이션의 어플리케이션 프로그래밍 인터페이스 (API)는, 모니터 표시에 영향을 주는 디바이스 스테이트를 제어하는 메소드세트이다. 이러한 메소드로서 표시 설정 모드나, 화면 표시를 위한 프레임 단위의 메소드등이 있다.

  • IDirect3DDevice8::Present
  • IDirect3DDevice8::Reset
  • IDirect3DDevice8::GetGammaRamp
  • IDirect3DDevice8::SetGammaRamp
  • IDirect3DDevice8::GetRasterStatus

프레젠테이션 API 를 이해하려면 , 다음의 용어를 알 필요가 있다.

  • 프런트 버퍼. 그래픽스 어댑터에 의해 변환되어 모니터 또는 다른 출력 디바이스에 표시되는 메모리의 직사각형.
  • 백 버퍼. 표면의 내용이 프런트 버퍼에 보내진다.
  • 스왑 체인. 백 버퍼의 집합체이며, 차례로 프런트 버퍼에 제시된다. 일반적으로, 풀 스크린 스왑 체인은 플립 DDI 로 연속하는 화면을 제시해, 윈도우 스왑 체인은 소총탄 DDI 로 화면을 제시한다.

Microsoft® Direct3D® for Microsoft DirectX® 8.0 은, 디바이스의 프로퍼티로서 1 개의 스왑 체인을 가지기 (위해)때문에, 각 디바이스에는 항상 적어도 1 개의 스왑 체인이 있다. IDirect3DDevice8 인터페이스에는, 비명시적인 스왑 체인을 조작하는 메소드 세트가 있다. 이 메소드 세트는, 스왑 체인 독자적인 인터페이스의 카피이다. 어플리케이션에서는 추가 스왑 체인을 생성 할 수 있지만, 일반의 단일 윈도우나 풀 스크린의 어플리케이션에서는 필요없다.

Direct3D API for DirectX 8.0 에서는, 프런트 버퍼에 직접 공개할 수 없다. 따라서, 어플리케이션은, 프런트 버퍼를 잠그거나 프런트 버퍼에 렌더링 할 수 없다. 상세한 것에 대하여는, 「칼라 프런트 버퍼에의 액세스」를 참조할것.

주 DirectX 7. x 에는, 조합해 불려 가는 프레젠테이션 API 가 몇개인가 존재했다. IDirectDraw7::SetCooperativeLevel,IDirectDraw7::SetDisplayMode, 및 IDirectDraw7::CreateSurface 에 의한 순서는 그 좋은 예이다. 또,IDirectDrawSurface7::Flip 메소드와 IDirectDrawSurface7::Blt 메소드의 편성에 의해, 렌더링 된 프레임을 모니터에 전송 하는 것을 알렸다. DirectX 8.0 에서는, 이러한 API 그룹을,Reset 와 Present 의 2 개의 메인 메소드에 분할했다. Reset 에는,SetCooperativeLevel,SetDisplayMode,CreateSurface, 그리고 Flip 에의 몇개의 파라미터가 포함되어 있다. Present 에는,Flip 와Blt 의 프레젠테이션의 사용이 포함되어 있다.

IDirect3D8::CreateDevice 호출은, 디바이스의 비명시적인리셋을 나타낸다. DirectX 8.0 API 에는 프라이머리 표면의 개념은 없고, 프라이머리 표면을 나타내는 오브젝트를 생성 할 수 없다. 프라이머리 표면은, 디바이스의 내부 프로퍼티라고 보여진다.

감마 램프는 스왑 체인에 관련지을 수 있어IDirect3DDevice8::GetGammaRamp 및 IDirect3DDevice8::SetGammaRamp 메소드로 조작한다.


윈도우 모드의 멀티 뷰

Direct3DDevice 오브젝트를 개입시켜 소유해 조작할 수 있는 스왑 체인에 가세해,IDirect3DDevice8::CreateAdditionalSwapChain 메소드를 사용해, 같은 디바이스로부터 복수의 뷰에 제시하기 위한 추가 스왑 체인을 생성 할 수 있다.

일반적으로, 어플리케이션은 뷰 마다 1 개의 스왑 체인을 생성 해, 그 스왑 체인을 특정의 뷰에 관련짓는다. 어플리케이션에서는, 각 스왑 체인의 백 버퍼에 화면을 렌더링 해,IDirect3DDevice8::Present 메소드를 사용해 그것을 1 개씩 제시한다. 어댑터 마다 한 번에 1 개의 스왑 체인 밖에 풀 스크린으로 할 수 없는 것에 주의 해야 한다.


멀티 모니터 처리

풀 스크린 처리에 대해 디바이스의 리셋 (IDirect3DDevice8::Reset ) 또는 생성 (IDirect3D8::CreateDevice )에 성공하면(자), 그 디바이스를 생성 한 Microsoft® Direct3D® 오브젝트가 시스템 위에의 모든 어댑터를 소유하고 있는 것으로서 마크 된다. 이 상태는 배타 모드로 불려 Direct3D 오브젝트는 배타 모드를 소유하고 있다. 배타 모드에서는, 다른 Direct3D 오브젝트에 의해 생성 된 디바이스가 풀 스크린 처리를 실시하거나 비디오 메모리를 할당할 수 없다. 또, 어느 Direct3D 오브젝트가 배타 모드이다고 보여졌을 때, 풀 스크린이 된 이외외의 디바이스는 소실 상태가 된다. 상세한 것에 대하여는, 「소실한 디바이스」를 참조할것.

배타 모드에서는, Direct3D 오브젝트에, 디바이스가 사용하는 포커스 윈도우를 알게 된다. 그 Direct3D 오브제쿳트가 소유하는 마지막 풀 스크린 디바이스가 윈도우 모드에 리셋 될까 파기되면(자), 배타 모드는 해방된다.

Direct3D 오브젝트가 배타 모드를 소유 하면 와, 디바이스는 2 개의 카테고리로 분류된다. 최초의 카테고리의 디바이스에는, 이하의 특성이 있다.

  • 풀 스크린의 디바이스를 생성 한 같은 Direct3D 오브젝트에 의해 생성 되고 있다.
  • 풀 스크린의 디바이스와 같은 포커스 윈도우를 가진다.
  • 어느 풀 스크린 디바이스와도 다른 어댑터를 나타낸다.

이 카테고리의 디바이스에는 리셋 처리나 생성 처리에 관한 제한은 없고, 소실 상태가 되지 않는다. 이 카테고리의 디바이스는, 풀 스크린 모드로 할 수도 있다.

최초의 카테고리에 들어가지 않는 디바이스 (다른 Direct3D 오브젝트에 의해 생성 되어 다른 포커스 윈도우로 생성 되어 이미 풀 스크린의 디바이스가 있는 어댑터에 생성 된 디바이스)는, 리셋 하지 못하고, 배타 모드가 없어질 때까지 소실 상태로부터 해방되지 않는다. 결과적으로, 멀티 모니터 어플리케이션에서는 복수의 디바이스를 풀 스크린 모드로 할 수 있지만, 그것은, 이러한 디바이스가 모두 다른 어댑터의 디바이스이며, 같은 Direct3D 오브젝트에 의해 생성 되어 게다가 같은 포커스 윈도우를 공유하는 경우에 한정된다.


깊이 버퍼의 조작

깊이 버퍼는 디바이스에 관련지을 수 있고 있다. 어플리케이션에서는, 렌더링 타겟을 설정할 경우에 깊이 버퍼를 이동할 필요가 있다. IDirect3DDevice8::GetDepthStencilSurface 및 IDirect3DDevice8::SetRenderTarget 메소드는, 깊이 버퍼의 조작에 사용한다.


칼라 프런트 버퍼에의 액세스

프런트 버퍼에의 액세스는,IDirect3DDevice8::GetFrontBuffer 메소드를 개입시켜 실시한다. 다만, 메소드는 제공되고 있어도, 테스트용인 것이 명시되고 있다. 따라서, 그 기능성은 보증되지 않는다.


프리미티브의 렌더링

여기에서는, DrawPrimitive 렌더링 메소드에 대해, 및 이 메소드의 어플리케이션에서의 사용 방법에 대해 설명한다.

  • 버텍스 데이터 스트림
  • 스트림 소스의 설정
  • 버텍스 버퍼 및 인덱스 버퍼로부터의 렌더링
  • 유저 메모리 포인터로부터의 렌더링


버텍스 데이터 스트림

Microsoft® Direct3D® 의 렌더링 인터페이스는, 1 개(살) 이상의 데이터 버퍼에 저장 된 버텍스 데이터로부터 프리미티브를 렌더링 하는 메소드로 구성된다. 버텍스 데이터는, 버텍스의 성분을 형성하는 버텍스 요소의 편성으로부터 완성된다. 버텍스 요소는 버텍스의 최소단위이며, 위치 좌표, 법선, 색등의 엔티티를 나타낸다.

버텍스의 성분이란, 단일 메모리 버퍼내에 연속적으로 (버텍스 마다 인터리브 되어) 저장 된 1 개(살) 이상의 버텍스 요소이다. 완전한 버텍스는, 각 성분이 각각 개별의 메모리 버퍼에 있는 1 개 이상의 성분으로부터 완성된다. 프리미티브를 렌더링 하기 위한(해), 복수의 버텍스의 성분이 읽어내져 버텍스 처리로 완전한 버텍스를 이용할 수 있도록(듯이) 조립할 수 있다. 다음의 그림은, 버텍스의 성분을 사용해 프리미티브를 렌더링 하는 처리를 나타내고 있다.

프리미티브의 렌더링에는, 2 개의 스텝이 있다. 우선, 1 개(살) 이상의 버텍스의 성분 스트림을 설정해, 다음에, 이러한 스트림으로부터 렌더링하기 위한 DrawPrimitive 메소드를 호출한다. 이러한 컴퍼넌트 스트림내에서의 버텍스 요소의 식별은, 버텍스 쉐이더에 의해 지정된다. 상세한 것에 대하여는, 「버텍스 쉐이더」를 참조할것.

DrawPrimitive 메소드는, 드로잉(Drawing)를 기동할 때마다, 어느 버텍스 데이터 세트내의 임의가 연속하는 프리미티브 서브 세트가 렌더링 되도록(듯이), 버텍스 데이터 스트림에 오프셋(offset)를 지정한다. 이것에 의해, 같은 버텍스 버퍼로부터 렌더링 되는 프리미티브의 그룹간으로, 디바이스 렌더링 스테이트를 변경할 수 있다.

인덱스 첨부 드로잉(Drawing) 메소드와 인덱스 없음 드로잉(Drawing) 메소드의 양쪽 모두가 지원 되고 있다. 상세한 것에 대하여는, 「버텍스 버퍼 및 인덱스 버퍼로부터의 렌더링」을 참조할것.

렌더링 인터페이스의 세칸다리셋트에서는, 버텍스 및 인덱스 데이터를 유저 메모리 포인터로부터 직접 렌더링 할 수 있다. 상세한 것에 대하여는, 「유저 메모리 포인터로부터의 렌더링」을 참조할것.


스트림 소스의 설정

IDirect3DDevice8::SetStreamSource 메소드는, 버텍스 버퍼를 디바이스 데이터 스트림에 바인드 해, 버텍스 데이터라고 프리미티브 처리 함수에 데이터를 제공하는 데이터 스트림 포토의 1 개를 관련짓는다. 스트림 데이터에의 실제의 참조는,IDirect3DDevice8::DrawPrimitive , 등의 드로잉(Drawing) 메소드가 불려 갈 때까지는 발생하지 않는다.

스트림은, 성분 데이터의 유니폼 배열로서 정의되어 각 성분은, 위치 좌표, 법선, 색등의 단일 엔티티를 나타내는 1 개(살) 이상의 요소로 구성된다. Stride 파라미터는, 성분의 사이즈를 바이트 단위로 지정한다.


버텍스 버퍼 및 인덱스 버퍼로부터의 렌더링

Microsoft® Direct3D® 는, 인덱스 첨부와 인덱스 없음의 양쪽 모두의 드로잉(Drawing) 메소드를 지원 한다. 인덱스 첨부 메소드는, 모든 버텍스의 성분에의 인덱스 세트를 1 개 사용한다. 버텍스 데이터는, 버텍스 버퍼내의 Direct3D API 에 제시되어 인덱스 첨부 드로잉(Drawing) 메소드의 인덱스 데이터는, 인덱스 버퍼내에 제시된다. 상세한 것에 대하여는, 이하의 레퍼런스 주제를 참조할것.

  • IDirect3DDevice8::DrawPrimitive
  • IDirect3DDevice8::DrawIndexedPrimitive

이러한 메소드는, 데이터 입력 스트림의 경향 세트로부터 프리미티브를 드로잉(Drawing) 한다. 인덱스 버퍼에의 경향 인덱스 배열의 설정에 대해서는, 「IDirect3DDevice8::SetIndices 메소드」를 참조할것.


유저 메모리 포인터로부터의 렌더링

렌더링 인터페이스의 세칸다리셋트에서는, 버텍스 및 인덱스 데이터를 유저 메모리 포인터로부터 직접 렌더링 할 수 있다. 이러한 인터페이스는, 버텍스 데이터만의 단일 스트림을 지원 한다. 상세한 것에 대하여는, 이하의 레퍼런스 주제를 참조할것.

  • IDirect3DDevice8::DrawPrimitiveUP
  • IDirect3DDevice8::DrawIndexedPrimitiveUP

이러한 메소드는, 버텍스나 인덱스 버퍼는 아니고, 유저 메모리 포인터에 의해 지정된 데이터를 사용해 렌더링을 실시한다.


디바이스 스테이트

Microsoft® Direct3D® 디바이스는 스테이트 머신이다. 즉, 어플리케이션으로 라이팅, 렌더링, 및 트랜스 폼 모듈의 스테이트를 설정해, 렌더링시에 그러한 모듈을 개입시켜 데이터를 건네준다.

여기에서는, 렌더링 스테이트, 및 Direct3D 로 사용하는 각 렌더링 스테이트에 대해 자세하게 설명한다. 또, 디바이스 스테이트의 그룹을 1 회의 호출로 처리할 수 있는 디바이스 스테이트 블록에 대해서도 설명한다. 설명하는 주제는, 다음과 같다.

  • 렌더링 스테이트
  • 텍스쳐 스테이지 스테이트
  • 스테이트 블록


렌더링 스테이트

여기에서는, 렌더링 스테이트의 개요와 각 렌더링 스테이트의 상세한 것에 대하여 설명한다. 설명하는 주제는, 다음과 같다.

  • 렌더링 스테이트에 대해
  • 알파 블렌딩 스테이트
  • 알파 실험 스테이트
  • 앰비언트 라이트 스테이트
  • anti-aliasing 스테이트
  • 카링스테이트
  • 깊이 버퍼링 스테이트
  • fog 스테이트
  • 라이팅 스테이트
  • 아우트라인 및 전부 칠해 스테이트
  • 버텍스 단위의 칼라 스테이트
  • 프리미티브 클리핑 스테이트
  • 쉐이딩 스테이트
  • 스텐실 버퍼 스테이트
  • 텍스쳐 랩핑 스테이트


렌더링 스테이트에 대해

디바이스 렌더링 스테이트는, Microsoft® Direct3D® 디바이스의 라스터화 모듈의 동작을 제어한다. 렌더링 스테이트의 속성, 사용하는 쉐이딩 타입, fog 속성, 그 외의 라스터화 처리를 변경하는 것에 의해, 이러한 동작을 제어한다.

C++ 로 기술된 어플리케이션에서는,IDirect3DDevice8::SetRenderState 메소드를 호출해, 렌더링 스테이트의 그 외의 특성을 제어한다. D3DRENDERSTATETYPE 열거형은, 가능한 렌더링 스테이트를 모두 지정한다. 어플리케이션에서는,D3DRENDERSTATETYPE 열거로부터의 값을 제 1 파라미터로서 SetRenderState 메소드에 건네준다.

고정 기능에 의한 버텍스 처리는,SetRenderState 메소드와 이하의 디바이스 렌더링 스테이트에 의해 제어된다. 프로그램 된 버텍스 쉐이더를 사용해도, 이러한 제어의 상당수는 아무것도 영향을 받지 않는다.

  • D3DRS_SPECULARENABLE
  • D3DRS_FOGSTART
  • D3DRS_FOGEND
  • D3DRS_FOGDENSITY
  • D3DRS_RANGEFOGENABLE
  • D3DRS_LIGHTING
  • D3DRS_AMBIENT
  • D3DRS_FOGVERTEXMODE
  • D3DRS_COLORVERTEX
  • D3DRS_LOCALVIEWER
  • D3DRS_NORMALIZENORMALS
  • D3DRS_DIFFUSEMATERIALSOURCE
  • D3DRS_SPECULARMATERIALSOURCE
  • D3DRS_AMBIENTMATERIALSOURCE
  • D3DRS_EMISSIVEMATERIALSOURCE
  • D3DRS_VERTEXBLEND

또, 고정 기능 버텍스 처리 파이프라인에서는, 이하의 메소드를 사용해, 트랜스 폼, 머트리얼, 및 라이팅을 설정한다.

  • IDirect3DDevice8::SetTransform
  • IDirect3DDevice8::SetMaterial
  • IDirect3DDevice8::SetLight
  • IDirect3DDevice8::LightEnable

주 픽셀 파이프라인내에서의 스펙큐러색의 추가는, D3DRS_SPECULARENABLE 가 제어한다. D3DRS_FOGSTART, D3DRS_FOGEND, 및 D3DRS_FOGDENSITY 는, 픽셀 fog 농도계산의 시작, 종료, 및 농도를 제어한다.


알파 블렌딩 스테이트

색의 알파값은 투명도를 제어한다. 알파 블렌딩을 유효하게 하면, 어느 표면의 색, 머트리얼, 및 텍스쳐를 투명도와 브렌드 해, 다른 표면에 적용할 수 있다.

상세한 것에 대하여는, 「알파 텍스쳐 블렌딩」 및 「멀티 텍스쳐 블렌딩」을 참조할것.

C++ 로 기술된 어플리케이션에서는,D3DRS_ALPHABLENDENABLE 렌더링 스테이트를 사용해 알파 투명 블렌딩을 유효하게 한다. Microsoft® Direct3D® API 에서는, 다양한 종류의 알파 블렌딩을 사용할 수 있다. 다만, 유저의 3D 하드웨어가 Direct3D 로 가능한 블렌딩 스테이트의 모두에게 대응 하면은 한정되지 않기 때문에 주의가 필요하다.

실행되는 알파 블렌딩의 종류는,D3DRS_SRCBLEND 및 D3DRS_DESTBLEND 렌더링 스테이트에 따라서 다르다. 전송원 및 전송처의 블렌딩 스테이트는 페어로 사용한다. 다음의 코드는, 전송원의 블렌딩 스테이트를 D3DBLEND_SRCCOLOR 로 설정해, 전송처의 블렌딩 스테이트를 D3DBLEND_INVSRCCOLOR 로 설정하는 방법을 나타내고 있다.

// 이 샘플 코드에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.

// 전송원의 블렌딩 스테이트를 설정한다.
d3dDevice->SetRenderState(D3DRS_SRCBLEND, D3DBLEND_SRCCOLOR);

// 전송처의 블렌딩 스테이트를 설정한다.
d3dDevice->SetRenderState(D3DRS_DESTBLEND, D3DBLEND_INVSRCCOLOR);

위에의 샘플 코드에 나타내는 호출의 결과, Direct3D 는 전송원칼라 (현재의 위치에서 렌더링 되는 프리미티브의 색)와 전송처 칼라 (frame buffer내의 현재의 위치의 색)의 사이에 선형 블렌딩을 실행한다. 이 처리에 의해, 색조를 가지는 유리와 같은 외관이 된다. 전송처 오브젝트의 색의 일부는, 전송원오브젝트로부터 전해진 것처럼 보인다. 그 외의 색은 흡수된 것처럼 보인다.

전송원 및 전송처의 블렌딩 스테이트의 설정을 바꾸면(자), 안개나 먼지 중(안)에서 오브젝트가 빛나고 있는 것 같은 외관이 된다. 예를 들어, 어플리케이션으로, 불길, 전자력계, 플라스마 광선, 또는 멍하니 한 중에서 빛나고 있는 것 같은 오브젝트를 모델링 하는 경우, 전송원 및 전송처의 블렌딩 스테이트를 D3DBLEND_ONE 로 설정한다.

또, 알파 블렌딩은 3D 신의 라이팅을 제어한다. 이것은 라이트 매핑으로 불리는 일도 있다. 전송원의 블렌딩 스테이트를 D3DBLEND_ZERO 로 설정해, 전송처의 블렌딩 스테이트를 D3DBLEND_SRCALPHA 로 설정 하면, 전송원의 알파 정보에 따라 장면이 어두워진다. 전송원의 프리미티브는, frame buffer의 내용을 스케일링 하는 라이트 맵으로서 사용되어 필요에 따라서 장면을 어둡게 한다. 이것에 의해, 흑백의 라이트 매핑이 생성된다.

칼라 라이트 매핑은, 전송원의 알파 블렌딩 스테이트를 D3DBLEND_ZERO 로 설정해, 전송처의 블렌딩 스테이트를 D3DBLEND_SRCCOLOR 로 설정하는 것으로 실현될 수 있다.


알파 실험 스테이트

C++ 어플리케이션에서는, 알파 실험을 사용해, 언제 픽셀을 렌더링 타겟 표면에 기입하는지를 제어한다. D3DRS_ALPHATESTENABLE 렌더링 스테이트를 사용하는 것으로써, 어플리케이션에서는, 알파 테스트 함수에 근거해 각 픽셀을 테스트할 수 있도록(듯이) 현재의 Microsoft® Direct3D® 디바이스를 설정한다. 테스트가 성공하면(자), 픽셀이 표면에 기입해진다. 테스트가 실패 하면, 픽셀은 무시된다. 알파 테스트 함수는,D3DRS_ALPHAFUNC 렌더링 스테이트에서 선택한다. D3DRS_ALPHAREF 렌더링 스테이트를 사용하는 것으로써, 어플리케이션에서는, 비교하는 모든 픽셀에 참조 알파값을 설정한다.

알파 실험은, 보통, 투명하게 가까운 오브젝트를 라스터화할 때의 퍼포먼스를 개선하기 위해서 사용한다. 라스터화하는 칼라 데이터가 지정의 픽셀 (D3DPCMPCAPS_GREATEREQUAL)보다 불투명하게 가까운 경우, 픽셀이 기입해진다. 그렇지 않은 경우는, 래스터라이저는 픽셀을 무시해, 2 색의 브렌드에 필요한 처리를 생략 한다. 다음의 샘플 코드는, 지정된 비교 함수가 지원 되고 있는지 어떤지를 조사하고 있다. 지원 되고 있는 경우는, 렌더링의 퍼포먼스 개선에 필요한 비교 함수의 파라미터를 설정한다.

// 이 샘플 코드에서는, pCaps 는,
// 전의 IDirect3D8::GetDeviceCaps 에의 호출에 의해 저장 되었다
// D3DCAPS8 구조체이라고 가정하고 있다.
if (pCaps.AlphaCmpCaps & D3DPCMPCAPS_GREATEREQUAL)
{
    dev->SetRenderState(D3DRS_ALPHAREF, (DWORD) 0x00000001);
    dev->SetRenderState(D3DRS_ALPHATESTENABLE, TRUE);
    dev->SetRenderState(D3DRS_ALPHAFUNC, D3DCMP_GREATEREQUAL);
}

// 비교 함수가 지원되어 있지 않은 경우에도 렌더링을 실행한다.
// 다만, 퍼포먼스는 개선되지 않는다.

모든 하드웨어가 알파 실험 기능을 지원 하고 있는 것은 아니다. 디바이스 기능을 조사하려면 ,IDirect3D8::GetDeviceCaps 메소드를 호출한다. 디바이스 기능을 취득한 후, 사용하는 비교 함수의 관련하는 D3DCAPS8 구조체의 AlphaCmpCaps 멤버를 조사한다. AlphaCmpCaps 멤버가 D3DPCMPCAPS_ALWAYS 능력만, 또는 D3DPCMPCAPS_NEVER 능력만 포함하고 있는 경우, 드라이버는 알파 테스트를 전혀 지원 하고 있지 않다.


앰비언트 라이트 스테이트

앰비언트 라이트란, 전방향으로부터 조사하는 환경빛이다.

Microsoft® Direct3D® 의 앰비언트 라이트의 사용에 관한 특정의 정보에 대해서는, 「다이렉트 라이트와 앰비언트 라이트의 비교」 및 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.

C++ 어플리케이션으로 앰비언트 라이트의 색을 설정하려면 ,IDirect3DDevice8::SetRenderState 메소드를 호출해, 제 1 파라미터로서 열거값 D3DRS_AMBIENT 를 건네준다. 제 2 파라미터는 칼라값이다. 디폴트값은 제로이다.

// 이 샘플 코드에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.

// 앰비언트 라이트를 설정한다.
d3dDevice->SetRenderState(D3DRS_AMBIENT, 0x00202020);


anti-aliasing 스테이트

에일리어징 제거란, 선과 엣지를 스크린상에서 보다 매끄럽게 표시하는 방법이다. Microsoft® Direct3D® 가 지원 하는 anti-aliasing에는, 엣지 anti-aliasing 및 풀 신 anti-aliasing의 2 종류가 있다.

이러한 테크닉의 상세한 것에 대하여는, 「anti-aliasing」를 참조할것.

디폴트에서는, Direct3D 는 anti-aliasing를 실행하지 않는다. 엣지 anti-aliasing ( 제 2 렌더링 패스가 필요)를 유효하게 하려면 ,D3DRS_EDGEANTIALIAS 렌더링 스테이트를 TRUE 로 설정한다. 엣지 anti-aliasing를 무효로 하려면 , D3DRS_EDGEANTIALIAS 를 FALSE 로 설정한다.

풀 신 anti-aliasing를 유효하게 하려면 ,D3DRS_MULTISAMPLEANTIALIAS 렌더링 스테이트를 TRUE 로 설정한다. 풀 신 anti-aliasing를 무효로 하려면 , D3DRS_MULTISAMPLEANTIALIAS 를 FALSE 로 설정한다.


카링스테이트

Microsoft® Direct3D® 는, 프리미티브를 렌더링 할 경우에 프리미티브의 배면을 카링 한다.

C++ 어플리케이션으로 카링모드를 설정하려면 ,D3DCULL 열거형의 멤버를 설정할 수 있는 D3DRS_CULLMODE 렌더링 스테이트를 사용한다. 디폴트에서는, 반시계회전의 버텍스를 가지는 배면을 카링 한다.

다음의 샘플 코드는, 시계회전의 버텍스를 가지는 배면을 카링 하는 카링모드를 설정하는 처리를 나타내고 있다.

// 이 샘플 코드에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.

// 카링스테이트를 설정한다.
d3dDevice->SetRenderState(D3DRS_CULLMODE, D3DCULL_CW);


깊이 버퍼링 스테이트

깊이 버퍼링이란, 은선 및 은면을 삭제하는 방법이다. 디폴트에서는, Microsoft® Direct3D® 로 깊이 버퍼링은 사용되지 않는다.

깊이 버퍼의 개요에 대해서는, 「깊이 버퍼란」을 참조할것.

C++ 어플리케이션에서는,D3DZBUFFERTYPE 열거의 멤버의 어느쪽이든을 사용해 새로운 스테이트값을 지정하는 것으로,D3DRS_ZENABLE 렌더링 스테이트에서 깊이 버퍼링 스테이트를 갱신한다.

Direct3D 에 의한 깊이 버퍼에의 기입을 방지할 필요가 있는 경우는, D3DRS_ZWRITEENABLE 열거값을 사용해,IDirect3DDevice8::SetRenderState 의 호출의 제 2 파라미터로서 D3DZB_FALSE 를 지정한다.

다음의 코드는, z 버퍼링이 유효하게 되도록(듯이) 깊이 버퍼 스테이트를 설정하는 방법을 나타내고 있다.

// 이 코드예에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.

// z 버퍼링을 유효하게 한다.
d3dDevice->SetRenderState(D3DRS_ZENABLE, D3DZB_TRUE);

어플리케이션에서는, 또,D3DRS_ZFUNC 렌더링 스테이트를 사용해, 깊이 버퍼링의 실행시에 Direct3D 로 사용하는 비교 함수를 제어할 수 있다.

z 바이어스란, 서로의 깊이값이 같아도, 한편의 표면을 한편의 표면보다 앞에 표시하는 방법이다. 이 테크닉은, 다양한 이펙트를 기대할 수 있다. 일반적인 예로서 벽에 그림자를 붙이는 경우를 생각한다. 그림자도 벽도 깊이값은 같다. 그러나, 아무래도 벽에 그림자를 붙이려고 하는 경우가 있다. 이러한 경우, 그림자에 z 바이어스를 적용하는 것으로, 벽 위에 그림자를 적절히 표시할 수 있다 ( 「D3DRS_ZBIAS 」를 참조할것).


fog 스테이트

fog 이펙트를 사용 하면, 3D 신을 한층 리얼하게 표현할 수 있다. fog 이펙트는, 안개의 시뮬레이션 이외에도 사용할 수 있다. fog 이펙트로 먼 경치를 애매하게 할 수가 있다. 이것은 실제를 표현하고 있다. 즉, 오브젝트는 멀게 떨어지는에 따라, 그 세부가 불명료하게 되어 간다.

어플리케이션에서의 fog의 사용의 상세한 것에 대하여는, 「fog」를 참조할것.

C++ 어플리케이션에서는, 디바이스 렌더링 스테이트를 개입시켜 fog를 제어한다. D3DRENDERSTATETYPE 열거형에는, 픽셀 (테이블) 또는 버텍스 fog의 머지않아가 사용되고 있는지, 그 색, 시스템이 적용하는 fog 공식, 그 공식의 파라미터등을 제어하는 스테이트가 포함된다.

fog를 유효하게 하려면 ,D3DRS_FOGENABLE 렌더링 스테이트를 TRUE 로 설정한다. fog 칼라는,D3DRS_FOGCOLOR 렌더링 스테이트를 사용하는 것에 의해, 임의의 칼라값으로 설정할 수 있다 (fog 칼라의 알파 성분은 무시된다).

D3DRS_FOGTABLEMODE 및 D3DRS_FOGVERTEXMODE 렌더링 스테이트는, fog의 계산에 적용되는 fog 공식을 제어해, 적용되는 fog의 종류를 간접적으로 제어한다. 이 양쪽 모두의 렌더링 스테이트는,D3DFOGMODE 열거형의 멤버의 어느 쪽인가에 설정할 수 있다. 렌더링 스테이트의 어느쪽이든을 D3DFOG_NONE 로 설정 하면, 거기에 응해 픽셀 또는 버텍스 fog가 무효가 된다. 양쪽 모두의 렌더링 스테이트가 유효한 모드로 설정되어 있는 경우는, 픽셀 fog 이펙트만 적용된다.

D3DRS_FOGSTART 및 D3DRS_FOGEND 렌더링 스테이트는, D3DFOG_LINEAR 모드용의 fog 공식 파라미터를 제어한다. D3DRS_FOGDENSITY 렌더링 스테이트는, 지수 fog 모드의 fog 농도를 제어한다.

상세한 것에 대하여는, 「fog 파라미터」를 참조할것.


라이팅 스테이트

Microsoft® Direct3D® 의 지오메트리 파이프라인을 사용하는 어플리케이션에서는, 라이팅 계산을 유효 또는 무효로 할 수 있다. 버텍스 법선을 포함한 버텍스에게만 라이팅이 올바르게 적용된다. 버텍스 법선이 없는 경우는, 모든 라이팅 계산으로 0 의 내적이 사용된다. 따라서, 법선을 사용하지 않는 버텍스에는 라이팅이 적용되지 않는다.

상세한 것에 대하여는, 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.

어플리케이션으로 Direct3D 의 라이팅을 유효하게 하려면 ,D3DRS_LIGHTING 렌더링 스테이트를 TRUE (디폴트 설정)로 설정해, Direct3D 의 라이팅을 무효로 하려면 FALSE 로 설정한다.

라이팅 렌더링 스테이트는, 버텍스 버퍼내의 버텍스로써 가능한 라이팅 계산에는 전혀 의존하지 않는다. IDirect3DDevice8::ProcessVertices 메소드는, 버텍스 처리 시에 라이팅 계산을 제어하는, 독자적인 플래그를 받는다.


아우트라인 및 전부 칠해 스테이트

텍스쳐가 적용되지 않은 프리미티브는, 머트리얼에 의해 지정되는 색, 또는 버텍스로 지정된 색이 있으면, 그 어느쪽이든으로 렌더링 된다. 프리미티브를 전부 칠하는 방법은,D3DFILLMODE 열거형으로 정의되는 값을 D3DRS_FILLMODE 렌더링 스테이트로 지정해 선택할 수 있다.

어플리케이션으로 디저링을 유효하게 하려면 , 제 1 파라미터로서 D3DRS_DITHERENABLE 열거값을 IDirect3DDevice8::SetRenderState 에 건네줄 필요가 있다. 디저링을 유효하게 하려면 제 2 파라미터를 TRUE 로 설정해, 무효로 하려면 FALSE 로 설정한다.

선의 마지막 픽셀을 드로잉(Drawing) 하면 주위의 프리미티브와 겹쳐, 외형이 나빠지는 일이 있다. 이것은,D3DRS_LASTPIXEL 열거값을 사용해 제어할 수 있다. 다만, 이 설정을 변경 하면나무는 주의가 필요하다. 경우에 따라서는, 마지막 픽셀을 드로잉(Drawing) 하지 않게 하면 프리미티브간에 틈새가 생겨 보기 흉해지는 일이 있다.

디폴트에서는, Microsoft®Direct3D® 디바이스는, 원시적으로 실선의 아우트라인을 사용한다. 아우트라인 패턴은,D3DLINEPATTERN 구조체를 사용해 변경할 수 있다. 상세한 것에 대하여는, 「D3DRS_LINEPATTERN 렌더링 스테이트」를 참조할것.


버텍스 단위의 칼라 스테이트

유연한 버텍스 포맷 (FVF)을 사용 하면, 버텍스는 색정보와 법선 정보의 양쪽 모두를 가질 수 있다. Microsoft® Direct3D® 에서는, 이 정보를 사용해 라이팅 계산이 실행된다 (디폴트). 어플리케이션으로 버텍스 칼라 라이팅 정보의 사용을 무효로 하려면 ,IDirect3DDevice8::SetRenderState 를 호출해, 제 1 파라미터로서 D3DRS_COLORVERTEX 를 건네준다. 제 2 파라미터를 FALSE 로 설정 하면 버텍스 칼라 라이팅이 무효가 되어, TRUE 로 설정 하면 유효하게 된다.

버텍스 단위의 칼라가 유효한은 있는 경우, 어플리케이션에서는, 버텍스의 색정보의 정보 소스를 설정할 수 있다. D3DRS_AMBIENTMATERIALSOURCE ,D3DRS_DIFFUSEMATERIALSOURCE ,D3DRS_EMISSIVEMATERIALSOURCE , 및 D3DRS_SPECULARMATERIALSOURCE 렌더링 스테이트는, 각각, 앰비언트, 디퓨즈, 에미션(emission), 및 스펙큐러색의 색성분 소스를 제어한다. 이러한 각 렌더링 스테이트는,D3DMATERIALCOLORSOURCE 열거형의 멤버로 설정할 수 있다. 이 열거형은, 현재의 머트리얼, 디퓨즈색, 또는 스펙큐러색을, 지정된 색성분의 소스로서 사용하도록(듯이) 시스템에 알리는 정수를 정의한다.


프리미티브 클리핑 스테이트

Microsoft® Direct3D® 에서는, 뷰 포토외에서 부분적으로 렌더링 하는 프리미티브를 클리핑 할 수가 있다. C++ 의 경우, Direct3D 클리핑은 D3DRS_CLIPPING 렌더링 스테이트에서 제어한다. 이 렌더링 스테이트를 TRUE (디폴트값)로 설정 하면, 프리미티브 클리핑이 유효하게 된다. 렌더링 스테이트를 FALSE 로 설정 하면, Direct3D 의 그리핑 서비스는 무효가 된다.

프리미티브 클리핑 렌더링 스테이트는, 버텍스 버퍼내의 버텍스로써 가능한 클리핑 처리에는 전혀 의존하지 않는다. IDirect3DDevice8::ProcessVertices 메소드는, 버텍스 처리 시에 프리미티브 클리핑을 제어하는, 독자적인 플래그를 받는다.


쉐이딩 스테이트

Microsoft® Direct3D® 에서는, flat shading와 gouraud shading의 양쪽 모두를 지원 하고 있다. 디폴트에서는 gouraud shading가 설정된다. 현재의 쉐이딩 모드를 제어하기 위해(때문에), C++ 어플리케이션에서는 D3DSHADEMODE 열거형의 멤버를 D3DRS_SHADEMODE 렌더링 스테이트로 지정한다.

다음의 C++ 코드는, 쉐이딩 스테이트를 flat shading 모드로 설정하는 처리를 나타내고 있다.

// 이 샘플 코드에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.

// 쉐이딩 스테이트를 설정한다.
d3dDevice->SetRenderState(D3DRS_SHADEMODE, D3DSHADE_FLAT);


스텐실 버퍼 스테이트

어플리케이션은, 스텐실 버퍼를 사용해, 렌더링 타겟 표면에 픽셀을 기입할지 어떨지를 결정한다.

상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.

C++ 로 기술된 어플리케이션으로, 스텐실 처리를 유효 또는 무효로 하려면 ,IDirect3DDevice8::SetRenderState 메소드를 호출한다. 제 1 파라미터의 값으로서 D3DRS_STENCILENABLE 를 건네준다. 스텐실 처리를 유효하게 하려면 제 2 파라미터의 값을 TRUE 로 설정해, 무효로 하려면 FALSE 로 설정한다.

Microsoft® Direct3D® 의 스텐실 테스트로 사용하는 비교 함수는,SetRenderState 를 호출해 설정한다. 제 1 파라미터의 값을 D3DRS_STENCILFUNC 로 설정한다. 제 2 파라미터의 값으로서 D3DCMPFUNC 열거형의 멤버를 건네준다.

스텐실 참조값이란, 스텐실 함수가 테스트에 사용하는, 스텐실 버퍼내의 값이다. 디폴트에서는 스텐실 참조값은 제로이다. 어플리케이션에서는,SetRenderState 를 호출해 이 값을 설정할 수 있다. 제 1 파라미터의 값으로서 D3DRS_STENCILREF 를 건네준다. 제 2 파라미터의 값을 새로운 참조값으로 설정한다.

Direct3D 모듈은, 픽셀에 대한 스텐실 테스트를 실행하기 전에, 스텐실 참조값과 스텐실 마스크값의 비트적을 계산한다. 그 결과는, 스텐실 비교 함수에 의해 스텐실 버퍼의 내용이라고 비교된다. 어플리케이션에서는,SetRenderState 를 호출해 스텐실 마스크를 설정할 수 있다. 제 1 파라미터의 값으로서 D3DRS_STENCILMASK 를 건네준다. 제 2 파라미터를 새로운 스텐실 마스크로 설정한다.

스텐실 테스트가 실패했을 때의 Direct3D 의 처리를 설정하려면 ,SetRenderState 를 호출해, 제 1 파라미터로서 D3DRS_STENCILFAIL 를 건네준다. 제 2 파라미터는 D3DSTENCILOP 열거형의 멤버가 아니면 안된다.

또, 스텐실 테스트는 성공했지만 z 버퍼 테스트가 실패했을 때의 Direct3D 의 처리도 어플리케이션으로 제어할 수 있다. SetRenderState 를 호출해, 제 1 파라미터로서 D3DRS_STENCILZFAIL 를 건네주어, 제 2 파라미터에 D3DSTENCILOP 열거형의 멤버를 설정한다.

게다가 어플리케이션에서는, 스텐실 테스트와 z 버퍼 테스트의 양쪽 모두가 성공했을 때의 Direct3D 의 처리도 제어할 수 있다. SetRenderState 를 호출해, 제 1 파라미터로서 D3DRS_STENCILPASS 를 건네준다. 이 경우도, 제 2 파라미터는 D3DSTENCILOP 열거형의 멤버가 아니면 안된다.


텍스쳐 랩핑 스테이트

D3DRS_WRAP0 ~ D3DRS_WRAP7 렌더링 스테이트는, 디바이스의 멀티 텍스쳐 cascade의 각종 텍스쳐에 대해서, u 및 v 랩핑을 유효 또는 무효로 한다. 이러한 렌더링 스테이트를 D3DWRAPCOORD_0, D3DWRAPCOORD_1, D3DWRAPCOORD_2, 및 D3DWRAPCOORD_3 플래그의 조합해로 설정해, 텍스쳐의 제 1, 제 2, 제 3, 및 제 4 방향에서의 랩핑을 유효하게 할 수 있다. 제로를 설정 하면, 랩핑은 모두 무효가 된다. 디폴트에서는, 텍스쳐 랩핑은, 모든 텍스쳐 스테이지의 전방향으로 무효가 되어 있다.

개요에 대해서는, 「텍스쳐 랩핑」을 참조할것.


텍스쳐 스테이지 스테이트

여기에서는, 텍스쳐 스테이지 스테이트의 개념과 각 텍스쳐 스테이지 스테이트의 상세한 것에 대하여 설명한다. 설명하는 주제는, 다음과 같다.

  • 텍스쳐 스테이지 스테이트에 대해
  • 텍스쳐 애드레싱 스테이트
  • 텍스쳐 경계 스테이트
  • 텍스쳐 필터 링 스테이트
  • 텍스쳐 블렌딩 스테이트


텍스쳐 스테이지 스테이트에 대해

텍스쳐 스테이지 스테이트는, 텍스쳐의 스타일 및 텍스쳐 필터 링의 방법을 제어한다.

C++ 로 기술된 어플리케이션에서는,IDirect3DDevice8::SetTextureStageState 메소드를 호출해, 텍스쳐 관련 렌더링 스테이트의 특성을 제어한다. D3DTEXTURESTAGESTATETYPE 열거형은, 가능한 모든 텍스쳐 관련 렌더링 스테이트를 지정한다. 어플리케이션에서는,D3DTEXTURESTAGESTATETYPE 열거로부터의 값을 제 1 파라미터로서 SetTextureStageState 메소드에 건네준다.

어플리케이션에서는,IDirect3DDevice8::SetTexture 메소드를 호출해 스테이지의 텍스쳐를 설정한다.


텍스쳐 애드레싱 스테이트

C++ 어플리케이션에서는,D3DTSS_ADDRESSU ,D3DTSS_ADDRESSV , 및 D3DTSS_ADDRESSW 텍스쳐 스테이지 스테이트를 사용해 텍스쳐 애드레싱을 설정한다.


텍스쳐 경계 스테이트

C++ 어플리케이션에서는,D3DTSS_BORDERCOLOR 텍스쳐 스테이지 스테이트를 사용해 경계색텍스쳐 애드레싱을 설정한다.

상세한 것에 대하여는, 「경계색텍스쳐 addressing mode」를 참조할것.


텍스쳐 필터 링 스테이트

C++ 어플리케이션에서는,D3DTSS_MAGFILTER ,D3DTSS_MINFILTER , 및 D3DTSS_MIPFILTER 텍스쳐 스테이지 스테이트를 사용해, 텍스쳐 필터 링을 제어할 필요가 있다.


텍스쳐 블렌딩 스테이트

C++ 어플리케이션에서는,D3DTSS_COLOROP 로 정의된 텍스쳐 블렌딩 스테이트와 D3DTSS_ALPHAOP 텍스쳐 스테이지 스테이트를 사용해, 텍스쳐 블렌딩을 제어한다.

상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.


스테이트 블록

여기에서는, 디바이스 스테이트 블록의 주요한 개념에 대해, 및 어플리케이션에서의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 스테이트 블록에 대해
  • 스테이트 블록의 기록
  • 스테이트 블록의 취득
  • 스테이트 블록의 적용
  • 사전 정의하는 스테이트 블록의 생성
  • 스테이트 블록의 삭제


스테이트 블록에 대해

Microsoft® Direct3D® 의 스테이트 블록이란, 디바이스 스테이트의 그룹이다. 이것에는, 렌더링 스테이트, 라이팅 및 머트리얼 파라미터, 트랜스 폼 스테이트, 텍스쳐 스테이지 스테이트, 및 경향 텍스쳐 정보가 있다. 스테이트 블록은, 디바이스의 현재의 스테이트의 snapshot로서 처리되는지, 또는 명시적으로 기록된다. snapshot는, 1 회의 호출로 디바이스에 적용할 수가 있다. 디바이스 스테이트 블록은, 어플리케이션으로 필요한 공통된 일련의 스테이트 변경을 고속화하기 위해서, 렌더링 디바이스로 최적화할 수가 있다. 또, 디바이스 스테이트 블록의 사용에 의해, 디바이스 스테이트의 적용을 단순화 할 수도 있다.

C++ 에서는, 스테이트 블록 핸들을 받는 것은,IDirect3DDevice8::EndStateBlock 메소드를 호출해 스테이트 블록의 기록을 종료했을 때, 및 IDirect3DDevice8::CreateStateBlock 메소드를 호출해 사전 정의되고 있는 디바이스 스테이트 데이터 세트를 취득했을 때이다.


스테이트 블록의 기록

IDirect3DDevice8 인터페이스에는, 어플리케이션으로부터 디바이스 스테이트의 요구가 있었을 때에 그 디바이스 스테이트를 스테이트 블록에 기록하는 IDirect3DDevice8::BeginStateBlock 메소드가 있다. BeginStateBlock 메소드는, 디바이스 스테이트의 변경을 디바이스에 적용하는 것이 아니라, 디바이스 스테이트의 변경을 스테이트 블록에 기록하기 시작한다. BeginStateBlock 를 호출한 후, 다음의 메소드의 호출은 모두 디바이스 스테이트 블록에 기록된다.

  • IDirect3DDevice8::LightEnable
  • IDirect3DDevice8::SetClipPlane
  • IDirect3DDevice8::SetLight
  • IDirect3DDevice8::SetMaterial
  • IDirect3DDevice8::SetRenderState
  • IDirect3DDevice8::SetTexture
  • IDirect3DDevice8::SetTextureStageState
  • IDirect3DDevice8::SetTransform
  • IDirect3DDevice8::SetViewport

스테이트 블록의 기록이 종료하면(자),IDirect3DDevice8::EndStateBlock 메소드를 호출해 기록의 정지를 시스템에 알린다. EndStateBlock 메소드는, 스테이트 블록의 핸들을 변수에 저장 한다. 이 변수의 주소는 pToken 파라미터에 건네준다. 어플리케이션에서는, 이 핸들을 사용해, 필요에 따라서 스테이트 블록을 디바이스에 적용하거나 새로운 스테이트 데이터를 블록에 기록하거나 불필요하게 된 스테이트 블록을 삭제할 수가 있다.

퍼포먼스에 관한 주의 최선의 결과를 얻기 위해서(때문에)는,BeginStateBlock 및 EndStateBlock 의 페어간에서의 모든 스테이트 변경을 그룹화 한다.

EndStateBlock 메소드가 돌려주는 에러 코드를 체크하는 것이 중요하다. 이 메소드가 실패했을 경우, 그 원인의 상당수는 디스플레이 모드가 변경된 것이다고 생각된다. 어플리케이션의 표면을 생성 다시 해 , 재차 스테이트 블록을 기록하는 것으로, 이러한 장해로부터 어플리케이션이 회복하도록(듯이) 설계한다.


스테이트 블록의 취득

IDirect3DDevice8::CaptureStateBlock 메소드는, 기존의 스테이트 블록내의 값을 갱신해 디바이스의 현재의 스테이트에 반영한다. 이 메소드는,Token 파라미터를 1 개만 받는다. 이 파라미터는, 호출이 성공했을 경우에 디바이스의 현재의 스테이트의 혼잡처가 되는 스테이트 블록을 식별한다.

어플리케이션으로 기록 끝난 스테이트 블록을 갱신해 약간 다른 스테이트 설정을 포함하는 경우는,CaptureStateBlock 메소드가 특히 편리하다. 이것을 실시하려면 , 다음의 샘플 코드와 같이, 기존의 스테이트 블록을 적용해, 필요한 설정 변경을 실시해, 시스템의 스테이트를 스테이트 블록에 수중에 넣는다.

// 변수 token 에는, 이전에 기록된 디바이스 스테이트 세트의
// 디바이스 스테이트 블록에의 핸들이 저장 되고 있다.

// 현재의 스테이트 블록을 설정한다.
d3dDevice->ApplyStateBlock(token);

// 필요에 따라서 디바이스 스테이트를 변경한다.
.
.
.

// 수정한 디바이스 스테이트 데이터를 기존의 블록에 수중에 넣는다.
d3dDevice->CaptureStateBlock(token);

CaptureStateBlock 메소드는, 디바이스의 스테이트 전체를 수중에 넣는 것이 아니라, 스테이트 블록내의 기존의 스테이트값을 갱신할 뿐이다. 예를 들어, 다음의 코드 예의 같게, 2 개의 처리가 기록된 스테이트 블록이 있다고 한다.

d3dDevice->SetRenderState(D3DRS_SHADEMODE, D3DSHADE_GOURAUD);
d3dDevice->SetTexture(0, pTexture);

스테이트 블록이 처음에 기록된 이후, 2 개의 설정의 어느쪽이든을 변경했을 경우,CaptureStateBlock 메소드는, 블록내에서 변경된 스테이트만 새로운 값에 갱신한다.


스테이트 블록의 적용

IDirect3DDevice8::ApplyStateBlock 메소드는, 기존의 스테이트 블록을 디바이스에 적용한다. ApplyStateBlock 메소드는,Token 파라미터를 1 개만 받는다. 이 파라미터는, 적용하는 스테이트 블록을 식별한다.

주 스테이트 블록의 기록중 (즉,IDirect3DDevice8::BeginStateBlock 로부터 IDirect3DDevice8::EndStateBlock 의 호출동안), 다른 스테이트 블록을 적용할 수 없다. 이것을 실행하려고 하면(자) 실패한다.


사전 정의하는 스테이트 블록의 생성

IDirect3DDevice8::CreateStateBlock 메소드는, 디바이스 스테이트 세트의 전체를 포함하든가, 혹은 버텍스 또는 픽셀 처리에 관한 디바이스 스테이트만 포함한 새로운 스테이트 블록을 생성 한다. CreateStateBlock 메소드는 2 개의 파라미터를 받는다. 제 1 파라미터는, 새로운 스테이트 블록에 수중에 넣는 스테이트 정보의 종류를 식별한다. 제 2 파라미터는, 호출이 성공했을 때에 유효한 스테이트 블록 핸들을 받는 변수의 주소이다.

제 1 파라미터의 유효값은,D3DSTATEBLOCKTYPE 열거형으로 정의된다. 이것에 포함되는 멤버를 사용해, 디바이스 스테이트 세트의 전체 (D3DSBT_ALL), 혹은 점 또는 픽셀 처리 (D3DSBT_VERTEXSTATE 또는 D3DSBT_PIXELSTATE)에 관한 스테이트만 수중에 넣을 수가 있다. 다음의 일람은, D3DSBT_VERTEXSTATE 또는 D3DSBT_PIXELSTATE 값을 건네주었을 때에 시스템에 의해 받아들여지는 스테이트를 나타내고 있다.

  • 버텍스 관련의 스테이트 (D3DSBT_VERTEXSTATE)
  • 모든 라이팅의 스테이트 (유효 또는 무효)
  • 트랜스 폼행예
  • 유저 정의 클립면
    이러한 값은, 다음의 렌더링 스테이트에 대해서 설정된다.
    D3DRS_AMBIENT

    D3DRS_AMBIENTMATERIALSOURCE

    D3DRS_CLIPPING

    D3DRS_CLIPPLANEENABLE

    D3DRS_COLORVERTEX

    D3DRS_CULLMODE

    D3DRS_DIFFUSEMATERIALSOURCE

    D3DRS_EMISSIVEMATERIALSOURCE

    D3DRS_FOGCOLOR

    D3DRS_FOGDENSITY

    D3DRS_FOGENABLE

    D3DRS_FOGEND

    D3DRS_FOGSTART

    D3DRS_FOGTABLEMODE

    D3DRS_FOGVERTEXMODE

    D3DRS_INDEXEDVERTEXBLENDENABLE

    D3DRS_LIGHTING

    D3DRS_LOCALVIEWER

    D3DRS_NORMALIZENORMALS

    D3DRS_POINTSCALE_A

    D3DRS_POINTSCALE_B

    D3DRS_POINTSCALE_C

    D3DRS_POINTSIZE

    D3DRS_POINTSIZE_MAX

    D3DRS_POINTSIZE_MIN

    D3DRS_POINTSCALEENABLE

    D3DRS_POINTSPRITEENABLE

    D3DRS_PATCHEDGESTYLE

    D3DRS_PATCHSEGMENTS

    D3DRS_RANGEFOGENABLE

    D3DRS_SHADEMODE

    D3DRS_SOFTWAREVERTEXPROCESSING

    D3DRS_SPECULARENABLE

    D3DRS_SPECULARMATERIALSOURCE

    D3DRS_TWEENFACTOR

    D3DRS_VERTEXBLEND

    이러한 값은, 다음의 텍스쳐 스테이지 스테이트에 대해서 설정된다.
    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

  • 픽셀 관련의 스테이트 (D3DSBT_PIXELSTATE)
    이러한 값은, 다음의 렌더링 스테이트에 대해서 설정된다.
    D3DRS_ALPHABLENDENABLE

    D3DRS_ALPHAFUNC

    D3DRS_ALPHAREF

    D3DRS_ALPHATESTENABLE

    D3DRS_COLORWRITEENABLE

    D3DRS_DESTBLEND

    D3DRS_DITHERENABLE

    D3DRS_EDGEANTIALIAS

    D3DRS_FILLMODE

    D3DRS_FOGDENSITY

    D3DRS_FOGEND

    D3DRS_FOGSTART

    D3DRS_LASTPIXEL

    D3DRS_LINEPATTERN

    D3DRS_MULTISAMPLEANTIALIAS

    D3DRS_MULTISAMPLEMASK

    D3DRS_SHADEMODE

    D3DRS_SRCBLEND

    D3DRS_STENCILENABLE

    D3DRS_STENCILFAIL

    D3DRS_STENCILFUNC

    D3DRS_STENCILMASK

    D3DRS_STENCILPASS

    D3DRS_STENCILREF

    D3DRS_STENCILWRITEMASK

    D3DRS_STENCILZFAIL

    D3DRS_TEXTUREFACTOR

    D3DRS_WRAP0 ~ D3DRS_WRAP7

    D3DRS_ZBIAS

    D3DRS_ZENABLE

    D3DRS_ZFUNC

    D3DRS_ZWRITEENABLE

    이러한 값은, 다음의 텍스쳐 스테이지 스테이트에 대해서 설정된다.
    D3DTSS_ADDRESSU

    D3DTSS_ADDRESSV

    D3DTSS_ADDRESSW

    D3DTSS_ALPHAARG1

    D3DTSS_ALPHAARG2

    D3DTSS_ALPHAOP

    D3DTSS_BORDERCOLOR

    D3DTSS_BUMPENVLOFFSET

    D3DTSS_BUMPENVLSCALE

    D3DTSS_BUMPENVMAT00

    D3DTSS_BUMPENVMAT01

    D3DTSS_BUMPENVMAT10

    D3DTSS_BUMPENVMAT11

    D3DTSS_COLORARG1

    D3DTSS_COLORARG2

    D3DTSS_COLOROP

    D3DTSS_MAGFILTER

    D3DTSS_MAXANISOTROPY

    D3DTSS_MAXMIPLEVEL

    D3DTSS_MINFILTER

    D3DTSS_MIPFILTER

    D3DTSS_MIPMAPLODBIAS

    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

주 CreateStateBlock 메소드가 돌려주는 에러 코드를 체크하는 것이 중요하다. 이 메소드가 실패했을 경우, 그 원인의 상당수는 디스플레이 모드가 변경된 것이다고 생각된다. 어플리케이션의 표면을 생성 다시 해 스테이트 블록을 기록하는 것으로, 이러한 장해로부터 어플리케이션이 회복하도록(듯이) 설계한다.


스테이트 블록의 삭제

IDirect3DDevice8::DeleteStateBlock 는, 기존의 스테이트 블록을 삭제해, 이 스테이트 블록으로 사용한 메모리의 할당을 해제한다. DeleteStateBlock 메소드는, 그 파라미터에서만 삭제하는 스테이트 블록에의 핸들을 받는다. 스테이트 블록을 삭제 하면, 그 스테이트 블록에의 핸들은 무효가 되어, 이후 사용할 수 없다.


소실한 디바이스

여기에서는, Microsoft® Direct3D® 로 소실한 디바이스에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 소실한 디바이스란
  • 소실한 디바이스에의 응답
  • 소실한 디바이스와 락 처리
  • 소실한 디바이스와 리소스
  • 소실한 디바이스와 취득 데이터


소실한 디바이스란

Microsoft® Direct3D® 디바이스 상태에는, 처리 가능 상태와 소실 상태가 있다. 처리 가능 상태는 디바이스의 보통 상태이며, 모든 렌더링이 예측대로 실행되고 표시된다. 풀 스크린 어플리케이션으로 키보드 포커스가 소실하는 등의 이벤트가 발생해 렌더링 할 수 없게 되면(자), 디바이스는 소실 상태가 된다. 소실 상태의 특성은, 표면에는 아무것도 나타나지 않고 모든 렌더링 처리가 실패하는 것이다. 즉, 렌더링 처리는 실패하고 있는데, 렌더링 메소드는 성공 코드를 돌려주는 일이 있다. 이러한 경우,IDirect3DDevice8::Present 에 의해 에러 코드 D3DERR_DEVICELOST 가 돌려주어진다.

설계에서는, 디바이스가 소실하는 것 같은 모든 시나리오가 상정되고 있는 것은 아니다. 일반적인 예로서는, 유저가 Alt + Tab 키를 눌렀을 때 등, 즉 시스템 다이얼로그가 초기화되었을 때에 포커스가 소실한다. 또, 전력 관리 이벤트에 의해, 다른 어플리케이션이 풀 스크린 처리를 실시할 때도 발생하는 일이 있다. 게다가IDirect3DDevice8::Reset 가 실패 하면, 디바이스는 소실 상태가 된다.


소실한 디바이스에의 응답

디바이스가 소실 하면, 어플리케이션은 그 디바이스에 대해서, 처리 가능 상태에 복원할 수 있을지 어떨지를 문의한다. 복원할 수 없는 경우는, 디바이스를 복원할 수 없을지 어플리케이션은 대기한다.

복원할 수 있는 경우, 어플리케이션은 모든 비디오 메모리 리소스와 스왑 체인을 파기해, 디바이스의 복원에 대비한다. 다음에, 어플리케이션은 IDirect3DDevice8::Reset 메소드를 호출한다. Reset 는, 디바이스가 소실 상태 때에 유효한 유일한 메소드이며, 어플리케이션이 디바이스를 소실 상태로부터 처리 가능 상태에 되돌릴 수가 있는 유일한 메소드이다. IDirect3DDevice8::CreateRenderTarget 이나 IDirect3DDevice8::CreateDepthStencilSurface 로 생성 된 리소스 등, D3DPOOL_DEFAULT 로 할당할 수 있던 모든 리소스를 어플리케이션이 해방하지 않는 한,Reset 는 실패한다.

대부분의 경우, Microsoft® Direct3D® 를 빈번하게 호출해도 디바이스가 소실하고 있을지 어떨지에 관한 정보는 돌아가지 않는다. 어플리케이션은, 소실한 디바이스의 통지를 받지 않아도,IDirect3DDevice8::DrawPrimitive 등의 렌더링 메소드의 호출을 속행할 수 있다. 내부적으로는, 이러한 처리는, 디바이스가 처리 가능 상태에 리셋 될 때까지 파기된다.

어플리케이션은, 디바이스가 소실했을 때의 처리를 판정하기 위해서 IDirect3DDevice8::TestCooperativeLevel 메소드의 반환값을 조회한다.

  • 메소드가 D3D_OK 를 돌려주는 경우, 디바이스는 처리 가능하다.
  • 디바이스가 소실해 복원할 수 없는 경우, 반환값은 D3DERR_DEVICELOST 가 된다. 이것은, 유저가 Alt + Tab 키를 눌러, 풀 스크린 디바이스의 포커스가 없어진 케이스이다. 어플리케이션의 응답으로서는, 디바이스를 리셋 할 수 있을 때까지 일시정지해야 한다. TestCooperativeLevel 로부터의 return code가 D3DERR_DEVICENOTRESET 이면, 리셋 할 수 있는 상태인 것을 나타낸다.
  • 디바이스가 소실하고 있어 복원할 수 있는 경우,TestCooperativeLevel 로부터의 return code는 D3DERR_DEVICENOTRESET 이다. IDirect3DDevice8::Present 메소드로부터의 return code는 아직 D3DERR_DEVICELOST 인 것에 주의 해야 한다.

어느 경우도,Reset 의 호출에는 비디오 메모리 리소스의 파기가 전제 조건이 된다. 이것은, 디바이스가 소실하고 있지 않는 경우도 마찬가지이다.


소실한 디바이스와 락 처리

내부적으로는, Microsoft® Direct3D® 에서는 디바이스가 소실해도 락 처리는 성공하도록(듯이) 기능한다. 그러나, 락 처리시에는 비디오 메모리 리소스의 데이터가 정확한가 어떤가는 보증되지 않는다. 에러 코드가 돌아가지 않는 것은 보증되고 있다. 따라서, 어플리케이션의 기술해서는, 락 처리시의 디바이스의 소실에 대해서는 고려하지 않아 좋다.

상세한 것에 대하여는, 「소실한 디바이스와 취득 데이터」를 참조할것.


소실한 디바이스와 리소스

리소스는 비디오 메모리를 소비한다. 소실한 디바이스는, 어댑터가 소유하는 비디오 메모리로부터 접속 해제되기 (위해)때문에, 디바이스가 소실했을 때의 비디오 메모리의 할당을 보증할 수 없다. 그 때문에, 모든 리소스 생성 메소드는, D3D_OK 가 돌아가면(자) 성공하지만 실제로는 더미의 시스템 메모리만을 할당하도록(듯이) 이행 되고 있다. 모든 비디오 메모리 리소스는, 디바이스를 사이즈 변경하기 전에 파기할 필요가 있기 (위해)때문에, 비디오 메모리의 과잉 할당은 발생하지 않는다. 이러한 더미 표면에 의해, 어플리케이션이 IDirect3DDevice8::Present 를 호출해 디바이스의 소실을 검출할 때까지, 락 처리나 카피 처리가 정상적으로 기능하고 있는 것처럼 보인다.

드라이버가 소실 상태로부터 처리 가능 상태에 복원되기 전에, 모든 비디오 메모리가 해방되지 않으면 안 된다. 즉, 어플리케이션은 IDirect3DDevice8::CreateAdditionalSwapChain 에 의해 생성 된 모든 스왑 체인이나 D3DPOOL_DEFAULT 메모리 클래스에 배치 떠날 수 있어 모든 리소스를 해방해야 한다고 하는 것이다. 어플리케이션은, D3DPOOL_MANAGED 메모리 클래스나 D3DPOOL_SYSTEMMEM 메모리 클래스에 배치되고 있는 리소스는 해방할 필요가 없다. 다른 상태 데이터는, 처리 가능 상태에의 트란지션에 의해 자동적으로 파기된다.

어플리케이션의 개발해서는, 디바이스의 소실에 대해서 1 개의 코드 패스로 대응하는 것을 추천 한다. 이 코드 패스는, 스타트 업시에 디바이스의 초기화에 사용한 코드 패스와 동일하지 않아도 유사하는 것으로 한다.


소실한 디바이스와 취득 데이터

Microsoft® Direct3D® 에 의해 어플리케이션은, 생성된 화면 (또는 이전에 그려진 화면)을, 비디오 메모리 리소스로부터 불휘발성의 시스템 메모리 리소스에 카피할 수가 있다. 이러한 전송에서는 전송원화면은 언제라도 없어질 가능성이 있기 (위해)때문에, Direct3D 에서는, 디바이스가 소실했을 때는 카피 처리를 실패시킬 수가 있다.

이 주제는 IDirect3DDevice8::UpdateTexture 에는 적용하지 않는다.

카피 처리 IDirect3DDevice8::UpdateTexture 및 IDirect3DDevice8::CopyRects 는, 전송원오브젝트가 휘발성 메모리 (D3DPOOL_DEFAULT)에 있을 때와 전송처 오브젝트가 불휘발성 메모리 (D3DPOOL_SYSTEMMEM 또는 D3DPOOL_MANAGED)에 있을 때는, D3DERR_DEVICELOST 를 돌려준다. 다른 카피 처리 IDirect3DDevice8::GetFrontBuffer 는, 프라이머리 표면으로부터 데이터를 취득하는 것에 의해 실패하는 경우가 있다. 위의 케이스는,IDirect3DDevice8::Present ,IDirect3DDevice8::TestCooperativeLevel , 및 IDirect3DDevice8::Reset 의 외부에서 D3DERR_DEVICELOST 를 사용하는 유일한 예인 것에 주의 해야 한다.


Direct3D 리소스

여기에서는, 리소스에 대하고, 또 어플리케이션에서의 리소스 사용의 개요에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 리소스란
  • 리소스 프로퍼티
  • 리소스의 상호 관계
  • 리소스의 사용법


리소스란

리소스와는, 장면의 렌더링에 사용되는 텍스쳐 및 버퍼이다. 어플리케이션은, 리소스를 생성, 로드, 카피, 및 사용할 필요가 있다. 여기에서는, 리소스의 개요와 리소스의 조작 순서 및 메소드에 대해 설명한다. 각 리소스 타입에 대해서는, 「텍스쳐」, 「버텍스 버퍼」, 및 「인덱스 버퍼」를 참조할것.

지오메트리 리소스 IDirect3DIndexBuffer8 및 IDirect3DVertexBuffer8 를 포함한 모든 리소스는,IDirect3DResource8 인터페이스로부터 계승한다. 텍스쳐 리소스 IDirect3DCubeTexture8 ,IDirect3DTexture8 , 및 IDirect3DVolumeTexture8 는,IDirect3DBaseTexture8 인터페이스로부터도 계승한다.


리소스 프로퍼티

모든 리소스는, 이하의 프로퍼티를 공유한다.

  • 사용. 텍스쳐, 렌더링 타겟으로서 사용하는 등, 리소스의 사용 방법.
  • 포맷. 2D 표면의 픽셀 포맷 등, 데이터의 포맷.
  • 풀. 리소스를 할당할 수 있는 메모리 타입.
  • 타입. 버텍스 버퍼, 렌더링 타겟 등, 리소스의 타입

리소스의 사용은 강제당한다. 특정의 처리에 리소스를 사용하는 어플리케이션은, 리소스 생성시에 그 처리를 지정할 필요가 있다. 리소스에는, 이하의 사용 방법이 정의되고 있다.

  • D3DUSAGE_DEPTHSTENCIL
  • D3DUSAGE_DONOTCLIP
  • D3DUSAGE_DYNAMIC
  • D3DUSAGE_RTPATCHES
  • D3DUSAGE_NPATCHES
  • D3DUSAGE_POINTS
  • D3DUSAGE_RENDERTARGET
  • D3DUSAGE_SOFTWAREPROCESSING
  • D3DUSAGE_WRITEONLY

D3DUSAGE_RTPATCHES 플래그, D3DUSAGE_NPATCHES 플래그, 및 D3DUSAGE_POINTS 플래그는, 이러한 버퍼내의 데이터가 각각, 삼각형 또는 구라두의 패치, N 패치, 포인트 스프라이트용으로 사용될 가능성이 있는 것을 드라이버에 나타낸다. 호스트 처리가 없으면 하드웨어가 이러한 처리를 실행할 수 없는 경우에, 이러한 플래그가 제공된다. 따라서, CPU 로부터 액세스 할 수 있도록(듯이), 드라이버는 이러한 표면을 시스템 메모리에 할당하는 것을 희망하게 된다. 드라이버가 이러한 처리를 완전하게 하드웨어내에서 실시할 수가 있으면, 이러한 표면을 비디오 또는 /AGP 메모리에 할당할 수 있으므로, 호스트에게 카피하지 않아도 되어, 퍼포먼스도 2 배 이상 향상한다. 이러한 플래그에 의해 제공되는 정보가 절대로 필요라고 하는 것은 아니다. 드라이버는, 데이터에 대해서 그러한 처리를 하고 있는 것을 검출할 수 있 이후의 프레임을 위해서(때문에) 버퍼를 시스템 메모리에 되돌린다.

이용 플래그와 그 플래그인가 관련지을 수 있고 있는 리소스의 상세한 것에 대하여는, 각 리소스 생성 메소드의 레퍼런스 페이지를 참조할것.

리소스의 표면 포맷의 상세한 것에 대하여는, 「D3DFORMAT 열거형」을 참조할것.

리소스의 버퍼를 보관 유지하는 메모리 클래스를 풀이라고 부른다. 풀값은,D3DPOOL 열거형으로 정의된다. 단일 리소스 (즉, 밉맵의 밉레벨) 내에 다른 오브젝트가 저장 되고 있는 경우, 풀을 믹스 할 수 없다. 또, 리소스의 풀을 선택한 다음에 변경할 수 없다.

리소스 타입은, 어플리케이션이 실행시에 IDirect3DDevice8::CreateCubeTexture 등의 리소스 생성 메소드를 호출했을 때, 비명시적으로 설정된다. 리소스 타입은,D3DRESOURCETYPE 열거형으로 정의된다. 어플리케이션에서는, 실행시에 이러한 타입을 조회할 수 있지만, 대부분의 시나리오에서는 실행시의 타입 체크는 필요로 하지 않는다.


리소스의 상호 관계

다음의 그림은, 특정의 리소스와 그 내용에 대해서, 구문적으로 가능한 처리를 나타내고 있다. 리소스의 사용 방법에 대해서는, 「리소스의 조작」을 참조할것.

왼쪽에서 오른쪽에의 화살표는, 타겟 타입이 그 메소드에 의해 생성 된 것을 나타내, 금방 다른 곳으로의 화살표는, 그러한 리소스가 인수로서 그 메소드에 건네줄 수 있는 것을 나타내고 있다.


리소스의 사용법

여기에서는, 리소스를 처리할 때에 어플리케이션이 실행하는 일반적인 태스크에 대해 설명한다.

  • 리소스의 관리
  • 어플리케이션 관리 리소스 및 할당 방법
  • 리소스의 조작
  • 리소스의 락


리소스의 관리

리소스 관리는, 리소스를 시스템 메모리 스토리지로부터 디바이스가 액세스 가능한 스토리지로 옮겨, 디바이스가 액세스 가능한 스토리지로부터 파기하는 프로세스이다. Microsoft® Direct3D® 런타임에는, LRU (least-recently-used) 우선 방식에 근거하는 독자적인 관리 알고리즘이 있다. 1 개의 프레임 (IDirect3DDevice8::BeginScene 호출과 IDirect3DDevice8::EndScene 호출동안) 내에서, 디바이스가 액세스 가능한 메모리에 공존할 수 있는 리소스수보다 많은 리소스가 검출되면(자), most-recently-used 우선 방식으로 바뀐다.

관리 리소스를 지정하려면 , 생성시에 D3DPOOL_MANAGED 플래그를 사용한다. 관리 리소스는, 디바이스의 소실 상태와 처리 가능 상태와의 사이의 트란지션에서도 보관 유지된다. 디바이스는,IDirect3DDevice8::Reset 호출에 의해 복원할 수 있어 이러한 리소스는 artwork에 재로드하지 않아도 계속 정상적으로 기능한다. 다만, 디바이스를 파기해 생성 다시 할 필요가 있는 경우, D3DPOOL_MANAGED 를 사용해 생성 된 리소스는 모두 생성 다시 할 필요가 있다.

리소스를 디폴트의 풀에 배치하는 것을 지정하려면 , 생성시에 D3DPOOL_DEFAULT 플래그를 사용한다. 디폴트의 풀내의 리소스는, 디바이스의 소실 상태와 처리 가능 상태간의 트란지션에서는 보관 유지되지 않는다. 이러한 리소스는 Reset 를 호출하기 전에 해방해, 그 후로 생성 다시 할 필요가 있다.

디바이스의 소실 상태의 상세한 것에 대하여는, 「소실한 디바이스」를 참조할것.

리소스 관리는, 모든 타입 및 사용에 대해서 지원 되고 있는 것은 아니기 때문에 주의 해야 한다. 예를 들어, D3DUSAGE_RENDERTARGET 플래그로 생성 된 오브젝트는 지원되어 있지 않다. 또, 높은 빈도로 내용이 변경되는 오브젝트에 대해서는, 리소스 관리는 장려하지 않는다. 예를 들어, 모든 프레임을 변경하는 관리 버텍스 버퍼의 경우, 어떠한 하드웨어의 퍼포먼스를 크게 저하시키는 일이 있다. 다만, 이것은 텍스쳐 리소스에 관한 문제는 아니다.


어플리케이션 관리 리소스 및 할당 방법

관리 버텍스 버퍼 리소스 또는 인덱스 버퍼 리소스는, 생성시에 D3DUSAGE_DYNAMIC 를 지정해도, 동적으로서 선언할 수 없다. 이 때문에는, 버텍스 버퍼의 내용에 가세하는 변경 마다 추가 카피가 필요하다. 동적 버텍스 버퍼는, BSP 트리 또는 그 외의 가시 데이터 구조로부터 취득한 데이터 뿐만이 아니라, 동적 지오메트리의 렌더링으로 사용할 수 있다. 이것은, 목적의 포맷의 버퍼를 사전에 할당하는 것으로 실현된다. 그 후, 이러한 리소스는, 어플리케이션의 요구를 지원 하기 위해서, 어플리케이션의 리소스 매니저에 의해 분할된다. 어플리케이션이 동시에 사용하는 다른 버텍스 보폭은 매우 불과 밖에 없고, 다른 버텍스 버퍼는 일의의 각 보폭 에 대해서만 필요해서, 동적 버텍스 버퍼의 총수는 적다. 이와 같이 해 동적 리소스를 관리 하면나무는, 리소스에의 고빈도인 요구에 의해 어플리케이션의 퍼포먼스가 저하하지 않게 하는 것이 중요하다.

D3D 관리 리소스와 어플리케이션 관리 리소스의 양쪽 모두를 동시에 사용할때는, 관리 리소스를 생성 하기 전에, 모든 어플리케이션 관리 리소스를 D3DPOOL_DEFAULT 메모리에 할당할 필요가 있다. D3DPOOL_MANAGED 메모리에 리소스를 할당한 다음에 D3DPOOL_DEFAULT 메모리에 리소스를 할당하면(자), D3D 메모리 리소스는 사용 가능 메모리의 부정확한 어카운트를 지정한다.


리소스의 조작

어플리케이션은, 장면을 렌더링 하기 위해서, 리소스를 조작한다. 최초로, 어플리케이션은 다음의 메소드를 사용해 텍스쳐 리소스를 생성 한다.

  • IDirect3DDevice8::CreateCubeTexture
  • IDirect3DDevice8::CreateTexture
  • IDirect3DDevice8::CreateVolumeTexture

텍스쳐 생성 메소드에 의해 돌려주어지는 텍스쳐 오브젝트는, 표면 또는 볼륨의 컨테이너이며, 이러한 컨테이너를 일반적으로 버퍼라고 부른다. 리소스가 소유하는 버퍼는, 리소스의 사용, 포맷, 및 풀은 계승하지만, 형태는 독자적인 형태가 된다. 상세한 것에 대하여는, 「리소스 프로퍼티」를 참조할것.

어플리케이션에서는 (artwork를 로드하기 (위해)때문에), 이하의 메소드를 호출해, 저장 된 표면에의 액세스를 취득한다. 상세한 것에 대하여는, 「리소스의 락」을 참조할것.

  • IDirect3DCubeTexture8::LockRect
  • IDirect3DTexture8::LockRect
  • IDirect3DVolumeTexture8::LockBox

락 메소드는, 저장 된 표면 (예를 들어, 텍스쳐의 밉피맙사브레벨 또는 큐브면) 및 픽셀에의 리턴 포인터를 지정하는 인수를 취한다. 일반적인 어플리케이션에서는, 표면 오브젝트를 직접 사용할 것은 없다.

한층 더 어플리케이션은, 다음의 메소드를 호출해, 지오메트리 지향의 리소스를 생성 한다.

  • IDirect3DDevice8::CreateIndexBuffer
  • IDirect3DDevice8::CreateVertexBuffer

어플리케이션은, 다음의 메소드를 호출해, 버퍼 리소스를 잠그어, 데이터를 설정한다.

  • IDirect3DIndexBuffer8::Lock
  • IDirect3DVertexBuffer8::Lock

이러한 리소스를 Microsoft® Direct3D® 런타임으로 관리하고 있는 어플리케이션의 경우, 리소스의 생성 프로세스는 여기서 종료한다. 그 이외의 어플리케이션에서는,IDirect3DDevice8::UpdateTexture 를 호출해, 시스템 메모리 리소스의 디바이스 액세스 가능한 리소스 (하드웨어 가속기를 사용할 수 있다)에의 이동을 관리한다.

리소스로부터 렌더링 한 화면을 제시하기 위해(때문에), 어플리케이션에는 칼라 버퍼와 스텐실 버퍼도 필요하다. 일반적인 어플리케이션의 경우, 칼라 버퍼는 디바이스의 스왑 체인 (백 버퍼 표면의 집합체)이 소유해, 디바이스에 의해 비명시적으로 생성 된다. 스텐실 표면은 암묵중에 생성 되는지,IDirect3DDevice8::CreateDepthStencilSurface 메소드를 사용해 명시적으로 생성 된다. 어플리케이션은 IDirect3DDevice8::SetRenderTarget 를 호출해, 디바이스와 그 깊이 및 칼라 버퍼를 관련짓는다.

최종적 화면의 제시에 대해서는, 「장면의 프레젠테이션」을 참조할것.


리소스의 락

리소스를 잠그면(자), 스토리지에의 CPU 액세스가 허가된다. 리소스에는, 다음의 락킹 메소드가 정의되고 있다.

  • D3DLOCK_DISCARD
  • D3DLOCK_READONLY
  • D3DLOCK_NOOVERWRITE
  • D3DLOCK_NOSYSLOCK
  • D3DLOCK_NO_DIRTY_UPDATE

락킹 플래그 및 락킹 플래그와 특정의 리소스와의 관계에 대해서는, 각 리소스 락킹 메소드의 레퍼런스 페이지를 참조할것. 어플리케이션 개발자는, D3DLOCK_DISCARD, D3DLOCK_READONLY, 및 D3DLOCK_NOOVERWRITE 플래그는 단순한 힌트에 지나지 않는 것에 주의 해야 한다. 런타임에서는, 어플리케이션이 이러한 플래그로 지정되고 있는 기능에 따르고 있는지 어떤지의 체크는 행해지지 않는다. D3DLOCK_READONLY 를 지정하면서 리소스에 기입을 실시했을 경우, 예기 할 수 없는 결과가 발생한다. D3DUSAGE_WRITEONLY 를 지정한 다음에 리소스로부터 read를 실시했을 경우, 퍼포먼스가 크게 저하하는 것이 예상된다. 일반적으로, 락킹 이용 플래그를 포함 락킹 플래그에 대한 처리가, 장래 사용할 수 있을까는 보증되지 않고, 현재에 있어도 향후냄새나도 퍼포먼스의 대폭적인 저하를 가져올 가능성이 있다.

락 처리의 뒤에는 락 해제 처리를 실시한다. 예를 들어, 텍스쳐를 잠근 후, 어플리케이션은 락 된 텍스쳐의 락을 해제해, 그 텍스쳐에의 직접 액세스를 방폐한다. 프로세서 액세스를 허가할 뿐만 아니라, 락 지속중은, 그 리소스와 관계되는 것 외의 모든 처리가 차례로 늘어놓을 수 있다. 오버랩 하지 않는 영역에서 만나도, 리소스에 대해서 1 개의 락만이 허가되어 표면상에 락 처리를 하고 있는 동안은, 그 표면에서의 가속기 처리는 실행할 수 없다.

각 리소스 인터페이스에는, 저장 되고 있는 버퍼를 잠그기 위한 메소드가 있다. 또, 각 텍스쳐 리소스는, 리소스의 서브 일부를 잠글 수 있다. 2 차원 리소스 (표면)에서는, 서브 직사각형을 잠글 수가 있어 볼륨 리소스에서는, 서브 볼륨 또는 박스를 잠글 수가 있다. 각 락킹 메소드는, 리소스를 되돌리는 스토리지에의 포인터와 데이터의 행간격 또는 평면 간격 (리소스 타입에 따라서 다르다)을 나타내는 값을 돌려준다. 상세한 것에 대하여는, 리소스 인터페이스의 메소드 리스트를 참조할것. 돌려주어지는 포인터는, 항상, 락 된 서브 리젼의 좌상의 바이트를 가리킨다.

인덱스 버퍼나 버텍스 버퍼를 조작하는 경우는, 복수의 락 호출을 실시할 수 있지만, 락 호출의 수와 락 해제 호출의 수가 일치하고 있을 필요가 있다.

encode 된 4 × 4 블록에 픽셀을 저장 하는 압축한 텍스쳐 포맷의 DXT 세트는, 4 × 4 의 경계에서만 잠글 수가 있다.


표면

여기에서는, Microsoft® Direct3D® 서페이스에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 표면의 기본 개념
  • 감마 컨트롤
  • 표면 메모리에의 직접 액세스
  • 프라이빗 표면 데이터


표면의 기본 개념

여기에서는, Microsoft® Direct3D® 표면에 관한 기본 개념에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 표면 인터페이스
  • 폭과 피치
  • 표면 포맷
  • 후립핑서페스
  • 표면에의 카피


표면 인터페이스

표면은, 디스플레이 메모리의 선형 영역을 나타내고 있다. 보통, 표면은 디스플레이 카드의 디스플레이 메모리에 상주하고 있지만, 시스템 메모리에 존재할 수도 있다. 표면 오브젝트는,IDirect3DSurface8 인터페이스내에 포함되어 있다.

IDirect3DSurface8 인터페이스를 취득하려면 , 다음의 몇개의 메소드를 호출한다.

  • IDirect3DCubeTexture8::GetCubeMapSurface
  • IDirect3DDevice8::CreateDepthStencilSurface
  • IDirect3DDevice8::CreateImageSurface
  • IDirect3DDevice8::CreateRenderTarget
  • IDirect3DDevice8::GetBackBuffer
  • IDirect3DDevice8::GetDepthStencilSurface
  • IDirect3DDevice8::GetFrontBuffer
  • IDirect3DDevice8::GetRenderTarget
  • IDirect3DSwapChain8::GetBackBuffer
  • IDirect3DTexture8::GetSurfaceLevel

IDirect3DSurface8 인터페이스에서는,IDirect3DDevice8::CopyRects 메소드에 의해 간접적으로 메모리에 액세스 할 수 있다. 이 메소드에서는, 픽셀의 직사각형 영역을, 어느 IDirect3DSurface8 인터페이스로부터 다른 IDirect3DSurface8 인터페이스에 카피할 수가 있다. 게다가 표면 인터페이스에는 디스플레이 메모리에 직접 액세스 하는 메소드도 있다. 예를 들어,IDirect3DSurface8::LockRect 메소드를 사용해, 디스플레이 메모리의 직사각형 영역을 잠글 수가 있다. 중요한 (일)것은, 표면 위에의 잠근 직사각형 영역을 조작한 다음에,IDirect3DSurface8::UnlockRect 를 호출하는 것이다.


폭과 피치

폭과피치라고 하는 단어로부터 어느 정도 상상할 수 있지만, 매우 중요한, 그리고 분명하게 다른 의미가 있다. 따라서, 그 의미와 Microsoft®Direct3D® 로 폭과 피치의 기술에 사용하는 값의 판단 방법을 이해할 필요가 있다.

Direct3D 에서는,D3DSURFACE_DESC 구조체를 사용해 표면을 기술하는 정보를 전달한다. 그 밖에도, 이 넓이의 메모리내에서의 표시 방법과 같게, 이 구조체는 표면의 넓이의 정보를 포함하기 위해서(때문에) 정의된다. 이 구조체에서는 Height 멤버와 Width 멤버를 사용해, 표면의 논리적인 넓이를 기술한다. 양쪽 모두의 멤버는 픽셀 단위로 측정된다. 그 때문에, 640 × 480 의 표면에 대한 Height 값과 Width 값은, 8 비트의 표면이나 24 비트의 RGB 표면인가에 관계없이 같게 된다.

IDirect3DSurface8::LockRect 메소드를 사용해 표면을 잠그면(자), 이 메소드는 표면의 피치와 락 된 비트에의 포인터를 포함한 D3DLOCKED_RECT 구조체에 데이터를 설정한다. Pitch 멤버의 값은, 표면의 메모리 피치 (또는,보폭으로 불린다)를 기술한다. 피치는, 2 개의 메모리 주소간 (있는 비트 맵 라인의 시점과 다음의 비트 맵 라인의 시점)의 거리이며, 단위는 바이트이다. 피치는 픽셀은 아니고 바이트 단위로 측정되기 위해서(때문에), 640 × 480 × 8 의 표면은, 다른 픽셀 포맷의 같은 넓이의 표면보다 매우 다른 피치의 값을 가진다. 게다가 피치의 값은 Direct3D 가 캐쉬로서 확보하는 바이트를 반영하는 일도 있으므로, 단지 피치를 픽셀 단위의 바이트수를 건 폭이라고 가정할 수 없다. 다음의 그림은, 폭과 피치의 차이를 나타내고 있다.

위의도에서는,프런트 버퍼와백 버퍼는 어느쪽이나 640 × 480 × 8 으로, 캐쉬는 384 × 480 × 8 이다.

표면 메모리에 직접 액세스 하는 경우만, 피치의 값이 도움이 된다. 예를 들어,LockRect 메소드를 호출한 후에, 관련지을 수 있었던 D3DLOCKED_RECT 구조체의 pBits 멤버에는, 그 표면의 락 된 영역의 좌상 픽셀의 주소가 포함되어Pitch 멤버는 표면 피치가 된다. 픽셀 단위의 바이트수에 의해, 표면 포인터를 인크리먼트(increment) 하거나 감소 하는 것으로, 좌우에 픽셀에 액세스 할 수 있다. 또, 피치의 값을 현재의 표면 포인터에 추가하거나 또는 그 포인터로부터 줄이거나 하면, 상하로 이동할 수 있다.

표면에 직접 액세스 하는 경우, 표면의 넓이에 대해서 할당할 수 있었던 메모리의 범위내에 두는 것으로, 캐쉬에 대해서 확보된 모든 메모리의 밖에 두는 것에 주의한다. 게다가 표면의 포인터만을 잠그는 경우, 표면을 잠글 때 지정하는 직사각형의 범위내에 두지 않으면 안 된다. 이것에 따르지 않다고 예측 불가능한 결과가 생긴다. 표면 메모리에 직접 렌더링 하면나무는,LockRect 메소드가 돌려주는 피치를 항상 사용한다. 단지, 디스플레이 모드에 근거하는 피치를 가정해 사용해서는 안 된다. 다른 원인에 의해 정상적으로 동작하지 않게 된 몇개의 디스플레이 어댑터상에서 어플리케이션이 동작하는 경우, 문제가 생길 가능성이 있다.

상세한 것에 대하여는, 「표면 메모리에의 직접 액세스」를 참조할것.


표면 포맷

표면 포맷은, 표면 메모리내의 각 픽셀의 데이터를 어떻게 판단하는지를 지시한다. Microsoft® Direct3D® 는,D3DSURFACE_DESC 구조체의 D3DFORMAT 멤버를 사용해 표면 포맷을 기술한다. IDirect3DSurface8::GetDesc 메소드를 호출하는 것에 의해, 기존의 표면의 포맷을 취득할 수가 있다.


후립핑서페스

Microsoft® Direct3D® 어플리케이션은, 보통, 백 버퍼에 애니메이션의 프레임을 생성해, 연속해 제시하는 것으로, 애니메이션을 표시한다. 백 버퍼는 스왑 체인에 분할된다. 스왑 체인이란, 스크린에 순서에 “플립”하는 일련의 버퍼이다. 이 스왑 체인을 사용 하면, 메모리내가 있는 장면을 렌더링 해, 렌더링이 완료하면(자) 그 장면을 스크린에 플립 할 수 있다. 이것으로,테아링으로 불리는 현상을 막아, 보다 매끄러운 애니메이션을 얻을 수 있다.

Direct3D 로 생성 된 각 디바이스는, 스왑 체인을 적어도 1 개(살)은 가지고 있다. 최초의 Direct3D 디바이스를 초기화할 경우에, 스왑 체인내에 있는 백 버퍼의 수를 Direct3D 에 지시하는 D3DPRESENT_PARAMETERS 구조체의 BackBufferCount 멤버를 설정한다. IDirect3D8::CreateDevice 를 호출해, 다음에, Direct3D 디바이스 및 대응하는 스왑 체인을 생성 한다.

IDirect3DDevice8::Present 메소드를 이용해 서페스후립핑 처리를 요구하는 경우, 프런트 버퍼와 백 버퍼에 대한 표면 메모리에의 포인터는 스왑 된다. 후립핑은, 표면 메모리를 카피하는 것은 아니고, 메모리를 참조하기 위해서 디스플레이 디바이스의 사용하는 포인터를 바꾸는 것으로 실행된다. 후립핑체에 프런트 버퍼와 1 개 이상의 백 버퍼가 있는 경우, 다음의 그림에 나타내도록(듯이), 포인터는 순환적 패턴으로 교체된다.

디바이스의 추가 스왑 체인을 생성 하려면 ,IDirect3DDevice8::CreateAdditionalSwapChain 를 호출한다. 어플리케이션은 뷰 마다 1 개의 스왑 체인을 생성 해, 그 스왑 체인을 특정의 윈도우에 관련짓는다. 어플리케이션에서는, 각 스왑 체인의 백 버퍼에 화면을 렌더링 해, 다음에 그것을 개별적으로 제시한다. CreateAdditionalSwapChain 가 받는 2 개의 파라미터는,D3DPRESENT_PARAMETERS 구조체에의 포인터와 IDirect3DSwapChain8 인터페이스에의 포인터의 주소이다. 다음에,IDirect3DSwapChain8::Present 를 사용해, 다음의 백 버퍼의 내용을 프런트 버퍼에 표시한다. 각 디바이스는 풀 스크린 스왑 체인을 1 개 밖에 가질 수 없는 것에 주의 해야 한다.

특정의 백 버퍼에 액세스 하려면 ,IDirect3DDevice8::GetBackBuffer 메소드 또는 IDirect3DSwapChain8::GetBackBuffer 메소드를 호출한다. 이러한 메소드는, 돌려주어지는 백 버퍼 표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터를 돌려준다. 이 메소드를 호출하면,IDirect3DDevice8 인터페이스의 내부 참조 카운트가 증가하므로, 이 표면을 사용한 후는, 반드시 IUnknown::Release 를 호출하도록(듯이) 주의 해야 한다. 호출하지 않으면 메모리 누수가 일어난다.

Direct3D 는, 표면 자체를 스왑 하는 것이 아니라, 스왑 체인내의 표면 메모리 포인터를 스왑 하는 것으로, 표면의 후립핑을 실시하는 것을 생각해 내는 것. 즉, 다음에 표시되는 백 버퍼에 대해서 항상 렌더링 하면 말하는 것이다.

디스플레이 어댑터 드라이버에 의해 행해지는 "후립핑 처리" 와 D3DSWAPEFFECT_FLIP 를 사용해 생성 된 스왑 체인에 적용되는 "Present" 처리에는, 분명한 차이가 있는 것에 주의 해야 한다가 중요하다.

일반적으로 "플립" 이라고 하는 용어는, 디스플레이 어댑터가 그 출력 신호를 생성하기 위해서 사용하는 비디오 메모리의 주소 범위를 변경하는 처리여, 이것에 의해 은폐 백 버퍼의 내용이 표시된다. DirectX 8 의 경우, 이 용어는, D3DSWAPEFFECT_FLIP 스왑 이펙트로 생성 된 스왑 체인에 있어서의 백 버퍼의 프레젠테이션을 나타내기 위해서(때문에), 보다 일반적으로 사용된다.

스왑 체인이 풀 스크린의 경우에 "Present" 처리가 거의 항상 플립 처리에 의해 이행 될 때, 이러한 처리는 스왑 체인이 윈도우 시에 반드시 카피 처리에 의해 이행 된다. 게다가 디스플레이 어댑터 드라이버는, D3DSWAPEFFECT_DISCARD, D3DSWAPEFFECT_COPY, 및 D3DSWAPEFFECT_COPY_VSYNC 스왑 체인에 근거하는 풀 스크린 스왑 체인에 대해서 Present 처리를 이행 하기 위해서 후립핑을 사용할 수 있다.

지금까지의 설명은, D3DSWAPEFFECT_FLIP 로 생성 된 풀 스크린 스왑 체인을 사용하는 일반적인 케이스에 적용된다.

윈도우 스왑 체인 및 풀 스크린 스왑 체인이 다른 스왑 이펙트의 일반적인 설명에 대해서는, 「D3DSWAPEFFECT 」를 참조할것.


표면에의 카피

IDirect3DDevice8::CopyRects 메소드를 사용할때는, 전송원표면 위에의 직사각형의 배열 또는 NULL 를 건네주어, 표면 전체를 지정한다. 또, 전송원이미지의 각 직사각형의 좌상구석이 카피되는 전송처 표면 위에의 포인트의 배열을 건네준다. 이 메소드는 클리핑을 지원 하고 있지 않다. 모든 전송원직사각형 및 대응하는 전송처 직사각형이, 각각 전송원 및 전송처 표면내에 완전하게 포함되지 않은 경우에는, 이 메소드가 실패한다. 이 메소드는, 알파 블렌딩, 칼라 키, 및 포맷 변환은 지원 하고 있지 않다. 전송처 표면과 전송원표면은 다르지 않으면 안 되는 점에 주의 해야 한다.

CopyRects 의 예

다음에 나타내는 예에서는, 2 개의 직사각형이 전송원표면으로부터 전송처 표면에 카피된다. 최초의 직사각형은, 전송원표면 위에의 (0, 0, 50, 50)로부터 전송처 표면 위에의 같은 위치에 카피되어 2 번째의 직사각형은, 전송원표면 위에의 (50, 50, 100, 100)로부터 전송처 표면 위에의 (150 , 150, 200, 200)에 카피된다.

//이 코드에서는,
//-d3dDevice 는 유효한 Direct3DDevice8 오브젝트이며,
//-pSource 와 pDest 는 유효한 IDirect3DSurface8 포인터이라고 가정하고 있다.

RECT  rcSource[] = {  0,  0,  50,  50,
                     50, 50, 100, 100 };
POINT ptDest[]   = {  0,  0, 150, 150 };

d3dDevice->CopyRect( pSource, rcSource, 2, pDest, ptDest);

C++/C 에서는, Microsoft® Direct3D® 표면에 이미지를 카피하는 경우에, 다음의 메소드도 사용할 수 있다.

  • D3DXLoadSurfaceFromFileA
  • D3DXLoadSurfaceFromFileInMemory
  • D3DXLoadSurfaceFromFileW
  • D3DXLoadSurfaceFromMemory
  • D3DXLoadSurfaceFromResourceA
  • D3DXLoadSurfaceFromResourceW
  • D3DXLoadSurfaceFromSurface
  • IDirect3DDevice8::CopyRects


감마 컨트롤

여기에서는, Microsoft® Direct3D® 로 사용되는 감마 컨트롤에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 감마 컨트롤이란
  • 감마 컨트롤의 사용법


감마 컨트롤이란

감마 컨트롤에서는, 표면 자체의 컨텐츠에 영향을 주는 일 없이, 시스템이 표면의 컨텐츠를 표시하는 방법을 변경할 수 있다. 이러한 컨트롤은, Microsoft® Direct3D® 가 스크린상에서 렌더링 되기 전에 표면을 남기는 것과 같이, 데이터에 적용하는 매우 단순한 필터라고 생각된다.

감마 컨트롤은, 스왑 체인의 단순한 프로퍼티에 지나지 않는다. 감마 컨트롤은, 시스템이 표시하는 실제의 레벨에 표면의 적, 초록, 및 파랑의 레벨 맵을 동적으로 변경할 수 있다. 감마 레벨을 설정하는 것으로, 이펙트를 붙이는 frame buffer에 새로운 이미지를 카피하지 않고 , 유저의 스크린에 플래시 칼라 (유저의 캐릭터를 낼 때의 빨강, 캐릭터가 새로운 아이템을 취득 하면나무의 초록등)를 적용할 수 있다. 또는, 칼라 레벨을 조절해, 백 버퍼의 이미지에 칼라 바이어스를 적용할 수 있다.

Microsoft® Direct3D® for Microsoft DirectX® 8.0 은 디바이스의 프로퍼티로서 1 개의 스왑 체인을 가지고 있기 (위해)때문에, 각 디바이스에 대해서, 항상 적어도 1 개의 스왑 체인 (비명시적인 스왑 체인)이 존재한다. 감마 램프는 스왑 체인의 프로퍼티이므로, 스왑 체인을 윈도우로 할 때는 감마 램프를 적용할 수 있다. 감마 램프는 즉시 유효하게 된다. VSYNC 를 대기할 수 없다.

감마 컨트롤의 사용 방법의 상세한 것에 대하여는, 「감마 컨트롤의 사용법」을 참조할것.


감마 컨트롤의 사용법

IDirect3DDevice8::SetGammaRamp 메소드와 IDirect3DDevice8::GetGammaRamp 메소드에서는, 디스플레이에 대한 디지털-아날로그 컨버터 (DAC)에 픽셀이 보내지기 전에, 표면으로부터 픽셀의 적, 초록, 및 파랑의 색성분에 영향을 주는 램프 레벨을 조작할 수 있다.

여기에서는, 램프 레벨의 일반적인 개념과 이러한 레벨의 처리에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 감마 램프 레벨에 대해
  • 감마 램프 지원의 검출
  • 감마 램프 레벨의 설정과 취득


감마 램프 레벨에 대해

Microsoft® Direct3D® 에서는,감마 램프라고 하는 용어는 일련의 값을 나타낸다. 이 일련의 값은, frame buffer의 모든 픽셀에 대해서, 디스플레이에 대한 디지털 아날로그 컨버터 (DAC)에 의해 수취되는 새로운 레벨에, 특정의 색성분 (적, 초록, 및 파랑)의 레벨을 맵 하는 값이다. 재매핑은, 3 개의 참조 테이블 (개개의 색성분에 대해서 1 개)에 의해 실행된다.

여기에서는 그방법에 대해 설명한다. Direct3D 는 frame buffer로부터 픽셀을 취득해, 그 고유의 적, 초록, 및 파랑의 색성분으로 픽셀을 취득한다. 개개의 컴퍼넌트는 0 에서 65535 까지의 값으로 나타내진다. Direct3D 는 원의 값을 취득해, 그 값을 사용해 256 요소 배열 (램프)의 인덱스를 붙인다. 이 배열에는, 개개의 요소를 원의 요소와 옮겨놓는 값을 포함한다. Direct3D 에서는, frame buffer내의 각 픽셀의 각 색성분에 대해서 "참조와 치환" 의 프로세스를 실행해, 스크린 위에의 모든 픽셀에 대한 최종적인 색을 변경한다.

램프값의 그래프를 생성 하면, 시각화 되어 용이하게 이해할 수 있다. 다음에, 2 개의 그래프를 나타낸다. 좌측의 그래프는 색이 전혀 변경되지 않는 램프를 나타낸다. 우측의 그래프는 부의 바이어스를 적용하는 색성분에 두는 램프를 나타낸다.

좌측의 그래프의 배열 요소에는, 그러한 인덱스와 동일한 값 (인덱스 0 에는 요소 0, 및 인덱스 255 에는 65535)이 포함된다. 이러한 값이 표시되기 전의 입력값은 변경할 수 없기 때문에, 램프의 이 타입이 디폴트가 된다. 우측의 그래프는, 보다 큰 변동을 나타낸다. 이 램프에는, 최초의 요소 0 으로부터 마지막 요소 32768 까지의 값이, 중간의 비교적 한결같은 범위의 값으로 포함된다. 이 이펙트는, 이 램프를 사용하는 색성분이 디스플레이상에서 소리를 지워 표시된다. 선형 그래프의 이용인 만큼 한정되지 않는다. 즉, 필요에 따라서, 어플리케이션으로 임의의 매핑을 할당할 수가 있다. 게다가 입력을 모두 제로로 설정 하면, 디스플레이로부터 색성분을 삭제할 수 있다.


감마 램프 지원의 검출

디바이스가 스왑 체인의 현재의 프레젠테이션 모드 (풀 스크린 또는 윈도우)에 대해 감마 램프를 지원 하고 있지 않는 경우에서도, 에러값이 돌아갈 것은 없다. 어플리케이션에서는, D3DCAPS8 형의 Caps2 멤버의 D3DCAPS2_FULLSCREENGAMMA 능력 비트 및 D3DCAPS2_CANCALIBRATEGAMMA 능력 비트를 조사해, 디바이스의 능력 및 구경 측정기가 인스톨 되고 있는지 어떤지를 판단할 수 있다.


감마 램프 레벨의 설정과 취득

감마 램프 레벨은 효과적인 참조 테이블이며, Microsoft®Direct3D® 가 표시되는 새로운 레벨에 frame buffer색성분을 맵 하기 위해서 사용한다. 상세한 것에 대하여는, 「감마 램프 레벨에 대하며」를 참조할것. IDirect3DDevice8::SetGammaRamp 메소드 및 IDirect3DDevice8::GetGammaRamp 메소드를 호출하는 것으로, 프라이머리 표면에 대한 램프 레벨을 설정해, 취득할 수 있다. SetGammaRamp 는 2 개의 파라미터를 받아,GetGammaRamp 는 1 개의 파라미터를 받는다. SetGammaRamp 의 제 1 파라미터는, D3DSGR_CALIBRATE 나 D3DSGR_NO_CALIBRATION 의 언젠가이다. 제 2 파라미터 pRamp 는,D3DGAMMARAMP 구조체에의 포인터이다. D3DGAMMARAMP 구조체에는,WORD 의 256 요소 배열을 3 개 (1 개의 배열 마다 적, 초록, 파랑의 감마 램프) 포함한다. GetGammaRamp 에는, 현재의 감마 램프를 저장 하는 D3DGAMMARAMP 형에의 포인터를 받는 파라미터가 1 개 있다.

SetGammaRamp 의 제 1 파라미터에 DDSGR_CALIBRATE 값을 포함하면(자), 새로운 감마 레벨을 설정할 경우에 구경 측정기를 기동할 수 있다. 감마 램프를 calibration 하면 얼마인가 오버헤드가 있으므로, 빈번하게는 사용할 수 없다. 조정된 감마 램프의 설정은, 디스플레이 어댑터 및 모니터에 관계없이, 일관성이 있는 완전한 감마값을 제공한다.

모든 시스템이 감마 calibration를 지원 하는 것은 아니다. 감마 calibration를 지원 할지 어떨지를 판정하려면 ,IDirect3DDevice8::GetDeviceCaps 를 호출해, 메소드가 돌아온 후에 관련지을 수 있었던 D3DCAPS8 구조체의 Caps2 멤버를 조사한다. D3DCAPS2_CANCALIBRATEGAMMA 능력 플래그가 존재 하면, 감마 calibration는 지원 된다.

새로운 램프 레벨을 설정하는 경우, 그 배열로 설정한 레벨은 어플리케이션이 풀 스크린 (배타 모드)의 경우에만 사용된다. 어플리케이션이 노멀 모드로 변경되면(자), 항상 램프 레벨은 측에 설정되어 어플리케이션이 풀 스크린 모드에 복귀될 때 다시 취득된다.


표면 메모리에의 직접 액세스

표면 메모리에 직접 액세스 하려면 ,IDirect3DSurface8::LockRect 메소드를 사용한다. 이 메소드를 호출하는 경우,pRect 파라미터는, 직접 액세스 하려고 하는 표면 위에의 직사각형을 기술하는 RECT 구조체에의 포인터로 한다. 표면 전체를 잠그려면 ,pRect 를 NULL 로 설정한다. 또, 표면의 일부만을 커버하는 RECT 를 지정할 수도 있다. 2 개의 직사각형이 겹치지 않으면, 2 개의 thread 또는 2 개의 프로세스는, 표면의 복수의 직사각형을 동시에 잠글 수가 있다. 멀티 샘플 백 버퍼는 잠글 수 없는 것에 주의 해야 한다.

LockRect 메소드는, 표면 메모리에 올바르고 액세스 하기 위해서 필요한 모든 정보를,D3DLOCKED_RECT 구조체에 저장 한다. 이 구조체에는,피치에 관한 정보가 포함되어 있어 락 되고 있는 비트에의 포인터가 있다. 표면 메모리에의 액세스가 종료 하면,IDirect3DSurface8::UnlockRect 메소드를 호출해, 락을 해제한다.

표면을 잠그고 있는 동안, 그 컨텐츠를 직접 조작할 수가 있다. 표면 메모리를 직접 렌더링 하면나무의 일반적인 문제를 피하기 위한 힌트를, 이하의 리스트로 가리킨다.

  • 일정한 디스플레이 피치를 가정하지 않는다. 항상,LockRect 메소드가 돌려주는 피치 정보를 조사하는 것. 이 피치는, 표면 메모리의 위치, 디스플레이 카드의 타입, Microsoft® Direct3D® 드라이버의 버젼 등, 다양한 이유에 의해 변화한다. 상세한 것에 대하여는, 「폭과 피치」를 참조할것.
  • 락이 해제된 표면에의 카피를 확인한다. Direct3D 카피 메소드는, 락 된 표면으로 불려 가면(자), 실패한다.
  • 표면이 락 되고 있는 동안, 어플리케이션의 액티버티는 제한된다.
  • 디스플레이 메모리에 대해서 연속하는 데이터를 항상 카피하는 Microsoft® Windows® 95 및 Windows 98 에서는, 페이지 폴트 핸들러 Vflatd. 386 을 사용해, 반크스잇치메모리를 사용한 디스플레이 카드에 대한 가상 플랫 frame buffer를 이행 한다. 이 핸들러에 의해, 이러한 디스플레이 디바이스는 Direct3D 에 연속한 frame buffer를 건네줄 수가 있다. 디스플레이 메모리에 대해서 불연속의 데이터를 카피 하면, 카피가 메모리 뱅크에 스팬 하는 경우에, 시스템이 일시정지를 일으킬 가능성이 있다.
  • D3DPOOL_DEFAULT 메모리 풀에 할당할 수 있었던 리소스에 속하는 표면은, 락 되지 않는 경우가 있다. 백 버퍼 표면 (IDirect3DDevice8::GetBackBuffer 및 IDirect3DSwapChain8::GetBackBuffer 메소드를 사용해 액세스 할 수 있다)을 잠글 수 있는 것은, 스왑 체인이 D3DPRESENTFLAG_LOCKABLE_BACKBUFFER 를 포함하도록(듯이) D3DPRESENT_PARAMETERS 구조체의 Flags 멤버를 사용해 생성 되고 있는 경우 뿐이다.


프라이빗 표면 데이터

표면과 함께 모든 종류의 어플리케이션 고유 데이터를 저장 할 수 있다. 예를 들어, 게임의 맵을 나타내는 표면에는, 지역 정보를 포함한 경우가 있다.

표면에서는, 1 개(살) 이상의 프라이빗 데이터 버퍼를 소유할 수 있다. 각 버퍼는, 표면에 데이터를 어태치 할 때로 지정하는 GUID 로 식별된다.

프라이빗 표면 데이터를 저장 하려면 ,IDirect3DSurface8::SetPrivateData 메소드를 사용한다. 이 메소드는, 전송원버퍼, 데이터의 사이즈, 데이터용으로 어플리케이션으로 정의한 GUID 에의 포인터를 건네준다. 수의에, 전송원데이터는 COM 오브젝트의 폼에 존재할 수 있다. 이 경우, 오브젝트의 IUnknown 인터페이스 포인터에 포인터를 건네주어, D3DSPD_IUNKNOWNPOINTER 플래그를 설정한다.

SetPrivateData 는 데이터에 대해서 내부 버퍼를 할당해 데이터를 카피한다. 그 후로, 전송원버퍼 또는 오브젝트를 안전하게 해방할 수 있다. 내부 버퍼 또는 인터페이스 참조는,IDirect3DSurface8::FreePrivateData 의 호출시에 해방된다. 표면이 해방되면(자), 이 처리는 자동적으로 발생한다.

표면에 대한 프라이빗 데이터를 취득하려면 , 정확한 사이즈의 버퍼를 할당해SetPrivateData 로 데이터에 할당할 수 있었던 GUID 를 건네주는 IDirect3DSurface8::GetPrivateData 메소드를 호출하지 않으면 안 된다. 이 버퍼를 사용하는 모든 동적 메모리의 해방에 대해서는, 각자 책임을 가진다. 데이터가 COM 오브젝트의 경우, 이 메소드는 Iunknown 포인터를 취득한다.

할당하는 버퍼의 사이즈를 모르는 경우는, 최초로 SizeOfData 에 제로를 대입해 GetPrivateData 를 호출한다. 이 메소드가 D3DERR_MOREDATA 로 실패했을 경우, 버퍼에 필요한 바이트수를 SizeOfData 에 돌려준다.


라이트

라이트는, 장면의 오브젝트를 비추기 위해서(때문에) 사용한다. 여기에서는, 라이팅, 및 Microsoft® Direct3D® 어플리케이션에서의 라이트의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 라이팅과 머트리얼의 개요
  • Direct3D 의 라이팅 모델과 자연광의 비교
  • 라이팅과 머트리얼의 칼라값
  • 다이렉트 라이트와 앰비언트 라이트의 비교
  • 라이트 오브젝트
  • 라이트 프로퍼티
  • 라이트의 사용법


라이팅과 머트리얼의 개요

라이팅이 유효하게 되어 있을 때, Microsoft® Direct3D® 는 렌더링의 최종 단계로서 장면을 rasterize 할 때, 장면의 광원에 의해 생성되는 라이팅의 색과 강도나, 장면의 앰비언트 라이트 레벨 외에도, 현재의 머트리얼 칼라 및 관련지을 수 있었던 텍스쳐 맵의 텍셀, 버텍스의 디퓨즈색과 스펙큐러색 (지정되고 있는 경우) 의 편성에 근거해, 렌더링 하는 각 픽셀의 색을 결정한다. Direct3D 의 라이팅과 머트리얼을 사용할때는, Direct3D 로 자동적으로 라이팅의 상세를 제어하도록 할 수 있다. 경험을 쌓은 유저이면, 필요에 따라서 스스로 라이팅을 실행할 수 있다.

라이팅과 머트리얼의 처리 방법에 따라, 렌더링 한 장면의 표시는 크게 다르다. 머트리얼은, 표면으로부터의 반사광 상태를 정의한다. 다이렉트 라이트와 앰비언트 라이트 레벨은, 반사광을 정의한다. 라이팅이 유효 때는, 머트리얼을 사용해 장면을 렌더링 해야 한다. 라이팅은 장면의 렌더링에 대해 필수는 아니지만, 라이팅없이 렌더링 한 장면의 세부는 안보인다. 라이팅이 없는 장면을 렌더링 했을 경우는, 장면의 오브젝트의 실루엣이 표시되는 정도이다. 세부는 충분히 표시되지 않는다.


Direct3D 의 라이팅 모델과 자연광의 비교

자연계에서는, 광원으로부터 방사된 빛은, 몇천이나 몇백만은 아닌으로 해도, 몇백의 물체에 반사한 끝에 우리의 눈에 닿는다. 빛은 반사할 때마다, 그 일부가 물체의 표면에 흡수되거나 주위에 확산해, 그 나머지가 다른 표면이나 우리에 이른다. 이 과정은, 빛이 감쇠해 사라져 없어지는지, 또는 우리가 빛이 닿은 것을 지각할 때까지 반복해진다.

자연광의 움직임을 완전하게 시뮬레이트 하는 계산에는, 너무 방대한 시간이 걸리기 (위해)때문에, 리얼타임 3D 그래픽스로 사용할 수 없는 것은 명백하다. 거기서, 속도를 고려해, Microsoft® Direct3D® 의 라이팅 모델에서는 자연광의 움직임을 대략적으로 시뮬레이트 한다. Direct3D 에서는, 최종적인 색을 생성 하는 색성분, 적, 록, 및 파랑에 의해 빛을 그린다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 칼라값」을 참조할것.

Direct3D 에서는, 빛이 표면에 반사했을 때, 빛의 색과 표면 자체를 수학적으로 처리하는 것으로, 최종적으로 스크린에 드로잉(Drawing) 되는 색을 생성 한다. Direct3D 로 사용하는 알고리즘에 관한 특정의 정보에 대해서는, 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.

Direct3D 의 라이팅 모델은, 크게 나누어 앰비언트 라이트와 다이렉트 라이트의 2 개가 있다. 이것들은 서로 다른 속성을 가져, 표면의 머트리얼과의 상호작용도 다르다. 앰비언트 라이트는, 방향도 광원도 가지지 않고, 환경내를 산란하고 있는 빛으로, 환경빛이라고도 말한다. 앰비언트 라이트의 강도는, 어느 위치 좌표에 대해도 하위 레벨로 유지된다. 앰비언트 라이트의 적절한 예로서는, 카메라맨이 사용하는 간접조명이 있다. Direct3D 의 앰비언트 라이트에게는, 자연광과 같이, 실제의 방향이나 광원은 없다. 어느 색과 강도뿐이다. 실제, 앰비언트 라이트의 레벨은, 장면내의 미츠를 출발하는 오브젝트와는 전혀 관계하지 않는다. 앰비언트 라이트는 스펙큐러 반사를 일으키지 않는다.

다이렉트 라이트는, 장면내의 광원이 생성하는 빛이다. 다이렉트 라이트에게는 항상 색과 강도가 있어, 특정의 방향으로 나아간다. 다이렉트 라이트는, 표면의 머트리얼과 상호작용 해 스펙큐러 하이라이트를 낳아, 그 방향은 gouraud shading등의 쉐이딩 알고리즘으로 계수로서 사용된다. 다이렉트 라이트의 반사는, 장면의 앰비언트 라이트의 레벨에 영향을 주지 않는다. 장면내의 다이렉트 라이트를 생성하는 광원에는 다양한 특성이 있어, 거기에 따라 장면을 어떻게 비출지가 다르다. 상세한 것에 대하여는, 「라이트」를 참조할것.

게다가 다각형의 머트리얼에는, 다각형이 빛을 어떻게 반사할까를 결정하는 특성이 있다. 머트리얼이 어떻게 앰비언트 라이트를 반사하는지를 나타내는 단일의 반사 특성을 설정해, 머트리얼의 스펙큐러 반사율 및 디퓨즈 반사율을 결정하는 개개의 특성을 설정한다. 상세한 것에 대하여는, 「머트리얼」을 참조할것.


라이팅과 머트리얼의 칼라값

Microsoft® Direct3D® 에는, 색을 기술하는 4 개의 성분 (적, 록, 청, 및 알파)이 있어, 이것들을 조합해 최종적인 색이 생성된다. C++ 의 D3DCOLORVALUE 구조체는, 이러한 각 성분을 저장 하도록(듯이) 정의된다. 각 멤버는, 보통 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 의 범위의 부동 소수점값이다. 라이팅과 머트리얼에서는, 모두 같은 구조체를 사용해 색을 기술하지만, 구조 체내에서 사용하는 값은 서로 조금씩 다르다.

광원의 칼라값은, 광원이 출발하는 특정의 빛의 성분의 양을 나타낸다. 라이팅에서는 알파 성분은 사용하지 않기 때문에, 적, 록, 및 파랑 성분만 관련이 있다. 이러한 3 개의 성분은, 프로젝션 모니터의 적색, 녹색, 및 청색의 렌즈에 비유할 수가 있다. 각 렌즈를 오프로 하거나 (대응하는 멤버에 0.0 을 설정), 가능한 한 밝게 하거나 (1.0 을 설정), 그 사이의 레벨을 설정할 수가 있다. 각 렌즈로부터의 색을 조합해, 최종적인 라이팅의 색을 생성 한다. R:1. 0, G:1. 0, B:1. 0 의 편성의 경우, 백색광이 되어, R:0. 0, G:0. 0, B:0. 0 의 경우는 빛을 전혀 방사하지 않는 라이팅이 된다. 색성분을 1 개만 방사하는 라이팅을 생성 해, 순수한 적색, 녹색, 또는 청색의 라이팅을 만들 수가 있다. 또, 색성분의 조합해에 따라서는, 황색이나 보라색등의 색을 방사하는 라이팅을 생성 할 수도 있다. 색성분값을 부로 해, 장면으로부터 빛을 없애는 것 같은 "암색빛" 을 생성 할 수 있다. 또, 성분에 1.0 보다 큰 값을 설정해, 극단적으로 밝은 라이팅을 생성 할 수도 있다.

한편, 머트리얼의 경우, 칼라값은 그 머트리얼을 사용하는 표면이 어느 정도 빛의 성분을 반사하는지를 나타낸다. 머트리얼의 색성분이 R:1. 0, G:1. 0, B:1. 0, A:1. 0 의 경우, 머트리얼은 모든 빛을 반사한다. 같이 R:0. 0, G:1. 0, B:0. 0, A:1. 0 의 경우는, 녹색의 빛을 모두 반사한다. 머트리얼에 복수의 반사율을 지정해, 다양한 이펙트를 생성 할 수 있다. 상세한 것에 대하여는, 「머트리얼 프로퍼티」를 참조할것.

앰비언트 라이트의 칼라값은, 다이렉트 라이트 광원과 머트리얼에 사용하는 칼라값과는 다르다. 상세한 것에 대하여는, 「다이렉트 라이트와 앰비언트 라이트의 비교」를 참조할것.


다이렉트 라이트와 앰비언트 라이트의 비교

다이렉트 라이트와 앰비언트 라이트는 ,함께 장면내의 오브젝트를 비추지만, 양자는 서로 서로 영향을 줄 것은 없고, 각각이 가지는 이펙트는 크게 달라서 , 이러한 조작 방법에 대해서도 완전히 다르다.

다이렉트 라이트는, 문자 대로, 다이렉트이다. 다이렉트 라이트는 항상 방향과 색을 가져, 이것은 gouraud shading등의 쉐이딩 알고리즘의 계수로서 사용된다. 라이팅의 종류가 다르면, 다이렉트 라이트의 방사도 달라, 각각 특별한 감쇠 이펙트를 낳는다. 다이렉트 라이트의 라이팅 파라미터 세트는,IDirect3DDevice8::SetLight 메소드를 호출해 생성 한다. 상세한 것에 대하여는, 「라이트」를 참조할것.

앰비언트 라이트는, 장면내의 어느 위치 좌표에도 이펙트를 미친다. 앰비언트 라이트는, 오브젝트나 오브젝트의 장면내의 위치 좌표에 관계없이, 장면 전체를 같은 강도의 빛으로 비추는 라이팅이라고 생각할 수가 있다. 앰비언트 라이트는 모든 위치에 존재해, 색과 강도를 가질 뿐으로, 위치 좌표나 방향은 가지지 않는다. 앰비언트 라이트 레벨을 설정하려면 ,IDirect3DDevice8::SetRenderState 메소드를 호출해,State 파라미터로서 D3DRS_AMBIENT 를 지정해,Value 파라미터로서 목적의 RGBA 색을 지정한다.

앰비언트 라이트의 색은, RGBA 값의 형태를 취해, 각 성분은 0 ~ 255 의 정수값이다. 이것은, Microsoft® Direct3D® 의 대부분의 칼라값과는 다르다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 칼라값」을 참조할것.

D3DCOLOR_RGBA 매크로를 사용해 RGBA 값을 생성할 수 있다. 적, 초록, 및 파랑 성분을 조합해, 앰비언트 라이트의 최종적인 색을 생성 한다. 알파 성분은 색의 투명도를 제어한다. 하드웨어 가속화 또는 RGB 에뮬레이션을 사용할때는, 알파 성분은 무시된다.


라이트 오브젝트

Microsoft® Direct3D® 에서는, 포인트 라이트, spotlight, 및 디레크쇼나르라이트의 3 종류의 라이트를 사용한다. 라이트 프로퍼티 세트를 생성 할 경우에, 사용하는 라이트의 종류를 선택한다. 라이트 프로퍼티와 거기에 따르는 계산 위에의 오버헤드는, 라이팅의 종류에 따라서 다르다. Direct3D 라이팅 모듈로 지원 되는, 이하의 광원에 도착해 설명한다.

  • 포인트 라이트
  • spotlight
  • 디레크쇼나르라이트

이러한 광원과 앰비언트 라이트 레벨을 혼동 하지 않는 것. 상세한 것에 대하여는, 「다이렉트 라이트와 앰비언트 라이트의 비교」, 「라이트 프로퍼티」, 및 「라이트의 사용법」을 참조할것.


포인트 라이트

포인트 라이트는, 장면내에서 색과 위치 좌표를 가지지만, 단일의 방향은 가지지 않는다. 다음의 그림에 나타내도록(듯이), 포인트 라이트는 모든 방향으로 균등하게 미츠루를 추방한다.

포인트 라이트의 예로서는 전구가 있다. 포인트 라이트는 감쇠와 범위의 영향을 받아 버텍스 마다 메쉬를 비춘다. 라이팅의 실행중, Microsoft® Direct3D® 는, 월드 공간에서의 포인트 라이트의 위치 좌표와 라이팅 하는 버텍스의 좌표를 사용해, 라이트의 방향을 나타내는 벡터와 빛이 진행된 거리를 취득한다. 버텍스 법선에 가세해, 이 벡터와 거리의 양쪽 모두를 사용해, 표면에 어느 정도 빛이 맞는지를 계산한다.


spotlight

spotlight는, 색, 위치 좌표, 및 빛을 방사할 방향을 가진다. spotlight로부터 방사되는 빛은, 밝은 내부 콘과 이것보다 큰 외부 콘으로 구성된다. 다음의 그림에 나타내도록(듯이), 빛의 강도는 2개의 콘간에 감소한다.

spotlight는, 폴 오프, 감쇠, 및 범위의 영향을 받는다. 이러한 요인은, 빛이 각 버텍스까지 진행되는 거리와 같이, 장면내의 오브젝트에의 라이팅 이펙트를 계산할 경우에 고려에 넣는다. 각 버텍스에 대한 이러한 이펙트를 계산하는 경우, Microsoft Direct3D® 의 모든 라이트중에서 컴퓨터에의 부하가 가장 큰 것은 spotlight이다.


디레크쇼나르라이트

디레크쇼나르라이트는, 색과 방향을 가져, 위치 좌표는 가지지 않는다. 이것은 평행한 빛을 방사한다. 즉, 디레크쇼나르라이트로 생성된 빛은 모두 장면내에서 같은 방향으로 나아간다. 디레크쇼나르라이트는, 태양과 같이 멀게 멀어진 광원에 비유할 수가 있다. 디레크쇼나르라이트는 감쇠와 범위의 영향을 받지 않기 때문에, Microsoft® Direct3D® 에서는 지정된 색과 방향만 고려해, 버텍스의 색을 계산한다. 라이팅 계수의 개수가 적기 때문에, 디레크쇼나르라이트는 컴퓨터에의 부하가 가장 가벼운 라이트이다.


라이트 프로퍼티

라이트 프로퍼티는, 광원의 종류와 색을 결정한다. 사용하는 라이트의 종류에 의해, 라이트는 감쇠와 범위의 프로퍼티나 spotlight 이펙트의 프로퍼티를 가질 수가 있다. 그러나, 라이트의 종류에 따라서는 사용할 수 없는 프로퍼티도 있다. Microsoft® Direct3D® 에서는,D3DLIGHT8 구조체에 모든 종류의 광원의 라이트 프로퍼티에 관한 정보를 보관 유지한다. 여기에서는, 모든 라이트 프로퍼티에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 라이트의 종류
  • 라이트의 색
  • 버텍스색
  • 라이트의 위치 좌표, 범위, 및 감쇠
  • 라이트의 방향
  • spotlight 프로퍼티

라이트 프로퍼티는, 광원이 장면내의 오브젝트를 어떻게 비출까에 영향을 준다.

상세한 것에 대하여는, 「라이트의 사용법」, 「라이트 프로퍼티의 설정」, 및 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.


라이트의 종류

라이트의 종류 프로퍼티는, 사용하는 광원의 종류를 정의한다. C++ 의 경우, 라이트의 종류는, 라이트의 D3DLIGHT8 구조체의 Type 멤버에 D3DLIGHTTYPE 열거로부터의 값을 사용해 설정한다. Microsoft® Direct3D® 에는, 포인트 라이트, spotlight, 및 디레크쇼나르라이트의 3 종류의 라이트가 있다. 라이트의 종류 마다, 장면내의 오브젝트의 비추는 방법이 달라, 계산에 있어서의 오버헤드의 레벨도 다르다. 각 라이트의 작용에 관한 일반적인 정보에 대해서는, 「라이트 오브젝트」를 참조할것.


라이트의 색

Microsoft® Direct3D® 의 라이트는, 시스템에 의한 라이팅 계산으로 독립해 사용되는, 디퓨즈색, 앰비언트색, 및 스펙큐러색의 3 개의 색을 방사한다. 각각의 색은, Direct3D 라이팅 모듈에 의해 짜넣어져 현재의 머트리얼의 색과 상호작용 해, 최종적으로 렌더링으로 사용되는 색이 생성된다. 디퓨즈색은 현재의 머트리얼의 디퓨즈 프로퍼티와 상호작용 해, 스펙큐러색은 머트리얼의 스펙큐러 속성과 상호작용 한다, 라고 하는 상태에 처리된다. Direct3D 에서의 이러한 색의 적용 방법에 대해서는, 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.

C++ 어플리케이션의 경우,D3DLIGHT8 구조체에 이러한 색을 나타내는 3 개의 멤버 Diffuse,Ambient, 및 Specular 가 포함된다. 각 멤버는, 방사하는 색을 정의하는 D3DCOLORVALUE 구조체이다.

시스템의 계산 부하가 비교적 큰 것은, 디퓨즈색이다. 가장 일반적인 디퓨즈색은 백색 (R:1. 0 G:1. 0 B:1. 0)이지만, 목적의 이펙트를 내기 위해서(때문에) 필요에 따라서 색을 생성 할 수 있다. 예를 들어, 난로에 적색의 라이트를 사용하거나"Go" 가 된 교통신호에 녹색을 사용할 수가 있다.

일반적으로는, 라이트의 색성분을 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 의 값으로 설정하지만, 이외의 값으로 설정할 수도 있다. 예를 들어, 모든 성분을 2.0 으로 설정해,"백색보다 밝은" 라이트를 생성 할 수 있다. 이러한 설정은, 정수 이외의 감쇠 설정을 사용할때에는 특히 편리하다.

Direct3D 에서는 라이트로 RGBA 값을 사용하지만, 알파 성분은 사용하지 않는다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 칼라값」을 참조할것.


버텍스색

일반적으로, 머트리얼 칼라가 라이팅에 사용된다. 그러나, 머트리얼 칼라 (에미션(emission), 앰비언트, 디퓨즈, 및 스펙큐러)를, 디퓨즈 버텍스 칼라 또는 스펙큐러 버텍스 칼라로 옮겨놓도록(듯이) 지정할 수 있다. 이 지정을 실시하려면 ,IDirect3DDevice8::SetRenderState 를 호출해, 다음 표에 나타내는 디바이스 스테이트 변수를 설정한다.

디바이스 스테이트 변수 | 의미 | 형 | 디폴트
D3DRS_AMBIENTMATERIALSOURCE | 앰비언트 머트리얼 칼라를 취득하는 장소를 정의한다. | D3DMATERIALCOLORSOURCE | D3DMCS_MATERIAL
D3DRS_DIFFUSEMATERIALSOURCE | 디퓨즈 머트리얼 칼라를 취득하는 장소를 정의한다. | D3DMATERIALCOLORSOURCE | D3DMCS_COLOR1
D3DRS_SPECULARMATERIALSOURCE | 스펙큐러 머트리얼 칼라를 취득하는 장소를 정의한다. | D3DMATERIALCOLORSOURCE | D3DMCS_COLOR2
D3DRS_EMISSIVEMATERIALSOURCE | 에미션(emission) 머트리얼 칼라를 취득하는 장소를 정의한다. | D3DMATERIALCOLORSOURCE | D3DMCS_MATERIAL
D3DRS_COLORVERTEX | 버텍스 칼라의 사용을 유효/무효로 한다. | BOOL | TRUE

알파/투명값은 항상, 디퓨즈색의 알파 채널로부터 마셔 얻을 수 있다.

fog값은 항상, 스펙큐러색의 알파 채널로부터 마셔 얻을 수 있다.

D3DMATERIALCOLORSOURCE 에는, 이하의 값을 지정할 수가 있다.

  • D3DMCS_MATERIAL – 머트리얼 칼라를 소스로서 사용
  • D3DMCS_COLOR1 - 디퓨즈 버텍스 칼라를 소스로서 사용
  • D3DMCS_COLOR2 – 스펙큐러 버텍스 칼라를 소스로서 사용


라이트의 위치 좌표, 범위, 및 감쇠

위치 좌표, 범위, 및 감쇠 프로퍼티는,월드 공간에서의 라이트의 위치 좌표, 및 라이트가 방사하는 빛이 거리의 증가에 수반해 어떻게 변화하는지를 정의한다. C++ 로 사용하는 모든 라이트 프로퍼티와 같이, 이러한 프로퍼티는 라이트의 D3DLIGHT8 구조체에 포함된다.

위치 좌표

라이트의 위치 좌표는,D3DLIGHT8 구조체의 Position 멤버에 D3DVECTOR 구조체를 사용해 지정한다. x, y, z 좌표는 월드 공간에 있으면(자) 가정한다. 디레크쇼나르라이트는, 위치 좌표 프로퍼티를 사용하지 않는 유일한 라이트이다.

범위

라이트의 범위 프로퍼티는, 오브젝트가 방사한 빛을 장면내의 메쉬가 납득할 수 없게 될 때까지의, 월드 공간에서의 거리를 결정한다. Range 멤버에는, 월드 공간에서의 라이트의 최대 범위를 나타내는 부동 소수점값이 포함된다. 디레크쇼나르라이트에서는 범위 프로퍼티는 사용하지 않는다.

감쇠

감쇠는, 범위 프로퍼티로 지정한 최대 거리에 가까워지는 것에 따라 라이트의 강도가 어떻게 감소하는지를 제어한다. 라이트의 감쇠는, 3 개의 D3DLIGHT8 구조체의Attenuation0,Attenuation1, 및 Attenuation2 멤버로 나타낸다. 이러한 멤버에는, 라이트의 감쇠를 제어하는 0.0 ~무한대의 부동 소수점값이 포함된다. 어플리케이션에 따라서는,Attenuation1 멤버를 1.0 으로 설정해, 그 외의 멤버를 0.0 으로 설정하는 것으로, 라이트의 강도가 1 / D 로서 변화하도록(듯이) 한다. 여기서,D 는 광원으로부터 버텍스까지의 거리이다. 광원에서는 라이트의 강도가 최대로, 거기로부터 멀어지는에 따라 1 / (라이트의 범위)에 감소한다. 보통, 어플리케이션에서는 Attenuation0 를 0.0 으로 설정해,Attenuation1 를 정수로 설정해,Attenuation2 를 0.0 으로 설정한다.

감쇠값을 조합해, 보다 복잡한 감쇠 이펙트를 낼 수가 있다. 또, 감쇠값을 보통의 범위외의 값으로 설정해, 한층 더 드문 감쇠 이펙트를 낼 수가 있다. 예를 들어, 부의 감쇠값을 설정 하면, 거리가 증가하는에 따라 라이트가 밝아진다.

Microsoft® Direct3D® 로 감쇠의 계산에 사용하는 수학 모델의 상세한 것에 대하여는, 「거리의 증가에 의한 라이트의 감쇠」를 참조할것. 범위 프로퍼티와 같이, 디레크쇼나르라이트에서는 감쇠 프로퍼티는 사용하지 않는다.


라이트의 방향

라이트의 방향 프로퍼티는, 오브젝트의 방사하는 빛이월드 공간내로 나아갈 방향을 결정한다. 방향은, 디레크쇼나르라이트와 spotlight에서만 사용해, 벡터로 정의한다.

C++ 어플리케이션에서는, 라이트의 D3DLIGHT8 구조체의 Direction 멤버에 라이트의 방향을 설정한다. Direction 멤버는,D3DVECTOR 형이다. 방향 벡터는, 장면내의 라이트의 위치 좌표 (와)는 관계없는 것으로, 논리 원점으로부터의 거리로서 기술한다. 따라서, 장면에 똑바로 입사 하는 (z 축의 정방향에 따라) spotlight의 방향 벡터는, 그 위치 좌표가 어디에 정의되고 있어도 <0, 0,1> 이다. 같이 장면을 바로 위로부터 비추는 태양광을 시뮬레이트 하려면 , 방향이 <0,-1, 0> 의 디레크쇼나르라이트를 사용하면 좋다. 반드시 좌표축에 따라 비추는 라이트를 생성 할 필요가 없는 것은 분명하다. 값을 조합하거나 가지런히 하거나 해, 재미있는 각도로부터 라이트를 비출 수가 있다.

주 라이트의 방향 벡터를 정규화할 필요는 없지만, 반드시 벡터의 매그니튜드를 지정하는 것. 즉, <0, 0,0> 의 방향 벡터는 사용하지 않는다.


spotlight 프로퍼티

C++ 의 D3DLIGHT8 구조체에는, spotlight에서만 사용하는 3 개의 멤버가 포함되어 있다. 이러한 멤버 (Falloff,Theta, 및 Phi)는, spotlight 오브젝트의 내부 콘과 외부 콘의 크기를 제어해, 양쪽 모두의 콘의 사이에 라이트가 어떻게 감소하는지를 제어한다. 이러한 특성의 일반적인 설명에 대해서는, 「spotlight」를 참조할것.

Theta 값은 spotlight의 내부 콘의 라디안 각도를 나타내,Phi 값은 외부 콘의 라디안 각도를 나타낸다. Falloff 값은, 내부 콘의 외측 엣지와 외부 콘의 안쪽 엣지와의 사이로, 라이트의 강도가 어떻게 감소하는지를 제어한다. 대부분의 어플리케이션에서는,Falloff 를 1.0 으로 설정해 2 개의 콘간에 폴 오프가 한결같게 생기도록(듯이) 하지만, 필요에 따라서 이외의 값을 설정할 수도 있다.

폴 오프의 계산에 대해 Microsoft® Direct3D® 가 사용하는 수학적 모델의 상세한 것에 대하여는, 「spotlight 폴 오프 모델」을 참조할것.

다음의 그림은, 멤버의 값의 사이에 있는 관계와 이러한 값이 spotlight의 내부 콘과 외부 콘에게 주는 영향을 나타내고 있다.


라이트의 사용법

여기에서는, Microsoft® Direct3D® 어플리케이션에서의 라이트의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 라이트 프로퍼티의 설정
  • 라이트의 유효/무효
  • 라이트 프로퍼티의 취득


라이트 프로퍼티의 설정

C++ 어플리케이션으로 라이트 프로퍼티를 설정하려면 ,D3DLIGHT8 구조체를 준비해, 다음에 IDirect3DDevice8::SetLight 메소드를 호출한다. SetLight 메소드는, 디바이스가 라이트 프로퍼티 세트를 디바이스 내부의 라이트 프로퍼티의 리스트에 배치할 때의 인덱스와 그 라이트 프로퍼티를 정의하는 D3DLIGHT8 구조체의 주소를 받는다. 라이트 프로퍼티의 갱신이 필요한 때는, 새로운 정보로 SetLight 를 호출할 수가 있다.

프로퍼티를 할당할 수 있지 않은 인덱스로 SetLight 메소드를 호출할 때마다, 시스템은 라이트 프로퍼티 세트를 저장하기 위한 메모리를 할당한다. 어플리케이션에서는, 할당할 수 있고 있는 라이트의 서브 세트를 한 번에 유효하게 해, 수많은 라이트를 설정할 수 있다. 디바이스가 지원 하는 액티브한 라이트의 최대수를 결정하기 위해서(때문에) 디바이스 능력을 취득 하면나무는,D3DCAPS8 구조체의 MaxActiveLights 멤버를 체크한다. 라이트를 사용할 필요가 없어졌을 경우는, 그 라이트를 무효로 하는지, 새로운 라이트 프로퍼티 세트로 덧쓰기할 수가 있다.

다음의 C++ 의 샘플 코드는, 거리의 증가에 의해 감쇠하지 않는, 백색의 포인트 라이트의 프로퍼티를 준비 및 설정한다.

/*
* 이 코드에서는, 변수 g_pd3dDev 는, IDirect3DDevice8 인터페이스에의
* 유효한 포인터이라고 가정하고 있다.
 */
D3DLIGHT8 d3dLight;
HRESULT   hr;

// 구조체를 초기화한다.
ZeroMemory(&d3dLight, sizeof(D3DLIGHT8));

// 백색의 포인트 라이트의 설정을 실시한다.
d3dLight.Type = D3DLIGHT_POINT;
d3dLight.Diffuse.r  = 1.0f;
d3dLight.Diffuse.g  = 1.0f;
d3dLight.Diffuse.b  = 1.0f;
d3dLight.Ambient.r  = 1.0f;
d3dLight.Ambient.g  = 1.0f;
d3dLight.Ambient.b  = 1.0f;
d3dLight.Specular.r = 1.0f;
d3dLight.Specular.g = 1.0f;
d3dLight.Specular.b = 1.0f;

// 포인트 라이트를 장면의 상부에서 뷰아의 배후에 배치한다.
// 이러한 좌표는 월드 공간의 것이다.
// 유저는 월드 공간내의 어느 위치 좌표라도 존재할 수 있다.
// 이 코드에서는,
// 유저는 월드 공간의 원점에 있으면(자) 가정하고 있다.
d3dLight.Position.x = 0.0f;
d3dLight.Position.y = 1000.0f;
d3dLight.Position.z = -100. 0f;

// 감쇠시키지 않다.
d3dLight.Attenuation0 = 1.0f;
d3dLight.dvRange      = 1000.0f;

// 최초의 라이트의 프로퍼티 정보를 설정한다.
hr = d3dDevice->SetLight(0, &d3dLight);
if (FAILED(hr))
{
    // 에러 처리 코드.
}

라이트 프로퍼티 세트는, 재차 SetLight 를 호출해 언제라도 갱신할 수 있다. 갱신하는 라이트 프로퍼티 세트의 인덱스와 새로운 프로퍼티를 포함한 D3DLIGHT8 구조체의 주소를 지정하는 것만으로 있다.

주 라이트 프로퍼티 세트를 디바이스에 할당해도, 추가되는 프로퍼티를 가지는 광원이 유효하게 되는 것은 아니다. 광원을 유효하게 하려면 , 디바이스에 대해서 IDirect3DDevice8::LightEnable 메소드를 호출한다.


라이트의 유효/무효

장면내의 광원의 라이트 프로퍼티 세트를 일단 할당하면(자), 디바이스에 대해서 IDirect3DDevice8::LightEnable 메소드를 호출하는 것으로, 그 광원을 액티브하게 할 수가 있다. 새롭게 할당한 광원은, 디폴트에서는 무효가 되어 있다. LightEnable 메소드는, 2 개의 파라미터를 받는다. 제 1 파라미터에는, 메소드로 처리하는 광원의 인덱스 (0 으로부터 시작된다)를 설정한다. 제 2 파라미터에는, 라이트를 유효하게 하는 경우는 TRUE, 무효로 하는 경우는 FALSE 를 설정한다.

다음의 코드는,LightEnable 메소드를 사용해, 디바이스의 광원 프로퍼티의 리스트내의 최초의 광원을 유효하게 하는 방법을 나타내고 있다.

/*
* 이 코드에서는, 변수 d3dDevice 는, IDirect3DDevice8 인터페이스에의
* 유효한 포인터이라고 가정하고 있다.
 */
HRESULT hr;

hr = pd3dDevice->LightEnable(0, TRUE);
if (FAILED(hr))
{
    // 에러 처리 코드.
}

IDirect3Ddevice8::SetLight 로 설정하는 프로퍼티가 없는 라이트를 유효 또는 무효로 하는 경우,LightEnable 메소드는 이하의 겉(표)의 프로퍼티를 가지는 광원을 생성 해, 그 광원을 유효 또는 무효로 한다.

멤버 | 디폴트
Type | D3DLIGHT_DIRECTIONAL
Diffuse | (R:1, G:1, B:1, A:0)
Specular | (R:0, G:0, B:0, A:0)
Ambient | (R:0, G:0, B:0, A:0)
Position | (0, 0, 0)
Direction | (0, 0, 1)
Range | 0
Falloff | 0
Attenuation0 | 0
Attenuation1 | 0
Attenuation2 | 0
Theta | 0
Phi | 0


라이트 프로퍼티의 취득

C++ 로, 기존의 광원의 프로퍼티를 모두 취득하려면 , 디바이스에 대해서 IDirect3DDevice8::GetLight 메소드를 호출한다. GetLight 메소드를 호출하면 와, 프로퍼티를 취득하는 광원의 0 으로부터 시작되는 인덱스를 제 1 파라미터에 건네주어,D3DLIGHT8 구조체의 주소를 제 2 파라미터에 건네준다. 디바이스는,D3DLIGHT8 구조체에 값을 설정해, 지정된 인덱스의 광원에서 그 디바이스가 사용하는 라이트 프로퍼티를 기술한다.

다음의 샘플 코드는, 이 처리를 나타내고 있다.

/*
* 이 코드에서는, 변수 pd3dDevice 는, IDirect3DDevice8 인터페이스에의
* 유효한 포인터이라고 가정하고 있다.
 */
HRESULT hr;
D3DLIGHT8 light;

// 최초의 라이트에 대한 프로퍼티 정보를 취득한다.
hr = pd3dDevice->GetLight(0, &light);
if (FAILED(hr))
{
    // 에러 처리 코드.
}

디바이스내에서 할당할 수 있고 있는 광원의 범위외의 인덱스를 지정 하면,GetLight 메소드는 실패해,D3DERR_INVALIDCALL 를 돌려준다.


머트리얼

여기에서는, 머트리얼과 Microsoft® Direct3D® 어플리케이션에서의 머트리얼의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 머트리얼이란
  • 머트리얼 프로퍼티
  • 머트리얼의 사용법

디폴트의 머트리얼 프로퍼티에 관한 주의 어플리케이션으로, 렌더링 처리에 머트리얼 프로퍼티가 지정되어 있지 않은 경우는, 디폴트의 머트리얼이 사용된다. 디폴트의 머트리얼은, 모든 디퓨즈 라이트 (백색등)를 반사하지만, 앰비언트 반사 또는 스펙큐러 반사는 생기지 않고, 에미션(emission)색이 없다.


머트리얼이란

머트리얼은, 3D 신으로 다각형이 빛을 어떻게 반사하는지, 또는 어떻게 빛을 방사하는 것처럼 보이는지를 지정한다. 본질적으로는, 머트리얼은, Microsoft® Direct3D® 가 렌더링 하는 다각형에 대해 다음의 정보를 Direct3D 에 지시하는 프로퍼티의 집합이다.

  • 다각형에 의한 앰비언트 라이트와 디퓨즈 라이트의 반사 방법
  • 다각형으로부터의 스펙큐러 하이라이트 상태
  • 다각형이 미츠를 출발하고 있도록(듯이) 보이게 할지 어떨지

C++ 로 기술된, Direct3D 어플리케이션에서는,D3DMATERIAL8 구조체를 사용해 머트리얼 프로퍼티를 정의한다. 상세한 것에 대하여는, 「머트리얼 프로퍼티」를 참조할것.


머트리얼 프로퍼티

머트리얼 프로퍼티는, 머트리얼의 디퓨즈, 앰비언트 반사, 에미션(emission), 및 스펙큐러 하이라이트 특성을 상세하게 지정한다. Microsoft® Direct3D® 은,D3DMATERIAL8 구조체에 모든 머트리얼 프로퍼티 정보를 보관 유지한다. 머트리얼 프로퍼티는, 그 머트리얼을 사용하는 다각형을 라스터화할 때 Direct3D 가 사용하는 색에 영향을 준다. 스펙큐러 속성을 제외해, 각 프로퍼티는, 머트리얼이 소정의 종류의 라이트의 적, 초록, 및 파랑 성분을 어느 정도 반사하는지를 나타내는 RGBA 색과 알파 블렌딩 계수 (RGBA 색의 알파 성분)로서 지정한다. 머트리얼의 스펙큐러 속성은, 색 및 강도로 지정한다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 칼라값」을 참조할것.

디퓨즈 반사와 앰비언트 반사

D3DMATERIAL8 형의 Diffuse 및 Ambient 멤버는, 장면내에서 머트리얼이 앰비언트 라이트와 디퓨즈 라이트를 어떻게 반사하는지를 지정한다. 대부분의 장면에서는, 앰비언트 라이트보다 디퓨즈 라이트가 훨씬 많이 사용되기 (위해)때문에, 색의 결정에 대해 디퓨즈 반사가 가장 크게 영향을 준다. 게다가 디퓨즈 라이트는 방향을 가지고 있기 (위해)때문에, 그 입사각은 반사의 전체적인 강도에 영향을 준다. 디퓨즈 반사는, 라이트가 버텍스 법선과 평행에 버텍스에 해당될 때가 가장 강하다. 입사각이 커지는 것에 따라, 디퓨즈 반사의 이펙트는 감소한다. 다음에 나타내도록(듯이), 반사광의 양은 입사빛과 버텍스 법선이 이루는 각도의 코사인이다.

앰비언트 라이트와 같이, 앰비언트 반사는 방향을 가지지 않는다. 앰비언트 반사는, 렌더링 한 오브젝트의 외관의 색에의 영향은 적지만, 전체의 색에 영향을 주어, 머트리얼로부터 반사하는 디퓨즈 라이트가 전혀 없는지, 그저 적을 때 가장 눈에 띈다. 머트리얼의 앰비언트 반사는,D3DRS_AMBIENT 플래그를 지정해 IDirect3DDevice8::SetRenderState 메소드를 호출하는 것으로 장면으로 설정한 앰비언트 라이트의 영향을 받는다.

디퓨즈 반사 및 앰비언트 반사는 ,함께 작용해 오브젝트로 지각되는 색을 결정한다. 이것들은 보통은 같은 값이다. 예를 들어, 청색의 수정 오브젝트를 렌더링 하려면 , 디퓨즈 라이트와 앰비언트 라이트의 파랑 성분만 반사하는 머트리얼을 생성 한다. 이 수정을 백색광으로 비추어진 방에 두면(자) 청색으로 보인다. 그러나, 적색빛 밖에 없는 방에서는, 같은 수정에서도 검게 보인다. 이것은, 수정의 머트리얼이 적색빛을 반사하지 않기 때문이다.

에미션(emission)

머트리얼을 사용해, 렌더링 한 오브젝트 자체가 미츠를 출발하고 있도록(듯이) 보이게 할 수가 있다. D3DMATERIAL8 구조체의 Emissive 멤버를 사용해, 에미션(emission)빛의 색 및 투명도를 지정한다. 에미션(emission)는 오브젝트의 색에 영향을 준다. 예를 들어, 어두운 머트리얼을 밝게 해, 발광색의 일부가 될 수가 있다.

머트리얼의 에미션(emission) 속성을 사용해, 오브젝트가 미츠를 출발하고 있도록(듯이) 보이게 할 수가 있다. 이 방법에서는, 장면에 라이트를 추가할 때의 오버헤드가 발생하지 않는다. 청색의 수정의 예로, 장면내외의 오브젝트에는 라이트를 비추지 않고 , 수정만이 빛나고 있도록(듯이) 보이게 하는 경우는, 에미션(emission) 속성을 사용 하면이야 있고. 에미션(emission) 속성을 가지는 머트리얼이 발하는 빛은, 장면내외의 오브젝트로 반사할 수 있는 빛은 아니기 때문에 주의 해야 한다. 이 반사광을 얻으려면 , 장면내에 추가의 라이트를 배치할 필요가 있다.

스펙큐러 반사

스펙큐러 반사는 오브젝트상에 하이라이트를 생성 해, 오브젝트가 빛나고 있도록(듯이) 보이게 한다. D3DMATERIAL8 구조체에는, 스펙큐러 하이라이트색과 머트리얼의 전체적인 빛남을 지정하는 2 개의 멤버가 포함된다. Specular 멤버를 목적의 RGBA 색 (가장 일반적인 색은 백색 또는 밝은 회색이다)으로 설정해, 스펙큐러 하이라이트의 색을 결정한다. Power 멤버로 설정하는 값은, 스펙큐러 이펙트의 샤프함을 제어한다.

스펙큐러 하이라이트를 사용 하면, 훌륭한 이펙트를 얻을 수 있다. 다시 청색의 수정을 예로서 생각한다. Power 의 값이 큰 만큼 선명한 스펙큐러 하이라이트가 되어, 수정의 빛남이 늘어난다. 이 값이 작을 정도 이펙트가 미치는 영역은 확대하지만, 반사가 둔해져 수정이 서리로 덮인 것처럼 보인다. 전혀 광택이 없는 오브젝트로 하려면 ,Power 멤버를 제로로 설정해,Specular 의 색을 흑으로 설정한다. 생각 대로의 리얼한 표시가 되도록(듯이), 다양한 반사 레벨을 시험해 본다. 다음의 그림은, 2 개(살)의 같은 모델을 나타내고 있다. 좌측의 모델에서는 스펙큐러 반사 강도를 10 으로 설정해, 우측의 모델에서는 스펙큐러 반사를 설정하고 있지 않다.


머트리얼의 사용법

여기에서는, Microsoft® Direct3D® 어플리케이션에서의 머트리얼의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 머트리얼 프로퍼티의 설정
  • 머트리얼 프로퍼티의 취득


머트리얼 프로퍼티의 설정

Microsoft® Direct3D® 렌더링 디바이스에서는, 한 번에 1 개의 머트리얼 프로퍼티세트로 렌더링 할 수 있다.

C++ 어플리케이션의 경우, 시스템으로 사용하는 머트리얼 프로퍼티를 설정하려면 ,D3DMATERIAL8 구조체를 준비해, 다음에 IDirect3DDevice8::SetMaterial 메소드를 호출한다.

D3DMATERIAL8 구조체를 준비하려면 , 이 구조체에 프로퍼티 정보를 설정해, 렌더링에서의 목적의 이펙트를 생성 한다. 다음의 코드는, 샤프한 백색의 스펙큐러 하이라이트가 있는, 보라색의 머트리얼용의 D3DMATERIAL8 구조체를 설정한다.

D3DMATERIAL8 mat;

// 디퓨즈 반사를 나타내는 RGBA 를 설정한다.
mat.Diffuse.r = 0.5f;
mat.Diffuse.g = 0.0f;
mat.Diffuse.b = 0.5f;
mat.Diffuse.a = 1.0f;

// 앰비언트 반사를 나타내는 RGBA 를 설정한다.
mat.Ambient.r = 0.5f;
mat.Ambient.g = 0.0f;
mat.Ambient.b = 0.5f;
mat.Ambient.a = 1.0f;

// 스펙큐러 하이라이트의 색과 샤프함을 설정한다.
mat.Specular.r = 1.0f;
mat.Specular.g = 1.0f;
mat.Specular.b = 1.0f;
mat.Specular.a = 1.0f;
mat.Power = 50.0f;

// RGBA 에미션(emission)색을 설정한다.
mat.Emissive.r = 0.0f;
mat.Emissive.g = 0.0f;
mat.Emissive.b = 0.0f;
mat.Emissive.a = 0.0f;

D3DMATERIAL8 구조체를 준비하면(자), 렌더링 디바이스의 IDirect3DDevice8::SetMaterial 메소드를 호출해 이 프로퍼티를 적용한다. 이 메소드에는, 준비한 D3DMATERIAL8 구조체의 주소를 유일한 파라미터로서 지정한다. 디바이스의 머트리얼 프로퍼티의 갱신이 필요한 때는, 새로운 정보로 SetMaterial 를 호출할 수가 있다. 이상의 처리를 다음의 샘플 코드에 나타낸다.

// 이 코드에서는, 이 주제의 전의 예로 변수 mat 에 대해서 정의했다
// 머트리얼 프로퍼티를 사용한다. pd3dDev 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정한다.
HRESULT hr;
hr = pd3dDev->SetMaterial(&mat);
if(FAILED(hr))
{
    // 에러 처리 코드.
}

Direct3D 디바이스를 생성 하는 경우는, 이하의 겉(표)에 나타내도록(듯이) 현재의 머트리얼은 자동적으로 디폴트로 설정된다.

멤버 | 값
Diffuse | (R:1, G:1, B:1, A:0)
Specular | (R:0, G:0, B:0, A:0)
Ambient | (R:0, G:0, B:0, A:0)
Emissive | (R:0, G:0, B:0, A:0)
Power | (0.0)


머트리얼 프로퍼티의 취득

디바이스에 대해서 IDirect3DDevice8::GetMaterial 메소드를 호출해, 렌더링 디바이스로 현재 사용하고 있는 머트리얼 프로퍼티를 취득한다. IDirect3DDevice8::SetMaterial 메소드의 경우와는 달라,GetMaterial 에서는 준비는 필요없다. GetMaterial 메소드에는,D3DMATERIAL8 구조체의 주소를 지정한다. 이 메소드는, 종료전에 이 구조체에 현재의 머트리얼 프로퍼티의 정보를 기입한다.

// 이 코드에서는, 변수 pd3dDev 는 IDerect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정한다.
HRESULT hr;
D3DMATERIAL8 mat;

hr = pd3dDev->GetMaterial(&mat);
if(FAILED(hr))
{
    // 에러 처리 코드.
}


버텍스 포맷

여기에서는, Microsoft® Direct3D® 로 버텍스를 지정하기 위해서 이해해 둘 필요가 있는 개념에 대해 설명해, 버텍스를 선언하기 위해서 어플리케이션으로 사용할 수 있는 각종 포맷의 정보에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 버텍스 포맷에 대해
  • 트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스
  • 트랜스폼 되지 않은 라이팅 끝난 버텍스
  • 트랜스 폼이 끝난 라이팅 끝난 버텍스
  • 트랜스 폼이 끝난 라이팅 끝난 버텍스의 기능
  • 유연한 버텍스 포맷과 버텍스 쉐이더


버텍스 포맷에 대해

유연한 버텍스 포맷 (FVF)의 코드는, 인터리브 되어 저장 되는 버텍스의 내용을 단일 데이터 스트림에 기술한다. 일반적으로, 고정 기능 버텍스 처리 파이프라인으로 처리되는 데이터를 지정한다.

Microsoft® Direct3D® 어플리케이션에서는, 복수의 방법으로 모델의 버텍스를 정의할 수 있다. 유연한 버텍스 정의 ("유연한 버텍스 포맷" 또는 "유연한 버텍스 포맷 코드" 라고도 부른다)가 지원 되고 있는 것으로부터, 필요한 버텍스의 성분만 어플리케이션으로 사용해, 사용하지 않는 버텍스의 성분은 삭제할 수 있다. 필요한 버텍스의 성분만 사용할 수 있으므로, 어플리케이션으로 메모리를 절약할 수 있어 모델의 렌더링에 필요한 처리 대역폭을 최소한으로 억제할 수가 있다. 유연한 버텍스 포맷 플래그를 조합해 사용해, 버텍스의 포맷 방법을 지정한다.

FVF 사양에는 포인트 사이즈의 포맷도 포함되어 D3DFVF_PSIZE 에 의해 지정한다. 이 사이즈는, 비 TL 버텍스에 대해서는 카메라 공간 단위로, TL 버텍스에 대해서는 디바이스 공간 단위로 나타내진다.

C++ 어플리케이션에서는,IDirect3DDevice8 인터페이스의 렌더링 메소드에 의해, 이러한 플래그의 편성을 받는 메소드를 사용할 수 있어 그 편성을 사용해 프리미티브의 렌더링 방법을 결정한다. 기본적으로는, 이러한 플래그는, 어플리케이션으로 어느 버텍스의 성분 (위치 좌표, 버텍스 블렌딩 웨이트, 법선, 색, 및 텍스쳐 좌표의 수와 포맷)을 사용할까를 시스템에 알려 또, Direct3D 로 렌더링 파이프라인의 어느 부분을 버텍스의 성분에 적용할까를 간접적으로 알린다. 게다가 특정의 버텍스 포맷 플래그의 유무에 의해, 메모리에 존재하는 버텍스의 성분 필드와 생략 한 버텍스의 성분을 시스템에 알린다.

디바이스의 제한을 조사하려면 , D3DFVFCAPS_DONOTSTRIPELEMENTS 및 D3DFVFCAPS_TEXCOORDCOUNTMASK 유연한 버텍스 포맷 플래그에 대해 디바이스를 문의한다. 상세한 것에 대하여는,D3DCAPS8 구조체의 「FVFCaps 멤버」를 참조할것.

버텍스의 포맷 방법에 관한 시스템 조건 중(안)에서 중요한 것은, 데이터의 표시 순서이다. 다음의 그림은, 메모리내의 모든 버텍스의 성분의 순서와 거기에 관계하는 데이터형을 나타내고 있다.

주 텍스쳐 좌표는 다양한 포맷으로 선언할 수 있어 최소 1 요소의 좌표, 최대 4 요소의 텍스쳐 좌표 (2D 투영 텍스쳐 좌표의 경우)를 사용해 텍스쳐를 처리할 수 있다. 상세한 것에 대하여는, 「텍스쳐 좌표 포맷」을 참조할것. 매크로의 D3DFVF_TEXCOORDSIZEn 세트를 사용해, 버텍스 포맷으로 사용하는 텍스쳐 좌표 포맷을 식별하기 위한 비트 패턴을 생성 한다.

어플리케이션이 모든 컴퍼넌트를 사용 하면은 한정되지 않는다. 동차 W 의 역수 (RHW)와 버텍스 법선 필드는 서로 배타적이다. 또, 대부분의 어플리케이션으로 8 개의 텍스쳐 좌표 세트를 모두 사용 하면도 한정되지 않는다. 그러나, Direct3D 에는 이러한 유연성이 있다. 어느 플래그를 다른 플래그와 병용 하는 경우에는, 몇개의 제한이 있다. 예를 들어, D3DFVF_XYZ 플래그와 D3DFVF_XYZRHW 플래그는 병용 할 수 없다. 이 경우, 트랜스폼 되지 않은의 버텍스와 트랜스 폼 끝난 버텍스의 양쪽 모두를 사용해, 1 개의 버텍스의 위치 좌표를 정의하게 되기 때문이다.

인덱스 버텍스 블렌딩을 사용하려면 , D3DFVF_LASTBETA_UBYTE4 플래그는 FVF 의 마지막에 둘 필요가 있다. 이 플래그를 지정 하면, 5 번째의 블렌딩 웨이트는, 플로트는 아니고 DWORD 로서 처리된다. 상세한 것에 대하여는, 「인덱스 첨부 버텍스 블렌딩」을 참조할것.

다음의 코드는, D3DFVF_LASTBETA_UBYTE4 플래그를 사용하는 FVF 코드와 이 플래그를 사용하지 않는 FVF 코드와의 차이를 나타내고 있다. 다음에 정의하는 FVF 는, D3DFVF_LASTBETA_UBYTE4 플래그를 사용하고 있지 않다. 4 개의 블렌딩 인덱스를 사용하는 경우는, 플래그 D3DFVF_XYZ3 가 존재한다. 이것은, 4 번째의 블렌딩 인덱스에 대해서, 항상 (1 - 최초의 3 개의 합계)을 사용하기 때문이다.

#define D3DFVF_BLENDVERTEX (D3DFVF_XYZB3|D3DFVF_NORMAL|D3DFVF_TEX1)

struct BLENDVERTEX
{
    D3DXVECTOR3 v;       // 버텍스 쉐이더로 v0 로서 참조된다.
    FLOAT       blend1;  // 버텍스 쉐이더로 v1.x 로서 참조된다.
    FLOAT       blend2;  // 버텍스 쉐이더로 v1.y 로서 참조된다.
    FLOAT       blend3;  // 버텍스 쉐이더로 v1.z 로서 참조된다.
                         // v1.w = 1.0 - (v1.x + v1.y + v1.z)
    D3DXVECTOR3 n;       // 버텍스 쉐이더로 v3 로서 참조된다.
    FLOAT       tu, tv;  // 버텍스 쉐이더로 v7 로서 참조된다.
};

다음에 정의하는 FVF 는, D3DFVF_LAST_UBYTE4 플래그를 사용하고 있다.

#define D3DFVF_BLENDVERTEX (D3DFVF_XYZB4 | D3DFVF_LASTBETA_UBYTE4 |D3DFVF_NORMAL|D3DFVF_TEX1)

struct BLENDVERTEX
{
    D3DXVECTOR3 v;       // 버텍스 쉐이더로 v0 로서 참조된다.
    FLOAT       blend1;  // 버텍스 쉐이더로 v1.x 로서 참조된다.
    FLOAT       blend2;  // 버텍스 쉐이더로 v1.y 로서 참조된다.
    FLOAT       blend3;  // 버텍스 쉐이더로 v1.z 로서 참조된다.
                         // v1.w = 1.0 - (v1.x + v1.y + v1.z)
    DWORD       indices; // 버텍스 쉐이더로 v2.xyzw 로서 참조된다.
    D3DXVECTOR3 n;       // 버텍스 쉐이더로 v3 로서 참조된다.
    FLOAT       tu, tv;  // 버텍스 쉐이더로 v7 로서 참조된다.
};

상세한 것에 대하여는, 「유연한 버텍스 포맷 플래그」를 참조할것.


트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스

렌더링 메소드에 건네주는 버텍스 기술에 D3DFVF_XYZ 또는 D3DFVF_XYZBn 플래그의 몇개인가, 및 D3DFVF_NORMAL 플래그가 있는 경우는, 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」타입으로서 식별된다. 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」를 사용 하면, 어플리케이션은 Microsoft® Direct3D® 에 그 내부 알고리즘을 사용해 모든 트랜스 폼 & 라이팅 처리를 실행하도록(듯이) 효율적으로 요구할 수 있는D3DRS_LIGHTING 렌더링 스테이트를 FALSE 로 설정해, 렌더링 하는 프리미티브에 대해서 Direct3D 라이팅 엔진을 무효로 할 수 있다.

이 버텍스 타입은, 어플리케이션으로 독자적인 트랜스 폼 & 라이팅 엔진을 이행 할 필요가 없기 때문에, 대부분의 어플리케이션으로 사용된다. 다만, 시스템에 의해 자동적으로 계산이 실행되기 (위해)때문에, 각 버텍스에 대해서 얼마인가의 정보를 지정해 둘 필요가 있다.

  • 트랜스폼 되지 않은의모델 좌표에 버텍스를 지정하는 것이 요구된다. 다음에, 시스템은, 월드 트랜스 폼, 뷰 트랜스 폼, 및 투영 트랜스 폼을 모델 좌표에 적용해 장면내에 버텍스를 배치해, 버텍스의 화면상에서의 최종 위치 좌표를 결정한다.
  • 보다 리얼한 라이팅 이펙트를 내기 위해서(때문에), 버텍스 법선을 포함할 수가 있다. 버텍스 법선을 포함하지 않은 버텍스를 라이팅으로 비추는 경우, 그 버텍스는 0 의 내적을 사용한다. 즉, 이러한 버텍스는 입사빛을 받지 않는 것으로서 처리된다. 시스템은, 경향 머트리얼에 가세해, 버텍스 법선을 사용해 라이팅 계산을 실행한다. 상세한 것에 대하여는, 「면법선 벡터와 버텍스 법선 벡터」, 「라이트」, 「머트리얼」, 및 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.

이러한 조건 이외에서는, 그 외의 버텍스의 성분을 유연하게 사용 또는 무시할 수 있다. 예를 들어, 디퓨즈색 또는 스펙큐러색을 트랜스폼 되지 않은의 버텍스에 포함할 수가 있다. 이것은 Microsoft DirectX® 6.0 이전으로는 할 수 없었다. 각 버텍스에 개개의 색을 포함하면(자), 머트리얼 칼라만 사용한 라이팅 계산을 실행하는 것보다도, 섬세하고 유연한 쉐이딩 이펙트를 얻을 수 있다. 다만 이 경우,D3DRS_COLORVERTEX 렌더링 스테이트를 사용해 개개의 버텍스 단위의 칼라를 유효하게 할 필요가 있다. 또, 트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스에는, 최대 8 개(살)까지 텍스쳐 좌표 세트를 포함할 수가 있다.

독자적인 버텍스 포맷을 정의 하면나무는, 어느 버텍스의 성분이 어플리케이션으로 필요한가에 주의해, 반드시 올바르고 순서 붙인 구조체를 선언해, 필요한 순서로 버텍스의 성분이 표시되도록(듯이) 해야 한다. 다음의 샘플 코드는, 위치 좌표, 버텍스 법선, 디퓨즈색, 및 2 개의 텍스쳐 좌표 세트를 포함한 유효한 버텍스 포맷 구조체를 선언한다.

//
// 이 버텍스의 버텍스 포맷 기술은,
// (D3DFVF_XYZ | D3DFVF_NORMAL |  D3DFVF_DIFFUSE | D3DFVF_TEX2)(이)가 된다.
//
typedef struct _UNLITVERTEX
{
    float x, y, z;     // 위치 좌표
    float nx, ny, nz;  // 법선
    DWORD Diffuse;     // 디퓨즈색
    float tu1, tv1;    // 텍스쳐 좌표
    float tu2, tv2;
  tv2;
} UNLITVERTEX, *LPUNLITVERTEX;

이 구조체의 버텍스 기술은, 유연한 버텍스 포맷 플래그 D3DFVF_XYZ, D3DFVF_NORMAL, D3DFVF_DIFFUSE, 및 D3DFVF_TEX2 의 편성이 된다.

상세한 것에 대하여는, 「버텍스 포맷에 대하며」를 참조할것.


트랜스폼 되지 않은 라이팅 끝난 버텍스

Microsoft® Direct3D® 렌더링 메소드로 사용하는 버텍스 포맷 기술에 D3DFVF_XYZ 플래그를 포함해 D3DFVF_NORMAL 플래그를 포함하지 않은 경우, 그 버텍스는 「트랜스폼 되지 않은 라이팅 끝난 버텍스」로서 식별된다. 플래그의 의존 및 배타 관계의 상세한 것에 대하여는, 「유연한 버텍스 포맷 플래그」를 참조할것.

「트랜스폼 되지 않은 라이팅 끝난 버텍스」를 사용 하면, 어플리케이션은 Direct3D 에 버텍스에 대한 라이팅 계산을 실행하지 않게 요구하지만, Direct3D 는 이전으로 설정된 월드 행렬, 뷰 행렬, 및 투영 행렬을 사용해 버텍스를 트랜스 폼 한다. 라이팅 계산은 실행되지 않기 때문에, 버텍스 법선은 필요없다. 시스템은, 각 버텍스의 디퓨즈 성분과 스펙큐러 성분을 쉐이딩에 사용한다. 이러한 색은 임의로 지정해도, 독자적인 라이팅 공식을 사용해 계산해도 괜찮다. 디퓨즈 성분 또는 스펙큐러 성분을 포함하지 않는 경우는, 디폴트 칼라가 사용된다. 디퓨즈색의 디폴트값은 0xFFFFFFFF 로, 스펙큐러색의 디폴트값은 0x0 이다.

위치 좌표 물어 창고인가의 색정보를 포함한다고 하는 점을 제외해서는, 그 외의 버텍스 타입과 같이, 라이팅 계산 되지 않은의 버텍스 포맷에 텍스쳐 좌표 세트를 포함하거나 무시할 수가 있다.

독자적인 버텍스 포맷을 정의 하면나무는, 어느 버텍스의 성분이 어플리케이션으로 필요한가에 주의해, 반드시 올바르고 순서 붙인 구조체를 선언해, 필요한 순서로 버텍스의 성분이 표시되도록(듯이) 해야 한다. 다음의 샘플 코드는, 디퓨즈 버텍스 칼라, 스펙큐러 버텍스 칼라, 및 3 개의 텍스쳐 좌표 세트를 가지는, 트랜스폼 되지 않은으로 라이팅 끝난 유효한 버텍스를 선언한다.

//
// 이 버텍스의 버텍스 포맷 기술은,
// (D3DFVF_XYZ | D3DFVF_DIFFUSE |  D3DFVF_SPECULAR | D3DFVF_TEX3)(이)가 된다.
//
typedef struct _LITVERTEX {
    float x, y, z;   // 위치 좌표
    DWORD Diffuse;   // 디퓨즈색
    DWORD Specular;  // 스펙큐러색
    float tu1, tv1;  // 텍스쳐 좌표
    float tu2, tv2;
    float tu3, tv3;
} LITVERTEX, *LPLITVERTEX;

이 구조체의 버텍스 기술은, 유연한 버텍스 포맷 플래그 D3DFVF_XYZ, D3DFVF_DIFFUSE, D3DFVF_SPECULAR, 및 D3DFVF_TEX3 의 편성이 된다.

상세한 것에 대하여는, 「버텍스 포맷에 대하며」를 참조할것.


트랜스 폼이 끝난 라이팅 끝난 버텍스

버텍스 포맷 기술에 D3DFVF_XYZRHW 플래그를 포함했을 경우, 어플리케이션으로 「트랜스 폼이 끝난 라이팅 끝난 버텍스」를 사용하는 것이 시스템에 통지된다. 이것은, Microsoft® Direct3D® 로 월드 행렬, 뷰 행렬, 또는 투영 행렬을 사용해 버텍스를 트랜스 폼 하지 않고, 라이팅 계산도 실행하지 않는 것을 의미하고 있다. 즉, Direct3D 는, 어플리케이션으로 이러한 처리가 실행이 끝난 상태이다고 보고 있다. 이것에 의해, 기존의 3D 어플리케이션을 Direct3D 에 이식 하면 와, 트랜스 폼이 끝난 라이팅 끝난 버텍스가 그대로 사용할 수 있다. 요컨데, Direct3D 는, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」를 전혀 변경하지 않는다. 드라이버에 직접 건네주어 라스터화를 실행한다.

트랜스폼 되지 않은의 버텍스와 라이팅에 관련지을 수 있고 있는 버텍스 포맷 플래그 (D3DFVF_XYZ 와 D3DFVF_NORMAL)는, D3DFVF_XYZRHW 가 있는 경우는 사용할 수 없다. 플래그의 의존 및 배타 관계의 상세한 것에 대하여는, 「유연한 버텍스 포맷 플래그」를 참조할것.

버텍스 위치 좌표를 지정 하면나무는, 트랜스 폼 끝난 것을 지정해야 한다. x 와 y 의 값은 화면 좌표내에 존재하고 있을 필요가 있어, z 는 Z 버퍼로 사용되는 픽셀의 깊이값이 아니면 안된다. z 값은 0.0 ~ 1.0 의 값이다. 0.0 은 유저에게 가장 가까운 위치 좌표로, 1.0 은 가시 영역내의 가장 먼 위치 좌표이다. 「트랜스 폼이 끝난 라이팅 끝난 버텍스」는, 위치 좌표의 바로 후에 RHW 값 (동차 W 의 역수)을 포함하지 않으면 안 된다. RHW 는,투영 공간내에서 버텍스가 존재하는 동차 포인트 (x, y, z, w)로부터의 W 좌표의 역수이다. 이 값은, z 축으로 따른, 시점으로부터 버텍스까지의 거리가 되는 것이 많다.

위치 좌표와 RHW 의 조건을 제외하면, 이 버텍스 포맷은, 「트랜스폼 되지 않은 라이팅 끝난 버텍스」와 같다. 지금까지의 설명을 이하에 정리한다.

  • 이 포맷의 경우, 라이팅 계산은 실행되지 않기 때문에, 버텍스 법선은 필요없다.
  • 디퓨즈색 또는 스펙큐러색을 지정할 수 있다. 이것을 지정하지 않는 경우는, 0x0 가 스펙큐러색에, 0xFFFFFFFF 가 디퓨즈색에 사용된다.
  • 텍스쳐 좌표 세트는, 최대 8 개(살)까지 사용할 수 있다. 또, 사용 하지 않아도 되다.

독자적인 버텍스 포맷을 정의 하면나무는, 어느 버텍스의 성분이 어플리케이션으로 필요한가에 주의해, 반드시 올바르고 순서 붙인 구조체를 선언해, 필요한 순서로 버텍스의 성분이 표시되도록(듯이) 해야 한다. 다음의 샘플 코드는, 디퓨즈 버텍스 칼라, 스펙큐러 버텍스 칼라, 및 텍스쳐 좌표 세트를 1 개만 가지는, 트랜스 폼이 끝난 상태로 라이팅이 있는 유효한 버텍스를 선언한다.

//
// 이 버텍스의 버텍스 포맷 기술은,
// (D3DFVF_XYZRHW | D3DFVF_DIFFUSE |  D3DFVF_SPECULAR | D3DFVF_TEX1)(이)가 된다.
//
typedef struct _TRANSLITVERTEX {
    float x, y;      // 화면 좌표
    float z;         // Z 버퍼 깊이
    float rhw;       // 동차 W 의 역수
    DWORD Diffuse;   // 디퓨즈색
    DWORD Specular;  // 스펙큐러색
    float tu1, tv1;  // 텍스쳐 좌표
} TRANSLITVERTEX, *LPTRANSLITVERTEX;

이 구조체의 버텍스 기술은, 유연한 버텍스 포맷 플래그 D3DFVF_XYZRHW, D3DFVF_DIFFUSE, D3DFVF_SPECULAR, 및 D3DFVF_TEX1 의 편성이 된다.

상세한 것에 대하여는, 「버텍스 포맷에 대하며」를 참조할것.


트랜스 폼이 끝난 라이팅 끝난 버텍스의 기능

유연한 버텍스 포맷 (FVF) 코드로 지정된 버텍스 데이터는, 트랜스 폼 끝나 또는 트랜스폼 되지 않은의 몇개의 프로퍼티를 가진다. FVF 지정의 트랜스 폼이 끝난 버텍스는, TL (transformed and lit) 버텍스로 불린다. Microsoft® Direct3D® for Microsoft DirectX® 8.0 에서는, 전릴리스와 같이, TL 버텍스 데이터가 지원 되고 있다. 그러나, TL 버텍스는, 트랜스폼 되지 않은의 버텍스에는 적용되지 않는 몇개의 조건에 영향을 받는다.

TL 버텍스 데이터는, FVF 코드로 지정된 버텍스 에 대해서만 유효하고, 프로그램 가능한 버텍스 쉐이더의 입력으로서는 사용할 수 없다. 프로그램 가능한 버텍스 쉐이더는, 각종 폼의 트랜스 폼이 끝난 버텍스 데이터를 사용할 수 있는 유연성이 있지만, 변환은 쉐이더의 일부에서 만나며 버텍스 데이터의 프로퍼티는 아니기 때문에, FVF 의 TL 버텍스 데이터와는 다르다. TL 버텍스 데이터는, FVF 코드에 의해 정의되고 있기 (위해)때문에, 계승적으로 단일 스트림이기도 하다.

TL 버텍스 데이터가 Direct3D 로 클리핑 될지 어떨지는 보증이 없기 때문에, TL 버텍스 프리미티브를 Direct3D 에 보내 렌더링 하려면 , 사전에 클리핑 할 필요가 있다. x 값과 y 값은, 뷰 포토에 대해서, 또는 디바이스 가이드 밴드가 있으면 그에 대해, 클리핑 할 필요가 있다. TL 버텍스의 z 값은, 0 으로 1 의 사이가 아니면 안된다 (0 으로 1 을 포함한다). 또 RHW 값은,[0 < 1/D3DCAPS8.MaxVertexW] 의 범위내가 아니면 안된다. RHW 요건은, w 값이 하드웨어 라스터화 디바이스의 지원 범위내에 들어가도록(듯이) 하는 것이다. 버텍스의 w 및 RHW 범위가 퍼스펙티브 투영 트랜스 폼의 결과인 경우, 투영 행렬의 모든 값에 스케일을 적용해 수정할 수 있다.

주 D3DPMISCCAPS_CLIPTLVERTS 가 설정되어 있는 경우, 디바이스는 트랜스 폼 후의 버텍스 데이터를 z 및 (x, y) 뷰 포토의 한계에 대해서 클리핑 한다. 유저 정의의 클립면에 대한 클리핑은, 트랜스 폼 후의 버텍스 데이터에 대해서는 지원되어 있지 않다. D3DPMISCCAPS_CLIPTLVERTS 능력이 설정되어 있지 않은 경우, 어플리케이션이 이러한 프리미티브를 z 경계와 적어도 x 와 y 의 가이드 밴드의 범위에 대해서 클리핑 할 필요가 있다. 한편, 트랜스 폼전의 버텍스에 대한 클리핑은, 계속해 다른 드로잉(Drawing) 호출을 하는 것 같은, 전송처 버텍스 버퍼에 대한 드로잉(Drawing) 호출과 버텍스 처리 호출의 양쪽 모두로 충분히 지원 되고 있다. 이 지원에는, z 와 (x, y) 뷰 포토 한계에 가세해 유저 정의의 클립면도 포함된다.

TL 버텍스 데이터는, 항상, 드라이버에 직접 건네받아 렌더링 된다. TL 버텍스 데이터를 가지는 버텍스 버퍼를 사용 하면, 드라이버가 이러한 버텍스 버퍼를 AGP 또는 비디오 메모리에 할당하는 처리 속도가 꽤 향상한다. TL 버텍스 버퍼의 할당은, 비 TL 버텍스 데이터 (FVF 또는 비 FVF 의 어느쪽이든)가 드라이버에 의해 할당할 수 없는 경우에서도, 드라이버에 의해 할당할 수가 있다. 이것은, 트랜스 폼 및 라이팅을 지원 하지 않는 하드웨어 디바이스상에서 동작하는 경우와 같다.

상세한 것에 대하여는, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」를 참조할것.


유연한 버텍스 포맷과 버텍스 쉐이더

Microsoft® Direct3D® for Microsoft DirectX® 8.0 은, 단일 입력 스트림의 고정 기능 버텍스 처리 파이프라인을 사용하기 위한 프로그래밍 모델을 간소화해, 지금까지의 DirectX 릴리스와 같은 기능을 제공한다. 이 경우, 버텍스 쉐이더는, 현재의 버텍스 쉐이더를 설정할 경우에 버텍스 쉐이더 핸들의 대신으로서 건네받은 유연한 버텍스 포맷 (FVF) 코드로부터 완성된다. 버텍스 쉐이더의 핸들 공간은 런 타임 라이브러리에 의해 관리되어 이 용도를 위해서(때문에), 유효한 FVF 코드의 핸들이 예약되고 있다.

FVF 코드를 현재의 버텍스 쉐이더로서 설정 하면, 버텍스 처리는 스트림 제로로부터 마셔 로드 되어 버텍스 요소는 FVF 코드의 정의에 따라 변환된다.

다음의 샘플 코드는, C++ 어플리케이션에 있어서의 FVF 코드의 버텍스 쉐이더로서의 사용 방법을 나타내고 있다.

우선 최초로, 커스텀 버텍스 타입의 구조체를 정의해, 버텍스를 초기화한다. 이 예에서는, 삼각형을 렌더링 하기 위한(해), 3 개의 버텍스가 초기화된다.

// 이 샘플 코드로, d3dDevice 는,
// IDirect3DDevice8 인터페이스에의 유효한 포인터이다고 한다.

struct CUSTOMVERTEX
{
    FLOAT x, y, z, rhw; // 버텍스의 트랜스 폼 후의 위치 좌표.
    DWORD color;        // 버텍스 칼라.
};

#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZRHW|D3DFVF_DIFFUSE)

CUSTOMVERTEX g_Vertices[] =
{
    { 150.0f,  50.0f, 0.5f, 1.0f, 0xffff0000, }, // x, y, z, rhw, color
    { 250.0f, 250.0f, 0.5f, 1.0f, 0xff00ff00, },
    {  50.0f, 250.0f, 0.5f, 1.0f, 0xff00ffff, },
};

다음에, 스트림 제로를 사용해 프리미티브를 렌더링 한다.

d3dDevice->SetStreamSource( 0, g_pVB, sizeof(CUSTOMVERTEX) );
d3dDevice->SetVertexShader( D3DFVF_CUSTOMVERTEX );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, 1 );

상세한 것에 대하여는, 「버텍스 쉐이더」를 참조할것.


텍스쳐

텍스쳐는, 컴퓨터로 리얼한 3D 화면을 생성하기 위한 강력한 툴이다. Microsoft® Direct3D® 에서는, 다채로운 텍스쳐 기능을 지원 하고 있어, 고도의 텍스쳐 기술을 간단하게 이용할 수 있다. 여기에서는, Direct3D 에서의 텍스쳐의 용도와 그 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 기본적인 텍스쳐 처리의 개념
  • 텍스쳐 좌표
  • 텍스쳐 리소스
  • 텍스쳐 필터 링
  • 텍스쳐 랩핑
  • 텍스쳐 블렌딩
  • 압축한 텍스쳐 리소스
  • 볼륨 텍스쳐 리소스
  • 자동 텍스쳐 관리
  • 텍스쳐 처리에 있어서의 하드웨어에 의한 제약


기본적인 텍스쳐 처리의 개념

여기에서는, Microsoft® Direct3D® 에서의 텍스쳐 처리의 이해에 필요한 가장 기본적인 개념에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 텍스쳐란
  • 텍스쳐 addressing mode
  • 텍스쳐의 더티 영역
  • 텍스쳐 팔레트


텍스쳐란

지금까지는 컴퓨터로 생성하는 3D 화면은, 당시로서는 일반적으로 고도의 것이었지만, 플라스틱이 빛나 있는 것처럼 보이는 경향이 있었다. 당시의 3D 화면에는, 상처, 금, 지문, 더러움등을 3D 오브젝트로 리얼하게 표현할 방법이 없었다. 근년, 개발자의 사이에서는, 컴퓨터로 보다 리얼한 3D 화면을 생성하기 위한 툴로서 텍스쳐가 넓게 사용되게 되어 있다.

텍스쳐라고 하는 용어는, 보통, 오브젝트의 매끄러움이나 엉성함을 말한다. 그러나, 컴퓨터 그래픽스 분야에 있어서의 텍스쳐란, 오브젝트를 텍스쳐와 같이 보이는 픽셀 칼라의 비트 맵이다.

Microsoft® Direct3D® 의 텍스쳐는 비트 맵이기 (위해)때문에, 비트 맵조차 있으면 Direct3D 원시적으로 적용할 수 있다. 예를 들어, 어플리케이션에서는, 나뭇결 모양으로 보이는 오브젝트를 생성 해 조작할 수가 있다. 언덕을 형성하는 3D 프리미티브 세트에, 잔디, 흙, 바위를 적용할 수 있다. 그 결과, 진짜와 같은 언덕의 경사면이 완성된다. 텍스쳐 처리에서는, 또, 도로겨드랑이의 표지, 벼랑의 암층등의 이펙트를 생성 하거나 대리석의 마루를 생성 할 수도 있다.

게다가 Direct3D 는, 텍스쳐 블렌딩 (투명도 있어/없음)이나 라이트 매핑 등, 보다 고도의 텍스쳐 기법도 지원 하고 있다. 상세한 것에 대하여는, 「텍스쳐 블렌딩」 및 「텍스쳐에 의한 라이트 매핑」을 참조할것.

어플리케이션으로, 하드웨어 추상 계층 (HAL) 디바이스, 또는 소프트웨어 디바이스 ( 「디바이스의 종류」를 참조할것)를 생성 하는 경우는,8 비트, 16 비트, 24 비트, 또는 32 비트의 텍스쳐를 사용할 수 있다.


텍스쳐 addressing mode

여기에서는, Microsoft® Direct3D® 텍스쳐 addressing mode의 용도 및 그 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 텍스쳐 addressing mode란
  • 랩 텍스쳐 addressing mode
  • 밀러 텍스쳐 addressing mode
  • 클램프 텍스쳐 addressing mode
  • 경계색텍스쳐 addressing mode
  • 텍스쳐 addressing mode의 설정과 취득
  • 텍스쳐 addressing mode와 텍스쳐 랩핑
  • 텍스쳐 애드레싱에 있어서의 디바이스 제한


텍스쳐 addressing mode란

Microsoft® Direct3D® 어플리케이션에서는, 어느 프리미티브의 어느 버텍스에도 텍스쳐 좌표를 할당할 수가 있다. 상세한 것에 대하여는, 「텍스쳐 좌표」를 참조할것. 보통, 버텍스에 할당하는 텍스쳐 좌표 u 및 v 의 범위는, 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 이다. 그러나, 이 범위외의 텍스쳐 좌표를 할당해, 특수한 텍스쳐 이펙트를 생성 할 수도 있다.

텍스쳐 addressing mode를 설정하는 것으로,[0.0, 1.0] 의 범위외의 텍스쳐 좌표로 Direct3D 가 실시하는 처리를 제어할 수 있다. 예를 들어, 어플리케이션으로 텍스쳐 addressing mode를 설정해, 프리미티브 전체에 텍스쳐를 타일과 같이 칠 수가 있다. 다음의 주제로 한층 더 자세하게 설명한다.

  • 랩 텍스쳐 addressing mode
  • 밀러 텍스쳐 addressing mode
  • 클램프 텍스쳐 addressing mode
  • 경계색텍스쳐 addressing mode


랩 텍스쳐 addressing mode

D3DTEXTUREADDRESS 열거형의 D3DTADDRESS_WRAP 멤버로 지정하는 랩 텍스쳐 addressing mode에서는, Microsoft® Direct3D® 는 모든 정수 접합으로 텍스쳐를 반복해 적용한다. 예를 들어, 어플리케이션으로 정방형 프리미티브를 생성 해, 텍스쳐 좌표 (0.0, 0.0), (0.0, 3.0), (3.0, 3.0), 및 (3.0, 0.0)을 지정하는 경우를 생각한다. 텍스쳐 addressing mode를 D3DTADDRESS_WRAP 로 설정 하면, u 및 v 의 양방향에서 텍스쳐가 3 회 적용된다.

다음의 그림에 이것을 나타낸다.

이 텍스쳐 addressing mode의 이펙트는, 밀러 모드의 이펙트에 유사하는 부분이 있다. 상세한 것에 대하여는, 「밀러 텍스쳐 addressing mode」를 참조할것.


밀러 텍스쳐 addressing mode

D3DTEXTUREADDRESS 열거형의 D3DTADDRESS_MIRROR 멤버로 지정하는 밀러 텍스쳐 addressing mode에서는, Microsoft® Direct3D® 는 모든 정수 경계에서 텍스쳐를 미러링 한다. 예를 들어, 어플리케이션으로 정방형 프리미티브를 생성 해, 텍스쳐 좌표 (0.0, 0.0), (0.0, 3.0), (3.0, 3.0), 및 (3.0, 0.0)을 지정하는 경우를 생각한다. 텍스쳐 addressing mode를 D3DTADDRESS_MIRROR 로 설정 하면, u 및 v 의 양방향에서 텍스쳐가 3 회 적용된다. 텍스쳐가 적용되는 그 외의 모든 행과 열은, 직전의 행 또는 열의 경상이 된다.

다음의 그림에 이것을 나타낸다.

이 텍스쳐 addressing mode의 이펙트는, 랩 모드의 이펙트에 유사하는 부분이 있다. 상세한 것에 대하여는, 「랩 텍스쳐 addressing mode」를 참조할것.


클램프 텍스쳐 addressing mode

D3DTEXTUREADDRESS 열거형의 D3DTADDRESS_CLAMP 멤버로 지정하는 클램프 텍스쳐 addressing mode에서는, Microsoft® Direct3D® 는 텍스쳐 좌표를 [0.0, 1.0] 의 범위에 제한한다. 즉, 텍스쳐를 1 회 적용해, 다음에, 엣지의 픽셀의 색을 처발라 간다. 예를 들어, 어플리케이션으로 정방형 프리미티브를 생성 해, 텍스쳐 좌표 (0.0, 0.0), (0.0, 3.0), (3.0, 3.0), 및 (3.0, 0.0)을 그 프리미티브의 버텍스에 할당하는 경우를 생각한다. 텍스쳐 addressing mode를 D3DTADDRESS_CLAMP 로 설정 하면, 텍스쳐가 1 회 적용된다. 최초의 열과 마지막 행의 픽셀 칼라가, 프리미티브 위와 오른쪽으로 각각 퍼져 간다.

다음의 그림에 이것을 나타낸다.


경계색텍스쳐 addressing mode

D3DTEXTUREADDRESS 열거형의 D3DTADDRESS_BORDER 멤버로 지정하는 경계색텍스쳐 addressing mode에서는, Microsoft® Direct3D® 는 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 의 범위외의 모든 텍스쳐 좌표에 대해서, 경계색으로 불리는 임의의 색을 사용한다.

다음의 그림은, 이 처리를 나타내고 있다. 이 그림에서는, 어플리케이션은 적색의 경계색을 사용해 텍스쳐를 원시적으로 적용하도록(듯이) 지정하고 있다.

어플리케이션에서는,IDirect3DDevice8::SetTextureStageState 를 호출해 경계색을 설정한다. 이것을 호출하면나무의 제 1 파라미터에는 목적의 텍스쳐 스테이지 식별자를 설정해, 제 2 파라미터에는 D3DTSS_BORDERCOLOR 스테이지 스테이트값을 설정해, 제 3 파라미터에는 새로운 RGBA 경계색을 설정한다.


텍스쳐 addressing mode의 설정과 취득

IDirect3DDevice8::SetTextureStageState 메소드를 호출해, 각 텍스쳐 스테이지에 텍스쳐 addressing mode를 설정할 수 있다. 제 1 파라미터에 목적의 텍스쳐 스테이지 식별자를 지정한다. 제 2 파라미터에 D3DTSS_ADDRESSU, D3DTSS_ADDRESSV, 또는 D3DTSS_ADDRESSW 값을 설정해, u, v, 또는 w addressing mode를 개별적으로 갱신한다. SetTextureStageState 에 건네주는 제 3 파라미터는, 설정되어 있는 모드를 판별한다. 이것에는,D3DTEXTUREADDRESS 열거형의 어느 멤버를 지정해도 상관없다. 텍스쳐 스테이지의 현재의 텍스쳐 addressing mode를 취득하려면 ,IDirect3DDevice8::GetTextureStageState 를 호출해,D3DTEXTURESTAGESTATETYPE 열거의 D3DTSS_ADDRESSU, D3DTSS_ADDRESSV, 또는 D3DTSS_ADDRESSW 멤버를 사용해, 정보의 취득 대상의 addressing mode를 식별한다.


텍스쳐 addressing mode와 텍스쳐 랩핑

Direct3D 를 사용해, 어플리케이션에서는 텍스쳐 랩핑을 실행할 수 있다. 텍스쳐 addressing mode를 D3DTADDRESS_WRAP 로 설정하는 것으로, 텍스쳐 랩핑을 실행하는 것으로는 같지 않는 것에 주의 해야 한다. 텍스쳐 addressing mode를 D3DTADDRESS_WRAP 로 설정 하면, 현재의 원시적으로 적용되는 전송원텍스쳐의 카피가 복수 생성된다. 텍스쳐 랩핑을 유효하게 하면, 텍스쳐 처리된 다각형을 시스템이 라스터 처리할 때 방법이 변경된다. 상세한 것에 대하여는, 「텍스쳐 랩핑」을 참조할것.

텍스쳐 랩핑을 효과적으로 유효하게 하면,[0.0, 1.0] 외에 있는 텍스쳐 좌표를 무효로 할 수 있어 이러한 부적절한 텍스쳐 좌표의 라스터화의 동작을 미정도리로 할 수 있다. 텍스쳐 랩핑이 유효하게 되어 있으면(자), 텍스쳐 addressing mode는 사용되지 않는다. 텍스쳐 랩핑이 유효하게 되어 있는 경우에는, 어플리케이션으로 지정하는 텍스쳐 좌표가 0.0 보다 작고, 또는 1.0 보다 커지지 않게 주의 해야 한다.


텍스쳐 애드레싱에 있어서의 디바이스 제한

일반적으로, 시스템에서는 0.0 ~ 1.0 (0.0 으로 1.0 을 포함한다)의 범위외에 있는 텍스쳐 좌표에서도 사용할 수 있지만, 많은 경우, 그 허용 범위는 하드웨어 제한에 의해 영향을 받는다. 디바이스 능력을 취득 하면, 렌더링 디바이스는 이 제한을 D3DCAPS8 구조체의 MaxTextureRepeat 멤버에 알린다. 이 멤버내의 값은, 디바이스로 사용 가능한 텍스쳐 좌표의 전범위를 나타낸다. 예를 들어, 이 값이 128 의 경우, 입력 텍스쳐 좌표는 -128. 0 ~ +128. 0 의 범위내에 없으면 안 된다. 이 범위외의 텍스쳐 좌표를 가지는 버텍스를 건네주면(자) 무효가 된다. 자동 텍스쳐 좌표 생성 및 텍스쳐 좌표 트랜스 폼의 결과로서 생성된 텍스쳐 좌표에 대해서도, 이것과 같은 제한이 적용된다.

MaxTextureRepeat 의 해석도 D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 능력 비트에 의해 바뀐다. 이 비트를 설정 하면,D3DCAPS8 의 MaxTextureRepeat 멤버의 값이 정의대로 정확하게 사용된다. 다만, D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 가 설정되어 있지 않은 경우는, 텍스쳐 반복 제한은, 텍스쳐 좌표에 의해 인덱스화 된 텍스쳐의 사이즈에 의존한다. 이 경우, 유효한 텍스쳐 좌표의 범위를 계산하기 위해서,MaxTextureRepeat 는, 현재의 텍스쳐 사이즈에 의해 최대 상세 레벨로 스케일링 될 필요가 있다. 예를 들어, 텍스쳐의 치수가 32 로,MaxTextureRepeat 값이 512 의 경우, 실제의 유효한 텍스쳐 좌표 범위는 512/32 = 16 이 된다. 따라서, 이 디바이스에서는 -16. 0 ~ +16. 0 의 범위내에 텍스쳐 좌표가 존재할 필요가 있다.


텍스쳐의 더티 영역

어플리케이션에서는, 텍스쳐상에 더티 영역을 지정해, 텍스쳐의 어느 서브 세트를 카피하는지를 최적화할 수 있다. 더티로서 마크 되고 영역만이,IDirect3DDevice8::UpdateTexture 호출에 의해 카피된다. 다만, 더티 영역은 아라이먼트를 최적화하기 위해서 확대되는 일이 있다. 텍스쳐 생성시에는, 텍스쳐 전체가 더티라고 보여진다. 더티 상태의 텍스쳐에 영향을 주는 처리는, 이하의 4 개이다.

  • 텍스쳐에 더티 영역을 추가한다.
  • 텍스쳐내의 버퍼의 몇개인가를 잠근다. 이 처리에서는, 락 된 영역을 더티 영역으로서 추가한다. 어플리케이션에서는, 실제의 더티 영역을 잘 알고 있으면, 이 더티 영역의 자동 갱신은 오프로 할 수 있다.
  • IDirect3DDevice8::CopyRects 의 전송 먼저 텍스쳐를 사용 하면, 텍스쳐 전체가 더티로서 마크 된다.
  • UpdateTexture 의 전송 바탕으로 텍스쳐를 사용 하면, 전송원텍스쳐의 더티 영역이 모두 클리어 된다.

더티 영역은 밉맵 텍스쳐의 최상정도 레벨로 설정되어UpdateTexture 는, 더티 영역을 밉체까지 확대해 각 서브 레벨로 카피되는 바이트수를 최소한으로 억제할 수가 있다. 서브 레벨 더티 영역의 좌표는 외측에 말 수 있다, 즉 소수 부분은 텍스쳐에 가장 근접하는 엣지에 둥근 일로 주의 해야 한다.

텍스쳐 타입에 의해 더티 영역의 타입도 다르기 (위해)때문에, 테키스체타이프 마다 메소드가 있다. 2D 텍스쳐는 더티 직사각형을, 볼륨 텍스쳐는 박스를 사용한다.

  • IDirect3DCubeTexture8::AddDirtyRect
  • IDirect3DTexture8::AddDirtyRect
  • IDirect3DVolumeTexture8::AddDirtyBox

상기 메소드의 pDirtyRect 또는 pDirtyBox 파라미터에 NULL 를 건네주면(자), 더티 영역이 확대해 텍스쳐 전체를 가린다.

각 락킹 메소드는 D3DLOCK_NO_DIRTY_UPDATE 를 취해, 이것에 의해, 텍스쳐의 더티 상태가 변경되는 것을 막을 수가 있다. 상세한 것에 대하여는, 「리소스의 락」을 참조할것.

어플리케이션은, 락 처리 사용 가능시에, 영역의 트루 세트에 관한 상세 정보가 변경되었을 때는, D3DLOCK_NO_DIRTY_UPDATE 를 사용한다. (최상정도 레벨까지 락 또는 카피하지 말아줘) 텍스쳐의 서브 레벨만을 락 또는 카피해도, 그 텍스쳐의 더티 영역은 갱신되지 않는 것에 주의 해야 한다. 어플리케이션에서도, 최상정도 레벨을 잠그지 않고 하위 레벨을 잠그어도, 더티 영역은 갱신되지 않는다.


텍스쳐 팔레트

Microsoft® Direct3D® for Microsoft DirectX® 8.0 은,IDirect3DDevice8 오브젝트에 관련지을 수 있었던 256 엔트리의 팔레트 세트에 의한 팔레트 텍스쳐를 지원 한다. 팔레트를 경향으로 하려면 ,IDirect3DDevice8::SetCurrentTexturePalette 메소드를 호출한다. 커런트 팔레트는, 모든 액티브 텍스쳐 스테이지의 모든 팔레트 텍스쳐에 사용된다. IDirect3DDevice8::SetPaletteEntries 는, 팔레트의 256 엔트리를 모두 갱신한다. 각 엔트리는, 포맷 D3DFMT_A8R8G8B8 의 PALETTEENTRY 구조체이다. 모든 엔트리는 디폴트로 0xFFFFFFFF 로 설정된다. DirectX 8.0 의 시점에서는,PALLETTEENTRY 구조체의 peFlags 멤버는, Microsoft Platform Software Development Kit (SDK)로 설명되고 있도록(듯이)는 동작하지 않는 것에 주의 해야 한다. peFlags 멤버는 향후, 8 비트의 팔레트화 된 포맷의 알파 채널이다.

IDirect3DDevice8 팔레트는, 알파 채널을 포함한다. 이 알파 채널은, 디바이스가 팔레트로부터의 알파 채널을 지원 하는 것을 나타내는 D3DPTEXTURECAPS_ALPHAPALETTE 디바이스 능력 플래그가 설정되어 있을 때 사용할 수 있다. 팔레트 알파 채널은, 텍스쳐 포맷에 알파 채널이 없는 경우에 사용한다. 디바이스가 팔레트로부터의 알파를 지원 하지 않고, 텍스쳐 포맷에 알파 채널이 없는 경우는, 0xFF 의 값이 알파에 사용된다.

최대로 16,384 의 팔레트가 있다. 팔레트 세트에 관련지을 수 있는 메모리 리소스는, 어플리케이션이 참조하는 팔레트의 최대수 에 비례하기 (위해)때문에, 팔레트 번호에는, 제로로부터 시작되는 연속하는 수를 사용해야 한다.


텍스쳐 좌표

여기에서는, 텍스쳐 좌표의 개념, 텍스쳐 좌표 포맷, 및 텍스쳐 좌표 포맷을 조작하는 Microsoft® Direct3D® 의 서비스에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 텍스쳐 좌표에 대해
  • 텍셀과 픽셀간의 직접 매핑
  • 텍스쳐 좌표 포맷
  • 텍스쳐 좌표 처리


텍스쳐 좌표에 대해

대부분의 텍스쳐는, 비트 맵 같이, 칼라값의 2 차원 배열이다. 다만, 큐브 환경 맵 텍스쳐는 제외하다. 상세한 것에 대하여는, 「큐브 환경 맵」을 참조할것. 개개의 칼라값은, 텍스쳐 요소 또는텍셀로 불린다. 각 텍셀은, 텍스쳐내의 일의의 주소를 가진다. 이 주소는, 각각 u 와 v 로 나타내지는 행과 열의 번호이다고 생각할 수가 있다.

텍스쳐 좌표는 텍스쳐 공간에 있다. 즉, 텍스쳐 좌표는, 텍스쳐내의 것 (0,0)을 기준으로 한 상대 위치 좌표에 존재한다. 텍스쳐를 3D 공간의 원시적으로 적용 하면 와, 그 텍셀 주소를 오브젝트 좌표에 매핑 해야 한다. 그 후, 이 주소를 화면 좌표, 즉 픽셀 위치 좌표에 평행이동 할 필요가 있다.

Microsoft® Direct3D® 는, 텍스쳐 공간의 텍셀을 스크린 공간의 픽셀에 직접 매핑 한다. 이것에 의해, 중간의 순서가 생략 되어 효율이 높아진다. 이 매핑 처리는, 실제는 역매핑이다. 즉, 스크린 공간의 각 픽셀에 대해, 텍스쳐 공간의 대응하는 텍셀 위치 좌표가 계산된다. 이 포인트 또는 이 주위로 텍스쳐 칼라가 샘플링 된다. 이 샘플링 처리는, 텍스쳐 필터 링으로 불린다. 상세한 것에 대하여는, 「텍스쳐 필터 링」을 참조할것.

텍스쳐의 각 텍셀은, 텍셀 좌표로 지정할 수 있다. 그러나, 텍셀을 원시적으로 매핑 하기 위해서는, Direct3D 는, 모든 텍스쳐의 모든 텍셀에 대해서 동일한 주소 범위를 필요로 한다. 따라서, 모든 텍셀 주소가 0.0 ~ 1.0 의 범위에 있는 포괄적 주소 지정 스킴이 사용된다. 2D 데카르트 좌표가 x, y 좌표로 지정되는 것과 같이, Direct3D 어플리케이션에서는 u 와 v 의 값으로 텍스쳐 좌표를 지정한다. 실제로는, 0.0 ~ 1.0 의 범위외의 텍스쳐 좌표를 처리하는 일도 가능해, 텍스쳐 애드레싱으로 설정하는 파라미터를 사용해 이 처리를 실시한다. 상세한 것에 대하여는, 「텍스쳐 addressing mode」를 참조할것.

이 결과, 동일한 텍스쳐 주소를 다른 텍스쳐가 다른 텍셀에 매핑 할 수 있다. 다음의 그림에서는, 텍스쳐 주소 (0.5, 1.0)를 사용하고 있다. 그러나, 이러한 텍스쳐는 사이즈가 다르기 (위해)때문에, 텍스쳐 주소는 다른 텍셀에 매핑 된다. 좌측의 텍스쳐 1 은 5x5 이다. 텍스쳐 주소 (0.5, 1.0)는 텍셀 (2,4)에 매핑 된다. 우측의 텍스쳐 2 는 7x7 이다. 텍스쳐 주소 (0.5, 1.0)는 텍셀 (3,6)에 매핑 된다.

다음의 그림은, 간단한 텍셀 매핑 처리를 나타내고 있는 실제, 이것은 매우 단순한 예이다. 상세한 것에 대하여는, 「텍셀과 픽셀간의 직접 매핑」을 참조할것.

이 예에서는, 그림의 좌측의 픽셀을 관념화해 색첨부의 정방형으로 가리킨다. 이 픽셀의 4 개의 모퉁이의 주소는, 오브젝트 공간의 3D 원시적으로 매핑 된다. 픽셀의 형상은, 3D 공간의 프리미티브의 형상과 표시 각도가 원인으로 비뚤어지는 것이 많다. 다음에, 픽셀의 모퉁이에 대응한다, 프리미티브 위에의 표면 영역의 모퉁이가, 텍스쳐 공간에 매핑 된다. 이 매핑 처리에 의해 픽셀의 형상이 다시 비뚤어지지만, 이것이 일반적이다. 픽셀의 최종적인 칼라값은, 픽셀이 매핑 되는 영역의 텍셀로부터 계산된다. 텍스쳐 필터 링 메소드를 설정할 경우에 Direct3D 가 픽셀 칼라를 얻기 위해서(때문에) 사용하는 메소드를 결정한다. 상세한 것에 대하여는, 「텍스쳐 필터 링」을 참조할것.

어플리케이션은, 텍스쳐 좌표를 직접 버텍스에 할당할 수가 있다. 이 기능에 의해, 원시적으로 매핑 하는 텍스쳐의 부분을 결정할 수가 있다. 예를 들어, 다음의 그림의 텍스쳐와 완전히 같은 사이즈의 직사각형 프리미티브를 생성 하는 경우를 생각한다. 이 예에서는, 어플리케이션으로 텍스쳐 전체를 벽전체에 매핑 한다. 어플리케이션이 프리미티브의 버텍스에 할당하는 텍스쳐 좌표는, (0.0, 0.0), (1.0, 0.0), (1.0, 1.0), 및 (0.0, 1.0)이다.

벽의 높이를 1/2 만 작게 하는 경우는, 작은 벽에 맞추어 텍스쳐를 비뚤어지게 하는지, Direct3D 가 텍스쳐의 하반신을 사용하도록(듯이) 텍스쳐 좌표를 할당할 수가 있다.

작은 벽에 맞추어 텍스쳐를 비뚤어지게 하거나 스케일링 하거나 하는 경우, 사용하는 텍스쳐 필터 링 메소드에 의해 화질이 바뀐다. 상세한 것에 대하여는, 「텍스쳐 필터 링」을 참조할것.

Direct3D 로 작은 벽에 대해서 텍스쳐의 하반신을 사용하도록(듯이) 텍스쳐 좌표를 할당하는 경우, 어플리케이션이 이 프리미티브의 버텍스에 할당하는 텍스쳐 좌표는, (0.0, 0.0), (1.0, 0.0), (1.0, 0.5), 및 (0.0, 0.5)이 된다. Direct3D 는, 텍스쳐의 하반신을 벽에 적용한다.

버텍스의 텍스쳐 좌표가 1.0 을 넘고 있어도 상관없다. 0.0 ~ 1.0 의 범위외의 텍스쳐 좌표를 버텍스에 할당할 때는, 텍스쳐 addressing mode도 설정해야 한다. 상세한 것에 대하여는, 「텍스쳐 addressing mode」를 참조할것.


텍셀과 픽셀간의 직접 매핑

스크린 위에의 픽셀에 텍셀을 직접 매핑 하는 등, 어플리케이션에서는 보통, 장면내의 지오메트리에 텍스쳐를 적용할 필요가 있다. 예를 들어, 텍스쳐내의 텍스트를 장면내의 오브젝트에 표시할 필요가 있는 어플리케이션을 생각한다. 텍스쳐내의 텍스트 정보를 분명히 표시하려면 , 텍스쳐를 베푸는 지오메트리가, 텍스쳐 필터 링에 의해 무너지지 않은 텍셀을 확실히 받기 위한 어떠한 방법이 필요하다. 이것을 하지 않으면 멍하니 한 화면이 되거나 포인트 샘플 텍스쳐 필터 링의 경우에는 엣지가 엉성해질 가능성이 있다.

Microsoft® Direct3D® 에서는, 화면과 텍스쳐의 필터 링을 지원 하는 한편으로, 픽셀과 텍스쳐의 샘플링 룰은, 픽셀과 텍스쳐의 샘플링을 단일화하도록(듯이) 신중하게 정의되고 있기 (위해)때문에, 텍스쳐의 텍셀을 취득해 스크린 위에의 픽셀에 직접 매핑 하는 처리는 중요해, 곤란한 작업이 되는 것이 많다. 그 때문에, 버텍스에 대한 부동 소수점 텍스쳐 좌표가, 래스터라이저로 사용하는 정수 픽셀 좌표에 어떻게 매핑 될까에 임해서 충분히 이해해 둘 필요가 있다.

Direct3D 에서는, 다음의 계산을 실행해, 부동 소수점 텍스쳐 좌표를 텍셀 주소에 매핑 한다.

이러한 공식에서는,Tx 와 Ty 는 수평 방향과 수직 방향의 출력 텍셀 좌표,u 와 v 는 버텍스에 대해서 제공되는 수평 방향과 수직 방향의 텍스쳐 좌표이다. Mx 와 My 요소는, 현재의 밉맵 레벨에서의 수평 방향과 수직 방향의 텍셀수를 나타낸다. 설명의 후반으로는, 텍셀과 픽셀간의 수평 방향 매핑에 대해 해설한다. 수직 방향 매핑은 수평 방향으로 매핑 하는 경우와 같다.

텍스쳐 좌표의 상한과 하한의 0.0 으로 1.0 을 이러한 공식으로 대입 하면, 텍스쳐 좌표 0.0 은 반복 텍스쳐 맵의 최초와 마지막 텍셀간의 중간점에 매핑 된다. 텍스쳐 좌표 1.0 은, 현재의 보간 텍스쳐 맵의 마지막 텍셀과 다음의 보간 텍스쳐 맵간의 중간점에 매핑 된다. 텍셀폭이 4 의 반복 텍스쳐로, 밉맵 레벨이 0 의 경우, 좌표 0.0 으로 1.0 은, 다음의 그림에 나타내도록(듯이) 매핑 된다.

매핑에 대해 이해해 두면(자), 단순한 바이어스를 스크린 공간의 지오메트리 좌표에 적용해, 각 텍셀을 대응하는 픽셀에 강제적으로 매핑 할 수가 있다. 예를 들어, 4 개의 옆이 있는 다각형으로, 전의 텍스쳐의 각 텍셀을 스크린 위에의 1 개(살)만의 픽셀에 매핑 하는 경우, 지오메트리 좌표로 픽셀을 강제적으로 오버랩 해, 각 텍셀의 중심을 각 픽셀의 중심으로 효과적으로 배치할 필요가 있다. 이 결과, 어플리케이션으로 많은 경우 필요한 1 대 1 매핑이 된다.

텍셀폭이 4 의 텍스쳐를 픽셀 좌표 0 ~ 3 에 매핑 하려면 , 각각 스크린 공간 좌표 –0. 5 ~ 3.5 로 텍스쳐 좌표 0.0 ~1.0 을 가지는 4 옆으로부터 완성되는 다각형을, 2 개의 삼각형을 기본으로 드로잉(Drawing) 한다. 예를 들어, 화면 좌표 0.0 에 있는 픽셀을 예로서 생각한다. 0.0 은 최초의 버텍스 (-0. 5)로부터 0.5 픽셀만 멀어진 위치 좌표에 있어, 합계폭이 4.0 인 것으로부터, 보간 텍스쳐의 좌표는 0.125 가 된다. 이것을 텍스쳐 사이즈 4 를 기본으로 스케일링 하면, 좌표는 0.5 가 된다. 바이어스를 0.5 만 줄이면(자) 텍스쳐 주소가 0.0 이 된다. 이것은, 맵내의 최초의 텍셀에 완전에 대응한다.

요약 하면, 텍스쳐 좌표는 텍스쳐 맵을 양측으로 균등하게 오버랩 한다. 다음의 그림은, 텍셀폭이 4 의 텍스쳐의 매핑을 나타내고 있다.

픽셀 좌표는, 텍셀의 경우와 같게 정규화된다. 따라서, 버텍스가 렌더링처의 픽셀을 오버랩 해, 그 버텍스로써 텍스쳐 좌표 0.0 으로 1.0 을 사용하는 경우, 픽셀과 텍셀이 일렬에 줄선다. 양쪽 모두의 사이즈가 거의 같아 적절히 정렬하고 있으면, 다음의 그림에 나타내도록(듯이), 이것들은 텍셀과 픽셀간에 정확하게 대응한다.


텍스쳐 좌표 포맷

Microsoft® Direct3D® 의 텍스쳐 좌표에는, 1, 2, 3, 또는 4 개의 부동 소수점 요소를 포함해, 다양한 크기의 텍스쳐를 처리할 수 있다. 1D 텍스쳐 (크기가 1 x n 의 텍스쳐 표면)의 경우는, 1 개의 텍스쳐 좌표로 처리된다. 가장 일반적인 2D 텍스쳐의 경우는, 보통 u 와 v 로 불리는 2 개의 텍스쳐 좌표에 의해 처리된다. Direct3D 에서는, 큐브 환경 맵이라고 하는 3D 텍스쳐를 1 종류만 지원 하고 있다. 큐브 환경 맵은, 실제로는 3D 는 아니지만, 3 요소 벡터에 의해 처리된다. 상세한 것에 대하여는, 「큐브 환경 맵」을 참조할것.

「버텍스 포맷에 대하며」로 설명하도록(듯이), 어플리케이션에서는 버텍스 포맷내의 텍스쳐 좌표를 encode 한다. 버텍스 포맷에는 텍스쳐 좌표의 복수세트를 포함할 수가 있다. D3DFVF_TEX0 ~ D3DFVF_TEX8 유연한 버텍스 포맷 플래그를 사용해, 텍스쳐 좌표를 포함하지 않는가, 최대 8 개세트까지 포함하는 것을 지정한다.

각 텍스쳐 좌표 세트에는, 1 ~4 개의 요소를 포함할 수가 있다. D3DFVF_TEXTUREFORMAT1 ~ D3DFVF_TEXTUREFORMAT4 플래그는, 텍스쳐 좌표 세트내에 있는 요소의 개수를 기술하지만, 이러한 플래그는 단독으로는 사용하지 않는다. 그 대신해, 이러한 플래그는, 버텍스 포맷의 특정의 텍스쳐 좌표 세트로 사용되는 요소의 개수를 기술하는 비트 패턴의 생성을 위해서(때문에), 매크로의 D3DFVF_TEXCOORDSIZEn 세트로 사용한다. 이러한 매크로는, 요소수를 정의하는 좌표 세트의 인덱스를 식별하는 파라미터를 1 개 받는다. 다음의 그림은, 이러한 매크로의 사용 방법을 나타내고 있다.

// 이 버텍스 포맷에는, 2 개의 텍스쳐 좌표 세트가 포함되어 있다.
// 1 번째세트 (인덱스 0)에는 2 개의 요소가 있어, 2 번째세트에는
// 1 개의 요소가 있다. '이 버텍스 포맷은 다음과 같이 기술된다.
//     dwFVF = D3DFVF_XYZ  | D3DFVF_NORMAL | D3DFVF_DIFFUSE | D3DFVF_TEX2 |
//             D3DFVF_TEXCOORDSIZE2(0) | D3DFVF_TEXCOORDSIZE1(1);
typedef struct CVF
{
    D3DVECTOR position;
    D3DVECTOR normal;
    D3DCOLOR  diffuse;
    float     u, v;   // 1 번째세트, 2D
    float     t;      // 2 번째세트, 1D
} CustomVertexFormat;

주 큐브 환경 맵을 제외해, 래스터라이저에서는 3 개 이상의 요소를 사용해 텍스쳐를 처리할 수 없다. 어플리케이션에서는 텍스쳐 좌표에 최대 3 개(살)까지 요소를 지정할 수 있지만, 이것이 가능한 것은, 텍스쳐가 큐브 맵의 경우인가, D3DTTFF_PROJECTED 텍스쳐 트랜스 폼 플래그가 사용되고 있는 경우뿐이다. D3DTTFF_PROJECTED 플래그가 사용되고 있는 경우, 래스터라이저는 최초의 2 개의 요소를 3 번째 (또는 n 번째)의 요소로 나눗셈 한다. 상세한 것에 대하여는, 「텍스쳐 좌표 트랜스 폼」을 참조할것.


텍스쳐 좌표 처리

여기에서는, Microsoft® Direct3D® 로 지원 하는 텍스쳐 좌표 처리에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 텍스쳐 좌표 처리의 흐름
  • 텍스쳐 좌표의 자동 생성
  • 텍스쳐 좌표 트랜스 폼
  • 텍스쳐 좌표 처리의 사용법


텍스쳐 좌표 처리의 흐름

다음의 그림은, 텍스쳐 좌표가 처리를 통해 래스터라이저에 보내질 때까지의 흐름을 나타내고 있다.

시스템에서는, 2 개의 소스로부터 텍스쳐 좌표를 드로잉(Drawing) 할 수 있다. 소정의 텍스쳐 스테이지에서는, 버텍스 포맷 (D3DFVF_TEX1 ~ D3DFVF_TEX8)에 포함되는 텍스쳐 좌표를 사용하는지, Microsoft® Direct3D® 로 자동 생성한 텍스쳐 좌표를 사용할 수 있다. 후자의 상세한 것에 대하여는, 「텍스쳐 좌표의 자동 생성」을 참조할것. 현재의 텍스쳐 스테이지의 D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트를 D3DTTFF_DISABLE (디폴트 설정)로 설정 하면, 입력 좌표는 트랜스 폼 되지 않는다. D3DTSS_TEXTURETRANSFORMFLAGS 를 다른 값으로 설정 하면, 그 스테이지의 트랜스 폼 행렬이 입력 좌표에 적용된다.

D3DTEXTURETRANSFORMFLAGS 열거형은,D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트에 유효한 값을 정의한다. 텍스쳐 좌표 트랜스 폼을 실행하지 않는 D3DTTFF_DISABLE 플래그를 제외해, 이 열거에 정의되는 값은, 시스템에 의해 래스터라이저에게 건네지는 출력 좌표의 개수를 설정한다. D3DTTFF_COUNT1 ~ D3DTTFF_COUNT4 플래그의 경우, 1, 2, 3, 또는 4 개의 요소가 출력 좌표로부터 래스터라이저에게 건네진다. 현재 1D 텍스쳐 좌표는 지원되어 있지 않다.

D3DTTFF_PROJECTED 플래그는 특별한 플래그이다. 이 플래그는, 텍스쳐 좌표가 투영 텍스쳐용의 것임을 시스템에 알린다. D3DTTFF_PROJECTED 플래그와 D3DTEXTURETRANSFORMFLAGS 의 다른 멤버를 조합하는 것으로, 모든 요소를 마지막 요소로 나눗셈 하고 나서 라스터화를 실행하도록(듯이) 래스터라이저에 알린다. 예를 들어, 3 요소의 텍스쳐 좌표, 또는, 트랜스 폼 후의 3 요소의 텍스쳐 좌표를 명시적으로 사용할때, D3DTTFF_COUNT3 및 D3DTTFF_PROJECTED 플래그를 조합해 사용 하면, 래스터라이저로 최초의 2 개의 요소를 마지막 요소로 나눗셈 해, 2D 텍스쳐의 처리에 필요한 2D 텍스쳐 좌표를 생성할 수 있다.

주 큐브 환경 맵을 제외해, 래스터라이저에서는 3 개 이상의 요소를 사용해 텍스쳐를 처리할 수 없다. 경향 텍스쳐를 처리하기 위해서 사용할 수 있는 요소수보다 많은 요소를 텍스쳐 스테이지로 지정했을 경우, 무관계한 요소는 무시된다. 이것은, 1D 텍스쳐에 대해서 2D 텍스쳐 좌표를 사용할때에도 들어맞는다.


텍스쳐 좌표의 자동 생성

Microsoft® Direct3D® 에서는, 버텍스에 대해서 텍스쳐 좌표를 자동적으로 생성할 수 있다. 여기에서는, 시스템이 제공하는 기능과 그 사용 방법에 대해 자세하게 설명한다. 설명하는 주제는, 다음과 같다.

  • 텍스쳐 좌표의 자동 생성에 대해
  • 텍스쳐 좌표의 자동 생성의 구성


텍스쳐 좌표의 자동 생성에 대해

시스템에서는, 트랜스 폼 후의 카메라 공간 위치 좌표 또는 버텍스의 법선을 텍스쳐 좌표로서 사용할 수 있다. 또, 큐브 환경 맵을 실행하기 위한 3 요소 벡터를 계산하는 일도 가능하다. 버텍스로써 명시적으로 지정하는 텍스쳐 좌표와 같이, 자동 생성된 텍스쳐 좌표는, 텍스쳐 좌표 트랜스 폼용의 입력으로서 사용할 수 있다.

텍스쳐 좌표의 자동 생성에서는, 버텍스 포맷에서의 명시적인 텍스쳐 좌표의 필요성을 배제하는 것으로, 지오메트리 데이터로 필요한 대역폭을 큰폭으로 삭감할 수 있다. 많은 경우, 시스템으로 생성된 텍스쳐 좌표는, 특수 효과를 낳는 트랜스 폼과 함께 사용할 수 있다. 물론, 이 기능은 특수한 용도에 사용되는 것이어, 명시적인 텍스쳐 좌표를 사용하는 케이스도 많이 있다.


텍스쳐 좌표의 자동 생성의 구성

C++ 의 경우, (D3DTEXTURESTAGESTATETYPE 열거형으로부터의) D3DTSS_TEXCOORDINDEX 텍스쳐 스테이지 스테이트를 사용해, 텍스쳐 좌표의 생성 방법을 제어한다.

보통, 이 스테이트는, 버텍스 포맷으로 encode 된 특정의 텍스쳐 좌표 세트를 사용하도록(듯이) 시스템에 알린다. 이 스테이트에 할당하는 값안에, D3DTSS_TCI_CAMERASPACENORMAL, D3DTSS_TCI_CAMERASPACEPOSITION, 또는 D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR 플래그를 포함했을 경우, 시스템으로 실행되는 처리는 크게 달라 진다. 이러한 플래그의 어느쪽이든에서도 존재하고 있을 때, 텍스쳐 스테이지는 버텍스 포맷의 텍스쳐 좌표를 무시해, 시스템이 생성하는 좌표를 우선한다. 각 플래그의 의미는, 다음과 같다.

D3DTSS_TCI_CAMERASPACENORMAL
버텍스 법선을 입력 텍스쳐 좌표로서 사용한다. 버텍스 법선은 카메라 공간에 트랜스 폼 된다.
D3DTSS_TCI_CAMERASPACEPOSITION
버텍스 위치 좌표를 입력 텍스쳐 좌표로서 사용한다. 버텍스 위치 좌표가 카메라 공간에 트랜스 폼 된다.
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
반사 벡터를 입력 텍스쳐 좌표로서 사용한다. 반사 벡터가 카메라 공간에 트랜스 폼 된다. 반사 벡터는, 입력 버텍스 위치 좌표와 법선 벡터로부터 계산된다.

이러한 플래그는 서로 배타적이다. 이러한 플래그의 어느쪽이든을 사용하는 경우는, 텍스쳐 랩핑 모드를 결정하기 위해서(때문에) 시스템으로 사용하는 인덱스값을 지정할 수 있다.

다음의 코드는, C++ 에서의 이러한 플래그의 사용 방법을 나타내고 있다.

/*
* 이 코드에서는, 변수 d3dDevice 는, IDirect3DDevice8 인터페이스에의
* 유효한 포인터이라고 가정하고 있다.
 *
* 이 텍스쳐 스테이지의 입력 텍스쳐 좌표로서
* 버텍스 위치 좌표 (카메라 공간)를 사용해,
* D3DRENDERSTATE_WRAP1 렌더링 스테이트의 랩 모드 세트를 사용한다.
 */
d3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX,
                                   D3DTSS_TCI_CAMERASPACEPOSITION | 1 );

주 자동 생성된 텍스쳐 좌표는, 텍스쳐 좌표 트랜스 폼의 입력값으로서 매우 편리하고, 또 큐브 환경 맵의 3 요소 벡터를 계산할 필요가 없다고 하는 점에서도 편리하다.

참조

텍스쳐 좌표 트랜스 폼,큐브 환경 맵


텍스쳐 좌표 트랜스 폼

여기에서는, Microsoft® Direct3D® 직접 모드로 제공되는 텍스쳐 좌표 트랜스 폼 기능의 조작에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 텍스쳐 좌표 트랜스 폼에 대해
  • 텍스쳐 좌표 트랜스 폼의 설정과 취득
  • 텍스쳐 좌표 트랜스 폼을 유효하게 한다


텍스쳐 좌표 트랜스 폼에 대해

Microsoft® Direct3D® 디바이스에서는, 4×4 행렬을 적용해, 버텍스의 텍스쳐 좌표를 트랜스 폼 할 수 있다. 시스템은, 텍스쳐 좌표에 대해서, 지오메트리의 경우와 같게 트랜스 폼을 적용한다. 적용 가능한 트랜스 폼에는, 스케일링, 회전, 평행이동, 투영, 전단, 또는 이러한 편성 등, 4×4 행렬로 가능한 모든 트랜스 폼이 있다.

주 Direct3D 에서는, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」는 수정되지 않는다. 따라서, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」를 사용하는 어플리케이션에서는, Direct3D 에 의해 버텍스의 텍스쳐 좌표를 트랜스 폼 할 수 없다.

하드웨어 가속화에 의한 트랜스 폼 & 라이팅 처리를 지원 하는 디바이스 (TnLHAL 디바이스)에서는, 텍스쳐 좌표 트랜스 폼도 고속 처리된다. 하드웨어 가속화에 의한 트랜스 폼을 이용할 수 없는 경우는, Direct3D 지오메트리 파이프라인의 플랫폼 고유의 최적화에 의해 텍스쳐 좌표 트랜스 폼이 실행된다.

텍스쳐 좌표 트랜스 폼은, 지오메트리의 텍스쳐 좌표를 직접 변경하지 않고 특수 효과를 내려고 하는 경우에 편리하다. 단순한 평행이동 행렬이나 회전 행렬을 사용해, 오브젝트 위에의 텍스쳐를 애니메이션 하거나 Direct3D 에 의해 자동 생성되는 텍스쳐 좌표를 트랜스 폼 하는 것으로, 투영 텍스쳐나 동적 라이트 매핑 등 고도의 이펙트를 단순화 해, 고속 처리하는 일도 가능하다. 또, 텍스쳐 좌표 트랜스 폼을 사용해, 텍스쳐 좌표의 단일 세트를 복수의 텍스쳐 스테이지에서의 다양한 목적을 위해서(때문에) 재이용할 수 있다.

상세한 것에 대하여는, 「텍스쳐 좌표 처리의 사용법」을 참조할것.


텍스쳐 좌표 트랜스 폼의 설정과 취득

어플리케이션으로 지오메트리에 사용하는 행렬과 같이,IDirect3DDevice8::SetTransform 및 IDirect3DDevice8::GetTransform 메소드를 호출해 텍스쳐 좌표 트랜스 폼을 설정 및 취득할 수 있다. 이러한 메소드는, 텍스쳐 스테이지 0 ~ 7 의 트랜스 폼 행렬을 각각 식별하는,D3DTRANSFORMSTATETYPE 열거형의 D3DTS_TEXTURE0 ~ D3DTS_TEXTURE7 멤버를 받는다.

다음의 코드는, 텍스쳐 스테이지 0 의 텍스쳐 좌표에 적용되는 행렬을 설정한다.

// 이 예에서는, 변수 d3dDevice 는
// IDirect3DDevice8 인터페이스에의 유효한 포인터를 저장 하고 있다.
//
D3DMATRIX matTrans = D3DXMatrixIdentity( NULL );

// 목적의 트랜스 폼용의 행렬을 설정한다.
d3dDevice->SetTransform( D3DTS_TEXTURE0, &matTrans );


텍스쳐 좌표 트랜스 폼을 유효하게 한다

D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트는, 텍스쳐 좌표 트랜스 폼의 적용을 제어한다. 이 텍스쳐 스테이지 스테이트의 값은,D3DTEXTURETRANSFORMFLAGS 열거형으로 정의된다.

D3DTSS_TEXTURETRANSFORMFLAGS 가 D3DTTFF_DISABLE (디폴트값)로 설정되어 있을 때는, 텍스쳐 좌표 트랜스 폼은 무효이다. 텍스쳐 좌표 트랜스 폼이 스테이지 0 에 대해서 유효한 경우, 다음의 코드는 이것을 무효로 한다.

// 이 예에서는, 변수 d3dDevice 에는
// IDirect3DDevice8 인터페이스에의 유효한 포인터가 저장 되고 있다.

D3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_DISABLE );

D3DTEXTURETRANSFORMFLAGS 에 정의되고 있는 그 외의 값은, 텍스쳐 좌표 트랜스 폼을 유효하게 하기 위한(해), 또, 결과적으로 생성되는 텍스쳐 좌표의 요소 가운데, 래스터라이저에 건네주는 개수를 제어하기 위해서 사용한다. 예로서 다음의 코드를 생각한다.

// 이 예에서는, 변수 d3dDevice 에는
// IDirect3DDevice8 인터페이스에의 유효한 포인터가 저장 되고 있다.

D3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2 );

D3DTTFF_COUNT2 값은, 텍스쳐 스테이지 0 용의 트랜스 폼 행렬 세트를 적용해, 트랜스 폼 후의 텍스쳐 좌표의 최초의 2 개의 요소를 래스터라이저에 건네주도록(듯이) 시스템에 지시한다.

D3DTTFF_PROJECTED 텍스쳐 트랜스 폼 플래그는, 투영 되는 텍스쳐의 좌표를 나타낸다. 이 플래그가 지정되고 있는 경우, 래스터라이저는 트랜스 폼 대상의 요소를 마지막 요소로 나눗셈 한다. 예로서 다음의 코드를 생각한다.

// 이 예에서는, 변수 d3dDevice 에는
// IDirect3DDevice8 인터페이스에의 유효한 포인터가 저장 되고 있다.

d3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS,
                                   D3DTTFF_COUNT3 | D3DTTFF_PROJECTED );

이 예에서는, 3 개의 텍스쳐 좌표 요소를 래스터라이저에 건네주도록(듯이) 시스템에 알린다. 래스터라이저에서는, 최초의 2 개의 요소를 3 번째의 요소로 나눗셈 해, 텍스쳐의 처리에 필요한 2D 텍스쳐 좌표를 생성한다.


텍스쳐 좌표 처리의 사용법

다음에 나타내는 것은, 텍스쳐 좌표 처리에 의해 특수한 텍스쳐 이펙트를 내는 방법이다.

모델상에서 텍스쳐를 애니메이션 한다 (평행이동 또는 회전을 이용)

  • 2D 텍스쳐 좌표를 버텍스 포맷에 정의한다.
    // 2D 텍스쳐 좌표를 가지는 단일의 텍스쳐를 사용한다. 이 비트 패턴은,
// 필요에 따라서, 위치 좌표, 법선, 및 색정보를 추가할 수 있도록(듯이)
// 확장할 필요가 있다.
DWORD dwFVFTex = D3FVF_TEX1 | D3DFVF_TEXCOORDSIZE2(0);
  • 2D 텍스쳐 좌표를 사용하도록(듯이) 래스터라이저를 설정한다.
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2);
  • 적절한 텍스쳐 좌표 트랜스 폼 행렬을 정의해 설정한다.
    // M 는, U 및 V 방향의 텍스쳐 좌표를 평행이동하기 위한
// D3DMATRIX 이다.
//      1   0  0  0
//      0   1  0  0
//      du dv  1  0 (du 및 dv 는 각 프레임을 변경한다)
//      0   0  0  1

D3DMATRIX M = D3DXMatrixIdentity(); // d3dutil.h 에 선언된다.
M. _31 = du;
M. _32 = dv;

모델의 카메라 공간 위치 좌표의 선형 함수로서 텍스쳐 좌표를 생성 한다

  • D3DTSS_TCI_CAMERASPACEPOSITION 플래그를 사용해, 카메라 공간의 버텍스 위치 좌표를 입력으로서 텍스쳐 트랜스 폼에 건네준다.
    // 입력 버텍스에는 텍스쳐 좌표가 없고,
// 대역폭이 절약되고 있다. 3 개의 텍스쳐 좌표는, 카메라 공간 (x, y, z)의 버텍스 위치 좌표를 사용해
// 생성된다.
SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION);
  • 래스터라이저로 2D 텍스쳐 좌표를 평가한다.
    // 2 개의 출력 좌표를 사용한다.
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2);
  • 선형 함수를 적용하는 행렬을 정의해 설정한다.
    // 다음에 나타내도록(듯이),
// 텍스쳐 좌표를 선형 함수로서 생성한다.
//      u = Ux*x + Uy*x + Uz*x + Uw
//      v = Vx*x + Vy*x + Vz*x + Vw
// 이 경우, 행렬 M 는 다음과 같이 된다.
//      Ux  Vx  0  0
//      Uy  Vy  0  0
//      Uz  Vz  0  0
//      Uw  Vw  0  0

SetTransform(D3DTS_TEXTURE0, &M);

큐브 환경 맵에 의한 환경 매핑을 실행한다

  • D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR 플래그를 사용해, 큐브 맵용의 반사 벡터로서 텍스쳐 좌표를 자동적으로 생성한다.
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR);
  • 래스터라이저에, 3 개의 요소를 가지는 텍스쳐 좌표를 사용하도록 지시한다.
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT3);

투영 텍스쳐를 실행한다

  • D3DTSS_TCI_CAMERASPACEPOSITION 플래그를 사용해, 텍스쳐 트랜스 폼에 버텍스 위치 좌표를 입력으로서 건네준다.
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION);
  • 텍스쳐 투영 행렬을 생성 해 적용한다. 이것은 문서의 대상외이며, 그 외의 시판 제품으로 취급하는 내용이다.
  • 래스터라이저에 3 개의 요소를 가지는 투영 텍스쳐 좌표를 사용하도록 지시한다.
    // 2 개의 출력 좌표를 사용한다.
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTF_PROJECTED | D3DTTFF_COUNT3);


텍스쳐 리소스

여기에서는, 텍스쳐 인터페이스 포인터에 의한 생성 및 렌더링에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 텍스쳐 표면 오브젝트의 취득
  • 텍스쳐 리소스를 사용한 렌더링


텍스쳐 표면 오브젝트의 취득

텍스쳐 리소스는,IDirect3DTexture8 인터페이스에 이행 되고 있다. 텍스쳐 인터페이스에의 포인터를 취득하려면 ,IDirect3DDevice8::CreateTexture 메소드인가, 다음의 몇개의 D3DX 함수를 호출한다.

  • D3DXCreateTexture
  • D3DXCreateTextureFromFileA
  • D3DXCreateTextureFromFileExA
  • D3DXCreateTextureFromFileExW
  • D3DXCreateTextureFromFileInMemory
  • D3DXCreateTextureFromFileInMemoryEx
  • D3DXCreateTextureFromFileW
  • D3DXCreateTextureFromResourceA
  • D3DXCreateTextureFromResourceExA
  • D3DXCreateTextureFromResourceExW
  • D3DXCreateTextureFromResourceW

다음의 코드에서는,D3DXCreateTextureFromFileA 를 사용해, Tiger.bmp 라고 하는 파일로부터 텍스쳐를 로드한다.

// 다음의 코드에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.

LPDIRECT3DTEXTURE8 pTexture;

D3DXCreateTextureFromFile( d3dDevice, "tiger.bmp", &pTexture);

D3DXCreateTextureFromFile 가 받는 제 1 파라미터는,IDirect3DDevice8 인터페이스에의 포인터이다. 제 2 파라미터는, 로드하는 텍스쳐가 들어가 있는 파일명을 Microsoft® Direct3D® 에 지시한다. 제 3 파라미터는, 생성 된 텍스쳐 오브젝트를 나타내는 IDirect3DTexture8 인터페이스에의 포인터의 주소로 한다.


텍스쳐 리소스를 사용한 렌더링

Microsoft® Direct3D® 에서는, 텍스쳐 스테이지라고 하는 개념을 이용해 멀티 텍스쳐 블렌딩을 지원 한다. 텍스쳐 스테이지 마다, 텍스쳐와 그 텍스쳐로 실행 가능한 처리가 있다. 텍스쳐 스테이지의 텍스쳐는, 경향 텍스쳐의 모임을 형성한다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것. 각 텍스쳐의 스테이트는, 그 텍스쳐 스테이지에 캡슐화된다.

C++ 어플리케이션에서는, 각 텍스쳐의 스테이트는 IDirect3DDevice8::SetTextureStageState 메소드로 설정할 필요가 있다. 제 1 파라미터의 값으로서 스테이지 번호 (0 ~ 7)를 건네준다. 제 2 파라미터의 값에는,D3DTEXTURESTAGESTATETYPE 열거형의 멤버를 설정한다. 마지막 파라미터는, 특정의 텍스쳐 스테이트에 대한 스테이트값이다.

텍스쳐 인터페이스 포인터를 사용해, 최대 8 개의 텍스쳐의 브렌드를 렌더링 할 수 있다. IDirect3DDevice8::SetTexture 메소드를 호출해 경향 텍스쳐를 설정한다. Direct3D 는, 렌더링 하는 프리미티브에 대해서, 경향 텍스쳐를 모두 브렌드 한다.

주 SetTexture 메소드는, 할당할 수 있는 텍스쳐 표면의 참조 카운트를 인크리먼트(increment) 한다. 텍스쳐가 불필요하게 되었을 경우, 해당하는 스테이지의 텍스쳐를 NULL 로 설정할 필요가 있다. 이것을 실시하지 않으면 표면이 해방되지 않고 메모리 누수가 발생한다.

IDirect3DDevice8::SetRenderState 메소드를 호출해, 경향 텍스쳐의 텍스쳐 랩핑 스테이트를 설정할 수 있다. 제 1 파라미터의 값으로서 D3DRS_WRAP0 ~ D3DRR_WRAP7 로부터 값을 1 개 건네준다. 또, D3DWRAPCOORD_0, D3DWRAPCOORD_1, D3DWRAPCOORD_2, 및 D3DWRAPCOORD_3 플래그의 편성을 사용해, u, v, 또는 w 방향의 랩핑을 유효하게 한다.

또, 텍스쳐 퍼스펙티브 스테이트와 텍스쳐 필터 링 스테이트를 설정할 수도 있다. 「텍스쳐 필터 링」 및 「텍스쳐 필터 링 스테이트」를 참조할것.


텍스쳐 필터 링

Microsoft® Direct3D® 는 프리미티브를 렌더링 하면 와, 3D 프리미티브를 2D 스크린에 매핑 한다. 프리미티브가 텍스쳐를 가지고 있는 경우, Direct3D 는 그 텍스쳐를 사용해, 프리미티브의 2D 렌더링 화면의 각 픽셀의 색을 생성해야 한다. 프리미티브의 스크린 위에의 화면의 모든 픽셀에 대해서, 텍스쳐로부터 칼라값을 취득해야 한다. 이 처리를텍스쳐 필터 링이라고 부른다.

텍스쳐 필터 링 처리를 실행 하면 와, 사용하는 텍스쳐는 보통 확대 또는 축소된다. 즉, 텍스쳐는, 그 자체보다 큰 또는 작은 프리미티브 화면에 매핑 된다. 텍스쳐의 확대에 의해, 다수의 픽셀이 1 개의 텍셀에 매핑 되는 일이 있다. 이 결과, 화면이 엉성해지는 일이 있다. 텍스쳐의 축소에서는, 많은 경우, 단일의 픽셀이 다수의 텍셀에 매핑 된다. 이 결과, 화면이 불선명하게 되거나 톱니 모양이 생기는 일이 있다. 이러한 문제를 해결하려면 , 픽셀의 색이 되도록(듯이) 텍셀색의 블렌딩을 실행할 필요가 있다.

Direct3D 에서는, 텍스쳐 필터 링의 복잡한 처리를 간소화한다. Direct3D 에서는, 선형 필터 링, 이방성 필터 링, 및 밉맵 필터 링의 3 종류의 텍스쳐 필터 링을 사용할 수 있다. 텍스쳐 필터 링을 선택하지 않는 경우, Direct3D 에서는 최근 포인트 샘플링이라고 하는 방법을 사용한다.

각각의 텍스쳐 필터 링에는, 장점과 단점이 있다. 예를 들어, 선형 텍스쳐 필터 링을 사용했을 경우, 최종적인 화면으로 엣지가 깔쭉깔쭉하게 되거나 화질이 엉성해지는 일이 있다. 그러나, 이 필터 링은 오버헤드가 적다. 밉맵에 의한 필터 링을 사용 하면, 보통은 최선의 결과를 얻을 수 있다. 특히, 이방성 필터 링과 조합해 사용했을 경우는 그렇다. 그러나, 이 필터 링은, Direct3D 가 지원 하는 방법 중(안)에서 가장 메모리를 필요로 하는 것이다.

텍스쳐 인터페이스 포인터를 사용하는 어플리케이션에서는,IDirect3Ddevice8::SetTextureStageState 메소드를 호출해 현재의 텍스쳐 필터 링 방법을 설정할 필요가 있다. 제 1 파라미터의 값을, 텍스쳐 필터 링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)로 설정한다. 제 2 파라미터로서 D3DTEXTUREMAGFILTER, D3DTEXTUREMINFILTER, 또는 D3DTEXTUREMIPFILTER 를 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다. 제 3 파라미터의 값으로서 D3DTEXTUREFILTERTYPE 열거형의 멤버를 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다.

여기에서는, Direct3D 로 지원 하는 텍스쳐 필터 링 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 최근점샘플링
  • 선형 텍스쳐 필터 링
  • 이방성 텍스쳐 필터 링
  • 밉맵에 의한 텍스쳐 필터 링

주 D3DRENDERSTATETYPE 열거형에 있는 텍스쳐 필터 링 스테이트는, 텍스쳐 스테이지 스테이트로 옮겨지고 있지만, 이 렌더링 스테이트를 사용해도,IDirect3DDevice2 버젼과는 대조적으로 IDirect3DDevice8::SetRenderState 의 실행이 실패할 것은 없다. 그 대신해, 시스템에서는, 이 렌더링 스테이트의 이펙트를 멀티 텍스쳐 cascade의 최초의 스테이지 (스테이지 0)에 매핑 한다. 어플리케이션에서는, 종래의 렌더링 스테이트를 그것과 대응하는 텍스쳐 스테이지 스테이트와 병용 하지 않는 것. 예기치 못한 결과가 생길 우려가 있다.


최근점샘플링

어플리케이션에서는, 이 텍스쳐 필터 링을 사용할 필요는 없다. Microsoft® Direct3D® 는, 텍셀 주소를 계산 (이 주소는 정수가 아닌 것이 많다)하거나 이 값에 가장 가까운 정수 주소를 가지는 텍셀의 색을 단지 카피하도록(듯이) 설정할 수 있다. 이 처리를 최근점샘플링이라고 부른다. 텍스쳐의 사이즈가 스크린 위에의 프리미티브의 화면의 사이즈와 거의 같은 경우에는, 이 방법에 따라 텍스쳐는 고속으로 효율적으로 처리할 수 있다. 양쪽 모두의 사이즈의 차이가 큰 경우는, 텍스쳐를 확대하거나 축소할 필요가 있다. 이러한 처리를 실행한 결과, 화면이 엉성해지거나 톱니 모양이 생기거나 불선명하게 되는 일이 있다.

C++ 어플리케이션에서는,IDirect3DDevice8::SetTextureStageState 메소드를 호출해 최근점샘플링을 선택할 수 있다. 제 1 파라미터의 값을, 텍스쳐 필터 링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)로 설정한다. 제 2 파라미터로서 D3DTEXTUREMAGFILTER, D3DTEXTUREMINFILTER, 또는 D3DTEXTUREMIPFILTER 를 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다. 제 3 파라미터의 값으로서 D3DTEXTUREFILTERTYPE 열거형의 멤버를 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다.

상세한 것에 대하여는, 「텍스쳐 필터 링 스테이트」를 참조할것.

최근점샘플링은 주의해 사용하는 것. 2 개의 텍셀간의 경계에서 텍스쳐가 샘플링 될 때, 경우에 따라서는 부자연스러운 그래픽스 효과가 생기는 일이 있다. 이 경계란, 샘플링 대상의 텍셀이 다음의 텍셀로 옮길 때의, 텍스쳐에 따른 위치 좌표 (u 또는 v)이다. 포인트 샘플링을 사용할때, 시스템에서는 샘플 텍셀을 1 개 선택하는지, 다른 텍셀을 선택한다. 이것에 의해, 경계가 교차하고 있을 때는 결과가 텍셀간에 갑자기 변화하는 일이 있다. 이 영향으로부터, 표시되는 텍스쳐안에, 바람직하지 않은 부자연스러운 그래픽스 이펙트가 나타나는 일이 있다. 선형 필터 링을 사용했을 경우, 결과 텍셀은 인접 텍셀간에 계산되어 텍스쳐 인덱스가 경계를 따라 옮기는데 따라서 매끄럽게 브렌드 된다.

이러한 이펙트는, 매우 작은 텍스쳐를 매우 큰 다각형에 매핑 하는 (많은 경우 "확대" 라고 부른다) 풀어에 발생할 가능성이 있다. 예를 들어, checker반과 같은 텍스쳐로 포인트 샘플링을 사용 하면, checker반은 확대되어 엣지가 두드러진다. 대조적으로, 선형 텍스쳐 필터 링을 사용했을 경우는, checker반의 색이 다각형 전체에 걸쳐서 매끄럽게 변화한 화면이 완성된다.

대부분의 경우, 최선의 결과를 얻기 위해서(때문에)는, 최근점샘플링의 사용을 가능한 한 피하도록(듯이) 한다. 최근의 하드웨어의 대부분은, 선형 필터 링용으로 최적화되고 있기 (위해)때문에, 퍼포먼스가 저하할 것은 없다. 다만, 텍스쳐를 사용해 읽기 쉬운 텍스트 문자를 표시하는 경우 등, 목적의 이펙트를 내기 위해서(때문에) 아무래도 최근점샘플링을 사용해야 하는 경우는, 텍셀 경계에서 샘플링을 실시하지 않게 유의하고 생각하지 않는 이펙트가 생기지 않게 세심의 주위를 기울일 필요가 있다. 다음의 그림은, 부자연스러운 그래픽스 효과가 어떠한 것인지를 나타내고 있다.

그룹내의 우상에 있는 2 개의 사각형이 인접하는 사각형과는 다른 것에 주의한다. 이것들에는 대각 오프셋(offset)가 있다. 이러한 부자연스러운 그래픽스 효과를 피하기 위해서(때문에)는, 우선 최근점필터 링에 관한 Direct3D 텍스쳐 샘플링 룰에 대해 이해할 필요가 있다. Direct3D 에서는,[0.0, 1.0] (0.0 ~ 1.0 까지 포함한다)의 범위내의 부동 소수점 텍스쳐 좌표를,[–0. 5, n – 0.5] 의 범위내의 정수 텍셀 공간값에 매핑 한다. 여기서,n 는 텍스쳐의 소정의 크기에서의 텍셀수이다. 결과의 텍스쳐 인덱스는, 가장 가까운 정수에 말 수 있다. 이 매핑에 의해, 텍스쳐 경계에서는 샘플링의 오차가 생기는 경우가 있다.

간단한 예로서 D3DTADDRESS_WRAP 텍스쳐 addressing mode로 다각형을 렌더링 하는 경우를 생각해 본다. Direct3D 의 매핑을 사용 하면,u 텍스쳐 인덱스는, 4 텍셀폭의 텍스쳐에 대해서, 다음과 같이 매핑 된다.

이 그림으로, 텍스쳐 좌표 0.0 으로 1.0 은, 텍셀간의 경계상에 정확하게 위치한다. Direct3D 의 매핑용의 메소드를 사용 하면, 텍스쳐 좌표는 [–0. 5, 4 – 0.5] 의 범위내에 매핑 된다. 여기서, 4 는 텍스쳐의 폭이다. 이 경우, 샘플링 되는 것은, 텍스쳐 인덱스 1.0 의 0 번째의 텍셀이다. 다만, 텍스쳐 좌표가 1.0 보다 조금 적은 경우에는, 샘플링 되는 것은 0 번째의 텍셀은 아니고,n 번째의 텍셀이 된다.

이것은, 즉, 텍스쳐 좌표 0.0 으로 1.0 을 가지는 작은 텍스쳐를, 스크린 공간에 배열된 삼각형상에서 최근점필터 링에 의해 확대하면(자), 그 결과, 텍스쳐 맵이 텍셀간의 경계에서 샘플링 될 때의 대상이 되는 픽셀이 된다, 라고 하는 의미이다. 텍스쳐 좌표의 계산의 오차가 몇 안 되는 경우여도, 텍스쳐 맵의 텍셀 엣지에 대응하는, 렌더링 화면의 영역을 따라 부자연스러운 효과가 나타난다.

이와 같이 부동 소수점 텍스쳐 좌표를 정수 텍셀에 완벽하게 정확하게 매핑 하는 것은, 곤란한 작업이며, 계산 부하도 크지만, 이러한 처리를 일반적으로는 실시할 필요는 없다. 대부분의 하드웨어 이행에서는, 삼각형내의 각 픽셀 위치 좌표에 있어서의 텍스쳐 좌표의 계산에 반복 처리를 이용한다. 이 방법을 사용 하면, 보간 처리간에 오차가 균등하게 누적되어 가기 위해, 이러한 오차가 얼마 정도는 눈에 띄지 않게 된다.

Direct3D 레퍼런스 래스터라이저에서는, 각 픽셀 위치 좌표에서의 텍스쳐 인덱스의 계산에 직접 평가법을 이용한다. 직접 평가는 반복 처리와는 달라, 처리 위에의 오차가 보다 랜덤인 에러 분포를 나타낸다. 이 결과, 경계상에서는 보다 현저한 샘플링 에러가 발생한다. 이것은, 레퍼런스 래스터라이저에 의해 이 처리가 정확하게 실행되지 않기 때문이다

최근점필터 링은, 필요한 경우에게만 사용 하면이야 있고. 이것을 사용할 필요가 있는 경우는, 텍스쳐 좌표를 경계 위치 좌표로부터 약간 오프셋(offset) 해 부자연스러운 효과의 발생을 막는 것이 추천 된다.


선형 텍스쳐 필터 링

Microsoft® Direct3D® 에서는, 바이리니아피르타링으로 불리는 선형 텍스쳐 필터 링을 사용한다. 최근점샘플링과 같이, 바이리니아테크스체피르타링에서는 최초로 텍셀 주소를 계산하지만, 보통, 이 값이 정수 주소가 될 것은 없다. 바이리니아피르타링에서는, 계산한 주소에 가장 가까운 정수 주소를 가지는 텍셀이 검색된다. 게다가 Direct3D 렌더링 모듈에서는, 샘플링 한 최근점의 상하 좌우에 있는 텍셀의 가중평균을 계산한다.

IDirect3DDevice8::SetTextureStageState 메소드를 호출해, 바이리니아테크스체피르타링을 선택한다. 제 1 파라미터의 값을, 텍스쳐 필터 링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)로 설정한다. 제 2 파라미터로서 D3DTEXTUREMAGFILTER, D3DTEXTUREMINFILTER, 또는 D3DTEXTUREMIPFILTER 를 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다. 제 3 파라미터를 D3DTEXF_LINEAR 로 설정한다. 상세한 것에 대하여는, 「텍스쳐 필터 링 스테이트」를 참조할것.


이방성 텍스쳐 필터 링

이방성이란, 스크린 평면에 대해서 각도를 이루어 위치한 표면을 가지는 3D 오브젝트의 텍셀의 가시적인 왜곡이다. 이방성 프리미티브로부터의 픽셀을 텍셀에 매핑 하면 와, 프리미티브의 형상이 뒤틀린다. Microsoft® Direct3D® 에서는, 텍스쳐 공간에 역매핑 되는 스크린 픽셀의 신장도 (길이÷폭)로서 픽셀의 이방성을 측정한다.

이방성 텍스쳐 필터 링은, 선형 텍스쳐 필터 링 또는 밉맵 텍스쳐 필터 링과 병용 하는 것으로, 렌더링 결과를 향상시킬 수가 있다. IDirect3DDevice8::SetTextureStageState 메소드를 호출해, 이방성 텍스쳐 필터 링을 유효하게 한다. 제 1 파라미터의 값을, 텍스쳐 필터 링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)로 설정한다. 제 2 파라미터로서 D3DTEXTUREMAGFILTER, D3DTEXTUREMINFILTER, 또는 D3DTEXTUREMIPFILTER 를 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다. 제 3 파라미터를 D3DTEXF_ANISOTROPIC 로 설정한다. 상세한 것에 대하여는, 「텍스쳐 필터 링 스테이트」를 참조할것.

또, 이방성의 정도를 제로보다 큰 값으로 설정할 필요가 있다. 이것을 설정하려면 ,IDirect3DDevice8::SetTextureStageState 메소드를 호출한다. 제 1 파라미터에는, 이방성의 정도를 설정하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)를 설정한다. 제 2 파라미터에는, D3DTSS_MAXANISOTROPY 를 건네준다. 마지막 파라미터는, 이방성의 정도가 아니면 안된다.

이방성의 정도를 1 으로 설정 하면, 이방성 필터 링이 무효가 되어, 1 보다 큰 값을 설정 하면, 이방성 필터 링이 유효하게 된다. 이방성의 정도로서 설정 가능한 값의 범위를 판별하려면 ,D3DCAPS8 구조체의 MaxAnisotropy 플래그를 체크한다.


밉맵에 의한 텍스쳐 필터 링

밉맵 텍스쳐는, 장면의 렌더링에 필요한 시간을 단축하기 위해서 3D 신으로 사용된다. 또, 밉맵 텍스쳐를 사용 하면, 장면의 리얼리티가 늘어난다. 그러나, 밉맵 텍스쳐를 사용하려면 메모리가 대량으로 필요한 것이 많다.

여기에서는, 3D 신에서의 밉맵 텍스쳐의 사용에 관한 기본 사항에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 밉맵이란
  • 밉맵 세트의 생성
  • 밉맵의 선택과 표시


밉맵이란

밉맵과는 연속한 텍스쳐로, 각 텍스쳐는 같은 화면을 서서히 저해상도로 한 것이다. 밉맵에서의 각 화면의 높이와 폭, 즉 레벨은, 직전의 레벨보다 2 의 거듭제곱만 작다. 밉맵은 정방형일 필요는 없다.

유저에게 가까운 오브젝트에는, 고해상도 밉맵 화면이 사용된다. 오브젝트가 멀어지는에 따라, 저해상도의 밉맵 화면이 사용된다. 밉맵 처리에 의해, 렌더링 한 텍스쳐의 품질이 향상하지만, 사용하는 메모리는 증가한다.

Microsoft® Direct3D® 에서는, 밉맵은 어태치 된 표면의 체인으로서 나타내진다. 이 체인의 선두에는 최고 해상도의 텍스쳐가 있어, 그 후에는 다음의 밉맵 레벨의 텍스쳐가 계속된다. 이 레벨의 뒤에는 다음의 레벨의 밉맵이 계속된다, 라고 하는 순으로 최저 해상도의 밉맵이 될 때까지 계속되어 간다.

다음의 그림은, 이러한 레벨의 예를 나타내고 있다. 비트 맵 텍스쳐는, 대면형의 게임의 3D 컨테이너의 측면에 있는 기호를 나타내고 있다. 밉맵으로서 생성 하면, 최고 해상도의 텍스쳐가 이 세트의 선두에 온다. 이 밉맵 세트가 연속하는 각 텍스쳐는, 높이와 폭이 2 의 거듭제곱씩 작게 되어 간다. 이 경우, 최고 해상도의 밉맵은 256x256 픽셀이다. 다음의 텍스쳐는 128x128 이다. 마지막 텍스쳐는 64x64 이다.

이 기호는 가시 범위내의 최대 거리에 있다. 이 기호로부터 멀게 멀어진 위치로부터 게임을 시작 하는 경우, 밉맵 체인 중(안)에서 최소의 텍스쳐 (이 경우 64x64 텍스쳐)가 표시된다.

유저의 시점이 이 기호에 가까워지는 것에 따라, 서서히 고해상도의 텍스쳐가 사용된다. 다음의 그림의 해상도는 128x128 이다.

최고 해상도의 텍스쳐가 사용되는 것은, 플레이어의 시점이 이 기호에 가장 가까워졌을 때이다.

이것은, 텍스쳐의 퍼스펙티브를 시뮬레이트 하는 방법 중(안)에서는 오버헤드가 낮은 방법이다. 1 개의 텍스쳐를 많은 해상도로 렌더링 하는 것보다도, 다양한 해상도로 복수의 텍스쳐를 사용하는 (분)편이 고속으로 있다.

Direct3D 에서는, 밉맵 세트 중(안)에서 어느 텍스쳐가 가장 목적 출력에 가까운 해상도인지를 평가해, 픽셀을 그 텍셀 공간에 매핑 할 수 있다. 최종적인 화면의 해상도가 밉맵 세트내의 텍스쳐간에 있는 경우, Direct3D 에서는 양쪽 모두의 밉맵의 텍셀을 조사해 그 칼라값을 브렌드 한다.

밉맵을 사용하려면 , 어플리케이션으로 밉맵세트를 생성 할 필요가 있다. 상세한 것에 대하여는, 「밉맵 세트의 생성」을 참조할것. 어플리케이션에서는, 밉맵 세트를 경향 텍스쳐 세트의 최초의 텍스쳐로서 선택해, 밉맵을 적용한다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.

다음에, Direct3D 로 텍셀의 샘플링에 사용하는 필터 링 방법을 설정해야 한다. 가장 처리가 빠른 밉맵 필터 링은, Direct3D 로 가장 가까운 텍셀을 선택하는 방법이다. 이것 선택하려면 , D3DTFP_POINT 열거값을 사용한다. Direct3D 에서는, D3DTFP_LINEAR 열거값을 사용 하면, 보다 고품질인 필터 링 결과를 얻을 수 있다. 이 필터 링에서는, 가장 가까운 밉맵이 선택되어 다음에 현재의 픽셀이 매핑 되는, 텍스쳐내의 위치 좌표의 주변 텍셀의 가중평균이 계산된다.


밉맵 세트의 생성

다음의 예는,IDirect3DDevice8::CreateTexture 메소드를 호출해, 사이즈 256 × 256, 128 × 128, 64 × 64, 32 × 32, 및 16 × 16 의 5 개의 밉맵 레벨의 체인을 생성 하는 방법을 나타내고 있다.

// 이 샘플 코드에서는, 변수 d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.

IDirect3DTexture8 * pMipMap;

d3dDevice->CreateTexture(256, 256, 5, 0, D3DFMT_R8G8B8, D3DPOOL_MANAGED, &pMipMap);

CreateTexture 가 받는 최초의 2 개의 파라미터는, 최상정도 텍스쳐의 사이즈와 폭이다. 제 3 파라미터에는, 텍스쳐의 레벨수를 지정한다. 이 파라미터를 제로로 설정 하면, Microsoft® Direct3D® 는 표면의 체인을 생성 한다. 각 표면은, 직전의 표면보다 2 의 거듭제곱씩 작아져, 최종적으로 1 × 1 의 최소 사이즈가 된다. 제 4 파라미터에는, 이 리소스의 사용 방법을 지정한다. 여기에서는 제로가 지정되고 있으므로, 리소스에는 특정의 사용 방법은 없는 것을 나타낸다. 제 5 파라미터에는, 텍스쳐의 표면 포맷을 지정한다. 이 파라미터에는,D3DFORMAT 열거형의 값을 사용한다. 제 6 파라미터에는, 생성 한 리소스를 배치하는 메모리 클래스를 나타내는 D3DPOOL 열거형의 멤버를 지정한다. 동적 텍스쳐를 사용하고 있으므로 않으면, D3DPOOL_MANAGED 를 권한다. 마지막 파라미터는,IDirect3DTexture8 인터페이스에의 포인터의 주소로 한다.

주 밉맵 체인의 각 표면의 크기는, 직전의 표면의 반이 된다. 최상정도 밉맵의 크기가 256 × 128 의 경우, 2 번째의 레벨의 밉맵의 크기는 128 × 64 가 되어, 3 번째의 레벨은 64 × 32 라고 하는 순으로 밉맵의 크기는 작아져, 최종적으로는 1 × 1 이 된다. Levels 로 밉맵 레벨의 수를 지정할 수 없다. Levels 에서는, 체인의 밉맵의 폭 또는 높이중 한쪽이 1 보다 작아지는 일이 있다. 4 × 2 를 최상정도 밉맵 표면으로 하는 단순한 케이스에서는,Levels 의 최대치는 3 이 된다. 최상정도의 크기는 4 × 2 로, 다음의 레벨의 크기는 2 × 1 으로, 그 다음의 레벨의 크기는 1 × 1 이다. Levels 의 값이 3 보다 크면 제 2 레벨의 밉맵의 높이는 분수가 된다. 따라서, 이것은 허가되지 않는다.


밉맵의 선택과 표시

IDirect3DDevice8::SetTexture 메소드를 호출해, 경향 텍스쳐의 일람내의 선두의 텍스쳐로서 밉맵 텍스쳐를 설정한다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.

밉맵 텍스쳐 세트를 선택한 후,D3DTEXTUREFILTERTYPE 열거형으로부터의 값을 D3DTSS_MIPFILTER 텍스쳐 스테이지 스테이트에 할당하지 않으면 안 된다. Microsoft® Direct3D® 에서는 밉맵 텍스쳐 필터 링을 자동적으로 실행한다. 다음의 샘플 코드에서는, 밉맵 텍스쳐 필터 링이 유효하게 되고 있다.

d3dDevice->SetTexture(0, pMipMap);
d3dDevice->SetTextureStageState(0, D3DTSS_MIPFILTER, D3DTEXF_POINT);

또,IDirect3DTexture8::GetSurfaceLevel 메소드를 사용해, 취득하는 밉맵 레벨을 지정하는 것으로, 밉맵 표면의 체인을 수동으로 암벽 횡단 할 수 있다. 다음의 예에서는, 최고 해상도로부터 최저 해상도까지 밉맵 체인을 암벽 횡단 한다.

IDirect3DSurface8 * pSurfaceLevel;

for (int iLevel = 0; iLevel < pMipMap->GetLevelCount(); iLevel++)
{
    pMipMap->GetSurfaceLevel(iLevel, &pSurfaceLevel);

    //이 레벨을 처리한다.

    pSurfaceLevel->Release();
}

체인의 밉맵 표면의 각 표면에 비트 맵 데이터를 로드하기 위해서(때문에), 어플리케이션에서는 밉맵 체인을 수동으로 암벽 횡단 할 필요가 있다. 보통, 이 이유로부터 체인을 암벽 횡단 한다. 어플리케이션은,IDirect3DBaseTexture8::GetLevelCount 를 호출해, 밉맵에 저장 되고 있는 레벨의 수를 취득할 수 있다.


텍스쳐 랩핑

여기에서는, 3D 프리미티브에의 텍스쳐 랩핑에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 텍스쳐 랩핑이란
  • 텍스쳐 랩핑의 사용법

주 텍스쳐 랩핑과 유사한 이름의 텍스쳐 addressing mode를 혼동 하지 않는 것. 상세한 것에 대하여는, 「텍스쳐 addressing mode와 텍스쳐 랩핑」 및 「텍스쳐 addressing mode」를 참조할것.


텍스쳐 랩핑이란

간단하게 말하면, 텍스쳐 랩핑이란, Microsoft® Direct3D® 로 각 버텍스에 대해서 지정된 텍스쳐 좌표를 사용해, 텍스쳐 처리한 다각형을 라스터화할 때의 기본적인 방법을 변경하는 처리이다. 다각형의 라스터화중에, 시스템은 다각형의 각 버텍스의 텍스쳐 좌표의 사이를 보간 해, 다각형의 모든 픽셀에 사용하는 텍셀을 결정한다. 보통, 시스템은 텍스쳐를 2D 평면으로서 취급해, 텍스쳐내의 포인트 A 로부터 포인트 B 까지의 최단 경로를 잡는 것으로 새로운 텍셀을 보간 한다. 포인트 A 가 u, v 위치 좌표 (0.8, 0,1)로, 포인트 B 가 (0.1,. 9)의 경우, 보간의 선은 다음의 그림과 같이 된다.

위에의도에서는, AB 간의 최단 거리가 텍스쳐의 거의 중앙을 지나고 있다. u 또는 v 의 텍스쳐 좌표의 랩핑을 유효하게 하면, u 및 v 방향에서의 텍스쳐 좌표간의 최단 경로를 Direct3D 가 인식할 방법이 변화한다. 정의에서는, 0.0 으로 1.0 이 같은 위치 좌표를 차지하면(자) 가정해, 텍스쳐 랩핑에 의해 래스터라이저가 텍스쳐 좌표간의 최단 경로를 잡는다. 마지막 비트는 취급하기 어렵지만, 다음과 같이 생각하면(자) 알기 쉽다. 한방향의 텍스쳐 랩핑을 유효하게 하면, 시스템은 텍스쳐가 마치 원기둥(실린더)의 주위에 감겨 있는 것과 같게 텍스쳐를 취급한다. 예를 들어, 다음의 그림을 생각한다.

위에의도는, u 방향의 랩핑에 의해, 시스템에 의한 텍스쳐 좌표의 보간 방법이 어떻게 변화하는지를 나타내고 있다. 이 예로 사용한 같은 점을, 정상적인 또는 휘감지 않은 텍스쳐에 사용 하면, 점 A 와 B 의 최단 거리가 텍스쳐가 중심으로 없는 것을 안다. 이 경우, 최단 거리는 0.0 으로 1.0 이 모두 위치하는 경계를 지나고 있다. v 방향의 랩핑도 마찬가지이다. 다만, 측면이 아래가 되어 있는 원기둥(실린더)의 주위에 텍스쳐가 감기고 있다. u 및 v 의 양방향의 랩핑의 경우는 한층 더 복잡하다. 이 경우는 원환, 즉 도너츠를 상상 하면이야 있고.

텍스쳐 랩핑을 실제로 사용한 가장 일반적인 어플리케이션은, 환경 매핑의 실행이다. 보통, 환경 매핑으로 텍스쳐 처리한 오브젝트는 매우 반사적이며, 장면의 오브젝트의 주위에 화면이 반영한다. 이것을 설명하기 위해(때문에), 사방이 벽에서 둘러싸인 방을 생각한다. 벽에는 각각 R, G, B, 및 Y 라고 하는 문자가 붙여 있어, 거기에 대응하는 적색, 녹색, 청색, 및 황색으로 칠해지고 있다. 이러한 단순한 방의 환경 매핑이면, 다음과 같이 된다.

이 방의 천정이, 4 면으로부터 되는 매우 반사하기 쉬운 기둥에서 유지되고 있다고 한다. 이 기둥에 환경 매핑을 실행하는 것은 매우 간단하다. 그러나, 벽의 문자와 색이 기둥에 반사하고 있도록(듯이) 보이게 하는 것은 간단한 것은 아니다. 다음의 그림은, 윗쪽의 버텍스의 가까이의 텍스쳐 좌표를 적용한, 기둥의 와이어 프레임을 나타내고 있다. 랩핑이 이 텍스쳐의 엣지를 횡단하는 「연결고리」는, 점선으로 가리킨다.

u 방향으로 랩핑이 유효하게 되어 있으므로, 텍스쳐 처리한 기둥에는, 환경 매핑으로부터의 색과 심볼이 올바르게 표시되고 있어 텍스쳐의 전면의 연결고리에서는, 래스터라이저가 텍스쳐 좌표간의 최단 경로를 올바르게 선택하고 있다 (u 좌표 0.0 으로 1.0 이 같은 위치를 차지한다고 하는 전제). 텍스쳐를 적용한 기둥은, 다음의 그림에 나타내게 된다.

텍스쳐 랩핑이 유효하지 않은 경우, 래스터라이저는, 실물과 같이 반사한 화면을 생성하기 위해서 필요한 방향으로 보간을 실시하지 않는다. 반대로, 기둥의 전면 부분에서는, u 좌표의 0.175 및 0.875 간의 텍셀이, 텍스쳐의 중심을 통과할 때 수평 방향으로 압축되어 랩 이펙트는 무너진다.


텍스쳐 랩핑의 사용법

텍스쳐 랩핑을 유효하게 하려면 , 다음의 샘플 코드에 나타내도록(듯이),IDirect3DDevice8::SetRenderState 메소드를 호출한다.

d3dDevice->SetRenderState(D3DRS_WRAP0, D3DWRAPCOORD_0);

SetRenderState 가 받는 제 1 파라미터는, 설정하는 렌더링 스테이트이다. 랩핑을 설정하는 텍스쳐 레벨을 지정하는 D3DRS_WRAP0 ~ D3DRS_WRAP7 의 열거값의 어느쪽이든을 지정한다. 제 2 파라미터에 D3DWRAPCOORD_0 ~ D3DWRAPCOORD_3 플래그를 지정해, 대응할 방향의 텍스쳐 랩핑을 유효하게 하는지, 이러한 플래그를 조합해 복수의 방향의 랩핑을 유효하게 한다. 플래그를 생략 하면, 대응할 방향에서의 텍스쳐 랩핑이 무효가 된다. 텍스쳐 좌표세트에 대해서 텍스쳐 랩핑을 무효로 하려면 , 대응하는 렌더링 스테이트의 값을 0 으로 설정한다.


텍스쳐 블렌딩

Microsoft® Direct3D® 에서는, 텍스쳐를 프리미티브의 색과 브렌드 해 투명 이펙트를 생성할 수 있다. 또, 복수의 텍스쳐를 1 개의 원시적으로 브렌드 할 수도 있다. 여기에서는, 텍스쳐 블렌딩의 실행 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 알파 텍스쳐 블렌딩
  • 멀티 패스 텍스쳐 블렌딩
  • 멀티 텍스쳐 블렌딩
  • 텍스쳐에 의한 라이트 매핑

텍스쳐 블렌딩을 사용하는 경우, 유저의 하드웨어가 텍스쳐 블렌딩을 지원 하고 있을지 어떨지를 최초로 조사할 필요가 있다. 이러한 정보는,D3DCAPS8 구조체의 TextureCaps 멤버에 보관 유지되고 있다. 텍스쳐 블렌딩 기능에 대해 유저의 하드웨어에 문의하는 방법의 상세한 것에 대하여는, 「IDirect3DDevice8::GetDeviceCaps 」를 참조할것.


알파 텍스쳐 블렌딩

Microsoft® Direct3D® 에서는, 프리미티브를 렌더링 하면 와, 프리미티브의 머트리얼 또는 그 버텍스의 색, 및 라이팅 정보에 근거해 프리미티브의 색을 생성한다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 개요」를 참조할것. 어플리케이션으로 텍스쳐 블렌딩이 유효하게 되어 있는 경우, Direct3D 는 처리된 다각형의 픽셀 칼라의 값을, 이미 frame buffer에 저장 되고 있는 픽셀과 조합하지 않으면 안 된다. Direct3D 에서는, 다음의 공식을 사용해, 프리미티브의 화면의 각 픽셀에 대한 최종색을 결정한다.

FinalColor = TexelColor × SourceBlendFactor + PixelColor × DestBlendFactor

이 공식에서,FinalColor 는, 타겟 렌더링 표면에 출력되는 마지막 픽셀 칼라이다. TexelColor 는, 경향 픽셀에 대응하는 입력 칼라값 (텍스쳐 필터 링 후)을 나타낸다. Direct3D 로 텍셀을 픽셀에 매핑 하는 방법의 상세한 것에 대하여는, 「텍스쳐 필터 링」을 참조할것. SourceBlendFactor 는, 마지막에 적용하는 입력 칼라값의 비율을 결정하기 위해서(때문에) Direct3D 가 사용하는 계산값이다. PixelColor 는, 프리미티브의 화면내에 현재 저장 되고 있는 픽셀의 색이다. DestBlendFactor 는, 마지막에 렌더링 되는 픽셀로 사용되는 경향 픽셀의 색의 비율을 나타낸다. SourceBlendFactor 와 DestBlendFactor 의 값은, 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 이다.

위에의 공식으로부터 알도록(듯이),SourceBlendFactor 가 D3DBLEND_ONE 으로 DestBlendFactor 가 D3DBLEND_ZERO 의 경우, 마지막에 렌더링 되는 픽셀은 투명도가 없는 것으로서 렌더링 된다. SourceBlendFactor 가 D3DBLEND_ZERO 로 DestBlendFactor 가 D3DBLEND_ONE 의 경우는, 텍스쳐는 완전하게 투명하게 된다. 이러한 계수에 상기 이외의 값을 설정했을 경우는, 마지막에 렌더링 되는 픽셀은 어느 정도의 투명성이 있는 색과 브렌드 된다.

텍스쳐 필터 링 후는, 모든 픽셀 칼라값은, 적색, 녹색, 및 청색의 칼라값을 가지고 있다. 디폴트에서는, Direct3D 는 D3DBLEND_SRCALPHA 를 SourceBlendFactor 으로서 D3DBLEND_INVSRCALPHA 를 DestBlendFactor 로서 사용한다. 따라서, 어플리케이션에서는, 텍스쳐의 알파값을 설정하는 것으로 처리된 픽셀의 투명도를 제어할 수 있다.

C++ 로 개발하는 어플리케이션에서는, D3DRS_SRCBLEND 및 D3DRS_DESTBLEND 렌더링 스테이트를 사용해 블렌딩 계수를 제어한다. IDirect3DDevice8::SetRenderState 메소드를 호출해, 제 1 파라미터의 값으로서 렌더링 스테이트값의 어느쪽이든을 건네준다. 제 2 파라미터는,D3DBLEND 열거형의 멤버가 아니면 안된다.


멀티 패스 텍스쳐 블렌딩

Microsoft® Direct3D® 어플리케이션에서는, 멀티 렌더링 패스로 원시적으로 각종 텍스쳐를 적용해, 수많은 특수 효과를 실현할 수 있다. 이 처리는 일반적으로멀티 패스 텍스쳐 블렌딩으로 불린다. 멀티 패스 텍스쳐 블렌딩의 일반적인 용도는, 몇개의 다른 텍스쳐로부터 복수의 색을 적용해, 복잡한 라이팅 및 쉐이딩 모델의 이펙트를 에뮤레이트 하는 것이다. 이것을 라이트 매핑이라고 부른다. 상세한 것에 대하여는, 「텍스쳐에 의한 라이트 매핑」을 참조할것.

주 디바이스에 따라서는, 단일의 패스로, 복수의 텍스쳐를 원시적으로 적용할 수 있는 경우도 있다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.

유저의 하드웨어로 멀티 텍스쳐 블렌딩이 지원되어 있지 않은 경우에서도, 어플리케이션에서는, 멀티 패스 텍스쳐 블렌딩을 사용해 같은 시각 이펙트를 실현할 수 있다. 다만, 멀티 텍스쳐 블렌딩을 사용했을 경우에는, 어플리케이션은 가능한 frame rate를 유지할 수 없다.

C++ 어플리케이션으로 멀티 텍스쳐 블렌딩을 실행하려면

  1. IDirect3DDevice8::SetTexture 메소드를 호출해, 텍스쳐 스테이지 0 에 텍스쳐를 설정한다.
  2. IDirect3DDevice8::SetTextureStageState 메소드를 사용해, 목적의 색 및 알파 블렌딩 인수와 처리를 선택한다. 멀티 패스 텍스쳐 블렌딩용의 최적인 설정은 디폴트 설정이다.
  3. 장면내의 적절한 오브젝트를 렌더링 한다.
  4. 다음의 텍스쳐를 텍스쳐 스테이지 0 으로 설정한다.
  5. D3DRS_SRCBLEND 및 D3DRS_DESTBLEND 렌더링 스테이트를 설정해, 브렌드원 및 브렌드처의 블렌딩 계수를 필요에 따라서 조정한다. 이러한 파라미터에 근거해, 새로운 텍스쳐가 렌더링 타겟 표면내의 기존의 픽셀로 브렌드 된다.
  6. 필요에 따라서, 다른 텍스쳐에 대해서 순서 3, 4, 및 5 를 반복한다.


멀티 텍스쳐 블렌딩

Microsoft® Direct3D® 에서는, 단일의 패스로, 최대 8 개의 텍스쳐를 원시적으로 브렌드 할 수 있다. 멀티 텍스쳐 블렌딩을 사용하면, Direct3D 어플리케이션의 frame rate를 큰폭으로 올릴 수가 있다. 어플리케이션은, 멀티 텍스쳐 블렌딩을 채용해, 텍스쳐, 그림자, 스펙큐러 라이트, 디퓨즈 라이트등의 특수 효과를 단일 패스로 적용할 수 있다.

멀티 텍스쳐를 브렌드 하려면 , 어플리케이션으로 그러한 텍스쳐를 경향 텍스쳐 세트에 할당해 다음에블렌딩 스테이지를 생성 한다. 이하의 주제에서는, 이러한 순서의 실행 방법에 대해 설명한다.

  • 텍스쳐 스테이지와 텍스쳐 블렌딩 cascade
  • 텍스쳐 블렌딩 처리와 인수
  • 경향 텍스쳐의 할당
  • 블렌딩 스테이지의 생성


텍스쳐 스테이지와 텍스쳐 블렌딩 cascade

Microsoft® Direct3D® 는,텍스쳐 스테이지를 사용해, 싱글 패스의 멀티 텍스쳐 블렌딩을 지원 하고 있다. 텍스쳐 스테이지에는 2 개의 인수를 받아, 블렌딩 처리를 실시해, 후속의 처리 또는 라스터화에 결과를 건네준다. 텍스쳐 스테이지는, 다음의 그림과 같이 도식화할 수 있다.

위에의도에 나타내도록(듯이), 텍스쳐 스테이지는 지정의 오퍼레이터를 사용해 2 개의 인수를 브렌드 한다. 일반적인 조작에는, 인수의 색 또는 알파 요소의 단순 변조나 가산이 있지만, 20 이상의 조작이 지원 되고 있다. 스테이지의 인수는, 관련지을 수 있었던 텍스쳐, 보간색 또는 보간 알파 (gouraud shading중의 보간), 임의의 색과 알파, 또는 이전의 텍스쳐 스테이지로부터의 결과이다. 상세한 것에 대하여는, 「텍스쳐 블렌딩 처리와 인수」를 참조할것.

주 Direct3D 에서는, 칼라 블렌딩과 알파 블렌딩을 구별한다. 어플리케이션에서는, 색과 알파에 대해서 개별적으로 블렌딩 처리와 인수를 설정해, 이러한 설정이 서로의 결과에 영향을 줄 것은 없다.

멀티 블렌딩 스테이지에서 사용되는 인수와 처리의 편성은, 단순한 플로우를 기본으로 하는 블렌딩 언어를 정의한다. 1 개의 스테이지의 결과는 다른 스테이지에 흘러 다음에 그 스테이지의 결과가 다음의 스테이지에 흘러 이하와 같이 계속된다. 스테이지에서 스테이지에의 흐름이 최종적으로 다각형상에서 라스터화 되는 개념을, 보통,텍스쳐 블렌딩 cascade라고 부른다. 다음의 그림은, 개별의 텍스쳐 스테이지가 어떻게 텍스쳐 블렌딩 cascade를 구성하는지를 나타내고 있다.

디바이스내의 각 스테이지는, 0 으로부터 시작되는 인덱스를 가진다. Direct3D 에서는, 최대 8 개의 블렌딩 스테이지를 이용할 수 있다. 다만, 현재의 하드웨어로 지원 되는 스테이지수를 판단하기 위해서(때문에), 디바이스 기능을 조사할 필요가 있다. 제 1 블렌딩 스테이지는 인덱스 0 에 있어, 제 2 스테이지는 인덱스 1 에 있어, 이하 인덱스 7 까지 같이이다. 시스템은, 인덱스의 승순에 스테이지를 브렌드 한다.

필요한 수만의 스테이지를 사용한다. 사용하지 않는 블렌딩 스테이지는 디폴트로 무효가 된다. 어플리케이션이 최초의 2 개의 스테이지만을 사용하는 경우는, 스테이지 0 으로 1 에 관해서만 설정 조작과 인수가 필요하다. 시스템은 2 개의 스테이지를 브렌드 해, 무효인 스테이지를 무시한다.

최적화에 관한 주의 오브젝트에 따라서는 4 개의 스테이지를 사용하거나 2 개의 스테이지를 사용하는 등, 상황에 따라 어플리케이션으로 사용하는 스테이지의 수가 바뀌는 경우는, 이전에 사용한 모든 스테이지를 명시적으로 무효로 하지 않아도 좋다. 최초의 미사용의 스테이지에 대해서 칼라 처리를 무효로 해도, 그것보다 인덱스가 큰 스테이지에서는 무효가 되지 않는다. 칼라 처리를 최초의 텍스쳐 스테이지 (스테이지 0)로 설정 하면, 모든 텍스쳐 매핑을 무효로 할 수 있다.


텍스쳐 블렌딩 처리와 인수

어플리케이션에서는, 블렌딩 스테이지를 경향 텍스쳐 세트의 각 텍스쳐에 관련짓는다. 「텍스쳐 스테이지와 텍스쳐 블렌딩 cascade」로 설명하도록(듯이),Microsoft® Direct3D® 에서는, 세트의 최초의 텍스쳐로부터 순서에 8 번째의 텍스쳐까지 각 블렌딩 스테이지를 평가한다.

Direct3D 에서는, 경향 텍스쳐 세트의 각 텍스쳐의 정보를, 관련지을 수 있고 있는 블렌딩 스테이지에 적용한다. 어플리케이션에서는,IDirect3DDevice8::SetTextureStageState 를 호출해, 소정의 텍스쳐 스테이지로부터 어느 정보를 사용하는지를 제어한다. 칼라 채널과 알파 채널의 처리는, 개별적으로 설정할 수가 있다. 각 처리에서는 2 개의 인수를 사용한다. 칼라 채널 처리를 지정하려면 , D3DTSS_COLOROP 스테이지 스테이트를 사용해, 알파 처리를 지정하려면 , D3DTSS_ALPHAOP 스테이지 스테이트를 사용한다. 이러한 스테이지 스테이트는 모두 D3DTEXTUREOP 열거형으로부터의 값을 사용한다.

텍스쳐 블렌딩 인수에는,D3DTEXTURESTAGESTATETYPE 열거형의 D3DTSS_COLORARG1, D3DTSS_COLORARG2, D3DTSS_ALPHARG1, 및 D3DTSS_ALPHARG2 멤버를 사용한다. 대응하는 인수는,텍스쳐 인수 플래그를 사용해 식별한다.

주 있는 텍스쳐 스테이지의 칼라 처리를 D3DTOP_DISABLE 로 설정하는 것으로, 그 텍스쳐 스테이지와 거기에 계속되는 cascade내의 텍스쳐 블렌딩 스테이지를 무효로 할 수 있다. 칼라 처리를 무효 하면, 알파 처리도 이와 같이 무효가 된다. 칼라 처리가 유효 때에, 알파 처리를 무효로 하는 것은 할 수 없다. 칼라 블렌딩이 유효 때에 알파 처리를 D3DTOP_DISABLE 으로 설정 하면, 그 동작은 부정이다.

디바이스로 지원 되고 있는 텍스쳐 블렌딩 처리를 조사하려면 ,D3DCAPS8 구조체의 TextureCaps 멤버에 문의한다.


경향 텍스쳐의 할당

Microsoft® Direct3D® 는, 최대 8 개의 경향 텍스쳐에 의한 리스트를 이용할 수 있다. Direct3D 에서는, 렌더링 하는 모든 원시적으로, 이러한 텍스쳐를 브렌드 한다. 텍스쳐 인터페이스 포인터로서 생성 한 텍스쳐만, 경향 텍스쳐 세트로 사용할 수 있다.

어플리케이션에서는,IDirect3DDevice8::SetTexture 메소드를 호출해 경향 텍스쳐 세트에 텍스쳐를 할당한다. 제 1 파라미터는, 0 ~ 7 의 범위의 수치가 아니면 안된다. 제 2 파라미터로서 텍스쳐 인터페이스 포인터를 건네준다.

다음의 C++ 코드는, 텍스쳐를 경향 텍스쳐 세트에 할당하는 방법을 나타내고 있다.

// 이 샘플 코드에서는,
// 변수 lpd3dDev 은 IDirect3DDevice8 인터페이스에의 유효한 포인터이며,
// pTexture 은 IDirect3DBaseTexture8 인터페이스에의 유효한 포인터이라고 가정하고 있다.

// 3 번째의 텍스쳐를 설정한다.
d3dDevice->SetTexture(2, pTexture);

주 소프트웨어 디바이스에서는, 텍스쳐를 한 번에 복수의 텍스쳐 스테이지에 할당할 수 없다.


블렌딩 스테이지의 생성

블렌딩 스테이지란, 텍스쳐의 블렌딩 방법을 정의하는, 일련의 텍스쳐 처리와 인수이다. 블렌딩 스테이지를 생성 하면 와, C++ 어플리케이션에서는 IDirect3DDevice8::SetTextureStageState 메소드를 호출한다. 최초의 호출은, 실행하는 처리를 지정한다. 게다가 2 회의 호출을 실시해, 처리를 적용하는 인수를 정의한다. 다음의 샘플 코드는, 블렌딩 스테이지의 생성 방법을 나타내고 있다.

// 이 예에서는, lpD3DDev 이 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.

// 최초의 텍스쳐의 처리를 설정한다.
d3dDevice->SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_ADD);

// 인수 1 을 텍스쳐 칼라로 설정한다.
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE);

// 인수 2 를 보간 하는 디퓨즈색으로 설정한다.
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE);

텍스쳐의 텍셀 데이터에는, 칼라값과 알파값이 포함된다. 어플리케이션에서는, 단일의 블렌딩 스테이지에서 칼라값과 알파값의 양쪽 모두를 정의할 수 있다. 칼라 처리와 알파 처리에는, 각각 독자적인 인수가 있다. 상세한 것에 대하여는, 「D3DTEXTURESTAGESTATETYPE 」를 참조할것.

Microsoft® Direct3D® API 에 포함되지 않지만, 다음의 매크로를 어플리케이션에 삽입해, 텍스쳐 블렌딩 스테이지의 생성에 필요한 코드를 단축할 수가 있다.

#define SetTextureColorStage( dev, i, arg1, op, arg2 )     \
   dev->SetTextureStageState( i, D3DTSS_COLOROP, op);      \
   dev->SetTextureStageState( i, D3DTSS_COLORARG1, arg1 ); \
   dev->SetTextureStageState( i, D3DTSS_COLORARG2, arg2 );

#define SetTextureAlphaStage( dev, i, arg1, op, arg2 )     \
   dev->SetTextureStageState( i, D3DTSS_ALPHAOP, op);      \
   dev->SetTextureStageState( i, D3DTSS_ALPHARG1, arg1 );  \
   dev->SetTextureStageState( i  D3DTSS_ALPHARG2, arg2 );


텍스쳐에 의한 라이트 매핑

3D 신을 리얼하게 렌더링 하려면 , 광원이 장면의 표시에게 주는 이펙트를 고려해야 한다. flat shading나 gouraud shading등의 기술은 이 점으로써 귀중한 툴이지만, 이러한 기술만으로는 불충분하다. Microsoft® Direct3D® 는, 멀티 패스의 멀티 텍스쳐 블렌딩을 지원 하고 있다. 이러한 능력을 사용하는 것으로, 쉐이딩 방법만으로 렌더링 하는 것보다도, 보다 리얼한 장면을 렌더링 할 수 있다. 1 개(살) 또는 복수의라이트 맵을 이용하면, 원시적으로 라이팅과 그림자의 영역을 맵 할 수 있다.

라이트 맵이란, 3D 신의 라이팅에 대한 정보를 포함한 텍스쳐 또는 텍스쳐 그룹이다. 이 라이팅 정보를 라이트 맵의 알파값, 칼라값, 또는 그 양쪽 모두에 저장 할 수 있다.

멀티 패스 텍스쳐 블렌딩을 사용해 라이트 매핑을 실현하는 경우는, 최초의 패스로 원시적으로 라이트 맵을 렌더링 할 필요가 있다. 또, 제 2 의 패스를 사용해, 베이스 텍스쳐를 렌더링 할 필요가 있다. 다만, 스펙큐러 라이트 매핑은 제외하다. 스펙큐러 라이트 맵의 경우는, 최초로 베이스 텍스쳐를 렌더링 해, 다음에 라이트 맵을 추가한다.

멀티 텍스쳐 블렌딩에 의해, 1 살의 패스로 라이트 맵과 베이스 텍스쳐를 렌더링 할 수 있다. 유저의 하드웨어로 멀티 텍스쳐 블렌딩이 지원 되고 있는 경우는, 라이트 매핑을 실시할 때 이 블렌딩을 이용하도록(듯이) 한다. 이것에 의해, 어플리케이션의 퍼포먼스가 큰폭으로 향상한다.

라이트 맵을 사용하면, Direct3D 어플리케이션에서는, 프리미티브를 렌더링 할 경우에 다양한 라이팅 이펙트를 생성할 수 있다. 흑백 라이팅이나 칼라 라이팅을 장면에 매핑 할 수 있는 것 외에 스펙큐러 하이라이트나 디퓨즈 라이트등이 섬세한 이펙트도 추가할 수 있다.

Direct3D 텍스쳐 블렌딩을 사용해 라이트 매핑을 실행하는 방법에 대해서는, 이하의 주제로 설명한다.

  • 흑백 라이트 맵
  • 칼라 라이팅 맵
  • 스펙큐러 라이트 맵
  • 디퓨즈 라이트 맵


흑백 라이트 맵

일부의 낡은 3D 가속기 보드에서는, 전송처 픽셀의 알파값을 사용하는 텍스쳐 블렌딩을 지원 하고 있지 않는 경우가 있다. 상세한 것에 대하여는, 「알파 텍스쳐 블렌딩」을 참조할것. 이러한 어댑터에서는, 일반적으로 멀티 텍스쳐 블렌딩도 지원 하고 있지 않다. 이러한 어댑터로 어플리케이션을 실행하는 경우는, 멀티 패스 텍스쳐 블렌딩을 사용해 흑백 라이트 매핑을 실행할 수 있다.

흑백 라이트 매핑을 실행하려면 , 어플리케이션으로 라이팅 정보를 라이트 맵 텍스쳐의 알파 데이터에 저장 한다. 어플리케이션은, Microsoft® Direct3D® 의 텍스쳐 필터 링 능력을 사용해, 프리미티브의 화면의 각 픽셀로부터 라이트 맵의 대응하는 텍셀에의 매핑을 실행한다. 프로그램으로, 전송원블렌딩 계수를 대응하는 텍셀의 알파값으로 설정한다.

다음의 C++ 코드는, 어플리케이션으로 텍스쳐를 흑백 라이트 맵으로서 사용하는 방법을 나타내고 있다.

// 이 예에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의 유효한 포인터이며,
// lptexLightMap 는 흑백 라이트 맵 데이터를 포함한 텍스쳐에의
// 유효한 포인터이라고 가정하고 있다.

// 라이트 맵 텍스쳐를 경향 텍스쳐로서 설정한다.
d3dDevice->SetTexture(0, lptexLightMap);

// 칼라 처리를 설정한다.
d3dDevice->SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_SELECTARG1);

// 인수 1 을 칼라 처리로 설정한다.
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG1,
       D3DTA_TEXTURE | D3DTA_ALPHAREPLICATE);

전송처 알파 블렌딩을 지원 하고 있지 않는 디스플레이 어댑터는, 보통 멀티 텍스쳐 블렌딩을 지원 하고 있지 않기 때문에, 이 예에서는, 모든 3D accelerator card로 사용할 수 있는 라이트 맵을 최초의 텍스쳐로서 설정해 있다. 또, 이 예에서는, 텍스쳐의 블렌딩 스테이지에 대한 칼라 처리를 설정해, 텍스쳐 데이터를 프리미티브의 기존의 색과 브렌드 하고 있다. 그 다음에, 입력 데이터로서 최초의 텍스쳐와 프리미티브의 기존의 색을 선택하고 있다.


칼라 라이팅 맵

일반적으로, 칼라 라이팅 맵을 사용하면, 3D 신을 보다 리얼하게 렌더링 할 수 있다. 칼라 라이팅 맵은, 라이팅 정보로서 라이트 맵의 RGB 데이터를 사용한다.

다음의 C++ 코드는, RGB 칼라 데이터를 사용한 라이트 매핑을 나타내고 있다.

// 이 예에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의 유효한 포인터이며,
// lptexLightMap 는 RGB 라이트 맵 데이터를 포함한 텍스쳐에의
// 유효한 포인터이라고 가정하고 있다.

// 라이트 맵 텍스쳐를 최초의 텍스쳐로서 설정한다.
d3dDevice->SetTexture(0, lptexLightMap);

d3dDevice->SetTextureStageState( 0, D3DTSS_COLOROP, D3DTOP_MODULATE );
d3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );

이 예에서는, 라이트 맵을 최초의 텍스쳐로서 설정해 있다. 그 다음에, 최초의 블렌딩 스테이지의 스테이트를 설정해, 입력 텍스쳐 데이터를 곱셈하고 있다. 또, 최초의 텍스쳐와 프리미티브의 경향 칼라를 곱셈 처리용의 인수로서 사용하고 있다.


스펙큐러 라이트 맵

광원에서 비추었을 때에 빛나는 오브젝트 (반사성의 높은 머트리얼을 사용하는 오브젝트)는, 스펙큐러 하이라이트를 받는다. 경우에 따라서는, 라이팅 모듈로 생성된 스펙큐러 하이라이트는 정확하지 않은 경우도 있다. 보다 효과적인 하이라이트를 생성하기 위해서, 많은 Microsoft® Direct3D® 어플리케이션에서는 원시적으로 스펙큐러 라이트 맵을 적용한다.

스펙큐러 라이트 매핑을 실행하려면 , 우선 스펙큐러 라이트 맵을 프리미티브의 기존의 텍스쳐에 맞추어 곱셈한다. 다음에, 흑백 또는 RGB 라이트 맵을 추가한다.

다음의 샘플 코드는, C++ 에서의 이 처리를 나타내고 있다.

// 이 예에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
// lptexBaseTexture 는, 텍스쳐에의 유효한 포인터이다.
// lptexSpecLightMap 는, RGB 스펙큐러 라이트 맵 데이터를 포함한다
// 텍스쳐에의 유효한 포인터이다.
// lptexLightMap 는, RGB 라이트 맵 데이터를 포함한다
// 텍스쳐에의 유효한 포인터이다.

// 베이스 텍스쳐를 설정한다.
d3dDevice->SetTexture(0, lptexBaseTexture );

// 베이스 텍스쳐 처리와 인수를 설정한다.
d3dDevice->SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_MODULATE );
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );

// 스펙큐러 라이트 맵을 설정한다.
d3dDevice->SetTexture(1, lptexSpecLightMap);

// 스펙큐러 라이트 맵 처리와 인수를 설정한다.
d3dDevice->SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_ADD );
d3dDevice->SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT );

// RGB 라이트 맵을 설정한다.
d3dDevice->SetTexture(2, lptexLightMap);

// RGB 라이트 맵 처리와 인수를 설정한다.
d3dDevice->SetTextureStageState(2, D3DTSS_COLOROP, D3DTOP_MODULATE);
d3dDevice->SetTextureStageState(2, D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(2, D3DTSS_COLORARG2, D3DTA_CURRENT );


디퓨즈 라이트 맵

광원에서 비추었을 때, 광택이 없는 표면은 디퓨즈 라이트를 추방한다. 디퓨즈 라이트의 빛남은, 광원으로부터의 거리, 및 표면 법선과 광원의 방향 벡터와의 각도에 따라서 다르다. 라이팅 계산에 의해 시뮬레이트 하는 디퓨즈 라이트의 이펙트는 일반적인 것이다.

텍스쳐 라이트 맵을 사용해 디퓨즈 라이트를 시뮬레이트 할 수 있다. 이것을 실시하려면 , 다음의 C++ 코드로 가리키도록(듯이), 디퓨즈 라이트 맵을 베이스 텍스쳐에 추가한다.

// 이 예에서는, d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
// lptexBaseTexture 는, 텍스쳐에의 유효한 포인터이다.
// lptexDiffuseLightMap 는, RGB 디퓨즈 라이트 맵 데이터를 포함한다
// 텍스쳐에의 유효한 포인터이다.

// 베이스 텍스쳐를 설정한다.
d3dDevice->SetTexture(0, lptexBaseTexture );

// 베이스 텍스쳐 처리와 인수를 설정한다.
d3dDevice->SetTextureStageState(0, D3DTSS_COLOROP,
       D3DTOP_MODULATE );
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );

// 디퓨즈 라이트 맵을 설정한다.
d3dDevice->SetTexture(1, lptexDiffuseLightMap );

// 블렌딩 스테이지를 설정한다.
d3dDevice->SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_MODULATE );
d3dDevice->SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT );


압축한 텍스쳐 리소스

Microsoft® Direct3D® 는, 3D 모델의 텍스쳐 처리에 사용하는 표면 압축기노우를 갖추고 있다. 여기에서는, 압축 텍스쳐 표면의 데이터의 생성 및 조작에 대해 설명한다.

설명하는 주제는, 다음과 같다.

  • 압축한 텍스쳐란
  • 압축한 텍스쳐 포맷
  • 압축한 텍스쳐의 사용법


압축한 텍스쳐란

텍스쳐 맵이란, 3D 의 형상 위에 드로잉(Drawing) 해 세부를 더하는 디지털 화면이다. 텍스쳐 맵은, 라스터화의 실행중에 이러한 형상에 매핑 된다. 이 프로세스는, 시스템 버스와 메모리의 양쪽 모두를 대량으로 사용하는 경우가 있다. 텍스쳐로 소비되는 메모리 용량을 줄이기 위해서(때문에), Microsoft® Direct3D® 에서는 텍스쳐 표면의 압축을 지원 하고 있다. 몇개의 Direct3D 디바이스는, 압축한 텍스쳐 표면을 네이티브에 지원 한다. 이러한 디바이스로 압축한 표면을 생성 해, 그 디바이스에 데이터를 로드해 버리면, 다른 텍스쳐 표면과 같게 Direct3D 로 표면을 사용할 수 있다. 텍스쳐가 3D 표면 오브젝트에 맵 되는 경우, Direct3D 는 압축의 복원을 처리한다.


압축한 텍스쳐 포맷

여기에서는, 압축한 텍스쳐 포맷의 내부 조직에 대해 설명한다. 압축 포맷간의 변환에는 D3DX 함수를 사용하기 위해(때문에), 이러한 정보를 자세하게 알 필요는 없다. 다만, 압축한 표면 데이터를 직접 처리하는 경우는, 이 정보가 도움이 된다.

Direct3D 에서는, 텍스쳐 맵을 4 × 4 의 텍셀 블록에 분할하기 위해서 압축 포맷을 사용한다. 텍스쳐에 투과성이 포함되지 않는 경우 (불투명), 또는 투과성이 1 비트 알파에서 지정되는 경우, 8 바이트 블록이 텍스쳐 맵 블록을 나타낸다. 텍스쳐 맵에 투과형 텍셀이 포함되지 않는 경우, 알파 채널을 사용해 16 바이트 블록이 텍스쳐 맵 블록을 나타낸다.

  • 불투명과 1 비트 알파 텍스쳐
  • 알파 채널에 의한 텍스쳐
  • 스토리지의 효율과 텍스쳐 압축에 대해
  • 단일 텍스쳐내에서의 포맷의 편성

주 모든 단일의 텍스쳐에서는, 16 텍셀의 그룹 마다 64 비트 또는 128 비트로서 저장 되는 데이터를 지정하지 않으면 안 된다. 64 비트 블록 (즉, 포맷 DXT1)이 텍스쳐용으로 사용되는 경우, 몇개의 텍스쳐의 블록 마다 불투명과 1 비트 알파 포맷을 조합할 수가 있다. 즉, 색 0 으로 색 1 의 부호 없음 정수의 매그니튜드의 비교는, 16 텍셀의 각 블록 마다 실행된다.

128 비트 블록을 사용하는 경우, 텍스쳐 전체에 알파 채널을 명시적 (포맷 DXT2 또는 DXT3)으로, 또는 보간 한 모드 (포맷 DXT4 또는 DXT5)로 지정하지 않으면 안 된다. 색의 경우와 같이, 보간 한 모드를 선택 하면, 8 개의 보간 한 알파인가, 블록 단위로 사용할 수 있는 6 개의 보간 한 알파 모드의 어느쪽이든을 사용할 수 있다. 게다가 알파 0 으로 알파 1 의 크기의 비교는, 블록 마다 행해진다.

DXTn 포맷의 피치는, DirectX 7 으로 돌려주어지고 있던 것과는 다르다. 향후는, 블록 1 행의 피치이다. 예를 들어, 폭이 16 으로 하면, 피치는 4 블록 (DXT1 는 4*8, DXT2 ~ 5 는 4*16)이 된다.


불투명과 1 비트 알파 텍스쳐

텍스쳐 포맷 DXT1 는, 불투명 또는 단일의 투과형색이 있는 텍스쳐용이다.

각 불투명 또는 1 비트 알파 블록을 위해서(때문에), 2 개의 16 비트값 (RGB 5:6:5 포맷)과 픽셀 단위의 2 비트의 4 × 4 비트 맵이 저장 된다. 이것은, 16 텍셀에 대해서 합계 64 비트, 즉 4 비트/텍셀이 된다. 블록 비트 맵에는, 4 색간을 선택하는 텍셀 마다 2 비트가 있다. 4 색중 2 색은, encode 된 데이터에 저장 된다. 다른 2 색은, 선형 보간으로 저장 되는 색으로부터 파생한다. 다음의 그림은, 이 레이아웃을 나타내고 있다.

1 비트 알파 포맷은, 블록에 저장 되는 16 비트 칼라값을 비교하는 것으로써, 불투명 포맷과 구별된다. 이것들은, 부호 없음의 정수로서 처리된다. 최초의 색이 다음의 색보다 큰 경우는, 불투명 텍셀만이 정의되고 있는 것을 의미한다. 즉, 텍셀을 나타내는데 4 색이 사용된다. 4 색의 encode에는 2 개의 파생한 색이 있어, 전 4 색은 RGB 색공간(color space)에 동일하게 배포된다. 이 포맷은, RGB 5:6:5 포맷에 유사하고 있다. 다른 점에서는, 1 비트 알파 투과성용으로 이러한 색은 사용되어 4 번째의 색은 투과형 텍셀을 나타내기 위해서(때문에) 확보된다.

3 개의 색의 encode에는 1 개의 파생한 색이 있어, 4 번째의 2 비트 코드는 투과형 텍셀 (알파 정보)을 포함하기 위해서(때문에) 확보된다. 이 포맷은, 알파 마스크를 encode 하기 위해서 사용되는 마지막 비트가 있는 RGBA 5:5:5:1 에 유사하고 있다.

다음의 샘플 코드는, 3 색 또는 4 색의 encode를 선택할지 어떨지를 결정하기 위한 알고리즘을 나타낸다.

if (color_0 > color_1)
{
    // 4 색블록 :다른 2 색을 파생한다.
    // 00 = 색 0, 01 = 색 1, 10 = 색 2, 11 = 색 3
    // 64 비트 블록에 저장 되었다
    // 2 비트 필드에 대응하는 2 비트 코드.
    color_2 = (2 * color_0 + color_1 + 1) / 3;
    color_3 = (color_0 + 2 * color_1 + 1) / 3;
}
else
{
    // 3 색블록 :다른 색을 파생한다.
    // 00 = 색 0, 01 = 색 1, 10 = 색 2,
    // 11 = 투과형.
    // 64 비트 블록에 저장 되었다
    // 2 비트 필드에 대응하는 2 비트 코드.
     color_2 = (color_0 + color_1) / 2;
     color_3 = transparent;

}

투과형 픽셀의 RGBA 컴퍼넌트는, 블렌딩전에 제로로 설정해 두는 것을 권한다.

8 바이트 블록용의 메모리층을 다음 표에 나타낸다. 최초의 인덱스가 y 축, 2 번째의 인덱스가 x 축으로 대응 하면 생각한다. 예를 들어, 텍셀 [1][2] 는 (x, y) = (2,1)로 텍스쳐 맵 픽셀을 참조한다.

다음의 표는, 8 바이트 (64 비트) 블록용의 메모리 레이아웃을 나타내고 있다.

단어 주소 | 16 비트 단어
0 | 색 _0
1 | 색 _1
2 | 비트 맵 단어 _0
3 | 비트 맵 단어 _1

색 0 으로 색 1 (2 극값에서의 색)의 배치를 다음에 나타낸다.

비트 | 색
04:00 (LSB) | 청색 성분
10:5 | 녹색 성분
15:11 | 적색 성분

비트 맵 word_0 의 배치

비트 | 텍셀
01:00 (LSB) | 텍셀 [0][0]
3:2 | 텍셀 [0][1]
5:4 | 텍셀 [0][2]
7:6 | 텍셀 [0][3]
9:8 | 텍셀 [1][0]
11:10 | 텍셀 [1][1]
13:12 | 텍셀 [1][2]
15:14 (MSB) | 텍셀 [1][3]

비트 맵 word_1 의 배치

비트 | 텍셀
01:00 (LSB) | 텍셀 [2][0]
3:2 | 텍셀 [2][1]
5:4 | 텍셀 [2][2]
7:6 | 텍셀 [2][3]
9:8 | 텍셀 [3][0]
11:10 | 텍셀 [3][1]
13:12 | 텍셀 [3][2]
15:14 (MSB) | 텍셀 [3][3]

불투명색부호의 예

불투명 부호의 예로서 적과 흙이 극값이라고 가정한다. 빨강은 색 _0, 흑은 색 _1 으로 한다. 한결같게 경도를 서로 분할한 폼의 보간 한 4 색이 있다. 4 × 4 비트 맵의 값을 결정하려면 , 다음에 나타내는 계산식을 사용한다.

00 ?  color_0
01 ?  color_1
10 ?  2/3 color_0 + 1/3 color_1
11 ?  1/3 color_0 + 2/3 color_1

이 비트 맵은, 다음과 같이 된다.

이 비트 맵은 다음과 같은 일련의 색이 된다.

1 비트 알파 부호의 예

부호 없음 16 비트 정수 (색 _0)가 부호 없음 16 비트 정수 (색 _1)보다 작은 경우, 이 포맷이 선택된다. 이 포맷은, 푸른 하늘을 배경으로 한 나뭇잎 등에 사용할 수 있다. 몇개의 텍셀은, 3 색의 초록의 그림자가 잎에 대해서 사용되는 동안에 투과형으로서 기록된다. 이것들 2 색은 극값에 적합해, 3 번째의 색은 보간 한 색이 된다.

그러한 화면의 예를 다음에 나타낸다.

위에의도로, 백색으로 가리키는 화면에서는, 텍셀은 투과형으로서 encode 되는 것에 주의 해야 한다. 또, 투과형 텍셀의 RGBA 컴퍼넌트는, 블렌딩전에 제로로 설정하도록(듯이) 주의 해야 한다.

색과 투과성에 대한 비트 맵 부호는, 다음의 계산식을 사용해 결정된다.

00 ?  color_0
01 ?  color_1
10 ?  1/2 color_0 + 1/2 color_1
11   ?    Transparent

비트 맵은, 다음과 같이 된다.


알파 채널에 의한 텍스쳐

보다 복잡한 투과성을 나타내는 텍스쳐 맵의 encode에는, 2 통과해 방법이 있다. 어느 쪽의 경우도, 투과성을 기술하는 블록은 이미 기술되고 있는 64 비트 블록보다 먼저 일어난다. 투과성은 픽셀 단위에 4 비트의 4 × 4 비트 맵 (명시적인 encode), 또는 그것 이하의 비트의 비트 맵의 어느 쪽인지여, 선형 보간은 색encode로 사용되는 것으로 유사한다.

투과성 블록과 색블록의 배치는, 다음 표에 나타내는 대로이다.

단어 주소 | 64 비트 블록
3:0 | 투과성 블록
7:4 | 이미 기술된 64 비트 블록

명시적인 텍스쳐 encode

명시적인 텍스쳐 encode (DXT2 와 DXT3 포맷)를 위해서(때문에), 투과성을 기술하는 텍셀의 알파 성분은, 텍셀 마다 4 비트의 4 × 4 비트 맵으로 encode 된다. 이러한 4 비트는, 알파 데이터로 4 개의 최상정도 비트를 디저링 하거나 그것들을 단지 사용하는 등, 다양한 방법으로 달성할 수 있다. 다만, 생성 되면(자), 모든 보간의 폼이 없으면 그 만큼으로 밖에 사용할 수 없다.

다음의 그림은, 64 비트의 투과성 블록을 나타내고 있다.

주 Microsoft® Direct3D® 의 압축 메소드에서는, 4 개의 최상정도 비트를 사용한다.

다음의 표는, 알파 정보가 각 16 비트 단어용으로 배치되는 방법에 대해 가리키고 있다.

단어 0 용의 배치는, 다음과 같다.

비트 | 알파
3:0 (LSB) | [0][0]
7:4 | [0][1]
11:8 | [0][2]
15:12 (MSB) | [0][3]

단어 1 용의 배치는, 다음과 같다.

비트 | 알파
3:0 (LSB) | [1][0]
7:4 | [1][1]
11:8 | [1][2]
15:12 (MSB) | [1][3]

단어 2 용의 배치는, 다음과 같다.

비트 | 알파
3:0 (LSB) | [2][0]
7:4 | [2][1]
11:8 | [2][2]
15:12 (MSB) | [2][3]

단어 3 용의 배치는, 다음과 같다.

비트 | 알파
3:0 (LSB) | [3][0]
7:4 | [3][1]
11:8 | [3][2]
15:12 (MSB) | [3][3]

DXT2 와 DXT3 의 차이는, DXT2 포맷에서는 칼라 데이터는 미리 알파를 하는 도중라고 있는 것을 전제로 하고 있다. DXT3 포맷에서는, 칼라 데이터는 미리 알파를 하는 도중라고 없는 것을 전제로 하고 있다. 이러한 2 개의 포맷이 필요하게 되는 이유는, 텍스쳐가 사용되는 대부분의 경우, 데이터를 다만 조사하는 것 만으로는 칼라값에 알파가 걸려있을지 어떨지를 판단할 수 없기 때문에이다. 이러한 정보가 실행시에 필요해서, 2 개의 FOURCC 코드를 사용해 이러한 경우를 구별하고 있다. 다만, 이러한 2 개의 포맷에 사용되는 데이터와 보간의 메소드는 같다.

텍셀이 투과형인가 어떤가를 판정하기 위해서 DXT1 로 사용되는 색비교는, 이 포맷에서는 사용되지 않는다. 색비교없이는, 칼라 데이터는 항상 4 색모드로서 처리되는 것을 전제로 하고 있다. 즉, DXT1 코드의 선두의 if 문은 다음과 같이 된다.

if ((color_0 > color_1) OR ! DXT1) {

3 비트 선형 알파 보간

DXT4 및 DXT5 포맷에 대한 투과성의 부호는, 색에 사용되는 선형 부호 와 유사한 개념이 기가 된다. 2 개의 8 비트 알파값과 픽셀 단위에 3 비트의 4 × 4 비트 맵은, 블록의 최초의 8 바이트에 저장 된다. 전형적인 알파값은, 중간 알파값을 보간 하기 위해서 사용된다. 추가 정보는, 2 개의 알파값을 저장 하는 방법으로 이용할 수 있다. 알파 _0 가 알파 _1 보다 큰 경우, 6 개의 중간 알파값이 보간에 의해 생성 된다. 또, 4 개의 중간 알파값이 지정되는 알파 극값간에 보간 된다. 2 개의 추가의 명시적인 알파값은, 0 (완전하게 투과형)으로 255 (완전하게 불투명)가 된다.

다음의 샘플 코드는, 이 알고리즘을 나타내고 있다.

// 8 알파 블록이나 6 알파 블록인가.
if (alpha_0 > alpha_1) {
    // 8 알파 블록 :다른 6 개의 알파를 파생한다.
    // 비트 코드 000 = 알파 0, 001 = 알파 1, 그 외는 보간 된다.
    alpha_2 = (6 * alpha_0 + 1 * alpha_1 + 3) / 7;    // 비트 코드 010
    alpha_3 = (5 * alpha_0 + 2 * alpha_1 + 3) / 7;    // 비트 코드 011
    alpha_4 = (4 * alpha_0 + 3 * alpha_1 + 3) / 7;    // 비트 코드 100
    alpha_5 = (3 * alpha_0 + 4 * alpha_1 + 3) / 7;    // 비트 코드 101
    alpha_6 = (2 * alpha_0 + 5 * alpha_1 + 3) / 7;    // 비트 코드 110
    alpha_7 = (1 * alpha_0 + 6 * alpha_1 + 3) / 7;    // 비트 코드 111
}
else {
    // 6 알파 블록.
    // 비트 코드 000 = 알파 0, 001 = 알파 1, 그 외는 보간 된다.
    alpha_2 = (4 * alpha_0 + 1 * alpha_1 + 2) / 5;    // 비트 코드 010
    alpha_3 = (3 * alpha_0 + 2 * alpha_1 + 2) / 5;    // 비트 코드 011
    alpha_4 = (2 * alpha_0 + 3 * alpha_1 + 2) / 5;    // 비트 코드 100
    alpha_5 = (1 * alpha_0 + 4 * alpha_1 + 2) / 5;    // 비트 코드 101
    alpha_6 = 0;                                      // 비트 코드 110
    alpha_7 = 255;                                    // 비트 코드 111
}

알파 블록의 메모리층을 다음에 나타낸다.

바이트 | 알파
0 | 알파 _0
1 | 알파 _1
2 | [0][2] (2 LSBs) , [0][1], [0][0]
3 | [1][1] (1 LSB) , [1][0], [0][3], [0][2] (1 MSB)
4 | [1][3], [1][2], [1][1] (2 MSBs)
5 | [2][2] (2 LSBs) , [2][1], [2][0]
6 | [3][1] (1 LSB) , [3][0], [2][3], [2][2] (1 MSB)
7 | [3][3], [3][2], [3][1] (2 MSBs)

DXT4 와 DXT5 의 차이는, DXT4 포맷에서는 칼라 데이터는 미리 알파를 하는 도중라고 있는 것을 전제로 하고 있다. DXT5 포맷에서는, 칼라 데이터는 미리 알파를 하는 도중라고 없는 것을 전제로 하고 있다. 이러한 2 개의 포맷이 필요하게 되는 이유는, 텍스쳐가 사용되는 대부분의 경우, 데이터를 다만 조사하는 것 만으로는 칼라값에 알파가 걸려있을지 어떨지를 판단할 수 없기 때문에이다. 이러한 정보가 실행시에 필요해서, 2 개의 FOURCC 코드를 사용해 이러한 경우를 구별하고 있다. 다만, 이러한 2 개의 포맷에 사용되는 데이터와 보간의 메소드는 같다.

텍셀이 투과형인가 어떤가를 판정하기 위해서 DXT1 로 사용되는 색비교는, 이러한 포맷에서는 사용되지 않는다. 색비교없이는, 칼라 데이터는 항상 4 색모드로서 처리되는 것을 전제로 하고 있다. 즉, DXT1 코드의 선두의 if 문은 다음과 같이 된다.

if ((color_0 > color_1) OR ! DXT1) {


스토리지의 효율과 텍스쳐 압축에 대해

모든 텍스쳐 압축 포맷은, 2 의 거듭제곱이다. 이것은, 텍스쳐가 반드시 정방형이다고 하는 것은 아니지만, X 와 Y 가 양쪽 모두 2 의 거듭제곱이다고 하는 것이다. 예를 들어, 텍스쳐가 처음은 512 × 128 바이트라면 하면, 다음의 밉맵 처리에서는 256 × 64 와 같이, 각 레벨이 2 의 거듭제곱씩 줄어들어 간다. 한층 더 레벨이 작아져, 텍스쳐가 16 × 2 및 8 × 1 까지 필터 링 처리되면(자), 불용 비트가 생긴다. 이것은, 압축 블록이 항상 4 × 4 의 텍셀 블록이니까이다. 블록의 미사용 부분은 패딩 된다. 최소 레벨에서는 불용 비트가 있지만, 전체적으로 얻을 수 있는 것은 여전히 중요하다. 이론적으로 최악의 경우란, 2K × 1 텍스쳐 (2 의 0 승)이다. 이 경우, 1 블록에 대해 1 픽셀행밖에 encode 되지 않고, 블록의 나머지의 부분은 미사용이 된다.


단일 텍스쳐내에서의 포맷의 편성

중요한 점은, 모든 단일의 텍스쳐에서는, 16 텍셀의 그룹 마다 64 비트 또는 128 비트로서 저장 되는 데이터를 지정하도록(듯이) 주의한다고 하는 점이다. 64 비트 블록 (즉, 포맷 DXT1)이 텍스쳐용으로 사용되는 경우, 몇개의 텍스쳐의 블록 마다 불투명과 1 비트 알파 포맷을 조합할 수가 있다. 즉, 색 0 으로 색 1 의 부호 없음 정수의 매그니튜드의 비교는, 16 텍셀의 각 블록 마다 실행된다.

128 비트 블록을 사용하는 경우, 텍스쳐 전체에 알파 채널을 명시적 (포맷 DXT2 또는 DXT3)으로, 또는 보간 한 모드 (포맷 DXT4 또는 DXT5)로 지정하지 않으면 안 된다. 색의 경우와 같이, 보간 한 모드 (포맷 DXT4 및 DXT5)를 선택하는 경우, 8 개의 보간 한 알파인가, 블록 단위로 사용할 수 있는 6 개의 보간 한 알파 모드의 어느쪽이든을 사용할 수 있는 것에 주의 해야 한다. 게다가 알파 0 으로 알파 1 의 매그니튜드의 비교는, 블록 마다 행해진다.


압축한 텍스쳐의 사용법

여기에서는, Microsoft® Direct3D® 어플리케이션으로 압축한 텍스쳐를 사용하는 방법에 대해 설명한다.

설명하는 주제는, 다음과 같다.

  • 압축한 텍스쳐의 지원의 판정
  • 압축한 텍스쳐의 생성
  • 압축한 텍스쳐의 복원


압축한 텍스쳐의 지원의 판정

어플리케이션으로 렌더링 디바이스를 생성 하기 전에,IDirect3D8::CheckDeviceFormat 메소드를 호출해, 압축 텍스쳐 표면으로부터의 텍스쳐 처리를 디바이스가 지원 할지 어떨지를 조사할 수가 있다. 이 메소드는, 어댑터를 나타내는 디바이스상에서 표면 포맷이 텍스쳐로서 사용할 수 있을지 어떨지를 판정한다. 어댑터를 테스트하려면 , DXT1, DXT2, DXT3, DXT4, 또는 DXT5 의 FOURCC 코드를 사용하는 픽셀 포맷의 어느쪽이든을 지정한다. CheckDeviceFormat 가 D3D_OK 를 돌려주었을 경우, 디바이스는 그 포맷을 사용하는 압축 텍스쳐 표면으로부터 직접 텍스쳐를 얻을 수 있다. 이 경우,IDirect3DDevice8::SetTexture 메소드를 호출해, Microsoft®Direct3D® 로 압축 텍스쳐 표면을 직접 사용할 수 있다. 다음의 코드는, 어댑터가 D3DFMT_DXT1 압축 텍스쳐 포맷을 지원 할지 어떨지를 판정하는 방법을 나타내고 있다.

BOOL IsCompressedTextureFormatOk( D3DFORMAT TextureFormat,
                                  D3DFORMAT AdapterFormat ) {
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          0,
                                          D3DRTYPE_TEXTURE,
                                          D3DFMT_DXT1);

    return SUCCEEDED( hr );
}

디바이스가 압축 텍스쳐 표면으로부터의 텍스쳐 처리를 지원 하지 않는 경우에서도, 텍스쳐 데이터를 압축 포맷 표면내에 저장 할 수 있다. 다만, 압축 텍스쳐를 텍스쳐로서 사용하기 전에, 지원 되는 포맷으로 변환하지 않으면 안 된다.


압축한 텍스쳐의 생성

어댑터로 압축 텍스쳐 포맷을 지원 할 수 있는 디바이스를 생성 한 후, 압축 텍스쳐 리소스를 생성 할 수 있다. IDirect3DDevice8::CreateTexture 를 호출해,Format 파라미터에 압축 텍스쳐 포맷을 지정한다.

텍스쳐 오브젝트에 화면을 로드하기 전에,IDirect3DTexture8::GetSurfaceLevel 메소드를 호출해, 텍스쳐 표면에의 포인터를 취득한다.

이것으로, D3DXLoadSurface 으로 시작되는 D3DX 함수를 사용해,GetSurfaceLevel 로 취득한 표면에 화면을 로드할 수 있다. 이러한 함수는, 압축 텍스쳐 포맷간의 변환을 처리한다.

SDK 로 제공되는 DXTex 툴을 사용 하면, 압축한 텍스쳐 (DDS) 파일의 생성과 변환을 실시할 수가 있다. 독자적인 DDS 파일을 생성 할 수도 있다.

이 동작의 이점은, 어플리케이션으로, 특정의 포맷으로 특정의 폭과 높이를 가지는 표면에 필요한 스토리지 용량을 계산하지 않아도 압축한 표면의 컨텐츠를 파일에 카피할 수 있는 것이다.

압축한 텍스쳐의 5 개의 타입을 이하의 겉(표)에 나타낸다. 데이터의 보존 방법의 상세한 것에 대하여는, 「압축한 텍스쳐 포맷」을 참조할것. 다음의 정보는, 독자적인 압축 루틴을 기술하는 경우에 필요하다.

FOURCC | 설명 | 알파값사전 곱셈이 끝난 상태
DXT1 | 불투명/1 비트 알파 | N/A
DXT2 | 명시적인 알파 | Yes
DXT3 | 명시적인 알파 | No
DXT4 | 보간 한 알파 | Yes
DXT5 | 보간 한 알파 | No

주 값사전 곱셈이 끝난 상태가 아닌 포맷화등값사전 곱셈 끝난 포맷에 데이터를 전송 하는 경우, Direct3D 는 알파값을 기본으로 색을 스케일링 한다. 값사전 곱셈 끝난 퍼 매트로부터 값사전 곱셈이 끝난 상태가 아닌 포맷에의 데이터 전송은 지원 되지 않는다. 값사전 곱셈 끝난 알파 전송원으로부터 값사전 곱셈이 끝난 상태가 아닌 알파 전송처에의 데이터 전송을 시험하면(자), 메소드는 D3DERR_INVALIDCALL 를 돌려준다. 값사전 곱셈 끝난 알파 전송원으로부터 알파가 없는 전송 먼저 데이터를 전송 하면, 알파에서 스케일링 되는 전송원색성분은 그대로 카피된다.


압축한 텍스쳐의 복원

텍스쳐 표면의 압축과 같이, 압축한 텍스쳐의 복원은 Microsoft®Direct3D® 카피 서비스에 의해 실시할 수가 있다.

드라이버가 비디오 메모리 표면의 생성을 지원 하는 경우는, 압축한 비디오 메모리 표면으로부터 압축하고 있지 않는 비디오나 시스템 메모리 표면에의 카피에 있어서의 압축의 복원도 실시한다.

압축한 시스템 메모리 표면으로부터 압축하고 있지 않는 비디오 메모리 표면에의 카피는 많은 경우 지원 되지 않고, 드라이버가 압축한 텍스쳐를 지원 하는 경우에서도 지원 되지 않는다. 이것은, 압축한 시스템 메모리 표면의 압축의 복원과 비디오 메모리 표면에의 컨텐츠의 이동이 불가능한 것을 나타내고 있는 것은 아니다. 단지, 추가의 스텝을 필요로 하는 것만으로 있다.

비디오 메모리에의 시스템 메모리 표면의 압축을 복원하려면

  1. 필요한 넓이와 픽셀 포맷의 시스템 메모리에, 압축하고 있지 않는 오프 스크린 프레인 표면을 생성 한다.
  2. 압축한 시스템 메모리 표면으로부터 압축하고 있지 않는 시스템 메모리 표면에 카피한다
  3. 압축하고 있지 않는 표면으로부터 압축하고 있지 않는 비디오 메모리 표면에 카피한다.


볼륨 텍스쳐 리소스

이하의 주제에서는, 볼륨 텍스쳐에 대해 설명한다.

  • 볼륨 텍스쳐란
  • 볼륨 텍스쳐의 사용법


볼륨 텍스쳐란

볼륨 텍스쳐란, 삼각형이나 선등의 2D 프리미티브의 드로잉(Drawing)에 사용할 수 있는 픽셀 (텍셀)의 3D 의 모임이다. 입체로 텍스쳐 처리되는 프리미티브의 각 버텍스에는, 3 요소의 텍스쳐 좌표가 필요하다. 프리미티브를 드로잉(Drawing) 하는 경우, 각 원시적으로 포함되는 픽셀에는, 2D 텍스쳐의 경우와 같은 규칙에 따라, 입체내의 픽셀의 칼라값이 설정된다. 입체로 페인트 할 수 있는 3D 프리미티브가 없기 때문에, 입체는 직접 렌더링 되지 않는다.

볼륨 텍스쳐는, 아직들인 fog, 폭발등의 특수 효과에 사용할 수 있다.

입체는 슬라이스에 정리해폭 × 높이의 2D 표면이 스택 되어,폭 × 높이 × 깊이의 입체를 구성 하면 생각할 수가 있다. 각 슬라이스는, 단일행이다. 입체는 후속 레벨을 가질 수가 있다. 각 레벨의 크기는, 직전 레벨의 반의 크기에 잘라 버릴 수 있다. 다음의 그림은, 복수 레벨을 가지는 볼륨 텍스쳐를 나타내고 있다.


볼륨 텍스쳐의 사용법

다음의 코드는, 볼륨 텍스쳐를 사용하기 위해서 필요한 순서를 나타내고 있다.

우선, 각 버텍스에 대해서 3 개의 텍스쳐 좌표를 가지는 커스텀 버텍스 타입을 지정한다. 다음의 코드에 예를 나타낸다.

struct VOLUMEVERTEX
{
    FLOAT x, y, z;
    DWORD color;
    FLOAT tu, tv, tw;
};

#define D3DFVF_VOLUMEVERTEX (D3DFVF_XYZ|D3DFVF_DIFFUSE|
                             D3DFVF_TEX1|D3DFVF_TEXCOORDSIZE3(0))

다음에, 버텍스에 데이터를 설정한다.

VOLUMEVERTEX g_vVertices[4] =
{
    { 1.0f, 1.0f, 0.0f, 0xffffffff, 1.0f, 1.0f, 0.0f },
    {-1. 0f, 1.0f, 0.0f, 0xffffffff, 0.0f, 1.0f, 0.0f },
    { 1.0f,-1. 0f, 0.0f, 0xffffffff, 1.0f, 0.0f, 0.0f },
    {-1. 0f,-1. 0f, 0.0f, 0xffffffff, 0.0f, 0.0f, 0.0f }
};

다음에, 버텍스 버퍼를 생성 해, 버텍스의 데이터를 설정한다.

다음의 순서는,IDirect3DDevice8::CreateVolumeTexture 메소드를 사용해, 볼륨 텍스쳐를 생성 하는 것이다. 다음의 코드에 예를 나타낸다.

LPDIRECT3DVOLUMETEXTURE8 volTexture;

d3dDevice->CreateVolumeTexture( 8, 4, 4, 1, 0, D3DFMT_R8G8B8,
                                D3DPOOL_MANAGED, &volTexture );

프리미티브를 렌더링 하기 전에, 경향 텍스쳐를 전의 순서로 생성 한 볼륨 텍스쳐로 설정한다. 다음의 코드는, 삼각형의 스트립의 렌더링 프로세스 전체를 나타내고 있다.

if( SUCCEEDED( d3dDevice->BeginScene() ) )
{
    // 볼륨 텍스쳐로 사각형을 드로잉(Drawing) 한다.
    d3dDevice->SetTexture( 0, pVolumeTexture );
    d3dDevice->SetVertexShader( D3DFVF_VOLUMEVERTEX );
    d3dDevice->SetStreamSource( 0, pVB, sizeof(VOLUMEVERTEX) );
    d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0, 2);

   // 장면을 종료한다.
   d3dDevice->EndScene();
}


자동 텍스쳐 관리

텍스쳐 관리란, 어떤 시점에 있어 어느 텍스쳐가 렌더링에 필요한가를 판단해, 그러한 텍스쳐를 비디오 메모리에 확실히 로드하는 처리이다. 다른 알고리즘과 같이, 텍스쳐 관리 스킴도 그 복잡함은 다양하지만, 어떠한 어프로치로 텍스쳐 관리를 실시하는 경우여도, 이하에 나타내는 태스크가 중요하다.

  • 사용 가능한 텍스쳐 메모리의 양의 추적
  • 렌더링에 필요한 텍스쳐와 불필요한 텍스쳐의 계산
  • 기존의 텍스쳐 리소스 가운데, 다른 텍스쳐 화면에 재로드할 수 있는 텍스쳐 리소스의 판단, 또 파기할 필요가 있는 표면, 및 새로운 텍스쳐 리소스로 옮겨놓을 필요가 있는 표면의 판단

Microsoft® Direct3D® 에서는, 시스템에 의한 텍스쳐 관리가 이행 되고 있어 텍스쳐는 퍼포먼스 최적화를 위해서(때문에) 확실히 로드 된다. Direct3D 가 관리하는 텍스쳐 리소스를관리하의 텍스쳐라고 부른다.

텍스쳐 매니저는, 텍스쳐의 최종 사용시를 나타내는 타임 스탬프를 이용해 텍스쳐를 추적한다. 다음에, LRU (least-recently-used) 알고리즘을 이용해, 삭제할 필요가 있는 텍스쳐를 판단한다. 메모리로부터 삭제하는 텍스쳐가 2 개 있는 경우, 텍스쳐의 우선도에 근거해 텍스쳐가 삭제된다. 2 개의 텍스쳐의 우선도가 같은 경우는, 최종 사용시가 새로운 (분)편의 텍스쳐가 삭제된다. 다만, 2 개의 텍스쳐로 타임 스탬프가 같은 경우는, 우선도의 낮은 텍스쳐가 먼저 삭제된다.

텍스쳐를 생성 할 경우에, 그 텍스쳐의 자동 텍스쳐 관리를 요구한다. C++ 어플리케이션으로 관리하의 텍스쳐를 취득하려면 ,IDirect3DDevice8::CreateTexture 를 호출해,Pool 파라미터에 D3DPOOL_MANAGED 를 지정해, 텍스쳐 리소스를 생성 한다. 다만, 텍스쳐의 생성 장소를 지정할 수 없다. 관리하의 텍스쳐를 생성 할 경우에는, D3DPOOL_DEFAULT 또는 D3DPOOL_SYSTEMMEM 플래그는 사용할 수 없다. 관리하의 텍스쳐를 생성 한 후,IDirect3DDevice8::SetTexture 메소드를 호출해, 그 관리하의 텍스쳐를 렌더링 디바이스의 텍스쳐 cascade의 스테이지로 설정할 수 있다.

텍스쳐 표면에 대해서 IDirect3DResource8::SetPriority 메소드를 호출해, 관리하의 텍스쳐에 우선도를 할당할 수가 있다.

Direct3D 에서는, 필요에 따라서 텍스쳐를 비디오 메모리에 자동적으로 다운로드할 수 있는 시스템은, 비로컬 비디오 메모리나 그 외의 요소가 사용 가능한지 어떤지에 의해, 관리하의 텍스쳐를 로컬 또는 비로컬 비디오 메모리에 캐쉬한다. 관리하의 텍스쳐가 캐쉬되는 장소는, 어플리케이션에 통지되지 않는다. 자동 텍스쳐 관리를 이용할 때에, 이 정보는 필요없다. 어플리케이션으로 사용하는 텍스쳐가 비디오 메모리에 들어가지 않을 정도(수록) 있는 경우, Direct3D 는 비디오 메모리로부터 낡은 텍스쳐를 삭제해, 새로운 텍스쳐용의 영역을 확보한다. 삭제한 텍스쳐를 재차 사용하는 경우, 시스템은 오리지날 시스템 메모리 텍스쳐 표면을 사용해, 텍스쳐를 비디오 메모리 캐쉬에 재로드한다. 텍스쳐의 재로드가 필요하지만, 이것을 실시하면 어플리케이션의 퍼포먼스가 저하한다.

텍스쳐 리소스를 갱신 또는 잠그는 것으로, 텍스쳐의 오리지날 시스템 메모리 카피를 동적으로 변경할 수 있다. 더티 표면이 검출되었을 경우 (갱신의 완료 후, 또는 표면의 락 해제시), 텍스쳐 매니저는 텍스쳐의 비디오 메모리 카피를 자동적으로 갱신한다. 이 때의 퍼포먼스는, 삭제된 텍스쳐를 재로드하는 경우와 같다.

게임에서 새로운 레벨로 옮길 때, 어플리케이션으로 비디오 메모리로부터 모든 관리하의 텍스쳐를 플래시 해야 할 때가 있다. 모든 관리하의 텍스쳐를 삭제하도록(듯이) 명시적으로 요구하려면 ,IDirect3DDevice8::ResourceManagerDiscardBytes 메소드를 호출해,Bytes 파라미터에 0 의 값을 지정한다. 이 메소드를 호출하면, 캐쉬되고 있는 로컬 또는 비로컬 비디오 메모리 텍스쳐가 Direct3D 에 의해 파기되지만, 오리지날 시스템 메모리 카피는 그대로 남는다.

리소스 관리의 상세한 것에 대하여는, 「리소스의 관리」를 참조할것.


텍스쳐 처리에 있어서의 하드웨어에 의한 제약

현재의 하드웨어가, Microsoft® Direct3D® 인터페이스에 의해 가능하게 되는 기능을 모두 이행 하고 있다고는 할 수 없다. 어플리케이션으로 유저의 하드웨어를 테스트해, 거기에 응해 렌더링 방법을 조정할 필요가 있다.

3D accelerator card의 상당수는, 블렌딩 유니트에의 인수로서 디퓨즈 보간값을 지원 하고 있지 않다. 다만, 텍스쳐 블렌딩을 실행할 때는, 어플리케이션으로 보간색데이터를 도입할 수 있다.

3D 하드웨어에 따라서는, 블렌딩 스테이지를 최초의 텍스쳐에 관련지을 수가 없는 경우도 있다. 이러한 어댑터의 경우, 어플리케이션에서는 경향 텍스쳐 세트의 2 번째 및 3 번째의 스테이지에서 블렌딩을 실행할 필요가 있다.

현시점에서는 많은 하드웨어로 제약이 있기 (위해)때문에,IDirect3DDevice8 가 제공하는 멀티 텍스쳐 블렌딩 인터페이스에 의한 트라이 리니어 밉맵 보간을 실행할 수 있는 디스플레이 어댑터는 소수이다. 특히, D3DTSS_MIPFILTER 텍스쳐 스테이지 스테이트를 D3DTEXF_LINEAR 로 설정할 수 있는 것은 거의 없다. 어플리케이션으로 멀티 패스 텍스쳐 블렌딩을 사용해 같은 이펙트를 얻는지, 넓게 지원 되고 있는 D3DTEXF_POINT 밉맵 필터 모드를 사용 하면이야 있고.


깊이 버퍼

여기에서는, 깊이 버퍼를 사용해 은선과 은면을 지우는 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 깊이 버퍼란
  • 깊이 버퍼의 사용법


깊이 버퍼란

z 버퍼 또는 w 버퍼로 불리는 깊이 버퍼란, Microsoft® Direct3D® 로 사용하는 깊이 정보를 저장 하는 디바이스의 프로퍼티이다. Direct3D 가 3D 신을 타겟 표면에 렌더링 하면 와, 어태치 된 깊이 버퍼 표면의 메모리를 작업 공간으로서 사용해, 라스터화한 다각형의 픽셀이 서로 어떻게 서로 가리는지 를 판정할 수 있다. Direct3D 는, 오프 스크린 Direct3D 표면을, 최종적인 칼라값을 기입하는 타겟으로서 사용한다. 렌더링 타겟 표면에 관련하는 깊이 버퍼 표면은, 장면에서의 가시적 픽셀 각각의 깊이를 Direct3D 에 알리는 깊이 정보의 저장에 사용한다.

깊이 버퍼링을 유효하게 해 3D 신을 라스터화할 때, 렌더링 표면 위에의 각 포인트가 조사할 수 있다. 깊이 버퍼의 값은, 포인트의 z 좌표 또는 동차 w 좌표 (투영 공간의 포인트의 (x, y, z, w) 위치 좌표가) 일수 있다. z 값을 사용하는 깊이 버퍼는 Z 버퍼로 불려 w 값을 사용하는 깊이 버퍼는 W 버퍼로 불린다. 어느 종류의 깊이 버퍼에도 이점과 결점이 있지만, 이것에 대해서는 다음에 설명한다.

테스트의 최초로, 깊이 버퍼의 깊이값을 장면에서 가능한 최대치로 설정한다. 렌더링 표면 위에의 칼라값은, 배경의 칼라값 또는 그 포인트의 배경 텍스쳐의 칼라값으로 설정한다. 장면의 각 다각형을 조사해, 렌더링 표면 위에의 경향 좌표 (x, y)에 해당될지 어떨지를 확인한다. 교차하는 경우, 현재의 포인트에서의 깊이값 (Z 버퍼의 Z 좌표 또는 W 버퍼의 W 좌표)을 테스트해, 깊이 버퍼에 이미 저장 되고 있는 깊이값보다 작은지 어떤지를 확인한다. 다각형의 깊이값이 작으면, 그 값이 깊이 버퍼에 저장 되어 그 다각형으로부터의 칼라값이 렌더링 표면 위에의 현재의 포인트에 기입해진다. 그 포인트에서의 다각형의 깊이값이 크면, 리스트의 다음의 다각형이 조사할 수 있다. 다음의 그림에, 이 처리를 나타낸다.

주 대부분의 어플리케이션에서는 이 기능을 사용하지 않지만, 깊이 버퍼에 들어가는 값과 렌더링 타겟 표면을 판정하기 위해서 Direct3D 가 사용하는 이 비교를 변경할 수 있다. 이것을 실시하려면 ,D3DRS_ZFUNC 렌더링 스테이트의 값을 변경하는 것.

현재는, 시판의 거의 모든 3D 가속기가, z 버퍼링을 지원 하고 있어, Z 버퍼가 가장 일반적인 깊이 버퍼의 종류가 되어 있다. 그러나, Z 버퍼에도 결점이 있다. 사용하는 수학적 처리가 원인으로, Z 버퍼에 생성되는 z 값은, Z 버퍼의 범위 (보통 0.0 에서 1.0) 전체에 균등하게 분산되지 않는 경향이 있다. 특히, 먼 클립면과 가까이의 클립면의 사이의 비율은, z 값의 불균일인 분산에 강한 영향을 준다. 가까이의 평면의 거리에 대한 먼 평면의 거리의 비율을 100% 로 했을 경우, 깊이 버퍼 범위의 90% 가 장면의 깊이 범위의 최초의 10% 에 소비된다. 오락이나 풍경의 시뮬레이션용의 전형적인 어플리케이션에서는, 비율 (먼 평면 / 가까이의 평면)이 어디에서라도 1000 에서 10000 의 사이일 필요가 있다. 비율이 1000 의 경우, 깊이 버퍼 범위의98% 가 깊이 범위의 최초의 2% 에 소비되어 비율이 높아지는 것에 따라 분산 상태가 나빠진다. 이것에 의해, 먼 오브젝트로 표면 디테일이 숨어 버리는 일이 있다. 이것은, 특히 16 비트 깊이 (가장 일반적인 비트 깊이) 버퍼를 사용하는 경우에 현저하다.

한편, W 깊이 버퍼에서는, Z 버퍼의 경우보다, 가까이의 클립면과 먼 클립면의 사이의 분산이 보다 균등이다. 따라서, 먼 클립면과 가까이의 클립면의 거리의 비율이 문제가 되지 않는다고 하는 이점이 있다. 이것에 의해, 어플리케이션은 큰 최대 범위를 지원 할 수 있다. 다만, 시점에 가까운 정확한 깊이 버퍼링이라고 해도 상대적인 것이다. W 깊이 버퍼는 완벽하지 않고, 가까이의 오브젝트의 표면 디테일이 숨는 일이 있다. 이제(벌써) 1 개의 결점은, 하드웨어 지원에 관계하는 것이다. 즉, w 버퍼링은 하드웨어로 z 버퍼링만큼 넓지는 지원되어 있지 않다.

z 버퍼링에는, 렌더링 때에 오버헤드가 있다. Z 버퍼를 사용할때에, 렌더링을 최적화하기 위해서 사용할 수 있는 다양한 기술이 있다. 상세한 것에 대하여는, 「Z 버퍼의 퍼포먼스」를 참조할것.

주 깊이값의 실제의 해석은, 3D 렌더러에 따라서 다르다.


깊이 버퍼의 사용법

여기에서는, 일반적인 깊이 버퍼의 사용 방법에 대해 설명한다.

  • 깊이 버퍼의 지원 상황의 문의
  • 깊이 버퍼의 생성
  • 깊이 버퍼링을 유효하게 한다
  • 깊이 버퍼의 취득
  • 깊이 버퍼의 클리어
  • 깊이 버퍼에의 기입해 액세스의 변경
  • 깊이 버퍼 비교 함수의 변경
  • Z 바이어스의 사용법

참조

깊이 버퍼란


깊이 버퍼의 지원 상황의 문의

다른 기능에서도 같이이지만, 어플리케이션으로 사용하는 드라이버가 모든 종류의 깊이 버퍼링을 지원 하고 있다고는 할 수 없다. 항상 드라이버의 기능을 조사할 필요가 있다. z 베이스의 깊이 버퍼링은 대부분의 디바이스로 지원 되고 있지만, w 베이스의 깊이 버퍼링은 일부의 디바이스로 밖에 지원되어 있지 않다. 지원되어 있지 않은 스킴을 유효하게 해도, 드라이버는 실패하지 않는다. 드라이버는 다른 깊이 버퍼링에 의지했을 경우에 따라서는 모든 깊이 버퍼링을 무효로 해, 그 결과, 렌더링 후의 장면에 깊이 소트에 의한 부자연스러운 효과가 나타나는 일이 있다.

Direct3D 디바이스를 생성 하기 전에 어플리케이션으로 사용하는 디스플레이 디바이스에 대해 Microsoft® Direct3D® 에 문의하는 것으로, 깊이 버퍼의 지원을 조사할 수가 있다. Direct3D 오브젝트로부터 깊이 버퍼링을 지원 하고 있다라는 보고가 있으면, 이 Direct3D 오브젝트로부터 생성 하는 하드웨어 디바이스는 z 버퍼링을 지원 한다.

C++ 어플리케이션으로 일반적인 깊이 버퍼링의 지원 상황을 조회하려면

깊이 버퍼링의 지원 상황을 문의하려면 ,IDirect3D8::CheckDeviceFormat 메소드를 사용한다. 다음의 코드는, 그 예를 나타내고 있다.

// 다음의 예에서는, pCaps 는 초기화된 D3DCAPS8 구조체에의
// 유효한 포인터이라고 가정하고 있다.
    if( FAILED( m_pD3D->CheckDeviceFormat( pCaps->AdapterOrdinal,
                                           pCaps->DeviceType, Format,
                                           D3DUSAGE_DEPTHSTENCIL,
                                           D3DRTYPE_SURFACE,
                                           D3DFMT_D16 ) ) )
        return E_FAIL;

CheckDeviceFormat 에서는, 해당하는 디바이스의 능력에 근거해, 생성 하는 디바이스를 선택할 수 있다. 이 경우, 16 비트의 깊이 버퍼를 지원 하지 않는 디바이스는 거부된다.

또,IDirect3D8::CheckDepthStencilMatch 를 사용해, 지원 되고 있는 스텐실 포맷이 디스플레이 모드로 렌더링 타겟의 포맷과 호환성이 있을지 어떨지, 특히, 깊이 포맷이 렌더링 타겟의 포맷과 동일한지 어떤지를 조사할 수가 있다.

다음의 코드에 나타내도록(듯이),CheckDepthStencilMatch 를 사용해, 스텐실이 렌더링 타겟과 호환성이 있을지 어떨지를 조사한다.

// 백 버퍼가 RTF 포맷으로,
// 스텐실 버퍼가 적어도 8 비트의 스텐실인 한편으로,
// RTF 포맷의 렌더링 타겟을 생성 할 수 없는 디바이스는 거부한다.
if( FAILED( m_pD3D->CheckDepthStencilMatch( pCaps->AdapterOrdinal,
                                            pCaps->DeviceType,
                                            AdapterFormat,
                                            RTFormat,
                                            D3DFMT_D24S8 ) ) )
        return E_FAIL;

드라이버로 깊이 버퍼가 지원 되고 있는 것을 알 수 있으면(자), 다음은 w 버퍼의 지원 상황을 조사할 수가 있다. 깊이 버퍼는 모든 소프트웨어 래스터라이저로 지원 되고 있지만, w 버퍼는 레퍼런스 래스터라이저로 밖에 지원되어 있지 않다. 이것으로는, 실제의 어플리케이션에서의 사용에 적합하지 않는다. 어플리케이션으로 사용하는 디바이스가 어떠한 종류에서도, w 베이스 깊이 버퍼링을 유효하게 하기 전에, w 버퍼의 지원 상황을 조사할 필요가 있다.

C++ 어플리케이션으로 w 버퍼의 지원 상황을 조사하려면

  1. 디바이스를 생성 한 후,IDirect3DDevice8::GetDeviceCaps 메소드를 호출해, 초기화한 D3DCAPS8 구조체를 건네준다.
  2. 이 호출의 뒤, 프리미티브의 렌더링에 관한 드라이버의 지원의 정보가 LineCaps 멤버에 들어간다.
  3. 이 구조체의 RasterCaps 멤버에 D3DPRASTERCAPS_WBUFFER 플래그가 포함되어 있는 경우, 드라이버는 해당의 프리미티브 타입에 대한 W 깊이 버퍼링을 지원 한다.

깊이 버퍼링의 일반 정보에 대해서는, 「깊이 버퍼란」을 참조할것.


깊이 버퍼의 생성

깊이 버퍼는 디바이스의 프로퍼티이다. Microsoft® Direct3D® 에 의해 관리되는 깊이 버퍼를 생성 하려면 ,D3DPRESENT_PARAMETERS 구조체의 적절한 멤버를 설정한다. 다음의 코드는, 그 예를 나타내고 있다.

    D3DPRESENT_PARAMETERS d3dpp;

    ZeroMemory( &d3dpp, sizeof(d3dpp) );
    d3dpp.Windowed               = TRUE;
    d3dpp.SwapEffect             = D3DSWAPEFFECT_COPY_VSYNC;
    d3dpp.EnableAutoDepthStencil = TRUE;
    d3dpp.AutoDepthStencilFormat = D3DFMT_D16;

EnableAutoDepthStencil 멤버를 TRUE 로 설정해, 어플리케이션의 깊이 버퍼를 관리하도록(듯이) Direct3D 에 지시한다. AutoDepthStencilFormat 는 유효한 깊이 버퍼 포맷으로 설정하는 것. D3DFMT_D16 플래그는, 16 비트의 깊이 버퍼를 사용할 수 있는 경우는, 그것을 지정한다.

다음의 IDirect3D8::CreateDevice 메소드의 호출에 의해, 깊이 버퍼를 생성 하는 디바이스를 생성 한다.

if( FAILED( g_pD3D->CreateDevice( D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd,
                                  D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                                  &d3dpp, &d3dDevice ) ) )
    return E_FAIL;

깊이 버퍼는, 디바이스의 렌더링 타겟으로서 자동적으로 설정된다. 디바이스가 리셋 되면(자), 깊이 버퍼는 자동적으로 파기되어 새로운 사이즈로 재생성 된다.

새로운 깊이 버퍼 표면을 생성 하려면 ,IDirect3DDevice8::CreateDepthStencilSurface 메소드를 사용한다.

디바이스의 새로운 깊이 버퍼 표면을 설정하려면 ,IDirect3DDevice8::SetRenderTarget 메소드를 사용한다

어플리케이션으로 깊이 버퍼를 사용하기 위해서는, 깊이 버퍼를 유효하게 할 필요가 있다. 상세한 것에 대하여는, 「깊이 버퍼링을 유효하게 한다」를 참조할것.


깊이 버퍼링을 유효하게 한다

「깊이 버퍼의 생성」으로 설명한 것처럼 깊이 버퍼를 생성 한 후,IDirect3DDevice8::SetRenderState 메소드를 호출해 깊이 버퍼링을 유효하게 한다. D3DRS_ZENABLE 렌더링 스테이트를 설정해 깊이 버퍼를 유효하게 한다. z 버퍼링을 유효하게 하려면 D3DZBUFFERTYPE 열거형의 D3DZB_TRUE 멤버 (또는 TRUE)를, w 버퍼링을 유효하게 하려면 D3DZB_USEW 를, 깊이 버퍼링을 무효로 하려면 D3DZB_FALSE (또는 FALSE)를 각각 설정한다.

주 w 버퍼링을 사용하려면 , 어플리케이션으로 Microsoft® Direct3D® 트랜스 폼 파이프라인을 사용하지 않는 경우여도, 대응하는 투영 행렬을 설정해야 한다. 적절한 투영 행렬의 설정에 대해서는, 「W 버퍼에 유효한 투영 행렬」을 참조할것. 「투영 트랜스 폼이란」으로 설명하는 투영 행렬은 적절한 것이다.


깊이 버퍼의 취득

다음의 샘플 코드는,IDirect3DDevice8::GetDepthStencilSurface 메소드를 사용해, 디바이스가 소유하는 깊이 버퍼 표면에의 포인터를 취득하는 방법을 나타내고 있다.

    LPDIRECT3DSURFACE8 pZBuffer;

    m_d3dDevice->GetDepthStencilSurface( &pZBuffer );


깊이 버퍼의 클리어

많은 C++ 어플리케이션은, 새로운 프레임을 렌더링 하기 전에 깊이 버퍼를 클리어 한다. IDirect3DDevice8::Clear 를 호출해 Flags 파라미터에 D3DCLEAR_ZBUFFER 를 지정하는 것으로써, Microsoft® Direct3D® 로 깊이 버퍼를 명시적으로 클리어 할 수 있다. Clear 메소드에서는,Z 파라미터에 임의의 깊이값을 지정할 수 있다.


깊이 버퍼에의 기입해 액세스의 변경

디폴트에서는, Microsoft® Direct3D® 시스템은 깊이 버퍼에의 기입이 용서되고 있다. 대부분의 어플리케이션에서는 깊이 버퍼에의 기입을 유효하게 한채로 있지만, Direct3D 시스템에 의한 깊이 버퍼에의 기입을 금지하는 것에 의해, 특수 효과를 생성할 수가 있다.

C++ 로 깊이 버퍼에의 기입을 무효로 하려면 ,State 파라미터를 D3DRS_ZWRITEENABLE 로 설정해,Value 파라미터를 0 으로 설정해 IDirect3DDevice8::SetRenderState 메소드를 호출한다.


깊이 버퍼 비교 함수의 변경

디폴트에서는, 렌더링 표면의 깊이 테스트를 실시할 때, Microsoft® Direct3D® 시스템은, 각 포인트에 대응하는 깊이값 (z 또는 w)이 깊이 버퍼의 기존의 값보다 작은 경우, 렌더링 타겟 표면을 갱신한다. C++ 어플리케이션으로, 시스템에 의한 깊이값의 비교 방법을 변경하려면 ,State 파라미터를 D3DRS_ZFUNC 로 설정해 IDirect3DDevice8::SetRenderState 메소드를 호출한다. Value 파라미터에는,D3DCMPFUNC 열거형의 값을 설정할 필요가 있다.


Z 바이어스의 사용법

3D 공간에서 동일 평면상에 있는 다각형은, 각각의 다각형에 Z 바이어스를 추가하는 것으로, 마치 동일 평면상에 없게 표시할 수가 있다. 이 기술은, 장면내의 그림자를 올바르게 표시하기 위해서 사용되는 것이 많다. 예를 들어, 벽위에의그림자의 깊이값이 벽의 깊이값과 같게 될 가능성이 있다. 최초로 벽을 렌더링 해, 다음에 그림자를 렌더링 하면, 그림자가 안보이는지, 또는 깊이에 의한 부자연스러운 효과가 보인다. 동일 평면상의 오브젝트의 렌더링순서를 반대로 하면, 이것과는 역의 이펙트를 얻을 수 있지만, 깊이에 의한 부자연스러운 효과가 남은채로 있는 것이 많다.

C++ 어플리케이션에서는, 동일 평면상의 다각형 세트를 렌더링 할 때에 시스템이 사용하는 z 값에 바이어스를 추가하는 것으로, 동일 평면상의 다각형을 올바르게 렌더링 할 수 있다. z 바이어스를 다각형 세트에 추가하려면 , 렌더링의 직전에 IDirect3DDevice8::SetRenderState 메소드를 호출한다. 이 때,State 파라미터를 D3DRS_ZBIAS 로 설정해,Value 파라미터를 0 으로 16 을 포함한 0 ~ 16 의 값으로 설정한다. z 바이어스값이 높을 정도(수록), 동일 평면상외의 다각형과 함께 표시 하면 와, 렌더링 하는 다각형이 보일 가능성이 높아진다.


스텐실 버퍼

여기에서는, 스텐실 버퍼의 목적과 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 스텐실 버퍼란
  • 스텐실 버퍼의 동작
  • 스텐실 버퍼의 커스터마이즈


스텐실 버퍼란

스텐실 버퍼는, 렌더링 타겟 표면의 픽셀 단위의 드로잉(Drawing)를 유효 또는 무효로 한다. 이 버퍼의 가장 기본적인 레벨에서는, 어플리케이션이 렌더링 한 화면의 부분을 마스크로 가리는 것이 가능하게 되어, 그 화면이 표시되지 않는다. 어플리케이션은 디조르브, 십-링, 및 아웃 라이닝등의 특수 효과를 위해서(때문에) 스텐실 버퍼를 사용하는 것이 많다. 상세한 것에 대하여는, 「스텐실 버퍼 기술」을 참조할것.

스텐실 버퍼 정보는, Z 버퍼 데이터에 파묻히고 있다. IDirect3D8::CheckDeviceFormat 메소드를 사용해, 하드웨어가 스텐실을 지원 하고 있을지 어떨지를 조사할 수가 있다. 다음의 코드에 예를 나타낸다.

// 8 비트의 스텐실 버퍼링을 실행할 수 없는 디바이스는 거부한다.
// 다음의 예에서는, pCaps 는 초기화된 D3DCAPS8 구조체에의
// 유효한 포인터이라고 가정하고 있다.

if( FAILED( m_pD3D->CheckDeviceFormat( pCaps->AdapterOrdinal,
                                       pCaps->DeviceType,
                                       Format,
                                       D3DUSAGE_DEPTHSTENCIL,
                                       D3DRTYPE_SURFACE,
                                       D3DFMT_D24S8 ) ) )
        return E_FAIL;

CheckDeviceFormat 에서는, 해당하는 디바이스의 능력에 근거해, 생성 하는 디바이스를 선택할 수 있다. 이 경우, 8 비트의 스텐실 버퍼를 지원 하지 않는 디바이스는 거부된다. 이것은 CheckDeviceFormat 로 사용할 수 있는 방법의 1 개에 지나지 않는다. 상세한 것에 대하여는, 「하드웨어 지원의 판정」을 참조할것.

디바이스에서의 스텐실 버퍼 제한을 조사하려면 , 지원 되고 있는 스텐실 버퍼 처리에 대해 D3DCAPS8 구조체의 StencilCaps 멤버에 문의한다.


스텐실 버퍼의 동작

Microsoft® Direct3D® 는, 스텐실 버퍼의 내용을 픽셀 단위에 조사한다. 스텐실 버퍼의 대응하는 값, 스텐실 참조값, 및 스텐실 마스크값을 사용해, 타겟 표면의 각 픽셀에 대한 테스트를 실시한다. 테스트에 패스 하면, Direct3D 는 액션을 실행한다. 이 테스트는 다음의 순서로 실행된다.

  1. 스텐실 참조값과 스텐실 마스크의비트적을 계산한다.
  2. 경향 픽셀에 대한 스텐실 버퍼값과 스텐실 마스크의비트적을 계산한다.
  3. 비교 함수를 사용해, 순서 1 으로 순서 2 의 결과를 비교한다.

이러한 스텝을 다음의 예로 가리킨다.

(StencilRef & StencilMask) CompFunc (StencilBufferValue & StencilMask)

여기서,StencilBufferValue 는, 경향 픽셀에 대한 스텐실 버퍼의 내용이다. 이 코드에서는, ampersand(&) (&) 기호는비트적연산을 나타내고 있다. StencilMask 는 스텐실 마스크,StencilRef 는 스텐실 참조값을 나타내고 있다. CompFunc 는 비교 함수이다.

이 스텐실 테스트에 패스 하면, 경향 픽셀은 타겟 표면에 기입해지지만, 실패했을 경우는 무시된다. 디폴트의 비교 처리에서는, 각 비트 연산의 결과에 관계없이, 픽셀이 기입해진다 (D3DCMP_ALWAYS). 이 동작을 변경하려면 , 목적의 비교 함수를 지정하는 D3DCMPFUNC 열거형의 멤버를 건네주어,D3DRS_STENCILFUNC 렌더링 스테이트의 값을 변경한다.


스텐실 버퍼의 커스터마이즈

어플리케이션에서는, 스텐실 버퍼의 처리를 커스터마이즈 할 수 있다. 어플리케이션에서는, 비교 함수, 스텐실 마스크, 및 스텐실 참조값을 설정할 수 있다. 또, 스텐실 테스트에 패스했을 경우 또는 실패했을 경우에 실행하는 Microsoft® Direct3D® 의 처리를 제어할 수도 있다. 상세한 것에 대하여는, 「스텐실 버퍼 스테이트」를 참조할것.


버텍스 버퍼

여기에서는, Microsoft® Direct3D® 어플리케이션에 대해 버텍스 버퍼를 이해해, 사용하는데 필요한 개념을 설명한다. 설명하는 주제는, 다음과 같다.

  • 버텍스 버퍼란
  • 버텍스 버퍼의 기술
  • 버텍스 버퍼의 풀과 사용
  • FVF 버텍스 버퍼
  • 디바이스의 종류와 버텍스 처리의 요건
  • 버텍스 버퍼의 사용법


버텍스 버퍼란

버텍스 버퍼란,IDirect3DVertexBuffer8 인터페이스로 나타내지는, 버텍스 데이터를 포함한 메모리 버퍼이다. 버텍스 버퍼는, 트랜스 폼 끝난 버텍스, 트랜스폼 되지 않은의 버텍스, 라이팅 끝난 버텍스, 라이팅 계산 되지 않은의 버텍스 등,IDirect3DDevice8 인터페이스의 버텍스 버퍼 렌더링 메소드로 렌더링 가능한 모든 종류의 버텍스를 포함할 수가 있다. 버텍스 버퍼내의 버텍스를 처리해, 트랜스 폼, 라이팅, 클리핑 플래그의 생성등의 처리를 실행할 수 있는 트랜스 폼은 항상 실행된다.

버텍스 버퍼는 유연해서, 트랜스 폼 된 지오메트리를 재사용하기 위한 이상적인 스테이지 포인트가 된다. 단일의 버텍스 버퍼를 생성 해, 버텍스를 트랜스 폼, 라이팅을 적용, 및 그 버텍스 버퍼에 버텍스를 잘라내, 비록 인타리브 된 렌더링 스테이트가 변화했을 경우에서도, 장면의 모델을 몇번도 재트랜스 폼 하지 않고 렌더링 할 수 있다. 이것은, 멀티 텍스쳐를 사용하는 모델의 렌더링 시에 편리하다. 지오메트리를 한 번 트랜스 폼 하면, 요구된 텍스쳐의 변경에 맞추어 인타리브 해, 필요에 따라서 그 일부를 렌더링 할 수 있다. 버텍스를 처리한 다음에 변경한 렌더링 스테이트는, 다음에 버텍스를 처리할 경우에 유효하게 된다. 상세한 것에 대하여는, 「버텍스의 처리」를 참조할것.


버텍스 버퍼의 기술

버텍스 버퍼의 기술은, 능력에 대해 실시한다. 버텍스 버퍼는, 시스템 메모리내에만 존재할 수 있는지, 기입 조작인 만큼 사용되는지, 버텍스 버퍼가 포함할 수가 있는 버텍스의 종류와 수등을 기술한다. 이러한 특성은 모두 D3DVERTEXBUFFER_DESC 구조체안에 보관 유지된다.

버텍스 버퍼의 기술에 의해, 어플리케이션은, 기존 버퍼가 생성 된 방법 및 생성 후에 최적화되었는지 어떠했는지를 알 수 있다. 시스템이 생성이 끝난 버텍스 버퍼의 능력을 기입할 수 있도록(듯이), 공백의 기술 구조체를 준비한다. 이 태스크의 상세한 것에 대하여는, 「버텍스 버퍼의 기술의 취득」을 참조할것.

Format 멤버는, 버텍스 버퍼인 것을 나타내는 D3DFMT_VERTEXDATA 로 설정된다. Type 는, 버텍스 버퍼의 리소스 타입을 식별한다. Usage 구조체의 멤버는, 일반적인 능력 플래그를 저장 한다. D3DUSAGE_SOFTWAREPROCESSING 플래그는, 그 버텍스 버퍼가 소프트웨어 버텍스 처리에 사용되는 것을 나타낸다. Usage 에 D3DUSAGE_WRITEONLY 플래그가 있는 경우는, 버텍스 버퍼 메모리는 기입해 처리에만 사용된다. 이것에 의해 드라이버는 해방되어 고속 처리와 고속 렌더링을 가능하게 하는 최적인 메모리 위치에 버텍스 데이터가 배치된다. D3DUSAGE_WRITEONLY 플래그가 사용되어 있지 않은 경우, 드라이버는, 읽기 처리에 효율이 나쁜 위치에 데이터를 배치하지 않게 한다. 이것에 의해, 처리 속도나 렌더링 속도가 다소 희생이 된다. 이 플래그가 사용되어 있지 않은 경우, 어플리케이션은, 버텍스 버퍼내의 데이터로 읽고 쓰기의 처리를 실행 하면 보여진다.

Pool 는, 버텍스 버퍼에 할당할 수 있는 메모리 클래스를 지정한다. D3DPOOL_SYSTEMMEM 플래그는, 시스템이 시스템 메모리내에 버텍스 버퍼를 생성 한 것을 나타낸다.

Size 멤버는, 단지 버텍스 버퍼 데이터의 사이즈를 바이트수로 저장 한다. FVF 멤버는, 버퍼가 저장 하는 버텍스의 타입을 식별하는유연한 버텍스 포맷 플래그의 편성을 저장 한다.


버텍스 버퍼의 풀과 사용

버텍스 버퍼는,IDirect3DDevice8::CreateVertexBuffer 메소드로 생성 해, 이 메소드는 풀 (메모리 클래스) 파라미터와 사용 파라미터를 취한다. CreateVertexBuffer 는, 고정 기능 버텍스 처리 또는 프로세스 버텍스의 출력으로서 사용하기 위해(때문에), 유연한 버텍스 포맷 (FVF) 코드를 지정해 생성 할 수도 있다. 상세한 것에 대하여는, 「FVF 버텍스 버퍼」 및 「전송처 버텍스 버퍼의 FVF 사용 설정」을 참조할것.

D3DUSAGE_SOFTWAREPROCESSING 플래그는, 그 디바이스에 대해서 믹스 모드 또는 소프트웨어 버텍스 처리 (D3DCREATE_MIXED_VERTEXPROCESSING / D3DCREATE_SOFTWARE_VERTEXPROCESSING)가 유효하게 되어 있을 때 설정할 수 있다. D3DUSAGE_SOFTWAREPROCESSING 는 믹스 모드에서의 소프트웨어 버텍스 처리에 사용하는 버퍼로 설정해, 믹스 모드에서의 하드웨어 버텍스 처리 (D3DCREATE_HARDWARE_VERTEXPROCESSING) 시에 최고의 퍼포먼스를 얻고 싶을 때는 설정해서는 안 된다. 다만, 단일의 버퍼가 하드웨어 및 소프트웨어 버텍스 처리의 양쪽 모두로 사용되는 경우, D3DUSAGE_SOFTWAREPROCESSING 를 설정하는 이외의 옵션은 없다. D3DUSAGE_SOFTWAREPROCESSING 는, 소프트웨어 디바이스 뿐만이 아니라 믹스에도 설정할 수가 있다.

버텍스 처리가 하드웨어로 실행되는 경우에서도, D3DPOOL_SYSTEMMEM 를 지정하면, 버텍스 버퍼와 인덱스 버퍼를 시스템 메모리내에 강제적으로 배치할 수가 있다. 이것은, 드라이버에 의해 이러한 버퍼가 AGP 메모리에 넣어졌을 때에, 페이지 락 되는 메모리가 너무 많아 지지 않게 하는 방법이다.


FVF 버텍스 버퍼

유효한 FVF 코드로 IDirect3DDevice8::CreateVertexBuffer 의 FVF 파라미터를 제로 이외의 값으로 설정 하면, 버퍼의 내용은 FVF 코드에 의해 특성 붙일 수 있다. FVF 코드로 생성 된 버텍스 버퍼를, FVF 버텍스 버퍼라고 한다. IDirect3DDevice8 의 메소드나 사용에 따라서는, FVF 버텍스 버퍼를 필요로 하는 경우와 비 FVF 버텍스 버퍼를 필요로 하는 경우가 있다. FVF 버텍스 버퍼는,IDirect3DDevice8::ProcessVertices 의 전송처 버텍스 버퍼 인수로서 필요하다.

FVF 버텍스 버퍼는, 임의의 스트림 번호의 전송원데이터 스트림에 바인드 할 수 있다. 다만, FVF 버텍스 버퍼는, 프로그램 된 버텍스 쉐이더에의 입력으로서 사용할 수 없다.

FVF 버텍스 버퍼에 D3DFVF_XYZRHW 컴퍼넌트가 있는 경우는, 그 버퍼내의 버텍스가 처리되고 있는 것을 나타낸다. ProcessVertices 전송처 버텍스 버퍼에 사용되는 버텍스 버퍼는, 처리 후의 버텍스 버퍼가 아니면 안된다. 고정 기능 쉐이더의 입력에 사용되는 버텍스 버퍼는, 처리전이라도 처리 다음에도 상관없다. 버텍스 버퍼가 처리 후의 경우에는, 쉐이더는 우회도로 되어 프리미티브 클리핑 및 셋업 모듈에 직접 데이터가 건네받는다.

FVF 버텍스 버퍼는, 버텍스 쉐이더와 함께 사용할 수가 있다. 또, 버텍스 스트림은, 비 FVF 버텍스 버퍼가 나타낼 수 있는 버텍스 포맷과 같은 버텍스 포맷을 나타낼 수가 있다. 다른 버텍스 버퍼로부터의 데이터를 입력하기 위해서 사용할 필요는 없다. 새로운 버텍스 스트림이 가지는 유연성에 의해, 데이터를 따로 유지할 필요가 있는 어플리케이션에서는, 보다 고속처리를 실시할 수 있게 되지만, 이것은 필수는 아니다. 어플리케이션이 미리 인터리브 된 데이터를 보관 유지할 수 있는 경우는, 퍼포먼스가 향상한다. 어플리케이션이 각 렌더링 호출전에 데이터를 인터리브 할 뿐(만큼)의 경우는, 어플리케이션 프로그래밍 인터페이스 (API) 또는 하드웨어에 복수의 스트림으로 이 처리를 실시하게 한 없으면 안 된다.

버텍스의 퍼포먼스로 가장 중요한 (일)것은, 32 바이트의 버텍스를 사용해, 좋은 캐쉬순서를 보관 유지하는 것이다.


디바이스의 종류와 버텍스 처리의 요건

트랜스 폼이나 라이팅등의 버텍스 처리의 퍼포먼스는, 버텍스 버퍼의 메모리내에서의 위치 좌표와 사용되는 렌더링 디바이스의 종류에 크게 의존한다. 버텍스 버퍼를 생성 하면, 어플리케이션은 그 버텍스 버퍼에의 메모리 할당을 제어할 수 있다. D3DPOOL_SYSTEMMEM 메모리 플래그가 설정되어 있을 때는, 시스템 메모리내에 버텍스 버퍼가 생성 된다. D3DPOOL_DEFAULT 메모리 플래그를 사용 하면, 버텍스 버퍼용의 메모리의 최선의 할당 장소를 디바이스 드라이버가 결정되어, 이와 같이 해 결정된 메모리를 많은 경우 드라이버 최적화 메모리라고 부른다. 드라이버 최적화 메모리로서는, 로컬 비디오 메모리, 비로컬 비디오 메모리, 또는 시스템 메모리가 지정된다.

D3DUSAGE_SOFTWAREPROCESSING 동작 플래그를 설정해 IDirect3DDevice8::CreateVertexBuffer 메소드를 호출하면, 버텍스 버퍼는 소프트웨어 버텍스 처리에 사용된다. 이 플래그는, 혼합 버텍스 처리 모드에 있어서의 소프트웨어 버텍스 처리로 필요하다. 이 플래그는, 소프트웨어 버텍스 처리 모드에서는 사용할 수 있지만, 하드웨어 버텍스 처리 모드에서는 사용할 수 없다. 소프트웨어 버텍스 처리에 사용되는 버텍스 버퍼를 다음에 나타낸다.

  • IDirect3DDevice8::ProcessVertices 의 모든 입력 스트림.
  • 소프트웨어 버텍스 처리에 있어서의,IDirect3DDevice8::DrawPrimitive 및 IDirect3DDevice8::DrawIndexedPrimitive 의 모든 입력 스트림. 상세한 것에 대하여는, 「D3DRS_SOFTWAREVERTEXPROCESSING 」를 참조할것.

버텍스 버퍼가 시스템 메모리에 있는지, 드라이버 최적화 메모리에 있을까를 조사할 필요가 있는 것은, 텍스쳐의 경우와 같은 이유로부터이다. 하드웨어에 있어서의 버텍스 처리 (트랜스 폼이나 라이팅등)에 최적인 것은, 드라이버 최적화 메모리에 할당할 수 있었던 버텍스 버퍼로, 소프트웨어에서의 버텍스 처리에 최적인 것은, 시스템 메모리에 할당할 수 있었던 버텍스 버퍼이다. 텍스쳐의 경우, 하드웨어 라스터화에는, 드라이버 최적화 메모리에 할당할 수 있었던 텍스쳐가 최적이어, 소프트웨어 라스터화에는, 시스템 메모리에 할당할 수 있었던 텍스쳐가 최적이다.

주 Microsoft® Direct3D® for Microsoft DirectX® 8.0 은,ProcessVertices 메소드로 프리미티브를 렌더링 하지 않는 스탠드얼론 버텍스 처리를 지원 한다. 이 스탠드얼론 버텍스 처리는, 항상 호스트 프로세서 위에의 소프트웨어로 실행된다. 이 때문에,IDirect3DDevice8::SetStreamSource 의 전송원으로서 설정되는 버텍스 버퍼는, D3DUSAGE_SOFTWAREPROCESSING 플래그로 생성 할 필요가 있다. ProcessVertices 의 기능은,IDirect3DDevice8::DrawPrimitive 메소드 및 IDirect3DDevice8::DrawIndexedPrimitive 메소드가 소프트웨어 버텍스 처리에 대해 제공하는 기능과 같다. 상세한 것에 대하여는, 「버텍스의 처리」를 참조할것.

어플리케이션이 독자적인 버텍스 처리를 실행한다, 또, 트랜스 폼이 끝난 상태로, 라이팅이 적용되어 클리핑 된 버텍스를 버텍스 버퍼 렌더링 메소드에 건네주는 경우, 어플리케이션은 드라이버 최적화 메모리에 할당할 수 있었던 버텍스 버퍼에 버텍스를 직접 기입할 수가 있다. 이 방법에 의해, 이후의 장황한 카피 처리를 방지한다. 다만, 드라이버 최적화 메모리로부터 호스트에 의해 실행되는 독해 처리는, 매우 처리 속도가 늦은 일이 있기 (위해)때문에, 어플리케이션이 버텍스 버퍼로부터 데이터를 다시 읽는 경우에는, 이 방법은 잘 기능하지 않는다. 따라서, 어플리케이션으로 처리중에 읽어내, 또는 버퍼에의 데이터 기입을 불규칙하게 실행할 필요가 있는 경우는, 시스템 메모리에 버텍스 버퍼를 할당하면(자) 좋다.

Direct3D 버텍스 처리 기능을 사용하는 경우 (트랜스폼 되지 않은의 버텍스를 버텍스 버퍼 렌더링 메소드에 건네줘), 디바이스의 종류와 디바이스 생성 플래그에 응해, 하드웨어 또는 소프트웨어의 어느쪽이든으로 처리가 실행된다. 최종적으로 모든 경우에 대해 최선의 퍼포먼스를 얻을 수 있도록(듯이), 버텍스 버퍼는 풀 D3DPOOL_DEFAULT 에 할당하는 것을 추천 한다. 디바이스가 하드웨어 버텍스 처리를 사용하는 경우는, 플래그 D3DUSAGE_DYNAMIC 및 D3DUSAGE_WRITEONLY 에 근거해 실행할 수 있는 추가의 최적화 기능이 몇개인가 있다. 이러한 플래그의 사용 방법의 상세한 것에 대하여는, 「IDirect3DDevice8::CreateVertexBuffer 」를 참조할것.


버텍스 버퍼의 사용법

여기에서는, 버텍스 버퍼 처리로 어플리케이션이 실행하는 일반적인 태스크에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 버텍스 버퍼의 생성
  • 버텍스 버퍼의 내용에의 액세스
  • 버텍스의 처리
  • 버텍스 버퍼로부터의 렌더링
  • 버텍스 버퍼의 기술의 취득


버텍스 버퍼의 생성

5 개의 파라미터를 받는 IDirect3DDevice8::CreateVertexBuffer 메소드를 호출해, 버텍스 버퍼 오브젝트를 생성 한다. 제 1 파라미터는, 버텍스 버퍼의 길이를 바이트수로 지정한다. 버텍스 포맷의 사이즈를 바이트 단위로 판정하려면 ,sizeof 연산자를 사용한다. 다음에, 커스텀 버텍스 포맷의 예를 나타낸다.

struct CUSTOMVERTEX {
        FLOAT x, y, z;
        FLOAT rhw;
        DWORD color;
        FLOAT tu, tv;   // 텍스쳐 좌표.
};

// 커스텀 버텍스 구조체를 기술하는 커스텀 FVF.
#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZRHW | D3DFVF_DIFFUSE | D3DFVF_TEX1)

4 개의 CUSTOMVERTEX 구조체를 보관 유지하는 버텍스 버퍼를 생성 하려면 ,Length 파라미터에 [4*sizeof(CUSTOMVERTEX)] 를 지정한다.

제 2 파라미터는, 사용 컨트롤 세트이다. 특히, 이 값은, 버텍스 버퍼가 표시 영역외의 버텍스의 클리핑 정보를 (클립 플래그 형식에서) 보관 유지할 수가 있을지 어떨지를 지정한다. 클립 플래그를 저장 할 수 없는 버텍스 버퍼를 생성 하려면 ,Usage 파라미터에 D3DUSAGE_DONOTCLIP 플래그를 포함한다. D3DUSAGE_DONOTCLIP 플래그는, 버텍스 버퍼가 트랜스 폼 끝난 버텍스를 보관 유지하도록(듯이) 지시했을 경우, 즉, D3DFVF_XYZRHW 플래그가 FVF 멤버에 포함되는 경우만 적용된다. 트랜스폼 되지 않은의 버텍스 (D3DFVF_XYZ 플래그)를 버퍼에 포함하도록 지시했을 경우,CreateVertexBuffer 메소드는 D3DUSAGE_DONOTCLIP 플래그를 무시한다. 클리핑 플래그는 추가 메모리를 점유 하기 위한(해), 클리핑 가능한 버텍스 버퍼는, 클리핑 플래그를 포함하지 않는 버텍스 버퍼보다 약간 커진다. 리소스는 버텍스 버퍼가 생성 될 때 할당할 수 있기 (위해)때문에, 클리핑 가능한 버텍스 버퍼는 먼저 요구해 두지 않으면 안 된다.

제 3 파라미터 FVF 는,유연한 버텍스 포맷 플래그의 편성에 의해, 버텍스 버퍼의 버텍스 포맷을 기술한다. 이 파라미터에 0 을 지정했을 경우, 버텍스 버퍼는 비 FVF 버텍스 버퍼가 된다. 상세한 것에 대하여는, 「FVF 버텍스 버퍼」를 참조할것. 제 4 파라미터는, 버텍스 버퍼를 저장 하는 메모리 클래스를 지정한다.

CreateVertexBuffer 가 받는 마지막 파라미터는, 호출이 성공했을 때에 버텍스 버퍼 오브젝트의 새로운 IDirect3DVertexBuffer8 인터페이스에의 포인터가 저장 되는 변수의 주소이다.

주 클립 플래그를 지원 하지 않고 생성 된 버텍스 버퍼에 클립 플래그를 생성할 수 없다.

다음의 코드는, C++ 로 버텍스 버퍼를 생성 하는 방법을 나타내고 있다.

    // 이 예에서는, 변수 d3dDevice 는,
    // Direct3DDevice 오브젝트에 의해 공개되는 IDirect3DDevice8 인터페이스에의 주소이며,
    // g_pVB 는, LPDIRECT3DVERTEXBUFFER8 형의 변수이다.

// 커스텀의 버텍스 타입.
struct CUSTOMVERTEX {
        FLOAT x, y, z;
        FLOAT rhw;
        DWORD color;
        FLOAT tu, tv;   // 텍스쳐 좌표.
};

#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZRHW | D3DFVF_DIFFUSE | D3DFVF_TEX1)

    // 클리핑 가능한 버텍스 버퍼를 생성 한다. 3 개의 CUSTOMVERTEX 구조체를 보관 유지하는데 충분한 메모리를
    // 디폴트의 메모리 풀에 할당한다.

    if( FAILED( d3dDevice->CreateVertexBuffer( 3*sizeof(CUSTOMVERTEX),
                                                  0 /* 사용 */, D3DFVF_CUSTOMVERTEX,
                                                  D3DPOOL_DEFAULT, &g_pVB ) ) )
        return E_FAIL;


버텍스 버퍼의 내용에의 액세스

버텍스 버퍼 오브젝트를 사용하면(자), 버텍스 데이터에 할당할 수 있었던 메모리에 어플리케이션이 직접 액세스 할 수 있다. IDirect3DVertexBuffer8::Lock 메소드를 호출해 버텍스 버퍼 메모리에의 포인터를 취득해, 다음에 필요에 따라서 메모리에 액세스 해 새로운 버텍스 데이터를 버퍼로 설정하는지, 이미 설정되어 있는 데이터를 읽어낸다. Lock 메소드는 4 개의 파라미터를 받는다. 제 1 파라미터 OffsetToLock 는, 버텍스 데이터에의 오프셋(offset)이다. 제 2 파라미터는 버텍스 데이터의 사이즈를 바이트수로 가리킨다. Lock 메소드가 받는 제 3 파라미터 ppbData 는, 호출이 성공했을 경우에, 버텍스 데이터를 포인트 하는 BYTE 포인터의 주소이다.

마지막 파라미터 Flags 는, 메모리의 락 방법을 시스템에 알린다. 이 파라미터를 사용해, 버퍼내의 데이터에 어플리케이션이 어떻게 액세스 하는지를 나타낼 수가 있다. 어플리케이션이 버텍스 데이터에 액세스 하는 방법으로 응해,Flags 파라미터에 정수를 지정한다. 이것에 의해, 드라이버는 메모리를 잠그어, 요구되고 있는 액세스 타입으로, 최고의 퍼포먼스를 제공한다. 어플리케이션이 버텍스 버퍼 메모리로부터 읽기만을 실시하는 경우는, D3DLOCK_READONLY 플래그를 사용한다. 이 플래그를 포함하면(자), Microsoft® Direct3D® 가 내부 순서를 최적화하므로 효율이 오른다. 다만, 메모리에의 액세스는 읽어내기 전용이 된다.

버텍스 데이터의 설정 또는 읽기가 종료하면(자),IDirect3DVertexBuffer8::Unlock 메소드를 호출한다. 다음의 코드에 예를 나타낸다.

// 이 코드예에서는, g_pVB 는 LPDIRECT3DVERTEXBUFFER8 형의 변수이며,
// g_Vertices 는 버텍스에 올바르고
// 초기화되고 있는 것과 가정하고 있다.

// 버텍스 버퍼에 데이터를 설정하려면 , 버텍스에의
// 액세스를 취득하기 위해(때문에), 버퍼를 잠글 필요가 있다. 이것은, 버텍스 버퍼가 디바이스 메모리에 존재하고 있을 가능성이 있기 위해서(때문에)
// 필요한 메카니즘이다.
VOID* pVertices;

if( FAILED( g_pVB->Lock( 0,                  // 버퍼의 선두로부터
                                             // 값을 저장 한다.
                         sizeof(g_Vertices), // 로드하는 데이터의 사이즈.

                         (BYTE**) &pVertices, // 돌려주어지는 버텍스 데이터.
                         0 ) ) )             // 락에 디폴트 플래그를 보낸다.

    return E_FAIL;

memcpy( pVertices, g_Vertices, sizeof(g_Vertices) );
g_pVB->Unlock();

퍼포먼스의 주의 D3DUSAGE_WRITEONLY 플래그로 버텍스 버퍼를 생성 했을 경우, D3DLOCK_READONLY 락킹 플래그는 사용할 수 없다. 어플리케이션이 버텍스 버퍼 메모리로부터 읽기만을 실시하는 경우는, D3DLOCK_READONLY 플래그를 사용한다. 이 플래그를 포함하면(자), Direct3D 가 내부 순서를 최적화하므로 효율이 오른다. 다만, 메모리에의 액세스는 읽어내기 전용이 된다.

Lock 메소드의 Flags 파라미터에 D3DLOCK_DISCARD 또는 D3DLOCK_NOOVERWRITE 를 사용하는 방법의 상세한 것에 대하여는, 「동적인 버텍스 및 인덱스 버퍼의 사용법」을 참조할것.

C++ 에서는, 버텍스 버퍼에 할당할 수 있고 있는 메모리에 직접 액세스 하므로, 어플리케이션이 목적의 메모리에 올바르게 액세스 하도록(듯이) 주의 해야 한다. 그렇지 않으면 부정한 메모리가 렌더링 될 우려가 있다. 어플리케이션으로 사용하는 버텍스 포맷의 보폭을 이용해, 할당할 수 있고 있는 버퍼의 버텍스로부터 다음의 버텍스로 이동한다. 버텍스 버퍼 메모리는, 유연한 버텍스 포맷으로 지정된 버텍스의 단순한 배열이다. 정의하는 임의의 버텍스 포맷 구조체의 보폭을 사용한다. 버텍스 버퍼의 기술에 포함되는유연한 버텍스 포맷 플래그를 조사하는 것으로, 실행시에 각 버텍스의 보폭을 계산할 수 있다. 다음의 표는, 각 버텍스의 성분의 사이즈를 나타내고 있다.

버텍스 포맷 플래그 | 사이즈
D3DFVF_DIFFUSE | sizeof(DWORD)
D3DFVF_NORMAL | sizeof(float) × 3
D3DFVF_SPECULAR | sizeof(DWORD)
D3DFVF_TEXn | sizeof(float) × n × t
D3DFVF_XYZ | sizeof(float) × 3
D3DFVF_XYZRHW | sizeof(float) × 4

버텍스 포맷에 존재하는 텍스쳐 좌표의 수는, D3DFVF_TEXn 플래그로 기술된다 (n 는 0 ~ 8 의 값). 그 수만큼 있는 텍스쳐 좌표로 필요한 메모리를 계산하려면 , 텍스쳐 좌표 세트의 수에 텍스쳐 좌표 1 세트분 (1 ~ 4 개의 부동 소수)의 사이즈를 탄다.

특정의 버텍스에 액세스 하려면 , 합계 버텍스 보폭을 사용해, 메모리 포인터를 필요한 만큼 인크리먼트(increment) 또는 감소 한다.


버텍스의 처리

버텍스 버퍼에서의 버텍스 처리는, 디바이스의 현재의 트랜스 폼 행렬에 적용할 수 있다. 옵션으로, 라이팅, 클립 플래그의 생성, 범위의 갱신등의 버텍스 처리도 적용할 수 있다. 설명하는 주제는, 다음과 같다.

  • 고정 기능에 의한 버텍스 처리
  • 프로그램에 의한 버텍스 처리


고정 기능에 의한 버텍스 처리

여기에서는, 고정 기능에 의한 버텍스 처리에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 고정 기능에 의한 버텍스 처리에 대해
  • 전송처 버텍스 버퍼의 FVF 사용 설정


고정 기능에 의한 버텍스 처리에 대해

고정 기능 버텍스 파이프라인에서는, 버텍스 버퍼에서의 버텍스 처리는, 디바이스의 현재의 트랜스 폼 행렬에 적용할 수 있다. 옵션으로, 라이팅, 클립 플래그의 생성, 범위의 갱신등의 버텍스 처리도 적용할 수 있다. 고정 기능에 의한 버텍스 처리를 사용하는 경우, 전송처 버텍스 버퍼의 요소의 수정 처리는 D3DPV_DONOTCOPYDATA 플래그에 의해 제어된다. 이 플래그는, 고정 기능에 의한 버텍스 처리에만 적용할 수 있다. IDirect3DDevice8 인터페이스는, 버텍스 처리용의 IDirect3DDevice8::ProcessVertices 메소드를 공개한다. 버텍스 쉐이더의 버텍스를 입력 데이터 스트림 세트에 처리해,ProcessVertices 메소드를 호출해 1 개의 인터리브 된 버텍스 데이터의 스트림을 생성한다. 이 메소드는, 메소드가 타겟으로 하는 버텍스의 위치와 양, 전송처 버텍스 버퍼, 및 처리 옵션을 기술하는 5 개의 파라미터를 받는다. 호출 후, 처리된 버텍스 데이터는 전송처 버퍼에 저장 된다.

제1 파라미터 SrcStartIndex, 제 2 파라미터 DestIndex, 제 3 파라미터 VertexCount 는, 각각, 최초로 로드 되는 버텍스의 인덱스, 버텍스가 배치되는 전송처 버텍스 버퍼의 인덱스, 처리해 전송처 버퍼에 배치하는 버텍스의 총수를 나타낸다. 제 4 파라미터 pDestBuffer 에는, 전송원버텍스를 받는 버텍스 버퍼 오브젝트의 IDirect3DVertexBuffer8 의 주소를 설정한다. SrcStartIndex 는, 메소드가 버텍스의 처리를 시작 하는 인덱스를 지정한다.

마지막 파라미터 Flags 는, 메소드의 특수한 처리 옵션을 지정한다. 이 파라미터를 0 으로 설정 하면, 디폴트의 버텍스 처리가 실행되어 D3DPV_DONOTCOPYDATA 를 설정 하면, 어떠한 상황에 있어 처리가 최적화된다. Flags 를 0 으로 설정했을 때는, 버텍스 처리의 영향을 받지 않는 전송처 버텍스 버퍼의 버텍스 포맷의 버텍스의 성분은, 버텍스 쉐이더로부터 카피하는지, 0 으로 설정된다. 다만, D3DPV_DONOTCOPYDATA 를 사용 하면, Microsoft® Direct3D® 에 의해 색 및 좌표 정보가 생성되지 않는 이상ProcessVertices 에 의해 색 및 좌표 정보는 덧쓰기되지 않는다. 라이팅이 유효, 즉 D3DRS_LIGHTING 가 TRUE 때는, 디퓨즈색이 생성된다. 라이팅이 유효해 스펙큐러가 유효, 즉 D3DRS_SPECULARENABLE 및 D3DRS_LIGHTING 가 TRUE 때는, 스펙큐러색이 생성된다. 스펙큐러색은, fog가 유효 때도 생성된다. 텍스쳐 좌표는, 텍스쳐 트랜스 폼 또는 텍스쳐 생성이 유효 때에 생성된다. ProcessVertices 는, 현재의 렌더링 스테이트를 사용해, 실행하는 버텍스 처리를 결정한다.

디바이스에 의한 버텍스 처리의 제한을 판정하려면 ,D3DCAPS8 구조체의 VertexProcessingCaps 멤버에, 지원 하는 버텍스 처리 능력을 문의한다.


전송처 버텍스 버퍼의 FVF 사용 설정

IDirect3DDevice8::ProcessVertices 메소드에서는, 전송처 버텍스 버퍼의유연한 버텍스 포맷 플래그에 대해서 특수한 설정이 필요하다. 유연한 버텍스 포맷 (FVF)의 사용 설정에는, 버텍스 처리의 현재의 설정과의 호환성이 없으면 안 된다.

고정 기능에 의한 버텍스 처리의 경우,ProcessVertices 는 이하와 같은 FVF 설정을 필요로 한다.

  • 위치 좌표의 타입은 항상 D3DFVF_XYZRHW 이며, D3DFVF_XYZ 및 D3DFVF_XYZB1 ~ D3DFVF_XYZB5 는 무효이다.
  • D3DFVF_NORMAL, D3DFVF_RESERVED0, 및 D3DFVF_RESERVED2 플래그는 설정하지 않는다.
  • 이하의 조건의 OR 연산자가 TRUE 를 돌려주는 경우, D3DFVF_DIFFUSE 플래그를 설정할 필요가 있다.
    • 라이팅이 유효, 즉 D3DRS_LIGHTING 가 TRUE 이다.
    • 라이팅이 무효이며, 입력 버텍스 스트림에 디퓨즈색이 있어, D3DPV_DONOTCOPYDATA 가 설정되어 있지 않다.
  • 이하의 조건의 OR 연산자가 TRUE 를 돌려주는 경우, D3DFVF_SPECULAR 플래그를 설정할 필요가 있다.
    • 라이팅이 유효해 스펙큐러색이 유효, 즉 D3DRS_SPECULARENABLE 가 TRUE 이다.
    • 라이팅이 무효이며, 입력 버텍스 스트림에 스펙큐러색이 존재해, D3DPV_DONOTCOPYDATA 가 설정되어 있지 않다.
    • 버텍스 fog가 유효, 즉이 D3DFOG_NONE 로 설정되어 있지 않다.

또, 텍스쳐 좌표의 카운트수는, 이하의 방법으로 설정한다.

  • 모든 액티브 텍스쳐 스테이지에 대해서, 텍스쳐 트랜스 폼과 텍스쳐 생성이 무효의 경우, D3DPV_DONOTCOPYDATA 는 설정되지 않고, 출력 텍스쳐 좌표의 수 및 타입은, 입력 텍스쳐 좌표의 수 및 타입과 일치해야 한다. D3DPV_DONOTCOPYDATA 가 설정되어 있어, 텍스쳐 트랜스 폼과 텍스쳐 생성이 무효인 경우, 출력 텍스쳐 좌표는 무시된다.
  • 몇개의 액티브 텍스쳐 스테이지에 대해서, 텍스쳐 트랜스 폼 또는 텍스쳐 생성이 유효하게 되어 있는 경우, 출력되는 버텍스는 입력된 버텍스보다 많은 텍스쳐 좌표를 필요로 하는 일이 있다. 이것은, 텍스쳐 생성에 의해 생성되거나 텍스쳐 트랜스 폼에 의해 파생한 텍스쳐 좌표에 의한, 텍스쳐 좌표의 증식에 의하는 것이다. DrawPrimitive 호출에서도 같은 증식이 발생하지만, 이 경우는 어플리케이션 프로그래머로부터는 안보이는 것에 주의 해야 한다. 이 케이스에서는, Microsoft® Direct3D® 에 의해 새로운 텍스쳐 좌표 세트가 생성된다. 텍스쳐 스테이지로 나아가, 텍스쳐 생성, 텍스쳐 트랜스 폼, 텍스쳐 좌표 인덱스의 설정을 분석해, 그 스테이지에 고유의 텍스쳐 좌표 세트가 필요한가 어떤가를 판정하는 것에 따라, 새로운 텍스쳐 좌표 세트가 생성된다. 새로운 세트가 필요하게 될 때마다, 추가된 순서에 할당할 수 있다. 최대의, 그리고 일반적인 필요수는 1 스테이지 근처 1 세트이지만,D3DTSS_TEXCOORDINDEX 를 개입시켜 트랜스폼 되지 않은의 텍스쳐 좌표를 공유하는 것에 의해, 이것보다 적은 경우도 있다.

즉, 텍스쳐가 그 스테이지에 바인드 되고 있어, 이하의 조건중 한쪽이 TRUE 의 경우, 각 텍스쳐 스테이지에는, 새로운 텍스쳐 좌표 세트가 생성된다.

  • 그 스테이지의 텍스쳐 생성이 유효하다.
  • 그 스테이지의 텍스쳐 트랜스 폼이 유효하다.
  • 트랜스폼 되지 않은의 입력 텍스쳐 좌표가, D3DTSS_TEXCOORDINDEX 를 개입시키고 처음으로 참조된다.

Direct3D 가 텍스쳐 좌표를 생성 하면 와, 어플리케이션은 이하의 액션을 실행할 필요가 있다.

  1. 적절한 FVF 사용으로 전송처 버텍스 버퍼를 사용한다.
  2. 처리 후의 텍스쳐 좌표의 배치에 응해, 텍스쳐 스테이지의 D3DTSS_TEXCOORDINDEX 를 재프로그램 한다. 처리된 버텍스 버퍼를, 그 후의 IDirect3DDevice8::DrawPrimitive 호출이나 IDirect3DDevice8::DrawIndexedPrimitive 호출로 사용 하면, D3DTSS_TEXCOORDINDEX 설정이 재프로그램 되는 것에 주의 해야 한다.

마지막으로, 텍스쳐 좌표의 사이즈 (D3DFVF_TEX0 ~ D3DFVF_TEX8)는, 이하와 같이 설정해야 한다.

  • 각 텍스쳐 좌표 세트에 대한 텍스쳐 트랜스 폼 및 텍스쳐 생성이 무효의 경우, 출력 텍스쳐 좌표의 사이즈는 입력과 일치해야 한다. 텍스쳐 트랜스 폼이 유효의 경우, 출력의 사이즈는 D3DTTFF_COUNT1, D3DTTFF_COUNT2, D3DTTFF_COUNT3, 또는 D3DTTFF_COUNT4 에 의해 정의되는 카운트와 일치해야 한다. 텍스쳐 트랜스 폼이 무효로 텍스쳐 생성이 유효의 경우, 출력의 사이즈는, 텍스쳐 생성 모드의 설정에 일치해야 한다. 현재로서는, 모든 모드로 3 개의 float 형의 값이 생성된다.

전송처 버텍스 버퍼의 FVF 코드와 호환성이 없기 위해(때문에) ProcessVertices 가 실패했을 경우, 디버그 출력에 호환성을 가지는 코드가 출력된다 (디버그 빌드만).


프로그램에 의한 버텍스 처리

프로그램 된 버텍스 쉐이더를 사용할때는, 전송처 버텍스 버퍼로 갱신된 요소는, 쉐이더 함수 프로그램에 의해 제어된다. 어플리케이션이 전송처 버텍스의 몇개의 레지스터에 기입을 실시하면, 전송처 버텍스 버퍼의 각 버텍스내의 대응하는 요소가 갱신된다. 어플리케이션이 기입을 실시하지 않았던 전송처 버텍스 버퍼내의 요소는, 수정되지 않는다. 어플리케이션이 전송처 버텍스 버퍼에 존재하지 않는 요소에 기입을 실시하면,IDirect3DDevice8::ProcessVertices 는 실패한다.


버텍스 버퍼로부터의 렌더링

버텍스 버퍼로부터 버텍스 데이터를 렌더링 하려면 , 몇개의 스텝이 필요하다. 우선,IDirect3DDevice8::SetStreamSource 메소드를 호출해, 스트림 소스를 설정할 필요가 있다. 다음의 코드에 예를 나타낸다.

d3dDevice->SetStreamSource( 0, g_pVB, sizeof(CUSTOMVERTEX) );

SetStreamSource 의 제 1 파라미터는, Microsoft® Direct3D® 에 디바이스 데이터 스트림의 소스를 알린다. 제 2 파라미터는, 데이터 스트림에 바인드 하는 버텍스 버퍼이다. 제 3 파라미터는, 성분의 사이즈를 바이트 단위로 지정한다. 위에의 샘플 코드에서는, CUSTOMVERTEX 의 사이즈가 성분의 사이즈에 사용된다.

다음의 스텝에서는,IDirect3DDevice8::SetVertexShader 메소드를 호출해, 사용하는 버텍스 쉐이더를 Direct3D 에 알린다. 다음의 샘플 코드에서는, FVF 코드를 버텍스 쉐이더로 설정해 있다. 이것에 의해, 처리하는 버텍스의 타입을 Direct3D 에 알린다.

d3dDevice->SetVertexShader( D3DFVF_CUSTOMVERTEX );

스트림 소스 및 버텍스 쉐이더를 설정한 후, 드로잉(Drawing) 메소드로 버텍스 버퍼를 사용한다. 다음의 코드는,IDirect3DDevice8::DrawPrimitive 메소드를 사용해, 버텍스 버퍼로부터 버텍스를 렌더링 하는 방법을 나타내고 있다.

d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, 1 );

DrawPrimitive 가 받는 제 2 파라미터는, 로드하는 버텍스 버퍼에 있는 최초의 벡터의 인덱스이다.


버텍스 버퍼의 기술의 취득

IDirect3DVertexBuffer8::GetDesc 메소드를 호출해, 버텍스 버퍼에 관한 정보를 취득할 수 있다. 이 메소드는, 버텍스 버퍼에 관한 정보를 D3DVERTEXBUFFER_DESC 구조체의 멤버에 저장 한다.


인덱스 버퍼

여기에서는, Microsoft® Direct3D® 어플리케이션에 대해 인덱스 버퍼를 이해해, 사용하는데 필요한 개념을 설명한다. 설명하는 주제는, 다음과 같다.

  • 인덱스 버퍼란
  • 인덱스 버퍼의 기술
  • 인덱스 버퍼의 풀과 사용
  • 디바이스의 종류와 인덱스 처리의 요건
  • 인덱스 버퍼의 사용법


인덱스 버퍼란

인덱스 버퍼란,IDirect3DIndexBuffer8 인터페이스로 나타내지는, 인덱스 데이터를 보관 유지하는 메모리 버퍼이다. 인덱스 데이터, 즉 인덱스는, 버텍스 버퍼에의 정수 오프셋(offset)이며,IDirect3DDevice8::DrawIndexedPrimitive 메소드를 호출하면, 프리미티브를 렌더링 하기 위해서 사용된다.


인덱스 버퍼의 기술

인덱스 버퍼는, 능력의 점으로부터 기술된다. 인덱스 버퍼는, 시스템 메모리내에만 존재할 수 있는지, 기입 조작인 만큼 사용되는지, 인덱스 버퍼가 포함할 수가 있는 버텍스의 종류와 수등이 기술된다. 이러한 특성은 모두 D3DINDEXBUFFER_DESC 구조체에 보관 유지된다.

인덱스 버퍼의 기술에 의해, 기존 버퍼가 생성 된 방법이 어플리케이션에 알게 된다. 시스템이 생성이 끝난 인덱스 버퍼의 능력을 기입할 수 있도록(듯이), 공백의 기술 구조체를 준비한다. 이 태스크의 상세한 것에 대하여는, 「인덱스 버퍼의 기술의 취득」을 참조할것.

Format 멤버는, 인덱스 버퍼 데이터의 표면 포맷을 기술한다.

Type 는, 인덱스 버퍼의 리소스 타입을 식별한다.

Usage 구조체의 멤버는, 일반적인 능력 플래그를 저장 한다. D3DUSAGE_SOFTWAREPROCESSING 플래그는, 그 인덱스 버퍼가 소프트웨어 버텍스 처리에 사용되는 것을 나타낸다. Usage 에 D3DUSAGE_WRITEONLY 플래그를 지정 하면, 인덱스 버퍼 메모리는 기입해 처리에만 사용된다. 이것에 의해 드라이버는 해방되어 고속 처리와 고속 렌더링을 가능하게 하는 최적인 메모리 위치에 인덱스 데이터가 배치된다. D3DUSAGE_WRITEONLY 플래그가 사용되어 있지 않은 경우, 드라이버는 읽기 처리에 효율이 나쁜 위치에 데이터를 배치하지 않게 된다. 이것에 의해, 처리 속도나 렌더링 속도가 다소 희생이 된다. 이 플래그가 지정되어 있지 않은 경우, 어플리케이션은 인덱스 버퍼내의 데이터로 읽고 쓰기 처리를 실행 하면 보여진다.

Pool 는, 인덱스 버퍼에 할당할 수 있는 메모리 클래스를 지정한다. D3DPOOL_SYSTEMMEM 플래그는, 시스템이 시스템 메모리내에 인덱스 버퍼를 생성 한 것을 나타낸다.

Size 멤버는, 단지 버텍스 버퍼 데이터의 사이즈를 바이트수로 저장 한다.


인덱스 버퍼의 풀과 사용

인덱스 버퍼는,IDirect3DDevice8::CreateIndexBuffer 메소드로 생성 한다. 이 메소드는 풀 (메모리 클래스) 파라미터와 사용 파라미터를 취한다.

D3DUSAGE_SOFTWAREPROCESSING 플래그는, 그 디바이스에 대해서 믹스 모드 또는 소프트웨어 버텍스 처리 (D3DCREATE_MIXED_VERTEXPROCESSING / D3DCREATE_SOFTWARE_VERTEXPROCESSING)가 유효하게 되어 있을 때 설정할 수 있다. D3DUSAGE_SOFTWAREPROCESSING 는, 믹스 모드에서의 소프트웨어 버텍스 처리에 사용하는 버퍼로 설정해, 믹스 모드에서의 하드웨어 버텍스 처리 (D3DCREATE_HARDWARE_VERTEXPROCESSING) 시에 최고의 퍼포먼스를 얻으려고 할 경우에는 설정해서는 안 된다. 다만, 단일의 버퍼를 하드웨어 및 소프트웨어 버텍스 처리의 양쪽 모두에 사용하는 경우는, D3DUSAGE_SOFTWAREPROCESSING 를 설정하는 것이 유일한 옵션이다. D3DUSAGE_SOFTWAREPROCESSING 는, 믹스 및 소프트웨어 디바이스로 사용할 수 있다.

인덱스 처리가 하드웨어로 실행되는 경우에서도, D3DPOOL_SYSTEMMEM 를 지정하면, 버텍스 버퍼와 인덱스 버퍼를 시스템 메모리내에 강제적으로 배치할 수가 있다. 이것은, 드라이버에 의해 이러한 버퍼가 AGP 메모리에 넣어졌을 때에, 페이지 락 되는 메모리가 너무 많아 지지 않게 하는 방법이다.


디바이스의 종류와 인덱스 처리의 요건

인덱스 처리의 퍼포먼스는, 인덱스 버퍼의 메모리내에서의 위치와 사용되는 렌더링 디바이스의 종류에 크게 의존한다. 인덱스 버퍼를 생성 하면, 어플리케이션은 그 인덱스 버퍼에의 메모리 할당을 제어한다. D3DPOOL_SYSTEMMEM 메모리 플래그가 설정되어 있을 때는, 시스템 메모리내에 인덱스 버퍼가 생성 된다. D3DPOOL_DEFAULT 메모리 플래그를 사용 하면, 인덱스 버퍼용의 메모리의 최선의 할당 장소를 디바이스 드라이버가 결정되어, 이와 같이 해 결정된 메모리를 많은 경우, 드라이버 최적화 메모리라고 부른다. 드라이버 최적화 메모리로서는, 로컬 비디오 메모리, 비로컬 비디오 메모리, 또는 시스템 메모리가 지정된다.

IDirect3DDevice8::CreateIndexBuffer 메소드를 호출하면나무에, D3DUSAGE_SOFTWAREPROCESSING 동작 플래그를 설정 하면, 인덱스 버퍼는 소프트웨어 버텍스 처리에 사용된다. 소프트웨어 버텍스 처리를 사용하는 경우, 이 플래그는 믹스 모드의 버텍스 처리 (D3DCREATE_MIXED_VERTEXPROCESSING)로 필요하다.

어플리케이션은, 드라이버 최적화 메모리에 할당할 수 있었던 인덱스 버퍼에 버텍스를 직접 기입할 수가 있다. 이 방법에 의해, 이후의 장황한 카피 처리를 방지한다. 다만, 드라이버 최적화 메모리로부터 호스트에 의해 실행되는 독해 처리는 저속인 경우가 있기 (위해)때문에, 어플리케이션이 인덱스 버퍼로부터 데이터를 다시 읽을 때는, 이 방법은 잘 기능하지 않는다. 따라서, 어플리케이션으로 처리중에 읽어내, 또는 버퍼에의 데이터 기입을 불규칙하게 실행할 필요가 있는 경우는, 시스템 메모리에 인덱스 버퍼를 할당하면(자) 좋다.

주 드라이버가 버텍스 버퍼 또는 인덱스 버퍼를 AGP 메모리에 배치하는 경우에, 비디오 메모리 또는 대량의 페이지 락 RAM 를 확장하지 않을 때를 제외해서는, 항상 D3DPOOL_DEFAULT 를 사용한다.


인덱스 버퍼의 사용법

여기에서는, 인덱스 버퍼를 처리할 때에 어플리케이션이 실행하는 일반적인 태스크에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 인덱스 버퍼의 생성
  • 인덱스 버퍼의 내용에의 액세스
  • 인덱스 버퍼로부터의 렌더링
  • 인덱스 버퍼의 기술의 취득


인덱스 버퍼의 생성

IDirect3DDevice8::CreateIndexBuffer 메소드를 호출해, 인덱스 버퍼 오브젝트를 생성 한다. 이 메소드는, 5 개의 파라미터를 받는다. 제 1 파라미터는, 인덱스 버퍼의 길이를 바이트 단위로 지정한다.

제 2 파라미터는, 사용 컨트롤 세트이다. 특히, 이 값은, 인덱스에 의해 참조되는 버텍스가 클리핑 정보를 저장 할 수 있을지 어떨지를 지정한다. 퍼포먼스를 향상시키려면 , 클리핑의 필요가 없을 때에 D3DUSAGE_DONOTCLIP 를 지정한다.

제 3 파라미터는, 각 인덱스의 사이즈를 지정하는 D3DFORMAT 열거형의 D3DFMT_INDEX16 또는 D3DFMT_INDEX32 멤버의 언젠가이다.

제 4 파라미터는, 새로운 인덱스 버퍼를 메모리내의 어느 위치에 배치하는지를 지시하는 D3DPOOL 열거형의 멤버이다.

CreateIndexBuffer 가 받는 마지막 파라미터는, 호출이 성공했을 때에 버텍스 버퍼 오브젝트의 새로운 IDirect3DIndexBuffer8 인터페이스에의 포인터가 저장 되는 변수의 주소이다.

다음의 C++ 샘플 코드는, 인덱스 버퍼의 생성 방법을 나타내고 있다.

/*
* 이 예에서는, 변수 d3dDevice 는
* Direct3DDevice 오브젝트에 의해 공개되는 IDirect3DDevice8 인터페이스에의 주소이며,
 * g_IB 는 LPDIRECT3DINDEXBUFFER8 형의 변수이다.

 */

if( FAILED( d3dDevice->CreateIndexBuffer( 16384 *sizeof(WORD),
                                            D3DUSAGE_WRITEONLY, D3DFMT_INDEX16,
                                            D3DPOOL_DEFAULT, &g_IB ) ) )
    return E_FAIL;


인덱스 버퍼의 내용에의 액세스

인덱스 버퍼 오브젝트를 사용 하면, 어플리케이션은 인덱스 데이터에 할당할 수 있었던 메모리에 직접 액세스 할 수 있다. IDirect3DIndexBuffer8::Lock 메소드를 호출해 인덱스 버퍼 메모리에의 포인터를 취득해, 다음에, 필요에 따라서 메모리에 액세스 해 새로운 인덱스 데이터를 버퍼로 설정하는지, 이미 설정되어 있는 데이터를 읽어낸다. Lock 메소드는 4 개의 파라미터를 받는다. 제 1 파라미터 OffsetToLock 는, 인덱스 데이터에의 오프셋(offset)이다. 제 2 파라미터는, 인덱스 데이터의 사이즈를 바이트 단위로 지정한다. 제 3 파라미터는,Lock 메소드에 의해 수취된다. ppbData 는, 호출이 성공했을 경우에, 인덱스 데이터에의 포인터가 저장 되는 BYTE 포인터의 주소이다.

마지막 파라미터 Flags 는, 메모리의 락 방법을 시스템에 알린다. 이 파라미터를 사용해, 버퍼내의 데이터에 어플리케이션이 어떻게 액세스 하는지를 나타낼 수가 있다. 어플리케이션이 인덱스 데이터에 액세스 하는 방법으로 응해,Flags 파라미터에 정수를 지정한다. 이것에 의해, 드라이버는 메모리를 잠그어, 요구되고 있는 액세스 타입에서의 최고의 퍼포먼스를 제공한다. 어플리케이션이 인덱스 버퍼 메모리로부터 읽기만을 실시하는 경우는, D3DLOCK_READONLY 플래그를 사용한다. 이 플래그를 포함하면(자), Microsoft® Direct3D® 가 내부 순서를 최적화하므로 효율이 오른다. 다만, 메모리에의 액세스는 읽어내기 전용이 된다.

인덱스 데이터를 설정 또는 읽어낸 후,IDirect3DIndexBuffer8::Unlock 메소드를 호출한다. 다음의 코드에 예를 나타낸다.

// 이 샘플 코드에서는, IB 는 LPDIRECT3DINDEXBUFFER8 형의 변수이며,
// g_Indices 는
// 인덱스로 올바르게 초기화되고 있으면(자) 가정하고 있다.

// 인덱스 버퍼에 데이터를 저장 하려면 , 버퍼를 잠그어
// 인덱스에의 액세스를 취득한다. 이것은, 인덱스 버퍼가 디바이스 메모리에 존재한다
// 가능성이 있기 위해서(때문에) 필요한 메카니즘이다.

VOID* pIndices;

if( FAILED( IB->Lock( 0,                 // 버퍼의 최초부터 데이터를 저장 한다.
                      sizeof(g_Indices), // 로드하는 데이터의 사이즈.
                      (BYTE**) &pIndices, // 돌려주어지는 인덱스 데이터.
                      0 ) ) )            // 디폴트 플래그를 락에 보낸다.
    return E_FAIL;

memcpy( pIndices, g_Indices, sizeof(g_Vertices) );
IB->Unlock();

주 D3DUSAGE_WRITEONLY 플래그로 인덱스 버퍼를 생성 했을 경우, D3DLOCK_READONLY 락킹 플래그는 사용할 수 없다. 어플리케이션이 인덱스 버퍼 메모리로부터 읽기만을 실시하는 경우는, D3DLOCK_READONLY 플래그를 사용한다. 이 플래그를 포함하면(자), Direct3D 가 내부 순서를 최적화하므로 효율이 오른다. 다만, 메모리에의 액세스는 읽어내기 전용이 된다.

Lock 메소드의 Flags 파라미터에 D3DLOCK_DISCARD 또는 D3DLOCK_NOOVERWRITE 를 사용하는 방법의 상세한 것에 대하여는, 「동적인 버텍스 및 인덱스 버퍼의 사용법」을 참조할것.

C++ 에서는, 인덱스 버퍼에 할당할 수 있고 있는 메모리에 직접 액세스 하므로, 어플리케이션이 목적의 메모리에 올바르게 액세스 하도록(듯이) 주의 해야 한다. 그렇지 않으면 부정한 메모리가 렌더링 될 우려가 있다. 어플리케이션으로 사용하는 인덱스 포맷의 보폭을 이용해, 할당할 수 있고 있는 버퍼의 인덱스로부터 다음의 인덱스로 이동한다.


인덱스 버퍼로부터의 렌더링

인덱스 버퍼의 인덱스 데이터를 렌더링 하려면 , 몇개의 스텝이 필요하다. 우선,IDirect3DDevice8::SetStreamSource 메소드를 호출해, 스트림 소스를 설정할 필요가 있다.

d3dDevice->SetStreamSource( 0, VB, sizeof(CUSTOMVERTEX) );

SetStreamSource 의 제 1 파라미터는, Microsoft® Direct3D® 에 디바이스 데이터 스트림의 소스를 알린다. 제 2 파라미터는, 데이터 스트림에 바인드 하는 버텍스 버퍼이다. 제 3 파라미터는, 성분의 사이즈를 바이트 단위로 지정한다. 위에의 샘플 코드에서는, CUSTOMVERTEX 의 사이즈가 성분의 사이즈에 사용되고 있다.

다음의 스텝에서는,IDirect3DDevice8::SetIndices 메소드를 호출해 인덱스 데이터의 소스를 설정한다.

d3dDevice->SetIndices( IB, 0 );

SetIndices 가 받는 최초의 파라미터는, 설정하는 인덱스 버퍼의 주소이다. 제 2 파라미터는, 버텍스 스트림의 시작점이다.

스트림 및 인덱스 소스를 설정한 후,IDirect3DDevice8::DrawIndexedPrimitive 메소드를 사용해, 인덱스 버퍼로부터 인덱스를 사용하는 버텍스를 렌더링 한다.

d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0,
                                   dwVertices, 0, dwIndices / 3);

DrawPrimitive 가 받는 제 2 파라미터는, 이 호출동안에 사용되는 버텍스군에 대한 최소의 버텍스 인덱스이다. 제 3 파라미터는, 이 호출로 사용되는 인덱스의 수이다 (BaseVertexIndex + MinIndex 로부터 시작된다). 제 4 파라미터는, 인덱스 배열에 있어서의 인덱스의 읽기 시작 위치이다. DrawPrimitive 가 받는 마지막 파라미터는, 렌더링 하는 프리미티브의 개수이다. 이 파라미터는, 프리미티브 카운트 및 프리미티브 타입의 함수이다. 위에의 코드에서는, 삼각형을 사용하고 있다. 따라서, 렌더링 하는 프리미티브의 개수는, 3 으로 나뉘어 떨어지는 인덱스수가 된다.


인덱스 버퍼의 기술의 취득

IDirect3DIndexBuffer8::GetDesc 메소드를 호출해, 인덱스 버퍼에 관한 정보를 취득한다. 이 메소드는,D3DINDEXBUFFER_DESC 구조체의 멤버에 버텍스 버퍼에 관한 정보를 설정한다.


테크놀러지와 특수 효과

Microsoft® Direct3D® 는, 3D 신을 보다 리얼하게 표시하기 위한 강력한 툴 세트를 제공한다. 여기에서는, Direct3D 로 생성할 수 있는 일반적인 특수 효과에 대해 설명한다. 사용할 수 있는 효과는, 여기에 게재하는 것에 한정되지 않는다. 설명하는 주제는, 다음과 같다.

  • 알파 블렌딩
  • anti-aliasing
  • 범프 맵핑
  • 환경 매핑
  • fog
  • 지오메트리 블렌딩
  • 인덱스 첨부 버텍스 블렌딩
  • 스텐실 버퍼 기술
  • 버텍스 트이닝
  • 칼라 라이팅


알파 블렌딩

알파 블렌딩은, 투명 또는 반투명 픽셀을 포함한 화면을 표시하기 위해서 사용된다. 적, 초록, 및 파랑의 칼라 채널외, 알파 비트 맵내의 각 픽셀에는,알파 채널로 불리는 투명 성분이 있다. 알파 채널에는, 일반적으로 칼라 채널과 같은 수만의 비트가 포함된다. 예를 들어, 8 비트 알파 채널의 경우, 0 (픽셀 전체가 투명) ~ 255 (픽셀 전체가 불투명)까지, 256 레벨의 투명을 표현할 수 있다. 다음의 일람은, 알파 블렌딩을 사용해 생성 할 수 있는 특수 효과의 몇개인가를 나타내고 있다.

  • 빌딩 승선
  • 운, 연기, 증기
  • 화, 불길, 폭발


빌딩 승선

3D 신을 생성 하면 와, 2D 오브젝트를 3D 오브젝트인것 같이 표시하는 것에 의해 퍼포먼스를 향상할 수 있는 일이 있다. 이 생각이, 빌보드 처리 기술의 기본으로 되어 있다.

보통의 의미에서의 빌보드는, 도로 가의 게시판이다. Microsoft® Direct3D® 어플리케이션에서는, 직사각형 솔리드를 정의해 텍스쳐를 적용하는 것으로, 이러한 빌보드를 간단하게 생성 및 렌더링 할 수 있다. 3D 그래픽스에서의 특수한 의미에서의 빌보드는, 이것을 확장한 것이다. 이 의미에서의 빌보드 처리의 목적은, 2D 오브젝트를 3D 오브젝트와 같이 보이는 것이다. 이 방법에서는, 오브젝트의 이미지를 보관 유지하는 텍스쳐를 직사각형 원시적으로 적용한다. 이 프리미티브는, 정면이 항상 유저의 분을 향하도록(듯이) 회전된다. 이 프리미티브는, 정면이 항상 뷰아의 분을 향하도록(듯이) 회전된다. 이 오브젝트의 화면은 직사각형이 아니어도 문제 없다. 빌보드의 부분을 투명하게 해, 표시하고 싶지 않은 빌보드 화면의 부분을 불가시로 할 수 있다.

많은 게임에서는, 애니메이션 한 스프라이트에 빌보드 처리를 사용하고 있다. 예를 들어, 유저가 3D 의 미로를 이동 하면 와, 수집할 수 있는 무기나 포상이 표시된다. 이것들은, 직사각형 원시적으로 텍스쳐를 적용한 전형적인 2D 화면이다. 빌보드 처리는, 게임에서 나무, 관목, 및 구름의 화면을 렌더링 하기 위해서 사용되는 것이 많다.

빌보드에 화면을 적용 하면나무는, 최초로, 정면이 유저의 분을 향하도록(듯이) 직사각형 프리미티브를 회전해야 한다. 다음에, 이 프리미티브를 배치 장소에 평행이동 해야 한다. 그 후, 이 원시적으로 텍스쳐를 적용할 수 있다.

빌보드 처리는, 대칭적인 오브젝트, 특히 수직 축으로 대해 대칭적인 오브젝트의 처리에 최적이다. 또, 빌보드 처리에는, 시점의 높이가 그다지 오르지 않는 것이 필요하다. 유저가 빌보드를 위로부터 보는 것이 허락되고 있는 경우, 그 오브젝트가 3D 는 아니고 2D 인 것을 곧바로 알아 버린다.


운, 연기, 증기

운, 연기, 증기간 모두, 빌보드 처리 기술을 확장해 생성 할 수 있다. 상세한 것에 대하여는, 「빌딩 승선」을 참조할것. 1 개의 축이 아니라 2 개의 축을 중심으로 빌보드를 회전하는 것으로, 유저가 빌보드를 어느 각도로부터에서도 볼 수가 있다. 보통, 어플리케이션에서는 수평축과 수직축을 중심으로 빌보드를 회전한다.

간단한 구름을 생성 하려면 , 프리미티브의 면이 유저의 분을 향하도록(듯이) 1 개(살) 또는 2 개의 축을 중심으로 직사각형 프리미티브를 회전시킨다. 다음에, 구름과 같은 텍스쳐를 투명도와 함께 이 원시적으로 적용한다. 투명도가 있는 텍스쳐의 프리미티브에의 적용의 상세한 것에 대하여는, 「텍스쳐 블렌딩」을 참조할것. 구름을 애니메이션 하려면 , 일련의 텍스쳐를 시간의 경과에 따라 적용한다.

프리미티브의 그룹에서 구름을 만들면, 게다가 복잡한 구름을 생성 할 수 있다. 이 경우, 구름의 각 부분이 직사각형 원시적으로 된다. 이러한 프리미티브를 각각 독립해 연속적으로 이동해, 동적인 안개와 같이 보일 수가 있다. 다음의 그림에 이것을 나타낸다.

연기는, 구름과 같은 방법으로 표시한다. 보통, 연기에서는 복잡한 구름과 같이 복수의 빌보드가 필요하다. 연기는 시간과 함께 꾸불꾸불하거나 상승하므로, 서 오르는 연기를 형성하는 빌보드를 이동시킬 필요가 있다. 연기가 상승하거나 소산 하면나무는, 빌보드의 추가가 필요한 경우도 있다.

증기나무는, 상승하지 않는 연기와 같은 것이다. 다만, 증기는 연기와 같이 서서히 소산한다. 다음의 그림은, 증기나무를 시뮬레이트 하기 위해서 빌보드를 사용하는 기술을 나타내고 있다.


화, 불길, 폭발

Microsoft® Direct3D® 를 사용해, 에너지를 발하는 자연현상을 시뮬레이션 할 수 있다. 예를 들어, 불길과 같은 텍스쳐를 빌보드 세트에 적용해, 불을 표현할 수 있다. 이것이 특히 효과적인 것은, 불의 텍스쳐를 연속적으로 사용해, 불타는 빌보드 각각의 위에의염을 애니메이션 하는 경우이다. 빌보드 마다 애니메이션 재생의 속도를 바꾸면(자), 불길의 리얼리티가 늘어난다. 서로 섞인 3D 의 불길에 보이려면 , 빌보드를 거듭해 맞추어 빌보드 위에의 텍스쳐를 거듭해 맞추면 좋다.

불길이나 섬광은, 장면내의 모든 프리미티브에 대해서, 서서히 밝아지는 라이트 맵을 적용하는 것으로 시뮬레이션 할 수 있다. 이것은 오버헤드의 높은 기술이지만, 국소적인 불길이나 섬광의 시뮬레이션은 가능하다. 즉, 불길이나 섬광을 발하는 장면을 최초로 밝게 할 수가 있다.

다른 기술로서는, 렌더링 타겟 영역 전체를 가리도록(듯이) 장면의 전면에 빌보드를 배치하는 방법이 있다. 어플리케이션으로, 연속적으로 희어지는 텍스쳐를 빌보드에 적용해, 서서히 투명도를 감소시킨다. 시간과 함께 장면 전체가 희어진다. 이것은, 불길을 생성 하는 방법으로서는 오버헤드의 낮은 방법이다. 그러나, 이 기술을 사용 하면, 단일의 포인트 라이트의 광원으로부터 밝은 섬광을 표현하는 것이 곤란하게 되는 일이 있다.

폭발은, 불, 섬광, 및 불길로 사용한 것 같은 3D 신의 생성 방법에 따라 표시할 수 있다. 예를 들어, 어플리케이션으로 빌보드를 사용해, 폭발의 충격파나 연기를 표시할 수 있다. 동시에, 빌보드 세트를 사용해 불길을 시뮬레이트 할 수 있다. 게다가 장면의 전면에 단일의 빌보드를 배치해, 장면 전체에 섬광을 추가할 수 있다.

에너지 빔은, 빌보드를 사용해 시뮬레이션 할 수 있다. 또, 선리스트 또는 선스트립으로서 정의한 프리미티브를 사용해도 이 빔을 표시할 수 있다. 상세한 것에 대하여는, 「선리스트」 및 「선스트립」을 참조할것.

빌보드나 삼각형 리스트로서 정의한 프리미티브를 사용해, 전자력계를 생성 할 수 있다. 삼각형 리스트로부터 전자력계를 생성 하려면 , 전자력계의 범위와 같은 공간을 차지하는 삼각형 리스트에 있는 분리한 삼각형세트를 정의하는 것. 유저는, 삼각형 끼리의 틈새로부터 삼각형의 배후의 장면을 볼 수가 있어 마치 전자력계를 봐 있는 것과 같게 느껴진다. 삼각형이 에너지로 빛나고 있도록(듯이) 보이게 하는 텍스쳐를 삼각형 리스트에 적용한다. 상세한 것에 대하여는, 「삼각형 리스트」를 참조할것.


anti-aliasing

anti-aliasing란, 정확하게 수평 또는 수직이 아닌 선을 그렸을 때에 나타나는 계단상의 픽셀을 줄이기 위한 기법이다. 3 차원 신의 경우, 이 부자연스러운 효과는 다른 색의 다각형간의 경계선상에서 가장 눈에 띈다. anti-aliasing는, 픽셀을 효과적으로 경계선상에서 브렌드 해, 장면의 외관을 보다 자연스럽게 한다.

Microsoft® Direct3D® 가 지원 하는 anti-aliasing의 방법에는, 엣지 anti-aliasing 및 풀 신 anti-aliasing의 2 종류가 있다. 어느 쪽의 anti-aliasing가 어플리케이션에 좋은가는, 퍼포먼스와 시각적 품질의 요건에 의존한다.

  • 엣지 anti-aliasing
  • 풀 신 anti-aliasing

다음의 주제에서는, 특수 효과를 사용해 시뮬레이트 하는 방법 또는 anti-aliasing의 사용 방법에 대해 설명한다.

  • 모션브라


엣지 anti-aliasing

엣지 anti-aliasing에서는, 장면을 렌더링 한 후, 오브젝트의 볼록한 모양 실루엣을 재렌더링 해, 선에 anti-aliasing 한다. 시스템은 옆을 재드로잉(Drawing) 해, 애매하게 해, 부자연스러운 효과를 줄인다.

우선,IDirect3DDevice8::GetDeviceCaps 메소드를 호출해, Microsoft® Direct3D® 디바이스가 anti-aliasing를 지원 하고 있을지 어떨지를 조사한다. 디바이스가 엣지 anti-aliasing를 지원 하고 있는 경우는,GetDeviceCaps 이 D3DCAPS8 구조체의 D3DPRASTERCAPS_ANTIALIASEDGES 능력 플래그를 TRUE 로 설정한다.

디바이스가 anti-aliasing를 지원 하고 있는 경우는, D3DRS_EDGEANTIALIAS 렌더링 스테이트를 TRUE 로 설정한다. 다음의 코드에 예를 나타낸다.

d3dDevice->SetRenderState( D3DRS_EDGEANTIALIAS, TRUE );

다음에,IDirect3DDevice8::DrawPrimitive , 및 D3DPT_LINESTRIP 또는 D3DPT_LINELIST 프리미티브 타입의 어느쪽이든을 사용해, 장면내의 엣지만 재드로잉(Drawing) 한다. 엣지 anti-aliasing의 동작은, 선 이외의 프리미티브에 대해서는 정의되어 있지 않기 때문에, anti-aliasing가 완료하면(자), D3DRS_EDGEANTIALIAS 를 FALSE 로 설정해 기능을 확실히 무효로 한다.

장면안의 모든 엣지를 재드로잉(Drawing) 하면, 큰 부자연스러운 효과를 일으키게 한 하지않고서 끝나지만, 계산량이 방대하게 된다. 또, 이 방법에서는 어느 엣지를 anti-aliasing 해야할 것인가 판단이 곤란한 일도 있다. 재드로잉(Drawing) 하는데 가장 중요한 엣지는, 매우 다른 색의 영역의 사이의 엣지 (예를 들어 그림자의 엣지), 또는 매우 다른 머트리얼의 사이의 경계이다. 거의 같은 색의 2 개의 다각형의 사이의 엣지를 anti-aliasing 하는 것에 의미는 없지만, 계산량은 방대하다. 이러한 이유에 의해, 현재의 하드웨어가 풀 신 anti-aliasing를 지원 하고 있다면, 이것이 바람직한 일이 많다. 상세한 것에 대하여는, 「풀 신 anti-aliasing」를 참조할것.


풀 신 anti-aliasing

풀 신 anti-aliasing와는, 장면내의 각 다각형의 엣지를 싱글 패스로 rasterize 해 애매하게 하는 것을 가리킨다. 2 번째의 패스는 필요없다. 풀 신 anti-aliasing는, 지원 되고 있는 경우는 삼각형 및 삼각형의 그룹에게만 영향을 준다. Microsoft® Direct3D® 서비스를 사용해 선에 anti-aliasing를 적용할 수 없다. Direct3D 에서는, 풀 신 anti-aliasing를 실행하려면 , 각 픽셀에 멀티 샘플링을 사용한다. 멀티 샘플링이 유효한 경우, 픽셀의 모든 서브 샘플이 1 살의 패스로 갱신되지만, 복수의 렌더링 패스를 포함하는 것 외의 이펙트에 사용되는 경우는, 어플리케이션으로 서브 샘플의 일부만이 지정의 렌더링 패스에 영향을 받도록(듯이) 지정할 수 있다. 이 후자의 어프로치에 의해, 모션브라, 필드 포커스 이펙트의 깊이, 반사 브라등을 시뮬레이트 할 수가 있다.

어느 쪽의 경우도, 픽셀 마다 기록된 다양한 샘플이 브렌드 되어 스크린에 출력된다. 이러한 어프로치를 사용 하면, anti-aliasing나 다른 이펙트의 이미지 품질이 향상한다.

IDirect3D8::CreateDevice 로 디바이스를 생성 하기 전에, 풀 신 anti-aliasing가 지원 되고 있는지 어떤지를 조사할 필요가 있다. 조사하려면 ,IDirect3D8::CheckDeviceMultiSampleType 메소드를 호출한다. 다음의 코드에 예를 나타낸다.

/*
* 이 코드에서는, pD3D 는 IDirect3D8 인터페이스에의
* 유효한 포인터이라고 가정하고 있다.
 */

if( SUCCEEDED(pD3D->CheckDeviceMultiSampleType( D3DADAPTER_DEFAULT,
                                                D3DDEVTYPE_HAL , D3DFMT_R8G8B8,
                                                FALSE, D3DMULTISAMPLE_2_SAMPLES ) ) )
    // 풀 신 anti-aliasing가 지원 되고 있다. 여기서 유효하게 한다.

CheckDeviceMultiSampleType 가 받는 제 1 파라미터는, 문의하는 디스플레이 어댑터를 나타내는 서수이다. 이 예에서는, D3DADAPTER_DEFAULT 를 사용해 프라이머리 디스플레이 어댑터를 지정한다. 제 2 파라미터는 D3DDEVTYPE 열거형의 값으로, 디바이스의 종류를 지정한다. 제 3 파라미터에는, 표면의 포맷을 지정한다. 제 4 파라미터는, 풀 윈도우 멀티 샘플링 (TRUE) 또는 풀 스크린 anti-aliasing (FALSE)를 문의할지 어떨지를 Direct3D 에 알린다. 이 예에서는 FALSE 를 사용해, 풀 신 anti-aliasing에 대해 문의하는 것을 Direct3D 에 지시하고 있다. 마지막 파라미터에는, 테스트하는 멀티 샘플링 테크닉을 지정한다. D3DMULTISAMPLE_TYPE 열거형의 값을 사용한다. 이 예에서는, 2 개의 레벨의 멀티 샘플링이 지원 되고 있는지 어떤지를 테스트한다.

디바이스가 사용하고 싶은 2 개의 레벨의 멀티 샘플링을 지원 하고 있는 경우, 다음의 순서는, 멀티 샘플의 렌더링 표면을 생성 하기 위해서,D3DPRESENT_PARAMETERS 구조체의 적절한 멤버에 데이터를 설정해, 프레젠테이션 파라미터를 설정하는 것이다. 설정한 후는, 디바이스를 생성 할 수가 있다. 다음의 샘플 코드는, 멀티 샘플링의 렌더링 표면으로 디바이스를 설정하는 방법을 나타내고 있다.

/*
* 이 예에서는, pD3D 는 IDirect3D8 인터페이스에의 유효한 포인터이며,
 * d3dDevice 는 IDirect3DDevice8 인터페이스에의 포인터,
* hWnd 는 윈도우에의
* 유효한 핸들이라고 가정하고 있다.
 */

D3DPRESENT_PARAMETER d3dPP
ZeroMemory( &d3dPP, sizeof( d3dPP ) );
d3dPP.Windowed        = FALSE
d3dPP.SwapEffect      = D3DSWAPEFFECT_DISCARD;
d3dPP.MultiSampleType = D3DMULTISAMPLE_2_SAMPLES;
pD3D->CreateDevice(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd,
                   D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                   &d3dpp, &d3dDevice)

주 멀티 샘플링을 사용하려면 , D3DPRESENT_PARAMETER 의 SwapEffect 멤버를 D3DSWAPEFFECT_DISCARD 로 설정할 필요가 있다.

마지막 순서는,IDirect3DDevice8::SetRenderState 메소드를 호출해 D3DRS_MULTISAMPLEANTIALIAS 를 TRUE 로 설정하는 것에 의해, 멀티 샘플링의 anti-aliasing를 유효하게 하는 것이다. 이 값에 TRUE 를 설정한 후는, 렌더링에는 반드시 멀티 샘플링이 적용된다. 렌더링 대상으로 응해, 멀티 샘플링의 유효/무효를 바꿀 수도 있다.


모션브라

3D 신의 오브젝트의 지각 속도는, 오브젝트를 애매하게 해, 오브젝트의 배후에 오브젝트 화면의 멍하니 한 자취를 남기는 것으로 높일 수가 있다. Microsoft® Direct3D® 어플리케이션은, 프레임 마다 오브젝트를 여러 차례 렌더링 해, 이것을 실현한다.

보통, Direct3D 어플리케이션은 장면을 오프 스크린 버퍼에 렌더링 하는 것을 생각해 내면 좋겠다. 버퍼의 내용은, 어플리케이션으로IDirect3DDevice8::Present 메소드를 호출했을 때에 스크린에 표시된다. Direct3D 어플리케이션은, 스크린에 프레임을 표시하기 전에 오브젝트를 장면에 여러 차례 렌더링 할 수 있다.

어플리케이션으로 DrawPrimitive 메소드에의 호출을 여러 차례 실시해, 같은 3D 오브젝트를 반복해 건네준다. 각각의 호출전에, 오브젝트의 위치 좌표를 조금 갱신해, 타겟 렌더링 표면상에 일련의 불선명한 오브젝트 화면을 생성한다. 오브젝트가 1 개 또는 복수의 텍스쳐를 가지고 있는 경우, 텍스쳐 모든 것을 거의 투명하게 해 오브젝트의 최초의 화면을 렌더링 하면, 모션브라에페크트를 높일 수가 있다. 오브젝트를 렌더링 할 때마다, 오브젝트의 텍스쳐의 투명도가 감소한다. 최종 위치 좌표로 오브젝트를 렌더링 하면나무는, 투명도없이 오브젝트를 렌더링 하는 것. 예외는, 텍스쳐의 투명도를 필요로 하는 것 외의 이펙트에 모션브라를 추가하는 경우이다. 어느 경우에서도, 프레임의 오브젝트의 최초의 화면이 가장 투명하지 않으면 안 된다. 마지막 화면의 투명도가 가장 낮지 않으면 안 된다.

타겟 렌더링 표면에 일련의 오브젝트 화면을 렌더링 해, 나머지의 장면도 렌더링 하면(자),Present 메소드를 호출해 스크린에 프레임을 표시한다.

유저가 장면을 고속으로 이동하는 이펙트를 시뮬레이션 하는 경우는, 스크린 전체에 모션브라를 추가할 수 있다. 이 경우, 어플리케이션은, 프레임 마다 장면 전체를 여러 차례 렌더링 한다. 장면을 렌더링 할 때마다, 시점을 조금 이동해야 한다. 장면이 매우 복잡한 경우, 프레임마다의 장면의 렌더링 회수가 증가하므로, 고속으로 이동하는 장면만큼 퍼포먼스가 저하하는 것이 유저에게 안다.


범프 맵핑

여기에서는, Microsoft® Direct3D® 로 실행하는 범프 맵핑에 대해 설명한다. 이하의 주제에서는, 범프 맵핑을 소개해, 그 주요한 개념을 특정 및 정의해, 어플리케이션에서의 범프 맵핑의 사용 방법에 대해 설명한다.

  • 범프 맵핑이란
  • 범프 맵 픽셀 포맷
  • 범프 맵핑의 공식
  • 범프 맵핑의 사용법


범프 맵핑이란

범프 맵핑은, 소수의 다각형만으로 예쁘게 테셀레이션 된 오브젝트의 반사 상태를 시뮬레이트 하는, 특수한 스펙큐러 또는 디퓨즈 환경 매핑이다. 다음의 화면은,BumpEarth 샘플에 근거해 범프 맵핑의 이펙트를 나타내고 있다.

좌측의 지구는, 지구의 표면의 화면으로 텍스쳐 처리되어 스펙큐러 환경 맵이 적용되고 있다. 우측의 지구도 완전히 같지만, 범프 맵이 적용되고 있다. 2 번째의 지구의 화면의 다각형수는, 1 번째의 화면의 다각형수로 변함없다.

Microsoft® Direct3D® 의 범프 맵핑에서는, 개발자는 델타값에 의한 윤곽선의 정보를 제공하는 것으로부터, 범프 맵핑은, 정확하게는 스펙큐러 또는 디퓨즈 환경 맵의 픽셀 단위의 텍스쳐 좌표의 보정과 기술할 수 있다. 윤곽선의 정보는, 시스템에 의해 다음의 텍스쳐 스테이지의 환경 맵의 u 및 v 텍스쳐 좌표에 적용된다. 델타값은, 범프 맵 표면의 픽셀 포맷으로 encode 된다. 상세한 것에 대하여는, 「범프 맵 픽셀 포맷」을 참조할것.

BumpEarth 샘플에서는, 고도 맵을 사용해 윤곽선데이터를 저장 한다. 샘플을 시작 하면, 고도 맵내의 픽셀이 처리되어 적절한 u 및 v 가 계산된다. 이것은, 인접하는 4 개의 픽셀을 기준으로 한, 각 픽셀의 상대 고도로 기초를 둔다.

본래, Direct3D 에서는 고도 맵을 지원 하고 있지 않다. 고도 맵은, 윤곽선데이터를 저장 및 시각화하는데 편리한 포맷인 것에 지나지 않는다. 전의 화면은 고도 맵에 근거해 생성 된 것으로, BumpEarth 샘플에서는 이 고도 맵을 사용해, Direct3D 에 제공하는 범프 맵을 생성하고 있다. 이 화면은 설명을 목적으로 나타낸 것이다. 어플리케이션에서는 윤곽선정보를 어떠한 포맷에서도 저장 할 수 있어 또,BumpWaves 샘플과 같이 개개의 범프 맵을 생성할 수도 있다.

다음은, BumpEarth 샘플로 사용하는 고도 맵 화면이다. 이 샘플에서는, 이것을 사용해, 범프 맵 텍스쳐의 픽셀 포맷으로 encode 되는 델타값을 계산한다.

범프 맵핑은, 복수의 텍스쳐 블렌딩 서비스에 완전하게 의존하고 있어, 디바이스는 적어도 2 개의 블렌딩 스테이지 (1 개(살)은 범프 맵용, 이제(벌써) 1 개(살)은 환경 맵용)를 지원 하고 있을 필요가 있다. 베이스 텍스쳐 맵을 적용하려면 , 가장 일반적인 경우, 최저 3 개의 텍스쳐 블렌딩 스테이지가 요구된다. 다음의 그림은, 텍스쳐 블렌딩 cascade에 있어서의, 베이스 텍스쳐, 범프 맵, 및 환경 맵간의 관계를 나타내고 있다.

텍스쳐 스테이지를 적절히 준비해, 범프 맵핑을 유효하게 할 필요가 있다. 이 태스크에 대해서는, 「범프 맵핑 파라미터의 설정」으로 설명한다.


범프 맵 픽셀 포맷

범프 맵이란, 특수한 픽셀 포맷을 사용하는 IDirect3DTexture8 오브젝트이다. 적, 초록, 및 파랑의 색성분을 저장 하는 것이 아니라, 범프 맵의 각 픽셀은,u 및 v 의 델타값 (Du 및 Dv)을 저장 해, 휘도 L. (을)를 저장 하면 간 있다. 이러한 값은, 「범프 맵핑의 공식」에서 설명하도록(듯이), 시스템에 의해 적용된다.

범프 맵 픽셀 포맷을 지정하려면 ,D3DFORMAT 열거형을 이하의 범프 맵 픽셀 포맷의 어느 쪽인가에 설정한다.

포맷 | 설명
D3DFMT_V8U8 | 16 비트의 범프 맵 포맷.
D3DFMT_L6V5U5 | 휘도 첨부의 16 비트 범프 맵 포맷.
D3DFMT_X8L8V8U8 | 휘도 첨부의 32 비트 범프 맵 포맷으로, 8 비트는 각 요소를 위해서(때문에) 확보되고 있다.
D3DFMT_Q8W8V8U8 | 32 비트의 범프 맵 포맷.
D3DFMT_V16U16 | 32 비트의 범프 맵 포맷.
D3DFMT_W11V11U10 | 32 비트의 범프 맵 포맷.

픽셀의 Du 및 Dv 컴퍼넌트는,-1. 0 ~ +1. 0 의 범위의 부호 첨부의 값이다. 휘도 컴퍼넌트가 사용되고 있는 경우, 이 값은 0 ~ 255 의 범위의 부호 없음 정수값이다.

주 범프 맵 픽셀 포맷을 선택하기 전에, 특정의 포맷이 지원 되고 있는지 어떤지를 조사할 필요가 있다. 상세한 것에 대하여는, 「범프 맵핑의 지원의 검출」을 참조할것.


범프 맵핑의 공식

Microsoft® Direct3D® 에서는, 각 범프 맵 픽셀의 Du 및 Dv 컴퍼넌트에 다음의 공식을 적용한다.

이 공식에서는, 변수 Du 및 Dv 는 범프 맵 픽셀로부터 직접 취득되어 출력 델타값 Du' 및 Dv' 를 생성하기 위해서 2 × 2 행렬로 트랜스 폼 된다. 시스템에서는, 이 출력값을 사용해, 다음의 텍스쳐 스테이지의 환경 맵을 처리하는 텍스쳐 좌표를 수정한다. 트랜스 폼 행렬의 계수는,D3DTSS_BUMPENVMAT00 ,D3DTSS_BUMPENVMAT10 ,D3DTSS_BUMPENVMAT01 , 및 D3DTSS_BUMPENVMAT11 텍스쳐 스테이지 스테이트에서 설정한다.

u 및 v 델타값 외에도, 시스템에서는, 다음의 블렌딩 스테이지의 환경 맵의 색의 곱셈에 사용하는 휘도를 계산할 수 있다.

이 공식에서는,L' 는 계산되는 출력 휘도이다. 변수 L 는 범프 맵 픽셀로부터 취득되는 휘도값이며, 스케일링 계수 S 로 곱셈되어 변수 O 의 값으로 오프셋(offset) 된다. D3DTSS_BUMPENVLSCALE 및 D3DTSS_BUMPENVLOFFSET 텍스쳐 스테이지 스테이트는, 공식의 변수 S 및 O 의 값을 제어한다. 이 공식이 적용되는 것은, 범프 맵을 포함한 스테이지의 텍스쳐 블렌딩 처리가 D3DTOP_BUMPENVMAPLUMINANCE 로 설정되어 있는 경우뿐이다. D3DTOP_BUMPENVMAP 를 사용할때는,L' 의 값에 1.0 이 사용된다.

출력 델타값 Du' 및 Dv' 의 계산 후, 시스템에서는, 이러한 값을 다음의 텍스쳐 스테이지의 텍스쳐 좌표에 추가해, 선택되고 있는 색의 휘도를 곱셈해, 다각형에 적용하는 색을 생성한다.


범프 맵핑의 사용법

여기에서는, Microsoft® Direct3D® 의 범프 맵핑을 사용할 때에, 어플리케이션으로 실행하는 가장 일반적인 태스크에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 범프 맵핑의 지원의 검출
  • 범프 맵 텍스쳐의 생성
  • 범프 맵핑 파라미터의 설정


범프 맵핑의 지원의 검출

Microsoft® Direct3D® 디바이스가 D3DTOP_BUMPENVMAP 또는 D3DTOP_BUMPENVMAPLUMINANCE 의 몇개의 텍스쳐 블렌딩 처리를 지원 하고 있는 경우, 그 디바이스에서는 범프 맵핑을 실행할 수 있다. 또, 어플리케이션에서는 디바이스 능력을 조사하는 것으로, 그 어플리케이션으로 적절한 블렌딩 스테이지수 (보통은 3 개 이상)가 지원 되어 적어도 1 개의 범프 맵핑 픽셀 포맷이 공개되고 있는 것을 확인할 필요가 있다.

다음의 코드는, 지정된 조건에 의해 디바이스 기능을 조사해, 현재의 디바이스에서의 범프 맵핑의 지원을 검출한다.

BOOL SupportsBumpMapping()
{
    D3DCAPS8 d3dCaps;

    d3dDevice->GetDeviceCaps( &d3dCaps );

    // 이 디바이스가 2 개의 범프 맵핑 브렌드 처리를 지원 하고 있을지 어떨지.
    if ( 0 == d3dCaps.TextureOpCaps & ( D3DTEXOPCAPS_BUMPENVMAP |
                                         D3DTEXOPCAPS_BUMPENVMAPLUMINANCE ))
        return FALSE;

    // 이 디바이스가 최대 3 개의 블렌딩 스테이지를 지원 하고 있을지 어떨지.
    if( d3dCaps.MaxTextureBlendStages < 3 )
        return FALSE;
}


범프 맵 텍스쳐의 생성

다른 텍스쳐의 경우와 같게, 범프 맵 텍스쳐를 생성 한다. 어플리케이션으로 범프 맵핑의 지원을 확인해, 유효한 픽셀 포맷을 취득하면(자) ( 「범프 맵핑의 지원의 검출」로 설명하도록(듯이)), 범프 맵 텍스쳐 표면을 생성 할 수 있다. 텍스쳐의 생성에 대해서는, 「텍스쳐 표면 오브젝트의 취득」을 참조할것.

표면의 생성 후는, 적절한 델타값을 가지는 각 픽셀과 휘도 (표면 포맷에 휘도가 포함되는 경우)를 로드할 수 있다. 각 픽셀 컴퍼넌트의 값에 대해서는, 「범프 맵 픽셀 포맷」으로 설명한다.


범프 맵핑 파라미터의 설정

어플리케이션으로 범프 맵의 생성과 각 픽셀의 내용의 설정이 완료하면(자), 범프 맵핑 파라미터를 설정해 렌더링의 준비를 실시할 수가 있다. 범프 맵핑 파라미터에는, 필요한 텍스쳐와 그 블렌딩 처리나, 범프 맵 자체에 대한 트랜스 폼과 휘도의 제어등을 설정한다.

C++ 로 범프 맵핑 파라미터를 설정하려면

  1. 베이스 텍스쳐 맵 (사용되고 있는 경우), 범프 맵, 및 환경 맵 텍스쳐를 텍스쳐 블렌딩 스테이지로 설정한다.
  2. 각 텍스쳐 스테이지의 색 및 알파 블렌딩 처리를 설정한다.
  3. 범프 맵 트랜스 폼 행렬을 설정한다.
  4. 필요에 따라서, 휘도 스케일값 및 오프셋(offset)값을 설정한다.

다음의 코드에서는, 베이스 텍스쳐 맵, 범프 맵, 및 스펙큐러 환경 맵의 3 개의 텍스쳐를, 적절한 텍스쳐 블렌딩 스테이지로 설정한다.

    // 3 개의 텍스쳐를 설정한다.
    d3dDevice->SetTexture( 0, d3dBaseTexture );
    d3dDevice->SetTexture( 1, d3dBumpMap );
    d3dDevice->SetTexture( 2, d3dEnvMap );

텍스쳐를 블렌딩 스테이지로 설정한 후, 다음의 코드로, 각 스테이지의 블렌딩 처리 및 인수를 준비한다.

    // 칼라 처리 및 인수를 설정해 범프 맵핑
    // (을)를 준비한다.

    // 스테이지 0:베이스 텍스쳐.
    d3dDevice->SetTextureStageState( 0, D3DTSS_COLOROP, D3DTOP_MODULATE );
    d3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    d3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );
    d3dDevice->SetTextureStageState( 0, D3DTSS_ALPHAOP, D3DTOP_SELECTARG1 );
    d3dDevice->SetTextureStageState( 0, D3DTSS_ALPHAARG1, D3DTA_TEXTURE );
    d3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX, 1 );

    // 스테이지 1:범프 맵 - 이 예에서는 휘도를 사용한다.
    d3dDevice->SetTextureStageState( 1, D3DTSS_TEXCOORDINDEX, 1 );
    d3dDevice->SetTextureStageState( 1, D3DTSS_COLOROP, D3DTOP_BUMPENVMAPLUMINANCE);
    d3dDevice->SetTextureStageState( 1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    d3dDevice->SetTextureStageState( 1, D3DTSS_COLORARG2, D3DTA_CURRENT );

    // 스테이지 2:스펙큐러 환경 맵.
    d3dDevice->SetTextureStageState( 2, D3DTSS_TEXCOORDINDEX, 0 );
    d3dDevice->SetTextureStageState( 2, D3DTSS_COLOROP, D3DTOP_ADD );
    d3dDevice->SetTextureStageState( 2, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    d3dDevice->SetTextureStageState( 2, D3DTSS_COLORARG2, D3DTA_CURRENT );

블렌딩 처리 및 인수를 설정한 후, 다음의 코드로,D3DTSS_BUMPENVMAT00 및 D3DTSS_BUMPENVMAT11 텍스쳐 스테이지 스테이트를 1.0 으로 설정해, 2×2 범프 맵핑 행렬을 단위행렬로 설정한다. 행렬을 단위행렬로 설정 하면, 시스템에서는 미수정의 범프 맵의 델타값이 사용되게 되지만, 이것은 반드시 필요하지 않다.

    // 범프 맵핑 행렬을 설정한다.
    //
    // 주
    //    이러한 호출은, 이하의 인 라인 쇼트 컷 함수에 의존한다.
    //       inline DWORD F2DW( FLOAT f ) { return *((DWORD*) &f); }
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT00, F2DW(1.0f) );
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT01, F2DW(0.0f) );
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT10, F2DW(0.0f) );
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT11, F2DW(1.0f) );

범프 맵핑 처리에 휘도 (D3DTOP_BUMPENVMAPLUMINANCE)를 포함하는 경우는, 휘도 제어를 설정할 필요가 있다. 휘도 제어에 의해, 다음의 스테이지의 텍스쳐로부터 색을 조정하기 전에 시스템이 실시하는 휘도의 계산방법을 설정한다. 상세한 것에 대하여는, 「범프 맵핑의 공식」을 참조할것.

    // 휘도 제어를 설정한다. 이 설정이 필요한 것은,
    // 휘도를 포함한 범프 맵을 사용하는 경우, 및
    // D3DTOP_BUMPENVMAPLUMINANCE 텍스쳐 블렌딩 처리가 사용되는 경우 뿐이다.
    //
    //
    // 주
    //    이러한 호출은, 이하의 인 라인 쇼트 컷 함수에 의존한다.
    //       inline DWORD F2DW( FLOAT f ) { return *((DWORD*) &f); }
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVLSCALE, F2DW(0.5f) );
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVLOFFSET, F2DW(0.0f) );

어플리케이션으로 범프 맵핑 파라미터를 설정한 후는, 보통대로 렌더링을 실행할 수 있어 렌더링 되는 다각형에 범프 맵핑 이펙트가 적용된다.

주 이 예에서는, 파라미터는 스펙큐러 환경 매핑용으로 설정되어 있다. 디퓨즈 라이트 매핑을 실시하는 경우는, 마지막 스테이지의 텍스쳐 블렌딩 처리를 D3DTOP_MODULATE 로 설정한다. 상세한 것에 대하여는, 「디퓨즈 라이트 맵」을 참조할것.


환경 매핑

여기에서는, Microsoft® Direct3D® 의 일반적인 2 종류의 환경 매핑의 실행에 대해 설명한다. 그래픽스 업계에서는 다종 다양한 환경 매핑이 사용되고 있지만, 이하의 주제에서는, 가장 일반적인 큐브 환경 맵 및 구(공)장 환경 매핑에 대해 설명한다.

  • 환경 매핑이란
  • 큐브 환경 맵
  • 구(공)장 환경 매핑


환경 매핑이란

환경 매핑이란, 반사성의 높은 표면을 레이 트래싱을 사용하지 않고 시뮬레이트 하는 방법이다. 실제, 환경 매핑에서는, 오브젝트의 주위의 경치를 포함한 특수한 텍스쳐 맵이 그 오브젝트 자체에 적용된다. 그 결과, 반사성을 가지는 표면에는, 충분히 사람의 눈을 속일 수 있는 정도로 주위의 경치가 비친다. 레이 트래싱을 실행했을 경우에 생기는 계산 부하도 발생하지 않는다.

다음의 화면은,SphereMap 샘플의 것이다. 이름으로부터 알도록(듯이), 이 샘플에서는 구(공)장 환경 매핑으로 불리는 환경 매핑을 사용하고 있다. 상세한 것에 대하여는, 「구(공)장 환경 매핑」을 참조할것.

이 티폿트는 주위의 경치를 반사하고 있는 것처럼 보이지만, 실제로는 텍스쳐가 적용되고 있다. 환경 매핑은, 텍스쳐 (특수한 계산으로 요구한 텍스쳐 좌표를 조합한 것)를 사용하기 위해(때문에) 순간에 실행된다.


큐브 환경 맵

큐브 환경 맵에서는, 오브젝트의 주위의 공간 또는 라이팅의 이펙트가 그 오브젝트의 표면을 따라 적용된다. 이것은 입방체의 내부의 6 개의 면에 의해 표현된다. 설명하는 주제는, 다음과 같다.

  • 큐브 환경 맵이란
  • 큐브 환경 맵 표면의 생성
  • 큐브 환경 맵 표면에의 액세스
  • 큐브 환경 맵의 밉맵화
  • 큐브 환경 맵에의 렌더링
  • 큐브 환경 맵의 텍스쳐 좌표


큐브 환경 맵이란

큐브 환경 맵 (큐브 맵이라고도 불린다)이란, 오브젝트의 주위의 장면을 오브젝트가 입방체의 중심으로 있는 것 같게 표현한 화면 데이터를 포함한 텍스쳐이다. 큐브 환경 맵의 각면은, 수평 방향과 수직 방향의 90о의 시야를 대상으로 해, 1 개의 큐브 맵에는 6 개의 면이 있다. 각면의 방향은, 다음의 그림에 나타내는 대로이다.

입방체의 각면은, 월드 공간의 x/y, y/z, 또는 x/z 평면에 수직에 위치 좌표 한다. 다음의 그림은, 각 평면과 면의 대응을 나타내고 있다.

큐브 환경 맵은, 일련의 텍스쳐 오브젝트로서 이행 된다. 어플리케이션에서는, 큐브 환경 맵에 정적인 화면을 사용하거나 큐브 맵의 면에 렌더링을 실시하는 것으로 동적인 환경 매핑을 실행할 수가 있다. 이 경우, 큐브 맵 표면은 유효한 렌더링 타겟 표면이 아니면 안되어, D3DUSAGE_RENDERTARGET 플래그 세트로 생성 되고 있을 필요가 있다.

큐브 맵의 각면에는, 주위의 장면이 치밀하게 렌더링 될 필요는 없다. 대부분의 경우, 환경 맵은 만곡 표면에 적용된다. 대부분의 어플리케이션으로 사용하는 만곡의 정도가 주어졌다고 하면, 결과적으로 히않고 다 화면이 생성되기 (위해)때문에, 환경 맵의 치밀함은 메모리의 점으로부터도 렌더링의 오버헤드의 점으로부터도 쓸데없게 된다.


큐브 환경 맵 표면의 생성

큐브 환경 맵 텍스쳐를 생성 하려면 ,IDirect3DDevice8::CreateCubeTexture 메소드를 호출한다. 큐브 환경 맵 텍스쳐는 직사각형이 아니면 안되어, 그 크기는 2 의 거듭제곱이다.

다음의 코드는, C++ 어플리케이션으로 단순한 큐브 환경 맵을 생성 하는 방법을 나타내고 있다.

/*
** 이 예에서는, m_d3dDevice 는 IDirect3DDevice8 인터페이스에의
* 유효한 포인터이라고 가정하고 있다.
 */

LPDIRECT3DCUBETEXTURE8 m_pCubeMap;

m_d3dDevice->CreateCubeTexture( 256, 1, D3DUSAGE_RENDERTARGET, D3DFMT_R8G8B8,
                                D3DPOOL_MANAGED, &m_pCubeMap );


큐브 환경 맵 표면에의 액세스

IDirect3DCubeTexture8::GetCubeMapSurface 메소드를 사용해 큐브 환경 맵의 표면으로부터 표면으로 이동할 수 있다.

다음의 코드는,GetCubeMapSurface 를 사용해, 정방향의 y 면 (표면 2)의 큐브 맵 표면을 취득한다.

/*
* 이 예에서는, m_pCubeMap 는 IDirect3DCubeTexture8 인터페이스에의
* 유효한 포인터이다.
 */
LPDIRECT3DSURFACE8 pFace2;

m_pCubeMap->GetCubeMapSurface( D3DCUBEMAP_FACE_POSITIVE_Y, 0, &pFace2);

GetAttachedSurface 가 받는 제 1 파라미터는, 이 메소드로 취득할 필요가 있는 어태치 된 표면을 기술하는 D3DCUBEMAP_FACES 열거형이다. 제 2 파라미터는, 취득하는 밉맵화 큐브 텍스쳐의 레벨을 Microsoft® Direct3D® 에 지시한다. 제 3 파라미터는, 돌려주어지는 큐브 텍스쳐 표면을 나타내는 IDirect3DSurface8 인터페이스의 주소이다. 이 경우, 이 큐브 맵은 밉맵화되어 있지 않기 때문에, 0 이 사용된다.

주 이 메소드를 호출한 후는,IDirect3DSurface8 인터페이스의 내부 참조 카운트가 증가한다. 이 표면을 사용한 후는, 반드시 IDirect3DSurface8 인터페이스에 대해서 IUnknown::Release 메소드를 호출하는 것. 호출하지 않으면 메모리 누수가 된다.


큐브 환경 맵의 밉맵화

큐브 환경 맵은 밉맵화할 수 있다. DDSCAPS_MIPMAP 능력을 포함하면(자), 어태치 된 밉맵 표면이 있는 각 표면이 생성 된다. 이러한 표면의 형상은, 다음의 그림에 나타내게 된다.

밉맵화 큐브 환경 맵을 생성 하는 어플리케이션으로 각 표면에 액세스 하려면 ,IDirect3DCubeTexture8::GetCubeMapSurface 메소드를 호출한다. D3DCUBEMAP_FACES 열거형으로부터 적절한 값을 설정해 시작 한다. 이것에 대해서는, 「큐브 환경 맵 표면에의 액세스」로 설명한다. 다음에,Level 파라미터를 목적의 밉맵 레벨로 설정해, 취득하는 레벨을 선택한다. 0 은 최상정도 화면에 대응하는 것을 생각해 내는 것.


큐브 환경 맵에의 렌더링

큐브 맵의 개개의 표면에는, 그 외의 텍스쳐나 표면 오브젝트와 같이 화면을 카피할 수가 있다. 이 렌더링을 실시하기 전에 실행하는 가장 중요한 일은, 카메라를 올바르게 배치해, 그 표면에 대해서 올바를 방향을 향하도록(듯이) 트랜스 폼 행렬을 설정하는 것이다. 올바를 방향이란, 전방 (+z), 후방 (-z), 좌 (-x), 우 (+x), 윗쪽 (+y), 또는 하부 (-y)이다.

다음의 C++ 코드는, 렌더링 하는 표면에 응해 뷰 행렬을 준비해 설정한다.

/*
* 이 예에서는, pCubeMap 은 IDirect3DCubeTexture8 인터페이스에의 유효한 포인터이며,
* d3dDevice 는 IDirect3DDevice8 인터페이스에의
* 유효한 포인터이다.
 */
void RenderFaces()
{
    // 디바이스의 트랜스 폼 행렬을 보존한다.
    D3DXMATRIX matProjSave, matViewSave;
    d3dDevice->GetTransform( D3DTS_VIEW,       &matViewSave );
    d3dDevice->GetTransform( D3DTS_PROJECTION, &matProjSave );

    // 현재의 백 버퍼와 z 버퍼를 저장 한다.
    LPDIRECT3DSURFACE8 pBackBuffer, pZBuffer;
    d3dDevice->GetRenderTarget( &pBackBuffer );
    d3dDevice->GetDepthStencilSurface( &pZBuffer );

큐브 환경 맵의 각 표면에는 90о의 시야가 포함되는 것을 생각해 내는 것. 어플리케이션으로 특수 효과등을 (위해)때문에에 시야의 각도를 변경하지 않는 한, 이 각도에 응해 투영 행렬을 설정하도록(듯이) 주의가 필요하다.

다음의 코드는, 가장 일반적으로 사용하는 투영 행렬을 생성 및 설정한다.

    // 90о의 시야를 투영에 사용한다.
    D3DMATRIX matProj;
    D3DXMatrixPerspectiveFovLH( matProj, D3DX_PI/2, 1.0f, 0.5f, 1000.0f );
    d3dDevice->SetTransform( D3DTS_PROJECTION, &matProj );

    // 큐브 맵의 6 개의 표면에 대해서 루프 처리를 실행한다.
    for( DWORD i=0; i<6; i++ )
    {
        // 이하와 같이, 표준 뷰를 오버라이드(override) 한다.
        D3DVECTOR vEnvEyePt = D3DVECTOR( 0.0f, 0.0f, 0.0f );
        D3DVECTOR vLookatPt, vUpVec;

        switch( i )
        {
            case D3DCUBEMAP_FACE_POSITIVE_X:
                vLookatPt = D3DVECTOR( 1.0f, 0.0f, 0.0f );
                vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                break;
            case D3DCUBEMAP_FACE_NEGATIVE_X:
                vLookatPt = D3DVECTOR(-1. 0f, 0.0f, 0.0f );
                vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                break;
            case D3DCUBEMAP_FACE_POSITIVE_Y:
                vLookatPt = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                vUpVec    = D3DVECTOR( 0.0f, 0.0f,-1. 0f );
                break;
            case D3DCUBEMAP_FACE_NEGATIVE_Y:
                vLookatPt = D3DVECTOR( 0.0f,-1. 0f, 0.0f );
                vUpVec    = D3DVECTOR( 0.0f, 0.0f, 1.0f );
                break;
            case D3DCUBEMAP_FACE_POSITIVE_Z:
                vLookatPt = D3DVECTOR( 0.0f, 0.0f, 1.0f );
                vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                break;
            case D3DCUBEMAP_FACE_NEGATIVE_Z:
                vLookatPt = D3DVECTOR( 0.0f, 0.0f,-1. 0f );
                vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                break;
        }

        D3DMATRIX matView;
        D3DXMatrixLookAtLH( matView, vEnvEyePt, vLookatPt, vUpVec );
        d3dDevice->SetTransform( D3DTS_VIEW, &matView );

카메라를 올바르게 배치해, 투영 행렬을 설정 하면, 장면을 렌더링 할 수 있다. 장면의 각 오브젝트는, 보통 배치 하면 내려에 배치한다. 다음의 코드에서는, 처리 전체를 알 수 있도록(듯이), 이 태스크의 개략을 나타낸다.

        //렌더링 하는 표면에의 포인터를 취득한다.
        LPDIRECT3DSURFACE8 pFace;
        pCubeMap->GetCubeMapSurface( (D3DCUBEMAP_FACES) i, 0, &pFace );
        d3dDevice->SetRenderTarget ( pFace , pZBuffer );
        pFace->Release();

        d3dDevice->BeginScene();
        // 여기서, 장면을 렌더링 한다.
        d3dDevice->EndScene();
    }

    // 렌더링 타겟을 메인 백 버퍼에 되돌린다.
    d3dDevice->SetRenderTarget( pBackBuffer, pZBuffer );
    pBackBuffer->Release();
    pZBuffer->Release();

    // 원의 트랜스 폼 행렬을 restore 한다.
    d3dDevice->SetTransform( D3DTS_VIEW,       &matViewSave );
    d3dDevice->SetTransform( D3DTS_PROJECTION, &matProjSave );
}

IDirect3DDevice8::SetRenderTarget 메소드의 호출에는 주의 해야 한다. 큐브 맵 표면에 렌더링 하면나무는, 그 표면을 경향 렌더링 타겟 표면으로서 할당할 필요가 있다. 깊이 버퍼를 사용하는 어플리케이션에서는, 그 렌더링 타겟으로 명시적으로 깊이 버퍼를 생성 하거나 기존의 깊이 버퍼를 렌더링 타겟 표면에 재할인 맞히고 할 수가 있다. 위에의 코드에서는, 후자의 방법을 사용하고 있다.


큐브 환경 맵의 텍스쳐 좌표

큐브 환경 맵을 지시하는 텍스쳐 좌표는, 표준 텍스쳐를 적용할 때에 사용하는 단순한 u, v 스타일의 좌표와는 다르다. 실제, 큐브 환경 맵에서는 텍스쳐 좌표를 사용하지 않는다. 텍스쳐 좌표 세트 대신에, 큐브 환경 맵에서는 3D 벡터가 필요하다. 적절한 버텍스 포맷을 지정하는 것이 중요하다. 또, 시스템에 어플리케이션으로 사용하는 텍스쳐 좌표세트수를 알리는 것 외에도, 각 세트내의 요소수에 대한 정보를 알릴 필요가 있다. Microsoft®Direct3D® 는, 이것을 실시하기 위해서(때문에) 매크로의 D3DFVF_TEXCOORDSIZEn 세트를 준비해 있다. 이러한 매크로에는 파라미터가 1 개 있어, 사이즈가 기술되는 텍스쳐 좌표 세트의 인덱스를 식별한다. 3D 벡터의 경우는, D3DFVF_TEXCOORDSIZE3 매크로로 생성 하는 비트 패턴을 포함한다. 다음의 코드는, 이 매크로의 사용 방법을 나타내고 있다.

/*
* 버텍스의 유연한 버텍스 포맷 기술자를 생성 한다.
* 이것에는, 위치 좌표, 법선, 및
* 3D 텍스쳐 좌표세트가 1 개 포함된다.
 */
DWORD dwFVF = D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_TEX1 | D3DFVF_TEXCOORDSIZE3(0);

디퓨즈 라이트 매핑등의 경우에는, 벡터에 카메라 공간의 버텍스 법선을 사용한다. 스펙큐러 환경 매핑등의 경우에는, 반사 벡터를 사용하는 트랜스 폼이 끝난 버텍스 법선에 대해서는 넓게 이해되고 있기 (위해)때문에, 여기에서는 반사 벡터의 계산에 대해 자세하게 설명한다.

독자적으로 반사 벡터를 계산하려면 , 각 버텍스의 위치 좌표와 뷰 포토로부터 그 버텍스에의 벡터를 알고 있을 필요가 있다. Direct3D 에서는 지오메트리의 반사 벡터를 자동적으로 계산할 수 있다. 이 기능을 사용하면, 환경 맵의 텍스쳐 좌표를 포함할 필요가 없기 때문에, 메모리를 절약할 수 있다. 게다가 대역폭이 감소해, TnLHAL 디바이스의 경우는, 어플리케이션으로 독자적으로 계산하는 것 보다 훨씬 빠르게 계산을 실행할 수 있다. 이 기능을 이용하려면 , 큐브 환경 맵을 포함한 텍스쳐 스테이지에 있어, D3DTSS_TEXCOORDINDEX 텍스쳐 스테이지 스테이트를, D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR 플래그의 편성과 텍스쳐 좌표 세트의 인덱스로 설정한다. 디퓨즈 라이트 매핑의 경우등에는, D3DTSS_TCI_CAMERASPACENORMAL 플래그를 사용해, 시스템에 카메라 공간의 트랜스 폼이 끝난 버텍스 법선을 텍스쳐의 애드레싱 벡터로서 사용하는 것을 알릴 수가 있다. 인덱스는, 시스템이 텍스쳐의 랩핑 모드를 결정하기 위해서(때문에) 마셔 사용한다.

다음의 코드는, 이 값의 사용 방법을 나타내고 있다.

/*
* 변수 m_d3dDevice 는, IDirect3DDevice8 인터페이스에의
* 유효한 포인터이다.
 *
* 스테이지 2 에 대해서 텍스쳐 좌표를 자동 생성한다.
* 여기에서는, 스테이지 2 에 큐브 맵을 할당할 수 있고 있다고 한다.
* 인덱스 1 의 텍스쳐 좌표 세트로부터의 랩 모드를 사용한다.
 */
m_d3dDevice->SetTextureStageState( 2, D3DTSS_TEXCOORDINDEX,
                                   D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR | 1);

자동 텍스쳐 좌표 생성을 유효하게 하면, 2 개의 공식의 어느쪽이든을 사용해 각 버텍스의 반사 벡터가 계산된다. D3DRS_LOCALVIEWER 렌더링 스테이트를 TRUE 로 설정 하면, 다음의 공식이 사용된다.

이 공식에서는,R 는 계산하는 반사 벡터,E 는 위치 좌표로부터 시점까지의 정규화된 벡터,N 는 카메라 공간의 버텍스 법선이다.

D3DRS_LOCALVIEWER 렌더링 스테이트를 FALSE 로 설정 하면, 다음의 공식이 사용된다.

이 공식에서는,R 및 N 요소에 대해서는 전의 공식과 같다. Nz 요소는 버텍스 법선의 월드 공간 z,I 는 무한대 거리에 있는 뷰 포토의 벡터 (0,0,1)이다. 시스템에서는, 몇개의 공식에서 요구한 반사 벡터를 사용해, 큐브 맵의 적절한 표면을 선택 및 처리한다.

주 대부분의 경우, 어플리케이션에서는 버텍스 법선의 자동 정규화를 유효하게 할 필요가 있다. 이것을 유효하게 하려면 , D3DRS_NORMALIZENORMALS 를 TRUE 로 설정한다. 이 렌더링 스테이트를 유효하게 하고 있지 않는 경우, 환경 맵의 외관이 기대와는 크게 다른 것이 된다.


구(공)장 환경 매핑

구(공)장 환경 매핑 (구(공)장 매핑으로 불리는 것이 많다)은, 오브젝트의 주위의 공간의 화면 또는 라이팅의 이펙트를, 그 오브젝트의 표면을 따라 붙여 간다. 이 때, 오브젝트의 주위의 공간은, 특수한 포맷의 텍스쳐 맵에 코드화 된다. 이하의 주제에서는, 구(공)장 매핑의 개념에 대해, 및 Microsoft Direct3D 어플리케이션에서의 구(공)장 매핑의 사용 방법에 대해 설명한다.

  • 구(공)장 환경 맵이란
  • 구(공)장 환경 맵의 텍스쳐 좌표
  • 구(공)장 환경 맵의 적용


구(공)장 환경 맵이란

구(공)장 환경 맵, 또는 구(공)장 맵은, 오브젝트의 주위의 장면의 화면 또는 오브젝트의 주위의 라이팅 이펙트를 포함한 특수한 텍스쳐이다. 큐브 환경 맵과는 달라, 구(공)장 맵은 오브젝트의 주위의 모습을 직접 표현하는 것은 아니다. 「환경 매핑이란」의 주제의 티폿트의 화면은, 구(공)장 매핑으로 실현될 수 있는 반사 이펙트를 나타내고 있다.

구(공)장 맵은, 오브젝트의 주위의 360о의 시야를, 어안 렌즈로 본 것처럼 2D 표현한 것이다. 다음의 그림은,SphereMap 샘플로 사용하는 구(공)장 맵을 나타내고 있다.


구(공)장 환경 맵의 텍스쳐 좌표

환경 매핑의 대상이 되는 각 버텍스로 지정하는 텍스쳐 좌표는, 텍스쳐를 만곡한 표면에 비치는 왜곡의 함수로서 처리할 필요가 있다. 어플리케이션에서는, 각 버텍스의 텍스쳐 좌표를 계산해, 목적의 이펙트를 실현되지 않으면 안 된다. 텍스쳐 좌표를 간단하고 효과적으로 생성하는 방법은, 버텍스 법선을 입력으로서 사용하는 것이다. 방법에는 몇 종류인가 있지만, 다음의 공식은, 구(공)장 맵에 의한 환경 매핑을 실행하는 어플리케이션으로 공통의 공식이다.

이 공식에서는,u 및 v 는 계산하는 텍스쳐 좌표,Nx 및 Ny 는 카메라 공간의 버텍스 법선의 x 및 y 요소이다. 이 공식은 단순하고 유효하다. 법선에 정방향의 x 요소가 있는 경우, 법선은 우측향을 가리키고 있어u 좌표는 텍스쳐를 적절히 처리할 수 있도록(듯이) 조정된다. v 좌표도 마찬가지, 정방향의 y 는, 법선이 윗방향을 가리키고 있는 것을 나타낸다. 각 성분의 부의 값에 대해서는, 이 반대가 성립된다.

법선이 직접 카메라를 가리키고 있는 경우, 결과의 좌표에는 왜곡이 생기지 않는다. 양쪽 모두의 좌표에 +0. 5 바이어스를 더하면(자), 왜곡이 없는 포인트는 구(공)장 맵의 중앙에 배치되어(0, 0, z)의 버텍스 법선에 의해 이 포인트가 처리된다. 이 공식에서는, 법선의 z 요소는 고려되지 않는다. 다만, 이 공식을 사용하는 어플리케이션에서는, 정방향의 z 요소가 있는 법선을 가지는 버텍스를 생략 하는 것으로 계산을 최적화할 수 있다. 이러한 처리를 하는 것은, 카메라 공간에서 법선이 카메라로부터 멀어질 방향 (z 의 정방향)을 가리키고 있는 경우, 오브젝트의 렌더링시에 버텍스가 카링 되기 때문에 있다.


구(공)장 환경 맵의 적용

환경 맵을 오브젝트에 적용 하면나무는, 그 외의 텍스쳐의 경우와 같이,IDirect3DDevice8::SetTexture 메소드로 적절한 텍스쳐 스테이지에 텍스쳐를 설정한다. 제 1 파라미터에는, 목적의 텍스쳐 스테이지의 인덱스를 설정해, 제 2 파라미터에는, 환경 맵의 큐브 맵 텍스쳐의 생성시에 돌려주어진 IDirect3DcubeTexture8 인터페이스의 주소를 설정한다. 필요에 따라서 색 및 알파 블렌딩 처리와 인수를 설정해, 목적의 텍스쳐 블렌딩 이펙트를 얻을 수 있다.


fog

여기에서는, fog 기능을 소개해, Microsoft® Direct3D® 어플리케이션에서의 각종 fog 기능의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • fog의 개요
  • fog 공식
  • fog 파라미터
  • fog 블렌딩
  • fog 칼라
  • 픽셀 fog
  • 버텍스 fog

fog 블렌딩은, 렌더링 스테이트에서 제어된다. 프로그램 가능한 픽셀 파이프라인의 일부에서는 없다.


fog의 개요

3D 신에 fog를 추가하는 것으로써, 보다 리얼한 정경을 표현하거나 분위기를 내거나 먼 경치를 애매하게 할 수가 있다. Microsoft® Direct3D® 는, 픽셀 fog와 버텍스 fog라고 하는 2 개의 fog 모델을 지원 한다. 이 2 개(살)은, 각각 고유의 기능과 프로그래밍 인터페이스를 가진다.

fog는, 기본적으로는, 장면내의 오브젝트의 깊이 또는 시점으로부터의 거리에 근거해, 장면내의 오브젝트의 색과 선택한 fog 칼라를 브렌드 해 실현된다. 오브젝트가 멀어지는에 따라, 원의 색과 fog 칼라의 브렌드가 늘어나, 장면에 떠오르는 작은 입자에 의해 오브젝트의 표시가 노망나 간다. 다음의 화면은, fog없이 렌더링 한 장면과 fog를 유효하게 해 렌더링 한 같은 장면을 나타내고 있다.

위에의도로, 좌측의 장면에는 명료한 수평선이 있어, 저 너머에는 열매 세계에서는 보여야할 풍경이 안보인다. 우측의 장면에서는 배경색과 동일한 fog 칼라를 사용해 수평선이 애매하게 해져 다각형이 먼 곳에서는 사라지는 것처럼 보인다. 개별의 fog 이펙트와 크리에이티브인 장면 디자인을 조합하면(자), 장면내의 오브젝트의 색을 완화시켜 분위기를 늘릴 수가 있다.

Direct3D 에서는, 픽셀 fog와 버텍스 fog라고 하는 2 개의 방법으로 장면에 fog를 추가할 수 있다. 각각의 이름은, 그 fog 효과의 적용 방법을 나타내고 있다. 상세한 것에 대하여는, 「픽셀 fog」 및 「버텍스 fog」를 참조할것. 간단하게 말하면, 픽셀 fog (테이블 fog라고도 한다)는 디바이스 드라이버로 이행 되어 버텍스 fog는 Direct3D 라이팅 엔진으로 이행 된다.

주 버텍스 fog 및 픽셀 fog의 머지않아를 사용하는 경우에서도, 어플리케이션에서는 fog 이펙트가 올바르게 적용되도록(듯이) 적절한 투영 행렬을 준비할 필요가 있다. 이 제약은, Direct3D 트랜스 폼 & 라이팅 엔진을 사용하지 않는 어플리케이션에도 들어맞는다. 적절한 행렬의 생성 방법의 상세한 것에 대하여는, 「W 버퍼에 유효한 투영 행렬」을 참조할것.


fog 공식

C++ 어플리케이션에서는, Microsoft® Direct3D® 로 거리에 응해 fog 이펙트의 계산을 변경하는 것으로써, fog가 장면의 오브젝트의 색에게 주는 영향을 제어할 수 있다. D3DFOGMODE 열거형에는, 3 개의 fog 공식을 식별하는 멤버가 포함되어 있다. 모든 식은, 어플리케이션이 설정하는 파라미터가 주어져 거리의 함수로서 fog 계수를 계산한다. 거리가 어떻게 계산될까는, 범위 베이스의 fog가 유효한지 어떤지와 투영 행렬에 의해 변화한다. 상세한 것에 대하여는, 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」 및 「범위 베이스의 fog」를 참조할것.

D3DFOG_LINEAR

이 선형 공식에서,start 는 fog 이펙트가 시작되는 거리,end 는 fog 이펙트가 그 이상 증가하지 않게 되는 거리,d 는 장면의 범위내에서의 깊이 또는 시점으로부터의 거리를 나타낸다. 오브젝트가 먼 곳이 되는에 따라 d 의 값이 증가한다. 선형 공식과 지수 공식은, 픽셀 fog와 버텍스 fog의 양쪽 모두로 지원 되고 있다.

D3DFOG_EXP

D3DFOG_EXP2

위에의 2 개의 지수 공식에서,e 는 자연대수의 바닥 ( 약 2.71828),density 는 0.0 에서 1.0 의 범위의 임의의 fog 밀도,d 는 장면의 범위내에서의 깊이, 즉 시점으로부터의 거리이다.

주 시스템은, 버텍스의 스펙큐러색의 알파 성분에 fog 계수를 저장 한다. 어플리케이션으로 독자적인 트랜스 폼 & 라이팅을 실행하는 경우는, fog 계수를 수동으로 삽입해 두면(자), 렌더링시에 시스템이 그 fog 계수를 적용한다.

다음의 그림에서는, 공식의 파라미터에 공통의 값을 사용해, 이러한 공식을 그래프에 나타내고 있다.

Direct3D 가 fog 이펙트를 계산 하면나무는, 위에의 등식의 1 개의 fog 계수를 다음에 나타내는 블렌딩 공식에서 사용한다.

이 공식은, 현재의 다각형 Ci 의 색을 fog 계수 f 에 의해 효과적으로 스케일링 해, 그 적을, fog 계수의 비트 반전에 의해 스케일링 한 fog 칼라 Cf 에 가산한다. 결과적으로 얻을 수 있는 칼라값은, fog 칼라와 원의 색의 브렌드이며, 거리의 계수이기도 하다. 이 공식은, Microsoft DirectX® 7.0 및 그 이후가 지원 하는 모든 디바이스에 적용된다. 종래부터의 램프 디바이스에 대해서는, fog 계수는 디퓨즈색성분과 스펙큐러색성분을 스케일링 해, 0.0 에서 1.0 의 범위내 (0.0 으로 1.0 을 포함한다)에 넣는다. fog 계수는, 보통, 전방 클립면을 1.0 으로서 시작되어, 후방 클립면을 0.0 으로서 감소한다.


fog 파라미터

fog 파라미터는, 디바이스 렌더링 스테이트에 의해 제어된다. 픽셀 fog 및 버텍스 fog에서는 함께, 「fog 공식」에서 설명하는 fog 공식을 모두 지원 하고 있다. D3DFOGMODE 열거형은, Microsoft® Direct3D® 로 사용하는 fog 공식을 식별하는 정수를 정의한다. D3DRS_FOGTABLEMODE 렌더링 스테이트는, Direct3D 가 픽셀 fog에 사용하는 fog 모드를 제어해,D3DRS_FOGVERTEXMODE 렌더링 스테이트는 버텍스 fog의 모드를 제어한다.

선형 fog 공식을 사용할때는,D3DRS_FOGSTART 및 D3DRS_FOGEND 렌더링 스테이트를 사용해 시작 거리 및 엔딩 거리를 설정한다. 이러한 값을 시스템이 어떻게 해석할까는, 어플리케이션으로 픽셀 fog 및 버텍스 fog의 어느 쪽을 사용하고 있을까에 따라서 다르다. 픽셀 fog를 사용하고 있는 경우는, z 베이스 또는 w 베이스의 깊이가 사용된다. z 베이스 및 w 베이스의 깊이의 상세한 것에 대하여는, 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것. fog의 종류 및 fog의 시작 단위와 종료 단위를 이하의 표에 정리한다.

fog의 종류 | fog의 시작/종료 단위
픽셀 (Z) | 디바이스 공간 [0.0, 1.0]
픽셀 (W) | 카메라 공간
버텍스 | 카메라 공간

D3DRS_FOGDENSITY 렌더링 스테이트는, 지수 fog 공식이 유효한 때에 적용되는 fog 밀도를 제어한다. fog 밀도는, 본질적으로는 가중 계수이며, 지수의 거리값을 0.0 에서 1.0 (0.0 으로 1.0 을 포함한다)에 스케일링 한다.

시스템이 fog 블렌딩에 사용하는 색은,D3DRS_FOGCOLOR 디바이스 렌더링 스테이트를 사용해 제어한다. 상세한 것에 대하여는, 「fog 칼라」 및 「fog 블렌딩」을 참조할것.


fog 블렌딩

fog 블렌딩이란, 「fog 공식」에서 설명하도록(듯이), 장면에 표시하는 최종색을 생성하기 위해서, fog 및 오브젝트의 색에 fog 계수를 적용하는 것이다. D3DRS_FOGENABLE 렌더링 스테이트는, fog 블렌딩을 제어한다. 다음의 코드로 가리키도록(듯이), 이 렌더링 스테이트를 TRUE 로 설정 하면, fog 블렌딩이 유효하게 된다. 디폴트는 FALSE 이다.

//
// 이 예에서는, g_pDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이다.
HRESULT hr;
hr = g_pDevice->SetRenderState(
                     D3DRS_FOGENABLE,
                     TRUE);
if FAILED(hr)
    return hr;

fog 블렌딩은, 픽셀 fog와 버텍스 fog의 양쪽 모두에 대해서 유효하게 해야 한다. 이러한 종류의 fog의 사용 방법에 대해서는, 「픽셀 fog」 및 「버텍스 fog」를 참조할것.


fog 칼라

픽셀 fog 및 버텍스 fog의 양쪽 모두의 fog 칼라는,D3DRS_FOGCOLOR 렌더링 스테이트를 사용해 설정한다. 렌더링 스테이트값은, RGBA 색으로서 지정하는 임의의 RGB 색이다. 알파 성분은 무시된다.

다음의 C++ 코드는, fog 칼라를 흰색으로 설정한다.

/* 이 예에서는, 변수 d3dDevice 는 IDirect3DDevice8 인터페이스에의
* 유효한 포인터이다.
 */
HRESULT hr;

hr = d3dDevice->SetRenderState(
                    D3DRS_FOGCOLOR,
                    0x00FFFFFF); // 상위 8 비트는 사용되지 않는다.

if(FAILED(hr))
    return hr;


픽셀 fog

여기에서는, 픽셀 fog의 개념을 소개해, 픽셀 fog의 Microsoft® Direct3D® 어플리케이션에서의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 픽셀 fog에 대해
  • 시점으로부터의 상대 깊이대 Z 베이스의 깊이
  • 픽셀 fog의 사용법


픽셀 fog에 대해

픽셀 fog라는 이름은, 디바이스 드라이버로 픽셀 단위에 계산이 실행되는 것으로부터 붙일 수 있었던 이름이다. 이것에 대해서 버텍스 fog에서는, 트랜스 폼 & 라이팅을 실행할 때에 fog 이펙트가 계산된다. 픽셀 fog는, 드라이버에 따라서는, 블렌딩 계산에 적용하는 fog 계수 ( 각 픽셀의 깊이를 사용)를 결정하기 위해서(때문에) 사전에 계산된 룩 업 테이블을 사용하기 위해(때문에), 테이블 fog로 불리는 일도 있다.

픽셀 fog는,D3DFOGMODE 열거형의 멤버에 의해 식별되는 fog 공식의 어느쪽이든을 사용해 적용한다. 픽셀 fog 공식의 이행은 드라이버 고유하고, 드라이버가 복잡한 fog 공식을 지원 하고 있지 않는 경우는, 그다지 복잡하지 않은 공식을 사용하는 것.

주 「범위 베이스의 fog」로 설명하도록(듯이), 픽셀 fog는 범위 베이스의 fog의 계산을 지원 하지 않는다.


시점으로부터의 상대 깊이대 Z 베이스의 깊이

깊이 버퍼내에서의 z 값의 불균등인 격차에 의해 생기는, fog의 부자연스러운 그래픽스 효과를 억제하기 위해서(때문에), 대부분의 하드웨어 디바이스에서는, 픽셀 fog에 z 베이스 깊이값은 아니고 시점으로부터의 상대 깊이를 사용한다. 시점으로부터의 상대 깊이란, 본질적으로는 동차 좌표 세트로부터의 w 요소이다. Microsoft® Direct3D® 는, 디바이스 공간 좌표로부터 RHW 요소의 역수를 취득해 진정한 w 를 재생성한다. 디바이스가 시점과의 상대 fog를 지원 하고 있는 경우,IDirect3DDevice8::GetDeviceCaps 메소드를 호출하면, 그 디바이스는 D3DCAPS8 구조체의 RasterCaps 멤버에 D3DPRASTERCAPS_WFOG 플래그를 설정한다.

주 레퍼런스 래스터라이저를 제외해, 소프트웨어 디바이스는 항상 z 를 사용해 픽셀 fog 이펙트를 계산한다.

시점과의 상대 fog가 지원 되고 있을 때, 설정된 투영 행렬로 디바이스 공간의 w 값에 대응하는, 월드 공간의 z 값을 생성하는 경우, 시스템은 z 베이스 깊이보다 시점으로부터의 상대 깊이를 우선해 자동적으로 사용한다. 투영 행렬을 설정하려면 ,IDirect3DDevice8::SetTransform 메소드를 호출해, D3DTS_PROJECTION 값을 사용해, 목적의 행렬을 나타내는 D3DMATRIX 구조체를 건네준다. 투영 행렬이 이 요건에 대응하고 있지 않는 경우는, fog 이펙트가 올바르게 적용되지 않는다. 적절한 행렬의 생성의 상세한 것에 대하여는, 「W 버퍼에 유효한 투영 행렬」을 참조할것. 「투영 트랜스 폼이란」으로 설명하는 퍼스펙티브 투영 행렬은, 적절한 투영 행렬을 생성한다.

Direct3D 에서는, 현재 설정되어 있는 투영 행렬을 사용해 w 베이스 깊이의 계산을 실행한다. 따라서, 어플리케이션으로 Direct3D 트랜스 폼 파이프라인을 사용하지 않는 경우여도, 목적의 w 베이스 기능을 취득하기 위해서 적절한 투영 행렬을 설정해 둘 필요가 있다.

Direct3D 는 투영 행렬의 제 4 열을 조사한다. 계수가 [0,0,0,1] (아핀 투영)의 경우에는, 시스템은 z 베이스의 깊이값을 fog에 사용한다. 이 경우, 디바이스 공간의 선형 fog 이펙트의 시작 거리 및 종료 거리를 지정할 필요도 있다. 이 범위는, 유저에게 가장 가까운 포인트를 0.0 으로 해, 가장 먼 포인트를 1.0 으로 한 범위이다.


픽셀 fog의 사용법

어플리케이션으로 픽셀 fog를 유효하게 하려면 , 다음의 순서를 실행한다.

C++ 어플리케이션으로 픽셀 fog를 유효하게 하려면

  1. D3DRS_FOGENABLE 렌더링 스테이트를 TRUE 로 설정해, fog 블렌딩을 유효하게 한다.
  2. D3DRS_FOGCOLOR 렌더링 스테이트에서, 목적의 fog 칼라를 설정한다.
  3. D3DRS_FOGTABLEMODE 렌더링 스테이트를 D3DFOGMODE 열거형의 대응하는 멤버로 설정해, 사용하는 fog 공식을 선택한다.
  4. 선택한 fog 모드에 필요한 fog 파라미터를, 관련하는 렌더링 스테이트로 설정한다. 선형 fog의 시작 거리와 종료 거리, 지수 fog의 fog 밀도도 포함한다.

다음의 샘플 코드는, 이러한 순서를 나타내고 있다.

// 간단하게 하기 위해서, 이 예에서는, 호출의 후에
// 에러값을 체크하지 않는다. 실제의 어플리케이션에서는,
// 에러값을 올바르게 체크하는 것.
//
// 이 예에서는, g_pDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
void SetupPixelFog(DWORD Color, DWORD Mode)
{
    float Start = 0.5f,    // 선형 모드용.
          End   = 0.8f,
          Density = 0.66;  // 지수 모드용.

    // fog 블렌딩을 유효하게 한다.
    g_pDevice->SetRenderState(D3DRS_FOGENABLE, TRUE);

    // fog 칼라를 설정한다.
    g_pDevice->SetRenderState(D3DRS_FOGCOLOR, Color);

    // fog 파라미터를 설정한다.
    if(D3DFOG_LINEAR == Mode)
    {
        g_pDevice->SetRenderState(D3DRS_FOGTABLEMODE, Mode);
        g_pDevice->SetRenderState(D3DRS_FOGSTART, *(DWORD *)(&Start));
        g_pDevice->SetRenderState(D3DRS_FOGEND,   *(DWORD *)(&End));
    }
    else
    {
        g_pDevice->SetRenderState(D3DRS_FOGTABLEMODE, Mode);
        g_pDevice->SetRenderState(D3DRS_FOGDENSITY, *(DWORD *)(&Density));
    }

}

주 IDirect3DDevice8::SetRenderState 메소드는, 제 2 파라미터에 DWORD 값만을 받지만, 부동 소수점의 fog 파라미터가 요구되는 일도 있다. 위에의예에서는 부동 소수점의 값을 SetRenderState 에 건네주기 위해서(때문에), 데이터를 평행이동 하는 것이 아니라, 부동 소수점 변수의 주소를 DWORD 포인터에 캐스트 해, 다음에 그것을 참조하고 있다.


버텍스 fog

여기에서는, 버텍스 fog를 소개해, 버텍스 fog의 Microsoft® Direct3D® 어플리케이션에서의 사용 방법에 대해 자세하게 설명한다. 설명하는 주제는, 다음과 같다.

  • 버텍스 fog에 대해
  • 범위 베이스의 fog
  • 버텍스 fog의 사용법


버텍스 fog에 대해

시스템은 버텍스 fog를 실행 하면 와, 다각형의 각 버텍스에 fog 계산을 적용해, 다음에, rasterize때, 다각형의 면에 결과를 보간 한다. 버텍스 fog의 이펙트는, Microsoft® Direct3D® 의 라이팅 & 트랜스 폼 엔진에 의해 계산된다. 상세한 것에 대하여는, 「fog 파라미터」를 참조할것.

어플리케이션으로 Direct3D 를 사용하지 않고 트랜스 폼 & 라이팅을 실행하는 경우는, 어플리케이션으로 독자적으로 fog 계산을 실시할 필요가 있다. 이 경우, 어플리케이션은 fog 계수를 계산해, 각 버텍스의 스펙큐러색의 알파 성분에 둔다. 공식으로는, 범위 베이스의 공식, 체적을 이용하는 공식적인 , 어떠한 것에서도 사용할 수 있다. Direct3D 는 주어진 fog 계수를 사용해, 각 다각형의 면을 보간 한다. Direct3D 의 트랜스 폼 & 라이팅을 사용하지 않는 어플리케이션에서는, 버텍스 fog 파라미터를 설정할 필요는 없지만, fog를 유효하게 해, 관련하는 렌더링 스테이트에 의해 fog 칼라를 설정해야 한다. 상세한 것에 대하여는, 「fog 파라미터」를 참조할것.

주 어플리케이션으로 독자적인 트랜스 폼 & 라이팅을 실행하는 경우는, 그것 독자적인 fog 계산을 실행할 필요가 있다. 따라서, 그러한 어플리케이션에서는, 「fog 블렌딩」 및 「fog 칼라」로 설명하도록(듯이), fog 블렌딩을 유효하게 해, 관련하는 렌더링 스테이트에 의해 fog 칼라를 설정하는 것만으로 좋다.


범위 베이스의 fog

주 Microsoft® Direct3D® 에서는, Direct3D 의 트랜스 폼 & 라이팅 엔진으로 버텍스 fog를 사용할때만, 범위 베이스의 fog의 계산을 실행한다. 이것은, 픽셀 fog는 디바이스 드라이버에 이행 되어 현재로서는, 픽셀 단위의 범위 베이스의 fog를 지원 하는 하드웨어는 존재하지 않기 때문이다. 어플리케이션으로 독자적인 트랜스 폼 & 라이팅을 실행하는 경우는, 범위 베이스의 계산이나 그 외의 계산에 의한 독자적인 fog 계산을 실시할 필요가 있다.

fog를 사용 하면, 오브젝트가 fog 칼라와 직감적이 아닌 방법으로 브렌드 되는 부자연스러운 그래픽스 효과가 생기는 일이 있다. 예를 들어, 2 개의 오브젝트가 보이고 있어, 한편은 fog의 영향을 받을 정도로에 멀리 있어, 한편은 영향을 받지 않을 정도 에 근처에 있다고 하는 장면을 상정한다. 표시 영역이 같은 장소에서 회전했을 경우, 오브젝트가 정지하고 있었다고 해도, 나타나는 fog 이펙트는 변화하는 일이 있다. 다음의 그림은, 이러한 상황을 내려다 본 스테이트를 나타내고 있다.

범위 베이스의 fog는, fog 이펙트를 보다 정확하게 결정하는 방법이다. 범위 베이스의 fog에서는, Direct3D 는 시점으로부터 버텍스까지의 실제의 거리를 fog의 계산에 사용한다. 장면의 범위내에서의 버텍스의 깊이는 아니고 2 점간의 거리의 증가에 따라 fog의 이펙트가 증가되기 (위해)때문에, 부자연스러운 회전 효과가 회피된다.

현재의 디바이스가 범위 베이스의 fog를 지원 하고 있는 경우,IDirect3DDevice8::GetDeviceCaps 메소드를 호출했을 때에, 디바이스는 D3DCAPS8 구조체의 RasterCaps 멤버에 D3DPRASTERCAPS_FOGRANGE 능력 플래그를 설정한다. 범위 베이스의 fog를 유효하게 하려면 ,D3DRS_RANGEFOGENABLE 렌더링 스테이트를 TRUE 로 설정한다.

범위 베이스의 fog는, Direct3D 에 의해, 트랜스 폼 & 라이팅의 사이에 계산된다. 「버텍스 fog에 대하며」로 설명한 것처럼,Direct3D 트랜스 폼 & 라이팅 엔진을 사용하지 않는 어플리케이션은, 독자적으로 버텍스 fog의 계산도 실시하지 않으면 안 된다. 이 경우, 범위 베이스의 fog 계수를, 각 버텍스의 스펙큐러 성분의 알파 성분으로 설정한다.


버텍스 fog의 사용법

어플리케이션으로 버텍스 fog를 유효하게 하려면 , 다음의 순서를 실행한다.

C++ 어플리케이션으로 버텍스 fog를 유효하게 하려면

  1. D3DRS_FOGENABLE 를 TRUE 로 설정해, fog 블렌딩을 유효하게 한다.
  2. D3DRS_FOGCOLOR 렌더링 스테이트에서, 필요한 fog 칼라를 설정한다.
  3. D3DRS_FOGVERTEXMODE 렌더링 스테이트를 D3DFOGMODE 열거형의 멤버로 설정해, 목적의 fog 공식을 선택한다.
  4. 선택한 fog 공식에서 필요한 fog 파라미터를 렌더링 스테이트로 설정한다.

다음의 C++ 샘플 코드는, 이러한 순서를 나타내고 있다.

// 간단하게 하기 위해서, 이 예에서는, 호출의 후에
// 에러값을 체크하지 않는다. 실제의 어플리케이션에서는,
// 에러값을 올바르게 체크하는 것.
//
// 이 예에서는, g_pDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
void SetupVertexFog(DWORD Color, DWORD Mode, BOOL UseRange, FLOAT Density)
{
    float Start = 0.5f,    // 선형 fog 거리.
          End   = 0.8f;

    // fog 블렌딩을 유효하게 한다.
    g_pDevice->SetRenderState(D3DRS_FOGENABLE, TRUE);

    // fog 칼라를 설정한다.
    g_pDevice->SetRenderState(D3DRS_FOGCOLOR, Color);

    // fog 파라미터를 설정한다.
    if(D3DFOG_LINEAR == Mode)
    {
        g_pDevice->SetRenderState(D3DRS_FOGVERTEXMODE, Mode);
        g_pDevice->SetRenderState(D3DRS_FOGSTART, *(DWORD *)(&Start));
        g_pDevice->SetRenderState(D3DRS_FOGEND,   *(DWORD *)(&End));
    }
    else
    {
        g_pDevice->SetRenderState(D3DRS_FOGVERTEXMODE, Mode);
        g_pDevice->SetRenderState(D3DRS_FOGDENSITY, *(DWORD *)(&Density));
    }

    // 필요에 따라서, 범위 베이스의 fog를 유효하게 한다
    // (버텍스 fog에서만 지원 된다). 이 예에서는, 드라이버가 D3DPRASTERCAPS_FOGRANGE 능력을 공개하는 경우에게만,
    // UseRange 는
    // 제로 이외의 값으로 설정된다고 한다.
    // 주  이 (분)편이, 범위에 근거하지 않는 fog보다
    //       약간 퍼포먼스가 좋다.
    if(UseRange)
        g_pDevice->SetRenderState(
                       D3DRS_RANGEFOGENABLE,
                       TRUE);
}

IDirect3DDevice8::SetRenderState 메소드는, 제 2 파라미터에 DWORD 값만을 받지만, 부동 소수점의 fog 파라미터가 요구되는 일도 있다. 이 예에서는, 부동 소수점의 값을 데이터의 평행이동없이 메소드에 건네주기 위해서(때문에), 부동 소수점 변수의 주소를 DWORD 포인터로서 캐스트 해, 다음에 그것을 참조로부터 해제하고 있다.


지오메트리 블렌딩

여기에서는, 지오메트리 블렌딩에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 지오메트리 블렌딩에 대해
  • 블렌딩 트랜스 폼과 렌더링 스테이트
  • 블렌딩의 중량감
  • 지오메트리 블렌딩의 사용법


지오메트리 블렌딩에 대해

Microsoft® Direct3D® 에서는, Joint부가 매끄럽게 브렌드 되고 있는 부분화된 다각형 오브젝트, 특히 캐릭터를 렌더링 하는 것으로, 장면을 한층 리얼하게 표현할 수가 있다. 이러한 이펙트를 일반적으로스키닝라고 부르는. 이 이펙트는, 추가의 월드 트랜스 폼 행렬을 버텍스의 단일 세트에 적용해, 그 결과 생성되는 복수의 트랜스 폼 후의 버텍스간에 선형 브렌드를 실행해 렌더링용의 지오메트리의 단일 세트를 생성하는 것으로 실현된다. 다음의 바나나의 일러스트는, 이 예를 나타내고 있다.

이 화면은, 지오메트리 블렌딩의 처리가 어떠한 것인지를 나타내고 있다. 1 회의 렌더링의 호출로, 시스템은 바나나의 버텍스를 취득해, 이 버텍스에 대해서 회전하지 않는 트랜스 폼과 단순한 회전의 트랜스 폼을 1 회씩 실행해, 그 결과 구부러진 바나나를 생성한다. 시스템은, 라이팅이 유효한 경우에, 버텍스 법선 뿐만이 아니라 버텍스 위치 좌표도 브렌드 한다. 어플리케이션은 2 개의 블렌딩 방법으로 한정되는 것은 아니다. Direct3D 는, 최대 4 개의 월드 행렬 (표준 월드 행렬의 D3DTS_WORLD 등) 간에서 지오메트리를 브렌드 할 수 있다.

주 라이팅이 유효하게 되어 있는 경우, 버텍스 법선이, 대응하는 월드 뷰 행렬의 역행열에 의해 트랜스 폼 된다. 이 때, 중요는, 버텍스 위치 좌표의 계산의 경우와 같게 행해진다. D3DRS_NORMALIZENORMALS 렌더링 스테이트가 TRUE 로 설정되어 있는 경우는, 결과의 법선 벡터가 시스템에 의해 정규화된다.

가동 결합부가 있는 모델의 경우, 지오메트리 블렌딩을 사용하지 않고 부분 마다 렌더링 되는 것이 많다. 예를 들어, 인간의 팔의 3D 모델을 생각한다. 가장 단순하게 해, 팔에는 신체로 연결되는 상완과 손으로 연결되는 팔뚝이 있다. 2 개의 팔은 함께 팔꿈치로 연결되어 있어 팔뚝은 이 정도치좌표로 회전한다. 어플리케이션으로 팔을 렌더링 하는 경우, 상완과 팔뚝의 버텍스 데이터는 보관 유지되어 각각 개별의 월드 트랜스 폼 행렬이 적용된다. 다음의 샘플 코드는, 이것을 나타내고 있다.

typedef struct _Arm {
    VERTEX upper_arm_verts[200];
    D3DMATRIX matWorld_Upper;

    VERTEX lower_arm_verts[200];
    D3DMATRIX matWorld_Lower;
} ARM, *LPARM;

ARM MyArm; // 이것은 초기화할 필요가 있다.

팔을 렌더링 하려면 , 다음의 코드로 가리키도록(듯이), 렌더링의 호출을 2 회 실행한다.

// 상완을 렌더링 한다.
d3dDevice->SetTransform( D3DTS_WORLD, &MyArm.matWorld_Upper );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, numFaces );

// 팔뚝을 렌더링 해, 팔을 관절로 잇는 월드 행렬을 갱신한다.
// 팔꿈치로 pi/4 라디안 (45о) 두개회전하도록(듯이) 한다.
MyArm.matWorld_Lower = RotateMyArm(MyArm.matWorld, pi/4);
d3dDevice->SetTransform( D3DTS_WORLD, &MyArm.matWorld_Lower );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, numFaces );

다음의 화면은, 이 테크닉을 사용해 바나나를 수정한 것이다.

브렌드 된 지오메트리와 브렌드되어 있지 않은 지오메트리의 차이는 분명하다. 이 예에서도 그 차이는 분명히 안다. 실제의 어플리케이션에서는, 각 모델을 Joint 해도, 그만큼 Joint부가 눈에 띌 것은 없다. 그러나, Joint부가 보기 흉하게 표시되는 일도 있다. 이것은, 모데르데자이나에 있어서는 항상 과제이다.

Direct3D 의 지오메트리 블렌딩에서는, 종래의 세그먼트(segment) 모델 시나리오를 사용할 수도 있다. 그러나, 분할되고 있는 개개의 오브젝트의 표시 품질을 올리려면 , 렌더링시의 블렌딩 계산이 필요하다. 이러한 추가 처리에 의한 영향을 최소한으로 억제하기 위해서(때문에), Direct3D 지오메트리 파이프라인은, 가능한 한 오버헤드를 발생시키지 않고 지오메트리를 브렌드 할 수 있도록(듯이) 최적화된다. 어플리케이션에서는 Direct3D 의 지오메트리 블렌딩 서비스를 유효하게 사용하는 것으로, 퍼포먼스에의 심각한 영향을 피하면서, 캐릭터를 보다 진짜인것 같게 표현할 수가 있다.


블렌딩 트랜스 폼과 렌더링 스테이트

IDirect3DDevice8::SetTransform 메소드는,D3DTS_WORLD 매크로 및 D3DTS_WORLDn 매크로를 인식하지만, 이러한 매크로는 D3DTS_WORLDMATRIX 매크로에 의해 정의되는 값에 대응한다. 이러한 매크로를 사용해, 지오메트리가 브렌드 될 때의 행렬을 식별한다.

D3DRENDERSTATETYPE 열거형에는, 지오메트리 블렌딩을 유효하게 해 제어하는 D3DRS_VERTEXBLEND 렌더링 스테이트가 포함된다. 이 렌더링 스테이트의 유효값은,D3DVERTEXBLENDFLAGS 열거형에 의해 정의된다. 지오메트리브렌딘이 유효하게 되어 있는 경우, 버텍스 포맷에는 블렌딩의 적절한 가중값이 포함되지 않으면 안 된다.

참조

블렌딩 행렬의 설정,지오메트리 블렌딩을 유효하게 하는,블렌딩의 중량감


블렌딩의 중량감

블렌딩의 중량감 (베타의 중량감이라고 부를 때도 있다)은, 지정된 월드 행렬에 의해 버텍스가 받는 영향의 범위를 제어한다. 블렌딩의 중량감이란, 0.0 ~ 1.0 의 범위의 부동 소수점값이며, 버텍스 포맷으로 encode 된다. 값이 0.0 의 경우, 버텍스는 그 행렬로 브렌드 되지 않는다. 값이 1.0 의 경우, 버텍스는 행렬의 영향을 모두 받는다.

지오메트리 블렌딩의 중량감은, 버텍스 포맷으로 encode 되어 「버텍스 포맷에 대하며」로 설명하도록(듯이), 각 버텍스의 위치 좌표의 바로 후에 나타난다. Microsoft® Direct3D® 렌더링 메소드로 지정하는 버텍스 기술에 D3DFVF_XYZB1 ~ D3DFVF_XYZB5 의유연한 버텍스 포맷 플래그의 어느쪽이든을 포함하는 것으로, 버텍스 포맷에 블렌딩의 중량감을 지정한다.

중요 된 브렌드 행렬간으로, 시스템에 의해 선형 브렌드가 실행된다. 다음에, 정식적 블렌딩 공식을 나타낸다.

앞에서 본 공식에서는,vBlend 는 출력 버텍스이며, v 요소는 적용 후의 월드 행렬 (D3DTS_WORLDn )에 의해 생성되는 버텍스이다. W 요소는, 버텍스 포맷내의 대응하는 중량감이다. n 개의 행렬간에 브렌드 되는 버텍스는,n–1 개의 블렌딩의 중량감을 가질 수가 있다 (마지막 블렌딩 행렬을 제외해, 각 블렌딩 행렬에 1 개의 중량감). 마지막 월드 행렬의 중량감은, 이 공식에서는 Σ 으로 나타내도록(듯이), 중량감의 합계가 1.0 이 되도록(듯이) 시스템에 의해 자동적으로 생성된다. 이 공식은, Direct3D 가 지원 하고 있는 케이스에 맞추어 간략화할 수 있다.

이러한 공식은, 정식적 블렌딩 공식을, 2, 3, 및 4 개의 브렌드 행렬의 케이스에 맞추어 간략화한 것이다.

주 Direct3D 에서는, 최대 5 개의 블렌딩의 중량감을 가지는 버텍스를 정의하는 유연한 버텍스 포맷 기술자를 포함할 수가 있지만, 이 릴리스의 Microsoft DirectX® 에서는 3 개까지 밖에 사용할 수 없다.


지오메트리 블렌딩의 사용법

여기에서는, 어플리케이션에서의 지오메트리 블렌딩의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 블렌딩용의 버텍스의 정의
  • 블렌딩 행렬의 설정
  • 지오메트리 블렌딩을 유효하게 한다


블렌딩용의 버텍스의 정의

다음의 유저 정의 구조체는, 2 개의 행렬간에 브렌드 하는 버텍스에 사용할 수 있다.

//
// 이 버텍스의 유연한 버텍스 포맷 기술자는 다음과 같다.
//
//     FVF = D3DFVF_XYZB1 | D3DFVF_NORMAL | D3DFVF_TEX1;
//
struct D3DBLENDVERTEX {
    D3DVECTOR v;
    FLOAT     blend;
    D3DVECTOR n;
    FLOAT     tu, tv;
};

「블렌딩의 중량감」으로 설명하도록(듯이), 브렌드의 중량감은 유연한 버텍스 포맷내의 위치 좌표 및 RHW 데이터의 뒤로, 한편 버텍스 법선의 전에 없으면 안 된다.

전의 버텍스 포맷에는, 블렌딩의 중량감이 1 개 밖에 없는 것에 주의한다. 이것은,D3DTS_WORLDMATRIX (0) 및 D3DTS_WORLDMATRIX(1) 트랜스 폼 스테이트에서 정의되는 2 개의 월드 행렬이 있기 때문에 있다. 이것들 2 개의 행렬간에 각각의 버텍스가, 1 개의 중량감을 사용해 브렌드 된다. 행렬이 3 개 있는 경우, 중량감은 2 개 필요하다.

주 스킨의 중량감은 간단하게 정의할 수 있다. Joint 하는 오브젝트간의 거리의 선형 함수를 사용 하면이야 겉껍데기, 보다 매끄러운 S 자 함수를 사용 하면 한층 더 좋다. 스킨의 중량감 분포 함수를 선택 하면, 필요에 따라서 Joint부에 선명 없음원을 붙일 수가 있다 (짧은 거리간에 스킨의 중량감의 변화를 크게 한다).

참조

버텍스 포맷에 대해,유연한 버텍스 포맷 플래그


블렌딩 행렬의 설정

IDirect3DDevice8::SetTransform 메소드를 호출해, 시스템이 브렌드 할 때의 트랜스 폼 행렬을 설정한다. 제 1 파라미터에 D3DTS_WORLDMATRIX 매크로로 정의되는 값을 설정해, 제 2 파라미터에는 설정하는 행렬의 주소를 설정한다.

다음의 C++ 코드예는, 2 개의 월드 행렬을 설정한다. 이러한 행렬간에 지오메트리를 브렌드 해 Joint 된 팔의 일루젼을 생성 한다.

// 이 예에서는, 변수 d3dDevice 는
// 초기화 끝난 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
float     BendAngle = 3.1415926f / 4.0f; // 45о
D3DMATRIX matUpperArm, matLowerArm;

// 상완은 움직이지 않는다. 단위행렬을 사용한다.
D3DXMatrixIdentity( matUpperArm );
d3dDevice->SetTransform( D3DTS_WORLDMATRIX(0), &matUpperArm );

// 팔뚝은 x 축을 중심으로 회전한다. 이것은 상완에 연결한다.
D3DXMatrixRotationX( matLowerArm, -BendAngle );
d3dDevice->SetTransform( D3DTS_WORLDMATRIX(1), &matLowerArm );

블렌딩 행렬을 설정해도, 시스템은 그 행렬을 다음에 사용할 수 있도록(듯이) 단지 캐쉬하는 것만으로, 버텍스의 브렌드를 시작 하는 것은 아니다. 상세한 것에 대하여는, 「지오메트리 블렌딩을 유효하게 한다」를 참조할것.


지오메트리 블렌딩을 유효하게 한다

디폴트에서는, 지오메트리 블렌딩은 무효이다. 지오메트리 블렌딩을 유효하게 하려면 ,IDirect3DDevice8::SetRenderState 메소드를 호출해 D3DRS_VERTEXBLEND 렌더링 스테이트를 D3DVERTEXBLENDFLAGS 열거형으로부터의 값으로 설정한다. 다음의 코드는, 2 개의 월드 행렬간에서 브렌드하기 위한 , 렌더링 스테이트의 설정을 나타내고 있다.

d3dDevice->SetRenderState( D3DRS_VERTEXBLEND, D3DVBF_1WEIGHTS );

D3DRS_VERTEXBLEND 가 D3DVBF_DISABLE 이외의 값으로 설정되어 있는 경우는, 버텍스 포맷에 적절한 개수의 블렌딩의 중량감이 포함되어 있다고 보여진다. 적절한 버텍스 포맷을 생성 하는 것, 및 그 포맷의 올바른 기술을 Microsoft® Direct3D® 렌더링 메소드에 제공하는 것은 개발자의 책임이다. 상세한 것에 대하여는, 「블렌딩용의 버텍스의 정의」를 참조할것.

지오메트리 블렌딩이 유효하게 되어 있는 경우, DrawPrimitive 렌더링 메소드로 렌더링 되는 모든 오브젝트에 대해서 지오메트리 블렌딩이 실행된다.


인덱스 첨부 버텍스 블렌딩

여기에서는, Microsoft® Direct3D® 고정 기능 버텍스 파이프라인의 인덱스 첨부 버텍스 블렌딩에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 인덱스 첨부 버텍스 블렌딩에 대해
  • 인덱스 첨부 버텍스 블렌딩 트랜스 폼과 렌더링 스테이트
  • 인덱스 첨부 버텍스 블렌딩의 사용법


인덱스 첨부 버텍스 블렌딩에 대해

인덱스 첨부 버텍스 블렌딩은, Microsoft® Direct3D® 의 버텍스 블렌딩 지원을 확장해, 행렬을 블렌딩에 사용할 수 있도록(듯이) 한 것이다. 이러한 행렬은, 행렬의 인덱스를 사용해 나타난다. 이러한 인덱스는, 버텍스 마다 제공되어 최대 256 개의 행렬의 팔레트를 참조한다. 각 인덱스는 8 비트로, 각 버텍스에는 최대 4 개(살)까지의 인덱스를 갖게할 수가 있기 (위해)때문에, 1 개의 버텍스에 대해 4 개의 행렬을 브렌드 할 수가 있다. 인덱스는,DWORD 에 팩 된다. 인덱스는 버텍스 마다 지정되므로, 최대 12 개의 행렬이 단일의 삼각형에 영향을 줄 수가 있어 팔레트내의 임의의 행렬이 1 개의 드로잉(Drawing) 호출의 버텍스에 영향을 줄 수가 있다. 이 어프로치에는, 다음과 같은 장점이 있다.

  • 단일의 삼각형에 대해서, 보다 많은 행렬이 영향을 주도록(듯이) 할 수가 있다.
  • 보다 많은 브렌드 된 삼각형을, 동일한 드로잉(Drawing) 호출에 건네줄 수가 있다.
  • 버텍스 블렌딩을 삼각형 인덱스와는 독립한 것으로 한다. 이 때문에, 프로그래시브 메쉬를 버텍스 블렌딩과 함께 동작시킬 수가 있다.

이 방법의 약점은, 버텍스 처리전에 테셀레이션을 하면(자), 곡면 표면 프리미티브를 처리하지 않는 것이다.

다음의 그림은, 버텍스가 4 개의 행렬에 의해 영향을 받는 모습을 나타내고 있다. 각 버텍스는 최대 4 개(살)까지의 인덱스를 가질 수가 있으므로, 버텍스 마다 4 개의 행렬을 브렌드 할 수가 있다. 다음의 그림에서는, 0, 2, 5, 및 6 으로 인덱스를 붙일 수 있었던 행렬을 사용한다.

다음의 그림은, 1 개의 삼각형이 최고 12 의 행렬에 의해 영향을 받는 모습을 나타내고 있다. 버텍스 마다 지정되는 인덱스를 사용해, 최대 12 개의 행렬이 단일의 삼각형에 영향을 줄 수가 있다.

다음의 공식은, 행렬이 버텍스에게 주는 효과에 대한 일반적인 경우를 결정한다.

Vmodel 는, 입력 모델 공간에서의 버텍스의 위치 좌표이다. Index0..Index3 는, DWORD 에 팩 된 버텍스마다의 행렬의 인덱스이다. M[] 는, 인덱스를 붙이는 월드 행렬의 배열로,b0..b2 는 브렌드 웨이트이다. Vworld 는, 출력 월드 공간에서의 버텍스의 위치 좌표이다.


인덱스 첨부 버텍스 블렌딩 트랜스 폼과 렌더링 스테이트

256 ~ 511 의 범위의 트랜스 폼 스테이트는, 8 비트의 인덱스를 사용해 인덱스 붙이고 할 수 있는 최대 256 개의 행렬을 저장 하기 위해서 확보되고 있다. D3DTS_WORLDMATRIX 매크로를 사용해, 인덱스 0 ~ 255 를 대응하는 트랜스 폼 스테이트에 매핑 한다. 다음의 코드는,IDirect3DDevice8::SetTransform 메소드를 사용해 트랜스 폼 스테이트 번호 256 의 행렬을 단위행렬로 설정하는 방법을 나타내고 있다.

D3DMATRIX matBlend1;

D3DXMatrixIdentity( &matBlend1 );
d3dDevice->SetTransform( D3DTS_WORLDMATRIX(0), &matBlend );

인덱스 첨부 버텍스 블렌딩의 유효와 무효를 바꾸려면 ,D3DRS_INDEXEDVERTEXBLENDENABLE 렌더링 스테이트를 TRUE 로 설정한다. 이 렌더링 스테이트가 유효하게 되어 있는 경우는, 버텍스 마다 팩 DWORD 로 행렬 인덱스를 건네주지 않으면 안 된다. 이 렌더링 스테이트를 무효로 해, 버텍스 블렌딩을 유효하게 하는 것은, 모든 버텍스에 대해 행렬 인덱스 0, 1, 2, 3 을 지정하는 것에 동일하다. 이하의 코드는,IDirect3DDevice8::SetRenderState 메소드를 사용해, 인덱스 첨부 버텍스 블렌딩을 유효하게 한다.

d3dDevice->SetRenderState( D3DRS_INDEXEDVERTEXBLENDENABLE, TRUE );

버텍스 블렌딩의 유효와 무효를 바꾸려면 ,D3DRS_VERTEXBLEND 렌더링 스테이트를 D3DVERTEXBLENDFLAGS 열거형의 D3DRS_DISABLE 이외의 값으로 설정한다. 이 렌더링 스테이트가 D3DRS_DISABLE 로 설정되어 있지 않은 경우는, 각 버텍스에 필요한 가중값을 건네주지 않으면 안 된다. 다음의 코드는,SetRenderState 를 사용해, 각 버텍스 대해 3 개의 중량감으로 버텍스 블렌딩을 유효하게 한다.

d3dDevice->SetRenderState( D3DRS_VERTEXBLEND, D3DVBF_3WEIGHTS );


인덱스 첨부 버텍스 블렌딩의 사용법

여기에서는, 이하의 토픽에 대해 설명한다.

  • 인덱스 첨부 버텍스 블렌딩의 지원의 판정
  • Direct3D 에 대한 행렬 인덱스의 수수


인덱스 첨부 버텍스 블렌딩의 지원의 판정

인덱스 첨부 버텍스 블렌딩 행렬의 최대 사이즈를 판정하려면 ,D3DCAPS8 구조체의 MaxVertexBlendMatrix 멤버를 조사한다. 다음의 코드는,IDirect3DDevice8::GetDeviceCaps 메소드를 사용해, 이 사이즈를 취득한다.

D3DCAPS8 d3dCaps;

d3dDevice->GetDeviceCaps( &d3dCaps );
IndexedMatrixMaxSize = d3dCaps.MaxVertexBlendMatrixIndex;

MaxVertexBlendMatrix 로 설정된 값이 0 의 경우, 디바이스는 인덱스 첨부의 행렬을 지원 하고 있지 않다.

주 소프트웨어 버텍스 처리가 사용되고 있는 경우는, 법선 블렌딩이 있어도 없어도, 256 개의 행렬을 인덱스 첨부 버텍스 블렌딩에 사용할 수 있다.


Direct3D 에 대한 행렬 인덱스의 수수

월드 행렬 인덱스는, 종래의 버텍스 쉐이더 (FVF)나 선언의 어느 쪽인지를 사용해, Microsoft® Direct3D® 에 건네줄 수가 있다.

다음의 코드는, 종래의 버텍스 쉐이더를 사용하는 방법을 나타내고 있다.

struct VERTEX
{
    float x, y, z;
    float weight;
    DWORD matrixIndices;
    float normal[3];
};

#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZB2 | D3DFVF_LASTBETA_UBYTE4 |
                             D3DFVF_NORMAL);

종래의 버텍스 쉐이더를 사용하는 경우, 행렬 인덱스는 D3DFVF_XYZBn 플래그를 사용해 버텍스 위치 좌표와 함께 건네받는다. 행렬 인덱스는 DWORD 내의 바이트로서 건네받아 마지막 버텍스 가중의 직후에 존재해야 한다. 버텍스 가중도 D3DFVF_XYZBn 를 사용해 건네받는다. 팩 DWORD 는, index3, index2, index1, 및 index0 를 보관 유지해, index0 는 DWORD 의 최하정도 바이트에 있다. 사용되는 월드 행렬 인덱스의 수는,D3DRS_VERTEXBLEND 에 의해 정의되는 블렌딩에 사용되는 행렬의 수에게 건네지는 수치에 동일하다.

선언을 사용하는 경우는,D3DVSDE_BLENDINDICES 가 행렬 인덱스를 취득하는 입력 버텍스 레지스터를 정의한다. 행렬 인덱스는,D3DVSDT_PACKEDBYTE 로서 건네줄 필요가 있다.

다음의 코드는, 선언의 사용 방법을 나타내고 있다. 고정 기능에 의한 버텍스 쉐이더를 사용하지 않는 한, 컴퍼넌트의 순서는 완전히 중요하지 않는 점에 주의 해야 한다.

struct VERTEX
{
    float x, y, z;
    float weight;
    DWORD matrixIndices;
    float normal[3];
}

DWORD decl[] =
{
    D3DVSD_STREAM(0),
    D3DVSD_REG(D3DVSDE_POSITION, D3DVSDT_FLOAT3),
    D3DVSD_REG(D3DVSDE_BLENDWEIGHT, D3DVSDT_FLOAT1),
    D3DVSD_REG(D3DVSDE_BLENDINDICES, D3DVSDT_UBYTE),
    D3DVSD_REG(D3DVSDE_NORMAL, D3DVSDT_FLOAT3),
    D3DVSD_END()
};


스텐실 버퍼 기술

어플리케이션으로 스텐실 버퍼를 사용해, 화면의 픽셀을 마스크 한다. 이 마스크는, 픽셀을 드로잉(Drawing) 할지 어떨지를 제어한다. 스텐실 버퍼의 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.

Microsoft® Direct3D® 어플리케이션은, 스텐실 버퍼를 사용해 광범위한 특수 효과를 낳을 수가 있다. 여기에서는, 빈번하게 사용되는 이하의 이펙트에 대해 설명한다.

  • 디조르브, 페이드, 및 와이프
  • 십-링
  • 합성
  • 아우트라인과 실루엣


디조르브, 페이드, 및 와이프

디조르브, 와이프, 및 페이드등의 영화나 비디오로 자주(잘) 사용되는 특수 효과를 어플리케이션으로 이용하는 것이 증가하고 있다.

디조르브에서는, 프레임이 서서히 바뀌는 것에 의해 있는 화면이 다른 화면에 순조롭게 이행 한다. Microsoft® Direct3D® 에서는, 멀티 텍스쳐 블렌딩을 사용하는 방법으로 이 이펙트를 생성 할 수 있지만, 디조르브에 스텐실 버퍼를 사용하는 어플리케이션은, 디조르브의 실행중에 텍스쳐 블렌딩 기능을 다른 이펙트에 이용할 수 있다.

디조르브를 실행 하면 와, 어플리케이션은 2 개가 다른 화면을 렌더링 해야 한다. 어플리케이션은 스텐실 버퍼를 사용해, 렌더링 타겟 표면에 각 화면의 어느 픽셀을 드로잉(Drawing) 하는지를 제어한다. 일련의 스텐실 마스크를 정의해, 연속하는 프레임의 스텐실 버퍼에 이러한 마스크를 카피할 수 있다. 다른 방법으로서 최초의 프레임용의 기본 스텐실 마스크를 정의해, 이 마스크를 인크리먼트(increment) 해 변경할 수도 있다.

디조르브를 시작 한 시점에서, 어플리케이션은, 시작시의 화면의 픽셀의 대부분이 스텐실 테스트를 패스하도록(듯이) 스텐실 함수와 스텐실 마스크를 설정한다. 마지막 화면의 대부분의 픽셀은, 스텐실 테스트에 실패하게 된다. 프레임이 계속되는 것에 따라, 최초의 화면의 픽셀로 테스트에 패스하는 픽셀이 서서히 적게 되도록(듯이), 스텐실 마스크를 갱신한다. 프레임이 계속되는 것에 따라, 마지막 화면의 픽셀로 테스트에 실패하는 픽셀이 서서히 적게 된다. 이와 같이, 임의의 디조르브파탄을 사용해 디조르브를 실행할 수 있다.

용명 또는 용암은, 디조르브의 특수한 케이스이다. 용명 하면나무는, 스텐실 버퍼를 사용해, 흑색 또는 백색의 화면으로부터 3D 신의 렌더링에 디조르브 한다. 용암은 이것과 역으로, 3D 신의 렌더링으로부터 시작되어, 흑색 또는 백색의 화면에 디조르브 한다. 페이드에는, 어떠한 패턴에서도 사용할 수 있다.

Direct3D 어플리케이션은, 와이프에도 동일한 기술을 사용한다. 예를 들어, 왼쪽에서 오른쪽에의 와이프를 실행하는 경우, 마지막 화면이 최초의 화면 위에 서서히 슬라이드하도록(듯이) 왼쪽에서 오른쪽으로 이동한다. 디조르브의 경우와 같이, 연속 프레임의 스텐실 버퍼에 로드하는 일련의 스텐실 마스크를 정의하는지, 최초의 스텐실 마스크를 연속적으로 수정할 필요가 있다. 이 스텐실 마스크는, 최초의 화면의 픽셀의 기입을 무효로 해, 마지막 화면의 픽셀의 기입을 유효하게 하기 위해서 사용한다.

와이프의 순서와는 역의 순서로 마지막 화면의 픽셀을 읽어내지 않으면 안 된다고 하는 점으로써, 와이프는 디조르브보다 조금 복잡하다. 즉, 와이프가 왼쪽에서 오른쪽으로 이동하는 경우, 어플리케이션은 마지막 화면의 픽셀을 오른쪽에서 왼쪽으로 읽어내지 않으면 안 된다.


십-링

Microsoft® Direct3D® 어플리케이션은, 십-링 기술을 사용해, 특정의 프리미티브 화면의 어느 픽셀을 렌더링 타겟 표면에 드로잉(Drawing) 하는지를 제어한다. 어플리케이션은, 디칼을 프리미티브의 화면에 적용해, 동일 평면상의 다각형이 올바르고 렌더링 되도록(듯이) 한다.

예를 들어, 타이어의 자취와 황색의 선을 도로에 적용 하면 와, 이 자취는 직접 도로 위에 표시해야 한다. 그러나, 이 자취와 도로의 z 값은 동일하다. 따라서, 깊이 버퍼에서는, 양자를 분명히 구별할 수 없다. 배후의 프리미티브의 픽셀이 전면의 프리미티브상에 렌더링 되거나 그 역의 렌더링을 하는 경우가 있다. 이 결과, 화면은 프레임 마다 흔들린다. 이 이펙트를Z 화이팅또는후리마링이라고 부른다.

이 문제를 해결하려면 , 스텐실을 사용해, 디칼이 표시되는 배면 프리미티브의 부분을 마스크 한다. z 버퍼링을 오프로 해, 렌더링 타겟 표면의 마스크로 가리고 있는 영역에 전면 프리미티브의 화면을 렌더링 한다.

멀티 텍스쳐 블렌딩을 사용해 이 문제를 해결할 수도 있지만, 이 방법을 사용 하면, 어플리케이션으로 생성할 수 있는 것 외의 특수 효과의 수가 제한된다. 스텐실 버퍼를 사용해 디칼을 적용 하면, 다른 이펙트에 대한 텍스쳐 블렌딩 스테이지의 제한이 해방된다.


합성

어플리케이션으로 스텐실 버퍼를 사용해, 2D 또는 3D 화면을 3D 신에 합성할 수 있다. 스텐실 버퍼의 마스크를 사용해, 렌더링 타겟 표면의 영역을 가림한다. 다음에, 텍스트나 비트 맵등의 저장 2D 정보를 가림 영역에 기입할 수가 있다. 다른 방법으로서 추가 3D 프리미티브를 렌더링 타겟 표면의 스텐실 마스크 된 영역에 렌더링 할 수 있다. 이 경우, 장면 전체를 렌더링 할 수도 있다.

게임에서는, 복수의 3D 신을 합성하는 것이 많다. 예를 들어, 운전 게임에서는 보통 백미러를 표시한다. 백미러에는, 운전자의 배후의 3D 신의 표시가 포함된다. 따라서, 백미러는, 본질적으로는 운전자의 전방의 풍경과 합성된 제 2 의 3D 신이라고 말할 수 있다.


아우트라인과 실루엣

스텐실 버퍼는, 아우트라인이나 실루엣등의 보다 추상적인 이펙트에 사용할 수도 있다.

프로그램으로, 프리미티브와 같은 형상이지만 조금 작은 스텐실 마스크를 프리미티브의 화면에 적용 하면, 화면은 프리미티브의 아우트라인만으로 된다. 다음에 화면의 스텐실 마스크를 한 영역을 균일의 색으로 전부 칠해, 프리미티브가 떠올라 보이도록(듯이) 할 수가 있다.

렌더링 하는 프리미티브와 스텐실 마스크가 같은 사이즈로 같은 형상의 경우, 본래 프리미티브가 존재하는 장소에 구멍이 생긴다. 이 구멍을 검게 전부 칠하면(자), 프리미티브의 실루엣을 생성할 수 있다.


버텍스 트이닝

여기에서는, 복수 스트림을 사용한 버텍스 트이닝에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 버텍스 트이닝에 대해
  • 버텍스 트이닝의 알고리즘
  • 버텍스 트이닝의 사용법


버텍스 트이닝에 대해

버텍스 트이닝은, 2 살의 유저 지정의 위치 좌표간 또는 법선 스트림을 브렌드 하기 위해서 사용된다. 버텍스 트이닝은, 선언에 의해서만 사용할 수 있다. 트이닝을 유효하게 하려면 , D3DRS_VERTEXBLEND 를 D3DVBF_TWEENING 로 설정한다. 가중을 사용한 버텍스 블렌딩과 버텍스 브렌딘그트이닝은, 서로 배타적이다.

C++ 의 「DolphinVS 샘플」은, 버텍스 트이닝에 의한, 돌고래가 수중을 이동하고 있는 것처럼 보이는 애니메이션이다. 이하의 화면은, 2 개(살)이 다른 점에 있어서의 돌고래를 나타내고 있다. 우측의 화면의 돌고래가, 꼬리의 위치가 위에서 아래로 내리고 있어 코도 보다 하향이 되어 있는 점에 주의 해야 한다.

궁bmc dolphin1.gif}�


버텍스 트이닝의 알고리즘

트이닝은, 라이팅이나 클리핑의 전에 행해진다. 최종적인 버텍스의 위치 좌표 (법선)는, 다음과 같이 계산된다.

POSITION = POSITION1 * (1.0 - TWEENFACTOR) + POSITION2 * TWEENFACTOR. 법선의 경우도 마찬가지이다.


버텍스 트이닝의 사용법

설명하는 주제는, 다음과 같다.

  • 버텍스 트이닝의 지원의 판정
  • 버텍스의 선언의 설정
  • 고정 기능에 의한 트이닝
  • 버텍스 쉐이더에 의한 트이닝


버텍스 트이닝의 지원의 판정

Microsoft® Direct3D® 가 버텍스 트이닝을 지원 하고 있을지 어떨지를 조사하려면 ,D3DCAPS8 구조체의 VertexProcessingCaps 멤버의 D3DVTXPCAPS_TWEENING 플래그를 조사한다. 다음의 코드는,IDirect3DDevice8::GetDeviceCaps 메소드를 사용해, 트이닝이 지원 되고 있는지 어떤지를 판정한다.

//
// 이 예에서는, m_d3dDevice 는 IDirect3DDevice8 인터페이스에의
// 유효한 포인터이라고 가정하고 있다.
//

D3DCAPS8 d3dCaps;

m_d3dDevice->GetDeviceCaps( &d3dCaps );
if( 0 ! = d3dCaps.VertexProcessingCaps & D3DVTXPCAPS_TWEENING )
    // 버텍스 트이닝은 지원 되고 있다.


버텍스의 선언의 설정

베크트르트이닝을 사용하려면 , 최초로, 2 번째의 법선 또는 2 번째의 위치 좌표를 사용하는 커스텀 버텍스 타입을 설정해야 한다. 다음의 코드는, 2 번째의 법선과 2 번째의 위치 좌표의 양쪽 모두를 포함한 선언의 예를 나타내고 있다.

struct TEX_VERTEX
{
    D3DVECTOR position;
    D3DVECTOR normal;
    D3DVECTOR position2;
    D3DVECTOR normal2;
};

// 타입이 TEX_VERTEX 의 버텍스 버퍼를 생성 한다.

다음의 순서는, 현재의 선언을 설정하는 것이다. 다음의 샘플 코드는, 이 설정 방법법을 나타내고 있다.

DWORD decl[]
{
    D3DVSD_STREAM(0),
    D3DVSD_REG( D3DVSDE_POSITION, D3DVSDT_FLOAT3 ) // 위치 좌표 1
    D3DVSD_REG( D3DVSDE_NORMAL, D3DVSDT_FLOAT3 )   // 법선 1
    D3DVSD_REG( D3DVSDE_POSITION2, D3DVSDT_FLOAT3) // 위치 좌표 2
    D3DVSD_REG( D3DVSDE_NORMAL2, D3DVSDT_FLOAT3 )  // 법선 2
    D3DVSD_END()
};

커스텀 버텍스 타입과 버텍스 버퍼의 생성의 상세한 것에 대하여는, 「버텍스 버퍼의 생성」을 참조할것.

버텍스 쉐이더의 선언의 생성의 상세한 것에 대하여는, 「버텍스 쉐이더 선언」을 참조할것.

주 버텍스 트이닝이 유효하게 되어 있는 경우, 2 번째의 위치 좌표 또는 2 번째의 법선은 현재의 선언안에 존재해야 한다.


고정 기능에 의한 트이닝

다음의 샘플 코드는, 버텍스 타입과 선언을 설정한 다음에, 고정 기능에 의한 버텍스 트이닝을 실현하는 방법을 나타내고 있다.

//이 예로 사용되는 변수.
DWORD handle;
float TweenFactor = 0.3f;

최초의 순서는, 다음의 코드에 나타내도록(듯이),IDirect3DDevice8::CreateVertexShader 메소드를 사용해 버텍스 쉐이더를 생성 하는 것이다.

m_d3dDevice->CreateVertexShader( decl, NULL, &handle, 0 );

CreateVertexShader 가 받는 제 1 파라미터는, 벡터 쉐이더 선언에의 포인터이다. 이 예에서는, 「버텍스의 선언의 설정」으로 선언한 선언이 사용되고 있다. 제 2 파라미터는, 버텍스 쉐이더 함수의 배열에의 포인터가 된다. 이 예에서는, 버텍스 쉐이더 함수는 사용하지 않기 때문에, 이 파라미터에는 NULL 를 설정한다. 제 3 파라미터는, 돌려주어지는 버텍스를 나타내는 버텍스 쉐이더 핸들에의 포인터가 된다. 제 4 파라미터에는, 버텍스 쉐이더의 사용 컨트롤을 지정한다. D3DUSAGE_SOFTWAREPROCESSING 플래그를 사용해, 버텍스 쉐이더가 소프트웨어 버텍스 처리를 사용할 필요가 있는 것을 지시할 수가 있다. 이 예에서는, 이 파라미터를 제로로 설정해, 버텍스 처리는 하드웨어로 실시할 필요가 있는 것을 지시하고 있다.

다음의 순서는, 다음의 코드에 나타내도록(듯이),IDirect3DDevice8::SetVertexShader 메소드를 호출해, 현재의 버텍스 쉐이더를 설정하는 것이다.

m_d3dDevice->SetVertexShader( handle );

SetVertexShader 는, 버텍스 쉐이더에의 핸들을 받는다. 이 파라미터의 값으로서CreateVertexShader 로부터 돌아가는 핸들 또는 FVF 코드를 사용할 수 있다. 이 예에서는, 마지막 순서로 불려 가는 CreateVertexShader 로부터 돌려주어지는 핸들을 사용한다.

다음의 순서는, 현재의 렌더링 스테이트를 설정해 버텍스 트이닝을 유효하게 해, 트인 계수를 설정해, 스트림 소스를 설정하는 것이다. 다음의 코드에서는,IDirect3DDevice8::SetRenderState 및 IDirect3DDevice8::SetStreamSource 를 사용해 이 순서를 실행하고 있다.

m_d3dDevice->SetRenderState( D3DRS_VERTEXBLEND, D3DVBF_TWEENING );
m_d3dDevice->SetRenderState( D3DRS_TWEENFACTOR, *(DWORD*) &TweenFactor );
m_d3dDevice->SetStreamSource( 0 , vb, 12*sizeof(float));

현재의 버텍스 쉐이더에 대해서 복수의 스트림을 지정했을 경우는, 트이닝에페크트에 사용되는 스트림 마다 SetStreamSource 를 호출할 필요가 있다. 이 시점에서, 버텍스 트이닝이 유효하게 된다. 렌더링 함수를 호출하면, 자동적으로 버텍스 트이닝이 적용된다.


버텍스 쉐이더에 의한 트이닝

버텍스 쉐이더에 의한 트이닝을 사용하는 코드는,고정 기능에 의한 트이닝의 코드와 자주(잘) 비슷하다. 유일 다른 점은, 다음에 나타내도록(듯이) IDirect3DDevice8::CreateVertexShader 호출 뿐이다.

m_d3dDevice->CreateVertexShader( decl, &vsFunction, &handle, 0 );

CreateVertexShader 의 제 2 파라미터는, 버텍스 쉐이더 함수의 토큰 배열에의 포인터이다. 이 함수는, 이하의 함수의 어느쪽이든을 호출해 생성 할 수도 있다.

  • D3DXAssembleShader
  • D3DXAssembleShaderFromFileA
  • D3DXAssembleShaderFromFileW

다음의 샘플 코드에서는, AppTween.vsh 파일로부터 버텍스 쉐이더를 조립한다.

D3DXAssembleShaderFromFile( "AppTween.vsh", 0, NULL, &vsFunction, NULL );

버텍스 쉐이더 함수의 생성의 상세한 것에 대하여는, 「버텍스 쉐이더 함수」를 참조할것.


칼라 라이팅

D3DLIGHT8 구조체 (Diffuse,Specular,Ambient)의 색에 관련하는 멤버는,D3DCOLORVALUE 구조체이다. 이러한 구조체로 정의하는 색은, 일반적으로는 0.0 ~ 1.0 의 범위의 RGBA 값이며, 0.0 이 흑에 상당한다. 대부분은 광색이 이 범위가 되도록(듯이) 하지만, 특수 효과를 겨냥할 때는, 이 범위외의 값을 사용할 수도 있다. 예를 들어, 큰 값의 색을 설정해, 장면을 엉망으로 할 만큼 강한 빛을 만들 수가 있다. 또, 색을 부의 값으로 설정해,암색빛을 만들 수가 있다. 어두운 빛은, 장면에서 극적인그림자를 강하게 하거나 그 외의 이펙트에 유용하다.


DirectX Graphics 의 고도의 주제

여기에서는, Microsoft® Direct3D® 및 Direct3DX API 의 고도의 사용법에 대해 설명한다. 여기서의 내용은, 「DirectX Graphics 의 사용법」의 내용보다 자세하다.

설명하는 주제는, 다음과 같다.

  • 이펙트와 테크닉
  • 고차원 프리미티브
  • 행렬 스택
  • 픽셀 쉐이더
  • 포인트 스프라이트
  • 버텍스 쉐이더
  • X 파일


이펙트와 테크닉

여기에서는, 이펙트와 테크닉에 대해 설명해, 어플리케이션내에서의 사용 방법을 해설한다. 설명하는 주제는, 다음과 같다.

  • 이펙트와 테크닉에 대해
  • 이펙트 파일의 원가요소
  • 이펙트와 테크닉의 사용법


이펙트와 테크닉에 대해

Microsoft® Direct3D® 의 이펙트를 사용하면(자), 어플리케이션으로 1 개의 이펙트에 대해서 다수가 다른 테크닉을 정의할 수 있다. 각 이펙트에는 1 개 이상의 테크닉이 있어, 그 이펙트의 렌더링을 제어한다. 각 테크닉에서는, 현재의 디바이스가 그 테크닉을 지원 하고 있을지 어떨지가 확인된다. 현재의 디바이스가 테크닉을 지원 하고 있지 않는 경우는, 다른 테크닉을 사용할 수 있다.

렌더링 하는 이펙트의 복잡함의 제어에는, 다른 테크닉을 사용할 수 있다. 예를 들어, 샘에 잔물결이 서, 빛을 반사하고 있는 경우를 생각한다. 1 개의 테크닉을 사용해, 복수의 텍스쳐와 라이팅이 있는 장면 전체를 1 살의 패스로 렌더링 하면 동시에, 다른 테크닉을 사용해, 멀티 패스 렌더링을 실시할 수가 있다. 이러한 조작을 실시할 수 있으므로, 싱글 패스 렌더링을 지원 하고 있지 않는 비디오 카드에서도 이펙트를 렌더링 할 수가 있다.

또, 세부를 어느 정도 세세하게 표현할까에 근거해, 이펙트를 조정할 수 있다. 먼 곳에 표시되는 이펙트에는 보다 단순한 테크닉을 사용하는 것으로, 복잡한 테크닉을 렌더링 할 때에 발생하는 컴퓨터의 오버헤드를 줄일 수가 있다.

이펙트를 사용하는 이점은 그 밖에도 있어, 소스 어플리케이션을 재컴파일 하는 일 없이, 이펙트 파일을 변경할 수가 있다. 이 때문에, 최신의 비디오 카드를 최대한으로 이용하는 제품을 릴리스 할 수 있다. 또, 향후의 비디오 카드를 이용할 수 있도록(듯이), 이펙트 파일을 갱신하는 일도 가능하다.


이펙트 파일의 원가요소

이펙트 파일은, 사용하는 테크닉을 정의한다. 이펙트 파일의 정의는, 기본적으로는 1 개(살) 또는 복수의 선언으로 시작되어, 그 후에 이펙트의 각 테크닉의 정의를 계속한다. 다음에 나타내는 샘플은, 2 개의 텍스쳐 및 2 개의 테크닉을 정의하는 이펙트 파일이다.

이펙트 파일은, 이펙트에 사용하는 2 개의 텍스쳐의 선언으로 시작되어 있다.

texture tex0; // 1 번째의 텍스쳐
texture tex1; // 2 번째의 텍스쳐

1 번째의 텍스쳐에서는, 1 살의 패스를 사용해 장면을 렌더링 한다.

technique t0
{
    pass p0
    {
        Texture[0] = <tex0>;
        Texture[1] = <tex1>;

        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;

        ColorOp[1] = Add;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;

        ColorOp[2] = Disable;
    }
}

2 번째의 테크닉에서는, 복수의 패스를 사용해 장면을 렌더링 한다. 이 테크닉은, 현재의 디바이스가 복수의 텍스쳐에 대한 싱글 패스 렌더링을 지원 하고 있지 않는 경우에 사용한다.

technique t1
{
    pass p0
    {
        Texture[0] = <tex0>;

        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;
        ColorOp[1] = Disable;
    }

    pass p1
    {
        AlphaBlendEnable = True;
        SrcBlend = One;
        DestBlend = One;

        Texture[1] = <tex1>;

        ColorOp[1] = SelectArg1;
        ColorArg1[1] = Texture;
        ColorOp[1] = Disable;
    }
}

이 이펙트 파일에 의해, 디바이스가 2 개의 텍스쳐에 대한 싱글 패스 렌더링을 지원 하고 있지 않는 경우에는, 복수의 패스를 사용해 텍스쳐를 렌더링 할 수 있다. 이펙트 파일의 상세한 것에 대하여는, 「이펙트 파일 형식」을 참조할것.


이펙트와 테크닉의 사용법

여기에서는, 어플리케이션에서의 이펙트와 테크닉의 생성 방법 및 사용 방법에 대해 설명한다.

  • 이펙트의 생성
  • 테크닉의 타당성 확인
  • 테크닉을 사용한 렌더링
  • 이펙트와 테크닉의 기술의 읽기
  • 이펙트 파일의 샘플


이펙트의 생성

이펙트를 생성 하는 최초의 순서는, 이펙트의 컴파일이다. 다음의 함수를 사용해, 이펙트를 컴파일 할 수 있다.

  • D3DXCompileEffect
  • D3DXCompileEffectFromFileA
  • D3DXCompileEffectFromFileW

다음의 샘플 코드에서는,D3DXCompileEffectFromFileA 함수를 사용해, 파일 Water.sha 에 정의된 이펙트를 로드해 컴파일 하고 있다.

LPD3DXBUFFER pCompiledEffect;
D3DXCompileEffectFromFile( "Water.sha", &pCompiledEffect, NULL );

D3DXCompileEffectFromFileA 의 1 번째의 파라미터는, 이펙트가 정의된 파일을 지정하는 ANSI 캐릭터 라인에의 포인터이다. 2 번째의 파라미터는,ID3DXBuffer 인터페이스에의 포인터의 주소이다. 이 버퍼에는, 컴파일 된 이펙트가 저장 된다. D3DXCompileEffectFromFileA 의 마지막 파라미터는,ID3DXBuffer 인터페이스에의 포인터의 주소이다. 이 버퍼에는, 돌려주어진 ASCII 에러 메세지가 저장 된다. 이 예에서는, 에러를 무시해, 이 파라미터에 NULL 를 설정해 있다.

이펙트를 컴파일 한 후는, 다음의 예에 나타내도록(듯이),D3DXCreateEffect 함수를 사용해 ID3DXEffect 인터페이스에의 포인터를 취득한다.

ID3DXEffect * pEffect;
D3DXCreateEffect( g_d3dDevice, pCompiledEffect->GetBufferPointer(),
                  pCompiledEffect->GetBufferSize(), 0, &pEffect);
pCompiledEffect->Release();

이 함수가 성공하면(자), pEffect 에 ID3DXEffect 인터페이스에의 유효한 포인터가 저장 된다. 컴파일 끝난 이펙트를 저장 한 ID3DXBuffer 에 의해 종료한 후, 반드시 IUnknown::Release 메소드를 호출해 메모리 누수를 막는다.


테크닉의 타당성 확인

테크닉을 사용하기 전에, 디바이스가 그 테크닉을 지원 하고 있는 것을 확인한다. 테크닉의 타당성을 확인하려면 , 다음의 샘플 코드에 나타내도록(듯이),ID3DXTechnique::Validate 메소드를 사용한다.

LPD3DXTECHNIQUE pTechnique;
pEffect->GetTechnique(0, &pTechnique);
if ( pTechnique->Validate() ! = D3D_OK)
    // 테크닉이 현재의 디바이스에서는 유효하지 않다.

주 테크닉을 사용하기 전에, 그 타당성을 확인하는 것을 강하게 권한다. 무효인 테크닉을 사용하면(자), 불명한 이펙트가 포함된다.


테크닉을 사용한 렌더링

다음의 예는, 어플리케이션에서의 테크닉의 렌더링 방법을 나타내고 있다. 유효한 테크닉을 검출한 후, 다음의 샘플 코드에 나타내도록(듯이), 어플리케이션에서는 ID3DXTechnique::Begin 메소드를 호출해, 테크닉의 적용을 시작 한다.

UINT uPasses;
pTechnique->Begin(&uPasses);

Begin 의 유일한 파라미터는, 부호 없음 정수의 주소이다. Begin 가 불려 간 후, 이 값에는 테크닉으로 사용되는 패스의 수가 저장 된다.

다음의 순서로서 각 패스의 개별의 렌더링을 실시한다. 패스를 렌더링 하려면 ,ID3DXTechnique::Pass 메소드를 호출한다. 다음의 샘플 코드에서는, 루프를 사용해, 테크닉에 필요한 모든 패스를 렌더링 하고 있다.

for(UINT uPass = 0; uPass < uPasses; uPass++)
{
    pTechnique->Pass(uPass);
    g_d3dDevice->SetStreamSource( 0, pvbVertices, sizeof(WATER_VERTEX) );
    g_d3dDevice->SetIndices( pIB, 0 );
    g_d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLESTRIP, 0,
                                       uVertices, 0, uIndices -2 );
}

Pass 를 호출하는 것으로, 장면의 렌더링에 필요한 스테이트를 설정해 있다.

주 ID3DXTechnique::Begin 는,IDirect3DDevice8::BeginScene / IDirect3DDevice8::EndScene 블록내에서 호출할 필요가 있다.


이펙트와 테크닉의 기술의 읽기

이펙트에 관한 정보를 읽어내려면 ,ID3DXEffect::GetDesc 메소드를 사용해, 파라미터에 D3DXEFFECT_DESC 구조체를 건네준다. D3DXEFFECT_DESC 구조체에는, 이펙트를 기술하는 멤버가 포함된다.

테크닉에 관한 정보를 읽어내려면 ,ID3DXTechnique::GetDesc 메소드를 사용해, 파라미터에 D3DXTECHNIQUE_DESC 구조체를 건네준다. D3DXTECHNIQUE_DESC 구조체에는, 테크닉을 기술하는 멤버가 포함된다.


이펙트 파일의 샘플

다음의 이펙트 파일은,Water 샘플에 사용하는 것이다.

이 파일에는, 최초로 이 이펙트로 사용하는 2 개의 행렬, 3 개의 텍스쳐, 및 버텍스 쉐이더가 선언되고 있다.

matrix mID;     // 단위 트랜스 폼
matrix mENV;    // 환경 맵 트랜스 폼

texture tFLR;   // 플로어 텍스쳐
texture tCAU;   // 코스틱테크스체
texture tENV;   // 큐브 환경 맵

vertexshader vs =  decl { fvf xyz | normal | diffuse | tex1; };

최초의 테크닉에서는, 플로어 텍스쳐와 코스틱테크스체를 사용해, 물의 장면을 렌더링 한다. 물과 플로어에는 빛이 반사한다. 이 테크닉에서는, 단일의 패스와 4 개의 텍스쳐 스테이지 스테이트를 사용한다.

technique T0
{
    vertexshader = <vs>;

    pass P0
    {
        Lighting       = True;
        SpecularEnable = True;

        // 스테이지 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0]   = SelectArg2;
        AlphaArg2[0] = Current;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tFLR>;
        TextureTransform[0] = <mID>;
        TextureTransformFlags[0] = Count2;

        // 스테이지 1
        ColorOp[1]   = Add;
        ColorArg1[1] = Texture;
        ColorArg2[1] = Current;
        AlphaOp[1]   = SelectArg2;
        AlphaArg2[1] = Current;

        MinFilter[1] = Linear;
        MagFilter[1] = Linear;
        MipFilter[1] = Point;

        Texture[1] = <tCAU>;
        TextureTransform[1] = <mID>;
        TextureTransformFlags[1] = Count2;

        // 스테이지 2
        ColorOp[2]   = BlendCurrentAlpha;
        ColorArg1[2] = Texture;
        ColorArg2[2] = Current;
        AlphaOp[2]   = Disable;

        MinFilter[2] = Linear;
        MagFilter[2] = Linear;
        MipFilter[2] = Point;

        Texture[2] = <tENV>;
        TextureTransform[2] = <mENV>;
        TextureTransformFlags[2] = Count3;
        TexCoordIndex[2] = CameraSpaceReflectionVector;

        // 스테이지 3
        ColorOp[3] = Disable;
        AlphaOp[3] = Disable;
    }
}

2 번째의 테크닉에서는, 플로어 텍스쳐와 코스틱테크스체를 사용해, 물의 장면 렌더링 한다. 플로어와 물에는 빛이 반사한다. 이 테크닉에서는, 2 살의 패스를 사용해 장면을 렌더링 한다.

technique T1
{
    vertexshader = <vs>;

    pass P0
    {
        // 스테이지 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0]   = Disable;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tFLR>;
        TextureTransform[0] = <mID>;
        TextureTransformFlags[0] = Count2;

        // 스테이지 1
        ColorOp[1]   = Add;
        ColorArg1[1] = Texture;
        ColorArg2[1] = Current;
        AlphaOp[1]   = Disable;

        MinFilter[1] = Linear;
        MagFilter[1] = Linear;
        MipFilter[1] = Point;

        Texture[1] = <tCAU>;
        TextureTransform[1] = <mID>;
        TextureTransformFlags[1] = Count2;

        // 스테이지 2
        ColorOp[2] = Disable;
        AlphaOp[2] = Disable;
    }

    pass P1
    {
        SrcBlend  = One;
        DestBlend = InvSrcAlpha;

        Lighting         = True;
        SpecularEnable   = True;
        AlphaBlendEnable = True;

        // 스테이지 0
        ColorOp[0]   = BlendDiffuseAlpha;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Diffuse;
        AlphaOp[0]   = SelectArg2;
        AlphaArg2[0] = Diffuse;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tENV>;
        TextureTransform[0] = <mENV>;
        TextureTransformFlags[0] = Count3;
        TexCoordIndex[0] = CameraSpaceReflectionVector;

        // 스테이지 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }
}

3 번째의 테크닉에서는, 플로어 텍스쳐와 코스틱테크스체를 사용해, 물의 장면을 렌더링 한다. 수면에는 빛이 반사한다. 이 이펙트에서는, 3 살의 패스를 사용해 장면을 렌더링 한다.

technique T2
{
    vertexshader = <vs>;

    pass P0
    {
        // 스테이지 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0]   = Disable;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tFLR>;
        TextureTransform[0] = <mID>;
        TextureTransformFlags[0] = Count2;

        // 스테이지 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }

    pass P1
    {
        SrcBlend  = One;
        DestBlend = One;

        Lighting         = False;
        SpecularEnable   = True;
        AlphaBlendEnable = True;

        // 스테이지 0
        ColorOp[0]   = Add;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;
        AlphaOp[0]   = Disable;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tCAU>;
        TextureTransform[0] = <mID>;
        TextureTransformFlags[0] = Count2;

        // 스테이지 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }

    pass P2
    {
        SrcBlend  = One;
        DestBlend = InvSrcAlpha;

        Lighting         = True;
        SpecularEnable   = True;
        AlphaBlendEnable = True;

        // 스테이지 0
        ColorOp[0]   = BlendDiffuseAlpha;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Diffuse;
        AlphaOp[0]   = SelectArg2;
        AlphaArg2[0] = Diffuse;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tENV>;
        TextureTransform[0] = <mENV>;
        TextureTransformFlags[0] = Count3;
        TexCoordIndex[0] = CameraSpaceReflectionVector;

        // 스테이지 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }
}

4 번째의 테크닉에서는, 플로어 텍스쳐와 코스틱테크스체를 사용해, 물의 장면을 렌더링 한다. 이 이펙트에서는, 단일의 패스를 사용해 장면을 렌더링 한다.

technique T3
{
    vertexshader = <vs>;

    pass P0
    {
        Lighting       = True;
        SpecularEnable = True;

        // 스테이지 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0]   = Disable;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0]   = <tFLR>;

        // 스테이지 1
        ColorOp[1]   = Add;
        ColorArg1[1] = Texture;
        ColorArg2[1] = Current;
        AlphaOp[1]   = Disable;

        MinFilter[1] = Linear;
        MagFilter[1] = Linear;
        MipFilter[1] = Point;

        Texture[1]   = <tCAU>;

        // 스테이지 2
        ColorOp[2]   = Disable;
        AlphaOp[2]   = Disable;
    }
}

5 번째의 테크닉에서는, 플로어 텍스쳐와 코스틱테크스체를 사용해, 물의 장면을 렌더링 한다. 이 테크닉에서는 반사는 사용하지 않는다. 이 이펙트에서는, 2 살의 패스를 사용해 장면을 렌더링 한다.

technique T4
{
    vertexshader = <vs>;

    pass P0
    {
        // 스테이지 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Diffuse;

        AlphaOp[0]   = SelectArg1;
        AlphaArg1[0] = Texture;
        AlphaArg2[0] = Diffuse;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0]   = <tFLR>;

        // 스테이지 1
        ColorOp[1]   = Disable;
        AlphaOp[1]   = Disable;
    }

    pass P1
    {
        SrcBlend  = One;
        DestBlend = One;

        Lighting         = True;
        SpecularEnable   = True;
        AlphaBlendEnable = True;

        // 스테이지 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;

        AlphaOp[0]   = SelectArg1;
        AlphaArg1[0] = Texture;
        AlphaArg2[0] = Current;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0]   = <tCAU>;

        // 스테이지 1
        ColorOp[1]   = Disable;
        AlphaOp[1]   = Disable;
    }
}

6 번째 및 마지막 테크닉에서는, 플로어 텍스쳐만을 사용해, 물의 장면을 렌더링 한다. 이 테크닉에서는 반사는 사용하지 않는다. 이 이펙트에서는, 단일의 패스를 사용해 장면을 렌더링 한다.

technique T5
{
    vertexshader = <vs>;

    pass P0
    {
        Lighting       = True;
        SpecularEnable = True;

        // 스테이지 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;

        AlphaOp[0]   = SelectArg1;
        AlphaArg1[0] = Texture;
        AlphaArg2[0] = Current;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = None;

        Texture[0]   = <tFLR>;

        // 스테이지 1
        ColorOp[1]   = Disable;
        AlphaOp[1]   = Disable;
    }
}


고차원 프리미티브

여기에서는, 고차원 원시적에 대해 설명해, 어플리케이션내에서의 사용 방법을 해설한다. 설명하는 주제는, 다음과 같다.

  • 고차원 원시적이다고는
  • 분할도 증가에 의한 품질 향상
  • 스플라인 베이스의 툴로부터의 직접 매핑
  • 고차원 프리미티브의 사용법


고차원 원시적이다고는

Microsoft® Direct3D® for Microsoft DirectX® 8.0 에서는, 포인트, 라인, 삼각형, 및 구라두 프리미티브를 지원 하고 있다. 이것들은, 선형 보간을 넘는 고차원 보간을 지원 하기 위해서 확장되었다. 삼각형이나 선은 공간적인 확대가 있는 것에도 불구하고, 지금까지는 선형 보간을 사용해 렌더링 되고 있었다. DirectX 8.0 에서는, Direct3D 가, 고차원 (최대 5 차까지의) 보간을 사용하는 이러한 프리미티브 타입의 렌더링을 지원 하고 있다. 또, 새로운 사변형 프리미티브 타입이 지원 되고 있다. 이 새로운 타입도 고차원 보간을 사용해 렌더링 된다. 이러한 기능은, 본래는 애니메이션이나 캐릭터의 렌더링의 필요성으로부터 추가되었다. 그러나, 지형이나 수면이라고 하는 표면에도 응용할 수 있다.

고차원 프리미티브는, 리스트, 스트라이프, 팬, 또는 인덱스화 된 메쉬로서 어플리케이션 프로그래밍 인터페이스 (API)에 전송 될 때, 고차원 보간을 지원 한다. 이것은, 버텍스 자체에 encode 된 추가 정보를 사용해 실행된다. 예를 들어, 삼차 보간을 유효하게 하기 위해서, 법선 벡터를 사용해 버텍스 위치의 접면을 정의할 수가 있다. 대부분의 이행에서는, 평면의 삼각형에의 테셀레이션에 의해 고차원 보간을 지원 한다. 테셀레이션의 스텝은, 논리적으로 버텍스 쉐이더 스테이지의 앞에 적용된다. 버텍스 쉐이더 API 는 입력 데이터에 시멘틱스를 적용하지 않기 때문에, 좌표 위치 및 옵션으로 법선 벡터를 나타내는 버텍스 스트림 성분을 식별하기 위한 특별한 메카니즘이 준비되어 있다. 그 외 모든 성분은 응분에 보간 된다.


분할도 증가에 의한 품질 향상

현재의 프리미티브는, 매끄러운 표면을 표현하는데 최적인 것이라고는 할 수 없다. 곡면의 렌더링에서는, 삼차 다항식등의 고차원 보간 테크닉을 사용하면(자), 보다 정확한 계산을 실시할 수가 있다. 이것에 의해, 실루엣의 인연이나 스펙큐러 표면 라이팅에 나타나는 부자연스러운 효과를 삭감 또는 해소해, 보다 리얼한 표현이 가능하게 된다. 게다가 팁상에서 테셀레이션을 할 때, 테셀레이트 된 삼각형은, 버스의 대역폭에 영향을 주지 않는다. 많은 경우, 소량의 테셀레이션에 의해, 퍼포먼스에 너무 영향을 주는 일 없이, 이미지의 품질을 향상시킬 수가 있다.

Microsoft® Direct3D® for Microsoft DirectX® 8.0 에서는, 기존의 다각형 지향의 툴이나 아트 파이프라인으로 생성 된 컨텐츠의 분할도를, 간단한 방법으로 향상시킬 수가 있다. 어플리케이션이 해야 할것은, 필요한 레벨의 테셀레이션을 제공하는 것으로, 법선 벡터를 포함한 표준적인 삼각형 구문을 사용해 데이터를 전송 하는 것 뿐이다.


스플라인 베이스의 툴로부터의 직접 매핑

현재, 많은 authoring tool가 고차원 프리미티브를 지원 하고 있어, 보통의 평면 삼각형 메쉬보다 강력한 모델링 처리를 실현하고 있다. 이러한 툴은, 타당한 수의 패치가 생성되는 것 같은 효율적인 사용법을 하면, 어플리케이션 프로그래밍 인터페이스 (API)로 직접 렌더링 할 수 있는 것 같은 컨텐츠를 생성 할 수 있다. 이 요건을 채우기 (위해)때문에, 들어 오는 버텍스 데이터 스트림을 제어 포인트의 2D 배열로서 해석해, 필요한 해상도에 테셀레이트 하는, 새로운 엔트리 포인트가 추가되었다.


고차원 프리미티브의 사용법

여기에서는, 어플리케이션으로 고차원 프리미티브를 사용하는 방법에 대해 설명한다.

  • 고차원 프리미티브 지원의 확인
  • 패치의 드로잉(Drawing)


고차원 프리미티브 지원의 확인

D3DCAPS8 의 DevCaps 멤버를 조회해, 고차원 원시적에 관한 처리의 지원 레벨을 확인할 수가 있다. 다음의 표는, Microsoft® DirectX® 8.0에서의 고차원 원시적으로 관련하는 디바이스 기능을 나타내고 있다.

디바이스 기능 | 설명
D3DDEVCAPS_NPATCHES | 디바이스는, N 패치를 지원 하고 있다.
D3DDEVCAPS_QUINTICRTPATCHES | 디바이스는, 5 차 베쥬 및 B 스플라인을 지원 하고 있다.
D3DDEVCAPS_RTPATCHES | 디바이스는, 사각형 및 삼각형 (RT) 패치를 지원 하고 있다.
D3DDEVCAPS_RTPATCHHANDLEZERO | RT 패치는, 핸들 제로를 사용하면(자) 효율적으로 드로잉(Drawing) 할 수 있다.


패치의 드로잉(Drawing)

Microsoft® DirectX® 8.0 에서는, 2 종류의 고차원 프리미티브, 즉 패치가 지원 되고 있다. 이것들은 N 패치 및 Rect/Tri 패치로 불린다. N 패치는, D3DRS_PATCHSEGMENTS 에 1.0 보다 큰 값을 설정하는 것으로, 삼각형 렌더링 호출을 사용해 렌더링 할 수 있다. Rect/Tri 패치는, 다음의 명시적인 엔트리 포인트를 사용해 렌더링 할 필요가 있다.

다음의 메소드를 사용해, Microsoft Direct3D® for DirectX 로 패치를 드로잉(Drawing) 할 수 있다.

  • IDirect3DDevice8::DrawRectPatch
  • IDirect3DDevice8::DrawTriPatch

DrawRectPatch 는, 현재 설정되어 있는 스트림을 사용해,pRectPatchInfo 파라미터로 지정된 사각형 고차원 패치를 드로잉(Drawing) 한다. Handle 파라미터는, 패치와 핸들을 관련짓기 위해서(때문에) 사용된다. 이 때문에, 다음에 패치가 드로잉(Drawing) 될 때는,pRectPatchInfo 를 다시 지정할 필요가 없다. 이것에 의해, 순서 방향 차이 계수 또는 그 외의 정보를 사전에 계산해 캐쉬할 수가 있어 그 결과, 같은 핸들을 사용한 그 후의 DrawRectPatch 에의 호출이 효율적으로 실행된다.

정적 패치에 대해서는, 어플리케이션이 버텍스 쉐이더와 적절한 스트림을 설정해,pRectPatchInfo 파라미터내에 패치 정보를 제공해, 핸들을 지정하는 것으로, Direct3D 가 정보를 캡춰 해 캐쉬할 수 있도록(듯이) 되고 있다. 어플리케이션은 그 후 pRectPatchInfo 가 NULL 로 설정된 상태로 DrawRectPatch 를 호출하는 것으로, 패치를 효율적으로 드로잉(Drawing) 할 수 있다. 캐쉬된 패치를 드로잉(Drawing) 하면나무는, 현재 설정되어 있는 스트림은 무시된다. 다만,pNumSegs 에 새로운 값을 설정하는 것으로, 캐쉬된 pNumSegs 를 덧쓰기할 수도 있다. 또, 캐쉬된 패치를 렌더링 하는 경우는, 그 패치가 캐쉬되었을 때와 같은 버텍스 쉐이더를 설정할 필요가 있다.

동적 패치에 대해서는, 패치의 렌더링 마다 패치 데이터가 변화하기 위해(때문에), 정보를 캐쉬하는 것은 효율적은 아니다. 어플리케이션은,Handle 를 0 으로 설정하는 것으로, 이 정보를 Direct3D 에게 전할 수가 있다. 이 경우, Direct3D 는, 현재 설정되어 있는 스트림 및 pNumSegs 값을 사용해 패치를 드로잉(Drawing) 해, 정보의 캐쉬를 실시하지 않는다. Handle 를 0 으로 설정한 상태로 pPatch 를 NULL 로 설정 하면 무효가 된다.

같은 핸들에 pRectPatchInfo 를 다시 지정하는 것으로 , 어플리케이션은 전회 캐쉬한 정보를 덧쓰기할 수가 있다.

pNumSegs 가 NULL 로 설정되어 있는 경우는, 테셀레이트는 D3DRS_PATCHSEGMENTS 를 사용해 테셀레이션의 양을 제어한다. 이 경우는, 당연, 모든 옆에 같은 테셀레이션이 사용된다. N 패치에는 특별한 메소드는 없다. 테셀레이션은, D3DRS_PATCHSEGMENTS 에 의해 제어된다. 법선을 지정할 필요가 있다.

DrawTriPatch 는 DrawRectPatch 를 닮아 있지만, 삼각형 고차원 패치를 드로잉(Drawing) 하는 점이 다르다.


행렬 스택

Direct3DX 유틸리티 라이브러리는, COM 오브젝트를 사용한 행렬 스택을 제공하고 있다.

설명하는 주제는, 다음과 같다.

  • 행렬 스택이란
  • 장면의 계층의 이행


행렬 스택이란

Direct3DX 유틸리티 라이브러리는,ID3DXMatrixStack 인터페이스를 갖추고 있다. 이 인터페이스는, 행렬을 행렬 스택에 푸쉬 하거나 행렬 스택으로부터 팝 오프 하거나하기 위한 메카니즘을 제공한다. 행렬 스택을 이행 하면, 트랜스 폼 계층내를 이동할 때에, 행렬을 효율적으로 관리할 수가 있다.

Direct3DX 유틸리티 라이브러리는, 행렬 스택을 사용해 트랜스 폼을 행렬로서 저장 한다. ID3DXMatrixStack 인터페이스의 각종 메소드를 사용해, 현재의 행렬 (행렬의 최상부에 있는 행렬)을 조작할 수가 있다. 경향 행렬을 클리어 하려면 ,ID3DXMatrixStack::LoadIdentity 메소드를 사용한다. 특정의 행렬을 경향 트랜스 폼 행렬로서 로드하도록(듯이) 명시적으로 지정하려면 ,ID3DXMatrixStack::LoadMatrix 메소드를 사용한다. 그 후 ID3DXMatrixStack::MultMatrix 메소드 또는 ID3DXMatrixStack::MultMatrixLocal 메소드를 호출해, 현재의 행렬을 지정한 행렬로 곱셈할 수가 있다.

ID3DXMatrixStack::Pop 메소드를 사용 하면, 전의 트랜스 폼 행렬에 돌아와,ID3DXMatrixStack::Push 메소드를 사용 하면, 스택에 트랜스 폼 행렬이 추가된다.

행렬 스택 위에의 개개의 행렬은, Direct3DX 유틸리티 라이브러리의 D3DXMATRIX 구조체에 의해 정의된 4 × 4 동차 행렬로서 표현된다.


장면의 계층의 이행

일련의 단순한 오브젝트로부터 복잡한 오브젝트가 구축되는 계층 모델은, 행렬 스택을 사용하는 것으로 간단하게 구축할 수 있게 된다.

장면이나 트랜스 폼에서는, 계층은 보통 트리 데이터 구조로서 표현된다. 트리 데이터 구조내의 각 노드에는 행렬이 포함된다. 특정의 행렬은, 노드의 부모로부터 노드에의 좌표계의 변화를 나타낸다. 예를 들어, 인간의 팔을 모델링 하고 있는 경우, 다음과 같은 계층을 이행 하는 경우가 있다.

이 계층에서는, Body 행렬이 동체를 월드내에 배치한다. UpperArm 행렬에는 어깨의 회전, LowerArm 행렬에는 팔꿈치의 회전, Hand 행렬에는 손목의 회전이 각각 포함된다. 손이 어디서 월드와 관련할까를 결정하려면 , Body 로부터 Hand 까지의 행렬을 모두 곱셈한다.

전의 계층은, 각 노드에 자식이 1 개(살)씩 밖에 없었기 때문에, 매우 단순했다. 보다 상세하게 손을 모델링 하는 경우는, 손가락을 추가하게 된다. 5 개의 손가락은 모두, Hand 의 자식으로 계층에 추가할 수 있다.

팔의 완전한 그래프내를 깊이 우선의 순서 (단일의 패스를 가능한 한 깊게 이동하고 나서 다음의 패스로 옮긴다)로 이동하는 경우는, 분단 된 일련의 렌더링을 실행하게 된다. 예를 들어, 손과 손가락을 렌더링 하는 경우는, 다음의 순서를 실행한다.

  1. Hand 행렬을 행렬 스택에 푸쉬 한다.
  2. 손을 드로잉(Drawing) 한다.
  3. Thumb 행렬을 행렬 스택에 푸쉬 한다.
  4. 엄지를 드로잉(Drawing) 한다.
  5. Thumb 행렬을 스택으로부터 팝 오프 한다.
  6. Finger 1 행렬을 행렬 스택에 푸쉬 한다.
  7. 최초의 손가락을 드로잉(Drawing) 한다.
  8. Finger 1 행렬을 스택으로부터 팝 오프 한다.
  9. Finger 2 행렬을 행렬 스택에 푸쉬 한다. 모든 손가락이 렌더링 될 때까지, 이 순서를 반복한다.

손가락의 렌더링이 끝나면(자), Hand 행렬을 스택으로부터 팝 오프 한다.

다음의 예를 사용해, 이 기본적인 프로세스를 코드내에서 실행할 수 있다. 트리 데이터 구조의 깊이 우선 검색중에 노드가 발견되면, 행렬을 행렬 스택의 최상부에 푸쉬 한다.

MatrixStack->Push();
MatrixStack->MultMatrix(pNode->matrix);

노드의 조작이 종료하면(자), 행렬을 행렬 스택의 최상부로부터 팝 오프 한다.

MatrixStack->Pop();

즉, 스택의 최상부에 있는 행렬은, 항상 현재의 노드의 월드 트랜스 폼을 나타낸다. 이 때문에, 각 노드의 드로잉(Drawing)전에, Microsoft® Direct3D® 행렬을 설정할 필요가 있다.

pD3DDevice->SetTransform(D3DTS_WORLDMATRIX(0), *MatrixStack->GetTop());

Direct3DX 행렬 스택으로 실행할 수 있는 각종 메소드에 관한 자세한 것은, 「ID3DXMatrixStack 」를 참조할것.


픽셀 쉐이더

여기에서는, Microsoft® DirectX® 8.0 으로 지원 되는 픽셀 처리의 최신 기능인 픽셀 쉐이더에 대해 해설해, Microsoft Direct3D® 어플리케이션에서의 사용 방법을 설명한다. 설명하는 주제는, 다음과 같다

  • 픽셀 쉐이더란
  • 픽셀 쉐이더의 기본
  • 픽셀 쉐이더의 적용 범위
  • 픽셀 쉐이더의 데이터 플로우
  • 픽셀 쉐이더의 사용법
  • 픽셀 쉐이더의 예

이 문서로 사용되는 모든 픽셀 쉐이더 코드 및 구문은, Direct3DX 픽셀 쉐이더 어셈블러에 근거해서 , 호환성이 있다. 이 섹션을 읽기 전에, 「픽셀 쉐이더 어셈블러 레퍼런스」를 읽어, 픽셀 쉐이더 어셈블러에 대한 지식을 취득해 둘 필요가 있다.


픽셀 쉐이더란

다음의 예는, 픽셀 쉐이더의 간단한 사용 방법과 Direct3DX 픽셀 쉐이더 어셈블러가 해석 가능한 구문을 나타내고 있다.

ps. 1.0          // DirectX8 버젼.
tex t0          // 텍스쳐를 선언한다.
tex t1          // 라이트 맵을 선언한다.

mov r0, t0
mul r0, r0, t1  // 라이트 맵을 곱셈한다.
mul r0, r0, v0  // 디퓨즈를 곱셈한다.
add r0, r0, v1  // 스펙큐러를 추가한다.

이 픽셀 쉐이더는, 라이트 맵, 디퓨즈색, 및 스펙큐러의 추가와 함께 베이스 텍스쳐를 선언하고 있다.

픽셀 쉐이더는, 색 및 알파 블렌딩 처리 및 텍스쳐 애드레싱 처리를 제어한다. Microsoft® Direct3D® for Microsoft DirectX® 8.0 은, 픽셀 처리 및 텍스쳐 블렌딩 처리를 정의하기 위한 프로시쟈르파라다임을 정의한다. 이 모델에게는, 가상 머신 아키텍쳐의 정의, 및 그 동작을 정의하는 일련의 명령과 수식자가 포함된다. 이 패러다임(paradigm)는, 프로세서 베이스의 이행일 필요는 없다.

픽셀 쉐이더는, 다음의 방법으로, DirectX 6.0 및 7.0 의 멀티 텍스쳐 기능을 확장 및 표준화 한다.

  • 일반적인 읽고 쓰기 레지스터세트가 추가되었기 때문에, D3DTA_CURRENT 만을 사용하는 시리얼 cascade에 의한 지원보다 유연한 식을 사용할 수 있다. 이것에 의해, 개별의 결과 레지스터 인수의 지정이 각 스테이지에서 필요하다.
  • D3DTOP_MODULATE2X 및 D3DTOP_MODULATE4X 텍스쳐 처리가, 어느 명령에 대해서도 적용할 수 있는 개별의 수식자로서 분할되었다 (양쪽 모두는 불가). 이것에 의해, 개별의 D3DTOP_MODULATE 및 D3DTOP_MODULATE2X 처리의 필요성이 없어졌다.
  • 바이어스 처리 수식자 및 비바이어스 텍스쳐 처리 수식자가 적용 가능하게 되었다 (양쪽 모두는 불가). 이것에 의해, 개별의 추가 및 바이어스 추가 처리의 필요성이 없어졌다.
  • 추가를 곱셈하기 위해서 옵션의 3 번째의 인수가 추가되었기 때문에, 프로시쟈르피크세르시다가 arg1 * arg2 + arg0 를 실행할 수 있게 되어 있다. 이것에 의해, D3DTOP_MODULATEALPHA_ADDCOLOR 및 D3DTOP_MODULATECOLOR_ADDALPHA 텍스쳐 처리가 없어졌다. 또, 브렌드 처리에도 옵션의 3 번째의 인수가 추가되었기 때문에, 프로시쟈르피크세르시다는 arg1 와 arg2 의 사이의 브렌드 비율로서 arg0 를 사용할 수 있게 되었다. 이것에 의해, D3DTOP_BLENDDIFFUSEALPHA, D3DTOP_BLENDTEXTUREALPHA, D3DTOP_BLENDFACTORALPHA, D3DTOP_BLENDTEXTUREALPHAPM, 및 D3DTOP_BLENDCURRENTALPHA 텍스쳐 처리가 없어졌다.
  • 칼라 처리 및 알파 처리로부터, D3DTOP_BUMPENVMAP 등의 텍스쳐 주소 수정 처리가 발생해, 특히 텍스쳐 주소상에서 처리를 행하기 위한 3 번째의 처리 타입으로서 정의되었다.

이와 같이 확장된 유연성을 보다 효율적으로 지원 하기 위한(해), 어플리케이션 프로그래밍 인터페이스 (API) 구문이 DWORD 페어로부터 ASCII 어셈블(assemble) 코드 구문으로 변경되었다. 이것에 의해, 프로시쟈르피크세르시다에 의해 제공되는 기능을 공개할 수가 있다.

주 픽셀 쉐이더를 사용하는 경우, 스펙큐러의 추가는 렌더링 스테이트에 의해 특히 제어되지 않게 되어, 필요에 따라서 이행 하는 것은 픽셀 쉐이더의 역할이 된다. 그러나, fog 블렌딩은 고정 기능 구문에 의해 적용된다.

Direct3DX 픽셀 쉐이더 어셈블러의 사용 방법에 대한 자세한 것은, 「픽셀 쉐이더 어셈블러 레퍼런스」를 참조할것.


픽셀 쉐이더의 기본

여기에서는, 픽셀 쉐이더를 사용하기에 즈음해 필요한 기본적 정보에 대해 설명한다.

  • 픽셀 쉐이더의 연산 논리 단위
  • 픽셀 쉐이더의 명령의 페어
  • 픽셀 쉐이더의 처리 순서
  • 픽셀 쉐이더의 텍스쳐 선언
  • 픽셀 쉐이더의 텍스쳐 애드레싱
  • 픽셀 쉐이더의 라이팅


픽셀 쉐이더의 연산 논리 단위

다음의 그림은, 픽셀 쉐이더의 연산 논리 단위 (ALU)를 나타내고 있다.


픽셀 쉐이더의 명령의 페어

픽셀 쉐이더를 실행하는 프로세서는, 2 개의 패러렐 파이프라인을 가지고 있다. 1 개(살)은 벡터 처리 (RGB) 용으로, 이제(벌써) 1 개(살)은 스칼라 처리 (알파) 용이다. 이러한 파이프라인을 패러렐로 사용하는 것으로써, 필요한 클락 사이클의 합계수가 삭감되어 프로세서의 이용 효율과 퍼포먼스가 매우 향상한다. 이것은, 기본적으로는 픽셀의 전부 칠해 속도에 영향을 준다.

출력 마스크에 의해 2 개의 파이프라인의 할당 방법으로 영향을 줄 수 있지만, 명시적으로 페어 설정의 구문이 사용되지 않는 이상 처리 순서는 불명확이 된다. 다음의 표는, 출력 마스크 및 관련지을 수 있었던 파이프를 나타내고 있다.

출력 마스크 | 파이프
. a | 처리는 스칼라 파이프에 있다.
. rgb | 처리는 벡터 파이프에 있다.
. rgba | 처리는 스칼라 파이프와 벡터 파이프의 양쪽 모두에 있다. 이것은 이미 페어라고 보여지고 있다.

페어의 2 번째의 명령의 선두에는 + 기호를 붙일 수 있고 있다.

  mul r0.rgb, t0, v0    // 색성분은 곱셈.
+ add r0.a,   t0, v0    // 다만, 알파 성분은 가산.

내적의 명령은 특별한 케이스이다. 이것들은 벡터 처리이며, 항상 벡터 파이프라인내에서 실행된다. 이 때문에, 스칼라 파이프내에서 다른 명령을 지정해도, 다음의 픽셀 쉐이더 코드 예의 같게 페어로 할 수 있다.

dp3 r0.rgb, t0, v0
mul r0.a,   t0, v0

벡터 명령으로서의 내적 처리없이, 내적 처리를 스칼라 명령으로서 지정할 수 없다.


픽셀 쉐이더의 처리 순서

픽셀의 명령과 수식자의 처리 순서는 다음과 같이 된다. 1) 입력 또는 인수 수식자가 적용된다. 2) 중심이 되는 명령이 실행된다. 3) 출력 또는 명령 수식자가 적용된다. 4) 출력 기입 마스크에 대해 결과가 기입해진다.

입력 또는 인수 수식자에 대해서는, 다음과 같은 순서가 된다. 1) 바이어스가 적용된다. 2) 스케일링이 적용된다. 3) 정부의 반전 또는 보충 스텝이 실행된다. 알파 복제도 이 스테이지에서 실행된다. 출력 또는 명령 수식자의 경우는, 스케일/쉬프트 연산자는 채도 스텝보다 우선된다.

최종적인 처리 순서는, 다음과 같이 된다.

  1. 인수 수식자가 적용된다.
  2. 중심이 되는 명령이 실행된다.
  3. 명령 수식자가 적용된다.
  4. 출력 기입 마스크가 적용된다.


픽셀 쉐이더의 텍스쳐 선언

텍스쳐 선언 (텍스쳐 애드레싱 명령)은, 칼라 블렌딩이나 알파 블렌딩등의 명령과는 구별되는, 개별의 픽셀 쉐이더 명령 세트이다. 이러한 명령은, 픽셀 쉐이더의 선두에 없으면 안되어, 또 사전에 정의된 값 밖에 사용할 수 없다. 텍스쳐 애드레싱 명령은, 처리를 실행할 수가 있다. 예를 들어, 이러한 명령을 사용해, 샘플링 스테이지가 주소로서 사용하고 있는 텍스쳐 좌표를 수정하거나 보정 특수 효과를 유효하게 하거나 할 수 있다.

상세한 것에 대하여는, 「텍스쳐 애드레싱 명령」을 참조할것.


픽셀 쉐이더의 텍스쳐 애드레싱

다음의 그림은, 픽셀 쉐이더의 텍스쳐 애드레싱의 메카니즘을 나타내고 있다.

텍스쳐 처리와 관련해, 텍스쳐 좌표를 사용해, 4 개의 입력 텍스쳐를 샘플링 하는 것으로, 텍스쳐 레지스터 t0, t1, t2, 및 t3 를 결과적으로 얻을 수 있다. 텍스쳐 좌표와 텍스쳐 레지스터의 매핑은,D3DTSS_TEXCOORDINDEX 텍스쳐 스테이지 스테이트에 의해 제어된다. 디폴트에서는, 모든 텍스쳐 스테이지는 좌표 세트 0 으로부터 텍스쳐 좌표를 받는다. 명령은 이전의 텍스쳐 레지스터로부터의 결과 밖에 사용할 수 없기 때문에, 적절한 순서로 배치할 필요가 있다.

의존 텍스쳐를 사용하는 경우는, 임의의 텍스쳐를, 그것보다 큰 번호의 텍스쳐의 좌표 보정에 사용할 수 있다 (t1 를 사용해 t2 의 좌표를 보정하는 등).

Direct3DX 의 픽셀 쉐이더 어셈블러는, 텍스쳐 주소 연산자와 수식자의 양쪽 모두를 제공한다. 상세한 것에 대하여는, 「픽셀 쉐이더 어셈블러 레퍼런스」를 참조할것.

다음의 픽셀 쉐이더 코드는, 라이팅 베이스의 텍스쳐상에 범프 환경 맵을 프로그래밍 한 텍스쳐 주소 쉐이더를 나타내고 있다.

ps. 1.0              // DirectX8 버젼.
tex t0              // 텍스쳐를 선언한다.
tex t1              // 범프 맵을 선언한다.
texbem t3, t1       // 섭동, 다음에
                    // 환경 맵을 샘플링 한다.
mul r0, v0, t0      // 디퓨즈를 곱셈한다.
add r0, r0, t3      // 범프 스펙큐러 환경 맵을 추가한다.


픽셀 쉐이더의 라이팅

다음의 그림은, 픽셀 쉐이더의 라이팅의 메카니즘을 나타내고 있다.

예를 들어, 3D 범프 환경 맵의 경우, 법선 맵을 샘플링 해, 텍스쳐 좌표를 행으로서 사용해 다각형상에 3 × 3 행렬 연산을 보간 한다. 그 후, 디퓨즈 휘도 큐브 맵에 트랜스 폼 및 인덱스 하는지, 또는 스펙큐러 환경 큐브 맵에 반사 및 인덱스 할 수가 있다. 전의 패스로부터 베이스에 적용한다.


픽셀 쉐이더의 적용 범위

픽셀 쉐이더는, Microsoft® DirectX® 6.0 및 7.0 의 멀티 텍스쳐 어플리케이션 프로그래밍 인터페이스 (API)로 정의되고 있는 픽셀 블렌딩 기능, 특히 D3DTSS_COLOROP, D3DTSS_COLORARG1, D3DTSS_COLORARG2, D3DTSS_ALPHAOP, D3DTSS_ALPHAARG1, 및 D3DTSS_ALPHAARG2 텍스쳐 스테이지 스테이트에 의해 정의되는 처리, 및 관련하는 인수와 수식자에 완전하게 대신하는 것이다. 프로시쟈르피크세르시다가 설정되면(자), 이러한 스테이트는 무시된다.

픽셀 쉐이더의 적용 범위에 대한 자세한 것은, 다음의 각 주제에 기술되고 있다.

  • 픽셀 쉐이더와 텍스쳐 스테이지 스테이트
  • 픽셀 쉐이더와 텍스쳐 샘플링
  • 쉐이더 후의 픽셀 처리


픽셀 쉐이더와 텍스쳐 스테이지 스테이트

픽셀 쉐이더가 처리되고 있을 때, 다음의 텍스쳐 스테이지 스테이트는 계속해 보관 유지된다.

  • D3DTSS_ADDRESSU
  • D3DTSS_ADDRESSV
  • D3DTSS_ADDRESSW
  • D3DTSS_BUMPENVMAT00
  • D3DTSS_BUMPENVMAT01
  • D3DTSS_BUMPENVMAT10
  • D3DTSS_BUMPENVMAT11
  • D3DTSS_BORDERCOLOR
  • D3DTSS_MAGFILTER
  • D3DTSS_MINFILTER
  • D3DTSS_MIPFILTER
  • D3DTSS_MIPMAPLODBIAS
  • D3DTSS_MAXMIPLEVEL
  • D3DTSS_MAXANISOTROPY
  • D3DTSS_BUMPENVLSCALE
  • D3DTSS_BUMPENVLOFFSET
  • D3DTSS_TEXCOORDINDEX
  • D3DTSS_TEXTURETRANSFORMFLAGS

이러한 텍스쳐 스테이지 스테이트는 픽셀 쉐이더의 일부에서는 없기 때문에, 쉐이더의 컴파일시에는 사용하지 못하고, 드라이버는 그것들을 따라가고 되는 상정도 할 수 없다. 예를 들어, 드라이버는 그 시점에서는, 바이리니아피르타링과 트라이 리니어 필터 링을 구별할 수 없다. 어플리케이션은, 현재 바인드 되고 있는 쉐이더를 재생성하지 않아도, 이러한 스테이트를 자유롭게 변경할 수 있다.

게다가 사용되는 이미지 데이터를 변경하기 위해서 IDirect3DDevice8::SetTexture 메소드를 호출해도, 픽셀 쉐이더는 무효가 되지 않기 때문에, 비트 깊이에 관한 텍스쳐의 형식은 자유롭게 변경할 수 있다. D3DFMT_A8L8 나 D3DFMT_V8U8 라고 하는 2 채널 텍스쳐 포맷에서의 SetTexture 의 호출도, 3 번째의 채널이 0 으로 설정되어 있는 것과 같게, 계속 사용할 수 있다.


픽셀 쉐이더와 텍스쳐 샘플링

축소, 확대, 밉피르타링, 및 랩 addressing mode에 대해서는, 텍스쳐 샘플링 및 필터 링 처리는 표준 텍스쳐 스테이지 스테이트에 의해 제어된다. 상세한 것에 대하여는, 「텍스쳐 스테이지 스테이트」를 참조할것.

이 정보는 쉐이더의 컴파일시에 드라이버에 제공되지 않기 때문에, 이 스테이트가 바뀌어도 쉐이더는 처리를 속행할 수 있다. 텍스쳐 타입 (텍스쳐, 큐브 텍스쳐, 또는 볼륨 텍스쳐)은, 쉐이더의 구문에 명시적으로 지정한다. 어플리케이션은, 쉐이더의 실행중에 올바른 타입의 텍스쳐만을 설정해야 한다. 쉐이더의 실행중에 잘못한 타입의 텍스쳐를 설정 하면, 예기치 않은 결과가 발생하는 일이 있다.


쉐이더 후의 픽셀 처리

Microsoft® DirectX® 8.0 에서는, fog 블렌딩, 스텐실 처리, 렌더링 타겟 블렌딩이라고 하는 픽셀 처리는, 쉐이더의 실행 후에 실시한다. 렌더링 타겟 블렌딩의 구문은, 이 주제로 해설하도록(듯이), 새로운 기능을 지원 하기 위해서 갱신되고 있다.

픽셀 쉐이더 입력

DirectX 8.0 에서는, 텍스쳐 레지스터에 선언되는 모든 색 (디퓨즈색 및 스펙큐러색)은, 쉐이더로 사용하기 전에, 쉐이더에의 유효 입력의 범위의 0 에서 1 의 범위에 있는 (고정되고 있다)라고 보여진다. 위치 좌표는, 픽셀 쉐이더의 실행전에 클립 되고 있다고 보여진다.

픽셀 쉐이더는, 모든 보간값은 보간 된 퍼스펙티브 보정이다고 보지만, 이것은 모든 하드웨어로 보증되고 있는 것은 아니다. 주소 쉐이더에 의해 텍스쳐 좌표로서 생성된 색은, 항상 퍼스펙티브 보정의 방법으로 보간 된다. 그러나, 이것들은 보간의 사이에 0 ~ 1 의 범위에 고정된다.

픽셀 쉐이더 출력

픽셀 쉐이더에 의해 출력되는 결과는, 레지스터 r0 의 컨텐츠이다. 쉐이더의 처리가 종료한 시점에서 이 레지스터에 저장 되고 있는 데이터는, 항상 fog 스테이지 및 렌다링타겟트브렌다에 송신된다.


픽셀 쉐이더의 데이터 플로우

여기에서는, 픽셀 쉐이더의 가상 머신에 전송 되어 또 가상 머신으로부터 전송 되는 데이터 플로우에 대해 해설한다. 이하의 주제는, 픽셀 쉐이더의 개발 및 그 기초가 되는 가상 머신에 대해 상세하게 이해하는 것을 목적으로 해 기술되고 있다.

  • 픽셀 쉐이더 가상 머신에 대해
  • 픽셀 데이터의 처리


픽셀 쉐이더 가상 머신에 대해

다음의 그림은, 픽셀 쉐이더 가상 머신내에서의 논리 데이터 플로우를 나타내고 있다.

각 삼각형으로 보간 된 데이터는, 위에의도에 나타낸 것처럼 가상 머신에 전송 된다. 텍스쳐 좌표 및 칼라값은, 각 픽셀 마다 보간 된다. 텍스쳐 좌표의 매핑은,D3DTSS_TEXCOORDINDEX 텍스쳐 스테이지 스테이트를 설정해 제어한다. 예를 들어, 버텍스 쉐이더로부터의 oD0 데이터 출력이 삼각형상에서 보간 되어 개개의 픽셀의 결과가 픽셀 쉐이더의 v0 레지스터로 설정되는 등이다.


픽셀 데이터의 처리

픽셀 데이터가 가상 머신에 의해 어떻게 처리되는지를 이해하기 위해(때문에), 오렌지의 구(공)체를 상상해, 그것을 범프 맵 해, 라이트가 표면을 비추는 것 같은 환경가운데에 둔다고 한다. 이 단순한 시나리오로, 오렌지의 색이, 구(공)체를 형성하는 삼각형을 사용해 보간 된다고 한다. 오렌지의 색은, 버텍스 쉐이더의 oD0 채널에게 건네진 데이터로부터 보간 되기 (위해)때문에, 각 픽셀은 v0 레지스터를 사용해 픽셀 쉐이더에 제시된다.

다음의 주제에서는, 범프 맵 및 환경 맵의 데이터를 사용해, 오렌지의 구(공)체의 최종 이미지를 렌더링 하기 위해서 필요한 스텝을 해설한다.

  • 픽셀 쉐이더 가상 머신용의 데이터를 준비한다
  • 픽셀 쉐이더 가상 머신을 사용해 데이터를 송신한다
  • 픽셀 쉐이더 파이프라인의 처리 순서

여기에서는, 특정의 예를 사용해 픽셀 쉐이더 가상 머신이 데이터를 처리하는 방법을 나타내지만, 그 원칙과 순서는, 각종의 픽셀 쉐이더의 개발에 응용할 수 있다.


픽셀 쉐이더 가상 머신용의 데이터를 준비한다

오렌지의 구(공)체를 범프 맵과 환경 맵의 데이터로 렌더링 하기 전에, 범프 맵 및 환경 맵을 로드할 필요가 있다. 그 후 각 텍스쳐 처리 유니트에 해당하는 텍스쳐 스테이지 스테이트를 설정한다. 이것에는,D3DTSS_BUMPENVMAT00 ,D3DTSS_BUMPENVMAT01 ,D3DTSS_BUMPENVMAT10 ,D3DTSS_BUMPENVMAT11 , 및 D3DTSS_TEXCOORDINDEX 텍스쳐 스테이지 스테이트의 설정이 포함된다. 다만,D3DTSS_COLOROP 에 의해 정의되는 칼라 처리는 설정할 필요가 없다. 이것은, 픽셀 단위에 실행되는 처리의 정의에, 픽셀 쉐이더 코드가 사용되기 때문에 있다. 일반적으로, 삼각형, 오브젝트, 또는 프레임을 렌더링 하고 있는 동안에 일정한 상태를 유지하는 텍스쳐 스테이지 스테이트는, 픽셀 쉐이더 가상 머신을 호출하기 전으로 설정된다. 이것에는, 2 × 2 범프 맵핑 행렬값이 포함된다. 다만, 각 픽셀의 쉐이드에 사용되는 데이터는, 픽셀 쉐이더 언어를 사용해 지정된다.

이 예에서는, 버텍스 쉐이더내에서 발생하는 프론트엔드 처리에 대해서는 접하지 않았다. 그 대신해, 프론트엔드가 텍스쳐 보간을 설정하는 것으로써, 범프 데이터가 버텍스 쉐이더의 oT0 채널을 개입시켜 건네받으면(자) 전제 한다. 이것은, 오렌지의 구(공)체의 예에서는, 범프 데이터에의 액세스에 사용되는 범프 맵 주소가, 픽셀 쉐이더의 최초의 텍스쳐 좌표 레지스터 (t0)로 설정되는 것을 의미한다. 같이 라이트 맵 주소는, 텍스쳐 처리 유니트로 변경을 하기 전에, 버텍스 쉐이더의 oT1 채널로부터 t1 를 개입시켜 픽셀 쉐이더에게 건네진다.


픽셀 쉐이더 가상 머신을 사용해 데이터를 송신한다

스테이지 0 의 텍스쳐 처리에 사용되는 주소는, 최초의 텍스쳐 좌표 레지스터 (t0)를 개입시켜 제시되는 범프 맵 주소가 된다. 처리는, 다음의 픽셀 쉐이더 코드에 나타내도록(듯이), 범프 데이터의 단순한 참조이다.

tex t0

스테이지 1 의 텍스쳐 처리는 보다 복잡하다. 이 경우에는, 2 × 2 행렬이 로드 되도록(듯이) 텍스쳐 스테이지 스테이트를 설정할 필요가 있다. 여기서, 시점과 광원의 사이의 변경을 시뮬레이트 하기 위해서 로드할 수 있는 2 × 2 행렬이 있는 것에 주목한다. 이것에 의해, 장면내에서 시점이 이동할 때, 범프 맵 및 환경 맵을 재이용할 수가 있다. 이 때문에, 환경 맵에의 주소는, 2 번째의 텍스쳐 좌표인 t1 를 개입시켜 제시된 베이스 주소가, 시점 조정 및 로컬 범프값에 의해 곱셈된 것이 된다. 보다 정확하게는, 환경 맵에의 u 좌표는 u = t1.r + mat00 * t0.r + mat01 * t0.g 이며, 환경 맵에의 v 좌표는 v = t1.g + mat10 * t0.r + mat11 * t0.g 가 된다. t0.r 및 t0.g 레지스터 성분의 값은, 실제로는 du 및 dv 의 값이며, 스테이지 0 에서의 범프 데이터 참조를 나타내, 레지스터 t0 에 저장 된다.

주 u 및 v 주소의 계산에는, 실제의 픽셀 쉐이더 코드내에 2 개의 슬롯을 필요로 하는 경우가 있다. 이것은, 대부분의 하드웨어가, u 의 논리를 재이용해, 그 후 v 주소 계산을 재이용하기 위해(때문에)이다. 현재의 하드웨어에서는, 주소를 패러렐로 계산할 수 없다.

다음의 예에서는, 이것을 픽셀 쉐이더 코드내에서 실행하는 방법을 나타내고 있다.

ps. 1.0         // DirectX8 버젼.
tex t0         // 텍스쳐 (범프 데이터)를 선언한다.
texbem t1, t0  // 환경 맵을 선언해, t0 로부터 데이터를 취득한다.
mov r0, v0     // 디퓨즈색의 오렌지색이
               // 각 픽셀의 레지스터 v0 를 개입시켜 픽셀 쉐이더에
               // 건네받고 있다고 하는 가정에 주의 해야 한다.
add r0, r0, t1 // 스펙큐러 환경 데이터를 추가한다.

이것은 매우 단순한 예이며, 많은 경우에 적용할 수 있는 것은 아니다. 보통은, 범프 환경 매핑의 실행전에 베이스 텍스쳐가 오브젝트에 적용된다. 예를 들어, 텍스쳐 데이터를 적용하기 위한 베이스로서 흰 구(공)체등을 보낸다. 이것은, 표면 위에의 있는 부분에서는 밝고, 어느 부분에서는 약간 어두운 디퓨즈 라이트이다. 이 경우, 스테이지로부터 범프 환경 매핑 처리를 제외해, 베이스 텍스쳐를 디퓨즈 라이트에 의해 곱셈한다. 다음의 예에서는, 이것을 픽셀 쉐이더 코드내에서 실행하는 방법을 나타내고 있다.

ps. 1.0         // DirectX8 버젼
tex t0         // 베이스 텍스쳐를 선언한다. 대리석, 목재, 그 외의 표면 머트리얼 등,
               // 임의의 것을 선언할 수 있다.
tex t1         // 텍스쳐 (범프 데이터)를 선언한다.
texbem t2, t1  // 환경 맵을 선언한다.
mul r0, v0, t0 // 디피즈라이트로 베이스 텍스쳐를 곱셈한다.
add r0, r0, t2 // 스펙큐러 환경 데이터를 추가한다.

종래의 텍스쳐 매핑 (1 스테이지)을 사용해, 스펙큐러를 보간 해, 픽셀 쉐이더 가상 머신의 레지스터 v1 를 개입시켜 이용할 수 있도록(듯이) 하는 것이 추천 된다. 그 외의 복잡한 픽셀 쉐이더는, 정수 레지스터 (c0~c7)에 저장 되고 있는 일련의 고정 정수를 사용해 구축할 수 있다. 또, 텍스쳐 레지스터는 많은 경우 텍스쳐 스테이지와 함께 사용되지만, 픽셀 연산 논리 단위 (ALU)에의 읽고 쓰기이다. 이 때문에 픽셀 쉐이더는, 텍스쳐 레지스터를 텐포라리레지스타로서 사용할 수 있다. 또, r0 및 r1 는 ALU 에의 읽고 쓰기이지만, r0 에 저장 되는 결과는, 깊이 및 스텐실 논리에 출력할 수 있는 유일한 결과이다. 사실, 결과를 스트림에 건네주는 유일한 방법은, r0 레지스터를 사용하는 것이다.


픽셀 쉐이더 파이프라인의 처리 순서

픽셀 쉐이더 파이프라인의 스테이트는, 렌더링 스테이트 및 텍스쳐 스테이지 스테이트를 설정해,IDirect3DDevice8::SetTexture ,IDirect3DDevice8::SetTextureStageState ,IDirect3DDevice8::SetPixelShader , 및 IDirect3Ddevice8::SetPixelShaderConstant 메소드를 호출하는 것으로, 그 실행시 전체에 걸쳐서 제어할 수 있다. 이러한 스테이트 및 함수는, 픽셀 쉐이더의 제어 플로우, 및 픽셀 쉐이더 파이프라인의 각 스텝의 스테이트를 지정한다. 다음의 그림은, 이러한 스텝의 순서, 및 각 스텝을 직접 제어하는 설정을 나타내고 있다.

SetPixelShader 에게 건네지는 핸들의 값에 응해, 고정 기능 또는 픽셀 쉐이더 파이프라인중 한쪽이 1 개의 인스턴스로 사용되지만, 그 양쪽 모두가 사용될 것은 없다. 수치에 의해 나타나는 시간이 되기 전에, 스텐실 테스트를 하는 일이 있지만, 이것에 의해 칼라 파이프라인의 결과에 영향이 나올 것은 없다. 쉐이딩 알고리즘으로 처리를 진행시키는 중, 값을 고정할 수 있는 각종 파이프라인 처리가 존재하는 것에 주의한다.


픽셀 쉐이더의 사용법

여기에서는, 어플리케이션내에서의 픽셀 쉐이더의 사용 방법에 대해 설명한다.

  • 픽셀 쉐이더 지원의 확인
  • 픽셀 쉐이더 텍스쳐 입력의 설정
  • 픽셀 쉐이더 정수 레지스터의 설정
  • 픽셀 쉐이더의 컴파일
  • 픽셀 쉐이더의 생성


픽셀 쉐이더 지원의 확인

D3DCAPS8 의 멤버를 조회해, 픽셀 쉐이더에 관한 처리의 지원 레벨을 확인할 수가 있다. 다음의 표는, Microsoft® DirectX® 8.0에서의 프로그램 가능한 픽셀 처리에 관련하는 디바이스 기능을 나타내고 있다.

디바이스 기능 | 설명
MaxPixelShaderValue | 픽셀 쉐이더의 산술 컴퍼넌트의 최대치.
MaxSimultaneousTextures | 지원 되는 텍스쳐 선언 명령의 수.
MaxTextureBlendStages | 지원 되는 명령의 수.
PixelShaderVersion | 픽셀 쉐이더의 지원 레벨.

MaxSimultaneousTextures 및 MaxTextureBlendStages 능력은, 고정 기능 픽셀 블렌딩 (멀티 텍스쳐를 사용)에게만 적용된다.

PixelShaderVersion 기능은, 픽셀 쉐이더의 지원 레벨을 나타낸다. IDirect3DDevice8::CreatePixelShader 메소드를 호출했을 때, 이 값이하의 버젼 번호를 가지는 픽셀 쉐이더만 정상적으로 생성 된다. 주된 버젼 번호는,PixelShaderVersion 의 세컨드 바이트에 encode 된다. 하위 바이트에는, 마이너 버젼의 번호가 포함된다. 픽셀 쉐이더의 버젼은, 각 쉐이더의 최초의 토큰에 의해 나타난다.

픽셀 쉐이더 어플리케이션은,MaxSimultaneousTextures 및 MaxTextureBlendStages 디바이스 능력을 체크할 필요가 없다.

각 이행은, 완전하게 지원 할 수 있는 최대의 픽셀 쉐이더 버젼을 나타내는 PixelShaderVersion 멤버를 설정한다. 이 때문에,PixelShaderVersion 에 의해 제시된 버젼 이하의 쉐이더의 생성이 실패할 것은 없다.

다음의 표는, 지원 되고 있는 픽셀 쉐이더의 버젼, 및 관련하는 기능 레벨과 레지스터 카운트를 나타내고 있다.

버젼 | 기능 | tn | rn | cn | vn
1.0 | DirectX 8.0 | 4 | 2 | 8 | 2
1.1 | DirectX 8.0 | 4 | 2 | 8 | 2

버젼 1.0 은, 픽셀 쉐이더의 레퍼런스의 「명령」에 기재되는 모든 처리를 지원 하고 있다. 최대 4 개의 텍스쳐 주소 처리, 및 합계 8 개의 명령이 지원 된다. 이 버젼의 경우, 텍스쳐 레지스터의 tn 는 읽어내 전용이며, 지정된 명령내에서는 이 텍스쳐 레지스터만 사용할 수 있다.

버젼 1.1 에서는, 최대 4 개의 주소 처리, 및 8 개의 블렌딩 처리를 지원 하고 있다. 이 버젼의 경우, 텍스쳐 레지스터는 읽어/써 가능하고, 그 2 개(살)을 단일의 명령내에서 입력으로서 사용할 수 있다.


픽셀 쉐이더 텍스쳐 입력의 설정

입력 레지스터색과 텍스쳐 스테이지의 사이에는, 직접 매핑이 존재한다. Direct3DX 픽셀 쉐이더 어셈블러의 텐포라리레지스타는, 대응하는 텍스쳐 스테이지로부터의 텍스쳐 칼라와 함께 프리로드 된다. 이것에 대해, 텍스쳐는,IDirect3DDevice8::SetTexture 메소드를 호출하는 것에 의해 텐포라리레지스타에 직접 바인드 된다.

또 텍스쳐 좌표는, 직접 맵 되어 텍스쳐 선언에 의해 정의된다.


픽셀 쉐이더 정수 레지스터의 설정

다음의 메소드를 사용해, 픽셀 쉐이더 정수 레지스터에 대한 값의 설정 및 읽기를 실시할 수가 있다.

  • IDirect3DDevice8::GetPixelShaderConstant
  • IDirect3DDevice8::SetPixelShaderConstant

또,def Direct3DX 어셈블러 명령을 사용해, 픽셀 쉐이더의 정수 레지스터를 설정할 수도 있다.


픽셀 쉐이더의 컴파일

Direct3DX 유틸리티 라이브러리에는, 픽셀 쉐이더를 컴파일하기 위한 일련의 함수가 준비되어 있다. 사용할 수 있는 함수는 다음과 같다.

  • D3DXAssembleShader
  • D3DXAssembleShaderFromFileA
  • D3DXAssembleShaderFromFileW


픽셀 쉐이더의 생성

Microsoft® DirectX® 8.0 으로 픽셀 쉐이더를 생성 하려면 ,IDirect3DDevice8::CreatePixelShader 메소드를 사용한다. 이 메소드에는, 블렌딩 처리를 정의하는 선언을 건네준다. Microsoft Direct3D® 는, 쉐이더의 핸들을 돌려준다. 쉐이더는,CreatePixelShader 가 불려 갈 때 타당성이 검증된다.

DirectX 8.0 하드웨어 모델의 제한에 의해, 지정된 쉐이더의 생성에 실패하는 일도 있다.


픽셀 쉐이더의 예

여기에서는, 픽셀 쉐이더 코드에 이행 되고 있는 일반적인 이펙트에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 디퓨즈 라이팅
  • 스펙큐러 매핑
  • 디퓨즈 라이팅과 스펙큐러 매핑
  • 내적 라이팅
  • 픽셀 쉐이더의 샘플


디퓨즈 라이팅

다음의 쉐이더는, 픽셀 단위의 디퓨즈 라이팅을 실행한다. 디퓨즈 강도를 계산하려면 ,dp3 명령을 사용한다.

ps. 1.0                      // DirectX8 버젼.
tex t0                      // 법선 맵을 선언한다.
texm3x3pad t1, t0_bx2       // 1 행 째트랜스 폼.
texm3x3pad t2, t0_bx2       // 2 행 째트랜스 폼.
texm3x3tex t3, t0_bx2       // 3 행 째트랜스 폼.
dp3_sat r0, t3_bx2, v0_bx2


스펙큐러 매핑

다음의 쉐이더는, 픽셀 단위의 스펙큐러 매핑을 실행한다.

ps. 1.0                   // DirectX8 버젼.
tex t0                   // 법선 맵을 선언한다.
texm3x3pad   t1, t0      // 1 행 째트랜스 폼.
texm3x3pad   t2, t0      // 2 행 째트랜스 폼.
texm3x3spec  t3, t0, c0  // 3 행 째트랜스 폼. 다음에 공간을 반사시켜,
                         // 큐브 맵을 샘플링 한다.

mov r0, t3               // 후레임밧파브렌다에 보낸다.
                         // 이것은 frame buffer의 내용에 추가된다.


디퓨즈 라이팅과 스펙큐러 매핑

다음의 쉐이더의 편성은, 픽셀 단위의 디퓨즈 라이팅과 스펙큐러 매핑을 실행한다.

ps. 1.0                // DirectX8 버젼.
tex t0                // 법선 맵을 선언한다.
texm3x3pad  t1, t0    // 1 행 째트랜스 폼.
texm3x3pad  t2, t0    // 2 행 째트랜스 폼.
texm3x3spec t3, t0    // 3 행 째트랜스 폼. 디퓨즈 큐브 맵을 t2 에,
                      // 스펙큐러 큐브 맵을 t3 에 샘플링 한다.
mov r0, t3            // 스펙큐러색을 출력한다.


내적 라이팅

내적에는 부호 첨부 데이터가 필요하기 때문에,_bx2 인수 수식자를 사용해 입력 데이터를 변환할 필요가 있다. 라이팅은,_sat 명령 수식자를 사용해 부의 값을 고정한다.

// 디피즈는 라이트의 방향이다.

ps. 1.0      // DirectX8 버젼.
tex t0      // 법선 맵.
dp3_sat r0, t0_bx2, v0_bx2


픽셀 쉐이더의 샘플

MFCPixelShader 샘플은, 다른 픽셀 쉐이더가 렌더링 대상의 장면에 사용하는 이펙트를 나타낸다. 이 샘플에는, 미리 정의되고 있는 6 개의 쉐이더가 있어, 이러한 안으로부터 선택해 픽셀 쉐이더를 변경하는 것으로, 다른 결과를 얻을 수 있다.


포인트 스프라이트

여기에서는, 포인트 스프라이트에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 포인트 스프라이트란
  • 포인트 프리미티브의 렌더링 제어
  • 포인트 사이즈의 계산
  • 포인트 렌더링


포인트 스프라이트란

Microsoft® Direct3D® for Microsoft DirectX® 8.0 에서는, 포인트 스프라이트가 지원 되고 있기 (위해)때문에, 포인트 (입자 시스템)의 고성능 렌더링이 가능하다. 포인트 스프라이트란, 임의의 형상을 텍스쳐로 정의된 것처럼 렌더링 할 수 있도록(듯이) 하는, 일반화된 범용 포인트이다.

포인트 스프라이트는, 고정 기능 지오메트리 파이프라인에서는 지원되어 있지 않다. 포인트 스프라이트를 사용하려면 , 프로그램 가능한 버텍스 처리를 사용할 필요가 있다.


포인트 프리미티브의 렌더링 제어

Microsoft® Direct3D® for Microsoft DirectX® 8.0 은, 포인트 스프라이트 (포인트 프리미티브)의 렌더링을 제어하기 위한 추가 파라미터를 지원 하고 있다. 이러한 파라미터에 의해, 포인트에 가변 사이즈를 설정할 수 있어 텍스쳐 맵 전체를 적용할 수가 있다. 각 포인트의 사이즈는, 어플리케이션으로 지정된 사이즈와 Direct3D 가 계산하는 거리 베이스의 함수를 조합해 결정된다. 어플리케이션은, 포인트 사이즈를 버텍스 마다 설정할 수도 있어 또, 버텍스 마다는 설정을 실시하지 않고,D3DRS_POINTSIZE 를 설정해 포인트에 적용할 수도 있다. 포인트 사이즈는 카메라 공간 단위로 표현된다. 다만, 어플리케이션이 트랜스 폼 후의 유연한 버텍스 포맷 (FVF) 버텍스를 건네주고 있을 때는, 거리 베이스의 함수는 적용되지 않고, 포인트 사이즈는 렌더링 타겟 위에의 픽셀의 단위로 표현된다.

포인트의 렌더링시에 계산되고 사용되는 텍스쳐 좌표는,D3DRS_POINTSPRITEENABLE 의 설정에 따라서 다르다. 이 값이 TRUE 로 설정되어 있는 경우는, 각 포인트가 텍스쳐 전체를 표시하도록(듯이) 텍스쳐 좌표가 설정된다. 이것은 일반적으로, 포인트가 1 픽셀보다 매우 큰 경우에만 사용한다. D3DRS_POINTSPRITEENABLE 가 FALSE 로 설정되어 있는 경우는, 각 포인트의 버텍스 텍스쳐 좌표가 포인트 전체에 사용된다.


포인트 사이즈의 계산

포인트 사이즈는 D3DRS_POINTSCALEENABLE 에 의해 결정된다. 이 값이 FALSE 로 설정되어 있는 경우는, 어플리케이션으로 지정된 사이즈가 스크린 공간 (트랜스 폼 후) 사이즈로서 사용된다. 스크린 공간에서 Microsoft® Direct3D® 에게 건네지는 버텍스는, 포인트 사이즈가 계산되지 않고, 지정된 포인트 사이즈가 스크린 공간의 사이즈로서 해석된다.

D3DRS_POINTSCALEENABLE 가 TRUE 의 경우는, Direct3D 가, 다음의 식에 따라 스크린 공간의 포인트 사이즈를 계산한다. 어플리케이션으로 지정된 포인트 사이즈는, 카메라 공간 단위로 표현된다.

Ss = Vh * Si * sqrt(1/(A + B*De + C*(De2)))

이 식안의 입력 포인트 사이즈 Si 는, 버텍스마다의 값인가, 또는 D3DRS_POINTSIZE 렌더링 스테이트의 값이다. 포인트 스케일 계수 D3DRS_POINTSCALE_A ,D3DRS_POINTSCALE_B , 및 D3DRS_POINTSCALE_C 는, 포인트 A,B, 및 C 에 의해 나타내진다. 뷰 포토 Vh 의 높이는, 뷰 포토를 나타내는 D3DVIEWPORT8 구조체의 Height 멤버이다. 시점에서 위치 좌표에의 거리 (원점의 눈) De 는, 포인트 (Xe, Ye, Ze)의 시점 공간 위치를 잡아, 다음의 처리를 실행하는 것에 의해 계산된다.

De = sqrt (Xe2 + Ye2 + Ze2)

최대 포인트 사이즈 Pmax 는,D3DCAPS8 의 MaxPointSize 멤버 또는 D3DRS_POINTSIZE_MAX 렌더링 스테이트의 어느 쪽인지 작은 (분)편을 취해 결정된다. 최소 포인트 사이즈 Pmin 는,D3DRS_POINTSIZE_MIN 의 값을 조사하는 것에 의해 결정된다. 즉, 최종적인 스크린 공간 포인트 사이즈 S 는 다음의 규칙에 따라 결정된다.

  • Ss > Pmax 라면 S = Pmax
  • Ss < Pmin 라면 S = Pmin
  • 그 이외의 경우는 S = Ss


포인트 렌더링

스크린 공간 사이즈 S 의 스크린 공간 포인트

P = (X, Y, Z, W)

(은)는, 다음의 4 개의 버텍스를 가지는 사변형으로서 라스터화 된다.

((X+S/2, Y+S/2, Z, W), (X+S/2, Y-S/2, Z, W), (X-S/2, Y-S/2, Z, W), (X-S/2, Y+S/2, Z, W))

버텍스 칼라 속성은 버텍스 각각으로 복제되기 (위해)때문에, 각 포인트는 항상 정수 칼라로 렌더링 된다.

텍스쳐 인덱스의 할당은,D3DRS_POINTSPRITEENABLE 렌더링 스테이트 설정에 의해 제어된다. D3DRS_POINTSPRITEENABLE 가 FALSE 로 설정되어 있는 경우는, 버텍스 텍스쳐 좌표는 버텍스 각각으로 복제된다. D3DRS_POINTSPRITEENABLE 가 TRUE 로 설정되어 있는 경우는, 4 개의 버텍스의 텍스쳐 좌표는 다음의 값으로 설정된다.

(0. F, 0. F), (0. F, 1. F), (1. F, 0. F), (1. F, 1. F)

이것을 다음의 그림에 나타낸다.

클리핑이 유효하게 되고 있는 경우는, 다음의 규칙에 따라 포인트가 클리핑 된다. 장면이 렌더링 되는 깊이의 범위 (D3DVIEWPORT8 구조체의 MinZ 및 MaxZ)를 버텍스가 넘고 있는 경우, 포인트는 시추대의 밖에 존재해, 렌더링 되지 않는다. 포인트 사이즈를 생각에 넣어, 포인트가 완전하게 X 및 Y 의 뷰 포토의 밖에 존재하는 경우, 그 포인트는 렌더링 되지 않고, 나머지의 포인트는 렌더링 된다. 포인트의 위치가 X 또는 Y 의 뷰 포토의 밖에 있어도, 부분적으로 표시할 수 있는 경우가 있다.

포인트는, 유저 정의 클립면에 올바르고 클립 되는 경우도 있어, 그렇지 않은 경우도 있다. D3DCAPS8 의 PrimitiveMiscCaps 멤버내에서 D3DPMISCCAPS_CLIPPLANESCALEDPOINTS 가 설정되어 있지 않은 경우, 포인트는, 버텍스 위치에만 기초를 두어, 포인트 사이즈는 무시해, 유저 정의 클립면에 클립 된다. 이 때, 스케일링 된 포인트는, 버텍스 위치가 클립면안에 있는 경우는 완전하게 렌더링 되어 버텍스 위치가 클립면의 밖에 있는 경우는 파기된다. 어플리케이션에서는, 최대 포인트 사이즈와 같은 크기의 경계 지오메트리를 클립면에 추가하는 것으로, 부자연스러운 효과의 발생을 막을 수가 있다.

D3DPMISCCAPS_CLIPPLANESCALEDPOINTS 비트가 설정되어 있는 경우는, 스케일링 된 포인트는, 유저 정의 클립면에 정확하게 클립 된다.

하드웨어 버텍스 처리는, 포인트 사이즈를 지원 하고 있는 경우도 있어, 그렇지 않은 경우도 있다. 예를 들어,D3DCAPS8 구조체의 MaxPointSize 멤버가 1.0 또는 0.0 으로 설정되어 있는,HAL 디바이스 (D3DDEVTYPE_HAL) 위에의 D3DCREATE_HARDWARE_VERTEXPROCESSING 로 디바이스를 생성 하면, 모든 포인트는 단일 픽셀이 된다. 1.0 보다 작은 픽셀 포인트 스프라이트를 렌더링 하려면 , 유연한 버텍스 포맷 (FVF) TL (트랜스 폼이 끝난 라이팅이 끝난) 버텍스, 또는 소프트웨어 버텍스 처리 (D3DCREATE_SOFTWARE_VERTEXPROCESSING)를 사용할 필요가 있어, 이 경우 Microsoft® Direct3D® 런타임이 포인트 스프라이트 렌더링을 에뮤레이트 한다. FVF TL 버텍스의 상세한 것에 대하여는, 「트랜스 폼이 끝난 라이팅 끝난 버텍스의 기능」을 참조할것.

버텍스 처리를 실행해 (MaxPointSize 가 1.0f 보다 큰 값으로 설정된) 포인트 스프라이트를 지원 하는 하드웨어 디바이스는, 트랜스 폼 되지 않는 스프라이트의 사이즈 계산에 필요하고, 또 TL 버텍스의 버텍스마다 또는 D3DRS_POINTSIZE 의 설정을 올바르게 실시하기 위해서(때문에)도 필요하다.


버텍스 쉐이더

여기에서는, 버텍스 쉐이더에 대해 해설해, Microsoft® Direct3D® 어플리케이션내에서의 사용 방법을 설명한다. 설명하는 주제는, 다음과 같다

  • 버텍스 쉐이더란
  • 버텍스 쉐이더의 원가요소
  • 버텍스 쉐이더의 사용법
  • 버텍스 쉐이더의 테크닉과 어플리케이션
  • 버텍스 쉐이더의 예

이 문서내에서 사용 떠날 수 있어 모든 버텍스 쉐이더 코드 및 구문은, Direct3DX 버텍스 쉐이더 어셈블러에 따르고 있어 호환성이 있다. 이 섹션을 읽기 전에, 「버텍스 쉐이더 어셈블러 레퍼런스」를 읽어, 버텍스 쉐이더 어셈블러에 대한 지식을 취득해 둘 필요가 있다.


버텍스 쉐이더란

버텍스 쉐이더는, 버텍스의 로드와 처리를 제어한다. Microsoft® Direct3D® for Microsoft DirectX® 8.0 에서는, 프로그램 가능한 버텍스 처리 및 고정 기능 버텍스 처리의 2 종류의 버텍스 처리를 지원 하고 있다. DirectX 8.0 의 문서에서는, 「버텍스 쉐이더」라고 하면(자) 주로 프로그램 가능한 모드에 적용되지만, 버텍스 쉐이더 API 기구에서는, 어느 쪽의 타입도 사용할 수 있다. 버텍스 쉐이더는, 생성 시에, 프로그램 가능한 버텍스 처리를 사용하든가 또는 고정 기능 버텍스 처리를 사용할까 정의된다. 생성 후는, 버텍스 쉐이더 자신의 핸들에 의해 참조된다. 버텍스 쉐이더를 편집할 수 없다. 버텍스 쉐이더를 변경하려면 , 일단 파기해 다시 만들 필요가 있다.

각 버텍스 쉐이더에는 함수가 1 개 포함되어 있어 이것에 의해 각 버텍스에 적용하는 처리가 정의된다. 또 선언도 1 개 포함되어 있어 이것에 의해, 입력 데이터 스트림내의 버텍스 요소가 쉐이더에 의해 어떻게 사용될까 등, 쉐이더에의 입력이 정의된다.

버텍스 쉐이더에 의해 실행되는 버텍스 처리에는, 단일의 버텍스에 적용되는 처리만이 포함된다. 버텍스 처리 순서에 의해 얻을 수 있는 출력은, 개개의 버텍스 마다 정의되어 각각, 클립 공간 위치 (x, y, z, w), 색, 텍스쳐 좌표, fog 강도, 및 포인트 사이즈 정보가 포함된다. 이러한 위치 좌표로부터 뷰 포토에의 투영과 매핑, 복수의 버텍스로부터 프리미티브에의 어셈블(assemble), 및 프리미티브의 클리핑은, 후의 처리 단계에 의해 실행되어 버텍스 쉐이더의 제어하에는 없다.

고정 기능 버텍스 처리는, 트랜스 폼, 라이팅, 버텍스 블렌딩, 텍스쳐 좌표 생성을 포함해 Direct3D for DirectX 7.0 으로 같은 기능을 제공한다. 프로그램 가능한 버텍스 쉐이더에서는, 버텍스에 적용되는 처리가 쉐이더내에서 정의되는데 대해, 고정 기능 버텍스 처리는, 라이트나 트랜스 폼등을 설정하는 IDirect3DDevice8 의 메소드에 의해 설정된 디바이스 스테이트에 의해 제어된다. 그러나, 기능이 고정되고 공유되고 있는 경우에서도, 선언은 변경할 수 있기 (위해)때문에, 복수의 고정 기능 버텍스 쉐이더를 사용하는 일도 유용하다. 이것에 의해, 고정 기능 쉐이더에, 다른 멀티 스트림 입력의 레이아웃을 제공할 수가 있다.

고정 기능 버텍스 처리의 입력 버텍스 요소의 시멘틱스는 고정되고 있다. 이 때문에, 선언 태그에 의해, 입력 버텍스 요소가, 좌표, 법선, 색등으로 해서 지정된다. 고정 기능 버텍스 쉐이더의 버텍스 출력에는 항상, 픽셀 처리를 위한 현재의 디바이스 스테이트 설정으로 필요하게 되는, 좌표, 디퓨즈색, 스펙큐러색, 복수의 텍스쳐 좌표가 포함된다.

프로그램 가능한 버텍스 쉐이더에는, 각 버텍스에 적용되는 명령의 배열에 의해 정의된 함수가 1 개 포함된다. 입력 버텍스 요소로부터 프로그램 가능한 버텍스 쉐이더의 버텍스 입력 레지스터에의 매핑은, 쉐이더 선언으로 정의되지만, 입력 버텍스 요소는, 그 사용에 대해 특정의 시멘틱스를 가지지 않는다. 입력 버텍스 요소의 해석은, 쉐이더의 명령에 따른다. 프로그램 가능한 버텍스 쉐이더의 버텍스 출력은, 쉐이더 함수내의 명령에 의해 명시적으로 기입해진다.

Direct3DX 버텍스 쉐이더 어셈블러의 상세한 것에 대하여는, 「버텍스 쉐이더 어셈블러 레퍼런스」를 참조할것.


버텍스 쉐이더의 원가요소

여기에서는, 버텍스 쉐이더의 원가요소에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 버텍스 쉐이더 선언
  • 버텍스 쉐이더 함수


버텍스 쉐이더 선언

버텍스 쉐이더의 선언 부분에서는, 쉐이더의 정적인 외부 인터페이스를 정의하고 있다. 버텍스 쉐이더 선언에는 다음의 정보가 포함된다.

  • 버텍스 쉐이더 입력 레지스터에 대한 스트림 데이터의 바인드. 이 정보에 의해, 각 데이터 스트림내의 각 요소의 타입과 버텍스 입력 레지스터 할당이 정의된다. 이 타입에 의해, 산술 데이터형 및 디멘션 (값 1, 2, 3, 4)이 지정된다. 4 개보다 적은 값의 스트림 데이터 요소는, 0 개, 1 개, 또는 복수개의 0. F 값과 1 개의 1. F 값에 의해 4 개의 값에 확장된다.
  • 버텍스 쉐이더 입력 레지스터로부터, 프리미티브 테셀레이트의 비명시적 데이터에의 바인드. 이것에 의해, 스트림으로부터 로드 되므로 없고, 버텍스 쉐이더의 전에 행해지는 프리미티브의 테셀레이션중에 생성되는 버텍스 데이터의 로드가 제어된다.
  • 쉐이더가 현재의 쉐이더로서 설정될 때의 정수 메모리의 데이터의 로드. 각 토큰은, 1 개(살) 또는 복수가 연속하는 4-DWORD 정수 레지스터의 값을 지정한다. 이것에 의해, 쉐이더는, 정수 메모리의 임의의 서브 세트를 갱신해, 정수 메모리의 현재의 값을 저장 하고 있는 디바이스 스테이트를 덧쓰기할 수가 있다. 이러한 값은, 쉐이더가 IDirect3DDevice8::SetVertexShaderConstant 메소드를 개입시켜 디바이스에 바인드 되고 있을 때, DrawPrimitive 호출동안에 덧쓰기할 수 있다.

선언 배열은, 각각이 1 개(살) 또는 복수의 DWORD 인 토큰이 복수 모여 구성된 DWORD 의 1 차원 배열이다. 1-DWORD 토큰값 0xFFFFFFFF 는, 선언 배열의 말미를 나타내는 특별한 토큰이다. 1-DWORD 토큰값 0x00000000 는, 패딩 토큰이며, 선언의 해석시에는 무시된다. 이 패딩 토큰에 의해, 선언내에서 보다 복잡한 편집을 실행할 수 있다. 복수어의 토큰의 제 1 DWORD 에 계속되는 DWORD 에 대해서 0x00000000 는 유효한 값이다.

다음의 샘플 코드에서는, 선언을 기술하고 있다. 이 예에서는, 단순한 구조를 사용해 버텍스를 정의하는 방법을 나타내고 있다.

struct Vertex
{
    D3DXVECTOR3 Position;
    D3DXVECTOR3 Normal;
    D3DCOLOR    Diffuse;
    D3DXVECTOR2 TexCoord0;
};

다음의 샘플 코드는, 위의 같은 버텍스 구조를 선언 자식으로 정의하는 방법을 나타내고 있다.

DWORD dwDecl[] =
{
    D3DVSD_STREAM( 0 ),
    D3DVSD_REG( D3DVSDE_POSITION,  D3DVSDT_FLOAT3 ),
    D3DVSD_REG( D3DVSDE_NORMAL,    D3DVSDT_FLOAT3 ),
    D3DVSD_REG( D3DVSDE_DIFFUSE,   D3DVSDT_D3DCOLOR ),
    D3DVSD_REG( D3DVSDE_TEXCOORD0, D3DVSDT_FLOAT2 ),
    D3DVSD_END()
};

DWORD dwFvf = D3DFVF_POSITION | D3DFVF_NORMAL | D3DFVF_DIFFUSE |
              D3DFVF_TEX0 | D3DFVF_TEXCOORDSIZE2(0);

선언자는 데이터 스트림을 0 으로 설정해, 3 개의 float 형의 값으로 구성되는 위치 좌표와 법선 벡터를 정의해, 4 성분 부호 없음 바이트로 구성되는 디퓨즈 성분을 정의해, 2 개의 float 형의 값으로 구성되는 텍스쳐 좌표의 조를 정의한다.

고정 기능 버텍스 쉐이더를 사용할 때, 버텍스 입력 레지스터의 매핑은 고정된다. 이것에 의해, 위치 좌표나 법선이라고 하는 특정의 버텍스 요소는 버텍스 입력 메모리내의 특정의 레지스터 위치에 놓여질 필요가 있다. 이러한 할당은, FVF 코드가 IDirect3DDevice8::SetVertexShader 에게 건네질 때 자동적으로 실행된다. 명시적인 쉐이더 선언을 사용하는 경우는,D3DVSDE 프리프로세서 매크로가, 특정의 요소의 로드처가 되는 버텍스 입력 위치를 정의한다. 선언 토큰 배열의 생성에 사용하는 매크로의 정의에 대해서는, D3d8types.h 를 참조할것.

쉐이더 선언 토큰 타입과 비트 정의에 대해서는, 「버텍스 쉐이더 선언자 매크로」를 참조할것.

주 고정 기능 버텍스 쉐이더를 사용할 때는,IDirect3DDevice8::SetStreamSource 의 버텍스 보폭 세트와 버텍스 사이즈가 같은 사이즈가 아니면 안된다. 선언을 사용하는 버텍스 쉐이더의 경우는, 스트림 보폭은 선언 보폭보다 커도 상관없다.


버텍스 쉐이더 함수

버텍스 쉐이더의 함수 부분에서는, 각 버텍스에 적용되는 처리를 정의하고 있다. 쉐이더 함수는, 프로그램 가능한 버텍스 쉐이더 밖에 없다. 선언과 같이, 쉐이더 함수도 DWORD 의 1 차원 배열이며, 각 버텍스에 대해서 실행하는 명령의 순서 첨부 리스트를 형성하고 있다. 각 명령은 복수의 DWORD 로 구성된다.

Direct3DX 유틸리티 라이브러리에는, 드라이버에 전송 되는 표준 DWORD 토큰을 생성하기 위한 일련의 함수가 준비되어 있다. 상세한 것에 대하여는, 「버텍스 쉐이더의 컴파일」을 참조할것.


버텍스 쉐이더의 사용법

여기에서는, 어플리케이션내에서의 버텍스 쉐이더의 정의 방법 및 사용 방법을 설명해, 버텍스 쉐이더를 사용해 얻을 수 있는 이펙트에 대해 해설한다.

  • 버텍스 쉐이더 지원의 확인
  • 버텍스 쉐이더 정수 레지스터의 설정
  • 버텍스 쉐이더의 컴파일
  • 버텍스 쉐이더의 생성


버텍스 쉐이더 지원의 확인

D3DCAPS8 의 멤버를 조회해, 버텍스 쉐이더에 관한 처리의 지원 레벨을 확인할 수가 있다. 다음의 표는, Microsoft® DirectX® 8.0 에서의 프로그램 가능한 버텍스 처리에 관련하는 디바이스 기능을 나타내고 있다.

디바이스 기능 | 설명
MaxPrimitiveCount | DrawPrimitive 의 각 호출의 최대 프리미티브수.
MaxVertexIndex | 하드웨어 버텍스 처리에 대해서 지원 되는 인덱스의 최대 사이즈.
MaxStreams | 동시 데이터 스트림의 최대수.
MaxStreamStride | 보폭에 대한 최대 데이터 스트림.
MaxVertexShaderConst | 버텍스 쉐이더의 정수 레지스터의 수.
VertexShaderVersion | 버텍스 쉐이더의 지원 레벨.

VertexShaderVersion 기능은, 버텍스 쉐이더의 지원 레벨을 나타낸다. IDirect3DDevice8::CreateVertexShader 메소드를 호출했을 때, 이 값이하의 버젼 번호를 가지는 버텍스 쉐이더만 정상적으로 생성 된다. CreateVertexShader 에 대한 버텍스 쉐이더의 레벨의 지정은, 쉐이더 토큰 스트림의 제 1 토큰으로 행해진다.

다음의 표는, 지원 되고 있는 버텍스 쉐이더의 버젼을 나타내고 있다.

버젼 | 기능
0.0 | DirectX 7.0.
1.0 | DirectX 8.0. 어드레스 레지스터 A0 없음.
1.1 | DirectX 8.0 어드레스 레지스터 A0 있어.

지원 레벨의 1.0 으로 1.1 의 유일한 차이는, A0 레지스터의 지원의 유무이다.


버텍스 쉐이더 정수 레지스터의 설정

다음의 메소드를 사용해, 버텍스 쉐이더 정수 레지스터에 대한 값의 설정 및 읽기를 실시할 수가 있다.

  • IDirect3DDevice8::GetVertexShaderConstant
  • IDirect3DDevice8::SetVertexShaderConstant

또,def Direct3DX 어셈블러 명령을 사용해, 버텍스 쉐이더의 정수 레지스터를 설정할 수도 있다.


버텍스 쉐이더의 컴파일

Direct3DX 유틸리티 라이브러리에는, 버텍스 쉐이더를 컴파일하기 위한 일련의 함수가 준비되어 있다. 사용할 수 있는 함수는 다음과 같다.

  • D3DXAssembleShader
  • D3DXAssembleShaderFromFileA
  • D3DXAssembleShaderFromFileW


버텍스 쉐이더의 생성

버텍스 쉐이더는, 쉐이더의 선언과 기능을 지정하는 2 개의 토큰 배열에 의해 정의된다. 토큰 배열은, 1 개(살) 이상의 DWORD 토큰으로 구성되어 있어 배열의 말미는 값 0xFFFFFFFF 의 토큰으로 나타난다.

쉐이더의 선언은 쉐이더의 정적인 외부 인터페이스를 정의하고 있어, 버텍스 레지스터 입력에 대한 스트림 데이터의 바인드나, 쉐이더의 정수 메모리에 로드 되는 값등이 포함된다. 쉐이더 함수는, 쉐이더의 처리를 명령의 배열로서 정의한다. 이러한 명령은, 쉐이더가 디바이스에 바인드 되고 있을 때 처리되는 각 버텍스에 대해서, 적절한 순서로 실행된다. 기능 배열을 지정하지 않고 쉐이더를 생성 하면, 그 쉐이더가 경향 쉐이더 때에는, 고정 기능 버텍스 처리가 적용된다.

Microsoft® DirectX® 8.0 으로 버텍스 쉐이더를 생성 하려면 ,IDirect3DDevice8::CreateVertexShader 메소드를 사용한다. 이 메소드에는, 사용되는 패러렐 DMA 스트림을 정의하는 선언, 및 블렌딩 처리를 정의하는 함수를 건네준다. Direct3D 는, 쉐이더의 핸들을 돌려준다. 쉐이더는,CreateVertexShader 가 불려 갈 때 타당성이 검증된다.


버텍스 쉐이더의 테크닉과 어플리케이션

여기에서는, 버텍스 쉐이더에 이행 되고 있는 일반적인 테크닉에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 행렬 팔레트의 스키닝
  • 프로시쟈르지오메트리
  • 물결의 모델링


행렬 팔레트의 스키닝

8 ~ 10 의 행렬로 구성되는 세트를, 팔레트로서 정수 레지스터에 로드할 수가 있다. 그 후, 처리된 각 버텍스는, 이러한 행렬의 서브 세트에 의해 트랜스 폼 되어 버텍스 레벨의 중량감값을 사용해 최종 결과에 브렌드 된다. 유용한 이행의 1 개로서 들고 있는 것은, 팩 된 4 바이트 정수 배열을 사용해, 버텍스에 영향을 주고 있는 4 개의 행렬의 행렬 팔레트 주소를 저장 하는 것이다. Microsoft® DirectX® 7.0 텍스쳐 좌표 세트 등, 표준적인 4D 성분에는, 이러한 행렬의 브렌드에 사용하는 4 개의 중량감값을 포함할 수가 있다.


프로시쟈르지오메트리

피부아래에서 근육이 움직이는 모습은, 구(공)체로부터 계산한 타원과 3 개의 축으로 따른 스케일링에 의해 시뮬레이트 할 수 있다. 이것은, 들어 오는 메쉬 버텍스의 위치를 보정하기 위해서 평가 및 사용할 수 있다. 근육의 타원은, 상대 위치와 스케일 계수가 저장 된 정수 레지스터를 갱신하는 것에 의해 스케일 및 평행이동 할 수 있다.


물결의 모델링

2차 쌍곡면과 같은 형태는, 단위 직사각형내에서 생성해, 들어 오는 지오메트리상에 반복해 맵 할 수가 있다. 이것을 실행하려면 ,frc 매크로를 사용해 입력 버텍스 (x, y) 값을 단위 직사각형에 맵 해, 로컬의 쌍곡면의 상승을 계산해, 입력 버텍스 z 값에 가산한다. 이것을 이용해, 해파등을 시뮬레이트 할 수 있다.


버텍스 쉐이더의 예

여기에서는, 버텍스 쉐이더 코드에 이행 되고 있는 일반적인 이펙트에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 트랜스 폼과 정수 쉐이딩
  • 디레크쇼나르라이트
  • 그 외의 버텍스 쉐이더의 샘플


트랜스 폼과 정수 쉐이딩

다음의 쉐이더는, 정수 칼라로 단일 행렬의 트랜스 폼을 실행한다. 입력 버텍스 레지스터 v0 는 위치이며, 동일이라고 보여진다. 트랜스 폼 행렬은, 정수 레지스터 (c[0] ~ c[3]) (안)중에 있다. 디퓨즈색은 c[4] 에 로드 된다.

dp4 r0.x, v0, c[0]
dp4 r0.y, v0, c[1]
dp4 r0.z, v0, c[2]
dp4 r0.w, v0, c[3]
mov oD0, c[4]         ; 정수 칼라
mov oPos, r0          ; 출력

이 쉐이더는, 6 클락 사이클내에 실행된다.


디레크쇼나르라이트

다음의 쉐이더는, 「트랜스 폼과 정수 쉐이딩」으로 가리킨 버텍스 쉐이더의 예에, 디레크쇼나르라이트의 광원을 추가하는 것으로 생성 할 수 있다.

; 디레크쇼날 광원
dp3 r1.x, v1, c[8]   ; N 와 L 의 내적
max r1, r1.x, c[0000]   ; 0 이상으로 클램프

; diffuse = dot*diffuse + ambient
mad oD0, r1.x, c[5], c[6]


그 외의 버텍스 쉐이더의 샘플

SDK 의 몇개의 샘플에서는, 버텍스 쉐이더 파일을 사용하고 있다. 확장자(extension) . vsh 가 붙은 파일을 \Samples\Multimedia\Media 디렉토리에서 찾는 것.


X 파일

여기에서는, Microsoft® DirectX®(. x) 파일의 구조에 대해 설명해, 어플리케이션내에서의 사용 방법을 해설한다.

설명하는 주제는, 다음과 같다.

  • X 파일에 대해
  • X 파일 인터페이스 계층
  • X 파일 아키텍쳐
  • X 파일의 사용법


X 파일에 대해

. x 파일 포맷은, Microsoft® DirectX® 2.0 으로부터 채용되었다. 이 포맷의 바이너리 버젼은, DirectX 3.0 과 함께 릴리스 되었다. 이것에 대해서도 이 레퍼런스로 자세하게 해설하고 있다. 그 후, DirectX 버젼 6.0 에서는, DirectX (. x) 파일에 대해서 읽고 쓰기를 실행하기 위한 인터페이스 및 메소드가 채용되었다.

. x 파일 포맷은, 상세한 설정이 가능한, 템플릿 지향의 포맷이며, 메쉬, 텍스쳐, 애니메이션, 유저 정의 가능한 오브젝트등을 저장 할 수 있다. 애니메이션 세트를 지원 하고 있기 (위해)때문에, 리얼타임에 재생하기 위해서 사전 정의된 패스를 저장 할 수가 있다. 인스턴스와 계층도 지원 되고 있다. 인스턴스를 사용하는 것으로, 1 파일에 대해 데이터를 1 번 밖에 저장 하지 않아도, 메쉬와 같은, 1 개의 오브젝트에 대한 복수의 참조를 실행할 수 있다. 계층은, 데이터 레코드 끼리의 관계를 표현하기 위해서 사용된다.

. x 파일 포맷은, 하위 레벨의 데이터 프리미티브를 제공한다. 어플리케이션은, 템플릿을 사용해, 이 위에 고차원 레벨의 프리미티브를 정의한다.


X 파일 인터페이스 계층

다음의 그림은,. x 파일 인터페이스 끼리의 관계를 나타내고 있다.


X 파일 아키텍쳐

The Microsoft® DirectX® (. x) 파일 포맷은, 아키텍쳐에도 문맥에도 의존하지 않는 템플릿 지향의 포맷이며, 사용 방법에 대한 지식은 필요없다. 또, 모든 클라이언트 어플리케이션으로 사용할 수 있다.

다음의 각 주제로, X 파일 포맷의 내용과 구문에 대해 설명한다. 이 파일 포맷은, DirectX 소프트웨어 개발 킷 (SDK)으로 사용하는 경우는 확장자(extension) . x 를 사용한다.

  • 예약어(reserved word), 헤더, 코멘트
  • 템플릿
  • 데이터
  • 콤마와 세미콜론의 사용법


예약어(reserved word), 헤더, 코멘트

다음의 표는 예약어(reserved word)를 나타내고 있다. 예약어(reserved word)를 사용할 수 없다.

  • ARRAY
  • DWORD
  • UCHAR
  • BINARY
  • FLOAT
  • ULONGLONG
  • BINARY_RESOURCE
  • SDWORD
  • UNICODE
  • CHAR
  • STRING
  • WORD
  • CSTRING
  • SWORD
  • DOUBLE
  • TEMPLATE

가변장 헤더는 필수로, 데이터 스트림의 선두에 없으면 안 된다. 헤더에는 다음의 데이터가 포함된다.

형 | 사이즈 | 내용 | 의미
매직 번호 (필수) | 4 바이트 | "xof" |
버젼 번호 (필수) | 2 바이트 | 03 | 메이저 버젼 3
 | 2 바이트 | 02 | 메이저 버젼 2
포맷 타입 (필수) | 4 바이트 | "txt" | 텍스트 파일
 |  | "bin" | 바이노리필드
 |  | "tzip" | MSZip 압축 텍스트 파일
 |  | "bzip" | MSZip 압축 바이노리필드
부동 소수점 사이즈 (필수) | 4 바이트 | 0064 | 64 비트 부동 소수점
 |  | 0032 | 32 비트 부동 소수점

다음에 유효한 헤더의 예를 나타낸다.

xof 0302txt 0064

코멘트는, 텍스트 파일에서만 사용할 수 있어 데이터 스트림내의 어디에라도 삽입할 수 있다. 코멘트의 시작 기호는, C++ 형식의 더블즈 러쉬 (//)인가, 또는 번호 기호 (#)를 사용한다. 코멘트는, 복수행에 걸칠 수가 있다. 다음에 유효한 코멘트의 예를 나타낸다.

#  This is a comment.
// 이것도 코멘트이다.


템플릿

템플릿은, 데이터 스트림의 해석 방법을 정의한다. 즉, 템플릿의 정의에 의해 데이터가 곱셈된다. 여기에서는, 템플릿의 다양한 측면으로 도착해 설명해, 마지막에 템플릿의 예를 소개한다.

  • 템플릿의 형식, 이름, UUID
  • 템플릿의 멤버
  • 템플릿의 한정 사용
  • 템플릿의 예

템플릿안에는,헤더 템플릿이라고 하는 특수한 템플릿이 1 개 있다. 버젼 정보라고 하는 어플리케이션 고유의 정보를 정의하기 위해서, 각 어플리케이션에 대해 1 개씩의 헤더 템플릿을 정의하는 것이 추천 된다. 이 템플릿이 존재하는 경우, 이 헤더는 . x 파일 포맷 API 에 의해 읽힌다. flags 멤버가 있는 경우는, 그 이후의 데이터의 해석 방법의 결정에 사용된다. flags 멤버가 정의되고 있는 경우는,DWORD 이다. 현재, 비트 0 의 1 비트가 정의되고 있다. 이 비트가 클리어의 경우, 파일내의 이후의 데이터는 바이너리이다. 설정되어 있는 경우는, 그 이후의 데이터는 텍스트이다. 복수의 헤더 데이터 오브젝트를 사용해, 파일내에서 바이너리와 텍스트를 바꿀 수가 있다.


템플릿의 형식, 이름, UUID

템플릿의 형식은 다음과 같이 된다.

template <template-name> {
<UUID>
<member 1>;
...
<member n>;
[restrictions]
}

템플릿명에는, 영숫자 및 언더 스코아 (_)를 사용할 수 있다. 다만, 선두의 문자에 숫자는 사용할 수 없다. UUID 는, Open Software Foundation 의 분산 컴퓨팅 환경 표준의 서식에 따르는 유니버설 유니크 식별자이며, 산형이나 와 (< >)로 둘러싼다. 예 : <3D82AB43-62DA-11cf-AB39-0020AF71E433>.


템플릿의 멤버

템플릿 멤버는, 이름 첨부 데이터형의 뒤에, 옵션의 이름, 또는 이름 첨부 데이터형의 배열이 계속된다고 하는 구성이 된다. 유효한 프리미티브 데이터형을 다음 표에 나타낸다.

형 | 사이즈
WORD | 16 비트
DWORD | 32 비트
FLOAT | IEEE 부동 소수점
DOUBLE | 64 비트
CHAR | 8 비트
UCHAR | 8 비트
BYTE | 8 비트
STRING | NULL 종단 캐릭터 라인
CSTRING | 포맷 된 C 캐릭터 라인 (지원되어 있지 않다)
UNICODE | Unicode™ 캐릭터 라인 (지원되어 있지 않다)

추가의 데이터형도, 템플릿내에서 데이터 스트림의 전에 정의되고 있으면, 템플릿 정의내에서 참조할 수 있다. 전방 참조는 실행할 수 없다.

유효한 데이터형은 모두 템플릿 정의내에서 배열로서 표현할 수 있다. 기본적인 구문의 예를 다음에 나타낸다.

array <data-type> <name>[<dimension-size>];

<dimension-size> 는, 정수인가, 또는 다른 템플릿 멤버에의 이름 첨부 참조이다. 이름 첨부 참조의 경우는, 참조처의 값이 대입된다. 사용할 수 있는 배열은 n 차원이다. 여기서 n 란, 정의문의 뒤에 붙일 수 있었던 모퉁이나 이 페어의 수이다. 다음에 예를 나타낸다.

array DWORD FixedHerd[24];
array DWORD Herd[nCows];
array FLOAT Matrix4x4[4][4];


템플릿의 한정 사용

템플릿은, 여는 또는 닫는다, 혹은 한정 사용할 수 있다. 이것에 의해, 템플릿에 정의된 데이터 오브젝트의 직접 계층에서 표시되는 데이터형을 결정할 수 있다. 열린 템플릿에는 제약은 없고, 닫혀진 템플릿은 모든 데이터형을 거부한다. 한정 사용 템플릿에서는, 지정한 데이터형을 사용할 수 있다.

템플릿이 열리고 있는 것을 나타내는 구문은, 3 개의 피리어드를 모퉁이나 개로 둘러싼 것이다.

[ ... ]

템플릿이 한정 사용되는 것을 나타내는 구문은, 이름 첨부 데이터형 (옵션으로 모퉁이나 개내에 UUID 첨부)을 콤마로 단락지어 늘어놓은 것이다.

[ { data-type [ UUID ] , } ... ]

이러한 어느쪽이나 지정되어 있지 않은 경우는, 템플릿이 닫고 있는 것을 나타낸다.


템플릿의 예

다음에 템플릿의 예를 나타낸다.

template Mesh {
<3D82AB44-62DA-11cf-AB39-0020AF71E433>
DWORD nVertices;
array Vector vertices[nVertices];
DWORD nFaces;
array MeshFace faces[nFaces];
 [ ... ]                // 열린 템플릿
}
template Vector {
<3D82AB5E-62DA-11cf-AB39-0020AF71E433>
FLOAT x;
FLOAT y;
FLOAT z;
}                        // 닫혀진 템플릿
template FileSystem {
<UUID>
STRING name;
[ Directory <UUID>, File <UUID> ]    // 한정 사용되는 템플릿
}


데이터

데이터 오브젝트에는, 실제의 데이터인가, 또는 그 데이터에의 참조가 포함된다. 각 데이터 오브젝트에는 각각, 데이터형을 정의하는 템플릿이 있다. 다음의 각 주제로, 데이터 오브젝트의 형식과 원가요소에 대해 설명한다.

  • 형식, 식별자, 이름
  • 데이터 멤버


형식, 식별자, 이름

데이터 오브젝트의 형식은 다음과 같이 된다.

<Identifier> [name] { [<UUID>]
<member 1>;
...
<member n>;
}

식별자는 필수로, 사전에 정의된 데이터형 또는 원시적으로 일치해야 한다. 이름은 옵션이다. 멤버의 상세한 것에 대하여는, 「데이터 멤버」를 참조할것


데이터 멤버

데이터 멤버란, 데이터 오브젝트, 데이터 참조, 정수 리스트, 부동 소수점 리스트, 또는 캐릭터 라인 리스트의 언젠가이다.

데이터 오브젝트란, 네스트 된 데이터 오브젝트이다. 이것에 의해, 파일 포맷의 계층 구조적 성질을 표현할 수 있다. 계층 구조 중(안)에서 사용할 수 있는 네스트 된 데이터 오브젝트의 타입은 제한할 수가 있다. 상세한 것에 대하여는 「템플릿」을 참조할것.

데이터 참조란, 전에 존재하는 데이터 오브젝트에의 참조이다. 다음에 예를 나타낸다.

{
  name |
  UUID |
  name UUID
}

정수 리스트란, 세미콜론으로 단락지어진 정수의 리스트이다. 다음에 예를 나타낸다.

1; 2; 3;

부동 소수점 리스트란, 세미콜론으로 단락지어진 부동 소수점의 리스트이다. 다음에 예를 나타낸다.

1.0; 2.0; 3.0;

캐릭터 라인 리스트란, 세미콜론으로 단락지어진 캐릭터 라인의 리스트이다. 다음에 예를 나타낸다.

"Moose"; "Goats"; "Sheep";


콤마와 세미콜론의 사용법

파일 포맷의 구문으로 가장 복잡한 것은, 콤마와 세미콜론의 사용법이다. 이러한 사용법은 엄밀하게 규정되고 있다. 콤마는, 배열의 멤버의 단락을 나타낸다. 세미콜론은, 각 데이터 항목의 마지막을 나타낸다.

예를 들어, 템플릿이 다음과 같이 정의되고 있는 경우,

template mytemp {
DWORD myvar;
}

이 템플릿의 인스턴스는 다음과 같이 된다.

mytemp dataTemp {
1;
}

다른 템플릿을 포함한 템플릿이 다음과 같이 정의되고 있는 경우,

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
FLOAT aFloat;
mytemp aTemp;
}

이 템플릿의 인스턴스는 다음과 같이 된다.

container dataContainer {
1.1;
2; 3;;
}

container 안의 mytemp 를 나타내는 2 행 째의 마지막에는, 세미콜론이 2 개 붙일 수 있고 있다. 최초의 세미콜론은 컨테이너내의 데이터 항목 aTemp 의 마지막을 나타내, 2 번째의 세미콜론은 container 의 마지막을 나타내고 있다.

배열이 다음과 같이 정의되고 있는 경우,

Template mytemp {
array DWORD myvar[3];
}

이 인스턴스는 다음과 같이 된다.

mytemp aTemp {
1, 2, 3;
}

배열의 예에서는, 콤마로 나타내지고 있기 (위해)때문에, 데이터 항목을 세미콜론으로 단락지을 필요는 없다. 마지막에 세미콜론을 붙일 수 있고 있는 경우는, 배열의 마지막을 나타낸다.

다음과 같은, 템플릿에 의해 정의된 데이터 항목의 배열을 포함한 템플릿의 경우,

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
DWORD count;
array mytemp tempArray[count];
}

이 인스턴스는 다음과 같이 된다.

container aContainer {
3;
1;2;,3;4;,5;6;;
}


X 파일의 사용법

여기에서는, Microsoft® Direct3D® 어플리케이션내에서의 . x 파일의 사용 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • X 파일의 로드
  • X 파일에의 보존
  • 큐브의 생성
  • 3D 모델로부터 X 파일에의 변환과 export


X 파일의 로드

x. 파일을 로드하려면 , 다음의 순서를 실행한다.

  1. DirectXFileCreate 함수를 사용해 IDirectXFile 오브젝트를 생성 한다.
  2. 로드하는 Microsoft® DirectX® 파일에 템플릿이 있는 경우는,IDirectXFile::RegisterTemplates 메소드를 사용해 그러한 템플릿을 등록한다.
  3. IDirectXFile::CreateEnumObject 메소드를 사용해 IDirectXFileEnumObject 열거 오브젝트를 생성 한다.
  4. 파일내의 오브젝트를 루프 한다. 각 오브젝트에 대해서, 다음의 순서를 실행한다.
    1. IDirectXFileEnumObject::GetNextDataObject 메소드를 사용해 각 IDirectXFileData 오브젝트를 취득한다.
    2. IDirectXFileData::GetType 메소드를 사용해 데이터의 형태를 취득한다.
    3. IDirectXFileData::GetData 메소드를 사용해 데이터를 로드한다.
    4. 오브젝트에 옵션의 멤버가 있는 경우는,IDirectXFileData::GetNextObject 메소드를 호출해 옵션의 멤버를 취득한다.
    5. IDirectXFileData 오브젝트를 해방한다.
  5. IDirectXFileEnumObject 오브젝트를 해방한다.
  6. IDirectXFile 오브젝트를 해방한다.


X 파일에의 보존

. x 파일 템플릿과 데이터를 . x 파일에 보존하려면 , 다음의 순서를 실행한다.

  1. DirectXFileCreate 함수를 사용해 IDirectXFile 오브젝트를 생성 한다.
  2. IDirectXFile::RegisterTemplates 메소드를 사용해, 사용하는 모든 템플릿에 대해 Microsoft® DirectX® 파일 시스템에 정보를 준다.
  3. IDirectXFile::CreateSaveObject 메소드를 사용해 IDirectXFileSaveObject 오브젝트를 생성 한다.
  4. 필요에 따라서,IDirectXFileSaveObject::SaveTemplates 메소드를 사용해 템플릿을 보존한다.
  5. 보존하는 오브젝트를 루프 한다. 각 최상정도 레벨의 오브젝트에 대해서, 다음의 순서를 실행한다.
    1. IDirectXFileSaveObject::CreateDataObject 메소드를 사용해, 파일내의 최상정도 오브젝트로서 IDirectXFileData 오브젝트를 생성 한다. 최상정도 데이터 오브젝트에 옵션의 아이 오브젝트가 있는 경우는, 다음의 스텝에서 정의되고 있도록(듯이) 적절한 메소드를 사용해 오브젝트에 추가한다.
    2. 템플릿에 의해 허가되고 있으면, 각 IDirectXFileData 오브젝트는 옵션의 아이 오브젝트를 가질 수가 있다. 아이 오브젝트의 타입은,IDirectXFileData,IDirectXFileDataReference , 또는 IDirectXFileBinary 의 3 종류의 머지않아에서도 가능하다. 후의 순서로 가리키는 것 같은, 각각의 타입에 적절한 방법으로 각 옵션의 아이 멤버를 오브젝트 리스트에 추가하면서, 보존하는 오브젝트를 루프 한다. 오브젝트 타입이 Data 의 경우는,IDirectXFileSaveObject::CreateDataObject 메소드를 호출해 IDirectXFileData 오브젝트를 생성 해, 그 후 IDirectXFileData::AddDataObject 메소드를 호출해, 오브젝트의 자식으로 추가한다. 오브젝트 타입이 Data Reference 의 경우는,IDirectXFileData::AddDataReference 메소드를 호출해, 오브젝트의 자식으로 데이터 참조 오브젝트를 생성 및 추가한다. 오브젝트 타입이 Binary 의 경우는,IDirectXFileData::AddBinaryObject 메소드를 호출해, 오브젝트의 자식으로 바이너리 오브젝트를 생성 및 추가한다.
    3. IDirectXFileSaveObject::SaveData 메소드를 호출해, 데이터 오브젝트와 아이를 보존한다.
    4. IDirectXFileData 오브젝트를 해방한다.
  6. IDirectXFileSaveObject 오브젝트를 해방한다.
  7. IDirectXFile 오브젝트를 해방한다.


큐브의 생성

여기에서는, 단순한 큐브에 대해 설명해, 텍스쳐, 프레임, 및 애니메이션의 추가 방법에 대해 해설한다.

  • 단순한 큐브의 정의
  • 텍스쳐의 추가
  • 프레임과 애니메이션의 추가


단순한 큐브의 정의

다음의 파일은, 4 개의 붉은 옆과 2 개의 초록의 옆을 가지는 단순한 큐브를 정의한다. 이 파일에서는, 옵션의 정보를 사용해,Mesh 템플릿으로 정의된 데이터 오브젝트에 정보를 추가하고 있다.

Material RedMaterial {
1.000000;0. 000000;0. 000000;1. 000000;;    // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0. 000000;0. 000000;;
0.000000;0. 000000;0. 000000;;
}
Material GreenMaterial {
0.000000;1. 000000;0. 000000;1. 000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0. 000000;0. 000000;;
0.000000;0. 000000;0. 000000;;
}
// 8 개의 버텍스와 12 의 면 (삼각형)을 가지는 메쉬를 정의한다.
// 메쉬내의 옵션의 데이터 오브젝트를 사용해,
// 머트리얼, 법선, 및 텍스쳐 좌표를 지정한다.
Mesh CubeMesh {
8;                                // 8 개의 버텍스.
1.000000;1. 000000;-1. 000000;,     // 버텍스 0.
-1. 000000;1. 000000;-1. 000000;,    // 버텍스 1.
-1. 000000;1. 000000;1. 000000;,     // 똑같이 계속된다.
1.000000;1. 000000;1. 000000;,
1.000000;-1. 000000;-1. 000000;,
-1. 000000;-1. 000000;-1. 000000;,
-1. 000000;-1. 000000;1. 000000;,
1.000000;-1. 000000;1. 000000;;

12;                      // 12 개의 면.
3;0,1,2;,                // 면 0 에는 3 개의 버텍스가 있다.
3;0,2,3;,                // 똑같이 계속된다.
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;

// 모든 필수 데이터가 정의되었다. 여기서, 파일 포맷의
// 계층 구조적 성질을 사용해 옵션의 데이터를 정의한다.
MeshMaterialList {
2;                    // 사용되는 머트리얼의 수.
12;                   // 각면의 머트리얼.
0,                    // 면 0 은 최초의 머트리얼을 사용한다.
0,
0,
0,
0,
0,
0,
0,
1,                    // 면 8 은 2 번째의 머트리얼을 사용한다.
1,
1,
1;;
{RedMaterial}         // 머트리얼 0 및 1 의
{GreenMaterial}       // 정의에의 참조.
}
MeshNormals {
8;                    // 8 개의 법선을 정의한다.
0.333333;0. 666667;-0. 666667;,
-0. 816497;0. 408248;-0. 408248;,
-0. 333333;0. 666667;0. 666667;,
0.816497;0. 408248;0. 408248;,
0.666667;-0. 666667;-0. 333333;,
-0. 408248;-0. 408248;-0. 816497;,
-0. 666667;-0. 666667;0. 333333;,
0.408248;-0. 408248;0. 816497;;
12;                   // 12 개의 면에 대해서 법선을 정의한다.
3;0,1,2;,
3;0,2,3;,
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;
}
MeshTextureCoords {
8;                        // 각 버텍스에 대해서 텍스쳐 좌표를 정의한다.
0.000000;1. 000000;
1.000000;1. 000000;
0.000000;1. 000000;
1.000000;1. 000000;
0.000000;0. 000000;
1.000000;0. 000000;
0.000000;0. 000000;
1.000000;0. 000000;;
}
}


텍스쳐의 추가

텍스쳐를 추가하려면 , 파일 포맷의 계층 구조적인 성질을 사용해, 옵션의 TextureFilename 데이터 오브젝트를 Material 데이터 오브젝트에 추가한다. Material 오브젝트는 다음과 같이 된다.

Material RedMaterial {
1.000000;0. 000000;0. 000000;1. 000000;;    // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0. 000000;0. 000000;;
0.000000;0. 000000;0. 000000;;
TextureFilename {
"tex1.ppm";
}
}
Material GreenMaterial {
0.000000;1. 000000;0. 000000;1. 000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0. 000000;0. 000000;;
0.000000;0. 000000;0. 000000;;
TextureFilename {
"win95.ppm";
}
}


프레임과 애니메이션의 추가

여기에서는, 단순한 큐브에 프레임과 애니메이션을 추가하는 방법을 설명한다.

  • 프레임의 조작
  • AnimationSets 와 애니메이션의 조작


프레임의 조작

프레임은, 다음의 구조를 가지지 않으면 안 된다.

Frame Aframe {        // 알기 쉬운 프레임명을 붙인다.
FrameTransformMatrix {
...transform data...
}
[ Meshes ] and/or [ More frames]
}

정의 끝난 큐브 메쉬를 프레임내에 두어, 정규 행렬로 트랜스 폼 한다. 그 후, 이 프레임에 애니메이션을 적용한다.

Frame CubeFrame {
FrameTransformMatrix {
1.000000, 0.000000, 0.000000, 0.000000,
0.000000, 1.000000, 0.000000, 0.000000,
0.000000, 0.000000, 1.000000, 0.000000,
0.000000, 0.000000, 0.000000, 1.000000;;
}
{CubeMesh}        // 메쉬를 인 라인에 둘 수도 있지만,
                  // 여기에서는 오브젝트 참조를 사용한다.
}


AnimationSets 와 애니메이션의 조작

애니메이션은, 일련의 키로 정의한다. 키란, 스케일링 처리, 향해, 또는 위치에 관련지을 수 있던, 시간의 값이다.

Animation Animation0 {        // 알기 쉬운 이름을 붙인다.
{ Frame that it applies to&em;normally a reference }
AnimationKey {
...animation key data...
}
{ ...more animation keys... }
}

애니메이션은 그 후 AnimationSets 에 그룹화 된다:

AnimationSet AnimationSet0 { // 알기 쉬운 이름을 붙인다.
{ an animation? could be inline or a reference }
{ ... more animations ... }
}

여기서, 애니메이션내에서 큐브를 이동한다.

AnimationSet AnimationSet0 {
Animation Animation0 {
{CubeFrame}    // 큐브를 포함한 프레임을 사용한다.
AnimationKey {
2;             // 위치 좌표 키.
9;             // 9 키.
10; 3; -100. 000000, 0.000000, 0.000000;;,
20; 3; -75. 000000, 0.000000, 0.000000;;,
30; 3; -50. 000000, 0.000000, 0.000000;;,
40; 3; -25. 500000, 0.000000, 0.000000;;,
50; 3; 0.000000, 0.000000, 0.000000;;,
60; 3; 25.500000, 0.000000, 0.000000;;,
70; 3; 50.000000, 0.000000, 0.000000;;,
80; 3; 75.500000, 0.000000, 0.000000;;,
90; 3; 100.000000, 0.000000, 0.000000;;;
}
}
}

상세한 것에 대하여는,Animation 및 AnimationSet 템플릿을 참조할것.


3D 모델로부터 X 파일에의 변환과 export

Microsoft® Direct3D® 는, 3D 모델로부터 . x 파일 포맷에 변환 및 export 하기 위해서 다음의 툴을 제공하고 있다.

  • Conv3ds.exe
  • XSkinExp.dle


Conv3ds.exe

Conv3ds.exe 유틸리티는, Autodesk 3-D Studio 등의 모델링 패키지로 생성 한 3 차원 (3D) 모델을, Microsoft® DirectX® 의 파일 포맷으로 변환한다. 이 유틸리티는, 디폴트에서는 템플릿없이 바이너리의 . x 파일을 생성 한다.

설명하는 주제는 다음과 같다.

  • Conv3ds.exe 의 실행
  • Conv3ds.exe 의 옵션 인수의 지정
  • Lightwave 오브젝트로부터의 3DS 파일의 생성
  • 힌트와 요령


Conv3ds.exe 의 실행

Conv3ds.exe 를 옵션없이 실행 하면, 프레임의 계층을 포함한다 . x 파일이 생성 된다. 예를 들어, 다음의 커멘드를 실행 하면,. 3ds 파일로부터 File.x 라는 이름의 . x 파일이 생성 된다.

conv3ds File. 3ds

옵션을 지정해 Conv3ds.exe 를 실행하는 경우에 대해서는, 「Conv3ds.exe 의 옵션 인수의 지정」을 참조할것.


Conv3ds.exe 의 옵션 인수의 지정

. 3ds 파일에 키 프레임 데이터가 포함되어 있는 경우는,-A 옵션을 사용 하면, 애니메이션 세트를 포함한다 . x 파일이 생성 된다. 커멘드의 예를 다음에 나타낸다.

conv3ds -A File. 3ds

File. 3ds 파라미터는, 변환하는 파일의 이름이다.

-m 옵션을 사용 하면,. 3ds 파일내의 모든 오브젝트로부터 생성 된 1 개의 메쉬를 포함한 x. 파일이 생성 된다.

conv3ds -m File. 3ds

-T 옵션을 사용 하면, 모든 오브젝트와 프레임 계층이 1 개의 최상정도 프레임내에 랩 된다. 이 옵션을 사용하는 것으로,. 3ds 파일내의 모든 프레임과 오브젝트를 1 개의 호출로 로드할 수 있다.. x 파일내의, 최초의 최상정도 프레임 계층이 로드 된다. 다른 모든 프레임과 메쉬를 포함한 프레임은,. 3ds 확장자(extension)없이 「x3ds_filename」라고 불린다. -T 옵션은,-m 옵션과 함께 사용했을 경우는 효력이 없다.

-s 옵션을 사용하면(자),. 3ds 파일내에서 변환되는 모든 오브젝트의 스케일링 계수를 지정할 수 있다. 예를 들어, 다음의 커멘드를 실행 하면, 모든 오브젝트가 10 배의 크기가 된다.

conv3ds -s10 File. 3ds

다음의 커멘드를 실행 하면, 모든 오브젝트가 10 분의 1 의 크기가 된다.

conv3ds -s0. 1 File. 3ds

-r 옵션을 사용 하면,. 3ds 파일이 변환될 때의 면의 와인딘그 순서가 거꾸로 된다.. 3ds 파일을 변환해 Microsoft® Direct3D® 로 표시했을 때에 오브젝트가 반대에 표시되는 경우는,-r 옵션을 사용해 다시 변환하지 않으면 안 된다.. 3ds 파일로서 export 된 Lightwave 모델은 모두 이 옵션을 사용해 변환할 필요가 있다. 상세한 것에 대하여는, 「Lightwave 오브젝트로부터의 3DS 파일의 생성」을 참조할것.

-v 옵션을 사용 하면, 장황 출력 모드가 온이 된다. 이 옵션에는 정수를 지정한다. 다음의 표는, 현재 지원 되고 있는 정수를 나타내고 있다.

옵션 | 동작
-v0 | 디폴트. 장황 모드 오프.
-v1 | 부정 오브젝트에 관한 경고를 인쇄해, 컨버터의 동작의 일반적인 정보도 인쇄한다.
-v2 | 기본적인 키 프레임 정보, 변환 처리에 포함되는 오브젝트, 및 보존되는 오브젝트에 관한 정보를 인쇄한다.
-v3 | 매우 장황한 모드. 디버그 정보를 이용할 때에 가장 유용.

-e 옵션을 사용 하면, 다음의 예에 나타내도록(듯이), 텍스쳐 맵 파일의 확장자(extension)를 변경할 수 있다.

conv3ds -e"ppm" File. 3ds

File. 3ds 에 텍스쳐 맵 파일 Brick.gif 를 참조하는 오브젝트가 포함되어 있는 경우,. x 파일은 텍스쳐 맵 파일 Brick.ppm 를 참조한다. 컨버터는 텍스쳐 맵 파일을 변환하지 않는다. 변환 후의 . x 파일이 로드 될 때, 텍스쳐 맵 파일은 D3DPATH 에 존재하고 있지 않으면 안 된다. D3DPath 는, 디폴트의 검색 패스를 설정하는 환경 변수이다.

-x 옵션을 사용 하면, 바이너리 . x 파일이 아니고 텍스트 . x 파일이 생성 된다. 텍스트 파일이 사이즈가 커지지만, 수작업으로 간단하게 편집할 수 있다.

-X 옵션을 사용 하면, 파일내에 . x 파일 템플릿이 강제적으로 포함된다. 디폴트에서는, 템플릿은 포함되지 않는다.

-t 옵션을 사용 하면, 변환 후의 . x 파일에 텍스쳐 정보가 포함되지 않는다.

-N 옵션을 사용 하면, 변환 후의 . x 파일에 법선 벡터 정보가 포함되지 않는다. 몇개의 로드의 호출을 실시하면,. x 파일내에 법선 벡터를 가지지 않는 오브젝트의 법선 벡터가 생성된다.

-c 옵션을 사용 하면, 변환 후의 . x 파일에 텍스쳐 좌표가 포함되지 않는다.. 3ds 오브젝트가 텍스쳐 좌표를 가지지 않는 경우, 디폴트에서는,-m 옵션을 사용 하면, 출력되는 메쉬에는 (0,0) uv 텍스쳐 좌표가 포함된다.

-f 옵션을 사용 하면, 변환 후의 . x 파일에 프레임 트랜스 폼 행렬이 포함되지 않는다.

-z 및 -Z 옵션을 사용 하면,. x 파일내의 오브젝트에 의해 참조 떠날 수 있어 모든 머트리얼의 알파면칼라값을 조정할 수가 있다. 예를 들어 다음의 커멘드를 실행 하면, 0.2 미만의 모든 알파값에 0.1 이 가산된다.

conv3ds -z0. 1 -Z0. 2 File. 3ds

다음의 커멘드를 실행 하면, 모든 알파에 대해, 알파값으로부터 0.2 가 감산된다.

conv3ds-z"-0. 2" -z1 File. 3ds

-o 옵션을 사용 하면, 변환 후의 . x 파일의 이름을 지정할 수 있다.

-h 옵션을 사용 하면, 보통 키 프레머-에 의해 생성 되는,. 3ds 파일내의 어느 계층 정보도 해결되지 않는다. 그 대신해,-m 옵션이 사용되지 않는 경우는, 모든 오브젝트가 최상정도 레벨의 프레임내에 출력된다.


Lightwave 오브젝트로부터의 3DS 파일의 생성

Lightwave 의 Trans3d 플러그 인에 의해 export 되었다 . 3ds 파일에 대해서는, 몇개의 주의점이 있다. 이러한 파일을 최적인 상태로 변환하려면 , 다음의 Conv3ds.exe 커멘드를 사용한다.

conv3ds -r -N -f -h -T|m trans3dfile. 3ds

Trans3d 및 Lightwave 오브젝트 에디터에 의해 생성 되었다 . 3ds 오브젝트는 모두, 와인딘그 순서를 반대로 할 필요가 있다. 그렇게 하지 않다고 표시했을 때에 반대 상태가 된다. 이러한 파일에는, 표면 법선 벡터 정보는 포함되지 않았다.


힌트와 요령

Conv3ds.exe 에 의해 생성 된 오브젝트를 로드해도 표시되지 않는 경우는, 스케일 옵션 -s 에 약 100 의 스케일 계수를 지정한다. 이것에 의해,. x 파일내에서 오브젝트의 스케일이 증가한다.

오브젝트를 뷰아내에 로드해, flat shading로부터 gouraud shading로 전환했을 때에, 오브젝트가 진한 회색으로 바뀌었을 경우는,-N 옵션을 사용해 다시 변환한다.

오브젝트의 변환 후에, 텍스쳐가 로드 되지 않는 경우는, 오브젝트가 -e 옵션을 사용해 . ppm 또는 . bmp 파일을 참조하고 있지 않는지 어떤지 확인한다. 또, 텍스쳐의 폭 및 높이가 2 의 거듭제곱이 되어 있는 것을 확인한다. 게다가 텍스쳐가 D3DPATH 의 디렉토리에 저장 되고 있는 것을 확인한다.

현재, Conv3ds.exe 는 . 3ds 애니메이션으로 사용되는 더미 프레임을 지원 하고 있지 않기 때문에, 더미 프레임은 무시된다. 다만, 아이 오브젝트는 모두 변환된다.


XSkinExp.dle

XSkinExp.dle 는 extras 디렉토리에 있다. 이것은 3dsmax 의 에크스포타로서 사용된다. 사용 방법에 대해서는, XSkinExp.dle 에 부속되는 readme 파일을 참조할것.


프로그래밍의 힌트 및 툴

여기에서는, Microsoft® DirectX® Graphics 어플리케이션을 효율적으로 개발하기 위한 정보를 기술한다. 설명하는 주제는, 다음과 같다.

  • 트러블 슈팅
  • 퍼포먼스의 최적화
  • multi-thread 처리의 문제
  • 디바이스 윈도우의 처리
  • 이전의 드라이버의 처리
  • 멀티 모니터 시스템의 처리
  • 윈도우 모드의 멀티 뷰


트러블 슈팅

여기에서는, Microsoft® Direct3D® 어플리케이션의 개발중에 발생할 가능성이 있는 문제를 일반적인 카테고리별로 나타내, 그 회피 방법에 대해 설명한다.

  • 디바이스의 생성
  • 라이팅이 끝난 버텍스의 사용법
  • 아무것도 표시되지 않는다
  • 디버그
  • 볼랜드 부동 소수점 초기화
  • 파라미터의 타당성 검사


디바이스의 생성

디바이스의 생성중에 어플리케이션이 이상종료(ABEND) 했을 경우, 다음의 공통의 에러를 조사한다.

  • 디바이스 능력, 특히 렌더링 깊이를 조사한다.
  • 에러 코드를 조사한다. D3DERR_OUTOFVIDEOMEMORY 에 에러가 있다고 생각된다.
  • 디버그 DirectX DLL 를 사용해, 디버거에 표시되는 출력 메세지를 확인한다.


라이팅이 끝난 버텍스의 사용법

라이팅이 끝난 버텍스를 사용하는 어플리케이션의 경우, D3DRS_LIGHTING 렌더링 스테이트를 FALSE 로 설정해, Microsoft® Direct3D® 라이팅 엔진을 무효로 할 필요가 있다. 디폴트에서는, 라이팅은 유효하게 되어 있어 입력 버텍스에 제로 이외의 칼라값이 포함되어 있어도, 시스템은 법선 벡터를 포함하지 않은 버텍스의 색을 0 (흑)으로 설정한다. 본래, 라이팅이 끝난 버텍스에는 버텍스 법선이 포함되지 않기 때문에, 라이팅 엔진이 유효하게 되어 있으면(자), Direct3D 에게 건네지는 색정보는 렌더링 시에 모두 없어진다.

독자적인 라인 팅을 실행하는 어플리케이션에 있어, 버텍스 칼라가 중요하다 (일)것은 말할 필요도 없다. 시스템에 의한 디폴트값의 사용을 회피하기 위해서, D3DRS_LIGHTING 를 FALSE 로 설정하는 것.


아무것도 표시되지 않는다

어플리케이션을 실행해도 아무것도 표시되지 않는 경우, 다음의 공통의 에러를 조사한다.

  • 삼각형이 없어지지 않은 것을 확인한다.
  • 삼각형이 카링되어 있지 않은 것을 확인한다.
  • 트랜스 폼이 내부적으로 일관하고 있는 것을 확인한다.
  • 뷰 포토의 설정을 조사해, 삼각형의 표시가 가능하게 되어 있는 것을 확인한다.


디버그

Microsoft® Direct3D® 어플리케이션의 디버그는 곤란을 따르는 일이 있다. 모든 반환값 (Direct3D 프로그래밍에 대해 특히 중요한 요소이지만, 하드웨어의 이행에 의해 크게 다르다)을 조사하는 것 외에 다음의 방법을 시험해 본다.

  • 디버그 DLL 로 전환한다.
  • 소프트웨어 전용 디바이스를 강제적으로 사용해, 하드웨어 가속화가 사용 가능해도 오프로 한다.
  • 표면을 강제적으로 시스템 메모리에 배치한다.
  • 윈도우로 실행하는 옵션을 생성 해, 통합 디버거를 사용할 수 있도록(듯이) 한다.

이 일람의 2 번째와 3 번째의 옵션은, 디버거를 헹 시키는 일이 있는 Win16 락을 방지한다.

또, 다음의 엔트리를 Win.ini 에 추가해 본다.

[Direct3D]
debug=3
[DirectDraw]
debug=3


볼랜드 부동 소수점 초기화

볼랜드의 컴파일러는, Microsoft® Direct3D® 와의 호환성이 없는 방법으로 부동 소수점 예외를 보고한다. 이 문제를 해결하려면 , 다음에 나타내도록(듯이), _matherr 예외 핸들러를 포함한다.

// 볼랜드 부동 소수점 초기화.
#include <math.h>
#include <float.h>

void initfp(void)
{
    // 부동 소수점 예외를 무효로 한다.
    _control87(MCW_EM, MCW_EM);
}

int _matherr(struct _exception  *e)
{
    e;               // 경고를 캐쉬하는 더미 참조.
    return 1;        // 에러 처리가 완료.
}


파라미터의 타당성 검사

퍼포먼스 위에의 이유로부터, Microsoft® Direct3D® 런타임의 디버그 버젼에서는, 리테일 버젼의 경우보다 많은 파라미터의 타당성 검사를 실시한다. 리테일 버젼에서는, 타당성 검사가 전혀 행해지지 않는 것도 있다. 이것을 사용하는 것으로, 어플리케이션에서는 저속인 디버그 런타임 컴퍼넌트에 의해 안정된 데밧깅을 실행할 수 있어 그 후로 고속의 리테일 버젼을 사용해 퍼포먼스를 조정해, 최종적인 릴리스에 대비할 수가 있다.

Direct3D 의 몇개의 메소드에서는, 사용할 수 있는 값에 제한이 있지만, 이 제한은 Direct3D 런타임의 디버그 버젼에 의해 체크되어 실시되는 것만으로 있는 것이 많다. 어플리케이션은 이 제한에 따를 필요가 있다. 이것에 따르지 않으면 Direct3D 의 리테일 버젼으로 실행했을 때에, 예상외의 바람직하지 않은 결과가 생길 가능성이 있다. 예를 들어,IDirect3Ddevice8::DrawPrimitive 메소드에서는, 이 메소드로 렌더링 하는 프리미티브의 개수를 나타내는 파라미터 (PrimitiveCount)를 사용한다. 이 메소드로 사용할 수 있는 값의 범위는 0 ~ D3DMAXNUMPRIMITIVES 이다. Direct3D 의 디버그 버젼으로, D3DMAXNUMPRIMITIVES 개보다 많은 프리미티브를 건네주었을 경우, 메소드는 이상종료(ABEND) 해, 에러 로그에 에러 메세지를 출력해, 어플리케이션에 에러값을 돌려준다. 반대로, 런타임의 리테일 버젼으로 실행하고 있는 경우에 어플리케이션으로 같은 에러가 발생했을 때는, 동작은 부정이다. 퍼포먼스 위에의 이유로부터, 메소드는 파라미터의 타당성 검사를 실시하지 않는다. 따라서, 파라미터가 유효하지 않은 경우에는, 그 상황에 의존한 예상외의 동작이 생긴다. 경우에 따라서는, 호출을 하는 일도 있다. 또, 경우에 따라서는, 그 호출해에 기인해 Direct3D 로 메모리 장해가 발생하는 일도 있다. 무효인 호출이 특정의 하드웨어 구성과 DirectX 의 버젼으로 일관해 기능했다고 해도, 다른 하드웨어나 DirectX 의 향후의 릴리스로 기능하는 것은 보증되지 않는다.

리테일 Direct3D 런타임 파일로 어플리케이션을 실행하고 있는 경우에, 설명할 수 없는 장해가 발생했을 때는, 디버그 버젼에 대해서 테스트를 실시해, 어플리케이션으로 무효인 파라미터를 건네주고 있는 개소가 있는지 없는지를 신중하게 조사하는 것.


퍼포먼스의 최적화

3D 그래픽스를 사용하는 리얼타임 어플리케이션의 개발자에게 있어, 퍼포먼스의 최적화는 관심사의 1 개이다. 여기에서는, 최고의 퍼포먼스를 얻을 수 있는 코드를 기술하는 에 해당하는 가이드 라인에 대해 설명한다.

다음의 주제로 설명하는 가이드 라인은, 모든 Microsoft® Direct3D® 어플리케이션에 대해서 사용할 수 있다.

  • 퍼포먼스에 관한 일반적인 힌트
  • 데이타베이스 및 카링
  • 프리미티브의 배치처리
  • 라이팅에 관한 힌트
  • 텍스쳐 사이즈
  • 동적인 버텍스 및 인덱스 버퍼의 사용법
  • 메쉬의 사용법
  • Z 버퍼의 퍼포먼스
  • 버텍스 쉐이더의 최적화


퍼포먼스에 관한 일반적인 힌트

몇개의 일반적인 가이드 라인에 따라, 어플리케이션의 퍼포먼스를 향상시킬 수가 있다.

  • 클리어 처리는 필요한 때에만 실시한다.
  • 스테이트의 변경은 최소한으로 억제한다.
  • 퍼스펙티브 보정은 필요한 때에만 사용한다.
  • 가능한 한 작은 텍스쳐를 사용한다.
  • system resource의 공유의 밸런스를 무너뜨리는 것 같은 특수 효과는 가능한 한 사용하지 않는다.
  • 어플리케이션의 퍼포먼스를 끊임없이 테스트한다.
  • 하드웨어 가속화와 소프트웨어 에뮬레이션의 양쪽 모두로 어플리케이션이 정상적으로 실행되는 것을 확인한다.


데이타베이스 및 카링

Microsoft® Direct3D® 가 뛰어난 퍼포먼스를 실현하기 위한 열쇠가 되는 것은, 월드내의 오브젝트를 거두는 신뢰성 있는 데이타베이스를 구축하는 것이다. 이것은 라스터화나 하드웨어의 개선보다 중요한 것이다.

다각형의 개수는, 관리할 수 있는 범위내에서 최소한으로 억제할 필요가 있다. 다각형의 개수를 줄이려면 , 최초부터 그 개수가 적어도 되는 것 같은 모델을 구축한다. 다각형의 추가는, 개발 단계의 후반으로, 퍼포먼스를 희생하지 않고 추가할 수 있는 경우에 실시한다. 최고 속도의 다각형은 드로잉(Drawing) 하지 않는 다각형인 것을 기억해 둔다.


프리미티브의 배치처리

실행시에 최고의 렌더링 퍼포먼스를 얻으려면 , 프리미티브를 배치처리 해, 렌더링 스테이트의 변경 회수를 가능한 한 줄인다. 예를 들어, 1 개의 오브젝트로 2 개의 텍스쳐를 사용하고 있는 경우, 최초의 텍스쳐를 사용하는 삼각형을 그룹화 해, 필요한 렌더링 스테이트를 그 삼각형에 부가해 텍스쳐를 변경한다. 다음에, 이제(벌써) 1 개의 텍스쳐를 사용하는 삼각형을 모두 그룹화 한다. Microsoft® Direct3D® 의 가장 단순한 하드웨어 지원은, Hardware Abstraction Layer (HAL)를 개입시켜, 렌더링 스테이트의 배치 및 프리미티브의 배치에 의해 불려 간다. 명령의 배치처리를 효율적으로 실시하면, 실행시의 HAL 의 호출 회수가 감소한다.


라이팅에 관한 힌트

라이트를 적용했을 경우, 렌더링 되는 각 프레임에 버텍스마다의 부하가 더해진다. 따라서, 어플리케이션으로 라이트를 신중하게 사용하면, 퍼포먼스의 대폭적인 향상을 전망할 수 있다. 다음의 힌트의 대부분은, 최고 속도의 코드는 불려 가지 않는 코드이다고 하는 생각에 근거한다.

  • 광원은 필요 최소한으로 사용한다. 전체적인 라이팅 레벨을 증가시키는 것만이 필요한 경우는, 새로운 광원을 추가하는 것이 아니라, 앰비언트 라이트를 사용한다. 부담이 훨씬 가벼워진다.
  • 디레크쇼나르라이트는, 포인트 라이트나 spotlight보다 부담이 가볍다. 디레크쇼나르라이트의 경우, 빛의 방향이 고정되고 있기 (위해)때문에, 버텍스 마다 계산할 필요가 없다.
  • spotlight는, 포인트 라이트보다 부담이 가볍다. 빛의 콘의 외측의 영역의 계산은 재빠르게 행해지기 때문에 있다. spotlight의 부담이 가벼운지 어떤지는, spotlight로 장면을 비추는 양에 따라서 다르다.
  • 범위 파라미터를 사용해, 필요한 부분에만 라이트를 비춘다. 범위외에 있는 모든 라이트의 타입은 곧바로 종료한다.
  • 스펙큐러 하이라이트는, 부담이 대략 2 배가 되기 (위해)때문에, 필요한 때에만 사용한다. D3DRS_SPECULARENABLE 렌더링 스테이트에는, 가능한 한 디폴트값 0 을 설정한다. 머트리얼을 정의 하면나무는, 스펙큐러 강도값을 제로로 설정해, 그 머트리얼에 대한 스펙큐러 하이라이트를 오프로 한다. 단지 스펙큐러색을 0,0,0 으로 설정하는 것 만으로는 불충분하다.


텍스쳐 사이즈

텍스쳐 매핑의 퍼포먼스는, 메모리의 속도에 크게 의존한다. 어플리케이션의 텍스쳐를 캐쉬할 때의 퍼포먼스를 최대한으로 높일 방법이 몇개인가 있다.

  • 텍스쳐는 작게 한다. 텍스쳐가 작으면, 메인 CPU 의 2 차 캐쉬에 저장 될 가능성이 높아진다.
  • 프리미티브 마다 텍스쳐를 변경하지 않는다. 다각형은 사용하는 텍스쳐의 순서에 그룹화 한다.
  • 가능한 한 정방형 텍스쳐를 사용한다. 치수가 256 × 256 의 텍스쳐가 최고 속도이다. 예를 들어, 어플리케이션으로 128 × 128 의 4 개의 텍스쳐를 사용하는 경우, 이러한 텍스쳐로 같은 팔레트를 사용해, 모든 텍스쳐를 256 × 256 의 1 개의 텍스쳐에 배치한다. 이 방법을 사용 하면, 텍스쳐의 스왑량도 감소한다. 물론, 위에서 설명한 것처럼, 텍스쳐는 가능한 한 작게 할 필요가 있으므로, 어플리케이션으로 256 × 256 의 텍스쳐가 필요한 경우를 제외해서는, 그러한 텍스쳐를 사용해서는 안 된다.


동적인 버텍스 및 인덱스 버퍼의 사용법

동적인 버텍스 및 인덱스 버퍼에는, 사이즈와 사용 방법에 근거해 퍼포먼스에 차이가 있다. 다음의 사용 방법을 참고에,Lock 메소드의 Flags 파라미터에 D3DLOCK_DISCARD 를 사용하는지, 또는 D3DLOCK_NOOVERWRITE 를 사용할까를 판단한다.

사용 방법 1 :

for loop()
{
    pBuffer->Lock(...D3DLOCK_DISCARD...); // 새로운 포인터를 돌려주어,
                                          // 하드웨어가 기능 정지하지 않는 것을
                                          // 보증한다.
    Fill data (optimally 1000s of vertices/indices, no fewer) in pBuffer.
    pBuffer->Unlock()
    Change state(s).
    DrawPrimitive() or DrawIndexedPrimitive()
}

사용 방법 2 :

for loop()
{
    pVB->Lock(...D3DLOCK_DISCARD...);//새로운 포인터가 돌아가는 것에 의해
                                      //하드웨어가 stall 하지 않는다
                                      //같게 한다.
    Fill data (optimally 1000s of vertices/indices, no fewer) in pBuffer.
    pBuffer->Unlock
    for loop( 100s of times )
    {
        Change State
        DrawPrimitive() or DrawIndexPrimitives() //Tens of primitives
    }
}

사용 방법 3 :

for loop()
{
    If there is space in the Buffer
    {
        // 버텍스나 인덱스를 추가한다.
        pBuffer->Lock(·3DLOCK_NOOVERWRITE�);
    }
    Else
    {
        // 선두로 돌아간다.
        pBuffer->Lock(·3DLOCK_DISCARD�);
    }
    Fill few 10s of vertices/indices in pBuffer
    pBuffer->Unlock
    Change State
    DrawPrimitive() or DrawIndexedPrimitive() // 몇 개의 프리미티브.

}

사용 방법 1 은, 사용 방법 2 또는 3 보다 처리는 빠르지만, 일반적으로는 실용에 향하지 않는다. 어플리케이션으로 각 Lock 에 대해서 평균 2, 3000 개의 버텍스나 인덱스를 추가하는 경우, 사용 방법 2 가 사용 방법 3 보다 처리가 빠르다. 평균보다 적은 경우에는, 사용 방법 3 이 빠르다. 어느 Lock 메소드가 고속으로 있을까에 관해서는 확실한 대답은 없고, 여러가지 방법을 시험하는 것으로 최선의 방법을 찾아낸다.


메쉬의 사용법

메쉬를 최적화하려면 , Microsoft® Direct3D® 의 인덱스 첨부 삼각형 스트립은 아니고, 인덱스 첨부 삼각형을 사용한다. 하드웨어는, 연속하는 삼각형의 95% 가 실제로 스트립을 형성하고 있는 것으로서 검출해, 거기에 응해 조정을 실시한다. 많은 드라이버는, 유산 하드웨어에 대해서도 이러한 처리를 실시한다.

이하에, 메쉬의 다양한 속성에 대해 가리킨다.

속성 ID

속성 ID 는, 면의 그룹을 속성 그룹에 관련짓는 값이다. 이 ID 는,DrawSubset 로 드로잉(Drawing) 하는 면의 서브 세트를 기술한다. 속성 ID 는, 속성 버퍼내의 면에 대해서 지정된다. 속성 ID 의 실제의 값은, 32 비트에 적합하면 어떠한 값에서도 상관없지만, 일반적으로는 0 ~ n (속성수)를 사용한다.

속성 버퍼

속성 버퍼는, 각면이 속하는 속성 그룹을 지정하는 DWORD (각면에 1 개)의 배열이다. 이 버퍼는, 메쉬의 생성시에 제로에 초기화되지만, 로드 루틴에 의해 값을 지정하는지, ID 0 의 속성이 복수개 필요한 경우에는 유저에 의해 지정할까의 몇개의 필요가 있다. 이 버퍼에는,Optimize 로 속성에 근거해 메쉬를 소트 하기 위해서 사용하는 정보가 저장 된다. 속성 테이블이 제시되어 있지 않은 경우,DrawSubset 는 이 버퍼를 조사해, 드로잉(Drawing) 하는 지정의 속성의 면을 선택한다.

속성 테이블

속성 테이블은, 메쉬에 의해 소유 및 보관 유지되는 구조체이다. 이것을 생성하려면 , 속성 소트 기능 또는 최적화의 강화 기능을 유효하게 해 Optimize 를 호출할 필요가 있다. 속성 테이블은, 프리미티브를 드로잉(Drawing) 하는 단일의 호출을 DrawSubset 에 재빠르게 초기화하기 위해서 사용된다. 또, 프로그래시브 메쉬도 이 구조체를 보관 유지하므로, 현재의 상세 레벨 (LOD)로 액티브한 면과 버텍스를 표시할 수가 있다.


Z 버퍼의 퍼포먼스

장면이 전부터 후에 렌더링 되도록(듯이), z 버퍼링을 사용해 텍스쳐 처리를 실시하면, 어플리케이션의 퍼포먼스를 향상시킬 수가 있다. 텍스쳐를 적용해, z 버퍼를 사용한 프리미티브는, 주사선 단위로 z 버퍼에 대해 사전에 테스트된다. 전에 렌더링 된 다각형에 의해 주사선이 숨어 있는 경우는, 그 다각형이 시스템에 의해 재빠르게 효율적으로 제거된다. z 버퍼링에 의해 퍼포먼스는 향상하지만, 이 방법은 장면에서오바드로를 몇번이나 실시할 때 가장 유효하다. 오바드로란, 스크린 픽셀의 평균 기입 회수이다. 오바드로를 정확하게 계산하는 것은 어렵지만, 근사치를 요구할 수 있다. 오바드로의 평균이 2 보다 작은 경우에는, z 버퍼링을 오프로 해, 장면을 나중에 전에 렌다린 하면, 최고의 퍼포먼스를 얻을 수 있다.

고속의 퍼스널 컴퓨터의 경우, 소프트웨어에 의한 시스템 메모리에의 렌더링이, 비디오 메모리에의 렌더링보다 고속으로 있는 것이 많다. 다만, 이 경우, 더블 버퍼링이나 하드웨어 가속화에 의한 클리어 처리는 사용할 수 없다. 어플리케이션으로 시스템 메모리 또는 비디오 메모리의 어느 것에도 렌더링 할 수 있어 어느 쪽이 고속으로 있는지를 테스트하는 루틴이 있으면, 현재의 시스템으로 최적인 방법을 이용할 수가 있다. Microsoft® Direct3D® 의 SDK 에 수록되는 샘플 코드에서는, 이 방법을 나타내고 있다. 속도를 테스트할 방법이 그 밖에 없기 때문에, 양쪽 모두의 방법을 이행 할 필요가 있다. 속도는 컴퓨터간에 크게 달라, 메인 메모리 아키텍쳐나, 사용하는 그래픽스 어댑터의 종류에 의존한다.


버텍스 쉐이더의 최적화

버텍스 쉐이더를 최적화하려면 , 다음에 나타내도록(듯이) 몇개의 방법이 있다.

  • 버텍스 버퍼의 스윗치를 최소화하는 것.
  • 가능하면 정적 버텍스 버퍼를 사용하는 것.
  • 오브젝트마다는 아니고, 정적 오브젝트에 대해서 FVF 마다 1 개(살)의 큰 버텍스 버퍼를 사용하는 것.
  • 쉐이더내에서 필요하지 않으면, 출력 레지스터를 카피하지 않는다.

예를 들어,

       mad r1, c[2], c[3]
       mov oD0, r1

(은)는 아니고, 다음과 같이 한다.

       mad oD0, r1, c[2], c[3]


multi-thread 처리의 문제

풀 스크린의 Microsoft® Direct3D® 어플리케이션은, Direct3D 런타임에 윈도우 핸들을 제공한다. 이 윈도우는 런타임에 의해 훅 된다. 이것은, 어플리케이션의 윈도우 메세지 프로시저에게 건네진 모든 메세지가, 우선, Direct3D 런타임 독자적인 메세지 처리 프로시저에 의해 조사할 수 있던 것을 의미한다.

디스플레이 모드의 변경은, 하위의 operating system에 짜넣어진 지원 루틴에 의해 초래된다. 모드가 변경되면(자), 시스템은 복수의 메세지를 모든 어플리케이션에 있는 요소를 전요소에 카피한다. Direct3D 어플리케이션에서는, 메세지는 윈도우 프로시저 thread로 수신된다. 이 thread는,IDirect3DDevice8::Reset 또는 IDirect3D8::CreateDevice (또는 디스플레이 모드를 변경하는 경우가 있는 IDirect3DDevice8 의 마지막 IUnknown::Release )를 호출한 thread와 반드시 같지 않다. Direct3D 런타임은, 복수의 크리티컬 섹션을 내부에서 보관 유지한다. 적어도 1 개의 크리티컬 섹션이,Reset 또는 CreateDevice 에 의한 모드 변환의 뒤도 보관 유지되므로, 이러한 크리티컬 섹션은, 어플리케이션이 모드 변경에 관련하는 윈도우 메세지를 수신한 후도 보관 유지된다.

이 설계는, 은근히 multi-thread 어플리케이션을 의도하고 있다. 특히, 어플리케이션은 윈도우 메세지 처리 thread를 Direct3D thread로부터 완전하게 분리해야 한다. 1 개의 thread로 모드 변경을 실시하면서, 다른 thread로 Direct3D 의 호출을 실시하는 어플리케이션은, 데드 록의 위험성이 있다.

이러한 이유로부터, Direct3D 에서는,Reset,CreateDevice,TestCoorperativeLevel, 또는 IDirect3DDevice8 의 마지막 Release 의 각 메소드는, 윈도우 메세지를 처리하는 thread와 같은 thread로부터 마셔 호출할 수가 있도록(듯이) 설계되고 있다.


디바이스 윈도우의 처리

여기에서는, Microsoft® Direct3D® 어플리케이션으로 디바이스 윈도우를 처리할 때에 발생할 가능성이 있는 문제에 대해 설명한다.

  • Direct3D 는, Direct3D 메세지 처리 함수를 사용해, 디바이스 윈도우는 아니고, 포커스 윈도우만을 훅 해, 포커스 윈도우 메세지만을 처리한다. 따라서, 포커스 윈도우는, 모든 디바이스 윈도우의 부모가 아니면 안된다.
  • 모든 어플리케이션 (멀티 모니터 또는 싱글 모니터)으로, 적어도 1 개의 디바이스 윈도우가 포커스 윈도우가 아니면 안된다. 이것은, 실질적으로, 싱글 모니터 시스템으로 포커스 윈도우의 자식 윈도우를 디바이스 윈도우로서 사용할 수 없는 것을 의미한다. 친포커스 윈도우를, 포커스 윈도우 및 디바이스 윈도우의 양쪽 모두로서 사용할 필요가 있다. 멀티 모니터 시스템의 경우, 적어도 1 개의 모니터가 포커스 윈도우를 디바이스 윈도우로서 사용할 필요가 있다.


이전의 드라이버의 처리

여기에서는, DirectX 8.0 이전의 버젼의 DirectX 용으로 생성 된 드라이버상에서 Microsoft® DirectX® 8.0 을 처리하는 경우에 발생할 가능성이 있는 문제를 나타낸다.

  • TnLHAL 디바이스를 처리하는 경우, fog의 강도는 계산되지만, 이 값에 절대치 연산은 적용되지 않는다. 계산 결과가 부의 경우, 값은 부인 채이다. 이러한 상황을 회피하는 최선의 방법은, 트랜스 폼을 올바르게 설정하는 것이다. 차선지책으로서는, fog의 시작값과 fog의 종료값을 부가 되도록(듯이) 하는 방법이 있다.

D3DCAPS8 의 MaxStream 멤버를 조회하는 것으로, 드라이버가 DirectX 8.0 용으로 생성되어 있지 않은 것을 검출할 수 있다. 이 값이 0 인 경우, 드라이버는 DirectX 8.0 드라이버는 아니다.


멀티 모니터 시스템의 처리

배타적인 풀 스크린 모드의 개념이 Microsoft® DirectX® 8.0 에는 보관 유지되고 있지만,IDirect3D8::CreateDevice 및 IDirect3DDevice8::Reset 메소드의 호출에서는 완전하게 비명시적으로 보관 유지된다. 풀 스크린 처리로 디바이스의 리셋 또는 생성이 정상적으로 행해지면(자), 그 디바이스를 생성 한 Microsoft® Direct3D® 오브젝트가 시스템 위에의 모든 어댑터를 소유하고 있는 것으로서 마크 된다. 이 상태는 배타 모드로 불려 이 시점에서 Direct3D8 오브젝트는 배타 모드를 소유하고 있다. 배타 모드에서는, 다른 Direct3D8 오브젝트에 의해 생성 된 디바이스가 풀 스크린 처리를 실시하거나 비디오 메모리를 할당할 수 없다. 또, Direct3D8 오브젝트가 배타 모드이다고 보았을 때에는, 풀 스크린이 된 디바이스 이외의 디바이스는 모두 소실 상태가 된다. 소실한 디바이스를 처리하는 방법에 대해서는, 「소실한 디바이스」를 참조할것.

배타 모드에서는, 그 Direct3D8 오브젝트에, 디바이스가 사용하는 포커스 윈도우가 통지된다. 그 Direct3D8 오브젝트가 소유하는 마지막 풀 스크린 디바이스가 윈도우 모드에 리셋 될까 파괴되면(자), 배타 모드는 해방된다.

Direct3D8 오브젝트가 배타 모드를 소유 하면 와, 디바이스는 2 개의 카테고리로 분류된다. 최초의 카테고리의 디바이스는, 이미 풀 스크린인 디바이스를 생성 한 것과 같은 Direct3D8 오브젝트에 의해 생성 되어 이미 풀 스크린인 디바이스와 같은 포커스 윈도우를 가져, 다른 풀 스크린 디바이스와는 다른 어댑터를 나타낸다. 이 카테고리의 디바이스는, 제한없이 Reset 또는 생성 할 수 있어 소실 상태가 될 것은 없다. 이 카테고리의 디바이스는, 풀 스크린 모드로 할 수도 있다.

이 카테고리에 들어가지 않는 디바이스 (다른 Direct3D8 오브젝트에 의해 생성 되었는지, 다른 포커스 윈도우로 생성 되었는지, 이미 풀 스크린의 데이 바이스가 있는 어댑터에 생성 된 디바이스)는 리셋 하지 못하고, 배타 모드가 없어질 때까지 소실 상태대로 된다.

실제로는, 멀티 모니터 어플리케이션에서는 복수의 디바이스를 풀 스크린 모드로 할 수 있지만, 그것은, 이러한 디바이스가 모두 다른 어댑터의 디바이스이며, 같은 Direct3D8 오브젝트에 의해 생성 되어 게다가 같은 포커스 윈도우를 공유하는 경우에 한정된다.


윈도우 모드의 멀티 뷰

IDirect3DDevice8 인터페이스를 개입시켜 소유해 조작할 수 있는 스왑 체인에 가세해, 같은 디바이스로부터 복수의 뷰에 제시하기 위한 추가 스왑 체인을 생성 할 수 있다. 어플리케이션은, 일반적으로,IDirect3DDevice8::CreateAdditionalSwapChain 메소드를 사용해 뷰 마다 1 개의 스왑 체인을 생성 해, 그 스왑 체인을 특정의 윈도우에 관련짓는다. 어플리케이션은, 각 스왑 체인의 백 버퍼에 이미지를 렌더링 한 후, 개개에 제시한다.

각 어댑터에서는 한 번에 1 개의 스왑 체인 밖에 풀 스크린으로 할 수 없다.


DirectX Graphics C/C++ 튜토리얼

이 튜토리얼에서는, C/C++ 어플리케이션으로 Microsoft® Direct3D® 및 Direct3DX 를 사용해, 공통의 태스크를 실시하는 방법을 설명한다. 각 태스크는, 필요한 스텝으로 나누어져 있다. 이해하기 쉽게 하기 위해서, 스텝이 한층 더 세세한 스텝으로 나누어져 있는 튜토리얼도 있다.

다음의 튜토리얼을 기술한다.

  • 튜토리얼 1 : 디바이스의 생성
  • 튜토리얼 2 : 버텍스의 렌더링
  • 튜토리얼 3 : 행렬의 사용법
  • 튜토리얼 4 : 라이트의 생성 및 사용법
  • 튜토리얼 5 : 텍스쳐 맵의 사용법
  • 튜토리얼 6 : 메쉬의 사용법

주 이러한 튜토리얼의 샘플 코드는 소스 프로젝트에 포함되어 있어 그 자리소는 각 튜토리얼에 나타나고 있다.

각 튜토리얼의 샘플 파일은 C++ 로 기술되고 있다. C 컴파일러를 사용하고 있는 경우, 샘플 파일에 적절한 변경을 더해, 에러 없게 컴파일 할 수 있도록(듯이) 해야 한다. 적어도, 인터페이스 메소드에는,vtable 포인터와 this 포인터를 추가할 필요가 있다.

첨부되고 있는 샘플 코드중의 코멘트에는, Microsoft Platform Software Development Kit (SDK)의 원시 파일과는 다른 것도 있다. 변경은, 샘플 코드의 동작이 바뀌는 것을 피하기 (위해)때문에, 코멘트인 만큼 한정해, 간결하게 하기 위한(해)인 만큼 가고 있다.

참조

DirectX Graphics C/C++ 샘플


튜토리얼 1 : 디바이스의 생성

Microsoft® Direct3D® 를 사용하려면 , 우선, 어플리케이션 윈도우를 생성 한 후, Direct3D 오브젝트를 생성 해 초기화한다. 유저는, 오브젝트가 이행 하고 있는 COM 인터페이스를 사용해 오브젝트를 처리해, 장면의 렌더링에 필요한 종속 오브젝트를 생성한다. 이 튜토리얼로 사용하는 샘플 프로젝트 CreateDevice 에서는, Direct3D 디바이스를 생성 해, 푸른 화면을 렌더링 하는 것에 의해, 이 태스크를 나타낸다.

이 튜토리얼에서는, 다음의 스텝에서, Direct3D 를 초기화해, 장면을 렌더링 해, 마지막에 슛다운을 실시한다.

  • 스텝 1 : 윈도우의 생성
  • 스텝 2 : Direct3D 의 초기화
  • 스텝 3 : 시스템 메세지의 처리
  • 스텝 4 : 신의 렌더링 및 표시
  • 스텝 5 : 슛다운

주 CreateDevice 샘플 프로젝트의 패스는 다음과 같다.

(SDK 루트) \Samples\Multimedia\Direct3D\Tutorials\Tut01_CreateDevice


스텝 1 : 윈도우의 생성

어느 Microsoft® Windows® 어플리케이션에서도, 실행시에, 우선 실시하지 않으면 안 되는 것은, 어플리케이션 윈도우를 생성 해, 유저에게 표시하는 것이다. 이 때문에, CreateDevice 샘플 프로젝트에서는, 우선 WinMain 함수의 실행으로부터 시작 한다. 다음의 샘플 코드는, 윈도우를 초기화한다.

INT WINAPI WinMain( HINSTANCE hInst, HINSTANCE, LPSTR, INT )
{
    // 윈도우 클래스를 등록한다.
    WNDCLASSEX wc = { sizeof(WNDCLASSEX), CS_CLASSDC, MsgProc, 0L, 0L,
                      GetModuleHandle(NULL), NULL, NULL, NULL, NULL,
                      "D3D Tutorial", NULL };
    RegisterClassEx( &wc );

    // 어플리케이션의 윈도우를 생성 한다.
    HWND hWnd = CreateWindow( "D3D Tutorial", "D3D Tutorial 01: CreateDevice",
                              WS_OVERLAPPEDWINDOW, 100, 100, 300, 300,
                              GetDesktopWindow(), NULL, wc.hInstance, NULL );

위의 샘플 코드는, 표준적인 Windows 프로그래밍이다. 이 샘플에서는, 우선,"D3D Tutorial" 로 불리는 윈도우 클래스를 정의해, 등록하고 있다. 클래스를 등록한 후, 그 클래스를 사용하는 기본적인 최상정도 레벨의 윈도우를 생성 한다. 이 윈도우에는, 폭 300 픽셀, 높이 300 픽셀의 클라이언트 영역이 있다. 이 윈도우에는 메뉴와 자식 윈도우는 없다. 이 샘플에서는, WS_OVERLAPPEDWINDOW 윈도우 스타일을 사용해, 윈도우 어플리케이션에 공통되는 최소화, 최대화, 및 닫는 버튼이 붙은 윈도우를 생성 한다. 샘플을 풀 스크린 모드로 실행하는 경우는, 윈도우 스타일에 WS_EX_TOPMOST 를 사용 하면이야 있고. 이 스타일에서는, 생성 한 윈도우는 다른 모든 윈도우보다 앞에 표시되어 이 윈도우를 비액티브하게 해도 가장 앞에 표시된다. 이 윈도우가 생성 되면(자), 샘플 코드는 Microsoft Win32® 표준 함수를 호출해, 윈도우의 표시와 갱신을 실시한다.

어플리케이션 윈도우를 준비할 수 있으면(자), Microsoft Direct3D® 의 주요 오브젝트의 설정을 시작 할 수 있다. 이것에 대해서는, 「스텝 2 : Direct3D 의 초기화」로 설명한다.


스텝 2 : Direct3D 의 초기화

CreateDevice 샘플 프로젝트에서는, 윈도우의 생성 후,WinMain 로부터 불려 가는 어플리케이션 정의 함수 InitD3D 로 Microsoft® Direct3D® 의 초기화를 실행한다. 어플리케이션 윈도우를 생성 하면, 장면의 렌더링에 사용하는 Direct3D 오브젝트의 초기화를 시작 할 수 있다. 이 처리에는, Direct3D 오브젝트의 생성, 프레젠테이션 파라미터의 설정, 및 Direct3D 디바이스의 생성이 포함된다.

Direct3D 오브젝트를 생성 한 후,IDirect3D8::CreateDevice 메소드를 사용해 Direct3D 디바이스를 생성 할 수 있다. 또, Direct3D 오브젝트를 사용해, 디바이스, 타입, 모드등을 열거할 수도 있다. 다음의 샘플 코드에서는,Direct3DCreate8 함수를 사용해 Direct3D 오브젝트를 생성 하고 있다.

if( NULL == ( g_pD3D = Direct3DCreate8( D3D_SDK_VERSION ) ) )
    return E_FAIL;

Direct3DCreate8 에게 건네지는 파라미터는, 항상 D3D_SDK_VERSION 뿐이다. 이것에 의해, 사용하는 올바른 헤더 파일이 Direct3D 에 통지된다. 헤더 또는 다른 변경에 의해 어플리케이션의 리빌드가 필요하게 될 때마다, 이 값은 인크리먼트(increment) 된다. 버젼이 일치하지 않는 경우,Direct3DCreate8 는 실패한다.

다음의 스텝에서는,IDirect3D8::GetAdapterDisplayMode 메소드를 사용해 현재의 디스플레이 모드를 검출한다. 다음의 샘플 코드에 그것을 나타낸다.

D3DDISPLAYMODE d3ddm;
if( FAILED( g_pD3D->GetAdapterDisplayMode( D3DADAPTER_DEFAULT, &d3ddm ) ) )
    return E_FAIL;

Direct3D 디바이스를 생성 하면나무는,D3DDISPLAYMODE 구조체의 Format 멤버가 사용된다. 윈도우 모드로 실행하는 경우는, 어댑터의 현재의 모드와 일치하는 백 버퍼를 생성 하기 위해서 Format 멤버가 사용된다.

D3DPRESENT_PARAMETERS 의 필드에 입력하는 것에 의해, 3D 어플리케이션의 동작을 지정할 수 있다. CreateDevice 샘플 프로젝트에서는,Windowed 멤버에 TRUE,SwapEffect 멤버에 D3DSWAPEFFECT_DISCARD, 및 BackBufferFormat 멤버에 d3ddm.Format 를 설정해 있다.

D3DPRESENT_PARAMETERS d3dpp;
ZeroMemory( &d3dpp, sizeof(d3dpp) );
d3dpp.Windowed   = TRUE;
d3dpp.SwapEffect = D3DSWAPEFFECT_DISCARD;
d3dpp.BackBufferFormat = d3ddm.Format;

마지막 스텝은, 다음의 샘플 코드에 나타나고 있도록(듯이),IDirect3D8::CreateDevice 메소드를 사용해 Direct3D 디바이스를 생성 하는 것이다.

if( FAILED( g_pD3D->CreateDevice( D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd,
                                  D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                                  &d3dpp, &g_pd3dDevice ) ) )

위의 샘플 코드에서는, D3DADAPTER_DEFAULT 플래그를 사용해, 디폴트의 어댑터를 지정해 디바이스를 생성 하고 있다. 시스템에 복수의 그래픽스 하드웨어 카드가 인스톨되어 있지 않은 한, 대부분의 경우, 시스템의 어댑터는 1 개 뿐이다. 하드웨어 디바이스를 소프트웨어 디바이스보다 우선하는 것을 지정하려면 ,DeviceType 파라미터에 D3DDEVTYPE_HAL 를 지정한다. 이 샘플 코드에서는, D3DCREATE_SOFTWARE_VERTEXPROCESSING 를 사용해, 소프트웨어 버텍스 처리를 사용하는 것을 시스템에 지시하고 있다. D3DCREATE_HARDWARE_VERTEXPROCESSING 를 지정해 하드웨어 버텍스 처리를 사용하는 것을 시스템에 지시했을 경우, 하드웨어 버텍스 처리를 지원 하는 비디오 카드에서는 퍼포먼스가 큰폭으로 향상하는 것에 주의 해야 한다.

Direct3D 가 초기화되었으므로, 다음의 스텝에서는, 시스템 메세지를 처리하는 메카니즘을 생성 한다. 이것에 대해서는, 「스텝 3 : 시스템 메세지의 처리」로 설명한다.


스텝 3 : 시스템 메세지의 처리

어플리케이션 윈도우를 생성 해, Microsoft® Direct3D® 를 초기화하면(자), 장면의 렌더링을 시작 할 수 있다. 보통, Microsoft Windows® 어플리케이션은 메시지 루프의 시스템 메세지를 감시해, 큐에 메세지가 없으면 언제라도 프레임의 렌더링을 실시한다. 다만, CreateDevice 샘플 프로젝트에서는, 큐에 WM_PAINT 메세지가 넣을 수 있을 때까지 대기한다. 이 메세지는, 윈도우의 전체 또는 일부를 재드로잉(Drawing) 할 필요가 있는 것을 어플리케이션에 통지한다.

// 메시지 루프.
MSG msg;
while( GetMessage( &msg, NULL, 0, 0 ) )
{
    TranslateMessage( &msg );
    DispatchMessage( &msg );
}

루프가 실행될 때마다,DispatchMessage 는 MsgProc 를 호출해, 큐내의 메세지를 처리한다. WM_PAINT 가 큐에 넣어지면(자), 어플리케이션은, 윈도우를 재드로잉(Drawing) 하는 어플리케이션 정의 함수 Render 를 호출한다. 다음에, Microsoft Win32® 함수 ValidateRect 가 불려 가, 클라이언트 영역 전체가 검증된다.

이 메세지 처리 함수의 샘플 코드를 이하에 나타낸다.

LRESULT WINAPI MsgProc( HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam )
{
    switch( msg )
    {
        case WM_DESTROY:
            PostQuitMessage( 0 );
            return 0;

        case WM_PAINT:
            Render();
            ValidateRect( hWnd, NULL );
            return 0;
    }

    return DefWindowProc( hWnd, msg, wParam, lParam );
}

어플리케이션으로 시스템 메세지를 처리하게 되었으므로, 다음의 스텝에서는, 디스플레이를 렌더링 한다. 이것에 대해서는, 「스텝 4 : 신의 렌더링 및 표시」로 설명한다.


스텝 4 : 신의 렌더링 및 표시

장면을 렌더링 및 표시하기 위해서, 이 스텝의 샘플 코드에서는, 백 버퍼를 청색에 클리어 해, 백 버퍼의 내용을 프런트 버퍼에 전송 해, 프런트 버퍼를 화면에 표시하고 있다.

장면을 클리어 하려면 ,IDirect3DDevice8::Clear 메소드를 호출한다.

// 백 버퍼를 청색에 클리어 한다.
g_pd3dDevice->Clear( 0, NULL, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0,0,255), 1.0f, 0 );

Clear 가 받는 최초의 2 개의 파라미터는, Microsoft® Direct3D® 에, 클리어 하는 직사각형의 배열의 사이즈와 주소를 통지한다. 직사각형의 배열은, 렌더링 타겟 표면 위에의 클리어 하는 영역을 기술한다.

보통, 렌더링 타겟 전체를 가리는 1 개의 직사각형을 사용한다. 이것을 실시하려면 , 최초의 파라미터를 0 에, 2 번째의 파라미터를 NULL 로 설정한다. 3 번째의 파라미터는, 메소드의 동작을 결정한다. 렌더링 타겟 표면, 관련 깊이 버퍼, 스텐실 버퍼, 또는 이 3 개의 임의의 편성을 클리어 할 수가 있다. 이 튜토리얼에서는, 깊이 버퍼를 사용하지 않기 때문에, D3DCLEAR_TARGET 이외의 플래그는 사용하지 않는다. 마지막 3 개의 파라미터는, 렌더링 타겟, 깊이 버퍼, 스텐실 버퍼의 클리어값을 반영하도록(듯이) 설정한다. CreateDevice 샘플 프로젝트에서는, 렌더링 타겟 표면의 클리어 칼라를 파랑 (D3DCOLOR_XRGB(0,0,255))로 설정해 있다. 마지막 2 개의 파라미터는, 대응하는 플래그가 존재하지 않기 때문에,Clear 메소드로 무시된다.

뷰 포토를 클리어 한 후, CreateDevice 샘플 프로젝트는, 다음의 샘플 코드에 나타내도록(듯이), 렌더링의 시작 및 렌더링의 종료를 Direct3D 에 통지한다.

// 장면을 시작 한다.
g_pd3dDevice->BeginScene();

// 여기서, 장면의 오브젝트를 렌더링 한다.

// 장면을 종료한다.
g_pd3dDevice->EndScene();

IDirect3DDevice8::BeginScene 및 IDirect3DDevice8::EndScene 메소드는, 렌더링의 시작시 및 종료시를 각각 시스템에 통지한다. 렌더링 메소드는, 이 2 개의 메소드의 호출동안에서 밖에 호출할 수가 없다. 렌더링 메소드가 정상적으로 종료하지 않았던 경우에서도,BeginScene 를 재차 호출하기 전에,EndScene 를 호출할 필요가 있다.

장면을 렌더링 하면(자),IDirect3DDevice8::Present 메소드를 사용해 장면을 표시한다.

g_pd3dDevice->Present( NULL, NULL, NULL, NULL );

Present 가 받는 최초의 2 개의 파라미터는, 전송원직사각형과 전송처 직사각형이다. 이 스텝의 샘플 코드에서는, 이 2 개의 파라미터를 NULL 로 설정해, 백 버퍼 전체를 프런트 버퍼에 표시한다. 3 번째의 파라미터는, 이 프레젠테이션의 전송처 윈도우를 설정한다. 이 파라미터는 NULL 로 설정되어 있으므로,D3DPRESENT_PARAMETERS 의 hWndDeviceWindow 멤버가 사용된다. 4 번째의 파라미터는 DirtyRegion 파라미터로, 대부분의 경우 NULL 로 설정할 필요가 있다.

이 튜토리얼의 마지막 스텝에서는, 어플리케이션을 슛다운 한다. 이것에 대해서는, 「스텝 5 : 슛다운」으로 설명한다.


스텝 5 : 슛다운

어플리케이션은, 실행중이 있는 시점에서, 슛다운 해야 한다. Microsoft® DirectX® 어플리케이션을 슛다운 하면은, 어플리케이션 윈도우를 파기할 뿐만 아니라, 어플리케이션이 사용하고 있는 모든 DirectX 오브젝트의 할당을 해제해, 오브젝트에의 포인터를 무효로 하는 것을 의미한다. CreateDevice 샘플 프로젝트에서는, WM_DESTROY 메세지를 받아들였을 때에, 이 처리를 실시하는 어플리케이션 정의 함수 Cleanup 를 호출한다.

VOID Cleanup()
{
    if( g_pd3dDevice ! = NULL)
        g_pd3dDevice->Release();
    if( g_pD3D ! = NULL)
        g_pD3D->Release();
}

위의 함수는, 각 오브젝트에 대해서 IUnknown::Release 메소드를 호출해, 어플리케이션이 사용하고 있는 DirectX 오브젝트의 할당을 해제하고 있다. 이 튜토리얼은 COM 의 규칙에 따르고 있기 (위해)때문에, 대부분의 오브젝트에 대한 참조 카운트는 제로가 되어, 자동적으로 메모리로부터 삭제될 것이다.

슛다운 하면나무 이외에도, 유저가 데스크탑 해상도나 색깊이를 변경했을 때등의 보통의 실행시에, 사용중의 Microsoft Direct3D® 오브젝트를 파기해 재생성 할 필요가 생기는 일도 있다. 따라서, 어플리케이션의 클린 업 코드를 생성 해 두어, 필요한 경우에 호출하면이야 있고.

이 튜토리얼에서는, 디바이스의 생성 방법을 나타냈다. 「튜토리얼 2 : 버텍스의 렌더링」에서는, 버텍스를 사용해 지오메트리 형상을 드로잉(Drawing) 하는 방법을 나타낸다.


튜토리얼 2 : 버텍스의 렌더링

Microsoft® Direct3D® 로 생성 된 생성 된 어플리케이션에서는, 버텍스를 사용해 지오메트리 형상을 드로잉(Drawing) 한다. 각 3D 신에는, 이러한 지오메트리 형상이 1 개 또는 복수 포함된다. Vertices 샘플 프로젝트에서는, 가장 단순한 도형인 삼각형을 생성 해, 디스플레이에 렌더링 한다.

이 튜토리얼에서는, 다음의 스텝에서, 버텍스를 사용해 삼각형을 생성 하는 방법을 나타낸다.

  • 스텝 1 : 커스텀 버텍스 타입의 정의
  • 스텝 2 : 버텍스 버퍼의 설정
  • 스텝 3 : 디스플레이의 렌더링

주 Vertices 샘플 프로젝트의 패스는 다음과 같다.

(SDK 루트) \Samples\Multimedia\Direct3D\Tutorials\Tut02_Vertices

Vertices 프로젝트의 샘플 코드는, CreateDevice 프로젝트의 샘플 코드와 거의 같다. 이 튜토리얼에서는, 버텍스에 고유의 코드에만 주목해, Direct3D 의 초기화, Microsoft Windows® 메세지의 처리, 렌더링, 또는 슛다운에 대해서는 설명하지 않는다. 이러한 태스크에 대해서는, 「튜토리얼 1 : 디바이스의 생성」을 참조할것.


스텝 1 : 커스텀 버텍스 타입의 정의

Vertices 샘플 프로젝트에서는, 3 개의 버텍스를 사용해 2D 의 삼각형을 렌더링 한다. 여기에서는, 버텍스를 저장 및 렌더링 하기 위해서 사용되는 Microsoft® Direct3D® 오브젝트인, 버텍스 버퍼의 개념을 도입하고 있다. 버텍스는, 커스텀 버텍스 구조체 및 대응하는 커스텀 FVF (유연한 버텍스 포맷)를 지정하는 것에 의해, 많은 방법으로 정의할 수 있다. Vertices 샘플 프로젝트의 버텍스의 포맷을, 다음의 샘플 코드에 나타낸다.

struct CUSTOMVERTEX
{
    FLOAT x, y, z, rhw; // 버텍스의 트랜스 폼 후의 위치 좌표.
    DWORD color;        // 버텍스 칼라.
};

위의 구조체는, 커스텀 버텍스 타입의 포맷을 지정한다. 다음의 스텝은, 버텍스 버퍼내의 버텍스의 내용을 기술하는 FVF 를 정의하는 것이다. 다음의 샘플 코드에서는, 위에서 생성 한 커스텀 버텍스 타입에 대응하는 FVF 를 정의하고 있다.

#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZRHW|D3DFVF_DIFFUSE)

유연한 버텍스 포맷 플래그는, 사용하는 커스텀 버텍스의 타입을 지정한다. 위의 샘플 코드에서는, D3DFVF_XYZRHW 및 D3DFVF_DIFFUSE 플래그를 사용해, 커스텀 버텍스 타입이 트랜스 폼 된 버텍스와 색성분을 가지는 것을 버텍스 버퍼에 통지하고 있다.

커스텀 버텍스 포맷 및 FVF 가 지정되었으므로, 다음의 스텝에서는, 버텍스 버퍼에 버텍스를 입력한다. 이것에 대해서는, 「스텝 2 : 버텍스 버퍼의 설정」으로 설명한다.

주 Vertices 샘플 프로젝트의 버텍스는 트랜스 폼 되고 있다. 즉, 버텍스는 이미 2D 윈도우 좌표로 나타내지고 있다. 이것은, 포인트 (0,0)가 좌상구석이며, 정의 x 축이 우측향, 정의 y 축이 아래방향인 것을 의미한다. 이러한 버텍스에 라이트를 댈 수도 있다. 이것은, 버텍스는 Direct3D 라이팅을 사용하고 있지 않지만, 독자적인 색을 가지고 있는 것을 의미한다.


스텝 2 : 버텍스 버퍼의 설정

커스텀 버텍스 포맷이 정의되었으므로, 다음은 버텍스를 초기화한다. Vertices 샘플 프로젝트에서는, 이 처리를 실시하기 위해서(때문에), 필요한 Microsoft® Direct3D® 오브젝트를 생성 한 후, 어플리케이션 정의 함수 InitVB 를 호출하고 있다. 다음의 샘플 코드에서는, 3 개의 커스텀 버텍스의 값을 초기화하고 있다.

CUSTOMVERTEX g_Vertices[] =
{
    { 150.0f,  50.0f, 0.5f, 1.0f, 0xffff0000, }, // x, y, z, rhw, color
    { 250.0f, 250.0f, 0.5f, 1.0f, 0xff00ff00, },
    {  50.0f, 250.0f, 0.5f, 1.0f, 0xff00ffff, },
};

위의 샘플 코드에서는, 3 개의 버텍스에 삼각형의 포인트를 설정해, 각 버텍스가 방사하는 색을 지정한다. 최초의 포인트는 (150, 50)에 있어, 적색 (0xffff0000)을 방사한다. 2 번째의 포인트는 (250, 250)에 있어, 녹색 (0xff00ff00)을 방사한다. 3 번째의 포인트는 (50, 250)에 있어, 청록색색 (0xff00ffff)을 방사한다. 3 개의 포인트의 깊이값은 0.5 로, RHW 는 1.0 이다. 이 버텍스 포맷의 상세한 것에 대하여는, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」를 참조할것.

다음의 스텝은, 다음의 샘플 코드와 같이,IDirect3DDevice8::CreateVertexBuffer 를 호출해 버텍스 버퍼를 생성 하는 것이다.

if( FAILED( g_pd3dDevice->CreateVertexBuffer( 3*sizeof(CUSTOMVERTEX),
                                              0 /* 사용 */, D3DFVF_CUSTOMVERTEX,
                                              D3DPOOL_DEFAULT, &g_pVB ) ) )
    return E_FAIL;

CreateVertexBuffer 의 최초의 2 개의 파라미터는, 새로운 버텍스 버퍼의 필요한 사이즈와 사용 방법을 Direct3D 에 지시한다. 다음의 2 개의 파라미터는, 새로운 버퍼의 벡터 포맷 및 메모리 영역을 지정한다. 벡터 포맷은, 이 샘플 코드로 이전으로 지정된 FVF 인 D3DFVF_CUSTOMVERTEX 이다. D3DPOOL_DEFAULT 플래그는, 버텍스 버퍼를, 이 버퍼에 가장 적합한 메모리 할당을 실시해 생성 하도록(듯이) Direct3D 에 지시한다. 마지막 파라미터는, 생성 하는 버텍스 버퍼의 주소이다.

버텍스 버퍼를 생성 하면, 다음의 샘플 코드와 같이, 이 버퍼에 커스텀 버텍스의 데이터가 설정된다.

VOID* pVertices;
if( FAILED( g_pVB->Lock( 0, sizeof(g_Vertices), (BYTE**) &pVertices, 0 ) ) )
    return E_FAIL;
memcpy( pVertices, g_Vertices, sizeof(g_Vertices) );
g_pVB->Unlock();

버텍스 버퍼는, 우선,IDirect3DVertexBuffer8::Lock 를 호출하는 것에 의해 락 된다. 최초의 파라미터는, 잠그는 버텍스 데이터에의 바이트 단위의 오프셋(offset)이다. 제 2 파라미터는, 잠그는 버텍스 데이터의 사이즈를 바이트수로 가리킨다. 제 3 파라미터는, 버텍스 데이터에의 포인터를 저장 하는 BYTE 포인터의 주소이다. 제 4 의 파라미터는, 버텍스 버퍼에 데이터의 락 방법을 지시한다.

버텍스는,memcpy 를 사용해 버텍스 버퍼에 카피된다. 버텍스가 버텍스 버퍼에 저장 된 후,IDirect3DVertexBuffer8::Unlock 를 호출해, 버텍스 버퍼가 언락 된다. 이 락과 언락의 메카니즘은, 버텍스 버퍼가 디바이스 메모리에 존재하는 경우가 있기 (위해)때문에 필요하게 된다.

버텍스 버퍼에 버텍스가 저장 되었으므로, 다음은 디스플레이를 렌더링 한다. 이것에 대해서는, 「스텝 3 : 디스플레이의 렌더링」으로 설명한다.


스텝 3 : 디스플레이의 렌더링

버텍스 버퍼에 버텍스가 저장 되었으므로, 다음은 디스플레이를 렌더링 한다. 디스플레이의 렌더링에서는, 우선 백 버퍼를 청색에 클리어 한 후,BeginScene 를 호출한다.

g_pd3dDevice->Clear( 0, NULL, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0,0,255), 1.0f, 0L );
g_pd3dDevice->BeginScene();

버텍스 버퍼의 버텍스를 렌더링 하려면 , 몇개의 스텝이 필요하다. 우선, 스트림 소스를 설정한다. 이 경우는, 스트림 0 을 사용한다. 스트림의 소스는,IDirect3DDevice8::SetStreamSource 를 호출해 지정한다.

g_pd3dDevice->SetStreamSource( 0, g_pVB, sizeof(CUSTOMVERTEX) );

SetStreamSource 의 최초의 파라미터는, Microsoft® Direct3D® 에 디바이스 데이터 스트림의 소스를 지시한다. 2 번째의 파라미터는, 데이터 스트림에 바인드 하는 버텍스 버퍼이다. 3 번째의 파라미터는, 컴퍼넌트의 사이즈를 바이트 단위로 지정한다. 위의 샘플 코드에서는, CUSTOMVERTEX 의 사이즈가 컴퍼넌트의 사이즈로서 사용되고 있다.

다음의 스텝은,IDirect3DDevice8::SetVertexShader 를 호출해, 사용하는 버텍스 쉐이더를 Direct3D 에 통지하는 것이다. 완전한 커스텀 버텍스 쉐이더는 고도의 주제이지만, 대부분의 경우, 버텍스 쉐이더에 보내지는 것은 단순한 FVF 코드이다. 이것에 의해, 처리하는 버텍스의 타입이 Direct3D 에 통지된다. 다음의 샘플 코드에서는, 버텍스 쉐이더를 설정해 있다.

g_pd3dDevice->SetVertexShader( D3DFVF_CUSTOMVERTEX );

SetVertexShader 의 파라미터는, 사용하는 버텍스 쉐이더에의 핸들 뿐이다. 이 파라미터의 값으로서IDirect3DDevice8::CreateVertexShader 로부터 돌아가는 핸들 또는 FVF 코드를 사용할 수 있다. 여기에서는, D3DFVF_CUSTOMVERTEX 에 의해 정의된 FVF 코드를 사용하고 있다.

버텍스 쉐이더의 상세한 것에 대하여는, 「버텍스 쉐이더」를 참조할것.

다음의 스텝은, 다음의 샘플 코드와 같이,IDirect3DDevice8::DrawPrimitive 를 사용해 버텍스 버퍼의 버텍스를 렌더링 하는 것이다.

g_pd3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, 1 );

DrawPrimitive 가 받는 최초의 파라미터는, 드로잉(Drawing) 하는 프리미티브의 타입을 Direct3D 에 지시하는 플래그이다. 이 샘플에서는, D3DPT_TRIANGLELIST 플래그를 사용해, 삼각형의 리스트를 지정하고 있다. 2 번째의 파라미터는, 로드하는 최초의 버텍스의 인덱스이다. 3 번째의 파라미터는, 드로잉(Drawing) 하는 프리미티브의 수를 지정한다. 이 샘플에서는, 삼각형을 1 개만 드로잉(Drawing) 하므로, 이 값은 1 으로 설정된다.

다양한 프리미티브의 상세한 것에 대하여는, 「3D 프리미티브」를 참조할것.

마지막 스텝은, 장면을 종료해, 백 버퍼를 프런트 버퍼에 표시하는 것이다. 다음의 샘플 코드에 그 처리를 나타낸다.

g_pd3dDevice->EndScene();
g_pd3dDevice->Present( NULL, NULL, NULL, NULL );

백 버퍼를 프런트 버퍼에 표시 하면, 클라이언트 윈도우에 3 종류의 색의 점을 가지는 삼각형이 표시된다.

이 튜토리얼에서는, 버텍스를 사용해 지오메트리 형상을 렌더링 하는 방법을 나타냈다. 「튜토리얼 3 : 행렬의 사용법」에서는, 행렬의 개념과 그 사용 방법에 대해 설명한다.


튜토리얼 3 : 행렬의 사용법

이 튜토리얼에서는, 행렬의 개념과 그 사용 방법을 나타낸다. Vertices 샘플 프로젝트에서는, 2D 의 버텍스를 렌더링 해 삼각형을 드로잉(Drawing) 했다. 여기에서는, 3D 의 버텍스의 트랜스 폼을 처리한다. 행렬은, 카메라와 뷰 포토의 설정에도 사용된다. 트랜스 폼 행렬의 처리의 상세한 것에 대하여는, 「3D 트랜스 폼」을 참조할것.

Matrices 샘플 프로젝트에서는, 지오메트리를 렌더링 하기 전에, 3D 의 삼각형의 렌더링에 사용하는 행렬 트랜스 폼을 생성 및 설정하는 어플리케이션 정의 함수 SetupMatrices 를 호출한다. 보통, 3D 신에는 3 개의 타입의 트랜스 폼이 설정된다. 이 일반적인 트랜스 폼을 생성 하는 스텝을, 이하에 나타낸다.

  • 스텝 1 : 월드 트랜스 폼 행렬의 정의
  • 스텝 2 : 뷰 트랜스 폼 행렬의 정의
  • 스텝 3 : 투영 트랜스 폼 행렬의 정의

행렬 및 트랜스 폼의 상세한 것에 대하여는, 「행렬」을 참조할것.

3D 트랜스 폼의 상세한 것에 대하여는, 「3D 트랜스 폼」을 참조할것.

주 Matrices 샘플 프로젝트의 패스는 다음과 같다.

(SDK 루트) \Samples\Multimedia\Direct3D\Tutorials\Tut03_Matrices

트랜스 폼 행렬을 생성 하는 순서는, 장면내의 오브젝트의 레이아웃에는 영향을 주지 않는다. 다만, Direct3D 에서는, (1) 월드, (2) 뷰, (3) 투영의 순서로, 장면에 행렬이 적용된다.

Matrices 프로젝트의 샘플 코드는, Vertices 프로젝트의 샘플 코드와 거의 같다. 이 튜토리얼에서는, 행렬에 고유의 코드에만 주목해, Direct3D 의 초기화, Microsoft Windows® 메세지의 처리, 렌더링, 또는 슛다운에 대해서는 설명하지 않는다. 이러한 태스크에 대해서는, 「튜토리얼 1 : 디바이스의 생성」을 참조할것.

이 튜토리얼에서는, 커스텀 버텍스 및 버텍스 버퍼를 사용해 지오메트리를 표시한다. 커스텀 버텍스 타입의 선택 및 버텍스 버퍼의 이행의 상세한 것에 대하여는, 「튜토리얼 2 : 버텍스의 렌더링」을 참조할것.


스텝 1 : 월드 트랜스 폼 행렬의 정의

월드 트랜스 폼 행렬은, 3D 모델 공간에서 지오메트리를 평행이동, 스케일링, 및 회전하는 방법을 정의한다.

다음의 샘플 코드에서는, 삼각형을 y 축상에서 회전시킨 후, Microsoft® Direct3D® 디바이스에 현재의 월드 트랜스 폼을 설정해 있다.

D3DXMATRIX matWorld;
D3DXMatrixRotationY( &matWorld, timeGetTime()/150. 0f );
g_pd3dDevice->SetTransform( D3DTS_WORLD, &matWorld );

최초의 스텝은,D3DXMatrixRotationY 메소드를 호출해, Y 축을 중심으로 삼각형을 회전시키는 것이다. 최초의 파라미터는, 처리의 결과가 되는 D3DXMATRIX 에의 포인터이다. 2 번째의 파라미터는, 라디안 단위의 회전의 각도이다.

다음의 스텝에서는,IDirect3DDevice8::SetTransform 를 호출해, Direct3D 디바이스에 월드 트랜스 폼을 설정한다. SetTransform 가 받는 최초의 파라미터는, 설정하는 트랜스 폼을 Direct3D 에 지시한다. 이 샘플에서는,D3DTS_WORLD 매크로를 사용해, 월드 트랜스 폼을 지정한다. 2 번째의 파라미터는, 현재의 트랜스 폼으로서 설정하는 행렬에의 포인터이다.

월드 트랜스 폼의 상세한 것에 대하여는, 「월드 트랜스 폼」을 참조할것.

장면의 월드 트랜스 폼을 정의한 후, 뷰 트랜스 폼 행렬을 준비할 수 있다. 여기에서도, 트랜스 폼을 정의하는 순서는 중요하지 않는 것에 주의 해야 한다. 다만, Direct3D 에서는, (1) 월드, (2) 뷰, (3) 투영의 순서로, 장면에 행렬이 적용된다.

뷰 트랜스 폼 행렬의 정의에 대해서는, 「스텝 2 : 뷰 트랜스 폼 행렬의 정의」로 설명한다.


스텝 2 : 뷰 트랜스 폼 행렬의 정의

뷰 트랜스 폼 행렬은, 뷰의 위치 및 회전을 정의한다. 뷰 행렬은 장면의 카메라이다.

다음의 샘플 코드에서는, 뷰 트랜스 폼 행렬을 생성 한 후, Microsoft® Direct3D® 디바이스에 현재의 뷰 트랜스 폼을 설정해 있다.

D3DXMATRIX matView;
D3DXMatrixLookAtLH( &matView, &D3DXVECTOR3( 0.0f, 3.0f,-5. 0f ),
                              &D3DXVECTOR3( 0.0f, 0.0f, 0.0f ),
                              &D3DXVECTOR3( 0.0f, 1.0f, 0.0f ) );
g_pd3dDevice->SetTransform( D3DTS_VIEW, &matView );

최초의 스텝은,D3DXMatrixLookAtLH 를 호출해 뷰 행렬을 정의하는 것이다. 최초의 파라미터는, 처리의 결과가 되는 D3DXMATRIX 구조체에의 포인터이다. 제 2, 제 3, 제 4 의 파라미터는, 시점, 주시점, 및 "상" 방향을 정의한다. 여기에서는, 시점은 z 축방향으로 -5 단위, 윗방향에 3 단위의 위치에, 주시점은 원점에,"상" 방향은 y 축방향으로 정의되고 있다.

다음의 스텝에서는,IDirect3DDevice8::SetTransform 를 호출해, 뷰 트랜스 폼을 Direct3D 디바이스에 적용한다. SetTransform 가 받는 최초의 파라미터는, 설정하는 트랜스 폼을 Direct3D 에 지시한다. 이 샘플에서는, D3DTS_VIEW 플래그를 사용해, 뷰 트랜스 폼을 지정한다. 2 번째의 파라미터는, 현재의 트랜스 폼으로서 설정하는 행렬에의 포인터이다.

뷰 트랜스 폼의 상세한 것에 대하여는, 「뷰 트랜스 폼」을 참조할것.

장면의 월드 트랜스 폼을 정의한 후, 투영 트랜스 폼 행렬을 준비할 수 있다. 여기에서도, 트랜스 폼을 정의하는 순서는 중요하지 않는 것에 주의 해야 한다. 다만, Direct3D 에서는, (1) 월드, (2) 뷰, (3) 투영의 순서로, 장면에 행렬이 적용된다.

투영 트랜스 폼 행렬의 정의에 대해서는, 「스텝 3 : 투영 트랜스 폼 행렬의 정의」로 설명한다.


스텝 3 : 투영 트랜스 폼 행렬의 정의

투영 트랜스 폼 행렬은, 3D 뷰 공간으로부터 2D 뷰 포토 공간에 지오메트리를 트랜스 폼 하는 방법을 정의한다.

다음의 샘플 코드에서는, 투영 트랜스 폼 행렬을 생성 한 후, Microsoft® Direct3D® 디바이스에 현재의 투영 트랜스 폼을 설정해 있다.

D3DXMATRIX matProj;
D3DXMatrixPerspectiveFovLH( &matProj, D3DX_PI/4, 1.0f, 1.0f, 100.0f );
g_pd3dDevice->SetTransform( D3DTS_PROJECTION, &matProj );

최초의 스텝은,D3DXMatrixPerspectiveFovLH 를 호출해 투영 행렬을 설정하는 것이다. 최초의 파라미터는, 처리의 결과가 되는 D3DXMATRIX 구조체에의 포인터이다. 2 번째의 파라미터는 시야를 정의한다. 이것에 의해, 멀리 있는 오브젝트가 어떻게 작아지는지를 지시한다. 표준적인 시야는 1/4 pi 이며, 이 샘플에서도 이 값이 사용되고 있다. 3 번째의 파라미터는 어스펙트비(가로세로 비율)을 정의한다. 샘플로 사용하는 표준의 어스펙트비(가로세로 비율)은 1 이다. 4 번째와 5 번째의 파라미터는, 가까이의 클립면과 먼 클립면을 정의한다. 이것은, 지오메트리가 렌더링 되지 않게 되는 거리를 결정한다. Matrices 샘플 프로젝트에서는, 가까이의 클립면은 1 에, 먼 클립면은 100 으로 설정되어 있다.

다음의 스텝은,IDirect3DDevice8::SetTransform 를 호출해, 트랜스 폼을 Direct3D 디바이스에 적용하는 것이다. SetTransform 가 받는 최초의 파라미터는, 설정하는 트랜스 폼을 Direct3D 에 지시한다. 이 샘플에서는, D3DTS_PROJECTION 플래그를 사용해, 투영 트랜스 폼을 지정한다. 2 번째의 파라미터는, 현재의 트랜스 폼으로서 설정하는 행렬에의 포인터이다.

투영 트랜스 폼의 상세한 것에 대하여는, 「투영 트랜스 폼」을 참조할것.

이 튜토리얼에서는, 행렬의 사용법을 나타냈다. 「튜토리얼 4 : 라이트의 생성 및 사용법」에서는, 장면에 라이트를 추가해, 한층 리얼하게 하는 방법을 나타낸다.


튜토리얼 4 : 라이트의 생성 및 사용법

Microsoft® Direct3D® 라이트에 의해, 3D 오브젝트는 한층 리얼하게 된다. 라이트를 사용 하면, 장면내의 각 지오메트리 오브젝트는, 사용하는 라이트의 위치 및 타입에 근거해 라이트가 댈 수 있다. 이 튜토리얼의 샘플 코드에서는, 라이트 및 머트리얼에 대해 설명한다.

이 튜토리얼에서는, 다음의 스텝에서 머트리얼 및 라이트를 생성 한다.

  • 스텝 1 : 신의 지오메트리의 초기화
  • 스텝 2 : 머트리얼 및 라이트의 설정

주 Lights 샘플 프로젝트의 패스는 다음과 같다.

(SDK 루트) \Samples\Multimedia\Direct3D\Tutorials\Tut04_Lights

Lights 프로젝트의 샘플 코드는, Matrices 프로젝트의 샘플 코드와 거의 같다. 이 튜토리얼에서는, 라이트의 생성과 사용에 고유의 코드에만 주목해, Direct3D 의 설정, Microsoft Windows 메세지의 처리, 렌더링, 또는 슛다운에 대해서는 설명하지 않는다. 이러한 태스크에 대해서는, 「튜토리얼 1 : 디바이스의 생성」을 참조할것.

이 튜토리얼에서는, 커스텀 버텍스 및 버텍스 버퍼를 사용해 지오메트리를 표시한다. 커스텀 버텍스 타입의 선택 및 버텍스 버퍼의 이행의 상세한 것에 대하여는, 「튜토리얼 2 : 버텍스의 렌더링」을 참조할것.

이 튜토리얼에서는, 행렬을 사용해 지오메트리를 트랜스 폼 한다. 행렬 및 트랜스 폼의 상세한 것에 대하여는, 「튜토리얼 3 : 행렬의 사용법」을 참조할것.


스텝 1 : 신의 지오메트리의 초기화

라이트를 사용하기 위한 조건의 1 개는, 각 표면이 법선을 가지고 있는 것이다. 이것을 처리하기 위해서, Lights 샘플 프로젝트에서는 다른 커스텀 버텍스 타입을 사용한다. 새로운 커스텀 버텍스 포맷에는, 3D 위치 좌표와 표면의 법선이 포함된다. 표면의 법선은, Microsoft® Direct3D® 에 의해 내부적으로 라이팅의 계산에 사용된다.

struct CUSTOMVERTEX
{
    D3DXVECTOR3 position; // 버텍스의 3D 위치 좌표.
    D3DXVECTOR3 normal;   // 버텍스의 표면의 법선.
};

// 커스텀 FVF.
#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZ|D3DFVF_NORMAL)

이것으로 올바른 벡터 포맷이 정의되었으므로, Lights 샘플 프로젝트에서는 어플리케이션 정의 함수 InitGeometry 를 호출해 원기둥(실린더)를 생성 한다. 최초의 스텝은, 다음의 샘플 코드와 같이, 원기둥(실린더)의 포인트를 저장 하는 버텍스 버퍼를 생성 하는 것이다.

// 버텍스 버퍼를 생성 한다.
if( FAILED( g_pd3dDevice->CreateVertexBuffer( 50*2*sizeof(CUSTOMVERTEX),
                                              0 /* 사용 */, D3DFVF_CUSTOMVERTEX,
                                              D3DPOOL_DEFAULT, &g_pVB ) ) )
    return E_FAIL;

다음의 스텝은, 버텍스 버퍼에 원기둥(실린더)의 점을 설정하는 것이다. 다음의 샘플 코드에서는, 각 포인트가 위치 좌표와 법선에 의해 정의되고 있는 것에 주의 해야 한다.

for( DWORD i=0; i<50; i++ )
{
    FLOAT theta = (2*D3DX_PI*i)/(50-1);
    pVertices[2*i+0]. position = D3DXVECTOR3( sinf(theta),-1. 0f, cosf(theta) );
    pVertices[2*i+0]. normal   = D3DXVECTOR3( sinf(theta), 0.0f, cosf(theta) );
    pVertices[2*i+1]. position = D3DXVECTOR3( sinf(theta), 1.0f, cosf(theta) );
    pVertices[2*i+1]. normal   = D3DXVECTOR3( sinf(theta), 0.0f, cosf(theta) );
}

위의 샘플 코드로 버텍스 버퍼에 원기둥(실린더)의 버텍스를 설정하면(자), 버텍스 버퍼를 렌더링 할 수가 있다. 다만, 원기둥(실린더)를 렌더링 하기 전에, 이 장면의 머트리얼과 라이트를 설정해야 한다. 이것에 대해서는, 「스텝 2 : 머트리얼 및 라이트의 설정」으로 설명한다.


스텝 2 : 머트리얼 및 라이트의 설정

Microsoft® Direct3D® 로 라이팅을 사용하려면 , 1 개(살) 또는 복수의 라이트를 생성 해야 한다. 지오메트리 오브젝트가 반사하는 색을 결정하려면 , 지오메트리 오브젝트의 렌더링에 사용하는 머트리얼을 생성 한다. Lights 샘플 프로젝트에서는, 장면을 렌더링 하기 전에, 1 개의 머트리얼과 1 개의 디레크쇼나르라이트를 설정하는 어플리케이션 정의 함수 SetupLights 를 호출한다. 이 함수는, 다음의 스텝에서 머트리얼 및 라이트를 생성 한다.

  • 스텝 2.1 : 머트리얼의 생성
  • 스텝 2.2 : 라이트의 생성


스텝 2.1 : 머트리얼의 생성

머트리얼은, 지오메트리 오브젝트에 라이트가 맞았을 때에, 지오메트리 오브젝트의 표면으로부터 반사되는 색을 정의한다. 다음의 샘플 코드에서는,D3DMATERIAL8 구조체를 사용해, 황색의 머트리얼을 생성 하고 있다.

D3DMATERIAL8 mtrl;
ZeroMemory( &mtrl, sizeof(D3DMATERIAL8) );
mtrl.Diffuse.r = mtrl.Ambient.r = 1.0f;
mtrl.Diffuse.g = mtrl.Ambient.g = 1.0f;
mtrl.Diffuse.b = mtrl.Ambient.b = 0.0f;
mtrl.Diffuse.a = mtrl.Ambient.a = 1.0f;
g_pd3dDevice->SetMaterial( &mtrl );

이 머트리얼의 디퓨즈색 및 앰비언트색은 황색으로 설정된다. IDirect3DDevice8::SetMaterial 메소드의 호출에 의해, 장면의 렌더링에 사용되는 Microsoft® Direct3D® 디바이스에 머트리얼이 적용된다. SetMaterial 가 받는 파라미터는, 설정하는 머트리얼의 주소 뿐이다. 이 호출을 한 후, 다른 머트리얼을 지정하는 SetMaterial 의 다음의 호출을 할 때까지, 이 머트리얼을 사용해 각 프리미티브가 렌더링 된다.

이것으로 장면에 머트리얼이 적용되었으므로, 다음의 스텝은 라이트를 생성 하는 것이다. 이것에 대해서는, 「스텝 2.2 : 라이트의 생성」으로 설명한다.


스텝 2.2 : 라이트의 생성

Microsoft® Direct3D® 로 사용할 수 있는 라이트에게는, 포인트 라이트, 디레크쇼나르라이트, 및 spotlight의 3 종류가 있다. 샘플 코드에서는, 빛이 1 방향으로 나아가는 디레크쇼나르라이트를 생성 해, 라이트의 방향을 변화시키고 있다.

다음의 샘플 코드에서는,D3DLIGHT8 구조체를 사용해, 디레크쇼나르라이트를 생성 한다.

D3DXVECTOR3 vecDir;
D3DLIGHT8 light;
ZeroMemory( &light, sizeof(D3DLIGHT8) );
light.Type       = D3DLIGHT_DIRECTIONAL;

다음의 샘플 코드에서는, 이 라이트의 디퓨즈색을 흰색으로 설정해 있다.

light.Diffuse.r  = 1.0f;
light.Diffuse.g  = 1.0f;
light.Diffuse.b  = 1.0f;

다음의 샘플 코드에서는, 라이트의 방향을 원호로 회전시키고 있다.

vecDir = D3DXVECTOR3(cosf(timeGetTime()/360. 0f),
                     0.0f,
                     sinf(timeGetTime()/360. 0f) );
D3DXVec3Normalize( (D3DXVECTOR3*) &light.Direction, &vecDir );

D3DXVec3Normalize 의 호출에 의해, 라이트의 방향을 결정하기 위한 방향 벡터를 정규화한다.

범위를 지정해, 라이트의 이펙트가 닿는 범위를 Direct3D 에 지시할 수 있다. 이 멤버는, 디레크쇼나르라이트에는 영향을 주지 않는다. 다음의 샘플 코드에서는, 이 라이트로 1000 단위의 범위를 할당하고 있다.

light.Range       = 1000.0f;

다음의 샘플 코드에서는,IDirect3DDevice8::SetLight 를 호출해, Direct3D 디바이스에 라이트를 할당하고 있다.

g_pd3dDevice->SetLight( 0, &light );

SetLight 가 받는 최초의 파라미터는, 이 라이트가 할당할 수 있는 인덱스이다. 라이트가 이미 그 위치에 존재하는 경우, 새로운 라이트에 의해 덧쓰기되는 것에 주의 해야 한다. 2 번째의 파라미터는, 라이트를 정의하는 light 구조체에의 포인터이다. Lights 샘플 프로젝트에서는, 이 라이트를 인덱스 0 에 배치한다.

다음의 샘플 코드에서는,IDirect3DDevice8::LightEnable 를 호출해 라이트를 유효하게 하고 있다.

g_pd3dDevice->LightEnable( 0, TRUE);

LightEnable 가 받는 최초의 파라미터는, 유효하게 하는 라이트의 인덱스이다. 2 번째의 파라미터는, 라이트를 온으로 하는 (TRUE)인가, 오프로 하는 (FALSE)인지를 지정하는 불리언 값이다. 위의 샘플 코드에서는, 인덱스 0 에 있는 라이트가 온이 되어 있다.

다음의 샘플 코드에서는,IDirect3DDevice8::SetRenderState 를 호출해, 라이트를 렌더링 하도록(듯이) Direct3D 에 지시하고 있다.

g_pd3dDevice->SetRenderState( D3DRS_LIGHTING, TRUE );

SetRenderState 가 받는 최초의 2 개의 파라미터는, 변경하는 디바이스 스테이트 변수와 그 변수로 설정하는 값이다. 이 샘플 코드에서는, D3DRS_LIGHTING 디바이스 변수를 TRUE 로 설정해 있다. 이것은, 라이트의 렌더링을 유효하게 하는 효과가 있다.

이 샘플 코드의 마지막 스텝은, 한번 더 SetRenderState 를 호출해, 앰비언트 라이트를 온으로 하는 것이다.

g_pd3dDevice->SetRenderState( D3DRS_AMBIENT, 0x00202020 );

위의 샘플 코드에서는, D3DRS_AMBIENT 디바이스 변수를 라이트 회색 (0x00202020)으로 설정해 있다. 앰비언트 라이트는, 모든 오브젝트가 지정된 색으로 라이트 업 한다.

라이팅의 상세한 것에 대하여는, 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.

이 튜토리얼에서는, 라이트와 머트리얼의 사용법을 나타냈다. 「튜토리얼 5 : 텍스쳐 맵의 사용법」에서는, 표면에 텍스쳐를 추가하는 방법을 나타낸다.


튜토리얼 5 : 텍스쳐 맵의 사용법

라이트와 머트리얼에 의해, 장면은 한층 리얼하게 되지만, 가장 리얼함이 늘어나는 것은 표면에 텍스쳐를 추가했을 때이다. 텍스쳐는, 표면에 축소 랩 된 벽지이다고 생각할 수가 있다. 예를 들어, 나무의 텍스쳐를 입방체에 붙이는 것에 의해, 그 입방체가 나무로 되어 있도록(듯이) 보이게 할 수가 있다. Texture 샘플 프로젝트에서는, 「튜토리얼 4 : 라이트의 생성 및 사용법」으로 생성 한 원기둥(실린더)에 바나나의 껍질의 텍스쳐를 추가한다. 이 튜토리얼에서는, 텍스쳐의 로드, 버텍스의 설정, 및 텍스쳐를 사용한 오브젝트의 표시 방법을 설명한다.

이 튜토리얼에서는, 다음의 스텝에서 텍스쳐를 이행 한다.

  • 스텝 1 : 커스텀 버텍스 포맷의 정의
  • 스텝 2 : 화면의 지오메트리의 초기화
  • 스텝 3 : 신의 렌더링

주 Texture 샘플 프로젝트의 패스는 다음과 같다.

(SDK 루트) \Samples\Multimedia\Direct3D\Tutorials\Tut05_Textures

Texture 프로젝트의 샘플 코드는, Lights 프로젝트의 샘플 코드와 거의 같다. 다만, Texture 샘플 프로젝트에서는 머트리얼이나 라이트를 생성 하지 않는 점이 다르다. 이 튜토리얼에서는, 텍스쳐에 고유의 코드에만 주목해, Microsoft® Direct3D® 의 초기화, Microsoft Windows® 메세지의 처리, 렌더링, 또는 슛다운에 대해서는 설명하지 않는다. 이러한 태스크에 대해서는, 「튜토리얼 1 : 디바이스의 생성」을 참조할것.

이 튜토리얼에서는, 커스텀 버텍스 및 버텍스 버퍼를 사용해 지오메트리를 표시한다. 커스텀 버텍스 타입의 선택 및 버텍스 버퍼의 이행의 상세한 것에 대하여는, 「튜토리얼 2 : 버텍스의 렌더링」을 참조할것.

이 튜토리얼에서는, 행렬을 사용해 지오메트리를 트랜스 폼 한다. 행렬 및 트랜스 폼의 상세한 것에 대하여는, 「튜토리얼 3 : 행렬의 사용법」을 참조할것.


스텝 1 : 커스텀 버텍스 포맷의 정의

텍스쳐를 사용하려면 , 텍스쳐 좌표를 포함한 커스텀 버텍스 포맷을 정의해야 한다. 텍스쳐 좌표에 의해, 프리미티브내의 각 벡터에 대해 텍스쳐를 배치하는 장소를 Microsoft® Direct3D® 에 지시한다. 텍스쳐 좌표의 범위는 0.0 에서 1.0 까지로, (0.0, 0.0)는 텍스쳐의 좌상을 나타내, (1.0, 1.0)는 텍스쳐의 우하를 나타낸다.

다음의 샘플 코드는, Texture 샘플 프로젝트로, 텍스쳐 좌표를 포함하는 커스텀 버텍스 포맷의 설정 방법법을 나타내고 있다.

struct CUSTOMVERTEX
{
    D3DXVECTOR3 position; // 위치 좌표.
    D3DCOLOR    color;    // 색.
    FLOAT       tu, tv;   // 텍스쳐 좌표.
};

// 커스텀 버텍스 구조체를 기술하는 커스텀 FVF.
#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZ|D3DFVF_DIFFUSE|D3DFVF_TEX1)

텍스쳐 좌표의 상세한 것에 대하여는, 「텍스쳐 좌표」를 참조할것.

커스텀 버텍스 타입이 정의되었으므로, 다음의 스텝에서는, 텍스쳐를 로드해, 원기둥(실린더)를 생성 한다. 이것에 대해서는, 「스텝 2 : 화면의 지오메트리의 초기화」로 설명한다.


스텝 2 : 화면의 지오메트리의 초기화

렌더링을 실시하기 전에, Texture 샘플 프로젝트에서는, 텍스쳐를 생성 해, 원기둥(실린더)의 지오메트리를 초기화하는 어플리케이션 정의 함수 InitGeometry 를 호출하고 있다.

텍스쳐는 파일 베이스의 이미지로부터 생성 된다. 다음의 샘플 코드에서는,D3DXCreateTextureFromFile 를 사용해, Banana.bmp 로부터 원기둥(실린더)의 표면을 가리기 위한 텍스쳐를 생성 하고 있다.

if( FAILED( D3DXCreateTextureFromFile( g_pd3dDevice, "Banana.bmp",
                                       &g_pTexture ) ) )
    return E_FAIL;

D3DXCreateTextureFromFile 가 받는 최초의 파라미터는, 텍스쳐를 렌더링 하기 위해서 사용되는 Microsoft® Direct3D® 디바이스에의 포인터이다. 2 번째의 파라미터는, 생성 하는 텍스쳐의 원의 파일명을 지정하는 ANSI 캐릭터 라인에의 포인터이다. 이 샘플에서는, Banana.bmp 를 지정해, 이 파일로부터 이미지를 로드한다. 3 번째의 파라미터는, 텍스쳐 오브젝트에의 포인터의 주소이다.

바나나의 텍스쳐가 로드 되어 사용할 준비를 할 수 있으면(자), 다음의 스텝은 원기둥(실린더)를 생성 하는 것이다. 다음의 샘플 코드에서는, 버텍스 버퍼에 원기둥(실린더)의 데이터를 설정해 있다. 각 포인트는 텍스쳐 좌표 (tu, tv)를 가지는 것에 주의 해야 한다.

for( DWORD i=0; i<50; i++ )
{
    FLOAT theta = (2*D3DX_PI*i)/(50-1);

    pVertices[2*i+0]. position = D3DXVECTOR3( sinf(theta),-1. 0, cosf(theta) );
    pVertices[2*i+0]. color    = 0xffffffff;
    pVertices[2*i+0]. tu       = ((FLOAT) i)/(50-1);
    pVertices[2*i+0]. tv       = 1.0f;

    pVertices[2*i+1]. position = D3DXVECTOR3( sinf(theta), 1.0, cosf(theta) );
    pVertices[2*i+1]. color    = 0xff808080;
    pVertices[2*i+1]. tu       = ((FLOAT) i)/(50-1);
    pVertices[2*i+1]. tv       = 0.0f;
}

각 버텍스에는, 위치 좌표, 색, 및 텍스쳐 좌표가 포함된다. 위의 샘플 코드에서는, 텍스쳐가 원기둥(실린더)의 주위를 매끈매끈하게 가리도록(듯이), 각 포인트의 텍스쳐 좌표를 설정해 있다.

텍스쳐가 로드 되어 버텍스 버퍼를 렌더링 할 준비를 할 수 있었으므로, 다음은 디스플레이를 렌더링 한다. 이것에 대해서는, 「스텝 3 : 신의 렌더링」으로 설명한다.


스텝 3 : 신의 렌더링

장면의 지오메트리가 초기화되면(자), 장면을 렌더링 한다. 텍스쳐를 가지는 오브젝트를 렌더링 하려면 , 그 텍스쳐가 현재의 텍스쳐의 1 개로서 설정되어 있지 않으면 안 된다. 다음의 스텝은, 텍스쳐 스테이지 스테이트의 값을 설정하는 것이다. 텍스쳐 스테이지 스테이트에 의해, 텍스쳐를 렌더링 하는 동작을 정의할 수 있다. 예를 들어, 복수의 텍스쳐를 1 개에 블렌딩 할 수가 있다.

Texture 샘플 프로젝트에서는, 우선, 사용하는 텍스쳐를 설정한다. 다음의 샘플 코드에서는,IDirect3DDevice8::SetTexture 를 사용해, Microsoft® Direct3D® 디바이스가 렌더링 하는 텍스쳐를 설정해 있다.

g_pd3dDevice->SetTexture( 0, g_pTexture );

SetTexture 가 받는 최초의 파라미터는, 텍스쳐를 설정하는 스테이지 식별자이다. 1 개의 디바이스로 최대 8 개의 텍스쳐를 가지기 (위해)때문에, 최대치는 7 이다. Texture 샘플 프로젝트에서는 1 개만 텍스쳐가 있어, 스테이지 0 에 배치하고 있다. 2 번째의 파라미터는, 텍스쳐 오브젝트에의 포인터이다. Texture 샘플 프로젝트에서는, 어플리케이션 정의 함수 InitGeometry 로 생성 한 텍스쳐 오브젝트를 사용한다.

다음의 샘플 코드에서는,IDirect3DDevice8::SetTextureStageState 메소드를 호출하는 것에 의해, 텍스쳐 스테이지 스테이트의 값을 설정해 있다.

g_pd3dDevice->SetTextureStageState( 0, D3DTSS_COLOROP,   D3DTOP_MODULATE );
g_pd3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
g_pd3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );
g_pd3dDevice->SetTextureStageState( 0, D3DTSS_ALPHAOP,   D3DTOP_DISABLE );

SetTextureState 가 받는 최초의 파라미터는, 설정하는 스테이트 변수의 스테이지 인덱스이다. 이 샘플 코드에서는, 스테이지 0 의 텍스쳐의 값을 변경하므로, 여기에서는 0 을 지정하고 있다. 다음의 파라미터는, 설정하는 텍스쳐 스테이트이다. 유효한 모든 텍스쳐 스테이트 및 그 의미의 일람에 대해서는, 「D3DTEXTURESTAGESTATETYPE 」를 참조할것. 다음의 파라미터는, 텍스쳐 스테이트로 설정하는 값이다. 여기로 지정하는 값은, 변경하는 텍스쳐 스테이지 스테이트의 값에 근거하고 있다.

각 텍스쳐 스테이지 스테이트에 적절한 값을 설정 하면, 원기둥(실린더)를 렌더링 할 수가 있어 텍스쳐가 표면에 추가된다.

텍스쳐 좌표의 이제(벌써) 1 개의 사용법은, 자동적으로 텍스쳐 좌표를 생성하는 방법이다. 이 방법에서는, 텍스쳐 좌표 인덱스 (TCI)를 사용한다. TCI 에서는, 텍스쳐 행렬을 사용해, (x, y, z) TCI 좌표를 (tu, tv) 텍스쳐 좌표에 트랜스 폼 한다. Texture 샘플 프로젝트에서는, 카메라 공간에서의 버텍스의 위치 좌표를 사용해, 텍스쳐 좌표를 생성하고 있다.

최초의 스텝은, 다음의 샘플 코드에 나타나고 있도록(듯이), 트랜스 폼에 사용하는 행렬을 생성 하는 것이다.

D3DXMATRIX mat;
mat. _11 = 0.25f; mat. _12 = 0.00f; mat. _13 = 0.00f; mat. _14 = 0.00f;
mat. _21 = 0.00f; mat. _22 =-0. 25f; mat. _23 = 0.00f; mat. _24 = 0.00f;
mat. _31 = 0.00f; mat. _32 = 0.00f; mat. _33 = 1.00f; mat. _34 = 0.00f;
mat. _41 = 0.50f; mat. _42 = 0.50f; mat. _43 = 0.00f; mat. _44 = 1.00f;

행렬을 생성 하면(자), 다음의 샘플 코드와 같이,IDirect3DDevice8::SetTransform 를 호출해 설정해야 한다.

g_pd3dDevice->SetTransform( D3DTS_TEXTURE0, &mat );

D3DTS_TEXTURE0 플래그는, 텍스쳐 스테이지 0 의 텍스쳐에 트랜스 폼을 적용하도록(듯이) Direct3D 에 지시한다. 이 샘플의 다음의 스텝에서는, 목적의 효과를 내기 위해서(때문에), 한층 더 텍스쳐 스테이지 스테이트값을 설정한다. 이 처리는, 다음의 샘플 코드로 행해진다.

g_pd3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2 );
g_pd3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION );

텍스쳐 좌표가 설정되었으므로, 장면을 렌더링 할 수가 있다. 원기둥(실린더)의 좌표는 자동적으로 생성 되는 것에 주의 해야 한다. 이 설정에서는, 지오메트리 형상이 렌더링 된 후, 렌더링 화면에 텍스쳐를 거듭하는 이펙트가 적용된다.

텍스쳐의 상세한 것에 대하여는, 「텍스쳐」를 참조할것.

이 튜토리얼에서는, 표면의 텍스쳐의 사용법을 나타냈다. 「튜토리얼 6 : 메쉬의 사용법」에서는, 메쉬를 포함한 복잡한 지오메트리 형상의 사용 방법을 나타낸다.


튜토리얼 6 : 메쉬의 사용법

복잡한 지오메트리는 보통 3D 모델링 소프트웨어를 사용해 모델링 되어 파일에 보존된다. 예를 들어,. x 파일 포맷등이 있다. Microsoft® Direct3D® 에서는, 메쉬를 사용해 이러한 파일로부터 오브젝트를 로드한다. 메쉬는 조금 복잡하지만, D3DX 에는 메쉬를 용이하게 사용할 수 있도록(듯이) 하는 함수가 포함되어 있다. Meshes 샘플 프로젝트에서는, 메쉬에 관한 주제를 설명해, 메쉬의 로드, 렌더링, 언로드의 방법을 나타낸다.

이 튜토리얼에서는, 다음의 스텝에서, 메쉬를 로드, 렌더링, 및 언로드하는 방법을 나타낸다.

  • 스텝 1 : 메쉬 오브젝트의 로드
  • 스텝 2 : 메쉬 오브젝트의 렌더링
  • 스텝 3 : 메쉬 오브젝트의 언로드

주 Meshes 샘플 프로젝트의 패스는 다음과 같다.

(SDK 루트) \Samples\Multimedia\Direct3D\Tutorials\Tut06_Meshes

Meshes 프로젝트의 샘플 코드는, Lights 프로젝트의 샘플 코드와 거의 같다. 다만, Meshes 샘플 프로젝트의 코드에서는 머트리얼이나 라이트를 생성 하지 않는 점이 다르다. 이 튜토리얼에서는, 메쉬에 고유의 코드에만 주목해, Direct3D 의 설정, Microsoft Windows® 메세지의 처리, 렌더링, 또는 슛다운에 대해서는 설명하지 않는다. 이러한 태스크에 대해서는, 「튜토리얼 1 : 디바이스의 생성」을 참조할것.

이 튜토리얼에서는, 커스텀 버텍스 및 버텍스 버퍼를 사용해 지오메트리를 표시한다. 커스텀 버텍스 타입의 선택 및 버텍스 버퍼의 이행의 상세한 것에 대하여는, 「튜토리얼 2 : 버텍스의 렌더링」을 참조할것.

이 튜토리얼에서는, 행렬을 사용해 지오메트리를 트랜스 폼 한다. 행렬 및 트랜스 폼의 상세한 것에 대하여는, 「튜토리얼 3 : 행렬의 사용법」을 참조할것.

이 튜토리얼에서는, 텍스쳐를 사용해 메쉬의 표면을 가린다. 텍스쳐의 로드 및 사용법의 상세한 것에 대하여는, 「튜토리얼 5 : 텍스쳐 맵의 사용법」을 참조할것.


스텝 1 : 메쉬 오브젝트의 로드

Microsoft® Direct3D® 어플리케이션으로 메쉬를 사용하려면 , 우선 메쉬를 로드하지 않으면 안 된다. Meshes 샘플 프로젝트에서는, 필요한 Direct3D 오브젝트를 로드한 후, 어플리케이션 정의 함수 InitGeometry 를 호출해, 호랑이의 메쉬를 로드한다.

메쉬에는, 사용하는 모든 머트리얼 및 텍스쳐를 저장 하는 머트리얼 버퍼가 필요하다. 이 함수는, 다음의 샘플 코드에 나타내도록(듯이), 최초로 머트리얼 버퍼를 선언한다.

LPD3DXBUFFER pD3DXMtrlBuffer;

다음의 샘플 코드에서는,D3DXLoadMeshFromX 메소드를 사용해, 메쉬를 로드하고 있다.

// 지정한 파일로부터 메쉬를 로드한다.
if( FAILED( D3DXLoadMeshFromX( "tiger.x", D3DXMESH_SYSTEMMEM,
                               g_pd3dDevice, NULL,
                               &pD3DXMtrlBuffer, &g_dwNumMaterials,
                               &g_pMesh ) ) )
    return E_FAIL;

D3DXLoadMeshFromX 가 받는 최초의 파라미터는, 로드하는 Microsoft DirectX® 파일의 이름을 지시하는 캐릭터 라인에의 포인터이다. 이 샘플에서는, Tiger.x 로부터 호랑이의 메쉬를 로드한다.

2 번째의 파라미터는 메쉬의 생성 방법을 Direct3D 에 지시한다. 이 샘플에서는 D3DXMESH_SYSTEMMEM 플래그를 사용하고 있다. 이것은, D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정하고 있는 것과 같다. 이 2 개의 플래그는, 메쉬의 인덱스 버퍼 및 버텍스 버퍼를 시스템 메모리에 배치하도록(듯이) Direct3D 에 지시한다.

3 번째의 파라미터는, 메쉬의 렌더링에 사용하는 Direct3D 디바이스에의 포인터이다.

4 번째의 파라미터는,ID3DXBuffer 오브젝트에의 포인터이다. 이 오브젝트에는, 각면의 인접하는 면에 관한 정보가 저장 된다. 이 샘플에서는, 이 정보는 필요없기 때문에, 이 파라미터는 NULL 로 설정되어 있다.

5 번째의 파라미터도 ID3DXBuffer 오브젝트에의 포인터를 취한다. 이 메소드가 종료한 후, 이 오브젝트에는 메쉬의 D3DXMATERIAL 구조체가 저장 된다.

6 번째의 파라미터는, 이 메소드가 돌아간 후,ppMaterials 배열에 배치되는 D3DXMATERIAL 구조체의 수에의 포인터이다.

7 번째의 파라미터는, 로드 되는 메쉬를 나타내는, 메쉬 오브젝트에의 포인터의 주소이다.

메쉬 오브젝트 및 머트리얼의 정보가 로드 된 후, 머트리얼 버퍼로부터 머트리얼의 프로퍼티 및 텍스쳐명을 추출할 필요가 있다.

Meshes 샘플 프로젝트에서는, 우선 머트리얼 버퍼에의 포인터를 취득하는 것에 의해, 이 처리를 실시한다. 다음의 샘플 코드에서는,ID3DXBuffer::GetBufferPointer 메소드를 사용해, 이 포인터를 취득하고 있다.

D3DXMATERIAL* d3dxMaterials = (D3DXMATERIAL*) pD3DXMtrlBuffer->GetBufferPointer();

다음의 샘플 코드에서는, 메쉬의 머트리얼의 합계수에 근거해, 새로운 메쉬 및 텍스쳐 오브젝트를 생성 하고 있다.

g_pMeshMaterials = new D3DMATERIAL8[g_dwNumMaterials];
g_pMeshTextures  = new LPDIRECT3DTEXTURE8[g_dwNumMaterials];

메쉬내의 각 머트리얼에 대해, 다음의 처리를 한다.

최초의 스텝은, 다음의 샘플 코드에 나타나고 있도록(듯이), 머트리얼을 카피하는 것이다.

g_pMeshMaterials[i] = d3dxMaterials[i]. MatD3D;

제 2 의 스텝은, 다음의 샘플 코드에 나타나고 있도록(듯이), 머트리얼의 앰비언트색을 설정하는 것이다.

g_pMeshMaterials[i]. Ambient = g_pMeshMaterials[i]. Diffuse;

마지막 스텝은, 다음의 샘플 코드에 나타나고 있도록(듯이), 머트리얼의 텍스쳐를 생성 하는 것이다.

// 텍스쳐를 생성 한다.
if( FAILED( D3DXCreateTextureFromFile( g_pd3dDevice,
                                       d3dxMaterials[i]. pTextureFilename,
                                       &g_pMeshTextures[i] ) ) )
    g_pMeshTextures[i] = NULL;
}

각 머트리얼을 로드한 후, 머트리얼 버퍼가 필요한 것은 없어지면(자),IUnknown::Release 를 호출해 해방할 필요가 있다.

pD3DXMtrlBuffer->Release();

메쉬, 및 대응하는 머트리얼과 텍스쳐가 로드 된다. 이것으로 메쉬를 디스플레이에 렌더링 할 수 있다. 이것에 대해서는, 「스텝 2 : 메쉬 오브젝트의 렌더링」으로 설명한다.


스텝 2 : 메쉬 오브젝트의 렌더링

스텝 1 으로 메쉬를 로드했으므로, 메쉬를 렌더링 할 준비가 되어 있다. 메쉬는, 메쉬에 대해 로드 된 각 머트리얼의 서브 세트에 분할된다. 각 서브 세트를 렌더링 하기 위해서, 메쉬는 루프로 렌더링 된다. 루프의 최초의 스텝은, 다음의 샘플 코드에 나타나고 있도록(듯이), 서브 세트의 머트리얼을 설정하는 것이다.

g_pd3dDevice->SetMaterial( &g_pMeshMaterials[i] );

루프의 2 번째의 스텝은, 다음의 샘플 코드에 나타나고 있도록(듯이), 서브 세트의 텍스쳐를 설정하는 것이다.

g_pd3dDevice->SetTexture( 0, g_pMeshTextures[i] );

머트리얼과 텍스쳐를 설정한 후, 다음의 샘플 코드에 나타나고 있도록(듯이),ID3DXBaseMesh::DrawSubset 메소드를 사용해 서브 세트가 드로잉(Drawing) 된다.

g_pMesh->DrawSubset( i );

DrawSubset 메소드는, 드로잉(Drawing) 하는 메쉬의 서브 세트를 지정하는 DWORD 를 취한다. 이 샘플에서는, 루프를 실행할 때마다 인크리먼트(increment) 되는 값을 사용한다.

메쉬를 사용한 후, 메쉬를 메모리로부터 올바르게 삭제할 필요가 있다. 이것에 대해서는, 「스텝 3 : 메쉬 오브젝트의 언로드」로 설명한다.


스텝 3 : 메쉬 오브젝트의 언로드

Microsoft® DirectX® 프로그램이 종료하면(자), 사용한 DirectX 오브젝트의 할당을 해제해, 그 오브젝트에의 포인터를 무효로 할 필요가 있다. 이 샘플로 사용한 메쉬 오브젝트도 할당을 해제할 필요가 있다. Meshes 샘플 프로젝트에서는, WM_DESTROY 메세지를 받아들였을 때에, 이 처리를 실시하는 어플리케이션 정의 함수 Cleanup 를 호출한다.

다음의 샘플 코드에서는, 머트리얼 리스트를 삭제하고 있다.

if( g_pMeshMaterials )
    delete[] g_pMeshMaterials;

다음의 샘플 코드에서는, 로드 된 각 텍스쳐의 할당을 해제해, 텍스쳐 리스트를 삭제하고 있다.

if( g_pMeshTextures )
{
    for( DWORD i = 0; i < g_dwNumMaterials; i++ )
    {
        if( g_pMeshTextures[i] )
            g_pMeshTextures[i]->Release();
    }
delete[] g_pMeshTextures;

다음의 샘플 코드에서는, 메쉬 오브젝트의 할당을 해제하고 있다.

Delete the mesh object
if( g_pMesh )
    g_pMesh->Release();

이 튜토리얼에서는, 메쉬의 로드와 렌더링의 방법을 나타냈다. 이 섹션의 튜토리얼은 이것으로 마지막이다. 표준적인 Direct3D 어플리케이션의 생성 방법에 대해서는, 「DirectX Graphics C/C++ 샘플」을 참조할것.


DirectX Graphics C/C++ 샘플

다음의 샘플 어플리케이션에는, Microsoft® Direct3D® 및 Direct3DX 어플리케이션 프로그래밍 인터페이스의 사용법과 기능이 나타나고 있다.

  • Billboard 샘플
  • BumpEarth 샘플
  • BumpLens 샘플
  • BumpUnderwater 샘플
  • BumpWaves 샘플
  • DotProduct3 샘플
  • Emboss 샘플
  • ClipMirror 샘플
  • DolphinVS 샘플
  • DXTex 툴
  • EnhancedMesh 샘플
  • CubeMap 샘플
  • FishEye 샘플
  • SphereMap 샘플
  • MFCFog 샘플
  • MFCPixelShader 샘플
  • MFCTex 샘플
  • OptimizedMesh 샘플
  • Pick 샘플
  • PointSprites 샘플
  • ProgressiveMesh 샘플
  • RTPatch 샘플
  • SkinnedMesh 샘플
  • ShadowVolume 샘플
  • StencilDepth 샘플
  • StencilMirror 샘플
  • Text3D 샘플
  • VertexBlend 샘플
  • VertexShader 샘플
  • VolumeTexture 샘플
  • Water 샘플

Microsoft DirectX® 샘플에는 Microsoft Visual C++® 프로젝트 워크 스페이스 파일이 포함되어 있지만, 독자의 개발 환경에서 올바르게 컴파일 할 수 있을지 어떨지를 확인할 필요가 있다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.

참조

DirectX Graphics C/C++ 튜토리얼


Billboard 샘플

설명

Billboard 샘플에서는, 빌딩 승선의 방법을 나타내고 있다. 다각형수가 많은 나무의 모델 등, 복잡한 3D 모델을 렌더링 하는 대신에, 모델의 2D 이미지를 렌더링 해, 항상 시점에 향하도록(듯이) 회전시킨다. 이 방법은, 목, 운, 연, 폭발등을 렌더링 하기 위해서, 일반적으로 사용된다. 상세한 것에 대하여는, 「빌딩 승선」을 참조할것.

이 샘플에서는, 카메라는 나무로 덮인 언덕의 3D 신을 비행한다. 나무는 3D 오브젝트와 같이 보이지만, 실제로는, 시점으로 향해 회전하는 2D 빌보드 이미지이다. 언덕의 지형 및 특별 관람석 (하늘의 텍스쳐를 포함한 입방체)은,. x 파일로부터 로드 되는 오브젝트이다. 이것들은 시각 효과를 위해서(때문에) 사용되어 빌딩 승선 방법과는 무관계하다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\Billboard

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

이 샘플에서는, 빌딩 승선 방법으로 중점을 두고 있다. 카메라는 각 프레임으로 이동해, 거기에 따라서 시점도 변화한다. 시점이 변화 하면, 빌보드가 새로운 시점의 분을 향하도록(듯이), y 축으로 따라 빌보드를 회전시키는 회전 행렬이 생성된다. 빌보드 행렬의 계산은 FrameMove 함수로 행해진다. 빌보드에는 보통 투명한 픽셀이 포함되어 있으므로, 적절한 알파 블렌딩을 실시하기 위해서(때문에), 나무도 이 함수에 저장 된다. 나무는,DrawTrees 함수로 버텍스 버퍼로부터 렌더링 된다.

이 샘플의 빌보드는, y 축으로 따라서만 회전하도록(듯이) 제한되고 있다. 이와 같이 하지 않으면 나무가지가 지면에 고정되어 있지 않은 것 처럼 보인다. 3D 항공 시뮬레이션 게임이나 스페이스 슈팅 게임의 폭발등의 효과에서는, 빌보드는 보통 1 개의 축으로 제약되지 않는다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft® DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 원시 코드는, (SDK 루트) \Samples\Multimedia\VBSamples 에 있다.


BumpEarth 샘플

설명

BumpEarth 샘플에서는, Microsoft® Direct3D® 의 범프 맵핑 기능을 나타낸다. 범프 맵핑은, 엉성한 요철이 있는 표면의 외관을 렌더링 하는 텍스쳐 블렌딩 방법이다. 이 샘플에서는, 회전하는, 범프 맵핑 처리된 지구를 렌더링 한다.

범프 맵핑 방법의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 일부의 하드웨어에서는, 범프 맵핑을 지원 하고 있지 않는 경우나, 일부 밖에 지원 하고 있지 않는 경우가 있다. 범프 맵핑의 상세한 것에 대하여는, 「범프 맵핑」을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\BumpMapping\BumpEarth

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

범프 맵은 섭동 데이터를 보존하는 텍스쳐이다. 범프 맵핑은 2 개의 텍스쳐를 필요로 한다. 1 개(살)은 환경 맵으로, 장면내에서 표시되는 라이트가 포함된다. 이제(벌써) 1 개(살)은 실제의 범프 맵핑이며, 환경 맵의 텍스쳐 좌표를 범프 하기 위해서 사용되는 값 (du 및 dv)이 포함된다. 일부의 범프 맵에서는, 특정의 텍셀의 빛남을 제어하는 휘도의 값도 포함된다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


BumpLens 샘플

설명

BumpLens 샘플에서는, 범프 맵핑을 사용해 실현될 수 있는 렌즈의 이펙트를 나타낸다. 범프 맵핑은, 엉성한 요철이 있는 표면의 외관을 렌더링 하는 멀티 텍스쳐 블렌딩 방법이지만, 여기에 나타내도록(듯이), 다른 이펙트에도 사용할 수 있다.

범프 맵핑 방법의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 일부의 하드웨어에서는, 범프 맵핑을 지원 하고 있지 않는 경우나, 일부 밖에 지원 하고 있지 않는 경우가 있다. 범프 맵핑의 상세한 것에 대하여는, 「범프 맵핑」을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\BumpMapping\BumpLens

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

범프 맵은 섭동 데이터를 보존하는 텍스쳐이다. 범프 맵핑은 2 개의 텍스쳐를 필요로 한다. 1 개(살)은 환경 맵으로, 장면내에서 표시되는 라이트가 포함된다. 이제(벌써) 1 개(살)은 실제의 범프 맵핑이며, 환경 맵의 텍스쳐 좌표를 범프 하기 위해서 사용되는 값 (du 및 dv)이 포함된다. 일부의 범프 맵에서는, 특정의 텍셀의 빛남을 제어하는 휘도의 값도 포함된다.

이 샘플에서는, 종래의 방법과는 다른 방법으로 범프 맵핑을 사용한다. 범프 맵핑은 환경 맵을 섭동 하므로, 다른 이펙트에도 사용할 수 있다. 여기에서는, 백그라운드 이미지를 섭동 해 (그 자리에서 렌더링 할 수 있다), 렌즈의 이펙트를 생성 하고 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, 다음의 장소에 있다. (SDK 루트) \Samples\Multimedia\Common


BumpUnderwater 샘플

설명

BumpLens 샘플에서는, 범프 맵핑을 사용해 실현될 수 있는 수중의 이펙트를 나타낸다. 범프 맵핑은, 엉성한 요철이 있는 표면의 외관을 렌더링 하는 멀티 텍스쳐 블렌딩 방법이지만, 여기에 나타내도록(듯이), 다른 이펙트에도 사용할 수 있다.

범프 맵핑 방법의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 일부의 하드웨어에서는, 범프 맵핑을 지원 하고 있지 않는 경우나, 일부 밖에 지원 하고 있지 않는 경우가 있다. 범프 맵핑의 상세한 것에 대하여는, 「범프 맵핑」을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\BumpMapping\BumpUnderWater

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

범프 맵은 섭동 데이터를 보존하는 텍스쳐이다. 범프 맵핑은 2 개의 텍스쳐를 필요로 한다. 1 개(살)은 환경 맵으로, 장면내에서 표시되는 라이트가 포함된다. 이제(벌써) 1 개(살)은 실제의 범프 맵핑이며, 환경 맵의 텍스쳐 좌표를 범프 하기 위해서 사용되는 값 (du 및 dv)이 포함된다. 일부의 범프 맵에서는, 특정의 텍셀의 빛남을 제어하는 휘도의 값도 포함된다.

이 샘플에서는, 종래의 방법과는 다른 방법으로 범프 맵핑을 사용한다. 범프 맵핑은 환경 맵을 섭동 하므로, 다른 이펙트에도 사용할 수 있다. 여기에서는, 백그라운드 이미지를 섭동 해 (그 자리에서 렌더링 할 수 있다), 수중의 이펙트를 생성 하고 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


BumpWaves 샘플

설명

BumpWave 샘플에서는, Microsoft® Direct3D® 의 범프 맵핑 기능을 나타낸다. 범프 맵핑은, 엉성한 요철이 있는 표면의 외관을 렌더링 하는 멀티 텍스쳐 블렌딩 방법이다. 이 샘플에서는, 4 개의 삼각형만으로 물가의 장면을 렌더링 하고 있다. 장면내의 물결은 모두 범프 맵을 사용해 생성 되고 있다.

범프 맵핑 방법의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 일부의 하드웨어에서는, 범프 맵핑을 지원 하고 있지 않는 경우나, 일부 밖에 지원 하고 있지 않는 경우가 있다. 범프 맵핑의 상세한 것에 대하여는, Microsoft DirectX® SDK 의 메뉴얼을 참조할것.

이 샘플에서는, 투영 텍스쳐로 불리는 텍스쳐 좌표 생성 방법도 사용하지만, 이 샘플의 중심은 아니다. 텍스쳐 좌표의 생성의 상세한 것에 대하여는, 「범프 맵핑」을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\BumpMapping\BumpWaves

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

범프 맵은 섭동 데이터를 보존하는 텍스쳐이다. 범프 맵핑은 2 개의 텍스쳐를 필요로 한다. 1 개(살)은 환경 맵으로, 장면내에서 표시되는 라이트가 포함된다. 이제(벌써) 1 개(살)은 실제의 범프 맵핑이며, 환경 맵의 텍스쳐 좌표를 범프 하기 위해서 사용되는 값 (du 및 dv)이 포함된다. 일부의 범프 맵에서는, 특정의 텍셀의 빛남을 제어하는 휘도의 값도 포함된다.

이 샘플에서는, 범프 맵핑을 사용해 장면내의 물결을 생성하고 있다. 배경은 환경 맵의 투영 텍스쳐로서 사용되고 있으므로, 물결로 반사한다. 물결 자체는, 많은 다각형을 사용해 생성된 것처럼 보인다. 그러나, 그것은 1 개의 큰 사각형이다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


DotProduct3 샘플

설명

DotProduct3 샘플에서는, Microsoft® Direct3D® 의 범프 맵핑의 다른 어프로치를 나타낸다. 이 방법은, 라이트의 벡터와 표면의 법선을 조합하는 수학적인 처리를 기념하여 이름을 붙일 수 있고 있다. 표면의 법선은, RGBA 포맷으로 텍스쳐 맵 (이 방법에서는 법선 맵으로 불린다)에 보존되는 종래의 (x, y, z) 벡터이다.

모든 카드가 DotProduct3 블렌딩 텍스쳐 스테이지를 지원 하고 있는 것은 아니고, 모든 카드가 Direct3D 범프 맵핑을 지원 하고 있는 것도 아니다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\BumpMapping\DotProduct3

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

범프 맵핑을 시뮬레이트 하는 라이팅의 방정식에서는, 표면의 법선과 라이팅의 벡터의 내적을 사용한다. 라이팅의 벡터는 텍스쳐 계수에게 건네져 법선은 텍스쳐 맵에 encode 된다. 블렌딩 스테이지는 다음과 같이 된다.

SetTextureStageState( 0, D3DTSS_COLOROP, D3DTOP_DOTPRODUCT3 );
SetTextureStageState( 0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
SetTextureStageState( 0, D3DTSS_COLORARG2, D3DTA_TFACTOR );

다음의 순서는, 법선을 텍스쳐에 보존하는 것이다. 이것을 실시하기 위해서(때문에), 벡터의 요소 (XYZW)는 각각, 32 비트 부동 소수점수(실수)값으로부터 부호 첨부 8 비트 정수에 변환되어 텍스쳐 칼라 (RGBA)에 팩 된다. 코드에서는, 독자적으로 생성한 법선 맵, 및 범프 맵핑 텍스쳐 이미지로부터 구축된 법선 맵을 사용해, 이것을 실시하는 방법을 나타내고 있다.

범프 맵핑 방법의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 일부의 하드웨어에서는, 범프 맵핑을 지원 하고 있지 않는 경우나, 일부 밖에 지원 하고 있지 않는 경우가 있다. 범프 맵핑의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


Emboss 샘플

설명

Emboss 샘플에서는, Microsoft® Direct3D® 의 범프 맵핑의 다른 어프로치를 나타낸다. 앰보스는 자기 자신으로부터 높이 맵을 꺼내, 조금 변경된 텍스쳐 좌표를 가지는 것에 의해 행해진다.

Direct3D 의 범프 맵핑을 지원 하고 있지 않는 카드도 있다. 상세한 것에 대하여는, Microsoft DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\Emboss

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.
Ctrl-E | 앰보스 이펙트의 온/오프를 바꾼다.

프로그래밍 위에의 주의

범프 맵은 섭동 데이터를 보존하는 텍스쳐이다. 범프 맵핑은 2 개의 텍스쳐를 필요로 한다. 1 개(살)은 환경 맵으로, 장면내에서 표시되는 라이트가 포함된다. 이제(벌써) 1 개(살)은 실제의 범프 맵핑이며, 환경 맵의 텍스쳐 좌표를 범프 하기 위해서 사용되는 값 (du 및 dv)이 포함된다. 일부의 범프 맵에서는, 특정의 텍셀의 빛남을 제어하는 휘도의 값도 포함된다.

이 샘플에서는, 범프 맵은 호랑이의 표피의 앰보스에 사용되고 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


ClipMirror 샘플

설명

ClipMirror 샘플에서는, 독자적으로 정의한 클립면의 사용법을 나타낸다. 3D 신은 보통 대로 렌더링 되어 2 번째의 패스로 평면의 거울에 반사된 것처럼 렌더링 된다. 클립면은, 반사된 장면을 거울의 엣지에서 잘라내기 위해서(때문에) 사용한다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\ClipMirror

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

이 샘플에서는, 마우스를 사용해 시점의 위치를 제어할 수 있다.

프로그래밍 위에의 주의

이 샘플의 주된 특징은, 클립면의 사용법이다. 직사각형의 거울에는 4 개의 엣지가 있으므로, 4 개의 클립면이 사용된다. 각 클립면은, 시점과 거울의 1 개의 엣지의 2 개의 버텍스에 의해 정의된다. 클립면을 배치 하면, 뷰 행렬은 거울의 평면에서 반사되어 장면의 지오메트리 (티폿트오브제크트)는 보통 대로 렌더링 할 수 있다. 그 후, 거울 자체를 나타내는 반투명의 직사각형이 드로잉(Drawing) 된다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


DolphinVS 샘플

설명

DolphinVS 샘플에서는, 돌고래와 해저에 코스티크에페크트를 적용한, 돌고래가 헤엄치는 수중의 장면을 나타낸다. 돌고래는 트이닝으로 불리는 방법을 사용해 애니메이션 된다. 수중의 이펙트에는 fog를 사용해, 워터 코스 디크스에는 텍스쳐의 애니메이션 세트를 사용하고 있다. 이러한 이펙트는, 버텍스 쉐이더를 사용해 실현되고 있다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\DolphinVS

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

이 샘플에서는, 복수의 처리를 하고 있다.

  • 2 개의 버텍스 쉐이더가 사용되고 있다. 1 개(살)은 돌고래에, 이제(벌써) 1 개(살)은 해저에 사용되고 있다. 버텍스 쉐이더는, DolphinTween.vsh 와 SeaFloor.vsh 의 2 개의 파일로부터 어셈블(assemble) 되는 어셈블리 명령이다.
  • 돌고래에는 트이닝 (morphing의 일종)이 적용된다. 이것을 실시하기 위해서(때문에), 복수의 버텍스 스트림으로 3 종류의 돌고래가 건네받는다. 버텍스 쉐이더는, 각 메쉬의 중요 된 좌표 위치를 사용해, 출력 위치를 생성한다. 다음에, 버텍스가 라이팅 되어 텍스쳐 좌표가 계산되어 fog가 추가된다.
  • 해저도 이와 같이 처리되지만, 트이닝의 필요는 없다. 코스티크에페크트는, 32 의 텍스쳐세트를 애니메이션 해, 다른 알파 블렌딩 패스로 추가된다. 코스 디크스의 텍스쳐 좌표는 버텍스 쉐이더로 생성되어 TEXCOORDINDEX 스테이지 1 으로서 보존된다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft® DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


DXTex 툴

설명

DXTex 툴을 사용하면(자), DirectX SDK 유저는 새로운 DXTn 압축 포맷을 사용해 텍스쳐 맵을 생성 할 수 있다. DXTn 로 압축된 텍스쳐의 생성은 어렵지 않다. 다만, Direct3D 에서는 IDirect3DTexture8 인터페이스를 사용하면(자), 자동적으로 이 변환을 실시할 수가 있다. 지식이 있는 개발자이면, 특정의 용도에 맞은 독자적인 툴을 생성 할 수도 있지만, DXTex 툴에는 도움이 되는 기본적인 기능이 준비되어 있다.

기능

  • . bmp 및 DirectDrawSurface (DDS) 파일을 연다. 상세한 것에 대하여는, 후의 「DDS 파일 포맷」을 참조할것.
  • . bmp 파일을 명시적 또는 비명시적으로 알파 채널로서 연다 (<filename>_a.bmp 의 명명 규칙을 사용).
  • 텍스쳐를 DDS 포맷으로 보존한다.
  • 5 개의 DXTn 압축 포맷 모두에의 변환을 지원 한다.
  • 밉맵의 생성을 지원 한다 (박스 필터를 사용).
  • 그레이 스케일 이미지 또는 유저가 선택 가능한 배경색에 의해 알파 채널의 시각화를 지원 한다.
  • 포맷마다의 화질을 시각적으로 용이하게 비교할 수 있다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\DXTex

실행 가능 파일 :(SDK 루트) \bin\dxutils

유저 인터페이스

DxTex 에서는, 각 텍스쳐 맵은 문서이며, 복수의 문서를 한 번에 열릴 수가 있는, 일반적인 유저 인터페이스 (UI)를 사용하고 있다. 다만, 문서를 DxTex 로 열려 있는 동안은, 각 문서에서는 1 개 또는 2 개의 포맷으로 텍스쳐를 보관 유지할 수 있다. 예를 들어,. bmp 파일을 임포트 해, 자동적으로 32 비트 ARGB 텍스쳐를 생성 할 수 있다. 다음에, 이 텍스쳐를 DXT1 포맷으로 변환한다. 이 시점에서, 문서에는 이미지가 2 개의 포맷으로 열리고 있다. 포맷을 바꾸려면 , 윈도우를 클릭하는지,[View] 메뉴의 [Original View] 또는 [New View] 를 클릭한다. 이 방법을 사용 하면, 이미지 압축에 의해 생기는 부자연스러운 효과를 확인할 수 있어 이미지를 단계적으로 열화 시키는 일 없이 다른 압축 형식을 시험할 수가 있다. 예를 들어, 이 방법을 사용하지 않고 , 이미지를 ARGB 로부터 DXT1 로 변환하면(자), 알파의 1 비트를 제외한 모든 비트가 없어진다.

그 후, DXT2 로 변환해도, 알파 레벨은 2 개 밖에 존재하지 않게 된다. DxTex 시스템에서는, 이 2 번째의 변환은 원의 ARGB 포맷화 라행 깨져 변환된 DXT2 이미지에는, DXT2 가 지원 하는 16 레벨의 알파가 모두 포함된다. 이 이미지를 보존 하면, 원의 포맷은 파기되어 새로운 포맷만이 보존된다.

DxTex 인터페이스를 사용할 때에는, 다음의 점에 주의 해야 한다.

  • 파일이 열리고 나서 포맷의 변환이 전혀 요구되지 않았던 경우, 그 1 개의 포맷이 원의 포맷이 되어, 파일을 보존할 경우에는 그 포맷으로 이미지가 기입해진다.
  • 파일이 열리고 나서 포맷의 변환이 요구되었을 경우, 변환된 포맷이 새로운 포맷이 되어, 파일을 보존 하면 그 포맷으로 이미지가 기입해진다.
  • 2 번째의 변환이 요구되었을 경우, 최초의 변환으로 생성 된 「새롭다」포맷이 제 2 의 포맷으로 옮겨진다. 원의 포맷은 변경되지 않는다.
  • 밉맵의 생성은, 양쪽 모두의 포맷에 동시에 적용된다.
  • 원의 포맷에 복수의 밉맵이 있어, 새로운 포맷에의 변환이 요구되었을 경우, 새로운 포맷에도 자동적으로 복수의 밉맵이 존재하게 된다.

퍼포먼스

DxTex 에서는, 3D 하드웨어가 사용 가능한가 어떤가에 관계없이, Microsoft Direct3D® 레퍼런스 래스터라이저를 사용해 텍스쳐를 드로잉(Drawing) 한다. 따라서, 텍스쳐가 큰 (256x256 픽셀을 넘는다) 경우, 어플리케이션은 CPU 의 속도에 응해 약간 늦어지는 일이 있다.

DSS 파일 포맷

DxTex 네이티브 파일 포맷은, DirectDrawSurface 에 정보를 캡슐화하므로, DDS 파일 포맷으로 불린다. DDS 파일의 포맷은, 다음과 같다.

DWORD dwMagic (0x20534444, 또는 "DDS")
DDSURFACEDESC2 ddsd (표면 포맷에 관한 정보를 제공한다)
BYTE bData1[] (메인 표면의 표면 데이터)
[BYTE bData2[]...] (어태치 되는 표면의 표면 데이터)

이 포맷은 읽고 쓰기가 간단해, DXTn 압축 뿐만이 아니라, 알파나 마르치밉레벨등의 기능도 지원 한다. DirectX SDK 의 Compress 샘플 어플리케이션에서는, DDS 파일을 올바르게 임포트 하는 방법을 나타내고 있다.

DXTn 압축한 텍스쳐를 사용하기 위해서 DDS 포맷을 사용할 필요는 없고, 그 역의 경우도 마찬가지이지만, 이것들 2 개(살)은 제휴하고 있다.

밉맵

밉맵은, 복수의 해상도로 미리 필터 처리된 텍스쳐 이미지를 제공하는 것에 의해, 화질을 향상시켜, 텍스쳐 메모리의 대역폭을 감소시키는 방법이다.

DxTex 의 밉맵을 생성하려면 , 소스 이미지의 폭과 높이가 모두 2 의 거듭제곱이 되어 있을 필요가 있다. 이 밉맵을 생성하려면 ,[Format] 메뉴의 [Generate Mip Maps] 를 클릭한다. 필터 링은, 단순한 박스 필터로 실행된다. 즉, 가장 가까운 4 개의 픽셀이 평균화되어 목적의 픽셀이 생성 된다.

알파

많은 텍스쳐 포맷에는, 각 픽셀의 불투명도의 정보를 제공하는 알파 채널이 포함되어 있다. DxTex 는 텍스쳐에 있어서의 알파를 완전 지원 한다.. bmp 파일을 임포트 하는 경우에, 사이즈가 같은 2 개의 파일이 존재해, 그 한편의 파일명이 "_a" 로 끝날 때는 (Sample.bmp 및 Sample_a.bmp 등),"_a" 로 끝나는 파일이 알파 채널로서 로드 된다. 이 2 번째의 . bmp 의 파랑의 채널이 알파 채널에 저장 된다. 파일을 연 후는,[File] 메뉴의 [Open As Alpha Channel] 를 클릭해, 명시적으로 . bmp 파일을 알파 채널로서 로드할 수 있다.

알파 채널을 RGB 채널없이 직접 표시하려면 ,[View] 메뉴의 [Alpha Channel Only] 를 클릭한다. 알파 채널이 그레이 스케일 이미지로서 표시된다. 알파 채널이 로드되어 있지 않은 경우, 모든 픽셀로 알파 채널은 100 퍼센트가 되어,[Alpha Channel Only] 를 선택 하면 이미지가 희게 전부 칠해진다. 알파 채널을 비표시로 하려면 ,[Alpha Channel Only] 를 한번 더 클릭한다.

보통의 뷰에서는 알파 채널의 효과가 눈에 보이지만, 이것은, 윈도우가 백그라운드 칼라로 전부 칠해지고 있어 알파 채널이 100 퍼센트 미만의 텍스쳐에서는, 그 색이 비쳐 보이기 때문이다. 백그라운드 칼라를 변경하려면 ,[View] 메뉴의 [Change Background Color] 를 클릭한다. 이 선택을 실행해도, 텍스쳐 그 자체, 또는 파일을 보존할 경우에 기입해지는 데이터에는 영향을 주지 않는다.

DXT2 포맷 및 DXT4 포맷에서는, 미리 계산된 알파가 사용된다. 즉, 표면에 저장 되는 적, 초록, 및 파랑의 값에는, 대응하는 알파값이 이미 곱셈되고 있다. Direct3D 에서는, 미리 계산된 알파가 포함되는 표면으로부터 미리 계산되어 있지 않은 알파가 포함되는 표면에 카피할 수 없다. 따라서, DxTex 의 일부의 처리 (알파 채널로서 여는, DXT3 에의 변환, 및 DXT5 에의 변환)는, DXT2 및 DXT4 포맷에서는 실행할 수 없다. DXTn 텍스쳐를 지원 하지 않는 Direct3D 디바이스에서는, 이러한 포맷을 사용한 텍스쳐를 지원 하는 것은 어렵다. 이것은, Direct3D 에서는 이러한 포맷을 종래의 ARGB 표면에도 카피할 수 없기 때문이다. ARGB 표면에서도 미리 계산된 알파가 사용되고 있는 경우는 카피할 수 있지만, 이러한 일은 보기 드물다. 이러한 이유로부터, 가능하면 DXT2 보다 DXT3 를, DXT4 보다 DXT5 를 사용하는 (분)편이 간단하다.

커멘드 라인 옵션

커멘드 라인 옵션을 사용해, 입력 파일, 출력 파일명, 및 처리 옵션을 DxTex 에 건네줄 수가 있다. 출력 파일명을 지정했을 경우는, 그 출력 파일을 기입한 후에 어플리케이션이 자동 종료해, 유저 인터페이스는 표시되지 않는다.

dxtex [infilename] [-a alphaname] [-m] [DXT1|DXT2|DXT3|DXT4|DXT5] [outfilename]

infilename:               로드하는 파일의 이름.
                          . bmp 또는 DDS 파일이 가능.

-a alphaname:             다음의 파라미터는 알파 채널로서
                          로드한다 . bmp 파일의 이름.
                          알파 파일명을 지정하지 않으면 DxTex 는
                          Infilename_a.bmp.  그렇다고 하는 이름의 파일을 찾아,
                          알파 채널로서 사용하는 것에
                          주의 해야 한다.

-m:                       밉맵이 생성된다.

DXT1|DXT2|DXT3|DXT4|DXT5: 압축 포맷. 포맷을 지정하지 않으면
                          이미지는 ARGB-8888 가 된다.

outfilename:              출력 파일명.   이 옵션을 지정하지 않으면
                          유저 인터페이스는 현재의 파일과
                          모든 필요한 조작을 표시한다.
                          출력 파일명을 지정 하면,
                          어플리케이션은 세이브 후,
                          유저 인터페이스를 표시하지 않고
                          종료한다.


EnhancedMesh 샘플

설명

EnhancedMesh 샘플에서는, D3DX 를 사용해 메쉬를 로드해 서브 디비전 하는 방법을 나타낸다. 메쉬는, 버텍스 카운트를 늘리는 것에 의해 서브 디비전 된다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\EnhancedMesh

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft® DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


CubeMap 샘플

설명

CubeMap 샘플에서는, 큐브 매핑으로 불리는 환경 매핑의 방법을 나타낸다. 환경 매핑은, 3D 오브젝트의 주위의 환경 (라이트등)을 텍스쳐 맵에 배치해, 라이팅의 계산을 실시하지 않고 오브젝트에 복잡한 라이팅 이펙트를 적용할 수 있는 방법이다.

환경 매핑의 방법 (큐브 매핑이나 투영 텍스쳐등)의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 환경 매핑, 큐브 매핑, 및 투영 텍스쳐의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\EnvMapping\CubeMap

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

큐브 매핑은, 6 면의 텍스쳐를 사용하는 방법이다. 이 방법의 이펙트를 시각화하려면 , 벽지를 붙인 방에 있는, 벽지로 축소 랩 된 오브젝트를 생각해 보면 좋다. 큐브 매핑은 구(공)체 매핑보다 우수하다. 이것은, 구(공)체 매핑이 본질적으로 뷰에 의존하기 때문이다 (구(공)체 맵은 특정의 시점을 염두에 두어 생성 된다). 또, 큐브 맵에서는 지오메트리의 일그러짐이 생기지 않기 때문에, 큐브 맵의 6 면 모두에 임해서,IDirect3DDevice8::SetRenderTarget 를 사용해 그 자리에서 생성할 수 있다.

큐브 매핑은, Microsoft Direct3D® 의 텍스쳐 좌표 생성에서도 사용할 수 있다. D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR 를 설정하는 것에 의해, Direct3D 는 버텍스의 반사 벡터로부터 큐브 맵의 텍스쳐 좌표를 생성하므로, 이 방법을 사용하면(자), 환경이 오브젝트로 반사되는 경우의 환경 매핑 이펙트를 용이하게 생성 할 수 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


FishEye 샘플

설명

FishEye 샘플에서는, 큐브 맵을 사용해 실현될 수 있는 어안 렌즈의 이펙트를 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\EnvMapping\FishEye

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

FishEye 샘플의 장면은, 백 버퍼는 아니고, 큐브 맵의 표면에 렌더링 된다. 다음에, 이 큐브 맵을, 지오메트리를 조금 비뚤어지게 해 장면을 반사하는 환경 맵으로서 사용한다. 여기에서는, 일부의 지오메트리가 어안 렌즈와 같이 된다. 큐브 매핑의 상세한 것에 대하여는, 「CubeMap 샘플」을 참조할것.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


SphereMap 샘플

설명

SphereMap 샘플에서는, 구(공)체 매핑으로 불리는 환경 매핑의 방법을 나타낸다. 환경 매핑은, 3D 오브젝트의 주위의 환경 (라이트등)을 텍스쳐 맵에 배치해, 라이팅의 계산을 실시하지 않고 오브젝트에 복잡한 라이팅 이펙트를 적용할 수 있는 방법이다.

환경 매핑의 방법 (큐브 매핑이나 투영 텍스쳐등)의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 환경 매핑, 큐브 매핑, 및 투영 텍스쳐의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\EnvMapping\SphereMap

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

구(공)체 매핑에서는, 모델링시에 미리 계산된, 크롬의 구(공)체에 의해 반사된 환경 전체를 포함한 텍스쳐 맵을 사용한다. 이 방법에서는, 각 버텍스에 대해, 그 법선을 계산해, 그 법선이 크롬의 구(공)체상에서 일치하는 위치를 찾아내, 그 텍스쳐 좌표를 버텍스에 할당한다.

매칭은 복잡하지 않지만, 각 프레임의 각 버텍스에 대해 계산이 필요하다. Direct3D 에는, 이 때문에 사용할 수 있는 텍스쳐 좌표 생성 기능이 있다. 관련하는 렌더링 스테이트 처리는 D3DTSS_TCI_CAMERASPACENORMAL 로, 카메라 공간에서의 버텍스의 법선을 사용해, 텍스쳐 트랜스 폼에 의해 변형해, 텍스쳐 좌표를 생성한다. 다음에, 텍스쳐 행렬을 설정해 나머지의 처리를 실시한다. 이 단순한 케이스에서는, 행렬은, 카메라 공간 (-1, +1)으로부터 텍스쳐 공간 (0,1)을 취득하기 위해서, 텍스쳐 좌표를 스케일링 해, 평행이동 하는 것만으로 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


MFCFog 샘플

설명

MFCFog 샘플에서는, CFormView 를 사용해, Microsoft® Direct3D® 를 Microsoft Foundation Classes (MFC)와 함께 사용하는 방법을 나타낸다. 다양한 컨트롤을 사용해, 3D 신의 fog 파라미터를 제어한다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\MFCFog

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

이 샘플에서의 유저의 조작은 모두, 표시 가능한 MFC 컨트롤 (슬라이더, 라디오 버튼등)에 의해 이행 된다. 유저는 컨트롤을 조작해, 렌더링 한 3D 신으로 다양한 이펙트를 표시할 수 있다.

프로그래밍 위에의 주의

모든 MFC 코드는, CFormView 클래스의 파생 멤버 함수와 함께 저장 되고 있다. MFC 코드 및 D3D 초기화 코드는, D3dapp.cpp 원시 파일에 기술되고 있다. 이 파일은, fog 관련의 코드를 꺼내, 다른 어플리케이션으로 동작하도록(듯이) 이식할 수 있다.

Direct3D 의 fog 코드는 Fog.cpp 에 기술되고 있다. 이 파일에는, 장면을 초기화, 애니메이션, 렌더링, 및 클린 업하기 위한 함수도 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


MFCPixelShader 샘플

설명

MFCFog 샘플에서는, CFormView 를 사용해, Microsoft® Direct3D® 를 Microsoft Foundation Classes (MFC)와 함께 사용하는 방법을 나타낸다. 다양한 컨트롤을 사용해, 3D 신용의 픽셀 쉐이더를 제어한다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\MFCPixelShader

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

이 샘플에서의 유저의 조작은 모두, 표시 가능한 MFC 컨트롤 (슬라이더, 라디오 버튼등)에 의해 이행 된다. 유저는 컨트롤을 조작해, 렌더링 한 3D 신으로 다양한 이펙트를 표시할 수 있다.

프로그래밍 위에의 주의

모든 MFC 코드는, CFormView 클래스의 파생 멤버 함수와 함께 저장 되고 있다. MFC 코드 및 D3D 초기화 코드는, D3dapp.cpp 원시 파일에 기술되고 있다. 이 파일은, fog 관련의 코드를 꺼내, 다른 어플리케이션으로 동작하도록(듯이) 이식할 수 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


MFCTex 샘플

설명

MFCTex 샘플에서는, CFormView 를 사용해, Microsoft® Direct3D® 를 Microsoft Foundation Classes (MFC)와 함께 사용하는 방법을 나타낸다. 다양한 컨트롤을 사용해, 텍스쳐의 외관을 제어한다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\MFCTex

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

이 샘플에서의 유저의 조작은 모두, 표시 가능한 MFC 컨트롤 (슬라이더, 라디오 버튼등)에 의해 이행 된다. 유저는 컨트롤을 조작해, 렌더링 한 3D 신으로 다양한 이펙트를 표시할 수 있다.

프로그래밍 위에의 주의

모든 MFC 코드는, CFormView 클래스의 파생 멤버 함수와 함께 저장 되고 있다. MFC 코드 및 D3D 초기화 코드는, D3dapp.cpp 원시 파일에 기술되고 있다. 이 파일은, fog 관련의 코드를 꺼내, 다른 어플리케이션으로 동작하도록(듯이) 이식할 수 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


OptimizedMesh 샘플

설명

OptimizedMesh 샘플에서는, D3DX 메쉬 유틸리티 함수를 사용해, 파일 베이스의 메쉬를 로드해 최적화하는 방법을 나타낸다.

D3DX 의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\OptimizedMesh

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.
Ctrl-O | 메쉬 파일을 연다.
Ctrl-M | 가장 효과적인 메쉬를 바꾼다.

프로그래밍 위에의 주의

DirectX SDK 에 포함되는 많은 Microsoft Direct3D® 의 샘플에서는, 파일 베이스의 메쉬가 사용되고 있다. OptimizedMesh 샘플은, 메쉬를 로드하는데 필요한 기본적인 코드가 좋은 예이다. D3DX 메쉬 로드 기능은,. x 파일의 프레임 계층을 1 개의 메쉬에 정리한다.

다른 샘플에서는, 순수한 D3DX 메쉬 기능은 공통 클래스 CD3DMesh 에 랩 되고 있다. 프레임 계층을 보관 유지하는 경우는, 공통 클래스 CD3DFile 를 사용할 수 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


Pick 샘플

설명

Pick 샘플에서는, 피킹을 이행 하는 방법을 나타낸다. 피킹이란, 메쉬내의 어느 삼각형이 레이에 해당될까를 찾아내는 것이다. 여기에서는, 레이는 마우스 좌표로 지정한다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\Pick

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

마우스를 사용해 메쉬내의 임의의 스포트를 픽 하면, 그 삼각형이 표시된다.

프로그래밍 위에의 주의

마우스를 클릭 하면, 커서의 화면 좌표가 읽어내진다. 이러한 좌표는, 투영 행렬 및 뷰 행렬에 의해 변환되어, 시점으로부터 스크린 위에의 클릭한 위치를 지나 장면에 이르는 레이로 바뀐다. 이 레이는, 로드 된 모델의 각 삼각형과 함께 IntersectTriangle 에게 건네져 어느 삼각형이 레이에 해당될지가 결정된다. 맞는 삼각형의 텍스쳐 좌표도 결정된다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft® DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


PointSprites 샘플

설명

PointSprites 샘플에서는, Microsoft® Direct3D® 의 새로운 포인트 스프라이트 기능의 사용법을 나타낸다. 포인트 스프라이트란, (x, y, z) 위치 좌표에 의해서만 참조되는 적극적인, 텍스쳐 처리된 사각형이다. 포인트 스프라이트는, 입자 시스템 및 관련 이펙트로 자주(잘) 사용된다.

포인트 스프라이트의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 포인트 스프라이트의 상세한 것에 대하여는, Microsoft DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\PointSprites

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
W, S | 전후로 이동한다.
E, Q | 좌우로 이동한다.
A, Z | 상하에 회전한다.
커서 키 | 상하 좌우에 슬라이드한다.
F1 | 헬프 또는 사용 가능한 커멘드를 표시한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
F3 | 이미터를 애니메이션 한다.
F4 | 색을 변경한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

Direct3D 지원을 사용하지 않는 경우는, 포인트 스프라이트는 각 프레임을 빌보드와 같게 시점에 향하는 4 개의 버텍스를 사용해 이행 할 수 있다. Direct3D 를 사용하는 경우는, 포인트 스프라이트의 중심 위치와 반경에 의해, 각 포인트 스프라이트를 참조할 수 있다. 이것에 의해, 프로세서의 계산 시간과 버텍스 정보를 그래픽 카드에 업 로드하기 위한 대역폭을 절약할 수 있다.

이 샘플에서는, 각 파티클은, 복수의 알파 블렌딩 된 포인트 스프라이트를 사용해, 파티클에 모션브라에페크트를 주어 실현되고 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


ProgressiveMesh 샘플

설명

ProgressiveMesh 샘플에서는, D3DX 메쉬 유틸리티 함수를 사용해, 파일 베이스의 메쉬를 로드해 최적화하는 방법을 나타낸다. 프로그래시브 메쉬에서는, 버텍스 정보가 특수한 트리에 보존되어 임의의 수의 버텍스를 지정해 메쉬를 렌더링 하기 위해서 액세스 할 수 있다. 이 처리는 고속의의로, 프로그래시브 메쉬는, 멀리 있는 오브젝트가 적은 다각형으로 렌더링 되는 상세 레벨을 사용하는 경우에 적절하고 있다.

D3DX 의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\ProgressiveMesh

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F1 | 헬프 또는 사용 가능한 커멘드를 표시한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.
↑ | 프로그래시브 메쉬에 버텍스를 1 개 추가한다.
↓ | 프로그래시브 메쉬로부터 버텍스를 1 개 줄인다.
PageUp | 프로그래시브 메쉬에 버텍스를 100 개 추가한다.
PageDown | 프로그래시브 메쉬로부터 버텍스를 100 개 줄인다.
Home | 프로그래시브 메쉬에 사용 가능한 버텍스를 모두 표시한다.
End | 프로그래시브 메쉬의 최저한의 버텍스를 표시한다.

프로그래밍 위에의 주의

DirectX SDK 에 포함되는 많은 Microsoft Direct3D® 의 샘플에서는, 파일 베이스의 메쉬가 사용되고 있다. ProgressiveMesh 샘플은, 메쉬를 로드하는데 필요한 기본적인 코드가 좋은 예이다. D3DX 메쉬 로드 기능은,. x 파일의 프레임 계층을 1 개의 메쉬에 정리한다.

프로그래시브 메쉬를 사용하는 제 1 의 이유는, 메쉬에 대해 ID3DXPMesh::SetNumVertices 를 호출하는 것이다.

다른 샘플에서는, 기본적인 D3DX 메쉬 기능은 공통 클래스 CD3DMesh 에 랩 되고 있다. 프레임 계층을 보관 유지하는 경우는, 공통 클래스 CD3DFile 를 사용할 수 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


RTPatch 샘플

설명

RTPatch 샘플은, Direct3D 로 패치를 사용하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\RTPatch

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F1 | 헬프 또는 사용 가능한 커멘드를 표시한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.
↑ | 세그먼트(segment) 근처의 패치수를 늘린다.
↓ | 세그먼트(segment) 근처의 패치수를 줄인다.
W | 와이어 프레임을 바꾼다.

프로그래밍 위에의 주의

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


SkinnedMesh 샘플

설명

SkinnedMesh 샘플은, 스킨 메쉬의 로드 방법 및 렌더링 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\SkinnedMesh

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


ShadowVolume 샘플

설명

ShadowVolume 샘플에서는, 스텐실 버퍼를 사용해, 리얼타임의 그림자를 실현하고 있다. 이 샘플에서는, 복잡한 오브젝트가 렌더링 되어, 그림자를 캐스트 하는 오브젝트로서 사용되어 그 오브젝트 자체 및 그 아래의 지형에 리얼타임의 그림자를 캐스트 하고 있다.

스텐실 버퍼는, 지오메트리를 렌더링 할 경우에 갱신할 수 있는 깊이 버퍼의 방법으로, 다른 지오메트리를 드로잉(Drawing)하기 위한 마스크로서 재차 사용할 수 있다. 일반적인 이펙트에는, 경, (고도의 방법으로서의) 영, 디조르브등이 있다.

스텐실 버퍼 방법의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 일부의 하드웨어에서는, 스텐실 버퍼를 지원 하고 있지 않는 경우나, 일부 밖에 지원 하고 있지 않는 경우가 있다. 스텐실 버퍼의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\StencilBuffer\ShadowVolume

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

리얼타임의 그림자의 생성은 꽤 고도의 방법이다. 각 프레임으로, 즉 장면내의 지오메트리 또는 라이트가 이동할 경우에, 그림자 볼륨으로 불리는 오브젝트가 계산된다. 그림자 볼륨은, 광원으로부터 밀어 내졌을 때의, 그림자를 캐스트 하는 오브젝트의 실루엣인 3D 오브젝트이다.

이 샘플에서는, 그림자를 캐스트 하는 3D 오브젝트는 복엽기이다. 비행기의 실루엣은 각 프레임으로 계산된다. 이 방법에서는, 엣지 검출 알고리즘을 사용해, 실루엣의 엣지를 검출한다. 인접하는 다각형의 법선에는 빛의 벡터에 관해서, 반대 방향으로 성장하는 법선이 있기 (위해)때문에, 이러한 엣지 검출이 가능하다. 검출된 엣지 리스트 (실루엣)는, 광원으로부터 멀어지도록(듯이) 밀어 내져 3D 오브젝트가 된다. 이 3D 오브젝트는, 이 볼륨의 안쪽에 있는 모든 포인트가 그림자안에 있으므로, 그림자 볼륨으로 불린다.

다음에, 그림자 볼륨은, 스텐실 버퍼에 2 회 렌더링 된다. 처음은 적극적인 다각형만이 렌더링 되어 스텐실 버퍼값이 매회 인크리먼트(increment) 된다. 다음에, 그림자 볼륨의 퇴행적인 다각형이 드로잉(Drawing) 되어 스텐실 버퍼의 값이 감소 된다. 보통, 인크리먼트(increment) 된 값과 감소 된 값은 모두 서로 지운다. 그러나, 장면은 이미 법선 지오메트리 (이 경우는 평면과 지형)를 사용해 렌더링 되고 있으므로, 일부의 픽셀은 그림자 볼륨을 렌더링 할 경우에 Z 버퍼 테스트에 합격하지 않는다. 스텐실 버퍼에 남은 값이, 그림자안의 픽셀에 대응한다.

마지막으로, 모든 것을 포함한 큰 사각형을 장면에 알파 블렌딩 할 경우에, 이 남은 스텐실 버퍼의 내용이 마스크로서 사용된다. 스텐실 버퍼를 마스크로서 사용하는 것에 의해, 그림자안의 픽셀만이 어두워진다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


StencilDepth 샘플

설명

StencilDepth 샘플에서는, 스텐실 버퍼를 사용해, 장면의 깊이 구조를 표시한다. 장면의 깊이 구조는, 각 픽셀의 평균 렌더링 회수로서 정의된다.

스텐실 버퍼는, 지오메트리를 렌더링 할 경우에 갱신할 수 있는 깊이 버퍼의 방법으로, 다른 지오메트리를 드로잉(Drawing)하기 위한 마스크로서 재차 사용할 수 있다. 일반적인 이펙트에는, 경, (고도의 방법으로서의) 영, 디조르브등이 있다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\StencilBuffer\StencilDepth

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

깊이 구조의 표시는, 장면의 퍼포먼스를 분석하기 위한 중요한 툴이다. 오바드로가 많은 장면에서는, 지오메트리를 전부터 순서에 늘어놓고 바꾸는 등, 장면의 최적화에 의해 퍼포먼스가 향상하는 경우가 있다.

스텐실 버퍼 방법의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 일부의 하드웨어에서는, 스텐실 버퍼를 지원 하고 있지 않는 경우나, 일부 밖에 지원 하고 있지 않는 경우가 있다. 스텐실 버퍼의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


StencilMirror 샘플

설명

StencilMirror 샘플에서는, 스텐실 버퍼를 사용해, 거울의 이펙트를 실현하고 있다. 이 샘플에서는, 물에 덮인 지형의 장면이, 상공을 비행하는 헬리콥터를 반사하는 물을 사용해 렌더링 되고 있다.

스텐실 버퍼는, 지오메트리를 렌더링 할 경우에 갱신할 수 있는 깊이 버퍼의 방법으로, 다른 지오메트리를 드로잉(Drawing)하기 위한 마스크로서 재차 사용할 수 있다. 일반적인 이펙트에는, 경, (고도의 방법으로서의) 영, 디조르브등이 있다.

스텐실 버퍼 방법의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 일부의 하드웨어에서는, 스텐실 버퍼를 지원 하고 있지 않는 경우나, 일부 밖에 지원 하고 있지 않는 경우가 있다. 스텐실 버퍼의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\StencilBuffer\StencilMirror

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

이 샘플에서는, 스텐실 버퍼를 사용해, 수면으로부터의 반사의 이펙트를 생성 하고 있다. 물의 지오메트리는 스텐실 버퍼에 렌더링 된다. 다음에, 이 스텐실 버퍼가 장면을 재차 렌더링하기 위한 마스크로서 사용된다. 이 때, 지오메트리가 상하 반대로 평행이동 되어 렌더링 되므로, 거울에 반사되어 있는 것처럼 보인다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


Text3D 샘플

설명

Text3D 샘플에서는, 3D 신내에 2D 텍스트를 드로잉(Drawing) 하는 방법을 나타낸다. 이것은, 통계 정보나 게임의 메뉴등을 표시할 경우에 편리하다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\Text3D

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

이 샘플에서는, 공통 클래스 CD3DFont 를 사용해, 3D 신내에 2D 텍스트를 표시한다. 이 클래스의 원시 코드는, 이 샘플로 가장 흥미로운 점이다. 이 클래스는, GDI 를 사용해 폰트를 로드해, 각 문자를 비트 맵으로서 출력한다. 다음에, 이 비트 맵을 사용해, 텍스쳐가 생성 된다.

CD3DFont 클래스의 DrawText 함수가 불려 가면(자), 버텍스 버퍼에, 위에서 생성 된 폰트 텍스쳐를 사용해 텍스쳐 처리된 다각형이 저장 된다. 다각형은, 2D 오버레이로서 드로잉(Drawing) 할 수도 있다. 통계 정보의 출력등에는 편리하다. 또, 다각형은, 3D 신에 완전하게 통합할 수도 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft® DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


VertexBlend 샘플

설명

VertexBlend 샘플에서는, 버텍스 블렌딩으로 불리는 방법 (서페스스키닝이라고도 불린다)을 나타낸다. 이 샘플에서는, 다양한 스포트로 구부러지도록(듯이) 생성 된 파일 베이스의 오브젝트를 표시한다.

버텍스 블렌딩은, 매끈매끈한 결합부나, 캐릭터 애니메이션에서의 잔손질등의 이펙트를 생성 하기 위해서 사용된다.

버텍스 블렌딩의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 버텍스 블렌딩의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\VertexBlend

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.
Ctrl-V | 커스텀 버텍스 쉐이더와 Direct3D 버텍스 블렌딩을 바꾼다.

프로그래밍 위에의 주의

버텍스 블렌딩에서는, 각 버텍스에 브렌드의 중량감을 관련지을 필요가 있다. 복수의 월드 트랜스 폼이 SetTransformState 를 사용해 설정되어 브렌드의 중량감에 의해, 각 버텍스를 배치할 경우에 각 월드 행렬에 어느 정도 영향을 줄까를 결정한다.

이 샘플에서는, 공통 헬퍼 코드를 사용해 메쉬가 로드 된다. 독자적인 버텍스 및 독자적인 FVF 가 어떻게 선언되어 메쉬의 구축에 사용되고 있을까에 주의 해야 한다. 메쉬 오브젝트에 대해서는,SetFVF 의 호출을 참조할것. 메쉬 헬퍼 코드를 사용하지 않는 경우도, 이 방법은 같다. 브렌드의 중량감을 가지는 버텍스를 저장 하는 버텍스 버퍼를 생성 해, 적절한 FVF 를 사용한다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


VertexShader 샘플

설명

VertexShader 샘플에서는, 버텍스 쉐이더를 사용해 실현될 수 있는 몇개의 이펙트를 나타낸다. 버텍스 쉐이더는 일련의 명령을 사용한다. 이 명령은, 3D 디바이스에 의해 버텍스 마다 실행되어 흥미로운 방법으로 버텍스의 프로퍼티 (위치, 법선, 색, 텍스쳐 좌표등)에 영향을 준다.

버텍스 쉐이더의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 버텍스 쉐이더의 상세한 것에 대하여는, Microsoft® DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\VertexShader

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
W, S | 전후로 이동한다.
E, Q | 좌우로 이동한다.
A, Z | 상하에 회전한다.
커서 키 | 상하 좌우에 슬라이드한다.
F1 | 헬프 또는 사용 가능한 커멘드를 표시한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

버텍스 쉐이더의 프로그래밍은 간단한 작업은 아니다. 상세한 것에 대하여는, Microsoft DirectX® SDK 의 메뉴얼을 참조할것.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


VolumeTexture 샘플

설명

VolumeTexture 샘플에서는, Microsoft® Direct3D® 의 새로운 볼륨 텍스쳐의 사용법을 나타낸다. 보통, 텍스쳐는 2D 이미지이다고 생각되어 폭과 높이를 가져, 그 텍셀은 2 개의 좌표 tu 와 tv 로 지정된다. 볼륨 텍스쳐는 이것을 3D 로 한 것으로, 폭, 높이, 및 깊이를 가져, 3 개의 좌표 tu, tv, tw 로 지정된다.

볼륨 텍스쳐는, 오합지졸의 fog, 폭발등이 재미있는 이펙트에 사용할 수 있다.

볼륨 텍스쳐의 일부의 기능 밖에 지원 하고 있지 않는 카드도 있다. 볼륨 텍스쳐의 상세한 것에 대하여는, Microsoft DirectX® SDK 의 메뉴얼을 참조할것.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\VolumeTexture

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

볼륨 텍스쳐는, 3D 텍스쳐보다 사용법이 어렵다. 이 샘플의 원시 코드에서는, 버텍스의 선언 ( 제 3 의 텍스쳐 좌표를 가진다), 텍스쳐의 생성 (깊이의 넓이를 가진다), 및 텍스쳐의 락 (이것도 제 3 의 넓이를 가진다)에 주의 해야 한다. 3D 래스터라이저는, 2D 텍스쳐의 경우와 같게, 텍셀값을 보간 한다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 DirectX 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


Water 샘플

설명

Water 샘플에서는, 쉐이더 파일에 보존되고 있는 D3DX 방법의 사용법을 나타낸다.

이 샘플에서는, 워터 코스 디크스를 포함한, 잔물결의 이펙트를 사용한, 건물내의 네모진 연못을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\Direct3D\Water

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\Direct3D\Bin

유저즈 가이드

다음의 표는 이행 되고 있는 키를 나타내고 있다. 메뉴 커멘드를 사용해 같은 조작을 실시할 수가 있다.

키 | 액션
Enter | 장면을 시작 및 정지한다.
Space | 장면을 조금씩 진행한다.
W, S | 전후로 이동한다.
E, Q | 좌우로 이동한다.
A, Z | 상하에 회전한다.
커서 키 | 상하 좌우에 슬라이드한다.
D | 물의 적하를 시작 한다.
PageDown | 다음의 방법을 표시한다.
PageUp | 전의 방법을 표시한다.
Shift + PageDown | 유효성의 확인을 하지 않고 , 다음의 방법을 표시한다.
Shift + PageUp | 유효성의 확인을 하지 않고 , 전의 방법을 표시한다.
F1 | 헬프 또는 사용 가능한 커멘드를 표시한다.
F2 | 새로운 렌더링 디바이스 또는 디스플레이 모드를 선택하도록(듯이) 유저에게 지시한다.
Alt + Enter | 풀 스크린 모드와 윈도우 모드를 바꾼다.
Esc | 어플리케이션을 종료한다.

프로그래밍 위에의 주의

이 샘플에서는, D3DX 쉐이더의 방법으로 중점을 두고 있다.

이 샘플에서는, 헬퍼 함수등의 프로그래밍 요소로부터 구성되는 공통의 Microsoft® DirectX® 코드를 사용하고 있다. 이 코드는 DirectX SDK 외의 샘플과 공유되고 있다. 공통의 헤더 및 원시 코드는, (SDK 루트) \Samples\Multimedia\Common 에 있다.


Direct3D C/C++ 레퍼런스

여기에서는, Microsoft® Direct3D® 가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 다음의 카테고리로 분류되고 있다.

  • 인터페이스
  • 함수
  • 매크로
  • 버텍스 쉐이더 선언자 매크로
  • 구조체
  • 열거형
  • 그 외의 형태
  • 텍스쳐 인수 플래그
  • 유연한 버텍스 포맷 플래그
  • FOURCC 코드
  • 반환값


인터페이스

여기에서는, Microsoft® Direct3D® 가 제공하는 COM 인터페이스의 레퍼런스 정보를 기술한다. Direct3D 에서는, 다음의 인터페이스가 사용된다.

  • IDirect3D8
  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DDevice8
  • IDirect3DIndexBuffer8
  • IDirect3DResource8
  • IDirect3DSurface8
  • IDirect3DSwapChain8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolume8
  • IDirect3DVolumeTexture8


IDirect3D8

Microsoft® Direct3D® 오브젝트를 생성 해, 오브젝트의 환경을 셋업 하려면 ,IDirect3D8 인터페이스의 메소드를 사용한다. 이 인터페이스에는, 디바이스의 능력을 열거 및 취득하기 위한 메소드가 포함된다.

IDirect3D8 인터페이스를 취득하려면 ,Direct3DCreate8 함수를 호출한다.

IDirect3D8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

생성 | CreateDevice
열거 | EnumAdapterModes
정보 | GetAdapterCount
 | GetAdapterDisplayMode
 | GetAdapterIdentifier
 | GetAdapterModeCount
 | GetAdapterMonitor
 | GetDeviceCaps
등록 | RegisterSoftwareDevice
검사 | CheckDepthStencilMatch
 | CheckDeviceFormat
 | CheckDeviceMultiSampleType
 | CheckDeviceType

모든 COM 인터페이스와 같이,IDirect3D8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3D8 및 PDIRECT3D8 형은,IDirect3D8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3D8 *LPDIRECT3D8, *PDIRECT3D8;

동작환경

헤더 : D3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

Direct3DCreate8


IDirect3D8::CheckDepthStencilMatch

스텐실 포맷이, 특정의 디스플레이 모드에서의 렌더링 타겟 포맷과 호환성이 있을지 어떨지를 조사한다.

HRESULT CheckDepthStencilMatch(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  D3DFORMAT AdapterFormat,
  D3DFORMAT RenderTargetFormat,
  D3DFORMAT DepthStencilFormat
);

파라미터

Adapter
[in] 조회하는 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다.
DeviceType
[in] 디바이스 타입을 식별하는 D3DDEVTYPE 열거형의 멤버.
AdapterFormat
[in] 어댑터로 사용되는 디스플레이 모드의 포맷을 식별하는,D3DFORMAT 열거형의 멤버.
RenderTargetFormat
[in] D3DFORMAT 열거형의 멤버. 테스트하는 렌더링 타겟 표면의 포맷을 지정한다.
DepthStencilFormat
[in] D3DFORMAT 열거형의 멤버. 테스트하는 스텐실 표면의 포맷을 지정한다.

반환값

스텐실 포맷이, 디스플레이 모드의 타겟 렌더링 포맷과 호환성이 있는 경우, 이 메소드는 D3D_OK 를 돌려준다.

파라미터의 1 개 이상이 무효인 경우는,D3DERR_INVALIDCALL 가 돌려주어지는 경우가 있다. 스텐실 포맷이, 디스플레이 모드의 타겟 렌더링 포맷과 호환성이 없는 경우, 이 메소드는 D3DERR_NOTAVAILABLE 를 돌려준다.

주의

이 메소드는, 특정의 깊이 포맷이 특정의 렌더링 타겟 포맷에서만 기능하는 하드웨어 렌더링으로 어플리케이션을 기능할 수 있도록(듯이) 하기 위해서 준비되어 있다.

다음의 코드는,CheckDeviceFormat 를 사용해 스텐실 포맷을 검증하는 방법을 나타내고 있다.

BOOL IsDepthFormatOk( D3DFORMAT DepthFormat, D3DFORMAT AdapterFormat,
                      D3DFORMAT BackBufferFormat ) {
    // 깊이 포맷이 존재하는 것을 확인한다.
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          D3DUSAGE_DEPTHSTENCIL,
                                          D3DRTYPE_SURFACE,
                                          DepthFormat);

    if( FAILED( hr ) ) return FALSE;

    // 깊이 포맷에 호환성이 있는 것을 확인한다.
    hr = pD3D->CheckDepthStencilMatch( D3DADAPTER_DEFAULT,
                                       D3DDEVTYPE_HAL,
                                       AdapterFormat,
                                       BackBufferFormat,
                                       DepthFormat);
    return SUCCEEDED( hr );
}

위에의 호출은,DepthFormat 이 AdapterFormat 및 BackBufferFormat 와 조합해 사용할 수 없는 경우, FALSE 를 돌려준다.

동작환경

헤더 : D3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3D8::CheckDeviceFormat

표면의 포맷이, 지정한 리소스 타입으로서 이용할 수 있을지 어떨지, 및 이 어댑터를 사용하는 디바이스로 텍스쳐, 스텐실 버퍼, 렌더링 타겟의 언젠가, 또는 이것들 3 개의 편성으로서 사용할 수 있을지 어떨지를 조사한다.

HRESULT CheckDeviceFormat(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  D3DFORMAT AdapterFormat,
  DWORD Usage,
  D3DRESOURCETYPE RType,
  D3DFORMAT CheckFormat
);

파라미터

Adapter
[in] 조회하는 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다. 이 값이 시스템의 디스플레이 어댑터의 수이상의 경우, 이 메소드는 D3DERR_INVALIDCALL 를 돌려준다.
DeviceType
[in] 디바이스 타입을 식별하는 D3DDEVTYPE 열거형의 멤버.
AdapterFormat
[in] 어댑터로 사용되는 디스플레이 모드의 포맷을 식별하는,D3DFORMAT 열거형의 멤버.
Usage
[in] CheckFormat 의 표면에 대해서 요구하는 사용 방법. 다음의 플래그의 어느 쪽인지 한편 또는 양쪽 모두를 지정할 수 있다.
D3DUSAGE_DEPTHSTENCIL
스텐실 표면으로서 사용할 수 있는 표면인 것을 나타낸다.
D3DUSAGE_RENDERTARGET
렌더링 타겟으로서 사용할 수 있는 표면인 것을 나타낸다. RType 파라미터의 값이 명확하게 특정의 용도를 시사하고 있는 경우, 어플리케이션은 Usage 파라미터를 0 으로 해 둘 수가 있다.
RType
[in] D3DRESOURCETYPE 열거형의 멤버. 조사하는 포맷과 함께 사용하는 것을 요구하는 리소스 타입을 지정한다.
CheckFormat
[in] D3DFORMAT 열거형의 멤버. Usage 로 지정한 방법으로 사용하는 표면의 포맷을 나타낸다.

반환값

지정한 포맷이, 지정한 디바이스 및 사용 방법과 호환성이 있는 경우, 이 메소드는 D3D_OK 를 돌려준다.

Adapter 의 값이 시스템의 디스플레이 어댑터의 수로 동일한지, 그것보다 큰 경우, 또는 DeviceType 가 지원되어 있지 않은 타입의 경우는,D3DERR_INVALIDCALL 를 돌려준다. 지정한 디바이스 및 사용 방법에서는 인정되지 않는 포맷의 경우는,D3DERR_NOTAVAILABLE 를 돌려준다.

주의

CheckDeviceFormat 의 일반적인 용도는, 특정의 스텐실 표면 포맷이 존재할지 어떨지를 확인하는 것이다. 열거 처리의 상세한 것에 대하여는, 「디바이스의 선택」을 참조할것. 다음의 코드는,CheckDeviceFormat 를 사용해 스텐실 포맷의 유무를 확인하는 방법을 나타내고 있다.

BOOL IsDepthFormatExisting( D3DFORMAT DepthFormat, D3DFORMAT AdapterFormat ) {
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          D3DUSAGE_DEPTHSTENCIL,
                                          D3DRTYPE_SURFACE,
                                          DepthFormat);

    return SUCCEEDED( hr );
}

위에의 호출은, 시스템에 DepthFormat 가 존재하지 않는 경우는 FALSE 를 돌려준다.

CheckDeviceFormat 마시자 1 개(살)의 일반적인 용도는, 특정의 표면 포맷에 존재하는 텍스쳐를, 현재의 디스플레이 모드로 렌더링 할 수 있을지 어떨지를 확인하는 것이다. 다음의 코드는,CheckDeviceFormat 를 사용해, 텍스쳐 포맷이 특정의 백 버퍼 포맷과 호환성이 있을지 어떨지를 확인하는 방법을 나타내고 있다.

BOOL IsTextureFormatOk( D3DFORMAT TextureFormat, D3DFORMAT AdapterFormat ) {
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          0,
                                          D3DRTYPE_TEXTURE,
                                          TextureFormat);

    return SUCCEEDED( hr );
}

위에의 호출은, 어댑터 표면 포맷이 AdapterFormat 일 때,TextureFormat 를 사용해 텍스쳐를 렌더링 할 수 없는 경우, FALSE 를 돌려준다.

동작환경

헤더 : D3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3D8::CheckDeviceMultiSampleType

이 디바이스로 멀티 샘플링 테크닉을 이용할 수 있을지 어떨지를 조사한다.

HRESULT CheckDeviceMultiSampleType(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  D3DFORMAT SurfaceFormat,
  BOOL Windowed,
  D3DMULTISAMPLE_TYPE MultiSampleType
);

파라미터

Adapter
[in] 조회하는 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다. 이 값이 시스템의 디스플레이 어댑터의 수이상의 경우, 이 메소드는 FALSE 를 돌려준다. 「주의」를 참조할것.
DeviceType
[in] 디바이스 타입을 식별하는 D3DDEVTYPE 열거형의 멤버.
SurfaceFormat
[in] D3DFORMAT 열거형의 멤버. 표면에 대해서 요구하는 멀티 샘플링 타입세트를 지정한다. 「주의」를 참조할것.
Windowed
[in] 불리언 값. 윈도우 멀티 샘플링에 대해 문의할 때는 TRUE 를 지정해, 풀 스크린 멀티 샘플링에 대해 문의할 때는 FALSE 를 지정한다.
MultiSampleType
[in] D3DMULTISAMPLE_TYPE 열거형의 멤버. 검사하는 멀티 샘플링 테크닉을 식별한다.

반환값

지정한 멀티 샘플링 방식을 디바이스를 실행할 수 있는 경우는,D3D_OK 를 돌려준다.

Adapter 또는 MultiSampleType 파라미터가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다. 조회한 멀티 샘플링 테크닉을 이 디바이스가 지원 하고 있지 않는 경우는,D3DERR_NOTAVAILABLE 를 돌려준다. DeviceType 가 이 어댑터에 해당하지 않는 경우는,D3DERR_INVALIDDEVICE 를 돌려준다.

주의

이 메소드는, 렌더링 타겟 및 스텐실 표면의 양쪽 모두로 사용한다. 이 2 개(살)을 모두 사용하는 경우, 멀티 샘플링 된 양쪽 모두의 표면을 생성 할 필요가 있기 때문이다.

다음의 코드는,CheckDeviceMultiSampleType 를 사용해, 디바이스가 특정의 멀티 샘플링 방식을 지원 하고 있는 것을 확인하는 방법을 나타내고 있다.

if( SUCCEEDED(pDevice->CheckDeviceMultiSampleType( pCaps->AdapterOrdinal,
                                pCaps->DeviceType, pMode->Format,
                                FALSE, D3DMULTISAMPLE_3_SAMPLES ) ) )
    return S_OK;

위에의 코드에서는, 디바이스가 풀 스크린 D3DMULTISAMPLE_3_SAMPLES 멀티 샘플링 방식 및 표면 포맷을 지원 하고 있는 경우, S_OK 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3D8::CheckDeviceType

이 어댑터로 특정의 디바이스 타입을 사용해, 특정의 포맷을 사용한 하드웨어 가속화를 기대할 수 있을지 어떨지를 확인한다.

HRESULT CheckDeviceType(
  UINT Adapter,
  D3DDEVTYPE CheckType,
  D3DFORMAT DisplayFormat,
  D3DFORMAT BackBufferFormat,
  BOOL Windowed
);

파라미터

Adapter
[in] 열거하는 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다. 이 값이 시스템의 디스플레이 어댑터의 수이상의 경우, 이 메소드는 D3DERR_INVALIDCALL 를 돌려준다.
CheckType
[in] D3DDEVTYPE 열거형의 멤버. 검사하는 디바이스 타입을 나타낸다.
DisplayFormat
[in] D3DFORMAT 열거형의 멤버. 디바이스 타입을 검사하는 어댑터 디스플레이 모드의 포맷을 나타낸다. 예를 들어, 디바이스에 따라서는, 픽셀 단위의 16 비트의 모드에서만 동작한다.
BackBufferFormat
[in] D3DFORMAT 열거형의 멤버. 테스트하는 백 버퍼의 포맷을 나타낸다.
Windowed
[in] 디바이스 타입이 풀 스크린 모드와 윈도우 모드의 머지않아로 사용되는지를 나타내는 값. TRUE 를 설정했을 경우, 윈도우 어플리케이션의 조회가 실행된다. 그 이외의 경우는, 이 값에 FALSE 를 설정하는 것이 바람직하다.

반환값

그 어댑터로 디바이스를 사용할 수 있는 경우는,D3D_OK 를 돌려준다.

Adapter 의 값이 시스템의 디스플레이 어댑터의 수로 동일한지, 그것보다 큰 경우는,D3DERR_INVALIDCALL 를 돌려준다. CheckType 가 존재하지 않는 디바이스를 지정하고 있었을 경우, 이 메소드는 D3DERR_INVALIDDEVICE 를 돌려준다. 표면 포맷이 지원되어 있지 않은지, 지정된 포맷으로 하드웨어 가속화를 사용할 수 없는 경우는,D3DERR_NOTAVAILABLE 를 돌려준다.

주의

사용할 수 없을 가능성이 있는 가장 중요한 디바이스 타입은 D3DDEVTYPE_HAL 이다. D3DDEVTYPE_HAL 에는 하드웨어 가속화가 필요하다. 어플리케이션에서는,CheckDeviceType 를 사용해, 필요한 하드웨어와 드라이버가 시스템에 있을지 어떨지를 확인할 필요가 있다. 사용할 수 없을 가능성이 있는 이제(벌써) 1 개의 디바이스는 D3DDEVTYPE_SW 이다. 이 디바이스 타입은,IDirect3D8::RegisterSoftwareDevice 를 사용해 등록된 플러그 가능한 소프트웨어 디바이스를 나타낸다.

어플리케이션에서는, 알파 채널을 포함한 DisplayFormat 를 지정해서는 안된다. 이 경우, 호출은 실패한다. 알파 채널은 백 버퍼에 존재하고 있는 경우가 있지만, 2 개의 디스플레이 포맷은 다른 모든 면에서 같지 않으면 안 된다. 예를 들어,DisplayFormat 가 D3DFMT_X1R5G5B5 인 경우,BackBufferFormat 의 유효한 값에는 D3DFMT_X1R5G5B5 및 D3DFMT_A1R5G5B5 는 포함되지만, D3DFMT_R5G6B5 는 제외된다.

다음의 코드는,CheckDeviceType 를 사용해, 특정의 디바이스 타입을 그 어댑터로 사용할 수 있을지 어떨지를 확인하는 방법을 나타내고 있다.

if(SUCCEEDED(pD3Device->CheckDeviceType(D3DADAPTER_DEFAULT,
                                        D3DDEVTYPE_HAL,
                                        DisplayFormat,
                                        BackBufferFormat,
                                        bIsWindowed)))
     return S_OK;

// 이 어댑터에는, 이 렌더링 타겟 포맷을 사용하는 HAL 가 없다.
// 다른 포맷을 사용해 재차 시도한다.

디바이스가 디폴트의 어댑터상에서, 지정된 표면 포맷으로 사용할 수 있는 경우, 위에의 코드는 S_OK 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3D8::CreateDevice

디스플레이 어댑터를 나타내기 위한 디바이스를 생성 한다.

HRESULT CreateDevice(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  HWND  hFocusWindow,
  DWORD BehaviorFlags,
  D3DPRESENT_PARAMETERS* pPresentationParameters,
  IDirect3DDevice8** ppReturnedDeviceInterface
);

파라미터

Adapter
[in] 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다.
DeviceType
[in] D3DDEVTYPE 열거형의 멤버. 목적의 디바이스 타입을 나타낸다. 목적의 디바이스 타입을 사용할 수 없는 경우, 이 메소드는 실패한다.
hFocusWindow
[in] 이 Microsoft® Direct3D® 디바이스로 포커스를 설정하는 윈도우 핸들. 지정하는 윈도우는, 풀 스크린의 최상정도 윈도우가 아니면 안된다.
BehaviorFlags
[in] Direct3D 디바이스의 전체적인 동작을 제어하는 1 개(살) 이상의 플래그의 편성.
D3DCREATE_FPU_PRESERVE
어플리케이션으로 배정밀도 FPU 또는 FPU 예외 유효가 필요한 것을 나타낸다. Direct3D 는, 불려 갈 때마다 FPU 상태를 설정한다. 이 플래그를 설정 하면, Direct3D 의 퍼포먼스가 저하한다.
D3DCREATE_HARDWARE_VERTEXPROCESSING
하드웨어 버텍스 처리를 지정한다. 「주의」를 참조할것.
D3DCREATE_MIXED_VERTEXPROCESSING
혼합 (소프트웨어와 하드웨어 양쪽 모두)의 버텍스 처리를 지정한다. 「주의」를 참조할것.
D3DCREATE_MULTITHREADED
어플리케이션이 Direct3D 에 multi-thread에서의 안전성을 요구하는 것을 나타낸다. Direct3D 는 글로벌 크리티컬 섹션을 한층 더 빈번하게 취득하게 되어, 퍼포먼스가 저하할 가능성이 있다.
D3DCREATE_PUREDEVICE
Direct3D 가, 스테이트 블록에 저장 할 수 있는 내용에 대한 Get* 의 호출을 지원 하지 않는 것을 지정한다. 또, 버텍스 처리의 에뮬레이션 서비스를 제공하지 않는 것을 Direct3D 에 지시한다. 이것은, 디바이스가 버텍스 처리를 지원 하고 있지 않는 경우, 어플리케이션에서는 트랜스 폼 후의 버텍스 밖에 사용할 수 없는 것을 의미한다.
D3DCREATE_SOFTWARE_VERTEXPROCESSING
소프트웨어 버텍스 처리를 지정한다. 「주의」를 참조할것.
pPresentationParameters
[in, out] D3DPRESENT_PARAMETERS 구조체에의 포인터. 생성 하는 디바이스의 프레젠테이션 파라미터가 기술되고 있다. CreateDevice 를 호출하면,D3DPRESENT_PARAMETERS 의 BackBufferCount 멤버의 값이 변경되는 경우가 있다. 백 버퍼 카운트는, 백 버퍼의 올바른 수를 반영해 변경된다.
ppReturnedDeviceInterface
[out, retval] 돌려주어지는 IDirect3DDevice8 인터페이스에의 포인터의 주소. 생성 된 디바이스를 나타내고 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY

주의

이 메소드로부터는, 요구한 디스플레이 모드 (또는 윈도우)로 설정되어, 적절한 백 버퍼를 할당할 수 있던, 완전하게 동작하는 디바이스 인터페이스가 돌아간다. 어플리케이션은, 필요에 따라서 깊이 버퍼를 생성 해 설정하는 것만으로, 렌더링을 시작 할 수 있다.

이 메소드는, WM_CREATE 의 처리중에 실행해서는 안된다. 따라서, 어플리케이션은, WM_CREATE 의 처리중에 Direct3D 에 윈도우 핸들을 건네주어서는 안 된다. DirectX 8.0 어플리케이션에서는, 이 호출의 실행중 (즉, 이 호출이 돌아가기 전)은 어플리케이션에 메세지가 송신되는 것을 기대할 수 있다. 어플리케이션은, 이 때에 Direct3D 를 호출하지 않기 위한 경고를 받아들인다. 또, 디바이스의 생성, 해방, 또는 리셋의 호출은, 포커스 윈도우의 윈도우 프로시저와 같은 thread에서만 행해지는 것에 주의 해야 한다.

D3DCREATE_HARDWARE_VERTEXPROCESSING, D3DCREATE_MIXED_VERTEXPROCESSING, 및 D3DCREATE_SOFTWARE_VERTEXPROCESSING 는 서로 배타적인 플래그이며,CreateDevice 를 호출하면나무는, 이 버텍스 처리 플래그의 적어도 1 개(살)을 반드시 지정해야 한다.

디바이스의 일부로서 생성 된 백 버퍼는, 프레젠테이션 파라미터로 D3DPRESENTFLAG_LOCKABLE_BACKBUFFER 가 지정되고 있는 경우에게만 락 가능하다. 멀티 샘플 백 버퍼 및 깊이 표면은 잠글 수 없다.

메소드의 IDirect3DDevice8::Reset ,Release, 및 IDirect3DDevice8::TestCooperativeLevel 는,CreateDevice 를 사용해 디바이스를 생성 한 같은 thread로부터 호출할 필요가 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

Direct3DCreate8 ,IDirect3DDevice8::Reset ,D3DDEVICE_CREATION_PARAMETERS


IDirect3D8::EnumAdapterModes

어댑터의 디스플레이 모드를 열거한다.

HRESULT EnumAdapterModes(
  UINT Adapter,
  UINT Mode,
  D3DDISPLAYMODE* pMode
);

파라미터

Adapter
[in] 조회하는 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다.
Mode
[in] 열거하는 모드를 나타내는 순서수. D3DCURRENT_DISPLAY_MODE 는 어댑터의 현재의 데스크탑 디스플레이 모드를 나타내는 특별한 값이며, 이 메소드에서는 지정할 수 없다. 「주의」를 참조할것.
pMode
[in, out] D3DDISPLAYMODE 구조체에의 포인터. 지정한 모드를 기술하는 정보가 저장 된다. 에러의 경우는 제로가 설정된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

Adapter 또는 Mode 가 범위외의 값의 경우, 또는 pMode 가 무효인 값의 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

일부의 디스플레이 드라이버에는, 모드수를 큰폭으로 증가시키는 refresh rate 정보를 포함하고 있다. 낡은 드라이버에서는, D3DADAPTER_DEFAULT 의 refresh rate만이 열거된다. Direct3D 에서는, 모니터의 능력에 응해, 디스플레이 모드 및 refresh rate를 제한하려고 하고 있지만, 열거된 모드가 시스템의 모니터로 지원되어 있지 않을 가능성이 있다. Microsoft® Windows® 의 디스플레이 컨트롤 패널 유틸리티로 사용되는 것과 같은 디스플레이 모드 테스트 유틸리티를 이행 할 수 있다.

IDirect3D8::GetAdapterModeCount 를 사용해, 시스템으로 지원 되고 있는 모드의 총수를 조사한다. Mode 파라미터의 유효한 값은, 0 으로부터 모드의 총수 - 1 까지의 범위이다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3D8::GetAdapterModeCount


IDirect3D8::GetAdapterCount

시스템에 있는 어댑터의 수를 돌려준다.

UINT GetAdapterCount();

파라미터

없음.

반환값

이 IDirect3D8 인터페이스가 인스턴스화 된 시점에서 시스템에 존재하고 있는 어댑터의 수를 나타내는 UINT 의 값.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3D8::GetAdapterIdentifier


IDirect3D8::GetAdapterDisplayMode

어댑터의 현재의 디스플레이 모드를 취득한다.

HRESULT GetAdapterDisplayMode(
  UINT Adapter,
  D3DDISPLAYMODE* pMode
);

파라미터

Adapter
[in] 조회하는 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다.
pMode
[in, out] D3DDISPLAYMODE 구조체에의 포인터. 어댑터의 현재의 모드를 기술하는 정보가 저장 된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

Adapter 가 범위외의 값의 경우, 또는 pMode 가 무효인 값의 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

어댑터를 나타내는 디바이스가 특정의 모드에 리셋 되고 있는 경우가 있지만, 이것은 어댑터의 실제의 모드가 아닐 가능성이 있는 것에 주의한다. 특정의 모드에의 디바이스 리셋이 없어지고 있어, 어댑터의 현재의 모드를 판정할 수 없을 가능성이 있다. 이 함수로부터는, 디바이스에 대해서 요구되고 있는 특정의 모드는 아니고, 어댑터의 모드가 돌아간다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3D8::GetAdapterIdentifier

IDirect3D8 인터페이스가 인스턴스화 된 시점에서 시스템에 존재하고 있던 물리적인 디스플레이 어댑터를 기술한다.

HRESULT GetAdapterIdentifier(
  UINT Adapter,
  DWORD Flags,
  D3DADAPTER_IDENTIFIER8* pIdentifier
);

파라미터

Adapter
[in] 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다. 이 파라미터의 최소 값은 0 으로, 최대치는 IDirect3D8::GetAdapterCount 로 돌려주어지는 값으로부터 1 을 뺀 값이다.
Flags
[in] 보통은 제로로 설정하는 파라미터. 다만, 다음의 값을 지정할 수도 있다.
D3DENUM_NO_WHQL_LEVEL
D3DADAPTER_IDENTIFIER8 구조체의 WHQLLevel 멤버를 강제적으로 제로로 한다. 이것에 의해, WHQL 의 인증 기일에 대한 정보가 돌아가지 않게 된다. 이 플래그를 설정 하면, WHQL 의 인증 기일을 확인할 때에 발생하는 1, 2 초의 지연을 피할 수가 있다.
pIdentifier
[in, out] D3DADAPTER_IDENTIFIER8 구조체에의 포인터. 지정한 어댑터를 기술하는 정보가 저장 된다. 시스템에 있는 어댑터의 수이상의 값을 Adapter 로 지정 하면, 이 구조체에는 제로가 설정된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

Adapter 의 값이 범위외의 경우,Flags 가 인식 불가능한 파라미터의 경우, 또는 pIdentifier 가 NULL 또는 기입해 불가능한 메모리를 가리키고 있는 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3D8::GetAdapterCount


IDirect3D8::GetAdapterModeCount

어댑터로 이용 가능한 디스플레이 모드의 수를 돌려준다.

UINT GetAdapterModeCount(
  UINT Adapter
);

파라미터

Adapter
[in] 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다.

반환값

Adapter 의 값이 시스템 위에의 어댑터의 수이상의 경우는, 이 어댑터의 디스플레이 모드의 수, 또는 제로를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3D8::EnumAdapterModes


IDirect3D8::GetAdapterMonitor

Microsoft® Direct3D® 오브젝트에 관련지을 수 있고 있는 모니터의 핸들을 돌려준다.

HMONITOR GetAdapterMonitor(
  UINT Adapter
);

파라미터

Adapter
[in] 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다.

반환값

Direct3D 오브젝트에 관련지을 수 있었던 모니터의 핸들.

주의

다음의 코드예는, 지정된 디바이스에 관련지을 수 있었던 모니터의 핸들을 취득하는 방법을 나타내고 있다. 이 예의 같게,IDirect3DDevice8::GetDirect3D 를 사용해, 디바이스로부터 Direct3D 열거형을 돌려주어,IDirect3DDevice8::GetCreationParameters 를 사용해,Adapter 의 값을 취득한다.

    if( FAILED( pDevice->GetCreationParameters(  &Parameters ) ) )
        return E_INVALIDCALL;

    if( FAILED( pDevice->GetDirect3D(&pD3D) ) )
        return E_INVALIDCALL;

    hMonitor = pD3D->GetAdapterMonitor(Parameters.AdapterOrdinal);

    pD3D->Release();

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetCreationParameters ,IDirect3DDevice8::GetDirect3D


IDirect3D8::GetDeviceCaps

디바이스에 대한 디바이스 고유의 정보를 취득한다.

HRESULT GetDeviceCaps(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  D3DCAPS8* pCaps
);

파라미터

Adapter
[in] 디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 는 항상 프라이머리 디스플레이 어댑터이다.
DeviceType
[in] D3DDEVTYPE 열거형의 멤버. 디바이스의 타입을 나타낸다.
pCaps
[out] D3DCAPS8 구조체에의 포인터. 디바이스의 능력을 기술한 정보가 저장 된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_INVALIDDEVICE
D3DERR_OUTOFVIDEOMEMORY

주의

어플리케이션으로, Microsoft® Direct3D® 디바이스 오브젝트 전체에 있어서의 버텍스 처리 능력의 지속성을 가정해서는 안 된다. 물리 디바이스가 공개하는 특정의 능력은,IDirect3D8::CreateDevice 로 지정되는 파라미터에 따라서 다르다. 예를 들어, 이러한 능력은, 하드웨어 버텍스 처리를 유효하게 해 Direct3D 디바이스 오브젝트를 생성 하는 전후로, 다른 버텍스 처리 능력을 제공할 수 있다. 상세한 것에 대하여는, 「D3DCAPS8 」를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3D8::RegisterSoftwareDevice

플러그 가능한 소프트웨어 디바이스를 Microsoft® Direct3D® 에 등록한다.

HRESULT RegisterSoftwareDevice(
  void* pInitializeFunction
);

파라미터

pInitializeFunction
[in] 등록하는 소프트웨어 디바이스의 초기화 함수에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

주의

Direct3D 에 대한 소프트웨어 라스터화는, 플러그 가능한 소프트웨어 디바이스에 의해 제공된다. 이것에 의해, 어플리케이션은, Direct3D 인터페이스를 통해 다양한 소프트웨어 래스터라이저에 액세스 할 수 있다. 소프트웨어 디바이스는, 어플리케이션에 의해 로드 되어, Direct3D 오브젝트에 등록된다. 이 시점에서, 소프트웨어 디바이스를 사용해 렌더링을 실행하는 Direct3DDevice 오브젝트를 생성 할 수 있다.

Direct3D 소프트웨어 디바이스는, 하드웨어 디바이스 드라이버 인터페이스 (DDI)에 유사하는 인터페이스를 개입시켜 Direct3D 와 통신한다.

Direct3D DDK 에는, 플러그 가능한 소프트웨어 디바이스를 개발하기 위한 문서와 헤더가 준비되어 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DBaseTexture8

큐브 텍스쳐, 볼륨 텍스쳐등의 텍스쳐 리소스를 조작하려면 ,IDirect3DBaseTexture8 인터페이스의 메소드를 사용한다.

디바이스의 특정의 스테이지에 할당할 수 있고 있는 IDirect3DBaseTexture8 인터페이스를 취득하려면 ,IDirect3DDevice8::GetTexture 메소드를 호출한다.

IDirect3DBaseTexture8 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirect3DResource8 메소드를 계승한다.

디바이스 | GetDevice
정보 | GetType
프라이빗 표면 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData
리소스 관리 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DBaseTexture8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

상세 | GetLOD
 | SetLOD
정보 | GetLevelCount

모든 COM 인터페이스와 같이,IDirect3DBaseTexture8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DBASETEXTURE8 및 PDIRECT3DBASETEXTURE8 형은,IDirect3DBaseTexture8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DBaseTexture8 *LPDIRECT3DBASETEXTURE8, *PDIRECT3DBASETEXTURE8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DBaseTexture8::GetLevelCount

멀티 레벨 텍스쳐의 텍스쳐 레벨의 수를 돌려준다.

DWORD GetLevelCount();

파라미터

없음.

반환값

멀티 레벨 텍스쳐의 텍스쳐 레벨의 수를 나타내는 DWORD 의 값.

대상

이 메소드는,IDirect3DBaseTexture8 를 계승하는 다음의 인터페이스에 적용된다.

  • IDirect3DCubeTexture8
  • IDirect3DTexture8
  • IDirect3DVolumeTexture8

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DBaseTexture8::GetLOD

관리하의 텍스쳐로 설정되어 있는 최대 상세 레벨 (LOD)에 제한된 값을 돌려준다.

DWORD GetLOD();

파라미터

없음.

반환값

최대 LOD 값에 제한된 DWORD 값 (레벨의 총수로부터 1 을 뺀 값).

대상

이 메소드는,IDirect3DBaseTexture8 를 계승하는 다음의 인터페이스에 적용된다.

  • IDirect3DCubeTexture8
  • IDirect3DTexture8
  • IDirect3DVolumeTexture8

주의

GetLOD 를 사용해, 관리하의 텍스쳐의 LOD 제어를 실시한다. 이 메소드는, 비관리하의 텍스쳐에 대해서 0 을 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DBaseTexture8::SetLOD


IDirect3DBaseTexture8::SetLOD

관리하의 텍스쳐에 최대 상세 레벨 (LOD)을 설정한다.

DWORD SetLOD(
  DWORD LODNew
);

파라미터

LODNew
[in] 밉맵 체인으로 설정하는 최대 LOD 의 값.

반환값

최대 LOD 값에 제한된 DWORD 값 (레벨의 총수로부터 1 을 뺀 값). 이후의 이 메소드의 호출에서는, 이전으로 설정된 LOD 값은 아니고, 제한된 값이 돌려주어진다.

대상

이 메소드는,IDirect3DBaseTexture8 를 계승하는 다음의 인터페이스에 적용된다.

  • IDirect3DCubeTexture8
  • IDirect3DTexture8
  • IDirect3DVolumeTexture8

주의

SetLOD 는, 관리하의 텍스쳐의 LOD 제어를 위해서(때문에) 사용된다. 이 메소드는, 비관리하의 텍스쳐에 대해서 0 을 돌려준다.

SetLOD 는, 로컬 비디오 메모리에 로드하는 체인 중(안)에서 가장 상세한 밉맵을 Microsoft® Direct3D® 텍스쳐 매니저에 통지한다. 예를 들어, 5 레벨의 밉맵 체인에 대해 LODNew 로 2 를 지정 하면, 텍스쳐 매니저는 어떤 시점에 레벨 2 에서 4 의 밉맵만을 로컬 비디오 메모리에 로드한다.

한층 더 구체적으로 설명 하면, 256 × 256 의 넓이로 텍스쳐가 생성 되고 있는 경우, 최대 상세 레벨을 0 으로 설정 하면 이용 가능한 최대의 밉맵이 256 × 256 인 것을 나타내, 최대 상세 레벨을 1 으로 설정 하면 이용 가능한 최대 밉맵이 128 × 128 인 것을 나타낸다. 이와 같이 해, 체인의 최대 밉레벨 (가장 작은 텍스쳐 사이즈)까지와 같이 나타난다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DBaseTexture8::GetLOD


IDirect3DCubeTexture8

큐브 텍스쳐 리소스를 조작하려면 ,IDirect3DCubeTexture8 인터페이스의 메소드를 사용한다.

IDirect3DCubeTexture8 인터페이스를 취득하려면 ,IDirect3DDevice8::CreateCubeTexture 메소드를 호출한다.

IDirect3DCubeTexture8 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirect3DResource8 메소드를 계승한다.

디바이스 | GetDevice
정보 | GetType
프라이빗 표면 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData
리소스 관리 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DCubeTexture8 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirect3DBaseTexture8 메소드를 계승한다.

상세 | GetLOD
 | SetLOD
정보 | GetLevelCount

IDirect3DCubeTexture8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetLevelDesc
표면의 락 | LockRect
 | UnlockRect
그 외 | AddDirtyRect
 | GetCubeMapSurface

모든 COM 인터페이스와 같이,IDirect3DCubeTexture8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DCUBETEXTURE8 및 PDIRECT3DCUBETEXTURE8 형은,IDirect3DCubeTexture8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DCubeTexture8 *LPDIRECT3DCUBETEXTURE8, *PDIRECT3DCUBETEXTURE8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CreateCubeTexture


IDirect3DCubeTexture8::AddDirtyRect

큐브 텍스쳐 리소스에 더티 영역을 추가한다.

HRESULT AddDirtyRect(
  D3DCUBEMAP_FACES FaceType,
  CONST RECT* pDirtyRect
);

파라미터

FaceType
[in] D3DCUBEMAP_FACES 열거형의 멤버. 큐브 맵의 표면을 지정한다.
pDirtyRect
[in] RECT 구조체에의 포인터. 더티 영역을 지정한다. NULL 를 지정 하면, 큐브 텍스쳐 전체를 가리도록(듯이) 더티 영역이 확대한다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

퍼포먼스의 이유에 의해, 더티인 범위는 텍스쳐의 레벨 제로에 대해서 기록될 뿐이다. 서브 레벨에 대해서는, 대응하는 (스케일 된) 직사각형 또는 박스도 더티이라고 가정된다. D3DLOCK_NO_DIRTY_UPDATE 또는 D3DLOCK_READONLY 없음으로 LockRect 나 LockBox 가 불려 갔을 때, 더티인 범위는 자동적으로 기록된다. 또 CopyRects 호출의 행선지 표면은 더티로서 마크 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DCubeTexture8::GetLevelDesc ,IDirect3DCubeTexture8::LockRect ,IDirect3DCubeTexture8::UnlockRect


IDirect3DCubeTexture8::GetCubeMapSurface

큐브 텍스쳐 맵의 표면을 취득한다.

HRESULT GetCubeMapSurface(
  D3DCUBEMAP_FACES FaceType,
  UINT Level,
  IDirect3DSurface8** ppCubeMapSurface
);

파라미터

FaceType
[in] 큐브 맵 표면을 식별하는 D3DCUBEMAP_FACES 열거형의 멤버.
Level
[in] 밉맵 큐브 텍스쳐의 레벨을 지정한다.
ppCubeMapSurface
[out, retval] IDirect3DSurface8 인터페이스에의 포인터의 주소. 돌려주어진 큐브 텍스쳐 맵의 표면을 나타내고 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DCubeTexture8::GetLevelDesc

지정한 큐브 텍스쳐 레벨의 기술을 취득한다.

HRESULT GetLevelDesc(
  UINT Level,
  D3DSURFACE_DESC* pDesc
);

파라미터

Level
[in] 밉맵 큐브 텍스쳐의 레벨을 지정한다.
pDesc
[out] 지정한 큐브 텍스쳐 레벨을 기술하고 있는 D3DSURFACE_DESC 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수의 1 개 이상이 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DCubeTexture8::AddDirtyRect ,IDirect3DCubeTexture8::LockRect ,IDirect3DCubeTexture8::UnlockRect


IDirect3DCubeTexture8::LockRect

큐브 텍스쳐 리소스 위에의 직사각형을 잠근다.

HRESULT LockRect(
  D3DCUBEMAP_FACES FaceType,
  UINT Level,
  D3DLOCKED_RECT* pLockedRect,
  CONST RECT* pRect,
  DWORD Flags
);

파라미터

FaceType
[in] 큐브 맵 표면을 식별하는 D3DCUBEMAP_FACES 열거형의 멤버.
Level
[in] 밉맵 큐브 텍스쳐의 레벨을 지정한다.
pLockedRect
[out] 잠그는 영역을 기술하는 D3DLOCKED_RECT 구조체에의 포인터.
pRect
[in] 잠그는 직사각형에의 포인터. RECT 구조체에의 포인터에 의해 지정된다. 이 파라미터에 NULL 를 지정 하면, 큐브 텍스쳐 전체를 가리도록(듯이) 더티 영역이 확대한다.
Flags
[in] 실행하는 락의 타입을 기술하는, 0 개 이상의 락킹 플래그의 편성.
D3DLOCK_NO_DIRTY_UPDATE
디폴트에서는, 리소스의 락은 더티 영역을 그 리소스에 추가한다. 이 플래그는, 리소스의 더티 상태에의 변경을 막는다. 락 처리동안으로 변경되는 실제의 영역군에 대한 추가 정보를 어플리-숀이 가지고 있어, 그 정보를 IDirect3DCubeTexture8::AddDirtyRect 에 건네줄 수가 있는 경우는, 어플리케이션으로 이 플래그를 사용해야 한다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작에서는, 시스템 전체의 크리티컬 섹션이 확보되어, 락의 기간중은 디스플레이 모드가 변화하지 않는 것이 보증된다. 이 플래그는, 시스템 와이드인 크리티컬 섹션이 락의 사이 보관 유지되지 않게 한다.

락 처리로 사용되는 메모리는 약간 증가하지만, 시스템은, 마우스 커서의 이동이라고 한 것 외의 동작을 실행할 수 있다. 이 플래그는, 소프트웨어 렌더링의 백 버퍼의 락과 같이, 락이 장시간에 이르러, 시스템의 응답성에 악영향을 주어 버리는 것 같은 락에 대해서 유효하다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입을 실시하지 않는다. 이것에 의해, 네이티브가 아닌 포맷으로 저장 된 리소스가, 언락시에 재압축 순서를 보존할 수 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수의 1 개 이상이 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

POOL_DEFAULT 를 지정해 생성 된 큐브 텍스쳐는 잠글 수 없다.

스텐실 표면의 락 가능한 포맷은, D3DFMT_D16_LOCKABLE 뿐이다.

멀티 샘플 백 버퍼는 잠글 수 없다.

퍼포먼스의 이유에 의해, 더티인 범위는 텍스쳐의 레벨 제로에 대해서 기록될 뿐이다. D3DLOCK_NO_DIRTY_UPDATE 또는 D3DLOCK_READONLY 없음으로 LockRect 나 LockBox 가 불려 갔을 때, 더티인 범위는 자동적으로 기록된다. 상세한 것에 대하여는, 「IDirect3DDevice8::UpdateTexture」를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DCubeTexture8::AddDirtyRect ,IDirect3DCubeTexture8::GetLevelDesc ,IDirect3DCubeTexture8::UnlockRect


IDirect3DCubeTexture8::UnlockRect

큐브 텍스쳐 리소스 위에의 직사각형을 언락 한다.

HRESULT UnlockRect(
  D3DCUBEMAP_FACES FaceType,
  UINT Level
);

파라미터

FaceType
[in] 큐브 맵 표면을 식별하는 D3DCUBEMAP_FACES 열거형의 멤버.
Level
[in] 밉맵 큐브 텍스쳐의 레벨을 지정한다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수의 1 개 이상이 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DCubeTexture8::AddDirtyRect ,IDirect3DCubeTexture8::LockRect


IDirect3DDevice8

DrawPrimitive 베이스의 렌더링, 리소스의 생성, 시스템 레벨 변수의 처리, 감마 램프 레벨의 조정, 팔레트의 처리, 및 쉐이더의 생성을 실시하려면 ,IDirect3DDevice8 인터페이스의 메소드를 사용한다.

IDirect3DDevice8 인터페이스를 취득하려면 ,IDirect3D8::CreateDevice 메소드를 호출한다.

IDirect3DDevice8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

커서 | SetCursorPosition
 | SetCursorProperties
 | ShowCursor
생성 | CreateAdditionalSwapChain
 | CreateCubeTexture
 | CreateDepthStencilSurface
 | CreateImageSurface
 | CreateIndexBuffer
 | CreateRenderTarget
 | CreateTexture
 | CreateVertexBuffer
 | CreateVolumeTexture
디바이스 스테이트 | ApplyStateBlock
 | BeginStateBlock
 | CaptureStateBlock
 | CreateStateBlock
 | DeleteStateBlock
 | EndStateBlock
 | GetClipStatus
 | GetDisplayMode
 | GetRenderState
 | GetRenderTarget
 | GetTransform
 | SetClipStatus
 | SetRenderState
 | SetRenderTarget
 | SetTransform
감마 램프 | GetGammaRamp
 | SetGammaRamp
고차원 프리미티브 | DeletePatch
 | DrawRectPatch
 | DrawTriPatch
인덱스 데이터 | GetIndices
 | SetIndices
정보 | GetAvailableTextureMem
 | GetCreationParameters
 | GetDeviceCaps
 | GetDirect3D
 | GetInfo
 | GetRasterStatus
라이팅과 머트리얼 | GetLight
 | GetLightEnable
 | GetMaterial
 | LightEnable
 | SetLight
 | SetMaterial
그 외 | CopyRects
 | GetFrontBuffer
 | MultiplyTransform
 | ProcessVertices
 | ResourceManagerDiscardBytes
 | TestCooperativeLevel
팔레트 | GetCurrentTexturePalette
 | GetPaletteEntries
 | SetCurrentTexturePalette
 | SetPaletteEntries
픽셀 쉐이더 | CreatePixelShader
 | DeletePixelShader
 | GetPixelShader
 | GetPixelShaderConstant
 | GetPixelShaderFunction
 | SetPixelShader
 | SetPixelShaderConstant
프레젠테이션 | Present
 | Reset
렌더링 | DrawIndexedPrimitive
 | DrawIndexedPrimitiveUP
 | DrawPrimitive
 | DrawPrimitiveUP
 | DrawRectPatch
 | DrawTriPatch
장면 | BeginScene
 | EndScene
스트림 데이터 | GetStreamSource
 | SetStreamSource
표면 | GetBackBuffer
 | GetDepthStencilSurface
텍스쳐 | GetTexture
 | GetTextureStageState
 | SetTexture
 | SetTextureStageState
 | UpdateTexture
 | ValidateDevice
유저 정의 클립면 | GetClipPlane
 | SetClipPlane
뷰 포토 | Clear
 | GetViewport
 | SetViewport
버텍스 쉐이더 | CreateVertexShader
 | DeleteVertexShader
 | GetVertexShader
 | GetVertexShaderConstant
 | GetVertexShaderDeclaration
 | GetVertexShaderFunction
 | SetVertexShader
 | SetVertexShaderConstant

모든 COM 인터페이스와 같이,IDirect3DDevice8 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DDEVICE8 및 PDIRECT3DDEVICE8 형은,IDirect3DDevice8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DDevice8 *LPDIRECT3DDEVICE8, *PDIRECT3DDEVICE8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3D8::CreateDevice


IDirect3DDevice8::ApplyStateBlock

기존의 디바이스 스테이트 블록을 렌더링 디바이스에 적용한다.

HRESULT ApplyStateBlock(
  DWORD Token
);

파라미터

Token
[in] 실행하는 디바이스 스테이트 블록에의 핸들. 이것은 전에 호출한 IDirect3DDevice8::EndStateBlock 메소드에 의해 돌려주어진다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

값 0xFFFFFFFF 는, 무효인 스테이트 블록 핸들이다.

어플리케이션으로 다른 블록을 기록하고 있을 때, 디바이스 스테이트 블록을 적용할 수 없다.

렌더링 디바이스의 스테이트에 영향을 주는 모든 처리와 같이, 스테이트 블록의 적용은, 장면의 렌더링중, 즉 IDirect3DDevice8::BeginScene 메소드를 호출하고 나서 IDirect3DDevice8::EndScene 를 호출할 때까지 에 실시하는 것을 추천 한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::BeginStateBlock ,IDirect3DDevice8::EndStateBlock ,IDirect3DDevice8::CaptureStateBlock ,IDirect3DDevice8::CreateStateBlock ,IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::BeginScene

장면을 시작 한다.

HRESULT BeginScene();

파라미터

없음.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

어플리케이션에서는, 렌더링을 실행하기 전에는 반드시 이 메소드를 호출해, 렌더링의 종료시 및 재차 BeginScene 를 호출하기 전에는, 반드시 IDirect3DDevice8::EndScene 를 호출한다.

BeginScene 메소드가 실패 하면, 디바이스는 장면을 시작 할 수 없기 때문에,IDirect3DDevice8::EndScene 메소드를 호출할 필요는 없다. 실제, 그 전의 BeginScene 의 호출이 실패 하면,EndScene 의 호출도 실패한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::EndScene


IDirect3DDevice8::BeginStateBlock

Microsoft® Direct3D® 에 디바이스 스테이트 블록의 기록을 시작 하도록(듯이) 알린다.

HRESULT BeginStateBlock();

파라미터

없음.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

어플리케이션에서는, 이 메소드를 호출하기 전에 IDirect3DDevice8::ValidateDevice 메소드를 호출해, 기록하는 모든 스테이트가 유효한 것을 확인할 수 있다.

BeginStateBlock 를 호출하고 나서 IDirect3DDevice8::EndStateBlock 를 호출하기까지 스테이트 블록에 기록할 수 있는 메소드는, 다음과 같다.

  • IDirect3DDevice8::LightEnable
  • IDirect3DDevice8::SetClipPlane
  • IDirect3DDevice8::SetIndices
  • IDirect3DDevice8::SetLight
  • IDirect3DDevice8::SetMaterial
  • IDirect3DDevice8::SetPixelShader
  • IDirect3DDevice8::SetPixelShaderConstant
  • IDirect3DDevice8::SetRenderState
  • IDirect3DDevice8::SetStreamSource
  • IDirect3DDevice8::SetTexture
  • IDirect3DDevice8::SetTextureStageState
  • IDirect3DDevice8::SetTransform
  • IDirect3DDevice8::SetViewport
  • IDirect3DDevice8::SetVertexShader
  • IDirect3DDevice8::SetVertexShaderConstant

스테이트 블록내에서는, 스테이트 변경의 순서는 보증되지 않는다. 스테이트 블록으로 같은 스테이트가 여러 차례 지정되었을 경우, 사용되는 것은 마지막 값뿐이다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::ApplyStateBlock ,IDirect3DDevice8::EndStateBlock ,IDirect3DDevice8::CaptureStateBlock ,IDirect3DDevice8::CreateStateBlock ,IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::CaptureStateBlock

기존의 스테이트 블록내의 값을, 디바이스로 설정되어 있는 값에 갱신한다.

HRESULT CaptureStateBlock(
  DWORD Token
);

파라미터

Token
[in] 디바이스 스테이트를 수중에 넣는 스테이트 블록에의 핸들.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

스테이트 블록이 현재 기록중인 경우, 메소드는 실패해,D3DERR_INVALIDCALL 를 돌려준다.

주의

값 0xFFFFFFFF 는, 무효인 스테이트 블록 핸들이다.

이 메소드는, 기존의 스테이트 블록에 포함되는 스테이트의 갱신 후의 값을 수중에 넣는다. 디바이스 전체의 스테이트는 수중에 넣지 않는다.

CaptureStateBlock 는, 스테이트 블록의 생성 후에, 명시적 또는 비명시적으로 생성 된 라이트의 정보를 수중에 넣지 않는다. 예를 들어, 현재의 스테이트를 D3DSBT_ALL 형의 스테이트 블록에 수중에 넣어도, 혼잡 후에 생성 된 라이트의 정보는 보존되지 않는다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::ApplyStateBlock ,IDirect3DDevice8::BeginStateBlock ,IDirect3DDevice8::CreateStateBlock ,IDirect3DDevice8::EndStateBlock ,IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::Clear

뷰 포토 또는 뷰 포토내의 직사각형 세트를 지정한 RGBA 색에 클리어 해, 깊이 버퍼를 클리어 해, 스텐실 버퍼를 삭제한다.

HRESULT Clear(
  DWORD Count,
  CONST D3DRECT* pRects,
  DWORD Flags,
  D3DCOLOR Color,
  float Z,
  DWORD Stencil
);

파라미터

Count
[in] pRects 의 배열에 있는 직사각형의 수. pRects 를 NULL 로 설정하는 경우는, 이 파라미터를 0 으로 설정한다.
pRects
[in] 클리어 하는 직사각형을 기술하는 D3DRECT 구조체의 배열에의 포인터. 직사각형을 렌더링 타겟의 치수로 설정 하면, 표면 전체가 클리어 된다. 각 직사각형은, 렌더링 타겟 표면 위에의점에 대응하는 화면 좌표를 사용한다. 좌표는 뷰 포토의 직사각형의 경계에서 클립 된다. 이 파라미터를 NULL 로 설정 하면, 뷰 포토 직사각형 전체를 클리어 하게 된다.
Flags
[in] 클리어 하는 표면을 나타내는 플래그. 이 파라미터에서는, 다음의 플래그의 임의의 편성을 지정할 수 있지만, 적어도 1 개의 플래그를 사용하지 않으면 안 된다.
D3DCLEAR_STENCIL
스텐실 버퍼를 클리어 해,Stencil 파라미터의 값으로 한다.
D3DCLEAR_TARGET
렌더링 타겟을 클리어 해,Color 파라미터의 색으로 한다.
D3DCLEAR_ZBUFFER
깊이 버퍼를 클리어 해,Z 파라미터의 값으로 한다.
Color
[in] 렌더링 타겟 표면을 클리어 하는 32 비트 ARGB 칼라값.
Z
[in] 이 메소드가 깊이 버퍼에 보존하는 새로운 z 값. 이 파라미터에는 0.0 에서 1.0 까지의 값을 사용할 수 있다 (Z 베이스 또는 W 베이스의 깊이 버퍼의 경우). 0.0 은 뷰아에 가장 가까운 거리, 1.0 은 가장 먼 거리를 나타낸다.
Stencil
[in] 각 스텐실 버퍼의 엔트리에 보존하는 정수값. 이 파라미터에는 0 에서 2n-1 까지의 값을 사용할 수 있다. n 는 스텐실 버퍼의 비트 깊이.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 렌더링 타겟으로 깊이 버퍼가 어태치되어 있지 않을 때에 D3DCLEAR_ZBUFFER 또는 D3DCLEAR_STENCIL 플래그를 지정 하면 실패한다. 같이 깊이 버퍼 포맷에 스텐실 버퍼 정보가 포함되지 않은 경우, D3DCLEAR_STENCIL 플래그를 지정 하면, 이 메소드는 실패한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::CopyRects

어느 표면으로부터 다른 표면에, 픽셀의 직사각형 서브 세트를 카피한다.

HRESULT CopyRects(
  IDirect3DSurface8* pSourceSurface,
  CONST RECT* pSourceRectsArray,
  UINT cRects,
  IDirect3DSurface8* pDestinationSurface,
  CONST POINT* pDestPointsArray
);

파라미터

pSourceSurface
[in] 전송원표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터. 이 파라미터는,pDestinationSurface 와 다른 표면을 나타내지 않으면 안 된다.
pSourceRectsArray
[in] RECT 구조체의 배열에의 포인터. 전송 하는 직사각형을 나타내고 있다. 각 직사각형은 전송처의 표면에 전송 되어, 직사각형의 맨 왼쪽 위쪽은 pDestPointsArray 의 대응하는 요소로 나타나고 있는 위치가 된다. 이 파라미터에 NULL 를 지정 하면, 표면 전체가 카피된다.
cRects
[in] pSourceRectsArray 에 저장 되고 있는 RECT 구조체의 수.
pDestinationSurface
[in] 전송처 표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터. 이 파라미터는,pSourceSurface 와 다른 표면을 나타내지 않으면 안 된다.
pDestPointsArray
[in] POINT 구조체의 배열에의 포인터. pSourceRectsArray 에 저장 되고 있는 각 직사각형의 맨 왼쪽 위쪽의 위치를 나타낸다. 이 파라미터가 NULL 의 경우,RECT 의 직사각형은 전송원의 직사각형과 같은 오프셋(offset) (맨 왼쪽 위쪽의 위치가 같다)에 카피된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 확대, 칼라 키, 알파 브렌드, 포맷 변환, 및 전송원 또는 전송처 직사각형의 몇개의 클리핑을 지원 하고 있지 않다. 모든 전송원직사각형 및 대응하는 전송처 직사각형이, 각각 전송원 및 전송처 표면내에 완전하게 포함되지 않은 경우에는, 이 메소드가 실패하는 것에 주의한다. 2 개의 표면의 포맷은 일치하고 있지 않으면 안 되지만, 사이즈는 차이가 나도 상관없다.

표면의 포맷이 스텐실 포맷의 경우, 이 메소드는 적용할 수 없다.

POINT 구조체에서는, 맨 왼쪽 위쪽의 x 좌표와 y 좌표를 정의한다. POINT 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것.

행선지 표면이 텍스쳐의 레벨 제로라면, 그것은 더티와 마크 된다. 상세한 것에 대하여는, 「IDirect3DDevice8::UpdateTexture」 및 「IDirect3DTexture8::AddDirtyRect」를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::CreateAdditionalSwapChain

복수의 뷰를 렌더링하기 위한 추가 스왑 체인을 생성 한다.

HRESULT CreateAdditionalSwapChain(
  D3DPRESENT_PARAMETERS* pPresentationParameters,
  IDirect3DSwapChain8** ppSwapChain
);

파라미터

pPresentationParameters
[in] 새로운 스왑 체인의 프레젠테이션 파라미터를 나타내는 D3DPRESENT_PARAMETERS 구조체에의 포인터. 이 값은 NULL 로 할 수 없다.
ppSwapChain
[out, retval] 추가 스왑 체인을 나타내는 IDirect3DSwapChain8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

Microsoft® Direct3D® for Microsoft DirectX 8.0® 는 디바이스의 프로퍼티로서 1 개의 스왑 체인을 가지고 있기 (위해)때문에, 각 디바이스에 대해서, 항상 적어도 1 개의 스왑 체인 (비명시적인 스왑 체인)이 존재한다.

어떠한 디바이스에서도, 지원 할 수 있는 풀 스크린 스왑 체인은 1 개 뿐이다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

윈도우 모드의 멀티 뷰


IDirect3DDevice8::CreateCubeTexture

큐브 텍스쳐 리소스를 생성 한다.

HRESULT CreateCubeTexture(
  UINT EdgeLength,
  UINT Levels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DCubeTexture8** ppCubeTexture
);

파라미터

EdgeLength
[in] 큐브 텍스쳐의 모든 최고다음 레벨 표면의 엣지의 사이즈. 밉맵 레벨이 아래의 픽셀 넓이는, 1 개(살) 위에의 레벨의 픽셀 넓이를 (단순하게) 1/2 한 값이다. 각각의 크기는, 1 픽셀의 사이즈에 거둘 수 있다. 따라서, 2 로 나눗셈 한 결과가 0 의 경우, 대신에 1 이 사용된다.
Levels
[in] 큐브 텍스쳐의 각 표면의 레벨의 수. 0 을 지정 하면, Microsoft® Direct3D® 는, 밉맵화 큐브 텍스쳐를 지원 하는 하드웨어에 대해서, 각면의 1 × 1 픽셀까지의 모든 큐브 텍스쳐 서브 레벨을 생성한다. 그 외의 값을 지정했을 경우는, 1 레벨을 생성한다. IDirect3DBaseTexture8::GetLevelCount 를 호출해, 생성된 레벨수를 확인한다.
Usage
[in] 이 리소스의 사용 방법을 기술하는, 다음의 1 개 이상의 플래그의 편성.
D3DUSAGE_DEPTHSTENCIL
표면이 스텐실 표면으로서 사용되는 것을 나타낸다. 리소스는,IDirect3DDevice8::SetRenderTarget 메소드의 pNewDepthStencil 파라미터에 건네줄 수가 있다. 「주의」를 참조할것.
D3DUSAGE_RENDERTARGET
표면이 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pRenderTarget 파라미터에 건네줄 수가 있다. 「주의」를 참조할것.

D3DUSAGE_RENDERTARGET 또는 D3DUSAGE_DEPTHSTENCIL 중 한쪽이 지정되었을 경우는, 어플리케이션으로 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 할지 어떨지를 확인해야 한다.

Format
[in] D3DFORMAT 열거형의 멤버. 큐브 텍스쳐의 전표면의 전레벨의 포맷을 나타낸다.
Pool
[in] D3DPOOL 열거형의 멤버. 큐브 텍스쳐를 저장 하는 메모리 클래스를 나타낸다.
ppCubeTexture
[out, retval] 생성 된 큐브 텍스쳐 리소스를 나타내는 IDirect3DCubeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

큐브 텍스쳐는, 표면의 집합인 점이 다른 표면과 다르다. 큐브 텍스쳐를 지정해 SetRenderTarget 을 호출하려면 ,IDirect3DCubeTexture8::GetCubeMapSurface 를 사용해 특정의 표면을 선택하고 나서, 그것을 SetRenderTarget 에 건네주지 않으면 안 된다.

텍스쳐 (밉맵)는, 연속해 다운 샘플링 된 (밉맵화 된) 표면의 집합이다. 한편,CreateCubeTexture 로 생성 되는 큐브 텍스쳐는, 표면 마다 1 개(살)씩, 전부 6 개의 텍스쳐 (밉맵)의 집합이다. 모든 표면은, 큐브 텍스쳐에 존재하고 있지 않으면 안 된다. 또, 큐브 맵 표면은, 3 개의 넓이 (x, y, 및 z)가 모두 같은 픽셀 사이즈가 아니면 안된다.

DirectX® 8.0 에서는, 리소스의 사용법이 강제당한다. 특정의 처리에 리소스를 사용하는 어플리케이션은, 리소스 생성시에 그 처리를 지정할 필요가 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::CreateDepthStencilSurface

스텐실 리소스를 생성 한다.

HRESULT CreateDepthStencilSurface(
  UINT Width,
  UINT Height,
  D3DFORMAT Format,
  D3DMULTISAMPLE_TYPE MultiSample,
  IDirect3DSurface8** ppSurface
);

파라미터

Width
[in] 스텐실 표면의 폭 (픽셀 단위).
Height
[in] 스텐실 표면의 높이 (픽셀 단위).
Format
[in] D3DFORMAT 열거형의 멤버. 스텐실 표면의 포맷을 나타낸다. 이 값은, 그 디바이스에 대해서 열거된 스텐실 포맷의 1 개가 아니면 안된다.
MultiSample
[in] 멀티 샘플링 버퍼 타입을 기술하는 D3DMULTISAMPLE_TYPE 열거형의 멤버. 이 값은, 사용할 수 있는 멀티 샘플링 타입의 1 개가 아니면 안된다. 이 표면을 SetRenderTarget 에 건네줄 때는, 멀티 샘플링 타입이 렌더링 타겟의 것과 같지 않으면 안 된다.
ppSurface
[out, retval] 생성 된 스텐실 표면 리소스를 나타내는 IDirect3DSurface8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

주의

스텐실 버퍼의 메모리 클래스는, 항상 D3DPOOL_DEFAULT 이다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CopyRects ,IDirect3DDevice8::SetRenderTarget


IDirect3DDevice8::CreateImageSurface

이미지 표면을 생성 한다.

HRESULT CreateImageSurface(
  UINT Width,
  UINT Height,
  D3DFORMAT Format,
  IDirect3DSurface8** ppSurface
);

파라미터

Width
[in] 이미지 표면의 폭 (픽셀 단위).
Height
[in] 이미지 표면의 높이 (픽셀 단위).
Format
[in] D3DFORMAT 열거형의 멤버. 이미지 표면의 포맷을 나타낸다.
ppSurface
[out, retval] 생성 된 이미지 표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

이미지 표면은 플레이스홀더이며, 락 처리와 IDirect3DDevice8::CopyRects 이외의 모든 Microsoft® Direct3D® 조작에서는 사용할 수 없다.

이미지 표면은, D3DPOOL_SYSTEMMEM 메모리 클래스에 저장 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::CreateIndexBuffer

인덱스 버퍼를 생성 한다.

HRESULT CreateIndexBuffer(
  UINT Length,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DIndexBuffer8** ppIndexBuffer
);

파라미터

Length
[in] 인덱스 버퍼의 사이즈 (바이트 단위).
Usage
[in] 이 리소스의 사용 방법의 제어 정보를 기술하는, 다음의 1 개 이상의 플래그의 편성.
D3DUSAGE_DONOTCLIP
인덱스 버퍼의 내용이 결코 클리핑을 요구하지 않는 것을 나타낸다.
D3DUSAGE_DYNAMIC
버텍스 또는 인덱스 버퍼가 동적인 메모리의 사용을 필요로 하는 것을 나타낸다. 이것을 사용 하면, 드라이버가 배치 장소를 결정할 수 있으므로, 드라이버에 있어 유효하다. 일반적으로, 정적인 버텍스 버퍼는 비디오 메모리에 배치되어 동적인 버텍스 버퍼는 AGP 메모리에 배치된다. 정적인 사용 방법만을 분리할 수 없는 것에 주의 해야 한다. D3DUSAGE_DYNAMIC 를 지정하지 않으면 버텍스 버퍼는 정적으로 생성 된다. D3DUSAGE_DYNAMIC 는, D3DLOCK_DISCARD 및 D3DLOCK_NOOVERWRITE 락킹 플래그에 의해 엄밀하게 강제당한다. 이 결과, D3DLOCK_DISCARD 및 D3DLOCK_NOOVERWRITE 는, D3DUSAGE_DYNAMIC 를 지정해 생성 된 버텍스 및 인덱스 버퍼에서만 유효하다. 이것들은, 정적인 버텍스 버퍼에서는 유효한 플래그는 아니다.

D3DUSAGE_DYNAMIC 는, 관리하의 버텍스 및 인덱스 버퍼에서는 지정할 수 없는 것에 주의 해야 한다. 상세한 것에 대하여는, 「리소스의 관리」를 참조할것.

D3DUSAGE_RTPATCHES
고차원 프리미티브의 드로잉(Drawing)에 인덱스 버퍼를 사용할때 설정한다.
D3DUSAGE_NPATCHES
N 패치의 드로잉(Drawing)에 인덱스 버퍼를 사용할때 설정한다.
D3DUSAGE_POINTS
포인트 스프라이트 또는 인덱스 첨부 포인트 리스트의 드로잉(Drawing)에, 인덱스 버퍼를 사용할때 설정한다.
D3DUSAGE_SOFTWAREPROCESSING
버퍼가 소프트웨어 처리로 사용되는 것을 나타낸다.
D3DUSAGE_WRITEONLY
인덱스 버퍼에의 기입해 조작 밖에 실행할 수 없는 것을 시스템에 통지한다. 이 플래그를 사용 하면, 드라이버는 최적인 메모리 영역을 선택해 효율적으로 기입해 조작이나 렌더링을 실행할 수 있다. 이 능력을 사용해 생성 된 인덱스 버퍼로부터의 read를 시도하면(자), 퍼포먼스가 저하하는 경우가 있다.
Format
[in] D3DFORMAT 열거형의 멤버. 인덱스 버퍼의 포맷을 나타낸다. 유효한 설정은 다음과 같다.
D3DFMT_INDEX16
인덱스는 각각 16 비트이다.
D3DFMT_INDEX32
인덱스는 각각 32 비트이다.

「주의」를 참조할것.

Pool
[in] D3DPOOL 열거형의 멤버. 리소스가 배치되는 유효한 메모리 클래스를 기술한다.
ppIndexBuffer
[out, retval] 생성 된 인덱스 버퍼 리소스를 나타내는 IDirect3DIndexBuffer8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

인덱스 버퍼는, 인덱스를 보관 유지하기 위해서 사용되는 메모리 리소스이며, 표면 버퍼 및 버텍스 버퍼를 닮아 있다. 인덱스 버퍼를 사용하는 것으로, Microsoft® Direct3D® 에서는, 데이터의 불필요한 카피 처리를 피할 수가 있어 의도되고 있는 사용 방법으로 최적인 메모리 타입에 버퍼를 저장 할 수가 있다.

인덱스 버퍼를 사용하려면 , 인덱스 버퍼를 생성 해, 그것을 잠그어, 인덱스를 저장 한다. 다음에, 그 인덱스 버퍼를 언락 해,IDirect3DDevice8::SetIndices 에 건네주어, 버텍스와 버텍스 쉐이더를 설정해,IDirect3DDevice8::DrawIndexedPrimitive 를 호출해 렌더링을 실시한다.

D3DCAPS8 구조체의 MaxVertexIndex 멤버는, 렌더링으로 유효한 인덱스 버퍼의 타입을 나타낸다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 :D3d8.lib 을 사용.

참조

IDirect3DIndexBuffer8::GetDesc


IDirect3DDevice8::CreatePixelShader

픽셀 쉐이더를 생성 한다.

HRESULT CreatePixelShader(
  CONST DWORD* pFunction,
  DWORD* pHandle
);

파라미터

pFunction
[in] 블렌딩 처리를 지정하는 픽셀 쉐이더 함수의 토큰 배열에의 포인터. 이 값은 NULL 로 할 수 없다.
pHandle
[out, retval] 돌려주어지는 픽셀 쉐이더의 핸들에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DeletePixelShader ,D3DXAssembleShader ,D3DXAssembleShaderFromFileA ,D3DXAssembleShaderFromFileW


IDirect3DDevice8::CreateRenderTarget

렌더링 타겟 표면을 생성 한다.

HRESULT CreateRenderTarget(
  UINT Width,
  UINT Height,
  D3DFORMAT Format,
  D3DMULTISAMPLE_TYPE MultiSample,
  BOOL Lockable,
  IDirect3DSurface8** ppSurface
);

파라미터

Width
[in] 렌더링 타겟 표면의 폭 (픽셀 단위).
Height
[in] 렌더링 타겟 표면의 높이 (픽셀 단위).
Format
[in] D3DFORMAT 열거형의 멤버. 렌더링 타겟의 포맷을 나타낸다.
MultiSample
[in] 멀티 샘플링 버퍼 타입을 기술하는 D3DMULTISAMPLE_TYPE 열거형의 멤버. 이 파라미터는, 생성 하는 렌더링 타겟의 anti-aliasing 타입을 지정하는 것이다. 이 타입은, 양쪽 모두의 버퍼를 SetRenderTarget 에 건네줄 때의 스텐실 버퍼의 것과 같지 않으면 안 된다.
Lockable
[in] 어플리케이션이 Lockable 에 TRUE 를 지정하지 않는 한, 렌더링 타겟은 잠글 수 없다. 락 가능한 렌더링 타겟으로 따라, 일부의 그래픽 하드웨어에서는 퍼포먼스의 코스트가 향상하는 것에 주의 해야 한다.
ppSurface
[out, retval] IDirect3DSurface8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

렌더링 타겟 표면은, D3DPOOL_DEFAULT 메모리 클래스에 저장 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::CreateStateBlock

모든 디바이스 스테이트, 버텍스 관련의 스테이트, 또는 픽셀 관련의 스테이트의 값을 포함한 새로운 스테이트 블록을 생성 한다.

HRESULT CreateStateBlock(
  D3DSTATEBLOCKTYPE Type,
  DWORD* pToken
);

파라미터

Type
[in] 메소드로 수중에 넣는 스테이트 데이터의 종류. 이 파라미터에는,D3DSTATEBLOCKTYPE 열거형으로 정의되고 있는 값을 설정할 수 있다.
pToken
[out, retval] 메소드가 성공했을 경우에 스테이트 블록의 핸들을 저장 하는 DWORD 값에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

값 0xFFFFFFFF 는, 무효인 스테이트 블록 핸들이다.

버텍스 관련의 디바이스 스테이트란, 일반적으로는 시스템의 버텍스의 처리 방법으로 영향을 주는 스테이트를 말한다. 픽셀 관련의 스테이트란, 라스터화에 있어서의 시스템의 픽셀 또는 깊이 버퍼의 처리 방법으로 영향을 주는 디바이스 스테이트를 말한다. 스테이트에 따라서는 양쪽 모두에 속하는 경우도 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::ApplyStateBlock ,IDirect3DDevice8::BeginStateBlock ,IDirect3DDevice8::CaptureStateBlock ,IDirect3DDevice8::EndStateBlock ,IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::CreateTexture

텍스쳐 리소스를 생성 한다.

HRESULT CreateTexture(
  UINT Width,
  UINT Height,
  UINT  Levels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DTexture8** ppTexture
);

파라미터

Width
[in] 최상정도의 텍스쳐의 폭 (픽셀 단위). 밉맵 레벨이 아래의 픽셀 넓이는 1 개 위에의 레벨의 픽셀 넓이를 (단순하게) 1/2 한 값이다. 각각의 크기는, 1 픽셀의 사이즈에 거둘 수 있다. 따라서, 2 로 나눗셈 한 결과가 0 의 경우, 대신에 1 이 사용된다.
Height
[in] 최상정도의 텍스쳐의 높이 (픽셀 단위). 밉맵 레벨이 아래의 픽셀 넓이는 1 개 위에의 레벨의 픽셀 넓이를 (단순하게) 1/2 한 값이다. 각각의 크기는, 1 픽셀의 사이즈에 거둘 수 있다. 따라서, 2 로 나눗셈 한 결과가 0 의 경우, 대신에 1 이 사용된다.
Levels
[in] 텍스쳐에 있는 레벨의 수. 0 을 지정 하면, MIP 맵화 텍스쳐를 지원 하는 하드웨어에 대해, Microsoft® Direct3D® 는, 1 × 1 픽셀까지의 모든 텍스쳐 서브 레벨을 생성한다. 그 외의 값을 지정했을 경우는, 1 레벨을 생성한다. IDirect3DBaseTexture8::GetLevelCount 를 호출해, 생성된 레벨수를 확인한다.
Usage
[in] 이 리소스의 사용 방법을 기술하는, 다음의 1 개 이상의 플래그의 편성.
D3DUSAGE_DEPTHSTENCIL
표면이 스텐실 표면으로서 사용되는 것을 나타낸다. 리소스는,IDirect3DDevice8::SetRenderTarget 메소드의 pNewZStencil 파라미터에 건네줄 수가 있다.
D3DUSAGE_RENDERTARGET
표면이 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 의pRenderTarget 파라미터에 건네줄 수가 있다.

D3DUSAGE_RENDERTARGET 또는 D3DUSAGE_DEPTHSTENCIL 중 한쪽이 지정되었을 경우는, 어플리케이션으로 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 할지 어떨지를 확인해야 한다.

Format
[in] D3DFORMAT 열거형의 멤버. 텍스쳐의 전레벨의 포맷을 나타낸다.
Pool
[in] D3DPOOL 열거형의 멤버. 텍스쳐를 저장 하는 메모리 클래스를 나타낸다.
ppTexture
[out, retval] 생성 된 텍스쳐 리소스를 나타내는 IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

텍스쳐를 지정해 IDirect3DDevice8::SetRenderTarget 를 호출하려면 ,IDirect3DTexture8::GetSurfaceLevel 를 사용해 레벨을 선택하고 나서, 그 표면을 SetRenderTarget 에 건네주지 않으면 안 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::CreateVertexBuffer

버텍스 버퍼를 생성 한다.

HRESULT CreateVertexBuffer(
  UINT Length,
  DWORD Usage,
  DWORD FVF,
  D3DPOOL Pool,
  IDirect3DVertexBuffer8** ppVertexBuffer
);

파라미터

Length
[in] 버텍스 버퍼의 사이즈 (바이트 단위). 유연한 버텍스 포맷 (FVF) 버텍스 버퍼의 경우는,Length 는 적어도 1 개의 버텍스를 저장 할 수 있는 크기가 아니면 안되지만, 버텍스 사이즈의 배수일 필요는 없다. Length 는 비 FVF 버퍼에 대해서는 검증되지 않는다. 「주의」를 참조할것.
Usage
[in] 이 리소스의 사용 방법의 제어 정보를 기술하는, 다음의 1 개 이상의 플래그의 편성.
D3DUSAGE_DONOTCLIP
버텍스 버퍼의 내용이 결코 클리핑을 요구하지 않는 것을 나타낸다. 이 플래그가 설정된 버퍼를 사용해 렌더링 하는 경우는, D3DRS_CLIPPING 렌더링 스테이트가 FALSE 로 설정되어 있지 않으면 안 된다.
D3DUSAGE_DYNAMIC
버텍스 또는 인덱스 버퍼가 동적인 메모리의 사용을 필요로 하는 것을 나타낸다. 이것을 사용 하면, 드라이버가 배치 장소를 결정할 수 있으므로, 드라이버에 있어 유효하다. 일반적으로, 정적인 버텍스 버퍼는 비디오 메모리에 배치되어 동적인 버텍스 버퍼는 AGP 메모리에 배치된다. 정적인 사용 방법만을 분리할 수 없는 것에 주의 해야 한다. D3DUSAGE_DYNAMIC 를 지정하지 않으면 버텍스 버퍼는 정적으로 생성 된다. D3DUSAGE_DYNAMIC 는, D3DLOCK_DISCARD 및 D3DLOCK_NOOVERWRITE 락킹 플래그에 의해 엄밀하게 강제당한다. 이 결과, D3DLOCK_DISCARD 및 D3DLOCK_NOOVERWRITE 는, D3DUSAGE_DYNAMIC 를 지정해 생성 된 버텍스 및 인덱스 버퍼에서만 유효하다. 이것들은, 정적인 버텍스 버퍼에서는 유효한 플래그는 아니다.

동적인 버텍스 버퍼의 사용 방법의 상세한 것에 대하여는, 「동적인 버텍스 및 인덱스 버퍼의 사용법」을 참조할것.

D3DUSAGE_DYNAMIC 는, 관리하의 버텍스 및 인덱스 버퍼에서는 지정할 수 없는 것에 주의 해야 한다. 상세한 것에 대하여는, 「리소스의 관리」를 참조할것.

D3DUSAGE_RTPATCHES
고차원 프리미티브의 드로잉(Drawing)에 버텍스 버퍼를 사용할때 설정한다.
D3DUSAGE_NPATCHES
N 패치의 드로잉(Drawing)에 버텍스 버퍼를 사용할때 설정한다.
D3DUSAGE_POINTS
포인트 스프라이트 또는 인덱스 첨부 포인트 리스트의 드로잉(Drawing)에, 버텍스 버퍼를 사용할때 설정한다.
D3DUSAGE_SOFTWAREPROCESSING
소프트웨어 버텍스 처리로 사용하는 버텍스 버퍼인 것을 나타낸다.
D3DUSAGE_WRITEONLY
버텍스 버퍼에의 기입해 조작 밖에 실행하지 않는 것을 시스템에 알린다. 이 플래그를 사용하는 것으로써, 드라이버는 최적인 메모리 영역을 선택해 효율적으로 기입해 조작이나 렌더링을 실행한다. 이 능력을 사용해 생성 된 버텍스 버퍼로부터의 읽기는 실패한다.
FVF
[in] 유연한 버텍스 포맷 플래그의 편성. 버퍼내의 버텍스의 버텍스 포맷을 기술하는 사용 방법의 지정자. 이 파라미터에 유효한 FVF 코드를 설정 하면, FVF 버텍스 버퍼가 생성 된다 ( 「주의」를 참조). 제로를 설정 하면, 버텍스 버퍼는 비 FVF 버텍스 버퍼가 된다.
Pool
[in] D3DPOOL 열거형의 멤버. 리소스가 배치되는 유효한 메모리 클래스를 기술한다.
ppVertexBuffer
[out, retval] 생성 된 버텍스 버퍼 리소스를 나타내는 IDirect3DVertexBuffer8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

IDirect3DDevice8 인터페이스는, 버텍스 버퍼 오브젝트에 저장 된 버텍스 데이터를 사용하는 프리미티브의 렌더링을 지원 하고 있다. 버텍스 버퍼는 IDirect3DDevice8 인터페이스로부터 생성 되어, 버텍스 버퍼의 기본으로 되어 있는 IDirect3DDevice8 오브젝트에서만 사용할 수 있다.

FVF 파라미터에 제로 이외의 값을 설정 하면나무는, 유효한 FVF 코드가 아니면 안되어, 이것은 버퍼의 내용이 FVF 코드에 의해 특징지울 수 있는 것을 나타내고 있다. FVF 코드로 생성 된 버텍스 버퍼를, FVF 버텍스 버퍼라고 한다. 상세한 것에 대하여는, 「FVF 버텍스 버퍼」를 참조할것.

D3DUSAGE_SOFTWAREPROCESSING 플래그는, 버텍스 버퍼가 소프트웨어 버텍스 처리로 사용되는 것인 것을 나타내고 있다. 상세한 것에 대하여는, 「디바이스의 종류와 버텍스 처리의 요건」을 참조할것.

비 FVF 버퍼를 사용해, 멀티 패스 렌더링 또는 싱글 패스의 멀티 텍스쳐 렌더링으로, 데이터를 인터리브 할 수가 있다. 이것을 실시하려면 , 1 개의 버퍼에는 지오메트리 데이터를 저장 해, 이제(벌써) 1 개의 버퍼에는 렌더링 하는 각 텍스쳐의 텍스쳐 좌표를 저장 한다. 렌더링시에는, 텍스쳐 좌표를 저장 하는 각 버퍼와 함께, 지오메트리 데이터를 저장 하는 버퍼가 인터리브 된다. 대신에 FVF 버퍼를 사용했을 경우, 각 버퍼에, 렌더링 하는 각 텍스쳐에 고유의 텍스쳐 좌표 데이터에 가세해, 같은 지오메트리 데이터를 저장 할 필요가 있다. 이것은, 사용하는 스트래터지에도 밤이, 스피드 또는 메모리의 면에서 마이너스가 된다. 텍스쳐 좌표의 상세한 것에 대하여는, 「텍스쳐 좌표에 대하며」를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVertexBuffer8::GetDesc ,IDirect3DDevice8::ProcessVertices


IDirect3DDevice8::CreateVertexShader

버텍스 쉐이더를 생성 해, 생성이 성공했을 경우는, 그 쉐이더를 경향 쉐이더로서 설정한다.

HRESULT CreateVertexShader(
  CONST DWORD* pDeclaration,
  CONST DWORD* pFunction,
  DWORD* pHandle,
  DWORD Usage
);

파라미터

pDeclaration
[in, out] 버텍스 쉐이더 선언 토큰 배열에의 포인터. 이 파라미터에서는 쉐이더에의 입력을 정의해, 입력 데이터 스트림중의 버텍스 요소의 쉐이더에 의한 사용 방법도 지정한다.
pFunction
[in, out] 버텍스 쉐이더 기능 토큰 배열에의 포인터. 이 파라미터에서는, 각 버텍스에 적용하는 조작을 정의한다. 이 파라미터를 NULL 로 하면(자), 고정 기능 파이프라인용의 쉐이더가 생성 된다. pDeclaration 로 나타나고 있는 파라미터 선언이 현재의 선언이 되어, 그 후 IDirect3DDevice8::SetVertexShader 의 호출로 핸들 포인터를 지정하는 경우는, 이 파라미터 선언을 설정할 수 있다.

이 파라미터를 NULL 이외에 하면, 쉐이더는 프로그램 가능하게 된다.

pHandle
[in, out] 돌려주어지는 버텍스 쉐이더의 핸들에의 포인터. 이 값은 NULL 로 설정할 수 없다.
Usage
[in] 버텍스 쉐이더에 대한 사용 방법의 제어 정보. 다음의 플래그를 설정할 수 있다.
D3DUSAGE_SOFTWAREPROCESSING
소프트웨어 버텍스 처리로 사용하는 버텍스 쉐이더인 것을 나타낸다. D3DRENDERSTATETYPE 열거형의 D3DRS_SOFTWAREVERTEXPROCESSING 멤버가 TRUE 때에 사용하는 버텍스 쉐이더에 대해서는 D3DUSAGE_SOFTWAREPROCESSING 플래그를 설정하지 않으면 안되어, D3DRS_SOFTWAREVERTEXPROCESSING 가 FALSE 때의 버텍스 쉐이더에 대해서는 이 플래그를 설정해서는 안 된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

버텍스 쉐이더는, 쉐이더의 선언과 기능을 지정하는 2 개의 토큰 배열에 의해 정의된다. 토큰 배열은, 1 개(살) 이상의 DWORD 토큰으로 구성되어 있어 배열의 말미는 특수한 값 0xFFFFFFFF 의 토큰으로 나타난다.

쉐이더의 선언은 쉐이더의 정적인 외부 인터페이스를 정의하고 있어, 버텍스 레지스터 입력에 대한 스트림 데이터의 바인드나, 쉐이더의 정수 메모리에 로드 되는 값등이 포함된다. 쉐이더의 기능에서는, 쉐이더가 디바이스에 바인드 되고 있는 동안에 각 버텍스에 대한 처리를 위해서(때문에) 실행되는 명령의 배열로서 쉐이더의 동작이 정의되고 있다. 기능 배열을 지정하지 않고 쉐이더를 생성 하면, 그 쉐이더가 경향 쉐이더 때에는, 고정 기능의 버텍스 처리가 적용된다.

선언의 토큰 배열을 생성하기 위해서 사용하는 매크로의 정의에 대해서는, d3d8types.h 를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DeleteVertexShader ,D3DXAssembleShader ,D3DXAssembleShaderFromFileA ,D3DXAssembleShaderFromFileW ,D3DXDeclaratorFromFVF


IDirect3DDevice8::CreateVolumeTexture

볼륨 텍스쳐 리소스를 생성 한다.

HRESULT CreateVolumeTexture(
  UINT Width,
  UINT Height,
  UINT Depth,
  UINT Levels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DVolumeTexture8** ppVolumeTexture
);

파라미터

Width
[in] 최상정도의 볼륨 텍스쳐의 폭 (픽셀 단위). 이 값은 2 의 거듭제곱이 아니면 안된다. 밉맵 레벨이 아래의 픽셀 넓이는 1 개 위에의 레벨의 픽셀 넓이를 (단순하게) 1/2 한 값이다. 각각의 크기는, 1 픽셀의 사이즈에 거둘 수 있다. 따라서, 2 로 나눗셈 한 결과가 0 의 경우, 대신에 1 이 사용된다.
Height
[in] 최상정도의 볼륨 텍스쳐의 높이 (픽셀 단위). 이 값은 2 의 거듭제곱이 아니면 안된다. 밉맵 레벨이 아래의 픽셀 넓이는 1 개 위에의 레벨의 픽셀 넓이를 (단순하게) 1/2 한 값이다. 각각의 크기는, 1 픽셀의 사이즈에 거둘 수 있다. 따라서, 2 로 나눗셈 한 결과가 0 의 경우, 대신에 1 이 사용된다.
Depth
[in] 최상정도의 볼륨 텍스쳐의 깊이 (픽셀 단위). 이 값은 2 의 거듭제곱이 아니면 안된다. 밉맵 레벨이 아래의 픽셀 넓이는 1 개 위에의 레벨의 픽셀 넓이를 (단순하게) 1/2 한 값이다. 각각의 크기는, 1 픽셀의 사이즈에 거둘 수 있다. 따라서, 2 로 나눗셈 한 결과가 0 의 경우, 대신에 1 이 사용된다.
Levels
[in] 텍스쳐에 있는 레벨의 수. 0 을 지정 하면, 밉맵화 볼륨 텍스쳐를 지원 하는 하드웨어에 대해, Microsoft® Direct3D® 는, 1 × 1 × 1 픽셀까지의 모든 텍스쳐 서브 레벨을 생성한다. 그 외의 값을 지정했을 경우는, 1 레벨을 생성한다. IDirect3DBaseTexture8::GetLevelCount 를 호출해, 생성되는 레벨수를 확인한다.
Usage
[in] 현재는 사용되어 있지 않다. 0 으로 설정된다.
Format
[in] D3DFORMAT 열거형의 멤버. 볼륨 텍스쳐의 전레벨의 포맷을 나타낸다.
Pool
[in] D3DPOOL 열거형의 멤버. 볼륨 텍스쳐를 저장 하는 메모리 클래스를 나타낸다.
ppVolumeTexture
[out, retval] 생성 된 볼륨 텍스쳐 리소스를 나타내는 IDirect3DVolumeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::DeletePixelShader

지정된 핸들로 참조되고 있는 픽셀 쉐이더를 삭제한다.

HRESULT DeletePixelShader(
  DWORD Handle
);

파라미터

Handle
[in] 픽셀 쉐이더의 핸들. 내부 엔트리로부터 삭제하는 픽셀 쉐이더를 나타낸다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CreatePixelShader


IDirect3DDevice8::DeleteStateBlock

이전에 기록하고 있던 디바이스 스테이트 블록을 삭제한다.

HRESULT DeleteStateBlock(
  DWORD Token
);

파라미터

Token
[in] 삭제하는 디바이스 스테이트 블록에의 핸들. 이것은 전에 호출한 IDirect3DDevice8::EndStateBlock 메소드에 의해 돌려주어진다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

값 0xFFFFFFFF 는, 무효인 스테이트 블록 핸들이다.

다른 스테이트 블록의 기록중에, 디바이스 스테이트 블록을 삭제할 수 없다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::ApplyStateBlock ,IDirect3DDevice8::BeginStateBlock ,IDirect3DDevice8::CaptureStateBlock ,IDirect3DDevice8::CreateStateBlock ,IDirect3DDevice8::EndStateBlock


IDirect3DDevice8::DeletePatch

캐쉬되고 있던 고차원 패치를 해방한다.

HRESULT DeletePatch(
  UINT Handle
);

파라미터

Handle
[in] 삭제하는 캐쉬되고 있던 고차원 패치의 핸들.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DrawRectPatch ,IDirect3DDevice8::DrawTriPatch ,패치의 드로잉(Drawing)


IDirect3DDevice8::DeleteVertexShader

지정된 핸들로 참조되고 있는 버텍스 쉐이더를 삭제해, 관련하는 리소스를 해방한다.

HRESULT DeleteVertexShader(
  DWORD Handle
);

파라미터

Handle
[in] 버텍스 쉐이더의 핸들. 삭제하는 버텍스 쉐이더를 나타낸다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CreateVertexShader


IDirect3DDevice8::DrawIndexedPrimitive

버텍스의 배열에의 인덱스에 근거해, 지정된 지오메트리 프리미티브를 렌더링 한다.

HRESULT DrawIndexedPrimitive(
  D3DPRIMITIVETYPE Type,
  UINT MinIndex,
  UINT NumVertices,
  UINT StartIndex,
  UINT PrimitiveCount
);

파라미터

Type
[in] D3DPRIMITIVETYPE 열거형의 멤버. 렌더링 하는 프리미티브의 종류를 기술한다. 「주의」를 참조할것.
MinIndex
[in] 이 호출동안에 사용되는 버텍스군에 대한 최소의 버텍스 인덱스.
NumVertices
[in] 이 호출로 사용되는 버텍스의 수 (BaseVertexIndex + MinIndex 로부터 시작된다).
StartIndex
[in] 인덱스 배열 중(안)에서 버텍스의 독해를 시작 하는 위치.
PrimitiveCount
[in] 렌더링 하는 프리미티브의 수. 사용되는 버텍스의 수는, 프리미티브 카운트의 기능과 프리미티브의 종류이다. 프리미티브의 허용 최대수는,D3DCAPS8 구조체의 MaxPrimitiveCount 멤버를 체크해 결정된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 현재의 데이터 입력 스트림의 집합으로부터 인덱스 첨부 프리미티브를 드로잉(Drawing) 한다.

MinIndex, 및 인덱스 스트림의 모든 버텍스는,IDirect3DDevice8::SetIndices 의 호출시로 설정되는 BaseVertexIndex 에 관련한다.

minIndex 파라미터와 NumVertices 파라미터로,DrawIndexedPrimitive 가 호출할 것에 사용하는 버텍스 인덱스의 범위를 지정한다. 이 2 개의 파라미터를 사용해, 인덱스 붙이고 하기 전의 버텍스군의 시퀀셜인 범위를 처리하는 것으로, 인덱스 첨부 프리미티브의 버텍스 처리를 최적화한다. 호출동안에 사용되는 인덱스가 이 범위외의 버텍스를 참조할것은 무효이다.

인덱스 배열이 설정되어 있지 않은 경우,DrawIndexedPrimitive 는 실패한다.

D3DPRIMITIVETYPE 열거형의 D3DPT_POINTLIST 멤버는 지원되어 있지 않기 때문에,Type 로서 지정해서는 안된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DrawPrimitive ,IDirect3DDevice8::SetStreamSource ,프리미티브의 렌더링


IDirect3DDevice8::DrawIndexedPrimitiveUP

유저 메모리 포인터로 지정되고 있는 데이터로, 지정되고 있는 지오메트리 프리미티브를 렌더링 한다.

HRESULT DrawIndexedPrimitiveUP(
  D3DPRIMITIVETYPE PrimitiveType,
  UINT MinIndex,
  UINT NumVertices,
  UINT PrimitiveCount,
  CONST void* pIndexData,
  D3DFORMAT IndexDataFormat,
  CONST void* pVertexStreamZeroData,
  UINT VertexStreamZeroStride
);

파라미터

PrimitiveType
[in] D3DPRIMITIVETYPE 열거형의 멤버. 렌더링 하는 프리미티브의 종류를 기술한다.
MinIndex
[in] 이 호출동안에 사용되는 버텍스군에 대한, 0 (pIndexData 의 시작 위치)을 기준으로 하는 최소의 버텍스 인덱스.
NumVertices
[in] 이 호출로 사용되는 버텍스의 수 (MinIndex. (으)로부터 시작된다).
PrimitiveCount
[in] 렌더링 하는 프리미티브의 수. 사용되는 인덱스의 수는, 프리미티브 카운트의 기능과 프리미티브의 종류이다. 프리미티브의 허용 최대수는,D3DCAPS8 구조체의 MaxPrimitiveCount 멤버를 체크해 결정된다.
pIndexData
[in] 인덱스 데이터에 대한 유저 메모리 포인터.
IndexDataFormat
[in] 인덱스 데이터의 포맷을 나타내는 D3DFORMAT 열거형의 멤버. 유효한 설정은 다음과 같다.
D3DFMT_INDEX16
인덱스는 각각 16 비트이다.
D3DFMT_INDEX32
인덱스는 각각 32 비트이다.
pVertexStreamZeroData
[in] 버텍스 스트림을 제로로 하기 위해서(때문에) 사용하는 버텍스 데이터의 유저 메모리 포인터.
VertexStreamZeroStride
[in] 각 버텍스의 데이터간의 보폭 (바이트 단위).

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 버텍스 데이터를 버텍스 버퍼에 저장 할 수 없는 어플리케이션으로 사용한다. 이 메소드는 단일의 버텍스 스트림만을 지원 한다. 이 호출은, 버텍스 스트림에 제공된 버텍스 데이터의 포인터와 보폭을 제로로 한다. 스트림 제로 이외의 버텍스 스트림을 참조하는 경향 버텍스 쉐이더를 선언할 수 없다 (or 를 선언 하면 에러가 된다).

DrawIndexedPrimitiveUP 의 호출의 뒤,IDirect3DDevice8::GetStreamSource 로 참조되는 스트림 제로의 설정은, NULL 로 설정된다. 또,IDirect3DDevice8::SetIndices 에 대한 인덱스 버퍼의 설정도, NULL 로 설정된다.

DrawIndexPrimitiveUP 에게 건네지는 버텍스 데이터는 소환 후에 존속할 필요는 없다. Direct3D 는 호출로부터 돌아온 시점에서 그 데이터에의 액세스를 완료하고 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DrawPrimitiveUP ,IDirect3DDevice8::SetStreamSource ,프리미티브의 렌더링


IDirect3DDevice8::DrawPrimitive

현재의 데이터 입력 스트림 세트로부터, 지정된 타입의 비인덱스 첨부 지오메트리 프리미티브의 순서를 렌더링 한다.

HRESULT DrawPrimitive(
  D3DPRIMITIVETYPE PrimitiveType,
  UINT StartVertex,
  UINT PrimitiveCount
);

파라미터

PrimitiveType
[in] D3DPRIMITIVETYPE 열거형의 멤버. 렌더링 하는 프리미티브의 종류를 기술한다.
StartVertex
[in] 로드하는 최초의 버텍스의 인덱스. StartVertex 를 선두에, 올바른 버텍스수가 버텍스 버퍼로부터 읽어내진다.
PrimitiveCount
[in] 렌더링 하는 프리미티브의 수. 프리미티브의 허용 최대수는,D3DCAPS8 구조체의 MaxPrimitiveCount 멤버를 체크해 결정된다. PrimitiveCount 는, 프리미티브 타입으로 지정된 프리미티브의 수이다. 프리미티브 타입이 선리스트의 경우, 각 프리미티브는 2 개의 버텍스를 가진다. 프리미티브 타입이 삼각형 리스트의 경우는, 각 프리미티브는 3 개의 버텍스를 가진다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

한 번에 1 개의 삼각형을 지정해 DrawPrimitive 를 호출해서는 안된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DrawIndexedPrimitive ,IDirect3DDevice8::SetStreamSource ,프리미티브의 렌더링


IDirect3DDevice8::DrawPrimitiveUP

유저 메모리 포인터로 지정된 데이터를, 지정된 타입의 지오메트리 프리미티브의 순서로서 렌더링 한다.

HRESULT DrawPrimitiveUP(
  D3DPRIMITIVETYPE PrimitiveType,
  UINT PrimitiveCount,
  CONST void* pVertexStreamZeroData,
  UINT VertexStreamZeroStride
);

파라미터

PrimitiveType
[in] D3DPRIMITIVETYPE 열거형의 멤버. 렌더링 하는 프리미티브의 종류를 기술한다.
PrimitiveCount
[in] 렌더링 하는 프리미티브의 수. 프리미티브의 허용 최대수는,D3DCAPS8 구조체의 MaxPrimitiveCount 멤버를 체크해 결정된다.
pVertexStreamZeroData
[in] 버텍스 스트림을 제로로 하기 위해서(때문에) 사용하는 버텍스 데이터의 유저 메모리 포인터.
VertexStreamZeroStride
[in] 각 버텍스의 데이터간의 보폭 (바이트 단위).

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 버텍스 데이터를 버텍스 버퍼에 저장 할 수 없는 어플리케이션으로 사용한다. 이 메소드는 단일의 버텍스 스트림만을 지원 한다. 이 호출은, 버텍스 스트림에 제공된 버텍스 데이터의 포인터와 보폭을 제로로 한다. 스트림 제로 이외의 버텍스 스트림을 참조하는 경향 버텍스 쉐이더를 선언할 수 없다 (or 를 선언 하면 에러가 된다).

DrawPrimitiveUP 의 호출의 뒤,IDirect3DDevice8::GetStreamSource 로 참조되는 스트림 제로의 설정은, NULL 로 설정된다.

DrawPrimitiveUP 에게 건네지는 버텍스 데이터는 소환 후에 존속할 필요는 없다. Direct3D 는 호출로부터 돌아온 시점에서 그 데이터에의 액세스를 완료하고 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DrawIndexedPrimitiveUP ,IDirect3DDevice8::SetStreamSource ,프리미티브의 렌더링


IDirect3DDevice8::DrawRectPatch

현재 설정되어 있는 스트림을 사용해, 직사각형의 고차원 패치를 드로잉(Drawing) 한다.

HRESULT DrawRectPatch(
  UINT Handle,
  CONST float* pNumSegs,
  CONST D3DRECTPATCH_INFO* pRectPatchInfo
);

파라미터

Handle
[in] 드로잉(Drawing) 하는 직사각형의 고차원 패치에의 핸들.
pNumSegs
[in, out] 테셀레이션 할 경우에 고차원 프리미티브의 각 엣지를 분할하는 세그먼트(segment)의 수를 나타내는 부동 소수점값에의 포인터.
pRectPatchInfo
[in, out] D3DRECTPATCH_INFO 구조체에의 포인터. 드로잉(Drawing) 하는 직사각형의 고차원 패치를 기술한다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DeletePatch ,패치의 드로잉(Drawing)


IDirect3DDevice8::DrawTriPatch

현재 설정되어 있는 스트림을 사용해, 삼각형의 고차원 패치를 드로잉(Drawing) 한다.

HRESULT DrawTriPatch(
  UINT Handle,
  CONST float* pNumSegs,
  CONST D3DTRIPATCH_INFO* pTriPatchInfo
);

파라미터

Handle
[in] 드로잉(Drawing) 하는 삼각형의 고차원 패치에의 핸들.
pNumSegs
[in, out] 테셀레이션 할 경우에 고차원 프리미티브의 각 엣지를 분할하는 세그먼트(segment)의 수를 나타내는 부동 소수점값에의 포인터.
pTriPatchInfo
[in, out] D3DTRIPATCH_INFO 구조체에의 포인터. 드로잉(Drawing) 하는 삼각형의 고차원 패치를 기술한다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DeletePatch ,패치의 드로잉(Drawing)


IDirect3DDevice8::EndScene

IDirect3DDevice8::BeginScene 메소드의 호출에 의해 시작 된 장면을 종료한다.

HRESULT EndScene();

파라미터

없음.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드가 성공하면(자), 장면이 렌더링 되어 렌더링 후의 장면이 디바이스 표면에 보관 유지된다.

장면의 렌더링이 정상적으로 시작 하고 있는 경우, 다른 장면의 렌더링을 시작 하기 위해서 IDirect3DDevice8::BeginScene 메소드를 호출하려면 , 그 전에 이 메소드를 호출할 필요가 있는BeginScene 메소드의 호출이 실패하고 있는 경우는 장면의 렌더링은 시작 하고 있지 않기 때문에, 이 메소드를 호출할 필요는 없다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::BeginScene


IDirect3DDevice8::EndStateBlock

디바이스 스테이트 블록의 기록을 정지해 스테이트 블록의 핸들을 취득하도록(듯이) Microsoft® Direct3D® 에 지시한다.

HRESULT EndStateBlock(
  DWORD* pToken
);

파라미터

pToken
[out, retval] 기록을 종료하는 디바이스 스테이트 블록의 핸들을 저장 하는 변수에의 포인터. 이 값은,IDirect3DDevice8::ApplyStateBlock 메소드 및 IDirect3DDevice8::DeleteStateBlock 메소드로 사용된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

주의

값 0xFFFFFFFF 는, 무효인 스테이트 블록 핸들이다.

참조

IDirect3DDevice8::ApplyStateBlock ,IDirect3DDevice8::BeginStateBlock ,IDirect3DDevice8::CaptureStateBlock ,IDirect3DDevice8::CreateStateBlock ,IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::GetAvailableTextureMem

사용 가능한 텍스쳐 메모리의 양의 추정값을 돌려준다.

UINT GetAvailableTextureMem();

파라미터

없음.

반환값

이 함수는, 사용 가능한 텍스쳐 메모리의 추정값을 돌려준다.

주의

돌려주어지는 값은, 가장 가까운 MB 에 말 수 있다. 이러한 처리를 하는 것은, 특정의 리소스에 의한 비디오 메모리의 소비에 영향을 주는 alignment나 다른 문제에 의해, 비디오 메모리의 추정값을 정확하게 요구할 수가 없기 때문이다. 어플리케이션에서는, 이 값을 사용해, 이용할 수 있는 메모리의 대범한 양을 추정해, 할당하려고 하는 밉맵의 레벨수와 같은 리소스에 관한 거시적인 결정을 내릴 수 있지만, 다른 리소스를 할당하는데 충분한 메모리가 남아 있는지 어떤지라고 한 작은 스케일의 결정에 사용할 수 없다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::GetBackBuffer

디바이스의 스왑 체인으로부터 백 버퍼를 취득한다.

HRESULT GetBackBuffer(
  UINT BackBuffer,
  D3DBACKBUFFER_TYPE Type,
  IDirect3DSurface8** ppBackBuffer
);

파라미터

BackBuffer
[in] 돌려주어지는 백 버퍼 오브젝트의 인덱스. 백 버퍼는 0 으로부터 백 버퍼의 총수 - 1 까지 넘버링 된다. 0 의 반환값은 최초의 백 버퍼를 나타내, 프런트 버퍼는 아니다. 이 메소드를 사용해 프런트 버퍼에 액세스 할 수 없다.
Type
[in] DirectX 8.0 에서는 스테레오 뷰는 지원되어 있지 않기 때문에, 이 파라미터의 유효한 값은 D3DBACKBUFFER_TYPE_MONO 뿐이다.
ppBackBuffer
[out, retval] 돌려주어지는 백 버퍼 표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

BackBuffer 가 백 버퍼의 총수 이상의 경우, 함수는 실패해,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DSurface8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DSurface8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::GetClipPlane

디바이스의 유저 정의 클립면의 계수를 취득한다.

HRESULT GetClipPlane(
  DWORD Index,
  float* pPlane
);

파라미터

Index
[in] 평면 방정식의 계수를 취득하는 클립면의 인덱스.
pPlane
[out] 일반 평면 방정식에 대해 클립면의 계수를 나타내는 값의, 4 요소로 구성되는 배열에의 포인터. 「주의」를 참조할것.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다. 이 에러는,Index 의 값이 디바이스로 지원 되는 최대 클립면인덱스를 넘고 있는지,pPlane 의 배열이 4 개의 부동 소수점값을 저장 할 만큼 크지 않은 것을 나타낸다.

주의

이 메소드로 취득하는 계수는, 일반 평면 방정식의 형태를 취한다. pPlane 의 배열의 값이 배열내에서의 순서에 A, B, C, 및 D 와 라벨 붙이고 되고 있는 경우, 이러한 값은 일반 평면 방정식이 Ax + By + Cz + Dw = 0 이 되도록(듯이) 적용된다. Ax + By + Cz + Dw >= 0 인 경우, 동차 좌표 (x, y, z, w)의 포인트는 평면에서 잘라내진 반의 공간에 표시된다. 클립 얼굴 또는 배후에 존재하는 포인트는 장면으로부터 클리핑 된다.

이 메소드로 사용되는 평면 방정식은 월드 공간에 존재해, 그 전에 호출하는 IDirect3DDevice8::SetClipPlane 메소드에 의해 설정된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetClipPlane


IDirect3DDevice8::GetClipStatus

클립 스테이터스를 취득한다.

HRESULT GetClipStatus(
  D3DCLIPSTATUS8* pClipStatus
);

파라미터

pClipStatus
[out] 클립 스테이터스를 기술하는 D3DCLIPSTATUS8 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

이 인수가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetClipStatus


IDirect3DDevice8::GetCreationParameters

디바이스의 생성 파라미터를 취득한다.

HRESULT GetCreationParameters(
  D3DDEVICE_CREATION_PARAMETERS* pParameters
);

파라미터

pParameters
[out] 디바이스의 생성 파라미터가 기술된 D3DDEVICE_CREATION_PARAMETERS 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

이 인수가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 디바이스로 나타내지고 있는 어댑터의 번호를 취득하려면 , 돌려주어지는 D3DDEVICE_CREATION_PARAMETERS 구조체의 AdapterOrdinal 멤버를 참조한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::GetCurrentTexturePalette

현재의 텍스쳐 팔레트를 취득한다.

HRESULT GetCurrentTexturePalette(
  UINT* pPaletteNumber
);

파라미터

pPaletteNumber
[out, retval] 돌려주어지는 현재의 텍스쳐 팔레트를 나타내는 값에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetCurrentTexturePalette ,텍스쳐 팔레트


IDirect3DDevice8::GetDepthStencilSurface

Direct3DDevice 오브젝트가 소유하는 스텐실 표면을 취득한다.

HRESULT GetDepthStencilSurface(
  IDirect3DSurface8** ppZStencilSurface
);

파라미터

ppZStencilSurface
[out, retval] 돌려주어지는 스텐실 표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DSurface8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DSurface8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetRenderTarget ,IDirect3DDevice8::CopyRects


IDirect3DDevice8::GetDeviceCaps

렌더링 디바이스의 능력을 취득한다.

HRESULT GetDeviceCaps(
  D3DCAPS8* pCaps
);

파라미터

pCaps
[out] 돌려주어지는 디바이스를 기술하는 D3DCAPS8 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

GetDeviceCaps 는, 디바이스가 소프트웨어 버텍스 처리 모드로 사용되고 있을 때, 소프트웨어 버텍스 파이프라인 능력을 취득한다. 디바이스가 D3DCREATE_SOFTWAREVERTEXPROCESSING 를 지정해 생성 되고 있는 경우, 또는 디바이스가 D3DCREATE_MIXEDVERTEXPROCESSING 를 지정해 생성 되어D3DRS_SOFTWAREVERTEXPROCESSING 가 TRUE 로 설정되어 있는 경우, 소프트웨어 버텍스 처리 모드가 선택된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::GetDirect3D

디바이스를 생성 한 Microsoft® Direct3D® 오브젝트의 인스턴스에의 인터페이스를 돌려준다.

HRESULT GetDirect3D(
  IDirect3D8** ppD3D8
);

파라미터

ppD3D8
[out, retval] IDirect3D8 인터페이스에의 포인터의 주소. 디바이스를 생성 한 Direct3D 오브젝트의 인터페이스를 나타낸다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

GetDirect3D 를 호출하면 그 인터페이스에 대한 참조 카운트가 증가하므로, 인터페이스의 사용이 종료하면(자), 이 포인터를 통해 IUnknown::Release 를 호출할 필요가 있다.

주 이 메소드를 호출하면,IDirect3D8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3D8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::GetDisplayMode

디스플레이 모드의 공간 해상도, 색해상도, 및 리프레쉬 주파수를 취득한다.

HRESULT GetDisplayMode(
  D3DDISPLAYMODE* pMode
);

파라미터

pMode
[out] 어댑터의 디스플레이 모드에 대한 데이터를 저장 하는 D3DDISPLAYMODE 구조체에의 포인터. 디바이스의 디스플레이 모드와는 반대로, 디바이스로 풀 스크린 모드를 사용할 수 없는 경우는, 이 디스플레이 모드는 액티브하게 할 수 없다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::GetFrontBuffer

디바이스의 프런트 버퍼의 카피를 생성해, 어플리케이션이 제공하는 시스템 메모리 버퍼에 그 카피를 저장 한다.

HRESULT GetFrontBuffer(
  IDirect3DSurface8* pDestSurface
);

파라미터

pDestSurface
[in] 프런트 버퍼의 내용의 카피를 받는 IDirect3DSurface8 인터페이스에의 포인터. 데이터는, 디바이스의 출력의 맨 위의 행으로부터 시작해 맨 밑의 행까지, 사이에 스페이스를 사이에 두지 않는 연속한 행으로서 돌려주어진다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_DEVICELOST
D3DERR_INVALIDCALL

주의

pDestSurface 로 나타나는 버퍼에는, 프런트 버퍼의 표시를 표준의 32bpp 포맷인 D3DFMT_A8R8G8B8 로 변환한 것이 저장 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::GetGammaRamp

스왑 체인의 감마 수정 램프를 취득한다.

void GetGammaRamp(
  D3DGAMMARAMP* pRamp
);

파라미터

pRamp
[in, out] 어플리케이션이 제공하는 D3DGAMMARAMP 구조체에의 포인터. 감마 수정 램프가 저장 된다.

반환값

없음.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DSwapChain8 ,IDirect3DDevice8::SetGammaRamp


IDirect3DDevice8::GetIndices

인덱스 데이터를 취득한다.

HRESULT GetIndices(
  IDirect3DIndexBuffer8** ppIndexData,
  UINT* pBaseVertexIndex
);

파라미터

ppIndexData
[out] 돌려주어지는 인덱스 데이터를 나타내는 IDirect3DIndexBuffer8 인터페이스에의 포인터의 주소.
pBaseVertexIndex
[out] 돌려주어지는 버텍스 인덱스의 베이스값을 저장 하는 UINT 값에의 포인터. 이 값은, 버텍스 데이터를 참조하기 전에 모든 인덱스에 추가되어 버텍스 스트림의 시작 위치를 정의한다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

인덱스 리스트의 값은, 렌더링 하는 지오메트리를 생성 하면나무의 버텍스 리스트에의 인덱스부에 사용된다.

pBaseVertexIndex 파라미터에 돌려주어지는 값은, 인덱스의 베이스값을 나타내고 있다. 이 베이스값은, 버텍스 데이터 스트림을 참조하기 전에 모든 인덱스에 추가된다. 그 결과, 버텍스 데이터 스트림의 시작 위치가 설정된다. 베이스가 되는 버텍스 인덱스에 의해, 버텍스 데이터내에 배치되고 있는 대응하는 프리미티브의 장소에 근거해 인덱스를 재계산하지 않고 , 복수의 인덱스 첨부 프리미티브를 단일의 버텍스 데이터세트에 팩 할 수가 있다.

주 이 메소드를 호출하면,IDirect3DIndexBuffer8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DIndexBuffer8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetIndices


IDirect3DDevice8::GetInfo

렌더링 디바이스에 대한 정보를 취득한다.

HRESULT GetInfo(
  DWORD DevInfoID,
  VOID* pDevInfoStruct,
  DWORD DevInfoStructSize
);

파라미터

DevInfoID
[in] pDevInfoStruct 에 돌려주어지는 정보를 식별하기 위해서 사용되는 값.
pDevInfoStruct
[in, out] 호출이 성공했을 경우에, 지정한 디바이스의 정보를 받는 구조체에의 포인터.
DevInfoStructSize
[in] pDevInfoStruct 의 구조체의 사이즈 (바이트 단위).

반환값

성공했을 경우는,D3D_OK 를 돌려준다. 이 메소드는, Microsoft® DirectX® 의 리테일 빌드에서는 S_FALSE 를 돌려준다 ( 「주의」를 참조).

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드가 돌려주는 정보는, 기본이 되는 디바이스 드라이버에 관련하는 것이다. 이 메소드를 사용 하면, 드라이버로 특정의 종류의 정보 및 거기에 대응하는 구조체를 선언할 수 있게 된다. 이것들에 대해서는, 이 SDK 에서는 설명되어 있지 않다.

이 메소드는 동기 해 실행되지만, 실행 속도가 늦은 경우는, 어플리케이션의 퍼포먼스가 저하하는 일이 있다. 장면의 렌더링중 (IDirect3DDevice8::BeginScene 를 호출하고 나서 IDirect3DDevice8::EndScene 를 호출할 때까지)은, 이 메소드를 호출해서는 안 된다.

이 메소드는, 제품 개발시의 퍼포먼스 추적 및 디버그에 사용한다 (DirectX 의 디버그 버젼). 이 메소드가 성공해 S_FALSE 를 돌려주어도, 디바이스 데이터를 취득하고 있지 않을 때가 있다. 호스트 시스템에 DirectX 런타임의 리테일 버젼이 인스톨 되고 있는 경우, 이러한 일이 일어난다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::GetLight

이 디바이스로 사용하는 일련의 라이트 프로퍼티를 취득한다.

HRESULT GetLight(
  DWORD Index,
  D3DLIGHT8* pLight
);

파라미터

Index
[in] 취득하는 라이트 프로퍼티 세트의 제로로부터 시작되는 인덱스.
pLight
[out] 취득한 라이팅 파라미터 세트를 저장 하는 D3DLIGHT8 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

pLight 파라미터가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetLight ,IDirect3DDevice8::GetLightEnable ,IDirect3DDevice8::LightEnable


IDirect3DDevice8::GetLightEnable

디바이스내의 라이팅 파라미터 세트의 액티버티 스테이터스 (유효/무효)를 취득한다.

HRESULT GetLightEnable(
  DWORD Index,
  BOOL* pEnable
);

파라미터

Index
[in] 이 메소드의 대상이 되는 라이팅 파라미터 세트의 제로로부터 시작되는 인덱스.
pEnable
[out, retval] 지정한 라이팅 파라미터의 스테이터스를 저장 하는 변수에의 포인터. 호출의 뒤, 이 주소의 값이 제로 이외의 경우는, 지정한 라이팅 파라미터가 유효한 것을 나타내, 0 의 경우는 무효라는 점을 나타낸다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetLight ,IDirect3DDevice8::LightEnable ,IDirect3DDevice8::SetLight


IDirect3DDevice8::GetMaterial

디바이스에 대한 현재의 머트리얼의 프로퍼티를 취득한다.

HRESULT GetMaterial(
  D3DMATERIAL8*pMaterial
);

파라미터

pMaterial
[out] 현재 설정되어 있는 머트리얼의 프로퍼티를 저장 하는 D3DMATERIAL8 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

pMaterial 파라미터가 무효인 경우는,D3DERR_INVALIDCALL 가 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetMaterial


IDirect3DDevice8::GetPaletteEntries

팔레트 엔트리를 취득한다.

HRESULT GetPaletteEntries(
  UINT PaletteNumber,
  PALETTEENTRY* pEntries
);

파라미터

PaletteNumber
[in] 취득하는 특정의 파라미터를 식별하는 서수값.
pEntries
[in, out] 돌려주어지는 팔레트 엔트리를 나타내는 PALETTEENTRY 구조체에의 포인터. 「주의」를 참조할것.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. DirectX 8.0 에서는,PALETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는, 현재, 8 비트 팔레트화 포맷의 알파 채널이다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetCurrentTexturePalette ,IDirect3DDevice8::SetCurrentTexturePalette ,IDirect3DDevice8::SetPaletteEntries ,텍스쳐 팔레트


IDirect3DDevice8::GetPixelShader

현재 설정되어 있는 픽셀 쉐이더를 취득한다.

HRESULT GetPixelShader(
   DWORD* pHandle
);

파라미터

pHandle
[out, retval] 돌려주어지는 픽셀 쉐이더를 나타내는 픽셀 쉐이더 핸들에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetPixelShader


IDirect3DDevice8::GetPixelShaderConstant

픽셀 쉐이더 정수 배열중의 값을 취득한다.

HRESULT GetPixelShaderConstant(
   DWORD Register,
   void* pConstantData,
   DWORD ConstantCount
);

파라미터

Register
[in] 픽셀 쉐이더 정수 배열로부터의 데이터의 취득을 시작 하는 위치의 레지스터 주소.
pConstantData
[in, out] 픽셀 쉐이더 정수 배열로부터 취득한 값을 저장 하는 데이터 블록에의 포인터. 데이터 블록의 사이즈는,ConstantCount * 4 * sizeof(float)이다.
ConstantCount
[in] 픽셀 쉐이더 정수 배열로부터 취득 취득하는 정수의 수. 각 정수는, 4 개의 부동 소수점값으로부터 완성된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 픽셀 쉐이더 어셈블러의 정수 레지스터에 있는 값을 취득하기 위해서 사용한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetPixelShaderConstant


IDirect3DDevice8::GetPixelShaderFunction

픽셀 쉐이더의 기능을 취득한다.

HRESULT GetPixelShaderFunction(
   DWORD Handle,
   void* pData,
   DWORD* pSizeOfData
);

파라미터

Handle
[in] 참조하는 픽셀 쉐이더에의 핸들.
pData
[out] 호출이 성공했을 경우에 요구한 픽셀 쉐이더 핸들에 관련지을 수 있고 있는 코드를 저장 하는, 이전에 할당할 수 있고 있던 버퍼에의 포인터. 이 메소드를 호출하는 어플리케이션은, 이 버퍼의 할당과 해방에 책임을 진다.
pSizeOfData
[in, out] DWORD 값에의 포인터. pData 의 버퍼 사이즈를 바이트 단위로 가리킨다. 이 값이 0 등과 같이, 실제의 데이터 사이즈보다 작은 경우, 메소드는 이 파라미터를 필요한 버퍼 사이즈로 설정해, D3DERR_MOREDATA 를 돌려준다. 버퍼가 NULL 의 경우, 이 파라미터에는 필요한 사이즈가 지정되어D3D_OK 가 돌려주어진다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

Handle 가 픽셀 쉐이더에의 무효인 핸들인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

픽셀 쉐이더의 기능은, 블렌딩 처리를 나타내고 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetPixelShader


IDirect3DDevice8::GetRasterStatus

스왑 체인이 표시되고 있는 모니터의 라스터를 기술하는 정보를 돌려준다.

HRESULT GetRasterStatus(
  D3DRASTER_STATUS* pRasterStatus
);

파라미터

pRasterStatus
[out] 이 어댑터에 의해 구동되는 모니터 위에의 라스터의 위치나 그 외의 스테이터스에 대한 정보가 저장 되는 D3DRASTER_STATUS 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

pRasterStatus 가 무효인 경우, 또는 디바이스가 현재의 주사선으로부터의 독해를 지원 하고 있지 않는 경우는,D3DERR_INVALIDCALL 를 돌려준다. 디바이스가 주사선으로부터의 독해를 지원 하고 있을지 어떨지는,D3DCAPS8 의 Caps 멤버의 D3DCAPS_READ_SCANLINE 플래그를 체크해 조사할 수가 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

D3DRASTER_STATUS


IDirect3DDevice8::GetRenderState

디바이스에 대한 렌더링 스테이트의 값을 취득한다.

HRESULT GetRenderState(
  D3DRENDERSTATETYPE State,
  DWORD* pValue
);

파라미터

State
[in] 조사 대상의 디바이스 스테이트 변수. 이 파라미터에는,D3DRENDERSTATETYPE 열거형의 임의의 멤버를 지정할 수 있다.
pValue
[out, retval] 메소드로부터 돌아왔을 때에, 조회한 렌더링 스테이트 변수의 값을 받는 변수에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수중 한쪽이 무효인 경우는,D3DERR_INVALIDCALL 가 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetRenderState


IDirect3DDevice8::GetRenderTarget

렌더링 타겟으로서 사용되는 Microsoft® Direct3D® 표면에의 포인터를 취득한다.

HRESULT GetRenderTarget(
  IDirect3DSurface8** ppRenderTarget
);

파라미터

ppRenderTarget
[out, retval] IDirect3DSurface8 인터페이스에의 포인터의 주소. 돌려주어지는 이 디바이스의 렌더링 타겟 표면을 나타낸다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수중 한쪽이 무효인 경우는,D3DERR_INVALIDCALL 가 된다.

주 이 메소드를 호출하면,IDirect3DSurface8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DSurface8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetRenderTarget


IDirect3DDevice8::GetStreamSource

지정된 데이터 스트림에 바인드 되고 있는 버텍스 버퍼를 취득한다.

HRESULT GetStreamSource(
   UINT StreamNumber
   IDirect3DVertexBuffer8** ppStreamData,
   UINT* pStride
);

파라미터

StreamNumber
[in] 0 으로부터 스트림의 최대수 - 1 까지의 범위의 데이터 스트림을 지정한다.
ppStreamData
[in, out] 지정한 데이터 스트림에 바인드 되고 있는 버텍스 버퍼를 나타내는 IDirect3DVertexBuffer8 인터페이스에의 포인터의 주소.
pStride
[in, out] 돌려주어진 컴퍼넌트의 보폭 (바이트 단위)에의 포인터. 「주의」를 참조할것.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

스트림은 컴퍼넌트 데이터의 한결같은 배열로서 정의되고 있어 각 컴퍼넌트는, 위치, 법선, 색등의 단일 엔티티를 나타내는 1 개(살) 이상의 요소로 구성되어 있다.

주 이 메소드를 호출하면,IDirect3DVertexBuffer8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DVertexBuffer8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetStreamSource


IDirect3DDevice8::GetTexture

디바이스의 스테이지에 할당할 수 있고 있는 텍스쳐를 취득한다.

HRESULT GetTexture(
  DWORD Stage,
  IDirect3DBaseTexture8** ppTexture
);

파라미터

Stage
[in] 취득하는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 0 으로부터 시작된다. 디바이스는 최대 8 세트까지 텍스쳐를 가질 수가 있으므로,Stage 로 지정할 수 있는 최대치는 7 이다.
ppTexture
[out, retval] 돌려주어지는 텍스쳐를 나타내는 IDirect3DBaseTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DTexture8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DTexture8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetTexture ,IDirect3DDevice8::GetTextureStageState ,IDirect3DDevice8::SetTextureStageState


IDirect3DDevice8::GetTextureStageState

할당할 수 있고 있는 텍스쳐의 스테이트값을 취득한다.

HRESULT GetTextureStageState(
  DWORD Stage,
  D3DTEXTURESTAGESTATETYPE Type,
  DWORD* pValue
);

파라미터

Stage
[in] 스테이트를 취득하는 대상이 되는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 0 으로부터 시작된다. 디바이스는 최대 8 세트까지 텍스쳐를 가질 수가 있으므로,Stage 로 지정할 수 있는 최대치는 7 이다.
Type
[in] 취득하는 텍스쳐의 스테이트. 이 파라미터에는,D3DTEXTURESTAGESTATETYPE 열거형의 임의의 멤버를 지정할 수 있다.
pValue
[out, retval] 취득한 스테이트값을 저장 하는 변수에의 포인터. 취득된 값의 의미는 Type 파라미터로 정해진다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetTextureStageState ,IDirect3DDevice8::GetTexture ,IDirect3DDevice8::SetTexture


IDirect3DDevice8::GetTransform

트랜스 폼 스테이트를 기술하는 행렬을 취득한다.

HRESULT GetTransform(
  D3DTRANSFORMSTATETYPE State,
  D3DMATRIX* pMatrix
);

파라미터

State
[in] 변경 대상의 디바이스 스테이트 변수. 이 파라미터에는,D3DTRANSFORMSTATETYPE 열거형의 임의의 멤버 또는 D3DTS_WORLDMATRIX 매크로를 지정할 수 있다.
pMatrix
[out] 돌려주어지는 트랜스 폼 스테이트를 나타내는 D3DMATRIX 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수중 한쪽이 무효인 경우는,D3DERR_INVALIDCALL 가 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetTransform


IDirect3DDevice8::GetVertexShader

현재 설정되어 있는 버텍스 쉐이더를 취득한다.

HRESULT GetVertexShader(
   DWORD* pHandle
);

파라미터

pHandle
[out, retval] 돌려주어지는 버텍스 쉐이더를 나타내는 버텍스 쉐이더 핸들에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

pHandle 가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetVertexShader


IDirect3DDevice8::GetVertexShaderConstant

버텍스 쉐이더 정수 배열중의 값을 취득한다.

HRESULT GetVertexShaderConstant(
   DWORD Register,
   void* pConstantData,
   DWORD ConstantCount
);

파라미터

Register
[in] 버텍스 쉐이더 정수 배열로부터의 데이터의 취득을 시작 하는 위치의 레지스터 주소.
pConstantData
[out] 버텍스 쉐이더 정수 배열로부터 취득한 값을 저장 하는 데이터 블록에의 포인터. 데이터 블록의 사이즈는,ConstantCount * 4 * sizeof(float)이다.
ConstantCount
[in] 버텍스 쉐이더 정수 배열로부터 취득 취득하는 정수의 수. 각 정수는, 4 개의 부동 소수점값으로부터 완성된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 버텍스 쉐이더 어셈블러의 정수 레지스터에 있는 값을 취득하기 위해서 사용한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetVertexShaderConstant


IDirect3DDevice8::GetVertexShaderDeclaration

버텍스 쉐이더의 선언 토큰 배열을 취득한다.

HRESULT GetVertexShaderDeclaration(
   DWORD Handle,
   void* pData,
   DWORD* pSizeOfData
);

파라미터

Handle
[in] 버텍스 쉐이더를 참조하는 핸들.
pData
[in] 그것까지 할당할 수 있고 있던 버퍼에의 포인터. 호출이 성공했을 경우, 요구한 버텍스 쉐이더 핸들에 관련지을 수 있고 있는 선언이 저장 된다. 이 메소드를 호출하는 어플리케이션은, 이 버퍼의 할당과 해방에 책임을 진다.
pSizeOfData
[in, out] DWORD 값에의 포인터. pData 의 버퍼 사이즈를 바이트 단위로 가리킨다. 이 값이 0 등과 같이, 실제의 데이터 사이즈보다 작은 경우, 메소드는 이 파라미터를 필요한 버퍼 사이즈로 설정해, D3DERR_MOREDATA 를 돌려준다. 버퍼가 NULL 의 경우, 이 파라미터에는 필요한 사이즈가 지정되어D3D_OK 가 돌려주어진다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

Handle 가 버텍스 쉐이더에의 무효인 핸들인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

버텍스 쉐이더의 선언 토큰 배열에서는 쉐이더에의 입력이 정의되고 있어 입력 데이터 스트림중의 버텍스 요소를 쉐이더가 사용하는 방법도 포함된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetVertexShader


IDirect3DDevice8::GetVertexShaderFunction

버텍스 쉐이더의 기능을 취득한다.

HRESULT GetVertexShaderFunction(
   DWORD Handle,
   void* pData,
   DWORD* pSizeOfData
);

파라미터

Handle
[in] 버텍스 쉐이더를 참조하는 핸들.
pData
[out] 그것까지 할당할 수 있고 있던 버퍼에의 포인터. 호출이 성공했을 경우, 요구한 버텍스 쉐이더 핸들에 관련지을 수 있고 있는 코드가 저장 된다. 이 메소드를 호출하는 어플리케이션은, 이 버퍼의 할당과 해방에 책임을 진다.
pSizeOfData
[in, out] DWORD 값에의 포인터. pData 의 버퍼 사이즈를 바이트 단위로 가리킨다. 이 값이 0 등과 같이, 실제의 데이터 사이즈보다 작은 경우, 메소드는 이 파라미터를 필요한 버퍼 사이즈로 설정해, D3DERR_MOREDATA 를 돌려준다. 버퍼가 NULL 의 경우, 이 파라미터에는 필요한 사이즈가 지정되어D3D_OK 가 돌려주어진다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

Handle 가 버텍스 쉐이더에의 무효인 핸들인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

버텍스 쉐이더의 기능에서는, 각 버텍스에 적용되는 조작이 정의되고 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetVertexShader


IDirect3DDevice8::GetViewport

디바이스에 현재 설정되어 있는 뷰 포토 파라미터를 취득한다.

HRESULT GetViewport(
  D3DVIEWPORT8* pViewport
);

파라미터

pViewport
[out] 돌려주어지는 뷰 포토 파라미터를 나타내는 D3DVIEWPORT8 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

pViewport 파라미터가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetViewport


IDirect3DDevice8::LightEnable

디바이스내의 라이팅 파라미터 세트를 유효 또는 무효로 한다.

HRESULT LightEnable(
  DWORD LightIndex,
  BOOL bEnable
);

파라미터

LightIndex
[in] 이 메소드의 대상이 되는 라이팅 파라미터 세트의 제로로부터 시작되는 인덱스.
bEnable
[in] 라이팅 파라미터 세트가 유효 또는 무효의 머지않아인지를 나타내는 값. 이 파라미터에 TRUE 를 설정 하면, 지정된 인덱스의 파라미터의 라이트가 유효하게 되어, FALSE 를 설정 하면 무효가 된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

디바이스내에서 할당할 수 있고 있는 라이트 프로퍼티 세트의 범위외의 값을 LightIndex 로 설정 하면,LightEnable 메소드는 D3DLIGHT8 구조체로 나타내지는 광원을 이하의 프로퍼티로 생성 해, 유효한 스테이트를 bEnable 로 지정된 값으로 설정한다.

멤버 | 디폴트
Type | D3DLIGHT_DIRECTIONAL
Diffuse | (R:1, G:1, B:1, A:0)
Specular | (R:0, G:0, B:0, A:0)
Ambient | (R:0, G:0, B:0, A:0)
Position | (0, 0, 0)
Direction | (0, 0, 1)
Range | 0
Falloff | 0
Attenuation0 | 0
Attenuation1 | 0
Attenuation2 | 0
Theta | 0
Phi | 0

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetLight ,IDirect3DDevice8::GetLightEnable ,IDirect3DDevice8::SetLight


IDirect3DDevice8::MultiplyTransform

디바이스의 월드 행렬, 뷰 행렬, 또는 투영 행렬에, 지정된 행렬을 곱셈한다.

HRESULT MultiplyTransform(
  D3DTRANSFORMSTATETYPE State,
  CONST D3DMATRIX* pMatrix
);

파라미터

State
[in] 변경하는 디바이스 행렬을 지정하는 D3DTRANSFORMSTATETYPE 열거형의 멤버, 또는 D3DTS_WORLDMATRIX 매크로. 가장 일반적인 설정은 D3DTS_WORLDMATRIX(0)로, 월드 행렬을 변경하지만, 필요하면, 뷰 행렬이나 투영 행렬을 변경하도록(듯이) 지정할 수도 있다.
pMatrix
[in] 현재의 트랜스 폼을 변경하는 D3DMATRIX 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수중 한쪽이 무효인 경우는,D3DERR_INVALIDCALL 가 된다.

주의

곱셈의 순서는,State × pMatrix 이다

어플리케이션이, 트랜스 폼의 계층 구조를 사용해 동작하기 위해서,MultiplyTransform 메소드를 사용하는 일도 생각할 수 있다. 예를 들어, 팔을 나타내는 지오메트리와 트랜스 폼은, 이하의 계층에서 구성하는 일도 있다.

shoulder_transformation
    upper_arm geometry
    elbow transformation
        lower_arm geometry
        wrist transformation
            hand geometry

어플리케이션에서는, 이 계층을 렌더링 하기 위해서 이하의 일련의 호출을 실시할 수가 있다. 이 코드에서는 일부의 파라미터만 가리킨다.

IDirect3DDevice8::SetTransform(D3DTS_WORLDMATRIX(0),
    shoulder_transform)
IDirect3DDevice8::DrawPrimitive(upper_arm)
IDirect3DDevice8::MultiplyTransform(D3DTS_WORLDMATRIX(0),
    elbow_transform)
IDirect3DDevice8::DrawPrimitive(lower_arm)
IDirect3DDevice8::MultiplyTransform(D3DTS_WORLDMATRIX(0),
    wrist_transform)
IDirect3DDevice8::DrawPrimitive(hand)

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DrawPrimitive ,IDirect3DDevice8::SetTransform ,D3DTS_WORLD ,D3DTS_WORLDn ,D3DTS_WORLDMATRIX


IDirect3DDevice8::Present

디바이스가 소유하는 백 버퍼의 순서 중(안)에서 다음의 컨텐츠를 제시한다.

HRESULT Present(
  CONST RECT* pSourceRect,
  CONST RECT* pDestRect,
  HWND hDestWindowOverride,
  CONST RGNDATA* pDirtyRegion
);

파라미터

pSourceRect
[in] 스왑 체인이 D3DSWAPEFFECT_COPY 또는 D3DSWAPEFFECT_COPY_VSYNC 로 생성 되고 있는 경우를 제외해, NULL 를 지정해야 하는 값에의 포인터. pSourceRect 는, 전송원직사각형을 포함한 RECT 구조체에의 포인터이다. NULL 의 경우는, 전송원표면 전체가 표시된다. 직사각형이 전송원표면을 넘었을 경우, 직사각형은 전송원표면에 클리핑 된다.
pDestRect
[in] 스왑 체인이 D3DSWAPEFFECT_COPY 또는 D3DSWAPEFFECT_COPY_VSYNC 로 생성되어 있지 않은 한, NULL 를 지정해야 하는 값에의 포인터. PDestRect 는 윈도우의 클라이언트 좌표에 전송처 직사각형을 포함한 RECT 구조체에의 포인터이다. NULL 의 경우는, 클라이언트 영역 전체가 저장 된다. 직사각형이 전송처의 클라이언트 영역을 넘었을 경우, 직사각형은 전송처의 클라이언트 영역에 클리핑 된다.
hDestWindowOverride
[in] 클라이언트 영역이 이 프레젠테이션의 대상으로 해 다루어지는 전송처 윈도우에의 포인터. 이 파라미터가 NULL 의 경우는,D3DPRESENT_PARAMETERS 의 hWndDeviceWindow 멤버가 사용된다.
pDirtyRegion
[in] 이 파라미터는 미사용인 모아 두어 NULL 로 설정할 필요가 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_DEVICELOST

주의

필요에 따라서, 전송원직사각형내의 픽셀을 타겟 윈도우의 클라이언트 영역의 전송처 직사각형에 전송 하기 위해서 확대 처리가 적용된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::Reset


IDirect3DDevice8::ProcessVertices

버텍스 쉐이더로 정의되고 있는 버텍스 처리를 일련의 입력 데이터 스트림에 적용해, 인터리브 된 버텍스 데이터의 단일 스트림을 생성해 전송처 버텍스 버퍼에 저장 한다.

HRESULT ProcessVertices(
  UINT SrcStartIndex,
  UINT DestIndex,
  UINT VertexCount,
  IDirect3DVertexBuffer8* pDestBuffer,
  DWORD Flags
);

파라미터

SrcStartIndex
[in] 로드하는 최초의 버텍스의 인덱스.
DestIndex
[in] 결과를 저장 하는 전송처 버텍스 버퍼내의 최초의 버텍스의 인덱스.
VertexCount
[in] 처리하는 버텍스의 수.
pDestBuffer
[in] IDirect3DVertexBuffer8 인터페이스에의 포인터. 인터리브 된 버텍스 데이터의 스트림을 나타내는 전송처 버텍스 버퍼이다.
Flags
[in] 처리 옵션. 디폴트 처리에 대해서는 이 파라미터를 0 으로 설정한다. D3DPV_DONOTCOPYDATA 로 설정 하면, 버텍스의 처리에 무관계한 버텍스 데이터를 카피처 버퍼에 카피하는 것을 막을 수가 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

전송처 버텍스 버퍼 pDestBuffer 는, 제로 이외의 FVF 파라미터를 지정해 생성 해야 한다. IDirect3DDevice8::CreateVertexBuffer 메소드의 호출에 대해 지정하는 FVF 코드는, 전송처 버텍스 버퍼에 저장 되는 버텍스 요소를 지정하고 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

디바이스의 종류와 버텍스 처리의 요건


IDirect3DDevice8::Reset

스왑 체인의 타입, 사이즈, 및 포맷을 리셋 한다.

HRESULT Reset(
  D3DPRESENT_PARAMETERS* pPresentationParameters
);

파라미터

pPresentationParameters
[in] 새로운 프레젠테이션 파라미터를 기술하는 D3DPRESENT_PARAMETERS 구조체에의 포인터. 이 값은 NULL 로 할 수 없다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

Reset 의 호출이 실패 하면, 디바이스는 "소실" 상태 (IDirect3DDevice::TestCooperativeLevel 의 호출로부터의 반환값 D3DERR_DEVICELOST 가 가리킨다)가 된다. 다만, 디바이스가 이미 "비리셋" 상태 (IDirect3DDevice8::TestCooperativeLevel 의 호출로부터의 반환값 D3DERR_DEVICENOTRESET 가 가리킨다)의 경우는 제외하다. 소실한 디바이스의 문맥에 있어서의 Reset 의 사용법의 상세한 것에 대하여는, 「IDirect3DDevice8::TestCooperativeLevel 」 및 「소실한 디바이스」를 참조할것.

리셋을 호출하면, 모든 텍스쳐 메모리 표면이 없어져, 관리하의 텍스쳐가 비디오 메모리로부터 플래시 되어, 모든 스테이트 정보가 클리어 된다. 디바이스에 대해서 Reset 메소드를 호출하기 전에, 어플리케이션에서는 명시적인 렌더링 타겟, 스텐실 표면, 추가 스왑 체인, 및 디바이스에 관련지을 수 있고 있는 D3DPOOL_DEFAULT 리소스를 해방할 필요가 있다.

스왑 체인의 타입에는, 풀 스크린과 윈도우가 있다. 새로운 스왑 체인이 풀 스크린의 경우, 어댑터는 새로운 사이즈에 맞은 디스플레이 모드로 설정된다.

DirectX 8.0 어플리케이션에서는, 이 호출중 (예를 들어, 이 호출이 돌아가기 전)은 어플리케이션에 메세지가 송신되는 것을 기대할 수 있다. 어플리케이션은, 이 때에 Direct3D 를 호출하지 않기 위한 경고를 받아들인다. 또,Reset 가 실패했을 경우, 호출할 수가 있는 유효한 메소드는 Reset,IDirect3DDevice8::TestCooperativeLevel , 및 다양한 Release 멤버 함수 뿐이다. 그 외의 메소드를 호출하면, 예외가 되는 경우가 있다.

리셋 하는 디바이스를 생성 한 thread와는 다른 thread로 Reset 를 호출하면, 이 호출은 실패한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

D3DSWAPEFFECT ,D3DPRESENT_PARAMETERS ,IDirect3DDevice8::Present


IDirect3DDevice8::ResourceManagerDiscardBytes

리소스 매니저를 호출해, 메모리를 해방한다.

HRESULT ResourceManagerDiscardBytes(
  DWORD Bytes
);

파라미터

Bytes
[in] 파기의 대상이 되는 바이트수. 0 을 지정 하면, 리소스 매니저는 전바이트를 파기한다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

리소스 매니저는, 목표의 바이트수에 이를 때까지, 메모리 할당의 해방을 실시한다. 리소스 매니저는, 최저 사용 빈도 방식 (LRU)의 우선 순위 결정 기법에 따른다.

해방되는 바이트수가 연속적이다라고는 보증되지 않는다. 따라서, 이 메소드를 호출한 후에,Bytes 로 지정되는 바이트수의 리소스를 생성 할 수 없는 경우도 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::SetClipPlane

디바이스의 유저 정의 클립면의 계수를 설정한다.

HRESULT SetClipPlane(
  DWORD Index,
  CONST float* pPlane
);

파라미터

Index
[in] 평면 방정식의 계수를 설정하는 클립면의 인덱스.
pPlane
[in] 설정하는 일반 평면 방정식 형식의 클립면계수를 나타내는 값의, 4 요소로 구성되는 배열의 주소에의 포인터. 「주의」를 참조할것.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다. 이 에러는,Index 의 값이 디바이스로 지원 되는 최대 클립면인덱스를 넘고 있는지,pPlane 의 배열이 4 개의 부동 소수점값을 저장 할 만큼 크지 않은 것을 나타낸다.

주의

이 메소드로 설정하는 계수는, 일반 평면 방정식의 형태를 취한다. pPlane 의 배열의 값이 배열내에서의 순서에 A, B, C, 및 D 와 라벨 붙이고 되고 있는 경우, 이러한 값은 일반 평면 방정식이 Ax + By + Cz + Dw = 0 이 되도록(듯이) 적용된다. Ax + By + Cz + Dw >= 0 인 경우, 동차 좌표 (x, y, z, w)의 포인트는 평면에서 잘라내진 반의 공간에 표시된다. 클립 얼굴 또는 배후에 존재하는 포인트는 장면으로부터 클리핑 된다.

고정 기능 파이프라인이 사용되는 경우, 평면 방정식은 월드 공간에 있으면(자) 가정된다. 프로그램 가능한 파이프라인이 사용되는 경우, 평면 방정식은 클립 공간 (출력 버텍스와 같은 공간)에 있으면(자) 가정된다.

이 메소드는, 설정된 클립면의 평면 방정식을 유효하게는 하지 않는다. 클립면을 유효하게 하려면 ,D3DRS_CLIPPLANEENABLE 렌더링 스테이트에 적용하는 DWORD 값의 대응하는 비트를 설정한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetClipPlane


IDirect3DDevice8::SetClipStatus

클립 스테이터스를 설정한다.

HRESULT SetClipStatus(
  CONST D3DCLIPSTATUS8* pClipStatus
);

파라미터

pClipStatus
[in] 설정하는 클립 스테이터스를 기술하는 D3DCLIPSTATUS8 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수중 한쪽이 무효인 경우는,D3DERR_INVALIDCALL 가 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetClipStatus


IDirect3DDevice8::SetCurrentTexturePalette

현재의 텍스쳐 팔레트를 설정한다.

HRESULT SetCurrentTexturePalette(
  UINT PaletteNumber
);

파라미터

PaletteNumber
[in] 현재의 텍스쳐 팔레트로서 설정하는 텍스쳐 팔레트를 지정하는 값.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

단일의 논리 팔레트를 디바이스에 관련지을 수 있어 모든 텍스쳐 스테이지에서 공유된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetCurrentTexturePalette ,텍스쳐 팔레트


IDirect3DDevice8::SetCursorPosition

커서의 위치와 갱신 옵션을 설정한다.

void SetCursorPosition(
  UINT XScreenSpace,
  UINT YScreenSpace,
  DWORD Flags
);

파라미터

XScreenSpace
[in] 스크린 공간 좌표로 나타낸 커서의 새로운 x 위치. 「주의」를 참조할것.
YScreenSpace
[in] 스크린 공간 좌표로 나타낸 커서의 새로운 y 위치. 「주의」를 참조할것.
Flags
[in] 커서의 갱신 옵션을 지정한다. 현재, 정의되고 있는 플래그는 1 개 뿐이다.
D3DCURSOR_IMMEDIATE_UPDATE
refresh rate로 커서를 갱신한다.

이 플래그를 지정했을 경우, 시스템은 최저 디스플레이의 refresh rate의 반의 속도로 커서를 갱신하는 것을 보증하지만, 디스플레이의 refresh rate보다 빈번하게 갱신할 것은 없다. 이 플래그를 지정하지 않는 경우, 이 메소드는 커서의 갱신을 다음의 IDirect3DDevice8::Present 의 호출까지 지연 시킨다. 이 디폴트의 동작은, 보통, 플래그를 설정했을 경우보다 퍼포먼스가 향상한다. 다만,Present 의 호출의 빈도가 높고, 유저가 커서의 움직임에 큰 지연을 느끼는 것 같으면, 어플리케이션으로 이 플래그를 설정할 필요가 있다.

반환값

없음.

주의

풀 스크린 모드로 실행하고 있는 경우, 스크린 공간 좌표는 백 버퍼 좌표에 변환되어, 현재의 디스플레이 모드에 맞추어 적절히 스케일링 된다. 윈도우 모드로 실행하고 있는 경우는, 스크린 공간 좌표는 데스크탑 좌표에 변환된다. 커서 이미지는, 지정한 위치로부터 IDirect3DDevice8::SetCursorProperties 메소드로 지정되고 있는 핫 스포트 오프셋(offset)의 값을 당긴 위치에 드로잉(Drawing) 된다.

커서가 IDirect3DDevice8::ShowCursor 로 숨겨지고 있는 경우, 커서는 드로잉(Drawing) 되지 않는다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetCursorProperties ,IDirect3DDevice8::ShowCursor


IDirect3DDevice8::SetCursorProperties

커서의 프로퍼티를 설정한다.

HRESULT SetCursorProperties(
  UINT XHotSpot,
  UINT YHotSpot,
  IDirect3DSurface8* pCursorBitmap
);

파라미터

XHotSpot
[in] 커서의 맨 왼쪽 위쪽을 기준으로서 커서의 내부로 향하는 X 좌표 오프셋(offset) (픽셀 단위). 커서의 중심이라고 보여진다. 커서가 새로운 위치로 지정되었을 경우, 이미지는, 이 새로운 위치로부터의 오프셋(offset)에 그려진다. 이 새로운 위치는, 그 위치로부터 핫 스포트의 좌표를 당기는 것에 의해 결정된 위치이다.
YHotSpot
[in] 커서의 맨 왼쪽 위쪽을 기준으로서 커서의 내부로 향하는 Y 좌표 오프셋(offset) (픽셀 단위). 커서의 중심이라고 보여진다. 커서가 새로운 위치로 지정되었을 경우, 이미지는, 이 새로운 위치로부터의 오프셋(offset)에 그려진다. 이 새로운 위치는, 그 위치로부터 핫 스포트의 좌표를 당기는 것에 의해 결정된 위치이다.
pCursorBitmap
[in] IDirect3DSurface8 인터페이스에의 포인터. 이 파라미터는, 8888 ARGB 표면 (포맷은 D3DFORMAT_A8R8G8B8)을 포인트 하고 있지 않으면 안 된다. 이 표면의 컨텐츠는, 커서의 표시에 사용되는 내부 버퍼에 카피되어, 동시에 포맷 변환을 하는 경우가 있다. 이 표면의 넓이는 디스플레이 모드의 넓이보다 작지 않으면 안되어, 각방향과도 2 의 거듭제곱이 아니면 안된다. 다만, 양방향이 같은 크기가 아니어도 상관없다. 알파 채널은, 0.0 또는 1.0 이 아니면 안된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

Microsoft® Direct3D® 의 커서 함수에서는, 하드웨어에 응해, GDI 커서 또는 소프트웨어 에뮬레이션의 어느쪽이든을 사용한다. 유저는 보통, WM_SETCURSOR 메세지에 응한다. 예를 들어, 유저는 메세지 핸들러를 다음과 같이 기술할 수 있다.

case WM_SETCURSOR:
    // 윈도우 커서를 오프로 한다.
    SetCursor( NULL );
    m_pd3dDevice->ShowCursor( TRUE );
    return TRUE; // Windows 가 커서를 윈도우 클래스 커서로 설정하지 않게 한다.
break;

또, 커서를 변경하는 경우는, 유저는 IDirect3DDevice8::SetCursorProperties 메소드를 호출할 수가 있다. 상세한 것에 대하여는, Microsoft DirectX® Graphics C/C++ 샘플의 샘플 코드를 참조할것.

어플리케이션에서는,D3DCAPS8 구조체의 적절한 멤버를 조사하는 것으로, 커서로 이용 가능한 하드웨어 지원을 확인할 수 있다. 일반적으로, 하드웨어가 지원 하는 것은 32 × 32 의 커서 뿐이다. 게다가 윈도우 모드에서는, 시스템을 지원 할 수 있는 것도 32 × 32 의 커서 뿐이다. 그 경우에서도 SetCursorProperties 는 성공하지만, 커서는 이 사이즈에 축소되어, 핫 스포트는 적절히 스케일링 될 가능성이 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetCursorPosition ,IDirect3DDevice8::ShowCursor ,D3DCAPS8


IDirect3DDevice8::SetGammaRamp

비명시적인 스왑 체인의 감마 수정 램프를 설정한다.

void SetGammaRamp(
  DWORD Flags,
  CONST D3DGAMMARAMP* pRamp
);

파라미터

Flags
[in] 수정을 적용할지 어떨지를 지정한다. 감마 수정을 실시하면 한층 더 일관성이 있는 표시를 얻을 수 있지만, 처리 오버헤드가 발생할 가능성이 있으므로, 빈번하게 사용해서는 안된다. 전화면을 붉고 플래시 시키는 것 같은 단시간의 이펙트는 조정하지 않는 것이 좋지만, 장시간의 감마 변화는 조정할 필요가 있다. 다음의 플래그의 어느쪽이든을 설정할 수 있다.
D3DSGR_CALIBRATE
감마 구경 측정기가 인스톨 되고 있는 경우는, 시스템 및 모니터의 응답 커브에 맞추어, 디바이스에 송신되기 전에 램프가 조정된다.

구경 측정기가 인스톨되어 있지 않은 경우는, 램프는 디바이스에 직접 건네받는다.

D3DSGR_NO_CALIBRATION
감마 수정을 적용하지 않는다. 제공되고 있는 감마 테이블이, 디바이스에 직접 전송 된다.
pRamp
[in] D3DGAMMARAMP 구조체에의 포인터. 비명시적인 스왑 체인으로 설정하는 감마 수정 램프를 나타낸다.

반환값

없음.

주의

Microsoft® Direct3D® for Microsoft DirectX 8.0® 는 디바이스의 프로퍼티로서 1 개의 스왑 체인을 가지고 있기 (위해)때문에, 각 디바이스에 대해서, 항상 적어도 1 개의 스왑 체인 (비명시적인 스왑 체인)이 존재한다.

감마 램프는 스왑 체인의 프로퍼티이므로, 스왑 체인을 윈도우화할 때는, 감마 램프를 적용할 수 있다.

감마 램프는 즉시 유효하게 된다. VSYNC 의 대기는 발생하지 않는다.

디바이스가 스왑 체인의 현재의 프레젠테이션 모드 (풀 스크린 또는 윈도우)에 대해 감마 램프를 지원 하고 있지 않는 경우에서도, 에러가 돌아갈 것은 없다. 어플리케이션에서는,D3DCAPS8 구조체의 Caps2 멤버의 D3DCAPS2_FULLSCREENGAMMA 능력 비트 및 D3DCAPS2_CANCALIBRATEGAMMA 능력 비트를 조사해, 디바이스의 능력 및 구경 측정기가 인스톨 되고 있는지 어떤지를 판단할 수 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DSwapChain8 ,IDirect3DDevice8::GetGammaRamp


IDirect3DDevice8::SetIndices

인덱스 데이터를 설정한다.

HRESULT SetIndices(
  IDirect3DIndexBuffer8* pIndexData
  UINT BaseVertexIndex
);

파라미터

pIndexData
[in] 설정하는 인덱스 데이터를 나타내는 IDirect3DIndexBuffer8 인터페이스에의 포인터.
BaseVertexIndex
[in] 버텍스 인덱스의 베이스값. 이 값은, 버텍스 데이터를 참조하기 전에 모든 인덱스에 추가되어 버텍스 스트림의 시작 위치를 정의한다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

SetIndices 메소드는, 인덱스 버퍼에 현재의 인덱스 배열을 설정한다. 단일의 인덱스 세트를 사용해, 모든 스트림에 인덱스를 붙일 수 있다.

BaseVertexIndex 파라미터에서는, 인덱스에 대한 베이스값을 지정한다. 이 베이스값은, 버텍스 데이터 스트림을 참조하기 전에 모든 인덱스에 추가된다. 그 결과, 버텍스 데이터 스트림의 시작 위치가 설정된다. 베이스가 되는 버텍스 인덱스에 의해, 버텍스 데이터내에 배치되고 있는 대응하는 프리미티브의 장소에 근거해 인덱스를 재계산하지 않고 , 복수의 인덱스 첨부 프리미티브를 단일의 버텍스 데이터세트에 팩 할 수가 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetIndices


IDirect3DDevice8::SetLight

이 디바이스에 일련의 라이트 프로퍼티를 할당한다.

HRESULT SetLight(
  DWORD Index,
  CONST D3DLIGHT8* pLight
);

파라미터

Index
[in] 설정하는 라이트 프로퍼티 세트의 제로로부터 시작되는 인덱스. 인덱스에 라이트 프로퍼티 세트가 존재하는 경우는,pLight 로 지정한 새로운 프로퍼티로 덧쓰기된다.
pLight
[in] 설정하는 라이팅 파라미터가 저장 되고 있는 D3DLIGHT8 구조체에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetLight ,IDirect3DDevice8::GetLightEnable ,IDirect3DDevice8::LightEnable


IDirect3DDevice8::SetMaterial

디바이스에 머트리얼 프로퍼티를 설정한다.

HRESULT SetMaterial(
   CONST D3DMATERIAL8* pMaterial
);

파라미터

pMaterial
[in] 설정하는 머트리얼 프로퍼티가 기술되고 있는 D3DMATERIAL8 구조체에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

pMaterial 파라미터가 무효인 경우는,D3DERR_INVALIDCALL 가 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetMaterial


IDirect3DDevice8::SetPaletteEntries

팔레트 엔트리를 설정한다.

HRESULT SetPaletteEntries(
  UINT PaletteNumber,
  CONST PALETTEENTRY* pEntries
);

파라미터

PaletteNumber
[in] 실행하는 처리의 대상이 되는 특정의 파라미터를 식별하는 서수값.
pEntries
[in] 설정하는 팔레트 엔트리를 나타내는 PALETTEENTRY 구조체에의 포인터. pEntries 가 포인트 하는 PALETTEENTRY 구조체의 수는 256 이라고 가정되고 있다. 「주의」를 참조할것.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

단일의 논리 팔레트를 디바이스에 관련지을 수 있어 모든 텍스쳐 스테이지에서 공유된다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 에서는,PALETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는, 현재, 8 비트 팔레트화 포맷의 알파 채널이다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetCurrentTexturePalette ,IDirect3DDevice8::GetPaletteEntries ,IDirect3DDevice8::SetCurrentTexturePalette ,텍스쳐 팔레트


IDirect3DDevice8::SetPixelShader

이전 생성 한 픽셀 쉐이더를 현재의 픽셀 쉐이더로서 설정한다.

HRESULT SetPixelShader(
  DWORD Handle
);

파라미터

Handle
[in] 설정하는 픽셀 쉐이더를 지정하는 픽셀 쉐이더에의 핸들. 이 파라미터의 값으로서IDirect3DDevice8::CreatePixelShader 로부터 돌아가는 핸들을 사용할 수 있다.

핸들이 NULL 의 경우는, 종래의 픽셀 파이프라인이 사용된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetPixelShader


IDirect3DDevice8::SetPixelShaderConstant

픽셀 정수 배열에 값을 설정한다.

HRESULT SetPixelShaderConstant(
  DWORD Register,
  CONST void* pConstantData,
  DWORD ConstantCount
);

파라미터

Register
[in] 픽셀 정수 배열에의 데이터의 로드를 시작 하는 레지스터 주소.
pConstantData
[in] 픽셀 정수 배열에 로드하는 값이 저장 되고 있는 데이터 블록에의 포인터. 데이터 블록의 사이즈는,ConstantCount * 4 * sizeof(float)이다.
ConstantCount
[in] 픽셀 정수 배열에 로드하는 정수의 수. 각 정수는, 4 개의 부동 소수점값으로부터 완성된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 픽셀 쉐이더 어셈블러의 정수 레지스터에 값을 로드하기 위해서(때문에) 사용한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetPixelShaderConstant


IDirect3DDevice8::SetRenderState

단일 디바이스의 렌더링 스테이트 파라미터를 설정한다.

HRESULT SetRenderState(
  D3DRENDERSTATETYPE State,
  DWORD Value
);

파라미터

State
[in] 변경 대상의 디바이스 스테이트 변수. 이 파라미터에는,D3DRENDERSTATETYPE 열거형의 임의의 멤버를 지정할 수 있다.
Value
[in] 디바이스의 렌더링 스테이트로 설정하는 새로운 값. 이 파라미터의 의미는,State 의 지정값에 의존한다. 예를 들어,State 가 D3DRS_SHADEMODE 의 경우, 제 2 파라미터는 D3DSHADEMODE 열거형의 멤버의 어느 쪽인가에 된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

인수의 1 개가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetRenderState ,IDirect3DDevice8::SetTransform


IDirect3DDevice8::SetRenderTarget

디바이스에 새로운 칼라 버퍼와 깊이 버퍼의 한편 또는 양쪽 모두를 설정한다.

HRESULT SetRenderTarget(
  IDirect3DSurface8* pRenderTarget,
  IDirect3DSurface8* pNewZStencil
);

파라미터

pRenderTarget
[in] 새로운 칼라 버퍼에의 포인터. NULL 의 경우는, 기존의 칼라 버퍼가 그대로 사용된다. 이 파라미터가 NULL 가 아닌 경우는, 새로운 렌더링 타겟의 참조 카운트가 인크리먼트(increment) 된다. 디바이스에는, 항상, 칼라 버퍼를 관련지을 수 있지 않으면 안 된다.

새로운 렌더링 타겟의 표면에는, 적어도 D3DUSAGE_RENDERTARGET 가 지정되어 있지 않으면 안 된다.

pNewZStencil
[in] 새로운 스텐실 버퍼에의 포인터. 기존의 스텐실 버퍼가 있는 경우는, 그 버퍼가 해방된다. 이 파라미터가 NULL 가 아닌 경우는, 새로운 스텐실 버퍼 표면의 참조 카운트가 인크리먼트(increment) 된다. IDirect3DDevice8::GetDepthStencilSurface 의 ppZStencilSurface 파라미터를 건네주면(자), 깊이 버퍼를 변경하지 않고 렌더링 타겟을 변경할 수 있다.

새로운 스텐실 표면에는, 적어도 D3DUSAGE_DEPTHSTENCIL 와 D3DPOOL_DEFAULT 가 지정되어 있지 않으면 안 된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

pRenderTarget 또는 pNewZStencil 가 NULL 이외로 무효인 값의 경우, 혹은 새로운 깊이 버퍼가 새로운 칼라 버퍼 또는 계속해 사용되는 칼라 버퍼보다 작은 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드를 사용해 칼라 버퍼와 스텐실 표면을 같은 디바이스에 관련짓는 것을, 양자를 페어로 한다고 한다.

디바이스는,SetRenderTarget 에 NULL 이외의 표면이 건네받을 때마다,AddRef 를 호출한다. 그 후, 디바이스는 이전으로 설정되어 있는 칼라 버퍼에 대해서 Release 를 호출한다.

SetRenderTarget 를 호출해 이전의 스텐실 표면과 디바이스의 관련을 절단 한 다음에도, 전의 스텐실 표면의 컨텐츠는 보관 유지된다. 그 표면을 디바이스와 다시 관련지으면(자), 새로운 스텐실 표면과 페어로 되고 있는 칼라 버퍼의 사이즈와 포맷이, 스텐실 표면과 마지막에 페어가 되어 있던 칼라 버퍼와 같으면, 표면의 컨텐츠는 변경되지 않는다.

이 메소드를 호출하면, 디바이스의 현재의 뷰 포토는, 현재의 렌더링 타겟의 사이즈에 리셋 된다. 이 처리는, Z 버퍼만이 변경될지 어떨지에 관계없이 행해진다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CreateDepthStencilSurface ,IDirect3DDevice8::GetDepthStencilSurface


IDirect3DDevice8::SetStreamSource

버텍스 버퍼를 디바이스의 데이터 스트림에 바인드 한다.

HRESULT SetStreamSource(
  UINT StreamNumber,
  IDirect3DVertexBuffer8* pStreamData,
  UINT Stride
);

파라미터

StreamNumber
[in] 0 으로부터 스트림의 최대수 - 1 까지의 범위의 데이터 스트림을 지정한다.
pStreamData
[in] IDirect3DVertexBuffer8 인터페이스에의 포인터. 지정한 데이터 스트림에 바인드 하는 버텍스 버퍼를 나타낸다.
Stride
[in] 컴퍼넌트의 보폭 (바이트 단위). 「주의」를 참조할것.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 할당할 수 있는 스트림의 참조 카운트를 인크리먼트(increment) 한다. 텍스쳐가 불필요하게 되었을 경우는, 해당하는 스테이지의 텍스쳐를 NULL 로 설정해야 한다. 이것을 실시하지 않았던 경우, 표면은 해방되지 않고, 메모리 누수가 발생한다.

유연한 버텍스 포맷 (FVF) 버텍스 쉐이더를 사용하는 경우,SetStreamSource 의 스트림 버텍스 보폭은, FVF 로부터 계산된 버텍스 사이즈와 일치하고 있지 않으면 안 된다. 이 선언을 사용하는 경우,SetStreamSource 의 스트림 버텍스 보폭은, 선언으로부터 계산된 스트림 사이즈 이상이 아니면 안된다.

SetStreamSource 메소드는, 버텍스 버퍼를 디바이스의 데이터 스트림에 바인드 한다. 상세한 것에 대하여는, 「스트림 소스의 설정」을 참조할것.

텍스쳐가 필요없게 되었을 때, 적절한 스테이지에서 그 텍스쳐를 NULL 로 설정하는 것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::DrawIndexedPrimitive ,IDirect3DDevice8::DrawIndexedPrimitiveUP ,IDirect3DDevice8::DrawPrimitive ,IDirect3DDevice8::DrawPrimitiveUP ,IDirect3DDevice8::GetStreamSource


IDirect3DDevice8::SetTexture

텍스쳐를 디바이스의 스테이지에 할당한다.

HRESULT SetTexture(
  DWORD Stage,
  IDirect3DBaseTexture8* pTexture
);

파라미터

Stage
[in] 텍스쳐를 설정하는 스테이지 식별자. 스테이지 식별자는 0 으로부터 시작된다. 디바이스는 최대 8 세트까지 텍스쳐를 가질 수가 있으므로,Stage 로 지정할 수 있는 최대치는 7 이다.
pTexture
[in] 설정하는 텍스쳐를 나타내는 IDirect3DBaseTexture8 인터페이스에의 포인터. 밉맵 텍스쳐나 큐브 텍스쳐등과 같이 복잡한 텍스쳐의 경우, 이 파라미터는 톱 레벨의 표면을 포인트 하고 있지 않으면 안 된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 할당할 수 있고 있는 텍스쳐 표면의 참조 카운트를 인크리먼트(increment) 해, 이전에 선택된 텍스쳐가 있는 경우에는 그 참조 카운트를 감소 한다. 텍스쳐가 불필요하게 되었을 경우는, 해당하는 스테이지의 텍스쳐를 NULL 로 설정해야 한다. 이 처리를 실시하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetTexture ,IDirect3DDevice8::GetTextureStageState ,IDirect3DDevice8::SetTextureStageState


IDirect3DDevice8::SetTextureStageState

현재 할당할 수 있고 있는 텍스쳐에 스테이트값을 설정한다.

HRESULT SetTextureStageState(
  DWORD Stage,
  D3DTEXTURESTAGESTATETYPE Type,
  DWORD Value
);

파라미터

Stage
[in] 스테이트값을 설정하는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 0 으로부터 시작된다. 디바이스는 최대 8 세트까지 텍스쳐를 가질 수가 있으므로,Stage 로 지정할 수 있는 최대치는 7 이다.
Type
[in] 설정하는 텍스쳐의 스테이트. 이 파라미터에는,D3DTEXTURESTAGESTATETYPE 열거형의 임의의 멤버를 지정할 수 있다.
Value
[in] 설정하는 스테이트값. 이 값의 의미는 Type 파라미터로 정해진다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetTextureStageState ,IDirect3DDevice8::GetTexture ,IDirect3DDevice8::SetTexture


IDirect3DDevice8::SetTransform

단일 디바이스의 트랜스 폼 관련 스테이트를 설정한다.

HRESULT SetTransform(
  D3DTRANSFORMSTATETYPE State,
  CONST D3DMATRIX* pMatrix
);

파라미터

State
[in] 변경 대상의 디바이스 스테이트 변수. 이 파라미터에는,D3DTRANSFORMSTATETYPE 열거형의 임의의 멤버 또는 D3DTS_WORLDMATRIX 매크로를 지정할 수 있다.
pMatrix
[in] 현재의 트랜스 폼을 변경하는 D3DMATRIX 구조체에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

인수의 1 개가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetTransform ,IDirect3DDevice8::SetRenderState ,D3DTS_WORLD ,D3DTS_WORLDn ,D3DTS_WORLDMATRIX


IDirect3DDevice8::SetVertexShader

이전에 생성 한 버텍스 쉐이더, 또는 유연한 버텍스 포맷 (FVF)의 고정 기능 쉐이더에, 현재의 버텍스 쉐이더를 설정한다.

HRESULT SetVertexShader(
  DWORD Handle
);

파라미터

Handle
[in] 설정하는 버텍스 쉐이더를 지정하는 버텍스 쉐이더에의 핸들. 이 파라미터의 값으로서IDirect3DDevice8::CreateVertexShader 로부터 돌아가는 핸들 또는 FVF 코드를 사용할 수 있다. FVF 코드는유연한 버텍스 포맷 플래그의 편성이다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

핸들로서 FVF 코드를 사용 하면, 고정 기능의 버텍스 쉐이더가 유효하게 되어, 스트림 제로로부터 읽히는 FVF 코드의 컨텐츠와 일치하는 비명시적인 선언이 사용된다. FVF 지정의 쉐이더를 디바이스에 바인드 하면, 스트림 제로만이 참조된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetVertexShader


IDirect3DDevice8::SetVertexShaderConstant

버텍스 정수 배열에 값을 설정한다.

HRESULT SetVertexShaderConstant(
  DWORD Register,
  CONST void* pConstantData,
  DWORD  ConstantCount
);

파라미터

Register
[in] 버텍스 정수 배열에의 데이터의 로드를 시작 하는 레지스터 주소.
pConstantData
[in] 버텍스 정수 배열에 로드하는 값이 저장 되고 있는 데이터 블록에의 포인터. 데이터 블록의 사이즈는,ConstantCount * 4 * sizeof(float)이다.
ConstantCount
[in] 버텍스 정수 배열에 로드하는 정수의 수. 각 정수는, 4 개의 부동 소수점값으로부터 완성된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 버텍스 쉐이더 어셈블러의 정수 레지스터에 값을 로드하기 위해서(때문에) 사용한다. 트랜스 폼 행렬을 로드할 때는, 어플리케이션은 그 행과 열을 전치 하고 나서, 연속한 정수 레지스터에 로드할 필요가 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetVertexShaderConstant


IDirect3DDevice8::SetViewport

디바이스에 뷰 포토 파라미터를 설정한다.

HRESULT SetViewport(
  CONST D3DVIEWPORT8* pViewport
);

파라미터

pViewport
[in] 설정하는 뷰 포토 파라미터를 나타내는 D3DVIEWPORT8 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

pViewport 파라미터가 무효인 경우는,D3DERR_INVALIDCALL 가 된다.

D3DVIEWPORT8 구조체로 기술하는 뷰 포토 파라미터가, 렌더링 타겟 표면내에 존재할 수 없는 영역을 기술하고 있는 경우, 메소드는 실패해,D3DERR_INVALIDCALL 을 돌려준다.

주의

IDirect3DDevice8::BeginScene 와 IDirect3DDevice8::EndScene 의 사이에서의 SetViewPort 의 호출은, 지오메트리를 드로잉(Drawing) 하기 전에 실시하지 않으면 안 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetViewport


IDirect3DDevice8::ShowCursor

커서를 표시 또는 은폐 한다.

BOOL ShowCursor(
  BOOL bShow
);

파라미터

bShow
[in] TRUE 를 지정 하면, 커서가 표시된다. FALSE 를 지정 하면, 커서가 은폐 된다.

반환값

호출전에 커서가 표시되고 있었는지 어떠했는지를 나타내는 값. 커서가 표시되고 있었을 경우는 TRUE , 커서가 표시되어 있지 않았던 경우는 FALSE 를 돌려준다.

주의

Microsoft® Direct3D® 의 커서 함수에서는, 하드웨어에 응해, GDI 커서 또는 소프트웨어 에뮬레이션의 어느쪽이든을 사용한다. 유저는 보통, WM_SETCURSOR 메세지에 응한다. 예를 들어, 유저는 메세지 핸들러를 다음과 같이 기술할 수 있다.

case WM_SETCURSOR:
    // 윈도우 커서를 오프로 한다.
    SetCursor( NULL );
    m_pd3dDevice->ShowCursor( TRUE );
    return TRUE; // Windows 가 커서를 윈도우 클래스 커서로 설정하지 않게 한다.
break;

또, 커서를 변경하는 경우는, 유저는 IDirect3DDevice8::SetCursorProperties 메소드를 호출할 수가 있다. 상세한 것에 대하여는, Microsoft DirectX® Graphics C/C++ 샘플의 샘플 코드를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::SetCursorPosition ,IDirect3DDevice8::SetCursorProperties


IDirect3DDevice8::TestCooperativeLevel

윈도우 어플리케이션 또는 풀 스크린 어플리케이션에 대한 Microsoft® Direct3D® 디바이스의 현재의 협조 레벨 스테이터스를 보고한다.

HRESULT TestCooperativeLevel();

파라미터

없음.

반환값

성공했을 경우는,D3D_OK 를 돌려준다. 이 반환값은, 디바이스가 동작하고 있어, 호출측 어플리케이션을 속행할 수 있는 것을 나타낸다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다 ( 「주의」를 참조).

D3DERR_DEVICELOST
D3DERR_DEVICENOTRESET

주의

디바이스가 없어졌음에도 불구하고, 현시점에서 복원할 수 없는 경우,IDirect3DDevice8::TestCooperativeLevel 는 D3DERR_DEVICELOST 귀가 코드를 돌려준다. 예를 들어, 풀 스크린 디바이스가 포커스를 잃은 것 같은 경우이다. 어플리케이션으로 소실한 디바이스를 검출했을 경우, 어플리케이션은 중단해 TestCooperativeLevel 를 정기적으로 호출해, 반환값 D3DERR_DEVICENOTRESET 를 받을 때까지 대기할 필요가 있다. 그 후로,IDirect3DDevice8::Reset 를 호출해 디바이스를 리셋 한다. 이것에 성공했을 경우는, 필요한 리소스를 복원해, 보통의 처리를 재개한다. 디바이스 상태가 "소실" 또는 "비리셋" 의 몇개의 경우는,IDirect3DDevice8::Present 는 D3DERR_DEVICELOST 를 돌려주는 것에 주의한다.

리셋 하는 디바이스를 생성 한 thread와는 다른 thread로 호출하면,TestCooperative Level 의 호출은 실패한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DDevice8::UpdateTexture

텍스쳐의 더티 부분을 갱신한다.

HRESULT UpdateTexture(
  IDirect3DBaseTexture8* pSourceTexture,
  IDirect3DBaseTexture8* pDestinationTexture
);

파라미터

pSourceTexture
[in] 전송원텍스쳐를 나타내는 IDirect3DBaseTexture8 인터페이스에의 포인터. 전송원텍스쳐는 시스템 메모리내 (D3DPOOL_SYSTEMMEM)에 없으면 안 된다.
pDestinationTexture
[in] 전송처 텍스쳐를 나타내는 IDirect3DBaseTexture8 인터페이스에의 포인터. 전송처 텍스쳐는 D3DPOOL_DEFAULT 메모리 풀에 없으면 안 된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

텍스쳐의 일부분을 더티로 하려면 , 그 부분을 잠그는지, 또는 다음의 몇개의 메소드를 호출한다.

  • IDirect3DCubeTexture8::AddDirtyRect
  • IDirect3DTexture8::AddDirtyRect
  • IDirect3DVolumeTexture8::AddDirtyBox
  • IDirect3DDevice8::CopyRects

UpdateTexture 는, 마지막 갱신 조작 이후에 누적된 조작을 계산하는 것으로, 텍스쳐의 더티 부분을 취득한다.

전송원과 전송처의 텍스쳐의 타입이 다른 경우, 양쪽 모두의 텍스쳐의 최하정도 버퍼의 사이즈가 다른 경우, 및 일치 레벨이 일치하지 않는 경우, 이 메소드는 실패한다. 예를 들어, 다음과 같은 넓이의 6 개의 레벨의 전송원텍스쳐가 있다고 한다.

32x16, 16x8, 8x4, 4x2, 2x1, 1x1

이 6 개의 레벨의 전송원텍스쳐는, 다음의 1 개의 레벨의 전송처의 전송 바탕으로 된다.

1x1

2 개의 레벨의 전송처의 경우.

2x1, 1x1

또는, 4 개의 레벨의 전송처의 경우.

4x2, 2x1, 1x1

또, 텍스쳐의 포맷이 다른 경우, 이 메소드는 실패한다. 전송처 텍스쳐의 레벨수가 전송원보다 적은 경우는, 일치하는 레벨만이 카피된다.

전송원텍스쳐에 더티 영역이 있는 경우는, 카피를 그 영역에만 한정하는 것으로, 카피 처리를 최적화할 수 있다. 더티로서 마크 되고 있는 바이트만이 카피된다고 하는 보증은 없다.

퍼포먼스의 이유에 의해, 더티인 범위는 텍스쳐의 레벨 제로에 대해서 기록될 뿐이다. 서브 레벨에 대해서는, 대응하는 (스케일 된 ) 직사각형, 또는 박스도 더티이라고 가정된다. D3DLOCK_NO_DIRTY_UPDATE 또는 D3DLOCK_READONLY 없음으로 LockRect 나 LockBox 가 불려 갔을 때, 더티인 범위는 자동적으로 기록된다. 또 CopyRects 호출의 행선지 서페이스는 더티로서 마크 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3D8::CreateDevice


IDirect3DDevice8::ValidateDevice

현재의 텍스쳐의 블렌딩 처리와 인수를 디바이스가 1 회의 처리로 렌더링 할 수 있는 능력을 보고한다.

HRESULT ValidateDevice(
  DWORD* pNumPasses
);

파라미터

pNumPasses
[out, retval] 멀티 패스 렌더링에 의해 목적의 이펙트를 완성하기 위해서 필요한 렌더링 패스의 수를 저장 하는 DWORD 값에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_CONFLICTINGTEXTUREFILTER
D3DERR_CONFLICTINGTEXTUREPALETTE
D3DERR_TOOMANYOPERATIONS
D3DERR_UNSUPPORTEDALPHAARG
D3DERR_UNSUPPORTEDALPHAOPERATION
D3DERR_UNSUPPORTEDCOLORARG
D3DERR_UNSUPPORTEDCOLOROPERATION
D3DERR_UNSUPPORTEDFACTORVALUE
D3DERR_UNSUPPORTEDTEXTUREFILTER
D3DERR_WRONGTEXTUREFORMAT

주의

ValidateDevice 메소드는, 다른 능력이 부속되어 있는 시나리오를 검증하는 경우에게만 사용해야 한다. 예를 들어, 멀티 스테이지 텍스쳐 링의 시나리오에서는,D3DCAPS8 구조체의 MaxTextureBlendStages 멤버와 MaxSimultaneousTextures 멤버를 조사하는 것으로, 그 디바이스로 멀티 스테이지 텍스쳐 링이 가능한가 어떤가를 판단할 수 있다.

현재의 하드웨어가, 반드시 조작과 인수의 가능한 모든 편성을 이행 하고 있을 필요는 없다. 주어진 인수로 특정의 블렌딩 처리를 실행할 수 있을지 어떨지는, 목적의 블렌딩 처리를 설정해,ValidateDevice 메소드를 호출하는 것으로 확인할 수 있다.

ValidateDevice 메소드는, 현재의 렌더링 스테이트, 텍스쳐, 텍스쳐 스테이지의 스테이트를 사용해, 불려 간 시점에서의 확인을 실시한다. 이 호출의 후에 이러한 요소로 변경이 있으면(자), 지금까지의 확인 결과는 무효가 되므로, 장면의 렌더링을 하기 전에 이 메소드를 재차 호출하지 않으면 안 된다.

디퓨즈 보간값의 인수 또는 조작 (D3DTA_DIFFUSE 또는 D3DTOP_BLENDDIFFUSEALPHA)으로서의 사용은, 현재의 하드웨어에서는 거의 지원되어 있지 않다. 대부분의 하드웨어에서는, 직전의 텍스쳐 처리 스테이지에 있어 보간색데이터의 값을 도입하고 있는 정도이다.

각 스테이지의 텍스쳐 (D3DTA_TEXTURE)는, 제 2 인수는 아니고 제 1 인수로서 지정하도록(듯이) 한다.

많은 카드는, 임의의 텍스쳐 스테이지에 있어서의 디퓨즈값이나 스칼라값의 사용은 지원 하고 있지 않다. 이것들은, 최초 또는 마지막 텍스쳐 블렌딩 스테이지에서만 사용할 수 있는 것이 많다.

최초의 텍스쳐에 관련지을 수 있었던 블렌딩 유니트로, 알파 채널로부터 칼라 채널에의 복제나 입력 반전 등 이상의 능력을 가지는 것을 갖춘 카드는 적다. 따라서, 어플리케이션에서는, 가능한 경우, 2 번째의 텍스쳐 스테이지만 사용해야 할 때가 있다. 이러한 하드웨어에서는, 최초의 유니트는 디폴트 스테이트에 있으면(자) 가정되어 D3DTOP_SELECTARG1 처리에 있어서의 제 1 칼라 인수에는 D3DTA_TEXTURE 가 설정된다.

출력되는 알파값에 대한 조작으로, 칼라 처리보다 복잡한 것, 또는 칼라 처리와 본질적으로 다른 것을 지원 하는 하드웨어는, 한층 더 적다.

하드웨어에 따라서는, D3DTA_TFACTOR 와 D3DTA_DIFFUSE 의 동시 사용을 지원 하고 있지 않는 경우도 있다.

또 많은 카드는, 멀티 텍스쳐와 밉맵 트라이 리니어 필터 링의 동시 사용을 지원 하고 있지 않다. 멀티 텍스쳐 블렌딩 처리에 있어서의 텍스쳐에 대해서 트라이 리니어 필터 링이 요구되었을 경우, 타당성 검증이 실패 하면, 트라이 리니어 필터 링은 오프가 되어 재검증을 한다. 이러한 경우에는, 대신에 멀티 패스 렌더링을 실행할 수가 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::GetTextureStageState ,IDirect3DDevice8::SetTextureStageState


IDirect3DIndexBuffer8

인덱스 버퍼 리소스를 조작하려면 ,IDirect3DIndexBuffer8 인터페이스의 메소드를 사용한다.

IDirect3DIndexBuffer8 인터페이스를 취득하려면 ,IDirect3DDevice8::CreateIndexBuffer 메소드를 호출한다.

IDirect3DIndexBuffer8 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirect3DResource8 메소드를 계승한다.

디바이스 | GetDevice
정보 | GetType
프라이빗 표면 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData
리소스 관리 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DIndexBuffer8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetDesc
락 | Lock
 | Unlock

모든 COM 인터페이스와 같이,IDirect3DIndexBuffer8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DINDEXBUFFER8 및 PDIRECT3DINDEXBUFFER8 형은,IDirect3DIndexBuffer8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DIndexBuffer8 *LPDIRECT3DINDEXBUFFER8, *PDIRECT3DINDEXBUFFER8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CreateIndexBuffer


IDirect3DIndexBuffer8::GetDesc

인덱스 버퍼 리소스의 기술을 취득한다.

HRESULT GetDesc(
  D3DINDEXBUFFER_DESC* pDesc
);

파라미터

pDesc
[out] 돌려주어지는 인덱스 버퍼를 기술하고 있는 D3DINDEXBUFFER_DESC 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

이 인수가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DIndexBuffer8::Lock

인덱스 데이터의 범위를 잠그어, 인덱스 버퍼 메모리에의 포인터를 취득한다.

HRESULT Lock(
  UINT OffsetToLock,
  UINT SizeToLock,
  BYTE** ppbData,
  DWORD Flags
);

파라미터

OffsetToLock
[in] 잠그는 인덱스 데이터에의 오프셋(offset) (바이트 단위).
SizeToLock
[in] 잠그는 인덱스 데이터의 사이즈 (바이트 단위).
ppbData
[out] 돌려주어지는 인덱스 데이터가 저장 되는 BYTE 값배열에의 포인터의 주소.
Flags
[in] 0 개 이상의 락킹 플래그의 편성. 인덱스 버퍼 메모리를 잠그는 방법을 나타낸다.
D3DLOCK_DISCARD
어플리케이션은, 기입 전용 처리로 인덱스 버퍼 전체를 덧쓰기한다. 이것에 의해, Direct3D 는 새로운 메모리 영역에의 포인터를 돌려줄 수가 있으므로, 다이나믹 메모리 액세스 (DMA)와 낡은 영역으로부터의 렌더링이 기능 정지할 것은 없다.
D3DLOCK_NOOVERWRITE
프레임의 시작 이후, 또는 이 플래그가 지정되어 있지 않은 마지막 락 이후에 드로잉(Drawing) 처리의 호출 중(안)에서 참조된 인덱스는, 락중으로 변경되지 않는 것을 나타낸다. 인덱스 버퍼에의 데이터의 추가만을 실시하는 경우는, 이 플래그에 의해 처리를 최적화할 수 있다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템의 크리티컬 섹션을 확보하는 것으로, 락중에 디스플레이 모드의 변경을 하지 않는 것을 보증한다. 이 플래그는, 시스템 와이드인 크리티컬 섹션이 락의 사이 보관 유지되지 않게 한다.

락 처리는 약간 부하가 높아지지만, 마우스 커서의 이동 등, 시스템으로 다른 처리를 실행하는 것이 가능하게 된다. 이 플래그는, 소프트웨어 렌더링의 백 버퍼의 락과 같이, 락이 장시간에 이르러, 시스템의 응답성에 악영향을 주어 버리는 것 같은 락에 대해서 유효하다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입을 실시하지 않는다. 이것에 의해, 얼마인가의 최적화가 실현된다. D3DLOCK_READONLY 는 D3DLOCK_DISCARD 와 함께 지정할 수 없다. 또, D3DUSAGE_WRITEONLY 로 생성 된 버텍스 버퍼로 지정하는 일도 할 수 없다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

인덱스 버퍼의 처리에서는, 락의 호출을 여러 차례 실시할 수 있다. 다만, 락의 호출 회수와 언락의 호출 회수가 일치하고 있을 필요가 있다. 현재 설정해 있는 인덱스 버퍼로 락 카운트가 남아 있는 경우, DrawPrimitive 의 호출은 실패한다.

D3DLOCK_DISCARD 및 D3DLOCK_NOOVERWRITE 플래그는, D3DUSAGE_DYNAMIC 로 생성 된 버퍼 에 대해서만 유효하다.

D3DLOCK_DISCARD 또는 D3DLOCK_NOOVERWRITE 를 Lock 메소드의 Flags 파라미터로 사용하는 방법에 대해서는, 「동적인 버텍스 및 인덱스 버퍼의 사용법」을 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DIndexBuffer8::Unlock


IDirect3DIndexBuffer8::Unlock

인덱스 데이터를 언락 한다.

HRESULT Unlock();

파라미터

없음.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DIndexBuffer8::Lock


IDirect3DResource8

리소스의 조회 및 준비를 실시하려면 ,IDirect3DResource8 인터페이스의 메소드를 사용한다.

다음의 몇개의 메소드를 호출하는 것으로, 텍스쳐 리소스를 생성 할 수 있다.

  • IDirect3DDevice8::CreateCubeTexture
  • IDirect3DDevice8::CreateTexture
  • IDirect3DDevice8::CreateVolumeTexture

다음의 몇개의 메소드를 호출하는 것으로, 지오메트리 지향의 리소스를 생성 할 수 있다.

  • IDirect3DDevice8::CreateIndexBuffer
  • IDirect3DDevice8::CreateVertexBuffer

IDirect3DResource8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

디바이스 | GetDevice
정보 | GetType
프라이빗 표면 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData
리소스 관리 | GetPriority
 | PreLoad
 | SetPriority

모든 COM 인터페이스와 같이,IDirect3DResource8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DRESOURCE8 및 PDIRECT3DRESOURCE8 형은,IDirect3DResource8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DResource8 *LPDIRECT3DRESOURCE8, *PDIRECT3DRESOURCE8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DResource8::FreePrivateData

이 리소스에 관련지을 수 있고 있는 지정된 프라이빗 데이터를 해방한다.

HRESULT FreePrivateData(
  REFGUID refguid
);

파라미터

refguid
[in] 해방하는 프라이빗 데이터를 식별하는 글로벌 유니크 식별자에의 참조 (C++) 또는 주소 (C).

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTFOUND

대상

이 메소드는, 다음의 인터페이스 (IDirect3DResource8 로부터 계승)에 적용된다.

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

주의

Microsoft® Direct3D® 는, 리소스가 해방되면(자) 자동적으로 이 메소드를 호출한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DResource8::GetPrivateData ,IDirect3DResource8::SetPrivateData


IDirect3DResource8::GetDevice

리소스에 관련지을 수 있고 있는 디바이스를 취득한다.

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
);

파라미터

ppDevice
[out, retval] 조회가 성공했을 경우에, 디바이스의 포인터가 저장 되는 IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 을 돌려준다.

대상

이 메소드는, 다음의 인터페이스 (IDirect3DResource8 로부터 계승)에 적용된다.

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

주의

이 메소드를 사용 하면, 소유하고 있는 디바이스 오브젝트로 이동할 수가 있다.

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DResource8::GetPriority

이 리소스에 대한 우선 순위를 취득한다.

DWORD GetPriority();

파라미터

없음.

반환값

리소스의 우선 순위를 나타내는 DWORD 값을 돌려준다.

대상

이 메소드는, 다음의 인터페이스 (IDirect3DResource8 로부터 계승)에 적용된다.

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

주의

GetPriority 를 사용해, 관리하의 리소스의 우선 순위를 제어한다. 관리하에 없는 리소스에 대해서는 0 이 돌아간다.

우선 순위를 사용해, 관리하의 리소스를 메모리로부터 언제 삭제할까를 결정할 수 있다. 우선 순위가 낮은 리소스는, 우선 순위가 높은 리소스보다 먼저 삭제된다. 2 개의 리소스의 우선 순위가 같은 경우는, 최종 사용시가 새로운 (분)편의 리소스가 메모리에 보관 유지되어 이제(벌써) 한편의 리소스가 삭제된다. 관리하의 리소스의 디폴트의 우선 순위는 0 이다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DResource8::SetPriority


IDirect3DResource8::GetPrivateData

리소스에 관련지을 수 있었던 프라이빗 데이터가 제공된 버퍼에 카피한다.

HRESULT GetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD* pSizeOfData
);

파라미터

refguid
[in] 취득하는 프라이빗 데이터를 식별하는 글로벌 유니크 식별자에의 참조 (C++) 또는 주소 (C).
pData
[out] 호출이 성공했을 경우에, 요구한 프라이빗 데이터를 저장 하는 할당이 끝난 버퍼에의 포인터. 이 메소드를 호출하는 어플리케이션은, 이 버퍼의 할당과 해방에 책임을 진다.
pSizeOfData
[in, out] pData 의 버퍼 사이즈 (바이트 단위)에의 포인터. 이 값이 실제의 프라이빗 데이터의 사이즈보다 작은 (0 등) 경우, 메소드는 필요한 버퍼 사이즈를 이 파라미터로 설정해,D3DERR_MOREDATA 를 돌려준다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_MOREDATA
D3DERR_NOTFOUND

대상

이 메소드는, 다음의 인터페이스 (IDirect3DResource8 로부터 계승)에 적용된다.

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DResource8::FreePrivateData ,IDirect3DResource8::SetPrivateData


IDirect3DResource8::GetType

리소스의 타입을 돌려준다.

D3DRESOURCETYPE GetType();

파라미터

없음.

반환값

리소스의 타입을 나타내는 D3DRESOURCETYPE 열거형의 멤버를 돌려준다.

대상

이 메소드는, 다음의 인터페이스 (IDirect3DResource8 로부터 계승)에 적용된다.

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DResource8::PreLoad

관리하의 리소스를 프리로드 한다.

void PreLoad();

파라미터

없음.

반환값

없음.

대상

이 메소드는, 다음의 인터페이스 (IDirect3DResource8 로부터 계승)에 적용된다.

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

주의

이 메소드를 호출하는 것은, 이 관리하의 리소스가 어플리케이션에 대해 머지않아 필요하게 되는 것을 의미한다. 관리하에 없는 리소스에 대해서는 어떠한 영향도 미치지 않는다.

PreLoad 는, 각 프레임으로 사용하는 리소스가, 비디오 메모리내에 동시에 수용할 수 있는 양을 넘고 있는 "스래싱" 상태를 검출한다. 그러한 상황하에서는,Preload 는 아무것도 처리를 실시하지 않는다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DResource8::SetPriority

이 리소스에 리소스 관리의 우선 순위를 할당한다.

DWORD SetPriority(
  DWORD PriorityNew
);

파라미터

PriorityNew
[in] 리소스에 대한 새로운 리소스 관리 우선 순위를 나타내는 DWORD 값.

반환값

이전 리소스에 할당할 수 있고 있던 우선 순위의 값을 돌려준다.

대상

이 메소드는, 다음의 인터페이스 (IDirect3DResource8 로부터 계승)에 적용된다.

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

주의

SetPriority 를 사용해, 관리하의 리소스의 우선 순위를 제어한다. 관리하에 없는 리소스에 대해서는 0 이 돌아간다.

우선 순위를 사용해, 관리하의 리소스를 메모리로부터 언제 삭제할까를 결정할 수 있다. 우선 순위가 낮은 리소스는, 우선 순위가 높은 리소스보다 먼저 삭제된다. 2 개의 리소스의 우선 순위가 같은 경우는, 최종 사용시가 새로운 (분)편의 리소스가 메모리에 보관 유지되어 이제(벌써) 한편의 리소스가 삭제된다. 관리하의 리소스의 디폴트의 우선 순위는 0 이다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DResource8::GetPriority


IDirect3DResource8::SetPrivateData

Microsoft® Direct3D® 는 아니고, 어플리케이션에서의 사용이 의도되고 있는 리소스와 데이터를 관련짓는다. 데이터는 값으로 건네받아 복수의 데이터 세트를 단일의 리소스와 관련지을 수가 있다.

HRESULT SetPrivateData(
  REFGUID refguid,
  CONST void* pData,
  DWORD SizeOfData,
  DWORD Flags
);

파라미터

refguid
[in] 설정하는 프라이빗 데이터를 식별하는 글로벌 유니크 식별자에의 참조 (C++) 또는 주소 (C).
pData
[in] 리소스에 관련짓는 데이터가 저장 되고 있는 버퍼에의 포인터.
SizeOfData
[in] pData 의 버퍼 사이즈 (바이트 단위).
Flags
[in] 건네받는 데이터형을 기술하는 값, 또는 리소스가 변경되었을 경우에 데이터를 무효로 할 필요가 있는 것을 어플리케이션에 나타내는 값.
(none)
플래그를 지정하지 않는 경우, Direct3D® 는 버퍼내의 데이터를 보관 유지하는 메모리를 할당해 새로운 버퍼에 데이터를 카피한다. Direct3D 에 의해 할당할 수 있는 버퍼는, 적당 자동적으로 해방된다.
D3DSPD_IUNKNOWN
pData 의 데이터는 IUnknown 인터페이스에의 포인터이다. SizeOfData 는,IUnknown 인터페이스 (sizeof(IUnknown*))에의 포인터의 사이즈로 설정할 필요가 있다. Direct3D 는 pData 를 개입시켜 IUnknown::AddRef 를, 프라이빗 데이터가 파기되는 경우는 IUnknown::Release 를 자동적으로 호출한다. 다음에 같은 GUID 로 SetPrivateData 를 호출하면, 또는 다음에 IDirect3DResource8::FreePrivateData 를 호출하면, 또는 Direct3D8 오브젝트가 해방되면(자), 프라이빗 데이터는 파기된다. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

대상

이 메소드는, 다음의 인터페이스 (IDirect3DResource8 로부터 계승)에 적용된다.

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

주의

Direct3D 는 pData 로 메모리를 관리하지 않는다. 이 버퍼가 동적으로 할당할 수 있었을 경우는, 호출측의 책임으로 메모리를 해방한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DResource8::FreePrivateData ,IDirect3DResource8::GetPrivateData


IDirect3DSurface8

표면의 조회 및 준비를 실시하려면 ,IDirect3DSurface8 인터페이스의 메소드를 사용한다.

IDirect3DSurface8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

디바이스 | GetDevice
정보 | GetContainer
 | GetDesc
표면의 락 | LockRect
 | UnlockRect
프라이빗 표면 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData

모든 COM 인터페이스와 같이,IDirect3DSurface8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DSURFACE8 및 PDIRECT3DSURFACE8 형은,IDirect3DSurface8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DSurface8 *LPDIRECT3DSURFACE8, *PDIRECT3DSURFACE8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

표면 인터페이스


IDirect3DSurface8::FreePrivateData

이 표면에 관련지을 수 있고 있는 지정된 프라이빗 데이터를 해방한다.

HRESULT FreePrivateData(
  REFGUID refguid
);

파라미터

refguid
[in] 해방하는 프라이빗 데이터를 식별하는 글로벌 유니크 식별자에의 참조 (C++) 또는 주소 (C).

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTFOUND

주의

Microsoft® Direct3D® 는, 표면이 해방되면(자) 자동적으로 이 메소드를 호출한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DSurface8::GetPrivateData ,IDirect3DSurface8::SetPrivateData


IDirect3DSurface8::GetContainer

이 표면이 큐브 텍스쳐 또는 밉맵의 아이 레벨인 경우, 부모의 큐브 텍스쳐 또는 텍스쳐 (밉맵) 오브젝트에의 액세스를 제공한다.

HRESULT GetContainer(
  REFIID riid
  void** ppContainer
);

파라미터

riid
[in] 요구하는 컨테이너의 참조 식별자.
ppContainer
[out] 조회가 성공했을 경우에 컨테이너 포인터가 저장 되는 포인터의 주소. 「주의」를 참조할것.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

표면이 IDirect3DDevice8::CreateImageSurface ,IDirect3DDevice8::CreateRenderTarget , 또는 IDirect3DDevice8::CreateDepthStencilSurface 를 사용해 생성 되고 있는 경우, 표면은 스탠드얼론이다고 보여진다. 이 경우,GetContainer 는, 표면의 생성에 사용한 Direct3D 디바이스를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DSurface8::GetDevice

표면에 관련지을 수 있고 있는 디바이스를 취득한다.

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
);

파라미터

ppDevice
[out, retval] 조회가 성공했을 경우에, 디바이스의 포인터가 저장 되는 IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드를 사용 하면, 소유하고 있는 디바이스 오브젝트로 이동할 수가 있다.

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DSurface8::GetPrivateData

표면에 관련지을 수 있었던 프라이빗 데이터가 제공된 버퍼에 카피한다.

HRESULT GetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD* pSizeOfData
);

파라미터

refguid
[in] 취득하는 프라이빗 데이터를 식별하는 글로벌 유니크 식별자에의 참조 (C++) 또는 주소 (C).
pData
[in, out] 호출이 성공했을 경우에, 요구한 프라이빗 데이터를 저장 하는 할당이 끝난 버퍼에의 포인터. 이 메소드를 호출하는 어플리케이션은, 이 버퍼의 할당과 해방에 책임을 진다.
pSizeOfData
[in, out] pData 의 버퍼 사이즈 (바이트 단위)에의 포인터. 이 값이 실제의 프라이빗 데이터의 사이즈보다 작은 (0 등) 경우, 메소드는 필요한 버퍼 사이즈를 이 파라미터로 설정해, D3DERR_MOREDATA 를 돌려준다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_MOREDATA
D3DERR_NOTFOUND

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DSurface8::FreePrivateData ,IDirect3DSurface8::SetPrivateData


IDirect3DSurface8::GetDesc

표면의 기술을 취득한다.

HRESULT GetDesc(
  D3DSURFACE_DESC* pDesc
);

파라미터

pDesc
[out] 표면을 기술하고 있는 D3DSURFACE_DESC 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

이 인수가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DSurface8::LockRect

표면 위에의 직사각형을 잠근다.

HRESULT LockRect(
  D3DLOCKED_RECT* pLockedRect,
  CONST RECT* pRect,
  DWORD Flags
);

파라미터

pLockedRect
[out] 락 끝난 영역을 기술하는 D3DLOCKED_RECT 구조체에의 포인터.
pRect
[in] 잠그는 직사각형에의 포인터. RECT 구조체에의 포인터에 의해 지정된다. 이 파라미터에 NULL 를 지정 하면, 표면 전체를 가리도록(듯이) 더티 영역이 확대한다.
Flags
[in] 실행하는 락의 타입을 기술하는, 0 개 이상의 락킹 플래그의 편성.
D3DLOCK_NO_DIRTY_UPDATE
디폴트에서는, 리소스의 락은 더티 영역을 그 리소스에 추가한다. 이 플래그는, 리소스의 더티 상태에의 변경을 막는다. 락 처리동안으로 변경되는 실제의 영역군에 대한 추가 정보를 어플리-숀이 가지는 경우는, 어플리케이션으로 이 플래그를 사용해야 한다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템의 크리티컬 섹션을 확보하는 것으로, 락중에 디스플레이 모드의 변경을 하지 않는 것을 보증한다. 이 플래그는, 시스템 와이드인 크리티컬 섹션이 락의 사이 보관 유지되지 않게 한다.

락 처리는 약간 부하가 높아지지만, 마우스 커서의 이동 등, 시스템으로 다른 처리를 실행하는 것이 가능하게 된다. 이 플래그는, 소프트웨어 렌더링의 백 버퍼의 락과 같이, 락이 장시간에 이르러, 시스템의 응답성에 악영향을 주어 버리는 것 같은 락에 대해서 유효하다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입을 실시하지 않는다. 이것에 의해, 네이티브가 아닌 포맷으로 저장 된 리소스가, 언락시에 재압축 순서를 보존할 수 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

스텐실 표면의 락 가능한 포맷은, D3DFMT_D16_LOCKABLE 뿐이다.

멀티 샘플 백 버퍼는 잠글 수 없다.

퍼포먼스의 이유에 의해, 더티인 범위는 텍스쳐의 레벨 제로에 대해서 기록될 뿐이다. D3DLOCK_NO_DIRTY_UPDATE 또는 D3DLOCK_READONLY 없음으로 LockRect 나 LockBox 가 불려 갔을 때, 더티인 범위는 자동적으로 기록된다. 또 CopyRects 호출의 행선지 서페이스는 더티로서 마크 된다. 상세한 것에 대하여는, 「IDirect3DDevice8::UpdateTexture」를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DSurface8::UnlockRect


IDirect3DSurface8::SetPrivateData

Microsoft® Direct3D® 는 아니고, 어플리케이션에서의 사용이 의도되고 있는 표면과 데이터를 관련짓는다.

HRESULT SetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD SizeOfData,
  DWORD Flags
);

파라미터

refguid
[in] 설정하는 프라이빗 데이터를 식별하는 글로벌 유니크 식별자에의 참조 (C++) 또는 주소 (C).
pData
[in] 표면과 관련짓는 데이터가 저장 되고 있는 버퍼에의 포인터.
SizeOfData
[in] pData 의 버퍼 사이즈 (바이트 단위).
Flags
[in] 건네받는 데이터형을 기술하는 값, 또는 리소스가 변경되었을 경우에 데이터를 무효로 할 필요가 있는 것을 어플리케이션에 나타내는 값.
(none)
플래그를 지정하지 않는 경우, Direct3D 는 버퍼내의 데이터를 보관 유지하는 메모리를 할당해 새로운 버퍼에 데이터를 카피한다. Direct3D 에 의해 할당할 수 있는 버퍼는, 적당 자동적으로 해방된다.
D3DSPD_IUNKNOWN
pData 의 데이터는 IUnknown 인터페이스에의 포인터이다. SizeOfData 는,IUnknown 인터페이스 (sizeof(IUnknown*))에의 포인터의 사이즈로 설정할 필요가 있다. Direct3D 는 pData 를 개입시켜 IUnknown::AddRef 를, 프라이빗 데이터가 파기되는 경우는 IUnknown::Release 를 자동적으로 호출한다. 다음에 같은 GUID 로 SetPrivateData 를 호출하면, 또는 다음에 IDirect3DSurface8::FreePrivateData 를 호출하면, 또는 Direct3D8 오브젝트가 해방되면(자), 프라이빗 데이터는 파기된다. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

Direct3D 는 pData 로 메모리를 관리하지 않는다. 이 버퍼가 동적으로 할당할 수 있었을 경우는, 호출측의 책임으로 메모리를 해방한다.

데이터는 값으로 건네받아 복수의 데이터 세트를 단일의 표면과 관련지을 수가 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DSurface8::FreePrivateData ,IDirect3DSurface8::GetPrivateData


IDirect3DSurface8::UnlockRect

표면 위에의 직사각형을 언락 한다.

HRESULT UnlockRect();

파라미터

없음.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DSurface8::LockRect


IDirect3DSwapChain8

스왑 체인을 조작하려면 ,IDirect3DSwapChain8 인터페이스의 메소드를 사용한다.

각 디바이스에는, 적어도 1 개의 스왑 체인이 항상 존재하고 있어, 비명시적인 스왑 체인으로 불린다. 다만,IDirect3DDevice8::CreateAdditionalSwapChain 메소드를 호출하는 것으로, 같은 디바이스로부터 복수의 뷰를 렌더링하기 위한 추가 스왑 체인을 생성 할 수 있다.

IDirect3DSwapChain8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

프레젠테이션 | Present
표면 관리 | GetBackBuffer

모든 COM 인터페이스와 같이,IDirect3DSwapChain8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DSWAPCHAIN8 및 PDIRECT3DSWAPCHAIN8 형은,IDirect3DSwapChain8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DSwapChain8 *LPDIRECT3DSWAPCHAIN8, *PDIRECT3DSWAPCHAIN8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CreateAdditionalSwapChain


IDirect3DSwapChain8::GetBackBuffer

디바이스의 스왑 체인으로부터 백 버퍼를 취득한다.

HRESULT GetBackBuffer(
  UINT  BackBuffer,
  D3DBACKBUFFER_TYPE Type,
  IDirect3DSurface8** ppBackBuffer
);

파라미터

BackBuffer
[in] 돌려주어지는 백 버퍼 오브젝트의 인덱스. 백 버퍼는 0 으로부터 백 버퍼의 총수 - 1 까지 넘버링 된다. 0 의 반환값은 최초의 백 버퍼를 나타내, 프런트 버퍼는 아니다. 이 메소드를 사용해 프런트 버퍼에 액세스 할 수 없다.
Type
[in] DirectX 8.0 에서는 스테레오 뷰는 지원되어 있지 않기 때문에, 이 파라미터의 유효한 값은 D3DBACKBUFFER_TYPE_MONO 뿐이다.
ppBackBuffer
[out, retval] 돌려주어지는 백 버퍼 표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

BackBuffer 가 백 버퍼의 총수 이상의 경우, 함수는 실패해,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DSurface8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DSurface8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DSwapChain8::Present

스왑 체인이 소유하는 백 버퍼의 순서 중(안)에서 다음의 컨텐츠를 제시한다.

HRESULT Present(
  CONST RECT* pSourceRect,
  CONST RECT* pDestRect,
  HWND hDestWindowOverride,
  CONST RGNDATA* pDirtyRegion
);

파라미터

pSourceRect
[in] 전송원직사각형을 포함한 RECT 구조체에의 포인터. 이 값은, 스왑 체인이 D3DSWAPEFFECT_COPY 또는 D3DSWAPEFFECT_COPY_VSYNC 로 생성되어 있지 않은 한, NULL 가 아니면 안된다. NULL 의 경우는, 전송원표면 전체가 표시된다. 직사각형이 전송원표면을 넘었을 경우, 직사각형은 전송원표면에 클리핑 된다.
pDestRect
[in] 윈도우의 클라이언트 좌표로 전송처 직사각형을 포함한 RECT 구조체에의 포인터. 이 값은, 스왑 체인이 D3DSWAPEFFECT_COPY 또는 D3DSWAPEFFECT_COPY_VSYNC 로 생성되어 있지 않은 한, NULL 가 아니면 안된다. NULL 의 경우는, 클라이언트 영역 전체가 저장 된다. 직사각형이 전송처의 클라이언트 영역을 넘었을 경우, 직사각형은 전송처의 클라이언트 영역에 클리핑 된다.
hDestWindowOverride
[in] 클라이언트 영역이 이 프레젠테이션의 대상으로 해 다루어지는 전송처 윈도우. 이 파라미터가 NULL 의 경우는,D3DPRESENT_PARAMETERS 의 hWndDeviceWindow 멤버가 사용된다.
pDirtyRegion
[in] 이 파라미터는 미사용인 모아 두어 NULL 로 설정할 필요가 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

이 메소드의 동작은,IDirect3DDevice8::Present 메소드와 완전히 같다.

필요에 따라서, 전송원직사각형내의 픽셀을 타겟 윈도우의 클라이언트 영역의 전송처 직사각형에 전송 하기 위해서 확대 처리가 적용된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::Reset


IDirect3DTexture8

텍스쳐 리소스를 조작하려면 ,IDirect3DTexture8 인터페이스의 메소드를 사용한다.

IDirect3DTexture8 인터페이스를 취득하려면 ,IDirect3DDevice8::CreateTexture 메소드를 호출한다.

IDirect3DTexture8 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirect3DResource8 메소드를 계승한다.

디바이스 | GetDevice
정보 | GetType
프라이빗 표면 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData
리소스 관리 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DTexture8 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirect3DBaseTexture8 메소드를 계승한다.

상세 | GetLOD
 | SetLOD
정보 | GetLevelCount

IDirect3DTexture8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetLevelDesc
표면의 락 | LockRect
 | UnlockRect
그 외 | AddDirtyRect
 | GetSurfaceLevel

모든 COM 인터페이스와 같이,IDirect3DTexture8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DTEXTURE8 및 PDIRECT3DTEXTURE8 형은,IDirect3DTexture8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DTexture8 *LPDIRECT3DTEXTURE8, *PDIRECT3DTEXTURE8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CreateTexture


IDirect3DTexture8::AddDirtyRect

텍스쳐 리소스에 더티 영역을 추가한다.

HRESULT AddDirtyRect(
  CONST RECT* pDirtyRect
);

파라미터

pDirtyRect
[in] RECT 구조체에의 포인터. 추가하는 더티 영역을 지정한다. NULL 를 지정 하면, 더티 영역이 확대해 텍스쳐 전체를 가린다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

리소스의 더티 영역을 지정하는 것으로, 카피되는 리소스의 서브 세트를 최적화할 수 있다.

퍼포먼스의 이유에 의해, 더티인 범위는 텍스쳐의 레벨 제로에 대해서 기록될 뿐이다. 서브 레벨에 대해서는, 대응하는 (스케일 된 ) 직사각형 또는 박스도 더티이라고 가정된다. D3DLOCK_NO_DIRTY_UPDATE 또는 D3DLOCK_READONLY 없음으로 LockRect 나 LockBox 가 불려 갔을 때, 더티인 범위는 자동적으로 기록된다. 또 CopyRects 호출의 행선지 서페이스는 더티로서 마크 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DTexture8::GetLevelDesc

텍스쳐 표면의 레벨 기술을 취득한다.

HRESULT GetLevelDesc(
  UINT Level,
  D3DSURFACE_DESC* pDesc
);

파라미터

Level
[in] 텍스쳐의 리소스의 레벨을 식별한다. 이 메소드는, 이 파라미터로 지정된 레벨에 대한 표면의 기술을 돌려준다.
pDesc
[out] 돌려주어지는 레벨이 기술되고 있는 D3DSURFACE_DESC 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수의 1 개가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DTexture8::GetSurfaceLevel

지정된 텍스쳐 표면의 레벨을 취득한다.

HRESULT GetSurfaceLevel(
  UINT Level,
  IDirect3DSurface8** ppSurfaceLevel
);

파라미터

Level
[in] 텍스쳐의 리소스의 레벨을 식별한다. 이 메소드는, 이 파라미터로 지정된 레벨에 대한 표면을 돌려준다. 톱 레벨의 표면은 0 으로 나타난다.
ppSurfaceLevel
[out, retval] 돌려주어지는 표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DSurface8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DSurface8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DTexture8::LockRect

텍스쳐 리소스 위에의 직사각형을 잠근다.

HRESULT LockRect(
  UINT Level,
  D3DLOCKED_RECT* pLockedRect,
  CONST RECT* pRect,
  DWORD Flags
);

파라미터

Level
[in] 잠그는 텍스쳐 리소스의 레벨을 지정한다.
pLockedRect
[out] 락 끝난 영역을 기술하는 D3DLOCKED_RECT 구조체에의 포인터.
pRect
[in] 잠그는 직사각형에의 포인터. RECT 구조체에의 포인터에 의해 지정된다. 이 파라미터에 NULL 를 지정 하면, 텍스쳐 전체를 가리도록(듯이) 더티 영역이 확대한다.
Flags
[in] 실행하는 락의 타입을 기술하는, 0 개 이상의 락킹 플래그의 편성.
D3DLOCK_NO_DIRTY_UPDATE
디폴트에서는, 리소스의 락은 더티 영역을 그 리소스에 추가한다. 이 플래그는, 리소스의 더티 상태에의 변경을 막는다. 락 처리동안으로 변경되는 실제의 영역군에 대한 추가 정보를 어플리케이션이 가지고 있어, 그 정보를 IDirect3DTexture8::AddDirtyRect 에 건네줄 수가 있는 경우는, 어플리케이션으로 이 플래그를 사용해야 한다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템의 크리티컬 섹션을 확보하는 것으로, 락중에 디스플레이 모드의 변경을 하지 않는 것을 보증한다. 이 플래그는, 시스템 와이드인 크리티컬 섹션이 락의 사이 보관 유지되지 않게 한다.

락 처리는 약간 부하가 높아지지만, 마우스 커서의 이동 등, 시스템으로 다른 처리를 실행하는 것이 가능하게 된다. 이 플래그는, 소프트웨어 렌더링의 백 버퍼의 락과 같이, 락이 장시간에 이르러, 시스템의 응답성에 악영향을 주어 버리는 것 같은 락에 대해서 유효하다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입을 실시하지 않는다. 이것에 의해, 네이티브가 아닌 포맷으로 저장 된 리소스가, 언락시에 재압축 순서를 보존할 수 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

D3DPOOL_DEFAULT 로 생성 된 텍스쳐는 잠글 수 없다.

스텐실 표면의 락 가능한 포맷은, D3DFMT_D16_LOCKABLE 뿐이다.

멀티 샘플 백 버퍼는 잠글 수 없다. 비디오 메모리 텍스쳐는 잠글 수 없지만,IDirect3Ddevice8::CopyRects 또는 IDirect3Ddevice8::UpdateTexture 를 호출해 수정할 필요가 있다. Microsoft® DirectX® 8.0 이 인식하지 않는, 일부의 메이커의 드라이버의 픽셀 포맷은 예외이다. 이것들은 잠글 수 있다.

퍼포먼스의 이유에 의해, 더티인 범위는 텍스쳐의 레벨 제로에 대해서 기록될 뿐이다. D3DLOCK_NO_DIRTY_UPDATE 또는 D3DLOCK_READONLY 없음으로 LockRect 나 LockBox 가 불려 갔을 때, 더티인 범위는 자동적으로 기록된다. 상세한 것에 대하여는, 「IDirect3DDevice8::UpdateTexture」를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DTexture8::UnlockRect


IDirect3DTexture8::UnlockRect

텍스쳐 리소스 위에의 직사각형을 언락 한다.

HRESULT UnlockRect(
  UINT Level
);

파라미터

Level
[in] 언락 하는 텍스쳐 리소스의 레벨을 지정한다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DTexture8::LockRect


IDirect3DVertexBuffer8

버텍스 버퍼 리소스를 조작하려면 ,IDirect3DVertexBuffer8 인터페이스의 메소드를 사용한다.

IDirect3DVertexBuffer8 인터페이스를 취득하려면 ,IDirect3DDevice8::CreateVertexBuffer 메소드를 호출한다.

IDirect3DVertexBuffer8 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirect3DResource8 메소드를 계승한다.

디바이스 | GetDevice
정보 | GetType
프라이빗 표면 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData
리소스 관리 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DVertexBuffer8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetDesc
락 | Lock
 | Unlock

모든 COM 인터페이스와 같이,IDirect3DVertexBuffer8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DVERTEXBUFFER8 및 PDIRECT3DVERTEXBUFFER8 형은,IDirect3DVertexBuffer8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DVertexBuffer8 *LPDIRECT3DVERTEXBUFFER8, *PDIRECT3DVERTEXBUFFER8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CreateVertexBuffer


IDirect3DVertexBuffer8::GetDesc

버텍스 버퍼 리소스의 기술을 취득한다.

HRESULT GetDesc(
  D3DVERTEXBUFFER_DESC* pDesc
);

파라미터

pDesc
[out] 돌려주어지는 버텍스 버퍼가 기술되고 있는 D3DVERTEXBUFFER_DESC 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

이 인수가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DVertexBuffer8::Lock

버텍스 데이터의 범위를 잠그어, 버텍스 버퍼 메모리에의 포인터를 취득한다.

HRESULT Lock(
  UINT OffsetToLock,
  UINT SizeToLock,
  BYTE** ppbData,
  DWORD Flags
);

파라미터

OffsetToLock
[in] 잠그는 버텍스 데이터에의 오프셋(offset) (바이트 단위).
SizeToLock
[in] 잠그는 버텍스 데이터의 사이즈 (바이트 단위). 0 을 지정 하면, 버텍스 버퍼 전체가 락 된다.
ppbData
[out] 돌려주어지는 버텍스 데이터가 저장 되는 BYTE 값배열에의 포인터의 주소.
Flags
[in] 버텍스 버퍼 메모리를 잠그는 방법을 나타내는, 0 개 이상의 락킹 플래그의 편성.
D3DLOCK_DISCARD
어플리케이션은, 기입 전용 처리로 인덱스 버퍼 전체를 덧쓰기한다. 이것에 의해, Direct3D 는 새로운 메모리 영역에의 포인터를 돌려줄 수가 있으므로, 다이나믹 메모리 액세스 (DMA)와 낡은 영역으로부터의 렌더링이 기능 정지할 것은 없다. 「주의」를 참조할것.
D3DLOCK_NOOVERWRITE
프레임의 시작 이후, 또는 이 플래그가 지정되어 있지 않은 마지막 락 이후에 드로잉(Drawing) 처리의 호출 중(안)에서 참조된 버텍스는, 락중으로 변경되지 않는 것을 나타낸다. 버텍스 버퍼에게만 데이터를 추가하는 경우는, 이 플래그에 의해 처리를 최적화할 수 있다. 「주의」를 참조할것.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템의 크리티컬 섹션을 확보하는 것으로, 락중에 디스플레이 모드의 변경을 하지 않는 것을 보증한다. 이 플래그는, 시스템 와이드인 크리티컬 섹션이 락의 사이 보관 유지되지 않게 한다.

락 처리는 약간 부하가 높아지지만, 마우스 커서의 이동 등, 시스템으로 다른 처리를 실행하는 것이 가능하게 된다. 이 플래그는, 소프트웨어 렌더링의 백 버퍼의 락과 같이, 락이 장시간에 이르러, 시스템의 응답성에 악영향을 주어 버리는 것 같은 락에 대해서 유효하다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입을 실시하지 않는다. 이것에 의해, 얼마인가의 최적화가 실현된다. D3DLOCK_READONLY 는 D3DLOCK_DISCARD 와 함께 지정할 수 없다. 또, D3DUSAGE_WRITEONLY 로 생성 된 버텍스 버퍼로 지정하는 일도 할 수 없다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

버텍스 버퍼를 조작하는 경우, 복수의 락 호출을 실시할 수가 있다. 다만, 락 호출의 수와 언락 호출의 수는 일치하고 있지 않으면 안 된다. 현재 설정해 있는 버텍스 버퍼로 락 카운트가 남아 있는 경우, DrawPrimitive 의 호출은 실패한다.

D3DLOCK_DISCARD 및 D3DLOCK_NOOVERWRITE 플래그는, D3DUSAGE_DYNAMIC 로 생성 된 버퍼 에 대해서만 유효하다.

D3DLOCK_DISCARD 또는 D3DLOCK_NOOVERWRITE 를 Lock 메소드의 Flags 파라미터로 사용하는 방법에 대해서는, 「동적인 버텍스 및 인덱스 버퍼의 사용법」을 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVertexBuffer8::Unlock


IDirect3DVertexBuffer8::Unlock

버텍스 데이터를 언락 한다.

HRESULT Unlock();

파라미터

없음.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVertexBuffer8::Lock


IDirect3DVolume8

볼륨 리소스를 조작하려면 ,IDirect3DVolume8 인터페이스의 메소드를 사용한다.

IDirect3DVolume8 인터페이스를 취득하려면 ,IDirect3DVolumeTexture8::GetVolumeLevel 메소드를 호출한다.

IDirect3DVolume8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

디바이스 | GetDevice
정보 | GetContainer
 | GetDesc
락킹 볼륨 | LockBox
 | UnlockBox
프라이빗 볼륨 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData

모든 COM 인터페이스와 같이,IDirect3DVolume8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DVOLUME8 및 PDIRECT3DVOLUME8 형은,IDirect3DVolume8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DVolume8 *LPDIRECT3DVOLUME8, *PDIRECT3DVOLUME8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DVolume8::FreePrivateData

이 볼륨에 관련지을 수 있고 있는 지정된 프라이빗 데이터를 해방한다.

HRESULT FreePrivateData(
  REFGUID refguid
);

파라미터

refguid
[in] 해방하는 프라이빗 데이터를 식별하는 글로벌 유니크 식별자에의 참조 (C++) 또는 주소 (C).

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTFOUND

주의

Microsoft® Direct3D® 는, 볼륨이 해방되면(자) 자동적으로 이 메소드를 호출한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVolume8::GetPrivateData ,IDirect3DVolume8::SetPrivateData


IDirect3DVolume8::GetContainer

이 표면이 볼륨 텍스쳐의 아이 레벨인 경우, 부모의 볼륨 텍스쳐 오브젝트에의 액세스를 제공한다.

HRESULT GetContainer(
  REFIID riid,
  void** ppContainer
);

파라미터

riid
[in] 요구하는 볼륨의 참조 식별자.
ppContainer
[out, retval] 조회가 성공했을 경우에 컨테이너 포인터가 저장 되는 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DVolume8::GetDevice

볼륨에 관련지을 수 있고 있는 디바이스를 취득한다.

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
);

파라미터

ppDevice
[out, retval] 조회가 성공했을 경우에, 디바이스의 포인터가 저장 되는 IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드를 사용 하면, 소유하고 있는 디바이스 오브젝트로 이동할 수가 있다.

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DVolume8::GetPrivateData

볼륨에 관련지을 수 있었던 프라이빗 데이터가 제공된 버퍼에 카피한다.

HRESULT GetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD* pSizeOfData
);

파라미터

refguid
[in] 취득하는 프라이빗 데이터를 식별하는 글로벌 유니크 식별자에의 참조 (C++) 또는 주소 (C).
pData
[in, out] 호출이 성공했을 경우에, 요구한 프라이빗 데이터를 저장 하는 할당이 끝난 버퍼에의 포인터. 이 메소드를 호출하는 어플리케이션은, 이 버퍼의 할당과 해방에 책임을 진다.
pSizeOfData
[in, out] pData 의 버퍼 사이즈 (바이트 단위)에의 포인터. 이 값이 실제의 프라이빗 데이터의 사이즈보다 작은 (0 등) 경우, 메소드는 필요한 버퍼 사이즈를 이 파라미터로 설정해,D3DERR_MOREDATA 를 돌려준다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_MOREDATA
D3DERR_NOTFOUND

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVolume8::FreePrivateData ,IDirect3DVolume8::SetPrivateData


IDirect3DVolume8::GetDesc

볼륨의 기술을 취득한다.

HRESULT GetDesc(
  D3DVOLUME_DESC* pDesc
);

파라미터

pDesc
[out] 볼륨이 기술되고 있는 D3DVOLUME_DESC 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

이 인수가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DVolume8::LockBox

볼륨 리소스 위에의 박스를 잠근다.

HRESULT LockBox(
  D3DLOCKED_BOX* pLockedVolume,
  CONST D3DBOX* pBox,
  DWORD Flags
);

파라미터

pLockedVolume
[out] 락 된 영역을 기술하는 D3DLOCKED_BOX 구조체에의 포인터.
pBox
[in] 잠그는 박스에의 포인터. D3DBOX 구조체에의 포인터로 지정된다. 이 파라미터에 NULL 를 지정 하면, 볼륨 전체가 락 된다.
Flags
[in] 실행하는 락의 타입을 기술하는, 0 개 이상의 락킹 플래그의 편성.
D3DLOCK_NO_DIRTY_UPDATE
디폴트에서는, 리소스의 락은 더티 영역을 그 리소스에 추가한다. 이 플래그는, 리소스의 더티 상태에의 변경을 막는다. 어플리케이션에서는, 락 처리중으로 변경되는 실제의 볼륨 세트에 대한 추가 정보를 가지고 있는 경우는, 이 플래그를 사용해야 한다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템의 크리티컬 섹션을 확보하는 것으로, 락중에 디스플레이 모드의 변경을 하지 않는 것을 보증한다. 이 플래그는, 시스템 와이드인 크리티컬 섹션이 락의 사이 보관 유지되지 않게 한다.

락 처리는 약간 부하가 높아지지만, 마우스 커서의 이동 등, 시스템으로 다른 처리를 실행하는 것이 가능하게 된다. 이 플래그는, 소프트웨어 렌더링의 백 버퍼의 락과 같이, 락이 장시간에 이르러, 시스템의 응답성에 악영향을 주어 버리는 것 같은 락에 대해서 유효하다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입을 실시하지 않는다. 이것에 의해, 네이티브가 아닌 포맷으로 저장 된 리소스가, 언락시에 재압축 순서를 보존할 수 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

퍼포먼스의 이유에 의해, 더티인 범위는 텍스쳐의 레벨 제로에 대해서 기록될 뿐이다. D3DLOCK_NO_DIRTY_UPDATE 또는 D3DLOCK_READONLY 없음으로 LockRect 나 LockBox 가 불려 갔을 때, 더티인 범위는 자동적으로 기록된다. 상세한 것에 대하여는, 「IDirect3DDevice8::UpdateTexture」를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVolume8::UnlockBox


IDirect3DVolume8::SetPrivateData

Microsoft® Direct3D® 는 아니고, 어플리케이션에서의 사용이 의도되고 있는 볼륨과 데이터를 관련짓는다.

HRESULT SetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD SizeOfData,
  DWORD Flags
);

파라미터

refguid
[in] 설정하는 프라이빗 데이터를 식별하는 글로벌 유니크 식별자에의 참조 (C++) 또는 주소 (C).
pData
[in] 볼륨과 관련짓는 데이터가 저장 되고 있는 버퍼에의 포인터.
SizeOfData
[in] pData 의 버퍼 사이즈 (바이트 단위).
Flags
[in] 건네받는 데이터형을 기술하는 값, 또는 리소스가 변경되었을 경우에 데이터를 무효로 할 필요가 있는 것을 어플리케이션에 나타내는 값.
(none)
플래그를 지정하지 않는 경우, Direct3D 는 버퍼내의 데이터를 보관 유지하는 메모리를 할당해 새로운 버퍼에 데이터를 카피한다. Direct3D 에 의해 할당할 수 있는 버퍼는, 적당 자동적으로 해방된다.
D3DSPD_IUNKNOWN
pData 의 데이터는 IUnknown 인터페이스에의 포인터이다. SizeOfData 는,IUnknown 인터페이스 (sizeof(IUnknown*))에의 포인터의 사이즈로 설정할 필요가 있다. Direct3D 는 pData 를 개입시켜 IUnknown::AddRef 를, 프라이빗 데이터가 파기되는 경우는 IUnknown::Release 를 자동적으로 호출한다. 다음에 같은 GUID 로 SetPrivateData 을 호출하면, 또는 다음에 IDirect3DVolume8::FreePrivateData 를 호출하면, 또는 Direct3D8 오브젝트가 해방되면(자), 프라이빗 데이터는 파기된다. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

Direct3D 는 pData 로 메모리를 관리하지 않는다. 이 버퍼가 동적으로 할당할 수 있었을 경우는, 호출측의 책임으로 메모리를 해방한다.

데이터는 값으로 건네받아 복수의 데이터 세트를 단일의 볼륨과 관련지을 수가 있다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVolume8::FreePrivateData ,IDirect3DVolume8::GetPrivateData


IDirect3DVolume8::UnlockBox

볼륨 리소스 위에의 박스를 언락 한다.

HRESULT UnlockBox();

파라미터

없음.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVolume8::LockBox


IDirect3DVolumeTexture8

볼륨 텍스쳐 리소스를 조작하려면 ,IDirect3DVolumeTexture8 인터페이스의 메소드를 사용한다.

IDirect3DVolumeTexture8 인터페이스를 취득하려면 ,IDirect3DDevice8::CreateVolumeTexture 메소드를 호출한다.

IDirect3DVolumeTexture8 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirect3DResource8 메소드를 계승한다.

디바이스 | GetDevice
정보 | GetType
프라이빗 표면 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData
리소스 관리 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DVolumeTexture8 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirect3DBaseTexture8 메소드를 계승한다.

상세 | GetLOD
 | SetLOD
정보 | GetLevelCount

IDirect3DVolumeTexture8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetLevelDesc
락킹 볼륨 | LockBox
 | UnlockBox
그 외 | AddDirtyBox
 | GetVolumeLevel

모든 COM 인터페이스와 같이,IDirect3DVolumeTexture8 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DVOLUMETEXTURE8 및 PDIRECT3DVOLUMETEXTURE8 형은,IDirect3DVolumeTexture8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DVolumeTexture8 *LPDIRECT3DVOLUMETEXTURE8, *PDIRECT3DVOLUMETEXTURE8;

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DDevice8::CreateVolumeTexture


IDirect3DVolumeTexture8::AddDirtyBox

볼륨 텍스쳐 리소스에 더티 영역을 추가한다.

HRESULT AddDirtyBox(
  CONST D3DBOX* pDirtyBox
);

파라미터

pDirtyBox
[in] D3DBOX 구조체에의 포인터. 추가하는 더티 영역을 지정한다. NULL 를 지정 하면, 더티 영역이 확대해 볼륨 텍스쳐 전체를 가린다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

리소스의 더티 영역을 지정하는 것으로, 카피되는 리소스의 서브 세트를 최적화할 수 있다. 다만, 더티 영역은 아라이먼트를 최적화하기 위해서 확대되는 일이 있다.

퍼포먼스의 이유에 의해, 더티인 범위는 텍스쳐의 레벨 제로에 대해서 기록될 뿐이다. 서브 레벨에 대해서는, 대응하는 (스케일 된 ) 직사각형 또는 박스도 더티이라고 가정된다. D3DLOCK_NO_DIRTY_UPDATE 또는 D3DLOCK_READONLY 없음으로 LockRect 나 LockBox 가 불려 갔을 때, 더티인 범위는 자동적으로 기록된다. 또 CopyRects 호출의 행선지 서페이스는 더티로서 마크 된다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DVolumeTexture8::GetLevelDesc

볼륨 텍스쳐 표면의 레벨 기술을 취득한다.

HRESULT GetLevelDesc(
  UINT Level,
  D3DVOLUME_DESC* pDesc
);

파라미터

Level
[in] 볼륨 텍스쳐 리소스의 레벨을 식별한다. 이 메소드는, 이 파라미터로 지정된 레벨에 대한 볼륨의 기술을 돌려준다.
pDesc
[out] 돌려주어지는 볼륨 텍스쳐 레벨이 기술되고 있는 D3DVOLUME_DESC 구조체에의 포인터.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

인수의 1 개 이상이 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DVolumeTexture8::GetVolumeLevel

지정된 볼륨 텍스쳐 레벨을 취득한다.

HRESULT GetVolumeLevel(
  UINT Level,
  IDirect3DVolume8** ppVolumeLevel
);

파라미터

Level
[in] 볼륨 텍스쳐 리소스의 레벨을 식별한다. 이 메소드는, 이 파라미터로 지정된 레벨에 대한 볼륨을 돌려준다.
ppVolumeLevel
[out, retval] 돌려주어지는 볼륨 레벨을 나타내는 IDirect3DVolume8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DVolume8 인터페이스에 대한 내부 참조 카운트가 증가한다. 이 IDirect3DVolume8 인터페이스의 사용을 종료했을 때에 IUnknown::Release 의 호출이 실패 하면, 메모리 누수가 발생한다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


IDirect3DVolumeTexture8::LockBox

볼륨 텍스쳐 리소스 위에의 박스를 잠근다.

HRESULT LockBox(
  UINT Level,
  D3DLOCKED_BOX* pLockedVolume,
  CONST D3DBOX* pBox,
  DWORD Flags
);

파라미터

Level
[in] 잠그는 볼륨 텍스쳐 리소스의 레벨을 지정한다.
pLockedVolume
[out] 락 된 영역을 기술하는 D3DLOCKED_BOX 구조체에의 포인터.
pBox
[in] 잠그는 볼륨에의 포인터. 이 파라미터는,D3DBOX 구조체에의 포인터로 지정된다. 이 파라미터에 NULL 를 지정 하면, 볼륨 레벨 전체가 락 된다.
Flags
[in] 실행하는 락의 타입을 기술하는, 0 개 이상의 락킹 플래그의 편성.
D3DLOCK_NO_DIRTY_UPDATE
디폴트에서는, 리소스의 락은 더티 영역을 그 리소스에 추가한다. 이 플래그는, 리소스의 더티 상태에의 변경을 막는다. 어플리케이션은, 락 처리동안으로 변경되는 실제의 볼륨 세트에 대한 추가 정보를 보관 유지하고 있어, 그 정보를 IDirect3DVolumeTexture8::AddDirtyBox 에 건네줄 수가 있을 때는, 이 플래그를 사용해야 한다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템의 크리티컬 섹션을 확보하는 것으로, 락중에 디스플레이 모드의 변경을 하지 않는 것을 보증한다. 이 플래그는, 시스템 와이드인 크리티컬 섹션이 락의 사이 보관 유지되지 않게 한다.

락 처리는 약간 부하가 높아지지만, 마우스 커서의 이동 등, 시스템으로 다른 처리를 실행하는 것이 가능하게 된다. 이 플래그는, 소프트웨어 렌더링의 백 버퍼의 락과 같이, 락이 장시간에 이르러, 시스템의 응답성에 악영향을 주어 버리는 것 같은 락에 대해서 유효하다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입을 실시하지 않는다. 이것에 의해, 네이티브가 아닌 포맷으로 저장 된 리소스가, 언락시에 재압축 순서를 보존할 수 있다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

퍼포먼스의 이유에 의해, 더티인 범위는 텍스쳐의 레벨 제로에 대해서 기록될 뿐이다. D3DLOCK_NO_DIRTY_UPDATE 또는 D3DLOCK_READONLY 없음으로 LockRect 나 LockBox 가 불려 갔을 때, 더티인 범위는 자동적으로 기록된다. 상세한 것에 대하여는, 「IDirect3DDevice8::UpdateTexture」를 참조할것.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVolumeTexture8::UnlockBox


IDirect3DVolumeTexture8::UnlockBox

볼륨 텍스쳐 리소스 위에의 박스를 언락 한다.

HRESULT UnlockBox(
  UINT Level
);

파라미터

Level
[in] 언락 하는 볼륨 텍스쳐 리소스의 레벨을 지정한다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.

참조

IDirect3DVolumeTexture8::LockBox


함수

여기에서는, Microsoft® Direct3D® 를 사용하는 경우에 사용할 필요가 있는 함수의 레퍼런스 정보를 기술한다. 다음의 함수가 이행 되고 있다.

  • Direct3DCreate8


Direct3DCreate8

Direct3D8 오브젝트의 인스턴스를 생성 한다.

IDirect3D8* Direct3DCreate8(
  UINT SDKVersion
);

파라미터

SDKVersion
이 파라미터의 값은 D3D_SDK_VERSION 가 아니면 안된다. 「주의」를 참조할것.

반환값

성공했을 경우는,IDirect3D8 인터페이스에의 포인터를 돌려준다. 그 이외의 경우는, NULL 포인터를 돌려준다.

주의

이 함수는, 열거를 지원 하는 Direct3D8 오브젝트를 생성 한다. 또, 이 함수를 사용해 Direct3DDevice8 오브젝트를 생성 할 수 있다.

어플리케이션이 올바른 헤더 파일에 대해서 빌드 되고 있는 것을 확인하기 위해(때문에),Direct3DCreate8 에는 D3D_SDK_VERSION 식별자를 건네준다. 헤더 또는 다른 변경에 의해 어플리케이션의 리빌드가 필요하게 될 때마다, 이 값은 인크리먼트(increment) 된다. 버젼이 일치하지 않는 경우,Direct3DCreate8 는 실패한다.

이 함수를 호출하면, 현재의 액티브 디스플레이 어댑터 세트가 샘플링 된다. 데스크탑에 디바이스를 추가하거나 랩탑을 핫 도킹 해, 동적으로 어댑터를 추가했을 경우, 이 Direct3D8 오브젝트의 유효기간의 사이, 그러한 디바이스는 열거되지 않는다. 새로운 Direct3D8 오브젝트를 생성 하면, 새로운 디바이스가 공개된다.

동작환경

헤더 : D3d8.h 로 선언.
임포트 라이브러리 : D3d8.lib 를 사용.


매크로

여기에서는, Microsoft® Direct3D® 가 제공하는 매크로의 레퍼런스 정보를 기술한다.

  • D3DCLIPPLANEn
  • D3DCOLOR_ARGB
  • D3DCOLOR_COLORVALUE
  • D3DCOLOR_RGBA
  • D3DCOLOR_XRGB
  • D3DFVF_TEXCOORDSIZEn
  • D3DTS_WORLD
  • D3DTS_WORLDn
  • D3DTS_WORLDMATRIX


D3DCLIPPLANEn

유저 정의 클립면을 유효하게 하는 비트 패턴을 정의한다. 이러한 매크로는, D3DRS_CLIPPLANEENABLE 렌더링 스테이트값의 설정을 간소화하기 위해서 정의되고 있다.

D3DCLIPPLANE0 (1 << 0)
D3DCLIPPLANE1 (1 << 1)
D3DCLIPPLANE2 (1 << 2)
D3DCLIPPLANE3 (1 << 3)
D3DCLIPPLANE4 (1 << 4)
D3DCLIPPLANE5 (1 << 5)

파라미터

없음.

주의

유저 정의 클립면은, D3DRS_CLIPPLANEENABLE 렌더링 스테이트로 설정되는 DWORD 값으로 1 개 이상의 비트가 설정되어 있는 (즉 0 이 아니다) 경우에 유효하게 된다. 렌더링 스테이트값의 DWORD 에 중요성은 없고, 시스템은 그 값을 번호로서 해석하지 않는다. 그 대신해,DWORD 를 해석해, 대응하는 비트가 설정되어 있는 클립면을 유효하게 한다. 비트 0 은 최초의 클립면 (인덱스 0)을 제어해, 비트 1 은 2 번째의 평면을 제어한다, 와 같이 각 클립면이 제어된다.

이러한 매크로로 생성 하는 비트 패턴은, 논리합연산자로 결합하는 것으로, 동시에 복수의 클립면을 유효하게 할 수 있다. 이 편성으로부터 매크로의 어느쪽이든을 생략하는 것만으로, 그 인덱스의 클립면을 간단하게 무효로 할 수 있다.

동작환경

헤더 : D3d8types.h 로 선언.


D3DCOLOR_ARGB

지정된 알파, 적, 록, 및 파랑의 각 값으로, 색을 초기화한다.

D3DCOLOR_ARGB(a, r, g, b) \
    ((D3DCOLOR)((((a) &0xff) <<24)|(((r) &0xff) <<16)|(((g) &0xff) <<8)|((b) &0xff)))

파라미터

a, r, g, 및 b
색의 알파 (alpha), 적 (red), 록 (green), 및 파랑 (blue)의 성분. 이러한 값의 범위는, 0 ~ 255 가 아니면 안된다.

반환값

지정된 ARGB 값에 대응하는 D3DCOLOR 값을 돌려준다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DCOLOR_RGBA ,D3DCOLOR_XRGB


D3DCOLOR_COLORVALUE

지정된 적, 록, 청, 및 알파의 각 부동 소수점값으로, 색을 초기화한다.

D3DCOLOR_COLORVALUE(r, g, b, a) \
    D3DCOLOR_RGBA((DWORD)((r)*255. f), (DWORD)((g)*255. f), (DWORD)((b)*255. f), (DWORD)((a)*255. f))

파라미터

r, g, b, 및 a
색의 적 (red), 록 (green), 청 (blue), 및 알파 (alpha)의 성분. 이러한 값은 0.0 에서 1.0 의 범위에 있는 부동 소수점값이 아니면 안된다.

반환값

지정된 RGBA 값에 대응하는 D3DCOLOR 값을 돌려준다.

동작환경

헤더 : D3d8types.h 로 선언.


D3DCOLOR_RGBA

지정된 적, 록, 청, 및 알파의 각 값으로, 색을 초기화한다.

D3DCOLOR_RGBA(r, g, b, a) D3DCOLOR_ARGB(a, r, g, b)

파라미터

r, g, b, 및 a
색의 적 (red), 록 (green), 청 (blue), 및 알파 (alpha)의 성분. 이러한 값의 범위는, 0 ~ 255 가 아니면 안된다.

반환값

지정된 RGBA 값에 대응하는 D3DCOLOR 값을 돌려준다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DCOLOR_ARGB ,D3DCOLOR_XRGB


D3DCOLOR_XRGB

지정된 적, 초록, 및 파랑의 각 값으로, 색을 초기화한다.

D3DCOLOR_XRGB(r, g, b) D3DCOLOR_ARGB(0xff, r, g, b)

파라미터

r, g, 및 b
색의 적 (red), 초록 (green), 및 파랑 (blue)의 성분. 이러한 값의 범위는, 0 ~ 255 가 아니면 안된다.

반환값

지정된 RGB 값에 대응하는 D3DCOLOR 값을 돌려준다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DCOLOR_ARGB ,D3DCOLOR_RGBA


D3DFVF_TEXCOORDSIZEn

유연한 버텍스 포맷의 기술내에서 텍스쳐 좌표 포맷의 식별로 사용되는 비트 패턴을 생성 한다. 이 매크로의 결과는,논리합연산자를 사용해 유연한 버텍스 포맷내에서 결합할 수 있다.

D3DFVF_TEXCOORDSIZE1(CoordIndex) (D3DFVF_TEXTUREFORMAT1 << (CoordIndex*2 + 16))
D3DFVF_TEXCOORDSIZE2(CoordIndex) (D3DFVF_TEXTUREFORMAT2)
D3DFVF_TEXCOORDSIZE3(CoordIndex) (D3DFVF_TEXTUREFORMAT3 << (CoordIndex*2 + 16))
D3DFVF_TEXCOORDSIZE4(CoordIndex) (D3DFVF_TEXTUREFORMAT4 << (CoordIndex*2 + 16))

파라미터

CoordIndex
텍스쳐 좌표 사이즈 (1, 2, 3, 또는 4 차원)가 적용되는 텍스쳐 좌표 세트를 식별하는 값.

주의

D3DFVF_TEXCOORDSIZEn 매크로에서는, 다음의 정수가 사용된다.

#define D3DFVF_TEXTUREFORMAT1 3         // 1 개의 부동 소수점값
#define D3DFVF_TEXTUREFORMAT2 0         // 2 개의 부동 소수점값
#define D3DFVF_TEXTUREFORMAT3 1         // 3 개의 부동 소수점값
#define D3DFVF_TEXTUREFORMAT4 2         // 4 개의 부동 소수점값

이하의 유연한 버텍스 포맷의 기술은, 위치, 법선, 디퓨즈색, 스펙큐러색, 및 2 개의 텍스쳐 좌표 세트를 가지는 버텍스 포맷을 나타내고 있다. 1 번째의 텍스쳐 좌표 세트에는 단일의 요소가 포함되어 2 번째세트에는 2 개의 요소가 포함된다.

DWORD dwFVF = D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE |
              D3DFVF_SPECULAR | D3DFVF_TEX2 |
              D3DFVF_TEXCOORDSIZE1(0) |  \\ Uses 1-D texture coordinates for
                                         \\ texture coordinate set 1 (index 0).
              D3DFVF_TEXCOORDSIZE2(1);   \\ And 2-D texture coordinates for
                                         \\ texture coordinate set 2 (index 1).

동작환경

헤더 : D3d8types.h 로 선언.

참조

유연한 버텍스 포맷 플래그


D3DTS_WORLD

월드 트랜스 폼 행렬로서 설정되는 트랜스 폼 행렬을 식별한다.

D3DTS_WORLD  D3DTS_WORLDMATRIX(0)

파라미터

없음.

주의

이 매크로는, 기존 어플리케이션의 Microsoft® DirectX® 8.0 에의 이식을 용이하게 하기 위해서 제공되고 있다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::SetTransform ,D3DTS_WORLDMATRIX


D3DTS_WORLDn

버텍스 포맷으로 지정된 대응하는 행렬 및 블렌딩 (베타) 가중값을 이용하는 버텍스 블렌딩에 사용된다, 이후의 트랜스 폼 행렬을 식별한다.

D3DTS_WORLD1 D3DTS_WORLDMATRIX(1)
D3DTS_WORLD2 D3DTS_WORLDMATRIX(2)
D3DTS_WORLD3 D3DTS_WORLDMATRIX(3)

파라미터

없음.

주의

이러한 매크로는, 기존 어플리케이션의 Microsoft® DirectX® 8.0 에의 이식을 용이하게 하기 위해서 제공되고 있다.

동작환경

헤더 : D3d8types.h 으로 선언.

참조

IDirect3DDevice8::SetTransform ,D3DTS_WORLDMATRIX


D3DTS_WORLDMATRIX

0 ~ 255 의 범위의 인덱스를 대응하는 트랜스 폼 스테이트에 맵 한다.

D3DTS_WORLDMATRIX(index) (D3DTRANSFORMSTATETYPE)(index + 256)

파라미터

index
0 ~ 255 의 범위의 인덱스값.

주의

256 ~ 511 의 범위의 트랜스 폼 스테이트는, 8 비트의 인덱스를 사용해 인덱스 지정할 수 있는 최대 256 개의 행렬을 저장 하기 위해서 확보되고 있다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::SetTransform


버텍스 쉐이더 선언자 매크로

여기에서는, 버텍스 쉐이더 선언자의 DWORD 배열을 생성 하기 위해서 사용되는 비트 어셈블리 매크로에 대해 설명한다.

  • D3DVSD_CONST
  • D3DVSD_END
  • D3DVSD_NOP
  • D3DVSD_REG
  • D3DVSD_SKIP
  • D3DVSD_STREAM
  • D3DVSD_STREAM_TESS
  • D3DVSD_TESSNORMAL
  • D3DVSD_TESSUV


D3DVSD_CONST

버텍스 쉐이더 정수 메모리에 데이터를 로드한다.

D3DVSD_CONST( _ConstantAddress, _Count ) \
            (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_CONSTMEM) | \
            ((_Count) << D3DVSD_CONSTCOUNTSHIFT) | (_ConstantAddress))

파라미터

_ConstantAddress
데이터의 저장을 시작 하는 정수 배열의 주소. 지정 가능한 값의 범위는, 0 ~ 95 이다.
_Count
각 데이터에 대해 4 DWORD 와 거기에 계속되어 4*_Count DWORD 를 로드하는 정수 벡터의 수. 「주의」를 참조할것.

주의

다음의 샘플 코드는, 이 매크로의 사용법을 나타내고 있다.

D3DVALUE diffuse[] = {1, 1, 1.0f/255. 0f, 1};
        DWORD decl[] =
        {
            D3DVSD_CONST(8, 1),
            *(DWORD*) &diffuse[0],
            *(DWORD*) &diffuse[1],
            *(DWORD*) &diffuse[2],
            *(DWORD*) &diffuse[3],
            D3DVSD_STREAM(0),
            D3DVSD_REG( 0, D3DVSDT_FLOAT3),
            D3DVSD_REG( 2, D3DVSDT_D3DCOLOR),
            D3DVSD_STREAM(1),
            D3DVSD_REG( 1, D3DVSDT_FLOAT1),
            D3DVSD_STREAM(2),
            D3DVSD_REG( 3, D3DVSDT_FLOAT2),
            D3DVSD_END()
        };

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateVertexShader


D3DVSD_END

END 토큰을 생성한다.

#define D3DVSD_END()

파라미터

없음.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateVertexShader


D3DVSD_NOP

NOP 토큰을 생성한다.

#define D3DVSD_NOP()

파라미터

없음.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateVertexShader


D3DVSD_REG

단일의 버텍스 레지스터를 버텍스 스트림으로부터의 버텍스 요소에 바인드 한다.

D3DVSD_REG( _VertexRegister, _Type ) \
          (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAMDATA) | \
          ((_Type) << D3DVSD_DATATYPESHIFT) | (_VertexRegister))

파라미터

_VertexRegister
버텍스 레지스터의 주소. 지정 가능한 값의 범위는, 0 ~ 15 이다. 고정 기능 파이프라인의 경우, 입력 레지스터는 이하의 고정 매핑을 갖추고 있다.
D3DVSDE_POSITION
레지스터 0.
D3DVSDE_BLENDWEIGHT
레지스터 1.
D3DVSDE_NORMAL
레지스터 2.
D3DVSDE_PSIZE
레지스터 3.
D3DVSDE_DIFFUSE
레지스터 4.
D3DVSDE_SPECULAR
레지스터 5.
D3DVSDE_TEXCOORD0
레지스터 6.
D3DVSDE_TEXCOORD1
레지스터 7.
D3DVSDE_TEXCOORD2
레지스터 8.
D3DVSDE_TEXCOORD3
레지스터 9.
D3DVSDE_TEXCOORD4
레지스터 10.
D3DVSDE_TEXCOORD5
레지스터 11.
D3DVSDE_TEXCOORD6
레지스터 12.
D3DVSDE_TEXCOORD7
레지스터 13.
_Type
치수 및 산술 데이터형을 지정한다. 이하의 값이 정의되고 있다.
D3DVSDT_D3DCOLOR
0.0 ~ 1.0 의 범위에 맵 되는 4D 의 팩 된 부호 없음 바이트. 더블 워드 형식에서는, 이것은 ARGB 이며, 바이트 오더에서는, B, G, R, A 이다.
D3DVSDT_FLOAT1
(value, 0.0, 0.0, 1.0)에 전개되는 1D float.
D3DVSDT_FLOAT2
(value, value, 0.0, 1.0)에 전개되는 2D float.
D3DVSDT_FLOAT3
(value, value, value, 1.0)에 전개되는 3D float.
D3DVSDT_FLOAT4
4D float.
D3DVSDT_UBYTE4
4D 부호 없음 바이트. 더블 워드 형식에서는, 이것은 ABGR 이며, 바이트 오더에서는, R, G, B, A 이다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateVertexShader


D3DVSD_SKIP

버텍스내에서 스킵 하는 DWORD 의 수를 지정한다.

D3DVSD_SKIP( _DWORDCount ) \
           (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAMDATA) | 0x10000000 | \
           ((_DWORDCount) << D3DVSD_SKIPCOUNTSHIFT))

파라미터

_DWORDCount
버텍스내에서 스킵 하는 DWORD 의 수.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateVertexShader


D3DVSD_STREAM

경향 스트림을 설정한다.

D3DVSD_STREAM( _StreamNumber ) \
             (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAM) | (_StreamNumber))

파라미터

_StreamNumber
데이터의 취득원의 스트림을 지정한다. 지정 가능한 값의 범위는, 0 ~ dwMaxStreams 로부터 1 당긴 값이다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateVertexShader


D3DVSD_STREAM_TESS

테셀레이트 스트림을 설정한다.

D3DVSD_STREAM_TESS( ) \
      (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAM) | (D3DVSD_STREAMTESSMASK))

파라미터

없음.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateVertexShader


D3DVSD_TESSNORMAL

테셀레이트로 생성되는 법선을 유효하게 한다.

D3DVSD_TESSNORMAL( _VertexRegisterIn, _VertexRegisterOut ) \
                 (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_TESSELLATOR) | \
                 ((_VertexRegisterIn) << D3DVSD_VERTEXREGINSHIFT) | \
                 ((0x02) << D3DVSD_DATATYPESHIFT) | (_VertexRegisterOut))

파라미터

_VertexRegisterIn
입력 스트림이 법선의 계산에 사용되는 버텍스 레지스터의 주소. 지정 가능한 값의 범위는, 0 ~ 15 이다.
_VertexRegisterOut
법선을 출력하는 버텍스 레지스터의 주소. 지정 가능한 값의 범위는, 0 ~ 15 이다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateVertexShader


D3DVSD_TESSUV

테셀레이트로 생성되는 표면 파라미터를 유효하게 한다.

D3DVSD_TESSUV( _VertexRegister ) \
             (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_TESSELLATOR) | 0x10000000 | \
             ((0x01) << D3DVSD_DATATYPESHIFT) | (_VertexRegister))

파라미터

_VertexRegister
파라미터를 출력하는 버텍스 레지스터의 주소. 지정 가능한 값의 범위는, 0 ~ 15 이다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateVertexShader


구조체

여기에서는, Microsoft® Direct3D® 로 사용하는 이하의 구조체에 대해 설명한다.

  • D3DADAPTER_IDENTIFIER8
  • D3DBOX
  • D3DCAPS8
  • D3DCLIPSTATUS8
  • D3DCOLORVALUE
  • D3DDEVICE_CREATION_PARAMETERS
  • D3DDISPLAYMODE
  • D3DGAMMARAMP
  • D3DINDEXBUFFER_DESC
  • D3DLIGHT8
  • D3DLINEPATTERN
  • D3DLOCKED_BOX
  • D3DLOCKED_RECT
  • D3DMATERIAL8
  • D3DMATRIX
  • D3DPRESENT_PARAMETERS
  • D3DRANGE
  • D3DRASTER_STATUS
  • D3DRECT
  • D3DRECTPATCH_INFO
  • D3DSURFACE_DESC
  • D3DTRIPATCH_INFO
  • D3DVECTOR
  • D3DVERTEXBUFFER_DESC
  • D3DVIEWPORT8
  • D3DVOLUME_DESC


D3DADAPTER_IDENTIFIER8

어댑터에 대한 정보를 보관 유지한다.

typedef struct _D3DADAPTER_IDENTIFIER8 {
    char            Driver[MAX_DEVICE_IDENTIFIER_STRING];
    char            Description[MAX_DEVICE_IDENTIFIER_STRING];

#ifdef _WIN32
    LARGE_INTEGER   DriverVersion;            /* 32 비트 컴퍼넌트용으로 정의된다 */
#else
    DWORD           DriverVersionLowPart;     /* 16 비트 컴퍼넌트용으로 정의된다 */
    DWORD           DriverVersionHighPart;
#endif

    DWORD           VendorId;
    DWORD           DeviceId;
    DWORD           SubSysId;
    DWORD           Revision;

    GUID            DeviceIdentifier;

    DWORD           WHQLLevel;
} D3DADAPTER_IDENTIFIER8;

멤버

Driver 및 Description
유저에게 제시하기 위해서 사용된다. 벤더가 다른 같은 디바이스 및 드라이버에 대해서 많은 다른 캐릭터 라인을 관련지을 수 있고 있을 가능성이 있기 (위해)때문에, 특정의 드라이버를 식별하기 위해서 이러한 값을 사용해서는 안된다.
DriverVersion, DriverVersionLowPart, 및 DriverVersionHighPart
Microsoft® Direct3D® 드라이버의 버젼을 식별한다. 64 비트의 부호 첨부 정수값으로서 대소 비교를 실시해도 문제는 없다. 다만, 이 요소를 사용해 의심스러운 드라이버를 식별하는 경우는, 주의해 실시하는 것. 이 값은 아니고,DeviceIdentifier 를 사용하는 것이 바람직하다.

다음의 유사 코드의 예는, 이 멤버에 encode 되는 버젼의 포맷을 나타낸 것이다.

Product = HIWORD(DriverVersion.HighPart)
Version = LOWORD(DriverVersion.HighPart)
SubVersion = HIWORD(DriverVersion.LowPart)
Build = LOWORD(DriverVersion.LowPart)

HIWORD 매크로,LOWORD 매크로, 및 LARGE_INTEGER 구조체의 상세한 것에 대하여는, Microsoft Platform Software Development Kit (SDK)를 참조할것.

VendorId
특정의 칩 세트의 식별로 사용할 수 있다. 메이커를 식별하려면 , 이 멤버를 조사한다. 불명한 경우, 이 값은 0 이 되는 경우가 있다.
DeviceId
특정의 칩 세트의 식별로 사용할 수 있다. 칩 세트의 종류를 식별하려면 , 이 멤버를 조사한다. 불명한 경우, 이 값은 0 이 되는 경우가 있다.
SubSysId
특정의 칩 세트의 식별로 사용할 수 있다. 서브 시스템을 식별하려면 , 이 멤버를 조사한다. 일반적으로, 서브 시스템과는 특정의 보드를 가리킨다. 불명한 경우, 이 값은 0 이 되는 경우가 있다.
Revision
특정의 칩 세트의 식별로 사용할 수 있다. 칩 세트의 리버젼 레벨을 식별하려면 , 이 멤버를 조사한다. 불명한 경우, 이 값은 0 이 되는 경우가 있다.
DeviceIdentifier
이 멤버를 조사하면(자), 드라이버 및 칩 세트의 변경을 확인할 수 있다. GUID 는, 드라이버와 칩 세트의 페어에 대한 일의인 식별자이다. 드라이버 및 칩 세트에의 변경을 추적해, 그래픽스 서브시스템 의 새로운 프로파일을 생성 하는 경우는, 이 멤버를 참조한다. 이 멤버는, 특정의 의심스러운 드라이버를 식별하기 위해서도 사용할 수 있다.
WHQLLevel
이 디바이스와 드라이버의 페어의 Windows Hardware Quality Lab (WHQL) 인증 레벨을 특정하기 위해서 사용한다. DWORD 에는 팩 형식의 데이터 구조가 저장 되고 있어 드라이버가 합격한 최신의 WHQL 테스트의 릴리스일이 정의되고 있다. 이 값에 대해서 대소 비교 연산을 실행해도 문제는 없다. 다음은 일자의 포맷이다.
Bits
31-16:    The year, a decimal number from 1999 upwards.
15-8:     The month, a decimal number from 1 to 12.
7-0:      The day, a decimal number from 1 to 31.

다음의 값도 사용된다.

0
인증되어 있지 않다.
1
WHQL 의 인증은 받고 있지만, 이용할 수 있는 일자 정보는 없다.

주의

정수 MAX_DEVICE_IDENTIFIER_STRING 는, 다음과 같이 정의되고 있다.

#define MAX_DEVICE_IDENTIFIER_STRING        512

VendorId,DeviceId,SubSysId, 및 Revision 의 각 멤버를 조합해 사용하는 것으로, 특정의 칩 세트를 식별할 수 있다. 다만, 이러한 멤버를 사용할 때는 주의가 필요하다.

동작환경

헤더 : D3d8types.h 로 선언.


D3DBOX

볼륨을 정의한다.

typedef struct _D3DBOX {
    UINT                Left;
    UINT                Top;
    UINT                Right;
    UINT                Bottom;
    UINT                Front;
    UINT                Back;
} D3DBOX;

멤버

Left, Top, Right, Bottom, Front, 및 Back
박스의 넓이.

주의

D3DBOX 에는 좌측면, 표면, 및 전면의 엣지는 포함되지만, 우측면, 저면, 및 배면의 엣지는 포함되지 않는다. 예를 들어, 100 단위의 폭으로 0 으로부터 시작되는 박스 (즉, 최대 99 까지의 포인트를 포함한다)는, 0 이라고 하는 값의 Left 멤버와 100 이라고 하는 값의 Right 멤버로 나타내진다. Right 멤버의 값이 99 는 아닌 것에 주의 해야 한다.

D3DBOX 로 나타나는 면의 순서의 규칙은, 왼쪽에서 오른쪽, 위에서 아래, 및 전부터 다음에 있다.

동작환경

헤더 : D3d8types.h 로 선언.


D3DCAPS8

Microsoft® Direct3D® 오브젝트가 공개하는 하드웨어의 능력을 나타낸다.

typedef struct _D3DCAPS8 {
    D3DDEVTYPE          DeviceType;
    UINT                AdapterOrdinal;

    DWORD               Caps;
    DWORD               Caps2;
    DWORD               Caps3;
    DWORD               PresentationIntervals;

    DWORD               CursorCaps;

    DWORD               DevCaps;

    DWORD               PrimitiveMiscCaps;
    DWORD               RasterCaps;
    DWORD               ZCmpCaps;
    DWORD               SrcBlendCaps;
    DWORD               DestBlendCaps;
    DWORD               AlphaCmpCaps;
    DWORD               ShadeCaps;
    DWORD               TextureCaps;
    DWORD               TextureFilterCaps;
    DWORD               CubeTextureFilterCaps;
    DWORD               VolumeTextureFilterCaps;
    DWORD               TextureAddressCaps;
    DWORD               VolumeTextureAddressCaps;

    DWORD               LineCaps;

    DWORD               MaxTextureWidth, MaxTextureHeight;
    DWORD               MaxVolumeExtent;

    DWORD               MaxTextureRepeat;
    DWORD               MaxTextureAspectRatio;
    DWORD               MaxAnisotropy;
    float               MaxVertexW;

    float               GuardBandLeft;
    float               GuardBandTop;
    float               GuardBandRight;
    float               GuardBandBottom;

    float               ExtentsAdjust;
    DWORD               StencilCaps;

    DWORD               FVFCaps;
    DWORD               TextureOpCaps;
    DWORD               MaxTextureBlendStages;
    DWORD               MaxSimultaneousTextures;

    DWORD               VertexProcessingCaps;
    DWORD               MaxActiveLights;
    DWORD               MaxUserClipPlanes;
    DWORD               MaxVertexBlendMatrices;
    DWORD               MaxVertexBlendMatrixIndex;

    float               MaxPointSize;

    DWORD               MaxPrimitiveCount;
    DWORD               MaxVertexIndex;
    DWORD               MaxStreams;
    DWORD               MaxStreamStride;

    DWORD               VertexShaderVersion;
    DWORD               MaxVertexShaderConst;

    DWORD               PixelShaderVersion;
    float               MaxPixelShaderValue;
} D3DCAPS8;

멤버

DeviceType
D3DDEVTYPE 열거형의 멤버. 이 Direct3DDevice 오브젝트가 생성 된 대상의 디바이스의 타입.
AdapterOrdinal
이 Direct3DDevice 오브젝트가 생성 된 어댑터. 이 서수는, 이 Direct3DDevice 오브젝트를 생성 한 IDirect3D8 인터페이스의 메소드에 건네주는 경우에게만 유효하다. IDirect3D8 인터페이스는, 항상,IDirect3DDevice8::GetDirect3D 를 호출하는 것으로 취득할 수 있다.
Caps
이하에, 드라이버 고유의 능력을 나타낸다.
D3DCAPS_READ_SCANLINE
디스플레이 하드웨어는, 현재의 주사선을 돌려줄 수가 있다.
Caps2
이하에, 드라이버 고유의 능력을 나타낸다.
D3DCAPS2_CANCALIBRATEGAMMA
시스템에는 자동적으로 감마 램프를 조정할 수 있는 구경 측정기가 인스톨 되고 있으므로, 구경 측정기가 있는 전시스템에 대해 결과는 같다. 새로운 감마 레벨을 설정할 경우에 구경 측정기를 기동하려면 ,IDirect3DDevice8::SetGammaRamp 메소드를 호출할 때에 D3DSGR_CALIBRATE 플래그를 사용한다. 감마 램프의 calibration를 실시하면 처리 오버헤드가 발생하므로, 빈번하게 사용해서는 안된다.
D3DCAPS2_CANRENDERWINDOWED
드라이버는, 윈도우 모드의 렌더링이 생긴다.
D3DCAPS2_FULLSCREENGAMMA
드라이버는, 풀 스크린 모드에서의 다이나믹 감마 램프 조정을 지원 하고 있다.
D3DCAPS2_NO2DDURING3DSCENE
드라이버에 의해 D3DCAPS2_NO2DDURING3DSCENE 능력이 설정되어 있는 경우,IDirect3DDevice8::BeginScene 와 IDirect3DDevice8::EndScene 의 호출동안에서는 2D 처리를 실행할 수 없는 것을 의미한다.

보통, 이 능력은, 장면을 파티션화해, 장면내의 각 파티션을 렌더링 하는 하드웨어에 의해 설정된다. 파티션화는 드라이버에 의해 실행되어 하드웨어는 이미지 파티션의 사이즈에 대응하는 작은 색 및 깊이 버퍼를 저장 한다. 이 타입의 렌더링 하드웨어에서는, 보통, 이미지의 각 부분이 렌더링 되면(자), 칼라 버퍼내의 데이터는 비디오 메모리에 기입해져 깊이 버퍼의 내용은 파기된다. 또, 3D 렌더링은 EndScene 가 검출될 때까지 시작 되지 않는 것에 주의 해야 한다. 다음에, 장면이 리젼 마다 처리된다. 이 경우, 처리의 순서는 보증되지 않는다. 예를 들어, 처리되는 최초의 리젼 (보통은 윈도우의 좌상구석)이, 프레임의 마지막 삼각형을 포함하고 있는 경우가 있다. 종래의 그래픽스 시스템의 경우, 각 커멘드는 송신된 순서에 처리된다. 그 점에서 지금까지의 시스템과 다르다. 2D 처리는, 처리가 있는 특정의 시점에서 행해지는 것이 상정되고 있다. D3DCAPS2_NO2DDURING3DSCENE 가 설정된 시스템에서는, 처리의 순서는 보증되지 않는다. 따라서, 디스플레이 어댑터는, 3D 렌더링 시에 발생하는 2D 처리를 파기하는 일이 있다.

일반적으로는,BeginScene 와 EndScene 의 페어의 외측에서 2D 처리를 실행하는 것을 추천 한다. 2D 처리가BeginScene 와 EndScene 의 페어의 사이에 실행되는 경우는, D3DCAPS2_NO2DDURING3DSCENE 능력을 체크할 필요가 있다. 이 능력이 설정되어 있는 경우, 어플리케이션에서는,BeginScene 와 EndScene 의 사이에 있는 2D 처리는 파기된다고 생각하지 않으면 안 된다. D3DCAPS2_NO2DDURING3DSCENE 를 설정하는 시스템용의 어플리케이션 생성의 상세한 것에 대하여는, 「주의」를 참조할것.

D3DCAPS2_RESERVED
예약이 끝난 상태. 사용되지 않는다.
Caps3
이하에, 드라이버 고유의 능력을 나타낸다.
D3DCAPS3_RESERVED
예약이 끝난 상태. 사용되지 않는다.
PresentationIntervals
이용 가능한 프레젠테이션 스왑 간격을 나타내는 값의 비트 마스크. 윈도우 모드의 경우, 이 값은 0 이 아니면 안된다. 그 이외의 경우, 이 값은,D3DCAPS8 의 PresentationIntervals 멤버로 열거되는 값의 언젠가가 아니면 안된다.
D3DPRESENT_INTERVAL_IMMEDIATE
드라이버는, 직접 프레젠테이션 스왑 간격을 지원 하고 있다.
D3DPRESENT_INTERVAL_ONE
드라이버는, 스크린 리프레쉬 마다 프레젠테이션 스왑 간격을 지원 하고 있다.
D3DPRESENT_INTERVAL_TWO
드라이버는, 2 번째의 스크린 리프레쉬 마다 프레젠테이션 스왑 간격을 지원 하고 있다.
D3DPRESENT_INTERVAL_THREE
드라이버는, 3 번째의 스크린 리프레쉬 마다 프레젠테이션 스왑 간격을 지원 하고 있다.
D3DPRESENT_INTERVAL_FOUR
드라이버는, 4 번째의 스크린 리프레쉬 마다 프레젠테이션 스왑 간격을 지원 하고 있다.
CursorCaps
커서에 대해서 이용할 수 있는 하드웨어 지원을 나타내는 비트 마스크.
D3DCURSORCAPS_COLOR
하드웨어는, 풀 컬러 커서를 지원 하고 있다. 구체적으로는, 이 플래그는, 드라이버가 고해상도 모드 (주사선이 400 이상)로, 적어도 하드웨어 칼라 커서를 지원 하고 있는 것을 나타낸다.
D3DCURSORCAPS_LOWRES
하드웨어는, 풀 컬러 커서를 지원 하고 있다. 구체적으로는, 이 플래그는, 드라이버가 고해상도 모드와 저해상도 모드 (주사선이 400 미만)의 양쪽 모두로, 하드웨어 칼라 커서를 지원 하고 있는 것을 나타낸다.

Direct3D for Microsoft DirectX® 8.0 에서는, 알파 블렌딩 커서의 능력은 정의되어 있지 않다.

DevCaps
디바이스의 능력을 나타내는 플래그.
D3DDEVCAPS_CANBLTSYSTONONLOCAL
디바이스는, 시스템 메모리 텍스쳐로부터 비로컬 비디오 메모리 텍스쳐에의 소총탄을 지원 한다.
D3DDEVCAPS_CANRENDERAFTERFLIP
디바이스는, 페이지 플립의 다음에, 렌더링 커멘드를 큐에 넣을 수가 있다. 이 플래그는 어플리케이션의 동작을 바꾸는 것은 아니다. 단지 디바이스가 비교적 고속으로 있는 것을 나타내는 것이다.
D3DDEVCAPS_DRAWPRIMTLVERTEX
디바이스는, DrawPrimitive 대응의 하드웨어 추상 계층 (HAL)을 export 한다.
D3DDEVCAPS_EXECUTESYSTEMMEMORY
디바이스는, 시스템 메모리에 있는실행 버퍼를 사용할 수 있다.
D3DDEVCAPS_EXECUTEVIDEOMEMORY
디바이스는, 비디오 메모리에 있는실행 버퍼를 사용할 수 있다.
D3DDEVCAPS_HWRASTERIZATION
디바이스에는, 장면의 라스터화용의 하드웨어 가속화가 있다.
D3DDEVCAPS_HWTRANSFORMANDLIGHT
디바이스는, 하드웨어로 트랜스 폼 & 라이팅을 지원 할 수 있다.
D3DDEVCAPS_NPATCHES
디바이스는, N 패치를 지원 한다.
D3DDEVCAPS_PUREDEVICE
디바이스는, 하드웨어로 라스터화, 트랜스 폼, 라이팅, 및 쉐이딩을 지원 할 수 있다.
D3DDEVCAPS_QUINTICRTPATCHES
디바이스는, 5 차 베쥬 및 B 스플라인을 지원 하고 있다.
D3DDEVCAPS_RTPATCHES
디바이스는, 직사각형 및 삼각형 패치를 지원 하고 있다.
D3DDEVCAPS_RTPATCHHANDLEZERO
이 디바이스 능력이 설정되어 있는 경우, 하드웨어 아키텍쳐로 정보를 캐쉬할 필요가 없고, 캐쉬되어 있지 않은 패치 (핸들 0)는, 캐쉬된 패치와 같이, 효율적으로 드로잉(Drawing) 된다. D3DDEVCAPS_RTPATCHHANDLEZERO 의 설정은 핸들 0 의 패치를 드로잉(Drawing) 할 수 있는 것을 의미하는 것은 아닌 것에 주의 해야 한다. 핸들 0 의 패치는, 이 능력이 설정되어 있는지 어떤지에 관계없이, 항상 드로잉(Drawing) 할 수 있다.
D3DDEVCAPS_SEPARATETEXTUREMEMORIES
디바이스는, 독립한 메모리 풀로부터 텍스쳐 처리를 실시하고 있다.
D3DDEVCAPS_TEXTURENONLOCALVIDMEM
디바이스는, 비로컬 비디오 메모리로부터 텍스쳐를 취득할 수 있다.
D3DDEVCAPS_TEXTURESYSTEMMEMORY
디바이스는, 시스템 메모리로부터 텍스쳐를 취득할 수 있다.
D3DDEVCAPS_TEXTUREVIDEOMEMORY
디바이스는, 디바이스 메모리로부터 텍스쳐를 취득할 수 있다.
D3DDEVCAPS_TLVERTEXSYSTEMMEMORY
디바이스는, 트랜스 폼이 끝난 라이팅 끝난 버텍스용으로, 시스템 메모리의 버퍼를 사용할 수 있다.
D3DDEVCAPS_TLVERTEXVIDEOMEMORY
디바이스는, 트랜스 폼이 끝난 라이팅 끝난 버텍스용으로, 비디오 메모리의 버퍼를 사용할 수 있다.
PrimitiveMiscCaps
이 프리미티브의 총체적인 능력. 이 멤버에는, 다음의 1 개 이상의 플래그를 설정할 수 있다.
D3DPMISCCAPS_BLENDOP
디바이스는,D3DBLENDOP 열거형으로 정의되고 있는 알파 블렌딩 처리를 지원 하고 있다.
D3DPMISCCAPS_CLIPPLANESCALEDPOINTS
디바이스는, 정확하게, 1.0 보다 큰 사이즈의 스케일링 된 포인트를, 유저 정의 클립면에 클립 한다.
D3DPMISCCAPS_CLIPTLVERTS
디바이스는, 트랜스 폼 후의 버텍스 프리미티브를 클립 한다.
D3DPMISCCAPS_COLORWRITEENABLE
디바이스는, D3DRS_COLORWRITEENABLE 스테이트를 사용해, 렌더링 타겟의 칼라 버퍼에의 채널마다의 기입을 지원 한다.
D3DPMISCCAPS_CULLCCW
드라이버는, D3DRS_CULLMODE 스테이트를 사용해 반시계회전의 카링을 지원 한다 (이것은 삼각형 원시적으로 마셔 적용된다). 이 플래그는,D3DCULL 열거형의 D3DCULL_CCW 멤버에 대응한다.
D3DPMISCCAPS_CULLCW
드라이버는, D3DRS_CULLMODE 스테이트를 사용해 시계회전의 카링을 지원 한다(이것은 삼각형 원시적으로 마셔 적용된다). 이 플래그는,D3DCULL 열거형의 D3DCULL_CW 멤버에 대응한다.
D3DPMISCCAPS_CULLNONE
드라이버는, 삼각형 카링을 실행하지 않는다. 이것은,D3DCULL 열거형의 D3DCULL_NONE 멤버에 대응한다.
D3DPMISCCAPS_LINEPATTERNREP
드라이버는,D3DLINEPATTERN 구조체의 wRepeatFactor 멤버로 1 이외의 값을 처리할 수 있다 (이것은 선묘화 원시적으로 마셔 적용된다).
D3DPMISCCAPS_MASKZ
디바이스는, 픽셀 처리에 있어서의 깊이 버퍼의 변경의 유효/무효를 바꿀 수가 있다.
D3DPMISCCAPS_TSSARGTEMP
디바이스는, 텐포라리레지스타용의 D3DTA_TEMP 를 지원 한다.
RasterCaps
라스터 드로잉(Drawing) 능력에 대한 정보. 이 멤버에는, 다음의 1 개 이상의 플래그를 설정할 수 있다.
D3DPRASTERCAPS_ANISOTROPY
디바이스는, 이방성 필터 링을 지원 한다.
D3DPRASTERCAPS_ANTIALIASEDGES
디바이스는, 오브젝트의 윤곽선을 볼록한 모양으로 하는 에일리어징 제거선을 드로잉(Drawing) 할 수 있다. 상세한 것에 대하여는, 「D3DRS_EDGEANTIALIAS 」를 참조할것.
D3DPRASTERCAPS_COLORPERSPECTIVE
디바이스는, 색의 퍼스펙티브 보정을 보간 한다.
D3DPRASTERCAPS_DITHER
디바이스는, 디저링을 사용해 양질인 색을 재현 할 수 있다.
D3DPRASTERCAPS_FOGRANGE
디바이스는, 범위 베이스의 fog를 지원 한다. 범위 베이스의 fog에서는, 장면에 있어서의 오브젝트의 깊이 (z 좌표)는 아니고, 뷰아로부터의 오브젝트의 거리로 fog 이펙트를 계산한다.
D3DPRASTERCAPS_FOGTABLE
디바이스는, 픽셀의 깊이를 가리키는 fog값을 포함한 참조 테이블과 조합해, fog값을 산출한다.
D3DPRASTERCAPS_FOGVERTEX
디바이스는, 라이팅 처리 시에 fog값을 계산해, 라스터화 시에 fog값을 보간 한다.
D3DPRASTERCAPS_MIPMAPLODBIAS
디바이스는, 상세 레벨 (LOD) 바이어스 조정을 지원 한다. 이러한 바이어스 조정에 의해, 밉맵을 보통보다 깨끗이또는 그다지 날카롭지 않게 보이게 할 수가 있다. 밉맵의 LOD 바이어스의 상세한 것에 대하여는, 「D3DTSS_MIPMAPLODBIAS 」를 참조할것.
D3DPRASTERCAPS_PAT
드라이버는, 조회되고 있는 프리미티브에 대해,D3DRS_LINEPATTERN 를 사용한 선이나 칠해의 패턴 드로잉(Drawing)를 실행할 수 있다.
D3DPRASTERCAPS_STRETCHBLTMULTISAMPLE
디바이스는, blt 메소드의 확대를 이행 하는 것으로, 제한된 멀티 샘플의 지원을 제공한다. 이 능력이 설정되어 있는 경우, 장면의 도중에 D3DRS_MULTISAMPLEANTIALIAS 의 온과 오프를 바꿀 수 없다. 이 플래그가 설정되어 있는 경우, 멀티 샘플 마스킹은 실행할 수 없다.
D3DPRASTERCAPS_WBUFFER
디바이스는, w 를 사용하는 깊이 버퍼링을 지원 한다.
D3DPRASTERCAPS_WFOG
디바이스는, w 베이스의 fog를 지원 한다. W 베이스의 fog는, 퍼스펙티브 투영 행렬이 지정되었을 경우에 사용되지만, 아핀 투영에서는 현재에도 Z 베이스의 fog가 사용된다. [3][4] 요소에 제로 이외의 값이 있는 투영 행렬이, 퍼스펙티브 투영 행렬이라고 보여진다.
D3DPRASTERCAPS_ZBIAS
디바이스는, z 바이어스값을 지원 한다. 이것들은 다각형에 할당할 수 있었던 정수값이며, 물리적으로 동일 평면상에 있는 다각형을 다른 것에 보일 수가 있다. 상세한 것에 대하여는, 「D3DRS_ZBIAS 」를 참조할것.
D3DPRASTERCAPS_ZBUFFERLESSHSR
디바이스는, 숨고 표면의 제거 (HRS)를 실행할 수 있어 이 때, 다각형의 소트나 깊이 버퍼의 할당을 필요로 하지 않는다. 이것에 의해, 보다 많은 비디오 메모리를 텍스쳐용으로 사용할 수 있다. HSR 를 실행하기 위해서 사용하는 메소드는 하드웨어의 기능에 의존해, 어플리케이션에 대해서는 투과적이다.

Z 버퍼 없음의 HRS 가 실행되는 것은, 깊이 버퍼 표면이 렌더링 타겟 표면에 관련지을 수 있지 않고, 한편 깊이 버퍼의 비교 테스트가 유효하게 되어 있는 경우 (즉, D3DRS_ZENABLE 열거 정수에 관련지을 수 있었던 스테이트값이 TRUE 로 설정되어 있는 경우)이다.

D3DPRASTERCAPS_ZFOG
디바이스는, z 베이스의 fog를 지원 한다.
D3DPRASTERCAPS_ZTEST
디바이스는, z 테스트 처리를 실행할 수 있다. 이 값은, 효과적으로 프리미티브를 렌더링 해, Z 픽셀이 렌더링 되었는지 어떠했는지를 나타낸다.
ZCmpCaps
Z 버퍼 비교 능력. 이 멤버에는, 다음의 1 개 이상의 플래그를 설정할 수 있다.
D3DPCMPCAPS_ALWAYS
항상 Z 테스트를 패스한다.
D3DPCMPCAPS_EQUAL
신규의 Z 가 현재의 Z 로 동일한 경우, Z 테스트를 패스한다.
D3DPCMPCAPS_GREATER
신규의 Z 가 현재의 Z 보다 큰 경우, Z 테스트를 패스한다.
D3DPCMPCAPS_GREATEREQUAL
신규의 Z 가 현재의 Z 보다 큰가 동일한 경우, Z 테스트를 패스한다.
D3DPCMPCAPS_LESS
신규의 Z 가 현재의 Z 보다 작은 경우, Z 테스트를 패스한다.
D3DPCMPCAPS_LESSEQUAL
신규의 Z 가 현재의 Z 보다 작은가 동일한 경우, Z 테스트를 패스한다.
D3DPCMPCAPS_NEVER
항상 Z 테스트를 실패한다.
D3DPCMPCAPS_NOTEQUAL
신규의 Z 가 현재의 Z 로 동일하지 않은 경우, Z 테스트를 패스한다.
SrcBlendCaps
소스 블렌딩 능력. 이 멤버에는, 다음의 1 개 이상의 플래그를 설정할 수 있다. (소스 및 목적지의 RGBA 값은, 첨자의 s 및 d. 그리고 나타난다).
D3DPBLENDCAPS_BOTHINVSRCALPHA
소스의블렌딩 계수는 (1-As, 1-As, 1-As, 1-As)으로, 목적지의 블렌딩 계수는 (As, As, As, As)이다. 목적지의 블렌딩의 선택은 무효가 된다.
D3DPBLENDCAPS_BOTHSRCALPHA
드라이버는 D3DBLEND_BOTHSRCALPHA 블렌딩 모드를 지원 한다(이 블렌딩 모드는 폐지되고 있다. 상세한 것에 대하여는, 「D3DBLEND 」를 참조할것).
D3DPBLENDCAPS_DESTALPHA
블렌딩 계수는 (Ad, Ad, Ad, Ad).
D3DPBLENDCAPS_DESTCOLOR
블렌딩 계수는 (Rd, Gd, Bd, Ad).
D3DPBLENDCAPS_INVDESTALPHA
블렌딩 계수는 (1-Ad, 1-Ad, 1-Ad, 1-Ad).
D3DPBLENDCAPS_INVDESTCOLOR
블렌딩 계수는 (1-Rd, 1-Gd, 1-Bd, 1-Ad).
D3DPBLENDCAPS_INVSRCALPHA
블렌딩 계수는 (1-As, 1-As, 1-As, 1-As).
D3DPBLENDCAPS_INVSRCCOLOR
블렌딩 계수는 (1-Rd, 1-Gd, 1-Bd, 1-Ad).
D3DPBLENDCAPS_ONE
블렌딩 계수는 (1, 1, 1, 1).
D3DPBLENDCAPS_SRCALPHA
블렌딩 계수는 (As, As, As, As).
D3DPBLENDCAPS_SRCALPHASAT
블렌딩 계수는 (f, f, f, 1), f = min(As, 1-Ad).
D3DPBLENDCAPS_SRCCOLOR
블렌딩 계수는 (Rs, Gs, Bs, As).
D3DPBLENDCAPS_ZERO
블렌딩 계수는 (0, 0, 0, 0).
DestBlendCaps
목적지 블렌딩 능력. 이 멤버는,SrcBlendCaps 멤버로 정의된 능력 정보와 같다.
AlphaCmpCaps
알파 테스트 비교 능력. 이 멤버는,ZCmpCaps 멤버로 정의된 능력 플래그를 포함한다. 이 멤버가 D3DPCMPCAPS_ALWAYS 능력만, 또는 D3DPCMPCAPS_NEVER 능력밖에 가지고 있지 않은 경우, 드라이버는 알파 테스트를 지원 하지 않는다. 그 이외의 경우, 이 플래그는 알파 테스트를 지원 하는 개개의 비교를 나타낸다.
ShadeCaps
쉐이딩 처리 능력. 일반적으로, 디바이스가 지정된 커멘드를 지원 하고 있는 경우, 그 디바이스는 D3DSHADE_FLAT 모드 (D3DSHADEMODE 열거형으로 지정된다)를 지원 하면 보여진다. 이 플래그는, 드라이버가 gouraud shading도 지원 할 수 있을지 어떨지, 및알파 성분이 지원 되고 있는지 어떤지를 나타낸다. 알파 성분이 지원 되지 않는 경우, 생성된 색의 알파값은 암묵으로 255 가 된다. 이 수치가, 알파의 최대치 (알파 성분이 최강)이다.

삼각형의 색, 스펙큐러 하이라이트, fog, 및 알파의 각 보간 요소에는 각각 능력 플래그가 있어, 어플리케이션은 그 플래그를 사용해, 디바이스 드라이버가 그것들을 어떻게 이행 하고 있을까를 알 수 있다.

이 멤버에는, 다음의 1 개 이상의 플래그를 설정할 수 있다.

D3DPSHADECAPS_ALPHAGOURAUDBLEND
디바이스는, 그로브렌드에 의한 투명화 (D3DSHADEMODE 열거형의 D3DSHADE_GOURAUD 스테이트)에 대한 알파 성분을 지원 할 수 있다. 이 모드에서는, 프리미티브의알파 성분은 버텍스로써 주어져 다른 색성분과 함께 면을 따라 보간 된다.
D3DPSHADECAPS_COLORGOURAUDRGB
디바이스는, RGB 칼라 모델로 칼라 gouraud shading를 지원 할 수 있다. 이 모드에서는, 프리미티브에 대한 색성분은 버텍스로써 주어져 다른 색성분과 함께 면을 따라 보간 된다. RGB 라이팅 모델에서는, 적, 록, 및 파랑의 각 성분이 보간 된다.
D3DPSHADECAPS_FOGGOURAUD
디바이스는, gouraud shading 모드로 fog를 지원 할 수 있다.
D3DPSHADECAPS_SPECULARGOURAUDRGB
디바이스는, RGB 칼라 모델의 gouraud shading에 대해 스펙큐러 하이라이트를 지원 할 수 있다.
TextureCaps
그 외의 텍스쳐 매핑 능력. 이 멤버에는, 다음의 1 개 이상의 플래그를 설정할 수 있다.
D3DPTEXTURECAPS_ALPHA
텍스쳐 픽셀에 대해 알파가 지원 된다.
D3DPTEXTURECAPS_ALPHAPALETTE
디바이스는, 텍스쳐 팔레트로부터 알파를 드로잉(Drawing) 할 수 있다.
D3DPTEXTURECAPS_CUBEMAP
큐브 텍스쳐를 지원 한다.
D3DPTEXTURECAPS_CUBEMAP_POW2
디바이스에서는, 큐브 텍스쳐 맵의 넓이는 2 의 거듭제곱으로 지정되지 않으면 안 된다.
D3DPTEXTURECAPS_MIPCUBEMAP
디바이스는, 밉맵화 큐브 텍스쳐를 지원 한다.
D3DPTEXTURECAPS_MIPMAP
디바이스는, 밉맵화 텍스쳐를 지원 한다.
D3DPTEXTURECAPS_MIPVOLUMEMAP
디바이스는, 밉맵화 볼륨 텍스쳐를 지원 한다.
D3DPTEXTURECAPS_NONPOW2CONDITIONAL
경우에 따라서는, 넓이가 2 의 거듭제곱이 아닌 텍스쳐의 사용을 지원 한다. 이하의 조건을 모두 채우는 경우, 이 능력을 공개하는 디바이스에서는 이러한 텍스쳐를 사용할 수 있다.
  • 텍스쳐 스테이지의 텍스쳐 addressing mode가, D3DTADDRESS_CLAMP 로 설정되어 있다.
  • 텍스쳐 스테이지의 텍스쳐 랩핑이 무효가 되어 있다 (D3DRS_WRAPn 를 0 으로 설정).
  • MIP Mapping가 사용되어 있지 않다 (확대 필터만을 사용).
D3DPTEXTURECAPS_PERSPECTIVE
퍼스펙티브 보정의 텍스쳐 링이 지원 된다.
D3DPTEXTURECAPS_POW2
모든 텍스쳐의 폭과 높이는, 2 의 거듭제곱으로 지정되어 있지 않으면 안 된다. 이 조건은, 큐브 텍스쳐 또는 볼륨 텍스쳐에는 적용되지 않는다.
D3DPTEXTURECAPS_PROJECTED
D3DTTFF_PROJECTED 텍스쳐 트랜스 폼 플래그를 지원 한다. 이 능력이 적용되고 있는 경우, 디바이스는 트랜스 폼이 끝난 텍스쳐 좌표를 마지막 텍스쳐 좌표로 나눗셈 한다. 이 능력이 설정되어 있는 경우, 픽셀 단위에 투영 나눗셈을 한다. 이 능력이 설정되어 있지 않은 경우에, 투영 나눗셈이 필요한 때는, Direct3D 런타임에 의해 버텍스 마다 행해진다.
D3DPTEXTURECAPS_SQUAREONLY
텍스쳐는, 모두 정방형이 아니면 안된다.
D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE
텍스쳐 인덱스는, 보간 실행전에는, 텍스쳐 사이즈에 맞추어 스케일링 되지 않는다.
D3DPTEXTURECAPS_VOLUMEMAP
디바이스는, 볼륨 텍스쳐를 지원 한다.
D3DPTEXTURECAPS_VOLUMEMAP_POW2
디바이스에서는, 볼륨 텍스쳐 맵의 넓이는 2 의 거듭제곱으로 지정되지 않으면 안 된다.
TextureFilterCaps
Direct3DTexture 오브젝트의 텍스쳐 필터 링 능력. 스테이지 단위의 필터 링 능력은,IDirect3DDevice8 인터페이스로 멀티 텍스쳐 블렌딩을 실행할 때에 텍스쳐 스테이지에서 지원 되는 필터 링 모드를 나타내고 있다. 이 멤버는, 다음에 나타내는 스테이지 단위의 텍스쳐 필터 링 플래그를 임의에 조합한 것이다.
D3DPTFILTERCAPS_MAGFAFLATCUBIC
디바이스는, 스테이지 마다, 텍스쳐를 확대하는 평면 3 차 필터 링을 지원 한다. 평면 3 차 확대 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_FLATCUBIC 멤버로 나타내진다.
D3DPTFILTERCAPS_MAGFANISOTROPIC
디바이스는, 스테이지 마다, 텍스쳐를 확대하는 이방성 필터 링을 지원 한다. 이방성 확대 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_ANISOTROPIC 멤버로 나타내진다.
D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC
디바이스는, 스테이지 마다, 텍스쳐를 확대하는 Gauss 3 차 필터 링을 지원 한다. Gauss 3 차 확대 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_GAUSSIANCUBIC 멤버로 나타내진다.
D3DPTFILTERCAPS_MAGFLINEAR
디바이스는, 스테이지 마다, 텍스쳐를 확대하는 바이리니아 보간 필터 링을 지원 한다. 바이리니아 보간 확대 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_LINEAR 멤버로 나타내진다.
D3DPTFILTERCAPS_MAGFPOINT
디바이스는, 스테이지 마다, 텍스쳐를 확대하는 포인트 샘플 필터 링을 지원 한다. 포인트 샘플 확대 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_POINT 멤버로 나타내진다.
D3DPTFILTERCAPS_MINFANISOTROPIC
디바이스는, 스테이지 마다, 텍스쳐를 축소하는 이방성 필터 링을 지원 한다. 이방성 축소 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_ANISOTROPIC 멤버로 나타내진다.
D3DPTFILTERCAPS_MINFLINEAR
디바이스는, 스테이지 마다, 텍스쳐를 축소하는 바이리니아 보간 필터 링을 지원 한다. 바이리니아 축소 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_LINEAR 멤버로 나타내진다.
D3DPTFILTERCAPS_MINFPOINT
디바이스는, 스테이지 마다, 텍스쳐를 축소하는 포인트 샘플 필터 링을 지원 한다. 포인트 샘플 축소 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_POINT 멤버로 나타내진다.
D3DPTFILTERCAPS_MIPFLINEAR
디바이스는, 스테이지 마다, 밉맵을 위한 트라이 리니어 보간 필터 링을 지원 한다. 트라이 리니어 보간 밉맵 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_LINEAR 멤버로 나타내진다.
D3DPTFILTERCAPS_MIPFPOINT
디바이스는, 스테이지 단위에, 밉맵을 실시하는 포인트 샘플 필터 링을 지원 한다. 포인트 샘플 밉맵 필터는,D3DTEXTUREFILTERTYPE 열거형의 D3DTEXF_POINT 멤버로 나타내진다.
CubeTextureFilterCaps
Direct3DCubeTexture 오브젝트의 텍스쳐 필터 링 능력. 스테이지 단위의 필터 링 능력은,IDirect3DDevice8 인터페이스로 멀티 텍스쳐 블렌딩을 실행할 때에 텍스쳐 스테이지에서 지원 되는 필터 링 모드를 나타내고 있다. 이 멤버는,TextureFilterCaps 용으로 정의된 스테이지 단위의 텍스쳐 필터 링 플래그를 임의에 조합한 것이다.
VolumeTextureFilterCaps
Direct3DVolumeTexture 오브젝트의 텍스쳐 필터 링 능력. 스테이지 단위의 필터 링 능력은,IDirect3DDevice8 인터페이스로 멀티 텍스쳐 블렌딩을 실행할 때에 텍스쳐 스테이지에서 지원 되는 필터 링 모드를 나타내고 있다. 이 멤버는,TextureFilterCaps 용으로 정의된 스테이지 단위의 텍스쳐 필터 링 플래그를 임의에 조합한 것이다.
TextureAddressCaps
Direct3DTexture 오브젝트의 텍스쳐 애드레싱 능력. 이 멤버에는, 다음의 1 개 이상의 플래그를 설정할 수 있다.
D3DPTADDRESSCAPS_BORDER
디바이스는, D3DTSS_BORDERCOLOR 텍스쳐 스테이지 스테이트에서 지정되는 경계색을,[0.0, 1.0] 의 범위외의 좌표로 설정할 수 있다.
D3DPTADDRESSCAPS_CLAMP
디바이스는, 텍스쳐를 주소에 고정할 수 있다.
D3DPTADDRESSCAPS_INDEPENDENTUV
디바이스는, 텍스쳐의 U 좌표와 V 좌표의 텍스쳐 addressing mode를 분리할 수 있다. 이 능력은, D3DTSS_ADDRESSU 및 D3DTSS_ADDRESSV 렌더링 스테이트값에 대응한다.
D3DPTADDRESSCAPS_MIRROR
디바이스는, 텍스쳐를 주소에 반영시킬 수가 있다.
D3DPTADDRESSCAPS_MIRRORONCE
디바이스는, 텍스쳐 좌표의 절대치를 취득해 (0 을 중심으로 미러링 되고), 최대치에 제한할 수 있다.
D3DPTADDRESSCAPS_WRAP
디바이스는, 텍스쳐가 붙이고가 가능하다.
VolumeTextureAddressCaps
Direct3DVolumeTexture 오브젝트의 텍스쳐 애드레싱 능력. 이 멤버에는,TextureAddressCaps 멤버용으로 정의된 1 개(살) 이상의 플래그를 설정할 수 있다.
LineCaps
선묘화 프리미티브의 능력을 정의한다.
D3DLINECAPS_ALPHACMP
알파 테스트 비교를 지원 한다.
D3DLINECAPS_BLEND
소스 블렌딩을 지원 한다.
D3DLINECAPS_FOG
fog를 지원 한다.
D3DLINECAPS_TEXTURE
텍스쳐 매핑을 지원 한다.
D3DLINECAPS_ZTEST
Z 버퍼 비교를 지원 한다.
MaxTextureWidth 및 MaxTextureHeight
이 디바이스의 최대의 텍스쳐의 폭과 높이.
MaxVolumeExtent
최대 볼륨 범위.
MaxTextureRepeat
정규화한 후의 텍스쳐 인덱스의 정수 비트의 전범위. D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 비트가 설정되어 있는 경우, 디바이스는, 텍스쳐 addressing mode가 적용될 때까지 텍스쳐 사이즈에 의한 스케일링을 실시하지 않는다. 이 비트가 설정되어 있지 않은 경우는, 디바이스는 텍스쳐 사이즈 (최대 상세 레벨)에 의한 텍스쳐 인덱스의 스케일링을 실행하고 나서 보간을 실시한다.

D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 가 설정되어 있는 경우, 텍스쳐를 랩 할 수 있는 회수는 MaxTextureRepeat 이다. D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 가 설정되어 있지 않은 경우, 텍스쳐를 랩 할 수 있는 회수는MaxTextureRepeat × 텍스쳐 사이즈이다. 예를 들어, 디바이스가 D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 를 설정해,MaxTextureRepeat 가 32k 로, 최대 텍스쳐 사이즈가 4k 이다고 한다. 이 디바이스는, 27 의 정수 비트 ( 및 32 비트 부호 첨부 정수의 경우는 5 개의 소수 비트)를 사용하므로, 4k 의 텍스쳐를 32k 회 랩 하는데 충분하다 (텍스쳐 좌표가, 정과 부의 텍스쳐 좌표의 범위에 동일하게 퍼지고 있으면(자) 가정했을 경우). 한편, 디바이스가 D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 를 설정할 수 없는 경우는,MaxTextureRepeat 를 2**27 로 설정한다.

MaxTextureAspectRatio
하드웨어에 의해 지원 되는, 텍스쳐의 최대 어스펙트비(가로세로 비율). 보통은 2 의 거듭제곱.
MaxAnisotropy
D3DTSS_MAXANISOTROPY 텍스쳐 스테이지 스테이트의 최대 유효값.
MaxVertexW
디바이스가 지원 하는 최대 W 베이스 깊이값.
GuardBandLeft, GuardBandTop, GuardBandRight, 및 GuardBandBottom
가이드 밴드 클리핑 영역의 화면 공간 좌표. 이 직사각형내에 있어, 한편 뷰 포토 직사각형의 외측에 있는 좌표는, 자동적으로 클리핑 된다.
ExtentsAdjust
에일리어징 제거 커넬이 들어가도록(듯이) 직사각형의 외변을 조절하기 위한 픽셀수.
StencilCaps
지원 되고 있는 스텐실 버퍼 처리를 지정하는 플래그. 스텐실 처리는, 3 종류의 스텐실 버퍼 처리 렌더링 스테이트 (D3DRS_STENCILFAIL, D3DRS_STENCILPASS, D3DRS_STENCILFAILZFAIL)의 모두에 대해서, 유효하다라고 보여진다.
D3DSTENCILCAPS_DECR
D3DSTENCILOP_DECR 처리를 지원 한다.
D3DSTENCILCAPS_DECRSAT
D3DSTENCILOP_DECRSAT 처리를 지원 한다.
D3DSTENCILCAPS_INCR
D3DSTENCILOP_INCR 처리를 지원 한다.
D3DSTENCILCAPS_INCRSAT
D3DSTENCILOP_INCRSAT 처리를 지원 한다.
D3DSTENCILCAPS_INVERT
D3DSTENCILOP_INVERT 처리를 지원 한다.
D3DSTENCILCAPS_KEEP
D3DSTENCILOP_KEEP 처리를 지원 한다.
D3DSTENCILCAPS_REPLACE
D3DSTENCILOP_REPLACE 처리를 지원 한다.
D3DSTENCILCAPS_ZERO
D3DSTENCILOP_ZERO 처리를 지원 한다.

상세한 것에 대하여는, 「D3DSTENCILOP 열거형」을 참조할것.

FVFCaps
유연한 버텍스 포맷의 능력.
D3DFVFCAPS_DONOTSTRIPELEMENTS
버텍스 요소는 삭제하지 않는 것이 좋다. 즉, 버텍스 포맷이 현재의 렌더링 스테이트에서 사용되지 않는 요소를 포함하고 있어도, 버텍스를 재차 생성할 필요는 없다. 이 능력 플래그가 지정되어 있지 않은 경우, 버텍스 포맷화등 불필요한 요소를 삭제 하면, 퍼포먼스가 향상한다.
D3DFVFCAPS_PSIZE
D3DFVFCAPS_PSIZE 가 없는 경우, 디바이스는 트랜스 폼전의 버텍스에 대해 D3DFVF_PSIZE 를 지원 하고 있지 않는 것을 나타낸다. 이 경우, 기본 포인트 사이즈는 항상 D3DRS_POINTSIZE 로부터 이용된다. 이 능력은, 소프트웨어의 고정 기능 버텍스 처리에게만 적용된다. 소프트웨어 버텍스 처리를 실시하는 경우, D3DFVF_PSIZE 는 항상 지원 된다.

버텍스 쉐이더에 의해 기입해지는 출력 포인트 사이즈는 항상 지원 된다. 버텍스 쉐이더의 경우, 입력은 모두 출력 포인트 사이즈에 의한다.

트랜스 폼 후의 버텍스에 대해서는, D3DFVF_PSIZE 는 항상 지원 된다.

D3DFVFCAPS_TEXCOORDCOUNTMASK
FVFCaps 의 하위 WORD 를 마스크 한다. 이 비트는,WORD 데이터형에 캐스트 되어 디바이스가 복수의 텍스쳐 블렌딩에 동시에 사용할 수 있는 텍스쳐 좌표 세트의 총수를 나타낸다 (어느 버텍스에 대해서도 최대 8 개의 텍스쳐 좌표 세트를 사용할 수 있지만, 디바이스에서는 지정된 개수의 텍스쳐 좌표 세트만 블렌딩 할 수 있다).
TextureOpCaps
이 디바이스가 지원 하는 텍스쳐 처리를 나타내는 플래그의 편성. 이하의 플래그가 정의되고 있다.
D3DTEXOPCAPS_ADD
D3DTOP_ADD 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_ADDSIGNED
D3DTOP_ADDSIGNED 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_ADDSIGNED2X
D3DTOP_ADDSIGNED2X 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_ADDSMOOTH
D3DTOP_ADDSMOOTH 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_BLENDCURRENTALPHA
D3DTOP_BLENDCURRENTALPHA 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_BLENDDIFFUSEALPHA
D3DTOP_BLENDDIFFUSEALPHA 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_BLENDFACTORALPHA
D3DTOP_BLENDFACTORALPHA 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_BLENDTEXTUREALPHA
D3DTOP_BLENDTEXTUREALPHA 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_BLENDTEXTUREALPHAPM
D3DTOP_BLENDTEXTUREALPHAPM 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_BUMPENVMAP
D3DTOP_BUMPENVMAP 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_BUMPENVMAPLUMINANCE
D3DTOP_BUMPENVMAPLUMINANCE 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_DISABLE
D3DTOP_DISABLE 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_DOTPRODUCT3
D3DTOP_DOTPRODUCT3 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_LERP
D3DTOP_LERP 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_MODULATE
D3DTOP_MODULATE 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_MODULATE2X
D3DTOP_MODULATE2X 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_MODULATE4X
D3DTOP_MODULATE4X 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_MODULATEALPHA_ADDCOLOR
D3DTOP_MODULATEALPHA_ADDCOLOR 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_MODULATECOLOR_ADDALPHA
D3DTOP_MODULATECOLOR_ADDALPHA 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLOR
D3DTOP_MODULATEINVALPHA_ADDCOLOR 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHA
D3DTOP_MODULATEINVCOLOR_ADDALPHA 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_MULTIPLYADD
D3DTOP_MULTIPLYADD 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_PREMODULATE
D3DTOP_PREMODULATE 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_SELECTARG1
D3DTOP_SELECTARG1 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_SELECTARG2
D3DTOP_SELECTARG2 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_SUBTRACT
D3DTOP_SUBTRACT 텍스쳐 블렌딩 처리가 지원 된다.
MaxTextureBlendStages
지원 되는 텍스쳐 블렌딩 스테이지의 최대수. 이 값은, 사용 가능한 브렌다의 수이다. DirectX 8.0 의 프로그램 가능 픽셀 파이프라인에서는, 이것은, 이 특정의 이행의 픽셀 쉐이더에 의해 지원 되고 있는 명령수에 대응한다.
MaxSimultaneousTextures
텍스쳐 블렌딩 스테이지에 동시에 바인드 할 수 있는 텍스쳐의 최대수. 이 값은, 싱글 패스로 사용할 수 있는 텍스쳐의 수이다. DirectX 8.0 의 프로그램 가능 픽셀 쉐이더에서는, 이것은 특정의 하드웨어의 픽셀 쉐이더에 의해 지원 되는 텍스쳐 레지스터의 수, 및 사용할 수 있는 텍스쳐 선언 명령의 수를 나타낸다.
VertexProcessingCaps
버텍스의 처리 능력. 임의의 물리 디바이스의 경우, 이 능력은,IDirect3D8::CreateDevice 로 지정된 파라미터에 응해, Direct3D Device Object 간에 다른 일이 있다.
D3DVTXPCAPS_DIRECTIONALLIGHTS
디바이스는 디레크쇼나르라이트를 지원 한다.
D3DVTXPCAPS_LOCALVIEWER
디바이스는 로카르뷰아를 지원 한다.
D3DVTXPCAPS_MATERIALSOURCE7
디바이스는 선택 가능한 버텍스 칼라 소스를 지원 한다.
D3DVTXPCAPS_POSITIONALLIGHTS
디바이스는 국부 라이트 (포인트 라이트, spotlight등)를 지원 한다.
D3DVTXPCAPS_TEXGEN
디바이스는 텍스쳐 좌표를 생성할 수 있다.
D3DVTXPCAPS_TWEENING
디바이스는 버텍스 트이닝을 지원 한다.
D3DVTXPCAPS_NO_VSDT_UBYTE4
디바이스는, D3DVSDT_UBYTE4 버텍스 선언 타입을 지원 하지 않는다.
MaxActiveLights
동시에 액티브하게 할 수 있는 라이트의 최대수. 임의의 물리 디바이스의 경우, 이 능력은,IDirect3D8::CreateDevice 로 지정된 파라미터에 응해, Direct3D Device Object 간에 다른 일이 있다.
MaxUserClipPlanes
지원 되는 유저 정의 클립면의 최대수. 이 멤버는 0 으로부터 D3DMAXUSERCLIPPLANES 까지의 범위가 된다. 임의의 물리 디바이스의 경우, 이 능력은,IDirect3D8::CreateDevice 로 지정된 파라미터에 응해, Direct3D Device Object 간에 다른 일이 있다.
MaxVertexBlendMatrices
복수의 행렬에 의한 버텍스 블렌딩을 실행할 때에 디바이스를 적용할 수 있는 행렬의 최대수. 임의의 물리 디바이스의 경우, 이 능력은,IDirect3D8::CreateDevice 로 지정된 파라미터에 응해, Direct3D Device Object 간에 다른 일이 있다.
MaxVertexBlendMatrixIndex
버텍스 단위의 인덱스를 사용해 인덱스 붙이고 할 수 있는 최대의 행렬 인덱스를 나타내는 DWORD 값. 행렬의 수는 MaxVertexBlendMatrixIndex + 1 으로, 이것은 행렬 팔레트의 사이즈이다. 라이팅에 블렌딩 할 필요가 있는 버텍스 데이터에 법선이 존재하는 경우, 행렬의 수는, 이 능력 플래그로 나타나고 있는 수의 반이 된다. MaxVertexBlendMatrixIndex 에 0 이 설정되어 있는 경우, 드라이버는 인덱스 첨부 버텍스 블렌딩을 지원 하고 있지 않다. 이 값이 0 이 아닌 경우, 인덱스의 유효한 범위는 0 으로부터 MaxVertexBlendIndexedMatrices 까지이다.

MaxVertexBlendMatrixIndex 의 값이 0 의 경우는, 드라이버가 인덱스 첨부 행렬을 지원 하고 있지 않는 것을 나타낸다.

소프트웨어 버텍스 처리가 사용되고 있는 경우는, 법선 블렌딩이 있어도 없어도, 256 개의 행렬을 인덱스 첨부 버텍스 블렌딩에 사용할 수 있다.

임의의 물리 디바이스의 경우, 이 능력은,IDirect3D8::CreateDevice 로 지정된 파라미터에 응해, Direct3D Device Object 간에 다른 일이 있다.

MaxPointSize
포인트 프리미티브의 최대 사이즈. 1.0f 로 설정되어 있는 경우, 디바이스는 포인트 사이즈의 제어를 지원 하고 있지 않다. 범위는 1.0f 이상이다.
MaxPrimitiveCount
DrawPrimitive 의 각 호출의 최대 프리미티브수.
MaxVertexIndex
하드웨어 버텍스 처리에 대해서 지원 되는 인덱스의 최대 사이즈. D3DFMT_INDEX32 를 지정해 32 비트 인덱스 버퍼를 생성 할 수 있다. 다만, 이 값이 0x0000FFFF 보다 크지 않은 경우는, 인덱스 버퍼를 사용해 렌더링 할 수 없다.
MaxStreams
IDirect3DDevice8::SetStreamSource 에 대한 동시 데이터 스트림의 최대수. 유효 범위는 1 ~ 16 이다. 이 값이 0 의 경우, DirectX 8.0 드라이버는 아닌 것에 주의한다.
MaxStreamStride
IDirect3DDevice8::SetStreamSource 의 최대 보폭.
VertexShaderVersion
버텍스 쉐이더의 버젼. 디바이스가 지원 하는 버텍스 쉐이더의 레벨을 나타낸다. IDirect3DDevice8::CreateVertexShader 의 호출은, 이 멤버의 값이하의 버젼 번호의 버텍스 쉐이더를 지정했을 경우에게만 성공한다. CreateVertexShader 에 대한 쉐이더 레벨의 지정은, 버텍스 쉐이더 토큰 스트림의 제 1 토큰으로 행해진다.
  • DirectX 7.0 기능은 0.
  • DirectX 8.0 기능은 01.

주된 버젼 번호는, 세컨드 바이트에 encode 된다. 하위 바이트에는, 서브 버젼의 번호가 포함된다.

MaxVertexShaderConst
버텍스 쉐이더의 정수 레지스터의 수.
PixelShaderVersion
픽셀 쉐이더의 버젼. 디바이스가 지원 하는 픽셀 쉐이더의 레벨을 나타낸다. IDirect3DDevice8::CreatePixelShader 의 호출은, 이 멤버의 값이하의 버젼 번호의 픽셀 쉐이더를 지정했을 경우에게만 성공한다.
  • DirectX 8.0 기능은 01.

주된 버젼 번호는, 세컨드 바이트에 encode 된다. 하위 바이트에는, 서브 버젼의 번호가 포함된다.

MaxPixelShaderValue
픽셀 쉐이더의 산술 컴퍼넌트의 최대치. 이 값은, 픽셀 칼라 블렌딩 처리로 지원 되는 값의 내부 범위를 나타낸다. 리포트되는 범위내에서는, 데이터가 변경 (제한)되지 않고 픽셀 처리에게 건네질 필요가 있다. 보통, 이 멤버의 값은 절대치이다. 예를 들어, 1.0 은 -1. 0 ~ 1 의 범위를 나타내, 8.0 은 -8. 0 ~ 8.0 의 범위를 나타낸다. 이 값이 0.0 의 경우, 부호 첨부의 범위가 지원되어 있지 않은 것을 나타내, 범위는 DirectX 6.0 및 7.0 과 같게 0 ~ 1.0 이 된다.

주의

MaxTextureBlendStages 멤버와 MaxSimultaneousTextures 멤버는 같은 것과 같이 보이지만, 서로 다른 정보를 포함하고 있다. MaxTextureBlendStages 멤버는, 현재의 디바이스로 지원 되는 텍스쳐 블렌딩 스테이지의 총수를 나타내,MaxSimultaneousTextures 멤버는,IDirect3DDevice8::SetTexture 메소드를 사용해 이러한 스테이지중 몇개의 스테이지에서 텍스쳐를 바인드 할 수 있는지를 나타낸다.

드라이버가 이 구조체에 값을 설정하는 경우, 능력의 취득에 사용하는 인터페이스 (IDirect3DDevice8 등)가 실행 버퍼를 지원 하고 있지 않아도, 실행 버퍼 능력의 값이 설정되는 경우가 있다.

D3DCAPS2_NO2DDURING3DSCENE 능력 플래그를 설정하는 시스템의 경우는, 텍스쳐를 사용해, 장면안으로 변경 하면 퍼포먼스의 문제가 발생하는 일이 있다. 이것은 모든 하드웨어에 해당하지만, D3DCAPS2_NO2DDURING3DSCENE 능력을 공개하는 하드웨어로 보다 심각하다. 하드웨어에 D3DCAPS2_NO2DDURING3DSCENE 가 존재하는 경우, 어플리케이션 베이스의 텍스쳐 관리에서는, 현재의 BeginScene 와 EndScene 블록내에서 사용되고 있는 텍스쳐가, 정말로 필요하지 않은 한, 제외되지 않게 해야 한다. 장면에서 텍스쳐를 다용하고 있는 경우, 결과는 부정이다. 이것은, 장면에서 사용한 텍스쳐를 변경하는 경우에, 이용 가능한 텍스쳐 메모리가 부족 하면 발생한다. 이러한 시스템에서는, Z 버퍼의 내용은 EndScene 로 무효가 된다. 어플리케이션은, 이 타입의 하드웨어상에서는,BeginScene 와 EndScene 의 사이로, 백 버퍼에의, 또는 백 버퍼로부터의 IDirect3DDevice8::CopyRects 를 호출해서는 안된다. 게다가 D3DPRASTERCAPS_ZBUFFERLESSHSR 능력 플래그가 설정되어 있는 경우, 어플리케이션은 Z 버퍼에 액세스 해서는 안된다. 마지막으로, 어플리케이션은 BeginScene 와 EndScene 의 페어의 사이로, 백 버퍼 또는 Z 버퍼를 락 해서는 안된다.

다음에 나타내는 밉맵 텍스쳐 관련의 플래그는, DirectX 8.0 에서는 지원되어 있지 않다.

  • D3DPTFILTERCAPS_NEAREST
  • D3DPTFILTERCAPS_LINEAR
  • D3DPTFILTERCAPS_MIPNEAREST
  • D3DPTFILTERCAPS_MIPLINEAR
  • D3DPTFILTERCAPS_LINEARMIPNEAREST
  • D3DPTFILTERCAPS_LINEARMIPLINEAR

동작환경

헤더 : D3d8caps.h 로 선언.

참조

IDirect3D8::GetDeviceCaps ,IDirect3DDevice8::GetDeviceCaps


D3DCLIPSTATUS8

현재의 클립 스테이터스를 기술한다.

typedef struct _D3DCLIPSTATUS8 {
   DWORD ClipUnion;
   DWORD ClipIntersection;
} D3DCLIPSTATUS8;

멤버

ClipUnion
현재의 클립 스테이터스를 나타내는 클립 결합 플래그. 이 멤버에는, 다음의 1 개 이상의 플래그를 설정할 수 있다.
D3DCS_ALL
모든 클립 플래그의 편성.
D3DCS_BACK
모든 버텍스를시추대의 배면에서 클리핑 한다.
D3DCS_BOTTOM
모든 버텍스를 시추대의 저면에서 클리핑 한다.
D3DCS_FRONT
모든 버텍스를 시추대의 전면에서 클리핑 한다.
D3DCS_LEFT
모든 버텍스를 시추대의 좌측면에서 클리핑 한다.
D3DCS_RIGHT
모든 버텍스를 시추대의 우측면에서 클리핑 한다.
D3DCS_TOP
모든 버텍스를 시추대의 표면에서 클리핑 한다.
D3DCS_PLANE0 through D3DCS_PLANE5
어플리케이션으로 정의되고 있는 클립면.
ClipIntersection
현재의 클립 스테이터스를 나타내는 클립 교점 플래그. 이 멤버의 값은,ClipUnion 와 같은 플래그이다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetClipStatus ,IDirect3DDevice8::SetClipStatus


D3DCOLORVALUE

칼라값을 기술한다.

typedef struct _D3DCOLORVALUE {
    float r;
    float g;
    float b;
    float a;
} D3DCOLORVALUE;

멤버

r, g, b, 및 a
색의 적, 록, 청, 및 알파의 각 성분을 지정하는 부동 소수점값. 일반적으로, 이러한 값은 0.0 에서 1.0 까지의 값으로, 0.0 은 흑이다.

주의

특수한 이펙트를 내기 위해서(때문에), 이 구조체의 멤버를 0 에서 1 의 범위외의 값으로 설정할 수가 있다. 1 보다 큰 값은, 신을 조사해 흘리는 것 같은 강한 빛을 낳는다. 마이너스의 값은 어두운 빛을 낳아, 실제로는 빛을 장면으로부터 제외해 버린다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

라이팅과 머트리얼의 칼라값


D3DDEVICE_CREATION_PARAMETERS

디바이스의 생성 파라미터를 기술한다.

typedef struct _D3DDEVICE_CREATION_PARAMETERS {
    UINT          AdapterOrdinal;
    D3DDEVTYPE    DeviceType;
    DWORD         hFocusWindow;
    HWND          BehaviorFlags;
} D3DDEVICE_CREATION_PARAMETERS;

멤버

AdapterOrdinal
디스플레이 어댑터를 나타내는 서수. D3DADAPTER_DEFAULT 은 항상 프라이머리 디스플레이 어댑터이다.

임의의 IDirect3D8 메소드의 Adapter 파라미터에는, 이 서수를 사용한다. Direct3D8 오브젝트의 인스턴스가 다르면(자) 사용하는 서수가 다른 경우가 있는 것에 주의한다. 예를 들어, 유저가 멀티 모니터 시스템에 모니터를 추가하거나 시스템으로부터 모니터를 제외했기 때문에, 또는 랩탑을 hot swap 했기 때문에, 어댑터가 시스템에 더해지거나 제외해지거나 하는 경우가 있다. 따라서, 이 서수는 유효하다라고 하는 것이 알고 있는 Direct3D8 에 대해서만 사용해야 한다. 유효한 Direct3D8 인스턴스는, 이 IDirect3DDevice8 인터페이스를 생성 한 Direct3D8 과 이 IDirect3DDevice8 인터페이스를 개입시켜 불려 갔을 때에 IDirect3DDevice8::GetDirect3D 로부터 돌려주어지는 Direct3D8 의 2 개뿐이다.

DeviceType
D3DDEVTYPE 열거형의 멤버. 이 디바이스에 대해서 에뮤레이트 되는 모든 기능을 나타낸다. 이 파라미터의 값에는, 이 디바이스를 생성 한 IDirect3D8::CreateDevice 의 호출에게 건네진 값이 그대로 나타난다.
hFocusWindow
이 Microsoft® Direct3D® 디바이스로 포커스를 설정하는 윈도우 핸들. 이 파라미터의 값에는, 이 디바이스를 생성 한 IDirect3D8::CreateDevice 의 호출에게 건네진 값이 그대로 나타난다.
BehaviorFlags
Microsoft® Direct3D® 디바이스의 전체적인 동작을 제어하는 다음의 플래그의 편성.
D3DCREATE_FPU_PRESERVE
호출측 어플리케이션은, 어플리케이션으로부터 인식할 수 있는 것 같은 방법으로 Direct3D 가 FPU 상태를 변경하는 것을 바라지 않는다. 이 모드에서는, Direct3D 는, FPU 상태를 변경할 필요가 있을 때마다, FPU 상태를 보존 및 복원한다.
D3DCREATE_HARDWARE_VERTEXPROCESSING
하드웨어 버텍스 처리를 지정한다.
D3DCREATE_MIXED_VERTEXPROCESSING
혼합 (소프트웨어와 하드웨어 양쪽 모두)의 버텍스 처리를 지정한다.
D3DCREATE_MULTITHREADED
multi-thread의 확실한 동작을 요구한다. 이것에 의해, Direct3D 는 빈번하게 글로벌 크리티컬 섹 숀을 취득하게 된다.
D3DCREATE_PUREDEVICE
하드웨어의 라스터화, 트랜스 폼, 라이팅, 및 쉐이딩을 지정한다.
D3DCREATE_SOFTWARE_VERTEXPROCESSING
소프트웨어 버텍스 처리를 지정한다.

이 파라미터의 값에는, 이 디바이스를 생성 한 IDirect3D8::CreateDevice 의 호출에게 건네진 값이 그대로 나타난다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetCreationParameters ,IDirect3D8::CreateDevice


D3DDISPLAYMODE

디스플레이 모드를 기술한다.

typedef struct _D3DDISPLAYMODE {
    UINT            Width;
    UINT            Height;
    UINT            RefreshRate;
    D3DFORMAT       Format;
} D3DDISPLAYMODE;

멤버

Width
픽셀 단위로 나타낸 스크린의 폭.
Height
픽셀 단위로 나타낸 스크린의 높이.
RefreshRate
refresh rate. 이 값이 0 의 경우, 어댑터 디폴트를 나타낸다.
Format
D3DFORMAT 열거형의 멤버. 디스플레이 모드의 표면 포맷을 나타낸다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3D8::EnumAdapterModes ,IDirect3D8::GetAdapterDisplayMode ,IDirect3DDevice8::GetDisplayMode


D3DGAMMARAMP

적, 초록, 파랑의 각 램프의 데이터를 저장 한다.

typedef struct _D3DGAMMARAMP {
    WORD                red  [256];
    WORD                green[256];
    WORD                blue [256];
} D3DGAMMARAMP;

멤버

red, green, 및 blue
적, 초록, 및 파랑의 감마 램프를 기술하는 256 WORD 요소의 배열.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetGammaRamp ,IDirect3DDevice8::SetGammaRamp


D3DINDEXBUFFER_DESC

인덱스 버퍼를 기술한다.

typedef struct _D3DINDEXBUFFER_DESC {
    D3DFORMAT           Format;
    D3DRESOURCETYPE     Type;
    DWORD               Usage;
    D3DPOOL             Pool;
    UINT                Size;
} D3DINDEXBUFFER_DESC;

멤버

Format
D3DFORMAT 열거형의 멤버. 인덱스 버퍼 데이터의 표면 포맷을 나타낸다.
Type
인덱스 버퍼로서의 이 리소스를 식별하는 D3DRESOURCETYPE 열거형의 멤버.
Usage
이 리소스의 사용 방법을 지정하는, 다음의 1 개 이상의 플래그의 편성.
D3DUSAGE_DONOTCLIP
인덱스 버퍼의 내용이 결코 클리핑을 요구하지 않는 것을 나타낸다.
D3DUSAGE_RTPATCHES
고차원 프리미티브의 드로잉(Drawing)에 인덱스 버퍼를 사용할때 설정한다.
D3DUSAGE_NPATCHES
N 패치의 드로잉(Drawing)에 인덱스 버퍼를 사용할때 설정한다.
D3DUSAGE_POINTS
포인트 스프라이트 또는 인덱스 첨부 포인트 리스트의 드로잉(Drawing)에, 인덱스 버퍼를 사용할때 설정한다.
D3DUSAGE_SOFTWAREPROCESSING
버퍼가 소프트웨어 처리로 사용되는 것을 나타낸다.
D3DUSAGE_WRITEONLY
인덱스 버퍼에의 기입해 조작 밖에 실행할 수 없는 것을 시스템에 통지한다. 이 플래그를 사용하는 것으로써, 드라이버는 최적인 메모리 영역을 선택해 효율적으로 기입해 조작이나 렌더링을 실행한다. 이 능력을 사용해 생성 된 인덱스 버퍼로부터의 read를 시도하면(자), 퍼포먼스가 저하하는 경우가 있다.
Pool
D3DPOOL 열거형의 멤버. 이 인덱스 버퍼에 할당할 수 있고 있는 메모리의 클래스를 나타낸다.
Size
인덱스 버퍼의 사이즈 (바이트 단위).

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DIndexBuffer8::GetDesc


D3DLIGHT8

일련의 라이트 프로퍼티를 정의한다.

typedef struct _D3DLIGHT8 {
    D3DLIGHTTYPE    Type;
    D3DCOLORVALUE   Diffuse;
    D3DCOLORVALUE   Specular;
    D3DCOLORVALUE   Ambient;
    D3DVECTOR       Position;
    D3DVECTOR       Direction;
    float           Range;
    float           Falloff;
    float           Attenuation0;
    float           Attenuation1;
    float           Attenuation2;
    float           Theta;
    float           Phi;
} D3DLIGHT8;

멤버

Type
광원의 형태. 이 값은 D3DLIGHTTYPE 열거형의 멤버의 언젠가이다.
Diffuse
광원이 방출하는 디퓨즈색. 이 멤버는 D3DCOLORVALUE 구조체이다.
Specular
광원이 방출하는 스펙큐러색. 이 멤버는 D3DCOLORVALUE 구조체이다.
Ambient
광원이 방출하는 앰비언트색. 이 멤버는 D3DCOLORVALUE 구조체이다.
Position
월드 공간내에서의 광원의 위치. D3DVECTOR 구조체로 지정된다. 이 멤버는, 디레크쇼나르라이트에 대해 의미가 없게 무시된다.
Direction
월드 공간에서 빛이 가리킬 방향. D3DVECTOR 구조체로 지정된다. 이 멤버는, 디레크쇼나르라이트 및 spotlight의 경우에게만 의미를 가진다. 이 벡터는 정규화할 필요는 없지만, 제로가 아닌 길이를 가지지 않으면 안 된다.
Range
광원의 유효 거리. 이 멤버의 최대 허용값은 FLT_MAX 의 평방근이다. 이 멤버는 디레크쇼나르라이트에는 영향을 주지 않는다.
Falloff
spotlight의 내부 콘 (Theta로 지정되는 각도)과 외부 콘의 외측 엣지 (Phi 로 지정되는 각도)와의 사이에 휘도가 폴 오프 한다.

라이팅에 대한 폴 오프의 영향은 미묘하다. 게다가 폴 오프 커브를 그리면(자) 다소의 성능 위에의 로스를 입는다. 이러한 이유에 의해, 개발자의 상당수는 이 값을 1.0 으로 설정한다.

Attenuation0, Attenuation1, 및 Attenuation2

빛의 휘도가 거리에 의해 어떻게 변화하는지를 지정하는 값. 디레크쇼나르라이트의 경우, 감쇠값은 무시된다. 이러한 멤버는 감쇠 정수를 나타낸다. 감쇠에 대해서는, 「거리의 증가에 의한 라이트의 감쇠」를 참조할것. 이러한 멤버에 유효한 값의 범위는 0.0 으로부터 무한대이다. 디레크쇼나르라이트 이외의 경우, 3 개의 감쇠값 모든 것을 동시에 0.0 으로 설정해서는 안 된다.

Theta
spotlight의 내부 콘, 즉 충분히 빛으로 비추어지고 있는 spotlight 콘의 각도를 라디안 단위로 나타낸다. 이 값은, 0 으로부터 Phi 에 의한 지정값의 범위에 없으면 안 된다.
Phi
spotlight의 밖원추의 외측의 엣지를 정의하는 각도를 라디안 단위로 나타낸다. 이 원추의 외측에 있는 점은 spotlight로 라이팅 되지 않는다. 이 값은 0 으로부터 pi 의 범위에 없으면 안 된다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetLight ,IDirect3DDevice8::SetLight


D3DLINEPATTERN

선패턴을 기술한다.

typedef struct _D3DLINEPATTERN {
    WORD    wRepeatFactor;
    WORD    wLinePattern;
} D3DLINEPATTERN;

멤버

wRepeatFactor
wLinePattern 멤버로 지정하는 연속한 1 및 0 을 반복하는 회수. 이것에 의해, 어플리케이션에서는 선패턴을 신축할 수 있다.
wLinePattern
선패턴을 지정하는 비트. 예를 들어, 다음의 값은 점선을 생성한다. 1100110011001100.

주의

이러한 값은,D3DRENDERSTATETYPE 열거형의 D3DRS_LINEPATTERN 렌더링 스테이트에서 사용된다.

선패턴은 선의 그리는 방법을 지정한다. 선패턴은, 기점의 위치에 관계없이 항상 같다 (이것은 점묘와는 다르다. 점묘는 오브젝트의 렌더링 방법, 즉 투과성의 표현 방법으로 영향을 준다).

선패턴에서는, 선에 따른 16 개의 픽셀의 온/오프 패턴을 지정한다. wRepeatFactor 멤버에서는,wLinePattern 의 각 엔트리에 대해서 반복하는 픽셀의 수를 지정한다.

동작환경

헤더 : D3d8types.h 로 선언.


D3DLOCKED_BOX

락 된 박스 (볼륨)를 기술한다.

typedef struct _D3DLOCKED_BOX {
    INT                 RowPitch;
    INT                 SlicePitch;
    void*               pBits;
} D3DLOCKED_BOX;

멤버

RowPitch
어느 행의 좌단으로부터 다음의 행의 좌단까지의 바이트 오프셋(offset).
SlicePitch
어느 슬라이스의 좌상으로부터 다음의 가장 깊은 슬라이스의 좌상까지의 바이트 오프셋(offset).
pBits
볼륨 박스의 선두에의 포인터. D3DBOX 가 LockRect 의 호출에 제공되고 있는 경우,pBits 는 볼륨의 선두로부터 적절히 오프셋(offset) 된다.

주의

폭 × 높이의 2D 표면의 슬라이스를 겹쳐 쌓아,폭 × 높이 × 깊이의 볼륨을 생성 하는 것으로, 볼륨은 시각화할 수가 있다. 상세한 것에 대하여는, 「볼륨 텍스쳐 리소스」를 참조할것.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DVolume8::LockBox ,IDirect3DVolumeTexture8::LockBox


D3DLOCKED_RECT

락 된 직사각형 영역을 기술한다.

typedef struct _D3DLOCKED_RECT {
    INT                 Pitch;
    void*               pBits;
} D3DLOCKED_RECT;

멤버

Pitch
바이트 단위로 나타낸 표면 피치.
pBits
락이 끝난 비트에의 포인터. RECT 가 LockRect 의 호출에 제공되고 있는 경우,pBits 는 표면의 선두로부터 적절히 오프셋(offset) 된다.

주의

DXTn 포맷의 피치는, DirectX 7.0 으로 돌려주어지는 것과는 다르다. 현재는, 블록의 행을 가리킨다. 예를 들어, 폭이 16 인 경우, 피치는 4 블록이 된다 (DXT1 의 경우는 4*8, DXT2-5 의 경우는 4*16).

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DCubeTexture8::LockRect ,IDirect3DSurface8::LockRect ,IDirect3DTexture8::LockRect


D3DMATERIAL8

머트리얼 프로퍼티를 지정한다.

typedef struct _D3DMATERIAL8 {
    D3DCOLORVALUE   Diffuse;
    D3DCOLORVALUE   Ambient;
    D3DCOLORVALUE   Specular;
    D3DCOLORVALUE   Emissive;
    float           Power;
} D3DMATERIAL8;

멤버

Diffuse, Ambient, Specular, 및 Emissive
각각, 머트리얼의 디퓨즈색, 앰비언트색, 스펙큐러색, 에미션(emission)색을 지정하는 값. 이러한 값은 D3DCOLORVALUE 구조체이다.
Power
스펙큐러 하이라이트의 선명도를 지정하는 부동 소수점값. 머트리얼의 스펙큐러 하이라이트를 오프로 하려면 , 이 멤버를 0.0 으로 설정한다. 스펙큐러색성분을 0 으로 설정하는 것 만으로는 불충분하다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetMaterial ,IDirect3DDevice8::SetMaterial


D3DMATRIX

행렬을 기술한다.

typedef struct _D3DMATRIX {
    union {
        struct {
            float        _11, _12, _13, _14;
            float        _21, _22, _23, _24;
            float        _31, _32, _33, _34;
            float        _41, _42, _43, _44;

        };
        float m[4][4];
    };
} D3DMATRIX;

주의

Microsoft® Direct3D® 에서는, 투영 행렬의 _34 요소는 부로 할 수 없다. 여기서 부의 값을 사용할 필요가 있는 경우는, 대신에 투영 행렬 전체를 -1 로 스케일 한다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetTransform ,IDirect3DDevice8::MultiplyTransform ,IDirect3DDevice8::SetTransform


D3DPRESENT_PARAMETERS

프레젠테이션 파라미터를 기술한다.

typedef struct _D3DPRESENT_PARAMETERS_ {
    UINT                    BackBufferWidth;
    UINT                    BackBufferHeight;
    D3DFORMAT               BackBufferFormat;
    UINT                    BackBufferCount;

    D3DMULTISAMPLE_TYPE     MultiSampleType;

    D3DSWAPEFFECT           SwapEffect;
    HWND                    hDeviceWindow;
    BOOL                    Windowed;
    BOOL                    EnableAutoDepthStencil;
    D3DFORMAT               AutoDepthStencilFormat;
    DWORD                   Flags;

    UINT                    FullScreen_RefreshRateInHz;
    UINT                    FullScreen_PresentationInterval;

} D3DPRESENT_PARAMETERS;

멤버

BackBufferWidth 및 BackBufferHeight
새로운 스왑 체인의 백 버퍼의 폭과 높이 (픽셀 단위). Windowed 가 FALSE 의 경우 (프레젠테이션은 풀 스크린), 이러한 값은,IDirect3D8::EnumAdapterModes 에 의해 열거된 디스플레이 모드의 몇개의 폭 및 높이로 일치하고 있지 않으면 안 된다. Windowed 가 TRUE 로, 이러한 값중 한쪽이 0 의 경우는,hDeviceWindow (또는 hDeviceWindow 가 NULL 의 경우는 포커스 윈도우)의 클라이언트 영역의 대응하는 넓이가 사용된다.
BackBufferFormat
D3DFORMAT 열거형의 멤버. 이 값은,IDirect3D8::CheckDeviceType 로 검증된 렌더링 타겟의 포맷의 언젠가가 아니면 안된다.

Windowed 를 TRUE 로 설정하는 경우,BackBufferFormat 의 설정은, 현재의 디스플레이 모드의 포맷과 일치하고 있을 필요가 있다. IDirect3DDevice8::GetDisplayMode 를 사용해, 현재의 포맷을 취득한다.

BackBufferCount
이 값에는, 0, 1, 2, 또는 3 을 설정할 수 있다. 0 은 1 으로서 처리되는 것에 주의한다. 백 버퍼의 수를 생성 할 수 없는 경우, 런타임은 메소드의 호출해에 실패해, 생성 할 수 있던 백 버퍼수를 이 값으로 설정한다. 따라서, 어플리케이션은 같은 D3DPRESENT_PARAMETERS 구조체를 지정해 메소드를 2 회 호출할 수가 있어 2 번째에는 호출이 성공하는 것으로 예상된다.

백 버퍼의 수의 최소 값은 1 으로 상정되고 있다. 백 버퍼를 1 개나 생성 할 수 없는 경우, 메소드의 호출은 실패한다. BackBufferCount 의 값은, 사용 가능한 스왑 이펙트세트에 영향을 준다. 특히, D3DSWAPEFFECT_COPY 스왑 이펙트에서는, 존재하는 백 버퍼가 엄밀하게 1 개(살)이 아니면 안된다.

MultiSampleType
D3DMULTISAMPLE_TYPE 열거형의 멤버. SwapEffect 에 D3DSWAPEFFECT_DISCARD 가 설정되어 있지 않은 경우, 이 값은 D3DMULTISAMPLE_NONE 가 아니면 안된다. 멀티 샘플링은, 스왑 이펙트가 D3DSWAPEFFECT_DISCARD 의 경우에게만 지원 된다.
SwapEffect
D3DSWAPEFFECT 열거형의 멤버. 런타임은, 버퍼 스왑 동작에 관해서 지정되고 있는 시멘틱스를 보증한다. 따라서,Windowed 가 TRUE 로,SwapEffect 가 D3DSWAPEFFECT_FLIP 로 설정되어 있는 경우, 런타임은 1 개 여분으로 백 버퍼를 생성 해, 프레젠테이션시에 프런트 버퍼가 되는 것을 모두 카피한다.

D3DSWAPEFFECT_COPY 및 D3DSWAPEFFECT_COPY_VSYNC 의 경우는,BackBufferCount 에 1 이 설정되어 있지 않으면 안 된다.

디버그 런타임에 대해서는, 제시한 후의 버퍼에 노이즈를 저장 하는 것으로, D3DSWAPEFFECT_DISCARD 를 강제한다.

hDeviceWindow
풀 스크린 모드의 경우, 이것은 커버 윈도우이다. 윈도우 모드의 경우, 이것은 IDirect3DDevice8::Present 에 대한 디폴트의 타겟 윈도우이다. 이 값이 NULL 의 경우는, 포커스 윈도우가 사용된다. 멀티 모니터 시스템 등, 복수의 풀 스크린 디바이스를 사용하는 어플리케이션의 경우는, 정확하게 1 개의 디바이스가 디바이스 윈도우로서 포커스 윈도우를 사용해야 한다. 그 외의 모든 윈도우는, 일의의 디바이스 윈도우를 가진다. 그 이외의 경우는, 동작은 정의되지 않고, 어플리케이션은 기대대로 동작하지 않는다.

런타임은 유저에 의한 윈도우 사이즈의 변경을 반영하려고 하지 않는 것에, 주의할 필요가 있다. 이 윈도우가 리셋 되어도, 백 버퍼가 암묵적으로 리셋 될 것은 없다. 다만,Present 메소드는, 윈도우 위치의 변화를 자동적으로 추적한다.

Windowed
어플리케이션이 윈도우 모드로 동작하는 경우는 TRUE 로, 풀 스크린 모드로 동작하는 경우는 FALSE 이다.
EnableAutoDepthStencil
이 값이 TRUE 의 경우, Microsoft® Direct3D® 는 어플리케이션에 대한 깊이 버퍼를 관리한다. 디바이스는, 생성 되면(자), 스텐실 버퍼를 생성 한다. 스텐실 버퍼는, 자동적으로, 디바이스의 렌더링 타겟으로서 설정된다. 디바이스가 리셋 되면(자), 스텐실 버퍼는 자동적으로 파기되어, 새로운 사이즈로 재차 생성 된다.

EnableAutoDepthStencil 가 TRUE 의 경우,AutoDepthStencilFormat 는 유효한 스텐실 포맷이 아니면 안된다.

AutoDepthStencilFormat
D3DFORMAT 열거형의 멤버. 디바이스가 생성 하는 자동 스텐실 표면의 포맷이다. EnableAutoDepthStencil 가 TRUE 가 아닌 경우, 이 멤버는 무시된다.
Flags
이 멤버는, 0 또는 다음의 플래그로 설정할 수 있다.
D3DPRESENTFLAG_LOCKABLE_BACKBUFFER
어플리케이션이 백 버퍼를 직접 잠글 필요가 있는 경우는, 이 플래그를 설정한다. IDirect3D8::CreateDevice 또는 IDirect3DDevice8::Reset 를 호출할 때에, D3DPRESENTFLAG_LOCKABLE_BACKBUFFER 를 지정하고 있지 않는 경우는, 백 버퍼는 잠글 수 없는 것에 주의한다. 락 가능한 백 버퍼에 의해, 일부의 그래픽스 하드웨어 구성에서는 퍼포먼스의 코스트가 향상한다.

락 가능한 백 버퍼로 락 처리를 실행 하면 (또는 읽고 쓰기에 IDirect3DDevice8::CopyRects 를 사용 하면), 많은 카드로 퍼포먼스가 저하한다. 이 경우, 텍스쳐화한 삼각형을 사용해 데이터를 백 버퍼로 이동하는 것을 검토할 필요가 있다.

FullScreen_RefreshRateInHz
디스플레이 어댑터에 의한 스크린의 refresh rate. 윈도우 모드의 경우, 이 값은 0 이 아니면 안된다. 그 이외의 경우, 이 값은,IDirect3D8::EnumAdapterModes 가 돌려주는 refresh rate의 언젠가, 또는 다음의 값의 언젠가가 아니면 안된다.
D3DPRESENT_RATE_DEFAULT
런타임은 프레젠테이션 속도를 선택한다. 윈도우 모드의 경우는, 현재의 속도를 사용한다.
D3DPRESENT_RATE_UNLIMITED
프레젠테이션 속도는, 하드웨어가 프레임을 제공할 수 있는 속도로 동작한다.
FullScreen_PresentationInterval
스왑 체인의 백 버퍼를 프레젠테이션 할 수 있는 최대 레이트. 윈도우 스왑 체인의 경우, 이 값은 D3DPRESENT_INTERVAL_DEFAULT (0)가 아니면 안된다. 풀 스크린 스왑 체인의 경우는, D3DPRESENT_INTERVAL_DEFAULT, 또는 D3DCAPS8 의 PresentationIntervals 멤버에 열거되는 플래그에 대응하는 값을 설정할 수 있다.
D3DPRESENT_INTERVAL_IMMEDIATE
프레젠테이션 처리에 직접 영향을 주는 경우가 있다. 드라이버는 수직귀선간격을 기다리지 않는다.
D3DPRESENT_INTERVAL_ONE
드라이버는 수직귀선간격을 기다린다. 프레젠테이션 처리에의 영향은, 스크린 리프레쉬만큼 빈번하지 않다.
D3DPRESENT_INTERVAL_TWO
드라이버는 수직귀선간격을 기다린다. 프레젠테이션 처리에의 영향은, 스크린 리프레쉬 (1 회 일어나고)만큼 빈번하지 않다.
D3DPRESENT_INTERVAL_THREE
드라이버는 수직귀선간격을 기다린다. 프레젠테이션 처리에의 영향은, 스크린 리프레쉬 (2 회 일어나고)만큼 빈번하지 않다.
D3DPRESENT_INTERVAL_FOUR
드라이버는 수직귀선간격을 기다린다. 프레젠테이션 처리에의 영향은, 스크린 리프레쉬 (3 회 일어나고)만큼 빈번하지 않다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3D8::CreateDevice ,IDirect3DDevice8::CreateAdditionalSwapChain ,IDirect3DDevice8::Present ,IDirect3DDevice8::Reset


D3DRANGE

범위를 정의한다.

typedef struct _D3DRANGE {
    UINT                Offset;
    UINT                Size;
} D3DRANGE;

멤버

Offset
바이트 단위로 나타낸 오프셋(offset).
Size
바이트 단위로 나타낸 사이즈.

동작환경

헤더 : D3d8types.h 로 선언.


D3DRASTER_STATUS

라스터 스테이터스를 기술한다.

typedef struct _D3DRASTER_STATUS {
    BOOL            InVBlank;
    UINT            ScanLine;
} D3DRASTER_STATUS;

멤버

InVBlank
라스터가 수직귀선소거 간격에 있는 경우는 TRUE 이다. 라스터가 수직귀선소거 간격에 없는 경우는 FALSE 이다.
ScanLine
InVBlank 가 FALSE 의 경우, 이 값은, 라스터에 의해 드로잉(Drawing) 된 현재의 주사선에 거의 대응하는 정수값이다. 주사선에는, Microsoft® Direct3D® 의 표면 좌표와 같은 방법으로 번호를 붙일 수 있고 있다. 즉, 0 은 프라이머리 표면의 상단이며, 디스플레이 하단의 값 (표면의 높이 - 1)에 이를 때까지 증가한다.

InVBlank 가 TRUE 의 경우는, 이 값은 0 으로 설정되어 무시할 수 있다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetRasterStatus


D3DRECT

직사각형을 정의한다.

typedef struct _D3DRECT {
    LONG x1;
    LONG y1;
    LONG x2;
    LONG y2;
} D3DRECT;

멤버

x1 및 y1
직사각형의 좌상구석의 좌표.
x2 및 y2
직사각형의 우하구석의 좌표.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::Clear


D3DRECTPATCH_INFO

직사각형의 고차원 패치를 기술한다.

typedef struct _D3DRECTPATCH_INFO {
    UINT                StartVertexOffsetWidth;
    UINT                StartVertexOffsetHeight;
    UINT                Width;
    UINT                Height;
    UINT                Stride;
    D3DBASISTYPE        Basis;
    D3DORDERTYPE        Order;
} D3DRECTPATCH_INFO;

멤버

StartVertexOffsetWidth
버텍스의 수로 나타낸, 시작 버텍스 오프셋(offset)의 폭.
StartVertexOffsetHeight
버텍스의 수로 나타낸, 시작 버텍스 오프셋(offset)의 높이.
Width
버텍스의 수로 나타낸, 각 버텍스의 폭.
Height
버텍스의 수로 나타낸, 각 버텍스의 높이.
Stride
버텍스의 수로 나타낸, 세그먼트(segment)간의 보폭.
Basis
직사각형의 고차원 패치의 기본 타입을 정의하는 D3DBASISTYPE 열거형의 멤버.
Order
고차원 패치의 오더타임을 정의하는 D3DORDERTYPE 열거형의 멤버.

주의

개개의 직사각형 패치의 스트림 (비모자이크)을 렌더링 하려면 , 지오메트리를 가늘고 긴 (1 × N) 직사각형 패치로서 해석해야 한다. 이러한 스트립 (입방체 베쥬)의 D3DRECTPATCH_INFO 구조체는, 다음과 같이 설정된다.

D3DRECTPATCH_INFO RectInfo;

RectInfo.Width = 4;
RectInfo.Height= 4;
RectInfo.Stride= 4;
RectInfo.Basis =  D3DBASIS_BEZIER;
RectInfo.Order =  D3DORDER_CUBIC;
RectInfo.StartVertexOffsetWidth = 0;
RectInfo.StartVertexOffsetHeight = 4*i;  // 변수 i 는 렌더링 하는 패치의 인덱스이다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::DrawRectPatch


D3DSURFACE_DESC

표면을 기술한다.

typedef struct _D3DSURFACE_DESC {
    D3DFORMAT           Format;
    D3DRESOURCETYPE     Type;
    DWORD               Usage;
    D3DPOOL             Pool;
    UINT                Size;
    D3DMULTISAMPLE_TYPE MultiSampleType;
    UINT                Width;
    UINT                Height;
} D3DSURFACE_DESC;

멤버

Format
표면 포맷을 나타내는 D3DFORMAT 열거형의 멤버.
Type
표면으로서의 이 리소스를 나타내는 D3DRESOURCETYPE 열거형의 멤버.
Usage
이 리소스의 사용 방법을 지정하는, 다음의 1 개 이상의 플래그의 편성.
D3DUSAGE_DEPTHSTENCIL
표면이 스텐실 표면으로서 사용되는 것을 나타낸다.
D3DUSAGE_RENDERTARGET
표면이 렌더링 타겟으로서 사용되는 것을 나타낸다.
Pool
이 표면에 할당할 수 있고 있는 메모리의 클래스를 지정하는 D3DPOOL 열거형의 멤버.
Size
바이트 단위로 나타내진 표면의 사이즈.
MultiSampleType
D3DMULTISAMPLE_TYPE 열거형의 멤버. 표면이 지원 하는 풀 신 멀티 샘플링의 레벨을 지정한다.
Width
픽셀 단위로 나타낸 표면의 폭.
Height
픽셀 단위로 나타낸 표면의 높이.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DCubeTexture8::GetLevelDesc ,IDirect3DSurface8::GetDesc ,IDirect3DTexture8::GetLevelDesc


D3DTRIPATCH_INFO

삼각형의 고차원 패치를 기술한다.

typedef struct _D3DTRIPATCH_INFO {
    UINT                StartVertexOffset;
    UINT                NumVertices;
    D3DBASISTYPE        Basis;
    D3DORDERTYPE        Order;
} D3DTRIPATCH_INFO;

멤버

StartVertexOffset
버텍스의 수로 나타낸, 시작 버텍스 오프셋(offset).
NumVertices
버텍스의 수.
Basis
삼각형의 고차원 패치의 기본 타입을 정의하는 D3DBASISTYPE 열거형의 멤버.
Order
삼각형의 고차원 패치의 오더타임을 정의하는 D3DORDERTYPE 열거형의 멤버.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::DrawTriPatch


D3DVECTOR

벡터를 정의한다.

typedef struct _D3DVECTOR {
    float x;
    float y;
    float z;
} D3DVECTOR;

멤버

x, y 및 z
벡터를 기술하는 부동 소수점값.

동작환경

헤더 : D3d8types.h 로 선언.


D3DVERTEXBUFFER_DESC

버텍스 버퍼를 기술한다.

typedef struct _D3DVERTEXBUFFER_DESC {
    D3DFORMAT           Format;
    D3DRESOURCETYPE     Type;
    DWORD               Usage;
    D3DPOOL             Pool;
    UINT                Size;
    DWORD               FVF;
} D3DVERTEXBUFFER_DESC;

멤버

Format
버텍스 버퍼 데이터의 표면 포맷을 나타내는 D3DFORMAT 열거형의 멤버.
Type
버텍스 버퍼로서의 이 리소스를 식별하는 D3DRESOURCETYPE 열거형의 멤버.
Usage
이 리소스의 사용 방법을 지정하는, 다음의 1 개 이상의 플래그의 편성.
D3DUSAGE_DONOTCLIP
버텍스 버퍼의 내용이 결코 클리핑을 요구하지 않는 것을 나타낸다.
D3DUSAGE_RTPATCHES
고차원 프리미티브의 드로잉(Drawing)에 버텍스 버퍼를 사용할때 설정한다.
D3DUSAGE_NPATCHES
N 패치의 드로잉(Drawing)에 버텍스 버퍼를 사용할때 설정한다.
D3DUSAGE_POINTS
포인트 스프라이트 또는 인덱스 첨부 포인트 리스트의 드로잉(Drawing)에, 버텍스 버퍼를 사용할때 설정한다.
D3DUSAGE_SOFTWAREPROCESSING
소프트웨어 버텍스 처리로 사용하는 버텍스 버퍼인 것을 나타낸다.
D3DUSAGE_WRITEONLY
버텍스 버퍼에의 기입해 조작 밖에 실행하지 않는 것을 시스템에 알린다. 이 플래그를 사용하는 것으로써, 드라이버는 최적인 메모리 영역을 선택해 효율적으로 기입해 조작이나 렌더링을 실행한다. 이 능력을 이용해 생성 한 버텍스 버퍼로부터 읽기를 실시하려고 하면, 퍼포먼스가 저하하는 일이 있다.
Pool
이 버텍스 버퍼에 할당할 수 있고 있는 메모리의 클래스를 지정하는 D3DPOOL 열거형의 멤버.
Size
버텍스 버퍼의 사이즈 (바이트 단위).
FVF
이 버퍼내의 버텍스의 버텍스 포맷을 나타내는유연한 버텍스 포맷 플래그의 편성.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DVertexBuffer8::GetDesc


D3DVIEWPORT8

3D 볼륨이 투영 되는 렌더링 타겟 표면의 윈도우의 크기를 정의한다.

typedef struct _D3DVIEWPORT8 {
    DWORD       X;
    DWORD       Y;
    DWORD       Width;
    DWORD       Height;
    float       MinZ;
    float       MaxZ;
} D3DVIEWPORT8;

멤버

X 및 Y
렌더링 타겟 표면 위에의 뷰 포토의 좌상구석을 나타내는 픽셀 좌표. 표면의 서브 세트에 렌더링 하므로 없으면, 이러한 멤버는 0 으로 설정할 수 있다.
Width 및 Height
렌더링 타겟 표면 위에의 뷰 포토의 넓이 (픽셀 단위). 표면의 서브 세트로 한정해 렌더링 하므로 없으면, 이러한 멤버에는 렌더링 타겟 표면의 넓이를 설정한다.
MinZ 및 MaxZ
장면을 렌더링 하는 깊이값의 범위를 나타내는 값. 클립 볼륨의 최소 값과 최대치. 대부분의 어플리케이션에서는, 이러한 값을 각각 0.0 및 1.0 으로 설정한다. 투영 행렬의 적용 후에 클리핑을 한다.

주의

X,Y,Width, 및 Height 의 각 멤버는, 렌더링 타겟 표면 위에의 뷰 포토의 위치와 넓이를 기술한다. 보통, 어플리케이션은 타겟 표면 전체에 렌더링 하므로, 640 x 480 의 표면에 렌더링 하면 와, 이러한 멤버는 각각 0, 0, 640, 480 이 된다. 일반적으로,MinZ 및 MaxZ 는 0.0 및 1.0 으로 설정되지만, 다른 값을 설정해 특수 효과를 낼 수도 있다. 예를 들어, 양쪽 모두의 값을 0.0 으로 설정 하면, 장면의 foreground에 오브젝트가 렌더링 된다. 또, 양쪽 모두의 값을 1.0 으로 설정 하면, 오브젝트가 백그라운드에 렌더링 된다.

디바이스의 뷰 포토 파라미터를 변경 하면 (IDirect3DDevice8::SetViewport 메소드의 호출에 의해), 드라이버는 새로운 트랜스 폼 행렬을 생성 한다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetViewport ,IDirect3DDevice8::SetViewport


D3DVOLUME_DESC

볼륨을 기술한다.

typedef struct _D3DVOLUME_DESC {
    D3DFORMAT           Format;
    D3DRESOURCETYPE     Type;
    DWORD               Usage;
    D3DPOOL             Pool;
    UINT                Size;
    UINT                Width;
    UINT                Height;
    UINT                Depth;
} D3DVOLUME_DESC;

멤버

Format
볼륨의 표면 포맷을 나타내는 D3DFORMAT 열거형의 멤버.
Type
볼륨으로서의 이 리소스를 식별하는 D3DRESOURCETYPE 열거형의 멤버.
Usage
현재는 사용되어 있지 않다. 항상 0 이 돌려주어진다.
Pool
이 볼륨에 할당할 수 있고 있는 메모리의 클래스를 지정하는 D3DPOOL 열거형의 멤버.
Size
바이트 단위로 나타내진 볼륨의 사이즈.
Width
픽셀 단위로 나타내진 볼륨의 폭.
Height
픽셀 단위로 나타내진 볼륨의 높이.
Depth
픽셀 단위로 나타내진 볼륨의 깊이.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DVolume8::GetDesc ,IDirect3DVolumeTexture8::GetLevelDesc


열거형

여기에서는, Microsoft® Direct3D® 로 사용되는 이하의 열거형에 대해 기술한다.

  • D3DBACKBUFFER_TYPE
  • D3DBLEND
  • D3DBLENDOP
  • D3DCMPFUNC
  • D3DCUBEMAP_FACES
  • D3DCULL
  • D3DDEBUGMONITORTOKENS
  • D3DDEVTYPE
  • D3DFILLMODE
  • D3DFOGMODE
  • D3DFORMAT
  • D3DBASISTYPE
  • D3DLIGHTTYPE
  • D3DMATERIALCOLORSOURCE
  • D3DMULTISAMPLE_TYPE
  • D3DORDERTYPE
  • D3DPATCHEDGESTYLE
  • D3DPOOL
  • D3DPRIMITIVETYPE
  • D3DRENDERSTATETYPE
  • D3DRESOURCETYPE
  • D3DSHADEMODE
  • D3DSTATEBLOCKTYPE
  • D3DSTENCILOP
  • D3DSWAPEFFECT
  • D3DTEXTUREADDRESS
  • D3DTEXTUREFILTERTYPE
  • D3DTEXTUREOP
  • D3DTEXTURESTAGESTATETYPE
  • D3DTEXTURETRANSFORMFLAGS
  • D3DTRANSFORMSTATETYPE
  • D3DVERTEXBLENDFLAGS
  • D3DZBUFFERTYPE


D3DBACKBUFFER_TYPE

백 버퍼의 타입을 기술하는 정수를 정의한다.

typedef enum _D3DBACKBUFFER_TYPE {
    D3DBACKBUFFER_TYPE_MONO         = 0,
    D3DBACKBUFFER_TYPE_LEFT         = 1,
    D3DBACKBUFFER_TYPE_RIGHT        = 2,

    D3DBACKBUFFER_TYPE_FORCE_DWORD  = 0x7fffffff
} D3DBACKBUFFER_TYPE;

정수

D3DBACKBUFFER_TYPE_MONO
비스테레오 스왑 체인을 지정한다.
D3DBACKBUFFER_TYPE_LEFT
스왑 체인의 스테레오 페어의 좌측을 지정한다.
D3DBACKBUFFER_TYPE_RIGHT
스왑 체인의 스테레오 페어의 우측을 지정한다.
D3DBACKBUFFER_TYPE_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

DirectX 8.0 에서는 스테레오 뷰는 지원되어 있지 않기 때문에, 이 열거형의 D3DBACKBUFFER_TYPE_LEFT 및 D3DBACKBUFFER_TYPE_RIGHT 의 값은 Direct3D 에서는 사용되지 않는다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetBackBuffer ,IDirect3DSwapChain8::GetBackBuffer


D3DBLEND

지원 되고 있는블렌딩 모드를 정의한다.

typedef enum _D3DBLEND {
    D3DBLEND_ZERO               =  1,
    D3DBLEND_ONE                =  2,
    D3DBLEND_SRCCOLOR           =  3,
    D3DBLEND_INVSRCCOLOR        =  4,
    D3DBLEND_SRCALPHA           =  5,
    D3DBLEND_INVSRCALPHA        =  6,
    D3DBLEND_DESTALPHA          =  7,
    D3DBLEND_INVDESTALPHA       =  8,
    D3DBLEND_DESTCOLOR          =  9,
    D3DBLEND_INVDESTCOLOR       = 10,
    D3DBLEND_SRCALPHASAT        = 11,
    D3DBLEND_BOTHSRCALPHA       = 12,
    D3DBLEND_BOTHINVSRCALPHA    = 13,

    D3DBLEND_FORCE_DWORD        = 0x7fffffff
} D3DBLEND;

정수

D3DBLEND_ZERO
블렌딩 계수는 (0, 0, 0, 0).
D3DBLEND_ONE
블렌딩 계수는 (1, 1, 1, 1).
D3DBLEND_SRCCOLOR
블렌딩 계수는 (Rs, Gs, Bs, As).
D3DBLEND_INVSRCCOLOR
블렌딩 계수는 (1-Rs, 1-Gs, 1-Bs, 1-As).
D3DBLEND_SRCALPHA
블렌딩 계수는 (As, As, As, As).
D3DBLEND_INVSRCALPHA
블렌딩 계수는 (1-As, 1-As, 1-As, 1-As).
D3DBLEND_DESTALPHA
블렌딩 계수는 (Ad, Ad, Ad, Ad).
D3DBLEND_INVDESTALPHA
블렌딩 계수는 (1-Ad, 1-Ad, 1-Ad, 1-Ad).
D3DBLEND_DESTCOLOR
블렌딩 계수는 (Rd, Gd, Bd, Ad).
D3DBLEND_INVDESTCOLOR
블렌딩 계수는 (1-Rd, 1-Gd, 1-Bd, 1-Ad).
D3DBLEND_SRCALPHASAT
블렌딩 계수는, (f, f, f, 1), f = min(As, 1-Ad).
D3DBLEND_BOTHSRCALPHA
폐지되고 있다. Microsoft® DirectX® 6.0 이후에서는, 전송원 및 전송처의 블렌딩 계수에 D3DBLEND_SRCALPHA 과 D3DBLEND_INVSRCALPHA 를 각각 다른 호출로 설정하는 것으로써, 같은 효과를 얻을 수 있다.
D3DBLEND_BOTHINVSRCALPHA
전송원의 블렌딩 계수는 (1-As, 1-As, 1-As, 1-As)으로, 전송처의 블렌딩 계수는 (As, As, As, As)이다. 전송처의 블렌딩의 선택은 무효가 된다. 이 블렌딩 모드는,D3DRS_SRCBLEND 렌더링 스테이트 에 대해서만 지원 된다.
D3DBLEND_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

전술의 멤버의 설명에서는, 전송원 및 전송처의 RGBA 값은 첨자 s 및 d 에 의해 나타난다.

이 열거형의 값은,D3DRS_DESTBLEND 렌더링 스테이트에 의해 사용된다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DBLENDOP

지원 되고 있는 블렌딩 처리를 정의한다.

typedef enum _D3DBLENDOP {
    D3DBLENDOP_ADD              = 1,
    D3DBLENDOP_SUBTRACT         = 2,
    D3DBLENDOP_REVSUBTRACT      = 3,
    D3DBLENDOP_MIN              = 4,
    D3DBLENDOP_MAX              = 5,

    D3DBLENDOP_FORCE_DWORD      = 0x7fffffff
} D3DBLENDOP;

정수

D3DBLENDOP_ADD
결과는 전송 바탕으로 전송처가 가산된다.

결과 = 전송원 + 전송처

D3DBLENDOP_SUBTRACT
결과는 전송원으로부터 전송처가 감산된다.

결과 = 전송원 - 전송처

D3DBLENDOP_REVSUBTRACT
결과는 전송처로부터 전송원이 감산된다.

결과 = 전송처 - 전송원

D3DBLENDOP_MIN
결과는 전송원과 전송처의 최소 값이다.

결과 = MIN(전송원, 전송처)

D3DBLENDOP_MAX
결과는 전송원과 전송처의 최대치이다.

결과 = MAX(전송원, 전송처)

D3DBLENDOP_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거형은,D3DRS_BLENDOP 렌더링 스테이트에서 사용되는 값을 정의한다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DPRIMCAPS8 ,D3DRENDERSTATETYPE


D3DCMPFUNC

지원 되는 비교 함수를 정의한다.

typedef enum _D3DCMPFUNC {
    D3DCMP_NEVER                = 1,
    D3DCMP_LESS                 = 2,
    D3DCMP_EQUAL                = 3,
    D3DCMP_LESSEQUAL            = 4,
    D3DCMP_GREATER              = 5,
    D3DCMP_NOTEQUAL             = 6,
    D3DCMP_GREATEREQUAL         = 7,
    D3DCMP_ALWAYS               = 8,

    D3DCMP_FORCE_DWORD          = 0x7fffffff
} D3DCMPFUNC;

정수

D3DCMP_NEVER
테스트는 항상 실패한다.
D3DCMP_LESS
새로운 픽셀값이, 현재의 픽셀값보다 작을 때에 응한다.
D3DCMP_EQUAL
새로운 픽셀값이, 현재의 픽셀값과 동일할 때에 응한다.
D3DCMP_LESSEQUAL
새로운 픽셀값이, 현재의 픽셀값이하 때에 응한다.
D3DCMP_GREATER
새로운 픽셀값이, 현재의 픽셀값보다 클 때에 응한다.
D3DCMP_NOTEQUAL
새로운 픽셀값이, 현재의 픽셀값과 동일하지 않을 때에 응한다.
D3DCMP_GREATEREQUAL
새로운 픽셀값이, 현재의 픽셀값이상 때에 응한다.
D3DCMP_ALWAYS
테스트는 항상 패스한다.
D3DCMP_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거형의 값은,D3DRS_ZFUNC ,D3DRS_ALPHAFUNC , 및 D3DRS_STENCILFUNC 의 각 렌더링 스테이트에 대해서 지원 되는 비교 함수를 정의하는 것이다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DCUBEMAP_FACES

큐브 맵의 면을 정의한다.

typedef enum _D3DCUBEMAP_FACES {
    D3DCUBEMAP_FACE_POSITIVE_X     = 0,
    D3DCUBEMAP_FACE_NEGATIVE_X     = 1,
    D3DCUBEMAP_FACE_POSITIVE_Y     = 2,
    D3DCUBEMAP_FACE_NEGATIVE_Y     = 3,
    D3DCUBEMAP_FACE_POSITIVE_Z     = 4,
    D3DCUBEMAP_FACE_NEGATIVE_Z     = 5,

    D3DCUBEMAP_FACE_FORCE_DWORD    = 0xffffffff
} D3DCUBEMAP_FACES;

정수

D3DCUBEMAP_FACE_POSITIVE_X
큐브 맵의 정방향의 x 면.
D3DCUBEMAP_FACE_NEGATIVE_X
큐브 맵의 부방향의 x 면.
D3DCUBEMAP_FACE_POSITIVE_Y
큐브 맵의 정방향의 y 면.
D3DCUBEMAP_FACE_NEGATIVE_Y
큐브 맵의 부방향의 y 면.
D3DCUBEMAP_FACE_POSITIVE_Z
큐브 맵의 정방향의 z 면.
D3DCUBEMAP_FACE_NEGATIVE_Z
큐브 맵의 부방향의 z 면.
D3DCUBEMAP_FACE_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DCubeTexture8::AddDirtyRect ,IDirect3DCubeTexture8::GetCubeMapSurface ,IDirect3DCubeTexture8::LockRect ,IDirect3DCubeTexture8::UnlockRect


D3DCULL

지원 하는 카링모드를 정의한다.

typedef enum _D3DCULL {
    D3DCULL_NONE                = 1,
    D3DCULL_CW                  = 2,
    D3DCULL_CCW                 = 3,

    D3DCULL_FORCE_DWORD         = 0x7fffffff
} D3DCULL;

정수

D3DCULL_NONE
배면의 카링은 하지 않는다.
D3DCULL_CW
배면을 우회전으로 카링 한다.
D3DCULL_CCW
배면을 왼쪽 돌아에 카링 한다.
D3DCULL_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거형의 값은,D3DRS_CULLMODE 렌더링 스테이트에 의해 사용된다. 카링모드는, 지오메트리를 렌더링 하면나무의 배면의 카링 방법을 정의한다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DPRIMCAPS8 ,D3DRENDERSTATETYPE


D3DDEBUGMONITORTOKENS

디버그 모니터 토큰을 정의한다.

typedef enum _D3DDEBUGMONITORTOKENS {
    D3DDMT_ENABLE          = 0,
    D3DDMT_DISABLE         = 1,

    D3DDMT_FORCE_DWORD     = 0x7fffffff
} D3DDEBUGMONITORTOKENS;

정수

D3DDMT_ENABLE
디버그 모니터를 유효하게 한다.
D3DDMT_DISABLE
디버그 모니터를 무효로 한다.
D3DDMT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거형의 값은,D3DRS_DEBUGMONITORTOKEN 렌더링 스테이트에서만 사용되어 디버그 빌드에게만 관련한다.

동작환경

헤더 : d3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DDEVTYPE

디바이스의 종류를 정의한다.

typedef enum _D3DDEVTYPE {
    D3DDEVTYPE_HAL         = 1,
    D3DDEVTYPE_REF         = 2,
    D3DDEVTYPE_SW          = 3,

    D3DDEVTYPE_FORCE_DWORD = 0xffffffff
} D3DDEVTYPE;

정수

D3DDEVTYPE_HAL
라스터화와 쉐이딩은 하드웨어로 실시해, 트랜스 폼과 라이팅에는 소프트웨어, 하드웨어, 또는 그 양쪽 모두를 사용한다.
D3DDEVTYPE_REF
Microsoft® Direct3D® 의 기능은 소프트웨어에 이행 되고 있다. 다만, 레퍼런스 래스터라이저는, 이용 가능한 경우는 항상, 특별한 CPU 명령을 이용한다.
D3DDEVTYPE_SW
IDirect3D8::RegisterSoftwareDevice 를 사용해 Direct3D 에 등록된 플러그 가능한 소프트웨어 디바이스.
D3DDEVTYPE_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3D8::CheckDeviceFormat ,IDirect3D8::CheckDeviceMultiSampleType ,IDirect3D8::CheckDeviceType ,IDirect3D8::CreateDevice ,IDirect3D8::GetDeviceCaps ,D3DDEVICE_CREATION_PARAMETERS


D3DFILLMODE

전부 칠해 모드를 기술하는 정수를 정의한다.

typedef enum _D3DFILLMODE {
    D3DFILL_POINT               = 1,
    D3DFILL_WIREFRAME           = 2,
    D3DFILL_SOLID               = 3,

    D3DFILL_FORCE_DWORD         = 0x7fffffff
} D3DFILLMODE;

정수

D3DFILL_POINT
점으로써 전부 칠한다.
D3DFILL_WIREFRAME
와이어 프레임으로 전부 칠한다. 현재, 이 전부 칠해 모드는, DrawPrimitive 메소드의 사용시, 클립 된 원시적인 것은 동작하지 않는다.
D3DFILL_SOLID
면에서 전부 칠한다.
D3DFILL_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거형의 값은,D3DRS_FILLMODE 렌더링 스테이트에 의해 사용된다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DFOGMODE

fog 모드를 기술하는 정수를 정의한다.

typedef enum _D3DFOGMODE {
    D3DFOG_NONE                 = 0,
    D3DFOG_EXP                  = 1,
    D3DFOG_EXP2                 = 2,
    D3DFOG_LINEAR               = 3,

    D3DFOG_FORCE_DWORD          = 0x7fffffff
} D3DFOGMODE;

정수

D3DFOG_NONE
fog 이펙트는 없다.
D3DFOG_EXP
다음의 방정식의 지수로, fog 이펙트가 늘어난다.

D3DFOG_EXP2
다음의 방정식의 지수의 2 승으로, fog 이펙트가 늘어난다.

D3DFOG_LINEAR
다음의 방정식의 시점과 종점의 사이에 선형에 fog 이펙트가 늘어난다.

이것은, 현재 지원 되고 있는 유일한 fog 모드이다.

D3DFOG_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거형의 값은,D3DRS_FOGTABLEMODE 및 D3DRS_FOGVERTEXMODE 의 렌더링 스테이트에 의해 사용된다.

fog는, 투명도를 나타내는 기준이다. 이 경우, fog의 방정식에 의해 생성되는 fog의 값이 작을 정도(수록), 오브젝트는 보이기 어려워진다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DFORMAT

다양한 종류의 표면 포맷을 정의한다.

typedef enum _D3DFORMAT {
    D3DFMT_UNKNOWN              =   0,

    D3DFMT_R8G8B8               =  20,
    D3DFMT_A8R8G8B8             =  21,
    D3DFMT_X8R8G8B8             =  22,
    D3DFMT_R5G6B5               =  23,
    D3DFMT_X1R5G5B5             =  24,
    D3DFMT_A1R5G5B5             =  25,
    D3DFMT_A4R4G4B4             =  26,
    D3DFMT_R3G3B2               =  27,
    D3DFMT_A8                   =  28,
    D3DFMT_A8R3G3B2             =  29,
    D3DFMT_X4R4G4B4             =  30,

    D3DFMT_A8P8                 =  40,
    D3DFMT_P8                   =  41,

    D3DFMT_L8                   =  50,
    D3DFMT_A8L8                 =  51,
    D3DFMT_A4L4                 =  52,

    D3DFMT_V8U8                 =  60,
    D3DFMT_L6V5U5               =  61,
    D3DFMT_X8L8V8U8             =  62,
    D3DFMT_Q8W8V8U8             =  63,
    D3DFMT_V16U16               =  64,
    D3DFMT_W11V11U10            =  65,

    D3DFMT_UYVY                 =  MAKEFOURCC('U', 'Y', 'V', 'Y'),
    D3DFMT_YUY2                 =  MAKEFOURCC('Y', 'U', 'Y', '2'),
    D3DFMT_DXT1                 =  MAKEFOURCC('D', 'X', 'T', '1'),
    D3DFMT_DXT2                 =  MAKEFOURCC('D', 'X', 'T', '2'),
    D3DFMT_DXT3                 =  MAKEFOURCC('D', 'X', 'T', '3'),
    D3DFMT_DXT4                 =  MAKEFOURCC('D', 'X', 'T', '4'),
    D3DFMT_DXT5                 =  MAKEFOURCC('D', 'X', 'T', '5'),

    D3DFMT_D16_LOCKABLE         =  70,
    D3DFMT_D32                  =  71,
    D3DFMT_D15S1                =  73,
    D3DFMT_D24S8                =  75,
    D3DFMT_D16                  =  80,
    D3DFMT_D24X8                =  77,
    D3DFMT_D24X4S4              =  79,

    D3DFMT_VERTEXDATA           = 100,
    D3DFMT_INDEX16              = 101,
    D3DFMT_INDEX32              = 102,

    D3DFMT_FORCE_DWORD          = 0xFFFFFFFF
} D3DFORMAT;

정수

D3DFMT_UNKNOWN
표면 포맷은 불명하다.
D3DFMT_R8G8B8
24 비트의 RGB 픽셀 포맷.
D3DFMT_A8R8G8B8
알파 첨부의 32 비트 ARGB 픽셀 포맷.
D3DFMT_X8R8G8B8
32 비트의 RGB 픽셀 포맷으로, 그 중 8 비트는 각 색을 위해서(때문에) 확보되고 있다.
D3DFMT_R5G6B5
16 비트의 RGB 픽셀 포맷.
D3DFMT_X1R5G5B5
16 비트의 픽셀 포맷으로, 그 중 5 비트는 각 색을 위해서(때문에) 확보되고 있다.
D3DFMT_A1R5G5B5
16 비트의 픽셀 포맷으로, 각 색에 5 비트가, 알파 (투과형 텍셀)에 1 비트가, 각각 확보되고 있다.
D3DFMT_A4R4G4B4
16 비트의 ARGB 픽셀 포맷.
D3DFMT_R3G3B2
8 비트의 RGB 텍스쳐 포맷.
D3DFMT_A8
8 비트의 알파만.
D3DFMT_A8R3G3B2
16 비트의 ARGB 텍스쳐 포맷.
D3DFMT_X4R4G4B4
16 비트의 RGB 픽셀 포맷으로, 그 중 4 비트는 각 색을 위해서(때문에) 확보되고 있다.
D3DFMT_A8P8
표면은, 8 비트의 알파가 붙은 8 비트의 칼라 인덱스 첨부.
D3DFMT_P8
표면은, 8 비트의 칼라 인덱스 첨부.
D3DFMT_L8
8 비트의 휘도만.
D3DFMT_A8L8
16 비트의 알파 휘도.
D3DFMT_A4L4
8 비트의 알파 휘도.
D3DFMT_V8U8
16 비트의 범프 맵 포맷.
D3DFMT_L6V5U5
휘도가 붙은 16 비트의 범프 맵 포맷.
D3DFMT_X8L8V8U8
휘도 첨부의 32 비트 범프 맵 포맷으로, 8 비트는 각 요소를 위해서(때문에) 확보되고 있다.
D3DFMT_Q8W8V8U8
32 비트의 범프 맵 포맷.
D3DFMT_V16U16
32 비트의 범프 맵 포맷.
D3DFMT_W11V11U10
32 비트의 범프 맵 포맷.
D3DFMT_UYVY
UYVY 포맷 (PC98 준거).
D3DFMT_YUY2
YUY2 포맷 (PC98 준거).
D3DFMT_DXT1
DXT1 압축 텍스쳐 포맷.
D3DFMT_DXT2
DXT2 압축 텍스쳐 포맷.
D3DFMT_DXT3
DXT3 압축 텍스쳐 포맷.
D3DFMT_DXT4
DXT4 압축 텍스쳐 포맷.
D3DFMT_DXT5
DXT5 압축 텍스쳐 포맷.
D3DFMT_D16_LOCKABLE
16 비트의 Z 버퍼 비트 깊이. 이것은 어플리케이션으로 락 가능한 표면 포맷이다.
D3DFMT_D32
32 비트의 Z 버퍼 비트 깊이.
D3DFMT_D15S1
16 비트의 Z 버퍼 비트 깊이로, 15 비트가 깊이 채널에, 1 비트가 스텐실 채널에 확보되고 있다.
D3DFMT_D24S8
32 비트의 Z 버퍼 비트 깊이로, 24 비트가 깊이 채널에, 8 비트가 스텐실 채널에 확보되고 있다.
D3DFMT_D16
16 비트의 Z 버퍼 비트 깊이.
D3DFMT_D24X8
32 비트의 Z 버퍼 비트 깊이로, 24 비트가 깊이 채널에 확보되고 있다.
D3DFMT_D24X4S4
32 비트의 Z 버퍼 비트 깊이로, 24 비트가 깊이 채널에, 4 비트가 스텐실 채널에 확보되고 있다.
D3DFMT_VERTEXDATA
버텍스 버퍼 표면을 기술한다.
D3DFMT_INDEX16
16 비트의 인덱스 버퍼의 비트 깊이.
D3DFMT_INDEX32
32 비트의 인덱스 버퍼의 비트 깊이.
D3DFMT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

렌더링 타겟 포맷은 D3DFMT_X1R5G5B5, D3DFMT_R5G6B5, D3DFMT_X8R8G8B8, 및 D3DFMT_A8R8G8B8 에 제한되고 있는 것에 주의 해야 한다.

비트 오더는, 최상정도 비트 (MSB)가 선두이다. 따라서, D3DFMT_A8L8 는, 이 2 바이트 포맷의 상위 바이트가 알파인 것을 나타내고 있다. D3DFMT_D16 는, 16 비트의 정수값으로, 어플리케이션으로 락 가능한 표면을 나타낸다.

D3DFMT_D16_LOCKABLE를 제외한 모든 스텐실 포맷은, 픽셀 단위에 특정의 비트 오더를 지정하지 않고, 어플리케이션으로 잠글 수 없기 때문에, 드라이버는 깊이 채널로 지정된 비트수보다 많은 비트를 사용할 수 있다 (다만, 스텐실 채널에서는 사용할 수 없다).

픽셀 포맷은, 불투명 DWORD 식별자에 의해 나타난다. 이러한 DWORD 의 포맷이 선택되고 있는 것은, IHV 로 정의되고 있는 확장 포맷의 표현을 가능하게 해, 확립되어 있는 FOURCC 방식을 도입하기 때문에 있다. Microsoft® Direct3D® 런타임이 인식하는 포맷군은,D3DFORMAT 로 정의되고 있다.

IHV 로 제공되는 포맷 및 많은 FOURCC 코드는,D3DFORMAT 열거형의 일람에는 나타나지 않은 것에 주의할 필요가 있다. 이 열거형의 포맷은, 런타임에 의해 인정되고 있는 점이 다른 포맷과 다르다. 즉, 레퍼런스 래스터라이저는, 이러한 형태의 모두로 동작한다. IHV 제공의 포맷은, 카드 단위에 개개의 IHV 에 의해 지원 된다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3D8::CheckDeviceFormat ,FOURCC 코드


D3DBASISTYPE

고차원 패치 표면의 기본 타입을 정의한다.

typedef enum _D3DBASISTYPE{
   D3DBASIS_BEZIER        = 0,
   D3DBASIS_BSPLINE       = 1,
   D3DBASIS_INTERPOLATE   = 2,

   D3DBASIS_FORCE_DWORD   = 0x7fffffff
} D3DBASISTYPE;

정수

D3DBASIS_BEZIER
입력 버텍스는, 일련의 베쥬 패치로서 다루어진다. 지정하는 버텍스의 수는, 3 + 1 으로 결론지을 수 있는 수가 아니면 안된다. 이 조건을 채우지 않는 메쉬 부분은 렌더링 되지 않는다. 각 호출에 의해 렌더링 되는 표면의 안쪽에 있는 서브 패치의 사이는, 완전하게 연속하고 있는 것과 상정되고 있다. 생성 되는 표면상에 있는 것이 보증되고 있는 것은, 각 서브 패치의 구석에 있는 버텍스 뿐이다.
D3DBASIS_BSPLINE
입력 버텍스는, B 스플라인 표면의 제어 포인트로서 다루어진다. 렌더링 되는 개구부의 수는, 그 방향의 개구부의 수부터 2 개 적다. 일반적으로, 지정되고 있는 제어 버텍스는, 생성되는 표면에 포함되지 않았다.
D3DBASIS_INTERPOLATE
지정 떠날 수 있어 모든 입력 버텍스를 표면이 통과하도록, 보간 기준에 의해 표면이 정의된다.
D3DBASIS_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

D3DBASISTYPE 의 멤버는, 테셀레이션의 사이에 행해지는 고차원 패치 표면 프리미티브의 평가에 대해 사용되는 식을 규정하고 있다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DRECTPATCH_INFO ,D3DTRIPATCH_INFO


D3DLIGHTTYPE

라이트의 종류를 정의한다.

typedef enum _D3DLIGHTTYPE {
    D3DLIGHT_POINT          = 1,
    D3DLIGHT_SPOT           = 2,
    D3DLIGHT_DIRECTIONAL    = 3,

    D3DLIGHT_FORCE_DWORD    = 0x7fffffff
} D3DLIGHTTYPE;

정수

D3DLIGHT_POINT
라이트는 포인트 라이트이다. 라이트는 공간내의 점을 가져, 전방향으로 빛을 조사한다.
D3DLIGHT_SPOT
라이트는spotlight이다. 이 라이트는, 조사가 콘내에 제한되는 점을 제외해서는, 포인트 라이트로 유사한다. 이 라이트 타입에는, 방향, 및 콘의 형상을 결정하는 그 외의 파라미터가 몇개인가 있다. 이러한 파라미터에 대해서는, 「D3DLIGHT8 구조체」를 참조할것.
D3DLIGHT_DIRECTIONAL
라이트는디레크쇼날 라이트이다. 이것은 무한대의 거리로 포인트 라이트를 고용하는 것에 동일하다.
D3DLIGHT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

디레크쇼나르라이트는 포인트 라이트보다 처리는 다소 빠르지만, 결과에 대해서는 포인트 라이트가 위이다. spotlight는 재미있는 시각 이펙트를 내지만, 계산상 부하가 높다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DLIGHT8


D3DMATERIALCOLORSOURCE

라이팅 계산을 위해서(때문에) 참조해야 하는 색 또는 색성분의 장소를 정의한다.

typedef enum _D3DMATERIALCOLORSOURCE {
    D3DMCS_MATERIAL         = 0,
    D3DMCS_COLOR1           = 1,
    D3DMCS_COLOR2           = 2,

    D3DMCS_FORCE_DWORD      = 0x7fffffff
} D3DMATERIALCOLORSOURCE;

정수

D3DMCS_MATERIAL
현재의 머트리얼의 색을 사용한다.
D3DMCS_COLOR1
디퓨즈 버텍스색을 사용한다.
D3DMCS_COLOR2
스펙큐러 버텍스색을 사용한다.
D3DMCS_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이러한 플래그는,D3DRENDERSTATETYPE 열거형으로 다음의 렌더링 스테이트의 값을 설정하기 위해서 사용한다.

  • D3DRS_DIFFUSEMATERIALSOURCE
  • D3DRS_SPECULARMATERIALSOURCE
  • D3DRS_AMBIENTMATERIALSOURCE
  • D3DRS_EMISSIVEMATERIALSOURCE

동작환경

헤더 : d3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DMULTISAMPLE_TYPE

디바이스가 대응하는 풀 신 멀티 샘플링의 레벨을 정의한다.

typedef enum _D3DMULTISAMPLE_TYPE {
    D3DMULTISAMPLE_NONE            =  0,
    D3DMULTISAMPLE_2_SAMPLES       =  2,
    D3DMULTISAMPLE_3_SAMPLES       =  3,
    D3DMULTISAMPLE_4_SAMPLES       =  4,
    D3DMULTISAMPLE_5_SAMPLES       =  5,
    D3DMULTISAMPLE_6_SAMPLES       =  6,
    D3DMULTISAMPLE_7_SAMPLES       =  7,
    D3DMULTISAMPLE_8_SAMPLES       =  8,
    D3DMULTISAMPLE_9_SAMPLES       =  9,
    D3DMULTISAMPLE_10_SAMPLES      = 10,
    D3DMULTISAMPLE_11_SAMPLES      = 11,
    D3DMULTISAMPLE_12_SAMPLES      = 12,
    D3DMULTISAMPLE_13_SAMPLES      = 13,
    D3DMULTISAMPLE_14_SAMPLES      = 14,
    D3DMULTISAMPLE_15_SAMPLES      = 15,
    D3DMULTISAMPLE_16_SAMPLES      = 16,

    D3DMULTISAMPLE_FORCE_DWORD     = 0xffffffff
} D3DMULTISAMPLE_TYPE;

정수

D3DMULTISAMPLE_NONE
어느 레벨의 풀 신 멀티 샘플링도 이용할 수 없다.
D3DMULTISAMPLE_2_SAMPLES ~ D3DMULTISAMPLE_16_SAMPLES
그 레벨의 풀 신 멀티 샘플링을 이용할 수 있다.
D3DMULTISAMPLE_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

IDirect3DDevice8::Reset 의 호출시에 풀 신 멀티 샘플링을 유효하게 가능할 뿐만 아니라, 다양한 기능의 온 또는 오프를 치밀한 레벨로 설정하는 렌더링 스테이트가 준비되어 있다.

멀티 샘플링은, D3DSWAPEFFECT_DISCARD 스왑 이펙트로 생성 또는 리셋 하고 있는 스왑 체인에서만 유효하다.

동작환경

헤더 : d3d8types.h 로 선언.

참조

IDirect3D8::CheckDeviceMultiSampleType ,IDirect3DDevice8::CreateDepthStencilSurface ,IDirect3DDevice8::CreateRenderTarget ,D3DPRESENT_PARAMETERS ,D3DSURFACE_DESC


D3DORDERTYPE

고차원 표면의 오더타임을 정의한다.

typedef enum _D3DORDERTYPE {
   D3DORDER_LINEAR      = 1,
   D3DORDER_CUBIC       = 3,
   D3DORDER_QUINTIC     = 5,

   D3DORDER_FORCE_DWORD = 0x7fffffff
} D3DORDERTYPE;

정수

D3DORDER_LINEAR
선형 타입.
D3DORDER_CUBIC
3 차 타입.
D3DORDER_QUINTIC
5 차 타입.
D3DORDER_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DRECTPATCH_INFO ,D3DTRIPATCH_INFO


D3DPATCHEDGESTYLE

현재의 테셀레이션 모드가 개별 또는 연속의 머지않아인지를 정의한다.

typedef enum _D3DPATCHEDGESTYLE {
   D3DPATCHEDGE_DISCRETE    = 0,
   D3DPATCHEDGE_CONTINUOUS  = 1,

   D3DPATCHEDGE_FORCE_DWORD = 0x7fffffff,
} D3DPATCHEDGESTYLE;

정수

D3DPATCHEDGE_DISCRETE
개별 엣지 스타일. 개별 모드에서는, 부동 소수점수(실수)의 테셀레이션을 지정할 수 있지만, 정수에 절약할 수 있다.
D3DPATCHEDGE_CONTINUOUS
연속 엣지 스타일. 연속 모드에서는, 테셀레이션은 부동 소수점수(실수)값으로서 지정되어 매끈매끈하게 변화시켜 부자연스러운 효과 「폽핑」을 감소시킬 수가 있다.
D3DPATCHEDGE_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

연속 테셀레이션에서는, 테셀레이션의 값이 같아도, 개별 테셀레이션과는 완전히 다른 테셀레이션 패턴이 생성되는 것에 주의 해야 한다 (이것은 와이어 프레임 모드로 보다 현저하게 된다). 따라서, 연속 모드의 4.0 은 개별 모드의 4 와 같지 않다.

동작환경

헤더 : D3d8types.h 로 선언.


D3DPOOL

리소스의 버퍼를 보관 유지하는 메모리 클래스를 정의한다.

typedef enum _D3DPOOL {
    D3DPOOL_DEFAULT                 = 0,
    D3DPOOL_MANAGED                 = 1,
    D3DPOOL_SYSTEMMEM               = 2,

    D3DPOOL_FORCE_DWORD             = 0x7fffffff
} D3DPOOL;

정수

D3DPOOL_DEFAULT
리소스는, 리소스에 대해서 요구된 사용 방법으로 가장 적합한 메모리 풀에 놓여진다. 보통, 이것은, 로컬 비디오 메모리와 AGP 메모리의 양쪽 모두를 포함한, 비디오 메모리이다. D3DPOOL_DEFAULT 풀은, D3DPOOL_MANAGED 및 D3DPOOL_SYTEMMEM 로부터 독립하고 있어, 리소스가 디바이스 액세스용의 우선 메모리에 배치되는 것을 지정한다. D3DPOOL_DEFAULT 는, 이 리소스의 메모리 풀 타입으로서 D3DPOOL_MANAGED 또는 D3DPOOL_SYSTEMMEM 의 어느쪽이든을 선택해야 하는 것을 나타내고 있는 것은 아닌 것에 주의 해야 한다. D3DPOOL_DEFAULT 풀에 배치된 텍스쳐는, 잠글 수 없기 때문에, 직접 액세스 할 수 없다. 대신에,IDirect3DDevice8::CopyRects 나 IDirect3DDevice8::UpdateTexture 등의 함수를 사용해야 한다. D3DPOOL_MANAGED 는, 대부분의 어플리케이션으로 D3DPOOL_DEFAULT 보다 적합한 경우가 많다. Direct3D 런타임에서는 미지의, 드라이버 독자적인 픽셀 포맷으로 생성 된 텍스쳐의 일부는 잠글 수 있는 것에 주의 해야 한다. 또, 텍스쳐와는 달라, 스왑 체인 백 버퍼, 렌더링 타겟, 버텍스 버퍼, 및 인덱스 버퍼를 잠글 수 있게도 주의한다.

디바이스가 소실했을 경우는, D3DPOOL_DEFAULT 를 사용해 생성 한 리소스는,IDirect3DDevice8::Reset 를 호출하기 전에 해방해야 한다. 상세한 것에 대하여는, 「소실한 디바이스」를 참조할것.

D3DPOOL_MANAGED
리소스는, 필요에 따라서, 디바이스로부터 액세스 할 수 있는 메모리에 자동적으로 카피된다. 관리 리소스는, 시스템 메모리에 백업 되므로, 디바이스가 소실했을 때에 생성 다시 할 필요가 없다. 상세한 것에 대하여는, 「리소스의 관리」를 참조할것. 관리 리소스는 잠글 수 있다. 시스템 메모리의 카피만이 직접 변경된다. Direct3D 는, 필요에 따라서, 드라이버가 액세스 가능한 메모리로 변경 내용을 카피한다.
D3DPOOL_SYSTEMMEM
보통, 3D 디바이스에 의해 액세스 할 수 없는 메모리. 시스템 RAM 를 사용하지만, 페이징 가능한 RAM 가 줄어들 것은 없다. 이러한 리소스는, 디바이스가 소실해도 생성 다시 할 필요가 없다. 이 풀의 리소스는 잠글 수가 있어 D3DPOOL_DEFAULT 를 사용해 생성 된 메모리 리소스에 대한 IDirect3DDevice8::CopyRects 또는 IDirect3DDevice8::UpdateTexture 처리의 전송원으로서 사용할 수 있다.
D3DPOOL_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

1 개의 리소스 (밉맵의 밉레벨)에 포함되는 다른 오브젝트에 대해서 복수의 풀을 혼재시키지 못하고, 일단 선택한 풀은 변경할 수 없다.

어플리케이션에서는, 대부분의 정적 리소스에 대해서 D3DPOOL_MANAGED 를 사용할 필요가 있다. 이것에 의해, 소실한 디바이스를 처리할 필요가 없어진다. 관리 리소스는 런타임에 의해 복원된다. 이것은, 특히 UMA 시스템으로 유효하다. 또, 다이나믹 텍스쳐 리소스에 대해서도, 그 변경 빈도가 많음에 관계없이, D3DPOOL_MANAGED 를 사용한다. 그 이외의 동적 리소스에 대해서는, D3DPOOL_MANAGED 는 그다지 사용하지 않는다. 실제, D3DPOOL_MANAGED 와 D3DUSAGE_DYNAMIC 를 함께 사용해, 인덱스 버퍼 및 버텍스 버퍼를 생성 할 수 없다.

다이나믹 텍스쳐의 경우, 비디오 메모리와 시스템 메모리의 텍스쳐의 페어를 사용해, D3DPOOL_DEFAULT 를 사용해 비디오 메모리를, D3DPOOL_SYSTEMMEM 를 사용해 시스템 메모리를 할당하는 일이 있다. 락킹 메소드를 사용해, 시스템 메모리 텍스쳐의 비트를 락 및 변경할 수 있다. 그 후,IDirect3DDevice8::UpdateTexture 를 사용해, 비디오 메모리 텍스쳐를 갱신할 수가 있다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateCubeTexture ,IDirect3DDevice8::CreateIndexBuffer ,IDirect3DDevice8::CreateTexture ,IDirect3DDevice8::CreateVolumeTexture ,IDirect3DDevice8::CreateVertexBuffer ,D3DINDEXBUFFER_DESC ,D3DSURFACE_DESC ,D3DVERTEXBUFFER_DESC ,D3DVOLUME_DESC


D3DPRIMITIVETYPE

Microsoft® Direct3D® 가 지원 하는 프리미티브를 정의한다.

typedef enum _D3DPRIMITIVETYPE {
    D3DPT_POINTLIST             = 1,
    D3DPT_LINELIST              = 2,
    D3DPT_LINESTRIP             = 3,
    D3DPT_TRIANGLELIST          = 4,
    D3DPT_TRIANGLESTRIP         = 5,
    D3DPT_TRIANGLEFAN           = 6,

    D3DPT_FORCE_DWORD           = 0x7fffffff
} D3DPRIMITIVETYPE;

정수

D3DPT_POINTLIST
버텍스를 별개의 점의 집합으로서 렌더링 한다.
D3DPT_LINELIST
별개의 선분의 리스트로서 버텍스를 렌더링 한다. 이 프리미티브 타입을 사용하는 호출은, 카운트가 2 보다 작은지, 홀수의 경우는 실패한다.
D3DPT_LINESTRIP
버텍스를 단일의 polyline로서 렌더링 한다. 이 프리미티브 타입을 사용하는 호출은, 카운트가 2 보다 작은 경우는 실패한다.
D3DPT_TRIANGLELIST
별개의 삼각형의 연속으로서 지정의 버텍스를 렌더링 한다. 각 3 버텍스의 그룹은 개별적으로 삼각형을 정의한다.

배면의 카링은, 현재의 카링모드렌다링스테이트의 영향을 받는다.

D3DPT_TRIANGLESTRIP
버텍스를 삼각형의 전개도로서 렌더링 한다. 배면 카링후라그는, 짝수 번호의 삼각형으로 자동적으로 반전한다.
D3DPT_TRIANGLEFAN
버텍스를 삼각형의 선형으로서 렌더링 한다.
D3DPT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

삼각형 스트립 또는삼각형 팬을 사용하면(자) 복제되는 버텍스의 수가 적기 때문에, 효율적인 것이 많다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::DrawIndexedPrimitive ,IDirect3DDevice8::DrawIndexedPrimitiveUP ,IDirect3DDevice8::DrawPrimitive ,IDirect3DDevice8::DrawPrimitiveUP


D3DRENDERSTATETYPE

디바이스의 렌더링 스테이트를 정의한다.

typedef enum _D3DRENDERSTATETYPE {
    D3DRS_ZENABLE                   =   7,
    D3DRS_FILLMODE                  =   8,
    D3DRS_SHADEMODE                 =   9,
    D3DRS_LINEPATTERN               =  10,
    D3DRS_ZWRITEENABLE              =  14,
    D3DRS_ALPHATESTENABLE           =  15,
    D3DRS_LASTPIXEL                 =  16,
    D3DRS_SRCBLEND                  =  19,
    D3DRS_DESTBLEND                 =  20,
    D3DRS_CULLMODE                  =  22,
    D3DRS_ZFUNC                     =  23,
    D3DRS_ALPHAREF                  =  24,
    D3DRS_ALPHAFUNC                 =  25,
    D3DRS_DITHERENABLE              =  26,
    D3DRS_ALPHABLENDENABLE          =  27,
    D3DRS_FOGENABLE                 =  28,
    D3DRS_SPECULARENABLE            =  29,
    D3DRS_ZVISIBLE                  =  30,
    D3DRS_FOGCOLOR                  =  34,
    D3DRS_FOGTABLEMODE              =  35,
    D3DRS_FOGSTART                  =  36,
    D3DRS_FOGEND                    =  37,
    D3DRS_FOGDENSITY                =  38,
    D3DRS_EDGEANTIALIAS             =  40,
    D3DRS_ZBIAS                     =  47,
    D3DRS_RANGEFOGENABLE            =  48,

    D3DRS_STENCILENABLE             =  52,
    D3DRS_STENCILFAIL               =  53,
    D3DRS_STENCILZFAIL              =  54,
    D3DRS_STENCILPASS               =  55,
    D3DRS_STENCILFUNC               =  56,
    D3DRS_STENCILREF                =  57,
    D3DRS_STENCILMASK               =  58,
    D3DRS_STENCILWRITEMASK          =  59,
    D3DRS_TEXTUREFACTOR             =  60,

    D3DRS_WRAP0                     = 128,
    D3DRS_WRAP1                     = 129,
    D3DRS_WRAP2                     = 130,
    D3DRS_WRAP3                     = 131,
    D3DRS_WRAP4                     = 132,
    D3DRS_WRAP5                     = 133,
    D3DRS_WRAP6                     = 134,
    D3DRS_WRAP7                     = 135,
    D3DRS_CLIPPING                  = 136,
    D3DRS_LIGHTING                  = 137,
    D3DRS_AMBIENT                   = 139,
    D3DRS_FOGVERTEXMODE             = 140,
    D3DRS_COLORVERTEX               = 141,
    D3DRS_LOCALVIEWER               = 142,
    D3DRS_NORMALIZENORMALS          = 143,
    D3DRS_DIFFUSEMATERIALSOURCE     = 145,
    D3DRS_SPECULARMATERIALSOURCE    = 146,
    D3DRS_AMBIENTMATERIALSOURCE     = 147,
    D3DRS_EMISSIVEMATERIALSOURCE    = 148,
    D3DRS_VERTEXBLEND               = 151,
    D3DRS_CLIPPLANEENABLE           = 152,

    D3DRS_SOFTWAREVERTEXPROCESSING  = 153,

    D3DRS_POINTSIZE                 = 154,
    D3DRS_POINTSIZE_MIN             = 155,
    D3DRS_POINTSPRITEENABLE         = 156,

    D3DRS_POINTSCALEENABLE          = 157,
    D3DRS_POINTSCALE_A              = 158,
    D3DRS_POINTSCALE_B              = 159,
    D3DRS_POINTSCALE_C              = 160,

    D3DRS_MULTISAMPLEANTIALIAS      = 161,
    D3DRS_MULTISAMPLEMASK           = 162,

    D3DRS_PATCHEDGESTYLE            = 163,
    D3DRS_PATCHSEGMENTS             = 164,

    D3DRS_DEBUGMONITORTOKEN         = 165,
    D3DRS_POINTSIZE_MAX             = 166,
    D3DRS_INDEXEDVERTEXBLENDENABLE  = 167,
    D3DRS_COLORWRITEENABLE          = 168,
    D3DRS_TWEENFACTOR               = 170,
    D3DRS_BLENDOP                   = 171,

    D3DRS_FORCE_DWORD               = 0x7fffffff
} D3DRENDERSTATETYPE;

정수

D3DRS_ZENABLE
D3DZBUFFERTYPE 열거형의 1 개의 멤버로서의 깊이 버퍼 스테이트. Z 버퍼링을 유효하게 하려면 D3DZB_TRUE, w 버퍼링을 유효하게 하려면 D3DZB_USEW, 깊이 버퍼링을 무효로 하려면 D3DZB_FALSE 를, 각각 설정한다.

D3DPRESENT_PARAMETERS 구조체의 EnableAutoDepthStencil 멤버에 TRUE 를 설정해 스텐실이 스왑 체인과 함께 생성 되고 있는 경우, 이 렌더링 스테이트의 디폴트값은 TD3DZB_TRUE, 그렇지 않은 경우는 D3DZB_FALSE 이다.

D3DRS_FILLMODE
D3DFILLMODE 열거형의 멤버의 언젠가 또는 복수. 디폴트값은 D3DFILL_SOLID 이다.
D3DRS_SHADEMODE
D3DSHADEMODE 열거형의 멤버의 언젠가 또는 복수. 디폴트값은 D3DSHADE_GOURAUD 이다.
D3DRS_LINEPATTERN
D3DLINEPATTERN 구조체. 디폴트값은 wRepeatPattern 가 0 으로,wLinePattern 가 0 이다.
D3DRS_ZWRITEENABLE
어플리케이션에 의한 깊이 버퍼에의 기입을 유효하게 하려면 , TRUE 를 설정한다. 디폴트값은 TRUE 이다. 어플리케이션은 이 멤버를 이용하는 것으로써, 시스템이 새로운 깊이값으로 깊이 버퍼를 갱신해 버리는 것을 막을 수가 있다. FALSE 의 경우는, 렌더링 스테이트 D3DRS_ZFUNC (깊이 버퍼링을 하고 있으면(자) 가정)에 따라 깊이 비교가 실행되지만, 깊이값은 버퍼에 기입해지지 않다.
D3DRS_ALPHATESTENABLE
알파 테스트를 가능하게 하려면 , TRUE 를 설정한다. 디폴트값은 FALSE 이다. 이 멤버를 사용 하면, 알파값에 근거해 픽셀을 받는지 거부할까를 판단하는 테스트를 오프로 할 수 있다.

들어 오는 알파값은, D3DRS_ALPHAFUNC 렌더링 스테이트에 의해 제공되는 비교 함수를 이용해 참조 알파값이라고 비교된다. 이 모드가 가능하게 되면(자), 테스트가 성공했을 경우에 한정해, 알파 블렌딩이 일어난다.

D3DRS_LASTPIXEL
직선이나 삼각형의 마지막 픽셀을 드로잉(Drawing) 가능하게 하려면 , FALSE 를 설정한다. 디폴트값은 TRUE 이다.
D3DRS_SRCBLEND
D3DBLEND 열거형의 멤버의 언젠가이다. 디폴트값은 D3DBLEND_ONE 이다.
D3DRS_DESTBLEND
D3DBLEND 열거형의 멤버의 언젠가이다. 디폴트값은 D3DBLEND_ZERO 이다.
D3DRS_CULLMODE
배면의 삼각형을 카링 하는 경우에, 그방법을 지정한다. D3DCULL 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은 D3DCULL_CCW 이다.
D3DRS_ZFUNC
D3DCMPFUNC 열거형의 멤버의 언젠가이다. 디폴트값은 D3DCMP_LESSEQUAL 이다. 이 멤버는, 어플리케이션에카메라로부터의 거리를 기준으로 하는 픽셀의 수취나 받아 거부를 허가한다.

픽셀의 깊이값을 깊이 버퍼의 값과 비교한다. 픽셀의 깊이값이 비교 함수로 허가되었을 경우에 픽셀이 기입해진다.

깊이값이 깊이 버퍼에 기입해지는 것은, 렌더링 스테이트가 TRUE 의 경우 뿐이다.

이 깊이 테스트에 실패한 (분)편이, 소프트웨어에 의한 라스터화나 많은 하드웨어 가속기의 처리는 빨라진다. 이것은, 픽셀의 렌더링 처리를 실시하지 않는 경우에, 텍스쳐를 필터 처리하거나 곱셈하거나 할 필요가 없어지기 때문에 있다.

D3DRS_ALPHAREF
알파 테스트가 유효하게 설정되어 있는 경우에, 픽셀을 테스트하기 위한 기준 알파값을 지정하는 값. 이것은,DWORD 렌더링 스테이트값의 하위 8 비트에 해당하는 8 비트값이다. 값은 0x00000000 에서 0x000000FF 의 범위내이다.
D3DRS_ALPHAFUNC
D3DCMPFUNC 열거형의 멤버의 언젠가이다. 디폴트값은, D3DCMP_ALWAYS 이다. 이 멤버는, 어플리케이션에 알파값을 기준으로 하는 픽셀의 수취나 받아 거부를 허가한다.
D3DRS_DITHERENABLE
디저링을 가능하게 하려면 , TRUE 를 설정한다. 디폴트값은 FALSE 이다.
D3DRS_ALPHABLENDENABLE
알파 브렌드에 의한 투명화를 유효하게 하려면 , TRUE 를 설정한다. 디폴트값은 FALSE 이다.

알파 블렌딩의 타입은, D3DRS_SRCBLEND 와 D3DRS_DESTBLEND 의 렌더링 스테이트에 의해 결정된다.

어플리케이션에서는 D3DCAPS8 구조체의 DevCaps 멤버의 D3DDEVCAPS_DRAWPRIMTLVERTEX 플래그를 조사해, 이 렌더링 스테이트가 지원 되고 있는지 어떤지를 체크한다.

D3DRS_FOGENABLE
fog 블렌딩을 가능하게 하려면 , TRUE 를 설정한다. 디폴트값은 FALSE 이다. fog 블렌딩의 상세한 것에 대하여는, 「fog」를 참조할것.
D3DRS_SPECULARENABLE
스펙큐러 하이라이트를 가능하게 하려면 , TRUE 를 설정한다. 디폴트값은 FALSE 이다.

스펙큐러 하이라이트는, 빛이 맞고 있는 오브젝트의 각 버텍스가 그 오브젝트의 원점에 있는것 같이 산출된다. 이것에 의해, 오브젝트가 원점의 주위로 모델화 되어 광원과 오브젝트간의 거리가 비교적 큰 경우에 한정해, 결과를 예측할 수가 있다. 그 이외의 경우는, 결과는 부정이다.

이 멤버를 TRUE 로 설정 하면, 텍스쳐 cascade 후, 알파 블렌딩전에, 베이스 칼라에 스펙큐러색이 추가된다.

D3DRS_ZVISIBLE
지원 되지 않는다.
D3DRS_FOGCOLOR
D3DCOLOR 형의 값. 디폴트값은 0 이다. fog 칼라의 상세한 것에 대하여는, 「fog 칼라」를 참조할것.
D3DRS_FOGTABLEMODE
픽셀 fog에 사용되는 fog식. D3DFOGMODE 열거형의 멤버의 어느쪽이든을 설정한다. 디폴트값은 D3DFOG_NONE 이다. 픽셀 fog의 상세한 것에 대하여는, 「픽셀 fog」를 참조할것.
D3DRS_FOGSTART
선형 fog 모드에 있어서의, 픽셀 또는 버텍스 fog 이펙트의 시작 깊이. 버텍스 fog의 경우, 깊이는 월드 공간에서 지정된다. 픽셀 fog의 경우는, 디바이스 공간 [0.0, 1.0] 또는 월드 공간의 어느쪽이든으로 지정된다. 픽셀 fog에서는, fog 계산에 Z 가 사용되는 경우, 이러한 값은 디바이스 공간에 있어, 시점과의 상대 fog (W fog)가 사용되는 경우는 월드 공간에 있다. 상세한 것에 대하여는, 「fog 파라미터」 및 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것.

이 렌더링 스테이트의 값은 부동 소수점값이다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.

pd3dDevice8->SetRenderState(D3DRS_TWEENFACTOR, *((DWORD*) &TweenFactor));
D3DRS_FOGEND
선형 fog 모드에 있어서의, 픽셀 또는 버텍스 fog 이펙트의 종료 깊이. 버텍스 fog의 경우, 깊이는 월드 공간에서 지정된다. 픽셀 fog의 경우는, 디바이스 공간 [0.0, 1.0] 또는 월드 공간의 어느쪽이든으로 지정된다. 픽셀 fog에서는, fog 계산에 Z 가 사용되는 경우, 이러한 값은 디바이스 공간에 있어, 시점과의 상대 fog (W fog)가 사용되는 경우는 월드 공간에 있다. 상세한 것에 대하여는, 「fog 파라미터」 및 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것.

이 렌더링 스테이트의 값은 부동 소수점값이다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.

pd3dDevice8->SetRenderState(D3DRS_FOGEND, *((DWORD*) (&fFogEnd)));
D3DRS_FOGDENSITY
지수 fog 모드 (D3DFOG_EXP 및 D3DFOG_EXP2)로 사용하는 픽셀 또는 버텍스 fog의 fog 밀도. 유효한 밀도는 0.0 에서 1.0 의 범위내이다. 디폴트값은 1.0 이다. 상세한 것에 대하여는, 「fog 파라미터」를 참조할것.

이 렌더링 스테이트의 값은 부동 소수점값이다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.

pd3dDevice8->SetRenderState(D3DRS_FOGDENSITY, *((DWORD*) (&fFogDensity)));
D3DRS_EDGEANTIALIAS
오브젝트의 철면의 윤곽을 형성하는 선을 에일리어징 제거 하려면 , TRUE 를 설정한다. 디폴트값은 FALSE 이다. TRUE 의 경우, 렌더링의 대상이 되는 것은 선만으로, 장면내의 다각형의 외측 엣지로 한정된다. 이 렌더링 스테이트가 설정되어 있어, 삼각형 또는 점이 드로잉(Drawing) 되면(자), 그 동작은 부정이다. anti-aliasing는, 인접 픽셀의 값의 평균치를 취하는 것에 의해 실행된다. anti-aliasing를 실시하는 것은 최선의 방식은 아니지만, 효율적이다. 이런 종류의 처리를 지원 하는 하드웨어는 보급하고 있다.

엣지 anti-aliasing은, D3DPRASTERCAPS_ANTIALIASEDGES 능력을 공개하는 디바이스에 한정해, 유효하게 할 수가 있다. 엣지 anti-aliasing의 상세한 것에 대하여는, 「엣지 anti-aliasing」 및 「anti-aliasing 스테이트」를 참조할것.

D3DRS_ZBIAS
물리적으로는 동일 얼굴에 있는 다각형이 따로 따로 존재하도록(듯이) 보이게 하는, 0 에서 16 까지의 범위의 정수값. Z 바이어스값이 높은 다각형은, Z 바이어스값이 낮은 다각형보다 앞에 표시되기 (위해)때문에, 드로잉(Drawing) 순서를 결정하는 소트를 실행할 필요는 없다. 예를 들어, 값 1 을 가지는 다각형은, 값 0 의 다각형보다 앞으로 보인다. 디폴트값은 0 이다. 상세한 것에 대하여는, 「깊이 버퍼의 사용법」을 참조할것.
D3DRS_RANGEFOGENABLE
범위 베이스의 버텍스 fog를 유효하게 하려면 , TRUE 를 설정한다. 디폴트값은 FALSE 이다. 이 경우는 깊이 베이스의 fog가 사용된다. 범위 베이스의 fog에서는, 장면에 있어서의 오브젝트의 깊이 (z 좌표)는 아니고, 뷰아로부터의 오브젝트의 거리로 fog 이펙트를 계산한다. 범위 베이스의 fog에서는, 보통의 모든 fog 메소드가 기능하지만, 깊이는 아니고 범위를 사용해 계산을 실시하는 점만이 다르다.

범위는 fog 계산에 사용하는 적절한 요소이지만, 범위는 계산의 점으로써 부하가 높고, 깊이는 보통 계산이 끝난 상태이므로, 대신에 깊이가 넓게 사용된다. 깊이를 사용해 fog를 계산 하면, 주변 오브젝트의 fog 이펙트가 시점의 이동과 함께 변화 하면 말하는 바람직하지 않은 영향이 나온다. 이 경우, 깊이는 변화하지만 범위는 일정한 까지 있다.

현재로서는, 픽셀 단위의 범위 베이스의 fog를 지원 하는 하드웨어는 존재하지 않기 때문에, 범위 보정은 버텍스 fog에서만 행해진다.

상세한 것에 대하여는, 「범위 베이스의 fog」 및 「버텍스 fog」를 참조할것.

D3DRS_STENCILENABLE
스텐실 처리를 가능하게 하려면 TRUE, 무효로 하려면 FALSE 를 설정한다. 디폴트값은 FALSE 이다.

상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.

D3DRS_STENCILFAIL
스텐실 테스트에 실패했을 때에 실행하는 스텐실 처리. 이것에는 D3DSTENCILOP 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은 D3DSTENCILOP_KEEP 이다.

상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.

D3DRS_STENCILZFAIL
스텐실 테스트에 패스해, 깊이 테스트 (Z 테스트)에 실패했을 경우에 실행하는 스텐실 처리. 이것에는 D3DSTENCILOP 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은 D3DSTENCILOP_KEEP 이다.
D3DRS_STENCILPASS
스텐실 테스트 및 깊이 (Z) 테스트의 양쪽 모두에 패스했을 경우에 실행하는 스텐실 처리. 이것에는 D3DSTENCILOP 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은 D3DSTENCILOP_KEEP 이다.
D3DRS_STENCILFUNC
스텐실 테스트를 위한 비교 함수. 이것에는 D3DCMPFUNC 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은, D3DCMP_ALWAYS 이다.

비교 함수는, 스텐실 버퍼의 요소를 기준치와 비교하기 위해서(때문에) 사용된다. 이 비교는, 기준치의 비트와 스텐실 마스크 (D3DRS_STENCILMASK 렌더링 스테이트에 의해 설정)로 설정된 스텐실 버퍼 요소에게만 적용된다. TRUE 의 경우는, 스텐실 테스트에 패스한다.

D3DRS_STENCILREF
스텐실 테스트를 위한 정수 기준치. 디폴트값은 0 이다.
D3DRS_STENCILMASK
기준치와 각각의 스텐실 버퍼 요소에 적용해, 스텐실 테스트를 위한 유효 비트를 결정하는 마스크. 디폴트 마스크는 0xFFFFFFFF 이다.
D3DRS_STENCILWRITEMASK
스텐실 버퍼에 기입하는 값에 적용하는 기입 마스크. 디폴트 마스크는 0xFFFFFFFF 이다.
D3DRS_TEXTUREFACTOR
D3DTA_TFACTOR 텍스쳐 블렌딩 인수, 또는 D3DTOP_BLENDFACTORALPHA 텍스쳐 블렌딩 처리를 이용한 멀티 텍스쳐 블렌딩으로 사용되는 색. 관련하는 값은 D3DCOLOR 변수이다.
D3DRS_WRAP0 ~ D3DRS_WRAP7
복수의 텍스쳐 좌표 세트에 대한 텍스쳐 랩핑 동작. 이러한 렌더링 스테이트의 유효값으로서 D3DWRAPCOORD_0 (또는 D3DWRAP_U), D3DWRAPCOORD_1 (또는 D3DWRAP_V), D3DWRAPCOORD_2 (또는 D3DWRAP_W), 및 D3DWRAPCOORD_3 의 각 플래그를 조합할 수가 있다. 이러한 값을 설정 하면, 지정된 텍스쳐에 대해서 1, 2, 3, 및 4 차원 방향 (s, t, r, 및 q 방향으로 불리는 경우도 있다)의 랩핑이 실행된다. 이러한 렌더링 스테이트의 디폴트값은 0 이다 (전방향의 랩핑이 무효).
D3DRS_CLIPPING
Microsoft® Direct3D® 에 의한 프리미티브의 클리핑을 유효하게 하려면 TRUE, 무효로 하려면 FALSE 를 설정한다. 디폴트값은 TRUE 이다.
D3DRS_LIGHTING
Direct3D 의 라이팅을 유효하게 하려면 TRUE, 무효로 하려면 FALSE 를 설정한다. 디폴트값은 TRUE 이다. 버텍스 법선을 포함한 버텍스만 올바르게 라이트가 댈 수 있어 법선을 포함하지 않는 버텍스에서는 모든 라이팅 계산으로 0 의 내적이 사용된다.
D3DRS_AMBIENT
앰비언트 라이트의 색. 이 값은 D3DCOLOR 형이다. 디폴트값은 0 이다.
D3DRS_FOGVERTEXMODE
버텍스 fog용의 fog식. D3DFOGMODE 열거형의 멤버의 어느쪽이든을 설정한다. 디폴트값은 D3DFOG_NONE 이다.
D3DRS_COLORVERTEX
버텍스 단위의 칼라를 유효하게 하려면 TRUE, 무효로 하려면 FALSE 를 설정한다. 디폴트값은 TRUE 이다. 버텍스 단위의 칼라를 유효하게 하면, 개개의 버텍스에 정의된 색이 라이팅 계산에 포함되게 된다.

상세한 것에 대하여는, 이하의 렌더링 스테이트를 참조할것.

  • D3DRS_DIFFUSEMATERIALSOURCE
  • D3DRS_SPECULARMATERIALSOURCE
  • D3DRS_AMBIENTMATERIALSOURCE
  • D3DRS_EMISSIVEMATERIALSOURCE
D3DRS_LOCALVIEWER
카메라와의 상대 각도에 의존한 스펙큐러 하이라이트를 유효하게 하려면 , TRUE 를 설정한다. 직행 스펙큐러 하이라이트를 사용하려면 , FALSE 를 설정한다. 디폴트값은 TRUE 이다. 정사영을 사용하는 어플리케이션에서는 FALSE 를 설정하는 것.
D3DRS_NORMALIZENORMALS
버텍스 법선의 자동 정규화를 유효하게 하려면 TRUE, 무효로 하려면 FALSE 를 설정한다. 디폴트값은 FALSE 이다. 이 기능을 유효하게 하면, 버텍스가 카메라 공간에 트랜스 폼 된 다음에 버텍스 법선이 정규화되지만, 계산 부하가 크다.
D3DRS_DIFFUSEMATERIALSOURCE
라이팅 계산에 사용되는 디퓨즈색의 소스. 유효값은,D3DMATERIALCOLORSOURCE 열거형의 멤버이다. 디폴트값은 D3DMCS_COLOR1 이다. 이 렌더링 스테이트의 값이 사용되는 것은, D3DRS_COLORVERTEX 렌더링 스테이트가 TRUE 로 설정되어 있는 경우 뿐이다.
D3DRS_SPECULARMATERIALSOURCE
라이팅 계산에 사용되는 스펙큐러색의 소스. 유효값은,D3DMATERIALCOLORSOURCE 열거형의 멤버이다. 디폴트값은 D3DMCS_COLOR2 이다.
D3DRS_AMBIENTMATERIALSOURCE
라이팅 계산에 사용되는 앰비언트색의 소스. 유효값은,D3DMATERIALCOLORSOURCE 열거형의 멤버이다. 디폴트값은 D3DMCS_COLOR2 이다.
D3DRS_EMISSIVEMATERIALSOURCE
라이팅 계산에 사용되는 에미션(emission)색의 소스. 유효값은,D3DMATERIALCOLORSOURCE 열거형의 멤버이다. 디폴트값은 D3DMCS_MATERIAL 이다.
D3DRS_VERTEXBLEND
지오메트리가 있는 경우, 지오메트리 블렌딩을 실행하기 위해서 사용하는 행렬의 개수. 유효값은 D3DVERTEXBLENDFLAGS 열거형의 멤버이다. 디폴트값은 D3DVBF_DISABLE 이다.
D3DRS_CLIPPLANEENABLE
유저 정의 클립면을 유효 또는 무효로 한다. 유효값은, 각 비트의 스테이터스 (설정의 유무)에 의해 대응하는 유저 정의 클립면을 액티브하게 하는 스테이트를 바꾸는, 임의의 DWORD 이다. 최하정도 비트 (비트 0)는 인덱스 0 의 최초의 클립면을 제어해, 후속 비트는 그것보다 상위의 인덱스의 클립면을 액티브하게 하는 것을 제어한다. 비트가 설정되어 있는 경우, 장면의 렌더링중에 적절한 클립면이 적용된다. 디폴트값은 0 이다.

클립면을 간단하게 유효하게 할 수 있도록,D3DCLIPPLANEn 매크로가 정의되고 있다.

D3DRS_SOFTWAREVERTEXPROCESSING
하드웨어 버텍스 처리 또는 소프트웨어 버텍스 처리의 설정을 어플리케이션으로부터 조회 및 선택할 수 있도록(듯이) 하는 BOOL 값. 디바이스의 종류가 D3DDEVTYPE_SW 의 경우, 이 값은 TRUE 의 고정이다. 디바이스의 종류가 D3DDEVTYPE_REF 의 경우는, 어플리케이션으로 이 값을 설정할 수 있다. 디바이스의 종류가 D3DDEVTYPE_HAL 의 경우는, D3DDEVCAPS_HWTRANSFORMANDLIGHT 가 설정되어 있을 때 한정해, 어플리케이션으로 이 값을 설정할 수 있다. 그 이외의 경우, 이 플래그는 TRUE 에 고정된다. 어플리케이션에서의 설정이 가능한 경우, 디폴트값은 FALSE 이다.

양쪽 모두의 버텍스 처리가 가능한 모드에 대해, 버텍스 처리의 렌더링 스테이트를 변경 하면, 경향 스트림, 인덱스, 및 버텍스 쉐이더는, 디폴트값의 NULL 또는 0 에 리셋 된다.

D3DRS_POINTSIZE
각 버텍스에 대해서 포인트 사이즈가 지정되어 있지 않은 경우에, 포인트 사이즈 계산으로 사용하는 사이즈를 지정하는 부동 소수점값. 버텍스가 포인트 사이즈를 포함하고 있는 경우, 이 값은 사용되지 않는다. 이 값은, D3DRS_POINTSCALEENABLE 가 FALSE 의 경우는 스크린 공간 단위로 지정한다. 그 이외의 경우는, 월드 공간 단위로 지정한다. 디폴트값은 1.0f 이다. 이 값의 범위는, 0.0f 이상이다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*) &PointSize));
D3DRS_POINTSIZE_MIN
포인트 프리미티브의 최소 사이즈를 지정하는 부동 소수점값. 렌더링의 사이, 포인트 프리미티브는 이 사이즈에 고정된다. 1.0 보다 작은 값을 설정 하면, 포인트에 픽셀의 중심이 포함되지 않고 anti-aliasing가 무효가 되어 있는 경우는 포인트가 표시되지 않게 되어, anti-aliasing가 유효하게 되어 있는 경우는 낮은 휘도로 렌더링 된다. 디폴트값은 1.0f 이다. 이 값의 범위는, 0.0f 이상이다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*) &PointSizeMin));
D3DRS_POINTSPRITEENABLE
BOOL 값. TRUE 를 설정 하면, 텍스쳐 전체가 각 포인트에 매핑 되도록(듯이), 포인트 프리미티브의 텍스쳐 좌표가 설정된다. FALSE 를 설정 하면, 버텍스의 텍스쳐 좌표가 포인트 전체에 대해서 사용된다. 디폴트값은 FALSE 이다. D3DRS_POINTSCALEENABLE 에 FALSE (디폴트값)를 설정해, D3DRS_POINTSIZE 에 1.0 (디폴트값)을 설정하는 것으로, DirectX 7 스타일의 싱글 픽셀 포인트를 실현할 수 있다.
D3DRS_POINTSCALEENABLE
포인트 프리미티브에 대한 사이즈의 계산을 제어하는 BOOL 값. TRUE 를 설정 하면, 포인트 사이즈는, 카메라 공간의 값으로서 해석되어 거리 함수 및 시추대에 의해 뷰 포토의 Y 축의 스케일링이 되도록(듯이) 조정되어, 최종적인 스크린 공간의 포인트 사이즈가 계산된다. FALSE 를 설정 하면, 포인트 사이즈는 스크린 공간의 값이라고 해석되어, 그대로 사용된다. 디폴트값은 FALSE 이다.
D3DRS_POINTSCALE_A
포인트 프리미티브에 대한 거리 베이스의 사이즈의 감쇠를 제어하는 부동 소수점값. D3DRS_POINTSCALEENABLE 가 TRUE 의 경우에게만 유효하다. 디폴트값은 1.0f 이다. 이 값의 범위는, 0.0f 이상이다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*) &PointScaleA));
D3DRS_POINTSCALE_B
포인트 프리미티브에 대한 거리 베이스의 사이즈의 감쇠를 제어하는 부동 소수점값. D3DRS_POINTSCALEENABLE 가 TRUE 의 경우만 유효하다. 디폴트값은 0.0f 이다. 이 값의 범위는, 0.0f 이상이다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*) &PointScaleB));
D3DRS_POINTSCALE_C
포인트 프리미티브에 대한 거리 베이스의 사이즈의 감쇠를 제어하는 부동 소수점값. D3DRS_POINTSCALEENABLE 가 TRUE 의 경우만 유효하다. 디폴트값은 0.0f 이다. 이 값의 범위는, 0.0f 이상이다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*) &PointScaleC));
D3DRS_MULTISAMPLEANTIALIAS
멀티 샘플 렌더링의 타겟 버퍼를 사용할 때의, 개개의 샘플의 계산방법을 결정하는 BOOL 값. TRUE 를 설정 하면, 복수 샘플의 각각 붙어 다른 샘플링 위치에서 샘플링 하는 것으로 풀 신 anti-aliasing를 실행하도록(듯이), 복수의 샘플이 계산된다. FALSE 를 설정 하면, 복수의 샘플은 모두 같은 샘플링값 (픽셀의 중심으로 샘플링 된 값)으로 기술된다. 이것에 의해, 멀티 샘플 버퍼에 대한 비anti-aliasing 렌더링이 가능하게 된다. 싱글 샘플 버퍼에의 렌더링시, 이 렌더링 스테이트는 이펙트를 가지지 않는다. 디폴트값은 TRUE 이다.
D3DRS_MULTISAMPLEMASK
LSB 를 선두로 하는 이 마스크의 각 비트는, 멀티 샘플 렌더링 타겟의 샘플의 1 개에 대한 변경을 제어한다. 따라서, 8 샘플의 렌더링 타겟의 경우는, 8 개의 샘플의 각각 대하는 8 개의 기입 허가 정보가, 하위 바이트에 저장 되고 있다. 싱글 샘플 버퍼에의 렌더링시, 이 렌더링 스테이트는 이펙트를 가지지 않는다. 디폴트값은 0xFFFFFFFF 이다.

이 렌더링 스테이트를 사용하면(자), 멀티 샘플 버퍼를 축적 버퍼로서 사용해, 각 패스가 샘플의 서브 세트를 갱신하는 지오메트리의 멀티 패스 렌더링을 실시할 수가 있다.

D3DRS_PATCHEDGESTYLE
패치 엣지가 부동 소수점수(실수) 스타일의 테셀레이션을 사용할지 어떨지를 설정한다. 설정 가능한 값은,D3DPATCHEDGESTYLE 열거형으로 정의된다.
D3DRS_PATCHSEGMENTS
패치를 드로잉(Drawing) 할 경우에, 세그먼트(segment)수를 각 엣지의 부동 소수점수(실수)값으로서 설정한다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*) &NumSegments));
D3DRS_DEBUGMONITORTOKEN
모니터를 디버그 하는 경우에게만 설정한다. 설정 가능한 값은,D3DDEBUGMONITORTOKENS 열거형으로 정의된다. D3DRS_DEBUGMONITORTOKEN 가 설정되어 있는 경우, 이 호출은 디버그 모니터에의 토큰의 수수로서 처리되는 것에 주의 해야 한다. 예를 들어, D3DDMT_ENABLE 또는 D3DDMT_DISABLE 을 D3DRS_DEBUGMONITORTOKEN 에 건네준 후, 다른 토큰의 값이 건네받았을 경우, 디버그 모니터의 스테이트 (유효 또는 무효)는 변화하지 않는다.

이 스테이트는, 디버그 빌드에서만 유용하다. 디버그 모니터의 디폴트는 D3DDMT_ENABLE 이다.

D3DRS_POINTSIZE_MAX
포인트 스프라이트가 제한되는 최대 사이즈를 지정하는 부동 소수점수(실수)값. 값은,D3DCAPS8 의 MaxPointSize 멤버 이하로,D3DRS_POINTSIZE_MIN 이상이 아니면 안된다. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.
pd3dDevice8->SetRenderState(D3DRS_PONTSIZE_MAX, *((DWORD*) &PointSizeMax));
D3DRS_INDEXEDVERTEXBLENDENABLE
인덱스 첨부의 버텍스 블렌딩을 유효 또는 무효로 하는 BOOL 값. TRUE 를 설정 하면, 인덱스 첨부 버텍스 블렌딩이 유효하게 된다. FALSE 를 설정 하면, 인덱스 첨부 버텍스 블렌딩은 무효가 된다. 이 렌더링 스테이트를 유효하게 하는 경우는, 버텍스 마다 팩 DWORD 로 행렬 인덱스를 건네주지 않으면 안 된다. 이 렌더링 스테이트를 무효로 해, D3DRS_VERTEXBLEND 스테이트를 사용해 버텍스 블렌딩을 유효하게 하는 것은, 모든 버텍스에 대해 행렬 인덱스 0, 1, 2, 3 을 지정하는 것으로 동일하다.
D3DRS_COLORWRITEENABLE
렌더링 타겟의 칼라 버퍼에 대한 채널마다의 기입을 유효하게 하는 UINT 값. 비트를 설정 하면, 3D 렌더링의 사이에 칼라 채널이 갱신된다. 비트를 클리어 하면, 칼라 채널은 갱신되지 않는다. 디바이스에 대한 D3DCAPS8 구조체의 PrimitiveMiscCaps 멤버로 D3DPMISCCAPS_COLORWRITEENABLE 능력 비트를 설정 하면, 이 기능을 이용할 수 있게 된다. 이 렌더링 스테이트는, 클리어 처리에는 영향을 주지 않는다. 디폴트값은 0x0000000F 이다.

이 렌더링 스테이트에 대한 유효한 값은, D3DCOLORWRITEENABLE_ALPHA, D3DCOLORWRITEENABLE_BLUE, D3DCOLORWRITEENABLE_GREEN, 및 D3DCOLORWRITEENABLE_RED 의 각 플래그의 임의의 편성이다.

D3DRS_TWEENFACTOR
트인 계수를 제어하는 부동 소수점수(실수)값. IDirect3DDevice8::SetRenderState 메소드는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*) &TweenFactor));
D3DRS_BLENDOP
알파 블렌딩 렌더링 스테이트 D3DRS_ALPHABLENDENABLE 가 TRUE 로 설정되어 있을 때 적용되는 산술 연산을 선택하기 위해서 사용하는 값. 유효값은,D3DBLENDOP 열거형으로 정의된다. 디폴트값은 D3DBLENDOP_ADD 이다.

D3DPMISCCAPS_BLENDOP 디바이스 능력이 지원되어 있지 않은 경우는, D3DBLENDOP_ADD 가 실행된다.

D3DRS_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

Direct3D 는, 어플리케이션에서의 편의를 고려해, (D3DRS_WRAPn 스테이트값의 1 개를 명시적으로 사용하는 대신에) 정수 D3DRENDERSTATE_WRAPBIAS 를 정의해, 텍스쳐 좌표 세트의 제로로부터 시작되는 정수값에 근거해, 텍스쳐 랩핑을 유효하게 하거나 무효로 하거나 한다. 다음의 예의 같게, D3DRENDERSTATE_WRAPBIAS 값을 텍스쳐 좌표 세트의 제로 시점 인덱스에 가산해, 그 인덱스에 대응하는 D3DRS_WRAPn 값을 계산한다.

// 변수 dwIndex 의 인덱스에 대응하는 텍스쳐 좌표 세트를
// 사용하는 텍스쳐에 대해서, U/V 랩핑을 유효하게 한다.
HRESULT hr = pd3dDevice->SetRenderState(
    dwIndex + D3DRENDERSTATE_WRAPBIAS,
    D3DWRAPCOORD_0 | D3DWRAPCOORD_1);

// dwIndex가 3 의 경우, 가산의 결과의 값은,
// D3DRS_WRAP3 (131)에 동일해진다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetRenderState ,IDirect3DDevice8::SetRenderState


D3DRESOURCETYPE

리소스의 종류를 정의한다.

typedef enum _D3DRESOURCETYPE {
    D3DRTYPE_SURFACE                =  1,
    D3DRTYPE_VOLUME                 =  2,
    D3DRTYPE_TEXTURE                =  3,
    D3DRTYPE_VOLUMETEXTURE          =  4,
    D3DRTYPE_CUBETEXTURE            =  5,
    D3DRTYPE_VERTEXBUFFER           =  6,
    D3DRTYPE_INDEXBUFFER            =  7,

    D3DRTYPE_FORCE_DWORD            = 0x7fffffff
} D3DRESOURCETYPE;

정수

D3DRTYPE_SURFACE
표면 리소스.
D3DRTYPE_VOLUME
볼륨 리소스.
D3DRTYPE_TEXTURE
텍스쳐 리소스.
D3DRTYPE_VOLUMETEXTURE
볼륨 텍스쳐 리소스.
D3DRTYPE_CUBETEXTURE
큐브 텍스쳐 리소스.
D3DRTYPE_VERTEXBUFFER
버텍스 버퍼 리소스.
D3DRTYPE_INDEXBUFFER
인덱스 버퍼 리소스.
D3DRTYPE_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DResource8::GetType


D3DSHADEMODE

지원 되고 있는 쉐이딩 모드를 기술하는 정수를 정의한다.

typedef enum _D3DSHADEMODE {
    D3DSHADE_FLAT               = 1,
    D3DSHADE_GOURAUD            = 2,
    D3DSHADE_PHONG              = 3,

    D3DSHADE_FORCE_DWORD        = 0x7fffffff
} D3DSHADEMODE;

정수

D3DSHADE_FLAT
flat shading 모드. 삼각형의 최초의 버텍스의 색이, 표면의 색을 결정하기 위해서(때문에) 사용된다. 이 색은 삼각형 전체에 걸쳐서 마을 없게 적용된다. 즉, 보간 되지 않는다. 스펙큐러 알파는 보간 된다. 「주의」를 참조할것.
D3DSHADE_GOURAUD
gouraud shading 모드. 표면의 색은, 삼각형의 3 개의 버텍스간으로, 선형 보간에 의해 결정된다.
D3DSHADE_PHONG
지원 되지 않는다.
D3DSHADE_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

flat shading 모드의 삼각형의 최초의 버텍스는, 다음과 같이 정의된다.

  • 삼각형 리스트의 경우, 삼각형 i 의 최초의 버텍스는 i * 3 이다.
  • 삼각형 스트립의 경우, 삼각형 i 의 최초의 버텍스는 버텍스 i 이다.
  • 삼각형 팬의 경우, 삼각형 i 의 최초의 버텍스는 버텍스 i + 1 이다.

이 열거형의 멤버는,D3DRS_SHADEMODE 렌더링 스테이트의 값을 정의한다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DSTATEBLOCKTYPE

디바이스 스테이트의 논리 그룹을 정의한다.

typedef enum _D3DSTATEBLOCKTYPE {
    D3DSBT_ALL           = 1,
    D3DSBT_PIXELSTATE    = 2,
    D3DSBT_VERTEXSTATE   = 3,

    D3DSBT_FORCE_DWORD   = 0xffffffff
} D3DSTATEBLOCKTYPE;

정수

D3DSBT_ALL
다음의 모든 디바이스 스테이트를 수중에 넣는다.
현재의 모든 렌더링 스테이트 | 현재의 모든 클립면
현재의 모든 텍스쳐 스테이지 스테이트 | 현재의 머트리얼
현재의 모든 텍스쳐 | 현재의 모든 라이트 및 유효한 라이트 파라미터
현재의 팔레트 | 현재의 픽셀 쉐이더
현재의 모든 스트림 | 현재의 픽셀 쉐이더 정수
현재의 뷰 포토 | 현재의 버텍스 쉐이더
현재의 모든 트랜스 폼 | 현재의 버텍스 쉐이더 정수

D3DSBT_PIXELSTATE
현재의 픽셀 쉐이더, 픽셀 쉐이더 정수, 및 다음의 픽셀 관련 디바이스 스테이트를 모두 수중에 넣는다.

렌더링 스테이트
D3DRS_ALPHABLENDENABLE D3DRS_ALPHAFUNC
D3DRS_ALPHAREF D3DRS_ALPHATESTENABLE
D3DRS_BLENDOP D3DRS_COLORWRITEENABLE
D3DRS_DESTBLEND D3DRS_DITHERENABLE
D3DRS_EDGEANTIALIAS D3DRS_FILLMODE
D3DRS_FOGDENSITY D3DRS_FOGEND
D3DRS_FOGSTART D3DRS_LASTPIXEL
D3DRS_LINEPATTERN D3DRS_SHADEMODE
D3DRS_SRCBLEND D3DRS_STENCILENABLE
D3DRS_STENCILFAIL D3DRS_STENCILFUNC
D3DRS_STENCILMASK D3DRS_STENCILPASS
D3DRS_STENCILREF D3DRS_STENCILWRITEMASK
D3DRS_STENCILZFAIL D3DRS_TEXTUREFACTOR
D3DRS_WRAP0 ~ D3DRS_WRAP7 D3DRS_ZBIAS
D3DRS_ZENABLE D3DRS_ZFUNC
D3DRS_ZWRITEENABLE

텍스쳐 스테이지 스테이트
D3DTSS_ADDRESSU D3DTSS_ADDRESSV
D3DTSS_ADDRESSW D3DTSS_ALPHAARG0
D3DTSS_ALPHAARG1 D3DTSS_ALPHAARG2
D3DTSS_ALPHAOP D3DTSS_BORDERCOLOR
D3DTSS_BUMPENVLOFFSET D3DTSS_BUMPENVLSCALE
D3DTSS_BUMPENVMAT00 D3DTSS_BUMPENVMAT01
D3DTSS_BUMPENVMAT10 D3DTSS_BUMPENVMAT11
D3DTSS_COLORARG0 D3DTSS_COLORARG1
D3DTSS_COLORARG2 D3DTSS_COLOROP
D3DTSS_MAGFILTER D3DTSS_MAXANISOTROPY
D3DTSS_MAXMIPLEVEL D3DTSS_MINFILTER
D3DTSS_MIPFILTER D3DTSS_MIPMAPLODBIAS
D3DTSS_RESULTARG D3DTSS_TEXCOORDINDEX
D3DTSS_TEXTURETRANSFORMFLAGS

D3DSBT_VERTEXSTATE
현재의 모든 라이트, 현재의 버텍스 쉐이더와 버텍스 쉐이더 정수, 및 D3DTSS_TEXCOORDINDEX 와 D3DTSS_TEXTURETRANSFORMFLAG 로 지정되는 텍스쳐 스테이지 스테이트를 수중에 넣는다. 또, 이 플래그는, 다음의 버텍스 관련 디바이스 스테이트를 모두 수중에 넣는다.

렌더링 스테이트
D3DRS_AMBIENT D3DRS_AMBIENTMATERIALSOURCE
D3DRS_CLIPPING D3DRS_CLIPPLANEENABLE
D3DRS_COLORVERTEX D3DRS_DIFFUSEMATERIALSOURCE
D3DRS_EMISSIVEMATERIALSOURCE D3DRS_FOGDENSITY
D3DRS_FOGEND D3DRS_FOGSTART
D3DRS_FOGTABLEMODE D3DRS_FOGVERTEXMODE
D3DRS_INDEXEDVERTEXBLENDENABLE D3DRS_LIGHTING
D3DRS_LOCALVIEWER D3DRS_MULTISAMPLEANTIALIAS
D3DRS_MULTISAMPLEMASK D3DRS_NORMALIZENORMALS
D3DRS_PATCHEDGESTYLE D3DRS_PATCHSEGMENTS
D3DRS_POINTSCALE_A D3DRS_POINTSCALE_B
D3DRS_POINTSCALE_C D3DRS_POINTSCALEENABLE
D3DRS_POINTSIZE D3DRS_POINTSIZE_MAX
D3DRS_POINTSIZE_MIN D3DRS_POINTSPRITEENABLE
D3DRS_RANGEFOGENABLE D3DRS_SOFTWAREVERTEXPROCESSING
D3DRS_SPECULARMATERIALSOURCE D3DRS_TWEENFACTOR
D3DRS_VERTEXBLEND

D3DSBT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

D3DSBT_PIXELSTATE 및 D3DSBT_VERTEXSTATE 값은, 다른 논리 그룹의 디바이스 스테이트를 각각 식별하지만, 스테이트에 따라서는 양쪽 모두의 그룹에 공통되는 것도 있다. D3DSBT_PIXELSTATE 및 D3DSBT_VERTEXSTATE 의 편성은 D3DSBT_ALL 와 동등하지 않다. D3DSBT_PIXELSTATE 및 D3DSBT_VERTEXSTATE 값을 사용하는 것으로,IDirect3DDevice8::DrawPrimitive 의 호출동안에 빈번하게 변경되는 스테이트를 수중에 넣을 수가 있어 스테이트 전체를 수중에 넣는 것에 의한 퍼포먼스에의 악영향은 없다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::CreateStateBlock


D3DSTENCILOP

스텐실 처리를 정의한다.

typedef enum _D3DSTENCILOP {
    D3DSTENCILOP_KEEP           = 1,
    D3DSTENCILOP_ZERO           = 2,
    D3DSTENCILOP_REPLACE        = 3,
    D3DSTENCILOP_INCRSAT        = 4,
    D3DSTENCILOP_DECRSAT        = 5,
    D3DSTENCILOP_INVERT         = 6,
    D3DSTENCILOP_INCR           = 7,
    D3DSTENCILOP_DECR           = 8,

    D3DSTENCILOP_FORCE_DWORD    = 0x7fffffff
} D3DSTENCILOP;

정수

D3DSTENCILOP_KEEP
스텐실 버퍼내의 항목을 갱신하지 않는다. 이것이 디폴트값이다.
D3DSTENCILOP_ZERO
스텐실 버퍼내의 항목을 0 으로 설정한다.
D3DSTENCILOP_REPLACE
스텐실 버퍼내의 항목을 기준치로 옮겨놓는다.
D3DSTENCILOP_INCRSAT
스텐실 버퍼내의 항목의 값을, 최대치에 이를 때까지 증가시킨다. 스텐실 버퍼의 최대치에 대해서는, 「주의」를 참조할것.
D3DSTENCILOP_DECRSAT
스텐실 버퍼내의 항목의 값을 0 이 될 때까지 감소시킨다.
D3DSTENCILOP_INVERT
스텐실 버퍼내의 항목의 비트를 반전한다.
D3DSTENCILOP_INCR
스텐실 버퍼내의 항목의 값을 증가시켜, 그 값이 최대치를 넘으면(자) 0 에 되돌린다. 스텐실 버퍼의 최대치에 대해서는, 「주의」를 참조할것.
D3DSTENCILOP_DECR
스텐실 버퍼내의 항목의 값을 감소시켜, 그 값이 0 보다 작아지면(자) 최대치에 되돌린다.
D3DSTENCILOP_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

스텐실 버퍼의 항목은 0 에서 2n -1 까지의 범위의 정수값이다. n 는 스텐실 버퍼의 비트 깊이이다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DSWAPEFFECT

스왑 이펙트를 정의한다.

typedef enum _D3DSWAPEFFECT {
    D3DSWAPEFFECT_DISCARD         = 1,
    D3DSWAPEFFECT_FLIP            = 2,
    D3DSWAPEFFECT_COPY            = 3,
    D3DSWAPEFFECT_COPY_VSYNC      = 4,

    D3DSWAPEFFECT_FORCE_DWORD     = 0xFFFFFFFF
} D3DSWAPEFFECT;

정수

D3DSWAPEFFECT_DISCARD
스왑 이펙트의 D3DSWAPEFFECT_FLIP, D3DSWAPEFFECT_COPY, 또는 D3DSWAPEFFECT_COPY_VSYNC 를 사용해 스왑 체인을 생성 했을 경우, 런타임은 IDirect3DDevice8::Present 처리가 백 버퍼의 내용에 일절 영향을 주지 않는 것을 보증한다. 다만, 윈도우 스왑 체인의 플립 시멘틱스나, 풀 스크린 스왑 체인의 카피 시멘틱스를 이행 할 때등에는, 이 보증을 채우기 위해서(때문에) 상당한 비디오 메모리의 오버헤드나 처리의 오버헤드가 수반하는 일이 있다. 어플리케이션에서는 D3DSWAPEFFECT_DISCARD 스왑 이펙트를 사용하는 것으로, 이러한 오버헤드를 회피할 수가 있어 가장 효율적인 스왑 체인의 표현 방법을 디스플레이 드라이버측에서 선택할 수 있다. 또, 이것은,D3DPRESENT_PARAMETERS 의 MultiSampleType 멤버에 D3DMULTISAMPLE_NONE 이외의 값을 지정했을 때에 사용할 수 있는 유일한 스왑 이펙트이다.

D3DSWAPEFFECT_FLIP 를 사용하는 스왑 체인과 같이, D3DSWAPEFFECT_DISCARD 를 사용하는 스왑 체인은 복수의 백 버퍼를 포함하고 있는 일이 있어, 이러한 버퍼에는 IDirect3DDevice8::GetBackBuffer 또는 IDirect3DSwapChain8::GetBackBuffer 를 사용해 액세스 할 수 있다. 스왑 체인은 기다리는 행렬로서 볼 수가 있어 이 기다리는 행렬 중(안)에서는, 다음의 Present 처리로 표시되는 백 버퍼에 항상 인덱스 0 이 붙어, 일단 표시된 버퍼는 기다리는 행렬로부터 파기된다.

이 스왑 이펙트를 사용하는 어플리케이션에서는, 파기되는 백 버퍼의 내용을 추측할 수 없기 때문에, 백 버퍼 전체를 갱신한 다음에 Present 처리를 호출할 필요가 있다. 이것은 강제적인 것은 아니지만, 디버그 버젼의 런타임은, 파기되는 백 버퍼의 내용을 임의의 데이터로 덧쓰기할 수 있으므로, 개발자는 어플리케이션이 백 버퍼 표면 전체를 올바르게 갱신하고 있는 것을 확인할 수 있다.

풀 스크린 스왑 체인의 경우, 디바이스 또는 스왑 체인의 생성시에 D3DPRESENT_PARAMETERS 구조체의 FullScreen_PresentationInterval 멤버에 할당할 수 있었던 값에 의해 프레젠테이션 레이트가 정해진다. 이 값이 D3DPRESENT_INTERVAL_IMMEDIATE 가 아닌 경우, 프레젠테이션은 모니터의 수직 동기와 동기 된다. 윈도우 스왑 체인의 경우, 프레젠테이션은 카피 처리에 의해 이행 되어, 항상 즉석에서 실행된다.

D3DSWAPEFFECT_FLIP
스왑 체인에는 복수의 백 버퍼가 포함되는 일이 있어, 프런트 버퍼를 포함한 순회 기다리는 행렬로서 볼 수가 있다. 이 기다리는 행렬 중(안)에서는, 백 버퍼에 항상 0 으로부터 N -1 (N 는 백 버퍼의 수)까지가 연속한 숫자를 붙일 수 있다. 따라서, 0 은 프레젠테이션 되는 가장 낡은 버퍼를 나타낸다. Present 가 불려 가면(자), 기다리는 행렬이 「순환」되어, 프런트 버퍼가 백 버퍼 (N - 1)가 되어, 백 버퍼 0 이 새로운 프런트 버퍼가 된다.

풀 스크린 스왑 체인의 경우, 디바이스 또는 스왑 체인의 생성시에 D3DPRESENT_PARAMETERS 구조체의 FullScreen_PresentationInterval 멤버에 할당할 수 있었던 값에 의해 프레젠테이션 레이트가 정해진다. 이 값이 D3DPRESENT_INTERVAL_IMMEDIATE 가 아닌 경우, 프레젠테이션은 모니터의 수직 동기와 동기 된다. 윈도우 스왑 체인의 경우, 후립핑은 카피 처리에 의해 이행 되어 프레젠테이션은 항상 즉석에서 실행된다.

D3DSWAPEFFECT_COPY
스왑 이펙트는, 단일의 백 버퍼를 구성하는 스왑 체인 에 대해서만 지정할 수 있다. 윈도우 스왑 체인의 경우도 풀 스크린 스왑 체인의 경우도, 런타임은 카피 베이스의 Present 처리에 의한 시멘틱스를 보증한다. 즉, 백 버퍼의 내용이 변경될 것은 없고, 플립 베이스의 Present 처리로 행해지도록(듯이) 프런트 버퍼의 내용으로 옮겨놓을 수 있을 것은 없다.

윈도우 스왑 체인의 경우,Present 처리에 의해 백 버퍼의 내용이 타겟 윈도우의 클라이언트 영역에 즉석에서 카피된다. 카피 내용과 디스플레이 어댑터의 수직귀선간격과의 동기 처리는 행해지지 않기 때문에, 「테아링」효과가 나타나는 일이 있다. 윈도우 어플리케이션에서는, 그러한 테아링 효과를 지우거나 최소한으로 억제하기 위해서(때문에), D3DSWAPEFFECT_COPY_VSYNC 를 사용할 수 있다.

풀 스크린 스왑 체인의 경우, 런타임은 플립 처리와 카피 처리의 편성 (필요에 따라서, 은폐 백 버퍼로 지원 된다)을 사용해 Present 처리를 실시한다. 따라서, 프레젠테이션은 디스플레이 어댑터의 수직귀선과 동기 되어 그 레이트는 선택된 프레젠테이션 간격에 의해 제어된다. 다만, D3DPRESENT_INTERVAL_IMMEDIATE 플래그로 지정된 스왑 체인은 예외이다. (D3DPRESENT_PARAMETERS 구조체의 FullScreen_PresentationInterval 멤버의 설명을 참조할것). 이 경우,Present 처리는 수직귀선을 대기하지 않고 , 백 버퍼의 내용을 프런트 버퍼에 직접 카피한다.

D3DSWAPEFFECT_COPY_VSYNC
D3DSWAPEFFECT_COPY 와 같이, 이 스왑 이펙트는, 단일의 백 버퍼로 구성되는 스왑 체인에서만 사용할 수 있다. 위에의 D3DSWAPEFFECT_COPY 로 설명한 것처럼, 스왑 체인에 적용되는 Present 처리가 카피 시멘틱스를 제시하는 것이 보증된다.

윈도우 스왑 체인의 경우,Present 처리에 의해 백 버퍼의 내용이 타겟 윈도우의 클라이언트 영역에 즉석에서 카피된다. 어댑터가 디스플레이상의 전송처의 직사각형내에서 스캔 하고 있는 동안, 런타임은 카피 처리를 피해 테아링 효과를 배제하려고 한다. 또, 런타임은, 어댑터의 리프레쉬 간격의 사이에 카피 처리를 겨우 1 회 실행해, 프레젠테이션의 빈도를 제한한다. 다만, 어댑터가 라스터 스테이터스의 보고 기능을 지원 하고 있지 않는 경우에는, 스왑 체인은 D3DSWAPEFFECT_COPY 스왑 이펙트로 생성 된 것 같은 기능을 한다. (D3DCAPS8 의 Caps 멤버에 대해서는, D3DCAPS_READ_SCANLINE 플래그값의 설명을 참조할것).

풀 스크린 스왑 체인의 경우, D3DSWAPEFFECT_COPY_VSYNC 는 D3DSWAPEFFECT_COPY 와 같다. 다만, D3DPRESENT_INTERVAL_IMMEDIATE 플래그는, D3DSWAPEFFECT_COPY_VSYNC 와 함께 사용했을 경우에는 아무것도 효과가 없다. (D3DPRESENT_PARAMETERS 구조체의 FullScreen_PresentationInterval 멤버의 설명을 참조할것).

D3DSWAPEFFECT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

Present 를 호출한 후의 백 버퍼 상태는, 각 스왑 이펙트에 의해 명확하게 정의되고 있어 Microsoft®Direct3D® 디바이스가 풀 스크린 스왑 체인과 윈도우 스왑 체인의 어디에서 생성 되었는지를 따라, 이 상태가 영향을 받을 것은 없다. 특히, D3DSWAPEFFECT_FLIP 스왑 이펙트는 윈도우에서도 풀 스크린에서도 똑같이 동작해, Direct3D 런타임은 외부 버퍼를 생성 하는 것으로 이것을 보증하고 있다. 결과적으로, 그러한 악영향을 회피할 수 있는 경우에는, 항상 어플리케이션으로 D3DSWAPEFFECT_DISCARD 를 사용하는 것을 추천 한다. 메모리의 소비 및 퍼포먼스의 점에 대해, 이 스왑 체인은 항상 가장 효율적인 것이 이유이다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::Reset ,D3DPRESENT_PARAMETERS


D3DTEXTUREADDRESS

지원 되고 있는 텍스쳐 addressing mode를 기술하는 정수를 정의한다.

typedef enum _D3DTEXTUREADDRESS {
    D3DTADDRESS_WRAP            = 1,
    D3DTADDRESS_MIRROR          = 2,
    D3DTADDRESS_CLAMP           = 3,
    D3DTADDRESS_BORDER          = 4,
    D3DTADDRESS_MIRRORONCE      = 5,

    D3DTADDRESS_FORCE_DWORD     = 0x7fffffff
} D3DTEXTUREADDRESS;

정수

D3DTADDRESS_WRAP
모든 정수 접합점으로써 텍스쳐를 붙여 맞춘다. 예를 들어, u 의 값이 0 에서 3 까지의 경우, 텍스쳐는 3 회 반복해져 미러링은 행해지지 않는다.
D3DTADDRESS_MIRROR
모든 정수 접합점으로써 텍스쳐의 후립핑이 일어나는 것을 제외하면, D3DTADDRESS_WRAP 와 같다. 예를 들어, u 의 값이 0 에서 1 의 범위에 있는 경우, 텍스쳐의 처리는 보통대로 행해지지만, 1 에서 2 의 범위에 있는 경우는 플립 (밀러화)을 해 2 에서 3 의 범위의 경우는 다시 보통의 처리를 한다. 이후, 이 패턴이 반복해진다.
D3DTADDRESS_CLAMP
범위 [0.0, 1.0] 의 외측의텍스쳐 좌표가, 각각,0.0 으로 1.0 의 텍스쳐 칼라로 설정된다.
D3DTADDRESS_BORDER
범위 [0.0, 1.0] 의 외측의 텍스쳐 좌표는, 경계색으로 설정된다.
D3DTADDRESS_MIRRORONCE
D3DTADDRESS_MIRROR 및 D3DTADDRESS_CLAMP 에 유사하고 있다. 텍스쳐 좌표의 절대치를 취득해 (0 을 중심으로 미러링 되고), 최대치에 제한한다. 가장 일반적인 용도는 볼륨 텍스쳐로 사용하는 것이다. 볼륨 텍스쳐에서는, 완전한 D3DTADDRESS_MIRRORONCE 텍스쳐 addressing mode는 필요없지만, 데이터는 1 개의 축으로 따라 대칭이다.
D3DTADDRESS_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DTEXTURESTAGESTATETYPE


D3DTEXTUREFILTERTYPE

텍스쳐 스테이지에 대한 텍스쳐 필터 링 모드를 정의한다.

typedef enum _D3DTEXTUREFILTERTYPE {
    D3DTEXF_NONE            = 0,
    D3DTEXF_POINT           = 1,
    D3DTEXF_LINEAR          = 2,
    D3DTEXF_ANISOTROPIC     = 3,
    D3DTEXF_FLATCUBIC       = 4,
    D3DTEXF_GAUSSIANCUBIC   = 5,

    D3DTEXF_FORCE_DWORD     = 0x7fffffff
} D3DTEXTUREFILTERTYPE;

정수

D3DTEXF_NONE
밉맵 처리를 무효로 한다. 래스터라이저는 대신에 확대 필터를 사용한다.
D3DTEXF_POINT
텍스쳐의 확대 필터 또는 축소 필터로서 사용되는 점필터 링. 희망의 픽셀값에 가장 가까운 좌표를 가지는 텍셀을 사용한다.

밉맵 레벨간에 사용되는 텍스쳐 필터는, 최근점밉맵 필터이다. 래스터라이저는 가장 가까운 밉맵 텍스쳐의 텍셀로부터의 색을 사용한다.

D3DTEXF_LINEAR
텍스쳐의 확대 필터 또는 축소 필터로서 사용되는 바이리니아 보간 필터 링. 희망의 픽셀을 둘러싸는 2 x 2 영역의 텍셀의 중량감 첨부 평균을 사용한다.

밉맵 레벨간에 사용되는 텍스쳐 필터는, 트라이 리니어 밉맵 보간이다. 래스터라이저는, 가장 가까운 밉맵 텍스쳐 2 점으로부터의 텍셀을 사용해 픽셀색을 선형 보간 한다.

D3DTEXF_ANISOTROPIC
텍스쳐의 확대 필터 또는 축소 필터로서 사용되는 이방성 텍스쳐 필터 링. 텍스쳐 다각형과 스크린 평면간의 각도의 상위에 의해 일어나는 일그러짐을 보정한다.
D3DTEXF_FLATCUBIC
텍스쳐 확대 필터로서 사용되는 평면 큐브 필터 링.
D3DTEXF_GAUSSIANCUBIC
텍스쳐 확대 필터로서 사용되는 Gauss 큐브 필터 링.
D3DTEXF_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

디바이스의 유효한 필터 링 모드가 모두 볼륨 맵에 적용되는 것은 아니다. 일반적으로, 볼륨 맵에서는, D3DTEXF_POINT 및 D3DTEXF_LINEAR 확대 필터가 지원 되고 있다. D3DPTEXTURECAPS_MIPVOLUMEMAP 가 설정되어 있는 경우, 볼륨 맵에서는, D3DTEXF_POINT 밉맵 필터와 D3DTEXF_POINT 및 D3DTEXF_LINEAR 축소 필터가 지원 된다. 디바이스는, 볼륨 맵의 D3DTEXF_LINEAR 밉맵 필터를 지원 하는 경우와 하지 않는 경우가 있다. DirectX 8 디바이스가 2D 맵의 이방성 필터 링을 지원 하고 있는 경우에는, 반드시 볼륨 맵의 이방성 필터 링을 지원 하고 있을 필요는 없다. 다만, 이방성 필터 링이 지원되어 있지 않은 경우, 이방성 필터 링을 사용하는 어플리케이션에서는, 가장 유효한 필터 링 (선형등)을 받는다.

텍스쳐 스테이지의 확대 필터를 설정하려면 ,IDirect3DDevice8::SetTextureStageState 메소드를 호출해, 제 2 파라미터로서 D3DTSS_MAGFILTER 값을 지정해, 제 3 파라미터로서 이 열거의 멤버의 어느쪽이든을 지정한다.

텍스쳐 스테이지의 축소 필터를 설정하려면 ,SetTextureStageState 메소드를 호출해, 제 2 파라미터로서 D3DTSS_MINFILTER 값을 지정해, 제 3 파라미터로서 이 열거의 멤버의 어느쪽이든을 지정한다.

밉맵 레벨간에 사용하는 텍스쳐 필터를 설정하려면 ,SetTextureStageState 메소드를 호출해, 제 2 파라미터로서 D3DTSS_MIPFILTER 값을 지정해, 제 3 파라미터로서 이 열거의 멤버의 어느쪽이든을 지정한다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DTEXTURESTAGESTATETYPE


D3DTEXTUREOP

스테이지마다의 텍스쳐 블렌딩 처리를 정의한다.

typedef enum _D3DTEXTUREOP {
    D3DTOP_DISABLE                   =  1,
    D3DTOP_SELECTARG1                =  2,
    D3DTOP_SELECTARG2                =  3,
    D3DTOP_MODULATE                  =  4,
    D3DTOP_MODULATE2X                =  5,
    D3DTOP_MODULATE4X                =  6,
    D3DTOP_ADD                       =  7,
    D3DTOP_ADDSIGNED                 =  8,
    D3DTOP_ADDSIGNED2X               =  9,
    D3DTOP_SUBTRACT                  = 10,
    D3DTOP_ADDSMOOTH                 = 11,
    D3DTOP_BLENDDIFFUSEALPHA         = 12,
    D3DTOP_BLENDTEXTUREALPHA         = 13,
    D3DTOP_BLENDFACTORALPHA          = 14,
    D3DTOP_BLENDTEXTUREALPHAPM       = 15,
    D3DTOP_BLENDCURRENTALPHA         = 16,
    D3DTOP_PREMODULATE               = 17,
    D3DTOP_MODULATEALPHA_ADDCOLOR    = 18,
    D3DTOP_MODULATECOLOR_ADDALPHA    = 19,
    D3DTOP_MODULATEINVALPHA_ADDCOLOR = 20,
    D3DTOP_MODULATEINVCOLOR_ADDALPHA = 21,
    D3DTOP_BUMPENVMAP                = 22,
    D3DTOP_BUMPENVMAPLUMINANCE       = 23,
    D3DTOP_DOTPRODUCT3               = 24,
    D3DTOP_MULTIPLYADD               = 25,
    D3DTOP_LERP                      = 26,

    D3DTOP_FORCE_DWORD               = 0x7fffffff,
} D3DTEXTUREOP;

정수

제어 멤버
D3DTOP_DISABLE
이 텍스쳐 스테이지, 및 보다 높은 인덱스를 가지는 스테이지로부터의 출력을 모두 무효로 한다. 텍스쳐 매핑을 무효로 하려면 , 이것을 최초의 텍스쳐 스테이지 (스테이지 0)의 칼라 처리로서 설정한다. 칼라 처리가 유효하게 되어 있을 때는, 알파 처리를 무효로 하는 것은 할 수 없다. 칼라 블렌딩이 유효한 경우, 알파 처리를 D3DTOP_DISABLE 로 설정 하면, 부정의 동작이 생긴다.
D3DTOP_SELECTARG1
이 텍스쳐 스테이지의 최초의 색, 또는 알파 인수를 변경하지 않고 출력으로서 사용한다. 이 처리는, D3DTSS_COLOROP 텍스쳐 스테이지 스테이트에서 사용 하면색인수에 영향을 주어 D3DTSS_ALPHAOP 로 사용했을 경우에는 알파 인수에 영향을 준다.

D3DTOP_SELECTARG2
이 텍스쳐 스테이지의 2 번째의 색, 또는 알파 인수를 변경하지 않고 출력으로서 사용한다. 이 처리는, D3DTSS_COLOROP 텍스쳐 스테이지 스테이트에서 사용 하면색인수에 영향을 주어 D3DTSS_ALPHAOP 로 사용했을 경우에는 알파 인수에 영향을 준다.

곱셈 멤버
D3DTOP_MODULATE
인수의 성분을 곱셈한다.

D3DTOP_MODULATE2X
인수의 성분을 곱셈해, 그 적을 왼쪽으로 1 비트만 쉬프트 (2 로 곱셈하는 것으로 같다) 해 밝게 한다.

D3DTOP_MODULATE4X
인수의 성분을 곱셈해, 그 적을 왼쪽으로 2 비트만 쉬프트 (4 로 곱셈하는 것으로 같다) 해 밝게 한다.

가감(상태)산멤버
D3DTOP_ADD
인수의 성분을 가산한다.

D3DTOP_ADDSIGNED
바이어스값 -0. 5 를 인수의 성분에 가산해, 값의 유효 범위를 -0. 5 에서 0.5 로 한다.

D3DTOP_ADDSIGNED2X
바이어스값 -0. 5 를 인수의 성분에 가산해, 그 적을 왼쪽으로 1 비트만 쉬프트 한다.

D3DTOP_SUBTRACT
제 1 인수의 성분으로부터, 대응하는 제 2 인수의 성분을 감산한다.

D3DTOP_ADDSMOOTH
제 1 및 제 2 인수를 가산해, 다음에 그 적을 합계로부터 감산한다.

선형 알파 블렌딩 멤버
D3DTOP_BLENDDIFFUSEALPHA, D3DTOP_BLENDTEXTUREALPHA, D3DTOP_BLENDFACTORALPHA, 및 D3DTOP_BLENDCURRENTALPHA
각 버텍스로부터의 보간 알파 (D3DTOP_BLENDDIFFUSEALPHA), 이 스테이지의 텍스쳐로부터의 알파 (D3DTOP_BLENDTEXTUREALPHA),D3DRS_TEXTUREFACTOR 렌더링 스테이트에서 설정되는 스칼라 알파 (D3DTOP_BLENDFACTORALPHA), 또는 전의 텍스쳐 스테이지로부터의 알파 (D3DTOP_BLENDCURRENTALPHA)를 사용해, 이 스테이지의 선형 블렌딩을 실시한다.

D3DTOP_BLENDTEXTUREALPHAPM
미리 곱셈된 알파를 사용하는 텍스쳐 스테이지의 선형 블렌딩을 실행한다.

스펙큐러 매핑 멤버
D3DTOP_PREMODULATE
현재의 텍스쳐 스테이지와 다음의 텍스쳐 스테이지의 사이에 곱셈을 실시한다.
D3DTOP_MODULATEALPHA_ADDCOLOR
제 1 인수의 알파를 사용해 제 2 인수의 칼라를 조정해, 그 결과를 제 1 인수에 가산한다. 이 처리는, 칼라 처리 (D3DTSS_COLOROP)에서만 지원 된다.

D3DTOP_MODULATECOLOR_ADDALPHA
인수를 조정해, 제 1 인수의 알파를 가산한다. 이 처리는, 칼라 처리 (D3DTSS_COLOROP)에서만 지원 된다.

D3DTOP_MODULATEINVALPHA_ADDCOLOR
D3DTOP_MODULATEALPHA_ADDCOLOR 에 유사하고 있지만, 제 1 인수의 알파의 역수를 사용한다. 이 처리는, 칼라 처리 (D3DTSS_COLOROP)에서만 지원 된다.

D3DTOP_MODULATEINVCOLOR_ADDALPHA
D3DTOP_MODULATECOLOR_ADDALPHA 에 유사하고 있지만, 제 1 인수의 색의 역수를 사용한다. 이 처리는, 칼라 처리 (D3DTSS_COLOROP)에서만 지원 된다.

범프 맵핑 멤버
D3DTOP_BUMPENVMAP
다음의 텍스쳐 스테이지의 환경 맵 (휘도 없음)에 의한, 픽셀 단위의 범프 맵핑을 실행한다. 이 처리는, 칼라 처리 (D3DTSS_COLOROP)에서만 지원 된다.
D3DTOP_BUMPENVMAPLUMINANCE
다음의 텍스쳐 스테이지의 환경 맵 (휘도 있어)에 의한, 픽셀 단위의 범프 맵핑을 실행한다. 이 처리는, 칼라 처리 (D3DTSS_COLOROP)에서만 지원 된다.
D3DTOP_DOTPRODUCT3
각 인수의 요소를 (부호부 요소로서) 곱셈해 적을 가산해, 얻을 수 있던 합계값을 모든 칼라 채널에, 알파를 포함해 복제한다. 이 처리가 지원 되는 것은 칼라 처리와 알파 처리에 대해서이다.

DirectX 6.0 및 7.0 의 멀티 텍스쳐 처리에서는, 위의 입력은, 부호 첨부 데이터를 시뮬레이트 하기 위한(해), 사용하기 전에 모두 0.5 쉬프트 되고 (y = x - 0.5), 결과의 스칼라는 정의 값에 제한되어 3 개의 출력 채널 모두에게 복제된다. 또, 칼라 처리로서는, rgb 성분을 갱신한 알파를 갱신하지 않는 것에 주의 해야 한다.

다만, DirectX 8.0 쉐이더에서는, 출력을 . rgb 또는 . a 컴퍼넌트, 또는 그 양쪽 모두 (디폴트)에 루팅 하는 것을 지정할 수 있다. 알파 채널로 개별의 스칼라 처리를 지정할 수도 있다.

3항텍스쳐 블렌딩 멤버
D3DTOP_MULTIPLYADD
적화연산을 실행한다. 마지막 2 개의 인수를 취해, 이것들을 곱셈해, 나머지의 입력/소스 인수에 가산해, 이것을 결과에 배치한다.

SRGBA = Arg1 + Arg2 * Arg3

D3DTOP_LERP
제 1 소스 인수로 지정된 비율로, 제 2 및 제 3 소스 인수의 사이를 선형 보간 한다.

SRGBA = (Arg1) * Arg2 + (1-Arg1) * Arg3.

그 외의 멤버
D3DTOP_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거형의 멤버는, D3DTSS_COLOROP 또는 D3DTSS_ALPHAOP 값으로 IDirect3DDevice8::SetTextureStageState 메소드를 호출해 칼라 처리 또는 알파 처리를 설정할 때에 사용된다.

위에의식에서는, SRGBA 는 텍스쳐 처리로 생성 되는 RGBA 색,Arg1,Arg2, 및 Arg3 는 텍스쳐 인수의 완전 RGBA 색이다. 인수의 개개의 요소는, 첨자를 붙여 표기된다. 예를 들어, 인수 1 의 알파 요소는 Arg1A 로서 나타내진다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DTEXTURESTAGESTATETYPE


D3DTEXTURESTAGESTATETYPE

텍스쳐 스테이지 스테이트를 정의한다.

typedef enum _D3DTEXTURESTAGESTATETYPE {
    D3DTSS_COLOROP               =  1,
    D3DTSS_COLORARG1             =  2,
    D3DTSS_COLORARG2             =  3,
    D3DTSS_ALPHAOP               =  4,
    D3DTSS_ALPHAARG1             =  5,
    D3DTSS_ALPHAARG2             =  6,
    D3DTSS_BUMPENVMAT00          =  7,
    D3DTSS_BUMPENVMAT01          =  8,
    D3DTSS_BUMPENVMAT10          =  9,
    D3DTSS_BUMPENVMAT11          = 10,
    D3DTSS_TEXCOORDINDEX         = 11,
    D3DTSS_ADDRESSU              = 13,
    D3DTSS_ADDRESSV              = 14,
    D3DTSS_BORDERCOLOR           = 15,
    D3DTSS_MAGFILTER             = 16,
    D3DTSS_MINFILTER             = 17,
    D3DTSS_MIPFILTER             = 18,
    D3DTSS_MIPMAPLODBIAS         = 19,
    D3DTSS_MAXMIPLEVEL           = 20,
    D3DTSS_MAXANISOTROPY         = 21,
    D3DTSS_BUMPENVLSCALE         = 22,
    D3DTSS_BUMPENVLOFFSET        = 23,
    D3DTSS_TEXTURETRANSFORMFLAGS = 24,
    D3DTSS_ADDRESSW              = 25,
    D3DTSS_COLORARG0             = 26,
    D3DTSS_ALPHAARG0             = 27,
    D3DTSS_RESULTARG             = 28,

    D3DTSS_FORCE_DWORD           = 0x7fffffff
} D3DTEXTURESTAGESTATETYPE;

정수

D3DTSS_COLOROP
텍스쳐 스테이지 스테이트는 텍스쳐 칼라 블렌딩 처리이며,D3DTEXTUREOP 열거형의 멤버에 의해 식별된다. 최초의 텍스쳐 스테이지 (스테이지 0)의 디폴트값은 D3DTOP_MODULATE 이며, 그 이외의 모든 스테이지의 디폴트값은 D3DTOP_DISABLE 이다.
D3DTSS_COLORARG1
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 최초의 색인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트의 인수는 D3DTA_TEXTURE 이다.

읽고 쓰기용의 텐포라리레지스타의 색을 선택하려면 , D3DTA_TEMP 를 지정한다. D3DTA_TEMP 는, D3DPMISCCAPS_TSSARGTEMP 디바이스 능력이 존재하는 경우에 지원 된다. 이 레지스터의 디폴트값은, (0.0, 0.0, 0.0, 0.0)이다.

D3DTSS_COLORARG2
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 2 번째의 색인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트의 인수는 D3DTA_CURRENT 이다.

읽고 쓰기용의 텐포라리레지스타의 색을 선택하려면 , D3DTA_TEMP 를 지정한다. D3DTA_TEMP 는, D3DPMISCCAPS_TSSARGTEMP 디바이스 능력이 존재하는 경우에 지원 된다. 이 레지스터의 디폴트값은, (0.0, 0.0, 0.0, 0.0)이다.

D3DTSS_ALPHAOP
텍스쳐 스테이지 스테이트는, 텍스쳐 알파 블렌딩 처리이며,D3DTEXTUREOP 열거형의 멤버에 의해 식별된다. 최초의 텍스쳐 스테이지 (스테이지 0)의 디폴트값은 D3DTOP_SELECTARG1 이며, 그 이외의 모든 스테이지의 디폴트값은 D3DTOP_DISABLE 이다.
D3DTSS_ALPHAARG1
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 최초의 알파 인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트의 인수는 D3DTA_TEXTURE 이다. 스테이지에 텍스쳐가 설정되어 있지 않은 경우는, D3DTA_DIFFUSE 가 디폴트의 인수가 된다.

읽고 쓰기용의 텐포라리레지스타의 색을 선택하려면 , D3DTA_TEMP 를 지정한다. D3DTA_TEMP 는, D3DPMISCCAPS_TSSARGTEMP 디바이스 능력이 존재하는 경우에 지원 된다. 이 레지스터의 디폴트값은, (0.0, 0.0, 0.0, 0.0)이다.

D3DTSS_ALPHAARG2
텍스쳐 스테이지 스테이트는, 스테이지의 2 번째의 알파 인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트의 인수는 D3DTA_CURRENT 이다.

읽고 쓰기용의 텐포라리레지스타의 색을 선택하려면 , D3DTA_TEMP 를 지정한다. D3DTA_TEMP 는, D3DPMISCCAPS_TSSARGTEMP 디바이스 능력이 존재하는 경우에 지원 된다. 이 레지스터의 디폴트값은, (0.0, 0.0, 0.0, 0.0)이다.

D3DTSS_BUMPENVMAT00
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [0][0] 계수에 대한 부동 소수점값이다. 디폴트값은 0.0 이다.
D3DTSS_BUMPENVMAT01
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [0][1] 계수에 대한 부동 소수점값이다. 디폴트값은 0.0 이다.
D3DTSS_BUMPENVMAT10
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [1][0] 계수에 대한 부동 소수점값이다. 디폴트값은 0.0 이다.
D3DTSS_BUMPENVMAT11
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [1][1] 계수에 대한 부동 소수점값이다. 디폴트값은 0.0 이다.
D3DTSS_TEXCOORDINDEX
이 텍스쳐 스테이지에서 사용하기 위해서 설정된 텍스쳐 좌표 인덱스. 이 플래그는, 고정 기능 버텍스 처리에서만 사용한다. 예를 들어, 버텍스 쉐이더에서는 사용하지 않는다. 버텍스 쉐이더를 사용해 렌더링 하면나무는, 각 스테이지의 텍스쳐 인덱스를 디폴트값으로 설정할 필요가 있다. 각 스테이지의 디폴트의 인덱스는, 스테이지 인덱스와 같다. 이 스테이트에는, 텍스쳐 스테이지에서 사용하는, 각 버텍스의 좌표 세트의 제로로부터 시작되는 인덱스를 설정한다. 버텍스 1 개에 대해서 최대 8 조까지의 텍스쳐 좌표를 설정할 수 있다. 버텍스가, 지정된 인덱스의 텍스쳐 좌표 세트를 포함하지 않은 경우는, u 및 v 좌표 (0,0)가 디폴트로 사용된다.

또, 어플리케이션에서는, (설정되는 인덱스와의논리합으로서) 이하의 플래그의 어느쪽이든을 설정해, 텍스쳐 트랜스 폼용의 입력 텍스쳐 좌표를 자동적으로 생성하도록(듯이) Microsoft® Direct3D® 에 요구할 수 있다. 제로에 해결되는 D3DTSS_TCI_PASSTHRU 를 제외해, 설정되는 인덱스와 이하의 플래그의 어느쪽이든을 사용 하면, 텍스쳐 랩핑 모드의 결정에 인덱스가 엄밀하게 사용된다. 이 플래그는 환경 매핑을 실시하는 경우에는 특히 유효하다.

D3DTSS_TCI_PASSTHRU
버텍스 포맷내의 지정된 텍스쳐 좌표를 사용한다. 이 값은 제로에 해결된다.
D3DTSS_TCI_CAMERASPACENORMAL
이 스테이지의 텍스쳐 트랜스 폼의 입력 텍스쳐 좌표로서 카메라 공간에 트랜스 폼 된 버텍스 법선을 사용한다.
D3DTSS_TCI_CAMERASPACEPOSITION
이 스테이지의 텍스쳐 트랜스 폼의 입력 텍스쳐 좌표로서 카메라 공간에 트랜스 폼 된 버텍스 위치 좌표를 사용한다.
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
이 스테이지의 텍스쳐 트랜스 폼의 입력 텍스쳐 좌표로서 카메라 공간에 트랜스 폼 된 반사 벡터를 사용한다. 반사 벡터는 입력 버텍스 위치 좌표와 법선 벡터로부터 계산된다.
D3DTSS_ADDRESSU
D3DTEXTUREADDRESS 열거형의 멤버. u 좌표로 사용하는 텍스쳐 애드레싱 방법을 선택한다. 디폴트값은 D3DTADDRESS_WRAP 이다.
D3DTSS_ADDRESSV
D3DTEXTUREADDRESS 열거형의 멤버. v 좌표로 사용하는 텍스쳐 애드레싱 방법을 선택한다. 디폴트값은 D3DTADDRESS_WRAP 이다.
D3DTSS_BORDERCOLOR
[0.0, 1.0] 의 범위의 밖에 있는 텍스쳐 좌표의 라스터화를 실행할 경우에 사용하는 색을 기술하는 D3DCOLOR 값. 디폴트색은 0x00000000 이다.
D3DTSS_MAGFILTER
텍스쳐를 원시적으로 렌더링 할 경우에 사용하는 텍스쳐 확대 필터를 나타내는 D3DTEXTUREFILTERTYPE 열거형의 멤버. 디폴트값은 D3DTEXF_POINT 이다.
D3DTSS_MINFILTER
D3DTEXTUREFILTERTYPE 열거형의 멤버로, 텍스쳐를 프리미티브상에 렌더링 할 경우에 사용하는 텍스쳐 축소 필터를 나타낸다. 디폴트값은 D3DTEXF_POINT 이다.
D3DTSS_MIPFILTER
D3DTEXTUREFILTERTYPE 열거형의 멤버로, 밉맵 레벨간에 사용하는 텍스쳐 필터를 나타낸다. 디폴트값은 D3DTEXF_NONE 이다.
D3DTSS_MIPMAPLODBIAS
밉맵 상세 바이어스의 레벨. 이것을 이용 하면, 텍스쳐에 질량감을 주거나 희미해진 느낌을 줄 수가 있다. 디폴트값은 0 이다. 이 스테이트의 값은 부동 소수점값이다. IDirect3DDevice8::SetTextureStageState 및 IDirect3DDevice8::GetTextureStageState 는 DWORD 값을 사용하기 위해(때문에), 이하의 코드예로 가리키도록(듯이), 값을 저장 한 변수를 캐스트 해야 한다.
pd3dDevice->SetTextureStageState(D3DTSS_MIPMAPLODBIAS, *((LPDWORD) (&fBias)));

바이어스의 각 단위 (+/-1. 0)은, 정확하게 1 밉맵 레벨 마다 선택 범위를 변경한다. 부의 바이어스는, 사용하는 밉맵 레벨을 크게 한다. 결과는 샤프하게 되지만, 톱니 모양 한 이미지가 된다. 정의 바이어스는, 사용하는 밉맵 레벨을 작게 한다. 결과는 희미해진 이미지가 된다. 또, 정의 바이어스를 지정 하면, 참조되는 텍스쳐 데이터가 적게 되어, 시스템에 따라서는 퍼포먼스가 향상하는 경우가 있다.

D3DTSS_MAXMIPLEVEL
어플리케이션으로 허용 하는 최대 밉맵 상세 레벨 밉맵 체인의 선두를 시점으로 하는 인덱스로서 표현된다. 낮은 값이, 밉맵 체인내의 비싼 상세 레벨을 나타낸다. 0 이 디폴트값으로, 전레벨이 사용 가능한 것을 나타낸다. 0 이외의 값은, 지정된 인덱스보다 높은 상세 레벨의 밉맵을 표시할 수 없는 것을 나타낸다.
D3DTSS_MAXANISOTROPY
이방성 레벨의 최대치. 디폴트값은 1 이다.
D3DTSS_BUMPENVLSCALE
범프 맵 휘도에 사용하는 부동 소수점수(실수)의 스케일값. 디폴트값은 0.0 이다.
D3DTSS_BUMPENVLOFFSET
범프 맵 휘도에 사용하는 부동 소수점수(실수)의 오프셋(offset). 디폴트값은 0.0 이다.
D3DTSS_TEXTURETRANSFORMFLAGS
텍스쳐 스테이지의 텍스쳐 좌표의 트랜스 폼을 제어하는 D3DTEXTURETRANSFORMFLAGS 열거형의 멤버. 디폴트는 D3DTTFF_DISABLE 이다.
D3DTSS_ADDRESSW
D3DTEXTUREADDRESS 열거형의 멤버. w 좌표로 사용하는 텍스쳐 애드레싱 방법을 선택한다. 디폴트값은 D3DTADDRESS_WRAP 이다.
D3DTSS_COLORARG0
3항연산 (적화 및 선형 보간)의 3 번째의 색오퍼랜드의 설정. 텍스쳐 인수 플래그에 의해 식별된다. 이 설정은, D3DTEXOPCAPS_MULTIPLYADD 또는 D3DTEXOPCAPS_LERP 디바이스 능력이 존재하는 경우에 지원 된다.

읽고 쓰기용의 텐포라리레지스타의 색을 선택하려면 , D3DTA_TEMP 를 지정한다. D3DTA_TEMP 는, D3DPMISCCAPS_TSSARGTEMP 디바이스 능력이 존재하는 경우에 지원 된다. 이 레지스터의 디폴트값은, (0.0, 0.0, 0.0, 0.0)이다.

D3DTSS_ALPHAARG0
3항연산 (적화 및 선형 보간)의 알파 채널 실렉터 오퍼랜드의 설정. 텍스쳐 인수 플래그에 의해 식별된다. 이 설정은, D3DTEXOPCAPS_MULTIPLYADD 또는 D3DTEXOPCAPS_LERP 디바이스 능력이 존재하는 경우에 지원 된다.

읽고 쓰기용의 텐포라리레지스타의 색을 선택하려면 , D3DTA_TEMP 를 지정한다. D3DTA_TEMP 는, D3DPMISCCAPS_TSSARGTEMP 디바이스 능력이 존재하는 경우에 지원 된다. 이 레지스터의 디폴트값은, (0.0, 0.0, 0.0, 0.0)이다.

D3DTSS_RESULTARG
이 스테이지의 결과의 목적지 레지스터를 선택하기 위한 설정. 텍스쳐 인수 플래그에 의해 식별된다. 이 값은, D3DTA_CURRENT (디폴트값) 또는 D3DTA_TEMP 로 설정할 수 있다. D3DTA_TEMP 는, 입력 인수로서 이후의 스테이지에 읽어들일 수가 있는 단일의 텐포라리레지스타이다. 포그브렌다 및 frame buffer에게 건네지는 최종적인 색은 D3DTA_CURRENT 로부터 취득되므로, 마지막에 액티브한 텍스쳐 스테이지 스테이트는 경향에의 기입으로 설정해야 한다.

이 설정은, D3DPMISCCAPS_TSSARGTEMP 디바이스 능력이 존재하는 경우에 지원 된다.

D3DTSS_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거형의 멤버는, 텍스쳐 스테이트값을 취득 및 설정하기 위해서 IDirect3DDevice8::GetTextureStageState 메소드 및 IDirect3DDevice8::SetTextureStageState 메소드로 사용한다.

D3DTSS_BUMPENVMAT00, D3DTSS_BUMPENVMAT01, D3DTSS_BUMPENVMAT10, 및 D3DTSS_BUMPENVMAT11 범프 맵핑 행렬 계수의 유효 범위는,-8. 0 이상 8.0 미만이다. 이 범위는, 수학적으로는 [-8. 0,8.0] 으로 표기한다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetTextureStageState ,IDirect3DDevice8::SetTextureStageState


D3DTEXTURETRANSFORMFLAGS

텍스쳐 스테이지 스테이트의 값을 정의한다.

typedef enum _D3DTEXTURETRANSFORMFLAGS {
    D3DTTFF_DISABLE         =   0,
    D3DTTFF_COUNT1          =   1,
    D3DTTFF_COUNT2          =   2,
    D3DTTFF_COUNT3          =   3,
    D3DTTFF_COUNT4          =   4,
    D3DTTFF_PROJECTED       = 256,

    D3DTTFF_FORCE_DWORD     = 0x7fffffff
} D3DTEXTURETRANSFORMFLAGS;

정수

D3DTTFF_DISABLE
텍스쳐 좌표는 래스터라이저에 직접 건네받는다.
D3DTTFF_COUNT1
래스터라이저는 1D 텍스쳐 좌표를 상정한다.
D3DTTFF_COUNT2
래스터라이저는 2D 텍스쳐 좌표를 상정한다.
D3DTTFF_COUNT3
래스터라이저는 3D 텍스쳐 좌표를 상정한다.
D3DTTFF_COUNT4
래스터라이저는 4D 텍스쳐 좌표를 상정한다.
D3DTTFF_PROJECTED
텍스쳐 좌표는, 래스터라이저에게 건네지기 전에 마지막 요소로 모두 분할된다. 예를 들어, 이 플래그가 D3DTTFF_COUNT3 와 함께 지정되고 있는 경우, 1 번째 및 2 번째의 텍스쳐 좌표는, 래스터라이저에게 건네지기 전에, 3 번째의 좌표로 분할된다.
D3DTTFF_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이러한 플래그는, D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트의 값을 D3DTEXTURESTAGESTATETYPE 열거형으로 설정하기 위해서 사용된다.

동작환경

헤더 : d3d8types.h 로 선언.

참조

D3DTEXTURESTAGESTATETYPE


D3DTRANSFORMSTATETYPE

트랜스 폼 스테이트의 값을 기술하는 정수를 정의한다.

typedef enum _D3DTRANSFORMSTATETYPE {
    D3DTS_VIEW            =  2,
    D3DTS_PROJECTION      =  3,
    D3DTS_TEXTURE0        = 16,
    D3DTS_TEXTURE1        = 17,
    D3DTS_TEXTURE2        = 18,
    D3DTS_TEXTURE3        = 19,
    D3DTS_TEXTURE4        = 20,
    D3DTS_TEXTURE5        = 21,
    D3DTS_TEXTURE6        = 22,
    D3DTS_TEXTURE7        = 23,

    D3DTS_FORCE_DWORD     = 0x7fffffff
} D3DTRANSFORMSTATETYPE;

정수

D3DTS_VIEW
뷰 트랜스 폼 행렬로서 설정되는 트랜스 폼 행렬을 식별한다. 디폴트값은 NULL 이다 (단위행렬).
D3DTS_PROJECTION
투영 트랜스 폼 행렬로서 설정되는 트랜스 폼 행렬을 식별한다. 디폴트값은 NULL 이다 (단위행렬).
D3DTS_TEXTURE0 ~ D3DTS_TEXTURE7
지정된 텍스쳐 스테이지로 설정되는 트랜스 폼 행렬을 식별한다.
D3DTS_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

매크로

D3DTS_WORLD
D3DTS_WORLDMATRIX(0)와 동등.
D3DTS_WORLDMATRIX (index)
index 의 월드 행렬을 설정하는 트랜스 폼 행렬을 식별한다. 버텍스 블렌딩 에 대해서만, 복수의 월드 행렬이 사용된다. 그 이외의 경우는, D3DTS_WORLD 마셔 사용된다.

주의

256 ~ 511 의 범위의 트랜스 폼 스테이트는 예약이 끝난 상태이며, D3DTS_WORLDMATRIX 및 D3DTS_WORLD 매크로를 사용해 인덱스 지정할 수 있는 월드 행렬이, 최대 256 개까지 저장 된다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

IDirect3DDevice8::GetTransform ,IDirect3DDevice8::MultiplyTransform ,IDirect3DDevice8::SetTransform ,D3DTS_WORLD ,D3DTS_WORLDn ,D3DTS_WORLDMATRIX


D3DVERTEXBLENDFLAGS

복수의 행렬에 의한 버텍스 블렌딩 시에 적용되는 수치 또는 행렬을 제어하기 위한 플래그를 정의한다.

typedef enum _D3DVERTEXBLENDFLAGS {
    D3DVBF_DISABLE  =   0,
    D3DVBF_1WEIGHTS =   1,
    D3DVBF_2WEIGHTS =   2,
    D3DVBF_3WEIGHTS =   3,
    D3DVBF_TWEENING = 255,
    D3DVBF_0WEIGHTS = 256
} D3DVERTEXBLENDFLAGS;

정수

D3DVBF_DISABLE
버텍스 블렌딩을 무효로 한다. D3DTS_WORLDMATRIX 매크로에 의해 설정된 월드 행렬만을 적용한다. 트랜스 폼 스테이트에 대한 인덱스값은 0 이다.
D3DVBF_1WEIGHTS
D3DTS_WORLDMATRIX 매크로에 의해 설정된 2 개의 행렬간의 버텍스 블렌딩을 유효하게 한다. 트랜스 폼 스테이트에 대한 인덱스값은, 0 및 1 이다.
D3DVBF_2WEIGHTS
D3DTS_WORLDMATRIX 매크로에 의해 설정된 3 개의 행렬간의 버텍스 블렌딩을 유효하게 한다. 트랜스 폼 스테이트에 대한 인덱스값은, 0, 1, 및 2 이다.
D3DVBF_3WEIGHTS
D3DTS_WORLDMATRIX 매크로에 의해 설정된 4 개의 행렬간의 버텍스 블렌딩을 유효하게 한다. 트랜스 폼 스테이트에 대한 인덱스값은, 0, 1, 2, 및 3 이다.
D3DVBF_TWEENING
버텍스 블렌딩은,D3DRS_TWEENFACTOR 에 할당할 수 있었던 값을 사용해 행해진다.
D3DVBF_0WEIGHTS
1.0 의 중량감으로 단일의 행렬을 사용한다.

주의

이 형태의 멤버는,D3DRS_VERTEXBLEND 렌더링 스테이트에서 사용된다.

지오메트리 블렌딩 (복수의 행렬에 의한 버텍스 블렌딩)에서는, 각 버텍스의 블렌딩 (베타) 가중값을 가지는 버텍스 포맷을 사용해야 한다.

동작환경

헤더 : D3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE ,D3DTS_WORLD ,D3DTS_WORLDn ,D3DTS_WORLDMATRIX ,


D3DZBUFFERTYPE

깊이 버퍼 포맷을 기술하는 정수를 정의한다.

typedef enum _D3DZBUFFERTYPE {
    D3DZB_FALSE                 = 0,
    D3DZB_TRUE                  = 1,
    D3DZB_USEW                  = 2,

    D3DZB_FORCE_DWORD           = 0x7fffffff
} D3DZBUFFERTYPE;

정수

D3DZB_FALSE
깊이 버퍼의 사용을 무효로 한다.
D3DZB_TRUE
z 버퍼의 사용을 가능하게 한다.
D3DZB_USEW
w 버퍼의 사용을 가능하게 한다.
D3DZB_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거형의 멤버는,D3DRS_ZENABLE 렌더링 스테이트에서 사용된다.

동작환경

헤더 : d3d8types.h 로 선언.

참조

D3DRENDERSTATETYPE


그 외의 형태

여기에서는, 구조체에서도 열거형도 아닌 이하의 Microsoft® Direct3D® 형에 대해 기술한다.

  • D3DCOLOR


D3DCOLOR

Microsoft® Direct3D® 의 기본적인 칼라 타입을 정의한다.

typedef DWORD D3DCOLOR;

동작환경

헤더 : D3d8types.h 로 선언.


텍스쳐 인수 플래그

디바이스에 대응하는 각각의 텍스쳐 스테이지는 2 개의 텍스쳐 인수를 가질 수가 있어 이러한 인수는 텍스쳐의 색과 알파 채널에 영향을 준다.

텍스쳐 인수를 취득 또는 설정하려면 ,IDirect3DDevice8::SetTextureStageState 메소드 또는 IDirect3DDevice8::GetTextureStageState 메소드를 호출해,D3DTEXTURESTAGESTATETYPE 열거형의 D3DTSS_COLORARG0, D3DTSS_COLORARG1, D3DTSS_COLORARG2, D3DTSS_ALPHAARG0, D3DTSS_ALPHAARG1, D3DTSS_ALPHAARG2, 또는 D3DTSS_RESULTARG 멤버를 지정한다.

다음에 나타내는 플래그 (인수와 수식자에 정리하고 있다)를 텍스쳐 스테이지의 색과 알파 인수와 함께 사용할 수가 있다. 인수 플래그와 수식자를 조합할 수 있지만, 2 개의 인수 플래그를 조합할 수 없다.

인수 플래그
D3DTA_CURRENT
텍스쳐 인수는 전의 블렌딩 스테이지의 결과이다. 최초의 텍스쳐 스테이지 (스테이지 0)의 경우, 이 인수는 D3DTA_DIFFUSE 와 동등하다. 전의 블렌딩 스테이지가 범프 맵 텍스쳐 (D3DTOP_BUMPENVMAP 처리)를 사용하고 있는 경우, 범프 맵 텍스쳐의 전의 스테이지로부터 텍스쳐가 선택된다. s 가 현재의 텍스쳐 스테이지를 나타내,s – 1 에 범프 맵 텍스쳐가 있는 경우, 이 인수는 텍스쳐 스테이지 s – 2 로부터의 결과 출력이 된다. 읽고 쓰기가 허가된다.
D3DTA_DIFFUSE
텍스쳐 인수는, gouraud shading 처리중에 버텍스의 성분으로부터 보간 해 얻을 수 있던 디퓨즈색이다. 버텍스가 디퓨즈색을 포함하지 않는 경우의 디폴트색은 0xFFFFFFFF 이다. 허가는 읽어내 전용이다.
D3DTA_SELECTMASK
모든 인수에 대응하는 마스크값. 텍스쳐 인수의 설정에는 사용하지 않는다.
D3DTA_SPECULAR
텍스쳐 인수는, gouraud shading 처리중에 버텍스의 성분으로부터 보간 된 스펙큐러색이다. 버텍스가 스펙큐러색을 포함하지 않은 경우, 디폴트색은 0xFFFFFFFF 이다. 허가는 읽어내 전용이다.
D3DTA_TEMP
이 텍스쳐 인수는, 읽고 쓰기용의 텐포라리레지스타의 색이다. D3DTA_TEMP 는, D3DPMISCCAPS_TSSARGTEMP 디바이스 능력이 존재하는 경우에 지원 된다. 이 레지스터의 디폴트값은, (0.0, 0.0, 0.0, 0.0)이다. 허가는 읽고 쓰기이다.
D3DTA_TEXTURE
텍스쳐 인수는, 이 텍스쳐 스테이지의 텍스쳐 칼라이다. 허가는 읽어내 전용이다.
D3DTA_TFACTOR
텍스쳐 인수는,D3DRS_TEXTUREFACTOR 렌더링 스테이트를 사용해 전회 IDirect3DDevice8::SetRenderState 를 호출했을 때의 텍스쳐 계수 세트이다. 허가는 읽어내 전용이다.
수정자 플래그 플래그
D3DTA_ALPHAREPLICATE
처리가 완료하기 전에, 알파 정보를 모든 칼라 채널에 복제한다. 이것은 읽어내 수식자이다.
D3DTA_COMPLEMENT
인수의 역수를 취한다. 예를 들어, 인수의 결과가 변수 x 에 의해 참조되는 경우, 그 값은 1.0 - x 가 된다. 이것은 읽어내 수식자이다.


유연한 버텍스 포맷 플래그

유연한 버텍스 포맷 (FVF)은, 단일의 데이터 스트림에 인터리브 되어 저장 되고 있는 버텍스의 컨텐츠를 기술하기 위해서 사용된다. FVF 코드는, 보통, 고정 기능의 버텍스 처리에 의해 처리되는 데이터를 지정하기 위해서 사용된다.

버텍스의 포맷은, 다음의 플래그에 의해 기술된다. 버텍스 포맷에 대해서는, 「버텍스 포맷에 대하며」를 참조할것.

유연한 버텍스 포맷 (FVF) 플래그
D3DFVF_DIFFUSE
버텍스 포맷이 디퓨즈색성분을 포함한다.
D3DFVF_NORMAL
버텍스 포맷이 버텍스 법선 벡터를 포함한다. 이 플래그를, D3DFVF_XYZRHW 와 함께 사용할 수 없다.
D3DFVF_PSIZE
버텍스 포맷은 포인트 사이즈로 지정되고 있다. 이 사이즈는, 트랜스 폼이 끝난 상태에서도 라이팅이 끝난 상태도 아닌 버텍스에 대한 카메라 공간 단위, 및 트랜스 폼이 끝난 상태로 라이팅 끝난 버텍스에 대한 디바이스 공간 단위로 나타내지고 있다.
D3DFVF_SPECULAR
버텍스 포맷이 스펙큐러색성분을 포함한다.
D3DFVF_XYZ
버텍스 포맷이 트랜스폼 되지 않은 버텍스의 위치 좌표를 포함한다. 이 플래그를, D3DFVF_XYZRHW 와 함께 사용할 수 없다.
D3DFVF_XYZRHW
버텍스 포맷이, 트랜스 폼 된 버텍스의 위치 좌표를 포함한다. 이 플래그를 D3DFVF_XYZ 또는 D3DFVF_NORMAL 플래그와 동시에 사용할 수 없다.
D3DFVF_XYZB1 ~ D3DFVF_XYZB5
버텍스 포맷은, 위치 좌표 데이터, 및 복수의 행렬에 의한 버텍스 블렌딩 처리용의 가중 (베타) 값의 대응수를 포함한다. 현재, Microsoft® Direct3D® 에서는 최대 3 개의 가중값 및 4 개의 블렌딩 행렬로 블렌딩이 가능하다. 블렌딩 행렬의 사용법의 상세한 것에 대하여는, 「인덱스 첨부 버텍스 블렌딩」을 참조할것.
텍스쳐 관련 FVF 플래그
D3DFVF_TEX0 ~ D3DFVF_TEX8
이 버텍스에 대응하는 텍스쳐 좌표 세트의 번호. 이러한 플래그에 대응하는 숫자는 연속 번호로 되어 있지 않다.
D3DFVF_TEXTUREFORMAT1 ~ D3DFVF_TEXTUREFORMAT4
텍스쳐 좌표 세트를 정의하는 값의 번호. D3DFVF_TEXTUREFORMAT1 는 1 차원 좌표를 나타내, D3DFVF_TEXTUREFORMAT2 는 2 차원 좌표를 나타내, 라고 하는 순으로 이하 계속된다. 이 플래그가 단독으로 사용되는 것은 보기 드물어,D3DFVF_TEXCOORDSIZEn 매크로와 함께 사용된다.
마스크값
D3DFVF_POSITION_MASK
위치 좌표 비트를 추출하는 마스크.
D3DFVF_RESERVED0 및 D3DFVF_RESERVED2
유연한 버텍스 포맷의 예약 비트를 추출하기 위한 마스크값. 사용 불가.
D3DFVF_TEXCOUNT_MASK
텍스쳐 flag bit를 추출하기 위한 마스크값.
그 외
D3DFVF_LASTBETA_UBYTE4
인덱스 첨부 버텍스 블렌딩과 고정 기능 FVF 버텍스 쉐이더를 사용하는 경우는, 버텍스 쉐이더에 이 플래그를 지정해야 한다.
D3DFVF_TEXCOUNT_SHIFT
버텍스의 텍스쳐 좌표수를 식별하는 정수값을 몇 비트분 쉬프트 하는지를 나타내는 수. 이 값은, 예를 들어 다음과 같이 사용한다.
    DWORD dwNumTextures = 1;  // 버텍스에는 좌표 세트가
// 1 개(살)만 있다.

    // FVF 의 편성을 만들 때, 값을 쉬프트 시켜 사용한다.
    dwFVF = dwNumTextures<<D3DFVF_TEXCOUNT_SHIFT;

    /*
* 쉬프트 후의 값을 사용해, 여기서 FVF 의 편성을 생성 한다.
     */

자주(잘) 사용되는 플래그의 편성예를 다음에 나타낸다.

    // 라이팅 되어 텍스쳐가 붙지 않는, gouraud shading 된 컨텐츠를 위한,
    // 가벼운 트랜스폼 되지 않은 버텍스.
    dwFVF = ( D3DFVF_XYZ | D3DFVF_DIFFUSE );

    // 라이팅 이루어, 텍스쳐 이루어, gouraud shading 있어.
    // 버텍스 마다 디 푸즈 머트리얼색이 지정되고 있는 트랜스폼 되지 않은 버텍스.
    dwFVF = ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE );

    // 라이트 맵 베이스의 라이팅에 대한 트랜스폼 되지 않은 버텍스.
    dwFVF = ( D3DFVF_XYZ | D3DFVF_TEX2 );

    // 라이트 맵 베이스의 라이팅에 대한 트랜스 폼이 끝난 버텍스.
    // 공유 rhw 있어.
    dwFVF = ( D3DFVF_XYZRHW | D3DFVF_TEX2 );

    // 2 개의 텍스쳐 좌표 세트를 갖춘,
    // 라이팅 계산 되지 않은으로, 색첨부의 컨텐츠에 대한 무거운 버텍스.
    dwFVF = ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE |
              D3DFVF_SPECULAR | D3DFVF_TEX2 );

참조

버텍스 포맷에 대해,지오메트리 블렌딩


FOURCC 코드

Microsoft® Direct3D® 및 Direct3DX 유틸리티 라이브러리에서는, 4 문자의 길이가 특수한 코드 세트가 사용된다. 이러한 코드는, 4 문자 코드 또는 FOURCC 로 불려 비트 맵 이미지, 사운드, 비디오등의 멀티미디어 데이터를 저장 하는 파일의 파일 헤더에 보존된다. FOURCC 는, 멀티미디어 데이터를 생성하기 위해서 사용된 소프트웨어 테크놀러지를 나타낸다. 또, 은근히, 데이터 자체의 포맷도 나타낸다.

Direct3D 어플리케이션은, 이미지의 색이나 포맷의 변환에 FOURCC 를 사용한다.

FOURCC 는, 개개의 멀티미디어 소프트웨어 테크놀러지의 벤더에 의해, Microsoft 에 등록된다. 다음의 일람은, 일반적인 FOURCC 의 일부를 나타내고 있다.

FOURCC | 회사명 | 테크놀러지명
AUR2 | AuraVision Corporation | AuraVision Aura 2:YUV 422
AURA | AuraVision Corporation | AuraVision Aura 1:YUV 411
CHAM | Winnov, Inc. | MM_WINNOV_CAVIARA_CHAMPAGNE
CVID | Supermac | Cinepak by Supermac
CYUV | Creative Labs, Inc. | Creative Labs YUV
DXT1 | Microsoft Corporation | DirectX Texture Compression Format 1
DXT2 | Microsoft Corporation | DirectX Texture Compression Format 2
DXT3 | Microsoft Corporation | DirectX Texture Compression Format 3
DXT4 | Microsoft Corporation | DirectX Texture Compression Format 4
DXT5 | Microsoft Corporation | DirectX Texture Compression Format 5
FVF1 | Iterated Systems, Inc. | Fractal Video Frame
IF09 | Intel Corporation | Intel Intermediate YUV9
IV31 | Intel Corporation | Indeo 3.1
JPEG | Microsoft Corporation | Still Image JPEG DIB
MJPG | Microsoft Corporation | Motion JPEG DIB Format
MRLE | Microsoft Corporation | Run Length Encoding
MSVC | Microsoft Corporation | Video 1
PHMO | IBM Corporation | Photomotion
RT21 | Intel Corporation | Indeo 2.1
ULTI | IBM Corporation | Ultimotion
V422 | Vitec Multimedia | 24-bit YUV 4:2:2
V655 | Vitec Multimedia | 16-bit YUV 4:2:2
VDCT | Vitec Multimedia | Video Maker Pro DIB
VIDS | Vitec Multimedia | YUV 4:2:2 CCIR 601 for V422
YU92 | Intel Corporation | YUV
YUV8 | Winnov, Inc. | MM_WINNOV_CAVIAR_YUV8
YUV9 | Intel Corporation | YUV9
YUYV | Canopus, Co., Ltd. | BI_YUYV, Canopus
ZPEG | Metheus | Video Zipper


반환값

에러는 부의 값으로 나타내지므로, 조합할 수 없다. 이 리스트는, Microsoft® Direct3D® 메소드가 돌려줄 수 있는 값을 집계한 것이다. 각 메소드가 돌려주는 값의 일람에 대해서는, 각 메소드에 대한 설명을 참조할것. 이러한 리스트는 반드시 포괄적인 것이라고는 할 수 없다.

D3D_OK
에러는 발생하고 있지 않다.
D3DERR_CONFLICTINGRENDERSTATE
현재 설정되어 있는 렌더링 스테이트는 함께 사용할 수 없다.
D3DERR_CONFLICTINGTEXTUREFILTER
현재의 텍스쳐 필터는 함께 사용할 수 없다.
D3DERR_CONFLICTINGTEXTUREPALETTE
현재의 텍스쳐는 동시에 사용할 수 없다. 일반적으로 멀티 텍스쳐 디바이스에 대해, 동시에 유효하게 된 팔레트화 텍스쳐로 같은 팔레트를 공유할 필요가 있는 경우에 발생한다.
D3DERR_DEVICELOST
디바이스가 없어지고 있어, 현시점에서는 복원할 수 없기 때문에, 렌더링은 불가능하다.
D3DERR_DEVICENOTRESET
디바이스는 리셋 할 수 없다.
D3DERR_DRIVERINTERNALERROR
내부 드라이버 에러.
D3DERR_INVALIDCALL
메소드의 호출이 무효이다. 예를 들어, 메소드의 파라미터에 무효인 값이 설정되어 있는 경우 등.
D3DERR_INVALIDDEVICE
요구된 디바이스의 종류가 유효하지 않다.
D3DERR_MOREDATA
지정된 버퍼 사이즈 로 유지할 수 있는 이상의 데이터가 존재한다.
D3DERR_NOTAVAILABLE
이 디바이스는, 조회된 테크닉을 지원 하고 있지 않다.
D3DERR_NOTFOUND
요구된 항목이 발견되지 않았다.
D3DERR_OUTOFVIDEOMEMORY
Direct3D 가 처리를 실시하는데 충분한 디스플레이 메모리가 없다.
D3DERR_TOOMANYOPERATIONS
디바이스가 지원 하고 있는 이상의 텍스쳐 필터 링 처리를, 어플리케이션이 요구하고 있다.
D3DERR_UNSUPPORTEDALPHAARG
알파 채널에 대해서 지정되고 있는 텍스쳐 블렌딩 인수를, 디바이스가 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDALPHAOPERATION
알파 채널에 대해서 지정되고 있는 텍스쳐 블렌딩 처리를, 디바이스가 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDCOLORARG
칼라값에 대해서 지정되고 있는 텍스쳐 블렌딩 인수를, 디바이스가 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDCOLOROPERATION
칼라값에 대해서 지정되고 있는 텍스쳐 블렌딩 처리를, 디바이스가 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDFACTORVALUE
디바이스가 지정된 텍스쳐 계수값을 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDTEXTUREFILTER
디바이스가 지정된 텍스쳐 필터를 지원 하고 있지 않다.
D3DERR_WRONGTEXTUREFORMAT
텍스쳐 표면의 픽셀 포맷이 유효하지 않다.
E_FAIL
Direct3D 서브 시스템내에서 원인 불명의 에러가 발생했다.
E_INVALIDARG
무효인 파라미터가 돌아오는 함수에게 건네졌다.
E_INVALIDCALL
메소드의 호출이 무효이다. 예를 들어, 메소드의 파라미터에 무효인 값이 설정되어 있는 경우 등.
E_OUTOFMEMORY
Direct3D 가 호출을 완료하기 위한 충분한 메모리를 할당할 수가 없었다.
S_OK
에러는 발생하고 있지 않다.


Direct3DX C/C++ 레퍼런스

여기에서는, Direct3DX 유틸리티 라이브러리가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는, 다음의 카테고리로 분류된다.

  • 인터페이스
  • 함수
  • 매크로
  • 구조체
  • C++ 고유의 기능
  • 반환값


인터페이스

여기에서는, Direct3DX 유틸리티 라이브러리가 제공하는 COM 인터페이스의 레퍼런스 정보를 기술한다. Direct3DX 유틸리티 라이브러리에서는 다음의 인터페이스가 사용된다.

  • ID3DXBaseMesh
  • ID3DXBuffer
  • ID3DXEffect
  • ID3DXFont
  • ID3DXMatrixStack
  • ID3DXMesh
  • ID3DXPMesh
  • ID3DXRenderToSurface
  • ID3DXSkinMesh
  • ID3DXSPMesh
  • ID3DXSprite
  • ID3DXTechnique


ID3DXBaseMesh

어플리케이션은,ID3DXBaseMesh 인터페이스의 메소드를 사용해, 메쉬 오브젝트나 프로그래시브 메쉬 오브젝트의 조작 및 조회를 실시한다.

ID3DXBaseMesh 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

버퍼 | GetIndexBuffer
 | GetVertexBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
카피 | CloneMesh
 | CloneMeshFVF
면 | GetNumFaces
정보 | GetDevice
 | GetOptions
렌더링 | DrawSubset
 | GetAttributeTable
버텍스 | GetDeclaration
 | GetFVF
 | GetNumVertices

ID3DXBaseMesh 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

메쉬란, 다각형의 면세트로 구성되는 오브젝트이다. 메쉬는, 버텍스세트 및 면세트를 정의한다 (면은, 메쉬의 버텍스와 법선에 의해 정의된다).

LPD3DXBASEMESH 형은,ID3DXBaseMesh 인터페이스에의 포인터로서 정의되고 있다.

typedef struct ID3DXBaseMesh *LPD3DXBASEMESH;

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMesh ,ID3DXPMesh


ID3DXBaseMesh::CloneMesh

선언자를 사용해 메쉬의 카피를 생성 한다.

HRESULT CloneMesh(
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXMESH* ppCloneMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다. 이러한 메쉬는, 공유하는 버텍스 버퍼에 인덱스 붙이고 하는 개별의 인덱스 버퍼를 갖춘다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pDeclaration
[in] 출력 메쉬에 포함되는 버텍스의 버텍스 포맷을 기술하는 선언자를 나타내는,DWORD 값의 배열에의 포인터. 이 파라미터는 FVF 에 직접 맵 해야 한다.
pD3DDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppCloneMesh
[out, retval] 카피된 메쉬를 나타내는 ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::GetDeclaration ,D3DXDeclaratorFromFVF


ID3DXBaseMesh::CloneMeshFVF

유연한 버텍스 포맷 (FVF) 코드를 사용해 메쉬의 카피를 생성 한다.

HRESULT CloneMeshFVF(
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXMESH* ppCloneMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다. 이러한 메쉬는, 공유하는 버텍스 버퍼에 인덱스 붙이고 하는 개별의 인덱스 버퍼를 갖춘다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
FVF
[in] 출력 메쉬에 포함되는 버텍스의 버텍스 포맷을 지정하는유연한 버텍스 포맷 플래그의 편성.
pD3DDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppCloneMesh
[out, retval] 카피된 메쉬를 나타내는 ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

주의

CloneMeshFVF 를 사용해, 메쉬를 1 개의 FVF 로부터 다른 FVF 로 변환할 수 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::GetFVF ,D3DXFVFFromDeclarator


ID3DXBaseMesh::DrawSubset

메쉬의 서브 세트를 드로잉(Drawing) 한다.

HRESULT DrawSubset(
  DWORD AttribId
);

파라미터

AttribId
[in] 드로잉(Drawing) 하는 메쉬의 서브 세트를 지정하는 DWORD. 이 값은, 메쉬내의 면을, 1 개(살) 이상의 속성 그룹에 속하고 있다고 하여 구별하기 위해서 사용된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

주의

속성 테이블은, 다른 텍스쳐, 렌더링 스테이트, 머트리얼등에 의해 드로잉(Drawing) 할 필요가 있는 메쉬의 영역을 식별하기 위해서 사용된다. 한층 더 어플리케이션은, 속성 테이블을 사용해, 프레임의 드로잉(Drawing)시에 소정의 속성 식별자 (AttribId)를 드로잉(Drawing) 하지 않는 것에 따라, 메쉬의 일부를 숨길 수가 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::GetAttributeTable


ID3DXBaseMesh::GetAttributeTable

메쉬의 속성 테이블, 또는 메쉬의 속성 테이블에 저장 되고 있는 엔트리의 수를 취득한다.

HRESULT GetAttributeTable(
  D3DXATTRIBUTERANGE* pAttribTable,
  DWORD* pAttribTableSize
);

파라미터

pAttribTable
[in, out] 메쉬의 속성 테이블에 저장 되고 있는 엔트리를 나타내는,D3DXATTRIBUTERANGE 구조체의 배열에의 포인터. NULL 를 지정해 pAttribTableSize 의 값을 취득한다.
pAttribTableSize
[in, out] pAttribTable 에 저장 되고 있는 엔트리수, 또는 메쉬의 속성 테이블에 저장 되고 있는 엔트리수로 묻는 값의 어느 쪽인지에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

주의

속성 테이블은 ID3DXMesh::Optimize 에 의해 생성 되어 D3DXMESHOPT_ATTRSORT 를 Flags 파라미터에 건네준다.

속성 테이블은, 다른 텍스쳐, 렌더링 스테이트, 머트리얼등에 의해 드로잉(Drawing) 할 필요가 있는 메쉬의 영역을 식별하기 위해서 사용된다. 한층 더 어플리케이션은, 속성 테이블을 사용해, 프레임의 드로잉(Drawing)시에 소정의 속성 식별자를 드로잉(Drawing) 하지 않는 것에 따라, 메쉬의 일부를 숨길 수가 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXBaseMesh::GetDeclaration

메쉬에 포함되는 버텍스를 기술하는 선언을 취득한다.

HRESULT GetDeclaration(
  DWORD Declaration[MAX_FVF_DECL_SIZE]
);

파라미터

Declaration
[in, out] 조회된 메쉬에 포함되는 버텍스의 버텍스 포맷을 기술하는 돌려주어진 배열. 이 선언자의 배열의 상한은 MAX_FVF_DECL_SIZE 로, 선언자를 15 DWORD 의 최대수에 제한한다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::GetFVF


ID3DXBaseMesh::GetDevice

메쉬에 관련지을 수 있고 있는 디바이스를 취득한다.

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice

파라미터

ppDevice
[out, retval] 메쉬에 관련지을 수 있고 있는 Microsoft® Direct3D® 디바이스 오브젝트를 나타내는,IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스의 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXBaseMesh::GetFVF

메쉬에 포함되는 버텍스의 유연한 버텍스 포맷을 취득한다.

DWORD GetFVF();

파라미터

없음.

반환값

조회된 메쉬에 포함되는 버텍스의 유연한 버텍스 포맷을 기술하는,유연한 버텍스 포맷 플래그의 편성을 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::GetDeclaration


ID3DXBaseMesh::GetIndexBuffer

인덱스 버퍼내의 데이터를 취득한다.

HRESULT GetIndexBuffer(
  LPDIRECT3DINDEXBUFFER8* ppIB
);

파라미터

ppIB
[out, retval] 메쉬에 관련지을 수 있고 있는 인덱스 버퍼 오브젝트를 나타내는,IDirect3DIndexBuffer8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXBaseMesh::GetNumFaces

메쉬에 포함되는 면의 수를 취득한다.

DWORD GetNumFaces();

파라미터

없음.

반환값

메쉬에 포함되는 면의 수를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXBaseMesh::GetNumVertices

메쉬에 포함되는 버텍스의 수를 취득한다.

DWORD GetNumVertices();

파라미터

없음.

반환값

메쉬에 포함되는 버텍스의 수를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXBaseMesh::GetOptions

이 메쉬의 생성시에 유효하게 되어 있는 메쉬 옵션을 취득한다.

DWORD GetOptions();

파라미터

없음.

반환값

이 메쉬의 생성시에 유효하게 되어 있는 옵션을 나타내는, 다음의 1 개 이상의 플래그의 편성을 돌려준다.

D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXBaseMesh::GetVertexBuffer

버텍스 버퍼내의 데이터를 취득한다.

HRESULT GetVertexBuffer(
  LPDIRECT3DVERTEXBUFFER8* ppVB
);

파라미터

ppVB
[out, retval] 메쉬에 관련지을 수 있고 있는 버텍스 버퍼 오브젝트를 나타내는,IDirect3DVertexBuffer8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXBaseMesh::LockIndexBuffer

인덱스 버퍼를 잠그어, 인덱스 버퍼 메모리에의 포인터를 취득한다.

HRESULT LockIndexBuffer(
  DWORD Flags,
  BYTE** ppData
);

파라미터

Flags
[in] 인덱스 버퍼 메모리를 어떻게 잠그는지를 기술하는, 1 개(살) 이상의 락킹 플래그의 편성.
D3DLOCK_DISCARD
어플리케이션은, 락 되고 있는 영역내의 모든 장소를, 기입 전용 처리로 덧쓰기한다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는 압축 해제 스텝을 생략 할 수 있다.
D3DLOCK_NOOVERWRITE
프레임의 시작 이후, 또는 이 플래그를 가지지 않는 최신의 락 이후, 드로잉(Drawing) 호출 중(안)에서 참조되는 인덱스 가운데, 락시에 수정되는 인덱스가 없는 것을 나타낸다. 이것에 의해, 어플리케이션이 인덱스 버퍼에 데이터를 추가할 뿐(만큼)의 경우에 최적화를 유효하게 할 수 있다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템 전체의 크리티컬 섹션을 확보해, 락의 기간중은 디스플레이 모드가 변화하지 않는 것을 보증 하면 말하는 것이다. 이 플래그를 지정 하면, 시스템 전체의 크리티컬 섹션은 락의 사이 보관 유지되지 않는다.

락 처리는 약간 부하가 높아지지만, 시스템은, 마우스 커서의 이동이라고 한 것 외의 동작을 실행할 수 있다. 이 플래그는, 그것을 실시하지 않으면 시스템의 응답에 악영향을 미치는 소프트웨어 렌더링에 대한 백 버퍼의 락과 같은, 장기간의 락에 도움이 된다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입하지 않는다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는, 언락시에 재압축 스텝을 생략 할 수 있다.
ppData
[out, retval] BYTE 값의 배열에의 포인터의 주소. 반환값의 인덱스 데이터가 입력된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

주의

인덱스 버퍼를 조작하는 경우는, 복수의 락 호출을 실시할 수가 있다. 다만, 락 호출의 수와 언락 호출의 수는 일치하고 있지 않으면 안 된다. 현재 설정되어 있는 인덱스 버퍼로 락 카운트가 남아 있는 경우, DrawPrimitive 의 호출은 실패한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::UnlockIndexBuffer


ID3DXBaseMesh::LockVertexBuffer

버텍스 버퍼를 잠그어, 버텍스 버퍼 메모리에의 포인터를 취득한다.

HRESULT LockVertexBuffer(
  DWORD Flags,
  BYTE** ppData
);

파라미터

Flags
[in] 버텍스 버퍼 메모리를 어떻게 잠그는지를 나타내는, 1 개(살) 이상의 락킹 플래그의 편성.
D3DLOCK_DISCARD
어플리케이션은, 락 되고 있는 영역내의 모든 장소를, 기입 전용 처리로 덧쓰기한다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는 압축 해제 스텝을 생략 할 수 있다.
D3DLOCK_NOOVERWRITE
프레임의 시작 이후, 또는 이 플래그를 가지지 않는 최신의 락 이후, 드로잉(Drawing) 호출 중(안)에서 참조되는 버텍스 가운데, 락시에 수정되는 버텍스가 없는 것을 나타낸다. 버텍스 버퍼에의 데이터의 추가만을 실시하는 경우는, 이 플래그에 의해 처리를 최적화할 수 있다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템 전체의 크리티컬 섹션을 확보해, 락의 기간중은 디스플레이 모드가 변화하지 않는 것을 보증 하면 말하는 것이다. 이 플래그를 지정 하면, 시스템 전체의 크리티컬 섹션은 락의 사이 보관 유지되지 않는다.

락 처리는 약간 부하가 높아지지만, 시스템은, 마우스 커서의 이동이라고 한 것 외의 동작을 실행할 수 있다. 이 플래그는, 그것을 실시하지 않으면 시스템의 응답에 악영향을 미치는 소프트웨어 렌더링에 대한 백 버퍼의 락과 같은, 장기간의 락에 도움이 된다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입하지 않는다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는, 언락시에 재압축 스텝을 생략 할 수 있다.
ppData
[out, retval] BYTE 값의 배열에의 포인터의 주소. 반환값의 버텍스 데이터가 입력된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

주의

버텍스 버퍼를 조작 하면나무는, 복수의 락 호출을 실행할 수 있다. 다만, 락 호출의 수와 락 해제 호출의 수를 일치시킬 필요가 있다. 현재 설정되어 있는 버텍스 버퍼로 락 카운트가 남아 있는 경우, DrawPrimitive 의 호출은 실패한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::UnlockVertexBuffer


ID3DXBaseMesh::UnlockIndexBuffer

인덱스 버퍼의 락을 해제한다.

HRESULT UnlockIndexBuffer();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::LockIndexBuffer


ID3DXBaseMesh::UnlockVertexBuffer

버텍스 버퍼의 락을 해제한다.

HRESULT UnlockVertexBuffer();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::LockVertexBuffer


ID3DXBuffer

ID3DXBuffer 인터페이스는 데이터 버퍼로서 사용되어 메쉬의 최적화 및 로드의 조작시에, 버텍스, 인접성, 및 머트리얼에 관한 정보를 저장 한다. 버퍼 오브젝트는, 임의의 길이의 데이터를 돌려주기 위해서(때문에) 사용된다.

한층 더 버퍼 오브젝트는, 버텍스 쉐이더와 픽셀 쉐이더를 조립하는 메소드에 포함되는 오브젝트 코드와 에러 메세지를 돌려주기 위해서(때문에) 사용된다.

ID3DXBuffer 인터페이스는,D3DXCreateBuffer 함수를 호출해 취득한다.

ID3DXBuffer 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetBufferPointer
 | GetBufferSize

ID3DXBuffer 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXBUFFER 형은,ID3DXBuffer 인터페이스에의 포인터로서 정의되고 있다.

typedef struct ID3DXBuffer *LPD3DXBUFFER;

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXBuffer::GetBufferPointer

버퍼내의 데이터에 대한 포인터를 취득한다.

LPVOID GetBufferPointer();

파라미터

없음.

반환값

버퍼내의 데이터에 대한 포인터를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXBuffer::GetBufferSize

버퍼내의 데이터의 합계 사이즈를 취득한다.

DWORD GetBufferSize();

파라미터

없음.

반환값

버퍼내의 데이터의 합계 사이즈를 돌려준다 (바이트 단위).

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXEffect

ID3DXEffect 인터페이스는, 이펙트의 설정과 조회, 및 테크닉의 선택에 사용한다. 이펙트 오브젝트에는, 같은 이펙트를 렌더링 하는 복수의 테크닉을 저장 할 수 있다.

  • ID3DXEffect 인터페이스는,D3DXCreateEffect 를 호출하는 것으로 취득된다.

ID3DXEffect 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

카피 | CloneEffect
이펙트 | SetDword
 | SetFloat
 | SetMatrix
 | SetPixelShader
 | SetTexture
 | SetVector
 | SetVertexShader
이펙트 정보 | GetDword
 | GetFloat
 | GetMatrix
 | GetParameterDesc
 | GetPixelShader
 | GetTexture
 | GetVector
 | GetVertexShader
정보 | GetDesc
 | GetDevice
테크닉 | GetTechnique
 | GetTechniqueDesc

ID3DXEffect 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXEFFECT 형은,ID3DXEffect 인터페이스에의 포인터로서 정의되고 있다.

typedef struct ID3DXEffect *LPD3DXEFFECT;

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateEffect ,D3DXCompileEffect ,D3DXCompileEffectFromFileA ,D3DXCompileEffectFromFileW


ID3DXEffect::CloneEffect

이펙트의 카피를 생성 한다.

STDMETHODIMP CloneEffect(
  LPDIRECT3DDEVICE8 pDevice,
  DWORD             Usage,
  LPD3DXEFFECT*     ppEffect
)

파라미터

pDevice
[in] 이펙트에 관련지을 수 있고 있는 디바이스를 나타내는IDirect3DDevice8 인터페이스에의 포인터.
Usage
[in] 이 이펙트의 사용 방법의 제어 정보. 다음의 플래그를 설정할 수 있다.
D3DUSAGE_SOFTWAREPROCESSING
이펙트가 소프트웨어 처리를 사용해 렌더링 되는 것을 나타낸다.
ppEffect
[out, retval] 카피된 이펙트를 저장 하는 ID3DXEffect 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXEffect::GetDesc

이펙트의 설명을 취득한다.

HRESULT GetDesc(
  D3DXEFFECT_DESC* pDesc
)

파라미터

pDesc
[in, retval] 돌려주어진 기술을 저장 하는 D3DXEFFECT_DESC 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC


ID3DXEffect::GetDevice

이펙트에 관련지을 수 있고 있는 디바이스를 취득한다.

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
)

파라미터

ppDevice
[out, retval] 이펙트에 관련지을 수 있고 있는 디바이스를 나타내는,IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스의 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 인터페이스의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXEffect::GetDword

이펙트에 관련지을 수 있고 있는 DWORD 값을 취득한다.

HRESULT GetDword(
  DWORD  Name,
  DWORD* pdw
)

파라미터

Name
[in] DWORD 값을 취득하는 파라미터의 이름. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pdw
[out, retval] 돌려주어진 DWORD 를 저장 하는 DWORD 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXEffect::SetDword


ID3DXEffect::GetFloat

이펙트에 관련지을 수 있고 있는 부동 소수점값을 취득한다.

HRESULT GetFloat(
  UINT   Name,
  FLOAT* pf
);

파라미터

Name
[in] 부동 소수점값을 취득하는 파라미터의 이름. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pf
[out, retval] 돌려주어진 부동 소수점값을 저장 하는 FLOAT 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::SetFloat


ID3DXEffect::GetMatrix

이펙트에 관련지을 수 있고 있는 행렬을 취득한다.

HRESULT GetMatrix(
  UINT       Name,
  D3DMATRIX* pMat
);

파라미터

Name
[in] 행렬을 취득하는 파라미터의 이름. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pMatrix
[out, retval] 돌려주어진 행렬을 저장 하는 D3DMATRIX 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::SetMatrix


ID3DXEffect::GetParameterDesc

특정의 이펙트 파라미터에 관한 정보를 취득한다.

HRESULT GetParameterDesc(
  UINT                Index,
  D3DXPARAMETER_DESC* pDesc
)

파라미터

Index
[in] 정보를 취득하는 파라미터의 인덱스.
pDesc
[out, retval] 파라미터에 관한 정보를 저장 하는 D3DXPARAMETER_DESC 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXEffect::GetPixelShader

이펙트에 관련지을 수 있고 있는 픽셀 쉐이더를 취득한다.

HRESULT GetPixelShader(
  DWORD  Name,
  DWORD* pHandle
)

파라미터

Name
[in] 픽셀 쉐이더를 취득하는 파라미터의 이름. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pHandle
[out, retval] 돌려주어진 픽셀 쉐이더를 저장 하는 DWORD 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXEffect::SetPixelShader


ID3DXEffect::GetTechnique

이펙트에 관련지을 수 있고 있는 테크닉을 취득한다.

HRESULT GetTechnique(
  UINT            Name,
  ID3DXTechnique* ppTechnique
);

파라미터

Name
[in] 취득하는 테크닉의 이름. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
ppTechnique
[out, retval] 돌려주어진 테크닉을 저장 하는 ID3DXTechnique 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXTECHNIQUE_DESC , ID3DXEffect::GetTechniqueDesc


ID3DXEffect::GetTechniqueDesc

이펙트에 관련지을 수 있고 있는 테크닉의 설명을 취득한다.

HRESULT GetTechniqueDesc(
  UINT                Index,
  D3DXTECHNIQUE_DESC* pDesc
)

파라미터

Index
[in] 취득하는 테크닉 기술의 이름.
pDesc
[out, retval] 돌려주어진 기술을 저장 하는 D3DXTECHNIQUE_DESC 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXTECHNIQUE_DESC , ID3DXEffect::GetTechnique


ID3DXEffect::GetTexture

이펙트에 관련지을 수 있고 있는 텍스쳐를 취득한다.

HRESULT GetTexture(
  UINT                   Name,
  IDirect3DBaseTexture8* pTex
);

파라미터

Name
[in] 텍스쳐를 취득하는 파라미터의 이름. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pTex
[out, retval] 돌려주어진 텍스쳐를 저장 하는 IDirect3DBaseTexture8 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

주 이 메소드를 호출하면,IDirect3DBaseTexture8 인터페이스의 내부 참조 카운트가 증가한다. 이 IDirect3DTexture8 인터페이스의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXEffect::SetTexture


ID3DXEffect::GetVector

이펙트에 관련지을 수 있고 있는 벡터를 취득한다.

HRESULT GetVector(
  UINT         Name,
  D3DXVECTOR4* pVec
);

파라미터

Name
[in] 벡터를 취득하는 파라미터의 이름. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pVec
[out, retval] 돌려주어진 벡터를 저장 하는 D3DXVECTOR4 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::GetVector


ID3DXEffect::GetVertexShader

이펙트에 관련지을 수 있고 있는 버텍스 쉐이더를 취득한다.

HRESULT GetVertexShader(
  DWORD  Name,
  DWORD* pHandle
)

파라미터

Name
[in] 버텍스 쉐이더를 취득하는 파라미터의 이름. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pHandle
[out, retval] 돌려주어진 버텍스 쉐이더를 저장 하는 DWORD 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::SetVertexShader


ID3DXEffect::SetDword

이펙트의 DWORD 값을 설정한다.

HRESULT SetDword(
  UINT  Name,
  DWORD dw
);

파라미터

Name
[in] 설정하는 이펙트 파라미터의 이름을 식별한다. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
dw
[in] Name 에 할당하는 DWORD 값을 지정한다.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::GetDword


ID3DXEffect::SetFloat

이펙트의 부동 소수점값을 설정한다.

HRESULT SetFloat(
  UINT  Name,
  FLOAT f
);

파라미터

Name
[in] 설정하는 이펙트 파라미터의 이름을 식별한다. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
f
[in] Name 에 할당하는 부동 소수점값을 지정한다.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::GetFloat


ID3DXEffect::SetMatrix

이펙트의 행렬을 설정한다.

HRESULT SetMatrix(
  UINT Name,
  D3DMATRIX* pMat
);

파라미터

Name
[in] 설정하는 이펙트 파라미터의 이름을 식별한다. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pMat
[in] Name 에 할당하는 D3DMATRIX 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::GetMatrix


ID3DXEffect::SetPixelShader

이펙트의 픽셀 쉐이더를 설정한다.

HRESULT SetPixelShader(
  DWORD Name,
  DWORD Handle
)

파라미터

Name
[in] 설정하는 이펙트 파라미터의 이름을 식별한다. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
Handle
[in] Name 에 할당하는 픽셀 쉐이더를 지정한다.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::GetPixelShader


ID3DXEffect::SetTexture

이펙트의 텍스쳐를 설정한다.

HRESULT SetTexture(
  UINT                  Name,
  IDirect3DBaseTexture8 pTexture
);

파라미터

Name
[in] 설정하는 이펙트 파라미터의 이름을 식별한다. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pTexture
[in] Name 에 할당하는 텍스쳐를 지정하는,IDirect3DBaseTexture8 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

주 이 메소드를 호출하면,IDirect3DBaseTexture8 인터페이스의 내부 참조 카운트가 증가한다. 이 IDirect3BaseTexture8 인터페이스의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::GetTexture


ID3DXEffect::SetVector

이펙트의 벡터를 설정한다.

HRESULT SetVector(
  UINT         Name,
  D3DXVECTOR4* pVec
);

파라미터

Name
[in] 설정하는 이펙트 파라미터의 이름을 식별한다. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
pVector
[in] Name 에 할당하는 벡터를 지정하는 D3DXVECTOR4 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::SetVector


ID3DXEffect::SetVertexShader

이펙트의 버텍스 쉐이더를 설정한다.

HRESULT SetVertexShader(
  DWORD Name,
  DWORD Handle
)

파라미터

Name
[in] 설정하는 이펙트 파라미터의 이름을 식별한다. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.
Handle
[in] Name 에 할당하는 버텍스 쉐이더에의 핸들.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

FOURCC 는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXEFFECT_DESC , ID3DXEffect::SetVertexShader


ID3DXFont

ID3DXFont 인터페이스는, 특정 디바이스 위에의 특정의 폰트를 렌더링 하기 위해서 필요한 텍스쳐와 리소스를 캡슐화하기 위해서 사용한다.

ID3DXFont 인터페이스는,D3DXCreateFont 또는 D3DXCreateFontIndirect 함수를 호출해 취득한다.

ID3DXFont 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

드로잉(Drawing) | Begin
 | DrawTextA
 | DrawTextW
 | End
정보 | GetDevice
 | GetLogFont

ID3DXFont 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXFONT 형은,ID3DXFont 인터페이스에의 포인터로서 정의되고 있다.

typedef interface ID3DXFont *LPD3DXFONT;

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXFont::Begin

텍스트를 드로잉(Drawing) 할 수 있도록(듯이) 디바이스를 준비한다.

HRESULT Begin();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

이 메소드는 옵션이다. DrawText 메소드가 Begin 와 ID3DXFont::End 의 대의 외측에서 불려 갔을 경우, Microsoft® Direct3D® 에 의해 Begin 와 End 가 불려 간다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXFont::End


ID3DXFont::DrawTextA

Microsoft® Direct3D® 디바이스상에, 정형한 ANSI 텍스트를 드로잉(Drawing) 한다.

INT DrawTextA(
  LPCSTR pString,
  INT Count,
  LPRECT pRect,
  DWORD Format,
  D3DCOLOR Color
);

파라미터

pString
[in] 드로잉(Drawing) 하는 ANSI 캐릭터 라인에의 포인터. Count 파라미터가 -1 의 경우, 캐릭터 라인은 NULL 로 끝날 필요가 있다.

Format 에 DT_MODIFYSTRING 가 포함되어 있는 경우는, 이 함수로 최대 4 문자까지 문자를 추가할 수 있다. 캐릭터 라인을 보관 유지하는 버퍼는, 이러한 여분의 문자를 적응할 수 있도록(듯이) 충분한 용량이 없으면 안 된다.

Count
[in] 캐릭터 라인의 문자수를 지정한다. Count 가 -1 의 경우, 파라미터의 pString 는 말미가 Null 의 캐릭터 라인에의 포인터라고 보여져DrawTextA 에 의해 캐릭터 라인 카운트가 자동적으로 계산된다.
pRect
[in] 텍스트가 포맷 되는 논리 좌표에 직사각형을 보관 유지하는 RECT 구조체에의 포인터.
Format
[in] 텍스트를 포맷 하는 메소드를 지정한다. 다음의 값을 임의에 조합할 수가 있다.
DT_BOTTOM
직사각형의 저부로 텍스트를 both and justification로 한다. 이 값은 DT_SINGLELINE 와 조합해 사용해야 한다.
DT_CALCRECT
직사각형의 폭과 높이를 산출한다. 텍스트가 복수행 있는 경우,DrawTextA 는 pRect 파라미터가 참조하는 사각형의 폭을 사용해, 텍스트의 마지막 행이 포함되도록(듯이) 사각형의 저변을 연장한다. 텍스트가 1 행만의 경우,DrawTextA 하행의 마지막 문자가 들어가도록(듯이) 사각형의 우측의 옆의 위치를 수정한다. 어느 쪽의 경우도,DrawTextA 는 정형된 텍스트의 높이를 돌려주지만, 텍스트는 드로잉(Drawing) 하지 않는다.
DT_CENTER
직사각형내에서 텍스트를 수평 방향으로 centering로 한다.
DT_EDITCONTROL
멀티 라인 에디트 컨트롤의 텍스트 표시 특성을 복제한다. 특히, 평균의 문자폭은 에디트 컨트롤과 같은 방법으로 계산되어 부분적으로 보이는 마지막 행은 표시되지 않는다.
DT_END_ELLIPSIS 또는 DT_PATH_ELLIPSIS
생략 기호를 추가하지 않고 캐릭터 라인을 잘라 버려 지정한 직사각형에 들어가도록(듯이) 한다. DT_MODIFYSTRING 플래그가 지정되고 있는 경우를 제외해, 캐릭터 라인은 수정되지 않는다.

DT_END_ELLIPSIS 는 캐릭터 라인의 최후로 문자를 잘라 버리기 위해서(때문에) 지정한다. DT_PATH_ELLIPSIS 는 캐릭터 라인의 중간으로 문자를 잘라 버리기 위해서(때문에) 지정한다. 캐릭터 라인에 backslash (\)가 포함되어 있는 경우, DT_PATH_ELLIPSIS 는 마지막 backslash보다 뒤에 있는 텍스트를 가능한 한 많이 보관 유지한다.

DT_EXPANDTABS
탭 문자를 확장한다. 탭 마다의 디폴트의 문자수는 8 자이다. DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS, 및 DT_END_ELLIPSIS 는 DT_EXPANDTABS 와 동시에 사용할 수 없다.
DT_EXTERNALLEADING
행의 높이에 폰트의 외부 margin를 포함한다. 보통, 외부 margin는, 텍스트의 행의 높이에는 포함되지 않는다.
DT_HIDEPREFIX
Windows 2000 에서는 다음과 같이 된다. 텍스트에 포함되는 ampersand(&) (&) 프리픽스 문자를 무시한다. ampersand(&)에 계속되는 문자에 밑줄은 붙지 않지만, 다른 무릎 관절 모닛크 프리픽스 문자는 그대로 처리된다.

례 :

입력 캐릭터 라인 :"A&bc&&d"

표준 :"Abc&d"

HIDEPREFIX:"Abc&d"

DT_NOPREFIX 과 DT_PREFIXONLY 와 비교하는 것.

DT_INTERNAL
시스템 폰트를 사용해 테키스트메트리크스를 계산한다.
DT_LEFT
텍스트를 왼쪽 가지런히 해로 한다.
DT_MODIFYSTRING
캐릭터 라인을 수정해 표시된 텍스트에 맞춘다. DT_END_ELLIPSIS 또는 DT_PATH_ELLIPSIS 가 지정되고 있는 경우만, 이 플래그는 유효가 된다.
DT_NOCLIP
클리핑 하지 않고 드로잉(Drawing) 한다. DrawTextA 는, DT_NOCLIP 를 사용 하면 약간 고속으로 있다.
DT_NOFULLWIDTHCHARBREAK
Windows 98, Windows 2000 의 경우,DBCS (double-wide character string)로 개행되지 않게 한다. 이것에 의해 개행 룰은 SBCS 의 설정과 같게 된다. 예를 들어, 한국어판 Windows 로 아이콘 라벨을 읽기 쉽게 하기 위해서 사용된다. DT_WORDBREAK 가 지정되고 있는 경우만 유효하다.
DT_NOPREFIX
프리픽스 문자의 처리를 오프로 한다. 보통,DrawTextA 는 무릎 관절 모닛크 프리픽스 문자의 & 를, 그 후에 계속되는 문자에 밑줄을 붙이는 명령으로서 해석해, 무릎 관절 모닛크 프리픽스 문자가 && 와 2 개 계속되었을 경우는, & 를 1 개 출력하는 명령으로서 해석한다. DT_NOPREFIX 를 지정하는 것으로써, 이 처리는 오프가 된다. 「DT_HIDEPREFIX」 및 「DT_PREFIXONLY」를 참조할것.
DT_PREFIXONLY
Windows 2000 에서는 다음과 같이 된다. ampersand(&) (&) 프리픽스 문자에 계속되는 문자의 위치에서, 밑줄만을 드로잉(Drawing) 한다. 캐릭터 라인에 포함되는 문자는 드로잉(Drawing) 하지 않는다.

례 :

입력 캐릭터 라인 :"A&bc&&d"

표준 :"Abc&d"

PREFIXONLY:

DT_NOPREFIX 및 DT_HIDEPREFIX 와 비교하는 것.

DT_RIGHT
텍스트를 우단 가지런히 해로 한다.
DT_RTLREADING
헤브라이어 또는 아라비아어의 폰트가 선택되고 있는 경우, 읽기의 순서가 쌍방향의 텍스트에 대해 오른쪽에서 왼쪽의 순서에 읽도록(듯이) 텍스트를 표시한다. 디폴트의 읽기의 순서는, 모든 텍스트로 왼쪽에서 오른쪽이 되고 있다.
DT_SINGLELINE
1 행에만 텍스트를 표시한다. 개행과 행송로 새로운 행으로 옮기지 않는다.
DT_TABSTOP
tab stop를 설정한다. Format 파라미터의 비트 15-8 (저위어의 고차원 바이트)에 의해 각 탭의 문자수를 지정한다. 탭 마다의 디폴트의 문자수는 8 자이다. DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, 및 DT_NOPREFIX 는 DT_TABSTOP 와 동시에 사용할 수 없다.
DT_TOP
선두행의 텍스트를 both and justification로 한다 (1 행만).
DT_VCENTER
상하 방향으로 텍스트를 centering로 한다 (1 행만).
DT_WORDBREAK
말을 분할한다. 말이 pRect 파라미터로 지정한 직사각형의 구석을 넘는 경우, 말과 말의 사이에 자동적으로 개행된다. 개행/행 송의 순서도 개행이 된다.
DT_WORD_ELLIPSIS
직사각형에 들어가지 않는 텍스트를 잘라 버려 생략 기호를 추가한다.
Color
[in] 텍스트의 색을 지정하는 D3DCOLOR 형.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA

주의

DrawText 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,DrawTextA 또는 ID3DXFont::DrawTextW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,DrawText 의 정의 방법을 나타내고 있다.

#ifndef DrawText
#ifdef UNICODE
#define DrawText DrawTextW
#else
#define DrawText DrawTextA
#endif
#endif

DrawTextA 메소드는, 디바이스 콘텍스트로 선택된 폰트, 텍스트 칼라, 백그라운드 칼라를 사용해 텍스트를 드로잉(Drawing) 한다. DT_NOCLIP 포맷이 사용되는 경우를 제외해,DrawTextA 는 지정된 사각형의 외측에 텍스트가 초과하지 않게 텍스트를 클립 한다. DT_SINGLELINE 포맷이 지정되고 있는 경우를 제외해, 정형 처리에서는 복수행이 대상이다고 보여진다.

선택한 폰트가 너무 커 사각형에 들어가지 않는 경우,DrawTextA 메소드는 작은 폰트로 옮겨놓는 처리를 실시하지 않는다.

DrawTextA 메소드는, escapement 와 orientation 의 양쪽 모두가 제로의 폰트만 지원 한다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXFont::DrawTextW


ID3DXFont::DrawTextW

Microsoft® Direct3D® 디바이스상에, 정형한 Unicode™ 텍스트를 드로잉(Drawing) 한다.

INT DrawTextW(
  LPCWSTR pString,
  INT Count,
  LPRECT pRect,
  DWORD Format,
  D3DCOLOR Color
);

파라미터

pString
[in] 드로잉(Drawing) 하는 Unicode 캐릭터 라인에의 포인터. Count 파라미터가 -1 의 경우, 캐릭터 라인은 NULL 로 끝날 필요가 있다.

Format 에 DT_MODIFYSTRING 가 포함되어 있는 경우는, 이 함수로 최대 4 문자까지 문자를 추가할 수 있다. 캐릭터 라인을 보관 유지하는 버퍼는, 이러한 여분의 문자를 적응할 수 있도록(듯이) 충분한 용량이 없으면 안 된다.

Count
[in] 캐릭터 라인의 문자수를 지정한다. Count 가 -1 의 경우, 파라미터의 pString 는 말미가 Null 의 캐릭터 라인에의 포인터라고 보여져DrawTextW 에 의해 캐릭터 라인 카운트가 자동적으로 계산된다.
pRect
[in] 텍스트가 포맷 되는 논리 좌표에 직사각형을 보관 유지하는 RECT 구조체에의 포인터.
Format
[in] 텍스트를 포맷 하는 메소드를 지정한다. 다음의 값을 임의에 조합할 수가 있다.
DT_BOTTOM
직사각형의 저부로 텍스트를 both and justification로 한다. 이 값은 DT_SINGLELINE 와 조합해 사용해야 한다.
DT_CALCRECT
직사각형의 폭과 높이를 산출한다. 텍스트가 복수행 있는 경우,DrawTextW 는 pRect 파라미터가 참조하는 사각형의 폭을 사용해, 텍스트의 마지막 행이 포함되도록(듯이) 사각형의 저변을 연장한다. 텍스트가 1 행만의 경우,DrawTextW 하행의 마지막 문자가 들어가도록(듯이) 사각형의 우측의 옆의 위치를 수정한다. 어느 쪽의 경우도,DrawTextW 는 정형된 텍스트의 높이를 돌려주지만, 텍스트는 드로잉(Drawing) 하지 않는다.
DT_CENTER
직사각형내에서 텍스트를 수평 방향으로 centering로 한다.
DT_EDITCONTROL
멀티 라인 에디트 컨트롤의 텍스트 표시 특성을 복제한다. 특히, 평균의 문자폭은 에디트 컨트롤과 같은 방법으로 계산되어 부분적으로 보이는 마지막 행은 표시되지 않는다.
DT_END_ELLIPSIS 또는 DT_PATH_ELLIPSIS
생략 기호를 추가하지 않고 캐릭터 라인을 잘라 버려 지정한 직사각형에 들어가도록(듯이) 한다. DT_MODIFYSTRING 플래그가 지정되고 있는 경우를 제외해, 캐릭터 라인은 수정되지 않는다.

DT_END_ELLIPSIS 는 캐릭터 라인의 최후로 문자를 잘라 버리기 위해서(때문에) 지정한다. DT_PATH_ELLIPSIS 는 캐릭터 라인의 중간으로 문자를 잘라 버리기 위해서(때문에) 지정한다. 캐릭터 라인에 backslash (\)가 포함되어 있는 경우, DT_PATH_ELLIPSIS 는 마지막 backslash보다 뒤에 있는 텍스트를 가능한 한 많이 보관 유지한다.

DT_EXPANDTABS
탭 문자를 확장한다. 탭 마다의 디폴트의 문자수는 8 자이다. DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS, 및 DT_END_ELLIPSIS 는 DT_EXPANDTABS 와 동시에 사용할 수 없다.
DT_EXTERNALLEADING
행의 높이에 폰트의 외부 margin를 포함한다. 보통, 외부 margin는, 텍스트의 행의 높이에는 포함되지 않는다.
DT_HIDEPREFIX
Windows 2000 에서는 다음과 같이 된다. 텍스트에 포함되는 ampersand(&) (&) 프리픽스 문자를 무시한다. ampersand(&)에 계속되는 문자에 밑줄은 붙지 않지만, 다른 무릎 관절 모닛크 프리픽스 문자는 그대로 처리된다.

례 :

입력 캐릭터 라인 :"A&bc&&d"

표준 :"Abc&d"

HIDEPREFIX:"Abc&d"

DT_NOPREFIX 및 DT_PREFIXONLY 와 비교하는 것.

DT_INTERNAL
시스템 폰트를 사용해 테키스트메트리크스를 계산한다.
DT_LEFT
텍스트를 왼쪽 가지런히 해로 한다.
DT_MODIFYSTRING
캐릭터 라인을 수정해 표시된 텍스트에 맞춘다. DT_END_ELLIPSIS 또는 DT_PATH_ELLIPSIS 가 지정되고 있는 경우만, 이 플래그는 유효가 된다.
DT_NOCLIP
클리핑 하지 않고 드로잉(Drawing) 한다. DrawTextW 는, DT_NOCLIP 를 사용 하면 약간 고속으로 있다.
DT_NOFULLWIDTHCHARBREAK
Windows 98, Windows 2000 의 경우,DBCS (double-wide character string)로 개행되지 않게 한다. 이것에 의해 개행 룰은 SBCS 의 설정과 같게 된다. 예를 들어, 한국어판 Windows 로 아이콘 라벨을 읽기 쉽게 하기 위해서 사용된다. DT_WORDBREAK 가 지정되고 있는 경우만 유효하다.
DT_NOPREFIX
프리픽스 문자의 처리를 오프로 한다. 보통,DrawTextW 는 무릎 관절 모닛크 프리픽스 문자의 & 를, 그 후에 계속되는 문자에 밑줄을 붙이는 명령으로서 해석해, 무릎 관절 모닛크 프리픽스 문자가 && 와 2 개 계속되었을 경우는, & 를 1 개 출력하는 명령으로서 해석한다. DT_NOPREFIX 를 지정하는 것으로써, 이 처리는 오프가 된다. 「DT_HIDEPREFIX」 및 「DT_PREFIXONLY」를 참조할것.
DT_PREFIXONLY
Windows 2000 에서는 다음과 같이 된다. ampersand(&) (&) 프리픽스 문자에 계속되는 문자의 위치에서, 밑줄만을 드로잉(Drawing) 한다. 캐릭터 라인에 포함되는 문자는 드로잉(Drawing) 하지 않는다.

례 :

입력 캐릭터 라인 :"A&bc&&d"

표준 :"Abc&d"

PREFIXONLY:

DT_NOPREFIX 및 DT_HIDEPREFIX 와 비교하는 것.

DT_RIGHT
텍스트를 우단 가지런히 해로 한다.
DT_RTLREADING
헤브라이어 또는 아라비아어의 폰트가 선택되고 있는 경우, 읽기의 순서가 쌍방향의 텍스트에 대해 오른쪽에서 왼쪽의 순서에 읽도록(듯이) 텍스트를 표시한다. 디폴트의 읽기의 순서는, 모든 텍스트로 왼쪽에서 오른쪽이 되고 있다.
DT_SINGLELINE
1 행에만 텍스트를 표시한다. 개행과 행송로 새로운 행으로 옮기지 않는다.
DT_TABSTOP
tab stop를 설정한다. Format 파라미터의 비트 15-8 (저위어의 고차원 바이트)에 의해 각 탭의 문자수를 지정한다. 탭 마다의 디폴트의 문자수는 8 자이다. DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, 및 DT_NOPREFIX 는 DT_TABSTOP 와 동시에 사용할 수 없다.
DT_TOP
선두행의 텍스트를 both and justification로 한다 (1 행만).
DT_VCENTER
상하 방향으로 텍스트를 centering로 한다 (1 행만).
DT_WORDBREAK
말을 분할한다. 말이 pRect 파라미터로 지정한 직사각형의 구석을 넘는 경우, 말과 말의 사이에 자동적으로 개행된다. 개행/행 송의 순서도 개행이 된다.
DT_WORD_ELLIPSIS
직사각형에 들어가지 않는 텍스트를 잘라 버려 생략 기호를 추가한다.
Color
[in] 텍스트의 색을 지정하는 D3DCOLOR 형.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA

주의

DrawText 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,DrawTextW 또는 ID3DXFont::DrawTextA 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,DrawText 의 정의 방법을 나타내고 있다.

#ifndef DrawText
#ifdef UNICODE
#define DrawText DrawTextW
#else
#define DrawText DrawTextA
#endif
#endif

DrawTextW 메소드는, 디바이스 콘텍스트로 선택된 폰트, 텍스트 칼라, 백그라운드 칼라를 사용해 텍스트를 드로잉(Drawing) 한다. DT_NOCLIP 포맷이 사용되는 경우를 제외해,DrawTextW 는 지정된 사각형의 외측에 텍스트가 초과하지 않게 텍스트를 클립 한다. DT_SINGLELINE 포맷이 지정되고 있는 경우를 제외해, 정형 처리에서는 복수행이 대상이다고 보여진다.

선택한 폰트가 너무 커 사각형에 들어가지 않는 경우,DrawTextW 메소드는 작은 폰트로 옮겨놓는 처리를 실시하지 않는다.

DrawTextW 메소드는, escapement 와 orientation 의 양쪽 모두가 제로의 폰트만 지원 한다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXFont::DrawTextA


ID3DXFont::End

ID3DXFont::Begin 가 불려 간 시점의 디바이스 상태를 복원한다.

HRESULT End();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXFont::Begin


ID3DXFont::GetDevice

폰트 오브젝트에 관련지을 수 있고 있는 Microsoft® Direct3D® 디바이스를 취득한다.

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice
);

파라미터

ppDevice
[out, retval] 폰트 오브젝트에 관련지을 수 있고 있는 Direct3D 디바이스 오브젝트를 나타내는,IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

파라미터가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스의 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 인터페이스의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXFont::GetLogFont

폰트의 속성을 취득한다.

HRESULT GetLogFont(
  LOGFONT* pLogFont
);

파라미터

pLogFont
[in, out] 폰트의 속성을 기술하는, 돌려주어진 LOGFONT 구조체에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

파라미터가 무효인 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

LOGFONT 구조체의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXMatrixStack

어플리케이션은, 행렬 스택을 사용할때,ID3DXMatrixStack 인터페이스의 메소드를 사용한다.

ID3DXMatrixStack 인터페이스는,D3DXCreateMatrixStack 함수를 호출해 취득한다.

ID3DXMatrixStack 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

행렬 조작 | MultMatrix
 | MultMatrixLocal
그 외 | GetTop
 | LoadIdentity
 | LoadMatrix
 | Pop
 | Push
회전 | RotateAxis
 | RotateAxisLocal
 | RotateYawPitchRoll
 | RotateYawPitchRollLocal
스케일링 | Scale
 | ScaleLocal
평행이동 | Translate
 | TranslateLocal

ID3DXMatrixStack 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXMatrixStack::GetTop

스택의 맨 위에 있는 현재의 행렬을 취득한다.

D3DXMATRIX* GetTop();

파라미터

없음.

반환값

현재의 행렬을 나타내는 D3DXMATRIX 구조체에의 포인터를 돌려준다.

주의

이 메소드에 의해 돌려주어지는 D3DXMATRIX 포인터는, 그 이후의 스택 조작에서도 유효하다라고는 보증되어 있지 않다.

이 메소드는, 스택의 맨 위로부터 현재의 행렬을 삭제하지 않고, 다만 돌려주는 것만으로 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::Pop ,ID3DXMatrixStack::Push


ID3DXMatrixStack::LoadIdentity

현재의 행렬에 단위행렬을 로드한다.

HRESULT LoadIdentity();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

단위행렬은,[1,1][2,2][3,3][4,4] 계수에 1.0 이 설정되어 있는 것을 제외해, 모든 계수가 0.0 의 행렬이다. 단위행렬은, 버텍스에 적용되어도 그것들이 변경되지 않는다고 하는 점으로써 특별하다. 단위행렬은, 버텍스값을 변경해 회전, 평행이동, 및 4 × 4 행렬로 표현할 수 있는 그 외의 변환을 실시하는 행렬의 기점으로서 사용된다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::LoadMatrix


ID3DXMatrixStack::LoadMatrix

지정된 행렬을 현재의 행렬에 로드한다.

HRESULT LoadMatrix(
  CONST D3DXMATRIX* pMat
);

파라미터

pMat
[in] 현재의 행렬에 로드 되는 D3DXMATRIX 구조체에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 스택에 항목을 추가하는 것이 아니라, 현재의 행렬이 지정된 행렬에 옮겨놓는다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::LoadIdentity


ID3DXMatrixStack::MultMatrix

현재의 행렬과 지정된 행렬과의 적을 산출한다.

HRESULT MultMatrix(
  CONST D3DXMATRIX* pMat
);

파라미터

pMat
[in] 현재의 행렬에 적산하는 D3DXMATRIX 구조체에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 현재의 행렬로 지정된 행렬을 적산한다 (변환은 현재의 월드 원점을 중심으로서 행해진다).

    m_stack[m_currentPos] = m_stack[m_currentPos] * *pMat;

이 메소드는, 스택에 항목을 추가하는 것이 아니라, 현재의 행렬을, 현재의 행렬과 지정된 행렬의 적산에 옮겨놓는다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::MultMatrixLocal


ID3DXMatrixStack::MultMatrixLocal

지정된 행렬과 현재의 행렬과의 적을 산출한다.

HRESULT MultMatrixLocal(
  CONST D3DXMATRIX* pMat
);

파라미터

pMat
[in] 현재의 행렬에 적산하는 D3DXMATRIX 구조체에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 지정된 행렬에 현재의 행렬을 적산한다 (변환은 오브젝트의 로컬 원점을 중심으로서 행해진다).

    m_stack[m_currentPos] = *pMat * m_stack[m_currentPos];

이 메소드는, 스택에 항목을 추가하는 것이 아니라, 현재의 행렬을, 지정된 행렬과 현재의 행렬의 적산에 옮겨놓는다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::MultMatrix


ID3DXMatrixStack::Pop

스택의 맨 위로부터 현재의 행렬을 삭제한다.

HRESULT Pop();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

주의

이 메소드는, 스택의 맨 위로부터 현재의 행렬을 삭제해, 행렬을 스택의 맨 위에 진행해, 스택의 항목 카운트를 1 만 줄인다. 스택의 현재의 항목 카운트가 0 의 경우, 이 메소드는 아무것도 처리를 실시하지 않고 돌아온다. 스택의 현재의 항목 카운트가 1 의 경우, 이 메소드는 스택을 비운다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::GetTop ,ID3DXMatrixStack::Push


ID3DXMatrixStack::Push

행렬을 스택에 추가한다.

HRESULT Push();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 현재의 행렬을 복사해, 스택의 항목 카운트를 1 만 늘린다. 항목이 좀 더 추가되면(자), 스택은 동적으로 확대된다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::GetTop ,ID3DXMatrixStack::Pop


ID3DXMatrixStack::RotateAxis

현재의 행렬과 산출된 회전 행렬과의 적을 산출한다.

HRESULT RotateAxis(
  CONST D3DXVECTOR3* pV,
  FLOAT Angle
);

파라미터

pV
[in] 축의 각도를 지정하는 D3DXVECTOR3 구조체에의 포인터.
Angle
[in] 회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 현재의 행렬에 산출된 회전 행렬을 적산한다. 이것은, 지정한 축으로 대해 반시계회전으로 지정한 각도만 회전시킨다 (회전은, 현재의 월드 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixRotationAxis( &tmp, pV, angle );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::RotateAxisLocal ,ID3DXMatrixStack::RotateYawPitchRoll ,ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateAxisLocal

산출된 회전 행렬과 현재의 행렬과의 적을 산출한다.

HRESULT RotateAxisLocal(
  CONST D3DXVECTOR3* pV,
  FLOAT Angle
);

파라미터

pV
[in] 축의 각도를 지정하는 D3DXVECTOR3 구조체에의 포인터.
Angle
[in] 회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 산출된 회전 행렬에 현재의 행렬을 적산한다. 이것은, 지정한 축으로 대해 반시계회전으로 지정한 각도만 회전시킨다 (회전은, 오브젝트의 로컬 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixRotationAxis( &tmp, pV, angle );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::RotateAxis ,ID3DXMatrixStack::RotateYawPitchRoll ,ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateYawPitchRoll

현재의 행렬과 산출된 회전 행렬 (지정된 요, 피치, 및 롤에 의해 구성된다)의 적을 산출한다.

HRESULT RotateYawPitchRoll(
  FLOAT Yaw,
  FLOAT Pitch,
  FLOAT Roll
);

파라미터

Yaw
[in] y 축의 요 (라디안 단위).
Pitch
[in] x 축의 피치 (라디안 단위).
Roll
[in] z 축의 롤 (라디안 단위).

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

주의

이 메소드는, 현재의 행렬에 산출된 회전 행렬을 적산한다. 모든 각도는 반시계회전이며, 회전은 현재의 월드 원점을 중심으로서 행해진다.

    D3DXMATRIX tmp;

    D3DXMatrixRotationYawPitchRoll( &tmp, yaw, pitch, roll );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::RotateAxis ,ID3DXMatrixStack::RotateAxisLocal ,ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateYawPitchRollLocal

산출된 회전 행렬 (지정된 요, 피치, 및 롤에 의해 구성된다)과 현재의 행렬과의 적을 산출한다.

HRESULT RotateYawPitchRollLocal(
  FLOAT Yaw,
  FLOAT Pitch,
  FLOAT Roll
);

파라미터

Yaw
[in] y 축의 요 (라디안 단위).
Pitch
[in] x 축의 피치 (라디안 단위).
Roll
[in] z 축의 롤 (라디안 단위).

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

주의

이 메소드는, 산출된 회전 행렬에 현재의 행렬을 적산한다. 모든 각도는 반시계회전이며, 회전은 오브젝트의 로컬 원점을 중심으로서 행해진다.

    D3DXMATRIX tmp;

    D3DXMatrixRotationYawPitchRoll( &tmp, yaw, pitch, roll );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::RotateAxis ,ID3DXMatrixStack::RotateAxisLocal ,ID3DXMatrixStack::RotateYawPitchRoll


ID3DXMatrixStack::Scale

현재의 행렬과 산출된 스케일 행렬 (지정된 포인트 (x, y, z)로부터 구성된다)의 적을 산출한다.

HRESULT Scale(
  FLOAT x,
  FLOAT y,
  FLOAT z
);

파라미터

x
[in] x 방향의 스케일링 컴퍼넌트.
y
[in] y 방향의 스케일링 컴퍼넌트.
z
[in] z 방향의 스케일링 컴퍼넌트.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

주의

이 메소드는, 현재의 행렬에 산출된 스케일 행렬을 적산한다 (변환은 현재의 월드 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixScaling( &tmp, x, y, z );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::ScaleLocal


ID3DXMatrixStack::ScaleLocal

산출된 스케일 행렬 (지정된 포인트 (x, y, z)로부터 구성된다)와 현재의 행렬의 적을 산출한다.

HRESULT Scale(
  FLOAT x,
  FLOAT y,
  FLOAT z
);

파라미터

x
[in] x 방향의 스케일링 컴퍼넌트.
y
[in] y 방향의 스케일링 컴퍼넌트.
z
[in] z 방향의 스케일링 컴퍼넌트.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

주의

이 메소드는, 산출된 스케일 행렬에 현재의 행렬을 적산한다 (변환은 오브젝트의 로컬 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixScaling( &tmp, x, y, z );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::Scale


ID3DXMatrixStack::Translate

현재의 행렬과 산출된 평행이동 행렬 (지정된 계수 (x, y, z)에 의해 결정된다)의 적을 산출한다.

HRESULT Translate(
  FLOAT x,
  FLOAT y,
  FLOAT z
);

파라미터

x
[in] x 방향의 평행이동 계수.
y
[in] y 방향의 평행이동 계수.
z
[in] z 방향의 평행이동 계수.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

주의

이 메소드는, 현재의 행렬에 산출된 평행이동 행렬을 적산한다 (변환은, 현재의 월드 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixTranslation( &tmp, x, y, z );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::TranslateLocal


ID3DXMatrixStack::TranslateLocal

산출된 평행이동 행렬 (지정된 계수 (x, y, z)에 의해 결정된다)와 현재의 행렬의 적을 산출한다.

HRESULT TranslateLocal(
  FLOAT x,
  FLOAT y,
  FLOAT z
);

파라미터

x
[in] x 방향의 평행이동 계수.
y
[in] y 방향의 평행이동 계수.
z
[in] z 방향의 평행이동 계수.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

주의

이 메소드는, 산출된 평행이동 행렬에 현재의 행렬을 적산한다 (변환은, 오브젝트의 로컬 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixTranslation( &tmp, x, y, z );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMatrixStack::Translate


ID3DXMesh

어플리케이션은,ID3DXMesh 인터페이스의 메소드를 사용해 메쉬 오브젝트를 조작한다.

ID3DXMesh 인터페이스는,D3DXCreateMesh 함수 또는 D3DXCreateMeshFVF 함수의 어느 쪽인지를 호출해 취득한다.

ID3DXMesh 인터페이스는, 다음에 나타내는 ID3DXBaseMesh 메소드를 계승한다. 메소드는 이하의 그룹에 정리할 수가 있다.

버퍼 | GetIndexBuffer
 | GetVertexBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
카피 | CloneMesh
 | CloneMeshFVF
면 | GetNumFaces
정보 | GetDevice
 | GetOptions
렌더링 | DrawSubset
 | GetAttributeTable
버텍스 | GetFVF
 | GetNumVertices

ID3DXMesh 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

락 | LockAttributeBuffer
 | UnlockAttributeBuffer
그 외 | ConvertAdjacencyToPointReps
 | ConvertPointRepsToAdjacency
 | GenerateAdjacency
최적화 | Optimize
 | OptimizeInplace

ID3DXMesh 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXMESH 형은,ID3DXMesh 인터페이스에의 포인터로서 정의되고 있다.

typedef struct ID3DXMesh *LPD3DXMESH;

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

메쉬 함수


ID3DXMesh::ConvertAdjacencyToPointReps

메쉬의 포인트 표현을 생성한다.

HRESULT ConvertAdjacencyToPointReps(
  CONST DWORD* pAdjacency,
  DWORD* PointRep
);

파라미터

pAdjacency
[in] 메쉬의 면인접성 배열에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다.
PointRep
[in, out] 메쉬의 포인트 표현에 사용하는 전송처 버퍼에의 포인터. 포인트 표현은, 버텍스 마다 1 개의 요소를 수반하는 인덱스의 배열로서 저장 된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDMESH
E_OUTOFMEMORY

주의

포인트 표현은, 다른 방선좌표, u 좌표와 v 좌표, 칼라 데이터등을 사용하는 것이 아니라, 같은 x 좌표, y 좌표, z 좌표로 2 개의 버텍스를 융합하는 것으로써, 메쉬의 인접성을 기술하는 방법이다. 완전하게 매끈매끈한 (해 원, 경계, 또는 구멍이 없다) 메쉬에서는, 포인트 표현은 장황하다. 그 경우, 해시 테이블을 사용해 버텍스 인덱스를 공유하는 엣지를 검색하는 것에 의해, 인접하는 삼각형을 계산할 수가 있다. 해 원 및 텍스쳐 경계의 경우는, 메쉬내의 버텍스를 구성 하면도에 배치되고 있는 버텍스 그룹의 해시 테이블로 사용하는 일의의 버텍스 인덱스를 지정하기 위해서, 포인트 표현이 필요하다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMesh::ConvertPointRepsToAdjacency


ID3DXMesh::ConvertPointRepsToAdjacency

Microsoft® DirectX® (. x) 파일에 저장 되고 있는 포인트 표현 데이터를 면인접 천성보로 변환한다. 면인접 천성보는, 최적화 및 단순화의 조작에 대해 보다 뛰어난 유연성을 가져온다.

HRESULT ConvertPointRepsToAdjacency(
  CONST DWORD* pPRep,
  DWORD* pAdjacency
);

파라미터

pPRep
[in] 메쉬를 나타내는 포인트 표현에의 포인터. 포인트 표현은, 버텍스 마다 1 개의 요소를 수반하는 인덱스의 배열로서 저장 된다.
pAdjacency
[in, out] 메쉬의 면인접성 배열에 사용하는 전송처 버퍼에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

포인트 표현은, 다른 방선좌표, u 좌표와 v 좌표, 칼라 데이터등을 사용하는 것이 아니라, 같은 x 좌표, y 좌표, z 좌표로 2 개의 버텍스를 융합하는 것으로써, 메쉬의 인접성을 기술하는 방법이다. 완전하게 매끈매끈한 (해 원, 경계, 또는 구멍이 없다) 메쉬에서는, 포인트 표현은 장황하다. 그 경우, 해시 테이블을 사용해 버텍스 인덱스를 공유하는 엣지를 검색하는 것에 의해, 인접하는 삼각형을 계산할 수가 있다. 해 원 및 텍스쳐 경계의 경우는, 메쉬내의 버텍스를 구성 하면도에 배치되고 있는 버텍스 그룹의 해시 테이블로 사용하는 일의의 버텍스 인덱스를 지정하기 위해서, 포인트 표현이 필요하다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMesh::ConvertAdjacencyToPointReps


ID3DXMesh::GenerateAdjacency

Epsilon 값을 사용해 면인접 천성보를 생성한다. 면인접 천성보는, 최적화 및 단순화의 조작에 대해 보다 뛰어난 유연성을 가져온다.

HRESULT GenerateAdjacency(
  FLOAT Epsilon,
  DWORD* pAdjacency
);

파라미터

Epsilon
[in] 버텍스를 결합하는 간격을 나타내는 거리. 이 파라미터는 현재 무시되어 0.0 의 Epsilon 가 사용된다.
pAdjacency
[in, out] 메쉬의 면인접성 배열에 사용하는 전송처 버퍼에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

이 메소드는, 버텍스를 논리적으로 결합하는 것만으로, 메쉬에 대한 변경은 실시하지 않는다. 메쉬를 변경하는 경우는, 이 메소드의 뒤,D3DXWeldVertices 를 호출할 필요가 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXMesh::LockAttributeBuffer

속성 버퍼를 잠그어, 속성 버퍼 메모리에의 포인터를 취득한다.

HRESULT LockAttributeBuffer(
  DWORD Flags,
  DWORD** ppData
);

파라미터

Flags
[in] 속성 버퍼 메모리를 어떻게 잠그는지를 나타내는, 1 개(살) 이상의 락킹 플래그의 편성.
D3DLOCK_DISCARD
어플리케이션은, 락 되고 있는 영역내의 모든 장소를, 기입 전용 처리로 덧쓰기한다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는 압축 해제 스텝을 생략 할 수 있다.
D3DLOCK_NOOVERWRITE
프레임의 시작 이후, 또는 이 플래그를 가지지 않는 최신의 락 이후, 드로잉(Drawing) 호출 중(안)에서 참조되는 정보 가운데, 락시에 수정되는 정보가 없는 것을 나타낸다. 버텍스 버퍼에의 데이터의 추가만을 실시하는 경우는, 이 플래그에 의해 처리를 최적화할 수 있다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템 전체의 크리티컬 섹션을 확보해, 락의 기간중은 디스플레이 모드가 변화하지 않는 것을 보증 하면 말하는 것이다. 이 플래그를 지정 하면, 시스템 전체의 크리티컬 섹션은 락의 사이 보관 유지되지 않는다.

락 처리는 약간 부하가 높아지지만, 시스템은, 마우스 커서의 이동이라고 한 것 외의 동작을 실행할 수 있다. 이 플래그는, 그것을 실시하지 않으면 시스템의 응답에 악영향을 미치는 소프트웨어 렌더링에 대한 백 버퍼의 락과 같은, 장기간의 락에 도움이 된다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입하지 않는다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는, 언락시에 재압축 스텝을 생략 할 수 있다.
ppData
[out, retval] DWORD 값의 배열에의 포인터의 주소. 반환값의 속성 버퍼 데이터가 입력된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMesh::UnlockAttributeBuffer ,D3DXATTRIBUTERANGE


ID3DXMesh::Optimize

메쉬의 면 및 버텍스의 차례 변경을 제어해, 퍼포먼스를 최적화해, 출력 메쉬를 생성한다.

HRESULT Optimize(
  DWORD Flags,
  CONST DWORD* pAdjacencyIn,
  DWORD* pAdjacencyOut,
  DWORD* pFaceRemap,
  LPD3DXBUFFER* ppVertexRemap,
  LPD3DXMESH* ppOptMesh
);

파라미터

Flags
[in] 실행하는 최적화의 종류를 지정하는, 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESHOPT_ATTRSORT
속성 번들 스테이트의 변경을 줄여,ID3DXBaseMesh::DrawSubset 의 퍼포먼스를 강화하기 위해(때문에), 면의 차례를 변경해 최적화를 실시한다.
D3DXMESHOPT_COMPACT
면의 차례를 변경해, 사용되어 있지 않은 버텍스와 면을 삭제한다.
D3DXMESHOPT_IGNOREVERTS
면만을 최적화해, 버텍스는 최적화하지 않는다.
D3DXMESHOPT_SHAREVB
버텍스 버퍼를 공유한다.
D3DXMESHOPT_STRIPREORDER
면의 차례를 변경해, 인접하는 삼각형의 길이를 최대로 한다.
D3DXMESHOPT_VERTEXCACHE
면의 차례를 변경해, 버텍스 캐쉬의 캐쉬 히트율을 향상시킨다.

최적화 플래그의 D3DXMESHOPT_STRIPREORDER 및 D3DXMESHOPT_VERTEXCACHE 는 각각 서로 배타적이다.

pAdjacencyIn
[in, out] 소스 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pAdjacencyOut
[in, out] 최적화된 메쉬의 면인접성 배열에 사용하는 전송처 버퍼에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다.
pFaceRemap
[in, out] 각면의 새로운 인덱스를 저장 하고 있는 전송처 버퍼에의 포인터.
ppVertexRemap
[out] 각 버텍스의 새로운 인덱스를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.
ppOptMesh
[out] 최적화된 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

이 메소드는, 메쉬의 새로운 카피의 생성중에 최적화를 실행할 수 있는 점을 제외해,ID3DXBaseMesh::CloneMesh 메소드와 거의 같이이다.

출력 메쉬는, 입력 메쉬의 모든 생성 파라미터를 계승한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXMesh::OptimizeInplace

메쉬의 면 및 버텍스의 차례 변경을 제어해, 퍼포먼스를 최적화한다.

HRESULT OptimizeInplace(
  DWORD Flags,
  CONST DWORD* pAdjacencyIn,
  DWORD* pAdjacencyOut,
  DWORD* pFaceRemap,
  LPD3DXBUFFER* ppVertexRemap
);

파라미터

Flags
[in] 실행하는 최적화의 종류를 지정하는, 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESHOPT_ATTRSORT
속성 번들 스테이트의 변경을 줄여,ID3DXBaseMesh::DrawSubset 의 퍼포먼스를 강화하기 위해(때문에), 면의 차례를 변경해 최적화를 실시한다.
D3DXMESHOPT_COMPACT
면의 차례를 변경해, 사용되어 있지 않은 버텍스와 면을 삭제한다.
D3DXMESHOPT_IGNOREVERTS
면만을 최적화해, 버텍스는 최적화하지 않는다.
D3DXMESHOPT_STRIPREORDER
면의 차례를 변경해, 인접하는 삼각형의 길이를 최대로 한다.
D3DXMESHOPT_VERTEXCACHE
면의 차례를 변경해, 버텍스 캐쉬의 캐쉬 히트율을 향상시킨다.

최적화 플래그의 D3DXMESHOPT_STRIPREORDER 및 D3DXMESHOPT_VERTEXCACHE 는 각각 서로 배타적이다.

pAdjacencyIn
[in] 소스 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pAdjacencyOut
[out] 최적화된 메쉬의 면인접성 배열에 사용하는 전송처 버퍼에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다.
pFaceRemap
[out] 각면의 새로운 인덱스를 저장 하고 있는 전송처 버퍼에의 포인터.
ppVertexRemap
[out] 각 버텍스의 새로운 인덱스를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_CANNOTATTRSORT
E_OUTOFMEMORY

주 이 메소드는, 메쉬가 버텍스 버퍼를 다른 메쉬와 공유하고 있는 경우, 실패한다. 다만,Flags 파라미터에 D3DXMESHOPT_IGNOREVERTS 플래그가 설정되어 있는 경우를 제외하다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXMesh::UnlockAttributeBuffer

속성 버퍼의 락을 해제한다.

HRESULT UnlockAttributeBuffer();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 을 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXMesh::LockAttributeBuffer


ID3DXPMesh

어플리케이션은,ID3DXPMesh 인터페이스의 메소드를 사용해 프로그래시브 메쉬 오브젝트를 조작한다. 프로그래시브 메쉬에 의해, 메쉬 오브젝트의 프로그래시브 리파인이 가능해진다.

ID3DXPMesh 인터페이스는,D3DXGeneratePMesh 함수를 호출해 취득한다.

ID3DXPMesh 인터페이스는, 다음에 나타내는 ID3DXBaseMesh 메소드를 계승한다. 메소드는 이하의 그룹에 정리할 수가 있다.

버퍼 | GetIndexBuffer
 | GetVertexBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
카피 | CloneMesh
 | CloneMeshFVF
면 | GetNumFaces
정보 | GetDevice
 | GetOptions
렌더링 | DrawSubset
 | GetAttributeTable
버텍스 | GetFVF
 | GetNumVertices

ID3DXPMesh 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

카피 | ClonePMesh
 | ClonePMeshFVF
면 | GetMaxFaces
 | GetMinFaces
 | SetNumFaces
그 외 | GetAdjacency
 | Save
최적화 | Optimize
버텍스 | GetMaxVertices
 | GetMinVertices
 | SetNumVertices

ID3DXPMesh 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXPMESH 형은,ID3DXPMesh 인터페이스에의 포인터로서 정의되고 있다.

typedef struct ID3DXPMesh *LPD3DXPMESH;

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

메쉬 함수


ID3DXPMesh::ClonePMesh

선언자를 사용해 프로그래시브 메쉬의 카피를 생성 한다.

HRESULT ClonePMesh(
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXPMESH* ppCloneMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다. 이러한 메쉬는, 공유하는 버텍스 버퍼에 인덱스 붙이고 하는 개별의 인덱스 버퍼를 갖춘다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pDeclaration
[in] 출력 메쉬에 포함되는 버텍스의 버텍스 포맷을 기술하는 선언을 나타내는,DWORD 값의 배열에의 포인터. 이 파라미터는 FVF 에 직접 맵 해야 한다.
pDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppCloneMesh
[out, retval] 카피된 프로그래시브 메쉬를 나타내는 ID3DXPMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

동작환경

헤더 : D3dx8mesh.h 으로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::GetDeclaration ,D3DXDeclaratorFromFVF


ID3DXPMesh::ClonePMeshFVF

유연한 버텍스 포맷 (FVF) 코드를 사용해, 프로그래시브 메쉬의 카피를 생성 한다.

HRESULT ClonePMeshFVF(
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXPMESH* ppCloneMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다. 이러한 메쉬는, 공유하는 버텍스 버퍼에 인덱스 붙이고 하는 개별의 인덱스 버퍼를 갖춘다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
FVF
[in] 출력 메쉬에 포함되는 버텍스의 버텍스 포맷을 지정하는유연한 버텍스 포맷 플래그의 편성.
pDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppCloneMesh
[out, retval] 카피된 프로그래시브 메쉬를 나타내는 ID3DXPMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

ClonePMeshFVF 를 사용해, 프로그래시브 메쉬를 1 개의 FVF 로부터 다른 FVF 로 변환할 수 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXBaseMesh::GetFVF ,D3DXFVFFromDeclarator


ID3DXPMesh::GetAdjacency

메쉬의 면인접성 배열을 돌려준다.

HRESULT GetAdjacency(
  DWORD* pAdjacency
);

파라미터

pAdjacency
[in] 돌려주어진 메쉬의 면인접성 배열에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다. 인접성 배열의 사이즈는, 면의 수의 최대치에 3 을 곱셈한 것이다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXPMesh::GetMaxFaces


ID3DXPMesh::GetMaxFaces

프로그래시브 메쉬가 지원 하는 면의 수의 최대치를 취득한다.

DWORD GetMaxFaces();

파라미터

없음.

반환값

프로그래시브 메쉬가 지원 하는 면의 수의 최대치를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXPMesh::GetMaxVertices

프로그래시브 메쉬가 지원 하는 버텍스의 수의 최대치를 취득한다.

DWORD GetMaxVertices();

파라미터

없음.

반환값

프로그래시브 메쉬가 지원 하는 버텍스의 수의 최대치를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXPMesh::GetMinFaces

프로그래시브 메쉬가 지원 하는 면의 수의 최소 값을 취득한다.

DWORD GetMinFaces();

파라미터

없음.

반환값

프로그래시브 메쉬가 지원 하는 면의 수의 최소 값을 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXPMesh::GetMinVertices

프로그래시브 메쉬가 지원 하는 버텍스의 수의 최소 값을 취득한다.

DWORD GetMinVertices();

파라미터

없음.

반환값

프로그래시브 메쉬가 지원 하는 버텍스의 수의 최소 값을 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXPMesh::Optimize

메쉬의 면 및 버텍스의 차례 변경을 제어해, 퍼포먼스를 최적화해, 출력 메쉬를 생성한다.

HRESULT Optimize(
  DWORD Flags,
  DWORD* pAdjacencyOut,
  DWORD* pFaceRemap,
  LPD3DXBUFFER* ppVertexRemap,
  LPD3DXMESH* ppOptMesh
);

파라미터

Flags
[in] 실행하는 최적화의 종류를 지정하는, 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESHOPT_ATTRSORT
속성 번들 스테이트의 변경을 줄여,ID3DXBaseMesh::DrawSubset 의 퍼포먼스를 강화하기 위해(때문에), 면의 차례를 변경해 최적화를 실시한다.
D3DXMESHOPT_COMPACT
면의 차례를 변경해, 사용되어 있지 않은 버텍스와 면을 삭제한다.
D3DXMESHOPT_IGNOREVERTS
면만을 최적화해, 버텍스는 최적화하지 않는다.
D3DXMESHOPT_SHAREVB
버텍스 버퍼를 공유한다.
D3DXMESHOPT_STRIPREORDER
면의 차례를 변경해, 인접하는 삼각형의 길이를 최대로 한다.
D3DXMESHOPT_VERTEXCACHE
면의 차례를 변경해, 버텍스 캐쉬의 캐쉬 히트율을 향상시킨다.

최적화 플래그의 D3DXMESHOPT_STRIPREORDER 및 D3DXMESHOPT_VERTEXCACHE 는 각각 서로 배타적이다.

pAdjacencyOut
[out] 최적화된 메쉬의 면인접성 배열에 사용하는 전송처 버퍼에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다. 이 배열의 사이즈는, 면의 수의 최대치에 3 을 곱셈한 것이다.
pFaceRemap
[out] 각면의 새로운 인덱스를 저장 하고 있는 전송처 버퍼에의 포인터.
ppVertexRemap
[out] 각 버텍스의 새로운 인덱스를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.
ppOptMesh
[out] 최적화된 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXPMesh::Save

지정한 스트림 오브젝트에 프로그래시브 메쉬를 보존한다.

HRESULT Save(
  IStream* pStream,
  LPD3DXMATERIAL pMaterials,
  DWORD NumMaterials
);

파라미터

pStream
[in] 파일 데이터의 기입처가 되는 스트림 오브젝트를 나타내는,IStream 인터페이스에의 포인터.
pMaterials
[in] 스트림 오브젝트에 보존되는 머트리얼 정보를 저장 하는,D3DXMATERIAL 구조체의 배열에의 포인터.
NumMaterials
[in] pMaterials array 내의 D3DXMATERIAL 구조체의 수.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

IStream 인터페이스의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXPMesh::SetNumFaces

현재의 LOD (Level of Detail)를, 지정한 면의 수로 할 수 있는 한 접근해 설정한다.

HRESULT SetNumFaces(
  DWORD Faces
);

파라미터

Faces
[in] 면의 수를 지정한다. 이 값은 LOD (Level of Detail) 변경의 희망값을 지정한다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

면의 수가 면의 수의 최대치보다 큰 경우,ID3DXPMesh::GetMaxFaces 가 돌려주는 면의 수의 최대치가 상한이 된다. 면의 수가 면의 수의 최소 값보다 작은 경우는,ID3DXPMesh::GetMinFaces 가 돌려주는 면의 수의 최소 값이 하한이 된다.

이 호출의 뒤의 면의 수는, 1 개(살) 적게 되는 경우가 있다. 이것은, 엣지의 때보고가 발생하거나 거기에 따라 1 개(살) 또는 2 개의 면이 삭제되는 경우가 있기 때문에 있다. 예를 들어, 면이 수라고 해 4 나 6 의 값이 설정 가능한 경우에, 중간의 5 를 설정하려고 했을 경우, 항상 결과는 4 가 된다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXPMesh::SetNumVertices

현재의 LOD (Level of Detail)를, 지정한 버텍스의 수로 할 수 있는 한 접근해 설정한다.

HRESULT SetNumVertices(
  DWORD Vertices
);

파라미터

Vertices
[in] 버텍스의 수를 지정한다. 이 값은 LOD (Level of Detail) 변경의 희망값을 지정한다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

버텍스의 수가 버텍스의 수의 최대치보다 큰 경우,ID3DXPMesh::GetMaxVertices 가 돌려주는 버텍스의 수의 최대치가 상한이 된다. 버텍스의 수가 버텍스의 수의 최소 값보다 작은 경우,ID3DXPMesh::GetMinVertices 가 돌려주는 버텍스의 수의 최소 값이 하한이 된다.

이 호출의 뒤의 버텍스의 수는, 1 개(살) 적게 되는 경우가 있다. 이것은, 엣지의 때보고가 발생하거나 거기에 따라 1 개(살) 또는 2 개의 버텍스가 삭제되는 경우가 있기 때문에 있다. 예를 들어, 버텍스가 수라고 해 4 나 6 의 값이 설정 가능한 경우에, 중간의 5 를 설정하려고 했을 경우, 항상 결과는 4 가 된다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXRenderToSurface

ID3DXRenderToSurface 인터페이스는, 표면에의 렌더링의 프로세스를 범용화하기 위해서(때문에) 사용한다. 표면이 렌더링 타겟이 아닌 경우, 호환성이 있는 렌더링 타겟이 사용되어 장면의 마지막으로 결과가 표면에 카피된다.

ID3DXRenderToSurface 인터페이스는,D3DXCreateRenderToSurface 함수를 호출해 취득한다.

ID3DXRenderToSurface 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetDesc
 | GetDevice
렌더링 | BeginScene
 | EndScene

ID3DXRenderToSurface 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXRENDERTOSURFACE 형은,ID3DXRenderToSurface 인터페이스에의 포인터로서 정의되고 있다.

typedef interface ID3DXRenderToSurface* LPD3DXRENDERTOSURFACE;

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXRenderToSurface::BeginScene

장면을 시작 한다.

HRESULT BeginScene(
  LPDIRECT3DSURFACE8 pSurface,
  CONST D3DVIEWPORT8* pViewport
);

파라미터

pSurface
[in] 렌더링 표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터.
pViewport
[in] 신의 뷰 포토를 기술하는 D3DVIEWPORT8 구조체에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXRenderToSurface::EndScene


ID3DXRenderToSurface::EndScene

장면을 종료한다.

HRESULT EndScene();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXRenderToSurface::BeginScene


ID3DXRenderToSurface::GetDesc

렌더링 표면의 파라미터를 취득한다.

HRESULT GetDesc(
  D3DXRTE_DESC* pParameters
);

파라미터

pParameters

[out] 렌더링 표면의 파라미터를 기술하는 D3DXRTS_DESC 구조체에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXRenderToSurface::GetDevice

렌더링 표면에 관련지을 수 있고 있는 Microsoft® Direct3D® 디바이스를 취득한다.

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice
);

파라미터

ppDevice
[out] 렌더링 표면에 관련지을 수 있고 있는 Direct3D 디바이스 오브젝트를 나타내는,IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스의 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 인터페이스의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh

어플리케이션은,ID3DXSkinMesh 인터페이스의 메소드를 사용해 스킨 메쉬 오브젝트를 조작한다.

ID3DXSkinMesh 인터페이스는, 다음에 나타내는 함수의 어느쪽이든을 호출해 취득한다.

  • D3DXCreateSkinMesh
  • D3DXCreateSkinMeshFromMesh
  • D3DXCreateSkinMeshFVF

Microsoft® DirectX® (. x) 파일 데이터 오브젝트로부터 스킨 메쉬를 로드하려면 ,D3DXLoadSkinMeshFromXof 함수를 사용한다.

스키닝은, 메쉬가 다른 복수의 버텍스를 복수의 트랜스 폼 행렬에 의해 트랜스 폼 하는 테크닉이며, 개개의 행렬로 버텍스를 트랜스 폼 한 결과를 브렌드 해, 최종적인 트랜스 폼 된 버텍스를 취득한다.

이 프로세스는 일반적으로 스키닝으로 불려 뼈의 스켈리턴의 애니메이션에 근거해, 캐릭터의 스킨을 정의하는 메쉬를 변형시키기 위해서(때문에) 사용된다. 엄밀한 애니메이션의 가장 단순한 케이스에서는, 캐릭터 메쉬가 다른 복수의 파츠를 스켈리턴의 일의인 1 개의 뼈에 관련지어 그 뼈의 트랜스 폼을 사용해 버텍스를 트랜스 폼 한다.

스키닝을 설명하는데 도움이 되는 용어의 의미를 다음에 나타낸다.

  • 스킨. 변형을 이용해 렌더링 되는 삼각형 메쉬. 도움이 되는 포즈의 캐릭터의 모델인 것이 많다.
  • 뼈. 스킨의 하나 이상의 버텍스에 영향을 주는 트랜스 폼 행렬.
  • 스켈리턴. 스킨 메쉬에 영향을 주는 모든 뼈로부터 되는 계층.
  • 포즈. 뼈 트랜스 폼세트. 특정의 스킨 메쉬에 영향을 주는 모든 뼈의 트랜스 폼을 완전하게 정의한다.
  • 초기 포즈. 메쉬를 스켈리턴에 관련지을 수 있었던 포즈. 스켈리턴이 이 포즈 때는, 변형된 메쉬와 원의 미변형의 메쉬는 동일하다.
  • 뼈 공간 트랜스 폼. 메쉬를 특정의 뼈의 로컬 공간에 트랜스 폼 한다.
  • 뼈 웨이트. 특정의 버텍스에 대한 뼈의 영향의 정도. 웨이트 1 은, 버텍스에 영향을 주는 뼈가 그 뼈 뿐인 것을 의미해, 0 은 그 뼈가 버텍스에 영향을 주지 않는 것을 의미한다. 모든 버텍스에 대해, 1 개의 버텍스에 영향을 주는 모든 뼈의 웨이트의 합계는 1 이 된다.

스키닝 된 캐릭터는, 메쉬세트와 메쉬의 버텍스에 영향을 주는 뼈세트에 의해 정의된다. 뼈는 트랜스 폼 계층으로서 표현된다. 메쉬 마다, 그 메쉬에 영향을 주는 모든 뼈에 적용하는 행렬이 있어, 그 행렬에 의해 메쉬가 뼈의 로컬 좌표 공간에 트랜스 폼 된다. 이 행렬은, 메쉬의 뼈의 뼈 공간 트랜스 폼이다. 이 행렬은, 오쏘링 프로세스로 스켈리턴을 메쉬에 관련지을 때 정의된다.

ID3DXSkinMesh 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

버퍼 | GetIndexBuffer
 | GetVertexBuffer
변환 | ConvertToBlendedMesh
 | ConvertToIndexedBlendedMesh
정보 | GetBoneInfluence
 | GetDevice
 | GetMaxFaceInfluences
 | GetMaxVertexInfluences
 | GetNumBoneInfluences
 | GetNumBones
 | GetOptions
면 | GetNumFaces
락 | LockAttributeBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockAttributeBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
그 외 | GenerateSkinnedMesh
 | GetOriginalMesh
 | SetBoneInfluence
 | UpdateSkinnedMesh
버텍스 | GetDeclaration
 | GetFVF
 | GetNumVertices

ID3DXSkinMesh 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXSKINMESH 형은,ID3DXSkinMesh 인터페이스에의 포인터로서 정의되고 있다.

typedef struct ID3DXSkinMesh* LPD3DXSKINMESH;

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::ConvertToBlendedMesh

브렌드 된 메쉬를 돌려준다.

HRESULT ConvertToBlendedMesh(
  DWORD Options,
  CONST LPDWORD pAdjacencyIn,
  LPDWORD pAdjacencyOut,
  DWORD* pNumBoneCombinations,
  LPD3DXBUFFER* ppBoneCombinationTable,
  LPD3DXMESH* ppMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_USEHWONLY
하드웨어 처리만을 사용한다. 이 플래그는, 하드웨어 처리 디바이스 에 대해서만 지정한다. 혼합 모드의 디바이스에 대해서 이 플래그를 지정 하면, 시스템은 하드웨어만을 사용하는지, 하드웨어에 처리 능력이 없는 경우는, 소프트웨어의 능력을 사용해 개산 한다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pAdjacencyIn
[in] 소스 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pAdjacencyOut
[in, out] 최적화된 메쉬의 면인접성 배열에 사용하는 전송처 버퍼에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다.
pNumBoneCombinations
[in, out] 엔트리의 수.
ppBoneCombinationTable
[in, out] D3DXBONECOMBINATION 구조체의 배열에의 포인터의 주소. 구조체의 카운트는 pNumBoneCombinations 이다. 각각의 뼈 편성표에, 한 번에 드로잉(Drawing) 할 수 있는 4 개의 뼈가 정의된다.
ppMesh
[in, out] 브렌드 된 메쉬를 나타내는 ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,E_OUTOFMEMORY 를 돌려준다.

주의

이 메소드는, 스킨 메쉬를 받아, 브렌드 된 메쉬 (뼈의 영향을 받는 메쉬)로 변환한다. 변환에는, Microsoft® DirectX® 7. x 로 이용 가능하게 된 Microsoft® Direct3D® 버텍스 블렌딩 기능을 사용한다. 상세한 것에 대하여는, 「지오메트리 블렌딩」을 참조할것.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::ConvertToIndexedBlendedMesh

인덱스 첨부의 브렌드 된 메쉬를 돌려준다.

HRESULT ConvertToIndexedBlendedMesh(
  DWORD Options,
  CONST LPDWORD pAdjacencyIn,
  DWORD PaletteSize,
  LPDWORD pAdjacencyOut,
  DWORD* pNumBoneCombinations
  LPD3DXBUFFER* ppBoneCombinationTable
  LPD3DXMESH* ppMesh,
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pAdjacencyIn
[in] 소스 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
PaletteSize
[in] 팔레트 사이즈.
pAdjacencyOut
[in, out] 최적화된 메쉬의 면인접성 배열에 사용하는 전송처 버퍼에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다.
pNumBoneCombinations
[in, out] 엔트리의 수.
ppBoneCombinationTable
[in, out] D3DXBONECOMBINATION 구조체의 배열에의 포인터의 주소. 구조체의 카운트는 pNumBoneCombinations 이다. 각각의 뼈 편성표에, 한 번에 드로잉(Drawing) 할 수 있는 4 개의 뼈가 정의된다.
ppMesh
[in, out] 인덱스 첨부의 브렌드 된 메쉬를 나타내는 ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 스킨 메쉬를 받아, 인덱스 첨부의 브렌드 된 메쉬로 변환한다. 변환에는, Microsoft DirectX® 8.0 으로 이용 가능하게 된 Microsoft® Direct3D® 인덱스 첨부 버텍스 블렌딩 기능을 사용한다. 인덱스 첨부 버텍스 블렌딩에서는, 인덱스를 사용해, 행렬 팔레트에의 인덱스를 생성 한다. 상세한 것에 대하여는, 「지오메트리 블렌딩」을 참조할것. 스킨 메쉬로부터 인덱스 첨부의 브렌드 된 메쉬로 변환하면(자), 단일의 드로잉(Drawing) 호출 중(안)에서 메쉬를 렌더링 할 수 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GenerateSkinnedMesh

스키닝에 의해 메쉬를 생성한다.

HRESULT GenerateSkinnedMesh(
  DWORD Options,
  FLOAT minWeight,
  CONST LPDWORD pAdjacencyIn,
  LPDWORD pAdjacencyOut,
  LPD3DXMESH* ppMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
minWeight
[in] 최소 웨이트 고정값을 설정한다.
pAdjacencyIn
[in, out] 소스 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pAdjacencyOut
[in, out] 최적화된 메쉬의 면인접성 배열에 사용하는 전송처 버퍼에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다.
ppMesh
[out, retval] 스키닝에 의해 생성된 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드에 의해 생성되는 메쉬는, 스켈리턴 트랜스 폼이 변경될 때마다,ID3DXSkinMesh::UpdateSkinnedMesh 로 지정할 필요가 있는 메쉬이다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::UpdateSkinnedMesh


ID3DXSkinMesh::GetBoneInfluence

뼈가 스킨 메쉬에 어떻게 영향을 주는지를 나타내는 값의 일람을 돌려준다.

HRESULT GetBoneInfluence(
  DWORD Bone,
  DWORD* pVertices,
  FLOAT* pWeights
);

파라미터

Bone
[in] 조회하는 뼈.
pVertices
[in, out] 뼈가 영향을 주는 버텍스의 일람에의 참조.
pWeights
[in, out] 뼈가 영향을 주는 버텍스의 일람에 포함되는 각 버텍스에 관련지을 수 있었던 웨이트의 일람.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::GetBoneInfluence

Built on 2000년 11월 18일


ID3DXSkinMesh::GetDeclaration

메쉬에 포함되는 버텍스를 기술하는 선언을 취득한다.

HRESULT GetDeclaration(
  DWORD Declaration[MAX_FVF_DECL_SIZE]
);

파라미터

Declaration
[out] 조회된 메쉬에 포함되는 버텍스의 버텍스 포맷을 기술하는 돌려주어진 배열. 이 선언자의 배열의 상한은 MAX_FVF_DECL_SIZE 로, 선언자를 15 DWORD 의 최대수에 제한한다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::GetFVF


ID3DXSkinMesh::GetDevice

스킨 메쉬에 관련지을 수 있고 있는 디바이스를 취득한다.

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice

파라미터

ppDevice
[out, retval] 스킨 메쉬에 관련지을 수 있고 있는 Microsoft® Direct3D® 디바이스 오브젝트를 나타내는,IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : d3dx8mesh.h 로 선언.
임포트 라이브러리 : d3dx8.lib 을 사용.


ID3DXSkinMesh::GetFVF

스킨 메쉬에 포함되는 버텍스의 유연한 버텍스 포맷을 취득한다.

DWORD GetFVF();

파라미터

없음.

반환값

스킨 메쉬에 포함되는 버텍스의 유연한 버텍스 포맷을 기술하는,유연한 버텍스 포맷 플래그의 편성을 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::GetDeclaration


ID3DXSkinMesh::GetIndexBuffer

인덱스 버퍼내의 데이터를 취득한다.

HRESULT GetIndexBuffer(
  LPDIRECT3DINDEXBUFFER8* ppIB
);

파라미터

ppIB
[out, retval] 스킨 메쉬에 관련지을 수 있고 있는 인덱스 버퍼 오브젝트를 나타내는,IDirect3DIndexBuffer8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GetMaxFaceInfluences

면의 영향의 수의 최대치를 돌려준다.

HRESULT GetMaxFaceInfluences(
  DWORD* maxFaceInfluences
);

파라미터

maxFaceInfluences
[out, retval] 스킨 메쉬의 임의의 1 면에 영향을 주는, 영향의 수의 최대치.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

각면에 n 개의 뼈가 영향을 준다. 다음에 나타내는 그림에서는, 1 개의 면에 6 개의 뼈 (면의 각 버텍스에 영향을 주는 뼈의 합계)가 영향을 준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GetMaxVertexInfluences

버텍스의 영향의 수의 최대치를 돌려준다.

HRESULT GetMaxVertexInfluences(
  DWORD* maxVertexInfluences
);

파라미터

maxVertexInfluences
[out, retval] 스킨 메쉬의 임의의 1 개의 버텍스에 영향을 주는, 영향의 수의 최대치.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

각 버텍스에 n 개의 뼈가 영향을 준다. 이 메소드로 17 이라고 하는 값이 돌려주어졌을 경우, 스킨 메쉬의 1 개의 버텍스에 영향을 주는 뼈의 최대수는 17 이다. 따라서, 그 버텍스에는 17 의 별개의 웨이트가 존재해, 웨이트의 합계는 1 이 된다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GetNumBoneInfluences

특정의 뼈에 대한 영향 (웨이트)의 수를 돌려준다.

DWORD GetNumBoneInfluences(
  DWORD Bone
);

파라미터

Bone
[in] 조회하는 뼈.

반환값

특정의 뼈에 대한 웨이트의 수를 돌려준다. Bone 가 무효인 뼈수인 경우,GetNumBoneInfluences 는 0 을 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GetNumBones

스킨 메쉬에 포함되는 뼈의 수를 돌려준다.

DWORD GetNumBones();

파라미터

없음.

반환값

스킨 메쉬에 포함되는 뼈의 수.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GetNumFaces

스킨 메쉬에 포함되는 면의 수를 취득한다.

DWORD GetNumFaces();

파라미터

없음.

반환값

스킨 메쉬에 포함되는 면의 수를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GetNumVertices

스킨 메쉬에 포함되는 버텍스의 수를 취득한다.

DWORD GetNumVertices();

파라미터

없음.

반환값

스킨 메쉬에 포함되는 버텍스의 수를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GetOptions

이 스킨 메쉬의 생성시에 유효하게 되어 있는 메쉬 옵션을 취득한다.

DWORD GetOptions();

파라미터

없음.

반환값

이 메쉬의 생성시에 유효하게 되어 있는 옵션을 나타내는, 다음의 1 개 이상의 플래그의 편성을 돌려준다.

D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_USEHWONLY
하드웨어 처리만을 사용한다. 이 플래그는, 하드웨어 처리 디바이스 에 대해서만 지정한다. 혼합 모드의 디바이스에 대해서 이 플래그를 지정 하면, 시스템은 하드웨어만을 사용하는지, 하드웨어에 처리 능력이 없는 경우는, 소프트웨어의 능력을 사용해 개산 한다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GetOriginalMesh

원의 (디폴트) 포즈의 스킨 메쉬를 돌려준다.

HRESULT GetOriginalMesh(
  LPD3DXMESH* ppMesh
);

파라미터

ppMesh
[out, retval] 메소드가 돌아왔을 때에 원의 메쉬를 저장 하는,ID3DXMesh 인터페이스에의 포인터. 이 메소드가 돌아오면(자), 돌려주어진 메쉬의 참조 카운트가 인크리먼트(increment) 되는 것에 주의 해야 한다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,ID3DXMesh 인터페이스의 내부 참조 카운트가 증가한다. 이 ID3DXMesh 인터페이스의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::GetVertexBuffer

버텍스 버퍼내의 데이터를 취득한다.

HRESULT GetVertexBuffer(
  LPDIRECT3DVERTEXBUFFER8* ppVB
);

파라미터

ppVB
[out, retval] 스킨 메쉬에 관련지을 수 있고 있는 버텍스 버퍼 오브젝트를 나타내는,IDirect3DVertexBuffer8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::LockAttributeBuffer

속성 버퍼를 잠그어, 속성 버퍼 메모리에의 포인터를 취득한다.

HRESULT LockAttributeBuffer(
  DWORD Flags,
  DWORD** ppData
);

파라미터

Flags
[in] 속성 버퍼 메모리를 어떻게 잠그는지를 나타내는, 1 개(살) 이상의 락킹 플래그의 편성.
D3DLOCK_DISCARD
어플리케이션은, 락 되고 있는 영역내의 모든 장소를, 기입 전용 처리로 덧쓰기한다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는 압축 해제 스텝을 생략 할 수 있다.
D3DLOCK_NOOVERWRITE
프레임의 시작 이후, 또는 이 플래그를 가지지 않는 최신의 락 이후, 드로잉(Drawing) 호출 중(안)에서 참조되는 정보 가운데, 락시에 수정되는 정보가 없는 것을 나타낸다. 버텍스 버퍼에의 데이터의 추가만을 실시하는 경우는, 이 플래그에 의해 처리를 최적화할 수 있다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템 전체의 크리티컬 섹션을 확보해, 락의 기간중은 디스플레이 모드가 변화하지 않는 것을 보증 하면 말하는 것이다. 이 플래그를 지정 하면, 시스템 전체의 크리티컬 섹션은 락의 사이 보관 유지되지 않는다.

락 처리는 약간 부하가 높아지지만, 시스템은, 마우스 커서의 이동이라고 한 것 외의 동작을 실행할 수 있다. 이 플래그는, 그것을 실시하지 않으면 시스템의 응답에 악영향을 미치는 소프트웨어 렌더링에 대한 백 버퍼의 락과 같은, 장기간의 락에 도움이 된다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입하지 않는다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는, 언락시에 재압축 스텝을 생략 할 수 있다.
ppData
[out, retval] DWORD 값의 배열에의 포인터의 주소. 반환값의 속성 버퍼 데이터가 입력된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::UnlockAttributeBuffer


ID3DXSkinMesh::LockIndexBuffer

인덱스 버퍼를 잠그어, 인덱스 버퍼 메모리에의 포인터를 취득한다.

HRESULT LockIndexBuffer(
  DWORD Flags,
  BYTE** ppData
);

파라미터

Flags
[in] 인덱스 버퍼 메모리를 어떻게 잠그는지를 기술하는, 1 개(살) 이상의 락킹 플래그의 편성.
D3DLOCK_DISCARD
어플리케이션은, 락 되고 있는 영역내의 모든 장소를, 기입 전용 처리로 덧쓰기한다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는 압축 해제 스텝을 생략 할 수 있다.
D3DLOCK_NOOVERWRITE
프레임의 시작 이후, 또는 이 플래그를 가지지 않는 최신의 락 이후, 드로잉(Drawing) 호출 중(안)에서 참조되는 인덱스 가운데, 락시에 수정되는 인덱스가 없는 것을 나타낸다. 이것에 의해, 어플리케이션이 인덱스 버퍼에 데이터를 추가할 뿐(만큼)의 경우에 최적화를 유효하게 할 수 있다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템 전체의 크리티컬 섹션을 확보해, 락의 기간중은 디스플레이 모드가 변화하지 않는 것을 보증 하면 말하는 것이다. 이 플래그를 지정 하면, 시스템 전체의 크리티컬 섹션은 락의 사이 보관 유지되지 않는다.

락 처리는 약간 부하가 높아지지만, 시스템은, 마우스 커서의 이동이라고 한 것 외의 동작을 실행할 수 있다. 이 플래그는, 그것을 실시하지 않으면 시스템의 응답에 악영향을 미치는 소프트웨어 렌더링에 대한 백 버퍼의 락과 같은, 장기간의 락에 도움이 된다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입하지 않는다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는, 언락시에 재압축 스텝을 생략 할 수 있다.
ppData
[out, retval] BYTE 값의 배열에의 포인터의 주소. 반환값의 인덱스 데이터가 입력된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

인덱스 버퍼를 조작 하면나무는, 복수의 락 호출을 실행할 수 있다. 다만, 락 호출의 수와 락 해제 호출의 수를 일치시킬 필요가 있다. 현재 설정되어 있는 인덱스 버퍼로 락 카운트가 남아 있는 경우, DrawPrimitive 의 호출은 실패한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::UnlockIndexBuffer


ID3DXSkinMesh::LockVertexBuffer

버텍스 버퍼를 잠그어, 버텍스 버퍼 메모리에의 포인터를 취득한다.

HRESULT LockVertexBuffer(
  DWORD Flags,
  BYTE** ppData
);

파라미터

Flags
[in] 버텍스 버퍼 메모리를 어떻게 잠그는지를 나타내는, 1 개(살) 이상의 락킹 플래그의 편성.
D3DLOCK_DISCARD
어플리케이션은, 락 되고 있는 영역내의 모든 장소를, 기입 전용 처리로 덧쓰기한다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는 압축 해제 스텝을 생략 할 수 있다.
D3DLOCK_NOOVERWRITE
프레임의 시작 이후, 또는 이 플래그를 가지지 않는 최신의 락 이후, 드로잉(Drawing) 호출 중(안)에서 참조되는 버텍스 가운데, 락시에 수정되는 버텍스가 없는 것을 나타낸다. 버텍스 버퍼에의 데이터의 추가만을 실시하는 경우는, 이 플래그에 의해 처리를 최적화할 수 있다.
D3DLOCK_NOSYSLOCK
비디오 메모리 락의 디폴트의 동작은, 시스템 전체의 크리티컬 섹션을 확보해, 락의 기간중은 디스플레이 모드가 변화하지 않는 것을 보증 하면 말하는 것이다. 이 플래그를 지정 하면, 시스템 전체의 크리티컬 섹션은 락의 사이 보관 유지되지 않는다.

락 처리는 약간 부하가 높아지지만, 시스템은, 마우스 커서의 이동이라고 한 것 외의 동작을 실행할 수 있다. 이 플래그는, 그것을 실시하지 않으면 시스템의 응답에 악영향을 미치는 소프트웨어 렌더링에 대한 백 버퍼의 락과 같은, 장기간의 락에 도움이 된다.

D3DLOCK_READONLY
어플리케이션은 버퍼에 기입하지 않는다. 이것에 의해, 비네이티브 포맷으로 저장 되고 있는 리소스는, 언락시에 재압축 스텝을 생략 할 수 있다.
ppData
[out, retval] BYTE 값의 배열에의 포인터의 주소. 반환값의 버텍스 데이터가 입력된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

버텍스 버퍼를 조작 하면나무는, 복수의 락 호출을 실행할 수 있다. 다만, 락 호출의 수와 락 해제 호출의 수를 일치시킬 필요가 있다. 현재 설정되어 있는 버텍스 버퍼에 미처리의 락 카운트가 있는 경우, DrawPrimitive 호출은 성공하지 않는다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::UnlockVertexBuffer


ID3DXSkinMesh::SetBoneInfluence

스킨 메쉬에 포함되는 뼈에 대해서, 뼈의 영향을 설정한다.

HRESULT SetBoneInfluence(
  DWORD Bone,
  DWORD numInfluences,
  CONST DWORD* pVertices,
  CONST FLOAT* pWeights
);

파라미터

Bone
[in] 영향을 설정하는 뼈.
numInfluences
[in] 뼈에 대해서 설정하는 영향의 수.
pVertices
[in] 영향 (웨이트)의 설정에 사용하는 버텍스의 일람에의 포인터.
pWeights
[in] 지정된 버텍스에 대해서 설정하는 웨이트의 일람에의 포인터. 이러한 값은, 스킨 메쉬의 스키닝 정보를 프로그램에 근거해 저장 하기 위해서 사용된다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,E_OUTOFMEMORY 를 돌려준다.

주의

이 메소드는, 특정의 뼈가 특정의 버텍스에 어떻게 영향을 주는지를 지정하는 구조를 제공한다. 이 메소드는, 메쉬에 영향을 주는 각 뼈에 대해서 호출할 필요가 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSkinMesh::UnlockAttributeBuffer

속성 버퍼의 락을 해제한다.

HRESULT UnlockAttributeBuffer();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::LockAttributeBuffer


ID3DXSkinMesh::UnlockIndexBuffer

인덱스 버퍼의 락을 해제한다.

HRESULT UnlockIndexBuffer();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::LockIndexBuffer


ID3DXSkinMesh::UnlockVertexBuffer

버텍스 버퍼의 락을 해제한다.

HRESULT UnlockVertexBuffer();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::LockVertexBuffer


ID3DXSkinMesh::UpdateSkinnedMesh

스킨 메쉬를 갱신한다.

HRESULT UpdateSkinnedMesh(
  CONST D3DXMATRIX* pBoneTransforms,
  LPD3DXMESH pMesh
);

파라미터

pBoneTransforms
[in] 새로운 뼈 트랜스 폼을 나타내는,D3DXMATRIX 구조체의 배열에의 포인터. 이 배열의 길이는, 스킨 메쉬에 포함되는 모든 뼈의 카운트이다.
pMesh
[out, retval] 갱신된 스키닝 된 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 새로운 뼈 트랜스 폼과 브렌드 된 버텍스를 갱신한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::GenerateSkinnedMesh


ID3DXSPMesh

어플리케이션은,ID3DXSPMesh 인터페이스의 메소드를 사용해 단순화 메쉬 오브젝트를 조작한다. 단순화 메쉬는, 지정한 메쉬를 단순화 해, 면의 수를 줄이기 위해서(때문에) 사용한다.

ID3DXSPMesh 인터페이스는,D3DXCreateSPMesh 함수를 호출해 취득한다.

ID3DXSPMesh 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

카피 | CloneMesh
 | CloneMeshFVF
 | ClonePMesh
 | ClonePMeshFVF
면 | GetMaxFaces
 | GetNumFaces
 | ReduceFaces
정보 | GetDevice
 | GetOptions
버텍스 | GetDeclaration
 | GetFVF
 | GetMaxVertices
 | GetNumVertices
 | ReduceVertices

ID3DXSPMesh 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXSPMESH 형은,ID3DXSPMesh 인터페이스에의 포인터로서 정의되고 있다.

typedef struct ID3DXSPMesh *LPD3DXSPMESH;

동작환경

헤더 : D3dx8mesh.h 으로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

메쉬 함수


ID3DXSPMesh::CloneMesh

선언자를 사용해 메쉬의 카피를 생성 한다.

HRESULT CloneMesh(
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pD3DDevice,
  DWORD* pAdjacency,
  DWORD* pVertexRemap,
  LPD3DXMESH* ppCloneMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다. 이러한 메쉬는, 공유하는 버텍스 버퍼에 인덱스 붙이고 하는 개별의 인덱스 버퍼를 갖춘다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pDeclaration
[in] 출력 메쉬에 포함되는 버텍스의 버텍스 포맷을 기술하는 선언자를 나타내는,DWORD 값의 배열에의 포인터. 이 파라미터는 FVF 에 직접 맵 해야 한다.
pD3DDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pAdjacency
[in] 소스 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pVertexRemap
[in] 각 버텍스의 인덱스를 저장 하는 배열에의 포인터.
ppCloneMesh
[out, retval] 카피된 메쉬를 나타내는 ID3DXPMesh 인터페이스에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSPMesh::GetDeclaration ,D3DXDeclaratorFromFVF


ID3DXSPMesh::CloneMeshFVF

유연한 버텍스 포맷 (FVF) 코드를 사용해 메쉬의 카피를 생성 한다.

HRESULT CloneMeshFVF(
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  DWORD* pAdjacency,
  DWORD* pVertexRemap,
  LPD3DXMESH* ppCloneMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다. 이러한 메쉬는, 공유하는 버텍스 버퍼에 인덱스 붙이고 하는 개별의 인덱스 버퍼를 갖춘다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
FVF
[in] 출력 메쉬에 포함되는 버텍스의 버텍스 포맷을 지정하는유연한 버텍스 포맷 플래그의 편성.
pDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pAdjacency
[in] 소스 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pVertexRemap
[in] 각 버텍스의 인덱스를 저장 하는 배열에의 포인터.
ppCloneMesh
[out, retval] 카피된 메쉬를 나타내는 ID3DXPMesh 인터페이스에의 포인터.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

CloneMeshFVF 를 사용해, 메쉬를 1 개의 FVF 로부터 다른 FVF 로 변환할 수 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSPMesh::GetFVF ,D3DXFVFFromDeclarator


ID3DXSPMesh::ClonePMesh

선언자를 사용해 프로그래시브 메쉬의 카피를 생성 한다.

HRESULT ClonePMesh(
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pDevice,
  DWORD* pVertexRemap,
  LPD3DXPMESH* ppCloneMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다. 이러한 메쉬는, 공유하는 버텍스 버퍼에 인덱스 붙이고 하는 개별의 인덱스 버퍼를 갖춘다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pDeclaration
[in] 출력 메쉬에 포함되는 버텍스의 버텍스 포맷을 기술하는 선언자를 나타내는,DWORD 값의 배열에의 포인터. 이 파라미터는 FVF 에 직접 맵 해야 한다.
pDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pVertexRemap
[in] 각 버텍스의 인덱스를 저장 하는 배열에의 포인터.
ppCloneMesh
[out, retval] 카피된 프로그래시브 메쉬를 나타내는 ID3DXPMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_CANNOTATTRSORT
E_OUTOFMEMORY

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSPMesh::GetDeclaration ,D3DXDeclaratorFromFVF


ID3DXSPMesh::ClonePMeshFVF

유연한 버텍스 포맷 (FVF) 코드를 사용해, 프로그래시브 메쉬의 카피를 생성 한다.

HRESULT ClonePMeshFVF(
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  DWORD* pVertexRemap,
  LPD3DXPMESH* ppCloneMesh
);

파라미터

Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다. 이러한 메쉬는, 공유하는 버텍스 버퍼에 인덱스 붙이고 하는 개별의 인덱스 버퍼를 갖춘다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
FVF
[in] 출력 메쉬에 포함되는 버텍스의 버텍스 포맷을 지정하는유연한 버텍스 포맷 플래그의 편성.
pDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pVertexRemap
[in] 각 버텍스의 인덱스를 저장 하는 배열에의 포인터.
ppCloneMesh
[out, retval] 카피된 프로그래시브 메쉬를 나타내는 ID3DXPMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_CANNOTATTRSORT
E_OUTOFMEMORY

주의

ClonePMeshFVF 를 사용해, 프로그래시브 메쉬를 1 개의 FVF 로부터 다른 FVF 로 변환할 수 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSPMesh::GetFVF ,D3DXFVFFromDeclarator


ID3DXSPMesh::GetDeclaration

메쉬에 포함되는 버텍스를 기술하는 선언을 취득한다.

HRESULT GetDeclaration(
  DWORD Declaration[MAX_FVF_DECL_SIZE]
);

파라미터

Declaration
[out] 조회된 메쉬에 포함되는 버텍스의 버텍스 포맷을 기술하는 돌려주어진 배열. 이 선언자의 배열의 상한은 MAX_FVF_DECL_SIZE 로, 선언자를 15 DWORD 의 최대수에 제한한다.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

대상

이 메소드는,ID3DXBaseMesh 를 계승하는 다음의 인터페이스에 적용된다.

  • ID3DXMesh
  • ID3DXPMesh

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSPMesh::GetFVF


ID3DXSPMesh::GetDevice

단순화 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 취득한다.

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice

파라미터

ppDevice
[out, retval] 단순화 메쉬에 관련지을 수 있고 있는 Microsoft® Direct3D® 디바이스 오브젝트를 나타내는,IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스의 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 인터페이스의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSPMesh::GetFVF

단순화 메쉬에 포함되는 버텍스의 유연한 버텍스 포맷을 취득한다.

DWORD GetFVF();

파라미터

없음.

반환값

단순화 메쉬에 포함되는 버텍스의 유연한 버텍스 포맷을 기술하는,유연한 버텍스 포맷 플래그의 편성을 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSPMesh::GetDeclaration


ID3DXSPMesh::GetMaxFaces

단순화 메쉬가 지원 하는 면의 수의 최대치를 취득한다.

DWORD GetMaxFaces();

파라미터

없음.

반환값

원의 메쉬에 포함되는 면의 최대수를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSPMesh::GetMaxVertices

단순화 메쉬가 지원 하는 버텍스의 수의 최대치를 취득한다.

DWORD GetMaxVertices();

파라미터

없음.

반환값

원의 메쉬에 포함되는 버텍스의 최대수를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSPMesh::GetNumFaces

단순화 메쉬에 포함되는 면의 수를 취득한다.

DWORD GetNumFaces();

파라미터

없음.

반환값

단순화 메쉬에 포함되는 면의 수를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSPMesh::GetNumVertices

단순화 메쉬에 포함되는 버텍스의 수를 취득한다.

DWORD GetNumVertices();

파라미터

없음.

반환값

단순화 메쉬에 포함되는 버텍스의 수를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSPMesh::GetOptions

이 단순화 메쉬의 생성시에 유효하게 되어 있는 메쉬 옵션을 취득한다.

DWORD GetOptions();

파라미터

없음.

반환값

이 메쉬의 생성시에 유효하게 되어 있는 옵션을 나타내는, 다음의 1 개 이상의 플래그의 편성을 돌려준다.

D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에, 사용해서는 안된다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼 및 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 사용해 생성 되게 된다. 이것은, Microsoft® Direct3D® 의 N 패치 확장 기능을 사용해 메쉬 오브젝트를 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SHARE
카피한 메쉬에 버텍스 버퍼를 공유시킨다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSPMesh::ReduceFaces

단순화 메쉬에 포함되는 면의 수를 줄인다.

HRESULT ReduceFaces(
  DWORD Faces
);

파라미터

Faces
[in] 프리미티브 카운트를 줄인 후의 면의 수.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 엣지의 때보고를 실시해,Faces 로 지정한 값까지 프리미티브의 수를 줄인다. 특정의 제한이 있기 (위해)때문에, 메쉬가 요구된 값까지 항상 줄일 수 있는 것은 아니다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSPMesh::ReduceVertices

단순화 메쉬에 포함되는 버텍스의 수를 줄인다.

HRESULT ReduceVertices(
  DWORD Vertices
);

파라미터

Vertices
[in] 프리미티브 카운트를 줄인 후의 버텍스의 수.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

이 메소드는, 엣지의 때보고를 실시해,Vertices 로 지정한 값까지 프리미티브의 수를 줄인다. 특정의 제한이 있기 (위해)때문에, 메쉬가 요구된 값까지 항상 줄일 수 있는 것은 아니다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSprite

ID3DXSprite 인터페이스는, Microsoft® Direct3D® 를 사용해 스프라이트를 드로잉(Drawing) 하는 프로세스를 단순화 하는 메소드세트를 제공한다.

ID3DXSprite 인터페이스는,D3DXCreateSprite 함수를 호출해 취득한다.

ID3DXSprite 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

드로잉(Drawing) | Begin
 | Draw
 | DrawTransform
 | End
정보 | GetDevice

ID3DXSprite 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXSPRITE 형은,ID3DXSprite 인터페이스에의 포인터로서 정의되고 있다.

typedef interface ID3DXSprite *LPD3DXSPRITE;

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXSprite::Begin

스프라이트를 드로잉(Drawing) 할 수 있도록(듯이) 디바이스를 준비한다.

HRESULT Begin();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

Begin 의 호출은 생략 할 수 있다. Begin/End 순서의 외측에서 드로잉(Drawing) 함수를 호출하면, 내부에서 Begin 와End 가 불려 간다. 여분의 오버헤드를 회피하려면 , 복수의 드로잉(Drawing) 함수를 계속해 호출하는 경우에, 이 메소드를 사용할 필요가 있다.

IDirect3DDevice8::BeginScene 또는 ID3DXRenderToSurface::BeginScene 의 대신으로서 ID3DXSprite::Begin 를 사용할 수 없다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSprite::End


ID3DXSprite::Draw

스크린 공간에 단순한 스프라이트를 드로잉(Drawing) 한다.

HRESULT Draw(
  LPDIRECT3DTEXTURE8 pSrcTexture,
  CONST RECT* pSrcRect,
  CONST D3DXVECTOR2* pScaling,
  CONST D3DXVECTOR2* pRotationCenter,
  FLOAT Rotation,
  CONST D3DVECTOR2* pTranslation,
  D3DCOLOR Color
);

파라미터

pSrcTexture
[in] 스프라이트에 사용하는 소스 이미지를 나타내는 IDirect3DTexture8 인터페이스에의 포인터.
pSrcRect
[in] 소스 텍스쳐의 어느 부분을 스프라이트에 사용하는지를 나타내는 RECT 구조체에의 포인터. 이 파라미터를 NULL 로 하면(자), 소스 이미지 전체가 스프라이트에 사용된다. 다만, 소스 이미지의 부분적인 직사각형을 지정할 수도 있다. 이 RECT 구조체의 왼쪽과 위 및 오른쪽과 아래의 파라미터를 바꿔 넣으면(자), x 와 y 의 미러링을 간단하게 지정할 수 있다.

트랜스 폼의 전에, 스프라이트의 사이즈가 pSrcRect 에 의해 좌상구석을 시점 (0,0)으로서 정의된다.

pScaling
[in] 스케일링 벡터인 D3DXVECTOR2 구조체에의 포인터. 이 인수가 NULL 의 경우는, 스케일링 하지 않다고 보여진다.
pRotationCenter
[in] 회전의 중심을 식별하는 포인트인 D3DVECTOR2 구조체에의 포인터. 이 인수가 NULL 의 경우는, 텍스쳐의 좌상구석을 나타내는 포인트 (0,0)이다고 보여진다.
Rotation
[in] 회전을 지정하는 값.
pTranslation
[in] 평행이동을 나타내는 D3DXVECTOR2 구조체에의 포인터. 이 인수가 NULL 의 경우는, 평행이동 하지 않다고 보여진다.
Color
[in] D3DCOLOR 형. 이 값에 의해 칼라 채널과 알파 채널이 곱셈된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

ID3DXSprite::Begin 가 불려 가지 않은 경우, 이 메소드는 내부에서 Begin 와 ID3DXSprite::End 를 호출한다. ID3DXSprite::Draw 또는 ID3DXSprite::DrawTransform 혹은 그 양쪽 모두를 계속해 호출하는 경우는, 반드시 Begin 를 호출해,Draw 및 DrawTransform 가 매회 내부에서 Begin 와 End 를 호출하는 여분의 오버헤드를 회피할 필요가 있다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSprite::DrawTransform


ID3DXSprite::DrawTransform

지정한 행렬에 의해 트랜스 폼 한 스프라이트를 드로잉(Drawing)하기 위한 구조를 제공한다.

HRESULT DrawTransform(
  LPDIRECT3DTEXTURE8 pSrcTexture,
  CONST RECT* pSrcRect,
  CONST D3DXMATRIX* pTransform,
  D3DCOLOR Color
);

파라미터

pSrcTexture
[in] 스프라이트에 사용하는 소스 이미지를 나타내는 IDirect3DTexture8 인터페이스에의 포인터.
pSrcRect
[in] 소스 텍스쳐의 어느 부분을 스프라이트에 사용하는지를 나타내는 RECT 구조체에의 포인터. 이 파라미터를 NULL 로 하면(자), 소스 이미지 전체가 스프라이트에 사용된다. 다만, 소스 이미지의 부분적인 직사각형을 지정할 수도 있다. 이 RECT 구조체의 왼쪽과 위 및 오른쪽과 아래의 파라미터를 바꿔 넣으면(자), x 와 y 의 미러링을 간단하게 지정할 수 있다.

트랜스 폼의 전에, 스프라이트의 사이즈가 pSrcRect 에 의해 좌상구석을 시점 (0,0)으로서 정의된다.

pTransform
[in] 적용하는 트랜스 폼을 지정하는 D3DXMATRIX 구조체에의 포인터.
Color
[in] D3DCOLOR 형. 이 값에 의해 칼라 채널과 알파 채널이 곱셈된다.

반환값

성공했을 경우는,D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

ID3DXSprite::Begin 가 불려 가지 않은 경우, 이 메소드는 내부에서 Begin 와 ID3DXSprite::End 를 호출한다. ID3DXSprite::Draw 또는 ID3DXSprite::DrawTransform 혹은 그 양쪽 모두를 계속해 호출하는 경우는, 반드시 Begin 를 호출해,Draw 및 DrawTransform 가 매회 내부에서 Begin 와 End 를 호출하는 여분의 오버헤드를 회피할 필요가 있다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSprite::Draw


ID3DXSprite::End

ID3DXSprite::Begin 가 불려 간 시점의 디바이스 상태를 복원한다.

HRESULT End();

파라미터

없음.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

IDirect3DDevice8::EndScene 또는 ID3DXRenderToSurface::EndScene 의 대신으로서 ID3DXSprite::End 를 사용할 수 없다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSprite::Begin


ID3DXSprite::GetDevice

스프라이트 오브젝트에 관련지을 수 있고 있는 Microsoft® Direct3D® 디바이스를 취득한다.

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice
);

파라미터

ppDevice
[out, retval] 스프라이트 오브젝트에 관련지을 수 있고 있는 Direct3D 디바이스 오브젝트를 나타내는,IDirect3DDevice8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스의 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 인터페이스의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXTechnique

ID3DXTechnique 인터페이스는, 테크닉의 조회, 검증, 및 적용에 사용한다.

ID3DXTechnique 인터페이스는,ID3DXEffect::GetTechnique 메소드를 호출하는 것에 의해 취득한다.

ID3DXTechnique 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

이펙트 | IsParameterUsed
정보 | GetDevice
 | GetDesc
 | GetPassDesc
검증 | Validate
테크닉 적용 | Begin
 | End
 | Pass

ID3DXTechnique 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXTECHNIQUE 형은,ID3DXTechnique 인터페이스에의 포인터로서 정의되고 있다.

typedef struct ID3DXTechnique* LPD3DXTECHNIQUE;

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXTechnique::Begin

테크닉의 어플리케이션을 시작 한다.

HRESULT Begin(
  UINT* pPasses
);

파라미터

pPasses
[out, retval] 테크닉의 렌더링에 필요한 패스수를 나타내는 값에의 포인터.

반환값

항상 S_OK 를 돌려준다.

주의

이 메소드는, 테크닉의 렌더링에 필요한 패스수를 돌려준다. 이펙트를 적용할 필요가 있는 지오메트리를 드로잉(Drawing) 하기 위한(해), 어플리케이션은 패스 마다 값을 늘려 ID3DXTechnique::Pass 를 호출하지 않으면 안 된다. 모든 패스의 렌더링이 종료하면(자),ID3DXTechnique::End 를 호출하지 않으면 안 된다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXTechnique::End ,ID3DXTechnique::Pass


ID3DXTechnique::End

테크닉의 어플리케이션을 종료한다.

HRESULT End();

파라미터

없음.

반환값

항상 S_OK 를 돌려준다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXTechnique::Begin ,ID3DXTechnique::Pass


ID3DXTechnique::GetDevice

테크닉에 관련지을 수 있고 있는 디바이스를 취득한다.

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
);

파라미터

ppDevice
IDirect3DDevice8 인터페이스에의 포인터의 주소. 테크닉에 관련지을 수 있고 있는 디바이스를 나타낸다.

반환값

항상 S_OK 를 돌려준다.

주 이 메소드를 호출하면,IDirect3DDevice8 인터페이스의 내부 참조 카운트가 증가한다. 이 IDirect3DDevice8 인터페이스의 처리가 종료하면(자), 반드시 IUnknown::Release 를 호출할 필요가 있다. 그렇게 하지 않으면 메모리 누수가 발생한다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXTechnique::GetDesc

테크닉의 설명을 취득한다.

HRESULT GetDesc(
  D3DXTECHNIQUE_DESC* pDesc
);

파라미터

pDesc
[out, retval] D3DXTECHNIQUE_DESC 구조체. 테크닉의 설명.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXTechnique::GetPassDesc

이펙트의 패스에 관한 정보를 취득한다.

HRESULT GetPassDesc(
  UINT           Index,
  D3DXPASS_DESC* pDesc
)

파라미터

Index
정보를 취득하는 패스의 인덱스.
pDesc
[out, retval] 패스의 설명을 저장 하는 D3DXPASS_DESC 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXTechnique::IsParameterUsed

테크닉이 파라미터를 사용하고 있을지 어떨지를 판별한다.

BOOL IsParameterUsed(
  DWORD Name
)

파라미터

Name
조사하는 파라미터의 인덱스. 이 파라미터는 FOURCC 코드가 아니면 안된다. 「주의」를 참조할것.

반환값

파라미터가 사용되고 있는 경우는 TRUE 를 돌려준다. 파라미터가 사용되어 있지 않은 경우는 FALSE 를 돌려준다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


ID3DXTechnique::Pass

지정한 테크닉의 패스에 대해, 스테이트의 설정을 적용한다.

HRESULT Pass(
  UINT Index
);

파라미터

Pass
[in] 적용하는 패스를 지정한다.

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

Pass 를 호출한 후, 어플리케이션은, 이펙트가 설정되는 디바이스에 대해서 지오메트리를 드로잉(Drawing) 해야 한다.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXTechnique::Begin ,ID3DXTechnique::End


ID3DXTechnique::Validate

테크닉을 검증한다.

HRESULT Validate();

반환값

성공했을 경우는, S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


함수

여기에서는, Direct3DX 유틸리티 라이브러리를 사용할 때에 이행 할 필요가 있는 함수의 레퍼런스 정보를 기술한다. 다음의 함수가 이행 되고 있다.

  • 이펙트 함수
  • 범용 함수
  • 산술 함수
  • 메쉬 함수
  • 쉐이더 함수
  • 형상 드로잉(Drawing) 함수
  • 텍스쳐 함수


이펙트 함수

Direct3DX 에서는 다음의 이펙트 함수가 준비되어 있다.

  • D3DXCompileEffect
  • D3DXCompileEffectFromFileA
  • D3DXCompileEffectFromFileW
  • D3DXCreateEffect


D3DXCompileEffect

이펙트의 ASCII 기술을,D3DXCreateEffect 로 사용할 수 있는 바이너리 형식에 컴파일 한다.

HRESULT WINAPI D3DXCompileEffect(
  LPCVOID       pSrcData,
  UINT          SrcDataSize,
  LPD3DXBUFFER* ppCompiledEffect,
  LPD3DXBUFFER* ppCompilationErrors
);

파라미터

pSrcData
[in] 컴파일 하는 이펙트를 나타내는 소스 데이터에의 포인터.
SrcDataSize
[in] 소스 데이터의 사이즈 (바이트 단위).
ppCompiledEffect
[out, retval] 컴파일 된 이펙트를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.
ppCompilationErrors
[out, retval] 돌려주어진 ASCII 에러 메세지를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

이펙트를 컴파일 한 후,D3DXCreateEffect 를 사용해 ID3DXEffect 인터페이스에의 포인터를 취득하는 것.

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCompileEffectFromFileA , D3DXCompileEffectFromFileW , D3DXCreateEffect


D3DXCompileEffectFromFileA

ANSI 캐릭터 라인으로 지정한 파일을 바탕으로 해 이펙트를 컴파일 한다.

HRESULT WINAPI D3DXCompileEffectFromFileA(
  LPCSTR        pSrcFile,
  LPD3DXBUFFER* ppCompiledEffect,
  LPD3DXBUFFER* ppCompilationErrors
);

파라미터

pSrcFile
[in] 이펙트 생성의 원이 되는 파일을 지정하는 ANSI 캐릭터 라인에의 포인터.
ppCompiledEffect
[out, retval] 컴파일 된 이펙트를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.
ppCompilationErrors
[out, retval] 돌려주어진 ASCII 에러 메세지를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

이펙트를 컴파일 한 후,D3DXCreateEffect 를 사용해 ID3DXEffect 인터페이스에의 포인터를 취득하는 것.

D3DXCompileEffectFromFile 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCompileEffectFromFileA 또는 D3DXCompileEffectFromFileW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCompileEffectFromFile 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCompileEffectFromFile D3DXCompileEffectFromFileW
#else
#define D3DXCompileEffectFromFile D3DXCompileEffectFromFileA
#endif

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCompileEffect , D3DXCompileEffectFromFileW , D3DXCreateEffect


D3DXCompileEffectFromFileW

Unicode 캐릭터 라인으로 지정한 파일을 바탕으로 해 이펙트를 컴파일 한다.

HRESULT WINAPI D3DXCompileEffectFromFileW(
  LPCWSTR       pSrcFile,
  LPD3DXBUFFER* ppCompiledEffect,
  LPD3DXBUFFER* ppCompilationErrors
);

파라미터

pSrcFile
[in] 이펙트 생성의 원이 되는 파일을 지정하는 Unicode 캐릭터 라인에의 포인터.
ppCompiledEffect
[out, retval] 컴파일 된 이펙트를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.
ppCompilationErrors
[out, retval] 돌려주어진 ASCII 에러 메세지를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

이펙트를 컴파일 한 후,D3DXCreateEffect 를 사용해 ID3DXEffect 인터페이스에의 포인터를 취득하는 것.

D3DXCompileEffectFromFile 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCompileEffectFromFileA 또는 D3DXCompileEffectFromFileW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCompileEffectFromFile 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCompileEffectFromFile D3DXCompileEffectFromFileW
#else
#define D3DXCompileEffectFromFile D3DXCompileEffectFromFileA
#endif

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCompileEffect , D3DXCompileEffectFromFileA , D3DXCreateEffect


D3DXCreateEffect

컴파일 끝난 소스 데이터를 사용해 이펙트를 생성 한다.

HRESULT WINAPI D3DXCreateEffect(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID           pCompiledEffect,
  UINT              CompiledEffectSize,
  DWORD             Usage,
  LPD3DXEFFECT*     ppEffect
);

파라미터

pDevice
[in] 이펙트에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pCompiledEffect
[in] 이펙트 생성의 바탕으로 되는 컴파일 끝난 소스 데이터에의 포인터.
CompiledEffectSize
[in] 컴파일 끝난 데이터의 사이즈 (바이트 단위).
Usage
[in] 이 이펙트의 사용 방법의 제어 정보. 다음의 플래그를 설정할 수 있다.
D3DUSAGE_SOFTWAREPROCESSING
이펙트가 소프트웨어 처리를 사용해 렌더링 되는 것을 나타낸다.
ppEffect
[out, retval] 생성 된 이펙트를 나타내는,ID3DXEffect 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

CreateEffect 를 사용하기 전에, 다음의 몇개의 함수를 사용해 이펙트를 컴파일 해야 한다.

  • D3DXCompileEffect
  • D3DXCompileEffectFromFileA
  • D3DXCompileEffectFromFileW

동작환경

헤더 : D3dx8effect.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCompileEffect , D3DXCompileEffectFromFileA , D3DXCompileEffectFromFileW


범용 함수

Direct3DX 에서는 다음의 범용 함수가 준비되어 있다.

  • D3DXCreateFont
  • D3DXCreateFontIndirect
  • D3DXCreateRenderToSurface
  • D3DXCreateSprite
  • D3DXGetErrorStringA
  • D3DXGetErrorStringW
  • D3DXGetFVFVertexSize


D3DXCreateFont

디바이스와 폰트용의 폰트 오브젝트를 생성 한다.

HRESULT D3DXCreateFont(
  LPDIRECT3DDEVICE8 pDevice,
  HFONT hFont,
  LPD3DXFONT* ppFont
);

파라미터

pDevice
[in] 폰트 오브젝트에 관련지을 수 있는 디바이스인,IDirect3DDevice8 인터페이스에의 포인터.
hFont
[in] 폰트 오브젝트에의 핸들.
ppFont
[out] 생성 된 폰트 오브젝트를 나타내는,ID3DXFont 인터페이스에의 포인터를 돌려준다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateFontIndirect

디바이스와 폰트용의 폰트 오브젝트를 간접적으로 생성 한다.

HRESULT D3DXCreateFontIndirect(
  LPDIRECT3DDEVICE8 pDevice,
  CONST LOGFONT* pLogFont,
  LPD3DXFONT* ppFont
);

파라미터

pDevice
[in] 폰트 오브젝트에 관련지을 수 있는 디바이스인,IDirect3DDevice8 인터페이스에의 포인터.
pLogFont
[in] 생성 하는 폰트 오브젝트의 속성을 기술하는,LOGFONT 구조체에의 포인터.
ppFont
[out] 생성 된 폰트 오브젝트를 나타내는,ID3DXFont 인터페이스에의 포인터를 돌려준다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

LOGFONT 구조체의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateRenderToSurface

렌더링 표면을 생성 한다.

HRESULT D3DXCreateRenderToSurface(
  LPDIRECT3DDEVICE8 pDevice,
  UINT Width,
  UINT Height,
  D3DFORMAT Format,
  BOOL DepthStencil,
  D3DFORMAT DepthStencilFormat,
  LPD3DXRENDERTOSURFACE* ppRenderToSurface
);

파라미터

pDevice
[in] 렌더링 표면에 관련지을 수 있는 디바이스인,IDirect3DDevice8 인터페이스에의 포인터.
Width
[in] 렌더링 표면의 폭 (픽셀 단위).
Height
[in] 렌더링 표면의 높이 (픽셀 단위).
Format
[in] 렌더링 표면의 픽셀 포맷을 기술하는,D3DFORMAT 열거형의 멤버.
DepthStencil
[in] TRUE 의 경우, 렌더링 표면은 스텐실 표면을 지원 한다. 그렇지 않은 경우, 이 멤버는 FALSE 로 설정된다.
DepthStencilFormat
[in] DepthStencil 가 TRUE 로 설정되는 경우, 이 파라미터는, 렌더링 표면의 스텐실 포맷을 기술하는 D3DFORMAT 열거형의 멤버이다.
ppRenderToSurface
[out] 생성 된 렌더링 표면을 나타내는,ID3DXRenderToSurface 인터페이스에의 포인터의 주소.

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateSprite

스프라이트 오브젝트를 생성 한다.

HRESULT D3DXCreateSprite(
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXSPRITE* ppSprite
);

파라미터

pDevice
[in] 스프라이트에 관련지을 수 있는 디바이스인,IDirect3DDevice8 인터페이스에의 포인터.
ppSprite
[out] 생성 된 스프라이트를 나타내는 ID3DXSprite 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXGetErrorStringA

HRESULT 에 대해 ANSI 에러 캐릭터 라인을 돌려준다.

HRESULT D3DXGetErrorStringA(
  HRESULT hr,
  LPSTR pBuffer,
  UINT BufferLen
);

파라미터

hr
[in] 해독 대상의 지정된 HRESULT 에러 코드.
pBuffer
[out] ANSI 에러 캐릭터 라인으로 묻는 버퍼에의 포인터.
BufferLen
[in] 버퍼내의 문자수. 이 값보다 긴 에러 메세지는 잘라 버릴 수 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

D3DXGetErrorString 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXGetErrorStringA 또는 D3DXGetErrorStringW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXGetErrorString 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXGetErrorString D3DXGetErrorStringW
#else
#define D3DXGetErrorString D3DXGetErrorStringA
#endif

이 함수는, 모든 Microsoft® Direct3D® HRESULTS 를 해석한다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXGetErrorStringW


D3DXGetErrorStringW

HRESULT 에 대해 Unicode 에러 캐릭터 라인을 돌려준다.

HRESULT D3DXGetErrorStringW(
  HRESULT hr,
  LPWSTR pBuffer,
  UINT BufferLen
);

파라미터

hr
[in] 해독 대상의 지정된 HRESULT 에러 코드.
pBuffer
[out] Unicode 에러 캐릭터 라인으로 묻는 버퍼에의 포인터.
BufferLen
[in] 버퍼내의 문자수. 이 값보다 긴 에러 메세지는 잘라 버릴 수 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

이 함수는, 모든 Microsoft® Direct3D® HRESULTS 를 해석한다.

D3DXGetErrorString 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXGetErrorStringA 또는 D3DXGetErrorStringW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXGetErrorString 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXGetErrorString D3DXGetErrorStringW
#else
#define D3DXGetErrorString D3DXGetErrorStringA
#endif

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXGetErrorStringA


D3DXGetFVFVertexSize

유연한 버텍스 포맷용으로 버텍스의 사이즈를 돌려준다.

UINT D3DXGetFVFVertexSize(
  DWORD FVF
);

파라미터

FVF
[in] 조회 대상의 유연한 버텍스 포맷. 유연한 버텍스 포맷 플래그의 편성.

반환값

유연한 버텍스 포맷의 버텍스의 사이즈 (바이트 단위).

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


산술 함수

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 산술 라이브러리에는, 기본적인 산술 연산과 복잡한 3D 산술 연산의 양쪽 모두를 계산하는 함수가 있다.

3D 산술 어플리케이션 함수는, 이하의 그룹에 정리할 수가 있다.

칼라 | D3DXColorAdd
 | D3DXColorAdjustContrast
 | D3DXColorAdjustSaturation
 | D3DXColorLerp
 | D3DXColorModulate
 | D3DXColorNegative
 | D3DXColorScale
 | D3DXColorSubtract
생성 | D3DXCreateMatrixStack
평면 | D3DXPlaneDot
 | D3DXPlaneDotCoord
 | D3DXPlaneDotNormal
 | D3DXPlaneIntersectLine
 | D3DXPlaneFromPointNormal
 | D3DXPlaneNormalize
 | D3DXPlaneFromPoints
 | D3DXPlaneTransform
쿠오타니온 | D3DXQuaternionBaryCentric
 | D3DXQuaternionConjugate
 | D3DXQuaternionDot
 | D3DXQuaternionExp
 | D3DXQuaternionIdentity
 | D3DXQuaternionInverse
 | D3DXQuaternionIsIdentity
 | D3DXQuaternionLength
 | D3DXQuaternionLengthSq
 | D3DXQuaternionLn
 | D3DXQuaternionMultiply
 | D3DXQuaternionNormalize
 | D3DXQuaternionRotationAxis
 | D3DXQuaternionRotationMatrix
 | D3DXQuaternionRotationYawPitchRoll
 | D3DXQuaternionSlerp
 | D3DXQuaternionSquad
 | D3DXQuaternionToAxisAngle
2D 벡터 | D3DXVec2Add
 | D3DXVec2BaryCentric
 | D3DXVec2CatmullRom
 | D3DXVec2CCW
 | D3DXVec2Dot
 | D3DXVec2Hermite
 | D3DXVec2Length
 | D3DXVec2LengthSq
 | D3DXVec2Lerp
 | D3DXVec2Maximize
 | D3DXVec2Minimize
 | D3DXVec2Normalize
 | D3DXVec2Scale
 | D3DXVec2Subtract
 | D3DXVec2Transform
 | D3DXVec2TransformCoord
 | D3DXVec2TransformNormal
3D 벡터 | D3DXVec3Add
 | D3DXVec3BaryCentric
 | D3DXVec3CatmullRom
 | D3DXVec3Cross
 | D3DXVec3Dot
 | D3DXVec3Hermite
 | D3DXVec3Length
 | D3DXVec3LengthSq
 | D3DXVec3Lerp
 | D3DXVec3Maximize
 | D3DXVec3Minimize
 | D3DXVec3Normalize
 | D3DXVec3Project
 | D3DXVec3Scale
 | D3DXVec3Subtract
 | D3DXVec3Transform
 | D3DXVec3TransformCoord
 | D3DXVec3TransformNormal
 | D3DXVec3Unproject
4D 행렬 | D3DXMatrixAffineTransformation
 | D3DXMatrixfDeterminant
 | D3DXMatrixIdentity
 | D3DXMatrixInverse
 | D3DXMatrixIsIdentity
 | D3DXMatrixLookAtRH
 | D3DXMatrixLookAtLH
 | D3DXMatrixMultiply
 | D3DXMatrixOrthoRH
 | D3DXMatrixOrthoLH
 | D3DXMatrixOrthoOffCenterRH
 | D3DXMatrixOrthoOffCenterLH
 | D3DXMatrixPerspectiveRH
 | D3DXMatrixPerspectiveLH
 | D3DXMatrixPerspectiveFovRH
 | D3DXMatrixPerspectiveFovLH
 | D3DXMatrixPerspectiveOffCenterRH
 | D3DXMatrixPerspectiveOffCenterLH
 | D3DXMatrixReflect
 | D3DXMatrixRotationAxis
 | D3DXMatrixRotationQuaternion
 | D3DXMatrixRotationX
 | D3DXMatrixRotationY
 | D3DXMatrixRotationYawPitchRoll
 | D3DXMatrixRotationZ
 | D3DXMatrixScaling
 | D3DXMatrixShadow
 | D3DXMatrixTransformation
 | D3DXMatrixTranslation
 | D3DXMatrixTranspose
4D 벡터 | D3DXVec4Add
 | D3DXVec4BaryCentric
 | D3DXVec4CatmullRom
 | D3DXVec4Cross
 | D3DXVec4Dot
 | D3DXVec4Hermite
 | D3DXVec4Length
 | D3DXVec4LengthSq
 | D3DXVec4Lerp
 | D3DXVec4Maximize
 | D3DXVec4Minimize
 | D3DXVec4Normalize
 | D3DXVec4Scale
 | D3DXVec4Subtract
 | D3DXVec4Transform

주 모든 산술 함수는, 입력 파라미터와 출력 파라미터의 양쪽 모두로 같은 오브젝트를 사용할 수 있다. 또, 출력 파라미터는 보통 반환값으로서 돌려주어지므로, 어느 산술 함수의 출력을 다른 산술 함수의 파라미터로서 사용할 수 있다.


D3DXColorAdd

2 종류의 칼라값을 가산해, 새로운 칼라값을 생성 한다.

D3DXCOLOR* D3DXColorAdd(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC1,
  CONST D3DXCOLOR* pC2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC1
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.
pC2
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.

반환값

2 개의 칼라값의 합계인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorAdd 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXColorModulate ,D3DXColorSubtract


D3DXColorAdjustContrast

칼라의 콘트라스트를 조절한다.

D3DXCOLOR* D3DXColorAdjustContrast(
  D3DXCOLOR* pOut,
  D3DXCOLOR* pC,
  FLOAT c
);

파라미터

pOut
[in, out] 연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.
c
[in] 콘트라스트값. 이 파라미터는,50% 회색과 지정 칼라 pC 의 사이에 선형 보간 한다. c 값에 제한값은 없다. 이 파라미터가 0 의 경우, 돌려주어지는 색은 50% 회색이다. 이 파라미터가 1 의 경우, 돌려주어지는 색은 오리지날 칼라이다.

반환값

이 함수는, 콘트라스트 조정 결과의 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorAdjustContrast 함수를 다른 함수의 파라미터로서 사용할 수 있다.

다음의 예로 가리키도록(듯이), 이 함수는 50% 회색과 지정 콘트라스트값의 사이에 D3DXCOLOR 구조체의 적 (red), 초록 (green), 파랑 (blue)의 색성분을 보간 한다.

    pOut->r = 0.5f + c * (pC->r - 0.5f);

c 가 0 보다 크고 1 미만의 경우, 콘트라스트는 작아진다. c 가 1 보다 큰 경우, 콘트라스트는 커진다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXColorAdjustSaturation


D3DXColorAdjustSaturation

칼라의 채도값을 조절한다.

D3DXCOLOR* D3DXColorAdjustSaturation(
  D3DXCOLOR* pOut,
  D3DXCOLOR* pC,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.
s
[in] 채도값. 이 파라미터는, 그레이 스케일에 변환된 색과 오리지날 칼라 pC 의 사이에 선형 보간 한다. s 값에 제한값은 없다. s 가 0 의 경우, 돌려주어지는 색은 그레이 스케일의 색이다. s 가 1 의 경우, 돌려주어지는 색은 오리지날 칼라이다.

반환값

이 함수는, 채도 조정 결과의 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorAdjustSaturation 함수를 다른 함수의 파라미터로서 사용할 수 있다.

다음에 나타내는 예의 같게, 이 함수는 미포화색과 있는 칼라의 사이에 D3DXCOLOR 구조체의 적 (red), 초록 (green), 파랑 (blue)의 색성분을 보간 한다.

    // 휘도에 대한 각 성분의 계수의 적절한 값.
    // ITU-R 권고 BT. 709 에 기재된 NTSC 표준에 근거한다.
    FLOAT grey = pC->r * 0.2125f + pC->g * 0.7154f + pC->b * 0.0721f;

    pOut->r = grey + s * (pC->r - grey);

s 가 0 보다 크고 1 미만의 경우, 채도는 작아진다. s 가 1 보다 큰 경우, 채도는 커진다.

그레이 스케일 칼라는 다음과 같이 해 계산된다. r = g = b = 0.2125*r + 0.7154*g + 0.0721*b

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXColorAdjustContrast


D3DXColorLerp

선형 보간을 사용해 칼라값을 생성 한다.

D3DXCOLOR* D3DXColorLerp(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC1,
  CONST D3DXCOLOR* pC2,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC1
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.
pC2
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.
s
[in] pC1 와 pC2 의 2 개의 색을 양쪽 모두 4D 벡터로서 처리해, 그러한 사이에 선형 보간 하는 파라미터. s 값에 제한값은 없다.

반환값

이 함수는, 선형 보간 결과의 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorLerp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

다음에 나타내는 예의 같게, 이 함수는 2 개의 색의 사이에 D3DXCOLOR 구조체의 적 (red), 초록 (green), 파랑 (blue)의 색성분과 알파 성분을 보간 한다.

    pOut->r = pC1->r + s * (pC2->r - pC1->r);

A 칼라와 B 칼라의 사이에 선형 보간 하는 경우에,s 가 0 때, 결과 칼라는 A 가 된다. s 가 1 때, 결과 칼라는 B 가 된다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXColorModulate ,D3DXColorNegative ,D3DXColorScale


D3DXColorModulate

2 종류의 칼라를 브렌드 한다.

D3DXCOLOR* D3DXColorModulate(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC1,
  CONST D3DXCOLOR* pC2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC1
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.
pC2
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.

반환값

이 함수는, 브렌드 결과인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorModulate 함수를 다른 함수의 파라미터로서 사용할 수 있다.

다음의 예에 나타내도록(듯이), 이 함수는 대응하는 2 개의 색성분의 적을 요구해 2 종류의 칼라를 브렌드 한다.

    pOut->r = pC1->r * pC2->r;

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXColorLerp ,D3DXColorNegative ,D3DXColorScale


D3DXColorNegative

어느 칼라값의 부의 색을 생성 한다.

D3DXCOLOR* D3DXColorNegative(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC
);

파라미터

pOut
[in, out] 연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.

반환값

이 함수는, 칼라값의 부의 색인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorNegative 함수를 다른 함수의 파라미터로서 사용할 수 있다.

다음의 예에 나타내도록(듯이), 이 함수는 D3DXCOLOR 구조체의 색성분으로부터 1.0 을 감산하는 것으로, 부의 칼라값을 돌려준다.

    pOut->r = 1.0f - pC->r;

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXColorLerp ,D3DXColorModulate ,D3DXColorScale


D3DXColorScale

칼라값을 스케일링 한다.

D3DXCOLOR* D3DXColorScale(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.
s
[in] 스케일링 계수. 색을 4D 벡터와 같이 처리해, 그것을 스케일링 한다. s 값에 제한값은 없다. s 가 1 의 경우, 돌려주어지는 색은 오리지날 칼라이다.

반환값

이 함수는, 스케일링 된 칼라값인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorScale 함수를 다른 함수의 파라미터로서 사용할 수 있다.

다음의 예에 나타내도록(듯이), 이 함수는,D3DXCOLOR 구조체의 색성분으로 지정된 스케일링 계수를 곱셈하는 것으로, 스케일링 한 칼라값을 산출한다.

    pOut->r = pC->r * s;

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXColorLerp ,D3DXColorModulate ,D3DXColorNegative


D3DXColorSubtract

2 종류의 칼라값의 사이에 감산을 실시해, 새로운 칼라값을 생성 한다.

D3DXCOLOR* D3DXColorSubtract(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC1,
  CONST D3DXCOLOR* pC2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC1
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.
pC2
[in] 처리의 기본으로 되는 D3DXCOLOR 구조체에의 포인터.

반환값

이 함수는, 2 개의 칼라값의 차분인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorSubtract 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXColorAdd


D3DXCreateMatrixStack

ID3DXMatrixStack 인터페이스의 인스턴스를 생성 한다.

HRESULT D3DXCreateMatrixStack(
  DWORD Flags,
  ID3DXMatrixStack** ppStack
);

파라미터

Flags
[in] 이행되어 있지 않다. 0 을 지정하는 것.
ppStack
[out] 함수가 성공했을 경우는,ID3DXMatrixStack 인터페이스 포인터가 설정되는 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXMatrixAffineTransformation

아핀 변환 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixAffineTransformation(
  D3DXMATRIX* pOut,
  FLOAT scaling,
  CONST D3DXVECTOR3* pRotationCenter,
  CONST D3DXQUATERNION* pRotation,
  CONST D3DXVECTOR3* pTranslation
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
scaling
[in] 스케일링 계수.
pRotationCenter
[in] 회전의 중심을 식별하는 포인트인 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우는, 회전하지 않다고 보여진다.
pRotation
[in] 회전을 지정하는 D3DXQUATERNION 구조체에의 포인터. 이 인수가 NULL 의 경우는, 회전하지 않다고 보여진다.
pTranslation
[in] 평행이동을 나타내는 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우는, 평행이동 하지 않다고 보여진다.

반환값

아핀 변환 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixAffineTransformation 함수는, Ms * Mrc-1 * Mr * Mrc * Mt 식에 의해 아핀 변환 행렬을 산출한다. 여기서, Ms 는 스케일 행렬, Mrc 는 회전 행렬의 중심, Mr 는 회전 행렬, Mt 는 평행이동 행렬이다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixAffineTransformation 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXMatrixfDeterminant

행렬의 행렬식을 돌려준다.

FLOAT D3DXMatrixfDeterminant(
  CONST D3DXMATRIX* pM
);

파라미터

pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

행렬의 값, 행렬식.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXMatrixIdentity

단위행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixIdentity(
  D3DXMATRIX* pOut
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.

반환값

단위행렬인 D3DXMATRIX 구조체에의 포인터.

주의

단위행렬은,[1,1][2,2][3,3][4,4] 계수에 1 이 설정되어 있는 것을 제외해, 모든 계수가 0 의 행렬이다. 단위행렬은, 버텍스에 적용되어도 그것들이 변경되지 않는다고 하는 점으로써 특별하다. 단위행렬은, 버텍스값을 변경해 회전, 평행이동, 및 4 × 4 행렬로 표현할 수 있는 그 외의 변환을 실시하는 행렬의 기점으로서 사용된다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixIdentity 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixIsIdentity


D3DXMatrixInverse

행렬의 역원을 산출한다.

D3DXMATRIX* D3DXMatrixInverse(
  D3DXMATRIX* pOut,
  FLOAT* pDeterminant,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pDeterminant
[in, out] 이 함수가 돌아온 후의, 지정된 행렬 pM 의 행렬값인 FLOAT 값에 대한 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

행렬의 역원인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수에서는, 임의의 행렬을 사용할 수 있다.

행렬의 역변환이 실패 하면,D3DXMatrixInverse 함수로부터 NULL 가 돌려주어진다. pDeterminant 파라미터가 NULL 이외의 경우는 pM 의 행렬값이 돌려주어진다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixInverse 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXMatrixIsIdentity

행렬이 단위행렬일지 어떨지를 판정한다.

BOOL D3DXMatrixIsIdentity(
  CONST D3DXMATRIX* pM
);

파라미터

pM
[in] 단위행렬일지 어떨지를 판정하는 D3DXMATRIX 구조체에의 포인터.

반환값

행렬이 단위행렬인 경우, 이 함수는 TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixIdentity


D3DXMatrixLookAtRH

오른손 좌표계 뷰 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixLookAtRH(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR3* pEye,
  CONST D3DXVECTOR3* pAt,
  CONST D3DXVECTOR3* pUp
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pEye
[in] 시점을 정의한 D3DXVECTOR3 구조체에의 포인터. 이 값은, 평행이동에 사용된다.
pAt
[in] 카메라의 주시 대상을 정의한 D3DXVECTOR3 구조체에의 포인터.
pUp
[in] 경향 월드의 윗쪽, 일반적으로는 [0, 1, 0] 을 정의한 D3DXVECTOR3 구조체에의 포인터.

반환값

오른손 좌표계 뷰 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixLookAtRH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixLookAtLH


D3DXMatrixLookAtLH

왼손 좌표계 뷰 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixLookAtLH(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR3* pEye,
  CONST D3DXVECTOR3* pAt,
  CONST D3DXVECTOR3* pUp
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pEye
[in] 시점을 정의한 D3DXVECTOR3 구조체에의 포인터. 이 값은, 평행이동에 사용된다.
pAt
[in] 카메라의 주시 대상을 정의한 D3DXVECTOR3 구조체에의 포인터.
pUp
[in] 경향 월드의 윗쪽, 일반적으로는 [0, 1, 0] 을 정의한 D3DXVECTOR3 구조체에의 포인터.

반환값

왼손 좌표계 뷰 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixLookAtLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixLookAtRH


D3DXMatrixMultiply

2 개의 행렬의 적을 산출한다.

D3DXMATRIX* D3DXMatrixMultiply(
  D3DXMATRIX* pOut,
  CONST D3DXMATRIX* pM1,
  CONST D3DXMATRIX* pM2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pM1
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.
pM2
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

2 개의 행렬의 적인 D3DXMATRIX 구조체에의 포인터.

주의

결과는, 변환 M1 후의 변환 M2 의 결과를 나타낸다 (Out = M1 * M2).

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixMultiply 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionMultiply


D3DXMatrixOrthoRH

오른손 좌표계 정사영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixOrthoRH(
  D3DXMATRIX* pOut,
  FLOAT w,
  FLOAT h,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
w
[in] 뷰 볼륨의 폭.
h
[in] 뷰 볼륨의 높이.
zn
[in] 뷰 볼륨의 최소 z 값.
zf
[in] 뷰 볼륨의 최대 z 값.

반환값

오른손 좌표계 정사영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

정사영 행렬은 반전 가능한 행렬이다. 그 행렬의 반전은, 행렬의 전치에 동일하다.

D3DXMatrixOrthoRH 함수의 파라미터는 모두, 카메라 공간의 거리이다. 이 파라미터는, 뷰 볼륨의 넓이를 기술한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixOrthoRH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 으로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixOrthoLH ,D3DXMatrixOrthoOffCenterRH ,D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoLH

왼손 좌표계 정사영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixOrthoLH(
  D3DXMATRIX* pOut,
  FLOAT w,
  FLOAT h,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
w
[in] 뷰 볼륨의 폭.
h
[in] 뷰 볼륨의 높이.
zn
[in] 뷰 볼륨의 최소 z 값.
zf
[in] 뷰 볼륨의 최대 z 값.

반환값

왼손 좌표계 정사영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

정사영 행렬은 반전 가능한 행렬이다. 그 행렬의 반전은, 행렬의 전치에 동일하다.

D3DXMatrixOrthoLH 함수의 파라미터는 모두, 카메라 공간의 거리이다. 이 파라미터는, 뷰 볼륨의 넓이를 기술한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixOrthoLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixOrthoRH ,D3DXMatrixOrthoOffCenterRH ,D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenterRH

커스터마이즈 한 오른손 좌표계 정사영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixOrthoOffCenterRH(
  D3DXMATRIX* pOut,
  FLOAT l,
  FLOAT r,
  FLOAT t,
  FLOAT b,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
l
[in] 뷰 볼륨의 최소 x 값.
r
[in] 뷰 볼륨의 최대 x 값.
t
[in] 뷰 볼륨의 최소 y 값.
b
[in] 뷰 볼륨의 최대 y 값.
zn
[in] 뷰 볼륨의 최소 z 값.
zf
[in] 뷰 볼륨의 최대 z 값.

반환값

커스터마이즈 한 오른손 좌표계 정사영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

정사영 행렬은 반전 가능한 행렬이다. 그 행렬의 반전은, 행렬의 전치에 동일하다.

D3DXMatrixOrthoRH 함수는,D3DXMatrixOrthoOffCenterRH 함수의 특수한 케이스이다. D3DXMatrixOrthoOffCenterRH 를 사용해 같은 투영을 생성 하려면 ,l = -w/2,r = w/2,b = -h/2,t = h/2 라고 하는 값을 사용하는 것.

D3DXMatrixOrthoOffCenterRH 함수의 파라미터는 모두, 카메라 공간의 거리이다. 이 파라미터는, 뷰 볼륨의 넓이를 기술한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixOrthoOffCenterRH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixOrthoRH ,D3DXMatrixOrthoLH ,D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenterLH

커스터마이즈 한 왼손 좌표계 정사영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixOrthoOffCenterLH(
  D3DXMATRIX* pOut,
  FLOAT l,
  FLOAT r,
  FLOAT t,
  FLOAT b,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
l
[in] 뷰 볼륨의 최소 x 값.
r
[in] 뷰 볼륨의 최대 x 값.
t
[in] 뷰 볼륨의 최소 y 값.
b
[in] 뷰 볼륨의 최대 y 값.
zn
[in] 뷰 볼륨의 최소 z 값.
zf
[in] 뷰 볼륨의 최대 z 값.

반환값

커스터마이즈 한 왼손 좌표계 정사영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

정사영 행렬은 반전 가능한 행렬이다. 그 행렬의 반전은, 행렬의 전치에 동일하다.

D3DXMatrixOrthoLH 함수는,D3DXMatrixOrthoOffCenterLH 함수의 특수한 케이스이다. D3DXMatrixOrthoOffCenterLH 를 사용해 같은 투영을 생성 하려면 ,l = -w/2,r = w/2,b = -h/2,t = h/2 라고 하는 값을 사용하는 것.

D3DXMatrixOrthoOffCenterLH 함수의 파라미터는 모두, 카메라 공간의 거리이다. 이 파라미터는, 뷰 볼륨의 넓이를 기술한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixOrthoOffCenterLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixOrthoRH ,D3DXMatrixOrthoLH ,D3DXMatrixOrthoOffCenterRH


D3DXMatrixPerspectiveRH

오른손 좌표계 퍼스펙티브 투영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixPerspectiveRH(
  D3DXMATRIX* pOut,
  FLOAT w,
  FLOAT h,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
w
[in] 가까이의 뷰 프레인에서의 뷰 볼륨의 폭.
h
[in] 가까이의 뷰 프레인에서의 뷰 볼륨의 높이.
zn
[in] 가까이의 뷰 프레인의 z 값.
zf
[in] 먼 뷰 프레인의 z 값.

반환값

오른손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixPerspectiveRH 함수의 파라미터는 모두, 카메라 공간의 거리이다. 이 파라미터는, 뷰 볼륨의 넓이를 기술한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveRH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFovRH ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenterRH ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFovLH

시야 (FOV)에 근거해, 왼손 좌표계 퍼스펙티브 투영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixPerspectiveFovLH(
  D3DXMATRIX* pOut,
  FLOAT fovy,
  FLOAT Aspect,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
fovy
[in] 시야 (라디안 단위).
Aspect
[in] 어스펙트비(가로세로 비율).
zn
[in] 가까이의 뷰 프레인의 z 값.
zf
[in] 먼 뷰 프레인의 z 값.

반환값

왼손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveFovLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixPerspectiveRH ,D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFovRH ,D3DXMatrixPerspectiveOffCenterRH ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFovRH

시야 (FOV)에 근거해, 오른손 좌표계 퍼스펙티브 투영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixPerspectiveFovRH(
  D3DXMATRIX* pOut,
  FLOAT fovy,
  FLOAT Aspect,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
fovy
[in] 시야 (라디안 단위).
Aspect
[in] 어스펙트비(가로세로 비율).
zn
[in] 가까이의 뷰 프레인의 z 값.
zf
[in] 먼 뷰 프레인의 z 값.

반환값

오른손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveFovRH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixPerspectiveRH ,D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenterRH ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveLH

왼손 좌표계 퍼스펙티브 투영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixPerspectiveLH(
  D3DXMATRIX* pOut,
  FLOAT w,
  FLOAT h,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
w
[in] 가까이의 뷰 프레인에서의 뷰 볼륨의 폭.
h
[in] 가까이의 뷰 프레인에서의 뷰 볼륨의 높이.
zn
[in] 가까이의 뷰 프레인의 z 값.
zf
[in] 먼 뷰 프레인의 z 값.

반환값

왼손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixPerspectiveLH 함수의 파라미터는 모두, 카메라 공간의 거리이다. 이 파라미터는, 뷰 볼륨의 넓이를 기술한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixPerspectiveRH ,D3DXMatrixPerspectiveFovRH ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenterRH ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenterRH

커스터마이즈 한 오른손 좌표계 퍼스펙티브 투영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixPerspectiveOffCenterRH(
  D3DXMATRIX* pOut,
  FLOAT l,
  FLOAT r,
  FLOAT t,
  FLOAT b,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 조작 결과의 D3DXMATRIX 구조체에의 포인터.
l
[in] 뷰 볼륨의 최소 X 값.
r
[in] 뷰 볼륨의 최대 X 값.
t
[in] 뷰 볼륨의 최소 Y 값.
b
[in] 뷰 볼륨의 최대 Y 값.
zn
[in] 뷰 볼륨의 최소 Z 값.
zf
[in] 뷰 볼륨의 최대 Z 값.

반환값

오른손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixPerspectiveOffCenterRH 함수의 파라미터는 모두, 카메라 공간의 거리이다. 이 파라미터는, 뷰 볼륨의 넓이를 기술한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveOffCenterRH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixPerspectiveRH ,D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFovRH ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenterLH

커스터마이즈 한 왼손 좌표계 퍼스펙티브 투영 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixPerspectiveOffCenterLH(
  D3DXMATRIX* pOut,
  FLOAT l,
  FLOAT r,
  FLOAT t,
  FLOAT b,
  FLOAT zn,
  FLOAT zf
);

파라미터

pOut
[in, out] 조작 결과의 D3DXMATRIX 구조체에의 포인터.
l
[in] 뷰 볼륨의 최소 X 값.
r
[in] 뷰 볼륨의 최대 X 값.
t
[in] 뷰 볼륨의 최소 Y 값.
b
[in] 뷰 볼륨의 최대 Y 값.
zn
[in] 뷰 볼륨의 최소 Z 값.
zf
[in] 뷰 볼륨의 최대 Z 값.

반환값

왼손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixPerspectiveOffCenterLH 함수의 파라미터는 모두, 카메라 공간의 거리이다. 이 파라미터는, 뷰 볼륨의 넓이를 기술한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveOffCenterLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixPerspectiveRH ,D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFovRH ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenterRH


D3DXMatrixReflect

평면의 좌표계를 반전한 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixReflect(
  D3DXMATRIX* pOut,
  CONST D3DXPLANE* pPlane
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pPlane
[in] 처리의 기본으로 되는 D3DXPLANE 구조체에의 포인터.

반환값

소스의 평면의 좌표계를 반전한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수는, 평면 방정식을 정규화하고 나서, 반전하는 행렬을 생성 한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixReflect 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXMatrixRotationAxis

임의의 축을 회전축으로서 회전한 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixRotationAxis(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR3* pV,
  FLOAT Angle
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pV
[in] 축의 각도를 식별하는 D3DXVECTOR3 구조체에의 포인터.
Angle
[in] 회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

지정된 축을 회전축으로서 회전한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationAxis 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixRotationQuaternion ,D3DXMatrixRotationX ,D3DXMatrixRotationY ,D3DXMatrixRotationYawPitchRoll ,D3DXMatrixRotationZ


D3DXMatrixRotationQuaternion

쿠오타니온으로부터 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixRotationQuaternion(
  D3DXMATRIX* pOut,
  CONST D3DXQUATERNION* pQ
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pQ
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

소스의 쿠오타니온으로부터 구축된 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationQuaternion 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationX ,D3DXMatrixRotationY ,D3DXMatrixRotationYawPitchRoll ,D3DXMatrixRotationZ


D3DXMatrixRotationX

x 축을 회전축으로서 회전한 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixRotationX(
  D3DXMATRIX* pOut,
  FLOAT Angle
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
Angle
[in] 회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

x 축을 회전축으로서 회전한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationX 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationQuaternion ,D3DXMatrixRotationY ,D3DXMatrixRotationYawPitchRoll ,D3DXMatrixRotationZ


D3DXMatrixRotationY

y 축을 회전축으로서 회전한 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixRotationY(
  D3DXMATRIX* pOut,
  FLOAT Angle
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
Angle
[in] 회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

y 축을 회전축으로서 회전한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationY 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationQuaternion ,D3DXMatrixRotationX ,D3DXMatrixRotationYawPitchRoll ,D3DXMatrixRotationZ


D3DXMatrixRotationYawPitchRoll

요, 피치, 및 롤을 지정해 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixRotationYawPitchRoll(
  D3DXMATRIX* pOut,
  FLOAT Yaw,
  FLOAT Pitch,
  FLOAT Roll,
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
Yaw
[in] y 축의 요 (라디안 단위).
Pitch
[in] x 축의 피치 (라디안 단위).
Roll
[in] z 축의 롤 (라디안 단위).

반환값

지정된 요, 피치, 및 롤을 가지는 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationYawPitchRoll 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationQuaternion ,D3DXMatrixRotationX ,D3DXMatrixRotationY ,D3DXMatrixRotationZ


D3DXMatrixRotationZ

z 축을 회전축으로서 회전한 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixRotationZ(
  D3DXMATRIX* pOut,
  FLOAT Angle
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
Angle
[in] 회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

z 축을 회전축으로서 회전한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationZ 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationQuaternion ,D3DXMatrixRotationX ,D3DXMatrixRotationY ,D3DXMatrixRotationYawPitchRoll


D3DXMatrixScaling

x 축, y 축, z 축으로 따라 스케일링 한 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixScaling(
  D3DXMATRIX* pOut,
  FLOAT sx,
  FLOAT sy,
  FLOAT sz,
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
sx
[in] x 축으로 따라 적용되는 스케일링 계수.
sy
[in] y 축으로 따라 적용되는 스케일링 계수.
sz
[in] z 축으로 따라 적용되는 스케일링 계수.

반환값

스케일링 된 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixScaling 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXMatrixShadow

지오메트리를 평면에 투영 하는 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixShadow(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR4* pLight,
  CONST D3DXPLANE* pPlane
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pLight
[in] 라이트의 위치를 기술한 D3DXVECTOR4 구조체에의 포인터.
pPlane
[in] 처리의 기본으로 되는 D3DXPLANE 구조체에의 포인터.

반환값

지오메트리를 평면에 투영 하는 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixShadow 함수는, 라이트로부터 그림자를 투영 하도록(듯이), 지오메트리를 평면에 투영 한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixShadow 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXMatrixTransformation

트랜스 폼 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixTransformation(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR3* pScalingCenter,
  CONST D3DXQUATERNION* pScalingRotation,
  CONST D3DXVECTOR3* pScaling,
  CONST D3DXVECTOR3* pRotationCenter,
  CONST D3DXQUATERNION* pRotation,
  CONST D3DXVECTOR3* pTranslation,
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pScalingCenter
[in] 스케일링의 중심점을 식별하는 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우는, 스케일 하지 않다고 보여진다.
pScalingRotation
[in] 스케일링의 회전을 지정하는 D3DXQUATERNION 구조체에의 포인터. 이 인수가 NULL 의 경우는, 스케일 하지 않다고 보여진다.
pScaling
[in] 스케일링 벡터인 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우는, 스케일 하지 않다고 보여진다.
pRotationCenter
[in] 회전의 중심을 식별하는 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우는, 회전하지 않다고 보여진다.
pRotation
[in] 회전을 지정하는 D3DXQUATERNION 구조체에의 포인터. 이 인수가 NULL 의 경우는, 회전하지 않다고 보여진다.
pTranslation
[in] 평행이동을 나타내는 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우는, 평행이동 하지 않다고 보여진다.

반환값

트랜스 폼 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixTransformation 함수는, Msc-1 * Msr-1 * Ms * Msr * Msc * Mrc-1 * Mr * Mrc * Mt 라고 하는 식에 의해 트랜스 폼 행렬을 계산한다. 다만, Msc 는 중심의 스케일링 행렬, Msr 는 스케일링 회전 행렬, Ms 는 스케일링 행렬, Mrc 는 회전 행렬의 중심, Mr 는 회전 행렬, Mt 는 평행이동 행렬이다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixTransformation 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixAffineTransformation


D3DXMatrixTranslation

오프셋(offset)를 지정해 행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixTranslation(
  D3DXMATRIX* pOut,
  FLOAT x,
  FLOAT y,
  FLOAT z,
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
x
[in] x 좌표의 오프셋(offset).
y
[in] y 좌표의 오프셋(offset).
z
[in] z 좌표의 오프셋(offset).

반환값

평행이동 된 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixTranslation 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXMatrixTranspose

행렬의 전치행렬을 돌려준다.

D3DXMATRIX* D3DXMatrixTranspose(
  D3DXMATRIX* pOut,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXMATRIX 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

행렬의 전치행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixTranspose 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXPlaneDot

평면과 4D 벡터의 내적을 산출한다.

FLOAT D3DXPlaneDot(
  CONST D3DXPLANE* pP,
  CONST D3DXVECTOR4* pV
);

파라미터

pP
[in] 처리의 기본으로 되는 D3DXPLANE 구조체에의 포인터.
pV
[in] D3DXVECTOR4 구조체에의 포인터.

반환값

평면과 4D 벡터의 내적.

주의

평면 (a, b, c, d)과 4D 벡터 (x, y, z, w)를 지정했을 경우, 이 함수의 반환값은 a*x + b*y + c*z + d*w 가 된다. D3DXPlaneDot 함수는, 평면과 동차 좌표의 관계를 판단할 때 유용하다. 예를 들어, 이 함수를 사용하면, 특정의 좌표가 특정의 평면상에 있을지 어떨지, 또는 특정의 좌표가 특정의 평면의 어느 쪽 측에 있을까를 판단할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXPlaneDotCoord ,D3DXPlaneDotNormal


D3DXPlaneDotCoord

평면과 3D 벡터의 내적을 산출한다. 벡터의 w 파라미터는, 1 이다고 보여진다.

FLOAT D3DXPlaneDotCoord(
  CONST D3DXPLANE* pP,
  CONST D3DXVECTOR3* pV
);

파라미터

pP
[in] 처리의 기본으로 되는 D3DXPLANE 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

평면과 3D 벡터의 내적.

주의

평면 (a, b, c, d)과 3D 벡터 (x, y, z)를 지정했을 경우, 이 함수의 반환값은 a*x + b*y + c*z + d*1 가 된다. D3DXPlaneDotCoord 함수는, 평면과 3D 공간의 좌표의 관계를 판단할 때 유용하다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXPlaneDot ,D3DXPlaneDotNormal


D3DXPlaneDotNormal

평면과 3D 벡터의 내적을 산출한다. 벡터의 w 파라미터는, 0 이다고 보여진다.

FLOAT D3DXPlaneDotNormal(
  CONST D3DXPLANE* pP,
  CONST D3DXVECTOR3* pV
);

파라미터

pP
[in] 처리의 기본으로 되는 D3DXPLANE 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

평면과 3D 벡터의 내적.

주의

평면 (a, b, c, d)과 3D 벡터 (x, y, z)를 지정했을 경우, 이 함수의 반환값은 a*x + b*y + c*z + d*0 가 된다. D3DXPlaneDotNormal 함수는, 평면의 법선과 다른 평면의 각도를 계산할 경우에 유용하다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXPlaneDot ,D3DXPlaneDotCoord


D3DXPlaneFromPointNormal

포인트와 법선으로부터 평면을 생성 한다.

D3DXPLANE* D3DXPlaneFromPointNormal(
  D3DXPLANE* pOut,
  CONST D3DXVECTOR3* pPoint,
  CONST D3DXVECTOR3* pNormal
);

파라미터

pOut
[in, out] 연산 결과인 D3DXPLANE 구조체에의 포인터.
pPoint
[in] 평면의 생성에 사용하는 포인트를 정의하는 D3DXVECTOR3 구조체에의 포인터.
pNormal
[in] 평면의 생성에 사용하는 법선을 정의하는 D3DXVECTOR3 구조체에의 포인터.

반환값

포인트와 법선으로부터 생성 한 D3DXPLANE 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXPlaneFromPointNormal 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXPlaneFromPoints


D3DXPlaneFromPoints

3 개의 점으로부터 평면을 생성 한다.

D3DXPLANE* D3DXPlaneFromPoints(
  D3DXPLANE* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2,
  CONST D3DXVECTOR3* pV3
);

파라미터

pOut
[in, out] 연산 결과인 D3DXPLANE 구조체에의 포인터.
pV1
[in] 평면의 생성에 사용하는 점 가운데 1 개를 정의하는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 평면의 생성에 사용하는 점 가운데 1 개를 정의하는 D3DXVECTOR3 구조체에의 포인터.
pV3
[in] 평면의 생성에 사용하는 점 가운데 1 개를 정의하는 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 점으로부터 생성 한 D3DXPLANE 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXPlaneFromPoints 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXPlaneFromPointNormal


D3DXPlaneIntersectLine

평면과 직선의 교점을 검색한다.

D3DXVECTOR3* D3DXPlaneIntersectLine(
  D3DXVECTOR3* pOut,
  CONST D3DXPLANE* pP,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

파라미터

pOut
[in, out] 지정된 평면과 직접적인 교점을 식별하는 D3DXVECTOR3 구조체에의 포인터.
pP
[in] 처리의 기본으로 되는 D3DXPLANE 구조체에의 포인터.
pV1
[in] 기점을 정의한, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 종점을 정의한, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 평면과 직선의 교점인 D3DXVECTOR3 구조체에의 포인터.

주의

직선이 평면에 대해서 평행의 경우, NULL 가 돌려주어진다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXPlaneIntersectLine 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXPlaneNormalize

정규화한 평면을 돌려준다.

D3DXPLANE* D3DXPlaneNormalize(
  D3DXPLANE* pOut,
  CONST D3DXPLANE* pP
);

파라미터

pOut
[in, out] 연산 결과인 D3DXPLANE 구조체에의 포인터.
pP
[in] 처리의 기본으로 되는 D3DXPLANE 구조체에의 포인터.

반환값

평면의 법선을 나타내는 D3DXPLANE 구조체에의 포인터.

주의

D3DXPlaneNormalize 는, |a, b, c| == 1 이 되도록(듯이) 평면을 정규화한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXPlaneNormalize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXPlaneTransform

행렬을 지정해 평면을 트랜스 폼 한다.

D3DXPLANE* D3DXPlaneTransform(
  D3DXPLANE* pOut,
  CONST D3DXPLANE* pP,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXPLANE 구조체에의 포인터.
pP
[in] 처리의 기본으로 되는 D3DXPLANE 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

변환된 평면을 나타내는 D3DXPLANE 구조체에의 포인터.

주의

행렬 pM 는, 아핀 변환이 아니면 안된다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXPlaneTransform 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXQuaternionBaryCentric

중심 좌표의 쿠오타니온을 돌려준다.

D3DXQUATERNION* D3DXQuaternionBaryCentric(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2,
  CONST D3DXQUATERNION* pQ3,
  CONST D3DXQUATERNION* pQ4,
  FLOAT f,
  FLOAT g
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ1
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pQ2
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pQ3
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pQ4
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
f
[in] 가중 계수. 「주의」를 참조할것.
g
[in] 가중 계수. 「주의」를 참조할것.

반환값

중심 좌표의 D3DXQUATERNION 구조체에의 포인터.

주의

중심 좌표를 계산하기 위해(때문에),D3DXQuaternionBaryCentric 함수는 다음에 나타내는 구(공)장 선형 보간 연산자를 이행 한다. Slerp(Slerp(Q1, Q2, f+g), Slerp(Q1, Q3, f+g), g/(f+g))

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionBaryCentric 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXQuaternionConjugate

쿠오타니온의 공역을 돌려준다.

D3DXQUATERNION* D3DXQuaternionConjugate(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

쿠오타니온의 공역인 D3DXQUATERNION 구조체에의 포인터.

주의

쿠오타니온 (x, y, z, w)이 지정되었을 경우,D3DXQuaternionConjugate 함수는 쿠오타니온 (-x, -y, -z, w)을 돌려준다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionConjugate 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionInverse


D3DXQuaternionDot

2 개의 쿠오타니온의 내적을 돌려준다.

FLOAT D3DXQuaternionDot(
  D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2
);

파라미터

pQ1
[out] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pQ2
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

2 개의 쿠오타니온의 내적.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXQuaternionExp

지수함수의 계산을 실시한다.

D3DXQUATERNION* D3DXQuaternionExp(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

지수함수인 D3DXQUATERNION 구조체에의 포인터.

주의

D3DXQuaternionExp 함수는,w == 0 의 단일 쿠오타니온에서만 기능한다.

이 함수는, 다음과 같이 이행 된다.

q = (0, theta * v)
exp(q) = (cos(theta), sin(theta) * v)

D3DXQuaternionExp 함수와 D3DXQuaternionLn 함수는,D3DXQuaternionSquad 함수를 사용할때에 유용하다. 다음의 예로 가리키도록(듯이), 쿠오타니온키셋트 (q0, q1, q2, ..., qn)를 지정 하면, 인접 세그먼트(segment)를 또 있고로 접선을 연속시키기 위해서(때문에), 다음과 같이 내부 사각형의 점 (a1, a2, a3, ..., an-1)를 계산할 수 있다.

        a1    a2    a3
  q0    q1    q2    q3    q4

a[i] = q[i] * exp( -(ln(inv(q[i]) *q[i+1]) + ln(inv(q[i]) *q[i-1])) / 4 )

(a1, a2, a3, ...)(이)가 계산되면(자), 이 결과를 사용해, 커브에 따라 보간 할 수 있다.

qt = Squad(t, q[i], a[i], a[i+1], q[i+1])

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionExp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionLn ,D3DXQuaternionSquad


D3DXQuaternionIdentity

단위 쿠오타니온을 돌려준다.

D3DXQUATERNION* D3DXQuaternionIdentity(
  D3DXQUATERNION* pOut
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.

반환값

단위 쿠오타니온인 D3DXQUATERNION 구조체에의 포인터.

주의

쿠오타니온 (x, y, z, w)을 지정했을 경우,D3DXQuaternionIdentity 함수는 쿠오타니온 (0, 0, 0, 1)을 돌려준다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionIdentity 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionIsIdentity


D3DXQuaternionInverse

쿠오타니온을 모두 부려, 재정규화한다.

D3DXQUATERNION* D3DXQuaternionInverse(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

쿠오타니온의 역쿠오타니온인 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionInverse 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionConjugate ,D3DXQuaternionNormalize


D3DXQuaternionIsIdentity

쿠오타니온이 단위 쿠오타니온일지 어떨지를 판정한다.

BOOL D3DXQuaternionIsIdentity(
  CONST D3DXQUATERNION* pQ
);

파라미터

pQ
[in] 단위 쿠오타니온일지 어떨지를 판정하는 D3DXQUATERNION 구조체에의 포인터.

반환값

쿠오타니온이 단위 쿠오타니온의 경우, 이 함수는 TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionIdentity


D3DXQuaternionLength

쿠오타니온의 길이를 돌려준다.

FLOAT D3DXQuaternionLength(
  CONST D3DXQUATERNION* pQ
);

파라미터

pQ
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

쿠오타니온의 길이.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionLengthSq


D3DXQuaternionLengthSq

쿠오타니온의 길이의 2 승을 돌려준다.

FLOAT D3DXQuaternionLengthSq(
  CONST D3DXQUATERNION* pQ
);

파라미터

pQ
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

쿠오타니온의 길이의 2 승.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionLength


D3DXQuaternionLn

자연대수를 계산한다.

D3DXQUATERNION* D3DXQuaternionLn(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

자연대수인 D3DXQUATERNION 구조체에의 포인터.

주의

D3DXQuaternionLn 함수는, 정규화된 쿠오타니온에서만 기능한다.

이 함수는, 다음과 같이 이행 된다.

q = (cos(theta), sin(theta) * v)
|v| = 1
ln(q) = (0, theta * v)

D3DXQuaternionExp 함수와 D3DXQuaternionLn 함수는,D3DXQuaternionSquad 함수를 사용할때 유용하다. 쿠오타니온키셋트 (q0, q1, q2, ..., qn)를 지정 하면, 인접 세그먼트(segment)를 또 있고로 접선을 연속시키기 위해서(때문에), 다음과 같이 내부 사각형의 점 (a1, a2, a3, ..., an-1)를 계산할 수 있다.

        a1    a2    a3
  q0    q1    q2    q3    q4

a[i] = q[i] * exp( -(ln(inv(q[i]) *q[i+1]) + ln(inv(q[i]) *q[i-1])) / 4 )

(a1, a2, a3, ...)(이)가 계산되면(자), 이 결과를 사용해, 커브에 따라 보간 할 수 있다.

qt = Squad(t, q[i], a[i], a[i+1], q[i+1])

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionLn 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionExp ,D3DXQuaternionSquad


D3DXQuaternionMultiply

2 개의 쿠오타니온의 적을 요구한다.

D3DXQUATERNION* D3DXQuaternionMultiply(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ1
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pQ2
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

2 개의 쿠오타니온의 적인 D3DXQUATERNION 구조체에의 포인터.

주의

결과는, 회전 Q1 의 뒤에 회전 Q2 를 실행한 결과를 나타내고 있다 (Out = Q2 * Q1). 실제의 출력은 Q2*Q1 이다 (Q1*Q2 는 아니다). 이와 같이 하면, 회전 행렬을 나타내는 또 다른 방법으로서 정규화된 쿠오타니온을 볼 수가 있으므로,D3DXQuaternionMultiply 함수는 D3DXMatrixMultiply 와 같은 시멘틱스를 보관 유지한다.

D3DXQuaternionMultiply 함수와 D3DXMatrixMultiply 함수의 양쪽 모두, 같은 순서로 변환이 결합된다. 예를 들어, mX 와 mY 가 qX 와 qY 와 같은 회전을 나타내고 있는 것과 가정하면(자), m 와 q 는 양쪽 모두 같은 회전을 나타내게 된다.

D3DXMatrixMultiply(&m, &mX, &mY);

D3DXQuaternionMultiply(&q, &qX, &qY);

쿠오타니온의 적산은, 가환성이 없다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionMultiply 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXMatrixMultiply


D3DXQuaternionNormalize

정규화된 쿠오타니온을 돌려준다.

D3DXQUATERNION* D3DXQuaternionNormalize(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.

반환값

정규화된 쿠오타니온인 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionNormalize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionInverse


D3DXQuaternionRotationAxis

지정한 축을 중심으로 해 쿠오타니온을 회전시킨다.

D3DXQUATERNION* D3DXQuaternionRotationAxis(
  D3DXQUATERNION* pOut,
  CONST D3DXVECTOR3* pV,
  FLOAT Angle
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pV
[in] 축의 각도를 식별하는 D3DXVECTOR3 구조체에의 포인터.
Angle
[in] 회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

지정된 축을 회전축으로서 회전한 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionRotationAxis 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionRotationMatrix ,D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationMatrix

회전 행렬로부터 쿠오타니온을 생성 한다.

D3DXQUATERNION* D3DXQuaternionRotationMatrix(
  D3DXQUATERNION* pOut,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

회전 행렬로부터 생성 된 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionRotationMatrix 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionRotationAxis ,D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationYawPitchRoll

요, 피치, 및 롤을 지정해 쿠오타니온을 생성 한다.

D3DXQUATERNION* D3DXQuaternionRotationYawPitchRoll(
  D3DXQUATERNION* pOut,
  FLOAT Yaw,
  FLOAT Pitch,
  FLOAT Roll
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
Yaw
[in] y 축의 요 (라디안 단위).
Pitch
[in] x 축의 피치 (라디안 단위).
Roll
[in] z 축의 롤 (라디안 단위).

반환값

요, 피치, 및 롤을 가지는 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionRotationYawPitchRoll 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionRotationAxis ,D3DXQuaternionRotationMatrix


D3DXQuaternionSlerp

구(공)장 선형 보간을 사용해, 2 개의 쿠오타니온간을 보간 한다.

D3DXQUATERNION* D3DXQuaternionSlerp(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2,
  FLOAT t
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ1
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pQ2
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
t
[in] 쿠오타니온간을 보간 하는 범위를 지정하는 파라미터.

반환값

보간 결과인 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionSlerp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXQuaternionSquad

구(공)장 평방 보간을 사용해, 쿠오타니온간을 보간 한다.

D3DXQUATERNION* D3DXQuaternionSquad(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2,
  CONST D3DXQUATERNION* pQ3,
  CONST D3DXQUATERNION* pQ4,
  FLOAT t
);

파라미터

pOut
[in, out] 연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ1
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pQ2
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pQ3
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pQ4
[in] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
t
[in] 쿠오타니온간을 보간 하는 범위를 지정하는 파라미터.

반환값

구(공)장 평방 보간의 결과인 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수는, 다음에 나타내는 구(공)장 선형 보간 연산을 사용한다. Slerp(Slerp(Q1, Q4, t), Slerp(Q2, Q3, t), 2t(1-t))

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionSquad 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXQuaternionExp ,D3DXQuaternionLn


D3DXQuaternionToAxisAngle

쿠오타니온의 회전축과 회전 각도를 계산한다.

void D3DXQuaternionToAxisAngle(
  CONST D3DXQUATERNION* pQ,
  D3DXVECTOR3* pAxis,
  FLOAT* pAngle
);

파라미터

pQ
[in, out] 처리의 기본으로 되는 D3DXQUATERNION 구조체에의 포인터.
pAxis
[in, out] 이 함수가 돌아오는 경우, 쿠오타니온의 회전축을 식별하는 D3DXVECTOR3 구조체에의 포인터.
pAngle
[in, out] 이 함수가 돌아오는 경우, 쿠오타니온의 회전 각도 (라디안 단위)를 식별하는 FLOAT 값에의 포인터.

반환값

없음.

주의

이 함수는, 정규화된 쿠오타니온이 건네받는 것과 가정하고 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec2Add

2 개의 2D 벡터를 가산한다.

D3DXVECTOR2* D3DXVec2Add(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.

반환값

2 개의 벡터의 합계인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Add 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2Subtract ,D3DXVec2Scale


D3DXVec2BaryCentric

지정된 2D 벡터를 사용해 중심 좌표의 포인트를 돌려준다.

D3DXVECTOR2* D3DXVec2BaryCentric(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2,
  D3DXVECTOR2* pV3,
  FLOAT f,
  FLOAT g
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV3
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
f
[in] 가중 계수. 「주의」를 참조할것.
g
[in] 가중 계수. 「주의」를 참조할것.

반환값

중심 좌표의 D3DXVECTOR2 구조체에의 포인터.

주의

D3DXVec2BaryCentric 함수는, 삼각형의 실제의 위치와는 관계없이, 삼각형의 내부나 주변의 포인트를 이해하는 방법을 제공하고 있다. 이 함수는, 다음의 식을 사용해 결과인 포인트를 돌려준다. V1 + f(V2-V1) + g(V3-V1)

평면 V1V2V3 의 포인트는 모두, 중심 좌표 (f, g)로 나타낼 수가 있다. 파라미터 f 는, V2 의 결과에 대한 가중을 제어해, 파라미터 g 는, V3 의 결과에 대한 가중을 제어한다. 마지막으로,1-f-g 는 V1 의 결과에 대한 가중을 제어한다.

다음의 관계에 주의 해야 한다.

  • (f>=0 && g>=0 && 1-f-g>=0)의 경우, 포인트는 삼각형 V1V2V3 내에 있다.
  • (f==0 && g>=0 && 1-f-g>=0)의 경우, 포인트는 직선 V1V3 상에 있다.
  • (f>=0 && g==0 && 1-f-g>=0)의 경우, 포인트는 직선 V1V2 상에 있다.
  • (f>=0 && g>=0 && 1-f-g==0)의 경우, 포인트는 직선 V2V3 상에 있다.

중심 좌표는, 일반적인 좌표의 형식이다. 여기서 중심 좌표를 사용할때는, 단지 좌표계의 변경을 나타내고 있다. 데카르트 좌표로 진정한 것은, 중심 좌표에서도 진이다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2BaryCentric 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec2CatmullRom

지정된 2D 벡터를 사용해, Catmull-Rom 보간을 실행한다.

D3DXVECTOR2* D3DXVec2CatmullRom(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2,
  CONST D3DXVECTOR2* pV3,
  CONST D3DXVECTOR2* pV4,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV3
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV4
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
s
[in] 가중 계수. 「주의」를 참조할것.

반환값

Catmull-Rom 보간의 결과인 D3DXVECTOR2 구조체에의 포인터.

주의

D3DXVec2CatmullRom 함수는, Catmull-Rom 보간을 사용해, 위치 V1 (s 가 0 의 경우)의 사이와 위치 V2 (s 가 1 의 경우)의 사이의 보간을 실시한다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec2CCW

2 개의 2D 벡터의 외적을 산출해 z 요소를 돌려준다.

FLOAT D3DXVec2CCW(
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

파라미터

pV1
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.

반환값

z 요소.

주의

이 함수는, 식 ((x1, y1, 0) cross (x2, y2, 0))에 근거해 외적을 산출해, z 요소를 판정한다. ((x1, y1, 0) cross (x2, y2, 0)). 또, 다음의 코드를 사용해 판정할 수도 있다.

pV1->x * pV2->y - pV1->y * pV2->x

z 요소의 값이 정의 경우, V2 는 V1 에 대해서 반시계회전이다. 이 정보는, 배면의 카링으로 도움이 된다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2Dot


D3DXVec2Dot

2 개의 2D 벡터의 내적을 산출한다.

FLOAT D3DXVec2Dot(
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

파라미터

pV1
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.

반환값

내적.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2CCW


D3DXVec2Hermite

지정된 2D 벡터를 사용해, 엘 미트의 스플라인 보간을 실행한다.

D3DXVECTOR2* D3DXVec2Hermite(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pT1,
  CONST D3DXVECTOR2* pV2,
  CONST D3DXVECTOR2* pT2,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pT1
[in] 접선 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pT2
[in] 접선 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
s
[in] 가중 계수. 「주의」를 참조할것.

반환값

엘 미트의 스플라인 보간의 결과인 D3DXVECTOR2 구조체에의 포인터.

주의

D3DXVec2Hermite 함수는, 엘 미트의 스플라인 보간을 사용해 (positionA, tangentA)로부터 (positionB, tangentB)에 보간 한다. 이 함수는, 위치 V1 와 접선 T1 의 사이 (s 가 0 의 경우)와 위치 V2 와 접선 T2 의 사이 (s 가 1 의 경우)를 보간 한다.

엘 미트의 스플라인은, 커브가 모든 제어 포인트를 통과하므로, 애니메이션을 제어하는 경우에 편리하다. 또, 위치나 접선이 각 세그먼트(segment)의 종점에서 명시적으로 지정되고 있으므로, 기점과 접선이 최종 세그먼트(segment)의 종점의 값에 일치하도록(듯이) 하고 있는 한, C2 연속 커브를 간단하게 생성 할 수 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Hermite 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec2Length

2D 벡터의 길이를 돌려준다.

FLOAT D3DXVec2Length(
  CONST D3DXVECTOR2* pV
);

파라미터

pV
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.

반환값

벡터의 길이.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2LengthSq


D3DXVec2LengthSq

2D 벡터의 길이의 2 승을 돌려준다.

FLOAT D3DXVec2LengthSq(
  CONST D3DXVECTOR2* pV
);

파라미터

pV
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.

반환값

벡터의 길이의 2 승.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2Length


D3DXVec2Lerp

2 개의 2D 벡터간의 선형 보간을 실행한다.

D3DXVECTOR2* D3DXVec2Lerp(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
s
[in] 벡터간을 선형 보간 하는 파라미터.

반환값

선형 보간의 결과인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수는, 다음의 식에 근거해 선형 보간을 실행한다. V1 + s(V2-V1)

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Lerp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec2Maximize

2 개의 2D 벡터의 각 요소의 최대치로부터 생성 된 2D 벡터를 돌려준다.

D3DXVECTOR2* D3DXVec2Maximize(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.

반환값

2 개의 벡터의 최대치로부터 생성 한 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Maximize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2Minimize


D3DXVec2Minimize

2 개의 2D 벡터의 각 요소의 최소 값으로부터 생성 된 2D 벡터를 돌려준다.

D3DXVECTOR2* D3DXVec2Minimize(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.

반환값

2 개의 벡터의 최소 값으로부터 생성 한 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Minimize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2Maximize


D3DXVec2Normalize

2D 벡터의 정규화한 벡터를 돌려준다.

D3DXVECTOR2* D3DXVec2Normalize(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.

반환값

정규화한 벡터의 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Normalize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec2Scale

2D 벡터를 스케일링 한다.

D3DXVECTOR2* D3DXVec2Scale(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
s
[in] 스케일링값.

반환값

스케일링 된 벡터인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Scale 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2Add ,D3DXVec2Subtract


D3DXVec2Subtract

2 개의 2D 벡터를 감산한다.

D3DXVECTOR2* D3DXVec2Subtract(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.

반환값

2 개의 벡터의 차분인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Subtract 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2Add ,D3DXVec2Scale


D3DXVec2Transform

지정된 행렬에 의해 2D 벡터를 트랜스 폼 한다.

D3DXVECTOR4* D3DXVec2Transform(
  D3DXVECTOR4** pOut,
  CONST D3DXVECTOR2* pV,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

트랜스 폼 된 벡터의 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수는, 벡터 pV (x, y, 0, 1)를 행렬 pM 에 의해 트랜스 폼 한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Transform 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2TransformCoord ,D3DXVec2TransformNormal


D3DXVec2TransformCoord

지정된 행렬에 의해 2D 벡터를 트랜스 폼 해, 그 결과를 w = 1 에 투영 한다.

D3DXVECTOR2* D3DXVec2TransformCoord(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

트랜스 폼 된 벡터의 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수는, 벡터 pV (x, y, 0, 1)를 행렬 pM 에 의해 트랜스 폼 해, 그 결과를 w=1 에 투영 한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2TransformCoord 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2Transform ,D3DXVec2TransformNormal


D3DXVec2TransformNormal

지정된 행렬에 의해 2D 벡터를 w = 0 으로 트랜스 폼 한다.

D3DXVECTOR2* D3DXVec2TransformNormal(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR2 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

트랜스 폼 된 벡터의 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수는, 벡터 pV 의 벡터 법선 (x, y, 0, 0)을 행렬 pM 에 의해 트랜스 폼 한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2TransformNormal 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec2Transform ,D3DXVec2TransformCoord


D3DXVec3Add

2 개의 3D 벡터를 가산한다.

D3DXVECTOR3* D3DXVec3Add(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

2 개의 3D 벡터의 합계인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Add 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Subtract ,D3DXVec3Scale


D3DXVec3BaryCentric

지정된 3D 벡터를 사용해 중심 좌표의 포인트를 돌려준다.

D3DXVECTOR3* D3DXVec3BaryCentric(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2,
  D3DXVECTOR3* pV3,
  FLOAT f,
  FLOAT g
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV3
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
f
[in] 가중 계수. 「주의」를 참조할것.
g
[in] 가중 계수. 「주의」를 참조할것.

반환값

중심 좌표의 D3DXVECTOR3 구조체에의 포인터.

주의

D3DXVec3BaryCentric 함수는, 삼각형의 실제의 위치와는 관계없이, 삼각형의 내부나 주변의 포인트를 이해하는 방법을 제공하고 있다. 이 함수는, 다음의 식을 사용해 결과인 포인트를 돌려준다. V1 + f(V2-V1) + g(V3-V1)

평면 V1V2V3 의 임의의 포인트는, 중심 좌표 (f,g)로 나타낼 수가 있다. 파라미터 f 는 V2 의 결과에 대한 가중을 제어해, 파라미터 g 는 V3 의 결과에 대한 가중을 제어한다. 마지막으로,1-f-g 는 V1 의 결과에 대한 가중을 제어한다.

다음의 관계에 주의 해야 한다.

  • (f>=0 && g>=0 && 1-f-g>=0)의 경우, 포인트는 삼각형 V1V2V3 내에 있다.
  • (f==0 && g>=0 && 1-f-g>=0)의 경우, 포인트는 직선 V1V3 상에 있다.
  • (f>=0 && g==0 && 1-f-g>=0)의 경우, 포인트는 직선 V1V2 상에 있다.
  • (f>=0 && g>=0 && 1-f-g==0)의 경우, 포인트는 직선 V2V3 상에 있다.

중심 좌표는, 일반적인 좌표의 형식이다. 여기서 중심 좌표를 사용할때는, 단지 좌표계의 변경을 나타내고 있다. 데카르트 좌표로 진정한 것은, 중심 좌표에서도 진이다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3BaryCentric 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec3CatmullRom

지정된 3D 벡터를 사용해, Catmull-Rom 보간을 실행한다.

D3DXVECTOR3* D3DXVec3CatmullRom(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2,
  CONST D3DXVECTOR3* pV3,
  CONST D3DXVECTOR3* pV4,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV3
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV4
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
s
[in] 가중 계수. 「주의」를 참조할것.

반환값

Catmull-Rom 보간의 결과인 D3DXVECTOR3 구조체에의 포인터.

주의

D3DXVec3CatmullRom 함수는, Catmull-Rom 보간을 사용해, 위치 V1 (s 가 0 의 경우)의 사이와 위치 V2 (s 가 1 의 경우)의 사이의 보간을 실시한다.

동작환경

헤더 : D3dx8math.h 으로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec3Cross

2 개의 3D 벡터의 외적을 산출한다.

D3DXVECTOR3* D3DXVec3Cross(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

2 개의 3D 벡터의 외적인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수는, 다음의 코드를 사용해 외적을 산출한다.

    D3DXVECTOR3 v;

    v.x = pV1->y * pV2->z - pV1->z * pV2->y;
    v.y = pV1->z * pV2->x - pV1->x * pV2->z;
    v.z = pV1->x * pV2->y - pV1->y * pV2->x;

    *pOut = v;

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Cross 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Dot


D3DXVec3Dot

2 개의 3D 벡터의 내적을 산출한다.

FLOAT D3DXVec3Dot(
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

파라미터

pV1
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

내적.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Cross


D3DXVec3Hermite

지정된 3D 벡터를 사용해, 엘 미트의 스플라인 보간을 실행한다.

D3DXVECTOR3* D3DXVec3Hermite(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pT1,
  CONST D3DXVECTOR3* pV2,
  CONST D3DXVECTOR3* pT2,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pT1
[in] 접선 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pT2
[in] 접선 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
s
[in] 가중 계수. 「주의」를 참조할것.

반환값

엘 미트의 스플라인 보간의 결과인 D3DXVECTOR3 구조체에의 포인터.

주의

D3DXVec3Hermite 함수는, 엘 미트의 스플라인 보간을 사용해 (positionA, tangentA)로부터 (positionB, tangentB)에 보간 한다. 이 함수는, 위치 V1 와 접선 T1 의 사이 (s 가 0 의 경우)와 위치 V2 와 접선 T2 의 사이 (s 가 1 의 경우)를 보간 한다.

엘 미트의 스플라인은, 커브가 모든 제어 포인트를 통과하므로, 애니메이션을 제어하는 경우에 편리하다. 또, 위치나 접선이 각 세그먼트(segment)의 종점에서 명시적으로 지정되고 있으므로, 기점과 접선이 최종 세그먼트(segment)의 종점의 값에 일치하도록(듯이) 하고 있는 한, C2 연속 커브를 간단하게 생성 할 수 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Hermite 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec3Length

3D 벡터의 길이를 돌려준다.

FLOAT D3DXVec3Length(
  CONST D3DXVECTOR3* pV
);

파라미터

pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

벡터의 길이.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3LengthSq


D3DXVec3LengthSq

3D 벡터의 길이의 2 승을 돌려준다.

FLOAT D3DXVec3LengthSq(
  CONST D3DXVECTOR3* pV
);

파라미터

pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

벡터의 길이의 2 승.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Length


D3DXVec3Lerp

2 개의 3D 벡터간의 선형 보간을 실행한다.

D3DXVECTOR3* D3DXVec3Lerp(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
s
[in] 벡터간을 선형 보간 하는 파라미터.

반환값

선형 보간의 결과인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수는, 다음의 식에 근거해 선형 보간을 실행한다. V1 + s(V2-V1)

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Lerp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec3Maximize

2 개의 3D 벡터의 각 요소의 최대치로부터 생성 된 3D 벡터를 돌려준다.

D3DXVECTOR3* D3DXVec3Maximize(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 각 요소의 최대치로부터 생성 된 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Maximize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Minimize


D3DXVec3Minimize

2 개의 3D 벡터의 각 요소의 최소 값으로부터 생성 된 3D 벡터를 돌려준다.

D3DXVECTOR3* D3DXVec3Minimize(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 최소 값으로부터 생성 된 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Minimize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Maximize


D3DXVec3Normalize

3D 벡터의 정규화한 벡터를 돌려준다.

D3DXVECTOR3* D3DXVec3Normalize(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 정규화한 벡터의 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Normalize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec3Project

오브젝트 공간으로부터 스크린 공간에 벡터를 투영 한다.

D3DXVECTOR3* D3DXVec3Project(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV
  CONST D3DVIEWPORT8* pViewport,
  CONST D3DXMATRIX* pProjection
  CONST D3DXMATRIX* pView,
  CONST D3DXMATRIX* pWorld
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pViewport
[in] 뷰 포토를 나타내는 D3DVIEWPORT8 구조체에의 포인터.
pProjection
[in] 투영 행렬을 나타내는 D3DXMATRIX 구조체에의 포인터.
pView
[in] 뷰 행렬을 나타내는 D3DXMATRIX 구조체에의 포인터.
pWorld
[in] 월드 행렬을 나타내는 D3DXMATRIX 구조체에의 포인터.

반환값

오브젝트 공간으로부터 스크린 공간에 투영 된 벡터인,D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Project 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Unproject


D3DXVec3Scale

3D 벡터를 스케일링 한다.

D3DXVECTOR3* D3DXVec3Scale(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
s
[in] 스케일링값.

반환값

스케일링 된 벡터인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Scale 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Add ,D3DXVec3Subtract


D3DXVec3Subtract

2 개의 3D 벡터를 감산한다.

D3DXVECTOR3* D3DXVec3Subtract(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.

반환값

2 개의 벡터의 차분인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Subtract 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Add ,D3DXVec3Scale


D3DXVec3Transform

지정된 행렬에 의해 3D 벡터를 트랜스 폼 한다.

D3DXVECTOR4* D3DXVec3Transform(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR3* pV,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

트랜스 폼 된 벡터의 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수는, 벡터 pV (x, y, z, 1)를 행렬 pM 에 의해 트랜스 폼 한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Transform 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3TransformCoord ,D3DXVec3TransformNormal


D3DXVec3TransformCoord

지정된 행렬에 의해 3D 벡터를 트랜스 폼 해, 그 결과를 w = 1 에 투영 한다.

D3DXVECTOR3* D3DXVec3TransformCoord(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

트랜스 폼 된 벡터의 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수는, 벡터 pV (x, y, z, 1)를 행렬 pM 에 의해 트랜스 폼 해, 그 결과를 w=1 에 투영 한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3TransformCoord 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Transform ,D3DXVec3TransformNormal


D3DXVec3TransformNormal

지정된 행렬에 의해 3D 벡터를 w = 0 으로 트랜스 폼 한다.

D3DXVECTOR3* D3DXVec3TransformNormal(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

트랜스 폼 된 벡터의 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수는, 벡터 pV 의 벡터 법선 (x, y, z, 0)을 행렬 pM 에 의해 트랜스 폼 한다.

아핀 행렬 이외의 행렬로 법선을 트랜스 폼 하는 경우, 이 함수에 건네주는 행렬은, 좌표의 트랜스 폼에 사용하는 행렬의 반전의 전치로 할 필요가 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3TransformNormal 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec3Unproject

스크린 공간으로부터 오브젝트 공간에 벡터를 역변환한다.

D3DXVECTOR3* D3DXVec3Unproject(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV
  CONST D3DVIEWPORT8* pViewport,
  CONST D3DXMATRIX* pProjection
  CONST D3DXMATRIX* pView,
  CONST D3DXMATRIX* pWorld
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR3 구조체에의 포인터.
pViewport
[in] 뷰 포토를 나타내는 D3DVIEWPORT8 구조체에의 포인터.
pProjection
[in] 투영 행렬을 나타내는 D3DXMATRIX 구조체에의 포인터.
pView
[in] 뷰 행렬을 나타내는 D3DXMATRIX 구조체에의 포인터.
pWorld
[in] 월드 행렬을 나타내는 D3DXMATRIX 구조체에의 포인터.

반환값

스크린 공간으로부터 스크린 오브젝트에 투영 된 벡터인,D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Unproject 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Project


D3DXVec4Add

2 개의 4D 벡터를 가산한다.

D3DXVECTOR4* D3DXVec4Add(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 합계인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Add 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec4Subtract ,D3DXVec4Scale


D3DXVec4BaryCentric

지정된 4D 벡터를 사용해 중심 좌표의 포인트를 돌려준다.

D3DXVECTOR4* D3DXVec4BaryCentric(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2,
  CONST D3DXVECTOR4* pV3,
  FLOAT f,
  FLOAT g
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV3
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
f
[in] 가중 계수. 「주의」를 참조할것.
g
[in] 가중 계수. 「주의」를 참조할것.

반환값

중심 좌표의 D3DXVECTOR4 구조체에의 포인터.

주의

D3DXVec4BaryCentric 함수는, 삼각형의 실제의 위치와는 관계없이, 삼각형의 내부나 주변의 포인트를 이해하는 방법을 제공하고 있다. 이 함수는, 다음의 식을 사용해 결과인 포인트를 돌려준다. V1 + f(V2-V1) + g(V3-V1)

평면 V1V2V3 의 임의의 포인트는, 중심 좌표 (f,g)로 나타낼 수가 있다. 파라미터 f 는 V2 의 결과에 대한 가중을 제어해, 파라미터 g 는 V3 의 결과에 대한 가중을 제어한다. 마지막으로,1-f-g 는 V1 의 결과에 대한 가중을 제어한다.

다음의 관계에 주의 해야 한다.

  • (f>=0 && g>=0 && 1-f-g>=0)의 경우, 포인트는 삼각형 V1V2V3 내에 있다.
  • (f==0 && g>=0 && 1-f-g>=0)의 경우, 포인트는 직선 V1V3 상에 있다.
  • (f>=0 && g==0 && 1-f-g>=0)의 경우, 포인트는 직선 V1V2 상에 있다.
  • (f>=0 && g>=0 && 1-f-g==0)의 경우, 포인트는 직선 V2V3 상에 있다.

중심 좌표는, 일반적인 좌표의 형식이다. 여기서 중심 좌표를 사용할때는, 단지 좌표계의 변경을 나타내고 있다. 데카르트 좌표로 진정한 것은, 중심 좌표에서도 진이다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4BaryCentric 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec4CatmullRom

지정된 4D 벡터를 사용해, Catmull-Rom 보간을 실행한다.

D3DXVECTOR4* D3DXVec4CatmullRom(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2,
  CONST D3DXVECTOR4* pV3,
  CONST D3DXVECTOR4* pV4,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV3
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV4
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
s
[in] 가중 계수. 「주의」를 참조할것.

반환값

Catmull-Rom 보간의 결과인 D3DXVECTOR4 구조체에의 포인터.

주의

D3DXVec4CatmullRom 함수는, Catmull-Rom 보간을 사용해, 위치 V1 (s 가 0 의 경우)의 사이와 위치 V2 (s 가 1 의 경우)의 사이의 보간을 실시한다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec4Cross

4 차원 공간에 있어서의 외적을 산출한다.

D3DXVECTOR4* D3DXVec4Cross(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2,
  CONST D3DXVECTOR4* pV3
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV3
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.

반환값

외적인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Cross 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec4Dot


D3DXVec4Dot

2 개의 4D 벡터의 내적을 산출한다.

FLOAT D3DXVec4Dot(
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

파라미터

pV1
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.

반환값

내적.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec4Cross


D3DXVec4Hermite

지정된 4D 벡터를 사용해, 엘 미트의 스플라인 보간을 실행한다.

D3DXVECTOR4* D3DXVec4Hermite(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pT1,
  CONST D3DXVECTOR4* pV2,
  CONST D3DXVECTOR4* pT2,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pT1
[in] 접선 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 위치 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pT2
[in] 접선 벡터를 나타내는, 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
s
[in] 가중 계수. 「주의」를 참조할것.

반환값

엘 미트의 스플라인 보간의 결과인 D3DXVECTOR4 구조체에의 포인터.

주의

D3DXVec4Hermite 함수는, 엘 미트의 스플라인 보간을 사용해 (positionA, tangentA)로부터 (positionB, tangentB)에 보간 한다. 이 함수는, 위치 V1 와 접선 T1 의 사이 (s 가 0 의 경우)와 위치 V2 와 접선 T2 의 사이 (s 가 1 의 경우)를 보간 한다.

엘 미트의 스플라인은, 커브가 모든 제어 포인트를 통과하므로, 애니메이션을 제어하는 경우에 편리하다. 또, 위치나 접선이 각 세그먼트(segment)의 종점에서 명시적으로 지정되고 있으므로, 기점과 접선이 최종 세그먼트(segment)의 종점의 값에 일치하도록(듯이) 하고 있는 한, C2 연속 커브를 간단하게 생성 할 수 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Hermite 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec4Length

4D 벡터의 길이를 돌려준다.

FLOAT D3DXVec4Length(
  CONST D3DXVECTOR4* pV
);

파라미터

pV
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.

반환값

벡터의 길이.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec4LengthSq


D3DXVec4LengthSq

4D 벡터의 길이의 2 승을 돌려준다.

FLOAT D3DXVec4LengthSq(
  CONST D3DXVECTOR4* pV
);

파라미터

pV
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.

반환값

벡터의 길이의 2 승.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec4Length


D3DXVec4Lerp

2 개의 4D 벡터간의 선형 보간을 실행한다.

D3DXVECTOR4* D3DXVec4Lerp(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
s
[in] 벡터간을 선형 보간 하는 파라미터.

반환값

선형 보간의 결과인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수는, 다음의 식에 근거해 선형 보간을 실행한다. V1 + s(V2-V1)

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Lerp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec4Maximize

2 개의 4D 벡터의 각 요소의 최대치로부터 생성 된 4D 벡터를 돌려준다.

D3DXVECTOR4* D3DXVec4Maximize(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 최대치로부터 생성 한 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Maximize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec4Minimize


D3DXVec4Minimize

2 개의 4D 벡터의 각 요소의 최소 값으로부터 생성 된 4D 벡터를 돌려준다.

D3DXVECTOR4* D3DXVec4Minimize(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 최소 값으로부터 생성 한 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Minimize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec4Maximize


D3DXVec4Normalize

4D 벡터의 정규화한 벡터를 돌려준다.

D3DXVECTOR4* D3DXVec4Normalize(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.

반환값

지정된 정규화한 벡터의 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Normalize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXVec4Scale

4D 벡터를 스케일링 한다.

D3DXVECTOR4* D3DXVec4Scale(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV,
  FLOAT s
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
s
[in] 스케일링값.

반환값

스케일링 된 벡터인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Scale 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec4Add ,D3DXVec4Subtract


D3DXVec4Subtract

2 개의 4D 벡터를 감산한다.

D3DXVECTOR4* D3DXVec4Subtract(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pV2
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.

반환값

2 개의 벡터의 차분인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Subtract 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXVec3Add ,D3DXVec3Scale


D3DXVec4Transform

지정된 행렬에 의해 4D 벡터를 트랜스 폼 한다.

D3DXVECTOR4* D3DXVec4Transform(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV,
  CONST D3DXMATRIX* pM
);

파라미터

pOut
[in, out] 연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
[in] 처리의 기본으로 되는 D3DXVECTOR4 구조체에의 포인터.
pM
[in] 처리의 기본으로 되는 D3DXMATRIX 구조체에의 포인터.

반환값

트랜스 폼 된 4D 벡터의 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Transform 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

헤더 : D3dx8math.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


메쉬 함수

Direct3DX 에서는 다음의 메쉬 함수가 준비되어 있다.

  • D3DXBoxBoundProbe
  • D3DXCleanMesh
  • D3DXComputeBoundingBox
  • D3DXComputeBoundingSphere
  • D3DXComputeNormals
  • D3DXCreateBuffer
  • D3DXCreateMesh
  • D3DXCreateMeshFVF
  • D3DXCreatePMeshFromStream
  • D3DXCreateSkinMesh
  • D3DXCreateSkinMeshFromMesh
  • D3DXCreateSkinMeshFVF
  • D3DXCreateSPMesh
  • D3DXDeclaratorFromFVF
  • D3DXFVFFromDeclarator
  • D3DXGeneratePMesh
  • D3DXIntersect
  • D3DXLoadMeshFromX
  • D3DXLoadMeshFromXof
  • D3DXLoadSkinMeshFromXof
  • D3DXSaveMeshToX
  • D3DXSimplifyMesh
  • D3DXSphereBoundProbe
  • D3DXTesselateMesh
  • D3DXValidMesh
  • D3DXWeldVertices


D3DXBoxBoundProbe

레이가 박스의 경계 박스의 볼륨에 해당될지 어떨지를 판정한다.

BOOL D3DXBoxBoundProbe(
  CONST D3DXVECTOR3* pMin,
  CONST D3DXVECTOR3* pMax,
  D3DXVECTOR3* pRayPosition,
  D3DXVECTOR3* pRayDirection
);

파라미터

pMin
[out] 경계 박스의 왼쪽 하단 모서리를 기술하는,D3DXVECTOR3 구조체에의 포인터. 「주의」를 참조할것.
pMax
[out] 경계 박스의 우상구석을 기술하는,D3DXVECTOR3 구조체에의 포인터. 「주의」를 참조할것.
pRayPosition
[in] 레이의 시점 좌표를 지정하는 D3DXVECTOR3 구조체에의 포인터.
pRayDirection
[in] 레이의 방향을 지정하는 D3DXVECTOR3 구조체에의 포인터.

반환값

레이가 박스의 경계 박스의 볼륨에 해당되는 경우는, TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

주의

D3DXBoxBoundProbe 는, 레이가 박스의 표면 만이 아니고, 박스의 경계 박스의 볼륨에 해당될지 어떨지를 판정한다.

D3DXBoxBoundProbe 에게 건네지는 D3DXVECTOR3 의 값은, xmin, xmax, ymin, ymax, zmin, zmax 이다. 따라서, 경계 박스의 모퉁이의 정의는 다음과 같이 된다.

xmax, ymax, zmax
xmax, ymax, zmin
xmax, ymin, zmax
xmax, ymin, zmin
xmin, ymax, zmax
xmin, ymax, zmin
xmin, ymin, zmax
xmin, ymin, zmin

경계 박스의 깊이는, z 방향이 zmax - zmin, y 방향이 ymax - ymin, 그리고 x 방향이 xmax - xmin 이다. 예를 들어, 최소 벡터가 min (-1, -1, -1), 최대 벡터가 (1, 1, 1)의 경우, 경계 박스의 정의는 다음과 같이 된다.

 1,  1,  1
 1,  1, -1
 1, -1,  1
 1, -1, -1
-1,  1,  1
-1,  1, -1
-1, -1,  1
-1, -1, -1

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXComputeBoundingBox


D3DXCleanMesh

단순화의 준비로서 메쉬의 클리닝을 실시한다.

HRESULT D3DXCleanMesh(
  LPD3DXMESH pMeshIn,
  CONST DWORD* pAdjacency,
  LPD3DXMESH* ppMeshOut
);

파라미터

pMeshIn
[in] 클리닝 하는 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터.
pAdjacency
[in] 클리닝 하는 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
ppMeshOut
[out] 클리닝 된 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터의 주소. 클리닝의 필요가 없는 경우는, 건네준 메쉬와 같은 메쉬가 돌려주어진다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

이 메소드는, 2 개의 삼각형 팬이 같은 버텍스를 공유하고 있는 경우에, 버텍스를 추가하는 것에 의해 메쉬의 클리닝을 실시한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXComputeBoundingBox

경계 박스를 산출한다.

HRESULT D3DXComputeBoundingBox(
  PVOID pPointsFVF,
  DWORD NumVertices,
  DWORD FVF,
  D3DXVECTOR3* pMin,
  D3DXVECTOR3* pMax
);

파라미터

pPointsFVF
[in] 경계 박스의 산출에 사용하는 버텍스 데이터를 저장 하는 버퍼에의 포인터.
NumVertices
[in] 버텍스의 수.
FVF
[in] 버텍스 포맷을 기술하는유연한 버텍스 포맷 플래그의 편성.
pMin
[out] 경계 박스의 왼쪽 하단 모서리를 기술하는,D3DXVECTOR3 구조체에의 포인터. 「주의」를 참조할것.
pMax
[out] 경계 박스의 우상구석을 기술하는,D3DXVECTOR3 구조체에의 포인터. 「주의」를 참조할것.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 1 개의 D3DERR_INVALIDCALL 를 돌려준다.

주의

D3DXComputeBoundingBox 가 돌려주는 D3DXVECTOR3 의 값은, xmin, xmax, ymin, ymax, zmin, zmax 이다. 따라서, 경계 박스의 모퉁이의 정의는 다음과 같이 된다.

xmax, ymax, zmax
xmax, ymax, zmin
xmax, ymin, zmax
xmax, ymin, zmin
xmin, ymax, zmax
xmin, ymax, zmin
xmin, ymin, zmax
xmin, ymin, zmin

경계 박스의 깊이는, z 방향이 zmax - zmin, y 방향이 ymax - ymin, 그리고 x 방향이 xmax - xmin 이다. 예를 들어, 최소 벡터가 min (-1, -1, -1), 최대 벡터가 (1, 1, 1)의 경우, 경계 박스의 정의는 다음과 같이 된다.

 1,  1,  1
 1,  1, -1
 1, -1,  1
 1, -1, -1
-1,  1,  1
-1,  1, -1
-1, -1,  1
-1, -1, -1

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXComputeBoundingSphere

경계구(공)을 산출한다.

HRESULT D3DXComputeBoundingSphere(
  PVOID pvPointsFVF,
  DWORD NumVertices,
  DWORD FVF,
  D3DXVECTOR3* pCenter,
  FLOAT* pRadius
);

파라미터

pvPointsFVF
[in] 경계구(공)의 산출에 사용하는 버텍스 데이터를 저장 하는 버퍼에의 포인터.
NumVertices
[in] 버텍스의 수.
FVF
[in] 버텍스 포맷을 기술하는유연한 버텍스 포맷 플래그의 편성.
pCenter
[out] 경계구(공)의 좌표의 중심을 정의하는,D3DXVECTOR3 구조체.
pRadius
[out] 경계구(공)의 반경.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 1 개의 D3DERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXComputeNormals

메쉬에 포함되는 각 버텍스의 법선을 산출한다.

HRESULT D3DXComputeNormals(
  LPD3DXBASEMESH pMesh
);

파라미터

pMesh
[in, out] 정규화된 메쉬 오브젝트를 나타내는,ID3DXBaseMesh 인터페이스에의 포인터.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 1 개의 D3DERR_INVALIDCALL 를 돌려준다.

주 입력 메쉬의 FVF 에 D3DFVF_NORMAL 플래그가 지정되고 있을 필요가 있다.

버텍스의 법선은, 그 버텍스를 공유하는 모든 면의 법선을 평균하는 것으로써, 생성된다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateBuffer

버퍼 오브젝트를 생성 한다.

HRESULT D3DXCreateBuffer(
  DWORD NumBytes,
  LPD3DXBUFFER* ppBuffer
);

파라미터

NumBytes
[in] 생성 하는 버퍼의 사이즈 (바이트 단위).
ppBuffer
[out] 생성 된 버퍼 오브젝트를 나타내는,ID3DXBuffer 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 1 개의 E_OUTOFMEMORY 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateMesh

선언자를 사용해 메쉬 오브젝트를 생성 한다.

HRESULT D3DXCreateMesh(
  DWORD NumFaces,
  DWORD NumVertices,
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXMESH* ppMesh
);

파라미터

NumFaces
[in] 메쉬의 면의 수. 이 파라미터는 1 이상이 아니면 안된다.
NumVertices
[in] 메쉬의 버텍스의 수. 이 파라미터는 1 이상이 아니면 안된다.
Options
[in] 메쉬에 대한 옵션을 지정하는, 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에 사용할 수 없다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼와 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 지정해 생성 된다. 이것은, 메쉬 오브젝트를 N 패치 강화를 사용해 Microsoft® Direct3D® 로 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pDeclaration
[in] 돌려주어진 메쉬의 버텍스 포맷을 기술하는 선언자를 나타내는,DWORD 값에의 포인터. 이 파라미터는 FVF 를 직접 맵 할 필요가 있다.
pDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppMesh
[out] 생성 된 메쉬 오브젝트를 나타내는 ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXDeclaratorFromFVF


D3DXCreateMeshFVF

유연한 버텍스 포맷 (FVF) 코드를 사용해 메쉬 오브젝트를 생성 한다.

HRESULT D3DXCreateMeshFVF(
  DWORD NumFaces,
  DWORD NumVertices,
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXMESH* ppMesh
);

파라미터

NumFaces
[in] 메쉬의 면의 수. 이 파라미터는 1 이상이 아니면 안된다.
NumVertices
[in] 메쉬의 버텍스의 수. 이 파라미터는 1 이상이 아니면 안된다.
Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에 사용할 수 없다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼와 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 지정해 생성 된다. 이것은, 메쉬 오브젝트를 N 패치 강화를 사용해 Microsoft® Direct3D® 로 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
FVF
[in] 메쉬의 버텍스 포맷을 기술하는,유연한 버텍스 포맷 플래그의 편성.
pDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppMesh
[out] 생성 된 메쉬 오브젝트를 나타내는 ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXFVFFromDeclarator


D3DXCreatePMeshFromStream

스트림 오브젝트로부터 프로그래시브 메쉬를 생성 한다.

HRESULT D3DXCreatePMeshFromStream(
  IStream* pStream,
  DWORD Options,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXBUFFER* ppMaterials,
  DWORD* pNumMaterials,
  LPD3DXPMESH* ppPMesh
);

파라미터

pStream
[in] 프로그래시브 메쉬 생성의 원이 되는 스트림 오브젝트를 나타내는 IStream 인터페이스에의 포인터. 이 스트림의 데이터는,ID3DXPMesh::Save 메소드로 생성되고 있다.
Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에 사용할 수 없다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼와 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 지정해 생성 된다. 이것은, 메쉬 오브젝트를 N 패치 강화를 사용해 Microsoft® Direct3D® 로 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pD3DDevice
[in] 프로그래시브 메쉬에 관련지을 수 있는 디바이스 오브젝트인,IDirect3DDevice8 인터페이스에의 포인터.
ppMaterials
[out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 스트림 오브젝트에 보존된 정보를 저장 하는 D3DXMATERIAL 구조체의 배열이 입력된다.
pNumMaterials
[out] 메소드가 돌아왔을 때의 ppMaterials 배열내의 D3DXMATERIAL 구조체의 수에의 포인터.
ppPMesh
[out] 생성 된 프로그래시브 메쉬를 나타내는,ID3DXPMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

IStream 인터페이스의 상세한 것에 대하여는, Microsoft Platform Software Development Kit (SDK)를 참조할것.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXPMesh::Save


D3DXCreateSkinMesh

선언자를 사용해 하늘의 스킨 메쉬 오브젝트를 생성 한다.

HRESULT D3DXCreateSkinMesh(
  DWORD numFaces,
  DWORD numVertices,
  DWORD numBones,
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXSKINMESH* ppSkinMesh
);

파라미터

numFaces
[in] 스킨 메쉬의 면의 수.
numVertices
[in] 스킨 메쉬의 버텍스의 수.
numBones
[in] 스킨 메쉬의 뼈의 수.
Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에 사용할 수 없다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼와 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 지정해 생성 된다. 이것은, 메쉬 오브젝트를 N 패치 강화를 사용해 Microsoft® Direct3D® 로 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pDeclaration
[in] 돌려주어진 스킨 메쉬의 버텍스 포맷을 기술하는 선언자를 나타내는,DWORD 값에의 포인터.
pDevice
[in] 스킨 메쉬에 관련지을 수 있는 디바이스 오브젝트인,IDirect3DDevice8 인터페이스에의 포인터.
ppSkinMesh
[out, retval] 생성 된 스킨 메쉬 오브젝트를 나타내는 ID3DXSkinMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는,E_OUTOFMEMORY 를 돌려준다.

주의

이 메소드로 돌려주어지는 하늘의 스킨 메쉬 오브젝트에 데이터를 대입하려면 ,ID3DXSkinMesh::SetBoneInfluence 를 사용한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::SetBoneInfluence


D3DXCreateSkinMeshFromMesh

다른 메쉬로부터 스킨 메쉬를 생성 한다.

HRESULT D3DXCreateSkinMeshFromMesh(
  LPD3DXMESH pMesh,
  DWORD numBones,
  LPD3DXSKINMESH* ppSkinMesh
);

파라미터

pMesh
[in] 스킨 메쉬 생성의 원이 되는 메쉬인 ID3DXMesh 오브젝트에의 포인터.
numBones
[in] 스킨 메쉬의 뼈의 수.
ppSkinMesh
[out, retval] 생성 된 스킨 메쉬 오브젝트를 나타내는 ID3DXSkinMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는,E_OUTOFMEMORY 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateSkinMeshFVF

유연한 버텍스 포맷 (FVF) 코드를 사용해 하늘의 스킨 메쉬 오브젝트를 생성 한다.

HRESULT D3DXCreateSkinMeshFVF(
  DWORD numFaces,
  DWORD numVertices,
  DWORD numBones,
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXSKINMESH* ppSkinMesh
);

파라미터

numFaces
[in] 스킨 메쉬의 면의 수.
numVertices
[in] 스킨 메쉬의 버텍스의 수.
numBones
[in] 스킨 메쉬의 뼈의 수.
Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에 사용할 수 없다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼와 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 지정해 생성 된다. 이것은, 메쉬 오브젝트를 N 패치 강화를 사용해 Microsoft® Direct3D® 로 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
FVF
[in] 스킨 메쉬의 버텍스 포맷을 기술하는,유연한 버텍스 포맷 플래그의 편성.
pDevice
[in] 스킨 메쉬에 관련지을 수 있는 디바이스 오브젝트인,IDirect3DDevice8 인터페이스에의 포인터.
ppSkinMesh
[out, retval] 생성 된 스킨 메쉬 오브젝트를 나타내는 ID3DXSkinMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

이 메소드로 돌려주어지는 하늘의 스킨 메쉬 오브젝트에 데이터를 대입하려면 ,ID3DXSkinMesh::SetBoneInfluence 를 사용한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

ID3DXSkinMesh::SetBoneInfluence


D3DXCreateSPMesh

단순화 메쉬를 생성 한다.

HRESULT D3DXCreateSPMesh(
  LPD3DXMESH pMesh,
  CONST DWORD* pAdjacency,
  CONST LPD3DXATTRIBUTEWEIGHTS pVertexAttributeWeights,
  CONST FLOAT* pVertexWeights,
  LPD3DXSPMESH* ppSMesh
);

파라미터

pMesh
[in] 단순화 하는 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터.
pAdjacency
[in] 생성 된 단순화 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pVertexAttributeWeights
[in] 각 버텍스의 성분에 대한 가중을 저장 하는 D3DXATTRIBUTEWEIGHTS 구조체에의 포인터. 이 파라미터를 NULL 로 설정 하면, 디폴트의 구조체가 사용된다. 「주의」를 참조할것.
pVertexWeights
[in] 버텍스 가중의 배열에의 포인터. 이 파라미터를 NULL 로 설정 하면, 모든 버텍스 가중은 1.0 으로 설정된다. 지정된 버텍스의 버텍스 가중이 큰 만큼, 단순화 하기 어려운 것에 주의한다.
ppSMesh
[out] 생성 된 단순화 메쉬를 나타내는,ID3DXSPMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DXERR_CANNOTATTRSORT
D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

단순화 메쉬는, 메쉬를 단순화 해, 삼각형과 면의 수를 줄이기 위해서(때문에) 사용한다.

pVertexAttributeWeights 를 NULL 로 설정했을 경우, 다음에 나타내는 값이 디폴트의 D3DXATTRIBUTEWEIGHTS 구조체에 할당할 수 있다.

D3DXATTRIBUTEWEIGHTS AttributeWeights;

AttributeWeights.Position  = 1.0;
AttributeWeights.Boundary =  1.0;
AttributeWeights.Normal   =  1.0;
AttributeWeights.Diffuse  =  0.0;
AttributeWeights.Specular =  0.0;
AttributeWeights.Tex[8]   =  {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};

보통의 어플리케이션에서는, 이 디폴트의 구조체를 사용해야 한다. 이유는, 이 구조체가 지오메트리와 법선의 조정만을 목적으로 하고 있기 때문이다. 그 외의 멤버 필드를 수정할 필요가 있는 것은, 특별한 경우뿐이다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXDeclaratorFromFVF

유연한 버텍스 포맷 (FVF) 코드로부터 선언자를 돌려준다.

HRESULT D3DXDeclaratorFromFVF(
  DWORD FVF,
  DWORD Declaration[MAX_FVF_DECL_SIZE]
);

파라미터

FVF
[in] 선언자의 배열을 생성하는 원이 되는 FVF 를 기술하는,유연한 버텍스 포맷 플래그의 편성.
Declaration
[out] 조회된 메쉬에 포함되는 버텍스의 버텍스 포맷을 기술하는 돌려주어진 배열. 이 선언자의 배열의 상한은 MAX_FVF_DECL_SIZE 로, 선언자를 15 DWORD 의 최대수에 제한한다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 1 개의D3DXERR_INVALIDMESH 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXFVFFromDeclarator


D3DXFVFFromDeclarator

선언자로부터 유연한 버텍스 포맷 (FVF) 코드를 돌려준다.

HRESULT D3DXFVFFromDeclarator(
  CONST DWORD* pDeclarator,
  DWORD* pFVF
);

파라미터

pDeclarator
[in] FVF 코드를 생성하는 원이 되는 선언자를 나타내는,DWORD 값에의 포인터.
pFVF
[out] 선언자로부터 돌려주어지는 버텍스 포맷을 기술하는유연한 버텍스 포맷 플래그의 편성을 나타내는,DWORD 값에의 포인터.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주 이 함수는, FVF 를 직접 맵 하지 않는 선언자에서는 실패한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXDeclaratorFromFVF


D3DXGeneratePMesh

프로그래시브 메쉬를 생성한다.

HRESULT D3DXGeneratePMesh(
  LPD3DXMESH pMesh,
  CONST DWORD* pAdjacency,
  CONST LPD3DXATTRIBUTEWEIGHTS pVertexAttributeWeights,
  CONST FLOAT* pVertexWeights,
  DWORD MinValue,
  DWORD Options,
  LPD3DXPMESH* ppPMesh
);

파라미터

pMesh
[in] 소스 메쉬를 나타내는 ID3DXMesh 인터페이스에의 포인터.
pAdjacency
[in] 생성 된 프로그래시브 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pVertexAttributeWeights
[in] 각 버텍스의 성분에 대한 가중을 저장 하는 D3DXATTRIBUTEWEIGHTS 구조체에의 포인터. 이 파라미터를 NULL 로 설정 하면, 디폴트의 구조체가 사용된다. 「주의」를 참조할것.
pVertexWeights
[in] 버텍스 가중의 배열에의 포인터. 이 파라미터를 NULL 로 설정 하면, 모든 버텍스 가중은 1.0 으로 설정된다. 버텍스 가중이 큰 만큼, 단순화 되기 어려운 것에 주의한다.
MinValue
[in] Options 파라미터로 설정되어 있는 플래그에 응한 버텍스 또는 면의 수. 이것에 의해, 소스 메쉬가 단순화 된다.
Options
[in] 메쉬에 대해서 단순화 옵션을 지정한다. 다음의 몇개의 플래그를 설정할 수 있다.
D3DXMESHSIMP_FACE
MinValue 파라미터로 지정한 수의 면에서 메쉬가 단순화 된다.
D3DXMESHSIMP_VERTEX
MinValue 파라미터로 지정한 수의 버텍스로써 메쉬가 단순화 된다.
ppPMesh
[out] 생성 된 프로그래시브 메쉬를 나타내는,ID3DXPMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DXERR_CANNOTATTRSORT
D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

이 함수는, LOD (Level of Detail)를 현재의 값으로부터 MinValue 까지 조절 가능한 경우에 메쉬를 생성한다.

단순화 프로세스에 의해 메쉬를 MinValue 까지 줄일 수가 없는 경우에서도 호출은 계속된다. 이것은,MinValue 가 절대적인 최소 값은 아니고, 희망의 최소 값이기 때문이다.

pVertexAttributeWeights 를 NULL 로 설정했을 경우, 다음에 나타내는 값이 디폴트의 D3DXATTRIBUTEWEIGHTS 구조체에 할당할 수 있다.

D3DXATTRIBUTEWEIGHTS AttributeWeights;

AttributeWeights.Position  = 1.0;
AttributeWeights.Boundary =  1.0;
AttributeWeights.Normal   =  1.0;
AttributeWeights.Diffuse  =  0.0;
AttributeWeights.Specular =  0.0;
AttributeWeights.Tex[8]   =  {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};

보통의 어플리케이션에서는, 이 디폴트의 구조체를 사용해야 한다. 이유는, 이 구조체가 지오메트리와 법선의 조정만을 목적으로 하고 있기 때문이다. 그 외의 멤버 필드를 수정할 필요가 있는 것은, 특별한 경우뿐이다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXIntersect

레이가 메쉬에 해당될지 어떨지를 판정한다.

HRESULT D3DXIntersect(
  LPD3DXBASEMESH pMesh,
  CONST D3DXVECTOR3* pRayPos,
  CONST D3DXVECTOR3* pRayDir,
  BOOL* pHit,
  DWORD* pFaceIndex,
  FLOAT* pU,
  FLOAT* pV,
  FLOAT* pDist
);

파라미터

pMesh
[in] 검증하는 메쉬를 나타내는,ID3DXBaseMesh 인터페이스에의 포인터.
pRayPos
[in] 레이의 시점 좌표를 지정하는 D3DXVECTOR3 구조체에의 포인터.
pRayDir
[in] 레이의 방향을 지정하는 D3DXVECTOR3 구조체에의 포인터.
pHit
[out] BOOL 에의 포인터. 레이가 메쉬의 삼각형의 면에 해당되는 경우, 이 값은 TRUE 로 설정된다. 그 이외의 경우, 이 값은 FALSE 로 설정된다.
pFaceIndex
[out] pHit 가 TRUE 의 경우, 레이의 시점에 가장 가까운 면의 인덱스값에의 포인터.
pU
[out] 중심 히트 좌표에의 포인터.
pV
[out] 중심 히트 좌표에의 포인터.
pDist
[out] 레이의 시점에서 교점까지의 거리에의 포인터.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는,E_OUTOFMEMORY 를 돌려준다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXLoadMeshFromX

Microsoft® DirectX® (. x) 파일로부터 메쉬를 로드한다.

HRESULT D3DXLoadMeshFromX(
  LPSTR pFilename,
  DWORD Options,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXBUFFER* ppAdjacency,
  LPD3DXBUFFER* ppMaterials,
  PDWORD pNumMaterials,
  LPD3DXMESH* ppMesh
);

파라미터

pFilename
[in] 로드하는 DirectX 파일의 이름을 지정하는 캐릭터 라인에의 포인터.
Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에 사용할 수 없다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼와 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 지정해 생성 된다. 이것은, 메쉬 오브젝트를 N 패치 강화를 사용해 Microsoft® Direct3D® 로 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppAdjacency
[out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열이 입력된다.
ppMaterials
[out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, Microsoft® DirectX® 파일에 보존된 정보를 저장 하는 D3DXMATERIAL 구조체의 배열이 입력된다.
pNumMaterials
[out] 메소드가 돌아왔을 때의 ppMaterials 배열내의 D3DXMATERIAL 구조체의 수에의 포인터.
ppMesh
[out] 로드 된 메쉬를 나타내는 ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주 파일내의 모든 메쉬가 1 개의 출력 메쉬에 정리한다. 파일에 프레임 계층이 저장 되고 있는 경우, 모든 트랜스 폼이 메쉬에 적용된다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXLoadMeshFromXof

Microsoft® DirectX® (. x) 파일 데이터 오브젝트로부터 메쉬를 로드한다.

HRESULT D3DXLoadMeshFromXof(
  LPDIRECTXFILEDATA pXofObjMesh,
  DWORD Options,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXBUFFER* ppAdjacency,
  LPD3DXBUFFER* ppMaterials,
  PDWORD pNumMaterials,
  LPD3DXMESH* ppMesh
);

파라미터

pXofObjMesh
[in] 로드하는 Microsoft® DirectX® 파일 데이터 오브젝트를 나타내는,IDirectXFileData 인터페이스에의 포인터.
Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에 사용할 수 없다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼와 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 지정해 생성 된다. 이것은, 메쉬 오브젝트를 N 패치 강화를 사용해 Microsoft® Direct3D® 로 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pD3DDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppAdjacency
[in, out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열이 입력된다.
ppMaterials
[in, out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는 D3DXMATERIAL 구조체의 배열이 입력된다.
pNumMaterials
[in, out] 메소드가 돌아왔을 때의 ppMaterials 배열내의 D3DXMATERIAL 구조체의 수에의 포인터.
ppMesh
[out, retval] 로드 된 메쉬를 나타내는 ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXLoadSkinMeshFromXof

Microsoft® DirectX® (. x) 파일 데이터 오브젝트로부터 스킨 메쉬를 로드한다.

HRESULT D3DXLoadSkinMeshFromXof(
  LPDIRECTXFILEDATA pXofObjMesh,
  DWORD Options,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXBUFFER* ppAdjacency,
  LPD3DXBUFFER* ppMaterials,
  PDWORD pMatOut,
  LPD3DXBUFFER* ppBoneNames,
  LPD3DXBUFFER* ppBoneTransforms,
  LPD3DXSKINMESH* ppMesh
);

파라미터

pXofObjMesh
[in] 로드하는 DirectX 파일 데이터 오브젝트를 나타내는,IDirectXFileData 인터페이스에의 포인터.
Options
[in] 메쉬의 생성 옵션을 지정하는 1 개(살) 이상의 플래그의 편성. 다음의 플래그가 정의되고 있다.
D3DXMESH_32BIT
메쉬에, 16 비트는 아니고 32 비트의 인덱스를 생성 한다. 32 비트의 메쉬는, 최대 2^32-1 의 면과 버텍스를 포함할 수가 있다. 이 플래그는 지원되어 있지 않기 때문에 사용할 수 없다.
D3DXMESH_DONOTCLIP
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_DONOTCLIP 이용 플래그를 사용한다.
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC 과 D3DXMESH_IB_DYNAMIC 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_RTPATCHES
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_RTPATCHES 이용 플래그를 사용한다.
D3DXMESH_NPATCHES
이 플래그를 지정 하면, 메쉬의 버텍스 버퍼와 인덱스 버퍼가 D3DUSAGE_NPATCHES 플래그를 지정해 생성 된다. 이것은, 메쉬 오브젝트를 N 패치 강화를 사용해 Microsoft® Direct3D 로 렌더링 하는 경우에 필요하다.
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED 와 D3DXMESH_IB_MANAGED 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_POINTS
버텍스 버퍼 및 인덱스 버퍼에 D3DUSAGE_POINTS 이용 플래그를 사용한다.
D3DXMESH_IB_DYNAMIC
인덱스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_IB_MANAGED
인덱스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_IB_SYSTEMMEM
인덱스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_IB_WRITEONLY
인덱스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM 과 D3DXMESH_IB_SYSTEMMEM 의 양쪽 모두를 지정한 것이 된다.
D3DXMESH_VB_DYNAMIC
버텍스 버퍼에 D3DUSAGE_DYNAMIC 이용 플래그를 사용한다.
D3DXMESH_VB_MANAGED
버텍스 버퍼에 D3DPOOL_MANAGED 메모리 클래스를 사용한다.
D3DXMESH_VB_SYSTEMMEM
버텍스 버퍼에 D3DPOOL_SYSTEMMEM 메모리 클래스를 사용한다.
D3DXMESH_VB_WRITEONLY
버텍스 버퍼에 D3DUSAGE_WRITEONLY 이용 플래그를 사용한다.
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY 와 D3DXMESH_IB_WRITEONLY 의 양쪽 모두를 지정한 것이 된다.
pD3DDevice
[in] 메쉬에 관련지을 수 있고 있는 디바이스 오브젝트를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppAdjacency
[in, out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열이 입력된다.
ppMaterials
[in, out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는 D3DXMATERIAL 구조체의 배열이 입력된다.
pMatOut
[in, out] 메소드가 돌아왔을 때의 ppMaterials 배열내의 D3DXMATERIAL 구조체의 수에의 포인터.
ppBoneNames
[in, out] 뼈명을 저장 하는 ID3DXBuffer 인터페이스에의 포인터의 주소.
ppBoneTransforms
[in, out] 뼈 트랜스 폼을 저장 하는 ID3DXBuffer 인터페이스에의 포인터의 주소.
ppMesh
[out, retval] 로드 된 메쉬를 나타내는 ID3DXSkinMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

이 메소드는,. x 파일내의 내부 오브젝트에의 포인터를 받아, 프레임 계층을 로드할 수 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXSaveMeshToX

메쉬를 Microsoft® DirectX® (. x) 파일에 보존한다.

HRESULT D3DXSaveMeshToX(
  LPSTR pFilename,
  LPD3DXMESH pMesh,
  CONST DWORD* pAdjacency,
  CONST LPD3DXMATERIAL pMaterials,
  DWORD NumMaterials,
  DWORD Format
);

파라미터

pFilename
[in] 메쉬가 보존되고 있는 DirectX 파일의 이름을 지정하는 캐릭터 라인에의 포인터.
pMesh
[in] DirectX 파일에 보존하는 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터.
pAdjacency
[in] 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pMaterials
[in] DirectX 파일에 보존되고 있는 머트리얼 정보를 저장 하는,D3DXMATERIAL 구조체의 배열에의 포인터.
NumMaterials
[in] rgMaterials array 내의 D3DXMATERIAL 구조체의 수.
Format
[in] DirectX 파일의 보존에 사용하는 포맷을 지정한다. 상세한 것에 대하여는, 「주의」를 참조할것.
DXFILEFORMAT_BINARY
바이노리필드를 지정한다.
DXFILEFORMAT_COMPRESSED
압축파일을 지정한다.
DXFILEFORMAT_TEXT
텍스트 파일을 지정한다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

파일 포맷의 디폴트값은, DXFILEFORMAT_BINARY 이다. 파일 포맷의 값은, 논리합을 사용해 조합하는 것이 가능해, 압축이 끝난 텍스트 파일이나 압축이 끝난 바이노리필드를 생성 할 수 있다. 파일이 바이너리 (0)와 텍스트 (1)의 양쪽 모두로 지정되고 있는 경우, 텍스트 파일로 보존된다. 이것은, 0 + 1 = 1 이 되는 것으로부터 텍스트 파일 포맷의 값과 구별이 붙지 않기 때문이다. 파일 포맷을 텍스트와 압축의 양쪽 모두로서 지정했을 경우, 파일은 우선 텍스트로서 출력되고 나서 압축된다. 다만, 압축이 끝난 텍스트 파일은 바이너리 텍스트 파일(정도)만큼 효율은 좋지 않다. 그 때문에, 보통은 바이너리와 압축을 지정하면 좋다. 포맷을 지정하지 않고 파일을 압축하도록(듯이) 설정 하면, 바이너리의 압축파일이 된다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXSimplifyMesh

메쉬를 단순화 한다.

HRESULT D3DXSimplifyMesh(
  LPD3DXMESH pMesh,
  CONST DWORD* pAdjacency,
  CONST LPD3DXATTRIBUTEWEIGHTS pVertexAttributeWeights,
  CONST FLOAT* pVertexWeights,
  DWORD MinValue,
  DWORD* Options,
  LPD3DXMESH* ppMesh
);

파라미터

pMesh
[in] 소스 메쉬를 나타내는 ID3DXMesh 인터페이스에의 포인터.
pAdjacency
[in] 단순화 하는 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
pVertexAttributeWeights
[in] 각 버텍스의 성분에 대한 가중을 저장 하는 D3DXATTRIBUTEWEIGHTS 구조체에의 포인터. 이 파라미터를 NULL 로 설정 하면, 디폴트의 구조체가 사용된다. 「주의」를 참조할것.
pVertexWeights
[in] 버텍스 가중의 배열에의 포인터. 이 파라미터를 NULL 로 설정 하면, 모든 버텍스 가중은 1.0 으로 설정된다.
MinValue
[in] Options 파라미터로 설정되어 있는 플래그에 응한 버텍스 또는 면의 수. 이것에 의해, 소스 메쉬가 단순화 된다.
Options
[in] 메쉬에 대해서 단순화 옵션을 지정한다. 다음의 몇개의 플래그를 설정할 수 있다.
D3DXMESHSIMP_FACE
MinValue 파라미터로 지정한 수의 면에서 메쉬가 단순화 된다.
D3DXMESHSIMP_VERTEX
MinValue 파라미터로 지정한 수의 버텍스로써 메쉬가 단순화 된다.
ppMesh
[out] 단순화 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

이 함수는,minValue 의 버텍스 또는 면을 가지는 메쉬를 생성한다.

단순화 프로세스에 의해 메쉬를 minValue 까지 줄일 수가 없는 경우에서도 호출은 계속된다. 이것은,minValue 가 절대적인 최소 값은 아니고, 희망의 최소 값이니까이다.

pVertexAttributeWeights 를 NULL 로 설정했을 경우, 다음에 나타내는 값이 디폴트의 D3DXATTRIBUTEWEIGHTS 구조체에 할당할 수 있다.

D3DXATTRIBUTEWEIGHTS AttributeWeights;

AttributeWeights.Position  = 1.0;
AttributeWeights.Boundary =  1.0;
AttributeWeights.Normal   =  1.0;
AttributeWeights.Diffuse  =  0.0;
AttributeWeights.Specular =  0.0;
AttributeWeights.Tex[8]   =  {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};

보통의 어플리케이션에서는, 이 디폴트의 구조체를 사용해야 한다. 이유는, 이 구조체가 지오메트리와 법선의 조정만을 목적으로 하고 있기 때문이다. 그 외의 멤버 필드를 수정할 필요가 있는 것은, 특별한 경우뿐이다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXSphereBoundProbe

레이가 경계구(공)의 볼륨에 해당될지 어떨지를 판정한다.

BOOL D3DXSphereBoundProbe(
  CONST D3DXVECTOR3* pCenter,
  FLOAT Radius,
  D3DXVECTOR3* pRayPosition,
  D3DXVECTOR3* pRayDirection
);

파라미터

pCenter
[in] 구(공)의 중심 좌표를 지정하는 D3DXVECTOR3 구조체에의 포인터.
Radius
[in] 구(공)의 반경.
pRayPosition
[in] 레이의 시점 좌표를 지정하는 D3DXVECTOR3 구조체에의 포인터.
pRayDirection
[in] 레이의 방향을 지정하는 D3DXVECTOR3 구조체에의 포인터.

반환값

레이가 경계구(공)의 볼륨에 해당되는 경우는, TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

주의

D3DXSphereBoundProbe 는, 레이가 구(공)의 표면 만이 아니고, 경계구(공)의 볼륨에 해당될지 어떨지를 판정한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXTesselateMesh

메쉬를 테셀레이트 한다.

HRESULT D3DXTesselateMesh(
  LPD3DXMESH pMeshIn,
  CONST DWORD* pAdjacency,
  FLOAT NumSegs,
  BOOL bQuadraticNormals
  LPD3DXMESH* ppMeshOut
);

파라미터

pMeshIn
[in] 테셀레이트 하는 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터.
pAdjacency
[in] 소스 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.
NumSegs
[in] 테셀레이트 하는 엣지 근처의 세그먼트(segment)수.
bQuadraticNormals
[in] 법선에 대해서 2차 보간을 사용하는 경우는, TRUE 로 설정한다. 선형 보간을 사용하는 경우는, FALSE 로 설정한다.
ppMeshOut
[out] 테셀레이션 된 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주 이 함수는, N 패치 알고리즘을 사용해 테셀레이트 한다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXValidMesh

메쉬를 검증한다.

HRESULT D3DXValidMesh(
  LPD3DXMESH pMeshIn,
  CONST DWORD* pAdjacency
);

파라미터

pMeshIn
[in] 검증하는 메쉬를 나타내는,ID3DXMesh 인터페이스에의 포인터.
pAdjacency
[in] 검증하는 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DXERR_INVALIDMESH
D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

이 메소드는, 2 개의 삼각형 팬이 같은 버텍스를 공유하는 경우에 무효인 인덱스의 유무를 확인해, 다른 버텍스를 추가하는 것으로써, 메쉬를 검증한다.

에러 정보는 디버그시의 출력으로부터 입수할 수 있다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXWeldVertices

복제된, 동일한 속성을 가지는 버텍스를 결합한다.

HRESULT D3DXValidMesh(
  CONST LPD3DXMESH pMesh,
  float fEpsilon,
  CONST DWORD* pAdjacencyIn,
  DWORD* pAdjacencyOut,
  DWORD* pFaceRemap,
  LPD3DXBUFFER* ppVertexRemap
);

파라미터

pMesh
[in] 버텍스 결합의 원이 되는 메쉬인 ID3DXMesh 오브젝트에의 포인터.
fEpsilon
[in] 버텍스가 결합되는, 버텍스 속성의 차이.
pAdjacencyIn

[in] 소스 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열에의 포인터. 이 파라미터가 NULL 의 경우,ID3DXMesh::GenerateAdjacency 가 불려 가, 논리 인접 천성보가 생성 된다.

pAdjacencyOut
[in, out] 최적화된 메쉬의 면인접성 배열에 사용하는 전송처 버퍼에의 포인터. 면인접성은, 배열의 배열로서 저장 된다. 가장 안쪽의 배열은, 인접하는 삼각형의 3 개의 인덱스로, 외측의 배열은, 메쉬내의 삼각형마다의 면인접성의 1 세트이다.
pFaceRemap
[out] 각면의 새로운 인덱스를 저장 하고 있는 전송처 버퍼에의 포인터.
ppVertexRemap
[out] 각 버텍스의 새로운 인덱스를 저장 하는,ID3DXBuffer 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

이 메소드는, 주어진 인접 천성보를 사용해, 복제하는 포인트를 지정한다. 이 메소드는, Epsilon 의 비교에 의해 버텍스를 결합한다. 동일한 위치를 가지는 버텍스가 미리 계산되어 포인트 표현 데이터에 의해 나타내지고 있을 필요가 있다.

이 메소드는 논리적으로 결합된 버텍스를 취득해, 같은 성분을 가지는 버텍스를 결합한다. fEpsilon 내의 법선 또는 fEpsilon 내의 텍스쳐 좌표 등이다.

동작환경

헤더 : D3dx8mesh.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


쉐이더 함수

Direct3DX 에서는 다음의 쉐이더 함수가 준비되어 있다.

  • D3DXAssembleShader
  • D3DXAssembleShaderFromFileA
  • D3DXAssembleShaderFromFileW

어셈블러는, 어셈블리 시작시에 버젼 토큰을 검출하지 않는 한, 버텍스 쉐이더 (버젼 1.0)를 어셈블(assemble) 하면 상정한다. Direct3DX 의 버텍스 쉐이더 및 픽셀 쉐이더의 어셈블러에 대해서는, 「Direct3DX 쉐이더 어셈블러 레퍼런스」를 참조할것.


D3DXAssembleShader

쉐이더의 소스가 메모리내에 있는 경우에, 쉐이더의 ASCII 기술을 바이너리 형식에 어셈블(assemble) 한다.

HRESULT D3DXAssembleShader(
  LPCVOID pSrcData,
  UINT SrcDataLen,
  DWORD Flags,
  LPD3DXBUFFER* ppConstants,
  LPD3DXBUFFER* ppCompiledShader,
  LPD3DXBUFFER* ppCompilationErrors
);

파라미터

pSrcData
[in] 원시 코드에의 포인터.
SrcDataLen
[in] 원시 코드의 사이즈 (바이트 단위).
Flags
[in] 어셈블리 옵션을 지정하는, 다음의 플래그의 편성.
D3DXASM_DEBUG
어셈블(assemble) 된 쉐이더에, 디버그 정보를 코멘트로서 삽입한다.
D3DXASM_SKIPVALIDATION
생성된 코드에 대해서 기존의 능력 및 제약의 검증을 하지 않는다. 이 옵션은, 동작하는 것을 알 수 있고 있는 쉐이더를 어셈블(assemble) 하는 경우 (즉, 전에 이 옵션을 사용하지 않고 쉐이더를 어셈블(assemble) 했던 적이 있는 경우)에게만 사용하는 것을 권한다.
ppConstants
[out] 돌려주어진 정수 선언을 나타내는,ID3DXBuffer 인터페이스에의 포인터를 돌려준다. 이러한 정수는, 버텍스 쉐이더 선언자 fragment로서 돌려주어진다. 어플리케이션은, 이 버퍼의 내용을 정수 선언에 삽입할 필요가 있다. 픽셀 쉐이더의 경우, 정수 선언은 어셈블(assemble) 된 쉐이더에 포함되기 (위해)때문에, 이 파라미터는 의미를 이루지 않는다. 이 파라미터가 NULL 의 경우는 무시된다.
ppCompiledShader
[out] 돌려주어진 컴파일 끝난 오브젝트 코드를 나타내는,ID3DXBuffer 인터페이스에의 포인터를 돌려준다. 이 파라미터가 NULL 의 경우는 무시된다.
ppCompilationErrors
[out] 돌려주어진 ASCII 에러 메세지를 나타내는,ID3DXBuffer 인터페이스에의 포인터를 돌려준다. 이 파라미터가 NULL 의 경우는 무시된다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXAssembleShaderFromFileA

원시 파일의 파일명이 ANSI 캐릭터 라인인 경우에, 쉐이더의 ASCII 기술을 바이너리 형식에 어셈블(assemble) 한다.

HRESULT D3DXAssembleShaderFromFileA(
  LPCSTR pSrcFile,
  DWORD Flags,
  LPD3DXBUFFER* ppConstants,
  LPD3DXBUFFER* ppCompiledShader,
  LPD3DXBUFFER* ppCompilationErrors
);

파라미터

pSrcFile
[in] 원시 파일명 (ANSI 형식)에의 포인터.
Flags
[in] 어셈블리 옵션을 지정하는, 다음의 플래그의 편성.
D3DXASM_DEBUG
어셈블(assemble) 된 쉐이더에, 디버그 정보를 코멘트로서 삽입한다.
D3DXASM_SKIPVALIDATION
생성된 코드에 대해서 기존의 능력 및 제약의 검증을 하지 않는다. 이 옵션은, 동작하는 것을 알 수 있고 있는 쉐이더를 어셈블(assemble) 하는 경우 (즉, 전에 이 옵션을 사용하지 않고 쉐이더를 어셈블(assemble) 했던 적이 있는 경우)에게만 사용하는 것을 권한다.
ppConstants
[out] 돌려주어진 정수 선언을 나타내는,ID3DXBuffer 인터페이스에의 포인터를 돌려준다. 이러한 정수는, 버텍스 쉐이더 선언자 fragment로서 돌려주어진다. 어플리케이션은, 이 버퍼의 내용을 정수 선언에 삽입할 필요가 있다. 픽셀 쉐이더의 경우, 정수 선언은 어셈블(assemble) 된 쉐이더에 포함되기 (위해)때문에, 이 파라미터는 의미를 이루지 않는다. 이 파라미터가 NULL 의 경우는 무시된다.
ppCompiledShader
[out] 돌려주어진 컴파일 끝난 오브젝트 코드를 나타내는,ID3DXBuffer 인터페이스에의 포인터를 돌려준다. 이 파라미터가 NULL 의 경우는 무시된다.
ppCompilationErrors
[out] 돌려주어진 ASCII 에러 메세지를 나타내는,ID3DXBuffer 인터페이스에의 포인터를 돌려준다. 이 파라미터가 NULL 의 경우는 무시된다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

D3DXAssembleShaderFromFile 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXAssembleShaderFromFileA 또는 D3DXAssembleShaderFromFileW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다.

다음의 코드는,D3DXAssembleShaderFromFile 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXAssembleShaderFromFile D3DXAssembleShaderFromFileW
#else
#define D3DXAssembleShaderFromFile D3DXAssembleShaderFromFileA
#endif

다음의 래퍼 함수 PreprocessAndAssembleShaderFromFile 의 예는, 버텍스 쉐이더 코드에 대해서 C 프리프로세서를 호출한 후,D3DXAssembleShaderFromFile 를 사용해 어셈블러를 호출하는 방법을 나타내고 있다.

HRESULT PreprocessAndAssembleShaderFromFile(
        LPCSTR          szFile,
        DWORD           Flags,
        LPD3DXBUFFER*   ppConstants,
        LPD3DXBUFFER*   ppCode,
        LPD3DXBUFFER*   ppErrors)
{
    char szPath[_MAX_PATH];
    char szTemp[_MAX_PATH];
    char szCmd [_MAX_PATH];

    GetTempPath(sizeof(szPath), szPath);
    GetTempFileName(szPath, "vsa", 0, szTemp);

    _snprintf(szCmd, sizeof(szCmd), "cl /nologo /E %s > %s", szFile, szTemp);

    if(0 ! = system(szCmd))
        return D3DERR_INVALIDCALL;

    return D3DXAssembleShaderFromFile(szTemp, Flags, ppConstants, ppCode, ppErrors);
}

이 함수가 기능하기 위해서는, Microsoft®Visual C++® 가 인스톨 되고 있어, 환경의 셋업에 의해 Cl.exe 의 패스가 설정되어 있을 필요가 있다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXAssembleShaderFromFileW


D3DXAssembleShaderFromFileW

원시 파일의 파일명이 Unicode 캐릭터 라인인 경우에, 쉐이더의 ASCII 기술을 바이너리 형식에 어셈블(assemble) 한다.

HRESULT D3DXAssembleShaderFromFileW(
  LPCWSTR pSrcFile,
  DWORD Flags,
  LPD3DXBUFFER* ppConstants,
  LPD3DXBUFFER* ppCompiledShader,
  LPD3DXBUFFER* ppCompilationErrors
);

파라미터

pSrcFile
[in] 원시 파일명 (Unicode 형식)에의 포인터.
Flags
[in] 어셈블리 옵션을 지정하는, 다음의 플래그의 편성.
D3DXASM_DEBUG
어셈블(assemble) 된 쉐이더에, 디버그 정보를 코멘트로서 삽입한다.
D3DXASM_SKIPVALIDATION
생성된 코드에 대해서 기존의 능력 및 제약의 검증을 하지 않는다. 이 옵션은, 동작하는 것을 알 수 있고 있는 쉐이더를 어셈블(assemble) 하는 경우 (즉, 전에 이 옵션을 사용하지 않고 쉐이더를 어셈블(assemble) 했던 적이 있는 경우)에게만 사용하는 것을 권한다.
ppConstants
[out] 돌려주어진 정수 선언을 나타내는,ID3DXBuffer 인터페이스에의 포인터를 돌려준다. 이러한 정수는, 버텍스 쉐이더 선언자 fragment로서 돌려주어진다. 어플리케이션은, 이 버퍼의 내용을 정수 선언에 삽입할 필요가 있다. 픽셀 쉐이더의 경우, 정수 선언은 어셈블(assemble) 된 쉐이더에 포함되기 (위해)때문에, 이 파라미터는 의미를 이루지 않는다. 이 파라미터가 NULL 의 경우는 무시된다.
ppCompiledShader
[out] 돌려주어진 컴파일 끝난 오브젝트 코드를 나타내는,ID3DXBuffer 인터페이스에의 포인터를 돌려준다. 이 파라미터가 NULL 의 경우는 무시된다.
ppCompilationErrors
[out] 돌려주어진 ASCII 에러 메세지를 나타내는,ID3DXBuffer 인터페이스에의 포인터를 돌려준다. 이 파라미터가 NULL 의 경우는 무시된다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

D3DXAssemblePixelShaderFromFile 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해, D3DXAssembleShaderFromFileA 또는 D3DXAssembleShaderFromFileW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다.

다음의 코드는,D3DXAssembleShaderFromFile 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXAssembleShaderFromFile D3DXAssembleShaderFromFileW
#else
#define D3DXAssembleShaderFromFile D3DXAssembleShaderFromFileA
#endif

다음의 래퍼 함수 PreprocessAndAssembleShaderFromFile 의 예는, 버텍스 쉐이더 코드에 대해서 C 프리프로세서를 호출한 후,D3DXAssembleShaderFromFile 를 사용해 어셈블러를 호출하는 방법을 나타내고 있다.

HRESULT
    PreprocessAndAssembleShaderFromFile(
        LPCSTR          szFile,
        DWORD           Flags,
        LPD3DXBUFFER*   ppConstants,
        LPD3DXBUFFER*   ppCode,
        LPD3DXBUFFER*   ppErrors)
{
    char szPath[_MAX_PATH];
    char szTemp[_MAX_PATH];
    char szCmd [_MAX_PATH];

    GetTempPath(sizeof(szPath), szPath);
    GetTempFileName(szPath, "vsa", 0, szTemp);

    _snprintf(szCmd, sizeof(szCmd), "cl /nologo /E %s > %s", szFile, szTemp);

    if(0 ! = system(szCmd))
        return D3DERR_INVALIDCALL;

    return D3DXAssembleShaderFromFile(szTemp, Flags, ppConstants, ppCode, ppErrors);
}

이 함수가 기능하기 위해서는, Microsoft®Visual C++® 가 인스톨 되고 있어, 환경의 셋업에 의해 Cl.exe 의 패스가 설정되어 있을 필요가 있다.

동작환경

헤더 : D3dx8core.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXAssembleShaderFromFileA


형상 드로잉(Drawing) 함수

Direct3DX 에서는 다음의 형상 드로잉(Drawing) 함수가 준비되어 있다.

  • D3DXCreateBox
  • D3DXCreateCylinder
  • D3DXCreatePolygon
  • D3DXCreateSphere
  • D3DXCreateTeapot
  • D3DXCreateTextA
  • D3DXCreateTextW
  • D3DXCreateTorus

모든 형태는, 메쉬 오브젝트로서 돌려주어진다.

위에 나타낸 함수는, 왼손 좌표계 또는 오른손 좌표계로 사용할 수 있다.


D3DXCreateBox

왼손 좌표계를 사용해, 축으로 따른 박스의 메쉬를 생성 한다.

HRESULT D3DXCreateBox(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT Width,
  FLOAT Height,
  FLOAT Depth,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

파라미터

pDevice
[in] 생성 되는 박스 메쉬에 관련지을 수 있는 디바이스를 나타내는IDirect3DDevice8 인터페이스에의 포인터.
Width
[in] x 축방향의 박스의 폭.
Height
[in] y 축방향의 박스의 높이.
Depth
[in] z 축방향의 박스의 깊이.
ppMesh
[out] ID3DXMesh 인터페이스의 출력 형상에의 포인터의 주소.
ppAdjacency
[out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열이 입력된다. NULL 를 지정할 수 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

생성 되는 박스의 중심은 원점이 된다.

동작환경

헤더 : D3dx8shape.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateCylinder

왼손 좌표계를 사용해, 원기둥(실린더)의 메쉬를 생성 한다.

HRESULT D3DXCreateCylinder(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT Radius1,
  FLOAT Radius2,
  FLOAT Length,
  UINT Slices,
  UINT Stacks,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

파라미터

pDevice
[in] 생성 되는 원기둥(실린더) 메쉬에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
Radius1
[in] z 축의 부의 옆의 면의 반경. 값은 0.0f 이상일 필요가 있다.
Radius2
[in] z 축의 정의 옆의 면의 반경. 값은 0.0f 이상일 필요가 있다.
Length
[in] z 축방향의 원기둥(실린더)의 길이.
Slices
[in] 주축을 회전축으로 한 슬라이스의 수.
Stacks
[in] 주축에 따른 스택수.
ppMesh
[out] ID3DXMesh 인터페이스의 출력 형상에의 포인터의 주소.
ppAdjacency
[out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열이 입력된다. NULL 를 지정할 수 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

생성 되는 원기둥(실린더)는, 중심이 원점이 되어, 축은 z 축방향이 된다.

동작환경

헤더 : D3dx8shape.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreatePolygon

왼손 좌표계를 사용해, n 면의 다각형의 메쉬를 생성 한다.

HRESULT D3DXCreatePolygon(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT Length,
  UINT Sides,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

파라미터

pDevice
[in] 생성 되는 다각형 메쉬에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
Length
[in] 각면의 길이.
Sides
[in] 다각형의 면수. 값은 3 이상일 필요가 있다.
ppMesh
[out] ID3DXMesh 인터페이스의 출력 형상에의 포인터의 주소.
ppAdjacency
[out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열이 입력된다. NULL 를 지정할 수 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

생성 되는 다각형의 중심은 원점이 된다.

동작환경

헤더 : D3dx8shape.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateSphere

왼손 좌표계를 사용해, 구(공)의 메쉬를 생성 한다.

HRESULT D3DXCreateSphere(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT Radius,
  UINT Slices,
  UINT Stacks,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

파라미터

pDevice
[in] 생성 되는 구(공) 메쉬에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
Radius
[in] 구(공)의 반경. 이 값은 0.0f 이상일 필요가 있다.
Slices
[in] 주축을 회전축으로 한 슬라이스의 수.
Stacks
[in] 주축에 따른 스택수.
ppMesh
[out] ID3DXMesh 인터페이스의 출력 형상에의 포인터의 주소.
ppAdjacency
[out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열이 입력된다. NULL 를 지정할 수 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

생성 되는 구(공)은, 중심이 원점이 되어, 축은 z 축방향이 된다.

동작환경

헤더 : D3dx8shape.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateTeapot

왼손 좌표계를 사용해, 티폿트의 메쉬를 생성 한다.

HRESULT D3DXCreateTeapot(
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

파라미터

pDevice
[in] 생성 되는 티폿트멧슈에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
ppMesh
[out] ID3DXMesh 인터페이스의 출력 형상에의 포인터의 주소.
ppAdjacency
[out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열이 입력된다. NULL 를 지정할 수 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

동작환경

헤더 : D3dx8shape.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateTextA

디바이스 콘텍스트에 관련지을 수 있고 있는 폰트를 사용해, 지정한 ANSI 텍스트의 메쉬를 생성 한다.

HRESULT D3DXCreateTextA(
  LPDIRECT3DDEVICE8 pDevice,
  HDC hDC,
  LPCSTR pText,
  FLOAT Deviation,
  FLOAT Extrusion,
  LPD3DXMESH* ppMesh,
  LPGLYPHMETRICSFLOAT pGlyphMetrics
);

파라미터

pDevice
[in] 생성 된 텍스트 메쉬에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
hDC
[in] 출력용의 폰트를 저장 하고 있는 디바이스의 문맥. 디바이스의 문맥에 의해 선택되는 폰트는, TrueType 폰트가 아니면 안된다.
pText
[in] 생성하는 텍스트를 지정하는 ANSI 캐릭터 라인에의 포인터.
Deviation
[in] TRUE 폰트 아우트라인으로부터의 최대 코드 편차.
Extrusion
[in] z 축의 부의 방향으로 밀어 내지는 텍스트의 양.
ppMesh
[out] ID3DXMesh 인터페이스의 출력 형상에의 포인터의 주소.
pGlyphMetrics
[out] 그리후메트릭크데이타를 받는 GLYPHMETRICSFLOAT 구조체의 배열에의 포인터. 배열내의 각 GLYPHMETRICSFLOAT 구조체에는, 캐릭터 라인내의 대응하는 그리후의, 배치와 향해에 관한 정보가 저장 된다. 배열내의 요소의 수는, 캐릭터 라인의 문자수로 동일하지 않으면 안 된다. 각 구조 체내의 시점은, 캐릭터 라인 전체에 대해서 상대적은 아니고, 그 문자 셀에 대해서 상대적이다. 경계 박스 전체의 연산을 실시하려면 , 캐릭터 라인을 암벽 횡단 하는 동안 그리후 마다 증분을 추가한다.

그리후사이즈를 고려할 필요가 없는 경우는,pGlyphMetrics 에 NULL 를 건네줄 수가 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

D3DXCreateText 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextA 또는 D3DXCreateTextW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateText 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateText D3DXCreateTextW
#else
#define D3DXCreateText D3DXCreateTextA
#endif

GLYPHMETRICSFLOAT 구조체의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것.

동작환경

헤더 : D3dx8shape.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextW


D3DXCreateTextW

디바이스 콘텍스트에 관련지을 수 있고 있는 폰트를 사용해, 지정한 Unicode 텍스트의 메쉬를 생성 한다.

HRESULT D3DXCreateTextW(
  LPDIRECT3DDEVICE8 pDevice,
  HDC hDC,
  LPCSTR pText,
  FLOAT Deviation,
  FLOAT Extrusion,
  LPD3DXMESH* ppMesh,
  LPGLYPHMETRICSFLOAT pGlyphMetrics
);

파라미터

pDevice
[in] 생성 된 텍스트 메쉬에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
hDC
[in] 출력용의 폰트를 저장 하고 있는 디바이스의 문맥. 디바이스의 문맥에 의해 선택되는 폰트는, TrueType 폰트가 아니면 안된다.
pText
[in] 생성하는 텍스트를 지정하는 Unicode 캐릭터 라인에의 포인터.
Deviation
[in] TRUE 폰트 아우트라인으로부터의 최대 코드 편차.
Extrusion
[in] z 축의 부의 방향으로 밀어 내지는 텍스트의 양.
ppMesh
[out] ID3DXMesh 인터페이스의 출력 형상에의 포인터의 주소.
pGlyphMetrics
[out] 그리후메트릭크데이타를 받는 GLYPHMETRICSFLOAT 구조체의 배열에의 포인터. 배열내의 각 GLYPHMETRICSFLOAT 구조체에는, 캐릭터 라인내의 대응하는 그리후의, 배치와 향해에 관한 정보가 저장 된다. 배열내의 요소의 수는, 캐릭터 라인의 문자수로 동일하지 않으면 안 된다. 각 구조 체내의 시점은, 캐릭터 라인 전체에 대해서 상대적은 아니고, 그 문자 셀에 대해서 상대적이다. 경계 박스 전체의 연산을 실시하려면 , 캐릭터 라인을 암벽 횡단 하는 동안 그리후 마다 증분을 추가한다.

그리후사이즈를 고려할 필요가 없는 경우는,pGlyphMetrics 에 NULL 를 건네줄 수가 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

D3DXCreateText 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextA 또는 D3DXCreateTextW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateText 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateText D3DXCreateTextW
#else
#define D3DXCreateText D3DXCreateTextA
#endif

GLYPHMETRICSFLOAT 구조체의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것.

동작환경

헤더 : D3dx8shape.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextA


D3DXCreateTorus

왼손 좌표계를 사용해, 원환체의 메쉬를 생성 한다.

HRESULT D3DXCreateTorus(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT InnerRadius,
  FLOAT OuterRadius,
  UINT Sides,
  UINT Rings,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

파라미터

pDevice
[in] 생성 되는 원환체 메쉬에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
InnerRadius
[in] 원환체의 내부의 반경. 값은 0.0f 이상일 필요가 있다.
OuterRadius
[in] 원환체의 외부의 반경. 값은 0.0f 이상일 필요가 있다.
Sides
[in] 횡단면의 옆의 수. 값은 3 이상일 필요가 있다.
Rings
[in] 원환체를 구성하는 환의 수. 값은 3 이상일 필요가 있다.
ppMesh
[out] ID3DXMesh 인터페이스의 출력 형상에의 포인터의 주소.
ppAdjacency
[out] ID3DXBuffer 인터페이스에의 포인터의 주소. 메소드가 돌아가면(자), 이 파라미터에는, 메쉬에 포함되는 각면의 3 개의 인접면을 지정하는, 1 면근처의 3 개의 DWORD 의 배열이 입력된다. NULL 를 지정할 수 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

D3DXCreateTorus 함수는, 중심이 (0, 0, 0)로 축이 z 축방향의 도너츠형의 도형 (원환체)을 드로잉(Drawing) 한다. 이 원환체의 내부의 반경은 횡단면의 반경 (작은 (분)편의 반경), 외부의 반경은 중앙의 구멍의 반경이다.

이 함수는, 다음에 어플리케이션에 의해 드로잉(Drawing) 하거나 조작할 경우에 사용할 수 있는 메쉬를 돌려준다.

동작환경

헤더 : D3dx8shape.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


텍스쳐 함수

Direct3DX 에서는 다음의 텍스쳐 함수가 준비되어 있다.

  • D3DXCheckCubeTextureRequirements
  • D3DXCheckTextureRequirements
  • D3DXCheckVolumeTextureRequirements
  • D3DXCreateCubeTexture
  • D3DXCreateCubeTextureFromFileA
  • D3DXCreateCubeTextureFromFileExA
  • D3DXCreateCubeTextureFromFileExW
  • D3DXCreateCubeTextureFromFileInMemory
  • D3DXCreateCubeTextureFromFileInMemoryEx
  • D3DXCreateCubeTextureFromFileW
  • D3DXCreateTexture
  • D3DXCreateTextureFromFileA
  • D3DXCreateTextureFromFileExA
  • D3DXCreateTextureFromFileExW
  • D3DXCreateTextureFromFileInMemory
  • D3DXCreateTextureFromFileInMemoryEx
  • D3DXCreateTextureFromFileW
  • D3DXCreateTextureFromResourceA
  • D3DXCreateTextureFromResourceExA
  • D3DXCreateTextureFromResourceExW
  • D3DXCreateTextureFromResourceW
  • D3DXCreateVolumeTexture
  • D3DXFilterCubeTexture
  • D3DXFilterTexture
  • D3DXFilterVolumeTexture
  • D3DXLoadSurfaceFromFileA
  • D3DXLoadSurfaceFromFileInMemory
  • D3DXLoadSurfaceFromFileW
  • D3DXLoadSurfaceFromMemory
  • D3DXLoadSurfaceFromResourceA
  • D3DXLoadSurfaceFromResourceW
  • D3DXLoadSurfaceFromSurface
  • D3DXLoadVolumeFromMemory
  • D3DXLoadVolumeFromVolume


D3DXCheckCubeTextureRequirements

큐브 텍스쳐 생성 파라미터를 확인한다.

HRESULT D3DXCheckCubeTextureRequirements(
  LPDIRECT3DDEVICE8 pDevice,
  UINT* pSize,
  UINT* pNumMipLevels,
  DWORD Usage,
  D3DFORMAT* pFormat,
  D3DPOOL Pool
);

파라미터

pDevice
[in] 큐브 텍스쳐에 관련지을 수 있는 디바이스를 나타내는IDirect3DDevice8 인터페이스에의 포인터.
pSize
[in, out] 요구되는 폭과 높이 (픽셀 단위)에의 포인터, 또는 NULL. 정정 후의 사이즈를 돌려준다.
pNumMipLevels
[in, out] 요구되는 밉맵 레벨의 수에의 포인터, 또는 NULL. 정정 후의 밉맵 레벨의 수를 돌려준다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그를 D3DUSAGE_RENDERTARGET 로 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 하고 있는 것을 확인할 필요가 있다.
pFormat
[in, out] D3DFORMAT 열거형의 멤버에의 포인터. 요구되는 픽셀 포맷 또는 NULL 를 지정한다. 정정 후의 포맷을 돌려준다.
Pool
[in] 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_INVALIDCALL

주의

이 함수의 파라미터가 무효의 경우, 이 함수는 수정한 파라미터를 돌려준다.

큐브 텍스쳐는, 표면의 콜렉션인 점으로써 다른 표면과는 다르다. 큐브 텍스쳐를 지정해 SetRenderTarget 을 호출하려면 ,IDirect3DCubeTexture8::GetCubeMapSurface 를 사용해 개개의 면을 선택해, 결과 표면을 SetRenderTarget 에 건네줄 필요가 있다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCheckTextureRequirements

텍스쳐 생성 파라미터를 확인한다.

HRESULT D3DXCheckTextureRequirements(
  LPDIRECT3DDEVICE8 pDevice,
  UINT* pWidth,
  UINT* pHeight,
  UINT* pNumMipLevels,
  DWORD Usage,
  D3DFORMAT* pFormat,
  D3DPOOL Pool
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pWidth
[in, out] 요구되는 폭 (픽셀 단위)에의 포인터, 또는 NULL. 정정 후의 사이즈를 돌려준다.
pHeight
[in, out] 요구되는 높이 (픽셀 단위)에의 포인터, 또는 NULL. 정정 후의 사이즈를 돌려준다.
pNumMipLevels
[in, out] 요구되는 밉맵 레벨의 수에의 포인터, 또는 NULL. 정정 후의 밉맵 레벨의 수를 돌려준다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그를 D3DUSAGE_RENDERTARGET 로 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 하고 있는 것을 확인할 필요가 있다.
pFormat
[in, out] D3DFORMAT 열거형의 멤버에의 포인터. 요구되는 픽셀 포맷 또는 NULL 를 지정한다. 정정 후의 포맷을 돌려준다.
Pool
[in] 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_INVALIDCALL

주의

이 함수의 파라미터가 무효의 경우, 이 함수는 수정한 파라미터를 돌려준다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCheckVolumeTextureRequirements

볼륨 텍스쳐 생성 파라미터를 확인한다.

HRESULT D3DXCheckVolumeTextureRequirements(
  LPDIRECT3DDEVICE8 pDevice,
  UINT* pWidth,
  UINT* pHeight,
  UINT* pDepth,
  UINT* pNumMipLevels,
  DWORD Usage,
  D3DFORMAT* pFormat,
  D3DPOOL Pool
);

파라미터

pDevice
[in] 볼륨 텍스쳐에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pWidth
[in, out] 요구되는 폭 (픽셀 단위)에의 포인터, 또는 NULL. 정정 후의 사이즈를 돌려준다.
pHeight
[in, out] 요구되는 높이 (픽셀 단위)에의 포인터, 또는 NULL. 정정 후의 사이즈를 돌려준다.
pDepth
[in, out] 요구되는 깊이 (픽셀 단위)에의 포인터, 또는 NULL. 정정 후의 사이즈를 돌려준다.
pNumMipLevels
[in, out] 요구되는 밉맵 레벨의 수에의 포인터, 또는 NULL. 정정 후의 밉맵 레벨의 수를 돌려준다.
Usage
[in] 현시점에서는 미사용이므로 0 을 설정해 둔다.
pFormat
[in, out] D3DFORMAT 열거형의 멤버에의 포인터. 요구되는 픽셀 포맷 또는 NULL 를 지정한다. 정정 후의 포맷을 돌려준다.
Pool
[in] 볼륨 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_INVALIDCALL

주의

이 함수의 파라미터가 무효의 경우, 이 함수는 수정한 파라미터를 돌려준다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateCubeTexture

필요에 따라서 호출해 파라미터를 조정해, 하늘의 큐브 텍스쳐를 생성 한다.

HRESULT D3DXCreateCubeTexture(
  LPDIRECT3DDEVICE8 pDevice,
  UINT Size,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
Size
[in] 큐브 텍스쳐의 폭과 높이 (픽셀 단위). 예를 들어, 큐브 텍스쳐가 8x8 픽셀의 큐브의 경우, 이 파라미터의 값은 8 이 된다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 하고 있는 것을 확인할 필요가 있다.
Format
[in] 큐브 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는,D3DFORMAT 열거형의 멤버. 돌려주어지는 큐브 텍스쳐의 포맷은,Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 큐브 텍스쳐의 포맷을 확인할 필요가 있다.
Pool
[in] 큐브 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
ppCubeTexture
[out] 생성 된 큐브 텍스쳐 오브젝트를 나타내는,IDirect3DCubeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

주의

큐브 텍스쳐는, 표면의 콜렉션인 점으로써 다른 표면과는 다르다. 큐브 텍스쳐를 지정해 SetRenderTarget 을 호출하려면 ,IDirect3DCubeTexture8::GetCubeMapSurface 를 사용해 개개의 면을 선택해, 결과 표면을 SetRenderTarget 에 건네줄 필요가 있다.

D3DXCreateCubeTexture 는, 내부에서 D3DXCheckCubeTextureRequirements 를 사용해 호출 파라미터를 조정한다. 따라서,IDirect3Ddevice8::CreateCubeTexture 의 호출이 실패하는 경우에서도,D3DXCreateCubeTexture 의 호출은 성공하는 것이 많다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateCubeTextureFromFileA

ANSI 캐릭터 라인으로 지정한 파일을 바탕으로 해 큐브 텍스쳐를 생성 한다.

D3DXCreateCubeTextureFromFile 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateCubeTextureFromFileA 또는 D3DXCreateCubeTextureFromFileW 의 어느 쪽인지를 맵 한다. 「주의」를 참조할것.

HRESULT D3DXCreateCubeTextureFromFileA(
  LPDIRECT3DDEVICE8 pDevice,
  LPCSTR pSrcFile,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

파라미터

pDevice
[in] 큐브 텍스쳐에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcFile
[in] 큐브 텍스쳐의 생성에 사용하는 파일을 지정하는 ANSI 캐릭터 라인에의 포인터. 「주의」를 참조할것.
ppCubeTexture
[out] 생성 된 큐브 텍스쳐 오브젝트를 나타내는,IDirect3DCubeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

#define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateCubeTextureFromFile 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateCubeTextureFromFile D3DXCreateCubeTextureFromFileW
#else
#define D3DXCreateCubeTextureFromFile D3DXCreateCubeTextureFromFileA
#endif

이 함수를 사용해 생성 한 리소스는, D3DPOOL_MANAGED 로 나타나는 메모리 클래스에 배치된다.

D3DXCreateCubeTextureFromFileA 는, DirectDrawSurface (DDS) 파일 포맷을 사용한다. DXTex 툴에 의해, 다른 파일 포맷화등 큐브 맵을 생성해, 그것을 DDS 파일 포맷으로 보존할 수가 있다.

동작환경

헤더 : d3dx8mesh.h 로 선언.

참조

D3DXCreateCubeTextureFromFileW


D3DXCreateCubeTextureFromFileExA

ANSI 캐릭터 라인으로 지정한 파일을 바탕으로 해 큐브 텍스쳐를 생성 한다. 이것은,D3DXCreateCubeTextureFromFileA 보다 고도의 함수이다.

D3DXCreateCubeTextureFromFileEx 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateCubeTextureFromFileExA 또는 D3DXCreateCubeTextureFromFileExW 의 어느 쪽인지를 맵 한다. 「주의」를 참조할것.

HRESULT D3DXCreateCubeTextureFromFileExA(
  LPDIRECT3DDEVICE8 pDevice,
  LPCSTR pSrcFile,
  UINT Size,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

파라미터

pDevice
[in] 큐브 텍스쳐에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcFile
[in] 큐브 텍스쳐의 생성에 사용하는 파일을 지정하는 ANSI 캐릭터 라인에의 포인터. 「주의」를 참조할것.
Size
[in] 큐브 텍스쳐의 폭과 높이 (픽셀 단위). 예를 들어, 큐브 텍스쳐가 8x8 픽셀의 큐브의 경우, 이 파라미터의 값은 8 이 된다. 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 하고 있는 것을 확인할 필요가 있다.
Format
[in] 큐브 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는,D3DFORMAT 열거형의 멤버. 돌려주어지는 큐브 텍스쳐의 포맷은,Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 큐브 텍스쳐의 포맷을 확인할 필요가 있다. Format 의 값이 D3DFMT_UNKNOWN 의 경우, 포맷은 파일로부터 취득된다.
Pool
[in] 큐브 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다. 내부적으로는, 항상 D3DX_FILTER_MIRROR 플래그가 사용된다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다. 이 플래그는, 이 함수에서는 항상 내부적으로 사용된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
MipFilter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다. 내부적으로는, 항상 D3DX_FILTER_MIRROR 플래그가 사용된다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다. 이 플래그는, 이 함수에서는 항상 내부적으로 사용된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
ppCubeTexture
[out] 생성 된 큐브 텍스쳐 오브젝트를 나타내는,IDirect3DCubeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

큐브 텍스쳐는, 표면의 콜렉션인 점으로써 다른 표면과는 다르다. 큐브 텍스쳐를 지정해 SetRenderTarget 을 호출하려면 ,IDirect3DCubeTexture8::GetCubeMapSurface 를 사용해 개개의 면을 선택해, 결과 표면을 SetRenderTarget 에 건네줄 필요가 있다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX 8.0® 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

#define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateCubeTextureFromFileEx 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateCubeTextureFromFileEx D3DXCreateCubeTextureFromFileExW
#else
#define D3DXCreateCubeTextureFromFileEx D3DXCreateCubeTextureFromFileExA
#endif

D3DXCreateCubeTextureFromFileExA 는, DirectDrawSurface (DDS) 파일 포맷을 사용한다. DXTex 툴에 의해, 다른 파일 포맷화등 큐브 맵을 생성해, 그것을 DDS 파일 포맷으로 보존할 수가 있다.

동작환경

헤더 : d3dx8mesh.h 로 선언.

참조

D3DXCreateCubeTextureFromFileExW


D3DXCreateCubeTextureFromFileExW

Unicode 캐릭터 라인으로 지정된 파일로부터 큐브 텍스쳐를 생성 한다. 이것은,D3DXCreateCubeTextureFromFileW 보다 고도의 함수이다.

D3DXCreateCubeTextureFromFileEx 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateCubeTextureFromFileExA 또는 D3DXCreateCubeTextureFromFileExW 의 어느 쪽인지를 맵 한다. 「주의」를 참조할것.

HRESULT D3DXCreateCubeTextureFromFileExW(
  LPDIRECT3DDEVICE8 pDevice,
  LPCWSTR pSrcFile,
  UINT Size,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

파라미터

pDevice
[in] 큐브 텍스쳐에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcFile
[in] 큐브 텍스쳐의 생성에 사용하는 파일을 지정하는 Unicode 캐릭터 라인에의 포인터. 「주의」를 참조할것.
Size
[in] 큐브 텍스쳐의 폭과 높이 (픽셀 단위). 예를 들어, 큐브 텍스쳐가 8x8 픽셀의 큐브의 경우, 이 파라미터의 값은 8 이 된다. 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 하고 있는 것을 확인할 필요가 있다. 「주의」를 참조할것.
Format
[in] 큐브 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는,D3DFORMAT 열거형의 멤버. 돌려주어지는 큐브 텍스쳐의 포맷은 Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 큐브 텍스쳐의 포맷을 확인할 필요가 있다. Format 가 D3DFMT_UNKNOWN 의 경우, 포맷은 파일로부터 취득된다.
Pool
[in] 큐브 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다. 내부적으로는, 항상 D3DX_FILTER_MIRROR 플래그가 사용된다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다. 이 플래그는, 이 함수에서는 항상 내부적으로 사용된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
MipFilter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다. 내부적으로는, 항상 D3DX_FILTER_MIRROR 플래그가 사용된다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다. 이 플래그는, 이 함수에서는 항상 내부적으로 사용된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
ppCubeTexture
[out] 생성 된 큐브 텍스쳐 오브젝트를 나타내는,IDirect3DCubeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

큐브 텍스쳐는, 표면의 콜렉션인 점으로써 다른 표면과는 다르다. 큐브 텍스쳐를 지정해 SetRenderTarget 을 호출하려면 ,IDirect3DCubeTexture8::GetCubeMapSurface 를 사용해 개개의 면을 선택해, 결과 표면을 SetRenderTarget 에 건네줄 필요가 있다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

#define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateCubeTextureFromFileEx 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateCubeTextureFromFileEx D3DXCreateCubeTextureFromFileExW
#else
#define D3DXCreateCubeTextureFromFileEx D3DXCreateCubeTextureFromFileExA
#endif

D3DXCreateCubeTextureFromFileExW 는, DirectDrawSurface (DDS) 파일 포맷을 사용한다. DXTex 툴에 의해, 다른 파일 포맷화등 큐브 맵을 생성해, 그것을 DDS 파일 포맷으로 보존할 수가 있다.

동작환경

헤더 : d3dx8mesh.h 로 선언.

참조

D3DXCreateCubeTextureFromFileExA


D3DXCreateCubeTextureFromFileInMemory

메모리내의 파일로부터 큐브 텍스쳐를 생성 한다.

HRESULT D3DXCreateCubeTextureFromFileInMemory(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID pSrcData,
  UINT SrcDataSize,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

파라미터

pDevice
[in] 큐브 텍스쳐에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcData
[in] 큐브 맵의 생성에 사용하는 메모리내의 파일에의 포인터. 「주의」를 참조할것.
SrcDataSize
[in] 메모리내의 파일의 사이즈 (바이트 단위).
ppCubeTexture
[out] 생성 된 큐브 텍스쳐 오브젝트를 나타내는,IDirect3DCubeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

이 함수를 사용해 생성 한 리소스는, D3DPOOL_MANAGED 로 나타나는 메모리 클래스에 배치된다.

이 메소드는, 어플리케이션 정의의 리소스 (미가공 데이터)인, RT_RCDATA 로서 저장 된 이미지 파일을 로드하기 위해서(때문에) 사용하도록(듯이) 설계되고 있다. 그 이외의 목적으로 사용 하면, 이 메소드는 실패한다.

D3DXCreateCubeTextureFromFileInMemory 는, DirectDrawSurface (DDS) 파일 포맷을 사용한다. DXTex 툴에 의해, 다른 파일 포맷화등 큐브 맵을 생성해, 그것을 DDS 파일 포맷으로 보존할 수가 있다.

동작환경

헤더 : d3dx8mesh.h 로 선언.


D3DXCreateCubeTextureFromFileInMemoryEx

메모리내의 파일로부터 큐브 텍스쳐를 생성 한다. 이것은,D3DXCreateCubeTextureFromFileInMemory 보다 고도의 함수이다.

HRESULT D3DXCreateCubeTextureFromFileInMemoryEx(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID pSrcData,
  UINT SrcDataSize,
  UINT Size,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

파라미터

pDevice
[in] 큐브 텍스쳐에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcData
[in] 큐브 텍스쳐의 생성에 사용하는 메모리내의 파일에의 포인터. 「주의」를 참조할것.
SrcDataSize
[in] 메모리내의 파일의 사이즈 (바이트 단위).
Size
[in] 폭과 높이 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 하고 있는 것을 확인할 필요가 있다. 「주의」를 참조할것.
Format
[in] 큐브 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는,D3DFORMAT 열거형의 멤버. 돌려주어지는 텍스쳐의 포맷은 Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 텍스쳐의 포맷을 확인할 필요가 있다. Format 가 D3DFMT_UNKNOWN 의 경우, 포맷은 파일로부터 취득된다.
Pool
[in] 큐브 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다. 내부적으로는, 항상 D3DX_FILTER_MIRROR 플래그가 사용된다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다. 이 플래그는, 이 함수에서는 항상 내부적으로 사용된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
MipFilter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다. 내부적으로는, 항상 D3DX_FILTER_MIRROR 플래그가 사용된다

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다. 이 플래그는, 이 함수에서는 항상 내부적으로 사용된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
ppCubeTexture
[out] 생성 된 큐브 텍스쳐 오브젝트를 나타내는,IDirect3DCubeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

큐브 텍스쳐는, 표면의 콜렉션인 점으로써 다른 표면과는 다르다. 큐브 텍스쳐를 지정해 SetRenderTarget 을 호출하려면 ,IDirect3DCubeTexture8::GetCubeMapSurface 를 사용해 개개의 면을 선택해, 결과 표면을 SetRenderTarget 에 건네줄 필요가 있다.

이 메소드는, 어플리케이션 정의의 리소스 (미가공 데이터)인, RT_RCDATA 로서 저장 된 이미지 파일을 로드하기 위해서(때문에) 사용하도록(듯이) 설계되고 있다. 그 이외의 목적으로 사용 하면, 이 메소드는 실패한다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

D3DXCreateCubeTextureFromFileInMemoryEx 는, DirectDrawSurface (DDS) 파일 포맷을 사용한다. DXTex 툴에 의해, 다른 파일 포맷화등 큐브 맵을 생성해, 그것을 DDS 파일 포맷으로 보존할 수가 있다.

동작환경

헤더 : d3dx8mesh.h 로 선언.


D3DXCreateCubeTextureFromFileW

Unicode 캐릭터 라인으로 지정된 파일로부터 큐브 텍스쳐를 생성 한다.

D3DXCreateCubeTextureFromFile 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateCubeTextureFromFileA 또는 D3DXCreateCubeTextureFromFileW 의 어느 쪽인지를 맵 한다.

HRESULT D3DXCreateCubeTextureFromFileW(
  LPDIRECT3DDEVICE8 pDevice,
  LPCWSTR pSrcFile,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

파라미터

pDevice
[in] 큐브 텍스쳐에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcFile
[in] 큐브 텍스쳐의 생성에 사용하는 파일을 지정하는 Unicode 캐릭터 라인에의 포인터. 「주의」를 참조할것.
ppCubeTexture
[out] 생성 된 큐브 텍스쳐 오브젝트를 나타내는,IDirect3DCubeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

#define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateCubeTextureFromFile 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateCubeTextureFromFile D3DXCreateCubeTextureFromFileW
#else
#define D3DXCreateCubeTextureFromFile D3DXCreateCubeTextureFromFileA
#endif

이 함수를 사용해 생성 한 리소스는, D3DPOOL_MANAGED 로 나타나는 메모리 클래스에 배치된다.

D3DXCreateCubeTextureFromFileInMemoryW 는, DirectDrawSurface (DDS) 파일 포맷을 사용한다. DXTex 툴에 의해, 다른 파일 포맷화등 큐브 맵을 생성해, 그것을 DDS 파일 포맷으로 보존할 수가 있다.

동작환경

헤더 : d3dx8mesh.h 로 선언.

참조

D3DXCreateCubeTextureFromFileA


D3DXCreateTexture

필요에 따라서 호출해 파라미터를 조정해, 하늘의 텍스쳐를 생성 한다.

HRESULT D3DXCreateTexture(
  LPDIRECT3DDEVICE8 pDevice,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
Width
[in] 폭 (픽셀 단위). 이 값은 0 이외일 필요가 있다.
Height
[in] 높이 (픽셀 단위). 이 값은 0 이외일 필요가 있다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 하고 있는 것을 확인할 필요가 있다.
Format
[in] 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는 D3DFORMAT 열거형의 멤버. 돌려주어지는 텍스쳐의 포맷은 Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 텍스쳐의 포맷을 확인할 필요가 있다.
Pool
[in] 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

D3DXCreateTexture 는, 내부에서 D3DXCheckTextureRequirements 를 사용해 호출 파라미터를 조정한다. 따라서,IDirect3Ddevice8::CreateTexture 의 호출이 실패하는 경우에서도,D3DXCreateTexture 의 호출은 성공하는 것이 많다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXCreateTextureFromFileA

ANSI 캐릭터 라인으로 지정한 파일을 바탕으로 해 텍스쳐를 생성 한다.

HRESULT D3DXCreateTextureFromFileA(
  LPDIRECT3DDEVICE8 pDevice,
  LPCSTR pSrcFile,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcFile
[in] 텍스쳐의 생성에 사용하는 파일을 지정하는 ANSI 캐릭터 라인에의 포인터.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

밉맵 된 텍스쳐의 각 레벨에는, 로드 된 텍스쳐가 자동적으로 저장 된다.

밉맵 된 텍스쳐에 이미지를 로드할 때, 디바이스에 따라서는, 1x1 의 이미지로 변환하지 못하고, 함수가 실패하는 일이 있다. 이러한 경우는, 이미지를 수동으로 로드할 필요가 있다.

D3DXCreateTextureFromFile 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextureFromFileA 또는 D3DXCreateTextureFromFileW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateTextureFromFile 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateTextureFromFile D3DXCreateTextureFromFileW
#else
#define D3DXCreateTextureFromFile D3DXCreateTextureFromFileA
#endif

이 함수를 사용해 생성 한 리소스는, D3DPOOL_MANAGED 로 나타나는 메모리 클래스에 배치된다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromFileExA ,D3DXCreateTextureFromFileExW ,D3DXCreateTextureFromFileW


D3DXCreateTextureFromFileExA

ANSI 캐릭터 라인으로 지정한 파일을 바탕으로 해 텍스쳐를 생성 한다. 이것은,D3DXCreateTextureFromFileA 보다 고도의 함수이다.

HRESULT D3DXCreateTextureFromFileExA(
  LPDIRECT3DDEVICE8 pDevice,
  LPCSTR pSrcFile,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcFile
[in] 텍스쳐의 생성에 사용하는 파일을 지정하는 ANSI 캐릭터 라인에의 포인터.
Width
[in] 폭 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
Height
[in] 높이 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우,Pool 에 D3DPOOL_DEFAULT 를 설정해, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이러한 처리를 지원 하고 있는 것을 확인할 필요가 있다.
Format
텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는,D3DFORMAT 열거형의 멤버. 돌려주어지는 텍스쳐의 포맷은 Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 텍스쳐의 포맷을 확인할 필요가 있다. Format 가 D3DFMT_UNKNOWN 의 경우, 포맷은 파일로부터 취득된다.
Pool
[in] 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
MipFilter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

밉맵 된 텍스쳐의 각 레벨에는, 로드 된 텍스쳐가 자동적으로 저장 된다.

밉맵 된 텍스쳐에 이미지를 로드할 때, 디바이스에 따라서는, 1x1 의 이미지로 변환하지 못하고, 함수가 실패하는 일이 있다. 이러한 경우는, 이미지를 수동으로 로드할 필요가 있다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

D3DXCreateTextureFromFileEx 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextureFromFileExA 또는 D3DXCreateTextureFromFileExW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateTextureFromFileEx 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateTextureFromFileEx D3DXCreateTextureFromFileExW
#else
#define D3DXCreateTextureFromFileEx D3DXCreateTextureFromFileExA
#endif

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromFileA ,D3DXCreateTextureFromFileExW ,D3DXCreateTextureFromFileW


D3DXCreateTextureFromFileExW

Unicode 캐릭터 라인으로 지정된 파일로부터 텍스쳐를 생성 한다. 이것은,D3DXCreateTextureFromFileW 보다 고도의 함수이다.

HRESULT D3DXCreateTextureFromFileExW(
  LPDIRECT3DDEVICE8 pDevice,
  LPCWSTR pSrcFile,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcFile
[in] 텍스쳐의 생성에 사용하는 파일을 지정하는 Unicode 캐릭터 라인에의 포인터.
Width
[in] 폭 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
Height
[in] 높이 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우,Pool 에 D3DPOOL_DEFAULT 를 설정해, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이 처리를 지원 하고 있는 것을 확인할 필요가 있다.
Format
[in] 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는 D3DFORMAT 열거형의 멤버. 돌려주어지는 텍스쳐의 포맷은 Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 텍스쳐의 포맷을 확인할 필요가 있다. Format 가 D3DFMT_UNKNOWN 의 경우, 포맷은 파일로부터 취득된다.
Pool
[in] 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
MipFilter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

밉맵 된 텍스쳐의 각 레벨에는, 로드 된 텍스쳐가 자동적으로 저장 된다.

밉맵 된 텍스쳐에 이미지를 로드할 때, 디바이스에 따라서는, 1x1 의 이미지로 변환하지 못하고, 함수가 실패하는 일이 있다. 이러한 경우는, 이미지를 수동으로 로드할 필요가 있다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

D3DXCreateTextureFromFileEx 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextureFromFileExA 또는 D3DXCreateTextureFromFileExW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateTextureFromFileEx 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateTextureFromFileEx D3DXCreateTextureFromFileExW
#else
#define D3DXCreateTextureFromFileEx D3DXCreateTextureFromFileExA
#endif

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromFileA ,D3DXCreateTextureFromFileExA ,D3DXCreateTextureFromFileW


D3DXCreateTextureFromFileInMemory

메모리내의 파일로부터 텍스쳐를 생성 한다.

HRESULT D3DXCreateTextureFromFileInMemory(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID pSrcData,
  UINT SrcData,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcData
[in] 텍스쳐의 생성에 사용하는 메모리내의 파일에의 포인터.
SrcData
[in] 메모리내의 파일의 사이즈 (바이트 단위).
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

이 함수를 사용해 생성 한 리소스는, D3DPOOL_MANAGED 로 나타나는 메모리 클래스에 배치된다.

이 메소드는, 어플리케이션 정의의 리소스 (미가공 데이터)인, RT_RCDATA 로서 저장 된 이미지 파일을 로드하기 위해서(때문에) 사용하도록(듯이) 설계되고 있다. 그 이외의 목적으로 사용 하면, 이 메소드는 실패한다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromFileInMemoryEx


D3DXCreateTextureFromFileInMemoryEx

메모리내의 파일로부터 텍스쳐를 생성 한다. 이것은,D3DXCreateTextureFromFileInMemory 보다 고도의 함수이다.

HRESULT D3DXCreateTextureFromFileInMemoryEx(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID pSrcData,
  UINT SrcData,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcData
[in] 텍스쳐의 생성에 사용하는 메모리내의 파일에의 포인터.
SrcData
[in] 메모리내의 파일의 사이즈 (바이트 단위).
Width
[in] 폭 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
Height
[in] 높이 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우,Pool 에 D3DPOOL_DEFAULT 를 설정해, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이 처리를 지원 하고 있는 것을 확인할 필요가 있다.
Format
[in] 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는 D3DFORMAT 열거형의 멤버. 돌려주어지는 텍스쳐의 포맷은 Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 텍스쳐의 포맷을 확인할 필요가 있다. Format 가 D3DFMT_UNKNOWN 의 경우, 포맷은 파일로부터 취득된다.
Pool
[in] 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
MipFilter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

이 메소드는, 어플리케이션 정의의 리소스 (미가공 데이터)인, RT_RCDATA 로서 저장 된 이미지 파일을 로드하기 위해서(때문에) 사용하도록(듯이) 설계되고 있다. 그 이외의 목적으로 사용 하면, 이 메소드는 실패한다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromFileInMemory


D3DXCreateTextureFromFileW

Unicode 캐릭터 라인으로 지정된 파일로부터 텍스쳐를 생성 한다.

HRESULT D3DXCreateTextureFromFileW(
  LPDIRECT3DDEVICE8 pDevice,
  LPCWSTR pSrcFile,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
pSrcFile
[in] 텍스쳐의 생성에 사용하는 파일을 지정하는 Unicode 캐릭터 라인에의 포인터.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

밉맵 된 텍스쳐의 각 레벨에는, 로드 된 텍스쳐가 자동적으로 저장 된다.

밉맵 된 텍스쳐에 이미지를 로드할 때, 디바이스에 따라서는, 1x1 의 이미지로 변환하지 못하고, 함수가 실패하는 일이 있다. 이러한 경우는, 이미지를 수동으로 로드할 필요가 있다.

D3DXCreateTextureFromFile 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextureFromFileA 또는 D3DXCreateTextureFromFileW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateTextureFromFile 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateTextureFromFile D3DXCreateTextureFromFileW
#else
#define D3DXCreateTextureFromFile D3DXCreateTextureFromFileA
#endif

이 함수를 사용해 생성 한 리소스는, D3DPOOL_MANAGED 로 나타나는 메모리 클래스에 배치된다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromFileA ,D3DXCreateTextureFromFileExA ,D3DXCreateTextureFromFileExW


D3DXCreateTextureFromResourceA

ANSI 캐릭터 라인으로 지정한 리소스를 바탕으로 해 텍스쳐를 생성 한다.

HRESULT D3DXCreateTextureFromResourceA(
  LPDIRECT3DDEVICE8 pDevice,
  HMODULE hSrcModule,
  LPCSTR pSrcResource,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
hSrcModule
[in] 리소스를 특정하고 있는 모듈에의 핸들. 또는, operating system가 현재의 프로세스에 사용하는 이미지에 관련지을 수 있고 있는 모듈의 경우는 NULL.
pSrcResource
[in] 텍스쳐의 생성에 사용하는 리소스를 지정하는 ANSI 캐릭터 라인에의 포인터.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

로드 되는 리소스는 비트 맵 리소스 (RT_BITMAP)가 아니면 안된다.

D3DXCreateTextureFromResource 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextureFromResourceA 또는 D3DXCreateTextureFromResourceW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateTextureFromResource 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateTextureFromResource D3DXCreateTextureFromResourceW
#else
#define D3DXCreateTextureFromResource D3DXCreateTextureFromResourceA
#endif

이 함수를 사용해 생성 한 리소스는, D3DPOOL_MANAGED 로 나타나는 메모리 클래스에 배치된다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromResourceExA ,D3DXCreateTextureFromResourceExW ,D3DXCreateTextureFromResourceW


D3DXCreateTextureFromResourceExA

ANSI 캐릭터 라인으로 지정한 리소스를 바탕으로 해 텍스쳐를 생성 한다. 이것은,D3DXCreateTextureFromResourceA 보다 고도의 함수이다.

HRESULT D3DXCreateTextureFromResourceExA(
  LPDIRECT3DDEVICE8 pDevice,
  HMODULE hSrcModule,
  LPCSTR pSrcResource,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
hSrcModule
[in] 리소스를 특정하고 있는 모듈에의 핸들. 또는, operating system가 현재의 프로세스에 사용하는 이미지에 관련지을 수 있고 있는 모듈의 경우는 NULL.
pSrcResource
[in] 텍스쳐의 생성에 사용하는 리소스를 지정하는 ANSI 캐릭터 라인에의 포인터.
Width
[in] 폭 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
Height
[in] 높이 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우,Pool 에 D3DPOOL_DEFAULT 를 설정해, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이 처리를 지원 하고 있는 것을 확인할 필요가 있다.
Format
[in] 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는 D3DFORMAT 열거형의 멤버. 돌려주어지는 텍스쳐의 포맷은 Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 텍스쳐의 포맷을 확인할 필요가 있다. Format 가 D3DFMT_UNKNOWN 의 경우, 포맷은 파일로부터 취득된다.
Pool
[in] 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
MipFilter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX 를 지정하는 것으로 동일하다.
D3DX_FILTER_BOX

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

로드 되는 리소스는 비트 맵 리소스 (RT_BITMAP)가 아니면 안된다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

D3DXCreateTextureFromResourceEx 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextureFromResourceExA 또는 D3DXCreateTextureFromResourceExW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateTextureFromResourceEx 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateTextureFromResourceEx D3DXCreateTextureFromResourceExW
#else
#define D3DXCreateTextureFromResourceEx D3DXCreateTextureFromResourceExA
#endif

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromResourceA ,D3DXCreateTextureFromResourceW , D3DXCreateTextureFromResourceExW


D3DXCreateTextureFromResourceExW

Unicode 캐릭터 라인으로 지정한 리소스를 바탕으로 해 텍스쳐를 생성 한다. 이것은,D3DXCreateTextureFromResourceW 보다 고도의 함수이다.

HRESULT D3DXCreateTextureFromResourceExW(
  LPDIRECT3DDEVICE8 pDevice,
  HMODULE hSrcModule,
  LPCWSTR pSrcResource,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
hSrcModule
[in] 리소스를 특정하고 있는 모듈에의 핸들. 또는, operating system가 현재의 프로세스에 사용하는 이미지에 관련지을 수 있고 있는 모듈의 경우는 NULL.
pSrcResource
[in] 텍스쳐의 생성에 사용하는 리소스를 지정하는 Unicode 캐릭터 라인에의 포인터.
Width
[in] 폭 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
Height
[in] 높이 (픽셀 단위). 이 값이 0 또는 D3DX_DEFAULT 의 경우, 넓이는 파일로부터 취득된다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 0 또는 D3DUSAGE_RENDERTARGET. 이 플래그에 D3DUSAGE_RENDERTARGET 를 설정 하면, 그 표면은 렌더링 타겟으로서 사용되는 것을 나타낸다. 리소스는,SetRenderTarget 메소드의 pNewRenderTarget 파라미터에 건네줄 수가 있다. D3DUSAGE_RENDERTARGET 를 지정하는 경우,Pool 에 D3DPOOL_DEFAULT 를 설정해, 어플리케이션은 IDirect3D8::CheckDeviceFormat 를 호출해, 디바이스가 이 처리를 지원 하고 있는 것을 확인할 필요가 있다.
Format
[in] 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는 D3DFORMAT 열거형의 멤버. 돌려주어지는 텍스쳐의 포맷은 Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 텍스쳐의 포맷을 확인할 필요가 있다. Format 가 D3DFMT_UNKNOWN 의 경우, 포맷은 파일로부터 취득된다.
Pool
[in] 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
MipFilter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

로드 되는 리소스는 비트 맵 리소스 (RT_BITMAP)가 아니면 안된다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

D3DXCreateTextureFromResourceEx 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextureFromResourceExA 또는 D3DXCreateTextureFromResourceExW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateTextureFromResourceEx 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateTextureFromResourceEx D3DXCreateTextureFromResourceExW
#else
#define D3DXCreateTextureFromResourceEx D3DXCreateTextureFromResourceExA
#endif

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromResourceA ,D3DXCreateTextureFromResourceExA,D3DXCreateTextureFromResourceW


D3DXCreateTextureFromResourceW

Unicode 캐릭터 라인으로 지정한 리소스를 바탕으로 해 텍스쳐를 생성 한다.

HRESULT D3DXCreateTextureFromResourceW(
  LPDIRECT3DDEVICE8 pDevice,
  HMODULE hSrcModule,
  LPCWSTR pSrcResource,
  LPDIRECT3DTEXTURE8* ppTexture
);

파라미터

pDevice
[in] 텍스쳐에 관련지을 수 있고 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
hSrcModule
[in] 리소스를 특정하고 있는 모듈에의 핸들. 또는, operating system가 현재의 프로세스에 사용하는 이미지에 관련지을 수 있고 있는 모듈의 경우는 NULL.
pSrcResource
[in] 텍스쳐의 생성에 사용하는 리소스를 지정하는 Unicode 캐릭터 라인에의 포인터.
ppTexture
[out] 생성 된 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

주의

로드 되는 리소스는 비트 맵 리소스 (RT_BITMAP)가 아니면 안된다.

D3DXCreateTextureFromResource 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXCreateTextureFromResourceA 또는 D3DXCreateTextureFromResourceW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXCreateTextureFromResource 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXCreateTextureFromResource D3DXCreateTextureFromResourceW
#else
#define D3DXCreateTextureFromResource D3DXCreateTextureFromResourceA
#endif

이 함수를 사용해 생성 한 리소스는, D3DPOOL_MANAGED 로 나타나는 메모리 클래스에 배치된다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXCreateTextureFromResourceA ,D3DXCreateTextureFromResourceExA ,D3DXCreateTextureFromResourceExW


D3DXCreateVolumeTexture

필요에 따라서 호출해 파라미터를 조정해, 하늘의 볼륨 텍스쳐를 생성 한다.

HRESULT D3DXCreateVolumeTexture(
  LPDIRECT3DDEVICE8 pDevice,
  UINT Width,
  UINT Height,
  UINT Depth,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  LPDIRECT3DVOLUMETEXTURE8* ppVolumeTexture
);

파라미터

pDevice
[in] 볼륨 텍스쳐에 관련지을 수 있는 디바이스를 나타내는 IDirect3DDevice8 인터페이스에의 포인터.
Width
[in] 폭 (픽셀 단위). 이 값은 0 이외일 필요가 있다.
Height
[in] 높이 (픽셀 단위). 이 값은 0 이외일 필요가 있다.
Depth
[in] 깊이 (단위 픽셀). 이 값은 0 이외일 필요가 있다.
MipLevels
[in] 요구되는 밉레벨의 수. 이 값이 0 또는 D3DX_DEFAULT 의 경우는, 완전한 밉맵 체인이 생성 된다.
Usage
[in] 현시점에서는 미사용이므로 0 을 설정해 둔다.
Format
[in] 볼륨 텍스쳐에 대해서 요구된 픽셀 포맷을 기술하는,D3DFORMAT 열거형의 멤버. 돌려주어지는 볼륨 텍스쳐의 포맷은 Format 로 지정된 포맷과 다른 경우가 있다. 어플리케이션은, 돌려주어진 볼륨 텍스쳐의 포맷을 확인할 필요가 있다.
Pool
[in] 볼륨 텍스쳐의 배치처가 되는 메모리 클래스를 기술하는,D3DPOOL 열거형의 멤버.
ppVolumeTexture
[out] 생성 된 볼륨 텍스쳐 오브젝트를 나타내는 IDirect3DVolumeTexture8 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
E_OUTOFMEMORY

주의

D3DXCreateVolumeTexture 는, 내부에서 D3DXCheckVolumeTextureRequirements 를 사용해 호출 파라미터를 조정한다. 따라서,IDirect3Ddevice8::CreateVolumeTexture 의 호출이 실패하는 경우에서도,D3DXCreateVolumeTexture 의 호출은 성공하는 것이 많다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXFilterCubeTexture

큐브 텍스쳐 맵의 밉맵 레벨을 필터 링 한다.

HRESULT D3DXFilterCubeTexture(
  LPDIRECT3DCUBETEXTURE8 pCubeTexture,
  CONST PALETTEENTRY* pPalette,
  UINT SrcLevel,
  DWORD MipFilter
);

파라미터

pCubeTexture
[in] 필터 링 하는 큐브 텍스쳐 오브젝트를 나타내는,IDirect3DCubeTexture8 인터페이스에의 포인터.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 팔레트가 지정되어 있지 않은 경우, 디폴트의 Microsoft® Direct3D® 팔레트 (완전하게 불투명한 흰색의 팔레트)가 제공된다. 「주의」를 참조할것.
SrcLevel
[in] 하의 레벨을 생성하기 위해서 이미지를 사용하는 레벨. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, 0 을 지정하는 것으로 동일하다.
MipFilter
[in] 밉맵을 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

큐브 텍스쳐의 각면에 도착해, 각 레벨로 재귀적으로 박스 필터를 적용해 다음의 레벨을 생성한다.

디폴트의 풀 (D3DPOOL_DEFAULT)에 생성 된 큐브 텍스쳐를 D3DXFilterCubeTexture 와 함께 사용할 수 없다. 오브젝트에 대한 락 처리가 필요하기 때문에이다. 디폴트 풀내의 텍스쳐에 대한 락은 금지되고 있다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXFilterCubeTexture 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXFilterTexture

텍스쳐의 밉맵 레벨을 필터 링 한다.

HRESULT D3DXFilterTexture(
  LPDIRECT3DTEXTURE8 pTexture,
  CONST PALETTEENTRY* pPalette,
  UINT SrcLevel,
  DWORD MipFilter
);

파라미터

pTexture
[in] 필터 링 하는 텍스쳐 오브젝트를 나타내는,IDirect3DTexture8 인터페이스에의 포인터.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 비팔레트 형식의 경우는 NULL. 팔레트가 지정되어 있지 않은 경우, 디폴트의 Microsoft® Direct3D® 팔레트 (완전하게 불투명한 흰색의 팔레트)가 제공된다. 「주의」를 참조할것.
SrcLevel
[in] 하의 레벨을 생성하기 위해서 이미지를 사용하는 레벨. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, 0 을 지정하는 것으로 동일하다.
MipFilter
[in] 밉맵을 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
이 플래그는, 결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 하는 것을 나타낸다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

각 텍스쳐 레벨로 재귀적으로 박스 필터를 적용해 다음의 텍스쳐 레벨을 생성한다.

디폴트의 풀 (D3DPOOL_DEFAULT)에 생성 된 텍스쳐를 D3DXFilterTexture 와 함께 사용할 수 없다. 오브젝트에 대한 락 처리가 필요하기 때문에이다. 디폴트 풀내의 텍스쳐에 대한 락은 금지되고 있다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXFilterTexture 이 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXFilterVolumeTexture

볼륨 텍스쳐의 밉맵 레벨을 필터 링 한다.

HRESULT D3DXFilterVolumeTexture(
  LPDIRECT3DVOLUMETEXTURE8 pVolumeTexture,
  CONST PALETTEENTRY* pPalette,
  UINT SrcLevel,
  DWORD MipFilter
);

파라미터

pVolumeTexture
[in] 필터 링 하는 볼륨 텍스쳐 오브젝트를 나타내는,IDirect3DVolumeTexture8 인터페이스에의 포인터.
pPalette
[out] 저장 하는 256 색팔레트를 나타내는 PALETTEENTRY 구조체에의 포인터, 또는 비팔레트 형식의 경우는 NULL. 팔레트가 지정되어 있지 않은 경우, 디폴트의 Microsoft® Direct3D® 팔레트 (완전하게 불투명한 흰색의 팔레트)가 제공된다. 「주의」를 참조할것.
SrcLevel
[in] 하의 레벨을 생성하기 위해서 이미지를 사용하는 레벨. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, 0 을 지정하는 것으로 동일하다.
MipFilter
[in] 밉맵을 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_BOX | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는,D3DERR_INVALIDCALL 를 돌려준다.

주의

각 텍스쳐 레벨로 재귀적으로 박스 필터를 적용해 다음의 텍스쳐 레벨을 생성한다.

디폴트의 풀 (D3DPOOL_DEFAULT)에 생성 된 볼륨 텍스쳐를 D3DXFilterVolumeTexture 와 함께 사용할 수 없다. 오브젝트에 대한 락 처리가 필요하기 때문에이다. 디폴트 풀내의 텍스쳐에 대한 락은 금지되고 있다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXFilterVolumeTexture 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXLoadSurfaceFromFileA

ANSI 캐릭터 라인으로 지정한 파일로부터 표면을 로드한다.

HRESULT D3DXLoadSurfaceFromFileA(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCSTR pSrcFile,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

파라미터

pDestSurface
[in] IDirect3DSurface8 인터페이스에의 포인터. 전송처의 표면을 지정한다. 이 표면이 이미지를 받는다.
pDestPalette
[in] 256 색의 전송처 팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pDestRect
[in] RECT 구조체에의 포인터. 전송처 직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
pSrcFile
[in] 소스 이미지의 파일명을 지정하는 ANSI 캐릭터 라인에의 포인터.
pSrcRect
[in] RECT 구조체에의 포인터. 전송원직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 이미지 전체를 지정한다.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

D3DXLoadSurfaceFromFile 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXLoadSurfaceFromFileA 또는 D3DXLoadSurfaceFromFileW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXLoadSurfaceFromFile 의 정의 방법을 나타내고 있다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXLoadSurfaceFromFileA 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

#ifdef UNICODE
#define D3DXLoadSurfaceFromFile D3DXLoadSurfaceFromFileW
#else
#define D3DXLoadSurfaceFromFile D3DXLoadSurfaceFromFileA
#endif

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXLoadSurfaceFromFileW


D3DXLoadSurfaceFromFileInMemory

메모리내에 있는 파일로부터 표면을 로드한다.

HRESULT D3DXLoadSurfaceFromFileInMemory(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCVOID pSrcData,
  UINT SrcData,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

파라미터

pDestSurface
[in] IDirect3DSurface8 인터페이스에의 포인터. 전송처의 표면을 지정한다. 이 표면이 이미지를 받는다.
pDestPalette
[in] 256 색의 전송처 팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pDestRect
[in] RECT 구조체에의 포인터. 전송처 직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
pSrcData
[in] 로드하는 표면이 있는 메모리내에 있는 파일에의 포인터.
SrcData
[in] 메모리내의 파일의 사이즈 (바이트 단위).
pSrcRect
[in] RECT 구조체에의 포인터. 전송원직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 이미지 전체를 지정한다.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXLoadSurfaceFromFileInMemory 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXLoadSurfaceFromFileW

Unicode 캐릭터 라인으로 지정된 파일로부터 표면을 로드한다.

HRESULT D3DXLoadSurfaceFromFileW(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCWSTR pSrcFile,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

파라미터

pDestSurface
[in] IDirect3DSurface8 인터페이스에의 포인터. 전송처의 표면을 지정한다. 이 표면이 이미지를 받는다.
pDestPalette
[in] 256 색의 전송처 팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pDestRect
[in] RECT 구조체에의 포인터. 전송처 직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
pSrcFile
[in] 소스 이미지의 파일명을 지정하는 Unicode 캐릭터 라인에의 포인터.
pSrcRect
[in] RECT 구조체에의 포인터. 전송원직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 이미지 전체를 지정한다.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

D3DXLoadSurfaceFromFile 은,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXLoadSurfaceFromFileA 또는 D3DXLoadSurfaceFromFileW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다. 다음의 코드는,D3DXLoadSurfaceFromFile 의 정의 방법을 나타내고 있다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXLoadSurfaceFromFileW 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

#ifdef UNICODE
#define D3DXLoadSurfaceFromFile D3DXLoadSurfaceFromFileW
#else
#define D3DXLoadSurfaceFromFile D3DXLoadSurfaceFromFileA
#endif

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXLoadSurfaceFromFileA


D3DXLoadSurfaceFromMemory

메모리로부터 표면을 로드한다.

HRESULT D3DXLoadSurfaceFromMemory(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCVOID pSrcMemory,
  D3DFORMAT SrcFormat,
  UINT SrcPitch,
  CONST PALETTEENTRY* pSrcPalette,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey
);

파라미터

pDestSurface
[in] IDirect3DSurface8 인터페이스에의 포인터. 전송처의 표면을 지정한다. 이 표면이 이미지를 받는다.
pDestPalette
[in] 256 색의 전송처 팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pDestRect
[in] RECT 구조체에의 포인터. 전송처 직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
pSrcMemory
[in] 메모리내에 있는 소스 이미지의 좌상구석에의 포인터.
SrcFormat
[in] 소스 이미지의 픽셀 포맷인,D3DFORMAT 열거형의 멤버.
SrcPitch
[in] 전송원의 이미지의 피치 (바이트 단위). DXT 포맷의 경우, 이 수치는 셀로 구성되는 1 개의 행의 폭 (바이트 단위)을 나타낸다.
pSrcPalette
[in] 256 색의 전송원팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pSrcRect
[in] RECT 구조체에의 포인터. 메모리내의 소스 이미지의 넓이를 지정한다. NULL 를 지정할 수 없다.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXLoadSurfaceFromMemory 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXLoadSurfaceFromResourceA

ANSI 캐릭터 라인으로 지정한 리소스로부터 표면을 로드한다.

HRESULT D3DXLoadSurfaceFromResourceA(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  HMODULE hSrcModule,
  LPCSTR pSrcResource,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

파라미터

pDestSurface
[in] IDirect3DSurface8 인터페이스에의 포인터. 전송처의 표면을 지정한다. 이 표면이 이미지를 받는다.
pDestPalette
[in] 256 색의 전송처 팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pDestRect
[in] RECT 구조체에의 포인터. 전송처 직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
hSrcModule
[in] 리소스를 특정하고 있는 모듈에의 핸들. 또는, operating system가 현재의 프로세스에 사용하는 이미지에 관련지을 수 있고 있는 모듈의 경우는 NULL.
pSrcResource
[in] 소스 이미지의 리소스명을 지정하는 ANSI 캐릭터 라인에의 포인터.
pSrcRect
[in] RECT 구조체에의 포인터. 전송원직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

로드 되는 리소스는 비트 맵 리소스 (RT_BITMAP)가 아니면 안된다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

D3DXLoadSurfaceFromResource 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXLoadSurfaceFromResourceA 또는 D3DXLoadSurfaceFromResourceW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXLoadSurfaceFromResourceA 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

다음의 코드는,D3DXLoadSurfaceFromResource 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXLoadSurfaceFromResource D3DXLoadSurfaceFromResourceW
#else
#define D3DXLoadSurfaceFromResource D3DXLoadSurfaceFromResourceA
#endif

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXLoadSurfaceFromResourceW


D3DXLoadSurfaceFromResourceW

Unicode 캐릭터 라인으로 지정된 리소스로부터 표면을 로드한다.

HRESULT D3DXLoadSurfaceFromResourceW(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  HMODULE hSrcModule,
  LPCWSTR pSrcResource,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

파라미터

pDestSurface
[in] IDirect3DSurface8 인터페이스에의 포인터. 전송처의 표면을 지정한다. 이 표면이 이미지를 받는다.
pDestPalette
[in] 256 색의 전송처 팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pDestRect
[in] RECT 구조체에의 포인터. 전송처 직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
hSrcModule
[in] 리소스를 특정하고 있는 모듈에의 핸들. 또는, operating system가 현재의 프로세스에 사용하는 이미지에 관련지을 수 있고 있는 모듈의 경우는 NULL.
pSrcResource
[in] 소스 이미지의 리소스명을 지정하는 Unicode 캐릭터 라인에의 포인터.
pSrcRect
[in] RECT 구조체에의 포인터. 전송원직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.
pSrcInfo
[in, out] 소스 이미지 파일내의 데이터의 기술을 저장 하는 D3DXIMAGE_INFO 구조체에의 포인터, 또는 NULL.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

로드 되는 리소스는 비트 맵 리소스 (RT_BITMAP)가 아니면 안된다.

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

D3DXLoadSurfaceFromResource 는,#define UNICODE 스윗치가 포함되어 있는지 어떤지에 응해,D3DXLoadSurfaceFromResourceA 또는 D3DXLoadSurfaceFromResourceW 의 어느 쪽인지를 맵 한다. #define UNICODE 스윗치를 삽입 또는 제외해, 어플리케이션으로 Unicode 또는 ANSI 캐릭터 라인의 어느 쪽을 사용하는지를 지정한다.

비레벨 제로에의 기입은 업데이트 해야 할 더티 직사각형은 되지 않는다. D3DXLoadSurfaceFromResourceW 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

다음의 코드는,D3DXLoadSurfaceFromResource 의 정의 방법을 나타내고 있다.

#ifdef UNICODE
#define D3DXLoadSurfaceFromResource D3DXLoadSurfaceFromResourceW
#else
#define D3DXLoadSurfaceFromResource D3DXLoadSurfaceFromResourceA
#endif

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.

참조

D3DXLoadSurfaceFromResourceA


D3DXLoadSurfaceFromSurface

칼라 변환을 실시하면서, 다른 표면으로부터 표면을 로드한다.

HRESULT D3DXLoadSurfaceFromSurface(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPDIRECT3DSURFACE8 pSrcSurface,
  CONST PALETTEENTRY* pSrcPalette,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey
);

파라미터

pDestSurface
[in] IDirect3DSurface8 인터페이스에의 포인터. 전송처의 표면을 지정한다. 이 표면이 이미지를 받는다.
pDestPalette
[in] 256 색의 전송처 팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pDestRect
[in] RECT 구조체에의 포인터. 전송처 직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
pSrcSurface
[in] 전송원표면을 나타내는 IDirect3DSurface8 인터페이스에의 포인터.
pSrcPalette
[in] 256 색의 전송원팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pSrcRect
[in] RECT 구조체에의 포인터. 전송원직사각형을 지정한다. 이 파라미터에 NULL 를 설정해, 표면 전체를 지정한다.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXLoadSurfaceFromSurface 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXLoadVolumeFromMemory

메모리로부터 볼륨을 로드한다.

HRESULT D3DXLoadVolumeFromMemory(
  LPDIRECT3DVOLUME8 pDestVolume,
  CONST PALETTEENTRY* pDestPalette,
  CONST D3DBOX* pDestBox,
  LPCVOID pSrcMemory,
  D3DFORMAT SrcFormat,
  UINT SrcRowPitch,
  UINT SrcSlicePitch,
  CONST PALETTEENTRY* pSrcPalette,
  CONST D3DBOX* pSrcBox,
  DWORD Filter,
  D3DCOLOR ColorKey
);

파라미터

pDestVolume
[in] IDirect3DVolume8 인터페이스에의 포인터. 이미지를 받는 전송처의 볼륨을 지정한다.
pDestPalette
[in] 256 색의 전송처 팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pDestBox
[in] D3DBOX 구조체에의 포인터. 전송처의 박스를 지정한다. 이 파라미터에 NULL 를 설정해 볼륨 전체를 지정한다.
pSrcMemory
[in] 메모리내에 있는 소스 볼륨의 좌상구석에의 포인터.
SrcFormat
[in] 소스 볼륨의 픽셀 포맷인,D3DFORMAT 열거형의 멤버.
SrcRowPitch
[in] 전송원의 이미지의 피치 (바이트 단위). DXT 포맷 (압축된 텍스쳐 포맷)의 경우, 이 수치는 셀로 구성되는 1 개의 행의 사이즈 (바이트 단위)를 나타낸다.
SrcSlicePitch
[in] 전송원의 이미지의 피치 (바이트 단위). DXT 포맷 (압축된 텍스쳐 포맷)의 경우, 이 수치는 셀로 구성되는 1 개의 슬라이스의 사이즈 (바이트 단위)를 나타낸다.
pSrcPalette
[in] 256 색의 전송원팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pSrcBox
[in] D3DBOX 구조체에의 포인터. 전송원의 박스를 지정한다. NULL 는 무효인 값이다.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXLoadVolumeFromMemory 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


D3DXLoadVolumeFromVolume

다른 볼륨으로부터 볼륨을 로드한다.

HRESULT D3DXLoadVolumeFromVolume(
  LPDIRECT3DVOLUME8 pDestVolume,
  CONST PALETTEENTRY* pDestPalette,
  CONST D3DBOX* pDestBox,
  LPDIRECT3DVOLUME8 pSrcVolume,
  CONST PALETTEENTRY* pSrcPalette,
  CONST D3DBOX* pSrcBox,
  DWORD Filter,
  D3DCOLOR ColorKey
);

파라미터

pDestVolume
[in] IDirect3DVolume8 인터페이스에의 포인터. 이미지를 받는 전송처의 볼륨을 지정한다.
pDestPalette
[in] 256 색의 전송처 팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pDestBox
[in] D3DBOX 구조체에의 포인터. 전송처의 박스를 지정한다. 이 파라미터에 NULL 를 설정해 볼륨 전체를 지정한다.
pSrcVolume
[in] IDirect3DVolume8 인터페이스에의 포인터. 소스 볼륨을 지정한다.
pSrcPalette
[in] 256 색의 전송원팔레트인 PALETTEENTRY 구조체에의 포인터, 또는 NULL. 「주의」를 참조할것.
pSrcBox
[in] D3DBOX 구조체에의 포인터. 전송원의 박스를 지정한다. 이 파라미터에 NULL 를 설정해 볼륨 전체를 지정한다.
Filter
[in] 이미지를 필터 링 하는 방법을 제어하는 1 개(살) 이상의 플래그의 편성. 이 파라미터에 D3DX_DEFAULT 를 지정하는 것은, D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER 를 지정하는 것으로 동일하다.

유효한 각각의 필터에, 다음의 플래그의 1 개가 포함되지 않으면 안 된다.

D3DX_FILTER_BOX
각 픽셀은, 소스 이미지내의 2 × 2 (× 2)의 사이즈의 박스에 포함되는 픽셀의 평균을 산출하는 것으로써 계산된다. 이 필터는, 밉맵을 사용하는 경우와 같이, 전송처의 넓이가 소스의 반의 경우만 기능한다.
D3DX_FILTER_LINEAR
각 전송처 픽셀은, 가장 가까운 4 개의 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다. 이 필터는, 양축의 스케일이 2 미만의 경우에 가장 효율적으로 기능한다.
D3DX_FILTER_NONE
스케일링 또는 필터 링을 실시하지 않는다. 소스 이미지의 경계의 외측에 있는 픽셀은 투명한 흑이다고 보여진다.
D3DX_FILTER_POINT
각 전송처 픽셀은, 가장 가까운 픽셀을 소스 이미지로부터 샘플링 하는 것으로써 계산된다.
D3DX_FILTER_TRIANGLE
소스 이미지내의 각 픽셀이, 전송처 이미지에 동일하게 반영된다. 이것은, 가장 처리에 시간이 걸리는 필터이다.

게다가OR 연산자를 사용해, 유효한 필터와 함께 다음에 나타내는 옵션의 플래그를 0 개 이상 지정할 수 있다.

D3DX_FILTER_MIRROR
이 플래그를 지정 하면, D3DX_FILTER_MIRROR_U, D3DX_FILTER_MIRROR_V, 및 D3DX_FILTER_MIRROR_W 플래그를 지정한 것이 된다.
D3DX_FILTER_MIRROR_U
u 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_V
v 축의 텍스쳐의 엣지로부터 멀어진 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_MIRROR_W
w 축의 텍스쳐의 엣지로부터 멀어지고 있는 픽셀을, 랩핑 하지 않고 미러링 하도록(듯이) 지정한다.
D3DX_FILTER_DITHER
결과적으로 생성 된 이미지를, 4x4 의 순서 첨부 dither 알고리즘을 사용해 디저링 할 필요가 있다.
ColorKey
[in] 투명이 되는 D3DCOLOR 의 값. 칼라 키를 무효로 하는 경우는 0 을 지정한다. 소스 이미지의 포맷과는 관계없이, 이것은 항상 32 비트의 ARGB 칼라이다. 알파가 의미가 있고, 보통은 칼라 키를 불투명하게 하는 경우는 FF 를 지정한다. 따라서, 불투명한 흑의 경우, 값은 0xFF000000 가 된다.

반환값

성공했을 경우는 D3D_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

주의

PALETTEENTRY 의 상세한 것에 대하여는, Microsoft® Platform Software Development Kit (SDK)를 참조할것. Microsoft DirectX® 8.0 의 시점에서,PALLETTEENTRY 구조체의 peFlags 멤버는, Platform SDK 에 설명되고 있도록(듯이)는 기능하지 않는다. peFlags 멤버는 현재, 8 비트의 팔레트화 된 포맷용의 알파 채널이다.

비레벨 제로에의 기입은 업데이트 해야 할 더티인 직사각형은 되지 않는다. D3DXLoadVolumeFromVolume 가 불려 가 서페이스가 이미 더티는 아니었다 (이것은 보통의 사용 시나리오에는 없다)라면, 어플리케이션은 명시적으로 그 서페이스에 IDirect3DTexture8::AddDirtyRect 를 호출할 필요가 있다.

동작환경

헤더 : D3dx8tex.h 로 선언.
임포트 라이브러리 : D3dx8.lib 을 사용.


매크로

여기에서는, Direct3DX 유틸리티 라이브러리가 제공하는 매크로의 레퍼런스 정보를 기술한다.

  • D3DXToDegree
  • D3DXToRadian


D3DXToDegree

라디안을 번으로 변환한다.

D3DXToDegree( radian ) ((radian) * (180.0f / D3DX_PI))

파라미터

radian
도수로 변환하는 값 (라디안 단위).

반환값

매크로는, 라디안값을 도수로 돌려준다.

주의

정수 D3DX_PI 는 다음의 정의와 함께 선언된다.

#define D3DX_PI    ((FLOAT)  3.141592654f)

동작환경

헤더 : d3dx8math.h 로 선언.

참조

D3DXToRadian


D3DXToRadian

번을 라디안으로 변환한다.

D3DXToRadian( degree ) ((degree) * (D3DX_PI / 180.0f))

파라미터

degree
라디안으로 변환하는 값 (도수 단위).

반환값

매크로는, 도수값을 라디안 단위로 돌려준다.

주의

정수 D3DX_PI 는 다음의 정의와 함께 선언된다.

#define D3DX_PI    ((FLOAT)  3.141592654f)

동작환경

헤더 : d3dx8math.h 로 선언.

참조

D3DXToDegree


구조체

여기에서는, Direct3DX 유틸리티 라이브러리에 포함되는 구조체에 관한 정보를 기술한다.

  • D3DXATTRIBUTERANGE
  • D3DXATTRIBUTEWEIGHTS
  • D3DXBONECOMBINATION
  • D3DXCOLOR
  • D3DXEFFECT_DESC
  • D3DXIMAGE_INFO
  • D3DXMATERIAL
  • D3DXMATRIX
  • D3DXPASS_DESC
  • D3DXPARAMETER_DESC
  • D3DXPLANE
  • D3DXQUATERNION
  • D3DXTECHNIQUE_DESC
  • D3DXVECTOR2
  • D3DXVECTOR3
  • D3DXVECTOR4
  • D3DXRTS_DESC


D3DXATTRIBUTERANGE

테이블의 속성값을 저장 한다.

typedef struct _D3DXATTRIBUTERANGE {
    DWORD AttribId;
    DWORD FaceStart;
    DWORD FaceCount;
    DWORD VertexStart;
    DWORD VertexCount;
} D3DXATTRIBUTERANGE;

멤버

AttribId
속성 테이블의 식별자.
FaceStart
시작면.
FaceCount
면의 수.
VertexStart
시작 버텍스.
VertexCount
버텍스의 수.

주의

속성 테이블은, 다른 텍스쳐, 렌더링 스테이트, 머트리얼등에 의해 드로잉(Drawing) 할 필요가 있는 메쉬의 영역을 식별하기 위해서 사용된다. 한층 더 어플리케이션은, 속성 테이블을 사용해, 프레임의 드로잉(Drawing)시에 소정의 속성 식별자 (AttribId)를 드로잉(Drawing) 하지 않는 것에 따라, 메쉬의 일부를 숨길 수가 있다.

LPD3DXATTRIBUTERANGE 는 D3DXATTRIBUTERANGE 구조체에의 포인터로서 정의된다.

typedef D3DXATTRIBUTERANGE* LPD3DXATTRIBUTERANGE;

동작환경

헤더 : d3dx8mesh.h 로 선언.

참조

ID3DXBaseMesh::DrawSubset


D3DXATTRIBUTEWEIGHTS

버텍스의 성분의 중요를 지정한다.

typedef struct _D3DXATTRIBUTEWEIGHTS {
    FLOAT Position;
    FLOAT Boundary;
    FLOAT Normal;
    FLOAT Diffuse;
    FLOAT Specular;
    FLOAT Tex[8];
} D3DXATTRIBUTEWEIGHTS;

멤버

Position
위치 성분의 가중.
Boundary
경계 성분의 가중.
Normal
법선 성분의 가중.
Diffuse
디퓨즈 성분의 가중.
Specular
스펙큐러 성분의 가중.
Tex
텍스쳐 좌표의 가중.

주의

이 구조체는, 엣지를 접는 동안의 상대 코스트를 계산하는 경우에, 단순화의 조작이 버텍스 데이터를 취급하는 방법을 기술한다. 예를 들어,Normal 필드가 0.0 의 경우, 단순화의 조작에서는 엣지를 접는 것에 관한 에러를 계산할 때에 버텍스 법선 성분이 무시된다. 다만,Normal 필드가 1.0 의 경우는, 단순화의 조작으로 버텍스 법선 성분이 사용된다. Normal 필드가 2.0 의 경우는, 에러의 수가 2 배가 되어,Normal 필드가 4.0 의 경우는 에러의 수가 4 배가 된다. 이하와 같이 계속된다.

LPD3DXATTRIBUTEWEIGHTS 형은 D3DXATTRIBUTEWEIGHTS 구조체에의 포인터로서 정의된다.

typedef D3DXATTRIBUTEWEIGHTS* LPD3DXATTRIBUTEWEIGHTS;

동작환경

헤더 : d3dx8mesh.h 로 선언.

참조

D3DXCreateSPMesh ,D3DXGeneratePMesh ,D3DXSimplifyMesh


D3DXBONECOMBINATION

속성과 뼈의 편성이 같은 메쉬의 서브 세트를 기술한다.

typedef struct _D3DXBONECOMBINATION {
    DWORD AttribId;
    DWORD FaceStart;
    DWORD FaceCount;
    DWORD VertexStart;
    DWORD VertexCount;
    DWORD* BoneId;
} D3DXBONECOMBINATION, *LPD3DXBONECOMBINATION;

멤버

AttribId
속성 테이블의 식별자.
FaceStart
시작면.
FaceCount
면의 수.
VertexStart
시작 버텍스.
VertexCount
버텍스의 수.
BoneId
1 회의 드로잉(Drawing) 호출로 드로잉(Drawing) 할 수 있는 각 뼈를 식별하는 값의 배열에의 포인터. 이 배열은,ID3DXSkinMesh::ConvertToIndexedBlendedMesh 의 가변장 뼈 편성을 저장 하는 가변장이 될 수가 있는 것에 주의 해야 한다.

주의

D3DXBONECOMBINATION 로 기술한 메쉬의 서브 세트는 단일의 드로잉(Drawing) 호출로 렌더링 가능하다.

동작환경

헤더 : d3dx8mesh.h 로 선언.


D3DXCOLOR

칼라값을 기술한다.

typedef struct D3DXCOLOR {
  FLOAT r, g, b, a;
} D3DXCOLOR;

멤버

r
색의 빨강 성분.
g
색의 초록 성분.
b
색의 파랑 성분.
a
색의 알파 성분.

주의

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXCOLOR 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

헤더 : d3dx8math.h 로 선언.


D3DXEFFECT_DESC

이펙트 오브젝트를 기술한다.

typedef struct _D3DXEFFECT_DESC
{
    UINT  Parameters;
    UINT  Techniques;
    DWORD Usage;

} D3DXEFFECT_DESC;

멤버

Parameters
이펙트에 사용되는 파라미터의 수.
Techniques
이펙트를 렌더링 가능한 테크닉의 수.
Usage
이 이펙트에 대한 사용 방법의 제어 정보. 이 멤버에는, 다음의 플래그 세트를 지정할 수 있다.
D3DUSAGE_SOFTWAREPROCESSING
이펙트가 소프트웨어 처리를 사용하는 것을 나타낸다.

주의

이펙트 오브젝트에는, 같은 이펙트의 복수의 렌더링 테크닉 및 파라미터를 저장 하는 것이 가능하다.

동작환경

헤더 : d3dx8effect.h 로 선언.

참조

ID3DXEffect::GetDesc


D3DXIMAGE_INFO

이미지 파일의 오리지날의 내용의 기술을 돌려준다.

typedef struct _D3DXIMAGE_INFO {
    UINT Width;
    UINT Height;
    UINT Depth;
    UINT MipLevels;
    D3DFORMAT Format;
} D3DXIMAGE_INFO;

멤버

Width
오리지날 이미지의 폭 (픽셀 단위).
Height
오리지날 이미지의 높이 (픽셀 단위).
Depth
오리지날 이미지의 깊이 (픽셀 단위).
MipLevels
오리지날 이미지의 밉레벨의 수.
Format
오리지날 이미지의 데이터를 가장 엄밀하게 기술하는 D3DFORMAT 열거형으로부터의 값.

동작환경

헤더 : d3dx8mesh.h 로 선언.


D3DXMATERIAL

Microsoft® DirectX® (. x) 파일에 보존되고 있는 머트리얼 정보를 돌려준다.

struct D3DXMATERIAL {
    D3DMATERIAL8  MatD3D;
    LPSTR         pTextureFilename;
};

멤버

MatD3D
머트리얼의 프로퍼티를 기술하는 D3DMATERIAL8 구조체.
pTextureFilename
텍스쳐의 파일명을 지정하는 캐릭터 라인에의 포인터.

주의

D3DXLoadMeshFromX 및 D3DXLoadMeshFromXof 는, 메쉬내의 각 머트리얼의 칼라와 텍스쳐의 이름을 지정하는 D3DXMATERIAL 구조체의 배열을 돌려준다. 어플리케이션은, 한층 더 텍스쳐를 로드할 필요가 있다.

LPD3DXMATERIAL 형은 D3DXMATERIAL 구조체에의 포인터로서 정의된다.

typedef struct D3DXMATERIAL *LPD3DXMATERIAL;

동작환경

헤더 : d3dx8mesh.h 로 선언.

참조

D3DXLoadMeshFromX ,D3DXLoadMeshFromXof


D3DXMATRIX

행렬을 기술한다.

typedef struct D3DXMATRIX : public D3DMATRIX {
public:
    D3DXMATRIX() {};
    D3DXMATRIX( CONST FLOAT * );
    D3DXMATRIX( CONST D3DMATRIX& );
    D3DXMATRIX( FLOAT _11, FLOAT _12, FLOAT _13, FLOAT _14,
                FLOAT _21, FLOAT _22, FLOAT _23, FLOAT _24,
                FLOAT _31, FLOAT _32, FLOAT _33, FLOAT _34,
                FLOAT _41, FLOAT _42, FLOAT _43, FLOAT _44 );

    // 액세스 허가
    FLOAT& operator () ( UINT Row, UINT Col );
    FLOAT  operator () ( UINT Row, UINT Col ) const;

    // 연산자의 캐스팅
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 대입 연산자
    D3DXMATRIX& operator *= ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator += ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator -= ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator *= ( FLOAT );
    D3DXMATRIX& operator /= ( FLOAT );

    // 단항 연산자
    D3DXMATRIX operator + () const;
    D3DXMATRIX operator - () const;

    // 2 항연산자
    D3DXMATRIX operator * ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator + ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator - ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator * ( FLOAT ) const;
    D3DXMATRIX operator / ( FLOAT ) const;

    friend D3DXMATRIX operator * ( FLOAT, CONST D3DXMATRIX& );

    BOOL operator == ( CONST D3DXMATRIX& ) const;
    BOOL operator ! = ( CONST D3DXMATRIX& ) const;

} D3DXMATRIX, *LPD3DXMATRIX;

주의

이 구조체는 D3DMATRIX 구조체의 멤버를 계승한다. C 의 프로그래머는 D3DXMATRIX 구조체를 사용할 수 없다. C 의 프로그래머는 D3DMATRIX 구조체를 사용할 필요가 있다.

Direct3DX 로 투영 행렬의 _34 요소에는, 부의 값을 설정할 수 없다. 어플리케이션은, 이 요소로 부의 값을 사용해야 하는 경우, 그 대신에 투영 행렬 전체를 –1 에 의해 스케일링 한다.

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXMATRIX 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

헤더 : d3dx8math.h 로 선언.


D3DXPARAMETER_DESC

이펙트 오브젝트에 사용되는 파라미터를 기술한다.

typedef struct _D3DXPARAMETER_DESC
{
    DWORD             Name;
    D3DXPARAMETERTYPE Type;

} D3DXPARAMETER_DESC;

멤버

Name
파라미터의 이름인 FOURCC 코드.
Type
이 파라미터에 사용되는 변수의 형태를 기술한다. 이 멤버는, 다음의 몇개의 정수이다.
D3DXPT_DWORD
파라미터는 DWORD 값이다.
D3DXPT_FLOAT
파라미터는 부동 소수점값이다.
D3DXPT_VECTOR
파라미터는 벡터이다.
D3DXPT_MATRIX
파라미터는 4 × 4 행렬이다.
D3DXPT_TEXTURE
파라미터는 텍스쳐이다.
D3DXPT_VERTEXSHADER
파라미터는 버텍스 쉐이더이다.
D3DXPT_PIXELSHADER
파라미터는 픽셀 쉐이더이다.
D3DXPT_CONSTANT
파라미터는 정수값이다.
D3DXPT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : d3dx8effect.h 로 선언.

참조

ID3DXEffect::GetParameterDesc


D3DXPASS_DESC

이펙트 오브젝트에 대한 패스를 기술한다.

typedef struct _D3DXPASS_DESC
{
    DWORD Name;

} D3DXPASS_DESC;

멤버

Name
패스의 이름에 사용되는 FOURCC 코드.

주의

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : d3dx8effect.h 로 선언.

참조

ID3DXTechnique::GetPassDesc


D3DXPLANE

평면을 기술한다.

typedef struct D3DXPLANE {
  FLOAT a, b, c, d;
} D3DXPLANE;

멤버

a, b, c, 및 d
a, b, c, 및 d 는 각각, 일반 평면 방정식의 클립면의 계수이다. 「주의」를 참조할것.

주의

D3DXPLANE 구조체의 멤버는, 일반 평면식의 형식을 취한다. 멤버는, ax + by + cz + dw = 0 이라고 하는 일반 평면식에 적합한다.

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXPLANE 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 단항 연산자나 2 항연산자가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

헤더 : d3dx8math.h 로 선언.


D3DXQUATERNION

쿠타니온을 기술한다.

typedef struct D3DXQUATERNION {
  FLOAT x, y, z, w;
} D3DXQUATERNION;

멤버

x
x 요소.
y
y 요소.
z
z 요소.
w
w 요소.

주의

쿠오타니온은, 벡터를 정의한 [x, y, z] 값에 제 4 원을 추가해, 임의의 4D 벡터를 생성한다. 다음에, 단위 쿠오타니온의 각 원이 축/각도의 회전에 어떻게 관계하고 있는지를 나타내는 (다만,q 는 단위 쿠오타니온 (x, y, z, w)을 나타내,axis 는 정규화되어theta 는 축을 회전축으로 한 CCW 회전이다).

q.x = sin(theta/2) * axis.x
q.y = sin(theta/2) * axis.y
q.z = sin(theta/2) * axis.z
q.w = cos(theta/2)

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXQUATERNION 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

헤더 : d3dx8math.h 로 선언.


D3DXTECHNIQUE_DESC

테크닉 오브젝트를 기술한다.

typedef struct _D3DXTECHNIQUE_DESC
{
    DWORD Name;
    UINT  Passes;
} D3DXTECHNIQUE_DESC;

멤버

Name
이 테크닉 오브젝트의 이름에 사용되는 FOURCC 코드.
Passes
테크닉이 요구하는 렌더링 패스의 수. 「주의」를 참조할것.

주의

비디오 카드안에는, 단일의 패스로 2 개의 텍스쳐를 렌더링 할 수 있는 것도 있다. 다만, 카드가 이 능력을 갖추지 않은 경우는, 대부분 2 살의 패스로 같은 이펙트를 렌더링 할 수 있다. 이 때, 각 패스에 대해서 1 개의 텍스쳐를 사용한다.

FOURCC 코드는, 길이가 4 문자의 캐릭터 라인이다. 상세한 것에 대하여는, 「FOURCC 코드」를 참조할것.

동작환경

헤더 : d3dx8effect.h 로 선언.

참조

ID3DXTechnique::GetDesc


D3DXVECTOR2

D3DXVECTOR2 구조체는, 2 차원 (2D) 공간의 벡터를 기술한다.

typedef struct D3DXVECTOR2 {
  FLOAT x, y;
} D3DXVECTOR2;

멤버

x
x 요소.
y
y 요소.

주의

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXVECTOR2 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

헤더 : d3dx8math.h 로 선언.


D3DXVECTOR3

D3DXVECTOR3 구조체는, 3 차원 (3D) 공간의 벡터를 기술한다.

typedef struct D3DXVECTOR3 : public D3DVECTOR {
public:
    D3DXVECTOR3() {};
    D3DXVECTOR3( CONST FLOAT * );
    D3DXVECTOR3( CONST D3DVECTOR& );
    D3DXVECTOR3( FLOAT x, FLOAT y, FLOAT z );

    // 캐스팅
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 대입 연산자
    D3DXVECTOR3& operator += ( CONST D3DXVECTOR3& );
    D3DXVECTOR3& operator -= ( CONST D3DXVECTOR3& );
    D3DXVECTOR3& operator *= ( FLOAT );
    D3DXVECTOR3& operator /= ( FLOAT );

    // 단항 연산자
    D3DXVECTOR3 operator + () const;
    D3DXVECTOR3 operator - () const;

    // 2 항연산자
    D3DXVECTOR3 operator + ( CONST D3DXVECTOR3& ) const;
    D3DXVECTOR3 operator - ( CONST D3DXVECTOR3& ) const;
    D3DXVECTOR3 operator * ( FLOAT ) const;
    D3DXVECTOR3 operator / ( FLOAT ) const;

    friend D3DXVECTOR3 operator * ( FLOAT, CONST struct D3DXVECTOR3& );

    BOOL operator == ( CONST D3DXVECTOR3& ) const;
    BOOL operator ! = ( CONST D3DXVECTOR3& ) const;

} D3DXVECTOR3, *LPD3DXVECTOR3;

멤버

x
x 요소.
y
y 요소.
z
z 요소.

주의

이 구조체는,D3DVECTOR 구조체의 멤버 x,y,z 를 계승한다. C 의 프로그래머는 D3DXVECTOR3 구조체를 사용할 수 없다. C 의 프로그래머는 D3DVECTOR 구조체를 사용할 필요가 있다.

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXVECTOR3 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

헤더 : d3dx8math.h 로 선언.


D3DXVECTOR4

D3DXVECTOR4 구조체는, 4 차원 (4D) 공간의 벡터를 기술한다.

typedef struct D3DXVECTOR4 {
  FLOAT x, y, z, w;
} D3DXVECTOR4;

멤버

x
x 요소.
y
y 요소.
z
z 요소.
w
w 요소.

주의

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXVECTOR4 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

헤더 : d3dx8math.h 로 선언.


D3DXRTS_DESC

렌더링 표면을 기술한다.

typedef struct _D3DXRTS_DESC {
    UINT                Width;
    UINT                Height;
    D3DFORMAT           Format;
    BOOL                DepthStencil;
    D3DFORMAT           DepthStencilFormat;

} D3DXRTS_DESC;

멤버

Width
렌더링 표면의 폭 (픽셀 단위).
Height
렌더링 표면의 높이 (픽셀 단위).
Format
렌더링 표면의 픽셀 포맷을 기술하는,D3DFORMAT 열거형의 멤버.
DepthStencil
TRUE 의 경우, 렌더링 표면은 스텐실 표면을 지원 한다. 그 이외의 경우, 이 멤버는 FALSE 로 설정된다.
DepthStencilFormat
DepthStencil 가 TRUE 의 경우, 이 파라미터는 렌더링 표면의 스텐실 포맷을 기술하는 D3DFORMAT 열거형의 멤버이다.

동작환경

헤더 : D3dx8core.h 로 선언.

참조

ID3DXRenderToSurface::GetDesc


C++ 고유의 기능

C++ 프로그래머는, Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 constructor　 　 의 overload 기능, 연산자의 overload 기능, 형태 변환의 확장 기능을 이용할 수 있다. 다음의 구조체에는, 확장 기능이 이행 되고 있다.

  • D3DXCOLOR 확장 기능
  • D3DXMATRIX 확장 기능
  • D3DXPLANE 확장 기능
  • D3DXQUATERNION 확장 기능
  • D3DXVECTOR2 확장 기능
  • D3DXVECTOR3 확장 기능
  • D3DXVECTOR4 확장 기능


D3DXCOLOR 확장 기능

D3DXCOLOR 구조체로, 다음의 연산자 overload와 타입 캐스트를 사용 가능하게 한다.

#ifdef __cplusplus
public:
    D3DXCOLOR() {}
    D3DXCOLOR( DWORD argb );
    D3DXCOLOR( CONST FLOAT * );
    D3DXCOLOR( CONST D3DCOLORVALUE& );
    D3DXCOLOR( FLOAT r, FLOAT g, FLOAT b, FLOAT a );

    // 캐스팅
    operator DWORD () const;

    operator FLOAT* ();
    operator CONST FLOAT* () const;

    operator D3DCOLORVALUE* ();
    operator CONST D3DCOLORVALUE* () const;

    operator D3DCOLORVALUE& ();
    operator CONST D3DCOLORVALUE& () const;

    // 대입 연산자
    D3DXCOLOR& operator += ( CONST D3DXCOLOR& );
    D3DXCOLOR& operator -= ( CONST D3DXCOLOR& );
    D3DXCOLOR& operator *= ( FLOAT );
    D3DXCOLOR& operator /= ( FLOAT );

    // 단항 연산자
    D3DXCOLOR operator + () const;
    D3DXCOLOR operator - () const;

    // 2 항연산자
    D3DXCOLOR operator + ( CONST D3DXCOLOR& ) const;
    D3DXCOLOR operator - ( CONST D3DXCOLOR& ) const;
    D3DXCOLOR operator * ( FLOAT ) const;
    D3DXCOLOR operator / ( FLOAT ) const;

    friend D3DXCOLOR operator * (FLOAT, CONST D3DXCOLOR& );

    BOOL operator == ( CONST D3DXCOLOR& ) const;
    BOOL operator ! = ( CONST D3DXCOLOR& ) const;

#endif //__cplusplus

동작환경

헤더 : D3dx8math.h 으로 선언.


D3DXMATRIX 확장 기능

D3DXMATRIX 구조체로, 다음의 연산자 overload와 타입 캐스트를 사용 가능하게 한다.

#ifdef __cplusplus
typedef struct D3DXMATRIX : public D3DMATRIX
{
public:
    D3DXMATRIX() {};
    D3DXMATRIX( CONST FLOAT * );
    D3DXMATRIX( CONST D3DMATRIX& );
    D3DXMATRIX( FLOAT _11, FLOAT _12, FLOAT _13, FLOAT _14,
                FLOAT _21, FLOAT _22, FLOAT _23, FLOAT _24,
                FLOAT _31, FLOAT _32, FLOAT _33, FLOAT _34,
                FLOAT _41, FLOAT _42, FLOAT _43, FLOAT _44 );

    // 액세스 허가
    FLOAT& operator () ( UINT Row, UINT Col );
    FLOAT  operator () ( UINT Row, UINT Col ) const;

    // 연산자의 캐스팅
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 대입 연산자
    D3DXMATRIX& operator *= ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator += ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator -= ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator *= ( FLOAT );
    D3DXMATRIX& operator /= ( FLOAT );

    // 단항 연산자
    D3DXMATRIX operator + () const;
    D3DXMATRIX operator - () const;

    // 2 항연산자
    D3DXMATRIX operator * ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator + ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator - ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator * ( FLOAT ) const;
    D3DXMATRIX operator / ( FLOAT ) const;

    friend D3DXMATRIX operator * ( FLOAT, CONST D3DXMATRIX& );

    BOOL operator == ( CONST D3DXMATRIX& ) const;
    BOOL operator ! = ( CONST D3DXMATRIX& ) const;

} D3DXMATRIX, *LPD3DXMATRIX;

#else //! __cplusplus

동작환경

헤더 : D3dx8math.h 로 선언.


D3DXPLANE 확장 기능

D3DXPLANE 구조체로, 다음의 연산자 overload와 타입 캐스트를 사용 가능하게 한다.

#ifdef __cplusplus
public:
    D3DXPLANE() {}
    D3DXPLANE( CONST FLOAT* );
    D3DXPLANE( FLOAT a, FLOAT b, FLOAT c, FLOAT d );

    // 캐스팅
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 단항 연산자
    D3DXPLANE operator + () const;
    D3DXPLANE operator - () const;

    // 2 항연산자
    BOOL operator == ( CONST D3DXPLANE& ) const;
    BOOL operator ! = ( CONST D3DXPLANE& ) const;

#endif //__cplusplus

동작환경

헤더 : D3dx8math.h 로 선언.


D3DXQUATERNION 확장 기능

D3DXQUATERNION 구조체로, 다음의 연산자 overload와 타입 캐스트를 사용 가능하게 한다.

#ifdef __cplusplus
public:
    D3DXQUATERNION() {}
    D3DXQUATERNION( CONST FLOAT * );
    D3DXQUATERNION( FLOAT x, FLOAT y, FLOAT z, FLOAT w );

    // 캐스팅
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 대입 연산자
    D3DXQUATERNION& operator += ( CONST D3DXQUATERNION& );
    D3DXQUATERNION& operator -= ( CONST D3DXQUATERNION& );
    D3DXQUATERNION& operator *= ( CONST D3DXQUATERNION& );
    D3DXQUATERNION& operator *= ( FLOAT );
    D3DXQUATERNION& operator /= ( FLOAT );

    // 단항 연산자
    D3DXQUATERNION  operator + () const;
    D3DXQUATERNION  operator - () const;

    // 2 항연산자
    D3DXQUATERNION operator + ( CONST D3DXQUATERNION& ) const;
    D3DXQUATERNION operator - ( CONST D3DXQUATERNION& ) const;
    D3DXQUATERNION operator * ( CONST D3DXQUATERNION& ) const;
    D3DXQUATERNION operator * ( FLOAT ) const;
    D3DXQUATERNION operator / ( FLOAT ) const;

    friend D3DXQUATERNION operator * (FLOAT, CONST D3DXQUATERNION& );

    BOOL operator == ( CONST D3DXQUATERNION& ) const;
    BOOL operator ! = ( CONST D3DXQUATERNION& ) const;

#endif //__cplusplus

동작환경

헤더 : D3dx8math.h 로 선언.


D3DXVECTOR2 확장 기능

D3DXVECTOR2 구조체로, 다음의 연산자 overload와 타입 캐스트를 사용 가능하게 한다.

#ifdef __cplusplus
public:
    D3DXVECTOR2() {};
    D3DXVECTOR2( CONST FLOAT * );
    D3DXVECTOR2( FLOAT x, FLOAT y );

    // 캐스팅
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 대입 연산자
    D3DXVECTOR2& operator += ( CONST D3DXVECTOR2& );
    D3DXVECTOR2& operator -= ( CONST D3DXVECTOR2& );
    D3DXVECTOR2& operator *= ( FLOAT );
    D3DXVECTOR2& operator /= ( FLOAT );

    // 단항 연산자
    D3DXVECTOR2 operator + () const;
    D3DXVECTOR2 operator - () const;

    // 2 항연산자
    D3DXVECTOR2 operator + ( CONST D3DXVECTOR2& ) const;
    D3DXVECTOR2 operator - ( CONST D3DXVECTOR2& ) const;
    D3DXVECTOR2 operator * ( FLOAT ) const;
    D3DXVECTOR2 operator / ( FLOAT ) const;

    friend D3DXVECTOR2 operator * ( FLOAT, CONST D3DXVECTOR2& );

    BOOL operator == ( CONST D3DXVECTOR2& ) const;
    BOOL operator ! = ( CONST D3DXVECTOR2& ) const;

public:
#endif //__cplusplus

동작환경

헤더 : D3dx8math.h 로 선언.


D3DXVECTOR3 확장 기능

D3DXVECTOR3 구조체로, 다음의 연산자 overload와 타입 캐스트를 사용 가능하게 한다.

#ifdef __cplusplus
typedef struct D3DXVECTOR3 : public D3DVECTOR
{
public:
    D3DXVECTOR3() {};
    D3DXVECTOR3( CONST FLOAT * );
    D3DXVECTOR3( CONST D3DVECTOR& );
    D3DXVECTOR3( FLOAT x, FLOAT y, FLOAT z );

    // 캐스팅
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 대입 연산자
    D3DXVECTOR3& operator += ( CONST D3DXVECTOR3& );
    D3DXVECTOR3& operator -= ( CONST D3DXVECTOR3& );
    D3DXVECTOR3& operator *= ( FLOAT );
    D3DXVECTOR3& operator /= ( FLOAT );

    // 단항 연산자
    D3DXVECTOR3 operator + () const;
    D3DXVECTOR3 operator - () const;

    // 2 항연산자
    D3DXVECTOR3 operator + ( CONST D3DXVECTOR3& ) const;
    D3DXVECTOR3 operator - ( CONST D3DXVECTOR3& ) const;
    D3DXVECTOR3 operator * ( FLOAT ) const;
    D3DXVECTOR3 operator / ( FLOAT ) const;

    friend D3DXVECTOR3 operator * ( FLOAT, CONST struct D3DXVECTOR3& );

    BOOL operator == ( CONST D3DXVECTOR3& ) const;
    BOOL operator ! = ( CONST D3DXVECTOR3& ) const;

} D3DXVECTOR3, *LPD3DXVECTOR3;

#else //! __cplusplus

동작환경

헤더 : D3dx8math.h 로 선언.


D3DXVECTOR4 확장 기능

D3DXVECTOR4 구조체로, 다음의 연산자 overload와 타입 캐스트를 사용 가능하게 한다.

#ifdef __cplusplus
public:
    D3DXVECTOR4() {};
    D3DXVECTOR4( CONST FLOAT* );
    D3DXVECTOR4( FLOAT x, FLOAT y, FLOAT z, FLOAT w );

    // 캐스팅
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 대입 연산자
    D3DXVECTOR4& operator += ( CONST D3DXVECTOR4& );
    D3DXVECTOR4& operator -= ( CONST D3DXVECTOR4& );
    D3DXVECTOR4& operator *= ( FLOAT );
    D3DXVECTOR4& operator /= ( FLOAT );

    // 단항 연산자
    D3DXVECTOR4 operator + () const;
    D3DXVECTOR4 operator - () const;

    // 2 항연산자
    D3DXVECTOR4 operator + ( CONST D3DXVECTOR4& ) const;
    D3DXVECTOR4 operator - ( CONST D3DXVECTOR4& ) const;
    D3DXVECTOR4 operator * ( FLOAT ) const;
    D3DXVECTOR4 operator / ( FLOAT ) const;

    friend D3DXVECTOR4 operator * ( FLOAT, CONST D3DXVECTOR4& );

    BOOL operator == ( CONST D3DXVECTOR4& ) const;
    BOOL operator ! = ( CONST D3DXVECTOR4& ) const;

public:
#endif //__cplusplus

동작환경

헤더 : D3dx8math.h 로 선언.


반환값

에러는 부의 값으로 나타내져 짜 합쳐질 것은 없다. 이하는, Direct3DX 유틸리티 라이브러리에 포함되는 메소드가 돌려줄 가능성이 있는 값을 나타내고 있다. 메소드로부터 돌려주어지는 값에 대해서는, 각각의 설명을 참조할것. 이러한 리스트는 반드시 포괄적인 것이라고는 할 수 없다.

D3DXERR_CANNOTATTRSORT
최적화 테크닉으로서 속성의 소트 (D3DXMESHOPT_ATTRSORT)는 지원되어 있지 않다.
D3DXERR_CANNOTMODIFYINDEXBUFFER
인덱스 버퍼를 변경할 수 없다.
D3DXERR_INVALIDMESH
메쉬가 무효이다.
D3DXERR_SKINNINGNOTSUPPORTED
스키닝은 지원되어 있지 않다.
D3DXERR_TOOMANYINFLUENCES
지정된 영향이 너무 많다.
D3DXERR_INVALIDDATA
데이터가 무효이다.


Direct3DX 쉐이더 어셈블러 레퍼런스

여기에서는, Direct3DX 유틸리티 라이브러리가 제공하는 버텍스 쉐이더 어셈블러 및 픽셀 쉐이더 어셈블러의 레퍼런스 정보를 기술한다.

  • 버텍스 쉐이더 어셈블러 레퍼런스
  • 픽셀 쉐이더 어셈블러 레퍼런스

이 메뉴얼로 사용되고 있는 구문의 예는 모두, Direct3DX 버텍스 쉐이더 어셈블러 및 픽셀 쉐이더 어셈블러를 사용하는 경우의 쉐이더의 기술 방법을 나타내기 위한 것이다.


버텍스 쉐이더 어셈블러 레퍼런스

여기에서는, 버텍스 쉐이더 어셈블러에 대한 레퍼런스 정보를 기술한다. 레퍼런스 정보는 다음의 카테고리로 분류되고 있다.

  • 레지스터
  • 명령
  • 수식자

버텍스 쉐이더 어셈블러는, 일련의 레지스터 및 그 레지스터상에서 실행할 수 있는 처리군으로 구성되어 있다. 처리는, 연산자와 1 개 이상의 인수 (오퍼랜드)로 구성되는 명령으로서 표현되고 있다.


레지스터

여기에서는, Direct3DX 버텍스 쉐이더 어셈블러가 이행 하는 입력 및 출력 레지스터에 대한 레퍼런스 정보를 기술한다. 설명하는 주제는, 다음과 같다.

  • 입력 레지스터
  • 출력 레지스터

모든 레지스터는 4 성분 부동 소수점 벡터이다. 이 메뉴얼에서는, 벡터의 요소는, x, y, z 및 w 로서 지정하지만, 시멘틱스는 지정되어 있지 않다.


입력 레지스터

다음의 표는, Microsoft® DirectX® 8.0 의 버텍스 쉐이더를 이용할 수 있는 최저한의 입력 레지스터의 일람이다. 이 표는, 버젼 1.0 의 픽셀 쉐이더에 적용된다.

이름 | 수 | I/O 허가 | 명령 근처의 사용 가능수
an | 1 스칼라 | 기입/사용 전용 | 버젼 1.0 에서는 0. 버젼 1.1 에서는 1.
c[n] | 96 벡터 | 독해 전용 | 1
rn | 12 벡터 | 읽고 쓰기 가능 | 3
vn | 16 벡터 | 독해 전용 | 1


an

이것들은 어드레스 레지스터이다. 이러한 레지스터는, Microsoft® DirectX® 8.0 의 버텍스 쉐이더 버젼 1.0 에서는 사용하지 못하고, 버젼 1.1 에서는 단일의 레지스터만 사용할 수 있다. a0.x 와 나타내지는 어드레스 레지스터는, 정수 레지스터 파일에 대한 상대 어드레스 지정에 있어서의 부호 첨부 정수 오프셋(offset)로서 사용할 수 있다.

c[a0.x + n]

유효 범위외로부터의 독해에 대해서는, (0.0, 0.0, 0.0, 0.0)가 돌아간다. 어드레스 레지스터는,mov 명령 에 대해서만 목적지가 될 수가 있다. 버텍스 쉐이더는, 어드레스 레지스터의 값을 읽어내지 못하고, 정수 레지스터 파일의 상대 어드레스 지정으로 사용하는 것만이 할 수 있다. 지원 되고 있는 정수 레지스터의 범위의 외측의 주소가 지정되고 있는 경우, 거기에 따른 독해로부터는 예측 불가능한 결과가 돌아간다.

어드레스 레지스터를 사용하는 버젼 1.0 의 버텍스 쉐이더에서는, 버텍스 쉐이더를 생성 하는 Microsoft Direct3D® API 의 호출이 실패한다. 버젼 1.1 의 버텍스 쉐이더도, 어드레스 레지스터를 설정하지 않고 사용을 시도하면(자) 실패한다.


c[n]

이것들은 정수 레지스터이다. 정수 레지스터 파일을 구성하는 것은, 최저 96 개의 4 성분 부동 소수점값벡터이다. 정수 레지스터는, 절대 위치 또는 상대 위치에서 지정할 수 있다.

    c[n]            ; 절대 위치
    c[a0.x + n]     ; 상대 위치

따라서, 정수 레지스터는, 절대 주소를 사용해 읽어내는 일도, 어드레스 레지스터를 개입시켜 상대적으로 주소 지정할 수도 있다. 레지스터의 범위외로부터 독해를 실시하면, (0.0, 0.0, 0.0, 0.0)가 돌아간다.

버텍스 쉐이더로부터 보면(자), 정수 레지스터 파일은 읽어내 전용이다. 1 회의 명령으로 액세스 할 수 있는 정수 레지스터는 1 개 뿐이다. 다만, 그 명령에 포함되는 각 소스는 읽어낸 벡터를 개별적으로 바꿔 넣거나 정부를 반전하거나 할 수 있다.

D3DCAPS8 의 MaxVertexShaderConst 멤버는, 사용 가능한 정수 레지스터의 개수를 나타낸다. Microsoft® DirectX® 8.0 의 쉐이더는, 적어도 96 개의 정수를 지원 한다.

정수 레지스터 파일의 데이터는, 버텍스 쉐이더의 정수 레지스터를 설정하는 Microsoft Direct3D® API 함수를 호출하면 로드 된다. 대신에, 쉐이더를 생성 할 경우에,IDirect3DDevice8::SetVertexShader 의 호출에 의해, C++ 어플리케이션으로 로드하는 정수를 지정할 수 있다.


rn

이것들은 텐포라리레지스타이다. 텐포라리레지스타는, 12 개의 4D 부동 소수점값벡터에 그룹화 되고 있다. 각 텐포라리레지스타에 대해서는, 1 회의 기입 액세스와 3 회의 독해 액세스를 동시에 실시할 수가 있다. 따라서, 1 개의 명령은, 입력 소스 오퍼랜드세트로서 텐포라리레지스타를 3 개까지 사용할 수 있다.

버텍스 쉐이더에 의한 전회의 호출 후에 남아 있는 텐포라리레지스타안의 값을 사용할 수 없다. 기입을 하기 전의 텐포라리레지스타로부터 버텍스 쉐이더가 read를 실시하면, 그 버텍스 쉐이더를 생성 하는 Microsoft® Direct3D® API 의 호출은 실패한다.


vn

이것들은 버텍스 입력 레지스터이다. 1 개(살) 이상의 입력 버텍스 스트림으로부터의 각 버텍스는, 버텍스 쉐이더가 실행되기 전에, 버텍스 입력 레지스터에 로드 된다. 버텍스 입력 레지스터는, 16 개의 4 성분 부동 소수점값벡터로 구성되어 있는 레지스터 파일로, v0 로부터 v15 와 나타난다. 이러한 레지스터는 읽어내 전용이다.

1 회의 명령으로 액세스 할 수 있는 버텍스 입력 레지스터는 1 개 뿐이다. 다만, 그 명령에 포함되는 각 소스는 읽어낸 벡터를 개별적으로 바꿔 넣거나 정부를 반전시키거나 할 수 있다.

버텍스 쉐이더를 생성 하기 위해서 Microsoft® Direct3D® API 호출에게 건네지는 선언에서는, 소스 버텍스 스트림과 버텍스 입력 레지스터의 사이의 매핑이 정의되고 있다. 고정 기능 파이프라인의 경우, 입력 레지스터는 다음 표에 나타나고 있는 고정 매핑을 가진다.

벡터 컴퍼넌트 | 레지스터
위치 좌표 | 0
브렌드의 중량감 | 1
브렌드 식별자 | 2
법선 | 3
포인트 사이즈 | 4
디퓨즈 | 5
스펙큐러 | 6
텍스쳐 좌표 | 7
텍스쳐 좌표 1 | 8
텍스쳐 좌표 2 | 9
텍스쳐 좌표 3 | 10
텍스쳐 좌표 4 | 11
텍스쳐 좌표 5 | 12
텍스쳐 좌표 6 | 13
텍스쳐 좌표 7 | 14
위치 좌표 2 | 15
법선 2 | 16


출력 레지스터

출력 레지스터는, 래스터라이저에의 입력이라고 정의된다. 생성된 데이터는 출력 레지스터 파일에 기입해지지만, 이것은 기입해 전용의 액세스이다.

출력 레지스터는 라스터 쉐이더의 레지스터 모델에 의해 정의되고 있어 다음의 최저 개수를 지원 해야 한다.

이름 | I/O 허가 | 수
oDn | 기입 전용 | 2 개의 4D 벡터
oFog | 기입 전용 | 1 스칼라 플로트
oPos | 기입 전용 | 4D 벡터 1 개
oPts | 기입 전용 | 1 스칼라 플로트
oTn | 기입 전용 | 4 개의 4D 벡터

나타나지 않은 목적지 레지스터에의 기입해 처리는 무시된다.

레지스터명의 전을 뒤따르고 있는 소문자의 o 는, 출력 레지스터가 기입해 전용인 것을 나타내고 있다.

Microsoft® DirectX® 6.0 또는 7.0 의 픽셀 처리 모델만을 지원 하고 있는 이행 환경, 즉 픽셀 쉐이더가 없는 이행 환경에서 버텍스 쉐이더를 사용할 때는, 다음의 출력 레지스터를 이용할 수 있다.

이름 | I/0 허가 | 수 | 설명
oDn | 기입 전용 | 2 벡터 | 출력 칼라 데이터. 디퓨즈색 및 스펙큐러색을 위해서(때문에) 필요.
oPos | 기입 전용 | 1 벡터 | 출력 좌표. 클리핑을 위해서(때문에) 필요.
oTn | 기입 전용 | 2 벡터 | 출력 텍스쳐 좌표. 텍스쳐 블렌딩 스테이지에 동시에 바인드 할 수 있는 텍스쳐의 최대수를 위해서(때문에) 필요.


oDn

출력 데이터 레지스터. 버텍스 칼라 데이터를 출력하기 위해서 사용된다. 구체적으로는, 보간 되어 픽셀 쉐이더에 직접 전송 되는 출력 데이터 레지스터의 배열이다. 보통, 이러한 레지스터는 색의 처리에 사용된다.


oFog

출력 fog값레지스터. 이 값은, 보간 된 후 fog 테이블에 전송 되는 fog 계수이다. fog의 스칼라 x 요소만이 사용된다.


oPos

출력 위치 레지스터. 이 값은, 동차 클리핑 공간내의 위치 좌표이다. 이 값은, 버텍스 쉐이더가 기입하지 않으면 안 된다.


oPts

출력 위치 좌표 사이즈 레지스터. 포인트 사이즈의 스칼라 x 요소만이 사용된다.


oTn

출력 텍스쳐 좌표 레지스터. 구체적으로는, 보간 되어, 픽셀 쉐이더에 보내지는 샘플링 스테이지의 전송 데이터에 의해 텍스쳐 좌표로서 사용되는 출력 데이터 레지스터의 배열이다.


명령

여기에서는, Direct3DX 버텍스 쉐이더 어셈블러가 이행 하는 명령에 대한 레퍼런스 정보를 기술한다. 설명하는 주제는, 다음과 같다.

  • 일반 명령
  • 버젼 및 정수 정의 명령
  • 매크로 명령
  • 수식자

버텍스 쉐이더 프로그램은 128 개까지의 명령으로 구성할 수가 있어 명령은 최대로 3 개의 입력 인수 (소스 레지스터 오퍼랜드)를 가질 수가 있다.


일반 명령

Direct3DX 버텍스 쉐이더 어셈블러에서는, 다음의 일반적인 명령이 지원 되고 있다.

add | 가산
dp3 | 3 요소의 내적
dp4 | 4 요소의 내적
dst | 거리 벡터
expp | 지수 10 비트 정밀도
lit | 라이팅 계수
logp | 대수 10 비트 정밀도
mad | 곱셈과 가산
max | 최대
min | 최소
mov | 이동
mul | 곱셈
rcp | 역수
rsq | 역수 평방근
sge | 이상
slt | 미만
sub | 감산

각 소스 오퍼랜드는, 어느 요소를 전요소에 카피하거나 복제 등, 독해시에 자유롭게 바꿔 넣고 할 수 있다. 각 소스 오퍼랜드는 정부를 반전할 수 있다.

목적지 레지스터에의 기입에는, 개개의 요소의 마스킹을 포함할 수가 있다. 즉, 특정의 성분 (x, y, z, 또는 w)만이 갱신된다. 기입시의 교체나 정부의 반전은 지원되어 있지 않다. 따라서, 출력 마스크는, x, y, z, 그리고 w 의 순서가 아니면 안된다.

소프트웨어 에뮬레이션 프론트엔드는, 출력 레지스터 기입에서의 마스크를 사용해, 출력 버텍스 중(안)에서 쉐이더가 변경한 부분을 검출해, 거기에 따라서, 라스터화만의 사용을 위해서(때문에) 하드웨어에 송신하기 위한 , 출력의 유연한 버텍스 포맷 (FVF)을 계산한다.

픽셀 쉐이더 언어와는 달라, 버텍스 쉐이더 언어에서는 선형 보간 블렌딩 명령은 지원 되지 않고,dp3 연산자는 자동적으로 부의 결과를 0.0 에 제한하지 않는 것에 주의 해야 한다.

참조

매크로 명령


add

소스를 가산한다.

add   vDest, vSrc0, vSrc1

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,add 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = m_Source[0]. x + m_Source[1]. x;
    m_TmpReg.y = m_Source[0]. y + m_Source[1]. y;
    m_TmpReg.z = m_Source[0]. z + m_Source[1]. z;
    m_TmpReg.w = m_Source[0]. w + m_Source[1]. w;

    WriteResult();

주의

다음의 예는,add 명령의 사용법을 나타내고 있다.

add r0, v0, c2
add r1.xyz, r0.xyz, v1.xyz


dp3

소스의 3 요소에 의한 내적을 계산한다.

dp3   vDest, vSrc0, vSrc1

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,dp3 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x =
    m_TmpReg.y =
    m_TmpReg.z =
    m_TmpReg.w = m_Source[0]. x * m_Source[1]. x +
                 m_Source[0]. y * m_Source[1]. y +
                 m_Source[0]. z * m_Source[1]. z;

    WriteResult();

주의

다음의 예는,dp3 명령의 사용법을 나타내고 있다.

dp3 r2, r0, r1
dp3 r2.x, r0, r1


dp4

소스의 4 요소에 의한 내적을 계산한다.

dp4   vDest, vSrc0, vSrc1

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,dp4 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x =
    m_TmpReg.y =
    m_TmpReg.z =
    m_TmpReg.w = m_Source[0]. x * m_Source[1]. x +
                 m_Source[0]. y * m_Source[1]. y +
                 m_Source[0]. z * m_Source[1]. z +
                 m_Source[0]. w * m_Source[1]. w;

    WriteResult();

주의

다음의 예는,dp4 명령의 사용법을 나타내고 있다.

dp4 r2, r0, r1
dp4 r2.w, r0, r1


dst

거리 관련의 데이터를 계산한다.

dst   vDest, vSrc0, vSrc1

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,dst 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = 1;
    m_TmpReg.y = m_Source[0]. y * m_Source[1]. y;
    m_TmpReg.z = m_Source[0]. z;
    m_TmpReg.w = m_Source[1]. w;

    WriteResult();

주의

제 1 의 소스 오퍼랜드는 벡터 (무시, d*d, d*d, 무시)라고 보여져, 제 2 의 소스 오퍼랜드는 벡터 (무시, 1/d, 무시, 1/d)라고 보여진다. 목적지는, 결과의 벡터 (1, d, d*d, 1/d)이다.

다음의 예는,dst 명령의 사용법을 나타내고 있다.

dst r4, r0, r1


expp

지수 2x 의 부분 지원을 제공한다.

expp   vDest, vSrc0

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,expp 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);

    float w = m_Source[0]. w;
    float v = (float) floor(m_Source[0]. w);

    m_TmpReg.x = (float) pow(2, v);
    m_TmpReg.y = w - v;
    // 저정밀도 지수
    float tmp = (float) pow(2, w);
    DWORD tmpd = *(DWORD*) &tmp & 0xffffff00;
    m_TmpReg.z = *(float*) &tmpd;
    m_TmpReg.w = 1;

    WriteResult();

주의

지수에 부의 수를 지정했을 경우,expp 명령은 부정의 결과를 생성한다.

이 명령은, 2 를 바닥으로 하는 지수의 부분 정밀도를 계산한다. vDest. z 에는 근사해가 생성되어, 보다 정확한 값은 vDest. x*function(vDest. y)로 요구할 수가 있다. function 는, 한정된 범위 (0.0 <= vDest. y < 1.0)의 2*vDest. y 에 대해서 유저가 사용하는 근사이다.

이 명령에서는 스칼라 소스를 사용해,vDest. z 의 평가에는 저정밀도 계산을 사용할 수 있다. 다만, 근사 에러는, 절대 에러 (10 비트 정밀도)의 것 1/(211) 보다 작고, 0.0 <= t.y < 1.0 의 범위내에 없으면 안 된다. 또,expp 로부터 돌아가는 w 는 1.0 이다.

다음의 예는,expp 명령의 사용법을 나타내고 있다.

expp r5, r0


lit

라이팅의 부분 지원을 제공한다.

lit   vDest, vSrc0

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,lit 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);

    m_TmpReg.x = 1;
    m_TmpReg.y = 0;
    m_TmpReg.z = 0;
    m_TmpReg.w = 1;
    float power = m_Source[0]. w;
    const float MAXPOWER = 127.9961f;
    if (power < -MAXPOWER)
        power = -MAXPOWER;          // 8.8 고정 소수점 포맷에 적합.
    else
    if (power > MAXPOWER)
        power = -MAXPOWER;          // 8.8 고정 소수점 포맷에 적합.

    if (m_Source[0]. x > 0)
    {
        m_TmpReg.y = m_Source[0]. x;
        if (m_Source[0]. y > 0)
        {
            // 허용 되는 근사는 EXP(power * LOG(m_Source[0]. y))이다.
            m_TmpReg.z = (float)(pow(m_Source[0]. y, power));
        }
    }

    WriteResult();

주의

지수에 부의 수를 지정했을 경우,lit 명령은 부정의 결과를 생성한다.

이 명령은, 2 개의 내적과 1 개의 거듭제곱으로부터 라이팅 계수를 계산한다. 소스의 벡터에는, 다음의 유사 코드에 나타내는 것 같은 값이 포함되어 있는 것과 상정된다.

vSrc0.x = N*L        ; 법선과 라이트 벡터와의 내적
vSrc0.y = N*H        ; 법선과 반벡터와의 내적
vSrc0.z = ignored    ; 이 값은 무시된다
vSrc0.w = power      ; 거듭제곱, 이 값은 -128. 0 에서 128.0 의 범위가 아니면 안된다

vDest. z 의 평가에는 저정밀도 계산을 사용할 수 있다. 이행에서는, 거듭제곱 인수로 적어도 8 개의 소수 비트를 지원 할 필요가 있다. 내적은 정규화된 벡터로 계산되어, 클램프의 제한은 -128 으로부터 128 이다.

에러는 logp 와 expp 의 편성에 대응하고 있지 않으면 안되어, 즉 8 비트의 색성분에 대해서 최하정도 비트 (LSB) 약 1 개(살)이다.

다음의 예는,lit 명령의 사용법을 나타내고 있다.

lit r0, r1


logp

log2(x)의 부분 지원을 제공한다.

logp   vDest, vSrc0

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,logp 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);

    float v = ABSF(m_Source[0]. w);
    if (v ! = 0)
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w =
            (float)(log(v) /log(2));
    }
    else
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = MINUS_INFINITY();
    }

    WriteResult();

주의

이 명령은, 2 를 바닥으로 하는 대수의 부분 정밀도를 계산한다. vDest. z 에는 근사해가 생성되어, 보다 정확한 값은 vDest. x + function(vDest. y)로 요구할 수가 있다. function 는, 한정된 범위 (1.0 <= vDest. y < 2.0)의 log2(vDest. y)에 대해서 유저가 사용하는 근사이다.

logp 명령에서는, 부호 비트는 무시되는 스칼라 소스를 사용해,vDest. z 의 평가에는 저정밀도 계산을 사용할 수 있다. 근사 에러는, 절대 에러 (10 비트 정밀도)의 것 1/(211) 보다 작고, 1.0 <= t.y < 2.0 의 범위내에 없으면 안 된다. 소스 인수가 0 의 경우는, 결과의 벡터 (-infinity, 0.0, -infinity, 1.0)가 생성된다.

다음의 예는,logp 명령의 사용법을 나타내고 있다.

logp r0, r1


mad

소스를 곱셈 및 가산한다.

mad   vDest, vSrc0, vSrc1, vSrc2

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.
vSrc2
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,mad 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);
    SetSrcReg(2);

    m_TmpReg.x = m_Source[0]. x * m_Source[1]. x + m_Source[2]. x;
    m_TmpReg.y = m_Source[0]. y * m_Source[1]. y + m_Source[2]. y;
    m_TmpReg.z = m_Source[0]. z * m_Source[1]. z + m_Source[2]. z;
    m_TmpReg.w = m_Source[0]. w * m_Source[1]. w + m_Source[2]. w;

    WriteResult();

주의

다음의 예는,mad 명령의 사용법을 나타내고 있다.

mad r0, r1, r2, v3


max

소스의 최대치를 계산한다.

max   vDest, vSrc0, vSrc1

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.

처리

다음의 유사 코드는,max 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x=(m_Source[0]. x >= m_Source[1]. x) ?  m_Source[0]. x : m_Source[1]. x;
    m_TmpReg.y=(m_Source[0]. y >= m_Source[1]. y) ?  m_Source[0]. y : m_Source[1]. y;
    m_TmpReg.z=(m_Source[0]. z >= m_Source[1]. z) ?  m_Source[0]. z : m_Source[1]. z;
    m_TmpReg.w=(m_Source[0]. w >= m_Source[1]. w) ?  m_Source[0]. w : m_Source[1]. w;

    WriteResult();

주의

다음의 예는,max 명령의 사용법을 나타내고 있다.

max r2, r3, r4


min

소스의 최소 값을 계산한다.

min   vDest, vSrc0, vSrc1

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,min 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x=(m_Source[0]. x < m_Source[1]. x) ?  m_Source[0]. x : m_Source[1]. x;
    m_TmpReg.y=(m_Source[0]. y < m_Source[1]. y) ?  m_Source[0]. y : m_Source[1]. y;
    m_TmpReg.z=(m_Source[0]. z < m_Source[1]. z) ?  m_Source[0]. z : m_Source[1]. z;
    m_TmpReg.w=(m_Source[0]. w < m_Source[1]. w) ?  m_Source[0]. w : m_Source[1]. w;

    WriteResult();

주의

다음의 예는,min 명령의 사용법을 나타내고 있다.

min   r2, r3, r4


mov

소스의 내용을 목적지로 이동한다.

mov   vDest, vSrc0

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,mov 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);

    if( m_pDest == m_reg.m_a )
    {
        float p = (float) floor(m_Source[0]. x);
        *(int*) &m_pDest->x = FTOI(p);
    }
    else
    {
        m_TmpReg = m_Source[0];
        WriteResult();
    }

주의

다음의 예는,mov 명령의 사용법을 나타내고 있다.

mov r1, v2
mov r1.xy, r2.zw


mul

소스를 곱셈해 목적지에 저장 한다.

mul   vDest, vSrc0, vSrc1

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,mul 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = m_Source[0]. x * m_Source[1]. x;
    m_TmpReg.y = m_Source[0]. y * m_Source[1]. y;
    m_TmpReg.z = m_Source[0]. z * m_Source[1]. z;
    m_TmpReg.w = m_Source[0]. w * m_Source[1]. w;

    WriteResult();

주의

다음의 예는,mul 명령의 사용법을 나타내고 있다.

mul r4, v0, r1


rcp

소스 스칼라의 역수를 계산한다.

rcp   vDest, vSrc0

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,rcp 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);

    if( m_Source[0]. w == 1.0f )
    {
        // 정확하게 1.0 이 아니면 안된다.
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = 1.0f;
    }
    else if( m_Source[0]. w == 0 )
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = PLUS_INFINITY();
    }
    else
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = 1.0f/m_Source[0]. w;
    }

    WriteResult();

주의

소스에 첨자가 없는 경우는, x 요소가 사용된다. 입력이 1.0 의 경우는, 출력도 1.0 이 되어야 하다.

(1.0, 2.0)의 범위를 넘은 에러의 정밀도는 적어도 1.0/(222) 절대치이다. 이것은, 보통의 이행에서는 가수와 지수가 분리되기 때문에 있다. 0.0 의 소스는 무한대이다.

다음의 예는,rcp 명령의 사용법을 나타내고 있다.

rcp r1, r2
rcp r1, r2.y


rsq

소스 스칼라의 역수의 평방근을 계산한다.

rsq   vDest, vSrc0

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,rsq 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);

    float v = ABSF(m_Source[0]. w);
    if( v == 1.0f )
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = 1.0f;
    }
    else if( v == 0 )
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = PLUS_INFINITY();
    }
    else
    {
        v = (float)(1.0f / sqrt(v));
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = v;
    }

    WriteResult();

주의

소스에 첨자가 없는 경우는, x 요소가 사용된다. 입력이 1.0 의 경우는, 출력도 1.0 이 되어야 하다.

절대치는 처리전에 취득된다. 즉, 부호 비트는 무시된다.

(1.0, 4.0)의 범위를 넘은 에러의 정밀도는 적어도 1.0/(222) 절대치이다. 이것은, 보통의 이행에서는 가수와 지수가 분리되기 때문에 있다. 0.0 의 소스는 무한대이다.

다음의 예는,rsq 명령의 사용법을 나타내고 있다.

rsq r1, r2
rsq r1, r2.y


sge

제 1 소스 오퍼랜드의 값이 제 2 소스 오퍼랜드의 값이상의 경우는, 목적지에 1.0 을 설정한다. 그 이외의 경우는, 목적지에 0.0 을 설정한다.

sge   vDest, vSrc0, vSrc1

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,sge 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = (m_Source[0]. x >= m_Source[1]. x) ?  1.0f : 0.0f;
    m_TmpReg.y = (m_Source[0]. y >= m_Source[1]. y) ?  1.0f : 0.0f;
    m_TmpReg.z = (m_Source[0]. z >= m_Source[1]. z) ?  1.0f : 0.0f;
    m_TmpReg.w = (m_Source[0]. w >= m_Source[1]. w) ?  1.0f : 0.0f;

    WriteResult();

주의

다음의 예는,sge 명령의 사용법을 나타내고 있다.

sge   r1, r2, v1


slt

제 1 소스 오퍼랜드의 값이 제 2 소스 오퍼랜드의 값미만의 경우는, 목적지에 1.0 을 설정한다. 그 이외의 경우는, 목적지에 0.0 을 설정한다.

slt   vDest, vSrc0, vSrc1

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
vSrc1
입력 인수를 지정하는 소스 레지스터.

처리

다음의 코드는,slt 명령에 의해 실행되는 처리와 목적지에의 결과의 기입을 나타내고 있다.

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = (m_Source[0]. x < m_Source[1]. x) ?  1.0f : 0.0f;
    m_TmpReg.y = (m_Source[0]. y < m_Source[1]. y) ?  1.0f : 0.0f;
    m_TmpReg.z = (m_Source[0]. z < m_Source[1]. z) ?  1.0f : 0.0f;
    m_TmpReg.w = (m_Source[0]. w < m_Source[1]. w) ?  1.0f : 0.0f;

    WriteResult();

주의

다음의 예는,slt 명령의 사용법을 나타내고 있다.

slt   r1, r2, v1


sub

소스를 감산한다.

sub   tDest, tSrc0, tSrc1

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.
tSrc1
입력 인수를 지정하는 소스 레지스터.

주의

이 명령은, 다음의 공식으로 기초를 두어 감산을 실시한다.

tDest = tSrc0 - tSrc1

다음의 예는, 이 명령의 사용법을 나타내고 있다.

sub   r2, v2, r2    ; difference


버젼 및 정수 정의 명령

Direct3DX 버텍스 쉐이더 어셈블러에는, 쉐이더의 타입 및 버젼을 식별하거나 버텍스 쉐이더로 사용하는 정수를 정의하기 위한 명령이 준비되어 있다.

def | 정수를 정의한다
vs | 버젼 및 타입

버젼 명령은, 각 쉐이더의 선두에 있을 필요가 있다.

정수 정의 명령은, 버젼 명령의 실행 후, 다른 모든 명령보다 전에 실행해야 하는 것에 주의 해야 한다.


def

버텍스 쉐이더로 사용하는 정수를 정의하기 위한 메소드를 제공한다.

def   vDest, fVal0, fVal1, fVal2, fVal3

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
fVal0
입력 인수를 지정하는 소스 레지스터.
fVal1
입력 인수를 지정하는 소스 레지스터.
fVal2
입력 인수를 지정하는 소스 레지스터.
fVal3
입력 인수를 지정하는 소스 레지스터.

주의

다음의 예는,def 명령의 사용법을 나타내고 있다.

def c0, 0.0f, 0.0f, 0.0f, 1.0f
def c8, 1.0f, 2.0f, 3.0f, 4.0f

이러한 정수는, 쉐이더의 생성시에 선언에 포함되는 선언의 일부로서 돌려주어진다.


vs

쉐이더 코드의 타입 및 버젼을 지정하기 위한 메소드를 제공한다.

vs. mainVer. subVer

레지스터

mainVer
버텍스 쉐이더의 메인 버젼 번호.
subVer
버텍스 쉐이더의 서브 버젼 번호.

주의

다음의 예는,vs 명령의 사용법을 나타내고 있다.

vs. 1.0  ; 버텍스 쉐이더 버젼 1.0

이 명령은, 모든 버텍스 쉐이더의 선두에 있을 필요가 있다.


매크로 명령

Direct3DX 버텍스 쉐이더 어셈블러에서는, 공통의 단순한 처리를 실행할 때의 어플리케이션의 편의를 위해서(때문에), 매크로 명령이 제공되고 있다. 이러한 매크로는, 드라이버에 의해, 몇개의 표준적인 버텍스 쉐이더 명령에 확장되고 있다. 상세한 것에 대하여는, 각 매크로 명령의 레퍼런스 주제를 참조할것.

exp | 2 를 바닥으로 하는 지수의 완전 정밀도
frc | 소수부
log | 2 를 바닥으로 하는 대수의 완전 정밀도
m3x2 | 3 × 2 벡터 행렬의 곱셈
m3x3 | 3 × 3 벡터 행렬의 곱셈
m3x4 | 3 × 4 벡터 행렬의 곱셈
m4x3 | 4 × 3 벡터 행렬의 곱셈
m4x4 | 4 × 4 벡터 행렬의 곱셈

명령의 수의 상한인 128 을 넘을지 어떨지를 판단할 수 있도록(듯이) 하기 위한(해), 매크로 명령은, 열기되고 있는 실제의 명령의 수를 넘지 않는 것이 보증되고 있다.

매크로 명령은 실제의 명령과 같은 방법으로 이행 환경에게 건네지므로, 이행 환경은 자유롭게 매크로 명령을 최적화할 수 있다. 따라서, 필요한 타이밍 사이클 카운트에 대해서는 어떠한 상정도 할 수 없다.

참조

일반 명령


exp

최저 1/220 의 완전 정밀도의 지수 2x 를 제공한다.

exp   vDest, vSrc0

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.

처리

    SetDestReg();
    SetSrcReg(0);

    float v = m_Source[0]. w;

    m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = (float) pow(2, v);

    WriteResult();

전개

이 매크로는 12 의 명령 슬롯을 사용한다.

주의

이것은 스칼라 연산이며, 그 입력을 . w 채널로부터 취한다. 이 채널은 지정할 필요가 있다. 이 연산은, 항상 4 개(살)의 모든 채널에 결과를 복제한다.


frc

각 입력 요소의 소수 부분을 돌려준다.

frc   vDest, vSrc0

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.

처리

    SetDestReg();
    SetSrcReg(0);

    m_TmpReg.x = m_Source[0]. x - (float) floor(m_Source[0]. x);
    m_TmpReg.y = m_Source[0]. y - (float) floor(m_Source[0]. y);
    m_TmpReg.z = m_Source[0]. z - (float) floor(m_Source[0]. z);
    m_TmpReg.w = m_Source[0]. w - (float) floor(m_Source[0]. w);

    WriteResult();

전개

이 매크로는 3 개의 명령 슬롯을 사용한다.

주의

결과의 각 요소는, 0.0 에서 1.0 의 범위이다.

이 매크로는 x 및 y 요소를 기술할 뿐이다.


log

최저 1/220 의 완전 부동 소수점 정밀도로 log2(x)의 지원을 제공한다.

log   vDest, vSrc0

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.

처리

    SetDestReg();
    SetSrcReg(0);

    float v = ABSF(m_Source[0]. w);
    if (v ! = 0)
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w =
            (float)(log(v) /log(2));
    }
    else
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = minUS_INFINITY();
    }

    WriteResult();

전개

이 매크로는 12 의 명령 슬롯을 사용한다.

주의

이 명령에서는 부호 비트를 무시한 스칼라 소스 . w 가 받아들여진다. 결과는 4 개의 모든 채널에 복제된다.

입력 지수의 범위는,-128 으로부터 128 까지가 아니면 안된다. 근사 에러는, 절대 에러의 1/220 보다 작고, 1.0 <= t.y < 2.0 의 범위내에 없으면 안 된다. 소스가 0 의 경우는, (-infinity, -infinity, -infinity, -infinity)가 생성된다.


m3x2

입력 벡터와 3 × 2 행렬의 적을 계산한다.

m3x2   rDest, vSrc0, mSrc1

레지스터

rDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
mSrc1
입력 인수를 지정하는 소스 레지스터.

처리

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 2);
    m_TmpReg.x = m_Source[0]. x * m_Source[1]. x +
                 m_Source[0]. y * m_Source[1]. y +
                 m_Source[0]. z * m_Source[1]. z;
    m_TmpReg.y = m_Source[0]. x * m_Source[2]. x +
                 m_Source[0]. y * m_Source[2]. y +
                 m_Source[0]. z * m_Source[2]. z;

    WriteResult();

전개

다음의 예는 m3x2 명령의 사용법을 나타내고 있다.

m3x2   r5, v0, c[3]

내용

dp3   r5.x, v0, c[3]
dp3   r5.y, v0, c[4]

따라서, 이 매크로 명령은, 명령 카운트로부터 명령 슬롯을 2 개 소비한다. c[3] 및 c[4] 의 마지막 w 요소는 이 계산에 대해 무시되는 것에 주의한다.

주의

입력 벡터는 vSrc0 이며, 입력의 3 × 2 행렬은 mSrc1 및 같은 레지스터 파일내의 다음의 레지스터이다. 2D 의 결과가 생성되어,rDest 외의 요소 (z 및 w)는 변경되지 말고 그대로 남는다.

이 처리는, 일반적으로, 2D 트랜스 폼에 사용된다. 이 매크로 명령은, 1 대의 내적으로서 이행 된다.


m3x3

입력 벡터와 3 × 3 행렬의 적을 계산한다.

m3x3   rDest, vSrc0, mSrc1

레지스터

rDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
mSrc1
입력 인수를 지정하는 소스 레지스터.

처리

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 3);
    m_TmpReg.x = m_Source[0]. x * m_Source[1]. x +
                 m_Source[0]. y * m_Source[1]. y +
                 m_Source[0]. z * m_Source[1]. z;
    m_TmpReg.y = m_Source[0]. x * m_Source[2]. x +
                 m_Source[0]. y * m_Source[2]. y +
                 m_Source[0]. z * m_Source[2]. z;
    m_TmpReg.z = m_Source[0]. x * m_Source[3]. x +
                 m_Source[0]. y * m_Source[3]. y +
                 m_Source[0]. z * m_Source[3]. z;

    WriteResult();

전개

다음의 예는 m3x3 명령의 사용법을 나타내고 있다.

m3x3   r5, v0, c[3]

내용

dp3   r5.x, v0, c[3]
dp3   r5.y, v0, c[4]
dp3   r5.z, v0, c[5]

따라서, 이 매크로 명령은, 명령 카운트로부터 명령 슬롯을 3 개 소비한다. c[3], c[4], 및 c[5] 의 마지막 w 요소는 이 계산에 대해 무시되는 것에 주의 해야 한다.

주의

입력 벡터는 vSrc0 이며, 입력의 3 × 3 행렬은 mSrc1 및 같은 레지스터 파일내에서 이것에 계속되는 2 개의 레지스터이다.

이 처리는, 일반적으로, 라이팅 계산때의 법선 벡터의 트랜스 폼에 사용된다. 이 매크로 명령은, 일련의 내적으로서 이행 된다.


m3x4

입력 벡터와 3 × 4 행렬의 적을 계산한다.

m3x4   rDest, vSrc0, mSrc1

레지스터

rDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
mSrc1
입력 인수를 지정하는 소스 레지스터.

처리

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 4);
    m_TmpReg.x = m_Source[0]. x * m_Source[1]. x +
                 m_Source[0]. y * m_Source[1]. y +
                 m_Source[0]. z * m_Source[1]. z;
    m_TmpReg.y = m_Source[0]. x * m_Source[2]. x +
                 m_Source[0]. y * m_Source[2]. y +
                 m_Source[0]. z * m_Source[2]. z;
    m_TmpReg.z = m_Source[0]. x * m_Source[3]. x +
                 m_Source[0]. y * m_Source[3]. y +
                 m_Source[0]. z * m_Source[3]. z;
    m_TmpReg.w = m_Source[0]. x * m_Source[4]. x +
                 m_Source[0]. y * m_Source[4]. y +
                 m_Source[0]. z * m_Source[4]. z;

    WriteResult();

전개

다음의 예는 m3x4 명령의 사용법을 나타내고 있다.

m3x4   r5, v[0], c[3]

내용

dp3 r5.x, v[0], c[3]
dp3 r5.y, v[0], c[4]
dp3 r5.z, v[0], c[5]
dp3 r5.w, v[0], c[6]

따라서, 이 매크로 명령은, 명령 카운트로부터 명령 슬롯을 4 개 소비한다. c[3], c[4], 및 c[5] 의 마지막 w 요소는 이 계산에 대해 무시되는 것에 주의 해야 한다.

주의

입력 벡터는 vSrc0 이며, 입력의 3 × 4 행렬은 mSrc1 및 같은 레지스터 파일내에서 이것에 계속되는 2 개의 레지스터이다.

이 처리는, 일반적으로, 투영 이펙트는 있지만 평행이동은 실시하지 않는 행렬에 의한, 위치 벡터의 트랜스 폼에 사용된다. 이 매크로 명령은, 일련의 내적으로서 이행 된다.


m4x3

입력 벡터와 4 × 3 행렬의 적을 계산한다.

m4x3   rDest, vSrc0, mSrc1

레지스터

rDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
mSrc1
입력 인수를 지정하는 소스 레지스터.

처리

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 3);
    m_TmpReg.x = m_Source[0]. x * m_Source[1]. x +
                 m_Source[0]. y * m_Source[1]. y +
                 m_Source[0]. z * m_Source[1]. z +
                 m_Source[0]. w * m_Source[1]. w;
    m_TmpReg.y = m_Source[0]. x * m_Source[2]. x +
                 m_Source[0]. y * m_Source[2]. y +
                 m_Source[0]. z * m_Source[2]. z +
                 m_Source[0]. w * m_Source[2]. w;
    m_TmpReg.z = m_Source[0]. x * m_Source[3]. x +
                 m_Source[0]. y * m_Source[3]. y +
                 m_Source[0]. z * m_Source[3]. z +
                 m_Source[0]. w * m_Source[3]. w;

    WriteResult();

전개

다음의 예는 m4x3 명령의 사용법을 나타내고 있다.

m4x3   r5, v[0], c[3]

내용

dp4   r5.x, v[0], c[3]
dp4   r5.y, v[0], c[4]
dp4   r5.z, v[0], c[5]

따라서, 이 매크로 명령은, 명령 카운트로부터 명령 슬롯을 3 개 소비한다. 입력 벡터의 w 의 값이 1.0 이 아닌 한, c[3], c[4], 및 c[5] 의 마지막 w 요소는 이 계산에 대해 무시되는 것에 주의 해야 한다. 이 w 의 값이 0.0 의 경우는, 입력 벡터의 평행이동은 행해지지 않는다. 즉, 행렬의 평행이동 요소는 적용되지 않는다.

주의

입력 벡터는 vSrc0 이며, 입력의 4 × 3 행렬은 mSrc1 및 같은 레지스터 파일내에서 이것에 계속되는 2 개의 레지스터이다.

이 처리는, 일반적으로, 모델 공간의 트랜스 폼에 대해 발생하는 경우 등, 투영 이펙트가 없는 행렬에 의한 위치 벡터의 트랜스 폼에 사용된다. 이 매크로 명령은, 일련의 내적으로서 이행 된다.


m4x4

입력 벡터와 4 × 4 행렬의 적을 계산한다.

m4x4   rDest, vSrc0, mSrc1

레지스터

rDest
처리의 결과를 보관 유지하는 목적지 레지스터.
vSrc0
입력 인수를 지정하는 소스 레지스터.
mSrc1
입력 인수를 지정하는 소스 레지스터.

처리

   SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 4);
    m_TmpReg.x = m_Source[0]. x * m_Source[1]. x +
                 m_Source[0]. y * m_Source[1]. y +
                 m_Source[0]. z * m_Source[1]. z +
                 m_Source[0]. w * m_Source[1]. w;
    m_TmpReg.y = m_Source[0]. x * m_Source[2]. x +
                 m_Source[0]. y * m_Source[2]. y +
                 m_Source[0]. z * m_Source[2]. z +
                 m_Source[0]. w * m_Source[2]. w;
    m_TmpReg.z = m_Source[0]. x * m_Source[3]. x +
                 m_Source[0]. y * m_Source[3]. y +
                 m_Source[0]. z * m_Source[3]. z +
                 m_Source[0]. w * m_Source[3]. w;
    m_TmpReg.w = m_Source[0]. x * m_Source[4]. x +
                 m_Source[0]. y * m_Source[4]. y +
                 m_Source[0]. z * m_Source[4]. z +
                 m_Source[0]. w * m_Source[4]. w;

    WriteResult();

전개

다음의 예는 m4x4 명령의 사용법을 나타내고 있다.

m4x4   r5, v[0], c[3]

내용

dp4   r5.x, v[0], c[3]
dp4   r5.y, v[0], c[4]
dp4   r5.z, v[0], c[5]
dp4   r5.w, v[0], c[6]

따라서, 이 매크로는, 명령 카운트로부터 4 개의 명령 슬롯을 사용한다.

주의

입력 벡터는 vSrc0 이며, 입력의 4 × 4 행렬은 mSrc1 및 같은 레지스터 파일내에서 이것에 계속되는 3 개의 레지스터이다.

이 처리는, 일반적으로, 투영 행렬에 의한 위치 좌표의 트랜스 폼에 사용된다. 이 매크로 명령은, 일련의 내적으로서 이행 된다.


수식자

여기에서는, Direct3DX 버텍스 쉐이더 어셈블러가 이행 하는 성분 수식자에 대한 레퍼런스 정보를 기술한다.

다음 표로 가리키도록(듯이), 성분 수식자 (x 는 유효한 레지스터, 즉 an ,c[n] ,rn ,vn , 또는출력 레지스터의 어느쪽이든)는, 벡터 데이터의 개별의 성분에 적용할 수 있다.

성분 수식자 | 설명
r. {x}{y}{z}{w} | 목적지 마스크
r. [xyzw][xyzw][xyzw][xywz] | 소스의 교체
-r | 목적지의 정부를 반전


픽셀 쉐이더 어셈블러 레퍼런스

여기에서는, Direct3DX 픽셀 쉐이더 어셈블러에 대한 레퍼런스 정보를 기술한다. 레퍼런스 정보는 다음의 카테고리로 분류되고 있다.

  • 레지스터
  • 명령
  • 수식자
  • 출력 기입 마스크

픽셀 쉐이더 어셈블러는, 일련의 레지스터 및 그 레지스터상에서 실행할 수 있는 처리군으로 구성되어 있다. 처리는, 연산자와 1 개 이상의 인수 (오퍼랜드)로 구성되는 명령으로서 표현되고 있다.

Microsoft® DirectX® 8.0 에서는, 모든 표면 포맷에 대해서 적어도 8 비트의 정밀도를 유지하기 위한 중간 계산이 필요하다. 스테이지내의 계산에서는 고정밀도 (12 비트)가, 텍스쳐 스테이지간에서는 8 비트에 거두는 것이 추천 되고 있다. 수정 가능한 둥근 모드나 예외는 지원되어 있지 않다. 정밀도의 손실을 최소화하기 위해서, 바로 옆값 둥근 정밀도의 곱셈이 지원 되고 있을 필요가 있다.


레지스터

여기에서는, Direct3DX 픽셀 쉐이더 어셈블러가 이행 하는 레지스터에 대한 레퍼런스 정보를 기술한다.

이름 | I/0 허가 | 최소 카운트 | 명령마다의 최대 카운트 | 소스
cn | 독해 전용 | 8 | 2 | API 호출
rn | 읽고 쓰기 가능 | 2 | 2 | 기입해졌다
tn | 읽고 쓰기 가능 | 4 | 1 | 텍스쳐
vn | 독해 전용 | 2 | 1 | 버텍스 칼라

「최소 카운트」의 열은, Microsoft® DirectX® 8.0 의 쉐이딩 능력을 공개하기 위해서 이행 환경이 지원 해야 하는 레지스터의 최소 개수를 나타내고 있다.

「명령마다의 최대 카운트」의 열은, 1 개의 명령이 지원 하는 레지스터의 최대 개수를 나타내고 있다. 이것에는, 명령에 대한 소스 파라미터의 독해 포토가 포함된다. 명령의 목적지 파라미터에 제한은 적용되지 않는다.

각 레지스터는 4 요소의 벡터이며, 요소의 범위는 -1. 0 에서 1.0 까지로, 요소마다의 정밀도는 최저 8 비트이다. 버텍스 쉐이더 어셈블러와는 달라, 픽셀 쉐이더 어셈블러는 출력 레지스터를 가지지 않는다. 픽셀 쉐이더는 r0 만을 출력한다.


cn

이것들은 정수 레지스터이다. 정수 D3DRS_TEXTUREFACTOR 로부터 취득되는 고정 요소 레지스터는,IDirect3DDevice8::SetPixelShaderConstant 메소드를 사용해 어플리케이션에 의해 로드 된다.

고정 요소 레지스터는 읽어내 전용이다. 픽셀 쉐이더용으로 적어도 8 개의 고정 요소 레지스터가 정의되지만, 1 개의 명령으로 사용할 수 있는 것은 2 개(살)까지이다.


rn

이것들은 텐포라리레지스타이다. 텐포라리레지스타는 중간 결과를 저장 하기 위해서 사용할 수 있다. 텐포라리레지스타는 읽고 쓰기 가능해, 1 개의 쉐이더 명령으로 사용할 수 있는 것은 2 개(살)까지이다. 디버그 런타임에 있어서의 쉐이더의 사전 처리에서는, 전의 명령으로 기입해지지 않은 텐포라리레지스타로부터 독해를 실시하려고 하는 쉐이더에 대해,IDirect3DDevice8::CreatePixelShader 는 실패한다.

모든 픽셀 쉐이더는 최종 결과적으로 r0 를 기입할 필요가 있기 (위해)때문에, 가장 단순한 디칼 픽셀 쉐이더는 2 개의 명령으로 구성된다.

ps. 1.0       // DirectX8 버젼.
tex   t0
mov   r0, t0


tn

이것들은 텍스쳐 레지스터이다. 텍스쳐 레지스터의 최대수는, 동시에 지원 되는 텍스쳐의 수와 같다. 텍스쳐 레지스터는, 그 스테이지의 텍스쳐 스테이지 스테이트에 의해 정의되는 필터 링 모드를 포함한, 텍스쳐 샘플링 유니트로부터의 텍스쳐 칼라를 저장 하는 것으로 초기화된다. 색은,IDirect3DDevice8::SetTexture 로 정의되고 있는 대응하는 텍스쳐로부터 취득되어 대응하는 텍스쳐 좌표로 샘플링 된다.

텍스쳐 세트를 가지지 않는 모든 텍스쳐 레지스터는, 불투명의 흑 (0,0,0,1)으로서 샘플링 된다. 1 개의 쉐이더 명령으로 사용할 수 있는 텍스쳐 레지스터는 2 개까지이다. 텍스쳐 레지스터는, 텐포라리레지스타라고 해도 사용할 수 있다. 구체적으로는, 텍스쳐 애드레싱 명령의 후에, 이러한 레지스터는 읽고 쓰기 텐포라리레지스타로서 사용할 수 있다.

대부분의 경우, 텍스쳐 레지스터는, 텍스쳐 커멘드의 목적지로서의 보고 유효하다. 다만, 텍스쳐 레지스터로부터 산술 명령을 읽어낼 수가 있는 것에 주의 해야 한다.


vn

이것들은 버텍스 칼라 레지스터이다. 입력 버텍스 칼라 레지스터에는, 버텍스 쉐이더로부터 출력되는 칼라값의 픽셀 단위의 굿 로 보간에 의해 취득되는 칼라값이 저장 된다 (버텍스 쉐이더는 칼라값을 버텍스 스트림으로부터 받을 수가 있다). Microsoft® DirectX® 8.0 에 준거한 이행에서는, 적어도 2 개의 입력 칼라 레지스터를 지원 해야 한다.

입력 칼라 레지스터는 읽어내 전용으로, 1 개의 명령에서는 이러한 색중 1 개(살)만 사용할 수 있다.

flat shading를 시뮬레이트 하려면 정수 칼라가 효과적이다. 다만, 쉐이드 모드가 D3DSHADE_FLAT 때는, 어느 쪽의 색의 보간도 무효가 되어 있다. fog는 계속해 보간 되지 않으면 안 되는 것에 주의할 필요가 있다. 이상적이게는, 모든 색보간은, 텍스쳐 좌표 보간과 같은 방법의 퍼스펙티브 보정이 아니면 안된다.


명령

Direct3DX 컴파일러가 인식하는, 픽셀 쉐이더에 대한 처리는 주로 2 개(살)로 분류되어 픽셀색 및 알파 블렌딩 처리와 텍스쳐 블렌딩 처리가 있다. 어셈블러는, 명령을 사용해 이러한 처리를 제공하고 있다. 픽셀색 및 알파 블렌딩 처리는 칼라 데이터를 변경해서 , 텍스쳐 애드레싱 처리는 텍스쳐의 좌표 데이터를 조작 및 처리한다. 픽셀 쉐이더의 모든 명령은 픽셀 단위에 실행된다. 즉, 파이프라인내외의 픽셀은 인식되지 않는다.

  • 색 및 알파 블렌딩 명령
  • 버젼 및 정수 정의 명령
  • 텍스쳐 애드레싱 명령

블렌딩 처리는, RGB 색과 스칼라 알파의 개별 처리에 사용할 수 있다. 대부분의 경우, 픽셀 블렌딩 (색 또는 알파) 처리는, 색명령이라고 알파 명령의 양쪽 모두를 1 슬롯에서 지원 할 수 있다.

준거한 이행에서는, 최저 8 개의 블렌딩 명령과 4 개의 애드레싱 명령의 프로그램을 지원 해야 한다.

텍스쳐 애드레싱 처리는 각각 1 슬롯을 사용하지만, 픽셀 블렌딩 (색 및 알파) 처리는 대상으로 해, 색명령이라고 알파 명령의 양쪽 모두를 1 슬롯에서 실행할 수 있다. Microsoft® DirectX® 8.0 에서는, 텍스쳐 애드레싱 명령은 칼라 블렌딩 명령보다 먼저 실행해야 한다.

텍스쳐 주소 보정 처리의 구문은, 쉐이더 프로그램 자체에, 텍스쳐 선언의 형식에서 포함되어 있다. 이것들은, 픽셀 쉐이더 본체로 사용하기 위해서 텐포라리레지스타파일에 프리로드 할 경우에 텍스쳐로부터 샘플링 되는 색의 값에 대해서, 어떻게 주소 보정 처리를 적용하는지를 제어한다.


색 및 알파 블렌딩 명령

여기에서는, Direct3DX 픽셀 쉐이더 어셈블러가 이행 하는 색 및 알파 블렌딩 명령에 대한 레퍼런스 정보를 기술한다.

다음의 표는, 색 및 알파 블렌딩 명령의 일람이다. 이러한 처리는 모두 컴퍼넌트 단위로 실행된다.

명령 | 설명
add | 가산
cnd | 조건
dp3 | 3 요소 벡터의 내적
lrp | 선형 보간 블렌딩
mad | 곱셈과 가산
mov | 카피원으로부터 카피처에의 카피
mul | 곱셈
sub | 소스 오퍼랜드의 2 색의 차이를 로드한다


add

소스 오퍼랜드의 2 개의 색의 합계를 로드한다.

add   tDest, tSrc0, tSrc1

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.
tSrc1
입력 인수를 지정하는 소스 레지스터.

주의

다음의 예는, 이 명령의 사용법을 나타내고 있다.

add d, s1, s2    ; sum d = s1 + s2


cnd

r0.a 의 값을 0.5 와 비교하는 조건 연산을 실행한다.

cnd   tDest, tSrc0, tSrc1, tSrc2

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.
tSrc1
입력 인수를 지정하는 소스 레지스터.
tSrc2
입력 인수를 지정하는 소스 레지스터.

주의

이 명령은, r0.a 의 값과 0.5 를 비교하기 위해서 마셔 사용할 수 있다. 알파 (r0.a)가 0.5 보다 큰 경우, 최초의 소스가 결과적으로 돌려주어진다. 그 이외의 경우는, 2 번째의 소스가 돌려주어진다.

다음의 예는, 이 명령의 사용법을 나타내고 있다.

cnd d, r0.a, s1, s2    ; d = ( r0.a >0. 5 ?  s1 : s2 )

a - (b - 0.5) = a - b + 0.5 이므로, 2 개의 값을 비교하려면 , 다음의 픽셀 쉐이더 코드를 사용할 수 있다.

sub r0, v0,   v1_bias
cnd r0, r0.a, c0, c1

전에 설명한 것처럼, 최초의 소스 인수에 배치할 수 있는 값은 r0.a 뿐이어서, 비교값은 "0.5 보다 크지" 않으면 안 된다.


dp3

소스 오퍼랜드 레지스터의 2 색의 3 요소 벡터 내적을 로드한다.

dp3   tDest, tSrc0, tSrc1

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.
tSrc1
입력 인수를 지정하는 소스 레지스터.

주의

이 명령은 스칼라의 결과를 생성하지만, 그것이 지정된 모든 출력 채널에 복제한다.

dp3 r, s1, s2    ; s1 와 s2 의 내적, 모든 채널에 복제

dp3 명령은 기본적으로 벡터 연산이기 (위해)때문에, 항상 벡터 파이프라인으로 실행되는 것에 주의 해야 한다. 이것을알파 복제 ny입력 인수 수식자 (. a)와 함께 사용했을 경우, 이 입력 인수 수식자는 단지 결과가 알파 채널에도 전달되는 것을 나타낸다. 즉,dp3 는 칼라 처리도 실시하는 경우에게만 알파 처리로서 지정할 수 있어 같은 인수를 사용해야 한다.

dp3 r0.rgb, t0, v0
dp3 r0.a,   t0, v0

또는, 다음과 같이 해도 같다.

dp3 r0, t0, v0

이 경우,dp3 연산의 그레이 스케일의 결과가, r0 의 칼라 채널과 알파 채널의 양쪽 모두에 카피된다.

결과의 알파 채널에서는, 다른 명령을 지정할 수 있다.

dp3 r0.rgb, t0, v0
mul r0.a,   t0, v0

dp3 명령은, 입력 인수가 부호 첨부 동적 범위에 전개되어 있지 않은 경우, 보통, 입력 인수에 적용된encode 스케일링 입력 인수 수식자 (_bx2)를 이용한다. 라이팅에 대해 사용하는 경우는, 보통, 다음의 예의 같게, 채도 명령 수식자 (_sat)를 사용해 부의 값을 흑에 제한한다.

dp3_sat r0, t0_bx2, v0_bx2    ; t0 는 범프, v0 는 라이트의 방향 벡터


lrp

제 1 소스 레지스터로 지정된 비율로, 제 2 및 제 3 소스 레지스터의 사이를 선형 보간 한다.

lrp   tDest, tSrc0, tSrc1, tSrc2

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.
tSrc1
입력 인수를 지정하는 소스 레지스터.
tSrc2
입력 인수를 지정하는 소스 레지스터.

주의

이 명령은, 다음의 공식으로 기초를 두어 선형 보간을 실시한다.

tSrc0 * tSrc1 + (1-tSrc0) * tSrc2 = tSrc2 + tSrc0 * (tSrc1 - tSrc2)

다음의 예는, 이 명령의 사용법을 나타내고 있다.

lrp d, s0, s1, s2    ; d = s0*s1 + (1-s0) *s2 = s2 + s0*(s1-s2)


mad

마지막 2 개의 소스 오퍼랜드 레지스터로 지정되고 있는 2 개의 색의 적에, 제 1 소스 레지스터를 추가한 값을 로드한다.

mad   tDest, tSrc0, tSrc1, tSrc2

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.
tSrc1
입력 인수를 지정하는 소스 레지스터.
tSrc2
입력 인수를 지정하는 소스 레지스터.

주의

이 명령은, 복수 조작의 축적을 실시한다. 최초의 2 개의 인수를 걸어 거기에 남은 입력 소스 인수를 더해, 그 결과를 레지스터에 기입한다.

이 명령은, 다음의 공식으로 기초를 두어 곱셈과 가산을 실시한다.

tSrc0 * tSrc1 + tSrc2

다음의 예는, 이 명령의 사용법을 나타내고 있다.

mad  d, s0, s1, s2;    d = s0 * s1 + s2


mov

소스 레지스터의 값을 로드한다.

mov   tDest, tSrc0

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.

주의

다음의 예는, 이 명령의 사용법을 나타내고 있다.

mov   d, s    ; s 를 d 에 카피 ( d = s )


mul

목적지 레지스터에, 소스 오퍼랜드 레지스터의 2 색의 요소 단위의 내적을 로드한다.

mul   tDest, tSrc0, tSrc1

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.
tSrc1
입력 인수를 지정하는 소스 레지스터.

주의

이 명령은, 곱셈 처리를 실시하는 것이다.

다음의 예는, 이 명령의 사용법을 나타내고 있다.

mul  d, s1, s2    ; 곱셈 d = s1*s2


sub

소스 오퍼랜드의 2 개의 색의 차이를 로드한다.

sub   tDest, tSrc0, tSrc1

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.
tSrc1
입력 인수를 지정하는 소스 레지스터.

주의

이 명령은, 다음의 공식으로 기초를 두어 감산을 실시한다.

tDest = tSrc0 - tSrc1

다음의 예는, 이 명령의 사용법을 나타내고 있다.

sub   d, s1, s2    ; 차이


버젼 및 정수 정의 명령

Direct3DX 픽셀 쉐이더 어셈블러에는, 쉐이더의 타입 및 버젼을 식별하거나 픽셀 쉐이더로 사용하는 정수를 정의하기 위한 명령이 준비되어 있다.

def | 정수를 정의한다
ps | 버젼 및 타입

버젼 명령은, 각 쉐이더의 선두에 있을 필요가 있다.

정수 정의 명령은, 버젼 명령의 실행 후, 다른 모든 명령보다 전에 실행해야 하는 것에 주의 해야 한다.


def

픽셀 쉐이더로 사용하는 정수를 정의하기 위한 메소드를 제공한다.

def   vDest, fVal0, fVal1, fVal2, fVal3

레지스터

vDest
처리의 결과를 보관 유지하는 목적지 레지스터.
fVal0
입력 인수를 지정하는 소스 레지스터.
fVal1
입력 인수를 지정하는 소스 레지스터.
fVal2
입력 인수를 지정하는 소스 레지스터.
fVal3
입력 인수를 지정하는 소스 레지스터.

주의

다음의 예는,def 명령의 사용법을 나타내고 있다. def 명령은, 다른 쉐이더의 명령보다 전에 둘 필요가 있다.

Ps. 1.0
def c0, 0.0f, 0.0f, 0.0f, 1.0f
def c7, 1.0f, 2.0f, 3.0f, 4.0f
tex t0
mov r0, t0

이러한 정수는 명령 스트림으로 정의된다.


ps

쉐이더 코드의 타입 및 버젼을 지정하기 위한 메소드를 제공한다.

ps. mainVer. subVer

레지스터

mainVer
픽셀 쉐이더의 메인 버젼 번호.
subVer
픽셀 쉐이더의 서브 버젼 번호.

주의

다음의 예는,ps 명령의 사용법을 나타내고 있다.

ps. 1.0  ; 픽셀 쉐이더 버젼 1.0.

이 명령은, 모든 픽셀 쉐이더의 선두에 있을 필요가 있다.


텍스쳐 애드레싱 명령

여기에서는, Direct3DX 픽셀 쉐이더 어셈블러가 이행 하는 텍스쳐 애드레싱 명령에 대한 레퍼런스 정보를 기술한다. 텍스쳐 애드레싱 명령은, (텍스쳐 칼라 좌표에 대립하는 것으로서) 텍스쳐 주소 데이터를 조작할 수 있도록(듯이) 하기 위해서 준비되어 있다.

샘플링 스테이지의 텍스쳐 세트는, Microsoft® Direct3D® 어플리케이션 프로그래밍 인터페이스 (API)의 텍스쳐 스테이지 스테이트에 의해 선택되는 샘플링, 필터 링, 및 랩핑 모드를 사용해, 대응하는 텍스쳐로부터 샘플링 된다. 텍스쳐를 샘플링 할 경우에, 텍스쳐의 샘플링에 사용하는 주소에 적용할 수 있는 처리도 있다. 이러한 처리는, 텍스쳐 애드레싱 처리로 불린다.

다음의 표는, 텍스쳐 애드레싱 명령 및 텍스쳐 보정 처리의 서브 세트를 나타내고 있다.

명령 | 설명
tex | 변경 없음
texbem | 범프 환경 맵
texbeml | 휘도 첨부 범프 환경 맵
texcoord | 텍스쳐 좌표
texkill | 픽셀의 마스크 아웃
texm3x2pad | 3 × 2 행렬 곱셈에의 입력
texm3x2tex | 3 × 2 행렬 곱셈의 결과
texreg2ar | 알파 성분 및 빨강 성분의 재매핑
texreg2gb | 초록 성분 및 파랑 성분의 재매핑

게다가 픽셀 쉐이더 API 는, 텍스쳐로부터 샘플링 된 벡터에 대한 픽셀 단위의 3 × 3 행렬 곱셈을 실행하는 많은 메소드를 지원 한다. 3 × 3 행렬은, 3 개(살)이 연속하는 텍스쳐 선언 스테이지의 텍스쳐 좌표로 구성되어 있다. 이러한 행렬 곱셈 연산은, 복수의 텍스쳐 주소 처리로부터 구축된다.

다음의 표는, 픽셀 단위의 3 × 3 행렬 곱셈에 관련하는, 나머지의 텍스쳐 애드레싱 명령을 나타내고 있다.

명령 | 설명
texm3x3pad | 3 × 3 행렬 곱셈에의 입력
texm3x3spec | 스펙큐러 반사와 환경 매핑
texm3x3tex | 3 × 3 행렬 곱셈의 결과
texm3x3vspec | 고정 시점 벡터를 포함하지 않는 스펙큐러 반사/환경 매핑

텍스쳐 주소 명령은, 선언/정의한 텍스쳐 주소가 되는 출력 인수 (결과)를 정의한다. 일부의 명령에서는, 입력 오퍼랜드를 지정할 필요가 있다. 이 입력 오퍼랜드는, 정의 끝난 텍스쳐가 아니면 안된다. 이것들은, 텍스쳐 샘플링 유니트에 의해, 칼라 처리/알파 처리/블렌딩 쉐이더에 방출되는 텍스쳐 칼라의 선언이라고 생각된다. 이러한 텍스쳐 레지스터는, 정의 끝난 텍스쳐로 선언할 수 있지만, 후의 텍스쳐, 또는 그 외의 픽셀 칼라 레지스터로서는 선언할 수 없다.

모든 텍스쳐 주소 처리는, 텍스쳐를 정의한 순서로 선언해야 한다. 텍스쳐 주소 처리에서는, 그것보다 후에 있는 다른 텍스쳐 (즉, 스테이지 번호가 보다 큰 텍스쳐)를 참조할것은 할 수 없다.

퍼포먼스에 관한 주의 텍스쳐 애드레싱 처리에서는, 텍스쳐 주소를 나타내는데 충분한 정밀도를 지원 하고 있을 필요가 있다. 예를 들어, 디바이스로 지원 되고 있는 최대 텍스쳐 넓이의 환경 맵으로, 텍셀의 일부에 대해서 보정할 수 있는 범프 환경 매핑 행렬의 요소로 보정을 표현하는데 충분한 정밀도가 아니면 안된다. 또, 이러한 처리로 보간 되는 모든 양은, 퍼스펙티브 보정을 사용해 보간 해야 한다.


tex

텍스쳐로부터 색을 샘플링 해, 샘플링에 사용한 주소는 변경하지 않고 대응하는 레지스터에 카피한다.

tex   tDest

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.

주의

이 명령이 디폴트이므로, 다른 명령에 의해 샘플링이 지정되어 있지 않은 모든 텍스쳐에 대해서는,tex 명령의 적용이 상정된다.

다음의 예는, 이 명령의 사용법을 나타내고 있다.

tex r0    ; 스테이지 0 으로 세트 되고 있는 텍스쳐로부터
          ; 레지스터 0 을 선언

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texbem

입력 인수로 정의되고 있는 색을, DuDv 섭동 데이터로서 사용한다.

texbem   tDest, tSrc0

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 텐포라리소스레지스타.

주의

texbem 명령은, u 성분과 v 성분을 2D 범프 환경 매핑 행렬로 트랜스 폼 해, 그것을 현재의 스테이지의 텍스쳐 좌표에 추가해, 현재의 스테이지의 텍스쳐를 샘플링 한다.

tex    t0        ; 텍스쳐로부터 샘플 하도록(듯이) t0 를 정의
texbem t1, t0    ; u = u1 + mat00*r0.r + mat01*r0.g, 라고
                 ; v = v1 + mat10*r0.r + mat11*r0.g 를 계산
                 ; 다음에 u, v 로 샘플, r0.b 는 무시된다
mov r0, t1       ; 최종 결과를 출력색에 카피

이 처리는 항상 du 및 dv 를 부호 첨부의 수치로서 해석하므로, 입력 인수에 대해encode 스케일링 입력 수식자 (_bx2) 를 입력 인수로서 지정할 필요는 없다. 텍스쳐는 2 번째의 스테이지에서 설정되어 최초의 스테이지에서 설정된 텍스쳐는 무시된다.

이 명령은, 픽셀 단위의 환경 매핑이나 디퓨즈 라이트 (범프 맵핑), 환경 맛팅 등, 주소 보정에 근거하는 다양한 기법으로 사용할 수 있다.

이 처리는 2 개의 명령의 매크로이다 (2 스테이지/슬롯을 소비한다). u' = u + du*M00 + dv*M01 및 v' = v + du*M10 + dv*M11 로, M00, M01, M10, 및 M11 는 D3DTSS_BUMPENVMAT00, D3DTSS_BUMPENVMAT01, D3DTSS_BUMPENVMAT10, 및 D3DTSS_BUMPENVMAT11 이다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texbeml

전의 스테이지에서 샘플링 된 색을, 휘도 정보 첨부의 DuDvL 섭동 데이터로서 사용한다.

texbeml   tDest, tSrc0

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 텐포라리소스레지스타.

주의

texbeml 명령은, 색의 빨강 성분과 초록 성분을 2D 범프 환경 매핑 행렬로 트랜스 폼 해, 그 성분을 현재의 스테이지의 텍스쳐 좌표에 추가해, 생성 된 2D 주소로 이 텍스쳐를 샘플링 한다. 다음에, 휘도 (L) 및 Microsoft® Direct3D® API 지정의 휘도와 바이어스 텍스쳐 스테이지의 값을 사용해, 휘도 수정을 적용한다.

다음의 픽셀 쉐이더에서는, 목적지 레지스터로 설정되는 색은, 스테이지 1 으로 설정된 텍스쳐 맵으로부터 취득되어, 빨강 채널과 초록 채널의 값으로 보정된 주소에 의해 인덱스 붙이고 되어, 스테이지 0 으로 설정된 맵으로부터 샘플링 된 색으로서 정의된다.

tex     t0        ; 3 요소 DuDvL 를 취득하기 위해(때문에) t0 를 정의
texbeml t1, t0    ; u = u1 + mat00*r0.r + mat01*r0.g 와
                  ;  v = v1 + mat10*r0.r + mat11*r0.g 를 계산
                  ; 다음에 u, v 로 샘플, r0.b 는 무시된다
                  ; 다음에 휘도 수정을 적용
mov r0, t1        ; 최종 결과를 출력색에 카피

텍스쳐는 2 번째의 스테이지에서 설정되어 최초의 스테이지에서 설정된 텍스쳐는 무시된다.

이 처리는 2 개의 명령의 매크로이다 (2 스테이지/슬롯을 소비한다). u' = u + du*M00 + dv*M01 및 v' = v + du*M10 + dv*M11 로, M00, M01, M10, 및 M11 는 D3DTSS_BUMPENVMAT00, D3DTSS_BUMPENVMAT01, D3DTSS_BUMPENVMAT10, 및 D3DTSS_BUMPENVMAT11 이다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texcoord

이 스테이지에 대해서 할당할 수 있었던 보간 된 텍스쳐의 좌표를, 블렌딩으로 사용하는 색으로 변환한다.

texcoord   tDest

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.

주의

이 명령을 사용하면(자), 텍스쳐 좌표를 추가 굿 로 보간 (보증된 퍼스펙티브 보정) 색으로서 사용할 수 있다.

texcoord  t0    ; 텍스쳐 좌표로부터 칼라로서 t0 를 선언

버텍스 쉐이더는 임의의 양을 텍스쳐 좌표에 매핑 할 수 있으므로,texcoord 명령을 사용하면(자), 위치, 법선, 광원 방향등의 임의의 데이터를 픽셀 쉐이더에 스트림 할 수 있다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texkill

임의의 텍스쳐 좌표가 0 보다 작은 경우, 픽셀을 마스크 아웃 한다.

texkill   tDest

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.

이 명령을 사용해, 래스터라이저로 임의의 클립면을 이행 할 수 있다.

버텍스 쉐이더를 사용하는 경우, 어플리케이션은 퍼스펙티브 트랜스 폼을 적용할 필요가 있다. 부등형의 스케일링 계수가 포함되어 있는 경우, 클립면도 트랜스 폼 할 필요가 있으므로, 임의의 클립면에서는 문제가 발생하는 일이 있다. 따라서, 임의 클립면에서 사용하려면 ,texkill 연산자로 식별되는 텍스쳐 좌표 세트인 비투영 버텍스 위치를 제공하는 것이 최적이다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texm3x2pad

2 × 3 행렬 곱셈을 실행하기 위해서, 다른 텍스쳐 주소 처리와 조합해 사용된다.

texm3x2pad   tDest, tSrc0

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 텐포라리소스레지스타.

주의

이 명령은, 텍스쳐 좌표만이 사용되는 스테이지를 나타내기 위해서(때문에) 사용된다. 이러한 대응하는 스테이지에는 텍스쳐는 바인드되어 있지 않기 때문에, 샘플링은 행해지지 않는다. 입력 인수 t0 는 지정할 필요가 있다.

다음의 예는,texm3x2pad 명령의 사용법을 나타내고 있다.

tex t0             ; 표준적인 3 벡터로서 t0 를 정의
texm3x2pad t1, t0  ; 행렬의 제 1 행의 곱셈을 실행
texm3x2tex t2, t0  ; 행렬의 제 2 행의 곱셈을 실행해,
                   ; 텍스쳐 2 로서 샘플 하는 2 벡터를 취득

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texm3x2tex

입력색벡터에 대해서 3 × 2 행렬 곱셈을 실행한다.

texm3x2tex   tDest, tSrc0

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 텐포라리소스레지스타.

주의

texm3x2tex 명령은, 지정된 입력색을 취득해, 입력색과 그 스테이지의 텍스쳐 좌표 (u, v, 및 w)의 내적을 계산해, u 좌표를 생성한다. 다음에, 같은 입력색을 취득해, 입력색과 이 스테이지의 텍스쳐 좌표의 내적을 계산해, v 좌표를 얻는다. 마지막으로, 이 스테이지의 텍스쳐를 (u, v)로 샘플링 해, 최종적인 색을 생성한다. 전의 스테이지에서는 텍스쳐는 샘플링 되지 않고, 또 전의 스테이지에서 텍스쳐를 설정할 필요는 없고, 텍스쳐에 할당모든 연산자는 이 연산에 의해 무효가 된다.

다음의 예는,texm3x2tex 명령의 사용법을 나타내고 있다.

tex t0             ; 표준적인 3 벡터로서 t0 를 정의
texm3x2pad t1, t0  ; 행렬의 제 1 행의 곱셈을 실행
texm3x2tex t2, t0  ; 행렬의 제 2 행의 곱셈을 실행해,
                   ; 텍스쳐 2 로서 샘플 하는 2 벡터를 취득
mov r0, t2

범프 (보통의) 맵은 스테이지 0 으로 설정해, 표준의 2D 텍스쳐는 스테이지 2 로 설정할 필요가 있다. 스테이지 1 으로 설정되는 텍스쳐는, 모두 무시된다. 예를 들어, 다음의 쉐이더에서는, 베이스 텍스쳐는 디퓨즈 범프 맵을 곱셈해, 지수 스펙큐러를 추가하는 것에 의해 라이팅 되고 있다. 스테이지 0 에서는 베이스 텍스쳐를 설정해, 스테이지 1 에서는 법선 맵을 설정해, 스테이지 2 에서는 한번 더 법선 맵을 설정해 있다.

ps. 1.0                 ; DirectX8 버젼
tex t0                 ; 샘플 법선 맵
texm3x2pad t1, t0_bx2  ; 라이트 벡터에 의한 내적
texm3x2tex t2, t0_bx2  ; 반벡터와 샘플에 의한 내적
mov r0, t2

설정 0 의 텍스쳐 좌표는 범프 맵에 위치한다. 텍스쳐 좌표 세트 1 및 2 는, 행렬의 행이다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texm3x3pad

텍스쳐가 바인드되어 있지 않은 3 × 3 행렬 곱셈의 행으로 사용되는 처리를 나타낸다.

texm3x3pad   tDest, tSrc0

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 텐포라리소스레지스타.

주의

이 명령은, 픽셀 쉐이더의 텍스쳐 선언 스테이지에서 실행되는 3 × 3 행렬 곱셈 처리의 일부이다. 선언이 끝난 텍스쳐에 대응하는 텍스쳐 좌표는 행렬의 행으로서 사용된다. 이 스테이지에서는, 어느 텍스쳐도 바인드 해서는 안된다.

이 선언에 대한 입력 인수인 t0 는, 이하의 픽셀 쉐이더의 예에 나타내도록(듯이), 행렬의 곱셈에 대한 입력 인수인 tSrc0 로 지정하지 않으면 안 된다.

tex t0             ; 표준적인 3 벡터로서 t0 를 정의
texm3x3pad t1, t0  ; 행렬의 제 1 행의 곱셈을 실행
texm3x3pad t2, t1  ; 행렬의 제 2 행의 곱셈을 실행
texm3x3tex t3, t2  ; 행렬의 제 3 행의 곱셈을 실행해,
                   ; 텍스쳐 2 로서 샘플 하는 3 벡터를 취득
mov r0, t3

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texm3x3spec

스펙큐러 반사와 환경 매핑을 실행한다.

texm3x3spec   tDest, tSrc0, tSrc1

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.
tSrc1
입력 인수를 지정하는 소스 레지스터.

주의

이 처리는, 결과적으로 생성되는 트랜스 폼 후 벡터를 취득해, 시선 벡터를 반영하기 위한 법선으로서 사용한다. 시선 벡터는, 항상 정수 칼라 c0 이다. 그 후, 명령은, 처리의 결과를, 그 스테이지에서 설정되어 있는 큐브 텍스쳐를 참조하기 위한 주소로서 사용한다. 스펙큐러 환경 맵은 프리로드 되고 있다.

tex t0                  ; 표준적인 3 벡터로서 t0 를 정의
texm3x3pad t1, t0       ; 행렬의 제 1 행의 곱셈을 실행
texm3x3pad t2, t0       ; 행렬의 제 2 행의 곱셈을 실행
texm3x3spec t3, t0, c0  ; 행렬의 제 3 행의 곱셈을 실행해,
                        ; 반사 계산을 실시해, 텍스쳐 3 을 샘플 한다
mov r0, t3              ; 최종 결과를 출력색으로서 카피

범프 (보통의) 맵은 스테이지 0 으로 설정될 필요가 있어, 큐브 텍스쳐는 스테이지 3 으로 설정될 필요가 있다. 스테이지 1 또는 2 로 설정되는 텍스쳐는 모두 무시된다.

설정 0 의 텍스쳐 좌표는 범프 맵에 위치한다. 1, 2, 및 3 을 설정하는 텍스쳐 좌표는 3 × 3 행렬의 행이다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.

참조

texm3x3vspec


texm3x3tex

마지막 3 × 3 행렬 곱셈의 결과를 돌려준다.

texm3x3tex   tDest, tSrc0
tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 텐포라리소스레지스타.

주의

texm3x3tex 명령은, 픽셀 쉐이더의 텍스쳐 선언에 대해 실행되는 3 × 3 행렬 곱셈 처리를 나타내는 3 개의 명령의 마지막 것으로 해 사용된다. 이 명령의 결과에는, 명령을 실행한 결과 생기는 트랜스 폼 된 벡터가 포함된다. 이 선언에 대한 입력 인수에는, 행렬의 곱셈에 대한 입력을 지정해야 한다. 이 스테이지에 할당할 수 있었던 텍스쳐 좌표는, 행렬의 행으로서 사용된다.

3 × 3 행렬은, 이 스테이지 및 전의 2 개의 스테이지의 텍스쳐 좌표로 구성되어 있다. 결과적으로 얻을 수 있는 3 요소 벡터를 사용해, 이 스테이지에서 할당할 수 있고 있는 텍스쳐 (큐브 텍스쳐 또는 볼륨 텍스쳐)에 인덱스를 설정해, 최종적인 색을 생성한다. 전의 2 개의 스테이지로부터는 텍스쳐 칼라는 샘플링 되지 않고, 이러한 스테이지에 할당할 수 있고 있던 연산자는 모두 무효가 된다.

tex t0             ; 표준적인 3 벡터로서 t0 를 정의
texm3x3pad t1, t0  ; 행렬의 제 1 행의 곱셈을 실행
texm3x3pad t2, t0  ; 행렬의 제 2 행의 곱셈을 실행
texm3x3tex t3, t0  ; 행렬의 제 3 행의 곱셈을 실행

dp3 r0, t0, v0     ; v0 를 사용해 디퓨즈 라이팅 강도를 계산

범프 (보통의) 맵은 스테이지 0 으로 설정될 필요가 있어, 큐브 텍스쳐는 스테이지 3 으로 설정될 필요가 있다. 스테이지 1 또는 2 로 설정되는 텍스쳐는 모두 무시된다.

설정 0 의 텍스쳐 좌표는 범프 맵에 위치한다. 1, 2, 및 3 을 설정하는 텍스쳐 좌표는 3 × 3 행렬의 행이다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texm3x3vspec

시점 벡터가 고정하고 있지 않을 때의 스펙큐러 반사 및 환경 매핑을 실시한다.

texm3x3vspec   tDest, tSrc0

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 소스 레지스터.

주의

이 명령은 텍스쳐 애드레싱에 사용한다. 행렬의 행으로서 사용되는 3 개의 텍스쳐 좌표의 w 요소로부터 시선이 취득되는 점을 제외해, 이 명령의 동작은 texm3x3spec 와 완전히 같다.

tex t0               ; 표준적인 3 벡터로서 t0 를 정의
texm3x3pad t1, t0    ; 행렬의 제 1 행의 곱셈을 실행
texm3x3pad t2, t0    ; 행렬의 제 2 행의 곱셈을 실행
texm3x3vspec t3, t0  ; 행렬의 제 3 행의 곱셈을 실행해,
                     ; 텍스쳐 2 를 샘플 해, 반사 계산을 실시해,
                     ; 텍스쳐 3 을 스펙큐러 맵으로서 샘플
mov r0.rgb, t3       ; 스펙큐러색을 결과에 넣는다
mov r0.a,   t3       ; 디 푸즈색을 알파 채널에 넣는다

범프 (보통의) 맵은 스테이지 0 으로 설정될 필요가 있어, 큐브 텍스쳐는 스테이지 3 으로 설정될 필요가 있다. 스테이지 1 또는 2 로 설정되는 텍스쳐는 모두 무시된다.

설정 0 의 텍스쳐 좌표는 범프 맵에 위치한다. 1, 2, 및 3 을 설정하는 텍스쳐 좌표는 3 × 3 행렬의 행이다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.

참조

texm3x3spec


texreg2ar

지정된 입력색벡터의 알파 성분과 빨강 성분으로 지정되는 2D 좌표로, 이 스테이지의 텍스쳐를 샘플링 한다.

texreg2ar tDest, tSrc0

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 텐포라리소스레지스타.

주의

이 명령은, 색공간(color space)의 재매핑 처리로 편리하다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


texreg2gb

지정된 입력색벡터의 초록 성분과 파랑 성분으로 지정되는 2D 좌표로, 이 스테이지의 텍스쳐를 샘플링 한다.

texreg2gb tDest, tSrc0

레지스터

tDest
처리의 결과를 보관 유지하는 목적지 레지스터.
tSrc0
입력 인수를 지정하는 텐포라리소스레지스타.

주의

이 명령은, 색공간(color space)의 재매핑 처리로 편리하다.

이 명령은, 이 텍스쳐 스테이지에 대응하는 할당 끝난 텍스쳐인 무명의 입력을 취하는 것에 주의 해야 한다.


수식자

Direct3DX 픽셀 쉐이더 어셈블러에서는, 다음의 타입의 수식자가 지원 되고 있다.

  • 인수 수식자
  • 명령 수식자


인수 수식자

Direct3DX 픽셀 쉐이더 어셈블러는, 명령 인수 (오퍼랜드) 및 명령으로 처리되기 전의 입력 인수에 영향을 주는 수정자 플래그를 취할 수가 있다. 입력 인수 수식자에는 2 개의 타입이 있다. 색 및 알파 블렌딩 입력 인수 수식자와 텍스쳐 애드레싱 입력 인수 수식자이다.

입력 인수 수식자는, 다음 표로 정의되고 있다. rn. (은)는 입력 인수 (레지스터)이다.

명령 | 구문 | 설명
알파 복제 | rn. a | 알파 채널을 모든 색에 복제한다.
보수 | 1-rn | 보수를 계산한다 (y = 1.0 - x). 부호 없음 x 가 필요.
정부의 반전 | -rn | 값의 정부를 반전한다 (y = -x). 부호 첨부 x 가 필요.
바이어스 | rn_bias | 값을 스하에 쉬프트 한다. y = (x-0. 5).
encode 스케일링 | rn_bx2 | 값을 아래에 쉬프트 해, 데이터를 2 배에 스케일링 한다. y = 2*(x-0. 5).

예를 들어,lrp 명령은, 입력 인수 수식자를 사용해 이행 할 수 있다.

; 디퓨즈 알파를 사용해, r0 와 t0 브렌드 하면,
lrp r0, v0.a, r0, t0
; (보다 많은 클락을 사용해) 다음과 같이 기입할 수가 있다.
sub r0, r0, t0
mad r0, t0, v0.a, r0

버텍스 쉐이더와는 달라, 픽셀 쉐이더는 성분의 교체를 지원 하고 있지 않다. x, y, 및 z 의 각 요소는 정리해 RGB 색성분으로서 다루어져, w 요소는 개별적으로 전송 할 수 있는 알파로서 다루어진다.


알파 복제

rn. a

명령을 처리하기 전에, 영향을 받는 레지스터의 알파 채널을, 모든 칼라 채널에 복제한다.

다음의 예는, 이 수식자의 사용법을 나타내고 있다.

mul r0, r0, r1.a    ; 알파 채널로 곱셈 (그레이 스케일)
                    ; 색의 강도만을 변화

이 연산자는보수 또는정부의 반전 연산자와 조합해 사용할 수 있는 것에 주의 해야 한다. 이 연산자의 기능은, Microsoft® DirectX® 6.0 및 7.0 멀티 텍스쳐 구문의 D3DTA_ALPHAREPLICATE 플래그를 닮아 있다.

이 수식자는, 색 및 알파 블렌딩 명령으로 사용하기 위한의 것이다.


보수

1-rn

지정된 레지스터의 각 채널로 색의 보수를 계산한다.

다음의 예는, 이 수식자의 사용법을 나타내고 있다.

mul r0, r0, 1-r1    ; (1.0 - r1)로 곱셈한다.

입력 데이터가 부호 없음의 경우, 즉 0 에서 1 의 범위에 있는 경우, 이 수식자는 미리 정의되고 있는 결과만 생성한다. 이 처리는, 같은 인수에 그 외 모든 수식자가 제시된 다음에 실행된다.

이 애통자는, 부호 없음 데이터에 대한 보고 기능하는 것에 주의 해야 한다. 이 명령에는,바이어스,encode 스케일링, 및정부의 반전 수식자와의 정합성이 없기 때문에, 같은 레지스터로 이러한 수식자와 동시에 사용할 수 없다.

이 수식자는, 색 및 알파 블렌딩 명령으로 사용하기 위한의 것이다.


정부의 반전

rn

부호의 반전 (y = -x)을 실행한다. 즉, 명령으로 값을 사용하기 전에 정부를 반전한다.

다음의 예는, 이 수식자의 사용법을 나타내고 있다.

mul r0, r0, -v1    ; 마이너스의 스펙큐러색으로 곱셈한다.

이 처리는, 같은 인수에 대하는 것 외의 수식자의 뒤에 실행된다.

보수 (1-rn)와정부의 반전 (-rn)은 서로 배타적이고, 같은 레지스터에 적용할 수 없다.

이 수식자는, 색 및 알파 블렌딩 명령으로 사용하기 위한의 것이다.


바이어스

rn_bias

각 채널을 1/2 아래에 쉬프트 한다. 따라서, 레지스터를 처리하기 전에, y = (x-0. 5)를 실행한다.

다음의 예는, 이 수식자의 사용법을 나타내고 있다.

add r0, r0, t0_bias    ; 0.5 쉬프트 다운

이 예에서는,add 를 사용해, Microsoft® DirectX® 6.0 및 7.0 의 멀티 텍스쳐 구문의 D3DTOP_ADDSIGNED 와 같은 처리를 실행하는 방법을 나타내고 있다.

이 수식자는, 0 ~ 1 의 범위에 있는 데이터를 -0. 5 ~ 0.5 의 범위가 되도록(듯이) 변경하는 것으로 같은 효과가 있다. 이것은, 일반적으로 상세한 텍스쳐를 적용하기 위해서 사용된다. 또, 입력 데이터를 부호 첨부의 수치로서 처리해, 범위가 -1 ~1 에 제한되고 있는 이행 환경에서 오버플로우 클램프가 발생하기 전에, 동적 범위를 보관 유지할 수도 있다.

이 수식자는보수와 서로 배타적이기 때문에, 같은 레지스터에 적용할 수 없다.

이 수식자는, 색 및 알파 블렌딩 명령으로 사용하기 위한의 것이다.


encode 스케일링

rn_bx2

색 및 알파 블렌딩 명령과 함께 사용하는 경우, 이 수식자는, 명령이 실행되기 전에, 각 채널로부터 0.3 을 감산해, 그 결과를 2.0 배에 스케일링 한다. 즉, y = (x-0. 5)*2 를 실행한다.

다음의 예는, 이 수식자의 사용법을 나타내고 있다.

dp3_sat r0, t1_bx2, v0_bx2    ; 디퓨즈색 v0 에 라이트 방향,
                              ; TL 에 범프 법선을 가정한, 파 픽셀
                              ; 라이팅 / 범프 맵핑

이 수식자는, 0 에서 1 까지의 범위에 있는 데이터를 재매핑 해,-1 로부터 1 까지의 범위에 있는 부호 첨부 데이터로 한다. 이것에 의해, 이후의 데이터 처리에서는 이행의 완전한 부호 첨부 동적 범위를 사용할 수 있다.

이 수식자는, 일반적으로, 내적 명령 (dp3 )에의 입력에 대해 사용된다.

이 수식자는보수와 서로 배타적이기 때문에, 같은 레지스터에 적용할 수 없다.

텍스쳐 레지스터 선언에 대한 입력 인수에서는 _bx2 수식자를 지원 하고 있어,dp3 ,texm3x2tex , 및 texm3x3tex 처리의 선언/명령의 실행중에 실시하는 추가의 처리를 지정할 수 있다. 그 외의 텍스쳐 애드레싱 연산자는,_bx2 입력 인수 수식자를 지원 하고 있지 않다.

입력 레지스터 인수를 사용하기 전에 바이어스 및 스케일링의 처리가 필요가 있는 것을 지정하려면 , 입력 레지스터 인수에 _bx2 를 추가한다.

tex t0            ; 텍스쳐 칼라를 읽어들인다.
dp3 t1, t0_bx2    ; 이 스테이지의 텍스쳐 좌표로 내적을 계산한다.

이것은, 입력 레지스터가 지정된 연산자로 사용하기 전에, 입력 레지스터에 대해서 연산 y = 2(x - 0.5)를 실행한다. 이 연산은 일반적으로,-1 ~ 1 의 범위에 있는 부호 첨부의 값을 포함하도록(듯이) 의도되고 있는 데이터를 평행이동 하기 위해서 사용되지만, 소스가 이 연산을 지원 할 수 없기 때문에, 실행하지 않는다. 이러한 데이터 소스에는, 텍스쳐 (tn ), 보간색 (vn ), 텍스쳐 좌표, 또는 고정 요소 레지스터 (cn )가 있다.

이 수식자는, 색 및 알파 블렌딩 명령과 텍스쳐 애드레싱 명령의 양쪽 모두로 사용하기 위한의 것이다.


명령 수식자

Direct3DX 픽셀 쉐이더 어셈블러는, 쉬프트/스케일링 수정자 플래그, 및 생성되는 출력 결과에 영향을 주는 채도 수정자 플래그를 지원 하고 있다. 명령 수식자는, 다음의 순서로 명령 처리와 결부된다.

  1. 보수를 실행한다.
  2. 바이어스를 적용한다.
  3. 결과에 스케일링을 적용한다.
  4. 클램프를 실행한다.

쉬프트/스케일링 수식자를 사용하면(자), 결과의 크기를 있는 범위내에서 변경할 수 있다.

이름 | 수식자
_x2 | 2 로 곱셈한 결과
_x4 | 4 로 곱셈한 결과
_d2 | 2 로 나눗셈 한 결과

게다가 색 및 알파 블렌딩 명령과 텍스쳐 애드레싱 명령의 양쪽 모두로 사용하기 위해서, 채도 수식자 (_sat)가 준비되어 있다.

색 및 알파 블렌딩 명령의 경우, 채도 수식자는, 이 명령의 결과를 각 성분에 대해 0.0 ~ 1.0 의 범위에 클램프 한다. 다음의 예는, 이 수식자의 사용법을 나타내고 있다.

dp3_sat r0, t0_bx2, v0_bx2    ; t0 는 반브, v0 는 라이트 방향

이 처리는, 스케일링 명령 수식자의 다음에 실행된다. 이것은, 보통, 내적의 결과를 클램프 하기 위해서 사용된다. 다만, frame buffer가 항상 0 ~ 1 의 범위에 있는 멀티 패스 메소드와 채도가 각 스테이지에서 행해지도록(듯이) 정의되고 있는 Microsoft® DirectX 6.0 및 7.0 의 멀티 텍스쳐 구문으로, 일관성이 있는 에뮬레이션을 실행할 수 있다.

텍스쳐 애드레싱 명령의 경우, 채도 수식자를 처리에 추가해, 종료시의 처리의 결과를 0.0 ~ 1.0 의 색의 범위에 클램프 하도록(듯이) 지정할 수 있다. 이것은, 일반적으로, 라이팅 처리로 사용할 필요가 있다. 다음의 예는, 이 수식자의 사용법을 나타내고 있다.

ps. 1.0                       ; DirectX8 버젼
tex t0                       ; 텍스쳐 칼라를 읽어들인다
dp3_sat t1, t0_bx2, v0_bx2   ; 텍스쳐 좌표와 클램프로 내적을 계산

다음의 add 명령은, 소스 오퍼랜드 (s0 와 s1)의 2 개의 색을 더한 것을 목적지 레지스터 (d)에 로드해, 결과에 2 를 곱하고 있다.

add_x2   d, s0, s1

다음의 add 명령은, 소스 오퍼랜드 (s0 와 s1)의 2 개의 색을 더한 것을 목적지 레지스터 (d)에 로드해, 결과를 각 성분에 대해 0.0 ~ 1.0 의 범위에 클램프 하고 있다.

add_sat   d, s0, s1

다음의 add 명령은, 소스 오퍼랜드 (s0 와 s1)의 2 개의 색을 더한 것을 목적지 레지스터 (d)에 로드해, 결과를 2 배가 되고 나서, 각 성분에 대해 결과를 0.0 ~ 1.0 의 범위에 클램프 하고 있다.

add_2x_sat   d, s0, s1


출력 기입 마스크

Direct3DX 픽셀 쉐이더 컴파일러로 지원 되고 있는 출력 마스크는, 이 결과가 결과의 색 또는 알파 성분의 어느쪽이든을 갱신해야 하는지 어떤지, 및 그 처리에 색 또는 알파 파이프라인을 사용할지 어떨지를 지정하기 위해서 사용된다. 이러한 출력 마스크는, Microsoft® DirectX 6.0 및 7.0 멀티 텍스쳐 블렌딩의 개별의 색 및 알파 처리를 닮아 있다.

이러한 플래그는 버텍스 쉐이더로 지원 되고 있는 플래그만큼 일반적이지 않다. 이것은, rgb 성분이 항상 1 개의 플래그에 그룹화 되기 (위해)때문에,. a 와 . rgb 의 2 종류의 마스크 밖에 존재하지 않기 때문에이다.

다음의 출력 기입 마스크가 지원 되고 있다.

  • 색/벡터 기입 마스크
  • 알파/스칼라 기입 마스크
  • 완전 기입 마스크

텍스쳐 애드레싱 명령에서는, 출력 기입 마스크는 지원되어 있지 않은 것에 주의 해야 한다. 이러한 처리는, 항상 목적지 레지스터의 4 개의 성분을 갱신하므로, r, g, b 를 분할할 수 없다.

픽셀 쉐이더는, 임의의 교체를 지원 하고 있지 않고, 색 및 알파 처리만 지원 하고 있다.


색/벡터 기입 마스크

. rgb

출력 레지스터에 대해 지정했을 경우, 이 플래그는, 처리로 목적지 레지스터의 3 개의 칼라 채널만을 갱신하는 것을 지정하므로, 명령의 색 (벡터) 파이프라인으로 실행할 필요가 있다.

다음의 예는, 이 출력 기입 마스크의 사용법을 나타내고 있다.

mul r0.rgb,  t0, v0
add r0.a,    t1, v1


알파/스칼라 기입 마스크

. a

목적지 레지스터에 대해 지정했을 경우, 이 플래그는, 처리로 목적지 레지스터의 알파 채널만을 갱신하는 것을 지정하므로, 이 명령의 알파 (스칼라) 파이프라인으로 실행할 필요가 있다.

다음의 예는, 이 출력 기입 마스크의 사용법을 나타내고 있다.

mul r0.rgb,  t0, v0
add r0.a,    t1, v1


완전 기입 마스크

. rgba

색 및 알파 채널의 양쪽 모두에 같은 명령을 적용하는 것을 요구한다. 이것은 디폴트이며, 이것과 같은 결과를 얻기 위해서(때문에) 출력 마스크를 지정할 필요는 없다.

예를 들어, 다음의 명령

mul r0, t0, v0

(은)는, 다음의 명령과 같고,

mul r0.rgba, t0, v0

다음의 명령과도 같다.

  mul r0.rgb, t0, v0
+ mul r0.a,   t0, v0

이 마지막 구문에서도, 스칼라 파이프라인과 벡터 파이프라인을 페어로 하고 있기 (위해)때문에, 1 클락 밖에 사용하지 않는다. 상세한 것에 대하여는, 「픽셀 쉐이더의 명령의 페어」를 참조할것.


이펙트 파일 형식

여기에서는, 이펙트 파일 형식에 관한 레퍼런스 정보에 대해 설명한다. 이펙트 파일은, 파라미터 선언과 다양한 방법의 기술에 의해 구성된다.

  • 파라미터의 형태
  • 정수값의 구문
  • 버텍스 쉐이더 선언의 구문
  • 유효한 스테이트의 일람
  • 이펙트 파일의 샘플

방법은, 다음의 구문에 따라 기술한다. id 는 유효한 FourCC 코드가 아니면 안되는 것에 주의한다. FourCC 코드에 대해서는, 「FOURCC 코드 .」(을)를 참조할것.

  • 각종 선언을 기술한 다음에 방법을 기술한다.
  • 방법의 기술에는 1 개 이상의 패스를 포함한다.
  • 패스에는 1 개 이상의 스테이트 지정을 포함한다.
  • 스테이트는, 정수값 또는 파라미터의 어느 쪽인가에 지정할 수 있다.
{type} {id};
{type} {id} = {const};

TECHNIQUE {id}
{
    PASS {id}
    {
        {state}      = {const};
        {state}[{n}] = {const};
        {state}      = <{id}>;
        {state}[{n}] = <{id}>;
    }
}


파라미터의 형태

파라미터 선언은, 다음의 구문에 따른다. type 는 유효한 형태,id 는 유효한 FOURCC 코드이다. const 값을 파라미터의 초기값으로서 지정하는 경우, 그 형태는type 와 일치하고 있을 필요가 있다.

{type} {id};
{type} {id} = {const};

다음의 표는, 샘플외, 이펙트 파일의 파라미터 선언으로 사용하는 유효한 파라미터의 형태를 나타내고 있다.

형 샘플
DWORD
DWORD minVertices;
FLOAT
FLOAT fRotationAdvances;
VECTOR
VECTOR vecPoint;
MATRIX
MATRIX matIndentity;
TEXTURE
TEXTURE tex1;
VERTEXSHADER
VERTEXSHADER v1;
PIXELSHADER
PIXELSHADER p1;


정수값의 구문

다음의 표는, 정수값 및 샘플의 유효한 구문을 나타내고 있다.

형 구문
DWORD
#

0x#

54573153

0xff12a1fa
FLOAT
#f

#. f
. #f
#. #f

5f

5. f
. 4f
4.5f
VECTOR
(float)

(float, float)
(float, float, float)
(float, float, float, float)

( 4.5f )

( 4.5f, 1.0f )
( 4.5f, 1.0f, 2.0f )
( 4.5f, 1.0f, 2.0f, 3.4f )
MATRIX
[ float, float, float, float,

  float, float, float, float,
  float, float, float, float,
  float, float, float, float ]

[ 1.0f, 0.0f, 0.0f, 0.0f,

  0.0f, 1.0f, 0.0f, 0.0f,
  0.0f, 0.0f, 1.0f, 0.0f,
  0.0f, 0.0f, 0.0f, 1.0f ]
VERTEXSHADER
DECL { ... }

DECL { ... }, ASM { ... }

decl

{
   stream 0;
   float v0[3];
   float v3[3];
   ubyte v5[4];
   float v7[2];
}

decl
{
   stream 0;
   float v0[3];
   float v3[3];
   ubyte v5[4];
   float v7[2];
}
asm
{
   vs. 1.0
   mov oPos, v0
}
PIXELSHADER
ASM { ... }

asm

{
   ps. 1.0
   tex t0
   mov r0, t0
}

DECL 구문의 레이아웃에 대해서는, 「버텍스 쉐이더 선언의 구문」을 참조할것.

ASM 구문의 레이아웃에 대해서는, 「픽셀 쉐이더 어셈블러 레퍼런스」를 참조할것.


버텍스 쉐이더 선언의 구문

DECL
{
    STREAM n;
    SKIP n;
    FVF a|b|c;

    type v#;
    type v#[n];
}

다음의 표는, 위에의 구문으로 사용하는 값의 형태를 나타내고 있다.

구문 | 설명
a|b|c | 복수의 DWORD 와 유연한 벡터 형식 플래그로부터 구성할 수 있는 DWORD 표현. FVF 를 사용하려면 , D3DFVF_ prefix 를 없앤다.
Type | 다음의 형태의 언젠가. UBYTE, SHORT, FLOAT, D3DCOLOR.
v# | 유효한 버텍스 쉐이더 입력 레지스터. FVF 플래그 및 대응하는 버텍스 쉐이더 입력 레지스터를 나타내는, 아래의 겉(표)를 참조할것.
n | 1 에서 4 까지의 수치.

다음의 표는, FVF 코드 및 대응하는 버텍스 쉐이더 입력 레지스터를 나타내고 있다.

FVF | 이름 | 레지스터 번호
D3DFVF_XYZ | D3DVSDE_POSITION | 0
D3DFVF_XYZRHW | D3DVSDE_BLENDWEIGHT | 1
D3DFVF_XYZB1 로부터 D3DFVF_XYZB5 | D3DVSDE_BLENDINDICES | 2
D3DFVF_NORMAL | D3DVSDE_NORMAL | 3
D3DFVF_PSIZE | D3DVSDE_PSIZE | 4
D3DFVF_DIFFUSE | D3DVSDE_DIFFUSE | 5
D3DFVF_SPECULAR | D3DVSDE_SPECULAR | 6
D3DFVF_TEX0 | D3DVSDE_TEXCOORD0 | 7
D3DFVF_TEX1 | D3DVSDE_TEXCOORD1 | 8
D3DFVF_TEX2 | D3DVSDE_TEXCOORD2 | 9
D3DFVF_TEX3 | D3DVSDE_TEXCOORD3 | 10
D3DFVF_TEX4 | D3DVSDE_TEXCOORD4 | 11
D3DFVF_TEX5 | D3DVSDE_TEXCOORD5 | 12
D3DFVF_TEX6 | D3DVSDE_TEXCOORD6 | 13
D3DFVF_TEX7 | D3DVSDE_TEXCOORD7 | 14
 | D3DVSDE_POSITION2 | 15
 | D3DVSDE_NORMAL2 | 16


유효한 스테이트의 일람

다음의 주제에서는, 이펙트 파일을 생성 할 때에 사용할 수 있는 유효한 모든 스테이트에 대해 설명한다.

형태 DWORD 의 스테이트를 설정 하면나무는, 열거값을 사용할 수 있다. 예를 들어, 보통 SrcBlend 는 D3DBLEND_xxx 열거형을 사용해 설정된다. 따라서, 이러한 열거형을 사용해 지정할 수가 있다. 다음의 코드에 나타내도록(듯이), D3DBLEND_ prefix 를 없앨 뿐이다.

SrcBlend = One;

이러한 값은,"OR" 식에서 정리해 지정할 수도 있다.

TextureTransformFlags[0] = Count3 | Projected;

다음의 표는, 이펙트 파일로 사용하는 유효한 렌더링 스테이트를 나타내고 있다.

형 | 렌더링 스테이트 | 유효한 값
DWORD | ZEnable | D3DZB
DWORD | FillMode | D3DFILL
DWORD | ShadeMode | D3DSHADE
DWORD | LinePattern |
DWORD | ZWriteEnable | TRUE/FALSE
DWORD | AlphaTestEnable | TRUE/FALSE
DWORD | LastPixel | TRUE/FALSE
DWORD | SrcBlend | D3DBLEND
DWORD | DestBlend | D3DBLEND
DWORD | CullMode | D3DCULL
DWORD | ZFunc | D3DCMP
DWORD | AlphaRef |
DWORD | AlphaFunc | D3DCMP
DWORD | DitherEnable | TRUE/FALSE
DWORD | AlphaBlendEnable | TRUE/FALSE
DWORD | FogEnable | TRUE/FALSE
DWORD | SpecularEnable | TRUE/FALSE
DWORD | ZVisible | TRUE/FALSE
DWORD | FogColor |
DWORD | FogTableMode | D3DFOG
FLOAT | FogStart |
FLOAT | FogEnd
FLOAT | FogDensity
DWORD | EdgeAntialias | TRUE/FALSE
DWORD | Zbias |
DWORD | RangeFogEnable
DWORD | StencilEnable | TRUE/FALSE
DWORD | StencilFail | D3DSTENCILOP
DWORD | StencilZFail | D3DSTENCILOP
DWORD | StencilPass | D3DSTENCILOP
DWORD | StencilFunc | D3DCMP
DWORD | StencilRef |
DWORD | StencilMask
DWORD | StencilWriteMask
DWORD | TextureFactor
DWORD | Wrap0 | D3DWRAP
DWORD | Wrap1 | D3DWRAP
DWORD | Wrap2 | D3DWRAP
DWORD | Wrap3 | D3DWRAP
DWORD | Wrap4 | D3DWRAP
DWORD | Wrap5 | D3DWRAP
DWORD | Wrap6 | D3DWRAP
DWORD | Wrap7 | D3DWRAP
DWORD | Clipping | TRUE/FALSE
DWORD | Lighting | TRUE/FALSE
DWORD | Ambient |
DWORD | FogVertexMode
DWORD | ColorVertex | TRUE/FALSE
DWORD | LocalViewer | TRUE/FALSE
DWORD | NormalizeNormals | TRUE/FALSE
DWORD | DiffuseMaterialSource | D3DMCS
DWORD | SpecularMaterialSource | D3DMCS
DWORD | AmbientMaterialSource | D3DMCS
DWORD | EmissiveMaterialSource | D3DMCS
DWORD | VertexBlend | D3DVBF
DWORD | ClipPlaneEnable | TRUE/FALSE
DWORD | SoftwareVertexProcessing | TRUE/FALSE
FLOAT | PointSize |
FLOAT | PointSize_Min
FLOAT | PointSize_Max
DWORD | PointSpriteEnable | TRUE/FALSE
DWORD | PointScaleEnable | TRUE/FALSE
FLOAT | PointScale_A |
FLOAT | PointScale_B
FLOAT | PointScale_C
DWORD | MultiSampleAntialias | TRUE/FALSE
DWORD | MultiSampleMask |
DWORD | PatchSegments
DWORD | IndexedVertexBlendEnable | TRUE/FALSE
DWORD | ColorWriteEnable | TRUE/FALSE
FLOAT | TweenFactor |
DWORD | BlendOp | D3DBLENDOP

다음의 표는, 이펙트 파일로 사용하는 유효한 텍스쳐 스테이지 스테이트를 나타내고 있다.

형 | 텍스쳐 스테이지 스테이트 | 유효한 값
DWORD | ColorOp[8] | D3DTOP
DWORD | ColorArg0[8] | D3DTA
DWORD | ColorArg1[8] | D3DTA
DWORD | ColorArg2[8] | D3DTA
DWORD | AlphaOp[8] | D3DTOP
DWORD | AlphaArg0[8] | D3DTA
DWORD | AlphaArg1[8] | D3DTA
DWORD | AlphaArg2[8] | D3DTA
DWORD | ResultArg[8] | D3DTA
DWORD | BumpEnvMat00[8] |
DWORD | BumpEnvMat01[8]
DWORD | BumpEnvMat10[8]
DWORD | BumpEnvMat11[8]
DWORD | TexCoordIndex[8] | D3DTSS_TCI
DWORD | AddressU[8] | D3DTADDRESS
DWORD | AddressV[8] | D3DTADDRESS
DWORD | AddressW[8] | D3DTADDRESS
DWORD | BorderColor[8] |
DWORD | MagFilter[8] | D3DTEXF
DWORD | MinFilter[8] | D3DTEXF
DWORD | MipFilter[8] | D3DTEXF
DWORD | MipMapLodBias[8] |
DWORD | MaxMipLevel[8]
DWORD | MaxAnsiotropy[8]
FLOAT | BumpEnvLScale[8]
FLOAT | BumpEnvLOffset[8]
DWORD | TextureTransformFlags[8] | D3DTTFF

다음 표에, 이펙트 파일로 사용하는 라이팅 스테이트의 일람을 나타낸다. 이펙트에 라이팅 스테이트를 설정하는 경우는, 라이트를 완전하게 기술하기 위해서 필요한 모든 스테이트를 설정해야 한다. D3DX 는 개별적으로 라이팅 스테이트를 설정할 수 없기 때문에, 선언에 실패한 스테이트에는 디폴트값이 설정된다.

형 | 라이팅 스테이트 | 유효한 값
DWORD | LightType[n] | D3DLT
VECTOR | LightDiffuse[n] |
VECTOR | LightSpecular[n]
VECTOR | LightAmbient[n]
VECTOR | LightPosition[n]
VECTOR | LightDirection[n]
FLOAT | LightRange[n]
FLOAT | LightFalloff[n]
FLOAT | LightAttenuation0[n]
FLOAT | LightAttenuation1[n]
FLOAT | LightAttenuation2[n]
FLOAT | LightTheta[n]
FLOAT | LightPhi[n]
DWORD | LightEnable[n] | TRUE/FALSE

다음 표에, 이펙트 파일로 사용하는 유효한 머트리얼 스테이트의 일람을 나타낸다. 이펙트에 머트리얼 스테이트를 설정하는 경우는, 머트리얼을 완전하게 기술하기 위해서 필요한 모든 스테이트를 설정해야 한다. D3DX 는 개별적으로 머트리얼 스테이트를 설정할 수 없기 때문에, 선언에 실패한 스테이트에는 디폴트값이 설정된다.

형 | 머트리얼 스테이트
VECTOR | MaterialDiffuse
VECTOR | MaterialAmbient
VECTOR | MaterialSpecular
VECTOR | MaterialEmissive
FLOAT | MaterialPower

다음의 표는, 이펙트 파일로 사용하는 그 외의 유효한 스테이트를 나타내고 있다.

형 | 스테이트
VERTEXSHADER | VertexShader
PIXELSHADER | PixelShader
CONSTANT | VertexShaderConstant[n]
CONSTANT | PixelShaderConstant[n]
TEXTURE | Texture[8]
MATRIX | ProjectionTransform
MATRIX | ViewTransform
MATRIX | WorldTransform[256]
MATRIX | TextureTransform[8]


이펙트 파일의 샘플

다음에 나타내는 것은, 표준적인 이펙트 파일의 기본 구문 및 레이아웃이다.

//
// 샘플 이펙트.
// 이 이펙트는, 싱글 패스 방법 또는 멀티 패스 방법을 사용해, 2 개의 텍스쳐를 추가한다.
//

texture tex0;
texture tex1;

// 싱글 패스.

technique t0
{
    pass p0
    {
        Texture[0] = <tex0>;
        Texture[1] = <tex1>;

        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;

        ColorOp[1] = Add;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;

        ColorOp[2] = Disable;
    }
}

// 멀티 패스.

technique t1
{
    pass p0
    {
        Texture[0] = <tex0>;

        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;
        ColorOp[1] = Disable;
    }

    pass p1
    {
        AlphaBlendEnable = True;
        SrcBlend = One;
        DestBlend = One;

        Texture[1] = <tex1>;

        ColorOp[1] = SelectArg1;
        ColorArg1[1] = Texture;
        ColorOp[1] = Disable;
    }
}


X 파일 C/C++ 레퍼런스

여기에서는, Microsoft® DirectX® (. x)의 파일을 취급하기 위해서(때문에) 사용되는 API 요소의 레퍼런스 정보를 기술한다.

  • 인터페이스
  • 함수
  • 구조체
  • 반환값


인터페이스

여기에서는, Microsoft® DirectX® (. x)의 파일에 대한 읽고 쓰기로 사용되는 COM 인터페이스의 레퍼런스 정보를 기술한다.

  • IDirectXFile
  • IDirectXFileBinary
  • IDirectXFileData
  • IDirectXFileDataReference
  • IDirectXFileEnumObject
  • IDirectXFileObject
  • IDirectXFileSaveObject


IDirectXFile

IDirectXFileEnumObject 인터페이스 및 IDirectXFileSaveObject 인터페이스의 인스턴스를 생성 해, 템플릿을 등록하려면 ,IDirectXFile 인터페이스의 메소드를 사용한다.

IDirectXFile 인터페이스를 취득하려면 ,DirectXFileCreate 함수를 호출한다.

IDirectXFile 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

생성 | CreateEnumObject
 | CreateSaveObject
템플릿 | RegisterTemplates

모든 COM 인터페이스와 같이,IDirectXFile 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFile 인터페이스의 글로벌 유니크 식별자 (GUID)는 IID_IDirectXFile 이다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFile::CreateEnumObject

열거 오브젝트를 생성 한다.

HRESULT CreateEnumObject(
  LPVOID pvSource,
  DXFILELOADOPTIONS dwLoadOptions,
  LPDIRECTXFILEENUMOBJECT* ppEnumObj
);

파라미터

pvSource
[out] dwLoadOptions 의 값에 의해 내용이 다른 데이터에의 포인터.
dwLoadOptions
[in] 데이터의 소스를 지정하는 값. 이 값에는, 다음의 플래그의 어느쪽이든을 지정할 수 있다.
DXFILELOAD_FROMFILE
파일로부터 데이터를 읽어내는 것을 나타낸다. pvSource 의 값은 파일의 이름이다.
DXFILELOAD_FROMRESOURCE
리소스로부터 데이터를 읽어내는 것을 나타낸다. pvSource 의 값은 DXFILELOADRESOURCE 구조체이다.
DXFILELOAD_FROMMEMORY
메모리로부터 데이터를 읽어내는 것을 나타낸다. pvSource 의 값은 DXFILELOADMEMORY 구조체이다.
DXFILELOAD_FROMSTREAM
스트림으로부터 데이터를 읽어내는 것을 나타낸다. 현재는 지원되어 있지 않다.
DXFILELOAD_FROMURL
URL 로부터 데이터를 읽어내는 것을 나타낸다. pvSource 의 값은 URL 의 이름이다.
ppEnumObj
[out] 생성 된 열거 오브젝트를 나타내는 IDirectXFileEnumObject 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADALLOC
DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADRESOURCE
DXFILEERR_BADVALUE
DXFILEERR_FILENOTFOUND
DXFILEERR_RESOURCENOTFOUND
DXFILEERR_URLNOTFOUND

주의

이 메소드를 사용한 후는,IDirectXFileEnumObject 메소드의 1 개를 사용해, 데이터 오브젝트를 취득한다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.

참조

IDirectXFileEnumObject


IDirectXFile::CreateSaveObject

보존 오브젝트를 생성 한다.

HRESULT CreateSaveObject(
  LPCSTR szFileName,
  DXFILEFORMAT dwFileFormat,
  LPDIRECTXFILESAVEOBJECT* ppSaveObj
);

파라미터

szFileName
[in] 데이터를 보존하기 위해서 사용하는 파일의 이름에의 포인터.
dwFileFormat
[in] Microsoft® DirectX® 의 파일을 보존할 경우에 사용하는 포맷을 지정한다. 상세한 것에 대하여는, 「주의」를 참조할것.
DXFILEFORMAT_BINARY
바이노리필드를 나타낸다.
DXFILEFORMAT_COMPRESSED
압축파일을 나타낸다.
DXFILEFORMAT_TEXT
텍스트 파일을 나타낸다.
ppSaveObj
[out, retval] 생성 된 보존 오브젝트를 나타내는 IDirectXFileSaveObject 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADALLOC
DXFILEERR_BADFILE
DXFILEERR_BADVALUE

주의

이 메소드를 사용한 후는,IDirectXFileSaveObject 인터페이스의 메소드를 사용해 데이터 오브젝트를 생성 해, 템플릿 또는 데이터를 보존한다.

파일 포맷의 디폴트값은 DXFILEFORMAT_BINARY 이다. 파일 포맷의 값을 논리화로 결합해, 압축 텍스트 파일 또는 압축 바이노리필드를 생성 할 수 있다. 바이너리 (0)와 텍스트 (1)의 양쪽 모두를 지정했을 경우는, 텍스트 파일 포맷의 값과 구별이 되지 않기 때문에 (0 + 1 = 1), 텍스트 파일로서 보존된다. 파일 포맷으로서 텍스트 또한 압축을 지정 하면, 파일은 최초로 텍스트로서 기입해진 후, 압축된다. 다만, 압축 텍스트 파일은 바이너리 텍스트 파일(정도)만큼 효율이 좋지 않기 때문에, 대부분의 경우는, 바이너리 또한 압축을 지정할 필요가 있다. 포맷을 지정하지 않고 파일을 압축하도록(듯이) 설정 하면, 바이너리 압축파일이 생성 된다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.

참조

IDirectXFileSaveObject


IDirectXFile::RegisterTemplates

커스텀 템플릿을 등록한다.

HRESULT RegisterTemplates(
  LPVOID pvData,
  DWORD cbSize
);

파라미터

pvData
[in] 템플릿을 포함한 텍스트 포맷 또는 바이너리 포맷의 Microsoft® DirectX® 파일을 구성하는 버퍼에의 포인터.
cbSize
[in] pvData 에 의해 나타나는 바이트 단위의 버퍼 사이즈.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADVALUE
DXFILEERR_PARSEERROR

주의

다음의 샘플 코드는,RegisterTemplates 메소드의 호출해, 및 pvData 가 가리키는 버퍼의 내용의 예이다.

TIDirectXFile * pDXFile;

char *szTemplates = "xof 0303txt 0032\
    template SimpleData { \
        <2b934580-9e9a-11cf-ab39-0020af71e433> \
        DWORD item1;DWORD item2;DWORD item3;} \
    template ArrayData { \
        <2b934581-9e9a-11cf-ab39-0020af71e433> \
        DWORD cItems; array DWORD aItem[2][cItems]; [...] } \
    template RestrictedData { \
        <2b934582-9e9a-11cf-ab39-0020af71e433> \
        DWORD item; [SimpleData]}";

hr = pDXFile->RegisterTemplates(szTemplates, strlen(szTemplates));

템플릿은 모두, 이름과 유니버설 유니크 식별자 (UUID)를 지정해야 한다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileBinary

바이너리 데이터를 읽어내거나 바이너리 데이터에 대한 정보를 취득하거나 하려면 ,IDirectXFileBinary 인터페이스의 메소드를 사용한다.

IDirectXFileBinary 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirectXFileObject 의 메소드를 계승한다.

정보 | GetId
 | GetName

IDirectXFileBinary 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetMimeType
 | GetSize
데이터의 독해 | Read

모든 COM 인터페이스와 같이,IDirectXFileBinary 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileBinary 인터페이스의 글로벌 유니크 식별자 (GUID)는 IID_IDirectXFileBinary 이다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileBinary::GetMimeType

바이너리 데이터의 MIME (Multipurpose Internet Mail Extensions) 타입을 취득한다.

HRESULT GetMimeType(
  LPCSTR* pszMimeType
);

파라미터

pszMimeType
[out, retval] MIME 타입의 캐릭터 라인을 받는 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는 DXFILEERR_BADVALUE 를 돌려준다.

주의

바이너리 오브젝트에 대해서 Microsoft® DirectX® 파일로 MIME 타입이 지정되어 있지 않은 경우는,pszMimeType 에 NULL 가 설정된다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileBinary::GetSize

바이너리 데이터의 사이즈를 취득한다.

HRESULT GetSize(
  DWORD* pcbSize
);

파라미터

pcbSize
[out, retval] 돌려주어지는 바이너리 데이터의 사이즈에의 포인터 (바이트 단위).

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는 DXFILEERR_BADVALUE 를 돌려준다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileBinary::Read

바이너리 데이터를 읽어낸다.

HRESULT Read(
  LPVOID pvData,
  DWORD cbSize,
  LPDWORD pcbRead
);

파라미터

pvData
[out] 읽어낸 데이터를 받는 버퍼에의 포인터.
cbSize
[in] pvData 에 의해 나타나는 바이트 단위의 버퍼 사이즈.
pcbRead
[out, retval] 실제로 읽어내진 바이트수에의 포인터.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADVALUE
DXFILEERR_NOMOREDATA

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileData

데이터 오브젝트의 직접 계층을 구축하거나 직접 계층에 액세스 하거나 하려면 ,IDirectXFileData 인터페이스의 메소드를 사용한다. 템플릿의 제약에 의해 계층이 정해진다. 템플릿에 의해 허가되는 데이터형을, 옵션 멤버라고 부른다. 옵션 멤버는 필수는 아니지만, 옵션 멤버가 없으면 오브젝트로 중요한 정보가 부족하는 경우가 있다. 옵션 멤버는, 데이터 오브젝트의 자식으로 보존된다. 아이는, 다른 데이터 오브젝트, 이전의 데이터 오브젝트에의 참조, 또는 바이너리 오브젝트이다.

IDirectXFileData 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirectXFileObject 의 메소드를 계승한다.

정보 | GetId
 | GetName

IDirectXFileData 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

데이터의 추가 | AddBinaryObject
 | AddDataObject
 | AddDataReference
데이터의 취득 | GetData
 | GetNextObject
 | GetType

모든 COM 인터페이스와 같이,IDirectXFileData 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileData 인터페이스의 글로벌 유니크 식별자 (GUID)는 IID_IDirectXFileData 이다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileData::AddBinaryObject

바이너리 오브젝트를 생성 해, 아이 오브젝트로서 추가한다.

HRESULT AddBinaryObject(
  LPCSTR szName,
  const GUID* pguid,
  LPCSTR szMimeType,
  LPVOID pvData,
  DWORD cbSize
);

파라미터

szName
[in] 오브젝트의 이름에의 포인터. 오브젝트에 이름이 필요없는 경우는, NULL 를 지정한다.
pguid
[in] 오브젝트를 나타내는 글로벌 유니크 식별자 (GUID)에의 포인터. 오브젝트에 GUID 가 필요없는 경우는, NULL 를 지정한다.
szMimeType
[in] 오브젝트의 MIME 타입에의 포인터.
pvData
[in] 오브젝트의 데이터에의 포인터.
cbSize
[in] pvData 에 의해 나타나는 바이트 단위의 버퍼 사이즈.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.

참조

IDirectXFileBinary::GetMimeType


IDirectXFileData::AddDataObject

아이 오브젝트로서 데이터 오브젝트를 추가한다.

HRESULT AddDataObject(
  LPDIRECTXFILEDATA pDataObj
);

파라미터

pDataObj
[in] 자 오브젝트로서 추가하는 파일 데이터 오브젝트를 나타내는 IDirectXFileData 인터페이스에의 포인터.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

주의

IDirectXFileSaveObject::CreateDataObject 메소드를 사용해 IDirectXFileData 오브젝트를 생성 하고 나서, 이 메소드를 호출한다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.

참조

IDirectXFileSaveObject::CreateDataObject


IDirectXFileData::AddDataReference

데이터 참조 오브젝트를 생성 해, 아이 오브젝트로서 추가한다.

HRESULT AddDataReference(
  LPCSTR szRef,
  const GUID* pguidRef
);

파라미터

szRef
[in] 참조되는 데이터 오브젝트의 이름에의 포인터. pguidRef 로 글로벌 유니크 식별자 (GUID)에의 참조를 지정하는 경우, 이 파라미터에 NULL 를 설정할 수 있다.
pguidRef
[in] 데이터를 나타내는 GUID 에의 포인터. szRef 로 이름에의 참조를 지정하는 경우, 이 파라미터에 NULL 를 설정할 수 있다.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

주의

이 메소드가 성공하려면 , 파라미터 szRef 와 pguidRef 가 적어도 한편이 NULL 이외가 아니면 안된다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileData::GetData

오브젝트의 멤버의 1 개에 대한 데이터, 또는 모든 멤버에 대한 데이터를 취득한다.

HRESULT GetData(
  LPCSTR szMember,
  DWORD* pcbSize,
  void** ppvData
);

파라미터

szMember
[in] 데이터를 취득하는 멤버의 이름에의 포인터. 전필수 멤버의 데이터를 취득하는 경우는, NULL 를 지정한다.
pcbSize
[out] ppvData 버퍼의 사이즈를 받기 위한 포인터 (바이트 단위).
ppvData
[out] szMember 에 관련지을 수 있고 있는 데이터를 받는 버퍼에의 포인터의 주소. szMember 가 NULL 의 경우는, 전필수 멤버의 데이터가 저장 되고 있는 연속한 메모리 블록의 버퍼에의 포인터가 설정된다.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADARRAYSIZE
DXFILEERR_BADDATAREFERENCE
DXFILEERR_BADVALUE

주의

이 메소드를 사용하면(자), 데이터 오브젝트의 필수 멤버의 데이터를 취득할 수 있지만, 옵션 (아이) 멤버의 데이터는 취득할 수 없다. 아이 오브젝트를 취득하려면 ,IDirectXFileData::GetNextObject 메소드를 사용한다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.

참조

IDirectXFileData::GetNextObject


IDirectXFileData::GetNextObject

Microsoft® DirectX® 파일중의 다음의 아이 데이터 오브젝트, 데이터 참조 오브젝트, 또는 바이너리 오브젝트를 취득한다.

HRESULT GetNextObject(
  LPDIRECTXFILEOBJECT* ppChildObj
);

파라미터

ppChildObj
[out, retval] IDirectXFileObject 인터페이스에의 포인터의 주소. 돌려주어지는 아이 오브젝트의 파일 오브젝트 인터페이스에의 포인터가 저장 된다.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

주의

취득된 오브젝트의 형태를 조사하려면 ,QueryInterface 를 사용해, 취득된 오브젝트가 IDirectXFileData ,IDirectXFileDataReference , 또는 IDirectXFileBinary 목의 인터페이스를 지원 하는지를 조회한다. 지원 되는 인터페이스가, 오브젝트의 형태 (데이터, 데이터 참조, 또는 바이너리)를 나타내고 있다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.

참조

IDirectXFileBinary ,IDirectXFileData ,IDirectXFileDataReference


IDirectXFileData::GetType

오브젝트의 템플릿의 글로벌 유니크 식별자 (GUID)를 취득한다.

HRESULT GetType(
  const GUID** ppguid
);

파라미터

ppguid
[out, retval] 오브젝트의 템플릿의 GUID 를 받는 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는 DXFILEERR_BADVALUE 을 돌려준다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileDataReference

데이터 참조 오브젝트를 지원 하려면 ,IDirectXFileDataReference 인터페이스의 메소드를 사용한다. 데이터 참조 오브젝트는, 파일내에서 이미 정의되고 있는 데이터 오브젝트를 참조하고 있다. 데이터 참조 오브젝트를 사용하면(자), 파일내에서 반복해 정의하지 않아도, 같은 오브젝트를 몇회에서도 사용할 수 있다.

IDirectXFileDataReference 인터페이스는, 다음과 같은 그룹으로 분류할 수 있는 IDirectXFileObject 의 메소드를 계승한다.

정보 | GetId
 | GetName

모든 COM 인터페이스와 같이,IDirectXFileDataReference 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

오브젝트가 데이터 참조 오브젝트인 것을 판별한 후,IDirectXFileDataReference::Resolve 메소드를 사용해, 파일내에서 이미 정의되고 있는 참조 대상 오브젝트를 취득한다.

데이터 참조 오브젝트를 식별하는 방법에 대해서는, 「IDirectXFileData 인터페이스」를 참조할것.

IDirectXFileDataReference 인터페이스의 글로벌 유니크 식별자 (GUID)는 IID_IDirectXFileDataReference 이다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileDataReference::Resolve

데이터 참조를 해결한다.

HRESULT Resolve(
  LPDIRECTXFILEDATA* ppDataObj
);

파라미터

ppDataObj
[out, retval] 돌려주어지는 파일 데이터 오브젝트를 나타내는 IDirectXFileData 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileEnumObject

파일내의 데이터 오브젝트에 대한 처리를 반복해, 글로벌 유니크 식별자 (GUID) 또는 이름으로 데이터 오브젝트를 취득하려면 ,IDirectXFileEnumObject 인터페이스의 메소드를 사용한다.

IDirectXFileEnumObject 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

오브젝트의 취득 | GetDataObjectById
 | GetDataObjectByName
열거 | GetNextDataObject

모든 COM 인터페이스와 같이,IDirectXFileEnumObject 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileEnumObject 인터페이스의 GUID 는, IID_IDirectXFileEnumObject 이다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileEnumObject::GetDataObjectById

지정된 글로벌 유니크 식별자 (GUID)를 가지는 데이터 오브젝트를 취득한다.

HRESULT GetDataObjectById(
  REFGUID rguid,
  LPDIRECTXFILEDATA* ppDataObj
);

파라미터

rguid
[in] 요구된 글로벌 유니크 식별자 (GUID)에의 참조.
ppDataObj
[out] 돌려주어지는 파일 데이터 오브젝트를 나타내는 IDirectXFileData 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileEnumObject::GetDataObjectByName

지정된 이름을 가지는 데이터 오브젝트를 취득한다.

HRESULT GetDataObjectByName(
  LPCSTR szName,
  LPDIRECTXFILEDATA* ppDataObj
);

파라미터

szName
[in] 요구하는 이름에의 포인터.
ppDataObj
[out] 돌려주어지는 파일 데이터 오브젝트를 나타내는 IDirectXFileData 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileEnumObject::GetNextDataObject

Microsoft® DirectX® 파일중에 있는 다음의 톱 레벨 오브젝트를 취득한다.

HRESULT GetNextDataObject(
  LPDIRECTXFILEDATA* ppDataObj
);

파라미터

ppDataObj
[out] 돌려주어지는 파일 데이터 오브젝트를 나타내는 IDirectXFileData 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

주의

톱 레벨 오브젝트는, 반드시 데이터 오브젝트이다. 데이터 참조 오브젝트 및 바이너리 오브젝트는, 데이터 오브젝트의 아이가 되는 것만이 할 수 있다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileObject

Microsoft® DirectX® 파일 오브젝트에 대한 정보를 취득하려면 ,IDirectXFileObject 인터페이스의 메소드를 사용한다.

IDirectXFileObject 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetId
 | GetName

모든 COM 인터페이스와 같이,IDirectXFileObject 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileObject 인터페이스의 글로벌 유니크 식별자 (GUID)는 IID_IDirectXFileObject 이다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileObject::GetId

Microsoft® DirectX® 파일 오브젝트를 식별하는 글로벌 유니크 식별자 (GUID)에의 포인터를 취득한다.

HRESULT GetId(
  LPGUID pGuid
);

파라미터

pGuid
[out, retval] 오브젝트의 ID 를 받는 글로벌 유니크 식별자 (GUID)에의 포인터. 오브젝트가 ID 를 가지고 있지 않은 경우, 이 함수는 GUID 에 NULL GUID 를 설정한다.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는 DXFILEERR_BADVALUE 를 돌려준다.

대상

이 메소드는,IDirectXFileObject 를 계승하는 다음의 인터페이스에 적용된다.

  • IDirectXFileBinary
  • IDirectXFileData

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileObject::GetName

Microsoft® DirectX® 파일 오브젝트의 이름에의 포인터를 취득한다.

HRESULT GetName(
  LPSTR pstrNameBuf,
  LPDWORD pdwBufLen
);

파라미터

pstrNameBuf
[out] Microsoft® DirectX® 파일 오브젝트의 이름이 카피되는 버퍼에의 포인터. 버퍼장만이 필요하면 NULL 를 설정한다.
pdwBufLen
[in, out] pstrNameBuf 가 가리키는 버퍼의 길이를 나타내는 DWORD 값에의 포인터. pstrNameBuf 가 NULL 의 경우에서도, 오브젝트의 이름을 저장 하기 위해서 필요한 버퍼장이 설정된다. 어느 경우도,pdwBufLen 의 원의 값이 오브젝트의 이름을 저장 하는데 필요한 길이 이상의 값이 아닐 때는, DXFILEERR_BADVALUE 가 함수로부터 돌아간다.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

대상

이 메소드는,IDirectXFileObject 를 계승하는 다음의 인터페이스에 적용된다.

  • IDirectXFileBinary
  • IDirectXFileData

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileSaveObject

데이터 오브젝트를 생성 해, 템플릿과 데이터 오브젝트를 보존하려면 ,IDirectXFileSaveObject 인터페이스의 메소드를 사용한다. 템플릿은, 반드시 모든 파일에 대해 필요하지 않다. 예를 들어, DirectX 파일 마다 템플릿을 복제하는 것이 아니라, 모든 템플릿을 1 개의 Microsoft® DirectX® 파일에 거두어도 상관없다.

IDirectXFileSaveObject 인터페이스를 취득하려면 ,IDirectXFile::CreateSaveObject 메소드를 호출한다.

IDirectXFileSaveObject 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

생성 | CreateDataObject
보존 | SaveData
 | SaveTemplates

모든 COM 인터페이스와 같이,IDirectXFileSaveObject 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileSaveObject 인터페이스의 글로벌 유니크 식별자 (GUID)는 IID_IDirectXFileSaveObject 이다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileSaveObject::CreateDataObject

데이터 오브젝트를 생성 한다.

HRESULT CreateDataObject(
  REFGUID rguidTemplate,
  LPCSTR szName,
  const GUID* pguid,
  DWORD cbSize,
  LPVOID pvData,
  LPDIRECTXFILEDATA* ppDataObj
);

파라미터

rguidTemplate
[in] 데이터 오브젝트의 템플릿을 나타내는 글로벌 유니크 식별자 (GUID).
szName
[in] 데이터 오브젝트의 이름에의 포인터. 오브젝트에 이름이 없는 경우는, NULL 를 지정한다.
pguid
[in] 데이터 오브젝트를 나타내는 GUID 에의 포인터. 오브젝트에 GUID 가 없는 경우는, NULL 를 지정한다.
cbSize
[in] 데이터 오브젝트의 사이즈 (바이트 단위).
pvData
[in] 전필수 멤버의 데이터가 저장 되고 있는 버퍼에의 포인터.
ppDataObj
[out, retval] 생성 된 파일 데이터 오브젝트를 나타내는 IDirectXFileData 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

주의

데이터 참조 오브젝트가 생성 한 데이터 오브젝트를 참조하는 경우는,szName 파라미터와 pguid 파라미터의 적어도 한편은 NULL 이외의 값이 아니면 안된다.

이 메소드로 생성 한 데이터를 보존하기 전에,IDirectXFileSaveObject::SaveTemplates 메소드를 사용해 템플릿을 보존해야 한다. 생성 한 데이터는 IDirectXFileSaveObject::SaveData 메소드를 사용해 보존한다.

옵션 데이터를 보존할 필요가 있는 경우는, 이 메소드를 호출한 후,SaveData 메소드를 호출하기 전에,IDirectXFileData::AddDataObject 메소드를 사용해 실시한다. 아이 오브젝트가 있는 경우는,SaveData 를 호출하기 전에 추가한다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.

참조

IDirectXFileData::AddDataObject ,IDirectXFileSaveObject::SaveData ,IDirectXFileSaveObject::SaveTemplates


IDirectXFileSaveObject::SaveData

데이터 오브젝트와 그 아이를 Microsoft® DirectX® 파일에 보존한다.

HRESULT SaveData(
  LPDIRECTXFILEDATA pDataObj
);

파라미터

pDataObj
[in] 보존하는 파일 데이터 오브젝트를 나타내는 IDirectXFileData 인터페이스에의 포인터.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADARRAYSIZE
DXFILEERR_BADVALUE

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.


IDirectXFileSaveObject::SaveTemplates

템플릿을 Microsoft® DirectX® 파일에 보존한다.

HRESULT SaveTemplates(
  DWORD cTemplates,
  const GUID** ppguidTemplates
);

파라미터

cTemplates
[in] 보존하는 템플릿의 총수.
ppguidTemplates
[in] 보존하는 전템플릿의 글로벌 유니크 식별자 (GUID) 배열에의 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는 DXFILEERR_BADVALUE 를 돌려준다.

주의

다음의 샘플 코드는,SaveTemplates 메소드의 호출해, 및 ppguidTemplates 가 가리키는 배열의 내용의 예이다.

IDirectXFileSaveObject * pDXFileSaveObject;

const GUID *aIds[] = {
    &DXFILEOBJ_SimpleData,
    &DXFILEOBJ_ArrayData,
    &DXFILEOBJ_RestrictedData};

hr = pDXFileSaveObject->SaveTemplates(3, aIds);

이 메소드를 사용해 템플릿을 보존한 후, 데이터 오브젝트를 생성 하려면 ,IDirectXFileSaveObject::CreateDataObject 메소드를 사용한다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.

참조

IDirectXFileSaveObject::CreateDataObject


함수

여기에서는, Microsoft® DirectX® 파일을 사용하는 경우에 이행 할 필요가 있는 함수의 레퍼런스 정보를 기술한다. 다음의 함수가 이행 되고 있다.

  • DirectXFileCreate


DirectXFileCreate

DirectXFile 오브젝트의 인스턴스를 생성 한다.

STDAPI DirectXFileCreate(
  LPDIRECTXFILE* lplpDirectXFile
);

파라미터

lplpDirectXFile
생성 된 DirectXFile 오브젝트를 나타내는 IDirectXFile 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, DXFILE_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

주의

이 함수를 사용한 후, 템플릿을 등록하려면 IDirectXFile::RegisterTemplates 를, 열거 오브젝트를 생성 하려면 IDirectXFile::CreateEnumObject 를, 보존 오브젝트를 생성 하려면 IDirectXFile::CreateSaveObject 를, 각각 사용한다.

동작환경

헤더 : dxfile.h 로 선언.
임포트 라이브러리 : d3dxof.lib 를 사용.

참조

IDirectXFile::CreateEnumObject ,IDirectXFile::CreateSaveObject ,IDirectXFile::RegisterTemplates


구조체

여기에서는, Microsoft® DirectX® 로 사용하는 이하의 구조체에 대해 설명한다.

  • DXFILELOADMEMORY
  • DXFILELOADRESOURCE


DXFILELOADMEMORY

메모리 데이터를 나타낸다.

typedef struct _DXFILELOADMEMORY {
    LPVOID lpMemory;
    DWORD dSize;
} DXFILELOADMEMORY, *LPDXFILELOADMEMORY;

멤버

lpMemory
로드하는 메모리 블록에의 포인터.
dSize
로드하는 메모리 블록의 사이즈 (바이트 단위).

주의

이 구조체는, 어플리케이션으로 DXFILELOAD_FROMMEMORY 를 지정해 IDirectXFile::CreateEnumObject 메소드를 사용 하면 로드 되는 리소스를 나타내고 있다.

동작환경

헤더 : dxfile.h 로 선언.

참조

IDirectXFile::CreateEnumObject


DXFILELOADRESOURCE

리소스 데이터를 나타낸다.

typedef struct _DXFILELOADRESOURCE {
    HMODULE hModule;
    LPCTSTR lpName;
    LPCTSTR lpType;
} DXFILELOADRESOURCE, *LPDXFILELOADRESOURCE;

멤버

hModule
로드하는 리소스를 포함한 모듈의 핸들. 이 멤버가 NULL 의 경우는, 리소스는, 그것을 사용하는 실행 가능 파일에 어태치되어 있지 않으면 안 된다.
lpName
로드하는 리소스의 이름을 지정하는 캐릭터 라인에의 포인터. 예를 들어, 리소스가 메쉬의 경우는, 이 멤버로 메쉬 파일의 이름을 지정해야 한다.
lpType
리소스를 식별하는 유저 정의 타입을 지정하는 캐릭터 라인에의 포인터.

주의

이 구조체는, 어플리케이션으로 DXFILELOAD_FROMRESOURCE 를 지정해 IDirectXFile::CreateEnumObject 메소드를 사용 하면 로드 되는 리소스를 나타내고 있다.

동작환경

헤더 : dxfile.h 로 선언.

참조

IDirectXFile::CreateEnumObject


반환값

Microsoft® DirectX® (. x) 파일의 처리에 사용하는 메소드로부터는, COM 의 표준의 반환값에 가세해, 다음의 값이 돌아가는 경우가 있다.

DXFILE_OK
커멘드가 정상적으로 완료했다.
DXFILEERR_BADALLOC
메모리의 할당해에 실패했다.
DXFILEERR_BADARRAYSIZE
배열의 사이즈가 무효이다.
DXFILEERR_BADCACHEFILE
. x 파일의 데이터를 저장 하고 있는 캐쉬 파일이 무효이다. 캐쉬 파일에는, 네트워크로부터 취득되어, 하드 디스크에 캐쉬되어, 이후의 요구에 대해 취득된 데이터가 저장 되고 있다.
DXFILEERR_BADDATAREFERENCE
참조되고 있는 데이터가 무효이다.
DXFILEERR_BADFILE
파일이 무효이다.
DXFILEERR_BADFILECOMPRESSIONTYPE
파일 압축의 타입이 무효이다.
DXFILEERR_BADFILEFLOATSIZE
부동 소수점의 사이즈가 무효이다.
DXFILEERR_BADFILETYPE
파일이 DirectX (. x) 파일은 아니다.
DXFILEERR_BADFILEVERSION
파일의 버젼이 무효이다.
DXFILEERR_BADINTRINSICS
고유 정보가 무효이다.
DXFILEERR_BADOBJECT
오브젝트가 무효이다.
DXFILEERR_BADRESOURCE
리소스가 무효이다.
DXFILEERR_BADTYPE
오브젝트 타입이 무효이다.
DXFILEERR_BADVALUE
파라미터가 무효이다.
DXFILEERR_FILENOTFOUND
파일이 발견되지 않는다.
DXFILEERR_INTERNALERROR
내부 에러가 발생했다.
DXFILEERR_NOINTERNET
인터넷 접속이 발견되지 않는다.
DXFILEERR_NOMOREDATA
그 이상 이용할 수 있는 데이터가 없다.
DXFILEERR_NOMOREOBJECTS
모든 오브젝트가 열거되고 있다.
DXFILEERR_NOMORESTREAMHANDLES
스트림 핸들을 이용할 수 없다.
DXFILEERR_NOTDONEYET
처리가 완료하고 있지 않다.
DXFILEERR_NOTFOUND
오브젝트가 발견되지 않는다.
DXFILEERR_PARSEERROR
파일을 해석할 수 없다.
DXFILEERR_RESOURCENOTFOUND
리소스가 발견되지 않는다.
DXFILEERR_NOTEMPLATE
템플릿을 이용할 수 없다.
DXFILEERR_URLNOTFOUND
URL 가 발견되지 않는다.


X 파일 포맷 레퍼런스

여기에서는, Microsoft® DirectX® (. x) 파일 포맷의 레퍼런스 정보를 기술한다.

  • X 파일 템플릿
  • 바이너리 포맷


X 파일 템플릿

여기에서는, 다음의 . x 파일 템플릿에 대해 자세하게 설명한다.

  • Header
  • Vector
  • Coords2d
  • Quaternion
  • Matrix4x4
  • ColorRGBA
  • ColorRGB
  • IndexedColor
  • Boolean
  • Boolean2d
  • Material
  • TextureFilename
  • MeshFace
  • MeshFaceWraps
  • MeshTextureCoords
  • MeshNormals
  • MeshVertexColors
  • MeshMaterialList
  • Mesh
  • FrameTransformMatrix
  • Frame
  • FloatKeys
  • TimedFloatKeys
  • AnimationKey
  • AnimationOptions
  • Animation
  • AnimationSet
  • Patch
  • PatchMesh
  • VertexDuplicationIndices
  • XSkinMeshHeader
  • SkinWeights


Header

어플리케이션 고유의 헤더를 정의한다.

UUID

<3D82AB43-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
major | WORD |  | 없음
minor | WORD |  |
flags | DWORD


Vector

벡터를 정의한다.

UUID

<3D82AB5E-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
x | FLOAT |  | 없음
y | FLOAT |  |
z | FLOAT


Coords2d

메쉬의 텍스쳐 좌표를 정의하기 위해서 사용하는 2 차원 벡터.

UUID

<F6F23F44-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
u | FLOAT |  | 없음
v | FLOAT |  |


Quaternion

현재는 사용되어 있지 않다.

UUID

<10DD46A3-775B-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
s | FLOAT |  | 없음
v | Vector |  |


Matrix4x4

4 × 4 의 행렬을 정의한다. 이것은 프레임 트랜스 폼 행렬로서 사용된다.

UUID

<F6F23F45-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
matrix | 배열 FLOAT | 16 | 없음


ColorRGBA

알파 성분을 사용해 색오브젝트를 정의한다. 이것은, 머트리얼 템플릿 정의로 표면의 색으로서 사용된다.

UUID

<35FF44E0-6C7C-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
red | FLOAT |  | 없음
green | FLOAT |  |
blue | FLOAT
alpha | FLOAT


ColorRGB

기본적인 RGB 색오브젝트를 정의한다.

UUID

<D3E16E81-7835-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
red | FLOAT |  | 없음
green | FLOAT |  |
blue | FLOAT


IndexedColor

인덱스 파라미터와 RGBA 색으로 구성되어 메쉬 버텍스 칼라를 정의하기 위해서 사용된다. 인덱스는 색을 적용하는 버텍스를 정의한다.

UUID

<1630B820-7842-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈
index | DWORD |
indexColor | ColorRGBA


Boolean

단순한 불형을 정의한다. 이 템플릿은 0 또는 1 으로 설정해야 한다.

UUID

<4885AE61-78E8-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
truefalse | DWORD |  | 없음


Boolean2d

MeshFaceWraps 템플릿으로, 개개의 면의 텍스쳐 위상기하학을 정의하기 위해서 사용되는 2 개의 불리언 값세트를 정의한다.

UUID

<4885AE63-78E8-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
u | Boolean |  | 없음
v | Boolean |  |


Material

메쉬 전체 또는 메쉬의 개개의 면의 어느 쪽인가에 적용할 수 있는 기본적인 머트리얼색을 정의한다. 거듭제곱은 머트리얼의 스펙큐러 지수이다. 앰비언트색에는 알파 성분이 필요한 것으로 주의 해야 한다.

TextureFilename 는, 옵션의 데이터 오브젝트이다. 이 오브젝트가 존재하지 않는 경우, 면은 텍스쳐 처리되지 않는다.

UUID

<3D82AB4D-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
faceColor | ColorRGBA |  | 임의
power | FLOAT |  |
specularColor | ColorRGB
emissiveColor | ColorRGB


TextureFilename

메쉬 또는 면에 적용하는 텍스쳐의 파일명을 지정할 수 있도록(듯이) 한다. 이 템플릿은, 머트리얼 오브젝트내에 존재하고 있지 않으면 안 된다.

UUID

<A42790E1-7810-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
filename | STRING |  | 없음


MeshFace

Mesh 템플릿으로, 메쉬의 면을 정의하기 위해서 사용된다. nFaceVertexIndices 배열의 각 요소는, 면을 구축하기 위해서 사용되는 메쉬 버텍스를 참조한다.

UUID

<3D82AB5F-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nFaceVertexIndices | DWORD |  | 없음
faceVertexIndices | 배열 DWORD | nFaceVertexIndicies |


MeshFaceWraps

랩내의 각면의 텍스쳐 위상기하학을 정의하기 위해서 사용된다. nFaceWrapValues 멤버의 값은, 메쉬의 면의 수와 같지 않으면 안 된다.

UUID

<4885AE62-78E8-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nFaceWrapValues | DWORD |  | 없음
faceWrapValues | Boolean2d |  |


MeshTextureCoords

메쉬의 텍스쳐 좌표를 정의한다.

UUID

<F6F23F40-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nTextureCoords | DWORD |  | 없음
textureCoords | 배열 Coords2d | nTextureCoords |


MeshNormals

메쉬의 법선을 정의한다. 벡터의 최초의 배열은 법선 벡터 자체이며, 2 번째의 배열은 특정의 면에 적용해야 할 법선을 지정하는 인덱스의 배열이다. nFaceNormals 멤버의 값은, 메쉬의 면의 수와 같지 않으면 안 된다.

UUID

<F6F23F43-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nNormals | DWORD |  | 없음
normals | 배열 Vector | nNormals |
nFaceNormals | DWORD |
faceNormals | 배열 MeshFace | nFaceNormals


MeshVertexColors

면 마다, 또는 메쉬 마다 머트리얼을 적용하는 대신에, 메쉬의 버텍스 칼라를 지정한다.

UUID

<1630B821-7842-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nVertexColors | DWORD |  | 없음
vertexColors | 배열 IndexedColor | nVertexColors |


MeshMaterialList

메쉬 오브젝트로, 어느 머트리얼을 어느 면에 적용하는지를 지정하기 위해서 사용된다. nMaterials 멤버는 존재하는 머트리얼의 수를 지정해, materials 는 적용하는 머트리얼을 지정한다.

UUID

<F6F23F42-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nMaterials | DWORD |  | Material
nFaceIndexes | DWORD |  |
FaceIndexes | 배열 DWORD | nFaceIndexes


Mesh

단순한 메쉬를 정의한다. 최초의 배열은 버텍스의 리스트로, 2 번째의 배열은 버텍스 배열에 인덱스 붙이고 하는 것에 의해 메쉬의 면을 정의한다.

UUID

<3D82AB44-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nVertices | DWORD |  | 임의
vertices | 배열 Vector | nVertices |
nFaces | DWORD |
faces | 배열 MeshFace | nFaces

옵션의 데이터 요소

다음의 옵션의 데이터 요소를 사용할 수 있다.

Data element | 설명
MeshFaceWraps | 이 요소가 존재하지 않는 경우, u 및 v 의 양쪽 모두의 랩핑의 디폴트는 FALSE 가 된다.
MeshTextureCoords | 이 요소가 존재하지 않는 경우, 텍스쳐 좌표는 존재하지 않는다.
MeshNormals | 이 요소가 존재하지 않는 경우, 법선은 API 의 GenerateNormals 메소드를 사용해 생성된다.
MeshVertexColors | 이 요소가 존재하지 않는 경우, 색의 디폴트는 흰색이 된다.
MeshMaterialList | 이 요소가 존재하지 않는 경우, 머트리얼의 디폴트는 흰색이 된다.


FrameTransformMatrix

프레임 ( 및 그 모든 아이 오브젝트)의 로컬 트랜스 폼을 정의한다.

UUID

<F6F23F41-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
frameMatrix | Matrix4x4 |  | 없음


Frame

프레임을 정의한다. 현재, 프레임에는 Mesh 및 FrameTransformMatrix 형의 오브젝트를 포함할 수가 있다.

UUID

<3D82AB46-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
없음 |  |  | 임의

옵션의 데이터 요소

다음의 옵션의 요소를 사용할 수 있다.

Data element | 설명
FrameTransformMatrix | 이 요소가 존재하지 않는 경우, 프레임에 로컬 트랜스 폼이 적용되지 않는다.
Mesh | 프레임의 아이가 되는 임의의 수의 메쉬 오브젝트. 이러한 오브젝트는, 인 라인으로, 또는 참조에 의해 지정할 수 있다.


FloatKeys

부동 소수점수(실수) (float)의 배열 및 배열내의 float 의 수를 정의한다. 이것은, 애니메이션 키세트를 정의하기 위해서 사용된다.

UUID

<10DD46A9-775B-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nValues | DWORD |  | 없음
values | 배열 FLOAT | nValues |


TimedFloatKeys

애니메이션으로 사용되는 부동 소수점수(실수)세트 및 정의 시간을 정의한다.

UUID

<F406B180-7B3B-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
time | DWORD |  | 없음
tfkeys | FloatKeys |  |


AnimationKey

애니메이션 키세트를 정의한다. keyType 멤버는, 키가 회전, 스케일링, 위치, 또는 행렬 키의 머지않아인지를 지정한다 (각각, 정수 0, 1, 2, 3 을 사용한다). 행렬 키는, 애니메이션 데이터세트를 트랜스 폼 행렬로서 나타낼 필요가 있는 경우에 편리하다.

UUID

<10DD46A8-775B-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
keyType | DWORD |  | 없음
nKeys | DWORD |  |
keys | 배열 TimedFloatKeys | nKeys


AnimationOptions

애니메이션 옵션을 설정할 수 있도록(듯이) 한다. openclosed 멤버는 닫은 애니메이션을 나타내는 0, 또는 연 애니메이션을 나타내는 1 의 어느 쪽인가에 설정할 수 있다. positionquality 멤버는, 지정된 위치 키의 위치의 품질을 설정하기 위해서 사용된다. 스플라인 위치를 나타내는 0, 또는 리니어 위치를 나타내는 1 의 어느 쪽인가에 설정할 수 있다. 디폴트에서는, 애니메이션은 닫혀진다.

UUID

<E2BF56C0-840F-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
openclosed | DWORD |  | 없음
positionquality | DWORD |  |


Animation

전의 프레임을 참조하는 애니메이션을 저장 한다. 프레임에의 참조가 1 개로 적어도 1 세트의 AnimationKey 템플릿이 저장 되고 있을 필요가 있다. AnimationOptions 데이터 오브젝트를 저장 할 수도 있다.

UUID

<3D82AB4F-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
없음 |  |  | 임의

옵션의 데이터 요소

다음의 옵션의 데이터 요소가 사용된다.

Data element | 설명
AnimationKey | 모든 애니메이션으로 AnimationKeys 가 필요하게 된다.
AnimationOptions | 이 요소가 존재하지 않는 경우, 애니메이션은 닫혀진다.


AnimationSet

1 개(살) 이상의 Animation 오브젝트를 저장 한다. 애니메이션 세트내의 각 애니메이션은, 어느 시점에서도 같은 시간을 가진다. 애니메이션 세트의 시간을 늘리면(자), 포함할 수 있어 모든 애니메이션의 시간이 증가한다.

UUID

<3D82AB50-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
없음 |  |  | Animation


Patch

베쥬 제어 패치를 정의한다. 이 배열은 패치의 제어점을 정의한다.

UUID

<A3EB5D44-FC22-429D-9AFB-3221CB9719A6>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nControlIndices | DWORD |  | 없음
controlIndices | 배열 DWORD | nControlIndices |

패치의 타입은, 다음 표에 나타나고 있도록(듯이), 제어점의 수에 의해 정의된다.

제어점의 수 | 형
10 | 3 차 베쥬 삼각형 패치
15 | 4 차 베쥬 삼각형 패치
16 | 3 차 베쥬 사각형 (직사각형) 패치

제어점의 차수는, 삼각형 패치 및 직사각형 패치에 대해 다음의 그림에 나타나고 있도록(듯이), 나사형의 패턴으로 나타난다.

삼각형 패치에서는 다음의 패턴을 사용하고 있었다.

직사각형 패치에서는 다음의 패턴을 사용한다.


PatchMesh

베쥬 패치에 의해 정의된 메쉬를 정의한다. 최초의 배열은 버텍스의 리스트로, 2 번째의 배열은 버텍스 배열에 인덱스 붙이고 하는 것에 의해 메쉬의 패치를 정의한다.

UUID

<D02C95CC-EDBA-4305-9B5D-1820D7704BBF>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nVertices | DWORD |  | 없음
vertices | 배열 Vector | nVertices |
nPatches | DWORD |
patches | 배열 Patch | nPatches

패치는, 각 패치의 제어점으로서 버텍스의 배열내의 버텍스를 사용한다.


VertexDuplicationIndices

이 템플릿은 메쉬 마다 인스턴스화 되어 메쉬내의 어느 버텍스가 서로 중복 하고 있는가 하는 정보를 보관 유지한다. 버텍스가 스무딩 그룹 또는 머트리얼의 경계에 있는 경우에 중복이 발생한다. 이 템플릿의 목적은, 주변 파라미터가 다른 어느 버텍스가, 실제로는 모델내의 같은 버텍스일까를, 로더를 결정될 수 있도록(듯이) 하는 것이다. 특정의 용도 (메쉬의 단순화등)로, 이 정보를 이용할 수 있다.

UUID

<B8D65549-D7C9-4995-89CF-53A9A8B031E3>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nIndices | DWORD |  | 없음
nOriginalVertices | DWORD |  |
indices | 배열 DWORD | nIndices

중복이 발생하기 전의 메쉬내의 버텍스의 수는 nOriginalVertices 이다. 값 indices[n] 는, 중복이 발생하지 않는 경우에 메쉬의 버텍스 배열내의 vertex[n] 가 가지는 버텍스 인덱스를 보관 유지한다. 따라서, 이 배열내의 인덱스가 같은 경우는, 중복 한 버텍스인 것을 나타낸다.


XSkinMeshHeader

이 템플릿은, export 된 스키닝 정보를 포함한 메쉬내에서만, 메쉬 마다 인스턴스화 된다. 이 템플릿의 목적은, export 된 스키닝 정보의 성질에 관한 정보를 제공하는 것이다.

UUID

<3CF169CE-FF7C-44ab-93C0-F78F62D172E2>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
nMaxSkinWeightsPerVertex | WORD |  | 없음
nMaxSkinWeightsPerFace | WORD |  |
nBones | WORD

메쉬내의 버텍스에 영향을 주는 트랜스 폼의 최대수는 nMaxSkinWeightsPerVertex 이다. 임의의 면의 3 개의 버텍스에 영향을 주는 일의의 트랜스 폼의 최대수는 nMaxSkinWeightsPerFace 이다. 이 메쉬의 버텍스에 영향을 주는 뼈의 수는 nBones 이다.


SkinWeights

이 템플릿은 메쉬 마다 인스턴스화 된다. 메쉬내에, 이 템플릿의 n 개의 인스턴스의 순서가 표시된다. 여기서,n 는 메쉬내의 버텍스에 영향을 주는 뼈의 수 (X 파일 포맷)이다. 템플릿의 각 인스턴스는, 기본적으로 특정의 뼈의 메쉬에의 영향을 정의한다. 버텍스 인덱스의 리스트, 및 대응하는 중량감의 리스트가 있다.

UUID

<6F0D123B-BAD2-4167-A0D0-80224F25FABB>

멤버명 | 형 | 옵션의 배열 사이즈 | 옵션의 데이터 오브젝트
transformNodeName | STRING |  | 없음
nWeights | DWORD |  |
vertexIndices | 배열 DWORD | nWeights
weights | 배열 float | nWeights
matrixOffset | Matrix4x4 |

영향을 정의하는 뼈의 이름은 transformNodeName 이며,nWeights 는 이 뼈의 영향을 받는 버텍스의 수이다. 이 뼈의 영향을 받는 버텍스는 vertexIndices 에 저장 되고 있어 이 뼈의 영향을 받는 각 버텍스의 중량감은 weights 에 저장 된다.

행렬 matrixOffset 는, 메쉬의 버텍스를 뼈의 공간에 트랜스 폼 한다. 뼈의 트랜스 폼과 연결 하면, 뼈의 영향을 받는 메쉬의 월드 공간 좌표를 얻을 수 있다.


바이너리 포맷

여기에서는, DirectX 3.0 의 릴리스 이후 도입된 Microsoft® DirectX® (. x) 파일 포맷의 바이너리 버젼에 대해 자세하게 설명한다. 여기서 설명되고 있는 내용은, 「X 파일 아키텍쳐」의 설명을 참조하면서 읽는 것을 추천 한다.

바이너리 포맷은, 토큰화 된 텍스트 포맷의 표현이다. 토큰은, 스탠드얼론인 경우라고 프리미티브 데이터 레코드가 부속되는 경우가 있다. 스탠드얼론 토큰은 문법적인 구조를 제공해, 레코드 생성 토큰은 필요한 데이터를 제공한다.

모든 데이터는 little endian 포맷으로 저장 되는 것에 주의 해야 한다. 유효한 바이너리 데이터 스트림은, 헤더와 거기에 계속되는 템플릿과 데이터 오브젝트의 양쪽 모두 또는 어느쪽이든으로 구성된다.

여기에서는, 바이노리필드 포맷의 다음의 컴퍼넌트에 대해 설명해, 템플릿 및 바이너리 데이터 오브젝트의 예를 나타낸다.

  • 헤더
  • 토큰
  • 토큰 레코드
  • 템플릿
  • 데이터
  • 례


헤더

바이너리 헤더를 직접 읽고 쓰기하는 경우는, 다음의 정의를 사용해야 한다. 압축 데이터 스트림은 현재 지원되어 있지 않기 때문에, 여기에서는 자세하게 나타나지 않은 것에 주의 해야 한다.

#define XOFFILE_FORMAT_MAGIC \
  ((long)'x' + ((long)'o' << 8) + ((long)'f' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_VERSION \
  ((long)'0' + ((long)'3' << 8) + ((long)'0' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_BINARY \
  ((long)'b' + ((long)'i' << 8) + ((long)'n' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_TEXT   \
  ((long)'t' + ((long)'x' << 8) + ((long)'t' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_COMPRESSED \
  ((long)'c' + ((long)'m' << 8) + ((long)'p' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_32 \
  ((long)'0' + ((long)'0' << 8) + ((long)'3' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_64 \
  ((long)'0' + ((long)'0' << 8) + ((long)'6' << 16) + ((long)'4' << 24))


토큰

토큰은 little endian WORD 로서 기술된다. 이하의 토큰의 리스트는, 레코드 생성 토큰과 스탠드얼론 토큰으로 나누어져 있다.

레코드 생성 토큰은 다음과 같이 정의된다.

#define TOKEN_NAME 1
#define TOKEN_STRING 2
#define TOKEN_INTEGER 3
#define TOKEN_GUID 5
#define TOKEN_INTEGER_LIST 6
#define TOKEN_FLOAT_LIST 7

스탠드얼론 토큰은 다음과 같이 정의된다.

#define TOKEN_OBRACE 10
#define TOKEN_CBRACE 11
#define TOKEN_OPAREN 12
#define TOKEN_CPAREN 13
#define TOKEN_OBRACKET 14
#define TOKEN_CBRACKET 15
#define TOKEN_OANGLE 16
#define TOKEN_CANGLE 17
#define TOKEN_DOT 18
#define TOKEN_COMMA 19
#define TOKEN_SEMICOLON 20
#define TOKEN_TEMPLATE 31
#define TOKEN_WORD 40
#define TOKEN_DWORD 41
#define TOKEN_FLOAT 42
#define TOKEN_DOUBLE 43
#define TOKEN_CHAR 44
#define TOKEN_UCHAR 45
#define TOKEN_SWORD 46
#define TOKEN_SDWORD 47
#define TOKEN_VOID 48
#define TOKEN_LPSTR 49
#define TOKEN_UNICODE 50
#define TOKEN_CSTRING 51
#define TOKEN_ARRAY 52


토큰 레코드

여기에서는, 각 레코드 생성 토큰의 레코드의 포맷에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • TOKEN_NAME
  • TOKEN_STRING
  • TOKEN_INTEGER
  • TOKEN_GUID
  • TOKEN_INTEGER_LIST
  • TOKEN_FLOAT_LIST


TOKEN_NAME

가변장 레코드. 토큰의 뒤에는,name 필드에 계속되는 바이트수를 지정하는 count 값이 계속된다. 길이 count 의 ASCII 명으로 레코드가 완료한다.

필드 | 형 | 사이즈 (바이트) | 내용
token | WORD | 2 | TOKEN_NAME
count | DWORD | 4 | 바이트 단위의 name 필드의 길이
name | BYTE 배열 | count | ASCII 명


TOKEN_STRING

가변장 레코드. 토큰의 뒤에는, string 필드에 계속되는 바이트수를 지정하는 count 값이 계속된다. 길이 count 의 ASCII 캐릭터 라인에서는 레코드는 계속해, 종료 토큰에 의해 완료한다. terminator 의 선택은, 그 외로 설명하는 구문의 문제에 의해 정해진다.

필드 | 형 | 사이즈 (바이트) | 내용
token | WORD | 2 | TOKEN_STRING
count | DWORD | 4 | 바이트 단위의 string 필드의 길이
string | BYTE 배열 | count | ASCII 캐릭터 라인
terminator | DWORD | 4 | TOKEN_SEMICOLON 또는 TOKEN_COMMA


TOKEN_INTEGER

고정장 레코드. 토큰의 뒤에는, 필요한 정수값이 계속된다.

필드 | 형 | 사이즈 (바이트) | 내용
token | WORD | 2 | TOKEN_INTEGER
value | DWORD | 4 | 단일의 정수


TOKEN_GUID

고정장 레코드. 토큰의 뒤에는, OSF DCE 표준으로 정의되고 있는 4 개의 데이터 필드가 계속된다.

필드 | 형 | 사이즈 (바이트) | 내용
token | WORD | 2 | TOKEN_GUID
data1 | DWORD | 4 | UUID 데이터 필드 1
data2 | WORD | 2 | UUID 데이터 필드 2
data3 | WORD | 2 | UUID 데이터 필드 3
data4 | BYTE 배열 | 8 | UUID 데이터 필드 4


TOKEN_INTEGER_LIST

가변장 레코드. 토큰의 뒤에는, list 필드에 계속되는 정수의 수를 지정하는 count 값이 계속된다. 효율화를 위해서(때문에), 연속하는 정수의 리스트는 단일의 리스트에 합성하는 것이 바람직하다.

필드 | 형 | 사이즈 (바이트) | 내용
token | WORD | 2 | TOKEN_INTEGER_LIST
count | DWORD | 4 | list 필드의 정수의 수
list | DWORD | 4 × count | 정수의 리스트


TOKEN_FLOAT_LIST

가변장 레코드. 토큰의 뒤에는, list 필드에 계속되는 부동 소수점수(실수) 또는 배정밀도 정수의 수를 지정하는 count 값이 계속된다. 부동 소수점수(실수)값 (float 또는 double)의 사이즈는, 파일 헤더로 지정된 float 의 사이즈의 값에 의해 정해진다. 효율화를 위해서(때문에), 연속하는 TOKEN_FLOAT_LIST 는 단일의 리스트에 합성하는 것이 바람직하다.

필드 | 형 | 사이즈 (바이트) | 내용
token | WORD | 2 | TOKEN_FLOAT_LIST
count | DWORD | 4 | list 필드의 부동 소수점수(실수) 또는 배정밀도 정수의 수
list | float/double 배열 | 4 또는 8 라 count | float 또는 double 의 리스트


템플릿

템플릿에는, 다음의 구문의 정의가 있다.

template              : TOKEN_TEMPLATE name TOKEN_OBRACE
                            class_id
                            template_parts
                            TOKEN_CBRACE

template_parts        : template_members_part TOKEN_OBRACKET
                        template_option_info
                        TOKEN_CBRACKET
                      | template_members_list

template_members_part :/* 하늘 */
                      | template_members_list

template_option_info  : ellipsis
                      | template_option_list

template_members_list :    template_members
                      | template_members_list template_members

template_members      : primitive
                      | array
                      | template_reference

primitive             : primitive_type optional_name TOKEN_SEMICOLON

array                 : TOKEN_ARRAY array_data_type name dimension_list
                        TOKEN_SEMICOLON

template_reference    : name optional_name YT_SEMICOLON

primitive_type        : TOKEN_WORD
                      | TOKEN_DWORD
                      | TOKEN_FLOAT
                      | TOKEN_DOUBLE
                      | TOKEN_CHAR
                      | TOKEN_UCHAR
                      | TOKEN_SWORD
                      | TOKEN_SDWORD
                      | TOKEN_LPSTR
                      | TOKEN_UNICODE
                      | TOKEN_CSTRING

array_data_type       : primitive_type
                      | name

dimension_list        : dimension
                      | dimension_list dimension

dimension             : TOKEN_OBRACKET dimension_size TOKEN_CBRACKET

dimension_size        : TOKEN_INTEGER
                      | name

template_option_list  : template_option_part
                      | template_option_list template_option_part

template_option_part  : name optional_class_id

name                  : TOKEN_NAME

optional_name         :/* 하늘 */
                      | name

class_id              : TOKEN_GUID

optional_class_id     :/* 하늘 */
                      | class_id

ellipsis              : TOKEN_DOT TOKEN_DOT TOKEN_DOT


데이터

데이터 오브젝트에는, 다음의 구문의 정의가 있다.

object                : identifier optional_name TOKEN_OBRACE
                            optional_class_id
                            data_parts_list
                            TOKEN_CBRACE
data_parts_list       : data_part
                      | data_parts_list data_part

data_part             : data_reference
                      | object
                      | number_list
                      | float_list
                      | string_list

number_list           : TOKEN_INTEGER_LIST

float_list            : TOKEN_FLOAT_LIST

string_list           : string_list_1 list_separator

string_list_1         : string
                      | string_list_1 list_separator string

list_separator        : comma
                      | semicolon

string                : TOKEN_STRING

identifier            : name
                      | primitive_type

data_reference        : TOKEN_OBRACE name optional_class_id TOKEN_CBRACE

바이노리필드의 number_list 및 float_list 데이터에서는, TOKEN_COMMA 및 TOKEN_SEMICOLON 는 사용되지 않는 것에 주의 해야 한다. 칸마 및 세미콜론은 string_list 데이터로 사용된다. 옵션의 데이터 멤버로서 사용할 수 있는 것은 data_reference 뿐이게도 주의 해야 한다.


례

2 개의 바이너리 템플릿 정의의 예 및 바이너리 데이터 오브젝트의 예를 이하에 나타낸다. 데이터는 little endian 포맷으로 저장 되지만, 이러한 예에는 나타나지 않은 것에 주의 해야 한다.

닫은 템플릿 RGB 는 UUID {55b6d780-37ec-11d0-ab39-0020af71e433} 에 의해 식별되어 각각 float 형의 3 개의 멤버 r,g,b 를 가진다.

TOKEN_TEMPLATE, TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_OBRACE,
TOKEN_GUID, 55b6d780, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_FLOAT, TOKEN_NAME, 1, 'r', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'g', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'b', TOKEN_SEMICOLON,
TOKEN_CBRACE

닫은 템플릿 Matrix4x4 은 UUID {55b6d781-37ec-11d0-ab39-0020af71e433} 에 의해 식별되어float 형의 matrix 라는 이름의 2 차원 배열인 1 개의 멤버를 가진다.

TOKEN_TEMPLATE, TOKEN_NAME, 9, 'M', 'a', 't', 'r', 'i', 'x', '4', 'x', '4', TOKEN_OBRACE,
TOKEN_GUID, 55b6d781, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_ARRAY, TOKEN_FLOAT, TOKEN_NAME, 6, 'm', 'a', 't', 'r', 'i', 'x',
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_CBRACE

다음의 바이너리 데이터 오브젝트는, 이전에 정의한 RGB 템플릿의 인스턴스를 나타내고 있다. 이 예의 오브젝트는 blue 라는 이름으로, 그 3 개의 멤버 r,g,b 의 값은 각각 0.0, 0.0, 1.0 이다. 데이터는 little endian 포맷으로 저장 되지만, 이 예에는 나타나지 않은 것에 주의 해야 한다.

TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_NAME, 4, 'b', 'l', 'u', 'e', TOKEN_OBRACE,
TOKEN_FLOAT_LIST, 3, 0.0, 0.0, 1.0, TOKEN_CBRACE


DirectX Audio

여기에서는, Microsoft® DirectX® 를 사용해, 어플리케이션으로 사운드를 재생 및 캡춰 하는 방법에 대해 설명한다.

DirectX 외의 컴퍼넌트와 같게, DirectX Audio 는 C, C++, 및 Microsoft® Visual Basic® 로 사용할 수 있다. 이 헬프 파일에서는, C 및 C++ 에 대해 설명한다. 샘플 코드에는 C++ 의 구문을 사용한다.

DirectX Audio 의 헬프의 구성에 대해서는, 「도로지도」를 참조할것.


도로지도

DirectX Audio 에 대해서는, 이하의 주제로 설명한다.

  • DirectX Audio 의 신기능 . DirectX 8.0 의 이 컴퍼넌트의 신기능. 지금까지 Microsoft® DirectSound® 또는 Microsoft® DirectMusic® 를 사용한 경험이 있는 경우는, DirectX 7.0 으로부터 많은 변경을 하고 있기 (위해)때문에, 이 섹션을 최초로 읽는 것.
  • DirectX Audio 의 개요 . DirectX Audio 의 개요 및 어플리케이션으로 사용 가능한 기능, 오디오의 재생에 관련하는 중요한 오브젝트와 순서를 나타낸다.
  • DirectX Audio 에 대해 . 기본적인 메카니즘에 대해 자세하게 설명한다. 여기에서는, 어플리케이션으로 오디오 재생 및 캡춰를 이행 하는 방법은 설명하지 않지만, 어플리케이션 프로그래밍 인터페이스 (API)의 이해에 도움이 될 것이다.
  • DirectX Audio 의 사용법 . API 의 사용법의 가이드이다. 이 주제의 목차를 참고로 해, 특정의 정보가 필요하게 되었을 때에 대상이 되는 개소를 참조할 수 있다. 이 주제는, 레퍼런스 주제와 조합해 사용하는 것.
  • DirectX Audio 의 고도의 주제 . 주로, 특수한 어플리케이션 또는 퍼포먼스를 고도로 최적화할 필요가 있는 어플리케이션에 대해 설명한다.
  • 프로그래밍의 힌트 및 툴 . DirectX Audio 어플리케이션의 컴파일 및 디버그에 관한 다양한 정보를 제공한다.
  • DirectX Audio C++ 튜토리얼 . 기본적인 기능을 단계적으로 이행 하는 튜토리얼이다. 실천적으로 DirectX Audio 를 이해할 수가 있다.
  • DirectX Audio C++ 샘플 . 필요한 샘플 코드를 찾아내기 위한, SDK 의 샘플 어플리케이션에 대한 가이드. 기본적 기능의 이행 방법을 설명해, DirectX Audio 의 특정의 기능을 이용한 샘플을 나타낸다.
  • DirectMusic C/C++ 레퍼런스 . DirectMusic 의 헤더 파일로 선언되는 모든 API 요소에 대해 자세하게 설명한다. 여기에서는, DirectMusic 및 DirectMusic Producer 로 사용되는 파일 형식에 대해서도 설명한다.
  • DirectSound C/C++ 레퍼런스 . Dsound.h 로 선언되는 모든 API 요소에 대해 자세하게 설명한다.

DirectMusic Producer

DirectMusic Producer 는, DirectX SDK 에 포함되어 있는 강력한 오쏘링 어플리케이션이다. 이 어플리케이션을 사용해, 작곡자는 어플리케이션에 짜넣을 수가 있는 다이나믹한 뮤직 요소를 생성 할 수 있다.

어플리케이션 개발보다 사운드의 디자인에 중점을 두고 있는 경우는, 이 어플리케이션과 함께 인스톨 되는 DirectMusic Producer 헬프를 참조할것.

어플리케이션을 개발하는 경우에, 대상이 되는 머트리얼의 개요 붙어 알고 싶은 경우는, 「어레인지용의 뮤직 요소」를 참조할것.

오디오 스크립팅

작곡자나 사운드의 생성자는 DirectX Audio 의 스크립팅 기능을 사용해, 어플리케이션으로 사운드 트랙을 직접적으로 제어할 수가 있다. 스크립트 API 의 메뉴얼은, DirectMusic Producer 의 헬프에 포함되어 있다.

개요에 대해서는, 「오디오 스크립트」를 참조할것. 스크립트를 어플리케이션에 짜넣는 방법에 대해서는, 「오디오 스크립트의 사용법」을 참조할것.


DirectX Audio 의 신기능

DirectX 의 오디오 컴퍼넌트는 큰폭으로 개정되고 있다. 다양한 사운드를 재생하기 위해서, DirectMusic 와 DirectSound 의 API 의 통일이 진행되어 많은 신기능이 추가되었다.

다음의 일람은, 주된 신기능을 나타내고 있다.

1 개의 재생 메카니즘으로 웨이브 베이스와 메세지 베이스의 사운드를 통합
웨이브 파일 및 리소스를 DirectMusic 로더로 로드해, DirectMusic 퍼포먼스에 의해 재생할 수 있다. 어플리케이션으로, 웨이브 사운드를 해석 및 카피하거나 DirectSound 버퍼에 스트리밍 할 필요가 없어졌다. 웨이브 재생의 타이밍은 DirectMusic master clock에 근거하고 있어 웨이브를 음악 이벤트에 동기 시키거나 다른 세그먼트(segment)와 같게 툴로 처리할 수가 있다.

DirectSound API 도 계속해 지원 되고 있어 DirectSound 버퍼를 사용해 직접 웨이브를 재생할 수도 있다. DirectSound 는, 웨이브 캡춰 및 전이중의 API 이다.

유연성을 더해 강화된 오디오 파스 모델
이전의 버젼의 DirectMusic 에서는, 퍼포먼스 채널은 포토에 맵 되어 각 포토가 그 출력을 단일의 DirectSound 버퍼에 송신하고 있었다. 새로운 모델에서는, 세그먼트(segment)의 채널은, 퍼포먼스로부터 최종적인 출력에의 데이터 플로우를 제어하는 오디오 패스에 맵 된다. 신디사이저로부터의 출력을, 3D 포지셔닝 및 이펙트가 개별적으로 설정되어 있는 복수의 재생 버퍼에 송신할 수 있다. 오디오 패스는, 어플리케이션에 의해 동적으로 생성 하거나 세그먼트(segment)에 오쏘링 할 수가 있다.
여기의 세그먼트(segment) 상태의 제어
세그먼트(segment)의 각 재생 인스턴스는 각각 오디오 패스를 가질 수가 있어 볼륨, 빵, 핏치벤드등의 파라미터를, 각 세그먼트(segment) 상태에 대해 개개로 변경할 수 있다.
DLS2 에 근거하는 합성
DirectMusic 신디사이저는 Downloadable Sounds (DLS) Level 2 규격에 근거해, 고품질인 사운드 합성을 가능하게 하고 있다. DLS2 신디사이저의 신기능에는, 6 단계의 포락선, 음성의 계층 링, 웨이브 폼의 해방, 및 추가의 저주파수발진기 (LFO)등이 있다. 각 음성에는, 옵션의 로우 패스 공진 필터가 있다.
특수 효과
DirectX Media Object 를 사운드 버퍼에 어태치 해, 이펙트를 추가할 수가 있다. 뮤직크리바브, I3DL2 (Interactive 3-D Audio Level 2) 환경 리바브, 뒤틀림, 메아리등의 DirectX Audio 에 준비되어 있는 표준적인 이펙트 외에, 써드파티의 이펙트를 추가할 수 있다.
큐의 상세한 제어
작곡자가 세그먼트(segment)내에 세그먼트(segment)의 재생을 시작 하는 포인트를 설정해, 세그먼트(segment)가 박자 기호와의 관계를 유지할 수 있도록(듯이) 할 수가 있다. 프라이머리 세그먼트(segment)에는, 다른 세그먼트(segment)에 큐를 주는 임의의 포인트를 포함할 수가 있어 가장 가까운 소절, 박, 또는 구라두에 큐를 주는 경우에 비해 세세한 제어가 가능하다. 새로운 세그먼트(segment) 큐 플래그 DMUS_SEGF_SEGMENTEND 에 의해, 현재의 프라이머리 세그먼트(segment)의 재생이 종료했을 때에, 세그먼트(segment)를 재생할 수가 있다.
연주가 이제 곧 종료하는 것을 알리는 통지
퍼포먼스 통지 이벤트에 새로운 통지 타입 DMUS_NOTIFICATION_MUSICALMOSTEND 가 추가되었다. 이것은, 큐내의 마지막 프라이머리 세그먼트(segment)의 마지막이 가까운 일을 나타낸다. 이 통지에 의해, 어플리케이션은 새로운 세그먼트(segment)를 스케줄 할 수가 있다.
MIDI 콘트롤러 지원의 강화
커브 메세지가, RPN/NRPN 콘트롤러의 변경을 지원 하게 되었다.
세그먼트(segment)의 무한회의 반복
새로운 DMUS_SEG_REPEAT_INFINITE 플래그에 의해, 세그먼트(segment)를 무한하게 재생할 수 있다.
밴드의 다운로드 및 언로드의 간이화
간단한 메소드 호출로, 밴드를 세그먼트(segment) 오브젝트에 다운로드하거나 세그먼트(segment) 오브젝트로부터 언로드할 수가 있다.
트럭 데이터의 동적 생성
새로운 트럭 구성 및 재생 플래그에 의해, 세그먼트(segment)를 재생 또는 루프 할 때마다, 트럭을 재생성할 수가 있다. 예를 들어, 세그먼트(segment)를 재생할 때마다 새로운 코드 진행이 설정되도록(듯이) 코드 맵 트럭을 구성할 수 있다.
오디오 스크립팅
작곡자나 사운드의 생성자는, 스크립트를 사용하는 것에 의해, 연주를 세세하게 제어할 수가 있다. 어플리케이션은 재생의 상세를 처리하는 대신에, 스크립트를 호출한다. 예를 들어, 게임 이벤트가 스크립트 함수의 방아쇠가 된다. 스크립트의 생성자는, 이 함수를 변경하는 것에 의해, 게임에 대한 사운드 트랙의 응답을 용이하게 변경할 수 있다.
트럭의 실행 시제기능의 향상
어플리케이션으로, 재생 및 파라미터의 제어를 무효로 하도록(듯이), 개개의 트럭 구성을 설정할 수 있다. 트럭은, 뮤직 타임은 아니고, 클락 타임에 연주되도록(듯이) 구성할 수 있다. 자기 제어 세그먼트(segment)내의 트럭은, 제어 또는 프라이머리 세그먼트(segment)내의 파라미터 트럭을 오버라이드(override) 하도록(듯이) 구성할 수 있다.
컨테이너 오브젝트
DirectMusic Producer 프로젝트의 모든 컴퍼넌트를 단일의 파일에 보존할 수 있어 모든 오브젝트를 용이하게 검색 및 로드할 수가 있다. 컨테이너를 세그먼트(segment)에 묻어, 세그먼트(segment)의 재생에 필요한 것을 모두 세그먼트(segment)내에 보존할 수도 있다.
가사 트럭
가사 트럭을 포함한 세그먼트(segment)에 의해, 타임 스탬프가 지정된 텍스트가 퍼포먼스에 송신된다.
캐쉬 관리 기능의 향상
어플리케이션으로, 다른 오브젝트에 의해 로드 된 사용되어 있지 않은 오브젝트를 용이하게 해방할 수 있게 되었다.


DirectX Audio 의 개요

  • DirectX Audio 의 기능
  • DirectX Audio 입문


DirectX Audio 의 기능

DirectX Audio 에는, 사운드의 재생 이외에도 다양한 기능이 있다. 하드웨어 가속화, 다운로다브르사운드 (DLS ), DirectX Media Object (DMO ), 및 고도의 3D 포지셔닝 이펙트를 활용하는 다이나믹 사운드 트랙을 이행하기 위한 시스템을 제공한다.

어플리케이션으로 DirectMusic 및 DirectSound 인터페이스를 사용하는 것에 의해, 다음과 같은 처리를 실시할 수가 있다.

  • MIDI, 웨이브, 또는 DirectMusic Producer 런타임 형식의 파일 또는 리소스로부터 사운드를 로드해 재생한다.
  • 복수의 소스를 동시에 재생한다.
  • 높은 정밀도로 뮤직 이벤트의 타이밍을 스케줄 한다.
  • 템포의 변경, 패치의 변경, 및 그 외의 MIDI 이벤트를 프로그램에 의해 송신한다.
  • 다운로다브르사운드를 사용한다. DLS 신디사이저를 사용하는 것에 의해, 어플리케이션은, 메세지 베이스의 곡이 어느 컴퓨터로도 똑같이 재생되는 것을 보증할 수 있다. 어플리케이션은 다양한 음색을 재생할 수 있어 개개의 노트야 및 velocity에 응해 독자적인 소리를 생성할 수 있다.
  • 3D 환경에서 사운드를 특정한다.
  • 피치의 변경, 리바브, 및 그 외의 이펙트를 간단하게 사운드에 적용한다.
  • 16 을 넘는 MIDI 채널을 사용한다. DirectX Audio 는 채널수 16 의 제약을 타파해, 임의의 수의 음성을 신디사이저의 제한까지, 동시에 연주하는 것을 가능하게 했다.
  • 세그먼트(segment)를 다른 오디오 패스로 재생해, 이펙트 또는 공간적인 확대를 각 세그먼트(segment)에 개개에 적용한다.
  • MIDI 데이터를 캡춰 하거나 있는 포토로부터 다른 포토에 스트리밍 ("전송") 한다.
  • 마이크 또는 그 외의 입력으로부터 웨이브 사운드를 캡춰 한다.

DirectMusic Producer 또는 유사하는 어플리케이션의 원시 파일을 사용하는 경우는, 한층 더 다음과 같은 처리가 가능하다.

  • 다른 바리에이션을 선택하거나 코드 진행을 변경하는 것에 의해, 실행시에 재생의 다양한 면을 제어한다.
  • 반복할 때마다 약간 다른 곡을 재생한다.
  • 웨이브 사운드에 바리에이션을 붙여 재생한다.
  • 퍼포먼스 채널을 오디오 패스에 맵 하는 것에 의해, 동일 세그먼트(segment)내에서, 부분에 의해 다른 이펙트를 적용한다.
  • 알고리즘에 의해 생성하는 것이 아니라, 작곡자가 지정한 컴퍼넌트에 근거해, 실행시에 완전히 새로운 곡을 생성 한다.
  • 기존의 곡간의 트란지션을 동적으로 어레인지 한다.
  • 트란지션, 모티프, 및 사운드 이펙트에 큐를 내, 퍼포먼스내의 지정한 리듬 포인트로 재생한다.

이러한 기능은, 주류가 되고 있는 어플리케이션으로 일반적으로 사용되고 있는 기능이다. DirectX Audio 는 기본적인 태스크를 용이하게 사용할 수 있도록(듯이) 설계되고 있지만, 필요에 따라서 하위 레벨의 액세스도 제공되고 있다. 또, 확장도 가능하다. 특수한 어플리케이션에서는, 다음과 같이, 사실상 오디오 패스의 모든 단계에서 새로운 오브젝트를 이행 할 수 있다.

  • 새로운 형식 또는 독자적인 형식의 데이터를 해석하는 로더.
  • 임의의 종류의 순서화 된 데이터를 포함한 트럭.
  • 메세지를 처리하는 툴. 예를 들어, 노트를 도중에 처리해 전조를 적용하거나 세그먼트(segment) 파일에 파묻힌 가사를 표시하는 메세지를 처리한다.
  • 커스텀 시퀀서.
  • 커스텀 신디사이저.
  • 이펙트 필터.

DirectX Audio 에는 DirectMusic Producer 도 포함되어 있다. 이 어플리케이션에 의해, 작곡자는 DirectMusic 의 기능을 최대한으로 이용하기 위한 DLS 콜렉션, 코드 맵, 스타일, 및 세그먼트(segment)를 생성 할 수 있다. 또, DirectMusic Producer 에 의해, 복수의 타임 스탬프를 가지는 웨이브를 저장 하는, 재생 가능한 세그먼트(segment)를 생성 할 수 있다. 이러한 웨이브는, 압축 형식에서도 비압축 형식에서도 사용할 수 있어 실행시에 스트리밍 하는지, 또는 메모리내에 전체를 저장 할 수 있다.

어플리케이션을 개발하는 경우, 직접 DirectMusic Producer 를 사용할 것은 없을지도 모르지만, 그 기능을 넓게 이해해 두는 것은, 사운드의 디자인 팀과의 작업을 효율적으로 진행하는데 있어서 중요하다. 어플리케이션 설계자의 관점으로부터 본 개요에 대해서는, 「어레인지용의 뮤직 요소」를 참조할것. 상세한 것에 대하여는, DirectMusic Producer 의 메뉴얼을 참조할것.

DirectX Audio 는, Microsoft® Windows® 95, Microsoft Windows 98, Microsoft Windows Me, 및 Microsoft Windows 2000 에 대해, 모든 기능을 발휘할 수 있다. 다만, 하드웨어 신디사이저를 이용할 수 있는 것은, Windows 2000 및 Windows 98 Second Edition 이후 뿐인다.


DirectX Audio 입문

처음으로 DirectX Audio 어플리케이션을 생성 하는 경우, 복잡한 설정은 불필요하다. 다만, 현재의 버젼의 DirectX 가 인스톨 되고 있어 개발 환경에서 헤더 파일에의 패스가 설정되어 있을 필요가 있다. \lib 폴더내의 DirectX 라이브러리 파일에 링크할 수 있을 필요도 있다. 소프트웨어 신디사이저에 의해 사용되는, 필요한 DLL 및 디폴트의 DLS 콜렉션은, SDK 의 일부로서 시스템 디렉토리에 인스톨 된다.

이외에 필요한 것은, 사운드 카드, 스피커 또는 헤드폰, 및 사운드 뿐이다. 이하의 몇개의 사운드를 사용할 수 있다.

  • MIDI (. mid) 파일.


DirectX Audio 의 기본적인 개념

여기에서는, DirectX Audio 의 기본적인 개념 및 그것을 이행 하는 오브젝트를 소개한다.

DirectX 는 컴퍼넌트 오브젝트 모델 (COM)에 근거하고 있어 모든 기능은 오브젝트에 의해 실행된다. 또, 소스 데이터는 오브젝트에 캡슐화된다.

여기서 설명하는 오브젝트는, DirectSound 만을 사용하는 어플리케이션 이외의, 모든 DirectX Audio 어플리케이션에 공개된다. 이 밖에도 많은 오브젝트가 내부에서 사용되고 있어 고도의 어플리케이션에 의해 액세스 할 수가 있지만, 여기에서는 설명하지 않는다.

설명하는 주제는, 다음과 같다.

  • 로더
  • 세그먼트(segment)와 세그먼트(segment) 상태
  • 퍼포먼스
  • 메세지
  • 퍼포먼스 채널
  • DLS 신디사이저
  • 음색과 다운로드
  • 오디오 패스 및 버퍼


로더

로더 (IDirectMusicLoader8 )는 다른 오브젝트를 취득하는 오브젝트이다. 일반적으로, DirectX Audio 어플리케이션으로 최초로 생성 되는 오브젝트의 1 개이다. 로더는, DirectMusic 세그먼트(segment) 파일,DLS 콜렉션, MIDI 파일, 단청의 및 스테레오 양쪽 모두의 웨이브 파일 등, 모든 오디오 컨텐츠의 로드에 사용된다. 또, 리소스에 저장 되고 있는 데이터도 로드할 수 있다.

파일 또는 리소스로부터의 데이터를 캡슐화하는 오브젝트는 모두 IDirectMusicObject8 인터페이스를 지원 하고 있다. 로더는 이 인터페이스를 취득해, 이것을 사용해 어플리케이션내의 오브젝트에 데이터를 스트리밍 하는 처리를 시작 한다. 데이터 오브젝트는,IPersistStream 의 이행에 의해 그 자체를 해석해, 전체적인 로드 처리는 자동적으로 실행된다. 필요한 처리는, 오브젝트의 기술을,IDirectMusicSegment8 등이 필요한 인터페이스의 요구와 함께 로더에 건네주는 것 뿐이다.


세그먼트(segment)와 세그먼트(segment) 상태

세그먼트(segment)는, 순서화 된 사운드 데이터를 캡슐화하는 오브젝트이다. 데이터에는, MIDI 순서, 웨이브, DirectMusic Producer 의 세그먼트(segment) 파일의 정보의 콜렉션, 또는 실행시에 복수의 컴퍼넌트로부터 어레인지 되는 뮤직이 있다. 일반적으로, 세그먼트(segment)는, 1 곡의 뮤직 또는 1 개의 단위로서 재생되는 그 외의 사운드이다.

세그먼트(segment)는,프라이머리 세그먼트(segment)또는세칸다리세그먼트로서 재생할 수 있다. 프라이머리 세그먼트(segment)는, 한 번에 1 개(살)만 연주할 수 있다. 세칸다리세그먼트는, 일반적으로, 프라이머리 세그먼트(segment)에 거듭해 재생되는 짧은 모티프 또는 사운드 이펙트이다.

MIDI 또는 웨이브 파일로서 생성된 세그먼트(segment)는, 어플리케이션으로 특수한 처리를 하지 않는 한, 언제나 똑같이 재생된다. 한편, DirectMusic Producer 로 오쏘링 된 세그먼트(segment)에는, 다른 뮤직 패턴이나, 세그먼트(segment)를 재생할 때마다 바리에이션을 가능하게 하는 그 외의 정보를 포함할 수가 있다.

세그먼트(segment)에서는, 웨이브, 패턴, 코드 변경, 밴드 변경, 템포 변경 등, 다른 종류의 데이터를 조합할 수가 있다. 각종의 데이터는 트럭 오브젝트에 캡슐화된다. C++ 로 생성 된 어플리케이션에서는, 개개의 트럭에 액세스 할 수 있지만, 대부분의 경우 그 필요는 없다. 또 세그먼트(segment)는, 특수 효과 등, 그 세그먼트(segment)를 재생하는 오디오 패스에 관한 정보도 저장 할 수 있다.

DirectMusic Producer 의 세그먼트(segment)에는, 다른 로드 가능한 뮤직 컴퍼넌트에의 참조를 포함할 수도 있다. 예를 들어, 어느 밴드를 사용해 생성 된 세그먼트(segment)로부터 그 밴드 오브젝트를 취득할 수 있다.

세그먼트(segment)를 재생할 때마다, 세그먼트(segment) 상태 오브젝트가 생성 된다. 어플리케이션에서는, 이 오브젝트를 사용해, 재생 상태 및 재생중의 세그먼트(segment)의 인스턴스의 오디오 패스에 관한 정보를 취득할 수 있다.


퍼포먼스

퍼포먼스 오브젝트는, 소스로부터 신디사이저까지의 데이터 플로우를 관리한다. 보통, 어플리케이션은 퍼포먼스를 1 개만 가진다.

퍼포먼스는, 타이밍, 데이터 채널과 오디오 패스에의 매핑, 메세지의 루팅, 툴 관리, 통지, 및 그 외의 중요한 태스크를 처리한다.


메세지

오디오 데이터는, 메세지의 형태로 퍼포먼스에게 건네진다. 퍼포먼스 메세지는 MIDI 메세지를 닮아 있지만, 보다 많은, 보다 다양한 정보를 포함하고 있다. 메세지에는, 노트, 웨이브, 또는 콘트롤러의 변경에 관한 정보를 포함할 수가 있다. 또, 가사를 표시하기 위한 텍스트를 포함할 수도 있다.

많은 어플리케이션에서는, 세그먼트(segment)의 재생중에 트럭에 의해 생성되는 메세지를 직접 처리하지 않는다. 다만, 어플리케이션으로 퍼포먼스에 메세지를 삽입하거나 이행 하고 있는 툴에 의해 메세지를 도중에 처리하는 것은 가능하다.

또, 통지에는 메세지도 사용된다. 어플리케이션은, 퍼포먼스가 특정의 포인트에 이를 때마다 이벤트가 통지되도록(듯이) 요구할 수 있다. 예를 들어, 음악의 박자 마다 이벤트를 통지할 수 있다. 퍼포먼스 메세지에는 그 이벤트에 관한 정보가 포함되어 있다.


퍼포먼스 채널

재생중의 사운드는 1 개 또는 복수의 파트로 구성된다. 파트에는 MIDI 채널, DirectMusic Producer 세그먼트(segment)의 파트, 또는 웨이브가 있다. 보통, 파트는 1 개의 악기에 대응한다.

퍼포먼스 채널은, 파트와 오디오 패스와의 사이의 루트이다. 파트에 관한 정보를 포함한 각 메세지는, 메세지가 올바르고 루팅 되도록(듯이) 파트의 퍼포먼스 채널도 지정한다.

퍼포먼스 채널은 MIDI 채널에 자주(잘) 비슷하지만, 종래의 MIDI 재생은 16 채널에 제한되고 있던 것에 대해, 퍼포먼스 채널에서는 실질상 무제한하다.


DLS 신디사이저

MIDI 노트 등, 웨이브 형식으로 되어 있지 않은 데이터를 사운드 카드로 재생하려면 , 웨이브 형식으로 변환할 필요가 있다. 이 변환은, 신디사이저에 의해 행해진다.

DirectX Audio 는 일부의 operating system로 기본적인 MIDI 합성을 지원 하고 있지만, 많은 어플리케이션은 Downloadable Sounds (DLS) Level 2 규격을 이행 하는 신디사이저를 사용한다. 적절한 하드웨어 신디사이저가 없는 경우는, Microsoft 의 소프트웨어 신디사이저가 사용된다.

신디사이저는, 웨이브 샘플에 근거해 사운드를 생성한다. 이것에 의해, 모든 종류의 사운드에 가세해 고도의 틴바도 생성할 수 있다.

주 DirectX 7 인터페이스와 함께 사용되는 DLS Level 1 신디사이저에는, 리바브 기능이 포함되어 있어 디폴트로 유효하게 되어 있다. Waves TrueVerb 리바브테크노로지가 Microsoft 에 라이센스 되고 있어 SimpleVerb 로서 이행 되고 있다.

DirectX 8.0 과 함께 사용되는 DLS Level 2 신디사이저에는, 편입의 리바브 기능은 포함되지 않았다. 그 대신해, 리바브는 DMO 로서 이행 되고 있다. 이 때문에 Waves MaxxVerb 가 Microsoft 에 라이센스 되고 있다.


음색과 다운로드

음색을 재생하기 위해서, 신디사이저는 그 음색이 어떻게 들릴까에 대한 정보를 가지고 있을 필요가 있다. 이 정보는, 웨이브 샘플 및 아티큘레이션 데이터로 구성되어DLS 콜렉션에 저장 된다. 음색의 데이터는, 다운로드하는 것에 의해 신디사이저로 사용할 수 있게 된다.

보통, 1 개의 음색의 다양한 노트는, 같은 1 개의 샘플에 각 노트의 피치를 할당하는 것에 의해 생성된다. 다만, DLS Level 2 를 사용 하면, 다른 샘플 또는 샘플의 배합해에 근거해 각 노트를 생성할 수 있다. 노트의 velocity를 방아쇠로서 기본의 음색이 다른 샘플을 사용할 수도 있다.

디폴트에서는, Microsoft 의 소프트웨어 신디사이저는 Roland GM/GS 콜렉션의 DLS 데이터를 이용한다. 디폴트의 콜렉션에는, General MIDI 규격으로 정의되고 있는 128 의 음색의 DLS 데이터가 포함되어 있다. 커스텀 콜렉션에는, 임의의 종류의 음색을 포함할 수가 있다. 음색의 웨이브 샘플은 악기의 음색에 근거하고 있을 필요는 없다. 사운드 이펙트, 연설의 일부, 생성 끝난 완전한 소절 등, 녹음된 임의의 사운드를 사용할 수 있다.

필요한 데이터는 디폴트의 콜렉션에 포함되어 있는지, 세그먼트(segment)에 관련지을 수 있었던 밴드 오브젝트에 의해 참조되므로, 대부분의 어플리케이션에서는 직접 콜렉션에 액세스 할 필요가 없다. 밴드는, 음색과 퍼포먼스 채널에 맵 된 설정과의 세트이다. 밴드의 음색을 사용하기 전에 다운로드되도록(듯이) 하려면 , 몇개의 방법이 있다.

주 Roland GM/GS Sound Set 를 수정할 수 없다. 「법적 정보」의 「저작권에 관한 주의」를 참조할것.

웨이브 파일 및 리소스도, 재생하려면 신디사이저에 다운로드할 필요가 있다.


오디오 패스 및 버퍼

각 DirectMusic 세그먼트(segment)는, 퍼포먼스로부터 신디사이저에의 사운드의 플로우를 제어하는 오디오 패스상에서 재생되어 다음에 DirectSound 버퍼로 이펙트가 적용되어 마지막에 프라이머리 버퍼로 최종적인 출력이 믹싱 된다.

주 여기서 설명되고 있는 버퍼는, 신디사이저로부터 송신된 후의 PCM 데이터의 스트리밍 및 처리에 사용되어IDirectSoundBuffer8 인터페이스를 지원 한다. IDirectMusicBuffer8 인터페이스에 의해 나타내지는 다른 종류의 버퍼는, 신디사이저에의 메세지 데이터를 순서화하기 위해서(때문에) 사용된다. 2 번째의 종류의 버퍼는, DirectMusic 의 퍼포먼스에 의해 관리되므로, 대부분의 어플리케이션에서는 액세스 할 필요는 없다.

어플리케이션은 표준 오디오 패스를 생성 해, 그 오디오 패스로 세그먼트(segment)를 재생할 수 있다. 예를 들어, 뮤직크리바브가 설정된 버퍼로 MIDI 파일을 재생하는 오디오 패스와 3D 컨트롤이 설정된 버퍼로 웨이브 파일을 재생하는 오디오 패스를 어플리케이션으로 생성 할 수 있다.

DirectMusic Producer 에서는, 한층 더 고도의 오디오 패스의 구성으로부터 세그먼트(segment)를 생성 할 수 있다. 예를 들어, 표준 이외의 구성으로, 세그먼트(segment)내의 파트를 다른 DirectSound 버퍼에 송신해, 다른 이펙트를 적용할 수가 있다.

오디오 패스는, 데이터가 스트리밍 되는 일련의 오브젝트라고 볼 수가 있다. 어플리케이션은 이러한 오브젝트의 모두에게 액세스 할 수 있다. 예를 들어, 버퍼 오브젝트를 취득해 음원의 3D 프로퍼티를 설정하거나 이펙트 DMO 를 취득해 이펙트의 파라미터를 변경할 수 있다.


사운드 재생의 기본적인 순서

「DirectX Audio 의 기본적인 개념」으로 설명되고 있는 기본적인 항목을 이해하면(자), 다음에 어플리케이션으로 기본적인 사운드 트랙을 이행 한다. 간단한 순서를 학습한 후, 필요에 따라서 사운드 트랙을 세세하게 제어하기 위한 API 에 대해 학습할 수가 있다.

여기에서는, 코딩의 상세하게는 접하지 않고 , 필요한 순서의 개요에 대해 설명한다. 샘플 코드에 대해서는, 「튜토리얼 1 : 오디오 파일의 재생」을 참조할것.

사운드를 생성하려면 , 어플리케이션으로 다음의 처리를 실시할 필요가 있다.

1. COM 의 초기화

DirectMusic 오브젝트를 생성하기 위한 헬퍼 함수는 없기 때문에,CoInitializeEx 를 호출해 COM 를 초기화할 필요가 있다.

2. 퍼포먼스의 생성과 초기화

대부분의 어플리케이션은 퍼포먼스 오브젝트를 1 개만 사용한다. 퍼포먼스 오브젝트는, CoCreateInstance 를 호출해,IDirectMusicPerformance8 인터페이스를 취득하는 것에 의해 생성 할 수 있다. 다음에,IDirectMusicPerformance8::InitAudio 를 호출한다. 이 메소드에 의해, 디폴트의 오디오 패스를 설정할 수 있다.

3. 로더의 생성

CoCreateInstance 를 사용해,IDirectMusicLoader8 인터페이스를 취득한다. 이 처리는 한 번만 실시할 필요가 있어, 어플리케이션을 종료할 때까지 같은 로더 오브젝트를 사용할 필요가 있다.

4. 세그먼트(segment)의 로드

로더가 데이터 파일을 찾아낼 수가 있도록(듯이),IDirectMusicLoader8::SetSearchDirectory 를 호출한다. 다음에,IDirectMusicLoader8::GetObject 를 호출해 파일 또는 리소스로부터 세그먼트(segment)를 로드해, 그 IDirectMusicSegment8 인터페이스를 취득한다.

5. 밴드의 다운로드

DLS 데이터를 신디사이저에 다운로드 하면, 음색을 재생할 수 있다. 웨이브 파일도 다운로드할 필요가 있다. 가장 간단한 방법은,IDirectMusicSegment8::Download 를 호출하는 방법이다.

6. 세그먼트(segment)의 재생

세그먼트(segment) 포인터를 IDirectMusicPerformance8::PlaySegmentEx 에 건네준다.

이 처리의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 오디오 데이터의 로드
  • 사운드의 재생

주 DirectSound 인터페이스만을 사용해 웨이브 사운드를 재생할 수도 있다. 다만, 이러한 처리를 실시하려면 , 스스로 데이터 소스를 해석해, 버퍼에의 데이터의 스트리밍을 처리할 필요가 있다. 상세한 것에 대하여는, 「DirectSound 에서의 웨이브의 재생」을 참조할것.


DirectX Audio 프로젝트의 생성

프로젝트에는, DirectMusic 의 퍼포먼스 계층의 선언을 포함한 Dmusici.h 헤더 파일을 인클루드 할 필요가 있다. 이 파일을 인클루드 하면, 3 개(살)의 중요한 헤더도 인클루드 된다.

  • Dmusicc.h:DirectMusic 의 코어 계층의 선언
  • Dmerr.h:DirectMusic 의 반환값
  • Dsound.h:DirectSound API

Dmusicf.h 에는 파일 구조 및 정의가 포함된다. 이 헤더 파일은, 파일을 직접 조작하거나 DirectMusic 에 짜넣어지고 있는 로더에 전혀 의존하지 않는, 뮤직 authoring tool등의 어플리케이션 에 대해서만 필요하다.

Dmksctrl.h 에는, 포토 프로퍼티의 설정으로 사용되는 IKsControl 인터페이스의 선언이 포함되어 있다. Ksproxy.h 및 Ks.h 파일이 있는 경우, 이 파일은 필요없다.

Dmplugin.h 에는,IDirectMusicTool8 및 IDirectMusicTrack8 인터페이스의 선언이 포함된다. 이러한 인터페이스는, 특수한 메세지 처리 툴이나 트럭 타입을 필요로 하는 고도의 어플리케이션용의 애드 온(add-on)로 이행 된다. 대부분의 어플리케이션은, DirectMusic API 의 이 부분을 사용하지 않는다.

DirectSound API 를 직접 사용해,DirectSoundCreate8 등의 헬퍼 함수를 사용하는 경우는, Dsound.lib 에 링크해, 라이브러리 검색 패스에 적절한 폴더를 포함할 필요가 있다.

또, 어플리케이션이 DirectX Audio 로 사용되는 GUID 에 액세스 할 수 있도록(듯이) 주의한다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.

DirectX Audio 는, Windows 32 비트 operating system의 multi-thread 기능을 사용한다. multi-thread를 이용하는 것에 의해, 어플리케이션이 다른 태스크를 실행하고 있는 동안에, DirectX 는 백그라운드에서 음악의 생성, 처리, 및 합성을 실시할 수가 있다. multi-thread를 염두에 두어, 프로젝트를 개발할 필요가 있다. 적어도, multi-thread 라이브러리와 링크하는 것.


DirectX Audio 에 대해

여기에서는, DirectMusic 및 DirectSound API 의 상세하게는 접하지 않고, DirectX Audio 의 기본적인 처리에 대해 설명한다. 「DirectX Audio 의 기본적인 개념」으로 나타나고 있는 개념의 이해가 깊어지는 것을 목적으로 하고 있다. API 의 사용법에 대해서는, 「DirectX Audio 의 사용법」을 참조할것.

설명하는 주제는, 다음과 같다.

  • DirectSound 과 DirectMusic
  • 오디오 데이터의 흐름의 개요
  • 어레인지용의 뮤직 요소
  • 재생중의 음악의 변화
  • 뮤직값과 MIDI 노트
  • 다운로다브르사운드
  • 오디오 스크립트


DirectSound 과 DirectMusic

이전의 버젼의 DirectX 에서는, 2 개의 독립한 컴퍼넌트로 오디오 기능을 제공하고 있었다. DirectSound 과 DirectMusic 이다. DirectSound 는 디지털 샘플 (웨이브)을 재생 및 캡춰하기 위한의 것으로, DirectMusic 는 단순한 MIDI 파일로부터, DirectMusic Producer 로 생성 되는 뮤직 세그먼트(segment)까지, 다양한 메세지 베이스의 데이터를 재생하기 위한의 것이다. DirectMusic 는,DLS 를 사용하는 것에 의해 음악 이외의 사운드 이펙트를 재생할 수 있었지만, 이전에는 그 중점은 음악의 재생 기능에 놓여져 있었다.

DirectX 8 에서는, DirectMusic 인터페이스가 모든 사운드의 로드 및 재생의 주요한 메카니즘이다. 사운드가 웨이브 포맷, MIDI 포맷, DirectMusic Producer 포맷, 또는 애드 온(add-on) 로더나 툴로 사용 가능한 임의의 형식의 어느 파일 또는 리소스로서 생성 되고 있을까는 관계없다.

어플리케이션에서는 웨이브의 재생에 DirectSound 인터페이스를 사용할 수가 있어 웨이브 캡춰를 위한 API 로서 DirectSoundCapture 가 남아 있다. 다만, 대부분의 어플리케이션에서는, DirectSound 은 DirectMusic 신디사이저로부터 다운 스트림의 처리를 실시한다. 신디사이저로부터의 출력을 이펙트 필터에 루팅 해, 3D 이펙트를 적용해, 데이터를 출력 디바이스에 스트리밍 하기 전의 최종적인 믹싱을 실시한다.

이전에 DirectSound 를 사용하고 있었을 경우는, 웨이브의 로드 및 재생을 DirectMusic 인터페이스로 전환하는 것에 의해, 다음과 같은 이점이 있다.

  • 파일이나 리소스를 해석할 필요가 없다. 이 처리는 DirectMusic 로더에 의해 행해진다.
  • DirectSound 로 지원되어 있지 않은 웨이브 포맷에 대해서는, 자동적으로 Windows 오디오 압축 매니저 (ACM)가 사용된다.
  • 데이터의 자동적인 스트리밍. 수동으로 버퍼를 생성 하거나 읽고 쓰기 포인터를 기록할 필요가 없다.
  • 타이밍 제어의 향상. DirectMusic master clock를 사용해 정확하게 사운드를 스케줄 가능할 뿐만 아니라, 사운드 이펙트와 음악을 용이하게 동기화할 수 있다.
  • 사운드의 복수의 인스턴스를 용이하게 관리할 수 있다.

DirectMusic Producer 파일에 짜넣어지는 웨이브에는, 한층 더 몇개의 이점이 있다. 포락선등의 DLS 아테이큐레이션에페크트를 웨이브에 추가할 수 있다. 세그먼트(segment)에 복수의 바리에이션의 웨이브를 포함해, 재생에 랜덤인 요소를 더할 수가 있다.

이러한 이점은, DirectSound 에 의해 제공되는 하위 레벨의 제어가 없어지는 것을 의미하지 않는다. DirectMusic API 에 의해, 오디오 패스의 임의의 오브젝트에 액세스 할 수 있다. 기존의 버퍼의 인터페이스를 취득하고 싶은 경우는, 용이하게 취득할 수 있다. 필터나 이펙트를 추가하기 위해서, DirectSound API 의 모든 신기능을 이용할 수도 있다.


오디오 데이터의 흐름의 개요

일반적으로, DirectX Audio 어플리케이션은, 다음에 나타내는 것 같은 1 개(살) 또는 복수의 소스로부터 뮤직 데이터를 취득한다.

  • MIDI 파일
  • 웨이브 파일
  • DirectMusic Producer 또는 유사한 어플리케이션으로 생성 된 세그먼트(segment) 파일
  • DirectMusic Producer 등의 어플리케이션으로 오쏘링 되어 작곡가 오브젝트에 의해 완전하게 어레인지 된 컴퍼넌트 파일

주 이러한 데이터 소스는, 개별의 파일은 아니고, 리소스로서 어플리케이션에 저장 할 수가 있다.

이러한 소스로부터의 데이터는, 세그먼트(segment) 오브젝트에 캡슐화된다. 각 세그먼트(segment) 오브젝트는, 1 개의 소스로부터의 데이터를 나타낸다. 퍼포먼스가 있는 시점에서는, 1 개의 프라이머리 세그먼트(segment)와 임의의 수의 세칸다리세그먼트를 재생할 수 있다. 원시 파일은 혼재시킬 수가 있다. 예를 들어, 웨이브 파일에 근거하는 세칸다리세그먼트를, 오쏘링 된 세그먼트(segment) 파일과 함께 연주할 수가 있다.

1 개의 세그먼트(segment)에는 1 개 이상의 트럭이 포함되어 각각이 노트나 템포의 변경 등, 특정의 종류의 타임 데이터를 포함하고 있다. 대부분의 트럭은, 세그먼트(segment)가 퍼포먼스에 의해 재생될 때, 타임 스탬프 메세지를 생성한다. 일부의 트럭은, 퍼포먼스로부터 문의가 있었을 때에, 데이터만을 제공한다.

우선, 퍼포먼스는, 어플리케이션이 정의한 툴에 메세지를 디스팟치 한다. 그러한 툴은 세그먼트(segment) 툴 그래프에 그룹화 된다. 세그먼트(segment) 툴 그래프는, 특정의 세그먼트(segment)로부터의 메세지, 그 오디오 패스로 재생되는 모든 세그먼트(segment)로부터의 메세지의 오디오 파스퇴르 그래프, 모든 세그먼트(segment)로부터의 메세지를 수신하는 퍼포먼스 툴 그래프만을 처리한다. 툴로 메세지를 변경해 건네주거나 삭제하거나 새로운 메세지를 송신할 수가 있다.

최종적으로, 메세지는 출력 툴에 도달한다. 출력 툴로, 데이터는 MIDI 포맷에 변환되고 나서 신디사이저에게 건네진다. 채널 고유의 MIDI 메세지는, 신디사이저의 적절한 채널 그룹에 전송 된다. 신디사이저는 사운드 웨이브를 생성 해, 세면대로 불리는 디바이스에 스트리밍 한다. 세면대는, 버스를 개입시킨 DirectSound 버퍼에의 데이터의 전달을 관리한다.

버퍼에는, 이하의 3 개의 종류가 있다.

  • 세면대 인 버퍼는, 세면대가 데이터를 스트리밍 하는 DirectSound 의 세칸다리밧파이다. 이 버퍼는, 필요에 따라서, 데이터 형식을 프라이머리 버퍼의 데이터 형식으로 변환해, 어플리케이션이 빵, 볼륨, 3D 공간의 퍼져, 및 그 외의 프로퍼티를 제어할 수 있도록(듯이) 한다. 또, 이펙트 모듈을 개입시켜 데이터를 건네주어, 리바브나 메아리등의 이펙트를 추가할 수도 있다. 생성된 웨이브 폼은, 프라이머리 버퍼에 직접 건네받는지, 1 개(살) 이상의 믹스 인 버퍼에게 건네진다.
  • 믹스 인 버퍼는, 다른 버퍼로부터 데이터를 받아, 이펙트를 적용해, 웨이브 폼을 믹싱 한다. 이 버퍼를 사용해, 글로벌 이펙트를 적용할 수 있다. 데이터를 믹스 인 버퍼에 송신하는 것에 의해 얻을 수 있는 이펙트를센드라고 부른다.
  • 프라이머리 버퍼는, 모든 데이터의 최종적인 믹싱을 실시해, 렌더링 디바이스에 건네준다.

주 어플리케이션에서는, DirectMusic 의 퍼포먼스의 일부인 세칸다리밧파를 개입시켜 데이터를 스트리밍 할 필요는 없다. 어플리케이션에서는, 이펙트를 추가하거나 프로퍼티를 변경하기 위해서, 버퍼 오브젝트를 취득할 수 있지만, DirectSound API 를 사용해 웨이브 사운드를 재생하는 경우와 같이, 버퍼를 잠그어 기입할 수 없다.

다음의 그림은, 파일로부터 스피커에의 데이터 플로우의 개략도이다. 복수의 세그먼트(segment)를 동시에 재생할 수 있지만, 여기에서는 1 개의 세그먼트(segment)만이 나타나고 있다. 세그먼트(segment)는, 4 개의 소스의 몇개의 미카등 데이타를 뽑기 시작한다. 사용할 수 있는 소스는, 웨이브 파일, MIDI 파일, DirectMusic Producer 로 생성 한 세그먼트(segment) 파일, 및 작곡가 오브젝트에 의해 결합된 컴퍼넌트 파일의 언젠가이다.

주 어느 경우도, 파일은 아니고, 리소스의 데이터를 사용할 수 있다.

퍼포먼스에 있어서의 메세지의 흐름을 상세하게 확인하려면 , 「DirectMusic 메세지의 사용법」을 참조할것.

이 그림에 나타나고 있는 프로세스의 이행 방법에 대해서는, 「오디오 데이터의 로드」 및 「사운드의 재생」을 참조할것.


어레인지용의 뮤직 요소

DirectX Audio 를 최대한으로 활용 하면, MIDI 파일이나 웨이브 파일의 재생 이외의 처리도 실시할 수가 있다. DirectMusic Producer 등의 어플리케이션으로 오쏘링 된 뮤직 요소를 이용해, 다양한 방법으로 변경 또는 조작할 수 있는 퍼포먼스를 생성 할 수 있다.

주 이 메뉴얼에서는, DirectMusic 의 작곡가 오브젝트와의 혼동을 피하기 위해서(때문에), 뮤직 요소를 생성 하는 인간의 작곡가 (작곡자)를 작가라고 표현한다. 같이 뮤직 요소는, 작곡은 아니고, 오쏘링 하면 말한다.

이하에 나타내는 이러한 요소의 간단한 설명과 그 오쏘링 방법은, 어플리케이션 개발자가 퍼포먼스로 사용되는 머트리얼을 이해할 수 있도록(듯이)하기 위한의 것이다. 상세한 것에 대하여는, DirectMusic Producer 의 메뉴얼을 참조할것. 이러한 요소를 어플리케이션에 짜넣는 방법에 대해서는, 「어레인지 요소의 사용법」을 참조할것.

다음의 어레인지 요소에 대해 설명한다.

  • 스타일
  • 코드 맵
  • 스타일 베이스의 세그먼트(segment)
  • MIDI 베이스의 세그먼트(segment)
  • 템플릿
  • 밴드


스타일

스타일은, 다이내믹스 코어의 생성에 사용되는 음악 패턴의 콜렉션이다. 또, 박자 기호나 템포를 포함해, 1 개(살) 또는 복수의 밴드를 포함할 수도 있다.

패턴은, 1 소절 이상의 길이의 음형으로, 각 음색의 기본적인 일련의 노트, 즉 파트로 구성된다. 이러한 노트는 고정되어 있지 않지만, 최종적으로는, 현재의 키, 코드, 및 연주 모드에 응해, 특정의 피치에 할당할 수 있다. 패턴에는, 바리에이션도 포함된다.

모티프는, 기본 스코아상에서 다이나믹하게 연주되도록(듯이) 디자인된, 특수한 패턴이다. 보통, 모티프는 인터랙티브 어플리케이션으로 이벤트를 마크 하기 위해서 사용된다.

DirectMusic Producer 에서는, 작가는 피아노 롤을 닮은 구라두를 사용해 패턴을 생성 한다. 각 파트는 (퍼포먼스 채널에 대응한다) 독자적인 행을 가져, 노트는 바의 길이 (지속 시간), 굵기 (velocity), 세로축 방향의 위치 (피치), 및 횡축 방향의 위치 (시간)에서 나타내진다.

작가는, 각 패턴에 대해서 많은 바리에이션을 생성 할 수가 있다. 보통은, 패턴을 카피해 일부를 조금 변경하는 것으로써, 바리에이션을 생성 할 수 있다. 스타일의 재생 메카니즘에 의해, 실행시에 바리에이션이 선택된다. 다만, 작가는 임의의 코드에 대해서 바리에이션을 무효로 할 수도 있다. 즉, 특정의 코드가 연주되고 있을 때는, 어느 바리에이션을 결코 선택하지 않게 지정할 수 있다.

작가는, 패턴에 홈 범위를 할당해, 패턴을 연주할 수 있는홈 레벨을 지정할 수도 있다.

패턴은, 장식으로서 지정할 수도 있다. 장식에는, 인트로, 필, 브레이크, 엔드, 및 커스텀의 5 종류가 있어, 이러한 1 개(살) 또는 복수의 카테고리에, 패턴을 할당할 수가 있다. 음악의 연주중에 특정의 장식이 불려 가면(자), 그 종류의 패턴만이 재생의 후보가 된다.


코드 맵

현대의 음악이 많고, 특히 파퓰러, 락, 포크, 재즈의 특색은 코드 진행의 개념에 근거하고 있어 특정의 시간범위에 연주되는 모든 노트가 특정의 코드에 관련지을 수 있고 있는 것, 및 음악은 있는 코드로부터 다른 코드로 조화적으로 이행 하는 것을 의미한다.

DirectMusic 용으로 오쏘링 된 패턴에 있는 노트는, 1 개의 코드로부터 파생하고 있는지, 코드와 조화를 이루도록(듯이) 의도된 것이다. 그러나 실행시에, 패턴은 코드 진행에 맞추어 전치 한다. 즉 베이스 코드의 변화에 응해, DirectMusic 는 노트의 피치를 변경한다.

코드 맵은, 코드 진행의 도로지도이다. 코드맙데자이나를 사용해, 작가는 희망의 음악감이나 퍼소낼러티를 표현할 수 있는 코드를 선택한다. 이러한 코드는, 타임 라인에 따른 플로차트(flow chart)에 따라 어레인지 된다. 타임 라인에는 순환이라고 하는 개념이 있으므로, 뮤직 섹션의 연주가 계속되는 동안, 최초로 돌아와 루프를 형성한다.

특정의 중요한 코드를싸인 포스트로서 지정한다. 이것들은, 특정의 포인트로 연주되지 않으면 안 되는 코드이다. 음악은, 항상 싸인 포스트로부터 싸인 포스트로 이행 한다. 그러나, 싸인 포스트간의 코드 진행은, 작가의 지정한 맵에 따라 다양한 루트를 더듬을 수도 있다.

화음표내의 루트는, 작곡가 엔진에 의해 실행시에 선택할 수가 있다. 이 경우, 패턴 자체의 바리에이션에 추가해 바리에이션이 제공된다. 작가가 세그먼트(segment)를 생성 할 때에, authoring tool을 사용해 루트를 선택할 수도 있다.

코드 맵의 코드는,서브 코드로 불리는, 복수가 다른 코드로 구성할 수가 있다. 같은 코드를 다른 회전으로 연주해 다조성을 얻기 위해서(때문에), 작가는 다른 서브 코드에 다른 파트를 할당할 수가 있다. 각 서브 코드는, 1 개(살) 또는 복수의 레벨로 유효하고, 스타일의 포토에 할당할 수 있었던 레벨로 조화를 이룬다.


스타일 베이스의 세그먼트(segment)

스타일 베이스의 세그먼트(segment)는, 미리 생성 된, 음악의 큰 부분이며, 작가는 다음의 요소를 사용해 섹션을 구축한다.

  • 스타일. 스타일은, 패턴과 같이, 음악에 관한 일반적인 정보 (박자 기호나 템포등)로 구성된다. 「스타일」을 참조할것.
  • 코드 진행. authoring tool가 코드 맵으로부터 자동적으로 파생한 것 (화음표로부터 패스를 선택한다), 또는 작가가 수작업으로 입력한 것.
  • 커멘드 트럭. DirectMusic Producer 의 홈 트럭으로서 알려져 있는 이 트럭은, 설정시의 적절한 패턴을 선택하기 위한 일련의 커멘드이다. 스타일중의 패턴의 특징은, 장식 (인트로, 필, 브레이크, 및 엔드)으로서 지정할 수 있는 것, 및 작가가 특정의 홈 범위를 할당할 수가 있는 것이다. 세그먼트(segment)의 커멘드 트럭은, 스타일 재생 엔진에 대해서, 인트로 패턴을 선택해 최초의 소절로 연주해, 다음의 4 소절로홈 레벨이 25 의 패턴만을 재생한 후, 브레이크를 연주하는, 등의 동작을 지시할 수가 있다.
  • 밴드. 작가는, 음색과 퍼포먼스 채널을, 다양한 패턴의 모든 파트에 할당할 수가 있다.


MIDI 베이스의 세그먼트(segment)

MIDI 베이스의 세그먼트(segment)는, 보통은 MIDI 파일을 임포트 해 DirectMusic Producer 로 생성 해, 여기서 작가는, 루프 포인트 뿐만이 아니라, 템포, 키, 밴드의 변경을 추가할 수 있다. 스타일 베이스의 세그먼트(segment)와 달리, MIDI 세그먼트(segment)에는 패턴 및 커멘드 트럭이 없다. 이러한 대신에 순서 트럭이 있어, MIDI 노트와 그 외의 커멘드는 여기에 포함된다.


템플릿

템플릿은, 싸인 포스트트럭과 커멘드 트럭 (옵션)을 저장 할 수 있다. 싸인 포스트트럭을 사용해, 그 세그먼트(segment) 자체 또는 싸인 포스트트럭을 가지지 않는 다른 세그먼트(segment)의 새로운 코드 진행을 생성 할 수 있다. 코만드드락크는,홈 레벨 및 장식을 제공한다. 실행시에 템플릿을 사용해, 새로운 머트리얼을 생성 할 수도 있다.

주 DirectX 8.0 이전의 버젼의 DirectMusic Producer 로 생성 한 템플릿은, 재생 가능한 독립한 세그먼트(segment)는 아니다. 이것들은, 다른 세그먼트(segment)를 어레인지 하기 위해서만 사용할 수 있다.

싸인 포스트트럭에는, 코드 진행의 바리에이션이 인정되는 리젼의 선두와 최후를 마크 하는 일련의 싸인 포스트마커가 포함된다. 각 싸인 포스트마커는, 코드 맵내의 특정의 그룹의 싸인 포스트코드에 대한 보고 유효하다. 컨텐츠의 작가는, 싸인 포스트마커 및 싸인 포스트코드를 적절한 그룹에 할당할 필요가 있다.

DirectMusic 에서는, 싸인 포스트트럭을 특정의 스타일 및 코드 맵에 적용하는 것에 의해 세그먼트(segment)를 어레인지 한다. 템플릿내의 타임 라인에 따라 작곡가가 싸인 포스트마커 페어를 찾아낼 때마다, 작곡가는 그 그룹에 소속하는 싸인 포스트코드의 페어에 대응하는 코드 맵을 검색한다. 페어가 발견되어, 그 페어간의 간격이 이용 가능한 시간에 적합하는 경우는, 엔진은 코드 맵으로 정의되고 있는 2 개의 싸인 포스트코드간의 고정 코드 진행에 따른다. 페어간의 적절한 패스가 발견되지 않는 경우나, 엔드 싸인 포스트마커가 존재하지 않는 경우는, 엔진은 시작 싸인 포스트마커로부터 파생한 임의의 코드를 연주한다.

어플리케이션으로 템플릿으로부터 세그먼트(segment)를 어레인지 하는 방법에 대해서는, 「템플릿의 사용법」을 참조할것.


밴드

밴드와는 일련의 음색에 각각의 퍼포먼스 파라미터를 조합해 음악의 부분내의 특정의 파트를 조합한 것이다. 밴드는 DLS 콜렉션과 같지 않다. DLS 콜렉션은 신디사이저에 다운로드할 수 있는 음색세트를 나타내, 임의의 어플리케이션으로부터 이용할 수가 있다.

작가는 DirectMusic Producer와 같은 툴을 사용해, 음색을 퍼포먼스 채널에 할당하는 것으로 밴드를 생성 한다. 이러한 음색은 임의의 DLS 콜렉션으로부터 취득할 수가 있어 다른 소스의 음색을 1 개의 밴드에 혼재시킬 수도 있다. 각각의 음색에는, 볼륨, 빵, 전조가 설정된다.

퍼포먼스 채널은, 음색을 파트에 할당한다. 패턴이 채널 1 의 특정의 노트를 호출하는 경우, 이 노트는 채널 1 에 할당할 수 있고 있는 현재의 밴드의 음색으로 연주된다. 사운드는, 밴드로 설정되어 있는 음색의 볼륨, 빵, 및 전조의 값으로 수정된다.

밴드는 개별의 파일에 보존하는지, 스타일이나 세그먼트(segment)에 포함할 수 있다.


재생중의 음악의 변화

DirectMusic 가 스타일 베이스의 세그먼트(segment)를 연주 하면 와, 기본적인 화음과 리듬으로 변경이 더해지므로, 연주에 변화가 나타난다. 변경의 일부는 스크립트화 되어 일부는 랜덤에 행해진다.

  • 패턴의 선택. 일반적인 스타일에는 복수의 패턴이 포함된다. 이러한 패턴은, 커멘드 트럭으로부터의 커멘드에 응해 선택된다. 예를 들어, 커멘드 트럭이 브레이크 장식의 연주를 요구 하면, 스타일 재생 엔진은 현재의홈 레벨에 모순되지 않는 브레이크 패턴을 선택한다 (작가는, 각 패턴에 어울린 홈 레벨을 지정한다). 적절한 패턴이 몇개인가 있는 경우는, 작가에 의해 세그먼트(segment)에 파묻힌 룰에 따라 패턴이 선택된다. 패턴은 완전 또는 부분적으로 랜덤에 선택되는 일도 있으면, 특정의 순서로 선택되는 일도 있다.
  • 패턴내의 바리에이션. 패턴내의 파트에는, 복수의 바리에이션을 설정할 수가 있다. 바리에이션은, 작가가 지정한 순서로 연주할 수가 있다. 그 이외의 경우는, 패턴의 각 반복에 대해, 스타일 재생 엔진이 바리에이션을 랜덤에 선택한다.
  • 홈 레벨. 세그먼트(segment)의 현재의 홈 레벨에 의해, 스타일내의 어느 패턴을 재생용으로 선택할 수 있을지가 정해진다. 현재의 레벨을 설정하는 것은 커멘드 트럭이지만, 커멘드 트럭은 보통, 세그먼트(segment)나 템플릿의 일부로서 오쏘링 된다. 세그먼트(segment)의 현재의 홈 레벨은, 프로그램적으로 변경할 수가 있다. 퍼포먼스의 마스터 홈 레벨을 설정하는 것으로, 변경을 모든 세그먼트(segment)에 적용할 수가 있다.
  • 전조. 세그먼트(segment)를 연주할 경우에, 베이스 코드는 코드 트럭의 진행에 따라 변화한다. 현재의 패턴의 노트는, 새로운 코드와 조화를 이루도록, 자동적으로 전치 된다.
  • 타이밍의 바리에이션. 재생 엔진은, 개개의 노트의 파라미터, 즉 노트의 시작 시기와 종료시기에, 랜덤인 변경을 더할 수가 있다.
  • 밴드. 세그먼트(segment)의 연주중에, 음색과 음색의 설정 (볼륨, 빵, 및 전조)의 선택을, 오쏘링 된 세그먼트(segment)내의 밴드 트럭으로 변경하거나 어플리케이션으로 동적으로 변경할 수가 있다. 어플리케이션으로 밴드를 변경하려면 , 밴드 오브젝트에 근거하는 세칸다리세그먼트를 생성 해 그 세그먼트(segment)를 연주하는지, 연주중의 세그먼트(segment)의 밴드 트럭상에 파라미터를 설정한다.

어플리케이션은 대부분의 경우, 기존의 세그먼트(segment)를 조작하는 것이 아니라, 다른 세그먼트(segment)를 연주해 음악 전체를 제어한다. 예를 들어, 게임의 인텐시티의 변화를 음악에 반영시키려면 , 인텐시티레벨에 응해 오쏘링 된 새로운 세그먼트(segment)에 트란지션 하는 것만으로 좋다. 작가에게 홈 범위가 다른 패턴을 생성시켜, 게임 이벤트에 응해 홈 레벨을 변경 하면, 1 개의 스타일 베이스의 세그먼트(segment)에서도 같은 이펙트를 얻을 수 있다.


뮤직값과 MIDI 노트

DirectMusic 스타일내의 패턴의 노트는, 고정된 노트는 아니다. 이러한 노트는, 현재의 연주 모드와 서브 코드 레벨에 응해 현재의 코드에 전치 되었을 때에만 실제의 노트가 되는, 뮤직값이다.

뮤직값은, 노트의 의도적인 역할을 나타내는 것이다. 예를 들어, 뮤직값으로, 노트를 코드의 2 번째의 위치, 1 개(살) 위에의 스케일로 연주하도록(듯이) 지정할 수가 있다. 이 뮤직값이 특정의 코드에 적용되면(자), 그 코드의 2 번째로, 1 개(살) 위에의 스케일의 적절한 MIDI 노트에 변환된다.

코드에 대해서 노트가 어떻게 해석될까는, 연주 모드에 따라서 다르다. 예를 들어, 모드가 DMUS_PLAYMODE_NORMALCHORD 의 경우, 노트는 코드의 루트음에 근거해, 코드와 스케일의 음정으로서 해석된다. 모드가 DMUS_PLAYMODE_FIXEDTOKEY 의 경우, 노트는 선형인 값으로서 해석된다.

복수의 병행하는 코드 진행을 사용해 복잡한 화음을 가능하게 하기 위해서, DirectMusic 코드는 복수의 서브 코드로 구성할 수 있다. 서브 코드 레벨은 0 ~ 31 의 값으로, 뮤직값의 확립에 사용할 수 있는 코드의 서브 코드를 결정한다. 각 서브 코드는, 작가의 정의에 따라, 1 개(살) 또는 복수의 레벨로 유효하다. DirectMusic Producer 는, 1 개의 코드에 대해서 최고 4 개의 서브 코드를 지원 한다.

세그먼트(segment)가 연주될 때, 각 노트는 메세지 구조체에 캡슐화된다. 이 구조체는, 원의 뮤직값 및 최종적인 MIDI 노트와 함께, 전조로 사용되는 연주 모드와 서브 코드 레벨을 지정한다. 대부분의 어플리케이션은 노트 메세지를 직접 처리하지 않지만, 툴을 사용해 이 메세지를 처리해, 노트를 변경할 수가 있다. 예를 들어, 툴은 특정의 연주 모드로 전치 되는 노트를 끼어들어 취득하거나 연주 모드를 변경하거나 메세지가 건네받기 전에 새로운 MIDI 값을 계산할 수가 있다.

뮤직값, 연주 모드, 코드, 및 서브 코드에 대해서는, 다음의 주제를 참조할것.

  • DMUS_NOTE_PMSG
  • DMUS_PLAYMODE_FLAGS
  • DMUS_CHORD_PARAM
  • DMUS_CHORD_KEY
  • DMUS_SUBCHORD
  • IDirectMusicPerformance8::MIDIToMusic
  • IDirectMusicPerformance8::MusicToMIDI


다운로다브르사운드

지금까지, 대부분의 컴퓨터 음악은, 다음의 2 개의 방법의 어느쪽이든으로 생성되고 있었다. 각각 이점은 있지만, 결점도 있다.

  • 보통은 . WAV 파일, 또는 레드 북 오디오 규격에 따른 표준적인 CD 트럭에 기록되고 있는 디지털 샘플로부터 웨이브 폼 (파형)을 재현 하는 방법. 디지털 샘플에서는 어떠한 사운드도 재현 가능해, 어느 사운드 카드를 사용했을 경우에서도 얻을 수 있는 출력은 매우 자주(잘) 비슷하다. 다만, 스트리밍용으로 많은 기억 영역과 리소스가 필요하다.
  • 일반적으로는 MIDI 파일로부터의 메세지에 응답해, 음색의 사운드를 보통은 하드웨어로 합성하는 방법. MIDI 파일은 컴팩트해, 스트리밍 리소스도 불과 밖에 필요로 하지 않지만, 출력은 General MIDI 세트의 신디사이저로 이용할 수 있는 음색의 수로 한정되어 시스템에 따라서는 매우 다른 소리가 되는 경우가 있다.

디지털 샘플링의 이점과 MIDI 의 컴팩트함, 및 유연성을 조합하는 1 개의 방법이, 웨이브 테이블 합성이다. 이것은, 디지털 샘플로부터 음색의 사운드를 합성하는 방법이다. 실제의 음색을 레코딩 하는 것에 의해 샘플을 취득해, 하드웨어에 보존한다. 다양한 피치와 볼륨으로 임의의 길이의 사운드를 생성 하기 위해서, 샘플의 루프라고 조정을 한다.

웨이브 테이블 합성은 알고리즘에 근거하는 FM 합성보다 현실적인 틴바를 생성 하지만, 여전히 고정 세트의 음색으로 한정된다. 한층 더 특정의 음색의 사운드는 메이커의 이행에 따라서 달라, 하드웨어의 편성이 다르면(자) 매우 다른 사운드가 되는 경우가 있다.

다음에, MIDI Manufactures Association 에 의해 발표된, 다운로다브르사운드 (DLS) 규격이 있다. DLS 는, 시스템에 하드 와이어드로 이행 된 샘플 대신에, 실행시에 제공되는 샘플에 근거해 웨이브 테이블 합성을 실시할 수가 있는 방법이다. 음색을 기술하는 데이터는 신디사이저에 다운로드되어 그 후는 다른 MIDI 음색과 같게 그 음색을 연주할 수 있다. DLS 는 어플리케이션의 일부로서 전달할 수 있기 (위해)때문에, 개발자는 사운드 트랙을 모든 시스템으로 똑같이 연주시킬 수가 있다. 또, 음색의 선택이 제한될 것도 없다.

DLS 음색은 1 개 또는 복수의 샘플로부터 생성 되어 보통은 싱글 피치를 나타내지만, 신디사이저로 변경을 더하는 것으로 그 외의 피치를 생성 할 수 있다. 광범위의 피치로 음색의 사운드를 현실적으로 하려면 , 복수의 샘플을 사용한다. DLS 음색을 다운로드할 때에, 리젼으로 불리는 특정의 피치 범위가 각 샘플에 할당할 수 있다.

DLS Level 2 에서는, 모든 노트에 각각의 리젼을 할당할 수가 있다. 또, 각 리젼의 틴바를 계층으로 불리는 복수의 샘플로부터 생성 하거나 노트의 velocity에 응해 다른 계층을 방아쇠 할 수가 있다. 이것에 의해, 1 개의 음색으로부터 무수한 사운드를 생성 할 수 있다.

더해, 샘플에 아티큘레이션을 줄 수도 있다. 이것은 사운드를 실제의 음색에 의해 접근하기 위한 특징을 정의한다. 아티큘레이션에는, 사운드의 볼륨이나 피치의포락선 및 바이브라토나 트레몰로를 제공하는 저주파수발진기 (LFO)가 포함된다.

샘플은, 루프 가능하게 하는 일도, 단발로 할 수도 있다. 루프 가능한 샘플은, 노트의 계속 시간의 사이, 반복 연주된다. 단발의 샘플은 한 번만 연주된다.

DLS 데이터는 음색 콜렉션에 저장 되어 여기로부터 신디사이저에 다운로드된다.

다른 MIDI 음색의 경우와 같게, DLS 음색에는 패치 번호를 할당할 수 있어 MIDI 메세지에 응답한다. 다만, DLS 음색 (기기)은 General MIDI 세트에 따를 필요는 없다. 실제, 뮤직의 음색일 필요는 전혀 없다. 연설의 일부나 생성 끝난 완전한 소절 등, 어떤 사운드라도 DLS 음색에 관련지을 수가 있다.

DLS 콜렉션과 DLS 음색의 생성 방법의 상세한 것에 대하여는, DirectMusic Producer 의 문서를 참조할것. DLS 규격의 상세한 것에 대하여는, MIDI Manufacturers Association 로부터 입수 가능한 「Downloadable Sounds Level 2」를 참조할것.

대부분의 어플리케이션은 음색이나 DLS 데이터를 직접 취급할 필요가 없다. 콜렉션을 열거나 음색 데이터를 다운로드하는 처리는, 밴드 오브젝트에 의해 실행된다. 밴드를 다운로드 하면, 그 밴드에 관련 붙일 수 있어 모든 음색 데이터도 다운로드된다. 상세한 것에 대하여는, 「밴드의 사용법」을 참조할것.


오디오 스크립트

오디오 스크립트는, 어플리케이션내로부터 액세스 할 수 있는 변수와 루틴을 포함한 파일이다. Microsoft® Visual Basic® Scripting Edition 의 AudioVBScript 로 불리는 서브 세트로 기술된다. DirectMusic Producer 에는 스크립트의 오쏘링 환경이 포함되어 있어 스크립트는 바이너리 파라미터와 스크립트의 텍스트를 포함한 특수한 형식에서 보존된다.

스크립트는 주된 DirectX Audio 오브젝트의 몇개인가를 이행 해, 다음과 같은 기본적인 기능을 실행할 수 있다.

  • 오디오 패스의 생성
  • 오디오 패스의 볼륨의 설정
  • 퍼포먼스의 글로벌 파라미터의 설정
  • 세그먼트(segment)의 로드, 연주, 및 정지
  • 밴드의 다운로드

DirectX Audio 스크립트는, 어플리케이션 개발자와 사운드 생성자가 용이하게 공동으로 작업할 수 있도록(듯이) 하는 것을 목적으로 하고 있다. 스크립트에 의해, 사운드 생성자는 사운드 트랙을 세세하고, 직접 제어할 수가 있다. 사운드의 로드나 연주의 기본적인 기능은 스크립트에 의해 실행된다. 어플리케이션에는, 스크립트를 호출하는 일반적인 코드가 포함된다.

여기에서는, 스크립트를 사용하는 이점에 대해 예를 들어 설명한다.

어느 게임의 사운드 이펙트가 개개의 웨이브 파일에 보존되고 있다고 한다. 게임에서는, 무기의 발사음이나 monster의 신음소리소리등의 이벤트에 이러한 사운드를 사용한다. 종래의 프로그래밍 방법에서는, 개발자는 개개의 사운드를 파일명을 지정해 로드해, 게임의 적절한 포인트로 세칸다리세그먼트로서 연주하고 있었다.

사운드 생성자가, 사운드를 변경하려고 했을 경우를 생각해 본다. 예를 들어, monster의 보스의 신음소리소리를 부하와는 다른 신음소리소리로 변경하고 싶다고 한다. 사운드 생성자는 필요한 파일을 생성 해, 코드로 변경을 이행 하는 개발자에게 건네준다. 사운드 생성자가 새롭고 컴파일 된 게임을 받아, 테스트하기까지는 상당한 시간이 걸린다.

같은 상황으로, 오디오 스크립트를 사용하는 경우를 생각해 본다. 실제의 사운드를 어플리케이션에 하드 코딩 하는 대신에, 개발사람은 끙끙거려 소리에 대응하는 다음과 같은 코드를 기술한다. 여기에서는,szGrunter 가 "Player","Boss" 또는 "Minion" 등의 캐릭터 라인 정수로 설정되어 있어pdmScript 는 스크립트 오브젝트에의 인터페이스이라고 가정한다.

pdmScript->SetVariableVariant("Grunter", szGrunter, NULL);
pdmScript->CallRoutine("PlayGrunt", NULL);

이 코드에서는, 스크립트내의 Grunter 변수의 값을 설정해, PlayGrunt 스크립트 루틴을 호출하고 있다. 스크립트의 생성자, 보통은 사운드 설계 팀의 멤버가 루틴의 처리를 결정한다. 예를 들어, 재생하는 사운드를 결정하기 전에,"Grunter" 의 값을 테스트하는 등이다.

게임의 상황에 대한 응답을 변경하려면 , 스크립트의 텍스트를 변경하는 것만으로 끝나, 새로운 루틴을 기존의 어플리케이션으로 즉시 테스트할 수 있다.

스크립팅 API 는 DirectMusic Producer 의 헬프 파일로 설명되고 있다. 어플리케이션으로 스크립트를 이행 하는 방법에 대해서는, 「오디오 스크립트의 사용법」을 참조할것.

주 오디오 스크립트는 Web 페이지로 사용하도록(듯이)는 설계되어 있지 않다.


DirectX Audio 의 사용법

여기에서는, 어플리케이션 개발에 있어서의 Microsoft® DirectMusic® 및 Microsoft® DirectSound® API 의 사용 방법을 설명한다.

설명하는 주제는, 다음과 같다.

  • 오디오 데이터의 로드
  • 사운드의 재생
  • 퍼포먼스 파라미터
  • 오디오 패스의 사용법
  • 3D 사운드
  • 이펙트의 사용법
  • 버퍼 체인
  • 어레인지 요소의 사용법
  • 오디오 스크립트의 사용법
  • DirectSound 에서의 웨이브의 재생
  • 사운드 캡춰

일반적인 개요에 대해서는, 「DirectX Audio 입문」을 참조할것.

기본적인 데이터 플로우의 메카니즘에 대해서는, 「DirectX Audio 에 대하며」를 참조할것.

특수한 어플리케이션으로 사용되는 고도의 기능에 대해서는, 「DirectX Audio 의 고도의 주제」를 참조할것.


오디오 데이터의 로드

DirectMusic 오브젝트를 퍼포먼스에 짜넣기 전에, 그것들을 파일 또는 리소스로부터 로드하지 않으면 안 된다. IDirectMusicLoader8 인터페이스는, 이러한 오브젝트의 열거 및 로드를 관리하기 위해서 사용된다. 또, 캐쉬하는 것에 의해 오브젝트의 로드가 한 번에 끝나도록(듯이) 하기 위해서도 사용된다.

어플리케이션에서는, 기존의 로더의 인스턴스를, 한 번에 1 개(살)만 사용해야 하는 것이다. 1 개의 글로벌 로더 오브젝트를 생성 해, 로드가 모두 종료할 때까지 오브젝트를 해방하지 않게 한다. 이 방법에 의해, 오브젝트가 효과적으로 검색 및 캐싱 된다.

DirectMusic 에 있어서의 IStream 의 이행에 의해, 데이터가 소스로부터 스트림에 넣어진다. 데이터의 해석은,IPersistStream 의 이행을 통해, 다양한 오브젝트 자신에 의해 처리된다. 표준적인 DirectMusic 데이터만을 처리하는 경우는, 이러한 인터페이스를 직접 사용할 필요는 없다.

다른 오브젝트에 의해 참조되는 오브젝트의 로드는, 투과적으로 처리된다. 예를 들어, DirectMusic Producer 로부터 로드 되는 스타일에, 다른 파일에 데이터가 있는 밴드에의 참조가 포함되어 있다고 한다. 스타일의 IPersistStream 는 참조를 찾아내면(자), 데이터 스트림을 건네준 IStream 로부터 IDirectMusicGetLoader8 인터페이스를 취득한다. 이 인터페이스를 사용해, 로더 오브젝트에의 포인터를 취득한다. 계속되어,IDirectMusicLoader8::GetObject 를 호출해, 밴드를 로드한다.

로더의 사용 방법의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 로더의 검색 디렉토리의 설정
  • 디렉토리에서의 오브젝트 검색
  • 오브젝트의 열거
  • 파일로부터의 오브젝트의 로드
  • 리소스로부터의 오브젝트의 로드
  • 컨테이너
  • 오브젝트 디스크립터의 취득
  • 캐쉬의 관리
  • 가베지 콜렉션
  • 오브젝트의 설정

「DirectX Audio 의 고도의 주제」의 「커스텀 로드」도 참조할것.


로더의 검색 디렉토리의 설정

검색 대상의 오브젝트를 기술하는 DMUS_OBJECTDESC 구조체의 wszFileName 멤버가 풀 패스를 지정하고 있지 않는 한, 로더는 디폴트로 커런트 디렉토리를 검색한다. IDirectMusicLoader8::SetSearchDirectory 메소드를 사용하면(자),IDirectMusicLoader8::GetObject ,IDirectMusicLoader8::LoadObjectFromFile , 및 IDirectMusicLoader8::EnumObject 의 각 메소드로 다른 디폴트 패스를 설정할 수 있다. 이 디폴트 패스를 모든 오브젝트에 적용하는 일도, 특정의 클래스의 오브젝트인 만큼 적용할 수도 있다.

다음의 샘플 코드에서는, 스타일 파일의 검색 패스를 설정해 있다.

HRESULT mySetLoaderPath (
    IDirectMusicLoader8 *pILoader)    // 이전에 생성 되었다.
{
    return pILoader->SetSearchDirectory(
            CLSID_DirectMusicStyle,
            L"c:\\mymusic\\funky",
            FALSE);
}

이 함수를 호출해 두면(자), 어플리케이션은, 풀 패스를 지정하지 않고 파일명만을 사용해 스타일을 로드할 수 있다.


디렉토리에서의 오브젝트 검색

IDirectMusicLoader8::ScanDirectory 메소드는, 특정의 클래스의 오브젝트를 현재의 검색 디렉토리에서 찾는다. 서브 클래스와"*" 이외의 파일 확장자(extension)를 지정하는 것으로써, 검색 범위를 좁힐 수 있다.

이 메소드는 일치하는 모든 파일로부터 완성되는 리스트를 생성 해,IDirectMusicObject8::ParseDescriptor 메소드를 사용해 오브젝트의 GUID 와 이름을 추출한다. 이러한 식별자는 내부 데이타베이스에 보관 유지되므로, 어플리케이션은 그 이후, 파일명은 아니고 GUID 나 이름을 사용해 오브젝트를 로드할 수 있는 「파일로부터의 오브젝트의 로드」를 참조할것.

주 DirectMusic Producer 로 생성 한 컨텐츠의 경우, 오브젝트를 로드하기 전에, 반드시 IDirectMusicLoader8::ScanDirectory 를 호출하는 것을 추천 한다. 파일명을 명시적으로 지정해 오브젝트를 로드하는 경우에서도, 이러한 오브젝트에는 파일명으로 지정되어 있지 않은 것 외의 오브젝트에의 참조가 포함되어 있는 경우가 있다. 오브젝트가 저장 되고 있는 각 디렉토리에 대해서 ScanDirectory 가 불려 가지 않은 경우, 로더는 이러한 참조되고 있는 오브젝트를 찾아낼 수가 없다.

ScanDirectory 메소드의 pwszScanFileName 파라미터에, 캐릭터 라인에의 포인터를 포함하면(자), 그 이름을 가지는 파일에 검색 결과가 캐싱 되어 그 이후의 검색이 고속화된다. 캐쉬 파일을 이용할 수 있는 경우, 이 메소드는 타임 스탬프나 사이즈가 변경되고 있는 파일에 한해서 오브젝트 정보를 갱신한다.

주 현재의 버젼의 DirectMusic 에서는,ScanDirectory 는 캐쉬 파일을 사용하지 않는다. 캐쉬 파일의 이행은, 현재에도 가능하다. 이것에 의해, 향후의 버젼으로 퍼포먼스가 향상한다.

예에 대해서는, 「오브젝트의 열거」를 참조할것.


오브젝트의 열거

IDirectMusicLoader8::EnumObject 메소드를 사용해,IDirectMusicLoader8::ScanDirectory 또는 IDirectMusicLoader8::GetObject 의 어느 쪽인지를 호출해 내부 데이타베이스에 기록한, 특정의 클래스 또는 전클래스의 전오브젝트를 보간 한다. 발견된 각 오브젝트의 설명은,DMUS_OBJECTDESC 구조체에 돌려주어진다.

주 전오브젝트를 확실히 찾아내려면 , 최초로 ScanDirectory 를 호출해 둔다. EnumObject 는 디스크 파일을 해석하는 것이 아니라, 내부 데이타베이스로 오브젝트를 체크한다.

다음의 예에서는, 현재의 검색 디렉토리에 기록 떠날 수 있어 모든 스타일 오브젝트를 열거해, 데밧깅마크로 TRACE 를 사용해 그러한 정보를 1 개씩 표시하고 있다. 그 클래스에서 열거해야 할 오브젝트가 없어질 때까지 루프는 속행된다.

void myListStyles(
        IDirectMusicLoader *pILoader)

{
    HRESULT hr = pILoader->SetSearchDirectory(
            CLSID_DirectMusicStyle,
            L"c:\\mymusic\\wassup",
            TRUE);
    if (SUCCEEDED(hr))
    {
        hr = pILoader->ScanDirectory(
                CLSID_DirectMusicStyle,
                L"sty",
                L"stylecache");
        if (hr == S_OK)    // 파일이 발견되었을 경우만.
        {
            DWORD dwIndex;
            DMUS_OBJECTDESC Desc;
            Desc.dwSize = sizeof(DMUS_OBJECTDESC);
            for (dwIndex = 0; ;dwIndex++)
            {
                if (S_OK ==(pILoader->EnumObject(
                        CLSID_DirectMusicStyle,
                        dwIndex, &Desc)))
                {
                    TRACE("Name: %S, Category: %S, Path: %S\n",
                            Desc.wszName,
                            Desc.wszCategory,
                            Desc.wszFileName);
                }
                else break;
            }
        }
    }
}

이 예에서는, 메소드 호출의 결과를 테스트하는 목적으로,SUCCEEDED 매크로를 사용하지 않은 점에 주의 해야 한다. 부적절한 인덱스 번호를 지정했을 경우,EnumObject 가 성공 코드의 S_FALSE 를 돌려주기 때문에 있다.


파일로부터의 오브젝트의 로드

오브젝트를 로드하려면 , 다음의 예에 나타내도록(듯이), 최초로 IDirectMusicLoader8 인터페이스를 취득한다.

IDirectMusicLoader8* m_pLoader;

CoInitializeEx(NULL, 0);
HRESULT hr = CoCreateInstance(
    CLSID_DirectMusicLoader,
    NULL,
    CLSCTX_INPROC,
    IID_IDirectMusicLoader8,
    (void**) &m_pLoader);

다음에,IDirectMusicLoader8::LoadObjectFromFile 또는 IDirectMusicLoader8::GetObject 의 어느쪽이든을 사용해, 파일로부터 오브젝트를 로드할 수 있다. 전자는,DMUS_OBJECTDESC 구조체를 사용해 오브젝트를 기술할 필요가 없기 때문에 편리하다.

다음의 샘플 코드에서는, 이전에 IDirectMusicLoader8::SetSearchDirectory 로 설정된 디렉토리로부터 4 개의 세그먼트(segment)를 로드하고 있다.

IDirectMusicSegment8 * m_pSegments[4];

static WCHAR  wszNames[4][MAX_PATH] = {
    L"AudioPath1.sgt",
    L"AudioPath2.sgt",
    L"AudioPath3.wav",
    L"AudioPath4.sgt"
};

for (DWORD dwIndex = 0; dwIndex < 4; dwIndex++)
{
    hr = m_pLoader->LoadObjectFromFile(
            CLSID_DirectMusicSegment,
            IID_IDirectMusicSegment8,
            wszNames[dwIndex],
            (void**) &m_pSegments[dwIndex]);
}

다음의 예에서는,IDirectMusicLoader8::GetObject 를 사용해 파일로부터 스타일 오브젝트를 로드하고 있다. 최초의 파라미터는, 스타일에의 포인터를 받는다.

void myLoadStyle(
    IDirectMusicStyle8 **ppStyle, IDirectMusicLoader8 *pLoader)
{
    if (pLoader)
    {
        DMUS_OBJECTDESC Desc;

        // 스타일 오브젝트의 파일명과 클래스 GUID 를 사용해,
        // Desc 를 초기화하는 것으로부터 시작 한다.

        wcscpy(Desc.wszFileName, L"c:\\mymusic\\funky\\polka.sty");
        Desc.guidClass = CLSID_DirectMusicStyle;
        Desc.dwSize = sizeof (DMUS_OBJECTDESC);
        Desc.dwValidData = DMUS_OBJ_CLASS |
                           DMUS_OBJ_FILENAME |
                           DMUS_OBJ_FULLPATH;

        pLoader->GetObject(&Desc, IID_IDirectMusicStyle8,
                (void **) ppStyle);
    }
}

이 예에서는, 파일을 풀 패스명으로 지정해, 이것을 DMUS_OBJ_FULLPATH 플래그를 설정해 지시하고 있다.

검색 대상의 특정의 파일 오브젝트를 식별하려면 ,DMUS_OBJECTDESC 구조체의 wszName,guidObject,wszFileName 의 각 멤버의 어느 쪽인가에 값을 입력해,dwValidData 멤버에 적절한 1 개(살) 또는 복수의 플래그를 설정한다. wszFileName 는 아니고 wszName 나 guidObject 를 사용해 파일을 식별하는 경우는,IDirectMusicLoader8::ScanDirectory 메소드를 호출해, 커런트 디렉토리내의 GUID 와 이름을 이용 가능하게 해야 한다. 상세한 것에 대하여는, 「디렉토리에서의 오브젝트 검색」을 참조할것.

「리소스로부터의 오브젝트의 로드」도 참조할것.


리소스로부터의 오브젝트의 로드

리소스로서 저장 된 오브젝트 또는 메모리내의 다른 장소에 저장 된 오브젝트는, 파일 오브젝트와 같게 로드 된다. 「파일로부터의 오브젝트의 로드」를 참조할것.

다만, 메모리 오브젝트의 경우,DMUS_OBJECTDESC 구조체의 wszName,guidObject, 및 wszFileName 멤버는 사용하지 않는다. 이러한 멤버 대신에, 오브젝트가 점유 하고 있는 메모리 블록에의 포인터와 그 사이즈를 취득해, 이러한 정보를 각각 pbMemData 및 llMemLength 멤버에 저장 한다. dwFlags 멤버의 DMUS_OBJ_MEMORY 플래그도 설정해야 한다.

데이터를 간단하게 캐싱 할 수 있도록(듯이), 로더는 메모리에의 내부 포인터를 보관 유지하기 위해(때문에), 한 번 IDirectMusicLoader8::GetObject 가 불려 가면(자), 메모리를 해방할 수 없다. 이것을 소거하려면 ,IDirectMusicLoader8::SetObject 를 같은 DMUS_OBJECTDESC 디스크립터를 사용해 호출한다. 다만,pbMemData 에는 NULL 를 설정한다. 리소스 메모리는 해방되지 않기 때문에, 리소스로부터 로드하는 경우는 관계없다.

다음의 함수에서는, MIDI 파일을 리소스로부터 세그먼트(segment)에 로드하고 있다.

// m_pLoader 는 유효한 IDirectMusicLoader8 포인터이다.

IDirectMusicSegment8* m_pSegment;

HRESULT LoadMidi(HMODULE hMod, WORD ResourceID)
{
    HRESULT              hr;
    DMUS_OBJECTDESC      ObjDesc;

    HRSRC hFound = FindResource(hMod,
            MAKEINTRESOURCE(ResourceID), RT_RCDATA);
    HGLOBAL hRes = LoadResource(hMod, hFound);

    ObjDesc.dwSize = sizeof(DMUS_OBJECTDESC);
    ObjDesc.guidClass = CLSID_DirectMusicSegment;
    ObjDesc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_MEMORY;
    ObjDesc.pbMemData = (BYTE *) LockResource(hRes);
    ObjDesc.llMemLength = SizeofResource(hMod, hFound);

    hr = m_pLoader->GetObject(
            &ObjDesc, IID_IDirectMusicSegment8,
            (void**) &m_pSegment );

    return hr;
}

다른 오브젝트에 의해 참조되고 있는 오브젝트는, 최초로 로드하지 않으면 안 된다. 예를 들어, 스타일에의 참조를 포함한 세그먼트(segment)를 로드하는 경우, 세그먼트(segment)를 올바르게 연주하려면 , 스타일이 먼저 로드되어 있지 않으면 안 된다. 세그먼트(segment)를 스타일을 찾아낼 수 있도록(듯이), 스타일로 IDirectMusicLoader8::SetObject 를 호출할 수도 있다.


컨테이너

컨테이너는, 다양한 오브젝트를 포함한 파일을 나타내는 오브젝트이다. 컨테이너 파일에는, 세그먼트(segment), 스타일, DLS 콜렉션 등, 퍼포먼스에 필요한 모든 데이터가 보관 유지되는 경우가 있다. 컨테이너 파일은, 보통, DirectMusic Producer 로 생성 된다. 컨테이너는 세그먼트(segment) 파일 및 스크립트 파일내에도 생성 할 수 있다.

컨테이너는,IDirectMusicLoader8::GetObject 를 사용해, 다른 오브젝트와 같게 로드한다. 이 메소드는, 컨테이너내의 모든 오브젝트를 로더에 알려GetObject 를 사용해 이름 또는 GUID 로 오브젝트를 취득할 수 있도록(듯이) 한다.

IDirectMusicContainer8 인터페이스를 취득한 후는,IDirectMusicContainer8::EnumObject 를 사용해 컨테이너내의 오브젝트를 열거할 수 있다.

다음의 샘플 함수는, 컨테이너를 로드해, 이름에 의해 컨테이너로부터 세그먼트(segment)를 취득해,IDirectMusicSegment 인터페이스를 돌려준다. 실제의 예를 나타내기 (위해)때문에, 컨테이너 오브젝트는 함수내에서 생성 및 해방된다. 오브젝트의 복제를 피하기 (위해)때문에, 이 처리는 어플리케이션내에서 한 번 밖에 실행할 수 없다.

IDirectMusicSegment* LoadSegmentFromContainer (
        IDirectMusicLoader8* pLoader,
        WCHAR* wszFileName,
        WCHAR* wszSegmentName )

{
  DMUS_OBJECTDESC ObjDesc;
  IDirectMusicSegment* pSegment = NULL;
  IDirectMusicContainer8* pContainer = NULL;

// 컨테이너의 로드.

  HRESULT hr = pLoader->LoadObjectFromFile(CLSID_DirectMusicContainer,
      IID_IDirectMusicContainer8, wszFileName, (void**) &pContainer);
  if (FAILED(hr))
        return NULL;

// 세그먼트(segment)를 기술한다.

  ZeroMemory(&objDesc, sizeof(objDesc));
  objDesc.dwSize = sizeof(objDesc);
  objDesc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_NAME;
  objDesc.guidClass = CLSID_DirectMusicSegment;
  wcsncpy (objDesc.wszName, wszSegmentName,
      sizeof(objDesc.wszName) - 1);
  objDesc.wszName[sizeof(objDesc.wszName) - 1] = 0;

// 세그먼트(segment)의 로드.

  hr = pLoader->GetObject(&ObjDesc, IID_IDirectMusicSegment,
      (void**) &pSegment);

// 컨테이너를 캐쉬로부터 해방해, 오브젝트를 파기한다.

  if (pContainer)
  {
    IDirectMusicObject *pObject = NULL;
    pContainer->QueryInterface(IID_IDirectMusicObject,
            (void **) &pObject);
    if (pObject)
    {
      pLoader->ReleaseObject(pObject);
      pObject->Release();
    }
  pContainer->Release();
  }
  if (S_OK ! = hr) return NULL;
  return pSegment;
}


오브젝트 디스크립터의 취득

오브젝트를 로드한 다음에, 그 오브젝트의 IDirectMusicObject8 인터페이스를 사용해,DMUS_OBJECTDESC 구조 체내의 정보를 취득해야 한다.

다음의 샘플 코드에서는,IDirectMusicObject8::GetDescriptor 메소드를 사용해 스타일명을 취득하고 있다.

//  pStyle 는 IDirectMusicStyle8 인터페이스에의 유효한 포인터이다.

IDirectMusicObject8 *pIObject;
DMUS_OBJECTDESC Desc;

if (SUCCEEDED(pStyle->QueryInterface(IID_IDirectMusicObject8,
        (void **) &pIObject)))
{
    if (SUCCEEDED(pIObject->GetDescriptor(&Desc)))
    {
        if (Desc.dwValidData & DMUS_OBJ_NAME)
        {
            // Desc.wszName 는 스타일의 이름을 보관 유지한다.
        }
    }
    pIObject->Release();
}


캐쉬의 관리

오브젝트를 캐싱 하면,IDirectMusicLoader8::GetObject 메소드는 항상 오브젝트의 같은 인스턴스를 돌려주게 된다.

캐쉬에는, 오브젝트에의 포인터가 저장 된다. 오브젝트 자체의 메모리는 COM 에 의해 관리되어 참조 카운트가 0 이 될 때까지 해방되지 않는다. 캐쉬로부터 오브젝트를 해방하는 것으로, 오브젝트에 대한 어플리케이션의 COM 참조를 해방하는 것은 다른 것에 주의가 필요하다.

파일 로드 프로세스에서는, 오브젝트에의 링크를 해결하기 위해서 캐싱이 광범위하게 사용된다. 예를 들어, 2 개의 세그먼트(segment)가 같은 스타일을 참조하고 있는 경우를 생각한다. 최초의 세그먼트(segment)를 로드할 때, 세그먼트(segment)는 로더를 호출해 스타일을 취득한다. 로더는, 스타일 오브젝트를 생성 해 디스크로부터 데이터를 로드해, 스타일 오브젝트에의 포인터를 캐쉬에 저장 해, 이 포인터를 세그먼트(segment)에 돌려준다. 캐싱이 유효한 경우, 2 번째의 세그먼트(segment)가 로드 될 때 스타일의 문의를 해 로더가 즉시 같은 포인터를 돌려준다. 2 개의 세그먼트(segment)는, 어느쪽이나 같은 스타일을 가리키고 있다. 캐싱이 무효인 경우는, 2 번째의 세그먼트(segment)가 같은 스타일을 요구했을 때에, 같은 스타일 오브젝트가 파일로부터 로드 되어 중복 하므로, 시간과 메모리를 소비한다.

다른 예를 생각해 본다. 밴드 오브젝트가, 로더에 General MIDI 의 DLS 콜렉션을 캐쉬에 두도록(듯이) 요구하는 경우를 생각한다. 밴드가 GM 음색을 다운로드할 필요가 있을 때마다, 로더로부터 콜렉션을 취득한다. CLSID_DirectMusicCollection 의 캐싱이 무효가 되어 있는 경우, MIDI 파일내에서 패치 체인지가 발생할 때마다, GM 콜렉션 전체의 카피가 생성 된다. 이것은 분명하게 바람직하지 않다.

디폴트에서는, 모든 오브젝트 클래스에서 캐싱이 유효하게 되어 있다. IDirectMusicLoader8::EnableCache 메소드를 사용하면(자), 1 개(살) 또는 모든 오브젝트 클래스의 캐싱을 무효로 할 수 있다. 이 메소드를 사용해, 임의 또는 모든 오브젝트 클래스의 캐싱을 유효하게 할 수도 있다.

향후의 캐싱을 무효로 하지 않고 캐쉬를 소거하려면 ,IDirectMusicLoader8::ClearCache 메소드를 사용한다. 캐쉬는 로더가 해방되면(자) 자동적으로 소거되므로, 어플리케이션을 종료하기 전에 이 메소드를 호출할 필요는 없다. ClearCache 가 필요하게 되는 것은, 완전히 새로운 음색이나 사운드 파일을 사용해, 어플리케이션의 사운드 트랙을 완전하게 변경하는 경우 뿐이다.

일반적인 캐싱이 무효일 때, 1 개의 오브젝트를 캐쉬하려면 , 그 오브젝트를 IDirectMusicLoader8::CacheObject 메소드에 건네준다.

IDirectMusicLoader8::ReleaseObject 또는 IDirectMusicLoader8::ReleaseObjectByUnknown 메소드를 사용해 캐쉬로부터 오브젝트를 삭제해, 다음에 그 오브젝트에 대해서 GetObject 를 호출했을 때에, 그 오브젝트가 다시 로드 되는 것을 보증할 수 있다. 오브젝트, 특히 세그먼트(segment)에 대해 Release 를 호출하기 전에 이러한 메소드의 어느쪽이든을 호출하는 것은 좋은 생각이다. 이 호출을 실시하지 않았던 경우, 오브젝트에의 참조가 캐쉬내에 남아, 오브젝트는 계속 존재한다. 메모리를 소비 함과 동시에, 오브젝트는 특정 상태 정보를 보관 유지하는 경우가 있다. 세그먼트(segment)의 경우는, 향후 로드하는 인스턴스가 캐쉬로부터 로드 되어 시작 포인트와 루프 포인트가, 전의 인스턴스가 파기되었을 때 상태와 같게 된다.

캐쉬 관리의 상세한 것에 대하여는, 「가베지 콜렉션」을 참조할것.


가베지 콜렉션

로드 된 오브젝트를 캐싱 하면, 어플리케이션으로 많은 오브젝트를 로드하는 경우, 특히 다른 오브젝트를 참조하는 오브젝트를 로드하는 경우에, 메모리의 낭비로 연결되는 일이 있다.

디폴트의 경우와 같이, 자동적인 캐싱이 유효한 경우, 참조에 의해 로드 되는 오브젝트를 포함해IDirectMusicLoader8::GetObject 에 의해 로드 되는 각 오브젝트는 캐싱 된다. 예를 들어, 세그먼트(segment)에 대해 GetObject 를 호출하는 경우, 이 세그먼트(segment)에 스크립트에의 참조가 포함되어 있으면(자), 스크립트도 로드 되어 캐싱 된다.

다만,IDirectMusicLoader8::ReleaseObject 또는 IDirectMusicLoader8::ReleaseObjectByUnknown 를 호출했을 경우,GetObject 에 의해 로드 된 프라이머리 오브젝트만이 캐쉬로부터 삭제된다. 참조된 오브젝트는, 다른 오브젝트에 의해 사용중인가 어떤가에 관계없이 해방되지 않는다.

사용되어 있지 않은 오브젝트를 클린 업 하려면 ,IDirectMusicLoader8::CollectGarbage 를 호출한다. 이 메소드는,GetObject 에 의해 직접 로드 된 오브젝트, 및 그 오브젝트에 의해 참조되는 오브젝트를 제외해, 모든 오브젝트를 캐쉬로부터 해방한다. CollectGarbage 는, 로더의 오브젝트에의 COM 참조를 해방하는 것에 의해, 캐쉬로부터 오브젝트를 소거한다. 이 결과, 오브젝트의 참조 카운트가 0 이 되었을 경우는, 오브젝트는 파기되어 그 메모리는 다시 이용 가능하게 된다.

로드 된 오브젝트가 불필요하게 되었을 때에 메모리내에 남지 않게 하려면 , 다음의 처리를 실시할 필요가 있다.

  • GetObject 의 호출의 대상이 된 오브젝트에 대해,ReleaseObject 또는 ReleaseObjectByUnknown 를 호출한다.
  • CollectGarbage 를 호출해, 간접적으로 로드 된 오브젝트에의 로더의 참조를 해방한다.
  • 어플리케이션에 의해 보관 유지되고 있는 포인터에 대해 Release 를 호출한다.

오브젝트가 서로 순환 참조하고 있는 경우는 처리가 복잡하게 된다. 세그먼트(segment)에 스크립트 트럭 경유로 스크립트 오브젝트에의 참조가 포함되어 스크립트에 세그먼트(segment)에의 참조가 포함되어 있다고 한다. GetObject 를 호출해 세그먼트(segment)를 직접 로드하면(자), 스크립트가 간접적으로 로드 된다. 다음에,ReleaseObject 를 사용해 캐쉬로부터 세그먼트(segment)를 해방해, 어플리케이션의 세그먼트(segment)에의 참조에 대해 Release 를 호출한다. 스크립트 오브젝트에 의해 보관 유지된다, 세그먼트(segment)에의 COM 참조가 존재하므로, 이 세그먼트(segment)는 계속 존재한다. 이 경우, 스크립트는 캐쉬내외의 오브젝트에 의해 참조되지 않기 때문에, 가베지가 된다. 다만, 특수한 처리를 실시하지 않는 경우,CollectGarbage 는 로더의 스크립트에의 참조만을 해방한다. 이 때문에, 그 참조 카운트는 0 이 되지 않는다. 세그먼트(segment)와 스크립트는 계속 서로 참조하므로 , 양쪽 모두 캐쉬로부터 삭제되고 있는데, 메모리내에 계속 존재한다.

이 문제를 회피하기 위해서,CollectGarbage 는 오브젝트에 대해 내부 메소드를 호출해, 그 오브젝트가 다른 오브젝트에의 참조를 해방하도록(듯이) 강제한다. 위에의예에서는, 스크립트는 세그먼트(segment)에의 참조를 해방한다. 세그먼트(segment)의 참조 카운트가 0 이 되어, 세그먼트(segment) 자체를 파기할 경우에, 세그먼트(segment)는 스크립트에의 참조를 해방하므로, 로더가 스크립트에의 참조를 해방할 경우에, 스크립트는 그 자체를 파기할 수 있다.

그러나, 여기서 이제(벌써) 1 개(살) 문제가 있다. 어플리케이션이, 로더가 모르는 스크립트에의 인터페이스를 취득해, 이 포인터에 대한 Release 의 호출을 무시했다고 한다. 스크립트는 계속 존재하지만 , 의도했던 대로 동작하지 않는 경우가 있다. 이것은, 세그먼트(segment)에의 참조가 존재하지 않기 때문에이다. 이 스크립트에 대해 메소드를 호출하면, 치명적인 에러가 발생하는 경우가 있다. 이것을 회피하기 위해서,CollectGarbage 는 스크립트에 대한 모든 메소드가 DMUS_S_GARBAGE_COLLECTED 를 돌려주는 것을 보증하고 있다.

이 상황은, 대부분의 어플리케이션에 영향을 주지 않는다. 다만,CollectGarbage 에 의해 캐쉬로부터 소거된 오브젝트에 대해 메소드를 호출하는 경우, 예기 한 결과가 되지 않는 경우가 있는 것에 주의할 필요가 있다.

다음의 샘플 코드에서는, 세그먼트(segment)에의 참조를 포함한 스크립트를 로드하고 있다. m_pLoader 는 IDirectMusicLoader8 인터페이스로, m_pPerformance 는 IDirectMusicPerformance8 인터페이스이다. 이 예에서는, 스크립트로 루틴을 호출한 후, 캐쉬로부터 스크립트 오브젝트를 삭제해,CollectGarbage 를 호출해 세그먼트(segment) 오브젝트를 해방하고 있다. 세그먼트(segment)에 스크립트에의 참조가 포함되는 경우, 이 스크립트를 파기할 수 있도록(듯이) 스크립트가 해방되어 다음에 세그먼트(segment)가 해방되어 파기할 수 있게 된다.

// 스크립트를 로드해, 루틴을 호출한다.

IDirectMusicScript8 *pScript;

m_pLoader->GetObject(scriptdesc, IID_IDirectMusicScript8, &pScript);
pScript->Init(m_pPerformance, NULL);
pScript->CallRoutine(L"DoorSlam", NULL);

// 스크립트 오브젝트를 해방해, 가베지를 수집한다.

pLoader->ReleaseObjectByUnknown(pScript);
pLoader->CollectGarbage();
pScript->Release();


오브젝트의 설정

다음에 다른 오브젝트로부터 참조되는 오브젝트를, 참조원의 오브젝트를 로드할 때 로더를 취득할 수 있도록(듯이), 실제로는 로드하지 않고 , 그 자리소만을 로더에 지시하는 것이 바람직하다. 오브젝트에 새로운 속성을 주어, 로더가 속성을 사용해 오브젝트를 검색할 수 있도록(듯이) 할 수도 있다.

IDirectMusicLoader8::SetObject 메소드는, 파라미터로서 DMUS_OBJECTDESC 구조체를 받는다. 이 구조체에는, 2 개(살)의 주요한 정보가 포함된다.

  • 데이터에의 포인터. 파일 패스 또는 메모리의 블록에의 포인터가 된다. 「파일로부터의 오브젝트의 로드」 및 「리소스로부터의 오브젝트의 로드」를 참조할것.
  • 다음에 참조되었을 때에 사용하는, 오브젝트의 식별자. GUID 또는 이름이 된다. 나중에,IDirectMusicLoader8::GetObject 의 호출로, 같은 이름 또는 GUID 를 사용해, 저장 된 오브젝트가 검색된다. 오브젝트에 이미 존재하고 있는 GUID 또는 이름을 변경할 수 없다.

반환값으로서DMUS_OBJECTDESC 구조체에, 로더에 의해 수집된 오브젝트에 관한 추가 정보가 보관 유지되는 경우가 있다.

다음의 함수에서는, 리소스내의 이름이 붙지 않은 오브젝트 (MIDI 파일등)에 이름을 할당하고 있다.

// m_pLoader 는 유효한 IDirectMusicLoader8 인터페이스 포인터이다.

HRESULT SetObjectFromResource(const GUID* guid, int ID,
        char* type, WCHAR* name)
{
  HRSRC hResource = NULL;
  HGLOBAL hData = NULL;
  hResource = FindResource(g_hInstance, MAKEINTRESOURCE(ID), type);
  if (hResource ! = NULL)
  {
    hData = LoadResource(g_hInstance, hResource);
    if (hData ! = NULL)
    {
      DMUS_OBJECTDESC desc;
      if(m_pLoader && (hResource ! = NULL) && (hData ! = NULL))
      {
        ZeroMemory(&desc, sizeof(desc));
        desc.pbMemData = (BYTE*) LockResource(*hData);
        desc.llMemLength = SizeofResource(g_hInstance, (*hResource));
        desc.guidClass = (*guid);
        desc.dwSize = sizeof(desc);
        desc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_MEMORY;
        if (name)
        {
            wcscpy(desc.wszName, name);
            desc.dwValidData |= DMUS_OBJ_NAME;
        }
        return m_pLoader->SetObject(&desc);
      }
    }
  }
  return E_FAIL;
}

다음의 샘플 함수는,"MIDI" 타입의 리소스로서 저장 된 MIDI 파일에 이름을 할당할 때 사용할 수 있다.

SetObjectFromResource(CLSID_DirectMusicSegment, 101,
        "MIDI", "canyon");

이 이후, 오브젝트는 언제라도 이름을 사용해 로드할 수 있다.


사운드의 재생

여기에서는, DirectMusic 의 퍼포먼스의 기본적인 요소와 소스로부터 데이터를 취득해 출력하기 위해서 필요한 중요한 메소드를 소개한다.

설명하는 주제는, 다음과 같다.

  • 퍼포먼스의 생성
  • 세그먼트(segment)의 사용법
  • 밴드의 사용법
  • 타이밍
  • 통지와 이벤트의 처리


퍼포먼스의 생성

퍼포먼스 오브젝트는 재생 전반을 관리한다. 퍼포먼스 오브젝트는, 다음의 태스크를 실행한다.

  • 포토와 오디오 패스의 관리
  • 오디오 패스에의 채널의 매핑
  • 세그먼트(segment)의 연주와 정지
  • 메세지의 디스팟치
  • 툴과 타이밍의 관리

대부분의 어플리케이션은, 퍼포먼스 오브젝트를 1 개만 사용하지만, 마스터 템포나 볼륨등의 파라미터가 다른 복수의 퍼포먼스를 사용할 수도 있다.

다음의 샘플 코드에서는, 퍼포먼스를 1 개 생성 해,IDirectMusicPerformance8 인터페이스에의 포인터를 취득하고 있다.

IDirectMusicPerformance8* pPerf;

if (FAILED(CoCreateInstance(
        CLSID_DirectMusicPerformance,
        NULL,
        CLSCTX_INPROC,
        IID_IDirectMusicPerformance8,
        (void**) &pPerf
    )))
{
    pPerf = NULL;
}

생성 한 퍼포먼스는 초기화해야 한다. 추천 되고 있도록(듯이), 어플리케이션으로 오디오 패스를 사용하고 있는 경우는,IDirectMusicPerformance8::InitAudio 메소드를 호출하지 않으면 안 된다. 어플리케이션으로 이전의 채널과 포토의 매핑 모델을 사용하고 있는 경우는, 대신에 IDirectMusicPerformance8::Init 를 호출한다. 상세한 것에 대하여는, 「포토로부터 오디오 패스에의 이행」을 참조할것.

초기화에 있어서의 중요한 처리는, DirectMusic 오브젝트의 생성이다. 기존의 IDirectMusic8 인터페이스 포인터를 IDirectMusicPerformance8::InitAudio 에 건네줄 수도 있지만, 대부분의 경우 InitAudio 로 DirectMusic 오브젝트를 생성 하는 (분)편이 편리하다. 포토 및 master clock에 대해서 필요한 제어의 정도로 응해,IDirectMusic8 인터페이스에의 포인터를 취득할지 어떨지를 선택할 수도 있다. 대부분의 어플리케이션에서는,IDirectMusic8 의 메소드에 액세스 할 필요는 없기 때문에,InitAudio 의 ppDirectMusic 파라미터로서 NULL 를 건네줄 수가 있다.

InitAudio 는, 기존의 DirectSound 오브젝트를 취할 수도 있다. DirectSound 는 신디사이저로부터 출력된 사운드 데이터를 관리한다. 대부분의 경우,InitAudio 로 이 오브젝트를 생성 할 수 있다. 이 오브젝트에의 인터페이스는, DirectSoundCapture 오브젝트를 생성 하거나 DirectMusic 의 퍼포먼스는 아니고 버퍼내에서 직접 웨이브를 재생하는 등, DirectSound 를 다른 용도로 하지 않는 한 필요가 없다.

DMUS_AUDIOPARAMS 구조체를 InitAudio 에 건네주는 것에 의해, 어플리케이션은 신디사이저의 기능을 요구하거나 디폴트 이외의 신디사이저를 설정할 수 있다. 대부분의 어플리케이션에서는, 이 처리의 필요는 없다.

다음의 샘플 코드에서는, DirectMusic 및 DirectSound 오브젝트에의 포인터를 취득하지 않고 , 퍼포먼스를 초기화하고 있다. 16 의 퍼포먼스 채널과 포토상에서 사용 가능한 모든 기능을 가지는, 디폴트의 표준 오디오 패스를 생성 한다.

// hWnd 는 어플리케이션 윈도우 핸들이다.

if (SUCCEEDED(pPerf->InitAudio(NULL, NULL, hWnd,
        DMUS_APATH_SHARED_STEREOPLUSREVERB, 16,
        DMUS_AUDIOF_ALL, NULL)))
{
    // 퍼포먼스의 초기화.
}


세그먼트(segment)의 사용법

세그먼트(segment)는, DirectMusic 의 퍼포먼스로 연주 가능한 데이터의 기본 단위이다. 세그먼트(segment)는 IDirectMusicSegment8 인터페이스에 의해 나타내진다.

어플리케이션에서는, 다음의 몇개의 방법으로 세그먼트(segment) 오브젝트를 생성 할 수 있다.

  • IDirectMusicSegment8 인터페이스를 지원 하는 파일 또는 리소스 오브젝트를 로드한다. 상세한 것에 대하여는, 「오디오 데이터의 로드」를 참조할것.
  • IDirectMusicStyle8::GetMotif 메소드를 사용해, 스타일로부터 모티프를 취득한다.
  • IDirectMusicComposer8 인터페이스의 메소드를 사용해, 실행시에 어레인지 또는 트란지션을 생성 한다. 「어레인지용의 프로그래밍 개요」 및 「트란지션의 사용법」을 참조할것.
  • IDirectMusicSegment8::Clone 메소드를 사용해, 기존의 세그먼트(segment)의 카피를 생성 한다.
  • IDirectMusicBand8::CreateSegment 메소드를 사용한다. 이 메소드에 의해, 밴드 체인지의 생성인 만큼 사용되는, 특수한 세칸다리세그먼트가 생성 된다. 「프로그램에 의한 밴드 체인지의 실행」을 참조할것.
  • IDirectMusicPatternTrack8::CreateSegment 메소드를 사용해, 패턴 트럭 오브젝트로부터 세그먼트(segment)를 생성 한다. 대부분의 어플리케이션에서는 이 처리는 필요가 없다. 패턴 트럭은, 보통, 최초로 세그먼트(segment)로부터 생성 되기 때문이다.
  • 기존의 트럭으로부터 세그먼트(segment)를 구축한다. CoCreateInstance 를 호출해 세그먼트(segment) 오브젝트를 생성 해, 다음에 IDirectMusicSegment8::InsertTrack 를 호출해 트럭을 추가한다. 이 방법은, 대부분의 어플리케이션으로 사용되지 않는다.

각 세그먼트(segment)은 1 개 또는 복수의 트럭에 의해 구성되어 각 트럭은 IDirectMusicTrack8 인터페이스에 의해 나타내진다. 트럭은, 세그먼트(segment)의 데이터의 대부분을 보관 유지해, 데이터는, 노트 이벤트, 밴드 체인지, 템포 체인지, 또는 그 외의 타임 이벤트로 구성된다. 트럭은 세그먼트(segment) 오브젝트를 통해 관리되기 (위해)때문에, 어플리케이션은 일반적으로 이러한 인터페이스를 필요로 하지 않는다. 상세한 것에 대하여는, 「DirectMusic 트럭」을 참조할것.

세그먼트(segment)는, 퍼포먼스로 다른 역할을 완수하는 경우가 있다. 항상 필요한프라이머리 세그먼트(segment)는, 사운드 트랙의 주된 내용을 제공해, 보통,제어 세그먼트(segment)로서 기능한다. 세칸다리세그먼트는 프라이머리 세그먼트(segment)와 함께 연주되어 사운드 이펙트나 짧은 테마를 제공한다. 특수한 타입의 세칸다리세그먼트로서모티프가 있어, 항상 DirectMusic 스타일 오브젝트로부터 취득된다.

게다가 특수한 역할을 가지는 3 종류의 세그먼트(segment)가 있다.

  • 트란지션세그먼트. 실행시에 DirectMusic 작곡가 오브젝트에 의해 생성 되는 짧은 음악의 트란지션으로, 보통, 어느 세그먼트(segment)로부터 다른 세그먼트(segment)에, 또는 세그먼트(segment)로부터 무음에 이행 하는 프라이머리 세그먼트(segment)로서 연주된다.
  • 밴드 세그먼트(segment). 퍼포먼스내의 다양한 채널용의 일련의 음색 및 음색 세그먼트(segment). 어플리케이션은 밴드 세그먼트(segment)를 세칸다리세그먼트로서 연주해, 음악을 연주하는 밴드로 변경을 더할 수가 있다.
  • 템플릿 세그먼트(segment). 코드 진행,홈 레벨, 및 장식등의 가이드로서 실행시에 스타일이나 코드 맵과 함께 짜 합쳐져 음악을 형성한다.

세그먼트(segment)의 재생은 퍼포먼스 오브젝트에 의해 제어되어IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 의 호출로 시작 된다.

퍼포먼스내에서는, 다만 1 개의 프라이머리 세그먼트(segment)를 연주할 수 있다. 재생의 목적으로 프라이머리 세그먼트(segment)를 삽입하는 경우는, 현재 연주되고 있는 세그먼트(segment)가 끝난 후에 그 세그먼트(segment)를 연주하도록(듯이) 지정하거나 현재의 프라이머리 세그먼트(segment)를 옮겨놓을 수가 있다.

한편, 세칸다리세그먼트는 프라이머리 세그먼트(segment)상에서 연주되어 임의의 수의 세칸다리세그먼트를 동시에 연주할 수 있다.

보통, 세칸다리세그먼트는 프라이머리 세그먼트(segment)의 퍼포먼스를 변경하지 않는다. 예를 들어, 세칸다리세그먼트는, 프라이머리 세그먼트(segment)의 스타일에 영향을 주지 않고 , 다른 스타일에 근거할 수가 있다. 다만, 세칸다리세그먼트를 제어 세그먼트(segment)로서 지정할 수 있다. 이 경우, 세칸다리세그먼트는, 보통 프라이머리 세그먼트(segment)로 처리되는 특정의 태스크를 실행한다.

세그먼트(segment)의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 세그먼트(segment) 상태
  • 제어 세그먼트(segment)
  • 자기 제어 세그먼트(segment)
  • 웨이브 세그먼트(segment)

「세그먼트(segment)의 타이밍」도 참조할것.


세그먼트(segment) 상태

세그먼트(segment)를 연주하는 경우, 오디오 패스, 반복, 시작 포인트 등, 그 세그먼트(segment)의 파라미터는 IDirectMusicSegmentState8 인터페이스로 나타내지는 세그먼트(segment) 상태에 저장 된다. 파라미터는, 세그먼트(segment)의 그 인스턴스에 대한 보고 유효하다. IDirectMusicSegment8 의 메소드를 사용해, 세그먼트(segment)에 대해서 간 변경은,IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 의 호출에 의해 생성 되는 새로운 세그먼트(segment) 상태에 반영된다.

세그먼트(segment)가 다른 인스턴스가 다른 오디오 패스로 재생되고 있는 경우, 세그먼트(segment) 상태를 사용해, 3D 사운드 버퍼나 이펙트를 취득하거나 그 인스턴스에게만 적용되는 변경을 실시할 수가 있다. 예를 들어, 레이싱 게임에서, 각자 동차의 사운드를 독자적인 오디오 패스로 재생하는 것에 의해, 복수의 자동차로 같은 엔진음을 사용할 수 있다. IDirectMusicAudioPath8::GetObjectInPath 또는 IDirectMusicSegmentState8::GetObjectInPath 의 어느쪽이든을 사용해, 각 오디오 패스로부터 IDirectSound3DBuffer8 인터페이스를 취득하는 것에 의해, 각자 동차의 3D 파라미터를 개개로 설정할 수 있다.


제어 세그먼트(segment)

제어 세그먼트(segment)는, 트럭간에 공유되는 데이터의 소스이다. 다음의 트럭은, 다른 트럭과는 달라, 메세지를 송신하는 것이 아니라, 파라미터의 호출해에 응답하는 것에 의해, 퍼포먼스에 데이터를 건네준다.

  • 코드.
  • 커멘드.
  • 뮤트.
  • 템포.
  • 박자 기호.

예를 들어, 코드 트럭은 스타일 트럭으로부터의 파라미터의 호출해에 응답한다. 노트를 송신하기 전에 그 노트의 MIDI 값을 결정하려면 , 스타일 트럭으로 현재의 코드를 결정하지 않으면 안 된다. 스타일 트럭은 IDirectMusicPerformance8::GetParam 를 호출하는 것에 의해 이 처리를 실시해, 이 호출은 제어 세그먼트(segment)의 코드 트럭에 인계된다.

제어 세그먼트(segment)로서 기능하려면, 세그먼트(segment)에 1 개 이상의 제어 트럭이 필요하다. 뮤트, 커멘드, 템포, 및 코드의 트럭이 제어 트럭이다.

제어 세그먼트(segment)는, 메세지에 의해 제어되는 재생에는 영향을 주지 않는다. 제어 세그먼트(segment)의 박자 기호가 사용되는 것은, 박자 기호 트럭이 없는 경우 뿐이다. 이것은, 보통, 세그먼트(segment)가 MIDI 파일에 근거하지 않은 경우이다.

디폴트에서는, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. 다만, DMUS_SEGF_CONTROL 플래그를 IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 에 건네주는 것에 의해, 세칸다리세그먼트를 제어 세그먼트(segment)로서 지정할 수 있다.

세칸다리세그먼트가 제어 세그먼트(segment)인 경우도, 프라이머리 세그먼트(segment)는 제어 데이터의 대체 소스로서 계속 기능한다. 예를 들어, 세칸다리 제어 세그먼트(segment)에 템포 트럭이 포함되지 않은 경우에, 프라이머리 세그먼트(segment)에 포함되어 있는 경우는, 프라이머리 세그먼트(segment)의 템포가 사용된다.

상세한 것에 대하여는, 다음의 주제를 참조할것.

  • DMUS_SEGF_FLAGS
  • 트럭 구성


자기 제어 세그먼트(segment)

자기 제어 세그먼트(segment)는, 자기 제어 세그먼트(segment)로부터 제어 정보를 카피하는제어 세그먼트(segment)로부터의 제어 정보를 무시한다. 예를 들어, 세그먼트(segment)에 커멘드 트럭이 있는 경우, 제어 세그먼트(segment)로 설정된 홈 레벨은 아니고, 독자적인 홈 레벨을 사용할 수 있다.

세그먼트(segment)는, 다음과 같이, 각 트랙에 도착해 제어 정보를 취득하는 장소를 정의할 수 있다.

  • 제어 세그먼트(segment)의 트럭으로부터. 이것은 디폴트의 동작이다.
  • 프라이머리 세그먼트(segment)의 트럭으로부터. 프라이머리 세그먼트(segment)가 제어 세그먼트(segment)일지 어떨지는 관계없다.
  • 같은 세그먼트(segment)의 트럭으로부터.

세그먼트(segment)는, 보통, 작가에 의해 자기 제어 세그먼트(segment)로서 구성된다. 다만, 어플리케이션으로,IDirectMusicSegment8::SetTrackConfig 또는 IDirectMusicSegmentState8::SetTrackConfig 메소드를 사용해, 다음의 플래그를 설정 또는 클리어 해, 세그먼트(segment)내의 개개의 트럭을 구성할 수 있다.

DMUS_TRACKCONFIG_OVERRIDE_ALL
트럭은, 제어 세그먼트(segment)나 프라이머리 세그먼트(segment)의 트럭의 전에, 이 세그먼트(segment)로부터 파라미터를 취득한다.
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
트럭은, 프라이머리 세그먼트(segment)의 트럭의 전에, 이 세그먼트(segment)로부터 파라미터를 취득한다.
DMUS_TRACKCONFIG_FALLBACK
세그먼트(segment)는, 프라이머리 세그먼트(segment)나 제어 세그먼트(segment)로부터 필요한 정보가 돌려주어지지 않은 경우에, 이 세그먼트(segment)로부터 파라미터를 취득한다.

다음의 샘플 코드에서는, 스타일 트럭이 모든 파라미터를 같은 세그먼트(segment)외의 트럭으로부터 취득하도록 지시해, 제어 세그먼트(segment)의 코드, 홈 레벨, 뮤트 커멘드를 사용하지 않게 하고 있다. pSegment 는 IDirectMusicSegment8 인터페이스 포인터이다.

HRESULT hr = pSegment ->SetTrackConfig(CLSID_DirectMusicStyleTrack,
        -1, DMUS_SEG_ALLTRACKS, DMUS_TRACKCONFIG_OVERRIDE_ALL, 0);

상세한 것에 대하여는, 「트럭 구성」을 참조할것.


웨이브 세그먼트(segment)

DirectMusic 로더는, 오디오 압축 매니저 (ACM)로 지원 되고 있는 포맷의 압축된 웨이브 폼 오디오 파일, 및 비압축 웨이브 파일을 로드할 수 있다.

웨이브 파일에 근거하는 세그먼트(segment)는, 다른 세그먼트(segment)와 같게 연주된다. 이러한 세그먼트(segment)는,DMUS_WAVE_PMSG 메세지로서 퍼포먼스에게 건네져 항상 오디오 패스의 채널 0 으로 연주된다. 웨이브에 대해서는 노트와는 다른 의미의 합성을 하지만, 웨이브도 신디사이저에게 건네져, MIDI 콘트롤러로 조작할 수 있다.

웨이브도 또 DirectMusic Producer 파일에 묻어, 다양한 바리에이션이 있는 스타일과 같이 동작시킬 수가 있다. 예에 대해서는, AudioScripts 샘플 어플리케이션을 참조할것. 이 샘플의 ScriptDemoBaseball.spt 스크립트는, 버튼이 클릭될 때마다 행상의 큰 소리로 외치는 소리의 바리에이션을 재생한다.

세그먼트(segment) (. sgt) 파일의 웨이브는, 재생하기 전에 다운로드할 필요가 있다. 세그먼트(segment)의 밴드를 다운로드 하면, 이러한 웨이브도 다운로드된다. 상세한 것에 대하여는, 「밴드의 다운로드와 언로드」를 참조할것.


밴드의 사용법

밴드란, 세그먼트(segment) 또는 스타일내의 특정의 파트에 할당할 수 있었던 일련의 음색이다. 연주시에 각 음색 트럭은, 다음의 정보를 보존하고 있는 퍼포먼스 채널에 맵 된다.

  • MIDI 볼륨.
  • MIDI 빵.
  • 전조. 이 값이 0 이 아닌 경우, 채널 위에의 음악의 노트는, 음색에 맞추어 자동적으로 전치 된다.
  • 음색의 MIDI 패치 번호. 뱅크 셀렉트의 MSB 와 LSB 도 포함된다.
  • 음색의 로드원이 되는 DLS 콜렉션에의 참조. 디폴트의 DLS 콜렉션은, 스탠다드 General MIDI 콜렉션이다.

세그먼트(segment)와 스타일은 항상, 적어도 디폴트 밴드로 불리는 1 개의 밴드에 의해 구성된다. 스타일에는, 추가의 밴드를 포함할 수가 있다. 세그먼트(segment) 또는 스타일을 로드할 때, 디폴트 밴드 및 그 외의 밴드는, 어느쪽이나 자동적으로 로드 된다. 다만, 어떤 밴드를 사용하는 경우에서도, 밴드의 음색용으로 DLS 데이터를 다운로드해야 한다.

IDirectMusicStyle8::GetDefaultBand 메소드를 사용해, 디폴트 밴드에의 포인터를 취득할 수가 있다.

스타일에 오쏘링 된 그 외의 밴드는,IDirectMusicStyle8::EnumBand 및 IDirectMusicStyle8::GetBand 메소드를 사용해, 검색 및 취득할 수가 있다. 밴드는, 다른 스타일 파일이나 밴드 파일로부터도 취득할 수 있다. IDirectMusicBand8 인터페이스를 취득한 후, 이 밴드에 액세스 해, 디폴트의 밴드를 옮겨놓을 수도 있다.

밴드는, 다른 오브젝트와 같게 로드 된다. 상세한 것에 대하여는, 「오디오 데이터의 로드」를 참조할것.

밴드의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 밴드의 다운로드와 언로드
  • 프로그램에 의한 밴드 체인지의 실행
  • 확실한 타이밍에서의 밴드 체인지
  • 커스텀 음색에 의한 MIDI 파일의 연주


밴드의 다운로드와 언로드

밴드를 사용하려면 , 우선 참조하는 음색을 퍼포먼스에 다운로드해야 한다. 이 순서에 의해, 음색이 퍼포먼스 채널에 할당할 수 있어 신디사이저에 DLS 데이터가 다운로드된다.

디폴트에서는, 사용하는 밴드의 다운로드는 어플리케이션이 실시한다. 다만, 밴드의 자동 다운로드를 유효하게 할 수도 있다.

밴드의 다운로드에 의해, 퍼포먼스가 밴드를 이용할 수 있게 되지만, 프로그램 체인지는 행해지지 않는다. 프로그램 체인지는, 세그먼트(segment)의 밴드 트럭으로 생성되는 메세지에 응해 실행된다. 이 메세지는, 일반적으로는 세그먼트(segment) 파일에 오쏘링 된다. 실행시에 프로그램 체인지를 실시하는 방법에 대해서는, 「프로그램에 의한 밴드 체인지의 실행」을 참조할것.

밴드의 다운로드와 언로드를 이행 하는 방법에 대해서는, 다음의 주제를 참조할것.

  • 밴드의 자동 다운로드
  • 밴드의 수동 다운로드
  • 패치의 경합
  • 밴드의 언로드


밴드의 자동 다운로드

자동 다운로드가 유효한 경우, 밴드에 포함되는 세그먼트(segment)가 큐에 저장 될 때, 밴드의 음색이 다운로드된다. 세그먼트(segment)가 정지되면(자), 같은 음색을 사용하고 있는 것 외의 세그먼트(segment)를 즉시 큐에 넣어 연주하는지, 현재 연주중이 아닌 한, 음색은 자동적으로 언로드된다.

자동 다운로드는, 세그먼트(segment)의 타이밍이 중요하지 않을 때에만 사용해야 하는 것이다. 음색의 로드와 언로드를 반복하면(자) 시간이 걸려, 복잡한 오디오 환경에서는, 중대한 퍼포먼스의 저하가 발생하는 경우가 있다.

자동 다운로드 메카니즘의 일부인 자동 언로드에서도, 바라지 않은 결과가 되는 경우가 있다. 예를 들어, 채널의 음색을 변경하는 짧은 세칸다리세그먼트를 연주하는 경우를 생각한다. 세칸다리세그먼트가 시작 될 때, 음색이 자동적으로 다운로드되어 기존의 음색으로 옮겨진다. 세칸다리세그먼트가 종료 하면, 음색은 자동적으로 언로드되어 그 결과, 채널에 음색이 없어져, 그 채널은 무음을 재생한다.

밴드의 자동 다운로드는, 다음의 몇개의 방법으로 유효하게 할 수 있다.

  • GUID_PerfAutoDownload 파라미터를 사용해 IDirectMusicPerformance8::SetGlobalParam 메소드를 호출한다. 「글로벌 파라미터의 설정과 취득」을 참조할것.
  • GUID_Enable_Auto_Download 파라미터를 사용해,IDirectMusicSegment8::SetParam 메소드를 호출하는 것에 의해, 단일의 세그먼트(segment)의 자동 다운로드를 유효하게 한다. 「트럭 파라미터의 설정과 취득」을 참조할것.

다음의 샘플 코드에서는, 퍼포먼스 pPerf 의 글로벌 파라미터를, 밴드의 자동 다운로드가 유효하게 되도록(듯이) 설정해 있다.

BOOL fAuto = TRUE;
pPerf->SetGlobalParam(GUID_PerfAutoDownload, &fAuto, sizeof(BOOL));


밴드의 수동 다운로드

다음의 몇개의 방법을 사용하면(자), 밴드를 수동으로 다운로드할 수가 있다.

  • IDirectMusicSegment8::Download 를 호출해, 세그먼트(segment)의 밴드와 웨이브를 오디오 패스 또는 퍼포먼스의 어딘가에 다운로드한다.
  • 로드 된 오브젝트로부터 IDirectMusicBand8 인터페이스를 취득해,IDirectMusicBand8::Download 메소드를 호출한다
  • GUID_Download 또는 GUID_DownloadToAudioPath 파라미터를 사용해 IDirectMusicSegment8::SetParam 메소드를 호출해, 세그먼트(segment)의 최초의 밴드 트럭에 밴드를 다운로드한다. IDirectMusicPerformance8::SetParam 를 사용해, 프라이머리 세그먼트(segment)으로 이 파라미터를 설정하거나IDirectMusicTrack8::SetParamEx 를 사용해, 직접 밴드 트럭을 설정할 수도 있다. 「트럭 파라미터의 설정과 취득」을 참조할것.

어플리케이션이 복수의 신디사이저, 즉 복수의 포토를 사용하는 오디오 패스를 생성 하는 경우, 퍼포먼스는 아니고, 여기의 오디오 패스에 밴드를 다운로드해야 한다. 다만, 대부분의 어플리케이션에서는 신디사이저를 1 개만 사용하므로, 모든 음색 데이터를 퍼포먼스에 다운로드해도 안전하다.

복수의 오디오 패스는, 보통 같은 신디사이저를 공유한다. 밴드를 오디오 패스에 다운로드 하면, 음색 데이터는 그 오디오 패스 위에의 포토에 다운로드되어 같은 포토를 사용하는 모든 오디오 패스로 이용할 수 있게 된다. 데이터를 각 오디오 패스에 다운로드할 필요는 없다.

예를 들어, 레이싱 게임에서 차의 엔진음의 DLS 음색을 사용하는 세그먼트(segment)가 있다고 한다. 레이스의 각자 동차의 3D 파라미터를 개개에 조작하기 위해서, 복수의 오디오 패스로 사운드를 재생한다. 이 음색은, 한 번만 다운로드할 필요가 있다.

같은 음색을 반복해 다운로드해도 문제는 생기지 않는다. 1 개의 밴드내에 있는 음색이 몇번이나 나타나는 경우나, 복수의 밴드를 동시에 열어 다운로드할 경우에 같은 음색이 이러한 밴드로 사용되고 있는 경우에서도, 그 음색의 데이터는 1 회만 신디사이저에 송신된다.

다음의 함수는, 디스크로부터 밴드를 로드해, 그 밴드를 퍼포먼스에 다운로드한다.

HRESULT myDownloadBand(
    IDirectMusicLoader8 *pILoader,      // 로더 인터페이스.
    IDirectMusicBand8 **ppBand,         // 포인터를 취득하기 위해(때문에).
    IDirectMusicPerformance8 *pPerf,    // 밴드를 사용하는 퍼포먼스.
    WCHAR *pwszFile)                    // 로드하는 파일.
{
    HRESULT hr;
    DMUS_OBJECTDESC Desc;

    // 밴드 오브젝트의 파일명과 GUID 를 사용해,
    // Desc 를 초기화하는 것으로부터 시작 한다.

    wcscpy(Desc.wszFileName, pwszFile);
    Desc.dwSize = sizeof(Desc);
    Desc.guidClass = CLSID_DirectMusicBand;
    Desc.dwValidData = DMUS_OBJ_CLASS |
            DMUS_OBJ_FILENAME | DMUS_OBJ_FULLPATH;

    hr = pILoader->GetObject(&Desc, IID_IDirectMusicBand8,
            (void **) ppBand);
    if (SUCCEEDED(hr))
    {
        hr = (*ppBand) ->Download(pPerf);
    }
    return hr;
}


패치의 경합

다른 세그먼트(segment)의 밴드를 같은 포토에 다운로드 하면, 밴드내의 음색에 의해, 이전에 다운로드한 밴드의 데이터가 덧쓰기되는 경우가 있다.

예를 들어, 세그먼트(segment) A 가 피아노를 패치 번호 1 에 할당하는 밴드를 사용해, 세그먼트(segment) B 가 밴조를 같은 패치에 할당하는 밴드를 사용 하면 한다. 어플리케이션은, 최초로 세그먼트(segment) A, 다음에 세그먼트(segment) B 에 대해 IDirectMusicSegment8::Download 를 호출한다. 밴드가 다른 오디오 패스에 다운로드되었을 경우에서도, 음색 데이터는 같은 신디사이저에 다운로드되므로, 퍼포먼스 채널의 모든 노트는, 밴조에 의해 연주되는 패치 번호 1 에 맵 된다.

컨텐츠를 오쏘링 할 경우에는, 이러한 잠재적인 패치의 경합을 고려할 필요가 있다. 복수의 세그먼트(segment)로, 같은 패치 번호가 다른 음색을 사용해서는 안된다.


밴드의 언로드

밴드는 메모리를 소비하기 위해(때문에), 사용하지 않게 된 밴드는 언로드해야 하는 것이다. 자동 다운로드를 유효하게 하고 있는 경우는, 세그먼트(segment)가 종료했을 때에, 세그먼트(segment)에 관련지을 수 있고 있는 밴드가 자동적으로 언로드된다. 그렇지 않은 경우는, 다음의 몇개의 방법을 사용해, 수동으로 밴드를 언로드할 수가 있다.

  • 대응하는 Download 메소드로 다운로드된 음색에 대해,IDirectMusicSegment8::Unload 또는 IDirectMusicBand8::Unload 메소드를 호출한다.
  • GUID_Unload 또는 GUID_UnloadFromAudioPath 파라미터를 사용해 IDirectMusicSegment8::SetParam 메소드를 호출해, 세그먼트(segment)의 밴드 트럭에 있는 밴드를 언로드한다. IDirectMusicPerformance8::SetParam 를 사용해, 프라이머리 세그먼트(segment)으로 이 파라미터를 설정하거나IDirectMusicTrack8::SetParamEx 를 사용해, 직접 밴드 트럭을 설정할 수도 있다. 「트럭 파라미터의 설정과 취득」을 참조할것.

IDirectMusicPerformance8::CloseDown 메소드에서도, 다운로드된 나머지의 음색이 언로드된다.


프로그램에 의한 밴드 체인지의 실행

보통은, 로드 된 세그먼트(segment)의 밴드 트럭에 의해, 프로그램 체인지가 실행된다. 다만, 수동으로 실시할 수도 있다.

우선,IDirectMusicBand8::CreateSegment 메소드를 호출해, 세칸다리세그먼트를 생성 한다. 다음에,IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 를 호출해, 생성 한 세그먼트(segment)를 연주한다. 보통은 dwFlags 파라미터내의 DMUS_SEGF_MEASURE 또는 DMUS_SEGF_GRID 를 사용해, 적절한 경계에서 밴드 체인지가 유효하게 되도록(듯이) 보증한다.

다음의 샘플 함수에서는, 밴드로부터 세그먼트(segment)를 생성 해, 그 세그먼트(segment)를 연주하고 있다. 음색이 다운로드가 끝난 상태인지, 자동 다운로드가 유효하게 되어 있으면(자) 가정하고 있다.

HRESULT myPlayBand(
    IDirectMusicBand8 *pBand,          // 밴드 오브젝트에의 포인터.
    IDirectMusicPerformance8 *pPerf,   // 밴드를 사용하는 퍼포먼스.
    REFERENCE_TIME rfTime,             // 연주되는 타임.
    DWORD dwFlags)                     // 퍼포먼스 플래그.
{
    IDirectMusicSegment *pSegment;

// QI 가 필요한 IDirectMusicSegment8 는 필요하지 않다.

    HRESULT hr = pBand->CreateSegment(&pSegment);
    if (SUCCEEDED(hr))
    {
        hr = pPerf->PlaySegment(pSegment,
                dwFlags | DMUS_SEGF_SECONDARY,
                rfTime,
                NULL);
        pSegment->Release();
    }
    return hr;
}

퍼포먼스는, 한 번에 복수의 밴드의 음색을 연주할 수가 있다. 예를 들어, 어플리케이션이 1 개의 밴드를 사용해 프라이머리 세그먼트(segment)를 연주하고 있을 때, 다른 밴드를 가지는 스타일의 모티프를 연주하는 경우를 생각한다. 2 개의 밴드의 음색이 다른 퍼포먼스 채널에 맵 되고 있는 한, 경합은 발생하지 않는다. 다만, 보통, 모티프 세그먼트(segment)는 독자적인 밴드 트럭을 가지지 않는다. 따라서, 최초로 밴드 세그먼트(segment)를 생성 하고 나서 연주하지 않으면, 모티프의 퍼포먼스 채널로부터는 소리가 나오지 않는다


확실한 타이밍에서의 밴드 체인지

밴드 세그먼트(segment)를 연주할 경우에 중요한 문제가 되는 것은, 스타일 트럭으로 연주되는 노트의 타이밍의 격차이다. 예를 들어, 소절 1 의 1 박목의 노트가, 실제의 박의 경계에서(보다) 조금 진행되거나 늦거나 하는 경우가 있다. 밴드 세그먼트(segment)에서는 이 상황을 인식하고 있지 않았기 때문에, 몇개의 노트가 잘못한 음색으로 연주되는 경우가 있다.

이 문제를 피하기 위해서(때문에), 어플리케이션은 밴드 세그먼트(segment)를 빨리 큐에 저장 해야 하는 것이다. 예를 들어, 스타일 세그먼트(segment)의 pStyleSeg 와 밴드 세그먼트(segment)의 pBandSeg 가 있을 때, 퍼포먼스 (pPerf)의 다음의 소절 경계에서, 스타일 세그먼트(segment)와 밴드 세그먼트(segment)의 양쪽 모두를 연주하는 경우를 생각한다. 스타일에는, 세그먼트(segment)의 시작 타임보다, 최대 30 틱 (뮤직 타임에) 빨리 시작 될 가능성이 있는 노트가 포함되어 있는 것을 알 수 있고 있다. 다음의 샘플 코드에서는, 밴드 세그먼트(segment)가 스타일 세그먼트(segment)보다 31 틱전에 연주되는 것이 보증되고 있다. 따라서, 모든 음색은, 노트가 연주되기 전에 적절히 설정된다.

// 우선, 다음의 소절의 타임을 취득해,
// 뮤직 타임으로 변환한다.

REFERENCE_TIME rtResolved;
MUSIC_TIME mtResolved;

pPerf->GetResolvedTime( 0, &rtResolved, DMUS_TIME_RESOLVE_MEASURE );
pPerf->ReferenceToMusicTime( rtResolved, &mtResolved );

// 밴드 세그먼트(segment)를, 소절 경계의 31 틱전에 연주한다.

mtResolved -= 31;
pPerf->PlaySegment(pBandSeg, 0, mtResolved, NULL);

// 스타일 세그먼트(segment)를 소절 경계에서 연주한다.

pPerf->PlaySegment(pStyleSeg, DMUS_TIME_RESOLVE_MEASURE, 0, NULL);

주 세그먼트(segment)로 연주되는 노트에 격차가 없는 경우 (예를 들어, MIDI 파일로부터 로드 된 세그먼트(segment)의 경우)는, 동시에 연주되는 밴드 세그먼트(segment)의 타이밍에 대해 주의할 필요는 없다. 디폴트에서는, 모든 밴드 세그먼트(segment)는 1 틱 빨리 시작 된다.


커스텀 음색에 의한 MIDI 파일의 연주

MIDI 파일을 연주하는 경우, 디폴트에서는, Gm.dls 파일에 포함되는 Roland GM/GS Sound Set 의 음색이 사용된다. 다만, MIDI 파일을 연주할 경우에, 임의의 DLS 콜렉션의 음색을 사용할 수 있다.

우선, 콜렉션을 로드해,IDirectMusicCollection8 인터페이스에의 포인터를 취득한다.

다음의 함수의 예에서는, 파일명을 사용해 콜렉션을 로드하고 있다.

HRESULT LoadCollectionByName(
        IDirectMusicLoader8 *pILoader,
        char *pszFileName,
        IDirectMusicCollection8 **ppICollection)
{
    HRESULT hr;
    DMUS_OBJECTDESC Desc;             // 디스크립터.

    // 콜렉션 오브젝트의 파일명과 GUID 를 사용해,
    // Desc 를 초기화하는 것으로부터 시작 한다.
    // 파일명은 char 캐릭터 라인으로부터 시작되므로,
    // Unicode 로 변환한다.

    mbstowcs(Desc.wszFileName, pszFileName, DMUS_MAX_FILENAME);
    Desc.dwSize = sizeof(DMUS_OBJECTDESC);
    Desc.guidClass = CLSID_DirectMusicCollection;
    Desc.dwValidData = DMUS_OBJ_CLASS
            | DMUS_OBJ_FILENAME
            | DMUS_OBJ_FULLPATH;

    hr = pILoader->GetObject(&Desc,
            IID_IDirectMusicCollection8,
            (void **) ppICollection);
    return hr;
}

다음에,IDirectMusicSegment8::SetParam 를 호출해, DLS 데이터를 세그먼트(segment)에 접속한다. 다음의 샘플 코드는, 세그먼트(segment)와 LoadCollectionByName 함수로부터 돌려주어지는 콜렉션을 접속하는 방법을 나타낸다.

// pSegment 는 MIDI 파일로부터 생성 되어
// pLoadedCollection 는 유효한 IDirectMusicCollection8 포인터이라고 가정한다.

HRESULT hr = pSegment->SetParam(GUID_ConnectToDLSCollection,
        0xFFFFFFFF, 0, 0,
        (void*) pLoadedCollection);

마지막으로,IDirectMusicSegment8::Download 를 호출하는 것에 의해, 콜렉션내의 음색을 퍼포먼스 또는 오디오 패스에 다운로드한다.

MIDI 세그먼트(segment)에 커스텀 콜렉션을 부가할 경우에, GM 콜렉션에의 접속은 절단 되지 않는다. 예를 들어, 패치 번호가 12 의 1 개의 음색을 포함한 콜렉션을 로드해, 이것을 세그먼트(segment)에 접속하는 경우, 12 이외의 패치 번호를 가지는 MIDI 채널에서는, GM 콜렉션의 적절한 음색을 사용해 연주가 계속된다.

콜렉션의 상세한 것에 대하여는, 「음색 콜렉션의 사용법」을 참조할것.


타이밍

여기에서는, DirectMusic 의 다양한 타이밍의 개요에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • master clock
  • 클락 타임과 뮤직 타임
  • 템포의 변경
  • 준비 시간
  • 지연 시간과 범퍼 시간
  • 세그먼트(segment)의 타이밍


master clock

정확한 타이밍과 받아들이고 가능한 짧은 지연 시간을 보증하기 위해서, DirectMusic 는 master clock를 커넬 모드에 이행 하고 있다. 이 클락은, 하드웨어 타이머에 근거하고 있다. DirectMusic 에서는, 시스템 클록이 자동적으로 master clock로서 선택되지만, 어플리케이션에서는 사운드 카드의 웨이브 출력 크리스탈등의 다른 클락을 선택할 수가 있다.

master clock는 고분해가능의 타이머이며, DirectMusic 를 사용하는 프로세스, 디바이스, 및 어플리케이션은 이 클락을 공유한다. 이 클락은, 시스템내의 모든 오디오 재생을 동기화하기 위해서(때문에) 사용된다. 이것은, 표준적인 IReferenceClock 인터페이스이다. IReferenceClock::GetTime 메소드는, 현재의 타임을 100 나노초단위의 64 비트 정수로서 돌려준다 (REFERENCE_TIME 형으로서 정의되고 있다).

master clock에의 인터페이스를 취득하려면 ,IDirectMusic8::GetMasterClock 메소드를 사용한다.

어플리케이션으로 다른 master clock도 선택할 수 있다. 다만, master clock를 선택할 수 있는 것은, 그 밖에 동작중의 DirectMusic 어플리케이션이 없을 때 뿐이다. 최초로 IDirectMusic8::EnumMasterClock 메소드를 사용해, master clock의 기능을 완수할 수 있는 모든 디바이스의 기술을 취득한다. master clock로서 사용하고 싶은 디바이스의 GUID 를 취득한 다음에, 그 GUID 를 IDirectMusic8::SetMasterClock 메소드에 건네준다.


클락 타임과 뮤직 타임

DirectX for C++ 에서는, master clock에 의해 돌려주어지는 타임은,REFERENCE_TIME 형으로 정의되는 64 비트값이다. 기준 타임은 대략 100 나노초 (ns) 단위로 측정되므로, 클락의 틱 (눈금)은 1 초간에 대략 10,000,000 개 존재한다. IReferenceClock::GetTime 메소드는, 임의의 시작 타임 이후에 경과한 시간을 돌려준다.

뮤직 타임은,MUSIC_TIME 형으로서 정의되는 32 비트값이다. 이것은 시간의 절대적인 측정값은 아니고, 템포에 근거하는 상대값이다. 클락은, 퍼포먼스가 초기화될 때 시작 되어 4 분 음표 근처 DMUS_PPQ 의 시간이 경과하는 DMUS_PPQ 는, 현재 768 에 정의되고 있다.

퍼포먼스가 초기화될 때, 내장 시계의 유지가 시작 된다. IDirectMusicPerformance8::GetTime 메소드를 사용해, 현재의 퍼포먼스 타임을 기준 타임과 뮤직 타임의 양쪽 모두로 취득할 수가 있다.

IDirectMusicPerformance8::AdjustTime 메소드를 사용하면(자), 퍼포먼스 타임을 조금 변경할 수가 있다. 대부분의 어플리케이션에서는, 이 조작을 실행할 필요는 없다. 다만, 다른 소스에 동기 시키는 경우에는, 이 처리가 도움이 된다.

퍼포먼스내에서 이것들 2 종류의 타임을 변환하려면 ,IDirectMusicPerformance8::MusicToReferenceTime 과 IDirectMusicPerformance8::ReferenceToMusicTime 의 각 메소드를 사용한다. 이러한 메소드는, 퍼포먼스 시작 후의 모든 템포의 변경을 고려해, 퍼포먼스내의 타임 오프셋(offset)를 서로 변환한다.

IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 를 호출해, 연주하고 싶은 세그먼트(segment)를 삽입할 때에, 기준 타임을 사용해 시작 타임을 지정한다. 그 시점에서 프라이머리 세그먼트(segment)가 연주되어 있지 않은 경우, 이 타임은 현재의 템포에 따라 즉시 뮤직 타임에 변환된다. 다른 프라이머리 세그먼트(segment)가 연주되고 있는 경우는, 삽입된 세그먼트(segment)의 시작 타임에 이른 시점에서, 그 시작 타임은 뮤직 타임에 변환된다.

세그먼트(segment)의 연주가 시작 되기 전으로 템포가 변경되었을 경우는, 실제의 시작 타임이 영향을 받거나 세그먼트(segment)가 희망한 경계에서 시작 되지 않는 경우가 있다. 전자의 상황에서는, 즉시 뮤직 타임에의 변환을 한다. 템포의 속도가 상승했을 경우는 (기준 타임에서의) 시작 타임은 앞당겨져, 템포의 속도가 저하했을 경우는 늦는다. 후자의 상황에서는, 시작 타임에 변환을 하므로, 템포의 변경이 발생 하면, 정확한 분해가능의 경계에서 세그먼트(segment)가 시작되지 않는 것을 의미한다. 예를 들어, 세그먼트(segment)가 있는 소절 경계 (PlaySegment 또는 PlaySegmentEx 의 dwFlags 파라미터로 지시)에서 시작 되는 경우, 기준 타임에서의 실제의 시작 타임은, 세그먼트(segment)가 큐에 저장 될 때 계산된다. 그 후로 템포가 변경되면(자), 소절 경계가 계산한 타임대로 안 될 가능성이 있다.

프라이머리 세그먼트(segment)가 DMUS_SEGF_QUEUE 플래그와 함께 연주될 때 (DMUS_SEGF_FLAGS 를 참조),i64StartTime 파라미터는 무시되어 세그먼트(segment)는, 이미 시작 타임이 변환되고 있는 프라이머리 세그먼트(segment)의 다음에 연주되도록(듯이), 큐에 저장 된다. 이것은, 기준 타임을 지정해 현재 큐에 놓여져 있는 세그먼트(segment)가, DMUS_SEGF_QUEUE 세그먼트(segment)에 끼어들 가능성이 있는 것을 의미한다.

예를 들어, 3 개의 세그먼트(segment)가 있어, 각각의 길이가 10 초이다고 한다. 세그먼트(segment) A 를, 지금부터 5 초 후에 연주하도록(듯이) 큐에 저장 한다. 현재 연주되고 있는 프라이머리 세그먼트(segment)는 없기 때문에, 시작 타임은 즉시 뮤직 타임에 변환된다. 6 초 경과한 시점에서, 세그먼트(segment) B 를 20 초부터 연주하도록(듯이) 큐에 저장 한다. 이 경우, 이미 음악이 연주중에서, 템포가 변경되고 있을 가능성이 있기 (위해)때문에, 뮤직 타임에의 변환은 곧바로 하행 깨지지 않는다. 다음에, DMUS_SEGF_QUEUE 플래그를 설정한 세그먼트(segment) C 를, 세그먼트(segment) A 가 종료하는 대로, 즉 15 초부터 연주하도록(듯이) 큐에 저장 한다. 20 초의 시점에서, 세그먼트(segment) B 의 연주가 시작 되어 세그먼트(segment) C 가 중단된다.


템포의 변경

퍼포먼스의 템포는, DirectMusic 로 사용되는 2 종류의 타임의 변환을 지시해, 음악 경계의 이벤트의 분해가능을 제어한다( 「클락 타임과 뮤직 타임」을 참조할것). 보통,제어 세그먼트(segment)의 템포 트럭이 템포를 관리하지만, 어플리케이션으로 동적으로 템포를 설정할 수도 있다.

템포를 변경하는 방법은 2 개 있다. 메세지를 송신하는 방법과 제어 세그먼트(segment)에 트럭 파라미터를 설정하는 방법이다.

다음의 샘플 코드에서는, 메세지를 송신해 템포를 변경하고 있다.

// pIDMSegment 는 유효한 IDirectMusicSegment8 이며,
// IDMPerformance 는 유효한 IDirectMusicPerformance8 이라고 가정한다.

// 세그먼트(segment)의 템포 트럭을 무효로 해, 템포를 리셋 하지 않게 한다.

pIDMSegment->SetParam( GUID_DisableTempo, 0xFFFF, 0,0, NULL );

DMUS_TEMPO_PMSG* pTempo;

if( SUCCEEDED(pIDMPerformance->AllocPMsg(
        sizeof(DMUS_TEMPO_PMSG), (DMUS_PMSG**) &pTempo)))
{
    // 템포 이벤트를 큐에 저장 한다.
    ZeroMemory(pTempo, sizeof(DMUS_TEMPO_PMSG));
    pTempo->dwSize = sizeof(DMUS_TEMPO_PMSG);
    pTempo->dblTempo = 100;
    pTempo->dwFlags = DMUS_PMSGF_REFTIME;
    pTempo->dwType = DMUS_PMSGT_TEMPO;
    pIDMPerformance->SendPMsg((DMUS_PMSG*) pTempo);
}

다음의 예는, 템포 파라미터를 변경하는 방법을 나타내고 있다. 상세한 것에 대하여는, 「트럭 파라미터의 설정과 취득」을 참조할것.

DMUS_TEMPO_PARAM Tempo;
Tempo.dblTempo = 100;
pIDMSegment->SetParam(GUID_TempoParam, 0xFFFF, 0, 0, &Tempo);

제어 세그먼트(segment)에 의해 설정된 템포를 조정하는 마스터 템포를 변경할 수도 있다. 「글로벌 파라미터의 설정과 취득」을 참조할것.


준비 시간

세그먼트(segment)를 연주할 경우에, 퍼포먼스는 세그먼트(segment)의 트럭을 반복해 호출한다. 이 호출에 의해, 1 초의 몇분의 몇개의 지정된 시간 범위 분의 메세지가 생성된다. 이러한 메세지는, 지금까지의 호출로 생성된 메세지의 뒤로 삽입된다. 디폴트에서는, 대략 1 초 분의 메세지가, 언제라도 큐에 있다.

퍼포먼스가 메세지를 연주하도록(듯이) 트럭에 요구할 때 마다, 현재의 타임에 준비 시간을 가산해, 호출의 종료 타임이 계산된다. 현재의 타임이 10,000 밀리 세컨드 (또는, 등가인 REFERENCE_TIME 단위)로, 준비 시간이 디폴트로 1000 밀리 세컨드인 경우, 종료 타임은 11,000 이 된다. 즉, 11,000 까지의 연주 분의 새로운 메세지를 모두 준비해, 큐에 저장 해야 한다.

큐의 사이즈는,IDirectMusicPerformance8::SetPrepareTime 메소드를 호출해 변경할 수가 있다. 또, 현재의 사이즈는,IDirectMusicPerformance8::GetPrepareTime 를 사용해 취득할 수가 있다.

대부분의 어플리케이션에서는, 디폴트의 준비 시간을 변경할 필요는 없다. 여기서 설명한 처리는, 어플리케이션으로부터는 인식되어 있지 않다. 다만, 어플리케이션은 IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 에 DMUS_SEGF_AFTERPREPARETIME 플래그를 건네줄 수가 있으므로, 준비 시간의 개념을 이해해 두면(자) 도움이 된다.

이 플래그를 사용하지 않는 경우, 세그먼트(segment)의 시작 타임을 "현재" 로 설정 하면, 퍼포먼스는 현재 큐에 저장 되고 있는 메세지를 모두 무효로 한다. 이 시점에서 유효한 그대로의 트럭 (예를 들어, 새로운 프라이머리 세그먼트(segment)의 도입에 관계없이, 연주가 계속되는 세칸다리세그먼트의 트럭)은, 새로운 세그먼트(segment)에 의한 환경의 변화를 고려해, 메세지를 재발송신 해야 한다. 이것에 의해, 추가의 처리가 발생해, 바람직하지 않은 결과가 되는 경우도 있다.

DMUS_SEGF_AFTERPREPARETIME 플래그를 사용해, 현재 큐내에 있는 모든 메세지가 처리되어 포토 버퍼에게 건네질 때까지, 세그먼트(segment)를 연주하지 않는 것을 지정할 수 있다. 타임 10,000 까지의 메세지가 큐에 있어, 현재의 타임이 9,000 ms 의 경우, 연주용으로 큐에 저장 되어 DMUS_SEGF_AFTERPREPARETIME 플래그가 설정된 세그먼트(segment)는, 정확히 10,000 밀리 세컨드 후에 연주를 시작 한다.

상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것. 「지연 시간과 범퍼 시간」의 그림도 참조할것.


지연 시간과 범퍼 시간

지연 시간이란, 포토가 메세지를 받아들이고 나서, 연주해야 할 충분한 웨이브가 합성될 때까지의 지연을 의미한다. IDirectMusicPerformance8::GetLatencyTime 메소드는, 현재의 타임에 퍼포먼스의 지연 시간을 가산한 전체의 시간을 취득한다. 이 값은, 포토의 지연 시간 클락에 의해 돌려주어지는 최대의 값이다.

범퍼란, 이벤트가 포토 버퍼에 놓여지고 나서, 포토가 그 이벤트의 처리를 시작 하는 타임까지의, 코드를 실행하기 위해서 할당할 수 있었던 시간이다. 디폴트에서는, 범퍼의 길이는 50 밀리 세컨드 (ms)이다. 어플리케이션은,IDirectMusicPerformance8::SetBumperLength 메소드를 사용해 이 값을 변경해,IDirectMusicPerformance8::GetBumperLength 를 호출해 현재의 값을 취득할 수 있다.

여기에서는, 지연 시간과 범퍼 시간을 결합하는 방법을 나타낸다. 어느 이벤트가 10,000 밀리 세컨드의 시점에서 연주되면(자) 가정한다. 이 포토의 지연 시간은 100 밀리 세컨드인 것, 및 범퍼 시간의 길이는 디폴트의 50 밀리 세컨드인 것을 알 수 있고 있다. 그 때문에, 퍼포먼스는 9,850 밀리 세컨드의 시점에서 이 메세지를 포토 버퍼에 둔다.

메세지의 타임을 변경하는 툴은, 지연 시간과 범퍼 시간을 고려해야 한다. 툴이, 이미 지연 시간을 경과한 타임을 메세지에 스탬프 하는 경우, 노트나 그 외의 이벤트는 올바른 타임에 연주되지 않는다.

포토 버퍼에 놓여진 메세지는, 이미 퍼포먼스에 소속하지 않기 때문에,IDirectMusicPerformance8::Invalidate 메소드를 사용해도, 세그먼트(segment)를 정지해도 연주를 멈출 수 없는 점에 주의 해야 한다. 무효로 할 수 있는 최초의 메세지는, 현재의 타임에 지연 시간과 범퍼 시간을 더한 타임과 같은가, 그 이후의 타임 스탬프를 가진다. IDirectMusicPerformance8::GetQueueTime 메소드를 사용하면(자), 이 값을 취득할 수가 있다.

다음의 그림은, 다양한 메소드로 취득되는, 타임과 계속 시간의 관계를 나타내고 있다. 현재의 타임은 좌측으로 나타나고 있다. 우측이, 메세지의 준비가 완료하는 최종 타임이다. 준비 시간은 언제라도, 큐에 있는 메세지의 합계의 길이의 근사이다.


세그먼트(segment)의 타이밍

여기에서는, 세그먼트(segment)의 연주의 타이밍에 관한 다양한 면에 도착해 설명한다.

세그먼트(segment)의 타임과 퍼포먼스의 타임과의 관계를 명확하게 하기 위해서, 여기에서는 다음의 용어를 사용한다.

시작 포인트
세그먼트(segment)의 시작 타임이 될 수 있는 세그먼트(segment)내의 최초의 포인트. 디폴트의 경우, 이 값은 0 으로, 세그먼트(segment)의 선두를 나타낸다. 다만, 이 값은 어플리케이션으로 변경할 수 있다.
세그먼트(segment)의 시작 타임
사운드의 생성이 시작 되는 세그먼트(segment)내의 포인트. 이 타임은 보통 시작 포인트와 같지만, 시작 포인트가 의도적으로 과거의 연주 타임에 가지런히 할 수 있고 있는 경우는, 늦게 할 수도 있다.
연주 타임
새로운 세그먼트(segment)의 시작 포인트가 큐에 넣어지는 퍼포먼스내의 포인트. DirectMusic API 에서는, 이 타임은 시작 타임으로 불리는 일도 있다.
시작 마커
세그먼트(segment)내의 유효한 시작 타임을 나타내는 마커.
연주 마커
제어 세그먼트(segment)내에서, 다른 세그먼트(segment)의 시작 포인트를 큐에 넣을 수가 있는 포인트를 나타내는 마커.

주 시작 마커 및 연주 마커는, 작가에 의해 세그먼트(segment)의 마커 트럭에 배치되어 어플리케이션으로 변경할 수 없다. 다만,GUID_Valid_Start_Time 및 GUID_Play_Marker 파라미터를 사용해 취득할 수 있다.

세그먼트(segment)는, 보통, 최초부터 연주된다. IDirectMusicSegment8::SetStartPoint 메소드를 사용해, 다른 포인트로부터 세그먼트(segment)를 시작 할 수도 있다. 새로운 시작 포인트는, 변경될 때까지 유효하다.

IDirectMusicSegment8::SetRepeats 를 사용해 리피트 회수를 설정했을 경우,IDirectMusicSegment8::SetLoopPoints 를 호출해 루프를 정의하지 않으면, 세그먼트(segment) 전체가 그 회수만 반복된다.

연주 타임은,IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 메소드의 2 개의 파라미터에 의해 결정된다.

  • i64StartTime 파라미터는, 세그먼트(segment)의 연주를 시작 할 수 있다, 가장 빠른 타임을 설정한다. i64StartTime 가 0 의 경우는, 가능한 한 빠른 타임이 된다. 세그먼트(segment)가 시작 되는 실제의 타임은, 세그먼트(segment)의 종류에 따라서 다르다. 프라이머리 세그먼트(segment) 또는제어 세그먼트(segment)의 경우, 가장 빠른 연주 타임은 큐 (또는 플래시) 시간이다. 제어 이외의 세칸다리세그먼트의 경우, 가장 빠른 연주 타임은 지연 시간 다음에 있다. 큐 시간과 지연 시간의 상세한 것에 대하여는, 「지연 시간과 범퍼 시간」을 참조할것.
  • dwFlags 파라미터는, 가장 빠른 연주 타임의 뒤, 어느 정도 곧바로 세그먼트(segment)의 연주를 실제로 시작 하는지를 지정한다. 보통, 새로운 프라이머리 세그먼트(segment), 트란지션, 또는 모티프를 시작 하기 전에, 리듬의 적절한 포인트 기다린다. 다음의 DMUS_SEGF_FLAGS 열거형의 1 개 이상을 설정하는 것으로써, 지연을 제어한다.

세그먼트(segment)를 과거의 타임에 가지런히 한다

세그먼트(segment)의 시작 타임을제어 세그먼트(segment)의 다음의 구라두, 박, 또는 소절에 가지런히 하는 대신에, 세그먼트(segment)의 연주를 곧바로 시작 해, 현재의 세그먼트(segment)의 리듬에 맞추고 싶은 경우가 있다. 이와 같이 하려면, 세그먼트(segment)의 시작 포인트의 큐를 이미 경과한 리듬 경계에게 준다. 큐를 준 세그먼트(segment)의 리듬은, 현재의 세그먼트(segment)에 가지런히 할 수 있어 새로운 세그먼트(segment)는 즉시 연주를 시작 할 수 있다.

과거의 세그먼트(segment)에 큐를 주려면 , DMUS_SEGF_ALIGN 플래그를 사용한다. 적절한 리듬 경계에서 세그먼트(segment)의 시작 포인트에 큐를 주려면 , DMUS_SEGF_GRID, DMUS_SEGF_BEAT, 또는 DMUS_SEGF_MEASURE 의 어느쪽이든을 추가한다. 이 대신에, DMUS_SEGF_MARKER 를 사용해, 시작 포인트를 제어 세그먼트(segment)의 마지막에 연주된 연주 마커에 가지런히 할 수도 있다.

시작 포인트가 과거인 경우, 세그먼트(segment)의 시작 타임이 현재 또는 장래가 되도록(듯이) 조정해야 한다. 퍼포먼스는, 다음의 규칙에 따라, 세그먼트(segment)의 시작 타임을 결정한다. 어느 경우도,"다음" 과는 "다음에 가능" 인 것을 의미한다. 즉, 세그먼트(segment)의, 과거가 아닌 부분에 있다고 하는 의미이다.

  • 시작 마커가, 큐가 주어진 세그먼트(segment)의, 지정된 타입의 다음의 분해가능 경계보다 전에 있는 경우, 그 세그먼트(segment)의 시작 타임은 그 포인트가 된다.
  • 유효한 시작 마커가 없는 경우, 세그먼트(segment)의 시작 타임은 큐가 주어진 세그먼트(segment)의 다음의 시작 분해가능 경계가 된다. 이것은 다음의 몇개의 플래그로 지정된다.
    DMUS_SEGF_VALID_START_BEAT
    세그먼트(segment)의 시작 타임을 다음의 박으로 한다.
    DMUS_SEGF_VALID_START_GRID
    세그먼트(segment)의 시작 타임을 다음의 구라두로 한다.
    DMUS_SEGF_VALID_START_TICK
    세그먼트(segment)의 시작 타임을 가장 빠른 포인트로 한다.
  • 유효한 시작 마커가 없고, 시작 분해가능 플래그가 지정되어 있지 않은 경우, 세그먼트(segment)의 시작 타임은 다음의 연주 분해가능 경계가 된다. 이것은, DMUS_SEGF_GRID, DMUS_SEGF_BEAT, 또는 DMUS_SEGF_MEASURE 플래그로 지정된다. 이러한 플래그가 모두 존재하지 않는 경우, 세그먼트(segment)의 시작 타임은 즉시가 된다.

연주 마커와 시작 마커에 의해, 세그먼트(segment), 특히 모티프로 유연하게 큐를 줄 수가 있다. 모티프가, 프라이머리 세그먼트(segment)의 소절의 선두에서 연주를 시작 할 경우에 최적으로 연주되도록(듯이) 생성 되고 있다고 한다. 이 모티프로 DMUS_SEGF_MEASURE 플래그로 큐를 주면(자), 다음의 소절 경계에 이르러, 모티프가 연주 될 때까지 대폭적인 지연이 발생하는 경우가 있다. 그러나, DMUS_SEGF_ALIGN 플래그를 추가 하면, 리듬을 어지럽히는 일 없이, 곧바로 모티프의 연주를 시작 할 수 있다. DMUS_SEGF_MARKER 플래그를 추가 하면, 소절, 박, 또는 구라두 뿐만이 아니라, 제어 세그먼트(segment)내의 적절한 경계에서 모티프를 연주할 수 있게 된다.

템포의 변경에 의해 세그먼트(segment)의 시작 타임이 받는 영향에 대해서는, 「클락 타임과 뮤직 타임」을 참조할것.

다음의 그림은, DMUS_SEGF_MEASURE, DMUS_SEGF_ALIGN, 및 DMUS_SEGF_VALID_START_BEAT 의 각 플래그를 사용해 큐에 넣어진 세그먼트(segment)의 타이밍을 결정하는 과정을 나타내고 있다. 세로의 실선은 소절의 경계를 나타내, 점선은 박의 경계를 나타낸다. 세그먼트(segment)의 시작 포인트는, 현재의 프라이머리 세그먼트(segment)의 전에 있는 소절 경계에 가지런히 할 수 있다. 세그먼트(segment)의 시작 타임은, 미해결의 연주 타임의 뒤에 삽입되고 있는 세그먼트(segment)의 최초의 박이 된다.

논리적인 타임과 실제의 타임

일부의 이벤트는, 논리적인 타임과 실제의 타임의 양쪽 모두를 가지고 있다. 실제의 타임은 이벤트가 발생 하면나무이며, 논리적인 타임은 이벤트가 속하는 음악적인 위치를 나타낸다.

예를 들어, 세그먼트(segment)는, 박의 시작에 속하는 프로그램 체인지를 포함한 경우가 있다. 이 박의 시작은 논리적인 타임이다. 그러나, 박의 노트가 연주되기 전에 프로그램 체인지를 하도록(듯이) 하고 싶기 때문에, 이것보다 조금 빠른 물리적인 타임을 할당한다.

세그먼트(segment)가 논리적인 타임 (같은 박의 시작)에 루프 하는 경우, 프로그램 체인지도 행해진다.


통지와 이벤트의 처리

어플리케이션으로 퍼포먼스 이벤트에 응답해야 하는 경우가 있다. 예를 들어, 세그먼트(segment)의 종료에 도달한 것을 알 필요가 있는 경우나, 그래픽스를 음악의 박에 동기 시키고 싶은 경우가 있다. 특정의 타입의 이벤트가 발생했을 때에, 그것을 통지하도록(듯이) DirectMusic 에 지시해, 필요한 정보를 취득할 수가 있다.

주 퍼포먼스 통지와 DirectSound 의 버퍼 통지를 혼동 해서는 안 된다. DirectSound 의 버퍼 통지는, 버퍼에 대해서 직접 웨이브 데이터를 스트리밍 하는 어플리케이션에서만 사용된다. 「재생 버퍼의 통지」 및 「캡춰 버퍼의 통지」를 참조할것.

통지를 받고 싶은 음악 이벤트의 종류를 지정하려면 , 이벤트의 종류 마다 한 번 만여라 IDirectMusicPerformance8::AddNotificationType 메소드를 호출한다. 다음의 샘플 코드에서는, DirectMusic 에 세그먼트(segment)에 관련하는 이벤트를 설정하도록(듯이) 지시하고 있다. 실제의 이벤트의 종류 (세그먼트(segment)의 시작이나 세그먼트(segment)의 종료등)는, 통지 메세지로부터 얻을 수 있다.

// pPerformance 은 유효한 IDirectMusicPerformance8 포인터이다.

GUID guid = GUID_NOTIFICATION_SEGMENT;

pPerformance->AddNotificationType(guid);

IDirectMusicSegment8::AddNotificationType 메소드를 사용해, 특정의 세그먼트(segment)에 대해서 통지 타입을 추가할 수도 있다. 예를 들어, 특정의 세그먼트(segment)가 연주를 정지했을 때에 통지를 받는 것 같은 경우에, 이 설정을 실시할 수가 있다. 이 메소드를 사용해 GUID_NOTIFICATION_PERFORMANCE 형을 요구할 수 없다. 이러한 형태는, 퍼포먼스 오브젝트로부터 취득해야 한다.

주 대부분의 어플리케이션은,IDirectMusicTrack8::AddNotificationType 메소드를 직접 호출하지 않는다.

통지에 관한 정보는,DMUS_NOTIFICATION_PMSG 메세지 구조체로 송신된다. IDirectMusicPerformance8::GetNotificationPMsg 메소드를 호출해, Windows 메시지 루프내에서 보류중의 통지 메세지를 폴링 할 수가 있다. 또, 메세지가 보류중 때에, DirectMusic 에 다른 thread로 이벤트 오브젝트를 통지시킬 수도 있다.

Windows 이벤트 오브젝트를 사용해, 보류중의 DirectMusic 통지 메세지를 알리고 싶은 경우는, 우선 Microsoft® Win32® CreateEvent 함수를 호출해, 이벤트 핸들을 취득해야 한다. 보통은, 다음과 같은 호출을 실시해, 자동 리셋 이벤트를 생성 한다.

HANDLE g_hNotify = CreateEvent(NULL, FALSE, FALSE, NULL);

이벤트의 생성 후, 이 핸들을 IDirectMusicPerformance8::SetNotificationHandle 메소드에 건네주어 퍼포먼스에 할당한다. 이 메소드의 2 번째의 파라미터를 사용해, DirectMusic 로, 취득되어 있지 않은 이벤트를 대기하는 시간을 지정할 수 있다. 이 파라미터의 값이 0 의 경우는, 디폴트의 시간인 2 초가 사용된다.

다음의 예에서는,g_pPerf 는 IDirectMusicPerformance8 인터페이스에의 유효한 포인터를 나타내고 있다.

g_pPerf->SetNotificationHandle(g_hNotify, 0);

다음의 샘플 함수는, 독자적인 thread로 반복해 실행되어 통지된 이벤트를 확인해, 통지 메세지를 꺼내고 있다.

void WaitForEvent( LPVOID lpv)
{
    DWORD dwResult;
    DMUS_NOTIFICATION_PMSG* pPmsg;
    char szCount[4];

    while (TRUE)
    {
        dwResult = WaitForSingleObject(g_hNotify, 100);
        while (S_OK == g_pPerf->GetNotificationPMsg(&pPmsg))
        {
            // 통지 타입을 체크해, 거기에 응해 처리를 실시한다.
            .
            .
            .
            g_pPerf->FreePMsg((DMUS_PMSG*) pPmsg);
        }
    }
}

이 thread는 다음과 같이 실행된다.

_beginthread(WaitForEvent, 0, NULL);

통지가 필요없게 되었을 경우는, 다음의 코드에 나타내도록(듯이), thread를 슛다운 해, 퍼포먼스로부터 통지 핸들을 삭제해, 이벤트 오브젝트를 파기한다.

_endthread();
g_pPerf->SetNotificationHandle(0, 0);
CloseHandle(g_hNotify);

어플리케이션의 메시지 루프로, 이벤트를 생성 해 통지 메세지를 취득할 필요는 없다. AddNotificationType 메소드의 어느쪽이든을 호출해 통지를 요구하고 있는 경우, 메세지는 퍼포먼스에 의해 송신되어IDirectMusicPerformance8::GetNotificationPMsg 의 호출로 취득할 수가 있다.

이벤트가 통지되는 경우, 또는 메시지 루프로 GetNotificationPMsg 를 호출하는 경우는, 복수의 메세지를 대기할 수가 있다. 모든 통지를 확실히 받으려면 , S_FALSE 가 돌려주어질 때까지 GetNotificationPMsg 의 호출을 반복한다.

같은 타임 스탬프를 가지는 메세지가 다수 있는 경우, 이러한 메세지는 큐에 저장 될 때 특정의 순서는 되지 않는다.

어플리케이션은,IDirectMusicPerformance8::FreePMsg 메소드를 호출해, 취득한 메세지를 해방할 필요가 있다.


퍼포먼스 파라미터

DirectMusic 에서는, 다음의 SetParam 메소드의 어느쪽이든을 사용해 재생중으로 파라미터를 변경해, 트럭의 다양한 동작을 제어할 수가 있다.

  • IDirectMusicPerformance8::SetParam 는, 이 퍼포먼스의 현재의제어 세그먼트(segment)내에서, 특정의 트럭에 데이터를 설정한다. 제어 세그먼트(segment)는, 보통은 프라이머리 세그먼트(segment)이지만, 세칸다리세그먼트를 연주중에 제어 세그먼트(segment)로서 지정할 수가 있다. 「제어 세그먼트(segment)」를 참조할것.
  • IDirectMusicSegment8::SetParam 는, 세그먼트(segment)내의 특정의 트럭에 데이터를 설정한다.
  • IDirectMusicTrack8::SetParam 및 IDirectMusicTrack8::SetParamEx 는, 인터페이스에 의해 나타내지는 트럭에 데이터를 설정한다. 어플리케이션은, 보통, 개개의 트럭에 대한 인터페이스를 가지지 않는다.

IDirectMusicPerformance8::SetGlobalParam 메소드를 사용해, 퍼포먼스 전체에 적용되는 값을 설정할 수가 있다.

GetParam 및 GetGlobalParam 메소드는, 트럭 또는 퍼포먼스의 현재의 값을 취득한다.

변경된 파라미터에 음악을 즉시 응답시키려면 , 어플리케이션으로 IDirectMusicPerformance8::Invalidate 메소드를 사용해, 큐로부터 메세지를 플래시 한다. 이 메소드에 의해, 모든 트럭은 지정한 포인트 이후의 메세지를 재발송신 한다.

파라미터의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 트럭 파라미터의 설정과 취득
  • 트럭 파라미터의 무효화와 유효화
  • 글로벌 파라미터의 설정과 취득


트럭 파라미터의 설정과 취득

트럭 파라미터를 설정 및 취득하기 위해서, 이하의 메소드가 사용된다.

  • IDirectMusicPerformance8::GetParam
  • IDirectMusicPerformance8::SetParam
  • IDirectMusicSegment8::GetParam
  • IDirectMusicSegment8::SetParam
  • IDirectMusicTrack8::GetParam
  • IDirectMusicTrack8::SetParam
  • IDirectMusicTrack8::GetParamEx
  • IDirectMusicTrack8::SetParamEx

퍼포먼스 또는 세그먼트(segment)로 이러한 메소드의 어느쪽이든을 호출하면나무에,dwGroupBits 및 dwIndex 파라미터를 설정해, 트럭을 식별할 수가 있다. 다만, 보통은, DirectMusic 에 적절한 트럭을 검색시킬 수가 있다. 상세한 것에 대하여는, 「트럭의 식별」을 참조할것.

설정 또는 취득하는 트럭 파라미터는, 메소드의 rguidType 파라미터에 있는 GUID 로 식별된다. 데이터를 필요로 하는 각 파라미터는, 특정의 데이터형에 관련지을 수 있고 있다. pParam 는, 이 형태의 변수 또는 구조체를 가리키지 않으면 안 된다. 경우에 따라서는, 파라미터를 취득할 경우에도, 데이터 구조체의 일부를 초기화할 필요가 있다. 또, 파라미터에 따라서는, 변경을 실시하는 타임, 또는 파라미터를 취득하는 타임을 트럭내에서 지정해야 한다.

표준적인 파라미터 타입에 관련하는 데이터의 레퍼런스 정보에 대해서는, 「표준 트럭 파라미터」를 참조할것.

일부의 파라미터의 변경은, 즉시 유효하게 안 되는 것 처럼 보인다. 예를 들어,홈 레벨의 변경은, 현재의 패턴의 연주가 종료해, 다음의 패턴을 선택할 때까지 변화가 없다. 이 변경을 즉시 유효하게 하려면 ,IDirectMusicPerformance8::Invalidate 메소드를 호출해, 현재의 패턴을 강제적으로 파기할 수가 있다.

특정의 파라미터가 트럭에 의해 지원 되고 있는지 어떤지를 확인하려면 ,IDirectMusicTrack8::IsParamSupported 메소드를 사용해, S_OK 의 결과를 확인한다.

상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 트럭의 식별


트럭의 식별

IDirectMusicTrack8::SetParamEx 또는 IDirectMusicTrack8::GetParamEx 를 사용해 파라미터를 설정 또는 취득할 경우에, 파라미터는 메소드를 호출한 트럭에 관련지을 수 있다. 다만,IDirectMusicPerformance8::SetParam ,IDirectMusicPerformance8::GetParam ,IDirectMusicSegment8::SetParam , 또는 IDirectMusicSegment8::GetParam 를 호출하면나무에, DirectMusic 는 적절한 트럭을 검색할 필요가 있다.

보통은, 목적의 파라미터가 어느 트럭에 포함될까를, DirectMusic 로 결정시킬 수가 있다. 이 경우,dwGroupBits 를 0xFFFFFFFF 에,dwIndex 를 DMUS_SEG_ANYTRACK 로 설정한다. 예를 들어, 다음의 IDirectMusicSegment8::SetParam 의 호출에서는, 세그먼트(segment)의 루프로 템포가 리셋 되지 않게, 템포 트럭을 오프로 하고 있다.

pIDMSegment->SetParam(GUID_DisableTempo, 0xFFFFFFFF,
    DMUS_SEG_ALLTRACKS, 0, NULL);

다만, 트럭을 식별해야 하는 경우도 있다. 일반적으로는, 세그먼트(segment)에 같은 타입의 트럭이 2 개 이상 포함되어 있는 경우이다. 목적의 트럭으로 파라미터를 설정 또는 취득하려면 , 그룹 또는 인덱스값을 사용해, 트럭을 식별해야 한다.

모든 트럭은 1 개 또는 복수의 그룹에 속해, 각각의 그룹은 dwGroupBits 파라미터의 비트로 나타내진다. dwGroupBits 는, 다음에 설명하는 메소드의 1 개의 파라미터이다. 트럭은, 퍼포먼스에 삽입될 때, 1 개(살) 또는 복수의 그룹에 할당할 수 있다. 「IDirectMusicSegment8::InsertTrack 」를 참조할것. 파일로부터 로드 되는 세그먼트(segment)의 경우, 트럭 그룹은 세그먼트(segment)의 작가에 의해 할당할 수 있다.

트럭은, 속하고 있는 그룹 각각 두어, 제로로부터 시작되는 인덱스값으로 식별된다. 인덱스값은, 트럭이 삽입된 순서로 결정된다.

어느 세그먼트(segment)에, 다음 표에 나타내는 트럭이 저장 되고 있으면(자) 가정한다.

트럭 | 그룹 비트
A | 0x1
B | 0x2
C | 0x1
D | 0x3

그룹 1 은 트럭 A, 트럭 C, 및 트럭 D 를 포함해, 그룹 2 는 트럭 B 와 트럭 D 를 포함한다. dwGroupBits 를 1,dwIndex 를 0 (� 설정 메소드 또는 취득 메소드를 호출하면, 파라미터는, 그룹 1 의 최초의 트럭인 트럭 A 로부터 취득된다. dwIndex 가 1 의 경우는, 그룹에서 2 번째의 트럭 C 로부터 파라미터가 취득된다. 트럭 D 는, 그룹 1 으로 그룹 2 의, 2 개의 그룹에 속하고 있다. 따라서, 이 트럭은,dwGroupBits = 1 및 dwIndex =2, 또는 dwGroupBits = 2 및 dwIndex = 1 의 편성의 어느 쪽인지로 식별된다.

dwGroupBits 에 복수의 비트를 설정 하면, 그러한 모든 비트를 포함한 n 번째의 트럭으로부터 파라미터가 취득된다. 여기서 n 는 dwIndex 내의 값이다.


트럭 파라미터의 무효화와 유효화

트랙에 도착해 GUID_DisableTempo 및 GUID_DisableTimeSig 파라미터를 설정 하면,제어 세그먼트(segment)에 의한 템포 및 박자 기호의 설정을 무효로 할 수 있다. 예를 들어, 동적으로 템포를 설정해, 프라이머리 세그먼트(segment)에 템포 메세지를 송신시키고 싶지 않은 경우 등에 사용할 수 있다.

이 파라미터를 다시 유효하게 하려면 ,rguidType 파라미터에 GUID_EnableTempo 또는 GUID_EnableTimeSig 를 지정해, 몇개의 파라미터 설정 메소드를 호출한다. 이러한 파라미터를 설정해, 제어 세그먼트(segment)가 아닌 세그먼트(segment)에 템포 메세지를 송신시키거나 세칸다리세그먼트에 박자 기호 메세지를 송신시킬 수도 있는 상세한 것에 대하여는, 「제어 세그먼트(segment)」를 참조할것.

파라미터를 설정하는 방법에 대해서는, 「트럭 파라미터의 설정과 취득」을 참조할것.

「IDirectMusicTrack8::IsParamSupported 」의 「주의」도 참조할것.

트럭의 구성 플래그를 설정하는 것에 의해, 임의의 트럭 파라미터를 무효 또는 유효하게 할 수도 있다. 상세한 것에 대하여는, 「트럭 구성」을 참조할것.


글로벌 파라미터의 설정과 취득

IDirectMusicPerformance8::SetGlobalParam 및 IDirectMusicPerformance8::GetGlobalParam 메소드를 사용하면(자), 1 개의 트럭 뿐만이 아니라, 퍼포먼스 전체에 영향을 주는 파라미터를 설정 및 취득할 수가 있다.

설정 또는 취득하는 파라미터는, 메소드의 rguidType 파라미터에 있는 GUID 로 식별된다. 각 파라미터는 특정의 데이터형에 관련지을 수 있다. 데이터형의 사이즈는,dwSize 파라미터로 주어진다. 다음의 표는, 정의 끝난 GUID 와 그 데이터형을 나타내고 있다.

파라미터 타입의 GUID (rguidType) (와)과 데이터 (*pParam) | 설명
GUID_PerfAutoDownload BOOL | 이 파라미터는, 세그먼트(segment)를 연주할 경우에 음색을 자동적으로 다운로드할지 어떨지를 제어한다. 디폴트에서는 오프이다. 「밴드의 다운로드와 언로드」를 참조할것.
GUID_PerfMasterGrooveLevel char | 마스터 홈 레벨은, 커멘드 트럭으로 설정되는 홈 레벨에 항상 가산되는 값이다. 돌려주어지는 값은 1 ~ 100 의 범위에 들어가도록(듯이) 필요에 따라서 조정된다.
GUID_PerfMasterTempo float | 마스터 템포는, 최종 출력 툴에 의해 템포에 적용되는 스케일링 계수이다. 디폴트의 값은 1 이다. 0.5 로 템포는 2 분의 1 이 되어, 2.0 으로 2 배의 템포가 된다. 이 값은, DMUS_MASTERTEMPO_MIN 로부터 DMUS_MASTERTEMPO_MAX 의 범위에서 설정할 수 있다.
GUID_PerfMasterVolume long | 마스터 볼륨은, 증폭 또는 감쇠의 계수로, 1 데시벨의 100 분의 1 의 단위로 나타내진다. 그 퍼포먼스 전체의 디폴트의 볼륨과 같은 신디사이저를 사용하고 있는 것 외의 모든 퍼포먼스에 적용된다. 설정할 수 있는 값의 범위는 포토에 의해 정해진다. 디폴트의 소프트웨어 신디사이저의 경우, 허용 범위는 +20db ~ -200dB 이지만, 실용 범위는 +10db ~ -100db 이다. 하드웨어 MIDI 포토에서는, 마스터 볼륨의 변경은 지원되어 있지 않다.

어플리케이션은, 독자적인 타입의 글로벌 파라미터를 사용할 수도 있다. 새로운 타입을 생성 하려면 , GUID 와 그 데이터형을 확정한다.

파라미터를 설정할 경우에, 퍼포먼스는, GUID 로 식별되는 링크된 항목의 리스트의 데이터에 메모리를 할당한다. 데이터는,IDirectMusicPerformance8::GetGlobalParam 를 호출해 취득할 수 있다.

주 정의 끝난 파라미터도, 취득하기 전으로 설정해야 한다. 파라미터에 대해서 SetGlobalParam 가 불려 가지 않은 경우,GetGlobalParam 는 실패한다.


오디오 패스의 사용법

DirectMusic 퍼포먼스에는 1 개 이상의 오디오 패스가 포함된다. 오디오 패스는, 다양한 오브젝트에 의해 사운드 데이터의 흐름을 관리한다. 오디오 패스에는, 퍼포먼스 자체, 세그먼트(segment), 툴 그래프, 신디사이저, DirectSound 버퍼, 이펙트 DMO , 및 최종적인 믹싱을 하는 프라이머리 DirectSound 버퍼가 포함되는 경우가 있다.

어플리케이션으로 2D 사운드 이펙트나 MIDI 파일의 재생 이외의 복잡한 처리를 실시하지 않는 경우는, 디폴트의 표준 오디오 패스를 설정해, 거기서 모든 재생을 실시한다. 다만, DirectX Audio 의 기능을 최대한으로 이용하려면 , 오디오 패스를 제어할 필요가 있다.

여기에서는, 오디오 패스의 생성, 오디오 패스에서의 세그먼트(segment)의 연주, 및 오디오 패스내의 오브젝트에의 액세스에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 포토로부터 오디오 패스에의 이행
  • 오디오 패스의 생성
  • 디폴트의 오디오 패스
  • 표준 오디오 패스
  • 오디오 패스에서의 사운드의 재생
  • 오디오 패스로부터의 오브젝트의 취득


포토로부터 오디오 패스에의 이행

DirectX 8.0 이전의 버젼의 DirectMusic 를 사용해 어플리케이션을 생성 하고 있었을 경우, 오디오 출력에의 루트의 추천 되는 생성 방법이 변경되고 있다. 이전의 방법으로 DirectMusic 를 사용할 수도 있지만, 이펙트 처리, 개개의 세그먼트(segment) 상태의 제어, 및 DirectMusic Producer 세그먼트(segment)의 커스텀 오디오 패스 구성등의 기능을 이용하려면 , 새로운 방법에 따를 필요가 있다.

오디오 출력의 이전의 모델과 새로운 모델에게는, 다음과 같은 차이가 있다.

  • 어플리케이션은 직접 포토를 조작하지 않는다. DirectMusic 가 포토의 생성 및 퍼포먼스 채널의 매핑을 처리한다. IDirectMusicPerformance8::Init ,IDirectMusicPerformance8::AddPort ,IDirectMusicPerformance8::AssignPChannel , 및 IDirectMusicPerformance8::AssignPChannelBlock 의 각 메소드는, 오디오 파스 모델에서는 사용되지 않는다.
  • 3D 버퍼를 사용해 사운드를 재생하는 경우, 어플리케이션으로 명시적으로 버퍼를 생성 해,IDirectMusicPort8::SetDirectSound 를 사용해 버퍼를 포토에 할당할 필요가 없어졌다. 버퍼는 오디오 패스의 일부로서 생성 되어 어플리케이션은 GetObjectInPath 메소드의 어느쪽이든을 사용해 버퍼에 액세스 할 수 있다.
  • 오디오 패스를 비액티브하게 했을 경우와 포토를 비액티브하게 했을 경우에서는, 다른 결과를 얻을 수 있다. 포토를 비액티브하게 하면, 사운드는 생성되지 않게 되지만, 퍼포먼스에 의해 세그먼트(segment)의 재생은 계속된다. 오디오 패스를 비액티브하게 하면, 그 오디오 패스의 모든 재생이 정지해, 무엇을 실시해도 세그먼트(segment)를 재생할 수 없게 된다.


오디오 패스의 생성

어플리케이션에서는, 다음의 방법으로 오디오 패스를 설정할 수 있다.

  • IDirectMusicPerformance8::CreateStandardAudioPath 를 사용해, 1 개(살) 또는 복수의 표준 오디오 패스를 생성 한다. 「표준 오디오 패스」를 참조할것.
  • IDirectMusicPerformance8::InitAudio 의 호출로, 퍼포먼스의 디폴트의 표준 오디오 패스를 생성 한다. 「디폴트의 오디오 패스」를 참조할것.
  • DirectMusic Producer 로 생성 된 파일로부터 오디오 패스 구성을 취득해, 구성 오브젝트를 IDirectMusicPerformance8::CreateAudioPath 에 건네준다.
  • 세그먼트(segment)를 연주할 경우에, 세그먼트(segment)의 오디오 패스 구성으로부터 DirectMusic 에 오디오 패스를 생성 시킨다. 이 방법으로 생성 된 오디오 패스는, 일시적이며, 어플리케이션에서는 인식되지 않는다.

오디오 패스 구성 오브젝트는,IDirectMusicLoader8::GetObject 또는 IDirectMusicLoader8::LoadObjectFromFile 를 사용해, 다른 오브젝트와 같게 로드할 수 있다. 세그먼트(segment)에 파묻히고 있는 구성은,IDirectMusicSegment8::GetAudioPathConfig 를 사용해 취득할 수 있다.

오디오 패스 구성 오브젝트는, 고유의 인터페이스나 메소드를 가지지 않기 때문에, 어플리케이션으로 구성을 변경할 수 없다. 이 오브젝트에 대해서 가능한 처리는, 오브젝트의 IUnknown 인터페이스를 사용해,IDirectMusicPerformance8::CreateAudioPath 에 건네주는 것 뿐이다. 샘플 코드에 대해서는, 「오디오 패스에서의 사운드의 재생」을 참조할것.

오디오 패스 구성은, 표준 이외의 오디오 패스를 생성 하는 유일한 방법이다. 예를 들어, 복수의 퍼포먼스 채널이 복수의 버퍼에 루팅 되는 경우, 이 매핑은 세그먼트(segment)의 오디오 패스 구성으로 지정해야 한다.


디폴트의 오디오 패스

디폴트의 오디오 패스는, 세그먼트(segment)가 IDirectMusicPerformance8::PlaySegment 를 사용해 연주되는 경우, 또는 IDirectMusicPerformance8::PlaySegmentEx 의 호출로 오디오 패스가 지정되어 있지 않은 경우에 사용된다.

오디오 패스를 생성 해,IDirectMusicPerformance8::InitAudio 의 dwDefaultPathType 파라미터로 표준 타입을 지정하는 것에 의해 디폴트의 오디오 패스로 할 수 있다.

기존의 오디오 패스는,IDirectMusicPerformance8::SetDefaultAudioPath 에 건네주는 것에 의해 디폴트의 오디오 패스로 할 수 있다. IDirectMusicPerformance8::GetDefaultAudioPath 를 사용하는 것에 의해, 디폴트의 오디오 패스를 취득한다.


표준 오디오 패스

오디오 패스 구성 오브젝트로부터 생성 된 오디오 패스 이외의 오디오 패스로 재생을 실시하는 경우는, 1 개(살) 또는 복수의 표준 오디오 패스를 생성 할 필요가 있다.

표준 오디오 패스는,IDirectMusicPerformance8::CreateStandardAudioPath 의 dwType 파라미터 또는 IDirectMusicPerformance8::InitAudio 의 dwDefaultPathType 파라미터로 건네받는 값에 의해 식별된다.

DirectMusic 에 의해 정의되는 오디오 패스는, 표준 버퍼의 편성에 의해 신디사이저 출력의 플로우를 관리한다. 표준 버퍼의 일부에는, 이펙트 DMO 가 부가되고 있다. 다음의 표는, 표준 오디오 패스와 표준 오디오 패스에 포함되는 표준적인 버퍼를 나타내고 있다. 복수의 오디오 패스로 공유 버퍼를 사용할 수 있다.

오디오 패스의 타입 | 표준 버퍼 | 버퍼를 공유할까
DMUS_APATH_DYNAMIC_3D | 3D 드라이 | 아니오
DMUS_APATH_DYNAMIC_MONO | 단청의 | 아니오
DMUS_APATH_DYNAMIC_STEREO | 스테레오 | 아니오
DMUS_APATH_SHARED_STEREOPLUSREVERB | 스테레오 리바브 | 네 네

표준적인 버퍼의 특성을 다음 표에 나타낸다. 「능력」의 란에는,IDirectSoundBuffer8::GetCaps 에게 건네지는 DSBCAPS 구조체의 dwFlags 멤버로 돌려주어지는 값이 나타나고 있다. 마지막 란은, 버퍼 오브젝트로부터 항상 취득할 수 있는 인터페이스를 나타내고 있다. 또, 어플리케이션은 IDirectSoundBuffer8::SetFX 를 사용해 버퍼에 이펙트를 추가할 수 있다. 이 경우, 다른 인터페이스도 사용할 수 있다. IDirectSoundBuffer8 는, 모든 버퍼에 대해 사용할 수 있다. 인터페이스의 취득의 상세한 것에 대하여는, 「오디오 패스로부터의 오브젝트의 취득」을 참조할것.

표준적인 버퍼 | 설명 | 능력 | 인터페이스
3D 드라이 | 단청의 3D 버퍼. | DSBCAPS_CTRL3D DSBCAPS_CTRLFX DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS DSBCAPS_MUTE3DATMAXDISTANCE | IDirectSound3DBuffer8
단청의 | 이펙트를 가지지 않는 단청의 버퍼. | DSBCAPS_CTRLFX DSBCAPS_CTRLPAN DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS | 없음.
리바브 | 뮤직크리바브에페크트를 가지는 스테레오 버퍼. | DSBCAPS_CTRLFX DSBCAPS_CTRLPAN DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS | IDirectSoundFXWavesReverb8
스테레오 | 이펙트를 가지지 않는 스테레오 버퍼. | DSBCAPS_CTRLFX DSBCAPS_CTRLPAN DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS | 없음.

표준 오디오 패스의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • DMUS_APATH_DYNAMIC_3D
  • DMUS_APATH_DYNAMIC_MONO
  • DMUS_APATH_DYNAMIC_STEREO
  • DMUS_APATH_SHARED_STEREOPLUSREVERB


DMUS_APATH_DYNAMIC_3D

3D 드라이 타입의 비공유 버퍼를 설정한다.

어플리케이션은,dwStage 를 DMUS_PATH_BUFFER 에,dwBuffer 를 0 으로 설정해 GetObjectInPath 메소드의 어느쪽이든을 호출하는 것에 의해, 3D 드라이밧파에의 인터페이스를 취득할 수 있다.


DMUS_APATH_DYNAMIC_MONO

3D 파라미터 또는 특수 효과를 가지지 않는 단청의 타입의 비공유 버퍼를 설정한다.

어플리케이션은,dwStage 를 DMUS_PATH_BUFFER 에,dwBuffer 를 0 으로 설정해 GetObjectInPath 메소드의 어느쪽이든을 호출하는 것에 의해, 버퍼에의 인터페이스를 취득할 수 있다.


DMUS_APATH_DYNAMIC_STEREO

연판의 비공유 버퍼를 설정한다. 이 오디오 패스는, 스테레오 버퍼 위에의 사운드 이펙트용이다. 리바브는 사용할 수 없다.

어플리케이션은,dwStage 를 DMUS_PATH_BUFFER 에,dwBuffer 를 0 으로 설정해 GetObjectInPath 메소드의 어느쪽이든을 호출하는 것에 의해, 버퍼에의 인터페이스를 취득할 수 있다.


DMUS_APATH_SHARED_STEREOPLUSREVERB

리바브 및 연판의 버퍼를 설정한다.

스테레오 버퍼는 복수의 오디오 패스로 공유된다. 이것은 세면대 인 버퍼로, 다른 버퍼로부터는 아니고, 신디사이저로부터 직접 데이터를 받는다.

어플리케이션은,dwStage 를 DMUS_PATH_BUFFER 에,dwBuffer 를 0 으로 설정해 GetObjectInPath 메소드의 어느쪽이든을 호출하는 것에 의해, 스테레오 버퍼에의 인터페이스를 취득할 수 있다.

리바브밧파도 공유 세면대 인 버퍼이다. 스테레오 버퍼와는 달라, 신디사이저로부터의 단청의 입력을 받아, 데이터를 스테레오 포맷으로 변환한다.

어플리케이션은,dwStage 를 DMUS_PATH_BUFFER 에,dwBuffer 를 1 으로 설정해 GetObjectInPath 메소드의 어느쪽이든을 호출하는 것에 의해, 리바브밧파에의 인터페이스를 취득할 수 있다.

다음의 샘플 코드는, 디폴트의 DMUS_APATH_SHARED_STEREOPLUSREVERB 오디오 패스상에 있는 리바브밧파내의 DMO 에의 IDirectSoundFXWavesReverb8 인터페이스를 취득한다. g_pPerf 는 IDirectMusicPerformance8 인터페이스이다.

IDirectMusicAudioPath8 * pAudioPath;
IDirectSoundFXWavesReverb8 * pEffectDMO;
HRESULT hr;

hr = g_pPerf->GetDefaultAudioPath(&pAudioPath);
if (SUCCEEDED(hr))
{
  HRESULT hr = pAudioPath->GetObjectInPath(DMUS_PCHANNEL_ALL,
        DMUS_PATH_BUFFER_DMO, 1,
        GUID_All_Objects, 0, IID_IDirectSoundFXWavesReverb8,
        (LPVOID*) &pEffectDMO);
}


오디오 패스에서의 사운드의 재생

어플리케이션이 IDirectMusicPerformance8::InitAudio 의 호출로 디폴트의 오디오 패스를 생성 했을 경우,IDirectMusicPerformance8::PlaySegment 를 사용해 이 패스로 세그먼트(segment)를 연주할 수 있다. IDirectMusicPerformance8::PlaySegmentEx 의 pAudioPath 파라미터에 NULL 를 건네주는 것에 의해, 디폴트의 패스로 세그먼트(segment)를 연주할 수도 있다.

디폴트의 오디오 패스가 없는 경우나, 세그먼트(segment)를 다른 패스로 연주하는 경우는,PlaySegment 는 아니고,PlaySegmentEx 를 사용한다. 오디오 패스를 지정하려면 , 2 개의 방법이 있다.

  • pAudioPath 파라미터로 포인터를 지정한다. 보통, 이것은, 오디오 패스를 생성 했을 때에 받은 IDirectMusicAudioPath8 인터페이스 포인터이다.
  • dwFlags 에 DMUS_SEGF_USE_AUDIOPATH 를 포함한다. 이 플래그를 지정 하면, 세그먼트(segment)에 의해, 세그먼트(segment) 오브젝트에 파묻힌 구성으로부터 오디오 패스가 생성 된다.

주 DMUS_SEGF_USE_AUDIOPATH 플래그를 지정해 생성 된 오디오 패스는, 세그먼트(segment)의 재생이 정지 하면 즉시 해방된다. 오디오 패스에 리바브등의 이펙트가 포함되는 경우, 그 이펙트는 중단된다. 이러한 돌연의 중단을 막으려면 , 수동으로 오디오 패스를 생성 해, 적절한 시간을 두고 나서 해방한다.

DMUS_SEGF_USE_AUDIOPATH 플래그를 사용해 재생하는 세그먼트(segment)에 대해서는, 자동 다운로드가 유효하게 되지 않은 한, 밴드는 다운로드되지 않는다. 상세한 것에 대하여는, 「밴드의 자동 다운로드」를 참조할것.

다음의 샘플 코드에서는, 오디오 패스 구성이 파묻히고 있는 경우는 그것을 사용해 세그먼트(segment)를 재생해, 그렇지 않은 경우는 디폴트의 오디오 패스로 세그먼트(segment)를 재생한다. g_pPerf 는 IDirectMusicPerformance8 인터페이스 포인터이며,g_pSeg 는 사운드 파일의 임의의 타입에의 IDirectMusicSegment8 인터페이스이다.

IDirectMusicAudioPath8 * pPath =  NULL;
IUnknown *pConfig;

if (g_pSeg)
{
  if (SUCCEEDED(g_pSeg->GetAudioPathConfig(&pConfig)))
  {
    g_pPerf->CreateAudioPath(pConfig, TRUE, &pPath);
    pConfig->Release();
  }
  g_pPerf->PlaySegmentEx(g_pSeg, NULL, NULL, 0, 0, NULL,
      NULL, pPath);
  if (pPath)
  {
      pPath->Release();
      pPath = NULL;
  }
}

오디오 패스에의 인터페이스가 있는 경우는,IDirectMusicAudioPath8::SetVolume 을 사용해 볼륨을 변경할 수 있다. 글로벌 파라미터의 GUID_PerfMasterVolume 는 그 신디사이저로 재생되는 모든 사운드에 영향을 주지만, 이 메소드는, 그 오디오 패스로 재생되는 퍼포먼스 채널의 볼륨만을 설정한다.


오디오 패스로부터의 오브젝트의 취득

오디오 패스내의 특정의 오브젝트에의 인터페이스를 취득해야 하는 경우가 있다. 이러한 경우의 일반적인 이유는 다음과 같다.

  • IDirectSound3DBuffer8 인터페이스를 취득하는 것에 의해, 사운드의 3D 프로퍼티를 조작하기 위해(때문에).
  • 프라이머리 버퍼로부터 IDirectSound3DListener8 인터페이스를 취득하는 것에 의해, 글로벌 3D 사운드 파라미터를 설정하기 위해(때문에).
  • IDirectSoundBuffer8 인터페이스를 취득하는 것에 의해, 세칸다리밧파의 이펙트를 설정하기 위해(때문에).
  • IDirectSoundFXI3DL2Reverb8 등의 DMO 에의 인터페이스를 취득하는 것에 의해, 이펙트 파라미터를 설정하기 위해(때문에).

오브젝트는, 오디오 패스로 연주중의 세그먼트(segment) 상태에 대해 IDirectMusicSegmentState8::GetObjectInPath 를 호출하는 것에 의해, 오디오 패스로부터 취득할 수 있다. 오디오 패스 오브젝트 자체에 대해 IDirectMusicAudioPath8::GetObjectInPath 를 호출할 수도 있다. 다음 표에서는, 이것들 2 개의 메소드의 파라미터에 대해 설명한다.

dwStage | guidObject | dwPChannel (을)를 사용할까 | dwIndex (을)를 사용할까 | iidInterface (표준)
DMUS_PATH_AUDIOPATH (*) | 무시된다 | 아니오 | 아니오 | IID_IDirectMusicAudioPath8
DMUS_PATH_AUDIOPATH_GRAPH | 무시된다 | 아니오 | 아니오 | IID_IDirectMusicGraph8
DMUS_PATH_AUDIOPATH_TOOL | 툴 클래스 ID 또는 열거하는 GUID_All_Objects | 네 | 네 | IID_IDirectMusicTool8
DMUS_PATH_BUFFER | 무시된다 | 네 | 아니오. dwBuffer 에 의해 식별한다 | IID_IDirectSoundBuffer8
DMUS_PATH_BUFFER_DMO | GUID_DSFX_STANDARD_GARGLE 등의 DMO 클래스 ID 또는 열거하는 GUID_All_Objects | 네 | 네. 버퍼내의 DMO 의 인덱스 | IID_IDirectSoundFXGargle(**) 등, 표준 DMO 인터페이스의 GUID
DMUS_PATH_MIXIN_BUFFER | 무시된다 | 아니오 | 아니오. dwBuffer 에 의해 식별한다 | IID_IDirectSoundBuffer8
DMUS_PATH_MIXIN_BUFFER_DMO | GUID_DSFX_STANDARD_I3DL2REVERB 등의 DMO 클래스 ID 또는 열거하는 GUID_All_Objects | 아니오 | 네. 버퍼내의 DMO 의 인덱스 | IID_IDirectSoundFXI3DL2Reverb(**) 등, 표준 DMO 인터페이스의 GUID
DMUS_PATH_PERFORMANCE | 무시된다 | 아니오 | 아니오 | IID_IDirectMusicPerformance8
DMUS_PATH_PERFORMANCE_GRAPH | 무시된다 | 아니오 | 아니오 | IID_IDirectMusicGraph8
DMUS_PATH_PERFORMANCE_TOOL | 툴 클래스 ID 또는 열거하는 GUID_All_Objects | 네 | 네 | IID_IDirectMusicTool8
DMUS_PATH_PORT | 포토 클래스 ID 또는 열거하는 GUID_All_Objects | 네 | 네 | IID_IDirectMusicPort
DMUS_PATH_PRIMARY_BUFFER | 무시된다 | 아니오 | 아니오 | IID_IDirectSound3DListener8
DMUS_PATH_SEGMENT (*) | 무시된다 | 아니오 | 아니오 | IID_IDirectMusicSegment8
DMUS_PATH_SEGMENT_GRAPH (*) | 무시된다 | 아니오 | 아니오 | IID_IDirectMusicGraph8
DMUS_PATH_SEGMENT_TOOL (*) | 툴 클래스 ID 또는 열거하는 GUID_All_Objects | 네 | 네 | IID_IDirectMusicTool8
DMUS_PATH_SEGMENT_TRACK (*) | 트럭 클래스 ID 또는 열거하는 GUID_All_Objects | 아니오 | 네 | IID_IDirectMusicTrack8

주 (*) 이 단계의 오브젝트는,IDirectMusicAudioPath8::GetObjectInPath 에 의해 취득할 수 있다.

(**) DirectX 의 DMO 는,IMediaObject,IMediaObjectInPlace, 및 IMediaParams 인터페이스를 지원 한다. 이러한 인터페이스의 상세한 것에 대하여는, DirectShow 의 메뉴얼을 참조할것.

표준적인 버퍼를 취득 하면나무의 dwIndex 의 값의 상세한 것에 대하여는, 「표준 오디오 패스」를 참조할것.

이미 이펙트 버퍼에의 인터페이스가 있는 경우는,IDirectSoundBuffer8::GetObjectInPath 를 사용해 DMO 인터페이스를 취득할 수도 있다.

오디오 패스의 모든 버퍼에 대해 IDirectSoundBuffer8 인터페이스를 취득할 수 있지만, 일부의 메소드는 유효하지 않다. 상세한 것에 대하여는, 「IDirectSoundBuffer8 」를 참조할것.


3D 사운드

DirectX Audio 를 사용해, 공간내의 사운드의 위치를 인식해, 이동하는 사운드에 돕라편이를 적용할 수 있다.

3D 이펙트는 개개의 DirectSound 버퍼에 적용된다. 각각 독자적인 버퍼를 가지는 복수의 오디오 패스에 다른 사운드를 지정할 수 있으므로, 다른 사운드에 용이하게 다른 파라미터를 적용할 수 있다.

다음의 주제에서는, 3D 사운드의 기본적 개념을 몇개인가 소개한다.

  • 3D 공간의 좌표
  • 음원 위치의 인식

다음의 주제에서는, 어플리케이션내에서의 3D 사운드의 사용법에 대한 정보를 기술한다.

  • DirectSound 3D 버퍼
  • DirectSound 3D 청취자


3D 공간의 좌표

3D 공간에서의 음원과 청취자의 위치, 속도, 및 방향은, 데카르트 좌표의 3 개의 좌표축, x 축, y 축, 및 z 축의 값으로 나타내진다. 이러한 축은, 어플리케이션으로 확립된 시점으로부터 상대적이다. x 축의 값은 왼쪽에서 오른쪽으로, y 축의 값은 아래에서 위로, z 축의 값은 앞에서 안쪽으로 가는 만큼 커진다.

D3DVECTOR 구조체는, 3 개의 축으로 위치, 속도, 또는 방향을 기술하는 값을 저장 한다.

관습적으로, 벡터는 외모로 둘러싸여 칸마로 단락지어졌다 (x, y, z)의 순서의 3 개의 값으로 나타내진다.

위치의 경우, 이러한 값은 디폴트로 미터 단위이다. 어플리케이션이 3D 그래픽의 측정 단위로서 미터 이외의 것을 사용하고 있는 경우, 거리 계수를 설정해, 어플리케이션이 사용하는 거리 단위가 몇 미터에 상당할까를 부동 소수점의 값으로서 표현한다. 예를 들어, 어플리케이션이 피트 단위를 사용하고 있는 경우, 거리 계수로서 0.3048 을 지정하지만, 이것은 1 피트를 미터 단위로 표현한 것이다. 상세한 것에 대하여는, 「거리 계수」를 참조할것.

속도의 경우, 벡터는, 각 축으로 따른 이동 속도를 1 초 쯤의 단위로 나타낸다. 이 경우도, 디폴트의 단위는 미터이지만, 어플리케이션으로 변경할 수 있다.

방향의 경우, 값은 임의의 단위이며, 서로 상대적이다. 3D 공간의 베이스 뷰가 북쪽에서, 지면의 레벨로, 청취자의 방향이 (1, 0, 0), 즉, x 축이 정으로, 다른 2 개의 축이 변함없는 경우, 청취자는 동쪽을 향한다. 이 벡터가 (1, 0, 1)의 경우, 청취자의 방향은 북동이 된다. (-1, 0, 1)의 경우, 청취자는 북서를 향한다. 벡터의 값은 절대적인 단위는 아니기 때문에, 마지막 예는 (-5, 0, 5) 또는 (-0. 25, 0, 0.25)와 나타낼 수도 있다.

2D 공간에서의 벡터의 구조는, 그래프 용지에 그려 보면 알기 쉽다. 값이 용지아래에서 위, 왼쪽에서 오른쪽을 향해 커지도록(듯이) 한다. (0, 0)(으)로부터 (1, 1)로 향해 그린 직선은, (0, 0)로부터 (5, 5)로 향해 그린 직선과 향해, 즉 방향이 같다. 다만, 2 번째의 직선은 거리, 즉 속도가 큰 일을 나타낸다. 3D 벡터의 경우도, 축이 증가하는 것만으로, 이것과 같다.


음원 위치의 인식

현실의 세계에서는, 공간내의 음원 위치의 인식은, 복수의 요소에 영향을 받는다. 이러한 요소의 모든 것이 음향적이지 않다. 가장 중요하지만 1 개(살)에 시각이 있다. 사운드 자체의 단서에는, 다음과 같은 것이 있다.

  • 전체적인 음량. 음원이 청취자로부터 멀어지면(자), 인식되는 음량은 일정 속도로 감소한다. 이 현상은 롤 오프로 불리고 있다.
  • 청감 위에의 강도의 차이. 청취자의 우측향으로 발생한 소리는, 왼쪽귀보다 오른쪽귀의 (분)편으로 크게 들린다.
  • 도달이 질질 꺼라. 청취자의 우측향으로 발생한 소리는, 왼쪽귀보다 약간 빨리 오른쪽귀에 도달한다. 이 차이의 시간은, 약 1 밀리 세컨드이다.
  • 소음. 귀가 적극적으로 도착해 있는 것으로, 그 형상을 위해서(때문에), 청취자의 뒤방향으로 발생한 소리는, 전으로 발생한 소리에 비해 희미하게 약해지고 있다. 게다가 우측향으로 소리가 발생했을 경우, 왼쪽귀에 닿는 소리는, 머리 부분에 차단해지는 것으로 왼쪽귀의 방향에 의해 약해진다.

인간이 소리의 위치를 식별하기 위한 단서는 이만큼은 아니지만, 여기에 올린 것은 주요한 것이다. 그리고 DirectX Audio 의 위치 결정 시스템은 이러한 요소를 제공한다. 3D 사운드용으로 최적화된 하드웨어는, 다를 방향으로부터 발 다투어지는 소리의 높이나 타이밍에 대한 귓불의 이펙트 등, 다른 단서도 지원 할 수 있다. 이 이펙트의 배경에 있는 수학적 이론을 머리 부분 전달 함수 (HRTF)라고 부른다.

대부분의 경우, DirectSound 는 2 개의 스피커 또는 헤드폰으로 가상 3D 이펙트를 생성 한다. 다만, 유저가 컨트롤 패널로 환경 사운드 스피커 구성을 선택했을 경우는, WDM 드라이버를 사용하는 4 채널 시스템을 이용할 수도 있다. 상세한 것에 대하여는, 「DSBUFFERDESC 」를 참조할것.


DirectSound 3D 버퍼

3D 환경에서의 각 음원은 IDirectSound3DBuffer8 인터페이스에 의해 나타내진다. 이 인터페이스를 지원 하는 것은, DSBCAPS_CTRL3D 플래그를 지정해 생성 된 사운드 버퍼 뿐이다. 이 인터페이스의 메소드를 사용해, 단일의 음원의 파라미터를 설정 및 취득한다.

DirectSound 의 3D 능력을 이용 하면나무는, 어플리케이션은 단청의 음원을 제공해야 한다. DSBCAPS_CTRL3D 플래그를 지정해 버퍼를 생성 하는 경우, 웨이브 포맷에 복수의 채널이 포함되어 있으면(자), 에러가 된다.

여기에서는, 어플리케이션이 3D 버퍼 오브젝트를 취득 및 관리하는 방법에 대해 설명한다. 이하의 토픽에 대해 설명한다.

  • 3D 버퍼 오브젝트의 취득
  • 3D 버퍼의 배치 파라미터
  • 최소 거리와 최대 거리
  • 처리 모드
  • 버퍼의 위치 좌표와 속도
  • 사운드 콘


3D 버퍼 오브젝트의 취득

IDirectSound3DBuffer8 인터페이스는,DSBUFFERDESC 구조체의 dwFlags 멤버로 DSBCAPS_CTRL3D 플래그를 지정해 생성 된 DirectSound 세칸다리밧파로부터 취득된다.

어플리케이션이 DirectMusic 의 퍼포먼스 및 오디오 패스를 사용하고 있는 경우,DMUS_APATH_DYNAMIC_3D 을 dwType 파라미터로서 IDirectMusicPerformance8::CreateStandardAudioPath 에 건네주는 것에 의해, 3D 버퍼를 포함한 오디오 패스를 생성 할 수 있다.

구성 오브젝트로부터 적절한 오디오 패스를 생성 할 수도 있다. 오디오 패스 구성에 의해, 버퍼의 3D 파라미터를 지정할 수 있다. 오디오 패스를 생성 할 경우에, 버퍼의 3D 프로퍼티는 이러한 파라미터를 사용해 초기화된다.

오디오 패스내의 3D 버퍼에의 인터페이스를 취득하려면 ,dwStage 를 DMUS_PATH_BUFFER 로 설정해,IDirectMusicAudioPath8::GetObjectInPath 또는 IDirectMusicSegmentState8::GetObjectInPath 를 호출한다.

다음의 샘플 코드에서는, 표준 오디오 패스를 생성 해,IDirectSound3DBuffer8 인터페이스를 취득하고 있다.

HRESULT                  hr;
IDirectMusicAudioPath8*  g_p3DAudioPath;
IDirectSound3DBuffer8*   g_pDS3DBuffer;

if (FAILED(hr = pPerformance->CreateStandardAudioPath(
        DMUS_APATH_DYNAMIC_3D, 64, TRUE, &g_p3DAudioPath)))
    return hr;

if (FAILED(hr = g_p3DAudioPath->GetObjectInPath(
        DMUS_PCHANNEL_ALL, DMUS_PATH_BUFFER, 0,
        GUID_NULL, 0, IID_IDirectSound3DBuffer8,
        (LPVOID*) &g_pDS3DBuffer)))
    return hr;

어플리케이션이 독자적인 DirectSound 세칸다리밧파를 생성 및 관리해, DirectMusic 퍼포먼스를 사용하지 않는 경우, 다음의 샘플 코드와 같이, 버퍼에 대해 IDirectSoundBuffer8:: QueryInterface 메소드를 호출하는 것에 의해,IDirectSound3DBuffer8 인터페이스를 취득할 수 있다.

// lpDsbSecondary 는, DSBCAPS_CTRL3D 를 지정해 생성 되었다
// 유효한 IDirectSoundBuffer8 이라고 가정한다.

LPDIRECTSOUND3DBUFFER8 lpDs3dBuffer;

HRESULT hr = lpDsbSecondary->QueryInterface(IID_IDirectSound3DBuffer8,
                                            (LPVOID *) &lpDs3dBuffer);


3D 버퍼의 배치 파라미터

어플리케이션은, 3D 사운드 파라미터의 취득이나 설정을 개별 또는 배치 단위로 실시할 수 있다. 개별의 값을 설정하려면 , 어플리케이션으로 적용 가능한 IDirectSound3DBuffer8 인터페이스 메소드를 사용할 수 있다. 그러나, 모든 값을 한 번으로 설정 또는 취득할 필요가 생기는 일도 자주 있다. 그 경우는,IDirectSound3DBuffer8::GetAllParameters 와 IDirectSound3DBuffer8::SetAllParameters 의 각 메소드를 사용한다.

또, 파라미터의 변경은, 그것들에 지연의 플래그를 붙여 두어 그 후 모든 것을 한 번에 실행하는 것으로보다 효율적으로 실시할 수가 있다. 상세한 것에 대하여는, 「지연 설정」을 참조할것.


최소 거리와 최대 거리

청취자가 음원에 가까워지는 것에 따라 사운드가 커져, 거리가 반이 되었을 때에 소리의 볼륨은 배증한다. 그러나, 특정의 점을 지나면(자), 볼륨이 계속 증가하는 것은 합리적은 아니다. 이것이 음원의최소 거리이다.

어플리케이션이 다른 소리의 절대 볼륨 레벨의 차이를 보정해야 하는 경우, 최소 거리는 특별히 도움이 된다. 예를 들어, 제트 엔진의 소리는 벌의 날개소리보다 훨씬 크지만, 실용 위에의 이유로써 이러한 소리를 동일한 정도의 절대 볼륨으로 녹음해야 한다. 어플리케이션은 제트 엔진의 최소 거리를 100 미터, 벌의 최소 거리를 2 센치로 설정하는 것을 생각된다. 이러한 설정에서는, 청취자가 200 미터 떨어지면(자) 제트 엔진은 반의 볼륨이 되어, 청취자가 4 센치 떨어지면(자) 벌의 날개소리는 반의 볼륨이 된다.

사운드 버퍼의 디폴트의 최소 거리 DS3D_DEFAULTMINDISTANCE 는, 1 단위, 즉 디폴트의 거리 계수에서는 1 미터로 정의되고 있다. 이 값을 변경하지 않는 한, 청취자로부터 1 미터 멀어진 위치에서 소리는 최대가 되어, 2 미터 떨어지면(자) 반의 크기, 4 미터 떨어지면(자) 1/4 의 크기가 된다. 대부분의 사운드에서는, 최소 거리를 이것보다 크게 설정해, 거리가 커져도 사운드가 급속히 사라지지 않게 한다.

음원의최대 거리란, 그 이상 떨어져도 소리가 보다 작게 안 되는 거리를 의미한다. DirectSound 의 3D 버퍼의 디폴트의 최대 거리 (DS3D_DEFAULTMAXDISTANCE)는 10 억이며, 소리가 들리지 않게 된 후도 계속해 감쇠를 계산해야 하는 것을 의미한다. 불필요한 처리를 피하기 위해서(때문에), 어플리케이션은 적절한 최대 거리를 설정해, 버퍼를 생성 할 때에 DSBCAPS_MUTE3DATMAXDISTANCE 플래그를 포함해야 하는 것이다. 이 플래그는, 오디오 패스의 일부로서 생성 된 표준적인 3D 버퍼에 대해서는 자동적으로 설정된다. 「표준 오디오 패스」를 참조할것.

사운드가 들리지 않게 되는 것을 방지하는 목적으로도, 최대 거리를 이용할 수 있다. 예를 들어, 어느 사운드의 최소 거리를 100 미터로 설정해, 1,000 미터 이상 떨어지면(자) 그 사운드가 사실상 들리지 않게 되면(자) 가정한다. 여기서 최대 거리를 800 미터로 설정 하면, 거리 에 관계없이, 그 사운드는 최대 볼륨의 적어도 1/8 로 들리는 것이 보증된다. 물론, 이 경우는 DSBCAPS_MUTE3DATMAXDISTANCE 플래그를 설정하지 않는다.

다음의 그림은, 거리가 커지는 것에 따라, 최소 거리와 최대 거리가 제트 엔진의 소리와 벌의 날개소리의 크기에 어떻게 영향을 주는지를 나타내고 있다.

어플리케이션으로 최소 거리값을 설정 및 취득하려면 ,IDirectSound3DBuffer8::SetMinDistance 와 IDirectSound3DBuffer8::GetMinDistance 의 각 메소드를 사용한다. 같이 최대 거리값을 설정 및 취득하려면 IDirectSound3DBuffer8::SetMaxDistance 와 IDirectSound3DBuffer8::GetMaxDistance 의 각 메소드를 사용한다.

디폴트에서는, 거리값은 미터 단위로 나타내진다. 「거리 계수」를 참조할것.

모든 사운드 버퍼로, 거리가 볼륨에 미치는 이펙트를 조정하려면 ,롤 오프 계수를 변경한다.


처리 모드

사운드 버퍼에는 3 개의 처리 모드가 있다. 표준, 머리 상대 (청취자 상대), 및 무효의 각 모드이다.

표준 모드에서는, 음원은 월드 공간내의 절대 위치와 절대 방향에 근거해 처리된다. 이것은 디폴트의 모드이다.

머리 상대 (청취자 상대) 모드에서는, 청취자의 이동과 회전에 응해, 버퍼는 월드 공간내에서 자동적으로 위치 조정된다. IDirectSound3DBuffer8::SetPosition ,IDirectSound3DBuffer8::SetVelocity ,IDirectSound3DBuffer8::GetConeOrientation 등의 메소드로 값의 설정과 취득을 실시할 수 있지만, 이것들은 모두 청취자의 현재의 위치, 속도, 방향에 대한 상대적인 것이다.

무효 모드에서는 3D 사운드 처리는 무효가 되어, 사운드는 청취자의 머릿속심으로 발생하고 있도록(듯이) 들린다.

어플리케이션은 IDirectSound3DBuffer8::SetMode 메소드를 사용해 3D 사운드 버퍼의 모드를 설정한다.


버퍼의 위치 좌표와 속도

3D 사운드에는 위치와 속도가 있다. 이러한 값의 지정은, 모두 어플리케이션으로 실시한다.

위치는 처리 모드에 근거해, 월드 공간이나 청취자의 어느 쪽인지를 기준으로 한 상대적인 벡터로서 나타내진다.

속도는 초쯤의 거리 단위로 측정된다. 디폴트에서는 미터/초이다. 속도는 돕라편이의 이펙트를 계산하기 위해서 마셔 사용되어 음원의 실제의 이동 측에 대응하고 있을 필요는 없다.

어플리케이션은,IDirectSound3DBuffer8::SetPosition 와 IDirectSound3DBuffer8::GetPosition 의 각 메소드를 사용해, 3D 공간에서의 음원의 위치를 설정 및 취득할 수 있다.

속도를 설정 또는 취득하려면 ,IDirectSound3DBuffer8::SetVelocity 와 IDirectSound3DBuffer8::GetVelocity 의 각 메소드를 사용한다.


사운드 콘

방향을 가지지 않는 사운드는, 어느 방향으로도, 거리에 응해 크기가 정해진다. 방향이 있는 사운드는, 그 방향을 향했을 때에 가장 커진다. 방향이 있는 사운드의 크기를 나타내는 모델을, 사운드 콘이라고 부른다. 사운드 콘은, 내부 콘과 외부 콘으로 형성된다.

내부 콘내의 각도에서는, 사운드의 볼륨은, 버퍼의 기본적인 볼륨, 청취자로부터의 거리, 청취자의 방향등을 고려해도, 콘이 없는 경우와 같게 된다.

외부 콘의 외측의 각도에서는, 어플리케이션에 의해 설정된 계수에 의해 보통의 볼륨이 감쇠된다. 외부 콘의 볼륨은,1/100 dB 단위의 부의 수로 나타내진다. 디폴트의 볼륨을 0 으로 해, 이 볼륨은 거기로부터의 감쇠를 나타내기 때문이다.

내부 콘과 외부 콘의 사이의 각도는, 내부 볼륨으로부터 외부 볼륨에의 트란지션이다. 각도가 증가하는 것에 따라, 볼륨은 작아진다.

다음의 그림은, 사운드 콘의 개념을 나타내고 있다.

모든 3D 사운드 버퍼는 사운드 콘이다. 그러나, 외부 볼륨은 감쇠하지 않고, 내부 콘과 외부 콘의 각도는 어느쪽이나 360 번이므로, 디폴트에서는 버퍼는 전방향의 음원으로서 동작한다. 어플리케이션이 이러한 값을 변경하지 않는 한, 사운드에는 외관의 방향은 없다.

사운드 콘을 적절히 설계 하면, 어플리케이션에 극적인 이펙트가 추가된다. 예를 들어 음원을 방의 중앙에 두어, 음원의 방향을, 복도에 접해 연 문의 향해로 설정한다. 다음에 그 문의 폭에 맞추어 내부 콘의 각도를 설정한다. 외부 콘을 그것보다 약간 넓게 설정해, 외부 콘의 볼륨을 청취 불가능하게 설정한다. 청취자가 복도를 걸어, 문의 근처까지 오면(자) 사운드가 들리기 시작한다. 그리고 열려 있는 문의 정면으로 오면(자) 사운드는 최대가 된다.

어플리케이션은,IDirectSound3DBuffer8::SetConeAngles 와 IDirectSound3DBuffer8::GetConeAngles 의 각 메소드를 사용해, 사운드 콘을 정의하는 각도를 설정 및 취득한다. 외부 콘의 각도는, 항상 내부 콘의 각도 이상이 아니면 안된다.

어플리케이션은,IDirectSound3DBuffer8::SetConeOrientation 와 IDirectSound3DBuffer8::GetConeOrientation 의 각 메소드를 사용해, 사운드 콘의 방향을 설정 및 취득한다.

어플리케이션은,IDirectSound3DBuffer8::SetConeOutsideVolume 과 IDirectSound3DBuffer8::GetConeOutsideVolume 의 각 메소드를 사용해, 외부 콘의 볼륨을 설정 및 취득한다.


DirectSound 3D 청취자

가상 3D 환경에서는, 열매 세계와 같게, 사운드는 수신 포인트와의 관계에서만 존재한다. DirectX Audio 어플리케이션의 3D 사운드 이펙트는, 사운드 버퍼의 위치와 방향과 속도 만이 아니고, 가상 청취자의 위치와 방향과 속도의 영향을 받는다.

디폴트에서는, 청취자는 모든 벡터가 0 의 위치에 정지해, Z 축의 정의 방향을 향해, 머리를 Y 축의 정의 방향으로 하고 있다. 청취자를 나타내는 오브젝트를 취득하는 것에 의해, 어플리케이션은 이러한 모든 값을 변경해 가상 공간에서의 유저의 움직임과 방향을 반영할 수 있다. 청취자 오브젝트는, 도플러 효과의 양이나 거리에 응한 볼륨의 감쇠 등, 청감 환경의 일반적인 파라미터도 컨트롤 한다.

여기에서는, 어플리케이션이 청취자를 취득해, 글로벌 3D 사운드 파라미터를 관리하는 방법에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • 3D 청취자의 취득
  • 3D 청취자의 배치 파라미터
  • 지연 설정
  • 거리 계수
  • 청취자의 방향
  • 청취자의 위치 좌표와 속도
  • 돕라 계수
  • 롤 오프 계수


3D 청취자의 취득

글로벌 사운드 파라미터는,IDirectSound3DListener8 인터페이스를 사용해 설정 및 취득된다. 이 인터페이스는,프라이머리 사운드 버퍼에의 인터페이스이다. 어플리케이션의 프라이머리 버퍼는 1 개만으로, 청취자도 1 명 뿐이다.

DirectMusic 의 퍼포먼스와 오디오 패스를 사용해 3D 사운드를 재생하는 경우는,IDirectMusicAudioPath8::GetObjectInPath 또는 IDirectMusicSegmentState8::GetObjectInPath 를 사용해,dwStage 파라미터를 DMUS_PATH_PRIMARY_BUFFER 로 설정해, 오디오 패스로부터 청취자를 취득할 수 있다. 다음의 예에서는,g_p3DAudioPath 는 IDirectMusicAudioPath8 인터페이스에의 포인터이다.

IDirectSound3DListener8* g_pDSListener;

HRESULT hr = g_p3DAudioPath->GetObjectInPath(
    DMUS_PCHANNEL_ALL, DMUS_PATH_PRIMARY_BUFFER, 0,
    GUID_NULL, 0, IID_IDirectSound3DListener8,
    (LPVOID*) &g_pDSListener));

어플리케이션이, DirectSound API 를 사용해, 독자적인 사운드 버퍼를 생성 및 관리하는 경우는, 프라이머리 버퍼 오브젝트를 생성 해, 이 오브젝트로부터 청취자 인터페이스를 취득할 필요가 있다.

프라이머리 버퍼를 생성 하려면 ,IDirectSound8::CreateSoundBuffer 메소드를 사용해,DSBUFFERDESC 구조체의 dwFlags 멤버로 DSBCAPS_CTRL3D 와 DSBCAPS_PRIMARYBUFFER 의 각 플래그를 지정한다. 생성 된 버퍼에 대해서 IDirectSoundBuffer:: QueryInterface 메소드를 호출해, 그 버퍼의 IDirectSound3DListener8 인터페이스에의 포인터를 취득한다.

다음의 예에서는,lpds 는 IDirectSound8 인터페이스 포인터이다.

DSBUFFERDESC           dsbd;
LPDIRECTSOUNDBUFFER    lpdsbPrimary;
LPDIRECTSOUNDLISTENER8 lp3DListener;

ZeroMemory(&dsbd, sizeof(DSBUFFERDESC));
dsbd.dwSize = sizeof(DSBUFFERDESC);
dsbd.dwFlags = DSBCAPS_CTRL3D | DSBCAPS_PRIMARYBUFFER;
if SUCCEEDED(lpds->CreateSoundBuffer(&dsbd, &lpdsbPrimary, NULL))
{
    // 청취자 인터페이스를 취득한다.
    if FAILED(lpdsbPrimary->QueryInterface(
            IID_IDirectSound3DListener8,
            (LPVOID *) &lp3DListener))
    {
    lpdsbPrimary->Release();
    }
}

청취자가 취득되면(자), 프라이머리 버퍼에의 IDirectSoundBuffer 인터페이스는 불필요하게 되어, 해방할 수 있다.


3D 청취자의 배치 파라미터

어플리케이션은, 3D 청취자 오브젝트 파라미터의 취득이나 설정을 개별 또는 배치 단위로 실시할 수 있다. 개별의 값을 설정하려면 , 어플리케이션으로 적용 가능한 IDirectSound3DListener8 인터페이스 메소드를 사용할 수 있다. 그러나, 청취자를 표현하는 모든 값을 한 번으로 설정 또는 취득할 필요가 생기는 일도 자주 있다. 그 경우는,IDirectSound3DListener8::GetAllParameters 와 IDirectSound3DListener8::SetAllParameters 의 각 메소드를 사용하면(자), 배치 파라미터 조작을 1 회의 호출로 실행할 수 있다.

또, 파라미터의 변경은, 그것들에 지연의 플래그를 붙여 두어 그 후 모든 것을 한 번에 실행하는 것으로보다 효율적으로 실시할 수가 있다. 상세한 것에 대하여는, 「지연 설정」을 참조할것.


지연 설정

3D 사운드 버퍼와 청취자의 설정을 변경할 때마다, 재믹싱을 해 CPU 사이클을 소비한다. 3D 설정의 변경에 의한 처리 성능에의 영향을 최소한으로 억제하려면 , 3D 설정을 변경하는 IDirectSound3DListener8 와 IDirectSound3DBuffer8 의 몇개의 메소드의 dwApply 파라미터로 DS3D_DEFERRED 플래그를 지정한다. 그 후 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출해, 지연 되고 있던 모든 커멘드를 1 회에 실행한다.

주 지연 설정은 즉시 설정에 의해 오버라이드(override) 된다. 예를 들어, DS3D_DEFERRED 플래그를 지정해 청취자 속도를 (1.0, 0.0, 0.0)로 설정한 후, DS3D_IMMEDIATE 플래그를 지정해 청취자 속도를 (2.0, 0.0, 0.0)로 설정 하면, 속도는 (2.0, 0.0, 0.0)이 되어,CommitDeferredSettings 를 호출해도 변경되지 않는다.


거리 계수

거리 계수는, 벡터의 단위가 되는 미터수이다. 디폴트의 거리 계수는 1.0 이다. 버퍼의 속도가 (2.0, 0.0, 0.0)인 경우, 음원은 X 축으로 따라, 2 미터/초에 이동 하면 보여진다. 어플리케이션이 3D 그래픽 벡터의 측정 단위로서 미터 이외의 단위를 사용하고 있는 경우는, 그 단위에 응해 거리 계수도 변경할 수 있다.

예를 들어, 현재의 어플리케이션이 측정의 기본 단위로서 피트 (0.3048 미터)를 사용하고 있다고 한다. 이 경우는,IDirectSound3DListener8::SetDistanceFactor 메소드를 호출해,flDistanceFactor 파라미터로서 0.3048 을 지정한다. 그 이후, 메소드를 호출할 때에 파라미터를 피트 단위로 지정 하면, 그러한 값은 미터 단위에 자동적으로 환산된다.

IDirectSound3DListener8::GetDistanceFactor 메소드를 사용하면(자), 청취자에 대해서 설정되어 있는 현재의 거리 계수를 취득할 수 있다.

거리 계수는, 1 초 쯤 n 단위로 나타내지는 실제의 속도를 변경하는 것으로써, 주로 도플러 효과에 영향을 미친다. 롤 오프에 직접적인 영향을 미칠 것은 없다. 거리에 응한 감쇠율은, 이 단위를 사용한 최소 거리에 근거하고 있기 때문이다. 어느 사운드의 최소 거리를 2 단위로 설정했을 경우, 4 단위 떨어지면(자) 볼륨은 반이 된다. 거리가 피트나 미터나 다른 단위여도, 이것은 공통이다. 상세한 것에 대하여는, 「최소 거리와 최대 거리」를 참조할것.


청취자의 방향

청취자의 방향은, 청취자의 머릿속심을 원점으로 하는 2 개의 벡터, 윗쪽 벡터와 전방 벡터의 관계에 의해 정의된다. 윗쪽 벡터는 두정부를 지나는 오름새의 직선으로, 전방 벡터는 윗쪽 벡터와 직각을 이루어 청취자의 얼굴을 통과하는 직선이다. 다음의 그림은 이러한 관계를 나타내고 있다.

어플리케이션은 IDirectSound3DListener8::SetOrientation 와 IDirectSound3DListener8::GetOrientation 의 각 메소드를 사용해, 청취자의 방향을 설정 및 취득할 수 있다.

디폴트에서는, 전방 벡터가 (0.0, 0.0, 1.0), 윗쪽 벡터가 (0.0, 1.0, 0.0)이다. 이것들 2 개의 벡터는, 항상 서로 대해 직각이 아니면 안된다. 필요에 따라서, DirectSound 는 전방 벡터에 조정을 더해 윗쪽 벡터에 대해서 직각의 관계를 유지한다.


청취자의 위치 좌표와 속도

어플리케이션은 IDirectSound3DListener8::SetPosition 와 IDirectSound3DListener8::GetPosition 의 각 메소드를 사용해, 3D 공간에 있어서의 청취자의 위치를 설정 및 취득할 수 있다.

DirectSound 가 이동하는 청취자에 대한 도플러 효과를 계산할 때에 사용하는 속도값을 설정 또는 취득하려면 ,IDirectSound3DListener8::SetVelocity 와 IDirectSound3DListener8::GetVelocity 의 각 메소드를 사용한다. 속도는 초쯤의 거리 단위로 측정된다. 디폴트에서는 미터/초이다.

버퍼와 같이, 청취자의 위치와 속도와는 완전하게 독립하고 있다. 청취자의 적절한 속도를 설정하는 작업은, 어플리케이션에 의존하고 있다.


돕라 계수

DirectSound 는, 속도를 가지는 버퍼나 청취자에 대해서, 자동적으로 도플러 효과를 생성 한다. 이 이펙트는 누적한다. 청취자와 사운드 버퍼의 양쪽 모두가 이동하고 있는 경우, 시스템은 상대속도를 자동적으로 계산해, 거기에 따라서 도플러 효과를 조정한다.

현실적인 도플러 효과를 어플리케이션에 추가하려면 , 이동하고 있는 모든 오브젝트의 속도를 계산해, 그 음원 또는 청취자의 적절한 속도를 설정해야 한다. 특정의 상황에서는 특수 효과를 가져오기 위해서(때문에), 이 값을 자유롭게 확장 또는 감소시켜도 좋다. 돕라 계수를 변경 하면, 돕라편이를 전체적으로 증가 또는 감소 당한다.

돕라 계수는, DS3D_MINDOPPLERFACTOR 로부터 DS3D_MAXDOPPLERFACTOR 의 범위에서 변경할 수 있지만, 이것들은 각각 0.0 으로 10.0 으로 설정되어 있다. 값 0 은, 사운드에 돕라편이를 적용하지 않는 것을 의미한다. 다른 값은, 열매 세계의 돕라편이에 대한 승수를 나타낸다. 바꾸어 말하면, 값 1 (또는 DS3D_DEFAULTDOPPLERFACTOR)은 열매 세계에서 체험하는 돕라편이를 사운드에 적용하는 것, 값 2 는 열매 세계의 돕라편이의 2 배를 의미한다. 이하 같이이다.

IDirectSound3DListener8::SetDopplerFactor 와 IDirectSound3DListener8::GetDopplerFactor 의 각 메소드를 사용하면(자), 돕라 계수를 설정 및 취득할 수 있다.


롤 오프 계수

롤 오프와는, 청취자와 사운드의 거리에 의해 생기는 소리의 감쇠의 정도이다. DirectSound 는 롤 오프 계수라고 부르는 변수에 의해, 롤 오프의 무시, 과장, 열매 세계와 같은 이펙트의 재현이 생긴다.

롤 오프 계수는, DS3D_MINROLLOFFFACTOR 로부터 DS3D_MAXROLLOFFFACTOR 의 범위에서 변경할 수 있지만, 이것들은 각각 0.0 으로 10.0 으로 설정되어 있다. 값 DS3D_MINROLLOFFFACTOR 는, 사운드에 롤 오프를 적용하지 않는 것을 의미한다. 다른 값은, 열매 세계의 롤 오프에 대한 승수를 나타낸다. 바꾸어 말하면, 값 1 (DS3D_DEFAULTROLLOFFFACTOR)은 열매 세계에서 체험하는 롤 오프를 사운드에 적용하는 것, 값 2 는 열매 세계의 롤 오프의 2 배를 의미한다. 이하 같이이다.

IDirectSound3DListener8::SetRolloffFactor 와 IDirectSound3DListener8::GetRolloffFactor 의 각 메소드를 사용하면(자), 롤 오프 계수를 설정 및 취득할 수 있다.

개별의 사운드 버퍼의 거리에 의한 이펙트를 변경하기 위해서, 그 버퍼의 최소 거리를 설정할 수 있다. 상세한 것에 대하여는, 「최소 거리와 최대 거리」를 참조할것.


이펙트의 사용법

DirectX Audio 는, DMO (DirectX Media Object)에 의한 사운드의 이펙트 처리를 지원 하고 있다. DMO 의 개요에 대해서는, DirectShow 의 메뉴얼의 「DirectX Media Object 의 개요」를 참조할것.

모든 DirectX 어플리케이션으로, 표준 이펙트세트를 사용할 수 있다. 그 외의 DMO 는 시스템에 등록된다.

웨브리바브 이외의 모든 표준적인 DMO 는, DirectSound 가 지원 하고 있는 임의의 샘플 레이트로, 1 개(살) 또는 2 개의 채널을 사용해, 8 비트 또는 16 비트의 PCM 웨이브 포맷의 데이터를 처리할 수 있다. 웨브리바브는 8 비트의 샘플을 지원 하고 있지 않다.

다음의 주제에서는, 이펙트의 설정과 사용법에 대해 설명한다.

  • 버퍼에서의 이펙트의 설정
  • 이펙트 파라미터
  • 표준 이펙트

여기에서는, 오디오 패스에 있어서의 이펙트의 사용법을 중심으로 설명하지만, 많은 정보는, 독자적인 DirectSound 버퍼를 관리하는 어플리케이션에도 대응한다. 「DirectSound 에서의 이펙트의 사용법」을 참조할것.


버퍼에서의 이펙트의 설정

DirectMusic Producer 로 생성 한 세그먼트(segment)를, 오디오 패스 구성을 사용해 연주하고 있는 경우, 이펙트는 구성 오브젝트로부터 오디오 패스를 생성 했을 때에 설정된다. 표준 오디오 패스에는 이펙트도 보관 유지된다. 다만, 실행시에 커스텀 오디오 패스로 이펙트를 이행 하거나 표준 오디오 패스에 이펙트를 추가하고 싶은 경우가 있다. 예를 들어, 웨이브 또는 MIDI 파일에 이펙트를 적용할 수 있도록(듯이), 표준 오디오 패스에 이펙트를 추가하고 싶은 경우가 있다.

오디오 패스에 이펙트를 적용하려면 , 우선 패스 위에의 버퍼에의 IDirectSoundBuffer8 인터페이스를 취득한다. 다음에,IDirectSoundBuffer8::SetFX 를 사용해, 그 버퍼에 1 개 또는 복수의 이펙트를 설정한다.

버퍼 인터페이스를 취득하는 방법에 대해서는, 「오디오 패스로부터의 오브젝트의 취득」을 참조할것. GetObjectInPath 의 호출로 표준 오디오 패스 버퍼를 식별하는 방법에 대해서는, 「표준 오디오 패스」의 오디오 패스의 타입을 참조할것.

다음의 샘플 코드에서는, 표준 오디오 패스를 설정해, 패스로부터 버퍼를 취득해, 버퍼상에서 메아리 이펙트를 설정해 있다.

// pPerformance 이 유효한 IDirectMusicPerformance8
// 인터페이스 포인터이라고 가정한다.

IDirectMusicAudioPath*  g_p3DAudioPath;
IDirectSoundBuffer8*    g_pDSBuffer;
HRESULT                 hr;

// 음원 및 환경 리바브밧파를 사용해,
// 표준 오디오 패스를 생성 한다. 패스는 액티브하게 하지 않는다.
// 버퍼가 실행중의 경우, SetFX 는 실패한다.

if( FAILED(hr = pPerformance->CreateStandardAudioPath(
    DMUS_APATH_DYNAMIC_3D, 64, FALSE, &g_p3DAudioPath)))
    return hr;

// 오디오 패스의 버퍼를 취득한다.

if( FAILED(hr = g_p3DAudioPath->GetObjectInPath(DMUS_PCHANNEL_ALL,
    DMUS_PATH_BUFFER, 0, GUID_NULL, 0, IID_IDirectSoundBuffer8,
    (LPVOID*) &g_pDSBuffer)))
    return hr;

// 이펙트를 기술한다.

DSEFFECTDESC dsEffect;
dsEffect.dwSize = sizeof(DSEFFECTDESC);
dsEffect.dwFlags = 0;
dsEffect.guidDSFXClass = GUID_DSFX_STANDARD_ECHO;
dsEffect.dwReserved1 = 0;
dsEffect.dwReserved2 = 0;

DWORD dwResults;

// 이펙트를 설정한다
if (FAILED(hr = g_pDSBuffer->SetFX(1, &dsEffect, &dwResults)))
    return hr;

// 여기서 dwResults 의 값을 체크해, 이펙트가
// 어떻게 할당할 수 있고 있는지를 확인할 수 있다.

// 패스를 액티브하게 한다.

g_p3DAudioPath->Activate(TRUE);


이펙트 파라미터

사운드 이펙트의 파라미터를 설정 또는 취득하려면 , 우선, 그 이펙트를 포함한 버퍼의 적절한 인터페이스를 취득할 필요가 있다. 다음의 인터페이스를 사용해, DirectX Audio 로 제공되는 DMO 의 파라미터에 액세스 할 수 있다.

  • IDirectSoundFXChorus8
  • IDirectSoundFXCompressor8
  • IDirectSoundFXDistortion8
  • IDirectSoundFXEcho8
  • IDirectSoundFXFlanger8
  • IDirectSoundFXGargle8
  • IDirectSoundFXI3DL2Reverb8
  • IDirectSoundFXParamEq8
  • IDirectSoundFXWavesReverb8

이펙트의 인터페이스를 취득하려면 , DMUS_PATH_BUFFER_DMO 를 dwStage 파라미터로서 IDirectMusicAudioPath8::GetObjectInPath 또는 IDirectMusicSegmentState8::GetObjectInPath 에 건네준다. 오디오 패스에 복수의 버퍼가 포함되는 경우,dwBuffer 는 버퍼의 인덱스가 아니면 안된다. 표준 오디오 패스의 버퍼의 인덱스 번호에 대해서는, 「표준 오디오 패스」의 오디오 패스의 타입을 참조할것.

다음의 샘플 코드는, 오디오 패스 구성으로부터 생성 된 버퍼의 가그르에페크트의 인터페이스를 취득한다. 다음에, 이 인터페이스를 사용해, 이펙트의 파라미터를 변경하고 있다.

// g_p3DAudioPath 는 유효한 IDirectMusicAudioPath8 포인터이며,
// IDirectMusicPerformance8::CreateAudioPath 로부터 취득된다.
// 예를 알기 쉽게 하기 위해서, 에러 처리는 생략 하고 있다.

HRESULT                  hr;
IDirectSoundFXGargle8*   pEffectDMO;
DSFXGargle               FXParams;

hr = g_p3DAudioPath->GetObjectInPath(DMUS_PCHANNEL_ALL,
        DMUS_PATH_BUFFER_DMO, 0,
        GUID_All_Objects, 0, IID_IDirectSoundFXGargle8,
        (LPVOID*) &pEffectDMO);

hr = pEffectDMO->GetAllParameters(&FXParams);
FXParams.dwRateHz  = DSFXGARGLE_RATEHZ_MIN;
hr = pEffectDMO->SetAllParameters(&FXParams);

어플리케이션이 독자적인 DirectSound 버퍼를 관리하는 경우, 이펙트 파라미터의 변경을 곧바로 실행할 필요가 있다. 효율을 높이기 (위해)때문에, DirectSound 는,IDirectSoundBuffer8::Play 를 호출하기 전에, 재생 커서의 위치로부터 시작 해 100 밀리 세컨드의 사운드 데이터를 처리한다. 이 처리는, 이하의 몇개의 호출이 실행된 후에 실시할 수가 있다.

  • IDirectSoundBuffer8::Unlock
  • IDirectSoundBuffer8::Stop
  • IDirectSoundBuffer8::SetCurrentPosition
  • IDirectSoundBuffer8::SetFX

이러한 메소드의 어느쪽이든을 호출한 다음에 이펙트 파라미터를 변경했을 경우, 처리필 보고의 데이터가 재생될 때까지, 새로운 파라미터는 들리지 않는다. 이것을 회피하려면 , 이하의 어느쪽이든을 실행한다.

  • 버퍼에의 데이터의 기입을, 파라미터의 변경전은 아니고 변경 후에 실시한다.
  • 버퍼로 Stop 또는 SetCurrentPosition 를 호출해, 데이터의 처리를 강제적으로 파라미터 설정 뒤로 한다.


표준 이펙트

여기에서는, DirectX Audio 의 사운드 이펙트를 소개한다. 다음의 이펙트에 대해 설명한다.

  • 코러스
  • 콘프렛션
  • 뒤틀림
  • 메아리
  • 환경 리바브
  • 플랜지
  • 가굴
  • 파라메트릭 이퀼라이저
  • 웨브리바브


코러스

코러스는, 원의 사운드에 약간의 지연을 부가해 메아리를 걸쳐 메아리의 지연을 약간 변조해 생성 되는 음성 이중화 이펙트이다.

이 이펙트는,IDirectSoundFXChorus8 인터페이스에 의해 나타내진다. 그 파라미터는,DSFXChorus 구조체에 저장 된다.


콘프렛션

콘프렛션이란, 특정의 진폭을 넘는 시그널의 변동을 삭감하는 것이다.

이 이펙트는,IDirectSoundFXCompressor8 인터페이스에 의해 나타내진다. 그 파라미터는,DSFXCompressor 구조체에 저장 된다.


뒤틀림

뒤틀림을 실행하려면 , 신호에 화음을 추가한다. 이것에 의해, 레벨이 올랐을 때에 웨이브 폼의 최상부가 사각형이 되는지, 잘라내진다.

이 이펙트는,IDirectSoundFXDistortion8 인터페이스에 의해 나타내진다. 그 파라미터는,DSFXDistortion 구조체에 저장 된다.


메아리

메아리 이펙트에 의해, 사운드 전체가 고정 지연의 뒤, 반복해진다.

이 이펙트는,IDirectSoundFXEcho8 인터페이스에 의해 나타내진다. 그 파라미터는,DSFXEcho 구조체에 저장 된다.


환경 리바브

DirectX 에서는, Interactive Audio Special Interest Group 에 의해 발행된 Interactive 3-D Audio, Level 2 (I3DL2) 사양에 근거하는 환경 리바브를 지원 하고 있다.

DirectX 환경 리바브에페크트는, I3DL2 사양의 청취자 프로퍼티의 이행이다. 이 릴리스에서는, 음원 프로퍼티는 지원되어 있지 않다.

청취자에게 닿는 사운드는, 3 개(살)의 일시적인 컴퍼넌트를 가진다.

  • 직접 패스는, 어느 표면에도 반사하지 않고, 음원으로부터 청취자에게 똑바로 진행되는 오디오 시그널이다. 따라서, 직접 패스 시그널은 1 개 밖에 없다.
  • 초기 반사음은, 벽, 상, 천정등의 표면에 1, 2 회 반사한 후, 청취자에게 닿는 오디오 시그널이다. 시그널이, 청취자에게 닿기까지 1 회만 벽에 해당된 소리인 경우, 이 시그널은 1 차 반사음으로 불린다. 청취자에게 닿기까지 벽에 2 회 반사한 소리는, 2 차 반사음으로 불린다. 인간이 보통 개별적으로 감지할 수 있는 것은, 1 차 반사음 또는 2 차 반사음 뿐이다.
  • 후기 리바브, 또는 단순한리바브은 , 저다음 반사음의 편성, 보통, 강함이 감소해 나가는 연속하는 메아리의 겹이든지로 구성된다.

초기 반사음과 후기 리바브의 편성은, 실내 이펙트로 불리는 일도 있다.

리바브프로파티에는 다음의 것이 있다.

  • 초기 반사음 및 후기 리바브의 감쇠.
  • 롤 오프 계수, 즉 반사한 시그널이 거리에 응해 감쇠하는 비율. 직접 패스의 롤 오프 계수는, DirectSound 청취자에 의해 관리된다.
  • 반사음의 지연. 이것은, 직접 패스의 시그널의 도달과 최초의 초기 반사음의 도달과의 시간차이이다.
  • 리바브의 지연. 이것은, 최초의 초기 반사음과 후기 리바브의 도달과의 시간차이이다.
  • 디케이 시간. 이것은, 후기 리바브의 도달과 그 강함이 60 dB 감소하는 시간과의 시간 간격이다.
  • 확산. 후기 리바브의 1 초 쯤의 메아리수 에 비례한다. 이행에 의해, 리바브디케이에 따라 밀도는 변화한다. DirectX 에서는, 이행에 의한 허용 범위의 퍼센티지를 설정하는 것에 의해, 어플리케이션으로 이 프로퍼티를 제어할 수 있다.
  • 밀도. 후기 리바브의 1 Hz 근처의 공진수 에 비례한다. 밀도가 낮을 정도(수록), 좁은 실내의 소리와 같이, 속이 비어 있는 소리가 된다. DirectX 에서는, 이행에 의한 허용 범위의 퍼센티지를 설정하는 것에 의해, 어플리케이션으로 이 프로퍼티를 제어할 수 있다.

리바브프로파티는 IDirectSoundFXI3DL2Reverb8 인터페이스에 의해 나타내져 환경의 파라미터는 DSFXI3DL2REVERB 구조체에 포함되어 있다.

DirectX 에서는, 산으로부터 하수관까지, 다양한 오디오 환경의 리바브프로파티를 기술하는 수많은 디폴트의 파라미터, 즉 pre-set값을 지원 하고 있다. 대부분의 어플리케이션에서는,IDirectSoundFXI3DL2Reverb8::SetPreset 를 사용해, 이러한 환경의 어느쪽이든을 간단하게 선택할 수 있다.

커스텀 프로퍼티를 설정하려면 ,IDirectSoundFXI3DL2Reverb8::SetAllParameters 를 사용한다. IDirectSoundFXI3DL2Reverb8::GetAllParameters 를 사용해, 현재의 프로퍼티를 취득할 수 있다.


플랜지

플랜지는, 원의 시그널과 그 메아리와의 사이의 지연이 매우 짧고, 시간에 의해 변화하는 메아리 이펙트이다. 이 결과는, 스이핑사운드로 불리는 일도 있다. 플랜지라고 하는 용어는, 테이프 릴의 가장자리 (flange)를 잡아 회전 속도를 변화시키고 있었던 것에 유래한다.

이 이펙트는,IDirectSoundFXFlanger8 인터페이스에 의해 나타내진다. 그 파라미터는,DSFXFlanger 구조체에 저장 된다.


가굴

가그르에페크트는, 신호의 진폭을 곱셈한다.

이 이펙트는,IDirectSoundFXGargle8 인터페이스에 의해 나타내진다. 그 파라미터는,DSFXGargle 구조체에 저장 된다.


파라메트릭 이퀼라이저

파라메트릭 이퀼라이저는, 지정된 주파수의 시그널을 증폭 또는 감쇠시킨다.

같은 버퍼에 GUID_DSFX_STANDARD_PARAMEQ 의 복수의 인스턴스를을 설정하는 것에 의해, 복수의 피치의 파라메트릭 이퀼라이저 이펙트를 병행해 적용할 수 있다. 이것에 의해, 어플리케이션으로 하드웨어 이퀼라이저와 같은 톤 컨트롤을 실현할 수 있다.

이 이펙트는,IDirectSoundFXParamEq8 인터페이스에 의해 나타내진다. 그 파라미터는,DSFXParamEq 구조체에 저장 된다.


웨브리바브

웨브리바브는 음악용의 이펙트이다. 웨브리바브 DMO 는, Microsoft 에 라이센스 되고 있는 Waves MaxxVerb 테크놀러지에 근거하고 있다.

이 이펙트는,IDirectSoundFXWavesReverb8 인터페이스에 의해 나타내진다. 그 파라미터는,DSFXWavesReverb 구조체에 저장 된다.


버퍼 체인

사운드는, 반드시 1 개의세칸다리사운드밧파만을 경유 하지 않아도 되다. 오디오 패스의 버퍼는, 다른 세칸다리밧파에 데이터를 보낼 수가 있다. 이 처리의 이점은, 복수의 버퍼로부터의 사운드를 공유 버퍼에 전송 해, 거기서 공통의 3D 파라미터나 특수 효과를 적용할 수 있는 것이다. 버퍼를 공유 하면, 보다 효율이 높아진다.

DirectMusic Producer 파일에 파묻힌 오디오 패스 구성으로부터 오디오 패스가 생성 되었을 때는, 버퍼 체인이 자동적으로 설정된다. 상세한 것에 대하여는, 「오디오 패스의 사용법」을 참조할것.

DirectX 8.0 은, DirectSound API 에 의한 버퍼 체인의 생성을 지원 하고 있지 않다.


어레인지 요소의 사용법

여기서 설명하는 내용은, 동적인 뮤직 컴퍼넌트를 DirectX Audio 어플리케이션에 짜넣기 위한 가이드이다. 여기에서는, 코드 맵이나 스타일등의 요소의 기본 사항을 이해하고 있는 것을 전제로 하고 있다. 이것들에 대해 불명한 점은, 「어레인지용의 뮤직 요소」를 참조할것.

개개의 어레인지 요소를 사용하지 않고 , DirectMusic Producer 의 파일을 어플리케이션에 짜넣는 일도 가능하다. 많은 어플리케이션에서는, 완전하게 생성 된 세그먼트(segment)만이 사용되고 있다. 그러나, 개별의 컴퍼넌트를 사용하는 것에 의해, 실행시의 퍼포먼스를 한층 더 제어할 수가 있다.

설명하는 주제는, 다음과 같다.

  • 어레인지용의 뮤직 파일
  • 어레인지용의 프로그래밍 개요
  • 스타일의 사용법
  • 모티프의 사용법
  • 코드 맵의 사용법
  • 템플릿의 사용법
  • 트란지션의 사용법


어레인지용의 뮤직 파일

DirectMusic 콤포지션을 프로그래밍 하면나무는, DirectMusic Producer 또는 같은 어플리케이션으로 생성 된 다양한 파일을 사용한다. 이러한 요소를 COM 오브젝트로서 어플리케이션에 로드해, 그러한 오브젝트에의 인터페이스를 취득하는 「오디오 데이터의 로드」를 참조할것.

다음의 표는, 개발자가 취급하는 파일 오브젝트의 타입을 나타내고 있다. 이러한 오브젝트는 모두, 컨테이너 파일 또는 리소스로부터도 취득할 수 있다.

클래스 GUID 는, 오브젝트를 로드할 때에 DMUS_OBJECTDESC 구조체의 guidClass 멤버에 기입하는 값이다.

요소 | 클래스 GUID | 인터페이스 | 파일 타입
밴드 | CLSID_DirectMusicBand | IDirectMusicBand8 | bnd
코드 맵 | CLSID_DirectMusicChordMap | IDirectMusicChordMap8 | cdm
DLS 콜렉션 | CLSID_DirectMusicCollection | IDirectMusicCollection8 | dls
세그먼트(segment) | CLSID_DirectMusicSegment8 | IDirectMusicSegment8 | sgt
스타일 | CLSID_DirectMusicStyle | IDirectMusicStyle8 | sty

주 밴드는 스타일의 일부로서 오쏘링 할 수 있지만, 그 경우, 스타일을 로드할 때 그것들도 자동적으로 로드 된다. 같이 스타일과 밴드는 세그먼트(segment)에 오쏘링 할 수 있다. 이 경우, 이러한 요소를 다른 파일로 나눌 필요없다.

파일에는, 다른 파일에의 참조를 포함할 수가 있다. 스타일에 밴드 파일에의 참조가 포함되어 있는 경우, 로더가 밴드 파일을 찾아낼 수가 있으면, 스타일이 로드 될 때 자동적으로 밴드도 로드 된다.


어레인지용의 프로그래밍 개요

실행시에 어레인지 되는 음악을 이행 할 경우에, 이미 오쏘링 되고 있는 오브젝트를 빌딩 블록으로서 사용한다. 작가나 다른 컨텐트 프로바이더와 상담하면서, 작은 빌딩 블록으로서 취득하는 뮤직 데이터를 선택하는 것으로써, 실행시에 가장 높은 유연성이나 바리에이션을 실현하거나 음악을 보다 완성된 형태로 정의하기 위해서, 미리 생성 된 요소를 보다 많이 이용할 수 있다.

최대의 빌딩 블록을 사용해, 사운드의 재생에 대해 퍼포먼스가 지시해야 하는 정보의 모든 것이 포함되어 있는, 스타일, MIDI 파일, 또는 웨이브에 근거하는, 고도로 구조화 된 세그먼트(segment)를 로드한다. 필요한 것은, 섹션을 로드해,IDirectMusicSegment8 인터페이스의 조회를 실시하는 것 뿐이다. 이 인터페이스 포인터를 IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 메소드에 건네준다. 스타일 재생 엔진은, 스타일로부터 패턴 바리에이션을 선택해, 고정 코드 진행에 따라 이것들을 연주한다. 또, MIDI 베이스의 세그먼트(segment)의 경우는, MIDI 순서를 연주한다. 밴드 체인지는, 보통, 세그먼트(segment)에 포함된다.

보다 작은 빌딩 블록을 사용하는 경우는, 다음의 요소를 취득한다.

  • 코드 맵. 코드 진행의 도로지도를 나타낸다.
  • 스타일. 기본적인 멜로디나 리듬과 함께, 바리에이션, 모티프, 및 장식을 정의한다.
  • 템플릿 세그먼트(segment). 구조적인 계획이며, 세그먼트(segment)의 길이, 루프의 유무,홈 레벨의 변경이나 장식을 배치하는 장소, 코드 맵으로 싸인 포스트의 역할을 완수하는 코드의 타입을 포함해 재생의 다양한 측면을 제어한다.

IDirectMusicComposer8::ComposeSegmentFromTemplate 메소드를 사용해, 코드 맵, 스타일, 및 템플릿을 조합해 세그먼트(segment)를 구축한다.

실행시의 음악 어레인지를 보다 유연하게 실시하려면 ,IDirectMusicComposer8::ComposeSegmentFromShape 메소드를 사용해, 템플릿은 아니고 정의 끝난셰이프에 근거하는 세그먼트(segment)를 생성 한다. 셰이프는, 커멘드 및 싸인 포스트트럭의 생성에 사용되어 장식 패턴, 코드 진행, 및 코드 변경의 빈도의 선택을 제어한다.

세그먼트(segment)를 연주할 경우에, 파트의 연주에 사용하는 밴드를 제어할 수도 있다. 밴드는 보통, 스타일 및 템플릿에 오쏘링 되지만, 개별의 파일로서 제공할 수도 있다. 밴드를 동적으로 변경하려면 ,IDirectMusicBand8::CreateSegment 메소드를 사용해, 밴드만으로부터 완성되는 세칸다리세그먼트를 생성 해, 음색이나 음색의 설정을 프라이머리 세그먼트(segment)에 할당할 때, 이 세칸다리세그먼트를 연주한다. 상세한 것에 대하여는, 「밴드의 사용법」을 참조할것.


스타일의 사용법

DirectMusic 스타일 오브젝트는, 음악 패턴의 모임을 나타낸다. 보통은, 장식과 모티프, 박자 기호, 템포, 및 밴드가 포함된다. 기본적인 리듬과 각 음색 파트에서 연주되는 노트가 정의된다.

개념에 대해서는, 「스타일」을 참조할것.

스타일 단독으로는, 실행시에 뮤직 세그먼트(segment)를 생성 하는데 충분한 정보를 갖추지 않았다. 이 때문에, 스타일 외에 2 개의 컴퍼넌트가 필요하다. 코드 맵 (코드 진행의 맵)과 연주시에홈 레벨과 장식을 설정하는 커멘드 트럭이다. 커멘드 트럭은 템플릿으로부터 꺼내는지, 실행시에 셰이프로부터 생성한다. 코드 맵은, 보통은 코드 맵 파일이나 리소스로부터 취득한다.

템플릿에 근거해, 커멘드 트럭을 사용해 세그먼트(segment)를 생성 하려면 ,IDirectMusicComposer8::ComposeSegmentFromTemplate 메소드를 호출한다. 「템플릿의 사용법」을 참조할것.

셰이프에 근거해 세그먼트(segment)를 생성 하려면 ,IDirectMusicComposer8::ComposeSegmentFromShape 메소드를 호출한다. 스타일과 코드 맵에의 포인터를 지정한다. 또, 코드 변경의 빈도를 제어하는 화음 진행의 레이트, 및 홈 레벨과 장식의 진행을 결정하는 셰이프 정수도 지정한다.


모티프의 사용법

모티프란, 보통은 인터랙티브 이벤트에 응해 연주되어서 , 기본적인 스타일 패턴상에서 연주되는 것을 의도한, 스타일내의 특종인 패턴이다. 모티프에는, 다른 패턴과 같은 복잡함을 줄 수가 있다. 또, 바리에이션이나 복수의 음색 파트를 갖추는 일도 가능하지만, 보통은 다양한 백그라운드 패턴과 조합해도 적절히 들리는, 짧은 단순한 음형이다. 커스텀 DLS 음색으로 연주하는 사운드 이펙트로도 된다.

어느 모티프도 스타일의 일부로서 오쏘링 되므로, 스타일을 로드하자마자 모티프를 이용할 수 있다. 특정의 모티프를 재생할 수 있도록(듯이) 하려면 ,IDirectMusicStyle8::GetMotif 메소드를 호출해, 다음의 파라미터를 건네준다.

  • 모티프명. 이 정보는 스타일의 문서로 확인하는지,IDirectMusicStyle8::EnumMotif 메소드를 사용해 인덱스값으로부터 취득한다.
  • 메소드가 생성 하는 세그먼트(segment) 오브젝트에의 IDirectMusicSegment8 인터페이스를 받는 포인터.

다음의 샘플 코드에서는,pwszMotifName 로 이름이 지정된 모티프를 취득해, 연주한다.

void PlayMotif(IDirectMusicPerformance8* pPerf,
         IDirectMusicStyle8* pStyle,
         WCHAR* pwszMotifName)
{
  IDirectMusicSegment* pSeg;

  // 스타일로부터 모티프 세그먼트(segment)를 취득한다. GetMotif()는,
  // 모티프를 찾아낼 수 없었던 경우는 S_FALSE 를 돌려주므로,
  // S_OK 가 돌려주어지는 것을 확인한다.

  if (S_OK == pStyle->GetMotif(pwszMotifName, &pSeg))
  {
    // 세그먼트(segment)를 연주한다.

    pPerf->PlaySegment(pSeg,
                       DMUS_SEGF_BEAT | DMUS_SEGF_SECONDARY,
                       0,
                       NULL);
    pSeg->Release();
  }
}

보통, 모티프는 프라이머리 세그먼트(segment)에 거듭해 연주되기 (위해)때문에,pSeg 는 세칸다리세그먼트로서 연주되는 점에 주의 해야 한다. 모티프에는 코드 트럭이나 밴드 트럭이 없기 때문에, 이것을 프라이머리 세그먼트(segment)로서 연주할 수 없다. 무음 상태 때에 모티프를 연주하는 경우는, 스타일로부터 공백의 패턴만을 포함한 프라이머리 세그먼트(segment)를 생성 해, 모티프를 연주하는 동안, 이 세그먼트(segment)를 연주해 둔다.


코드 맵의 사용법

코드 맵 오브젝트는, 기초가 되는 화음 구조와 음악의 분위기를 제공하는 코드의 콜렉션을 나타낸다. 코드 맵에는, 많은 관련하는 코드에 의한 몇개의 패스가 포함되어 작곡가 엔진이 음악의 부분의 코드 진행을 결정할 때에, 다양한 선택이 가능해진다.

개념에 대해서는, 「코드 맵」을 참조할것.

오쏘링 된 세그먼트(segment)의 경우, 보통, 어플리케이션은 코드 맵에 관여할 필요는 없다. 코드 맵은, 고정 코드 진행을 생성 하기 위해서, 오쏘링의 단계에서 사용된다. 다만, 코드 맵을 사용해, 실행시에 세그먼트(segment)를 생성 하거나 기존의 세그먼트(segment)의 코드 진행을 변경할 수도 있다.

스타일의 일부로서 코드 맵 참조를 오쏘링 했을 경우는,IDirectMusicStyle8::GetChordMap 메소드에 (작가가 할당한) 코드 맵의 이름을 건네주어,IDirectMusicChordMap8 인터페이스에의 포인터를 취득할 수가 있다. IDirectMusicStyle8::EnumChordMap 메소드를 사용해, 특정의 코드 맵을 검색할 수도 있다. 또,IDirectMusicStyle8::GetDefaultChordMap 메소드를 사용해, 스타일의 디폴트 코드 맵에의 포인터를 취득할 수도 있다.

주 DirectMusic Producer 에서는, 스타일 파일에의 코드 맵 참조의 오쏘링은 지원되어 있지 않다.

IDirectMusicComposer8::ComposeSegmentFromTemplate 또는 IDirectMusicComposer8::ComposeSegmentFromShape 메소드를 사용해 세그먼트(segment)를 생성 할 경우에, 어레인지용의 코드 맵을 설정한다. 상세한 것에 대하여는, 「스타일의 사용법」을 참조할것.

세그먼트(segment)를 생성 한 다음에,IDirectMusicComposer8::ChangeChordMap 메소드를 호출해, 언제라도 코드 맵을 변경할 수 있다. 이것에 의해, 기본적인 리듬이나 멜로디를 바꾸는 일 없이, 음악의 분위기를 변경하는 효과가 있다.

각 코드 맵은, 24 의 음정으로부터 완성되는 기조의 스케일을 가진다. IDirectMusicChordMap8::GetScale 메소드를 사용해, 스케일의 음정을 결정할 수가 있다. 이 메소드의 pdwScale 파라미터로 나타나는 변수의 하위 24 비트는, 대응하는 음정이 스케일의 일부가 되어 있는지 어떤지에 응해 설정 또는 소거된다. 상위 8 비트는, 스케일의 루트음을, 0 ~ 23 의 범위 (낮은 C 로부터 중간의 B)의 정수로 설정한다.


템플릿의 사용법

템플릿은, 연주 가능한 음악의 세그먼트(segment)를 실행시에 어레인지 할 경우에 사용할 수 있는 세그먼트(segment)이다. 템플릿은, 세그먼트(segment)의 길이와 루프 포인트를 설정한다. 커멘드 트럭이 제공되어홈 레벨의 변경이나, 장식 패턴의 선택이 제어된다. 또, 새로운 코드를 각각 어느 싸인 포스트그룹으로부터 취득하는지를 지정해, 세그먼트(segment)를 어레인지 할 경우에 코드 맵을 어떻게 사용할지도 지시한다.

개념에 대해서는, 「템플릿」을 참조할것.

각 템플릿은 DirectMusic 세그먼트(segment) 오브젝트에 의해 나타내진다.

템플릿을 취득하는 방법은 2 개 있다.

  • 세그먼트(segment) 파일 또는 리소스로부터 템플릿을 로드한다. 템플릿을 DirectMusicObject 로서 로드해,IDirectMusicSegment8 인터페이스의 조회를 실시한다. 상세한 것에 대하여는, 「오디오 데이터의 로드」를 참조할것.
  • IDirectMusicComposer8::ComposeTemplateFromShape 메소드를 사용해, 셰이프로부터 템플릿을 생성 한다. 템플릿의 길이, 전체의 셰이프, 인트로와 엔드의 장식 패턴을 연주할지 어떨지, 및 엔딩의 길이를 선택한다. IDirectMusicSegment 인터페이스에의 포인터가 돌려주어진다.

템플릿 세그먼트(segment) 오브젝트를 취득한 후, 스타일이나 코드 맵에의 포인터와 함께, 그 오브젝트를 IDirectMusicComposer8::ComposeSegmentFromTemplate 메소드에 건네줄 수 있다. 또, 코드 변경의 빈도를 설정하는 화음 진행도 지정한다. ComposeSegmentFromTemplate 메소드는 세그먼트(segment)를 생성 해,IDirectMusicSegment8 인터페이스에의 포인터를 돌려준다. 이 포인터를 IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 메소드에 건네준다.


트란지션의 사용법

어느 세그먼트(segment)를 정지해 다음의 세그먼트(segment)를 시작할 때에, 귀에 거슬리는 소리인 중단이 돌연 발생하는 것을 방지하기 위해(때문에), 또는 음악을 종지형 (카덴트)에 이행 하기 위해서, 적절한 트란지션을 제공하는 중간 또는 시종의 세그먼트(segment)를 생성 하도록(듯이) 작곡가에게 지시할 수 있다.

트란지션세그먼트를 어레인지 하려면 , 3 개의 방법의 어느쪽이든을 선택할 수 있다.

  • IDirectMusicPerformance8::PlaySegmentEx 메소드를 사용하면(자),pTransition 파라미터로 세그먼트(segment)를 지정할 수 있다. 이 세그먼트(segment)는, 새롭게 어레인지 하는 트란지션의 템플릿으로서 사용된다. 트란지션은 i64StartTime 로 연주되어pSource 로 지정된 세그먼트(segment)가 연주된다.
  • IDirectMusicComposer8::AutoTransition 메소드는, 퍼포먼스에의 포인터를 받아, 현재 연주중의 세그먼트(segment)로부터 개발자가 지정한 2 번째의 세그먼트(segment)에의 트란지션을 생성 한다. 계속되어, 재생의 목적으로 트란지션세그먼트와 2 번째의 세그먼트(segment)를 자동적으로 삽입해, 이것들 양쪽 모두의 세그먼트(segment)에의 IDirectMusicSegmentState 인터페이스를 돌려준다. 트란지션의 연주는, 즉시, 또는 dwFlags 파라미터로 지정된 다음의 경계로부터 시작 된다. 옵션으로, 2 번째의 세그먼트(segment)를 NULL 에도 할 수 있지만, 그 경우는 트란지션을 거쳐 무음에 이른다.
  • IDirectMusicComposer8::ComposeTransition 메소드는, 1 번째의 세그먼트(segment)의 임의의 장소로부터 2 번째의 세그먼트(segment)의 선두 또는 무음에 이르는 트란지션을 생성 해, 어플리케이션이 트란지션을 연주할 수 있도록(듯이) IDirectMusicSegment 인터페이스에의 포인터를 돌려준다.

AutoTransition 와 ComposeTransition 의 어느 쪽의 메소드도 파라미터로서 코드 맵, 커멘드, 및 일련의 플래그를 받는다.

  • 코드 맵은, 보통 대로, 세그먼트(segment)의 코드 진행을 정의하는 코드 트럭을 생성 하기 위해서 사용된다.
  • 커멘드로서DMUS_COMMANDT_TYPES 열거형의 어느쪽이든을 지정한다. 커멘드는, 트란지션세그먼트의 커멘드 트럭으로 요구하는 패턴의 타입으로서 보통의 홈 패턴과 장식의 어느 쪽을 사용할까를 결정한다. 세그먼트(segment)를 연주할 때에, 스타일로부터 적절한 패턴이 선택된다.
  • DMUS_COMPOSEF_FLAGS 로부터 플래그를 선택해, 트란지션의 상세, 특히 그 타이밍을 정의한다. DMUS_COMPOSEF_MODULATE 플래그를 사용해, 트란지션을 있는 조성으로부터 다른 조성에 원활히 이행 시킨다. 2 번째의 세그먼트(segment)가 없는 경우, 무음에의 변조는 불가능해서, 이 플래그는 이용할 수 없다.

AutoTransition 및mposeTransition 에 의해 생성 된 트란지션의 길이는, 보통 1 소절이다. 다만, DMUS_COMPOSEF_LONG 플래그가 포함되어 스타일내의 엔드 장식이 1 소절보다 긴 경우는, 1 소절보다 길어진다. 또, DMUS_COMMANDT_ENDANDINTRO 형의 경우는 2 소절 이상이 된다.


트럭의 어레인지

세그먼트(segment)내의 대부분의 트럭은 고정되고 있어 세그먼트(segment)를 연주할 때마다 같은 데이터가 생성된다. 다만, 트럭이 IDirectMusicTrack8::Compose 메소드를 이행 해, 적절히 설정되어 있는 경우, 연주의 시작시나 루프 할 때마다, 동적으로 데이터를 생성할 수 있다.

싸인 포스트트럭인 단일의 표준 트럭은, 어레인지를 지원 한다. 싸인 포스트트럭은, 코드 맵으로부터 새로운 코드 트럭을 어레인지 한다.

보통, 트럭 구성은 작가에 의해 설정되지만, 다음의 언젠가 또는 복수의 플래그를 IDirectMusicSegment8::SetTrackConfig 또는 IDirectMusicSegmentState8::SetTrackConfig 에 건네주는 것에 의해, 어플리케이션으로 트럭의 어레인지의 동작의 온과 오프를 바꿀 수가 있다.

DMUS_TRACKCONFIG_COMPOSING
트럭은,IDirectMusicSegment8::Compose 메소드에 의해 어레인지 된다.
DMUS_TRACKCONFIG_LOOP_COMPOSE
트럭은, 세그먼트(segment)가 루프 할 때마다 자동적으로 어레인지 된다.
DMUS_TRACKCONFIG_PLAY_COMPOSE
트럭은, 세그먼트(segment)가 시작 될 때마다 자동적으로 어레인지 된다.

자동적으로 어레인지를 하는 것은, 어레인지 한 내용을 보존하는 트럭이 세그먼트(segment)에 포함되어 있는 경우 뿐이다. 싸인 포스트트럭을 어레인지 하면나무는, 새로운 코드의 코드 트럭이 필요하다. 세그먼트(segment)를 연주하기 전에,IDirectMusicSegment8::Compose 를 호출하는 것에 의해, 필요한 트럭이 존재하는 것을 확인할 수 있다.

모든 어레인지를 수동으로 실시하는 경우는, 설정하는 구성 플래그는 DMUS_TRACKCONFIG_COMPOSING 뿐이다. 다른 2 개의 플래그가 모두 설정되어 있지 않은 경우, 트럭은,Compose 메소드를 호출했을 경우에게만 어레인지 된다.


오디오 스크립트의 사용법

스크립트는, DirectMusic Producer 등, 스크립트 에디터를 포함한 어플리케이션으로 오쏘링 된 오브젝트이다. 스크립트는 주로 텍스트로 구성되지만, 스크립트 오브젝트에는 몇개의 바이너리 파라미터도 포함되어 있다.

개요에 대해서는, 「오디오 스크립트」를 참조할것.

스크립트는,IDirectMusicLoader8::GetObject 메소드를 사용해 로드한다. IDirectMusicScript8 인터페이스를 취득해,IDirectMusicScript8::Init 를 호출해, 스크립트를 퍼포먼스에 관련짓는다.

다음의 코드에서는, 스크립트를 로드해 초기화하고 있다. m_pLoader 는 IDirectMusicLoader8 인터페이스로,m_PPerformance 는 IDirectMusicPerformance8 인터페이스이며,wstrFileName 에는 파일의 이름이 저장 되고 있다고 한다.

IDirectMusicScript8*  pScript = NULL;
DMUS_SCRIPT_ERRORINFO errInfo;
HRESULT               hr;

if (SUCCEEDED(hr = m_pLoader->LoadObjectFromFile(
        CLSID_DirectMusicScript, IID_IDirectMusicScript8,
        wstrFileName, (LPVOID*) &pScript)))
{
    hr = pScript->Init( m_pPerformance, &errInfo);
}

Init 를 제외해,IDirectMusicScript8 의 메소드에는, 3 개(살)의 주된 목적이 있다.

  • 스크립트로 선언된 변수의 값을 설정 및 취득한다. 스크립트 루틴은 파라미터를 받아들이지 않기 때문에, 변수는, 스크립트와 어플리케이션으로 정보를 교환하기 위한 유일한 방법이다.
  • 루틴을 호출한다. 어플리케이션 thread가 속행하려면 , 루틴의 실행이 완료하고 있을 필요가 있다.
  • 루틴과 변수를 열거한다. 이러한 메소드는, 주로 스크립트 편집 어플리케이션으로 사용된다.

열거 메소드를 제외한,IDirectMusicScript8 의 모든 메소드는,DMUS_SCRIPT_ERRORINFO 구조체로부터 에러 정보를 취득한다. 변수가 발견되지 않았던 경우나, 루틴내의 코드를 실행할 수 없었던 경우는, 에러가 발생할 가능성이 있다.

스크립트는, 어플리케이션으로 직접 로드 또는 호출을 실시하지 않아도 사용할 수 있다. DirectMusic Producer 로 생성 하는 세그먼트(segment)에 스크립트 트럭을 포함해, 스크립트내의 루틴의 호출을 방아쇠 할 수가 있다.


DirectSound 에서의 웨이브의 재생

여기에서는, DirectMusic 로더 및 퍼포먼스 오브젝트로 제공되는 서비스를 사용하지 않고 , DirectSound 버퍼를 사용해 웨이브를 재생하는 방법에 대해 설명한다.

DirectX 8.0 이후용으로 생성 된 대부분의 어플리케이션에서는, 웨이브 사운드를 재생하는 최적인 방법은, 웨이브 사운드를 세그먼트(segment)로서 로드해, 퍼포먼스로 재생하는 것이다. 이렇게 하는 것에 의해, 코드가 적게 되어, 사운드 이펙트와 뮤직을 밀접하게 통합할 수 있어 3D 버퍼에 넣기 전에, 오디오 패스 위에의 사운드를 믹싱 하는 등의 고도의 기능을 이용할 수 있다. 다만, 웨이브 사운드를 직접 버퍼로 재생할 수도 있다.

상세한 것에 대하여는, 다음의 주제를 참조할것.

  • DirectSound 의 재생의 개요
  • DirectSound 디바이스
  • DirectSound 버퍼
  • 웨이브 데이터의 사용법
  • DirectSound 에서의 이펙트의 사용법


DirectSound 의 재생의 개요

DirectSound 오브젝트는 디바이스를 나타내, 그 디바이스를 관리해, 사운드 버퍼를 생성 하기 위해서 사용된다.

1 개의 사운드 디바이스에 대해서 복수의 어플리케이션이 DirectSound 오브젝트를 생성 할 수가 있다. 입력초점이 있는 어플리케이션으로부터 다른 어플리케이션에 이동할 때에, 오디오 출력은 있는 어플리케이션의 스트림으로부터 다른 어플리케이션의 스트림으로 자동적으로 바뀐다. 따라서, 입력초점이 이동할 때에, 어플리케이션은 버퍼의 재생과 정지를 반복할 필요는 없다.

DirectSound 버퍼 오브젝트는, 사운드 데이터를 보관 유지하는 버퍼를 나타낸다. 버퍼 오브젝트는, 사운드의 재생의 시작, 정지, 일시정지, 주파수나 포맷등의 속성을 설정하기 위해서 사용된다.

프라이머리 사운드 버퍼는, 청취자가 실제로 (듣)묻는 오디오를 보관 유지한다. 각세칸다리사운드밧파는,1 개의 사운드 또는 오디오 스트림을 보관 유지한다. DirectSound 는 자동적으로 프라이머리 버퍼를 생성 하지만, 세칸다리밧파는 어플리케이션이 생성 해야 한다. 세칸다리밧파내의 사운드가 재생되면(자), DirectSound 는 프라이머리 버퍼내에서 이것들을 믹싱 해, 출력 디바이스에 배웅한다. DirectSound 를 믹싱 할 수 있는 버퍼수는 처리 시간에게만 제한되어 처리 시간이 허락하는 한 믹싱 할 수가 있다.

짧은 사운드는 전체를 버퍼에 로드해, 언제라도 단순한 메소드의 호출에 의해 재생할 수 있다. 긴 사운드는 스트리밍 할 필요가 있다. 어플리케이션에서는, 재생 커서의 위치를 폴링 하거나 재생 커서가 특정의 위치에 도달했을 때에 통지를 요구하는 것에 의해, 버퍼에 넣는 데이터를 스트리밍 해야 하는 시기를 확인할 수 있다.

데이터를 올바른 형식에 정돈해 세칸다리밧파에 보내는 것은, 개발자의 책임이다. DirectSound 에는, 웨이브 파일이나 리소스를 해석하는 기능은 없다. 그러나, SDK 샘플 어플리케이션내에, 이 태스크를 지원하는 코드가 기술되고 있다.


DirectSound 디바이스

어플리케이션에 DirectSound 를 이행 하는 최초의 스텝은, 사운드 디바이스를 나타내는 DirectSound 오브젝트를 생성 하는 것이다.

여기에서는, 이용 가능한 사운드 디바이스의 열거, 디바이스에 대한 DirectSound 오브젝트의 생성, 오브젝트의 메소드를 사용한 협조 레벨의 설정, 디바이스 능력의 취득, 사운드 버퍼의 생성, 시스템 스피커의 구성, 하드웨어 메모리의 압축을 어플리케이션이 실시하는 방법에 대해 설명한다.

  • 사운드 디바이스의 열거
  • DirectSound 오브젝트의 생성
  • 협조 레벨
  • 디바이스의 능력
  • 스피커의 구성
  • 하드웨어 메모리의 압축


사운드 디바이스의 열거

유저가 좋아하는 재생장치로 단순하게 사운드를 재생할 뿐(만큼)의 어플리케이션에서는, 이용 가능한 디바이스를 열거할 필요는 없다. DirectSoundCreate8 함수를 호출해 DirectSound 오브젝트를 생성 하는 경우, 디폴트의 디바이스를 지정할 수 있다. 상세한 것에 대하여는, 「DirectSound 오브젝트의 생성」을 참조할것.

특정의 종류의 디바이스를 찾고 있는 경우나, 유저에게 디바이스를 선택시키는 경우, 복수의 디바이스를 사용해 동작할 필요가 있는 경우는, 시스템상에서 이용 가능한 디바이스를 열거해야 한다.

열거는 3 개의 목적으로 사용된다.

  • 이용 가능한 하드웨어를 보고.
  • 각 디바이스에 GUID 를 공급.
  • 열거된 각 디바이스에 대해 일시적인 DirectSound 오브젝트를 생성 해, 디바이스의 능력을 체크할 수 있도록(듯이) 한다.

디바이스를 열거하려면 , DirectSound 가 디바이스를 찾아낼 때마다 호출하는 콜백 함수를 최초로 생성 해야 한다. 필요한 모든 처리를 이 함수내에서 실행해, 함수에 임의의 이름을 붙일 수가 있지만, 이 함수는 prototype인 DSEnumCallback 와 같은 형식에서 선언해야 한다. 이 콜백 함수는, 열거를 계속하는 경우는 TRUE, 그 외 (예를 들어 필요한 능력을 갖춘 디바이스를 찾아낸 후등)의 경우는 FALSE 를 돌려주지 않으면 안 된다.

다음의 콜백 함수는, 열거된 각 디바이스에 관한 정보를 combobox에 추가한다. 최초의 3 개의 파라미터의 값은 디바이스 드라이버에 의해 공급되고 있다. 4 번째의 파라미터는 DirectSoundEnumerate 함수로부터 인도해진다.

BOOL CALLBACK DSEnumProc(LPGUID lpGUID,
                         LPCTSTR lpszDesc,
                         LPCTSTR lpszDrvName,
                         LPVOID lpContext )
{
    HWND   hCombo = *(HWND *) lpContext;
    LPGUID lpTemp = NULL;

    if ( lpGUID ! = NULL )
    {
        if (( lpTemp = malloc( sizeof(GUID))) == NULL )
        return( TRUE );

        memcpy( lpTemp, lpGUID, sizeof(GUID));
    }

    ComboBox_AddString( hCombo, lpszDesc );
    ComboBox_SetItemData( hCombo,
                ComboBox_FindString( hCombo, 0, lpszDesc ),
                lpTemp );
    return( TRUE );
}

combobox를 포함한 다이얼로그를 초기화할 때에, 열거를 실시한다.

if FAILED(DirectSoundEnumerate((LPDSENUMCALLBACK) DSEnumProc,
        (VOID*) &hCombo))
{
    EndDialog( hDlg, TRUE );
    return( TRUE );
}

이 예에서는, combobox의 핸들의 주소는 DirectSoundEnumerate 에 보내져 다음에 콜백 함수에게 건네진다. 이 파라미터는, 콜백 함수내에서 액세스 하고 싶은 임의의 32 비트의 값으로 할 수가 있다.

주 열거된 최초의 디바이스는 항상 프라이머리 사운드 드라이버로 불려 콜백의 lpGUID 파라미터는 NULL 이다. 이 디바이스는, 유저가 컨트롤 패널로 설정한 우선하는 재생 디바이스를 나타낸다. 어플리케이션이 "프라이머리 사운드 드라이버" 를 일람에 추가해, 유저에게 디바이스의 선택사항을 제공하기 쉽게 하기 위해서, 이 디바이스는 별도로 열거된다. 프라이머리 디바이스는, 적절한 이름 및 GUID 와 함께 열거된다.


DirectSound 오브젝트의 생성

DirectSound 오브젝트를 생성 하는 가장 간단한 방법은,DirectSoundCreate8 함수를 사용하는 것이다. 이 함수의 최초의 파라미터는, 이 오브젝트에 관련지을 수 있는 디바이스의 GUID 를 지정한다. 이 GUID 는,사운드 디바이스의 열거로 취득할 수 있다. 또는, 다음의 몇개의 GUID 를 건네주어 디폴트의 디바이스를 지정한다.

DSDEVID_DefaultPlayback
디폴트의 시스템 오디오 디바이스. 디바이스의 GUID 파라미터로 NULL 포인터를 건네주는 것에 의해, 이 디바이스를 지정할 수도 있다. 디폴트의 디바이스는, "프라이머리 DirectSound 드라이버" 로서 열거된다.
DSDEVID_DefaultVoicePlayback
디폴트의 음성 통신 디바이스. 이것은, 보통, USB 마이크 첨부 헤드 세트등의 세칸다리데바이스이다.

디바이스 드라이버가 존재하지 않는 경우는,DirectSoundCreate8 의 호출은 실패한다.

사운드 디바이스가 존재하지 않는지, VXD 드라이버의 경우, 표준의 Win32 웨이브 폼 오디오 함수를 이용하는 어플리케이션이 사운드 디바이스를 제어하고 있는 경우는, 이 함수는 에러를 돌려준다. 어플리케이션은 이 호출이 실패했을 경우에 대비해, 사운드없이 어플리케이션을 속행하는지, 이미 사운드 디바이스를 사용하고 있는 어플리케이션을 닫도록(듯이) 유저에게 prompt를 표시하는지, 어느 쪽인가의 준비를 할 필요가 있다.

다음의 코드에서는, 디폴트 디바이스의 DirectSound 오브젝트를 생성 해,IDirectSound8 인터페이스를 취득하고 있다.

LPDIRECTSOUND8 lpds;
HRESULT hr = DirectSoundCreate8(NULL, &lpds, NULL));

주 DirectSoundCreate8 는 CoInitialize 를 호출하지 않는다. 어플리케이션이 이펙트 DMO 를 사용하는 경우, 어플리케이션은 DirectSound 오브젝트의 생성 방법으로 관계없이,CoInitialize 를 호출할 필요가 있다.

어플리케이션이 사운드를 캡춰 해 재생하는 경우,DirectSoundFullDuplexCreate8 함수를 사용해, DirectSound 와 DirectSoundCapture 의 양쪽 모두의 오브젝트, 및 재생 및 캡춰 버퍼를 생성 할 수 있다.

표준적인 COM 함수를 사용해, 다음과 같이 DirectSound 오브젝트를 생성 할 수도 있다.

  1. 어플리케이션의 기동시에 CoInitializeEx 를 호출해 COM 를 초기화한다.
    if FAILED(CoInitializeEx(NULL, 0))
    return FALSE;
  2. DirectSoundCreate8 함수는 아니고,CoCreateInstance 와 IDirectSound8::Initialize 의 각 메소드를 사용해 DirectSound 오브젝트를 생성 한다.
    LPDIRECTSOUND8 lpds;
HRESULT hr = CoCreateInstance(&CLSID_DirectSound8,
                              NULL,
                              CLSCTX_INPROC_SERVER,
                              &IID_IDirectSound8,
                              &lpds);

    CLSID_DirectSound8 은 DirectSound 의 드라이버 오브젝트 클래스의 클래스 식별자이며,IID_IDirectSound8 은 인터페이스 식별자이다. lpds 파라미터는 인터페이스 포인터를 받는다.

  3. IDirectSound8::Initialize 메소드를 호출해, 오브젝트를 디바이스에 관련짓는다. 이 메소드는,DirectSoundCreate8 와 같은 디바이스 GUID 파라미터를 취한다.
    if SUCCEEDED(hr)
    hr = lpds->Initialize(NULL);
  4. 어플리케이션을 닫기 전에, 다음과 같이 CoUninitialize 함수를 호출해 COM 라이브러리를 닫는다.
    CoUninitialize();


협조 레벨

Windows 는 멀티태스킹 환경이므로, 복수의 어플리케이션이 임의의 시점에서 같은 디바이스 드라이버를 사용해 동작하는 일이 있다. DirectX 는 협조 레벨을 사용해, 각 어플리케이션이 부적절한 방법 또는 부적절한 타이밍에 디바이스에 액세스 하지 않는 것을 보증한다. DirectSound 의 각 어플리케이션은, 디바이스에 대해서 인정되는 액세스 범위를 결정하는 1 개의 협조 레벨을 가진다.

DirectSound 오브젝트를 생성 한 다음에, 사운드를 재생하기 전에 IDirectSound8::SetCooperativeLevel 메소드를 사용해 디바이스의 협조 레벨을 설정해야 한다.

다음의 예에서는,IDirectSound8 인터페이스에 의해 나타내지는 DirectSound 디바이스의 lpDirectSound 에서의 협조 레벨을 설정해 있다. hwnd 파라미터는, 어플리케이션 윈도우에의 핸들이다.

HRESULT hr = lpDirectSound->SetCooperativeLevel(hwnd, DSSCL_PRIORITY);

DirectSound 에서는, DSSCL_NORMAL, DSSCL_PRIORITY, 및 DSSCL_WRITEPRIMARY 의 값으로 나타내지는 3 개의 사운드 디바이스의 협조 레벨을 정의하고 있다.

주 DirectX 8.0 이전의 버젼으로 이용 가능함 협조 레벨 DSSCL_EXCLUSIVE 는 폐지되었다. DirectX 어플리케이션으로 다른 어플리케이션을 뮤트 할 수 없게 되었다. 배타적 레벨을 요구하는 어플리케이션에는, 대신에 우선 레벨이 부여된다.

표준 협조 레벨

표준 협조 레벨에서는, 어플리케이션은,프라이머리 사운드 버퍼의 포맷의 설정, 프라이머리 버퍼에의 기입해, 디바이스의 온보드 메모리의 압축을 실시할 수 없다. 이 협조 레벨을 사용하는 모든 어플리케이션은, 22 kHz, 스테레오 사운드, 8 비트 샘플링의 프라이머리 버퍼 포맷을 사용하므로, 디바이스는 어플리케이션간에 가장 원활히 교체된다.

우선 협조 레벨

우선 협조 레벨로 DirectSound 디바이스를 사용하면(자), 어플리케이션은 하드웨어 믹싱등의 하드웨어 리소스에 대해서 최고의 권한을 확보해, 프라이머리 사운드 버퍼의 포맷의 설정, 디바이스의 온보드 메모리의 압축을 실시할 수 있다.

게임 어플리케이션은, 거의 모든 환경에서 우선 협조 레벨을 사용한다. 이 레벨은, 샘플링 레이트와 비트 깊이에 대한 어플리케이션 제어를 가능하게 하면서, 가장 강력하게 동작한다. 또, 우선 협조 레벨에서는, IP 테레포니등의 다른 어플리케이션으로부터의 오디오를 게임으로부터의 오디오와 함께 (들)물을 수도 있다.

기입 우선 협조 레벨

최상정도의 협조 레벨은 기입해 우선이다. 이 협조 레벨로 DirectSound 디바이스를 사용하면(자), 어플리케이션은 프라이머리 사운드 버퍼에 직접 액세스 할 수 있다. 이 모드에서는, 어플리케이션은 프라이머리 버퍼에 직접 기입을 실시하지 않으면 안 된다. 이 기입중은, 세칸다리밧파를 재생할 수 없다.

프라이머리 버퍼내의 오디오 샘플에 직접 기입의 액세스를 하려면 , 어플리케이션을 기입해 우선 레벨로 설정해야 한다. 어플리케이션이 이 레벨로 설정되어 있지 않은 경우,IDirectSoundBuffer8::Lock 메소드의 호출은 모두 실패한다.

기입 우선 협조 레벨로 설정된 어플리케이션이 foreground가 되면(자), 다른 어플리케이션의 모든 세칸다리밧파는 정지되어 「없어졌다」라고 마크 된다. 최초의 어플리케이션이 백그라운드로 옮겨지면(자), 그 프라이머리 버퍼는 「없어졌다」라고 마크 되어 어플리케이션이 재차 foreground로 옮길 때는 이 버퍼를 복원하지 않으면 안 된다. 상세한 것에 대하여는, 「버퍼 관리」를 참조할것.

DirectSound 드라이버가 유저의 시스템에 존재하고 있지 않는 경우는, 기입 우선 레벨의 설정은 할 수 없다. 이 상황에 해당할지 어떨지를 확인하려면 ,IDirectSound8::GetCaps 메소드를 호출해,DSCAPS 구조체의 DSCAPS_EMULDRIVER 플래그를 체크한다.

상세한 것에 대하여는, 「프라이머리 버퍼에의 기입해」를 참조할것.


디바이스의 능력

DirectSound 를 사용하면(자), 어플리케이션은 사운드 디바이스의 하드웨어 능력을 취득할 수 있다. DirectSound 는 이용 가능한 하드웨어 가속화를 자동적으로 이용하므로, 어플리케이션에서는, 보통 이 취득을 실시할 필요는 없다. 그러나 고성능의 어플리케이션은 이 정보를 이용해, 이용 가능한 하드웨어에 대해서 사운드의 요구 사항을 평가할 수 있다. 예를 들어, 하드웨어 믹싱이 이용 가능한 경우는, 이용 불가능한 경우에 비해, 어플리케이션이 보다 많은 사운드를 재생할 수 있을 것이다.

DirectSoundCreate8 함수를 호출해 DirectSound 오브젝트를 생성 한 후는,IDirectSound8::GetCaps 메소드를 사용해 사운드 디바이스의 능력을 취득할 수 있다.

다음의 예에서는,IDirectSound8 인터페이스 포인터 lpDirectSound 에 의해 나타내지는 디바이스의 능력을 취득하고 있다.

DSCAPS dscaps;

dscaps.dwSize = sizeof(DSCAPS);
HRESULT hr = lpDirectSound->GetCaps(&dscaps);

DSCAPS 구조체는, 사운드 디바이스의 능력과 리소스에 관한 정보를 받지만, 이 안에는 타입마다의 최대의 리소스와 현재 이용 가능한 리소스가 포함된다. 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 초기화해야 하는 점에 주의 해야 한다.

어플리케이션이 하드웨어 능력을 평가하는 경우는, 버퍼 할당을 실시할 때마다 IDirectSound8::GetCaps 메소드를 호출해, 다음의 버퍼를 생성 하는데 충분한 리소스가 있을지 어떨지를 확인해야 한다.


스피커의 구성

DirectSound 는, 스피커가 청취자에 대한 상대적인 위치를 잡는 스피커 구성을 사용해, 유저의 사운드 시스템에 맞추어 3D 이펙트를 최적화한다.

Windows® 98 으로 Windows® 2000 에서는, 유저는 컨트롤 패널을 사용해 스피커 구성을 설정할 수 있다. 어플리케이션은 IDirectSound8::GetSpeakerConfig 를 사용해 이 값을 취득해,IDirectSound8::SetSpeakerConfig 를 호출해 그 값을 변경할 수 있다.

SetSpeakerConfig 가 곧바로 유효하게 된다고 하는 보증은 없고, 단지 레지스트리 설정을 변경한 것만으로, 컴퓨터를 재기동하지 않으면 유효하게 안 되는 경우도 있다. 이 메소드를 사용하는 대신에, 컨트롤 패널을 사용해 스피커 구성을 변경하도록(듯이) 유저에게 어드바이스 할 필요가 있다.

Windows 95 에서는,GetSpeakerConfig 는 단순하게, 디폴트의 값 또는 SetSpeakerConfig 로 설정한 직전의 값을 돌려준다.


하드웨어 메모리의 압축

어플리케이션은 최소한의 협조 레벨을 갖추고 있는 것을 전제로서IDirectSound8::Compact 메소드를 사용해, 임의의 온보드 사운드 메모리를 이동해 연속 블록을 형성해, 프리 메모리의 최대 부분을 사용 가능하게 할 수 있다.


DirectSound 버퍼

DirectSound 버퍼 오브젝트는, 웨이브 데이터의 입력으로부터 출력까지의 전달을 제어한다. 입력에는, 신디사이저, 다른 버퍼, 파일, 또는 리소스가 있다. 대부분의 버퍼의 경우, 출력처는 프라이머리 버퍼로 불리는 믹싱 엔진이다. 데이터는, 프라이머리 버퍼로부터,PCM 샘플을 사운드 웨이브로 변환하는 하드웨어에 보내진다.

여기에서는, 이전의 버젼의 DirectSound 용으로 생성 된 어플리케이션, 즉 버퍼의 하위 레벨의 제어를 필요로 하는 어플리케이션에 대해 설명한다. 어플리케이션이 DirectMusic 퍼포먼스 오브젝트를 사용해 사운드를 재생하는 경우, 버퍼의 생성 및 관리는 자동적으로 행해진다. 다만, 3D 이펙트나 DMO 의 이펙트의 파라미터에의 액세스를 취득하기 위해서, 버퍼 오브젝트를 취득할 수 있다. 상세한 것에 대하여는, 「이펙트의 사용법」 및 「3D 사운드」를 참조할것.

DirectSound 버퍼의 사용법에 대해서는, 이하의 주제로 설명한다.

  • 버퍼의 기본
  • 세칸다리밧파의 생성
  • 버퍼의 복제
  • 버퍼 컨트롤 옵션
  • 버퍼의 3D 알고리즘
  • 스태틱 버퍼의 기입과 재생
  • 스트림 버퍼의 사용법
  • 재생의 컨트롤
  • 재생 커서와 기입해 커서
  • 재생 버퍼의 통지
  • 사운드의 믹싱
  • 버퍼 관리

캡춰 버퍼에 대해서는, 「웨이브의 캡춰」를 참조할것.


버퍼의 기본

DirectSound 를 초기화 하면, DirectSound 는 사운드의 믹싱과 출력 디바이스에의 송신을 하기 위해서,프라이머리 사운드 버퍼의 생성과 관리를 자동적으로 실시한다.

어플리케이션은, 개개의 사운드의 보존과 재생을 하기 위해서, 적어도 1 개의세칸다리사운드밧파를 생성 해야 한다. 이 방법의 상세한 것에 대하여는, 「세칸다리밧파의 생성」을 참조할것.

세칸다리밧파는, 어플리케이션이 동작하고 있는 동안 항상 지속하는 일도, 불필요하게 되었을 때에 삭제할 수도 있다. 세칸다리밧파에는, 게임중의 효과음등 반복해 재생되는 1 개의 사운드를 저장 하거나 적당 새로운 데이터를 기록할 수도 있다. 어플리케이션은, 세칸다리밧파에 기억되고 있는 사운드를 1 개의 이벤트, 또는 연속 재생되는 루프 사운드로서 재생할 수 있다. 사운드 파일의 데이터가 매우 크고, 메모리에 기억해 두는 것이 실용적이지 않는 경우, 데이터를 스트림 하기 위해서 세칸다리밧파를 이용할 수 있다.

버퍼는, 하드웨어 또는 소프트웨어의 어느 쪽인가에 배치할 수 있다. 하드웨어 버퍼는 사운드 카드의 프로세서에 의해 믹싱 되어 소프트웨어 버퍼는 CPU 에 의해 믹싱 된다. 소프트웨어 버퍼의 데이터는 항상 시스템 메모리에 놓여진다. 하드웨어 버퍼의 데이터는 시스템 메모리에 두는 일도, 어플리케이션이 요구해, 리소스가 사용 가능한 경우는 온보드 메모리에 둘 수도 있다. 상세한 것에 대하여는, 「다이나믹 음성 관리」 및 「ISA 및 PCI 카드에서의 하드웨어 가속화」를 참조할것.

다른 세칸다리밧파의 사운드는, 이것들을 동시에 재생하는 것만으로 믹싱 할 수 있다. 처리 능력의 한계내이면, 임의의 수의 세칸다리밧파를 동시에 재생할 수 있다.

보통, 개발자는 프라이머리 버퍼를 의식할 필요는 전혀 없다. DirectSound 가 내부에서 관리를 실시한다. 그러나, 어플리케이션이 고유의 믹싱을 실시하는 경우는, 개발자가 프라이머리 버퍼에 직접 기입을 실시할 필요가 있다. 이것을 실시하면, 세칸다리밧파를 동시에는 이용할 수 없다. 상세한 것에 대하여는, 「프라이머리 버퍼에의 기입해」를 참조할것.


세칸다리밧파의 생성

사운드 버퍼를 생성 하려면 ,IDirectSound8::CreateSoundBuffer 메소드를 호출한다. 이 메소드는,IDirectSoundBuffer8 인터페이스에의 포인터를 돌려준다. 어플리케이션은 이 인터페이스를 사용해, 버퍼를 조작 및 연주한다.

다음의 예는, 세칸다리사운드밧파를 생성 하는 방법을 나타내고 있다.

BOOL AppCreateBasicBuffer(
        LPDIRECTSOUND8 lpDirectSound,
        LPDIRECTSOUNDBUFFER *lplpDsb)
{
    PCMWAVEFORMAT pcmwf;
    DSBUFFERDESC dsbdesc;
    HRESULT hr;

    // 웨이브 포맷 구조체를 설정한다.
    memset(&pcmwf, 0, sizeof(PCMWAVEFORMAT));
    pcmwf.wf.wFormatTag = WAVE_FORMAT_PCM;
    pcmwf.wf.nChannels = 2;
    pcmwf.wf.nSamplesPerSec = 22050;
    pcmwf.wf.nBlockAlign = 4;
    pcmwf.wf.nAvgBytesPerSec =
        pcmwf.wf.nSamplesPerSec * pcmwf.wf.nBlockAlign;
    pcmwf.wBitsPerSample = 16;

    // DSBUFFERDESC 구조체를 설정한다.

    memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags =
        DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY;

    dsbdesc.dwBufferBytes = 3 * pcmwf.wf.nAvgBytesPerSec;
    dsbdesc.lpwfxFormat = (LPWAVEFORMATEX) &pcmwf;

    // 버퍼를 생성 한다.

    hr = lpDirectSound->CreateSoundBuffer(&dsbdesc, lplpDsb, NULL);
    if SUCCEEDED(hr)
    {
        // IDirectSoundBuffer 인터페이스는 *lplpDsb 에 있다.
        // QueryInterface 를 사용해 IDirectSoundBuffer8 를 취득한다.
        return TRUE;
    }
    else
    {
        // 실패했을 경우.
        *lplpDsb = NULL;
        return FALSE;
    }
}

이 예에서는, 3 초간의 스트리밍 데이터를 보관 유지하는데 충분한 크기의스트림 버퍼를 생성 한다. 스트림 버퍼 이외의 버퍼는, 사운드 전체를 보관 유지하는데 충분한 크기로 생성 해야 한다.

DirectSound 는 하드웨어 리소스를 최초의 버퍼에 할당해 그 이점을 살린다. 하드웨어 버퍼는 사운드 카드 프로세서로 믹싱 되므로, 어플리케이션 성능에 거의 영향을 미치지 않는다.

버퍼의 위치를 DirectSound 로 결정하게 한 하지않고서 스스로 지정하고 싶은 경우는,DSBUFFERDESC 구조체에 DSBCAPS_LOCHARDWARE 또는 DSBCAPS_LOCSOFTWARE 의 어느 쪽인가의 플래그를 설정한다. DSBCAPS_LOCHARDWARE 플래그를 설정해, 하드웨어 리소스가 부족한 경우, 버퍼의 생성 요구는 실패한다.

DirectSound 의 음성 관리 기능을 이용하려면 , 버퍼의 생성시에 DSBCAPS_LOCDEFER 플래그를 지정한다. 이 플래그는, 버퍼에 대한 리소스의 할당을, 버퍼가 재생될 때까지 지연 한다. 상세한 것에 대하여는, 「다이나믹 음성 관리」를 참조할것.

기존의 버퍼의 위치를 확인하려면 ,IDirectSoundBuffer8::GetCaps 메소드를 사용해,DSBCAPS 구조체의 dwFlags 멤버를 체크해, DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 어느 쪽의 플래그가 되어 있을까를 조사한다. 어느 쪽인지가 반드시 지정되고 있다.

DSBCAPS_STATIC 플래그를 설정 하면, 가능한 경우는 버퍼를 온보드의 하드웨어 메모리에 생성 해야 한다라고 하는 것이 DirectSound 에 통지된다. 하드웨어 버퍼를 이용할 수 없는 경우에서도,IDirectSound::CreateSoundBuffer 메소드는 실패하지 않는다. 이 플래그는, 버퍼용으로 시스템 메모리를 사용하는 최근의 사운드 카드가 많게는 영향을 주지 않는다. 하드웨어 스태틱 버퍼는, 반복 재생되는 짧은 사운드에 대해서만 사용해야 하는 것이다. 상세한 것에 대하여는, 「ISA 및 PCI 카드에서의 음성 관리」를 참조할것.

버퍼 오브젝트는, 이것을 생성 한 DirectSound 오브젝트가 소유한다. DirectSound 오브젝트가 해방되면(자), 이 오브젝트가 생성 한 모든 버퍼도 해방되어 참조할 수 없게 된다.


버퍼의 복제

IDirectSound8::DuplicateSoundBuffer 메소드를 사용해, 같은 데이터를 포함한 복수의 세칸다리밧파를 생성 할 수 있다. 프라이머리 사운드 버퍼는 복제할 수 없다. 비록 호출이 성공했다고 해도, 실제로 중복 버퍼가 원의 버퍼와 메모리를 공유 하면은 한정되지 않기 때문에, 이러한 변경이 모든 중복 버퍼에 반영될 것이다라고 하는 예측의 아래에서 버퍼를 변경해서는 안된다.


버퍼 컨트롤 옵션

사운드 버퍼를 생성 할 경우에, 버퍼가 필요로 하는 컨트롤 옵션을 지정해야 한다. 이것에는 DSBUFFERDESC 구조체의 dwFlags 멤버를 사용한다. 이 구조체는, 1 개(살) 또는 복수의 DSBCAPS_CTRL* 플래그를 보관 유지할 수 있다.

다음의 컨트롤을 이용할 수 있다.

  • 3D 프로퍼티.
  • 이펙트.
  • 주파수.
  • 빵.
  • 볼륨.
  • 위치의 통지.

모든 사운드 카드로부터 최고의 성능을 얻으려면 , 어플리케이션이 사용하는 옵션만을 지정해야 한다.

DirectSound 는 컨트롤 옵션을 사용해, 사운드 버퍼에 하드웨어 리소스를 할당할 수 있을지 어떨지를 결정한다. 예를 들어, 어느 디바이스가 하드웨어 버퍼를 지원 하고 있어, 그러한 버퍼에 빵 컨트롤을 제공하고 있지 않다고 한다. 이 경우, DirectSound 는 DSBCAPS_CTRLPAN 플래그가 지정되어 있지 않은 경우에 한해서, 하드웨어 가속화를 사용한다.

컨트롤은, 특정의 편성으로 사용할 수 없는 것에 주의 해야 한다. 예를 들어, 빵과 3D 를 동시에 사용할 수 없다.

버퍼가 갖추지 않은 컨트롤을 사용하려고 하면, 메소드는 실패한다. 예를 들어,IDirectSoundBuffer8::SetVolume 메소드를 사용해 볼륨을 변경하려고 할 때, 그 버퍼의 생성시에 DSBCAPS_CTRLVOLUME 플래그가 지정되고 있었을 경우에 한해서 메소드는 성공한다. 이 플래그가 지정되어 있지 않았던 경우는 메소드는 실패에 끝나,DSERR_CONTROLUNAVAIL 에러 코드가 돌려주어진다.

「재생의 컨트롤」도 참조할것.


버퍼의 3D 알고리즘

DSBCAPS_CTRL3D 컨트롤 플래그를 지정해 세칸다리후밧파를 생성 할 경우에, 버퍼가 소프트웨어로 처리되는 경우는, 사운드의 공간적인 확대를 내기 위해서(때문에) 사용하는 알고리즘도 지정할 수 있다. 디폴트에서는,HRTF 처리는 실행되지 않고, 청취자로부터 상대적인 사운드의 위치는, 빵 및 볼륨에 의해서만 지정된다. 버퍼에 2 개의 레벨의 HRTF 를 요구할 수 있다.

상세한 것에 대하여는, 「DSBUFFERDESC 」를 참조할것.


스태틱 버퍼의 기입과 재생

독립한 사운드 전체를 보관 유지하는 세칸다리밧파를, 스태틱 버퍼라고 한다. 같은 버퍼를 다른 사운드로 재이용할 수도 있지만, 보통은 데이터를 한 번만 스태틱 버퍼에 기술한다.

스태틱 버퍼는스트림 버퍼와 같게 생성 및 관리된다. 차이는 버퍼의 사용법 뿐이다. 스태틱 버퍼는 한 번 기입해져 연주되지만, 스트림 버퍼는 연주중에 정기적으로 데이터가 갱신된다.

주 스태틱 버퍼는 반드시, DSBCAPS_STATIC 플래그를 버퍼 기술로 설정하는 것으로 생성 되는 것은 아니다. 이 플래그는, 현재가 많은 하드웨어에서는 사용할 수 없는, 사운드 카드상에서의 메모리 할당을 요구한다. 스태틱 버퍼는 시스템 메모리내에 놓여져 DSBCAPS_LOCHARDWARE 또는 DSBCAPS_LOCSOFTWARE 의 어느 쪽인가의 플래그로 생성 된다. 상세한 것에 대하여는, 「ISA 및 PCI 카드에서의 음성 관리」를 참조할것.

스태틱 버퍼에의 데이터의 로드는, 3 개의 스텝에서 행해진다.

  1. IDirectSoundBuffer8::Lock 를 사용해 버퍼 전체를 잠근다. 기술을 시작하는 버퍼내의 오프셋(offset)를 지정해 (보통은 0), 그 위치의 메모리 주소를 돌려준다.
  2. 표준의 메모리 카피 루틴을 사용해, 돌려주어진 주소에 오디오 데이터를 기입한다.
  3. IDirectSoundBuffer8::Unlock 를 사용해, 버퍼를 언락 한다.

이러한 스텝을 다음의 예로 가리킨다. lpdsbStatic 는 IDirectSoundBuffer8 인터페이스 포인터이며,pbData 는 데이터 소스의 주소이다.

LPVOID lpvWrite;
DWORD  dwLength;

if (DS_OK == lpdsbStatic->Lock(
        0,              // 락을 시작 하는 오프셋(offset).
        0,              // 락의 사이즈. 플래그를 위해서(때문에) 무시된다.
        &lpvWrite,      // 락의 최초의 부분의 주소를 취득한다.
        &dwLength,      // 락의 최초의 부분의 사이즈를 취득한다.
        NULL,           // rack-around의 주소는 필요없다.
        NULL,           // rack-around의 사이즈는 필요없다.
        DSBLOCK_ENTIREBUFFER))  // 플래그.
{
    memcpy(lpvWrite, pbData, dwLength);
    lpdsbStatic->Unlock(
        lpvWrite,       // 락 시작의 주소.
        dwLength,       // 락의 사이즈.
        NULL,           // rack-around 위치는 없다.
        0);             // rack-around 사이즈는 없다.
}

버퍼를 재생하려면 , 다음의 예의 같게 IDirectSoundBuffer8::Play 를 호출한다.

lpdsbStatic->SetCurrentPosition(0);
HRESULT hr = lpdsbStatic->Play(
        0,    // 미사용.
        0,    // 음성 관리의 우선도.
        0);   // 플래그.

이 예에서는 DSBPLAY_LOOPING 플래그를 설정하고 있지 않았기 때문에, 버퍼는 마지막에 도달 하면 자동적으로 정지한다. 또,IDirectSoundBuffer8::Stop 를 사용하면(자) 버퍼를 빨리 정지할 수 있다. 버퍼를 빨리 정지하는 경우는, 재생 커서 위치가 그 자리소에 머무른다. 따라서, 예에 나타나고 있는 IDirectSoundBuffer8::SetCurrentPosition 에 대한 호출은, 버퍼가 처음부터 시작 하는 것을 보증하는 것이다.


스트림 버퍼의 사용법

스트림 버퍼는, 한 번에 버퍼에 들어가지 않는 긴 사운드를 재생한다. 버퍼가 재생되는 것에 따라, 낡은 데이터는 정기적으로 새로운 데이터에 옮겨진다.

스트림 버퍼를 재생하려면 ,dwFlags 파라미터에 DSBPLAY_LOOPING 를 지정해 IDirectSoundBuffer8::Play 메소드를 호출한다.

재생을 정지하려면 ,IDirectSoundBuffer8::Stop 메소드를 호출한다. 이 메소드는 버퍼를 즉시에 정지하므로, 모든 데이터가 재생된 것을 확인할 필요가 있다. 이것을 실시하려면 , 재생 위치를 폴링 하는지, 통지 위치를 설정한다.

버퍼에 스트리밍 하려면 , 다음의 스텝이 필요하다.

  1. IDirectSoundBuffer8::Lock 를 사용해, 버퍼의 일부를 잠근다. 이 메소드는, 데이터를 기술할 수 있는 1 개(살), 또는 2 개의 주소를 돌려준다.
  2. 이 1 개(살) 또는 2 개의 주소에 대해서, 표준의 메모리 카피 루틴을 사용해 오디오 데이터를 기입한다.
  3. IDirectSoundBuffer8::Unlock 를 사용해, 버퍼를 언락 한다.

IDirectSoundBuffer8::Lock 가 2 개의 주소를 돌려주는 일이 있는 것은, 시작 위치에 관계없이, 버퍼의 사이즈까지의 바이트수를 잠글 수 있기 때문이다. 필요에 따라서, 락 되는 부분은 버퍼의 선두에 랩 된다. 랩 되는 경우는, 2 개(살)의 개별의 메모리 카피를 실행해야 한다.

예를 들어 40,000 바이트의 버퍼로, 오프셋(offset) 20,000 으로 시작되는 30,000 바이트를 잠그는 경우,Lock 를 호출하면 4 개의 값이 돌려주어진다.

  • 오프셋(offset) 20,000 의 주소.
  • 버퍼의 그 위치로부터 끝까지의 락 된 바이트수 (20,000). 최초의 주소에 이 바이트수만큼 기술한다.
  • 오프셋(offset) 0 의 주소.
  • 그 위치로부터 락 된 바이트수 (10,000). 2 번째의 주소에 이 바이트수만큼 기술한다.

rack-around가 필요없는 경우는, 마지막 2 개의 값이 각각 NULL 와 0 이 된다.

버퍼 전체를 잠글 수도 있지만, 재생중에 실시해서는 안된다. 매회 버퍼의 일부만을 리프레쉬 하는 것. 예를 들어, 재생 커서가 2/4 에 이르자 마자, 버퍼의 최초의 것 1/4 을 잠그어 기입하도록(듯이) 한다. 버퍼의 재생 커서와 기입해 커서의 사이에 있는 부분에는 기입해서는 안 된다. 상세한 것에 대하여는, 「재생 커서와 기입해 커서」를 참조할것.

다음의 함수는,dwOffset 에게 건네진 위치로부터, 데이터를 사운드 버퍼에 기입한다.

BOOL AppWriteDataToBuffer(
    LPDIRECTSOUNDBUFFER8 lpDsb,  // 버퍼.
    DWORD dwOffset,              // 독자적인 기입 커서.
    LPBYTE lpbSoundData,         // 데이터의 시작.
    DWORD dwSoundBytes)          // 카피하는 블록의 사이즈.
{
    LPVOID  lpvPtr1;
    DWORD   dwBytes1;
    LPVOID  lpvPtr2;
    DWORD   dwBytes2;
    HRESULT hr;

    // 기입 블록의 메모리 주소를 취득한다. 블록이 rack-around 되는 경우,
    // 이것은 2 개의 부분이 된다.

    hr = lpDsb->Lock(dwOffset, dwSoundBytes, &lpvPtr1,
        &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    // 버퍼가 없어졌을 경우, 복원해 락을 재시행한다.

    if (DSERR_BUFFERLOST == hr)

    {
        lpDsb->Restore();
        hr = lpDsb->Lock(dwOffset, dwSoundBytes,
            &lpvPtr1, &dwBytes1, &lpvPtr2, &dwBytes2, 0);
    }
    if SUCCEEDED(hr)
    {
        // 포인터에 기입한다.

        CopyMemory(lpvPtr1, lpbSoundData, dwBytes1);
        if (NULL ! = lpvPtr2)
        {
            CopyMemory(lpvPtr2, lpbSoundData+dwBytes1, dwBytes2);
        }

        // 데이터를 해방해 DirectSound 에 되돌린다.

        hr = lpDsb->Unlock(lpvPtr1, dwBytes1, lpvPtr2,
            dwBytes2);
        if SUCCEEDED(hr)
        {
            // 성공.
            return TRUE;
        }
    }

    // 락, 언락, 또는 복원이 실패했다.

    return FALSE;
}

상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 재생 커서와 기입해 커서
  • 재생 버퍼의 통지
  • 웨이브 파일의 read


재생의 컨트롤

IDirectSoundBuffer8::GetVolume 과 IDirectSoundBuffer8::SetVolume 의 각 메소드를 사용하면(자), 재생중의 버퍼의 볼륨을 취득 및 설정할 수 있다. 프라이머리 사운드 버퍼의 볼륨을 설정 하면, 사운드 카드의 웨이브 폼 오디오의 볼륨이 변경된다.

IDirectSoundBuffer8::GetFrequency 와 IDirectSoundBuffer8::SetFrequency 의 각 메소드를 사용하면(자), 샘플링 오디오의 재생 주파수를 취득 및 설정할 수 있다. 프라이머리 버퍼의 주파수는 변경할 수 없다.

빵을 취득 및 설정하려면 ,IDirectSoundBuffer8::GetPan 과 IDirectSoundBuffer8::SetPan 의 각 메소드를 호출한다.

이러한 컨트롤의 어느쪽이든을 사용하려면 , 버퍼를 생성 할 때에 적절한 플래그를 설정해야 한다. 「버퍼 컨트롤 옵션」을 참조할것.


재생 커서와 기입해 커서

DirectSound 는 버퍼에의 포인터를 2 개 보관 유지하고 있다. 재생 커서와 기입해 커서이다. 이러한 위치는 버퍼의 바이트 오프셋(offset)이며, 메모리의 절대 주소는 아니다.

IDirectSoundBuffer8::Play 메소드는, 항상 버퍼의 재생 커서의 위치로부터 재생을 시작 한다. 버퍼를 생성 한 시점에서, 커서 위치는 0 으로 설정된다. 사운드가 재생되는 것에 따라, 커서 위치는 이동해, 다음에 출력되는 데이터 바이트를 나타낸다. 버퍼가 정지했을 때는, 커서는 다음의 데이터 바이트에 머무른다.

버퍼의 기입 커서보다 후의 장소에는, 데이터를 안전하게 기입할 수 있다. 경향 플레이 포지션과 경향 라이트 포지션의 사이에 있는 블록은, 이미 재생이 확정되어 있어, 안전하게 변경할 수 없다.

버퍼를 시계의 문자판으로 나타내, 시계회전의 방향으로 데이터를 기입한다고 생각한다. 재생 위치와 기입해 위치는, 이 문자판상에서 같은 속도로 회전하는 2 개의 바늘에 비유되어 기입 위치는, 항상 재생 위치의 조금 전방에 있다. 재생 위치가 1 을 나타내, 기입 위치가 2 를 나타내고 있는 경우는, 데이터를 기입해도 안전한 것은 2 의 뒤 뿐이다. 1 으로 2 의 사이의 데이터는 DirectSound 가 이미 재생 큐에 넣고 있을 가능성도 있으므로, 변경해서는 안된다.

기입 위치는, 버퍼에 기입해진 데이터는 아니고 재생 위치에 맞추어 이동한다. 데이터를 스트리밍 하는 경우, 다음에 기입을 실시하는 데이터 블록의 위치를 나타내기 위해서(때문에), 개발자는 독자적인 포인터를 유지할 책임을 진다.

어플리케이션은,IDirectSoundBuffer8::GetCurrentPosition 메소드를 호출하는 것으로, 재생 커서와 기입해 커서를 취득할 수 있다. IDirectSoundBuffer8::SetCurrentPosition 메소드에 의해, 재생 커서를 이동할 수 있다. 어플리케이션은, 기입 커서의 위치를 제어하지 않는다.

재생 커서를 가능한 한 정확하게 보고하려면 , 세칸다리밧파를 생성 할 때에 DSBCAPS_GETCURRENTPOSITION2 플래그를 지정해야 한다. 상세한 것에 대하여는, 「DSBUFFERDESC 」를 참조할것.


재생 버퍼의 통지

오디오를 스트리밍 하는 경우, 재생 커서가 버퍼내가 있는 포인트에 도달했을 때나, 재생이 정지했을 때에, 어플리케이션에의 통지를 발생시키고 싶은 것이 있다. IDirectSoundNotify8::SetNotificationPositions 메소드를 사용하면(자), 이벤트의 시그널을 송신하는 포인트를 버퍼내에 몇개에서도 설정할 수 있다. 다만, 버퍼의 재생중은 이벤트 포인트의 설정을 실시할 수 없다.

최초로 IDirectSoundNotify8 인터페이스에의 포인터를 취득해야 한다. 이 취득은, 버퍼 오브젝트의 QueryInterface 메소드를 사용해 실시한다. 다음에 C++ 에 의한 예를 나타낸다. lpDsbSecondary 는 IDirectSoundBuffer8 인터페이스 포인터이다.

LPDIRECTSOUNDNOTIFY8 lpDsNotify;

HRESULT hr = lpDsbSecondary->QueryInterface(IID_IDirectSoundNotify8,
                                            (LPVOID *) &lpDsNotify);
if SUCCEEDED(hr)
{
    // 속행해 lpDsNotify->SetNotificationPositions 를 사용한다.
}

IDirectSoundNotify8 인터페이스는, 포인터를 취득한 버퍼 오브젝트에 관련지을 수 있고 있다. 인터페이스의 메소드는 자동적으로 이 버퍼에 적용된다.

다음에, Win32 의 CreateEvent 함수를 사용해, 이벤트 오브젝트를 생성 한다. 이 이벤트의 핸들을 DSBPOSITIONNOTIFY 구조체의 hEventNotify 멤버에 기입한다. 이 구조체의 dwOffset 멤버로, 버퍼내에서 이벤트의 시그널을 송신하고 싶은 위치의 오프셋(offset)를 지정한다. 다음에 이 구조체의 주소를, 또는 복수의 통지 위치를 설정하고 싶은 경우는 구조체의 배열을,IDirectSoundNotify8::SetNotificationPositions 메소드에 건네준다.

다음의 예는, 1 개의 통지 위치를 설정한다. 루프 하지 않는 조건으로 버퍼의 종료 위치에 도달했는지, 어플리케이션이 IDirectSoundBuffer8::Stop 메소드를 호출했는지, 어느 쪽인가의 이유로써 재생이 정지했을 때에, 이벤트의 시그널이 송신된다.

DSBPOSITIONNOTIFY PositionNotify;

PositionNotify.Offset = DSBPN_OFFSETSTOP;
PositionNotify.hEventNotify = hMyEvent;
// hMyEvent 는 CreateEvent()에 의해 돌려주어지는 핸들이다.

lpDsNotify->SetNotificationPositions(1, &PositionNotify);

음성 관리를 이용하고 있는 경우는, 통지 위치에 도달하기 전에 버퍼를 종료할 수 있다. DSBPOSITIONNOTIFY 의 「주의」를 참조할것.


사운드의 믹싱

DirectSound 로 복수의 스트림을 믹싱 하는 것은 간단하다. 단순하게세칸다리사운드밧파를 생성 해, 각 사운드에 대한 IDirectSoundBuffer8 인터페이스를 취득하는 것만으로 있다. 다음에 그러한 버퍼를 동시에 재생한다. DirectSound 는프라이머리 사운드 버퍼에서의 믹싱을 처리해, 그 결과를 재생한다.

어플리케이션내의 모든 사운드가 같은 웨이브 포맷을 사용해, 하드웨어 출력 포맷이 그러한 사운드의 포맷과 일치하고 있는 경우, DirectSound 믹서는 최고의 품질의 사운드를 가져온다. 이 경우, 믹서는 포맷 변환을 할 필요가 없다.

하드웨어 출력 포맷을 변경하려면 , 프라이머리 사운드 버퍼 오브젝트를 생성 해,IDirectSoundBuffer8::SetFormat 메소드를 호출한다. 이 프라이머리 버퍼 오브젝트는 컨트롤의 목적에게만 사용할 수 있다. 이 버퍼의 생성은, 「프라이머리 버퍼에의 기입해」로 설명한 프라이머리 버퍼에의 기입해 액세스의 취득과 같은 것을 의미하지 않고, 협조 레벨을 DSSCL_WRITEPRIMARY 로 설정할 필요도 없다. 그러나,SetFormat 메소드를 호출하기 위해서(때문에), DSSCL_PRIORITY 또는 그 이상의 협조 레벨을 설정할 필요가 있다. 어플리케이션이 입력초점을 취득할 때마다, DirectSound 는 하드웨어 포맷을, 전회의 호출로 지정된 포맷에 복원한다.

세칸다리밧파를 생성 하기 전에, 프라이머리 버퍼의 포맷을 설정해야 한다.

주 WDM 드라이버를 사용하는 경우는, 프라이머리 버퍼의 포맷을 설정해도 효과가 없다. 포맷은 커넬 믹서에 의해 결정된다. 상세한 것에 대하여는, 「DirectSound 드라이버 모델」을 참조할것.


버퍼 관리

IDirectSoundBuffer8::GetCaps 메소드는, DirectSoundBuffer 오브젝트의 능력을 취득한다.

어플리케이션은 IDirectSoundBuffer8::GetStatus 메소드를 사용해, 버퍼가 재생중이나 정지하고 있는지를 확인할 수 있다.

IDirectSoundBuffer8::GetFormat 메소드를 사용하면(자), 버퍼내의 사운드 데이터의 포맷 정보를 취득할 수 있다. 또,IDirectSoundBuffer8::SetFormat 를 사용해, 프라이머리 버퍼내의 사운드 데이터의 포맷을 설정할 수 있다. 상세한 것에 대하여는, 「사운드의 믹싱」을 참조할것.

주 SetFormat 메소드를 세칸다리밧파에 대해 호출할 수 없다. 세칸다리밧파가 생성 된 후, 그 포맷이 고정된다. 다른 포맷을 사용하는 세칸다리밧파가 필요한 경우는, 그 포맷을 지정해 새로운 사운드 버퍼를 생성 해야 한다.

사운드 버퍼용의 메모리는 특정의 상황으로 없어지는 일이 있다. 예를 들어, 버퍼가 사운드 카드의 메모리에 놓여져 있어, 다른 어플리케이션이 하드웨어 리소스의 제어를 취득했을 경우이다. 기입 우선의 협조 레벨로 동작하는 어플리케이션이 foreground로 이동했을 경우도, 메모리가 없어지는 일이 있다. 이 경우, 다른 모든 사운드 버퍼는 없어지므로, foreground로 이동한 어플리케이션은 프라이머리 버퍼에 직접 기입할 수 있다.

없어진 버퍼에 대해서 IDirectSoundBuffer8::Lock ,IDirectSoundBuffer8::Play 메소드의 어느쪽이든을 호출하면,DSERR_BUFFERLOST 에러 코드가 돌려주어진다. 버퍼를 잃게 한 어플리케이션의 협조 레벨이 기입해 우선으로부터 내리거나 그 어플리케이션이 백그라운드로 이동했을 경우, 다른 어플리케이션은 IDirectSoundBuffer8::Restore 메소드를 호출해 버퍼 메모리의 재배치를 시도할 수가 있다. 성공했을 경우, 이 메소드는 버퍼 메모리와 볼륨이나 빵의 설정등 다른 모든 설정을 복원한다. 그러나, 복원된 버퍼는 유효한 사운드 데이터를 보관 유지하고 있지 않다. 따라서, 어플리케이션은 복원된 버퍼에 데이터를 한번 더 기입해야 하는 것이다.


웨이브 데이터의 사용법

DirectSound 버퍼는, 고정 샘플링 레이트의 사운드의 디지털 샘플로 구성되는 웨이브 폼 오디오 데이터만 재생한다. 아날로그 시그널을 숫자의 순서로 표현하는 것을, 펄스 코드 변조 (PCM)라고 부른다.

웨이브 데이터는, 보통, RIFF (Resource Interchange File Format)의 파일 또는 리소스에 보존된다. 이 데이터에는, 샘플링 레이트나 출력 채널수등의 파라미터를 포함한, 웨이브 포맷의 기술이 포함된다.

사운드의 특정의 포맷은,WAVEFORMATEX 또는 WAVEFORMATEXTENSIBLE 구조체를 사용해 기술할 수 있다.

이 구조체의 wFormatTag 멤버는, Microsoft 가 할당한 일의의 식별자를 보관 유지한다. DirectSound 로 유효한 태그는, 다음의 태그 뿐이다.

  • WAVE_FORMAT_PCM. 이 태그는, 펄스 코드 변조 (PCM ), 비압축 포맷을 나타낸다.
  • WAVE_FORMAT_EXTENSIBLE. 멀티 채널 오디오 포맷으로, WDM 드라이버에서만 유효. 상세한 것에 대하여는, 「멀티 채널 웨이브 포맷」을 참조할것.

DirectSound 는, 압축 웨이브 포맷을 지원 하고 있지 않다. 어플리케이션은 사운드 버퍼에 데이터를 기입하기 전에, Platform SDK 내의 Win32 API 로 제공되고 있는 오디오 압축 매니저 (ACM) 함수를 사용해, 압축된 오디오 데이터를 PCM 포맷에 변환해야 한다. 이 대신에, DirectMusic 퍼포먼스로 재생하기 위해서 압축된 웨이브를 로드했을 때에, 자동적으로 ACM 를 이용하는 DirectMusic 로더를 사용할 수도 있다.

웨이브의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 멀티 채널 웨이브 포맷
  • 웨이브 파일의 read
  • 리소스로부터의 웨이브 데이터의 read


멀티 채널 웨이브 포맷

WDM 드라이버에서는, DirectSound 버퍼는, 5.1 등의 스피커 구성용으로 복수의 출력 채널을 가지는 웨이브 포맷을 지원 하고 있다. 5.1 스피커 구성에서는, 전방왼쪽, 전방 중앙, 전방 오른쪽, 후방왼쪽, 후방 오른쪽의 스피커와 저주파수저음용 스피커를 사용한다.

WAVEFORMATEXTENSIBLE 구조체는, 멀티 채널 웨이브 포맷을 기술한다. 이 구조체는,WAVEFORMATEX 의 cbSize 멤버로 지원 되고 있는 추가 바이트를 구성하는,WAVEFORMATEX 의 확장 기능이다. WAVEFORMATEXTENSIBLE 구조체는,DSBUFFERDESC 구조체 등,WAVEFORMATEX 가 사용되는 장소에서 WAVEFROMATEX 로서 캐스트 할 수가 있다.

멀티 채널 웨이브 파일로 지정된 채널보다 물리적인 스피커가 적은 경우는, 오디오 데이터는 적절히 믹싱 되어 기존의 스피커에 출력된다.

DirectSound 는, 멀티 채널 포맷에서의 버퍼의 이펙트나 3D 처리를 지원 하고 있지 않다. DSBCAPS_CTRL3D 또는 DSBCAPS_CTRLFX 플래그를 지정해 버퍼를 생성 하려고 하면(자), 멀티 채널 웨이브 포맷은 실패한다.

멀티 채널 웨이브 포맷의 상세한 것에 대하여는,http://www.microsoft.com/hwdev/audio/multichaud.htm 로부터 입수 가능한 「Enhanced Audio Formats for Multi-Channel Configurations and High-Bit Resolution」를 참조할것.


웨이브 파일의 read

여기에서는, DirectMusic 로더 및 퍼포먼스를 사용하지 않고 , 웨이브 파일의 데이터를 DirectSound 버퍼에 로드하는 방법에 대해 설명한다. 대부분의 어플리케이션에서는, 웨이브 데이터나 버퍼를 직접 처리할 필요는 없다. 웨이브의 로드나 재생의 우선되는 방법에 대해서는, 「오디오 데이터의 로드」 및 「사운드의 재생」을 참조할것.

웨이브 파일은 RIFF (Resource Interchange File Format, 리소스 교환 파일 포맷)를 채용하고 있어 헤더 정보 (예를 들어 사운드 샘플의 웨이브 포맷)와 데이터 (샘플 자체)를 보관 유지하는, 임의의 수의 체크에 의해 구성되어 있다. Win32 API 는, RIFF 파일을 열거나 닫거나하기 위한 함수나, 체크의 검색 함수등을 제공한다. 이러한 함수의 이름은 모두 "mmio" 로 시작된다.

DirectSound API 는, 웨이브 파일을 처리하기 위한 메소드를 갖추지 않았다. 다만, 많은 SDK 샘플 어플리케이션으로 사용되는 Dsutil.cpp 파일은, 다음의 퍼블릭 메소드를 가지는 CWaveFile 클래스를 이행 한다.

  • Open. 읽을 위해(때문에) 파일을 열어 웨이브 포맷을 취득하거나 기입을 위해서(때문에) 파일을 열어 헷다체크를 기입한다.
  • GetSize. Open 가 불려 간 후, 데이타체크의 사이즈를 돌려준다.
  • Read. 데이타체크의 일부를 버퍼에 카피해, read 커서를 진행시킨다.
  • Write. 버퍼로부터 데이타체크에 기입해, 기입 커서를 진행시킨다.
  • ResetFile. read 커서와 기입해 커서를 데이타체크의 선두로 설정한다.
  • Close. 파일을 닫는다.

웨이브 파일을 읽어들이는 최초의 스텝은,CWaveFile::Open 메소드를 호출하는 것이다. 이 메소드는, 파일이 RIFF 포맷인 것을 확인해, 웨이브 포맷에 관한 정보를 취득한다. 파라미터는 파일명, 포맷의 NULL, 및 WAVEFILE_READ 플래그이다. 이 메소드는 HRESULT 를 돌려준다.

다음의 코드는, 웨이브 파일을 연다.

CWaveFile waveFile;

if (FAILED(waveFile.Open("mywave.wav", NULL, WAVEFILE_READ)))
{
    waveFile.Close();
}

이것으로, 어플리케이션은 파일로부터 세칸다리밧파에의 카피를 시작 할 수 있다. 보통은, 웨이브의 포맷을 취득할 때까지는 사운드 버퍼를 생성 하지 않는다. 다음의 코드는, 파일내의 전데이터를 보관 유지하는데 정확히 좋은 사이즈의스태틱 버퍼를 생성 한다.

LPDIRECTSOUNDBUFFER  lpdsbStatic;
DSBUFFERDESC         dsbdesc;

memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
dsbdesc.dwSize = sizeof(DSBUFFERDESC);
dsbdesc.dwFlags = 0;

/* 웨이브 포맷과 데이타체크의 사이즈는,
// CWaveFile::Open 가 불려 간 후, CWaveFile 에 저장 된다.

dsbdesc.dwBufferBytes = waveFile.GetSize();
dsbdesc.lpwfxFormat = waveFile.m_pwfx;

// lpds 는 유효한 IDirectSound8 포인터이다.

if FAILED(lpds->CreateSoundBuffer(&dsbdesc, &lpdsbStatic, NULL))
{
    // 에러 처리.
    .
    .
    .
}

이것으로, 버퍼에 데이터를 기입할 수가 있다. 이 경우, 어플리케이션은 데이터의 스트리밍을 실시하지 않기 때문에, 버퍼 전체가 선두로부터 락 된다. rack-around (선두에 돌아온다)도 발생하지 않기 때문에, 필요한 것은 1 개의 포인터와 바이트 카운트이다.

LPVOID lpvAudio1;
DWORD  dwBytes1;

if FAILED(lpdsbStatic->Lock(
        0,              // 락 시작의 오프셋(offset).
        0,              // 락의 사이즈. 이 경우는 무시된다.
        &lpvAudio1,     // 락 시작의 주소.
        &dwBytes1,      // 락 되는 바이트수.
        NULL,           // rack-around의 시작. 사용되지 않는다.
        NULL,           // rack-around의 사이즈. 사용되지 않는다.
        DSBLOCK_ENTIREBUFFER))
{
    // 에러 처리.
    .
    .
    .
}

CWaveFile::Read 메소드를 사용해, 다음과 같이 버퍼에 기입할 수가 있다.

DWORD dwBytesRead;

waveFile.Read((BYTE*) lpvAudio1, dwBytes1, &dwBytesRead);

마지막에 어플리케이션은 버퍼를 언락 해, 웨이브 파일을 닫는다.

lpdsbStatic->Unlock(lpvAudio1, dwBytes1, NULL, 0);
waveFile.Close();

스트림 버퍼의 경우는, 보통, 재생 커서의 움직임에 의해 결정되는 일정한 간격으로 CWaveFile::Read 를 호출한다. 버퍼의 락 된 부분이 rack-around 하고 있는 경우는, 락의 각 세그먼트(segment) 마다 이 메소드를 호출한다.

스트리밍의 상세한 것에 대하여는, 「스트림 버퍼의 사용법」 및 「재생 버퍼의 통지」를 참조할것.

CWaveFile 클래스의 사용법의 그 외의 예에 대해서는, DirectX SDK 인스톨에 포함되는 샘플 어플리케이션을 참조할것.


리소스로부터의 웨이브 데이터의 read

DirectSound API 는, 리소스로부터 웨이브를 읽어들이는 메소드를 갖추지 않았다. 다만, 많은 SDK 샘플 어플리케이션으로 사용되는 Dsutil.cpp 파일은, 리소스로서 저장 된 웨이브 및 웨이브 파일을 읽어들일 수가 있는 CWaveFile 클래스를 이행 한다.

실행 가능 파일에 웨이브 사운드를 보존하려면 , 웨이브 파일을 리소스로서 임포트 해, 캐릭터 라인의 이름을 할당한다. CWaveFile 에서는, 이러한 리소스가 "WAVE" 또는 "WAV" 타입이며, DLL 는 아니고 실행 가능 모듈에 포함되어 있는 것을 상정하고 있다.

다음의 코드는,"mywave" 로 식별되는 리소스를 연다.

CWaveFile waveFile;

if (FAILED(waveFile.Open("mywave", NULL, WAVEFILE_READ)))
{
    waveFile.Close();
}

연 리소스는, 파일과 같게 읽어들일 수가 있다. CWaveFile 클래스를 사용한 이 처리의 상세한 것에 대하여는, 「웨이브 파일의 read」를 참조할것.


DirectSound 에서의 이펙트의 사용법

순수한 DirectSound 어플리케이션에서의 이펙트의 재생은, 기본적으로는 DirectMusic 의 퍼포먼스 및 오디오 패스를 사용하는 어플리케이션의 경우와 같게 처리된다. 상세한 것에 대하여는, 「이펙트의 사용법」을 참조할것. DirectSound 어플리케이션에는 오디오 패스가 없기 때문에, 항상 버퍼를 직접 조작한다.

이펙트를 사용하려면 , DirectSound 어플리케이션은 CoInitialize 를 호출해 COM 를 초기화할 필요가 있다. 이 처리는,DirectSoundCreate8 에 의한 DirectSound 오브젝트의 생성을 배제하지 않는다.

버퍼가 너무 작으면 이펙트가 잘 동작하지 않는다. DirectSound 에서는, DSBSIZE_FX_MIN 밀리 세컨드 이하의 데이터 밖에 보관 유지할 수 없는 이펙트 사용 가능한 버퍼는 생성 할 수 없다.

DSBUFFERDESC 구조체의 DSBCAPS_CTRLFX 플래그를 설정해,DMO 를 보관 유지할 수 있는 세칸다리밧파를 생성 한다.

세칸다리사운드밧파로 이펙트를 이행 하려면 ,IDirectSoundBuffer8::SetFX 를 사용한다.

이펙트의 인터페이스를 취득하려면 ,IDirectSoundBuffer8::GetObjectInPath 를 사용한다. 이 메소드는,IDirectMusicAudioPath8::GetObjectInPath 나 IDirectMusicSegmentState8::GetObjectInPath 과는 달리,dwStage 파라미터를 취하지 않는다. 이것은, 버퍼로부터 취득할 수 있는 오브젝트는 DMO 만이니까이다.


사운드 캡춰

여기에서는, DirectMusic 및 DirectSoundCapture 오브젝트를 사용한 사운드의 캡춰에 대해 설명한다. 설명하는 주제는, 다음과 같다.

  • MIDI 의 캡춰
  • 웨이브의 캡춰


MIDI 의 캡춰

키보드등의 디바이스로부터 MIDI 메세지를 캡춰 하려면 , 캡춰 디바이스의 포토를 생성 해,IDirectMusicPort8::SetReadNotificationHandle 메소드를 사용해, 읽어들이는 메세지가 있을 때 항상 이벤트를 통지시킨다. 이벤트에 응답해,IDirectMusicPort8::Read 메소드의 호출을 S_FALSE 가 돌려주어질 때까지 반복해, 미처리의 이벤트를 버퍼에 둔다. Read 가 불려 갈 때마다, 이용 가능할 뿐(만큼)의 이벤트, 또는 버퍼에 들어갈 뿐(만큼)의 이벤트가 버퍼에 놓여진다. 적어도 1 개의 이벤트가 버퍼에 놓여지면(자), S_OK 가 돌려주어진다.

버퍼로부터 이벤트를 취득하려면 ,IDirectMusicBuffer8::GetNextEvent 메소드를 호출한다. S_FALSE 가 돌려주어져 이용 가능한 이벤트가 없어질 때까지, 호출할 것에 1 개의 이벤트를 취득한다.

다음의 샘플 코드는, 이 처리를 나타내고 있다. hEvent 가 CreateEvent 에 의해 생성 되어SetReadNotificationHandle 의 호출에 의해 캡춰 포토 pPort 에게 줄 수 있었다고 가정한다. 또,pBuffer 가 IDirectMusic8::CreateMusicBuffer 에 의해 초기화되었다고 가정한다.

REFERENCE_TIME rt;
DWORD          dwGroup;
DWORD          cb;
BYTE          *pb;

DWORD dw = WaitForMultipleObjects(1, hEvent, FALSE, INFINITE);
for (;;)
{
    hr = pPort->Read(pBuffer);
    if (hr == S_FALSE)
      {
          break;  // 더 이상 버퍼에 읽어들이는 메세지가 없다.
      }
    pBuffer->ResetReadPtr();
    for (;;)
    {
        hr = pBuffer->GetNextEvent(&rt, &dwGroup, &cb, &pb);
        if (hr == S_OK)
        {
            // pb 는 메세지의 데이터 구조체를 가리킨다.
            // 포인터를 사용해, 필요한 조작을 실행할 수 있다.
        }
        else if (hr == S_FALSE)
        {
            break;  // 버퍼에는 메세지가 남지 않았다.
        }
    }  // 버퍼의 조작이 종료.
}  // 미처리의 이벤트의 read가 종료.

도중에 메세지를 처리하지 않고 , 단지 메세지를 포토로부터 포토에 송신하는 경우는,IDirectMusicThru8 인터페이스를 사용한다. 상세한 것에 대하여는, 「IDirectMusicThru8::ThruChannel 」를 참조할것.


웨이브의 캡춰

DrectSoundCapture 오브젝트 (IDirectSoundCapture8 )는, 사운드 캡춰 디바이스의 능력의 문의나, 입력 소스로부터 오디오를 캡춰하기 위한 버퍼의 생성에 사용된다. DirectSoundCapture 를 사용하면(자),PCM 포맷 또는 압축 포맷으로 데이터를 캡춰 할 수 있다.

DirectSound 캡춰 버퍼 오브젝트 (IDirectSoundCaptureBuffer8 )는, 입력 디바이스로부터의 데이터를 받기 위한 버퍼를 나타낸다. 재생 버퍼와 같이, 이 버퍼는 순환이라고 하는 개념을 채용하고 있다. 입력 포인터가 버퍼의 마지막에 도달 하면, 자동적으로 시작점에 돌아온다.

IDirectSoundCaptureBuffer8 오브젝트의 메소드를 사용하면(자), 버퍼의 프로퍼티의 취득, 오디오 캡춰의 시작과 정지, 메모리의 일부의 락이 생기므로, 파일에 보존하는 등의 목적으로 데이터를 안전하게 취득할 수 있다. 이펙트의 캡춰를 지원 하는 operating system에서는,DMO 를 취득하거나 이펙트의 스테이터스를 확인하는 메소드도 제공한다.

웨이브의 캡춰의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 캡춰 디바이스의 열거
  • DirectSoundCapture 오브젝트의 생성
  • 캡춰 디바이스의 능력
  • 캡춰 버퍼의 생성
  • 캡춰 버퍼의 정보
  • 캡춰 버퍼의 통지
  • 캡춰 버퍼의 이펙트
  • 캡춰 버퍼의 사용법
  • 웨이브 파일에의 기입해


캡춰 디바이스의 열거

유저가 우선하는 캡춰 디바이스로 사운드를 캡춰 할 뿐(만큼)의 어플리케이션에서는, 이용 가능한 디바이스를 열거할 필요는 없다. NULL 또는 정의 끝난 GUID 를 DirectSoundCaptureCreate8 또는 DirectSoundFullDuplexCreate8 에 건네주는 것에 의해, 디폴트의 디바이스를 생성 할 수 있다. 상세한 것에 대하여는, 「DirectSoundCapture 오브젝트의 생성」을 참조할것.

특정의 종류의 디바이스를 찾고 있는 경우나, 복수의 디바이스를 사용해 동작할 필요가 있는 경우는, 시스템상에서 이용 가능한 디바이스를 열거해야 한다.

열거는 3 개의 목적으로 사용된다.

  • 이용 가능한 하드웨어를 보고.
  • 각 디바이스에 GUID 를 공급.
  • 각 디바이스를 열거했을 때에, 각 디바이스를 초기화. 그 결과, 각 디바이스의 능력을 체크할 수 있다.

디바이스를 열거하려면 , DirectSound 가 디바이스를 찾아낼 때마다 호출하는 콜백 함수를 최초로 생성 해야 한다. 필요한 모든 처리를 이 함수내에서 실행해, 함수에 임의의 이름을 붙일 수가 있지만, 이 함수는 prototype인 DSEnumCallback 와 같은 형식에서 선언해야 한다. 이 콜백 함수는, 열거를 계속하는 경우는 TRUE, 그 외 (예를 들어 필요한 능력을 갖춘 디바이스를 찾아낸 후등)의 경우는 FALSE 를 돌려주지 않으면 안 된다.

콜백 함수의 예에 대해서는, 「사운드 디바이스의 열거」를 참조할것. 각 디바이스의 GUID 가, 이 함수에게 건네지는 파라미터의 1 개로서 취득되는 점에 주의 해야 한다.

열거는 DirectSoundCaptureEnumerate 함수를 사용하는 것으로 동작에 옮겨진다.

DWORD pv;  // 임의의 32 비트형.

HRESULT hr = DirectSoundCaptureEnumerate(
        (LPDSENUMCALLBACK) DSEnumProc,
        (VOID*) &pv);


DirectSoundCapture 오브젝트의 생성

DirectSoundCapture 오브젝트를 생성 하려면 ,DirectSoundCaptureCreate8 또는 DirectSoundFullDuplexCreate8 함수를 호출한다. 이러한 함수는 모두,IDirectSoundCapture8 인터페이스에의 포인터를 취득한다.

DirectSoundCaptureCreate 에 대한 lpcGUID 파라미터나,DirectSoundFullDuplexCreate8 에 대한 pcGuidRenderDevice 파라미터에는, 열거에 의해 취득되는 GUID 또는 다음의 몇개의 정의가 끝난 GUID 를 지정할 수 있다.

DSDEVID_DefaultCapture
디폴트의 시스템 캡춰 디바이스. 디바이스의 GUID 파라미터로 NULL 포인터를 건네주는 것에 의해, 이 디바이스를 지정할 수도 있다.
DSDEVID_DefaultVoiceCapture
디폴트의 음성 통신 캡춰 디바이스. 이것은, 보통, USB 마이크 첨부 헤드 세트등의 세칸다리데바이스이다.

디바이스 드라이버가 존재하지 않는 경우는, 이 호출은 실패한다.

CoCreateInstance 함수를 사용해 오브젝트를 생성 할 수도 있다. 그 순서는, DirectSound 오브젝트를 생성 하는 순서와 같다. 「DirectSound 오브젝트의 생성」을 참조할것. CoCreateInstance 를 사용하는 경우, 컨트롤 패널로 유저가 선택한 디폴트의 캡춰 디바이스에 대응하는 오브젝트가 생성 된다.

DirectSound 오브젝트와 DirectSoundCapture 오브젝트를 공존시키고 싶은 경우는, DirectSoundCapture 오브젝트의 생성과 초기화를 실시하기 전에, DirectSound 오브젝트의 생성과 초기화를 실시하는지,DirectSoundFullDuplexCreate8 를 사용한다.

오디오 기기에 따라서는, 디폴트로 전이중 오디오 구성으로 되어 있지 않은 것도 있다. DirectSound 오브젝트와 DirectSoundCapture 오브젝트의 생성과 초기화 시에 문제가 발생했을 경우는, 유저에 대해서 오디오 디바이스 프로퍼티의 체크와 전이중 오디오가 유효하게 되어 있는 것의 확인을 요구하지 않으면 안 된다.


캡춰 디바이스의 능력

캡춰 디바이스의 능력을 취득하려면 ,IDirectSoundCapture8::GetCaps 메소드를 호출한다. 이 메소드의 파라미터는,DSCCAPS 구조체에의 포인터이다. 다른 구조체와 같이, 이 인수를 건네주기 전에 dwSize 멤버를 초기화해 두지 않으면 안 된다. 반환값으로서 이 구조체는 이 디바이스가 지원 하는 채널수, 및 지원 되는 포맷에 관한 값의 편성을 보관 유지한다. 후자의 값은, Win32 웨이브 폼 오디오 함수로 사용되고 있는 WAVEINCAPS 구조체의 값과 동등하다.

비 WDM 드라이버에서는, 캡춰 디바이스는 한 번에 1 개의 어플리케이션에서만 사용할 수 있다. 드라이버가, 복수의 어플리케이션에 의한 디바이스의 동시 사용을 지원 하고 있는 경우는,DSCCAPS 의 dwFlags 멤버에 DSCCAPS_MULTIPLECAPTURE 가 돌려주어진다. 각 어플리케이션은, 캡춰 버퍼에 대해 각각의 포맷을 설정할 수 있다.


캡춰 버퍼의 생성

캡춰 버퍼를 생성 하려면 ,IDirectSoundCapture8::CreateCaptureBuffer 메소드를 호출한다.

이 메소드에게 건네지는 파라미터의 1 개는 DSCBUFFERDESC 구조체이며, 이것은 희망의 버퍼의 특성을 기술하고 있다. 이 구조체의 마지막 멤버는,WAVEFORMATEX 구조체이지만, 목적의 웨이브 포맷의 상세하게 따라서 이 구조체를 초기화해야 한다.

어플리케이션이 DirectSound 와 DirectSoundCapture 의 양쪽 모두를 사용하는 경우, 캡춰 버퍼의 포맷이 프라이머리 버퍼의 포맷과 다르고 있으면(자), 캡춰 버퍼의 생성은 실패한다. 일부의 카드는 클락을 1 개 밖에 준비하고 있지 않기 때문에, 2 개(살)이 다른 주파수로 캡춰와 재생을 실시할 수 없는 것이 원인이다.

다음의 예에서는, 대략 1 초 분의 데이터를 보관 유지하는 캡춰 버퍼를 설정한다.

// pDSC 는 유효한 IDirectSoundCapture8 인터페이스 포인터이다.

DSCBUFFERDESC              dscbd;
LPDIRECTSOUNDCAPTUREBUFFER pDSCB;
WAVEFORMATEX               wfx =
    {WAVE_FORMAT_PCM, 2, 44100, 176400, 4, 16, 0};

    // wFormatTag, nChannels, nSamplesPerSec, mAvgBytesPerSec,
    // nBlockAlign, wBitsPerSample, cbSize

dscbd.dwSize = sizeof(DSCBUFFERDESC);
dscbd.dwFlags = 0;
dscbd.dwBufferBytes = wfx.nAvgBytesPerSec;
dscbd.dwReserved = 0;
dscbd.lpwfxFormat = &wfx;
dscbd.dwFXCount = 0;
dscbd.lpDSCFXDesc = NULL;

pDSCB = NULL;

HRESULT hr = pDSC->CreateCaptureBuffer(&dscbd,
        &pDSCB, NULL);


캡춰 버퍼의 정보

캡춰 버퍼의 사이즈를 취득하려면 ,IDirectSoundCaptureBuffer8::GetCaps 메소드를 사용한다. 이 구조체를 파라미터로서 건네주기 전에,DSCBCAPS 구조체의 dwSize 멤버를 초기화해 두지 않으면 안 된다.

버퍼 생성시로 설정된, 버퍼내의 데이터 형식의 정보를 취득할 수도 있다. IDirectSoundCaptureBuffer8::GetFormat 메소드를 호출하면, 이 메소드는 WAVEFORMATEX 구조체를 사용해 포맷 정보를 돌려준다.

lpwfxFormat 파라미터로 NULL 를 지정해 GetFormat 메소드를 최초로 호출하는 것으로, 어플리케이션이 WAVEFORMATEX 구조체를 통해 추가의 포맷 정보를 입수할 수 있는 점에 주의 해야 한다. 이 경우,lpdwSizeWritten 파라미터가 가리키는 DWORD 가, 완전한 포맷 정보를 받는데 필요한 구조체의 사이즈를 받는다.

캡춰 버퍼가 현재 가고 있는 것을 파악하려면 ,IDirectSoundCaptureBuffer8::GetStatus 메소드를 호출한다. 이 메소드는 플래그의 편성을 변수 DWORD 에 기입하지만, 그 플래그는 버퍼가 캡춰 링으로 Busy일지 어떨지, Busy의 경우는 루프 하고 있을지 어떨지 (즉 IDirectSoundCaptureBuffer8::Start 를 직전에 호출한 시점에서 DSCBSTART_LOOPING 플래그를 설정해 있었는지)를 나타낸다.

마지막으로,IDirectSoundCaptureBuffer8::GetCurrentPosition 메소드는, 버퍼내에서의 현재의 read 커서와 캡춰 커서의 오프셋(offset)를 돌려준다. read 커서는, 이 시점에서 완전하게 캡춰 되어 버퍼에 놓여진 데이터의 최후이다. 캡춰 커서는, 현재 하드웨어로부터 카피되고 있는 한중간의 데이터 블록의 최후이다. 버퍼로부터 안전하게 카피할 수 있는 것은 read 커서까지의 데이터뿐이다.


캡춰 버퍼의 통지

read 커서가 버퍼내가 있는 위치 또는 마지막에 달했을 때에, 어플리케이션에의 통지를 발생시키고 싶은 것이 있다. 버퍼내에서의 읽어들여 커서까지의 부분은, 안전하게 데이터를 읽어들일 수가 있다. IDirectSoundNotify8::SetNotificationPositions 메소드를 사용하면(자), 이벤트의 시그널을 송신하는 포인트를 버퍼내에 몇개에서도 설정할 수 있다.

우선,IDirectSoundNotify8 인터페이스에의 포인터를 취득한다. 「재생 버퍼의 통지」로 설명했던 대로, 캡춰 버퍼의 QueryInterface 메소드를 사용해 이것을 취득할 수가 있다.

다음에, Win32 의 CreateEvent 함수를 사용해, 이벤트 오브젝트를 생성 한다. 이 이벤트에의 핸들을 DSBPOSITIONNOTIFY 구조체의 hEventNotify 멤버에 기입해, 이 구조체의 dwOffset 멤버로, 버퍼내에서 이벤트의 시그널을 송신하고 싶은 위치의 오프셋(offset)를 지정한다. 다음에 이 구조체의 주소를, 또는 복수의 통지 위치를 설정하고 싶은 경우는 구조체의 배열을,IDirectSoundNotify8::SetNotificationPositions 메소드에 건네준다.

다음의 예는, 3 개의 통지 위치를 설정한다. 1 개의 이벤트는 읽어들여 위치가 버퍼내의 중앙에 이르렀을 때, 2 번째는 마지막 근처에 이르렀을 때, 3 번째는 캡춰가 정지했을 때에, 각각 시그널을 송신한다.

#define cEvents  3

// 이하의 변수는 올바르게 초기화되어
// 버퍼의 생성시에, 버퍼 기술에 wfx 가 포함되어 있으면(자)
// 가정하고 있다.
//   LPDIRECTSOUNDNOTIFY8 lpDsNotify;
//   WAVEFORMATEX          wfx;

HANDLE             rghEvent[cEvents] = {0};
DSBPOSITIONNOTIFY  rgdsbpn[cEvents];
HRESULT            hr;
int                i;

// 이벤트를 생성 한다.
for (i = 0; i < cEvents; ++i)
{
    rghEvent[i] = CreateEvent(NULL, TRUE, FALSE, NULL);
    if (NULL == rghEvent[i])
    {
        hr = GetLastError();
        goto Error;
    }
}

// 통지를 기술한다.

rgdsbpn[0]. dwOffset = (wfx.nAvgBytesPerSec/2) -1;
rgdsbpn[0]. hEventNotify = rghEvent[0];

rgdsbpn[1]. dwOffset = wfx.nAvgBytesPerSec - 1;
rgdsbpn[1]. hEventNotify = rghEvent[1];

rgdsbpn[2]. dwOffset = DSBPN_OFFSETSTOP;
rgdsbpn[2]. hEventNotify = rghEvent[2];

// 통지를 생성 한다.

hr = lpDsNotify->SetNotificationPositions(cEvents, rgdsbpn);


캡춰 버퍼의 이펙트

캡춰 버퍼의 이펙트는, 현재의 operating system에서는 이용할 수 없다.

캡춰 버퍼의 이펙트를 설정하려면 ,IDirectSoundCapture8::CreateCaptureBuffer 에게 건네지는 DSCBUFFERDESC 구조체에 이펙트를 기술한다. 생성 된 버퍼의 정보를 취득하려면 ,IDirectSoundCaptureBuffer8::GetFXStatus 를 사용한다.

DirectX 8.0 으로 지원 되고 있는 캡춰 이펙트의 인터페이스에는 다음의 것이 있어, 이러한 인터페이스를 사용해 파라미터를 설정 및 취득한다.

  • IDirectSoundCaptureFXAec8
  • IDirectSoundCaptureFXNoiseSuppress8

이러한 인터페이스를 캡춰 버퍼 오브젝트로부터 취득하려면 ,IDirectSoundCaptureBuffer8::GetObjectInPath 를 사용한다.


캡춰 버퍼의 사용법

사운드의 캡춰는, 다음의 스텝으로 구성된다.

  1. IDirectSoundCaptureBuffer8::Start 메소드를 호출해 버퍼링을 시작 한다. 입력 디바이스로부터 얻은 오디오 데이터를, 버퍼의 시작 위치 이후에 기입한다.
  2. 희망의 양의 데이터가 이용 가능하게 될 때까지 기다린다. 캡춰 커서가 특정의 지점에 이르는 시기를 결정하는 방법의 1 개에 대해서는, 「캡춰 버퍼의 통지」를 참조할것.
  3. 충분한 데이터가 이용 가능하게 되었을 때,IDirectSoundCaptureBuffer8::Lock 메소드를 호출해 캡춰 버퍼의 일부를 잠근다.

    락을 시도하는 부분이, 캡춰에 사용되려 하고 있는 메모리 부분과 겹치지 않은 것을 확인하려면 , 최초로 IDirectSoundCaptureBuffer8::GetCurrentPosition 를 호출해 현재의 read 커서의 위치를 취득한다. read 커서에 대해서는, 「캡춰 버퍼의 정보」를 참조할것.

    Lock 메소드의 파라미터로서 읽어들이고 싶은 메모리 블록의 사이즈와 오프셋(offset)를 건네준다. 이 메소드는, 메모리 블록 시작 위치의 주소에의 포인터와 블록의 사이즈를 돌려준다. 블록이 버퍼의 최후로부터 최초에 rack-around 하고 있는 (선두에 돌아오고 있다) 경우, 블록의 섹션 마다 1 개(살), 합계 2 개의 포인터가 돌려주어진다. 버퍼의 락 부분이 rack-around 하고 있지 않는 경우는, 2 번째의 포인터는 NULL 이다.

  4. Lock 메소드가 돌려준 주소와 블록 사이즈를 사용해, 버퍼로부터 데이터를 카피한다.
  5. IDirectSoundCaptureBuffer8::Unlock 메소드를 사용해, 버퍼를 언락 한다.
  6. 전데이터의 캡춰가 끝날 때까지, 스텝 2 에서 5 를 반복한다. 다음에,IDirectSoundCaptureBuffer8::Stop 메소드를 호출한다.

보통, 캡춰 커서가 버퍼의 마지막에 달하면(자), 버퍼는 캡춰 링을 자동적으로 정지한다. 그러나,IDirectSoundCaptureBuffer8::Start 메소드에 건네주는 dwFlags 파라미터로 DSCBSTART_LOOPING 플래그를 설정했을 경우는, 어플리케이션이 IDirectSoundCaptureBuffer8::Stop 메소드를 호출할 때까지 캡춰는 속행된다.


웨이브 파일에의 기입해

DirectSound API 는, 웨이브 파일에의 기입을 위한 메소드를 갖추지 않았다. 다만, 많은 SDK 샘플 어플리케이션으로 사용되는 Dsutil.cpp 파일은, 다음의 퍼블릭 메소드를 가지는 CWaveFile 클래스를 이행 한다.

  • Open. 기입을 위해서(때문에) 파일을 열어 웨이브 포맷을 취득하거나 기입을 위해서(때문에) 파일을 열어 헷다체크를 기입한다.
  • GetSize. Open 또는 ResetFile 가 불려 간 후, 데이타체크의 사이즈를 돌려준다.
  • Read. 데이타체크의 일부를 버퍼에 카피해, read 커서를 진행시킨다.
  • Write. 버퍼로부터 데이타체크에 기입해, 기입 커서를 진행시킨다.
  • ResetFile. read 커서와 기입해 커서를 데이타체크의 선두로 설정한다.
  • Close. 파일을 닫는다.

웨이브 파일을 기입하는 최초의 스텝은,CWaveFile::Open 메소드를 호출하는 것이다. 이 메소드는, 파일을 생성 해, 웨브포맛트체크를 기입한다. 파라미터는, 파일명, 초기화된 WAVEFORMATEX 구조체에의 포인터, 및 WAVEFILE_WRITE 플래그이다. 이 메소드는 HRESULT 를 돌려준다.

다음의 코드는, 기입을 위해서(때문에) 웨이브 파일을 연다.

CWaveFile     g_pWaveFile;
WAVEFORMATEX  wfxInput;

ZeroMemory( &wfxInput, sizeof(wfxInput));
wfxInput.wFormatTag = WAVE_FORMAT_PCM;
wfxInput.nSamplesPerSec = 22050
wfxInput.wBitsPerSample =  8;
wfxInput.nChannels = 1;
wfxInput.nBlockAlign =
    wfxInput.nChannels * (wfxInput.wBitsPerSample / 8);
wfxInput.nAvgBytesPerSec =
    wfxInput.nBlockAlign * wfxInput.nSamplesPerSec;

g_pWaveFile = new CWaveFile;
if (FAILED(g_pWaveFile->Open("mywave.wav", &wfxInput,
        WAVEFILE_WRITE)))
{
    g_pWaveFile->Close();
}

이것으로, 어플리케이션은 캡춰 버퍼로부터 파일에의 카피를 시작 할 수 있다. 다음의 함수는, read 커서가 통지 위치에 도달할 때마다 불려 간다. 다음의 글로벌 변수가 사용된다.

  • g_pDSBCapture 는, 캡춰 버퍼의 IDirectSoundCapture 인터페이스에의 포인터이다.
  • g_dwNextCaptureOffset 는, 파일에 카피되는 다음의 데이터 블록의 버퍼 오프셋(offset)를 기록한다.
  • g_dwCaptureBufferSize 는, 캡춰 버퍼의 사이즈이며, rack-around의 계산에 사용된다.
HRESULT RecordCapturedData()
{
    HRESULT hr;
    VOID*   pbCaptureData    = NULL;
    DWORD   dwCaptureLength;
    VOID*   pbCaptureData2   = NULL;
    DWORD   dwCaptureLength2;
    VOID*   pbPlayData       = NULL;
    UINT    dwDataWrote;
    DWORD   dwReadPos;
    LONG lLockSize;

    if (NULL == g_pDSBCapture)
        return S_FALSE;
    if (NULL == g_pWaveFile)
        return S_FALSE;

    if (FAILED( hr = g_pDSBCapture->GetCurrentPosition(
            NULL, &dwReadPos)))
        return hr;

    // 프라이빗 커서와 읽어들여 커서의 사이를
    // 모두 잠그어, rack-around를 가능하게 한다.

    lLockSize = dwReadPos - g_dwNextCaptureOffset;
    if( lLockSize < 0 )
        lLockSize += g_dwCaptureBufferSize;

    if( lLockSize == 0 )
        return S_FALSE;

    if (FAILED(hr = g_pDSBCapture->Lock(
            g_dwNextCaptureOffset, lLockSize,
            &pbCaptureData, &dwCaptureLength,
            &pbCaptureData2, &dwCaptureLength2, 0L)))
    return hr;

    // 데이터를 기입한다. 이것은 2 개의 스텝에서 행해져
    // rack-around가 계산된다.

    if (FAILED( hr = g_pWaveFile->Write( dwCaptureLength,
            (BYTE*) pbCaptureData, &dwDataWrote)))
        return hr;

    if (pbCaptureData2 ! = NULL)
    {
        if (FAILED(hr = g_pWaveFile->Write(
                dwCaptureLength2, (BYTE*) pbCaptureData2,
                &dwDataWrote)))
                return hr;
    }

    // 캡춰 버퍼를 언락 한다.

   g_pDSBCapture->Unlock( pbCaptureData, dwCaptureLength,
            pbCaptureData2, dwCaptureLength2  );

    // 캡춰 오프셋(offset)를 이동한다.

    g_dwNextCaptureOffset += dwCaptureLength;
    g_dwNextCaptureOffset %= g_dwCaptureBufferSize;
    g_dwNextCaptureOffset += dwCaptureLength2;
    g_dwNextCaptureOffset %= g_dwCaptureBufferSize;

    return S_OK;
}

캡춰가 종료 하면, 어플리케이션은 웨이브 파일을 닫는다.

g_pWaveFile->Close();

CWaveFile::Close 메소드는, 파일을 닫기 전에, 체크사이즈를 파일에 기입한다.


DirectX Audio 의 고도의 주제

여기에서는, 「DirectX Audio 의 사용법」으로 기술되고 있는 기능보다 고도의 기능을 필요로 하는 특수한 어플리케이션에 대해 설명한다.

설명하는 주제는, 다음과 같다.

  • DirectMusic 트럭
  • DirectMusic 메세지의 사용법
  • DirectMusic 포토의 사용법
  • 커스텀 로드
  • 음색 콜렉션의 사용법
  • 하위 레벨 DLS
  • DirectMusic 툴
  • 프로퍼티 세트
  • DirectSound 의 성능의 최적화
  • 프라이머리 버퍼에의 기입해


DirectMusic 트럭

트럭은 세그먼트(segment)의 컴퍼넌트로, 순서화 된 데이터가 포함된다. 데이터에는, 노트, 베이스 코드, 템포, 패치 체인지, 밴드 체인지, 및 퍼포먼스가 사운드를 연주할 경우에 알아 둘 필요가 있는, 그 외 모두에 관한 정보가 포함된다.

각 트럭은,IDirectMusicTrack8 인터페이스에 의해 나타내진다. 이 인터페이스의 메소드는 퍼포먼스에 의해 불려 가 대부분의 어플리케이션에서는, 직접 사용할 필요는 없다. 이 인터페이스는, 주로, 독자적인 타입의 트럭을 이행 하는 플러그 인 컴퍼넌트로 사용한다.

어플리케이션이 IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 를 호출하면, DirectMusic 는 그 세그먼트(segment)의 트랙에 도착해 IDirectMusicTrack8::Play 또는 IDirectMusicTrack8::PlayEx 메소드를 호출한다. 대부분의 트럭은, 연주되고 있는 세그먼트(segment)의 파트에 대해서 유효한 데이터를 포함한, 타임 스탬프 메세지를 즉시 생성한다. 이러한 메세지는 큐에 저장 된다. 그 후의 동작에 대해서는, 「메세지의 생성과 전달」을 참조할것.

몇개의 트럭에서는,IDirectMusicTrack8::Play 나 IDirectMusicTrack8::PlayEx 에 대해서 통지 이외의 메세지는 생성되지 않지만, 대신에 퍼포먼스나 다른 트럭으로부터의 정보의 요구에 응답한다. 가장 중요한 것으로 해, 코드, 뮤트, 및 커멘드의 각 트럭이 있다. 템포 트럭은 메세지를 송신하지만, 파라미터의 요구에도 응답한다.

상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 표준 트럭의 종류
  • 트럭 구성


표준 트럭의 종류

다음의 리스트는, Microsoft® DirectMusic® 로 이행 되는 표준 트럭의 종류를 나타내고 있다. CLSID_DirectMusicBandTrack 등의 클래스 식별자는, 다양한 메소드의 호출에서의 트럭의 종류를 식별하기 위해서 사용한다.

트럭의 종류 | 클래스 GUID | 목적
밴드 | CLSID_DirectMusicBandTrack | DLS 데이터를 퍼포먼스에 다운로드한다. DMUS_PATCH_PMSG ,DMUS_TRANSPOSE_PMSG ,DMUS_CHANNEL_PRIORITY_PMSG , 및 DMUS_MIDI_PMSG 형의 메세지를 송신한다 (볼륨 및 빵용). MIDI 파일 및 스타일에 근거하는 세그먼트(segment)로 사용된다.
코드 | CLSID_DirectMusicChordTrack | 패턴내의 뮤직값을, MIDI 값으로 변환하기 위해서(때문에) 사용된다. DMUS_NOTIFICATION_PMSG 형의 메세지를 송신한다 (GUID_NOTIFICATION_CHORD 통지용).
코드 맵 | CLSID_DirectMusicChordMapTrack | 코드 트럭을 생성 하기 위해서, 템플릿 세그먼트(segment)로 사용된다.
커멘드 | CLSID_DirectMusicCommandTrack | 템플릿 세그먼트(segment)로 코드 트럭을 생성 하기 위한(해), 및 스타일 세그먼트(segment)로 연주하는 패턴을 결정하기 위해서(때문에) 사용된다. GUID_NOTIFICATION_COMMAND 통지용의 DMUS_NOTIFICATION_PMSG 형의 메세지를 송신한다.
가사 | CLSID_DirectMusicLyricsTrack | 단어와 뮤직을 동기 시키기 위해서(때문에) 사용된다. DMUS_LYRIC_PMSG 형의 메세지를 생성한다.
마커 | CLSID_DirectMusicMarkerTrack | flow control에 사용된다. 마커 트럭은, 세그먼트(segment)의 시작 타임, 및 새로운 세그먼트(segment)에 큐를 줄 수가 있는 연주 타임을 보관 유지할 수 있다. 상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것.
모티프 | CLSID_DirectMusicMotifTrack | 다른 세그먼트(segment)와 함께 모티프를 연주하기 위해서 사용한다. DMUS_CURVE_PMSG ,DMUS_NOTE_PMSG , 및 DMUS_NOTIFICATION_PMSG 형의 메세지를 송신한다 (GUID_NOTIFICATION_MEASUREANDBEAT 의 통지용).
뮤트 | CLSID_DirectMusicMuteTrack | 퍼포먼스 채널을 재맵 또는 뮤트 할 수 있도록(듯이) 한다. 스타일 베이스의 세그먼트(segment), 또는 MIDI 베이스의 세그먼트(segment)와 함께 사용한다.
파라미터 제어 | CLSID_DirectMusicParamControlTrack | 툴, 이펙트, 및 IMediaParams 인터페이스를 지원 하는 그 외의 오브젝트의 설정을 제어한다.
패턴 | CLSID_DirectMusicPatternTrack | 단일의 뮤직 패턴을 포함한다. 패턴 트럭은 순서 트럭과 닮아 있지만, 고정된 노트는 아니고 뮤직값을 포함한다. 이 트럭은 다양한 코드에 대해 패턴의 오디션을 실행할 수 있도록(듯이) 해, 많은 경우 뮤직 오쏘링 어플리케이션으로 사용된다. 반주를 연주하기 위해서도 사용된다. 이 트럭은, 독자적인 인터페이스 IDirectMusicPatternTrack8 에 의해 나타내진다.
스크립트 | CLSID_DirectMusicScriptTrack | 오디오 스크립트로 루틴을 호출한다.
세그먼트(segment) 방아쇠 | CLSID_DirectMusicSegmentTriggerTrack | 세그먼트(segment)의 재생을 방아쇠 한다. 이 트럭을 사용 하면, 어플리케이션 개발자에게 맡기는 것이 아니라, 파일의 작가가 세그먼트(segment)내로부터 세그먼트(segment)에 큐를 줄 수가 있다.
순서 | CLSID_DirectMusicSeqTrack | DMUS_NOTE_PMSG 및 DMUS_MIDI_PMSG 형의 순서 메세지를 송신한다. MIDI 파일에 근거하는 세그먼트(segment)로 사용된다.. sgt 형식에서 보존된 세그먼트(segment)에 대해,DMUS_CURVE_PMSG 형의 메세지를 송신한다.
싸인 포스트 | CLSID_DirectMusicSignPostTrack | 코드 트럭을 생성 하기 위해서, 템플릿 세그먼트(segment)로 사용된다.
스타일 | CLSID_DirectMusicStyleTrack | 스타일에 근거하는 세그먼트(segment)의 기본적인 트럭. DMUS_TIMESIG_PMSG ,DMUS_CURVE_PMSG,DMUS_NOTE_PMSG, 및 DMUS_NOTIFICATION_PMSG 형의 메세지를 송신한다 (GUID_NOTIFICATION_MEASUREANDBEAT 의 통지용).
시스템에크스크루시브 | CLSID_DirectMusicSysExTrack | DMUS_SYSEX_PMSG 형의 시스템에크스크루시브멧세이지를 송신한다. MIDI 파일에 근거하는 세그먼트(segment)로 사용된다.
템포 | CLSID_DirectMusicTempoTrack | 퍼포먼스의 템포를 제어한다.
박자 기호 | CLSID_DirectMusicTimeSigTrack | GUID_NOTIFICATION_MEASUREANDBEAT 통지와 같게,DMUS_TIMESIG_PMSG 형의 메세지를 송신한다. 박자 기호 트럭은, 임포트 된 MIDI 파일 및 그것을 사용해 생성 되는 세그먼트(segment)내에 존재한다. 대부분의 경우, 스타일 트럭은 박자 기호 트럭의 기능을 이행 한다. 그 때문에, 스타일 트럭을 포함하고 있는 세그먼트(segment)가 박자 기호 트럭도 포함하고 있을 필요는 없다.
웨이브 | CLSID_DirectMusicWaveTrack | 타임 스탬프 첨부의 웨이브 메세지를 연주하기 위해서,DMUS_WAVE_PMSG 형의 메세지를 송신한다.


트럭 구성

IDirectMusicSegment8::SetTrackConfig 와 IDirectMusicSegmentState8::SetTrackConfig 의 각 메소드를 사용해, 어플리케이션으로 세그먼트(segment)내의 임의의 트럭의 동작을 변경할 수 있다. 다음과 같은 구성 옵션이 있다.

  • 재생을 유효 또는 무효로 한다.
  • 제어 세그먼트(segment)내의 트럭에 대한 파라미터 호출을 유효 또는 무효로 한다.
  • 통지를 유효 또는 무효로 한다.
  • 세칸다리 제어 세그먼트(segment)의 통지에 의한 프라이머리 세그먼트(segment)의 통지를 오버라이드(override) 한다.
  • 트럭의 어레인지를 유효 또는 무효로 한다.
  • 트란지션의 어레인지에 사용되는 트럭 데이터의 시작 포인트를 제어한다.

트럭 구성 플래그의 일람 및 표준 트럭으로 유효한 플래그의 겉(표)에 대해서는, 「IDirectMusicSegmentState8::SetTrackConfig 」를 참조할것.

DMUS_TRACKCONFIG_CONTROL_PLAY 와 DMUS_TRACKCONFIG_CONTROL_NOTIFICATION 의 2 개의 구성 플래그는, 세칸다리 제어 세그먼트(segment)의 기능을 확장한다. 보통, 세칸다리 제어 세그먼트(segment)은, 퍼포먼스에 의해 IDirectMusicTrack8::GetParam 의 호출로부터 취득된 파라미터만을 관리한다. 다른 세그먼트(segment)와 같게, 제어 세그먼트(segment)는 메세지를 송신하는 것에 의해 퍼포먼스를 변경할 수도 있다. 예를 들어, 퍼포먼스의 볼륨을 변경할 수 있다. 이러한 변경은 프라이머리 세그먼트(segment)의 파라미터를 오버라이드(override) 하고 있는 것처럼 보이지만, 실제의 컨트롤의 변경과는 2 개의 점으로써 다르다.

  • 다른 세그먼트(segment)에 의해 같은 변경을 할 때까지 유효하다. 제어 세그먼트(segment)의 파라미터는, 다른 세그먼트(segment)에 의해 오버라이드(override) 할 수 없다.
  • 오버라이드(override) 되지 않는 이상 송신 세그먼트(segment)의 연주가 종료한 후도 유효인 채이다. 제어 세그먼트(segment)의 파라미터는, 다른 세그먼트(segment)가 제어 세그먼트(segment)가 될 때까지 유효하다.

트랙에 도착해 DMUS_TRACKCONFIG_CONTROL_PLAY 또는 DMUS_TRACKCONFIG_CONTROL_NOTIFICATION 플래그가 설정되어 있는 경우, 프라이머리 세그먼트(segment)의 대응하는 트럭은 무효가 된다. 제어 세그먼트(segment)가 정지 하면 다시 유효하게 된다.

SetTrackConfig 메소드는 IDirectMusicSegmentState8 인터페이스 및 IDirectMusicSegment8 로 사용할 수 있다. 파라미터는 같지만, 그 동작은 다음과 같이 다르다.

  • 세그먼트(segment)의 플래그를 변경했을 경우, 이후에 연주되는 세그먼트(segment) 상태의 인스턴스는, 변경된 플래그를 계승한다. 다만, 이미 연주중의 세그먼트(segment) 상태의 동작은 변경되지 않는다.
  • 세그먼트(segment)의 플래그를 변경했을 경우, 그 세그먼트(segment) 상태만은 동작이 즉시 변경된다.

주 세그먼트(segment) 상태의 트럭 구성이, 준비 시간의 다음에는 없고, 즉시 변경되도록(듯이) 하려면 ,IDirectMusicPerformance8::Invalidate 를 호출한다.

다음의 샘플 코드에서는,pSegment 로 주소가 지정된 세그먼트(segment)의 코드 진행 트럭을 무효로 하고 있다. 코드 진행은, 제어 세그먼트(segment)의 파라미터로서 있는 요소를 전요소에 카피하므로, DMUS_TRACKCONFIG_CONTROL_ENABLED 플래그를 오프로 하는 것에 의해 이 처리를 실시한다.

HRESULT hr = pSegment->SetTrackConfig(CLSID_DirectMusicChordTrack,
        -1, DMUS_SEG_ALLTRACKS, 0, DMUS_TRACKCONFIG_CONTROL_ENABLED);

다음의 예에서는, 반대로, 모든 코드 트럭의 연주를 유효하게 하고 있다.

hr = pSegment->SetTrackConfig(CLSID_DirectMusicChordTrack,
        -1, DMUS_SEG_ALLTRACKS, DMUS_TRACKCONFIG_CONTROL_ENABLED, 0);

관련 정보에 대해서는, 다음의 주제를 참조할것.

  • 트럭의 어레인지
  • 제어 세그먼트(segment)
  • 자기 제어 세그먼트(segment)


DirectMusic 메세지의 사용법

사운드 데이터는, 메세지의 형태로 DirectMusic 퍼포먼스에게 건네진다. 대부분의 경우, 메세지의 생성 및 처리는 자동적으로 행해져 어플리케이션으로 직접 이러한 처리를 할 필요는 없다. 다만, 메세지의 기본적인 지식은 DirectMusic 의 구조를 이해하는데 도움이 되어, 이해가 깊어지는 만큼, 메세지를 사용해 퍼포먼스를 세세하게 제어할 수 있게 된다.

DirectMusic 에서는, 2 종류의 메세지가 사용된다.

  • 퍼포먼스 메세지. 순서화 된 데이터는 모두, 이 형식에서 퍼포먼스 엔진에게 건네진다. 이러한 메세지에는, 데이터의 타이밍 및 루팅에 관한 상세한 정보가 포함되어 있다.
  • 스탠다드 MIDI 메세지. 이러한 메세지는, MIDI 파일 또는 디바이스로부터 읽혀 다른 디바이스에 직접 건네받는 (스르 된다)인가, 재생시에 퍼포먼스에 의해 퍼포먼스 메세지 형식에 변환된다.

어플리케이션은, MIDI 메세지를 직접 처리하지 않는다. 세그먼트(segment)를 연주하는 경우, 그 모든 데이터는 퍼포먼스 메세지 형식이며, 최종적인 출력 툴에게 건네질 때까지 그 형식인 채이다. 최종적인 출력 툴에서는, 퍼포먼스 메세지를 MIDI 메세지 포맷으로 변환한 후, 순서화해 신디사이저에 건네준다. 다만, 일부의 퍼포먼스 메세지에는, 스탠다드 MIDI 메세지와 같은 정보가 포함되어 있다. 이러한 메세지를 이해하기 위해서, 여기에서는 MIDI 메세지 포맷의 몇개의 점에 대해 설명한다.

주 DMUS_MIDI_PMSG 구조체는, 스탠다드 MIDI 메세지의 데이터에 상당하는 데이터를 저장 한다. 다만, 퍼포먼스 메세지이다.

대부분의 퍼포먼스 메세지는, 세그먼트(segment)가 연주될 때, 세그먼트(segment)의 트럭에 의해 송신된다. 어플리케이션은, 메세지를 송신해, MIDI 콘트롤러의 설정, 단일의 노트의 연주, 템포의 변경등의 처리도 실시할 수가 있다.

메세지를 송신한 후, 어플리케이션은 툴을 이행 하는 방법 이외에 메세지를 취득 또는 변경할 수 없다. 예를 들어, DirectMusic Producer 로 오쏘링 한 세그먼트(segment)에는,DMUS_LYRIC_PMSG 메세지를 생성하는 가사 트럭이 포함되는 경우가 있다. 어플리케이션으로 이 가사를 표시하는 방법은, 그 목적에 맞은 툴을 이행 하는 방법 뿐이다. 상세한 것에 대하여는, 「DirectMusic 툴」을 참조할것.

통지는, 메세지가 툴에서만 처리할 수 있다고 하는 규칙의 예외이다. IDirectMusicPerformance8::GetNotificationPMsg 메소드에 의해, 어플리케이션은 DMUS_NOTIFICATION_PMSG 메세지를 취득할 수 있다. 상세한 것에 대하여는, 「통지와 이벤트의 처리」를 참조할것.

다음의 주제에서는, 메세지와 그 루팅 방법에 대해 설명한다.

  • 채널
  • 메세지의 생성과 전달
  • 어플리케이션으로 생성 된 메세지
  • 퍼포먼스 메세지의 타입
  • 커브
  • MIDI 메세지


채널

채널은, 퍼포먼스내의 1 개의 파트에 고유의 메세지의 송신지이다. 예를 들어 채널은, 음색에 사운드를 발생시키는 노트 온 메세지를 받아들이거나 파트에 다른 음색을 할당하는 프로그램 체인지 메세지를 받아들인다. 「MIDI 채널 메세지」를 참조할것.

MIDI 1.0 규격에서는, 16 개의 MIDI 채널이 있어, 한 번에 16 을 넘는 음색은 연주할 수 없는 것을 의미하고 있다. DirectMusic 에서는, 이 규격에 대응 하면 동시에, 어플리케이션이 보다 많은 채널을 동시에 이용할 수 있도록(듯이), 채널 그룹이 생성 된다. 최대 65,536 개의 채널 그룹이 동시에 존재해, 각각 16 개의 채널이 포함되므로, 채널 총수는 100 만 이상으로 오른다. 특정의 포토에, 그 포토가 지원 하는 범위에서 임의의 수의 채널 그룹을 할당할 수가 있다. MIDI 하드웨어 포토에는, 1 개의 채널 그룹 밖에 할당할 수가 없다.

시스템에크스크루시브멧세이지는, 1 개의 채널 그룹내의 16 채널의 모두에 대해서 송신할 수 있지만, 다른 채널 그룹 앞으로는 송신할 수 없다.

DirectMusic 퍼포먼스내의 모든 파트는, 고유의 퍼포먼스 채널, 즉 P 채널을 가진다. 퍼포먼스 채널은, 특정의 포토에 대한 특정의 그룹내의 특정의 MIDI 채널을 나타낸다. 퍼포먼스가 있는 밴드를 선택 하면, 그 밴드내의 각 음색은 1 개의 퍼포먼스 채널에 맵 되어 그 채널의 파트는 그 음색으로 연주된다.

오디오 패스가 사용되고 있는 경우는, 다른 오디오 패스 위에의 동일한 퍼포먼스 채널이 다른 출력 채널에 맵 된다.

채널의 우선 순위

동시에 연주할 수 있는 노트의 수는, 포토로 이용할 수 있는 음성수에 의해 제한된다. 음성은, 채널로 연주되는 1 개의 노트 또는 웨이브를 합성하는, 리소스세트이다. 이용할 수 있는 음성의 수보다 많은 노트가 연주되는 경우는, 신디사이저에 의해, 1 개(살) 또는 복수의 노트가 억제되지 않으면 안 된다. 어느 노트를 연주할까는, 현재 노트를 연주하고 있는 음성의우선 순위에 의해 결정되어 이것은 채널의 우선 순위에 근거한다. 디폴트에서는, 채널은 인덱스값에 근거해 순위를 매기고 된다. 다만, 채널 10 은 MIDI 퍼크션 채널로, 우선 순위는 가장 높아진다.

어플리케이션 및 신디사이저에서는, 독자적으로 채널의 우선 순위를 설정할 수 있다. 상세한 것에 대하여는,IDirectMusicPort8::GetChannelPriority 의 「주의」를 참조할것. 「DMUS_CHANNEL_PRIORITY_PMSG 」도 참조할것.


메세지의 생성과 전달

세그먼트(segment)가 연주되고 있는 경우, 대부분의 트럭은, 재생중에 발생하는 이벤트에 관한 정보를 포함한 메세지를 생성한다. 상세한 것에 대하여는, 「DirectMusic 트럭」을 참조할것.

여러종류의 메세지를 송신하는 트럭도 있다. 예를 들어, 스타일 트럭은 노트 메세지와 박자 기호 메세지를 송신한다. 이러한 경우, 어플리케이션은 트럭의 특정의 종류의 메세지를 무효로 할 수 있다. 상세한 것에 대하여는, 「트럭 파라미터의 무효화와 유효화」를 참조할것.

퍼포먼스 엔진은, 각 메세지를 클락 타임에 언제 처리할까를 결정한다. 채널 메세지의 경우, 퍼포먼스는 메세지를 취득하는 퍼포먼스 채널도 결정한다. 이 정보는, 메세지 타입, 소스 트럭, 메세지를 수신하는 최초의 툴 그래프와 툴에의 포인터등을 보관 유지하는 것 외의 데이터와 함께, 메세지 구조체에 보존된다.

템포나 박자 기호의 변경등의 특정의 메세지는, 퍼포먼스에 의해 즉시 처리되어 해방된다. 노트나 패치의 변경 등, 그 외의 메세지는 큐에 넣어져 타임 스탬프의 순서에 처리된다.

주 같은 타임 스탬프의 메세지가 특정의 순서로 처리된다고 하는 보증은 없다.

박자 기호 메세지는 순수한 정보이다. 박자 기호는 세그먼트(segment)에 짜넣어져 변경할 수 없다.

메세지는, 최초로 세그먼트(segment) 툴 그래프내의 툴, 다음에 오디오 파스퇴르 그래프내의 툴, 마지막에 퍼포먼스 툴 그래프내의 툴에 송신된다.

세그먼트(segment) 툴 그래프와 퍼포먼스 툴 그래프를 생성 해, 툴을 정의하는 것은 어플리케이션의 역할이다. 툴 그래프의 생성의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • IDirectMusicGraph8
  • IDirectMusicPerformance8::SetGraph
  • IDirectMusicSegment8::SetGraph

오디오 파스퇴르 그래프는, DirectMusic Producer 파일에 포함되는 오디오 패스 구성의 옵션 컴퍼넌트이다. 어플리케이션에서는, 오디오 패스의 생성 후, 오디오 파스퇴르 그래프의 이행과 관계될 필요는 없다.

툴 그래프내의 최초의 툴은 메세지를 처리해, 그 메세지를 다른 툴에 건네주고 싶은 경우는, 다음의 툴에의 포인터와 함께 그 메세지를 툴 그래프에 스탬프 처리시킨다.

이 시점에서, 툴 그래프는 메세지에 전달 타입의 플래그를 할당한다. 이 플래그에 근거해, 메세지를 다음의 툴에 전달하는 시기가 정해진다. 이 플래그는, 툴로 예기 되고 있는, 다음과 같은 전달 타입에 근거하고 있다.

  • 메세지에 DMUS_PMSGF_TOOL_IMMEDIATE 플래그를 할당할 수 있고 있는 경우, 즉석에서 다음의 툴에 전달된다.
  • DMUS_PMSGF_TOOL_QUEUE 플래그를 할당할 수 있고 있는 메세지는, 지연 시간을 고려에 넣은 다음, 연주되면(자) 상정되는 시기의 직전에 전달된다 ( 「지연 시간과 범퍼 시간」을 참조할것).
  • 메세지에 DMUS_PMSGF_TOOL_ATTIME 플래그를 할당할 수 있고 있는 경우, 처리되는 것과 완전히 같은 시기에 전달된다. 통지의 처리에는, 거의 또는 전혀 지연 시간이 발생하지 않기 때문에, 통지 메세지에는 이 플래그를 할당할 수 있다.

툴 그래프가 메세지의 스탬프 처리와 플래그 할당을 실시한 다음에, 현재의 툴은 전달 타입을 변경할 수가 있다.

최종적으로, 메세지는 파기되지 않는 이상 DirectMusic 의 출력 툴에 도달한다. 이 툴은 받은 모든 메세지를 스탠다드 MIDI 메세지로 변환해, 그것들을 포토 버퍼 경유로 신디사이저에 전달한다.

해설에 대해서는, 「오디오 데이터의 흐름의 개요」를 참조할것.


어플리케이션으로 생성 된 메세지

대부분의 메세지는 트럭에 의해 생성되지만, 어플리케이션으로 직접 메세지를 큐에 배치할 수 있다. 예를 들어, 템포를 변경하거나DLS 음색으로 노트로서 사운드 이펙트를 연주하는 경우에, 이 처리를 실시한다.

상세와 샘플 코드에 대해서는, 「IDirectMusicPerformance8::SendPMsg 」를 참조할것.

퍼포먼스가 복수의 오디오 패스를 가지는 경우, DirectMusic 는 어플리케이션이 생성 한 메세지를 올바르고 루팅 할 수 없는 경우가 있다. 이것은, 새로운 메세지가 속하는 오디오 패스에 관한 정보가 메세지에 포함되지 않기 때문에이다. 채널 고유의 메세지가, 다른 세그먼트(segment)가 다른 오디오 패스에 맵 되는 퍼포먼스 채널에 속하는 경우도 있다.

메세지가 특정의 오디오 패스에 송신되도록(듯이) 하려면 , 우선 IDirectMusicSegmentState8::GetObjectInPath 또는 IDirectMusicAudioPath8::GetObjectInPath 를 호출해, 오디오 패스의 DMUS_PATH_AUDIOPATH_GRAPH 또는 DMUS_PATH_SEGMENT_GRAPH 스테이지로부터 IDirectMusicGraph8 인터페이스를 취득해, 세그먼트(segment) 또는 오디오 패스의 툴 그래프를 취득한다. 다음에, 메세지를 IDirectMusicGraph8::StampPMsg 에 건네준다.


퍼포먼스 메세지의 타입

메세지는,DMUS_PMSG 로부터 파생한 다양한 타입에 보존된다. C 는 계승을 지원 하고 있지 않기 때문에,DMUS_PMSG 의 멤버는 DMUS_PMSG_PART 매크로내의 각 메세지 타입의 선언에 포함되어 있다. 이러한 멤버는, 메세지 타입, 타임 스탬프, 메세지 송신지의 퍼포먼스 채널, 메세지 처리에 사용되는 다음의 툴 그래프와 툴을 포함한, 모든 메세지에 있어 공통의 데이터를 보관 유지하고 있다. 다른 멤버는, 메세지 타입 고유의 데이터를 보관 유지하고 있다.

다음의 표준적인 메세지 구조체가 정의되고 있다.

구조체 | 내용
DMUS_PMSG | 추가 파라미터가 없는 단순한 메세지. 「주의」를 참조할것.
DMUS_CHANNEL_PRIORITY_PMSG | 채널 우선 순위 변경. 「채널」을 참조할것.
DMUS_CURVE_PMSG | 커브 .
DMUS_LYRIC_PMSG | 텍스트.
DMUS_MIDI_PMSG | 고유의 메세지 타입을 가지지 않는 MIDI 메세지. 예를 들어, 컨트롤 체인지.
DMUS_NOTE_PMSG | 음악의 노트 (계속 시간을 포함한다. 따라서, MIDI 노트 온 및 노트 오프 메세지는, 이 스타일에 짜 합쳐진다).
DMUS_NOTIFICATION_PMSG | 통지. 「통지와 이벤트의 처리」를 참조할것.
DMUS_PATCH_PMSG | MIDI 패치의 변경.
DMUS_SYSEX_PMSG | MIDI 시스템에크스크루시브멧세이지.
DMUS_TEMPO_PMSG | 템포의 변경.
DMUS_TIMESIG_PMSG | 박자 기호의 변경.
DMUS_TRANSPOSE_PMSG | 전조.
DMUS_WAVE_PMSG | 웨이브의 재생.


커브

커브는, MIDI 콘트롤러의 일련의 변경으로 구성되어 값이 매끈매끈하게 트란지션 한다. 예를 들어, 볼륨의 용암 또는 용명이 있다.

DMUS_CURVE_PMSG 형의 1 개의 퍼포먼스 메세지를 송신하는 것에 의해 커브를 실행할 수 있다. 이 구조체를 사용 하면, 커브의 시작시와 종료시의 값, 기간, 및 형상을 설정할 수 있다. 옵션으로, 콘트롤러가 무효의 경우에 돌려주어지는 리셋값을 설정할 수도 있다.

이 메세지 구조체의 wMeasure,nOffset,bBeat,bGrid, 및 mtOriginalStart 멤버는, 정보 제공만을 목적으로 하고 있어 메세지의 타이밍에는 영향을 주지 않는다. 이것들은, DirectMusic Producer 세그먼트(segment)에 의해 송신된 메세지내로 설정되어 툴로 사용된다. 보통, 어플리케이션에서는 이러한 멤버를 0 으로 설정할 수 있다.

wMergeIndex 멤버는, 변경이 누적일까 오버라이드(override)인지를 나타낸다. 머지 인덱스가 다른 경우, 2 개의 커브 메세지는 누적된다. 머지 인덱스가 같은 경우는, 전의 메세지에 의한 설정이 새로운 메세지에 의해 차례차례 오버라이드(override) 된다.

bCCData 멤버는, 콘트롤러의 변경의 대상이 되는 MIDI 콘트롤러 번호를 포함해, 하늘의 경우는 무시된다. 콘트롤러 번호에 대해서는, MIDI 의 사양을 참조할것.

다음의 샘플 코드에서는, 현재의 값으로부터 볼륨을 내려 5 초 후에 0 이 되도록(듯이) 하고 있다. 이 시간내에, 현재 재생중의 세그먼트(segment)가 다른 세그먼트(segment)로 옮겨져 콘트롤러가 무효가 되었을 경우는, 최대 볼륨이 복원된다.

DMUS_CURVE_PMSG *pCurveMsg;
HRESULT hr = g_pPerf->AllocPMsg(sizeof(DMUS_CURVE_PMSG),
        (DMUS_PMSG**) &pCurveMsg);
ZeroMemory(pCurveMsg, sizeof(DMUS_CURVE_PMSG));

pCurveMsg->dwSize = sizeof(DMUS_CURVE_PMSG);
pCurveMsg->rtTime = 0;
pCurveMsg->dwFlags = DMUS_PMSGF_DX8 | DMUS_PMSGF_REFTIME
        | DMUS_PMSGF_LOCKTOREFTIME;
pCurveMsg->dwPChannel = DMUS_PCHANNEL_BROADCAST_PERFORMANCE;
pCurveMsg->dwType = DMUS_PMSGT_CURVE;
pCurveMsg->dwGroupID = 0xFFFFFFF;
pCurveMsg->mtDuration = 5000;
pCurveMsg->nEndValue = 0;
pCurveMsg->bCurveShape = DMUS_CURVES_LINEAR;
pCurveMsg->bCCData = 7;
pCurveMsg->bFlags = DMUS_CURVE_RESET | DMUS_CURVE_START_FROM_CURRENT;
pCurveMsg->bType = DMUS_CURVET_CCCURVE ;

pCurveMsg->mtResetDuration = 0;
pCurveMsg->nResetValue = 127;

g_pPerf->SendPMsg((DMUS_PMSG*) pCurveMsg);

주 보다 간단하게 볼륨의 페이드를 이행 하려면 ,IDirectMusicAudioPath8::SetVolume 를 사용한다. 이 메소드에서는, 항상, 커브에 평행한 셰이프를 사용한다.


MIDI 메세지

대부분의 어플리케이션은, MIDI 메세지를 직접 처리하지 않는다. 다만, 어플리케이션은 퍼포먼스 메세지로서 MIDI 커멘드를 송신해, 컨트롤 체인지등을 실시할 수가 있다.

MIDI 메세지는, 1 바이트의 스테이터스 바이트와 보통, 1 바이트나 2 바이트의 데이터 바이트에 의해 구성된다. 시스템에크스크루시브 MIDI 메세지는 가변장이다.

스테이터스 바이트는 메세지의 타입을 나타내, 일부의 상황에서는, 그 메세지를 받아들이는 채널을 나타낸다. 파일중에 같은 종류의 이벤트가 계속해 나타나는 경우는, 스테이터스 바이트를 생략 할 수 있다. 상위 비트가 항상 소거되고 있으므로, 데이터 바이트를 인식할 수 있다. 스테이터스 바이트의 상위 비트는, 항상 설정되어 있다.

MIDI 이벤트의 타이밍은, 각 메세지의 전에 있는 숫자로 제어된다. 이 값은, 이 이벤트와 마지막 이벤트의 간격을, 틱수로 나타내고 있다. 틱의 실제의 계속 시간은, 파일 헤더의 시간의 형식에 의해 결정된다.

주 MIDI 메세지가, 소스 데이터에 기술되고 있는 순서로 처리된다고 하는 보증은 없다. DirectMusic 메세지는 타임 스탬프의 순서에 전달된다. 타임이 동일한 MIDI 메세지가 2 개 있는 경우는, 예상과 다른 순서로 전달되는 경우가 있다. MIDI 컨텐츠를 오쏘링 할 경우에, 이벤트를 발생시키는 순서가 정해져 있는 경우는, 이벤트간에 간격을 넣도록(듯이) 주의할 필요가 있다. 예를 들어, 프로그램 체인지에 의존하는 노트가 있는 경우는, 이러한 노트와 프로그램 체인지를 동시에 배치하지 않는다.

MIDI 메세지는, 다음의 2 개의 주요한 카테고리로 분류할 수 있다.

  • MIDI 채널 메세지
  • MIDI 시스템 메세지


MIDI 채널 메세지

채널 메세지는, 음악의 1 개의 파트에 대응하는 특정의 MIDI 채널에 주소 지정된다.

채널 메세지는,모드 메시지나음성 메세지의 어느 쪽인지이다.

모드 메시지는, 채널이 그 이후의 음성 메세지를 취급하는 방법을 결정한다. 예를 들어, 모드 메시지는, 무엇인가 통지가 있을 때까지는 모든 노트 온 메세지를 무시해, 무음 상태를 유지하도록(듯이) 채널에 지시하는 일이 있다.

대부분의 채널 메세지는 음성 메세지이다. 이것들은 채널에 노트의 연주의 시작 또는 정지, 어떠한 방법에서의 노트의 변경을 지시해, 채널에 다른 MIDI 패치 번호를 할당하는 것으로 틴바를 변경한다.

다음의 표는, 음성 메세지의 종류를 나타내고 있다.

음성 메세지 | 목적
노트 온 | 노트를 연주한다.
노트 오프 | 노트의 연주를 정지한다.
컨트롤 체인지 | 페달, 레바, 그 외의 디바이스로부터의 데이터를 사용해 악음을 변경한다. 볼륨이나 뱅크 셀렉트 등, 다양한 컨트롤에도 사용된다.
프로그램 (패치) 체인지 | 패치 번호를 할당하는 것으로, 채널의 음색을 선택한다.
애프터 터치 | 키의 애프터 터치에 따라, 개별의 노트 또는 채널의 모든 노트를 변경한다.
핏치벤드첸지 | 채널로 연주되는 모든 노트의 피치를 변경한다.

이러한 설명은, 스탠다드 MIDI 메세지에 적용되어 퍼포먼스 메세지 형식에 변환된 MIDI 데이터에는 적용되지 않는 것에 주의한다. 예를 들어, 노트의 연주를 시작 및 정지하기 위한 2 개의 MIDI 메세지는, DirectMusic 에 의해, 노트의 계속 시간을 지정하는 1 개의 퍼포먼스 메세지에 결합된다. DirectMusic 메세지에는, 타이밍이나 루팅에 관한 많은 추가 정보도 함 기다릴 수 있는 넣는다.

MIDI 노트

노트 온 메세지의 데이터 바이트는, 피치와velocity를 나타낸다. 대부분의 경우, 피치의 값 (키 넘버) 0 은 2 옥타브하의 C 음 (MIDI 에서는 C0 와 표기)이며, 12 는 1 옥타브하의 C (MIDI 의 C1), 60 은 피아노로 말하는 중앙의 C (MIDI 의 C5)를 의미한다. 드럼 킷의 경우, 데이터 바이트는 특정의 드럼 사운드를 의미한다. 예를 들어, GM (General MIDI)의 퍼크션 키 맵에서는, 값 60 은 하이본고의 사운드를 의미한다. 채널 10 은 드럼 킷에 예약되고 있으므로, 신디사이저는 이 채널에서의 노트 온 메세지를 다른 채널과는 다른 방법으로 취급하는 것을 알고 있다.

DirectMusic 가 MIDI 노트를 변환하는 방법에 대해서는, 「뮤직값과 MIDI 노트」를 참조할것.

프로그램 체인지

프로그램 체인지와 패치 번호는, MIDI 재생과 DirectMusic 에 대해 중요한 개념이다. 프로그램 체인지는 특정의 음색 (프로그램 또는 틴바라고도 부른다)을 채널에 할당하므로, 채널에 송신된 노트는 적절한 사운드로 연주된다. 음색은 패치 번호에 의해 식별된다. GM 음색 세트를 로드하는 경우, 패치 번호 1 을 지정하는 프로그램 체인지에서는, 채널은 반드시 어쿼스틱 그랜드 피아노의 노트로 연주된다. 스피커로 생성되는 실제의 사운드는, 음색의 합성 방법으로 의존한다.

뱅크 셀렉트

프로그램 체인지 시에 1 바이트의 데이터 바이트를 사용해 패치 번호를 선택하고 있지만, MIDI 메세지의 각 데이터 바이트로 유효한 것은 7 비트 뿐이므로, 프로그램 체인지에서는 최대 128 의 음색을 선택할 수가 있다. 보다 많은 선택사항을 제공하기 위해서, MIDI 규격에서는 최대 16,384 의 음색 뱅크의 사용이 인정되어 각 뱅크에 최대 128 의 음색을 포함할 수가 있다.

다른 뱅크로부터 음색을 선택하려면 , MIDI 시퀀서는 최초로뱅크 셀렉트로 불리는 컨트롤 체인지 메세지를 송신해야 한다. 이 메세지의 데이터 바이트중 2 바이트를, 최상정도 바이트 (MSB) 및 최하정도 바이트 (LSB)라고 불러, 이것들을 조합해 뱅크를 식별한다. 뱅크를 선택한 후, 그 이후의 프로그램 체인지에서는 그 뱅크로부터 음색이 선택된다.

DirectMusic 패치 번호

MIDI 가 정하는 7 비트 패치 번호와는 달라, DirectMusic 의 음색 패치 번호는 32 비트값이며, 그 중에 MIDI 패치 번호, 뱅크 셀렉트의 MSB 와 LSB, 및 드럼 킷용의 1 비트 플래그가 포함되어 있다. IDirectMusicCollection8::EnumInstrument ,IDirectMusicCollection8::GetInstrument , 및 IDirectMusicInstrument8::GetPatch 의 각 메소드는, 이 확장 번호를 돌려준다. IDirectMusicInstrument8::SetPatch 메소드를 사용하면(자), 음색을 변경할 수 있다.

DirectMusic 에서의 패치의 값을 집계한 것을 이하에 나타낸다.

비트 | 목적
0-7 | MIDI 패치 번호 (비트 7 은 항상 0)
8-15 | LSB 뱅크 셀렉트 (비트 15 는 항상 0)
16-23 | MSB 뱅크 셀렉트 (비트 23 은 항상 0)
24-30 | 미사용
31 | 드럼 킷용의 플래그


MIDI 시스템 메세지

시스템 메세지는, 어느 채널에 있어서도 배타적이지 않다. 이것들은 다음 표와 같이 3 종류로 분류된다.

메세지 타입 | 목적
시스템 공통 | 다양한 커멘드와 데이터
시스템에크스크루시브 | 기기 고유의 커멘드와 데이터
시스템 리얼타임 | 클락 베이스의 MIDI 기기의 동기화

다른 MIDI 메세지와는 달라, 시스템에크스크루시브멧세이지는 임의의 길이의 데이터 바이트를 보관 유지할 수 있다. 데이터를 송신한 다음에, 시퀀서는 EOX 로 불리는 시스템 공통 메세지를 송신해, 시스템에크스크루시브멧세이지의 마지막을 알린다.

DirectMusic 에서는,DMUS_SYSEX_PMSG 구조체가, 데이터 길이와 데이터 바이트의 배열에의 포인터를 보관 유지한다.


DirectMusic 포토의 사용법

여기에서는, 오디오 패스를 사용하지 않는 어플리케이션에 의한 DirectMusic 포토에의 액세스에 대해 설명한다. 추천 되고 있도록(듯이), 어플리케이션이 IDirectMusicPerformance8::InitAudio 를 사용해 퍼포먼스를 초기화하는 경우, 오디오 패스에 의해, 포토 및 퍼포먼스 채널의 포토에의 매핑이 관리된다.

포토는, 데이터의 송신 또는 수신을 실시하는 디바이스이다. 하드웨어 디바이스, 소프트웨어 신디사이저, 소프트웨어 필터의 어느쪽이든을 나타낸다.

DirectMusic 어플리케이션내의 각 포토는,IDirectMusicPort8 인터페이스에 의해 나타내진다. 이 인터페이스의 메소드를 사용해, 디바이스에 관한 정보의 취득, 디바이스내의 메모리의 관리,DLS 음색의 다운로드와 언로드, 유입 데이터의 읽어들여, 재생 버퍼의 삽입을 실시한다.

어느 퍼포먼스도 적어도 1 개의 포토를 갖추지 않으면 안 된다. 디폴트 포토 이외의 포토를 사용하는 경우나, 디폴트 포토의 특별한 파라미터를 설정하는 경우는, 우선 DMUS_PORTPARAMS8 구조체를 설정한다. 모든 멤버에 값을 입력할 필요는 없지만,dwValidParams 멤버에 적절한 플래그를 기입하는 것으로, 어느 멤버가 유효한 정보를 가지고 있는지 DirectMusic 에 알리지 않으면 안 된다. 다음에, 이 구조체를 IDirectMusic8::CreatePort 메소드에 건네준다.

다음의 C++ 샘플 코드에서는, 디폴트의 출력 포토용의 오브젝트를 생성 해, 포토에 5 개의 채널 그룹을 설정하는 방법을 나타내고 있다. pDirectMusic 은 유효한 IDirectMusic8 인터페이스 포인터이라고 가정한다.

IDirectMusicPort8*  pPort;
DMUS_PORTPARAMS    dmos;

ZeroMemory( &dmos, sizeof(DMUS_PORTPARAMS) );
dmos.dwSize = sizeof(DMUS_PORTPARAMS);
dmos.dwValidParams = DMUS_PORTPARAMS_CHANNELGROUPS;
dmos.dwChannelGroups = 5;
HRESULT hr = pDirectMusic->CreatePort( GUID_NULL, &dmos,
        &pPort, NULL )

설정한 포토는 IDirectMusic8::Activate 또는 IDirectMusicPort8::Activate 를 호출해 액티브하게 해,IDirectMusicPerformance8::AddPort 메소드를 사용해 퍼포먼스에 부가한다.

포토를 퍼포먼스에 부가할 경우에,IDirectMusicPerformance8::AssignPChannelBlock 메소드를 호출해,P 채널의 블록을 할당한다. IDirectMusicPerformance8::AddPort 에 NULL 를 건네주어 디폴트 포토를 추가 하면나무만, 이 처리는 필요없다. 이 경우, P 채널 0-15 은, 포토의 최초의 그룹의 MIDI 채널에 할당할 수 있다.

IDirectMusicPerformance8::AssignPChannelBlock 및 IDirectMusicPerformance8::AssignPChannel 의 각 메소드를 사용하면(자), 이러한 P 채널을 다른 방법으로 할당해 다른 P 채널을 추가해, P 채널을 다른 포토에 할당할 수가 있다.

포토의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 디폴트 포토
  • DirectMusic 포토의 프로퍼티 세트


디폴트 포토

Windows® 95, 및 Windows 98 Second Edition 이전의 Windows 98 에 대해, 또는 DLS 를 지원 하는 하드웨어를 이용할 수 없는 경우는, Microsoft 의 소프트웨어 신디사이저가 디폴트 포토가 된다. Windows 98 Second Edition 이후, 및 Windows 2000 에서는, 하드웨어 신디사이저가 디폴트 포토가 되는 경우도 있다.

어플리케이션으로 디폴트 포토를 사용하는 경우, 퍼포먼스에 포토를 추가하기 전에 IDirectMusic8::CreatePort 메소드를 호출할 필요는 없다. 대신에,IDirectMusicPerformance8::AddPort 에 NULL 를 건네줄 수가 있다.

IDirectMusic8::GetDefaultPort 를 호출해 디폴트 포토를 취득해, 계속되어 IDirectMusicPort8::GetCaps 메소드를 사용해 능력을 확인할 수 있다. 포토가 어플리케이션의 요구에 적합하지 않는 경우는,IDirectMusic8::EnumPort 메소드를 사용해, Microsoft 의 소프트웨어 신디사이저나 그 외의 포토를 검색한다.


커스텀 로드

특수한 어플리케이션에서는, 파일이나 리소스로부터의 데이터를 캡슐화하는, 독자적인 오브젝트 타입을 생성 할 수 있다. DirectMusic 로더에, 이러한 오브젝트의 로드를 처리시키면(자) 편리하다. 커스텀 오브젝트가 다른 오브젝트로부터 참조되고 있는 경우나, 커스텀 오브젝트에 다른 오브젝트에의 참조가 포함되어 있는 경우에, 특히 편리하다.

DirectMusic 로더를 이용하는 로드 메카니즘을 이행 하려면 , 다음의 순서를 실행한다.

  • IDirectMusicLoader8::GetObject 로 검색되도록(듯이), 오브젝트 클래스를 등록한다.
  • 오브젝트를 검색 및 캐싱 하기 위해서 필요한 정보를 로더를 취득할 수 있도록(듯이), 오브젝트에 IDirectMusicObject8 인터페이스를 이행 한다.
  • 오브젝트에 IPersistStream 인터페이스를 이행 해,IPersistStream::Load 메소드의 기능을 모두 사용할 수 있도록(듯이) 한다. 이것에 의해, DirectMusic 로더에 의해 건네받은,IStream 인터페이스 위에의 호출을 통해 취득한 데이터를 해석할 수가 있다.
  • Load 의 이행에 대해,IDirectMusicGetLoader8 인터페이스에 대해서 IStream 를 조회해, 다음에 IDirectMusicGetLoader8::GetLoader 를 호출해, 스트림을 생성 한 DirectMusicLoader 에의 포인터를 취득하는 것으로, 다른 오브젝트에의 참조가 처리되고 있는 것을 확인한다. 이 포인터를 취득하면(자),IDirectMusicLoader8::GetObject 를 호출해, 새로운 오브젝트를 로드할 수 있다.

어플리케이션이, 파일 입력 그 자체를 관리해야 하는 경우도 있다. 예를 들어, 모든 오브젝트가, 특수한 압축 리소스 파일에 저장 되고 있는 경우 등이다. 어플리케이션은,IDirectMusicLoader8 인터페이스를 지원 하는 오브젝트를 생성 해,IDirectMusicLoader8::GetObject 메소드를 이행 해, 독자적인 로더를 생성 할 수가 있다. 다른 메소드는 모두 옵션이다. 또, 로더의 이 이행은,IStream 및 IDirectMusicGetLoader8 인터페이스의 양쪽 모두를 가지는 독자적인 스트림 오브젝트를 생성 해야 한다.


음색 콜렉션의 사용법

대부분의 어플리케이션에서는,DLS 음색 데이터는 밴드에 관련지을 수 있어 밴드가 다운로드되었을 때에 신디사이저에 다운로드된다. 상세한 것에 대하여는, 「밴드의 사용법」을 참조할것.

독자적인 DLS 관리를 실시하는 특별한 DirectMusic 어플리케이션에서는, 2 개의 스텝을 실시해야 한다. 최초로 음색 콜렉션을 로드해, 다음에 음색 데이터를 포토에 다운로드한다.

다음의 주제로, 이러한 스텝에 대해 설명한다.

  • 콜렉션의 로드와 다운로드
  • 음색의 조작

음색과 콜렉션을 편집하는 어플리케이션에서는, 보다 낮은 레벨에서도 DLS 데이터를 조작할 필요가 있다. 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 하위 레벨 DLS


콜렉션의 로드와 다운로드

콜렉션은, 다른 오브젝트와 같게 로드 된다. 상세한 것에 대하여는, 「오디오 데이터의 로드」를 참조할것.

표준적인 GM/GS 세트를 로드하기 위해서(때문에),DMUS_OBJECTDESC 구조체의 guidObject 멤버에, 로더에의 패스 GUID_DefaultGMCollection 를 설정한다. 로더를 사용해 이 오브젝트에 몇번이나 액세스 하는 경우는, 캐싱이 유효하게 되어 있는 것을 확인해 (디폴트의 설정), GM 콜렉션을 요구할 때마다 카피가 1 개 생성 되는 것을 방지한다.

주 GM/GS Sound Set 를 변경할 수 없다. 상세한 것에 대하여는, 「법적 정보」의 「저작권에 관한 주의」를 참조할것.

다음의 샘플 코드는, GUID 에 의해 식별되는 콜렉션을 로드하는 방법을 나타내고 있다.

HRESULT myGetGMCollection(
        IDirectMusicLoader8 *pILoader,
        IDirectMusicCollection8 **ppICollection)
{
    HRESULT hr;
    DMUS_OBJECTDESC desc;

    desc.dwSize = sizeof(DMUS_OBJECTDESC);
    desc.guidClass = CLSID_DirectMusicCollection;
    desc.guidObject = GUID_DefaultGMCollection;
    desc.dwValidData = (DMUS_OBJ_CLASS | DMUS_OBJ_OBJECT);
    hr = pILoader->GetObject(&desc, IID_IDirectMusicCollection8,
            (void **) ppICollection);
    return hr;
}

IDirectMusicCollection8 인터페이스에의 포인터를 취득 하면, 콜렉션내의 모든 음색에 액세스 할 수 있다. 다만, 이 시점에서는, 음색은 포토에 다운로드되어 있지 않다.

콜렉션 전체를 한 번에 다운로드하려면 , 콜렉션을 세그먼트(segment)에 관련지어,IDirectMusicSegment8::Download 메소드를 호출한다. 예에 대해서는, 「커스텀 음색에 의한 MIDI 파일의 연주」를 참조할것.

이러한 순서는, 디폴트 이외의 콜렉션을 사용하는 경우에게만 필요하다. 세그먼트(segment)가 콜렉션을 참조하지 않는 경우, 보통은 IDirectMusicSegment8::Download 를 호출하면나무에, 세그먼트(segment)중에 오쏘링 된 디폴트 콜렉션의 음색, 또는 General MIDI 세트의 음색이 포토에 다운로드된다. 밴드를 다운로드할 경우에, 그 밴드의 음색으로 필요한 모든 DLS 데이터가 다운로드된다. 「밴드의 사용법」을 참조할것.


음색의 조작

콜렉션 오브젝트를 생성 하거나 콜렉션 파일이나 리소스로부터 로드했을 경우, 음색은 특정의 포토에 바인드 되지 않는다. 다른 음색을 다른 포토에 다운로드하는 일도, 1 개의 음색을 복수의 포토에 다운로드할 수도 있다.

IDirectMusicCollection8::EnumInstrument 메소드를 사용해, 이용 가능한 모든 음색의 패치 번호 및 이름을 취득할 수 있다.

다음의 샘플 코드는, 콜렉션내의 모든 음색을 열거해, 그 이름과 패치 번호를 표시하고 있다.

void myListInstruments(
        IDirectMusicCollection8 *pCollection)

{
    HRESULT hr = S_OK;
    DWORD dwPatch;
    WCHAR wszName[MAX_PATH];
    DWORD dwIndex;
    for (dwIndex = 0; hr == S_OK; dwIndex++)
    {
        hr = pCollection->EnumInstrument(
                dwIndex, &dwPatch, wszName, MAX_PATH);
        if (hr == S_OK)
        {
           printf("Patch %lx is %S\n", dwPatch, wszName);
        }
    }
}

IDirectMusicCollection8::GetInstrument 메소드에 특정의 음색의 패치 번호를 건네주어, 특정의 음색에의 포인터를 취득한다.

음색을 취득한 후,IDirectMusicInstrument8::SetPatch 메소드를 사용해 패치 번호를 변경할 수 있다.

단일의 음색을 포토에 다운로드하려면 ,IDirectMusicInstrument8 인터페이스 포인터를 IDirectMusicPort8::DownloadInstrument 또는 IDirectMusicPerformance8::DownloadInstrument 메소드에 건네준다. 이 호출은, 포토로 DLS 데이터를 이용 가능하게 한다. 음색을 특정의 퍼포먼스나 오디오 패스에 관련지을 것은 없다.

메모리를 절약하기 위해서, 지정된 노트의 범위에서 필요한 웨이브와 아티큘레이션만이 다운로드된다. 예를 들어, 바순을 사용하는 경우, 저음의 C 로부터 중간의 B 까지의 노트 범위에 상당하는 데이터만을 다운로드하도록(듯이) 지정하는 일이 있다. 이 범위 이외의리젼의 데이터는 다운로드되지 않는다.

다음의 샘플 코드에서는, 지정된 콜렉션, 패치 번호, 포토, 및 노트 범위에 대해서, 콜렉션으로부터 음색을 취득해, 그 음색을 다운로드하고 있다. 이 함수는, 1 개의 DMUS_NOTERANGE 구조체로부터 완성되는 배열을 생성 해, 이 배열을 IDirectMusicPort8::DownloadInstrument 메소드에 건네준다. 일반적으로는, 노트의 1 개의 범위만을 지정하지만, 복수의 범위를 지정할 수도 있다. 배열 대신에 NULL 를 건네주면(자), 모든 범위의 데이터가 다운로드된다.

HRESULT myDownload(
    IDirectMusicCollection8 *pCollection,    // DLS 콜렉션
    IDirectMusicPort8 *pPort,                // 전송처 포토
    IDirectMusicDownloadedInstrument8 **ppDLInstrument,
    DWORD dwPatch,                          // 요구된 음색
    DWORD dwLowNote,                        // 범위내의 낮은 노트
    DWORD dwHighNote)                       // 범위내의 비싼 노트

{
    HRESULT hr;
    IDirectMusicInstrument8* pInstrument;
    hr = pCollection->GetInstrument(dwPatch, &pInstrument);
    if (SUCCEEDED(hr))
    {
        DMUS_NOTERANGE NoteRange[1];         // 옵션의 노트 범위
        NoteRange[0]. dwLowNote = dwLowNote;
        NoteRange[0]. dwHighNote = dwHighNote;
        hr = pPort->DownloadInstrument(pInstrument,
                ppDLInstrument,
                NoteRange,   // 범위의 배열
                1);          // 배열내의 요소의 수
        pInstrument->Release();
    }
    return hr;
}

DownloadInstrument 메소드는,IDirectMusicDownloadedInstrument8 인터페이스에의 포인터를 돌려준다. 이 포인터의 목적은, 그 이후에 IDirectMusicPort8::UnloadInstrument 메소드를 호출하면나무에 음색을 식별하는 것 뿐이어서, 이 메소드는 특정의 포토로부터 음색 인스턴스를 언로드한다.

다음의 함수에서는, 음색을 다운로드한 후, 언로드하고 있다. 이 예는,IDirectMusicDownloadedInstrument8 포인터의 사용 방법을 나타낼 뿐(만큼)의 것이다.

HRESULT myFickleDownload(
        IDirectMusicInstrument8* pInstrument,
        IDirectMusicPort8 *pPort,
        DWORD dwPatch)

{
    HRESULT hr;
    IDirectMusicDownloadedInstrument * pDLInstrument;
    hr = pPort->DownloadInstrument(
            pInstrument, &pDLInstrument,
            NULL, 0);
    if (SUCCEEDED(hr))
    {
        pPort->UnloadInstrument(pDLInstrument);
        pDLInstrument->Release();
    }
    return hr;
}


하위 레벨 DLS

DLS 콜렉션을 편집하는 어플리케이션을 생성 하고 있는 경우는, DirectMusic 음색 오브젝트에 캡슐화하는 일 없이, 음색 데이터를 신디사이저에 다운로드할 수 있을 필요가 있다.

DLS 데이터를 조작하려면 , DLS 의 사양 및 파일 구조에 대한 지식이 필요하다. 이러한 정보의 상세한 것에 대하여는, MIDI Manufactures Association 에 문의하는 것.

미가공의 음색 데이터를 다운로드하려면 , 최초로, 다음의 샘플 코드와 같이 IDirectMusicPortDownload8 인터페이스에의 포인터를 취득할 필요가 있다. 여기에서는,pIPort 가 IDirectMusicPort8 인터페이스에의 유효한 포인터인 것을 상정하고 있다.

IDirectMusicPortDownload **ppIDownloadPort;

HRESULT hr = pIPort->QueryInterface(IID_IDirectMusicPortDownload8,
        (void **) ppIDownloadPort);

HRESULT 가 S_OK 가 아닌 경우, 그 포토는 DLS 의 다운로드를 지원 하고 있지 않다.

다음에, 준비 및 다운로드해야 하는 버퍼를 식별한다. 음색을 신디사이저에 송신하려면 , 음색 전체의 정의를 나타내, 모든 리젼과 아티큘레이션을 갖춘 1 개의 음색 버퍼와 일련의 웨이브 버퍼를 생성 한다. 음색이 리젼용으로 참조하는 1 개의 웨이브에 대해, 1 개의 웨이브 버퍼를 생성 한다.

각 버퍼에는, 고유의 식별자를 붙이지 않으면 안 된다. 이러한 식별자를 사용해 버퍼간의 링크, 특히 리젼과 웨이브의 링크를 해결한다. 다운로드할 필요가 있는 버퍼수를 집계해,IDirectMusicPortDownload8::GetDLId 를 호출해, 식별자의 범위를 할당한다. 예를 들어, 1 개의 음색을 3 개의 웨이브와 함께 다운로드하는 경우, 전부 4 개의 버퍼를 다운로드해야 하기 때문에, 4 개의 식별자를 요구한다.

버퍼 마다 필요한 사이즈를 계산해, 다음에 IDirectMusicPortDownload8::AllocateBuffer 를 호출해 그 사이즈를 할당한다. 이 메소드는, 버퍼를 나타내는 IDirectMusicDownload8 인터페이스를 돌려준다. 메모리에 액세스 하려면 ,IDirectMusicDownload8::GetBuffer 를 호출한다.

주 GetBuffer 메소드는 2 개 있다.

IDirectMusicPortDownload8::GetBuffer 는, 다운로드 식별자가 기존의 버퍼 오브젝트에 대한 IDirectMusicDownload 인터페이스 포인터를 돌려준다.

IDirectMusicDownload::GetBuffer 는, 버퍼의 메모리에의 포인터를 돌려준다.

이번은 데이터를 버퍼에 기입한다. 각 버퍼는 DMUS_DOWNLOADINFO 구조체에 의해 지정된 장소에서 시작된다. 이 구조체는, 사이즈와 다운로드의 기능을 정의한다. 이 구조체는, 다음의 방법으로 준비해야 한다.

  • dwDLType 멤버를, 음색의 경우는 DMUS_DOWNLOADINFO_INSTRUMENT2 에, 웨이브의 경우는 DMUS_DOWNLOADINFO_WAVE 로 설정한다.
  • dwDLId 멤버를,IDirectMusicPortDownload::GetDLId 를 실행해 취득한, 고유의 식별자의 어느 쪽인가에 설정한다.
  • dwNumOffsetTableEntries 멤버를,DMUS_OFFSETTABLE 구조 체내의 엔트리수로 설정한다.
  • cbSize 멤버를,DMUS_DOWNLOADINFO 및 DMUS_OFFSETTABLE 를 포함한, 다운로드체크의 사이즈로 설정한다.

DMUS_DOWNLOADINFO 구조체는, 항상 DMUS_OFFSETTABLE 구조체에 따른다. 이 오프셋(offset) 테이블을 사용해, 데이터내의 모든 링크를 관리한다. 데이터내의 구조체가 다른 구조체를 참조하는 경우는 언제라도, 포인터는 아니고 정수의 인덱스 번호를 사용한다. 데이터내에 있는 참조 가능한 모든 구조체에는, 일의의 인덱스 번호를 할당할 수 있고 있다. DMUS_OFFSETTABLE 는, 이 정수 인덱스 번호를 데이터내의 바이트 오프셋(offset)에 평행이동 한다.

음색 데이터 또는 웨이브 데이터는,DMUS_OFFSETTABLE 에 따른다. 음색을 다운로드하는 경우는,DMUS_INSTRUMENT 구조체로 지정된 장소로부터 데이터가 시작된다. 그 이외의 것을 다운로드하는 경우는,DMUS_WAVE 구조체로 지정된 장소로부터 데이터가 시작된다.

DMUS_INSTRUMENT 구조체에 따르는 음색 데이터는, 다음의 구조체로 구성된다.

  • DMUS_ARTICPARAMS
  • DMUS_ARTICULATION
  • DMUS_ARTICULATION2
  • DMUS_COPYRIGHT
  • DMUS_EXTENSIONCHUNK
  • DMUS_INSTRUMENT
  • DMUS_NOTERANGE
  • DMUS_REGION

DMUS_WAVE 구조체로 나타나는 웨이브 데이터는,DMUS_WAVEDATA 구조체로 구성된다.

버퍼 모든 것이 준비 되어 있는 경우,IDirectMusicPortDownload8::Download 를 사용해 그것들을 다운로드한다. 최초로 웨이브 버퍼를 다운로드하는 것. 그 결과 웨이브 버퍼가 적절한 장소에 배치되어 음색을 다운로드할 경우에 참조할 수 있다.

버퍼를 다운로드 하면, 신디사이저는 음색을 연주할 수 있는 상태가 된다. 버퍼를 다운로드한 후, 그 버퍼로 사용되고 있는 메모리에는 액세스 할 수 없게 된다.

그 후, 음색의 연주가 종료하면(자), 버퍼의 언로드와 해방을 실시한다. 최초로 음색 버퍼를 언로드해, 다음에 모든 웨이브 버퍼를 언로드한다. 언로드하려면 ,IDirectMusicDownload8 포인터를 IDirectMusicPortDownload8::Unload 에 건네준다. 다음에,IDirectMusicDownload8:: Release 를 호출해, 각 버퍼를 해방한다.

이미 다운로드되고 있는 음색을 갱신하는 경우, 다운로드 끝난 버퍼의 덧쓰기는 할 수 없다. 대신에, 웨이브는 아니고 음색을 옮겨놓는다. 음색을 옮겨놓으려면 ,IDirectMusicPortDownload8::AllocateBuffer 를 호출해, 적절한 버퍼 사이즈를 지정해 새로운 IDirectMusicDownload8 인터페이스를 할당한다. IDirectMusicPortDownload8::GetDLId 를 호출해, 버퍼의 새로운 식별자를 생성하는 것. 새로운 아티큘레이션 정보를 버퍼에 기입해, 다음에 버퍼를 다운로드한다. 다음에,IDirectMusicPortDownload8::Unload 를 호출해, 이전에 다운로드되고 있던 버퍼를 언로드한다.

웨이브 버퍼를 갱신하는 경우는, 이제(벌써) 1 개(살) 스텝이 증가한다. 새로운 웨이브 버퍼와 그 버퍼를 참조하는 갱신된 음색 버퍼의 2 개를 생성 한다. 새로운 웨이브 버퍼, 그 다음에 새로운 음색 버퍼를 다운로드한다. 한층 더 낡은 음색 버퍼, 그 다음에 낡은 웨이브 버퍼를 언로드한다.


DirectMusic 툴

툴이란, 메세지를 도중에 취득해, 어떠한 방법으로 처리하는 오브젝트를 의미한다. 툴은 메세지로 변경을 더해 다음의 툴에 건네주는지, 메세지를 해방하는지, 원의 메세지내의 정보에 근거해 새로운 메세지를 송신하는지, 몇개의 방법으로 처리를 실시할 수가 있다.

DirectMusic 에는 출력 툴이 있어, 보통은 이 툴이 마지막에 메세지를 받아들인다. 이 툴은, 퍼포먼스 메세지를 스탠다드 MIDI 메세지로 변환해, 신디사이저에의 스트림에 넣는다. 다른 툴은, 어플리케이션에 의해 이행 하는지, 라이브러리로부터 취득한다.

툴을 이행 하려면 ,IDirectMusicTool8 인터페이스를 지원 하는 오브젝트를 생성 해야 한다. IDirectMusicTool8 메소드의 오브젝트 이행에 의해, 이 툴이 어느 메세지를 취득하는지, 및 그 메세지에 어떠한 작업을 실시할까를 결정한다.

출력 툴 이외의 모든 툴은, 툴 그래프에 정리한다. 어플리케이션이 다른 툴을 1 개 밖에 사용하지 않는 경우에서도, 그 툴을 포함한 툴 그래프를 생성 해야 한다. 다음에, 그 툴 그래프를 세그먼트(segment)나 퍼포먼스에 추가한다. 툴 그래프는, 툴간에 메세지를 전송 할 때에 유효한 메카니즘이다.

퍼포먼스 엔진이 세그먼트(segment)를 연주할 경우에, 세그먼트(segment) 툴 그래프내의 각 툴, 그 다음에 퍼포먼스 툴 그래프내의 각 툴이, 각 메세지를 처리할 수 있다. 어느 툴이 메세지를 처리한 후, 그 툴은 DMUS_PMSG 구조체의 pGraph 멤버로부터 IDirectMusicGraph8 포인터를 취득해, 다음에 그 메세지를 받아들이는 툴이 있는 경우는,IDirectMusicGraph8::StampPMsg 메소드를 호출해 그 툴에의 포인터를 메세지에 스탬프 한다.

툴은, 우선 순위의 높은 thread로 메세지를 처리한다. 툴의 IDirectMusicTool8::ProcessPMsg 메소드내에서는, 그래픽스나 파일 입출력등을 실시하는 시간이 걸리는 함수를 호출하지 않게 한다. 툴이 액션을 방아쇠 할 필요가 있는 경우는, 어플리케이션의 메인 thread등의 다른 thread에 통지해 실행한다.

IDirectMusicTool8 의 메소드를 이행 할 경우에, 친오브젝트에의 순환 참조를 생성 하지 않게 주의한다. 순환 참조는, 어느 오브젝트가 다른 오브젝트를 생성 했을 때에, 아이 오브젝트가 친오브젝트에의 참조를 유지하고 있는 경우에 발생한다. 예를 들어, 툴이,IDirectMusicTool8::Init 메소드에게 건네지는, 툴 그래프에의 새로운 참조를 생성 하는 경우를 생각한다. 툴이 이 참조를 해방할 수 없는 경우, 세그먼트(segment)가 툴 그래프를 해방하려고 했을 때에 문제가 발생한다. 툴에는 툴 그래프에의 참조가 남아 있기 (위해)때문에, 툴 그래프가 완전하게 해방되지 않는다. 또, 툴 그래프에는 툴에의 참조가 있기 (위해)때문에, 툴도 해방되지 않는다.

툴의 이행 방법의 예에 대해서는, 「MusicTool 샘플 어플리케이션」을 참조할것.


프로퍼티 세트

프로퍼티 세트에 의해, DirectX Audio 는 포토나 사운드 카드로 제공되는 확장 서비스를 지원 할 수 있다.

하드웨어 벤더는 새로운 능력을 프로퍼티로서 정의해, 그 프로퍼티의 사양을 발표한다. GUID 가 프로퍼티 세트를 식별해,ULONG 가 세트내의 특정의 프로퍼티를 식별한다. 예를 들어, 하드웨어 벤더가 리바브에페크트를 생성 할 수 있는 카드를 설계해, DSPROPERTY_REVERBPROPERTIES_HALL 와 DSPROPERTY_REVERBPROPERTIES_STADIUM 등의 프로퍼티를 보관 유지하는 프로퍼티 세트 DSPROPSETID_ReverbProperties 를 정의하는 일도 생각할 수 있다. 보통, 번호 0 으로 시작되는 C 언어의 열거형을 사용해 프로퍼티 식별자를 정의한다.

개별의 프로퍼티에 파라미터를 관련지어도 괜찮다. 파라미터의 의미는, 프로퍼티와 함께 정의된다.


DirectMusic 포토의 프로퍼티 세트

IKsControl::KsProperty 메소드를 사용해, 프로퍼티가 이용 가능한지 어떤지를 확인해, 프로퍼티의 값을 설정 및 취득한다. IDirectMusicPort8:: QueryInterface 메소드를 호출해, 인터페이스 식별자로서 IID_IKsControl 를 건네주는 것으로, 포토에 대응하는 IKsControl 인터페이스를 취득한다.

프로퍼티 세트는 GUID 에 의해 나타내져 세트의 각 항목은 0 으로부터 시작되는 인덱스에 의해 나타내진다. GUID 에 대해서 인덱스화 된 항목의 의미가 변경될 것은 없다. DirectMusic 로 지원 되는 프로퍼티 세트의 리스트에 대해서는, 「KSPROPERTY 」를 참조할것.

DirectMusic 로 미리 정의되고 있는 프로퍼티 세트는 모두, 다만 1 개의 항목을 가지고 있어 보통, 인덱스 번호는 0 으로 설정되어 있다. 커넬 스트리밍 (KS) 프로퍼티의 완전 정의도 지원 되고 있어 벤더는 임의의 수의 항목과 인스턴스, 및 임의의 사이즈의 데이터를 가지는 프로퍼티 세트를 자유롭게 생성 할 수 있다.

프로퍼티 항목의 요구를 포토에 대해서 송신하는 작업은, 포토의 이행에 의존한다. Win32® 핸들 베이스의 멀티미디어 호출 (midiOut 와 midiIn 의 각 함수)을 이용해 DirectMusic 의 에뮬레이션을 실시하고 있는 포토에서는, 어느 프로퍼티도 지원 되지 않는다.

다음의 샘플 코드에서는,IKsControl::KsProperty 메소드를 사용해, 포토가 General MIDI 사운드 세트를 하드웨어로 지원 하고 있을지 어떨지를 조사하고 있다.

BOOL IsGMSupported(IDirectMusicPort8 *pPort)
{
    HRESULT     hr;
    IKsControl  *pControl;
    KSPROPERTY  ksp;
    DWORD       dwFlags;
    ULONG       cb;
    BOOL        fIsSupported;

    // IKsControl 인터페이스의 조회를 실시한다.
    hr = pPort->QueryInterface(IID_IKsControl, (void**) &pControl);
    if (FAILED(hr))
    {
        // 포토가 프로퍼티를 지원 하고 있지 않다. GM 지원이 없으면 가정한다.
        return FALSE;
    }
    // GM 에 대해 문의한다.
    ksp.Set   = GUID_DMUS_PROP_GM_Hardware;
    ksp.Id    = 0;
    ksp.Flags = KSPROPERTY_TYPE_BASICSUPPORT;
    hr = pControl->KsProperty(&ksp, sizeof(ksp),
            &dwFlags, sizeof(dwFlags), &cb);
    fIsSupported = FALSE;
    if (SUCCEEDED(hr) || (cb >= sizeof(dwFlags))
    {
        // 세트가 지원 되고 있다.
        fIsSupported = (BOOL)(dwFlags & KSPROPERTY_TYPE_GET);
    }
    pControl->Release();
    return fIsSupported;
}


DirectSound 버퍼의 프로퍼티 세트

사운드 카드 위에의 확장 프로퍼티를 이용하려면 , 최초로 그 드라이버가 IKsPropertySet 인터페이스를 지원 하고 있을지 어떨지를 확인해, 지원 하고 있는 경우는 그 인터페이스에의 포인터를 취득해야 한다. 이것을 실시하려면 , 다음과 같이, DirectSound3D 버퍼 오브젝트 위에의 기존의 인터페이스에 대해서 QueryInterface 메소드를 호출한다.

HRESULT hr = lpDirectSound3DBuffer->QueryInterface(
        IID_IKsPropertySet,
        (void**) &lpKsPropertySet));

이 예에서는,lpDirectSound3DBuffer 는 버퍼의 인터페이스에의 포인터이며,IKsPropertySet 인터페이스가 발견되었을 경우는,lpKsPropertySet 는 그 주소를 받는다. IID_lpKsPropertySet 는, Dsound.h 내에서 정의되고 있는 GUID 이다.

버퍼가 하드웨어 액셀러레이트 되고 있는 경우에 한정해, 이 호출은 성공한다. 성공했을 경우는,IKsPropertySet::QuerySupport 메소드를 사용해 특정의 프로퍼티를 검색할 수 있다. PropertySetId 파라미터의 값은, 하드웨어 벤더에 의해 정의된 GUID 이다.

특정의 프로퍼티에 대한 지원이 존재 하면 확인한 후는,IKsPropertySet::Set 메소드에 의한 프로퍼티 상태의 변경과IKsPropertySet::Get 메소드에 의한 현재 상태의 확인을 실시할 수가 있다. pPropertyData 파라미터를 사용해, 프로퍼티 상태의 설정과 취득을 실시한다.

IKsPropertySet::Set 의 pPropertyParams 파라미터가 가리키는 구조 체내의 오브젝트에, 추가의 프로퍼티 파라미터를 건네주어도 괜찮다. 이 파라미터의 정확한 사용 방법은, 프로퍼티 세트에 관한 하드웨어 벤더의 시방서로 정의되지만, 프로퍼티 세트의 인스턴스를 정의하기 위해서 사용되는 것이 보통이다. 실제로는,pPropertyParams 를 사용하는 것은 거의 없다.


DirectSound 의 성능의 최적화

여기에서는, DirectSound 버퍼로 직접 오디오 데이터를 연주하는 어플리케이션의 성능을 향상시키기 위한 다양한 힌트를 나타낸다. 설명하는 주제는, 다음과 같다.

  • 버퍼 포맷의 매칭
  • 하드웨어 믹싱의 이용
  • 다이나믹 음성 관리
  • ISA 및 PCI 카드에서의 하드웨어 가속화
  • 프라이머리 버퍼의 연속 재생
  • 컨트롤의 변경의 최소화
  • 3D 버퍼에 관계하는 CPU 의 고려사항


버퍼 포맷의 매칭

DirectSound 믹서는, 각세칸다리사운드밧파로부터 얻은 데이터를프라이머리 사운드 버퍼용의 포맷으로 변환한다. 이 변환은 데이터를 프라이머리 버퍼에 믹싱 할 때에 그 자리에서 행해져 CPU 사이클을 소비한다. 세칸다리밧파와 프라이머리 버퍼로 같은 포맷을 사용하는 것으로, 이 부하를 회피할 수 있다. 보통, 이것은, 프라이머리 버퍼의 포맷을, 데이터로 사용되는 웨이브 파일의 포맷으로 설정하는 것이다.

DirectSound 가 채용하는 포맷 변환 방법에서는, 샘플링 레이트와 채널수를 맞추는 것만으로 좋다. 샘플링 사이즈 (8 비트나 16 비트인가)는 관계없다.


하드웨어 믹싱의 이용

대부분의 사운드 카드는, 대응하는 DirectSound 드라이버가 존재하면, 어떠한 레벨의 하드웨어 믹싱을 지원 한다. 다음의 힌트는, 하드웨어 믹싱을 가능한 한 이용하는데 도움이 된다.

  • 실행시에 IDirectSound8::GetCaps 메소드를 호출해, 사운드 가속기 하드웨어가 지원 하고 있는 포맷을 확인해, 할 수 있는 한 그 포맷을 사용한다.
  • 가장 이용이 많은 사운드의 사운드 버퍼를 최초로 생성 한다. 하드웨어로 믹싱 할 수 있는 버퍼수에는 한도가 있다.
  • 버퍼를 하드웨어에 반드시 생성 하려면 ,DSBUFFERDESC 구조체의 dwFlags 멤버에 DSBCAPS_LOCHARDWARE 플래그를 지정한다. 이 플래그를 지정해, 하드웨어 믹싱에 대한 리소스를 이용할 수 없는 경우는,IDirectSound8::CreateSoundBuffer 메소드는 실패한다.
  • 음성 관리를 사용해, 하드웨어 리소스가 이용 가능한 때에 버퍼를 리소스에 할당하거나 그다지 중요하지 않은 버퍼를 강제 종료시켜 하드웨어 리소스를 해방할 수 있도록(듯이) 한다. 「다이나믹 음성 관리」를 참조할것.


다이나믹 음성 관리

많은 사운드 카드는 고유의 세칸다리밧파를 유지해, 3D 이펙트와 그 믹싱을 처리한다. 이러한 하드웨어 버퍼는, 호출때, 보통은 카드 자체는 아니고 시스템 메모리에 배치된다. 그러나, 이것들은 디바이스에 의해 믹싱 되므로, 시스템 프로세서에 대한 요구는, 소프트웨어 버퍼보다 훨씬 적게 된다. 따라서, 하드웨어로 할 수 있는 한 많은 버퍼, 특히 3D 버퍼를 할당하는 것이 가장 효율적이다.

디폴트에서는, DirectSound 는 가능하면 항상 버퍼를 하드웨어에 할당한다. 그러나, DirectSound 는 디바이스가 한 번에 재생 가능한 한의 하드웨어 버퍼 밖에 생성 할 수 없다. 즉, 하드웨어 버퍼수는, 이용 가능한 하드웨어 음성으로 제한된다. DirectSound 는, 버퍼가 생성 될 때 하드웨어 음성을 할당해 버퍼가 불필요하게 되었을 때만 해방한다. 음성은, 버퍼가 재생중이 아닐 때도 프리는 아니다. 어플리케이션이 많은 버퍼를 생성 하는 경우, 몇개의 버퍼가 소프트웨어에 존재할 가능성이 있다. 즉, 사운드 카드는 아니고 CPU 로 버퍼의 관리와 믹싱을 한다.

다이나믹 음성 관리를 사용하면(자), 버퍼가 재생될 때까지 음성 할당을 지연 하거나 DirectSound 가 우선 순위의 낮은 사운드를 빨리 정지해 리소스를 새로운 사운드에 할당하는 것으로, 하드웨어 리소스의 이용 제한을 극복할 수 있다.

하드웨어 믹싱과 3D 이펙트에 대한 리소스의 할당을 버퍼가 재생될 때까지 지연 하려면 ,IDirectSound8::CreateSoundBuffer 에게 건네지는 DSBUFFERDESC 구조체에 DSBCAPS_LOCDEFER 플래그를 지정한다. DSBCAPS_LOCDEFER 플래그에 의해 생성 된 버퍼에 대해 IDirectSoundBuffer8::Play 또는 IDirectSoundBuffer8::AcquireResources 를 호출하는 경우, DirectSound 는 가능하면 하드웨어에 버퍼를 배치해, 그 이외의 경우는 소프트웨어에 배치한다.

Play 를 호출하는 경우는, 다음 표에 나타내는 플래그의 1 개, 또는 최초의 2 개의 플래그의 어느 쪽인지를 3 번째의 플래그와 조합해 건네주는 것으로, 버퍼에 대한 하드웨어 음성의 해방을 시도할 수가 있다. 그 후, DirectSound 는 플래그의 지정하는 종료 기준에 적절한 재생 버퍼를 검색한다.

플래그 | 기준
DSBPLAY_TERMINATEBY_TIME | 어느 후보 버퍼보다 길게 재생되고 있는 버퍼를 선택한다.
DSBPLAY_TERMINATEBY_DISTANCE | 청취자로부터 가장 먼 3D 의 후보 버퍼를 선택한다.
DSBPLAY_TERMINATEBY_PRIORITY | Play 의 호출에서의 설정에 근거해, 후보 버퍼의 쳐 가장 우선도의 낮은 버퍼를 선택한다. 이 플래그를 다른 2 개의 플래그의 어느 쪽일까하고 조합하면(자), 그 플래그는 우선도가 동일한 경우인 만큼 사용된다.

적절한 버퍼가 발견되면(자), DirectSound 는 그 버퍼를 정지해, 사용하고 있던 음성을 새롭게 재생되는 버퍼에 할당한다. 어느 버퍼도 종료 기준에 적절하지 않은 경우는, DSBPLAY_LOCHARDWARE 플래그가 지정되어 있지 않으면, 새롭게 재생되는 버퍼는 소프트웨어로 재생된다. 이 플래그가 지정되고 있는 경우,Play 에 대한 호출은 실패한다.

지연 버퍼의 재생시의 처리에 대한 자세한 것은, 「IDirectSoundBuffer8::Play 」를 참조할것.

주 버퍼의 생성시는, DSBCAPS_LOCDEFER 플래그를 DSBCAPS_STATIC 플래그와 조합해 사용하지 않는 것. 몇개의 PCI 카드의 경우와 같이, 온 카드 메모리가 이용 가능한 때, DSBCAPS_STATIC 버퍼는 이 메모리에 놓여진다. DSBCAPS_LOCDEFER 플래그로 이러한 버퍼를 생성 하는 경우, 버퍼 메모리는 버퍼가 최초로 재생될 때까지 사운드 카드로 카피되지 않고, 부적절한 지연이 생긴다. 상세한 것에 대하여는, 「ISA 및 PCI 카드에서의 음성 관리」를 참조할것.


ISA 및 PCI 카드에서의 하드웨어 가속화

과거 몇 년간에, 사운드 카드는 ISA 버스 카드로부터 PCI 카드로 이행했다. 이 설계의 변경에 의해, DirectSound 를 액셀러레이트 하는 카드가 오디오 데이터를 처리하는 기본적인 방법이 변화했다. 게다가 DirectSound 에 음성 관리가 도입되어 어플리케이션은 한정된 하드웨어 가속화 리소스를 효율적으로 사용할 수 있게 되었다.

여기에서는, 2 종류의 사운드 카드로, 버퍼를 할당하거나 음성 관리를 사용할 때의 주의 사항을 설명한다. 설명하는 주제는, 다음과 같다.

  • ISA 카드 위에의 DirectSound 버퍼
  • PCI 카드 위에의 DirectSound 버퍼
  • ISA 및 PCI 카드에서의 음성 관리


ISA 카드 위에의 DirectSound 버퍼

DirectSound 가 최초로 도입되었을 때, 모든 오디오 디바이스는 ISA 버스상에서 동작하고 있었다. ISA 버스는, 시스템 전체의 성능에 큰 영향을 주는 일 없이, 16 비트, 22 kHz 스테레오 데이터를 CPU 로부터 사운드 카드로 스트리밍 하기에는 충분했다. 그러나, 보다 많은 데이터를 송신하려고 하면(자), 버스에 과도의 부하가 걸리는 경우가 있었다. 이 제한에 의해, 오디오 하드웨어의 설계는 크게 영향을 받고 있었다.

DirectSound 버퍼를 믹싱 하기 위해서, 사운드 카드 위에의 팁으로 2 로 우리의 처리를 실시할 수가 있다. ISA 버스를 개입시켜 시스템 메모리에 액세스 하는지, 카드 자체의 전용 메모리를 사용할까이다. ISA 버스의 대역폭은 한정되어 있으므로, 시스템 메모리로부터의 오디오 데이터의 read는 현실적이지 않다. 따라서, ISA 베이스의 사운드 카드로, DirectSound 가속화를 실행하는 카드는, 대부분의 경우 전용의 온보드 RAM 를 가지고 있다.

이러한 사운드 카드를 사용해 DirectSound 를 액셀러레이트 하는 경우, 우선 사운드 데이터를 시스템 메모리로부터, ISA 버스를 개입시켜 카드 위에의 전용 메모리에 카피해야 한다. 이 카피에는 약간 시간이 걸리는 경우가 있다. 그러나, 데이터를 카드로 카피한 후는, 시스템에 대해서 사운드의 시작, 정지, 믹싱의 부하는 거의 걸리지 않는다. 이러한 처리는 모두, 카드 위에의 전용 메모리에 액세스 하는 오디오 프로세서 팁에 의해 처리된다.

ISA 베이스의 DirectSound 가속기는 카드 위에의 스태틱 버퍼를 지원 하고 있지만, 스트리밍 버퍼는 지원 하고 있지 않다. 이것은, 저속의 ISA 버스를 개입시켜 데이터를 스트리밍 하는 것은 실용적이지 않기 때문에이다. DSBCAPS_STATIC 플래그를 지정해 생성 한 DirectSound 버퍼는, 카드로 메모리가 탑재되고 있는 경우, 그 메모리에 배치된다. 그 외의 버퍼는, 시스템 메모리에 생성 된다.


PCI 카드 위에의 DirectSound 버퍼

현재 판매되고 있는 대부분의 오디오 카드는 PCI 버스에 접속하도록(듯이) 설계되고 있다. PCI 버스가 일반적으로 되는에 따라, 시스템과 오디오 카드와의 사이에 이용 가능한 대역폭이 큰폭으로 증가했다. 현재는, 오디오 팁이 직접 시스템 메모리에 액세스 해, 오디오 데이터를 취득해 하드웨어 믹싱을 실시하는 일도 현실적으로 되었다. 그 결과, 버퍼용의 온보드 메모리를 가지는 의미가 없어졌다.

PCI 카드로는, 스태틱 버퍼와 스트리밍 버퍼는 사실상 같다. 모든 버퍼는 시스템 메모리내에 배치되므로, DSBCAPS_STATIC 플래그는 버퍼의 장소에 영향을 주지 않는다.

주 대부분의 사운드 카드는, 온보드 RAM 를 가지고 있지 않은 경우에서도, 스태틱 버퍼를 가지고 있으면(자) DSCAPS 에 리포트한다. 이러한 카드에 의해 리포트되는 스트리밍 버퍼와 스태틱 버퍼는 같은 버퍼인 경우가 있다.


ISA 및 PCI 카드에서의 음성 관리

버퍼의 생성시에 DSBCAPS_LOCDEFER 플래그를 사용하는 것에 의해, 버퍼가 재생될 때까지, 하드웨어 믹싱 메모리 또는 소프트웨어 믹싱 메모리에의 버퍼의 할당을 지연 할 수가 있다. 상세한 것에 대하여는, 「다이나믹 음성 관리」를 참조할것.

어플리케이션의 성능에 대한 지연 할당의 효과는, 유저의 시스템에서의 DirectSound 가속기의 타입에 따라서 다르다.

PCI 가속기의 경우를 생각해 본다. 지연 버퍼를 재생할 경우에, DirectSound 는 사운드의 재생에 이용할 수 있는 하드웨어가 있을지 어떨지를 조사한다. 하드웨어를 이용할 수 있는 경우, DirectSound 는 원의 장소에 있는 사운드 데이터에 액세스 할 수 있을지 어떨지를 확인한다. 마지막으로, DirectSound 는 재생을 시작 하도록(듯이) 하드웨어에 지시한다. 이 처리는, 효율적이며, 또 고속으로 있다.

주 DirectSound 음성 매니저는, 메모리는 아니고, 하드웨어 믹싱 리소스를 할당한다. PCI 카드로는, 버퍼는 하드웨어 믹서와 소프트웨어 믹서의 머지않아에 할당할 수 있을까에 관계없이, 할당의 전후로 같은 메모리를 사용한다.

유저가 ISA 베이스의 가속기를 사용하는 경우, 상황은 완전히 다르다. 이 경우, 오디오 데이터를 하드웨어 믹싱 버퍼에 수중에 넣는 처리는 매우 늦다. 오디오 데이터를 믹싱 하려면 , ISA 버스를 개입시켜, 사운드 카드 위에의 메모리에 데이터를 로드하지 않으면 안 되기 때문에이다. 지연 버퍼의 경우, 재생의 호출을 한 후, 사운드가 시작 되기 전에 부적절한 지연이 발생한다. 이러한 이유로부터, ISA 베이스의 DirectSound accelerator card에서는 음성 관리의 사용은 추천되어 있지 않다.

ISA 디바이스로 어플리케이션이 음성 관리를 사용하지 않게 하는 것은 간단하다. DSBCAPS_STATIC 플래그를 설정하지 않는 한, 버퍼는 온보드 메모리에 할당할 수 없다. 따라서, DSBCAPS_STATIC 와 DSBCAPS_LOCDEFER 를 조합하지 않는 이상 재생시에 버퍼가 온보드 메모리에 할당할 수 있는 위험성은 없다.

DSBCAPS_STATIC 만을 지정 하면, 버퍼는 ISA 카드 위에의 기존의 메모리를 이용하지만, PCI 카드의 경우는 아무 효과도 없다. 이 경우, 다른 플래그가 지정되어 있지 않으면 DirectSound 는 버퍼를 하드웨어의 제어하에 두지만, 시스템 메모리를 이용한다. DSBCAPS_LOCDEFER 만을 지정 하면, ISA 카드로는 아무 효과도 없다. 버퍼는 항상 시스템 메모리에 배치되어 하드웨어에 의해 관리되지 않기 때문에이다.

다음 표에, ISA 및 PCI 디바이스용으로 생성 된 버퍼에 대한 DSBCAPS_STATIC 및 DSBCAPS_LOCDEFER 플래그의 효과를 정리한다.

카드 | 플래그 | 메모리 | HW 가속화
ISA | DSBCAPS_STATIC | 이용 가능한 경우는 하드웨어. | 하드웨어 메모리에 있는 경우는 가능.
PCI | DSBCAPS_STATIC | 시스템. | 하드웨어 음성이 이용 가능한 경우는 가능. 플래그의 효과는 없다.
ISA | DSBCAPS_LOCDEFER | 이용 가능해, DSBCAPS_STATIC 가 설정되어 있는 경우는 하드웨어. | 하드웨어 메모리에 있는 경우는 가능. 다만, 최초의 재생에는 대기 시간이 발생한다.
PCI | DSBCAPS_LOCDEFER | 시스템. | 하드웨어 음성이 이용 가능한 경우는 가능.

지연 할당에 의한 문제를 회피하면서, ISA 카드로 가속화를 이용하려면 , 우선 디바이스의 능력을 체크한다. 카드로 1 개 이상의 스태틱 버퍼가 있어, 스트리밍 버퍼가 없으면 리포트되는 경우는, 온보드 메모리를 탑재한 낡은 ISA 카드일 가능성이 높다. 이 경우, DSBCAPS_STATIC 플래그를 사용할 수 있지만 DSBCAPS_LOCDEFER 를 사용해서는 안 된다. 카드로 1 개 이상의 스트리밍 버퍼가 있다고 리포트되는 경우는, 새로운 PCI 베이스의 accelerator card이다. 이 경우는, 하드웨어 음성을 최대한으로 이용하기 위해서, DSBCAPS_LOCDEFER 를 사용해, DSBCAPS_STATIC 를 사용하지 않는다.


프라이머리 버퍼의 연속 재생

사운드가 재생되어 있지 않은 경우, DirectSound 는 믹서 엔진을 정지해, DMA (다이렉트 메모리 액세스)를 정지시킨다. 재생 없음 상태가 빈번하게 발생하는 어플리케이션에서는, 사운드를 재생할 때마다 믹서의 시작과 정지를 실시하는 경우의 오버헤드는, 믹서를 상시 액티브하게 하는 경우의 DMA 의 오버헤드보다 커지는 일이 있다. 또, 사운드 기기나 드라이버에 따라서는, 재생의 빈번한 시작과 정지에 의해 불필요한 잡음을 내는 일도 있다.

어플리케이션이 거의 연속적으로 재생을 실시해, 휴지 시간이 적은 경우는, 프라이머리 버퍼에 대해서 IDirectSoundBuffer8::Play 메소드를 호출해, 믹서 엔진을 상시 액티브하게도 할 수 있다.

사운드의 재생이 없을 때에 믹서 엔진을 정지하는 디폴트 상태에 되돌리려면 , 프라이머리 버퍼에 대해서 IDirectSoundBuffer8::Stop 메소드를 호출한다.


컨트롤의 변경의 최소화

세칸다리밧파의 빵, 볼륨, 주파수를 변경 하면 성능에 영향을 준다. 사운드 출력이 중단되는 것을 방지하려면 , DirectSound 믹서는 20ms 에서 100 ms, 또는 그 이상 선행해 믹싱을 실시하지 않으면 안 된다. 컨트롤을 변경했을 경우는, 믹서는 선행 믹싱 버퍼를 플래시 (해방) 해, 변경 후의 사운드를 사용해 재믹싱을 실시하지 않으면 안 된다.

송신하는 컨트롤의 변경 회수를 최소로 하는 것은 좋은 생각이다. IDirectSoundBuffer8::SetVolume ,IDirectSoundBuffer8::SetPan ,IDirectSoundBuffer8::SetFrequency 의 각 메소드를 사용하는 루틴의 호출 회수를 줄이도록(듯이) 노력한다. 예를 들어, 애니메이션의 프레임에 동기 해 소리를 왼쪽 스피커로부터 오른쪽 스피커에 작동시키는 루틴을 사용하고 있는 경우,SetPan 메소드를 1 프레임 마다 2 회는 아니고 1 회 호출하는 것을 시도한다.

주 3D 컨트롤 (향해, 위치, 속도, 돕라 계수등)을 변경했을 경우도, DirectSound 믹서는 선행 믹싱 버퍼를 재믹싱 해야 한다. 그러나, 3D 컨트롤의 변경을 그룹화 해, 재믹싱을 1 회에 삭감할 수 있다. 「지연 설정」을 참조할것.


3D 버퍼에 관계하는 CPU 의 고려사항

소프트웨어에 의한 3D 버퍼의 에뮬레이션은, 많은 계산 처리를 필요로 한다. 어플리케이션으로, 언제, 어떻게 3D 버퍼를 사용할까를 결정하는 경우는, 이것을 고려해야 한다.

3D 사운드의 이용은 최소한으로 억제해 3D 이펙트가 이점이 되지 않는 사운드에는 3D 사운드를 적용하지 않는다. 각 사운드의 3D 이펙트를 간단하게 유효 또는 무효로 할 수 있도록(듯이) 어플리케이션을 설계한다. 임의의 3D 사운드 버퍼에 대한 3D 처리를 정지하려면 , DS3DMODE_DISABLE 플래그를 지정해 IDirectSound3DBuffer8::SetMode 메소드를 호출한다.

청취자로부터의 거리가 멀고, 들리지 않는 버퍼에 대해서도, 3D 처리가 정지하고 있는 것을 확인할 수 있다. 「최소 거리와 최대 거리」를 참조할것.


DirectSound 드라이버 모델

VxD 드라이버 모델에서는, DirectSound 의 모든 믹싱은, 가상 디바이스 드라이버 Dsound.vxd 로 처리된다. Dsound.vxd 는, 사운드 카드가 호스트 CPU 로부터 데이터를 수신하기 위해서 사용하는 실제의 DMA 버퍼에의 액세스도 제공한다. 이것은 DirectSound 프라이머리 버퍼와 같다. DirectSound 어플리케이션은, 샘플링 레이트나 비트 깊이 등, 프라이머리 버퍼의 특정의 프로퍼티를 설정할 수가 있어 따라 하드웨어 자체의 프로퍼티도 변경할 수 있다.

Windows Driver Model (WDM)에서는, DirectSound 는, 하드웨어에 의해 액셀러레이트 된 버퍼의 경우를 제외해, 사운드 버퍼에 직접 액세스 하지 않는다. 그 대신에, DirectSound 는 커넬 믹서, 즉 Kmixer 와 통신한다. Kmixer 의 역할은, 복수의 오디오 스트림의 포맷을 공통의 포맷으로 변환해, 이것들을 믹싱 해, 그 결과를 하드웨어에 송신하는 것이다. 즉, Dsound.vxd 가 가고 있던 처리를 실시하고 있다. 큰 차이는, Dsound.vxd 가 DirectSound 버퍼의 데이터만을 믹싱 하는데 대해, Kmixer 는, Win32 waveOut 함수를 사용하는 어플리케이션으로부터의 데이터를 포함한, 모든 Windows 오디오 데이터를 믹싱 하는 것이다. DirectSound 와 웨이브 폼 오디오 출력 디바이스를 동시에 오픈할 수 없다고 하는 규칙은, WDM 드라이버를 사용하는 시스템에는 들어맞지 않는다.

Kmixer 와 오디오 하드웨어와의 관계는 특히 중요하다. Kmixer 는, 시스템상에서, 하드웨어의 DMA 버퍼의 폼을 지정할 수 있는 유일한 소프트웨어이다. Kmixer 는, 믹싱이 요구된 사운드에 근거해 포맷을 선택한다. 출력 포맷은, 믹싱이 요구된 사운드의 최고 품질의 포맷화, 하드웨어로 지원 되고 있다, 거기에 가장 가까운 포맷으로 설정된다.

이것은, 매우 중요한 의미를 가지고 있다. DirectSound 에서는, 하드웨어의 DMA 버퍼의 포맷을 설정할 수 없다고 하는 것이다. 어플리케이션에서는, 하드웨어 포맷은 실제로 연주되는 데이터에 근거하는 것을 의미한다. 44 kHz 의 파일을 재생하는 경우, Kmixer 는 최대 44 kHz 의 모든 데이터를 믹싱 해, 하드웨어가 44 kHz 로 실행되고 있는 것을 확인한다.

어플리케이션 개발자는, 사용되는 드라이버 모델을 선택하지 않는다. 드라이버 모델은, 사운드 카드의 종류, Windows 의 버젼, 유저가 인스톨 하고 있는 특정의 드라이버에 의해 정해진다. 이러한 이유로부터, 어플리케이션을 테스트할 경우에, 모든 가능성을 조사해 두는 것이 중요하다. DirectSound 는 Dsound.vxd 를 사용하는 경우도 있으면, Kmixer 를 사용하는 경우도 있으므로, 어플리케이션의 동작 및 성능이 어느 경우도 허용 할 수 있는 것인 것을 확인해야 한다.


프라이머리 버퍼에의 기입해

세칸다리밧파가 지원 하고 있지 않는 특별한 믹싱이나 다른 이펙트를 필요로 하는 어플리케이션에 대해서, DirectSound 는프라이머리 사운드 버퍼에의 직접 액세스를 허가한다.

프라이머리 버퍼에의 기입해 액세스를 취득 하면, DirectSound 외의 기능은 이용할 수 없게 된다. 세칸다리밧파의 믹싱도 행해지지 않기 때문에, 하드웨어 가속화 믹싱도 이용할 수 없게 된다.

대부분의 어플리케이션은, 프라이머리 버퍼에 직접 액세스 하지 않고 세칸다리밧파를 사용한다. 세칸다리밧파에의 기입은 간단하게 실시할 수가 있다. 보다 큰 버퍼에 의해, 다음의 데이터 블록의 기입까지의 시간이 길어져, 오디오의 소리가 중단되는 위험이 최소한으로 억제 당한다. 어플리케이션이 필요로 하는 오디오가, 믹싱을 필요로 하지 않는 1 개의 오디오 스트림과 같이 단순한 것이어도, 세칸다리밧파를 사용해 오디오 데이터를 재생하는 것으로써, 보다 높은 성능을 실현될 수 있다.

주 프라이머리 버퍼에의 직접적인 기입은, WDM 드라이버 모델에서는 이점이 없다. WDM 에서는, 프라이머리 버퍼는, 사실상, 커넬 믹서에 의해 믹싱 되는 세칸다리밧파이다. WDM 의 상세한 것에 대하여는, 「DirectSound 드라이버 모델」을 참조할것.

프라이머리 버퍼의 사이즈는 지정하지 못하고, 버퍼를 생성 한 후에 돌려주어지는 사이즈를 받아들이지 않으면 안 된다. 보통, 프라이머리 버퍼는 지극히 작고, 만약 어플리케이션이 이러한 버퍼에 직접 기입하는 경우는 짧은 간격으로 데이터 블록을 기입해, 이전의 데이터가 한번 더 재생되는 것을 막지 않으면 안 된다.

프라이머리 버퍼가 하드웨어상에 존재하고 있지 않는 한, 그 버퍼의 기입 액세스는 취득할 수 없다. 이것에 해당할지 어떨지를 확인하려면 ,IDirectSoundBuffer8::GetCaps 메소드를 호출해 DSBCAPS 구조체의 dwFlags 멤버내의 DSBCAPS_LOCHARDWARE 플래그의 유무를 체크한다. 소프트웨어로 에뮤레이트 한 프라이머리 버퍼를 잠그려고 하면, 호출은 실패한다.

DSBUFFERDESC 구조체에 DSBCAPS_PRIMARYBUFFER 플래그를 지정해, 이 구조체를 IDirectSound8::CreateSoundBuffer 메소드에 건네주어, 액세스 가능한 프라이머리 버퍼를 생성 한다. 버퍼에 기입을 하고 싶은 경우, 협조 레벨은 DSSCL_WRITEPRIMARY 가 아니면 안된다.

프라이머리 사운드 버퍼는, 루프 해 재생해야 한다. 그 목적으로, DSBPLAY_LOOPING 플래그가 설정되어 있는 것을 확인한다.

다음의 예는, 프라이머리 버퍼에의 기입해 액세스를 취득하는 방법을 나타내고 있다. 프라이머리 버퍼는 IDirectSoundBuffer 인터페이스만을 지원 해,IDirectSoundBuffer8 를 지원 하고 있지 않는 것에 주의 해야 한다.

BOOL AppCreateWritePrimaryBuffer(
    LPDIRECTSOUND8 lpDirectSound,
    LPDIRECTSOUNDBUFFER *lplpDsb,
    LPDWORD lpdwBufferSize,
    HWND hwnd)
{
    DSBUFFERDESC dsbdesc;
    DSBCAPS dsbcaps;
    HRESULT hr;
    WAVEFORMATEX wf;

    // 웨이브 포맷 구조체를 설정한다.
    memset(&wf, 0, sizeof(WAVEFORMATEX));
    wf.wFormatTag = WAVE_FORMAT_PCM;
    wf.nChannels = 2;
    wf.nSamplesPerSec = 22050;
    wf.nBlockAlign = 4;
    wf.nAvgBytesPerSec =
        wf.nSamplesPerSec * wf.nBlockAlign;
    wf.wBitsPerSample = 16;

    // DSBUFFERDESC 구조체를 설정한다.
    memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags = DSBCAPS_PRIMARYBUFFER;
    // 버퍼 사이즈는 사운드 하드웨어에 의해 정해진다.
    dsbdesc.dwBufferBytes = 0;
    dsbdesc.lpwfxFormat = NULL; // 프라이머리 버퍼에서는 NULL 가 아니면 안된다.

    // 기입 우선 협조 레벨을 취득한다.
    hr = lpDirectSound->SetCooperativeLevel(hwnd, DSSCL_WRITEPRIMARY);
    if SUCCEEDED(hr)
    {
        // 버퍼의 생성을 시도한다.
        hr = lpDirectSound->CreateSoundBuffer(&dsbdesc,
                lplpDsb, NULL);
        if SUCCEEDED(hr)
        {
            // 프라이머리 버퍼를 적절한 포맷으로 설정한다.
            hr = (*lplpDsb) ->SetFormat(&wf);
            if SUCCEEDED(hr)
            {
                // 버퍼 사이즈를 알고 싶은 경우는, GetCaps 를 호출한다.
                    dsbcaps.dwSize = sizeof(DSBCAPS);
                (*lplpDsb) ->GetCaps(&dsbcaps);
                *lpdwBufferSize = dsbcaps.dwBufferBytes;
                return TRUE;
            }
        }
    }
    // 실패.
    *lplpDsb = NULL;
    *lpdwBufferSize = 0;
    return FALSE;
}

다음의 예는, 어플리케이션이 커스텀 믹서를 이행 하는 방법을 나타내고 있다. 사운드 디바이스가 데이터 블록의 재생을 반복하지 않게, AppMixIntoPrimaryBuffer 함수를 일정한 간격으로 호출하지 않으면 안 된다. CustomMixer 함수는 어플리케이션이 정의한 함수이며, 어플리케이션이 정의한 AppStreamInfo 구조체의 지정에 따라 복수의 스트림을 믹싱 해, 다음과 같이 결과를 지정의 포인터에 기입한다.

BOOL AppMixIntoPrimaryBuffer(
        LPAPPSTREAMINFO lpAppStreamInfo,
        LPDIRECTSOUNDBUFFER lpDsbPrimary,
        DWORD dwDataBytes,
        DWORD dwOldPos,
        LPDWORD lpdwNewPos)
{
    LPVOID lpvPtr1;
    DWORD dwBytes1;
    LPVOID lpvPtr2;
    DWORD dwBytes2;
    HRESULT hr;
    // 기입 포인터를 취득한다.
    hr = lpDsbPrimary->Lock(dwOldPos, dwDataBytes,
                            &lpvPtr1, &dwBytes1,
                            &lpvPtr2, &dwBytes2, 0);

    // DSERR_BUFFERLOST 가 돌려주어졌을 경우, 복원해 락을 재시행한다.

    if (DSERR_BUFFERLOST == hr)
    {
        lpDsbPrimary->Restore();
        hr = lpDsbPrimary->Lock(dwOldPos, dwDataBytes,
                                &lpvPtr1, &dwBytes1,
                                &lpvPtr2, &dwBytes2, 0);
    }
    if SUCCEEDED(hr)
    {
        // 돌려주어진 포인터에 데이터를 믹싱 한다.
        CustomMixer(lpAppStreamInfo, lpvPtr1, dwBytes1);
        *lpdwNewPos = dwOldPos + dwBytes1;
        if (NULL ! = lpvPtr2)
        {
            CustomMixer(lpAppStreamInfo, lpvPtr2, dwBytes2);
            *lpdwNewPos = dwBytes2; // rack-around 되기 때문이다.
        }
        // 데이터를 해방해 DirectSound 에 되돌린다.
        hr = lpDsbPrimary->Unlock(lpvPtr1, dwBytes1,
                                  lpvPtr2, dwBytes2);
        if SUCCEEDED(hr)
        {
            return TRUE;
        }
    }
    // 락 또는 언락이 실패했다.
    return FALSE;
}


프로그래밍의 힌트 및 툴

여기에서는, DirectX Audio 어플리케이션을 효율적으로 개발하기 위한 정보를 기술한다. 설명하는 주제는, 다음과 같다.

  • DirectX Audio 프로젝트의 디버그
  • 테스트용의 DirectSound 가속화의 컨트롤


DirectX Audio 프로젝트의 디버그

DirectX 소프트웨어 개발 킷의 디버그 버젼으로 인스톨 되는 DirectMusic 및 DirectSound 의 DLL (동적 링크 라이브러리)는, 어플리케이션의 실행시에, 정보를 디버그 출력 윈도우에 생성한다. 디폴트에서는, 이용할 수 있는 모든 정보가 표시된다. 이러한 DLL 는, DirectX SDK 의 디버그 버젼이 인스톨 되고 있는 경우에 이용할 수 있다. DirectMusic DLL는, 컨트롤 패널의 DirectX 프로퍼티 시트로 [Use Debug Version of DirectMusic] 를 선택하는 것에 의해 동적으로 선택할 수 있다.

DirectMusic DLL 에서는, Win.ini 의 값을 변경 하면, 디버그 출력 윈도우에 표시되는 정보를 제어할 수가 있다. DirectMusic DLL 각각의 출력은, 다음의 예에 나타내도록(듯이), 개별적으로 설정할 수가 있다.

[Debug]
DMBAND=1
DMCOMPOS=1
DMIME=1
DMLOADER=0
DMUSIC=1
DMSTYLE=3
DMSYNTH=5

각각의 값은 -1 ~ 5 의 범위에서 설정할 수 있다. -1 (을)를 설정 하면, 디버그 정보는 생성되지 않고, 5 를 설정 하면, 가장 상세한 정보가 생성된다. Win.ini 에 엔트리가 없는 경우, 디버그 출력의 레벨은 0 이 된다. 특정의 DLL 에 다른 컴퍼넌트보다 낮은 값을 설정해, 그 DLL의 문제에 주목할 수가 있다.

컨트롤 패널의 DirectX 프로퍼티 시트의 [DirectMusic] 페이지 및 [DirectSound] 페이지에 있는 [Debug Output Level] 슬라이더를 사용해, 디버그 레벨을 0 ~ 5 의 범위로 설정할 수도 있다. 다만, 이 방법에서는 모든 DLL 에 같은 값이 설정된다.

「DirectX 어플리케이션의 디버그」도 참조할것.


테스트용의 DirectSound 가속화의 컨트롤

컨트롤 패널의 [사운드와 멀티미디어의 프로퍼티] 페이지로, 시스템 위에의 DirectSound 의 성능을 조정할 수 있다. [오디오] 탭의 [재생] 의 [상세] 를 클릭한다. [퍼포먼스] 탭을 클릭한다. 슬라이더를 사용해, 하드웨어 가속화를 다음의 어느 쪽인가에 설정할 수 있다.

최대
IKsPropertySet 확장 기능 등, 모든 DirectSound 가속화를 유효하게 한다. Windows 98 에서는, 이것이 디폴트의 설정이다.
표준
DirectSound 세칸다리밧파의 가속화를 유효하게 하지만, 하드웨어 고유의 IKsPropertySet 확장 기능을 무효로 한다. Windows 2000 에서는, 이것이 디폴트의 설정이다.
기본
DirectSound 세칸다리밧파의 하드웨어 가속화를 무효로 한다. 이 옵션은, 테스트용으로 가속화 기능을 가지지 않는 사운드 카드를 에뮬레이션 하는 경우에 편리하다.
없음
DirectSound 를 에뮬레이션 모드로 한다. 이 모드는, 시스템에 DirectSound 호환의 드라이버가 없는 것으로서 기능한다. 모든 믹싱은, 유저 모드의 DirectSound 에 의해 행해져 믹싱 된 데이터는 Win32 웨이브 폼 오디오 함수에 송신된다. 보통, 이것에 의해 지연 시간이 큰폭으로 증가한다.


DirectX Audio C++ 튜토리얼

여기에서는, 다음의 튜토리얼을 사용해, C++ 어플리케이션에 Microsoft® DirectMusic® 및 Microsoft® DirectSound® 를 이행 하는 방법을 설명한다.

  • 튜토리얼 1 : 오디오 파일의 재생
  • 튜토리얼 2 : 오디오 패스 오브젝트의 사용법

이 밖에, SDK 와 함께 제공되는 샘플 어플리케이션에서는, Microsoft® DirectX® Audio 의 것보다 전문적인 사용법이 나타나고 있다. 이러한 샘플의 설명에 대해서는, 「DirectX Audio C++ 샘플」을 참조할것.


튜토리얼 1 : 오디오 파일의 재생

이 튜토리얼에서는, DirectX Audio 의 가장 기본적인 태스크에 대해 스텝바이스텝으로 설명한다. 구체적으로는, DirectMusic 퍼포먼스의 초기화와 오디오 파일의 재생에 대해 설명한다. 이 튜토리얼은, 다음의 스텝으로부터 구성되어 있다.

  • 스텝 1 : 초기화
  • 스텝 2 : 파일의 로드
  • 스텝 3 : 파일의 재생
  • 스텝 4 : 종료 처리

튜토리얼로 사용하고 있는 샘플 코드 전체의 파일이 다음의 폴더에 있다.

\mssdk\samples\Multimedia\DirectMusic\Tutorials\Tut1

주 DirectX SDK 가 인스톨 되고 있는 루트 디렉토리가 다른 경우는, 패스내의 "mssdk" 를 그 디렉토리의 이름에 옮겨놓을 필요가 있다.


스텝 1 : 초기화

어플리케이션으로 DirectMusic API 를 사용하려면 , 다음의 인클루드 파일이 필요하다. Dmusici.h 를 인클루드 하면, DirectMusic 와 DirectSound 의 그 외의 필요한 헤더 파일도 인클루드 된다.

#define INITGUID
#include <dmusici.h>

이 튜토리얼은, 3 개의 인터페이스 포인터를 사용한다. 그것들은 다음과 같이 선언된다.

IDirectMusicLoader8*      g_pLoader       = NULL;
IDirectMusicPerformance8* g_pPerformance  = NULL;
IDirectMusicSegment8*     g_pSegment      = NULL;

WinMain 함수에는, 이 간단한 어플리케이션의 모든 코드가 포함되어 있다. 이 어플리케이션은 메인 윈도우를 가지지 않기 때문에, 직접, COM 와 2 개의 오브젝트의 생성에 진행된다. 생성 하는 오브젝트는, 로더와 퍼포먼스이다.

INT APIENTRY WinMain( HINSTANCE hInst, HINSTANCE hPrevInst,
    LPSTR pCmdLine, INT nCmdShow )
{
    CoInitialize(NULL);

    CoCreateInstance(CLSID_DirectMusicLoader, NULL,
                     CLSCTX_INPROC, IID_IDirectMusicLoader8,
                     (void**) &g_pLoader);

    CoCreateInstance(CLSID_DirectMusicPerformance, NULL,
                     CLSCTX_INPROC, IID_IDirectMusicPerformance8,
                     (void**) &g_pPerformance );

다음의 스텝에서는, 퍼포먼스와 신디사이저를 초기화한다. IDirectMusicPerformance8::InitAudio 메소드에 의해 다음의 태스크를 실행한다.

  • DirectMusic 오브젝트와 DirectSound 오브젝트를 생성 한다. 보통, 이러한 오브젝트에의 인터페이스는 필요없고, 최초의 2 개의 파라미터에 NULL 를 건네준다.
  • 어플리케이션 윈도우를 DirectSound 에 관련짓는다. 보통, 3 번째의 파라미터로서 메인 어플리케이션 윈도우의 핸들이 건네받지만, 이 튜토리얼의 어플리케이션은 윈도우를 가지지 않기 때문에 NULL 를 건네준다.
  • 표준 타입의 디폴트의 오디오 패스를 설정한다. 이 튜토리얼에서는, 음악에 적절한 DMUS_APATH_SHARED_STEREOPLUSREVERB 형의 패스를 요구한다.
  • 퍼포먼스 채널의 수를 오디오 패스에 할당한다. 웨이브 파일에 필요한 퍼포먼스 채널은 1 개 뿐이다. MIDI 파일은 16 개의 채널을 필요로 한다. DirectMusic Producer 로 생성 한 세그먼트(segment)는, 한층 더 많은 채널을 사용하는 경우가 있다. 여분의 채널을 요구해도 문제는 생기지 않는다.
  • 신디사이저의 기능 및 리소스를 지정한다. 이것은, 다음의 2 개의 방법으로 실시할 수가 있다. 플래그를 설정하는 방법과 보다 상세한 정보를 포함한 DMUS_AUDIOPARAMS 구조체를 건네주는 방법이다. 대부분의 어플리케이션은, DMUS_AUDIOF_ALL 플래그를 설정해, DirectMusic 에 의해 디폴트의 파라미터 설정의 신디사이저가 생성 되도록(듯이) 하고 있다.

이 튜토리얼에서는, 매우 간단한 방법으로 InitAudio 를 호출하고 있다.

    g_pPerformance->InitAudio(
        NULL,                  // IDirectMusic 인터페이스는 불요.
        NULL,                  // IDirectSound 인터페이스는 불요.
        NULL,                  // 윈도우의 핸들.
        DMUS_APATH_SHARED_STEREOPLUSREVERB,  // 디폴트의 오디오파스타이프
        64,                    // 퍼포먼스 채널의 수.
        DMUS_AUDIOF_ALL,       // 신디사이저의 기능.
        NULL                   // 오디오 파라미터에는 디폴트를 사용.
    );

다음의 「스텝 2 : 파일의 로드」에 계속된다.


스텝 2 : 파일의 로드

다음은, DirectMusic 의 퍼포먼스 및 신디사이저로 사운드 데이터를 처리한다. 데이터를 취득하려면 , 로더에 데이터의 장소를 지시할 필요가 있다. 파일을 로드할 때마다 풀 패스를 지정할 수도 있지만, 디폴트의 디렉토리를 설정해 두는 (분)편이 편리하다. 이것에는,IDirectMusicLoader8::SetSearchDirectory 메소드를 사용한다.

샘플 코드에서는, 디폴트의 Windows 미디어 디렉토리에의 패스가 지정되고 있다. 다른 폴더의 파일을 취득하려면 ,wstrSearchPath 의 값을 변경한다.

다음의 코드는, 튜토리얼 샘플내의 WinMain 함수의 일부이다.

    // Windows 미디어 디렉토리를 찾아낸다.

    CHAR strPath[MAX_PATH];
    GetWindowsDirectory( strPath, MAX_PATH );
    strcat( strPath, "\\media" );

   // Unicode 로 변환한다.

    WCHAR wstrSearchPath[MAX_PATH];
    MultiByteToWideChar( CP_ACP, 0, strPath, -1,
                         wstrSearchPath, MAX_PATH );

    // 검색 디렉토리를 설정한다.

    g_pLoader->SetSearchDirectory(
        GUID_DirectMusicAllTypes,   // 검색하는 파일의 종류.
        wstrSearchPath,             // 검색하는 장소.
        FALSE                       // 오브젝트 데이터를 소거하지 않는다.
    );

SetSearchDirectory 의 호출 중(안)에서,fClear 파라미터가 FALSE 로 설정되어 있는 것은, 잘못한 디렉토리의 오브젝트가 재로드 될 가능성은 없기 때문에이다. 어플리케이션이 다른 폴더로부터 같은 이름의 오브젝트를 로드하지 않는 이상 잘못한 디렉토리의 오브젝트가 재로드 될 것은 없다.

로더에 파일의 검색 장소를 지시하면(자), 다음은, 파일을 1 개의 세그먼트(segment)로서 로드한다.

    WCHAR wstrFileName[MAX_PATH] = L"The Microsoft Sound.wav";

    if (FAILED(g_pLoader->LoadObjectFromFile(
        CLSID_DirectMusicSegment,   // 클래스 식별자.
        IID_IDirectMusicSegment8,   // 목적의 인터페이스의 ID.
        wstrFileName,               // 파일명.
        (LPVOID*) &g_pSegment       // 인터페이스를 받는 포인터.
    )))
    {
        MessageBox( NULL, "Media not found, sample will now quit. ",
                          "DMusic Tutorial", MB_OK );
        return 0;
    }

다음의 「스텝 3 : 파일의 재생」에 계속된다.


스텝 3 : 파일의 재생

이 스텝에서는, 전의 스텝에서 로드한 웨이브 파일을 IDirectMusicSegment8 인터페이스 경유로 퍼포먼스에 건네준다.

세그먼트(segment)를 재생하기 전에, 밴드를 신디사이저에 다운로드해 둘 필요가 있다. 밴드를 다운로드하지 않는 경우, 이 스텝은, 고유의 밴드를 사용하는 세그먼트(segment) 마다 1 회만 실행한다.

다음의 코드는, 샘플내의 WinMain 함수의 일부이다. 이 코드는, 밴드를 퍼포먼스에 다운로드한다. 밴드는 오디오 패스에 다운로드할 수도 있다. 사용하는 신디사이저가 1 개만의 경우는, 다운로드처로서 어느 쪽의 오브젝트를 선택해도 상관없다.

    g_pSegment->Download( g_pPerformance );

파일을 재생하려면, 세그먼트(segment)의 인터페이스를 IDirectMusicPerformance8::PlaySegmentEx 에 건네준다. 이 메소드에는 다수의 재생 옵션이 준비되어 있다. 다만, 디폴트의 오디오 패스로 즉시 세그먼트(segment)를 재생하려면 , 2 번째 이후의 파라미터를 모두 NULL 또는 0 으로 설정한다.

    g_pPerformance->PlaySegmentEx(
        g_pSegment,  // 재생하는 세그먼트(segment).
        NULL,        // 노래에 사용하는 파라미터. 이행되어 있지 않다.
        NULL,        // 트란지션에 관한 파라미터.
        0,           // 플래그.
        0,           // 시작 타임. 0 은 즉시 시작.
        NULL,        // 세그먼트(segment) 상태를 받는 포인터.
        NULL,        // 정지하는 오브젝트.
        NULL         // 디폴트가 아닌 경우는 오디오 패스.
    );
    MessageBox( NULL, "Click OK to Exit. ", "Play Audio", MB_OK );

다음의 「스텝 4 : 종료 처리」에 계속된다.


스텝 4 : 종료 처리

오디오 어플리케이션을 정상적으로 종료하려면 , 다음의 4 개의 주된 순서를 실행할 필요가 있다.

  • IDirectMusicPerformance8::Stop 를 호출해 재생중의 세그먼트(segment)를 모두 정지한다.
  • 퍼포먼스의 종료 처리를 실시한다. IDirectMusicPerformance8::CloseDown 메소드를 사용해, 그 외의 클린 업 태스크를 실행해, 오브젝트에의 내부 참조를 해방한다.
  • 모든 인터페이스를 해방한다.
  • COM 를 닫는다.

다음의 샘플 코드는, 튜토리얼 샘플내의 WinMain 함수의 일부이다. 다이알로그 박스를 종료 하면나무는 이 코드가 불려 간다.

    g_pPerformance->Stop(
        NULL,   // 모든 세그먼트(segment)를 정지한다.
        NULL,   // 모든 세그먼트(segment) 상태를 정지한다.
        0,      // 즉시 실행한다.
        0       // 플래그.
    );

    g_pPerformance->CloseDown();

    g_pLoader->Release();
    g_pPerformance->Release();
    g_pSegment->Release();

    CoUninitialize();

    return 0;  // WinMain 의 반환값.
}              // WinMain 의 종료.


튜토리얼 2 : 오디오 패스 오브젝트의 사용법

이 튜토리얼에서는, DirectMusic 퍼포먼스를 설정하는 방법과 오디오 패스로부터 오브젝트를 취득해 사운드 파라미터를 변경하는 방법에 대해 스텝바이스텝으로 설명한다. 튜토리얼 샘플에서는, 오디오 패스로부터 3D 버퍼를 취득한다. 이 튜토리얼은, 다음의 스텝으로부터 구성되어 있다.

  • 스텝 1 : 오디오 패스의 생성
  • 스텝 2 : 버퍼의 취득
  • 스텝 3 : 버퍼의 파라미터의 변경

튜토리얼로 사용하고 있는 샘플 코드 전체의 파일이 다음의 폴더에 있다.

\mssdk\samples\Multimedia\DirectMusic\Tutorials\Tut2

주 DirectX SDK 가 인스톨 되고 있는 루트 디렉토리가 다른 경우는, 패스내의 "mssdk" 를 그 디렉토리의 이름에 옮겨놓을 필요가 있다.

이 튜토리얼은, 퍼포먼스 오브젝트 및 로더 오브젝트의 생성과 파일의 로드 및 재생에 대한 기본적인 순서를 이해하고 있는 것을 전제로 하고 있다. 이러한 순서에 대해서는 「튜토리얼 1 : 오디오 파일의 재생」으로 설명되고 있다.


스텝 1 : 오디오 패스의 생성

오디오 패스를 생성 하는 가장 간단한 방법은,IDirectMusicPerformance8::InitAudio 에 플래그를 건네주는 방법이다. 이 튜토리얼 샘플에서는, DMUS_APATH_DYNAMIC_STEREO 플래그를 건네주어,InitAudio 로 스테레오 사운드를 지원 하는 디폴트의 오디오 패스를 셋업 한다.

g_pPerformance->InitAudio(
    NULL,                      // IDirectMusic 인터페이스는 불요.
    NULL,                      // IDirectSound 인터페이스는 불요.
    NULL,                      // 윈도우의 핸들.
    DMUS_APATH_DYNAMIC_STEREO, // 디폴트의 오디오파스타이프.
    64,                        // 퍼포먼스 채널의 수.
    DMUS_AUDIOF_ALL,           // 신디사이저의 기능.
    NULL                       // 오디오 파라미터에는 디폴트를 사용.
);

디폴트의 오디오 패스는, 배경 음악이나 나레이션 등, 공간내에 위치할 필요가 없는 사운드에 적절하고 있다. 다만, 어플리케이션으로 3D 사운드 이펙트를 이행 하는 경우는, 각각의 오디오 패스상에서 각 음원이 연주되기 (위해)때문에, 3D 파라미터를 개별적으로 설정할 수 있다.

다음의 샘플에서는, 그러한 오디오 패스를 1 개 생성 하고 있다.

IDirectMusicAudioPath8* p3DAudioPath = NULL;
g_pPerformance->CreateStandardAudioPath(
    DMUS_APATH_DYNAMIC_3D,      // 패스의 종류.
    64,                         // 퍼포먼스 채널의 수.
    TRUE,                       // 여기서 액티브하게 된다.
    &p3DAudioPath               // 오디오 패스를 받는 포인터.
);

A segment can now be played on this audiopath as follows:

g_pPerformance->PlaySegmentEx(
    g_pSegment,  // 재생하는 세그먼트(segment).
    NULL,        // 노래에 사용하는 파라미터. 이행되어 있지 않다.
    NULL,        // 트란지션에 관한 파라미터.
    0,           // 플래그.
    0,           // 시작 타임. 0 은 즉시 시작.
    NULL,        // 세그먼트(segment) 상태를 받는 포인터.
    NULL,        // 정지하는 오브젝트.
    p3DAudioPath // Audiopath.
);

다음의 「스텝 2 : 버퍼의 취득」에 계속된다.


스텝 2 : 버퍼의 취득

IDirectMusicAudioPath8::GetObjectInPath 메소드를 사용해, 패스의 일부를 형성하는 오브젝트에의 인터페이스를 취득할 수가 있다. DMUS_APATH_DYNAMIC_3D 표준 오디오 패스형의 경우, 이러한 오브젝트에는, 세칸다리밧파 그 자체, 프라이머리 버퍼, DirectSound 청취자, 또는 오디오 패스의 생성 후에 버퍼상으로 설정되는 DMO 가 포함된다. 이 튜토리얼 샘플은, 버퍼에의 IDirectSound3DBuffer8 인터페이스를 취득한다.

IDirectSound3DBuffer8* pDSB = NULL;

p3DAudioPath->GetObjectInPath(
    DMUS_PCHANNEL_ALL,        // 퍼포먼스 채널.
    DMUS_PATH_BUFFER,         // 패스내의 단계.
    0,                        // 체인내의 버퍼의 인덱스.
    GUID_NULL,                // 오브젝트의 클래스.
    0,                        // 버퍼내의 오브젝트의 인덱스. 무시.
    IID_IDirectSound3DBuffer, // 목적의 인터페이스의 GUID.
    (LPVOID*) &pDSB           // 인터페이스를 받는 포인터.
);

IDirectMusicAudioPath8::GetObjectInPath 의 파라미터는, 설정이 조금 복잡하게 되어 있다. 패스내의 각 단계의 오브젝트에 대응한 파라미터에 대해서는, 「오디오 패스로부터의 오브젝트의 취득」을 참조할것.

튜토리얼 샘플에서는, 이 오디오 패스 위에의 모든 퍼포먼스 채널로 사용되는 세칸다리밧파를 취득한다. dwPChannel 파라미터를 DMUS_PCHANNEL_ALL 로 설정한다.

취득하는 것은 1 번째의 버퍼로, 이 경우는 체인내에 1 개의 버퍼 밖에 존재하지 않기 때문에,dwBuffer 로서 0 을 건네준다. DMUS_PATH_BUFFER 스테이지는 버퍼 오브젝트만을 포함해, 그러한 버퍼에 부가된 DMO 는 포함하지 않는다. 이 때문에,dwIndex 는 무시된다.

다음의 「스텝 3 : 버퍼의 파라미터의 변경」에 계속된다.


스텝 3 : 버퍼의 파라미터의 변경

취득한 IDirectSound3DBuffer8 인터페이스를 사용해, 공간내에서 사운드를 이동한다. 튜토리얼 샘플 어플리케이션에서는, 일련의 메시지 박스를 닫을 때 이 처리를 실행한다. 예를 들어, 다음의 코드는, 사운드를 즉시 왼쪽으로 이동한다.

pDSB->SetPosition( -0. 1f, 0.0f, 0.0f, DS3D_IMMEDIATE );

최초의 3 개의 파라미터는, 음원의 새로운 위치를 디폴트의 청취자와의 상대적인 위치에서 지정한다. 디폴트의 청취자는 좌표 (0.0, 0.0, 0.0)에 있어, 정면은 z 축의 정의 방향을 향해, 머리의 꼭대기는 y 축의 정의 방향을 향하고 있다. 디폴트의 거리의 단위는 미터이다. x 축의 정의 방향은 왼쪽에서 오른쪽이므로, 사운드의 새로운 위치는 청취자의 왼쪽 10 cm 의 곳이 된다. 상세한 것에 대하여는, 「3D 공간의 좌표」 및 「청취자의 방향」을 참조할것.

IDirectSound3DBuffer8::SetPosition 메소드의 마지막 파라미터는, 변경을 즉시 반영하는지, 모든 변경이 실행되고 나서 반영하는지를 지정한다. 상세한 것에 대하여는, 「지연 설정」을 참조할것.


DirectX Audio C++ 샘플

여기서 가리키는 샘플 어플리케이션에는, Microsoft® DirectX® for C++ 의 Microsoft® DirectMusic® 및 Microsoft® DirectSound® 어플리케이션 프로그래밍 인터페이스 (API)의 사용법과 기능이 나타나고 있다.

각 주제로, 다음의 2 종류의 샘플에 대해 설명한다.

  • DirectMusic C++ 샘플 . 이러한 샘플은, DirectMusic API 를 사용해 사운드를 로드해 재생하고 있다. 일부의 샘플에서는, DirectSound API 요소를 사용하고 있다.
  • DirectSound C++ 샘플 . 이러한 샘플은, DirectSound API 만을 사용하고 있다. 다만, 여기에 나타나는 테크닉의 상당수는, DirectMusic 오디오 패스로부터 취득한 버퍼와 함께 사용할 수도 있다.


DirectMusic C++ 샘플

다음에 나타내는 실행 가능 어플리케이션은, DirectMusic API 마셔 또는 DirectSound 과 DirectMusic 의 양쪽 모두를 사용하고 있다. 이러한 어플리케이션을 실행하려면 ,[스타트] 메뉴의 [프로그램] 을 포인트 한다. 다음에,[Microsoft DirectX8 SDK] 를 포인트 해,[DirectMusic Samples] 를 클릭한다.

  • 3DAudio
  • AudioFX
  • AudioPath
  • AudioScripts
  • MusicTool
  • PlayAudio
  • PlayMotif

원시 코드는 다음의 폴더에 있다.

\mssdk\samples\Multimedia\DirectMusic

이러한 샘플 외에, 다음의 폴더에, 튜토리얼 어플리케이션의 원시 파일이 있다.

\mssdk\samples\Multimedia\DirectMusic\Tutorials

상세한 것에 대하여는, 「DirectX Audio C++ 튜토리얼」을 참조할것.

튜토리얼 이외의 샘플은, 공통의 원시 파일을 사용하고 있다. 이러한 파일은, DirectMusic 및 DirectSound 의 기본적인 기능과 미디어 파일의 검색등이 일반적인 태스크에 사용되는 함수 및 클래스를 이행 하고 있다. 파일은 다음의 장소에 있다.

\mssdk\samples\Multimedia\Common\src

주 DirectX SDK 가 인스톨 되고 있는 루트 디렉토리가 다른 경우는, 모든 패스로 "mssdk" 를 그 디렉토리의 이름에 옮겨놓을 필요가 있다.


3DAudio

설명

3DAudio 샘플 어플리케이션은, DirectMusic 퍼포먼스내에 3D 오디오 패스를 생성 하는 방법, 그 패스의 3D 버퍼 및 청취자에게로의 인터페이스를 취득하는 방법, 및 버퍼와 청취자의 파라미터를 변경하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectMusic\3DAudio

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectMusic\Bin

유저즈 가이드

[Open File] 를 클릭해, 웨이브, MIDI, 또는 DirectMusic 의 세그먼트(segment) 파일을 로드한다. 세그먼트(segment)를 재생한다. 음원의 위치가 그래프상에 붉은 점으로써 나타난다. 이 그래프에서는, x 축이 왼쪽에서 오른쪽을 향해, z 축이 아래에서 위로 향하고 있다. 슬라이더를 사용해, 2 개의 좌표축 위에의 이동 범위를 변경한다.

청취자는 그래프의 중앙에 위치해, 디폴트의용을 적합하다. 디폴트의 방향은, z 축의 정의 방향, 즉 화면의 윗방향이다. 음원은 청취자의 좌우 전후로 이동해, 상하에는 이동하지 않는다.

윈도우의 중앙에 있는 슬라이더는, 청취자의 프로퍼티, 즉 글로벌 사운드 프로퍼티를 제어한다. [Defer Settings] 를 클릭 하면, 변경은, 다음에 [Apply Settings] 를 클릭할 때까지 적용되지 않는다.

프로그래밍 메모

원시 코드 폴더의 Readme.txt 를 참조할것.

참조

3D 사운드,오디오 패스로부터의 오브젝트의 취득


AudioFX

설명

AudioFX 샘플은, DirectMusic 오디오 패스로 DMO 를 사용해 사운드에 이펙트를 추가하는 방법, 및 이펙트 파라미터를 설정하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectMusic\AudioFX

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectMusic\Bin

유저즈 가이드

어플리케이션을 실행 하면, 디폴트의 사운드 파일이 로드 된다. 다른 파일을 로드하는 경우는,[Open File] 를 클릭해 파일을 선택한다.

처음은, 이펙트가 유효하게 되지 않았다. [Play] 를 클릭해, 이펙트없이 사운드를 (듣)묻는다.

[Stop] 를 클릭해, 버퍼를 정지한다. [Enable] 의 체크 박스를 온으로 해, 1 개(살) 또는 복수의 이펙트를 적용한다. 사운드를 한번 더 재생한다.

이펙트의 파라미터를 조정하려면 ,[Adjust] 로 옵션 버튼을 선택해, 윈도우의 우측의 프레임에 있는 값을 변경한다. 이 조정은, 사운드의 재생 그 중에서, 이펙트의 적용전이라도 실행할 수 있다.

프로그래밍 메모

어플리케이션은 이펙트를 관리하기 위한 CSoundFXManager 클래스를 이행 하고 있다. CSoundFXManager::Initialize 메소드에서는, 오디오 패스로부터 IDirectSoundBuffer8 인터페이스를 취득한다. 이 인터페이스는, CSoundFXManager::ActivateFX 메소드로 버퍼에 이펙트를 설정하기 위해서 사용된다. Effect 파라미터는, 인터페이스로부터의 메세지에 응답해, OnEffectChanged 함수로 설정된다.

참조

이펙트의 사용법


AudioPath

설명

AudioPath 샘플은, 1 개의 오디오 패스로 복수가 다른 사운드를 재생하는 방법과 오디오 패스에서의 변경이 모든 사운드의 파라미터에게 주는 영향을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectMusic\AudioPath

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectMusic\Bin

유저즈 가이드

[Lullaby],[Snore], 및 [Mumble] 를 클릭해 다양한 사운드를 재생한다. 슬라이더를 사용해, 3D 공간에서의 사운드의 위치를 조정한다. [Rude Awakening] 를 클릭 하면, 다른 1 개의 사운드를 재생해 다른 모든 사운드를 정지할 수가 있다.

프로그래밍 메모

이 샘플은,PlayAudio 샘플과 형식이 자주(잘) 비슷하다. AudioPath 는, 오디오 패스의 다양한 사용법을 몇개인가 가리키고 있다.

WM_INITDIALOG 로, OnInitDialog 함수는 다음의 처리를 실시한다.

  1. IDirectMusicPerformance8::CreateStandardAudioPath 를 호출해, DMUS_APATH_DYNAMIC_3D 에 건네주어,IDirectMusicAudioPath8 인터페이스 g_p3DAudiopath 에 의해 나타나는 3D 오디오 패스를 생성 한다.
  2. CMusicManager 체제 클래스를 사용해, 파일의 리스트로부터 CMusicSegment 오브젝트를 생성 한다.
  3. 오디오 패스로부터 IDirectSound3DListener8 인터페이스를 취득한다.
  4. IDirectSound3DListener8::SetRolloffFactor 를 호출해, 사운드의 진폭이 거리가 떨어지는 것에 따라 소멸 하면나무의 비율을 변경한다.

3D 위치 슬라이더가 변경되면(자), SetPosition 함수는 이하의 처리를 실행한다.

  1. IDirectMusicAudioPath8::GetObjectInPath 를 호출해 IDirectSound3DBuffer8 인터페이스를 취득한다.
  2. IDirectSound3DBuffer8::SetPosition 를 호출해 버퍼의 위치를 설정한다.
  3. 버퍼를 해방한다.

세그먼트(segment)를 재생 하면, PlaySegment 함수는 이하의 처리를 실행한다.

  • [Lullaby] 를 클릭 하면, 세그먼트(segment)가 프라이머리 세그먼트(segment)로서 오디오 패스상에서 재생된다.
  • [Snore] 또는 [Mumble] 를 클릭 하면, 세칸다리세그먼트가 재생된다.
  • [Rude Awakening] 를 클릭 하면, 오디오 패스가 pFrom 파라미터로서 IDirectMusicPerformance8::PlaySegmentEx 에게 건네지기 (위해)때문에, 오디오 패스 위에의 모든 사운드가 정지된다. 다음에, 새로운 프라이머리 세그먼트(segment)로서 알람 사운드가 재생된다.

참조

오디오 패스의 사용법


AudioScripts

설명

AudioScripts 샘플은, 어플리케이션과 DirectMusic 스크립트의 제휴를 나타낸다. 스크립트는 어플리케이션내의 변수를 읽고 쓰기해, 어플리케이션은 스크립트내의 세그먼트(segment)를 재생하는 루틴을 호출한다.

이 샘플은, 1 개의 세그먼트(segment)내의 다양한 바리에이션으로서 웨이브를 재생하는 방법도 가리킨다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectMusic\AudioScripts

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectMusic\Bin

유저즈 가이드

[Script File] 박스의 일람으로부터 [ScriptDemoBasic.spt] 를 선택한다. [Routine 1] 을 클릭해 세그먼트(segment)를 연주한다. [Routine 2] 를 클릭해 엔딩을 연주해, 재생을 정지한다. 세그먼트(segment)를 재차 연주해,[Routine 3] 을 여러 차례 클릭한다. [Variable 1] 에, 버튼을 클릭한 회수가 표시되어 버튼을 클릭할 때마다 음악이 바뀐다.

[Script File] 박스의 일람으로부터 [ScriptDemoBaseball.spt] 를 선택한다. [Routine 1] 을 클릭해, 벤더로부터의 다양한 호출을 재생한다. [Routine 2] 를 클릭해, 다양한 음악 모티프를 재생한다. [Variable1] 박스 및 [Variable2] 박스에 다른 값을 입력해 스코아를 변경한다. [Routine 3] 을 클릭해 스코아를 (듣)묻는다.

프로그래밍 메모

원시 코드 폴더의 Readme.txt 를 참조할것.

참조

오디오 스크립트의 사용법


MusicTool

설명

MusicTool 샘플은, 메세지를 삽입하는 DirectMusic 툴을 이행 하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectMusic\MusicTool

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectMusic\Bin

유저즈 가이드

디폴트의 세그먼트(segment)를 재생하는지,[Open File] 를 클릭해 다른 웨이브, MIDI, 또는 DirectMusic 세그먼트(segment) 파일을 선택한다. 드롭 다운 리스트로부터 [Echo Tool] 를 선택해 메아리 이펙트를 적용한다.

프로그래밍 메모

원시 코드 폴더의 Readme.txt 를 참조할것.

참조

DirectMusic 툴


PlayAudio

설명

PlayAudio 샘플은, 세그먼트(segment)를 로드해 오디오 패스로 재생하는 방법, DirectMusic 통지를 사용하는 방법, 및 글로벌 퍼포먼스 파라미터를 변경하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectMusic\PlayAudio

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectMusic\Bin

유저즈 가이드

디폴트의 세그먼트(segment)를 재생하는지,[Open File] 를 클릭해 다른 웨이브, MIDI, 또는 DirectMusic 세그먼트(segment) 파일을 로드한다. 슬라이더를 사용해 템포와 볼륨을 조정한다.

프로그래밍 메모

WM_INITDIALOG 로, OnInitDialog 함수는 다음의 처리를 실시한다.

  1. Win32® 이벤트 g_hDMusicMessageEvent 를 생성 한다. DirectMusic 통지를 수신할 때마다, DirectMusic 는 이 이벤트를 사용해 어플리케이션에 통지한다.
  2. CMusicManager 클래스의 오브젝트 g_pMusicManager 를 생성 한다.
  3. CMusicManager 오브젝트를 초기화한다. 이것에 의해 다음의 처리를 한다.
    • CoCreateInstance 를 사용해 IDirectMusicLoader8 를 생성 한다.
    • CoCreateInstance 를 사용해 IDirectMusicPerformance8 를 생성 한다.
    • IDirectMusicPerformance8::InitAudio 를 호출해 퍼포먼스를 초기화해, 표준적인 오디오 패스를 생성 한다.
  4. IDirectMusicPerformance8::AddNotificationType 를 호출해 GUID_NOTIFICATION_SEGMENT 형의 통지를 요구한다. 어플리케이션이 세그먼트(segment)의 종료를 확인할 수 있도록(듯이), DirectMusic 는 모든 세그먼트(segment) 이벤트를 어플리케이션에 통지한다.
  5. IDirectMusicPerformance8::SetNotificationHandle 를 호출해 Win32 이벤트 g_hDMusicMessageEvent 를 건네준다. 이것을 받은 DirectMusic 는, 통지를 이용할 수 있을 때 이 이벤트를 통지한다.

WinMain 함수는 다음의 태스크를 실행한다.

  1. CreateDialog 를 사용해 윈도우를 생성 한다.
  2. 메시지 루프내에서,MsgWaitForMultipleObjects 를 호출해 g_hDMusicMessageEvent 를 건네준다. 이것을 받는 것에 의해,g_hDMusicMessageEvent 이 통지된 것을 알 수 있다. DirectMusic 은, DirectMusic 통지를 수신할 때마다 이 이벤트를 통지한다.
  3. WAIT_OBJECT_0 가 돌려주어졌을 경우는, ProcessDirectMusicMessages 를 호출한다.
  4. WAIT_OBJECT_0 + 1 이 돌려주어졌을 경우는, Windows 메세지를 이용할 수 있다. 이 함수는,PeekMessage 를 사용해 메세지의 표준적인 처리를 실시한다.

[Open File] 를 클릭 하면, OnOpenSoundFile 함수에 의해 다음의 태스크가 실행된다.

  1. 파일명을 취득한다.
  2. 이전에 생성 한 세그먼트(segment)가 있으면, 이것을 해방한다.
  3. Dmutil.cpp 내의 CMusicManager::CollectGarbage 를 호출한다. 이것에 의해 IDirectMusicLoader8::CollectGarbage 가 불려 가 미사용 오브젝트가 해방된다. 「가베지 콜렉션」을 참조할것.
  4. CMusicManager::SetSearchDirectory 를 호출한다. IDirectMusicLoader8::SetSearchDirectory 가 불려 가 GUID_DirectMusicAllTypes 와 디렉토리가 건네받는다. 이것에 의해, 세그먼트(segment)에 의해 참조되는 파일의 장소가 DirectMusic 에게 전할 수 있다.
  5. CMusicManager::CreateSegmentFromFile 를 호출해 g_pMusicSegment 로 불리는 CMusicSegment 를 생성 한다. 이 처리는 다음의 순서로 행해진다.
    • IDirectMusicLoader8::LoadObjectFromFile 를 호출해 IDirectMusicSegment8 를 pSegment 에 로드한다.
    • CMusicSegment 를 생성 해 pSegment 를 건네준다.
    • 파일이 순수한 MIDI 파일의 경우는,IDirectMusicSegment8::SetParam 를 호출해 GUID_StandardMIDIFile 를 건네준다. 이것에 의해, 파일을 올바르게 재생할 수 있게 된다.
    • IDirectMusicSegment8::Download 를 호출해 세그먼트(segment)의 밴드를 신디사이저에 다운로드한다. 어플리케이션에 따라서는, 다운로드에 시간이 걸리는 경우가 있다. 이것은, 다운로드하는 음색의 수가 많으면 많을수록, 메모리의 소요량도 커지기 때문이다.

[Play] 를 클릭 하면, OnPlayAudio 함수에 의해 다음의 처리를 한다.

  1. 그 사운드를 루프 하는 경우는, CMusicSegment::SetRepeats 를 호출해 DMUS_SEG_REPEAT_INFINITE 를 건네준다. 루프 하지 않는 경우는, 반복을 0 으로 설정한다.
  2. CMusicSegment::Play 을 호출해 IDirectMusicPerformance8::PlaySegmentEx 를 호출한다.

통지를 하면(자), ProcessDirectMusicMessages 함수는 세그먼트(segment)가 정지된 것을 나타내는 메세지를 검색한다. 다음의 태스크가 실행된다.

  1. 루프내에서 IDirectMusicPerformance8::GetNotificationPMsg 를 호출해 이용 가능한 각 메세지를 처리한다. S_OK 가 돌려주어지는 한 루프는 반복해진다. 이용 가능한 메세지가 없어지면(자), S_FALSE 가 돌려주어진다.
  2. DMUS_NOTIFICATION_PMSG 구조체의 dwNotificationOption 가 DMUS_NOTIFICATION_SEGEND 의 경우는,punkUser 멤버상에서 QueryInterface 를 호출해, 종료한 세그먼트(segment) 인스턴스의 IDirectMusicSegmentState8 인터페이스를 취득한다. IDirectMusicSegmentState8::GetSegment 를 사용 하면, 세그먼트(segment) 자체가 취득된다. 이 메소드는 IDirectMusicSegment 를 돌려준다. IDirectMusicSegment8 를 취득하려면 QueryInterface 를 사용할 필요가 있다. 어플리케이션은 이 포인트를 글로벌 프라이머리 세그먼트(segment)의 포인터와 비교해, 그것이 정말로 정지된 프라이머리 세그먼트(segment)인 것을 확인한다. DirectMusic Producer 로 생성 한 세그먼트(segment)를 다른 세그먼트(segment)의 방아쇠로 할 수가 있다. 이 때문에, 재생되고 있었던 것이 프라이머리 세그먼트(segment) 뿐이다고는 할 수 없다.
  3. 모든 인터페이스를 클린 업 한다.


PlayMotif

설명

PlayMotif 샘플은, 세칸다리세그먼트로서 재생되는 모티프를 프라이머리 세그먼트(segment)의 리듬에 할당하는 다양한 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectMusic\PlayMotif

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectMusic\Bin

유저즈 가이드

디폴트의 세그먼트(segment)를 재생하는지, 모티프를 포함한 스타일에 근거하는 다른 DirectMusic 세그먼트(segment)를 로드한다. 리스트 박스로부터 패턴을 1 개 선택해,[Align Option] 버튼을 1 개 선택해,[Play Motif] 를 클릭한다. 프라이머리 세그먼트(segment)의 적절한 경계에 도달할 때까지, 모티프의 재생은 시작 되지 않는다.

프로그래밍 메모

PlayMotif 샘플은, PlayAudio 샘플과 형식이 자주(잘) 비슷하다. 이 샘플을 기본으로 한 노트의 프로그래밍의 상세한 것에 대하여는, 「PlayAudio 」를 참조할것.

파일을 로드할 때, PlayMotif 는, PlayAudio 와 같은 순서를 실행한 후, LoadSegmentFile 함수를 실행한다.

  1. 루프 처리에 의해, 세그먼트(segment)에 포함되는 스타일내의 모티프를 검색한다. IDirectMusicSegment8::GetParam 를 호출해, GUID_IDirectMusicStyle 와 인크리먼트(increment) 하는 인덱스를 건네주어, 각 스타일을 취득한다. 이 메소드는, 다음에 검색해야 할 스타일이 없어지면(자) 실패한다.
  2. 각 스타일에 대해서,IDirectMusicStyle8::EnumMotif 를 호출해, 인크리먼트(increment) 하는 모티프 인덱스를 건네준다. 이 호출은, 그 인덱스를 사용해 모티프명을 취득한다. S_FALSE 가 돌려주어졌을 경우는, 그 스타일내에 그 밖에 모티프가 없는 것을 의미한다.

모티프명을 IDirectMusicStyle8::GetMotif 에 건네주어, 모티프에의 IDirectMusicSegment8 인터페이스 포인터를 취득해, 이것을 리스트 박스내의 항목으로 관련지을 수 있었던 데이터로서 보존한다.

[Play Motif] 를 클릭 하면, OnPlayMotif 함수에 의해 다음의 태스크가 실행된다.

  1. 인터페이스로부터 목적의 아라이먼트오프션을 취득한다.
  2. 리스트 박스로부터 선택된 모티프와 그 MOTIF_NODE 항목 데이터를 취득한다. MOTIF_NODE 구조체는, 현재 재생되고 있는 연주의 회수의 카운트와 모티프의 IDirectMusicSegment 인터페이스에의 포인터를 보관 유지한다.
  3. IDirectMusicPerformance8::PlaySegment 를 호출해, 모티프의 IdirectMusicSegment, DMUS_SEGF_SECONDARY 등의 플래그, 및 아라이먼트오프션을 건네준다.

DirectMusic 통지는, 보통, PlayAudio 내에서 처리된다. 다만, 이 어플리케이션은, 시작 또는 종료하는 모티프의 노트를 취득해 MOTIF_NODE 구조 체내의 연주 카운트를 갱신한다. 연주 카운트가 0 보다 크면 유저 인터페이스를 갱신해 그 모티프가 재생중인 것을 나타낸다.

참조

모티프의 사용법


DirectSound C++ 샘플

다음에 나타내는 실행 가능 어플리케이션은 DirectSound API 를 사용하고 있다. 이러한 어플리케이션을 실행하려면 ,[스타트] 메뉴의 [프로그램] 을 포인트 한다. 다음에,[Microsoft DirectX8 SDK] 를 포인트 해,[DirectSound Samples] 를 클릭한다.

  • AdjustSound
  • AmplitudeModulation
  • CaptureSound
  • EnumDevices
  • FullDuplexFilter
  • Play3DSound
  • PlaySound
  • SoundFX
  • StreamData
  • VoiceManagement

원시 코드는 다음의 폴더에 있다.

\mssdk\samples\Multimedia\DirectSound

이러한 샘플 외에, 다음의 폴더에, 튜토리얼 어플리케이션의 원시 파일이 있다.

\mssdk\samples\Multimedia\DirectSound\Tutorials

상세한 것에 대하여는, 「DirectX Audio C++ 튜토리얼」을 참조할것.

튜토리얼 이외의 샘플은, 공통의 원시 파일을 사용하고 있다. 이러한 파일은, DirectMusic 및 DirectSound 의 기본적인 기능과 미디어 파일의 검색등이 일반적인 태스크에 사용되는 함수 및 클래스를 이행 하고 있다. 파일은 다음의 장소에 있다.

\mssdk\samples\Multimedia\Common\src

주 DirectX SDK 가 인스톨 되고 있는 루트 디렉토리가 다른 경우는, 모든 패스로 "mssdk" 를 그 디렉토리의 이름에 옮겨놓을 필요가 있다.


AdjustSound

설명

AdjustSound 샘플은, DirectSound 세칸다리밧파를 생성 해 웨이브 파일을 재생하는 방법과 버퍼의 파라미터를 변경하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\AdjustSound

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

[Sound File] 를 클릭해 웨이브 파일을 로드한다. [Focus] 옵션 및 [Buffer Mixing] 옵션을 선택한다. 옵션의 선택에 응해, 다양한 설정이 [Expected Behavior] 에 표시된다. [Play] 를 클릭한다. 아무것도 사운드가 들리지 않는 경우는,[Status] 페인을 확인한다. 이 옵션이 선택되어 있지 않으면 어플리케이션이 하드웨어에 버퍼를 생성 할 수 없는 경우가 있다.

버퍼의 재생중에, 슬라이더를 사용해 주파수, 빵, 및 볼륨을 동적으로 조정한다.

프로그래밍 메모

보다 적은 컨트롤로 간단하게 DirectSound 버퍼를 설정하는 방법의 예에 대해서는,PlaySound 샘플을 참조할것.

어플리케이션은, DSBCAPS_GLOBALFOCUS 또는 DSBCAPS_STICKYFOCUS 를 설정하는지, 그 어느 플래그도 설정하지 않고 IDirectSound8::CreateSoundBuffer 를 호출해, 버퍼의 포커스의 동작을 설정한다. 버퍼의 메모리의 장소를 설정하려면 , DSBCAPS_LOCHARDWARE 또는 DSBCAPS_LOCSOFTWARE 를 설정하는지, 그 어느 플래그도 설정하지 않는다. 어느 플래그도 설정하지 않는 경우는, DirectSound 에 의해 하드웨어소프트웨어에 버퍼가 생성 된다.

파라미터는,IDirectSoundBuffer8::SetFrequency ,IDirectSoundBuffer8::SetPan , 및 IDirectSoundBuffer8::SetVolume 를 사용해 설정된다.

참조

DirectSound 버퍼


AmplitudeModulation

설명

AmplitudeModulation 샘플은, DirectSound 세칸다리밧파에 이펙트를 적용하는 방법과 이펙트의 파라미터를 변경하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\AmplitudeModulation

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

디폴트의 사운드를 재생하는지,[Sound File] 를 클릭해 다른 웨이브 파일을 로드한다. 이펙트의 파라미터를 변경하려면 ,[Wave Form] 옵션의 어느쪽이든을 선택해, 슬라이더를 이동해 변조의 강도를 변경한다.

프로그래밍 메모

어플리케이션은, 다음의 순서를 실행해 버퍼 위에의 이펙트의 설정과 이펙트의 파라미터의 변경을 실시한다.

  1. DSBCAPS_CTRLFX 플래그를 사용해 버퍼를 생성 한다.
  2. 목적의 이펙트의 GUID 에 guidDSFXClass 멤버를 설정하는 것에 의해,DSEFFECTDESC 구조체로 이펙트를 기술한다.
  3. 버퍼 기술을 IDirectSoundBuffer8::SetFX 에 건네준다.
  4. IDirectSoundBuffer8::GetObjectInPath 를 호출해, 이펙트에의 인터페이스 포인터를 취득한다. 이 예에서는 IDirectSoundFXGargle8 를 취득한다.
  5. OnEffectChanged 함수로,IDirectSoundFXGargle8::SetAllParameters 를 사용해 가그르에페크트의 파라미터를 변경한다.

참조

이펙트의 사용법


CaptureSound

설명

CaptureSound 어플리케이션은, 웨이브 사운드를 파일에 캡춰 하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\CaptureSound

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

디바이스 및 포맷을 선택한다. 파일을 생성 하는지,[Sound File] 를 클릭해 기존의 파일을 옮겨놓는다. [Record] 를 클릭해 레코딩을 시작 및 정지한다.

프로그래밍 메모

원시 코드 폴더의 Readme.txt 를 참조할것.

참조

웨이브의 캡춰


EnumDevices

설명

EnumDevices 샘플은, 재생 디바이스와 캡춰 디바이스를 열거 및 생성 하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\EnumDevices

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

드롭 다운 리스트로부터 재생 디바이스와 캡춰 디바이스를 선택한다. [Create] 를 클릭한다.

프로그래밍 메모

원시 코드 폴더의 Readme.txt 를 참조할것.

참조

사운드 디바이스의 열거,캡춰 디바이스의 열거


FullDuplexFilter

설명

FullDuplexFilter 어플리케이션은, 사운드의 캡춰와 재생을 동시에 실시하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\FullDuplexFilter

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

사운드 카드가 전이중 구성이 되어 있는 것으로, 마이크가 접속되고 있는 것을 확인한다. [Output Format] 박스의 일람으로부터 포맷을 선택한다. [Input Format] 박스에 포맷의 일람이 표시된다. 1 개(살)을 선택한다. [OK] 를 클릭한다. 전이중이 올바르고 생성 되면(자),[Record] 버튼이 있는 다른 다이알로그 박스가 표시된다. 이 버튼을 클릭한다. 마이크를 향해 이야기하면(자), 그 소리가 스피커로부터 들린다.

프로그래밍 메모

원시 코드 폴더의 Readme.txt 를 참조할것.


Play3DSound

설명

Play3DSound 샘플은, 3D 사운드 버퍼를 생성 하는 방법과 그 프로퍼티를 조작하는 방법을 나타낸다. 3DAudio 샘플을 닮아 있지만, 이것은 DirectSound API 만을 사용한다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\Play3DSound

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

[Sound File] 를 클릭해 웨이브 파일을 로드한다. 사운드를 재생한다. 음원의 위치가 그래프상에 붉은 점으로써 나타난다. 이 그래프에서는, x 축이 왼쪽에서 오른쪽을 향해, z 축이 아래에서 위로 향하고 있다. 슬라이더를 사용해, 2 개의 좌표축 위에의 이동 범위를 변경한다.

청취자는 그래프의 중앙에 위치해, 디폴트의용을 적합하다. 디폴트의 방향은, z 축의 정의 방향, 즉 화면의 윗방향이다. 음원은 청취자의 좌우 전후로 이동해, 상하에는 이동하지 않는다.

윈도우의 중앙에 있는 슬라이더는, 청취자의 프로퍼티, 즉 글로벌 사운드 프로퍼티를 제어한다. [Defer Settings] 를 클릭 하면, 변경은, 다음에 [Apply Settings] 를 클릭할 때까지 적용되지 않는다.

프로그래밍 메모

3D 컨트롤을 사용하지 않고 간단하게 DirectSound 버퍼를 설정하는 방법의 예에 대해서는,PlaySound 샘플을 참조할것.

이 샘플은, 다음의 순서로 IDirectSound3DListener8 인터페이스를 취득한다.

  1. DSBCAPS_CTRL3D 플래그 및 DSBCAPS_PRIMARYBUFFER 플래그를 포함한 DSBUFFERDESC 구조체로 버퍼를 기술한다.
  2. 버퍼 기술을 IDirectSound8::CreateSoundBuffer 에 건네준다. 이것에 의해, 3D 기능을 가지는 프라이머리 버퍼가 생성 된다.
  3. QueryInterface 를 호출해 IDirectSound3DListener8 인터페이스를 취득한다. 이 인터페이스는 글로벌 3D 프로퍼티를 제어한다.

이 샘플은, 다음의 순서로 IDirectSound3DBuffer8 인터페이스를 취득한다.

  1. DSBUFFERDESC 구조체에 버퍼를 기술한다. 이 때, DSBCAPS_CTRL3D 기능의 플래그와 3D 가상화 알고리즘을 설정한다.
  2. 버퍼 기술을 IDirectSound8::CreateSoundBuffer 에 건네주어 3D 기능을 가지는 세칸다리밧파를 생성 한다.
  3. QueryInterface 를 호출해 IDirectSound3DBuffer8 인터페이스를 취득한다. 이 인터페이스는, 그 버퍼를 사용해 재생되는 사운드의 3D 프로퍼티를 제어한다.

어플리케이션은,IDirectSound3DListener8::SetAllParameters 를 호출해 청취자의 파라미터를 설정한다. 청취자의 프로퍼티는,DS3DLISTENER 구조체에 기술되고 있다. 어플리케이션은,IDirectSound3DBuffer8::SetAllParameters 를 호출해 DS3DBUFFER 구조체를 건네주어, 음원의 위치를 설정한다.

파라미터를 설정 하면 DS3D_DEFERRED 플래그가 설정된다. 변경은,IDirectSound3DListener8::CommitDeferredSettings 가 불려 갔을 때에 반영된다. 이 메소드는, 버퍼와 청취자의 설정의 반영을 늦추어, DirectSound 에 의한 계산이 한 번에 끝나도록(듯이) 하고 있다.

참조

3D 사운드


PlaySound

설명

PlaySound 샘플은, DirectSound 의 세칸다리밧파내의 웨이브 파일을 재생하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\PlaySound

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

[Sound File] 를 클릭해 웨이브 파일을 로드한다. 반복 재생하는 경우는,[Loop Sound] 를 선택한다. [Play] 를 클릭한다.

프로그래밍 메모

이 샘플은, DirectSound 버퍼내의 사운드를 재생하기 위해서 필요한, 다음의 기본적 태스크를 나타내고 있다.

DirectSound 의 설정

  1. DirectSoundCreate 함수를 호출해 DirectSound 오브젝트를 생성 한다.
  2. IDirectSound8::SetCooperativeLevel 를 호출한다.
  3. 프라이머리 버퍼 포맷을 설정한다. 이 샘플은, Dsutil.cpp 내의 DSUtil_SetPrimaryBufferFormat 함수를 호출해 이 처리를 실시한다.

DirectSound 버퍼에의 웨이브 파일의 로드

  1. 웨이브 파일 헤더를 읽어들여 데이터의 사이즈와 포맷을 취득한다.
  2. 웨이브 파일의 사이즈가 적절하면, 그 데이터와 같은 포맷으로, 파일 전체를 저장 할 수 있는 사이즈의 세칸다리밧파를 생성 한다. 웨이브 파일이 너무 큰 경우, 데이터는 버퍼에 스트리밍 된다. StreamData 샘플을 참조할것.
  3. 버퍼에 데이터를 기입한다. IDirectSoundBuffer8::Lock 를 호출해, 버퍼에의 포인터를 취득한다. 버퍼의 재생중은 데이터의 스트리밍은 행해지지 않기 때문에, 버퍼 전체를 잠글 수 있다. 메모리를 카피한 후,IDirectSoundBuffer8::Unlock 를 호출한다.

DirectSound 버퍼의 재생

  1. 버퍼가 없어지지 않은지 어떤지를 조사한다. 없어졌을 경우는 복원한다.
  2. IDirectSoundBuffer8::Play 를 호출해 버퍼를 재생한다.

DirectSound 의 해방

취득한 모든 DirectSound 인터페이스로 Release 를 호출한다. 버퍼를 해방하고 나서, DirectSound 오브젝트를 해방한다.

참조

스태틱 버퍼의 기입과 재생


SoundFX

설명

SoundFX 샘플은, DirectSound 로 DMO 를 사용하는 방법, 및 이펙트 파라미터의 조작 방법을 나타낸다. 이 샘플은 AudioFX 샘플을 닮아 있지만, 오디오 패스나 DirectMusic 인터페이스는 사용하지 않는다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\SoundFX

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

어플리케이션을 실행 하면, 디폴트의 사운드 파일이 로드 된다. 다른 파일을 로드하는 경우는,[Open File] 를 클릭해 다른 파일을 선택한다.

처음은, 이펙트가 유효하게 되지 않았다. [Play] 를 클릭해, 이펙트없이 사운드를 (듣)묻는다.

[Stop] 를 클릭해, 버퍼를 정지한다. [Enable] 의 체크 박스를 온으로 해, 1 개(살) 또는 복수의 이펙트를 적용한다. 사운드를 한번 더 재생한다.

이펙트의 파라미터를 조정하려면 ,[Adjust] 로 옵션 버튼을 선택해, 윈도우의 우측의 프레임에 있는 값을 변경한다. 이 조정은, 사운드의 재생 그 중에서, 이펙트의 적용전이라도 실행할 수 있다.

프로그래밍 메모

어플리케이션은 이펙트를 관리하기 위한 CSoundFXManager 클래스를 이행 하고 있다. IDirectSoundBuffer8 인터페이스는, CSoundFXManager::ActivateFX 메소드로 버퍼에 이펙트를 설정하기 위해서 사용된다. Effect 파라미터는, 인터페이스로부터의 메세지에 응답해, OnEffectChanged 함수로 설정된다.

참조

이펙트의 사용법,DirectSound 에서의 이펙트의 사용법


StreamData

설명

StreamData 샘플은, 웨이브 파일을 DirectSound 세칸다리밧파에 스트리밍 하는 방법을 나타낸다. PlaySound 샘플을 닮아 있지만, 이것에는 스트리밍의 지원이 추가되고 있다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\StreamData

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

[Sound File] 를 클릭해 웨이브 파일을 로드한다. 반복 재생하는 경우는,[Loop Sound] 를 선택한다. [Play] 를 클릭한다.

프로그래밍 메모

이 샘플은, DirectSound 세칸다리밧파내의 스트리밍 사운드를 재생하기 위해서 필요한 기본적 태스크를 나타내고 있다.

DirectSound 의 설정

  1. DirectSoundCreate8 함수를 호출해 DirectSound 오브젝트를 생성 한다.
  2. IDirectSound8::SetCooperativeLevel 를 호출한다.
  3. 프라이머리 버퍼 포맷을 설정한다. 이 샘플은, Dsutil.cpp 내의 DSUtil_SetPrimaryBufferFormat 함수를 호출해 이 처리를 실시한다.

DirectSound 버퍼의 생성과 통지의 설정

  1. 웨이브 파일 헤더를 읽어들여 데이터의 사이즈와 포맷을 취득한다.
  2. DirectSound 버퍼의 사이즈를 선택한다. 이 샘플에서는, 버퍼는 3 초간의 데이터를 보관 유지한다.
  3. 선택한 사이즈로, 웨이브 파일과 같은 포맷의 DirectSound 버퍼를 생성 한다. DSBCAPS_CTRLPOSITIONNOTIFY 플래그도 설정한다. 이것에 의해, 재생이 버퍼내의 특정의 포인트에 도달할 때마다 버퍼에 의해 통지 이벤트가 송신되게 된다. 하드웨어 버퍼가 위치의 통지를 지원 하고 있지 않는 드라이버에서는, 이 플래그의 사용은 소프트웨어 버퍼에 제한된다.
  4. 버퍼로부터 IDirectSoundNotify8 인터페이스를 취득해,IDirectSoundNotify8::SetNotificationPositions 를 호출해, 버퍼의 통지를 설정한다. InitDSoundNotification 함수를 참조할것. 재생 커서는, 통지 위치를 건네줄 때, Win32® 이벤트를 통지한다.

DirectSound 버퍼의 재생

  1. 버퍼가 없어지지 않은지 어떤지를 조사해 없어졌을 경우는 IDirectSoundBuffer8::Restore 를 호출한다.
  2. 버퍼 전체에 파일의 데이터를 기입한다.
  3. DSBPLAY_LOOPING 플래그를 설정해 IDirectSoundBuffer8::Play 를 호출한다. 루프 플래그를 설정 하면, 버퍼는 데이터의 최초의 배치를 재생한 후에 이어 재생을 실시한다.

통지를 하고 있는지 어떤지의 확인

  1. 메시지 루프로, 또는 MsgWaitForMultipleObjects 를 호출해 독립한 thread로, 통지된 이벤트를 찾는다.
  2. 버퍼의 통지 이벤트를 수신하고 있는 경우는, 버퍼의 마지막에 재생을 종료한 섹션을 잠그어, 거기에 새로운 데이터를 기입한다. HandleNotification 함수를 참조할것.

버퍼의 정지

이벤트 통지를 처리할 때는, 버퍼에 기입해진 데이터량을 상시 추적한다. 웨이브 파일 전체가 버퍼에 기입해져 그 내용 모든 것이 DirectSound 에 의해 재생되면(자), 버퍼를 수동으로 정지할 필요가 있다. 수동으로 정지하지 않으면 버퍼는 루프 계속 한다.

참조

스트림 버퍼의 사용법


VoiceManagement

설명

VoiceManagement 샘플은, DirectSound 세칸다리밧파의 생성시에 다이나믹 음성 관리를 이행 하는 방법을 나타낸다.

패스

소스 :(SDK 루트) \Samples\Multimedia\DirectSound\VoiceManagement

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectSound\Bin

유저즈 가이드

[Sound File] 를 클릭해 웨이브 파일을 로드한다. [Voice Allocation Flags],[Buffer Priority], 및 [Voice Management Flags] 의 각 옵션을 선택한다. 선택한 옵션의 이펙트의 설명이 [Expected Behavior] 에 표시된다. 버퍼를 생성 해,[Play] 를 클릭해 사운드를 재생한다.

프로그래밍 메모

음성 관리 플래그를 사용하려면 , DSBCAPS_LOCDEFER 를 사용해 버퍼를 생성 할 필요가 있다. 이것을 사용하지 않고 생성 하면, DirectSound 는, 실행시에 하드웨어와 소프트웨어의 어느 버퍼도 동적으로 배치할 수 없게 된다.

버퍼의 재생시에, 유효한 배합하고의 음성 관리 플래그를 설정해 IDirectSoundBuffer8::Play 를 호출한다. 샘플을 실행해, 플래그의 다양한 배합하고의 결과를 관찰한다.

참조

다이나믹 음성 관리


DirectMusic C/C++ 레퍼런스

여기에서는, DirectMusic 가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • DirectMusic 인터페이스
  • DirectMusic 메세지
  • DirectMusic 구조체
  • DLS 구조체
  • DirectMusic 의 파일 형식
  • DirectMusic 의 파일 데이터 구조체
  • 표준 트럭 파라미터
  • DirectMusic 열거형
  • DirectMusic 반환값


DirectMusic 인터페이스

여기에서는, DirectMusic COM 인터페이스의 레퍼런스를 기술한다.

현재의 버젼의 인터페이스는, 이름의 마지막에 "8" 을 붙여, 선언이나 정의를 실시한다. 최신 버젼의 인터페이스를 확실히 사용하려면 , 포인터의 선언시에 이 사픽스를 반드시 붙인다.

주 IKsControl 및 IReferenceClock 는, 이 규칙의 예외로 한다.

메소드가 취득하는 인터페이스는, 항상 기본 버젼이다. 기본 버젼보다 새로운 버젼이 존재하는 경우는, 다음의 예의 같게,QueryInterface 를 호출해 그것을 취득할 필요가 있다. lpdmBand 는,IDirectMusicBand8 인터페이스 포인터이다.

IDirectMusicSegment * lpdmseg;
IDirectMusicSegment8 * lpdmseg8;

HRESULT hr = lpdmBand->CreateSegment(&lpdmseg);
if (SUCCEEDED(hr))
{
    hr = lpdmseg->QueryInterface(IID_IDirectMusicSegment8,
        (LPVOID *) &lpdmseg8);
}

인터페이스의 새로운 버젼이 없는 경우, 사픽스 8 이 붙은 인터페이스명은, 단순한 정의이다. 예를 들어,IDirectMusicGraph8 는, 모든 점으로써 IDirectMusicGraph 와 동일하다. 이러한 경우, 새로운 인터페이스를 문의할 필요는 없지만, 문의를 하는 것은 아무해도 없는 데다가, DirectX 의 장래의 버젼에 대비해, 코드의 보수성을 높일 수가 있다.

IN 파라미터로서 인터페이스 포인터를 건네줄 수가 있는 경우는, 낡은 버젼을 받아들이도록(듯이) 메소드가 선언되고 있어도, 새로운 버젼을 건네줄 수가 있다. 예를 들어,IDirectMusicPerformance8::PlaySegmentEx 에는,IDirectMusicSegment 또는 IDirectMusicSegment8 에의 포인터를 건네줄 수가 있다.

이 문서는, 인터페이스의 최신 버젼으로 한정한, 완전한 레퍼런스 주제를 수록하고 있다. IDirectMusicGraph8 와 같은 정의가 존재하는 경우, 인터페이스는 그 이름으로 기재되어 있다.

  • IDirectMusic8
  • IDirectMusicAudioPath8
  • IDirectMusicBand8
  • IDirectMusicBuffer8
  • IDirectMusicChordMap8
  • IDirectMusicCollection8
  • IDirectMusicComposer8
  • IDirectMusicContainer8
  • IDirectMusicDownload8
  • IDirectMusicDownloadedInstrument8
  • IDirectMusicGetLoader8
  • IDirectMusicGraph8
  • IDirectMusicInstrument8
  • IDirectMusicLoader8
  • IDirectMusicObject8
  • IDirectMusicPatternTrack8
  • IDirectMusicPerformance8
  • IDirectMusicPort8
  • IDirectMusicPortDownload8
  • IDirectMusicScript8
  • IDirectMusicSegment8
  • IDirectMusicSegmentState8
  • IDirectMusicSong8
  • IDirectMusicStyle8
  • IDirectMusicThru8
  • IDirectMusicTool8
  • IDirectMusicTrack8
  • IKsControl
  • IReferenceClock


IDirectMusic8

IDirectMusic8 인터페이스는, 버퍼, 포토, master clock를 관리하기 위한 메소드를 제공한다. 각 어플리케이션은, 이 인터페이스의 인스턴스를 복수 생성 해서는 안된다.

IDirectMusic8 은 IDirectMusic 을 계승해, 새롭게 SetExternalMasterClock 라고 하는 메소드를 추가한다.

이 인터페이스를 생성 하는 헬퍼 함수는 존재하지 않는다. 어플리케이션은 COM 의 CoCreateInstance 함수,IDirectMusicPerformance8::Init 메소드, 또는 IDirectMusicPerformance8::InitAudio 메소드를 사용해 DirectMusic 오브젝트를 생성 한다.

IDirectMusic8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

액티브하게 한다 | Activate
버퍼 | CreateMusicBuffer
링크 | SetDirectSound
포토 | CreatePort
 | EnumPort
 | GetDefaultPort
타이밍 | EnumMasterClock
 | GetMasterClock
 | SetExternalMasterClock
 | SetMasterClock

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSIC8 형은,IDirectMusic8 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusic8 *LPDIRECTMUSIC8;

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusic8::Activate

IDirectMusic8::Activate 메소드는, 이 인터페이스에 의해 생성 된 모든 포토를 액티브 또는 비액티브하게 한다.

HRESULT Activate(
  BOOL fEnable
);

파라미터

fEnable
DirectMusic 의 이 인스턴스로 생성 된 모든 포토를 액티브 (TRUE) 또는 비액티브 (FALSE)로 한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 DSERR_NODRIVER 를 돌려주어, 사운드 드라이버가 없는 것을 나타낸다.

주의

어플리케이션이 백그라운드에서 음악을 재생할 필요가 없는 경우, 입력초점을 잃은 단계에서 IDirectMusic8::Activate (FALSE)를 호출해야 하는 것이다. 이 결과, 입력초점이 놓여져 있는 것 외의 어플리케이션은 이러한 포토에 액세스 할 수 있다. 입력초점이 다시 이 어플리케이션에 놓여진 단계에서,Activate (TRUE)를 호출해, 할당모든 포토를 사용 가능하게 해야 한다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort8::Activate


IDirectMusic8::CreateMusicBuffer

포토에 순서화 되고 있는 뮤직 메세지를 보관 유지하는, DirectMusicBuffer 오브젝트를 생성 한다. 포토의 추가시에 버퍼 관리는 퍼포먼스에 의해 처리되기 (위해)때문에, 대부분의 어플리케이션은 이 메소드를 호출할 필요가 없다.

HRESULT CreateMusicBuffer(
  LPDMUS_BUFFERDESC pBufferDesc,
  LPDIRECTMUSICBUFFER *ppBuffer,
  LPUNKNOWN pUnkOuter
);

파라미터

pBufferDesc
생성 되는 뮤직 버퍼의 기술을 보관 유지하는 DMUS_BUFFERDESC 구조체의 주소. 포인터를 건네주기 전에, 어플리케이션은 이 구조체의 dwSize 멤버를 초기화해야 한다.
ppBuffer
IDirectMusicBuffer8 인터페이스 포인터를 받는 변수의 주소.
pUnkOuter
COM 집성체의 경우는, 제어 오브젝트의 IUnknown 인터페이스의 주소. 집성체는 현재 지원되어 있지 않기 때문에, 이 값은 NULL 로 설정해야 한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
CLASS_E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusic8::CreatePort

DirectMusic 포토의 오브젝트를 생성 한다.

HRESULT CreatePort(
  REFCLSID rclsidPort,
  LPDMUS_PORTPARAMS pPortParams,
  LPDIRECTMUSICPORT *ppPort,
  LPUNKNOWN pUnkOuter
);

파라미터

rclsidPort
IDirectMusicPort8 인터페이스의 생성처가 되는 포토를 식별하는 GUID 에의 참조 (C++) 또는 주소 (C). IDirectMusic8::EnumPort 메소드를 사용해 GUID 를 취득한다. 이 파라미터가 GUID_NULL 의 경우는, 돌려주어지는 포토가 디폴트 포토가 된다. 상세한 것에 대하여는, 「디폴트 포토」를 참조할것.
pPortParams
포토의 파라미터를 보관 유지하는 DMUS_PORTPARAMS8 구조체의 주소. 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 초기화해야 한다.
ppPort
IDirectMusicPort 인터페이스 포인터를 받는 변수의 주소.
pUnkOuter
COM 집성체의 경우는, 제어 오브젝트의 IUnknown 인터페이스의 주소. 집성체는 현재 지원되어 있지 않기 때문에, 이 값은 NULL 가 아니면 안된다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 지정한 파라미터를 이용할 수 없는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_DSOUND_NOT_SET
E_INVALIDARG
CLASS_E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

주의

포토는 디폴트로, 생성시에는 비액티브하게 되어 있다. IDirectMusic8::Activate 또는 IDirectMusicPort8::Activate 를 호출하는 것으로, 이것을 액티브하게 해야 한다.

모든 파라미터를 취득할 수 없는 경우는,DMUS_PORTPARAMS8 구조체를 이하와 같이 변경해, 포토의 이용할 수 있는 파라미터와 일치시킨다.

엔트리내에서는, 구조체의 dwValidParams 멤버에 의해, 구조 체내의 유효한 멤버가 나타난다. 구조체의 멤버에 대해 플래그를 설정하고 있지 않는 경우는, 포토의 생성시에, 그 파라미터에 디폴트값이 설정된다.

값이 돌려주어지면(자),dwValidParams 내의 플래그에 의해, 어느 포토 파라미터가 설정되었는지가 나타난다. 특정의 파라미터를 지정하지 않고, 디폴트값으로 설정했을 경우, 그 플래그는 건네받은 파라미터에 추가된다.

지정한 파라미터를 포토가 지원 하고 있어도, 파라미터의 값이 범위외의 경우는,*pPortParams 내의 파라미터값이 변경된다. 이 경우,dwValidParams 내의 플래그는 설정된채로 있지만, S_FALSE 가 돌려주어져 값이 변경되었던 것(적)이 나타난다.

다음의 샘플 코드는, 어플리케이션이 어떻게 리바브 기능을 요구해, 그것을 취득할 수 있었는지 어떠했는지를 판별하는 방법을 나타내고 있다. 포토 프로퍼티의 체크 및 설정의 다른 방법에 대해서는, 「DirectMusic 포토의 프로퍼티 세트」를 참조할것.

DMUS_PORTPARAMS8 params;

ZeroMemory(&params, sizeof(params));
params.dwSize = sizeof(params);
params.dwValidParams = DMUS_PORTPARAMS_EFFECTS;
params.dwEffectFlags = DMUS_EFFECT_REVERB;
HRESULT hr = pDirectMusic->CreatePort(guidPort, &params,
        &port, NULL);
if (SUCCEEDED(hr))
{
    fGotReverb = TRUE;
    if (hr == S_FALSE)
    {
        if (! (params.dwValidParams & DMUS_PORTPARAMS_EFFECTS))
        {
            // 디바이스는 어느 이펙트도 지원 하지 않는다.
            fGotReverb = FALSE;
        }
        else if (! (params.dwEffectFlags & DMUS_EFFECT_REVERB))
        {
            // 디바이스는 이펙트를 인식하지만,
            // 리바브를 할당할 수 없다.
            fGotReverb = FALSE;
        }
    }
}

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusic8::EnumMasterClock

DirectMusic 가 master clock로서 이용할 수 있는 클락을 열거한다. 이 메소드를 호출할 때마다, 1 개의 클락에 관한 정보를 취득한다.

HRESULT EnumMasterClock(
  DWORD dwIndex,
  LPDMUS_CLOCKINFO lpClockInfo
);

파라미터

dwIndex
기술을 꺼내고 싶은 클락의 인덱스 번호. 최초로 호출하면나무는 이 파라미터를 0 으로 설정해, 그 이후는 호출마다 1 두개 크게 해야 한다. S_FALSE 가 돌려주어질 때까지 호출을 계속한다.
lpClockInfo
클락의 기술을 받는 DMUS_CLOCKINFO8 구조체의 주소. 포인터를 건네주기 전에, 어플리케이션은 이 구조체의 dwSize 멤버를 초기화해야 한다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 지정한 인덱스 번호를 가지는 클락이 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_NOINTERFACE
E_POINTER

주의

어플리케이션은 클락의 인덱스 번호를 신뢰하거나 보존해서는 안된다. 재기동 또는 하드웨어의 추가나 삭제를 하면(자), 클락의 인덱스 번호가 변화할 가능성이 있다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusic8::SetMasterClock ,IDirectMusic8::GetMasterClock


IDirectMusic8::EnumPort

시스템에 접속되고 있는 DirectMusic 포토의 능력을 열거 및 취득한다. 이 메소드를 호출할 때마다, 1 개의 포토에 관한 정보를 취득한다.

HRESULT EnumPort(
  DWORD dwIndex,
  LPDMUS_PORTCAPS pPortCaps
);

파라미터

dwIndex
능력을 꺼내고 싶은 포토의 인덱스 번호. 최초로 호출하면나무는 이 파라미터를 0 으로 설정해, 그 이후는 호출마다 1 두개 크게 해야 한다. S_FALSE 가 돌려주어질 때까지 호출을 계속한다.
pPortCaps
포토의 능력을 받는 DMUS_PORTCAPS 구조체의 주소. 포인터를 건네주기 전에, 이 구조체의 dwSize 멤버를 초기화해야 한다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 지정한 인덱스값을 가지는 포토가 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_NOINTERFACE
E_POINTER

주의

어플리케이션은 포토의 인덱스 번호를 신뢰하거나 보존해서는 안된다. 재기동 또는 하드웨어의 추가나 삭제를 하면(자), 포토의 인덱스 번호가 변화할 가능성이 있다.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusic8::GetDefaultPort

디폴트의 출력 포토의 GUID 를 취득한다. 이것은,IDirectMusic8::CreatePort 에 GUID_NULL 를 건네주었을 때에 생성 되는 포토이다.

HRESULT GetDefaultPort(
  LPGUID pguidPort
);

파라미터

pguidPort
디폴트 포토의 GUID 를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

디폴트 포토


IDirectMusic8::GetMasterClock

현재 DirectMusic master clock로서 설정되어 있는 클락의 GUID 와IReferenceClock 인터페이스에의 포인터를 취득한다.

HRESULT GetMasterClock(
  LPGUID pguidClock,
  IReferenceClock **ppReferenceClock
);

파라미터

pguidClock
master clock의 GUID 를 받는 변수의 주소. 이 값이 필요없는 경우, 어플리케이션은 NULL 를 건네주어도 괜찮다.
ppReferenceClock
이 클락의 IReferenceClock 를 받는 변수의 주소. 이 값이 필요없는 경우, 어플리케이션은 NULL 를 건네주어도 괜찮다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_NOINTERFACE
E_POINTER

주의

어플리케이션은 IReferenceClock 인터페이스를 다 사용한 다음에, 이 인터페이스를 해방해야 한다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusic8::SetMasterClock


IDirectMusic8::SetDirectSound

신디사이저로부터의 출력용으로, DirectMusic 를 DirectSound 오브젝트에 접속한다.

대부분의 어플리케이션은 이 메소드를 사용하지 않는다. 보통, DirectSound 오브젝트의 생성과 퍼포먼스에의 접속은,IDirectMusicPerformance8::InitAudio 에 의해 행해진다.

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

파라미터

pDirectSound
출력용으로 사용하는 IDirectSound8 인터페이스의 주소. 이 파라미터가 NULL 의 경우, DirectSound 오브젝트가 생성 되어 협조 레벨이 설정된다 ( 「주의」를 참조할것). 이 파라미터에 IDirectSound 포인터가 포함되는 경우는, 어플리케이션이 협조 레벨을 설정해야 한다.
hWnd
이 호출에 의해 생성 되는, DirectSound 오브젝트의 윈도우 핸들. 이 값이 NULL 의 경우, 현재의 전면 윈도우가 포커스 윈도우로서 설정된다. 「주의」를 참조할것.

pDirectSound 이 유효한 인터페이스의 경우, 이 파라미터는 무시된다. IDirectSound8::SetCooperativeLevel 의 호출에서는, 어플리케이션이 유효한 윈도우 핸들을 제공할 필요가 있기 때문에 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 DMUS_E_DSOUND_ALREADY_SET 를 돌려준다.

주의

지정한 DirectSound 오브젝트는, 모든 포토상에서 오디오를 렌더링 할 때에 사용되는 오브젝트이다. 이 디폴트값은,IDirectMusicPort8::SetDirectSound 메소드를 사용해 덧쓰기할 수 있다.

IDirectMusic8::SetDirectSound 메소드를 호출할 때마다, 기존의 DirectSound 오브젝트는 해방된다.

pDirectSound 가 NULL 의 경우, DirectSound 를 사용하는 포토가 액티브하게 될 때까지 새로운 DirectSound 오브젝트는 생성 되지 않는다. DirectSound 오브젝트는, 그것을 사용하고 있는 마지막 포토가 비액티브하게 되면(자) 자동적으로 해방된다.

DirectSound 오브젝트를 스스로 생성 했을 경우는, 모든 포토를 비액티브하게 한 다음에, 이 메소드의 pDirectSound 파라미터에 NULL 를 설정해 호출하는 것에 의해 해방할 수 있다 (액티브한 포토에 대해서 SetDirectSound 를 호출하는 것은 잘못이다).

hWnd 파라미터에 NULL 를 건네주면(자), 현재의 전면 윈도우의 핸들을 DirectSound 에 건네줄 수가 있다. 다만, 어플리케이션 윈도우가 초기화중에 전면에 있으면(자) 상정하지 않는 것. 보통, 최상정도 레벨의 어플리케이션 윈도우 핸들을 DirectMusic 및 DirectSound 에 건네주지 않으면 안 된다. IDirectSound8::SetCooperativeLevel 의 「주의」를 참조할것.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusic8::SetExternalMasterClock

DirectMusic master clock에 기존의 클락 오브젝트를 설정한다. 모든 DirectMusic 어플리케이션은, 다만 1 개의 master clock를 사용한다.

HRESULT SetExternalMasterClock(
  IReferenceClock *pClock
);

파라미터

pClock
클락을 지정하는 IReferenceClock 인터페이스 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 DMUS_E_PORTS_OPEN 를 돌려준다.

주의

실행중외의 어플리케이션도 DirectMusic 를 사용하고 있는 경우, 그 어플리케이션이 슛다운 할 때까지는 master clock를 변경할 수 없다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusic8::GetMasterClock ,IDirectMusic8::EnumMasterClock ,IDirectMusic8::SetMasterClock


IDirectMusic8::SetMasterClock

IDirectMusic8::EnumMasterClock 를 호출했을 때에 취득된 GUID 에 의해 식별되는 클락을, DirectMusic 의 master clock로 설정한다. 모든 DirectMusic 어플리케이션은, 다만 1 개의 master clock를 사용한다.

HRESULT SetMasterClock(
  REFGUID rguidClock
);

파라미터

rguidClock
DirectMusic 의 master clock로서 설정되는 클락을 식별하는 GUID 에의 참조 (C++) 또는 주소 (C). 이 파라미터는,IDirectMusic8::EnumMasterClock 메소드가 돌려준 GUID 가 아니면 안된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 DMUS_E_PORTS_OPEN 를 돌려준다.

주의

실행중외의 어플리케이션도 DirectMusic 를 사용하고 있는 경우, 그 어플리케이션이 슛다운 할 때까지는 master clock를 변경할 수 없다.

(정도)만큼 어느 어플리케이션은 SetMasterClock 를 호출할 필요가 없다. 시스템 클록 이외의 하드웨어 타이머와의 엄밀한 동기를 필요로 하지 않는 이상 이 메소드를 호출해서는 안된다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusic8::SetExternalMasterClock ,IDirectMusic8::GetMasterClock ,IDirectMusic8::EnumMasterClock


IDirectMusicAudioPath8

IDirectMusicAudioPath8 인터페이스는, 퍼포먼스로부터프라이머리 사운드 버퍼까지의 데이터 플로우의 단계를 나타낸다. 오디오 패스는,IDirectMusicPerformance8::CreateAudioPath 메소드를 사용해, 오디오 패스 구성 오브젝트로부터 생성 할 수 있다. 표준 오디오 패스는,IDirectMusicPerformance8::CreateStandardAudioPath 를 사용해 생성 할 수 있다. 또, 표준 디폴트 패스는,IDirectMusicPerformance8::InitAudio 를 사용해 생성 할 수 있어IDirectMusicPerformance8::GetDefaultAudioPath 를 사용해 취득할 수 있다.

IDirectMusicAudioPath8 인터페이스를 IDirectMusicPerformance8::PlaySegmentEx 에 건네주면(자), 그 오디오 패스 위에의 세그먼트(segment)를 연주할 수 있다.

IDirectMusicAudioPath8 는,IDirectMusicAudioPath 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

IDirectMusicAudioPath8 인터페이스에는 다음의 메소드가 있다.

IDirectMusicAudioPath8 | Activate
 | ConvertPChannel
 | GetObjectInPath
 | SetVolume

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. 이 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicAudioPath8::Activate

오디오 패스를 액티브 또는 비액티브하게 한다.

HRESULT Activate(
  BOOL fActivate
);

파라미터

fActivate
패스를 액티브 (TRUE)로 하는지, 또는 비액티브 (FALSE)로 하는지를 지정하는 불리언 값.

반환값

성공했을 경우는 S_OK 를 돌려준다. 오디오 패스가 이미 요구된 상태가 되어 있는 경우는 S_FALSE 를 돌려준다.

주의

이 메소드의 동작은,IDirectMusicPort8::Activate 의 동작과는 다르다. 포토를 비액티브하게 하면, 포토에서는 사운드가 생성되지 않게 되지만, 퍼포먼스에 의해 세그먼트(segment)의 재생을 계속할 수 있다. 오디오 패스를 비액티브하게 하면, 모든 재생이 정지해, 세그먼트(segment)를 재생할 수 없게 된다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicAudioPath8::ConvertPChannel

세그먼트(segment)내의 퍼포먼스 채널과 오디오 패스의 퍼포먼스에 할당할 수 있었던 동등의 채널을 평행이동 한다. 어플리케이션은 보통, 이 메소드를 필요로 하지 않지만, 트럭등의 컴퍼넌트로 사용되는 일이 있다.

HRESULT ConvertPChannel(
  DWORD dwPChannelIn,
  DWORD *pdwPChannelOut
);

파라미터

dwPChannelIn
변환하는 퍼포먼스 채널을 지정하는 값.
pdwPChannelOut
가상 퍼포먼스 채널을 받는 DWORD 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicAudioPath8::GetObjectInPath

오디오 패스내의 오브젝트에 대해서 인터페이스를 취득한다.

RESULT GetObjectInPath(
  DWORD dwPChannel,
  DWORD dwStage,
  DWORD dwBuffer,
  REFGUID guidObject,
  DWORD dwIndex,
  REFGUID iidInterface,
  void ** ppObject
);

파라미터

dwPChannel
검색하는 퍼포먼스 채널 또는 모든 채널을 검색하는 DMUS_PCHANNEL_ALL. 최초의 채널은 0 번이 된다. 「주의」를 참조할것.
dwStage
패스의 스테이지. 다음의 몇개의 값을 지정한다.
DMUS_PATH_AUDIOPATH_GRAPH
오디오 파스퇴르 그래프를 취득한다. 존재하지 않으면 생성 된다.
DMUS_PATH_AUDIOPATH_TOOL
오디오 파스퇴르 그래프로부터 툴을 취득한다.
DMUS_PATH_BUFFER
DirectSound 버퍼를 취득한다.
DMUS_PATH_BUFFER_DMO
버퍼의 DMO 를 취득한다. DMO 인터페이스의 상세한 것에 대하여는, 「IDirectSoundBuffer8::GetObjectInPath 」를 참조할것.
DMUS_PATH_MIXIN_BUFFER
글로벌 믹스 인 버퍼를 취득한다.
DMUS_PATH_MIXIN_BUFFER_DMO
글로벌 믹스 인 버퍼내의 DMO 를 취득한다.
DMUS_PATH_PERFORMANCE
퍼포먼스를 취득한다.
DMUS_PATH_PERFORMANCE_GRAPH
퍼포먼스 툴 그래프를 취득한다. 존재하지 않으면 생성 된다.
DMUS_PATH_PERFORMANCE_TOOL
퍼포먼스 툴 그래프로부터 툴을 취득한다.
DMUS_PATH_PORT
신디사이저를 취득한다.
DMUS_PATH_PRIMARY_BUFFER
프라이머리 버퍼를 취득한다.
dwBuffer
dwStage 가 DMUS_PATH_BUFFER_DMO 또는 DMUS_PATH_MIXIN_BUFFER_DMO 의 경우, DMO 가 상주하는 버퍼의 인덱스. dwStage 가 DMUS_PATH_BUFFER 또는 DMUS_PATH_MIXIN_BUFFER 의 경우, 버퍼의 인덱스. 그 이외의 경우, 0 이 아니면 안된다.
guidObject
오브젝트의 클래스 식별자, 또는 임의의 클래스의 오브젝트를 검색하는 GUID_All_Objects. dwStage 에 의해 지정된 스테이지에 존재하는 오브젝트가 단일의 클래스로 한정되고 있는 경우는 무시된다. 이 파라미터는 GUID_NULL 로 설정할 수 있다.
dwIndex
일치하는 오브젝트의 리스트에 포함되는 오브젝트의 인덱스. 0 으로 설정해, 최초의 적합 오브젝트를 검색한다. dwStage 가 DMUS_PATH_BUFFER 또는 DMUS_PATH_MIXIN_BUFFER 의 경우, 이 파라미터는 무시되어dwBuffer 에 의해 버퍼 인덱스가 지정된다.
iidInterface
IID_IDirectMusicTool 등, 목적의 인터페이스의 식별자.
ppObject
요구된 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_INVALIDARG
E_OUTOFMEMORY
E_NOINTERFACE
E_POINTER

주의

채널 고유하지 않은 스테이지에 대해서는,dwPChannel 의 값은 0 으로 설정해야 한다. 다음의 스테이지의 오브젝트는 채널 고유해서,dwPChannel 에 채널 번호 또는 DMUS_PCHANNEL_ALL 를 설정해 취득할 수 있다.

DMUS_PATH_AUDIOPATH_TOOL
DMUS_PATH_BUFFER
DMUS_PATH_BUFFER_DMO
DMUS_PATH_PERFORMANCE_TOOL
DMUS_PATH_PORT
DMUS_PATH_SEGMENT_TOOL

불필요한 오브젝트를 필터 링에 의해 제외 하면나무의 파라미터의 우선 순위는 다음과 같다.

  1. dwStage.
  2. guidObject. 이 값이 GUID_All_Objects 가 아닌 경우, 클래스 식별자가 guidObject 에 동일한 오브젝트만이 검색된다. 다만, DMUS_PATH_AUDIOPATH_GRAPH 등의, 오브젝트가 단일의 클래스로 한정되는 스테이지에서는, 이 파라미터는 무시된다.
  3. dwPChannel. 스테이지가 채널 고유해, 이 값이 DMUS_PCHANNEL_ALL 가 아닌 경우, 그 채널의 오브젝트만이 검색된다.
  4. dwBuffer. 이 파라미터가 사용되는 것은,dwStage 가 DMUS_PATH_BUFFER, DMUS_PATH_MIXIN_BUFFER, DMUS_PATH_BUFFER_DMO, 또는 DMUS_PATH_MIXIN_BUFFER_DMO 의 경우 뿐이다.
  5. dwIndex.

일치하는 오브젝트가 발견되어도,iidInterface 로 지정되고 있는 인터페이스가 발견되지 않는 경우, 이 메소드는 실패한다.

다음의 샘플 코드는, 오디오 패스내의 버퍼를 열거하는 방법을 나타내고 있다. _stprintf 함수는 Tchar.h 로 선언된다.

void DumpAudioPathBuffers(
        IDirectMusicAudioPath *pDirectMusicAudioPath)
{
    TCHAR tcstrText[256];
    DWORD dwBuffer = 0;
    IDirectSoundBuffer *pDirectSoundBuffer;

    while(S_OK == pDirectMusicAudioPath->GetObjectInPath(
        DMUS_PCHANNEL_ALL, DMUS_PATH_BUFFER, dwBuffer,
        GUID_NULL, 0, IID_IDirectSoundBuffer,
        (void**) &pDirectSoundBuffer))
    {
        _stprintf( tcstrText, _T("Found buffer %x. \n"),
                pDirectSoundBuffer);
        OutputDebugString( tcstrText );
        dwBuffer++;
        pDirectSoundBuffer->Release();
    }

    if( dwBuffer == 0 )
    {
        OutputDebugString( _T("No buffers in audiopath. \n") );
    }
}

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegmentState8::GetObjectInPath ,오디오 패스로부터의 오브젝트의 취득


IDirectMusicAudioPath8::SetVolume

패스의 오디오 볼륨을 설정한다.

HRESULT SetVolume(
  long lVolume,
  DWORD dwDuration
);

파라미터

lVolume
감쇠를 지정하는 값. 1/100 데시벨 단위로 지정한다. 이 값의 범위는 -9600 ~ 0 이다. 0 은 최대 볼륨을 나타낸다.
dwDuration
어느 정도의 시간이 경과하면 볼륨 변경이 발생하는지를 지정하는 값. 밀리 세컨드 단위로 지정한다. 이 값에 0 을 지정 하면, 즉시 실행이 보증된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_INVALIDARG

동작환경

헤더 : dmusici.h 로 선언. 그리고 선언.


IDirectMusicBand8

IDirectMusicBand8 인터페이스는, DirectMusic 밴드 오브젝트를 나타낸다. 밴드를 사용해, 일련의 퍼포먼스 채널의 음색의 선택사항과 믹서 설정을 지정한다. 개요에 대해서는, 「밴드의 사용법」을 참조할것. 밴드는, 전용의 파일에 보존해도, 스타일의 밴드 리스트나 세그먼트(segment)의 밴드 트럭에 묻어도 괜찮다.

IDirectMusicBand8 는,IDirectMusicBand 의 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

DirectMusicBand 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IPersistStream 과 IDirectMusicObject8 의 각 인터페이스도 지원 하고 있다.

IDirectMusicBand8 인터페이스에는 다음의 메소드가 있다.

세그먼트(segment) 생성 | CreateSegment
음색 데이터 | Download
 | Unload

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicBand8::CreateSegment

밴드내에서 볼륨, 빵, 전조, 및 패치 변경 커멘드를 동적으로 실행하기 위해서, 연주 가능한 DirectMusicSegment 오브젝트를 생성 한다.

HRESULT CreateSegment(
  IDirectMusicSegment** ppSegment
);

파라미터

ppSegment
생성 된 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_OUTOFMEMORY
E_POINTER

주의

밴드로부터 세그먼트(segment)를 생성 하는 방법의 예에 대해서는, 「프로그램에 의한 밴드 체인지의 실행」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicBand8::Download

밴드내의 음색의 DLS 데이터를 퍼포먼스 오브젝트에 다운로드한다.

HRESULT Download(
  IDirectMusicPerformance* pPerformance
);

파라미터

pPerformance
음색의 다운로드처의 퍼포먼스. 퍼포먼스는 퍼포먼스 채널로부터 DirectMusic 포토에의 매핑을 관리한다.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_PARTIALDOWNLOAD 를 돌려준다 ( 「주의」를 참조할것).

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

주의

이 메소드는,IDirectMusicPerformance8::DownloadInstrument 메소드를 호출하는 것으로, 밴드내에서 각각의 음색을 다운로드한다. DownloadInstrument 는 음색의 퍼포먼스 채널을 사용해 적절한 포토를 찾아내 그 포토에 대해서 IDirectMusicPort8::DownloadInstrument 메소드를 호출한다.

밴드의 다운로드가 끝나면(자), 그 밴드내의 음색은, 프로그램 체인지 MIDI 메세지에 의해 개별적으로 선택하는지,IDirectMusicBand8::CreateSegment 메소드를 호출해 생성 한 밴드 세그먼트(segment)를 재생하는 것으로써 한 번에 모든 것을 선택할 수 있다.

다운로드한 밴드는 신디사이저 리소스를 사용하기 (위해)때문에, 필요가 없을 때는 IDirectMusicBand8::Unload 메소드를 사용해 언로드해야 한다.

이 메소드는, 포토가 DLS 를 지원 하고 있지 않아도, S_OK 를 돌려주는 일이 있다.

다운로드가 완전하게 실패했을 경우는, DMUS_E_NOT_INIT 가 돌려주어진다. 이것은 보통, 초기화된 포토에 퍼포먼스가 정상적으로 접속되지 않았던 것을 의미한다. 이것은 완전한 실패이기 (위해)때문에, 다음에 IDirectMusicBand8::Unload 를 호출할 필요는 없다.

다운로드가 일부 성공했을 경우는, DMUS_S_PARTIALDOWNLOAD 가 돌려주어진다. 이것은, 정상적으로 다운로드할 수 있던 음색과 다운로드할 수 없었던 음색이 있는 것을 의미한다. 그 원인은 보통, 퍼포먼스와 포토의 설정에 대해 프로그래밍 에러가 발생했기 때문이다. 문제를 특정하는 최선의 방법은, Dmime.dll, Dmband.dll, 및 Dmsynth.dll 의 디버그 트레이스를 1 으로 설정하는 것이다 ( 「DirectX Audio 프로젝트의 디버그」를 참조할것).

부분적인 다운로드가 발생하는 일반적인 원인을 이하에 나타낸다.

  • 밴드는, 퍼포먼스에 대해서 설정되어 있지 않은 퍼포먼스 채널상에 음색을 가지고 있다 (IDirectMusicPerformance8::AssignPChannelBlock 의 사용에 의한다).
  • 밴드는, 포토에 할당할 수 있지 않은 채널 그룹의 퍼포먼스 채널상에 음색을 가지고 있다.
  • 밴드는, 음색의 다운로드처가 되는 신디사이저와 호환성이 없는 DLS 포맷의 음색을 가지고 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicBand8::Unload


IDirectMusicBand8::Unload

IDirectMusicBand8::Download 를 사용해 이전에 다운로드한 밴드내의 음색의 DLS 데이터를 언로드한다.

HRESULT Unload(
  IDirectMusicPerformance* pPerformance
);

파라미터

pPerformance
음색의 언로드원의 퍼포먼스.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_NOT_FOUND

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPort8::UnloadInstrument


IDirectMusicBuffer8

IDirectMusicBuffer8 는, 포토에 의해 순서화 되는, 타임 스탬프를 할당할 수 있었던 데이터 (보통은 MIDI 메세지 형식)를 포함한 버퍼를 나타낸다. 세그먼트(segment)와는 달라, 버퍼는 몇 안 되는 양의 데이터 (보통은 200ms 미만)를 보관 유지해, 어플리케이션은 이벤트의 미소성을 제어할 때에 이 데이터를 이용한다.

IDirectMusicBuffer8 는 IDirectMusicBuffer 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

어플리케이션이 독자적인 순서화를 실시하지 않는 이상 이 인터페이스의 이 메소드를 사용할 필요는 없다.

IDirectMusicPort8::PlayBuffer 메소드나 IDirectMusicPort8::Read 메소드의 어느 쪽인지를 호출해 버퍼를 포토에 건네줄 때까지는, 버퍼 오브젝트는 포토 오브젝트로부터 완전하게 독립하고 있다. 그 후 어플리케이션은 버퍼를 해방해, 재이용을 가능하게 한다.

IDirectMusicBuffer8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

데이터 | Flush
 | GetNextEvent
 | GetRawBufferPtr
 | PackStructured
 | PackUnstructured
 | ResetReadPtr
파라미터 | GetBufferFormat
 | GetMaxBytes
 | GetUsedBytes
 | SetUsedBytes
시간 | GetStartTime
 | SetStartTime
 | TotalTime

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICBUFFER8 형은,IDirectMusicBuffer8 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicBuffer8 *LPDIRECTMUSICBUFFER8;

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicBuffer8::Flush

버퍼내의 전데이터를 파기한다.

HRESULT Flush();

파라미터

없음.

반환값

항상 S_OK 를 돌려준다.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicBuffer8::GetBufferFormat

버퍼 포맷을 나타내는 GUID 를 취득한다.

HRESULT GetBufferFormat(
  LPGUID pGuidFormat
);

파라미터

pGuidFormat
버퍼 포맷의 GUID 를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

버퍼를 생성 했을 때에 포맷을 지정하지 않았던 경우,*pGuidFormat 에 KSDATAFORMAT_SUBTYPE_DIRECTMUSIC 가 돌려주어진다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusic8::CreateMusicBuffer ,DMUS_EVENTHEADER


IDirectMusicBuffer8::GetMaxBytes

버퍼내에 보존할 수 있는 바이트수를 취득한다.

HRESULT GetMaxBytes(
  LPDWORD pcb
);

파라미터

pcb
버퍼를 보관 유지할 수 있는 최대의 바이트수를 포함한 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicBuffer8::GetNextEvent

버퍼내의 이하의 메세지에 관한 정보를 돌려주어, 독해 포인터를 먼저 진행한다.

HRESULT GetNextEvent(
  LPREFERENCE_TIME prt,
  LPDWORD pdwChannelGroup,
  LPDWORD pdwLength,
  LPBYTE* ppData
);

파라미터

prt
메세지의 타임을 받는 변수의 주소.
pdwChannelGroup
메세지의 채널 그룹을 받는 변수의 주소.
pdwLength
메세지의 길이 (바이트 단위)를 받는 변수의 주소.
ppData
메세지 데이터에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다. 다만, 버퍼내에 메세지가 존재하지 않았던 경우는 S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

항목이 필요없는 경우, 해당하는 포인터로서 NULL 를 지정해도 괜찮다.

ppData 에 돌려주어진 포인터는, 버퍼 오브젝트의 수명의 사이에 한해서 유효하다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8::ResetReadPtr


IDirectMusicBuffer8::GetRawBufferPtr

기저의 버퍼 데이터 구조체에의 포인터를 돌려준다.

HRESULT GetRawBufferPtr(
  LPBYTE* ppData
);

파라미터

ppData
버퍼의 데이터에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

이 메소드는, 버퍼의 raw 데이터에의 포인터를 돌려준다. 이 데이터의 포맷은, 이행에 의존한다. 데이터의 수명은, 버퍼 오브젝트의 수명과 같다. 그 때문에, 다음에 IDirectMusicBuffer8:: Release 메소드를 호출한 후는, 돌려주어진 포인터를 보관 유지해서는 안된다.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicBuffer8::GetStartTime

버퍼내의 데이터의 시작 타임을 취득한다. 이 타임은 master clock를 기준으로 한다.

HRESULT GetStartTime(
  LPREFERENCE_TIME prt
);

파라미터

prt
시작 타임을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_BUFFER_EMPTY
E_POINTER

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8::SetStartTime ,IDirectMusicBuffer8::TotalTime


IDirectMusicBuffer8::GetUsedBytes

버퍼내의 데이터의 바이트수를 취득한다.

HRESULT GetUsedBytes(
  LPDWORD pcb
);

파라미터

pcb
사용중의 바이트수를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8::SetUsedBytes


IDirectMusicBuffer8::PackStructured

고정장 데이터 (보통은 MIDI 채널 메세지)를, 타이밍 정보 및 루팅 정보와 함께 버퍼내에 삽입한다.

HRESULT PackStructured(
  REFERENCE_TIME rt,
  DWORD dwChannelGroup,
  DWORD dwChannelMessage
);

파라미터

rt
메세지의 절대 타임. 「주의」를 참조할것.
dwChannelGroup
데이터가 소속하는 채널 그룹.
dwChannelMessage
팩 해야 할 데이터 (MIDI 메세지).

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_INVALID_EVENT
E_OUTOFMEMORY

주의

버퍼내에 적어도 32 바이트 (DMUS_EVENTHEADER 와 dwChannelMessage 의 합계 사이즈)의 빈 곳이 존재해야 한다.

rt 파라미터에는, 데이터가 포토에 송신되는 절대 타임을 설정할 필요가 있다. 메세지를 즉석에서 연주하려면 , 지연 시간 클락에서 이 타임을 취득해,rt 로서 사용한다. 「IDirectMusicPort8::GetLatencyClock 」를 참조할것.

같은 타임의 스탬프가 뒤따른 메세지는, 버퍼내에 놓여진 순서와 같은 순서로 연주된다고는 할 수 없다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8::PackUnstructured


IDirectMusicBuffer8::PackUnstructured

비구조화 데이터 (보통은 MIDI 시스템에크스크루시브멧세이지)를, 타이밍 정보 및 루팅 정보와 함께 버퍼내에 삽입한다.

HRESULT PackUnstructured(
  REFERENCE_TIME rt,
  DWORD dwChannelGroup,
  DWORD cb,
  LPBYTE lpb
);

파라미터

rt
메세지의 절대 타임.
dwChannelGroup
메세지가 소속하는 채널 그룹.
cb
데이터의 사이즈 (바이트 단위).
lpb
데이터를 보관 유지하는 버퍼의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_OUTOFMEMORY
E_POINTER

주의

이 메소드를 사용해, 임의의 데이터를 포토에 송신할 수 있다.

적어도 28 바이트 (DMUS_EVENTHEADER 의 사이즈)와 데이터의 사이즈를 4 바이트의 배수까지 추가한 사이즈의 빈 곳이 버퍼내에 존재해야 한다. 필요한 버퍼는 DMUS_EVENT_SIZE(cb) 매크로를 사용해 취득할 수 있다. 여기서 cb 는 데이터의 사이즈이다.

rt 파라미터에는, 데이터가 포토에 송신되는 절대 타임을 설정할 필요가 있다. 메세지를 즉석에서 연주하려면 , 지연 시간 클락에서 이 타임을 취득해,rt 로서 사용한다. 「IDirectMusicPort8::GetLatencyClock 」를 참조할것.

같은 타임의 스탬프가 뒤따른 메세지는, 버퍼내에 놓여진 순서와 같은 순서로 연주된다고는 할 수 없다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8::PackStructured


IDirectMusicBuffer8::ResetReadPtr

독해 포인터를 버퍼내의 데이터의 선두로 설정한다.

HRESULT ResetReadPtr()

파라미터

없음.

반환값

항상 S_OK 를 돌려준다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8::GetNextEvent


IDirectMusicBuffer8::SetStartTime

버퍼내의 데이터의 시작 타임을 설정한다. 이 타임은 master clock를 기준으로 한다.

HRESULT SetStartTime(
  REFERENCE_TIME rt
);

파라미터

rt
버퍼의 새로운 시작 타임.

반환값

항상 S_OK 를 돌려준다.

주의

버퍼내에 이미 있는 이벤트는, 시작 타임을 기준으로 하는 타임 스탬프를 붙일 수 있어 새로운 시작 타임부터의 같은 오프셋(offset)로부터 연주한다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8::GetStartTime


IDirectMusicBuffer8::SetUsedBytes

버퍼내의 데이터의 바이트수를 설정한다.

HRESULT SetUsedBytes(
  DWORD cb
);

파라미터

cb
버퍼내의 유효한 데이터 바이트수.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 DMUS_E_BUFFER_FULL 를 돌려준다.

주의

이 메소드를 사용하면(자), 어플리케이션은 버퍼를 수동으로 재팩 할 수 있다. 보통, 버퍼내의 데이터 형식이, DirectMusic 의 제공하는 디폴트의 포맷과 다를 때 마셔, 이 메소드를 사용해야 하는 것이다.

지정한 바이트수가,IDirectMusicBuffer8::GetMaxBytes 메소드가 돌려주는 최대 버퍼 사이즈를 넘고 있는 경우, 이 메소드는 실패한다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8::GetUsedBytes


IDirectMusicBuffer8::TotalTime

버퍼내의 데이터의 합계 시간을 돌려준다.

HRESULT TotalTime(
  LPREFERENCE_TIME prtTime
);

파라미터

prtTime
버퍼내의 합계 시간 (100ns 단위)을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8::GetStartTime


IDirectMusicChordMap8

IDirectMusicChordMap8 인터페이스는, 코드 맵을 나타낸다. 코드 맵은, 작곡가 (IDirectMusicComposer8 에 의해 나타내진다)에 대해, 어레인지 하는 세그먼트(segment)의 코드 진행을 생성 하는데 필요한 정보를 제공한다. 코드 맵은, 기존 세그먼트(segment)내의 코드를 변경하는 경우에도 사용할 수 있다.

DirectMusicChordMap 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject8 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

IDirectMusicChordMap8 은,IDirectMusicChordMap 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

이 인터페이스는, 이하의 메소드를 지원 한다.

IDirectMusicChordMap8 GetScale

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicChordMap8::GetScale

코드 맵에 관련지을 수 있었던 스케일을 취득한다.

HRESULT GetScale(
  DWORD* pdwScale
);

파라미터

pdwScale
스케일의 값을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

스케일은,DWORD 내의 비트를 스케일의 패턴 (하위 24 비트)과 루트음 (상위 8 비트)에 분할해 정의된다. 스케일의 패턴은, 최하정도 비트 (0x0001)는 낮은 노트의 C, 다음의 상위 비트 (0x0002)는 C# 이며, 똑같이 2 옥타브의 스케일이 정의된다. 상위 8 비트는, 스케일의 루트음을 0 ~ 23 (저음의 C 로부터 중간의 B 까지)의 정수로 나타낸다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicCollection8

IDirectMusicCollection8 인터페이스는,DLS 파일의 인스턴스를 관리한다. 콜렉션은, 음색에 액세스하기 위한 메소드를 제공해,IDirectMusicPort8 인터페이스를 사용해 음색을 신디사이저에 다운로드한다.

IDirectMusicCollection8 는,IDirectMusicCollection 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

DirectMusicCollection 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject8 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

콜렉션을 사용한 작업의 상세한 것에 대하여는, 「음색 콜렉션의 사용법」을 참조할것.

IDirectMusicCollection8 인터페이스에는 다음의 메소드가 있다.

음색 | EnumInstrument
 | GetInstrument

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicCollection8::EnumInstrument

콜렉션내의 인덱스를 사용해, 음색의 패치 번호와 이름을 취득한다.

HRESULT EnumInstrument(
  DWORD dwIndex,
  DWORD* pdwPatch,
  LPWSTR pwszName,
  DWORD dwNameLen
);

파라미터

dwIndex
콜렉션내의 음색의 인덱스.
pdwPatch
패치 번호를 받는 변수의 주소.
pwszName
음색명을 받는 버퍼의 주소. 이름이 불필요한 경우는, NULL 이라도 좋다.
dwNameLen
음색명 버퍼에 저장 되는 WCHAR 값의 수.

반환값

성공했을 경우는 S_OK 를 돌려준다. 지정된 인덱스 번호를 가지는 음색이 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_OUTOFMEMORY
E_POINTER

주의

콜렉션내의 모든 음색을 열거하려면 ,dwIndex 의 값을 0 으로부터 시작해EnumInstrument 가 S_FALSE 를 돌려줄 때까지 값을 크게 한다.

pdwPatch 에 돌려주어지는 패치 번호는, 뱅크 셀렉트의 MSB 와 LSB 의 MIDI 파라미터도 포함한, 완전한 패치 주소를 기술한다. 상세한 것에 대하여는, 「MIDI 채널 메세지」를 참조할것.

열거형의 순서는 DLS 콜렉션의 1 개의 인스턴스내에서는 정합하고 있지만, 이 순서는 파일내의 음색의 순서, 패치 번호, 음색명의 머지않아와도 관계는 없다.

음색의 열거의 예에 대해서는, 「음색의 조작」을 참조할것.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicCollection8::GetInstrument

패치 번호를 지정해, 콜렉션으로부터 음색을 취득한다.

HRESULT GetInstrument(
  DWORD dwPatch,
  IDirectMusicInstrument** ppInstrument
);

파라미터

dwPatch
음색의 패치 번호.
ppInstrument
IDirectMusicInstrument8 인터페이스 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_CORE_INVALIDPATCH
E_FAIL
E_OUTOFMEMORY
E_POINTER

주의

dwPatch 로 건네받은 패치 번호는,뱅크 셀렉트의 MSB 와 LSB 의 MIDI 파라미터도 포함한, 완전한 패치 주소를 기술한다. MSB 는 왼쪽 쉬프트 된 16 비트이며, LSB 는 왼쪽 쉬프트 된 8 비트이다. 상세한 것에 대하여는, 「MIDI 채널 메세지」를 참조할것.

또, 음색이 MIDI 채널 10 재생용의 드럼 킷의 경우, 상위 비트 (0x80000000)가 설정된다.

이 메소드를 사용하는 방법의 상세한 것에 대하여는, 「음색의 조작」을 참조할것.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicComposer8

IDirectMusicComposer8 인터페이스를 사용하면(자), 작곡가 엔진에 액세스 할 수 있다. 템플릿이나 코드 맵으로부터 새로운 섹션 세그먼트(segment)를 구축하는 것에 가세해, 이 작곡가는 복수의 섹션 세그먼트(segment)간의 트란지션을 생성 할 수 있다. 코드 맵을 기존의 섹션 세그먼트(segment)에도 적용할 수 있으므로, 섹션의 코드 진행과 분위기도 변경할 수 있다.

IDirectMusicComposer8 는,IDirectMusicComposer 의 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

IDirectMusicComposer8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

코드 맵의 변경 | ChangeChordMap
보통의 세그먼트(segment)의 어레인지 | ComposeSegmentFromShape
 | ComposeSegmentFromTemplate
템플릿 세그먼트(segment)의 어레인지 | ComposeTemplateFromShape
트란지션세그먼트의 어레인지 | AutoTransition
 | ComposeTransition

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicComposer8::AutoTransition

퍼포먼스의 프라이머리 세그먼트(segment) (또는 무음)로부터 다른 세그먼트(segment)에의 트란지션을 어레인지 해, 연주의 목적으로 그 트란지션과 세칸다리세그먼트를 삽입한다.

HRESULT AutoTransition(
  IDirectMusicPerformance* pPerformance,
  IDirectMusicSegment* pToSeg,
  WORD wCommand,
  DWORD dwFlags,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppTransSeg,
  IDirectMusicSegmentState** ppToSegState,
  IDirectMusicSegmentState** ppTransSegState
);

파라미터

pPerformance
트란지션을 생성 하는 퍼포먼스.
pToSeg
이행처 섹션. 트란지션은 이 섹션에 원활히 이행 한다. 「주의」를 참조할것.
wCommand
트란지션을 생성 할 경우에 사용되는 장식. 이것에는,DMUS_COMMANDT_TYPES 열거형의 1 개인가, 또는 컨텐트 프로바이더에 의해 정의된 다른 값을 지정할 수 있다. 이 값이 DMUS_COMMANDT_ENDANDINTRO 의 경우, 메소드는, 프라이머리 세그먼트(segment)의 엔딩과 pToSeg 의 인트로를 포함한 세그먼트(segment)를 어레인지 한다.
dwFlags
작곡가 옵션. 「DMUS_COMPOSEF_FLAGS 」를 참조할것.
pChordMap
트란지션을 어레인지 할 경우에 사용되는 코드 맵의,IDirectMusicChordMap8 인터페이스에의 포인터.
ppTransSeg
생성 된 세그먼트(segment)에의 포인터를 받는 변수의 주소. 이 값은 NULL 이라도 좋다. 그 경우, 포인터는 돌려주어지지 않다.
ppToSegState
트란지션 (pToSeg)의 뒤의 세그먼트(segment)의 퍼포먼스 (pPerformance)에 의해 생성 되는 세그먼트(segment) 상태에의 포인터를 받는 변수의 주소. 「주의」를 참조할것.
ppTransSegState
생성 된 세그먼트(segment) (ppTransSeg)의 퍼포먼스 (pPerformance)에 의해 생성 되는 세그먼트(segment) 상태에의 포인터를 받는 변수의 주소. 「주의」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NO_MASTER_CLOCK
E_INVALIDARG
E_POINTER

주의

dwFlags 가 DMUS_COMPOSEF_MODULATE 를 포함하지 않은 경우,pToSeg 의 값은 NULL 이라도 좋다. pToSeg 가 NULL 또는 스타일 트럭을 포함하지 않은 경우 (MIDI 파일에 근거하고 있는 경우), 인트로의 장식은 무효가 된다. 연주중의 세그먼트(segment)가 NULL 또는 스타일 트럭을 포함하지 않은 경우는, 필, 브레이크, 엔드, 및 홈의 장식이 무효가 된다. 연주중의 세그먼트(segment) 또는 pToSeg 에 의해 나타내지는 세그먼트(segment)로 스타일 트럭을 이용할 수 없는 경우는, 모든 장식이 무효가 되어, 트란지션은 행해지지 않는다. 그 경우,ppTransSeg 와 ppTransSegState 의 양쪽 모두가 NULL 를 돌려주지만, 포인터가 NULL 이외 때 메소드는 성공해,pToSeg 에 의해 나타내지는 세그먼트(segment)가 삽입된다.

pChordMap 의 값은 NULL 이라도 좋다. 값이 NULL 의 경우, 코드 맵 트럭으로부터 코드 맵을 취득하는 시도를 한다. 최초로 pToSeg, 다음에 퍼포먼스의 프라이머리 세그먼트(segment)가 시험 받는다. 어느 세그먼트(segment)에도 코드 맵 트럭이 포함되지 않는 경우는, 현재의 타임에 프라이머리 세그먼트(segment)내에서 발생하는 코드가 트란지션의 코드로서 사용된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer8::ComposeTransition ,트란지션의 사용법


IDirectMusicComposer8::ChangeChordMap

새로운 코드 맵을 반영해, 기존의 섹션 세그먼트(segment)의 코드와 스케일의 패턴을 변경한다.

HRESULT ChangeChordMap(
  IDirectMusicSegment* pSegment,
  BOOL fTrackScale,
  IDirectMusicChordMap* pChordMap
);

파라미터

pSegment
코드 맵을 변경하는 세그먼트(segment)의,IDirectMusicSegment8 인터페이스에의 포인터. 이 세그먼트(segment)는, 코드 맵 트럭과 스타일을 보관 유지해야 한다.
fTrackScale
TRUE 의 경우, 메소드는, 모든 코드를 새로운 코드 맙스 케일인 루트음에 상대적으로 전치 한다. 루트음을 그대로의 상태로 하지 않는다.
pChordMap
세그먼트(segment)에 적용하는 새로운 코드 맵의 IDirectMusicChordMap8 인터페이스에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

메소드는 세그먼트(segment)의 연주중에 호출할 수가 있다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicComposer8::ComposeSegmentFromShape

미리 정의된 셰이프에 근거해, 스타일과 코드 맵으로부터 오리지날의 섹션 세그먼트(segment)를 생성 한다. 이 셰이프는, 섹션 전체로 시간의 경과에 수반해 코드와 장식을 발생시키는 방법을 나타낸다.

HRESULT ComposeSegmentFromShape(
  IDirectMusicStyle* pStyle,
  WORD wNumMeasures,
  WORD wShape,
  WORD wActivity,
  BOOL fIntro,
  BOOL fEnd,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppSegment
);

파라미터

pStyle
섹션 세그먼트(segment)의 어레인지에 사용하는 스타일.
wNumMeasures
어레인지 하는 섹션 세그먼트(segment)의 길이. 소절 단위로 지정한다.
wShape
어레인지 하는 섹션 세그먼트(segment)의 셰이프. DMUS_SHAPET_TYPES 열거형의 몇개의 값을 지정한다.
wActivity
화음 진행의 레이트. 유효한 값은 0 ~ 3 이다. 값이 낮으면 코드 체인지가 증가한다.
fIntro
섹션 세그먼트(segment)의 인트로를 어레인지 하고 싶은 경우는 TRUE 를 설정한다.
fEnd
섹션 세그먼트(segment)의 엔딩을 어레인지 하고 싶은 경우는 TRUE 를 설정한다.
pChordMap
세그먼트(segment) 생성의 원이 되는, 코드 맵의 IDirectMusicChordMap8 인터페이스에의 포인터.
ppSegment
생성 된 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer8::ComposeSegmentFromTemplate ,IDirectMusicComposer8::ComposeTemplateFromShape


IDirectMusicComposer8::ComposeSegmentFromTemplate

스타일, 코드 맵, 및 템플릿으로부터, 오리지날의 세그먼트(segment)를 생성 한다.

HRESULT ComposeSegmentFromTemplate(
  IDirectMusicStyle* pStyle,
  IDirectMusicSegment* pTemplate,
  WORD wActivity,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppSegment
);

파라미터

pStyle
세그먼트(segment)의 생성에 사용하는 스타일을 지정하는 IDirectMusicStyle8 인터페이스 포인터.
pTemplate
세그먼트(segment)의 생성에 사용하는 템플릿을 지정하는 IDirectMusicSegment8 인터페이스 포인터.
wActivity
화음 진행의 레이트. 유효한 값은 0 ~ 3 이다. 값이 낮으면 코드 체인지가 증가한다.
pChordMap
세그먼트(segment)의 생성에 사용하는 코드 맵을 지정하는 IDirectMusicChordMap8 인터페이스 포인터.
ppSegment
생성 된 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

주의

pStyle 가 NULL 가 아닌 경우, 이 스타일은 세그먼트(segment)의 어레인지에 사용된다. NULL 의 경우,pTempSeg 로 지정된 템플릿으로부터 취득한 스타일을 세그먼트(segment)의 어레인지에 사용한다. 같이pChordMap 가 NULL 이외의 경우, 코드 맵은 세그먼트(segment)의 어레인지에 사용되어 NULL 의 경우, 코드 맵은 템플릿으로부터 취득된다.

pStyle 가 NULL 로 템플릿내에 스타일 트럭이 존재하지 않는 경우나,pChordMap 가 NULL 로 코드 맵 트럭이 존재하지 않는 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.

섹션 세그먼트(segment)의 길이는, 건네받은 템플릿 섹션의 길이와 동일해진다.

생성 된 세그먼트(segment)의 디폴트의 시작 포인트와 루프 포인트는, 템플릿 세그먼트(segment)내의 값에 관계없이 0 이다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer8::ComposeSegmentFromShape ,IDirectMusicComposer8::ComposeTemplateFromShape ,템플릿의 사용법


IDirectMusicComposer8::ComposeTemplateFromShape

미리 정의된 셰이프에 근거해 새로운 템플릿을 생성 한다.

HRESULT ComposeTemplateFromShape(
  WORD wNumMeasures,
  WORD wShape,
  BOOL fIntro,
  BOOL fEnd,
  WORD wEndLength,
  IDirectMusicSegment** ppTemplate
);

파라미터

wNumMeasures
어레인지 하는 섹션 세그먼트(segment)의 길이. 소절 단위로 지정한다. 0 보다 큰 값이 아니면 안된다.
wShape
어레인지 하는 섹션 세그먼트(segment)의 셰이프. DMUS_SHAPET_TYPES 열거형의 몇개의 값을 지정한다.
fIntro
섹션 세그먼트(segment)의 인트로를 어레인지 하고 싶은 경우는 TRUE 를 설정한다.
fEnd
섹션 세그먼트(segment)의 엔딩을 어레인지 하고 싶은 경우는 TRUE 를 설정한다.
wEndLength
엔딩을 생성 하고 싶은 경우는, 엔딩의 길이. 소절 단위로 지정한다. fEnd 가 TRUE 의 경우, 이 값은 0 보다 크고, 이용할 수 있는 소절의 수이하가 아니면 안된다 (즉, 인트로에서는 사용되지 않는다). 「주의」도 참조할것.
ppTemplate
생성 된 섹션 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

wEndLength 의 값은,IDirectMusicComposer8::ComposeSegmentFromTemplate 메소드를 사용해 이 템플릿에 관련지을 수 있을 가능성이 있는 임의의 스타일내에서 이용할 수 있는, 최장의 엔딩의 길이를 넘어서는 안 된다. 엔딩은, 세그먼트(segment)가 끝나기 전의 wEndLength 의 소절로 연주를 시작 한다. 엔딩이 wEndLength 의 소절의 길이보다 짧은 경우, 음악은 기본홈 레벨에 돌아온다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer8::ComposeSegmentFromTemplate ,템플릿의 사용법


IDirectMusicComposer8::ComposeTransition

어느 섹션 세그먼트(segment)로부터 다른 섹션 세그먼트(segment)에의 트란지션을 어레인지 한다.

HRESULT ComposeTransition(
  IDirectMusicSegment* pFromSeg,
  IDirectMusicSegment* pToSeg,
  MUSIC_TIME mtTime,
  WORD wCommand,
  DWORD dwFlags,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppTransSeg
);

파라미터

pFromSeg
트란지션의 어레인지에 사용되는 이행원의 섹션.
pToSeg
이행처 섹션. 트란지션은 이 섹션에 원활히 이행 한다. dwFlags 가 DMUS_COMPOSEF_MODULATE 를 포함하지 않은 경우, NULL 이라도 좋다.
mtTime
pFromSeg 의 섹션내에서 트란지션의 어레인지를 시작 하는 타임.
wCommand
트란지션을 생성 할 경우에 사용되는 장식. 이것에는,DMUS_COMMANDT_TYPES 열거형의 1 개인가, 또는 컨텐트 프로바이더에 의해 정의된 다른 값을 지정할 수 있다. 이 값이 DMUS_COMMANDT_ENDANDINTRO 의 경우, 메소드는,pFromSeg 의 엔딩과 pToSeg 의 인트로를 포함한 세그먼트(segment)를 어레인지 한다.
dwFlags
작곡가 옵션. 이 파라미터는,DMUS_COMPOSEF_FLAGS 열거형의 값의 1 개 또는 복수를 보관 유지할 수 있다.
pChordMap
트란지션을 어레인지 할 경우에 사용되는 코드 맵의,IDirectMusicChordMap8 인터페이스에의 포인터. 「주의」를 참조할것.
ppTransSeg
생성 된 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

pChordMap 의 값은 NULL 이라도 좋다. 값이 NULL 의 경우, 코드 맵 트럭으로부터 코드 맵을 취득하는 시도를 한다. 최초로 pToSeg, 다음에 pFromSeg 가 시험 받는다. 어느 세그먼트(segment)에도 코드 맵 트럭이 포함되지 않는 경우는,mtTime 에 pFromSeg 내에서 발생하는 코드가 트란지션의 코드로서 사용된다.

작곡가는, 최초로 pFromSeg 내, 다음에 pToSeg 내에서 템포를 찾는다. 어느 세그먼트(segment)에도 템포 트럭이 없는 경우, 트란지션세그먼트의 템포는 스타일로부터 취득된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer8::AutoTransition ,트란지션의 사용법


IDirectMusicContainer8

IDirectMusicContainer8 인터페이스를 사용하면(자), 컨테이너내의 오브젝트에 액세스 할 수 있다. 컨테이너란, 세그먼트(segment)나 퍼포먼스가 사용하는 오브젝트의 콜렉션이다. 이 인터페이스는,IDirectMusicLoader8::GetObject 또는 IDirectMusicLoader8::LoadObjectFromFile 를 호출하는 것으로, 컨테이너가 로드 될 때 취득할 수 있다.

컨테이너 오브젝트가 로드 되면(자), 컨테이너내의 모든 오브젝트가, 로더로부터 이용할 수 있게 된다. 컨테이너가 해방되면(자), 컨테이너가 참조하는 모든 오브젝트가 로더로부터 해방된다. 다만, 컨테이너 해방시에 사용중의 오브젝트는, 명시적으로 해방될 때까지는 해방되지 않는다. 그러한 오브젝트가, DLS 콜렉션이나 스트리밍 웨이브와 같이 스트리밍을 연 채로 하고 있는 경우는, 스트림도 연 채로 있다. 그 결과, 개별의 웨이브 파일이나 DLS 파일과 같게, 컨테이너 파일은 락 상태에 머무른다.

컨테이너는 세그먼트(segment)에 묻을 수가 있다. 파일내에서, 컨테이너는 세그먼트(segment)의 트럭의 전에 배치된다. 이것에 의해, 트럭이 로드 되기 전에, 컨테이너가 읽어내져 오브젝트가 로더에 인스톨 된다. 트럭이 로드 되면(자), 로더는, 컨테이너내의 참조 오브젝트에의 링크를 설정할 수 있다.

IDirectMusicCollection8 는,IDirectMusicCollection8 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

IDirectMusicContainer8 인터페이스에는 다음의 메소드가 있다.

열거 EnumObject

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. 이 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.

참조

컨테이너


IDirectMusicContainer8::EnumObject

컨테이너내의 오브젝트에 관한 정보를 취득한다.

HRESULT EnumObject(
  REFGUID rguidClass,
  DWORD dwIndex,
  LPDMUS_OBJECTDESC pDesc,
  WCHAR* pwszAlias
);

파라미터

rguidClass
오브젝트 클래스의 일의인 식별자에의 참조 (C++) 또는 주소 (C). 임의의 타입의 오브젝트를 취득하는 경우는 GUID_DirectMusicAllTypes. 표준적인 로더 부루크 라스의 리스트에 대해서는, 「IDirectMusicLoader8 」를 참조할것.
dwIndex
컨테이너에 포함되는 오브젝트 클래스 rguidClass 내의 오브젝트의 인덱스.
pDesc
오브젝트의 기술을 받는 DMUS_OBJECTDESC 구조체에의 포인터. 기술을 필요로 하지 않는 경우는, 이 파라미터를 NULL 로 한다. 「주의」를 참조할것.
pwszAlias
오브젝트의 앨리어스(alias)를 받는 MAX_PATH 사이즈의 캐릭터 라인 버퍼의 주소 (앨리어스(alias)가 있는 경우). 앨리어스(alias)는, 오브젝트를 참조하기 위해서 스크립트로 사용되는 특수한 이름이다. 앨리어스(alias)를 필요로 하지 않는 경우는, 이 파라미터를 NULL 로 한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 오브젝트가 열거되었다.
S_FALSE | dwIndex 의 인덱스를 가지는 오브젝트가 없다.
DMUS_S_STRING_TRUNCATED | 앨리어스(alias)가 MAX_PATH 보다 길다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

메소드에 건네주기 전에,DMUS_OBJECTDESC 구조체의 dwSize 멤버를 초기화할 필요가 있다. 그 외의 멤버는 무시된다. wszName 멤버의 값의 지정등에 의해 열거의 범위를 축소할 수 없다. 메소드에 의해 돌려주어진 기술을 사용해,IDirectMusicLoader8::GetObject 를 호출하는 것으로, 오브젝트를 취득할 수 있다. 샘플 코드에 대해서는, 「컨테이너」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicDownload8

연속한 메모리체크를 나타내,DLS 신디사이저 포토에의 다운로드를 실시하기 위해서(때문에) 사용된다.

IDirectMusicDownload8 는,IDirectMusicDownload 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

IDirectMusicDownload8 인터페이스와 그 중에 포함되어 있는 메모리체크는,IDirectMusicPortDownload8::AllocateBuffer 메소드에 의해 생성 된다. 그 후, 이 인터페이스의 1 개의 메소드를 사용해, 이 메모리에 액세스 할 수 있다.

이 인터페이스는, 퍼포먼스, 밴드, 및 세그먼트(segment)의 각 오브젝트에 음색 데이터를 다운로드시키기 위해서(때문에) 있는 것이 아니라, DLS 버퍼에 직접 액세스 할 필요가 있는 어플리케이션만이 사용한다. 개요에 대해서는, 「하위 레벨 DLS 」를 참조할것.

이 인터페이스는, 이하의 메소드를 지원 한다.

메모리 액세스 GetBuffer

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicDownload8::GetBuffer

다운로드해야 할 데이터를 보관 유지하는 버퍼에의 포인터를 취득한다.

HRESULT GetBuffer(
  void** ppvBuffer,
  DWORD* pdwSize
);

파라미터

ppvBuffer
데이터 버퍼에의 포인터를 받는 변수의 주소.
pdwSize
돌려주어진 버퍼의 사이즈 (바이트 단위)를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_BUFFERNOTAVAILABLE
E_POINTER

주의

버퍼가 이미 다운로드되고 있는 경우, 이 메소드는 DMUS_E_BUFFERNOTAVAILABLE 를 돌려준다.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicDownloadedInstrument8

IDirectMusicDownloadedInstrument8 인터페이스는,IDirectMusicPort8::DownloadInstrument 메소드 또는 IDirectMusicPerformance8::DownloadInstrument 메소드로, 신디사이저에 다운로드된 음색을 식별하기 위해서 사용된다. 다음에 이 인터페이스 포인터를 사용해,IDirectMusicPort8::UnloadInstrument 를 호출해, 그 음색을 언로드한다. 음색을 언로드하면(자), 인터페이스 포인터는 어플리케이션에 의해 해방되지 않으면 안 된다. 구체적인 예에 대해서는, 「음색의 조작」을 참조할것.

IDirectMusicDownloadedInstrument8 는,IDirectMusicDownloadedInstrument 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

IDirectMusicDownloadedInstrument8 인터페이스는 독자적인 메소드를 가지지 않는다. 모든 COM 인터페이스와 같이, 이 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicGetLoader8

IDirectMusicGetLoader8 인터페이스는, 스트림을 해석하는 오브젝트가, 스트림에 의해 참조되는 다른 오브젝트를 로드할 필요가 있는 경우에 사용된다. 스트림이 로더를 지원 하고 있는 경우, 스트림은 반드시 IDirectMusicGetLoader8 인터페이스를 제공하고 있다.

스트림으로부터 IDirectMusicGetLoader8 인터페이스를 취득하는 방법의 예에 대해서는, 「IDirectMusicGetLoader8::GetLoader 」를 참조할것.

IDirectMusicGetLoader8 는,IDirectMusicGetLoader 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

IDirectMusicGetLoader8 인터페이스에는 다음의 메소드가 있다.

IDirectMusicGetLoader8 GetLoader

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8 ,오디오 데이터의 로드,커스텀 로드


IDirectMusicGetLoader8::GetLoader

스트림을 생성 한 로더 오브젝트에의 포인터를 취득한다.

HRESULT GetLoader8(
  IDirectMusicLoader ** ppLoader
);

파라미터

ppLoader
IDirectMusicLoader 인터페이스 포인터를 받는 변수의 주소. IDirectMusicLoader8 를 취득하려면 ,QueryInterface 를 사용한다. 이 인터페이스의 참조 카운트는 인크리먼트(increment) 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

다음의 샘플 코드는, 로더가 액세스 할 필요가 있는 오브젝트에의 참조를 찾아내는 파일 퍼서로부터 발췌한 것이다.

HRESULT myGetReferencedObject(
    DMUS_OBJECTDESC *pDesc,          // 디스크립터는 이미 준비 되어 있다.
    IStream *pIStream,               // 해석 대상의 스트림.
    IDirectMusicObject **ppIObject)  // 액세스 하고 싶은 오브젝트.
{
    IDirectMusicGetLoader *pIGetLoader;
    IDirectMusicLoader *pILoader;
    ppIObject = NULL;
    HRESULT hr = pIStream->QueryInterface(
           IID_IDirectMusicGetLoader,
           (void **) &pIGetLoader );
    if (SUCCEEDED(hr))
    {
        hr = pIGetLoader->GetLoader(&pILoader);
        if (SUCCEEDED(hr))
        {
            hr = pILoader->GetObject(pDesc, IID_DirectMusicLoader,
                  (void**) ppIObject);
            pILoader->Release();
        }
        pIGetLoader->Release();
    }
    return hr;
}

동작환경

헤더 : dmusici.h 로 선언.

참조

커스텀 로드


IDirectMusicGraph8

IDirectMusicGraph8 인터페이스는, 툴의 로드와 메세지 플로우를 관리한다.

그래프는, 세그먼트(segment)와 퍼포먼스의 2 개의 장소에 둘 수가 있다. 퍼포먼스내의 툴에 대응하는 그래프는, 성질상 글로벌이며, 그 때문에(위해) 모든 세그먼트(segment)의 메세지를 처리한다. 어느 세그먼트(segment)내의 그래프는, 그 세그먼트(segment)의 재생만을 목적으로 해 존재한다.

IDirectMusicGraph8 는,IDirectMusicGraph 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

IDirectMusicGraph8 인터페이스에는 다음의 메소드가 있다.

루팅 | StampPMsg
툴 | GetTool
 | InsertTool
 | RemoveTool

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicGraph8::GetTool

지정된 인덱스의 툴을 취득한다.

HRESULT GetTool(
  DWORD dwIndex,
  IDirectMusicTool** ppTool
);

파라미터

dwIndex
그래프내의 희망의 툴을 지정하는, 0 으로부터 시작되는 인덱스.
ppTool
툴에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

취득한 툴의 해방은, 어플리케이션의 역할이다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicGraph8::InsertTool

그래프에 툴을 삽입한다.

HRESULT InsertTool(
  IDirectMusicTool * pTool,
  DWORD * pdwPChannels,
  DWORD cPChannels,
  LONG lIndex
);

파라미터

pTool
삽입하는 툴.
pdwPChannels
툴이 메세지를 받아들이는 P 채널의 배열의 주소. 이 툴이 모든 채널로 메세지를 받아들이는 경우는, NULL 를 건네준다.
cPChannels
pdwPChannels 가 가리키는 채널의 수. pdwPChannels 가 NULL 의 경우는 무시된다.
lIndex
툴을 두는 위치. 이것은 0 으로부터 시작되는 인덱스이다. 값이 정의 경우는 현재의 툴 리스트의 선두로부터 센 위치를 의미해, 값이 부의 경우는 리스트의 최후로부터 센 위치를 의미한다. lIndex 가 범위외의 경우, 툴은 리스트의 선두 또는 마지막에 놓여진다. 툴을 리스트의 마지막에 두려면 , 현재의 툴 리스트내의 툴수보다 큰 값을 lIndex 로 지정한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_ALREADY_EXISTS
E_OUTOFMEMORY
E_POINTER

주의

툴의 참조 카운트는 인크리먼트(increment) 된다.

이 메소드는 IDirectMusicTool8::Init 를 호출한다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicGraph8::RemoveTool

그래프로부터 툴을 삭제한다.

HRESULT RemoveTool(
  IDirectMusicTool * pTool
);

파라미터

pTool
삭제하는 툴.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

이 툴에의 그래프의 참조는 해방된다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicGraph8::StampPMsg

메세지를 받아들이는 다음의 툴에의 포인터를 메세지에 스탬프 한다. 툴은, 메세지를 처리한 후, 이 메소드를 호출하지 않으면 안 된다.

HRESULT StampPMsg(
  DMUS_PMSG* pPMSG
);

파라미터

pPMSG
스탬프의 대상이 되는 메세지를 보관 유지하는 구조체의 주소. 이 구조체는,DMUS_PMSG 의 파생 타입이다.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_LAST_TOOL 를 돌려준다. 「주의」를 참조할것.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

엔트리시에, 이 메세지 구조체의 DMUS_PMSG 부에 포함되는 pTool 멤버는 현재의 툴을 가리킨다. StampPMsg 는 이 멤버를 사용해, 현재의 툴을 결정해, 그래프내의 다음의 툴을 찾아낸다. NULL 의 값은 그래프내의 최초의 툴을 나타낸다.

pGraph 멤버가 가리키는 오브젝트는, 툴을 보관 유지하는 그래프를 나타낸다. StampPMsg 내부에서는, 이 값이 툴 자체의 값과 함께 스탬프 된다. 복수의 툴 그래프가 존재하는 경우, 메세지가 세그먼트(segment) 상태로부터 퍼포먼스에 이동하는 과정에서, 이 값이 변경되는 일이 있다.

dwType 의 값은, 메세지의 미디어 타입에 동일하고, 다음의 툴을 찾아내는데 사용된다. 미디어 타입으로서 지원 되고 있는 것은,IDirectMusicTool8::GetMediaTypes 메소드가 돌려주는 값이다.

이 메소드는 pTool 가 가리키는 현재의 IDirectMusicTool8 에 대해서 Release 를 호출해, 그래프내의 다음의 툴에 옮겨놓아 새로운 툴에 대해서 AddRef 를 호출한다. 이 메소드는, 다음의 툴이 IDirectMusicTool8::GetMsgDeliveryType 메소드로 돌려주는 타입에 근거해, 메세지에 올바른 인도 타입 플래그도 할당한다. 이 플래그는, 메세지를 다음의 툴에 전달하는 시기를 결정한다.

툴은, 반드시, 다른 태스크가 모두 실행되고 나서 StampPMsg 를 호출한다. 오디오 패스가 사용되고 있는 경우는,StampPMsg 에 의해, 메세지 구조체의 dwPChannel 멤버의 값이 변경되는 경우가 있다. 이 값을 사용하는 툴은,StampPMsg 를 호출한 후, 이 값을 사용할 수 없게 된다.

DirectMusicSegmentState 와 DirectMusicPerformance 의 각 오브젝트에서의 이 메소드를 이행 하면, 성공했을 경우, 항상 S_OK 를 돌려준다. DirectMusicGraph 로 이행 하면, 메세지의 수취를 기다리고 있는 출력 툴 외에 툴이 없는 경우, DMUS_S_LAST_TOOL 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

DirectMusic 툴


IDirectMusicInstrument8

IDirectMusicInstrument8 인터페이스는,DLS 콜렉션의 개별의 음색을 나타낸다.

IDirectMusicInstrument8 는,IDirectMusicInstrument 의 형태 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

DirectMusicInstrument 오브젝트를 생성 해, 음색을 다운로드하기 위한 유일한 방법은, 최초로 DirectMusicCollection 오브젝트를 생성 해, 다음에 IDirectMusicCollection8::GetInstrument 메소드를 호출하는 것이다. GetInstrument 는 DirectMusicInstrument 오브젝트를 생성 해,IDirectMusicInstrument8 인터페이스 포인터를 돌려준다.

음색을 다운로드하려면 , 그 인터페이스 포인터를 IDirectMusicPort8::DownloadInstrument 메소드 또는 IDirectMusicPerformance8::DownloadInstrument 메소드에 건네준다. 이 메소드가 성공하면(자),IDirectMusicDownloadedInstrument8 인터페이스에의 포인터가 돌려주어진다. 이 인터페이스는, 음색을 언로드하는 경우에게만 사용된다.

IDirectMusicInstrument8 의 메소드는, 이미 다운로드되고 있는 음색에만 대해 동작한다. 포토에 다운로드된 음색의 인스턴스는,IDirectMusicInstrument8::GetPatch 메소드나 IDirectMusicInstrument8::SetPatch 메소드에 의한 영향은 받지 않는다.

이 인터페이스는, 이하의 메소드를 지원 한다.

IDirectMusicInstrument8 | GetPatch
 | SetPatch

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICINTRUMENT8 형은, 이 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicInstrument8 *LPDIRECTMUSICINSTRUMENT8;

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicInstrument8::GetPatch

음색의 패치 번호를 취득한다. 이 패치 번호는,뱅크 셀렉트의 MSB 와 LSB, 및 MIDI 패치 (프로그램 체인지) 번호에 의해 구성된 주소이다. 옵션의 flag bit는, 음색이 선율계의 음색은 아니고, 드럼인 것을 나타낸다.

HRESULT GetPatch(
  DWORD* pdwPatch
);

파라미터

pdwPatch
패치 번호를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_POINTER

주의

pdwPatch 에 돌려주어지는 패치 번호는,뱅크 셀렉트의 MSB 와 LSB 의 MIDI 파라미터도 포함한, 완전한 패치 번호를 나타낸다. 더해, 특히 음색이 드럼 킷이며, MIDI 채널 10 으로 연주되는 것을 의도하고 있는 경우는, 상위 비트가 설정된다. DLS 레벨 1 은 드럼을 반드시 MIDI 채널 10 으로 연주하기 위해(때문에), 이것이 DLS 레벨 1 용의 특별한 태그이다. 상세한 것에 대하여는, 「MIDI 채널 메세지」를 참조할것.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicInstrument8::SetPatch

음색의 패치 번호를 취득한다. DLS 콜렉션내의 각 음색은 미리 정의된 패치 번호를 가지고 있지만,IDirectMusicCollection8::GetInstrument 메소드를 사용해 콜렉션으로부터 음색을 취득한 후, 패치 번호를 재할인 맞히고 할 수도 있다. DirectMusic 패치 번호의 상세한 것에 대하여는, 「IDirectMusicInstrument8::GetPatch 」를 참조할것.

HRESULT SetPatch(
  DWORD dwPatch
);

파라미터

dwPatch
음색에 할당하는 새로운 패치 번호.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_CORE_INVALIDPATCH

주의

다음의 샘플 코드는, 콜렉션으로부터 음색을 취득해, 음색의 MSB 뱅크의 재맵을 실시해 다른 뱅크를 선택해, 그 음색을 다운로드한다.

HRESULT myRemappedDownload(
    IDirectMusicCollection8 *pCollection,
    IDirectMusicPort8 *pPort,
    IDirectMusicDownloadedInstrument8 **ppDLInstrument,
    BYTE bMSB,       // 패치 번호의 뱅크 셀렉트내에서 지정된 MIDI 의 MSB.
    DWORD dwPatch)   // 지정된 패치 번호.

{
    HRESULT hr;
    IDirectMusicInstrument8* pInstrument;
    hr = pCollection->GetInstrument(dwPatch, &pInstrument);
    if (SUCCEEDED(hr))
    {
        dwPatch &= 0xFF00FFFF;  // MSB 를 소거한다.
        dwPatch |= bMSB << 16;  // 새로운 MSB 의 값을 설정한다.
        pInstrument->SetPatch(dwPatch);
        hr = pPort->DownloadInstrument(pInstrument,
                ppDLInstrument,
                NULL, 0);       // 모든 리젼을 다운로드한다.
        pInstrument->Release();
    }
    return hr;
}

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicLoader8

IDirectMusicLoader8 인터페이스는, 오브젝트의 검색, 열거, 캐싱, 및 로드에 사용된다. 개요에 대해서는, 「오디오 데이터의 로드」를 참조할것.

이 인터페이스는,IDirectMusicLoader 를 계승해, 가베지 콜렉션의 지원을 추가한다.

IDirectMusicLoader8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

검색 | EnumObject
 | ScanDirectory
 | SetSearchDirectory
캐쉬와 메모리의 관리 | CacheObject
 | ClearCache
 | CollectGarbage
 | EnableCache
 | ReleaseObject
 | ReleaseObjectByUnknown
오브젝트의 로드 | GetObject
 | LoadObjectFromFile
 | SetObject

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_LOADER 형은,IDirectMusicLoader 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicLoader __RPC_FAR *LPDMUS_LOADER;

다음의 표는, 로드 가능한 오브젝트의 표준 타입과 그 클래스 식별자 (오브젝트를 처리하는 각종 메소드의 rguidClass 파라미터), 및 보통의 파일명의 확장자(extension)의 리스트이다.

오브젝트 타입 | 클래스 | 확장자(extension)
오디오 패스 | CLSID_DirectMusicAudioPathConfig | aud
밴드 | CLSID_DirectMusicBand | bnd
컨테이너 | CLSID_DirectMusicContainer | con
DLS 콜렉션 | CLSID_DirectMusicCollection | dls
코드 맵 | CLSID_DirectMusicChordMap | cdm
세그먼트(segment) | CLSID_DirectMusicSegment | sgt
스크립트 | CLSID_DirectMusicScript | spt
노래* | CLSID_DirectMusicSong | sng
스타일 | CLSID_DirectMusicStyle | sty
템플릿 | CLSID_DirectMusicSegment | tpl
툴 그래프 | CLSID_DirectMusicGraph | tgr
웨이브 | CLSID_DirectSoundWave | wav

* DirectX 8.0 에서는 이행되어 있지 않다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicLoader8::CacheObject

오브젝트에의 참조를 유지하도록(듯이) 로더에 지시한다. 이 결과, 오브젝트를 2 회 로드하지 않는 것이 보증된다.

HRESULT CacheObject(
  IDirectMusicObject * pObject
);

파라미터

pObject
캐쉬에 넣는 오브젝트의 IDirectMusicObject 인터페이스의 주소. IDirectMusicObject8 를 취득하려면 ,QueryInterface 를 사용한다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 오브젝트가 이미 캐쉬에 들어가 있는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
DMUS_E_LOADER_OBJECTNOTFOUND

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::EnableCache ,IDirectMusicLoader8::ClearCache ,IDirectMusicLoader8::ReleaseObject ,캐쉬의 관리


IDirectMusicLoader8::ClearCache

특정의 타입의 오브젝트에의 모든 참조를 해방하도록(듯이) 로더에 지시한다.

HRESULT ClearCache(
  REFGUID rguidClass
);

파라미터

rguidClass
소거하는 오브젝트 클래스의 식별자에의 참조 (C++) 또는 주소 (C). 모든 타입의 오브젝트를 소거하는 경우는 GUID_DirectMusicAllTypes. 표준적인 로더 부루크 라스의 리스트에 대해서는, 「IDirectMusicLoader8 」를 참조할것.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 현재 보관 유지 떠날 수 있어 모든 오브젝트를 소거하지만, 캐싱을 무효로 할 것은 없다. 자동적인 캐싱을 무효로 하려면 ,IDirectMusicLoader8::EnableCache 메소드를 사용한다.

캐쉬로부터 1 개의 오브젝트를 소거하려면 ,IDirectMusicLoader8::ReleaseObject 메소드를 호출한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::CacheObject ,캐쉬의 관리


IDirectMusicLoader8::CollectGarbage

사용중이 아닌 오브젝트를 캐쉬로부터 삭제한다.

CollectGarbage();

파라미터

없음.

반환값

없음.

주의

어플리케이션이 오브젝트에 대해서 IDirectMusicLoader8::ReleaseObject 를 호출하는 경우, 그 오브젝트는 캐쉬로부터 삭제되어 그 오브젝트가 참조하는 오브젝트는 삭제 후보가 된다. IDirectMusicLoader8::CollectGarbage 는, 다른 오브젝트가 사용중이 아닌 캐쉬된 오브젝트를 찾아내 캐쉬로부터 삭제해, 메모리로부터 해방한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

가베지 콜렉션


IDirectMusicLoader8::EnableCache

로드 되는 모든 오브젝트의 자동적인 캐싱을 유효 또는 무효로 하도록(듯이) 로더에 지시한다. 디폴트에서는, 모든 클래스에서 캐싱이 유효하게 되어 있다.

HRESULT EnableCache(
  REFGUID rguidClass,
  BOOL fEnable
);

파라미터

rguidClass
캐쉬하는 오브젝트 클래스의 식별자에의 참조 (C++) 또는 주소 (C). 모든 타입의 오브젝트를 캐쉬하는 경우는 GUID_DirectMusicAllTypes. 표준적인 로더 부루크 라스의 리스트에 대해서는, 「IDirectMusicLoader8 」를 참조할것.
fEnable
캐싱을 유효하게 하는 경우는 TRUE, 캐싱을 무효로 해 소거하는 경우는 FALSE 를 설정한다.

반환값

캐쉬 상태가 변경되는 경우는 S_OK, 캐쉬가 이미 희망 상태가 되어 있는 경우는 S_FALSE 를 돌려준다.

주의

캐싱을 무효로 하지 않고 캐쉬를 소거하려면 ,IDirectMusicLoader8::ClearCache 메소드를 호출한다.

다음의 샘플 코드는, 세그먼트(segment) 오브젝트에 한해서 캐싱을 무효로 하므로, 어플리케이션이 그것들을 해방한 후는 그러한 오브젝트는 메모리내에 머무를 것은 없다. 스타일, 코드 맵, DLS 콜렉션 등, 공유해야 할 그 외의 오브젝트는 계속해 캐싱 되고 있다. 디폴트로 모든 오브젝트의 캐싱은 유효하게 되어 있으므로,EnableCache 의 최초의 호출은, 보통은 불필요하다.

void myPrepareLoader(IDirectMusicLoader8 *pILoader)

{
    pILoader->EnableCache(GUID_DirectMusicAllTypes, TRUE);
    pILoader->EnableCache(CLSID_DirectMusicSegment, FALSE);
}

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::CacheObject ,IDirectMusicLoader8::ClearCache ,캐쉬의 관리


IDirectMusicLoader8::EnumObject

요구된 타입의 이용 가능한 모든 오브젝트를 열거한다. 이용 가능한 오브젝트란, 이미 로드 되고 있는 것, 또는 IDirectMusicLoader8::ScanDirectory 를 호출했을 때에 검색 디렉토리내에 존재하고 있던 것이다.

HRESULT EnumObject(
  REFGUID rguidClass,
  DWORD dwIndex,
  LPDMUS_OBJECTDESC pDesc
);

파라미터

rguidClass
표시되는 오브젝트의 클래스 식별자에의 참조 (C++) 또는 주소 (C). 표준적인 로더 부루크 라스의 리스트에 대해서는, 「IDirectMusicLoader8 」를 참조할것.
dwIndex
리스트의 인덱스. 보통은 0 으로부터 시작되어, 값이 순서에 커진다.
pDesc
오브젝트에 관한 데이터를 입력하기 위한 DMUS_OBJECTDESC 구조체의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다. dwIndex 가 리스트의 최후를 넘고 있는 경우는 S_FALSE 를 돌려준다.

주의

이 메소드의 사용법의 예에 대해서는, 「오브젝트의 열거」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::ScanDirectory


IDirectMusicLoader8::GetObject

지정된 오브젝트를 파일 또는 리소스로부터 취득해, 목적의 인터페이스를 돌려준다.

HRESULT GetObject(
  LPDMUS_OBJECTDESC pDesc,
  REFIID riid,
  LPVOID FAR * ppv
);

파라미터

pDesc
오브젝트에 대해 기술하는 DMUS_OBJECTDESC 구조체의 주소.
riid
인터페이스의 일의의 식별자. Dmusici.h 로 정의되고 있는 IID 를 참조할것. 표준적인 인터페이스는 모두,"IID_" 와 인터페이스의 이름으로 구성되는 정의 끝난 식별자를 가진다. 예를 들어,IDirectMusicTrack8 의 식별자는 IID_IDirectMusicTrack8 이다.
ppv
오브젝트의 목적의 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_PARTIALLOAD 를 돌려준다.

세그먼트(segment)로 참조되는 스타일 등, 참조되는 오브젝트가 발견되지 않는 경우는, DMUS_S_PARTIALLOAD 가 돌려주어진다. 스타일이 이름으로 참조되어 그 스타일에 대해서 IDirectMusicLoader8::ScanDirectory 가 불려 가지 않은 경우, 로더는 스타일을 찾아낼 수가 없는 경우가 있다. 디폴트의 음색 콜렉션 파일인 Gm.dls 를 이용할 수 없는 경우에도, DMUS_S_PARTIALLOAD 가 돌려주어지는 일이 있다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_NOCLASSID
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
REGDB_E_CLASSNOTREG

주의

파일 오브젝트의 경우는,IDirectMusicLoader8::LoadObjectFromFile 메소드를 사용하는 (분)편이 간단하다.

DirectMusic 는 URL 로부터의 로딩을 지원 하지 않는다. DMUS_OBJECTDESC 구조체의 dwValidData 멤버가 DMUS_OBJ_URL 를 포함하고 있는 경우, 이 메소드는 DMUS_E_LOADER_FORMATNOTSUPPORTED 를 돌려준다.

이 메소드는, 오브젝트를 취득하기 전에 DMUS_OBJECTDESC 의 상당하는 멤버를 필요로 할 것은 없다. 이 메소드는 다음의 순서로 검색을 실시한다.

  1. DMUS_OBJ_OBJECT
  2. DMUS_OBJ_MEMORY
  3. DMUS_OBJ_FILENAME 와 DMUS_OBJ_FULLPATH
  4. DMUS_OBJ_NAME 과 DMUS_OBJ_CATEGORY
  5. DMUS_OBJ_NAME
  6. DMUS_OBJ_FILENAME

바꾸어 말하면(자), 가장 우선 순위가 높은 것은 일의의 GUID 이며, 이하는, 리소스, 풀 패스명, 내부명과 카테고리, 내부명, 로컬 파일명의 순서이다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::ReleaseObject ,IDirectMusicLoader8::ScanDirectory ,IDirectMusicLoader8::LoadObjectFromFile


IDirectMusicLoader8::LoadObjectFromFile

지정된 오브젝트를 파일로부터 취득해, 목적의 인터페이스를 돌려준다. 이 메소드는, 오브젝트가 파일내에 있을 때,IDirectMusicLoader8::GetObject 대신에 사용할 수가 있다.

HRESULT LoadObjectFromFile(
  REFGUID rguidClassID,
  REFIID iidInterfaceID,
  WCHAR *pwzFilePath,
  void ** ppObject
);

파라미터

rguidClassID
오브젝트 클래스의 일의의 식별자. 표준적인 로더 부루크 라스의 리스트에 대해서는, 「IDirectMusicLoader8 」를 참조할것.
iidInterfaceID
인터페이스의 일의의 식별자. Dmusici.h 로 정의되고 있는 IID 를 참조할것. 표준적인 인터페이스는 모두,"IID_" 와 인터페이스의 이름으로 구성되는 정의 끝난 식별자를 가진다. 예를 들어,IDirectMusicTrack8 의 식별자는 IID_IDirectMusicTrack8 이다.
pwzFilePath
오브젝트를 보관 유지하는 파일의 이름. 풀 패스인가, 또는 검색 디렉토리로부터의 상대 패스를 사용할 수 있다.
ppObject
오브젝트의 목적의 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_PARTIALLOAD 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_NOCLASSID
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
REGDB_E_CLASSNOTREG

주의

세그먼트(segment)로 참조되는 스타일 등, 참조되는 오브젝트가 발견되지 않는 경우는, DMUS_S_PARTIALLOAD 가 돌려주어진다. 스타일이 이름으로 참조되어 그 스타일에 대해서 IDirectMusicLoader8::ScanDirectory 가 불려 가지 않은 경우, 로더는 스타일을 찾아낼 수가 없는 경우가 있다. 디폴트의 음색 콜렉션 파일인 Gm.dls 를 이용할 수 없는 경우에도, DMUS_S_PARTIALLOAD 가 돌려주어지는 일이 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::GetObject ,IDirectMusicLoader8::SetSearchDirectory


IDirectMusicLoader8::ReleaseObject

오브젝트에의 로더의 참조를 해방한다.

HRESULT ReleaseObject(
  IDirectMusicObject * pObject
);

파라미터

pObject
해방하는 오브젝트의 IDirectMusicObject8 인터페이스 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다. 오브젝트가 이미 해방되고 있는지, 또는 캐쉬내에서 검출되지 않는 경우는, S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

ReleaseObject 는,IDirectMusicLoader8::CacheObject 와 대를 이루는 메소드이다.

오브젝트의 캐싱은,CacheObject 메소드를 사용해 명시적으로, 또는 IDirectMusicLoader8::EnableCache 메소드를 사용해 자동적으로 실시할 수가 있다.

특정의 타입의 모든 오브젝트를 플래시 (해방) 하도록(듯이) 로더에 지시하려면 ,IDirectMusicLoader8::ClearCache 메소드를 호출한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::ReleaseObjectByUnknown ,IDirectMusicLoader8::GetObject ,캐쉬의 관리


IDirectMusicLoader8::ReleaseObjectByUnknown

오브젝트에의 로더의 참조를 해방한다. 이 메소드는,IDirectMusicLoader8::ReleaseObject 에 유사하고 있어,IDirectMusicObject8 인터페이스를 곧바로는 이용할 수 없는 오브젝트를 해방하는데 적합하다.

HRESULT ReleaseObject(
  IUnknown * pObject
);

파라미터

pObject
해방하는 오브젝트의 IUnknown 인터페이스 포인터의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다. 오브젝트가 이미 해방되고 있는지, 또는 캐쉬내에서 검출되지 않는 경우는, S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::GetObject ,캐쉬의 관리


IDirectMusicLoader8::ScanDirectory

디스크내가 있는 디렉토리에서, 지정의 쿠라스타이프와 파일명의 확장자(extension)를 가지는 모든 파일을 검색한다. 파일이 발견될 때마다,IDirectMusicObject8::ParseDescriptor 메소드를 호출해, 오브젝트의 GUID 와 이름을 추출한다. 이 정보는 내부 데이타베이스에 보존된다. 어느 디렉토리를 검색한 후, 지정된 타입에 속하는 모든 파일은 IDirectMusicLoader8::EnumObject 메소드의 열거형으로서 이용 가능하게 된다. 더해,IDirectMusicLoader8::GetObject 를 사용할 때에, 파일명없이도 오브젝트가 취득 가능하게 된다.

HRESULT ScanDirectory(
  REFGUID rguidClass,
  WCHAR* pwzFileExtension,
  WCHAR* pwzScanFileName
);

파라미터

rguidClass
오브젝트의 클래스 식별자에의 참조 (C++) 또는 주소 (C). 표준적인 로더 부루크 라스의 리스트에 대해서는, 「IDirectMusicLoader8 」를 참조할것.
pwzFileExtension
검색하는 파일의 타입을 나타내는 파일명의 확장자(extension). "*" (을)를 사용해, 임의의 확장자(extension)가 붙은 파일 또는 확장자(extension)가 없는 파일을 검색한다. 「주의」를 참조할것.
pwzScanFileName
캐싱 된 파일 정보의 보존과 취득을 행하기 위한 보존 파일. 생략 가능. 최초로 ScanDirectory 를 호출했을 때에 이 파일이 생성 되어 그 이후의 호출로 사용된다. 캐쉬 파일이 불필요한 경우는 NULL 를 지정한다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 파일이 발견되지 않았던 경우는 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_FAIL
E_OUTOFMEMORY
E_POINTER
REGDB_E_CLASSNOTREG

주의

검색의 장소를 설정하기 위해서, 최초로 IDirectMusicLoader8::SetSearchDirectory 메소드를 호출하지 않으면 안 된다.

pwzScanFileName 로 정의되는 파일에, 검색된 정보를 보존할 수 있다. 보존을 실시하면, 변경을 더해진 파일만이 검색되기 (위해)때문에, 그 이후의 ScanDirectory 의 호출이 큰폭으로 고속화된다 (캐쉬 파일에는 각 오브젝트의 파일 사이즈와 일자가 보존되므로, 파일이 변경되었을 경우는 그것을 검출할 수 있다).

GUID_DirectMusicAllTypes 는 rguidClass 의 유효한 값은 아니다.

파일 타입이 복수의 확장자(extension)를 가질 가능성이 있는 경우, 파일명의 확장자(extension) 마다 ScanDirectory 를 1 회 호출한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

디렉토리에서의 오브젝트 검색


IDirectMusicLoader8::SetObject

오브젝트가, 로드안의 다른 오브젝트에 의해 다음에 참조될 때, 오브젝트의 검색 장소를 로더에 지시한다. 다음에, 오브젝트에 속성을 추가하는 것에 의해, 속성을 사용해 그 오브젝트를 참조할 수 있도록(듯이) 한다. 개요에 대해서는, 「오브젝트의 설정」을 참조할것.

HRESULT SetObject(
  LPDMUS_OBJECTDESC pDesc
);

파라미터

pDesc
오브젝트에 대해 기술하는 DMUS_OBJECTDESC 구조체의 주소. 엔트리시에, 이 구조체는 오브젝트에 관해서 어플리케이션이 가지는 모든 정보를 보관 유지한다. 반환값으로서 이 구조체는 추가의 정보를 보관 유지하고 있는 경우가 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_NOCLASSID
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
REGDB_E_CLASSNOTREG

주의

이 메소드를 사용해, 오브젝트에 대해 현재 유효하지 않은 속성을 설정할 수 있다. 예를 들어,DMUS_OBJECTDESC 구조체의 wszName 멤버에 값을 입력해, MIDI 파일에 근거하는 세그먼트(segment) 등, 이름이 없는 오브젝트에 내부명을 할당할 수가 있다. 다만, 기존 속성을 변경하는 목적으로 이 메소드를 사용할 수 없다. 예를 들어, 대부분의 오쏘링 된 세그먼트(segment)는 이미 이름을 가지고 있어 이러한 이름을 어플리케이션에 의해 변경할 수 없다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::GetObject


IDirectMusicLoader8::SetSearchDirectory

오브젝트 파일을 찾기 위한 검색 패스를 설정한다. 1 개의 오브젝트 타입, 또는 모든 파일에 대한 검색 패스를 설정할 수 있다.

HRESULT SetSearchDirectory(
  REFGUID rguidClass,
  WCHAR* pwszPath,
  BOOL fClear
);

파라미터

rguidClass
호출에 관계가 있는 오브젝트의 클래스 식별자에의 참조 (C++) 또는 주소 (C). GUID_DirectMusicAllTypes 는, 모든 타입을 지정한다. 표준적인 로더 부루크 라스의 리스트에 대해서는, 「IDirectMusicLoader8 」를 참조할것.
pwszPath
디렉토리의 파일 패스. 길이가 MAX_PATH 이하의 유효한 디렉토리명이 아니면 안된다. 풀 패스인가, 또는 IDirectMusicLoader8::ScanDirectory 의 호출시의 현재 디렉토리로부터의 상대 패스이다.
fClear
TRUE 의 경우, 디렉토리를 설정하기 전에, 오브젝트에 관한 모든 정보를 소거한다. 이 결과, 같은 이름을 가지는 것 외의 디렉토리에 있는 오브젝트에의 액세스를 회피할 수 있다. 다만, 그러한 오브젝트는 캐쉬로부터 삭제되는 것은 아니다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 검색 디렉토리가 이미 pwszPath 로 설정되어 있는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_BADPATH

주의

검색 패스를 설정한 후, 로더는 파일명을 사용해 오브젝트를 로드할 때, 풀 패스명을 필요로 하지 않는다. 이 결과, 오브젝트는 풀 패스를 파악하고 있지 않아도 다른 오브젝트를 참조할 수 있다.

이 메소드가 불려 갔을 때에,DMUS_OBJECTDESC 구조체의 dwValidData 멤버에 DMUS_OBJ_FULLPATH 플래그가 설정되어 있지 않으면, 로더는 wszFileName 멤버가 파일명만, 또는 검색 디렉토리로부터의 상대 패스를 보관 유지하고 있는 것을 상정한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader8::ScanDirectory ,로더의 검색 디렉토리의 설정


IDirectMusicObject8

파일로부터 로드 가능한 모든 DirectMusic 오브젝트는, DirectMusic 로더로 조작할 수 있도록(듯이) IDirectMusicObject8 인터페이스를 지원 한다. 새로운 타입의 오브젝트는, 이 인터페이스를 이행 해야 한다. 상세한 것에 대하여는, 「커스텀 로드」를 참조할것.

대부분의 어플리케이션은, 이 인터페이스의 메소드를 직접 사용하지 않는다. 다만,IDirectMusicObject8::GetDescriptor 를 사용해, 오브젝트의 이름, GUID, 파일 패스, 버젼 등, 오브젝트에 관한 정보를 문의할 수가 있다.

IDirectMusicObject8 인터페이스는 보통, 다른 인터페이스의 QueryInterface 메소드를 호출하는 것에 의해 취득된다. CoCreateInstance 를 사용해 호출할 수 없다. IDirectMusicObject8 인터페이스는,IDirectMusicContainer8::EnumObject 로 취득할 수도 있다.

IDirectMusicObject8 는,IDirectMusicObject 의 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

IDirectMusicObject8 인터페이스에는 다음의 메소드가 있다.

디스크립터 | GetDescriptor
 | ParseDescriptor
 | SetDescriptor

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_OBJECT 형은,IDirectMusicObject 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicObject __RPC_FAR *LPDMUS_OBJECT;

동작환경

헤더 : dmusici.h 로 선언.

참조

오디오 데이터의 로드,커스텀 로드


IDirectMusicObject8::GetDescriptor

오브젝트의 내부적인 기술을 취득한다.

HRESULT GetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

파라미터

pDesc
오브젝트에 관한 데이터를 입력하기 위한 DMUS_OBJECTDESC 구조체의 주소. 오브젝트의 이행과 오브젝트를 파일로부터 로드한 방법에 근거해,GetDescriptor 가 표준적인 파라미터의 일부 또는 모든 것을 입력한다. dwValidData 멤버내의 플래그를 체크해, 다른 유효한 멤버를 확인한다.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_GARBAGE_COLLECTED 를 돌려준다. 「가베지 콜렉션」을 참조할것.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

구체적인 예에 대해서는, 「오브젝트 디스크립터의 취득」을 참조할것.

동작환경

헤더 : dmusici.h 으로 선언.

참조

IDirectMusicObject8::SetDescriptor


IDirectMusicObject8::ParseDescriptor

IDirectMusicObject8::ParseDescriptor 메소드는 파일 스트림을 받아,DMUS_OBJECTDESC 구조체에 보존할 수 있는 데이터를 파일로부터 검색한다. dwValidData 내에서, 공급된 멤버에 대해서 적절한 플래그를 할당한다.

이 메소드는, 주로 로더가 디렉토리에서 오브젝트를 검색할 때에 사용되는 것이어, 보통은 어플리케이션이 직접 이용할 것은 없다. 다만, 어플리케이션이 DirectMusic 내에 오브젝트 타입을 이행 하는 경우, 그 어플리케이션은 이 메소드를 지원 해야 한다.

HRESULT ParseDescriptor(
  LPSTREAM pStream,
  LPDMUS_OBJECTDESC pDesc
);

파라미터

pStream
파일의 스트림 소스.
pDesc
파일에 관한 데이터를 받는 DMUS_OBJECTDESC 구조체의 주소.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_GARBAGE_COLLECTED 를 돌려준다. 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_CHUNKNOTFOUND
DMUS_E_INVALID_BAND
DMUS_E_INVALIDFILE
DMUS_E_NOTADLSCOL
E_FAIL
E_OUTOFMEMORY
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicObject8::SetDescriptor


IDirectMusicObject8::SetDescriptor

오브젝트의 내부적인 기술을 일부 또는 모든 멤버로 설정한다.

이 메소드는, 주로 로더가 오브젝트를 생성 할 때에 사용되는 것이어, 보통은 어플리케이션이 직접 이용할 것은 없다. 다만, 어플리케이션이 DirectMusic 내에 오브젝트 타입을 이행 하는 경우, 그 어플리케이션은 이 메소드를 지원 해야 한다.

HRESULT SetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

파라미터

pDesc
오브젝트에 관한 데이터를 받는 DMUS_OBJECTDESC 구조체의 주소. dwValidData 멤버로 유효라고 정의 떠날 수 있어 모든 멤버에 데이터가 카피된다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 디스크립터가 설정되었다.
S_FALSE | 「주의」를 참조할것.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

주의

어플리케이션은 보통, 표준적인 오브젝트에 대해서 이 메소드를 호출할 것은 없다. IDirectMusicObject8::GetDescriptor 에 의해 돌려주어지는 오브젝트 디스크립터를 변경하는 것은 가능하지만, 새로운 기술을 IDirectMusicLoader8::GetObject 메소드에 정상적으로 건네줄 수 없다. 예를 들어, 오브젝트의 이름을 변경할 수 있지만, 변경해도,GetObject 는 오브젝트의 전의 이름을 사용해 그 오브젝트를 검색한다. 이것은,GetObject 가 오브젝트 자체의 SetDescriptor 의 이행에 의존하고 있기 때문에 있다.

카피되지 않았던 멤버는, 지금까지의 값을 유지한다. 예를 들어, 어느 오브젝트가 이름과 GUID 를 이미 내부에서 보존하고 있었다고 한다. 새로운 이름과 파일 패스를 지정해 (한층 더 dwValidData 에 DMUS_OBJ_NAME | DMUS_OBJ_FILENAME 를 포함해) SetDescriptor 메소드를 호출하면, 이름은 옮겨놓을 수 있어 파일명이 제공되지만, GUID 만일 수 있는은 원의 값대로 된다.

오브젝트가 1 개 또는 복수의 멤버를 설정할 수 없는 경우, 스스로가 지원 하고 있는 멤버만을 설정해, 지원 하고 있지 않는 멤버에 대응하는 dwValidData 내의 플래그를 소거해, S_FALSE 를 돌려준다. 어플리케이션에 의해 정의되는 오브젝트는, 적어도 DMUS_OBJ_NAME 와 DMUS_OBJ_OBJECT 를 지원 해야 한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicObject8::ParseDescriptor ,IDirectMusicObject8::GetDescriptor


IDirectMusicPatternTrack8

IDirectMusicPatternTrack8 인터페이스는, 단일의 패턴을 보관 유지하는 트럭을 나타낸다. 패턴 트럭은, 순서 트럭 과 유사하지만, 고정된 노트는 아니고 뮤직값을 보관 유지하므로, 코드 체인지에 대응한다.

IID_DirectMusicPatternTrack 를 패턴 트럭의 IDirectMusicTrack8::QueryInterface 메소드에 건네주는 것으로, 이 인터페이스를 취득할 수 있다.

IDirectMusicPatternTrack8 인터페이스에는 다음의 메소드가 있다.

세그먼트(segment)의 생성 | CreateSegment
패턴의 설정 | SetPatternByName
바리에이션의 설정 | SetVariation

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPatternTrack8::CreateSegment

패턴 트럭을 보관 유지하는 세그먼트(segment)를 생성 한다.

HRESULT CreateSegment(
  IDirectMusicStyle* pStyle,
  IDirectMusicSegment** ppSegment
);

파라미터

pStyle
세그먼트(segment)를 생성 할 때에 사용하는 스타일.
ppSegment
생성 된 세그먼트(segment)의 IDirectMusicSegment 인터페이스 포인터를 받는 변수의 주소. IDirectMusicSegment8 를 취득하려면 , QueryInterface 를 사용한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_OUTOFMEMORY

주의

패턴 트럭은 보통, 파일이나 리소스로부터 로드 된 세그먼트(segment) 오브젝트로부터 취득된다. 이 경우, 어플리케이션은 이미 IDirectMusicSegment 인터페이스를 가지고 있다. 이 메소드는, 패턴 트럭 오브젝트가 CoCreateInstance 로 생성 되었을 경우에, 세그먼트(segment)를 생성 하기 위해서 사용한다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPatternTrack8::SetPatternByName

트럭으로 재생되는 패턴을 설정한다. 패턴은 스타일로부터 취득한다.

HRESULT SetPatternByName(
  IDirectMusicSegmentState* pSegState,
  WCHAR* wszName,
  IDirectMusicStyle* pStyle,
  DWORD dwPatternType,
  DWORD* pdwLength
);

파라미터

pSegState
트럭을 재생하고 있는 세그먼트(segment) 상태의 IDirectMusicSegmentState8 인터페이스의 주소.
wszName
설정하는 패턴의 이름. 이름은 IDirectMusicStyle8::EnumPattern 를 사용해 취득할 수 있다.
pStyle
패턴을 보관 유지하는 스타일의 IDirectMusicStyle 또는 IDirectMusicStyle8 인터페이스의 주소.
dwPatternType
패턴의 타입을 지정하는 DMUS_STYLET_TYPES 열거의 1 개.
pdwLength
패턴의 길이 (뮤직 타임의 틱 단위)를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPatternTrack8::SetVariation

트럭으로 재생되는 바리에이션을 설정한다.

HRESULT SetVariation(
  IDirectMusicSegmentState* pSegState,
  DWORD dwVariationFlags,
  DWORD dwPart
);

파라미터

pSegState
트럭을 재생하고 있는 세그먼트(segment) 상태의 IDirectMusicSegmentState8 인터페이스의 주소.
dwVariationFlags
연주되는 바리에이션 마다 설정된 비트에 대한 히트 마스크.
dwPart
바리에이션을 보관 유지하는 파트의 식별자. 이것은, 뮤직 오쏘링 어플리케이션으로 파트에 할당할 수 있었던 번호이며,P 채널에 동일하다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_POINTER

주의

바리에이션은, 한 번에 1 개의 파트에만 설정할 수 있다. 이 메소드가 불려 갈 때마다, 전의 호출이 덧쓰기된다.

다음의 샘플 코드는, 퍼포먼스 채널 1 으로 바리에이션 16 으로 바리에이션 32 를 연주한다.

// pPattern 는 IDirectMusicPatternTrack8 포인터이다.
// pSegmentState 는 IDirectMusicSegmentState8 포인터이다.

#define VARIATION(v)  (1 << ((v) - 1))

HRESULT hr = pPattern->SetVariation(
    pSegmentState, VARIATION(32) | VARIATION(16), 1);

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8

IDirectMusicPerformance8 인터페이스는, 음악 연주 전체의 매니저이다. 이 인터페이스는, 포토의 추가와 삭제, 퍼포먼스 채널의 포토에의 매핑, 세그먼트(segment)의 연주, 툴에 의한 메세지의 발신과 루팅, 이벤트 통지의 요구라고 받아들여, 및 뮤직 파라미터의 설정과 취득에 사용된다. 또, 타이밍에 관한 정보의 취득, 및 시스템간에 타임과 뮤직값을 변환하기 위한 메소드도 갖추고 있다.

어플리케이션이 2 개의 완전한 뮤직 세트를 동시에 연주하고 싶은 경우, 복수의 퍼포먼스를 생성 하는 것으로써, 그러한 연주를 실시할 수 있다. 개별의 퍼포먼스는 독립한 템포 맵에 따라, 완전하게 비동기에게 연주되지만, 한편으로 1 개의 퍼포먼스내의 모든 세그먼트(segment)는 고정적인 스텝에서 연주된다.

IDirectMusicPerformance8 는,IDirectMusicPerformance 인터페이스를 계승해, 새로운 메소드를 추가한다.

IDirectMusicPerformance8 의 메소드는, 이하의 그룹에 정리할 수가 있다.

오디오 패스 | CreateAudioPath
 | CreateStandardAudioPath
 | GetDefaultAudioPath
 | SetDefaultAudioPath
채널 | AssignPChannel
 | AssignPChannelBlock
 | PChannelInfo
음색 | DownloadInstrument
메세지 | AllocPMsg
 | ClonePMsg
 | FreePMsg
 | SendPMsg
MIDI 변환 | MIDIToMusic
 | MusicToMIDI
통지 | AddNotificationType
 | GetNotificationPMsg
 | RemoveNotificationType
 | SetNotificationHandle
파라미터 | GetGlobalParam
 | GetParam
 | GetParamEx
 | SetGlobalParam
 | SetParam
재생 | GetSegmentState
 | IsPlaying
 | PlaySegment
 | PlaySegmentEx
 | Stop
 | StopEx
포토 | AddPort
 | RemovePort
타이밍 | AdjustTime
 | GetBumperLength
 | GetLatencyTime
 | GetPrepareTime
 | GetQueueTime
 | GetResolvedTime
 | GetTime
 | MusicToReferenceTime
 | ReferenceToMusicTime
 | RhythmToTime
 | SetBumperLength
 | SetPrepareTime
 | TimeToRhythm
툴 | GetGraph
 | SetGraph
그 외 | CloseDown
 | Init
 | InitAudio
 | Invalidate

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::AddNotificationType

퍼포먼스에 통지 타입을 추가한다. AddNotificationType 메소드를 호출하면, 모든 세그먼트(segment)와 트럭은 새로운 통지에 의해 자동적으로 갱신된다.

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
추가되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). 정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것. 어플리케이션은, 커스텀 트랙에 도착해 독자적인 타입을 정의할 수 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_OUTOFMEMORY
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::RemoveNotificationType ,IDirectMusicSegment8::AddNotificationType ,IDirectMusicTrack8::AddNotificationType ,통지와 이벤트의 처리


IDirectMusicPerformance8::AddPort

퍼포먼스에 포토를 할당한다. 이 메소드는, 오디오 패스를 사용하지 않는 퍼포먼스 에 대해서만 유효하다. 즉, 퍼포먼스는 IDirectMusicPerformance8::Init 를 사용해 초기화된다.

HRESULT AddPort(
  IDirectMusicPort* pPort
);

파라미터

pPort
추가하는 포토를 포함한 변수의 주소. NULL 의 경우는 디폴트 포토가 추가된다. 「주의」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_CANNOT_OPEN_PORT
E_OUTOFMEMORY
E_POINTER

주의

pPort 에 NULL 를 건네주어 디폴트 포토가 지정되었을 경우, 이 디폴트 포토에는 1 개의 채널 그룹을 할당할 수 있다. 그 외의 포토에 대해 퍼포먼스 채널이 설정되어 있지 않은 경우, 0 ~ 15 의 채널이, 0 ~ 15 의 MIDI 채널에 할당할 수 있다.

pPort 가 NULL 가 아닌 경우, 포토는 그 포토가 건네받은 것과 같은 DirectMusic 오브젝트에 의해 생성 되는지, 또는 IDirectMusicPerformance8::Init 에 의해 생성 될 필요가 있다. IDirectMusicPort8::Activate 를 호출해 포토를 액티브하게 해,IDirectMusicPerformance8::AssignPChannelBlock 를 호출해 채널 블록을 할당하지 않으면 안 된다.

이 메소드는,IDirectMusicPort8 에의 참조를 생성 한다. 이 참조는,IDirectMusicPerformance8::RemovePort 또는 IDirectMusicPerformance8::CloseDown 에 의해 해방된다. 다만,AddPort 에 NULL 가 건네받는 경우, 어플리케이션에는 RemovePort 에 건네주는 참조가 없기 때문에,RemovePort 로 포토를 삭제할 수 없다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::RemovePort ,디폴트 포토


IDirectMusicPerformance8::AdjustTime

퍼포먼스의 내부 시간을 전방 또는 후방에 조정한다. 이 메소드는 대부분의 경우, 다른 소스와의 동기화를 실시할 때에 차이를 보정하기 위해서 사용된다.

HRESULT AdjustTime(
  REFERENCE_TIME rtAmount
);

파라미터

rtAmount
가산 또는 감산되는 시간. －10,000,000 에서 10,000,000 (－1 초부터 +1 초)의 수치를 지정한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_INVALIDARG 를 돌려준다.

주의

조정된 시간은, DirectMusic 에 의해 내부적으로 사용된다. IDirectMusicPerformance8::GetTime 메소드로 취득되는 시간에는 반영되지 않는다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetTime ,타이밍


IDirectMusicPerformance8::AllocPMsg

퍼포먼스 메세지를 할당한다.

HRESULT AllocPMsg(
  ULONG cb,
  DMUS_PMSG** ppPMSG
);

파라미터

cb
메세지 구조체의 사이즈. 이 구조체는,DMUS_PMSG 의 파생 타입이다.
ppPMSG
할당할 수 있었던 메세지 구조체에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

메세지 구조체의 dwSize 멤버는,cb 의 값으로 설정된다. 내부 캐싱이기 때문에, 다른 멤버를 0 에 초기화할 필요는 없다.

메세지가 IDirectMusicPerformance8::SendPMsg 에 의해 송신된 후는, 어플리케이션은 메모리를 확보하지 않고, 메세지의 해방도 실시하지 않는다. 다만, 툴은, 그 IDirectMusicTool8::Flush 메소드 또는 IDirectMusicTool8::ProcessPMsg 메소드내에서 메세지를 해방할 수 있다. 어플리케이션은, 통지 메세지의 해방도 실시한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::FreePMsg ,IDirectMusicPerformance8::SendPMsg ,DirectMusic 메세지


IDirectMusicPerformance8::AssignPChannel

1 개의 퍼포먼스 채널을 퍼포먼스에 할당해 이 채널을 포토, 그룹, MIDI 채널에 맵 한다.

오디오 패스를 통해 데이터를 건네주는 어플리케이션에서는, 이 메소드는 사용되지 않는다.

HRESULT AssignPChannel(
  DWORD dwPChannel,
  IDirectMusicPort* pPort,
  DWORD dwGroup,
  DWORD dwMChannel
);

파라미터

dwPChannel
할당하는 퍼포먼스 채널.
pPort
채널의 할당처의 포토를 포함한 변수의 주소.
dwGroup
포토 위에의 채널 그룹.
dwMChannel
그룹내의 채널. 0 ~ 15 의 범위가 아니면 안된다.

반환값

성공했을 경우는 S_OK 또는 S_FALSE 를 돌려준다 ( 「주의」를 참조할것).

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

주의

dwGroup 가 포토의 범위외의 경우, 이 메소드는 S_FALSE 를 돌려준다. 채널은 할당할 수 있지만, 포토는 그 그룹을 연주할 수 없다.

dwMChannel 가 범위외, 또는 IDirectMusicPerformance8::AddPort 메소드를 호출해 포토를 퍼포먼스에 추가하는 작업을 실시하지 않은 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::AssignPChannelBlock ,IDirectMusicPerformance8::PChannelInfo ,채널


IDirectMusicPerformance8::AssignPChannelBlock

16 의 퍼포먼스 채널로부터 완성되는 블록을 퍼포먼스에 할당해 그것들을 포토와 채널 그룹에 맵 한다. 이 메소드는, 오디오 패스를 사용하지 않는 퍼포먼스 에 대해서만 유효하다. 즉, 퍼포먼스는 IDirectMusicPerformance8::Init 를 사용해 초기화된다.

HRESULT AssignPChannelBlock(
  DWORD dwBlockNum,
  IDirectMusicPort* pPort,
  DWORD dwGroup
);

파라미터

dwBlockNum
블록 번호. 0 은 채널 0 ~ 15, 1 은 채널 16 ~ 31 을 나타낸다. 이하 같이이다.
pPort
채널의 할당처의 포토를 포함한 변수의 주소.
dwGroup
포토 위에의 채널 그룹. 1 이상의 값이 아니면 안된다.

반환값

성공했을 경우는 S_OK 또는 S_FALSE 를 돌려준다 ( 「주의」를 참조할것).

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

주의

포토가 퍼포먼스에 추가되었을 때에, 이 메소드를 호출할 필요가 있다. 다만,IDirectMusicPerformance8::AddPort 에 NULL 를 건네주는 것으로디폴트 포토가 추가되었을 경우를 제외하다.

dwGroup 가 포토의 범위외의 경우, 이 메소드는 S_FALSE 를 돌려준다. 채널은 할당할 수 있지만, 포토는 그 그룹을 연주할 수 없다.

dwMChannel 가 범위외, 또는 IDirectMusicPerformance8::AddPort 메소드를 호출해 포토를 퍼포먼스에 추가하는 작업을 실시하지 않은 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::AssignPChannel ,IDirectMusicPerformance8::PChannelInfo ,채널


IDirectMusicPerformance8::ClonePMsg

퍼포먼스 메세지의 카피를 생성 한다.

HRESULT ClonePMsg(
  DMUS_PMSG* pSourcePMSG,
  DMUS_PMSG** ppCopyPMSG
);

파라미터

pSourcePMSG
카피하는 메세지.
ppCopyPMSG
카피하는 메세지에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_OUTOFMEMORY
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::CloseDown

퍼포먼스 오브젝트를 닫는다. 퍼포먼스 오브젝트를 생성 해, 그 오브젝트에 대해서 IDirectMusicPerformance8::Init 또는 IDirectMusicPerformance8::InitAudio 를 호출한 어플리케이션은, 퍼포먼스를 해방하기 전에 CloseDown 를 호출하지 않으면 안 된다.

HRESULT CloseDown();

파라미터

없음.

반환값

S_OK 를 돌려준다.

주의

CloseDown 의 호출을 잊으면(자), 메모리 누수나 프로그램 장해가 발생하는 일이 있다.

IDirectMusicPerformance8::Init 또는 IDirectMusicPerformance8::InitAudio 에 의해 IDirectMusic8 인터페이스의 참조가 생성 되었을 경우,CloseDown 가 그 해방을 처리한다. 어플리케이션이 DirectMusic 오브젝트를 명시적으로 생성 했을 경우는, 그 어플리케이션이 참조의 해방을 실시할 필요가 있다.

DirectSound 오브젝트가 Init 또는 InitAudio 의 호출로 생성 되어 어플리케이션에 참조가 돌려주어지지 않았던 경우,CloseDown 는 DirectSound 및 모든 DirectSound 버퍼도 해방한다. 어플리케이션으로 DirectSound 버퍼에의 인터페이스를 취득했을 경우는, 그것들을 해방하고 나서 Closedown 를 호출한다.

어플리케이션이 DirectSound 를 명시적으로 생성, 또는 Init 혹은 InitAudio 로부터 참조를 취득했을 경우, DirectSound 를 해방할 필요가 있다.

이 메소드는, 다운로드해 아직 언로드하고 있지 않는 음색을 해방한다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::CreateAudioPath

퍼포먼스로부터 DirectSound 버퍼에의 데이터 플로우내의 각 스테이지를 나타내는, 오디오 패스 오브젝트를 생성 한다.

HRESULT CreateAudioPath(
  IUnknown *pSourceConfig,
  BOOL fActivate,
  IDirectMusicAudioPath **ppNewPath
);

파라미터

pSourceConfig
오디오 패스 구성을 나타내는 인터페이스의 주소. 「주의」를 참조할것.
fActivate
생성시에 패스를 액티브하게 할지 어떨지를 지정하는 불형의 값.
ppNewPath
오디오 패스의 IDirectMusicAudioPath8 인터페이스 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_NOINTERFACE
E_POINTER
DMUS_E_NOT_INIT
DMUS_E_AUDIOPATHS_NOT_VALID
DSERR_BUFFERLOST
E_OUTOFMEMORY

주의

pSourceConfig 가 주소 하는 오브젝트는,IDirectMusicSegment8::GetAudioPathConfig 메소드를 사용해 세그먼트(segment)로부터 취득하는지, 파일로부터 직접 로드할 수가 있다.

DirectSound 가 무엇인가의 어플리케이션에 의해 기입 우선 협조 레벨로 초기화되고 있으면(자), 이 메소드는 실패해 DSERR_BUFFERLOST 를 돌려준다.

이용할 수 없는 사운드 디바이스가 오디오 패스 구성으로 지정되고 있으면(자), 이 메소드는 E_NOINTERFACE 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

오디오 패스의 생성


IDirectMusicPerformance8::CreateStandardAudioPath

퍼포먼스로부터 DirectSound 버퍼에의 데이터 플로우내의 각 스테이지를 나타내는, 오브젝트를 생성 한다. 이 메소드를 사용 하면,IDirectMusicPerformance8::CreateAudioPath 로 원시 파일에 정의된 오디오 패스를 생성 하는 대신에, 기본적인 사전 정의 오디오 패스를 생성 할 수가 있다.

HRESULT  CreateStandardAudioPath(
  DWORD dwType,
  DWORD dwPChannelCount,
  BOOL  fActivate,
  IDirectMusicAudioPath **ppNewPath
);

파라미터

dwType
패스의 타입. 다음의 값이 정의되고 있다.
DMUS_APATH_DYNAMIC_3D
3D 버퍼에 대한 1 개의 버스. 환경 리바브에는 보내지 않는다.
DMUS_APATH_DYNAMIC_MONO
단청의 버퍼에 대한 1 개의 버스.
DMUS_APATH_SHARED_STEREOPLUSREVERB
스테레오 출력과 리바브를 갖춘, 보통의 뮤직 셋업.
DMUS_APATH_DYNAMIC_STEREO
스테레오 버퍼에 대한 2 개의 버스.

이러한 오디오 패스의 상세한 것에 대하여는, 「표준 오디오 패스」를 참조할것.

dwPChannelCount
패스내의 퍼포먼스 채널의 수.
fActivate
생성시에 패스를 액티브하게 할지 어떨지를 지정하는 불형의 값.
ppNewPath
오디오 패스의 IDirectMusicAudioPath 인터페이스 포인터를 받는 변수의 주소. 「IDirectMusicAudioPath8 」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
DMUS_E_NOT_INIT
DMUS_E_AUDIOPATHS_NOT_VALID
DSERR_BUFFERLOST
E_INVALIDARG
E_OUTOFMEMORY

주의

DirectSound 가 무엇인가의 어플리케이션에 의해 기입 우선 협조 레벨로 초기화되고 있으면(자), 이 메소드는 실패해 DSERR_BUFFERLOST 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::DownloadInstrument

음색에 대응하는 DLS 데이터를 포토에 다운로드한다.

HRESULT DownloadInstrument(
  IDirectMusicInstrument* pInst,
  DWORD dwPChannel,
  IDirectMusicDownloadedInstrument** ppDownInst,
  DMUS_NOTERANGE* pNoteRanges,
  DWORD dwNumNoteRanges,
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

파라미터

pInst
다운로드하는 음색의 IDirectMusicInstrument8 인터페이스에의 포인터.
dwPChannel
음색의 할당처의 퍼포먼스 채널.
ppDownInst
다운로드된 음색에의 IDirectMusicDownloadedInstrument8 인터페이스 포인터를 받는 변수의 주소.
pNoteRanges
DMUS_NOTERANGE 구조체의 배열의 주소. 배열내의 각 엔트리는, 음색이 응답해야 하는 MIDI 노트 메세지의 연속 범위를 지정한다. 음색의리젼이 다운로드되는 것은, 그 리젼내의 적어도 1 개의 노트가 DMUS_NOTERANGE 구조체로 지정되고 있는 경우에 한정된다.
dwNumNoteRanges
pNoteRanges 가 가리키는 배열내의 DMUS_NOTERANGE 구조체의 수. 이 값이 0 으로 설정되어 있는 경우,pNoteRanges 파라미터는 무시되어 이 음색의 모든 리젼과 웨이브 데이터가 다운로드된다.
ppPort
음색의 다운로드처의 포토에의 포인터를 받는 변수의 주소.
pdwGroup
음색의 할당처의 그룹을 받는 변수의 주소.
pdwMChannel
음색의 할당처의 MIDI 채널을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

주의

음색의 다운로드는 보통, 밴드에 의해 처리되기 (위해)때문에, 대부분의 어플리케이션에서는 이 메소드를 사용할 필요가 없다. 「밴드의 다운로드와 언로드」를 참조할것.

퍼포먼스 채널을 포토에 할당할 수 있지 않은 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.

리소스의 낭비를 막으려면 , 음색이 불필요하게 되었을 때에,IDirectMusicPort8::UnloadInstrument 메소드를 사용해 언로드한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPort8::DownloadInstrument ,IDirectMusicPort8::UnloadInstrument ,음색의 조작


IDirectMusicPerformance8::FreePMsg

메세지를 해방한다.

HRESULT FreePMsg(
  DMUS_PMSG* pPMSG
);

파라미터

pPMSG
해방하는 메세지를 포함한 변수의 주소. 이 메세지는,IDirectMusicPerformance8::AllocPMsg 메소드를 사용해 할당해 둘 필요가 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_CANNOT_FREE
E_POINTER

주의

대부분의 메세지는, 처리되면(자), 퍼포먼스에 의해 자동적으로 해방된다. 또,IDirectMusicPerformance8::SendPMsg 를 사용해 송신된 메세지에 대해서,IDirectMusicPerformance8::FreePMsg 을 호출해서는 안 된다. 다만,IDirectMusicPerformance8::FreePMsg 는,IDirectMusicTool8::ProcessPMsg 또는 IDirectMusicTool8::Flush 중(안)에서 사용하면(자), 불필요한 메세지를 해방할 수가 있다. 통지 메세지를 해방할 때에도,IDirectMusicPerformance::FreePMsg 를 사용해야 한다.

이 메소드는, 이하의 경우에 DMUS_E_CANNOT_FREE 를 돌려준다.

  • pPMSG 가,AllocPMsg 를 사용해 할당한 메세지를 나타내지 않은 경우.
  • IDirectMusicPerformance8::SendPMsg 를 호출했기 때문에 pPMSG 가 현재 퍼포먼스 큐에 놓여져 있는 경우. 다만,SendPMsg 는 동기되어 있지 않기 때문에, 어플리케이션은 FreePMsg 가 모든 송신된 메세지에 대해서 DMUS_E_CANNOT_FREE 를 돌려주는 것이라고 볼 수가 없게 된다.
  • pPMSG 가 이미 해방되고 있는 경우.

pTool,pGraph,punkUser 의 몇개의 멤버 ( 「DMUS_PMSG 」를 참조) 내에 값이 존재하는 경우, 참조되고 있는 각 오브젝트는 해방된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::AllocPMsg ,DirectMusic 메세지


IDirectMusicPerformance8::GetBumperLength

메세지가 포토 버퍼에 놓여진 타임과 포토가 메세지의 처리를 시작 하는 타임의 사이의 시간을 취득한다. 이 주제의 개요에 대해서는, 「타이밍」을 참조할것.

HRESULT GetBumperLength(
  DWORD* pdwMilliSeconds
);

파라미터

pdwMilliSeconds
연주전의 시간의 길이가 들어가는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

디폴트의 값은 50 밀리 세컨드 (ms)이다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SetBumperLength


IDirectMusicPerformance8::GetDefaultAudioPath

IDirectMusicPerformance8::InitAudio 또는 IDirectMusicPerformance8::SetDefaultAudioPath 로 설정된, 디폴트의 오디오 패스를 취득한다.

HRESULT GetDefaultAudioPath(
  IDirectMusicAudioPath **ppAudioPath
);

파라미터

ppAudioPath
디폴트 오디오 패스의 IDirectMusicAudioPath8 인터페이스 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
DMUS_E_AUDIOPATHS_NOT_VALID
DMUS_E_NOT_INIT

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::GetGlobalParam

퍼포먼스로부터 글로벌값을 취득한다.

HRESULT GetGlobalParam(
  REFGUID rguidType,
  void* pParam,
  DWORD dwSize
);

파라미터

rguidType
데이터형의 식별자에의 참조 (C++) 또는 주소 (C).
pParam
데이터의 카피를 받기 위해서(때문에) 할당할 수 있었던 메모리에의 포인터. pParam 에는 올바른 사이즈를 지정해야 한다. 사이즈는 각 데이터형에 대해 일정한다. 이 파라미터는,IDirectMusicPerformance8::SetGlobalParam 메소드에게 건네진 정보를 보관 유지한다.
dwSize
데이터의 사이즈. rguidType 마다 일정한 값이다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

주의

SetGlobalParam 가 rguidType 에 대해 한번도 불려 갔던 적이 없는 경우, 이 퍼포먼스가 현재 처리하고 있는 글로벌 데이터 리스트안에,rguidType 가 없을 가능성이 있다. 그 경우, 이 메소드는 E_INVALIDARG 를 돌려준다. 즉, 어느 파라미터에도,GetGlobalParam 를 사용해 취득할 수 있는 디폴트값이 있으면(자) 상정하지 않는 것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SetGlobalParam ,IDirectMusicPerformance8::GetParam ,퍼포먼스 파라미터


IDirectMusicPerformance8::GetGraph

퍼포먼스의 툴 그래프를 취득한다.

HRESULT GetGraph(
  IDirectMusicGraph** ppGraph
);

파라미터

ppGraph
툴 그래프에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

그래프의 참조 카운트는 인크리먼트(increment) 된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SetGraph ,IDirectMusicSegment8::GetGraph ,IDirectMusicPerformance8::SendPMsg


IDirectMusicPerformance8::GetLatencyTime

현재의 지연 시간을 취득한다. 지연 시간은, 스피커로부터 음악이 들리고 있는 시간에, 메세지를 큐에 넣어 IDirectMusicPort8 에 렌더링하기 위한 소요 시간을 더한 길이가 된다. 이 주제의 개요에 대해서는, 「타이밍」을 참조할것.

HRESULT GetLatencyTime(
  REFERENCE_TIME * prtTime
);

파라미터

prtTime
현재의 지연 시간을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
DMUS_E_NO_MASTER_CLOCK

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::GetNotificationPMsg

보류중의 통지 메세지를 취득한다.

HRESULT GetNotificationPMsg(
  DMUS_NOTIFICATION_PMSG** ppNotificationPMsg
);

파라미터

ppNotificationPMsg
DMUS_NOTIFICATION_PMSG 구조체에의 포인터를 받는 변수의 주소. 이 메세지를 취득하는 어플리케이션은, 그 메세지에 대해서 IDirectMusicPerformance8::FreePMsg 를 호출할 책임이 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 돌려주어지는 통지 이벤트가 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리


IDirectMusicPerformance8::GetParam

제어 세그먼트(segment)내의 트럭으로부터 데이터를 취득한다.

HRESULT GetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

파라미터

rguidType
취득되는 데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
dwGroupBits
데이터의 취득에 사용되는 트럭의 그룹 ( 「주의」를 참조할것). 모든 그룹을 지정하려면 , 이 값을 0xFFFFFFFF 로 설정한다.
dwIndex
데이터의 취득에 사용되는 그룹내에서, 트럭에 할당할 수 있고 있는 인덱스.
mtTime
데이터를 취득하는 타임. 퍼포먼스 시간에 지정한다.
pmtNext
데이터가 유효하게 되는 타임 (mtTime 로부터의 상대 타임)을 받는 변수의 주소. 이 변수가 값 0 을 돌려주었을 경우, 데이터가 항상 유효하게 되어 있는지, 데이터가 무효가 되는 타임이 불명한 것을 의미한다. 이 정보가 불필요한 경우는,pmtNext 를 NULL 로 설정해도 괜찮다. 「주의」를 참조할것.
pParam
돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 이 구조체는,rguidType 로 식별된 데이터형에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_GET_UNSUPPORTED
DMUS_E_NO_MASTER_CLOCK
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND
E_POINTER

주의

보통, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. 다만, 세칸다리세그먼트를 연주 하면나무는, 이것을 제어 세그먼트(segment)로서 지정할 수 있다. 상세한 것에 대하여는, 「제어 세그먼트(segment)」를 참조할것.

다른 제어 세그먼트(segment)가 삽입되는 경우,*pParam 로 돌려주어지는 데이터는,*pmtNext 로 돌려주어지는 타임의 전에 무효가 되는 일이 있다.

각 트럭은 1 개 또는 복수의 그룹에 소속하지만, 각 그룹은 dwGroupBits 내의 비트에 의해 나타내지고 있다. 상세한 것에 대하여는, 「IDirectMusicSegment8::InsertTrack 」 및 「트럭의 식별」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicPerformance8::SetGlobalParam ,IDirectMusicPerformance8::GetTime ,IDirectMusicPerformance8::GetParamEx ,퍼포먼스 파라미터


IDirectMusicPerformance8::GetParamEx

트럭으로부터 데이터를 취득한다. 이 메소드는,IDirectMusicPerformance8::GetParam 에 유사하고 있지만, 자기 제어 세그먼트(segment)의 지원을 추가한다. 주로 툴로 사용된다.

HRESULT GetParamEx(
  REFGUID rguidType,
  DWORD dwTrackID,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

파라미터

rguidType
취득되는 데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
dwTrackID
파라미터의 취득에 사용되는 세그먼트(segment) 상태내의 트럭의 일의인 식별자. 트럭으로부터 취득되는 각 퍼포먼스 메세지에는, 메세지를 생성한 트럭 인스턴스의 식별자가 붙어 있다. 이 식별자는, 메세지 구조체의 DMUS_PMSG 부분의 dwVirtualTrackID 멤버에 보관 유지된다. 이 값이 GetParamEx 에게 건네지면(자),제어 세그먼트(segment)는 아닌 같은 세그먼트(segment)내의 다른 트럭으로부터 데이터를 취득했을 경우에, 이 트럭이 자기 제어하고 있을지 어떨지를 판단할 수 있다.
dwGroupBits
트럭이 속하는 그룹 ( 「주의」를 참조할것). 모든 그룹을 지정하려면 , 이 값을 0xFFFFFFFF 로 설정한다.
dwIndex
그룹내의 트럭의 인덱스.
mtTime
데이터를 취득하는 타임. 퍼포먼스 시간에 지정한다.
pmtNext
데이터가 유효하게 되는 타임 (mtTime 로부터의 상대 타임)을 받는 변수의 주소. 이 변수가 값 0 을 돌려주었을 경우, 데이터가 항상 유효하게 되어 있는지, 데이터가 무효가 되는 타임이 불명한 것을 의미한다. 이 정보가 불필요한 경우는,pmtNext 를 NULL 로 설정해도 괜찮다. 「주의」를 참조할것.
pParam
돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 이 구조체는,rguidType 로 식별된 데이터형에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_GET_UNSUPPORTED
DMUS_E_NO_MASTER_CLOCK
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND
E_POINTER

주의

각 트럭은 1 개 또는 복수의 그룹에 소속하지만, 각 그룹은 dwGroupBits 내의 비트에 의해 나타내지고 있다. 상세한 것에 대하여는, 「IDirectMusicSegment8::InsertTrack 」 및 「트럭의 식별」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicPerformance8::SetGlobalParam ,IDirectMusicPerformance8::GetTime ,퍼포먼스 파라미터


IDirectMusicPerformance8::GetPrepareTime

트럭에 의해 메세지가 송신되고 나서 사운드가 들릴 때까지의 간격을 취득한다. 이전 격은, 툴이 메세지를 처리하는데 충분한 시간이 아니면 안된다.

HRESULT GetPrepareTime(
  DWORD* pdwMilliSeconds
);

파라미터

pdwMilliSeconds
준비 시간을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

디폴트의 값은 1,000 밀리 세컨드 (ms)이다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SetPrepareTime ,준비 시간


IDirectMusicPerformance8::GetQueueTime

현재의 플래시 타임을 취득한다. 플래시 타임이란, 큐내의 메세지를 플래시 (해방) 할 수 있는 가장 빠른 타임이다. 이 타임보다 빠른 타임 스탬프를 가지는 메세지는, 이미 포토에 송신되고 있어 무효로 할 수 없다.

HRESULT GetQueueTime(
  REFERENCE_TIME * prtTime
);

파라미터

prtTime
현재의 플래시 타임을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
DMUS_E_NO_MASTER_CLOCK

동작환경

헤더 : dmusici.h 로 선언.

참조

지연 시간과 범퍼 시간


IDirectMusicPerformance8::GetResolvedTime

지정된 타임을, 지정된 경계에 조정한다.

HRESULT GetResolvedTime(
  REFERENCE_TIME rtTime,
  REFERENCE_TIME* prtResolved,
  DWORD dwTimeResolveFlags
);

파라미터

rtTime
경계에 조정해야 할 타임. 이 타임이 현재 타임보다 빠른 경우는, 현재 타임이 사용된다.
prtResolved
해결 지음의 타임을 받는 변수의 주소.
dwTimeResolveFlags
목적의 분해가능을 기술하는 1 개(살) 또는 복수의 DMUS_TIME_RESOLVE_FLAGS .

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

타이밍


IDirectMusicPerformance8::GetSegmentState

현재 연주중의 프라이머리 세그먼트(segment) 상태, 또는 특정의 시점에서 연주되고 있는 프라이머리 세그먼트(segment) 상태를 취득한다.

HRESULT GetSegmentState(
  IDirectMusicSegmentState ** ppSegmentState,
  MUSIC_TIME mtTime
);

파라미터

ppSegmentState
세그먼트(segment) 상태에의 포인터를 받는 변수의 주소. 호출원래는, 이 포인터에 대해서 Release 를 호출할 책임이 있다.
mtTime
세그먼트(segment) 상태가 취득되는 타임.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

현재 연주중의 세그먼트(segment) 상태를 취득하려면 ,IDirectMusicPerformance8::GetTime 메소드가 돌려주는 타임을 건네준다. 지연 시간이 존재하기 위해(때문에), 반드시 현재 연주되고 있는 세그먼트(segment) 상태가 현재 스피커로부터 실제로 들리고 있다고는 할 수 없다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::GetTime

퍼포먼스의 현재의 타임을 취득한다.

HRESULT GetTime(
  REFERENCE_TIME* prtNow,
  MUSIC_TIME* pmtNow
);

파라미터

prtNow
현재의 타임을 REFERENCE_TIME 포맷으로 받는 변수의 주소. NULL 이라도 좋다.
pmtNow
현재의 타임을 MUSIC_TIME 포맷으로 받는 변수의 주소. NULL 이라도 좋다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NO_MASTER_CLOCK
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

타이밍


IDirectMusicPerformance8::Init

퍼포먼스를 DirectMusic 오브젝트와 DirectSound 오브젝트에 관련짓는다. 어플리케이션이 오디오 패스를 사용하고 있지 않는 경우는, 퍼포먼스의 연주전에 이 메소드를 호출할 필요가 있다.

오디오 패스를 사용하는 어플리케이션에 대해서는, 이 메소드에 대신해 IDirectMusicPerformance8::InitAudio 가 사용된다.

HRESULT Init(
  IDirectMusic** ppDirectMusic,
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

파라미터

ppDirectMusic
DirectMusic 오브젝트에의 인터페이스 포인터를 지정 또는 받는 변수의 주소.

ppDirectMusic 가 가리키는 변수에, 유효한 IDirectMusic 또는 IDirectMusic8 인터페이스 포인터가 포함되어 있는 경우는, 기존의 오브젝트를 퍼포먼스에 할당할 수 있다. 이 인터페이스의 참조 카운트는 인크리먼트(increment) 된다. IDirectMusicPerformance8::AddPort 메소드에게 건네지는 포토는, 이 DirectMusic 오브젝트로부터 생성 할 필요가 있다.

ppDirectMusic 가 가리키는 변수에 NULL 가 포함되는 경우, DirectMusic 오브젝트가 생성 되어IDirectMusic 인터페이스 포인터가 돌려주어진다. QueryInterface 를 사용해 IDirectMusic8 를 취득한다.

ppDirectMusic 가 NULL 의 경우, DirectMusic 오브젝트가 생성 되어 퍼포먼스에 의해 내부적으로 사용된다.

「주의」를 참조할것.

pDirectSound
웨이브 출력의 디폴트로 사용되는 IDirectSound8 인터페이스 포인터. 이 값이 NULL 의 경우, DirectMusic 에 의해 DirectSound 오브젝트가 생성 된다. 다만, DirectSound 오브젝트를 존재할 수 있는 것은 1 개의 프로세스에 대해 1 개 뿐이다. 어플리케이션으로 DirectSound 를 개별적으로 사용하고 있는 경우, 그 인터페이스를 pDirectSound 에 건네주지 않으면 안 된다. 어플리케이션이 DirectMusic 오브젝트를 명시적으로 생성 하는 경우는, 그 인터페이스를 IDirectMusic8::SetDirectSound 에 건네주지 않으면 안 된다.
hWnd
DirectSound 의 생성에 사용하는 윈도우 핸들. 이 파라미터는 NULL 이라도 좋다. 그 경우, 전면 윈도우가 사용된다. 「주의」를 참조할것.

pDirectSound 가 NULL 의 경우, 이 파라미터는 무시된다. 그 경우,IDirectSound8::SetCooperativeLevel 의 호출에 대해, 어플리케이션이 윈도우 핸들의 설정을 실시하지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_ALREADY_INITED
E_OUTOFMEMORY
E_POINTER

주의

이 메소드는, 한 번만 호출할 수가 있다. 기존의 IDirectMusic8 인터페이스의 취득에 사용할 수 없다.

DirectMusic 오브젝트는, 이하의 방법의 어느쪽이든을 사용해, 퍼포먼스에 관련지을 수가 있다.

  • 어플리케이션이 독자적인 DirectMusic 오브젝트를 생성 해,IDirectMusic8 포인터의 주소를 ppDirectMusic 에 건네주는 것에 의해, 그 오브젝트를 퍼포먼스에 제공한다. 이 경우, 어플리케이션이 IDirectMusic8::SetDirectSound 를 호출할 필요가 있기 (위해)때문에,pDirectSound 와 hWnd 의 각 파라미터는 무시된다.
  • 어플리케이션이 퍼포먼스에 의한 DirectMusic 오브젝트의 생성을 허가해, 그 오브젝트에의 포인터를 필요로 한다. 이 경우, 엔트리시의 *ppDirectMusic 는 NULL 로, 종료시에는 IDirectMusic 포인터를 보관 유지한다.
  • 어플리케이션이 퍼포먼스에 의한 그것 자신의 초기화를 허가해, DirectMusic 오브젝트 포인터를 필요로 하지 않는다. 이 경우,ppDirectMusic 는 NULL 이다.

퍼포먼스를 해방하기 전에,IDirectMusicPerformance8::CloseDown 메소드를 사용해 퍼포먼스를 종료해야 한다.

hWnd 파라미터에 NULL 를 건네주면(자), 현재의 전면 윈도우의 핸들을 DirectSound 에 건네줄 수가 있다. 다만, 어플리케이션 윈도우가 초기화중에 전면에 있으면(자) 상정하지 않는 것. 최상정도 어플리케이션의 윈도우 핸들을 건네주는 것이 최선이다.

동작환경

헤더 : dmusici.h 로 선언.

참조

포토로부터 오디오 패스에의 이행


IDirectMusicPerformance8::InitAudio

퍼포먼스를 초기화해, 옵션으로 디폴트의 오디오 패스를 셋업 한다. 이 메소드는, 오디오 패스를 사용해 퍼포먼스를 연주하기 전에, 호출할 필요가 있다.

대부분의 경우,IDirectMusicPerformance8::Init 는 아니고, 이 메소드를 사용하는 것이 바람직하다.

HRESULT InitAudio(
  IDirectMusic** ppDirectMusic,
  IDirectSound** ppDirectSound,
  HWND hWnd,
  DWORD dwDefaultPathType,
  DWORD dwPChannelCount,
  DWORD dwFlags,
  DMUS_AUDIOPARAMS *pParams
);

파라미터

ppDirectMusic
DirectMusic 오브젝트에의 인터페이스 포인터를 지정 또는 받는 변수의 주소.

ppDirectMusic 가 가리키는 변수에, 유효한 IDirectMusic 또는 IDirectMusic8 인터페이스 포인터가 포함되어 있는 경우는, 기존의 오브젝트를 퍼포먼스에 할당할 수 있다. 이 인터페이스의 참조 카운트는 인크리먼트(increment) 된다.

ppDirectMusic 가 가리키는 변수에 NULL 가 포함되는 경우, DirectMusic 오브젝트가 생성 되어IDirectMusic 인터페이스 포인터가 돌려주어진다. QueryInterface 를 사용해 IDirectMusic8 를 취득한다.

ppDirectMusic 가 NULL 의 경우, DirectMusic 오브젝트가 생성 되어 퍼포먼스에 의해 내부적으로 사용된다.

「주의」를 참조할것.

ppDirectSound
웨이브 출력의 디폴트로 사용하는 DirectSound 오브젝트의,IDirectSound 인터페이스 포인터를 지정 또는 취득하는 변수의 주소. 이 파라미터에 NULL 포인터가 포함되는 경우, DirectMusic 에 의해 전용의 DirectSound 오브젝트가 생성 된다. 나타난 변수에 NULL 가 포함되는 경우, DirectMusic 오브젝트가 DirectSound 오브젝트를 생성 해, 그 인터페이스 포인터가 돌려주어진다. 「주의」를 참조할것.
hWnd
DirectSound 의 생성에 사용하는 윈도우 핸들. 이 파라미터는 NULL 이라도 좋다. 그 경우, 전면 윈도우가 사용된다. 「주의」를 참조할것.

IDirectSound 인터페이스 포인터가 ppDirectSound 의 메소드에게 건네지는 경우, 이 파라미터는 무시된다. 그 경우, 어플리케이션은,IDirectSound8::SetCooperativeLevel 를 사용해 윈도우 핸들을 설정할 책임이 있다.

dwDefaultPathType
디폴트의 오디오파스타이프를 지정하는 DWORD 값. 데포르트파스타이프가 불필요한 경우는, 0 을 지정한다. 정의된 값의 리스트에 대해서는, 「IDirectMusicPerformance8::CreateStandardAudioPath 」를 참조할것.
dwPChannelCount
dwDefaultPathType 가 0 이외인 경우, 패스에 할당하는 퍼포먼스 채널수를 지정하는 값.
dwFlags
요구된 기능을 지정하는 플래그. pParams 가 NULL 이외인 경우, 이 값은 무시되어 요구된 기능은,DMUS_AUDIOPARAMS 구조체의 dwFeatures 멤버로 지정된다. 이 파라미터로 사용할 수 있는 값으로서 다음의 값이 정의되고 있다.
DMUS_AUDIOF_3D
3D 버퍼.
DMUS_AUDIOF_ALL
모든 기능.
DMUS_AUDIOF_BUFFERS
복수의 버퍼.
DMUS_AUDIOF_ENVIRON
환경 모델링.
DMUS_AUDIOF_EAX
EAX 이펙트.
DMUS_AUDIOF_STREAMING
스트리밍 웨이브의 지원.
pParams
신디사이저의 파라미터를 지정해, 어느 파라미터가 설정되었는지를 붙은 정보를 받는 DMUS_AUDIOPARAMS 구조체의 주소. 디폴트의 파라미터를 사용하는 경우는, NULL 이라도 좋다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_ALREADY_INITED
DSERR_BUFFERLOST
DSERR_PRIOLEVELNEEDED
DSERR_UNINITIALIZED
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

주의

이 메소드는, 한 번만 호출할 수가 있다. 기존의 IDirectMusic8 인터페이스의 취득에 사용할 수 없다.

DirectMusic 오브젝트는, 이하의 방법으로, 퍼포먼스에 관련지을 수가 있다.

  • 어플리케이션이 퍼포먼스에 의한 DirectMusic 오브젝트의 생성을 허가해, 그 오브젝트에의 포인터를 필요로 한다. 이 경우,*ppDirectMusic 은 엔트리시에 NULL 로, 종료시에는 IDirectMusic8 포인터를 보관 유지한다.
  • 어플리케이션이 퍼포먼스에 의한 그것 자신의 초기화를 허가해, DirectMusic 오브젝트 포인터를 필요로 하지 않는다. 이 경우,ppDirectMusic 는 NULL 이다.
  • 어플리케이션이 독자적인 DirectMusic 오브젝트를 생성 해,IDirectMusic8 포인터의 주소를 ppDirectMusic 에 건네주는 것에 의해, 그 오브젝트를 퍼포먼스에 제공한다. 대부분의 어플리케이션에서는, 이 방법은 사용되지 않는다.

ppDirectSound 로 지정하는 인터페이스 포인터는, CLSID_DirectSound8 클래스의 오브젝트에의 인터페이스를 가리키지 않으면 안 된다. 이 클래스의 오브젝트는,IDirectSound 와 IDirectSound8 의 양쪽 모두를 지원 하고 있지만,IDirectSound 인터페이스를 건네줄 필요가 있다. 이 클래스의 오브젝트의 생성 방법에 대해서는, 「IDirectSound8 」의 「주의」를 참조할것. DirectSound 오브젝트는,InitAudio 에 건네주기 전에 완전하게 초기화할 필요가 있다. 그것이 CoCreateInstance 를 사용해 생성 된 오브젝트인 경우는,IDirectSound8::Initialize 를 호출한다. IDirectSound8::SetCooperativeLevel 를 사용해, 협조 레벨을 DSSCL_PRIORITY 로 설정한다.

hWnd 파라미터에 NULL 를 건네주면(자), 현재의 전면 윈도우의 핸들을 DirectSound 에 건네줄 수가 있다. 다만, 어플리케이션 윈도우가 초기화중에 전면에 있으면(자) 상정하지 않는 것. 최상정도 어플리케이션의 윈도우 핸들을 건네주는 것이 최선이다.

dwFlags 및 pParams 로 설정된 파라미터는, 디폴트의 오디오 패스, 및 그 후 생성 된 모든 오디오 패스에 적용된다.

dwDefaultPathType 로 0 이외의 값이 건네받았을 경우, 무엇인가의 어플리케이션에 의해 DirectSound 가 기입해 우선 협조 레벨로 초기화되고 있으면(자), 이 메소드는 실패해 DSERR_BUFFERLOST 를 돌려준다.

퍼포먼스를 해방하기 전에,IDirectMusicPerformance8::CloseDown 메소드를 사용해 퍼포먼스를 종료해야 한다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::Invalidate

지정된 타임부터 전방을 향해 큐내의 모든 메세지를 플래시 (해방) 해, 지정된 타임부터 전방을 향해 모든 세그먼트(segment)가 데이터를 재발송하는 모든 트럭에 통지한다.

HRESULT Invalidate(
  MUSIC_TIME mtTime,
  DWORD dwFlags
);

파라미터

mtTime
무효로 하는 타임. dwFlags 에 의해 조정을 더해진다. 이 값을 0 으로 설정 하면, 즉석에서 무효가 된다.
dwFlags
mtTime 를 조정해 소절, 박, 또는 구라두에 가지런히 하는 플래그. 이 값은, 0 또는 다음에 나타내는 DMUS_SEGF_FLAGS 열거형의 멤버의 언젠가이다.

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 DMUS_E_NO_MASTER_CLOCK 를 돌려준다.

주의

mtTime 가 꽤 전의 타임으로, 그 타임에 무효로 할 수 없는 경우는, 이용 가능한 범위에서 가장 빠른 타임을 사용한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

준비 시간,세그먼트(segment)의 타이밍


IDirectMusicPerformance8::IsPlaying

특정의 세그먼트(segment) 또는 세그먼트(segment) 상태가 스피커로부터 들리고 있는지 어떤지를 판별한다.

HRESULT IsPlaying(
  IDirectMusicSegment* pSegment,
  IDirectMusicSegmentState* pSegState
);

파라미터

pSegment
체크되는 세그먼트(segment). NULL 의 경우,pSegState 만을 체크한다.
pSegState
체크되는 세그먼트(segment) 상태. NULL 의 경우,pSegment 만을 체크한다.

반환값

이 메소드가 성공해, 요구한 세그먼트(segment)와 세그먼트(segment) 상태의 어느 쪽인지가 연주되고 있는 경우는 S_OK 를 돌려준다. 어느쪽이나 연주되어 있지 않은 경우, 또는 어느 쪽인지 1 개만을 요구해, 그것이 연주되어 있지 않은 경우는, S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
DMUS_E_NO_MASTER_CLOCK

주의

세그먼트(segment) 또는 세그먼트(segment) 상태가 실제로 스피커로 연주중인 경우에게만, S_OK 가 돌려주어진다. IDirectMusicPerformance8::PlaySegment 나 IDirectMusicPerformance8::PlaySegmentEx 가 세그먼트(segment)에 대해서 불려 간 직후라도, 지연 시간이 있으므로, S_FALSE 가 돌려주어질 가능성이 있다. 같은 이유로써, 모든 메세지가 이미 발신되고 있는 경우에서도, 세그먼트(segment)가 들리고 있는 동안은, S_OK 가 돌려주어진다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::MIDIToMusic

제공되는 코드, 서브 코드 레벨, 및 연주 모드를 사용해, MIDI 노트의 값을 DirectMusic 뮤직값으로 변환한다.

HRESULT MIDIToMusic(
  BYTE bMIDIValue,
  DMUS_CHORD_KEY* pChord,
  BYTE bPlayMode,
  BYTE bChordLevel,
  WORD *pwMusicValue
);

파라미터

bMIDIValue
변환하는 MIDI 노트의 값. 0 ~ 127 의 범위에서 지정한다.
pChord
노트의 변환으로 사용되는 코드와 키의 구조에 관한 정보를 포함한 DMUS_CHORD_KEY 구조체의 주소. 이것에는, 베이스 코드의 스케일도 포함된다. 예를 들어, 코드가 CM7 의 경우, 노트는 루트음 C, 메이저 7 번의 코드 음정에 비추어 해석된다. 이 구조체는, DMUS_MAXSUBCHORD 평행 서브 코드를, 각각의 코드 음정, 루트음, 스케일, 및 회전 플래그와 함께 보관 유지한다. 또, 전체적인 키의 루트음도 보관 유지한다.
bPlayMode
뮤직값이 코드로부터 어떻게 파생할까를 결정하는 연주 모드. 값의 리스트에 대해서는, 「DMUS_PLAYMODE_FLAGS 」를 참조할것.
bChordLevel
사용할 수 있는 서브 코드를 정의하는 서브 코드 레벨. 「DMUS_SUBCHORD 」를 참조할것.
pwMusicValue
뮤직값을 받는 변수의 주소. 이 값의 상세한 것에 대하여는, 「DMUS_NOTE_PMSG 」를 참조할것.

반환값

성공했을 경우는, 다음의 몇개의 값을 돌려준다. 「주의」를 참조할것.

S_OK
DMUS_S_DOWN_OCTAVE
DMUS_S_UP_OCTAVE

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_CANNOT_CONVERT
E_INVALIDARG

주의

메소드가 실패했을 경우,*pwMusicValue 는 변경되지 않는다.

반환값이 DMUS_S_UP_OCTAVE 또는 DMUS_DOWN_OCTAVE 의 경우, 노트 변환에서는 0 미만 또는 128 이상의 노트의 값이 생성되기 (위해)때문에, 0 ~ 127 의 적절한 MIDI 범위에 들어가도록(듯이), 1 또는 복수 옥타브분만큼 위 또는 아래에 이동된다. 이것은, 연주 모드 DMUS_PLAYMODE_FIXEDTOCHORD 및 DMUS_PLAYMODE_FIXEDTOKEY 를 사용할 때에 발생하는 일이 있다. 어느쪽이나, MIDI 값을 *pwMusicValue 에 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::MusicToMIDI ,뮤직값과 MIDI 노트


IDirectMusicPerformance8::MusicToMIDI

DirectMusic 뮤직값을 MIDI 노트의 값으로 변환한다.

HRESULT MusicToMIDI(
  WORD wMusicValue,
  DMUS_CHORD_KEY* pChord,
  BYTE bPlayMode,
  BYTE bChordLevel,
  BYTE *pbMIDIValue
);

파라미터

wMusicValue
변환하는 뮤직값. 뮤직값에 대해서는, 「DMUS_NOTE_PMSG 」를 참조할것.
pChord
노트의 변환으로 사용되는 코드와 키의 구조에 관한 정보를 포함한 DMUS_CHORD_KEY 구조체의 주소. 이것에는, 베이스 코드의 스케일도 포함된다. 예를 들어, 코드가 CM7 의 경우, 노트는 루트음 C, 메이저 7 번의 코드 음정에 비추어 해석된다. 이 구조체는, DMUS_MAXSUBCHORD 평행 서브 코드를, 각각의 코드 음정, 루트음, 스케일, 및 회전 플래그와 함께 보관 유지한다. 또, 전체적인 키의 루트음도 보관 유지한다.
bPlayMode
뮤직값이 코드에 어떻게 관련할까를 결정하는 연주 모드. 값의 리스트에 대해서는, 「DMUS_PLAYMODE_FLAGS 」를 참조할것.
bChordLevel
사용할 수 있는 서브 코드를 정의하는 서브 코드 레벨. 「DMUS_SUBCHORD 」를 참조할것.
pbMIDIValue
MIDI 값을 받는 변수의 주소. 0 ~ 127 의 범위에서 지정한다.

반환값

성공했을 경우는, 다음의 몇개의 값을 돌려준다. 「주의」를 참조할것.

S_OK
DMUS_S_OVER_CHORD
DMUS_S_DOWN_OCTAVE
DMUS_S_UP_OCTAVE

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_CANNOT_CONVERT
E_INVALIDARG

주의

메소드가 실패했을 경우 또는 DMUS_S_OVER_CHORD 를 돌려주는 경우,*pwMIDIValue 는 변경되지 않는다.

뮤직값이 코드의 최고음보다 높은 위치에 있는 노트를 가지고 있기 (위해)때문에, 노트가 계산되지 않는 경우는, DMUS_S_OVER_CHORD 를 돌려준다. 이것은, DMUS_PLAYMODE_NORMALCHORD 연주 모드인 만큼 적용된다. 어플리케이션은 노트에 대해서 어떤 처리도 해서는 안 된다. 노트는 이 코드에 대해서 연주되는 것은 아니다.

반환값이 DMUS_S_UP_OCTAVE 또는 DMUS_DOWN_OCTAVE 의 경우, 노트 변환에서는 0 미만 또는 128 이상의 노트의 값이 생성되기 (위해)때문에, 0 ~ 127 의 적절한 MIDI 범위에 들어가도록(듯이), 1 또는 복수 옥타브분만큼 위 또는 아래에 이동된다. 이것은, DMUS_PLAYMODE_FIXED 이외의 연주 모드를 사용할 때에 발생하는 일이 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::MIDIToMusic ,뮤직값과 MIDI 노트


IDirectMusicPerformance8::MusicToReferenceTime

MUSIC_TIME 포맷의 퍼포먼스 타임을 REFERENCE_TIME 포맷으로 변환한다.

HRESULT MusicToReferenceTime(
  MUSIC_TIME mtTime,
  REFERENCE_TIME* prtTime
);

파라미터

mtTime
변환되는,MUSIC_TIME 포맷의 시간.
prtTime
REFERENCE_TIME 포맷에 변환된 시간을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
DMUS_E_NO_MASTER_CLOCK

주의

기준 타임은 뮤직 타임보다 정확하기 때문에, 기준 타임부터 뮤직 타임으로 변환해, 또 기준 타임으로 변환한 타임은, 아마 원의 값과는 다르다.

이 메소드는, 퍼포먼스의 시간은 아니고, 퍼포먼스의 시작으로부터의 타임의 오프셋(offset)를 변환한다. 뮤직 타임과 기준 타임의 단위의 비율은, 템포에 의해 다르므로,prtTime 를 계산할 때에, DirectMusic 는 퍼포먼스 시작 이후의 모든 템포의 변경을 고려한다. 퍼포먼스에 대해 마스터 템포가 설정되어 있는 경우는, 똑같이 고려된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::ReferenceToMusicTime ,클락 타임과 뮤직 타임


IDirectMusicPerformance8::PChannelInfo

지정된 퍼포먼스 채널의 포토, 그룹, 및 MIDI 채널을 취득한다.

HRESULT PChannelInfo(
  DWORD dwPChannel,
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

파라미터

dwPChannel
정보가 필요하게 되는 퍼포먼스 채널.
ppPort
IDirectMusicPort8 포인터를 받는 변수의 주소. 포인터가 불필요한 경우는, NULL 이라도 좋다. NULL 이외의 포인터가 돌려주어지는 경우, 참조 카운트는 인크리먼트(increment) 된다. 포인터에 대해서 Release 를 호출하는 것은 어플리케이션이다. 「주의」도 참조할것.
pdwGroup
포토 위에의 그룹에의 포인터를 받는 변수의 주소. 이 값이 불필요한 경우는, NULL 이라도 좋다.
pdwMChannel
그룹내의 MIDI 채널에의 포인터를 받는 변수의 주소. 이 값이 불필요한 경우는, NULL 이라도 좋다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

주의

IDirectMusicPerformance8::RemovePort 의 호출에 의해 포토가 삭제되었을 경우,*ppPort 에는 NULL 포인터가 돌려주어지지만, 메소드는 성공한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::AssignPChannel ,IDirectMusicPerformance8::AssignPChannelBlock


IDirectMusicPerformance8::PlaySegment

세그먼트(segment)의 재생을 시작 한다.

HRESULT PlaySegment(
  IDirectMusicSegment* pSegment,
  DWORD dwFlags,
  __int64 i64StartTime,
  IDirectMusicSegmentState** ppSegmentState
);

파라미터

pSegment
연주되는 세그먼트(segment).
dwFlags
메소드의 동작을 변경하는 플래그. 「DMUS_SEGF_FLAGS 」를 참조할것.
i64StartTime
세그먼트(segment)의 연주를 시작 하는 퍼포먼스 타임. dwFlags 로 지정되는 임의의 경계 분해가능에 조정된다. DMUS_SEGF_REFTIME 플래그가 설정되어 있지 않은 한, 타임은 뮤직 타임에 나타내진다. 값이 0 의 경우, 세그먼트(segment)의 연주는 할 수 있는 한 빨리 시작 된다.
ppSegmentState
연주중의 세그먼트(segment)의 인스턴스에 관한 세그먼트(segment) 상태에의 포인터를 받는 변수의 주소. 이 필드는 NULL 이라도 좋다. NULL 가 아닌 경우, 세그먼트(segment) 상태 포인터가 돌려주어져 어플리케이션은 이 포인터에 대해서 Release 를 호출하지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_OUTOFMEMORY
E_POINTER
DMUS_E_NO_MASTER_CLOCK
DMUS_E_SEGMENT_INIT_FAILED
DMUS_E_TIME_PAST

주의

세그먼트(segment)의 길이는 250 밀리 세컨드 (ms)를 넘고 있을 필요가 있다.

dwFlags 의 경계 분해가능은, 프라이머리 세그먼트(segment)에 관련하는 것이다.

프라이머리 세그먼트(segment)의 연주가, 다른 프라이머리 세그먼트(segment)의 연주중에 스케줄 설정되어 있는 경우, 후에 연주되는 세그먼트(segment)에 DMUS_SEGF_QUEUE 플래그를 설정하지 않는 한, 최초의 세그먼트(segment)는 정지한다. 후에 연주되는 세그먼트(segment)에 DMUS_SEGF_QUEUE 플래그를 설정했을 경우, 그 세그먼트(segment)는, 최초의 세그먼트(segment)의 연주가 끝나는 것과 동시에 연주가 시작 된다.

세그먼트(segment)의 정확한 시작 타임의 상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것. 템포의 변경이 세그먼트(segment)의 시작 타임에 미치는 영향에 대해서는, 「클락 타임과 뮤직 타임」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::PlaySegmentEx


IDirectMusicPerformance8::PlaySegmentEx

세그먼트(segment)의 재생을 시작 한다. 이 메소드는,IDirectMusicPerformance8::PlaySegment 보다 높은 기능을 제공한다.

HRESULT PlaySegmentEx(
  IUnknown* pSource,
  WCHAR *pwzSegmentName,
  IUnknown* pTransition,
  DWORD dwFlags,
  __int64 i64StartTime,
  IDirectMusicSegmentState** ppSegmentState,
  IUnknown* pFrom,
  IUnknown* pAudioPath
);

파라미터

pSource
재생하는 오브젝트의 IUnknown 인터페이스의 주소.
pwzSegmentName
DirectX 8.0 에서는 이행되어 있지 않다. NULL 로 설정하는 것.
pTransition
템플릿 세그먼트(segment)의 트란지션을 어레인지 할 때에 사용하는, 템플릿 세그먼트(segment)의 IUnknown 인터페이스 포인터. NULL 이라도 좋다. 「주의」를 참조할것.
dwFlags
메소드의 동작을 변경하는 플래그. 「DMUS_SEGF_FLAGS 」를 참조할것.
i64StartTime
세그먼트(segment)의 연주를 시작 하는 퍼포먼스 타임. dwFlags 로 지정되는 임의의 경계 분해가능에 조정된다. DMUS_SEGF_REFTIME 플래그가 설정되어 있지 않은 한, 타임은 뮤직 타임에 나타내진다. 값이 0 의 경우, 세그먼트(segment)의 연주는 할 수 있는 한 빨리 시작 된다.
ppSegmentState
연주중 세그먼트(segment)의 이 인스턴스를 나타내는,IDirectMusicSegmentState 인터페이스 포인터를 받는 변수의 주소. IDirectMusicSegmentState8 를 취득하려면 ,QueryInterface 를 사용한다. 이 인터페이스의 참조 카운트는 인크리먼트(increment) 된다. 세그먼트(segment) 상태 포인터를 필요로 하지 않는 경우는, 이 파라미터를 NULL 로 한다.
pFrom
새로운 세그먼트(segment)의 연주를 시작 할 경우에 정지하는 세그먼트(segment) 상태 또는 오디오 패스를 가리키는 IUnknown 인터페이스 포인터. 오디오 패스를 가리키는 경우는, 그 오디오 패스로 연주중의 모든 세그먼트(segment) 상태가 정지된다. 이 값은 NULL 이라도 좋다.
pAudioPath
재생에 사용하는 오디오 패스를 나타내는 오브젝트의 IUnknown 인터페이스 포인터. 디폴트 패스로 연주하는 경우는, NULL.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_AUDIOPATH_INACTIVE
DMUS_E_AUDIOPATH_NOPORT
DMUS_E_NO_MASTER_CLOCK
DMUS_E_SEGMENT_INIT_FAILED
DMUS_E_TIME_PAST
E_OUTOFMEMORY
E_POINTER

주의

세그먼트(segment)의 길이는 250 밀리 세컨드 (ms)를 넘고 있을 필요가 있다.

dwFlags 의 경계 분해가능은, 프라이머리 세그먼트(segment)에 관련하는 것이다.

프라이머리 세그먼트(segment)의 연주가, 다른 프라이머리 세그먼트(segment)의 연주중에 스케줄 설정되어 있는 경우, 후에 연주되는 세그먼트(segment)에 DMUS_SEGF_QUEUE 플래그를 설정하지 않는 한, 최초의 세그먼트(segment)는 정지한다. 후에 연주되는 세그먼트(segment)에 DMUS_SEGF_QUEUE 플래그를 설정했을 경우, 그 세그먼트(segment)는, 최초의 세그먼트(segment)의 연주가 끝나는 것과 동시에 연주가 시작 된다.

세그먼트(segment)의 정확한 시작 타임의 상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것. 템포의 변경이 세그먼트(segment)의 시작 타임에 미치는 영향에 대해서는, 「클락 타임과 뮤직 타임」을 참조할것.

dwFlags 에 DMUS_SEGF_AUTOTRANSITION 가 지정되고 있을 때,i64StartTime 로 이미 연주중의 세그먼트(segment)를 중단하는 경우, 이 메소드는, 2 개의 세그먼트(segment)간의 트란지션을 어레인지 해, 그것을 연주한 후에 pSource 를 연주한다. 트란지션은,pTransition 로 제공되는 템플릿에 근거한다.

이 메소드를 사용해, 오디오 패스를 사용하지 않는 퍼포먼스, 즉 IDirectMusicPerformance8::Init 를 사용해 초기화된 퍼포먼스로 연주할 수 있다. 이 경우,pAudioPath 파라미터는 NULL 가 아니면 안된다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicPerformance8::ReferenceToMusicTime

REFERENCE_TIME 포맷의 퍼포먼스 타임을 MUSIC_TIME 포맷으로 변환한다.

HRESULT ReferenceToMusicTime(
  REFERENCE_TIME rtTime,
  MUSIC_TIME* pmtTime
);

파라미터

rtTime
REFERENCE_TIME 포맷의 시간.
pmtTime
MUSIC_TIME 포맷에 변환된 시간을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
DMUS_E_NO_MASTER_CLOCK

주의

뮤직 타임은 기준 타임만큼 정확하지 않기 때문에, 잘라서 버림을 한다.

이 메소드는, 퍼포먼스의 시간은 아니고, 퍼포먼스의 시작으로부터의 타임의 오프셋(offset)를 변환한다. 뮤직 타임과 기준 타임의 단위의 비율은, 템포에 의해 다르므로,prtTime 를 계산할 때에, DirectMusic 는 퍼포먼스 시작 이후의 모든 템포의 변경을 고려한다. 퍼포먼스에 대해 마스터 템포가 설정되어 있는 경우는, 똑같이 고려된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::MusicToReferenceTime ,클락 타임과 뮤직 타임


IDirectMusicPerformance8::RemoveNotificationType

이전에 추가된 통지 타입을 퍼포먼스로부터 삭제한다. RemoveNotificationType 메소드를 호출하면, 모든 세그먼트(segment)와 트럭은 갱신된다.

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
삭제되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). (정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것). 이 값이 GUID_NULL 의 경우, 모든 통지가 삭제된다.

반환값

성공했을 경우는 S_OK 또는 S_FALSE 를 돌려준다 ( 「주의」를 참조할것).

실패했을 경우는 E_POINTER 를 돌려준다.

주의

rguidNotificationType 가 액티브한 통지가 아닌 경우, S_FALSE 가 돌려주어진다.

연주를 정지한 세그먼트(segment)에 통지를 추가했을 경우, 세그먼트(segment)에의 참조가 없어지는 것으로, 퍼포먼스는 그 세그먼트(segment)로부터 통지 타입을 삭제할 수 없게 된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::AddNotificationType ,IDirectMusicSegment8::RemoveNotificationType ,IDirectMusicTrack8::RemoveNotificationType ,통지와 이벤트의 처리


IDirectMusicPerformance8::RemovePort

퍼포먼스로부터 포토를 삭제한다. 이 포토에 맵 되고 있던 모든 퍼포먼스 채널은 무효가 되어, 그 스탬프가 뒤따른 메세지가 연주될 것도 없다.

HRESULT RemovePort(
  IDirectMusicPort* pPort
);

파라미터

pPort
삭제되는 포토.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

주의

IDirectMusicPerformance8::AddPort 에 NULL 를 건네주어 추가된 포토는,RemovePort 에 NULL 를 건네주어 삭제할 수 없다.

이 메소드는, 오디오 패스를 사용하는 어플리케이션으로 호출할 수 없다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::AddPort


IDirectMusicPerformance8::RhythmToTime

리듬 타임을 뮤직 타임으로 변환한다.

HRESULT RhythmToTime(
  WORD wMeasure,
  BYTE bBeat,
  BYTE bGrid,
  short nOffset,
  DMUS_TIMESIGNATURE *pTimeSig,
  MUSIC_TIME *pmtTime
);

파라미터

wMeasure
변환되는 타임의 소절.
bBeat
변환되는 타임의 박.
bGrid
변환되는 타임의구라두 .
nOffset
변환되는 타임의 구라두로부터의 오프셋(offset). 뮤직 타임의 틱으로 나타낸다.
pTimeSig
박자 기호에 관한 정보를 포함한 DMUS_TIMESIGNATURE 구조체의 주소.
pmtTime
뮤직 타임을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::TimeToRhythm


IDirectMusicPerformance8::SendPMsg

퍼포먼스 메세지를 송신한다. 이 메소드는, 트럭의 연주시에 불려 간다. 툴에 의해 불려 가 새로운 데이터를 퍼포먼스에 삽입하는 경우도 있다.

HRESULT SendPMsg(
  DMUS_PMSG* pPMSG
);

파라미터

pPMSG
IDirectMusicPerformance8::AllocPMsg 에 의해 할당할 수 있었던 메세지. 이 구조체는,DMUS_PMSG 의 파생 타입이다. 「DirectMusic 메세지」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
E_INVALIDARG
E_POINTER

주의

타임 스탬프가 rtTime 와 mtTime 의 어느 쪽이 되어 있을까에 응해,dwFlags 멤버 ( 「DMUS_PMSG 」를 참조)는 DMUS_PMSGF_MUSICTIME 와 DMUS_PMSGF_REFTIME 의 어느 쪽인지를 포함하지 않으면 안 된다. 또, 메세지의 타입에 응해,dwFlags 는 DMUS_PMSGF_TOOL_QUEUE, DMUS_PMSGF_TOOL_ATTIME, 또는 DMUS_PMSGF_TOOL_IMMEDIATE 몇개의 적절한 전달 타입을 포함하지 않으면 안 된다. 어느 것도 지정하지 않는 경우, 디폴트로서 DMUS_PMSGF_TOOL_IMMEDIATE 가 사용된다.

메세지의 타임이 0 으로 설정되어dwFlags 멤버가 DMUS_PMSGF_REFTIME 를 포함하고 있는 경우, 이 메세지는 즉석에서 배웅하는 것으로서 큐에 삽입된다.

대부분의 경우는,SendPMsg 를 호출하기 전에 IDirectMusicGraph8::StampPMsg 메소드를 메세지에 대해서 호출해야 하는 것이다. 다만, 메세지를 메인의 출력 툴에 직접 송신하는 경우는, 이 스텝을 생략 해도 괜찮다. 퍼포먼스 그래프로부터 마셔 메세지를 건네주는 경우는,IDirectMusicPerformance8::QueryInterface 를 호출하는 것으로,IDirectMusicGraph8 인터페이스를 취득한다. 그 이외의 경우는,IDirectMusicSegment8::QueryInterface 를 호출하는 것에 의해, 이 인터페이스를 취득한다. IDirectMusicPerformance8::GetGraph 나 IDirectMusicSegment8::GetGraph 를 호출하는 것으로, 인터페이스를 취득하려고 해서는 안 된다. 이러한 메소드가 돌려주는 것은, 그래프 오브젝트에의 포인터이며, 퍼포먼스나 세그먼트(segment)의 IDirectMusicGraph8 인터페이스의 이행에의 포인터는 아니다.

퍼포먼스는 보통, 처리가 끝난 메세지를 해방한다. 상세한 것에 대하여는,IDirectMusicPerformance8::FreePMsg 의 「주의」를 참조할것.

다음의 샘플 코드는, 시스템에크스크루시브멧세이지와 템포 메세지의 할당 방법과 송신 방법을 나타내고 있다.

// pPerformance 은 유효한 IDirectMusicPerformance8 포인터이며,
mtTime 는 초기화 끝난 변수 MUSIC_TIME
// 이라고 가정한다.

IDirectMusicGraph* pGraph;

// 퍼포먼스로부터 그래프 포인터를 취득한다. 세그먼트(segment) 그래프를 사용해
// 메세지를 건네주는 경우는, 세그먼트(segment) 오브젝트 대신에
// QueryInterface 를 사용한다.

if ( SUCCEEDED( pPerformance->QueryInterface(
        IID_IDirectMusicGraph, (void**) &pGraph )))
{
    // 적절한 사이즈의 DMUS_SYSEX_PMSG 를 할당해
    // 시스템에크스크루시브데이타를 거기에 읽어들이게 한다.

    DMUS_SYSEX_PMSG* pSysEx;

    if ( SUCCEEDED( pPerformance->AllocPMsg(
            sizeof(DMUS_SYSEX_PMSG) + m_dwSysExLength,
            (DMUS_PMSG**) &pSysEx )))
    {
        ZeroMemory(pSysEx, sizeof(DMUS_NOTE_PMSG));
        pSysEx->dwSize = sizeof(DMUS_SYSEX_PMSG);
        pSysEx->dwLen = dwSysExLength;
        pSysEx->mtTime = mtTime;
        pSysEx->dwFlags = DMUS_PMSGF_MUSICTIME;
        pSysEx->dwType = DMUS_PMSGT_SYSEX;

        // m_pbSysExData 은, 길이가 m_dwSysExLength 의 데이터를 보관 유지한다
        // 배열에의 포인터이라고 가정한다.

        memcpy( pSysEx->abData, m_pbSysExData, m_dwSysExLength );

        pGraph->StampPMsg( (DMUS_PMSG*) pSysEx );
        if (FAILED(pPerformance->SendPMsg( (DMUS_PMSG*) pSysEx )))
        {
            pPerformance->FreePMsg( (DMUS_PMSG*) pSysEx );
        }
    }

    // 타임 mtTime 의 템포를 120 bpm 로 변경한다.

    DMUS_TEMPO_PMSG* pTempo;

    if( SUCCEEDED( pPerformance->AllocPMsg(
            sizeof(DMUS_TEMPO_PMSG),
            (DMUS_PMSG**) &pTempo )))
    {
        pTempo->dwSize = sizeof(DMUS_TEMPO_PMSG);
        pTempo->dblTempo = 120;
        pTempo->mtTime = mtTime;
        pTempo->dwFlags = DMUS_PMSGF_MUSICTIME;
        pTempo->dwType = DMUS_PMSGT_TEMPO;
        pGraph->StampPMsg( (DMUS_PMSG*) pTempo );
        if (FAILED(pPerformance->SendPMsg( (DMUS_PMSG*) pTempo )))
        {
            pPerformance->FreePMsg( (DMUS_PMSG*) pTempo );
        }
    }

    pGraph->Release();
}

다음의 샘플 코드는,dwTrackID 에 의해 식별되는 트럭에 관련지을 수 있었던 노트 메세지를 송신하는 함수를 나타낸다. 메세지가 DirectMusicTrack 오브젝트로부터 생성되어 있지 않은 경우, 가상 트럭 ID 는 0 이 아니면 안된다.

HRESULT CreateNotePMsg(IDirectMusicPerformance8* pPerformance,
        MUSIC_TIME mtTime, DWORD dwTrackID)
{

    // Note PMessage 를 할당한다.
    DMUS_NOTE_PMSG* pNote = NULL;
    HRESULT hr = pPerformance->AllocPMsg( sizeof(DMUS_NOTE_PMSG),
            (DMUS_PMSG**) &pNote);
    if (FAILED(hr)) return hr;

    pNote->dwSize = sizeof(DMUS_NOTE_PMSG); // Note Pmessage 의 사이즈.
    pNote->rtTime = 0;                      // 무시된다.
    pNote->mtTime = mtTime;                 // 노트의 연주 타임.
    pNote->dwFlags = DMUS_PMSGF_MUSICTIME;  // mtTime 필드를 사용한다.
    pNote->dwPChannel = 5;                  // PChannel 5 로 연주한다.
    pNote->dwVirtualTrackID = dwTrackID;    // 파라미터로부터의 트럭 ID.

    // 다음의 2 개의 필드는, 메세지를 처음으로 송신할 경우에,
    // NULL 로 설정해야 한다. 이러한 필드는,
    // IDirectMusicGraph::StampPMsg 로 갱신된다.
    pNote->pTool = NULL;
    pNote->pGraph = NULL;
    pNote->dwType = DMUS_PMSGT_NOTE;
    pNote->dwVoiceID = 0;           // 항상 0.
    pNote->dwGroupID = 0xFFFFFFFF;  // 모든 트럭 그룹.
    pNote->punkUser = NULL;         // 항상 NULL.

    // 현재의 박자 기호를 퍼포먼스로부터 취득해,
    // 소절과 박의 정보를 계산한다.
    DMUS_TIMESIGNATURE TimeSig;
    MUSIC_TIME mtNext;
    hr = pPerformance->GetParam(GUID_TimeSignature, 0xFFFFFFFF,
            0, mtTime, &mtNext, &TimeSig);
    if (FAILED(hr)) return hr;

    // TimeSig.mtTime 를 재계산해,
    // pPerformance->TimeToRhythm 가 예기 하는 값을 취득한다.
    TimeSig.mtTime += mtTime;

    // 현재의 코드를 퍼포먼스로부터 취득해,
    // 노트의 값을 생성 한다.
    DMUS_CHORD_KEY Chord;
    hr = pPerformance->GetParam(GUID_ChordParam, 0xFFFFFFFF, 0,
            mtTime, &mtNext, &Chord);
    if (FAILED(hr)) return hr;

    // 옥타브 5, 코드음 2 (5 도), 스케일을 가지는 노트를 생성 한다.
    // 오프셋(offset) 1 (=> 6 번), 변화음 없음.
    WORD wMusicValue = 0x5210;

    // DMUS_PLAYMODE_PEDALPOINT 을
    // pPerformance->MusicToMIDI 에서의 연주 모드로서 사용한다.
    BYTE bPlayModeFlags = DMUS_PLAYMODE_PEDALPOINT;

    // DMUS_NOTE_PMSG 에 고유한 필드를 입력한다.
    pNote->wMusicValue = wMusicValue;
    hr = pPerformance->MusicToMIDI(
        wMusicValue,
        &Chord,
        bPlayModeFlags,
        0,
        &(pNote->bMidiValue));
    if (FAILED(hr)) return hr;

    hr = pPerformance->TimeToRhythm(
        TimeSig.mtTime,
        &TimeSig,
        &(pNote->wMeasure),
        &(pNote->bBeat),
        &(pNote->bGrid),
        &(pNote->nOffset));
    if (FAILED(hr)) return hr;

    pNote->mtDuration = DMUS_PPQ;       // 4 분 음표의 지속 시간.
    pNote->bVelocity = 120;             // MIDI 의 velocity (0 ~ 127).
    pNote->bFlags = DMUS_NOTEF_NOTEON;  // 항상 이 값으로 설정한다.
    pNote->bTimeRange = 250;            // 시작 타임을 큰폭으로 랜덤화한다.
    pNote->bDurRange = 5;               // 지속 시간을 조금 랜덤화한다.
    pNote->bVelRange = 0;               // velocity는 랜덤화하지 않는다.
    pNote->bPlayModeFlags = bPlayModeFlags;
    pNote->bSubChordLevel = 0;          // 노트는 서브 코드 레벨 0 을 사용한다.
    pNote->cTranspose = 0;              // 전조는 없다.

    // 메세지에 퍼포먼스 그래프의 스탬프를 붙인다.
    IDirectMusicGraph* pGraph;
    hr = pPerformance->QueryInterface( IID_IDirectMusicGraph,
            (void**) &pGraph );
    if (FAILED(hr)) return hr;

    pGraph->StampPMsg( (DMUS_PMSG*) pNote );
    pGraph->Release();

    // 마지막에 메세지를 송신한다.
    hr = pPerformance->SendPMsg( (DMUS_PMSG*) pNote);
    if (FAILED(hr))
    {
        pPerformance->FreePMsg( (DMUS_PMSG*) pNote);
        return hr;
    }
    return S_OK;
}

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicTool8::ProcessPMsg ,메세지,DirectMusic 메세지,DirectMusic 툴


IDirectMusicPerformance8::SetBumperLength

렌더링의 목적으로 메세지를 포토에 송신하는 경우에, 포토의 지연 시간보다 전에 놓여지는 완충 시간 (범퍼 시간)을 설정한다. 이 주제의 개요에 대해서는, 「타이밍」을 참조할것.

HRESULT SetBumperLength(
  DWORD dwMilliSeconds
);

파라미터

dwMilliSeconds
연주전의 시간의 길이 (밀리 세컨드 단위). 디폴트값은 50 이다.

반환값

S_OK 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetBumperLength ,IDirectMusicPerformance8::SetPrepareTime


IDirectMusicPerformance8::SetDefaultAudioPath

퍼포먼스에 디폴트 오디오 패스를 설정해 액티브하게 한다.

HRESULT SetDefaultAudioPath(
  IDirectMusicAudioPath *pAudioPath
);

파라미터

pAudioPath
디폴트의 오디오 패스의 IDirectMusicAudioPath8 인터페이스에의 포인터. 현재의 디폴트의 오디오 패스를 삭제하려면 , NULL 를 지정한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_AUDIOPATH_NOPORT
DMUS_E_AUDIOPATHS_NOT_VALID
DMUS_E_NOT_INIT
E_INVALIDARG
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetDefaultAudioPath ,IDirectMusicPerformance8::InitAudio


IDirectMusicPerformance8::SetGlobalParam

퍼포먼스의 글로벌값을 설정한다.

HRESULT SetGlobalParam(
  REFGUID rguidType,
  void* pParam,
  DWORD dwSize
);

파라미터

rguidType
데이터형의 식별자에의 참조 (C++) 또는 주소 (C).
pParam
퍼포먼스에의 카피와 보존을 하는 데이터의 주소.
dwSize
데이터의 사이즈. rguidType 마다 일정한 값이다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_POINTER
E_OUTOFMEMORY

주의

퍼포먼스는 모든 데이터형을 파악하고 있는 것은 아니기 때문에,dwSize 파라미터는 필요하다. 필요에 따라서, 새로운 타입도 생성 할 수 있다.

DirectMusic 에 의해 정의되는 파라미터, 및 그것들에 관련이 있는 데이터형에 대해서는, 「글로벌 파라미터의 설정과 취득」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetGlobalParam ,IDirectMusicPerformance8::SetParam ,퍼포먼스 파라미터


IDirectMusicPerformance8::SetGraph

퍼포먼스의 툴 그래프를 옮겨놓는다.

HRESULT SetGraph(
  IDirectMusicGraph* pGraph
);

파라미터

pGraph
설정하는 툴 그래프. 퍼포먼스로부터 그래프를 소거하기 위해서, NULL 에도 설정할 수 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

현재의 툴 그래프내에서 처리중의 메세지는 모두 삭제된다.

이 메소드는 그래프의 참조 카운트를 인크리먼트(increment) 하므로, 오리지날의 참조를 해방해 두면(자) 안전하다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetGraph ,IDirectMusicPerformance8::GetGraph ,IDirectMusicPerformance8::SendPMsg


IDirectMusicPerformance8::SetNotificationHandle

통지용의 이벤트 핸들 (Microsoft® Win32® 의 CreateEvent 함수에 의해 생성 된다)을 설정한다. 어플리케이션은, 이 핸들에 대해서 Win32 WaitForSingleObject 함수를 적용해야 한다. 시그널이 송신되었을 때에, 어플리케이션은 IDirectMusicPerformance8::GetNotificationPMsg 메소드를 호출해, 통지 이벤트를 취득해야 한다.

HRESULT SetNotificationHandle(
  HANDLE hNotification,
  REFERENCE_TIME rtMinimum
);

파라미터

hNotification
CreateEvent 에 의해 생성 된 이벤트 핸들. 기존의 핸들을 소거하는 경우는, 0 을 지정한다.
rtMinimum
퍼포먼스가 낡은 통지 이벤트를 파기하기까지 보관 유지해 두는 최소의 시간. 값으로서 0 을 지정 하면, 디폴트의 최소 값인 20,000,000 기준 타임 단위 (2 초), 또는 이전에 이 메소드를 호출했을 때의 값을 의미한다. 어플리케이션이 아직 GetNotificationPMsg 를 호출하지 않은 경우는, 이 이벤트는 파기되어, 메모리가 해방된다.

반환값

S_OK 를 돌려준다.

주의

통지 핸들이 불필요하게 되었을 경우는, 어플리케이션이 통지 핸들에 대해서 Win32 CloseHandle 함수를 호출하지 않으면 안 된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리


IDirectMusicPerformance8::SetParam

제어 세그먼트(segment)의 트럭에 데이터를 설정한다.

HRESULT SetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  void* pParam
);

파라미터

rguidType
설정되는 데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
dwGroupBits
희망의 트럭이 놓여지는 그룹.
dwIndex
데이터를 어디로 설정하는지를 나타내는,dwGroupBits 로 식별되는 그룹내의 트럭의 인덱스. 파라미터를 저장 하는 그룹내의 모든 트럭에 파라미터를 설정하려면 , DMUS_SEG_ALLTRACKS 를 지정한다.
mtTime
데이터의 설정을 실시하는 타임. IDirectMusicSegment8::SetParam 과는 달리, 이 타임은 퍼포먼스 타임이다. 이 타임부터 세그먼트(segment)의 시작 타임을 당겨, 그 결과를 IDirectMusicSegment8::SetParam 에 건네준다.
pParam
데이터를 보관 유지하는 구조체의 주소. 이 구조체는,rguidType 로 식별된 데이터형에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

주의

보통, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. 다만, 세칸다리세그먼트를 연주 하면나무는, 이것을 제어 세그먼트(segment)로서 지정할 수 있다. 「DMUS_SEGF_FLAGS 」를 참조할것.

dwGroupBits 와 dwIndex 의 설명에 대해서는, 「트럭의 식별」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetGlobalParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::SetParamEx ,IDirectMusicPerformance8::GetTime ,퍼포먼스 파라미터


IDirectMusicPerformance8::SetPrepareTime

트럭에 의해 메세지가 송신되고 나서 사운드가 들릴 때까지의 간격을 설정한다. 이전 격은, 툴이 메세지를 처리하는데 충분한 시간이다.

HRESULT SetPrepareTime(
  DWORD dwMilliSeconds
);

파라미터

dwMilliSeconds
준비 시간의 길이 (밀리 세컨드 단위). 디폴트값은 1,000 이다.

반환값

S_OK 를 돌려준다.

주의

개요에 대해서는, 「타이밍」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetPrepareTime ,IDirectMusicPerformance8::SetBumperLength ,준비 시간,지연 시간과 범퍼 시간


IDirectMusicPerformance8::Stop

세그먼트(segment) 또는 세그먼트(segment) 상태의 재생을 정지한다.

현재는, 이 메소드에 대신해 IDirectMusicPerformance8::StopEx 가 사용되고 있다. 이것을 사용하면(자), 세그먼트(segment), 세그먼트(segment) 상태, 또는 오디오 패스를 정지할 수 있다.

HRESULT Stop(
  IDirectMusicSegment* pSegment,
  IDirectMusicSegmentState* pSegmentState,
  MUSIC_TIME mtTime,
  DWORD dwFlags
);

파라미터

pSegment
연주를 정지하는 세그먼트(segment). 이 세그먼트(segment)에 근거하는 모든 세그먼트(segment) 상태는,mtTime 의 시점에서 정지된다. 「주의」를 참조할것.
pSegmentState
연주를 정지하는 세그먼트(segment) 상태. 「주의」를 참조할것.
mtTime
세그먼트(segment), 세그먼트(segment) 상태, 또는 그 양쪽 모두를 정지하는 타임. 이 타임이 과거의 타임인 경우나, 값으로서 0 을 지정했을 경우는, 지정 세그먼트(segment)와 세그먼트(segment) 상태의 연주가 즉석에서 정지된다.
dwFlags
연주의 정지 타임을 지정하는 플래그. 경계는 현재의 프라이머리 세그먼트(segment)에 관련한다. 값의 리스트에 대해서는, 「IDirectMusicPerformance8::StopEx 」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

pSegment 와 pSegmentState 의 양쪽 모두가 NULL 인 경우, 모든 음악은 정지해, 현재 큐에 두어져 모든 세그먼트(segment)가 해방된다. pSegment 와 pSegmentState 의 어느 쪽인지가 NULL 가 아닌 경우, 지정된 세그먼트(segment) 상태가 퍼포먼스로부터 삭제된다. 양쪽 모두 NULL 는 아니고, 게다가 DMUS_SEGF_DEFAULT 가 사용되고 있는 경우,pSegment 로부터 얻을 수 있던 디폴트의 분해가능을 사용한다.

모든 파라미터에 NULL 또는 0 을 설정 하면, 모든 연주가 즉석에서 정지해, 콘트롤러 리셋 메세지 및 노트 오프 메세지가, 맵 된 모든 퍼포먼스 채널에 송신된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::PlaySegment ,IDirectMusicPerformance8::PlaySegmentEx ,IDirectMusicPerformance8::StopEx ,DMUS_SEGF_FLAGS


IDirectMusicPerformance8::StopEx

오브젝트의 재생을 정지한다.

HRESULT StopEx(
  IUnknown *pObjectToStop,
  __int64 i64StopTime,
  DWORD dwFlags
);

파라미터

pObjectToStop
정지하는 세그먼트(segment), 세그먼트(segment) 상태, 또는 오디오 패스의 IUnknown 인터페이스에의 포인터.
i64StopTime
정지하는 타임. 이 타임이 과거의 타임인 경우나, 값으로서 0 을 지정했을 경우는, 오브젝트의 연주가 즉석에서 정지된다.
dwFlags
연주의 정지 타임을 지정하는 플래그. 경계는 현재의 프라이머리 세그먼트(segment)에 관련한다. 다음의 몇개의 값인가, DMUS_SEGF_REFTIME 에 다른 플래그를 조합할 수가 있다.
0
즉석에서 정지한다.
DMUS_SEGF_AUTOTRANSITION
무음에의 트란지션을 어레인지 해 연주한다. 노래를 정지하는 경우에게만 유효하다. DirectX 8.0 에서는 이행 되지 않는다.
DMUS_SEGF_BEAT
다음의 박경계에서, 또는 i64StopTime 의 뒤에 정지한다.
DMUS_SEGF_DEFAULT
IDirectMusicSegment8::SetDefaultResolution 메소드로 설정된 디폴트 경계에서 정지한다.
DMUS_SEGF_GRID
다음의 구라두 경계에서, 또는 i64StopTime 의 뒤에 정지한다.
DMUS_SEGF_MEASURE
다음의 소절 경계에서, 또는 i64StopTime 의 뒤에 정지한다.
DMUS_SEGF_REFTIME
i64StopTime 의 값은 기준 타임이다.
DMUS_SEGF_SEGMENTEND
프라이머리 세그먼트(segment)의 최후로 정지한다.
DMUS_SEGF_MARKER
다음의 마커로 정지한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

세그먼트(segment)를 정지 하면, 연주중의 모든 인스턴스가 정지한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::Stop ,IDirectMusicPerformance8::PlaySegmentEx ,DMUS_SEGF_FLAGS


IDirectMusicPerformance8::TimeToRhythm

뮤직 타임을 리듬 타임으로 변환한다.

HRESULT TimeToRhythm(
  MUSIC_TIME mtTime,
  DMUS_TIMESIGNATURE *pTimeSig,
  WORD *pwMeasure,
  BYTE *pbBeat,
  BYTE *pbGrid,
  short *pnOffset
);

파라미터

mtTime
변환되는 타임.
pTimeSig
박자 기호에 관한 정보를 포함한 DMUS_TIMESIGNATURE 구조체의 주소.
pwMeasure
타임이 속하는 소절을 받는 변수의 주소.
pbBeat
타임이 속하는 박을 받는 변수의 주소.
pbGrid
타임이 속하는구라두를 받는 변수의 주소.
pnOffset
타임이 속하는 구라두 (뮤직 타임의 틱으로 나타낸다)로부터의 오프셋(offset)를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::RhythmToTime


IDirectMusicPort8

IDirectMusicPort8 인터페이스는, DirectMusicPort 오브젝트에의 액세스를 제공한다. DirectMusicPort 오브젝트는, 뮤직 데이터를 송신 또는 수신하는 디바이스를 나타낸다. MPU-401 의 입력 포토, MPU-401 의 출력 포토, Microsoft 의 소프트웨어 신디사이저, IHV 가 제공하는 필터는, 모두 포토이다. MPU-401 등의 물리적인 디바이스는, 복수의 포토를 제공할 수 있다. 다만, 단일의 포토에서는, 데이터의 캡춰와 렌더링은 할 수 없다.

IDirectMusicPort8 는,IDirectMusicPort 의 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

이 인터페이스는 보통,IDirectMusic8::CreatePort 메소드를 사용해 취득한다.

개요에 대해서는, 「DirectMusic 포토의 사용법」을 참조할것.

IDirectMusicPort8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

버퍼 | PlayBuffer
 | Read
 | SetReadNotificationHandle
채널 | GetChannelPriority
 | GetNumChannelGroups
 | SetChannelPriority
 | SetNumChannelGroups
디바이스 관리 | Activate
 | DeviceIoControl
 | SetDirectSound
DLS 데이터 | Compact
 | DownloadInstrument
 | UnloadInstrument
정보 | GetCaps
 | GetFormat
 | GetLatencyClock
 | GetRunningStats

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. 이 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICPORT8 형은,IDirectMusicPort8 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicPort8 *LPDIRECTMUSICPORT8;

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicPort8::Activate

포토를 액티브 또는 비액티브하게 한다.

HRESULT Activate(
  BOOL fActive
);

파라미터

fActive
포토를 액티브 (TRUE) 또는 비액티브 (FALSE)로 전환한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 DSERR_NODRIVER 를 돌려주어, 사운드 드라이버가 없는 것을 나타낸다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusic8::Activate ,DirectMusic 포토의 사용법


IDirectMusicPort8::Compact

DLS 또는 웨이브 테이블의 메모리를 컴팩트하게 하도록(듯이) 포토에 지시한다. 이 결과, 다운로드되는 새로운 음색이, 최대한으로 연속한 메모리체크를 이용할 수 있다.

HRESULT Compact();

파라미터

없음.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

주의

이 메소드는, 독자적인 웨이브 테이블 메모리를 관리할 필요가 있는 DLS 디바이스에만 영향을 준다. 독자적인 메모리를 관리하지 않는 포토 (호스트 시스템의 메모리를 사용하는 소프트웨어 신디사이저나 하드웨어 신디사이저)에 대해, 이 메소드는 E_NOTIMPL 를 돌려준다.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicPort8::DeviceIoControl

포토를 이행 하는 기저의 파일에 대해서 Win32 의 DeviceIoControl 함수를 호출한다.

HRESULT DeviceIoControl(
  DWORD dwIoControlCode,
  LPVOID lpInBuffer,
  DWORD nInBufferSize,
  LPVOID lpOutBuffer,
  DWORD nOutBufferSize,
  LPDWORD lpBytesReturned,
  LPOVERLAPPED lpOverlapped
);

파라미터

dwIoControlCode
실행되는 제어 코드.
lpInBuffer
입력 데이터를 보관 유지하는 버퍼.
nInBufferSize
입력 버퍼의 사이즈.
lpOutBuffer
출력 데이터를 받는 버퍼.
nOutBufferSize
출력 버퍼의 사이즈.
lpBytesReturned
출력 바이트수를 받는 변수의 주소.
lpOverlapped
비동기 처리용이 겹친 (오버랩) 구조체의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_NOTIMPL

주의

Windows 드라이버 모델 (WDM) 필터 그래프를 이행 하고 있는 포토에서만, 이 메소드는 지원 되고 있다. WDM 필터 그래프를 사용하고 있는 경우, 파일 핸들은 그래프내의 최상정도의 핀으로서 이용된다.

DirectMusic 가 필터 그래프에 대해서 실행하고 있는 조작과 핀에 대해서 정의된 커넬 스트리밍이 충돌할 가능성이 있는 경우, DirectMusic 는 커넬 스트리밍의 실행을 거부할 수 있다. 다만, 유저 정의의 조작은 결코 방해되지 않는다.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicPort8::DownloadInstrument

DLS 디바이스에 음색을 다운로드한다. 음색을 다운로드하는 것은, 음색을 구성하는 데이터를 DLS 디바이스에 건네주는 것을 의미한다. 이 안에는, 음색이 필요로 하는 아티큘레이션 데이터와 모든 웨이브가 포함된다. 웨이브의 스페이스를 절약하기 위해서, 그 범위에서 필요하게 되는 웨이브와 아티큘레이션만이 다운로드된다. 이 메소드는 IDirectMusicDownloadedInstrument8 인터페이스 포인터를 돌려주지만, 이것은 다음에 음색을 언로드하기 위해서 사용된다.

HRESULT DownloadInstrument(
  IDirectMusicInstrument *pInstrument,
  IDirectMusicDownloadedInstrument **ppDownloadedInstrument,
  DMUS_NOTERANGE *pNoteRanges,
  DWORD dwNumNoteRanges;
);

파라미터

pInstrument
다운로드하는 데이터가 속하는 음색의 IDirectMusicInstrument8 인터페이스에의 포인터.
ppDownloadedInstrument
IDirectMusicDownloadedInstrument8 인터페이스 포인터를 받는 변수의 주소.
pNoteRanges
DMUS_NOTERANGE 구조체의 배열의 주소. 배열내의 각 엔트리는, 음색이 응답해야 하는 MIDI 노트 메세지의 연속 범위를 지정한다. 음색의리젼이 다운로드되는 것은, 그 리젼내의 적어도 1 개의 노트가 DMUS_NOTERANGE 구조체로 지정되고 있는 경우에 한정된다.
dwNumNoteRanges
pNoteRanges 가 가리키는 배열내의 DMUS_NOTERANGE 구조체의 수. 이 값이 0 으로 설정되어 있는 경우,pNoteRanges 파라미터는 무시되어 이 음색의 모든 리젼과 웨이브 데이터가 다운로드된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_OUTOFMEMORY
E_NOTIMPL

주의

메모리의 낭비를 막으려면 , 음색이 불필요하게 되었을 때에,IDirectMusicPort8::UnloadInstrument 와 IDirectMusicDownloadedInstrument8::Release 의 양쪽 모두를 호출해, 언로드해야 한다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort8::Compact ,음색의 조작


IDirectMusicPort8::GetCaps

포토의 능력을 취득한다.

HRESULT GetCaps(
  LPDMUS_PORTCAPS pPortCaps
);

파라미터

pPortCaps
포토의 능력을 받는 DMUS_PORTCAPS 구조체의 주소. 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 올바르게 초기화해야 한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_INVALIDARG

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicPort8::GetChannelPriority

MIDI 채널의 우선 순위를 취득한다. 개요에 대해서는, 「채널」을 참조할것.

HRESULT GetChannelPriority(
  DWORD   dwChannelGroup,
  DWORD   dwChannel,
  LPDWORD pdwPriority
);

파라미터

dwChannelGroup
채널이 놓여져 있는 그룹.
dwChannel
그룹내의 채널의 인덱스.
pdwPriority
우선 순위를 받는 변수의 주소. 「주의」를 참조할것.

반환값

S_OK 를 돌려준다.

주의

Dmusicc.h 내에서 정의되고 있는 이하의 값은, 각각 우선 순위의 범위를 나타낸다. 우선 순위의 높은 것으로부터 순서에 리스트 한다.

DAUD_CRITICAL_VOICE_PRIORITY
DAUD_HIGH_VOICE_PRIORITY
DAUD_STANDARD_VOICE_PRIORITY
DAUD_LOW_VOICE_PRIORITY
DAUD_PERSIST_VOICE_PRIORITY

이하의 값은,DLS 레벨 1 표준에 의한, 범위내에 있어서의 채널의 디폴트 순위를 나타낸다. 우선 순위의 높은 것으로부터 순서에 리스트 한다. 퍼크션 채널의 채널 10 이, 가장 우선 순위가 높다.

DAUD_CHAN10_VOICE_PRIORITY_OFFSET
DAUD_CHAN1_VOICE_PRIORITY_OFFSET
DAUD_CHAN2_VOICE_PRIORITY_OFFSET
DAUD_CHAN3_VOICE_PRIORITY_OFFSET
DAUD_CHAN4_VOICE_PRIORITY_OFFSET
DAUD_CHAN5_VOICE_PRIORITY_OFFSET
DAUD_CHAN6_VOICE_PRIORITY_OFFSET
DAUD_CHAN7_VOICE_PRIORITY_OFFSET
DAUD_CHAN8_VOICE_PRIORITY_OFFSET
DAUD_CHAN9_VOICE_PRIORITY_OFFSET
DAUD_CHAN11_VOICE_PRIORITY_OFFSET
DAUD_CHAN12_VOICE_PRIORITY_OFFSET
DAUD_CHAN13_VOICE_PRIORITY_OFFSET
DAUD_CHAN14_VOICE_PRIORITY_OFFSET
DAUD_CHAN15_VOICE_PRIORITY_OFFSET
DAUD_CHAN16_VOICE_PRIORITY_OFFSET

채널의 우선 순위는, 범위와 오프셋(offset)를 사용해 나타낸다. 예를 들어, DAUD_STANDARD_VOICE_PRIORITY 와 DAUD_CHAN10_VOICE_PRIORITY 를 조합하는 것으로, 표준 범위내에서 가장 높은 우선 순위를 나타낸다. 표준 범위내의 우선 순위는, Dmusicc.h 내의 DAUD_CHAN1_DEF_VOICE_PRIORITY 로 시작되는 정의로 나타내진다.

같은 우선 순위값을 가지는 채널은, 소속하는 채널 그룹의 종류에 관계없이, 같은 우선 순위를 가진다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort8::SetChannelPriority


IDirectMusicPort8::GetFormat

IDirectMusic8::CreatePort 에 건네주는 DMUS_PORTPARAMS8 구조체로 지정되는 웨이브 포맷에 관한 정보, 및 웨이브 출력으로 사용하는 버퍼의 추천 사이즈에 관한 정보를 취득한다. 이러한 정보를 사용해, 포토용으로 호환성이 있는 DirectSound 버퍼를 생성 할 수 있다.

HRESULT GetFormat(
  LPWAVEFORMATEX pWaveFormatEx,
  LPDWORD pdwWaveFormatExSize
  LPDWORD pdwBufferSize
);

파라미터

pWaveFormatEx
포맷에 관한 정보를 받는 WAVEFORMATEX 구조체의 주소. 이 값은 NULL 이라도 좋다. 「주의」를 참조할것.
pdwWaveFormatExSize
구조체의 사이즈를 지정 또는 취득하는 변수의 주소. 「주의」를 참조할것.
pdwBufferSize
DirectSound 버퍼의 추천 사이즈를 받는 변수의 주소.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

WAVEFORMATEX 구조체는, 포맷의 상세하게 응해 가변장으로도 된다. 포맷의 기술을 취득하기 전에, 어플리케이션은, 이 메소드를 호출해,pWaveFormatEx 파라미터에 NULL 를 지정하는 것에 의해, 신디사이저 오브젝트에 대해서 포맷의 사이즈에 관한 문의를 실시하지 않으면 안 된다. 구조체의 사이즈는,pdwWaveFormatExSize 가 가리키는 변수에 돌려주어진다. 다음에 어플리케이션은, 충분한 메모리를 할당해GetFormat 를 재차 호출해, 포맷의 기술을 취득할 수 있다.

pWaveFormatEx 가 NULL 가 아닌 경우, DirectMusic 는, 가능한 한 많은 pdwWaveFormatExSize 바이트를 구조체에 기입한다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort8::SetDirectSound


IDirectMusicPort8::GetLatencyClock

포토의 지연 시간 클락에의 IReferenceClock 인터페이스 포인터를 취득한다. 이 지연 시간 클락은, 메세지를 연주할 수 있는, 현재에 가장 가까운 장래의 타임을 지정한다. 지연 시간 클락은,IDirectMusic8::SetMasterClock 메소드에 의해 설정되는 DirectMusic master clock에 근거하고 있다.

HRESULT GetLatencyClock(
  IReferenceClock** ppClock
);

파라미터

ppClock
지연 시간 클락의 IReferenceClock 인터페이스 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

COM 의 규칙에 따라,GetLatencyClock 는 돌려주어진 인터페이스의 참조 카운트를 늘린다. 그 때문에, 어플리케이션은 어떠한 시점에서 IReferenceClock 인터페이스에 대해서 Release 를 호출하지 않으면 안 된다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

지연 시간과 범퍼 시간


IDirectMusicPort8::GetNumChannelGroups

포토 위에의 채널 그룹의 수를 취득한다.

HRESULT GetNumChannelGroups(
  LPDWORD pdwChannelGroups
);

파라미터

pdwChannelGroups
채널 그룹의 수를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort8::SetNumChannelGroups ,채널


IDirectMusicPort8::GetRunningStats

신디사이저 상태에 관한 정보를 취득한다.

HRESULT GetRunningStats(
  LPDMUS_SYNTHSTATS pStats
);

파라미터

pStats
신디사이저의 동작 통계를 받는 DMUS_SYNTHSTATS8 구조체의 주소. 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 올바르게 초기화해야 한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_INVALIDARG
E_NOTIMPL

주의

일부의 하드웨어 신디사이저는, 포토가 비액티브하게 되어 있어도, 동작 통계를 계속 보고하는 일이 있다.

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicPort8::PlayBuffer

각 포토의 재생 버퍼에의 삽입을 실시한다.

HRESULT PlayBuffer(
  LPDIRECTMUSICBUFFER pBuffer
);

파라미터

pBuffer
포토의 재생 큐에 추가되는 버퍼의 IDirectMusicBuffer8 인터페이스 포인터의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

주의

이 버퍼가 시스템에 의해 사용되는 것은 이 메소드의 지속중 뿐이어서, 이 메소드로부터 제어가 돌아온 후는 재이용할 수 있다.

IDirectMusicBuffer8::SetStartTime 메소드에 의해 시작 타임이 설정되어 있지 않은 경우,IDirectMusicBuffer8::PackStructured 메소드 또는 IDirectMusicBuffer8::PackUnstructured 메소드에 의해 설정되는, 버퍼내의 가장 빠른 이벤트의 타임이 시작 타임이 된다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer8 ,IDirectMusic8::CreateMusicBuffer


IDirectMusicPort8::Read

수신한 MIDI 데이터를 버퍼로 설정한다. read에 이용할 수 있는 데이터가 없어질 때까지, 새로운 버퍼 오브젝트에 대해서 이 메소드를 호출해야 하는 것이다.

HRESULT Read(
  LPDIRECTMUSICBUFFER pBuffer
);

파라미터

pBuffer
수신한 MIDI 데이터를 설정하는 버퍼 오브젝트의 IDirectMusicBuffer8 인터페이스 포인터의 주소.

반환값

성공했을 경우는 S_OK 또는 S_FALSE를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_NOTIMPL

주의

읽어들이는 데이터가 존재하지 않는 경우, 이 메소드는 S_FALSE 를 돌려준다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

MIDI 의 캡춰


IDirectMusicPort8::SetChannelPriority

MIDI 채널의 우선 순위를 설정한다. 개요에 대해서는, 「채널」을 참조할것.

HRESULT SetChannelPriority(
  DWORD  dwChannelGroup,
  DWORD  dwChannel,
  DWORD  dwPriority
);

파라미터

dwChannelGroup
채널이 놓여져 있는 그룹. 이 값은 1 이상이 아니면 안된다.
dwChannel
그룹내의 채널의 인덱스.
dwPriority
우선 순위. 「IDirectMusicPort8::GetChannelPriority 」의 「주의」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_NOTIMPL

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort8::GetChannelPriority ,DMUS_CHANNEL_PRIORITY_PMSG


IDirectMusicPort8::SetDirectSound

포토의 웨이브 데이터가 스트림화 되는 디폴트의 DirectSound 오브젝트 또는 버퍼, 혹은 그 양쪽 모두를 덧쓰기하기 위해서 사용된다. 또, DirectSound 로부터 포토의 접속을 해제할 때에도 사용된다.

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  LPDIRECTSOUNDBUFFER pDirectSoundBuffer
);

파라미터

pDirectSound
포토의 접속처가 되는 DirectSound 오브젝트의 IDirectSound8 인터페이스의 주소. 기존의 DirectSound 오브젝트의 접속을 해제해, 해방하는 경우는 NULL 를 지정한다.
pDirectSoundBuffer
포토의 접속처인 IDirectSoundBuffer8 인터페이스의 주소. NULL 이라도 좋다. pDirectSound 가 NULL 인 경우는 이 값도 NULL 가 아니면 안된다. 포토가 DirectX 8.0 이후의 버젼의 Microsoft 의 소프트웨어 신디사이저인 경우는, 이 파라미터를 사용하지 않는다.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_NOBUFFERCONTROL 를 돌려준다. 「주의」를 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_ALREADY_ACTIVATED
E_INVALIDARG

주의

유효한 포인터가 pDirectSoundBuffer 에게 건네지면(자), 빵이나 볼륨등의 버퍼내에서의 컨트롤 체인지가 DirectMusic 의 재생에 영향을 주지 않는 경우, 이 메소드는 DMUS_S_NOBUFFERCONTROL 를 돌려준다. 이것은, Windows 드라이버 모델 (WDM) 포토인 만큼 영향을 준다.

포토를 액티브하게 하면, 필요에 따라서 DirectSound 프라이머리 버퍼가 업그레이드 되어 이 포토 (IDirectMusic8::CreatePort 에게 건네지는 DMUS_PORTPARAMS8 구조체로 지정한다)의 샘플링 레이트와 채널 정보를 지원 한다.

pDirectSoundBuffer 가 가리키는 버퍼는, 이 포토의 샘플링 레이트와 채널 정보에 일치하는 포맷을 가지는, 세칸다리스트리밍밧파가 아니면 안된다. 이 파라미터가 NULL 의 경우, 적절한 IDirectSoundBuffer 인스턴스가 내부적으로 생성 된다.

포토를 일단 액티브하게 하면(자),IDirectSound 도 IDirectSoundBuffer 도 변경할 수 없다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort8::Activate ,IDirectMusicPort8::GetFormat


IDirectMusicPort8::SetNumChannelGroups

어플리케이션이 포토상에서 필요로 하는 채널 그룹의 수를 변경한다.

HRESULT SetNumChannelGroups(
  DWORD dwChannelGroups
);

파라미터

dwChannelGroups
어플리케이션이 이 포토에 할당하고 싶은 채널 그룹의 수.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort8::GetNumChannelGroups ,채널


IDirectMusicPort8::SetReadNotificationHandle

IDirectMusicPort8::Read 메소드를 사용해 MIDI 메세지를 읽어들일 수 있게 되었을 때에 설정되는 이벤트를 지정한다. 새로운 데이터가 이용 가능하게 되면(자), 반드시 이벤트의 시그널이 송신된다. 이벤트 통지를 무효로 하려면 ,hEvent 파라미터의 값으로서 NULL 를 지정해,SetReadNotificationHandle 를 호출한다.

HRESULT SetReadNotificationHandle(
  HANDLE hEvent
);

파라미터

hEvent
Win32 CreateEvent 함수를 호출했을 때에 취득한 이벤트 핸들. 포토가 해방되면(자), 어플리케이션이 이 핸들을 닫지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_DMUSIC_RELEASED
E_NOTIMPL

주의

E_NOTIMPL 는, 그 포토가 입력 포토가 아닌 것을 의미하는 반환값을 돌려주는 경우도 있다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

MIDI 의 캡춰


IDirectMusicPort8::UnloadInstrument

이전에 다운로드한 DLS 음색을 언로드한다.

HRESULT UnloadInstrument(
  IDirectMusicDownloadedInstrument *pDownloadedInstrument
);

파라미터

pDownloadedInstrument
IDirectMusicPort8::DownloadInstrument 메소드를 호출하는 것으로, 음색을 다운로드했을 때에 취득된,IDirectMusicDownloadedInstrument8 인터페이스의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_DOWNLOADED_TO_PORT
E_POINTER
E_NOTIMPL

주의

IDirectMusicPort8::DownloadInstrument 에 의해 할당할 수 있었던 메모리를 해방하려면 , 이 메소드를 호출하지 않으면 안 된다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

음색의 조작


IDirectMusicPortDownload8

IDirectMusicPortDownload8 인터페이스를 사용하면(자), 어플리케이션은 DLS 다운로드를 지원 하고 있는 포토와 직접 통신해, 메모리체크를 포토에 직접 다운로드할 수 있다. 이 인터페이스가 주로 사용되는 것은, DLS 음색을 직접 편집하는 어플리케이션을 오쏘링 하면나무이다. 개요에 대해서는, 「하위 레벨 DLS 」를 참조할것.

IDirectMusicPortDownload8 을 취득하려면 ,IDirectMusicPort8:: QueryInterface 메소드를 호출해, IID_IDirectMusicPortDownload8 를 인터페이스 GUID 로서 건네준다. 포토가 DLS 다운로드를 지원 하고 있지 않는 경우, 이 메소드는 실패한다.

IDirectMusicPortDownload8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

버퍼 관리 | AllocateBuffer
 | GetAppend
 | GetBuffer
 | GetDLId
로드 | Download
 | Unload

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICPORTDOWNLOAD8 형은, 이 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicPortDownload8 *LPDIRECTMUSICPORTDOWNLOAD8;

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicPortDownload8::AllocateBuffer

DLS 데이터를 포토에 다운로드하기 위한 메모리체크를 할당해 이 버퍼에의 액세스를 가능하게 하는 IDirectMusicDownload8 인터페이스 포인터를 돌려준다.

HRESULT AllocateBuffer(
  DWORD dwSize,
  IDirectMusicDownload** ppIDMDownload
);

파라미터

dwSize
요구하는 버퍼의 사이즈.
ppIDMDownload
IDirectMusicDownload8 인터페이스 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_INVALIDARG
E_OUTOFMEMORY

주의

버퍼를 할당한 후에, 그 사이즈를 변경할 수 없다.

IDirectMusicDownload8 인터페이스를 해방 하면, 버퍼도 해방된다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPortDownload8::GetBuffer ,하위 레벨 DLS


IDirectMusicPortDownload8::Download

웨이브 또는 음색의 정의를 포토에 다운로드한다. 최초로 IDirectMusicPortDownload8::AllocateBuffer 메소드를 사용해, 메모리를 할당하지 않으면 안 된다.

HRESULT Download(
  IDirectMusicDownload* pIDMDownload
);

파라미터

pIDMDownload
버퍼용의 IDirectMusicDownload8 인터페이스의 주소.

반환값

반환값은 포토의 이행에 의해 정해진다.

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_FAIL
DMUS_E_ALREADY_DOWNLOADED
DMUS_E_BADARTICULATION
DMUS_E_BADINSTRUMENT
DMUS_E_BADOFFSETTABLE
DMUS_E_BADWAVE
DMUS_E_BADWAVELINK
DMUS_E_BUFFERNOTSET
DMUS_E_NOARTICULATION
DMUS_E_NOTMONO
DMUS_E_NOTPCM
DMUS_E_UNKNOWNDOWNLOAD

주의

다운로드하는 데이터의 준비 방법에 대해서는, 「하위 레벨 DLS 」를 참조할것.

메모리를 다운로드한 후, 그 이상 무엇인가를 실시할 수 없다. 다운로드를 갱신하려면 , 새로운 버퍼를 생성 해,IDirectMusicPortDownload8::GetDLId 메소드를 사용해 취득한 새로운 다운로드 ID 를 할당해 그 ID 를 송신해야 한다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPortDownload8::Unload ,DMUS_DOWNLOADINFO ,DMUS_OFFSETTABLE


IDirectMusicPortDownload8::GetAppend

포토가 다운로드 버퍼의 마지막에 추가할 필요가 있는 메모리의 양을 취득한다. 포토는 이 추가 메모리를 사용해, 루프 경계에 걸쳐 데이터를 보간 할 수 있다.

HRESULT GetAppend(
  DWORD* pdwAppend
);

파라미터

pdwAppend
메모리가 필요한 추가 샘플의 수를 받는 변수의 주소. 메모리의 양은 웨이브 포맷화등 계산할 수 있다.

반환값

반환값은 포토의 이행에 의해 정해진다.

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_NOTIMPL

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicPortDownload8::GetBuffer

기존의 일의인 식별자를 지정해, 버퍼의 IDirectMusicDownload8 인터페이스 포인터를 취득한다.

HRESULT GetBuffer(
  DWORD dwDLId,
  IDirectMusicDownload** ppIDMDownload
);

파라미터

dwDLId
버퍼의 다운로드 식별자. 「DMUS_DOWNLOADINFO 」를 참조할것.
ppIDMDownload
버퍼의 IDirectMusicDownload8 인터페이스 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
DMUS_E_INVALID_DOWNLOADID
DMUS_E_NOT_DOWNLOADED_TO_PORT

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPortDownload8::GetDLId ,IDirectMusicDownload8::GetBuffer ,하위 레벨 DLS


IDirectMusicPortDownload8::GetDLId

1 개(살) 또는 복수의 다운로드 버퍼의 시퀀셜 식별자를 취득한다.

신디사이저에 다운로드된 모든 메모리체크는, 스스로의 DMUS_DOWNLOADINFO 구조 체내에서 일의의 식별자를 보관 유지하고 있지 않으면 안 된다. GetDLId 메소드는, 2 개의 다운로드가 같은 식별자를 가지고 있지 않은 것을 보증한다.

HRESULT GetDLId(
  DWORD* pdwStartDLId,
  DWORD dwCount
);

파라미터

pdwStartDLId
최초의 식별자를 받는 변수의 주소.
dwCount
예약되는 식별자의 수. 일련의 체크 전체를 한 번에 다운로드하도록(듯이) 계획도 할 수 있다. 체크 마다 GetDLId 를 호출하는 대신에,dwCount 를 체크수로 설정한다. GetDLId 는 세트의 최초의 ID 를 돌려주어,*pdwStartDLId 와 dwCount 까지의 범위에서 다른 식별자가 자동적으로 예약된다. 그 이후 GetDLId 를 호출하면, 지금까지의 예약값은 날아간다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_INVALIDARG

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPortDownload8::GetBuffer ,하위 레벨 DLS


IDirectMusicPortDownload8::Unload

이전에 IDirectMusicPortDownload8::Download 를 사용해 다운로드된 버퍼를 언로드한다.

HRESULT Unload(
  IDirectMusicDownload* pIDMDownload
);

파라미터

pIDMDownload
버퍼용의 IDirectMusicDownload8 인터페이스의 주소.

반환값

반환값은 포토의 이행에 의해 정해진다.

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_NOINTERFACE
DMUS_E_SYNTHNOTCONFIGURED

동작환경

헤더 : dmusicc.h 로 선언.


IDirectMusicScript8

IDirectMusicScript8 인터페이스는, 어플리케이션이 설정이나 취득을 실시할 수 있는 변수, 및 어플리케이션이 호출할 수가 있는 루틴을 보관 유지하는 스크립트를 나타낸다.

보통, 이 인터페이스는, 스크립트 파일을 로드하는 IDirectMusicLoader8::GetObject 를 사용해 취득된다. 그 후, 어플리케이션은 IDirectMusicScript8::Init 를 호출해, 실제의 재생을 실행하는 DirectMusicPerformance 오브젝트에 스크립트를 관련짓는다.

IDirectMusicScript8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

초기화 | Init
루틴 호출 | CallRoutine
열거 | EnumRoutine
 | EnumVariable
변수의 취득 | GetVariableObject
 | GetVariableNumber
 | GetVariableVariant
변수의 설정 | SetVariableNumber
 | SetVariableObject
 | SetVariableVariant

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.

참조

오디오 스크립트의 사용법


IDirectMusicScript8::CallRoutine

스크립트내의 루틴을 실행한다.

HRESULT CallRoutine(
  WCHAR *pwszRoutineName,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

파라미터

pwszRoutineName
루틴의 이름.
pErrInfo
에러가 발생했을 경우에, 정보를 받는 DMUS_SCRIPT_ERRORINFO 구조체의 주소. 에러 정보가 필요하지 않은 경우는, 이 멤버에 NULL 를 설정한다.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_GARBAGE_COLLECTED 를 돌려준다. 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_ERROR_IN_SCRIPT
DMUS_E_SCRIPT_ROUTINE_NOT_FOUND
E_POINTER

주의

루틴의 실행이 종료할 때까지는, 어플리케이션에 제어가 돌아가지 않는다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicScript8::EnumRoutine

스크립트내의 루틴의 이름을 취득한다. 이 메소드는, 스크립트내의 모든 루틴을 열거할 필요가 있는 뮤직 오쏘링 어플리케이션이 사용한다.

HRESULT EnumRoutine(
  DWORD dwIndex,
  WCHAR *pwszName
);

파라미터

dwIndex
루틴의 0 으로부터 시작되는 인덱스.
pwszName
루틴의 이름을 받는 캐릭터 라인 버퍼에의 포인터. 적어도 MAX_PATH 요소를 포함할 필요가 있다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 루틴이 열거되었다.
S_FALSE | 지정된 인덱스값을 가지는 루틴이 없다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.
DMUS_S_STRING_TRUNCATED | 이름이 MAX_PATH 보다 길다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DMUS_E_NOT_INIT
E_POINTER

주의

다음의 샘플은,pScript 가 유효한 IDirectMusicScript8 인터페이스 포인터이며, 스크립트내의 모든 루틴의 인덱스와 이름을 표시한다.

WCHAR wszRoutineName[MAX_PATH];
int i = 0;
while (S_OK == pScript->EnumRoutine(i++, wszRoutineName))
    printf("Routine number %d is called %S\n", i, wszRoutineName);

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicScript8::EnumVariable


IDirectMusicScript8::EnumVariable

스크립트내의 변수의 이름을 취득한다. 이 메소드는, 스크립트내의 모든 변수를 열거할 필요가 있는 뮤직 오쏘링 어플리케이션이 사용한다.

HRESULT EnumVariable(
  DWORD dwIndex,
  WCHAR *pwszName
);

파라미터

dwIndex
변수의 0 으로부터 시작되는 인덱스.
pwszName
변수의 이름을 받는 캐릭터 라인 버퍼의 주소. 적어도 MAX_PATH 요소를 포함할 필요가 있다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 루틴이 열거되었다.
S_FALSE | 지정된 인덱스값을 가지는 루틴이 없다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.
DMUS_S_STRING_TRUNCATED | 이름이 MAX_PATH 보다 길다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DMUS_E_NOT_INIT

주의

다음의 샘플은,pScript 가 유효한 IDirectMusicScript8 인터페이스 포인터이며, 스크립트내의 모든 변수의 인덱스와 이름을 표시한다.

WCHAR wszVariableName[MAX_PATH];
int i = 0;
while (S_OK == pScript->EnumVariable(i++, wszVariableName))
    printf("Variable number %d is called %S\n", i, wszVariableName);

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicScript8::EnumRoutine


IDirectMusicScript8::GetVariableNumber

스크립트내에서 선언된 변수로부터 32 비트의 부호 첨부값을 취득한다.

HRESULT GetVariableNumber(
  WCHAR *pwszVariableName,
  LONG *plValue,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

파라미터

pwszVariableName
스크립트의 변수명.
plValue
값을 받는 변수의 주소.
pErrInfo
에러가 발생했을 경우에, 정보를 받는 DMUS_SCRIPT_ERRORINFO 구조체의 주소. 에러 정보가 필요하지 않은 경우는, 이 멤버에 NULL 를 설정한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 값이 취득되었다.
S_FALSE | 스크립트에 변수가 존재하지 않는다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DISP_E_TYPEMISMATCH ( 「Winerror.h」를 참조할것)
DMUS_E_NOT_INIT
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicScript8::SetVariableNumber


IDirectMusicScript8::GetVariableObject

스크립트내에서 선언된 변수로부터 오브젝트 포인터를 취득한다.

HRESULT GetVariableObject(
  WCHAR *pwszVariableName,
  REFIID riid,
  LPVOID FAR *ppv,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

파라미터

pwszVariableName
스크립트의 변수명.
riid
인터페이스의 일의의 식별자. Dmusici.h 로 정의되고 있는 IID 를 참조할것. 표준적인 인터페이스는 모두,"IID_" 와 인터페이스의 이름으로 구성되는 정의 끝난 식별자를 가진다. 예를 들어,IDirectMusicTrack8 의 식별자는 IID_IDirectMusicTrack8 이다.
ppv
오브젝트의 목적의 인터페이스에의 포인터를 받는 변수의 주소.
pErrInfo
에러가 발생했을 경우에, 정보를 받는 DMUS_SCRIPT_ERRORINFO 구조체의 주소. 에러 정보가 필요하지 않은 경우는, 이 멤버에 NULL 를 설정한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 값이 취득되었다.
S_FALSE | 스크립트에 변수가 존재하지 않는다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_NOINTERFACE
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicScript8::SetVariableObject


IDirectMusicScript8::GetVariableVariant

스크립트내에서 선언된 변수로부터 변형값을 취득한다.

HRESULT GetVariableVariant(
  WCHAR *pwszVariableName,
  VARIANT *pvarValue,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

파라미터

pwszVariableName
스크립트의 변수명.
pvarValue
값을 받는 변수의 주소.
pErrInfo
에러가 발생했을 경우에, 정보를 받는 DMUS_SCRIPT_ERRORINFO 구조체의 주소. 에러 정보가 필요하지 않은 경우는, 이 멤버에 NULL 를 설정한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 값이 취득되었다.
S_FALSE | 스크립트에 변수가 존재하지 않는다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_UNSUPPORTED_VARTYPE
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicScript8::SetVariableVariant


IDirectMusicScript8::Init

사운드를 연주하는 퍼포먼스에 스크립트를 관련짓는다.

HRESULT Init(
  IDirectMusicPerformance *pPerformance,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

파라미터

pPerformance
퍼포먼스 오브젝트의 IDirectMusicPerformance8 인터페이스의 주소.
pErrInfo
에러가 발생했을 경우에, 정보를 받는 DMUS_SCRIPT_ERRORINFO 구조체의 주소. 에러 정보가 필요하지 않은 경우는, 이 멤버에 NULL 를 설정한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 스크립트가 초기화되었다.
S_FALSE | 스크립트가 이미 다른 퍼포먼스에 어태치 되고 있다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_ERROR_IN_SCRIPT
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER
E_NOINTERFACE

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicScript8::SetVariableNumber

스크립트내에서 선언된 변수에 32 비트의 부호 첨부값을 설정한다.

HRESULT SetVariableNumber(
  WCHAR *pwszVariableName,
  LONG lValue,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

파라미터

pwszVariableName
스크립트의 변수명.
lValue
변수에 할당하는 값.
pErrInfo
에러가 발생했을 경우에, 정보를 받는 DMUS_SCRIPT_ERRORINFO 구조체의 주소. 에러 정보가 필요하지 않은 경우는, 이 멤버에 NULL 를 설정한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 값이 설정되었다.
S_FALSE | 스크립트에 변수가 존재하지 않는다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicScript8::GetVariableNumber


IDirectMusicScript8::SetVariableObject

스크립트내에서 선언된 변수에 오브젝트 인터페이스 포인터를 설정한다.

HRESULT SetVariableObject(
  WCHAR *pwszVariableName,
  IUnknown *punkValue,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

파라미터

pwszVariableName
스크립트의 변수명.
punkValue
변수로 설정하는 인터페이스 포인터. IDirectMusicSegment8 등, 스크립트 엔진이 지원 하는 DirectMusic 오브젝트의 인터페이스, 또는 IDispatch 인터페이스를 이행 하는 그 외의 오브젝트의 인터페이스를 사용할 수 있다.
pErrInfo
에러가 발생했을 경우에, 정보를 받는 DMUS_SCRIPT_ERRORINFO 구조체의 주소. 에러 정보가 필요하지 않은 경우는, 이 멤버에 NULL 를 설정한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 값이 설정되었다.
S_FALSE | 스크립트에 변수가 존재하지 않는다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicScript8::GetVariableObject


IDirectMusicScript8::SetVariableVariant

스크립트내에서 선언된 변수에 변형값을 설정한다.

HRESULT SetVariableVariant(
  WCHAR *pwszVariableName,
  VARIANT varValue,
  BOOL fSetRef,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

파라미터

pwszVariableName
스크립트의 변수명.
varValue
변수에 할당하는 값.
fSetRef
변수가 참조에 의해 설정되는 경우는 TRUE, 값에 의해 설정되는 경우는 FALSE. 참조에 의해 설정할 수 있는 것은 오브젝트 뿐이다. 이 플래그에는, DirectMusic 오브젝트에 대해서는 항상 TRUE 를 지정해, 그 외의 변수에 대해서는 FALSE 를 지정한다.
pErrInfo
에러가 발생했을 경우에, 정보를 받는 DMUS_SCRIPT_ERRORINFO 구조체의 주소. 에러 정보가 필요하지 않은 경우는, 이 멤버에 NULL 를 설정한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 값이 설정되었다.
S_FALSE | 스크립트에 변수가 존재하지 않는다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_NOT_A_REFERENCE
DMUS_E_SCRIPT_UNSUPPORTED_VARTYPE
DMUS_E_SCRIPT_VALUE_NOT_SUPPORTED
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicScript8::GetVariableObject


IDirectMusicSegment8

IDirectMusicSegment8 인터페이스는, 세그먼트(segment), 즉 복수의 트럭으로 구성되는 음악의 부품을 나타낸다. 대부분의 어플리케이션은, 뮤직 데이터를 세그먼트(segment) 레벨로 처리한다. 개요에 대해서는, 「세그먼트(segment)의 사용법」을 참조할것.

DirectMusicSegment 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject8 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

IDirectMusicSegment8 는 IDirectMusicSegment 인터페이스를 계승해, 새로운 메소드를 추가한다.

IDirectMusicSegment8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

음색 | Download
 | Unload
통지 | AddNotificationType
 | RemoveNotificationType
파라미터 | GetParam
 | SetParam
타이밍과 루프 | GetDefaultResolution
 | GetLength
 | GetLoopPoints
 | GetRepeats
 | GetStartPoint
 | SetDefaultResolution
 | SetLength
 | SetLoopPoints
 | SetRepeats
 | SetStartPoint
툴 | GetGraph
 | SetGraph
트럭 | GetTrack
 | GetTrackGroup
 | InsertTrack
 | RemoveTrack
 | SetTrackConfig
그 외 | Clone
 | Compose
 | GetAudioPathConfig
 | InitPlay
 | SetPChannelsUsed

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicSegment8::AddNotificationType

통지 타입을 추가한다. 이 메소드는, 세그먼트(segment)가 통지에 응답할 수 있도록(듯이) 하기 위해서,IDirectMusicPerformance8::AddNotificationType 메소드에 의해 불려 간다. 세그먼트(segment)은 각 트럭의 IDirectMusicTrack8::AddNotificationType 메소드를 호출한다.

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
추가되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). 정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것. 어플리케이션은, 커스텀 트랙에 도착해 독자적인 타입을 정의할 수 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

버퍼의 내용은 DirectSound 에 의해 초기화되지 않는다. 어플리케이션은, 버퍼에 무음이 포함되면(자) 상정할 수 없다.

하드웨어 가속화를 이용할 수 없는 시스템으로 DSBCAPS_LOCHARDWARE 플래그를 사용해 버퍼를 생성 하려고 하면(자), 메소드는 실패해, Windows 95 및 Windows 98 에서는 DSERR_CONTROLUNAVAIL 를 돌려준다. Windows 2000 에서는 DSERR_INVALIDCALL 를 돌려준다.

S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_OUTOFMEMORY

주의

세그먼트(segment)는, 타입 GUID_NOTIFICATION_PERFORMANCE 의 통지를 생성할 수 없다. 이 타입의 통지를 취득하려면 ,IDirectMusicPerformance8::AddNotificationType 을 호출하지 않으면 안 된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리


IDirectMusicSegment8::Clone

세그먼트(segment)와 그 중의 트럭의 모두 또는 파트를 카피한다.

HRESULT Clone(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  IDirectMusicSegment** ppSegment
);

파라미터

mtStart
카피 시작 파트. 0 미만의 경우나, 세그먼트(segment)의 길이를 넘는 경우는, 0 이 사용된다.
mtEnd
카피 종료 파트. 이 값이 세그먼트(segment)의 최후를 넘는 경우는, 세그먼트(segment)의 끝까지 카피된다. 0, 또는 mtStart 미만의 경우도, 끝까지 카피된다.
ppSegment
생성 된 세그먼트(segment)의 IDirectMusicSegment 인터페이스에의 포인터를 받는 변수의 주소. IDirectMusicSegment8 를 취득하려면 ,QueryInterface 를 사용한다. 어플리케이션에는, 세그먼트(segment)의 종료시에 Release 를 호출할 책임이 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 일부의 트럭의 카피에 실패했을 경우는 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_OUTOFMEMORY
E_POINTER

주의

시작 포인트, 루프 포인트, 반복 회수, 툴 그래프, 디폴트의 오디오 패스 등, 오리지날의 세그먼트(segment)의 프로퍼티가 클론에 카피된다.

스타일 베이스의 세그먼트(segment)는,mtStart 가 0 보다 큰 경우, 소절 경계상에 없으면 안 된다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicSegment8::Compose

DMUS_TRACKCONFIG_COMPOSING 플래그의 설정된 모든 트럭을 어레인지 해, 어레인지 끝난 트럭을 이 세그먼트(segment), 또는 이 세그먼트(segment)의 클론에 배치한다.

HRESULT Compose(
  MUSIC_TIME mtTime,
  IDirectMusicSegment* pFromSegment,
  IDirectMusicSegment* pToSegment,
  IDirectMusicSegment** ppComposedSegment
);

파라미터

mtTime
트란지션을 어레인지 하는 pFromSegment 의 현재 타임을 지정하는 MUSIC_TIME 타입의 값. pFromSegment 가 NULL 의 경우는 0 을 설정한다.
pFromSegment
트란지션으로 연결되는 세그먼트(segment)를 지정하는,IDirectMusicSegment8 인터페이스에의 포인터. 호출원세그먼트(segment)가 트란지션이 아닌 경우는 NULL.
pToSegment
트란지션에 계속되는 세그먼트(segment)를 지정하는,IDirectMusicSegment8 인터페이스에의 포인터. 호출원세그먼트(segment)가 트란지션이 아닌 경우, 또는 트란지션이 엔딩인 경우는 NULL.
ppComposedSegment
어레인지가 끝난 세그먼트(segment)의 IDirectMusicSegment8 인터페이스 포인터를 받는 변수의 주소. 호출원세그먼트(segment)를 재어레인지 하는 경우는 NULL.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_FAIL
E_OUTOFMEMORY
E_POINTER

주의

포인터의 파라미터가 모두 NULL 인 경우, 세그먼트(segment)은 그 모든 트럭에 대해서 IDirectMusicTrack8::Compose 를 호출한다. 어레인지에 필요한 다른 트럭을 찾고 있는 어레인지 트럭의 경우, 필요한 트럭이 발견되면(자), DMUS_E_NOT_FOUND 를 돌려준다.

ppComposedSegment 가 NULL 가 아닌 경우, 이 메소드는, 재어레인지 한 트럭을 보관 유지하는 오리지날 세그먼트(segment)의 클론을 생성 한다. pFromSegment 또는 pToSegment 의 어느쪽이나 NULL 가 아닌 경우, 호출원세그먼트(segment)는 트란지션이라고 상정되어 브랙킷 첨부의 세그먼트(segment)를 참조하는 헤더만을 보관 유지하는 트럭이 포함되어 있다고 생각된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicTrack8::Compose ,IDirectMusicSegment8::SetTrackConfig


IDirectMusicSegment8::Download

밴드 데이터를 퍼포먼스 또는 오디오 패스에 다운로드한다.

HRESULT Download(
  IUnknown *pAudioPath
);

파라미터

pAudioPath
데이터를 받는 퍼포먼스나 오디오 패스의 IUnknown 인터페이스에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND
E_POINTER

주의

세그먼트(segment)내의 모든 밴드와 웨이브 데이터가 다운로드된다.

세그먼트(segment)를 해방하기 전에, 반드시 IDirectMusicSegment8::Unload 를 호출하는 것.

동작환경

헤더 : dmusici.h 로 선언.

참조

밴드의 사용법


IDirectMusicSegment8::GetAudioPathConfig

세그먼트(segment)에 파묻힌 오디오 패스 구성을 나타내는 오브젝트를 취득한다. 이 오브젝트는 IDirectMusicPerformance8::CreateAudioPath 에 건네줄 수가 있다.

HRESULT GetAudioPathConfig(
  IUnknown ** ppAudioPathConfig
);

파라미터

ppAudioPathConfig
오디오 패스 구성 오브젝트의 IUnknown 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NO_AUDIOPATH_CONFIG
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicSegment8::GetDefaultResolution

동기용의 디폴트의 분해가능을 취득한다.

HRESULT GetDefaultResolution(
  DWORD* pdwResolution
);

파라미터

pdwResolution
디폴트의 분해가능을 받는 변수의 주소. 「DMUS_SEGF_FLAGS 」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetDefaultResolution ,세그먼트(segment)의 타이밍


IDirectMusicSegment8::GetGraph

세그먼트(segment)의 툴 그래프를 취득한다.

HRESULT GetGraph(
  IDirectMusicGraph** ppGraph
);

파라미터

ppGraph
툴 그래프에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

세그먼트(segment)내에 그래프가 존재하지 않는 경우, 이 메소드는 DMUS_E_NOT_FOUND 를 돌려준다.

툴 그래프의 참조 카운트는 인크리먼트(increment) 된다.

동작환경

헤더 : dmusici.h 으로 선언.

참조

IDirectMusicSegment8::SetGraph


IDirectMusicSegment8::GetLength

세그먼트(segment)의 길이를 취득한다.

HRESULT GetLength(
  MUSIC_TIME* pmtLength
);

파라미터

pmtLength
뮤직 타임에 나타내진 세그먼트(segment)의 길이를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

웨이브 파일로부터 생성 된 세그먼트(segment)의 경우, 이 메소드는 항상 *pmtLength f에 1 을 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetLength


IDirectMusicSegment8::GetLoopPoints

세그먼트(segment)내의 시작 포인트와 루프 포인트를 취득한다. 이러한 2 개의 포인트의 사이에,IDirectMusicSegment8::SetRepeats 메소드로 설정된 회수만 반복된다.

HRESULT GetLoopPoints(
  MUSIC_TIME* pmtStart,
  MUSIC_TIME* pmtEnd
);

파라미터

pmtStart
루프의 시작 포인트를 받는 변수의 주소.
pmtEnd
루프의 종료 포인트를 받는 변수의 주소. 값 0 은, 세그먼트(segment) 전체를 루프 시키는 것을 의미한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetLoopPoints ,세그먼트(segment)의 타이밍


IDirectMusicSegment8::GetParam

이 세그먼트(segment) 내부의 트럭으로부터 데이터를 취득한다.

HRESULT GetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

파라미터

rguidType
취득되는 데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
dwGroupBits
희망의 트럭이 놓여져 있는 그룹. 모든 그룹을 지정하려면 , 이 값을 0xFFFFFFFF 로 설정한다. 상세한 것에 대하여는, 「트럭의 식별」을 참조할것.
dwIndex
데이터를 취득하는 원이 되는,dwGroupBits 로 식별되는 그룹내의 트럭의 인덱스. 파라미터를 보관 유지하는 최초의 트럭을 찾아내려면 , DMUS_SEG_ANYTRACK 를 지정한다.
mtTime
데이터의 취득을 실시하는 타임.
pmtNext
데이터가 무효가 되는 세그먼트(segment) 타임 (mtTime 로부터의 상대 타임)을 받는 변수의 주소. 이 변수가 값 0 을 돌려주었을 경우, 데이터가 항상 유효하게 되어 있는지, 데이터가 무효가 되는 타임이 불명한 것을 의미한다. 이 정보가 불필요한 경우는,pmtNext 를 NULL 로 설정해도 괜찮다. 「주의」를 참조할것.
pParam
돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 이 구조체는,rguidType 로 식별된 데이터형에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_GET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

주의

다른제어 세그먼트(segment)가 삽입되는 경우,*pmtNext 로 돌려주어지는 타임의 전에 데이터가 무효가 되는 일이 있다. 상세한 것에 대하여는, 「제어 세그먼트(segment)」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,퍼포먼스 파라미터


IDirectMusicSegment8::GetRepeats

세그먼트(segment)의 루프 부분으로 설정된 반복 회수를 취득한다.

HRESULT GetRepeats(
  DWORD* pdwRepeats
);

파라미터

pdwRepeats
세그먼트(segment)의 루프 부분으로 설정되어 있는 반복 회수를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetRepeats


IDirectMusicSegment8::GetStartPoint

세그먼트(segment)의 연주가 시작 된, 또는 지금부터 시작 되는 포인트를 취득한다.

HRESULT GetStartPoint(
  MUSIC_TIME* pmtStart
);

파라미터

pmtStart
세그먼트(segment)의 연주 시작 타임을 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetStartPoint


IDirectMusicSegment8::GetTrack

지정된 타입, 그룹, 및 인덱스에 일치하는 트럭을 트럭 리스트로부터 검색해, DirectMusicTrack 오브젝트에의 포인터를 취득한다.

HRESULT GetTrack(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  IDirectMusicTrack** ppTrack
);

파라미터

rguidType
검색하는 트럭의 클래스 식별자에의 참조 (C++) 또는 주소 (C). 값으로서 GUID_NULL 를 지정 하면, 임의의 트럭을 취득한다. 트럭 식별자에 대해서는, 「표준 트럭의 종류」를 참조할것.
dwGroupBits
검색되는 트럭을 포함한 트럭 그룹. 값 0 은 무효이다. dwGroupBits 내의 각 비트는, 1 개의 트럭 그룹에 대응한다. 그룹 에 관계없이 모든 트럭을 검색하려면 , 이 파라미터를 0xFFFFFFFF 로 설정한다.
dwIndex
rguidType 타입, 게다가 dwGroupBits 에 일치하기 위해서 돌려주어진 그룹으로부터 1 개의 트럭을 식별하기 위해서 사용되는, 0 으로부터 시작되는 인덱스. dwGroupBits 로 복수의 그룹이 선택되고 있는 경우, 선택된 그룹의 집합 중(안)에서 발견된 pCommandGuid 타입으로부터, 이 인덱스는 n 번째의 트럭을 지정한다. 「주의」를 참조할것.
ppTrack
트럭에의 포인터를 받는 변수의 주소. 트럭이 발견되지 않았던 경우, 이 변수는 NULL 로 설정된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_FAIL
E_POINTER

주의

모든 트럭을 열거하려면 ,rguidType 에 GUID_NULL,dwGroupBits 에 0xFFFFFFFF 를 지정한다. 처음은 dwIndex 를 0 으로 설정해 GetTrack 를 호출해, 메소드가 성공 코드를 돌려주지 않게 될 때까지 dwIndex 를 인크리먼트(increment) 해 호출을 계속한다.

DirectMusic Producer 로 생성 되는 세그먼트(segment)의 트럭은, 반드시 어플리케이션과 같은 순서일 필요는 없다. 특정의 트럭의 검색을 dwIndex 인 만큼 의지하지 않는 것.

트럭 그룹의 상세한 것에 대하여는, 「트럭의 식별」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::InsertTrack


IDirectMusicSegment8::GetTrackGroup

세그먼트(segment)내의 트럭에 대해서 설정된 그룹 비트를 취득한다.

HRESULT GetTrackGroup(
  IDirectMusicTrack* pTrack,
  DWORD* pdwGroupBits
);

파라미터

pTrack
그룹 비트의 검색 대상이 되는 트럭.
pdwGroupBits
그룹을 받는 변수의 주소. *pdwGroupBits 내의 각 비트는, 1 개의 트럭 그룹에 대응한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_INVALIDARG

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::InsertTrack ,트럭의 식별


IDirectMusicSegment8::InitPlay

연주 상태를 초기화한다. 이 메소드는 내부적으로 사용되는 것이어, DirectX 7.0 보다 후의 버젼에는 이행되어 있지 않다.

HRESULT InitPlay(
  IDirectMusicSegmentState** ppSegState,
  IDirectMusicPerformance* pPerformance,
  DWORD dwFlags
);

파라미터

ppSegState
IDirectMusicSegmentState8 인터페이스에의 포인터를 받는 변수의 주소. 이 인터페이스는 이 메소드를 호출했을 때에 생성 되어 상태 데이터를 보관 유지하기 위해서 사용된다. 참조 카운트가 1 이 되어 돌려주어지므로,Release 메소드를 호출하면, 이 인터페이스는 완전하게 해방된다.
pPerformance
IDirectMusicPerformance8 인터페이스의 주소. 퍼포먼스 오브젝트에 대해서 이 메소드를 호출하기 위해서(때문에), 세그먼트(segment)와 세그먼트(segment) 상태는 이 인터페이스를 필요로 한다.
dwFlags
트럭의 동작을 변경하는 DMUS_SEGF_FLAGS .

반환값

DirectX 8.0 이후에서는 E_NOTIMPL 를 돌려준다.

그 이전의 버젼에서는, 성공했을 경우는 S_OK 를 돌려준다. 실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_OUTOFMEMORY

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicSegment8::InsertTrack

지정된 트럭을, 세그먼트(segment)의 트럭의 리스트에 삽입한다.

HRESULT InsertTrack(
  IDirectMusicTrack* pTrack,
  DWORD dwGroupBits
);

파라미터

pTrack
세그먼트(segment)에 추가되는 트럭.
dwGroupBits
트럭의 삽입처가 되는, 1 개(살) 또는 복수의 그룹. 이 값은 0 으로 할 수 없다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

트럭은 서로가 올바르게 링크하도록(듯이) 그룹에서 배치된다. 예를 들어, 세그먼트(segment)에는, 스타일 트럭과 뮤트 트럭이 각각 2 개(살) 포함되는 경우가 있다. 각 스타일 트럭은, 그것들에 관련지을 수 있고 있는 뮤트 트럭과 함께 다른 그룹에 배치된다. 트럭 그룹의 상세한 것에 대하여는, 「트럭의 식별」을 참조할것.

세그먼트(segment)가 현재 연주중의 경우, 새로운 트럭은 재생에 포함되지 않는다. 이것은, 세그먼트(segment) 상태의 초기화 시에 새로운 트럭은 포함되지 않았기 (위해)때문에이다.

이 메소드에 의해 트럭은 초기화된다. 다만, 그 이후에 트럭 데이터가 변경되는 경우, 어플리케이션은 IDirectMusicTrack8::Init 를 호출해, 트럭을 다시 초기화할 필요가 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::RemoveTrack ,IDirectMusicSegment8::GetTrackGroup


IDirectMusicSegment8::RemoveNotificationType

통지 타입을 삭제한다. 이 메소드는, 세그먼트(segment)가 통지를 삭제할 수 있도록(듯이) 하기 위해서,IDirectMusicPerformance8::RemoveNotificationType 메소드에 의해 불려 간다. 세그먼트(segment)은 각 트럭의 IDirectMusicTrack8::RemoveNotificationType 메소드를 호출한다.

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
삭제되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). (정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것). 이 값을 GUID_NULL 로 설정 하면, 모든 통지가 삭제된다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 통지 타입이 지금까지 설정되어 있지 않은 경우는 S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리


IDirectMusicSegment8::RemoveTrack

세그먼트(segment)의 트럭 리스트로부터 트럭을 삭제한다.

HRESULT RemoveTrack(
  IDirectMusicTrack* pTrack
);

파라미터

pTrack
세그먼트(segment)의 트럭 리스트로부터 삭제되는 트럭.

반환값

성공했을 경우는 S_OK 를 돌려준다. 지정된 트럭이 트럭 리스트안에 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

삭제된 트럭은 해방된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::InsertTrack


IDirectMusicSegment8::SetDefaultResolution

동기용의 디폴트의 분해가능을 설정한다.

HRESULT SetDefaultResolution(
  DWORD dwResolution
);

파라미터

dwResolution
목적의 디폴트의 분해가능. 이 값은, 0 또는 다음에 나타내는 DMUS_SEGF_FLAGS 열거형의 멤버의 언젠가이다.

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 주로 세칸다리세그먼트 (모티프)가 스스로를 소절, 박, 또는구라두의 어느 분해가능으로 동기 시키는지를 정의하기 위해서 사용된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::GetDefaultResolution ,세그먼트(segment)의 타이밍


IDirectMusicSegment8::SetGraph

세그먼트(segment)에 툴 그래프를 할당한다.

HRESULT SetGraph(
  IDirectMusicGraph* pGraph
);

파라미터

pGraph
툴 그래프의 포인터. 세그먼트(segment) 그래프를 소거하기 위해서 NULL 로 설정해도 괜찮다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

현재의 툴 그래프내에서 처리중의 메세지는 모두 삭제된다.

이 메소드는 그래프의 참조 카운트를 인크리먼트(increment) 하므로, 오리지날의 참조를 해방해 두면(자) 안전하다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SetGraph ,DirectMusic 툴


IDirectMusicSegment8::SetLength

세그먼트(segment)의 길이를 뮤직 타임 단위로 설정한다. 보통, 로더가 파일로부터 세그먼트(segment)의 길이를 취득해, 그 길이를 세그먼트(segment) 오브젝트에 건네줄 때, 로더가 이 메소드를 호출한다.

HRESULT SetLength(
  MUSIC_TIME mtLength
);

파라미터

mtLength
목적의 길이. 0 보다 큰 값이 아니면 안된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
DMUS_E_OUT_OF_RANGE

주의

프라이머리 세그먼트(segment)의 길이를 설정하지 않았던 경우는, DMUS_SEGF_QUEUE 플래그를 지정한 것 외의 프라이머리 세그먼트(segment)를 큐에 삽입할 때에 문제가 발생하는 일이 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::GetLength


IDirectMusicSegment8::SetLoopPoints

반복하는 세그먼트(segment)의 파트의 시작 포인트와 종료 포인트를 설정한다. 세그먼트(segment)의 파트는,IDirectMusicSegment8::SetRepeats 메소드에 의해 설정되는 회수만 반복한다.

HRESULT SetLoopPoints(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd
);

파라미터

mtStart
루프의 시작 포인트.
mtEnd
루프의 종료 포인트. 값 0 은, 세그먼트(segment) 전체를 루프 시키는 것을 의미한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 DMUS_E_OUT_OF_RANGE 를 돌려준다.

주의

세그먼트(segment)의 연주시에는, 시작 타임부터 mtEnd 까지 연주해,mtStart 에 루프 한다. 다음에, 루프 부분을 IDirectMusicSegment8::SetRepeats 에 의해 설정되는 회수만 반복해, 끝까지 연주한다.

디폴트값은, 최초부터 끝까지 세그먼트(segment) 전체를 루프 하도록(듯이) 설정되어 있다.

mtStart 의 값이 세그먼트(segment)의 길이 이상의 경우, 또는 mtEnd 의 값이 세그먼트(segment)의 길이를 넘는 경우, 메소드는 실패한다. mtEnd 가 0 의 경우,mtStart 도 0 이 아니면 안된다.

이 메소드는, 이 세그먼트(segment)로부터 생성 된, 현재 연주중의 세그먼트(segment) 상태에 영향을 미칠 것은 없다.

캐싱 된 세그먼트(segment)의 루프 포인트는, 세그먼트(segment)가 해방되어 재로드 되었을 경우에서도 계속된다. 세그먼트(segment)가 다음에 캐쉬로부터 재로드 되지 않게 하려면, 세그먼트(segment)를 해방하기 전에,IDirectMusicLoader8::ReleaseObject 를 호출한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::GetLoopPoints ,세그먼트(segment)의 타이밍


IDirectMusicSegment8::SetParam

이 세그먼트(segment) 내부의 트럭에 데이터를 설정한다.

HRESULT SetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  void* pParam
);

파라미터

rguidType
설정되는 데이터형에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
dwGroupBits
희망의 트럭이 놓여져 있는 그룹. 모든 그룹을 지정하려면 , 이 값을 0xFFFFFFFF 로 설정한다. 상세한 것에 대하여는, 「트럭의 식별」을 참조할것.
dwIndex
데이터를 어디로 설정하는지를 나타내는,dwGroupBits 로 식별되는 그룹내의 트럭의 인덱스. 파라미터를 저장 하는 그룹내의 모든 트럭에 파라미터를 설정하려면 , DMUS_SEG_ALLTRACKS 를 지정한다.
mtTime
데이터의 설정을 실시하는 타임.
pParam
데이터를 보관 유지하는 구조체의 주소. 데이터가 필요없는 경우는 NULL 를 지정한다. 이 구조체는,rguidType 로 식별된 데이터형에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicTrack8::SetParamEx ,퍼포먼스 파라미터


IDirectMusicSegment8::SetPChannelsUsed

이 세그먼트(segment)가 사용하는 퍼포먼스 채널을 설정한다. 이 메소드는 보통, 트럭이 어느 채널을 사용하고 있을까를 세그먼트(segment)에 통지하기 위해서 IDirectMusicTrack8::Init 메소드내에서 트럭에 의해 불려 간다.

HRESULT SetPChannelsUsed(
  DWORD dwNumPChannels,
  DWORD* paPChannels
);

파라미터

dwNumPChannels
설정되는 P 채널의 수. 이 값은,paPChannels 가 가리키는 배열내의 멤버의 수로 동일하지 않으면 안 된다.
paPChannels
P 채널의 배열에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

이 메소드를 사용하면(자), 세그먼트(segment)가 어느 포토를 사용하고 있을까를 퍼포먼스에 알릴 수가 있어 그 결과, 퍼포먼스가 워스트 케이스에 대비하는 대신에 실제의 지연 시간을 결정할 수 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

지연 시간과 범퍼 시간,채널


IDirectMusicSegment8::SetRepeats

세그먼트(segment)의 루프 부분에 반복하는 회수를 설정한다. 디폴트에서는, 세그먼트(segment) 전체가 루프 된다.

HRESULT SetRepeats(
  DWORD dwRepeats
);

파라미터

dwRepeats
세그먼트(segment)의 루프 부분이 반복되는 회수. 명시적으로 정지될 때까지 반복하려면 , DMUS_SEG_REPEAT_INFINITE 를 지정한다. 값 0 은, 한 번의 연주만으로 반복이 없는 것을 의미한다.

반환값

S_OK 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::GetRepeats ,IDirectMusicSegment8::SetLoopPoints ,세그먼트(segment)의 타이밍


IDirectMusicSegment8::SetStartPoint

세그먼트(segment)의 연주를 시작 하는 포인트를 설정한다.

HRESULT SetStartPoint(
  MUSIC_TIME mtStart
);

파라미터

mtStart
세그먼트(segment)의 연주 시작 포인트. 0 이상으로, 세그먼트(segment)의 길이보다 작지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 DMUS_E_OUT_OF_RANGE 를 돌려준다.

주의

시작 포인트는, (들)물을 수 있는 세그먼트(segment)의 최초의 포인트이다. 다만, 세그먼트(segment)의 시작 포인트가 경과시간에 맞추어 있는 경우, 실제로 들리는 최초의 포인트는, 이것보다 늦어진다. 상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것.

디폴트의 시작 포인트는 0 이며, 세그먼트(segment)의 선두로부터 시작 하는 것을 의미한다.

세그먼트(segment)가 아직 길이를 가지고 있지 않은 경우, 이 메소드의 전에 IDirectMusicSegment8::SetLength 를 호출하지 않으면 안 된다.

이 메소드는, 이 세그먼트(segment)로부터 생성 된, 현재 연주중의 세그먼트(segment) 상태에 영향을 미칠 것은 없다.

캐싱 된 세그먼트(segment)의 시작 포인트는, 세그먼트(segment)가 해방되어 재로드 되었을 경우에서도 계속된다. 세그먼트(segment)가 다음에 캐쉬로부터 재로드 되지 않게 하려면, 세그먼트(segment)를 해방하기 전에,IDirectMusicLoader8::ReleaseObject 를 호출한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::GetStartPoint ,IDirectMusicSegmentState8::GetStartPoint ,IDirectMusicSegment8::SetLength ,IDirectMusicSegment8::SetLoopPoints ,세그먼트(segment)의 타이밍


IDirectMusicSegment8::SetTrackConfig

트럭의 구성을 설정한다.

HRESULT SetTrackConfig(
  REFGUID rguidTrackClassID,
  DWORD dwGroupBits,
  DWORD dwIndex,
  DWORD dwFlagsOn,
  DWORD dwFlagsOff
);

파라미터

rguidTrackClassID
트럭 클래스의 식별자에의 참조 (C++) 또는 주소 (C). 값의 리스트에 대해서는, 「표준 트럭의 종류」를 참조할것.
dwGroupBits
트럭이 소속하는 그룹.
dwIndex
그룹내의 트럭의 인덱스, 또는 그룹내의 모든 트럭의 구성을 설정하는 DMUS_SEG_ALLTRACKS.
dwFlagsOn
설정하는 구성 플래그. 「주의」를 참조할것.
dwFlagsOff
클리어 하는 구성 플래그. 「주의」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_TRACK_NOT_FOUND
E_INVALIDARG

주의

세그먼트(segment)의 플래그를 변경 하면, 세그먼트(segment) 상태의 그 이후의 인스턴스는, 변경 내용을 계승한다. 다만, 이미 연주중인 세그먼트(segment) 상태는 동작을 변경하지 않는다.

다음의 플래그가 정의되고 있다.

DMUS_TRACKCONFIG_COMPOSING
이 트럭을 사용해, 다른 트럭을 어레인지 한다.
DMUS_TRACKCONFIG_CONTROL_ENABLED
IDirectMusicTrack8::GetParamEx 를 유효하게 한다.
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
제어 세그먼트(segment)내에서 연주중의 경우, 프라이머리 세그먼트(segment) 트럭의 통지를 덧쓰기한다.
DMUS_TRACKCONFIG_CONTROL_PLAY
제어 세그먼트(segment)내에서 연주중의 경우, 프라이머리 세그먼트(segment) 트럭의 재생을 덧쓰기한다.
DMUS_TRACKCONFIG_DEFAULT
DMUS_TRACKCONFIG_CONTROL_ENABLED | DMUS_TRACKCONFIG_PLAY_ENABLED | DMUS_TRACKCONFIG_NOTIFICATION_ENABLED 의 편성.
DMUS_TRACKCONFIG_FALLBACK
요구한 정보가 프라이머리 세그먼트(segment) 및 제어 세그먼트(segment)로부터 돌려주어지지 않은 경우, 트럭이 이 세그먼트(segment)로부터의 파라미터의 취득을 시도한다.
DMUS_TRACKCONFIG_LOOP_COMPOSE
트럭이 반복될 때마다, 데이터를 재생성한다.
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
통지를 유효하게 한다.
DMUS_TRACKCONFIG_OVERRIDE_ALL
제어 세그먼트(segment) 및 프라이머리 세그먼트(segment)의 전에, 트럭이 이 세그먼트(segment)로부터의 파라미터의 취득을 시도한다.
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
프라이머리 세그먼트(segment)의 전에, 트럭이 이 세그먼트(segment)로부터의 파라미터의 취득을 시도한다.
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
뮤직 타임을 사용하지 않고, 클락 타임에 연주한다.
DMUS_TRACKCONFIG_PLAY_COMPOSE
트럭이 연주를 시작 할 때마다, 데이터를 재생성한다.
DMUS_TRACKCONFIG_PLAY_ENABLED
트럭이 메세지를 송신할 수 있도록(듯이) 한다.
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
트란지션의 어레인지로, 선두 세그먼트(segment)의 현재의 장소에서 트럭 정보를 취득한다.
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
트란지션의 어레인지로, 선두 세그먼트(segment)의 시작 부분에서 트럭 정보를 취득한다.
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART
트란지션의 어레인지로, 2 번째의 세그먼트(segment)의 시작 부분에서 트럭 정보를 취득한다.

다음의 표는, 각 표준 트럭에 대해서 유효한 구성 플래그를 나타내고 있다.

밴드
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

코드
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

코드 맵
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

커멘드
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

가사
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

마커
DMUS_TRACKCONFIG_CONTROL_ENABLED

멜로디 편성. DirectX 8.0 에서는 이행되어 있지 않다.
DMUS_TRACKCONFIG_COMPOSING
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_LOOP_COMPOSE
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_PLAY_COMPOSE
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

모티프
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

뮤트
DMUS_TRACKCONFIG_CONTROL_ENABLED

파라미터 제어
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

패턴
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

스크립트
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

세그먼트(segment) 방아쇠
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

순서
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

싸인 포스트
DMUS_TRACKCONFIG_COMPOSING
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_LOOP_COMPOSE
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_PLAY_COMPOSE
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

스타일
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

시스템에크스크루시브
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

템포
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

박자 기호
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_PLAY_ENABLED

웨이브
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegmentState8::SetTrackConfig ,자기 제어 세그먼트(segment),트럭 구성


IDirectMusicSegment8::Unload

퍼포먼스나 오디오 패스로부터 음색 데이터를 언로드한다.

HRESULT Unload(
  IUnknown *pAudioPath
);

파라미터

pAudioPath
음색 데이터를 언로드하는 원인, 퍼포먼스나 오디오 패스의 IUnknown 인터페이스에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_TRACK_NOT_FOUND
E_POINTER

주의

전에 데이터가 다운로드되어 있지 않은 경우에서도, 메소드는 성공한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::Download


IDirectMusicSegmentState8

IDirectMusicPerformance8::PlaySegment 메소드나 IDirectMusicPerformance8::PlaySegmentEx 메소드를 호출하면, 퍼포먼스 엔진은 연주중의 세그먼트(segment) 상태를 추적하는 세그먼트(segment) 상태 오브젝트를 생성한다. 또,IDirectMusicSegmentState8 인터페이스의 형태로 세그먼트(segment)에의 핸들을 어플리케이션에 제공한다. 이 핸들을 사용해, 세그먼트(segment)의 재생 스테이터스를 추적할 수 있다. 또,IDirectMusicPerformance8 의 각 메소드와 조합하는 것으로, 세그먼트(segment) 재생의 직접적인 정지나 퍼포먼스로부터의 세그먼트(segment)의 삭제에도 이용할 수 있다.

IDirectMusicSegmentState8 은 IDirectMusicSegmentState 를 계승해, 새로운 메소드를 추가한다.

이 인터페이스는, 이하의 메소드를 지원 한다.

정보 | GetObjectInPath
 | GetRepeats
 | GetSeek
 | GetSegment
 | GetStartPoint
 | GetStartTime
트럭 구성 | SetTrackConfig

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicSegmentState8::GetObjectInPath

이 세그먼트(segment) 상태가 연주되고 있는 오디오 패스에 포함되는 오브젝트의 인터페이스를 취득한다.

HRESULT GetObjectInPath(
  DWORD dwPChannel,
  DWORD dwStage,
  DWORD dwBuffer,
  REFGUID guidObject,
  DWORD dwIndex,
  REFGUID iidInterface,
  void ** ppObject
);

파라미터

dwPChannel
검색하는 퍼포먼스 채널 또는 모든 채널을 검색하는 DMUS_PCHANNEL_ALL. 최초의 채널은 0 번이 된다. 「주의」를 참조할것.
dwStage
패스의 스테이지. 다음의 몇개의 값을 지정한다.
DMUS_PATH_AUDIOPATH
세그먼트(segment) 상태가 연주되고 있는 오디오 패스.
DMUS_PATH_AUDIOPATH_GRAPH
오디오 파스퇴르 그래프. 존재하지 않으면 생성 된다.
DMUS_PATH_AUDIOPATH_TOOL
오디오 파스퇴르 그래프내의 툴.
DMUS_PATH_BUFFER
DirectSound 버퍼.
DMUS_PATH_BUFFER_DMO
버퍼내의 DMO . DMO 인터페이스의 상세한 것에 대하여는, 「IDirectSoundBuffer8::GetObjectInPath 」를 참조할것.
DMUS_PATH_MIXIN_BUFFER
글로벌 믹스 인 버퍼.
DMUS_PATH_MIXIN_BUFFER_DMO
글로벌 믹스 인 버퍼내의 DMO.
DMUS_PATH_PERFORMANCE
퍼포먼스.
DMUS_PATH_PERFORMANCE_GRAPH
퍼포먼스 툴 그래프. 존재하지 않으면 생성 된다.
DMUS_PATH_PERFORMANCE_TOOL
퍼포먼스 그래프내의 툴.
DMUS_PATH_PORT
신디사이저.
DMUS_PATH_PRIMARY_BUFFER
프라이머리 버퍼.
DMUS_PATH_SEGMENT
세그먼트(segment) 상태를 소유하는 세그먼트(segment).
DMUS_PATH_SEGMENT_GRAPH
세그먼트(segment) 툴 그래프. 존재하지 않으면 생성 된다. 「주의」를 참조할것.
DMUS_PATH_SEGMENT_TOOL
세그먼트(segment) 그래프내의 툴. 「주의」를 참조할것.
DMUS_PATH_SEGMENT_TRACK
세그먼트(segment)내의 트럭. 「주의」를 참조할것.
dwBuffer
dwStage 가 DMUS_PATH_BUFFER_DMO 또는 DMUS_PATH_MIXIN_BUFFER_DMO 의 경우는, DMO 가 상주하는 버퍼의 인덱스. dwStage 가 DMUS_PATH_BUFFER 또는 DMUS_PATH_MIXIN_BUFFER 의 경우는, 버퍼의 인덱스. 그 이외의 경우는, 0 이 아니면 안된다.
guidObject
오브젝트의 클래스 식별자, 또는 임의의 클래스의 오브젝트를 검색하는 GUID_All_Objects. dwStage 에 의해 지정된 스테이지에 존재하는 오브젝트가 단일의 클래스로 한정되고 있는 경우는 무시된다. 이 파라미터는 GUID_NULL 로 설정할 수 있다.
dwIndex
적합 오브젝트의 리스트내의 오브젝트의 인덱스. 0 으로 설정해, 최초의 적합 오브젝트를 검색한다. dwStage 가 DMUS_PATH_BUFFER 또는 DMUS_PATH_MIXIN_BUFFER 의 경우, 이 파라미터는 무시되어dwBuffer 에 의해 버퍼 인덱스가 지정된다.
iidInterface
IID_IDirectMusicGraph 등, 목적의 인터페이스의 식별자.
ppObject
요구된 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_GARBAGE_COLLECTED 을 돌려준다. 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_INVALIDARG
E_NOINTERFACE
E_OUTOFMEMORY

주의

채널 고유하지 않은 스테이지에 대해서는,dwPChannel 의 값은 0 으로 설정해야 한다. 다음의 스테이지의 오브젝트는 채널 고유해서,dwPChannel 에 채널 번호 또는 DMUS_PCHANNEL_ALL 를 설정해 취득할 수 있다.

DMUS_PATH_AUDIOPATH_TOOL
DMUS_PATH_BUFFER
DMUS_PATH_BUFFER_DMO
DMUS_PATH_PERFORMANCE_TOOL
DMUS_PATH_PORT
DMUS_PATH_SEGMENT_TOOL

불필요한 오브젝트를 필터 링에 의해 제외 하면나무의 파라미터의 우선 순위는 다음과 같다.

  1. dwStage.
  2. guidObject. 이 값이 GUID_All_Objects 가 아닌 경우, 클래스 식별자가 guidObject 에 동일한 오브젝트만이 검색된다. 다만, 지정된 스테이지에 존재할 수 있는 오브젝트의 클래스가 1 개로 한정되고 있는 경우, 이 파라미터는 무시된다.
  3. dwPChannel. 스테이지가 채널 고유해, 이 값이 DMUS_PCHANNEL_ALL 가 아닌 경우, 그 채널의 오브젝트만이 검색된다.
  4. dwBuffer. 이 파라미터가 사용되는 것은,dwStage 가 DMUS_PATH_BUFFER, DMUS_PATH_MIXIN_BUFFER, DMUS_PATH_BUFFER_DMO, 또는 DMUS_PATH_MIXIN_BUFFER_DMO 의 경우 뿐이다.
  5. dwIndex. DirectMusic Producer 로 생성 하는 세그먼트(segment)의 트럭은, 반드시 어플리케이션과 같은 순서일 필요는 없다. 스테이지 DMUS_PATH_SEGMENT_TRACK 에서는, 특정의 트럭의 검색을 dwIndex 인 만큼 의지하지 않는 것.

일치하는 오브젝트가 발견되어도,iidInterface 로 지정되고 있는 인터페이스가 발견되지 않는 경우, 이 메소드는 실패한다.

dwStage 에 DMUS_PATH_SEGMENT_GRAPH 또는 DMUS_PATH_SEGMENT_TOOL 를 지정하는 경우에 돌려주어지는 오브젝트는, 같은 세그먼트(segment)에 근거하는 다른 세그먼트(segment) 상태에 돌려주어지는 오브젝트와 같지 않을 가능성이 있다. 세그먼트(segment)가 연주되는 경우, 그 툴 그래프는 카피되어IDirectMusicTool8::Clone 메소드를 지원 하는 툴도 모두 카피된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicAudioPath8::GetObjectInPath ,오디오 패스로부터의 오브젝트의 취득


IDirectMusicSegmentState8::GetRepeats

세그먼트(segment)의 루프 부분으로 설정된 반복 회수를 취득한다.

HRESULT GetRepeats(
  DWORD* pdwRepeats
);

파라미터

pdwRepeats
반복 회수를 받는 변수의 주소. 값 0 은, 그 세그먼트(segment) 전체를 1 회만 연주해, 반복하는 부분이 없는 것을 의미한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetRepeats


IDirectMusicSegmentState8::GetSeek

세그먼트(segment) 상태내의 시크 포인터를 취득한다. 이것은, 다음에 IDirectMusicTrack8::Play 메소드를 호출했을 때에 건네받는,mtStart 파라미터의 값이다. 이 값은 루프와 반복을 고려에 넣지 않기 때문에, 세그먼트(segment) 상태 전체가 최초부터 반복되는 경우는, 시크 포인터는 0 에 리셋 된다.

HRESULT GetSeek(
  MUSIC_TIME* pmtSeek
);

파라미터

pmtSeek
시크 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicSegmentState8::GetSegment

이 세그먼트(segment) 상태를 보관 유지하는 세그먼트(segment)에의 포인터를 취득한다.

HRESULT GetSegment(
  IDirectMusicSegment** ppSegment
);

파라미터

ppSegment
IDirectMusicSegment 인터페이스에의 포인터를 받는 변수의 주소. IDirectMusicSegment8 인터페이스를 취득하려면 ,QueryInterface 를 사용한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

ppSegment 에 돌려주어지는 포인터는, 어플리케이션이 해방해야 한다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicSegmentState8::GetStartPoint

연주의 시작에 사용되는 (또는 이미 사용된) 세그먼트(segment)에 오프셋(offset)를 돌려준다.

HRESULT GetStartPoint(
  MUSIC_TIME * pmtStart
);

파라미터

pmtStart
세그먼트(segment)의 선두로부터, 최초로 연주된 (또는 지금부터 연주된다) 세그먼트(segment) 상태까지의 오프셋(offset) (뮤직 타임 단위)를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

시작 포인트는, (들)물을 수 있는 세그먼트(segment)의 최초의 포인트이다. 다만, 세그먼트(segment)의 시작 포인트가 경과시간에 맞추어 있는 경우, 실제로 들리는 최초의 포인트는, 이것보다 늦어진다. 상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetStartPoint ,IDirectMusicSegmentState8::GetStartTime


IDirectMusicSegmentState8::GetStartTime

세그먼트(segment)의 연주가 시작 된, 또는 지금부터 시작 되는 연주 타임을 취득한다.

HRESULT GetStartTime(
  MUSIC_TIME* pmtStart
);

파라미터

pmtStart
이 세그먼트(segment) 상태에 보존되고 있는 뮤직 타임 단위의 오프셋(offset)를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

이 메소드에 의해 취득하는 타임은, 세그먼트(segment)의 시작 타임이 큐에 들어가 있는 퍼포먼스에서의, 해결 지음의 연주 타임이다. 상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetStartPoint ,IDirectMusicSegment8::GetStartPoint ,IDirectMusicSegmentState8::GetStartPoint


IDirectMusicSegmentState8::SetTrackConfig

트럭의 구성을 설정한다.

HRESULT SetTrackConfig(
  REFGUID rguidTrackClassID,
  DWORD dwGroupBits,
  DWORD dwIndex,
  DWORD dwFlagsOn,
  DWORD dwFlagsOff
);

파라미터

rguidTrackClassID
트럭 클래스의 식별자에의 참조 (C++) 또는 주소 (C). 값의 리스트에 대해서는, 「표준 트럭의 종류」를 참조할것.
dwGroupBits
트럭이 소속하는 그룹.
dwIndex
그룹내의 트럭의 인덱스, 또는 그룹내의 모든 트럭의 구성을 설정하는 DMUS_SEG_ALLTRACKS.
dwFlagsOn
설정하는 구성 플래그. 값의 리스트에 대해서는, 「IDirectMusicSegment8::SetTrackConfig 」를 참조할것.
dwFlagsOff
클리어 하는 구성 플래그.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_TRACK_NOT_FOUND
E_INVALIDARG

주의

구성의 변경은, 준비 시간 후에 유효하게 된다. 변경을 즉시에 유효하게 하려면 ,IDirectMusicPerformance8::Invalidate 를 호출한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::SetTrackConfig ,자기 제어 세그먼트(segment),트럭 구성


IDirectMusicSong8

DirectX 8.0 에서는 이행되어 있지 않다.

IDirectMusicSong8 인터페이스는, 노래를 나타낸다. 노래란, 공통의 소스 소재에 근거하는 세그먼트(segment)의 콜렉션이다.

이 인터페이스는, 이하의 메소드를 지원 한다.

음색 | Download
 | Unload
세그먼트(segment)의 취득 | EnumSegment
 | GetSegment
그 외 | Compose
 | GetAudioPathConfig
 | GetParam

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. 이 인터페이스는, 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicSong8::Compose

DirectX 8.0 에서는 이행되어 있지 않다.

노래의 소스 소재로부터 연주 가능한 세그먼트(segment)를 생성 한다.

HRESULT Compose();

파라미터

없음.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 노래가 어레인지 되었다.
S_FALSE | 어레인지 하는 트럭이 없다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_TRACK_NOT_FOUND
E_INVALIDARG
E_POINTER
E_OUTOFMEMORY

주의

이 메소드는, 노래중에서 모든 세그먼트(segment)내의 모든 어레인지 트럭을 검색해, 같은 식별자와 그룹 비트를 가지는 트럭을 마스터 어레인지 트럭에 정리한다. 다음에, 마스터 어레인지 트럭으로부터 우선 순위에 따라 새로운 트럭을 어레인지 해, 이러한 새로운 트럭을 원의 트럭에 대응하도록(듯이) 분할한다. 그리고, 분할한 어레인지 끝난 트럭을, 노래의 세그먼트(segment)의 적절한 장소에 삽입한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::Compose ,IDirectMusicTrack8::Compose


IDirectMusicSong8::Download

DirectX 8.0 에서는 이행되어 있지 않다.

밴드 데이터를 퍼포먼스 또는 오디오 패스에 다운로드한다.

HRESULT Download(
  IUnknown *pAudioPath
);

파라미터

pAudioPath
음색 데이터를 받는 퍼포먼스나 오디오 패스의 IUnknown 인터페이스에의 포인터.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_PARTIALDOWNLOAD 를 돌려주는 상세한 것에 대하여는,IDirectMusicBand8::Download 의 「주의」를 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

주의

노래의 모든 세그먼트(segment)내의 모든 밴드가 다운로드된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSong8::Unload


IDirectMusicSong8::EnumSegment

DirectX 8.0 에서는 이행되어 있지 않다.

노래를 구성하는 세그먼트(segment)의 1 개를 인덱스로 취득한다.

HRESULT EnumSegment(
  DWORD dwIndex,
  IDirectMusicSegment **ppSegment
);

파라미터

dwIndex
노래의 세그먼트(segment)의 인덱스.
ppSegment
일치하는 세그먼트(segment)가 발견되었을 경우,IDirectMusicSegment 인터페이스 포인터를 받는 변수의 주소. IDirectMusicSegment8 를 취득하려면 ,QueryInterface 를 사용한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 세그먼트(segment)가 열거되었다.
S_FALSE | dwIndex 에 세그먼트(segment)가 없다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

성공했을 경우는 S_OK,dwIndex 가 노래의 세그먼트(segment)에 일치하지 않는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSong8::GetSegment


IDirectMusicSong8::GetAudioPathConfig

DirectX 8.0 에서는 이행되어 있지 않다.

노래의 오디오 패스 구성을 나타내는 오브젝트를 취득한다.

HRESULT GetAudioPathConfig(
  IUnknown ** ppAudioPathConfig
);

파라미터

ppAudioPathConfig
오디오 패스 구성 오브젝트의 IUnknown 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_GARBAGE_COLLECTED 를 돌려준다. 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NO_AUDIOPATH_CONFIG
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::GetAudioPathConfig


IDirectMusicSong8::GetParam

DirectX 8.0 에서는 이행되어 있지 않다.

이 노래의 트럭으로부터 데이터를 취득한다.

HRESULT GetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

파라미터

rguidType
취득되는 데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
dwGroupBits
목적의 트럭이 놓여져 있는 그룹. 모든 그룹을 지정하려면 , 이 값을 0xFFFFFFFF 로 설정한다. 「주의」를 참조할것.
dwIndex
데이터의 취득에 사용되는 그룹내에서, 트럭에 할당할 수 있고 있는 인덱스.
mtTime
데이터를 취득하는 타임. 퍼포먼스 시간에 지정한다.
pmtNext
데이터가 무효가 되는 타임 (mtTime 로부터의 상대 타임)을 받는 변수의 주소. 이 변수가 값 0 을 돌려주었을 경우, 데이터가 항상 유효하게 되어 있는지, 데이터가 무효가 되는 타임이 불명한 것을 의미한다. 이 정보가 불필요한 경우는,pmtNext 를 NULL 로 설정해도 괜찮다.
pParam
파라미터 데이터를 받는 버퍼의 주소.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_GARBAGE_COLLECTED 를 돌려준다. 「가베지 콜렉션」을 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicSong8::GetSegment

DirectX 8.0 에서는 이행되어 있지 않다.

노래를 구성하는 세그먼트(segment)의 1 개를 이름으로 취득한다.

HRESULT GetSegment(
  WCHAR pwzName,
  IDirectMusicSegment **ppSegment
);

파라미터

pwzName
세그먼트(segment)의 이름. 최초의 세그먼트(segment)를 취득하려면 NULL 를 지정한다.
ppSegment
일치하는 세그먼트(segment)가 발견되었을 경우,IDirectMusicSegment 인터페이스 포인터를 받는 변수의 주소. IDirectMusicSegment8 를 취득하려면 ,QueryInterface 를 사용한다.

반환값

성공했을 경우는, 다음의 몇개의 코드를 돌려준다.

S_OK | 세그먼트(segment)가 취득되었다.
S_FALSE | pwzName 가 어느 세그먼트(segment)와도 일치하지 않는다.
DMUS_S_GARBAGE_COLLECTED | 「가베지 콜렉션」을 참조할것.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSong8::EnumSegment


IDirectMusicSong8::Unload

DirectX 8.0 에서는 이행되어 있지 않다.

오디오 패스로부터 음색 데이터를 언로드한다.

HRESULT Unload(
  IUnknown *pAudioPath
);

파라미터

pAudioPath
음색 데이터를 어디에서 언로드하는지를 나타내는, 오디오 패스의 IUnknown 인터페이스에의 포인터.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_GARBAGE_COLLECTED 를 돌려준다. 「가베지 콜렉션」을 참조할것.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

주의

전에 데이터가 다운로드되어 있지 않은 경우에서도, 메소드는 성공한다.

참조

IDirectMusicSong8::Download


IDirectMusicStyle8

IDirectMusicStyle8 인터페이스는, 스타일 오브젝트에의 액세스를 제공한다. 스타일 오브젝트는, 뮤직 패턴을 연주할 경우에 필요하게 되는 정보를 퍼포먼스에 제공한다. 개요에 대해서는, 「스타일의 사용법」을 참조할것.

스타일에는 보통, 밴드와 모티프가 포함되므로,IDirectMusicStyle8 는 이러한 오브젝트에 액세스하기 위한 메소드를 제공한다.

DirectMusicStyle 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject8 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

IDirectMusicStyle8 는 IDirectMusicStyle 인터페이스를 계승해, 새로운 메소드 EnumPattern 를 추가한다.

IDirectMusicStyle8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

열거 | EnumBand
 | EnumChordMap
 | EnumMotif
 | EnumPattern
정보 | GetBand
 | GetChordMap
 | GetDefaultBand
 | GetDefaultChordMap
 | GetEmbellishmentLength
 | GetMotif
 | GetTempo
 | GetTimeSignature

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicStyle8::EnumBand

지정의 인덱스값에 대응하는 밴드명을 취득한다.

HRESULT EnumBand(
  DWORD dwIndex,
  WCHAR * pwszName
);

파라미터

dwIndex
스타일의 밴드 리스트내의, 0 으로부터 시작되는 인덱스.
pwszName
밴드명을 받는 버퍼의 주소. MAX_PATH 의 사이즈를 가져야 하는 것이다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 지정된 인덱스값을 가지는 밴드가 없으면 S_FALSE, 이름의 길이의 값이 MAX_PATH 보다 큰 경우는 DMUS_S_STRING_TRUNCATED 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_TYPE_UNSUPPORTED
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicStyle8::EnumChordMap

지정의 인덱스값에 대응하는 코드 맵명을 취득한다.

HRESULT EnumChordMap(
  DWORD dwIndex,
  WCHAR * pwszName
);

파라미터

dwIndex
스타일의 코드 맵 리스트내에 있는, 코드 맵의 0 으로부터 시작되는 인덱스.
pwszName
코드 맵명을 받는 버퍼의 주소. MAX_PATH 의 사이즈를 가져야 하는 것이다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 지정된 인덱스값을 가지는 코드 맵이 없으면 S_FALSE, 이름의 길이의 값이 MAX_PATH 보다 큰 경우는 DMUS_S_STRING_TRUNCATED 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_TYPE_UNSUPPORTED
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicStyle8::EnumMotif

지정의 인덱스값에 대응하는 모티프명을 취득한다.

HRESULT EnumMotif(
  DWORD dwIndex,
  WCHAR* pwszName
);

파라미터

dwIndex
스타일의 모티프 리스트내의, 0 으로부터 시작되는 인덱스.
pwszName
모티프명을 받는 버퍼의 주소. MAX_PATH 의 사이즈를 가져야 하는 것이다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 지정된 인덱스값을 가지는 모티프가 없으면 S_FALSE, 모티프명의 길이의 값이 MAX_PATH 보다 큰 경우는 DMUS_S_STRING_TRUNCATED 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle8::GetMotif ,모티프의 사용법


IDirectMusicStyle8::EnumPattern

지정의 인덱스값과 타입에 대응하는 패턴명을 취득한다. 이 이름은 IDirectMusicPatternTrack8::SetPatternByName 메소드에 건네줄 수가 있다.

HRESULT EnumPattern(
  DWORD dwIndex,
  DWORD dwPatternType,
  WCHAR* pwszName
);

파라미터

dwIndex
스타일의 패턴 리스트내의, 0 으로부터 시작되는 인덱스.
dwPatternType
패턴의 타입을 지정하는 DMUS_STYLET_TYPES 열거의 1 개.
pwszName
패턴명을 받는 버퍼의 주소. MAX_PATH 의 사이즈를 가져야 하는 것이다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 지정된 인덱스값을 가지는 패턴이 없으면 S_FALSE, 패턴명의 길이의 값이 MAX_PATH 보다 큰 경우는 DMUS_S_STRING_TRUNCATED 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicStyle8::GetBand

지정된 밴드를 취득한다.

HRESULT GetBand(
  WCHAR* pwszName,
  IDirectMusicBand** ppBand
);

파라미터

pwszName
취득되는 밴드의 이름. 이 이름은, 스타일의 생성자에 의해 할당할 수 있다.
ppBand
밴드의 IDirectMusicBand8 인터페이스 포인터를 받는 변수의 주소.

반환값

메소드가 성공해, 밴드가 돌려주어졌을 경우는 S_OK 를 돌려준다. 지정된 이름에 대응하는 밴드가 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle8::GetDefaultBand ,밴드의 사용법


IDirectMusicStyle8::GetChordMap

지정된 코드 맵을 취득한다.

HRESULT GetChordMap(
  WCHAR* pwszName,
  IDirectMusicChordMap** ppChordMap
);

파라미터

pwszName
취득되는 코드 맵의 이름.
ppChordMap
IDirectMusicChordMap8 인터페이스에의 포인터를 받는 변수의 주소.

반환값

메소드가 성공해, 코드 맵이 돌려주어졌을 경우는 S_OK 를 돌려준다. 지정된 이름에 대응하는 코드 맵이 존재하지 않는 경우는 S_FALSE 를 돌려준다.

ppChordMap 가 유효한 포인터가 아닌 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle8::GetDefaultChordMap ,코드 맵의 사용법


IDirectMusicStyle8::GetDefaultBand

스타일의 디폴트의 밴드를 취득한다.

HRESULT GetDefaultBand(
  IDirectMusicBand ** ppBand
);

파라미터

ppBand
디폴트 밴드의 IDirectMusicBand8 인터페이스 포인터를 받는 변수의 주소.

반환값

메소드가 성공해, 밴드가 돌려주어졌을 경우는 S_OK 를 돌려준다. 스타일에 디폴트의 밴드가 없는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle8::GetBand ,밴드의 사용법


IDirectMusicStyle8::GetDefaultChordMap

스타일의 디폴트의 코드 맵을 취득한다.

HRESULT GetDefaultChordMap(
  IDirectMusicChordMap** ppChordMap
);

파라미터

ppChordMap
IDirectMusicChordMap8 인터페이스에의 포인터를 받는 변수의 주소.

반환값

메소드가 성공해, 코드 맵이 돌려주어졌을 경우는 S_OK 를 돌려준다. 스타일에 디폴트의 코드 맵이 없는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle8::GetChordMap ,코드 맵의 사용법


IDirectMusicStyle8::GetEmbellishmentLength

지정된 장식 타입과홈 레벨로부터, 최단 패턴의 길이와 최장 패턴의 길이를 찾아낸다.

HRESULT GetEmbellishmentLength(
  DWORD dwType,
  DWORD dwLevel,
  DWORD* pdwMin,
  DWORD* pdwMax
);

파라미터

dwType
장식 타입. 「DMUS_COMMANDT_TYPES 」를 참조할것.
dwLevel
1 ~ 100 의 범위의 홈 레벨. dwType 가 DMUS_COMMANDT_GROOVE 가 아닌 경우는 무시된다.
pdwMin
지정된 타입과 홈 레벨의 최단 패턴의 길이 (소절 단위)를 받는 변수의 주소.
pdwMax
지정된 타입과 홈 레벨의 최장 패턴의 길이 (소절 단위)를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 또는 S_FALSE 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

지정된 타입과 홈 레벨에 대응하는 패턴이 존재하지 않는 경우, 반환값은 S_FALSE 이다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicStyle8::GetMotif

지정된 모티프를 포함한 세그먼트(segment)를 생성 한다.

HRESULT GetMotif(
  WCHAR* pwszName,
  IDirectMusicSegment** ppSegment
);

파라미터

pwszName
취득되는 모티프의 이름.
ppSegment
지정된 모티프를 포함한 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 또는 S_FALSE를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

주의

이 메소드는,pwszName 에 일치하는 이름을 가지는 모티프를 스타일 리스트로부터 검색한다. 모티프가 발견되었을 경우, 모티프 트럭을 포함한 세그먼트(segment)가 생성 된다. 트럭은, 스타일을 트럭의 관련 스타일, 모티프를 트럭의 패턴으로서 참조한다.

지정된 이름을 가지는 모티프가 존재하지 않는 경우, 이 메소드는 S_FALSE 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.

참조

모티프의 사용법


IDirectMusicStyle8::GetTempo

스타일의 추천 템포를 취득한다.

HRESULT GetTempo(
  double* pTempo
);

파라미터

pTempo
스타일의 추천 템포를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

pTempo 가 유효한 포인터가 아닌 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicStyle8::GetTimeSignature

스타일의 박자 기호를 취득한다.

HRESULT GetTimeSignature(
  DMUS_TIMESIGNATURE* pTimeSig
);

파라미터

pTimeSig
데이터를 받는 DMUS_TIMESIGNATURE 구조체의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicThru8

IDirectMusicThru8 인터페이스는, 뮤직 메세지의 캡춰 포토로부터 다른 포토에의 전송을 지원 한다. 이 인터페이스는, 캡춰 포토의 IDirectMusicPort8 인터페이스에 대해서 QueryInterface 를 호출하는 것에 의해 취득된다. 구체적인 예에 대해서는, 「IDirectMusicThru8::ThruChannel 」의 「주의」를 참조할것.

IDirectMusicThru8 는,IDirectMusicThru 의 형태 정의이다. 이것들 2 개의 인터페이스명은 교환해 사용할 수 있다.

이 인터페이스는, 이하의 메소드를 지원 한다.

IDirectMusicThru8 ThruChannel

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICTHRU8 형은, 이 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicThru8 *LPDIRECTMUSICTHRU8;

동작환경

헤더 : dmusici.h 로 선언.

참조

MIDI 의 캡춰


IDirectMusicThru8::ThruChannel

캡춰 포토 위에의 채널과 다른 포토 위에의 채널간에서의 전송 접속을 확립 또는 해제한다.

HRESULT ThruChannel(
  DWORD dwSourceChannelGroup,
  DWORD dwSourceChannel,
  DWORD dwDestinationChannelGroup,
  DWORD dwDestinationChannel,
  LPDIRECTMUSICPORT pDestinationPort
);

파라미터

dwSourceChannelGroup
캡춰 포토 위에의 채널 그룹. 이 값은 항상 1 이다.
dwSourceChannel
소스 채널.
dwDestinationChannelGroup
전송처 포토 위에의 채널 그룹.
dwDestinationChannel
전송처 채널.
pDestinationPort
전송처 채널의 IDirectMusicPort8 인터페이스의 주소. 이 값을 NULL 로 설정 하면, 기존의 전송 접속이 해제된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_NOTIMPL
E_INVALIDARG
DMUS_E_PORT_NOT_RENDER

주의

시스템에크스크루시브멧세이지는, 전송처 포토에 송신되지 않는다.

Microsoft 의 소프트웨어 신디사이저 또는 일정한 지연 시간을 가지지 않는 그 외의 신디사이저에의 전송은 추천 되지 않는다. 전송은, 수신 MIDI 이벤트를 받으면(자) 즉석에서 행해진다. 소프트웨어 신디사이저의 지연 시간이 비교적 긴 일 (하드웨어 포토와 비교했을 경우), 및 소프트웨어 신디사이저는 복수의 오디오 블록을 동시에 렌더링 하는 것으로부터, 각 이벤트에는 연주전 정원않고일까 지연이 발생한다. 이 지연의 길이는, 일정하고 있지 않다. 이 랜덤인 오프셋(offset)는, 데이터의 재생시에 지터로서 발생한다. 그 외의 디바이스 (MPU-401 포토등)의 지연 시간은 적기 (위해)때문에, 지터는 발생하지 않는다.

어플리케이션이 소프트웨어 신디사이저에 대해서 데이터를 전송 할 필요가 있는 경우, 수신 노트 이벤트의 타임 스탬프 정원않고일까 오프셋(offset)를 추가해, 신디사이저의 렌더링 지연 시간을 보정해야 한다.

다음의 샘플 코드에서는,IDirectMusicThru8 인터페이스를 취득해, 캡춰 포토의 그룹 1 위에의 모든 채널과 전송처 포토 위에의 동등의 채널과의 사이에 전송 접속을 확립한다.

HRESULT SetupOneToOneThru(
    IDirectMusicPort8 *pCapturePort,
    IDirectMusicPort8 *pRenderPort)
{
    HRESULT hr;
    IDirectMusicThru8 *pThru;

    hr = pCapturePort->QueryInterface(IID_IDirectMusicThru8,
            (void**) &pThru);
    if (FAILED(hr))
        return hr;

    for (DWORD dwChannel = 0; dwChannel < 16; dwChannel++)
    {
        hr = pThru->ThruChannel(1, dwChannel,
            1, dwChannel, (IDirectMusicPort*) pRenderPort);
        if (FAILED(hr))
            break;
    }

    pThru->Release();
    return hr;
}

동작환경

헤더 : dmusici.h 로 선언.


IDirectMusicTool8

IDirectMusicTool8 인터페이스는, 메세지를 처리하는 툴 오브젝트를 나타낸다. 툴은 메세지의 변경, 추가의 메세지의 생성, 메세지의 삭제등을 실시할 수 있다.

이 인터페이스는 주로, 독자적인 툴을 생성 하는 것을 생각하고 있는 개발자에 의해 이용된다. 이 인터페이스의 메소드는, 툴의 설계자에 의해 이행 되어 많은 경우, 퍼포먼스에 의해 불려 간다. 어플리케이션은,IDirectMusicGraph8::InsertTool 를 사용해 메세지 패스에 툴을 삽입하는 것만으로 좋다.

IDirectMusicTool8 는 IDirectMusicTool 인터페이스를 계승해, 새로운 메소드를 추가한다.

IDirectMusicTool8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

복제 | Clone
초기화 | Init
메세지 관리 | Flush
 | GetMediaTypeArraySize
 | GetMediaTypes
 | GetMsgDeliveryType
 | ProcessPMsg

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmplugin.h 로 선언.

참조

메세지의 생성과 전달,DirectMusic 툴


IDirectMusicTool8::Clone

툴의 새로운 인스턴스를 생성 한다.

HRESULT Clone(
  IDirectMusicTool** ppTool
);

파라미터

ppTool
툴의 새로운 인스턴스의 IDirectMusicTool 인터페이스에의 포인터를 받는 변수의 주소. IDirectMusicTool8 를 취득하려면 , QueryInterface 를 사용한다.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다. 실패했을 경우는,E_POINTER 또는 E_OUTOFMEMORY 를 돌려준다.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTool8::Flush

퍼포먼스가 정지했을 때에, 큐로부터 메세지를 플래시 (해방) 하는 툴은 이 메소드를 사용해, 메세지의 플래시 (해방)에 필요한 모든 일을 실시할 수 있다. 예를 들어, 출력 툴은 이 메소드를 사용해, 보류되고 있는 모든 노트 오프 메세지가 즉석에서 처리되도록(듯이) 한다.

HRESULT Flush(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pPMSG,
  REFERENCE_TIME rtTime
);

파라미터

pPerf
IDirectMusicPerformance8 인터페이스의 주소.
pPMSG
플래시 되는 메세지.
rtTime
플래시를 실시하는 타임.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는, 다음의 어느쪽이든을 돌려준다.

DMUS_S_REQUEUE
DMUS_S_FREE
S_OK

실패했을 경우는 E_POINTER 를 돌려준다.

주의

메세지는 스스로의 dwFlags 멤버에 DMUS_PMSGF_TOOL_FLUSH 를 설정한다. 「DMUS_PMSG 」를 참조할것.

메소드가 DMUS_S_REQUEUE 를 돌려주었을 경우는, 지정된 메세지를 툴이 한번 더 큐에 넣으려 하고 있는 것을 의미한다. 이 결과, 툴은 메세지에 새로운 타임 스탬프와 파라미터를 기입해 한번 더 큐에 넣는지, 메세지에 다른 전달 타입을 할당해 한번 더 큐에 넣어진다.

반환값이 DMUS_S_FREE 의 경우, 툴은 메세지를 자동적으로 해방하려고 하고 있어 메세지를 한번 더 큐에 넣을 필요는 없는 것을 의미한다.

반환값이 S_OK 의 경우, 툴은 메세지를 자동적으로 해방하려고 젓가락이라고 없다. 어떠한 이유로써 툴은 메세지를 보관 유지하고 있는지, 이미 스스로 해방했다고 생각된다.

pPerf 에 의해 나타내지는 퍼포먼스에의 순환 참조는 생성 하지 않는 것. 상세한 것에 대하여는, 「DirectMusic 툴」을 참조할것.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTool8::GetMediaTypeArraySize

IDirectMusicTool8::GetMediaTypes 메소드에 건네주지 않으면 안 되는 배열의 사이즈를 취득한다. 값으로서 0 이 돌려주어졌을 경우, 그 툴은 모든 타입을 처리하므로,GetMediaTypes 를 호출할 필요가 없는 것을 의미한다.

HRESULT GetMediaTypeArraySize(
  DWORD* pdwNumElements
);

파라미터

pdwNumElements
미디어 타입의 수를 받는 변수의 주소. 이 필드에 0 이 돌려주어졌을 경우, 모든 타입이 지원 되고 있다.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다. 실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTool8::GetMediaTypes

이 툴이 지원 하는 메세지 타입의 리스트를 취득한다.

HRESULT GetMediaTypes(
  DWORD** padwMediaTypes,
  DWORD dwNumElements
);

파라미터

padwMediaTypes
DWORD 의 배열의 주소. 이 메소드는, 툴이 지원 하고 있는 미디어 타입을 이 배열에 기입한다. 미디어 타입에 대해서는, 「DMUS_PMSGT_TYPES 」를 참조할것.
dwNumElements
padwMediaTypes 배열내의 요소의 수. 이 값은,IDirectMusicTool8::GetMediaTypeArraySize 메소드가 돌려준 수로 일치하고 있어야 하는 것이다. dwNumElements 의 값이 이 수보다 작은 경우, 메소드는 지원 떠날 수 있어 모든 메세지 타입을 돌려줄 수 없다. 값이 이 수보다 큰 경우, 배열내의 여분의 요소는 0 으로 설정된다.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다. dwNumElements 가 너무 작아 모든 값을 기입할 수 없었던 경우는 S_FALSE 를 돌려준다. 실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_INVALIDARG
E_NOTIMPL

주의

메소드가 E_NOTIMPL 를 돌려주는 경우, 툴은 모든 미디어 타입을 처리한다.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTool8::GetMsgDeliveryType

메세지를 툴에 전달하는 시기를 결정하는 툴의 전달 타입을 취득한다.

HRESULT GetMsgDeliveryType(
  DWORD* pdwDeliveryType
);

파라미터

pdwDeliveryType
전달 타입을 받는 변수의 주소. 돌려주어지는 값은, DMUS_PMSGF_TOOL_IMMEDIATE, DMUS_PMSGF_TOOL_QUEUE, DMUS_PMSGF_TOOL_ATTIME 의 언젠가가 아니면 안된다. *pdwDeliveryType 의 값이 인식되지 않는 경우, 그래프에 의해 DMUS_PMSGF_TOOL_IMMEDIATE 로서 다루어진다.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다. 실패했을 경우는 E_POINTER 를 돌려준다.

주의

전달 메카니즘의 개요에 대해서는, 「메세지의 생성과 전달」을 참조할것.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTool8::Init

툴을 초기화한다. 이 메소드는, 툴을 그래프에 삽입했을 때에 불려 가 툴이 필요한 초기화를 행하기 위한 기회를 제공한다.

HRESULT Init(
  IDirectMusicGraph* pGraph
);

파라미터

pGraph
호출중의 그래프.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다. 실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_NOTIMPL

주의

툴은 복수의 그래프에 삽입할 수 있기 (위해)때문에, 이 메소드는 복수의 호출에 대해서 문제 없게 대처할 수 없으면 안 된다.

pGraph 에 의해 나타내지는 퍼포먼스에의 순환 참조는 생성 하지 않는 것. 상세한 것에 대하여는, 「DirectMusic 툴」을 참조할것.

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicGraph8::InsertTool


IDirectMusicTool8::ProcessPMsg

툴의 주요한 태스크를 실행한다. 이 메소드는,IDirectMusicTool8::GetMediaTypes 에 의해 지정되는 타입과 일치하는 모든 메세지에 대해서, 퍼포먼스의 리얼타임 thread의 내부로부터 불려 간다.

HRESULT ProcessPMsg(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pPMSG
);

파라미터

pPerf
메세지를 생성하고 있는 퍼포먼스.
pPMSG
처리되는 메세지.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는, 다음의 어느쪽이든을 돌려준다.

DMUS_S_REQUEUE
DMUS_S_FREE
S_OK

실패했을 경우는 E_POINTER 를 돌려준다.

주의

메소드가 DMUS_S_REQUEUE 를 돌려주었을 경우는, 지정된 메세지를 툴이 한번 더 큐에 넣으려 하고 있는 것을 의미한다. 이 결과, 툴은 메세지에 새로운 타임 스탬프와 파라미터를 기입해 한번 더 큐에 넣는지, 메세지에 다른 전달 타입을 할당해 한번 더 큐에 넣어진다.

반환값이 DMUS_S_FREE 의 경우, 툴은 메세지를 자동적으로 해방하려고 하고 있어 메세지를 한번 더 큐에 넣을 필요는 없는 것을 의미한다.

반환값이 S_OK 의 경우, 툴은 메세지를 자동적으로 해방하려고 젓가락이라고 없다. 어떠한 이유로써 툴은 메세지를 보관 유지하고 있는지, 이미 스스로 해방했다고 생각된다.

툴은 시간이 걸리는 조작을 실행해서는 안 된다. 만약 그러한 경우, 퍼포먼스 전체에 큰 영향을 미치기 때문에 있다. 또,pPerf 에 의해 나타내지는 퍼포먼스에의 순환 참조는 생성 하지 않는 것. 상세한 것에 대하여는, 「DirectMusic 툴」을 참조할것.

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicPerformance8::SendPMsg ,메세지,메세지의 생성과 전달


IDirectMusicTrack8

IDirectMusicTrack8 인터페이스는, 트럭 오브젝트를 나타낸다. 세그먼트(segment)의 정의에 관계가 있는 거의 모든 내용이 트럭에 보존되고 있다. 이 트럭 메카니즘에 의해, 세그먼트(segment)는 무한하게 확장 가능하고, 세그먼트(segment)는 스스로 사용하는 음악이나 오디오의 테크놀러지에 관해서 아무것도 파악하고 있지 않아도 상관없다.

독자적인 음악 재생 메카니즘을 DirectMusic 에 이행 하는 것을 계획하고 있는 경우, 그 메카니즘을 나타내는 DirectMusicTrack 오브젝트를 생성 할 필요가 있다. DirectMusicTrack 오브젝트를 생성 하지 않았던 경우, 이 인터페이스의 메소드는 보통, 어플리케이션으로부터 직접 불려 가지 않는다.

IDirectMusicTrack8 은 IDirectMusicTrack 인터페이스를 계승해, 새로운 메소드를 추가한다.

주 IDirectMusicTrack8 인터페이스의 메소드를 이행 하면나무는, 건네받는 오브젝트에의 참조를 보관 유지하지 않는 것. 예를 들어,IDirectMusicTrack8::Init 가 파라미터로서 받는 IDirectMusicSegment 인터페이스에의 참조를 추가하는 경우는, 이 참조가 해방되도록(듯이) 한다.

IDirectMusicTrack8 인터페이스에는 다음의 메소드가 있다.

생성 | Clone
 | Compose
 | Join
초기화 | Init
통지 | AddNotificationType
 | RemoveNotificationType
파라미터 | GetParam
 | GetParamEx
 | IsParamSupported
 | SetParam
 | SetParamEx
재생 | EndPlay
 | InitPlay
 | Play
 | PlayEx

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

DirectMusicTrack 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject8 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

동작환경

헤더 : dmplugin.h 로 선언.

참조

DirectMusic 트럭,트럭 파라미터의 설정과 취득


IDirectMusicTrack8::AddNotificationType

트럭에의 이벤트 통지를 가능하게 한다. IDirectMusicSegment8::AddNotificationType 메소드를 닮아 있어, 이 메소드로부터 불려 간다.

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
추가되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). 정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것. 어플리케이션은, 커스텀 트랙에 도착해 독자적인 타입을 정의할 수 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 트럭이 통지 타입을 지원 하지 않는 경우는 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_NOTIMPL

주의

트럭이 통지를 지원 하지 않는 경우는, E_NOTIMPL 를 돌려준다. 모티프 또는 스타일 트럭은, 초기화되어 있지 않은 경우는 DMUS_E_NOT_INIT 를 돌려준다.

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicTrack8::RemoveNotificationType ,통지와 이벤트의 처리


IDirectMusicTrack8::Clone

트럭의 카피를 생성 한다.

HRESULT Clone(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  IDirectMusicTrack** ppTrack
 );

파라미터

mtStart
카피 시작 파트. 0 이상, 한편 트럭의 길이 미만의 값으로 해야 한다.
mtEnd
카피 종료 파트. mtStart 보다 크고, 트럭의 길이 미만의 값으로 해야 한다.
ppTrack
메소드가 성공했을 경우는, 생성 된 트럭에의 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

어플리케이션은, 트럭의 종료시에 Release 를 호출하지 않으면 안 된다.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTrack8::Compose

세그먼트(segment)의 데이터에 근거해, 트럭을 재어레인지 한다. DirectMusic 는 싸인 포스트트럭에 이 메소드를 이행 해, 코트드락크를 어레인지 한다.

HRESULT Compose(
  IUnknown* pContext,
  DWORD dwTrackGroup,
  IDirectMusicTrack** ppResultTrack
 );

파라미터

pContext
어레인지에 사용하는 오브젝트의 IUnknown 인터페이스 포인터. 이것은 보통, 이 트럭을 소유하는 세그먼트(segment)이다.
dwTrackGroup
트럭에 대해서 그룹을 지정하는 DWORD 값. 그룹 비트의 상세한 것에 대하여는, 「트럭의 식별」을 참조할것.
ppResultTrack
어레인지가 끝난 트럭의 IDirectMusicTrack 인터페이스를 받는 변수의 주소. QueryInterface 를 사용해,IDirectMusicTrack8 를 취득한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_INVALIDARG
E_POINTER

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicSegment8::Compose


IDirectMusicTrack8::EndPlay

IDirectMusicTrack8::InitPlay 를 처음에 호출한 오브젝트를 삭제할 경우에 불려 간다.

HRESULT EndPlay(
  void * pStateData
);

파라미터

pStateData
IDirectMusicTrack8::InitPlay 로부터 돌려주어지는 상태 데이터에의 포인터. 이 데이터는 EndPlay 메소드로 해방해야 한다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는 E_POINTER 를 돌려준다.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTrack8::GetParam

트럭으로부터 데이터를 뮤직 타임에 취득한다.

HRESULT GetParam(
  REFGUID rguidType,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

파라미터

rguidType
취득되는 데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
mtTime
데이터를 취득하는 타임. 트럭 시간에 지정한다.
pmtNext
데이터가 무효가 되는 타임을 받는 변수의 주소. 이 변수가 값 0 을 돌려주었을 경우, 데이터가 항상 유효하게 되어 있는지, 데이터가 무효가 되는 타임이 불명한 것을 의미한다. 이 정보가 불필요한 경우는,pmtNext 를 NULL 로 설정해도 괜찮다.
pParam
돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 이 구조체는,rguidType 로 식별된 데이터형에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
DMUS_E_NOT_INIT
DMUS_E_TYPE_DISABLED
DMUS_E_GET_UNSUPPORTED
E_POINTER

주의

보다 강한 기능이 필요한 경우에는,IDirectMusicTrack8::GetParamEx 메소드를 사용할 수 있다.

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicTrack8::SetParam ,IDirectMusicTrack8::IsParamSupported ,IDirectMusicPerformance8::GetParam ,IDirectMusicSegment8::GetParam ,퍼포먼스 파라미터


IDirectMusicTrack8::GetParamEx

트럭으로부터 데이터를, 뮤직 타임 또는 기준 타임에 취득한다.

HRESULT GetParamEx(
  REFGUID rguidType,
  REFERENCE_TIME rtTime,
  REFERENCE_TIME* prtNext,
  void * pParam
  void * pStateData,
  DWORD dwFlags
);

파라미터

rguidType
취득되는 데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
rtTime
데이터의 취득을 실시하는 타임. dwFlags 에 DMUS_TRACK_PARAMF_CLOCK 가 설정되어 있지 않은 경우, 이 값은 뮤직 타임에 취득된다.
prtNext
데이터가 무효가 되는 타임을 받는 변수의 주소. 이 변수가 값 0 을 돌려주었을 경우, 데이터가 항상 유효하게 되어 있는지, 데이터가 무효가 되는 타임이 불명한 것을 의미한다. 이 정보가 불필요한 경우는,prtNext 를 NULL 로 설정해도 괜찮다.
pParam
돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 돌려주어지는 데이터의 보존용으로 할당할 수 있었던 구조체의 주소. 이 구조체는,rguidType 로 식별된 데이터형에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.
pStateData
트럭 인스턴스 상태 데이터를 보관 유지하는 버퍼의 주소. IDirectMusicTrack8::InitPlay 로부터 취득된다.
dwFlags
0 또는 다음의 플래그를 지정한다.
DMUS_TRACK_PARAMF_CLOCK
rtTime 의 값은, 클락 타임에 나타내진다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_FOUND
DMUS_E_NOT_INIT
DMUS_E_TYPE_DISABLED
DMUS_E_GET_UNSUPPORTED
DMUS_E_TRACK_NO_CLOCKTIME_SUPPORT
E_POINTER

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicTrack8::GetParam ,IDirectMusicTrack8::SetParamEx


IDirectMusicTrack8::Init

트럭을 초기화한다. 트럭의 추가시에 세그먼트(segment)에 의해 불려 간다.

HRESULT Init(
  IDirectMusicSegment* pSegment
);

파라미터

pSegment
이 트럭이 소속하는 세그먼트(segment).

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

주의

트럭이 메세지를 연주하는 경우,Init 메소드내에서 IDirectMusicSegment8::SetPChannelsUsed 를 호출해야 하는 것이다.

트럭이 세그먼트(segment)에 삽입된 다음에, 트럭 데이터에 변화가 있으면, 이 메소드를 반드시 호출하도록(듯이) 한다.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTrack8::InitPlay

트럭이 연주를 시작 할 준비를 할 수 있었을 때에 불려 간다. 이 메소드는, 상태 데이터에의 포인터를 돌려준다.

HRESULT InitPlay(
  IDirectMusicSegmentState* pSegmentState,
  IDirectMusicPerformance* pPerformance,
  void** ppStateData,
  DWORD dwVirtualTrackID,
  DWORD dwFlags
);

파라미터

pSegmentState
호출원의 IDirectMusicSegmentState 또는 IDirectMusicSegmentState8 인터페이스의 주소.
pPerformance
호출원의 IDirectMusicPerformance 또는 IDirectMusicPerformance8 인터페이스의 주소.
ppStateData
상태 정보에의 포인터를 받기 위한 변수의 주소. 데이터의 포맷과 사용 방법은, 트럭에 고유하다. 데이터는 InitPlay 메소드로 생성 해,IDirectMusicTrack8::EndPlay 메소드로 해방해야 한다. 포인터는,IDirectMusicTrack8::Play 메소드와 IDirectMusicTrack8::PlayEx 메소드에게 건네진다.
dwVirtualTrackID
이 트럭 인스턴스에 할당할 수 있었던 가상 트럭 ID.
dwFlags
트럭의 동작을 제어하는 DMUS_SEGF_FLAGS . 「주의」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

주의

dwFlags 파라미터는,IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 의 호출로 퍼포먼스에게 건네진 플래그를 건네준다. 트럭은, DMUS_SEGF_CONTROL 와 DMUS_SEGF_SECONDARY 의 각 플래그에 근거해, 그 실행 방법을 결정한다. 예를 들어, 템포 트럭은, 그 자체가 프라이머리 세그먼트(segment) 또는 세칸다리제어 세그먼트(segment)의 파트인 경우에 한정해, 템포의 변경을 자동적으로 연주한다 (DMUS_SEGF_SECONDARY 가 설정되어 있지 않은, 또는 DMUS_SEGF_CONTROL 가 설정되어 있다).

트럭은 ppStateData 로 NULL 를 돌려주는 경우가 있다.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTrack8::IsParamSupported

IDirectMusicTrack8::GetParam 메소드와 IDirectMusicTrack8::SetParam 메소드로 지정된 데이터형을 지원 하고 있을지 어떨지를 판단한다.

HRESULT IsParamSupported(
  REFGUID rguidType
);

파라미터

rguidType
데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.

반환값

메소드가 성공해, 타입이 지원 되고 있는 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_TYPE_DISABLED
DMUS_E_TYPE_UNSUPPORTED
E_POINTER
E_NOTIMPL

주의

SetParam 메소드의 어느쪽이든을 사용하는 것에 의해 파라미터가 무효가 되어 있는 경우,IDirectMusicTrack8::IsParamSupported 메소드는, 대응하는 파라미터 타입 (GUID_TempoParam 또는 GUID_TimeSignature)을 건네받았을 때에 DMUS_E_TYPE_DISABLED 를 돌려준다.

이 메소드는, GUID_DisableTempo 를 건네받아 그 파라미터가 이미 무효가 되어 있는 경우, 또는 GUID_EnableTempo 를 건네받아 그 파라미터가 현재 유효하게 되어 있는 경우에도, DMUS_E_TYPE_DISABLED 를 돌려준다. 이것은, GUID_DisableTimeSig 와 GUID_EnableTimeSig 에도 들어맞는다.

GUID_EnableTempo, GUID_EnableTimeSig, GUID_DisableTempo, 또는 GUID_DisableTimeSig 의 각 파라미터의 호출에 의해 참조되는 파라미터를 트럭이 지원 하지 않는 경우, 이 메소드는 DMUS_E_TYPE_UNSUPPORTED 를 돌려준다.

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicTrack8::GetParam ,IDirectMusicTrack8::SetParam ,퍼포먼스 파라미터


IDirectMusicTrack8::Join

트럭을 다른 트럭의 말미에 부가한다.

HRESULT Join(
  IDirectMusicTrack* pNewTrack,
  MUSIC_TIME mtJoin,
  IUnknown* pContext,
  DWORD dwTrackGroup,
  IDirectMusicTrack** ppResultTrack)
);

파라미터

pNewTrack
이 트럭의 뒤에 부가하는 트럭을 지정하는 IDirectMusicTrack8 인터페이스에의 포인터.
mtJoin
pNewTrack 를 시작 하는, 이 트럭에서의 타임.
pContext
문맥 세그먼트(segment)의 IUnknown 인터페이스 포인터. 이 오브젝트로부터, 싸인 포스트트럭 등, 소절이나 박을 사용하는 트럭의 박자 기호가 결정된다.
dwTrackGroup
새로운 트럭이 속하는, 1 개(살) 또는 복수의 그룹. 상세한 것에 대하여는, 「IDirectMusicSegment8::InsertTrack 」 및 「트럭의 식별」을 참조할것.
ppResultTrack
연결이 끝난 트럭의 IDirectMusicTrack 인터페이스를 받는 변수의 주소. QueryInterface 를 사용해,IDirectMusicTrack8 를 취득한다. NULL 의 경우, 새로운 트럭은 생성 되지 않고, 현재의 트럭이 연결이 끝난 트럭이 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_POINTER
E_INVALIDARG
E_OUTOFMEMORY

주의

이 메소드는, 밴드, 코드 맵, 템포, 스타일, 코드, 싸인 포스트, 및 커멘드의 각 트럭으로 지원 된다.

동작환경

헤더 : dmplugin.h 로 선언.


IDirectMusicTrack8::Play

트럭의 연주를 실시한다. 이 메소드는, 메세지의 생성과 송신 등, 세그먼트(segment)의 연주시에 트럭이 실시할 필요가 있는 임의의 조작을 실행한다.

HRESULT Play(
  void* pStateData,
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  MUSIC_TIME mtOffset
  DWORD dwFlags,
  IDirectMusicPerformance* pPerf,
  IDirectMusicSegmentState* pSegSt,
  DWORD dwVirtualID
);

파라미터

pStateData
IDirectMusicTrack8::InitPlay 메소드가 돌려준 상태 데이터에의 포인터. 데이터의 포맷과 사용 방법은, 트럭에 고유하다.
mtStart
시작 타임.
mtEnd
종료 타임.
mtOffset
IDirectMusicPerformance8::SendPMsg 에게 건네지는 모든 메세지에 추가되는 오프셋(offset).
dwFlags
이 호출 상태를 나타내는 플래그. 「DMUS_TRACKF_FLAGS 」를 참조할것. 값 0 은,Play 의 호출에 의해, 재생이 전의 호출로부터 계속되는 것을 의미한다.
pPerf
메세지의 할당과 송신에 사용되는 퍼포먼스.
pSegSt
이 트럭이 소속하는 세그먼트(segment) 상태. IDirectMusicSegmentState8:: QueryInterface 메소드는,IDirectMusicGraph8::StampPMsg 를 호출하는 경우 등,IDirectMusicGraph8 인터페이스를 취득하기 위해서 호출할 수가 있다.
dwVirtualID
트럭의 가상 식별자. IDirectMusicPerformance8::SendPMsg 로부터 건네받는 모든 메세지의 dwVirtualTrackID 멤버 ( 「DMUS_PMSG 」를 참조)에 이 값을 기입하지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_END 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_POINTER

주의

트럭이 하늘의 경우, 이 메소드는 DMUS_S_END 를 돌려준다.

트럭은, 우선 순위가 중저도의 thread내에 메세지를 생성한다. 파일의 데이터를 스트림화하는 코드 등, 시간이 걸리는 함수를, 트럭의 Play 메소드내로부터 호출할 수가 있다. 다만, 안전한 multi-thread화를 위한 가이드 라인에 따르는 것.

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicTrack8::PlayEx


IDirectMusicTrack8::PlayEx

트럭의 연주를 클락 타임에 실시한다. 이 메소드는, 메세지의 생성과 송신 등, 세그먼트(segment)의 연주시에 트럭이 실시할 필요가 있는 임의의 조작을 실행한다.

HRESULT PlayEx(
  void* pStateData,
  REFERENCE_TIME rtStart,
  REFERENCE_TIME rtEnd,
  REFERENCE_TIME rtOffset,
  DWORD dwFlags,
  IDirectMusicPerformance* pPerf,
  IDirectMusicSegmentState* pSegSt,
  DWORD dwVirtualID
);

파라미터

pStateData
IDirectMusicTrack8::InitPlay 메소드가 돌려준 상태 데이터에의 포인터. 데이터의 포맷과 사용 방법은, 트럭에 고유하다.
rtStart
시작 타임.
rtEnd
종료 타임.
rtOffset
IDirectMusicPerformance8::SendPMsg 에게 건네지는 모든 메세지에 추가되는 오프셋(offset).
dwFlags
이 호출 상태를 나타내는 플래그. 「DMUS_TRACKF_FLAGS 」를 참조할것. 값 0 은,PlayEx 의 호출에 의해, 재생이 전의 호출로부터 계속되는 것을 의미한다.
pPerf
메세지의 할당과 송신에 사용되는 퍼포먼스.
pSegSt
이 트럭이 소속하는 세그먼트(segment) 상태. IDirectMusicSegmentState8:: QueryInterface 메소드는,IDirectMusicGraph8::StampPMsg 을 호출하는 경우 등,IDirectMusicGraph8 인터페이스를 취득하기 위해서 호출할 수가 있다.
dwVirtualID
트럭의 가상 식별자. IDirectMusicPerformance8::SendPMsg 로부터 건네받는 모든 메세지의 dwVirtualTrackID 멤버 ( 「DMUS_PMSG 」를 참조)에 이 값을 기입하지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 또는 DMUS_S_END 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_NOT_INIT
E_POINTER

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicTrack8::Play


IDirectMusicTrack8::RemoveNotificationType

트럭으로부터의 이벤트 통지를 삭제한다. IDirectMusicSegment8::RemoveNotificationType 를 닮아 있어, 이 메소드로부터 불려 간다.

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
삭제되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). 정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것.

반환값

성공했을 경우는 S_OK 를 돌려준다. 트럭이 통지 타입을 지원 하지 않는 경우는 S_FALSE 를 돌려준다.

트럭이 통지를 지원 하지 않는 경우는,E_NOTIMPL 를 돌려준다.

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicTrack8::AddNotificationType ,통지와 이벤트의 처리


IDirectMusicTrack8::SetParam

데이터를 트럭에 뮤직 타임에 설정한다.

HRESULT SetParam(
  REFGUID rguidType,
  MUSIC_TIME mtTime,
  void* pParam
);

파라미터

rguidType
설정되는 데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
mtTime
데이터를 설정하는 타임. 트럭 시간에 지정한다.
pParam
데이터를 보관 유지하는 구조체의 주소. 데이터가 필요없는 경우는 NULL 를 지정한다. 이 구조체는,rguidType 로 식별된 데이터형에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_SET_UNSUPPORTED
DMUS_E_TYPE_DISABLED
E_OUTOFMEMORY
E_POINTER

주의

보다 강한 기능이 필요한 경우에는,IDirectMusicTrack8::SetParamEx 메소드를 사용할 수 있다.

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicTrack8::GetParam ,IDirectMusicTrack8::IsParamSupported ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::SetParam ,트럭 파라미터의 설정과 취득


IDirectMusicTrack8::SetParamEx

데이터를 트럭에, 클락 타임이나 뮤직 타임에 설정한다.

HRESULT SetParamEx(
  REFGUID rguidType,
  REFERENCE_TIME rtTime,
  void* pParam,
  void * pStateData,
  DWORD dwFlags
 );

파라미터

rguidType
설정되는 데이터형의 식별자에의 참조 (C++) 또는 주소 (C). 「표준 트럭 파라미터」를 참조할것.
rtTime
데이터의 설정을 실시하는 타임. dwFlags 에 DMUS_TRACK_PARAMF_CLOCK 가 설정되어 있지 않은 경우, 이것은 뮤직 타임이다.
pParam
데이터를 보관 유지하는 구조체의 주소. 데이터가 필요없는 경우는 NULL 를 지정한다. 이 구조체는,rguidType 로 식별된 데이터형에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.
pStateData
트럭 상태 데이터를 보관 유지하는 버퍼에의 포인터.
dwFlags
0 또는 다음의 플래그를 지정한다.
DMUS_TRACK_PARAMF_CLOCK
rtTime 의 값은, 클락 타임에 나타내진다.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DMUS_E_SET_UNSUPPORTED
DMUS_E_TYPE_DISABLED
E_OUTOFMEMORY
E_POINTER

동작환경

헤더 : dmplugin.h 로 선언.

참조

IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParam


IKsControl

IKsControl 인터페이스는, 프로퍼티, 이벤트, 및 메소드의 지원을 취득, 설정, 또는 문의하기 위해서(때문에) 사용된다. 이 인터페이스는, Windows 드라이버 모델 커넬 스트리밍 아키텍쳐의 일부이지만, DirectMusic 에 의해도 사용되어 DirectMusic 포토의 프로퍼티를 공개한다. 이 인터페이스를 취득하려면 ,riid 파라미터에 IID_IKsControl 를 지정해 IDirectMusicPort8::QueryInterface 메소드를 호출한다.

프로퍼티 항목의 요구를 포토에 대해서 송신하는 작업은, 포토의 이행에 의존한다. Win32 핸들 베이스의 멀티미디어 호출 (midiOut 와 midiIn 의 각 함수)을 이용해 DirectMusic 의 에뮬레이션을 실시하고 있는 포토는, 어느 프로퍼티도 지원 하지 않는다.

플러그 가능한 소프트웨어 신디사이저를 나타내는 포토에 대해서 프로퍼티 항목을 요구 하면, 완전하게 유저 모드로 응답이 이루어진다. 이 타입의 포토의 위상기하학은, 세면대 노드 (IDirectMusicSynthSink인터페이스)에 접속된 신디사이저 (IDirectMusicSynth인터페이스에 의해 나타내진다)이다. 이 프로퍼티 요구는 최초로 신디사이저 노드에 할당할 수 있어 신디사이저가 이 요구를 인식하지 않는 경우는 세면대 노드에 할당할 수 있다.

이 인터페이스는, 이하의 메소드를 지원 한다. 현재로서는,KsProperty 만이 DirectMusic 에 의해 지원 되고 있다.

IKsControl | KsProperty
 | KsEvent
 | KsMethod

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmksctrl.h 로 선언.

참조

DirectMusic 포토의 프로퍼티 세트


IKsControl::KsProperty

프로퍼티의 값을 취득 또는 설정한다. 개요에 대해서는, 「DirectMusic 포토의 프로퍼티 세트」를 참조할것.

HRESULT KsProperty(
  PKSPROPERTY pProperty,
  ULONG ulPropertyLength,
  LPVOID pvPropertyData,
  ULONG ulDataLength,
  PULONG pulBytesReturned
);

파라미터

pProperty
프로퍼티 세트, 항목, 실행하는 조작을 지정하는 KSPROPERTY 구조체의 주소. 이 프로퍼티에 인스턴스 데이터가 포함되는 경우, 그 데이터는 메모리내에서 구조체의 바로 후에 놓여지지 않으면 안 된다.
ulPropertyLength
pProperty 가 가리키는 메모리의 길이. 임의의 인스턴스 데이터도 포함한다.
pvPropertyData
설정 조작의 경우, 프로퍼티의 새로운 값을 나타내는 데이터를 포함한 메모리 버퍼의 주소. 취득 조작의 경우, 프로퍼티의 값을 충분히 보관 유지할 수 있는 메모리의 주소. 기본적인 지원의 문의의 경우, 사이즈가 최악이어도 DWORD 의 버퍼의 주소.
ulDataLength
pvPropertyData 가 가리키는 버퍼의 길이.
pulBytesReturned
KSPROPERTY_TYPE_GET 또는 KSPROPERTY_TYPE_BASICSUPPORT 의 호출로, 포토에 의해 pvPropertyData 에 돌려주어지는 바이트수를 받는 변수의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY
E_POINTER
DMUS_E_UNKNOWN_PROPERTY

동작환경

헤더 : dmksctrl.h 로 선언.

참조

DirectMusic 포토의 프로퍼티 세트


IReferenceClock

IReferenceClock 인터페이스는, 시스템 기준 타임을 나타낸다. DirectMusic master clock와 포토의 지연 시간 클락은, 이 인터페이스를 이행 한다.

이 인터페이스는, 이하의 메소드를 지원 한다.

IReferenceClock | GetTime
 | AdviseTime
 | AdvisePeriodic
 | Unadvise

모든 COM 인터페이스는 IUnknown 인터페이스의 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dmusicc.h 로 선언.

참조

IDirectMusic8::GetMasterClock ,IDirectMusicPort8::GetLatencyClock ,타이밍


IReferenceClock::AdvisePeriodic

지속 시간이 경과한 것을 나타내는, 비동기의 정기적인 통지를 요구한다.

HRESULT AdvisePeriodic(
  REFERENCE_TIME rtStartTime,
  REFERENCE_TIME rtPeriodTime,
  HANDLE hSemaphore,
  DWORD * pdwAdviseCookie
);

파라미터

rtStartTime
통지가 시작 되는 타임.
rtPeriodTime
통지를 하는 간격.
hSemaphore
어드바이스를 행하기 위한 수단이 되는 semaphore의 핸들.
pdwAdviseCookie
요구의 식별자를 받는 변수의 주소. 이것을 사용해, 장래, 요구를 캔슬하는 경우 등에,AdvisePeriodic 의 호출을 식별한다.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

주의

rtStartTime 에 의해 나타나는 타임에 이르렀을 경우, 핸들이 hSemaphore 로서 설정되어 있는 semaphore가 해방된다. 그 이후, semaphore는 rtPeriodTime 의 기간을 사용해 반복적으로 해방된다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IReferenceClock::Unadvise


IReferenceClock::AdviseTime

시간이 경과한 것을 나타내는, 비동기의 통지를 요구한다.

HRESULT AdviseTime(
  REFERENCE_TIME rtBaseTime,
  REFERENCE_TIME rtStreamTime,
  HANDLE hEvent,
  DWORD * pdwAdviseCookie
);

파라미터

rtBaseTime
기본이 되는 기준 타임.
rtStreamTime
스트림 오프셋(offset) 타임.
hEvent
어드바이스를 행하기 위한 수단이 되는 이벤트의 핸들.
pdwAdviseCookie
요구의 식별자를 받는 변수의 주소. 이것을 사용해, 장래, 요구를 캔슬하는 경우 등에,AdviseTime 의 호출을 식별한다.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

주의

rtBaseTime 와 rtStreamTime 를 더한 타임에 이르면(자), 핸들이 hEvent 의 이벤트가 설정된다. 타임이 이미 경과하고 있는 경우, 이벤트는 즉석에서 설정된다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

IReferenceClock::Unadvise


IReferenceClock::GetTime

현재의 타임을 취득한다.

HRESULT GetTime(
  REFERENCE_TIME * pTime
);

파라미터

pTime
현재의 타임을 받는 변수의 주소.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

동작환경

헤더 : dmusicc.h 로 선언.


IReferenceClock::Unadvise

통지의 요구를 캔슬한다.

HRESULT Unadvise(
  DWORD dwAdviseCookie
);

파라미터

dwAdviseCookie
IReferenceClock::AdviseTime 메소드 또는 IReferenceClock::AdvisePeriodic 메소드로 설정되어 있는, 캔슬하는 요구의 식별자.

반환값

반환값은 이행에 의해 정해진다. 성공했을 경우는 S_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

동작환경

헤더 : dmusicc.h 로 선언.


DirectMusic 메세지

DirectMusic 의 메세지 구조체는, 모두 DMUS_PMSG 구조체에 근거하고 있다. C 는 계승을 지원 하고 있지 않기 때문에, 이 구조체의 멤버는 DMUS_PMSG_PART 매크로로서의 각파생 구조체에 포함된다.

메세지의 개요에 대해서는, 「DirectMusic 메세지의 사용법」을 참조할것.

여기에서는, 메세지 정보의 보관 유지에 사용되는 이하의 구조체에 대해 설명한다.

  • DMUS_PMSG
  • DMUS_CHANNEL_PRIORITY_PMSG
  • DMUS_CURVE_PMSG
  • DMUS_LYRIC_PMSG
  • DMUS_MIDI_PMSG
  • DMUS_NOTE_PMSG
  • DMUS_NOTIFICATION_PMSG
  • DMUS_PATCH_PMSG
  • DMUS_SYSEX_PMSG
  • DMUS_TEMPO_PMSG
  • DMUS_TIMESIG_PMSG
  • DMUS_TRANSPOSE_PMSG
  • DMUS_WAVE_PMSG

참조

IDirectMusicPerformance8::AllocPMsg ,IDirectMusicPerformance8::SendPMsg ,IDirectMusicPerformance8::FreePMsg ,IDirectMusicTool8::ProcessPMsg


DMUS_PMSG

모든 DirectMusic 메세지에 공통되는 정보를 보관 유지한다. C 는 계승을 지원 하고 있지 않기 때문에, 다음의 구문에 전개되는 DMUS_PMSG_PART 매크로를 포함하는 것으로, 이 구조체의 멤버는 모든 메세지 타입 (DMUS_PMSG 자체를 포함한다)에 포함된다.

typedef struct DMUS_PMSG {
    DWORD              dwSize;
    REFERENCE_TIME     rtTime;
    MUSIC_TIME         mtTime;
    DWORD              dwFlags;
    DWORD              dwPChannel;
    DWORD              dwVirtualTrackID;
    IDirectMusicTool*  pTool;
    IDirectMusicGraph* pGraph;
    DWORD              dwType;
    DWORD              dwVoiceID;
    DWORD              dwGroupID;
    IUnknown*          punkUser;
} DMUS_PMSG;
dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 멤버는,IDirectMusicPerformance8::AllocPMsg 로 초기화된다.
rtTime
메세지의 연주를 시작 하는 기준 타임. dwFlags 에 의해 변경된다. DMUS_PMSGF_REFTIME 가 dwFlags 내에 있는 경우에게만 사용된다.
mtTime
메세지의 연주를 시작 하는 뮤직 타임. dwFlags 에 의해 변경된다. DMUS_PMSGF_MUSICTIME 가 dwFlags 내에 있는 경우에게만 사용된다.
dwFlags
DMUS_PMSGF_FLAGS 열거형 또는 DMUS_TIME_RESOLVE_FLAGS 열거형의 플래그. DMUS_PMSGF_REFTIME 또는 DMUS_PMSGF_MUSICTIME 를 보관 유지하고 있지 않으면 안 된다.
dwPChannel
퍼포먼스 채널 (P 채널). IDirectMusicPerformance8::PChannelInfo 메소드를 사용해, 이 값으로부터 포토, 채널 그룹, 및 MIDI 채널을 파생할 수 있다. 템포 메세지 등, 채널 고유하지 않는 메세지에 대해서는, 이 값을 0 으로 설정한다. 메세지를 복수의 채널에 송신하려면 , 다음의 몇개의 값을 사용한다.
DMUS_PCHANNEL_BROADCAST_AUDIOPATH
메세지의 카피를 오디오 패스의 모든 채널에 송신한다.
DMUS_PCHANNEL_BROADCAST_GROUPS
메세지의 카피를 퍼포먼스내의 각각의 채널 그룹에 송신한다. 시스템에크스크루시브멧세이지 등, 메세지를 각 채널 그룹에 한 번만 송신할 필요가 있는 경우에 사용한다.
DMUS_PCHANNEL_BROADCAST_PERFORMANCE
메세지의 카피를 퍼포먼스의 모든 채널에 송신한다.
DMUS_PCHANNEL_BROADCAST_SEGMENT
메세지의 카피를 세그먼트(segment)의 모든 채널에 송신한다.
dwVirtualTrackID
트럭의 식별자. 메세지가 트럭에 의해 송신되어 있지 않은 경우는, 0 으로 설정한다.
pTool
툴 인터페이스의 주소. IDirectMusicGraph8::StampPMsg 를 사용해 설정할 수 있다. 메세지가 출력 툴 이외의 툴에 보내지지 않는 경우는 NULL 로 설정할 수 있다.
pGraph
툴 그래프 인터페이스의 주소. IDirectMusicGraph8::StampPMsg 를 사용해 설정할 수 있다. 메세지가 출력 툴 이외의 툴에 보내지지 않는 경우는 NULL 로 설정할 수 있다.
dwType
메세지 타입 ( 「DMUS_PMSGT_TYPES 」를 참조).
dwVoiceID
예약이 끝난 상태. 0 이 아니면 안된다.
dwGroupID
메세지가 트럭에 의해 생성되고 있는 경우, 그 메세지가 소속하는 트럭 그룹 또는 그룹의 식별자 (트럭은,IDirectMusicSegment8::InsertTrack 메소드로 그룹에 할당할 수 있다). 대부분의 목적에 대해, 이 값은 0xFFFFFFF 이라도 좋다.
punkUser
어플리케이션에 의해 제공되는 IUnknown 인터페이스의 주소. 이 포인터는, 메세지를 해방했을 때에 항상 해방된다. 어플리케이션으로 오브젝트를 보관 유지하는 경우는, 메세지를 해방하기 전에,AddRef 를 호출하지 않으면 안 된다. 메세지가 COM 포인터를 필요로 하지 않는 경우, 이 값은 NULL 이라도 좋다.

주의

DMUS_PMSG 구조체는,dwType 멤버에 이하의 값을 보관 유지하는 메세지에 대해, 그 자체에 의해 사용된다.

DMUS_PMSGT_STOP
이 타입의 메세지를 송신 하면, 지정된 타임에 퍼포먼스가 정지한다.
DMUS_PMSGT_DIRTY
제어 세그먼트(segment)가 시작 또는 종료 하면 와, 세그먼트(segment) 및 퍼포먼스 그래프내의 모든 툴은, 이 타입의 메세지를 받아들인다. 이것은, 세그먼트(segment)내의 모든 툴과 퍼포먼스 그래프가, 파라미터 취득 메소드의 호출로 데이터를 캐싱 하는 경우, 같은 메소드를 재차 호출해, 각각의 데이터를 갱신해야 하는 것을 의미한다. 이 메세지 타입이 필요한 툴은,IDirectMusicTool8::GetMediaTypes 의 호출로 이것을 지정해야 한다. 퍼포먼스 그래프내의 툴은, 퍼포먼스내의 각 세그먼트(segment)에 대해, 메세지의 카피를 1 부만 받는다. 이러한 툴은, 같은 타임 스탬프가 붙은 여분의 메세지를 무시해도 안전하다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SendPMsg


DMUS_CHANNEL_PRIORITY_PMSG

채널 우선 순위 변경에 관한 메세지 데이터를 보관 유지한다.

typedef struct _DMUS_CHANNEL_PRIORITY_PMSG {
    DMUS_PMSG_PART
    DWORD dwChannelPriority;
} DMUS_CHANNEL_PRIORITY_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
dwChannelPriority
채널의 우선 순위. 정의 끝난 값의 리스트에 대해서는, 「IDirectMusicPort8::GetChannelPriority 」의 「주의」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPort8::SetChannelPriority ,IDirectMusicPerformance8::SendPMsg


DMUS_CURVE_PMSG

커브의 메세지 데이터를 보관 유지한다.

typedef struct DMUS_CURVE_PMSG {
    DMUS_PMSG_PART
    MUSIC_TIME mtDuration;
    MUSIC_TIME mtOriginalStart;
    MUSIC_TIME mtResetDuration;
    short      nStartValue;
    short      nEndValue;
    short      nResetValue;
    WORD       wMeasure;
    short      nOffset;
    BYTE       bBeat;
    BYTE       bGrid;
    BYTE       bType;
    BYTE       bCurveShape;
    BYTE       bCCData;
    BYTE       bFlags;
    WORD       wParamType;
    WORD       wMergeIndex;
} DMUS_CURVE_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
mtDuration
커브의 지속 시간. 이 값은,DMUS_PMSG_PART 의 dwFlags 멤버에 DMUS_PMSGF_LOCKTOREFTIME 가 존재하는 경우를 제외해, 뮤직 타임에 지정한다. 이 경우의 단위는 밀리 세컨드 단위가 되어, 템포의 변화에 의해 영향을 받을 것은 없다.
mtOriginalStart
오리지날의 시작 타임. 메세지를 생성 하면나무는 0 또는 커브의 오리지날의 시작 타임으로 설정해야 한다.
mtResetDuration
무효화에 응답해 리셋 할 수 있는 동안의 커브의 마지막 후의 시간의 길이. bFlags 내에 DMUS_CURVE_RESET 가 없는 경우는 무시된다. 이 값은,DMUS_PMSG_PART 의 dwFlags 멤버에 DMUS_PMSGF_LOCKTOREFTIME 가 존재하는 경우를 제외해, 뮤직 타임에 지정한다. 이 경우의 단위는 밀리 세컨드 단위가 되어, 템포의 변화에 의해 영향을 받을 것은 없다.
nStartValue
커브의 시작값.
nEndValue
커브의 종료값.
nResetValue
플래시 (해방) 또는 무효화를 설정하는 값. bFlags 내에 DMUS_CURVE_RESET 가 없는 경우는 무시된다.
wMeasure
커브가 발생하는 소절.
nOffset
커브가 발생하는구라두로부터의 오프셋(offset). 뮤직 타임에 나타내진다.
bBeat
이 커브가 발생하는 (소절내의) 박수.
bGrid
이 커브가 발생하는 박으로부터의구라두 오프셋(offset).
bType
커브의 타입. 다음의 몇개의 값을 지정할 수 있다.
DMUS_CURVET_CCCURVE
콘티뉴어스 콘트롤러 커브 (MIDI Control Change 채널 음성 메세지. 스테이터스 바이트는 &HBn).
DMUS_CURVET_MATCURVE
단청의 애프터 터치 커브 (MIDI Channel Pressure 채널 음성 메세지. 스테이터스 바이트는 &HDn).
DMUS_CURVET_PATCURVE
다선율 애프터 터치 커브 (MIDI Poly Key Pressure 채널 음성 메세지. 스테이터스 바이트는 &HDn).
DMUS_CURVET_PBCURVE
핏치벤드카브 (MIDI Pitch Bend 채널 음성 메세지. 스테이터스 바이트는 &HEn).
DMUS_CURVET_RPNCURVE
wParamType 에 정의된 타입의 RPN 커브.
DMUS_CURVET_NRPNCURVE
wParamType 에 정의된 타입의 NRPN 커브.
bCurveShape
커브의 셰이프. 다음의 몇개의 값을 지정할 수 있다.
DMUS_CURVES_EXP
지수 커브 셰이프.
DMUS_CURVES_INSTANT
즉시 커브 셰이프 (커브의 시작과 종료가 거의 동시에 발생한다).
DMUS_CURVES_LINEAR
선상 커브 셰이프.
DMUS_CURVES_LOG
대수 커브 셰이프.
DMUS_CURVES_SINE
정현 커브 셰이프.
bCCData
bType 가 DMUS_CURVET_CCCURVE 의 경우는 콘트롤러 번호.
bFlags
0 또는 다음의 1 개 이상의 값을 지정할 수 있다.
DMUS_CURVE_RESET
디폴트의 타임에 이르렀을 때, 또는 트란지션이 원인으로 무효화가 발생했을 때는,nResetValue 에 이 값을 설정해야 한다. 플래그가 설정되어 있지 않은 경우, 커브는 새로운 값에 영속적에 머무른다.
DMUS_CURVE_START_FROM_CURRENT
nStartValue 를 무시해, 현재의 값의 커브를 시작 한다. 볼륨, 에크스프렛션, 핏치벤드, 필터 절단, 빵, 및 못드호이르용으로 이행 된다. 「주의」를 참조할것.
wParamType
MIDI 파라미터 번호. DMUS_PMSGF_DX8 가 이 구조체의 DMUS_PMSG 부분의 dwFlags 멤버안에 존재하는 경우만, 이 값은 의미를 가진다. 「주의」를 참조할것.
wMergeIndex
머지 인덱스. 핏치벤드, 볼륨, 및 에크스프렛션콘트로라용으로 지원 된다. DMUS_PMSGF_DX8 가 이 구조체의 DMUS_PMSG 부분의 dwFlags 멤버안에 존재하는 경우만, 이 값은 의미를 가진다. 「주의」를 참조할것.

주의

wParamType 의 RPN 또는 NRPN 커브 타입은, 7 비트를 부가한 2 바이트로서 저장 된다. 예를 들어, MSB 가 0 x23, LSB 가 0x74 인 경우,wParamType 의 값은 0x2374 이다.

nStartValue,nEndValue, 및 nResetValue 내의 데이터는 14 비트에 제한된다. 7 비트의 바이트 2 개(살)로 구성되는 MIDI 데이터의 경우, 값은 비어 있는 2 비트를 부가해, 1 워드로서 저장 된다.

wMergeIndex 에 0 이 설정된 모든 커브는, 서로 오버라이드(override) 된다. wMergeIndex 가 다른 값인 경우, 커브가 생성하는 값은 머지 인덱스 0 의 값에 추가된다. 예를 들어, 어플리케이션이 0 으로 3 의 커브를 사용하는 경우, 0 커브는 항상 서로 바뀌지만 3 커브에 추가된다. 또, 3 커브도 항상 서로 바뀌지만 0 커브에 추가된다.

DMUS_CURVE_START_FROM_CURRENT 플래그는 현재의 콘트롤러값을 메세지에 보존하지 않는다. 따라서, 툴로 최종 인식값을 저장 하지 않는 한, 툴에 이 데이터에의 액세스권은 없다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SendPMsg ,커브


DMUS_LYRIC_PMSG

캐릭터 라인의 메세지 데이터를 보관 유지한다.

typedef struct _DMUS_LYRIC_PMSG {
    DMUS_PMSG_PART
    WCHAR  wszString[1];
} DMUS_LYRIC_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
wszString
NULL 로 종료하는 Unicode 캐릭터 라인. 메세지의 생성시에, 배열의 사이즈가 설정된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SendPMsg


DMUS_MIDI_PMSG

컨트롤 체인지나 핏치벤드 등, 스탠다드 MIDI 메세지의 데이터를 보관 유지한다.

typedef struct DMUS_MIDI_PMSGG {
    DMUS_PMSG_PART
    BYTE  bStatus;
    BYTE  bByte1;
    BYTE  bByte2;
    BYTE  bPad[1];
} DMUS_MIDI_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
bStatus
스탠다드 MIDI 의 스테이터스 바이트.
bByte1
MIDI 메세지의 최초의 1 바이트. 이것을 필요로 하지 않는 MIDI 메세지에서는 무시된다.
bByte2
MIDI 메세지의 2 바이트째. 이것을 필요로 하지 않는 MIDI 메세지에서는 무시된다.
bPad
WORD 경계까지의 추가.

동작환경

헤더 : dmusici.h 로 선언.

참조

MIDI 메세지,IDirectMusicPerformance8::SendPMsg


DMUS_NOTE_PMSG

MIDI 노트의 메세지 데이터를 보관 유지한다.

typedef struct DMUS_NOTE_PMSG {
    DMUS_PMSG_PART
    MUSIC_TIME mtDuration;
    WORD       wMusicValue;
    WORD       wMeasure;
    short      nOffset;
    BYTE       bBeat;
    BYTE       bGrid;
    BYTE       bVelocity;
    BYTE       bFlags;
    BYTE       bTimeRange;
    BYTE       bDurRange;
    BYTE       bVelRange;
    BYTE       bPlayModeFlags;
    BYTE       bSubChordLevel;
    BYTE       bMidiValue;
    char       cTranspose;
} DMUS_NOTE_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
mtDuration
노트의 지속 시간.
wMusicValue
노트의 기술. 대부분의 연주 모드에서는, 이하에 나타내도록(듯이), 팩 된 4 비트값의 배열이다.
Octave
－ 2 ~ 14 의 범위. 이 노트는, 1 옥타브의 12 배로 상하에 전치 된다.
Chord position
0 ~ 15 의 범위이지만, 3 을 넘어서는 안 된다. 코드내의 최초의 위치는 0 이다.
Scale position
0 ~ 15 의 범위. 보통은 0 ~ 2 의 범위이지만, 1 노트의 코드로 해, 코드의 위에의 모든 것을 스케일 위치로서 해석하는 일도 가능.
Accidental
－ 8 ~ 7 의 범위이지만, 보통은 － 2 ~ 2 의 범위. 이것은, 스케일로부터 노트를 꺼내는 오프셋(offset)를 나타낸다.

고정 연주 모드에서는, 뮤직값은 0 ~ 127 의 범위에 있는 MIDI 노트의 값이다.

wMeasure
노트가 발생하는 소절.
nOffset
노트가 발생하는구라두로부터의 오프셋(offset). 뮤직 타임에 나타내진다.
bBeat
이 노트가 발생하는 (소절내에서의) 박.
bGrid
이 노트가 발생하는 박으로부터의 구라두 오프셋(offset).
bVelocity
노트의velocity .
bFlags
「DMUS_NOTEF_FLAGS 」를 참조할것.
bTimeRange
랜덤 시간의 범위.
bDurRange
지속 시간을 랜덤화하는 범위.
bVelRange
velocity를 랜덤화하는 범위.
bPlayModeFlags
뮤직값이 코드와 서브 코드에 어떻게 관련할까를 결정하는 연주 모드. 값의 리스트에 대해서는, 「DMUS_PLAYMODE_FLAGS 」를 참조할것.
bSubChordLevel
노트가 사용하는 서브 코드 레벨. 「DMUS_SUBCHORD 」를 참조할것.
bMidiValue
wMusicValue 로부터 변환된, MIDI 노트의 값.
cTranspose
wMusicValue 로부터의 변환 후에 bMidiValue 에 추가하는 전조.

주의

출력 툴이 bFlags 의 DMUS_NOTEF_NOTEON 로 메세지를 받아들이는 경우는, MIDI 노트 온 메세지가 신디사이저에 보내진다. 다음에 DMUS_NOTEF_NOTEON 플래그를 소거해, 타임 스탬프에 mtDuration 를 더해 메세지를 요구한다. 그 결과, 적절한 타임에 노트는 종료한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SendPMsg ,뮤직값과 MIDI 노트


DMUS_NOTIFICATION_PMSG

통지의 메세지 데이터를 보관 유지한다.

typedef struct DMUS_NOTIFICATION_PMSG {
    DMUS_PMSG_PART
    GUID   guidNotificationType;
    DWORD  dwNotificationOption;
    DWORD  dwField1;
    DWORD  dwField2;
} DMUS_NOTIFICATION_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
guidNotificationType
통지 타입의 식별자. 다음의 타입이 정의되고 있다.
GUID_NOTIFICATION_CHORD
코드 체인지.
GUID_NOTIFICATION_COMMAND
커멘드 이벤트.
GUID_NOTIFICATION_MEASUREANDBEAT
소절 및 박이벤트.
GUID_NOTIFICATION_PERFORMANCE
퍼포먼스 이벤트. dwNotificationOption 로 한층 더 정의된다.
GUID_NOTIFICATION_RECOMPOSE
트럭은 재어레인지 되었다. 현재의 버젼에서는, 이것은 항상 코드 트럭이다.
GUID_NOTIFICATION_SEGMENT
세그먼트(segment) 이벤트. dwNotificationOption 로 한층 더 정의된다.
dwNotificationOption
통지 서브 타입의 식별자.

통지 타입이 GUID_NOTIFICATION_SEGMENT 의 경우, 이 멤버는 다음의 몇개의 값을 보관 유지한다.

DMUS_NOTIFICATION_SEGABORT
세그먼트(segment)가 도중에 정지했다. 또는 프라이머리 세그먼트(segment)의 큐로부터 삭제되었다.
DMUS_NOTIFICATION_SEGALMOSTEND
세그먼트(segment)가 종료 타임부터준비 시간을 당긴 타임에 이르렀다.
DMUS_NOTIFICATION_SEGEND
세그먼트(segment)가 종료했다.
DMUS_NOTIFICATION_SEGLOOP
세그먼트(segment)가 루프 했다.
DMUS_NOTIFICATION_SEGSTART
세그먼트(segment)가 시작 했다.

통지 타입이 GUID_NOTIFICATION_COMMAND 의 경우, 이 멤버는 다음의 몇개의 값을 보관 유지한다.

DMUS_NOTIFICATION_GROOVE
홈 레벨이 변화한다.
DMUS_NOTIFICATION_EMBELLISHMENT
장식 커멘드 (인트로, 필, 브레이크, 또는 엔드).

통지 타입이 GUID_NOTIFICATION_PERFORMANCE 의 경우, 이 멤버는 다음의 몇개의 값을 보관 유지한다.

DMUS_NOTIFICATION_MUSICALMOSTEND
현재 재생중의 프라이머리 세그먼트(segment)가, 종료 타임부터 준비 시간을 당긴 타임에 이르렀지만, 큐에는 이제 재생하는 프라이머리 세그먼트(segment)는 없다.
DMUS_NOTIFICATION_MUSICSTARTED
재생이 시작 했다.
DMUS_NOTIFICATION_MUSICSTOPPED
재생이 정지했다.

통지 타입이 GUID_NOTIFICATION_MEASUREANDBEAT 의 경우, 이 멤버는 DMUS_NOTIFICATION_MEASUREBEAT 를 보관 유지한다. 그 외의 서브 타입은 정의되지 않는다.

통지 타입이 GUID_NOTIFICATION_CHORD 의 경우, 이 멤버는 DMUS_NOTIFICATION_CHORD 를 보관 유지한다. 그 외의 서브 타입은 정의되지 않는다.

통지 타입이 GUID_NOTIFICATION_RECOMPOSE 의 경우, 이 멤버는 DMUS_NOTIFICATION_RECOMPOSE 를 보관 유지한다. 그 외의 서브 타입은 정의되지 않는다.

dwField1
통지 타입에 고유의 추가 데이터. GUID_NOTIFICATION_MEASUREANDBEAT 통지의 경우, 이 멤버는 소절내의 박번호를 돌려준다.
dwField2
통지 타입에 고유의 추가 데이터. 장래의 사용 또는 어플리케이션에 의해 정의되는 사용에 대비해 예약되고 있다.

주의

대부분의 통지에 대해,punkUser 멤버 ( 「DMUS_PMSG 」를 참조)는, 세그먼트(segment) 상태의 IUnknown 포인터를 보관 유지한다. 이것은, 코드 및 커멘드의 취득에 사용 하면 매우 편리하다. 그 경우,IDirectMusicSegmentState8 인터페이스를 조회해,IDirectMusicSegmentState8::GetSegment 를 호출해 IDirectMusicSegment8 포인터를 취득한다. 다음에,IDirectMusicSegment8::GetParam 메소드를 호출해, 통지 메세지의 mtTime 멤버로 지정된 타임에 코드 또는 커멘드를 취득한다.

GUID_NOTIFICATION_PERFORMANCE 타입의 통지의 경우,punkUser 멤버는 항상 NULL 이다.

어플리케이션은 독자적인 통지 메세지 타입 및 서브 타입을 정의할 수 있어 그러면 부족의 데이터에 대해서는 dwField1 와 dwField2 를 사용할 수 있다. 그러한 커스텀 통지 메세지는, 그 외의 메세지와 같게, 할당 및 송신할 수 있다. 어플리케이션에 의해 정의된 트럭은, GUID (guidNotificationType) 가 IDirectMusicTrack8::AddNotificationType 에게 건네진 후에, 특정 타입의 메세지를 송신할 수 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리,IDirectMusicPerformance8::SendPMsg


DMUS_PATCH_PMSG

MIDI 프로그램 체인지의 메세지 데이터를 보관 유지한다.

typedef struct DMUS_PATCH_PMSG {
    DMUS_PMSG_PART
    BYTE  byInstrument;
    BYTE  byMSB;
    BYTE  byLSB;
    BYTE  byPad[1];
} DMUS_PATCH_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
byInstrument
음색의 패치 번호.
byMSB
뱅크 셀렉트의 상위 바이트.
byLSB
뱅크 셀렉트의 하위 바이트.
byPad
WORD 경계까지의 추가. 이 값은 무시된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

DMUS_MIDI_PMSG ,IDirectMusicPerformance8::SendPMsg ,MIDI 메세지


DMUS_SYSEX_PMSG

MIDI 시스템에크스크루시브멧세이지의 데이터를 보관 유지한다.

typedef struct DMUS_SYSEX_PMSG {
    DMUS_PMSG_PART
    DWORD dwLen;
    BYTE  abData[1];
} DMUS_SYSEX_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
dwLen
데이터의 길이. 바이트 단위로 지정한다.
abData
데이터 배열. 메모리의 할당 방법 및 데이터를 이 멤버에 카피하는 방법의 예에 대해서는, 「IDirectMusicPerformance8::SendPMsg 」의 「주의」를 참조할것.

주의

시스템에크스크루시브멧세이지의 데이터 부분은, 시스템에크스크루시브 식별자 (0xF0)로 시작되어, EOX (0xF7)로 끝나지 않으면 안 된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

DMUS_MIDI_PMSG ,DMUS_PATCH_PMSG ,MIDI 메세지,IDirectMusicPerformance8::SendPMsg


DMUS_TEMPO_PMSG

퍼포먼스의 템포를 제어하는 메세지의 데이터를 보관 유지한다.

typedef struct DMUS_TEMPO_PMSG {
    DMUS_PMSG_PART
    double dblTempo;
} DMUS_TEMPO_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
dblTempo
DMUS_TEMPO_MIN ~ DMUS_TEMPO_MAX 의 범위에 있는 템포.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SendPMsg


DMUS_TIMESIG_PMSG

퍼포먼스의 박자 기호를 제어하는 메세지의 데이터를 보관 유지한다.

typedef struct _DMUS_TIMESIG_PMSG {
    DMUS_PMSG_PART
    BYTE bBeatsPerMeasure;
    BYTE bBeat;
    WORD wGridsPerBeat;
} DMUS_TIMESIG_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
bBeatsPerMeasure
소절 근처의 박수 (박자 기호의 분자 ).
bBeat
노트가 받는 박 (박자 기호의 분모). 이 값이 1 때는 전노트, 2 때는 2 분 노트, 4 때는 4 분 노트를 의미한다. 이하 같이이다. 0 은 256 분 노트를 의미한다.
wGridsPerBeat
박근처의 구라두 (소분할). 이 값은, 특정의 음악 이벤트의 타이밍 분해가능을 결정한다. 예를 들어, DMUS_SEGF_GRID 플래그를 사용한 세그먼트(segment)의 삽입을 들 수 있다 ( 「DMUS_SEGF_FLAGS 」를 참조).

주의

박자 기호 메세지는, 박자 기호 트럭과 스타일 트럭에 의해 생성된다. 보통, 세그먼트(segment)에는, 박자 기호 트럭 또는 스타일 트럭의 어느 쪽인지가 포함되지만, 양쪽 모두 포함될 것은 없다. MIDI 파일을 나타내는 세그먼트(segment)에는 박자 기호 트럭이 포함되지만, DirectMusic Producer 등의 어플리케이션을 사용해 오쏘링 된 세그먼트(segment)의 대부분에는, 스타일 트럭에 박자 기호 정보가 포함된다.

디폴트에서는, 프라이머리 세그먼트(segment)만이 박자 기호 메세지를 송신한다. 이 동작을 변경하는 방법에 대해서는, 「트럭 파라미터의 무효화와 유효화」를 참조할것.

박자 기호는 퍼포먼스에 의해 사용되어DMUS_SEGF_FLAGS 또는 DMUS_TIME_RESOLVE_FLAGS 으로 타임을 조정할 수 있는 모든 메소드로, 타임을 소절, 박, 및 구라두의 경계에 해결한다. 또, 박자 기호 트럭과 스타일 트럭은, 박자 기호를 사용해, 소절 경계 및 박경계에 대한 통지를 생성한다. 「DMUS_NOTIFICATION_PMSG 」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SendPMsg ,DMUS_TIMESIGNATURE


DMUS_TRANSPOSE_PMSG

전조의 메세지 데이터를 보관 유지한다.

typedef struct _DMUS_TRANSPOSE_PMSG {
    DMUS_PMSG_PART
    short nTranspose;
    WORD wMergeIndex;
} DMUS_TRANSPOSE_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것.
nTranspose
전치 되는 반음의 수. 부의 값이어도 괜찮다.
wMergeIndex
머지 인덱스. 같은 wMergeIndex 를 가지는 선행 메세지의 뒤에 전치메세지가 계속되는 경우,nTranspose 의 값은 신규 설정이 된다. 2 번째의 전치메세지가, 다른 wMergeIndex 를 가지는 경우,nTranspose 의 값은 전의 설정에 추가된다. 이 멤버가 의미를 가지는 것은, 이 구조체의 DMUS_PMSG 부분에 포함되는 dwFlags 멤버에, DMUS_PMSGF_DX8 가 존재하는 경우뿐이다.

주의

노트의 전조에 의해, 스탠다드 MIDI 의 범위 (0 ~ 127)보다 외측에 이르렀을 경우는, 그 노트는 연주되지 않는다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SendPMsg


DMUS_WAVE_PMSG

웨이브 사운드의 메세지 데이터를 보관 유지한다.

typedef struct _DMUS_WAVE_PMSG {
    DMUS_PMSG_PART
    REFERENCE_TIME rtStartOffset;
    REFERENCE_TIME rtDuration;
    long    lOffset;
    long    lVolume;
    long    lPitch;
    BYTE    bFlags;
} DMUS_WAVE_PMSG;
;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. 「DMUS_PMSG 」를 참조할것. punkUser 멤버에는, 웨이브에 관련지을 수 있었던 음성 오브젝트의,IUnknown 인터페이스의 주소가 포함된다.
rtStartOffset
웨이브의 시작 지점까지의 타임. 기준 타임 단위만으로 지정한다.
rtDuration
커브의 지속 시간. DMUS_PMSG_PART 의 dwFlags 멤버에 DMUS_PMSGF_LOCKTOREFTIME 가 존재하는 경우, 이 값의 단위는 기준 타임이 된다. 그 이외의 경우는, 뮤직 타임 단위로 나타내진다.
lOffset
실제의 타임부터 논리 위에의 타임까지의 오프셋(offset). 기준 타임 또는 뮤직 타임의 어느 쪽인지로 지정한다.
lVolume
초기 볼륨. 1/100 dB (데시벨) 단위로 지정한다.
lPitch
전조의 피치. 1/100 반음 단위로 지정한다.
bFlags
0 또는 다음의 값을 지정한다.
DMUS_WAVEF_NOINVALIDATE
이 웨이브를 무효로 하지 않는다.
DMUS_WAVEF_OFF
이 메세지에 의해, 웨이브의 재생이 정지중이다.
DMUS_WAVEF_STREAMING
웨이브는 스트림 하고 있다.

주의

IDirectMusicPerformance8::SendPMsg 를 사용하면(자), 어플리케이션은 웨이브 오브젝트에의 포인터를 취득하는 수단이 없기 때문에, 이 타입의 메세지를 송신할 수 없다. 다만, 툴은 웨이브 메세지를 처리할 수 있다.

동작환경

헤더 : dmusici.h 로 선언.


DirectMusic 구조체

여기에서는, DirectMusic 으로 사용되는 다음의 런타임 구조체에 관한 레퍼런스 정보를 기술한다.

  • DMUS_AUDIOPARAMS
  • DMUS_BAND_PARAM
  • DMUS_BUFFERDESC
  • DMUS_CHORD_KEY
  • DMUS_CHORD_PARAM
  • DMUS_CLOCKINFO8
  • DMUS_COMMAND_PARAM
  • DMUS_COMMAND_PARAM_2
  • DMUS_CONNECTION_RULE
  • DMUS_EVENTHEADER
  • DMUS_MUTE_PARAM
  • DMUS_NOTERANGE
  • DMUS_OBJECTDESC
  • DMUS_PLAY_MARKER_PARAM
  • DMUS_PORTCAPS
  • DMUS_PORTPARAMS8
  • DMUS_RHYTHM_PARAM
  • DMUS_SCRIPT_ERRORINFO
  • DMUS_SUBCHORD
  • DMUS_SYNTHSTATS8
  • DMUS_TEMPO_PARAM
  • DMUS_TIMESIGNATURE
  • DMUS_VALID_START_PARAM
  • DMUS_VARIATIONS_PARAM
  • DMUS_VERSION
  • DMUS_WAVES_REVERB_PARAMS
  • KSPROPERTY

구조체의 특별한 카테고리는, 이하의 주제로 설명한다.

  • DirectMusic 메세지
  • DirectMusic 의 파일 데이터 구조체
  • DLS 구조체


DMUS_AUDIOPARAMS

디폴트의 신디사이저 및 퍼포먼스의 버퍼에 필요한 리소스를 기술한다. 필요한 기능을 요구하기 위해(때문에), 및 어느 요구가 허가되었는지를 관한 정보를 받기 위해서(때문에),IDirectMusicPerformance8::InitAudio 메소드에게 건네진다.

typedef struct _DMUS_AUDIOPARAMS {
    DWORD  dwSize;
    BOOL   fInitNow;
    DWORD  dwValidData;
    DWORD  dwFeatures;
    DWORD  dwVoices;
    DWORD  dwSampleRate;
    CLSID  clsidDefaultSynth;
} DMUS_AUDIOPARAMS;
dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
fInitNow
세면대와 신디사이저를 즉시에 생성 할지 어떨지를 지정하는 불리언 값. 즉시 생성 하는 경우는, 이 구조체에 결과가 돌려주어진다.
dwValidData
이 구조체의 어느 멤버가 유효한가를 나타내는 플래그. 구조체가 건네받았을 때에 fInitNow 가 TRUE 이면, 어느 멤버가 데이터를 받았는지를 나타내는 플래그를 받는다. 다음의 값이 정의되고 있다.
DMUS_AUDIOPARAMS_FEATURES
dwFeatures 멤버가 데이터를 보관 유지하고 있다, 또는 받았다.
DMUS_AUDIOPARAMS_VOICES
dwVoices 멤버가 데이터를 보관 유지하고 있다, 또는 받았다.
DMUS_AUDIOPARAMS_SAMPLERATE
dwSampleRate 멤버가 데이터를 보관 유지하고 있다, 또는 받았다.
DMUS_AUDIOPARAMS_DEFAULTSYNTH
clsidDefaultSynth 멤버가 데이터를 보관 유지하고 있다, 또는 받았다. 이 플래그가 설정되어 있지 않은 경우는, Microsoft 의 소프트웨어 신디사이저가 디폴트의 신디사이저이다.
dwFeatures
필요한 기능을 지정하는 플래그. 다음의 값이 정의되고 있다.
DMUS_AUDIOF_3D
3D 버퍼.
DMUS_AUDIOF_ALL
다른 모든 플래그를 조합한 것.
DMUS_AUDIOF_BUFFERS
복수의 버퍼. 오디오 패스를 사용하는 경우는, 항상 이 플래그를 설정한다.
DMUS_AUDIOF_ENVIRON
환경 모델링.
DMUS_AUDIOF_EAX
EAX 이펙트.
DMUS_AUDIOF_DMOS
추가의 DMO .
DMUS_AUDIOF_STREAMING
스트리밍 웨이브의 지원.
dwVoices
음성의 수. 디폴트값은 64 이다.
dwSampleRate
11,025 ~ 96,000 kHz 의 범위의 세면대 및 신디사이저의 샘플링 레이트. 디폴트값은 22,050 이다.
clsidDefaultSynth
디폴트의 신디사이저의 클래스 식별자. 이것은, 표준 오디오 패스 및 디폴트의 신디사이저를 요구하는 구성으로부터 생성 된 오디오 패스로 사용되는 신디사이저이다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_BAND_PARAM

트럭이 밴드 트럭이며,rguidType 가 GUID_BandParam 인 경우, 각종의 파라미터 취득 메소드나 파라미터 설정 메소드를 호출할 때에,pParam 파라미터로서 사용된다.

typedef struct _DMUS_BAND_PARAM {
    MUSIC_TIME mtTimePhysical;
    IDirectMusicBand *pBand;
} DMUS_BAND_PARAM;

멤버

mtTimePhysical
밴드 체인지가 발생하는 실제의 타임. 「주의」를 참조할것.
pBand
밴드의 IDirectMusicBand8 인터페이스의 주소.

주의

mtTimePhysical 의 값은, 밴드 체인지가 발생하는 실제의 타임이다. 한편, 파라미터 설정 메소드의 mtTime 파라미터의 값은, 박이나 소절과 동기 한, 밴드 체인지가 속하는 퍼포먼스내의 포인트이다. mtTimePhysical 에 대해서,mtTime 보다 조금 빠른 타임을 설정하는 것으로, 밴드 체인지가 루프의 선두에 발생하는 경우에도, 노트가 항상 올바른 밴드에 의해 연주되는 것이 보증된다.

클락 타임 트럭의 경우,mtTimePhysical 는 그 트럭의 내부 시간 포맷으로 해석된다. 이것은, 재생 시작으로부터의 밀리 세컨드수이다. 이것은 혼동하기 쉽기 때문에, 클락 타임 트럭에서는 GUID_BandParam 를 사용하지 않는 것이 추천 된다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParamEx ,퍼포먼스 파라미터


DMUS_BUFFERDESC

IDirectMusic8::CreateMusicBuffer 메소드의 버퍼를 기술하기 위해서 사용된다.

typedef struct _DMUS_BUFFERDESC {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidBufferFormat;
    DWORD cbBuffer;
} DMUS_BUFFERDESC, *LPDMUS_BUFFERDESC;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
dwFlags
플래그는 정의되어 있지 않다.
guidBufferFormat
버퍼의 KS 포맷의 식별자. 값 GUID_NULL 는, KSDATAFORMAT_SUBTYPE_DIRECTMUSIC 를 나타낸다.

guidBufferFormat 이 KSDATAFORMAT_SUBTYPE_DIRECTMUSIC 이외의 KS 포맷을 나타내는 경우, 어플리케이션은, 데이터를 재생하고 있는 포토가 지정의 포맷을 이해하고 있을지 어떨지 검증해야 한다. 그렇게 하지 않았던 경우, 버퍼는 무시된다. 포토가 특정의 KS 포맷을 지원 하고 있을지 어떨지를 조사하려면 ,IKsControl::KsProperty 메소드를 사용한다.

cbBuffer
메세지의 최소 사이즈 (바이트 단위). 시스템이 버퍼를 4 바이트의 배수에 추가하기 위해(때문에), 할당할 수 있는 메모리량은 조금 증가한다. 1 개의 MIDI 채널 메세지를 저장 하려면 , 버퍼는 32 바이트 이상이 아니면 안된다. 시스템에크스크루시브멧세이지 또는 그 외의 비구조화 데이터를 저장 하기 위해서, 버퍼는 최저 28 바이트와 데이터 사이즈를 맞춘 사이즈가 아니면 안된다.

동작환경

헤더 : dmusici.h 로 선언.

참조

DMUS_EVENTHEADER ,IDirectMusicBuffer8::PackStructured ,IDirectMusicBuffer8::PackUnstructured


DMUS_CHORD_KEY

IDirectMusicPerformance8::MIDIToMusic 메소드 및 IDirectMusicPerformance8::MusicToMIDI 메소드로, 코드를 기술하기 위해서 사용된다.

typedef struct _DMUS_CHORD_KEY {
    WCHAR         wszName[16];
    WORD          wMeasure;
    BYTE          bBeat;
    BYTE          bSubChordCount;
    DMUS_SUBCHORD SubChordList[DMUS_MAXSUBCHORD];
    DWORD         dwScale;
    BYTE          bKey;
    BYTE          bFlags;
} DMUS_CHORD_KEY;

멤버

wszName
코드의 이름.
wMeasure
코드가 소속하는 소절.
bBeat
코드가 소속하는 박.
bSubChordCount
코드의 서브 코드 리스트내에 있는 코드의 수.
SubChordList
코드를 구성하는 컴퍼넌트를 기술하는,DMUS_SUBCHORD 구조체의 배열.
dwScale
코드 전체의 베이스가 되는 스케일.
bKey
코드 전체의 베이스가 되는 키.
bFlags
0 을 지정할 수 있다. 코드가 무음인 경우는 DMUS_CHORDKEYF_SILENT. 「주의」를 참조할것.

주의

이 구조체는,GUID_ChordParam 트럭 파라미터의 설정과 취득에 사용되는,DMUS_CHORD_PARAM 구조체라고 해도 정의된다.

코드에 무음 코드의 플래그가 설정되어 있어도, 연주 패턴이 선택되려면 고려되지 않는다. 예를 들어, 1 박목에 코드 체인지, 3 박목에 무음 코드가 있는 경우에서도, 소절 전체의 코드 리듬을 가지는 패턴이 연주되는 일이 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParamEx ,퍼포먼스 파라미터


DMUS_CHORD_PARAM

트럭이 코드 트럭이며,rguidType 가 GUID_ChordParam 인 경우, 각종의 파라미터 취득 메소드나 파라미터 설정 메소드를 호출할 때에,pParam 파라미터로서 사용된다.

typedef DMUS_CHORD_KEY DMUS_CHORD_PARAM;

「DMUS_CHORD_KEY 」를 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParamEx ,퍼포먼스 파라미터


DMUS_CLOCKINFO8

IDirectMusic8::EnumMasterClock 메소드를 사용해 열거된, 클락에 관한 정보를 보고한다.

typedef struct _DMUS_CLOCKINFO{
    DWORD           dwSize;
    DMUS_CLOCKTYPE  ctType;
    GUID            guidClock;
    WCHAR           wszDescription[DMUS_MAX_DESCRIPTION];
    DWORD           dwFlags;
} DMUS_CLOCKINFO8, *LPDMUS_CLOCKINFO8;

typedef DMUS_CLOCKINFO8 DMUS_CLOCKINFO;
typedef DMUS_CLOCKINFO *LPDMUS_CLOCKINFO;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 메소드에 건네주기 전에, 이 멤버를 초기화해야 한다.
ctType
클락의 타입을 지정하는,DMUS_CLOCKTYPE 열거형의 멤버.
guidClock
클락의 식별자. 이 값을 IDirectMusic8::SetMasterClock 메소드에 건네주면(자), DirectMusic 의 master clock를 설정할 수가 있다.
wszDescription
클락의 기술.
dwFlags
플래그.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_COMMAND_PARAM

트럭이 커멘드 트럭이며,rguidType 파라미터가 GUID_CommandParam 인 경우, 각종의 파라미터 취득 메소드나 파라미터 설정 메소드를 호출할 때에,pParam 파라미터로서 사용된다.

typedef struct {
    BYTE bCommand;
    BYTE bGrooveLevel;
    BYTE bGrooveRange;
    BYTE bRepeatMode;
} DMUS_COMMAND_PARAM;

멤버

bCommand
커멘드의 타입. 「DMUS_COMMANDT_TYPES 」를 참조할것.
bGrooveLevel
커멘드의홈 레벨 . 홈 레벨은, 1 ~ 100 의 범위에서 지정하는 값이다.
bGrooveRange
홈 레벨을 랜덤화할 수 있는 양. 예를 들어, 홈 레벨이 35 로 범위가 4 의 경우, 실제의 홈 레벨은 33 에서 37 의 몇개의 값이 된다. bGrooveRange 가 홀수라면, 거기로부터 1 이 끌린다.
bRepeatMode
반복의 패턴을 선택하는 방법을 지정하는 플래그. 「DMUS_PATTERNT_TYPES 」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParamEx


DMUS_COMMAND_PARAM_2

트럭이 커멘드 트럭이며,rguidType 파라미터가 GUID_CommandParam2 인 경우, 각종의 파라미터 취득 메소드나 파라미터 설정 메소드를 호출할 때에,pParam 파라미터로서 사용된다.

typedef struct _DMUS_COMMAND_PARAM_2 {
    MUSIC_TIME mtTime;
    BYTE bCommand;
    BYTE bGrooveLevel;
    BYTE bGrooveRange;
    BYTE bRepeatMode;
} DMUS_COMMAND_PARAM_2;

멤버

mtTime
커멘드의 타임.
bCommand
커멘드의 타입. 「DMUS_COMMANDT_TYPES 」를 참조할것.
bGrooveLevel
커멘드의홈 레벨 . 홈 레벨은, 1 ~ 100 의 범위에서 지정하는 값이다.
bGrooveRange
홈 레벨을 랜덤화할 수 있는 양. 예를 들어, 홈 레벨이 35 로 범위가 4 의 경우, 홈 레벨은 33 에서 37 의 몇개의 값이 된다. bGrooveRange 가 홀수라면, 거기로부터 1 이 끌린다.
bRepeatMode
반복의 패턴을 선택하는 방법을 지정하는 플래그. 「DMUS_PATTERNT_TYPES 」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParamEx


DMUS_CONNECTION_RULE

DirectX 8.0 에서는 이행 되지 않는다.

음악의 단편이 잇달아 순조롭게 흐르기 위한 규칙을 지정하기 위해서,DMUS_MELODY_FRAGMENT 의 ConnectionArc 멤버로 사용된다.

typedef struct _DMUS_CONNECTION_RULE {
    DWORD       dwFlags;
    DWORD       dwIntervals;
} DMUS_CONNECTION_RULE;

멤버

dwFlags
결합 규칙을 지정하는 플래그. 0 또는 다음의 1 개 이상의 값을 사용할 수 있다.
DMUS_CONNECTIONF_INTERVALS
바리에이션의 마지막 노트와 다음의 바리에이션의 최초의 노트의 사이로,dwIntervals 의 음정을 사용한다.
DMUS_CONNECTIONF_OVERLAP
2 개의 단편이 오버랩 하는 경우, 앞의 단편으로 연주되지 않는 최초의 노트가, 후의 단편의 최초의 노트와 같다.
dwIntervals
DMUS_CONNECTIONF_INTERVALS 가 설정되어 있는 경우, 최초의 단편으로 연주되는 마지막 노트와 2 번째의 단편에 포함되는 최초의 노트의 사이로, 유효한 음정세트를 지정한다. 하위 24 비트의 각각이, 2 옥타브의 범위를 가지는 음정이다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_EVENTHEADER

포토 버퍼내의 이벤트의 전에 놓여져 이 이벤트를 기술한다.

typedef struct _DMUS_EVENTHEADER {
    DWORD           cbEvent;
    DWORD           dwChannelGroup;
    REFERENCE_TIME  rtDelta;
    DWORD           dwFlags;
} DMUS_EVENTHEADER, *LPDMUS_EVENTHEADER;

멤버

cbEvent
이벤트내의 바이트수.
dwChannelGroup
이벤트가 소속하는 그룹.
rtDelta
버퍼의 시작 타임부터의 오프셋(offset).
dwFlags
이벤트가 해석 가능한 MIDI 데이터의 경우, DMUS_EVENT_STRUCTURED 로 설정된다.

주의

이 구조체의 선언전에는 Pshpack4.h 헤더 파일이 인클루드 되고 있다. 이것에 의해 구조체의 자동 정렬이 무효가 되어, 데이터는 헤더의 바로 후에 계속된다 (상세한 것에 대하여는, Pshpack4.h 내의 코멘트를 참조). 다음에 Poppack.h 가 인클루드 되어 정렬이 유효하게 된다. 구조체 전체 (헤더와 이벤트)가 8 바이트 경계까지 추가된다.

동작환경

헤더 : dmusbuff.h 로 선언.

참조

IDirectMusicBuffer8::GetNextEvent ,IDirectMusicBuffer8::PackStructured ,IDirectMusicBuffer8::PackUnstructured


DMUS_MELODY_FRAGMENT

DirectX 8.0 에서는 이행 되지 않는다.

멜로디 편성 트럭의 단편을 기술한다. 멜로디의 단편은, 멜로디의 어레인지를 실시할 때에, 패턴으로부터 바리에이션을 선택하기 위해서 사용된다.

typedef struct _DMUS_MELODY_FRAGMENT {
    MUSIC_TIME  mtTime;
    DWORD  dwID;
    WCHAR  wszVariationLabel[DMUS_MAX_FRAGMENTLABEL];
    DWORD  dwVariationFlags;
    DWORD  dwRepeatFragmentID;
    DWORD  dwFragmentFlags;
    DWORD  dwPlayModeFlags;
    DWORD  dwTransposeIntervals;
    DMUS_COMMAND_PARAM   Command;
    DMUS_CONNECTION_RULE ConnectionArc;
} DMUS_MELODY_FRAGMENT;

멤버

mtTime
단편을 연주하는 타임. 트럭의 시작으로부터의 상대 시간이다.
dwID
트럭의 식별자.
wszVariationLabel
예약이 끝난 상태.
dwVariationFlags
사용 가능한 바리에이션세트를 지정하는 DWORD 값. 설정되는 각 비트가 1 개의 바리에이션을 나타낸다. dwFragmentFlags 에 DMUS_FRAGMENTF_USE_REPEAT 가 포함되는 경우는 무시된다.
dwRepeatFragmentID
트럭내의 이전의 단편의 식별자. 여기로부터 바리에이션을 선택한다. dwFragmentFlags 에 DMUS_FRAGMENTF_USE_REPEAT 가 포함되지 않는 경우는 무시된다.
dwFragmentFlags
다음의 값의 어느쪽이든을 사용할 수 있다.
DMUS_FRAGMENTF_USE_REPEAT
dwRepeatFragmentID 로 지정된 단편을 사용한다.
DMUS_FRAGMENTF_REJECT_REPEAT
이전의 단편의 새로운 바리에이션을 사용한다.
DMUS_FRAGMENTF_USE_LABEL
wszVariationLabel 로 지정되는 세트를 사용한다. 현재 지원되어 있지 않다.
dwPlayModeFlags
예약이 끝난 상태. 0 이 아니면 안된다.
dwTransposeIntervals
하위 24 비트는 각각, 2 옥타브의 범위내의 음정을 나타낸다. 리피트 하는 단편내의 노트를, 현재의 코드 또는 키에 맞추어 전치하기 위한 기준이 되는, 음정세트를 지정한다.
Command
멜로디의 소스로서 사용하는 패턴의 타입을 지정하는 DMUS_COMMAND_PARAM 구조체.
ConnectionArc
단편이 잇달아 순조롭게 흐르도록(듯이)하기 위한 규칙을 지정하는 DMUS_CONNECTION_RULE 구조체.

주의

각각의 단편에 대해서 선택된 바리에이션이 멜로디를 형성한다. 단편은, 임의의 박경계상에 배치할 수 있어 소절 경계에 걸칠 수가 있다. 2 개의 단편이 오버랩 하는 경우, 선행하는 단편으로 선택된 바리에이션은, 후의 단편의 노트와 충돌하지 않게, 잘라 버릴 수 있다.

각각의 멜로디 단편에는, 그 포인트에 적절한 바리에이션의 기술이 포함된다. 이것은, 바리에이션의 범위, 리스트, 또는 "모든 바리에이션을 사용하는" 유익의 지시이다. 바리에이션의 선택은, 전의 바리에이션을 참조할것도 할 수 있다. 멜로디 단편은, 연주 모드를 사용해 구축중의 멜로디내에 노트를 생성하거나 코드의 음정이나 스케일의 음정을 사용해 현재의 코드에 가지런히 하는 바리에이션을 선택하거나 할 수가 있다. 게다가 단편을 가지런히 하기 위해서(때문에) 전치 할 때의 기준으로 하는 음정으로서 음정세트를 선택할 수도 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

GUID_MelodyFragment


DMUS_MUTE_PARAM

트럭이 뮤트 트럭이며,rguidType 가 GUID_MuteParam 인 경우, 각종의 파라미터 취득 메소드나 파라미터 설정 메소드를 호출할 때에,pParam 파라미터로서 사용된다.

typedef struct _DMUS_MUTE_PARAM {
    DWORD  dwPChannel;
    DWORD  dwPChannelMap;
    BOOL   fMute;
} DMUS_MUTE_PARAM;

멤버

dwPChannel
뮤트 또는 재맵 하는 퍼포먼스 채널. 구조체가 get 메소드에게 건네지는 경우는, 이 멤버를 초기화해야 한다.
dwPChannelMap
dwPChannel 가 맵 되고 있는 채널. fMute 가 TRUE 의 경우, 이 멤버는 무시된다.
fMute
dwPChannel 가 뮤트 되고 있는 경우는 TRUE.

주의

P 채널 3 위에의 모든 노트를 P 채널 9 상에서 연주하고 싶은 경우는, 이 구조체를 set 메소드의 어느 쪽인가에 건네주기 전에,dwPChannel 을 3 으로 설정해,dwPChannelMap 를 9 로 설정한다. P 채널 8 위에의 노트를 뮤트 하고 싶은 경우는,dwPChannel 을 8 으로 설정해,dwPChannelMap 를 0xFFFFFFFF 로 설정한다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParamEx


DMUS_NOTERANGE

음색이 응답해야 하는 노트 범위를 지정한다. 이 구조체의 배열을 IDirectMusicPerformance8::DownloadInstrument 메소드와 IDirectMusicPort8::DownloadInstrument 메소드에 건네주어, 음색이 어느 노트에 응답해야할 것인가, 그 때문에(위해) 어느 음색리젼을 다운로드할 필요가 있는지를 지정한다.

typedef struct _DMUS_NOTERANGE {
    DWORD dwLowNote;
    DWORD dwHighNote;
} DMUS_NOTERANGE, *LPDMUS_NOTERANGE;

멤버

dwLowNote
음색이 응답해야 하는 MIDI 노트 범위의 낮은 소리.
dwHighNote
음색이 응답해야 하는 MIDI 노트 범위의 높은 소리.

동작환경

헤더 : dmdls.h 로 선언.


DMUS_OBJECTDESC

DirectMusic 오브젝트를 기술하기 위해서 사용된다. 이 구조체를 IDirectMusicLoader8::GetObject 메소드에 건네주어, 로더가 기억장치로부터 취득해야 할 오브젝트를 식별한다. 이 구조체로부터 오브젝트에 관한 정보를 취득하려면 ,IDirectMusicLoader8::EnumObject 메소드와 IDirectMusicObject8::GetDescriptor 메소드를 사용한다.

typedef struct _DMUS_OBJECTDESC {
    DWORD         dwSize;
    DWORD         dwValidData;
    GUID          guidObject;
    GUID          guidClass;
    FILETIME      ftDate;
    DMUS_VERSION  vVersion;
    WCHAR         wszName[DMUS_MAX_NAME];
    WCHAR         wszCategory[DMUS_MAX_CATEGORY];
    WCHAR         wszFileName[DMUS_MAX_FILENAME];
    LONGLONG      llMemLength;
    LPBYTE        pbMemData;
    IStream       *pStream
} DMUS_OBJECTDESC, *LPDMUS_OBJECTDESC;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 임의의 메소드에 건네주기 전에, 이 멤버를 sizeof(DMUS_OBJECTDESC) 에 초기화해야 한다.
dwValidData
어느 멤버가 유효한가 기술해, 몇개의 멤버에 관한 상세한 정보를 제공하는 플래그. 다음의 값이 정의되고 있다.
DMUS_OBJ_CATEGORY
wszCategory 멤버는 유효하다.
DMUS_OBJ_CLASS
guidClass 멤버는 유효하다.
DMUS_OBJ_DATE
ftDate 멤버는 유효하다.
DMUS_OBJ_FILENAME
wszFileName 멤버는 유효하다. DMUS_OBJ_FULLPATH 가 설정되어 있는 경우는, 이 플래그가 있으면(자) 상정된다.
DMUS_OBJ_FULLPATH
wszFileName 멤버는, 파일의 풀 패스, 또는 어플리케이션 디렉토리로부터의 상대 패스의 어느 쪽인지를 보관 유지하고 있다. IDirectMusicLoader8::SetSearchDirectory 로 설정된 디렉토리는 검색되지 않는다. 이 플래그가 설정되지 않는 경우,wszFilename 는 항상, 어플리케이션 디렉토리로부터의 상대 패스, 또는 이 오브젝트 타입에 대해서 SetSearchDirectory 가 불려 가는 경우는, 검색 디렉토리로부터의 상대 패스이라고 가정된다.
DMUS_OBJ_LOADED
오브젝트는 현재 메모리내에 로드 되고 있다.
DMUS_OBJ_MEMORY
오브젝트는 메모리내에 있어,llMemLength 와 pbMemData 는 유효하다.
DMUS_OBJ_NAME
wszName 멤버는 유효하다.
DMUS_OBJ_OBJECT
guidObject 멤버는 유효하다.
DMUS_OBJ_STREAM
pStream 멤버는, 데이터 스트림에의 포인터를 보관 유지하고 있다.
DMUS_OBJ_URL
wszFileName 멤버는 URL 를 보관 유지하고 있다. DirectMusic 로더는 현재 URL 를 지원 하고 있지 않다.
DMUS_OBJ_VERSION
vVersion 멤버는 유효하다.
guidObject
이 오브젝트의 일의의 식별자.
guidClass
오브젝트 클래스의 일의의 식별자. 모든 표준적인 오브젝트는,"CLSID_" 와 오브젝트명으로 구성되는 정의 끝난 식별자를 가지고 있다. 예를 들어, 세그먼트(segment) 오브젝트는 CLSID_DirectMusicSegment 로서 식별된다. Dmusici.h 헤더 파일내의 정의를 참조할것.
ftDate
오브젝트가 마지막에 편집된 일자.
vVersion
버젼 정보를 보관 유지하는 DMUS_VERSION 구조체.
wszName
오브젝트의 이름.
wszCategory
오브젝트의 카테고리.
wszFileName
파일의 패스. DMUS_OBJ_FULLPATH 가 설정되어 있는 경우, 이 값은 풀 패스이다. 그 이외의 경우는, 파일명 뿐이다. IDirectMusicLoader8::SetSearchDirectory 메소드가 불려 가고 있었을 경우는, 파일명만이 아니면 안된다.
llMemLength
메모리내의 데이터의 사이즈.
pbMemData
메모리내의 데이터.
pStream
커스텀 스트림의 IStream 인터페이스의 주소. 오브젝트를 메모리에 로드하기 위해서(때문에) 사용할 수가 있다. 대부분의 경우, 이 값은 NULL 이다. 「주의」를 참조할것.

주의

IDirectMusicLoader8::GetObject 메소드를 사용해 오브젝트를 취득할 수 있도록(듯이),wszName,idGuid, 및 wszFileName 가 적어도 1 개(살)에 유효한 데이터를 기입하지 않으면 안 된다.

이름과 카테고리의 캐릭터 라인은, 8 비트의 ANSI 문자는 아니고, WCHAR 포맷의 16 비트 문자를 사용한다. 필요에 따라서 변환을 실시하도록(듯이) 주의 해야 한다. C 라이브러리의 mbstowcs 함수를 사용해, 멀티 바이트로부터 Unicode,wcstombs 함수를 사용해 Unicode 로부터 멀티 바이트에의 변환도 실시할 수 있다.

오브젝트 디스크립터를 파일명이나 메모리 포인터와 함께 IDirectMusicLoader8::GetObject 또는 IDirectMusicLoader8::SetObject 에 건네주는 대신에, 어플리케이션으로 스트림을 건네줄 수가 있다. 이것을 실시하려면 ,dwValidData 에 DMUS_OBJ_STREAM 플래그를 설정해,pStream 내의 스트림에의 포인터를 설정한다. 어플리케이션이 GetObject 를 호출하면, 로더는 스트림의 현재의 위치를 보존해, 스트림으로부터 오브젝트를 읽어내, 보존한 위치를 복원한다. 어플리케이션은,GetObject 에의 호출에 의한 영향을 받지 않고 , 스트림으로부터의 읽기를 계속해 실시할 수가 있다.

스트림으로 SetObject 가 불려 가면(자), 로더는 스트림의 카피를 생성 한다. 이 카피는, 오브젝트가 나중에 로드 되었을 경우에 사용된다. 따라서, 어플리케이션은 SetObject 를 사용해 로더에 스트림을 건네준 후, 스트림을 해방하거나 계속해 스트림으로부터 읽어내거나 할 수가 있다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_PLAY_MARKER_PARAM

연주 마커에 관한 정보를 보관 유지한다.

typedef struct _DMUS_PLAY_MARKER_PARAM {
    MUSIC_TIME mtTime;
} DMUS_PLAY_MARKER_PARAM;

멤버

mtTime
최초의 유효한 세그먼트(segment) 연주 마커의 타임, 또는 요구된 타임. 이 값은 요구된 타임부터의 오프셋(offset)이다.

동작환경

헤더 : dmusici.h 로 선언.

참조

GUID_Play_Marker


DMUS_PORTCAPS

IDirectMusic8::EnumPort 메소드의 호출로 열거된, 포토에 관한 정보를 받는다. IDirectMusicPort8::GetCaps 메소드를 통해 정보를 돌려줄 때도, 이 구조체가 사용된다.

typedef struct _DMUS_PORTCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidPort;
    DWORD dwClass;
    DWORD dwType;
    DWORD dwMemorySize;
    DWORD dwMaxChannelGroups;
    DWORD dwMaxVoices;
    DWORD dwMaxAudioChannels;
    DWORD dwEffectFlags;
    WCHAR wszDescription[DMUS_MAX_DESCRIPTION];
} DMUS_PORTCAPS, *LPDMUS_PORTCAPS;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 임의의 메소드에 건네주기 전에, 이 멤버를 sizeof(DMUS_PORTCAPS) 에 초기화해야 한다.
dwFlags
포토의 다양한 능력을 기술하는 플래그. 이 필드에는, 다음의 1 개 이상의 값을 포함할 수가 있다.
DMUS_PC_AUDIOPATH
오디오 패스용으로 복수의 출력을 DirectSound 에 접속할 수가 있다.
DMUS_PC_DIRECTSOUND
포토는 DirectSound 에 보내는 스트리밍 웨이브 데이터를 지원 한다.
DMUS_PC_DLS
포토는 DLS 레벨 1 의 샘플 콜렉션을 지원 한다.
DMUS_PC_DLS2
포토는 DLS 레벨 2 의 샘플 콜렉션을 지원 한다.
DMUS_PC_EXTERNAL
포토는 호스트의 외부에 있는 디바이스에 접속되고 있다. 예를 들어, MPU-401 와 같은 외부 MIDI 포토를 통해 디바이스에 접속되고 있다.
DMUS_PC_GMINHARDWARE
신디사이저는 독자적인 GM 음색 세트를 가지고 있다. 그 때문에, GM 음색은 다운로드할 필요가 없다.
DMUS_PC_GSINHARDWARE
이 포토는, 하드웨어내에 Roland GS 사운드 세트를 보관 유지하고 있다.
DMUS_PC_MEMORYSIZEFIXED
DLS 음색으로 이용할 수 있는 메모리는 조정할 수 없다.
DMUS_PC_SHAREABLE
디바이스상에 있는 채널 그룹의 같은 범위를 사용하는 포토는 복수 생성 할 수 있다. 이 비트를 세트 하지 않는 한, 포토는 배타 모드에서만 열 수가 있다. 배타 모드에서는, 생성 된 요구에의 할당에 이용할 수 있는 채널 그룹이 없는 한, 포토를 생성 하는 시도는 실패한다.
DMUS_PC_SOFTWARESYNTH
포토는 소프트웨어 신디사이저이다.
DMUS_PC_WAVE
스트리밍 및 one-shot 웨이브가 지원 되고 있다.
DMUS_PC_XGINHARDWARE
이 포토는, 하드웨어내에 Yamaha XG 확장을 보관 유지하고 있다.
guidPort
포토의 식별자. 이 값을 IDirectMusic8::CreatePort 메소드에 건네주면(자), 포토의 IDirectMusicPort8 인터페이스를 취득할 수가 있다.
dwClass
이 포토의 클래스. 다음의 클래스가 정의되고 있다.
DMUS_PC_INPUTCLASS
입력 포토.
DMUS_PC_OUTPUTCLASS
출력 포토.
dwType
이 포토의 타입. 다음의 타입이 정의되고 있다.
DMUS_PORT_WINMM_DRIVER
Windows 멀티미디어 드라이버.
DMUS_PORT_USER_MODE_SYNTH
유저 모드 신디사이저.
DMUS_PORT_KERNEL_MODE
WDM 드라이버.
dwMemorySize
DLS 음색의 보존에 이용할 수 있는 메모리의 양. 포토가 시스템 메모리를 사용하고 있어, 이용 가능한 시스템 메모리에 의해 그 양이 제한을 받는 경우, 이 멤버는 DMUS_PC_SYSTEMMEMORY 를 보관 유지한다.
dwMaxChannelGroups
이 포토가 지원 하는 채널 그룹의 최대수. 1 개의 채널 그룹은, 16 개의 MIDI 채널로부터 완성되는 세트이다.
dwMaxVoices
이 포토를 열었을 때에 할당을 할 수 있는 음성의 최대수. 이 파라미터가 돌려주어지는 것을 드라이버가 지원 하고 있지 않는 경우, 값은 － 1 이라도 좋다.
dwMaxAudioChannels
포토에 의해 렌더링 할 수 있는 오디오 채널의 최대수. 이 파라미터가 돌려주어지는 것을 드라이버가 지원 하고 있지 않는 경우, 값은 － 1 이라도 좋다.
dwEffectFlags
포토상에서 어떠한 오디오 이펙트를 이용할 수 있는지를 나타내는 플래그.

다음의 플래그가 정의되고 있다.

DMUS_EFFECT_NONE
이펙트는 지원 하고 있지 않다.
DMUS_EFFECT_REVERB
포토는 리바브를 지원 한다.
DMUS_EFFECT_CHORUS
포토는 코러스를 지원 한다.
wszDescription
포토의 기술. L"MPU-401 Output Port [330]" 과 같은 시스템 생성의 이름이라도, L"Port w/ External SC-55" 와 같은 유저 지정의 알기 쉬운 이름이라도 좋다.

동작환경

헤더 : dmusicc.h 로 선언.


DMUS_PORTPARAMS8

DirectMusic 포토를 열기 위한 파라미터로 구성되어 있다. IDirectMusic8::CreatePort 메소드를 호출했을 때에, 이러한 파라미터가 건네받는다.

DMUS_PORTPARAMS 라고 하는 정의는 DMUS_PORTPARAMS8 에 해결된다. 이 구조체는,DMUS_PORTPARAMS 이전의 버젼을 계승한다. 이전의 버젼은 현재 DMUS_PORTPARAMS7 로서 선언된다.

typedef struct _DMUS_PORTPARAMS8 {
    DWORD dwSize;
    DWORD dwValidParams;
    DWORD dwVoices;
    DWORD dwChannelGroups;
    DWORD dwAudioChannels;
    DWORD dwSampleRate;
    DWORD dwEffectFlags;
    DWORD fShare;
    DWORD dwFeatures;
} DMUS_PORTPARAMS8;

typedef DMUS_PORTPARAMS8 DMUS_PORTPARAMS;
typedef DMUS_PORTPARAMS *LPDMUS_PORTPARAMS;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 메소드에 건네주기 전에, 이 멤버를 sizeof(DMUS_PORTPARAMS) 에 초기화해야 한다.
dwValidParams
이 구조체의 어느 멤버가 유효한가를 지정한다. 특정의 파라미터에 플래그를 설정하는 것은, 포토의 생성시에, 메소드의 호출로 그 파라미터를 설정하고 싶은, 또는 디폴트값을 오버라이드(override) 하고 싶은 것을 의미한다. 다음의 플래그가 정의되고 있다.
DMUS_PORTPARAMS_VOICES
DMUS_PORTPARAMS_CHANNELGROUPS
DMUS_PORTPARAMS_AUDIOCHANNELS
DMUS_PORTPARAMS_SAMPLERATE
DMUS_PORTPARAMS_EFFECTS
DMUS_PORTPARAMS_SHARE
DMUS_PORTPARAMS_FEATURES
dwVoices
이 포토로 필요한 음성의 수. 이것은 절대적인 최대치는 아니다. 포토는, 우선 순위의 낮은 음성을 삭제할 필요가 있을 때, 추가의 음성을 일시적으로 생성 해, 슴즈궸란지션 시킬 수가 있다.
dwChannelGroups
이 포토에 할당할 수 있는 채널 그룹의 수. IDirectMusic8::EnumPort 메소드와 IDirectMusicPort8::GetCaps 메소드가 돌려준 DMUS_PORTCAPS 구조체로 지정되는 채널 그룹수이하가 아니면 안된다.
dwAudioChannels
목적의 출력 채널수.
dwSampleRate
목적의 샘플링 레이트. 헤르쯔 (Hz) 단위로 지정한다.
dwEffectFlags
목적의 특수 효과를 나타내는 플래그. 다음의 플래그가 정의되고 있다.

DMUS_EFFECT_NONE
DMUS_EFFECT_REVERB
DMUS_EFFECT_CHORUS

fShare
TRUE 의 경우, 모든 포토가, 이 포토에 할당할 수 있었던 채널 그룹을 사용한다. FALSE 의 경우, 포토는 배타 모드로 열려 그 외의 포토에 의한 같은 채널 그룹의 사용이 금지된다.
dwFeatures
포토의 그 외의 능력. 다음의 값이 정의되고 있다.
DMUS_PORT_FEATURE_AUDIOPATH
DirectSound 버퍼와의 오디오 패스 접속을 지원 한다.
DMUS_PORT_FEATURE_STREAMING
신디사이저로부터의 스트리밍 웨이브를 지원 한다.

주의

DirectX 8.0 보다 전의 버젼의 DMUS_PORTPARAMS 구조체는,DMUS_PORTPARAMS7 로서 Dmusicc.h 내에 유지된다.

동작환경

헤더 : dmusicc.h 로 선언.

참조

DMUS_PORTCAPS


DMUS_RHYTHM_PARAM

트럭이 코드 트럭이며,rguidType 가 GUID_RhythmParam 인 경우, 각종의 파라미터 취득 메소드를 호출할 때에,pParam 파라미터로서 사용된다.

typedef struct {
    DMUS_TIMESIGNATURE  TimeSig;
    DWORD               dwRhythmPattern;
} DMUS_RHYTHM_PARAM;

멤버

TimeSig
리듬 파라미터의 박자 기호를 보관 유지하는 DMUS_TIMESIGNATURE 구조체. DMUS_RHYTHM_PARAM 구조체를 get 메소드에 건네주기 전에, 이 구조체를 초기화해야 한다.
dwRhythmPattern
코드 순서의 리듬 패턴. 각 비트는 1 개 또는 복수의 소절내의 1 개의 박을 나타내, 1 은 그 박으로 코드가 온이 되어 있는 것, 0 은 코드가 존재하지 않는 것을 나타낸다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParamEx


DMUS_SCRIPT_ERRORINFO

스크립트 에러에 관한 정보를 보관 유지한다.

typedef struct _DMUS_SCRIPT_ERRORINFO {
    DWORD   dwSize;
    HRESULT hr;
    ULONG ulLineNumber;
    LONG ichCharPosition;
    WCHAR  wszSourceFile[DMUS_MAX_FILENAME];
    WCHAR  wszSourceComponent[DMUS_MAX_FILENAME];
    WCHAR  wszDescription[DMUS_MAX_FILENAME];
    WCHAR  wszSourceLineText[DMUS_MAX_FILENAME];
} DMUS_SCRIPT_ERRORINFO;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 IDirectMusicScript8 의 임의의 메소드에 건네주기 전에, 이 멤버를 초기화해야 한다.
hr
DirectMusic 또는 스크립트 엔진으로부터 취득되는 결과 코드.
ulLineNumber
에러가 발생한 스크립트내의 행 번호.
ichCharPosition
wszSourceLineText 가 캐릭터 라인을 보관 유지하는 경우에, 구문 에러가 발견된 은행내의 장소.
wszSourceFile
스크립트의 파일명.
wszSourceComponent
에러를 생성한 컴퍼넌트명. 예를 들어, DirectMusic 나 스크립트 해석 엔진 등.
wszDescription
에러의 설명.
wszSourceLineText
에러가 발생한 스크립트행의 텍스트. 에러가 구문내에 없는 경우는, 하늘의 캐릭터 라인이 된다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_SUBCHORD

DMUS_CHORD_PARAM 구조체의 SubChordList 멤버로 사용된다.

typedef struct {
    DWORD dwChordPattern;
    DWORD dwScalePattern;
    DWORD dwInversionPoints;
    DWORD dwLevels;
    BYTE  bChordRoot;
    BYTE  bScaleRoot;
} DMUS_SUBCHORD;

멤버

dwChordPattern
서브 코드내의 노트. 하위 24 비트는 각각 1 개의 반음을 나타내, 최하정도 비트는 루트음이다. 비트가 세트 되고 있는 경우, 거기에 대응하는 노트는 코드내에 존재한다.
dwScalePattern
스케일내의 노트. 하위 24 비트는 각각 1 개의 반음을 나타내, 최하정도 비트는 루트음이다. 비트가 세트 되고 있는 경우, 거기에 대응하는 노트는 스케일내에 존재한다.
dwInversionPoints
스케일내에서 회전을 발생할 수 있는 포인트. 비트가 오프가 되어 있는 경우, 거기에 대응하는 음정에서는 노트를 회전 할 수 없다. 예를 들어, 패턴 100001111111 은, 햇빛 음계 (메이저 스케일)의 5 번과 7 번을 제외해, 어디에서라도 회전이 인정되는 것을 의미한다.
dwLevels
이 서브 코드가 지원 하는 레벨을 나타내는 비트 필드. 스타일내의 각 파트에는 레벨을 할당할 수 있어 레벨이 이 멤버에 포함되는 파트에만 도착해 이 코드가 사용된다.
bChordRoot
서브 코드의 루트음. 0 은 범위내의 최저음의 C, 23 은 최고음의 B 이다.
bScaleRoot
스케일의 루트음. 0 은 범위내의 최저음의 C, 23 은 최고음의 B 이다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_SYNTHSTATS8

신디사이저의 현재의 동작 스테이터스를 취득하기 위해서,IDirectMusicPort8::GetRunningStats 메소드로 사용된다.

typedef struct DMUS_SYNTHSTATS {
    DWORD dwSize;
    DWORD dwValidStats;
    DWORD dwVoices;
    DWORD dwTotalCPU;
    DWORD dwCPUPerVoice;
    DWORD dwLostNotes;
    DWORD dwFreeMemory;
    long  lPeakVolume;
    DWORD   dwSynthMemUse;
} DMUS_SYNTHSTATS8;

typedef struct _DMUS_SYNTHSTATS8 *LPDMUS_SYNTHSTATS8;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 메소드에 건네주기 전에, 이 멤버를 sizeof(DMUS_SYNTHSTATS) 에 초기화해야 한다.
dwValidStats
신디사이저가, 이 구조 체내의 어느 필드에 기입을 실시하는지를 지정하는 플래그. 다음의 플래그가 정의되고 있다.

DMUS_SYNTHSTATS_VOICES
DMUS_SYNTHSTATS_TOTAL_CPU
DMUS_SYNTHSTATS_CPU_PER_VOICE
DMUS_SYNTHSTATS_FREE_MEMORY
DMUS_SYNTHSTATS_LOST_NOTES
DMUS_SYNTHSTATS_PEAK_VOLUME

dwVoices
연주중의 음성수의 평균치.
dwTotalCPU
CPU 이용율에 100 을 곱한 합계 퍼센티지.
dwCPUPerVoice
음성 근처의 CPU 이용율에 100 을 곱한 퍼센티지.
dwLostNotes
없어진 노트의 수. 보이스스티링이나 과도하게 높은 CPU 이용율이 원인으로, 노트가 결핍 하는 일이 있다.
dwFreeMemory
DLS 음색을 보존하기 위해서 현재 이용할 수 있는 메모리의 양. 신디사이저가 시스템 메모리를 사용하고 있어, 이용 가능한 시스템 메모리에 의해 그 양이 제한을 받는 경우, 이 필드는 DMUS_SYNTHSTATS_SYSTEMMEMORY 를 보관 유지한다.
lPeakVolume
피크 볼륨. 1/100dB (즉 mB) 단위로 측정된다.
dwSynthMemUse
신디사이저 웨이브 데이터로 사용되는 메모리.

주의

dwFreeMemory 를 제외해, 동작중의 모든 스테이터스 파라미터는 1 초 마다 갱신된다. 예를 들어,dwLostNotes 는, 1 초간에 없어진 노트의 합계수를 나타낸다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_TEMPO_PARAM

트럭이 템포 트럭이며,rguidType 가 GUID_TempoParam 인 경우, 각종의 파라미터 취득 메소드나 파라미터 설정 메소드를 호출할 때에,pParam 파라미터로서 사용된다.

typedef struct _DMUS_TEMPO_PARAM {
    MUSIC_TIME  mtTime;
    double      dblTempo;
} DMUS_TEMPO_PARAM;

멤버

mtTime
템포가 취득된 시간 (이 멤버는 set 메소드에서는 사용되지 않고, 대신에 메소드 자체의 mtTime 파라미터가 사용된다).
dblTempo
DMUS_TEMPO_MIN ~ DMUS_TEMPO_MAX 의 범위에 있는 템포.

동작환경

헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParamEx


DMUS_TIMESIGNATURE

스타일의 박자 기호에 관한 정보를 취득하기 위해서,IDirectMusicStyle8::GetTimeSignature 메소드로 사용된다. 이 구조체는,rguidType 파라미터가 GUID_TimeSignature 이며, 트럭이 박자 기호 트럭 또는 스타일 트럭인 경우,DMUS_RHYTHM_PARAM 구조체나 다양한 파라미터 취득 메소드에서도 사용된다.

typedef struct _DMUS_TIMESIGNATURE {
    MUSIC_TIME mtTime;
    BYTE  bBeatsPerMeasure;
    BYTE  bBeat;
    WORD  wGridsPerBeat;
} DMUS_TIMESIGNATURE;

멤버

mtTime
이 박자 기호가 발생하는 뮤직 타임.
bBeatsPerMeasure
박자 기호의 분자.
bBeat
박자 기호의 분모.
wGridsPerBeat
박근처의 구라두 (소분할). 이 값은, 특정의 음악 이벤트의 타이밍 분해가능을 결정한다. 예를 들어, DMUS_SEGF_GRID 플래그를 사용한 세그먼트(segment)의 삽입을 들 수 있다 ( 「DMUS_SEGF_FLAGS 」를 참조).

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicPerformance8::SetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicSegment8::SetParam ,IDirectMusicTrack8::GetParamEx ,IDirectMusicTrack8::SetParamEx ,DMUS_TIMESIG_PMSG


DMUS_VALID_START_PARAM

rguidType 가 GUID_Valid_Start_Time 인 경우, 각종의 파라미터 취득 메소드를 호출할 때에 pParam 파라미터로서 사용된다.

typedef struct _DMUS_VALID_START_PARAM {
    MUSIC_TIME mtTime;
} DMUS_VALID_START_PARAM;

멤버

mtTime
세그먼트(segment)를 시작 할 수 있는, 다음의 유효한 포인트.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::GetParam ,IDirectMusicSegment8::GetParam ,IDirectMusicTrack8::GetParamEx


DMUS_VARIATIONS_PARAM

채널에 관련지을 수 있었던 바리에이션에 관한 정보를 보관 유지한다. GUID_Variations 파라미터를 취득할 때에 사용된다.

typedef struct _DMUS_VARIATIONS_PARAM {
    DWORD   dwPChannelsUsed;
    DWORD*  padwPChannels;
    DWORD*   padwVariations;
} DMUS_VARIATIONS_PARAM;

멤버

dwPChannelsUsed
사용중의 퍼포먼스 채널 번호를 받는 DWORD.
padwPChannels
사용중의 퍼포먼스 채널을 받는 DWORD 값으로부터 완성되는 배열의 주소.
padwVariations
각 채널에 대한 이펙트의 바리에이션으로부터 완성되는 배열. 설정된 각 비트가 바리에이션을 나타낸다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_VERSION

DMUS_OBJECTDESC 구조체에 기술된 오브젝트의 버젼 정보를 보관 유지한다.

typedef struct _DMUS_VERSION {
    DWORD  dwVersionMS;
    DWORD  dwVersionLS;
} DMUS_VERSION, FAR *LPDMUS_VERSION;

멤버

dwVersionMS
버젼 번호의 최상정도 DWORD.
dwVersionLS
버젼 번호의 최하정도 DWORD.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_WAVES_REVERB_PARAMS

DirectX 7.0 으로 제공되는 Microsoft 의 소프트웨어 신디사이저의 리바브에페크트에 관한 정보를 보관 유지한다.

typedef struct _DMUS_WAVES_REVERB_PARAMS {
    float  fInGain;
    float  fReverbMix;
    float  fReverbTime;
    float  fHighFreqRTRatio;
} DMUS_WAVES_REVERB_PARAMS;

멤버

fInGain
(출력 오버플로우를 막기 위한) 입력 게인. dB 단위로 지정한다. 디폴트값은 0 이다.
fReverbMix
리바브믹스. dB 단위로 지정한다. 값이 0 의 경우,100% 웨트인 리바브인 것을 의미한다 (다이렉트 시그널은 없다). 부의 값을 지정 하면, 시그널의 웨트감은 약해진다. 계수가 계산되어 리바브믹스의 양에 관계없이, 전체적인 출력 레벨이 거의 일정으로 유지된다. 디폴트값은 － 10.0 이다.
fReverbTime
리바브디케이 시간. 밀리 세컨드 (ms) 단위로 지정한다. 디폴트값은 1,000 이다.
fHighFreqRTRatio
고주파수와 그로바르리바브 시간의 비율. 특히 명료한 리바브가 필요하지 않은 한, 1 미만의 값으로 설정해야 한다. 예를 들어,fReverbTime 가 1000 ms 로,dHighFreqRTRatio 가 0.1 의 경우, 고주파수의 디케이 시간은 100 ms 이다. 디폴트값은 0.001 이다.

주의

Waves 사의 TrueVerb 리바브테크노로지는, Microsoft 에 라이센스 제공되고 있어 Microsoft 의 소프트웨어 신디사이저로 사용되는 SimpleVerb 로서 이행 되고 있다.

DirectX 8.0 이후에서는, 뮤직크리바브는 DMO 로 처리된다. 상세한 것에 대하여는, 「웨브리바브」를 참조할것.

동작환경

헤더 : dmusicc.h 로 선언.


KSPROPERTY

프로퍼티와 조작을 식별하기 위해서,IKsControl::KsProperty 메소드로 사용된다.

KSPROPERTY 는 KSIDENTIFIER 구조체로서 정의되어 다음과 같이 선언된다.

typedef struct {
    union {
        struct {
            GUID   Set;
            ULONG  Id;
            ULONG  Flags;
        };
        LONGLONG    Alignment;
    };
} KSIDENTIFIER, *PKSIDENTIFIER;

멤버

설정
프로퍼티 세트의 식별자. 이하의 프로퍼티 세트 GUID 는, DirectMusic 에 의해 사전에 정의되고 있다.
GUID_DMUS_PROP_DLS1
항목 0 은, 이 포토가 DLS 레벨 1 샘플의 다운로드를 지원 할지 어떨지를 나타내는 불리언 값이다.
GUID_DMUS_PROP_DLS2
항목 0 은, 이 포토가 DLS 레벨 2 샘플의 다운로드를 지원 할지 어떨지를 나타내는 불리언 값이다.
GUID_DMUS_PROP_Effects
항목 0 은, DMUS_EFFECT_NONE 또는 1 개(살) 이상의 이펙트 플래그를 포함한다 ( 「DMUS_PORTCAPS 」의 「dwEffectFlags 멤버」를 참조). 이 프로퍼티를 사용해, 이펙트의 현재 상태를 설정 또는 취득한다.
GUID_DMUS_PROP_GM_Hardware
항목 0 은, 이 포토가 하드웨어내에서 GM 를 지원 할지 어떨지를 나타내는 불리언 값이다.
GUID_DMUS_PROP_GS_Capable
항목 0 은, 이 포토가 Roland GS 확장의 최저 요건을 지원 할지 어떨지를 나타내는 불리언 값이다.
GUID_DMUS_PROP_GS_Hardware
항목 0 은, 이 포토가 하드웨어내에서 Roland GS 확장을 지원 할지 어떨지를 나타내는 불리언 값이다.
GUID_DMUS_PROP_INSTRUMENT2
항목 0 은, 이 포토가 DMUS_ARTICULATION2 구조체를 사용한 샘플의 다운로드를 지원 할지 어떨지를 나타내는 불리언 값이다.
GUID_DMUS_PROP_LegacyCaps
항목 0 은, 이 포토를 이행 하고 있는 기반의 Windows 멀티미디어 디바이스를 기술하는 MIDIINCAPS 구조체 또는 MIDIOUTCAPS 구조체이다. 이 포토의 능력의 구조체로 dwClass 가 DMUS_PC_INPUTCLASS 의 경우,MIDIINCAPS 구조체가 돌려주어진다. 그 이외의 경우는 MIDIOUTCAPS 구조체가 돌려주어진다.
GUID_DMUS_PROP_MemorySize
항목 0 은, 이 디바이스 위에의 샘플 RAM 의 빈바이트수이다.
GUID_DMUS_PROP_SampleMemorySize
항목 0 은, 이 디바이스로 이용 가능한 샘플 RAM 의 빈바이트수와 사용 바이트수이다.
GUID_DMUS_PROP_SamplePlaybackRate
항목 0 은, 신디사이저의 샘플링 레이트이다. DLS 레벨 2 파일 형식은, 조건부 체크를 지원 하므로, 리젼이나 아티큘레이션을 다운로드해야할 것인가 제발을 판정할 수 있다. 이것에 의해, 생성자는 다른 샘플링 레이트를 사용하는 것을 의도한 옵션의 웨이브를 생성 할 수 있다.
GUID_DMUS_PROP_SynthSink_DSOUND
항목 0 은, 이 포토가 DirectSound 를 지원 할지 어떨지를 나타내는 불리언 값이다.
GUID_DMUS_PROP_SynthSink_WAVE
항목 0 은, 이 포토가 waveOut 함수를 사용해 웨이브 출력을 지원 할지 어떨지를 나타내는 불리언 값이다.
GUID_DMUS_PROP_Volume
항목 1 (DMUS_ITEM_Volume)은, DMUS_VOLUME_MAX ~ DMUS_VOLUME_MIN 의 범위의 LONG 값이다. 부호 첨부의 값으로, 1/100dB 단위로 나타낸다. 이 값은, 모든 DLS 아티큘레이션이 실행된 후에, 모든 음성의 게인에 추가된다. 디폴트에서는, 포토를 퍼포먼스에 추가 하면 와, 이 프로퍼티는 마스터 볼륨으로 설정된다. 마스터 볼륨에 대해서는, 「글로벌 파라미터의 설정과 취득」을 참조할것.
GUID_DMUS_PROP_WavesReverb
항목 0 은, 리바브파라메이타를 보관 유지하는 DMUS_WAVES_REVERB_PARAMS 구조체이다.
GUID_DMUS_PROP_WriteLatency
항목 0 은, 유저 모드 신디사이저 (DMUS_PORTCAPS 구조체의 dwType 멤버는 DMUS_PORT_USER_MODE_SYNTH)의 기입 지연 시간이다. 유저 모드 신디사이저는, 그 출력을 DirectSound 에 스트림화한다. 기입 지연 시간이란, 신디사이저가 사운드 버퍼를 생성 하고 나서, 그것이 들릴 때까지의 지연 시간을 의미한다. 이 값을 조정하는 것으로써, 어플리케이션은 신디사이저를 보다 상세하게 튜닝 해, 사운드의 분단이 없는 최소 지연 시간을 설정할 수 있다. 일부의 컴퓨터, 특히, DirectSound 의 하드웨어 지원이 없는 컴퓨터의 경우, 초기 지연 시간은 다른 컴퓨터보다 매우 길어진다. 그 때문에, 값은 항상 최초로 읽히도록(듯이) 해, 상대값을 사용해 조정해야 한다. 기입 지연 시간은, 각 포토 인스턴스에 대해 다른 값을 가질 수가 있다. 프로퍼티는, 포토를 액티브하게 할 때마다 설정해야 한다. 어플리케이션으로 신디사이저의 기입 지연 시간을 오디오 패스로 설정하는 것은 추천 되지 않는다.
GUID_DMUS_PROP_WritePeriod
항목 0 은, 유저 모드 신디사이저 (DMUS_PORTCAPS 구조체의 dwType 멤버는 DMUS_PORT_USER_MODE_SYNTH)의 기입 간격이다. 유저 모드 신디사이저는, 그 출력을 DirectSound 에 스트림화한다. 기입 간격은, 신디사이저 세면대가 신디사이저의 믹싱을 허가하는 빈도를 제어한다. 이 값을 줄이는 것에 의해, 어플리케이션은 신디사이저의 전체적인 지연 시간을 단축할 수 있다. 다만, 10 밀리 세컨드 (ms)보다 작은 값을 지정 하면, CPU 의 부하가 증가한다. 기입 간격은, 표준적인 DirectSound 세면대를 사용하는 모든 포토 인스턴스에 대해 같은 값을 가진다. 프로퍼티는, 포토를 액티브하게 할 때마다 설정해야 한다. 이 프로퍼티는, 오디오 패스내의 포토로 설정할 수 없다.
GUID_DMUS_PROP_XG_Capable
항목 0 은, 이 포토가 Yamaha XG 확장의 최저 요건을 지원 할지 어떨지를 나타내는 불리언 값이다.
GUID_DMUS_PROP_XG_Hardware
항목 0 은, 이 포토가 하드웨어내에서 Yamaha XG 확장을 지원 할지 어떨지를 나타내는 불리언 값이다.
Id
프로퍼티 세트내의 항목.
플래그
다음의 몇개의 플래그를 사용해, 조작을 지정한다.
KSPROPERTY_TYPE_GET
지정된 프로퍼티 항목의 값을 취득한다.
KSPROPERTY_TYPE_SET
지정된 프로퍼티 항목의 값을 설정한다.
KSPROPERTY_TYPE_BASICSUPPORT
프로퍼티 세트용으로 이용할 수 있는 지원의 타입을 결정한다. IKsControl::KsProperty 가 *pvPropertyData 에 돌려주는 데이터는, KSPROPERTY_TYPE_GET 와 KSPROPERTY_TYPE_SET 의 어느 쪽인지, 또는 양쪽 모두를 포함한 DWORD 이다. 이것은, 그 조작이 가능한 것을 나타낸다.
정렬
DirectMusic 에서는 사용되지 않는다.

동작환경

헤더 : dmksctrl.h 로 선언.

참조

DirectMusic 포토의 프로퍼티 세트


DLS 구조체

여기에서는,다운로다브르사운드와 함께 사용되는 구조체의 레퍼런스 정보에 대해 설명한다. DirectMusic 는, DLS 콜렉션의 로드 및 신디사이저에의 음색의 다운로드로 발생하는 세세한 작업을 처리하기 위해(때문에), 대부분의 어플리케이션에서는 이러한 구조체를 사용할 필요가 없다. 이러한 구조체는, 주로 DLS 를 편집하는 어플리케이션용으로 준비되어 있다.

DLS 데이터의 사용법의 개요에 대해서는 「하위 레벨 DLS 」를 참조할것.

DLS 데이터 형식의 상세한 것에 대하여는, MMA (MIDI Manufacturers Association)의 규격을 참조할것.

여기에서는, 이하의 구조체에 대해 설명한다.

  • DMUS_ARTICPARAMS
  • DMUS_ARTICULATION
  • DMUS_ARTICULATION2
  • DMUS_COPYRIGHT
  • DMUS_DOWNLOADINFO
  • DMUS_EXTENSIONCHUNK
  • DMUS_INSTRUMENT
  • DMUS_LFOPARAMS
  • DMUS_MSCPARAMS
  • DMUS_OFFSETTABLE
  • DMUS_PEGPARAMS
  • DMUS_REGION
  • DMUS_VEGPARAMS
  • DMUS_WAVE
  • DMUS_WAVEARTDL
  • DMUS_WAVEDATA
  • DMUS_WAVEDL


DMUS_ARTICPARAMS

DLS 레벨 1 아티큐레이션체크의 파라미터를 기술한다. 아티큘레이션에 관한 모든 파라미터는 1 개의 체크에 보존되지만, 이 체크는 일련의 구조체에 의해 구성되어 있어 각 구조체는 아티큘레이션의 각 기능 분야에 도착해 정의하고 있다. 음색이나 리젼이 아티큘레이션을 이용하는 경우,DMUS_ARTICULATION 체크로부터의 인덱스를 사용해, 이 체크를 참조한다.

typedef struct {
    DMUS_LFOPARAMS LFO;
    DMUS_VEGPARAMS VolEG;
    DMUS_PEGPARAMS PitchEG;
    DMUS_MSCPARAMS Misc;
} DMUS_ARTICPARAMS;

멤버

LFO
저주파수발진기 (오씨레이터) 용의 파라미터를 보관 유지하는 DMUS_LFOPARAMS 구조체.
VolEG
볼륨 포락선 제네레이터용의 파라미터를 보관 유지하는 DMUS_VEGPARAMS 구조체.
PitchEG
피치 포락선 제네레이터용의 파라미터를 보관 유지하는 DMUS_PEGPARAMS 구조체.
Misc
최초의 빵 위치를 보관 유지하는 DMUS_MSCPARAMS 구조체.

주의

DLS 레벨 2 아티큘레이션은 별도 처리되어 이 구조체를 사용하지 않는다. 「DMUS_ARTICULATION2 」를 참조할것.

동작환경

헤더 : dmdls.h 로 선언.


DMUS_ARTICULATION

DLS 음색의 아티큐레이션체크에 대해 기술한다. DMUS_DOWNLOADINFO 구조체의 dwDLType 멤버내의 포맷 식별자가, DMUS_DOWNLOADINFO_INSTRUMENT 인 경우에 사용된다. 이 체크는, 이용 가능한 모든 아티큘레이션 데이터를 1 개의 리스트내 로 유지할 수 있다. 예를 들어, DLS 레벨 1 체크와 있는 메이커 고유의 아티큐레이션체크를 보관 유지할 수 있다. DLS 체크는 ulArt1Idx 에 의해 참조되어 추가의 아티큐레이션체크는 모두 ulFirstExtCkIdx 로 시작되는 리스트에 의해 참조된다.

typedef struct {
    ULONG ulArt1Idx;
    ULONG ulFirstExtCkIdx;
} DMUS_ARTICULATION;

멤버

ulArt1Idx
DMUS_OFFSETTABLE 구조 체내에 있는, DLS 아티큐레이션체크의 인덱스. 이 값이 0 의 경우, DLS 아티큘레이션은 존재하지 않는다.
ulFirstExtCkIdx
최초의 써드파티 확장 체크의 인덱스. 이 값이 0 의 경우, 이 아티큘레이션에 관련하는 써드파티 확장 체크는 존재하지 않는다.

주의

아티큐레이션체크는,DMUS_ARTICPARAMS 구조체로부터 완성된다.

동작환경

헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICULATION2


DMUS_ARTICULATION2

DLS 음색의 아티큐레이션체크에 대해 기술한다. DMUS_DOWNLOADINFO 구조체의 dwDLType 멤버내의 포맷 식별자가, DMUS_DOWNLOADINFO_INSTRUMENT2 인 경우에 사용된다. DLS 레벨 1 체크는 ulArt1Idx 에 의해 참조되어 추가의 아티큐레이션체크는 모두 ulFirstExtCkIdx 로 시작되는 리스트에 의해 참조된다. DLS 레벨 2 아티큐레이션체크는,ulNextArtIdx 도 사용한다.

typedef struct {
    ULONG ulArt1Idx;
    ULONG ulFirstExtCkIdx;
    ULONG ulNextArtIdx;
} DMUS_ARTICULATION;

멤버

ulArt1Idx
DMUS_OFFSETTABLE 구조 체내에 있는, DLS 아티큐레이션체크의 인덱스. 이 값이 0 의 경우, DLS 레벨 1 또는 레벨 2 아티큘레이션은 존재하지 않는다.
ulFirstExtCkIdx
최초의 써드파티 확장 체크의 인덱스. 이 값이 0 의 경우, 이 아티큘레이션에 관련하는 써드파티 확장 체크는 존재하지 않는다. DLS 레벨 2 체크는, 여기에 둘 수도 있다.
ulNextArtIdx
DLS 레벨 2 아티큘레이션을 보다 깊게 지원하기 위한 추가의 아티큐레이션체크의 인덱스.

주의

아티큐레이션체크는,CONNECTIONLIST 구조체와 거기에 계속되는 CONNECTION 구조체의 배열로 구성된다. 이러한 구조체는 Dls1.h 로 선언된다. 상세한 것에 대하여는, MMA (MIDI Manufacturers Association)가 발행하는 DLS 레벨 2 규격을 참조할것.

동작환경

헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICULATION


DMUS_COPYRIGHT

DLS 데이터내에 옵션의 저작권 체크를 기술한다.

typedef struct {
    ULONG cbSize;
    BYTE  byCopyright[ ];
} DMUS_COPYRIGHT;

멤버

cbSize
데이터의 사이즈.
byCopyright[ ]
저작권 데이터.

동작환경

헤더 : dmdls.h 로 선언.


DMUS_DOWNLOADINFO

포토에 다운로드되는 DLS 데이터의 헤더로서 사용된다. 이 구조체는 다운로드의 사이즈와 기능을 정의해, 그 후에는 항상 DMUS_OFFSETTABLE 체크가 계속된다.

typedef struct _DMUS_DOWNLOADINFO {
    DWORD dwDLType;
    DWORD dwDLId;
    DWORD dwNumOffsetTableEntries;
    DWORD cbSize;
} DMUS_DOWNLOADINFO;

멤버

dwDLType
다운로드되는 데이터 타입. 다음의 타입이 정의되고 있다.
DMUS_DOWNLOADINFO_INSTRUMENT
DMUS_INSTRUMENT 구조체로부터 시작되는 음색의 정의.
DMUS_DOWNLOADINFO_INSTRUMENT2
DMUS_INSTRUMENT 구조체로부터 시작되는, DLS 레벨 2 아티큘레이션을 지원 하는 음색의 정의.
DMUS_DOWNLOADINFO_WAVE
DMUS_WAVE 구조체로부터 시작되는 PCM 웨이브의 데이터.
dwDLId
오브젝트의 일의의 32 비트 식별자. 「주의」를 참조할것.
dwNumOffsetTableEntries
후에 계속되는 DMUS_OFFSETTABLE 구조 체내의 엔트리의 수.
cbSize
DMUS_DOWNLOADINFO,DMUS_OFFSETTABLE, 및 실제의 데이타체크의 합계 사이즈.

주의

dwDLId 내의 식별자는, 오브젝트를 접속하기 위해서 사용되어IDirectMusicPortDownload8::GetDLId 메소드를 사용해 취득된다. 주로, 음색내의 리젼을 웨브체크에 결합한다. 예를 들어, 웨이브 다운로드에 3 의 dwDLId 를 지정했을 경우, 음색 체크는, 몇개의 DMUS_REGION 구조체의 WaveLink.ulTableIndex 멤버에 값 3 이 배치된 형태로 다운로드된다. 이것은, 리젼이 웨브체크에 접속되고 있는 것을 나타낸다.

동작환경

헤더 : dmdls.h 로 선언.

참조

하위 레벨 DLS


DMUS_EXTENSIONCHUNK

DLS 확장 체크를 기술한다. DirectMusic 에 있어 미지의 확장을 DLS 파일 포맷에 가세했을 경우, 이러한 확장 모든 것을 이 가변 사이즈의 체크로 다운로드한다.

typedef struct {
    ULONG  cbSize;
    ULONG  ulNextExtCkIdx;
    FOURCC ExtCkID;
    BYTE   byExtCk[ ];
} DMUS_EXTENSIONCHUNK;

멤버

cbSize
체크의 사이즈.
ulNextExtCkIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 다음의 확장 체크의 인덱스. 이 값이 0 의 경우, 써드파티의 확장 체크는 그 이상 존재하지 않는다.
ExtCkID
체크 식별자.
byExtCk[ ]
데이터.

동작환경

헤더 : dmdls.h 로 선언.


DMUS_INSTRUMENT

DLS 다운로드체크내의 음색 정의를 보관 유지한다.

typedef struct {
    ULONG ulPatch;
    ULONG ulFirstRegionIdx;
    ULONG ulGlobalArtIdx;
    ULONG ulFirstExtCkIdx;
    ULONG ulCopyrightIdx;
    ULONG ulFlags;
} DMUS_INSTRUMENT;

멤버

ulPatch
음색의 패치 번호.
ulFirstRegionIdx
음색내의 최초의 리젼체크 ( 「DMUS_REGION 」를 참조)의 인덱스. 이것은 항상 1 개의 리젼으로 해야 하지만, 장래의 신디사이저 아키텍쳐와의 호환성을 고려해, 이 멤버의 값을 0 으로 하는 일도 인정된다.
ulGlobalArtIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 음색의 그로바르아티큐레이션체크 ( 「DMUS_ARTICULATION 」 및 「DMUS_ARTICULATION2 」를 참조)의 인덱스. 이 값이 0 의 경우, 이 음색에는 글로벌 아티큘레이션이 없다.
ulFirstExtCkIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 최초의 확장 체크 ( 「DMUS_EXTENSIONCHUNK 」를 참조)의 인덱스. DirectMusic 가 인식하고 있지 않는 새로운 체크를 추가하기 위해서 사용된다. 이 값이 0 의 경우, 이 음색에는 써드파티의 확장을 관련지을 수 있지 않았다.
ulCopyrightIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 옵션의 저작권 체크 ( 「DMUS_COPYRIGHT 」를 참조)의 인덱스. 이 값이 0 의 경우, 이 음색에는 저작권 정보를 관련지을 수 있지 않았다.
ulFlags
음색의 추가의 플래그. 다음의 플래그가 정의되고 있다.
DMUS_INSTRUMENT_GM_INSTRUMENT
이 음색은 General MIDI 표준의 음색이다. 패치가 중복 하고 있는 경우, GM 음색의 우선 순위는 반드시 다른 DLS 음색보다 낮아진다. 예를 들어, 패치 0 을 지정해 GM 음색을 다운로드해, 같은 패치 0 을 지정해 GM 이외의 음색을 다운로드했을 경우, 재생 시에 반드시 GM 이외의 음색이 선택된다.

동작환경

헤더 : dmdls.h 로 선언.


DMUS_LFOPARAMS

DLS 아티큐레이션체크용의 저주파수발진기 (LFO)를 정의한다. DMUS_ARTICPARAMS 구조체로 사용된다.

typedef struct {
    PCENT pcFrequency;
    TCENT tcDelay;
    GCENT gcVolumeScale;
    PCENT pcPitchScale;
    GCENT gcMWToVolume;
    PCENT pcMWToPitch;
} DMUS_LFOPARAMS;

멤버

pcFrequency
주파수. 피치 단위로 지정한다. 「주의」를 참조할것.
tcDelay
초기의 지연. 타임 센트 (time cent) 단위로 지정한다. 「주의」를 참조할것.
gcVolumeScale
트레몰로를 제어하는 출력 스케일. 감쇠 단위로 지정한다. 「주의」를 참조할것.
pcPitchScale
바이브라토를 제어하는 LFO 출력 스케일. 피치 단위로 지정한다. 「주의」를 참조할것.
gcMWToVolume
트레몰로를 제어하는 모듈레이션 휠 범위. 감쇠 단위로 지정한다. 「주의」를 참조할것.
pcMWToPitch
트레몰로를 제어하는 모듈레이션 휠 범위. 감쇠 단위로 지정한다. 「주의」를 참조할것.

주의

DLS 레벨 1 규격은, 타임 센트, 피치 센트, 및 감쇠를 32 비트 대수값으로서 정의한다. 상세한 것에 대하여는, MMA (MIDI Manufacturers Association)의 규격을 참조할것.

동작환경

헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICPARAMS


DMUS_MSCPARAMS

DLS 레벨 1 아티큐레이션체크의 빵을 정의한다. 이 구조체는,DMUS_ARTICPARAMS 구조체로 사용된다.

typedef struct {
    PERCENT ptDefaultPan;
} DMUS_MSCPARAMS;

멤버

ptDefaultPan
디폴트의 빵. － 50% ~ 50% 의 범위를 0.1% 단위로 지정해, 16 비트왼쪽 쉬프트 한 것.

주의

PERCENT 는 long 로서 정의된다. 빵의 값에 대해서는, MMA (MIDI Manufacturers Association)의 규격을 참조할것.

동작환경

헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICPARAMS


DMUS_OFFSETTABLE

포토에 다운로드중의 DLS 음색 데이터의 헤더로 사용된다.

typedef struct _DMUS_OFFSETTABLE {
    ULONG ulOffsetTable[DMUS_DEFAULT_SIZE_OFFSETTABLE];
} DMUS_OFFSETTABLE;

멤버

ulOffsetTable
데이터의 바이트 오프셋(offset)의 배열.

동작환경

헤더 : dmdls.h 로 선언.

참조

하위 레벨 DLS


DMUS_PEGPARAMS

DLS 레벨 1 아티큐레이션체크의 피치 포락선을 정의한다. DMUS_ARTICPARAMS 구조체로 사용된다.

typedef struct {
    TCENT   tcAttack;
    TCENT   tcDecay;
    PERCENT ptSustain;
    TCENT   tcRelease;
    TCENT   tcVel2Attack;
    TCENT   tcKey2Decay;
    PCENT   pcRange;
} DMUS_PEGPARAMS;

멤버

tcAttack
어택 시간. 타임 센트 (time cent) 단위로 지정한다. 「주의」를 참조할것.
tcDecay
디케이 시간. 타임 센트 단위로 지정한다. 「주의」를 참조할것.
ptSustain
sustain. 16 비트왼쪽 쉬프트 한 퍼센트 표시의 것 1/100 을 단위로서 사용한다.
tcRelease
릴리스 시간. 타임 센트 단위로 지정한다. 「주의」를 참조할것.
tcVel2Attack
어택 기간의 velocity. 타임 센트 단위로 지정한다. 「주의」를 참조할것.
tcKey2Decay
디케이 기간의 키. 타임 센트 단위로 지정한다. 「주의」를 참조할것.
pcRange
포락선 범위. 피치 단위로 지정한다. 「주의」를 참조할것.

주의

DLS 레벨 1 규격은, 타임 센트와 피치 센트를 32 비트 대수값으로서 정의한다. 이 구조 체내의 값에 대해서는, MMA (MIDI Manufacturers Association)의 규격을 참조할것.

동작환경

헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICPARAMS


DMUS_REGION

DLS 다운로드용의 리젼을 정의한다. 1 개(살) 또는 복수의 리젼을 1 개의 음색 버퍼에 묻어, 음색 헷다체크 DMUS_INSTRUMENT 에 의해 참조할 수 있다.

typedef struct {
    RGNRANGE RangeKey;
    RGNRANGE RangeVelocity;
    USHORT   fusOptions;
    USHORT   usKeyGroup;
    ULONG    ulRegionArtIdx;
    ULONG    ulNextRegionIdx;
    ULONG    ulFirstExtCkIdx;
    WAVELINK WaveLink;
    WSMPL    WSMP;
    WLOOP    WLOOP[1];
} DMUS_REGION;

멤버

RangeKey
이 리젼의 키 범위.
RangeVelocity
이 리젼의 velocity 범위.
fusOptions
이 리젼의 합성 옵션. 다음의 플래그가 정의되고 있다.
F_RGN_OPTION_SELFNONEXCLUSIVE
합성 엔진이 같은 노트의 2 번째의 노트 온을 받으면(자), 2 번째의 노트는 최초의 노트와 같게 연주된다. 디폴트에서는 이 옵션은 오프가 되어 있으므로, 합성 엔진은 최초의 노트에 노트 오프를 강제적으로 적용한다.
usKeyGroup
드럼 악기의 키 그룹. 키 그룹의 값에 의해, 같은 그룹에 소속하는 1 개의 드럼 악기내에서 복수의 리젼을 이용할 수 있다. 어느 키 그룹을 지정되어 있는 노트를 연주하고 있을 때, 같은 키 그룹을 지정해 다른 노트를 연주하도록(듯이) 합성 엔진이 지시를 받았을 경우, 합성 엔진은 같은 키 그룹의 값을 가지는 것 외의 모든 노트를 가능한 한 빨리 오프에 해야 한다. 현재, 키 그룹 1 ~ 15 가 유효하고, 0 은 키 그룹이 존재하지 않는 것을 의미한다.
ulRegionArtIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 리젼의 그로바르아티큐레이션체크의 인덱스. 이 값이 0 의 경우, 리젼은 아티큘레이션을 보관 유지하지 않고, 음색의 글로벌 아티큘레이션에 의존한다.
ulNextRegionIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 리젼 리스트내의 다음의 리젼의 인덱스. 이 값이 0 의 경우, 그 이상 리젼은 없다.
ulFirstExtCkIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 써드파티 확장 체크의 인덱스. 이 값이 0 의 경우, 리젼에는 확장 체크를 관련지을 수 있지 않았다.
WaveLink
리젼으로부터 웨이브에의 링크를 관리하는, 표준적인 DLS 구조체 (Dls1.h 헤더 파일내에서 선언되고 있다). WAVELINK 구조체의 ulTableIndex 멤버는, 관련지을 수 있었던 웨이브 버퍼의 다운로드 식별자를 제공한다 (상세한 것에 대하여는, 「DMUS_DOWNLOADINFO 」와「하위 레벨 DLS 」를 참조할것).
WSMP
웨이브의 재생을 관리하는, 표준적인 DLS 구조체 (Dls1.h 내에서 선언되고 있다 ). cSampleLoops 멤버가 1 의 경우, 계속되는 WLOOP 구조체는 루프의 시작 포인트와 종료 포인트를 보관 유지한다.
WLOOP[ ]
루프를 기술하는, 표준적인 DLS 구조체 (Dls1.h 내에서 선언되고 있다 ).

동작환경

헤더 : dmdls.h 로 선언.


DMUS_VEGPARAMS

DLS 레벨 1 아티큐레이션체크의 볼륨 포락선을 정의한다.

typedef struct {
    TCENT   tcAttack;
    TCENT   tcDecay;
    PERCENT ptSustain;
    TCENT   tcRelease;
    TCENT   tcVel2Attack;
    TCENT   tcKey2Decay;
} DMUS_VEGPARAMS;

멤버

tcAttack
어택 시간. 타임 센트 (time cent) 단위로 지정한다. 「주의」를 참조할것.
tcDecay
디케이 시간. 타임 센트 단위로 지정한다. 「주의」를 참조할것.
ptSustain
sustain. 16 비트왼쪽 쉬프트 한 퍼센트 표시의 것 1/100 을 단위로서 사용한다.
tcRelease
릴리스 시간. 타임 센트 단위로 지정한다. 「주의」를 참조할것.
tcVel2Attack
어택 기간의 velocity. 타임 센트 단위로 지정한다. 「주의」를 참조할것.
tcKey2Decay
디케이 기간의 키. 타임 센트 단위로 지정한다. 「주의」를 참조할것.

주의

DLS 레벨 1 규격은, 타임 센트를 32 비트 대수값으로서 정의한다. 이 구조 체내의 값에 대해서는, MMA (MIDI Manufacturers Association)의 규격을 참조할것.

동작환경

헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICPARAMS


DMUS_WAVE

DLS 다운로드용의 웨브체크를 정의한다.

typedef struct {
    ULONG  ulFirstExtCkIdx;
    ULONG  ulCopyrightIdx;
    ULONG  ulWaveDataIdx;
    WAVEFORMATEX  WaveformatEx;
} DMUS_WAVE;

멤버

ulFirstExtCkIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 써드파티 확장 체크의 인덱스. 이 값이 0 의 경우, 웨이브에는 확장 체크를 관련지을 수 있지 않았다.
ulCopyrightIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 저작권 체크의 인덱스. 이 값이 0 의 경우, 웨이브에는 저작권 정보를 관련지을 수 있지 않았다.
ulWaveDataIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 웨이브 데이터의 인덱스. 「DMUS_WAVEDATA 」를 참조할것.
WaveformatEx
체크의 웨이브 포맷을 지정하는 WAVEFORMATEX 구조체.

동작환경

헤더 : dmdls.h 로 선언.


DMUS_WAVEARTDL

웨이브 아티큘레이션을 다운로드하기 위한 정보를 보관 유지한다.

typedef struct _DMUS_WAVEARTDL {
    ULONG   ulDownloadIdIdx;
    ULONG   ulBus;
    ULONG   ulBuffers;
    ULONG   ulMasterDLId;
    USHORT  usOptions
}   DMUS_WAVEARTDL, *LPDMUS_WAVEARTDL;

멤버

ulDownloadIdIdx
각 버퍼의 다운로드 식별자.
ulBus
재생 버스.
ulBuffers
버퍼.
ulMasterDLId
하위 그룹의 마스터음의 다운로드 식별자.
usOptions
DLS 2 리젼 옵션.

동작환경

헤더 : dmdls.h 로 선언.


DMUS_WAVEDATA

DLS 웨이브 다운로드용의 데이타체크를 보관 유지한다. 웨이브 데이터의 성질은,DMUS_WAVE 구조체의 WaveformatEx 멤버에 의해 정의된다.

typedef struct {
    ULONG cbSize;
    BYTE byData[ ];
} DMUS_WAVEDATA;

멤버

cbSize
데이터의 사이즈.
byData[ ]
PCM 웨이브 데이터.

동작환경

헤더 : dmdls.h 로 선언.


DMUS_WAVEDL

신디사이저에 다운로드되는 웨이브 데이터에 관한 정보를 보관 유지한다.

typedef struct _DMUS_WAVEDL {
    ULONG  cbWaveData;
}   DMUS_WAVEDL, *LPDMUS_WAVEDL;

멤버

cbWaveData
웨이브 데이터의 바이트수.

동작환경

헤더 : dmdls.h 로 선언.


DirectMusic 의 파일 형식

여기에서는, DirectMusic Producer 로 생성 되어IDirectMusicLoader8::GetObject 또는 IDirectMusicLoader8::LoadObjectFromFile 가 불려 갔을 때에 DirectMusic 에 의해 읽어내지는, 파일의 형식에 대해 설명한다. 대부분의 어플리케이션에서는, 이러한 파일을 직접 해석할 것은 없다. 이 파일 형식의 정보는, 뮤직 오쏘링 어플리케이션이나 DirectMusic 플러그 인의 개발자가, 데이터를 호환성이 있는 형식에서 보존하거나 독자적인 오브젝트에 데이터를 로드할 수 있도록(듯이) 하기 위해서 제공되고 있다.

DirectMusic 데이터는, RIFF (Resource Interchange File Format)로 보존된다. 이하의 주제는, RIFF 파일에 관한 일반적인 정보로 구성된다.

  • RIFF 에 대해
  • RIFF 의 표기법

이하의 주제에서는, DirectMusic 데이터가 RIFF 체크내에서 어떻게 편성되는지를 설명한다.

  • 공통의 체크
  • 오디오 패스 형식
  • 밴드 형식
  • 코드 맵 형식
  • 컨테이너 형식
  • DirectSound 버퍼 구성 형식
  • 이펙트 형식
  • 참조 리스트
  • 스크립트 형식
  • 세그먼트(segment) 형식
  • 노래 형식
  • 스타일 형식
  • 툴 형식
  • 툴 그래프 형식
  • 트럭 형식
  • 웨브헷다체크

다음의 주제는, RIFF 체크에 데이터를 저장 하기 위해서 사용되는 구조체의 레퍼런스이다.

  • DirectMusic 의 파일 데이터 구조체


RIFF 에 대해

RIFF 파일의 기본적인 구성 단위는 "체크" 인. 체크는, 데이터의 논리적인 단위이다. 각 체크에는, 다음의 필드가 포함되어 있다.

  • 체크 식별자를 나타내는, 4 문자의 코드 (FOURCC). 관습적으로, 체크타이프의 등록에는 대문자를 사용해, 그 이외에서는 소문자를 사용한다.
  • 체크의 데이터 멤버의 사이즈를 지정하는 DWORD 값.
  • 데이터.

다른 체크에 포함되어 있는 체크를,"사브체크" 이라고 부르는. 사브체크를 포함할 수가 있는 체크는, 체크 식별자가 RIFF 또는 LIST 의 체크 뿐이다.

파일의 최초의 체크는, RIFF 로서 식별되지 않으면 안 된다. 파일내의 그 외의 체크는 모두, 이 체크의 사브체크가 된다. RIFF 체크는, 형식이라고도 불린다.

LIST 체크는, 사브체크를 그룹화 한 것이다. 이러한 사브체크의 몇개인가는 반복해 나타나는 경우가 있지만, LIST 는 배열은 아니다. 용어가 혼동하기 쉬운 일도 있다. 예를 들어, <part-list> 라고 하는 라벨이 붙은 체크는, 파트의 리스트이다고 예상할지도 모르지만, 실제로는,"파트" 체크의 요소의 리스트이며, 1 개의 파트를 나타내고 있다.

RIFF 체크에서는, 데이터 필드의 최초의 4 바이트에 추가 필드가 포함된다. 추가 필드에서는, 체크의 형식 타입이 제공된다. 형식 타입은, 파일에 저장 되는 데이터의 형식을 식별하는, 4 문자의 코드이다. 예를 들어, DirectMusic 의 스타일의 형식 타입은 DMST 이다.

LIST 체크도, 데이터 필드의 최초의 4 바이트에 추가 필드를 포함하고 있다. 이 필드에는, 필드의 "리스트 타입" 이 포함된다. 리스트 타입은, 리스트의 내용을 식별하는 4 문자의 코드이다. 예를 들어, DirectMusic 의 스타일은, 퍼포먼스의 특정의 파트 (음색 트럭)에 관한 데이터를 포함한, 리스트 타입이 "part" 의 LIST 체크를 가지고 있다.

주 DirectMusic 파일로 사용 떠날 수 있어 모든 FOURCC 코드에는, 대응하는 매크로가 Dmusicf.h 에 준비되어 있다. 예를 들어, DMST 의 FOURCC 는,DMUS_FOURCC_STYLE_FORM 매크로에 의해 돌려주어진다.

일반적인 RIFF 파일의 상세한 것에 대하여는, Platform SDK 문서의 「Resource Interchange File Format Services」를 참조할것.


RIFF 의 표기법

다음의 DirectMusic 파일의 설명은, 종래의 RIFF 파일의 표기법의 서브 세트를 사용하고 있다. 이 표기법의 주된 부분을, 다음 표에 나타낸다.

표기법 | 설명
<element> | "element" 라고 하는 라벨이 붙은 파일 요소, 또는 element 타입
[ <element> ] | 옵션의 파일 요소
<element>... | 지정한 요소의 1 개 또는 복수의 카피
[<element>]... | 지정한 요소의 0 이상의 카피
name, 'name', NAME, 또는 'NAME' | 형식 타입, 리스트 타입, 또는 체크의 FOURCC 식별자
// 코멘트 | 코멘트

라벨은 표기법에서만 사용되어 파일 자체에서는 사용되지 않는다. <cheh-ck> 라고 하는 라벨은, 고유의 FOURCC 식별자 및 형식을 가지는 체크를 참조한다. 이 종류의 체크가 표기법으로 나타나는 경우는, 같은 라벨이 사용된다.

라벨에 관련지을 수 있었던 데이터 또는 서브 요소는, 다음의 예의 같게 나타내진다.

<cheh-ck> -> cheh( <DMUS_IO_CHORDENTRY> )

이 표기법은, <cheh-ck> 라고 하는 라벨이 붙은 체크가,FOURCC 식별자의 "cheh" 와 거기에 계속되는 DMUS_IO_CHORDENTRY 구조체로 구성되어 있는 것을 나타낸다.

주 모든 체크내의 데이터에는, 선두에, 데이터의 사이즈를 나타내는 DWORD 값이 붙어 있다. 이 요소는 표기법에서는 나타나지 않는다.

다음의 예는, 리스트 요소를 나타내고 있다. FOURCC "LIST" 와 리스트 식별자의 "cmap", 및 <choe-list> 라고 하는 라벨이 붙은 1 개(살) 또는 복수의 요소로 구성되어 있다. <choe-list> 요소는, 다른 장소에 전개된다.

<cmap-list> -> LIST( 'cmap'
    <choe-list>... )


공통의 체크

다음의 체크는, 다양한 리스트체크나 형식에서 사용된다.

<guid-ck>

이것은, 요소의 GUID 식별자이다.

<guid-ck> -> guid( <GUID> )

<vers-ck>

이 체크에는, 요소의 버젼 정보가 포함된다.

<vers-ck> -> vers( <DMUS_IO_VERSION > )

<UNFO-list>

UNFO 체크는, RIFF INFO 리스트를 닮아 있다. 다만, Unicode 문자를 사용하는 점이 차이가 난다. INFO 및 UNFO 리스트는, NULL 로 종료하는 캐릭터 라인을 포함한, 다양한 체크로 구성된다.

<UNFO-list> -> LIST( 'UNFO'
    <unfo-text-ck>...
    )

참조

참조 리스트


오디오 패스 형식

다음 표 기법은, 오디오 패스 형식의 편성을 나타내고 있다.

RIFF( 'DMAP'
    [<guid-ck>]        // 패스의 GUID
    [<vers-ck>]        // 버젼 정보
    [<UNFO-list>]      // 이름, 작자, 저작권, 코멘트
    [<DMTG-form>]      // 툴 그래프
    [<pcsl-list>]      // 포토 구성
    [<dbfl-list>]...// DirectSound 버퍼 디스크립터
)

모든 요소가 생략 가능하다.

<guid-ck>, <vers-ck>, <UNFO-list>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<DMTG-form>

「툴 그래프 형식」을 참조할것.

<pcsl-list>

이 리스트에는, 포토의 구성에 관한 정보가 저장 된다.

<pcsl-list> -> LIST( 'pcsl'
    <pcfl-list>...
    )

포토 구성 리스트는, 다음의 형식의 리스트의 배열이다.

LIST( 'pcfl'
    <pcfh-ck>          // 헷다체크
    <pprh-ck>          // 포토의 생성에 사용되는 포토 파라미터
    [<dbfl-list>]...// DirectSound 버퍼 디스크립터
    [<pchl-list>]      // P 채널의 버퍼에의 할당
    )

포토 구성 리스트는 복수의 체크로 구성되어 다음과 같이 포토 구성과 파라미터를 나타내는 헤더가 선두를 뒤따른다.

<pcfh-ck> -> pcfh( <DMUS_IO_PORTCONFIG_HEADER > )

<pprh-ck> -> pprh( <DMUS_PORTPARAMS8 > )

옵션의 버퍼 디스크립터는, 다음의 형식에서 각 체크내에 저장 된다.

<dbfl-list> -> LIST( 'dbfl'
    <ddah-ck>       // 버퍼 속성 헤더
    [<DSBC-form>]   // 버퍼 구성
)

버퍼 기술 리스트의 선두에는, 버퍼의 속성을 나타내는 헤더가 붙는다.

<ddah-ck> -> ( 'ddah' < DMUS_IO_BUFFER_ATTRIBUTES_HEADER  > )

헤더의 뒤에는, 옵션의 DirectSound 버퍼 구성 형식이 계속된다. 이것은 표준 버퍼 형식에는 불필요하다.

포토 구성 리스트의 마지막 체크는, 버퍼에의 퍼포먼스 채널의 할당 정보를 저장 하는 리스트이다.

pchl-list -> LIST( 'pchl'
    <pchh-ck>...
)

이 리스트는, 각각이 버퍼에의 채널의 1 개의 할당을 나타내는 체크의 배열이다.

<pchh-ck> -> pchh(
    <DMUS_IO_PCHANNELTOBUFFER_HEADER >
    <GUID>...// 버퍼를 지정하는 GUID 의 배열
)

<dbfl-list>

오디오 패스 형식의 마지막 부분에는, 옵션의 버퍼 디스크립터가, 포토 구성 리스트 <pcsl-list> 와 같은 형식에서 저장 된다.


밴드 형식

다음 표 기법은, 밴드 파일의 최상정도 레벨의 체크 또는 형식을 나타내고 있다. 밴드 형식은, 다른 체크에 포함할 수도 있다.

RIFF( 'DMBD'
    [<guid-ck>]     // 밴드의 GUID
    [<vers-ck>]     // 옵션의 버젼 정보
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    <lbil-list>     // 음색
    )

<guid-ck>, <vers-ck>, <UNFO-list>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<lbil-list>

데이터는, 리스트의 배열에 포함된다.

<lbil-list> -> LIST( 'lbil'
    <lbin-list>...
    )

각 음색은, 리스트중에 다음의 형식에서 기술된다.

<lbin-list> -> LIST( 'lbin'
    <bins-ck>
    [<DMRF-list>]
    )

음색 리스트내에서, 다음의 체크에는 음색을 나타내는 헤더가 포함된다.

<bins-ck> -> bins( <DMUS_IO_INSTRUMENT > )

음색 리스트에는, <DMRF-list> 를 포함할 수도 있다. 이 경우는, DLS 파일에의 참조이다. 「참조 리스트」를 참조할것.


코드 맵 형식

다음 표 기법은, 코드 맵 파일의 최상정도 레벨의 체크, 또는 형식의 구성을 나타내고 있다.

RIFF( 'DMPR'
    <perh-ck>       // 코드맙헷다체크
    [ <guid-ck> ]   // GUID 체크
    [ <vers-ck> ]   // 바젼체크
    [ <UNFO-list> ] // UNFO 리스트
    <chdt-ck>       // 코드데이타체크
    <chpl-list>     // 코드 팔레트
    <cmap-list>     // 코드 그래프
    <spsq-list>     // 싸인 포스트리스트
)

<perh-ck>

이것은, 코드 맵의 기본적인 헤더 정보이다.

<perh-ck> -> perh( <DMUS_IO_CHORDMAP > )

<guid-ck>, <vers-ck>, <UNFO-list>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<chdt-ck>

<chdt-ck> -> chdt(
    <WORD>    // DMUS_IO_CHORDMAP_SUBCHORD 의 사이즈
    <DMUS_IO_CHORDMAP_SUBCHORD >...
    )

<chdt-ck> 체크에는, 서브 코드 근처의 바이트수를 나타내는 WORD 값과 고유의 서브 코드의 배열이 포함된다. 이 파일외의 파트에서 참조되고 있는 서브 코드 식별자는 모두, 이 배열의 인덱스에 직접 대응한다.

<chpl-list>

<chpl-list> -> LIST( 'chpl'
    <chrd-list>...
    )

이 리스트에는 코드 팔레트가 포함된다. 이 리스트에는 24 의 항목이 필요하다.

<chrd-list> -> LIST( 'chrd'
    <UNAM-ck>    // 코드명
    <sbcn-ck>    // 서브 코드의 인덱스
    )

이 리스트에는, 기본적인 코드 정보가 포함된다. 이 정보는, 코드의 이름과 준거하는 서브 코드의 식별자의 리스트이다.

<UNAM-ck> -> UNAM ( <WCHAR>... )

UNAM 체크는, 코드의 이름을 저장 한다.

<sbcn-ck> -> sbcn( <WORD>... )

"sbcn" 체크에는, 1 개(살) 또는 복수의 서브 코드 식별자가 포함된다. 이것들은, <chdt-ck> 에 있는 배열의 인덱스에 직접 대응한다. 최대로 4 개의 코드가 지원 되고 있다.

<cmap-list>

이 리스트에는, 코드 맵의 코드 접속 그래프 전체가 포함된다. 코드 맵의 대부분의 데이터는, 이 체크에 존재한다.

<cmap-list>  ->  LIST( 'cmap'
    <choe-list>...
    )

각 리스트에는, 코드 그래프의 1 개의 엔트리의 데이터와 다음에 코드 그래프에 나타나는 모든 코드에의 포인터가 포함된다.

<choe-list> -> LIST( 'choe'
    <cheh-ck>      // 코드 엔트리 데이터
    <chrd-list>    // 코드 데이터. 위에의 설명을 참조
    <ncsq-ck>      // 다음의 코드 리스트
    )

<cheh-ck> -> cheh( <DMUS_IO_CHORDENTRY > )

이것은, 코드 엔트리 헤더이다. 구조체의 식별자는, 코드 접속 그래프의 식별자이며, 서브 코드 식별자는 아니다.

<ncsq-ck> -> ncsq (
    <WORD>         // DMUS_IO_NEXTCHORD 의 사이즈
    <DMUS_IO_NEXTCHORD >...
    )

"ncsq" 체크에는, 접속 그래프의 코드를 다른 코드에 접속하는 데이터가 포함된다. 접속 그래프의 각 코드는, 16 비트의 식별자로 나타내진다.

<spsq-list>

이 체크에는, 각 싸인 포스트의 데이터가 포함된다.

<spsq-list> -> LIST( 'spsq'
    <spst-list>...
    )

<spst-list> 리스트에는, 1 개의 싸인 포스트의 데이터가 포함된다. 데이터는, 헤더, 코드 정보, 및 옵션의 카덴트코드로 구성된다.

<spst-list>  ->  LIST( 'spst'
    <spsh-ck>
    <chrd-list>     // 코드 데이터
    [ <cade-list> ] // 카덴트코드
    )

<spsh-ck> 리스트에는, 싸인 포스트데이터가 포함된다.

<spsh-ck> -> spsh( <DMUS_IO_CHORDMAP_SIGNPOST > )

<chrd-list> 에 대해서는, 전에 설명한 <chpl-list> 를 참조할것.

<cade-list> 체크에는, 카덴트코드의 정보가 포함된다. 이 리스트에서는 2 개까지의 카덴트코드가 지원 되고 있다. 3 개(살) 이상의 코드는 무시된다.

<cade-list> -> LIST( 'cade'
    <chrd-list>...
    )


컨테이너 형식

컨테이너 형식은, 세그먼트(segment) 또는 스타일 형식 등, 다른 체크를 저장 하는 체크이다. 세그먼트(segment) 파일이나 스크립트 파일에 포함할 수가 있다. 구조는 다음과 같다.

RIFF ( 'DMCN'
    <conh-ck>       // 콘테나헷다체크
    [<guid-ck>]     // 컨테이너의 GUID
    [<vers-ck>]     // 옵션의 버젼 정보
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    <cosl-list>     // 오브젝트의 리스트
)

<conh-ck>

이 체크에는, 헤더 구조가 포함된다.

<conh-ck> -> 'conh' ( <DMUS_IO_CONTAINER_HEADER > )

<guid-ck>, <vers-ck>, <UNFO-list>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<cosl-list>

컨테이너 형식의 마지막 요소는, 컨테이너내의 오브젝트를 나타내는 체크의 배열이다.

<cosl-list> -> LIST ( 'cosl'
    <cobl-list>...
    )

각 오브젝트는, 다음의 형식에서 저장 된다.

<cobl-list> -> LIST( 'cobl'
    [<coba-ck>]
    <cobh-ck>       // 필요한 헤더
    [<data> ] or [ DMRF-list ]

선두의 요소는 앨리어스(alias), 즉, 이 오브젝트의 컨테이너내에서 사용되는 별명이다.

<coba-ck> -> coba( <WCHAR>...)  // Null 로 끝나는 캐릭터 라인

2 번째의 요소는, 오브젝트의 헤더이다.

<cobh-ck> -> cobh ( <DMUS_IO_CONTAINED_OBJECT_HEADER > )

헤더의 뒤에는 보통, <cobh-ck> 로 지정되는 타입의 오브젝트 데이터가 계속된다. 이것은,세그먼트(segment) 형식이나스타일 형식 등,RIFF 체크의 형식을 취할 수가 있다. 이것이 DMRF 리스트인 경우는, 오브젝트에의 참조이다. DMRF 의 상세한 것에 대하여는, 「참조 리스트」를 참조할것.


DirectSound 버퍼 구성 형식

다음 표 기법은, DirectSound 버퍼 구성에 관한 정보를 저장 하는 체크의 구성을 나타내고 있다.

RIFF ( 'DSBC'
    [<guid-ck>]     // 이 버퍼 구성의 GUID 식별자
    [<vers-ck>]     // 옵션의 버젼 정보
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    <dsbd-ck>       // DirectSound 버퍼 디스크립터
    [<bsid-ck>]     // 버스 식별자
    [<ds3d-ck>]     // 3-D 파라미터
    [<fxls-list>]   // 이펙트 디스크립터
    )

<guid-ck>, <vers-ck>, <UNFO-list>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<dsbd-ck>

DirectSound 버퍼 디스크립터는, 다음의 구성을 가진다.

<dsbd-ck> -> 'dsbd' (
    <DSOUND_IO_DSBUFFERDESC_dx_DSOUND_IO_DSBUFFERDESC_dxaudio>
    )

<bsid-ck>

버스 식별자는, 다음의 체크에 저장 된다.

<bsid-ck> -> 'bsid' ( <DSOUND_IO_DSBUSID_dx_DSOUND_IO_DSBUSID_dxaudio> )

DSOUND_IO_DSBUSID 구조체는, 사이즈가 체크사이즈로 지정되는 바이트 배열이다.

<ds3d-ck>

버퍼의 3D 파라미터는, 다음의 체크에 저장 된다.

<ds3d-ck> -> 'ds3d'( <DSOUND_IO_3D_dx_DSOUND_IO_3D_dxaudio> )

<fxls-list>

다음의 리스트에는, 버퍼에 관련지을 수 있었던 DMO 에 관한 정보가 저장 된다.

<fxls-list> -> LIST ( 'fxls'
    <DSFX-form>...
    )

각각의 DMO 는,이펙트 형식에서 저장 된다.


이펙트 형식

이펙트 형식은,DMO 이펙트를 나타낸다.

RIFF ( 'DSFX'
    <fxhr-ck>
    [<data-ck>]
)

<fxhr-ck>

헷다체크는, 이펙트를 나타낸다.

<fxhr-ck> -> fxhr ( <DSOUND_IO_DXDMO_HEADER_dx_DSOUND_IO_DXDMO_HEADER_dxaudio> )

<data-ck>

데이타체크는, 이펙트 파라미터의 값이 DMO 의 예기 하는 형식에서 저장 된 옵션세트이다.

<data-ck> -> data ( <DSOUND_IO_DXDMO_DATA_dx_DSOUND_IO_DXDMO_DATA_dxaudio> )


참조 리스트

참조 리스트체크에는, 다른 파일의 오브젝트에의 참조에 관한 정보가 포함된다. 예를 들어, 밴드 오브젝트에는, 다른 파일에 있는 DLS 콜렉션에의 참조가 포함되어 있는 경우가 있다. 사브체크는, 많은 다양한 체크로 사용된다.

참조 리스트의 표기법은, 다음과 같이 된다.

<DMRF-list> ->LIST( 'DMRF'
    <refh-ck>       // 참조 헤더
    [<guid-ck>]     // 오브젝트의 GUID
    [<date-ck>]     // 파일의 일자
    [<name-ck>]     // 이름
    [<file-ck>]     // 파일명
    [<catg-ck>]     // 카테고리명
    [<vers-ck>]     // 버젼 정보
)

<refh-ck>

데이터는, 참조되고 있는 오브젝트에 관한 정보를 포함한 헤더로부터 시작된다.

<refh-ck> -> refh( <DMUS_IO_REFERENCE > )

다른 체크는 모두 옵션이다.

<guid-ck>

「공통의 체크」를 참조할것.

<date-ck>

데이타체크에는,FILETIME 구조체의 데이터가 포함된다.

<date-ck> -> date( <FILETIME> )

<name-ck>, <file-ck>, <catg-ck>

이름, 파일명, 및 카테고리명은, NULL 로 끝나는 캐릭터 라인이다.

<name-ck> -> name( <WCHAR>... )
<file-ck> -> file( <WCHAR>...)  // Null 로 끝나는 캐릭터 라인
<catg-ck> -> catg( <WCHAR>...)  // Null 로 끝나는 캐릭터 라인

<vers-ck>

「공통의 체크」를 참조할것.


스크립트 형식

여기에서는, DirectMusic 의 스크립트에 관한 정보를 저장 하는 체크의 구조에 대해 설명한다.

RIFF ( 'DMSC'
    <schd-ck>       // 스크리프트헷다체크
    [<guid-ck>]     // 스크립트의 GUID
    [<vers-ck>]     // 옵션의 버젼 정보
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    <scve-ck>       // DirectMusic 의 버젼
    <DMCN-form>     // 스크립트가 참조하는 컨텐츠의 컨테이너
    <scla-ck>       // 스크립트 언어
    <scsr-ck> or <DMRF> // 원시 코드
)

<schd-ck>

헷다체크에는,DMUS_IO_SCRIPT_HEADER 구조체의 플래그가 포함된다.

<schd-ck> -> schd( <DMUS_IO_SCRIPT_HEADER> )

<guid-ck>, <vers-ck>, <UNFO-list>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<scve-ck>

이 체크는, 스크립트가 오쏘링 된 대상의 DirectMusic 의 버젼을 나타낸다.

<scve-ck> -> scve( <DMUS_IO_VERSION > )

<DMCN-form>

이 체크에 대해서는, 「컨테이너 형식」을 참조할것.

<scla-ck>

이 체크는, 스크립팅 언어를 나타내는 NULL 로 끝나는 캐릭터 라인이다.

<scla-ck> -> scla( <WCHAR>... )

<scsr-ck> 또는 <DMRF>

마지막 체크에는, 원시 코드가 WCHAR 값의 NULL 로 끝나는 배열로서 포함된다.

<scsr-ck> -> scsr( <WCHAR>... )

다른 방법으로서 마지막 체크는, 스크립트 코드를 포함한 텍스트 파일을 가리키는,참조 리스트 체크로 할 수도 있다. 이 텍스트 파일은 DirectMusic 오브젝트는 아니기 때문에,DMUS_IO_REFERENCE 의 guidClassID 멤버는 GUID_NULL 가 아니면 안된다.


세그먼트(segment) 형식

다음 표 기법은, 세그먼트(segment) 파일의 최상정도 레벨의 체크의 구성을 나타내고 있다. 이 형식은,컨테이너 형식내에 포함할 수도 있다.

RIFF( 'DMSG'
    <segh-ck>       // 세그먼트헷다체크
    [<guid-ck>]     // 세그먼트(segment)의 GUID
    [<vers-ck>]     // 옵션의 버젼 정보
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    [<DMCN-form>]   // 파일에 파묻힌 오브젝트의 옵션의 컨테이너
    <trkl-list>     // 트럭
    [<DMTG-form>]   // 옵션의 툴 그래프
    [<DMAP-form>]   // 옵션의 오디오 패스
    )

<segh-ck>

이 체크에는, 세그먼트(segment)의 기본적인 헤더 정보가 포함된다.

<segh-ck> -> segh( <DMUS_IO_SEGMENT_HEADER > )

<guid-ck>, <vers-ck>, <UNFO-list>

「공통의 체크」를 참조할것.

<DMCN-form>

「컨테이너 형식」을 참조할것.

<trkl-list>

이것은 트럭 리스트이다. 각 트럭은,트럭 형식에 캡슐화된다.

<trkl-list> -> LIST( 'trkl'
    <DMTK-form>...
    )

<DMTG-form>

「툴 그래프 형식」을 참조할것.

<DMAP-form>

「오디오 패스 형식」을 참조할것.


노래 형식

DirectX 8.0 에서는 이행 되지 않는다.

다음 표 기법은, 노래 파일의 최상정도 레벨의 체크의 구성을 나타내고 있다. 이 형식은,컨테이너 형식내에 포함할 수도 있다.

RIFF( 'DMSO'
    <sngh-ck>       // 송헷다체크
    [<guid-ck>]     // 노래의 GUID
    [<vers-ck>]     // 옵션의 버젼 정보
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    [<DMCN-form>]   // 파일에 파묻힌 오브젝트의 컨테이너
    <segl-list>     // 세그먼트(segment)
    [<tlgl-list>]   // 툴 그래프
    [<DMAP-form>]   // 모든 세그먼트(segment)가 공유하는 오디오 패스
    <srsl-list>     // 세그먼트(segment) 참조
)

<sngh-ck>

이 체크에는, 노래의 기본적인 헤더 정보가 포함된다.

<sngh-ck> -> sngh ( <DMUS_IO_SONG_HEADER > )

<guid-ck>, <vers-ck>, <UNFO-list>

「공통의 체크」를 참조할것.

<DMCN-form>

「컨테이너 형식」을 참조할것.

<segl-list>

<segl-list> -> LIST( 'segl'
    <ssgl-list>...
    )

노래 세그먼트(segment) 리스트에는 세그먼트(segment)의 배열이 포함되어 각각의 배열은, 다음의 리스트에 기술된다.

<ssgl-list> -> LIST( 'ssgl'
    [<DMSG-form>]
    [<DMRF-list>]
    )

이 리스트에는,세그먼트(segment) 형식 또는참조 리스트중 한쪽이 포함된다.

<tlgl-list>

<tlgl-list> -> LIST( 'tlgl'
    <DMTG-form>...
    )

툴 그래프 리스트에는,툴 그래프 형식의 배열이 포함된다.

<DMAP-form>

이 체크는, 노래에 포함되는 모든 세그먼트(segment)가 공유하는 오디오 패스를 기술한다. 「오디오 패스 형식」을 참조할것.

<srsl-list>

노래 형식의 마지막 체크는, 세그먼트(segment) 참조 리스트의 배열이며, 다음과 같이 구성된다.

<srsl-list> -> LIST( 'srsl'
    <sgrl-list>...
    )

<sgrl-list> -> LIST( 'sgrl'
    <sgrh-ck>       // 세그먼트(segment) 참조 헤더
    <segh-ck>       // 세그먼트(segment) 헤더
    [<UNFO-list>]   // 이름, 작자, 저작권, 코멘트
    [<strh-ck>]     // 세그먼트트란지션체크
    [<trsl-list>]   // 트럭 참조
    )

이 리스트의 선두에는, 세그먼트(segment) 참조 헤더가 붙는다.

<sgrh-ck> -> ( 'sgrh' <DMUS_IO_SEGREF_HEADER > )

다음은 세그먼트(segment) 헤더이다. <segh-ck> 체크의 구문에 대해서는, 「세그먼트(segment) 형식」을 참조할것.

<UNFO-list> 에 대해서는, 「공통의 체크」를 참조할것.

세그먼트트란지션체크는, 다른 세그먼트(segment)로부터 이 세그먼트(segment)에의 유효한 트란지션을 지정한다. 구조는 다음과 같다.

<strh-ck> -> ( strh
    <DMUS_IO_TRANSITION_DEF >    // 디폴트의 트란지션
    <DMUS_IO_TRANSITION_DEF >...// 추가의 트란지션
    )

세그먼트(segment) 참조 리스트의 마지막 부분에는, 트럭 참조가 포함된다. 이것은, 복수 세그먼트(segment)의 트럭으로부터 세그먼트(segment)를 생성 하기 위해서 사용된다.

<trsl-list> -> LIST( 'trsl'
    <tkrl-list>...
    )

이 리스트에는, 트럭 참조 리스트의 배열이 포함된다. 각 배열은, 다음과 같이 구성된다.

<tkrl-list> -> ( 'tkrl'
    <tkrh-ck>       // 트럭 참조 헷다체크
    <trkh-ck>       // 트락크헷다체크
    [<trkx-ck>]     // 트럭 플래그
    )

이 리스트에는 3 개의 체크가 포함된다. 최초의 체크에는, 트럭을 저장 하는 세그먼트(segment)를 식별하는 헤더 구조체가 포함된다.

tkrh-ck -> tkrh( <DMUS_IO_TRACKREF_HEADER > )

트럭 참조 리스트의 나머지의 2 개의 체크에 대해서는, 「트럭 형식」을 참조할것.


스타일 형식

다음 표 기법은, 스타일 파일의 최상정도 레벨의 체크의 구성을 나타내고 있다. 이 형식은,컨테이너 형식내에 포함할 수도 있다.

RIFF( 'DMST'
    <styh-ck>       // 스타이르헷다체크
    <guid-ck>       // 일의의 식별자
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    [<vers-ck>]     // 바젼체크
    <part-list>...// 패턴으로 사용되는, 스타일중의 파트의 배열
    <pttn-list>...// 스타일중의 패턴의 배열
    <DMBD-form>...// 스타일중의 밴드의 리스트
    [<prrf-list>]   // 스타일중의 코드 맵 참조의 리스트
)

<styh-ck>

이 체크에는, 스타일의 기본적인 헤더 정보가 포함된다.

<styh-ck> -> styh( <DMUS_IO_STYLE > )

<guid-ck>, <UNFO-list>, <vers-ck>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<part-list>

스타일내의 각 파트는, 체크내에 다음의 형식에서 기술된다.

<part-list> -> LIST('part'
    <prth-ck>       // 파트헷다체크
    [<UNFO-list>]
    [<note-ck>]     // 파트안의 노트
    [<crve-ck>]     // 파트안의 커브
    [<mrkr-ck>]     // 파트안의 마커
    [<rsln-ck>]     // 파트안의 바리에이션 분해가능
    [<anpn-ck>]     // 파트안의 해결 안티시페이션
    )

다음 표기에 나타내도록(듯이), 파트 리스트에는 헤더, 옵션의 UNFO 체크, 및 요소의 리스트가 포함된다 (UNFO 리스트에 대해서는, 「공통의 체크」를 참조할것).

<prth-ck> -> prth( <DMUS_IO_STYLEPART > )

<note-ck> -> note(
    < DWORD >  // DMUS_IO_STYLENOTE 의 사이즈
    < DMUS_IO_STYLENOTE  >...
    )

<crve-ck> -> crve(
    < DWORD >  // DMUS_IO_STYLECURVE 의 사이즈
    < DMUS_IO_STYLECURVE  >...
    )

<mrkr-ck> -> mrkr(
    < DWORD > // DMUS_IO_STYLEMARKER 의 사이즈
    < DMUS_IO_STYLEMARKER  >...
    )

<rsln-ck> -> rsln(
    < DWORD > // DMUS_IO_STYLERESOLUTION 의 사이즈
    < DMUS_IO_STYLERESOLUTION  >...
    )

<anpn-ck> -> anpn(
    < DWORD > Size of DMUS_IO_STYLE_ANTICIPATION
    < DMUS_IO_STYLE_ANTICIPATION  >...
    )

<pttn-list>

각 패턴은, 체크내에 다음의 형식에서 기술된다.

<pttn-list> -> LIST( 'pttn'
    <ptnh-ck>       // 파탄헷다체크
    <rhtm-ck>       // 코드 매칭용의 리듬의 리스트
    <swpt-ck>       // 패턴 스윗치 포인트의 리스트
    [<UNFO-list>]
    [<mtfs-ck>]     // 모티프 설정 체크
    [<DMBD-form>]   // 패턴에 관련지을 수 있었던 밴드
                    // (모티프용)
    <pref-list>...// 파트 참조 ID 의 배열
    )

패턴 리스트의 최초의 체크는, 헤더이다.

<ptnh-ck> -> ptnh( <DMUS_IO_PATTERN > )

2 번째의 체크는, 리듬 리스트이다.

<rhtm-ck> -> rhtm( <DWORD>... )

이 체크는, 각 소절 마다 1 개의 DWORD 배열로 구성되어 리듬 패턴을 나타낸다. 비트의 배치에 대해서는,DMUS_RHYTHM_PARAM 의 dwRhythmPattern 멤버를 참조할것.

패턴 리스트의 3 번째의 체크는, 스잇치포인트체크이다.

<swpt-ck> -> swpt( <DWORD>... )

스잇치포인트체크는, 각 소절 마다 1 개의 DWORD 배열로 구성되어 패턴을 시작 할 수 있는 유효한 포인트를 나타낸다.

옵션의 UNFO 리스트에 대해서는, 「공통의 체크」를 참조할것.

패턴 리스트의 다음의 체크는, 모티프 설정을 나타낸다.

<mtfs-ck> -> mtfs( <DMUS_IO_MOTIFSETTINGS > )

패턴 리스트의 <DMBD-form> 체크에 대해서는, 「밴드 형식」을 참조할것.

패턴 리스트의 마지막 체크는, 파트 참조 리스트이다.

<pref-list> -> LIST( 'pref'
    <prfc-ck>   // 파트 참조 체크
    )

요소는 파트 참조뿐이다.

<prfc-ck> -> prfc( <DMUS_IO_PARTREF > )

<DMBD-form>

스타일 형식의 다음의 체크는,밴드 형식이다.

<prrf-list>

마지막 체크에는, 코드 맵 참조의 배열이 포함된다.

<prrf-list> -> LIST( 'prrf'
    <DMRF-list>...
    )

<DMRF-list> 의 상세한 것에 대하여는, 「참조 리스트」를 참조할것.


툴 형식

툴 형식에는, 툴에 관한 정보가 포함된다. 툴은,툴 그래프 형식에 묻는지, 다른 파일에 저장 할 수가 있다.

<DMTL-form> -> RIFF( 'DMTL'
    <tolh-ck>
    [<data>]        // 툴 데이터
)

<tolh-ck>

이것은 트르헷다체크이다.

<tolh-ck> -> tolh( <DMUS_IO_TOOL_HEADER > )

<data>

<data> 요소는,DMUS_IO_TOOL_HEADER 구조체로 식별되는 타입의 체크이다. 이 체크의 형식은, 툴의 정의에 따라서 달라, 리스트 또는 보통의 체크가 된다.


툴 그래프 형식

트르그라후체크는, 최상정도 레벨의 형식, 또는세그먼트(segment) 형식이나컨테이너 형식의 사브체크로서 기술된다.

RIFF( 'DMTG'
    [<guid-ck>]     // 툴 그래프의 GUID
    [<vers-ck>]     // 버젼 정보
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    <toll-list>     // 툴의 리스트
)

<guid-ck>, <vers-ck>, <UNFO-list>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<toll-list>

트르그라후체크의 주요하고 유일 요구되는 파트는 툴 리스트이다. 툴 리스트는 툴 형식의 배열로 구성된다.

<toll-list> -> LIST( 'toll'
    <DMTL-form>...
    )

<DMTL-form> 체크의 상세한 것에 대하여는, 「툴 형식」을 참조할것.


트럭 형식

트럭 형식에는, 1 개의 트럭에 관한 정보가 포함된다. 이 형식은,세그먼트(segment) 형식에 묻는지, 독자적인 파일에 저장 할 수가 있다.

<DMTK-form> -> RIFF( 'DMTK'
    <trkh-ck>
    [<trkx-ck>]     // 옵션의 트럭 플래그
    [<guid-ck>]     // 트럭 오브젝트 인스턴스의 GUID
    [<vers-ck>]     // 버젼 정보
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    [<data>]        // 트럭 데이터
)

<trkh-ck>

최초의 체크에는, 트럭의 기본적인 헤더 정보가 포함된다.

<trkh-ck> -> trkh( <DMUS_IO_TRACK_HEADER > )

<trkx-ck>

이 옵션의 체크에는, 트럭의 플래그가 포함된다.

<trkx-ck> -> trkx( <DMUS_IO_TRACK_EXTRAS_HEADER > )

<guid-ck>, <vers-ck>, <UNFO-list>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<data>

트럭 형식의 마지막 요소는, 트럭의 데이터이다. 데이터로 사용되는 체크의 종류는,DMUS_IO_TRACK_HEADER 구조체로 식별된다. 표준 트락크체크는, 다음과 같이 정의되고 있다.

  • 밴드 트럭 형식
  • 코드 트럭 리스트
  • 코드 맵 트럭 리스트
  • 코만드트락크체크
  • 가사 트럭 리스트
  • 마커 트럭 리스트
  • 멜로디 편성 트럭 리스트
  • 뮤트트락크체크
  • 파라미터 제어 트럭 리스트
  • 패턴 트럭 형식
  • 스크립트 트럭 리스트
  • 세그먼트(segment) 방아쇠 트럭 리스트
  • 시켄스트락크체크
  • 사인포스트트락크체크
  • 스타일 트럭 리스트
  • 시스템에크스크루시브트락크체크
  • 텐포트락크체크
  • 박자 기호 트럭 리스트
  • 웨이브 트럭 리스트


밴드 트럭 형식

밴드 트럭 형식은 최상정도의 형식에도 사용할 수 있지만,트럭 형식의 데이터 부분이라고 해도 사용된다. 구조는 다음과 같다.

RIFF( 'DMBT'
    [<bdth-ck>]     // 밴드 트랙헤더-
    [<guid-ck>]     // 밴드 트럭의 GUID
    [<vers-ck>]     // 버젼 정보
    [<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
    <lbdl-list>     // 밴드 리스트의 리스트
    )

<bdth-ck>

이 옵션의 체크에는, 밴드 트럭의 헤더 정보가 포함된다. 구조체의 데이터는, 자동 다운로드의 플래그뿐이다.

<bnth-ck> -> bdth( <DMUS_IO_BAND_TRACK_HEADER > )

<guid-ck>, <vers-ck>, <UNFO-list>

이러한 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

<lbdl-list>

마지막 체크에는, 1 개(살) 또는 복수의 밴드가 포함된다.

<lbdl-list> -> LIST( 'lbdl'
    <lbnd-list>...
    )

각 밴드는, 다음의 리스트에 캡슐화된다.

<lbnd-list> -> LIST( 'lbnd'
    <bdih-ck> or <bd2h-ck>
    <DMBD-form>
    )

밴드 리스트는 다음의 헤더로 시작된다. 종래 형식의 파일에서는, 이것은 <bdih-ck> 이며, 신형식의 파일에서는 <bd2h-ck> 를 사용한다.

<bdih-ck> -> ( <DMUS_IO_BAND_ITEM_HEADER > )

<bd2h-ck> -> ( <DMUS_IO_BAND_ITEM_HEADER2 > )

헤더의 뒤에밴드 형식이 계속되어, 밴드의 음색에 관한 정보가 포함된다.


코드 트럭 리스트

코드 트럭 리스트에는,트럭 형식의 코드 데이터가 포함된다. 구조는 다음과 같다.

<cord-list> -> LIST( 'cord'
    <crdh-ck>       // 헤더
    <crdb-ck>       // 코드 본체의 체크
    )

<crdh-ck>

<crdh-ck> -> crdh ( <DWORD> )

헤더는 DWORD 값으로, 상위 8 비트에 코드 루트, 하위 24 비트에 스케일이 포함된다. 이러한 비트의 설명에 대해서는, 「DMUS_IO_SUBCHORD 」를 참조할것.

코드 트럭 리스트의 데이터 본체는, 코드 변경 및 컴퍼넌트 서브 코드에 관한 정보로 구성된다.

<crdb-ck> -> crdb(
    <DWORD>           // DMUS_IO_CHORD 의 사이즈
    <DMUS_IO_CHORD >
    <DWORD>           // 서브 코드의 수
    <DWORD>           // DMUS_IO_SUBCHORD 의 사이즈
    <DMUS_IO_SUBCHORD >...
    )


코드 맵 트럭 리스트

코드 맵 트럭 리스트에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<pftr-list> -> LIST('pftr'
    <pfrf-list>...
    )

데이터는, 타임 스탬프와 코드 맵에의 참조를 포함한, 1 개(살) 또는 복수의 리스트로 구성된다.

<pfrf-list> -> LIST('pfrf'
    <stmp-ck>
    <DMRF-list>
    )

타임스탄프체크의 표기법은, 다음과 같다.

<stmp-ck> -> stmp( <DWORD> )

<DMRF-list> 의 상세한 것에 대하여는, 「참조 리스트」를 참조할것.


코만드트락크체크

코만드트락크체크에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<cmnd-ck> -> cmnd(
    <DWORD>    // DMUS_IO_COMMAND 의 사이즈
    <DMUS_IO_COMMAND >...
    )


가사 트럭 리스트

가사 트럭 리스트에는,트럭 형식의 데이터가 포함된다.

<lyrt-list> -> LIST( 'lyrt'
    <lyrl-list>
    )

가사 트럭 리스트의 유일한 체크는, 가사 이벤트의 배열을 저장 하는 이제(벌써) 1 개의 리스트이다.

<lyrl-list> -> LIST(
    <lyre-list>...
    )

각각의 가사 이벤트는, 다음과 같이 이제(벌써) 1 개의 리스트에 저장 된다.

<lyre-list> -> LIST(
    <lyrh-ck>         // 이벤트헷다체크
    <lyrn-ck>         // 통지 텍스트
    )

선두의 체크는 헤더이다.

<lyrh-ck> -> lyrh( <DMUS_IO_LYRICSTRACK_EVENTHEADER > )

2 번째의 체크에는, 이벤트에 관련지을 수 있었던 텍스트가, NULL 로 끝나는 캐릭터 라인으로서 포함된다.

<lyrn-ck> -> lyrn( <WCHAR>... )


마커 트럭 리스트

마커 트럭 리스트에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<mark-list> -> LIST ( 'MARK'
    [<vals-ck>]
    [<play-ck>]
)

리스트의 선두 요소는, 유효한 시작 포인트를 정의하는 체크의 배열이다.

<vals-ck> -> vals(
    DWORD    // DMUS_IO_VALID_START 의 사이즈
    <DMUS_IO_VALID_START >...
    )

2 번째의 요소는, 유효한 연주 포인트를 정의하는 체크의 배열이다.

<play-ck> -> play(
    DWORD    // DMUS_IO_PLAYMARKER 의 사이즈
    <DMUS_IO_PLAYMARKER >...
    )


멜로디 편성 트럭 리스트

DirectX 8.0 에서는 이행 되지 않는다.

멜로디 편성 트럭 리스트에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<mfrm-list> -> LIST( 'mfrm'
    <mlfh-ck>    // 멜로디 편성 헤더
    <mlfb-ck>    // 멜로디 편성 본체
    )

멜로디 편성 헷다체크는 다음과 같은 구성이다.

<mlfb-ck> -> mlfb( <DMUS_IO_MELFORM > )

데이터 본체는, 다음의 체크에 저장 된다.

<mlfb-ck> -> mlfb(
    <DWORD>    // DMUS_IO_MELODY_FRAGMENT 의 사이즈
    <DMUS_IO_MELODY_FRAGMENT>...
    )

DMUS_IO_MELODY_FRAGMENT 는,DMUS_MELODY_FRAGMENT 에 동일한 것으로서 정의된다.


뮤트트락크체크

뮤트트락크체크에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<mute-ck> -> mute(
    <DWORD>    // DMUS_IO_MUTE 의 사이즈
    <DMUS_IO_MUTE >...
    )


파라미터 제어 트럭 리스트

파라미터 제어 트럭 리스트에는,트럭 형식의 데이터가 포함된다.

<prmt-list> -> LIST( 'prmt'
    <prol-list>...
    )

리스트에는, 리스트의 배열이 포함된다. 각각의 리스트는 오브젝트를 나타낸다.

<prol-list> -> LIST( 'proh'
    <proh-ck>       // 오브제크트헷다체크
    <prpl-list>...// 파라미터의 배열
    )

오브젝트 리스트의 최초의 체크는, 헤더이다.

<proh-ck> -> proh( <DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER > )

2 번째의 체크에는, 다음에 나타내도록(듯이) 구성된 파라미터 리스트가 포함된다.

<prpl-list> -> LIST( 'prpl'
    <prph-ck>       // 파라미터 헤더
    <prcc-ck>       // 커브의 배열
    )

파라미터 리스트의 헤더는, 다음과 같이 나타내진다.

<prph-ck> -> prph( <DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER > )

커브의 배열은, 다음의 체크로 나타내진다.

<prcc-ck> -> prcc(
    <DWORD>   // DMUS_IO_PARAMCONTROLTRACK_CURVEINFO 의 사이즈
   <DMUS_IO_PARAMCONTROLTRACK_CURVEINFO >...// mtTime 의 순서에 소트 된 커브
    )


패턴 트럭 형식

패턴 트럭 형식은, 최상정도 레벨의 형식으로 할 수도 있지만,트럭 형식의 데이터라고 해도 사용된다. 구조는 다음과 같다.

RIFF( 'DMPT'
    <styh-ck>       // 스타이르헷다체크
    <pttn-list>     // 패턴
    )

<pttn-list> 및 <pttn-list> 에 대해서는, 「스타일 형식」을 참조할것.


스크립트 트럭 리스트

스크립트 트럭 리스트에는,트럭 형식의 데이터가 포함된다.

<scrt-list> -> LIST( 'scrt'
    <scrl-list>
    )

리스트에는, 스크립트 이벤트의 배열을 저장 하는 다른 리스트가 포함된다.

<scrl-list> -> LIST( 'scrl'
    <scre-list>...
    )

각각의 <scre-list> 체크는, 다음과 같이 이벤트를 나타낸다.

<scre-list> -> LIST( 'scre'
    <scrh-ck>         // 이벤트헷다체크
    <DMRF>            // 참조
    <scrn-ck>         // 루틴명
    )

각 스크립트 트럭 이벤트의 선두에는, 헤더가 붙는다.

<scrh-ck> -> 'scrh'( <DMUS_IO_SCRIPTTRACK_EVENTHEADER > )

DMRF 체크에 대해서는, 「참조 리스트」를 참조할것.

스크립트 트럭 이벤트의 마지막 체크는, NULL 로 끝나는 루틴명이다.

<scrn-ck> -> 'scrn'( <WCHAR>... )


세그먼트(segment) 방아쇠 트럭 리스트

세그먼트(segment) 방아쇠 트럭 리스트에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<SEGT-list> -> LIST( 'segt'
    [<sgth-ck>]     // 세그먼트(segment) 트랙헤더-
    <lsgl-list>     // 세그먼트(segment) 리스트의 리스트
    )

선두의 체크는, 트랙헤더-이다.

<sgth-ck> -> 'sgth' ( <DMUS_IO_SEGMENT_TRACK_HEADER > )

다음의 체크는, 세그먼트(segment)의 배열을 포함한 리스트이다.

<lsgl-list> -> LIST( 'lsgl'
    <lseg-list>...
    )

각각의 "lseg" 리스트는, 단일의 세그먼트(segment) 항목을 나타낸다.

<lseg-list> -> LIST( 'lseg'
    <sgih-ck>
    <DMRF-list>
    [<snam-ck>]    // 모티프명
    )

세그먼트(segment) 항목의 최초의 체크는, 헤더이다.

<sgih-ck> -> ( <DMUS_IO_SEGMENT_ITEM_HEADER > )

이 후에는, 세그먼트(segment) 파일 또는 스타일 파일에의 참조가 계속된다. DMUS_SEGMENTTRACKF_MOTIF 플래그가 항목 헤더에 존재하는 경우, 이것은 스타일에의 참조이다. 상세한 것에 대하여는, 「참조 리스트」를 참조할것.

DMUS_SEGMENTTRACKF_MOTIF 플래그가 항목 헤더에 존재하는 경우, 세그먼트(segment) 항목의 마지막 체크에는, NULL 로 끝나는 모티프명이 포함된다.

<snam-ck> -> ( <WCHAR>... )


시켄스트락크체크

시켄스트락크체크에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<seqt> -> seqt(
    <evtl-ck>
    <curl-ck>
    )

시켄스트락크체크에는, 순서 항목과커브 항목의 2 개의 체크를 포함할 수가 있다.

<evtl-ck> -> evtl(
    <DWORD>     // DMUS_IO_SEQ_ITEM 의 사이즈
    <DMUS_IO_SEQ_ITEM >...
    )

<curl-ck> -> curl(
    <DWORD>     // DMUS_IO_CURVE_ITEM 의 사이즈
    <DMUS_IO_CURVE_ITEM >...
    )

주 시켄스트락크체크는, RIFF 와 LIST 체크만이 사브체크를 가질 수가 있다고 하는 표기법에는 따르지 않는다.


사인포스트트락크체크

사인포스트트락크체크에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<sgnp-list> -> sgnp(
    <DWORD>    // DMUS_IO_SIGNPOST 의 사이즈
    <DMUS_IO_SIGNPOST >...
    )


스타일 트럭 리스트

스타일 트럭 리스트에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<sttr-list> -> LIST('sttr'(
    <strf-list>...
    )

데이터는, 타임 스탬프와 스타일에의 참조를 포함한, 1 개(살) 또는 복수의 리스트로 구성된다.

<strf-list> -> LIST('strf'(
    <stmp-ck>
    <DMRF-list>
    )

최초의 체크에는, 다음과 같이 타임 스탬프 데이터가 포함된다.

<stmp-ck> -> stmp( <DWORD> )

<DMRF-list> 의 상세한 것에 대하여는, 「참조 리스트」를 참조할것.


시스템에크스크루시브트락크체크

시스템에크스크루시브트락크체크에는,트럭 형식의 데이터가 포함된다. 이것은, 시스템에크스크루시브멧세이지 항목의 배열이다. 각각,DMUS_IO_SYSEX_ITEM 구조체와 거기에 계속되는 dwSysExLength 멤버로 지정되는 바이트수로 구성된다.

<syex-ck> -> 'syex' (
    {
    <DMUS_IO_SYSEX_ITEM >
    <BYTE>...// 데이터
    }...
    )


텐포트락크체크

텐포트락크체크에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<tetr-ck> -> tetr(
    <DWORD>    // DMUS_IO_TEMPO_ITEM 의 사이즈
    <DMUS_IO_TEMPO_ITEM >...
    )


박자 기호 트럭 리스트

박자 기호 트럭 리스트에는,트럭 형식의 데이터가 포함된다. 구조는 다음과 같다.

<tims-list> -> LIST( 'TIMS'
    <tims-ck> // 박자 기호
    )

박자 기호 배열에는, 다음의 체크가 포함된다.

<tims-ck> -> tims (
    <DWORD>  // DMUS_IO_TIMESIGNATURE_ITEM 의 사이즈
    <DMUS_IO_TIMESIGNATURE_ITEM >...
    )


웨이브 트럭 리스트

다음 표 기법은, 웨이브 트럭의 데이터를 저장 하는 체크의 구성을 나타내고 있다.

<wavt-list> -> LIST ( 'wavt'
    <wath-ck>      // 웨이브 트랙헤더-
    <wavp-list>...// 웨이브 파트
    }

<wath-ck>

이 체크에는, 웨이브의 헤더 정보가 포함된다. 웨이브 파트를 기술하는 리스트의 배열이 후에 계속된다.

<wath-ck> -> wath( <DMUS_IO_WAVE_TRACK_HEADER > )

<wavp-list>

<wavp-list> -> LIST ( 'wavp'
    <waph-ck>       // 웨이브 파트 헤더
    <wavi-list>     // 웨이브 항목
    )

웨이브 파트 리스트는 다음의 헤더로 시작된다.

<waph-ck> -> 'waph' ( <DMUS_IO_WAVE_PART_HEADER > )

웨이브 파트 리스트의 2 번째의 파트는, 웨이브 항목의 배열이다.

<wavi-list> -> LIST( 'wavi'
    <wave-list>...
    )

각각의 웨이브 항목은, 다음과 같이 리스트체크에 기술된다.

<wave-list> -> LIST( 'wave'
    <waih-ck>       // 웨이브 항목 헤더
    <DMRF-list>     // 웨이브 오브젝트에의 참조
    )

웨이브 기술은 다음의 헤더로 시작된다.

<waih-ck> -> ( <DMUS_IO_WAVE_ITEM_HEADER > )

<DMRF-list> 의 상세한 것에 대하여는, 「참조 리스트」를 참조할것.


웨브헷다체크

웨브헷다체크는, DirectMusic 의 웨이브 파일에 부가되는 특수한 체크이다. 이 체크는, 스트리밍 기능을 지정한다.

<wavh-ck> -> ( <DMUS_IO_WAVE_HEADER > )


DirectMusic 의 파일 데이터 구조체

여기에서는, DirectMusic 파일로 사용되는 데이터 구조체의 레퍼런스 정보를 기술한다. 표준적인 DirectMusic 의 각 오브젝트는,IPersistStream 인터페이스를 사용해, 그 자체의 데이터를 로드하기 (위해)때문에, 대부분의 어플리케이션에서는, 이러한 구조체에 관한 지식은 필요없다. 이러한 구조체는, DirectMusic 와 호환성이 있는 포맷으로 데이터를 보존할 필요가 있는 뮤직 오쏘링 어플리케이션용으로 주로 준비되어 있다.

DirectMusic 파일에서는, 이하의 구조체가 사용된다.

  • DMUS_IO_BAND_ITEM_HEADER
  • DMUS_IO_BAND_ITEM_HEADER2
  • DMUS_IO_BAND_TRACK_HEADER
  • DMUS_IO_BUFFER_ATTRIBUTES_HEADER
  • DMUS_IO_CHORD
  • DMUS_IO_CHORDENTRY
  • DMUS_IO_CHORDMAP
  • DMUS_IO_CHORDMAP_SIGNPOST
  • DMUS_IO_CHORDMAP_SUBCHORD
  • DMUS_IO_COMMAND
  • DMUS_IO_CONTAINED_OBJECT_HEADER
  • DMUS_IO_CONTAINER_HEADER
  • DMUS_IO_CURVE_ITEM
  • DMUS_IO_INSTRUMENT
  • DMUS_IO_LYRICSTRACK_EVENTHEADER
  • DMUS_IO_MELFORM
  • DMUS_IO_MOTIFSETTINGS
  • DMUS_IO_MUTE
  • DMUS_IO_NEXTCHORD
  • DMUS_IO_PARAMCONTROLTRACK_CURVEINFO
  • DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER
  • DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER
  • DMUS_IO_PARTREF
  • DMUS_IO_PATTERN
  • DMUS_IO_PCHANNELTOBUFFER_HEADER
  • DMUS_IO_PLAYMARKER
  • DMUS_IO_PORTCONFIG_HEADER
  • DMUS_IO_REFERENCE
  • DMUS_IO_SCRIPT_HEADER
  • DMUS_IO_SCRIPTTRACK_EVENTHEADER
  • DMUS_IO_SEGMENT_HEADER
  • DMUS_IO_SEGMENT_ITEM_HEADER
  • DMUS_IO_SEGMENT_TRACK_HEADER
  • DMUS_IO_SEGREF_HEADER
  • DMUS_IO_SEQ_ITEM
  • DMUS_IO_SIGNPOST
  • DMUS_IO_SONG_HEADER
  • DMUS_IO_STYLE
  • DMUS_IO_STYLE_ANTICIPATION
  • DMUS_IO_STYLECURVE
  • DMUS_IO_STYLEMARKER
  • DMUS_IO_STYLENOTE
  • DMUS_IO_STYLEPART
  • DMUS_IO_STYLERESOLUTION
  • DMUS_IO_SUBCHORD
  • DMUS_IO_SYSEX_ITEM
  • DMUS_IO_TEMPO_ITEM
  • DMUS_IO_TIMESIG
  • DMUS_IO_TIMESIGNATURE_ITEM
  • DMUS_IO_TOOL_HEADER
  • DMUS_IO_TRACK_EXTRAS_HEADER
  • DMUS_IO_TRACK_HEADER
  • DMUS_IO_TRACKREF_HEADER
  • DMUS_IO_TRANSITION_DEF
  • DMUS_IO_VALID_START
  • DMUS_IO_VERSION
  • DMUS_IO_WAVE_HEADER
  • DMUS_IO_WAVE_ITEM_HEADER
  • DMUS_IO_WAVE_PART_HEADER
  • DMUS_IO_WAVE_TRACK_HEADER
  • DSOUND_IO_3D
  • DSOUND_IO_DSBUFFERDESC
  • DSOUND_IO_DSBUSID
  • DSOUND_IO_DXDMO_DATA
  • DSOUND_IO_DXDMO_HEADER

참조

DirectMusic 의 파일 형식


DMUS_IO_BAND_ITEM_HEADER

밴드 체인지에 관한 정보를 보관 유지한다. 종래 형식의 파일의밴드 트럭 형식에서 사용된다. 현재는 DMUS_IO_BAND_ITEM_HEADER2 에 인계되고 있다.

typedef struct _DMUS_IO_BAND_ITEM_HEADER {
    MUSIC_TIME lBandTime;
} DMUS_IO_BAND_ITEM_HEADER;

멤버

lBandTime
밴드 체인지의 타임.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_BAND_ITEM_HEADER2

밴드 체인지에 관한 정보를 보관 유지한다. 밴드 트럭 형식에서 사용된다.

typedef struct _DMUS_IO_BAND_ITEM_HEADER2 {
    MUSIC_TIME lBandTimeLogical;
    MUSIC_TIME lBandTimePhysical;
} DMUS_IO_BAND_ITEM_HEADER2;

멤버

lBandTimeLogical
밴드 체인지를 관련지을 수 있고 있는 뮤직 타임.
lBandTimePhysical
밴드 체인지가 이펙트를 발생시키는 정확한 시간. 논리 타임과 대충 같다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

세그먼트(segment)의 타이밍


DMUS_IO_BAND_TRACK_HEADER

밴드 트럭의 디폴트 동작에 관한 정보를 보관 유지한다. 밴드 트럭 형식에서 사용된다.

typedef struct _DMUS_IO_BAND_TRACK_HEADER {
    BOOL bAutoDownload;
} DMUS_IO_BAND_TRACK_HEADER;

멤버

bAutoDownload
세그먼트(segment)를 연주하고 있을 때의, 음색을 자동 다운로드하기 위한 플래그.

주의

자동 다운로드의 상세한 것에 대하여는, 「밴드의 사용법」을 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_BUFFER_ATTRIBUTES_HEADER

DirectSound 버퍼의 속성을 나타낸다. 오디오 패스 형식에서 사용된다.

typedef struct _DMUS_IO_BUFFER_ATTRIBUTES_HEADER {
    GUID    guidBufferID;
    DWORD   dwFlags;
} DMUS_IO_BUFFER_ATTRIBUTES_HEADER;

멤버

guidBufferID
버퍼 구성의 일의인 식별자. 표준 버퍼 타입에는 다음의 값이 정의되고 있다.

GUID_Buffer_Reverb
GUID_Buffer_EnvReverb
GUID_Buffer_Stereo
GUID_Buffer_3D_Dry
GUID_Buffer_Mono

dwFlags
버퍼를 나타내는 플래그. 다음의 값이 정의되고 있다.
DMUS_BUFFERF_DEFINED
표준 버퍼 타입의 1 개.
DMUS_BUFFERF_MIXIN
믹스 인 버퍼.
DMUS_BUFFERF_SHARED
오디오 패스간에 공유되는 버퍼.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_CHORD

코드 변경에 관한 정보를 보관 유지한다. 코드 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_CHORD {
    WCHAR       wszName[16];
    MUSIC_TIME  mtTime;
    WORD        wMeasure;
    BYTE        bBeat;
    BYTE        bFlags
} DMUS_IO_CHORD;

멤버

wszName
코드의 이름.
mtTime
코드의 타임.
wMeasure
코드가 소속하는 소절.
bBeat
코드가 소속하는 박.
bFlags
플래그. 다음의 값이 정의되고 있다.
DMUS_CHORDKEYF_SILENT
코드는 무음이다. DMUS_CHORD_KEY 의 「주의」를 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_CHORDENTRY

코드 엔트리에 관한 정보를 보관 유지한다. 코드 맵 형식에서 사용된다.

typedef struct _DMUS_IO_CHORDENTRY {
    DWORD   dwFlags;
    WORD    wConnectionID;
} DMUS_IO_CHORDENTRY;

멤버

dwFlags
코드가 코드 그래프내의 시작 코드 (비트 2 가 세트)일까 엔딩 코드 (비트 3 이 세트)인지를 나타내는 플래그.
wConnectionID
실행시 포인터를 this 에 옮겨놓는다. 각 코드 엔트리에는, 일의의 접속 식별자가 태그 붙이고 된다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_CHORDMAP

코드 맵에 관한 정보를 보관 유지한다. 코드 맵 형식에서 사용된다.

typedef struct _DMUS_IO_CHORDMAP {
    WCHAR   wszLoadName[20];
    DWORD   dwScalePattern;
    DWORD   dwFlags;
} DMUS_IO_CHORDMAP;

멤버

wszLoadName
코드 맵의 이름. 코드 맵을 로드할 때, 오브젝트 기술 중(안)에서 사용된다.
dwScalePattern
코드 맵에 관련지을 수 있었던 스케일. 하위 24 비트는 각각 1 개의 반음을 나타내, 최하정도 비트는 루트음이다. 비트가 세트 되고 있는 경우, 거기에 대응하는 노트는 스케일내에 존재한다.
dwFlags
플래그. 0 또는 다음의 값을 사용할 수 있다.
DMUS_CHORDMAPF_VERSION8
DirectX 8.0 이후를 위해서(때문에) 코드 맵이 생성 되었다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_CHORDMAP_SIGNPOST

코드 맵내의 싸인 포스트코드에 관한 정보를 보관 유지한다. 코드 맵 형식에서 사용된다.

typedef struct _DMUS_IO_CHORDMAP_SIGNPOST {
    DWORD   dwChords;
    DWORD   dwFlags;
} DMUS_IO_CHORDMAP_SIGNPOST;

멤버

dwChords
이 코드가 지원 하는 싸인 포스트의 타입. 템플릿내의 값과 같은 값인지를 조합하기 위해서, 이러한 값이 사용된다. 템플릿을 사용하는 어레인지는, 특히, 템플릿내에서 이러한 값을 찾아, 이러한 값과 일치하는 코드 맵내의 실제의 코드를 찾아내는 작업으로부터 완성된다. 다음의 플래그가 정의되고 있다.
DMUS_SIGNPOSTF_A
DMUS_SIGNPOSTF_B
DMUS_SIGNPOSTF_C
DMUS_SIGNPOSTF_D
DMUS_SIGNPOSTF_E
DMUS_SIGNPOSTF_F
DMUS_SIGNPOSTF_LETTER
DMUS_SIGNPOSTF_1
DMUS_SIGNPOSTF_2
DMUS_SIGNPOSTF_3
DMUS_SIGNPOSTF_4
DMUS_SIGNPOSTF_5
DMUS_SIGNPOSTF_6
DMUS_SIGNPOSTF_7
DMUS_SIGNPOSTF_ROOT
DMUS_SIGNPOSTF_CADENCE
dwFlags
이 코드를 카덴트코드의 전에 둘지 어떨지를 정의하는 플래그. 싸인 포스트코드는 최고 2 개의 카덴트코드를 가질 수가 있다. 그 경우의 값은, SPOST_CADENCE1 (최초의 카덴트), SPOST_CADENCE2 (2 번째의 카덴트), 또는 이것들 2 개의 플래그를 조합한 것을 설정할 수 있다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_SIGNPOST


DMUS_IO_CHORDMAP_SUBCHORD

서브 코드에 관한 정보를 보관 유지한다. 코드 맵 형식에서 사용된다.

typedef struct _DMUS_IO_CHORDMAP_SUBCHORD {
    DWORD   dwChordPattern;
    DWORD   dwScalePattern;
    DWORD   dwInvertPattern;
    BYTE    bChordRoot;
    BYTE    bScaleRoot;
    WORD    wCFlags;
    DWORD   dwLevels;
} DMUS_IO_CHORDMAP_SUBCHORD;

멤버

dwChordPattern
서브 코드내의 노트. 하위 24 비트는 각각 1 개의 반음을 나타내, 최하정도 비트는 루트음이다. 비트가 세트 되고 있는 경우, 거기에 대응하는 노트는 코드내에 존재한다.
dwScalePattern
스케일내의 노트. 하위 24 비트는 각각 1 개의 반음을 나타내, 최하정도 비트는 루트음이다. 비트가 세트 되고 있는 경우, 거기에 대응하는 노트는 스케일내에 존재한다.
dwInvertPattern
스케일내에서 회전을 발생할 수 있는 포인트. 비트가 오프가 되어 있는 경우, 거기에 대응하는 음정에서는 노트를 회전 할 수 없다. 예를 들어, 패턴 100001111111 은, 햇빛 음계 (메이저 스케일)의 5 번과 7 번을 제외해, 어디에서라도 회전이 인정되는 것을 의미한다.
bChordRoot
서브 코드의 루트음. 0 은 범위내의 최저음의 C, 23 은 최고음의 B 이다.
bScaleRoot
스케일의 루트음. 0 은 범위내의 최저음의 C, 23 은 최고음의 B 이다.
wCFlags
장래의 사용에 대비해 예약되고 있다.
dwLevels
이 서브 코드가 지원 하는 레벨을 나타내는 비트 필드. 스타일내의 각 파트에는 레벨을 할당할 수 있어 레벨이 이 멤버에 포함되는 파트에만 도착해 이 코드가 사용된다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_SUBCHORD


DMUS_IO_COMMAND

커멘드 이벤트에 관한 정보를 보관 유지한다. 코만드트락크체크로 사용된다.

typedef struct _DMUS_IO_COMMAND {
    MUSIC_TIME  mtTime;
    WORD        wMeasure;
    BYTE        bBeat;
    BYTE        bCommand;
    BYTE        bGrooveLevel;
    BYTE        bGrooveRange;
    BYTE        bRepeatMode;
} DMUS_IO_COMMAND;

멤버

mtTime
커멘드의 타임.
wMeasure
커멘드가 소속하는 소절.
bBeat
커멘드가 소속하는 박.
bCommand
커멘드의 타입. 「DMUS_COMMANDT_TYPES 」를 참조할것.
bGrooveLevel
홈 레벨 . 커멘드가 홈 커멘드가 아닌 경우는 0 을 지정한다.
bGrooveRange
홈 레벨을 랜덤으로 변경 가능한 범위의 사이즈. 이 값이 홀수라면, 홈 범위는 bGrooveRange 로부터 1 을 뺀 값이다. 예를 들어, 홈 레벨이 35,bGrooveRange 가 5 인 경우, 조정 후의 홈 범위는 4 이며, 홈 레벨은 33 ~ 37 의 어느 쪽인가에 된다.
bRepeatMode
반복의 패턴을 선택하는 방법을 지정하는 플래그. 「DMUS_PATTERNT_TYPES 」를 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_CONTAINED_OBJECT_HEADER

컨테이너 형식에서, 각 오브젝트의 전에 사용된다.

typedef struct _DMUS_IO_CONTAINED_OBJECT_HEADER {
    GUID        guidClassID;
    DWORD       dwFlags;
    FOURCC      ckid;
    FOURCC      fccType;
} DMUS_IO_CONTAINED_OBJECT_HEADER;

멤버

guidClassID
오브젝트의 클래스 식별자.
dwFlags
0 또는 다음의 플래그를 지정한다.
DMUS_CONTAINED_OBJF_KEEP
컨테이너의 해방 후, 캐쉬된 오브젝트를 로더내 로 유지한다.
ckid
데이타체크의 식별자. 이 값이 0 의 경우, 체크의 타입은 LIST 라고 보여진다. 그 경우,fccType 는 유효해, 0 이외의 값이 아니면 안된다.
fccType
리스트 타입. 이 값이 0 의 경우,ckid 는 유효해, 0 이외의 값이 아니면 안된다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_CONTAINER_HEADER

컨테이너 형식에서 사용된다.

typedef struct _DMUS_IO_CONTAINER_HEADER {
    DWORD       dwFlags;
} DMUS_IO_CONTAINER_HEADER;

멤버

dwFlags
플래그를 지정하는 DWORD 값. 0 또는 다음의 값을 지정한다.
DMUS_CONTAINER_NOLOADS
컨테이너의 로드시에, 컨테이너내의 항목을 로드하지 않는다. 엔트리는 로더내에 생성 되지만, 명시적으로 로드 될 때까지 오브젝트를 생성 하지 않는다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_CURVE_ITEM

트럭내의 커브 이벤트에 관한 정보를 보관 유지한다. 시켄스트락크체크로 사용된다.

typedef struct _DMUS_IO_CURVE_ITEM {
    MUSIC_TIME  mtStart;
    MUSIC_TIME  mtDuration;
    MUSIC_TIME  mtResetDuration;
    DWORD       dwPChannel;
    short       nOffset;
    short       nStartValue;
    short       nEndValue;
    short       nResetValue;
    BYTE        bType;
    BYTE        bCurveShape;
    BYTE        bCCData;
    BYTE        bFlags;
    WORD        wParamType;
    WORD        wMergeIndex
} DMUS_IO_CURVE_ITEM;

멤버

mtStart
커브의 시작 타임.
mtDuration
커브의 지속 시간.
mtResetDuration
리셋 할 수 있는 동안의 커브 종료후의 시간.
dwPChannel
이벤트의 퍼포먼스 채널.
nOffset
커브가 발생하는구라두 경계로부터의 오프셋(offset). 뮤직 타임에 나타내진다. MIDI 커브는 로드시에 가장 가까운 구라두에 관련지을 수 있기 (위해)때문에, 이 값은 정에서도 부 이라도 좋다.
nStartValue
시작값.
nEndValue
종료값.
nResetValue
mtResetDuration 에 의해 설정되는 시간내에 플래시 (해방) 또는 무효화를 설정하는 리셋값.
bType
커브의 타입. 다음의 타입이 정의되고 있다.
DMUS_CURVET_CCCURVE
콘티뉴어스 콘트롤러 커브 (MIDI Control Change 채널 음성 메세지. 스테이터스 바이트는 &HBn. n 는 채널 번호를 나타낸다).
DMUS_CURVET_MATCURVE
단청의 애프터 터치 커브 (MIDI Channel Pressure 채널 음성 메세지. 스테이터스 바이트는 &HDn).
DMUS_CURVET_PATCURVE
다선율 애프터 터치 커브 (MIDI Poly Key Pressure 채널 음성 메세지. 스테이터스 바이트는 &HDn).
DMUS_CURVET_PBCURVE
핏치벤드카브 (MIDI Pitch Bend 채널 음성 메세지. 스테이터스 바이트는 &HEn).
DMUS_CURVET_NRPNCURVE
NRPN 커브.
DMUS_CURVET_RPNCURVE
RPN 커브.
bCurveShape
커브의 형상. 다음의 형상이 정의되고 있다.
DMUS_CURVES_EXP
지수 커브 형상.
DMUS_CURVES_INSTANT
즉시 커브 형상 (커브의 시작과 종료가 거의 동시에 발생한다).
DMUS_CURVES_LINEAR
선상 커브 형상.
DMUS_CURVES_LOG
대수 커브 형상.
DMUS_CURVES_SINE
정현 커브 형상.
bCCData
컨트롤 체인지 타입의 경우는, CC 번호를 지정한다.
bFlags
트란지션이 원인으로 무효화가 발생했을 때에 nResetValue 를 설정해야 하는 경우는, DMUS_CURVE_RESET 를 설정한다. 이 값을 0 으로 설정했을 경우, 커브는 새로운 값에 영속적에 머무른다. 다른 모든 비트는 예약되고 있다.
wParamType
RPN 타입 및 NRPN 타입의 파라미터 번호.
wMergeIndex
머지 인덱스. 못드호이르, 리바브의 송신, 코러스의 송신, 핏치벤드, 볼륨, 및 에크스프렛션콘트로라용으로 지원 된다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_SEQ_ITEM ,커브


DMUS_IO_INSTRUMENT

음색에 관한 정보를 보관 유지한다. 밴드 형식에서 사용된다.

typedef struct _DMUS_IO_INSTRUMENT {
    DWORD  dwPatch;
    DWORD  dwAssignPatch;
    DWORD  dwNoteRanges[4];
    DWORD  dwPChannel;
    DWORD  dwFlags;
    BYTE   bPan;
    BYTE   bVolume;
    short  nTranspose;
    DWORD  dwChannelPriority;
    short  nPitchBendRange;
} DMUS_IO_INSTRUMENT;

멤버

dwPatch
음색을 정의하기 위한 MSB, LSB, 및 프로그램 체인지.
dwAssignPatch
음색의 다운로드시에 할당하는 MSB, LSB, 및 프로그램 체인지.
dwNoteRanges
128 비트. 음색을 연주할 수 없으면 안 되는 각 MIDI 노트에 대해 1 개 지정한다.
dwPChannel
음색이 연주되는 퍼포먼스 채널.
dwFlags
컨트롤 플래그. 다음의 값이 정의되고 있다.
DMUS_IO_INST_ASSIGN_PATCH
dwAssignPatch 멤버는 유효하다.
DMUS_IO_INST_BANKSELECT
dwPatch 멤버에는, MSB 와 LSB 의 유효한 뱅크 셀렉트가 포함된다.
DMUS_IO_INST_CHANNEL_PRIORITY
dwChannelPriority 멤버는 유효하다.
DMUS_IO_INST_GM
음색은 General MIDI 콜렉션의 것이다.
DMUS_IO_INST_GS
음색은 Roland GS 콜렉션의 것이다.
DMUS_IO_INST_NOTERANGES
dwNoteRanges 멤버는 유효하다.
DMUS_IO_INST_PAN
bPan 멤버는 유효하다.
DMUS_IO_INST_PATCH
dwPatch 멤버는 유효하다.
DMUS_IO_INST_PITCHBENDRANGE
nPitchBendRange 멤버는 유효하다.
DMUS_IO_INST_TRANSPOSE
nTranspose 멤버는 유효하다.
DMUS_IO_INST_USE_DEFAULT_GM_SET
디폴트의 General MIDI 음색 세트는, 포토가 하드웨어내에 GM 를 가지고 있는 경우에서도, 포토에 다운로드해야 한다. XG 또는 GS 가 리셋 된 MIDI 파일을 해석하는 경우, GUID_StandardMIDIFile 가 밴드에 대해서 요구되었는지 어떠했는지에 관계없이, 뱅크 셀렉트 메세지가 송신된다. 즉, GUID_StandardMIDIFile 는 순수하게 GM 파일만의 것이다.
DMUS_IO_INST_VOLUME
bVolume 멤버는 유효하다.
DMUS_IO_INST_XG
음색은 Yamaha XG 콜렉션의 것이다.
bPan
음색의 빵.
bVolume
음색의 볼륨.
nTranspose
노트를 전치 하는 반음의 수.
dwChannelPriority
채널의 우선 순위. 정의 끝난 값의 리스트에 대해서는, 「IDirectMusicPort8::GetChannelPriority 」를 참조할것.
nPitchBendRange
핏치벤드에 의해 쉬프트 된 반음의 수.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_LYRICSTRACK_EVENTHEADER

가사 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_LYRICSTRACK_EVENTHEADER {
    DWORD dwFlags;
    DWORD dwTimingFlags;
    MUSIC_TIME lTimeLogical;
    MUSIC_TIME lTimePhysical;
} DMUS_IO_LYRICSTRACK_EVENTHEADER;

멤버

dwFlags
예약이 끝난 상태. 0 으로 설정한다.
dwTimingFlags
통지의 타이밍을 결정하는 플래그. 다음의 1 개 이상의DMUS_PMSGF_FLAGS 열거형의 멤버를 지정할 수 있다.
DMUS_PMSGF_TOOL_IMMEDIATE
타임 스탬프 에 관계없이, 메세지를 즉석에서 처리해야 한다.
DMUS_PMSGF_TOOL_QUEUE
포토의 지연 시간을 고려해, 타임 스탬프의 직전에 메세지를 처리해야 한다.
DMUS_PMSGF_TOOL_ATTIME
타임 스탬프의 시점에서 메세지를 처리해야 한다.
lTimeLogical
이벤트를 관련지을 수 있고 있는 뮤직 타임.
lTimePhysical
이벤트가 방아쇠 되는 정확한 타임. 논리 타임과 대충 같다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

논리적인 타임과 실제의 타임


DMUS_IO_MELFORM

DirectX 8.0 에서는 이행 되지 않는다.

멜로디 편성 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_MELFORM {
    DWORD  dwPlaymode;
} DMUS_IO_MELFORM;

멤버

dwPlaymode
예약이 끝난 상태. 0 이 아니면 안된다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_MOTIFSETTINGS

모티프에 관한 정보를 보관 유지한다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_MOTIFSETTINGS {
    DWORD       dwRepeats;
    MUSIC_TIME  mtPlayStart;
    MUSIC_TIME  mtLoopStart;
    MUSIC_TIME  mtLoopEnd;
    DWORD       dwResolution;
} DMUS_IO_MOTIFSETTINGS;

멤버

dwRepeats
반복 회수.
mtPlayStart
재생의 시작 포인트. 보통은 0 으로 설정한다.
mtLoopStart
루프 부분의 시작 포인트. 보통은 0 으로 설정한다.
mtLoopEnd
루프 부분의 종료 포인트. mtLoopStart 보다 큰 값이 아니면 안된다. 모티프 전체를 루프 하는 경우는 0.
dwResolution
디폴트의 분해가능. 「DMUS_TIME_RESOLVE_FLAGS 」를 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.

참조

IDirectMusicSegment8::SetLoopPoints


DMUS_IO_MUTE

채널 위에의 뮤트 이벤트에 관한 정보를 보관 유지한다. 뮤트트락크체크로 사용된다.

typedef struct _DMUS_IO_MUTE {
    MUSIC_TIME  mtTime;
    DWORD       dwPChannel;
    DWORD       dwPChannelMap;
} DMUS_IO_MUTE;

멤버

mtTime
이벤트의 타임.
dwPChannel
뮤트 또는 재맵 하는 퍼포먼스 채널.
dwPChannelMap
dwPChannel 가 맵 되고 있는 채널. dwPChannel 를 뮤트 하는 경우는 0xFFFFFFFF 로 설정한다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_MUTE_PARAM


DMUS_IO_NEXTCHORD

코드 그래프내의 다음의 코드에 관한 정보를 보관 유지한다. 코드 맵 형식에서 사용된다.

typedef struct _DMUS_IO_NEXTCHORD {
    DWORD   dwFlags;
    WORD    nWeight;
    WORD    wMinBeats;
    WORD    wMaxBeats;
    WORD    wConnectionID;
} DMUS_IO_NEXTCHORD;

멤버

dwFlags
장래의 사용에 대비해 예약되고 있다.
nWeight
코드 그래프를 암벽 횡단 할 경우에 이 링크가 사용될 가능성 (1 ~ 100 의 범위).
wMinBeats
어레인지 된 세그먼트(segment)내에서 이 코드를 연주할 수 있는 박의 최소수.
wMaxBeats
어레인지 된 세그먼트(segment)내에서 이 코드를 연주할 수 있는 박의 최대수.
wConnectionID
DMUS_IO_CHORDENTRY 구조체의 wConnectionID 멤버를 참조한다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_PARAMCONTROLTRACK_CURVEINFO

파라미터 제어 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_PARAMCONTROLTRACK_CURVEINFO {
    MUSIC_TIME  mtStartTime;
    MUSIC_TIME  mtEndTime;
    float       fltStartValue;
    float       fltEndValue;
    DWORD       dwCurveType;
    DWORD       dwFlags;
} DMUS_IO_PARAMCONTROLTRACK_CURVEINFO;

멤버

mtStartTime
커브의 시작 타임.
mtEndTime
커브의 종료 타임.
fltStartValue
커브의 시작값.
fltEndValue
커브의 종료값.
dwCurveType
MP_CURVE_TYPE 열거의 항목. DirectShow 문서의 「MP_CURVE_TYPE」를 참조할것.
dwFlags
정수 MPF_ENVLP_* 의 편성. DirectShow 문서의 「Envelope Flags」를 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER

파라미터 제어 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER {
    DWORD dwFlags;
    GUID guidTimeFormat;
    DWORD dwPChannel;
    DWORD dwStage;
    DWORD dwBuffer;
    GUID guidObject;
    DWORD dwIndex;
} DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER;

멤버

dwFlags
예약이 끝난 상태. 0 으로 설정한다.
guidTimeFormat
오브젝트로 설정되는 타임 형식. Medparam.h 에 정의되고 있는, GUID_TIME_REFERENCE 또는 GUID_TIME_MUSIC 가 아니면 안된다.
dwPChannel
퍼포먼스 채널, 0, 또는 DMUS_PCHANNEL_ALL.
dwStage
패스의 스테이지.
dwBuffer
버퍼가 다수 있는 경우, 버퍼의 인덱스.
guidObject
GUID_DSFX_STANDARD_CHORUS 등의, 오브젝트의 클래스 식별자.
dwIndex
적합 오브젝트의 리스트내의 오브젝트의 인덱스.

주의

각 멤버로 설정 가능한 값의 상세한 것에 대하여는, 「IDirectMusicSegmentState8::GetObjectInPath 」를 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER

파라미터 제어 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER {
    DWORD dwFlags;
    DWORD dwIndex;
} DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER;

멤버

dwFlags
예약이 끝난 상태. 0 으로 설정한다.
dwIndex
오브젝트 위에의 파라미터의 인덱스 번호.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_PARTREF

파트 참조에 관한 정보를 보관 유지한다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_PARTREF {
    GUID  guidPartID;
    WORD  wLogicalPartID;
    BYTE  bVariationLockID;
    BYTE  bSubChordLevel;
    BYTE  bPriority;
    BYTE  bRandomVariation;
    WORD  wPad;
    DWORD dwPChannel;
} DMUS_IO_PARTREF;

멤버

guidPartID
파트의 식별자.
wLogicalPartID
포토 위에의 특정의 MIDI 채널에 대응하고 있는 식별자. 이 멤버는,dwPChannel 에 인계되어 향후는 사용되지 않는다.
bVariationLockID
락 식별자의 바리에이션. 이 멤버내의 값과 같은 값을 가지는 파트는, 항상 같은 바리에이션을 연주한다. 값 0 은, 파트가 바리에이션을 그 외의 파트와는 따로 연주하는 것을 의미한다.
bSubChordLevel
이 파트가 필요로 하는 서브 코드 레벨. 「주의」를 참조할것.
bPriority
장래의 사용에 대비해 예약되고 있다.
bRandomVariation
일치하는 바리에이션을 순서에 연주하는 경우는 0. 또는,DMUS_VARIATIONT_TYPES 열거형의 멤버의 언젠가.
wPad
alignment를 위한 패딩. 값은 사용되지 않는다.
dwPChannel
파트의 퍼포먼스 채널.

주의

bSubChordLevel 멤버는, 0 으로부터 시작되는 인덱스값을 가진다. 실행시에는, 이 값에 의해 1 이 왼쪽 쉬프트 되어DMUS_SUBCHORD 구조체의 dwLevels 멤버와 비교하기 위한 1 비트값이 생성된다. 따라서,bSubChordLevel 가 0 의 파트는,dwLevels 에 1 을 포함하고 있던 임의의 서브 코드에 맵 된다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_PATTERN

패턴에 관한 정보를 보관 유지한다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_PATTERN {
    DMUS_IO_TIMESIG  timeSig;
    BYTE             bGrooveBottom;
    BYTE             bGrooveTop;
    WORD             wEmbellishment;
    WORD             wNbrMeasures;
    BYTE             bDestGrooveBottom;
    BYTE             bDestGrooveTop;
    DWORD            dwFlags;
} DMUS_IO_PATTERN;

멤버

timeSig
스타일의 디폴트의 박자 기호를 오버라이드(override) 하는 박자 기호를 보관 유지하는 DMUS_IO_TIMESIG 구조체.
bGrooveBottom
홈 범위의 최저음.
bGrooveTop
홈 범위의 최고음.
wEmbellishment
장식의 타입. DMUS_COMMANDT_TYPES 열거형의 정수의 1 개, 또는 컨텐츠 프로바이더가 정의하는 값.
wNbrMeasures
소절내의 패턴의 길이.
bDestGrooveBottom
다음의 패턴의 홈 범위의 최저음.
bDestGrooveTop
다음의 패턴의 홈 범위의 최고음.
dwFlags
플래그. 0 또는 다음의 값을 사용할 수 있다.
DMUS_PATTERNF_PERSIST_CONTROL
패턴 베이스 트럭 상태 데이터의 바리에이션 설정은, 연주 종료후도 트럭내에서 계속된다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_PCHANNELTOBUFFER_HEADER

퍼포먼스 채널의 범위와 접속처의 버퍼를 정의한다. 오디오 패스 형식의 포토 구성 리스트로 사용된다.

typedef struct _DMUS_IO_PCHANNELTOBUFFER_HEADER {
    DWORD  dwPChannelBase;
    DWORD  dwPChannelCount;
    DWORD  dwBufferCount;
    DWORD  dwFlags;
} DMUS_IO_PCHANNELTOBUFFER_HEADER;

멤버

dwPChannelBase
최초의 퍼포먼스 채널.
dwPChannelCount
퍼포먼스 채널의 수.
dwBufferCount
채널이 접속하는 버퍼의 수.
dwFlags
예약이 끝난 상태. 0 이 아니면 안된다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_PLAYMARKER

연주 마커에 관한 정보를 보관 유지한다. 연주 마커는, 새로운 세그먼트(segment)가 연주 시작이 허가된 프라이머리 세그먼트(segment)내의 포인트이다. 마커 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_PLAY_MARKER {
    MUSIC_TIME mtTime;
} DMUS_IO_PLAY_MARKER;

멤버

mtTime
유효한 연주 포인트의 타임.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_PORTCONFIG_HEADER

오디오 패스 형식에서 사용된다.

typedef struct _DMUS_IO_PORTCONFIG_HEADER {
    GUID    guidPort;
    DWORD   dwPChannelBase;
    DWORD   dwPChannelCount;
    DWORD   dwFlags;
} DMUS_IO_PORTCONFIG_HEADER;

멤버

guidPort
포토의 일의인 식별자.
dwPChannelBase
최초의 퍼포먼스 채널.
dwPChannelCount
퍼포먼스 채널의 수.
dwFlags
구성 플래그. 다음의 값이 정의되고 있다.
DMUS_PORTCONFIGF_DRUMSON10
드럼은 채널 10 이다.
DMUS_PORTCONFIGF_USEDEFAULT
디폴트의 포토를 사용한다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_REFERENCE

다른 파일에 보존되고 있는 다른 오브젝트에의 참조에 관한 정보를 보관 유지한다. 참조 리스트 체크로 사용된다.

typedef struct _DMUS_IO_REFERENCE {
    GUID    guidClassID;
    DWORD   dwValidData;
} DMUS_IO_REFERENCE;

멤버

guidClassID
클래스 식별자.
dwValidData
참조의 어느 데이타체크가 존재하는지를 나타내는 플래그. 값의 리스트에 대해서는, 대응하는 DMUS_OBJECTDESC 의 멤버를 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_SCRIPT_HEADER

스크립트 형식에서 사용된다.

typedef struct _DMUS_IO_SCRIPT_HEADER {
    DWORD  dwFlags;
} DMUS_IO_SCRIPT_HEADER;

멤버

dwFlags
스크립트의 로드 동작을 지정하는 DWORD 값. 다음의 1 개 이상의 값을 지정할 수 있다.
DMUS_SCRIPTIOF_LOAD_ALL_CONTENT
스크립트의 컨테이너내의 모든 컨텐츠를 로드한다.
DMUS_SCRIPTIOF_DOWNLOAD_ALL_SEGMENTS
DMUS_SCRIPTIOF_LOAD_ALL_CONTENT 가 설정되어 있는 경우, 스크립트의 컨테이너에 포함되는 모든 세그먼트(segment)의 밴드가, 스크립트의 초기화시에 다운로드된다. 그 이외의 경우, 세그먼트(segment)의 밴드는, 스크립트가 세그먼트(segment)를 로드할 때 다운로드된다.

DMUS_SCRIPTIOF_DOWNLOAD_ALL_SEGMENTS 가 설정되어 있지 않은 경우, 스크립트는 세그먼트(segment)의 밴드의 다운로드와 언로드를 수동으로 실시하지 않으면 안 된다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_SCRIPTTRACK_EVENTHEADER

스크립트 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_SCRIPTTRACK_EVENTHEADER {
    DWORD dwFlags;
    MUSIC_TIME lTimeLogical;
    MUSIC_TIME lTimePhysical;
} DMUS_IO_SCRIPTTRACK_EVENTHEADER;

멤버

dwFlags
이벤트를 언제 설정할까를 결정하는 플래그. 다음의 몇개의 값을 지정한다.
DMUS_IO_SCRIPTTRACKF_PREPARE
타임 스탬프보다 전의, 준비 시간에 이벤트를 기동한다. 목적의 시간으로 음악을 변경하기 위해서 충분한 시간이 스크립트에 남겨지므로, 이것이 디폴트이다.
DMUS_IO_SCRIPTTRACKF_QUEUE
타임 스탬프 직전의, 큐 시간에 이벤트를 기동한다.
DMUS_IO_SCRIPTTRACKF_ATTIME
타임 스탬프 정확히에 이벤트를 기동한다.
lTimeLogical
이벤트의 논리 타임.
lTimePhysical
이벤트의 실제의 타임.

동작환경

헤더 : dmusicf.h 로 선언.

참조

논리적인 타임과 실제의 타임


DMUS_IO_SEGMENT_HEADER

세그먼트(segment)에 관한 정보를 보관 유지한다. 세그먼트(segment) 형식에서 사용된다.

typedef struct _DMUS_IO_SEGMENT_HEADER {
    DWORD          dwRepeats;
    MUSIC_TIME     mtLength;
    MUSIC_TIME     mtPlayStart;
    MUSIC_TIME     mtLoopStart;
    MUSIC_TIME     mtLoopEnd;
    DWORD          dwResolution;
    REFERENCE_TIME rtLength;
    DWORD          dwFlags;
    DWORD          dwReserved;
} DMUS_IO_SEGMENT_HEADER;

멤버

dwRepeats
반복 회수.
mtLength
세그먼트(segment)의 길이.
mtPlayStart
재생의 시작 포인트. 보통은 0 으로 설정한다.
mtLoopStart
루프 부분의 시작 포인트. 보통은 0 으로 설정한다.
mtLoopEnd
루프 부분의 종료 포인트. mtPlayStart 보다 큰 값이 아니면 안된다. 세그먼트(segment) 전체를 루프 하는 경우는 0.
dwResolution
디폴트의 분해가능. 「DMUS_TIME_RESOLVE_FLAGS 」를 참조할것.
rtLength
기준 타임내의 세그먼트(segment)의 길이. DMUS_SEGIOF_REFLENGTH 플래그가 설정되어 있는 경우에 유효하다.
dwFlags
0 또는 다음의 플래그를 지정한다.
DMUS_SEGIOF_REFLENGTH
rtLength 의 값이 mtLength 를 오버라이드(override) 한다.
dwReserved
예약이 끝난 상태.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_MOTIFSETTINGS ,IDirectMusicSegment8::SetLoopPoints


DMUS_IO_SEGMENT_ITEM_HEADER

세그먼트(segment) 방아쇠 트럭 리스트로 참조되는 세그먼트(segment)에 관한 정보를 보관 유지한다.

typedef struct _DMUS_IO_SEGMENT_ITEM_HEADER{
    MUSIC_TIME      lTimeLogical;
    MUSIC_TIME      lTimePhysical;
    DWORD           dwPlayFlags;
    DWORD           dwFlags;
} DMUS_IO_SEGMENT_ITEM_HEADER;

멤버

lTimeLogical
이벤트를 관련지을 수 있고 있는 뮤직 타임.
lTimePhysical
세그먼트(segment)를 연주하는 실제의 타임.
dwPlayFlags
IDirectMusicPerformance8::PlaySegmentEx 에게 건네지는 플래그. 「DMUS_SEGF_FLAGS 」를 참조할것.
dwFlags
0 또는 다음의 값을 지정한다.
DMUS_SEGMENTTRACKF_MOTIF
DMRF 체크는 스타일에의 링크이며, 'snam'체크는 스타일내의 모티프의 이름이다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_SEGMENT_TRACK_HEADER

세그먼트(segment) 방아쇠 트럭 리스트에 관한 정보를 보관 유지한다.

typedef struct _DMUS_IO_SEGMENT_TRACK_HEADER {
    DWORD dwFlags;
} DMUS_IO_SEGMENT_TRACK_HEADER;

멤버

dwFlags
예약이 끝난 상태. 0 으로 설정한다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_SEGREF_HEADER

DirectX 8.0 에서는 이행 되지 않는다.

노래 형식에서의 세그먼트(segment) 참조에 관한 정보를 보관 유지한다.

typedef struct _DMUS_IO_SEGREF_HEADER {
    DWORD       dwID;
    DWORD       dwSegmentID;
    DWORD       dwToolGraphID;
    DWORD       dwFlags;
    DWORD       dwNextPlayID;
} DMUS_IO_SEGREF_HEADER;

멤버

dwID
세그먼트(segment)의 일의인 식별자. DMUS_SONG_MAXSEGID 이하가 아니면 안된다.
dwSegmentID
링크처의 옵션의 소스 세그먼트(segment)의 식별자.
dwToolGraphID
처리에 사용하는 옵션의 툴 그래프의 식별자.
dwFlags
예약이 끝난 상태. 0 으로 설정한다.
dwNextPlayID
노래 체인의 다음의 세그먼트(segment)의 식별자.


DMUS_IO_SEQ_ITEM

순서 트럭내의 데이터 항목에 관한 정보를 보관 유지한다. 시켄스트락크체크로 사용된다.

typedef struct _DMUS_IO_SEQ_ITEM {
    MUSIC_TIME  mtTime;
    MUSIC_TIME  mtDuration;
    DWORD       dwPChannel;
    short       nOffset
    BYTE        bStatus;
    BYTE        bByte1;
    BYTE        bByte2;
} DMUS_IO_SEQ_ITEM;

멤버

mtTime
이벤트의 논리 타임.
mtDuration
이벤트가 유효한 지속 시간.
dwPChannel
이벤트의 퍼포먼스 채널.
nOffset
노트가 연주되는 mtTime 로부터의 오프셋(offset). 뮤직 타임에 나타내진다.
bStatus
MIDI 이벤트 타입. MIDI 스테이터스 바이트와 같지만, 채널 정보가 없다.
bByte1
MIDI 데이터의 최초의 1 바이트.
bByte2
MIDI 데이터의 2 바이트째.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_CURVE_ITEM ,MIDI 메세지


DMUS_IO_SIGNPOST

코드 맵내의 싸인 포스트코드에 관련지을 수 있던, 싸인 포스트트럭내의 싸인 포스트에 관한 정보를 보관 유지한다. 사인포스트트락크체크로 사용된다.

typedef struct _DMUS_IO_SIGNPOST {
    MUSIC_TIME  mtTime;
    DWORD       dwChords;
    WORD        wMeasure;
} DMUS_IO_SIGNPOST;

멤버

mtTime
싸인 포스트의 타임.
dwChords
이 싸인 포스트에 관련지을 수 있는 싸인 포스트코드의 타입. 템플릿내의 값과 같은 값인지를 조합하기 위해서, 이러한 값이 사용된다. 템플릿을 사용하는 어레인지는, 특히, 템플릿내에서 이러한 값을 찾아, 이러한 값과 일치하는 코드 맵내의 실제의 코드를 찾아내는 작업으로부터 완성된다. 다음의 플래그가 정의되고 있다.
DMUS_SIGNPOSTF_A
DMUS_SIGNPOSTF_B
DMUS_SIGNPOSTF_C
DMUS_SIGNPOSTF_D
DMUS_SIGNPOSTF_E
DMUS_SIGNPOSTF_F
DMUS_SIGNPOSTF_LETTER
DMUS_SIGNPOSTF_1
DMUS_SIGNPOSTF_2
DMUS_SIGNPOSTF_3
DMUS_SIGNPOSTF_4
DMUS_SIGNPOSTF_5
DMUS_SIGNPOSTF_6
DMUS_SIGNPOSTF_7
DMUS_SIGNPOSTF_ROOT
DMUS_SIGNPOSTF_CADENCE

wMeasure
싸인 포스트가 소속하는 소절.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_CHORDMAP_SIGNPOST


DMUS_IO_SONG_HEADER

DirectX 8.0 에서는 이행 되지 않는다.

노래 형식에 관한 정보를 보관 유지한다.

typedef struct _DMUS_IO_SONG_HEADER {
    DWORD  dwFlags;
    DWORD  dwStartSegID;
} DMUS_IO_SONG_HEADER;

멤버

dwFlags
예약이 끝난 상태.
dwStartSegID
최초로 연주하는 세그먼트(segment)의 식별자.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_STYLE

스타일의 박자 기호와 템포에 관한 정보를 보관 유지한다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_STYLE {
    DMUS_IO_TIMESIG  timeSig;
    double           dblTempo;
} DMUS_IO_STYLE;

멤버

timeSig
스타일의 디폴트의 박자 기호를 보관 유지하는 DMUS_IO_TIMESIG 구조체.
dblTempo
스타일의 템포.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_STYLE_ANTICIPATION

해결 안티시페이션을 나타낸다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_STYLE_ANTICIPATION {
    MUSIC_TIME    mtGridStart;
    DWORD         dwVariation;
    short         nTimeOffset;
    BYTE          bTimeRange;
} DMUS_IO_STYLE_ANTICIPATION;

멤버

mtGridStart
이벤트가 연주되는 파트내의 오프셋(offset). 구라두로 나타내진다. 「주의」를 참조할것.
dwVariation
바리에이션. 설정된 각 비트가 유효한 바리에이션을 지정한다.
nTimeOffset
mtGridStart 로부터의 타임의 오프셋(offset).
bTimeRange
랜덤 시간의 범위. 「주의」를 참조할것.

주의

이벤트의 타임은 다음과 같이 계산할 수 있다. TimeSig 는, 박자 기호를 보관 유지하는 DMUS_IO_TIMESIG 구조체이다.

mtEventTime = nTimeOffset + ((mtGridStart / TimeSig.wGridsPerBeat) *
((DMUS_PPQ * 4) / TimeSig.bBeat) + (mtGridStart %
TimeSig.wGridsPerBeat) * (((DMUS_PPQ * 4)/ TimeSig.bBeat) /
TimeSig.wGridsPerBeat))

bTimeRange 의 값은, 「DMUS_IO_STYLENOTE 」의 「주의」에 나타나고 있는 공식으로 따라서, 이벤트의 발생시에 뮤직 타임에 변환된다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_STYLECURVE

스타일내의 커브에 관한 정보를 보관 유지한다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_STYLECURVE {
    MUSIC_TIME  mtGridStart;
    DWORD       dwVariation;
    MUSIC_TIME  mtDuration;
    MUSIC_TIME  mtResetDuration;
    short       nTimeOffset;
    short       nStartValue;
    short       nEndValue;
    short       nResetValue;
    BYTE        bEventType;
    BYTE        bCurveShape;
    BYTE        bCCData;
    BYTE        bFlags;
    WORD        wParamType;
    WORD        wMergeIndex;
} DMUS_IO_STYLECURVE;

멤버

mtGridStart
커브가 발생하는 시점의 오프셋(offset). 구라두로 나타내진다.
dwVariation
이 커브가 소속하는 바리에이션. 각 비트는 32 있는 바리에이션의 어느 쪽인가에 대응한다.
mtDuration
커브의 지속 시간.
mtResetDuration
리셋 할 수 있는 동안의 커브 종료후의 시간.
nTimeOffset
커브가 발생하는 mtGridStart 로부터의 오프셋(offset). 「DMUS_IO_STYLE_ANTICIPATION 」의 「주의」를 참조할것.
nStartValue
시작값.
nEndValue
종료값.
nResetValue
mtResetDuration 에 의해 지정되는 시간의 사이에 플래시 (해방) 또는 무효화를 설정하는 리셋값.
bEventType
커브의 타입. 「DMUS_IO_CURVE_ITEM 」를 참조할것.
bCurveShape
커브의 형상. 「DMUS_IO_CURVE_ITEM 」를 참조할것.
bCCData
컨트롤 체인지 타입의 경우는, CC 번호를 지정한다.
bFlags
트란지션이 원인으로 무효화가 발생했을 때에 nResetValue 를 설정해야 하는 경우는, DMUS_CURVE_RESET 를 설정한다. 이 값을 0 으로 설정했을 경우, 커브는 새로운 값에 영속적에 머무른다. 다른 모든 비트는 예약되고 있다.
wParamType
RPN 또는 NRPN 의 파라미터 번호.
wMergeIndex
머지 인덱스. 못드호이르, 리바브의 송신, 코러스의 송신, 핏치벤드, 볼륨, 및 에크스프렛션콘트로라용으로 지원 된다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_CURVE_PMSG ,DMUS_IO_CURVE_ITEM


DMUS_IO_STYLEMARKER

스타일내의 마커에 관한 정보를 보관 유지한다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_STYLEMARKER {
    MUSIC_TIME  mtGridStart;
    DWORD       dwVariation;
    WORD        wMarkerFlags;
} DMUS_IO_STYLEMARKER;

멤버

mtGridStart
마커가 발생하는 시점의 오프셋(offset). 구라두로 나타내진다.
dwVariation
이 마커가 소속하는 바리에이션. 각 비트는 32 있는 바리에이션의 어느 쪽인가에 대응한다.
wMarkerFlags
마커의 동작을 지정하는 플래그. 0 또는 다음의 1 개 이상의 값을 지정할 수 있다. 0 의 경우, 동작은 DirectX 버젼 7.0 과 같다.
DMUS_MARKERF_START
바리에이션을 시작 한다.
DMUS_MARKERF_STOP
바리에이션을 정지한다.
DMUS_MARKERF_CHORD_ALIGN
새로운 바리에이션은 코드에 가지런히 할 필요가 있다. DMUS_MARKERF_START 와 DMUS_MARKERF_STOP 가 지정되어 있지 않은 경우, 이 플래그는 무시된다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_STYLENOTE

스타일내의 노트에 관한 정보를 보관 유지한다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_STYLENOTE {
    MUSIC_TIME  mtGridStart;
    DWORD       dwVariation;
    MUSIC_TIME  mtDuration;
    short       nTimeOffset;
    WORD        wMusicValue;
    BYTE        bVelocity;
    BYTE        bTimeRange;
    BYTE        bDurRange;
    BYTE        bVelRange;
    BYTE        bInversionID;
    BYTE        bPlayModeFlags;
    BYTE        bNoteFlags;
} DMUS_IO_STYLENOTE;

멤버

mtGridStart
노트가 발생하는 시점의 오프셋(offset). 구라두로 나타내진다.
dwVariation
이 노트가 소속하는 바리에이션. 각 비트는 32 있는 바리에이션의 어느 쪽인가에 대응한다.
mtDuration
노트의 지속 시간.
nTimeOffset
이벤트가 발생하는 mtGridStart 후의 타임. 「DMUS_IO_STYLE_ANTICIPATION 」의 「주의」를 참조할것.
wMusicValue
스케일내의 위치.
bVelocity
노트의 velocity.
bTimeRange
시작 타임을 랜덤화하는 범위. 「주의」를 참조할것.
bDurRange
지속 시간을 랜덤화하는 범위. 「주의」를 참조할것.
bVelRange;
velocity를 랜덤화하는 범위.
bInversionID
이 노트가 소속하는 회전 그룹의 식별자.
bPlayModeFlags
파트의 연주 모드를 오버라이드(override) 하는 플래그. 값의 리스트에 대해서는, 「DMUS_PLAYMODE_FLAGS 」를 참조할것.
bNoteFlags
플래그. 「DMUS_NOTEF_FLAGS 」를 참조할것.

주의

bTimeRange 및 bDurRange 의 값은, 다음의 함수를 사용해, 노트가 연주될 때 뮤직 타임에 변환된다.

int StoredRangeToActualRange(BYTE bRange)
{
    int nResult = 0;
    if (0 <= bRange && bRange <= 190)
    {
        nResult = bRange;
    }
    else if (191 <= bRange && bRange <= 212)
    {
        nResult = ((bRange - 190) * 5) + 190;
    }
    else if (213 <= bRange && bRange <= 232)
    {
        nResult = ((bRange - 212) * 10) + 300;
    }
    else // bRange > 232
    {
        nResult = ((bRange - 232) * 50) + 500;
    }
    return nResult;
}

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_STYLEPART

파트에 관한 정보를 보관 유지한다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_STYLEPART {
    DMUS_IO_TIMESIG  timeSig;
    DWORD            dwVariationChoices[32];
    GUID             guidPartID;
    WORD             wNbrMeasures;
    BYTE             bPlayModeFlags;
    BYTE             bInvertUpper;
    BYTE             bInvertLower;
    BYTE             bPad[3];
    DWORD            dwFlags;
} DMUS_IO_STYLEPART;

멤버

timeSig
스타일의 디폴트의 박자 기호를 오버라이드(override) 하는 박자 기호를 보관 유지하는 DMUS_IO_TIMESIG 구조체.
dwVariationChoices
각 요소는, 32 있는 바리에이션의 어느 쪽인가에 대응한다. 각 요소로 설정되는 플래그는, 그 바리에이션으로 지원 되는 코드의 타입을 나타낸다 ( 「주의」를 참조). 또, 바리에이션이 DirectMusic 모드와 IMA 모드의 어디에서 있는지를 지정하기 위해서, 모드 마스크의 1 개를 설정해야 한다.

다음의 플래그가 정의되고 있다.

DMUS_VARIATIONF_MAJOR
메이저 코드의 스케일내의 7 개의 위치.
DMUS_VARIATIONF_MINOR
마이너 코드의 스케일내의 7 개의 위치.
DMUS_VARIATIONF_OTHER
그 외의 코드의 스케일내의 7 개의 위치.
DMUS_VARIATIONF_ROOT_SCALE
스케일내의 코드 루트음을 처리한다.
DMUS_VARIATIONF_ROOT_FLAT
플랫의 코드 루트음을 처리한다 (스케일내의 노트에 근거한다).
DMUS_VARIATIONF_ROOT_SHARP
샤프의 코드 루트음을 처리한다 (스케일내의 노트에 근거한다).
DMUS_VARIATIONF_TYPE_TRIAD
3 화음의 단체 코드를 처리한다.
DMUS_VARIATIONF_TYPE_6AND7
6 으로 7 의 단체 코드를 처리한다.
DMUS_VARIATIONF_TYPE_COMPLEX
복합 코드를 처리한다.
DMUS_VARIATIONF_DEST_TO1
1 의 코드에의 트란지션을 처리한다.
DMUS_VARIATIONF_DEST_TO5
5 의 코드에의 트란지션을 처리한다.
DMUS_VARIATIONF_MODES
모드 마스크. 사용하지 않는다.
DMUS_VARIATIONF_MODES_EX
모드 마스크.
DMUS_VARIATIONF_IMA25_MODE
모드 마스크. (dwVariationChoices & DMUS_VARIATIONF_MODES_EX) == DMUS_VARIATIONF_IMA25_MODE 인 경우, 바리에이션은 IMA (Interactive Music Architecture) 모드이다.
DMUS_VARIATIONF_DMUS_MODE
모드 마스크. dwVariationChoices 에 이 마스크가 포함되는 경우, 바리에이션은 DirectMusic 모드이다. DirectMusic Producer 로 오쏘링 된 모든 바리에이션은, 이 모드를 사용한다.
guidPartID
파트의 일의의 식별자.
wNbrMeasures
파트의 길이. 소절 단위로 나타낸다.
bPlayModeFlags
연주 모드를 정의하는 플래그. 값의 리스트에 대해서는, 「DMUS_PLAYMODE_FLAGS 」를 참조할것.
bInvertUpper
회전의 상한.
bInvertLower
회전의 하한.
bPad
미사용.
dwFlags
파트의 동작을 지정하는 플래그. 다음의 값을 지정할 수 있다.
DMUS_PARTF_USE_MARKERS
파트는 마커 이벤트를 사용한다.
DMUS_PARTF_ALIGN_CHORDS
파트는, 코드에 가지런히 할 수 있었던 마커상에서만 바꿀 수가 있다.

주의

dwVariationChoices 내의 플래그는, DirectMusic 모드로 지정한 바리에이션에 의해 지원 되는 코드의 타입을 결정한다. 최초의 7 개의 플래그 (비트 1 ~ 7)는, 바리에이션이 스케일 위치에 근거하는 메이저 코드를 지원 하는 경우로 설정한다. 예를 들어, 1, 2, 4 의 각 비트가 설정되었을 경우, 바리에이션은 으뜸음, 2 번, 4 번의 스케일 위치에 근거하는 메이저 코드를 지원 한다. 다음의 7 개의 플래그는 마이너 코드에 대해서와 같이 기능해, 그 다음의 7 개의 플래그는 메이저 및 마이너 이외의 코드에 대해서와 같이 기능한다 (SUS 4 코드 등). 22, 23, 24 의 각 비트는, 바리에이션이 각각 스케일에 근거하는 코드, 스케일의 음정의 샤프하게 기초를 두는 코드, 스케일의 음정의 플랫에 근거하는 코드를 지원 하는 경우로 설정한다. 예를 들어, C 메이저의 스케일로 C# 마이너 코드를 지원 하려면 , 비트 8 ( 동주마이너)으로 비트 24 (샤프)를 설정할 필요가 있다. 25, 26, 27 의 각 비트는, 각각 3 화음의 코드, 6 번 또는 7 번의 코드, 확장된 코드를 처리한다. 28 으로 29 의 각 비트는, 각각 으뜸음의 코드와 주음에서 완정 5도위에 음의 코드가 계속되는 코드를 처리한다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_STYLERESOLUTION

스타일 해결을 나타낸다. 스타일 형식에서 사용된다.

typedef struct _DMUS_IO_STYLERESOLUTION {
    DWORD  dwVariation;
    WORD   wMusicValue;
    BYTE   bInversionID;
    BYTE   bPlayModeFlags;
} DMUS_IO_STYLERESOLUTION;

멤버

dwVariation
바리에이션. 각 비트가 유효한 바리에이션을 지정한다.
wMusicValue
스케일내의 위치.
bInversionID
이 노트가 소속하는 회전 그룹.
bPlayModeFlags
연주 모드 플래그. 「DMUS_PLAYMODE_FLAGS 」를 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_SUBCHORD

서브 코드에 관한 정보를 보관 유지한다. 코드 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_SUBCHORD {
    DWORD   dwChordPattern;
    DWORD   dwScalePattern;
    DWORD   dwInversionPoints;
    DWORD   dwLevels;
    BYTE    bChordRoot;
    BYTE    bScaleRoot;
} DMUS_IO_SUBCHORD;

멤버

dwChordPattern
서브 코드내의 노트. 하위 24 비트는 각각 1 개의 반음을 나타내, 최하정도 비트는 루트음이다. 비트가 세트 되고 있는 경우, 거기에 대응하는 노트는 코드내에 존재한다.
dwScalePattern
스케일내의 노트. 하위 24 비트는 각각 1 개의 반음을 나타내, 최하정도 비트는 루트음이다. 비트가 세트 되고 있는 경우, 거기에 대응하는 노트는 스케일내에 존재한다.
dwInversionPoints
스케일내에서 회전을 발생할 수 있는 포인트. 비트가 오프가 되어 있는 경우, 거기에 대응하는 음정에서는 노트를 회전 할 수 없다. 예를 들어, 패턴 100001111111 은, 햇빛 음계 (메이저 스케일)의 5 번과 7 번을 제외해, 어디에서라도 회전이 인정되는 것을 의미한다.
dwLevels
이 서브 코드가 지원 하는 레벨. 특정의 음색을 다른 레벨에 할당 (예를 들어 코드의 서브 코드만을 연주한다), 서브 코드를 그러한 레벨에 맵 하는 방법으로서 이 값을 이용할 수도 있다.
bChordRoot
서브 코드의 루트음. 0 은 범위내의 최저음의 C, 23 은 최고음의 B 이다.
bScaleRoot
스케일의 루트음. 0 은 범위내의 최저음의 C, 23 은 최고음의 B 이다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_SUBCHORD


DMUS_IO_SYSEX_ITEM

MIDI 의 시스템에크스크루시브멧세이지에 관한 정보를 보관 유지한다. 시스템에크스크루시브트락크체크로 사용된다.

typedef struct _DMUS_IO_SYSEX_ITEM {
    MUSIC_TIME  mtTime;
    DWORD       dwPChannel;
    DWORD       dwSysExLength;
} DMUS_IO_SYSEX_ITEM;

멤버

mtTime
메세지의 타임.
dwPChannel
이벤트의 퍼포먼스 채널.
dwSysExLength
데이터의 길이. 바이트 단위로 지정한다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

MIDI 시스템 메세지


DMUS_IO_TEMPO_ITEM

트럭내의 템포의 변경에 관한 정보를 보관 유지한다. 텐포트락크체크로 사용된다.

typedef struct _DMUS_IO_TEMPO_ITEM {
    MUSIC_TIME  lTime;
    double      dblTempo;
} DMUS_IO_TEMPO_ITEM;

멤버

lTime
템포를 변경하는 타임.
dblTempo
템포. 1 분 쯤의 박수로 나타낸다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_TIMESIG

세그먼트(segment)의 박자 기호에 관한 정보를 보관 유지한다. DMUS_IO_STYLE ,DMUS_IO_VERSION , 및 DMUS_IO_PATTERN 의 각 구조체로 사용된다.

typedef struct _DMUS_IO_TIMESIG {
    BYTE  bBeatsPerMeasure;
    BYTE  bBeat;
    WORD  wGridsPerBeat;
} DMUS_IO_TIMESIG;

멤버

bBeatsPerMeasure
소절 근처의 박수 (박자 기호의 분자).
bBeat
노트가 받는 박 (박자 기호의 분모). 이 값이 1 때는 전음부, 2 때는 2 분 음표, 4 때는 4 분 음표를 의미한다. 이하 같이이다. 0 은 256 분 음표를 의미한다.
wGridsPerBeat
박근처의 구라두 (소분할).

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_TIMESIGNATURE_ITEM


DMUS_IO_TIMESIGNATURE_ITEM

박자 기호의 변경에 관한 정보를 보관 유지한다. 박자 기호 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_TIMESIGNATURE_ITEM {
    MUSIC_TIME  lTime;
    BYTE        bBeatsPerMeasure;
    BYTE        bBeat;
    WORD        wGridsPerBeat;
} DMUS_IO_TIMESIGNATURE_ITEM;

멤버

lTime
이벤트의 타임.
bBeatsPerMeasure
소절 근처의 박수 (박자 기호의 분자).
bBeat
노트가 받는 박 (박자 기호의 분모). 이 값이 1 때는 전음부, 2 때는 2 분 음표, 4 때는 4 분 음표를 의미한다. 이하 같이이다. 0 은 256 분 음표를 의미한다.
wGridsPerBeat
박근처의 구라두 (소분할).

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_TIMESIG ,DMUS_TIMESIG_PMSG


DMUS_IO_TOOL_HEADER

툴에 관한 정보를 보관 유지한다. 툴 형식에서 사용된다.

typedef struct _DMUS_IO_TOOL_HEADER {
    GUID    guidClassID;
    long    lIndex;
    DWORD   cPChannels;
    FOURCC  ckid;
    FOURCC  fccType;
    DWORD   dwPChannels[1];
} DMUS_IO_TOOL_HEADER;

멤버

guidClassID
툴의 클래스 식별자.
lIndex
그래프내의 위치.
cPChannels
dwPChannels 배열내의 항목의 수.
ckid
툴의 데이타체크의 식별자. 이 값이 0 의 경우, 체크의 타입은 LIST 라고 보여진다. 그 경우,fccType 는 유효해, 0 이외의 값이 아니면 안된다.
fccType
리스트 타입. 이 값이 0 의 경우,ckid 는 유효해, 0 이외의 값이 아니면 안된다.
dwPChannels
툴이 유효한 퍼포먼스 채널의 배열.

동작환경

헤더 : dmusicf.h 로 선언.

참조

IDirectMusicGraph8::InsertTool


DMUS_IO_TRACK_EXTRAS_HEADER

트럭 형식에서 사용된다.

typedef struct _DMUS_IO_TRACK_EXTRAS_HEADER {
    DWORD  dwFlags;
} DMUS_IO_TRACK_EXTRAS_HEADER;

멤버

dwFlags
제어 트럭의 플래그. 사용할 수 있는 값에 대해서는, 「IDirectMusicSegment8::SetTrackConfig 」를 참조할것.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_TRACK_HEADER

트럭에 관한 정보를 보관 유지한다. 트럭 형식에서 사용된다.

typedef struct _DMUS_IO_TRACK_HEADER {
    GUID     guidClassID;
    DWORD    dwPosition;
    DWORD    dwGroup;
    FOURCC   ckid;
    FOURCC   fccType;
} DMUS_IO_TRACK_HEADER;

멤버

guidClassID
트럭의 클래스 식별자.
dwPosition
트럭 리스트내의 위치.
dwGroup
트럭의 그룹 비트.
ckid
트럭의 데이타체크의 식별자. 이 값이 0 의 경우, 체크의 타입은 LIST 라고 보여진다. 그 경우,fccType 는 유효해, 0 이외의 값이 아니면 안된다.
fccType
리스트 타입. 이 값이 0 의 경우,ckid 는 유효해, 0 이외의 값이 아니면 안된다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

IDirectMusicSegment8::GetTrackGroup ,IDirectMusicSegment8::InsertTrack ,트럭 형식


DMUS_IO_TRACKREF_HEADER

DirectX 8.0 에서는 이행 되지 않는다.

노래 형식에서의 트럭 참조에 관한 정보를 보관 유지한다.

typedef struct _DMUS_IO_TRACKREF_HEADER {
    DWORD       dwSegmentID;
    DWORD       dwFlags;
} DMUS_IO_TRACKREF_HEADER;

멤버

dwSegmentID
소속하는 세그먼트(segment)의 식별자.
dwFlags
예약이 끝난 상태.


DMUS_IO_TRANSITION_DEF

DirectX 8.0 에서는 이행 되지 않는다.

트란지션을 나타낸다. 노래 형식에서 사용된다.

typedef struct _DMUS_IO_TRANSITION_DEF {
    DWORD  dwSegmentID;
    DWORD  dwTransitionID;
    DWORD  dwPlayFlags;
} DMUS_IO_TRANSITION_DEF;

멤버

dwSegmentID
트란지션 후의 세그먼트(segment) 또는 다음의 정수의 어느 쪽인가에 된다.
DMUS_SONG_ANYSEG
임의의 세그먼트(segment).
DMUS_SONG_NOFROMSEG
선행하는 세그먼트(segment)가 없다. 트란지션은 인트로이다.
DMUS_SONG_NOSEG
후속의 세그먼트(segment)가 없다. 트란지션은 엔딩이다.
dwTransitionID
트란지션에 사용하는 템플릿 세그먼트(segment).
dwPlayFlags
트란지션의 연주 방법을 제어하는 플래그. 「DMUS_SEGF_FLAGS 」를 참조할것.

주의

이 구조체는, 다른 세그먼트(segment)로부터 이 세그먼트(segment)에의 유효한 트란지션을 나타낸다. 노래 세그먼트(segment)를 DMUS_SEGF_AUTOTRANSITION 플래그를 사용해 연주하는 경우는, 트란지션세그먼트가 어레인지 되어 연주된다. 적절한 트란지션세그먼트를 찾아내려면 , 퍼포먼스로 현재 연주중의 세그먼트(segment)를 확인해, 노래의 세그먼트(segment)인가 어떤가를 판단한다. 적절한 세그먼트(segment)인 경우는, 그 세그먼트(segment)의 ID 를 취득해, 다음에 전송처 세그먼트(segment)의 트란지션테이불로 목적의 세그먼트(segment)를 검색한다. dwSourceSegment 로 일치하는 세그먼트(segment)가 발견되었을 경우는,dwPlayFlags 를 사용해, 퍼포먼스가 dwTransitionSegment 를 어레인지 해, 연주한다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_VALID_START

리듬에 삽입된다, 세그먼트(segment)내의 유효한 시작 포인트에 관한 정보를 보관 유지한다. 마커 트럭 리스트로 사용된다.

typedef struct _DMUS_IO_VALID_START {
    MUSIC_TIME mtTime;
} DMUS_IO_VALID_START;

멤버

mtTime
시작 포인트의 타임.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_VERSION

데이터의 버젼 번호를 보관 유지한다. 다양한 체크의 바젼사브체크내에서 사용된다. 「공통의 체크」를 참조할것.

typedef struct _DMUS_IO_VERSION {
    DWORD  dwVersionMS;
    DWORD  dwVersionLS;
} DMUS_IO_VERSION;

멤버

dwVersionMS
버젼 번호의 상위 32 비트.
dwVersionLS
버젼 번호의 하위 32 비트.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_WAVE_HEADER

웨이브의 스트리밍 특성을 나타낸다. 웨이브 파일의웨브헷다체크로 사용된다.

typedef struct _DMUS_IO_WAVE_HEADER {
    REFERENCE_TIME  rtReadAhead;
    DWORD           dwFlags;
} DMUS_IO_WAVE_HEADER;

멤버

rtReadAhead
스트리밍 웨이브에서 선행해 읽어내는 타임.
dwFlags
플래그. 0 또는 다음의 값을 지정한다.
DMUS_WAVEF_STREAMING
웨이브는 스트리밍 웨이브이다.

동작환경

헤더 : dmusicf.h 로 선언.


DMUS_IO_WAVE_ITEM_HEADER

웨이브 트럭 리스트의 웨이브 사운드의 데이터를 보관 유지한다.

typedef struct _DMUS_IO_WAVE_ITEM_HEADER {
    long           lVolume;
    long           lPitch;
    DWORD          dwVariations;
    REFERENCE_TIME rtTime;
    REFERENCE_TIME rtStartOffset;
    REFERENCE_TIME rtReserved;
    REFERENCE_TIME rtDuration;
    MUSIC_TIME     mtLogicalTime;
    DWORD          dwLoopStart;
    DWORD          dwLoopEnd;
    DWORD          dwFlags;
} DMUS_IO_WAVE_ITEM_HEADER;

멤버

lVolume
게인. 1/100 dB (데시벨) 단위로 지정한다. 부의 값이 아니면 안된다.
lPitch
피치 오프셋(offset). 1/100 반음 단위로 지정한다.
dwVariations
바리에이션 플래그. 이 웨이브가 소속하는 바리에이션 마다 1 비트가 설정된다.
rtTime
시작 타임. 트럭이 클락 타임 형식인 경우는 기준 타임. 그 이외의 경우는 뮤직 타임.
rtStartOffset
재생을 시작 하는 웨이브까지의 거리. 기준 타임에 지정한다.
rtReserved
미사용.
rtDuration
지속 시간. 트럭이 클락 타임 형식인 경우는 기준 타임. 그 이외의 경우는 뮤직 타임.
mtLogicalTime
이 웨이브가 소속하는 음악 경계. 트럭이 클락 타임 형식인 경우는 무시한다.
dwLoopStart
루프 웨이브의 시작 포인트.
dwLoopEnd
루프 웨이브의 종료 포인트.
dwFlags
플래그. 0 또는 다음의 몇개의 값을 지정할 수 있다.
DMUS_WAVEF_NOINVALIDATE
이 웨이브는 무효화하지 않는다.
DMUS_WAVEF_STREAMING
웨이브는 스트림 하고 있다.

동작환경

헤더 : dmusicf.h 로 선언.

주의

논리적인 타임과 실제의 타임


DMUS_IO_WAVE_PART_HEADER

웨이브 트럭 리스트의 데이터를 보관 유지한다.

typedef struct _DMUS_IO_WAVE_PART_HEADER {
    long   lVolume;
    DWORD  dwVariations;
    DWORD  dwPChannel;
    DWORD  dwLockToPart;
    DWORD  dwFlags;
    DWORD  dwIndex;
} DMUS_IO_WAVE_PART_HEADER;

멤버

lVolume
이 웨이브 파트내의 모든 웨이브에 적용하는 게인. 1/100 dB (데시벨) 단위로 지정한다. 부의 값이 아니면 안된다.
dwVariations
액티브한 바리에이션. 액티브한 바리에이션 마다 1 비트가 설정된다.
dwPChannel
파트의 퍼포먼스 채널.
dwLockToPart
락 식별자의 바리에이션. 이 멤버내의 값과 같은 값을 가지는 파트는, 항상 같은 바리에이션을 연주한다. 값 0 은, 파트가 바리에이션을 그 외의 파트와는 따로 연주하는 것을 의미한다.
dwFlags
바리에이션의 선택 방법을 관리하는 플래그. 하위 4 비트로 지정한다. 「DMUS_VARIATIONT_TYPES 」를 참조할것.
dwIndex
동일한 퍼포먼스 채널상에서 복수의 파트를 구별하기 위한 인덱스.


DMUS_IO_WAVE_TRACK_HEADER

웨이브 트럭 리스트의 웨이브 트럭의 데이터를 보관 유지한다.

typedef struct _DMUS_IO_WAVE_TRACK_HEADER {
    long   lVolume;
    DWORD  dwFlags;
} DMUS_IO_WAVE_TRACK_HEADER;

멤버

lVolume
모든 웨이브에 적용하는 게인. 1/100 dB (데시벨) 단위로 지정한다.
dwFlags
플래그. 0 또는 다음의 1 개 이상의 값을 지정할 수 있다.
DMUS_WAVETRACKF_SYNC_VAR
트럭은, 패턴 트럭으로부터 바리에이션을 취득한다. 상세한 것에 대하여는, 「GUID_Variations 」를 참조할것.
DMUS_WAVETRACKF_PERSIST_CONTROL
바리에이션 제어 정보는, 어느 재생 인스턴스로부터 다음의 인스턴스에 지속한다.

동작환경

헤더 : dmusicf.h 로 선언.


DSOUND_IO_3D

DirectSound 버퍼 구성 형식의 DirectSound 버퍼의 3D 파라미터를 보관 유지한다.

typedef struct _DSOUND_IO_3D {
    GUID guid3DAlgorithm;
    DS3DBUFFER ds3d;
} DSOUND_IO_3D;

멤버

guid3DAlgorithm
사용하는 3D 알고리즘의 일의의 식별자. 「DSBUFFERDESC 」를 참조할것.
ds3d
파라미터를 보관 유지하는 DS3DBUFFER 구조체. 이 정보는, 버퍼 기술에 DSBCAPS_CTRL3D 가 설정되어 있는 경우에게만 유효하다.

동작환경

헤더 : dmusicf.h 로 선언.


DSOUND_IO_DSBUFFERDESC

DirectSound 버퍼를 나타낸다. DirectSound 버퍼 구성 형식에서 사용된다.

typedef struct _DSOUND_IO_DSBUFFERDESC {
    DWORD dwFlags;
    WORD nChannels;
    LONG lVolume;
    LONG lPan;
    DWORD dwReserved;
} DSOUND_IO_DSBUFFERDESC;

멤버

dwFlags
버퍼 생성 플래그. 「DSBUFFERDESC 」를 참조할것.
nChannels
채널의 수. 포맷의 그 외의 파라미터는, 버퍼를 소유하는 세면대에 의해 결정된다.
lVolume
초기 볼륨. dwFlags 로 DSBCAPS_CTRLVOLUME 가 지정되고 있는 경우만 사용된다.
lPan
초기의 빵. dwFlags 로 DSBCAPS_CTRLPAN 가 지정되고 있는 경우만 사용된다.
dwReserved
예약이 끝난 상태. 0 이 아니면 안된다.

동작환경

헤더 : dmusicf.h 로 선언.


DSOUND_IO_DSBUSID

버스 식별자를 보관 유지한다. DirectSound 버퍼 구성 형식에서 사용된다.

typedef struct _DSOUND_IO_DSBUSID {
    DWORD busid[1];
} DSOUND_IO_DSBUSID;

멤버

busid
버스 식별자를 보관 유지하는 DWORD 값의 배열. 배열의 사이즈는, 체크의 사이즈로부터 결정할 수가 있다.

동작환경

헤더 : dmusicf.h 로 선언.


DSOUND_IO_DXDMO_DATA

DMO 의 데이터를 보관 유지한다.

typedef struct _DSOUND_IO_DXDMO_DATA {
    DWORD data[1];
} DSOUND_IO_DXDMO_DATA;

멤버

data
데이터를 보관 유지하는 DWORD 값의 배열. 배열의 사이즈는, 체크의 사이즈로부터 결정할 수가 있다.

동작환경

헤더 : dmusicf.h 로 선언.


DSOUND_IO_DXDMO_HEADER

이펙트 형식의 DMO 체크의 헤더 정보를 보관 유지한다.

typedef struct _DSOUND_IO_DXDMO_HEADER {
    DWORD dwEffectFlags;
    GUID guidDSFXClass;
    GUID guidReserved;
    GUID guidSendBuffer;
    DWORD dwReserved;
} DSOUND_IO_DXDMO_HEADER;

멤버

dwEffectFlags
이펙트 생성 플래그. 「DSEFFECTDESC 」를 참조할것.
guidDSFXClass
이펙트의 클래스 식별자.
guidReserved
예약이 끝난 상태. GUID_NULL 가 아니면 안된다.
guidSendBuffer
이것이센드 이펙트의 경우는, 송신하는 버퍼의 일의의 식별자.
dwReserved
예약이 끝난 상태. 0 이 아니면 안된다.

동작환경

헤더 : dmusicf.h 로 선언.


표준 트럭 파라미터

여기에서는, 이하의 메소드를 사용해 설정 또는 취득할 수 있는 표준 트럭 파라미터에 대해 설명한다.

  • IDirectMusicPerformance8::GetParam
  • IDirectMusicPerformance8::GetParamEx
  • IDirectMusicPerformance8::SetParam
  • IDirectMusicSegment8::GetParam
  • IDirectMusicSegment8::SetParam
  • IDirectMusicTrack8::GetParam
  • IDirectMusicTrack8::GetParamEx
  • IDirectMusicTrack8::SetParam
  • IDirectMusicTrack8::SetParamEx

여기에서는 파라미터의 GUID 마다 파라미터 타입의 리스트를 나타낸다. 메소드 호출의 rGuidType 파라미터에는, 이 GUID 를 지정한다.

각 파라미터 타입에 대해, 이하의 정보가 제공된다.

요소 | 설명
트럭 타입 | 파라미터를 적용하는 트럭. 「표준 트럭의 종류」를 참조할것. 파라미터는 항상 특정의 트럭에 관련지을 수 있지만, 어플리케이션이 보통, 세그먼트(segment) 또는 퍼포먼스로 메소드를 호출해, DirectMusic 가 적절한 트럭을 검색한다. 「트럭의 식별」을 참조할것.
데이터 타입 | 파라미터를 설정 또는 취득하는 메소드 호출의,pParam 파라미터가 가리키는 데이터 타입.
mtTime | 파라미터를 설정 또는 취득하는 메소드 호출해에 있어서의 mtTime 파라미터의 의미 (있는 경우).

파라미터 타입은 이하대로이다.

  • GUID_BandParam
  • GUID_ChordParam
  • GUID_Clear_All_Bands
  • GUID_Clear_All_MelodyFragments
  • GUID_CommandParam
  • GUID_CommandParam2
  • GUID_CommandParamNext
  • GUID_ConnectToDLSCollection
  • GUID_Disable_Auto_Download
  • GUID_DisableTempo
  • GUID_DisableTimeSig
  • GUID_Download
  • GUID_DownloadToAudioPath
  • GUID_Enable_Auto_Download
  • GUID_EnableTempo
  • GUID_EnableTimeSig
  • GUID_IDirectMusicBand
  • GUID_IDirectMusicChordMap
  • GUID_IDirectMusicStyle
  • GUID_MelodyFragment
  • GUID_MuteParam
  • GUID_Play_Marker
  • GUID_RhythmParam
  • GUID_SeedVariations
  • GUID_StandardMIDIFile
  • GUID_TempoParam
  • GUID_TimeSignature
  • GUID_Unload
  • GUID_UnloadFromAudioPath
  • GUID_Valid_Start_Time
  • GUID_Variations


GUID_BandParam

밴드를 설정 또는 취득한다.

트럭 타입 | 밴드
데이터 타입 (*pParam) | DMUS_BAND_PARAM
mtTime | 어느 시점에서 밴드를 설정하는지를 나타내는 논리 위에의 타임, 또는 어느 시점의 밴드를 취득하는지를 나타내는 타임.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_ChordParam

코드 변경을 설정 또는 취득한다.

트럭 타입 | 코드
데이터 타입 (*pParam) | DMUS_CHORD_PARAM
mtTime | 어느 시점에서 트럭에 코드를 추가하는지를 나타내는 타임. 또는, 트럭으로부터 코드를 취득하는 타임, 또는 그 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_Clear_All_Bands

트럭으로부터 모든 밴드를 소거한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드
데이터 타입 (*pParam) | 없음
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_Clear_All_MelodyFragments

DirectX 8.0 에서는 이행 되지 않는다.

트럭으로부터 모든 멜로디 단편을 소거한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 멜로디 단편
데이터 타입 (*pParam) | 없음
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_CommandParam

홈 또는 장식 커멘드를 설정 또는 취득한다.

트럭 타입 | 커멘드
데이터 타입 (*pParam) | DMUS_COMMAND_PARAM_2
mtTime | 트럭에 커멘드를 추가하는 타임. 또는, 트럭으로부터 커멘드를 취득하는 타임 혹은 그 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_CommandParam2

홈 또는 장식 커멘드를 설정 또는 취득한다.

트럭 타입 | 커멘드
데이터 타입 (*pParam) | DMUS_COMMAND_PARAM_2 . 이 구조체의 mtTime 멤버는, 커멘드의 실제의 타임을 지정한다.
mtTime | 트럭에 커멘드를 추가하는 타임. 또는, 트럭으로부터 커멘드를 취득하는 타임 혹은 그 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_CommandParamNext

커멘드 트럭내의 그 외 모든 커멘드의 선두가 되는, 홈 커멘드나 장식 커멘드를 설정 또는 취득한다.

트럭 타입 | 커멘드
데이터 타입 (*pParam) | DMUS_COMMAND_PARAM_2
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_ConnectToDLSCollection

트럭내의 모든 밴드를 DLS 콜렉션에 접속한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드
데이터 타입 (*pParam) | IDirectMusicCollection8 포인터
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

커스텀 음색에 의한 MIDI 파일의 연주


GUID_Disable_Auto_Download

음색과 웨이브의 자동 다운로드를 무효로 한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드, 웨이브
데이터 타입 (*pParam) | 없음
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

밴드의 사용법,GUID_Enable_Auto_Download


GUID_DisableTempo

템포 메세지를 무효로 한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 템포
데이터 타입 (*pParam) | 없음
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

트럭 파라미터의 무효화와 유효화,GUID_EnableTempo


GUID_DisableTimeSig

박자 기호 메세지를 무효로 한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 패턴, 박자 기호, 스타일, 모티프
데이터 타입 (*pParam) | 없음
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

트럭 파라미터의 무효화와 유효화,GUID_EnableTimeSig


GUID_Download

음색 데이터 또는 웨이브 데이터를 다운로드한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드, 웨이브
데이터 타입 (*pParam) | IDirectMusicPerformance8 포인터
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::Download


GUID_DownloadToAudioPath

음색 데이터 또는 웨이브 데이터를 다운로드한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드, 웨이브
데이터 타입 (*pParam) | IDirectMusicAudioPath8 포인터
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment8::Download


GUID_Enable_Auto_Download

음색과 웨이브의 자동 다운로드를 유효하게 한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드, 웨이브
데이터 타입 (*pParam) | 없음
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

밴드의 사용법,GUID_Disable_Auto_Download


GUID_EnableTempo

템포 메세지를 유효하게 한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 템포
데이터 타입 (*pParam) | 없음
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

트럭 파라미터의 무효화와 유효화,GUID_DisableTempo


GUID_EnableTimeSig

박자 기호 메세지를 유효하게 한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 패턴, 박자 기호, 스타일, 모티프
데이터 타입 (*pParam) | 없음
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

트럭 파라미터의 무효화와 유효화,GUID_DisableTimeSig


GUID_IDirectMusicBand

밴드를 설정한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드
데이터 타입 (*pParam) | IDirectMusicBand8
mtTime | 어느 시점에서 트럭에 밴드를 추가하는지를 나타내는 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

이 파라미터는, 물리 타임을 지정할 수 있는 GUID_BandParam 에 인계된다.

동작환경

헤더 : dmusici.h 로 선언.


GUID_IDirectMusicChordMap

코드 맵을 설정 또는 취득한다.

트럭 타입 | 코드 맵
데이터 타입 (*pParam) | IDirectMusicChordMap8 포인터. 또는 이 포인터를 받는 변수의 주소.
mtTime | 어느 시점에서 트럭에 코드 맵을 추가하는지를 나타내는 타임. 또는, 트럭으로부터 코드 맵을 취득하는 타임, 또는 그 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_IDirectMusicStyle

스타일을 설정 또는 취득한다.

트럭 타입 | 스타일
데이터 타입 (*pParam) | IDirectMusicStyle8 포인터. 또는 이 포인터를 받는 변수의 주소.
mtTime | 어느 시점에서 트럭에 스타일을 추가하는지를 나타내는 타임. 또는, 트럭으로부터 스타일을 취득하는 타임, 또는 그 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_MelodyFragment

DirectX 8.0 에서는 이행 되지 않는다.

멜로디 단편을 설정 또는 취득한다.

트럭 타입 | 멜로디 단편
데이터 타입 (*pParam) | DMUS_MELODY_FRAGMENT
mtTime | 어느 시점에서 트럭에 단편을 추가하는지를 나타내는 타임. 또는, 트럭으로부터 단편을 취득하는 타임, 또는 그 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_MuteParam

채널 (매핑 정보)을 설정 또는 취득한다.

트럭 타입 | 뮤트
데이터 타입 (*pParam) | DMUS_MUTE_PARAM . 이 구조체를 get 메소드에 건네주기 전에,dwPChannel 멤버를 초기화해야 한다.
mtTime | 어느 시점에서 트럭에 뮤트 이벤트를 추가하는지를 나타내는 타임. 또는, 트럭으로부터 뮤트 이벤트를 취득하는 타임, 또는 그 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

뮤트 트럭의 연주중에 이 파라미터를 설정해도, 채널의 매핑이나 뮤트를 동적으로 변경할 수 없다. 뮤트 트럭의 파라미터는, 그 외의 트럭으로부터 내부의 GetParam 를 호출하는 것으로 취득된다. 어플리케이션은, 이러한 호출의 타이밍에 대한 제어를 가지지 않는다. 채널의 매핑이나 뮤트의 변경은, 제어 세그먼트(segment)로서 연주되는 세그먼트(segment)의 뮤트 트럭에 기술하는지, 툴을 사용해 실행시에 실시할 필요가 있다.

동작환경

헤더 : dmusici.h 로 선언.


GUID_Play_Marker

현재 연주중의 세그먼트(segment)로부터, 신규 세그먼트(segment)를 시작 할 수 있는 다음의 포인트를 취득한다. 이 파라미터는 취득할 수 있지만, 설정할 수 없다.

트럭 타입 | 마커
데이터 타입 (*pParam) | DMUS_PLAY_MARKER_PARAM
mtTime | 어느 시점에서 마커의 시크를 시작 하는지를 나타내는 트럭 시간.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

세그먼트(segment)의 타이밍


GUID_RhythmParam

트럭의 소절에 저장 되고 있는, 코드의 순서의 리듬 패턴을 취득한다. 이 파라미터는 취득할 수 있지만, 설정할 수 없다.

트럭 타입 | 코드
데이터 타입 (*pParam) | DMUS_RHYTHM_PARAM . 이 구조체를 get 메소드에 건네주기 전에,TimeSig 멤버를 초기화해야 한다.
mtTime | 트럭으로부터 취득하는 리듬 패턴이 포함되어 있는 소절의 시작, 또는 시작 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_SeedVariations

바리에이션 선택에 사용하는 랜덤값을 생성할 때의 배정이 된다. 제로 이외의 값이 시트로서 사용된다. 값이 제로의 경우는 디폴트 상태에 돌아와, 시스템 클록으로부터 배정을 취득한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 패턴, 스타일, 모티프
데이터 타입 (*pParam) | Long 형
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

이 파라미터에 제로 이외의 값을 설정 하면, 매회 같은 순서로 랜덤인 숫자가 생성되므로, 테스트 시에 도움이 된다. 파라미터는, 트럭을 연주하기 전에 한 번만 설정한다. 스타일과 커멘드 트럭은, 세그먼트(segment)가 연주될 때마다, 세그먼트(segment)의 같은 장소에서 같은 패턴이 선택되도록(듯이) 설계해야 한다. 각 루프는, 전회와는 다른 바리에이션으로 연주되지만, 세그먼트(segment) 전체가 최초부터 연주될 때마다, 각 루프는 세그먼트(segment)가 최초로 연주되었을 때 것과 같이 들린다.

동작환경

헤더 : dmusici.h 로 선언.


GUID_StandardMIDIFile

스탠다드 MIDI 파일 (DirectMusic 용으로 특별히 오쏘링되어 있지 않은 MIDI 파일)이, 올바르게 연주되도록(듯이) 보증한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드
데이터 타입 (*pParam) | 없음
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

이 파라미터는, 음색이 다운로드되기 전에, MIDI 파일에 근거하는 세그먼트(segment)로 설정되지 않으면 안 된다.

동작환경

헤더 : dmusici.h 로 선언.


GUID_TempoParam

템포를 설정 또는 취득한다.

트럭 타입 | 템포
데이터 타입 (*pParam) | DMUS_TEMPO_PARAM . 파라미터 설정시에, 구조체의 mtTime 멤버는 무시된다. 파라미터 취득시에,mtTime 멤버는, 요구된 타임부터의 템포의 변경의 오프셋(offset)를 받는다. 항상 0 이하이다.
mtTime | 어느 시점에서 템포를 설정하는지를 나타내는 타임. 또는, 템포의 변경을 취득하는 타임, 또는 그 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_TimeSignature

박자 기호를 취득한다. 이 파라미터는 취득할 수 있지만, 설정할 수 없다.

트럭 타입 | 박자 기호 및 스타일
데이터 타입 (*pParam) | DMUS_TIMESIGNATURE . mtTime 멤버는, 요구한 타임부터의 박자 기호의 변경의 오프셋(offset)를 받는다. 이 값은, 항상 0 이하이다.
mtTime | 어느 시점에서 박자 기호를 설정하는지를 나타내는 타임. 또는, 박자 기호의 변경을 취득하는 타임, 또는 그 직후의 타임. 트럭 시간에 지정한다.

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


GUID_Unload

음색 데이터 또는 웨이브 데이터를 언로드한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드, 웨이브
데이터 타입 (*pParam) | IDirectMusicPerformance8 포인터
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

참조

IDirectMusicSegment8::Unload

동작환경

헤더 : dmusici.h 로 선언.


GUID_UnloadFromAudioPath

음색 데이터 또는 웨이브 데이터를 언로드한다. 이 파라미터는 설정할 수 있지만, 취득할 수 없다.

트럭 타입 | 밴드, 웨이브
데이터 타입 (*pParam) | IDirectMusicAudioPath8 포인터
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

참조

IDirectMusicSegment8::Unload

동작환경

헤더 : dmusici.h 로 선언.


GUID_Valid_Start_Time

세그먼트(segment)내에서, 시작 할 수 있는 다음의 유효한 포인트를 취득한다. 이 파라미터는 취득할 수 있지만, 설정할 수 없다.

트럭 타입 | 마커, 모티프, 패턴
데이터 타입 (*pParam) | DMUS_VALID_START_PARAM
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

참조

세그먼트(segment)의 타이밍

동작환경

헤더 : dmusici.h 로 선언.


GUID_Variations

퍼포먼스 채널 전체로부터 이펙트의 바리에이션을 취득한다. 이 파라미터는 취득할 수 있지만, 설정할 수 없다.

트럭 타입 | 패턴
데이터 타입 (*pParam) | DMUS_VARIATIONS_PARAM
mtTime | 미사용

주의

겉(표)의 설명에 대해서는, 「표준 트럭 파라미터」를 참조할것.

동작환경

헤더 : dmusici.h 로 선언.


DirectMusic 열거형

여기에서는, 다음의 열거형에 관한 레퍼런스 정보를 기술한다.

  • DMUS_CHORDKEYF_FLAGS
  • DMUS_CLOCKTYPE
  • DMUS_COMMANDT_TYPES
  • DMUS_COMPOSEF_FLAGS
  • DMUS_CURVE_FLAGS
  • DMUS_NOTEF_FLAGS
  • DMUS_PATTERNT_TYPES
  • DMUS_PLAYMODE_FLAGS
  • DMUS_PMSGF_FLAGS
  • DMUS_PMSGT_TYPES
  • DMUS_SEGF_FLAGS
  • DMUS_SHAPET_TYPES
  • DMUS_STYLET_TYPES
  • DMUS_TIME_RESOLVE_FLAGS
  • DMUS_TRACKF_FLAGS
  • DMUS_VARIATIONT_TYPES


DMUS_CHORDKEYF_FLAGS

DMUS_CHORD_KEY 구조체의 bFlags 멤버로 사용된다.

typedef enum enumDMUS_CHORDKEYF_FLAGS {
    DMUS_CHORDKEYF_SILENT  = 1,
} DMUS_CHORDKEYF_FLAGS;

정수

DMUS_CHORDKEYF_SILENT
코드는 무음이다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_CLOCKTYPE

DMUS_CLOCKINFO8 구조체의 ctType 멤버로 사용된다.

typedef enum {
    DMUS_CLOCK_SYSTEM = 0,
    DMUS_CLOCK_WAVE   = 1
} DMUS_CLOCKTYPE;

정수

DMUS_CLOCK_SYSTEM
클락은 시스템 클록이다.
DMUS_CLOCK_WAVE
클락은 웨이브 재생 디바이스상에 있다.

동작환경

헤더 : dmusicc.h 로 선언.


DMUS_COMMANDT_TYPES

IDirectMusicComposer8::AutoTransition 메소드와 IDirectMusicComposer8::ComposeTransition 메소드의 wCommand 파라미터, 및 DMUS_COMMAND_PARAM 구조체의 bCommand 멤버로 사용된다.

typedef enum enumDMUS_COMMANDT_TYPES {
    DMUS_COMMANDT_GROOVE      = 0,
    DMUS_COMMANDT_FILL        = 1,
    DMUS_COMMANDT_INTRO       = 2,
    DMUS_COMMANDT_BREAK       = 3,
    DMUS_COMMANDT_END         = 4,
    DMUS_COMMANDT_ENDANDINTRO = 5
} DMUS_COMMANDT_TYPES;

정수

DMUS_COMMANDT_GROOVE
커멘드는 홈 커멘드이다.
DMUS_COMMANDT_FILL
커멘드는 필이다.
DMUS_COMMANDT_INTRO
커멘드는 인트로이다.
DMUS_COMMANDT_BREAK
커멘드는 변환점이다.
DMUS_COMMANDT_END
커멘드는 엔딩이다.
DMUS_COMMANDT_ENDANDINTRO
커멘드는 엔딩과 인트로이다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_COMPOSEF_FLAGS

IDirectMusicComposer8::ComposeTransition 메소드와 IDirectMusicComposer8::AutoTransition 메소드의 dwFlags 파라미터로 사용된다.

typedef enum enumDMUS_COMPOSEF_FLAGS {
    DMUS_COMPOSEF_NONE                =       0,
    DMUS_COMPOSEF_ALIGN               =     0x1,
    DMUS_COMPOSEF_OVERLAP             =     0x2,
    DMUS_COMPOSEF_IMMEDIATE           =     0x4,
    DMUS_COMPOSEF_GRID                =     0x8,
    DMUS_COMPOSEF_BEAT                =    0x10,
    DMUS_COMPOSEF_MEASURE             =    0x20,
    DMUS_COMPOSEF_AFTERPREPARETIME    =    0x40,
    DMUS_COMPOSEF_VALID_START_BEAT    =    0x80,
    DMUS_COMPOSEF_VALID_START_GRID    =   0x100,
    DMUS_COMPOSEF_VALID_START_TICK    =   0x200,
    DMUS_COMPOSEF_SEGMENTEND          =   0x400,
    DMUS_COMPOSEF_MARKER              =   0x800,
    DMUS_COMPOSEF_MODULATE            =  0x1000,
    DMUS_COMPOSEF_LONG                =  0x2000,
    DMUS_COMPOSEF_ENTIRE_TRANSITION   =  0x4000,
    DMUS_COMPOSEF_1BAR_TRANSITION     =  0x8000,
    DMUS_COMPOSEF_ENTIRE_ADDITION     = 0x10000,
    DMUS_COMPOSEF_1BAR_ADDITION       = 0x20000,
    DMUS_COMPOSEF_VALID_START_MEASURE = 0x40000,
    DMUS_COMPOSEF_DEFAULT             = 0x80000,
    DMUS_COMPOSEF_NOINVALIDATE       = 0x100000,
    DMUS_COMPOSEF_USE_AUDIOPATH      = 0x200000
}  DMUS_COMPOSEF_FLAGS;

정수

DMUS_COMPOSEF_NONE
플래그 없음. 디폴트에서는, 트란지션은 소절 경계로부터 시작 한다.
DMUS_COMPOSEF_ALIGN
트란지션을, 현재 연주되고 있는 세그먼트(segment)의 박자 기호에 가지런히 한다.
DMUS_COMPOSEF_OVERLAP
트란지션을 pToSeg 에 거듭한다 (오버랩). 이 플래그는 현재 이행되어 있지 않다.
DMUS_COMPOSEF_IMMEDIATE
AutoTransition 마셔. 뮤직 타임 또는 기준 타임의 경계로부터 트란지션을 시작 한다.
DMUS_COMPOSEF_GRID
AutoTransition 마셔. 구라두 경계로부터 트란지션을 시작 한다.
DMUS_COMPOSEF_BEAT
AutoTransition 마셔. 박의 경계로부터 트란지션을 시작 한다.
DMUS_COMPOSEF_MEASURE
AutoTransition 마셔. 소절 경계로부터 트란지션을 시작 한다.
DMUS_COMPOSEF_AFTERPREPARETIME
AutoTransition 마셔. 트란지션을 삽입 하면나무는, DMUS_SEGF_AFTERPREPARETIME 플래그를 사용한다.
DMUS_COMPOSEF_VALID_START_BEAT
임의의 박으로 변환을 발생할 수 있다. DMUS_COMPOSEF_ALIGN 와 조합해 사용된다.
DMUS_COMPOSEF_VALID_START_GRID
임의의 구라두로 변환을 발생할 수 있다. DMUS_COMPOSEF_ALIGN 와 조합해 사용된다.
DMUS_COMPOSEF_VALID_START_TICK
임의의 타임에 변환을 발생할 수 있다. DMUS_COMPOSEF_ALIGN 와 조합해 사용된다.
DMUS_COMPOSEF_SEGMENTEND
현재의 세그먼트(segment)의 마지막에 트란지션을 연주한다.
DMUS_COMPOSEF_MARKER
현재의 세그먼트(segment)의 다음의 마커로 트란지션을 연주한다.
DMUS_COMPOSEF_MODULATE
pToSeg 의 코드를 사용해,pFromSeg 로부터 pToSeg 로 순조롭게 변화하는 트란지션을 어레인지 한다.
DMUS_COMPOSEF_LONG
긴 트란지션을 어레인지 한다. 이 플래그가 설정되어 있지 않은 경우,ComposeTransition 또는 AutoTransition 의 wCommand 파라미터로 엔딩을 지정해, 스타일에 1 소절보다 긴 엔딩이 포함되지 않은 한, 트란지션의 길이는 최대에서도 1 소절이다. 이 플래그가 설정되어 있는 경우, 트란지션의 길이는 1 소절 증가한다.
DMUS_COMPOSEF_ENTIRE_TRANSITION
트란지션파탄 전체를 포함한다.
DMUS_COMPOSEF_1BAR_TRANSITION
트란지션파탄의 1 소절을 포함한다.
DMUS_COMPOSEF_ENTIRE_ADDITION
추가의 트란지션파탄을 완전한 형태로 포함한다. DMUS_COMPOSEF_LONG 와 조합해 사용된다.
DMUS_COMPOSEF_1BAR_ADDITION
추가의 트란지션파탄의 1 소절을 포함한다. DMUS_COMPOSEF_LONG 가 지정되고 있는 경우는, 이것이 디폴트의 동작이다.
DMUS_COMPOSEF_VALID_START_MEASURE
임의의 소절로 변환을 발생할 수 있다. DMUS_COMPOSEF_ALIGN 와 조합해 사용된다.
DMUS_COMPOSEF_DEFAULT
세그먼트(segment)의 디폴트의 경계를 사용한다.
DMUS_COMPOSEF_NOINVALIDATE
연주중의 세그먼트(segment)를 무효로 하지 않는다.
DMUS_COMPOSEF_USE_AUDIOPATH
세그먼트(segment)에 파묻힌 오디오 패스를 사용한다.

동작환경

헤더 : dmusici.h 로 선언.

참조

DMUS_SEGF_FLAGS


DMUS_CURVE_FLAGS

DMUS_CURVE_PMSG 구조체의 bFlags 멤버로 사용된다.

typedef enum enumDMUS_CURVE_FLAGS {
    DMUS_CURVE_RESET              = 1,
    DMUS_CURVE_START_FROM_CURRENT = 2,
} DMUS_CURVE_FLAGS;

정수

DMUS_CURVE_RESET
디폴트의 타임에 이르렀을 때, 또는 트란지션이 원인으로 무효화가 발생했을 때에 DMUS_CURVE_PMSG.nResetValue 를 설정해야 하는 경우는, 이 값을 DMUS_CURVE_RESET 로 설정한다. 플래그가 설정되어 있지 않은 경우, 커브는 새로운 값에 영속적에 머무른다.
DMUS_CURVE_START_FROM_CURRENT
DMUS_CURVE_PMSG.nStartValue 를 무시해, 현재의 값으로 커브를 시작 한다. 이것은, 볼륨, 에크스프렛션, 및 핏치벤드에만 작용한다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_NOTEF_FLAGS

DMUS_NOTE_PMSG 구조체의 bFlags 멤버로 사용된다.

typedef enum enumDMUS_NOTEF_FLAGS {
    DMUS_NOTEF_NOTEON =               1,
    DMUS_NOTEF_NOINVALIDATE =         2,
    DMUS_NOTEF_NOINVALIDATE_INSCALE = 4,
    DMUS_NOTEF_NOINVALIDATE_INCHORD = 8,
    DMUS_NOTEF_REGENERATE =        0x10,
} DMUS_NOTEF_FLAGS;

정수

DMUS_NOTEF_NOTEON
MIDI 노트 온. IDirectMusicPerformance8::SendPMsg 메소드로 최초로 DMUS_NOTE_PMSG 를 지정하는 경우는, 이 플래그를 설정해야 한다. 이 플래그가 설정되어 있지 않은 경우, 메세지는 노트 오프이다.
DMUS_NOTEF_NOINVALIDATE
이 노트를 무효로 하지 않는다.
DMUS_NOTEF_NOINVALIDATE_INSCALE
이 노트가 아직 스케일내에 있는 경우는, 무효로 하지 않는다.
DMUS_NOTEF_NOINVALIDATE_INCHORD
이 노트가 아직 코드내에 있는 경우는, 무효로 하지 않는다.
DMUS_NOTEF_REGENERATE
코드 체인지가 발생하면(자) 노트를 재생성한다. 노트의 뮤직값, 서브 코드 레벨, 및 연주 모드의 각 플래그는, 새로운 코드와 스케일에 따라 새로운 노트를 구축하기 위해서 사용된다. 원의 노트에 타이밍 오프셋(offset)가 있었을 경우, 이것이 새로운 노트의 시작 타임에 적용된다.

주의

NOINVALIDATE 플래그를 설정하는 것으로, 노트는 메세지가 무효화된다고 해도, 계속 시간의 끝까지 확실히 연주된다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_PATTERNT_TYPES

다양한 커멘드 구조 체내에서 사용되어 시퀀셜 커멘드내에서의 패턴의 선택 방법을 제어한다.

typedef enum enumDMUS_PATTERNT_TYPES {
    DMUS_PATTERNT_RANDOM           = 0,
    DMUS_PATTERNT_REPEAT           = 1,
    DMUS_PATTERNT_SEQUENTIAL       = 2,
    DMUS_PATTERNT_RANDOM_START     = 3,
    DMUS_PATTERNT_NO_REPEAT        = 4,
    DMUS_PATTERNT_RANDOM_ROW       = 5
} DMUS_PATTERNT_TYPES;

정수

DMUS_PATTERNT_RANDOM
일치하는 패턴을 랜덤에 선택한다. 이것은, DirectX 8.0 이전의 버젼의 동작이다.
DMUS_PATTERNT_REPEAT
일치하는 마지막 패턴을 반복한다.
DMUS_PATTERNT_SEQUENTIAL
일치하는 패턴을, 로드 된 순서에 최초부터 연주한다.
DMUS_PATTERNT_RANDOM_START
일치하는 패턴을, 로드 된 순서에, 순서내의 랜덤인 포인트로부터 연주한다.
DMUS_PATTERNT_NO_REPEAT
랜덤에 연주한다. 다만, 패턴은 한 번 두개 밖에 연주하지 않는다.
DMUS_PATTERNT_RANDOM_ROW
랜덤에 연주한다. 모든 것을 연주할 때까지는 패턴을 반복하지 않는다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_COMMAND_PARAM ,DMUS_COMMAND_PARAM_2 ,DMUS_IO_COMMAND ,DMUS_VARIATIONT_TYPES


DMUS_PLAYMODE_FLAGS

기본적인 연주 모드의 다양한 구조체로 사용된다. 연주 모드는, 뮤직값을 MIDI 노트에 어떻게 전치 할까를 결정한다.

typedef enum enumDMUS_PLAYMODE_FLAGS {
    DMUS_PLAYMODE_KEY_ROOT          = 1,
    DMUS_PLAYMODE_CHORD_ROOT        = 2,
    DMUS_PLAYMODE_SCALE_INTERVALS   = 4,
    DMUS_PLAYMODE_CHORD_INTERVALS   = 8,
    DMUS_PLAYMODE_NONE              = 16,
} DMUS_PLAYMODE_FLAGS;

정수

DMUS_PLAYMODE_KEY_ROOT
키의 루트음상에 전치 한다.
DMUS_PLAYMODE_CHORD_ROOT
코드의 루트음상에 전치 한다.
DMUS_PLAYMODE_SCALE_INTERVALS
스케일 패턴의 스케일의 음정을 사용한다.
DMUS_PLAYMODE_CHORD_INTERVALS
코드 패턴의 코드의 음정을 사용한다.
DMUS_PLAYMODE_NONE
모드 없음. 친파트의 모드를 사용할 필요가 있는 것을 나타낸다.

주의

다음의 정의 끝난 값은, 연주 모드 플래그의 편성을 나타내고 있다.

DMUS_PLAYMODE_ALWAYSPLAY
DMUS_PLAYMODE_SCALE_INTERVALS, DMUS_PLAYMODE_CHORD_INTERVALS, 및 DMUS_PLAYMODE_CHORD_ROOT 의 편성. 코드의 최고음보다 높은 노트를 연주하는 것이 바람직한 경우, 이 모드는, 스케일의 음정을 사용하는 것에 의해 노트의 위치를 검색한다. 즉, 이 모드는 보통의 연주 모드와 선율계의 연주 모드의 편성이며, 보통 모드로 실패 하면 2 번째의 시행이 선율계 모드로 강제적으로 행해진다.
DMUS_PLAYMODE_FIXED
뮤직값을 MIDI 값으로서 해석한다. 이것은 0 으로서 정의되어 그 외의 플래그가 없는 것을 의미한다. 이 플래그는, 드럼, 사운드 이펙트, 및 코드 또는 스케일에 의해 전치 해서는 안 되는, 순서화 된 노트에 대해 사용된다.
DMUS_PLAYMODE_FIXEDTOCHORD
DMUS_PLAYMODE_CHORD_ROOT 와 같다. 뮤직값은 고정의 MIDI 값이지만, 코드의 루트음상에 전치 된다.
DMUS_PLAYMODE_FIXEDTOKEY
DMUS_PLAYMODE_KEY_ROOT 와 같다. 뮤직값은 고정의 MIDI 값이지만, 키의 루트음상에 전치 된다.
DMUS_PLAYMODE_MELODIC
DMUS_PLAYMODE_CHORD_ROOT 와 DMUS_PLAYMODE_SCALE_INTERVALS 의 편성. 코드의 루트음은 사용되지만, 노트는 스케일내의 음정만을 쫓는다. 키의 루트음과 코드의 음정은 무시된다. 이것은, 코드의 루트음을 기준으로 해 연주되는 선율계의 라인에 있어 편리하다.
DMUS_PLAYMODE_NORMALCHORD
DMUS_PLAYMODE_CHORD_ROOT 와 DMUS_PLAYMODE_CHORD_INTERVALS 의 편성. 이것은 일반적인 재생 모드이다. 노트는 코드내의 음정을 쫓는다. 코드는 코드의 루트음에 근거하고 있다. 뮤직값에 스케일 요소가 있는 경우, 다른 음정은 스케일로부터 꺼내져 추가된다. 코드가 뮤직값의 코드 요소와 일치하는 음정을 가지고 있지 않은 경우, 노트는 무음이다.
DMUS_PLAYMODE_PEDALPOINT
DMUS_PLAYMODE_KEY_ROOT 와 DMUS_PLAYMODE_SCALE_INTERVALS 의 편성. 키의 루트음은 사용되지만, 노트는 스케일내의 음정만을 쫓는다. 코드의 루트음과 음정은 무시된다. 이것은, 키의 루트음을 기준으로 해 연주되는 선율계의 라인에 있어 편리하다.
DMUS_PLAYMODE_PEDALPOINTALWAYS
DMUS_PLAYMODE_PEDALPOINT 와 DMUS_PLAYMODE_PEDALPOINTCHORD 의 편성. 가능하면 코드의 음정을 사용한다. 그 이외의 경우는, 스케일의 음정을 사용한다.
DMUS_PLAYMODE_PEDALPOINTCHORD
DMUS_PLAYMODE_MELODIC 와 DMUS_PLAYMODE_NORMALCHORD 의 편성. 키의 루트음은 사용되지만, 노트는 코드내의 음정만을 쫓는다. 코드의 루트음과 스케일의 음정은 완전히 무시된다. 이것은, 키의 루트음을 기준으로 해 연주되는 코드계의 라인에 있어 편리하다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::MIDIToMusic ,IDirectMusicPerformance8::MusicToMIDI ,DMUS_NOTE_PMSG ,DMUS_IO_STYLENOTE ,DMUS_IO_STYLEPART ,뮤직값과 MIDI 노트


DMUS_PMSGF_FLAGS

DMUS_PMSG 구조체의 dwFlags 멤버로 사용된다.

typedef enum enumDMUS_PMSGF_FLAGS {
    DMUS_PMSGF_REFTIME        = 1,
    DMUS_PMSGF_MUSICTIME      = 2,
    DMUS_PMSGF_TOOL_IMMEDIATE = 4,
    DMUS_PMSGF_TOOL_QUEUE     = 8,
    DMUS_PMSGF_TOOL_ATTIME    = 0x10,
    DMUS_PMSGF_TOOL_FLUSH     = 0x20,
    DMUS_PMSGF_LOCKTOREFTIME  = 0x40,
    DMUS_PMSGF_DX8            = 0x80
} DMUS_PMSGF_FLAGS;

정수

DMUS_PMSGF_REFTIME
rtTime 멤버는 유효하다.
DMUS_PMSGF_MUSICTIME
mtTime 멤버는 유효하다.
DMUS_PMSGF_TOOL_IMMEDIATE
타임 스탬프 에 관계없이, 메세지를 즉석에서 처리해야 한다.
DMUS_PMSGF_TOOL_QUEUE
포토의 지연 시간을 고려해, 타임 스탬프의 직전에 메세지를 처리해야 한다.
DMUS_PMSGF_TOOL_ATTIME
타임 스탬프의 시점에서 메세지를 처리해야 한다.
DMUS_PMSGF_TOOL_FLUSH
메세지를 플래시 (해방) 해야 한다.
DMUS_PMSGF_LOCKTOREFTIME
템포가 변경되어도 rtTime 의 값을 덧쓰기할 수 없다.
DMUS_PMSGF_DX8
메세지는, DirectX 8.0 보다 전의 버젼에 존재하지 않는, 유효한 멤버를 가지고 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::SendPMsg ,IDirectMusicTool8::GetMsgDeliveryType


DMUS_PMSGT_TYPES

DMUS_PMSG 구조체의 dwType 멤버로 사용되어 메세지의 타입을 식별한다.

typedef enum enumDMUS_PMSGT_TYPES {
    DMUS_PMSGT_MIDI             = 0,
    DMUS_PMSGT_NOTE             = 1,
    DMUS_PMSGT_SYSEX            = 2,
    DMUS_PMSGT_NOTIFICATION     = 3,
    DMUS_PMSGT_TEMPO            = 4,
    DMUS_PMSGT_CURVE            = 5,
    DMUS_PMSGT_TIMESIG          = 6,
    DMUS_PMSGT_PATCH            = 7,
    DMUS_PMSGT_TRANSPOSE        = 8,
    DMUS_PMSGT_CHANNEL_PRIORITY = 9,
    DMUS_PMSGT_STOP             = 10,
    DMUS_PMSGT_DIRTY            = 11,
    DMUS_PMSGT_WAVE             = 12,
    DMUS_PMSGT_LYRIC            = 13,
    DMUS_PMSGT_SCRIPTLYRIC      = 14,
    DMUS_PMSGT_USER             = 255
} DMUS_PMSGT_TYPES;

정수

DMUS_PMSGT_MIDI
MIDI 채널 메세지. 「DMUS_MIDI_PMSG 」를 참조할것.
DMUS_PMSGT_NOTE
MIDI 의 노트. 「DMUS_NOTE_PMSG 」를 참조할것.
DMUS_PMSGT_SYSEX
MIDI 시스템에크스크루시브멧세이지. 「DMUS_SYSEX_PMSG 」를 참조할것.
DMUS_PMSGT_NOTIFICATION
통지 메세지. 「DMUS_NOTIFICATION_PMSG 」를 참조할것.
DMUS_PMSGT_TEMPO
템포 메세지. 「DMUS_TEMPO_PMSG 」를 참조할것.
DMUS_PMSGT_CURVE
컨트롤 체인지와 핏치벤드카브. 「DMUS_CURVE_PMSG 」를 참조할것.
DMUS_PMSGT_TIMESIG
박자 기호. 「DMUS_TIMESIG_PMSG 」를 참조할것.
DMUS_PMSGT_PATCH
패치의 변경. 「DMUS_PATCH_PMSG 」를 참조할것.
DMUS_PMSGT_TRANSPOSE
전조. 「DMUS_TRANSPOSE_PMSG 」를 참조할것.
DMUS_PMSGT_CHANNEL_PRIORITY
채널 우선 순위 변경. 「DMUS_CHANNEL_PRIORITY_PMSG 」를 참조할것.
DMUS_PMSGT_STOP
정지 메세지. 「DMUS_PMSG 」를 참조할것.
DMUS_PMSGT_DIRTY
제어 세그먼트(segment)가 시작 또는 종료했다. 「DMUS_PMSG 」를 참조할것.
DMUS_PMSGT_WAVE
웨이브 연주용의 제어 정보. 「DMUS_WAVE_PMSG 」를 참조할것.
DMUS_PMSGT_LYRIC
가사 메세지. 「DMUS_LYRIC_PMSG 」를 참조할것.
DMUS_PMSGT_SCRIPTLYRIC
스크립트로부터 송신되는 가사 메세지. 「DMUS_LYRIC_PMSG 」를 참조할것.
DMUS_PMSGT_USER
유저 정의 메세지.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_SEGF_FLAGS

IDirectMusicPerformance8 의 다양한 메소드에게 건네져 세그먼트(segment)에 대한 액션의 타이밍 및 그 외의 요소를 제어한다.

typedef enum enumDMUS_SEGF_FLAGS {
    DMUS_SEGF_REFTIME             = 1<<6,
    DMUS_SEGF_SECONDARY           = 1<<7,
    DMUS_SEGF_QUEUE               = 1<<8,
    DMUS_SEGF_CONTROL             = 1<<9,
    DMUS_SEGF_AFTERPREPARETIME    = 1<<10,
    DMUS_SEGF_GRID                = 1<<11,
    DMUS_SEGF_BEAT                = 1<<12,
    DMUS_SEGF_MEASURE             = 1<<13,
    DMUS_SEGF_DEFAULT             = 1<<14,
    DMUS_SEGF_NOINVALIDATE        = 1<<15,
    DMUS_SEGF_ALIGN               = 1<<16,
    DMUS_SEGF_VALID_START_BEAT    = 1<<17,
    DMUS_SEGF_VALID_START_GRID    = 1<<18,
    DMUS_SEGF_VALID_START_TICK    = 1<<19,
    DMUS_SEGF_AUTOTRANSITION      = 1<<20,
    DMUS_SEGF_AFTERQUEUETIME      = 1<<21,
    DMUS_SEGF_AFTERLATENCYTIME    = 1<<22,
    DMUS_SEGF_SEGMENTEND          = 1<<23,
    DMUS_SEGF_MARKER              = 1<<24,
    DMUS_SEGF_TIMESIG_ALWAYS      = 1<<25,
    DMUS_SEGF_USE_AUDIOPATH       = 1<<26,
    DMUS_SEGF_VALID_START_MEASURE = 1<<27
} DMUS_SEGF_FLAGS;

정수

DMUS_SEGF_REFTIME
타임 파라미터는 기준 타임에 나타내진다.
DMUS_SEGF_SECONDARY
세칸다리세그먼트.
DMUS_SEGF_QUEUE
프라이머리 세그먼트(segment) 큐의 마지막에 둔다. 프라이머리 세그먼트(segment) 에 대해서만 유효하다.
DMUS_SEGF_CONTROL
제어 세그먼트(segment)로서 연주한다. 세칸다리세그먼트 에 대해서만 유효하다. 「주의」를 참조할것.
DMUS_SEGF_AFTERPREPARETIME
준비 시간의 뒤에 연주한다. 「IDirectMusicPerformance8::GetPrepareTime 」를 참조할것.
DMUS_SEGF_GRID
구라두 경계에서 연주한다.
DMUS_SEGF_BEAT
박의 경계에서 연주한다.
DMUS_SEGF_MEASURE
소절 경계에서 연주한다.
DMUS_SEGF_DEFAULT
세그먼트(segment)의 디폴트의 경계를 사용한다.
DMUS_SEGF_NOINVALIDATE
프라이머리 세그먼트(segment) 또는 제어 세그먼트(segment)에 대해, 이 플래그를 IDirectMusicPerformance8::PlaySegment 또는 IDirectMusicPerformance8::PlaySegmentEx 로 설정 하면, 새로운 세그먼트(segment)로 무효화가 발생하지 않는다. 이 플래그가 없으면 무효화가 발생해, 연주중의 커브나 노트가 중단되어 리셋 된다. 이 플래그는 DMUS_SEGF_AFTERPREPARETIME 와 조합하지 않으면 안 된다. 그렇게 하는 것에 의해, 새로운 세그먼트(segment)내의 노트는, 낡은 세그먼트(segment)가 연주하는 노트에 거듭해 연주하지 않는다.
DMUS_SEGF_ALIGN
세그먼트(segment)의 시작을, 소절이나 박 등, 이미 지난 경계에 가지런히 할 수가 있다. 이것을 실행하려면, 세그먼트(segment)내에서 다음의 경계의 앞에, 유효한 시작 포인트가 있을 필요가 있다. 시작 포인트는 세그먼트(segment)내에 정의할 수 있다. 또, DMUS_SEGF_VALID_START_* 플래그의 1 개를 사용해, 유효한 시작 포인트의 세분도를 정의할 수 있다. DMUS_SEGF_VALID_START_* 플래그는, 세그먼트(segment)내에 유효한 시작 포인트가 정의되어 있지 않은 경우에게만 유효하다.
DMUS_SEGF_VALID_START_BEAT
임의의 박으로 시작 할 수 있다. DMUS_SEGF_ALIGN 와 조합해 사용된다.
DMUS_SEGF_VALID_START_GRID
임의의 구라두로 시작 할 수 있다. DMUS_SEGF_ALIGN 와 조합해 사용된다.
DMUS_SEGF_VALID_START_TICK
임의의 타임에 시작 할 수 있다. DMUS_SEGF_ALIGN 와 조합해 사용된다.
DMUS_SEGF_AUTOTRANSITION
트란지션텐프레이트를 사용해, 트란지션세그먼트를 어레인지 및 연주한다.
DMUS_SEGF_AFTERQUEUETIME
큐 시간의 뒤에 연주한다. 이것은 프라이머리 세그먼트(segment)의 디폴트이다. DMUS_SEGF_AFTERPREPARETIME 도 설정되어 있는 경우는 무시된다.
DMUS_SEGF_AFTERLATENCYTIME
지연 시간의 뒤에 연주한다. 이것은 모든 세그먼트(segment)에 들어맞으므로, 이 플래그는 현시점에서는 아무 효과도 없다.
DMUS_SEGF_SEGMENTEND
시작 타임에 연주중의 프라이머리 세그먼트(segment)의 최후로 연주한다. 현재 연주중의 프라이머리 세그먼트(segment) 후에 이미 삽입되고 있는 세그먼트(segment)는, 플래시 (해방) 된다. 프라이머리 세그먼트(segment)가 연주되어 있지 않은 경우는, 그 외의 해결 플래그를 사용한다.
DMUS_SEGF_MARKER
프라이머리 세그먼트(segment)내의 다음의 마커로 연주한다. 마커가 존재하지 않는 경우는, 그 외의 해결 플래그를 사용한다.
DMUS_SEGF_TIMESIG_ALWAYS
시작 타임을 현재의 박자 기호에 가지런히 한다. 프라이머리 세그먼트(segment)가 없는 경우도 이와 같이 한다.
DMUS_SEGF_USE_AUDIOPATH
세그먼트(segment)에 파묻힌 오디오 패스를 사용한다. 세그먼트(segment)가 올바르게 연주되도록(듯이), 밴드의 자동 다운로드를 유효하게 할 필요가 있다.
DMUS_SEGF_VALID_START_MEASURE
소절의 선두로부터 시작 할 수 있다. DMUS_SEGF_ALIGN 와 조합해 사용된다.

주의

프라이머리 세그먼트(segment)는 디폴트의 제어 세그먼트(segment)이다. DMUS_SEGF_CONTROL 플래그를 사용해, 세칸다리세그먼트를 제어 세그먼트(segment)로 할 수 있다. DMUS_SEGF_CONTROL 플래그를 설정 하면, DMUS_SEGF_SECONDARY 가 상정된다. 상세한 것에 대하여는, 「제어 세그먼트(segment)」를 참조할것.

다음의 각 그룹중에서 2 개 이상의 플래그를 지정해선 안 된다.

경계
이 플래그는, 큐에 있는 세그먼트(segment)의 시작 포인트가 위치하는 현재 연주중의 프라이머리 세그먼트(segment)의 포인트를 제어한다. DMUS_SEGF_MARKER 와 조합할 수가 있다. 이 경우, 경계 플래그는 프라이머리 세그먼트(segment)내에 마커가 존재하지 않는 경우에게만 사용된다.

DMUS_SEGF_BEAT
DMUS_SEGF_DEFAULT
DMUS_SEGF_GRID
DMUS_SEGF_MEASURE
DMUS_SEGF_QUEUE
DMUS_SEGF_SEGMENTEND

정렬
이 플래그는, 큐에 있는 세그먼트(segment)의 세그먼트(segment) 시작 타임을 제어한다. 이 시점에서, 연주 시간은 과거의 것이 된다. DMUS_SEGF_ALIGN 와 조합할 필요가 있다.

DMUS_SEGF_VALID_START_BEAT
DMUS_SEGF_VALID_START_GRID
DMUS_SEGF_VALID_START_MEASURE
DMUS_SEGF_VALID_START_TICK

각 그룹의 플래그를 1 개씩 조합하는 것은 가능하다. 예를 들어, DMUS_SEGF_MEASURE 에 DMUS_SEGF_ALIGN 와 DMUS_SEGF_VALID_START_BEAT 를 조합하면(자), 큐에 있는 세그먼트(segment)의 시작 포인트가 현재의 프라이머리 세그먼트(segment)의 소절 경계에 놓여진다. 이 경계를 이미 지나고 있는 경우, 큐에 놓여져 있는 세그먼트(segment)는, 지난 시간에 가지런히 할 수 있지 않은 세그먼트(segment)내의 다음의 박의 경계로부터 연주를 시작 한다. 상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것.

동작환경

헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance8::Invalidate ,IDirectMusicPerformance8::PlaySegment ,IDirectMusicPerformance8::PlaySegmentEx ,IDirectMusicPerformance8::Stop ,IDirectMusicSegment8::GetDefaultResolution ,IDirectMusicSegment8::SetDefaultResolution ,DMUS_TIME_RESOLVE_FLAGS


DMUS_SHAPET_TYPES

IDirectMusicComposer8::ComposeSegmentFromShape 메소드 및 IDirectMusicComposer8::ComposeTemplateFromShape 메소드의 wShape 파라미터로 사용되어 목적의그룹 레벨 의 패턴을 지정한다.

typedef enum enumDMUS_SHAPET_TYPES {
    DMUS_SHAPET_FALLING  = 0,
    DMUS_SHAPET_LEVEL    = 1,
    DMUS_SHAPET_LOOPABLE = 2,
    DMUS_SHAPET_LOUD     = 3,
    DMUS_SHAPET_QUIET    = 4,
    DMUS_SHAPET_PEAKING  = 5,
    DMUS_SHAPET_RANDOM   = 6,
    DMUS_SHAPET_RISING   = 7,
    DMUS_SHAPET_SONG     = 8
} DMUS_SHAPET_TYPES;

정수

DMUS_SHAPET_FALLING
홈 레벨은 하강한다.
DMUS_SHAPET_LEVEL
홈 레벨은 균등하게 유지된다.
DMUS_SHAPET_LOOPABLE
세그먼트(segment)는 선두에 루프 하도록(듯이) 조정되고 있다.
DMUS_SHAPET_LOUD
홈 레벨은 높다.
DMUS_SHAPET_QUIET
홈 레벨은 낮다.
DMUS_SHAPET_PEAKING
홈 레벨은 피크까지 상승해, 그 후 하강한다.
DMUS_SHAPET_RANDOM
홈 레벨은 랜덤이다.
DMUS_SHAPET_RISING
홈 레벨은 상승한다.
DMUS_SHAPET_SONG
세그먼트(segment)는 노래의 형식이다. 6 ~ 8 소절로부터 완성되는 복수의 락구를 어레인지 해, 정리하는 것에 의해, 홈 레벨에 바리에이션이 있는 바스코라스에페크트가 만들어진다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_STYLET_TYPES

IDirectMusicPatternTrack8::SetPatternByName 메소드 및 IDirectMusicStyle8::EnumPattern 메소드로 사용되어 패턴의 타입을 지정한다.

typedef enum enumDMUS_STYLET_TYPES {
    DMUS_STYLET_PATTERN  = 0,
    DMUS_STYLET_MOTIF    = 1,
    DMUS_STYLET_FRAGMENT = 2,
} DMUS_STYLET_TYPES;

정수

DMUS_STYLET_PATTERN
보통의 패턴.
DMUS_STYLET_MOTIF
모티프 패턴.
DMUS_STYLET_FRAGMENT
이행되어 있지 않다.

동작환경

헤더 : dmusici.h 로 선언.


DMUS_TIME_RESOLVE_FLAGS

DMUS_PMSG 구조체의 dwFlags 멤버 및 IDirectMusicPerformance8::GetResolvedTime 메소드의 dwTimeResolveFlags 파라미터로 사용된다.

typedef enum enumDMUS_TIME_RESOLVE_FLAGS {
    DMUS_TIME_RESOLVE_AFTERPREPARETIME =
            DMUS_SEGF_AFTERPREPARETIME,
    DMUS_TIME_RESOLVE_AFTERQUEUETIME   =
            DMUS_SEGF_AFTERQUEUETIME,
    DMUS_TIME_RESOLVE_AFTERLATENCYTIME =
            DMUS_SEGF_AFTERLATENCYTIME,
    DMUS_TIME_RESOLVE_GRID    = DMUS_SEGF_GRID,
    DMUS_TIME_RESOLVE_BEAT    = DMUS_SEGF_BEAT,
    DMUS_TIME_RESOLVE_MEASURE = DMUS_SEGF_MEASURE
    DMUS_TIME_RESOLVE_MARKER  = DMUS_SEGF_MARKER,
    DMUS_TIME_RESOLVE_SEGMENTEND = DMUS_SEGF_SEGMENTEND,
} DMUS_TIME_RESOLVE_FLAGS;

정수

DMUS_TIME_RESOLVE_AFTERPREPARETIME
준비 시간의 뒤의 타임에 해결한다.
DMUS_TIME_RESOLVE_AFTERQUEUETIME
큐 시간의 뒤의 타임에 해결한다.
DMUS_TIME_RESOLVE_AFTERLATENCYTIME
지연 시간의 뒤의 타임에 해결한다.
DMUS_TIME_RESOLVE_GRID
구라두 경계 위에의 타임에 해결한다.
DMUS_TIME_RESOLVE_BEAT
박경계 위에의 타임에 해결한다.
DMUS_TIME_RESOLVE_MEASURE
소절 경계 위에의 타임에 해결한다.
DMUS_TIME_RESOLVE_MARKER
마커에 해결한다.
DMUS_TIME_RESOLVE_SEGMENTEND
세그먼트(segment)의 마지막에 해결한다.

주의

이러한 플래그는, 대응하는 DMUS_SEGF_FLAGS 와 교환해 사용할 수가 있다.

동작환경

헤더 : dmusici.h 로 선언.

참조

타이밍


DMUS_TRACKF_FLAGS

IDirectMusicTrack8::Play 메소드 및 IDirectMusicTrack8::PlayEx 메소드의 dwFlags 파라미터로 사용된다.

typedef enum enumDMUS_TRACKF_FLAGS {
    DMUS_TRACKF_SEEK       = 1,
    DMUS_TRACKF_LOOP       = 2,
    DMUS_TRACKF_START      = 4,
    DMUS_TRACKF_FLUSH      = 8,
    DMUS_TRACKF_DIRTY      = 0x10,
    DMUS_TRACKF_NOTIFY_OFF = 0x20,
    DMUS_TRACKF_PLAYOFF    = 0x40,
    DMUS_TRACKF_LOOPEND    = 0x80,
    DMUS_TRACKF_STOP       = 0x100,
    DMUS_TRACKF_RECOMPOSE  = 0x200,
    DMUS_TRACKF_CLOCK      = 0x400,
} DMUS_TRACKF_FLAGS;

정수

DMUS_TRACKF_SEEK
IDirectMusicTrack8::Play 는, 시크에 대응해 불려 갔다. 이것은,mtStart 파라미터가 직전의 호출의 mtEnd 와 같지 않아도 상관없는 것을 의미한다.
DMUS_TRACKF_LOOP
루프에 응답해 Play 가 불려 갔다.
DMUS_TRACKF_START
이것이 IDirectMusicTrack8::Play 의 처음의 호출이다. 트럭이 선두로부터 연주되어 있지 않은 경우는, DMUS_TRACKF_SEEK 를 설정할 수도 있다.
DMUS_TRACKF_FLUSH
플래시 (해방)나 무효화에 응답해 Play 가 불려 갔다. 이것은, 이미 연주된 어떠한 것을 재연 상주하도록(듯이) 트럭에 요구한다. 이 경우, DMUS_TRACKF_SEEK 도 설정된다.
DMUS_TRACKF_DIRTY
제어 세그먼트(segment)가 시작 또는 종료했다. mtNext 가 IDirectMusicTrack8::GetParam 또는 IDirectMusicTrack8::GetParamEx 를 호출할 때까지 보통 호출을 기다리고 있는 트럭은, 데이터가 무효가 될 가능성이 있기 (위해)때문에, 대기하지 않고 , 즉석에서 호출을 실시해야 하는 것이다. 제어 세그먼트(segment)의 설정 방법법에 대해서는, 「DMUS_SEGF_FLAGS 」를 참조할것.
DMUS_TRACKF_NOTIFY_OFF
트럭은 통지를 송신하지 않는다.
DMUS_TRACKF_PLAYOFF
트럭은 연주하지 않지만, 계속 통지를 송신할 수 있다.
DMUS_TRACKF_LOOPEND
범위의 최후가 루프의 종료이기도 하다.
DMUS_TRACKF_STOP
범위의 최후가, 이 세그먼트(segment)의 연주의 마지막이기도 하다.
DMUS_TRACKF_RECOMPOSE
각 루프에 대해, 트럭을 재어레인지 한다. 싸인 포스트트럭은, 다른 코드 진행을 사용해 재어레인지 되어 멜로디 편성 트럭은, 다른 멜로디 단편을 사용해 재어레인지 된다.
DMUS_TRACKF_CLOCK
타임 파라미터는 기준 타임에 나타내진다. IDirectMusicTrack8::PlayEx 에 대해서만 유효하다.

주의

반복 (리피트)에 응답해 Play 를 호출했을 경우, DMUS_TRACKF_LOOP 과 DMUS_TRACKF_SEEK 가 설정된다.

무효화를 지원 하려면 , 트럭은 시크를 지원 해야 한다.

동작환경

헤더 : dmplugin.h 로 선언.


DMUS_VARIATIONT_TYPES

DMUS_IO_PARTREF 구조체로 사용되어 시퀀셜 커멘드내에서의 바리에이션의 선택 방법을 지정한다.

typedef enum enumDMUS_VARIATIONT_TYPES
{
    DMUS_VARIATIONT_SEQUENTIAL       = 0,
    DMUS_VARIATIONT_RANDOM           = 1,
    DMUS_VARIATIONT_RANDOM_START     = 2,
    DMUS_VARIATIONT_NO_REPEAT        = 3,
    DMUS_VARIATIONT_RANDOM_ROW       = 4
} DMUS_VARIATIONT_TYPES;

정수

DMUS_VARIATIONT_SEQUENTIAL
일치하는 바리에이션을, 로드 된 순서에 최초부터 연주한다.
DMUS_VARIATIONT_RANDOM
일치하는 바리에이션을 랜덤에 선택한다. 이것은, DirectX 8.0 이전의 버젼의 동작이다.
DMUS_VARIATIONT_RANDOM_START
일치하는 바리에이션을, 로드 된 순서에, 순서내의 랜덤인 포인트로부터 연주한다.
DMUS_VARIATIONT_NO_REPEAT
랜덤에 연주한다. 다만, 바리에이션은 한 번 두개 밖에 연주하지 않는다.
DMUS_VARIATIONT_RANDOM_ROW
랜덤에 연주한다. 모든 것을 연주할 때까지는 바리에이션을 반복하지 않는다.

동작환경

헤더 : dmusicf.h 로 선언.

참조

DMUS_COMMAND_PARAM ,DMUS_COMMAND_PARAM_2 ,DMUS_IO_COMMAND ,DMUS_VARIATIONT_TYPES


DirectMusic 반환값

여기에서는, DirectMusic 의 메소드에 의해 돌려주어질 가능성이 있는 다양한 에러 코드에 대해 간단하게 설명한다. 각 메소드가 돌려줄 가능성이 있는 특정의 코드의 리스트에 대해서는, 개별의 메소드의 설명을 참조할것. 그러한 리스트는 반드시 포괄적인 것이라고는 할 수 없다.

에러 코드는 이하의 주제에 나타나고 있다.

  • DirectMusic 반환값 (값)
  • DirectMusic 반환값 (이름)


DirectMusic 반환값 (값)

다음의 표는, 16 진값으로 저장 되는 DirectMusic 반환값을 나타내고 있다. 설명에 대해서는, 정수를 클릭하는 것.

16 진값 | 정수
0x00000000 | S_OK
0x00000001 | S_FALSE
0x08781091 | DMUS_S_PARTIALLOAD
0x08781092 | DMUS_S_PARTIALDOWNLOAD
0x08781200 | DMUS_S_REQUEUE
0x08781201 | DMUS_S_FREE
0x08781202 | DMUS_S_END
0x08781210 | DMUS_S_STRING_TRUNCATED
0x08781211 | DMUS_S_LAST_TOOL
0x08781212 | DMUS_S_OVER_CHORD
0x08781213 | DMUS_S_UP_OCTAVE
0x08781214 | DMUS_S_DOWN_OCTAVE
0x08781215 | DMUS_S_NOBUFFERCONTROL
0x08781216 | DMUS_S_GARBAGE_COLLECTED
0x80004001 | E_NOTIMPL
0x80004002 | E_NOINTERFACE
0x80004003 | E_POINTER
0x80040110 | CLASS_E_NOAGGREGATION
0x80040110 | CLASS_E_NOAGGREGATION
0x80040154 | REGDB_E_CLASSNOTREG
0x8007000E | E_OUTOFMEMORY
0x80070057 | E_FAIL
0x80070057 | E_INVALIDARG
0x88781101 | DMUS_E_DRIVER_FAILED
0x88781102 | DMUS_E_PORTS_OPEN
0x88781103 | DMUS_E_DEVICE_IN_USE
0x88781104 | DMUS_E_INSUFFICIENTBUFFER
0x88781105 | DMUS_E_BUFFERNOTSET
0x88781106 | DMUS_E_BUFFERNOTAVAILABLE
0x88781108 | DMUS_E_NOTADLSCOL
0x88781109 | DMUS_E_INVALIDOFFSET
0x88781111 | DMUS_E_ALREADY_LOADED
0x88781113 | DMUS_E_INVALIDPOS
0x88781114 | DMUS_E_INVALIDPATCH
0x88781115 | DMUS_E_CANNOTSEEK
0x88781116 | DMUS_E_CANNOTWRITE
0x88781117 | DMUS_E_CHUNKNOTFOUND
0x88781119 | DMUS_E_INVALID_DOWNLOADID
0x88781120 | DMUS_E_NOT_DOWNLOADED_TO_PORT
0x88781121 | DMUS_E_ALREADY_DOWNLOADED
0x88781122 | DMUS_E_UNKNOWNDOWNLOAD
0x88781123 | DMUS_E_SET_UNSUPPORTED
0x88781124 | DMUS_E_GET_UNSUPPORTED
0x88781125 | DMUS_E_NOTMONO
0x88781126 | DMUS_E_BADARTICULATION
0x88781127 | DMUS_E_BADINSTRUMENT
0x88781128 | DMUS_E_BADWAVELINK
0x88781128 | DMUS_E_BUFFER_EMPTY
0x8878112A | DMUS_E_NOTPCM
0x8878112B | DMUS_E_BADWAVE
0x8878112C | DMUS_E_BADOFFSETTABLE
0x8878112D | DMUS_E_UNKNOWN_PROPERTY
0x8878112E | DMUS_E_NOSYNTHSINK
0x8878112F | DMUS_E_ALREADYOPEN
0x88781130 | DMUS_E_ALREADYCLOSED
0x88781131 | DMUS_E_SYNTHNOTCONFIGURED
0x88781132 | DMUS_E_SYNTHACTIVE
0x88781133 | DMUS_E_CANNOTREAD
0x88781134 | DMUS_E_DMUSIC_RELEASED
0x88781136 | DMUS_E_BUFFER_FULL
0x88781137 | DMUS_E_PORT_NOT_CAPTURE
0x88781138 | DMUS_E_PORT_NOT_RENDER
0x88781139 | DMUS_E_DSOUND_NOT_SET
0x8878113A | DMUS_E_ALREADY_ACTIVATED
0x8878113B | DMUS_E_INVALIDBUFFER
0x8878113C | DMUS_E_WAVEFORMATNOTSUPPORTED
0x8878113D | DMUS_E_SYNTHINACTIVE
0x8878113E | DMUS_E_DSOUND_ALREADY_SET
0x8878113F | DMUS_E_INVALID_EVENT
0x88781150 | DMUS_E_UNSUPPORTED_STREAM
0x88781151 | DMUS_E_ALREADY_INITED
0x88781152 | DMUS_E_INVALID_BAND
0x88781155 | DMUS_E_TRACK_HDR_NOT_FIRST_CK
0x88781156 | DMUS_E_TOOL_HDR_NOT_FIRST_CK
0x88781157 | DMUS_E_INVALID_TRACK_HDR
0x88781158 | DMUS_E_INVALID_TOOL_HDR
0x88781159 | DMUS_E_ALL_TOOLS_FAILED
0x88781160 | DMUS_E_ALL_TRACKS_FAILED
0x88781161 | DMUS_E_NOT_FOUND
0x88781162 | DMUS_E_NOT_INIT
0x88781163 | DMUS_E_TYPE_DISABLED
0x88781164 | DMUS_E_TYPE_UNSUPPORTED
0x88781165 | DMUS_E_TIME_PAST
0x88781166 | DMUS_E_TRACK_NOT_FOUND
0x88781167 | DMUS_E_TRACK_NO_CLOCKTIME_SUPPORT
0x88781170 | DMUS_E_NO_MASTER_CLOCK
0x88781170 | DMUS_E_NOARTICULATION
0x88781180 | DMUS_E_LOADER_NOCLASSID
0x88781181 | DMUS_E_LOADER_BADPATH
0x88781182 | DMUS_E_LOADER_FAILEDOPEN
0x88781183 | DMUS_E_LOADER_FORMATNOTSUPPORTED
0x88781184 | DMUS_E_LOADER_FAILEDCREATE
0x88781185 | DMUS_E_LOADER_OBJECTNOTFOUND
0x88781186 | DMUS_E_LOADER_NOFILENAME
0x88781200 | DMUS_E_INVALIDFILE
0x88781201 | DMUS_E_ALREADY_EXISTS
0x88781202 | DMUS_E_OUT_OF_RANGE
0x88781203 | DMUS_E_SEGMENT_INIT_FAILED
0x88781204 | DMUS_E_ALREADY_SENT
0x88781205 | DMUS_E_CANNOT_FREE
0x88781206 | DMUS_E_CANNOT_OPEN_PORT
0x88781207 | DMUS_E_CANNOT_CONVERT
0x88781210 | DMUS_E_DESCEND_CHUNK_FAIL
0x88781211 | DMUS_E_NOT_LOADED
0x88781213 | DMUS_E_SCRIPT_LANGUAGE_INCOMPATIBLE
0x88781214 | DMUS_E_SCRIPT_UNSUPPORTED_VARTYPE
0x88781215 | DMUS_E_SCRIPT_ERROR_IN_SCRIPT
0x88781216 | DMUS_E_SCRIPT_CANTLOAD_OLEAUT32
0x88781217 | DMUS_E_SCRIPT_LOADSCRIPT_ERROR
0x88781218 | DMUS_E_SCRIPT_INVALID_FILE
0x88781219 | DMUS_E_INVALID_SCRIPTTRACK
0x8878121A | DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
0x8878121B | DMUS_E_SCRIPT_ROUTINE_NOT_FOUND
0x8878121C | DMUS_E_SCRIPT_CONTENT_READONLY
0x8878121D | DMUS_E_SCRIPT_NOT_A_REFERENCE
0x8878121E | DMUS_E_SCRIPT_VALUE_NOT_SUPPORTED
0x88781220 | DMUS_E_INVALID_SEGMENTTRIGGERTRACK
0x88781221 | DMUS_E_INVALID_LYRICSTRACK
0x88781222 | DMUS_E_INVALID_PARAMCONTROLTRACK
0x88781223 | DMUS_E_AUDIOVBSCRIPT_SYNTAXERROR
0x88781224 | DMUS_E_AUDIOVBSCRIPT_RUNTIMEERROR
0x88781225 | DMUS_E_AUDIOVBSCRIPT_OPERATIONFAILURE
0x88781226 | DMUS_E_AUDIOPATHS_NOT_VALID
0x88781227 | DMUS_E_AUDIOPATHS_IN_USE
0x88781228 | DMUS_E_NO_AUDIOPATH_CONFIG
0x88781229 | DMUS_E_AUDIOPATH_INACTIVE
0x8878122A | DMUS_E_AUDIOPATH_NOBUFFER
0x8878122B | DMUS_E_AUDIOPATH_NOPORT
0x8878122C | DMUS_E_NO_AUDIOPATH
0x8878122D | DMUS_E_INVALIDCHUNK
0x8878122E | DMUS_E_AUDIOPATH_NOGLOBALFXBUFFER
0x8878122F | DMUS_E_INVALID_CONTAINER_OBJECT


DirectMusic 반환값 (이름)

다음의 리스트는, 모든 DirectMusic 반환값을 나타내고 있다. 값으로부터 정수를 확인하려면 , 「DirectMusic 반환값 (값)」를 참조할것.

CLASS_E_NOAGGREGATION
집합체는 지원 하고 있지 않다. LPUNKNOWN 파라미터를 NULL 로 설정해야 한다.
DMUS_E_ALL_TOOLS_FAILED
그래프 오브젝트는,IStream 오브젝트 데이터로부터 모든 툴을 로드할 수 없었다. 이것은, 스트림내에서 에러가 발생했는지, 툴이 클라이언트상에서 부정하게 등록되어 있는 것이 원인이라고 생각된다.
DMUS_E_ALL_TRACKS_FAILED
세그먼트(segment) 오브젝트는,IStream 오브젝트 데이터로부터 모든 트럭을 로드할 수 없었다. 이것은, 스트림내에서 에러가 발생했는지, 트럭이 클라이언트상에서 부정하게 등록되어 있는 것이 원인이라고 생각된다.
DMUS_E_ALREADY_ACTIVATED
포토는 이미 액티브하게 되고 있어 파라미터는 변경할 수 없다.
DMUS_E_ALREADY_DOWNLOADED
버퍼는 이미 다운로드되고 있다.
DMUS_E_ALREADY_EXISTS
툴은 그래프내에 이미 포함되어 있다. 새로운 인스턴스를 생성 해야 한다.
DMUS_E_ALREADY_INITED
오브젝트는 이미 초기화되고 있다.
DMUS_E_ALREADY_LOADED
DLS 콜렉션은 이미 열려 있다.
DMUS_E_ALREADY_SENT
메세지는 이미 송신되고 있다.
DMUS_E_ALREADYCLOSED
포토는 열려 있지 않다.
DMUS_E_ALREADYOPEN
포토는 이미 열려 있다.
DMUS_E_AUDIOPATH_INACTIVE
오디오 패스가 비액티브하다. 퍼포먼스가 종료하고 있는 것이 원인이라고 생각된다.
DMUS_E_AUDIOPATH_NOBUFFER
요구된 버퍼를 생성 할 수 없기 때문에, 오디오 패스를 생성 할 수 없다.
DMUS_E_AUDIOPATH_NOGLOBALFXBUFFER
존재하지 않는 글로벌 이펙트 버퍼에 송신하는 오디오 패스를 생성 하려고 했다.
DMUS_E_AUDIOPATH_NOPORT
포토 할당이 없기 때문에, 재생에 오디오 패스를 사용할 수 없다.
DMUS_E_AUDIOPATHS_IN_USE
퍼포먼스가 오디오 패스를 셋업 했으므로, 퍼포먼스 채널을 할당할 수가 없다.
DMUS_E_AUDIOPATHS_NOT_VALID
퍼포먼스 채널이 IDirectMusicPerformance8::AssignPChannel 를 사용해 셋업 되었으므로, 퍼포먼스는 오디오 패스를 지원 할 수 없다.
DMUS_E_AUDIOVBSCRIPT_OPERATIONFAILURE
스크립트외의 함수를 실행할 수 없었기 (위해)때문에, AudioVBScript 로 생성 된 스크립트 루틴이 실패했다.
DMUS_E_AUDIOVBSCRIPT_RUNTIMEERROR
정수를 오브젝트에 추가한다, 또는 존재하지 않는 루틴을 호출하려고 하는 등, 무효인 연산이 발생했기 때문에, AudioVBScript 로 생성 된 스크립트 루틴이 실패했다.
DMUS_E_AUDIOVBSCRIPT_SYNTAXERROR
AudioVBScript 로 허가되어 있지 않은 스테이트먼트가 포함되어 있기 (위해)때문에, AudioVBScript 로 생성 된 스크립트 루틴을 읽어낼 수가 없었다.
DMUS_E_BADARTICULATION
DLS 콜렉션내에 무효인 아티큐레이션체크가 있다.
DMUS_E_BADINSTRUMENT
DLS 콜렉션내에 무효인 음색 체크가 있다.
DMUS_E_BADOFFSETTABLE
오프셋(offset) 테이블에 에러가 있다.
DMUS_E_BADWAVE
웨이브 헤더가 망가져 있다.
DMUS_E_BADWAVELINK
DLS 콜렉션내의 웨브린크체크가 무효인 웨이브를 가리키고 있다.
DMUS_E_BUFFER_EMPTY
버퍼내에 데이터가 없다.
DMUS_E_BUFFER_FULL
지정한 바이트수가 최대 버퍼 사이즈를 넘고 있다.
DMUS_E_BUFFERNOTAVAILABLE
이 버퍼는 다운로드에 이용할 수 없다.
DMUS_E_BUFFERNOTSET
데이터용으로 준비된 버퍼가 존재하지 않는다.
DMUS_E_CANNOT_CONVERT
뮤직값과 MIDI 값과의 사이에 요구한 변환은 행해지지 않았다. 이것은 보통, 제공된 DMUS_CHORD_KEY 구조체에 무효인 코드 또는 스케일 패턴이 포함되는 경우에 발생한다.
DMUS_E_CANNOT_FREE
메세지를 할당할 수 있지 않은지, 이미 해방되고 있기 (위해)때문에, 메세지를 해방할 수 없었다.
DMUS_E_CANNOT_OPEN_PORT
디폴트의 시스템 포토를 열 수가 없었다.
DMUS_E_CANNOTREAD
IStream 오브젝트로부터 read를 실시하려 하고 있었을 때에 에러가 발생했다.
DMUS_E_CANNOTSEEK
IStream 오브젝트는 Seek 를 지원 하지 않는다.
DMUS_E_CANNOTWRITE
IStream 오브젝트는 Write 를 지원 하지 않는다.
DMUS_E_CHUNKNOTFOUND
지정된 헤더를 가지는 체크가 발견되지 않았다.
DMUS_E_DESCEND_CHUNK_FAIL
체크내에 흐르려고 했지만 실패했다.
DMUS_E_DEVICE_IN_USE
디바이스는 (아마 DirectMusic 이외의 클라이언트에 의해) 사용중이며, 재차 열 수가 없다.
DMUS_E_DMUSIC_RELEASED
DirectMusic 오브젝트의 마지막 인스턴스가 해방되었기 때문에, 조작을 실행할 수 없다. DirectMusic 오브젝트의 마지막 해방이 끝날 때까지, 포토는 사용할 수 없다.
DMUS_E_DRIVER_FAILED
드라이버 또는 하드웨어에서의 장해의 가능성을 나타내는 예상외의 에러가 디바이스 드라이버로부터 돌려주어졌다.
DMUS_E_DSOUND_ALREADY_SET
DirectSound 오브젝트는 이미 설정되어 있다.
DMUS_E_DSOUND_NOT_SET
DirectSound 오브젝트가 지정되어 있지 않기 때문에, 포토를 생성 할 수 없었다.
DMUS_E_GET_UNSUPPORTED
파라미터의 취득은 지원 하고 있지 않다.
DMUS_E_INSUFFICIENTBUFFER
요구된 조작을 실행하기 위한 버퍼가 충분한 크기는 아니다.
DMUS_E_INVALID_BAND
파일에 유효한 밴드가 포함되지 않았다.
DMUS_E_INVALID_CONTAINER_OBJECT
파일에 유효한 컨테이너 오브젝트가 포함되지 않았다.
DMUS_E_INVALID_DOWNLOADID
다운로드 버퍼의 생성 프로세스로, 무효인 다운로드 식별자가 사용되었다.
DMUS_E_INVALID_EVENT
이벤트는, 유효한 MIDI 메세지는 아닌, 또는 동작 스테이터스를 이용하고 있어 버퍼내에 팩 할 수 없다.
DMUS_E_INVALID_LYRICSTRACK
파일에 포함되는 가사 트럭이 무효이다.
DMUS_E_INVALID_PARAMCONTROLTRACK
파일에 포함되는 파라미터 제어 트럭이 무효이다.
DMUS_E_INVALID_SCRIPTTRACK
파일에 포함되는 스크립트 트럭이 무효이다.
DMUS_E_INVALID_SEGMENTTRIGGERTRACK
파일에 포함되는 세그먼트(segment) 방아쇠 트럭이 무효이다.
DMUS_E_INVALID_TOOL_HDR
IStream 오브젝트의 데이터에는, 무효인 툴 헤더가 포함되어 있기 (위해)때문에, 그래프 오브젝트에 의한 read를 할 수 없다.
DMUS_E_INVALID_TRACK_HDR
IStream 오브젝트의 데이터에는, 무효인 트랙헤더-가 포함되어 있기 (위해)때문에, 세그먼트(segment) 오브젝트에 의한 read를 할 수 없다.
DMUS_E_INVALIDBUFFER
무효인 DirectSound 버퍼가 포토에게 건네졌다.
DMUS_E_INVALIDCHUNK
RIFF 파이르체크로 무효인 데이터가 발견되었다.
DMUS_E_INVALIDFILE
파일이 무효이다.
DMUS_E_INVALIDOFFSET
DLS 콜렉션 파일내의 웨브체크가 올바른 오프셋(offset)상에 없다.
DMUS_E_INVALIDPATCH
콜렉션내의 음색이 패치 번호와 일치하지 않는다.
DMUS_E_INVALIDPOS
DLS 콜렉션으로부터 웨이브 데이터를 읽어들여 안에 에러가 발생했다. 이것은, 부정한 파일인 것을 의미한다.
DMUS_E_LOADER_BADPATH
파일 패스가 무효이다.
DMUS_E_LOADER_FAILEDCREATE
오브젝트가 발견되지 않았다, 또는 생성 할 수 없었다.
DMUS_E_LOADER_FAILEDOPEN
파일이 존재하고 있지 않는가 락 되고 있는 것이 원인으로, 파일을 여는 것에 실패했다.
DMUS_E_LOADER_FORMATNOTSUPPORTED
데이터 포맷이 지원되어 있지 않기 때문에, 오브젝트를 로드할 수 없다.
DMUS_E_LOADER_NOCLASSID
오브젝트 기술에 클래스 식별자가 지정되어 있지 않다.
DMUS_E_LOADER_NOFILENAME
오브젝트 기술에 파일명이 지정되어 있지 않다.
DMUS_E_LOADER_OBJECTNOTFOUND
오브젝트가 발견되지 않았다.
DMUS_E_NO_AUDIOPATH
존재하지 않는 오디오 패스상에서 재생하려고 했다.
DMUS_E_NO_AUDIOPATH_CONFIG
오브젝트에, 매입형의 오디오 패스 구성이 포함되지 않았다.
DMUS_E_NO_MASTER_CLOCK
퍼포먼스내에 master clock가 존재하지 않는다. 반드시 IDirectMusicPerformance8::Init 메소드를 호출하는 것.
DMUS_E_NOARTICULATION
DLS 콜렉션내의 음색으로부터 아티큘레이션이 발견되지 않는다.
DMUS_E_NOSYNTHSINK
세면대가 신디사이저에 접속되어 있지 않다.
DMUS_E_NOT_DOWNLOADED_TO_PORT
오브젝트가 포토상에 없기 때문에, 언로드할 수 없다.
DMUS_E_NOT_FOUND
요구된 항목은 오브젝트에 포함되지 않았다.
DMUS_E_NOT_INIT
필요한 오브젝트는 초기화되어 있지 않은지, 초기화에 실패했다.
DMUS_E_NOT_LOADED
로드되어 있지 않았기 (위해)때문에, 이 오브젝트를 사용할 수 없었다.
DMUS_E_NOTADLSCOL
로드안의 오브젝트는 유효한 DLS 콜렉션은 아니다.
DMUS_E_NOTMONO
웨브체크에는 복수의 인터리브 채널이 있다. DLS 포맷에서는 단청의가 요구된다.
DMUS_E_NOTPCM
웨이브 데이터가 PCM 포맷으로 되어 있지 않다.
DMUS_E_OUT_OF_RANGE
요구된 타임은 세그먼트(segment)의 범위외이다.
DMUS_E_PORT_NOT_CAPTURE
포토는 캡춰 포토는 아니다.
DMUS_E_PORT_NOT_RENDER
포토는 출력 포토는 아니다.
DMUS_E_PORTS_OPEN
시스템내의 임의의 프로세스에 인스턴스화 된 포토가 있을 때는, 요구된 조작을 실행할 수 없다.
DMUS_E_SCRIPT_CANTLOAD_OLEAUT32
Oleaut32.dll 의 로드가 실패했다. ActiveX 스크립팅 언어는 oleaut32.dll 를 사용할 필요가 있다. 이 파일이 존재하지 않는 플랫폼에서 사용할 수 있는 것은, AudioVBScript 언어뿐이다.
DMUS_E_SCRIPT_CONTENT_READONLY
스크립트로 참조되는 컨텐트 또는 스크립트에 파묻히는 컨텐트의 스크립트 변수를 설정할 수 없다.
DMUS_E_SCRIPT_ERROR_IN_SCRIPT
스크립트의 해석중 또는 실행중에 에러가 발생했다.
DMUS_E_SCRIPT_INVALID_FILE
스크립트 파일이 무효이다.
DMUS_E_SCRIPT_LANGUAGE_INCOMPATIBLE
이 스크립트의 언어에 대응한 ActiveX 스크립팅 엔진에는, DirectMusic 와의 호환성이 없다.
DMUS_E_SCRIPT_LOADSCRIPT_ERROR
로드 된 스크립트에 에러가 있다.
DMUS_E_SCRIPT_NOT_A_REFERENCE
오브젝트 타입이 아닌 값에의 참조로 스크립트의 변수를 설정하려고 했다.
DMUS_E_SCRIPT_ROUTINE_NOT_FOUND
스크립트에, 지정된 이름의 루틴이 포함되지 않았다.
DMUS_E_SCRIPT_UNSUPPORTED_VARTYPE
DirectMusic 가 지원 하고 있지 않는 타입을 가지는 변형이 사용되었다.
DMUS_E_SCRIPT_VALUE_NOT_SUPPORTED
디폴트값의 프로퍼티를 지원 하지 않는 오브젝트에의 값으로 스크립트의 변수를 설정하려고 했다.
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
스크립트에, 지정된 이름의 변수가 포함되지 않았다.
DMUS_E_SEGMENT_INIT_FAILED
세그먼트(segment)의 초기화에 실패했다. 메모리로 중대한 문제가 발생했다고 생각된다.
DMUS_E_SET_UNSUPPORTED
파라미터의 설정은 지원 하고 있지 않다.
DMUS_E_SYNTHACTIVE
신디사이저는 이미 액티브하게 되고 있어 파라미터는 변경할 수 없다.
DMUS_E_SYNTHINACTIVE
신디사이저는 액티브하게 되지 않고, 데이터를 처리할 수 없다.
DMUS_E_SYNTHNOTCONFIGURED
신디사이저는 올바르게 구성되어 있지 않은지, 열려 있지 않다.
DMUS_E_TIME_PAST
요구된 타임은 과거의 타임이다.
DMUS_E_TOOL_HDR_NOT_FIRST_CK
스트림 오브젝트의 데이터에는 최초의 체크로서 툴 헤더가 없기 때문에, 그래프 오브젝트에 의한 read를 할 수 없다.
DMUS_E_TRACK_HDR_NOT_FIRST_CK
스트림 오브젝트의 데이터에는 최초의 체크로서 트랙헤더-가 없기 때문에, 세그먼트(segment) 오브젝트에 의한 read를 할 수 없다.
DMUS_E_TRACK_NO_CLOCKTIME_SUPPORT
트럭은, 클락 타임의 재생 또는 파라미터의 취득을 지원 하고 있지 않다.
DMUS_E_TRACK_NOT_FOUND
요구된 타입의 트럭이 없다.
DMUS_E_TYPE_DISABLED
트럭 파라미터는 무효로 되고 있기 (위해)때문에 이용할 수 없다.
DMUS_E_TYPE_UNSUPPORTED
파라미터는 이 트럭상에서 지원되어 있지 않다.
DMUS_E_UNKNOWN_PROPERTY
이 포토에는 프로퍼티 세트나 항목이 이행되어 있지 않다.
DMUS_E_UNKNOWNDOWNLOAD
신디사이저는 이 타입의 다운로드를 지원 하고 있지 않다.
DMUS_E_UNSUPPORTED_STREAM
IStream 오브젝트는, 로드안의 오브젝트가 지원 하고 있는 데이터를 포함하지 않았다.
DMUS_E_WAVEFORMATNOTSUPPORTED
무효인 버퍼 포맷이 신디사이저 세면대에게 건네졌다.
DMUS_S_DOWN_OCTAVE
노트가 1 옥타브 또는 복수 옥타브분 내릴 수 있어 MIDI 값의 범위내에 들어가고 있다.
DMUS_S_END
조작에 성공해, 데이터의 마지막에 달했다.
DMUS_S_FREE
할당할 수 있었던 메모리를 해방해야 한다.
DMUS_S_GARBAGE_COLLECTED
오브젝트가 해방되고 있었기 때문에, 요구된 처리가 실행되지 않았다.
DMUS_S_LAST_TOOL
그래프내에는 더 이상의 툴이 없다.
DMUS_S_NOBUFFERCONTROL
포토로부터의 오디오 출력은, 지정된 DirectSound 버퍼와 같은 디바이스에 전송 되지만, 빵이나 볼륨등의 버퍼 컨트롤은 출력에 영향을 주지 않는다.
DMUS_S_OVER_CHORD
뮤직값이 코드의 최고음보다 높은 위치에 있는 노트를 가지고 있기 (위해)때문에, MIDI 값은 계산되어 있지 않다.
DMUS_S_PARTIALDOWNLOAD
일부의 음색을 포토에 다운로드할 수 없었다.
DMUS_S_PARTIALLOAD
오브젝트는 부분적인 로드 밖에 할 수 없었다. 이것은, 파묻힌 트럭이나 툴등의 일부의 컴퍼넌트가 올바르게 등록되지 않은 경우에 발생하는 일이 있다. 또, 예를 들어, 세그먼트(segment)로 로더의 현재의 검색 디렉토리에 없는 DLS 콜렉션이 사용되고 있는 경우 등, 컨텐트의 일부가 없을 때에 발생하는 경우도 있다.
DMUS_S_REQUEUE
메세지를 다음의 툴에 건네주어야 하는 것이다.
DMUS_S_STRING_TRUNCATED
메소드는 성공했지만, 돌려주어진 캐릭터 라인은 잘라 버릴 수 있었다.
DMUS_S_UP_OCTAVE
노트가 1 옥타브 또는 복수 옥타브 분죠, MIDI 값의 범위내에 들어가고 있다.
E_FAIL
이 메소드는 성공하지 않았다.
E_INVALIDARG
인수가 무효이다. 구조체의 dwSize 멤버를 초기화하는 것을 잊어 이 멤버를 메소드에 건네주었을 경우에 이 에러가 일어나는 것이 많다.
E_NOINTERFACE
이용 가능한 오브젝트 인터페이스가 없다.
E_NOTIMPL
이 메소드는 이행되어 있지 않다. 동작에 필요한 기능을 드라이버가 지원 하고 있지 않기 위해(때문에), 이 메소드가 돌려주어지는 일이 있다.
E_OUTOFMEMORY
메모리 부족을 위해, 태스크를 완료할 수 없다.
E_POINTER
무효인 포인터 (보통은 NULL)가 파라미터로서 건네받았다.
REGDB_E_CLASSNOTREG
오브젝트 클래스가 등록되지 않았다.
S_FALSE
메소드는 성공했지만, 해야 할것이 아무것도 없었다.
S_OK
동작은 완료해, 성공했다.


DirectSound C/C++ 레퍼런스

여기에서는, Microsoft® DirectSound® 어플리케이션 프로그래밍 인터페이스 (API)의 레퍼런스 정보를 기술한다. 여기에서는, DirectSound 가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 다음의 카테고리로 분류된다.

  • DirectSound 인터페이스
  • DirectSound 콜백 함수
  • DirectSound 함수
  • DirectSound 구조체
  • DirectSound 반환값


DirectSound 인터페이스

여기에서는, 다음의 DirectSound 인터페이스의 메소드에 관한 레퍼런스 정보를 기술한다.

  • IDirectSound8
  • IDirectSound3DBuffer8
  • IDirectSound3DListener8
  • IDirectSoundBuffer8
  • IDirectSoundCapture8
  • IDirectSoundCaptureBuffer8
  • IDirectSoundCaptureFXAec8
  • IDirectSoundCaptureFXNoiseSuppress8
  • IDirectSoundFullDuplex8
  • IDirectSoundFXChorus8
  • IDirectSoundFXCompressor8
  • IDirectSoundFXDistortion8
  • IDirectSoundFXEcho8
  • IDirectSoundFXFlanger8
  • IDirectSoundFXGargle8
  • IDirectSoundFXI3DL2Reverb8
  • IDirectSoundFXParamEq8
  • IDirectSoundNotify8
  • IKsPropertySet

DirectX 8.0 으로, 이름에 번호가 붙지 않은 인터페이스를 옮겨놓는 새로운 인터페이스는,IDirectSound8,IDirectSoundBuffer8, 및 IDirectSoundCaptureBuffer8 뿐이다. 이름의 최후가 8 인 그 외의 인터페이스는, 변경이 없는 인터페이스, 또는 번호가 붙지 않은 새로운 인터페이스의 단순한 정의이다. 예를 들어,IDirectSoundCapture8 은 IDirectSoundCapture 와 완전히 같다.

8 으로 끝나는 정의를 가지는 인터페이스는 모두, 정의된 이름으로 설명되고 있다. 코드중에서는, 항상 이 이름을 사용하는 것을 추천 한다. 향후의 버젼에 대해 재컴파일 할 때에, 모든 선언으로 최신의 번호에 치환해, 갱신된 최신 버젼의 인터페이스를 사용할 수 있다.

메소드가 인터페이스 포인터를 파라미터로서 받는 경우는, 낡은 버젼을 받도록(듯이) 메소드로 선언되고 있는 경우에서도, 새로운 버젼을 건네줄 수가 있다. 예를 들어,IDirectSoundBuffer 또는 IDirectSoundBuffer8 에의 포인터를 pDSBufferOriginal 파라미터로서 IDirectSound8::DuplicateSoundBuffer 에 건네줄 수가 있다.

다만, 메소드가 인터페이스를 돌려주는 경우는, 낡은 인터페이스가 돌려주어지므로,QueryInterface 를 사용해 새로운 인터페이스를 취득할 필요가 있다. 예를 들어,IDirectSound8::CreateSoundBuffer 의 ppDSBuffer 는, 인터페이스를 돌려주는 파라미터이다.


IDirectSound8

버퍼 오브젝트의 생성 및 환경의 설정에 사용한다.

IDirectSound 대신에 IDirectSound8 인터페이스가 제공되어 새로운 메소드가 추가된다. 「주의」를 참조할것.

DirectSoundCreate8 또는 DirectSoundFullDuplexCreate8 함수를 사용해 이 인터페이스를 취득하는지,CoCreateInstance 또는 CoCreateInstanceEx 을 사용해 클래스 CLSID_DirectSound8 의 오브젝트를 생성 한다.

IDirectSound8 인터페이스의 메소드는, 다음의 그룹에 정리할 수가 있다.

초기화 | Initialize
 | SetCooperativeLevel
버퍼 생성 | CreateSoundBuffer
 | DuplicateSoundBuffer
디바이스의 능력 | GetCaps
 | VerifyCertification
메모리 메니지먼트 | Compact
스피커의 구성 | GetSpeakerConfig
 | SetSpeakerConfig

모든 COM 인터페이스와 같이,IDirectSound8 인터페이스는 IUuknown 인터페이스 메소드를 계승하고 있다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND8 형은,IDirectSound8 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSound8    *LPDIRECTSOUND8;

주의

CLSID_DirectSound8 클래스의 오브젝트만이, 이 인터페이스를 지원 한다. DirectSoundCreate8 및 DirectSoundFullDuplexCreate8 로 생성 된 DirectSound 오브젝트는, 모두 이 카테고리가 된다. CLSID_DirectSound 클래스의 오브젝트는,DirectSoundCreate 를 사용해 생성 된 모든 오브젝트를 포함해, 이전의 IDirectSound 인터페이스만을 지원 한다.

CLSID_DirectSound8 오브젝트의 동작은, 몇개의 점으로써 CLSID_DirectSound 오브젝트와 다르다. 이러한 차이는,IDirectSound8 인터페이스와 같이,IDirectSound 인터페이스에도 볼 수 있다. 새로운 오브젝트의 동작에 관해서, 다음과 같은 상위가 있다.

  • IDirectSound8::CreateSoundBuffer 에서는, 비단청의 형식의 버퍼로 DSBCAPS_CTRL3D 를 설정할 수 없다. 또, DSBCAPS_CTRL3D 를 DSBCAPS_CTRLPAN 와 조합할 수가 없다.
  • 신규 버퍼 생성의 플래그가 지원 되지 않는다.
  • 생성시에 버퍼에 무음이 설정되지 않는다.
  • IDirectSoundBuffer8 인터페이스에 대해서,CreateSoundBuffer 로 돌려주어지는 IDirectSoundBuffer 인터페이스를 문의할 수가 있다.
  • WAVE_FORMAT_EXTENSIBLE 포맷 태그가 있는 DSBUFFERDESC 구조체의 웨이브 포맷에서는, 그 유효성이 보다 엄밀하게 확인된다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound8::Compact

온보드 사운드 메모리에 미사용 부분이 존재하는 경우, 이것들을 이동해 연속 블록을 형성해, 빈메모리 영역을 최대로 한다.

HRESULT Compact();

파라미터

없음.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED
DSERR_UNINITIALIZED

주의

어플리케이션의 DirectSound 오브젝트는, 적어도 DSSCL_PRIORITY 의 협조 레벨을 갖추지 않으면 안 된다. IDirectSound8::SetCooperativeLevel 를 참조할것.

진행중의 조작이 그 밖에 1 개(살)에서도 존재 하면, 이 메소드는 실패한다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound8::CreateSoundBuffer

샘플링 오디오의 순서를 보관 유지하기 위한 DirectSoundBuffer 오브젝트를 생성 한다.

HRESULT CreateSoundBuffer(
  LPCDSBUFFERDESC pcDSBufferDesc,
  LPDIRECTSOUNDBUFFER * ppDSBuffer,
  LPUNKNOWN pUnkOuter
);

파라미터

pcDSBufferDesc
생성 하는 사운드 버퍼를 기술하는 DSBUFFERDESC 구조체의 주소.
ppDSBuffer
새로운 버퍼 오브젝트의 IDirectSoundBuffer 인터페이스를 받는 변수의 주소. IDirectSoundBuffer8 를 취득하려면 ,QueryInterface 을 사용한다. IDirectSoundBuffer8 는 프라이머리 버퍼에는 이용할 수 없다. 「주의」를 참조할것.
pUnkOuter
COM 집성체에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소. NULL 가 아니면 안된다.

반환값

성공했을 경우는 DS_OK 를 돌려준다. 또, 요구한 3D 알고리즘을 이용하지 못하고, 스테레오 빵이 대용되었을 경우는, DS_NO_VIRTUALIZATION 를 돌려준다. DSBUFFERDESC 의 guid3DAlgorithm 멤버의 기술을 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_ALLOCATED
DSERR_CONTROLUNAVAIL
DSERR_BADFORMAT
DSERR_BUFFERTOOSMALL
DSERR_DS8_REQUIRED
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

주의

DirectSound 는, 버퍼의 내용을 초기화하지 않는다. 따라서, 어플리케이션에서는, 버퍼에 무음이 포함되어 있으면(자) 상정해서는 안 된다.

어플리케이션이 multi-thread화 되고 있는 경우, 버퍼를 생성 하는 thread는, 버퍼의 유효기간을 통해 존재하고 있지 않으면 안 된다. WDM 드라이버로 생성 된 버퍼에서는, thread가 종료 하면 재생이 정지한다.

하드웨어 가속화를 이용할 수 없는 시스템으로 DSBCAPS_LOCHARDWARE 플래그를 사용해 버퍼를 생성 하려고 하면(자), 메소드는 실패해, operating system에 응해 DSERR_CONTROLUNAVAIL 또는 DSERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

세칸다리밧파의 생성,IDirectSound8::DuplicateSoundBuffer


IDirectSound8::DuplicateSoundBuffer

새로운 DirectSoundBuffer 오브젝트를 생성 한다. 이 오브젝트는, 오리지날의 버퍼의 메모리를 복제 또는 공유한다.

HRESULT DuplicateSoundBuffer(
  LPDIRECTSOUNDBUFFER pDSBufferOriginal,
  LPDIRECTSOUNDBUFFER * ppDSBufferDuplicate
);

파라미터

pDSBufferOriginal
복제하는 버퍼의 IDirectSoundBuffer 또는 IDirectSoundBuffer8 인터페이스의 주소.
ppDSBufferDuplicate
새로운 버퍼의 IDirectSoundBuffer 인터페이스 포인터를 받는 변수의 주소. IDirectSoundBuffer8 인터페이스는 복제 버퍼로부터는 취득할 수 없다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_ALLOCATED
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

주의

이 메소드는, DSBCAPS_CTRLFX 플래그를 사용해 생성 한 버퍼에는 무효이다.

복제 직후의 버퍼는, 오리지날 버퍼와 같은 파라미터를 가진다. 다만, 어플리케이션은 각 버퍼의 파라미터를 개별적으로 변경할 수 있어 각 버퍼는 차이에 영향을 미치는 일 없이 재생과 정지를 실시할 수 있다.

후에 남은 참조측 오브젝트가 해방되면(자), 버퍼 메모리는 해방된다.

복제 버퍼는 같은 메모리를 공유하는 경우도 있지만, 항상 그렇다라고는 한정되지 않는다. 버퍼에 저장 된 데이터의 변경은, 반드시 복제에 반영되는 것은 아니다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound8::CreateSoundBuffer


IDirectSound8::GetCaps

DirectSound 오브젝트로서 나타내지고 있는 하드웨어 디바이스의 능력을 취득한다.

HRESULT GetCaps(
  LPDSCAPS pDSCaps
);

파라미터

pDSCaps
사운드 디바이스의 능력을 받는 DSCAPS 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

주의

DSCAPS 구조체에 보관 유지되고 있는 정보는, 하드웨어 믹싱 채널의 수, 온보드 사운드 메모리의 용량 등, 사운드 디바이스의 최대 능력과 현재 사용 가능한 능력을 기술한다. 이러한 정보를 사용해 성능을 조정해, 리소스의 할당을 최적화할 수 있다.

리소스의 공유가 전제가 되고 있기 (위해)때문에, 어느 분야에서 최대의 능력을 이용 하면, 다른 분야가 그 영향을 받는 일이 있다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound8::GetSpeakerConfig

스피커의 구성을 취득한다.

HRESULT GetSpeakerConfig(
  LPDWORD pdwSpeakerConfig
);

파라미터

pdwSpeakerConfig
이 DirectSound 오브젝트용의 스피커의 구성에의 포인터. 스피커의 구성은 다음의 값의 어느쪽이든으로 지정된다.
DSSPEAKER_5POINT1
오디오는 사브워파 첨부의 환경 스피커의 스피커 배치로부터 출력된다.
DSSPEAKER_HEADPHONE
오디오는 헤드폰으로부터 출력된다.
DSSPEAKER_MONO
오디오는 단청의 스피커로부터 출력된다.
DSSPEAKER_QUAD
오디오는 4 채널 스테레오 스피커로부터 출력된다.
DSSPEAKER_STEREO
오디오는 스테레오 스피커로부터 출력된다 (디폴트값).
DSSPEAKER_SURROUND
오디오는 환경 스피커로부터 출력된다.
DSSPEAKER_STEREO 는, 다음의 값의 어느쪽이든조합해 사용할 수 있다.
DSSPEAKER_GEOMETRY_WIDE
2 개의 스피커는 청취자를 중심으로서 20 번의 각도에 놓여져 있다.
DSSPEAKER_GEOMETRY_NARROW
2 개의 스피커는 청취자를 중심으로서 10 번의 각도에 놓여져 있다.
DSSPEAKER_GEOMETRY_MIN
2 개의 스피커는 청취자를 중심으로서 5 번의 각도에 놓여져 있다.
DSSPEAKER_GEOMETRY_MAX
2 개의 스피커는 청취자를 중심으로서 180 번의 각도에 놓여져 있다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

주의

pdwSpeakerConfig 에 돌려주어지는 값은, 구성과 지오메트리 정보의 양쪽 모두를 보관 유지하는 팩 DWORD 가 되는 일이 있다. DWORD 를 unpack 하려면 , 다음의 예의 같게 DSSPEAKER_CONFIG 와 DSSPEAKER_GEOMETRY 의 각 매크로를 사용한다.

if (DSSPEAKER_CONFIG(dwSpeakerConfig) == DSSPEAKER_STEREO)
    {
    if (DSSPEAKER_GEOMETRY(dwSpeakerConfig) ==
                      DSSPEAKER_GEOMETRY_WIDE)
       {...}
    }

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound8::SetSpeakerConfig ,스피커의 구성


IDirectSound8::Initialize

CoCreateInstance 함수를 사용해 생성 된 DirectSound 오브젝트를 초기화한다.

HRESULT Initialize(
  LPCGUID pcGuidDevice
);

파라미터

pcGuidDevice
DirectSound 오브젝트에 할당할 수 있는 사운드 드라이버를 지정하는 GUID (글로벌 유니크 식별자) 주소. 프라이머리 사운드 드라이버를 선택하려면 , NULL 를 건네준다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_ALREADYINITIALIZED
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_NODRIVER

주의

이 메소드는 COM 프로토콜에 준거해 제공되고 있다. DirectSoundCreate8 함수를 사용해 DirectSound 오브젝트를 생성 했을 경우, 이 메소드는 DSERR_ALREADYINITIALIZED 를 돌려준다. CoCreateInstance 를 사용해 DirectSound 오브젝트를 생성 할 경우에,IDirectSound8::Initialize 를 호출하지 않으면 그 후에 호출한 모든 메소드는 DSERR_UNINITIALIZED 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound8::SetCooperativeLevel

이 사운드 디바이스의 어플리케이션 협조 레벨을 설정한다.

HRESULT SetCooperativeLevel(
  HWND hwnd,
  DWORD dwLevel
);

파라미터

hwnd
어플리케이션 윈도우에의 핸들.
dwLevel
요구되는 우선 레벨. 다음의 값의 어느쪽이든을 지정한다.
DSSCL_EXCLUSIVE
DirectX 8.0 이후의 버젼에서는, DSSCL_PRIORITY 와 같은 효과를 가진다. 그 이전의 버젼에서는, 어플리케이션을 배타 레벨로 설정한다. 즉, 입력초점이 놓여져 있는 어플리케이션만이 소리를 낼 수 있다 (DSBCAPS_GLOBALFOCUS 플래그가 설정되어 있는 어플리케이션의 사운드는 무음이 된다). 이 레벨로 설정된 어플리케이션은, DSSCL_PRIORITY 레벨의 모든 특권도 갖추고 있다. 어플리케이션이 입력초점을 얻으면(자), DirectSound 는 전회 IDirectSoundBuffer8::SetFormat 메소드를 호출했을 때에 지정된 하드웨어 포맷을 복원한다
DSSCL_NORMAL
어플리케이션을 완전하게 협조 가능한 스테이터스로 설정한다. 이 레벨에서는 가장 순조로운 multitasking와 리소스 공유의 동작을 얻을 수 있지만, 프라이머리 버퍼의 포맷의 변경은 실시하지 못하고, 출력도 디폴트의 8 비트 포맷으로 한정된다.
DSSCL_PRIORITY
어플리케이션을 우선 레벨로 설정한다. 이 협조 레벨로 설정된 어플리케이션은 IDirectSoundBuffer8::SetFormat 와 IDirectSound8::Compact 의 각 메소드를 호출할 수 있다.
DSSCL_WRITEPRIMARY
이것은 최상정도의 우선 레벨이다. 이 어플리케이션은프라이머리 사운드 버퍼에의 기입해 액세스를 보관 유지한다. 세칸다리사운드밧파는 모두 재생할 수 없다. 디바이스가 DirectSound 드라이버로 에뮤레이트 되고 있는 경우, 즉 IDirectSound8::GetCaps 메소드가 DSCAPS 구조 체내에 DSCAPS_EMULDRIVER 플래그를 돌려주었을 경우, 이 레벨은 설정할 수 없다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

주의

어플리케이션은 버퍼를 재생하기 전에, 이 메소드를 호출해 협조 레벨을 설정해야 한다. 추천 되는 협조 레벨은 DSSCL_PRIORITY 이다. 상세한 것에 대하여는, 「협조 레벨」을 참조할것.

락 된 버퍼가 있는 경우는, 이 메소드를 사용해서는 안 된다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound8::SetSpeakerConfig

DirectSound 오브젝트의 스피커의 구성을 지정한다.

어플리케이션으로 이 메소드를 사용하는 것은 권유받지 않는다. 「스피커의 구성」을 참조할것.

HRESULT SetSpeakerConfig(
  DWORD dwSpeakerConfig
);

파라미터

dwSpeakerConfig
DirectSound 오브젝트의 스피커의 구성. 이 파라미터에, 다음의 값의 어느쪽이든을 지정한다.
DSSPEAKER_5POINT1
오디오는 사브워파 첨부의 환경 스피커의 스피커 배치로부터 출력된다.
DSSPEAKER_HEADPHONE
스피커는 헤드폰이다.
DSSPEAKER_MONO
스피커는 단청의이다.
DSSPEAKER_QUAD
스피커는 4 채널이다.
DSSPEAKER_STEREO
스피커는 스테레오이다 (디폴트값).
DSSPEAKER_SURROUND
스피커는 환경 사운드이다.
DSSPEAKER_STEREO 는, 다음의 값의 어느쪽이든조합해 사용할 수 있다.
DSSPEAKER_GEOMETRY_WIDE
2 개의 스피커는 청취자를 중심으로서 20 번의 각도에 놓여져 있다.
DSSPEAKER_GEOMETRY_NARROW
2 개의 스피커는 청취자를 중심으로서 10 번의 각도에 놓여져 있다.
DSSPEAKER_GEOMETRY_MIN
2 개의 스피커는 청취자를 중심으로서 5 번의 각도에 놓여져 있다.
DSSPEAKER_GEOMETRY_MAX
2 개의 스피커는 청취자를 중심으로서 180 번의 각도에 놓여져 있다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

주의

지오메트리값을 사용하려면 , DSSPEAKER_STEREO 플래그와 조합한 다음 DWORD 에 팩 해야 한다. 다음의 C++ 에 의한 예에 나타내도록(듯이),DSSPEAKER_COMBINED 매크로를 사용해 이 팩을 실시한다.

lpds->SetSpeakerConfig(DSSPEAKER_COMBINED(
    DSSPEAKER_STEREO, DSSPEAKER_GEOMETRY_WIDE));

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound8::GetSpeakerConfig


IDirectSound8::VerifyCertification

DirectSound 디바이스가 DirectX 로 인증되고 있는지 어떤지를 확인한다.

VerifyCertification(
  LPDWORD pdwCertified
);

파라미터

pdwCertified
다음의 몇개의 값을 받는 DWORD 변수의 주소.
DS_CERTIFIED
드라이버는 DirectSound 로 인증되고 있다.
DS_UNCERTIFIED
드라이버는 DirectSound 로 인증되어 있지 않다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED

주의

에뮤레이트 되는 디바이스에서는, 이 메소드는 DSERR_UNSUPPORTED 를 돌려준다. 에뮤레이트 되는 디바이스는,DSCAPS 의 dwFlags 멤버의 DSCAPS_EMULDRIVER 플래그로 식별된다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound3DBuffer8

3D 공간에 있어서의 사운드 버퍼의 위치, 향해, 및 환경을 기술하는 파라미터의 취득과 설정에 사용한다.

IDirectSound3DBuffer8 는,IDirectSoundBuffer 의 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

IDirectSound3DBuffer8 인터페이스는,IDirectSoundBuffer8:: QueryInterface 메소드를 사용해 IDirectSoundBuffer8 인터페이스로부터 취득한다. 오디오 패스로부터 취득할 수도 있다.

IDirectSound3DBuffer8 인터페이스의 메소드는, 다음의 그룹에 정리할 수가 있다.

배치 파라미터 조작 | GetAllParameters
 | SetAllParameters
거리 | GetMaxDistance
 | GetMinDistance
 | SetMaxDistance
 | SetMinDistance
조작 모드 | GetMode
 | SetMode
위치 | GetPosition
 | SetPosition
사운드 프로젝션 콘 | GetConeAngles
 | GetConeOrientation
 | GetConeOutsideVolume
 | SetConeAngles
 | SetConeOrientation
 | SetConeOutsideVolume
속도 | GetVelocity
 | SetVelocity

모든 COM 인터페이스와 같이,IDirectSound3DBuffer8 인터페이스는 IUuknown 인터페이스 메소드를 계승하고 있다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND3DBUFFER 형은,IDirectSound3DBuffer8 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSound3DBuffer    *LPDIRECTSOUND3DBUFFER;

동작환경

헤더 : dsound.h 로 선언.

참조

3D 버퍼 오브젝트의 취득,오디오 패스로부터의 오브젝트의 취득


IDirectSound3DBuffer8::GetAllParameters

지정한 시점에서의 사운드 버퍼의 3D 특성에 관한 정보를 취득한다.

HRESULT GetAllParameters(
  LPDS3DBUFFER pDs3dBuffer
);

파라미터

pDs3dBuffer
DS3DBUFFER 구조체의 주소. 이 구조체는 사운드 버퍼의 3D 특성에 관한 정보를 받는다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound3DBuffer8::GetConeAngles

사운드 버퍼의 사운드 프로젝션 콘의 내부 각도와 외부 각도를 취득한다.

HRESULT GetConeAngles(
  LPDWORD pdwInsideConeAngle,
  LPDWORD pdwOutsideConeAngle
);

파라미터

pdwInsideConeAngle
사운드 프로젝션 콘의 내부 각도를 받는 변수의 주소 (번단위). 이 각도의 안쪽에서는, 사운드는 보통의 볼륨이다.
pdwOutsideConeAngle
사운드 프로젝션 콘의 외부 각도를 받는 변수의 주소 (번단위). 이 각도의 외측에서는, 사운드는 외부 볼륨이다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

최소, 최대, 디폴트의 각 콘 각도는 dsound.h 내에서 각각 DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, DS3D_DEFAULTCONEANGLE 로서 정의된다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::GetConeOutsideVolume ,IDirectSound3DBuffer8::SetConeOutsideVolume ,IDirectSound3DBuffer8::GetConeOrientation ,IDirectSound3DBuffer8::SetConeOrientation


IDirectSound3DBuffer8::GetConeOrientation

사운드 버퍼의 사운드 프로젝션 콘의 방향을 취득한다.

HRESULT GetConeOrientation(
  D3DVECTOR * pvOrientation
);

파라미터

pvOrientation
D3DVECTOR 구조체의 주소. 이 구조체는, 사운드 프로젝션 콘의 방향을 받는다. 벡터 정보는 사운드 콘의 중심을 나타낸다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

반환값은 반드시 IDirectSound3DBuffer8::SetConeOrientation 메소드를 사용해 설정한 것과 같은 값은 아니다. DirectSound 는 향해 벡터에 조정을 더해 그러한 매그니튜드를 1.0 이하로 한다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::SetConeOrientation ,IDirectSound3DBuffer8::SetConeAngles ,IDirectSound3DBuffer8::SetConeOutsideVolume


IDirectSound3DBuffer8::GetConeOutsideVolume

사운드 버퍼의 콘 외부 볼륨을 취득한다.

HRESULT GetConeOutsideVolume(
  LPLONG plConeOutsideVolume
);

파라미터

plConeOutsideVolume
버퍼의 콘 외부 볼륨을 받는 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

볼륨 레벨은 감쇠에 의해 나타내진다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 디폴트값은 DS3D_DEFAULTCONEOUTSIDEVOLUME (감쇠 없음)이다. 이러한 값은 dsound.h 내에서 정의되고 있다. 현재 DirectSound 는 증폭을 지원 하고 있지 않다.

콘 외부 볼륨의 개념에 대해서는, 「사운드 콘」을 참조할것.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::SetConeOutsideVolume ,IDirectSound3DBuffer8::GetConeOrientation ,IDirectSound3DBuffer8::SetConeOrientation


IDirectSound3DBuffer8::GetMaxDistance

사운드 버퍼의 최대 거리를 취득한다.

HRESULT GetMaxDistance(
  D3DVALUE * pflMaxDistance
);

파라미터

pflMaxDistance
최대 거리의 설정을 받는 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

디폴트의 최대 거리는 DS3D_DEFAULTMAXDISTANCE 에 의해 정의되어 실질적으로 무한대이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::GetMinDistance ,IDirectSound3DBuffer8::SetMaxDistance


IDirectSound3DBuffer8::GetMinDistance

사운드 버퍼의 최소 거리를 취득한다.

HRESULT GetMinDistance(
  D3DVALUE * pflMinDistance
);

파라미터

pflMinDistance
최소 거리의 설정을 받는 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

디폴트에서는, 최소 거리값은 DS3D_DEFAULTMINDISTANCE 이며, 현재는 1.0 으로 정의되고 있다 (디폴트의 거리 계수 1.0 을 사용했을 경우는, 1 단위는 1.0 미터에 상당한다).

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::SetMinDistance ,IDirectSound3DBuffer8::GetMaxDistance


IDirectSound3DBuffer8::GetMode

3D 사운드 처리의 조작 모드를 취득한다.

HRESULT GetMode(
  LPDWORD pdwMode
);

파라미터

pdwMode
모드 설정을 받는 변수의 주소. 다음의 값중 한쪽이 돌려주어진다.
DS3DMODE_DISABLE
3D 사운드 처리는 무효가 된다. 사운드는 청취자의 머릿속심으로 발생하고 있도록(듯이) 들린다.
DS3DMODE_HEADRELATIVE
사운드 파라미터 (위치, 속도, 방향)는 청취자의 파라미터에 대한 상대적인 것이다. 이 모드에서는, 청취자의 파라미터가 변화했을 때에 사운드의 절대 파라미터는 자동적으로 갱신되므로, 상대 파라미터는 일정으로 유지된다.
DS3DMODE_NORMAL
표준의 처리. 이것은 디폴트의 모드이다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound3DBuffer8::GetPosition

사운드 버퍼의 위치를 거리 단위로 취득한다. 거리의 디폴트의 단위는 미터이지만,IDirectSound3DListener8::SetDistanceFactor 메소드를 사용해 변경할 수 있다.

HRESULT GetPosition(
  D3DVECTOR * pvPosition
);

파라미터

pvPosition
D3DVECTOR 구조체의 주소. 이 구조체는, 사운드 버퍼의 위치를 받는다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound3DBuffer8::GetVelocity

사운드 버퍼의 속도를 취득한다. 속도는, 초속 단위로 계측 된다. 디폴트의 단위는 미터/초이지만,IDirectSound3DListener8::SetDistanceFactor 메소드를 사용해 변경할 수 있다.

HRESULT GetVelocity(
  D3DVECTOR * pvVelocity
);

파라미터

pvVelocity
D3DVECTOR 구조체의 주소. 이 구조체는 사운드 버퍼의 속도를 받는다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

속도는 도플러 효과에서만 사용된다. 실제로 버퍼를 이동할 것은 없다. 상세한 것에 대하여는, 「돕라 계수」를 참조할것.

디폴트의 계측 단위는 미터/초이지만,IDirectSound3DListener8::SetDistanceFactor 메소드를 사용해 변경할 수 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::SetPosition ,IDirectSound3DBuffer8::SetVelocity


IDirectSound3DBuffer8::SetAllParameters

3D 사운드 버퍼의 파라미터를 모두 설정한다.

HRESULT SetAllParameters(
  LPCDS3DBUFFER pcDs3dBuffer,
  DWORD dwApply
);

파라미터

pcDs3dBuffer
DS3DBUFFER 구조체의 주소. 이 구조체는 사운드 버퍼의 3D 특성을 기술한다.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound3DBuffer8::SetConeAngles

사운드 버퍼의 사운드 프로젝션 콘의 내부 각도와 외부 각도를 설정한다.

HRESULT SetConeAngles(
  DWORD dwInsideConeAngle,
  DWORD dwOutsideConeAngle,
  DWORD dwApply
);

파라미터

dwInsideConeAngle
콘의 내부 각도를 지정하는 값 (번단위). 이 각도의 안쪽에서는, 사운드는 보통의 볼륨이다.
dwOutsideConeAngle
콘의 외부 각도를 지정하는 값 (번단위). 이 각도의 외측에서는, 사운드는 외부 볼륨이다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

최소, 최대, 디폴트의 각 콘 각도는 dsound.h 내에서 각각 DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, DS3D_DEFAULTCONEANGLE 로서 정의된다. 각 각도의 범위는, 0о (콘 없음)에서 360о (전범위)까지이다. 디폴트값은 360 이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::SetConeOutsideVolume ,IDirectSound3DBuffer8::SetConeOrientation


IDirectSound3DBuffer8::SetConeOrientation

사운드 버퍼의 사운드 프로젝션 콘의 방향을 설정한다. 콘 각도와 콘 볼륨 계수가 이미 설정되어 있지 않은 한, 이 메소드는 아무것도 하지 않는다.

HRESULT SetConeOrientation(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x, y, 및 z
사운드 콘의 방향 벡터의 좌표를 지정하는 값.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::SetConeAngles ,IDirectSound3DBuffer8::SetConeOutsideVolume


IDirectSound3DBuffer8::SetConeOutsideVolume

사운드 버퍼의 콘 외부 볼륨을 설정한다.

HRESULT SetConeOutsideVolume(
  LONG lConeOutsideVolume,
  DWORD dwApply
);

파라미터

lConeOutsideVolume
사운드 버퍼의 콘 외부 볼륨을 100 분의 1 데시벨 (dB)의 단위로 지정한다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 이러한 값은 dsound.h 내에서 정의되고 있다.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

볼륨 레벨은 감쇠에 의해 나타내진다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 디폴트값은 DS3D_DEFAULTCONEOUTSIDEVOLUME (감쇠 없음)이다. 이러한 값은 dsound.h 내에서 정의되고 있다. 현재 DirectSound 는 증폭을 지원 하고 있지 않다.

콘 외부 볼륨의 개념에 대해서는, 「사운드 콘」을 참조할것.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::SetConeAngles ,IDirectSound3DBuffer8::SetConeOrientation ,IDirectSoundBuffer8::SetVolume


IDirectSound3DBuffer8::SetMaxDistance

최대 거리값을 설정한다.

HRESULT SetMaxDistance(
  D3DVALUE flMaxDistance,
  DWORD dwApply
);

파라미터

flMaxDistance
새로운 최대 거리값.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

디폴트의 최대 거리는 DS3D_DEFAULTMAXDISTANCE 에 의해 정의되어 실질적으로 무한대이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::GetMaxDistance ,IDirectSound3DBuffer8::SetMinDistance


IDirectSound3DBuffer8::SetMinDistance

최소 거리값을 설정한다.

HRESULT SetMinDistance(
  D3DVALUE flMinDistance,
  DWORD dwApply
);

파라미터

flMinDistance
새로운 최소 거리값.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

디폴트에서는, 최소 거리값은 DS3D_DEFAULTMINDISTANCE 이며, 현재는 1.0 으로 정의되고 있다 (디폴트의 거리 계수 1.0 을 사용했을 경우는, 1 단위는 1.0 미터에 상당한다).

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::SetMaxDistance


IDirectSound3DBuffer8::SetMode

3D 사운드 처리의 조작 모드를 설정한다.

HRESULT SetMode(
  DWORD dwMode,
  DWORD dwApply
);

파라미터

dwMode
설정되는 3D 사운드 처리 모드를 지정하는 플래그.
DS3DMODE_DISABLE
3D 사운드 처리는 무효가 된다. 사운드는 청취자의 머릿속심으로 발생하고 있도록(듯이) 들린다.
DS3DMODE_HEADRELATIVE
사운드 파라미터 (위치, 속도, 방향)는 청취자의 파라미터에 대한 상대적인 것이다. 이 모드에서는, 청취자의 파라미터가 변화했을 때에 사운드의 절대 파라미터는 자동적으로 갱신되므로, 상대 파라미터는 일정으로 유지된다.
DS3DMODE_NORMAL
표준의 처리. 이것은 디폴트의 모드이다.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound3DBuffer8::SetPosition

사운드 버퍼의 위치를 거리 단위로 설정한다. 거리의 디폴트의 단위는 미터이지만,IDirectSound3DListener8::SetDistanceFactor 메소드를 사용해 변경할 수 있다.

HRESULT SetPosition(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x, y, 및 z
위치 벡터의 좌표를 지정하는 값. 부동 소수점의 오버플로우를 막기 위해서(때문에), DirectSound 로 이러한 값이 조정되는 경우가 있다.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound3DBuffer8::SetVelocity

음원의 속도를 설정한다.

HRESULT SetVelocity(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x, y, 및 z
속도벡터의 좌표를 지정하는 값. 부동 소수점의 오버플로우를 막기 위해서(때문에), DirectSound 로 이러한 값이 조정되는 경우가 있다.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

속도는 도플러 효과에서만 사용된다. 버퍼의 위치를 변경할 것은 없다. 상세한 것에 대하여는, 「돕라 계수」를 참조할것.

디폴트의 계측 단위는 미터/초이지만,IDirectSound3DListener8::SetDistanceFactor 메소드를 사용해 변경할 수 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DBuffer8::SetPosition ,IDirectSound3DBuffer8::GetVelocity


IDirectSound3DListener8

3D 공간에 있어서의 청취자의 위치, 향해, 및 환경을 기술하는 파라미터의 취득과 설정에 사용한다.

인터페이스는, DSBCAPS_CTRL3D 플래그로 생성 된 프라이머리 버퍼로,IDirectSoundBuffer8:: QueryInterface 메소드를 호출하는 것으로 취득할 수 있다. 오디오 패스를 사용하는 어플리케이션은, 다음의 샘플 코드에 나타내도록(듯이), 오디오 패스로부터 인터페이스를 취득할 수 있다. pAudiopath 는 IDirectMusicAudioPath8 인터페이스 포인터이다.

IDirectSound3DListener8 *pListener;

pAudioPath->GetObjectInPath(0, DMUS_PATH_PRIMARY_BUFFER,
        0, GUID_All_Objects, 0, IID_IDirectSound3DListener,
        (void **) &pListener)));

IDirectSound3DListener8 인터페이스의 메소드는, 다음의 그룹에 정리할 수가 있다.

배치 파라미터 조작 | GetAllParameters
 | SetAllParameters
지연 설정 | CommitDeferredSettings
거리 계수 | GetDistanceFactor
 | SetDistanceFactor
돕라 계수 | GetDopplerFactor
 | SetDopplerFactor
방향 | GetOrientation
 | SetOrientation
위치 | GetPosition
 | SetPosition
롤 오프 계수 | GetRolloffFactor
 | SetRolloffFactor
속도 | GetVelocity
 | SetVelocity

모든 COM 인터페이스와 같이,IDirectSound3DListener8 인터페이스는 IUuknown 인터페이스 메소드를 계승하고 있다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND3DLISTENER 형은,IDirectSound3DListener 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSound3DListener    *LPDIRECTSOUND3DLISTENER;

동작환경

헤더 : dsound.h 로 선언.


IDirectSound3DListener8::CommitDeferredSettings

전회 이 메소드를 호출한 후에 행해진 지연 설정을 위탁한다.

HRESULT CommitDeferredSettings();

파라미터

없음.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

최대의 효율을 가져오는 지연 설정의 사용법에 대해서는, 「지연 설정」을 참조할것.

동작환경

헤더 : dsound.h 로 선언.


IDirectSound3DListener8::GetAllParameters

3D 월드와 청취자 상태를 취득한다.

HRESULT GetAllParameters(
  LPDS3DLISTENER pListener
);

파라미터

pListener
DS3DLISTENER 구조체의 주소. 이 구조체는 3D 월드와 청취자 상태를 받는다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::SetAllParameters


IDirectSound3DListener8::GetDistanceFactor

벡터 단위의 미터수로 거리 계수를 취득한다.

HRESULT GetDistanceFactor(
  D3DVALUE * pflDistanceFactor
);

파라미터

pflDistanceFactor
거리 계수의 값을 받는 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::SetDistanceFactor ,거리 계수


IDirectSound3DListener8::GetDopplerFactor

도플러 효과 계수를 취득한다.

HRESULT GetDopplerFactor(
  D3DVALUE * pflDopplerFactor
);

파라미터

pflDopplerFactor
돕라 계수의 값을 받는 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

돕라 계수의 범위는, DS3D_MINDOPPLERFACTOR (도플러 효과 없음)로부터 DS3D_MAXDOPPLERFACTOR (현재의 정의에서는 열매 세계의 10 배의 도플러 효과)까지이다. 디폴트값은 DS3D_DEFAULTDOPPLERFACTOR (1.0)이다. 상세한 것에 대하여는, 「돕라 계수」를 참조할것.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::SetDopplerFactor


IDirectSound3DListener8::GetOrientation

청취자의 방향을 벡터 (전방 벡터와 윗쪽 벡터)로 취득한다.

HRESULT GetOrientation(
  D3DVECTOR * pvOrientFront,
  D3DVECTOR * pvOrientTop
);

파라미터

pvOrientFront
D3DVECTOR 구조체의 주소. 이 구조체는 청취자의 전방 벡터를 받는다.
pvOrientTop
D3DVECTOR 구조체의 주소. 이 구조체는 청취자의 윗쪽 벡터를 받는다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

전방 벡터는 청취자의 코의 방향, 윗쪽 벡터는 청취자의 두정부의 방향을 가리킨다. 디폴트에서는, 전방 벡터는 (0, 0, 1.0), 윗쪽 벡터는 (0, 1.0, 0)이다.

반환값은 반드시 IDirectSound3DListener8::SetOrientation 메소드를 사용해 설정한 것과 같은 값은 아니다. DirectSound 는 향해 벡터에 조정을 더해, 그것들이 서로 직교 하도록(듯이) 해, 양쪽 모두의 매그니튜드를 1.0 이하로 한다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::SetOrientation


IDirectSound3DListener8::GetPosition

청취자의 위치를 거리 단위로 취득한다. 이러한 단위의 디폴트는 미터이지만,IDirectSound3DListener8::SetDistanceFactor 메소드를 호출해 변경할 수 있다.

HRESULT GetPosition(
  D3DVECTOR * pvPosition
);

파라미터

pvPosition
D3DVECTOR 구조체의 주소. 이 구조체는 청취자의 위치 벡터를 받는다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::SetPosition


IDirectSound3DListener8::GetRolloffFactor

거리에 응한 감쇠율을 결정하는 롤 오프 계수를 취득한다.

HRESULT GetRolloffFactor(
  D3DVALUE * pflRolloffFactor
);

파라미터

pflRolloffFactor
롤 오프 계수를 받는 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

롤 오프 계수는, DS3D_MINROLLOFFFACTOR (롤 오프 없음)로부터 DS3D_MAXROLLOFFFACTOR (현재의 정의에서는 열매 세계의 10 배)까지의 범위를 취한다. 디폴트값은 DS3D_DEFAULTROLLOFFFACTOR (1.0)이다. 상세한 것에 대하여는, 「롤 오프 계수」를 참조할것.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::SetRolloffFactor


IDirectSound3DListener8::GetVelocity

청취자의 속도를 취득한다.

HRESULT GetVelocity(
  D3DVECTOR * pvVelocity
);

파라미터

pvVelocity
D3DVECTOR 구조체의 주소. 이 구조체는 청취자의 속도를 받는다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

속도는 도플러 효과에서만 사용된다. 청취자의 위치를 변경할 것은 없다. 청취자의 위치를 변경하려면 IDirectSound3DListener8::SetPosition 메소드를 사용한다.

디폴트의 속도는 (0,0,0)이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::SetVelocity


IDirectSound3DListener8::SetAllParameters

DS3DLISTENER 구조체로 지정한, 모든 3D 청취자 파라미터를 설정한다. 이 구조체는 있는 순간의 청취자의 모든 상태를 기술한다.

HRESULT SetAllParameters(
  LPCDS3DLISTENER pcListener,
  DWORD dwApply
);

파라미터

pcListener
DS3DLISTENER 구조체의 주소. 이 구조체는 3D 청취자의 모든 파라미터 정보를 보관 유지한다.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::GetAllParameters


IDirectSound3DListener8::SetDistanceFactor

벡터 단위의 미터수로 거리 계수를 설정한다.

HRESULT SetDistanceFactor(
  D3DVALUE flDistanceFactor,
  DWORD dwApply
);

파라미터

flDistanceFactor
거리 계수를 지정하는 값.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

거리 계수의 범위는, DS3D_MINDISTANCEFACTOR 로부터 DS3D_MAXDISTANCEFACTOR 까지이다. dsound.h 에서는, 각각 FLT_MIN 및 FLT_MAX 로서 정의되고 있다. 디폴트값은, DS3D_DEFAULTDISTANCEFACTOR 또는 1.0 이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::GetDistanceFactor ,거리 계수


IDirectSound3DListener8::SetDopplerFactor

도플러 효과 계수를 설정한다.

HRESULT SetDopplerFactor(
  D3DVALUE flDopplerFactor,
  DWORD dwApply
);

파라미터

flDopplerFactor
돕라 계수를 지정하는 값.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

돕라 계수의 범위는, DS3D_MINDOPPLERFACTOR (도플러 효과 없음)로부터 DS3D_MAXDOPPLERFACTOR (현재의 정의에서는 열매 세계의 10 배의 도플러 효과)까지이다. 디폴트값은 DS3D_DEFAULTDOPPLERFACTOR (1.0)이다. 상세한 것에 대하여는, 「돕라 계수」를 참조할것.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::GetDopplerFactor


IDirectSound3DListener8::SetOrientation

2 개의 벡터 (전방 벡터와 윗쪽 벡터)에 의해, 청취자의 방향을 설정한다.

HRESULT SetOrientation(
  D3DVALUE xFront,
  D3DVALUE yFront,
  D3DVALUE zFront,
  D3DVALUE xTop,
  D3DVALUE yTop,
  D3DVALUE zTop,
  DWORD    dwApply
);

파라미터

xFront, yFront, zFront
전방 벡터의 좌표를 지정하는 값.
xTop, yTop, zTop
윗쪽 벡터의 좌표를 지정하는 값.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

전방 벡터는 청취자의 코의 방향, 윗쪽 벡터는 청취자의 두정부의 방향을 가리킨다. 디폴트에서는, 전방 벡터는 (0, 0, 1.0), 윗쪽 벡터는 (0, 1.0, 0)이다.

윗쪽 벡터는 전방 벡터에 대해서 직각이 아니면 안된다. 필요에 따라서, DirectSound 는 전방 벡터를 설정한 다음에 윗쪽 벡터를 조정한다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::GetOrientation


IDirectSound3DListener8::SetPosition

청취자의 위치를 거리 단위로 설정한다. 이러한 단위의 디폴트는 미터이지만,IDirectSound3DListener8::SetDistanceFactor 메소드를 호출해 변경할 수 있다.

HRESULT SetPosition(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x, y, 및 z
청취자의 위치 벡터의 좌표를 지정하는 값. 부동 소수점의 오버플로우를 방지하기 위해서, DirectSound 가 이러한 값에 조정을 더할 가능성이 있는 점에 주의 해야 한다.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::GetPosition


IDirectSound3DListener8::SetRolloffFactor

거리에 응한 감쇠율을 결정하는 롤 오프 계수를 설정한다.

HRESULT SetRolloffFactor(
  D3DVALUE flRolloffFactor,
  DWORD dwApply
);

파라미터

flRolloffFactor
롤 오프 계수를 지정하는 값.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

롤 오프 계수는, DS3D_MINROLLOFFFACTOR (롤 오프 없음)로부터 DS3D_MAXROLLOFFFACTOR (현재의 정의에서는 열매 세계의 10 배)까지의 범위를 취한다. 디폴트값은 DS3D_DEFAULTROLLOFFFACTOR (1.0)이다. 상세한 것에 대하여는, 「롤 오프 계수」를 참조할것.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::GetRolloffFactor


IDirectSound3DListener8::SetVelocity

청취자의 속도를 설정한다.

HRESULT SetVelocity(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x, y, 및 z
청취자의 속도벡터의 좌표를 지정하는 값. 부동 소수점의 오버플로우를 막기 위해서(때문에), DirectSound 로 이러한 값이 조정되는 경우가 있다.
dwApply
설정이 적용되는 타이밍을 지정하는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener8::CommitDeferredSettings 메소드를 호출할 때까지 설정은 적용되지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

속도는 도플러 효과에서만 사용된다. 실제로 청취자를 이동할 것은 없다. 청취자의 위치를 변경하려면 IDirectSound3DListener8::SetPosition 메소드를 사용한다. 디폴트의 속도는 (0,0,0)이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound3DListener8::GetVelocity


IDirectSoundBuffer8

사운드 버퍼의 관리에 사용한다.

IDirectSoundBuffer 에 대신해 IDirectSoundBuffer8 인터페이스가 제공되어 새로운 메소드가 추가되고 있다.

인터페이스를 취득하려면 ,IDirectSound8::CreateSoundBuffer 메소드를 사용해 IDirectSoundBuffer 를 취득해, IID_IDirectSoundBuffer8 를 IDirectSoundBuffer::QueryInterface 에 건네준다.

프라이머리 사운드 버퍼에는,IDirectSoundBuffer 인터페이스를 사용할 필요가 있다. IDirectSoundBuffer8 는 이용할 수 없다. IDirectSoundBuffer 의 독립한 설명 항목은 없다. 설명은, 대응하는 IDirectSoundBuffer8 메소드를 참조할것.

IDirectSoundBuffer 의 모든 메소드가, 프라이머리 버퍼로 유효인 것은 아니다. 예를 들어,SetCurrentPosition 는 실패한다. 각 메소드에 대해서는, 레퍼런스의 주제를 참조할것.

IDirectSoundBuffer8 인터페이스의 메소드는, 다음의 그룹에 정리할 수가 있다.

이펙트 | GetObjectInPath
 | SetFX
정보 | GetCaps
 | GetFormat
 | GetStatus
 | SetFormat
메모리 메니지먼트 | AcquireResources
 | Initialize
 | Restore
연주 관리 | GetCurrentPosition
 | Lock
 | Play
 | SetCurrentPosition
 | Stop
 | Unlock
사운드 관리 | GetFrequency
 | GetPan
 | GetVolume
 | SetFrequency
 | SetPan
 | SetVolume

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

다음의 표는, 오디오 패스로부터 취득한 버퍼 오브젝트, 즉, DirectMusic 퍼포먼스로 생성 된 버퍼로 지원 되는 메소드를 나타내고 있다. 믹스 인 버퍼는 그 외의 버퍼로부터의 센드를 받는다. 오디오 패스외의 버퍼는 모두, 세면대 인 버퍼이다. 이러한 버퍼는, 신디사이저 세면대로부터만 데이터를 받아들인다.

IDirectSoundBuffer8 메소드 | 믹스 인 | 세면대 인
AcquireResources |  |
GetCaps | 있어 | 있어
GetCurrentPosition |  |
GetFormat | 있어 | 있어
GetFrequency |  |
GetObjectInPath | 있어 | 있어
GetPan | 있어 | 있어
GetStatus | 있어 | 있어
GetVolume | 있어 | 있어
Initialize |  |
Lock
Play | 있어
Restore |
SetCurrentPosition
SetFormat
SetFrequency
SetFX | 있어 | 있어
SetPan | 있어 | 있어
SetVolume | 있어 | 있어
Stop | 있어 |
Unlock |

LPDIRECTSOUNDBUFFER8 형은,IDirectSoundBuffer 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundBuffer8    *LPDIRECTSOUNDBUFFER8;

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundBuffer8::AcquireResources

DSBUFFERDESC 구조체의 DSBCAPS_LOCDEFER 플래그를 사용해 생성 한 버퍼에 리소스를 할당한다.

HRESULT AcquireResources(
  DWORD dwFlags,
  DWORD dwEffectsCount,
  LPDWORD pdwResultCodes
);

파라미터

dwFlags
DSBCAPS_LOCDEFER 플래그를 사용해 생성 한 버퍼에 리소스를 할당하는 방법을 지정하는 플래그. 값의 리스트에 대해서는,IDirectSoundBuffer8::Play 의 음성 관리 플래그 및 음성 할당 플래그를 참조할것.
dwEffectsCount
pdwResultFlags 배열의 요소의 수를 지정하는 값. pdwResultCodes 가 NULL 의 경우는 0 을 지정한다.
pdwResultCodes
DWORD 변수의 배열의 주소. 이 배열은, 버퍼에 관련지을 수 있었던 이펙트에 관한 정보를 받는다. 이 배열에는,IDirectSoundBuffer8::SetFX 에 의해 버퍼에 할당할 수 있었던 이펙트 각각 대해, 1 개의 요소가 포함되지 않으면 안 된다. 각 이펙트에 대해서, 다음의 몇개의 값이 돌려주어진다.
DSFXR_LOCHARDWARE
이펙트는 하드웨어로 인스턴스화 된다.
DSFXR_LOCSOFTWARE
이펙트는 소프트웨어로 인스턴스화 된다.
DSFXR_FAILED
리소스를 이용할 수 없었기 (위해)때문에, 이펙트는 생성되어 있지 않다.
DSFXR_PRESENT
이펙트는 이용할 수 있지만, 다른 원인으로 메소드가 실패했으므로, 생성되어 있지 않다.
DSFXR_UNKNOWN
이펙트가 시스템에 등록되지 않기 때문에, 이펙트는 생성되어 있지 않다.

결과 코드가 필요하지 않은 경우, 이 파라미터는 NULL 로 한다.

반환값

성공했을 경우는, DS_OK 또는 DS_INCOMPLETE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDCALL
DSERR_INVALIDPARAM

주의

보통, DSBCAPS_LOCDEFER 로 생성 된 버퍼는,IDirectSoundBuffer8::Play 가 불려 갈 때까지 리소스에 할당할 수 없다. 지연 버퍼에 리소스를 할당하려면 ,IDirectSoundBuffer8::AcquireResources 를 사용한다. 이것에 의해, 어플리케이션은, 이펙트의 처리에 관한 정보를 취득해, 버퍼가 연주되기 전에 이펙트 파라미터를 설정할 수 있다.

메소드가 실패했을 경우는,pdwResultCodes 의 값을 조사해, 실패의 원인이 된 이펙트를 특정한다.

리소스를 할당할 수 있던, 아직 연주되어 있지 않은 버퍼는,Play 메소드에게 건네진 음성 관리 플래그에 의해, 빨리 종료되는 후보가 되지 않는다.

AcquireResources 에 의해 취득된 리소스는, 재생이 정지되었을 때에 해방된다.

메소드가 이미 불려 간 버퍼로, 반복 메소드가 불려 갔을 경우, 이펙트의 스테이터스는 돌려주어지지만, 그 이상의 리소스는 할당할 수 없다.

이 함수의 dwEffectsCount 파라미터는,IDirectSoundBuffer8::SetFX 의 호출로 건네받은 파라미터와 같지 않으면 안 된다.

하드웨어 가속화를 이용할 수 없는 시스템으로 DSBCAPS_LOCHARDWARE 플래그를 사용해 버퍼의 리소스를 취득하려고 하면(자), 메소드는 실패해, operating system에 응해 DSERR_CONTROLUNAVAIL 또는 DSERR_INVALIDCALL 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX ,DSBCAPS


IDirectSoundBuffer8::GetCaps

DirectSoundBuffer 오브젝트의 능력을 취득한다.

HRESULT GetCaps(
  LPDSBCAPS pDSBufferCaps
);

파라미터

pDSBufferCaps
DSBCAPS 구조체의 주소. 이 구조체는,사운드 버퍼의 능력을 보관 유지하고 있다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

DSBCAPS 구조체는,IDirectSound8::CreateSoundBuffer 메소드에게 건네지는 DSBUFFERDESC 구조체와 동등의 정보에 가세해, 몇개의 추가 정보를 보관 유지하고 있다. 추가 정보로서 버퍼의 위치 (하드웨어 또는 소프트웨어)와 퍼포먼스 측정값을 들 수 있다.

DSBCAPS 구조체의 dwFlags 멤버내에서 지정되는 플래그는,DSBUFFERDESC 구조체로 사용되는 플래그와 같은 것이다. 유일한 차이는,DSBCAPS 구조체에서는 버퍼 메모리의 장소에 응해 DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 어느 쪽인지가 지정되는 것이다. DSBUFFERDESC 구조체에서는 이러한 플래그는 옵션이며, 플래그의 지정에 응해, 버퍼를 하드웨어와 소프트웨어의 어딘가에 강제적으로 배치할 수 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

DSBCAPS ,DSBUFFERDESC ,IDirectSound8::CreateSoundBuffer


IDirectSoundBuffer8::GetCurrentPosition

사운드 버퍼내의 재생 커서와 기입해 커서의 위치를 취득한다.

HRESULT GetCurrentPosition(
  LPDWORD pdwCurrentPlayCursor,
  LPDWORD pdwCurrentWriteCursor
);

파라미터

pdwCurrentPlayCursor
재생 커서의 오프셋(offset)를 받는 변수의 주소 (바이트 단위). 값이 필요하지 않은 경우, 이 파라미터를 NULL 로 한다.
pdwCurrentWriteCursor
기입 커서의 오프셋(offset)를 받는 변수의 주소 (바이트 단위). 값이 필요하지 않은 경우, 이 파라미터를 NULL 로 한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

기입 커서는, 데이터 기입을 안전하게 실시할 수 있는, 버퍼의 선두 위치이다. 재생 커서보다 뒤, 및 기입 커서의 전방에 있는 버퍼에는, 데이터를 기입해서는 안된다. 상세한 것에 대하여는, 「재생 커서와 기입해 커서」를 참조할것.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetCurrentPosition


IDirectSoundBuffer8::GetFormat

버퍼내의 사운드 데이터의 포맷에 관한 정보, 또는 포맷의 기술을 취득하는데 필요한 버퍼 사이즈를 취득한다.

HRESULT GetFormat(
  LPWAVEFORMATEX pwfxFormat,
  DWORD dwSizeAllocated,
  LPDWORD pdwSizeWritten
);

파라미터

pwfxFormat
버퍼내의 사운드 데이터에 관한 정보를 받는 WAVEFORMATEX 구조체의 주소. 포맷의 기술을 보관 유지하기 위해서 필요한 버퍼 사이즈를 취득하려면 NULL 를 지정한다. 이 경우,pdwSizeWritten 의 변수가, 데이터를 받기 위해서(때문에) 필요한 구조체의 사이즈를 받는다.
dwSizeAllocated
pwfxFormat 의 구조체의 사이즈 (바이트 단위). pwfxFormat 가 NULL 가 아닌 경우, 이 값은 예기 되는 데이터 사이즈와 같은가, 그 이상이 아니면 안된다.
pdwSizeWritten
pwfxFormat 의 구조체에 기입해진 바이트수를 받는 변수의 주소. 이 파라미터는 NULL 로 해도 괜찮다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

WAVEFORMATEX 구조체는, 포맷에 응한 가변장이어도 괜찮다. 어플리케이션은 포맷의 기술을 취득하기 전에,pwfxFormat 파라미터에 NULL 를 지정해 이 메소드를 호출해, 포맷의 사이즈에 관해서 DirectSoundBuffer 오브젝트를 조회할 필요가 있다. 필요한 구조체의 사이즈는 pdwSizeWritten 파라미터에 돌려주어진다. 그 후, 어플리케이션은 충분한 메모리를 할당해 한번 더 IDirectSoundBuffer8::GetFormat 를 호출해, 포맷의 기술을 취득할 수 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFormat


IDirectSoundBuffer8::GetFrequency

버퍼의 재생을 하고 있는 장소에서의 1 초 쯤의 샘플링 회수를 주파수로서 취득한다.

HRESULT GetFrequency(
  LPDWORD pdwFrequency
);

파라미터

pdwFrequency
오디오 버퍼가 재생되고 있는 장소에서의 주파수를 받는 변수의 주소 (Hz 단위).

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

소프트웨어 버퍼의 주파수의 값은, DSBFREQUENCY_MIN 로부터 DSBFREQUENCY_MAX 의 범위를 취한다. 이러한 값은, Dsound.h 내에서 각각 100, 100,000 으로 정의되고 있다. 다만, 버퍼는 다른 값을 돌려주는 일이 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFrequency


IDirectSoundBuffer8::GetObjectInPath

버퍼에 관련지을 수 있었던 이펙트 오브젝트의 인터페이스를 취득한다.

HRESULT GetObjectInPath(
  REFGUID rguidObject,
  DWORD dwIndex,
  REFGUID rguidInterface,
  LPVOID * ppObject
);

파라미터

rguidObject
검색하는 오브젝트의 일의의 클래스 식별자를 지정하는 REFGUID 형의 값. 예를 들어, GUID_DSFX_STANDARD_ECHO 등. 임의의 클래스의 오브젝트를 검색하는 경우는, 이 파라미터를 GUID_All_Objects 로 설정한다.
dwIndex
패스중의 클래스의 오브젝트내에서, 오브젝트의 인덱스를 지정하는 값. 「주의」를 참조할것.
rguidInterface
목적의 인터페이스의 일의의 식별자를 지정하는 값. 「주의」를 참조할것.
ppObject
목적의 인터페이스 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_OBJECTNOTFOUND
E_NOINTERFACE

주의

IDirectSoundBuffer8::SetFX 를 사용해 버퍼로 설정되어 있는 DMO 는, 리소스를 할당할 수 있지 않아도 취득할 수가 있다.

이하의 인터페이스는, DirectX 로 제공되고 있는 각종 DMO 에 대해서 취득할 수 있다.

rguidInterface | *ppObject
IID_IDirectSoundFXGargle8 | IDirectSoundFXGargle8
IID_IDirectSoundFXChorus8 | IDirectSoundFXChorus8
IID_IDirectSoundFXFlanger8 | IDirectSoundFXFlanger8
IID_IDirectSoundFXEcho8 | IDirectSoundFXEcho8
IID_IDirectSoundFXDistortion8 | IDirectSoundFXDistortion8
IID_IDirectSoundFXCompressor8 | IDirectSoundFXCompressor8
IID_IDirectSoundFXParamEq8 | IDirectSoundFXParamEq8
IID_IDirectSoundFXWavesReverb8 | IDirectSoundFXWavesReverb8
IID_IDirectSoundFXI3DL2Reverb8 | IDirectSoundFXI3DL2Reverb8

게다가 표준의 DMO 에서는 이하의 인터페이스를 사용할 수 있다. 이러한 인터페이스의 상세한 것에 대하여는, DirectShow 의 헬프를 참조할것.

rguidInterface | *ppObject
IID_IMediaObject | IMediaObject
IID_IMediaObjectInPlace | IMediaObjectInPlace
IID_IMediaParams | IMediaParams

dwIndex 의 값은,IDirectSoundBuffer8::SetFX 에게 건네진 이펙트의 배열내에서의 오브젝트의 인덱스이다. 몇개의 이펙트가 아직 생성되어 있지 않은 경우가 있기 (위해)때문에, 이펙트내의 실제의 오브젝트의 위치를 나타내고 있다고는 할 수 없다.

오브젝트는,rguidObject 및 dwIndex 와의 일치인 만큼 기초를 두어 돌려주어진다. rguidInterface 가 그 오브젝트로 사용되고 있는 인터페이스를 나타내고 있을지 어떨지는, 어플리케이션측에서 확인할 필요가 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXChorus8 ,IDirectSoundFXCompressor8 ,IDirectSoundFXDistortion8 ,IDirectSoundFXEcho8 ,IDirectSoundFXFlanger8 ,IDirectSoundFXParamEq8 ,IDirectSoundFXI3DL2Reverb8


IDirectSoundBuffer8::GetPan

좌우의 오디오 채널의 상대 볼륨을 취득한다.

HRESULT GetPan(
  LPLONG plPan
);

파라미터

plPan
좌우의 상대 믹싱율을 보관 유지하는 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

반환값은 DSBPAN_LEFT 로부터 DSBPAN_RIGHT 의 범위에서, 100 분의 1 데시벨 (dB) 단위로 측정된다. 현재 이러한 값은, Dsound.h 내에서 각각 -10, 000, 10,000 으로 정의되고 있다. 값 DSBPAN_LEFT 는 오른쪽 채널이 100 dB 감쇠하고 있는 것을 의미한다. 값 DSBPAN_RIGHT 는 왼쪽 채널이 100 dB 감쇠하고 있는 것을 의미한다. 중립값은 DSBPAN_CENTER 이며, 0 으로 정의되고 있다. plPan 파라미터가 0 일 때는, 양쪽 모두의 채널이 최대 볼륨인 것을 의미한다 (어느쪽이나 0 dB 의 감쇠이다). DSBPAN_CENTER 이외의 값은 모두, 한편이 최대 볼륨으로 이제(벌써) 한편이 감쇠하고 있는 것을 의미한다.

빵의 값이 -2, 173 때, 왼쪽 채널은 최대 볼륨으로, 오른쪽 채널은 21.73 dB 감쇠하고 있는 것을 의미한다. (와)과 같이 빵의 값이 870 때, 왼쪽 채널은 8.7 dB 감쇠하고 있어, 오른쪽 채널은 최대 볼륨인 것을 의미한다. DSBPAN_LEFT 의 빵은, 오른쪽 채널이 무음으로, 사운드가 왼쪽으로부터 마셔 발생하고 있는 것을 의미한다. 한편, DSBPAN_RIGHT 의 빵은, 왼쪽 채널이 무음으로, 사운드가 오른쪽으로부터 마셔 발생하고 있는 것을 의미한다.

빵 컨트롤의 효과는, 음량 조절에 누적된다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::GetVolume ,IDirectSoundBuffer8::SetPan ,IDirectSoundBuffer8::SetVolume


IDirectSoundBuffer8::GetStatus

사운드 버퍼의 스테이터스를 취득한다.

HRESULT GetStatus(
  LPDWORD pdwStatus
);

파라미터

pdwStatus
사운드 버퍼의 스테이터스를 보관 유지하는 변수의 주소. 스테이터스는, 다음의 플래그의 편성이다.
DSBSTATUS_BUFFERLOST
버퍼는 없어지고 있어 재생이나 락을 실시하기 전에 복원하지 않으면 안 된다.
DSBSTATUS_LOOPING
버퍼는 루프 하고 있다. 이 값이 설정되어 있지 않은 경우, 버퍼의 사운드 데이터의 마지막에 달하면(자) 재생은 정지한다. 이 값은, DSBSTATUS_PLAYING 와의 편성에서만 돌려주어진다.
DSBSTATUS_PLAYING
버퍼는 재생중이다. 이 값이 설정되어 있지 않은 경우, 버퍼는 정지하고 있다.
DSBSTATUS_LOCSOFTWARE
소프트웨어의 버퍼는 재생중이다. DSBCAPS_LOCDEFER 플래그로 생성 한 버퍼에만 설정한다.
DSBSTATUS_LOCHARDWARE
하드웨어의 버퍼는 재생중이다. DSBCAPS_LOCDEFER 플래그로 생성 한 버퍼에만 설정한다.
DSBSTATUS_TERMINATED
음성 관리가 버퍼를 빨리 종료해, 버퍼는 정지하고 있다. DSBCAPS_LOCDEFER 플래그로 생성 한 버퍼에만 설정한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundBuffer8::GetVolume

버퍼의 볼륨을 취득한다.

HRESULT GetVolume(
  LPLONG plVolume
);

파라미터

plVolume
감쇠를 100 분의 1 데시벨의 단위로 받는 변수의 주소. 「주의」를 참조할것.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

반환값의 범위는, DSBVOLUME_MAX 로부터 DSBVOLUME_MIN 이다. 이러한 값은, 각각 0 및 -10, 000 으로 정의되고 있다. 값 DSBVOLUME_MAX 는, 사운드 본래의 미조정의 볼륨을 나타낸다. 값 DSBVOLUME_MIN 는, 오디오의 볼륨이 100 dB 감쇠하고 있는 것을 나타내지만, 이것은 실제적으로는 무음을 의미한다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetVolume


IDirectSoundBuffer8::Initialize

초기화되어 있지 않은 DirectSoundBuffer 오브젝트를 초기화한다.

HRESULT Initialize(
  LPDIRECTSOUND pDirectSound,
  LPCDSBUFFERDESC pcDSBufferDesc
);

파라미터

pDirectSound
DirectSoundBuffer 오브젝트에 관련지을 수 있었던 DirectSound 오브젝트의 주소.
pcDSBufferDesc
이 사운드 버퍼를 초기화하기 위해서 사용되는 값을 보관 유지하는 DSBUFFERDESC 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_ALREADYINITIALIZED

주의

IDirectSound8::CreateSoundBuffer 메소드가 내부에서 IDirectSoundBuffer8::Initialize 를 호출하기 (위해)때문에, 현재의 릴리스의 DirectSound 에서는 필요없다. Initialize 메소드는 장래의 확장성에 대비해 준비되어 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

DSBUFFERDESC ,IDirectSound8::CreateSoundBuffer ,IDirectSoundBuffer8


IDirectSoundBuffer8::Lock

버퍼의 전부 또는 일부를 데이터 기입용으로 준비해, 데이터를 기입할 수 있는 포인터를 돌려준다.

HRESULT Lock(
  DWORD dwOffset,
  DWORD dwBytes,
  LPVOID * ppvAudioPtr1,
  LPDWORD pdwAudioBytes1,
  LPVOID * ppvAudioPtr2,
  LPDWORD pdwAudioBytes2,
  DWORD dwFlags
);

파라미터

dwOffset
버퍼의 선두로부터 락 시작 위치까지의 오프셋(offset)를 바이트 단위로 지정하는 값. dwFlags 파라미터로 DSBLOCK_FROMWRITECURSOR 플래그가 지정되고 있는 경우는, 이 파라미터는 무시된다.
dwBytes
락 되는 버퍼 부분의 사이즈를 바이트 단위로 지정하는 값. 버퍼는 개념적으로는 순환 버퍼이기 (위해)때문에, 이 수는 dwOffset 로부터 버퍼의 끝까지의 사이의 바이트수를 웃돌 수가 있다.
ppvAudioPtr1
버퍼의 최초로 락 된 부분에의 포인터를 받는 변수의 주소.
pdwAudioBytes1
블록의 바이트수를 ppvAudioPtr1 로 받는 변수의 주소. 이 값이 dwBytes 보다 작은 경우, 락은 랩 되어ppvAudioPtr2 는 버퍼의 선두에 있는 제 2 의 데이터 블록을 가리킨다.
ppvAudioPtr2
캡춰 버퍼의 2 번째에 락 된 부분에의 포인터를 받는 변수의 주소. NULL 가 돌려주어졌을 경우,ppvAudioPtr1 파라미터는 캡춰 버퍼의 락 된 부분 전체를 가리킨다.
pdwAudioBytes2
블록의 바이트수를 ppvAudioPtr2 로 받는 변수의 주소. ppvAudioPtr2 가 NULL 의 경우, 값은 0 이다.
dwFlags
락 이벤트로 변경을 더하는 플래그. 다음의 플래그가 정의되고 있다.
DSBLOCK_FROMWRITECURSOR
기입 커서의 위치에서 락을 시작 한다. dwOffset 파라미터는 무시된다.
DSBLOCK_ENTIREBUFFER
버퍼 전체를 잠근다. dwBytes 파라미터는 무시된다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

이 메소드는 오프셋(offset)와 바이트 카운트를 받아, 2 개의 기입 포인터와 각각 관련하는 사이즈를 돌려준다. 락 되는 부분이 버퍼의 끝까지 확장하지 않고, 버퍼의 선두에 랩 되지 않는 경우, 2 번째의 포인터인 ppvAudioBytes2 는 NULL 를 받는다. 락이 랩 되는 경우,ppvAudioBytes2 는 버퍼의 선두에의 포인터를 가리킨다.

어플리케이션이 ppvAudioPtr2 파라미터 및 pdwAudioBytes2 파라미터에 대해서 NULL 를 건네주면(자), 락이 버퍼의 종단을 넘을 것은 없고, 랩 되지 않는다.

이 메소드로 돌려주어진 포인터에 데이터를 기입하면(자), 어플리케이션은 즉시 IDirectSoundBuffer8::Unlock 를 호출해, 데이터 재생의 준비를 할 수 있던 것을 DirectSound 에 통지할 필요가 있다. 이 통지를 실시하지 않으면 사운드 디바이스의 구성에 따라서는, 오디오의 분단 또는 무음 상태가 발생하는 경우가 있다.

이 메소드는, 기입 포인터만을 돌려준다. 데이터가 유효하지 않은 경우가 있기 (위해)때문에, 어플리케이션으로 이 포인터로부터 사운드 데이터를 읽어들이려고 해서는 안된다. 예를 들어, 버퍼가 카드의 메모리에 배치되고 있는 경우, 그 포인터는 메인 시스템 메모리내의 일시 버퍼의 주소가 되고 있는 일도 생각할 수 있다. IDirectSoundBuffer8::Unlock 를 호출하면, 이 일시 버퍼의 내용은 카드의 메모리에 전송 된다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::GetCurrentPosition


IDirectSoundBuffer8::Play

사운드 버퍼를 재생 커서의 위치로부터 재생한다.

HRESULT Play(
  DWORD dwReserved1,
  DWORD dwPriority,
  DWORD dwFlags
);

파라미터

dwReserved1
이 멤버는 예약되고 있다. 0 이 아니면 안된다.
dwPriority
사운드의 우선도. 이 우선도는, 하드웨어 믹싱 리소스를 할당할 때에 음성 관리가 사용한다. 가장 낮은 우선도는 0, 가장 높은 우선도는 0xFFFFFFFF 이다. 버퍼가 DSBCAPS_LOCDEFER 플래그로 생성되어 있지 않은 경우, 이 값은 0 이다.
dwFlags
버퍼의 재생 방법을 지정하는 플래그. 다음의 플래그가 정의되고 있다.
DSBPLAY_LOOPING
오디오 버퍼의 마지막에 달하면(자), 버퍼의 선두로부터 재생을 재개한다. 명시적으로 정지할 때까지 재생이 계속된다. 이 플래그는,프라이머리 사운드 버퍼를 재생할 때로 설정해야 한다.
음성 할당 플래그
음성 할당 플래그는, 버퍼가 DSBCAPS_LOCDEFER 플래그로 생성 되었을 때 마셔 유효하다. 사운드 처리를 하드웨어나 소프트웨어로 강제적으로 실시하려면 , 다음의 플래그의 어느쪽이든을 사용할 수도 있다. DBSPLAY_LOCHARDWARE 과 DBSPLAY_LOCSOFTWARE 의 어느쪽이나 설정되어 있지 않은 경우는, 메소드가 불려 갔을 때에 리소스가 이용 가능한가 어떤가에 의해, 사운드가 소프트웨어 또는 하드웨어로 재생된다. 「주의」를 참조할것.
DSBPLAY_LOCHARDWARE
하드웨어 버퍼만으로 음성을 재생한다. 하드웨어에 이용 가능한 음성이 없고, 음성 관리 플래그도 설정되어 있지 않은 경우,IDirectSoundBuffer8::Play 에 대한 호출은 실패한다. 이 플래그를 DSBPLAY_LOCSOFTWARE 와 조합할 수 없다.
DSBPLAY_LOCSOFTWARE
소프트웨어 버퍼만으로 음성을 재생한다. 이 플래그를 DSBPLAY_LOCHARDWARE 나 음성 관리 플래그의 어떤 것일까하고 조합할 수 없다.
음성 관리 플래그
음성 관리 플래그는, 버퍼가 DSBCAPS_LOCDEFER 플래그로 생성 되었을 때에 마셔 유효하고, 하드웨어로 재생하는 사운드에 사용된다. 이러한 플래그는, 이미 사용중의 하드웨어 리소스에 현재의 사운드가 주고 받아지도록(듯이) 한다. DSBCAPS_LOCDEFER 플래그로 생성 된 버퍼만이, 빨리 종료되는 후보가 된다. 「주의」를 참조할것.
DSBPLAY_TERMINATEBY_TIME
하드웨어에 이용 가능한 음성이 없는 경우는, 새로운 버퍼용의 빈 곳을 확보하기 위해서 현재 재생중의 비루프 버퍼가 정지한다. 빨리 종료되는 버퍼는, 재생의 남은 시간이 가장 적은 버퍼이다.
DSBPLAY_TERMINATEBY_DISTANCE
하드웨어에 이용 가능한 음성이 없는 경우는, 새로운 버퍼용의 빈 곳을 확보하기 위해서 현재 재생중의 버퍼가 정지된다. 빨리 종료되는 버퍼는, DSBCAPS_MUTE3DATMAXDISTANCE 플래그가 설정되어 최대 거리를 넘고 있는 것의 중으로부터 선택된다. 이러한 버퍼가 없는 경우, 메소드는 실패한다.
DSBPLAY_TERMINATEBY_PRIORITY
하드웨어에 이용 가능한 음성이 없는 경우는, 새로운 버퍼용의 빈 곳을 확보하기 위해서 현재 재생중의 버퍼가 정지된다. 빨리 종료되는 버퍼는,IDirectSoundBuffer8::Play 에게 건네지는 dwPriority 파라미터로 설정된 우선도가 가장 낮은 버퍼이다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

IDirectSound8::SetCooperativeLevel 가 불려 가지 않은 경우에서도, 메소드는 DS_OK 를 돌려준다. 다만, 협조 레벨이 설정될 때까지 사운드는 출력되지 않는다.

이 메소드가 지정한 버퍼가 이미 재생중이었던 경우, 메소드의 호출은 성공해, 버퍼는 재생을 계속한다. 다만 최신의 호출로 정의한 플래그는, 이전의 호출로 정의되고 있던 플래그를 옮겨놓는다.

이 메소드가 프라이머리 버퍼로 불려 갔을 경우는, 사운드 디바이스로 버퍼의 재생이 시작 된다. 어플리케이션이 DSSCL_WRITEPRIMARY 의 협조 레벨로 설정되어 있는 경우는, 어플리케이션에 의해 프라이머리 버퍼에 놓여진 임의의 오디오 데이터가 사운드 디바이스에 보내진다. 어플리케이션이 다른 협조 레벨로 설정되어 있는 경우는, 세칸다리밧파가 재생되어 있지 않으면 프라이머리 버퍼는 무음이 된다. 프라이머리 버퍼는, DSBPLAY_LOOPING 플래그로 재생해야 한다. 상세한 것에 대하여는, 「프라이머리 버퍼의 연속 재생」을 참조할것.

이 메소드가 DSBCAPS_LOCDEFER 플래그로 생성되어 있지 않은 버퍼상으로 설정된 음성 할당 플래그, 또는 음성 관리 플래그로 불려 가면(자), 이 호출은 실패해, DSERR_INVALIDPARAM 가 돌려주어진다.

DSBPLAY_TERMINATEBY_TIME 와 DSBPLAY_TERMINATEBY_DISTANCE 를 조합할 수 없지만, 이 어느 쪽일까하고 DSBPLAY_TERMINATEBY_PRIORITY 를 조합할 수가 있다. 이 경우, DSBPLAY_TERMINATEBY_TIME 또는 DSBPLAY_TERMINATEBY_DISTANCE 플래그는, 우선도가 동일한 경우에 어느 버퍼를 종료해야할 것인가를 결정하기 위해서(때문에) 사용된다.

다음의 표는, 하드웨어 음성의 빈 곳을 이용할 수 없는 경우에, 음성 할당 플래그와 음성 관리 플래그의 편성에 의해 정해지는 메소드의 동작을 나타내고 있다.

 | DSBPLAY_LOCHARDWARE | DSBPLAY_LOCHARDWARE 과 DSBPLAY_LOCSOFTWARE 의 어느쪽이나 사용하지 않는다 | DSBPLAY_LOCSOFTWARE
DSBPLAY_TERMINATEBY_TIME | 재생의 남은 시간이 가장 적은 사운드를 종료해, 새로운 사운드를 해방한 음성으로 재생한다. | 재생의 남은 시간이 가장 적은 사운드를 종료해, 새로운 사운드를 해방한 음성으로 재생한다. | 새로운 사운드를 소프트웨어로 재생한다.
DSBPLAY_TERMINATEBY_DISTANCE | 하드웨어로 현재 재생중의 사운드가 최대 거리를 넘고 있어 DSBCAPS_MUTE3DATMAXDISTANCE 플래그가 설정되어 있는 경우, 그 어느쪽이든을 종료해, 새로운 사운드를 하드웨어로 재생한다. 그 이외의 경우, 이 호출은 실패한다. | 하드웨어로 현재 재생중의 사운드가 최대 거리를 넘고 있어 DSBCAPS_MUTE3DATMAXDISTANCE 플래그가 설정되어 있는 경우, 그 어느쪽이든을 종료해, 새로운 사운드를 하드웨어로 재생한다. 그 이외의 경우는, 새로운 사운드를 소프트웨어로 재생한다. | 새로운 사운드를 소프트웨어로 재생한다.
DSBPLAY_TERMINATEBY_PRIORITY | 새로운 사운드의 우선도가 하드웨어로 현재 재생중의 사운드보다 높은가 같은 경우, 우선도의 가장 낮은 사운드를 종료해, 새로운 사운드를 하드웨어로 재생한다. 그 이외의 경우, 이 호출은 실패한다. | 새로운 사운드의 우선도가 하드웨어로 현재 재생중의 사운드보다 높은가 같은 경우, 우선도의 가장 낮은 사운드를 종료해, 새로운 사운드를 하드웨어로 재생한다. 그 이외의 경우는, 새로운 사운드를 소프트웨어로 재생한다. | 새로운 사운드를 소프트웨어로 재생한다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8 ,IDirectSound8::SetCooperativeLevel


IDirectSoundBuffer8::Restore

지정된 DirectSoundBuffer 오브젝트에 관련지을 수 있고 있던, 없어진 사운드 버퍼에의 메모리 할당을 복원한다.

HRESULT Restore();

파라미터

없음.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

어플리케이션에 입력초점이 놓여지지 않으면IDirectSoundBuffer8::Restore 는 성공하지 않는 것이 있다. 예를 들어, 입력초점이 놓여져 있는 어플리케이션이 DSSCL_WRITEPRIMARY (기입 우선) 협조 레벨로 설정되어 있는 경우, 다른 어느 어플리케이션도 버퍼를 복원할 수 없다. (와)과 같이 DSSCL_WRITEPRIMARY 협조 레벨의 어플리케이션이프라이머리 사운드 버퍼를 복원하려면 , 입력초점이 필요하다.

DirectSound 가 버퍼 메모리를 복원한 후, 유효한 사운드 데이터를 다시 기입할 필요가 있다. DirectSound 는 메모리를 복원하지만, 메모리의 내용은 복원할 수 없다.

어플리케이션은 버퍼를 지정해 IDirectSoundBuffer8::Lock 또는 IDirectSoundBuffer8::Play 의 각 메소드를 호출하면, 그 버퍼가 없어지고 있는 경우에 통지를 받게 된다. 버퍼가 없어지고 있는 경우, 이러한 메소드는 DSERR_BUFFERLOST 를 돌려준다. IDirectSoundBuffer8::GetStatus 메소드를 사용해, 사운드 버퍼의 스테이터스의 취득과 DSBSTATUS_BUFFERLOST 플래그의 테스트를 실시할 수도 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::Lock ,IDirectSoundBuffer8::Play ,IDirectSoundBuffer8::GetStatus


IDirectSoundBuffer8::SetCurrentPosition

재생 커서의 위치를 설정한다. 버퍼로부터 다음의 데이터 바이트를 읽어들일 수 있는 위치를 나타낸다.

HRESULT SetCurrentPosition(
  DWORD dwNewPosition
);

파라미터

dwNewPosition
버퍼의 선두로부터의 재생 커서의 오프셋(offset) (바이트 단위).

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

프라이머리 사운드 버퍼에 대해서는, 이 메소드를 호출할 수 없다.

버퍼가 재생중의 경우, 커서는 즉시 새로운 위치로 이동해, 재생은 그 위치로부터 속행된다. 버퍼가 정지하고 있는 경우는, 다음에 IDirectSoundBuffer8::Play 메소드를 호출했을 때에, 새로운 위치로부터 재생을 시작 한다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::GetCurrentPosition ,IDirectSoundBuffer8::Play


IDirectSoundBuffer8::SetFormat

어플리케이션용의프라이머리 사운드 버퍼의 포맷을 설정한다. 이 어플리케이션에 입력초점이 놓여질 때마다, DirectSound 는 프라이머리 버퍼가 지정된 포맷으로 설정한다.

프라이머리 사운드 버퍼는 IDirectSoundBuffer8 인터페이스를 지원 하고 있지 않기 때문에,IDirectSoundBuffer 로 이 메소드를 호출할 필요가 있다.

HRESULT SetFormat(
  LPCWAVEFORMATEX pcfxFormat
);

파라미터

pcfxFormat
WAVEFORMATEX 구조체의 주소. 이 구조체는, 프라이머리 사운드 버퍼의 새로운 포맷을 기술한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_BADFORMAT
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED
DSERR_UNSUPPORTED

주의

프라이머리 버퍼의 포맷은, 세칸다리밧파를 생성 하기 전으로 설정한다.

어플리케이션에 DSSCL_NORMAL 협조 레벨이 설정되어 있는 경우, 메소드는 실패한다.

어플리케이션이 DSSCL_WRITEPRIMARY 협조 레벨로 DirectSound 를 사용하고 있는 경우,IDirectSoundBuffer8::SetFormat 를 호출하기 전에 버퍼를 정지해야 한다. 포맷이 지원되어 있지 않은 경우, 메소드는 실패한다.

협조 레벨이 DSSCL_PRIORITY 또는 DSSCL_EXCLUSIVE 인 경우, DirectSound 는 프라이머리 버퍼를 정지해, 포맷을 변경해, 버퍼를 재개한다. 요구된 포맷을 하드웨어가 지원 하고 있지 않는 경우에서도, 메소드는 성공한다. DirectSound 는, 버퍼를 요구에 가장 가까운 포맷으로 설정한다. 이러한 상황이 발생하고 있을지 어떨지를 판단하려면 , 어플리케이션은 프라이머리 버퍼에 대해서 IDirectSoundBuffer8::GetFormat 메소드를 호출해, 그 결과를,SetFormat 메소드로 요구한 포맷과 비교한다.

이 메소드는 세칸다리사운드밧파에서는 이용할 수 없다. 새로운 포맷이 요구되었을 경우, 어플리케이션은 새로운 DirectSoundBuffer 오브젝트를 생성 해야 한다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8 ,IDirectSoundBuffer8::GetFormat


IDirectSoundBuffer8::SetFrequency

샘플링 오디오의 재생 주파수를 설정한다.

HRESULT SetFrequency(
  DWORD dwFrequency
);

파라미터

dwFrequency
샘플링 오디오를 재생하는 새로운 주파수 (Hz 단위). 값의 범위는 DSBFREQUENCY_MIN 로부터 DSBFREQUENCY_MAX 의 사이가 아니면 안된다. 현재 이러한 값은 dsound.h 내에서, 각각 100, 100,000 으로 정의되고 있다.

값이 DSBFREQUENCY_ORIGINAL 의 경우, 주파수는 버퍼 포맷내의 디폴트값에 리셋 된다. 이 포맷은 IDirectSound8::CreateSoundBuffer 메소드로 지정된 것이다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

주파수를 상하시키면(자), 오디오 데이터의 인식피치가 변화한다. 이 메소드는 버퍼의 포맷에는 영향을 미치지 않는다.

이 메소드는프라이머리 사운드 버퍼에는 유효하지 않다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound8::CreateSoundBuffer ,IDirectSoundBuffer8::GetFrequency ,IDirectSoundBuffer8::Play ,IDirectSoundBuffer8::SetFormat


IDirectSoundBuffer8::SetFX

버퍼의 이펙트를 유효하게 한다. 버퍼는 재생중에서 만나거나 락킹 되고 있어서는 안 된다.

이 메소드를 성공시키려면 ,CoInitialize 가 불려 가고 있을 필요가 있다. 이것은,IDirectMusicPerformance8::InitAudio 를 사용해 DirectSound 를 생성 하는 어플리케이션에서는, 자동적으로 실행된다. 그러나,DirectSoundCreate8 를 사용해 DirectSound 를 생성 하는 어플리케이션에서도,CoInitialize 를 호출할 필요가 있다.

HRESULT SetFX(
  DWORD dwEffectsCount,
  LPDSEFFECTDESC pDSFXDesc,
  LPDWORD pdwResultCodes
);

파라미터

dwEffectsCount
pDSFXDesc 배열 및 pdwResultCodes 배열의 요소수를 지정하는 값. 이 값이 0 의 경우,pDSFXDesc 및 pdwResultCodes 는 어느쪽이나 NULL 가 아니면 안된다. 0 으로 설정 하면, 버퍼의 모든 이펙트가 삭제된다.
pDSFXDesc
사이즈가 dwEffectsCount 의 DSEFFECTDESC 구조체의 배열의 주소. 버퍼의 이펙트를 지정한다. dwEffectsCount 가 0 의 경우는 NULL 가 아니면 안된다.
pdwResultCodes
사이즈가 dwEffectsCount 의 DWORD 요소의 배열의 주소. 각 요소는 다음의 몇개의 값을 받는다. 이러한 값은,pDSFXDesc 배열의 대응하는 이펙트를 생성 하려고 한 결과를 나타낸다.
DSFXR_LOCHARDWARE
이펙트는 하드웨어로 인스턴스화 된다.
DSFXR_LOCSOFTWARE
이펙트는 소프트웨어로 인스턴스화 된다.
DSFXR_UNALLOCATED
하드웨어 또는 소프트웨어에 아직 이펙트가 설정되어 있지 않다. 이 값이 돌려주어지는 것은, 그 버퍼가 DSBUFFERDESC 의 DSBCAPS_LOCDEFER 플래그를 사용해 생성 되고 있는 경우이다.
DSFXR_FAILED
리소스를 이용할 수 없었기 (위해)때문에, 이펙트는 생성되어 있지 않다.
DSFXR_PRESENT
이펙트는 이용할 수 있지만, 요구된 것 외의 이펙트의 1 개가 생성 할 수 없었기(위해)때문에 생성 할 수 없었다. 요구된 이펙트중 1 개(살)에서도 생성 할 수 없는 경우, 이펙트는 모두 생성 되지 않고, 호출은 실패한다.
DSFXR_UNKNOWN
지정된 이펙트는 시스템에 등록되지 않았다. 이 때문에, 메소드는 실패했다.

이 파라미터를 NULL 로 하면(자), 결과의 값이 돌려주어지지 않다. 또,dwEffectsCount 가 0 의 경우는, 이 파라미터를 NULL 로 하지 않으면 안 된다.

반환값

성공했을 경우는, DS_OK 또는 DS_INCOMPLETE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

CO_E_NOTINITIALIZED
DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_INVALIDCALL
DSERR_NOINTERFACE
DSERR_PRIOLEVELNEEDED

또, 이 메소드는,IMediaObject::SetInputType 이나 IMediaObject::SetOutputType. 등의 DMO 메소드의 에러값을 돌려준다. 돌려주어지는 에러값에 대해서는, DirectShow 의 문서를 참조할것.

주의

실패했을 경우, 각 이펙트의 pdwResultCodes 의 값은, DSFXF_PRESENT 또는 DSFXR_UNKNOWN 가 된다. 이러한 값을 조사하면(자), 어느 이펙트가 원인으로 실패했는지를 특정할 수 있다.

메소드를 성공시키려면 , 버퍼가 DSBCAPS_CTRLFX 플래그로 생성 되고 있을 필요가 있어, 또, 재생중에서 만나거나 락 되고 있어선 안 된다.

DSERR_NOINTERFACE 또는 그 외의 COM 에러가 돌려주어졌을 경우는, DSFXR_PRESENT 또는 DSFXR_UNKNOWN 의 결과 코드 배열을 확인해, 에러의 발생 원인이 된 이펙트를 조사한다. DSERR_INVALIDPARAM 가 돌려주어졌을 경우는, DSFXR_FAILED 의 결과 코드를 확인해, 리소스를 취득할 수 없었던 이펙트를 조사한다.

버퍼가 오디오 패스의 일부인 경우, 오디오 패스는 비액티브하지 않으면 안 된다. 「IDirectMusicAudioPath8::Activate 」를 참조할것.

이펙트 인터페이스를 취득하기 전에, 이펙트를 버퍼로 설정해야 한다. 이펙트 인터페이스를 취득하려면 ,IDirectSoundBuffer8::GetObjectInPath 를 사용한다.

동작환경

헤더 : dsound.h 로 선언.

참조

DSBCAPS ,IDirectSoundBuffer8::AcquireResources


IDirectSoundBuffer8::SetPan

좌우의 채널의 상대 볼륨을 설정한다.

HRESULT SetPan(
  LONG lPan
);

파라미터

lPan
좌우의 채널의 상대 볼륨.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

LPan 의 값은 DSBPAN_LEFT 로부터 DSBPAN_RIGHT 의 범위에서, 100 분의 1 데시벨 (dB) 단위로 측정된다. 현재 이러한 값은, Dsound.h 내에서 각각 -10, 000, 10,000 으로 정의되고 있다. 값 DSBPAN_LEFT 는 오른쪽 채널이 100 dB 감쇠하고 있는 것을 의미한다. 값 DSBPAN_RIGHT 는 왼쪽 채널이 100 dB 감쇠하고 있는 것을 의미한다. 중립값은 DSBPAN_CENTER 이며, 0 으로 정의되고 있다. plPan 파라미터가 0 일 때는, 양쪽 모두의 채널이 최대 볼륨인 것을 의미한다 (어느쪽이나 0 dB 의 감쇠이다). DSBPAN_CENTER 이외의 값은 모두, 한편이 최대 볼륨으로 이제(벌써) 한편이 감쇠하고 있는 것을 의미한다.

빵의 값이 -2, 173 때, 왼쪽 채널은 최대 볼륨으로, 오른쪽 채널은 21.73 dB 감쇠하고 있는 것을 의미한다. (와)과 같이 빵의 값이 870 때, 왼쪽 채널은 8.7 dB 감쇠하고 있어, 오른쪽 채널은 최대 볼륨인 것을 의미한다. DSBPAN_LEFT 의 빵은, 오른쪽 채널이 무음으로, 사운드가 왼쪽으로부터 마셔 발생하고 있는 것을 의미한다. 한편, DSBPAN_RIGHT 의 빵은, 왼쪽 채널이 무음으로, 사운드가 오른쪽으로부터 마셔 발생하고 있는 것을 의미한다.

빵 컨트롤의 효과는, 음량 조절에 누적된다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::GetPan ,IDirectSoundBuffer8::GetVolume ,IDirectSoundBuffer8::SetVolume


IDirectSoundBuffer8::SetVolume

사운드 볼륨을 설정한다.

HRESULT SetVolume(
  LONG lVolume
);

파라미터

lVolume
이 사운드 버퍼로 요구하는 새로운 볼륨.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

볼륨은 100 분의 1 데시벨 (dB) 단위로 지정된다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 현재 이러한 값은, Dsound.h 내에서 각각 0,-10, 000 으로 정의되고 있다. 값 DSBVOLUME_MAX 는, 스트림 본래의 미조정의 볼륨을 나타낸다. 값 DSBVOLUME_MIN 는, 오디오의 볼륨이 100 dB 감쇠하고 있는 것을 나타내지만, 이것은 실제적으로는 무음을 의미한다. 현재, DirectSound 는 증폭을 지원 하고 있지 않다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::GetPan ,IDirectSoundBuffer8::GetVolume ,IDirectSoundBuffer8::SetPan


IDirectSoundBuffer8::Stop

사운드 버퍼의 재생을 정지한다.

HRESULT Stop();

파라미터

없음.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

세칸다리사운드밧파에 대해서 IDirectSoundBuffer8::Stop 를 호출하면, 재생 커서가, 직전에 재생된 샘플의 직후의 샘플로 설정된다. 이것은, 그 버퍼에 대해서 다음에 IDirectSoundBuffer8::Play 메소드를 호출했을 때에, 이전에 재생을 정지한 장소로부터 재생이 재개되는 것을 의미한다.

DSSCL_WRITEPRIMARY 레벨로 설정된 어플리케이션이프라이머리 사운드 버퍼에 대해서 이 메소드를 호출하면, 이 메소드는 버퍼를 정지해, 재생 커서를 0 (버퍼의 선두)에 리셋 한다. 대부분의 사운드 카드는 버퍼의 선두로부터 마셔 재생을 실시할 수 있으므로, 이러한 처리가 필요하다.

그러나, 기입 우선 이외의 협조 레벨로 설정되어 있는 어플리케이션이, 프라이머리 버퍼에 대해서 IDirectSoundBuffer8::Stop 를 호출했을 경우는, 이 메소드는 IDirectSoundBuffer8::Play 와는 역의 이펙트를 가져오는 것만으로 있다. 세칸다리밧파가 재생되어 있지 않은 경우는, 프라이머리 버퍼를 정지하도록(듯이) 설정한다. 이 어플리케이션 또는 다른 어플리케이션이 다른 버퍼를 재생하고 있는 경우, 그러한 재생이 정지할 때까지 프라이머리 버퍼도 실제로는 정지하지 않는다. 비록 진폭이 0 dB 여도, 버퍼가 사운드 데이터를 재생하고 있는 경우는 처리의 오버헤드가 발생하므로, 이 메소드를 사용해 프라이머리 버퍼를 정지하는 것은 도움이 된다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::Play


IDirectSoundBuffer8::Unlock

사운드 버퍼를 언락 한다.

HRESULT Unlock(
  LPVOID pvAudioPtr1,
  DWORD dwAudioBytes1,
  LPVOID pvAudioPtr2,
  DWORD dwAudioBytes2
);

파라미터

pvAudioPtr1
IDirectSoundBuffer8::Lock 메소드의 ppvAudioPtr1 파라미터로 취득한 값의 주소.
dwAudioBytes1
버퍼의 pvAudioPtr1 로 나타내지는 위치에 기입하는 바이트수를 지정하는 값. 「주의」를 참조할것.
pvAudioPtr2
IDirectSoundBuffer8::Lock 메소드의 ppvAudioPtr2 파라미터로 취득한 값의 주소.
dwAudioBytes2
버퍼의 pvAudioPtr2 로 나타내지는 위치에 기입하는 바이트수를 지정하는 값. 「주의」를 참조할것.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

어플리케이션은,IDirectSoundBuffer8::Lock 메소드로 돌려주어지는 포인터 pvAudioPtr1 및 pvAudioPtr2 의 양쪽 모두를 건네주어,IDirectSoundBuffer8::Lock 와 IDirectSoundBuffer8::Unlock 의 대를 올바르게 지정해야 한다. 비록 2 번째의 포인터에 아무것도 기입해지지 않은 경우에서도, 2 번째의 포인터는 필요하다.

dwAudioBytes1 및 dwAudioBytes2 의 값은, 버퍼의 각 부분에 실제로 기입해지는 바이트수를 지정해야 한다. 락의 사이즈보다 작아지는 경우가 있다. DirectSound 는 이러한 값을 사용해, 디바이스에 위탁하는 데이터량을 결정한다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::GetCurrentPosition ,IDirectSoundBuffer8::Lock


IDirectSoundCapture8

IDirectSoundCapture8 인터페이스의 메소드는, 사운드 캡춰 버퍼를 생성 하기 위해서 사용된다.

인터페이스는,DirectSoundCaptureCreate8 함수 또는 DirectSoundFullDuplexCreate8 함수를 사용해 취득하는지,CoCreateInstance 또는 CoCreateInstanceEx 를 사용해, 클래스 CLSID_DirectSoundCapture8 의 오브젝트를 생성 한다.

IDirectSoundCapture8 은,IDirectSoundCapture 의 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다. 다만, 이 인터페이스를 지원 하고 있는 오브젝트는, 클래스에 의해 기능이 다르다. 상세한 것에 대하여는, 「DirectSoundCaptureCreate8 」 및 「IDirectSoundCapture8::CreateCaptureBuffer 」를 참조할것.

IDirectSoundCapture8 인터페이스의 메소드는, 다음의 그룹에 정리할 수가 있다.

생성 | CreateCaptureBuffer
 | Initialize
능력 | GetCaps

모든 COM 인터페이스와 같게,IDirectSoundCapture8 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTURE 형은,IDirectSoundCapture 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundCapture   *LPDIRECTSOUNDCAPTURE;

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCapture8::CreateCaptureBuffer

캡춰 버퍼를 생성 한다.

HRESULT CreateCaptureBuffer(
  LPCDSCBUFFERDESC pcDSCBufferDesc,
  LPDIRECTSOUNDCAPTUREBUFFER * ppDSCBuffer,
  LPUNKNOWN pUnkOuter
);

파라미터

pcDSCBufferDesc
DSCBUFFERDESC 구조체에의 포인터. 이 구조체는, 생성 되는 캡춰 버퍼용의 값을 보관 유지하고 있다.
ppDSCBuffer
IDirectSoundCaptureBuffer 인터페이스 포인터를 받는 변수의 주소. IDirectSoundCaptureBuffer8 를 취득하려면 ,QueryInterface 를 사용한다. 「주의」를 참조할것.
pUnkOuter
COM 집성체에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소. NULL 가 아니면 안된다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_BADFORMAT
DSERR_GENERIC
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

주의

Microsoft® Windows® 95, Windows® 98, 및 Windows® 2000 에서는, 각 캡춰 디바이스가 단일의 버퍼를 지원 한다.

IDirectSoundCaptureBuffer8 인터페이스는, CLSID_DirectSoundCapture8 클래스의 오브젝트로 생성 된 버퍼만으로 지원 된다. IDirectSoundCapture8 인터페이스를 DirectSoundCaptureCreate8 로부터 취득했을 경우는,IDirectSoundCaptureBuffer8 가 지원 된다. IDirectSoundCapture8 을 이전의 DirectSoundCaptureCreate 함수로부터 취득했을 경우는,IDirectSoundCaptureBuffer 만이 지원 된다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCapture8::GetCaps

캡춰 디바이스의 능력을 취득한다.

HRESULT GetCaps(
  LPDSCCAPS pDSCCaps
);

파라미터

pDSCCaps
캡춰 디바이스에 관한 정보를 받는 DSCCAPS 구조체에의 포인터. 이 메소드를 호출하려면 ,dwSize 멤버는 구조체의 사이즈를 바이트 단위로 지정해야 한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCapture8::Initialize

CoCreateInstance 를 사용해 DirectSoundCapture 오브젝트를 생성 했을 경우, 오브젝트는 IDirectSoundCapture8::Initialize 메소드로 초기화해야 한다. DirectSoundCaptureCreate 함수를 사용해 오브젝트를 생성 했을 경우는, 이 메소드를 호출할 필요는 없다.

HRESULT Initialize(
  LPCGUID pcGuidDevice
);

파라미터

pcGuidDevice
DirectSoundCapture 오브젝트에 결합되는 사운드 드라이버를 지정하는 GUID 의 주소. 프라이머리 사운드 드라이버를 선택하려면 , NULL 또는 GUID_NULL 를 지정한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_ALREADYINITIALIZED

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8

사운드 캡춰 버퍼의 조작에 사용한다.

IDirectSoundCaptureBuffer8 인터페이스를 취득하려면 ,IDirectSoundCapture8::CreateCaptureBuffer 메소드를 호출해 IDirectSoundCaptureBuffer 를 취득해, IID_IDirectSoundCaptureBuffer8 를 IDirectSoundCaptureBuffer::QueryInterface 에 건네준다.

주 DirectSoundCaptureCreate 함수를 사용해 IDirectSoundCapture8 인터페이스를 취득했을 경우는,IDirectSoundCaptureBuffer8 를 취득할 수 없다. 「DirectSoundCaptureCreate8 」를 참조할것.

이 인터페이스의 메소드는, 다음의 그룹에 정리할 수가 있다.

캡춰 관리 | Lock
 | Start
 | Stop
 | Unlock
이펙트 | GetFXStatus
 | GetObjectInPath
초기화 | Initialize
정보 | GetCaps
 | GetCurrentPosition
 | GetFormat
 | GetStatus

모든 COM 인터페이스와 같게, 이 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTUREBUFFER8 형은,IDirectSoundCaptureBuffer8 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundCaptureBuffer8 *LPDIRECTSOUNDCAPTUREBUFFER8;

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::GetCaps

버퍼의 능력을 돌려준다.

HRESULT GetCaps(
  LPDSCBCAPS pDSCBCaps
);

파라미터

pDSCBCaps
캡춰 버퍼에 관한 정보를 받는 DSCBCAPS 구조체에의 포인터. 입력시에,dwSize 멤버는 구조체의 사이즈를 바이트 단위로 지정해야 한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_OUTOFMEMORY

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::GetCurrentPosition

버퍼중의 캡춰 커서 및 읽어들여 커서를 취득한다.

캡춰 커서는, read 커서보다 전방에 있다. read 위치에서(보다) 다음에 캡춰 위치보다 전의 데이터는 (캡춰 위치를 포함한다), 반드시 유효한 데이터라고는 할 수 없다.

HRESULT GetCurrentPosition(
  LPDWORD pdwCapturePosition,
  LPDWORD pdwReadPosition
);

파라미터

pdwCapturePosition
캡춰 커서의 버퍼의 선두로부터의 오프셋(offset)를 받는 변수의 주소 (바이트 단위). 이 값이 필요없는 경우는, 파라미터를 NULL 로 설정할 수 있다.
pdwReadPosition
read 커서의 버퍼의 선두로부터의 오프셋(offset)를 받는 변수의 주소 (바이트 단위).

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::GetFormat

캡춰 버퍼의 포맷을 취득한다.

HRESULT GetFormat(
  LPWAVEFORMATEX pwfxFormat,
  DWORD dwSizeAllocated,
  LPDWORD pdwSizeWritten
);

파라미터

pwfxFormat
캡춰 버퍼내의 사운드 데이터에 관한 정보를 받는 WAVEFORMATEX 구조체의 주소. 포맷의 기술을 보관 유지하기 위해서 필요한 버퍼 사이즈를 취득하려면 NULL 를 지정한다. 이 경우,pdwSizeWritten 파라미터가 가리키는 DWORD 로, 완전한 포맷 정보를 받기 위해서(때문에) 필요한 구조체의 사이즈를 받는다.
dwSizeAllocated
WAVEFORMATEX 구조체의 사이즈 (바이트 단위). DirectSoundCapture 가 구조체에 기입하는 바이트수는, 최대로 dwSizeAllocated 바이트이다. 구조체가 그것보다 많은 메모리를 필요로 하는 경우, 잘라서 버림을 한다.
pdwSizeWritten
WAVEFORMATEX 구조체에 기입해진 바이트수를 받는 변수의 주소. 또는,pwfxFormat 가 NULL 의 경우는, 정보를 받기 위해서(때문에) 필요한 WAVEFORMATEX 구조체의 사이즈. 값이 필요하지 않은 경우, 이 파라미터를 NULL 로 한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::GetFXStatus

캡춰 버퍼의 이펙트의 스테이터스를 취득한다.

HRESULT GetFXStatus(
  DWORD dwFXCount,
  LPDWORD pdwFXStatus
);

파라미터

dwFXCount
pdwFXStatus 배열의 요소수를 지정하는 값.
pdwFXStatus
각 이펙트의 스테이터스를 받는 DWORD 변수의 배열의 주소. 이 파라미터에는,IDirectSoundCapture8::CreateCaptureBuffer 의 lpDSCFXDesc 파라미터로 건네받는 배열과 같은 수의 요소가 포함된다. 각 이펙트에 대해서, 다음의 몇개의 플래그가 돌려주어진다.
DSCFXR_LOCHARDWARE
이펙트는 하드웨어로 인스턴스화 된다.
DSCFXR_LOCSOFTWARE
이펙트는 소프트웨어로 인스턴스화 된다.
DSCFXR_UNALLOCATED
하드웨어 또는 소프트웨어에 아직 이펙트가 설정되어 있지 않다.
DSCFXR_FAILED
리소스를 이용할 수 없었기 (위해)때문에, 이펙트는 생성되어 있지 않다.
DSCFXR_UNKNOWN
이펙트가 시스템에 등록되지 않기 때문에, 이펙트는 생성되어 있지 않다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::GetObjectInPath

버퍼에 관련지을 수 있었던 이펙트 오브젝트의 인터페이스를 취득한다.

HRESULT GetObjectInPath(
  REFGUID rguidObject,
  DWORD dwIndex,
  REFGUID rguidInterface,
  LPVOID * ppObject
);

파라미터

rguidObject
검색하는 오브젝트의 일의의 클래스 식별자를 지정하는 REFGUID 형의 값. 예를 들어, GUID_DSCFX_CLASS_AEC 등. 임의의 클래스의 오브젝트를 검색하는 경우는, 이 파라미터를 GUID_All_Objects 로 설정한다.
dwIndex
패스중의 클래스의 오브젝트내에서, 오브젝트의 인덱스를 지정하는 값. 「주의」를 참조할것.
rguidInterface
목적의 인터페이스의 일의의 식별자를 지정하는 값. 예를 들어, IID_IDirectSoundCaptureFXAec8 등.
ppObject
목적의 인터페이스 포인터를 받는 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
E_NOINTERFACE

주의

dwIndex 의 값은,IDirectSoundCapture8::CreateCaptureBuffer 에게 건네진 이펙트의 배열내에서의 오브젝트의 인덱스이다. 몇개의 이펙트가 아직 생성되어 있지 않은 경우가 있기 (위해)때문에, 이펙트내의 실제의 오브젝트의 위치를 나타내고 있다고는 할 수 없다.

오브젝트는,rguidObject 및 dwIndex 와의 일치인 만큼 기초를 두어 돌려주어진다. rguidInterface 가 그 오브젝트로 사용되고 있는 인터페이스를 나타내고 있을지 어떨지는, 어플리케이션측에서 확인할 필요가 있다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::GetStatus

캡춰 버퍼의 스테이터스를 취득한다.

HRESULT GetStatus(
  LPDWORD pdwStatus
);

파라미터

pdwStatus
캡춰 버퍼의 스테이터스를 받는 변수의 주소. 스테이터스로서 다음의 값의 1 개 또는 복수를 설정할 수 있다.
DSCBSTATUS_CAPTURING
버퍼는 현재 오디오 데이터를 캡춰 하고 있다.
DSCBSTATUS_LOOPING
버퍼는 현재 루프 하고 있다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::Initialize

초기화되어 있지 않은 DirectSoundCaptureBuffer 오브젝트를 초기화한다.

HRESULT Initialize(
  LPDIRECTSOUNDCAPTURE pDirectSoundCapture,
  LPCDSCBUFFERDESC pcDSCBufferDesc
);

파라미터

pDirectSoundCapture
DirectSoundCaptureBuffer 오브젝트에 관련지을 수 있었던 DirectSoundCapture 오브젝트의 주소.
pcDSCBufferDesc
이 사운드 버퍼를 초기화하기 위해서 사용되는 값을 보관 유지하는 DSCBUFFERDESC 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_ALREADYINITIALIZED

주의

IDirectSoundCapture8::CreateCaptureBuffer 메소드는 내부에서 IdirectSoundCaptureBuffer8::Initialize 메소드를 호출하므로, 현재의 릴리스의 DirectSound 에서는 Initialize 를 명시적으로 호출할 필요는 없다. Initialize 메소드는 장래의 확장성에 대비해 준비되어 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

DSBUFFERDESC ,IDirectSoundCapture8::CreateCaptureBuffer


IDirectSoundCaptureBuffer8::Lock

버퍼를 잠근다. 버퍼를 잠그면(자), 그 버퍼에의 포인터가 돌려주어져 어플리케이션이 그 메모리에 대해서 오디오 데이터를 읽고 쓰기할 수 있게 된다.

HRESULT Lock(
  DWORD dwOffset,
  DWORD dwBytes,
  LPVOID *ppvAudioPtr1,
  LPDWORD pdwAudioBytes1,
  LPVOID *ppvAudioPtr2,
  LPDWORD pdwAudioBytes2,
  DWORD dwFlags
);

파라미터

dwOffset
버퍼의 선두로부터 락 시작 위치까지의 오프셋(offset)를 바이트 단위로 지정하는 값.
dwBytes
락 되는 버퍼 부분의 사이즈를 바이트 단위로 지정하는 값. 버퍼는 개념적으로는 순환 버퍼이기 (위해)때문에, 이 수는 dwOffset 로부터 버퍼의 끝까지의 사이의 바이트수를 웃돌 수가 있다.
ppvAudioPtr1
버퍼의 최초로 락 된 부분에의 포인터를 받는 변수의 주소.
pdwAudioBytes1
블록의 바이트수를 ppvAudioPtr1 로 받는 변수의 주소. 이 값이 dwBytes 보다 작은 경우, 락은 랩 되어ppvAudioPtr2 는 버퍼의 선두에 있는 제 2 의 데이터 블록을 가리킨다.
ppvAudioPtr2
캡춰 버퍼의 2 번째에 락 된 부분에의 포인터를 받는 변수의 주소. NULL 가 돌려주어졌을 경우,ppvAudioPtr1 파라미터는 캡춰 버퍼의 락 된 부분 전체를 가리킨다.
pdwAudioBytes2
블록의 바이트수를 ppvAudioPtr2 로 받는 변수의 주소. ppvAudioPtr2 가 NULL 의 경우, 값은 0 이다.
dwFlags
락 이벤트로 변경을 더하는 플래그. 이 값은 NULL 또는 다음의 플래그이다.
DSCBLOCK_ENTIREBUFFER
dwReadBytes 를 무시해, 캡춰 버퍼 전체를 잠근다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

주의

이 메소드는, 오프셋(offset)와 바이트 카운트를 받아, 2 개의 read 포인터와 각각 관련하는 사이즈를 돌려준다. 락 되는 부분이 버퍼의 끝까지 확장하지 않고, 버퍼의 선두에 랩 되지 않는 경우, 2 번째의 포인터인 ppvAudioBytes2 는 NULL 를 받는다. 락이 랩 되는 경우,ppvAudioBytes2 는 버퍼의 선두에의 포인터를 가리킨다.

어플리케이션이 ppvAudioPtr2 파라미터 및 pdwAudioBytes2 파라미터에 대해서 NULL 를 건네주면(자), 락이 버퍼의 종단을 넘을 것은 없고, 랩 되지 않는다.

어플리케이션은, 이 메소드로 돌려주어진 포인터로부터 데이터를 읽어들이면(자), 즉시 IDirectSoundCaptureBuffer8::Unlock 를 호출할 필요가 있다. 사운드 버퍼는, 동작중에 잠근 채로 해서는 안된다. 잠근 채로 하면(자), 캡춰 커서가 락 된 바이트 영역에 이르러, 오디오의 문제가 발생한다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::Start

버퍼에의 데이터의 캡춰 링을 시작 한다. 버퍼가 이미 캡춰 링 하고 있는 경우, 이 메소드는 아무것도 하지 않는다.

HRESULT Start(
  DWORD dwFlags
);

파라미터

dwFlags
사운드 데이터를 캡춰 링 하면나무의 버퍼의 동작을 지정하는 플래그. 다음의 플래그가 정의되고 있다.
DSCBSTART_LOOPING
버퍼의 마지막에 달하면(자), 선두로부터 캡춰를 재개해, 명시적으로 정지될 때까지 속행한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::Stop

버퍼를 정지해, 데이터의 캡춰 링을 종료한다. 버퍼가 캡춰 링 하고 있지 않는 경우, 이 메소드는 아무것도 하지 않는다.

HRESULT Stop();

파라미터

없음.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_NODRIVER
DSERR_OUTOFMEMORY

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureBuffer8::Unlock

버퍼를 언락 한다.

HRESULT Unlock(
  LPVOID pvAudioPtr1,
  DWORD dwAudioBytes1,
  LPVOID pvAudioPtr2,
  DWORD dwAudioBytes2
);

파라미터

pvAudioPtr1
IDirectSoundCaptureBuffer8::Lock 메소드의 ppvAudioPtr1 파라미터로 취득한 값의 주소.
dwAudioBytes1
pvAudioPtr1 파라미터로부터 읽어들이는 바이트수. 「주의」를 참조할것.
pvAudioPtr2
IDirectSoundCaptureBuffer8::Lock 메소드의 ppvAudioPtr2 파라미터로 취득한 값의 주소.
dwAudioBytes2
pvAudioPtr2 파라미터로부터 읽어들이는 바이트수. 「주의」를 참조할것.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

주의

어플리케이션은,IDirectSoundBuffer8::Lock 메소드로 돌려주어지는 포인터 pvAudioPtr1 및 pvAudioPtr2 의 양쪽 모두를 건네주어,IDirectSoundBuffer8::Lock 와 IDirectSoundBuffer8::Unlock 의 대를 올바르게 지정해야 한다. 비록 2 번째의 포인터에 0 바이트가 기입해졌을 경우에서도, 2 번째의 포인터는 필요하다.

dwAudioBytes1 및 dwAudioBytes2 의 값은, 버퍼의 각 부분으로부터 실제로 읽어들이는 바이트수를 지정해야 한다. 락의 사이즈보다 작아지는 경우도 있다. DirectSound 는 이러한 값을 사용해, 디바이스로부터 전송 하는 데이터량을 결정한다.

사운드 캡춰 버퍼의 락 상태를 장시간 유지하지 않게 주의 해야 한다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureFXAec8

현재의 operating system상에 이행되어 있지 않다.

청감 메아리 해제를 지원 하는 캡춰 버퍼로, 파라미터의 설정 및 취득에 사용한다.

IDirectSoundCaptureFXAec8 는,IDirectSoundCaptureFXAec 의 정의이다. 인터페이스명은 바꿔 넣고 가능하다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundCaptureBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundCaptureFXAec8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스와 같게,IDirectSoundCaptureFXAec8 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTUREFXAEC8 형은,IDirectSoundCaptureFXAec8 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundCaptureFXAec8 *LPDIRECTSOUNDCAPTUREFXAEC8;

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureFXAec8::GetAllParameters

현재의 operating system상에 이행되어 있지 않다.

버퍼의 청감 메아리 해제 파라미터를 취득한다.

HRESULT GetAllParameters(
  LPDSCFXAec pDscFxAec
);

파라미터

pDscFxAec
이펙트 파라미터를 받는 DSCFXAec 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureFXAec8::SetAllParameters

현재의 operating system상에 이행되어 있지 않다.

버퍼의 청감 메아리 해제 파라미터를 설정한다.

HRESULT SetAllParameters(
  LPCDSCFXAec  pcDscFxAec
);

파라미터

pcDscFxAec
이펙트 파라미터를 지정하는 DSCFXAec 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureFXNoiseSuppress8

현재의 operating system상에 이행되어 있지 않다.

노이즈 억제를 지원 하는 캡춰 버퍼로, 파라미터의 설정 및 취득에 사용한다.

IDirectSoundCaptureFXNoiseSuppress8 는 IDirectSoundCaptureFXNoiseSuppress 의 정의이다. 인터페이스명은 바꿔 넣고 가능하다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundCaptureBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundCaptureFXNoiseSuppress8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스와 같게,IDirectSoundNoiseSuppress8 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDNOISESUPPRESS8 형은,IDirectSoundNoiseSuppress8 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundCaptureFXNoiseSuppress8  *LPDIRECTSOUNDCAPTUREFXNOISESUPPRESS8;

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureFXNoiseSuppress8::GetAllParameters

현재의 operating system상에 이행되어 있지 않다.

버퍼의 노이즈 억제 파라미터를 취득한다.

HRESULT GetAllParameters(
  LPDSCFXNoiseSuppress pDsFxNoiseSuppress
);

파라미터

pDscFxNoiseSuppress
이펙트 파라미터를 받는 DSCFXNoiseSuppress 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundCaptureFXNoiseSuppress8::SetAllParameters

현재의 operating system상에 이행되어 있지 않다.

버퍼의 노이즈 억제 파라미터를 설정한다.

HRESULT SetAllParameters(
  LPCDSCFXNoiseSuppression  pcDscFxNoiseSuppress
);

파라미터

pcDscFxNoiseSuppress
이펙트 파라미터를 받는 DSCFXNoiseSuppress 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFullDuplex8

현재의 operating system상에 이행되어 있지 않다.

전이중 스트림을 나타낸다.

이 인터페이스는,DirectSoundFullDuplexCreate8 함수를 사용해 취득한다. 이 함수는, DirectSound 캡춰와 재생을 초기화한다.

인터페이스를 CoCreateInstance 또는 CoCreateInstanceEx 를 사용해 취득해, 클래스 CLSID_DirectSoundFullDuplex8 의 오브젝트를 생성 할 수도 있다.

IDirectSoundFullDuplex8 는 IDirectSoundFullDuplex 의 정의이다. 인터페이스명은 바꿔 넣고 가능하다.

이 인터페이스는, 다음의 메소드를 지원 한다.

초기화 Initialize

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDFULLDUPLEX 형은,IDirectSoundFullDuplex 에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundFullDuplex *LPDIRECTSOUNDFULLDUPLEX;

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFullDuplex8::Initialize

CoCreateInstance 를 사용해 생성 된 전이중 오브젝트를 초기화한다.

HRESULT Initialize(
  LPCGUID  pCaptureGuid,
  LPCGUID  pRenderGuid,
  LPCDSCBUFFERDESC  lpDscBufferDesc,
  LPCDSBUFFERDESC  lpDsBufferDesc,
  HWND  hWnd,
  DWORD  dwLevel,
  LPLPDIRECTSOUNDCAPTUREBUFFER8  lplpDirectSoundCaptureBuffer8,
  LPLPDIRECTSOUNDBUFFER8  lplpDirectSoundBuffer8
);

파라미터

pCaptureGuid
전이중 입력에 대해서 사운드 캡춰 디바이스를 식별하는 GUID 의 주소. DirectSoundCaptureEnumerate 가 돌려주는 GUID 의 언젠가, 디폴트의 캡춰 디바이스를 지정하는 NULL, 또는 다음의 값의 언젠가가 아니면 안된다.
DSDEVID_DefaultCapture
시스템 와이드인 디폴트의 오디오 캡춰 디바이스.
DSDEVID_DefaultVoiceCapture
디폴트의 음성 캡춰 디바이스.
pRenderGuid
전이중 출력에 대해서 사운드 렌더링 디바이스를 식별하는 GUID 의 주소. DirectSoundEnumerate 가 돌려주는 GUID 의 언젠가, 또는 디폴트의 렌더링 디바이스를 지정하는 NULL 가 아니면 안된다.
DSDEVID_DefaultPlayback
시스템 와이드인 디폴트의 오디오 재생 디바이스.
DSDEVID_DefaultVoicePlayback
디폴트의 음성 재생 디바이스.
lpDscBufferDesc
캡춰 버퍼의 특성을 지정하는 DSCBUFFERDESC 구조체의 주소.
lpDsBufferDesc
렌더링 버퍼의 특성을 지정하는 DSBUFFERDESC 구조체의 주소.
hWnd
어플리케이션 윈도우에의 핸들.
dwLevel
DirectSound 오브젝트의 협조 레벨. 상세한 것에 대하여는, 「IDirectSound8::SetCooperativeLevel 」를 참조할것.
lplpDirectSoundCaptureBuffer8
캡춰 버퍼의 IDirectSoundCaptureBuffer8 인터페이스를 받는 변수의 주소.
lplpDirectSoundBuffer8
렌더링 버퍼의 IDirectSoundBuffer8 인터페이스를 받는 변수의 주소.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXChorus8

코러스를 지원 하는 버퍼로, 이펙트 파라미터의 설정 및 취득에 사용한다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundFXChorus8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX


IDirectSoundFXChorus8::GetAllParameters

버퍼의 코러스 파라미터를 취득한다.

HRESULT GetAllParameters(
  LPDSFXChorus pDsFxChorus
);

파라미터

pDsFxChorus
이펙트 파라미터를 받는 DSFXChorus 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXChorus8::SetAllParameters

버퍼의 코러스 파라미터를 설정한다.

HRESULT SetAllParameters(
  LPCDSFXChorus  pcDsFxChorus
);

파라미터

pcDsFxChorus
이펙트 파라미터를 지정하는 DSFXChorus 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 을 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundFXCompressor8

압축을 지원 하는 버퍼로, 이펙트 파라미터의 설정 및 취득에 사용한다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundFXCompressor8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX ,콘프렛션


IDirectSoundFXCompressor8::GetAllParameters

버퍼의 압력 파라미터를 취득한다.

HRESULT GetAllParameters(
  LPDSFXCompressor pDsFxCompressor
);

파라미터

pDsFxCompressor
이펙트 파라미터를 받는 DSFXCompressor 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXCompressor8::SetAllParameters

버퍼의 압력 파라미터를 설정한다.

HRESULT SetAllParameters(
  LPCDSFXCompressor pcDsFxCompressor
);

파라미터

pcDsFxCompressor
이펙트 파라미터를 지정하는 DSFXCompressor 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundFXDistortion8

뒤틀림을 지원 하는 버퍼로, 이펙트 파라미터의 설정 및 취득에 사용한다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundFXDistortion8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX


IDirectSoundFXDistortion8::GetAllParameters

버퍼의 뒤틀림 파라미터를 취득한다.

HRESULT GetAllParameters(
  LPDSFXDistortion  pDsFxDistortion
);

파라미터

pDsFxDistortion
이펙트 파라미터를 받는 DSFXDistortion 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXDistortion8::SetAllParameters

버퍼의 뒤틀림 파라미터를 설정한다.

HRESULT SetAllParameters(
  LPCDSFXDistortion  pcDsFxDistortion
);

파라미터

pcDsFxDistortion
이펙트 파라미터를 지정하는 DSFXDistortion 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundFXEcho8

메아리를 지원 하는 버퍼로, 이펙트 파라미터의 설정 및 취득에 사용한다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundFXEcho8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX


IDirectSoundFXEcho8::GetAllParameters

버퍼의 메아리 파라미터를 취득한다.

HRESULT GetAllParameters(
  LPDSFXEcho pDsFxEcho
);

파라미터

pDsFxEcho
이펙트 파라미터를 받는 DSFXEcho 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXEcho8::SetAllParameters

버퍼의 메아리 파라미터를 설정한다.

HRESULT SetAllParameters(
  LPCDSFXEcho  pcDsFxEcho
);

파라미터

pcDsFxEcho
이펙트 파라미터를 지정하는 DSFXEcho 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundFXFlanger8

플랜지를 지원 하는 버퍼로, 이펙트 파라미터의 설정 및 취득에 사용한다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundFXFlanger8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX


IDirectSoundFXFlanger8::GetAllParameters

버퍼의 플랜지 파라미터를 취득한다.

HRESULT GetAllParameters(
  LPDSFXFlanger  pDsFxFlanger
);

파라미터

pDsFxFlanger
이펙트 파라미터를 받는 DSFXFlanger 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXFlanger8::SetAllParameters

버퍼의 플랜지 파라미터를 설정한다.

HRESULT SetAllParameters(
  LPCDSFXFlanger pcDsFxFlanger
);

파라미터

pcDsFxFlanger
이펙트 파라미터를 지정하는 DSFXFlanger 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundFXGargle8

진폭변조를 지원 하는 버퍼로, 이펙트 파라미터의 설정 및 취득에 사용한다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundFXGargle8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX


IDirectSoundFXGargle8::GetAllParameters

버퍼의 진폭변조 파라미터를 취득한다.

HRESULT GetAllParameters(
  LPDSFXGargle  pDsFxGargle
);

파라미터

pDsFxGargle
이펙트 파라미터를 받는 DSFXGargle 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXGargle8::SetAllParameters

버퍼의 진폭변조 파라미터를 설정한다.

HRESULT SetAllParameters(
  LPCDSFXGargle  pcDsFxGargle
);

파라미터

pcDsFxGargle
이펙트 파라미터를 지정하는 DSFXGargle 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundFXI3DL2Reverb8

I3DL2 (Interactive 3D Audio Level 2) 리바브에페크트를 지원 하는 버퍼로, 이펙트 파라미터의 설정 및 취득에 사용한다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundFXI3DL2Reverb8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | GetQuality
 | SetAllParameters
 | SetQuality
pre-set | GetPreset
 | SetPreset

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX


IDirectSoundFXI3DL2Reverb8::GetAllParameters

버퍼의 I3DL2 환경 리바브파라메이타를 취득한다.

HRESULT GetAllParameters(
  LPDSFXI3DL2Reverb pDsFxI3DL2Reverb
);

파라미터

pDsFxI3DL2Reverb
이펙트 파라미터를 받는 DSFXI3DL2Reverb 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXI3DL2Reverb8::GetPreset

버퍼의 표준 리바브파라메이타의 식별자를 취득한다.

HRESULT GetPreset(
  LPDWORD  pdwPreset
);

파라미터

pdwPreset

pre-set 식별자의 1 개를 받는 DWORD 의 주소. 정의 끝난 값의 일람에 대해서는, 「IDirectSoundFXI3DL2Reverb8::SetPreset 」를 참조할것.

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXI3DL2Reverb8::GetQuality

환경 리바브에페크트의 품질을 취득한다.

HRESULT GetQuality(
  LONG * plQuality
);

파라미터

plQuality
이펙트의 품질을 받는 LONG 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXI3DL2Reverb8::SetQuality


IDirectSoundFXI3DL2Reverb8::SetAllParameters

버퍼의 I3DL2 환경 리바브파라메이타를 설정한다.

HRESULT SetAllParameters(
  LPCDSFXI3DL2Reverb  pcDsFxI3DL2Reverb
);

파라미터

pcDsFxI3DL2Reverb
이펙트 파라미터를 지정하는 DSFXI3DL2Reverb 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundFXI3DL2Reverb8::SetPreset

버퍼의 표준 리바브파라메이타를 지정한다.

HRESULT SetPreset(
  DWORD  dwPreset
);

파라미터

dwPreset
pre-set를 지정하는 값. 다음의 정수가 열거된다. 미리 설정된 각 식별자에 관련하는 디폴트값에 대해서는, Dsound.h 를 참조할것.
DSFX_I3DL2_ENVIRONMENT_PRESET_DEFAULT
DSFX_I3DL2_ENVIRONMENT_PRESET_GENERIC
DSFX_I3DL2_ENVIRONMENT_PRESET_PADDEDCELL
DSFX_I3DL2_ENVIRONMENT_PRESET_ROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_BATHROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_LIVINGROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_STONEROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_AUDITORIUM
DSFX_I3DL2_ENVIRONMENT_PRESET_CONCERTHALL
DSFX_I3DL2_ENVIRONMENT_PRESET_CAVE
DSFX_I3DL2_ENVIRONMENT_PRESET_ARENA
DSFX_I3DL2_ENVIRONMENT_PRESET_HANGAR
DSFX_I3DL2_ENVIRONMENT_PRESET_CARPETEDHALLWAY
DSFX_I3DL2_ENVIRONMENT_PRESET_HALLWAY
DSFX_I3DL2_ENVIRONMENT_PRESET_STONECORRIDOR
DSFX_I3DL2_ENVIRONMENT_PRESET_ALLEY
DSFX_I3DL2_ENVIRONMENT_PRESET_FOREST
DSFX_I3DL2_ENVIRONMENT_PRESET_CITY
DSFX_I3DL2_ENVIRONMENT_PRESET_MOUNTAINS
DSFX_I3DL2_ENVIRONMENT_PRESET_QUARRY
DSFX_I3DL2_ENVIRONMENT_PRESET_PLAIN
DSFX_I3DL2_ENVIRONMENT_PRESET_PARKINGLOT
DSFX_I3DL2_ENVIRONMENT_PRESET_SEWERPIPE
DSFX_I3DL2_ENVIRONMENT_PRESET_UNDERWATER
DSFX_I3DL2_ENVIRONMENT_PRESET_SMALLROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMHALL
DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEHALL
DSFX_I3DL2_ENVIRONMENT_PRESET_PLATE

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundFXI3DL2Reverb8::SetQuality

환경 리바브에페크트의 품질을 설정한다. 높은 값을 설정 하면, 이펙트의 품질은 좋아지지만, 처리에 걸리는 시간이 길어진다.

HRESULT SetQuality(
  LONG lQuality
);

파라미터

lQuality
이펙트의 품질을 지정하는 값. 값의 범위는, DSFX_I3DL2REVERB_QUALITY_MIN 가 최소로 DSFX_I3DL2REVERB_QUALITY_MAX 가 최대. 디폴트는 2 이다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXI3DL2Reverb8::GetQuality ,이펙트 파라미터


IDirectSoundFXParamEq8

파라메트릭 이퀼라이저 이펙트를 지원 하는 버퍼로, 이펙트 파라미터의 설정 및 취득에 사용한다.

IDirectSoundFXParamEq8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX


IDirectSoundFXParamEq8::GetAllParameters

버퍼의 파라메트릭 이퀼라이저의 파라미터를 취득한다.

HRESULT GetAllParameters(
  LPDSFXParamEq pDsFxParamEq
);

파라미터

pDsFxParamEq
이펙트 파라미터를 받는 DSFXParamEq 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 을 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXParamEq8::SetAllParameters

버퍼의 파라메트릭 이퀼라이저의 파라미터를 설정한다.

HRESULT SetAllParameters(
  LPCDSFXParamEq  pcDsFxParamEq
);

파라미터

pcDsFxParamEq
이펙트 파라미터를 지정하는 DSFXParamEq 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundFXWavesReverb8

뮤직크리바브를 지원 하는 버퍼의 이펙트 파라미터의 설정 및 취득에 사용한다.

이 인터페이스는, 이펙트를 지원 하는 버퍼 위에의 IDirectSoundBuffer8::GetObjectInPath 를 호출하는 것에 의해 취득한다.

IDirectSoundFXWavesReverb8 인터페이스는, 다음의 메소드를 지원 한다.

파라미터 | GetAllParameters
 | SetAllParameters

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

주의

웨브리바브 DMO 는, Microsoft 에 라이센스 되고 있는 Waves MaxxVerb 테크놀러지에 근거하고 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundBuffer8::SetFX


IDirectSoundFXWavesReverb8::GetAllParameters

버퍼의 뮤직크리바브파라메이타를 취득한다.

HRESULT GetAllParameters(
  LPDSFXWavesReverb  pDsFXWavesReverb
);

파라미터

pDsFXWavesReverb
이펙트 파라미터를 받는 DSFXWavesReverb 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundFXWavesReverb8::SetAllParameters

버퍼의 뮤직크리바브파라메이타를 설정한다.

HRESULT SetAllParameters(
  LPCDSFXWavesReverb  pcDsFXWavesReverb
);

파라미터

pcDsFXWavesReverb
이펙트 파라미터를 지정하는 DSFXWavesReverb 구조체의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.

참조

이펙트 파라미터


IDirectSoundNotify8

재생 또는 캡춰 버퍼의 통지 이벤트를 설정한다.

IDirectSoundNotify8 는 IDirectSoundNotify 의 정의이다. 2 개의 인터페이스명은 바꿔 넣고 가능하다.

DirectSoundBuffer 오브젝트 위에의 기존의 인터페이스에 대해서 QueryInterface 메소드를 호출해, 이 인터페이스를 취득한다. 구체적인 예에 대해서는, 「재생 버퍼의 통지」를 참조할것.

IDirectSoundNotify 인터페이스는, 다음의 메소드를 지원 한다.

SetNotificationPositions

모든 COM 인터페이스와 같게,IDirectSoundNotify8 인터페이스도 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDNOTIFY 형은,IDirectSoundNotify 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundNotify    *LPDIRECTSOUNDNOTIFY;

동작환경

헤더 : dsound.h 로 선언.


IDirectSoundNotify8::SetNotificationPositions

통지 위치를 설정한다. 캡춰나 재생동안, 호출측이 제공한 배열내의 DSBPOSITIONNOTIFY 구조체의 어느쪽이든으로 지정되고 있는 오프셋(offset)에 읽어들여 또는 재생 커서가 달하면(자), 관련하는 이벤트가 시그널 송신된다.

HRESULT SetNotificationPositions(
  DWORD dwPositionNotifies,
  LPCDSBPOSITIONNOTIFY pcPositionNotifies
);

파라미터

dwPositionNotifies
DSBPOSITIONNOTIFY 구조체의 수.
pcPositionNotifies
DSBPOSITIONNOTIFY 구조체로부터 완성되는 배열에의 포인터.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY

주의

dwOffset 멤버로 값 DSBPN_OFFSETSTOP 를 지정 하면,IDirectSoundBuffer8::Stop 나 IdirectSoundCaptureBuffer8::Stop 메소드를 호출했을 때, 또는 버퍼의 마지막에 달해 루프 재생을 실시하지 않을 때에, 관련 이벤트를 시그널 송신하도록(듯이) DirectSound 에 지시할 수 있다. 이 값을 사용할 때는, 위치 통지 배열의 마지막 항목으로 해야 한다.

위치 통지 배열이 이미 설정되어 있는 경우는, 메소드에 의해 이전의 배열을 옮겨놓을 수 있다.

이 메소드를 호출하면나무는, 버퍼를 정지시키지 않으면 안 된다.

동작환경

헤더 : dsound.h 로 선언.


IKsPropertySet

드라이버는 이 인터페이스를 사용하는 것으로, API 를 확장하는 일 없이 이용할 수 있는 확장 기능을 제공할 수 있다. DirectSound 는, 사운드 드라이버의 프로퍼티에 액세스 할 수 있도록, 이 인터페이스를 지원 한다.

IKsPropertySet 인터페이스는, WDM KS (Win32® 드라이버 모델의 커넬 스트리밍) 아키텍쳐의 일부이다.

DirectSound 버퍼의 임의의 인터페이스의 QueryInterface 메소드를 호출해, 이 인터페이스를 취득한다.

IKsPropertySet 인터페이스는, 다음의 메소드를 지원 한다.

IKsPropertySet | Get
 | QuerySupport
 | Set

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 다음의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

헤더 : dsound.h 로 선언.


IKsPropertySet::Get

프로퍼티 세트내의 특정의 항목에 대응하는 데이터를 취득한다.

HRESULT Get(
  REFGUID rguidPropSet,
  ULONG ulId,
  LPVOID pInstanceData,
  ULONG ulInstanceLength,
  LPVOID pPropertyData,
  ULONG ulDataLength,
  PULONG pulBytesReturned
);

파라미터

rguidPropSet
액세스 해야 할 프로퍼티 세트를 나타내는 GUID 에의 참조 (C++) 또는 주소 (C).
ulId
액세스 해야 할 프로퍼티 세트내의 항목. 항목은 0 으로부터 시작되는 인덱스 번호를 할당할 수 있고 있어 특정의 프로퍼티 세트 GUID 에서는 항상 같다.
pInstanceData
Get 호출의 대상이 되는 인스턴스 데이터.
ulInstanceLength
pInstanceData 가 가리키는 바이트수.
pPropertyData
이 항목으로부터 취득되는 데이터.
ulDataLength
pPropertyData 가 가리키는 바이트수.
pulBytesReturned
pPropertyData 에 기입해진 바이트수를 받는 변수의 주소.

반환값

반환값은, 프로퍼티 세트의 설계자에 의해 결정된다.

성공했을 경우는 S_OK 를 돌려준다.

실패 하면, 메소드는 1 개의 E_POINTER 를 돌려준다.

주의

pInstanceData 와 pPropertyData 의 각 데이터의 포맷은, 항목 마다 다르다.

동작환경

헤더 : dsound.h 로 선언.


IKsPropertySet::QuerySupport

프로퍼티 세트내의 프로퍼티가, 포토 또는 디바이스에 의해 지원 되고 있는지 어떤지를 결정한다.

HRESULT QuerySupport(
  REFGUID rguidPropSet,
  ULONG ulId,
  PULONG pulTypeSupport
);

파라미터

rguidPropSet
문의해야 할 프로퍼티 세트를 나타내는 GUID 에의 참조 (C++) 또는 주소 (C).
ulId
액세스 해야 할 프로퍼티 세트내의 항목. 항목은 0 으로부터 시작되는 인덱스 번호를 할당할 수 있고 있어 특정의 프로퍼티 세트 GUID 에서는 항상 같다.
pulTypeSupport
프로퍼티의 지원에 관한 정보를 받는 변수의 주소. 이 변수는, 다음의 플래그의 머지않아인가 양쪽 모두를 받을 수가 있다. 「주의」를 참조할것.
KSPROPERTY_SUPPORT_GET
프로퍼티 항목은 취득할 수 있다.
KSPROPERTY_SUPPORT_SET
프로퍼티 항목은 설정할 수 있다.

반환값

반환값은, 프로퍼티 세트의 설계자에 의해 결정된다.

성공했을 경우는 S_OK 를 돌려준다. 「주의」를 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

E_NOTIMPL ( 「주의」를 참조)
E_POINTER

주의

세트내에서 특정의 프로퍼티를 지원 할지 어떨지는, 프로퍼티 세트의 정의에 의존한다. 관심이 있는 프로퍼티 세트에 대해서는, 하드웨어 메이커의 사양을 참조할것.

어느 사양에서는 프로퍼티가 지원되어 있지 않은 경우에 S_OK 를 돌려주어, 다른 사양에서는 E_NOTIMPL 를 돌려준다. 프로퍼티가 지원 되고 있는지 어떤지를 확인하려면 , 이 메소드의 반환값과pulTypeSupport 의 반환값의 양쪽 모두를 체크한다. S_OK 가 돌려주어져도,pulTypeSupport 에 유효한 플래그가 포함되지 않은 경우는, 그 프로퍼티는 지원되어 있지 않다.

동작환경

헤더 : dsound.h 로 선언.


IKsPropertySet::Set

프로퍼티 세트내의 특정의 프로퍼티의 값을 설정한다.

HRESULT Set(
  REFGUID rguidPropSet,
  ULONG ulId,
  LPVOID pInstanceData,
  ULONG ulInstanceLength,
  LPVOID pPropertyData,
  ULONG ulDataLength
);

파라미터

rguidPropSet
액세스 해야 할 프로퍼티 세트를 나타내는 GUID 에의 참조 (C++) 또는 주소 (C).
ulId
액세스 해야 할 프로퍼티 세트내의 항목. 항목은 0 으로부터 시작되는 인덱스 번호를 할당할 수 있고 있어 특정의 프로퍼티 세트 GUID 에서는 항상 같다.
pInstanceData
Set 호출의 대상이 되는 인스턴스 데이터. 이 조작을 실행할 수 있는 오브젝트가 포토내에 복수 존재하는 경우, 인스턴스 데이터는 어느 오브젝트를 사용해야할 것인가를 지정한다. DirectMusic® API 레벨에서는, 표준적인 프로퍼티 세트의 어느 항목도 인스턴스 데이터를 사용하지 않았다. 그러나, 벤더가 정의한 확장에서는, 인스턴스 데이터를 자유롭게 사용해도 좋다.
ulInstanceLength
pInstanceData 가 가리키는 바이트수.
pPropertyData
이 항목으로 설정되는 프로퍼티 데이터.
ulDataLength
pPropertyData 가 가리키는 바이트수.

반환값

반환값은, 프로퍼티 세트의 설계자에 의해 결정된다.

성공했을 경우는 S_OK 를 돌려준다.

실패 하면, 메소드는 1 개의 E_POINTER 를 돌려준다.

주의

pInstanceData 와 pPropertyData 의 각 데이터의 포맷은, 항목 마다 다르다.

동작환경

헤더 : dsound.h 로 선언.


DirectSound 콜백 함수

여기에서는, DirectSound 콜백 함수의 레퍼런스 정보를 기술한다.

  • DSEnumCallback


DSEnumCallback

DirectSound 드라이버를 열거하는 어플리케이션 정의 콜백 함수. 어플리케이션이 직전에 호출한 DirectSoundEnumerate 함수 또는 DirectSoundCaptureEnumerate 함수에 응답해, 시스템은 이 함수를 호출한다.

BOOL CALLBACK DSEnumCallback(
  LPGUID lpGuid,
  LPCSTR lpcstrDescription,
  LPCSTR lpcstrModule,
  LPVOID lpContext
);

파라미터

lpGuid
열거중의 DirectSound 드라이버를 식별하는 GUID 의 주소. 이 값을 DirectSoundCreate8 함수에 건네주면(자), 드라이버의 DirectSound 오브젝트를 생성 할 수 있다.
lpcstrDescription
DirectSound 디바이스의 텍스트 기술을 제공하는, NULL 로 끝나는 캐릭터 라인의 주소.
lpcstrModule
이 디바이스에 대응하는 DirectSound 드라이버의 모듈명을 지정하는, NULL 로 끝나는 캐릭터 라인의 주소.
lpContext
어플리케이션 정의 데이터의 주소. 이것은,lpContext 파라미터로서 DirectSoundEnumerate 또는 DirectSoundCaptureEnumerate 에게 건네지는 포인터이다.

반환값

드라이버의 열거가 계속되는 경우는 TRUE, 종료하는 경우는 FALSE 를 돌려준다.

주의

어플리케이션은 lpstrDescription 와 lpstrModule 의 각 파라미터에게 건네진 캐릭터 라인을, heap로부터 할당할 수 있었던 메모리에 카피하는 것으로써, 이러한 캐릭터 라인을 보존할 수 있다. 캐릭터 라인을 이 콜백 함수에 건네주기 위해서(때문에) 사용된 메모리는, 이 콜백 함수가 실행중 때에게만 유효하게 된다.

동작환경

헤더 : dsound.h 로 선언.

참조

DirectSoundEnumerate


DirectSound 함수

여기에서는, DirectSound 와 DirectSoundCapture 의 다음의 글로벌 함수의 레퍼런스 정보를 기술한다.

  • DirectSoundCaptureCreate8
  • DirectSoundFullDuplexCreate8
  • DirectSoundCaptureEnumerate
  • DirectSoundCreate8
  • DirectSoundEnumerate
  • GetDeviceID


DirectSoundCaptureCreate8

IDirectSoundCapture8 인터페이스를 지원 하는 오브젝트를 생성 및 초기화한다.

이 함수는, 캡춰 이펙트를 지원 하는 오브젝트를 생성 한다. 이전의 DirectSoundCaptureCreate 함수를 사용해 IDirectSoundCapture8 인터페이스를 취득할 수도 있지만, 이 경우, 생성 된 오브젝트는 IDirectSoundCaptureBuffer8 인터페이스를 지원 하는 캡춰 버퍼를 생성 하기 위해서 이용할 수 없다.

HRESULT WINAPI DirectSoundCaptureCreate8(
  LPCGUID lpcGUID,
  LPDIRECTSOUNDCAPTURE8 *lplpDSC,
  LPUNKNOWN pUnkOuter
);

파라미터

lpcGUID
사운드 캡춰 디바이스를 식별하는 GUID 의 주소. 이 파라미터의 값은,DirectSoundCaptureEnumerate 가 돌려준 GUID 의 언젠가, 디폴트의 디바이스를 지정하는 NULL, 또는 다음의 몇개의 값이 아니면 안된다.
DSDEVID_DefaultCapture
시스템 와이드인 디폴트의 오디오 캡춰 디바이스.
DSDEVID_DefaultVoiceCapture
디폴트의 음성 캡춰 디바이스.
lplpDSC
IDirectSoundCapture8 인터페이스 포인터를 받는 변수의 주소.
pUnkOuter
COM 집성체에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소. 집성체는 지원되어 있지 않기 때문에, NULL 로 설정해야 한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY

주의

전이중을 지원 하지 않는 사운드 카드로는, 이 메소드는 실패해, DSERR_ALLOCATED 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


DirectSoundCaptureEnumerate

시스템에 인스톨 되고 있는 DirectSoundCapture 오브젝트를 열거한다.

HRESULT WINAPI DirectSoundCaptureEnumerate(
  LPDSENUMCALLBACK lpDSEnumCallback,
  LPVOID lpContext
);

파라미터

lpDSEnumCallback
DSEnumCallback 함수의 주소. 이 함수는, 시스템에 인스톨 되고 있는 각 DirectSoundCapture 오브젝트에 대해서 불려 간다.
lpContext
유저 정의 문맥의 주소. 열거형 콜백 함수를 호출할 때마다, 그 함수에 이 문맥이 건네받는다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


DirectSoundCreate8

IDirectSound8 인터페이스를 지원 하는 오브젝트를 생성 및 초기화한다.

HRESULT WINAPI DirectSoundCreate8(
  LPCGUID lpcGuidDevice,
  LPDIRECTSOUND8 * ppDS8,
  LPUNKNOWN  pUnkOuter
);

파라미터

lpcGuidDevice
사운드 디바이스를 식별하는 GUID 의 주소. 이 파라미터의 값은,DirectSoundEnumerate 가 돌려준 GUID 의 언젠가, 또는 디폴트의 디바이스를 지정하는 NULL, 또는 다음의 몇개의 값이 아니면 안된다.
DSDEVID_DefaultPlayback
시스템 와이드인 디폴트의 오디오 재생 디바이스. NULL 에 동일하다.
DSDEVID_DefaultVoicePlayback
디폴트의 음성 재생 디바이스.
ppDS8
IDirectSound8 인터페이스 포인터를 받는 변수의 주소.
pUnkOuter
COM 집성체에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소. 집성체는 지원되어 있지 않기 때문에, NULL 로 설정해야 한다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_NODRIVER
DSERR_OUTOFMEMORY

주의

어플리케이션은 DirectSound 오브젝트를 생성 한 직후에,IDirectSound8::SetCooperativeLevel 메소드를 호출하지 않으면 안 된다.

동작환경

헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound8::GetCaps ,IDirectSound8::SetCooperativeLevel


DirectSoundEnumerate

시스템에 인스톨 되고 있는 DirectSound 드라이버를 열거한다.

HRESULT WINAPI DirectSoundEnumerate(
  LPDSENUMCALLBACK lpDSEnumCallback,
  LPVOID lpContext
);

파라미터

lpDSEnumCallback
DSEnumCallback 함수의 주소. 이 함수는, 시스템에 인스톨 되고 있는 각 DirectSound 오브젝트에 대해서 불려 간다.
lpContext
유저 정의 문맥의 주소. 열거형 콜백 함수를 호출할 때마다, 그 함수에 이 문맥이 건네받는다.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


DirectSoundFullDuplexCreate8

DirectSound 및 DirectSoundCapture 오브젝트를 생성 해,IDirectSoundFullDuplex8 인터페이스를 돌려준다.

현재의 operating system에서는,IDirectSoundFullDuplex8 오브젝트는 지원되어 있지 않다. 다만, 전이중 조작으로 필요한 다른 오브젝트를 설정할 때에, 이 함수를 사용하면(자) 편리하다.

HRESULT WINAPI DirectSoundFullDuplexCreate8(
  LPCGUID pcGuidCaptureDevice,
  LPCGUID pcGuidRenderDevice,
  LPCDSCBUFFERDESC pcDSCBufferDesc,
  LPCDSBUFFERDESC pcDSBufferDesc,
  HWND hWnd,
  DWORD dwLevel,
  LPDIRECTSOUNDFULLDUPLEX* ppDSFD,
  LPDIRECTSOUNDCAPTUREBUFFER8 *ppDSCBuffer8,
  LPDIRECTSOUNDBUFFER8 *ppDSBuffer8,
  LPUNKNOWN pUnkOuter
);

파라미터

pcGuidCaptureDevice
전이중 입력에 대해서 사운드 캡춰 디바이스를 식별하는 GUID 의 주소. DirectSoundCaptureEnumerate 가 돌려주는 GUID 의 언젠가, 디폴트의 캡춰 디바이스를 지정하는 NULL, 또는 다음의 값의 언젠가가 아니면 안된다.
DSDEVID_DefaultCapture
시스템 와이드인 디폴트의 오디오 캡춰 디바이스.
DSDEVID_DefaultVoiceCapture
디폴트의 음성 캡춰 디바이스.
pcGuidRenderDevice
전이중 출력에 대해서 사운드 렌더링 디바이스를 식별하는 GUID 의 주소. DirectSoundEnumerate 가 돌려주는 GUID 의 언젠가, 디폴트의 렌더링 디바이스를 지정하는 NULL, 또는 다음의 값의 언젠가가 아니면 안된다.
DSDEVID_DefaultPlayback
시스템 와이드인 디폴트의 오디오 재생 디바이스.
DSDEVID_DefaultVoicePlayback
디폴트의 음성 재생 디바이스.
pcDSCBufferDesc
캡춰 버퍼의 특성을 지정하는 DSCBUFFERDESC 구조체의 주소.
pcDSBufferDesc
렌더링 버퍼의 특성을 지정하는 DSBUFFERDESC 구조체의 주소.
hWnd
어플리케이션 윈도우에의 핸들.
dwLevel
DirectSound 오브젝트의 협조 레벨. 상세한 것에 대하여는, 「IDirectSound8::SetCooperativeLevel 」를 참조할것.
ppDSFD
IDirectSoundFullDuplex8 인터페이스 포인터를 받는 변수의 주소.
ppDSCBuffer8
캡춰 버퍼의 IDirectSoundCaptureBuffer8 인터페이스를 받는 변수의 주소.
ppDSBuffer8
렌더링 버퍼의 IDirectSoundBuffer8 인터페이스를 받는 변수의 주소.
pUnkOuter
COM 집성체에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소. 집성체는 지원되어 있지 않기 때문에, NULL 로 설정해야 한다.

동작환경

헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


GetDeviceID

유저가 컨트롤 패널의 [사운드] 및 [멀티미디어] 로 선택한 디폴트의 재생 디바이스 및 캡춰 디바이스의 일의의 디바이스 식별자를 받는다.

HRESULT GetDeviceID(
  LPCGUID pGuidSrc,
  LPGUID pGuidDest
);

파라미터

pGuidSrc
유효한 디바이스 식별자를 지정하는 GUID 형의 변수의 주소, 또는 다음의 정의 끝난 변수의 몇개의 주소.
DSDEVID_DefaultPlayback
시스템 와이드인 디폴트의 오디오 재생 디바이스.
DSDEVID_DefaultCapture
시스템 와이드인 디폴트의 오디오 캡춰 디바이스.
DSDEVID_DefaultVoicePlayback
디폴트의 음성 재생 디바이스.
DSDEVID_DefaultVoiceCapture
디폴트의 음성 캡춰 디바이스.
pGuidDest
디바이스의 일의의 식별자를 받는 GUID 의 변수의 주소.

반환값

성공했을 경우는 DS_OK 를 돌려준다.

실패했을 경우는 DSERR_INVALIDPARAM 를 돌려준다.

주의

pGuidSrc 가 유효한 디바이스 식별자를 가리키고 있는 경우는,pGuidDest 에 같은 값이 돌려주어진다. pGuidSrc 가 일람에 나타낸 정수의 몇개의 경우,pGuidDest 는 대응하는 디바이스의 GUID 의 주소를 돌려준다.

동작환경

헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


DirectSound 구조체

여기에서는, DirectSound 로 사용되는 다음의 구조체의 레퍼런스 정보를 기술한다.

  • DS3DBUFFER
  • DS3DLISTENER
  • DSBCAPS
  • DSBPOSITIONNOTIFY
  • DSBUFFERDESC
  • DSCAPS
  • DSCBCAPS
  • DSCBUFFERDESC
  • DSCCAPS
  • DSCEFFECTDESC
  • DSCFXAec
  • DSCFXNoiseSuppress
  • DSEFFECTDESC
  • DSFXI3DL2Reverb
  • DSFXChorus
  • DSFXCompressor
  • DSFXDistortion
  • DSFXEcho
  • DSFXFlanger
  • DSFXGargle
  • DSFXParamEq
  • DSFXWavesReverb
  • WAVEFORMATEX
  • WAVEFORMATEXTENSIBLE

주 모든 DirectX 구조 체용의 메모리는, 사용전에 초기화해야 한다. 더해,dwSize 멤버를 보관 유지하는 구조체에서는, 사용전에 그 멤버를 구조체의 바이트 단위의 사이즈로 설정해야 한다. 다음의 예는, 자주(잘) 사용되는 구조체 DSCAPS 에 대해서 이러한 처리를 실행한다.

DSCAPS dscaps; // 아직 이 구조체는 이용할 수 없다.

ZeroMemory(&dscaps, sizeof(dscaps));
dscaps.dwSize = sizeof(dscaps);

// 이것으로 이 구조체가 이용 가능하게 되었다.


DS3DBUFFER

3D 사운드 버퍼의 위치, 향해, 동작을 일의에 기술하기 위해서 필요한 모든 정보를 보관 유지하고 있다. 이 구조체는,IDirectSound3DBuffer8::GetAllParameters 와 IDirectSound3DBuffer8::SetAllParameters 의 각 메소드와 함께 사용된다.

typedef struct {
    DWORD      dwSize;
    D3DVECTOR  vPosition;
    D3DVECTOR  vVelocity;
    DWORD      dwInsideConeAngle;
    DWORD      dwOutsideConeAngle;
    D3DVECTOR  vConeOrientation;
    LONG       lConeOutsideVolume;
    D3DVALUE   flMinDistance;
    D3DVALUE   flMaxDistance;
    DWORD      dwMode;
} DS3DBUFFER, *LPDS3DBUFFER;

typedef const DS3DBUFFER *LPCDS3DBUFFER;

멤버

dwSize
구조체의 사이즈 (바이트 단위). 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
vPosition
3D 사운드 버퍼의 현재의 위치를 기술하는 D3DVECTOR 구조체.
vVelocity
3D 사운드 버퍼의 현재의 속도를 기술하는 D3DVECTOR 구조체.
dwInsideConeAngle
안쪽 사운드 프로젝션 콘의 각도.
dwOutsideConeAngle
외측 사운드 프로젝션 콘의 각도.
vConeOrientation
이 3D 사운드 버퍼 프로젝션 콘의 현재의 방향을 기술하는 D3DVECTOR 구조체.
lConeOutsideVolume
콘 외부 볼륨.
flMinDistance
최소 거리.
flMaxDistance
최대 거리.
dwMode
설정되는 3D 사운드 처리 모드.
DS3DMODE_DISABLE
3D 사운드 처리는 무효가 된다. 사운드는 청취자의 머릿속심으로 발생하고 있도록(듯이) 들린다.
DS3DMODE_HEADRELATIVE
사운드 파라미터 (위치, 속도, 방향)는 청취자의 파라미터에 대한 상대적인 것이다. 이 모드에서는, 청취자의 파라미터가 변화했을 때에 사운드의 절대 파라미터는 자동적으로 갱신되므로, 상대 파라미터는 일정으로 유지된다.
DS3DMODE_NORMAL
표준의 처리. 이것은 디폴트의 모드이다.

동작환경

헤더 : dsound.h 로 선언.


DS3DLISTENER

3D 월드 파라미터와 청취자의 위치를 기술한다. 이 구조체는,IDirectSound3DListener8::GetAllParameters 와 IDirectSound3DListener8::SetAllParameters 의 각 메소드와 함께 사용된다.

typedef struct {
    DWORD      dwSize;
    D3DVECTOR  vPosition;
    D3DVECTOR  vVelocity;
    D3DVECTOR  vOrientFront;
    D3DVECTOR  vOrientTop;
    D3DVALUE   flDistanceFactor;
    D3DVALUE   flRolloffFactor;
    D3DVALUE   flDopplerFactor;
} DS3DLISTENER, *LPDS3DLISTENER;

typedef const DS3DLISTENER *LPCDS3DLISTENER;

멤버

dwSize
구조체의 사이즈 (바이트 단위). 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
vPosition, vVelocity, vOrientFront, vOrientTop
청취자의 위치, 속도, 전방, 윗쪽의 각각을 기술하는 D3DVECTOR 구조체.
flDistanceFactor, flRolloffFactor, flDopplerFactor
각각 현재의 거리 계수, 롤 오프 계수, 돕라 계수.

동작환경

헤더 : dsound.h 로 선언.


DSBCAPS

DirectSound 버퍼 오브젝트의 능력을 기술한다. IDirectSoundBuffer8::GetCaps 메소드로 사용된다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwBufferBytes;
    DWORD  dwUnlockTransferRate;
    DWORD  dwPlayCpuOverhead;
} DSBCAPS, *LPDSBCAPS;

typedef const DSBCAPS *LPCDSBCAPS;

멤버

dwSize
구조체의 사이즈 (바이트 단위). 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
dwFlags
버퍼 오브젝트의 능력을 지정하는 플래그.
DSBCAPS_CTRL3D
버퍼는 3D 컨트롤 능력을 갖추고 있다.
DSBCAPS_CTRLFREQUENCY
버퍼는 주파수 컨트롤 능력을 갖추고 있다.
DSBCAPS_CTRLFX
버퍼는 이펙트 처리를 지원 하고 있다.
DSBCAPS_CTRLPAN
버퍼는 빵 컨트롤 능력을 갖추고 있다.
DSBCAPS_CTRLVOLUME
버퍼는 음량 조절 능력을 갖추고 있다.
DSBCAPS_CTRLPOSITIONNOTIFY
버퍼는 위치 통지 능력을 갖추고 있다. 「DSBUFFERDESC 」의 「주의」를 참조할것.
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer8::GetCurrentPosition 가 재생 커서의 새로운 동작을 사용해야 하는 것인 것을 나타낸다. DirectX 1 의 DirectSound 에서는, 에뮤레이트 된 사운드 카드상에서 재생 커서는 실제로 재생되고 있는 사운드보다 아득하게 전방에 있어, 기입 커서의 직후에 놓여져 있었다. 현재는, DSBCAPS_GETCURRENTPOSITION2 플래그를 지정 하면, 어플리케이션은 보다 정확한 재생 커서를 취득할 수 있다. 이 플래그를 지정하고 있지 않는 경우, 호환성을 유지하는 목적으로 과거의 동작이 유지된다. 이 플래그는, 에뮤레이트 된 사운드 카드에게만 영향을 미치는 점에 주의 해야 한다. DirectSound 드라이버가 존재하는 경우, DirectX 목의 버젼에서도, DirectSound 의 재생 커서는 정확한 위치를 나타낸다.
DSBCAPS_GLOBALFOCUS
이 버퍼는 글로벌인 사운드 버퍼이다. 이 플래그를 설정 하면, 유저가 다른 어플리케이션에 포커스를 이동해, 그 새로운 어플리케이션이 DirectSound 를 사용하는 경우에서도, DirectSound 를 사용하고 있는 어플리케이션은 계속해 그 버퍼를 재생할 수 있다. 1 개의 예외는, 협조 레벨로 DSSCL_WRITEPRIMARY 플래그를 설정한 DirectSound 어플리케이션에 포커스를 이동했을 경우이다. 이 경우, 다른 어플리케이션으로부터의 글로벌인 사운드는 들리지 않게 된다.
DSBCAPS_LOCDEFER
재생시, 또는 IDirectSoundBuffer8::AcquireResources 가 불려 갔을 때에, 버퍼는 하드웨어 또는 소프트웨어의 리소스에 할당할 수 있다.
DSBCAPS_LOCHARDWARE
버퍼는 하드웨어 믹싱을 사용한다.
DSBCAPS_LOCSOFTWARE
버퍼는 소프트웨어 메모리내에 있어, 소프트웨어 믹싱을 사용한다.
DSBCAPS_MUTE3DATMAXDISTANCE
사운드는, 최대 거리로 무음이 된다. 최대 거리를 넘으면(자) 버퍼의 재생이 정지하므로, 프로세서 시간을 소비하지 않고 끝난다.
DSBCAPS_PRIMARYBUFFER
이 버퍼는프라이머리 사운드 버퍼이다.
DSBCAPS_STATIC
버퍼는 온보드 하드웨어 메모리에 있다.
DSBCAPS_STICKYFOCUS
버퍼는스티키포카스를 갖추고 있다. 유저가 DirectSound 를 사용하지 않은 것 외의 어플리케이션으로 전환했을 경우, 버퍼는 계속해 소리를 낸다. 다만, 유저가 다른 DirectSound 어플리케이션으로 전환했을 경우, 버퍼는 무음이 된다.
dwBufferBytes
이 버퍼의 사이즈 (바이트 단위).
dwUnlockTransferRate
IDirectSoundBuffer8::Unlock 를 호출했을 때에 데이터를 버퍼 메모리에 전송 하는 속도를 지정한다. 단위는 1 초 쯤의 킬로바이트 (KB/s). 고성능의 어플리케이션은 이 값을 사용해,IDirectSoundBuffer8::Unlock 를 실행하기 위해서 필요한 시간을 결정할 수 있다. 시스템 메모리내에 배치되고 있는 소프트웨어 버퍼의 경우, 처리가 불필요해서 전송 속도는 매우 높다. 하드웨어 버퍼의 경우, 버퍼를 사운드 카드로 로드하지 않으면 안 될 가능성이 있으므로, 전송 속도는 보다 늦어질 가능성이 있다. 그 결과, 전송 속도가 제한되는 일이 있다.
dwPlayCpuOverhead
처리의 오버헤드를 지정한다. 이것은, 사운드 버퍼를 믹싱 하는데 필요한 메인 처리 사이클의 퍼센티지이다. 하드웨어 버퍼의 경우, 사운드 디바이스가 믹싱을 실시하므로, 이 멤버는 0 이다. 소프트웨어 버퍼의 경우, 이 멤버의 값은 버퍼 포맷과 시스템 프로세서의 속도에 의존한다.

주의

DSBCAPS 구조체는,IDirectSound8::CreateSoundBuffer 메소드에게 건네지는 DSBUFFERDESC 구조체를 닮은 정보와 그 이외의 몇개의 추가 정보를 보관 유지하고 있다. 추가 정보로서 버퍼의 위치 (하드웨어 또는 소프트웨어)와 몇개의 코스트 측정값 (예를 들어, 버퍼가 하드웨어에 배치되고 있는 경우는 다운로드 시간, 소프트웨어로 버퍼를 믹싱 하는 경우는 재생 처리의 오버헤드 등)을 들 수 있다.

dwFlags 멤버는,DSBUFFERDESC 구조체로 사용되는 같은 플래그를 보관 유지한다. 유일한 차이는,DSBCAPS 구조체에서는 버퍼의 장소에 응해 DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 어느 쪽인지가 지정되는 것이다. DSBUFFERDESC 구조체에서는 이러한 플래그는 옵션이며, 플래그의 지정에 응해, 버퍼를 하드웨어와 소프트웨어의 어딘가에 강제적으로 배치할 수 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound8::CreateSoundBuffer ,IDirectSoundBuffer8::GetCaps


DSBPOSITIONNOTIFY

통지 위치를 기술한다. IDirectSoundNotify8::SetNotificationPositions 메소드로 사용된다.

typedef struct {
    DWORD   dwOffset;
    HANDLE  hEventNotify;
} DSBPOSITIONNOTIFY, *LPDSBPOSITIONNOTIFY;

typedef const DSBPOSITIONNOTIFY *LPCDSBPOSITIONNOTIFY;

멤버

dwOffset
버퍼의 선두로부터, 통지 이벤트가 방아쇠 되는 장소까지의 오프셋(offset), 또는 DSBPN_OFFSETSTOP.
hEventNotify
지정의 오프셋(offset)에 이르렀을 때에 시그널 송신되는 이벤트에의 핸들.

주의

dwOffset 멤버내에서 값 DSBPN_OFFSETSTOP 가 설정되어 있는 경우, 재생 또는 캡춰가 버퍼의 마지막에 달했다 (그리고 재생 또는 캡춰가 루프 하고 있지 않다)인가, 어플리케이션이 IDirectSoundBuffer8::Stop 또는 IdirectSoundCaptureBuffer8::Stop 의 어느 쪽인가의 메소드를 호출했던 것이 원인으로, 재생 또는 캡춰가 정지 하면, 이벤트가 시그널 송신된다.

DSBCAPS_LOCDEFER 및 DSBCAPS_NOTIFY 를 음성 관리 플래그와 함께 사용하면(자), 통지가 설정되어 있지만, 아직 통지에 이르지 않은 사운드는, 음성 관리에 의해 종료되는 경우가 있다. 이 경우, 통지 이벤트는 발생하지 않는다.

동작환경

헤더 : dsound.h 로 선언.


DSBUFFERDESC

새로운 DirectSoundBuffer 오브젝트의 특성을 기술한다. IDirectSound8::CreateSoundBuffer 메소드로 사용된다.

DirectX 7 이전과의 호환성을 유지하기 위해서(때문에), 이 구조체의 전의 버젼의 DSBUFFERDESC1 도 dsound.h 로 유지되고 있다.

typedef struct {
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
    GUID            guid3DAlgorithm;
} DSBUFFERDESC, *LPDSBUFFERDESC;

typedef const DSBUFFERDESC *LPCDSBUFFERDESC;

멤버

dwSize
구조체의 사이즈 (바이트 단위). 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
dwFlags
새로운 DirectSoundBuffer 오브젝트를 생성 할 경우에 포함하는 능력을 식별하는 플래그. 다음의 플래그가 정의되고 있다. 「주의」를 참조할것.
DSBCAPS_CTRL3D
버퍼는 3D 컨트롤 능력을 갖추고 있다. DSBCAPS_CTRLPAN 와 조합할 수 없다. 또,lpwfxFormat 로 스테레오 포맷이 지정되고 있는 버퍼에는 설정할 수 없다.
DSBCAPS_CTRLFREQUENCY
버퍼는 주파수 컨트롤 능력을 갖추고 있다. DSBCAPS_CTRLFX 와 조합할 수 없다.
DSBCAPS_CTRLFX
버퍼는 이펙트 처리를 지원 하고 있다. DSBCAPS_CTRLFREQUENCY 와 조합할 수 없다. lpwfxFormat 의 웨이브 포맷은, 2 채널 이하의 8 비트 또는 16 비트의 PCM 포맷이 아니면 안된다. 또, 버퍼에는, DSBSIZE_FX_MIN 밀리 세컨드의 데이터를 저장 할 수 있는 사이즈가 필요하다.
DSBCAPS_CTRLPAN
버퍼는 빵 컨트롤 능력을 갖추고 있다. DSBCAPS_CTRL3D 와 조합할 수 없다.
DSBCAPS_CTRLPOSITIONNOTIFY
버퍼는 위치 통지 능력을 갖추고 있다. 「주의」를 참조할것.
DSBCAPS_CTRLVOLUME
버퍼는 음량 조절 능력을 갖추고 있다.
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer8::GetCurrentPosition 메소드에서는, 재생 커서의 새로운 동작을 사용한다. DirectX 1 의 DirectSound 에서는, 에뮤레이트 된 사운드 카드상에서 재생 커서는 실제로 재생되고 있는 사운드보다 아득하게 전방에 있어, 기입 커서의 직후에 놓여져 있었다. 현재는, DSBCAPS_GETCURRENTPOSITION2 플래그를 지정 하면, 어플리케이션은 보다 정확한 재생 커서를 취득할 수 있다. 이 플래그를 지정하고 있지 않는 경우, 호환성을 유지하는 목적으로 과거의 동작이 유지된다. 이 플래그는, 에뮤레이트 된 사운드 카드에게만 영향을 미치는 것에 주의한다. DirectSound 드라이버가 존재하는 경우, 어느 버젼의 DirectX 에서도 DirectSound 의 재생 커서는 정확한 위치를 나타낸다.
DSBCAPS_GLOBALFOCUS
이 버퍼는 글로벌인 사운드 버퍼이다. 이 플래그를 설정 하면, 유저가 다른 어플리케이션에 포커스를 이동해, 그 새로운 어플리케이션이 DirectSound 를 사용하는 경우에서도, DirectSound 를 사용하고 있는 어플리케이션은 계속해 그 버퍼를 재생할 수 있다. 1 개의 예외는, 협조 레벨로 DSSCL_WRITEPRIMARY 플래그를 설정한 DirectSound 어플리케이션에 포커스를 이동했을 경우이다. 이 경우, 다른 어플리케이션으로부터의 글로벌인 사운드는 들리지 않게 된다.
DSBCAPS_LOCDEFER
재생시, 버퍼는 하드웨어 또는 소프트웨어의 리소스에 할당할 수 있다. 이 플래그는, 음성 관리를 사용하는 버퍼로 설정되지 않으면 안 된다.
DSBCAPS_LOCHARDWARE
버퍼는 하드웨어 믹싱을 사용하지 않으면 안 된다. 디바이스가 하드웨어 믹싱을 지원 하고 있지 않는 경우나, 필요한 하드웨어 메모리를 이용할 수 없는 경우,IDirectSound8::CreateSoundBuffer 메소드의 호출은 실패한다. 어플리케이션은, 이 버퍼가 믹싱 채널을 이용 가능하다라고 보증할 필요가 있다. 이 상황은 보증되어 있지 않다.
DSBCAPS_LOCSOFTWARE
DSBCAPS_STATIC 가 지정되고 있어, 하드웨어 리소스가 이용 가능해도, 버퍼를 소프트웨어 메모리에 배치해, 소프트웨어 믹싱을 사용하지 않으면 안 된다.
DSBCAPS_MUTE3DATMAXDISTANCE
사운드는, 최대 거리로 무음이 된다. 최대 거리를 넘으면(자) 버퍼의 재생이 정지하므로, 프로세서 시간을 소비하지 않고 끝난다.
DSBCAPS_PRIMARYBUFFER
이 버퍼는프라이머리 사운드 버퍼이다. 이 값을 지정하지 않는 경우는,세칸다리사운드밧파가 생성 된다. DSBCAPS_CTRLFX 와 조합할 수 없다.
DSBCAPS_STATIC
온보드 하드웨어 메모리가 이용 가능한 경우, 버퍼는 거기에 놓여진다. 이러한 메모리를 이용할 수 없는 경우에서도, 에러는 발생하지 않는다. 이것에 대해서 DSBCAPS_LOCHARDWARE 는, 버퍼를 강제적으로 하드웨어 메모리 (아마, 드라이버가 버퍼의 믹싱에 사용하는 시스템 메모리)에 두므로, 이러한 메모리를 이용할 수 없는 경우는 에러를 일으킨다. 이 플래그는, DSBCAPS_CTRLFX 와 조합할 수 없다.
DSBCAPS_STICKYFOCUS
버퍼는스티키포카스를 갖추고 있다. 유저가 DirectSound 를 사용하지 않은 것 외의 어플리케이션으로 전환했을 경우, 어플리케이션의 표준 버퍼는 무음이 되지만, 스티키포카스밧파는 계속해 소리를 낸다.
dwBufferBytes
새로운 버퍼의 사이즈 (바이트 단위). DSBCAPS_PRIMARYBUFFER 플래그를 사용해 버퍼를 생성 하는 경우, 이 값은 0 이 아니면 안된다. 세칸다리밧파로 허용 되는 최소 사이즈와 최대 사이즈는, dsound.h 내에서 정의되는 DSBSIZE_MIN, DSBSIZE_MAX 이다.
dwReserved
이 멤버는 예약되고 있다. 0 이 아니면 안된다.
lpwfxFormat
버퍼의 웨이브 포맷을 지정하는 WAVEFORMATEX 또는 WAVEFORMATEXTENSIBLE 구조체의 주소. 프라이머리 버퍼에서는, 이 값은 NULL 가 아니면 안된다. 어플리케이션은 IDirectSoundBuffer8::SetFormat 를 사용해, 프라이머리 버퍼의 포맷을 설정할 수 있다.
guid3DAlgorithm
DirectSound3D HEL 가 사용하는 이중 스피커의 가상 알고리즘의 유니크 식별자. DSBCAPS_CTRL3D 가 dwFlags 로 설정되어 있지 않은 경우, 이 멤버는 GUID_NULL (DS3DALG_DEFAULT)에 해야 한다. 「주의」를 참조할것.

다음의 알고리즘 식별자가 정의되고 있다.

DS3DALG_DEFAULT
DirectSound 는 디폴트의 알고리즘을 사용한다. 보통은, DS3DALG_NO_VIRTUALIZATION 이다. WDM 드라이버에서는, 컨트롤 패널로 환경 사운드가 선택되고 있으면(자), 사운드는, 왼쪽, 중앙, 오른쪽, 및 환경의 각 채널간에 빵 된다.

소프트웨어 믹싱에게만 적용된다. WDM 또는 VxD 드라이버로 이용할 수 있다.

DS3DALG_NO_VIRTUALIZATION
3D 출력은, 표준의 좌우 스테레오의 빵에 맵 된다. 왼쪽으로 90о 때, 사운드는 왼쪽 스피커만으로부터 들려 오른쪽으로 90о 때, 사운드는 오른쪽 스피커만으로부터 들린다. 수직축에서는, 거리에 의해 볼륨이 조절되는 것만으로 있다. 이 버퍼에서는, 돕라시후트와 볼륨 조절은 적용되지만, 3D 필터 링은 행해지지 않는다. 이것은 가장 효율적인 소프트웨어의 이행이지만, 가상 3D 오디오 이펙트는 제공하지 않는다. DS3DALG_NO_VIRTUALIZATION 플래그를 지정 하면,HRTF 처리는 행해지지 않는다. 주 DS3DALG_NO_VIRTUALIZATION 는 표준의 스테레오의 빵만을 사용하므로, 이 알고리즘으로 생성 된 버퍼는, 3D 하드웨어 음성의 빈 곳을 이용할 수 없는 경우, 2D 하드웨어 음성에 의해 액셀러레이트 된다.

소프트웨어 믹싱에게만 적용된다. WDM 또는 VxD 드라이버로 이용할 수 있다.

DS3DALG_HRTF_FULL
3D API 는, 고품질인 3D 오디오 알고리즘으로 처리된다. 이 플래그는, 소프트웨어 HEL 에만 적용된다. 이 알고리즘은 최고 품질의 3D 오디오 이펙트를 주지만, CPU 를 보다 많이 소비한다. 「주의」를 참조할것.

소프트웨어 믹싱에게만 적용된다. WDM 드라이버를 사용한, Microsoft® Windows® 98 Second Edition 와 Windows 2000 으로 이용할 수 있다.

주 사운드 버퍼를 HRTF 알고리즘의 어느쪽이든을 사용해 생성 해, HRTF 알고리즘이 시스템으로 이용 불가능한 경우는 (예를 들어, WDM 시스템이 아닌 경우), 코드 DS_NO_VIRTUALIZATION 가 돌려주어진다. 생성 된 사운드 버퍼는, 대신에 DS3DALG_NO_VIRTUALIZATION 를 사용한다. 이것에 의해, 어플리케이션은 CreateSoundBuffer 의 호출시에 명시적으로 DS_OK 를 체크하는 것이 아니라,SUCCEEDED 매크로나 FAILED 매크로를 사용할 필요가 있다.

DS3DALG_HRTF_LIGHT
3D API 는, 효율적인 3D 오디오 알고리즘으로 처리된다. 이 플래그는, 소프트웨어 HEL 에만 적용된다. 이 알고리즘은 뛰어난 3D 오디오 이펙트를 주어 DS3DALG_HRTF_FULL (정도)만큼 CPU 에 부하를 걸지 않는다.

소프트웨어 믹싱에게만 적용된다. WDM 드라이버를 사용한, Windows 98 Second Edition 와 Windows 2000 으로 이용할 수 있다.

주 사운드 버퍼를 HRTF 알고리즘의 어느쪽이든을 사용해 생성 해, HRTF 알고리즘이 시스템으로 이용 불가능한 경우는 (예를 들어, WDM 시스템이 아닌 경우), 코드 DS_NO_VIRTUALIZATION 가 돌려주어진다. 생성 된 사운드 버퍼는, 대신에 DS3DALG_NO_VIRTUALIZATION 를 사용한다. 이것에 의해, 어플리케이션은 CreateSoundBuffer 의 호출시에 명시적으로 DS_OK 를 체크하는 것이 아니라,SUCCEEDED 매크로나 FAILED 매크로를 사용할 필요가 있다.

주의

프라이머리 버퍼를 생성 할 때, 어플리케이션은 dwBufferBytes 멤버를 0 으로 설정해야 한다. DirectSound 는, 사용중의 특정의 사운드 디바이스에 대한 최적인 버퍼 사이즈를 결정한다. 생성 된 프라이머리 버퍼의 크기를 취득하려면 ,IDirectSoundBuffer8::GetCaps 를 호출한다.

DSBCAPS_CTRLDEFAULT 플래그는 이제 지원되어 있지 않다. 이 플래그는, DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY 로서 정의되었다. 필요한 플래그만을 지정하는 것으로써, 불필요한 리소스를 줄일 수가 있다.

DSBCAPS_CTRLPOSITIONNOTIFY 플래그로 생성 된 사운드 버퍼에는, 통지 이벤트를 설정해야 한다. 이 플래그로 사운드 버퍼를 생성 해, 실제로는 아무것도 통지를 설정하지 않으면 동작이 정의되지 않고, 사운드가 2 회 재생되는 일이 있다.

VxD 드라이버의 경우, DSBCAPS_CTRLPOSITIONNOTIFY 를 사용해 생성 된 사운드 버퍼는 항상 소프트웨어 버퍼이다. 이것은, VxD 드라이버 모델이 통지를 지원 하지 않기 때문이다. 하드웨어가 이용 가능한 경우는, WDM 드라이버에 의해, 통지 가능한 버퍼가 하드웨어에 존재하는 일이 있다. 이 플래그 설정으로 생성 된 버퍼의 재생중은, DSBPLAY_LOCHARDWARE 플래그에 의한 IDirectSoundBuffer8::Play 의 호출은 실패한다.

DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 각 플래그는 옵션이며, 서로 배타적이다. DSBCAPS_LOCHARDWARE 는, 강제적으로 버퍼를 하드웨어에 배치한다. 이것은, 버퍼가 사운드 카드에 의해 믹싱 되는 것을 의미한다. DSBCAPS_LOCSOFTWARE 는, 강제적으로 버퍼를 소프트웨어에 배치한다. 이 경우, 버퍼는 CPU 에 의해 믹싱 된다. 이러한 플래그는,DSBCAPS 구조체의 dwFlags 멤버용으로도 정의되고 있어 버퍼의 실제의 장소를 나타낸다.

3D 알고리즘은, 소프트웨어 에뮬레이션 계층만의 선택을 실시한다. 이것은, 가속화용의 하드웨어가 없는 경우에 사용되는 소프트웨어 알고리즘이다. 하드웨어의 이용을 최대로 하기 위해서(때문에), DS3DALG_NO_VIRTUALIZATION 는 특별한 경우로서 다루어진다. 3D 하드웨어 음성의 빈 곳을 이용할 수 없는 경우, 버퍼는 3D API 컨트롤과 함께 2D 버퍼로서 다루어진다. 특히, 사운드 버퍼가 DS3DALG_NO_VIRTUALIZATION 로 생성 되고 있는 경우, 또는 버퍼가 DSBPLAY_LOCDEFER 로 생성 되고 있는 경우는, 버퍼의 연주중에 다음의 순서에 따른다.

  • 3D 하드웨어 음성의 빈 곳이 이용 가능한 경우는, 그 3D 하드웨어 음성을 사용한다.
  • 3D 하드웨어 음성의 빈 곳이 이용 불가능해, 2D 하드웨어 음성이 이용 가능한 경우는, 그 2D 하드웨어 음성을 사용한다. 이것이 가능한 것은, DS3DALG_NO_VIRTUALIZATION 알고리즘이 단순한 스테레오 빵 알고리즘이니까이다.
  • 2D 또는 3D 하드웨어 음성의 빈 곳이 이용 불가능한 경우, 음성은 DS3DALG_NO_VIRTUALIZATION 알고리즘을 사용해 소프트웨어로 재생된다.

DSSPEAKER_HEADPHONE 나 DSSPEAKER_STEREO 이외의 스피커 구성이 유효한 경우, 이 처리는 이중 스피커 구성에 대한 처리와 같이 행해진다.

버퍼를 HRTF 알고리즘의 어느쪽이든을 사용해 생성 해, HRTF 알고리즘이 시스템으로 이용 불가능한 경우는 (예를 들어, WDM 시스템이 아닌 경우), 코드 DS_NO_VIRTUALIZATION 가 돌려주어진다. 생성 된 사운드 버퍼는, 대신에 DS3DALG_NO_VIRTUALIZATION 를 사용한다. 이것에 의해, 어플리케이션은 CreateSoundBuffer 의 호출시에 명시적으로 DS_OK 를 체크하는 것이 아니라,SUCCEEDED 매크로나 FAILED 매크로를 사용할 필요가 있다.

동작환경

헤더 : dsound.h 으로 선언.

참조

IDirectSound8::CreateSoundBuffer ,DirectSound 버퍼,ISA 및 PCI 카드에서의 하드웨어 가속화


DSCAPS

DirectSound 디바이스의 능력을 기술한다. IDirectSound8::GetCaps 메소드로 사용된다.

typedef {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwMinSecondarySampleRate;
    DWORD  dwMaxSecondarySampleRate;
    DWORD  dwPrimaryBuffers;
    DWORD  dwMaxHwMixingAllBuffers;
    DWORD  dwMaxHwMixingStaticBuffers;
    DWORD  dwMaxHwMixingStreamingBuffers;
    DWORD  dwFreeHwMixingAllBuffers;
    DWORD  dwFreeHwMixingStaticBuffers;
    DWORD  dwFreeHwMixingStreamingBuffers;
    DWORD  dwMaxHw3DAllBuffers;
    DWORD  dwMaxHw3DStaticBuffers;
    DWORD  dwMaxHw3DStreamingBuffers;
    DWORD  dwFreeHw3DAllBuffers;
    DWORD  dwFreeHw3DStaticBuffers;
    DWORD  dwFreeHw3DStreamingBuffers;
    DWORD  dwTotalHwMemBytes;
    DWORD  dwFreeHwMemBytes;
    DWORD  dwMaxContigFreeHwMemBytes;
    DWORD  dwUnlockTransferRateHwBuffers;
    DWORD  dwPlayCpuOverheadSwBuffers;
    DWORD  dwReserved1;
    DWORD  dwReserved2;
} DSCAPS, *LPDSCAPS;

typedef const DSCAPS *LPCDSCAPS;

멤버

dwSize
구조체의 사이즈 (바이트 단위). 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
dwFlags
디바이스의 능력을 기술하는 플래그. 다음의 몇개의 값이 된다.
DSCAPS_CERTIFIED
이 드라이버는 Microsoft 로 테스트되어 인정되고 있다. 이 플래그는 항상 WDM 드라이버에 대해서 설정된다. 인증되고 있는지 어떤지 테스트하려면 ,IDirectSound8::VerifyCertification 를 사용한다.
DSCAPS_CONTINUOUSRATE
이 디바이스는,dwMinSecondarySampleRate 과 dwMaxSecondarySampleRate 의 각 멤버값의 사이의 모든 샘플링 레이트를 지원 한다. 일반적으로 이것은, 실제의 출력 레이트가 요구된 주파수의 ±10 헤르쯔 (Hz) 이내인 것을 의미한다.
DSCAPS_EMULDRIVER
이 디바이스에는 DirectSound 드라이버가 인스톨되어 있지 않다. 웨이브 폼 오디오 기능을 통해 에뮤레이트 되고 있다. 성능의 저하가 예상된다.
DSCAPS_PRIMARY16BIT
이 디바이스는 16 비트 샘플링으로프라이머리 사운드 버퍼를 지원 한다.
DSCAPS_PRIMARY8BIT
이 디바이스는 8 비트 샘플링으로 프라이머리 버퍼를 지원 한다.
DSCAPS_PRIMARYMONO
이 디바이스는 단청의의 프라이머리 버퍼를 지원 한다.
DSCAPS_PRIMARYSTEREO
이 디바이스는 스테레오의 프라이머리 버퍼를 지원 한다.
DSCAPS_SECONDARY16BIT
이 디바이스는, 16 비트 샘플링으로 하드웨어 믹싱의세칸다리사운드밧파를 지원 한다.
DSCAPS_SECONDARY8BIT
이 디바이스는, 8 비트 샘플링으로 하드웨어 믹싱의 세칸다리밧파를 지원 한다.
DSCAPS_SECONDARYMONO
이 디바이스는, 하드웨어 믹싱의 모노라르세칸다리밧파를 지원 한다.
DSCAPS_SECONDARYSTEREO
이 디바이스는, 하드웨어 믹싱의 스테레오세칸다리밧파를 지원 한다.
dwMinSecondarySampleRate, dwMaxSecondarySampleRate
이 디바이스의 하드웨아세칸다리사운드밧파가 지원 하는 최소와 최대의 샘플링 레이트의 사양.
dwPrimaryBuffers
지원 되고 있는 프라이머리 버퍼의 수. 이 값은 항상 1 이다.
dwMaxHwMixingAllBuffers
하드웨어로 믹싱 할 수 있는 버퍼의 수. 이 멤버는 dwMaxHwMixingStaticBuffers 와 dwMaxHwMixingStreamingBuffers 의 합계보다 작은 값을 취한다. 리소스의 트레이드 오프가 자주 발생한다.
dwMaxHwMixingStaticBuffers
스태틱 버퍼의 최대수.
dwMaxHwMixingStreamingBuffers
스트림 사운드 버퍼의 최대수.
dwFreeHwMixingAllBuffers
미할당 버퍼의 수. WDM 드라이버에서는,dwFreeHw3DAllBuffers 가 된다.
dwFreeHwMixingStaticBuffers
미할당의 스태틱 버퍼의 수.
dwFreeHwMixingStreamingBuffers
미할당의 스트림 버퍼의 수.
dwMaxHw3DAllBuffers
3D 버퍼의 최대수.
dwMaxHw3DStaticBuffers
스태틱 3D 버퍼의 최대수.
dwMaxHw3DStreamingBuffers
스트림 3D 버퍼의 최대수.
dwFreeHw3DAllBuffers
미할당의 3D 버퍼의 수.
dwFreeHw3DStaticBuffers
미할당의 스태틱 3D 버퍼의 수.
dwFreeHw3DStreamingBuffers
미할당의 스트림 3D 버퍼의 수.
dwTotalHwMemBytes
스태틱 사운드 버퍼를 보관 유지하는 사운드 카드 위에의 메모리 용량의 사이즈 (바이트 단위).
dwFreeHwMemBytes
사운드 카드 건성나무 메모리의 사이즈 (바이트 단위).
dwMaxContigFreeHwMemBytes
사운드 카드 건성나무 메모리 가운데, 최대의 연속 블록의 사이즈 (바이트 단위).
dwUnlockTransferRateHwBuffers
하드웨어 스태틱 사운드 버퍼에의 데이터 전송 속도. 단위는 1 초 쯤의 킬로바이트 (KB/s). 이 속도와 전송 바이트수에 의해,IDirectSoundBuffer8::Unlock 메소드를 호출했을 때의 실행 시간이 정해진다.
dwPlayCpuOverheadSwBuffers
(메인 시스템 메모리내의) 소프트웨어 버퍼를 믹싱 하기 위해서 필요한 처리 오버헤드를, CPU 퍼센티지로 기술한 값. 이 값은, 버스 타입, 프로세서 타입, 클락 속도에 응해 변화한다.

소프트웨어 버퍼의 언락 전송 속도는 0 이다. 데이터를 어디에도 전송 할 필요가 없기 때문에이다. 같이 하드웨어 버퍼의 재생 오버헤드도, 믹싱이 사운드 디바이스에 의해 처리되기 (위해)때문에, 0 이다.

dwReserved1
미사용.
dwReserved2
미사용.

주의

몇개의 오디오 사운드 카드는, 이용 가능한 하드웨어 버퍼나 그 빈 곳을 정확하게 보고할 수 없는 경우가 있다. 이것은 예를 들어, 카드가, 높은 샘플링 레이트보다 낮은 샘플링 레이트로 보다 많은 사운드를 재생할 수 있을 때 발생한다. 보통, 하드웨어 버퍼의 빈수에 관계하는 멤버의 값이 0 이외 때, 적절한 타입의 하드웨어 리소스가 적어도 1 개(살) 이용할 수 있는 것을 나타낸다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSound8::GetCaps


DSCBCAPS

캡춰 버퍼의 능력을 기술한다. IDirectSoundCaptureBuffer8::GetCaps 메소드로 사용된다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwBufferBytes;
    DWORD  dwReserved;
} DSCBCAPS, *LPDSCBCAPS;

typedef const DSCBCAPS *LPCDSCBCAPS;

멤버

dwSize
구조체의 사이즈 (바이트 단위). 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
dwFlags
디바이스의 능력을 지정한다. 0 또는 다음의 플래그를 지정한다.
DSCBCAPS_WAVEMAPPED
이 디바이스가 지원 하지 않는 포맷에 대해서, Win32 웨이브 맵퍼를 사용한다.
dwBufferBytes
캡춰 버퍼의 사이즈 (바이트 단위).
dwReserved
장래의 사용에 대비해 예약되고 있다.

동작환경

헤더 : dsound.h 로 선언.


DSCBUFFERDESC

캡춰 버퍼를 기술한다. IDirectSoundCapture8::CreateCaptureBuffer 메소드로 사용된다.

DirectX 7 이전과의 호환성을 유지하기 위해서(때문에), 이 구조체의 전의 버젼의 DSCBUFFERDESC1 도 dsound.h 로 유지되고 있다.

typedef struct {
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
    DWORD           dwFXCount;
    LPDSCEFFECTDESC lpDSCFXDesc;
} DSCBUFFERDESC, *LPDSCBUFFERDESC;

typedef const DSCBUFFERDESC *LPCDSCBUFFERDESC;

멤버

dwSize
구조체의 사이즈 (바이트 단위). 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
dwFlags
디바이스의 능력을 지정한다. 0 인가, 다음의 플래그의 1 개 또는 복수를 지정할 수 있다.
DSCBCAPS_CTRLFX
버퍼는 이펙트를 지원 한다. 「주의」를 참조할것.
DSCBCAPS_WAVEMAPPED
이 디바이스가 지원 하지 않는 포맷에 대해서, Win32 웨이브 맵퍼를 사용한다.
dwBufferBytes
생성 되는 캡춰 버퍼의 사이즈 (바이트 단위).
dwReserved
장래의 사용에 대비해 예약되고 있다.
lpwfxFormat
데이터의 캡춰에 사용하는 포맷을 보관 유지하는 WAVEFORMATEX 구조체에의 포인터.
dwFXCount
lpDSCFXDesc 로 나타나는 배열의 요소수. dwFlags 가 DSCBCAPS_CTRLFX 가 아닌 경우는, 0 이 아니면 안된다.
lpDSCFXDesc
DSCEFFECTDESC 구조체의 배열의 주소. 버퍼에 대해서 하드웨어로 지원 되고 있는 이펙트를 기술한다. 유저 모드의 DMO 는 지원 되지 않는다.

주의

DSCBCAPS_CTRLFX 플래그는, CLSID_DirectSoundCapture8 클래스의 오브젝트로 생성 된 버퍼에서만 지원 된다. IDirectSoundCapture8 인터페이스가 DirectSoundCaptureCreate8 로부터 취득되었을 경우, 이 플래그는 지원 된다. 이전의 DirectSoundCaptureCreate 함수로부터 취득되었을 경우, 이 플래그는 지원 되지 않는다.

현재의 operating system에서는, 캡춰 이펙트는 지원 되지 않는다.

동작환경

헤더 : dsound.h 로 선언.


DSCCAPS

캡춰 디바이스의 능력을 기술한다. IDirectSoundCapture8::GetCaps 메소드로 사용된다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwFormats;
    DWORD  dwChannels;
} DSCCAPS, *LPDSCCAPS;

typedef const DSCCAPS *LPCDSCCAPS;

멤버

dwSize
구조체의 사이즈 (바이트 단위). 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
dwFlags
디바이스의 능력을 지정한다. 0 또는 다음의 플래그를 지정한다.
DSCCAPS_EMULDRIVER
이 디바이스용의 DirectSoundCapture 드라이버는 존재하지 않는다. 그 때문에, 표준의 웨이브 오디오 함수가 사용되고 있다.
DSCCAPS_CERTIFIED
이 디바이스용의 드라이버는, 인증 끝난 WDM 드라이버이다.
DSCCAPS_MULTIPLECAPTURE
캡춰 디바이스는, 유효한 캡춰 데이터를 동시에 받을 수가 있는 복수의 어플리케이션으로 열릴 수가 있다.
dwFormats
지원 되고 있는 표준 포맷. 이것들은 Win32 웨이브 폼 오디오 함수로 사용되고 있는 WAVEINCAPS 구조체의 값과 같은 것이다. 다음에 일람을 나타낸다.
값 | 의미
WAVE_FORMAT_1M08 | 11.025 kHz, 단청의, 8 비트
WAVE_FORMAT_1M16 | 11.025 kHz, 단청의, 16 비트
WAVE_FORMAT_1S08 | 11.025 kHz, 스테레오, 8 비트
WAVE_FORMAT_1S16 | 11.025 kHz, 스테레오, 16 비트
WAVE_FORMAT_2M08 | 22.05 kHz, 단청의, 8 비트
WAVE_FORMAT_2M16 | 22.05 kHz, 단청의, 16 비트
WAVE_FORMAT_2S08 | 22.05 kHz, 스테레오, 8 비트
WAVE_FORMAT_2S16 | 22.05 kHz, 스테레오, 16 비트
WAVE_FORMAT_4M08 | 44.1 kHz, 단청의, 8 비트
WAVE_FORMAT_4M16 | 44.1 kHz, 단청의, 16 비트
WAVE_FORMAT_4S08 | 44.1 kHz, 스테레오, 8 비트
WAVE_FORMAT_4S16 | 44.1 kHz, 스테레오, 16 비트

dwChannels
디바이스가 지원 하는 채널수를 지정하는 수치. 1 은 단청의, 2 는 스테레오를 의미한다. 이하 같이이다.

동작환경

헤더 : dsound.h 로 선언.


DSCEFFECTDESC

캡춰 버퍼에 관련지을 수 있었던 이펙트의 파라미터를 보관 유지한다.

typedef struct _DSCEFFECTDESC {
    DWORD       dwSize;
    DWORD       dwFlags;
    GUID        guidDSCFXClass;
    GUID        guidDSCFXInstance;
    DWORD       dwReserved1;
    DWORD       dwReserved2;
} DSCEFFECTDESC, *LPDSCEFFECTDESC;

typedef const DSCEFFECTDESC *LPCDSCEFFECTDESC;

멤버

dwSize
구조체의 사이즈 (바이트 단위).
dwFlags
이펙트의 목적의 파라미터를 지정하는 플래그. 이 구조체를 IDirectSoundCapture8::CreateCaptureBuffer 에 건네주는 경우, 이 멤버에는 0 또는 다음의 1 개 이상의 값을 지정할 수 있다.
DSCFX_LOCHARDWARE
guidDSCFXInstance 로 지정한 이펙트가, 하드웨어에 없으면 안 된다.
DSCFX_LOCSOFTWARE
guidDSCFXInstance 로 지정한 이펙트가, 소프트웨어에 없으면 안 된다.
반환값으로서 이 멤버에는 다음의 1 개 또는 복수의 값이 보관 유지되는 경우가 있다.
DSCFXR_LOCHARDWARE
이펙트는 하드웨어로 생성 되었다.
DSCFXR_LOCSOFTWARE
이펙트는 소프트웨어로 생성 되었다.
DSCFXR_UNALLOCATED
이펙트는 생성되어 있지 않다.
DSCFXR_FAILED
이펙트의 생성에 실패했다.
DSCFXR_UNKNOWN
이펙트의 생성 결과가 불명하다.
guidDSCFXClass
이펙트의 클래스 식별자를 지정하는 GUID 형의 값. 다음의 일반적인 식별자가 정의되고 있다.
DSCFX_CLASS_AEC
청감 메아리 해제.
DSCFX_CLASS_NS
노이즈 억제.
guidDSCFXInstance
우선하는 이펙트의 일의인 식별자를 지정하는 GUID 형의 값. 다음의 일반적인 식별자가 정의되고 있다.
DSCFX_MS_AEC
Microsoft 의 청감 메아리 해제. 소프트웨어만으로 이용 가능.
DSCFX_MS _NS
Microsoft 의 노이즈 억제. 소프트웨어만으로 이용 가능.
DSCFX_SYSTEM_AEC
시스템으로 디폴트의 청감 메아리 해제.
DSCFX_SYSTEM_NS
시스템으로 디폴트의 노이즈 억제.
DSCFX_NOP
이펙트 없음.

dwReserved1
이 멤버는 예약되고 있다. 0 이 아니면 안된다.
dwReserved2
이 멤버는 예약되고 있다. 0 이 아니면 안된다.

동작환경

헤더 : dsound.h 로 선언.


DSCFXAec

캡춰 버퍼의 청감 메아리 해제의 파라미터를 보관 유지한다.

typedef struct _DSCFXAec {
    BOOL  fEnable;
    BOOL  fReset;
} DSCFXAec, *LPDSCFXAec;

typedef const DSCFXAec *LPCDSCFXAec;

멤버

fEnable
이펙트가 유효한가 어떤가를 지정하는 불형의 값.
fReset
이펙트를 디폴트 상태에 리셋 할지 어떨지를 지정하는 불형의 값.

주의

어플리케이션으로 이펙트를 리셋 하는 것은, 이펙트가 부정한 상태에 빠졌을 경우인 만큼 해야 한다. 유저의 입력에 응답해, 필요한 때 만일 수 있는 리셋 되도록(듯이) 할 수가 있다. 같은 이펙트를 다른 어플리케이션에서도 사용하고 있을 가능성이 있으므로, 기동시에 임의로 fReset 플래그가 설정되도록(듯이) 해선 안 된다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundCaptureFXAec8::GetAllParameters ,IDirectSoundCaptureFXAec8::SetAllParameters


DSCFXNoiseSuppress

캡춰 버퍼의 노이즈 억제의 파라미터를 보관 유지한다.

typedef struct _DSCFXNoiseSuppress {
    BOOL  fEnable;
    BOOL  fReset;
} DSCFXNoiseSuppress, *LPDSCFXNoiseSuppress;

typedef const DSCFXNoiseSuppress *LPCDSCFXNoiseSuppress;

멤버

fEnable
이펙트가 유효한가 어떤가를 지정하는 불형의 값.
fReset
이펙트를 디폴트 상태에 리셋 할지 어떨지를 지정하는 불형의 값.

주의

어플리케이션으로 이펙트를 리셋 하는 것은, 이펙트가 부정한 상태에 빠졌을 경우인 만큼 해야 한다. 유저의 입력에 응답해, 필요한 때 만일 수 있는 리셋 되도록(듯이) 할 수가 있다. 같은 이펙트를 다른 어플리케이션에서도 사용하고 있을 가능성이 있으므로, 기동시에 임의로 fReset 플래그가 설정되도록(듯이) 해선 안 된다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundCaptureFXNoiseSuppress8::GetAllParameters ,IDirectSoundCaptureFXNoiseSuppress8::SetAllParameters


DSEFFECTDESC

버퍼에 관련지을 수 있었던 이펙트를 기술한다.

typedef struct _DSEFFECTDESC {
    DWORD  dwSize;
    DWORD  dwFlags;
    GUID   guidDSFXClass;
    DWORD  dwReserved1;
    DWORD  dwReserved2
} DSEFFECTDESC, *LPDSEFFECTDESC;

typedef const DSEFFECTDESC *LPCDSEFFECTDESC;

멤버

dwSize
구조체의 사이즈 (바이트 단위).
dwFlags
플래그. 0 또는 다음의 값의 어느쪽이든을 지정한다.
DSFX_LOCHARDWARE
이펙트는 하드웨어에 없으면 안 된다. 하드웨어로 그 이펙트를 이용할 수 없는 경우는,IDirectSoundBuffer8::SetFX 로 에러가 발생한다. DirectX 8.0 은 이펙트의 하드웨어 가속화를 지원 하고 있지 않기 때문에, 이 플래그를 사용해서는 안된다.
DSFX_LOCSOFTWARE
하드웨어가 guidDSFXClass 의 가속화를 지원 하는 경우에서도, 이펙트는 소프트웨어에 없으면 안 된다. 소프트웨어로 그 이펙트를 이용할 수 없는 경우는,SetFX 로 에러가 발생한다. DirectX 8.0 에서는, 이 플래그의 설정에 관계없이, 모든 이펙트가 소프트웨어에 배치된다.
guidDSFXClass
이펙트의 클래스 식별자. 다음의 표준 이펙트 클래스가 정의되고 있다.
GUID_DSFX_STANDARD_CHORUS
GUID_DSFX_STANDARD_COMPRESSOR
GUID_DSFX_STANDARD_DISTORTION
GUID_DSFX_STANDARD_ECHO
GUID_DSFX_STANDARD_FLANGER
GUID_DSFX_STANDARD_GARGLE
GUID_DSFX_STANDARD_I3DL2REVERB
GUID_DSFX_STANDARD_PARAMEQ
GUID_DSFX_STANDARD_WAVES_REVERB
dwReserved1
장래의 사용에 대비해 예약되고 있다.
dwReserved2
장래의 사용에 대비해 예약되고 있다.

주의

dwFlags 가 0 의 경우, 이펙트는 가능하면 하드웨어에 놓여진다. 하드웨어가 이펙트를 지원 하고 있지 않는 경우는, 소프트웨어가 사용된다. 이펙트를 전혀 이용할 수 없는 경우,SetFX 의 호출은 실패한다.

GUID_DSFX_STANDARD_WAVES_REVERB 클래스의 이펙트는, 16 비트의 오디오 포맷을 갖추는 버퍼상에게만 설정할 수 있다.

동작환경

헤더 : dsound.h 로 선언.

참조

DSBCAPS ,IDirectSoundBuffer8::SetFX ,이펙트의 사용법


DSFXI3DL2Reverb

I3DL2 (Interactive 3D Audio Level 2) 리바브에페크트의 파라미터를 보관 유지한다.

typedef struct _DSFXI3DL2Reverb {
    LONG    lRoom;
    LONG    lRoomHF;
    FLOAT   flRoomRolloffFactor;
    FLOAT   flDecayTime;
    FLOAT   flDecayHFRatio;
    LONG    lReflections;
    FLOAT   flReflectionsDelay;
    LONG    lReverb;
    FLOAT   flReverbDelay;
    FLOAT   flDiffusion;
    FLOAT   flDensity;
    FLOAT   flHFReference;
} DSFXI3DL2Reverb, *LPDSFXI3DL2Reverb;

typedef const DSFXI3DL2Reverb *LPCDSFXI3DL2Reverb;

멤버

lRoom
공간 이펙트의 감쇠. 단위는 밀리 벨 (mB). 값의 범위는 DSFX_I3DL2REVERB_ROOM_MIN 로부터 DSFX_I3DL2REVERB_ROOM_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_ROOM_DEFAULT 또는 -1000 mB 이다.
lRoomHF
고주파수공간 이펙트의 감쇠. 단위는 mB. 값의 범위는 DSFX_I3DL2REVERB_ROOMHF_MIN 로부터 DSFX_I3DL2REVERB_ROOMHF_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_ROOMHF_DEFAULT 또는 0 mB 이다.
flRoomRolloffFactor
반사한 신호의 롤 오프 계수. 값의 범위는 DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MIN 로부터 DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_DEFAULT 또는 0.0 이다. 다이렉트 패스의 롤 오프 계수는, DirectSound 청취자에 의해 제어된다.
flDecayTime
디케이 시간. 단위는 초. 값의 범위는 DSFX_I3DL2REVERB_DECAYTIME_MIN 로부터 DSFX_I3DL2REVERB_DECAYTIME_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_DECAYTIME_DEFAULT 또는 1.49 초이다.
flDecayHFRatio
고주파수의 디케이 시간과 저주파수의 디케이타임의 비. 값의 범위는 DSFX_I3DL2REVERB_DECAYHFRATIO_MIN 로부터 DSFX_I3DL2REVERB_DECAYHFRATIO_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_DECAYHFRATIO_DEFAULT 또는 0.83 이다.
lReflections
lRoom 를 기준으로 하는 초기 반사의 감쇠. 단위는 mB. 값의 범위는 DSFX_I3DL2REVERB_REFLECTIONS_MIN 로부터 DSFX_I3DL2REVERB_REFLECTIONS_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_REFLECTIONS_DEFAULT 또는 -2, 602 mB 이다.
flReflectionsDelay
다이렉트 패스를 기준으로 하는 초기 반사의 지연 시간. 단위는 초. 값의 범위는 DSFX_I3DL2REVERB_REFLECTIONSDELAY_MIN 로부터 DSFX_I3DL2REVERB_REFLECTIONSDELAY_DEFAULT. 디폴트값은 0.007 초이다.
lReverb
lRoom 를 기준으로 하는 후기 리바브의 감쇠. 단위는 mB. 값의 범위는 DSFX_I3DL2REVERB_REVERB_MIN 로부터 DSFX_I3DL2REVERB_REVERB_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_REVERB_DEFAULT 또는 200 mB 이다.
flReverbDelay
최초의 반사 시간을 기준으로 하는, 초기 반사와 후기 리바브간의 제한 시간. 단위는 초. 값의 범위는 DSFX_I3DL2REVERB_REVERBDELAY_MIN 로부터 DSFX_I3DL2REVERB_REVERBDELAY_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_REVERBDELAY_DEFAULT 또는 0.011 초이다.
flDiffusion
후기 리바브디케이의 메아리 밀도. 단위는 퍼센트. 값의 범위는 DSFX_I3DL2REVERB_DIFFUSION_MIN 로부터 DSFX_I3DL2REVERB_DIFFUSION_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_DIFFUSION_DEFAULT 또는 100.0% 이다.
flDensity
후기 리바브디케이의 모덜 밀도. 단위는 퍼센트. 값의 범위는 DSFX_I3DL2REVERB_DENSITY_MIN 로부터 DSFX_I3DL2REVERB_DENSITY_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_DENSITY_DEFAULT 또는 100.0% 이다.
flHFReference
참조 고주파수. 단위는 Hz. 값의 범위는 DSFX_I3DL2REVERB_HFREFERENCE_MIN 로부터 DSFX_I3DL2REVERB_HFREFERENCE_MAX 로, 디폴트값은 DSFX_I3DL2REVERB_HFREFERENCE_DEFAULT 또는 5000.0 Hz 이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXI3DL2Reverb8


DSFXChorus

코러스 이펙트의 파라미터를 보관 유지한다.

typedef struct _DSFXChorus {
    FLOAT       fWetDryMix;
    FLOAT       fDepth;
    FLOAT       fFeedback;
    FLOAT       fFrequency;
    LONG        lWaveform;
    FLOAT       fDelay;
    LONG        lPhase;
} DSFXChorus, *LPDSFXChorus;

typedef const DSFXChorus *LPCDSFXChorus;

멤버

fWetDryMix
웨트 시그널 (처리필 보고)과 드라이 시그널 (미처리)의 비율. 값의 범위는 DSFXCHORUS_WETDRYMIX_MIN 로부터 DSFXCHORUS_WETDRYMIX_MAX (완전하게 웨트)이다.
fDepth
저주파수발진기에 의해 곱셈되는 지연 시간의 퍼센티지. 퍼센티지의 100 배의 값으로 지정한다. 값의 범위는 DSFXCHORUS_DEPTH_MIN 로부터 DSFXCHORUS_DEPTH_MAX 로, 디폴트값은 25 이다.
fFeedback
이펙트의 입력에 피드백되는 출력 신호의 퍼센티지. 값의 범위는 DSFXCHORUS_FEEDBACK_MIN 로부터 DSFXCHORUS_FEEDBACK_MAX 로, 디폴트값은 0 이다.
fFrequency
LFO 의 주파수. 값의 범위는 DSFXCHORUS_FREQUENCY_MIN 로부터 DSFXCHORUS_FREQUENCY_MAX 로, 디폴트값은 0 이다.
lWaveform
LFO 의 웨이브 폼. 정의되고 있는 값은 DSFXCHORUS_WAVE_TRIANGLE 및 DSFXCHORUS_WAVE_SIN 이다. 디폴트에서는, 웨이브 폼은 싸인이다.
fDelay
재생되기 전에 입력이 지연 하는 밀리 세컨드수. 값의 범위는 DSFXCHORUS_DELAY_MIN 로부터 DSFXCHORUS_DELAY_MAX 로, 디폴트값은 0 밀리 세컨드이다.
lPhase
좌우의 LFO 의 위상차이. 값의 범위는 DSFXCHORUS_PHASE_MIN 로부터 DSFXCHORUS_PHASE_MAX 이다. 설정 가능한 값은 다음과 같이 정의되고 있다.
DSFXCHORUS_PHASE_NEG_180
DSFXCHORUS_PHASE_NEG_90
DSFXCHORUS_PHASE_ZERO
DSFXCHORUS_PHASE_90
DSFXCHORUS_PHASE_180

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXChorus8 ,코러스


DSFXCompressor

압축 이펙트의 파라미터를 보관 유지한다.

typedef struct _DSFXCompressor {
    FLOAT   fGain;
    FLOAT   fAttack;
    FLOAT   fRelease;
    FLOAT   fThreshold;
    FLOAT   fRatio;
    FLOAT   fPredelay;
} DSFXCompressor, *LPDSFXCompressor;

typedef const DSFXCompressor *LPCDSFXCompressor;

멤버

fGain
압축 후의 신호의 출력 게인. 값의 범위는 DSFXCOMPRESSOR_GAIN_MIN 로부터 DSFXCOMPRESSOR_GAIN_MAX 로, 디폴트값은 0 dB 이다.
fAttack
압축이 최대치에 이를 때까지의 시간. 값의 범위는 DSFXCOMPRESSOR_ATTACK_MIN 로부터 DSFXCOMPRESSOR_ATTACK_MAX 로, 디폴트값은 0.01 밀리 세컨드이다.
fRelease
입력이 fThreshold 이하가 된 후에 압축을 정지하는 속도. 값의 범위는 DSFXCOMPRESSOR_RELEASE_MIN 로부터 DSFXCOMPRESSOR_RELEASE_MAX 로, 디폴트값은 50 밀리 세컨드이다.
fThreshold
압축을 시작 하는 포인트 (데시벨 단위). 값의 범위는 DSFXCOMPRESSOR_THRESHOLD_MIN 로부터 DSFXCOMPRESSOR_THRESHOLD_MAX 로, 디폴트값은 -10 dB 이다.
fRatio
압축율. 값의 범위는 DSFXCOMPRESSOR_RATIO_MIN 로부터 DSFXCOMPRESSOR_RATIO_MAX. 디폴트값은 10 으로, 이 값은 10:1 의 압축을 나타낸다.
fPredelay
lThreshold 에 이르고 나서 어택 국면이 시작 될 때까지의 시간 (밀리 세컨드 단위). 값의 범위는 DSFXCOMPRESSOR_PREDELAY_MIN 로부터 DSFXCOMPRESSOR_PREDELAY_MAX 로, 디폴트값은 0 밀리 세컨드이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXCompressor8 ,콘프렛션


DSFXDistortion

뒤틀림 이펙트의 파라미터를 보관 유지한다.

typedef struct _DSFXDistortion {
    FLOAT   fGain;
    FLOAT   fEdge;
    FLOAT   fPostEQCenterFrequency;
    FLOAT   fPostEQBandwidth;
    FLOAT   fPreLowpassCutoff;
} DSFXDistortion, *LPDSFXDistortion;

typedef const DSFXDistortion *LPCDSFXDistortion;

    멤버

    fGain
    뒤틀림 후의 신호 변화의 양. 값의 범위는 DSFXDISTORTION_GAIN_MIN 로부터 DSFXDISTORTION_GAIN_MAX 로, 디폴트값은 0 dB 이다.
    fEdge
    뒤틀림의 강도를 나타내는 퍼센티지. 값의 범위는 DSFXDISTORTION_EDGE_MIN 로부터 DSFXDISTORTION_EDGE_MAX 로, 디폴트값은 50% 이다.
    fPostEQCenterFrequency
    더하는 배음 성분의 중심 주파수. 값의 범위는 DSFXDISTORTION_POSTEQCENTERFREQUENCY_MIN 로부터 DSFXDISTORTION_POSTEQCENTERFREQUENCY_MAX 로, 디폴트값은 4000 Hz 이다.
    fPostEQBandwidth
    더하는 배음 성분의 범위를 결정하는 주파수대역의 폭. 값의 범위는 DSFXDISTORTION_POSTEQBANDWIDTH_MIN 로부터 DSFXDISTORTION_POSTEQBANDWIDTH_MAX 로, 디폴트값은 4000 Hz 이다.
    fPreLowpassCutoff
    고주파수배음의 감쇠의 필터 절단. 값의 범위는 DSFXDISTORTION_PRELOWPASSCUTOFF_MIN 로부터 DSFXDISTORTION_PRELOWPASSCUTOFF_MAX 로, 디폴트값은 4000 Hz 이다.

    주의

    fPostEQBandwidth,fPostEQCenterFrequency, 및 fPreLowpassCutoff 의 값은, 버퍼의 주파수의 3 분의 1 을 넘을 수 없다.

    동작환경

    헤더 : dsound.h 로 선언.

    참조

    IDirectSoundFXDistortion8 ,뒤틀림


DSFXEcho

메아리 이펙트의 파라미터를 보관 유지한다.

typedef struct _DSFXEcho {
    FLOAT   fWetDryMix;
    FLOAT   fFeedback;
    FLOAT   fLeftDelay;
    FLOAT   fRightDelay;
    LONG    lPanDelay;
} DSFXEcho, *LPDSFXEcho;

typedef const DSFXEcho *LPCDSFXEcho;

    멤버

    fWetDryMix
    웨트 시그널 (처리필 보고)과 드라이 시그널 (미처리)의 비율. DSFXECHO_WETDRYMIX_MIN 로부터 DSFXECHO_WETDRYMIX_MAX (완전하게 웨트)의 범위가 아니면 안된다.
    fFeedback
    입력에 피드백되는 출력의 퍼센티지. 값의 범위는 DSFXECHO_FEEDBACK_MIN 로부터 DSFXECHO_FEEDBACK_MAX 로, 디폴트값은 0 이다.
    fLeftDelay
    왼쪽 채널의 지연 (밀리 세컨드 단위). 값의 범위는 DSFXECHO_LEFTDELAY_MIN 로부터 DSFXECHO_LEFTDELAY_MAX 로, 디폴트값은 333 밀리 세컨드이다.
    fRightDelay
    오른쪽 채널의 지연 (밀리 세컨드 단위). 값의 범위는 DSFXECHO_RIGHTDELAY_MIN 로부터 DSFXECHO_RIGHTDELAY_MAX 로, 디폴트값은 333 밀리 세컨드이다.
    lPanDelay
    좌우의 디케이를 각각의 연속하는 메아리와 스왑 할지 어떨지를 지정하는 값. 디폴트값은 0 으로, 스왑 하지 않는 것을 의미한다. 가능한 값은, DSFXECHO_PANDELAY_MIN (FALSE 와 등가) 및 DSFXECHO_PANDELAY_MAX (TRUE 와 등가)로서 정의된다.

    동작환경

    헤더 : dsound.h 로 선언.

    참조

    IDirectSoundFXEcho8 ,메아리


DSFXFlanger

플랜지 이펙트의 파라미터를 보관 유지한다.

typedef struct _DSFXFlanger {
    FLOAT   fWetDryMix;
    FLOAT   fDepth;
    FLOAT   fFeedback;
    FLOAT   fFrequency;
    LONG    lWaveform;
    FLOAT   fDelay;
    LONG    lPhase;
} DSFXFlanger, *LPDSFXFlanger;

typedef const DSFXFlanger *LPCDSFXFlanger;

멤버

fWetDryMix
웨트 시그널 (처리필 보고)과 드라이 시그널 (미처리)의 비율. DSFXFLANGER_WETDRYMIX_MIN 로부터 DSFXFLANGER_WETDRYMIX_MAX (완전하게 웨트)의 범위가 아니면 안된다.
fDepth
저주파수발진기 (LFO)에 의해 곱셈되는 지연 시간의 퍼센티지. 퍼센티지의 100 배의 값으로 지정한다. 값은 DSFXFLANGER_DEPTH_MIN 로부터 DSFXFLANGER_DEPTH_MAX 의 범위가 아니면 안된다. 디폴트값은 25 이다.
fFeedback
이펙트의 입력에 피드백되는 출력 신호의 퍼센티지. 값의 범위는 DSFXFLANGER_FEEDBACK_MIN 로부터 DSFXFLANGER_FEEDBACK_MAX 로, 디폴트값은 0 이다.
fFrequency
LFO 의 주파수. 값의 범위는 DSFXFLANGER_FREQUENCY_MIN 로부터 DSFXFLANGER_FREQUENCY_MAX 로, 디폴트값은 0 이다.
lWaveform
LFO 의 웨이브 폼. 디폴트에서는, 웨이브 폼은 싸인이다. 값은 다음과 같이 정의되고 있다.
DSFXFLANGER_WAVE_TRIANGLE
삼각파.
DSFXFLANGER_WAVE_SIN
정현파.
fDelay
재생되기 전에 입력이 지연 하는 밀리 세컨드수. 값의 범위는 DSFXFLANGER_DELAY_MIN 로부터 DSFXFLANGER_DELAY_MAX 로, 디폴트값은 0 밀리 세컨드이다.
lPhase
좌우의 LFO 의 위상차이. 값의 범위는 DSFXFLANGER_PHASE_MIN 로부터 DSFXFLANGER_PHASE_MAX 이다. 설정 가능한 값은 다음과 같이 정의되고 있다.
DSFXFLANGER_PHASE_NEG_180
DSFXFLANGER_PHASE_NEG_90
DSFXFLANGER_PHASE_ZERO
DSFXFLANGER_PHASE_90
DSFXFLANGER_PHASE_180

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXFlanger8 ,플랜지


DSFXGargle

진폭변조 이펙트의 파라미터를 보관 유지한다.

typedef struct _DSFXGargle {
    DWORD  dwRateHz;
    DWORD  dwWaveShape;
} DSFXGargle, *LPDSFXGargle;

typedef const DSFXGargle *LPCDSFXGargle;

멤버

dwRateHz
변조율 (Hz 단위). DSFXGARGLE_RATEHZ_MIN 로부터 DSFXGARGLE_RATEHZ_MAX 의 범위가 아니면 안된다.
dwWaveShape
변조파의 형상. 다음의 플래그가 정의되고 있다.
DSFXGARGLE_WAVE_TRIANGLE
삼각파.
DSFXGARGLE_WAVE_SQUARE
직사각형파.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXGargle8 ,가굴


DSFXParamEq

파라메트릭 이퀼라이저 이펙트의 파라미터를 보관 유지한다.

typedef struct _DSFXParamEq {
    FLOAT fCenter;
    FLOAT fBandwidth;
    FLOAT fGain;
} DSFXParamEq, *LPDSFXParamEq;

멤버

fCenter
중심 주파수 (Hz 단위). 값의 범위는 DSFXPARAMEQ_CENTER_MIN 로부터 DSFXPARAMEQ_CENTER_MAX 이다. 이 값은, 버퍼의 주파수의 3 분의 1 을 넘을 수 없다.
fBandwidth
대역폭 (반음 단위). 값의 범위는 DSFXPARAMEQ_BANDWIDTH_MIN 로부터 DSFXPARAMEQ_BANDWIDTH_MAX 이다.
fGain
게인. 값의 범위는 DSFXPARAMEQ_GAIN_MIN 로부터 DSFXPARAMEQ_GAIN_MAX 이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXParamEq8 ,파라메트릭 이퀼라이저


DSFXWavesReverb

웨브리바브에페크트의 파라미터를 보관 유지한다.

typedef struct _DSFXWavesReverb {
    FLOAT   fInGain;
    FLOAT   fReverbMix;
    FLOAT   fReverbTime;
    FLOAT   fHighFreqRTRatio;
} DSFXWavesReverb, *LPDSFXWavesReverb;

typedef const DSFXWavesReverb *LPCDSFXWavesReverb;

멤버

fInGain
신호의 입력 게인. 단위는 데시벨 (dB). 값의 범위는, DSFX_WAVESREVERB_INGAIN_MIN 로부터 DSFX_WAVESREVERB_INGAIN_MAX. 디폴트값은 DSFX_WAVESREVERB_INGAIN_DEFAULT 또는 0 dB 이다.
fReverbMix
리바브의 믹싱량. 단위는 dB. 값의 범위는, DSFX_WAVESREVERB_REVERBMIX_MIN 로부터 DSFX_WAVESREVERB_REVERBMIX_MAX. 디폴트값은 DSFX_WAVESREVERB_REVERBMIX_DEFAULT 또는 0 dB 이다.
fReverbTime
리바브의 시간. 단위는 밀리 세컨드. 값의 범위는, DSFX_WAVESREVERB_REVERBTIME_MIN 로부터 DSFX_WAVESREVERB_REVERBTIME_MAX. 디폴트값은 DSFX_WAVESREVERB_REVERBTIME_DEFAULT 또는 1000 이다.
fHighFreqRTRatio
값의 범위는, DSFX_WAVESREVERB_HIGHFREQRTRATIO_MIN 로부터 DSFX_WAVESREVERB_HIGHFREQRTRATIO_MAX. 디폴트값은 DSFX_WAVESREVERB_HIGHFREQRTRATIO_DEFAULT 또는 0.001 이다.

동작환경

헤더 : dsound.h 로 선언.

참조

IDirectSoundFXWavesReverb8


WAVEFORMATEX

웨이브 폼 오디오 데이터의 포맷을 정의한다. 이 구조체에는, 웨이브 폼 오디오 데이터 형식 모두에게 공통의 포맷 정보만이 포함된다. 추가 정보가 필요한 포맷에서는, 이 구조체가 최초의 멤버로서 다른 정보와 함께 다른 구조체에 포함된다.

이 구조체는 Platform SDK 의 일부이며, Dsound.h 에서는 선언되지 않는다. 편의상 여기서 설명하고 있다.

typedef struct {
    WORD  wFormatTag;
    WORD  nChannels;
    DWORD nSamplesPerSec;
    DWORD nAvgBytesPerSec;
    WORD  nBlockAlign;
    WORD  wBitsPerSample;
    WORD  cbSize;
} WAVEFORMATEX;

멤버

wFormatTag
웨이브 폼 오디오 포맷의 타입. 많은 압축 알고리즘의 포맷 태그가, Microsoft 로 등록되어 있다. 포맷 태그의 완전한 리스트는, 헤더 파일 Mmreg.h 에 기술되고 있다. 1 채널 또는 2 채널 PCM 데이터의 경우, 이 값은 WAVEFORMAT_PCM 가 된다.
nChannels
웨이브 폼 오디오 데이터의 채널수. 단청의 데이터는 1 개의 채널을 사용해, 스테레오 데이터는 2 개의 채널을 사용한다.
nSamplesPerSec
샘플링 레이트. 1 초 쯤의 샘플수 (Hz)로 나타낸다. wFormatTag 가 WAVE_FORMAT_PCM 의 경우, nSamplesPerSec 의 일반적인 값은 8.0 kHz, 11.025 kHz, 22.05 kHz, 및 44.1 kHz 이다. PCM 포맷이 아닌 경우, 이 멤버는 메이커의 포맷 태그의 사양에 따라 계산할 필요가 있다.
nAvgBytesPerSec
포맷 태그로 필요한 평균 데이터 전송 속도. 단위는, 1 초 쯤의 바이트수. wFormatTag 가 WAVE_FORMAT_PCM 인 경우,nAvgBytesPerSec 는 nSamplesPerSec 와 nBlockAlign 의 적에 동일하게 한다. PCM 포맷이 아닌 경우, 이 멤버는 메이커의 포맷 태그의 사양에 따라 계산할 필요가 있다.
nBlockAlign
브록크아라이먼트 (바이트 단위). 브록크아라이먼트는,wFormatTag 포맷 타입의 최소단위이다. wFormatTag 가 WAVE_FORMAT_PCM 또는 WAVE_FORMAT_EXTENSIBLE 인 경우,nBlockAlign 는 nChannels 와 wBitsPerSample 의 적을 8 으로 나눈 값 (바이트 근처의 비트수)에 동일해질 필요가 있다. PCM 포맷이 아닌 경우, 이 멤버는 메이커의 포맷 태그의 사양에 따라 계산할 필요가 있다.

소프트웨어는, 복수의 nBlockAlign 바이트를, 한 번에 처리해야 한다. 디바이스에 기입하는 데이터, 및 디바이스로부터 읽어들이는 데이터는, 항상 블록의 선두로부터 시작 해야 한다. 예를 들어, PCM 데이터의 재생을, 샘플의 중간 (즉, 비블록 정렬의 경계)으로 시작 하는 것은 부정하다.

wBitsPerSample
wFormatTag 포맷 타입의, 샘플링 근처의 비트수. wFormatTag 가 WAVE_FORMAT_PCM 인 경우,wBitsPerSample 는 8 또는 16 으로 한다. wFormatTag 가 WAVE_FORMAT_EXTENSIBLE 인 경우는, 임의의 8 의 배수를 설정할 수 있다.
cbSize
WAVEFORMATEX 구조체의 뒤로 추가되는 포맷 정보의 사이즈 (바이트 단위). 이 정보를 비 PCM 포맷으로 사용해,wFormatTag 의 추가 속성을 저장 할 수가 있다. wFormatTag 로 필요한 추가 정보가 없는 경우, 이 멤버는 0 으로 설정해야 한다. WAVE_FORMAT_PCM 포맷에서는, 이 멤버는 무시된다.

동작환경

헤더 : mmreg.h 로 선언.

참조

WAVEFORMATEXTENSIBLE


WAVEFORMATEXTENSIBLE

3 개(살) 이상의 채널을 가지는 포맷에 대해, 웨이브 폼 오디오 데이터의 포맷을 결정한다.

이 구조체는 Platform SDK 의 일부이며, Dsound.h 에서는 선언되지 않는다. 편의상 여기서 설명하고 있다.

typedef struct {
    WAVEFORMATEX  Format;
    union {
        WORD      wValidBitsPerSample;
        WORD      wSamplesPerBlock;
        WORD      wReserved;
    } Samples;
    DWORD         dwChannelMask;
    GUID          SubFormat;
} WAVEFORMATEXTENSIBLE, *PWAVEFORMATEXTENSIBLE;

멤버

Format
기본 포맷을 지정하는 WAVEFORMATEX 구조체. wFormatTag 멤버는, Mmreg.h 로 정의된 WAVE_FORMAT_EXTENSIBLE 가 아니면 안된다. cbSize 멤버는, 적어도 22 가 아니면 안된다.
wValidBitsPerSample
신호중의 정밀도의 비트수. 보통은 WAVEFORMATEX.wBitsPerSample 에 동일하다.
wSamplesPerBlock
압축된 1 블록의 오디오 데이터에 보관 유지되는 샘플수. 이 값이 0 의 경우, 각 블록의 샘플수는 가변이 된다.
wReserved
wValidBitsPerSample 및 wSamplesPerBlock 가 포맷에 적용되지 않는 경우는, 0 으로 설정한다.
dwChannelMask
채널을 지정하는 비트 마스크. 「주의」를 참조할것.
SubFormat
데이터의 서브 포맷. Ksmedia.h 로 정의되고 있는 KSDATAFORMAT_SUBTYPE_PCM 가 아니면 안된다.

주의

dwChannelMask 멤버는, 멀티 채널 스트림에서의 채널을 나타낸다. 최하정도 비트가 운이 나빠짐의 스피커, 다음의 비트가 오른쪽앞의 스피커와 같이, 각 비트가 대응하고 있다. 각 비트는 순서에, Ksmedia.h 및 Mmreg.h 로 다음과 같이 정의되고 있다.

SPEAKER_FRONT_LEFT
SPEAKER_FRONT_RIGHT
SPEAKER_FRONT_CENTER
SPEAKER_LOW_FREQUENCY
SPEAKER_BACK_LEFT
SPEAKER_BACK_RIGHT
SPEAKER_FRONT_LEFT_OF_CENTER
SPEAKER_FRONT_RIGHT_OF_CENTER
SPEAKER_BACK_CENTER
SPEAKER_SIDE_LEFT
SPEAKER_SIDE_RIGHT
SPEAKER_TOP_CENTER
SPEAKER_TOP_FRONT_LEFT
SPEAKER_TOP_FRONT_CENTER
SPEAKER_TOP_FRONT_RIGHT
SPEAKER_TOP_BACK_LEFT
SPEAKER_TOP_BACK_CENTER
SPEAKER_TOP_BACK_RIGHT

이 구조체의 상세한 것에 대하여는,http://www.microsoft.com/hwdev/audio/multichaud.htm 의 「Enhanced Audio Formats for Multi-Channel Configurations and High-Bit Resolution」를 참조할것.

동작환경

헤더 : mmreg.h 및 ksproxy.h 로 선언.


DirectSound 반환값

여기에서는, DirectSound 의 메소드에 의해 돌려주어질 가능성이 있는 다양한 에러 코드에 대해 간단하게 설명한다. 각 메소드가 돌려줄 가능성이 있는 특정의 코드의 리스트에 대해서는, 개별의 메소드의 설명을 참조할것. 그러한 리스트는 반드시 포괄적인 것이라고는 할 수 없다.

에러 코드는 이하의 주제에 나타나고 있다.

  • DirectSound 반환값 (값)
  • DirectSound 반환값 (이름)


DirectSound 반환값 (값)

다음의 표는, 16 진값으로 저장 되는 DirectSound 반환값을 나타내고 있다. 설명에 대해서는, 정수를 클릭하는 것.

16 진값 | 정수
0x00000000 | DS_OK
0x00000007 | DSERR_OUTOFMEMORY
0x000001AE | DSERR_NOINTERFACE
0x0878000A | DS_NO_VIRTUALIZATION
0x08780014 | DS_INCOMPLETE
0x80004001 | DSERR_UNSUPPORTED
0x80004005 | DSERR_GENERIC
0x80070005 | DSERR_ACCESSDENIED
0x80070057 | DSERR_INVALIDPARAM
0x8878000A | DSERR_ALLOCATED
0x8878001E | DSERR_CONTROLUNAVAIL
0x88780032 | DSERR_INVALIDCALL
0x88780046 | DSERR_PRIOLEVELNEEDED
0x88780064 | DSERR_BADFORMAT
0x88780078 | DSERR_NODRIVER
0x88780082 | DSERR_ALREADYINITIALIZED
0x88780096 | DSERR_BUFFERLOST
0x887800A0 | DSERR_OTHERAPPHASPRIO
0x887800AA | DSERR_UNINITIALIZED
0x887810B4 | DSERR_BUFFERTOOSMALL
0x887810BE | DSERR_DS8_REQUIRED
0x88781161 | DSERR_OBJECTNOTFOUND


DirectSound 반환값 (이름)

다음의 리스트는, 모든 DirectSound 반환값을 나타내고 있다. 값으로부터 정수를 확인하려면 , 「DirectSound 반환값 (값)」를 참조할것.

DS_OK
메소드는 성공했다.
DS_NO_VIRTUALIZATION
버퍼는 생성 되었지만, 다른 3D 알고리즘이 대용되었다.
DS_INCOMPLETE
메소드는 성공했지만, 얻지 못하고 있는 옵션 이펙트도 있다.
DSERR_ACCESSDENIED
액세스가 거부되었기 때문에, 요구는 실패했다.
DSERR_ALLOCATED
우선 레벨등의 리소스가 다른 호출해에 의해 이미 사용중이기 (위해)때문에, 요구는 실패했다.
DSERR_ALREADYINITIALIZED
오브젝트는 이미 초기화되고 있다.
DSERR_BADFORMAT
지정한 웨이브 포맷은 지원되어 있지 않다.
DSERR_BUFFERLOST
버퍼 메모리가 없어졌기 때문에, 복원하지 않으면 안 된다.
DSERR_BUFFERTOOSMALL
버퍼 사이즈가 불충분해, 이펙트 처리를 실행할 수 없다.
DSERR_CONTROLUNAVAIL
호출원이 요구하는 버퍼 컨트롤 (볼륨, 빵등)은 이용할 수 없다.
DSERR_DS8_REQUIRED
요구된 기능에 대해서, CLSID_DirectSound8 클래스 또는 그 이후의 DirectSound 오브젝트가 요구되고 있다. 상세한 것에 대하여는, 「IDirectSound8 」를 참조할것.
DSERR_GENERIC
DirectSound 서브 시스템내에서 불확정의 에러가 발생했다.
DSERR_INVALIDCALL
이 오브젝트의 현재 상태에서는, 이 함수는 유효하지 않다.
DSERR_INVALIDPARAM
무효인 파라미터가 함수에게 건네졌다.
DSERR_NOAGGREGATION
이 오브젝트는 COM 집합화를 지원 하지 않는다.
DSERR_NODRIVER
이용 가능한 사운드 드라이버가 존재하지 않는지, 지정한 GUID 가 유효한 DirectSound 디바이스 ID 는 아니다.
DSERR_NOINTERFACE
요구된 COM 인터페이스는 이용할 수 없다.
DSERR_OBJECTNOTFOUND
요구된 오브젝트가 발견되지 않았다.
DSERR_OTHERAPPHASPRIO
다른 어플리케이션이 보다 높은 우선 레벨을 가지고 있기 (위해)때문에, 이 호출은 성공하지 않았다.
DSERR_OUTOFMEMORY
DirectSound 서브 시스템은, 호출원의 요구를 완료하기 위한 충분한 메모리를 할당할 수 없었다.
DSERR_PRIOLEVELNEEDED
호출원래는, 함수를 성공시키기 위해서(때문에) 필요한 우선 레벨을 가지고 있지 않다.
DSERR_UNINITIALIZED
다른 메소드를 호출하기 전에 IDirectSound8::Initialize 메소드를 호출하지 않았는지, 호출이 성공하지 않았다.
DSERR_UNSUPPORTED
호출한 함수는 이 시점에서는 지원되어 있지 않다.


DirectInput

이 섹션에서는, Microsoft® DirectX® API (Application Programming Interface)의 Microsoft DirectInput® 컴퍼넌트에 대해 설명한다. DirectInput API 는, 키보드, 마우스, 죠이스틱, 그 외 게임 콘트롤러로부터의 데이터의 처리에 사용한다.

문서의 개요에 대해서는, 「도로지도」를 참조할것.


도로지도

Microsoft® DirectInput® 의 사용에 대해, 이하의 섹션으로 나누어 설명한다. 이 페이지는, DirectInput 개발자로서의 경험 레벨에 응한 문서의 가이드로서 이용할 수 있다.

DirectInput 의 신기능 . Microsoft® DirectX® 의 이번 버젼으로 추가된 기능의 통계. 이미 Microsoft DirectInput® 를 사용한 경험이 있어, 신기능을 이용하고 싶은 경우는, 이 섹션을 참조한다.

DirectInput 의 개요 . DirectInput 의 기능과 그 이행 순서에 대한 고도의 개요. DirectInput 를 처음으로 사용하는 유저는, 이 섹션으로부터 읽기 시작하는 것.

DirectInput 에 대해 . DirectInput 의 오브젝트와 인터페이스에 대하고, 그리고 Microsoft Windows® 메세지 시스템과의 관계에 대한 개요. DirectInput 를 처음으로 사용하는 유저는, 이 섹션을 참조할것.

DirectInput 의 사용법 . API (application programming interface)의 설명. 이 섹션에서는, 전의 2 개의 섹션보다 자세한 개념적인 정보를 설명한다. 또, 디바이스의 설정, 데이터의 취득, force feedback 이펙트의 이행으로 사용하는 API 요소에 대해서도 설명한다. 초심자의 경우는, 적어도, 이 섹션의 내용을 잘 이해하는 것. 다음에 필요한 주제를 참조할것이 생긴다. 이 섹션은, 「DirectInput C/C++ 레퍼런스」라고 아울러 이용한다.

프로그래밍의 힌트와 툴 . 고도의 프로그래밍 관련 주제와 DirectX Software Development Kit (SDK) 부속의 DirectInput 툴에 대한 설명.

DirectInput C/C++ 튜토리얼 . 대부분의 경우, SDK 의 샘플에 근거하는 스텝바이스텝 방식의 튜토리얼. 샘플 코드를 사용한다고 이해하기 쉬운 경우는, 「DirectInput 의 개요」와「DirectInput 에 대하며」를 읽은 후, 이 튜토리얼에 진행되는 것이 좋다.

DirectInput C/C++ 샘플 . SDK 에 부속되어 있는 DirectInput 의 C/C++ 샘플 어플리케이션에의 가이드. DirectInput 의 사용 방법, 기능등이 설명되고 있다.

DirectInput C/C++ 레퍼런스 . API 의 레퍼런스 정보. 인터페이스, 메소드, 구조체, 매크로, 그 외 요소의 상세를 알고 싶은 경우는, 이 섹션을 이용한다.


DirectInput 의 신기능

Microsoft® DirectInput® 의 신기능은 다음과 같다.

액션 매핑
Microsoft DirectInput for Microsoft DirectX® 8.0 에서는, 액션 매핑이라고 하는 중요한 신기능이 도입되었다. 액션 매핑은, 특정의 디바이스 오브젝트 (특정의 버튼이나 축)의 존재에 의존하지 않는, 입력 액션과 입력 디바이스와의 사이의 접속 확립을 가능하게 한다. 액션 매핑은, 입력 루프를 간소화해, 게임에 있어서의 커스텀의 게임 드라이버, 커스텀의 디바이스 프로 filer, 및 커스텀의 환경 설정 유저 인터페이스의 필요성을 경감한다.

상세한 것에 대하여는, 「액션 매핑」을 참조할것.

DirectInput 오브젝트의 신기능
DirectInput 오브젝트는,IDirectInput8 인터페이스에 의해 표현된다. 새로운 헬 바 함수 DirectInput8Create 는, 오브젝트를 생성 해, 이 인터페이스를 취득한다. IDirectInput8 에는 새로운 CLSID 가 있어, 지금까지의 DirectX 버젼으로 사용되고 있던 클래스 CLSID_DirectInput 의 오브젝트에 대한 인터페이스상에서 QueryInterface 를 호출해도 취득할 수 없다.
새로운 키보드 프로퍼티
2 개의 키보드 프로퍼티가 추가되었다. 로컬라이즈 된 키명을 취득하는 DIPROP_KEYNAME 와 스캔 코드를 취득하는 DIPROP_SCANCODE 이다.
rglSlider 배열내의 죠이스틱 슬라이더 데이터
죠이스틱 슬라이더 데이터는, DirectX 의 전의 버젼에서는 DIJOYSTATE 또는 DIJOYSTATE2 구조체의 Z 축으로 할당할 수 있고 있었지만, 이번 버젼에서는 같은 구조체의 rglSlider 배열내에 저장 된다.


DirectInput 의 개요

Microsoft® DirectInput® 는, 마우스, 키보드, 죠이스틱, 그 외 게임 콘트롤러의 입력 디바이스에 가세해 force feedback (입출력) 디바이스도 지원 하는 API 이다.

이 섹션에서는, DirectInput 의 능력과 어플리케이션에서의 설정 방법법에 대해, 간단한 개요를 설명한다. 이하의 주제로 나누어, 설명한다.

  • DirectInput 의 파워
  • DirectInput 의 기초지식

DirectInput 의 기능의 종합적 설명에 대해서는, 「DirectInput 에 대하며」를 참조할것.

DirectInput API (application programming interface)의 사용법을 스텝바이스텝 방식에서 설명하는 가이드에 대해서는, 이하의 주제를 참조할것.

  • DirectInput 의 사용법
  • DirectInput C/C++ 튜토리얼


DirectInput 의 파워

Microsoft® DirectInput® 는, Microsoft Win32® API 가 지원 하고 있지 않는 디바이스에 새로운 서비스를 제공하는 것에 가세해 Microsoft Windows® 메세지에 의존하지 않고 , 하드웨어 드라이버와 직접 통신하는 것으로써, 입력 데이터에의 액세스를 고속화하고 있다.

DirectInput 를 사용하면(자), 어플리케이션이 백그라운드에 있는 경우에서도, 입력 디바이스에 대한 액세스권을 취득할 수 있다. 또, force feedback외, 모든 타입의 입력 디바이스를 완전하게 지원 하고 있다.

액션 매핑을 개입시켜, 어플리케이션은, 데이터가 어떤 디바이스로 생성되었는지를 몰라도, 입력 데이터를 취득할 수가 있다.

DirectInput 의 확장 서비스와 성능의 개선에 의해, DirectInput 는, Windows 로 동작하는 게임, 시뮬레이션, 및 그 외의 리얼타임 대화형 어플리케이션에 대한 유용한 툴이 되고 있다.

DirectInput 에서는, 텍스트 입력에 키보드를 사용하거나 이동에 마우스를 사용하는 어플리케이션이 유리하게 될 것은 없다. 상세한 것에 대하여는, 「Windows 와의 상호작용」을 참조할것.


DirectInput 의 기초지식

여기에서는, Microsoft® DirectInput® 의 설정법과 단순한 어플리케이션에서의 사용에 관한 개요에 대해 설명한다.

이 스텝의 상세와 예에 대해서는, 「DirectInput 의 사용법」과「DirectInput C/C++ 튜토리얼」을 참조할것.

주 : DirectInput 를 이해하려면 , 이하의 용어를 이해할 필요가 있다.

  • DirectInput 오브젝트 : 루트의 DirectInput 인터페이스.
  • 디바이스 : 키보드, 마우스, 죠이스틱, 그 외의 입력 디바이스.
  • DirectInputDevice 오브젝트 : 키보드, 마우스, 죠이스틱, 그 외의 입력 디바이스를 나타내는 코드.
  • 디바이스 오브젝트 : DirectInput 디바이스 오브젝트 위에의 키, 버튼, 방아쇠등을 나타내는 코드. 디바이스 오브젝트 인스턴스 라고도 부른다.

이하의 스텝은, 어플리케이션에 대해, 어느 디바이스 오브젝트 (버튼, 축등)가 데이터 항목을 생성했는지를 확인하기 위한 DirectInput 의 단순한 이행을 나타내고 있다.

  1. DirectInput 오브젝트를 생성 한다. 이 오브젝트의 메소드를 사용해, 디바이스를 열거해, DirectInput 디바이스 오브젝트를 생성 한다.
  2. 디바이스를 열거한다. 시스템 마우스 또는 키보드만을 사용하는 경우는, 이 스텝은 반드시 필요하지 않다. 유저의 시스템상에서 그 밖에 어떤 입력 디바이스를 사용할 수 있는지를 확인하려면 , DirectInput 에 디바이스를 열거시킨다. DirectInput 는, 설정 기준과 일치하는 디바이스를 발견할 때마다, 그 능력을 체크할 기회를 제공해 준다. 또, 그 디바이스를 나타내는 DirectInput 디바이스 오브젝트를 생성하기 위한 고유의 식별자도 취득한다.
  3. 사용 디바이스 마다 DirectInputDevice 오브젝트를 생성 한다. 이것에는, 열거중에 취득된 고유의 식별자가 필요하다. 시스템 마우스 또는 키보드에 대해서는, 표준의 GUID 를 사용할 수 있다.
  4. 디바이스를 설정한다. 디바이스 마다, 우선 협조 레벨을 설정해, 다른 어플리케이션이나 시스템과 그 디바이스를 공유하는 방법을 지정한다. 또, 데이터 패킷내에서, 버튼이나 축 등 그 디바이스 오브젝트를 식별하기 위한 데이터 형식을 설정한다. 버퍼링 데이터를 취득하는 경우 (스테이트는 아니고 이벤트를 취득하는 경우)는, 버퍼 사이즈도 설정할 필요가 있다. 옵션으로서 이 단계에서 디바이스에 관한 정보를 취득해, 어플리케이션의 동작을 거기에 응해 조정한다. 또, 죠이스틱의 축으로야는 돌려주어지는 값의 범위등의 프로파테이를 설정할 수도 있다.
  5. 디바이스를 취득한다. 이 단계에서, DirectInput 에 대해, 디바이스로부터 데이터를 받을 준비를 할 수 있던 것을 통지한다.
  6. 데이터를 취득한다. 일정한 간격으로, 보통은 메시지 루프 또는 렌더링 루프를 1 회 반복할 때마다, 각 디바이스의 현재 상태나 전회 취득 후에 발생한 이벤트의 기록의 어느쪽이든을 취득한다. 기호에 응해, 이벤트가 발생하면(자) DirectInput 로부터 통지시킬 수도 있다.
  7. 데이터를 처리한다. 어플리케이션은, 버튼이나 축 상태인가, 키가 밀리고 있을까 떼어 놓아지고 있을까 등의 이벤트의 어느 쪽인가에 반응할 수 있다.
  8. DirectInput 를 종료한다. 종료하기 전에, 어플리케이션은 모든 디바이스의 취득을 해제해 해방해, 다음에 DirectInput 오브젝트를 해방해야 한다.

DirectInput 를 이행 하는 방법은, 이만큼은 아니다. 현재 사용되고 있다, 또는 장래 사용되는 버라이어티 풍부한 입력 디바이스를 활용하기 위해(때문에), 또 유저의 환경 설정을 간소화하기 위해(때문에), 액션 매핑을 사용할 수가 있다.

디바이스에 액션 매핑을 설정하는 것으로써, 어플리케이션의 각 액션에 사용하는 디바이스 오브젝트를, DirectInput 로 결정하게 할 수가 있다. 예를 들어 레이싱 게임에서, 스롯톨이 항상 y 축으로야는 제어되도록(듯이) 지정하는 대신에, AXIS_THROTTLE 라고 하는 액션을 생성 해, 디바이스상에서 가장 적절한 축으로 DirectInput 가 액션을 할당하도록(듯이) 할 수가 있다. 이벤트를 취득했을 때는, 그 이벤트를 생성한 디바이스 오브젝트는 아니고, 그 이벤트에 관련지을 수 있고 있는 액션에 의해 이벤트를 식별한다.

상세한 것에 대하여는, 「액션 매핑」을 참조할것.


DirectInput 에 대해

이 섹션에서는, Microsoft® DirectInput® 의 기본 구조와 Microsoft Windows® 메세지 시스템과 DirectInput 간의 관계에 대해 설명한다.

  • DirectInput 오브젝트
  • Windows 와의 상호작용

여기서 설명하는 DirectInput 의 각 요소의 이행 방법에 대해서는, 「DirectInput 의 사용법」을 참조할것.


DirectInput 오브젝트

입력 전용의 Microsoft® DirectInput® 의 이행은,IDirectInput8 COM 인터페이스를 지원 하는 DirectInput 오브젝트와 데이터를 제공하는 입력 디바이스마다의 DirectInputDevice 오브젝트로 구성된다. 그리고 각 DirectInputDevice 오브젝트는, 키, 버튼, 축등의 개별의 제어 수단 또는 스윗치인 디바이스 오브젝트 를 가진다. 디바이스 오브젝트는, 디바이스 오브젝트 인스턴스라고도 불린다.

각각의 DirectInputDevice 오브젝트는, 마우스, 키보드, 또는 죠이스틱등의 입력 디바이스를 나타내는 DirectInput API 에서는,죠이스틱이라고 하는 용어는, 마우스나 키보드 이외의 입력 디바이스를 가리킨다. 터치 패드 첨부 키보드 등, 실제로는 다른 종류의 입력 디바이스를 조합한 물리 디바이스는, 2 개(살) 또는 그 이상의 DirectInputDevice 오브젝트로서 나타내진다. force feedback 디바이스는, 입력과 출력의 양쪽 모두를 조작하는 1 개의 죠이스틱 오브젝트로서 나타내진다.

DirectInputDevice 오브젝트는,IDirectInputDevice8 인터페이스를 인스턴스화한다. 어플리케이션은, 디바이스상에서 사용 가능한 오브젝트의 수와 타입을 IDirectInputDevice8::EnumObjects 메소드를 사용해 확인한다. 개별의 디바이스 오브젝트는, 코드 오브젝트로서 캡슐화되지 않고 ,DIDEVICEOBJECTINSTANCE 구조체로서 기술된다.

force feedback 이펙트는,IDirectInputEffect 인터페이스에 의해 나타내진다. 이 인터페이스의 각 메소드를 사용해, 이펙트의 생성, 변경, 시작, 및 정지를 실시한다.

모든 DirectInput 인터페이스는, ANSI 판과 Unicode 판으로 사용할 수 있다. 컴파일시에 「UNICODE」가 정의되고 있는 경우는, UNICODE 판이 사용된다.


Windows 와의 상호작용

Microsoft® DirectInput® 는 디바이스 드라이버에 직접 움직여 동작하므로, Microsoft Windows® 의 마우스 메세지와 키보드 메세지는 억제 또는 무시된다. DirectInput 는, 컨트롤 패널로 유저가 간 마우스와 키보드의 설정도 무시한다. 다만, 죠이스틱이나 그 외의 게임 콘트롤러의 calibration의 설정은 사용한다.

DirectInput 는, 키보드의 문자 반복의 설정을 인식하지 않는다. 버퍼링 데이터를 이용하고 있을 때는, DirectInput 는, 개개의 키의 「밀기」와「떼어 놓아」를 반복 없음의 1 개의 이벤트로서 해석한다. 직접 데이터를 이용하고 있을 때는, DirectInput 가 관여하는 것은 키의 현재의 물리적 상태뿐이어, Windows 로 해석되는 키보드 이벤트에는 관여하지 않는다.

DirectInput 는, 문자 변환이나 평행이동을 실행하지 않는다. 예를 들어 Shift 키는, 다른 키의 수정 자식으로는 아니고, 다른 키와 같이 처리된다. 키는, 유저의 시스템 언어 설정에 관계없이, 같은 식별자를 돌려준다.

Windows 2000 에서는, 배타 모드로 키보드를 취득 하면, 그 후로 기동된 어느 어플리케이션도 키보드 데이터를 취득할 수 없게 된다.

DirectInput 는 직접 마우스 드라이버에 작용하기 위해(때문에), 윈도우 표시 어플리케이션에 대해서 마우스 데이터를 해석하는 Windows 서브 시스템을 우회도로 한다. Windows 커서를 사용해 이동하는 어플리케이션은, 표준의 Windows 마우스 메세지 및 Microsoft® Win32® 함수를 사용한다.

배타 모드로 마우스를 사용 하면, DirectInput 는 마우스 메세지를 억제한다. 그 결과, Windows 는 표준 커서를 표시할 수 없게 된다.

DirectInput 는 가속값이나 버튼 기능의 교체등의 컨트롤 패널의 설정을 무시한다. 그러나, 드라이버 그 자체로 설정을 인식한다. 예를 들어, 유저가 3 개 버튼의 마우스를 가지고 있어, 드라이버 유틸리티 소프트웨어를 사용해 중앙의 버튼에 더블 클릭의 쇼트 컷을 할당하면(자), DirectInput 는, 중앙의 버튼의 1 회의 클릭을 주버튼의 2 회의 클릭으로서 보고한다.


DirectInput 의 사용법

여기에서는, Microsoft® DirectInput® 의 이행에 대해 설명한다. 보다 폭넓은 개요에 대해서는, 「DirectInput 에 대하며」를 참조할것.

다음의 토픽에 대해 해설한다.

  • DirectInput 의 생성
  • DirectInput 디바이스의 열거
  • DirectInput 디바이스
  • DirectInput 디바이스 데이터
  • 액션 매핑
  • force feedback


DirectInput 의 생성

Microsoft® DirectInput® 어플리케이션에서는, 반드시 최초로 IDirectInput8 인터페이스를 취득한다. 이것을 가장 간단하게 실시하는 방법은,DirectInput8Create 함수를 호출하는 것이다.

단일의 Microsoft® DirectInput 오브젝트를 생성 해, 어플리케이션이 종료할 때까지 해방해서는 안된다.


DirectInput 디바이스의 열거

Microsoft® DirectInput® 는, 모든 사용 가능한 입력 디바이스를 시스템에 문의해 그것들이 접속되고 있는지 어떤지를 판정해, 그러한 디바이스에 관한 정보를 돌려줄 수가 있다. 이 프로세스를 열거라고 부른다.

표준의 키보드나 마우스, 또는 그 양쪽 모두만을 어플리케이션으로 사용하고 있다면, 사용 가능한 입력 디바이스를 열거할 필요는 없다. 「DirectInput 디바이스의 생성」으로 설명하도록(듯이),IDirectInput8::CreateDevice 메소드를 호출하면나무는, 사전 정의된 글로벌 변수를 사용할 수 있다.

다른 모든 입력 디바이스, 및 복수의 키보드 또는 마우스를 사용하는 시스템에 관해서는,IDirectInput8::EnumDevices 및 IDirectInput8::EnumDevicesBySemantics 를 호출해, 사용 가능한 디바이스를 열거해, 적절한 디바이스를 선택할 수가 있다. 또, 열거해, 사용 가능한 디바이스를 유저가 선택할 수 있도록(듯이) 할 수도 있다.

이하는,IDirectInput8::EnumDevices 메소드 이행의 예이다.

/* lpdi 는, 유효한 IDirectInput8 인터페이스 포인터이다.  */

GUID KeyboardGUID = GUID_SysKeyboard;

lpdi->EnumDevices(DIDEVTYPE_KEYBOARD,
                  DIEnumDevicesCallback,
                  &KeyboardGUID,
                  DIEDFL_ATTACHEDONLY);

1 번째의 파라미터는, 열거해야 할 디바이스의 타입을 지정한다. 타입에 관계없이 모든 디바이스를 열거하고 싶으면, NULL 로 한다. 그 이외는,DIDEVICEINSTANCE 에 설명이 있는 DIDEVTYPE_* 값의 1 개를 지정한다.

2 번째의 파라미터는, 열거된 각 디바이스에 대해서 한 번 두개 불려 가는 콜백 함수에의 포인터이다. 이 함수는, 어떠한 이름이라도 좋지만, 여기에서는 플레이스홀더명의 DIEnumDevicesCallback 를 사용한다.

EnumDevices 메소드의 3 번째의 파라미터는, 콜백 함수에 건네주는 임의의 32 비트의 값이다. 이 예에서는,GUID 형의 변수에의 포인터이며, 콜백 함수가 이 변수에의 키보드 인스턴스 식별자를 할당할 수가 있도록(듯이) 건네받는다.

4 번째의 파라미터는, 열거 대상이 전디바이스인가, 또는어태치 되고 있는 디바이스만 (DIEDFL_ALLDEVICES 또는 DIEDFL_ATTACHEDONLY)인지를 지정하는 플래그이다.

어플리케이션이 복수의 입력 디바이스를 사용하고 있는 경우, 열거되었던 대로 디바이스를 초기화하려면 , 콜백 함수를 사용하는 것이 적합하다 (예에 대해서는, 「튜토리얼 3 : 죠이스틱의 사용법」을 참조할것). 디바이스의 인스턴스 GUID 를 콜백 함수로부터 취득한다. 여기에서는, 디바이스의 특정의 서브 타입을 검색하거나 디바이스명을 리스트 박스에 추가하거나 하는 등, 다른 처리를 실행할 수도 있다.

이하의 코드는, 확장 키보드의 존재를 체크해, 발견되면 열거를 정지하는 코드의 예이다. 발견된 키보드의 인스턴스 GUID 를 KeyboardGUID 변수 (전의 예의 EnumDevices 의 호출로 pvRef 로서 건네받는다)에 할당한다. 이 변수는, 다음에 IDirectInput8::CreateDevice 를 호출할 때에 사용할 수 있다.

BOOL  hasEnhanced;

BOOL CALLBACK DIEnumKbdCallback(LPCDIDEVICEINSTANCE lpddi,
                                LPVOID pvRef)
{
  *(GUID*) pvRef = lpddi->guidInstance;
  if (GET_DIDEVICE_SUBTYPE(lpddi->dwDevType) ==
                       DIDEVTYPEKEYBOARD_PCENH)
  {
    hasEnhanced = TRUE;
    return DIENUM_STOP;
  }
  return DIENUM_CONTINUE;
} // 콜백의 종료.

1 번째의 파라미터는, 디바이스의 정보를 저장 하는 DIDEVICEINSTANCE 구조체를 가리킨다. 이 구조체는, DirectInput 가 자동적으로 생성 한다.

2 번째의 파라미터는,EnumDevices 로부터 건네받은 데이터를 가리킨다. 이 경우는, 변수 KeyboardGUID 에의 포인터이다. 이 변수에는 당초, 디폴트값을 할당할 수 있고 있지만, 디바이스가 열거될 때마다, 새로운 값을 할당할 수 있다. 단일의 키보드에 대해서 어느 인스턴스 GUID 를 사용할까는 실제로는 중요하지 않지만, 위의 코드는, 콜백 함수로부터 인스턴스 GUID 를 취득하는 기법을 구체적으로 가리키고 있다.

인스턴스 GUID 를 보존해, 다음에 DirectInputDevice 를 생성 할 수 있도록(듯이) 하는 것이 아니라, 열거중에 DirectInput 에 의해 생성 된 디바이스를 보존할 수 있다. 상세한 것에 대하여는, 「DirectInput 디바이스의 생성」을 참조할것.

이 경우의 반환값은, 검색 대상의 디바이스가 발견되면 열거를 정지해, 그렇지 않으면 속행하는 것을 나타낸다. 열거는, 전디바이스의 열거가 종료 하면 즉시 자동적으로 정지한다.

IDirectInput8::EnumDevicesBySemantics 에 의한 디바이스 열거의 상세한 것에 대하여는, 「액션 매핑」을 참조할것.


DirectInput 디바이스

여기에서는, 마우스, 키보드, 죠이스틱등의 디바이스를 나타내는 코드 오브젝트에 대해 기술한다. 이하의 토픽에 대해 설명한다.

  • 디바이스의 셋업
  • DirectInput 디바이스의 생성
  • 디바이스 능력
  • 협조 레벨
  • 디바이스 오브젝트의 열거
  • 디바이스 데이터 형식
  • 디바이스 프로퍼티
  • 디바이스의 취득

디바이스로부터의 데이터의 취득 및 해석의 방법에 대한 정보는, 「DirectInput 디바이스 데이터」를 참조할것.


디바이스의 셋업

어플리케이션은, 입력을 하는 디바이스 마다 Microsoft® DirectInput® 디바이스 오브젝트를 취득해야 한다. 그 디바이스를 사용할 수 있도록(듯이), 최저한에서도 데이터 형식의 설정이나 디바이스의 취득등의 준비도 해야 한다. 그 밖에도, 디바이스에 관한 정보의 수집이나 디바이스의 프로퍼티의 변경 등, 독자적인 태스크를 실행하는 일도 있다.

이하의 태스크는, 셋업 순서의 일부이다. 순서안에는 필수의 것도 있으면, 디바이스의 상세 정보를 필요로 하는 경우, 혹은 디폴트값을 변경해야 하는 경우에 한정해 필요한 것도 있다.

  1. DirectInput 디바이스를 생성 한다 (필수). 「DirectInput 디바이스의 생성」을 참조할것.
  2. 디바이스 능력을 취득한다 (옵션).
  3. 디바이스의 키, 버튼 및 축을 열거한다 (옵션). 「디바이스 오브젝트의 열거」를 참조할것.
  4. 협조 레벨을 설정한다 (추천).
  5. 디바이스 데이터 형식을 설정한다 (추천).
  6. 디바이스 프로퍼티를 설정한다 (버퍼링 데이터를 취득할 예정이라면, 적어도 버퍼 사이즈를 설정해야 한다).
  7. 데이터를 읽어낼 준비를 할 수 있으면(자), 디바이스를 취득한다 (필수). 「디바이스의 취득」을 참조할것.


DirectInput 디바이스의 생성

디바이스로부터 입력 데이터를 취득하려면 , 우선 그 디바이스를 나타내는 오브젝트를 생성 해야 한다.

IDirectInput8::CreateDevice 메소드를 사용해,IDirectInputDevice8 인터페이스에의 포인터를 취득한다. 그 후, 이 인터페이스의 메소드를 사용해, 디바이스의 조작과 데이터의 취득을 실시한다.

다음의 코드는, 키보드 디바이스를 생성 하는 예이다. lpdi 는 IDirectInput8 인터페이스에의 포인터이다.

LPDIRECTINPUTDEVICE8  lpdiKeyboard;
lpdi->CreateDevice(GUID_SysKeyboard, &lpdiKeyboard, NULL);

CreateDevice 의 최초의 파라미터는 인스턴스 GUID 이며, 인터페이스의 생성 대상 디바이스의 인스턴스를 식별한다. Microsoft® DirectInput® 에는, 사전 정의된 2 개의 GUID (GUID_SysMouse 및 GUID_SysKeyboard)가 있어, 각각 시스템 마우스와 시스템키 보드를 나타낸다. 이러한 식별자의 1 개를 CreateDevice 메소드에 건네줄 수가 있다. CreateDevice 메소드의 파라미터로서 글로벌 변수의 GUID_Joystick 를 사용해서는 안 된다. GUID_Joystick 는 제품 GUID 이며, 인스턴스 GUID 는 아니기 때문에이다.

주 : 컴퓨터에 2 개 이상의 마우스가 있는 경우는, 모든 마우스가 결합되어 시스템 디바이스를 형성한다. 키보드에 대해서도 같이이다.

DirectInput 는, 이 밖에도 주로 테스트에 사용하는 사전 정의된 4 개의 GUID 를 준비해 있다.

  • GUID_SysKeyboardEm
  • GUID_SysKeyboardEm2
  • GUID_SysMouseEm
  • GUID_SysMouseEm2.

이 GUID 의 1 개를 CreateDevice 에 건네주는 것으로, 열거 계층-를 개입시켜, 시스템키 보드나 시스템 마우스에 대한 레벨 1 또는 레벨 2 의 액세스권이 부여된다. 이러한 GUID 는, 항상 시스템 마우스나 시스템키 보드를 나타낸다. 이것들은 GUID_SysKeyboard 및 GUID_SysMouse 의 앨리어스(alias)이며, DIEDFL_INCLUDEALIASES 플래그가 건네받지 않으면,IDirectInput8::EnumDevices 또는 IDirectInput8::EnumDevicesBySemantics 에서는 열거되지 않는다.

시스템 마우스 또는 시스템키 보드 이외의 디바이스의 경우는,EnumDevices 또는 EnumDevicesBySemantics 로 돌려주어지는 디바이스의 인스턴스 GUID 를 사용한다. 1 개의 디바이스에 대한 인스턴스 GUID 는 항상 동일하다. 열거한 리스트로부터 유저에게 1 개의 디바이스를 선택시켜, 그 GUID 를 구성 파일에 보존해 두면(자), 후의 세션으로 그 GUID 를 다시 사용할 수가 있다.


디바이스 능력

디바이스로부터의 입력을 요구하기 전에, 유저가 그 능력을 어느 정도 알아 둘 필요가 있다. 죠이스틱에 시점 하트가 붙어 있을까. 마우스는 유저의 머신에 현재어태치 되고 있을까.

그러한 의문점은,IDirectInputDevice8::GetCapabilities 메소드를 호출하는 것으로 해결할 수가 있다. 이 메소드는, 능력에 관한 데이터를 DIDEVCAPS 구조체에 돌려준다. Microsoft® DirectX® 외의 유사한 구조체의 경우와 같게, 메소드에 이 구조체를 건네주기 전에,dwSize 멤버를 초기화해 두지 않으면 안 된다.

주 : 처리 속도나 메모리 사용을 최적화하기 위해서, 보다 작은 DIDEVCAPS_DX3 구조체를 이용할 수가 있다. 구조체의 상세한 것에 대하여는, Microsoft Software Development Kit (SDK)의 Dinput.h 를 참조할것.

이하의 코드는, 마우스가 어태치 되고 있는지 어떤지, 및 마우스가 제 3 축 (보통은, 휠)을 가지고 있을지 어떨지를 체크하는 예이다. lpdiMouse 는 유효한 Microsoft DirectInput® 디바이스로 한다.

DIDEVCAPS  DIMouseCaps;
HRESULT    hr;
BOOLEAN    WheelAvailable;

DIMouseCaps.dwSize = sizeof(DIDEVCAPS);
hr = lpdiMouse->GetCapabilities(&DIMouseCaps);
WheelAvailable = ((DIMouseCaps.dwFlags & DIDC_ATTACHED)
        && (DIMouseCaps.dwAxes > 2));

어느 버튼 또는 축이 존재할지 어떨지를 체크하는 이제(벌써) 1 개의 방법은, 그 오브젝트에 대해서 IDirectInputDevice8::GetObjectInfo 를 호출하는 것이다. 그 호출에 대해 DIERR_OBJECTNOTFOUND 가 되돌아 왔을 경우, 오브젝트는 존재하지 않는다. 이하의 코드에서는, 제 3 축은 아닌으로 해도 z 축이 존재할지 어떨지를 판단한다.

DIDEVICEOBJECTINSTANCE  didoi;

didoi.dwSize = sizeof(DIDEVICEOBJECTINSTANCE);
hr = lpdiMouse->GetObjectInfo(&didoi, DIMOFS_Z, DIPH_BYOFFSET);
WheelAvailable = SUCCEEDED(hr);


협조 레벨

디바이스의 협조 레벨은, 어플리케이션간 및 Microsoft® Windows® 시스템으로 디바이스를 공유하는 방법을 정의한다. 이하의 예의 같게, 협조 레벨을 설정하려면 IDirectInputDevice8::SetCooperativeLevel 메소드를 사용한다.

/* hwnd 는, 최상정도 윈도우의 핸들이다.  */
lpdiDevice->SetCooperativeLevel(hwnd,
        DISCL_NONEXCLUSIVE | DISCL_FOREGROUND)

파라미터는, 디바이스에 관련하는 최상정도 윈도우 (일반적으로는, 어플리케이션 윈도우)의 핸들과 1 개 또는 복수의 플래그이다.

DirectInput 에는 디폴트 설정이 준비되어 있지만, 협조 레벨은, 명시적으로 설정해야 한다. 이것은, DirectInput 에 윈도우의 핸들을 주기 위한 유일한 방법이니까이다. 이 핸들이 없으면 DirectInput 는, 죠이스틱의 재calibration 등, 윈도우 메세지가 필요한 상황으로 반응할 수가 없게 된다.

유효한 플래그의 편성을 이하의 겉(표)에 나타낸다.

플래그 | 메모
DISCL_NONEXCLUSIVE DISCL_BACKGROUND | 디폴트 설정
DISCL_NONEXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_BACKGROUND | 키보드 또는 마우스에는 무효

키보드의 경우는, DISCL_NOWINKEY 와 DISCL_NONEXCLUSIVE 를 동시에 사용할 수도 있다. 이 플래그로 Windows 키를 무효로 하는 것으로, 유저는 부주의로 어플리케이션을 종료하는 것이 없어진다. 배타 모드에서는, Windows 키는 항상 무효이다.

주 : Windows 키는, 어플리케이션의 협조 레벨로 배타 협조 레벨을 통해 수동적으로, 또는 DISCL_NOWINKEY 플래그를 사용해 능동적으로 무효로 하는 경우에서도, 디폴트의 액션 매핑 UI 가 표시되고 있는 동안은 액티브하게 된다.

협조 레벨에는 2 개의 원가요소가 있다. 디바이스를 foreground 또는 백그라운드에서 사용하는지, 및 배타 또는 비배타에 사용할까이다.

foreground와 백그라운드

foreground 협조 레벨은, 어플리케이션이 foreground에 있는 경우, 즉, 입력초점을 가지는 경우에 한정해, 입력 디바이스가 사용 가능하게 되는 것을 의미한다. 어플리케이션이 백그라운드로 옮겨지면(자), 입력 디바이스는 자동적으로 해방될까 사용 불가가 된다.

백그라운드 협조 레벨이란, 실제로는 「foreground와 백그라운드」이다. 백그라운드 협조 레벨의 디바이스는, 어플리케이션으로부터 언제라도 취득해 사용할 수 있다.

보통은, foreground 액세스권만으로 충분할 것이다. 그렇다고 하는 것도, 대부분의 어플리케이션에 있어, 다른 프로그램이 foreground에 있는 경우에 발생하는 입력에 응답하도록(듯이)는 설계되어 있지 않기 때문에이다.

어플리케이션의 개발중에, 조건부 컴파일을 사용해, 디버그용으로 백그라운드 협조 레벨을 설정하는 것은 유용하다. 이것에 의해, 어플리케이션은, 디버그 환경에의 변환으로 백그라운드로 이동할 때마다, 디바이스에의 액세스를 잃는 것이 없어진다.

배타와 비배타

많은 경우, 어느 어플리케이션이 디바이스를 배타 레벨로 사용하고 있다고 해도, 다른 어플리케이션이 같은 디바이스로부터 데이터를 취득할 수 없다고 하는 것으로는 되지 않는다. 「배타 레벨로 사용」이란, 다른 어플리케이션이 같은 디바이스를 배타에는 취득할 수 없다고 하는 것을 의미한다.

예를 들어 있는 뮤직 플레이어 어플리케이션의 경우, 어플리케이션은 백그라운드에 있어도, 소형의 리모트 콘트롤 디바이스로부터 입력을 받아들인다. 여기서, 같은 리모트 콘트롤 디바이스로부터의 신호에 응답해, 영화를 재생하는 어플리케이션을 실행 하면 하자. 유저가 [Play] 를 누르면(자) 무엇이 일어날까. 양쪽 모두의 프로그램이 재생을 시작 하게 된다. 이러한 결과를 유저가 바라고 있다고는 생각되지 않는다. 그렇게 되지 않게 하려면 , 각 어플리케이션에 DISCL_EXCLUSIVE 플래그를 설정해, 한 번에 어느 쪽인가의 프로그램 밖에 실행할 수 없게 할 필요가 있다.

force feedback 이펙트를 이용하려면 , 어플리케이션은 디바이스에의 배타 액세스를 할 수 없으면 안 된다.

Windows 자체에는, 마우스에의 배타 액세스가 필요하다. 왜냐하면, 액티브하지 않은 윈도우상에서의 클릭등의 마우스 이벤트를 사용해, 어플리케이션에 디바이스를 강제 해방시키는 것이 가능하고, 그것이, 입력 버퍼로부터의 데이터의 상실 등, 잠재적으로 유해한 결과를 낳을 가능성이 있기 때문이다. 이 때문에, 어느 어플리케이션이 IDirectInput8::CreateDevice 에 GUID_SysMouse를 건네주어 생성 된 시스템 마우스에 대한 배타 액세스권을 가지고 있으면(자), Windows 에는 일절의 액세스가 용서되지 않고, 마우스 메세지는 생성되지 않는다. 새로운 부작용으로서 커서가 사라지는 일도 있다.

어느 어플리케이션이 키보드에 대한 배타 액세스권을 가지고 있는 경우, DirectInput 는 일절의 키보드 메세지를 억제한다. 다만, Ctrl+Alt+Del 키 및 Windows 95 나 Windows 98 에서의 Alt+Tab 키는 사용할 수 있다. Windows 2000 에서는, 배타 모드의 DirectInput 어플리케이션에 이어 기동되는 어플리케이션은, 키보드 데이터를 취득할 수 없다.


디바이스 오브젝트의 열거

디바이스상에서 어느 버튼 또는 축이 사용 가능한가를, 어플리케이션이 확인해야 하는 경우가 있다. 이 확인을 실시하려면 , 디바이스를 열거하는 경우와 거의 같은 방법으로 디바이스 오브젝트를 열거한다.

주 : 디바이스 드라이버에 의한 제약을 위해, 키보드의 키 및 인디케이터(indicator) 라이트의 열거는 신뢰할 수 없다. 오브젝트가 존재할 것 같은 거짓의 보고를 하는 경우가 있다. 사용 가능한 키에 관한 기본적 정보는, 디바이스의 서브 타입으로부터 취득할 수 있지만, 메뉴 키등의 추가 오브젝트가 사용 가능한가 어떤가를 판정하려면 , 유저에게 입력을 요구하는 이외, 방법은 없다.

IDirectInputDevice8::EnumObjects 의 기능은,IDirectInputDevice8::GetCapabilities 와 중복되는 곳(중)이 있다. 어느 쪽의 메소드도, 사용 가능한 버튼 또는 축이 몇개 있는지를 확인하는데 사용할 수 있다. 그러나,EnumObjects 는, 특정의 오브젝트의 존재를 체크하는 것보다도, 오히려, 사용 가능한 오브젝트를 모두 카탈로그화하는 것을 목적으로 한 메소드이다.

EnumObjects 메소드에는,IDirectInput8::EnumDevices 등과 같이 콜백 함수가 있어, 각 오브젝트에 대해서 다른 처리를 시킬 수가 있다. 예를 들어, 오브젝트를 리스트에 추가하거나 유저 인터페이스상에 대응하는 항목을 생성 하거나 하는 것이다.

이하의 코드는, 각 오브젝트의 이름을 추출해, 캐릭터 라인 리스트 또는 배열에 추가할 수 있도록(듯이) 하는 콜백의 예이다. 이 표준 콜백은, 문서에서는 플레이스홀더명 DIEnumDeviceObjectsCallback 로 나타내지고 있지만, 자유롭게 이름을 붙일 수가 있다. 이 함수는, 열거되는 각각 오브젝트에 대해서, 한 번 두개 불려 가는 것에 주의 해야 한다.

char  szName[MAX_PATH];

BOOL CALLBACK DIEnumDeviceObjectsCallback(
                      LPCDIDEVICEOBJECTINSTANCE lpddoi,
                      LPVOID pvRef)
{
  lstrcpy(szName, lpddoi->tszName);
  // szName 를 리스트 혹은 배열에 추가한다.
  .
  .
  .
  return DIENUM_CONTINUE;
}

1 번째의 파라미터는, 오브젝트의 정보를 저장 하는 구조체에의 포인터이다. 이 구조체는, Microsoft® DirectInput® 에 의해 자동 생성 된다.

2 번째의 파라미터는,EnumObjects 의 2 번째의 파라미터와 동등한 데이터에 대한 어플리케이션 정의 포인터이다. 이 예에서는, 당파라미터는 사용되어 있지 않다.

이 경우의 반환값은, 열거하는 오브젝트가 존재하는 한 열거가 계속되는 것을 나타낸다.

이하는,EnumObjects 메소드를 호출해, 콜백 함수를 동작시키는 예이다.

lpdiMouse->EnumObjects(DIEnumDeviceObjectsCallback,
                       NULL, DIDFT_ALL);

1 번째의 파라미터는, 콜백 함수의 주소이다. 2 번째의 파라미터는, 콜백 함수 중(안)에서, 사용 또는 변경하고 싶은 데이터에의 포인터로서 사용할 수 있다. 이 예에서는, 이 파라미터를 사용 자제이므로, NULL 를 건네주고 있다. 3 번째의 파라미터는, 열거안에 포함하는 오브젝트의 타입 (복수가능)을 나타내는 플래그이다. 이 예에서는, 모든 오브젝트를 열거하게 된다. 열거의 범위를 한정하려면 ,IDirectInputDevice8::EnumObjects 에 리스트 되는 것 외의 DIDFT_* 플래그를 1 개 이상 사용하면 좋다

주 : DIDFT_* 플래그의 일부는, 다른 플래그를 조합한 것이다. 예를 들어, DIDFT_AXIS 는, DIDFT_ABSAXIS | DIDFT_RELAXIS 와 동등하다.


디바이스 데이터 형식

액션 매핑을 사용하고 있지 않는 경우, 디바이스의 데이터 형식의 설정은, 디바이스 취득 및 디바이스 사용을 시작하기 전에 실시하는 기본적인 순서이다. 디바이스로부터 직접 데이터 (상태 데이터)를 취득하는 것을 목적으로 하지 않은 경우에서도, 데이터 형식을 설정해야 한다. Microsoft® DirectInput® 에서는 많은 메소드로 데이터 형식을 사용해, 특정의 디바이스 오브젝트를 식별한다.

디바이스 오브젝트가 사용하는 디바이스와 데이터 배열의 방법은,IDirectInputDevice8::SetDataFormat 메소드가 DirectInput 에 대해서 지시한다.

DIDATAFORMAT 구조체 및 DIOBJECTDATAFORMAT 구조체의 레퍼런스중의 예에는, 비표준 디바이스에 대해서 커스텀 데이터 형식을 설정할 방법이 나타나고 있다. 이 설정 순서는 다행히도, 죠이스틱, 키보드, 및 마우스에는 불필요하다. DirectInput 는, 5 개의 글로벌 변수, 즉 c_dfDIJoystick,c_dfDIJoystick2,c_dfDIKeyboard,c_dfDIMouse, 및 c_dfDIMouse2 를 제공하고 있다. 이러한 변수를 SetDataFormat 에 건네주어 죠이스틱, 키보드, 및 마우스에 대한 표준 데이터 형식을 생성 할 수가 있다.

이하의 샘플 코드로,lpdiMouse 는, DirectInputDevice 오브젝트에 대한 초기화된 포인터이다.

lpdiMouse->SetDataFormat(&c_dfDIMouse);

주 : 사전 정의된 DIDATAFORMAT 글로벌 변수는 const 변수이므로, 이 안의 dwFlags 멤버를 (예를 들어, 축의 프로퍼티를 변경하기 위해서) 변경할 수 없다. 프로퍼티를 변경하려면 , 데이터 형식을 설정한 다음에, 디바이스를 취득하기 전에,IDirectInputDevice8::SetProperty 를 사용한다.


디바이스 프로퍼티

Microsoft® DirectInput® 디바이스의 프로퍼티에는, 데이터 버퍼의 사이즈, 축이 돌려주는 값의 범위와 세분성, 축데이터가 상대인가 절대인가, 및 죠이스틱의 물리적 위치와 보고 데이터간의 관계에 영향을 주는 죠이스틱축의데드 존과포화가 있다. 특수 디바이스는, 이외의 프로퍼티를 가지는 일도 있다. DirectInput 에 의해 정의된 프로퍼티의 리스트에 대해서는, 「IDirectInputDevice8::GetProperty 」를 참조할것.

1 개의 예외 (force feedback 디바이스의 게인 프로퍼티)를 제외해, 프로퍼티는, 디바이스가 해방된 상태에 있는 경우에 한정해 변경할 수가 있다.

IDirectInputDevice8::SetProperty 메소드 또는 IDirectInputDevice8::GetProperty 메소드를 호출하기 전에,DIPROPHEADER 구조체와 데이터의 1 개 이상의 요소로 구성되는 프로퍼티 구조체를 설정할 필요가 있다. 입력 디바이스에는 많은 프로퍼티가 있으므로,SetProperty 는 이러한 프로퍼티를 정의하는 모든 종류의 구조체에 대해서 기능할 수 없으면 안 된다. DIPROPHEADER 구조체의 목적은, 프로퍼티 구조체의 사이즈와 데이터의 해석 방법을 정의하는 것이다.

DirectInput 는, 이하의 사전 정의된 프로퍼티 구조체를 포함한다.

  • DIPROPDWORD 는, 버퍼 사이즈 등 단일의 값을 요구하는 프로퍼티에 대해서,DIPROPHEADER 구조체와 DWORD 데이터 멤버를 포함한 구조체를 정의한다.
  • DIPROPRANGE 는 프로퍼티 범위에 대해서 , 2 개의 값 (최대치와 최소 값)을 요구한다. DIPROPHEADER 구조체와 2 개의 LONG 데이터 멤버로 구성된다.
  • DIPROPGUIDANDPATH 는, DirectInput 로 지원되어 있지 않은 HID (Human Interface Device)에 대해서 어플리케이션이 조작을 실행할 수 있는, 특수한 프로퍼티 구조체이다. 이 구조체는,DIPROPHEADER 구조체와 GUID, 및 패스를 나타내는 Unicode 캐릭터 라인으로 구성된다.
  • DIPROPSTRING 는, Unicode 캐릭터 라인 프로퍼티이다. 이 구조체는,DIPROPHEADER 구조체와 Unicode 캐릭터 라인으로 구성된다.

SetProperty 의 경우, 프로퍼티 구조체의 데이터 멤버는, 프로그래머가 설정하는 값이다. GetProperty 의 경우는, 현재의 값이 데이터 멤버에 돌려주어진다.

GetProperty 또는 SetProperty 를 호출하기 전에,DIPROPHEADER 구조체를 이하의 값으로 초기화해 두지 않으면 안 된다.

  • 프로퍼티 구조체의 사이즈.
  • DIPROPHEADER 구조체 자체의 사이즈.
  • 오브젝트 식별자.
  • 오브젝트 식별자의 해석 방법을 지시하는 값.

디바이스 전체로부터 프로퍼티를 취득하거나 설정하거나 하는 경우, 오브젝트 식별자 dwObj 는, 제로이며,dwHow 멤버는, DIPH_DEVICE 이다. 1 개의 디바이스 오브젝트 (예를 들어, 특정의 축)에 대해서 프로퍼티를 설정 또는 취득하고 싶은 경우는,dwObj 와 dwHow 의 편성값에 의해, 그 오브젝트가 식별된다. 상세한 것에 대하여는, 「DIPROPHEADER 구조체」를 참조할것.

프로퍼티 구조체의 설정 후, 취득 또는 변경하고 싶은 프로퍼티의 식별자와 함께, 구조체의 헤더의 주소를,GetProperty 또는 SetProperty 에 건네준다.

SetProperty 및 GetProperty 에게 건네지는 프로퍼티를 식별하기 위해서, 이하의 값이 사용된다. 상세한 것에 대하여는, 「IDirectInputDevice8::GetProperty 」를 참조할것.

  • DIPROP_BUFFERSIZE. 「버퍼링 데이터와 직접 데이터」도 참조할것. 버퍼 사이즈의 설정에는,IDirectInputDevice8::SetActionMap 메소드도 사용할 수 있다.
  • DIPROP_AXISMODE. 「상대 좌표와 절대 좌표」도 참조할것.
  • DIPROP_CALIBRATIONMODE
  • DIPROP_GRANULARITY
  • DIPROP_FFGAIN
  • DIPROP_FFLOAD
  • DIPROP_AUTOCENTER
  • DIPROP_RANGE
  • DIPROP_DEADZONE
  • DIPROP_SATURATION

마지막 3 개의 프로퍼티에 대한 자세한 것은, 「죠이스틱축데이터의 해석」도 참조할것.

이하의 샘플 코드에서는, 10 개의 데이터 항목을 보관 유지하도록(듯이) 디바이스의 버퍼 사이즈를 설정한다.

DIPROPDWORD  dipdw;
HRESULT      hr;
dipdw.diph.dwSize = sizeof(DIPROPDWORD);
dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);
dipdw.diph.dwObj = 0;
dipdw.diph.dwHow = DIPH_DEVICE;
dipdw.dwData = 10;
hr = lpdiDevice->SetProperty(DIPROP_BUFFERSIZE, &dipdw.diph);


디바이스의 취득

Microsoft® DirectInput® 디바이스의 취득이란, 어플리케이션에 디바이스에의 액세스를 시키는 것이다. 디바이스가 취득되고 있는 한, DirectInput 는, 어플리케이션이 디바이스의 데이터를 사용할 수 있도록(듯이) 한다. 디바이스가 취득되어 있지 않은 경우, 디바이스의 특성에 대한 조작은 할 수 있지만, 데이터는 일절 취득할 수 없다.

취득은 영속 하는 것은 아니다. 어플리케이션은, 디바이스를 몇회에서도 취득해, 해방하는 일이 있다.

협조 레벨에 따라서는, 어플리케이션이 백그라운드로 이행하면(자) 반드시 자동적으로 디바이스가 해방되는 일이 있다. 마우스의 경우, 유저가 메뉴를 클릭 하면 자동적으로 해방된다. 클릭한 시점에서 Microsoft Windows® 가 디바이스의 제어를 계승하기 때문이다.

디바이스 프로퍼티의 변경에 앞서, 그 디바이스를 해방할 필요가 있다. 유일한 예외로서 force feedback 디바이스는, 취득 상태에 있어도 게인을 변경할 수 있다.

취득의 구조가 필요한 이유는, 다음의 2 개이다.

제 1 에, DirectInput 는, 디바이스로부터의 데이터의 흐름이 시스템에 의해 중단되었을 때에는, 어플리케이션에 통지할 수 없으면 안 된다. 예를 들어, 유저가 Alt+Tab 를 사용해 다른 어플리케이션으로 전환해 변환 후의 어플리케이션으로 입력 디바이스를 사용했을 경우에, 원의 어플리케이션은, 입력 디바이스가 이미 자신에게 속하지 않고, 버퍼 상태가 변화한 가능성이 있는 것을 알 필요가 있다. DISCL_FOREGROUND 협조 레벨에서의 어플리케이션을 관찰해 보자. 유저가 Shift 키를 누르면서 다른 어플리케이션으로 전환한다. 그 후, 유저는 Shift 키를 떼어 놓아, 원의 어플리케이션에 돌아온다. 원의 어플리케이션으로부터 보면, Shift 키는 여전히 밀리고 있는 상태이다. 취득의 구조에서는, 원의 어플리케이션에 입력이 종료한 것을 통지해, 이 상태로부터 회복시킬 수가 있다.

제 2 에, 어플리케이션이 디바이스의 프로퍼티를 변경할 수 있으므로, 보호가 없으면 유저가 데이터를 취득하려고 할 때마다, DirectInput 가 프로퍼티를 체크해야 하게 된다. 이것은, 꽤 비효율적이겠지. 한층 더 나쁜 것에는, 버퍼 사이즈를 변경하고 있는 한중간에, 데이터 버퍼에 액세스 하는 하드웨어 인터럽트 등, 사고가 발생할 가능성이 있다. 그러한 이유로써, DirectInput 는, 프로퍼티를 변경하기 전에, 어플리케이션에 대해서 디바이스를 해방하도록(듯이) 요구한다. 디바이스를 재취득 하면, DirectInput 는 프로퍼티를 확인해, 디바이스로부터 어플리케이션에의 최적인 데이터 전송의 방법을 결정한다. 이 처리는 한 번 밖에 행해지지 않기 때문에, 데이터 취득의 각 메소드를 매우 고속으로 할 수가 있다.

디바이스를 상실하는 가장 일반적인 원인은, 어플리케이션이 백그라운드로 이행하는 것이다. 따라서, 어플리케이션이 액티브하게 되었을 때에는 항상, 디바이스를 재취득하는 것이 필요하게 된다. 그러나, 기동시의 WM_ACTIVATE 핸들러에 의존하려면 주의가 필요하다. 최초의 WM_ACTIVATE 메세지가 도착하는 것은, 아마 윈도우의 초기화중에서, DirectInput 의 셋업전이다. 기동시에 디바이스를 확실히 취득하려면 , 디바이스가 초기화되자 마자 IDirectInputDevice8::Acquire 를 호출하도록(듯이) 한다.

특히 표준의 키보드나 마우스 이외의 디바이스의 경우, 프로그램 윈도우가 액티브하게 되었을 때에 디바이스를 취득해도, 디바이스가 해방되는 모든 케이스에 대응할 수 있다고는 할 수 없다. 어플리케이션이 디바이스를 갑자기 해방하는 경우도 있으므로, 디바이스로부터 데이터를 취득하려고 하기 전에, 취득 상태를 확인하는 구조가 필요하다. Scrawl 샘플 어플리케이션에서는, Scrawl_OnMouseInput 함수로 이 확인을 실시하고 있다. 이 함수에서는,DIERR_INPUTLOST 에러가, 마우스를 재취득하는 메세지의 방아쇠가 된다(상세한 것에 대하여는, 「튜토리얼 2 : 마우스의 사용법」을 참조할것).

취득 끝난 디바이스를 재취득하려고 해도, 해는 전혀 없다. Acquire 에 대한 장황한 호출은 무시되어 디바이스는 상시 Unacquire 를 1 회 호출하는 것으로 해방할 수가 있다.

Windows 는, 어플리케이션이 마우스를 배타 모드로 사용하고 있을 때는, 마우스에 액세스 하지 않는다. Windows 에 마우스를 취득 찌를 수 있던 차면, 마우스를 해방해야 한다. Scrawl 샘플에서는, 오른쪽 버튼의 클릭에 반응하기 위해서, 마우스를 해방해, Windows 커서를 같은 점에 표시해, 쇼트 컷 메뉴를 표시해, 메뉴 선택을 할 때까지 Windows 가 입력을 처리하도록(듯이) 하고 있다.


DirectInput 디바이스 데이터

여기에서는, Microsoft® DirectInput® 디바이스 데이터의 취득에 관한 기본적인 생각을 몇개인가 설명한다.

  • 버퍼링 데이터와 직접 데이터
  • 타임 스탬프와 순서 번호
  • 폴링과 이벤트 통지
  • 상대 좌표와 절대 좌표

출력 데이터, 마우스, 키보드 및 죠이스틱 입력 데이터의 특정 사항에 대해서는, 이하의 주제로 상술한다.

  • 마우스 데이터
  • 키보드 데이터
  • 죠이스틱 데이터
  • 데이터 출력

DirectInput 에서는, 디바이스로부터 취득한 데이터를 식별하는 2 개의 구조를 제공한다. 종래의 구조를 사용해, 어플리케이션은, 마우스의 x 축 또는 키보드의 F1 키등의 특정의 디바이스 오브젝트로부터 입력되는 데이터를 식별한다. Microsoft DirectX® 8.0 이후의 새로운 시스템에서는, DirectInput 는 어플리케이션이 정의한 값 (예를 들어, 이동이나 슈팅 등, 특정의 게임 액션의 식별자)을 가장 적절한 사용 가능 디바이스 오브젝트에 관련짓는다. 데이터가 취득되면(자), 어플리케이션은, 데이터가 입력된 실제의 디바이스 또는 디바이스 오브젝트와의 관련을 가지지 않는다. 그 데이터의 의의 에 대해서만 동작한다.

이 섹션으로 설명하는 정보의 대부분은, 양쪽 모두의 메카니즘에 적용된다. 디바이스 데이터의 새로운 식별법의 상세한 것에 대하여는, 「액션 매핑」을 참조할것.


버퍼링 데이터와 직접 데이터

Microsoft® DirectInput® 는, 버퍼링 데이터와 직접 데이터의 2 종류의 데이터를 공급한다. 버퍼링 데이터는, 어플리케이션이 취득할 때까지 저장 되고 있는 이벤트의 레코드이다. 직접 데이터는, 디바이스의 현재 상태의 snapshot이다.

직접 데이터는, 디바이스의 현재 상태인 만큼 관심이 있는 어플리케이션으로 사용하는 것을 생각된다. 예를 들어, 죠이스틱의 현재 위치와 1 개 이상의 버튼 상태에 반응하는 플라이트 컴배트 시뮬레이션 등이다. 버퍼링 데이터는, 상태보다 이벤트를 중요시하는 경우에 선택 하면이야 있고. 예를 들어, 마우스의 움직임이나 버튼의 클릭에 반응하는 어플리케이션 등이다. 양쪽 모두의 타입의 데이터를 사용할 수도 있다. 예를 들어, 죠이스틱축에서는 직접 데이터를 취득해, 버튼에서는 버퍼링 데이터를 취득하는 경우 등이다.

주 : 액션 매핑을 사용하는 경우, 밧파링데이타파켓트에는 입력에 관한 어플리케이션 정의 데이터가 포함되기 (위해)때문에, 버퍼링 데이터를 취득할 필요가 있다. 버퍼링 데이터 패킷에서는 상태는 아니고 이벤트가 보고되기 (위해)때문에, 이 데이터를 취득하려면 절대축의 위치를 추적해야 한다.

어플리케이션은,IDirectInputDevice8::GetDeviceState 메소드를 호출해 직접 데이터를 취득한다. 이름이 나타내는 대로, 이 메소드는 디바이스의 현재 상태를 돌려준다. 예를 들어, 각 버튼이 업 상태나 다운 상태인가, 등이다. 이 메소드는, 현재 상태와 이전 상태를 비교해 얻을 수 있는 암묵의 정보를 제외해, 마지막 호출해 이후에 디바이스에 일어난 이벤트에 관한 데이터는, 전혀 제공하지 않는다. 예를 들어, 전회의 GetDeviceState 에의 호출해 이후에 유저가 버튼을 눌러 떼어 놓았을 경우, 이번 GetDeviceState 에의 호출에서는 그러한 입력 정보는 어플리케이션에는 전해지지 않는다. 한편, 버튼을 누른 채로 하고 있으면(자),GetDeviceState 는, 유저가 버튼을 떼어 놓을 때까지 「보턴다운」을 계속 보고한다.

이 디바이스 상태의 보고는, WM_LBUTTONDOWN 와 같은 한 번 한계의 메세지에 의한 Microsoft Windows® 의 이벤트 보고와는 다르다. 오히려, Microsoft Win32® 의 GetKeyboardState 함수의 보고에 유사하고 있다. GetDeviceState 를 사용해 디바이스를 폴링 하는 경우에는, 버튼 클릭, 더블 클릭, 또는 단일의 키스트로크(keystroke)의 구별을 프로그램으로 판단하지 않으면 안되어, 또, 어플리케이션이 보턴다운 상태 또는 키 다운 상태에 대해, 부적절한 타이밍에 계속 할리 가 없게 적절히 처리해야 한다.

버퍼링 데이터의 경우, 이벤트는, 프로그램이 처리를 시작 할 수 있는 상태가 될 때까지 저장 되고 있다. 버튼이나 키가 밀리거나 축이 이동 되거나 할 때마다, 그 이벤트에 대한 정보가 버퍼중의 DIDEVICEOBJECTDATA 구조체에 놓여진다. 버퍼가 오버플로우 하면, 새로운 데이터는 없어진다. 어플리케이션이 버퍼를 읽어내려면 ,IDirectInputDevice8::GetDeviceData 를 호출한다. 한 번에 임의의 수의 항목을 읽어낼 수가 있다.

항목을 읽어내면(자), 보통은, 버퍼로부터 그 항목이 소거되지만, 소거 없음 피킹도 선택할 수 있다.

버퍼링 데이터를 취득하려면 , 우선 IDirectInputDevice8::SetProperty 또는 IDirectInputDevice8::SetActionMap 메소드로 버퍼 사이즈를 설정할 필요가 있다 ( 「디바이스 프로퍼티」를 참조할것). 버퍼 사이즈의 설정은, 디바이스를 최초로 취득하기 전에 실시한다. 효율상의 이유로부터, 디폴트의 버퍼 사이즈는 제로이다. 이 값을 변경하지 않는 한, 버퍼링 데이터를 취득할 수 없다. 버퍼 사이즈는 바이트 단위는 아니고, 디바이스의 타입에 대응한 데이터의 항목 단위로 카운트 된다.

GetDeviceData 메소드를 호출한 후는,pdwInOut 파라미터값을 체크할 필요가 있다. 버퍼로부터 취득되는 항목수는, 이 변수에 돌려주어진다.

주 : 아날로그 죠이스틱 등, 세치기를 생성하지 않는 디바이스의 경우,IDirectInputDevice8::Poll 메소드가 불려 갈 때까지, DirectInput 는 어떠한 데이터도 취득하지 않는다. 상세한 것에 대하여는, 「폴링과 이벤트 통지」를 참조할것.

버퍼링 데이터를 취득하는 예에 대해서는, 「IDirectInputDevice8::GetDeviceData 」를 참조할것.

참조

  • 타임 스탬프와 순서 번호
  • 마우스 데이터
  • 키보드 데이터
  • 죠이스틱 데이터


타임 스탬프와 순서 번호

버퍼링 되고 있는 Microsoft® DirectInput® 입력 데이터의 경우 ( 「버퍼링 데이터와 직접 데이터」를 참조), 각 DIDEVICEOBJECTDATA 구조체에는, 이벤트의 타입과 거기에 관련하는 디바이스 오브젝트 뿐만이 아니라, 타임 스탬프와 순서 번호도 저장 된다.

dwTimeStamp 멤버는, 이벤트가 발생했을 때의 시스템 시간을 밀리 세컨드 단위로 저장 한다. 이것은, Microsoft Win32® GetTickCount 함수에 의해 돌려주어지는 값과 같은가, 보다 정밀도가 높은 값이다.

dwSequence 멤버는, DirectInput 가 할당한 순서 번호를 저장 한다. DirectInput 시스템은, 단일의 순서 카운터를 보관 유지하고 있다. 이 카운터는, 임의의 디바이스로, 버퍼링 되는 이벤트가 발생할 때마다 수시 증가한다. (마우스의 기울기의 움직임 등, 동일 디바이스상에서 동시에 발생한 이벤트는, 1 회만 카운트가 증가한다). 이 번호를 사용해, 다른 디바이스로부터 발생하는 이벤트를 비교해, 어느 쪽이 앞인지를 확인할 수가 있다. DirectInput 순서 번호의 비교에 사용되는 DISEQUENCE_COMPARE 매크로는, 순환성을 고려하고 있다.

주 이벤트는, 항상, 발생시간 순서에 버퍼에 넣어지므로, 단일 디바이스로부터의 이벤트를 단지 순서 붙이고 할 뿐(만큼)이라면, 순서 번호를 체크할 필요는 없다.


폴링과 이벤트 통지

입력 데이터가 발생하고 있을지 어떨지를 확인하려면 , 폴링과 이벤트 통지라고 하는 2 개의 방법이 있다.

디바이스의 폴링이란, 디바이스 오브젝트의 현재 상태를 정기적으로 취득하는 것, 또는 이벤트 버퍼의 내용을 체크하는 것을 의미한다. 폴링이 사용되는 것은 보통, 결코 아이돌이 되는 것이 없고, 항상 게임의 세계를 갱신, 렌더링 하는 리얼타임 게임이다.

폴링

C++ 어플리케이션에서의 폴링은 보통, 메시지 루프내에서 행해진다.

죠이스틱이나 다른 게임 디바이스, 또는 이러한 디바이스 위에의 오브젝트중 몇개인가는,IDirectInputDevice8::Poll 메소드를 호출할 때까지, 하드웨어 인터럽트를 생성하지 않고, 어떠한 데이터도 돌려주지 않고, 어떠한 이벤트도 송신하지 않는다 (이러한 백그라운드에서의 폴링을, 여기서 설명하는 어플리케이션 폴링과 혼동 하지 않는 것. Poll 메소드는, 데이터를 일절 취득하지 않지만, 데이터를 사용 가능하게 하는 일이 있다).

데이터를 취득하려고 할 때마다 Poll 메소드를 호출할 필요가 있을지 어떨지를 조사하려면 , 우선 디바이스의 데이터 형식을 설정해,IDirectInputDevice8::GetCapabilities 메소드를 호출해,DIDEVCAPS 구조체의 DIDC_POLLEDDATAFORMAT 플래그를 체크한다.

DIDC_POLLEDDATAFORMAT 플래그와 DIDC_POLLEDDEVICE 플래그를 혼동 하지 않는 것. 후자는, 데이터 형식에 관계없이, 디바이스 위에의 오브젝트중 한쪽이 폴링을 필요로 하고 있을 때 설정된다. 다음에,IDirectInputDevice8::GetObjectInfo 메소드를 호출해,DIDEVICEOBJECTINSTANCE 구조체에 있는 DIDOI_POLLED 플래그를 체크 하면, 폴링을 필요로 하고 있는 것이 특정의 오브젝트일지 어떨지를 분별할 수가 있다.

DIDC_POLLEDDEVICE 플래그는 디바이스의 최악 상태를 나타내는 것에서 만나며, 디바이스의 실제 상태를 나타내는 것은 아니다. 예를 들어, 소프트웨어 해상도 조절 첨부의 HID (Human Interface Device) 마우스에서는, 해상도 정보를 읽어내기 위해서(때문에) 폴링을 요구하므로, DIDC_POLLEDDEVICE 플래그가 설정된다. 디바이스의 표준 버튼과 축데이터만을 취득하고 싶은 경우는, 이러한 조건의 아래에서 디바이스를 폴링 할 필요는 없다. 다만, 임의의 입력 디바이스에 대해서 IDirectInputDevice8::Poll 메소드를 읽어내도 해는 없다. 이 호출이 불필요한 때는, 어떤 이펙트도 가지지 않고 곧바로 종료한다.

이벤트 통지

이벤트 통지는,Scrawl 샘플과 같이, 아무것도 하지 않고 입력을 기다리는 것 같은 어플리케이션에 적절하고 있다.

이벤트 통지를 사용하려면 , Microsoft® Win32® CreateEvent 함수로 thread 동기 오브젝트를 셋업 한 후, 이벤트의 핸들을 IDirectInputDevice8::SetEventNotification 메소드에 건네주는 것에 의해, 이 이벤트와 디바이스를 관계 붙인다. 이것으로, 디바이스 상태가 변화할 때마다, Microsoft DirectInput® 에 의해 이벤트가 통지된다. 어플리케이션은,WaitForSingleObject 등의 Win32 함수를 사용해, 이벤트의 통지를 받은 후, 입력 버퍼를 체크해 무슨 이벤트인지를 확인해, 응답할 수가 있다. 코드예에 대해서는, Scrawl 샘플과 「IDirectInputDevice8::SetEventNotification 」를 참조할것.


상대 좌표와 절대 좌표

축좌표는, 상대값으로서 돌려주어지는 경우도 있다. 즉, 어플리케이션이 전회 디바이스 상태를 취득하고 나서의 변화량, 버퍼링 입력의 경우는, 직전의 항목이 버퍼에 넣어지고 나서의 변화량이다.

절대축좌표란, 디바이스의 취득 이래, 시스템이 돌려준 모든 상대 좌표의 연속 합계이다. 즉, 어느 고정점에 대한 축의 위치를 나타낸다.

디폴트에서는, 마우스의 축은 상대 좌표이며, 죠이스틱축은 절대 좌표로 보고된다. 프로퍼티를 설정하는 것으로, 디바이스의 좌표 시스템을 변경할 수 있다. 상세한 것에 대하여는, 「디바이스 프로퍼티」를 참조할것.


마우스 데이터

데이터를 취득하도록(듯이) 마우스 디바이스를 설정하려면 , 파라미터로서 c_dfDIMouse 또는 c_dfDIMouse2 의 글로벌 변수를 지정해,IDirectInputDevice8::SetDataFormat 메소드를 호출한다. 5 개(살) 이상의 mouse button를 지원 하는 경우는,c_dfDIMouse2 를 사용한다.

풀 스크린 어플리케이션의 성능을 최대한 발휘하려면 , 협조 레벨에 DISCL_EXCLUSIVE | DISCL_FOREGROUND 를 설정한다. 배타를 설정 하면, Microsoft® Windows® 커서가 소실하는 것에 주의 해야 한다. DISCL_FOREGROUND 를 설정 하면, 디버그 윈도우로 전환했을 때에, 어플리케이션이 마우스에의 액세스권을 잃는다. DISCL_BACKGROUND 로 변경 하면, 어플리케이션의 퍼포먼스는 희생이 되지만, 어플리케이션의 디버그를 보다 용이하게 실시할 수가 있게 된다.

이하의 주제에서는, 마우스의 직접 데이터와 버퍼링 데이터의 취득과 해석에 대해 상세하게 설명한다.

  • 마우스의 직접 데이터
  • 마우스의 버퍼링 데이터
  • 마우스축데이터의 해석
  • 소실한 마우스 입력의 확인

참조

디바이스 데이터 형식,협조 레벨


마우스의 직접 데이터

마우스의 현재 상태를 취득하려면 ,DIMOUSESTATE 구조체나 DIMOUSESTATE2 구조체에의 포인터를 지정해,IDirectInputDevice8::GetDeviceState 를 호출한다. 어느 쪽의 구조체를 사용할까는, 데이터 형식에 의존한다. 이 구조체에 돌려주어지는 마우스 상태에는, 축데이터 및 각 버튼 상태가 포함된다.

구조체의 최초의 3 개의 멤버가 축좌표를 보관 유지한다 ( 「마우스축데이터의 해석」을 참조할것).

rgbButtons 멤버는, 바이트 배열이다. 4 개(살) 또는 8 개의 각 버튼에 1 요소가 대응한다. 종래형의 마우스의 경우, 일반적으로, 배열의 1 번째의 요소가 왼쪽 버튼, 2 번째가 오른쪽 버튼, 3 번째가 중앙 버튼이다. 상위 비트는, 버튼이 다운 상태의 경우에 세트 되어 버튼이 업 상태 또는 존재하지 않는 경우에 소거된다.

참조

버퍼링 데이터와 직접 데이터


마우스의 버퍼링 데이터

마우스로부터 버퍼링 데이터를 취득하려면 , 버퍼 사이즈를 설정해야 한다 ( 「디바이스 프로퍼티」를 참조할것). 버퍼의 디폴트 사이즈는 제로이므로, 이 순서는 불가결하다.

또,DIDEVICEOBJECTDATA 구조체의 배열도 선언할 필요가 있다. 이 배열은, 최고로 버퍼 사이즈와 동수의 요소를 가질 수가 있다. 1 번의 호출로 버퍼의 내용 전체를 취득할 필요는 없다. 배열내의 1 요소만을 보관 유지해, 버퍼가 비울 때까지 1 개(살)씩 이벤트를 취득할 수가 있다.

디바이스의 취득 후는,IDirectInputDevice8::GetDeviceData 메소드를 사용해 언제라도 버퍼내의 이벤트를 조사하거나 플래시 하거나 할 수가 있다 ( 「버퍼링 데이터와 직접 데이터」를 참조할것). 돌려주어진 DIDEVICEOBJECTDATA 배열중의 각 요소는, 마우스에 대한 단일 오브젝트 상태의 변화를 나타낸다. 예를 들어, 유저가 버튼 0 을 눌러 마우스를 비스듬하게 이동 하면,GetDeviceData 에게 건네진 배열 (3 개(살) 이상의 요소를 가지고 있는 경우,pdwInOut 는 3 이상)은, 3 개의 요소를 묻을 수 있다. 이러한 요소는 각각, 버튼 0 의 압하, x 축의 변화, 및 y 축의 변화를 나타낸다. pdwInOut 는 3 으로 설정된다.

배열중의 요소가 어느 오브젝트를 가리킬까는,DIDEVICEOBJECTDATA 구조체의 dwOfs 멤버를, 이하의 매크로에 의해 돌려주어지는 값과 비교하는 것으로 확인할 수 있다.

  • DIMOFS_BUTTON0 ~ DIMOFS_BUTTON7
  • DIMOFS_X
  • DIMOFS_Y
  • DIMOFS_Z

이러한 각 값은,DIMOUSESTATE 구조체 또는 DIMOUSESTATE2 구조 체내의 오브젝트에 대한 데이터의 오프셋(offset)로부터 이끌린다. 예를 들어,DIMOFS_BUTTON0 가 돌려주는 값은,DIMOUSESTATE 구조 체내의 rgbButtons[0] 오프셋(offset)와 동일하다. DIMOFS_BUTTON4 로부터 DIMOFS_BUTTON7 까지는,DIMOUSESTATE2 에 대해서 만일 수 있는 지원 되고 있다. 매크로를 사용해 단순한 비교를 실시해, 어느 디바이스 오브젝트가 버퍼의 항목에 관련하고 있을까를 결정할 수가 있다. 예를 들어, 이하대로이다.

DIDEVICEOBJECTDATA  *lpdidod;
int                 n;
.
.
.
/* MouseBuffer 는, DIDEVICEOBJECTDATA 구조체의 배열이며,
GetDeviceData 에의 호출에 의해 설정된다.
n 는, 배열중에서 파묻힌 모든 요소를
조사하는 루프로 증가한다.  */
lpdidod = &MouseBuffer[n];
if (( (int) lpdidod->dwOfs == DIMOFS_BUTTON0)
      && (lpdidod->dwData & 0x80))
{
 ;  // 왼쪽 버튼 압하에 응해 어떠한 처리를 실시한다.
}

디바이스 오브젝트 상태 변화 데이터는,DIDEVICEOBJECTDATA 구조체의 dwData 멤버에 저장 된다. 축의 경우에는, 좌표값이 이 멤버중에 돌려주어진다. 버튼 오브젝트의 경우는,dwData 의 하위 바이트만이 의미가 있다. 상위 비트는 버튼이 밀렸을 때에 설정되어 버튼이 떼어 놓아졌을 때에 소거된다. 바꾸어 말하면, (dwData & 0x80)가 제로가 아닐 때, 버튼이 밀리고 있게 된다.

액션 매핑을 사용하고 있는 경우는,dwOfs 의 값을 무시해, 키 이벤트에 관련하는 어플리케이션 정의 데이터를 uAppData 멤버로부터 취득한다.

DIDEVICEOBJECTDATA 구조체외의 멤버의 상세한 것에 대하여는, 「타임 스탬프와 순서 번호」를 참조할것.


마우스축데이터의 해석

마우스의 x 축 및 y 축으로 대해 돌려주어지는 데이터는, 커서는 아니고 마우스 자신의 동작을 나타낸다. 측정 단위는, 마우스의 하드웨어가 돌려주는 값에 근거하는 것이어, 픽셀이나 그 외의 화면 측정 형식과는 무관계하다. Microsoft® DirectInput® 는 마우스 드라이버와 직접 통신하므로, 유저가 컨트롤 패널로 설정하는 마우스의 스피드와 가속값은, 이 데이터에 영향을 주지 않는다.

마우스로부터 돌려주어지는 축데이터는, 상대에서도 절대라도 좋다 ( 「상대 좌표와 절대 좌표」를 참조할것). 마우스는 상대적인 디바이스이므로 (죠이스틱과는 달라, 홈 포지션을 가지지 않는다), 디폴트에서는, 상대 데이터가 돌려주어진다.

축모드는, 상대 데이터 또는 절대 데이터의 어느 쪽을 돌려주는지를 지정하는 것이지만, 디바이스를 취득하기 전으로 변경할 수 있는 프로퍼티이다 ( 「디바이스 프로퍼티」를 참조할것). 축모드를 "절대" 로 설정하려면 ,rguidProp 파라미터에 DIPROP_AXISMODE 값을 지정해,DIPROPDWORD 구조체의 dwData 멤버에 DIPROPAXISMODE_ABS 를 지정해,IDirectInputDevice8::SetProperty 를 호출한다.

마우스의 축모드가 "상대" 의 경우, 축좌표는, 마지막 값이 돌려주어진 이후, 축으로 따라 디바이스가 이동한 단위수를 나타낸다. 부의 값은, x축의 경우, 마우스가 좌방향으로 이동한 것, y 축의 경우, 유저로부터 멀어질 방향으로 마우스가 이동한 것, 및 z 축 (휠)이 앞에 회전한 것을 각각 가리킨다. 정의 값은 이것과 반대 방향의 움직임을 나타낸다.

축모드가 "절대" 의 경우, 축좌표는, 단순하게 DirectInput 가 수신한 상대 동작의 모든 누적 합계가 된다. 축좌표값은, 디바이스의 취득시에는, 특정의 값에 초기화되어 있지 않기 때문에, 어플리케이션은, 절대치를 미지의 원점을 기준으로 한 상대값으로서 취급할 필요가 있다. 디바이스를 취득했을 때는, 언제나 현재의 절대 위치를 기록해, 그것을 "가상 원점" 으로서 보존할 수가 있다. 이 가상 원점은, 그 후, 디바이스로부터 얻을 수 있는 절대 좌표로부터 감산하는 것으로써, 마우스가 취득시점으로부터 이동한 상대 거리를 계산할 수가 있다.

축좌표에 돌려주어지는 데이터는, 디바이스의 세분성 프로퍼티에 의해도 영향을 받는다. 마우스의 x 축과 y 축의 경우, 세분도는 보통 1 이며, 이것은, 값의 최소 변화가 1 인 것을 의미한다. 휠의 경우, 세분도가 1 보다 커질 수도 있다.


소실한 마우스 입력의 확인

협조 레벨에 DISCL_FOREGROUND 를 설정한 상태로, 포커스가 다른 어플리케이션에 바뀌는 경우 (혹은 사용중의 어플리케이션외의 메뉴에 바뀌는 경우에서도), Microsoft® Windows® 가 어플리케이션에 마우스를 강제적으로 해방시키는 일이 있다. 이 때문에,IDirectInputDevice8::GetDeviceData 또는 IDirectInputDevice8::GetDeviceState 메소드로부터의 반환값 DIERR_INPUTLOST 를 체크해, 필요에 따라서 마우스를 재취득할 필요가 있다 ( 「디바이스의 취득」을 참조할것).

주 : DIERR_NOTACQUIRED 에러를 받았을 경우에는, 마우스의 재취득을 시도하지 않게 할 필요가 있다. 그렇게 하지 않으면 엔들레스 루프에 들어갈 우려가 있다. 취득은 실패해, DIERR_NOTACQUIRED 에러를 받는다고 하는 반복이 영원히 계속된다.


키보드 데이터

Microsoft® DirectInput® 를 사용할때는, 키보드는 텍스트 입력 디바이스는 아니고, 다수의 버튼을 갖춘 게임패드인 것을 고려하는 것. 어플리케이션이 텍스트 입력을 필요로 할 때는, DirectInput 의 메소드를 이용해서는 안된다. 보통의 Microsoft Windows® 메세지로부터 데이터를 취득하는 것이 가장 간단하고, 문자 반복, 물리 키로부터 가상 키에의 평행이동등의 Windows 서비스를 이용할 수가 있기 때문이다. 이것은, 영어 이외의 언어를 사용하는 경우에는 특히 중요하다. 영어 이외의 언어에서는 키의 특별한 해석이 필요한 것이 있기 때문이다.

데이터를 취득하도록(듯이) 키보드 디바이스를 설정하려면 , 파라미터에 c_dfDIKeyboard 글로벌 변수를 지정해,IDirectInputDevice8::SetDataFormat 메소드를 호출한다 ( 「디바이스 데이터 형식」을 참조할것).

이하의 주제에서는, 키보드 데이터의 취득과 해석에 대해 상세하게 설명한다.

  • 키보드의 직접 데이터
  • 키보드의 버퍼링 데이터
  • 키보드 데이터의 해석
  • 소실한 키보드 입력의 확인


키보드의 직접 데이터

키보드의 현재 상태를 취득하려면 , 반환값 데이터를 보관 유지하는 256 바이트의 배열에의 포인터를 지정해,IDirectInputDevice8::GetDeviceState 메소드를 호출한다.

GetDeviceState 메소드는, Microsoft® Win32® GetKeyboardState 함수와 같게 동작한다. GetDeviceState 메소드는, 키보드의 현재 상태의 snapshot를 돌려준다. 각 키는, 256 바이트의 배열내의 1 바이트에 의해 나타내진다. 배열의 주소는,lpvData 파라미터로서 건네받은 것이다. 바이트의 상위 비트가 설정되어 있으면(자), 키는, 다운 상태에 있다. 배열은 가장 편리하게, Microsoft® DirectInput® 키보드 디바이스 정수에 의해 인덱스를 붙일 수 있고 있다 ( 「키보드 데이터의 해석」도 참조할것).

이하의 코드는, Esc 키의 압하에 응해 함수를 호출하는 예이다. lpdiKeyboard 는, 취득된 DirectInput 디바이스로 한다.

BYTE  diKeys[256];
if (lpdiKeyboard->GetDeviceState(256, diKeys) == DI_OK)
{
  if (diKeys[DIK_ESCAPE] & 0x80) DoSomething();
}


키보드의 버퍼링 데이터

키보드로부터 버퍼링 데이터를 취득하려면 , 버퍼 사이즈를 설정해야 한다 ( 「디바이스 프로퍼티」를 참조할것). 이 순서는, 버퍼의 디폴트 사이즈가 제로이므로 불가결하다.

또,DIDEVICEOBJECTDATA 구조체의 배열도 선언할 필요가 있다. 이 배열은, 최고로 버퍼 사이즈와 동수의 요소를 가질 수가 있다. 1 번의 호출로 버퍼의 내용 전체를 취득할 필요는 없다. 배열내의 1 요소만을 보관 유지해, 버퍼가 비울 때까지 1 개(살)씩 이벤트를 취득할 수가 있다.

키보드 디바이스의 취득 후는,IDirectInputDevice8::GetDeviceData 메소드를 사용해 언제라도 버퍼를 조사하거나 플래시 하거나 할 수가 있다 ( 「버퍼링 데이터와 직접 데이터」를 참조할것).

DIDEVICEOBJECTDATA 배열의 각 요소는, 단일 키 상태 변화, 즉, 압하 또는 해방을 나타낸다. Microsoft® DirectInput® 는, 키보드로부터 직접 데이터를 취득하기 위해서, 컨트롤 패널의 문자 반복의 설정은 모두 무시한다. 즉, 키스트로크(keystroke)는, 키가 압하되고 있는 시간의 장단에 관계없이, 1 번 밖에 카운트 되지 않는다고 하는 것이 된다.

배열중의 요소가 어느 키를 가리킬까는, DirectInput 의키보드 디바이스 정수와DIDEVICEOBJECTDATA 구조체의 dwOfs 멤버를 비교하는 것으로써 확인할 수 있다 ( 「키보드 데이터의 해석」도 참조할것).

액션 매핑을 사용하고 있는 경우는,dwOfs 의 값을 무시해, 키 이벤트에 관련하는 어플리케이션 정의 데이터를 uAppData 멤버로부터 취득한다.

키 상태 변화 데이터는,DIDEVICEOBJECTDATA 구조체의 dwData 멤버에 저장 되고 있다. dwData 의 하위 바이트만이 의미가 있다. 상위 비트는 키가 밀렸을 때에 설정되어 키가 떼어 놓아졌을 때에 소거된다. 바꾸어 말하면, (dwData & 0x80)가 제로가 아닐 때, 키가 밀리고 있게 된다.


키보드 데이터의 해석

여기에서는,IDirectInputDevice8::GetDeviceState 메소드 및 IDirectInputDevice8::GetDeviceData 메소드가 보고하는 데이터의 키의 식별에 대해 설명한다. GetDeviceData 로부터의 데이터의 해석에 대한 자세한 것은, 「타임 스탬프와 순서 번호」를 참조할것.

중요한 점으로서 Microsoft® DirectInput® 어플리케이션은, Microsoft Windows® 와는 다른 방법으로 키보드를 읽어낸다. DirectInput 어플리케이션에서는, 키보드 데이터는 가상 키를 가리키는 것이 아니라, 실제의 물리적인 키, 즉, 스캔 코드를 가리킨다. 예를 들어, DIK_ENTER 는 메인 키보드의 Enter 키를 가리키지만, 숫자 패드의 Enter 키는 가리키지 않았다.

또, 키보드의 차이에 의해, DirectInput 어플리케이션이 키보드 데이터를 해석하는 방법을 바꿀 수가 있다. 예를 들어, DirectInput 는, 확장 키보드 위에의 각 키에 대한 정수와 함께, 국제 키보드상에 있는 추가 키도 정의한다. NEC 키보드는, PC 확장 키보드와는 다른 스캔 코드를 지원 하고 있으므로, DirectInput 는, 가능한 한 NEC 스캔 코드를 PC 확장 스캔 코드로 변환한다.

이것들 이외로 키보드에 관해서 고려해야 할 사항은, 이하대로이다.

  • 또, 모든 PC 확장 키보드에, 새로운 Windows 키 (DIK_LWIN, DIK_RWIN, DIK_APPS)가 있는 것은 아니다. Windows 키가 물리적으로 사용 가능한가 어떤가를 결정하는 방법은 없다.
  • 랩탑등의 소형 컴퓨터는, 풀 세트의 키를 이행 하고 있지 않다. 대신에, 일부의 키 (보통은 숫자 패드)를 다른 키와 다중화해, 보조 모드 키에 의해 선택하도록(듯이) 해, 개별의 스캔 코드를 만들지 않게 하고 있다.
  • 키보드 서브 타입이 PC XT 또는 PC AT 키보드를 나타내고 있는 경우, DIK_F11, DIK_F12, 및 모든 확장 키 (0x7F 보다 큰 DIK_* 값을 가지는 키)는 이용할 수 없다. 게다가 PC XT 키보드에는 DIK_SYSRQ 가 없다.
  • 일본어 키보드, 특히 NEC PC-98 키보드는, US 키보드와는 상당히 다른 키 세트를 포함하고 있다. 상세한 것에 대하여는, 「DirectInput 와 일본어 키보드」를 참조할것.


소실한 키보드 입력의 확인

협조 레벨을 DISCL_FOREGROUND 로 설정한 상태로, 포커스가 다른 어플리케이션에 바뀌는 경우, Microsoft® Windows® 가 어플리케이션에 키보드를 강제적으로 해방시키는 일이 있다. 이 때문에,IDirectInputDevice8::GetDeviceData 메소드 또는 IDirectInputDevice8::GetDeviceState 메소드로부터의 DIERR_INPUTLOST 반환값을 체크해, 필요에 따라서 키보드를 재취득할 필요가 있다 ( 「디바이스의 취득」을 참조할것).

주 : DIERR_NOTACQUIRED 에러를 받았을 경우에는, 키보드의 재취득을 시도하지 않게 할 필요가 있다. 그렇게 하지 않으면 엔들레스 루프에 들어갈 우려가 있다. 취득은 실패해, DIERR_NOTACQUIRED 에러를 받는다고 하는 반복이 영원히 계속된다.


죠이스틱 데이터

데이터를 취득하도록(듯이) 죠이스틱 디바이스를 설정하려면 , 파라미터에 c_dfDIJoystick 또는 c_dfDIJoystick2 글로벌 변수를 지정해,IDirectInputDevice8::SetDataFormat 메소드를 호출한다 ( 「디바이스 데이터 형식」을 참조할것).

일부의 디바이스 드라이버는, 명시적으로 요구될 때까지 Microsoft® DirectInput® 에 상태의 변화를 통지하지 않는 것이 있으므로, 죠이스틱의 데이터를 취득하기 전에는 반드시 IDirectInputDevice8::Poll 메소드를 호출하지 않으면 안 된다. 상세한 것에 대하여는, 「폴링과 이벤트 통지」를 참조할것.

이하의 주제에서는, 죠이스틱 및 게임패드 또는 조종간등의 입력 디바이스로부터의 데이터의 취득과 해석에 대해 설명한다.

  • 죠이스틱의 직접 데이터
  • 죠이스틱의 버퍼링 데이터
  • 죠이스틱축데이터의 해석
  • 소실한 죠이스틱 입력의 확인


죠이스틱의 직접 데이터

죠이스틱의 현재 상태를 취득하려면 ,DIJOYSTATE 구조체 또는 DIJOYSTATE2 구조체에의 포인터를 지정해 IDirectInputDevice8::GetDeviceState 메소드를 호출한다. 어느 쪽의 구조체를 사용할까는,c_dfDIJoystick 이나 c_dfDIJoystick2 의 어디에서 데이터 형식이 설정되었는지에 의한다 ( 「디바이스 데이터 형식」을 참조할것). 구조체에 돌려주어지는 죠이스틱 상태에는, 축좌표, 버튼 상태, 및 시점 콘트롤러 상태등이 있다.

DIJOYSTATE 구조체의 최초의 7 개의 멤버가 축좌표를 보관 유지한다. 이 중 마지막 멤버 rglSlider 는 2 개의 값의 배열이다 (죠이스틱축데이터의 해석을 참조할것).

rgdwPOV 멤버에는, 4 개(살)까지의 시점 콘트롤러의 위치가 포함되어 있다. 이것들은, 북쪽으로부터 시계회전 (또는 전방)의 열매 각도의 100 배로 나타내진다. 중심 위치 (중립점)는 -1 으로서 보고된다. 5 개의 위치 밖에 가지지 않는 콘트롤러의 경우, 위치는 이하의 어떤 것이나 1 개의 값을 취한다.

  • -1
  • 0
  • 90 * DI_DEGREES
  • 180 * DI_DEGREES
  • 270 * DI_DEGREES

중심 위치로서-1 는 아니게 65,535 를 보고하는 드라이버도 있다. POV 표지가 중심 위치에 있을지 어떨지는, 다음과 같이 체크해야 한다.

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

rgbButtons 멤버는, 바이트 배열이다. 데이터 형식에 의해, 32 개 또는 128 개의 각 버튼에 1 요소가 대응한다. 각 버튼의 상위 비트는, 버튼이 다운 상태로 설정되어 업 상태 또는 존재하지 않는 경우에 소거된다

DIJOYSTATE2 구조체에는, 축의 속도, 가속도, 포스, 및 토르크에 대한 정보를 제공하는 추가 멤버가 있다.

참조

버퍼링 데이터와 직접 데이터


죠이스틱의 버퍼링 데이터

죠이스틱으로부터 버퍼링 데이터를 취득하려면 , 우선, 버퍼 사이즈를 설정해 ( 「디바이스 프로퍼티」를 참조할것),DIDEVICEOBJECTDATA 구조체의 배열을 선언해야 한다. 이 배열은, 최고로 버퍼 사이즈와 동수의 요소를 가질 수가 있다. 한 번의 호출로 버퍼의 내용 전체를 취득할 필요는 없다. 배열내의 1 요소만을 보관 유지해, 버퍼가 비울 때까지 1 개(살)씩 이벤트를 취득할 수가 있다.

디바이스의 취득 후는,IDirectInputDevice8::GetDeviceData 메소드를 사용해 언제라도 버퍼를 조사하거나 플래시 하거나 할 수가 있다 ( 「버퍼링 데이터와 직접 데이터」를 참조할것).

DIDEVICEOBJECTDATA 배열중의 각 요소는, 죠이스틱에 대한 단일 오브젝트 상태의 변화를 나타낸다. 예를 들어, 유저가 버튼 0 을 눌러 스틱을 비스듬하게 이동 하면,GetDeviceData 에게 건네진 배열 (3 개(살) 이상의 요소를 가지고 있는 경우,pdwInOut 는 3 이상)은, 3 개의 요소를 묻을 수 있다. 이러한 요소는 각각, 버튼 0 의 압하, x 축의 변화, 및 y 축의 변화를 나타낸다. pdwInOut 는 3 으로 설정된다.

배열중의 요소가 어느 오브젝트를 가리킬까는, 이하의 값과DIDEVICEOBJECTDATA 구조체의 dwOfs 멤버를 비교하는 것으로써 결정할 수 있다.

  • DIJOFS_X
  • DIJOFS_Y
  • DIJOFS_Z
  • DIJOFS_Rx
  • DIJOFS_Ry
  • DIJOFS_Rz
  • DIJOFS_BUTTON0 로부터 DIJOFS_BUTTON31 또는 DIJOFS_BUTTON(n)
  • DIJOFS_POV(n)
  • DIJOFS_SLIDER(n)

이러한 각각의 값은,DIJOYSTATE 구조 체내의 오브젝트에 대한 데이터의 오프셋(offset)와 동일하다. 예를 들어, DIJOFS_BUTTON0 는,DIJOYSTATE 구조 체내의 rgbButtons[0] 오프셋(offset)와 동일하다. 단순한 비교를 실시하는 것으로, 어느 디바이스 오브젝트가 버퍼 위에의 항목에 관련하고 있는지를 확인할 수가 있다. 예를 들어, 이하대로이다.

DIDEVICEOBJECTDATA  *lpdidod;
int                 n;
.
.
.
/* JoyBuffer 는, DIDEVICEOBJECTDATA 구조체의 배열이며,
GetDeviceData 에의 호출에 의해 설정된다.
n 는, 배열중에서 파묻힌 모든 요소를
조사하는 루프로 증가한다.  */
lpdidod = &JoyBuffer[n];
if (( (int) lpdidod->dwOfs == DIJOFS_BUTTON0)
   && (lpdidod->dwData & 0x80))
{
 ;  // 주버튼의 압하에 응해, 어떠한 처리를 실시한다.
}

데이터 형식이 c_dfDIJoystick2 로 설정되었을 경우는,DIJOYSTATE 내에 존재하는 모든 디바이스 오브젝트에 사전 정의된 오프셋(offset)를 사용할 수가 있다. 다만,DIJOYSTATE2 의 추가 멤버에 표현되는 디바이스 오브젝트에는, 독자적인 오프셋(offset)를 설정할 필요가 있다.

액션 매핑을 사용하고 있는 경우는,dwOfs 의 값을 무시해, 키 이벤트에 관련하는 어플리케이션 정의 데이터를 uAppData 멤버로부터 취득한다.

디바이스 오브젝트 상태 변화 데이터는,DIDEVICEOBJECTDATA 구조체의 dwData 멤버에 저장 된다. 축의 경우에는, 좌표값이 이 멤버중에 돌려주어진다. 버튼 오브젝트의 경우는,dwData 의 하위 바이트만이 의미가 있다. 상위 비트는 버튼이 밀렸을 때에 설정되어 버튼이 떼어 놓아졌을 때에 소거된다.

다른 멤버에 대해서는, 「타임 스탬프와 순서 번호」를 참조할것.


죠이스틱축데이터의 해석

죠이스틱의 축값은, 마우스의 축값과 같다. 스틱을 오른쪽으로 작동시키면(자) x 축의 반환값이 늘어나, 스틱을 앞에 당겨 넘어뜨리면(자) y 축의 값이 늘어난다.

죠이스틱축의 데이터는, 축의 범위 프로퍼티에 의해 임의의 단위로 결정된다. 예를 들어, 죠이스틱의 x 축의 범위가 0 에서 10,000 까지의 경우에는, 단위는 죠이스틱의 좌우의 이동의 10,000 분의 1 이 되어, 중심 위치는 5,000 이 된다. 축으로야는은, 세분도 프로퍼티가 1 보다 큰 경우도 있어, 그 경우에는 값은 말 수 있다. 예를 들어, 세분도가 10 의 경우에는, 값은 0, 10, 20 등과 같이 보고된다.

축데이터는, 무효 존이라고 하는, 동작이 무시되는 중심 위치의 주변 영역에 의해도 영향을 받는다. 무효 존은, 죠이스틱의 적어도 한편의 축으로 대하는 진정한 중심 위치로부터 가 작은 차이에 대한 허용 범위가 된다. 무효 존내의 축의 값은, 진정한 중심으로서 보고된다.

축의 포화 프로퍼티란, 범위의 최대치 및 최소 값의 허용 존이다. 이 존내의 축값은, 최소 값 또는 최대치로서 보고된다. 포화 프로퍼티의 목적은, 예를 들어, 죠이스틱의 정부의 왼쪽 위치와 저부의 왼쪽 위치에서 보고되는 최소 x 축간의 몇 안 되는 차위를 허용 하는 것에 있다.

다음의 그림은, 무효 존과 포화 존의 이펙트를 나타낸 것이다. 수직축은, 축의 반환값을 나타낸다. 여기서,min 와 max 는 보고된 범위의 하한과 상한이며,ctr 는 보고된 중심이다. 수평축은, 죠이스틱의 물리적인 위치를 나타낸다. 여기서,pmin 와 pmax 는, 물리적인 범위의 한계,pctr 는 축의 중립점,dmin 와 dmax 는 무효 존의 한계값, 그리고 smin 와 smax 는 상하의 포화 존의 경계이다. 하위 포화 존은 pmin 와 smin 의 사이에 존재해, 상위 포화 존은 smax 와 pmax 의 사이에 존재해, 무효 존은 dmin 와 dmax 의 사이에 존재한다.

죠이스틱 프로퍼티의 상세한 것에 대하여는, 이하를 참조할것.

  • IDirectInputDevice8::GetProperty
  • IDirectInputDevice8::SetProperty
  • DIPROPRANGE
  • DIACTIONFORMAT

죠이스틱으로부터 돌려주어지는 축좌표는, 상대에서도 절대라도 좋다 ( 「상대 좌표와 절대 좌표」를 참조할것). 죠이스틱은 절대 디바이스이므로 (마우스와는 달라, 축으로 따라 무한하게는 이동할 수 없다), 디폴트에서는 절대 데이터가 돌려주어진다. 죠이스틱의 축모드가 "상대" 로 설정되어 있는 경우에는, 축좌표는, 마지막 값이 돌려주어지고 나서 이후의 축으로 휜 이동의 단위수를 나타낸다.

축모드는, 상대 데이터 또는 절대 데이터의 어느 쪽을 돌려주는지를 지정하는 것이지만, 디바이스를 취득하기 전으로 변경할 수 있는 프로퍼티이다 ( 「디바이스 프로퍼티」를 참조할것). 축모드를 "상대" 로 설정하려면 ,rguidProp 파라미터에 DIPROP_AXISMODE 값을 지정해,DIPROPDWORD 구조체의 dwData 멤버에 DIPROPAXISMODE_REL 를 지정해,IDirectInputDevice8::SetProperty 메소드를 호출한다.


CPOINT 의 사용법

CPOINT 구조체를 사용해, 디바이스축의 응답 커브의 세그먼트(segment)를 calibration 한다. DIPROPCPOINTS 구조체를 개입시켜, 최고 8 개의 CPOINT 를 설정할 수 있다. 각 CPOINT 구조체에는, 죠이스틱의 축위에의 위치를 나타내는 미처리의 데이터와 논리값이 저장 되고 있다. 어플리케이션이 미처리의 데이터를 받으면(자), 논리값을 사용해, 실제로 사용되는 반환값을 계산한다. 지정된 CPOINT 미처리 데이터의 값의 범위내에 있는 미처리값은, CPOINT 와 값의 몇개의 구석을 묶는 선에 근거해, 논리값에 보간 된다.

다음에 나타내는 것은, 죠이스틱의 X 축의 응답 커브에 5 개의 CPOINT 를 적용한 예이다. DIPROPCPOINTS 구조체의 적용전은, 이 예의 축으로 대하는 응답 그래프는, 포화와 데드 존을 포함해 이하와 같이 된다.

DIPROPCPOINTS 구조체는, 물리적 범위를 -500 ~ 500 으로 해, 다음과 같이 초기화된다.

DIPROPCPOINTS dipcp;

dipcp.diph.dwSize = sizeof(DIPROPCPOINTS);
dipcp.diph.dwHeaderSize = sizeof(DIPROPHEADER);
dipcp.diph.dwObj = GUID_XAxis;
dipcp.diph.dwHow = DIPH_BYID;
dipcp.dwCPointsNum = 5;
dipcp.cp[0]. lP = -500
dipcp.cp[0]. dwLog = 0
dipcp.cp[1]. lP = -300
dipcp.cp[1]. dwLog = 1000
dipcp.cp[2]. lP = -100
dipcp.cp[2]. dwLog = 5000
dipcp.cp[3]. lP = 200
dipcp.cp[3]. dwLog = 9000
dipcp.cp[4]. lP = 500
dipcp.cp[4]. dwLog = 10000

CPOINT 구조체의 dwLog 멤버의 값은 합계에 대한 퍼센티지 (전범위내에서의 개개의 눈금의 수)로서 10000 을 곱셈해 표현되기 (위해)때문에, 실제의 반환값의 최대치를 알 필요는 없는 것에 주의한다. 예를 들어 이 예는, 죠이스틱의 범위를 -300 포인트로서 최대치의 10% 가 돌려주어지는 커브가 설정되어 있다. 0.10 * 10000 = 1000 이 되어, 이 값은 dwLog 멤버에게 줄 수 있어 대응하는 lP 멤버에는 -300 이 할당할 수 있다.

이 DIPROPCPOINTS 구조체를 IDirectInputDevice8::SetProperty 로 적용한 후, 커브는 다음과 같이 응답한다.


소실한 죠이스틱 입력의 확인

죠이스틱을 foreground 모드로 사용하는 ( 「협조 레벨」을 참조할것) 경우에는, 포커스가 다른 어플리케이션에 바뀔 때, 디바이스를 상실하는 일이 있다.

IDirectInputDevice8::GetDeviceData 메소드 또는 IDirectInputDevice8::GetDeviceState 메소드로부터의 DIERR_INPUTLOST 반환값을 체크해, 필요에 따라서 죠이스틱을 재취득할 수가 있다 ( 「디바이스의 취득」을 참조할것).

주 : DIERR_NOTACQUIRED 에러를 받았을 경우에는, 죠이스틱의 재취득을 시도하지 않게 할 필요가 있다. 그렇게 하지 않으면 엔들레스 루프에 들어갈 우려가 있다. 취득은 실패해, DIERR_NOTACQUIRED 에러를 받는다고 하는 반복이 영원히 계속된다.

키보드나 마우스와는 달라, Microsoft® Windows® 시스템은 죠이스틱을 사용하지 않기 때문에, 어플리케이션이 백그라운드로 이행하는 경우를 제외해, 죠이스틱에의 액세스권이 없어질 것은 없다. 따라서, 어느 쪽의 메소드에서도, WM_ACTIVATE 메세지에 응해 디바이스를 재취득할 수 있다.


데이터 출력

휴먼 인터페이스 디바이스는, 입력의 생성과 같게 출력을 인지할 수가 있다. IDirectInputDevice8::SendDeviceData 메소드는, 데이터의 패킷을 그러한 디바이스에 보낸다.

SendDeviceData 는, 반대로 IDirectInputDevice8::GetDeviceData 로서 표시할 수가 있다. SendDeviceData 메소드와 같이, GetDeviceData 메소드는, 데이터의 기본 단위로서 DIDEVICEOBJECTDATA 구조체를 사용한다. 이 경우,dwOfs 멤버에 포함되는 것은, 디바이스의 데이터 형식의 오프셋(offset)는 아니고, 데이터에 관련지을 수 있었던 디바이스 오브젝트의 인스턴스 ID 이다(오프셋(offset) 식별자는, 선택된 데이터 형식에서의 입력을 제공하는 디바이스 오브젝트 (을) 위해서만 존재하므로, 출력 밖에 인정하지 않는 오브젝트는, 오프셋(offset)를 가지는 것조차 없다). dwData 멤버에는, 그 오브젝트에 적절한 데이터가 포함된다. dwTimeStamp 및 dwSequence 멤버는 사용하지 않는다. 이러한 멤버는, 제로로 설정해야 한다.

디바이스에 데이터를 보내려면 , 최초로 DIDEVICEOBJECTDATA 구조체의 배열을 설정해, 요구된 수의 요소를 데이터로 묻고 나서, 사용되는 주소와 요소수를 SendDeviceData 에 건네준다. 다른 디바이스 오브젝트의 데이터는, 디바이스에 보내지는 단일 패킷에 결합된다.

데이터 패킷의 형식은, 패킷내의 사용되지 않는 필드의 처리 방법과 같아, 디바이스에 따라서 다르다. 디바이스에 따라서는, 필드를 옵션으로서 취급한다. 즉, 데이터가 제공되지 않는 경우, 오브젝트 상태는 전과 같다. 일반적으로는, 특히 데이터가 필드에 제공되지 않는 경우여도, 모든 필드는 중요하다. 예를 들어, 단일의 키보드 LED 에 데이터를 보내면(자), 다른 2 개의 LED 의 데이터는 제로로, 그러한 LED 는 오프이라고 가정된다. 다만, DISDD_CONTINUE 플래그를 사용해 이 동작을 무효로 할 수 있다. 이 경우는, 다른 2 개의 LED 의 데이터는, 마지막에 송신한 값이 된다.

디바이스 오브젝트의 형태의 식별자는, HID 사용 페이지와 사용 코드를 IDirectInputDevice8::GetObjectInfo 에 건네준 다음에 DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버로부터 취득한다. 예를 들어 Scroll Lock LED 의 형태 식별자는, 이하의 코드를 사용해 취득한다. 이 코드로,pdev 는 키보드를 나타내는 IDirectInputDevice8 인터페이스 포인터이다.

DIDEVICEOBJECTINSTANCE didoi;
DWORD NumLockID;

HRESULT hr = pdev->GetObjectInfo(&didoi,
        DIMAKEUSAGEDWORD(0x07, 0x53), DIPH_BYUSAGE);
NumLockID = didoi.dwType;

다음의 예에서는, 코드가 반복해 실행되는 경우, 키보드 위에의 LED 는 반복해 점멸한다. LED 상태는, 데이터 바이트의 상위 비트에 의해 결정되는 것으로 한다. DWORD 의 NumLockID,CapsLockID, 및 ScrollLockID 는, 모두 이 방법으로 취득한다.

#define ARRAYSIZE 4
void FlashLEDs(void)
    {
    static int         rgiBits[] = { 1, 2, 4, 2 };
    static int         iLooper = 0;
    DWORD              cdod = 3;                  // 항목수.
    DIDEVICEOBJECTDATA rgdod[ARRAYSIZE-1];
    HRESULT            hres;

    // dwTimeStamp 및 dwSequence 를 소거할 필요가 있다.
    ZeroMemory(rgdod, sizeof(rgdod));

    rgdod[0]. dwOfs = NumLockID;
    rgdod[1]. dwOfs = CapsLockID;
    rgdod[2]. dwOfs = ScrollLockID;

    rgdod[0]. dwData = (rgiBits[iLooper] & 1) ?  0x80 : 0;
                                           // NumLock 라이트의 온/오프
    rgdod[1]. dwData = (rgiBits[iLooper] & 2) ?  0x80 : 0;
                                           // CapsLock 라이트의 온/오프
    rgdod[2]. dwData = (rgiBits[iLooper] & 4) ?  0x80 : 0;
                                           // ScrollLock 라이트의 온/오프

    iLooper = (iLooper + 1) % ARRAYSIZE; // 0 에서 3 까지 루프 한다.

    hres = pdev->SendDeviceData(sizeof(DIDEVICEOBJECTDATA),
            rgdod, &cdod, 0);
    }


액션 매핑

종래, 어플리케이션은 특정의 버튼이나 축으로 대해 독자적인 이벤트 매핑을 실시하고 있었다. 예를 들어 카 레이싱 게임의 경우, 유저의 죠이스틱이나 마우스의 x 축이 차의 운전용 컨트롤에 최적이다라고 상정된다. 신규 디바이스나 특수 디바이스를 짜넣는 유일한 방법은, 유저가 운전용으로 사용하는 회전축 등 그 외의 축을 지정할 수 있도록(듯이), 구성 옵션을 제공하는 것이었다. 게다가 어플리케이션은, 인스톨 된 어느 디바이스가 게임에 최적인가를 아는 수단은 없었기 때문에, 유저는 보통, 메뉴로부터 디바이스를 선택하거나 적절한 디바이스만이 접속되고 있는 것을 확인하거나 해야 했다.

액션 매핑을 사용하면(자), 디바이스와 디바이스 오브젝트의 최적인 사용법에 관해서 다양한 일을 상정할 필요는 없어진다. 그 대신에, 어플리케이션이, 가능한 한 액션과 가상 컨트롤을 바인드 한다. 어플리케이션은, x 축으로부터 데이터를 취득해 차를 좌우에 움직이는 것이 아니라, DIAXIS_DRIVINGR_STEER 라고 하는 가상 컨트롤로부터 데이터를 취득하게 된다. Microsoft® DirectInput® 는, 가상 컨트롤을 물리 컨트롤, 즉 디바이스 오브젝트에 할당한다. 할당하고 시에는, 어플리케이션의 장르, 유저 설정, 디바이스 메이커로부터의 정보, 및 유저의 디바이스 구성이 고려된다.

또, 액션 매핑을 사용하면(자), 모든 디바이스의 데이터가, 특정의 디바이스에 의존하지 않는 형식에서 돌려주어지는 것으로, 입력 루프가 간소화된다. 단일의 액션을 복수의 디바이스에 맵 할 수 있어 그 액션에 대해, 어느 디바이스를 읽어내 안인가에 관계없이, 입력 루프가 동일한 방법으로 응답할 수가 있다.

이하의 주제에서는, 액션 매핑의 이행에 필요한 순서의 상세를 설명한다.

  • 액션 맵의 준비
  • 일치하는 디바이스의 검색
  • 액션 맵의 구성
  • 디바이스의 유저 구성
  • 액션 데이터의 취득
  • 개발중의 파일의 관리


액션 맵의 준비

액션 맵이란, 어플리케이션의 액션과 가상 컨트롤이나 디바이스 오브젝트에의 매핑에 관한 정보를 저장 하고 있는 DIACTIONFORMAT 구조체이다. 이 구조체가 어플리케이션과 Microsoft® DirectInput® 의 사이에 거래되어 최종적인 매핑이 확립된다. 여기에서는, 맵의 초기화 방법에 대해 설명한다.

1. 어플리케이션 액션의 정의

DirectInput 액션 매핑을 이행 할 때의 제 1 스텝은, 어플리케이션내의 어느 입력 드리분아크션을 디바이스 오브젝트에 맵 할 필요가 있을까를 결정하는 것이다. 축이나 버튼에 의해 실행할 수 있는 액션의 경우, 축과 버튼의 양쪽 모두의 입력 타입에 독립한 액션을 정의해야 한다. 디바이스가 적절한 축을 가지지 않는 경우에 대비해, 중요한 기능에는 모두 버튼 액션을 정의하는 것이 추천 된다.

다음의 액션값의 열거예는, 카 레이싱 게임에 의해 정의되는 것으로 한다. 축액션은 "eA" 로 시작되어, 버튼 액션은 "eB" 로 시작된다.

enum eGameActions
{
    eA_STEER,       // 핸들
    eB_STEER_LEFT,  // 핸들을 왼쪽으로 자른다
    eB_STEER_RIGHT, // 핸들을 오른쪽으로 자른다
    eA_ACCELERATE,  // 속도 변경
    eB_ACCELERATE,  // 가속
    eB_DECELERATE,  // 감속
    eA_BRAKE,       // 브레이크
    eB_BRAKE,       // 브레이크
    eB_UPSHIFT,     // 고속 기어에 쉬프트
    eB_DOWNSHIFT,   // 저속 기어에 쉬프트
    eB_CYCLEVIEW,   // 다음의 뷰로 전환
    eB_COURSEVIEW,  // 코스 뷰의 변환
    eB_DRIVERVIEW,  // 운전석 뷰
    eB_BRAKEBIAS,   // 브레이크 바이어스
    eA_VOLUME,      // 음량
    eB_MUTE         // 사운드의 변환
};

#define NUM_MY_ACTIONS 16

이 예에서는, 액션은 열거값으로서 정의되고 있다. 다만, 함수에의 포인터 등, 다른 32 비트 데이터형을 취할 수도 있다. 디바이스 데이터를 취득하는 경우, 정의한 액션값은 모두 취득되므로, 그 값을 자유롭게 처리할 수 있다.

2. 장르의 정의

제 2 스텝은, 어플리케이션이 속하는 장르를 결정하는 것이다. 장르에 의해, 가상 컨트롤세트가 정의된다. 적절한 장르를 선택하는 것으로, 어플리케이션 액션에 대해서 최적인 가상 컨트롤을 취득할 수 있다. 메이커가 디바이스에 디폴트 매핑을 설정하는 경우, 메이커는 DirectInput 로 정의된 장르중 1 개(살) 이상을 지원 해야 한다. 장르 일람에 대해서는, 「액션 매핑 정수」를 참조할것.

이 예의 게임의 경우는, 당연히 DIVIRTUAL_DRIVING_RACE 장르를 선택한다. 이 장르에는 이하의 가상 컨트롤이 포함되어 있다.

우선 순위 1 의 컨트롤

DIAXIS_DRIVINGR_STEER
DIAXIS_DRIVINGR_ACCELERATE
DIAXIS_DRIVINGR_BRAKE
DIBUTTON_DRIVINGR_SHIFTUP
DIBUTTON_DRIVINGR_SHIFTDOWN
DIBUTTON_DRIVINGR_VIEW
DIBUTTON_DRIVINGR_MENU

우선 순위 2 의 컨트롤

DIAXIS_DRIVINGR_ACCEL_AND_BRAKE
DIHATSWITCH_DRIVINGR_GLANCE
DIBUTTON_DRIVINGR_ACCELERATE_LINK
DIBUTTON_DRIVINGR_AIDS
DIBUTTON_DRIVINGR_BOOST
DIBUTTON_DRIVINGR_BRAKE
DIBUTTON_DRIVINGR_DASHBOARD
DIBUTTON_DRIVINGR_DEVICE
DIBUTTON_DRIVINGR_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGR_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGR_MAP
DIBUTTON_DRIVINGR_PAUSE
DIBUTTON_DRIVINGR_PIT
DIBUTTON_DRIVINGR_STEER_LEFT_LINK
DIBUTTON_DRIVINGR_STEER_RIGHT_LINK

우선 순위 1 의 컨트롤과 우선 순위 2 컨트롤의 사이에 기능상의 차이는 없다. 우선 순위 1 의 컨트롤은, 디바이스 메이커가 디폴트 매핑으로서 지원 하는 것이 바람직한 컨트롤이다. 다만, 어느 가상 컨트롤도, 디바이스에 의해 지원 되는 보증은 없다.

3. 컨트롤이나 디바이스 오브젝트에의 액션의 할당

액션 맵 생성의 다음의 스텝에서는, 각각의 어플리케이션 액션에, 해당 장르로 정의된 1 개(살) 이상의 가상 컨트롤을 관련짓는다. 이 처리를 실시하려면 ,DIACTION 구조체의 배열을 선언해 초기화한다. 배열내의 구조체는 각각, 액션값, 거기에 관련지을 수 있었던 가상 컨트롤, 및 그 액션을 설명하는 등록명을 지정한다. 그 외의 멤버는 제로로서 남긴다. 이러한 멤버의 값은 다음에 DirectInput 에 의해 지정된다.

DIACTION 배열의 요소를 사용해, 액션을 키보드의 특정의 키, 또는 마우스의 특정의 버튼, 혹은 Microsoft DirectPlay® 음성 디바이스에 맵 할 수도 있다. 그렇게 하는 것으로, 가상 컨트롤로부터의 입력에 한정하지 않고 모든 입력으로, 간략화된 입력 루프를 이용할 수 있다. 예를 들어, 어플리케이션 정의 액션 eB_UPSHIFT 를 DIBUTTON_DRIVINGR_SHIFTUP 가상 컨트롤과 Page Up 키의 양쪽 모두에 맵 하면 하자. 데이터를 취득하는 경우, 입력원이 죠이스틱 버튼과 키보드의 어디에서 있을까에 관계없이, eB_UPSHIFT 를 취득한다.

이하의 예는, 카 레이싱 게임용의 액션 맵을 선언하고 있다.

DIACTION rgActions[]=
{
// 장르 정의의 가상축.

  {eA_STEER,       DIAXIS_DRIVINGR_STEER,        0, "Steer",      },
  {eA_ACCELERATE,  DIAXIS_DRIVINGR_ACCELERATE,   0, "Accelerate", },
  {eA_BRAKE,       DIAXIS_DRIVINGR_BRAKE,        0, "Brake",      },

// 장르 정의의 가상 버튼.

  {eB_UPSHIFT,     DIBUTTON_DRIVINGR_SHIFTUP,    0, "Upshift",    },
  {eB_DOWNSHIFT,   DIBUTTON_DRIVINGR_SHIFTDOWN,  0, "DownShift",  },
  {eB_CYCLEVIEW,   DIBUTTON_DRIVINGR_VIEW,       0, "Change View",},

// 임의의 버튼이나 축으로 할당하고 가능한
// 장르 미정도리의 액션.

  {eA_VOLUME,      DIAXIS_ANY_1,                 0, "Volume",      },
  {eB_MUTE,        DIBUTTON_ANY(0),              0, "Toggle Sound",},

// 특정의 키에 할당할 필요가 있다
// 장르 미정도리의 액션.

  {eB_DRIVERVIEW,  DIKEYBOARD_1,                 0, "Driver View",},
  {eB_COURSEVIEW,  DIKEYBOARD_C,                 0, "Course View",},
  {eB_BRAKEBIAS,   DIKEYBOARD_B,                 0, "Brake Bias", },

// 키와 가상 컨트롤에 맵 된 액션.

  {eB_UPSHIFT,     DIKEYBOARD_PRIOR,              0, "Upshift",    },
  {eB_DOWNSHIFT,   DIKEYBOARD_NEXT,               0, "Downshift",  },
  {eB_STEER_LEFT,  DIKEYBOARD_LEFT,               0, "Steer Left", },
  {eB_STEER_RIGHT, DIKEYBOARD_RIGHT,              0, "Steer Right",},
  {eB_ACCELERATE,  DIKEYBOARD_UP,                 0, "Accelerate", },
  {eB_DECELERATE,  DIKEYBOARD_DOWN,               0, "Decelerate", },
  {eB_BRAKE,       DIKEYBOARD_END,                0, "Brake",      },

// 버튼과 가상 컨트롤 및 키에 맵 된 액션.

  {eB_UPSHIFT,     DIMOUSE_BUTTON0,              0, "Upshift",   },
  {eB_DOWNSHIFT,   DIMOUSE_BUTTON1,              0, "Downshift", },
};

이 예로, 일부의 액션은,키보드 매핑 정수를 사용해 실제의 키에 맵 되고 있다. 같이 마우스의 버튼과 축에의 매핑도,마우스 매핑 정수를 사용해 실시할 수가 있다.

DIACTION 배열은, 장르, 어플리케이션, 및 축데이터의 적절한 스케일링에 관한 정보를 저장 하는 DIACTIONFORMAT 구조체의 일부이다. 액션 매핑 프로세스의 전체에 걸쳐, 이 구조체의 같은 인스턴스를 사용한다. 일부의 멤버는 곧바로는 사용되지 않지만, 다음의 스텝 「일치하는 디바이스의 검색」으로 옮기기 전에, 구조체 전체에 값을 설정할 수 있다.


일치하는 디바이스의 검색

어플리케이션 액션과 그러한 액션의 맵처인 가상 컨트롤이나 디바이스 오브젝트의 정의가 끝나면(자), 다음의 스텝에서는, 시스템 위에의 디바이스를 열거해, 목적의 가상 컨트롤에 최적인 디바이스를 검색한다.

이것을 실시하기 위해서(때문에),IDirectInput8::EnumDevicesBySemantics 에 DIACTIONFORMAT 구조체를 건네준다. 이 메소드는, 대부분의 점으로써 IDirectInput8::EnumDevices 와 같이 기능해, 유사한 콜백 함수를 취한다.

특정의 컨트롤에 일치하도록(듯이) 유저가 구성한 디바이스는, 항상 최초로 열거된다. 예를 들어, 유저가 휠을 드라이빙 게임의 프라이머리 스티어링 디바이스로서 구성해 있는 경우는, DIAXIS_DRIVINGR_STEER 를 지원 하는 디바이스가 요구되면(자) 휠이 최초로 열거된다. DIAXIS_DRIVINGR_STEER 를 지원 하는 죠이스틱등의 다른 디바이스가 있어도, 유저에 의해 구성되어 있지 않으면, 휠이 우선된다. 그 이외의 경우, 이용 가능한 디바이스의 열거순서는, 요구된 컨트롤에 일치하는 정도에 의해 정해진다.

열거 콜백에서는, 각 디바이스의 디폴트 액션 매핑의 취득, 불필요한 매핑의 변경, 유저가 디바이스를 복구성 하는 기능의 설정, 및 액션 맵의 적용을 실시할 수가 있다. 이러한 스텝에 대해서는, 「액션 맵의 구성」으로 설명한다. DIEnumDevicesBySemanticsCallback 에 돌려주어지는 플래그는, 특정의 디바이스가 열거된 이유에 대한 정보를 제공한다. 이러한 플래그는, 디바이스가 최근 사용되었는지, 새롭고 인스톨 되었는지,우선 순위 1 또는 우선 순위 2 의 컨트롤의 매핑을 받아들일지 어떨지를 나타낸다.


액션 맵의 구성

각 디바이스가 열거되면(자), 그 디바이스에의 포인터의 취득, 디폴트 액션 맵의 취득, 디폴트 맵에의 변경, 및 최종 매핑의 적용을 실시할 수가 있다.

1. 디바이스의 취득

열거 콜백의 lpdid 파라미터로부터, 열거된 각 디바이스의 IDirectInputDevice8 인터페이스 포인터를 취득한다. 「DIEnumDevicesBySemanticsCallback 」를 참조할것. 어플리케이션으로 사용할 수 있도록(듯이) 디바이스 인터페이스를 보존하고 싶은 경우는, 그 인터페이스 포인터에 대해서 AddRef 를 호출해, 글로벌 변수를 할당한다.

2. 디폴트 액션 맵의 취득

디바이스의 디폴트 액션 맵을 취득하려면 ,IDirectInputDevice8::BuildActionMap 를 호출한다. Microsoft® DirectInput® 는,DIACTIONFORMAT 구조체로 지정된 가상 컨트롤의 리스트를 꺼내, 이러한 컨트롤을 물리 디바이스 오브젝트에 맵 하려고 한다. 결과는 같은 구조체에 돌려주어진다. 각각의 DIACTION 요소의 dwHow 멤버를 확인해, 컨트롤이 정상적으로 맵 되었는지 어떠했는지를 조사할 필요가 있다. 정상적이면, 유저에 의한 구성이나 디바이스 메이커에 의한 구성 등, 오브젝트의 선택에 어떠한 기준이 사용되었는지를 밝혀낼 수도 있다.

3. 액션 맵에의 변경

이 시점에서, 디폴트 매핑을 변경할 수 있다. 다만, 변경은 추천 되지 않는다. DIACTION 구조체의 dwSemantic 멤버를 검증해, 어느 디바이스 오브젝트가 액션에 맵 되었는지를 확인하면(자), 맵의 값을 변경할 수 있다. 예를 들어, DIJOFS_BUTTON9 에 맵 되고 있는 액션을, 방아쇠 버튼에 맵 다시 하고 싶은 경우, 액션 맵을 적용하기 전에, 이 값을 DIJOFS_BUTTON0 로 변경한다.

4. 액션 맵의 적용

DIACTIONFORMAT 구조체에 포함되는 디바이스의 매핑이 적절한 것을 확인하면(자),IDirectInputDevice8::SetActionMap 를 호출한다. 각각의 DIACTION 구조체의 uAppData 멤버에 할당한 값은, 이 시점에서,dwSemantic 멤버로 지정된 컨트롤에 바인드 된다. 이것은 다음에 특정의 디바이스 오브젝트에 바인드 된다.

5. 복수 디바이스의 매핑

스텝 1 에서 4 까지를, 어플리케이션으로 사용하는 각각의 디바이스에 대해서 실행한다. 액션을 죠이스틱과 키보드의 양쪽 모두에 맵 하면 하자. 레이싱 게임의 예로, 게임에 eB_DRIVERVIEW 로서 정의된 액션은, DIACTION 배열의 다음의 요소로 키보드의 키에 맵 되었다.

{eB_DRIVERVIEW, DIKEYBOARD_1, "Driver View", },

이 예에서는, 키보드 이외의 디바이스에 대해서 BuildActionMap 가 불려 가면(자), 그 요소의 DIACTION 구조체의 lHow 멤버가 DIAH_UNMAPPED 로 설정된다. 각 디바이스가 순서에 열거되는데 따라, DIAH_UNMAPPED 이외의 값이 돌려주어질 때까지,lHow 멤버의 검증을 계속한다. 이것은, 현재 맵 되고 있는 대상의 디바이스가 키보드이며, 액션이 요구된 키에 정상적으로 맵 된 것을 나타낸다.

정상적으로 맵 된 액션도, 다른 디바이스에 맵 할 수 있다. 이 예에서는, eB_UPSHIFT 가 다음과 같이 2 개의 DIACTION 구조체로 설정된다.

{eB_UPSHIFT, DIBUTTON_DRIVINGR_SHIFTUP, 0, "Upshift", },
...
{eB_UPSHIFT, DIKEYBOARD_PRIOR,          0, "Upshift", },

디바이스가 열거되는데 따라, eB_UPSHIFT 액션은 1 개 이상의 죠이스틱이나 그 외의 게임 콘트롤러의 적절한 버튼에 맵 되어 다음에 키보드의 키에 다시 맵 된다.

6. 구성의 표시

유저에게 디바이스에의 액션의 맵 상황을 나타내려면 , DICD_DEFAULT 플래그를 IDirectInput8::ConfigureDevices 에 건네준다. 다음의 그림에 나타내도록(듯이), 디바이스의 매핑도를 포함한 프로퍼티 시트가, 표시 전용 모드로 표시된다. 이미지를 표시하는 메카니즘의 상세한 것에 대하여는, 「액션 매핑의 사용법」의 튜토리얼을 참조할것.

디바이스 메이커로부터 디바이스 이미지가 제공되어 있지 않은 경우, 매핑은 다음의 그림과 같이 텍스트 모드로 표시된다.

주 : Microsoft® Windows® 키는, 어플리케이션의 협조 레벨로 배타 협조 레벨을 통해 수동적으로, 또는 DISCL_NOWINKEY 플래그를 사용해 능동적으로 무효로 하는 경우에서도, 디폴트의 액션 매핑 UI 가 표시되고 있는 동안은 액티브하게 된다.

프로퍼티 시트에 대한 상세 정보는, 「디바이스의 유저 구성」을 참조할것.


디바이스의 유저 구성

Microsoft® DirectInput® 에는, 어플리케이션으로부터 프로퍼티 시트를 호출하는 기능이 있다. 이것에 의해, 유저는 디바이스를 그 어플리케이션용으로 구성해, 현재의 구성을 볼 수가 있다. 디바이스 메이커의 대응에 따라서는, 이 프로퍼티 시트를 다양한 뷰로 표시할 수 있다.

유저 구성을 유효하게 하려면 , 목적의 매핑을 기술한 DIACTIONFORMAT 구조체에의 포인터를 포함한 DICONFIGUREDEVICESPARAMS 구조체를, DICD_EDIT 플래그와 함께 IDirectInput8::ConfigureDevices 메소드에 건네준다. 보통, 이 처리는, 어플리케이션으로 사용되는 모든 디바이스에 대해서 IDirectInputDevice8::BuildActionMap 를 호출한 다음에 실시한다.

다음의 그림은, 편집 모드의 전형적인 프로퍼티 시트를 나타내고 있다.

디바이스 메이커로부터 디바이스 이미지가 제공되어 있지 않은 경우, 매핑은 다음의 그림과 같이 텍스트 모드로 표시된다.

주 : Microsoft® Windows® 키는, 어플리케이션의 협조 레벨로 배타 협조 레벨을 통해 수동적으로, 또는 DISCL_NOWINKEY 플래그를 사용해 능동적으로 무효로 하는 경우에서도, 디폴트의 액션 매핑 UI 가 표시되고 있는 동안은 액티브하게 된다.

디바이스의 프로퍼티 페이지에는, 각 DIACTION 구조체의 lptszActionName 멤버로 지정된 등록명의 리스트가 표시된다. 디바이스에 대해서 이미 BuildActionMap 를 호출하고 있는 경우, 프로퍼티 페이지에서는, 디바이스의 이미지상에, 액션이 맵 된 디바이스 오브젝트를 가리키는 선과 콜 아웃으로서 이러한 이름도 표시된다.

이것에 의해, 유저는 우선 컨트롤을 선택해, 다음에 메뉴로부터 액션을 선택해, 게임의 액션을 다시 할당할 수가 있다. 유저가 프로퍼티 시트를 닫으면(자), 메소드가 돌아가, 건네준 DIACTIONFORMAT 구조체로 변경 내용이 저장 된다. 그 후, 같은 구조체를 IDirectInputDevice8::SetActionMap 에 건네주면(자), 새로운 매핑 설정을 이행 할 수가 있다.


액션 데이터의 취득

액션을 맵 한 디바이스로부터 버퍼 데이터를 취득하려면 , 맵되어 있지 않은 디바이스의 경우와 같게,IDirectInputDevice8::GetDeviceData 를 호출한다. 다만, DIDEVICEOBJECTDATA 구조체의 dwOfs 멤버를 검증하는 것으로 디바이스 오브젝트를 식별하는 것이 아니라,uAppData 멤버로부터 오브젝트에 관련지을 수 있었던 액션을 취득한다. 이것은,DIACTION 구조 체내의 디바이스에 건네준 것과 같은 값이다. 이 값에는, 단순한 식별자나, 액션의 처리를 목적으로 한 함수에의 포인터를 사용할 수 있다.

액션은 복수의 디바이스에의 관련짓고가 가능한 것으로 주의 해야 한다. 양쪽 모두의 디바이스로부터 별개에 데이터를 취득할 필요가 있지만, 데이터를 어디에서 취득할까에 관계없이, 같은 루틴을 사용해 데이터를 처리할 수 있다.

다음의 샘플 코드는, 드라이빙 시뮬레이션의 게임 루프의 일부로 한다. 여기에서는,g_lpIdiDevices 배열내의 모든 디바이스로부터 데이터를 취득한다. 이 배열에는 g_nDevices 요소가 저장 되고 있다.

for (int iDevice = 0x0; iDevice < g_nDevices; iDevice++)
{
    DIDEVICEOBJECTDATA didod;
    DWORD dwObjCount = 1;

    // 데이터의 유무를 디바이스에 폴링 한다.
    g_lpDiDevices[iDevice]->Poll();

    // 데이터를 취득한다.
    g_lpDiDevices[iDevice]->GetDeviceData( sizeof(didod),
                                           &didod,
                                           &dwObjCount, 0 );

    // 액션을 처리한다. 어느 디바이스로부터 돌려주어졌는가는 묻지 않는다.
    switch(didod.uAppData)
    {
        case eA_STEER:
            SteerCar(didod.dwData);
            break;
        case eB_UPSHIFT
            if (didod.dwData & 0x80) ShiftGears(UPSHIFT);
            break;
        .
        .
        .

        default:
            break;
    }
}

주 : DIAXIS_DRIVINGR_STEER 또는 DIAXIS_SPACESIM_LATERAL 등의 특정의 장르의 축정수는, 절대적인 죠이스틱 데이터에 대해서 사용된다. 액션 맵퍼는, 이 가상 컨트롤을 절대 데이터를 돌려주는 디바이스 오브젝트에 맵 한다. 어플리케이션에서는, 이 디바이스로부터 돌려주어진 데이터를 적절히 처리할 필요가 있다. 다만, DIMOUSE_XAXIS 등의 디바이스 정수는, 상대 데이터를 돌려주는 것이 상정되고 있다.

데이터를 취득 하면나무는, 1 개의 데바이스오브제크가 다른 디바이스 오브젝트의 데이터를 덧쓰기하지 않게, 각 데이터 소스를 개별적으로 처리할 필요가 있다. 예를 들어, 방향을 제어하는 다음의 DIACTION 구조체는 액션 맵으로 사용된다.

{INPUT_LEFTRIGHT_ABS_AXIS, DIAXIS_SPACESIM_LATERAL, 0,   _T("Turn"),},
{INPUT_LEFTRIGHT_REL_AXIS, DIMOUSE_XAXIS,           0,   _T("Turn"),},
{INPUT_TURNLEFT,           DIKEYBOARD_LEFT,     0,  _T("Turn left"),},
{INPUT_TURNRIGHT,          DIKEYBOARD_RIGHT,    0, _T("Turn right"),},

어플리케이션의 입력 루프에서는, 다음의 case 스테이트먼트로 이러한 액션의 데이터를 처리한다.

switch (adod[j]. uAppData)
{
    case INPUT_LEFTRIGHT_ABS_AXIS:
        g_dwAbsLR = adod[j]. dwData
        break;
    case INPUT_LEFTRIGHT_REL_AXIS:
        g_dwRelLR = adod[j]. dwData;
        break;
    case INPUT_TURNLEFT:
        g_bLeft = (adod[j]. dwData ! = 0);
        break;
    case INPUT_TURNRIGHT:
        g_bRight = (adod[j]. dwData ! = 0)
        break;
}

데이터 소스의 할당해에 관해서, 모든 데이터 소스가 1 개의 범용의 "turn" 변수에 할당할 수 있는 것이 아니라, 각 데이터 소스가 개별의 변수에 할당할 수 있는 것에 주의 해야 한다. 데이터 소스가 범용의 변수를 공유하는 경우, 왼쪽 화살표 (←) 키를 누른 채로 죠이스틱을 이동 하면, 키보드 정보가 없어진다. 이것은, 죠이스틱 데이터가 범용의 변수를 덧쓰기하기 때문이다.

변수에 대해서와 같게, 데이터에 대해서도 다양한 처리 방법이 있다. 어떠한 처리 방법을 사용하는 경우에서도, 예기치 않은 정보의 손실을 피하기 위해서(때문에) 데이터의 처리에는 주의할 필요가 있다.


개발중의 파일의 관리

개발 사이클에 대해서는, 빈번한 액션 맵의 변경, Microsoft® DirectX® 의 재인스톨, 복수 유저, 및 그 외 보통의 개발 상황에 의해, 사용하지 않는다 . ini 파일이나 일자의 낡다 . ini 파일이 누적하는 경우가 있다. 이러한 파일이 원인으로, 예기치 않은 매핑이나 "최신" 리포트 (DIEDBS_RECENTDEVICE)가, 이 값이 돌려주어지는 것을 예기 하고 있지 않는 디바이스에 대해서 돌려주어질 가능성이 있다. 그 때문에, 사용하지 않는다 . ini 파일을 가끔 삭제하는 것이 바람직하다. 이러한 파일은, C:\Program Files\Common Files\DirectX\DirectInput\User Maps 에 있다.

주 : 여기에 나타낸 추천 순서는, 개발 사이클에 대해, 개발 환경을 최신 상태로 하기 위해서(때문에) 수동으로 실행해야 할 순서이다. 유저의 우선 설정을 잃을 가능성이 있기 (위해)때문에, 출하 어플리케이션에서는 결코 유저 맵을 삭제해서는 안 된다.


force feedback

force feedback란, 입출력 디바이스 (예를 들어, 죠이스틱에 짜넣어지고 있는 모터)에 푸쉬 혹은 저항을 생성하는 것이다. Microsoft® DirectInput® 에서는, 호환성이 있는 드라이버를 가지는 디바이스에 force feedback 이펙트를 생성할 수가 있다.

이하의 주제에서는, force feedback의 개념을 소개한다.

  • force feedback의 기본 개념
  • 이펙트의 열거
  • 파일로부터의 이펙트의 read
  • 지원 되는 이펙트에 대한 정보
  • 이펙트의 생성
  • 이펙트의 방향
  • 포락선과 오프셋(offset)
  • 이펙트의 재생
  • 이펙트의 다운로드와 언로드
  • 이펙트의 변경
  • 게인
  • force feedback 상태
  • 이펙트 오브젝트의 열거
  • 이펙트의 타입


force feedback의 기본 개념

force feedback의 쳐 특수한 인스턴스를 "이펙트" 라고 말해, 푸쉬나 저항을 "포스" 라고 말한다. 많은 이펙트는, 이하의 카테고리의 어느 쪽인가에 속한다.

  • 정수 포스 － 단일 방향의 일정한 포스
  • 경사 포스 － 일정한 비율로 크기가 증가 또는 감소하는 포스
  • 주기적 이펙트 － 정의된 파형 패턴으로 변화하는 포스.
  • 조건 － 축으로 따른 움직임 또는 동작에의 반응. 예를 들어, 죠이스틱의 동작에 대해서 저항을 낳는 마찰 이펙트나, 죠이스틱이 있는 위치로부터 작동된 다음에, 스틱을 그 위치에 되돌리려고 하는 스프링 이펙트이다.

포스의 강함을 "매그니튜드" 라고 한다. 매그니튜드는, 0 (포스 없음)에서 10,000 (디바이스의 최대 포스로, C/C++ 및 Visual Basic 의 경우, DI_FFNOMINALMAX 로서 정의되고 있다)의 범위의 단위로 측정된다. 부의 값은, 반대의 방향에 있는 포스를 나타낸다. 매그니튜드는 비례적인 단위이다. 예를 들어, 포스 10,000 은 포스 5,000 의 2 배의 크기이다.

경사 포스에는, 초기 매그니튜드와 종기 매그니튜드가 있다. 주기적 이펙트에서는, 기본적 매그니튜드는 물결의 버텍스에서의 포스가 된다.

포스의 "방향" 은 포스가 올 방향이다. 어느 축위에의정의 포스는 정으로부터 부 쪽에 누르는 힘이다.

또, 이펙트에는 "계속 시간" 이 있다. 이것은, 마이크로 세컨드 단위로 측정된다. 주기적 이펙트에는,"주기" 또는 1 사이클의 계속 시간이 있어, 이것들도 마이크로 세컨드 단위로 측정된다. 주기적 이펙트의 "국면" 이란, 재생 시작 개소의 물결에 따라 존재하는 포인트이다.

다음의 그림은, 매그니튜드 5,000, 즉 디바이스의 최대 포스의 반에서의 톱니 주기적 이펙트를 나타낸다. 수평축은 이펙트의 계속 시간을, 수직축은 매그니튜드를 각각 나타낸다. 중앙선보다 위에의 포인트는, 이펙트에 정의된 방향에 있어서의 정의 포스를, 아래의 포인트는 부의 포스, 즉 반대 방향의 포스를 나타낸다.

한층 더 포스는,"포락선" 에 의해 형성된다. 포락선은,"어택값" 과 "페이드값" 을 정의한다. 어택값과 페이드값에 의해, 시점과 종점간의 이펙트의 매그니튜드가 변화한다. 어택과 페이드에는 계속 시간이 있다. 계속 시간은, 매그니튜드가 "보관 유지값" 에 도달하는데 필요한 시간, 또는 보관 유지값으로부터 빗나가는데 필요로 하는 시간을 결정한다. 보관 유지값이란, 이펙트의 중간부의 매그니튜드이다.

다음의 그림은, 포락선을 나타내고 있다. 어택 레벨은 8,000, 페이드 레벨은 1,000 으로 설정되어 있다. 보관 유지 레벨은, 이 포락선을 적용한 포스의 기본적 매그니튜드에 의해 정의된다. 이 예에서는 보관 유지 레벨은 5,000 이다. 이 케이스에서는, 어택이 보관 유지보다 큰 것에 주의 해야 한다. 이것은, 이펙트의 초기에 강한 킥을 주게 된다. 어택 레벨과 페이드 레벨의 양쪽 모두가 보관 유지 레벨보다 큰 일도 작은 일도 있다.

다음의 그림은, 최초의 그림의 주기적 이펙트에 포락선을 적용한 결과를 나타낸다. 매그니튜드의 부측에서는, 포락선이 거울 사본이 되어 있다. 어택값 8,000 이 의미하는 것은, 한편의 방향의 포스의 초기 매그니튜드가, 최대 포스의 80% 가 된다고 하는 것이다.

주기적 이펙트와 조건은, 모두,"오프셋(offset)" 의 추가에 의해도 변경할 수가 있다. 오프셋(offset)란, 파형을 기본 레벨보다 위 또는 아래에 쉬프트 하는 양을 정의하는 것이다. 톱니의 예에 정의 오프셋(offset)를 적용한 실제의 이펙트에서는, 정의 포스를 강하게 해 부의 포스를 약하게 하게 된다. 즉, 포스의 파형에서는, 한방향에의 물결의 버텍스가, 한편 향에의 물결의 버텍스보다 높아진다.

또, 이펙트의 전체적 매그니튜드는,"게인" 에 의해 증감 가능하다. 게인이란, 오디오에 있어서의 음량 컨트롤에 유사하고 있다. 단일의 게인값을 1 개의 디바이스의 모든 이펙트에 적용할 수 있으므로, 이것을 사용해, 여러가지 하드웨어에 대해서 포스를 강하게 하거나 약하게 하거나 하는 보정을 더할 수가 있다. 또, 유저의 좋아해에 대응할 수도 있다.


이펙트의 열거

IDirectInputDevice8::EnumEffects 메소드는, 다양한 종류의 이펙트에 관해서, 디바이스로 제공되는 지원에 대한 정보를 돌려준다.

"지원 되는 이펙트" 와 "생성되는 이펙트" ("이펙트 오브젝트")의 양자를 구별하는 것이 중요하다. 지원 되는 이펙트는, 디바이스를 재생할 수 있는 정수 포스등의 기본적인 타입이다. 그러나, 정수 포스 자체에는, 매그니튜드, 방향, 계속 시간,어택 또는페이드등의 프로퍼티가 전혀 없다. 이러한 프로퍼티는,포락선이 있는 미가공의 이펙트 타입을 형성할까 DIEFFECT 구조체의 값을 설정해, 어플리케이션으로 특정의 이펙트 오브젝트를 생성할 경우에 설정된다. 지원 되는 이펙트는, 각각 다른 파라미터를 가지는 많은 이펙트 오브젝트에 의해 나타낼 수가 있다. 예를 들어, 각각 다른 계속 시간, 매그니튜드 및 방향을 가지는 복수의 정수 포스에 의해 나타낼 수가 있다.

생성된 이펙트의 열거에 대해서는, 「이펙트 오브젝트의 열거」를 참조할것.

다른 Microsoft® DirectInput® 열거와 같게,IDirectInputDevice8::EnumEffects 메소드에는 콜백 함수가 필요하다. 문서에서는 이 함수는 플레이스홀더명의 DIEnumEffectsCallback 로 나타내지고 있지만, 좋아하는 이름을 붙일 수가 있다. 이 함수는, 열거되는 이펙트 마다 불려 간다. 이 함수내에서는, 각각의 이펙트에 대한 GUID 를 취득할 수 있어 하드웨어 지원의 범위에 대한 정보를 취득할 수 있어 게다가 1 개(살) 또는 그 이상의 이펙트 오브젝트를 생성해, 그 오브젝트의 메소드를 사용해 이펙트를 조작할 수가 있다.

이하의 예는, 열거를 시작 한다. g_lpdid 는, 디바이스의 IDirectInputDevice8 인터페이스에의 초기화된 포인터로 한다.

HRESULT hr = g_lpdid->EnumEffects(&DIEnumEffectsCallback,
        g_lpdid, DIEFT_ALL);

콜백의 골격을, 이하의 코드에 나타낸다. 이 콜백 함수의 pvRef 파라미터는 32 비트의 임의의 값을 취할 수가 있지만, 이 경우, 이 파라미터는 디바이스 인터페이스에의 포인터 (전의 예의 글로벌 g_lpdid)이며, 디바이스가 지원 하는 이펙트에 대한 정보의 취득과 이펙트 오브젝트의 생성에 사용된다.

BOOL CALLBACK DIEnumEffectsCallback(LPCDIEFFECTINFO pdei,
                                LPVOID pvRef)
{
    HRESULT              hr;
    LPDIRECTINPUTDEVICE8 lpdid = (LPDIRECTINPUTDEVICE8) pvRef;
// 호출 디바이스에의 포인터.
    LPDIRECTINPUTEFFECT  lpdiEffect;      // 생성된 이펙트에의 포인터.
    DIEFFECT             diEffect;        // 생성된 이펙트용의 파라미터.
    DICONSTANTFORCE      diConstantForce; // 타입 고유 파라미터.

    if (DIEFT_GETTYPE(pdei->dwEffType) == DIEFT_CONSTANTFORCE)
    {
       /* 이펙트 타입 (pdei 로부터)의 지원 정보를
추출해, 거기에 응해 이펙트를 적응시키는 것
하지만 할 수 있다. 예를 들어, 이 디바이스는, 이 타입
의 이펙트에서는 포락선을 지원 하지 않는다.  */
       .
       .
       .
       // 1 개(살) 또는 그 이상의 정수 포스 이펙트를 생성한다.
       // 각각 붙어, DICONSTANTFORCE 와
       // DIEFFECT 구조체를 초기화해야 한다.
       .
       .
       .
        hr = lpdid->CreateEffect(pdei->guid,
                                &diEffect,
                                &lpdiEffect,
                                NULL);
       .
       .
       .
    }
    // 다른 타입의 이펙트에 대해서도 같이.
   .
   .
   .

    return DIENUM_CONTINUE;
}  // 콜백의 종료.

이펙트 생성의 상세한 예에 대해, 및 이펙트를 초기화하는 방법의 상세한 것에 대하여는, 「이펙트의 생성」을 참조할것.


파일로부터의 이펙트의 read

Microsoft® DirectX® SDK 로 제공되는 Force Editor , 또는 같은 파일 포맷을 사용하는 다른 어플리케이션을 사용해, 이펙트를 디자인해, 파일에 보존할 수가 있다. 실행시에 이러한 이펙트를 읽어들이는 것으로, 임의의 어플리케이션으로 사용할 수가 있다.

이펙트를 읽어들이려면 ,IDirectInputDevice8::EnumEffectsInFile 메소드를 호출한다. 디폴트에서는, 열거는 표준의 Microsoft DirectInput® 이펙트로 한정되지만, DIFEF_INCLUDENONSTANDARD 플래그를 설정하는 것으로, 이외의 이펙트를 열거할 수 있다. 또, DIFEF_MODIFYIFNEEDED 플래그를 설정 하면, 필요에 따라서, 이펙트가 디바이스에 대해서 작용하도록(듯이), 각 이펙트의 파라미터의 변경을 DirectInput 에 지시할 수가 있다(예를 들어, 2 개의 축으로 대해 생성 된 이펙트를, 단일축의 차의 핸들에 대해서 작용시킬 수가 있다).

다음의 샘플 코드에서는, 최초의 3 개의 표준 이펙트가 파일로부터 읽혀 DirectInputEffect 오브젝트로서 생성 된다.

// g_lpdid 는, force feedback 디바이스에의 유효한
// IDirectInputDevice7 포인터이다.

// 이펙트 포인터의 배열은, 글로벌하게 선언된다.
LPDIRECTINPUTEFFECT pEff[3];
.
.
.
g_lpdid->EnumEffectsInFile("FEdit1.ffe",
                            EnumEffectsInFileProc,
                            NULL,
                            DIFEF_MODIFYIFNEEDED);
.
.
.

이하의 콜백 함수는, DIENUM_STOP 가 돌려주어질 때까지, 이펙트 파일내의 이펙트 마다 불려 간다. DIFEF_MODIFYIFNEEDED 플래그가 건네받았기 때문에, 이펙트 파라미터는 lpdife->lpDiEffect 로 변경되는 것에 주의 해야 한다. 이와 같이 파라미터를 수정한 콜백에 의해, 이펙트가 생성된다.

BOOL CALLBACK EnumEffectsInFileProc(LPCDIFILEEFFECT lpdife,
        LPVOID pvRef)

{
    HRESULT     hr;
    static int  i;

    hr = g_lpdid->CreateEffect(lpdife->GuidEffect,
                               lpdife->lpDiEffect,
                               &pEff[i],
                               NULL);
    if (FAILED(hr))
    {
        // 에러 처리.
    }
    if (++i > 2) return DIENUM_STOP;
    else return DIENUM_CONTINUE;
}

Microsoft® DirectX® SDK 로 제공되는 Force Editor , 또는 같은 파일 포맷을 사용하는 다른 어플리케이션을 사용해, 이펙트를 디자인해, 파일에 보존할 수가 있다. 실행시에 이러한 이펙트를 읽어들이는 것으로, 임의의 어플리케이션으로 사용할 수가 있다.

이펙트를 읽어들이려면 , DirectInputDevice8.CreateEffectFromFile 메소드를 호출한다. 그 후, 생성되는 DirectInputEffect 오브젝트를 보통 대로 사용할 수 있다.


지원 되는 이펙트에 대한 정보

IDirectInputDevice8::GetEffectInfo 메소드를 사용하면(자), GUID 가 판명하고 있는 이펙트에 대해, 그 디바이스의 지원 정보를 취득할 수 있다. 이 메소드는,DIEFFECTINFO 구조체로 돌려주어지는 정보와 같은 정보를 열거중에 취득한다. 상세한 것에 대하여는, 「이펙트의 열거」를 참조할것.

다음의 샘플 코드는,EffectGuid 변수에 GUID 가 저장 되고 있는 이펙트에 관한 정보를 취득해, 이펙트를 정지 또는 재기동하지 않고 이펙트의 방향을 변경할 수 있을지 어떨지를 조사한다.

DIEFFECTINFO diEffectInfo;
diEffectInfo.dwSize = sizeof(DIEFFECTINFO);
g_lpdid->GetEffectInfo(&diEffectInfo, EffectGuid);
if (diEffectInfo.dwDynamicParams & DIEP_DIRECTION)
{
  // 파라미터는 동적으로 리셋 할 수 있다.
}


이펙트의 생성

이펙트 오브젝트를 생성하려면 ,IDirectInputDevice8::CreateEffect 메소드를 사용한다. 다음의 샘플 코드로,g_lpdid 는 인터페이스의 인스턴스를 가리키고 있다. 이 예에서는, 반초간에 전력으로 죠이스틱을 유저로부터 멀어질 방향에 당긴다고 한다, 매우 단순한 이펙트가 생성된다.

HRESULT  hr;
LPDIRECTINPUTEFFECT lpdiEffect;  // 생성되는 이펙트에의 포인터를 받는다.
DIEFFECT diEffect;               // 생성되는 이펙트용의 파라미터.

DWORD    dwAxes[2] = { DIJOFS_X, DIJOFS_Y };
LONG     lDirection[2] = { 18000, 0 };

DICONSTANTFORCE diConstantForce;

diConstantForce.lMagnitude = DI_FFNOMINALMAX;   // 최대 포스.

diEffect.dwSize          = sizeof(DIEFFECT);
diEffect.dwFlags         = DIEFF_POLAR | DIEFF_OBJECTOFFSETS;
diEffect.dwDuration      = (DWORD)(0.5 * DI_SECONDS);
diEffect.dwSamplePeriod  = 0;                 // 디폴트 설정.
diEffect.dwGain          = DI_FFNOMINALMAX;   // 스케일링 없음.
diEffect.dwTriggerButton = DIEB_NOTRIGGER;    // 버튼 응답은 아니다.
diEffect.dwTriggerRepeatInterval = 0;         // 이용할 수 없다.
diEffect.cAxes                   = 2;
diEffect.rgdwAxes                = &dwAxes[0];
diEffect.rglDirection            = &lDirection[0];
diEffect.lpEnvelope              = NULL;
diEffect.cbTypeSpecificParams    = sizeof(DICONSTANTFORCE);
diEffect.lpvTypeSpecificParams   = &diConstantForce;

hr = g_lpdid->CreateEffect(GUID_ConstantForce,
                           &diEffect,
                           &lpdiEffect,
                           NULL);

이 메소드 호출에서는, 최초의 파라미터는, 생성되는 이펙트에 관련지을 수 있었던 지원 되는 이펙트를 나타낸다. 이 예에서는, Dinput.h 로 정의 끝난 GUID 가운데 1 개를 사용하고 있다. 정의 끝난 GUID 를 사용하는 경우, 디바이스가 이 이펙트를 지원 하지 않으면 호출은 실패한다.

제 2 의 파라미터는,DIEFFECT 구조체로 지정되고 있는 파라미터를 설정한다.

제 3 의 파라미터는, 호출이 성공했을 경우에, 이펙트 오브젝트에의 포인터를 받는다.

DIEFF_POLAR 플래그는, 포스의 방향으로 사용하는 좌표의 종류를 지정한다 ( 「이펙트의 방향」을 참조할것). 이 플래그는 DIEFF_OBJECTOFFSETS 와 짜 합쳐진다. 이것은, 다른 멤버로 사용되는 버튼이나 축도, 이 디바이스의 DIDATAFORMAT 구조체 중(안)에서 오프셋(offset)에 의해 식별된다, 라고 하는 것을 나타낸다. 이 대신에 DIEFF_OBJECTIDS 플래그를 사용할 수가 있다. 이 플래그는, 오브젝트가 IDirectInputDevice8::EnumObjects 메소드로 열거되었을 때, 그 오브젝트에 대해서 돌려주어지는 DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버에 의해 버튼과 축이 식별된다, 라고 하는 것을 의미하고 있다.

DIEFFECT 구조체의 멤버의 상세한 것에 대하여는, 「이펙트의 방향」을 참조할것.

디바이스가 만배는 아니고, 배타 협조 레벨로 취득되었다면, 이펙트는 생성시에 디바이스에 자동적으로 다운로드된다.


이펙트의 방향

1 개(살) 또는 그 이상의 축으로 대해 방향을 정의할 수가 있다. 마우스와 죠이스틱의 경우와 같게, x 축은 왼쪽에서 오른쪽으로 증가해, y 축은 멀리서 가까이증가한다. 3 차원 디바이스에서는, z 축은 윗쪽에서 하부로 증가한다.

이펙트의 방향은, 이펙트가 올 방향이다. y 축의 부측에 따른 방향에서의 이펙트는, 스틱을 y 축의 정측에 따라 (유저를 향해) 누르려고 한다. 이펙트를 지우기 위해서(때문에) 유저가 스틱을 좌방향에 누르지 않으면 안 되는 경우, 이 이펙트는 「왼쪽」방향이다. 즉, 이 이펙트는 x 축의 부측에 있다.

방향은 "극히" 좌표,"구(공)장" 좌표, 또는,"데카르트" 좌표로 나타낼 수가 있다.

극좌표는, 이펙트에 대해서 설정된 제로 포인트 (진북)로부터 시계회전에, 열매 각도의 100 배의 단일 각도로 나타내진다. 보통 이것은 부측의 y 축, 즉, 유저로부터 멀어질 방향이다. 따라서, 극좌표 9,000 의 이펙트는 보통, 동쪽향 즉 유저의 우측의 방향을 가진다. 이 이펙트를 지우려면 , 유저는 우측에 힘을 더하지 않으면 안 된다.

구(공)장 좌표도 열매 각도의 100 배로 나타내지지만, 2 개(살) 또는 그 이상의 각도를 포함하는 일이 있다. 각각의 각도에 대해, 방향은 다음의 축의 정방향에 회전한다. 3 차원 디바이스의 경우는, 제 1 의 각도는, 보통정측의 x 축으로부터 정측의 y 축으로 향해 (동쪽으로부터 시계회전에) 회전해, 제 2 의 각도는 정측의 z 축으로 향해 (하부에) 회전한다. 따라서, 방향이 (0, 0)의 포스는 유저의 우측의 방향이며, 궤면과 평행이 된다. 제 1 의 각도가 27,000 으로 제 2 의 각도가 4,500 의 방향과는, 유저로부터 똑바로 떨어지면서 (동쪽으로부터 시계회전에 270 번), 마루로 향할 (궤면으로부터 하부에 45 번의 각도) 방향이다. 이 방향의 포스를 지우려면 , 전방에 밀어 내면서 하부에 눌러 내리지 않으면 안 된다.

데카르트 좌표는 3 차원 벡터를 닮아 있다. 중심을 시점 (0,0)으로 하는 그래프 용지에 직선을 그으면(자), 그 직선의 방향은, 시점으로부터의 거리와는 관계없이, 교점의 임의의 좌표에 의해 정의할 수가 있다. 따라서, 방향 (1, -2)과 방향 (5, -10)은 완전히 같은 것된다.

주 : force feedback 이펙트의 생성에 사용하는 좌표는 방향만을 정의해, 매그니튜드나 거리는 정의하지 않는다.

이펙트를 생성 또는 변경 하면나무는,DIEFFECT 구조체의 cAxes,rgdwAxes, 및 rglDirection 멤버를 사용해, 포스의 방향을 지정한다.

cAxes 멤버는, 이펙트에 포함되는 축의 수를 지정한다. 이것은, 다음에 계속되는 2 개의 멤버가 가리키는 배열의 요소의 수이기도 하다.

rgdwAxes 가 가리키는 배열에 의해, 이펙트가 적용되는 축이 식별된다. DIEFF_OBJECTOFFSETS 플래그가 설정되어 있으면, 축은 데이터 형식 구조 체내의 오프셋(offset)에 의해 지정된다. 이러한 오프셋(offset)는 DIJOFS_* 를 사용해 매우 간단하게 지정된다 (이러한 값에 대해서는, 「죠이스틱 디바이스 정수」를 참조할것).

마지막으로,rglDirection 멤버는 포스의 방향을 지정한다.

주 : cAxes 및 rgdwAxes 멤버는 한 번 설정 하면, 변경할 수 없다. 이펙트는 항상 동일한 축리스트를 가진다.

데카르트 좌표, 극좌표, 구(공)장 좌표의 어떤 것을 사용하는 경우에서도,rgdwAxes 가 가리키는 배열에 있는 축의 수와 완전히 같은 수의 요소를 rglDirection 에 준비해야 한다.

극좌표 시스템에서는, 「북쪽 (제로도)」는 벡터 (0, -1) 상에 있어, 이 벡터의 요소는 rgdwAxes 가 가리키는 축리스트의 요소에 대응한다. 보통은 이러한 축은 x 와 y 이므로, 북쪽은 그대로 y 축의 부측의 방향이 된다. 즉, 유저로부터 멀어질 방향이 된다. rglDirection 의 마지막 요소는 제로가 아니면 안된다.

「이펙트의 생성」에서의 예에서는,2 차원 포스의 방향은 극좌표에서 정의된다. 이 예에서는 포스는 남방향, 즉 유저의 방향으로부터 와 있으므로, 유저가 포스를 지우려면 스틱을 앞에 끌어 들이지 않으면 안 된다. 남쪽향은 북쪽으로부터 시계회전에 180 번이며, 다음과 같이 할당할 수가 있다

LONG  lDirection[2] = { 18000, 0 };

보다 명확하게 하기 위해서, 할당은 다음과 같이 나타낼 수도 있다.

LONG  lDirection[2] = { 180 * DI_DEGREES, 0 };

구(공)장 좌표에 대해서는, 3 축디바이스로 작업하고 있으면(자) 가정했을 경우, 같은 방향은 다음과 같이 할당할 수 있다.

LONG  lDirection[3] = { 90 * DI_DEGREES, 0, 0 }

제 1 의 각도는, 방향 (1, 0)으로부터 방향 (0,1)에 회전한 열매 각도의 100 배로 계측 된다. 제 2 의 각도는 (0, 0, 1)에 회전하는 열매 각도의 100 배로 계측 된다. 이 경우도, 벡터 표기법의 요소는 rgdwAxes 멤버가 가리키는 배열의 요소에 대응한다. 이 배열의 요소가, 순서에 x 축, y 축, 및 z 축을 나타내면(자) 가정하자. 원점은 x = 1, y = 0 이다, 즉, 유저의 우측에 있다. 회전의 방향은, y 축의 정측 ( 0, 1)을 향한다, 즉, 유저측에, 또는 시계회전으로 향한다. 이 예에 있어서의 포스는, 오른쪽으로부터 시계회전에 90 번이다, 즉, 남방향이다. lDirection 의 제 2 의 요소가 0 이므로, 제 3 축상에서의 회전은 없다.

데카르트 좌표로 이것과 같은 것을 실현하기에는 어떻게 하면 좋을까. dwFlags 멤버의 DIEFF_CARTESIAN 플래그를 사용 하면 가정하면, 다음과 같이 방향을 지정하게 된다.

LONG  lDirection[2] = { 0, 1 };

반복하지만, 이 배열의 요소는 rgdwAxes 가 가리키는 배열에 리스트 되고 있는 축으로 대응하고 있다. 이 예에서는 x 축으로 제로를 설정해, y 축으로 1 을 설정해 있다. 즉, 방향은 직접 y 축의 정측상, 또는 남쪽에 있다.

이펙트의 방향에 대한 이론은, 이해하는 것은 어려울지도 모르지만, 실천해 볼 수 있고 바보든지 용이하게 이해할 수 있다. 샘플 코드가 있으므로, 「이펙트 방향 설정의 실례」를 참조할것.


이펙트 방향 설정의 실례

단일축이펙트

단일축이펙트의 방향의 설정은, 실제로 지정하는 것이 아무것도 없기 때문에, 단순하다. DIEFF_CARTESIAN 플래그를 DIEFFECT 구조체의 dwFlags 멤버로 설정해, 값이 제로의 단일의 LONG 를 가리키는 rglDirection 를 설정한다.

다음의 코드는, x 축이펙트의 방향과 축파라미터를 설정하는 예이다.

DIEFFECT eff;
LONG     lZero  = 0;                       // 방향 없음.
DWORD    dwAxis = DIJOFS_X;                // x 축이펙트.

ZeroMemory(&eff, sizeof(DIEFFECT));
eff.cAxes        = 1;                                     // 1 개의 축.
eff.dwFlags      = DIEFF_CARTESIAN | DIEFF_OBJECTOFFSETS; // 플래그.
eff.rglDirection = &lZero;                                // 방향.
eff.rgdwAxes     = &dwAxis;                         // 이펙트의 축.

극좌표에서의 2 축이펙트

극좌표 2 축이펙트의 방향의 설정은 조금 복잡하다. DIEFF_POLAR 플래그를 dwFlags 로 설정해, 2 개의 LONG 로부터 되는 1 개의 배열을 가리키도록(듯이) rglDirection 를 설정한다. 이렇게 하면(자), 이 배열의 제 1 의 요소가, 이펙트가 올 방향이 된다. 이 배열의 제 2 의 요소는 제로가 아니면 안 된다.

다음의 코드는, 동쪽으로부터 오는 2 축이펙트의 방향과 축파라미터를 설정하는 예이다.

DIEFFECT eff;
LONG     rglDirection[2] = { 90 * DI_DEGREES, 0 };
DWORD    rgdwAxes[2]     = { DIJOFS_X, DIJOFS_Y };   // x 축과 y 축.

ZeroMemory(&eff, sizeof(DIEFFECT));
eff.cAxes        = 2;                                  //  2 개의 축.
eff.dwFlags      = DIEFF_POLAR | DIEFF_OBJECTOFFSETS;  // 플래그.
eff.rglDirection = rglDirection;                       // 방향.
eff.rgdwAxes     = rgdwAxes;                     // 이펙트의 축.

데카르트 좌표에서의 2 축이펙트

데카르트 좌표 2 축이펙트의 방향의 설정은 조금 복잡하다. DIEFF_CARTESIAN 플래그를 dwFlags 로 설정해, 여기에서도, 2 개의 LONG 로부터 되는 1 개의 배열을 가리키도록(듯이) rglDirection 를 설정한다. 이 때의 배열의 제 1 요소는 방향 벡터의 x 좌표로, 제 2 요소는 y 좌표이다.

다음의 코드는, 동쪽으로부터 오는 2 축이펙트의 방향과 축파라미터를 설정하는 예이다

DIEFFECT eff;
LONG     rglDirection[2] = { 1, 0 };            // 정값 x = 동.
DWORD    rgdwAxes[2]     = { DIJOFS_X, DIJOFS_Y };  // x 축과 y 축.

ZeroMemory(&eff, sizeof(DIEFFECT));
eff.cAxes = 2;                                       //  2 개의 축.
eff.dwFlags = DIEFF_CARTESIAN | DIEFF_OBJECTOFFSETS; // 플래그.
eff.rglDirection = rglDirection;                     // 방향.
eff.rgdwAxes = rgdwAxes;                       // 이펙트의 축.


포락선과 오프셋(offset)

포락선 과 오프셋(offset)를 사용해, 몇개의 기본적 매그니튜드를 변경할 수가 있다. 개요에 대해서는, 「force feedback의 기본 개념」을 참조할것.

이펙트의 생성 또는 변경 시에 포락선을 적용하려면 ,DIENVELOPE 구조체를 초기화해, 이 구조체에의 포인터를 DIEFFECT 구조체의 lpEnvelope 멤버로 설정한다.

어느 이펙트가 포락선을 지원 할까를 결정하는 것은 디바이스 드라이버이다. 보통은, 정수 포스, 경사 포스 및 주기적 포스에 포락선을 적용할 수 있지만, 조건에는 적용할 수 없다. 특정의 포스가 포락선을 지원 할지 어떨지를 판정하려면 ,IDirectInputDevice8::GetEffectInfo 메소드를 호출해,DIEFFECTINFO 구조체의 dwStaticParams 멤버에 있는 DIEP_ENVELOPE 플래그를 체크한다.

오프셋(offset)를 적용하려면 ,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 가리키는 DIPERIODIC 구조체 또는 DICONDITION 구조체의 lOffset 멤버를 설정한다. 주기적 이펙트의 경우, 오프셋(offset)의 절대치와 이펙트의 매그니튜드를 더한 값이 DI_FFNOMINALMAX 를 넘어서는 안 된다.

오프셋(offset)를 정수 포스나 경사 포스에 적용할 수 없다. 정수 포스나 경사 포스의 경우, 매그니튜드를 변경하는 것에 의해 같은 이펙트를 발생시킬 수가 있다.


이펙트의 재생

이펙트의 재생을 시작 하는 주된 방법은 2 개 있다. IDirectInputEffect::Start 메소드를 호출해 수동으로 시작 하는 방법과 버튼 압하에의 응답으로 자동적으로 시작 하는 방법이다. DIEP_START 플래그를 지정해 IDirectInputEffect::SetParameters 메소드를 호출하는 것으로 이펙트를 변경할 경우에도, 재생이 시작 한다.

dwIterations 파라미터에 INFINITE 를 건네주면(자),포락선을 적용하면서 이펙트의 재생을 반복시킬 수가 있다. 포락선을 반복하는 일 없이 이펙트를 반복하고 싶을 때 (예를 들어, 최초로 강한 킥을 한 후, 동계를 가라앉힌다라고 하는 경우)는,dwIterations 에 1 을 설정해, 다음에 DIEFFECT 구조체의 dwDuration 멤버에 INFINITE 를 세트 하면 좋다(이것은 IDirectInputDevice8::CreateEffect 메소드에게 건네지는 구조체이다).

주 : 디바이스에 따라서는, 이펙트의 여러 차례의 보간이 불가능해,Start 메소드에의 파라미터 dwIterations 에 값 1 밖에 인정하지 않는 것도 있다. Start 로부터의 반환값을 항상 체크해, 이펙트가 정상적으로 재생되었는지 어떠했는지를 확인해야 한다.

이펙트를 버튼 압하에 할당하려면 ,DIEFFECT 구조체의 dwTriggerButton 멤버를 설정한다. 버튼이 압하되고 있을 때의 재생간에 지연을 더하고 싶다면, 그 지연값을 dwTriggerRepeatInterval 멤버로 설정한다. 이 지연은, 1 개의 재생의 종료로부터 다음의 재생의 시작까지의 간격으로, 마이크로 세컨드 단위로 나타내진다.

주 : 디바이스에 따라서는, 여러 차례의 이펙트를 같은 버튼으로 발생시킬 수가 없는 것도 있다. 2 개(살) 이상의 이펙트를 1 개의 버튼에 할당하면(자), 마지막에 다운로드된 이펙트가, 발생하는 이펙트가 된다. 또, 방아쇠의 반복 간격은 지원되어 있지 않다.

이펙트의 방아쇠 버튼에의 할당을 해제하는데는,IDirectInputEffect::Unload 메소드를 호출하는지, 또는 DIEB_NOTRIGGER 로 설정되어 있는 dwTriggerButton 에, 이 이펙트용의 파라미터를 설정하는지, 어느 쪽인가의 조작을 실시하지 않으면 안 된다.

할당한 이펙트는, 다른 모든 이펙트와 같게, 어플리케이션이 디바이스에의 액세스권을 잃으면(자) 없어진다. 다시 이러한 이펙트를 유효하게 하려면 , 어플리케이션이 디바이스를 재취득 하면 동시에 이러한 이펙트를 다운로드한다. 「이펙트의 다운로드와 언로드」를 참조할것. 이 처리는 방아쇠에 할당하지 않은 이펙트에서는 불필요하다. 왜냐하면, 이런 종류의 이펙트는,Start 메소드가 불려 갈 때는 언제나, 필요에 따라서 자동적으로 다운로드되기 때문이다.

이펙트의 계속 시간이 유한해, 이펙트가 Start 메소드에의 호출에 의해 시작 하는 경우, 계속 시간이 지나면(자) 이펙트의 재생은 종료한다. 이펙트의 계속 시간이 INFINITE 로 설정되어 있었을 경우, 재생이 종료하는 것은,IDirectInputEffect::Stop 메소드가 불려 갔을 때 뿐인다. 방아쇠 버튼에 할당한 이펙트는 그 버튼을 누르면(자) 시작 해, 그 버튼을 떼어 놓는지, 계속 시간이 지나는지, 어느 쪽인지 빠른 (분)편의 시점에서 종료한다.


이펙트의 다운로드와 언로드

이펙트는 재생하기 전에 디바이스에 다운로드해야 한다. 이펙트의 다운로드란, 드라이버에 이펙트의 재생의 준비를 하도록(듯이) 통지하는 것이다. 다운로드의 방법을 결정하는 것은 완전히 드라이버에 맡길 수 있다. 일반적으로, 드라이버는 이펙트의 파라미터를 하드웨어 메모리에 두어, 디바이스와 시스템의 사이의 데이터 차례차례 전송을 최소한으로 억제한다. 이것에 의해,지연 시간이 삭감된다. 이것은,"발사" 버튼과 같이, 방아쇠에의 응답으로 기능하는 조건과 이펙트에 있어서는 특히 의미가 있다. 디바이스가 축이동과 버튼 압하에 응답하기 위해서 시스템과 전혀 교환을 실시할 필요가 없는, 이라고 하는 것이 이상적일 것이다.

디바이스가 만배는 아니고 게다가 배타 협조 레벨로 취득되고 있는 경우에는, 이펙트의 생성시에 다운로드가 자동적으로 행해진다. 이펙트를 시작, 또는 이펙트의 파라미터를 변경 하면 간, 다운로드는 디폴트로 행해진다.

파라미터를 변경할 경우에 DIEP_NODOWNLOAD 플래그를 지정하면, 계속 IDirectInputEffect::Download 메소드를 사용해 이펙트의 다운로드나 업 로드를 실시하지 않으면 안 된다.

디바이스가 미취득 상태 때 (예를 들어, 디바이스가 배타 foreground 협조 레벨로 취득되고 있어, 어플리케이션이 백그라운드로 이행할 때), 이펙트는 언로드되고 있으므로, 어플리케이션이 foreground를 재취득할 경우에 다시 이펙트를 다운로드해야 한다. 이펙트의 다운로드는,IDirectInputEffect::Start 메소드를 호출하면 자동적으로 행해진다. 그러나, 디바이스를 재취득 하면 동시에 모든 이펙트를 다운로드할지 어떨지를 선택할 수 있다. Start 메소드는 보통 방아쇠 버튼에 할당한 이펙트에서는 불려 가지 않기 때문에, 이런 종류의 이펙트는 반드시 다운로드할 필요가 있다.

이펙트의 다운로드중에 어플리케이션이 DIERR_DEVICEFULL 에러를 받으면(자), 낡은 이펙트를 언로드해 새로운 이펙트를 위한 스페이스를 확보할 필요가 있다. IDirectInputEffect::Unload 메소드를 호출하면, 디바이스로부터 1 개의 이펙트를 삭제할 수가 있다. 또,IDirectInputDevice8::SendForceFeedbackCommand 메소드를 호출해 디바이스를 리셋 하면, 모든 이펙트를 삭제할 수도 있다.

force feedback 디바이스를 생성 하면, 하드웨어와 드라이버가 리셋 되므로, 존재하고 있던 이펙트 모든 것이 소거된다.


이펙트의 변경

이펙트의 재생 그 중에서 이펙트의 파라미터를 변경할 수가 있는 경우가 있다. 이것은 IDirectInputEffect::SetParameters 메소드를 사용해 실시한다.

DIEFFECTINFO 구조체의 dwDynamicParams 멤버는, 이펙트의 재생 그 중에서 변경할 수 있는 이펙트의 파라미터를 통지한다. 이펙트의 재생중에는 변경할 수 없는 이펙트의 파라미터를 변경하려고 해, 이펙트가 실제로 아직 재생하고 있을 때는, 보통, Microsoft® DirectInput® 는 이펙트를 정지시켜, 파라미터를 갱신해, 이펙트를 재스타트 시킨다. 이 DirectInput 의 디폴트의 동작을 무효로 하려면 , DIEP_NORESTART 플래그를 건네주면 좋다.

다음의 C++ 의 프로그램예에서는, 「이펙트의 생성」에 있는 샘플 프로그램으로 세트 된 정수 포스의 매그니튜드를 변경한다.

DIEFFECT        diEffect;           // 이펙트용의 파라미터.
DICONSTANTFORCE diConstantForce;    // 타입 고유 파라미터.

diConstantForce.lMagnitude = 5000;
diEffect.dwSize = sizeof(DIEFFECT);
diEffect.cbTypeSpecificParams = sizeof(DICONSTANTFORCE);
diEffect.lpvTypeSpecificParams = &diConstantForce;
hr = lpdiEffect->SetParameters(&diEffect, DIEP_TYPESPECIFICPARAMS);

DIEP_TYPESPECIFICPARAMS 플래그에 의해,DIEFFECT 구조체로부터의 데이터 전송은, 관련하는 멤버에 한정되는 것이 보증된다. 따라서, 이 구조체 전체를 초기화할 필요가 없어져, 디바이스에 송신할 필요가 있는 데이터의 양이 최소한으로 끝난다.


게인

포스를 미치는 디바이스의 종류에 응해, 이펙트의 포스의 크기에 차이를 내고 싶은 경우가 있을 것이다. 예를 들어, 어느 축으로 대해 최대 n 뉴턴의 포스를 낳는 디바이스로 어플리케이션의 이펙트가 올바르게 일한다고 생각될 때는, 보다 많은 포스를 낳는 디바이스용으로 게인을 조정하고 싶은 것이 있을 것이다 (축의 포스의 최대치를 늘리기 위해서(때문에) 게인을 사용할 수 없기 때문에, 낳는 포스가 작은 디바이스에 대해서, 적절한 값을 기본적 이펙트 매그니튜드로 설정해야 한다).

또, 게인을 사용해, 하드웨어로 정의된 이펙트의 매그니튜드를 감소시킬 수도 있다.

축이나 버튼등의 디바이스 오브젝트에 의해 발생하는 포스는, 오브젝트의 열거시에 DIDEVICEOBJECTINSTANCE 구조체의 dwFFMaxForce 멤버에 저장 되어 돌려주어진다 ( 「디바이스 오브젝트의 열거」를 참조할것).

IDirectInputDevice8::SetProperty 메소드를 사용해, 디바이스 전체의 게인을 설정할 수가 있다.

개별의 이펙트를 생성 하면나무는,DIEFFECT 구조체의 dwGain 멤버에 값을 설정하는 것으로, 이펙트에 게인을 설정해야 한다 (dwGain 가 제로라면, 그 이펙트는 느껴지지 않는다). 이 값은,dwFlags 파라미터에 DIEP_GAIN 를 지정해 IDirectInputEffect::SetParameters 를 호출하는 것으로, 나중에 변경할 수가 있다.

디바이스 게인을 설정하는 목적은, 어플리케이션에 모든 이펙트의 포스를 일괄해 제어시키는 것이다. 예를 들어, 음향 믹서의 메인 볼륨 콘트롤러와 같이, force feedback 이펙트에 필요하게 되는 강도를 유저로 지정시키는 슬라이더 컨트롤을 어플리케이션에 붙이고 싶다고 생각하는 일이 있을 것이다. 디바이스 게인을 설정하면, 유저의 취향에 맞추어 개별의 이펙트의 게인을, 어플리케이션이 조정할 필요가 없어진다.

1 개의 게인값은 0 에서 10,000 의 범위의 값을 취한다. 10,000 이라고 하는 값은, 매그니튜드를 스케일링 해서는 안된다고 하는 것을 나타낸다. 7,500 이라고 하는 값은, 포스의 명목 매그니튜드의 75% 에 포스를 스케일링 해야 한다라고 말하는 것을 의미하고 있다. 그 외의 수치도 이것에 준한다.


force feedback 상태

IDirectInputDevice8::SendForceFeedbackCommand 메소드를 사용하면, 디바이스의 액츄에이터를 오프 (재생하고 있는 이펙트 모든 것을 무시하는데 유효)로 해, 이펙트의 재생을 중단 또는 중지해, 디바이스를 리셋 해 다운로드한 모든 이펙트를 삭제할 수가 있다.

현재의 force feedback 상태를 취득하려면 ,IDirectInputDevice8::GetForceFeedbackState 메소드를 사용한다. 이 메소드에 의해, 액츄에이터가 유효한가 어떤가 재생이 중단 상태인가 부디 및 디바이스가 리셋 되었는지 어떠했는지라고 하는 정보가 돌려주어진다. 또, 다양한 스윗치에 관한 정보나, 현재 디바이스에 전원이 들어가 있을지 어떨지의 정보도 취득된다.


이펙트 오브젝트의 열거

프로그램에 생성한 모든 이펙트의 실험이나 조작이 필요하게 되었을 때는,IDirectInputDevice8::EnumCreatedEffectObjects 메소드를 이용할 수가 있다. 현재로서는, 이 메소드에는 플래그가 전혀 정의되어 있지 않기 때문에, 특정의 종류의 이펙트에 열거를 좁힐 수 없다. 모든 이펙트가 열거되어 버린다.

주 : 이 메소드는 생성되는 이펙트는 열거하지만, 디바이스에 의해 지원 되는 이펙트는 열거하지 않는다. 이 2 개의 이펙트의 구별에 대해 자세한 것은, 「이펙트의 열거」를 참조할것.

Microsoft® DirectInput® 외의 열거와 같게,EnumCreatedEffectObjects 메소드에는 콜백 함수가 필요하다. 이 표준 콜백 함수는, 문서에서는 플레이스홀더명 DIEnumCreatedEffectObjectsCallback 로 나타내지고 있지만, 다른 이름을 붙여도 괜찮다. 이 함수는 열거된 이펙트 각각 붙어 불려 간다. 이 함수내에서는, 어떤 처리라도 실행할 수가 있다. 그러나, 열거의 실행중은 새로운 이펙트를 생성하지 않는 것이 안전하다.

다음에 드는 것은, 콜백 함수의 골격을 나타내는 코드예이다. 콜백 함수의 pvRef 파라미터는, 32 비트의 임의의 값을 취할 수가 있다. 이 경우, 이 파라미터는 IDirectInputDevice8 인터페이스에의 포인터이다.

HRESULT  hr;

BOOL CALLBACK DIEnumCreatedEffectObjectsCallback(
                             LPDIRECTINPUTEFFECT peff, LPVOID pvRef);
{
    LPDIRECTINPUTDEVICE pdid = (IDirectInputDevice*) pvRef;
                                        // 호출 디바이스에의 포인터.
    DIEFFECT            diEffect;       // 생성된 이펙트용의 파라미터.

    diEffect.dwSize = sizeof(DIEFFECTINFO);
    peff->GetParameters(&diEffect, DIEP_ALLPARAMS);
    // 파라미터의 체크 또는 설정, 혹은 그 외의 처리.
    .
    .
    .
}   // 콜백의 종료.

이 호출은, 콜백을 시동해, DirectInputDevice 포인터 lpdid 에 건네준다.

hr = lpdid->EnumCreatedEffectObjects(
         &DIEnumCreatedEffectObjectsCallback,
         &lpdid, 0);


이펙트의 타입

여기에서는, 이하의 force feedback 이펙트 타입에 대해 설명한다.

  • 정수 포스
  • 경사 포스
  • 주기적 이펙트
  • 조건
  • 커스텀 포스
  • 디바이스 이펙트


정수 포스

정수 포스는, 일정한 매그니튜드와 계속 시간을 가지는 포스이다.

포락선을 정수 포스에 적용해, 포스에 형태를 줄 수가 있다. 예를 들어, 2,000 의 명목 매그니튜드와 2 초의 계속 시간을 가지는 이펙트가 있으면(자) 가정하자. 이 경우, 다음의 값을 가지는 포락선을 적용한다.

파라미터 | 값
어택 시간 | 0.5 초
초기 어택 레벨 | 5,000
페이드 시간 | 1 초
페이드 레벨 | 0

이펙트를 재생 하면, 다음의 값을 얻을 수 있다.

경과시간 | 매그니튜드
0.0 | 5,000
0.1 | 4,400
0.2 | 3,800
0.3 | 3,200
0.4 | 2,600
0.5 | 2,000
(보관 유지의 계속 시간) | 2,000
1.0: | 2,000
1.1 | 1,800
1.2 | 1,600
1.3 | 1,400
1.4 | 1,200
1.5 | 1,000
1.6 | 800
1.7 | 600
1.8 | 400
1.9 | 200
2.0 | 0

정수 포스에 오프셋(offset)를 적용할 수 없다.

정수 포스를 생성하려면 , GUID_ConstantForce 를 IDirectInputDevice8::CreateEffect 메소드에 건네준다. DIEFFECTINFO 구조체의 멤버 dwEffType (DIEFT_GETTYPE(dwEfftype))의 하위 바이트가 DIEFT_CONSTANTFORCE 과 동일할 때는,IDirectInputDevice8::EnumEffects 메소드로 취득한 것 외의 임의의 GUID 를 건네줄 수가 있다. 이 방법을 사용하면, 소란을 시뮬레이션 하는 "정수" 포스 (이름은 "정수 (정상)" 이지만 실제로는 매그니튜드가 랜덤에 변화한다) 등, 업자가 설계한 하드웨어 특유의 포스를 사용할 수가 있다.

정수 포스는,DICONSTANTFORCE 구조체를 사용해 매그니튜드를 정의한다. 부의 매그니튜드에는, 포스의 방향을 반전하는 이펙트가 있다.


경사 포스

경사 포스는, 정의 끝난 초기 매그니튜드와 종기 매그니튜드 및 유한의 계속 시간을 가지는 포스이다. 경사 포스는, 1 방향인 만큼 늘어나는 경우도, 혹은 1 방향을 향해 강할 기세로 시작되어, 약해져, 정지해, 반대 방향으로 강하게 진행된다고 하는 경우도 있다.

다음의 그림은, 매그니튜드 -5, 000 으로 시작되어, 매그니튜드 5,000 으로 끝나는 경사 포스를 나타내고 있다.

포락선 을 경사 포스에 적용해, 경사 포스를 잡아늘일 수가 있다. 다음의 그림은, 전의 그림의 경사 포스에 포락선 (초록으로 나타내 있다)을 적용하는 이펙트를 나타내고 있다.

포락선의유지 기간 부분에서는, 이펙트의 매그니튜드는 포락선의 적용전과 같은 직선을 그리는 것에 주의한다. 어택 과 페이드의 계속 시간에 대해서는, 경사 포스의 경사는 어택 레벨과 페이드 레벨로 변경된다.

경사 포스에는 오프셋(offset)를 적용할 수 없다.

경사 포스를 생성하려면 , GUID_RampForce 를 IDirectInputDevice8::CreateEffect 메소드에 건네준다. DIEFFECTINFO 구조체의 멤버 dwEffType (DIEFT_GETTYPE(dwEfftype))의 하위 바이트가 DIEFT_RAMPFORCE 와 동일한 경우는,IDirectInputDevice8::EnumEffects 메소드로 취득한 것 외의 임의의 GUID 를 건네줄 수도 있다. 이 방법을 사용하면, 업자가 설계한 하드웨어 특유의 경사 포스를 사용할 수가 있다.

경사 포스는 DIRAMPFORCE 구조체를 이용해, 포스의 초기 매그니튜드와 종기 매그니튜드를 정의할 수가 있다. 한편, 그 계속 시간은 DIEFFECT 구조체에 의해 정의된다. 계속 시간을 결코 INFINITE 로 설정해선 안 된다.


주기적 이펙트

주기적 이펙트는 파형 이펙트이다. Microsoft® DirectInput® 에서는, 이하의 파형을 정의하고 있다.

  • 정방형
  • 싸인 커브
  • 코사인 커브
  • 삼각형
  • 업 톱니 (SawtoothUp) － 이 파형은 최대의 정포스에 이른 후, 수직에 하강한다. force feedback의 기본 개념」의 예를 참조할것.
  • 다운 톱니 (SawtoothDown) － 이 파형은 최대의 부포스에 이른 후, 수직으로 상승한다.

주기적 이펙트에는포락선을 적용할 수가 있다. 「force feedback의 기본 개념」의 예를 참조할것.

주기적 이펙트의 국면이란, 이펙트가 시작되는 파형 위에의 포인트이다. 국면은 0 에서 35,999 까지의 범위에서, 열매 각도의 100 배로 계측 된다. 다음의 표는, 선택한 국면값 (번단위)이 다양한 파형 위에의 어디에 있는지를 나타내고 있다. Max 는 물결의 최상부 (+) 또는 최저부 (-)이며,Mid 는 물결의 중간 포인트이다. 이러한 위치에서는, 어느 방향에도 포스는 적용되지 않았다.

파형 | 0 | 90 | 180 | 270
정방형 | +Max | +Max | -Max | -Max
싸인 커브 | Mid | +Max | Mid | -Max
삼각형 | +Max | Mid | -Max | Mid
업 톱니 | -Max | -Max/2 | Mid | +Max/2 (사이클의 반복의 직전에 +Max 에 이른다)
다운 톱니 | +Max | +Max/2 | Mid | -Max/2 (사이클의 반복의 직전에 -Max 에 이른다)

드라이버에 의해, 국면값이 바로 옆의 지원값에 말 수 있는 일이 있다. 예를 들어, 드라이버에 따라서는, 싸인 이펙트로 0 으로 9,000 (코사인을 생성하기 위해서) 밖에 지원 하지 않고, 그 외의 이펙트로 0 으로 18,000 밖에 지원 하고 있지 않는 것도 있다.

주기적 포스를 생성하려면 ,IDirectInputDevice8::CreateEffect 메소드의 rguid 파라미터에 다음에 드는 값의 어떤 것이나 1 개를 건네준다.

  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown

DIEFFECTINFO 구조체의 멤버 dwEffType (DIEFT_GETTYPE(dwEfftype))의 하위 바이트가 DIEFT_PERIODIC 에 동일한 경우는,IDirectInputDevice8::EnumEffects 메소드로 취득한 것 외의 임의의 GUID 를 건네주어도 괜찮다. 이 방법을 사용하면, 업자가 설계한 하드웨어 특유의 포스를 사용할 수가 있다. 예를 들어, 스틱을 작은 원형에 회전하는 주기적 이펙트를 지원 하고 있는 하드웨어 디바이스등이 있다.

주기적 이펙트의 타입 고유 구조체는 DIPERIODIC 이다.

주기적 이펙트의 "주기" (DIPERIODIC.dwPeriod)와 "샘플링 간격" (DIEFFECT.dwSamplePeriod)을 혼동 하지 않게 주의 해야 한다. 주기는 1 개의 물결의 사이클 전체를 실행하는데 필요로 하는 시간이다. 샘플링 간격은, 모든 이펙트와 같게, 매그니튜드를 실제로 조정하는 간격의 최소 시간이다.


조건

조건이란, 디바이스내의 현재의 센서값에 반응해 적용되는 포스이다. 즉, 조건은, 죠이스틱 핸들의 위치 또는 속도 등, 디바이스에 관한 정보를 필요로 한다.

일반적으로, 조건은 게임이나 그 외의 어플리케이션에 있어서의 개별의 이벤트에는 관련지을 수 있지 않았다. 조건은, 플라이트 스틱의 딱딱함이나 느슨함, 또는 직진의 위치에 되돌리는 핸들의 방향등의 상태를 표현한다.

조건은, 정의된 매그니튜드를 가지지 않는다. 매그니튜드는, 입력 오브젝트의 동작과 위치에 의해 측정된다.

Microsoft® DirectInput® 는, 다음과 같은 조건의 이펙트를 정의한다.

  • 마찰 ― 축이 이동할 경우에 적용되는 포스로, 정의 끝난 마찰 계수에 의해 정해진다.
  • 댐퍼 ― 이 포스는 유저가 죠이스틱을 작동시키는 속도 에 비례해 증가한다.
  • 관성 ― 이 포스는 축의 가속도 에 비례해 증가한다.
  • 스프링 ― 이 포스는 정의되고 있는 중립 포인트로부터의 축의 거리 에 비례해 증가한다.

대부분의 하드웨어 디바이스에서는, 조건에포락선을 적용할 수 없다.

조건에는 다음의 타입의 파라미터가 있다.

Offset
조건의 적용이 시작되는 적절한 센서값을 읽어들이는, 제로로부터의 오프셋(offset). 스프링 이펙트에서는, 중립 포인트 (스프링이 정지하고 있다고 생각되는 축위에의 포인트)는 조건용의 이 오프셋(offset)에 의해 정의된다. 댐퍼 이펙트에서는, 이 오프셋(offset)에 의해, 댐퍼 포스가 제로가 되는 최대 속도값이 정의된다. 보통, 오프셋(offset)는 관성 이펙트나 마찰 이펙트에는 사용하지 않는다.
Coefficient
이펙트의 스케일링을 산출하는 승수. 디바이스에 따라서는, 조건에 관계하는 축위에의 정방향과 부방향으로 다른 계수를 설정할 수가 있다. 예를 들어, 공격을 받은 비행기를 컨트롤 하는 조종간은, 왼쪽보다 오른쪽에 작동시키는 (분)편이 용이하게 된다라고 하는 경우이다.
Saturation
force feedback에서는, 포화는 이펙트를 올리는 최대의 포스를 나타내고 있다. 예를 들어, 조종간이 X 축상에서 스프링 조건을 가지고 있으면(자) 가정해 보자. 오프셋(offset)는 제로, 계수는 10,000 이며, 보통은 조종간이 중립 포인트로부터 가장 떨어져 있을 때, 최대 포스가 발휘된다. 그러나, 정부 5,000 의 포화를 정의하고 있으면(자), 조종간이 오른쪽이나 왼쪽으로 이동한 후, 포스는 증가하지 않는다.

포화를 지원 하고 있지 않는 디바이스도 있다.

Deadband
데드 밴드란, 조건이 작용하지 않는 축의 오프셋(offset) 범위이다. 스프링이 축의 중립 포인트에 정지하고 있는 경우는, 데드 밴드는 이 정지의 범위를 확장한다.

데드 밴드를 지원 하고 있지 않는 디바이스도 있다.

조건에 계속 시간을 설정할 수가 있다. 그러나, 계속 시간을 INFINITE (-1)로 설정해, 어플리케이션으로 특정의 이벤트에 응답 하면나무만 이펙트를 정지할 방법이 사용되는 것이 많다.

조건을 생성하려면 ,IDirectInputDevice8::CreateEffect 메소드의 rguid 파라미터에, 다음에 드는 값의 어떤 것이나 1 개를 건네준다.

  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction

DIEFFECTINFO 구조체의 멤버 dwEffType (DIEFT_GETTYPE(dwEfftype))의 하위 바이트가 DIEFT_CONDITION 에 동일한 경우는,IDirectInputDevice8::EnumEffects 메소드로 취득한 것 외의 임의의 GUID 를 건네줄 수가 있다. 이 방법을 사용하면, 업자가 설계한 하드웨어 특유의 조건을 사용할 수가 있다.

조건의 타입 고유 구조체는 DICONDITION 이다. 복수축의 조건에서는, 1 개의 축으로 대해 복수의 구조체로부터 되는 배열을 사용하는지, 또는 특정의 방향에서의 조건을 정의하는 1 개의 구조체를 사용할 수가 있다. 어느 쪽의 경우에서도,DIEFFECT 구조체의 cbTypeSpecificParams 멤버에, 사용하는 바이트수를 설정할 필요가 있다. 즉,sizeof(DICONDITION) * n 를 설정할 필요가 있다. 여기서 n 는 사용하는 구조체의 수를 나타낸다. 1 개(살) 혹은 복수의 구조체를 사용하는 방법의 상세한 것에 대하여는,DICONDITION 구조체의 설명을 참조할것.

이펙트의 계수로포화에 대해 정과 부의 양쪽 모두가 디바이스로 지원 되고 있는지 어떤지를 확인하려면 , 어플리케이션으로 IDirectInputDevice8::GetEffectInfo 메소드 또는 IDirectInputDevice8::EnumEffects 메소드를 호출해,DIEFFECTINFO 구조체의 dwEffectType 멤버를 조사하지 않으면 안 된다. 이펙트가 DIEFT_POSNEGCOEFFICIENTS 플래그를 돌려주지 않으면,lNegativeCoefficient 멤버의 값은 무시되어lPositiveCoefficient 의 값이 축전체에 적용된다. 같이 이펙트가 DIEFT_POSNEGSATURATION 플래그를 돌려주지 않으면,dwNegativeSaturation 의 값은 무시되어dwPositiveSaturation 의 값이 부의 포화 레벨로서 사용된다. 또, 이펙트가 DIEFT_SATURATION 플래그를 돌려주지 않으면,dwPositiveSaturation 와 dwNegativeSaturation 의 양쪽 모두의 값이 무시되어 포화는 적용되지 않는다.

또,DIEFFECTINFO.dwEffectType 에 DIEFT_DEADBAND 플래그가 설정되어 있는지 어떤지를 체크하는 것으로,데드 밴드가 조건에 대해서 지원 되고 있는지 어떤지를 알 수 있다. 지원되어 있지 않은 경우,DICONDITION 구조체의 lDeadBand 멤버의 값은 무시된다.

계수에는 음수를 설정할 수가 있다. 이렇게 하면(자), 이펙트는 반대 방향의 포스를 생성한다. 예를 들어 스프링 이펙트에서는, 계수에 음수를 설정 하면, 스프링 이펙트는 오프셋(offset) 포인트로 향해 이끌지 않고 , 오프셋(offset) 포인트로부터 멀어질 방향에 누르게 된다.


커스텀 포스

어플리케이션의 생성자는, 커스텀 포스를 생성 하는 것에 의해, 독자적인 이펙트를 생성 할 수가 있다. 커스텀 포스는, 디바이스가 재생하는 정수 포스값의 배열이다.

커스텀 파형 이펙트의 타입 고유 구조체는,DICUSTOMFORCE 이다.

DICUSTOMFORCE 구조체의 dwSamplePeriod 멤버와 DIEFFECT 구조체의 dwSamplePeriod 멤버에는 같은 값을 설정해야 한다. 이 값은 밀리 세컨드 단위의 시간이며, 포스의 배열의 각 요소가 재생되는 시간을 나타낸다.

DIEFFECT 의 dwDuration 멤버로 설정된 시간이 지날 때까지, 커스텀 포스는 반복해 일한다.


디바이스 이펙트

하드웨어 드라이버는, Microsoft® DirectInput® 가 정의하는 카테고리에 들어맞지 않는 특수 효과를 지원 할 수가 있다. 이러한 이펙트에 대응하는 타입 고유의 파라미터는, 하드 코딩 되고 있는 일도 있으면, 어플리케이션으로 변경할 수 있는 일도 있다.

타입 고유의 파라미터가 변경 가능한 경우, 어플리케이션 개발자는, 이펙트에 의해 요구되는 데이터 구조를 선언하고 있는 헤더 파일을 취득해야 한다.

하드웨어 벤더는, 그 디바이스 고유 이펙트를 식별하는 GUID 를 제공해야 한다. 또 하드웨어 벤더는, 그 이펙트에 대한 타입 고유 파라미터용의 특별한 구조체를 제공하는 일도 있다. 다음에, 어플리케이션은,DIEFFECT 구조체와 그 이펙트에 대한 타입 고유 구조체를, 다른 어느 이펙트에서도 같이이지만, 초기화해야 한다. 다음에,IDirectInputDevice8::CreateEffect 메소드를 호출해, 디바이스 GUID 와 DIEFFECT 구조체에의 포인터를 건네준다.

DIEFFECTINFO 구조체에 디바이스 이펙트에 대한 정보가 들어가지만, 그 멤버 dwEffType (DIEFT_GETTYPE(dwEfftype))의 하위 바이트는, 정의 끝난 DirectInput 의 이펙트 타입 (정수 포스, 경사 포스, 주기적 이펙트, 조건)의 어느 것으로 디바이스 이펙트가 분류되는지를 나타내고 있다. 정의 끝난 카테고리의 어느 것에도 분류할 수 없는 경우, 하위 바이트의 값은 DIEFT_HARDWARE 이다.

디바이스 고유의 이펙트가 정의 끝난 몇개의 종류로 분류할 수 있으면,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버는 그 종류에 응해,DICONSTANTFORCE 구조체,DIRAMPFORCE 구조체,DIPERIODIC 구조체, 또는 DICONDITION 구조체를 가리켜,cbTypeSpecificParams 멤버는 그 구조체의 사이즈와 같은 값이 아니면 안 된다.

DIEFT_GETTYPE(dwEfftype)의 값이 DIEFT_HARDWARE 이면,lpvTypeSpecificParams 멤버 및 cbTypeSpecificParams 멤버의 값은, 그 이펙트가 특별한 타입 고유 파라미터를 필요로 하고 있는지 어떤지에 의해 정해진다. 특별한 파라미터를 필요로 할 때는, 이 2 개의 멤버의 값은, 메이커의 헤더 파일로 정의되어 각자의 어플리케이션으로 선언 및 초기화된, 적절한 구조체를 가리키지 않으면 안 된다. 그 이펙트가 특별한 파라미터를 필요로 하지 않는 경우, 즉, 하드웨어 이펙트용의 DIEFFECTINFO 구조체의 dwStaticParms 멤버에 DIEP_TYPESPECIFICPARAMS 플래그가 없을 때는,lpvTypeSpecificParams 는 NULL 로,cbTypeSpecificParams 는 제로가 아니면 안된다.

DirectInput 는 확인을 위해, GUID 와 DIEFFECT 구조체를 디바이스 드라이버에 건네준다. GUID 가 미지인 경우, 디바이스는 DIERR_DEVICENOTREG 를 돌려준다. GUID 는 기존에서도, 타입 고유 데이터가 그 이펙트에 대해서 부정확한 경우는, 디바이스는 DIERR_INVALIDPARAM 를 돌려준다.


프로그래밍의 힌트와 툴

이 섹션에서는, 특수한 프로그래밍 주제와 Microsoft® DirectX® SDK 부속 툴의 개요에 대해 설명한다. 이 정보는, DirectInput® 데이터의 이해와 force feedback 이펙트의 설계에 도움이 된다.

이하의 주제로 나누어, 설명한다.

  • 이전버전의 DirectInput 용의 설계
  • 디버그시의 응답 지연의 방지
  • Force Editor


이전버전의 DirectInput 용의 설계

DirectInput8Create, IDirectInput8::Initialize, IDirectInputDevice8::Initialize, 및 IDirectInputEffect::Initialize 메소드에서는, Microsoft® DirectInput® 의 버젼 번호를 건네줄 필요가 있다. 이 파라미터는, DirectInput 서브 시스템이 어느 버젼의 Microsoft DirectX® 를 에뮤레이트 하는지를 지정한다.

최신 버젼의 DirectInput 용으로 설계된 어플리케이션은, Dinput.h 로 정의되고 있는 DIRECTINPUT_VERSION 값을 건네줄 필요가 있다.

이전의 버젼으로 실행하도록(듯이) 설계된 어플리케이션에서는, 설계 대상의 DirectInput 의 버젼에 대응한 값, 즉 고차원 바이트에 메인 버젼 번호를 매긴 값을 건네줄 필요가 있다. 예를 들어, DirectInput 3.0 상에서 동작하도록(듯이) 설계된 어플리케이션은, 0x0300 를 건네줄 필요가 있다.

Dinput.h 헤더 파일을 인클루드 하기 전에, DIRECTINPUT_VERSION 를 0x0300 로 정의 하면, 이 헤더 파일은 DirectInput 3.0 으로 호환성을 가지는 구조체 정의를 생성한다.

Dinput.h 헤더 파일을 인클루드 하기 전에 DIRECTINPUT_VERSION 를 정의하지 않으면 Dinput.h 헤더 파일은 DirectInput 의 현행 버젼과 호환성이 있는 구조체 정의를 생성한다. 그러나, DirectX 3 으로 호환성이 있는 구조체도, 그 이름에 "_DX3" 를 붙이면 사용할 수가 있다. 예를 들어, DirectX 3 으로 호환성이 있는 DIDEVCAPS 구조체는 DIDEVCAPS_DX3 라고 명명되게 된다.

또, DirectInput 인터페이스와 DirectInputDevice 인터페이스의 적절한 버젼을 사용할 필요가 있다. DirectX 7.0 보다 전의 버젼의 DirectX 에서는,IDirectInput 와IDirectInputDevice 또는 IDirectInputDevice2 의 어느 쪽인지를 사용할 필요가 있다 (후자는 DirectX 5.0 이후의 버젼으로 이용 가능).


디버그시의 응답 지연의 방지

Microsoft Windows® 2000 의 아래, Microsoft® DirectInput® 로 키보드 또는 마우스를 사용하는 경우, 디버그 세션중에 코드를 실행 하면 단기간의 지연이 발생하는 경우가 있다. 이 현상은 debug 모드에서만 발생한다. 실제의 어플리케이션에서는 발생하지 않는다. 다만, Emulation 값을 다음의 레지스트리 키에 추가하는 것으로, debug 모드에서도 이 지연이 발생하지 않게 할 수가 있다.

HKEY_LOCAL_MACHINE
    SOFTWARE
        Microsoft
            DirectInput

이름 | 형 | 데이터
Emulation | DWORD | 0x08 (마우스용) 0x10 (키보드용) 0x18 (마우스 및 키보드용)

이러한 값을 설정 하면, DirectInput 가 데이터를 돌려주는 방법을 변경하는 일 없이, 지연에 영향을 받지 않는 에뮬레이션 모드를 기동할 수가 있다. Microsoft Software Development Kit (SDK)에는, Mouse and Keyboard Emulation On.reg 및 Mouse and Keyboard Emulation Off.reg 의 2 개의 레지스트리 파일이 부속되어 있어, 지연에 영향을 받지 않는 에뮬레이션 모드의 기동과 종료를 지정할 수가 있다. 이러한 파일은, (SDK 루트) \Samples\Multimedia\DirectInput\Bin 에 보존되고 있다.

주 : Emulation 값은, 디바이스가 디버그 모드의 배타 foreground 협조 레벨로 사용되고 있는 경우에게만 지원 된다.


Force Editor

설명

Force Editor 어플리케이션을 사용하면(자), force feedback 이펙트를 디자인하거나 그 이펙트를 단독으로 테스트하거나 몇개의 이펙트를 조합해 테스트하거나 할 수가 있다. 이펙트는, 파일에 보존해, Microsoft® DirectInput® 어플리케이션에 읽어들이게 할 수가 있다.

패스

실행 가능 파일 :(SDK 루트) \Bin\Dxutils\Fedit.exe

유저즈 가이드

Force Editor 에는 전용의 문서가 첨부하고 있다. Fedit.exe 를 기동해, F1 키를 누르면(자) on-line help를 참조할것이 생긴다. 이하의 파일을 더블 클릭 해, on-line help를 직접 기동할 수도 있다.

(SDK 루트) \Bin\Dxutils\Fedit.chm


DirectInput C/C++ 튜토리얼

여기에서는, 5 개의 튜토리얼을 사용해, Microsoft® DirectInput® 의 기본적인 기능을 C 또는 C++ 어플리케이션에 이행 하는 방법을 스텝바이스텝으로 설명한다.

  • 튜토리얼 1 : 키보드의 사용법

    최초의 튜토리얼은, 기존의 어플리케이션에 DirectInput 키보드 지원을 추가하는 순서를 나타낸다.

  • 튜토리얼 2 : 마우스의 사용법

    2 번째의 튜토리얼은, 어플리케이션으로 DirectInput 마우스 지원을 실현하는 순서를 나타낸다. 이 튜토리얼은,Scrawl 샘플을 베이스로 하고 있어 버퍼링 데이터에 초점을 맞힌다.

  • 튜토리얼 3 : 죠이스틱의 사용법

    이 튜토리얼은, 시스템에 접속되고 있는 죠이스틱을 열거하는 방법, 콜백 함수로 DirectInput 디바이스 오브젝트를 생성 해 초기화하는 방법, 및 직접 데이터를 취득하는 방법을 나타낸다. 샘플 코드는,Joystick 샘플이 베이스가 되어 있다.

  • 튜토리얼 4 : force feedback의 사용법

    이 튜토리얼은, force feedback 죠이스틱에서의 단순한 이펙트의 생성과 조작에 대해 설명한다.

  • 튜토리얼 5 : 액션 매핑의 사용법

    마지막 튜토리얼은, 액션 맵을 생성 해 적용하는 방법에 대해 설명한다.

주 이러한 튜토리얼은, C++ 스타일의 함수 호출을 사용해 기술되고 있다. C 환경에 있어서의 Microsoft DirectX® 함수 호출의 프로그래밍의 상세한 것에 대하여는, 「C 에 의한 COM 오브젝트에의 액세스」를 참조할것.


튜토리얼 1 : 키보드의 사용법

키보드 입력의 준비를 실시하려면 , 우선, Microsoft® DirectInput® 오브젝트의 인스턴스를 생성 한다. 다음에,IDirectInput8::CreateDevice 메소드를 사용해,IDirectInputDevice8 인터페이스의 인스턴스를 생성 한다. IDirectInputDevice8 인터페이스의 각 메소드는, 디바이스의 조작, 디바이스의 동작의 설정, 및 데이터의 취득을 실시하기 위해서(때문에) 사용한다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : DirectInput 오브젝트의 생성
  • 스텝 2 : DirectInput 키보드 디바이스의 생성
  • 스텝 3 : 키보드의 데이터 형식의 설정
  • 스텝 4 : 키보드의 동작의 설정
  • 스텝 5 : 키보드에의 액세스권의 취득
  • 스텝 6 : 키보드로부터의 데이터의 취득
  • 스텝 7 : DirectInput 시스템의 종료

DirectInput 키보드 지원을 어플리케이션에 추가하는 것은, 비교적 간단해서, 이 튜토리얼은, 완전한 Keyboard 샘플 어플리케이션으로는 되지 않았다. 튜토리얼의 모든 순서는, 본문내의 코드로 구체적으로 가리키고 있다. 시스템의 초기화의 관련 순서는, 「샘플 함수 1 : DI_Init 」에 집약되고 있다. 시스템을 종료시킬 필요가 있는 경우는, 이제(벌써) 1 개의 함수 「샘플 함수 2 : DI_Term 」가, 불려 간다. 이러한 함수의 내용의 상당수는, 이 후의 튜토리얼에서도 재차 사용된다.


스텝 1 : DirectInput 오브젝트의 생성

Microsoft® DirectInput® 시스템의 셋업 순서의 처음은, 전체의 매니저가 되는 단일의 DirectInput 오브젝트를 생성 하는 것이다. 이것을 실시하려면 ,DirectInput8Create 함수를 호출한다.

// HINSTANCE g_hinst; // 이전에 초기화가 끝난 상태.
HRESULT         hr;
LPDIRECTINPUT8  g_lpDI;

hr = DirectInput8Create(g_hinst, DIRECTINPUT_VERSION,
        IID_IDirectInput8, (void**) &g_lpDI, NULL);
if FAILED(hr)
{
    // DirectInput 는 이용 가능하지 않다.  적절한 조치를 취한다.
}

DirectInput8Create 의 제 1 파라미터는, 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들이다.

제 2 파라미터는, 어느 버젼의 DirectInput 시스템을 DirectInput 오브젝트에 사용하는지를 지시한다. 이전의 버젼의 DirectInput 와 호환성이 있는 어플리케이션을 설계할 수도 있다. 상세한 것에 대하여는, 「이전버전의 DirectInput 용의 설계」를 참조할것.

제 3 파라미터는, 어느 인터페이스가 돌려주어지는지를 지정한다. 대부분의 어플리케이션은, IID_IDirectInput8 를 건네주는 것에 의해 최신의 버젼을 취득한다.

제 4 파라미터는, 이 호출이 성공했을 경우에, 유효한 인터페이스 포인터로 초기화되는 변수의 주소이다.

마지막 파라미터에는, COM 집성체로 사용하는 제어 오브젝트의 IUnknown 인터페이스의 주소를 지정한다. 대부분의 어플리케이션에서는 집성체는 사용되지 않기 때문에, 보통의 경우, 이 파라미터의 값에는 NULL 를 설정한다.

전체의 매니저가 되는 단일의 DirectInput 오브젝트를 생성 하면(자), 「스텝 2 : DirectInput 키보드 디바이스의 생성」에 진행된다.


스텝 2 : DirectInput 키보드 디바이스의 생성

Microsoft® DirectInput® 오브젝트의 생성 후, 어플리케이션은 키보드 오브젝트 (디바이스)를 생성 해,IDirectInputDevice8 인터페이스에의 포인터를 취득할 필요가 있다. 디바이스는, 키보드 관련 태스크의 대부분을, 이 인터페이스의 메소드를 사용해 실행한다.

이 포인터를 취득하려면 , 「샘플 함수 1 : DI_Init 」로 가리키도록(듯이),IDirectInput8::CreateDevice 메소드를 호출하지 않으면 안 된다. CreateDevice 는, 3 개의 파라미터를 취한다.

제 1 파라미터는, 생성 하는 디바이스의 GUID 이다. 시스템키 보드가 사용되기 (위해)때문에, 어플리케이션은 사전에 정의된 글로벌 변수를 GUID_SysKeyboard 에 건네준다.

제 2 파라미터는, 호출이 성공했을 경우에 인터페이스 포인터로 초기화되는 변수의 주소이다.

제 3 파라미터는, COM 집성체로 사용하는 제어 오브젝트의 IUnknown 인터페이스의 주소이다. 대부분의 어플리케이션에서는 집성체는 사용되지 않기 때문에, 보통의 경우, 이 파라미터의 값에는 NULL 를 설정한다.

이하의 코드는,IDirectInputDevice8 인터페이스에의 포인터를 취득하려고 하는 예이다. 실패했을 경우에는,DI_Term 어플리케이션 정의 샘플 함수를 호출해, 기존의 DirectInput 오브젝트가 있으면 그 할당을 해제한다.

주 모든 예의 g_lpdi 는, DirectInput 오브젝트에 대한 초기화된 포인터이다.

HRESULT               hr;
LPDIRECTINPUTDEVICE8  g_lpDIDevice

hr = g_lpDI->CreateDevice(GUID_SysKeyboard, &g_lpDIDevice, NULL);
if FAILED(hr) {
    DI_Term();
    return FALSE;
}

DirectInput 키보드 디바이스를 생성 하면(자), 「스텝 3 : 키보드의 데이터 형식의 설정」하러 진행된다.


스텝 3 : 키보드의 데이터 형식의 설정

IDirectInputDevice8 포인터를 취득하면(자), 「샘플 함수 1 : DI_Init 」에 나타내도록(듯이), 어플리케이션으로 디바이스의 데이터 형식을 설정할 필요가 있다. 키보드의 경우, 이것은 매우 간단한 태스크이다. Microsoft® DirectInput® 에 준비되어 있는 데이터 형식을 c_dfDIKeyboard 글로벌 변수로 지정해,IDirectInputDevice8::SetDataFormat 메소드를 호출한다.

이하의 코드는, 데이터 형식을 설정하려고 하는 예이다. 실패했을 경우에는,DI_Term 샘플 함수를 호출해, 기존의 DirectInput 오브젝트가 있으면 그 할당을 해제한다.

hr = g_lpDIDevice->SetDataFormat(&c_dfDIKeyboard);

if FAILED(hr) {
    DI_Term();
    return FALSE;
}

키보드의 데이터 형식을 설정하면(자), 「스텝 4 : 키보드의 동작의 설정」하러 진행된다.


스텝 4 : 키보드의 동작의 설정

어플리케이션에서는, 키보드에 액세스 하기 전에,IDirectInputDevice8::SetCooperativeLevel 메소드를 사용해, 「샘플 함수 1 : DI_Init 」에 나타내도록(듯이), 디바이스의 동작을 설정할 필요가 있다. 이 메소드는, 디바이스에 관련지을 수 있었던 윈도우에의 핸들과 협조 레벨을 결정하는 플래그의 편성을 받는다. 이 경우, 어플리케이션은 foreground의 비배타 액세스를 요구하고 있다.

이하의 코드는, 디바이스의 협조 레벨을 설정하려고 하는 예이다. 실패했을 경우에는,DI_Term 어플리케이션 정의 샘플 함수를 호출해, 기존의 Microsoft® DirectInput® 오브젝트가 있으면 그 할당을 해제한다.

// 협조 레벨을 설정한다.
hr = g_lpDIDevice->SetCooperativeLevel(g_hwndMain,
                   DISCL_FOREGROUND | DISCL_NONEXCLUSIVE);

if FAILED(hr) {
    DI_Term();
    return FALSE;
}

키보드의 동작을 설정하면(자), 「스텝 5 : 키보드에의 액세스권의 취득」하러 진행된다.


스텝 5 : 키보드에의 액세스권의 취득

키보드의 동작을 설정하면(자), 어플리케이션은,IDirectInputDevice8::Acquire 메소드를 호출해, 디바이스에 대한 액세스권을 취득할 수 있다. 어플리케이션은, 디바이스로부터 데이터를 취득하기 전에, 디바이스를 취득해야 한다. Acquire 메소드에는, 파라미터는 없다.

다음의 샘플 코드는, 「스텝 2 : DirectInput 키보드 디바이스의 생성」으로 생성 한 키보드 디바이스를 취득하는 샘플 코드를 나타내고 있다.

if (g_lpDIDevice) g_lpDIDevice->Acquire();

어플리케이션이 키보드에의 액세스권을 취득하면(자), 「스텝 6 : 키보드로부터의 데이터의 취득」하러 진행된다.


스텝 6 : 키보드로부터의 데이터의 취득

디바이스를 취득하면, 어플리케이션은, 디바이스로부터의 데이터의 취득을 시작 할 수 있다. 데이터를 취득하는 가장 간단한 방법은,IDirectInputDevice8::GetDeviceState 메소드를 호출하는 것이다. 이 메소드는, 디바이스를 호출했을 때의 순간 상태를 취득한다.

GetDeviceState 메소드는 2 개의 파라미터를 취한다. 디바이스 상태 데이터가 설정되는 버퍼의 사이즈와 그 버퍼에의 포인터이다. 키보드의 경우는, 항상, 부호 없음 256 바이트의 버퍼를 선언한다.

이하의 코드는, 키보드 상태를 취득하려고 하는 예이다. 취득에 실패했을 경우, 어플리케이션 정의의 샘플 함수를 호출해, 기존의 Microsoft® DirectInput® 오브젝트가 있으면, 그 할당을 해제한다. 「샘플 함수 2 : DI_Term 」를 참조할것.

키보드의 현재 상태를 취득한 후, 어플리케이션은, 호출시에 밀린 특정의 키에 응답할 수가 있다. 버퍼중의 각 요소가 1 개의 키를 나타낸다. 요소의 상위 비트가 1 의 경우, 그 키는, 호출시에 밀리고 있던 것을 나타낸다. 그 이외의 경우는, 키는 밀리지 않았다. 어느 키 상태를 체크하려면 , DirectInput 의키보드 디바이스 정수를 사용해, 그 키에 대한 버퍼의 인덱스를 생성 한다.

이하의 코드는, 어느 가상의 우주선 게임의 메인 루프로부터 불려 가는 스켈리턴 함수이다. 여기에서는,IDirectInputDevice8::GetDeviceState 메소드를 사용해 키보드를 폴링 한다. 다음에, 디바이스 상태를 취득했을 때에, 좌향 화살표, 오른쪽 방향 화살표, 오름새 화살표, 또는 하향 화살표의 각 키가 밀렸는지 어떠했는지를 체크한다. 이것을 실시하려면 , 이 함수의 본체로 정의되고 있는 KEYDOWN 매크로를 사용한다. KEYDOWN 매크로는, 버퍼의 변수명과 인덱스값을 받은 후, 지정 인덱스에 위치하는 바이트를 체크해 상위 비트가 설정되어 있는지 어떤지를 조사해 설정되어 있는 경우에는 TRUE 를 돌려준다.

void WINAPI ProcessKBInput()
{
    #define KEYDOWN(name, key) (name[key] & 0x80)

    char     buffer[256];
    HRESULT  hr;

    hr = g_lpDIDevice->GetDeviceState(sizeof(buffer), (LPVOID) &buffer);
    if FAILED(hr)
    {
         // 실패의 경우, 디바이스는 없어지고 있다.
         // (hr == DIERR_INPUTLOST)(을)를 체크해,
         // 재취득을 시도할 필요가 있다.
         return;
    }

    // 배를 오른쪽 또는 왼쪽으로 향한다.
    if (KEYDOWN(buffer, DIK_RIGHT));
        // 오른쪽으로 향한다.
    else if(KEYDOWN(buffer, DIK_LEFT));
        // 왼쪽으로 향한다.

    // 배를 진행시킨다, 또는 정지시킨다.
    if (KEYDOWN(buffer, DIK_UP)) ;
        // 배를 전진시킨다.
    else if (KEYDOWN(buffer, DIK_DOWN));
        // 배를 정지시킨다.
}

어플리케이션이 키보드로부터의 데이터를 취득하면(자), 「스텝 7 : DirectInput 시스템의 종료」하러 진행된다.


스텝 7 : DirectInput 시스템의 종료

어플리케이션을 종료하기 직전에, 모든 Microsoft® DirectInput® 오브젝트를 파기할 필요가 있다. 이것은 3 단계의 처리로부터 완성된다.

  • 모든 DirectInput 디바이스의 액세스권을 해방한다 (IDirectInputDevice8::Unacquire )
  • 모든 DirectInput 디바이스를 해방한다 (IDirectInputDevice8::Release)
  • DirectInput 오브젝트를 해방한다 (IDirectInput8::Release)

DirectInput 시스템을 종료시키는 함수의 샘플에 대해서는, 「샘플 함수 2 : DI_Term 」를 참조할것.


샘플 함수 1 : DI_Init

이 어플리케이션 정의 샘플 함수는, Microsoft® DirectInput® 오브젝트를 생성 해 초기화해, 필요한 인터페이스 포인터를 취득해, 그러한 포인터를 글로벌 변수에 할당한다. 초기화가 완료하면(자), 디바이스를 취득한다.

초기화의 어느 부분에서 실패해도, 이 함수는,DI_Term 어플리케이션 정의 샘플 함수를 호출해, 프로그램을 종료할 준비로서 DirectInput 오브젝트와 인터페이스 포인터의 할당을 해제한다 ( 「샘플 함수 2 : DI_Term 」를 참조할것.

DI_Init 함수는, DirectInput 오브젝트를 생성 하는 것에 가세해, 이하의 튜토리얼 순서로 설명되고 있는 태스크를 실행한다.

  • 스텝 2 : DirectInput 키보드 디바이스의 생성
  • 스텝 3 : 키보드의 데이터 형식의 설정
  • 스텝 4 : 키보드의 동작의 설정
  • 스텝 5 : 키보드에의 액세스권의 취득

이하는,DI_Init 함수를 나타내고 있다.

/ * 다음의 변수는 초기화가 끝난 상태라고 보여진다.
HINSTANCE             g_hinst;    // 어플리케이션 인스턴스.
HWND                  g_hwndMain; // 어플리케이션 윈도우.
*/

LPDIRECTINPUT8        g_lpDI;
LPDIRECTINPUTDEVICE8  g_lpDIDevice;

BOOL WINAPI DI_Init()
{
    HRESULT hr;

    // DirectInput 오브젝트를 생성 한다.
    hr = DirectInput8Create(g_hinst, DIRECTINPUT_VERSION,
                            IID_IDirectInput8, (void**) &g_lpDI, NULL);

    if FAILED(hr) return FALSE;

    // IDirectInputDevice8 인터페이스에의 포인터를 취득한다.
    hr = g_lpDI->CreateDevice(GUID_SysKeyboard, &g_lpDIDevice, NULL);

    if FAILED(hr)
    {
        DI_Term();
        return FALSE;
    }

    // IDirectInputDevice8 인터페이스를 보관 유지해,
    // 사용 준비가 갖추어졌더니 있다.

    // 키보드용 DirectInput 오브젝트가 만드는, 사전 정의되었다
    // 키보드 데이터 형식을 이용해, 데이터 형식을 설정한다.

    hr = g_lpDIDevice->SetDataFormat(&c_dfDIKeyboard);

    if FAILED(hr)
    {
        DI_Term();
        return FALSE;
    }

    // 협조 레벨을 설정한다.
    hr = g_lpDIDevice->SetCooperativeLevel(g_hwndMain,
                             DISCL_FOREGROUND | DISCL_NONEXCLUSIVE);
    if FAILED(hr)
    {
        DI_Term();
        return FALSE;
    }

    // 입력 디바이스에 액세스 한다.
    hr = g_lpDIDevice->Acquire();
    if FAILED(hr)
    {
        DI_Term();
        return FALSE;
    }

    return TRUE;
}


샘플 함수 2 : DI_Term

이 어플리케이션 정의 샘플 함수는, 프로그램을 종료할 준비로서 또는 디바이스의 정상적인 초기화가 실패했을 경우의 처리로서 기존의 Microsoft® DirectInput® 인터페이스 포인터의 할당을 해제한다.

/ * 다음의 변수는 초기화가 끝난 상태로 한다.
LPDIRECTINPUT8        g_lpDI;
LPDIRECTINPUTDEVICE8  g_lpDIDevice;
*/

void WINAPI DI_Term()
{
    if (g_lpDI)
    {
        if (g_lpDIDevice)
        {
        // Release()를 호출하기 전은 항상 디바이스를 해방한다.
            g_lpDIDevice->Unacquire();
            g_lpDIDevice->Release();
            g_lpDIDevice = NULL;
        }
        g_lpDI->Release();
        g_lpDI = NULL;
    }
}

그 외의 DirectInput 튜토리얼에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.


튜토리얼 2 : 마우스의 사용법

이 튜토리얼에서는, 마우스 디바이스를 셋업 해, 입력의 버퍼링 데이터를 취득하는 작업을 순서를 쫓아 설명한다. 이 예는,Scrawl 샘플을 베이스로 하고 있다.

마우스 입력의 준비를 실시하려면 , 우선, Microsoft® DirectInput® 오브젝트의 인스턴스를 생성 한다. 다음에,IDirectInput8::CreateDevice 메소드를 사용해,IDirectInputDevice8 인터페이스의 인스턴스를 생성 한다. IDirectInputDevice8 인터페이스의 각 메소드는, 디바이스의 조작, 디바이스의 동작의 설정, 및 데이터의 취득을 실시하기 위해서(때문에) 사용한다.

DirectInput 시스템의 셋업의 준비 순서와 시스템을 종료하는 마지막 순서는, 어느 어플리케이션에서도 같고, 「튜토리얼 1 : 키보드의 사용법」으로 설명하고 있다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : DirectInput 마우스 디바이스의 생성
  • 스텝 2 : 마우스의 데이터 형식의 설정
  • 스텝 3 : 마우스의 동작의 설정
  • 스텝 4 : 마우스로부터의 버퍼링 데이터 입력의 준비
  • 스텝 5 : 마우스에의 액세스권의 관리
  • 스텝 6 : 마우스로부터의 버퍼링 데이터의 취득

주 어플리케이션이 배타 협조 레벨로 마우스를 취득하고 있을 때, Microsoft Windows® 는 마우스 포인터를 화면에 표시하지 않는다. 이 때문에, 어플리케이션에는, 간단한 스프라이트 엔진이 필요하다. Scrawl 샘플 어플리케이션에서는, Microsoft Win32® 함수의 DrawIcon 를 사용해 십자 커서를 화면에 표시한다.


스텝 1 : DirectInput 마우스 디바이스의 생성

Microsoft® DirectInput® 오브젝트를 생성 하면, 어플리케이션은, 마우스 관련 태스크의 대부분을 실행하기 위해서 사용하는 IDirectInputDevice8 인터페이스에의 포인터를 취득할 필요가 있다. 이 포인터를 취득하려면 ,IDirectInput8::CreateDevice 메소드를 호출한다.

CreateDevice 의 제 1 파라미터는, 어플리케이션이 생성 하려고 하고 있는 디바이스의 GUID (글로벌 유니크 식별자) 값이다. 이 경우는 시스템 마우스를 사용하므로, 어플리케이션은, 사전 정의된 글로벌 변수의 GUID_SysMouse 를 건네줄 필요가 있다.

제 2 파라미터는, 이 호출이 성공했을 경우에, 유효한 IDirectInputDevice8 인터페이스 포인터로 초기화되는 변수의 주소이다.

제 3 파라미터는, COM 집성체로 사용하는 제어 오브젝트의 IUnknown 인터페이스의 주소이다. 대부분의 어플리케이션에서는 집성체는 사용되지 않기 때문에, 보통의 경우, 이 파라미터의 값에는 NULL 를 설정한다.

이하의 코드는,IDirectInputDevice8 인터페이스에의 포인터를 취득하려고 하는 예이다. 호출이 실패하면, FALSE 가 돌려주어진다. g_pDI 는,IDirectInput8 에의 유효한 포인터이라고 가정한다.

LPDIRECTINPUTDEVICE g_pMouse;
HRESULT             hr;

hr = g_pDI->CreateDevice(GUID_SysMouse, &g_pMouse, NULL);

if (FAILED(hr)) {
    return FALSE;
}

DirectInput 마우스 디바이스를 생성 하면(자), 「스텝 2 : 마우스의 데이터 형식의 설정」하러 진행된다.


스텝 2 : 마우스의 데이터 형식의 설정

IDirectInputDevice8 포인터를 취득하면(자), 디바이스의 데이터 형식을 설정해야 한다. 마우스의 경우, 이것은 매우 간단한 태스크이다. 작업을 간편하게 하기 위한(해) Microsoft® DirectInput® 에 준비되어 있는 데이터 형식을,c_dfDIMouse 글로벌 변수로 지정해 IDirectInputDevice8::SetDataFormat 메소드를 호출한다.

이하는, 디바이스의 데이터 형식을 설정하려고 하는 코드이다. 호출이 실패하면, FALSE 가 돌려주어진다.

hr = g_pMouse->SetDataFormat(&c_dfDIMouse);

if (FAILED(hr)) {
    return FALSE;
}

마우스의 데이터 형식을 설정하면(자), 「스텝 3 : 마우스의 동작의 설정」하러 진행된다.


스텝 3 : 마우스의 동작의 설정

어플리케이션이 마우스에 대한 액세스권을 취득할 수 있도록(듯이) 하려면 , 미리,IDirectInputDevice8::SetCooperativeLevel 메소드를 사용해 마우스 디바이스의 동작을 설정해야 한다. 이 메소드는, 디바이스에 관련지을 수 있었던 윈도우의 핸들을 받는다. Scrawl 에서는, DISCL_EXCLUSIVE 플래그가 지정되고 있으므로, 마우스 디바이스에 대한 배타 액세스권을 가지는 것은, 이 어플리케이션뿐이다고 하는 것이 보증된다. Scrawl 는, 다른 어플리케이션이 foreground에 있을 때는 데이터 입력을 받아들이지 않기 때문에, 이 플래그는 DISCL_FOREGROUND 와 조합해 사용한다.

이하의 코드는, 디바이스의 협조 레벨을 설정하려고 하는 예이다. 설정에 실패하면, FALSE 가 돌려주어진다. hWnd 는 유효한 윈도우 핸들과 가정한다.

hr = g_pMouse->SetCooperativeLevel(hWnd,
               DISCL_EXCLUSIVE | DISCL_FOREGROUND);

if (FAILED(hr)) {
    return FALSE;
}

마우스의 동작을 설정하면(자), 「스텝 4 : 마우스로부터의 버퍼링 데이터 입력의 준비」하러 진행된다.


스텝 4 : 마우스로부터의 버퍼링 데이터 입력의 준비

Scrawl 어플리케이션은, 이벤트 통지를 사용해 마우스의 동작을 검출하는 방법, 및 마우스로부터의 버퍼링 입력을 읽어내는 방법을 나타내고 있다. 이 방법은 어느쪽이나, 어느 정도의 셋업을 필요로 한다. 그러한 순서는, 마우스 디바이스의 생성 다음에, 마우스 디바이스의 취득전이면 언제라도 실행할 수 있다.

우선, 이벤트를 생성 해, 마우스 디바이스와 관련짓는다. 이것에 의해, 새로운 유효 데이터가 발생한 것을 나타내는 하드웨어 인터럽트가 있으면, 언제라도 마우스 디바이스 오브젝트에 통지하도록(듯이), Microsoft® DirectInput® 에 지시하고 있게 된다.

이하는 Scrawl 에서의 처리 방법이다. 여기서,g_hevtMouse 는 글로벌 HANDLE 이다.

g_hMouseEvent = CreateEvent(NULL, FALSE, FALSE, NULL);

if (g_hMouseEvent == NULL) {
    return FALSE;
}

hr = g_pMouse->SetEventNotification(g_hMouseEvent);

if (FAILED(hr)) {
    return FALSE;
}

이 단계에서 버퍼 사이즈를 설정할 필요가 있다. 이것은, 프로그램이 입력 데이터를 참조할 준비를 할 수 있을 때까지, DirectInput 가 모든 입력 데이터를 저장 할 수 있도록(듯이) 하기 위한(해)이다. 디폴트의 버퍼 사이즈는 제로이기 (위해)때문에, 버퍼링 데이터를 사용하려면 이 순서가 불가결한 것으로 주의한다.

이벤트 통지에 버퍼링 데이터를 사용할 필요는 없다. 필요하면, 이벤트가 송신되었을 때에 직접 데이터를 취득할 수가 있다.

버퍼 사이즈를 설정하려면 ,DIPROPDWORD 구조체를, 구조체 자체에 대한 정보와 설정하고 싶은 프로퍼티에 대한 정보로 초기화한다. 대부분의 값은 정형적인 것이다. 중요한 값은 마지막 dwData 이며, 이것은 버퍼가 보관 유지하는 항목수에 초기화한다.

#define SAMPLE_BUFFER_SIZE  16

DIPROPDWORD dipdw;
    // 헤더
    dipdw.diph.dwSize       = sizeof(DIPROPDWORD);
    dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);
    dipdw.diph.dwObj        = 0;
    dipdw.diph.dwHow        = DIPH_DEVICE;
    // 데이터
    dipdw.dwData            = SAMPLE_BUFFER_SIZE;

다음에, 헤더 (DIPROPDWORD 구조 체내의 DIPROPHEADER 구조체)의 주소라고 변경하고 싶은 프로퍼티의 식별자를, 다음과 같이 IDirectInputDevice8::SetProperty 메소드에 건네준다.

hr = g_pMouse->SetProperty(DIPROP_BUFFERSIZE, &dipdw.diph);

if (FAILED(hr)) {
    return FALSE;
}

이것으로 셋업은 완료해, 언제라도 마우스를 취득해 데이터의 수집을 시작할 수 있다.

어플리케이션에서의 마우스로부터의 버퍼링 데이터 입력의 준비가 끝나면(자), 「스텝 5 : 마우스에의 액세스권의 관리」하러 진행된다.


스텝 5 : 마우스에의 액세스권의 관리

Microsoft® DirectInput® 는, 디바이스의 액세스권을 관리하기 위해서,IDirectInputDevice8::Acquire 및 IDirectInputDevice8::Unacquire 메소드를 제공한다. 어플리케이션은, 우선 Acquire 메소드를 호출해, 디바이스에 대한 액세스권을 취득해야 한다. 다음에,IDirectInputDevice8::GetDeviceState 메소드와 IDirectInputDevice8::GetDeviceData 메소드를 사용해, 마우스 정보를 요구한다.

대부분의 경우, 어플리케이션에는 취득된 상태의 디바이스가 있다. 그러나, foreground 액세스 밖에 가지지 않는 경우는, 어플리케이션이 백그라운드로 이행하면(자) 반드시 마우스는 해방된다. 포커스가 돌아왔을 경우에는, 확실히 디바이스를 재취득할 필요가 있다. 이것은, WM_ACTIVATE 메세지에 반응하는 것으로 실시할 수가 있다.

Scrawl 에서는, 어플리케이션이 포커스를 취득하는지, 또는 잃는지에 맞추어, 글로벌 변수의 g_bActive 를 설정하는 것으로, 이 메세지를 처리하고 있다. 다음에, 헬퍼 함수의 SetAcquire 를 호출한다. 이 헬퍼 함수는,g_bActive 가 TRUE 의 경우에 마우스를 취득해, 그렇지 않은 경우에는 마우스를 해방한다.

case WM_ACTIVATE:
    if (WA_INACTIVE == wParam)
        g_bActive = FALSE;
    else
        g_bActive = TRUE;

    // 액티브 상태에 근거해 마우스에의 배타 모드 액세스를 설정한다.
    SetAcquire();
    return 0;

배타 모드로 액세스 하고 있는 경우, 어플리케이션은 마우스를 해방해, 유저와 Microsoft Windows® 와의 대화 (메뉴나 다이알로그 박스에의 액세스등)를 가능하게 할 필요가 있다. Scrawl 에서는, Alt 키와 Space 키를 동시에 누르는 것으로, 유저가 시스템 메뉴를 열 수가 있다.

Scrawl 의 윈도우 프로시저는, WM_ENTERMENULOOP 에 대한 핸들러를 가지고 있다. 이 핸들러는, 글로벌 변수 g_bActive 에 FALSE 를 설정해 SetAcquire 함수를 호출하는 것으로 응답한다. 이 핸들러를 사용하면(자), Windows 는 마우스를 보관 유지해, 독자적인 커서를 표시할 수가 있다.

유저가 메뉴의 사용을 종료 하면, Windows 는 어플리케이션에 WM_EXITSIZEMOVE 메세지를 보낸다. 이 경우, Scrawl 의 윈도우 프로세스는 적절히 g_bActive 를 설정해,SetAcquire 를 호출한다.

또, Scrawl 는, 쇼트 컷 메뉴를 여는 오른쪽 버튼 클릭에 응답해, 마우스를 해방한다. 마우스는 늦어 해방되지만, WM_ENTERMENULOOP 핸들러에서는, 메뉴가 표시되기 전에 Windows 커서의 위치를 설정할 수 있도록(듯이), 최초로 마우스를 해방하고 있다.

마지막으로, Scrawl 는, 데이터의 취득을 시도해 DIERR_INPUTLOST 에러가 돌려주어지면(자), 마우스의 재취득을 시도한다. 이것은, 다른 개소에서는 처리되지 않는 방법에 따라 디바이스가 해방되었을 경우에의 준비이다. 예를 들어, 유저가 Ctrl + Alt + Del 키를 눌렀을 경우 등이다.

정리하면(자), 어플리케이션은, 마우스로부터 데이터를 취득하기 전에, 마우스를 취득할 필요가 있다. 마우스의 취득은, 어플리케이션에 강제적으로 마우스의 액세스권을 방폐시키는 사태가 발생하지 않는 한, 한 번만 실시하면 끝난다. 배타 모드에서는, Windows 가 마우스를 필요로 할 때, 마우스의 제어를 방폐해야 한다. 또, 마우스의 액세스권을 Windows 또는 그 외의 어플리케이션에 양보한 후, 마우스에 대한 액세스권이 필요하게 되었을 경우는, 마우스를 재취득해야 한다.

어플리케이션이 마우스의 액세스권을 관리하면(자), 「스텝 6 : 마우스로부터의 버퍼링 데이터의 취득」하러 진행된다.


스텝 6 : 마우스로부터의 버퍼링 데이터의 취득

마우스를 취득하면, 어플리케이션은, 마우스로부터의 데이터의 취득을 시작 할 수가 있다.

Scrawl 샘플에서는, 데이터 취득은, 통지된 이벤트가 방아쇠가 된다. 시그널이나 메세지가 있는 것이 MsgWaitForMultipleObjects 로부터 나타날 때까지, 어플리케이션은,WinMain 함수 중(안)에서 sleeve 상태에 들어간다. 마우스 관련의 시그널이 있으면,OnMouseInput 함수가 불려 간다. 이 함수는, 다음의 프로세스로 가리키도록(듯이), 버퍼링 데이터 입력의 처리 방법을 나타내는 좋은 예이다.

우선, 이 함수는, 원의 커서 위치가 완전하게 소거되고 있는 것을 확인한다. Scrawl 는 독자적인 커서를 유지해, 그 드로잉(Drawing)나 소거에 대해서 전면적으로 책임을 가진다.

VOID OnMouseInput(HWND hWnd)
{
    /* 원의 커서를 소거하기 위해(때문에), 무효로 한다. */
    InvalidateCursorRect(hWnd);

여기서, 함수는 루프에 들어가, 버퍼의 전내용에 대한 독해 및 응답을 실시한다. 데이터는 한 번에 1 항목 밖에 취득할 수 없기 때문에, 데이터를 보관 유지하기 위해서는,DIDEVICEOBJECTDATA 구조체가 1 개만 있으면 좋다.

    while (! bDone) {
        DIDEVICEOBJECTDATA od;
        DWORD dwElements = 1;   // 취득해야 할 항목수

주 입력 처리에는 이 밖에도, 버퍼 전체를 한 번에 읽어낸 후, 루프로 취득 항목을 순서에 1 개씩 응답해 나가는 방법이 있다. 그 경우는,dwElements 를 버퍼 사이즈로 해,od 는 그 사이즈에 동일한 수의 요소를 가지는 배열로 한다.

어플리케이션은, 데이터를 취득하기 위해서 IDirectInputDevice8::GetDeviceData 메소드를 호출한다. 제 2 파라미터는 데이터를 두는 위치를, 제 3 파라미터는 필요한 항목수를, Microsoft® DirectInput® 에 각각 통지한다. 데이터를 버퍼에 남겨 두는 경우는, 마지막 파라미터를 DIGDD_PEEK 로 한다. 다만, 이 경우는, 데이터를 재차 필요로 할 것은 없기 때문에 삭제한다.

        hr = g_pMouse->GetDeviceData(sizeof(DIDEVICEOBJECTDATA),
                                     &od, &dwElements, 0);

여기서, 어플리케이션은, 디바이스에 대한 액세스권이 없어지고 있는지 어떤지의 확인 체크를 실시해, 없어지고 있으면 곧바로 최초의 찬스로 마우스의 재취득을 실시하려고 한다. 이 순서는, 「스텝 5 : 마우스에의 액세스권의 관리」로 설명한다.

        if (hr == DIERR_INPUTLOST)
        {
            SetAcquire();
            break;
        }

다음에, 어플리케이션은,GetDeviceData 메소드의 호출이 성공한 것, 및 취득하는 데이터가 실제로 존재한 것을 확인한다. GetDeviceData 의 호출 후, 변수 dwElements 는 실제로 취득한 항목수를 나타내고 있는 것에 주의한다.

        /* 데이터를 읽을 수 없는, 또는 이용 가능 데이터가 없다. */
        if (FAILED(hr) || dwElements == 0)
        {
            break;
        }

여기까지의 프로세스가 종료했을 경우, 호출은 성공해, 버퍼에는 데이터의 항목이 들어가 있다. 여기서, 어플리케이션은,DIDEVICEOBJECTDATA 구조체의 dwOfs 멤버를 조사해 디바이스 위에의 어느 오브젝트가 상태 변화를 보고했는지를 확인한다. 다음에, 헬퍼 함수를 호출해, 적절히 대응한다. 이러한 함수에는 dwData 멤버가 건네받는다. 이 멤버는 디바이스 오브젝트에 무엇이 발생했는지를 저장 한다.

        /* 요소를 조사해 무엇이 발생했는지를 확인한다. */

        switch (od.dwOfs)
        {
            // 마우스의 수평 동작.
            case DIMOFS_X:
                UpdateCursorPosition(od.dwData, 0);
                break;

            // 마우스의 수직 동작.
            case DIMOFS_Y:
                UpdateCursorPosition(0, od.dwData);
                break;

            // DIMOFS_BUTTON0: 오른쪽 버튼이 밀린, 또는 떼어 놓아졌다.
            case DIMOFS_BUTTON0:
            // DIMOFS_BUTTON1:왼쪽 버튼이 밀린, 또는 떼어 놓아졌다.
            case DIMOFS_BUTTON1:
                // 오른쪽 버튼 또는 스왑 된 왼쪽 버튼이 눌러 내릴 수 있고 있을까.
                if((g_bSwapMouseButtons &&
                               DIMOFS_BUTTON1 == od.dwOfs) ||
                   (! g_bSwapMouseButtons &&
                               DIMOFS_BUTTON0 == od.dwOfs))
                {
                    if (od.dwData & 0x80)  // 왼쪽 버튼이 밀리고 있기 (위해)때문에,
                                           // 버튼 압하 모드가 된다.
                    {
                        bDone = TRUE;
                        OnLeftButtonDown(hWnd);
                    }
                // 왼쪽 버튼 또는 스왑 된 오른쪽 버튼이 눌러 내릴 수 있고 있을까.
                if((g_bSwapMouseButtons &&
                               DIMOFS_BUTTON0 == od.dwOfs) ||
                   (! g_bSwapMouseButtons &&
                               DIMOFS_BUTTON1 == od.dwOfs))
                {
                    if(! (od.dwData & 0x80))  // 버튼이 떼어 놓아지고 있기 (위해)때문에,
                                             // 쇼트 컷 메뉴를 체크한다.
                    {
                        bDone = TRUE;
                        OnRightButtonUp(hWnd);
                    }
                }
                break;
        }

마지막으로, 헬퍼 함수의 1 개에 의해 커서가 이동되었을 경우,OnMouseInput 샘플 함수가 커서가 점유 하고 있는 화면의 사각형을 무효로 한다.

    // 새로운 커서가 드로잉(Drawing) 되므로 무효로 한다.
    InvalidateCursorRect(hWnd);
}

또, Scrawl 는,OnLeftButtonDown 함수에 있는 마우스 데이터를 모은다. 이것은, 주버튼이 압하되고 있는 동안, 즉, 유저가 드로잉(Drawing) 하고 있는 동안의 마우스 이동을, 어플리케이션이 추적하는 함수이다. 이 함수는, 이벤트 통지에는 의존하지 않지만, 버튼이 떼어 놓아질 때까지, 연속적으로 DirectInput 버퍼를 폴링 한다.

OnLeftButtonDown 함수에서는, 대기중의 데이터가 모두 읽힐 때까지 드로잉(Drawing)는 행해지지 않는 것에 주의한다. 이것은, 마우스의 수평 방향과 수직 방향의 이동이, 독립한 이벤트로서 보고되기 때문에 있다 (다만, 양이벤트의 버퍼에의 배치는 동시에 행해진다). 독립한 각각의 축이동에 반응해 직선이 즉시 드로잉(Drawing) 되는 경우, 마우스를 비스듬하게 움직이면(자), 직각에 사귀는 2 직선이 드로잉(Drawing) 되게 된다.

어플리케이션의 응답전에, 양축으로 둘 수 있는 이동이 계산에 넣어지고 있는 것을 확인하려면 , x 축항목과 y 축항목의 순서 번호를 체크하는 방법도 있다. 번호가 동일하면, 2 개의 이벤트가 동시에 발생한 것이 된다. 상세한 것에 대하여는, 「타임 스탬프와 순서 번호」를 참조할것.

그 외의 DirectInput 튜토리얼에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.


튜토리얼 3 : 죠이스틱의 사용법

이 튜토리얼은, 시스템에 어태치 된 죠이스틱을 열거해, 입력에 대해서 설정하는 방법을 나타낸다. 샘플 코드는,Joystick 샘플이 베이스가 되어 있다.

Microsoft® DirectInput® 시스템의 설정의 준비 순서와 시스템을 종료하는 마지막 순서는, 어느 어플리케이션에서도 같고, 「튜토리얼 1 : 키보드의 사용법」으로 설명하고 있다.

이 튜토리얼의 최초의 순서는, 디바이스를 열거하는 것, 즉, 사용 가능한 죠이스틱을 확인하는 것이다. 이 처리의 일부로서 각 죠이스틱 디바이스를 초기화해, 필요한 특성을 설정한다. 다음에,IDirectInputDevice8 인터페이스 메소드를 사용해, 각 죠이스틱으로부터 데이터를 취득한다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : 죠이스틱의 열거
  • 스텝 2 : DirectInput 죠이스틱 디바이스의 생성
  • 스텝 3 : 죠이스틱의 데이터 형식의 설정
  • 스텝 4 : 죠이스틱의 동작의 설정
  • 스텝 5 : 죠이스틱에의 액세스권의 취득
  • 스텝 6 : 죠이스틱으로부터의 데이터의 취득


스텝 1 : 죠이스틱의 열거

Microsoft® DirectInput® 시스템을 생성 한 후, 다음의 샘플 코드에 나타내도록(듯이),IDirectInput8::EnumDevices 메소드를 호출해 죠이스틱을 열거한다.

// g_pDI 는, IDirectInput8 에의 초기화 끝난 포인터이다.

g_pDI->EnumDevices(DI8DEVCLASS_GAMECTRL, EnumJoysticksCallback,
                       NULL, DIEDFL_ATTACHEDONLY)

정수 DI8DEVCLASS_GAMECTRL 가 최초의 파라미터로서 건네받아 열거하는 디바이스의 클래스를 지정한다.

EnumJoysticksCallback 는, 죠이스틱이 발견될 때마다 불려 가는 콜백 함수의 주소이다. 「스텝 2 : DirectInput 죠이스틱 디바이스의 생성」에서는, 이 주소로 각 디바이스를 생성 한다.

제 3 파라미터는, 콜백 함수를 사용할 수 있는 임의의 32 비트값이다. 이 경우는, 아무것도 보내지지 않는다.

마지막 파라미터의 DIEDFL_ATTACHEDONLY 는, 열거 대상을 컴퓨터에어태치 되고 있는 디바이스로 한정하는 플래그이다.

죠이스틱을 열거할 수 있으면(자), 「스텝 2 : DirectInput 죠이스틱 디바이스의 생성」에 진행된다.


스텝 2 : DirectInput 죠이스틱 디바이스의 생성

Microsoft® DirectInput® 오브젝트를 생성 한 후는,IDirectInputDevice8 인터페이스에의 포인터를 취득할 필요가 있다. 이 인터페이스는, 죠이스틱 관련 태스크의 대부분으로 사용된다. Joystick 샘플에서는, 콜백 함수 EnumJoysticksCallback 로 이 포인트를 취득한다. 이 함수는, 죠이스틱을 열거할 때마다 불려 간다.

다음의 샘플 코드는, 이 콜백 함수의 최초의 부분이다.

BOOL CALLBACK EnumJoysticksCallback(const DIDEVICEINSTANCE*
                                       pdidInstance, VOID* pContext)
{
    HRESULT hr;

    // 열거된 죠이스틱에의 인터페이스를 취득한다.
    hr = g_pDI->CreateDevice(pdidInstance->guidInstance,
                                &g_pJoystick, NULL);
    if(FAILED(hr))
        return DIENUM_CONTINUE;

    return DIENUM_STOP;

EnumJoysticksCallback 콜백 함수의 파라미터를 다음에 나타낸다.

  • 디바이스 인스턴스에의 포인터. 인스턴스는, 디바이스가 열거되었을 때에 DirectInput 시스템에 의해 공급된다.
  • IDirectInput8::EnumDevices 에 파라미터로서 지정한 32 비트값에의 포인터. 이 파라미터에는, 메소드를 사용할 수 있는 인터페이스에의 포인터이면, 임의의 32 비트값을 지정할 수도 있다. 그러나, 이 예에서는 NULL 가 건네받고 있다.

콜백 함수의 최초의 태스크는, 디바이스를 생성 하는 것이다. IDirectInput8::CreateDevice 메소드는, 3 개의 파라미터를 취한다.

제 1 파라미터는, 디바이스의 인스턴스의 글로벌 유니크 식별자 (GUID)에 대한 참조값이다. 이 경우, GUID 는 DirectInput 가 디바이스를 열거했을 때에 주는 DIDEVICEINSTANCE 구조체로부터 놓친다.

제 2 파라미터는, 호출이 성공했을 경우에, 유효한 인터페이스 포인터로 초기화되는 변수의 주소이다.

제 3 파라미터는, COM 집성체로 사용하는 제어 오브젝트의 IUnknown 인터페이스의 주소이다. Joystick 샘플은 집성체를 사용하지 않기 때문에, 이 파라미터의 값에는 NULL 를 설정한다.

디바이스 인터페이스를 생성 할 수 없는 경우는, 콜백 함수로부터 DIENUM_CONTINUE 가 돌려주어지는 것에 주의한다. 이 플래그는, 열거 대상의 디바이스가 존재하는 한, 열거를 속행하는 것을 DirectInput 에 지시한다.

죠이스틱 디바이스를 생성 하면(자), 「스텝 3 : 죠이스틱의 데이터 형식의 설정」하러 진행된다.


스텝 3 : 죠이스틱의 데이터 형식의 설정

Microsoft® DirectInput® 디바이스에의 포인터를 취득하면(자),IDirectInputDevice8 메소드를 호출해, 그 디바이스를 조작할 수가 있다. 우선, 죠이스틱의 데이터 형식을 설정한다. 이 순서는 불가결하다. 이 순서에서는, DirectInput 에 대해서 입력 데이터의 서식을 설정하는 방법을 지시한다.

if (FAILED(hr = g_pJoystick->SetDataFormat(&c_dfDIJoystick2)))
    return hr;

IDirectInputDevice8::SetDataFormat 메소드의 파라미터는, 디바이스의 데이터의 포맷 방법에 관한 정보를 저장 하는 DIDATAFORMAT 구조체에의 포인터뿐이다. 죠이스틱의 경우, 사전 정의된 글로벌 변수 c_dfDIJoystick2 를 사용할 수 있다. 이 변수에 의해, 데이터 취득을 위한 DIJOYSTATE2 구조체의 사용이 유효하게 된다.

죠이스틱의 데이터 형식을 설정하면(자), 「스텝 4 : 죠이스틱의 동작의 설정」하러 진행된다.


스텝 4 : 죠이스틱의 동작의 설정

지금까지, 죠이스틱 디바이스의 생성과 디바이스의 데이터 형식의 설정이 완료하고 있다. 다음은, 디바이스의 협조 레벨을 설정하는 것이다. 전의 순서와 같이,g_pJoystick 는 디바이스 인터페이스에의 포인터이다.

if (FAILED(hr = g_pJoystick->SetCooperativeLevel(hDlg,
                    DISCL_EXCLUSIVE | DISCL_FOREGROUND)))
    return hr;

IDirectInputDevice8::SetCooperativeLevel 의 최초의 파라미터는 윈도우의 핸들이다. 이 예에서는, 메인 프로그램 윈도우가 되는 다이알로그 박스에의 핸들이 함수에게 건네진다.

마지막 파라미터는, 필요한 협조 레벨을 지정하는 플래그의 편성이다. Joystick 샘플은, 이 샘플이 foreground 어플리케이션 때는, 죠이스틱으로부터의 입력만을 요구한다. 또, 죠이스틱 샘플이 foreground의 경우, 이 어플리케이션이 죠이스틱에 배타적으로 액세스 하는 유일한 어플리케이션이 아니면 안된다. 따라서, 플래그는 DISCL_EXCLUSIVE | DISCL_FOREGROUND 로 설정된다. 이러한 플래그의 상세한 것에 대하여는, 「협조 레벨」을 참조할것.

다음의 순서에서는, 죠이스틱의 능력에 관한 정보를 수집한다. 이 정보에는, 축이나 버튼등의 콘트롤러의 수, force feedback의 지원, 그 외, 죠이스틱의 동작이나 지원 옵션에 관한 상세가 포함된다.

DIDEVCAPS 구조체는, 능력 정보의 보관 유지에 사용된다. 우선,DIDEVCAPS 구조체의 dwSize 멤버를 초기화해, 다음에 그 구조체의 주소가 IDirectInputDevice8::GetCapabilities 에 보내진다. 다음의 예에서는,g_diDevCaps 로 이전에 DIDEVCAPS 구조체가 선언되고 있다.

g_diDevCaps.dwSize = sizeof(DIDEVCAPS);
if (FAILED(hr = g_pJoystick->GetCapabilities(&g_diDevCaps)))
    return hr;

이 시점에서, 디바이스의 디폴트를 사용하는 일도, 디바이스 프로퍼티를 커스터마이즈 할 수도 있다. Joystick 샘플은, 죠이스틱의 축을 열거해,IDirectInputDevice8::EnumObjects 를 호출해, 각 축의 범위를 설정한다.

if (FAILED(hr = g_pJoystick->EnumObjects(EnumAxesCallback,
                                       (VOID*) hDlg, DIDFT_AXIS)))
    return hr;

EnumObjects 메소드의 최초의 파라미터 EnumAxesCallback 는, 열거된 오브젝트를 필요에 따라서 처리하는 콜백 함수의 주소이다.

제 2 파라미터는, 콜백 함수를 사용할 수 있는 임의의 32 비트값이다. 여기서 메인 다이얼로그 윈도우에의 핸들을 건네주어 표시를 갱신해, 죠이스틱에 어느 축이 있는지를 나타낼 수가 있다.

마지막 파라미터 DIDFT_AXIS 는, 콜백 함수에 디바이스의 축만을 열거하도록(듯이) 지정한다.

샘플에서는, 변경된 프로퍼티는, 검출된 축 또는 슬라이더의 범위이다 (슬라이더는 축이라고 보여진다) .

범위를 설정하는 것으로써, 돌려주게 하고 싶은 축의 최대치와 최소 값이 무엇으로 있을까를 DirectInput 에 지시하게 된다. 예의 같게, x 축으로 대해 범위 － 1,000 ~ ＋ 1,000 을 설정 하면, 죠이스틱이 최좌단에 있는 경우에는 － 1,000 을, 최우단에 있는 경우에는 ＋ 1,000 을, 중앙에 있는 경우에는 0 을 각각 돌려주는 것을 요구하게 된다.

다음의 샘플 코드는, 열거하는 축의 범위를 설정한다. 변수 pdidoi 는, 시스템이 콜백 함수에 건네주는 DIDEVICEOBJECTINSTANCE 구조체의 주소이다. 이 변수에는, 현재 열거 되려고 하고 있는 오브젝트에 관한 정보가 저장 되고 있다.

DIPROPRANGE diprg;

diprg.diph.dwSize       = sizeof(DIPROPRANGE);
diprg.diph.dwHeaderSize = sizeof(DIPROPHEADER);
diprg.diph.dwHow        = DIPH_BYID;
diprg.diph.dwObj        = pdidoi->dwType;
diprg.lMin              = -1000;
diprg.lMax              = +1000;
.
.
hr = g_pJoystick->SetProperty(DIPROP_RANGE, &diprg.diph);
if (FAILED(hr))
    return DIENUM_STOP;

여기에서는 최초로,DIPROPRANGE 구조체 diprg 를 설정한다. 그 구조체의 주소는,IDirectInputDevice8::SetProperty 메소드에게 건네진다. 실제로는, 구조체 자체의 주소가 건네받는 것이 아니라, 그 최초의 멤버의 주소가 건네받는다. 최초의 멤버란, 1 개의 DIPROPHEADER 구조체이다. 상세한 것에 대하여는, 「디바이스 프로퍼티」를 참조할것.

프로퍼티 헤더는, 이하의 값으로 초기화된다.

  • 프로퍼티 구조체의 사이즈
  • 헤더 구조체의 사이즈
  • dwObj 멤버의 해석 방법을 나타내는 플래그
  • DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버에 있는 값은, 프로퍼티가 변경 되려고 하고 있는 오브젝트를 나타낸다.

DIPROPRANGE 구조체의 lmin 와 lmax 멤버에 필요한 범위값을 할당한다.

어플리케이션은, 여기서 IDirectInputDevice8::SetProperty 메소드를 호출한다. 최초의 파라미터는, 어느 프로퍼티를 변경하는지를 나타내는 플래그이다. 제 2 파라미터는, 프로퍼티 구조체의 DIPROPHEADER 멤버의 주소이다.

죠이스틱의 동작을 설정하면(자), 「스텝 5 : 죠이스틱에의 액세스권의 취득」하러 진행된다.


스텝 5 : 죠이스틱에의 액세스권의 취득

죠이스틱의 동작을 설정하면(자), 어플리케이션은,IDirectInputDevice8::Acquire 메소드를 호출해, 디바이스에 대한 액세스권을 취득할 수 있다. 어플리케이션은, 디바이스로부터 데이터를 취득하기 전에, 디바이스를 취득해야 한다. Acquire 메소드에는, 파라미터는 없다.

Joystick 샘플은, 어플리케이션이 액티브하게 되면(자), 메시지 루프로 최초의 취득을 실행한다. 또 이 루프는, 어플리케이션이 포커스를 잃은 후에 재취득 하면나무는, 반드시, 디바이스를 자동적으로 재취득한다. 또, 죠이스틱에의 액세스권이 없어졌을 경우, 또는 어플리케이션이 입력 데이터를 취득하려고 했을 때에 DIERR_INPUTLOST 에러가 돌려주어졌을 경우에도, 취득이 실행된다. 이것을, 다음의 샘플 코드에 나타낸다.

hr = g_pJoystick->Poll();
if (FAILED(hr))
{
    hr = g_pJoystick->Acquire();
    while(hr == DIERR_INPUTLOST)
        hr = g_pJoystick->Acquire();
    return S_OK;
}

죠이스틱에의 액세스권을 취득할 수 있으면(자), 「스텝 6 : 죠이스틱으로부터의 데이터의 취득」하러 진행된다.


스텝 6 : 죠이스틱으로부터의 데이터의 취득

어플리케이션에서는, 죠이스틱축의 이동보다, 죠이스틱축의 위치가 중요하다라고 하는 것이 많기 때문에, 디바이스로부터는, 버퍼링 데이터보다 직접 데이터를 취득하는 것이 자주(잘) 행해진다. 직접 데이터는,IDirectInputDevice8::GetDeviceState 로 폴링 하는 것에 의해 취득할 수 있다. 디바이스 상태가 변화했을 때, 모든 디바이스 드라이버가 Microsoft® DirectInput® 에 통지하는 것은 아닌 것에 주의한다. 따라서, 디바이스 상태를 확인하기 전에 IDirectInputDevice8::Poll 메소드를 호출하는 것을 권한다.

Joystick 어플리케이션은, Microsoft® Windows® 메시지 루프로부터 다음의 함수를 호출한다.

HRESULT UpdateInputState(HWND hDlg)
{
    HRESULT     hr;
    CHAR        strText[128]; // 디바이스 상태의 텍스트.
    DIJOYSTATE2 js;           // Direct Input 죠이스틱 상태.
    CHAR*       str;

    if (NULL == g_pJoystick)
        return S_OK;

    // 현재 상태를 읽어내는 디바이스를 폴링 한다.
    hr = g_pJoystick->Poll();
    if (FAILED(hr))
    {
        // 죠이스틱의 재취득을 시도한다.
    }
    hr = g_pJoystick->GetDeviceState(sizeof(DIJOYSTATE2), &js);
    if (FAILED(hr))
        return hr;

GetDeviceState 의 호출에 주의한다. 최초의 파라미터는, 데이터가 돌려주어지는 구조체의 사이즈이다. 제 2 의 파라미터는,DIJOYSTATE2 형인 이 구조체의 주소이다. 이 구조체는, 최고 6 개의 축, 128 의 버튼, 및 4 개의 시점 하트를 보관 유지한다. 샘플 프로그램은, 모든 축과 버튼, 및 1 개의 슬라이더 상태를 확인한다. 다음에 이 정보가, 메인 다이얼로그 윈도우에 표시된다.

죠이스틱 버튼은, 키 또는 mouse button와 완전히 똑같이 기능한다. 반환값 바이트의 상위 비트가 1 의 경우는, 버튼이 밀리고 있는 것을 나타낸다.

그 외의 DirectInput 튜토리얼에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.


튜토리얼 4 : force feedback의 사용법

이 튜토리얼에서는, force feedback 죠이스틱으로 단순한 이펙트를 생성, 재생, 변경하는 순서를 나타낸다. 이펙트는, chain saw의 동작을 본뜨고 있다. 이펙트는, chain saw 그림의 기법 여기 없게 움직이기 시작해 보통 대로 움직여 목이 채 안되어 가는 모습을 시뮬레이트 하도록(듯이) 생성 되고 있다.

Microsoft® DirectInput® 시스템의 설정의 준비 순서와 시스템을 종료하는 마지막 순서는, 어느 어플리케이션에서도 기본적으로 같고, 이것에 대해서는 「튜토리얼 1 : 키보드의 사용법」으로 설명하고 있다. 그러나, DirectInput force feedback 시스템을 종료 하면나무는, 생성한 이펙트를 해제하는 순서를 추가할 필요가 있다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : force feedback 디바이스의 열거
  • 스텝 2 : DirectInput force feedback 디바이스의 생성
  • 스텝 3 : 지원 되는 이펙트의 열거
  • 스텝 4 : 이펙트의 생성
  • 스텝 5 : 무한 이펙트의 재생
  • 스텝 6 : 이펙트의 변경


스텝 1 : force feedback 디바이스의 열거

최초의 순서는, force feedback 디바이스를 시스템으로 이용할 수 있도록(듯이) 하는 것이다. 이것을 실시하려면 IDirectInput8::EnumDevices 메소드를 호출한다. 다음의 예에서는, 열거가 적어도 1 개의 적합하는 디바이스를 찾아낼 수가 있었을 경우만, 게임 디바이스 인터페이스에의 글로벌 포인터가 초기화된다.

LPDIRECTINPUTDEVICE8  g_lpDIDevice = NULL;

hr = g_lpDI->EnumDevices(DI8DEVTYPE_GAMECTRL,
                         DIEnumDevicesProc,
                         NULL,
                         DIEDFL_FORCEFEEDBACK | DIEDFL_ATTACHEDONLY);
if (FAILED(hr))
{
  // force feedback 죠이스틱을 이용할 수 없다.
}

이 예에서는,g_lpDI 는 IDirectInput8 인터페이스에의 초기화가 끝난 포인터이다. EnumDevices 의 제 1 파라미터에 의해, 열거 대상이 죠이스틱류의 디바이스로 한정된다. 제 2 파라미터는, Microsoft® DirectInput® 이 열거에 적합한 디바이스를 식별했을 때에 반드시 불려 가는 콜백 함수이다. 제 3 파라미터는, 콜백 함수에게 건네진다, 또는 콜백 함수로부터 건네받는 유저 정의 데이터를 나타낸다. 이 예에서는 사용되어 있지 않다. 마지막으로, 제 4 파라미터의 플래그에 의해, 열거 대상이, force feedback를 지원 하는 시스템에 실제로 어태치 되고 있는 디바이스로 한정된다.

콜백 함수는, 디바이스가 발견되자마자 그 디바이스를 초기화하는데 편리하다 (최초로 발견되었던 것이 사용하고 싶은 디바이스인 것을 전제로 하고 있다). 이것은, 「스텝 2 : DirectInput force feedback 디바이스의 생성」으로 실시하게 된다.


스텝 2 : DirectInput force feedback 디바이스의 생성

Microsoft® DirectInput® 에 디바이스를 열거시키려면 ,DIEnumDevicesCallback 와 같은 형태의 콜백 함수를 생성 한다. 스텝 1 에서는, 이 함수의 주소를 IDirectInput8::EnumDevices 메소드에 건네주고 있다.

DirectInput 는, 알 필요가 있는 디바이스에 대한 정보를 통지하는 DIDEVICEINSTANCE 구조체에의 포인터를, 제 1 파라미터로서 콜백 함수에 건네준다. 다음의 예로 가장 중요한 구조체 멤버는 guidInstance 이며, 이것은, 유저의 시스템으로 특정의 하드웨어를 식별하는 유일한 수단이다. 이 GUID 는 IDirectInput8::CreateDevice 메소드에 건네줄 필요가 있다.

다음의 샘플 코드는, 콜백 함수의 최초의 부분이며, GUID 를 꺼내 디바이스 오브젝트를 생성 한다.

BOOL CALLBACK DIEnumDevicesProc( LPCDIDEVICEINSTANCE lpddi,
                                 LPVOID pvRef )
{
    HRESULT hr;
    GUID DeviceGuid = lpddi->guidInstance;

    // 게임 디바이스를 생성한다.

    hr = g_lpDI->CreateDevice(DeviceGuid, &g_lpDIDevice, NULL);

    if (FAILED(hr))
        // 성공 또는 종료할 때까지 열거를 계속한다.
        return DIENUM_CONTINUE;

콜백 함수의 다음의 순서는, 입력 디바이스의 설정 순서에 유사하고 있다. 주의 해야 할 것은, 어느 force feedback 디바이스에 있어서도 배타 협조 레벨이 필요하다라고 말하는 것이다.

    // 협조 레벨을 설정한다.
    hr = g_lpDIDevice->SetCooperativeLevel(g_hwndMain,
                                  DISCL_EXCLUSIVE | DISCL_FOREGROUND);
    if (FAILED(hr))
        return hr;

    // 게임 데이터 형식의 설정.
    hr = g_lpDIDevice->SetDataFormat(&c_dfDIJoystick);
    if (FAILED(hr))
        return hr;

마지막으로, 디바이스의 자동 센터링 기능을 오프로 할 수 있다. 기본적으로 자동 센터링 기능은, 모터를 사용해 표준 죠이스틱으로 스프링을 시뮬레이트 하는 조건 이펙트이다. 이 기능을 오프로 하면(자), 다른 이펙트가 방해되지 않게 된다.

    DIPROPDWORD DIPropAutoCenter;

    DIPropAutoCenter.diph.dwSize       = sizeof(DIPropAutoCenter);
    DIPropAutoCenter.diph.dwHeaderSize = sizeof(DIPROPHEADER);
    DIPropAutoCenter.diph.dwObj        = 0;
    DIPropAutoCenter.diph.dwHow        = DIPH_DEVICE;
    DIPropAutoCenter.dwData            = DIPROPAUTOCENTER_OFF;

    hr = g_lpDIDevice->SetProperty(DIPROP_AUTOCENTER,
                                   &DIPropAutoCenter.diph);
    if (FAILED(hr))
    {
        // 적당 실패를 처리한다.
    }

    return DIENUM_STOP;   // 1 개(살)로 충분히.
}   // DIEnumDevicesProc 의 종료.

사용전에, 디바이스를 취득해야 한다. 취득 방법의 예에 대해서는, 「튜토리얼 3 : 죠이스틱의 사용법」의 「스텝 5 : 죠이스틱에의 액세스권의 취득」을 참조할것. 다른 프로퍼티 변경과는 달라, force feedback 이펙트는 취득 상태로 디바이스에 다운로드할 수 있는 것에 주의한다.

DirectInput force feedback 디바이스를 생성 하면(자), 「스텝 3 : 지원 되는 이펙트의 열거」하러 진행된다.


스텝 3 : 지원 되는 이펙트의 열거

지금까지 force feedback 디바이스의 열거와 생성에 성공했으므로, 그 디바이스가 지원 하는 이펙트의 타입을 열거할 수가 있다.

어느 디바이스에서도 이용 가능한 표준적 이펙트만을 생성하고 싶은 경우는, 이펙트의 열거는 반드시 필요하지 않다. 이펙트 오브젝트를 생성 하면 와,GUID_ConstantForce등의 정의가 끝난 GUID 중 어떤 것이나 1 개를 사용해, 목적의 이펙트 타입을 간단하게 식별할 수가 있다. 이러한 식별자의 전리스트에 대해서는, 「IDirectInputDevice8::CreateEffect 」를 참조할것.

좀 더 유연성이 있는 방법은, 특정 타입의 지원 되는 이펙트를 열거해, 콜백 함수로부터 이펙트에 대한 GUID 를 취득하는 것이다. 물론, 콜백 함수를 사용해, 이펙트에 대한 디바이스의 지원에 대한 상세 정보 (예를 들어, 디바이스가포락선을 지원 하고 있을지 어떨지에 임해서)를 얻을 수도 있지만, 이 튜토리얼에서는 이펙트 GUID 만을 취득하기로 한다.

우선, 열거된 이펙트 각각 붙어, Microsoft® DirectInput® 에 의해 불려 가는 콜백 함수를 생성한다. 이 표준 콜백의 정보에 대해서는, 「DIEnumEffectsCallback 」를 참조할것. 이 함수에는 좋아하는 이름을 붙일 수가 있다.

BOOL  EffectFound = FALSE;  // 글로벌 플래그.

BOOL CALLBACK DIEnumEffectsProc(LPCDIEFFECTINFO pei, LPVOID pv)
{
    *((GUID *) pv) = pei->guid;
    EffectFound = TRUE;
    return DIENUM_STOP;  // 1 개(살)로 충분히.
}

어플리케이션으로 정의된 값 pv 가 가리키는 GUID 변수에는, 이펙트를 위해서(때문에) DirectInput 가 생성하는 DIEFFECTINFO 구조체에 건네받는 값이 대입된다.

이펙트 GUID 를 취득하기 위해서, 다음과 같이 IDirectInputDevice8::EnumEffects 메소드를 호출해, 콜백을 시작 한다.

HRESULT  hr;
GUID     guidEffect;

hr = g_lpDIDevice->EnumEffects(
                         (LPDIENUMEFFECTSCALLBACK) DIEnumEffectsProc,
                          &guidEffect,
                          DIEFT_PERIODIC);
if (FAILED(hr))
{
    // 성공해도 이펙트가 발견되었다고는 할 수 없기 때문에 주의한다.
    // 단지 처리가 순조롭게 행해진 것을 의미한다.
}

GUID 변수의 주소 guidEffect 를 EnumEffects 메소드에 건네주는 것에 주의 해야 한다. 이 주소는, 콜백 함수에 pv 파라미터로서 건네받는다. 게다가 DIEFT_PERIODIC 플래그를 설정해, 열거 대상을 주기적 이펙트로 한정한다.

지원 되는 이펙트를 열거할 수 있으면(자), 「스텝 4 : 이펙트의 생성」에 진행된다.


스텝 4 : 이펙트의 생성

이펙트의 열거 후 EffectFound 의 값이 FALSE 가 아니면, 필요한 이펙트 타입의 적어도 1 개(살)에 대한 지원을 Microsoft® DirectInput® 가 발견했다고 봐도 좋다. 이펙트 GUID 를 알 수 있고 있으므로, 이번은 이펙트 오브젝트를 생성할 수가 있다.

IDirectInputDevice8::CreateEffect 메소드를 호출하기 전에, 다음의 배열과 구조체를 설정할 필요가 있다.

  • 이펙트와 관계되는 축의 배열. 죠이스틱의 경우, 이 배열은 보통 x 축과 y 축으로 대하는 식별자로부터 된다.
  • 방향을 설정하는 값의 배열. 이러한 값은, 축의 수로 사용하는 좌표의 종류 (극좌표, 구(공)장 좌표, 데카르트 좌표)에 응해 다르다. 상세한 것에 대하여는, 「이펙트의 방향」을 참조할것.
  • 타입 고유 파라미터의 구조체. 예에서는, 주기적 이펙트를 생성하고 있으므로, 구조체의 형태는 DIPERIODIC 가 되고 있다.
  • 이펙트에 적용하는포락선을 정의하는 DIENVELOPE 구조체.
  • 이펙트의 기본적 파라미터를 저장 하는 DIEFFECT 구조체.

배열은, 구조체와 함께, 선언할 경우에 초기화할 수 있다.

DWORD      dwAxes[2] = {DIJOFS_X, DIJOFS_Y};
LONG       lDirection[2] = {0, 0};

DIPERIODIC diPeriodic;      // 타입 고유 파라미터.
DIENVELOPE diEnvelope;      // 포락선.
DIEFFECT   diEffect;        // 범용 파라미터.

다음에 형태 고유의 파라미터를 초기화한다. 이 예의 값은, 1 초의 20 분의 1 의 주기로, 풀 포스의 주기적 이펙트를 생성 한다.

diPeriodic.dwMagnitude = DI_FFNOMINALMAX;
diPeriodic.lOffset = 0;
diPeriodic.dwPhase = 0;
diPeriodic.dwPeriod = (DWORD)(0.05 * DI_SECONDS);

chain saw의 모터가 시동하려고 해, 당분간 기침과 같은 소리를 내, 점차 그것이 들어간다고 하는 이펙트를 얻기 위해서(때문에), 포락선에 반초간의어택 시간과 1 초간의페이드 시간을 설정한다.

diEnvelope.dwSize = sizeof(DIENVELOPE);
diEnvelope.dwAttackLevel = 0;
diEnvelope.dwAttackTime = (DWORD)(0.5 * DI_SECONDS);
diEnvelope.dwFadeLevel = 0;
diEnvelope.dwFadeTime = (DWORD)(1.0 * DI_SECONDS);

다음에, 기본적인 이펙트 파라미터를 설정한다. 이러한 파라미터에는, 방향과 디바이스 오브젝트 (버튼과 축)의 식별 방법을 결정하는 플래그, 이펙트의 샘플 주기와 게인, 및 조금 전 준비한 다른 데이터에의 포인터가 포함된다. 게다가 죠이스틱의 발사 버튼에 이펙트를 할당해, 버튼을 누르면 이펙트가 자동적으로 재생하도록(듯이) 한다.

diEffect.dwSize = sizeof(DIEFFECT);
diEffect.dwFlags = DIEFF_POLAR | DIEFF_OBJECTOFFSETS;
diEffect.dwDuration = (DWORD)(2 * DI_SECONDS);

diEffect.dwSamplePeriod = 0;               // 디폴트 설정.
diEffect.dwGain = DI_FFNOMINALMAX;         // 스케일링 없음.
diEffect.dwTriggerButton = DIJOFS_BUTTON0;
diEffect.dwTriggerRepeatInterval = 0;
diEffect.cAxes = 2;
diEffect.rgdwAxes = dwAxes;
diEffect.rglDirection = &lDirection[0];
diEffect.lpEnvelope = &diEnvelope;
diEffect.cbTypeSpecificParams = sizeof(diPeriodic);
diEffect.lpvTypeSpecificParams = &diPeriodic;

마지막으로, 이펙트를 생성 한다.

LPDIRECTINPUTEFFECT  g_lpdiEffect;  // 글로벌 이펙트 오브젝트.

hr = g_lpDIDevice->CreateEffect(
                     guidEffect,     // 열거로부터의 GUID.
                     &diEffect,      // 데이터의 장소.
                     &g_lpdiEffect,  // 인터페이스 포인터를 두는 장소.
                     NULL);          // 집성체 없음.
if (FAILED(hr))
{
    return hr;
}

디바이스가 배타 협조 레벨로 취득된 상태에 있으면, 디폴트에서는, 이 이펙트는 생성되는 것과 동시에 디바이스에 다운로드되는 것에 주의한다. 이것을 컴파일 해 실행해, 발사 버튼을 누르면(자), 연료가 끊어진 chain saw가 프스프스 말하는 모습을 느낄 수가 있다.

이펙트 오브젝트를 생성 하면(자), 「스텝 5 : 무한 이펙트의 재생」하러 진행된다.


스텝 5 : 무한 이펙트의 재생

전의 스텝에서 생성한 이펙트는 버튼 압하에 응답해 시동한다. 명시적인 호출해에 응답해 재생되는 이펙트를 생성 하려면 , 「스텝 4 : 이펙트의 생성」에 돌아와,DIEFFECT 구조체의 dwTriggerButton 멤버를 다음과 같이 수정한다.

diEffect.dwTriggerButton = DIEB_NOTRIGGER;

동작 시작 후, 그대로의 동작을 계속하는 chain saw를 생성 하려면 ,dwDuration 멤버를 다음과 같이 변경한다.

diEffect.dwDuration = INFINITE;

다음에 이펙트를 시작 한다.

g_lpdiEffect->Start(1, 0);

이 이펙트는 중지할 때까지 계속 일한다.

g_lpdiEffect->Stop();

전의 스텝에서 생성한포락선은 변경할 필요가 없는 것에 주의한다. 어택은 이펙트가 시동 하면 재생하지만,페이드값은 무시된다.

어플리케이션이 무한 이펙트를 재생할 수 있으면(자), 「스텝 6 : 이펙트의 변경」하러 진행된다.


스텝 6 : 이펙트의 변경

다음에, 이펙트를 수정해, 목이 채 안되는 것에 따라 chain saw의 엔진의 회전이 늦어지도록(듯이) 한다. Microsoft® DirectInput® 에서는, 재생중에 이펙트의 파라미터를 수정할 수 있다.

이 이펙트를 변경하려면 , 새로운DIEFFECT 구조체를 설정하는지, 또는 이 이펙트의 생성에 사용한 구조체에 액세스 한다. 유효한 새로운 구조체를 로컬로 설정하는 경우는,dwSize 멤버라고 변경하는 데이터를 포함한 또는 그 데이터를 가리키는 멤버만을 초기화하면 좋다.

이 예에서는, 형태 고유 파라미터의 이펙트의 주기를 변경하기 위해(때문에), 이펙트의 생성에 사용한 DIPERIODIC 구조체에의 액세스가 필요하게 된다. 모든 멤버를 초기화한 로컬 카피를 생성 하는 방법도 있다. DIPERIODIC 구조체의 주소가 DIEFFECT 구조체의 멤버 lpvTypeSpecificParams 에 저장 되고 있는 것을 확인한다.

우선, 이펙트의 새로운 주기를 설정한다.

diPeriodic.dwPeriod = (DWORD)(0.08 * DI_SECONDS);

다음에,IDirectInputEffect::SetParameters 메소드를 호출해, 변경을 더한다.

hr = g_lpdiEffect->SetParameters(&diEffect, DIEP_TYPESPECIFICPARAMS);

이 변경을 DIEFFECT 구조체의 1 개의 멤버로 한정하고 있는 DIEP_TYPESPECIFICPARAMS 플래그에 주의 해야 한다.

다른 플래그를 사용해, 변경의 방법을 제어할 수가 있다. 예를 들어, DIEP_NODOWNLOAD 플래그를 사용하면(자), 이펙트의 시동 직후로 파라미터를 변경할 수 있지만,IDirectInputEffect::Download 메소드를 호출할 때까지 이행은 늦는다. 다양한 제어 플래그의 사용에 관한 상세한 것에 대하여는, 「IDirectInputEffect::SetParameters 」를 참조할것.

그 외의 DirectInput 튜토리얼에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.


튜토리얼 5 : 액션 매핑의 사용법

이 튜토리얼에서는, 액션 맵의 설정, 수정, 및 적용에 대해 설명한다. 이 예는, 우주전 게임에서 사용되는 경우를 상정하고 있다.

Microsoft® DirectInput® 시스템의 설정의 준비 순서와 시스템을 종료하는 마지막 순서는, 어느 어플리케이션에서도 같고, 「튜토리얼 1 : 키보드의 사용법」으로 설명하고 있다. 샘플에서는, 키보드, 마우스, 및 죠이스틱의 모든 것이 사용되고 있기 (위해)때문에, 각각을 설정할 필요가 있다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : 게임 액션의 정의
  • 스텝 2 : 액션 맵의 정의
  • 스텝 3 : 디바이스에의 액션의 매핑
  • 스텝 4 : 액션 맵의 구성과 적용
  • 스텝 5 : 액션 맵의 표시
  • 스텝 6 : 액션 맵의 유저 구성
  • 스텝 7 : 액션 매핑 된 데이터의 취득


스텝 1 : 게임 액션의 정의

액션 맵 생성의 최초의 순서는, 게임 액션의 정의이다. 이러한 액션은 어플리케이션 고유하고, 개발자가 정의한다. 이 예에서는, 액션은 우주전 시뮬레이터로서의 필요성을 생각해 선택되고 있다. 이러한 값은, 개발자가 적절이라고 생각하는 여러가지 방법으로 정의할 수 있다. 액션은,액션 맵의 준비의 개요에 나타내도록(듯이) 열거로서 정의하거나 이 코드와 같이 정수로서 정의할 수가 있다.

#define INPUT_LEFTRIGHT_AXIS   1L
#define INPUT_UPDOWN_AXIS      2L
#define INPUT_TURNLEFT         3L
#define INPUT_TURNRIGHT        4L
#define INPUT_FORWARDTHRUST    5L
#define INPUT_REVERSETHRUST    6L
#define INPUT_FIREWEAPONS      7L
#define INPUT_ENABLESHIELD     8L
#define INPUT_DISPLAYGAMEMENU  9L
#define INPUT_QUITGAME        10L

액션의 값을 정의하면(자), 그것을 장르 고유의 액션 매핑 정수에 할당한다. 이것에 대해서는, 「스텝 2 : 액션 맵의 정의」로 설명한다.


스텝 2 : 액션 맵의 정의

다음에, 각 게임 액션을, 1 개의 가상 컨트롤 또는 디바이스 오브젝트에 할당한다. 이러한 컨트롤은 액션 매핑 정수로서 정의되어 장르 및 서브 장르에 의해 정의된다. 이 예에서는, 플라이트 게임 장르의우주전 서브 장르를 선택하는 것이 적절하다. 이 서브 장르에서는, 이하의 정수를 사용할 수 있다.

우선 순위 1 의 컨트롤

DIAXIS_SPACESIM_LATERAL
DIAXIS_SPACESIM_MOVE
DIAXIS_SPACESIM_THROTTLE
DIBUTTON_SPACESIM_FIRE
DIBUTTON_SPACESIM_MENU
DIBUTTON_SPACESIM_TARGET
DIBUTTON_SPACESIM_WEAPONS

우선 순위 2 의 컨트롤

DIAXIS_SPACESIM_CLIMB
DIAXIS_SPACESIM_ROTATE
DIBUTTON_SPACESIM_BACKWARD_LINK
DIBUTTON_SPACESIM_DEVICE DIBUTTON_SPACESIM_DISPLAY
DIBUTTON_SPACESIM_FASTER_LINK
DIBUTTON_SPACESIM_FIRESECONDARY
DIBUTTON_SPACESIM_FORWARD_LINK
DIBUTTON_SPACESIM_GEAR
DIBUTTON_SPACESIM_GLANCE_DOWN_LINK
DIBUTTON_SPACESIM_GLANCE_LEFT_LINK
DIBUTTON_SPACESIM_GLANCE_RIGHT_LINK
DIBUTTON_SPACESIM_GLANCE_UP_LINK
DIBUTTON_SPACESIM_LEFT_LINK DIBUTTON_SPACESIM_LOWER
DIBUTTON_SPACESIM_PAUSE DIBUTTON_SPACESIM_RAISE
DIBUTTON_SPACESIM_RIGHT_LINK
DIBUTTON_SPACESIM_SLOWER_LINK
DIBUTTON_SPACESIM_TURN_LEFT_LINK
DIBUTTON_SPACESIM_TURN_RIGHT_LINK
DIBUTTON_SPACESIM_VIEW
DIHATSWITCH_SPACESIM_GLANCE

우선 순위 1 의 컨트롤은 최저한 필요한 컨트롤로, 가능한 한 데바이스오브제트에 매핑 할 필요가 있다. 우선 순위 2 의 컨트롤은, 기본적인 게임 조작에는 그만큼 중요하지 않고, 필요에 따라서 매핑 할 수 있다.

게임 액션은,DIACTION 구조체의 배열에 있는 액션 매핑 정수 컨트롤에 할당할 수 있다. 각 DIACTION 구조체는, 최저 1 개의 게임 액션과 거기에 관련하는 액션 매핑 정수, 필요한 플래그, 그리고, 액션의 알기 쉬운 이름이나 ID 캐릭터 라인을 저장 하고 있다. 나머지의 DIACTION 멤버는, 이 시점에서는 사용하지 않는다. 다음의 샘플 코드는,DIACTION 구조체의 배열의 정의를 나타내고 있다.

#define NUMBER_OF_ACTIONS 18

DIACTION g_rgGameAction[NUMBER_OF_ACTIONS] =
{
    // 디바이스 입력은, 장르에 응해 DInput 로 정의가 끝난 상태.
    {INPUT_LEFTRIGHT_AXIS, DIAXIS_SPACESIM_LATERAL, 0, "Turn",},
    {INPUT_UPDOWN_AXIS, DIAXIS_SPACESIM_MOVE, 0, "Move",},
    {INPUT_FIREWEAPONS, DIBUTTON_SPACESIM_FIRE, 0, "Shoot",},
    {INPUT_ENABLESHIELD, DIBUTTON_SPACESIM_GEAR, 0, "Shield",},
    {INPUT_DISPLAYGAMEMENU, DIBUTTON_SPACESIM_DISPLAY, 0, "Display",},
    {INPUT_QUITGAME, DIBUTTON_SPACESIM_MENU, 0, "Quit Game",},

    // 키보드 입력 매핑.
    {INPUT_TURNLEFT, DIKEYBOARD_LEFT, 0, "Turn left", },
    {INPUT_TURNRIGHT, DIKEYBOARD_RIGHT, 0, "Turn right", },
    {INPUT_FORWARDTHRUST, DIKEYBOARD_UP, 0, "Forward thrust", },
    {INPUT_REVERSETHRUST, DIKEYBOARD_DOWN, 0, "Reverse thrust", },
    {INPUT_FIREWEAPONS, DIKEYBOARD_F, 0, "Fire weapons", },
    {INPUT_ENABLESHIELD, DIKEYBOARD_S, 0, "Enable shields", },
    {INPUT_DISPLAYGAMEMENU, DIKEYBOARD_D, DIA_APPFIXED,
                                      "Display game menu"), },
    {INPUT_QUITGAME, DIKEYBOARD_ESCAPE, DIA_APPFIXED, "Quit game", },

    // 마우스 입력 매핑.
    {INPUT_LEFTRIGHT_AXIS, DIMOUSE_XAXIS, 0, "Turn", },
    {INPUT_UPDOWN_AXIS, DIMOUSE_YAXIS, 0, "Move", },
    {INPUT_FIREWEAPONS, DIMOUSE_BUTTON0, 0, "Fire weapons", },
    {INPUT_ENABLESHIELD, DIMOUSE_BUTTON1, 0, "Enable shields", },
};

다음에 DIACTIONFORMAT 구조체가 초기화되어 전에 정의 DIACTION 배열 g_rgGameAction 가 저장 된다. 또 DIACTIONFORMAT 구조체는, 장르, 버퍼 사이즈, 축스케일링, 및 액션 맵의 알기 쉬운 이름을 정의한다. g_AppGuid 값은 어플리케이션으로 정의된 GUID 로, 액션 맵을 식별한다. GUID 의 생성 방법의 상세한 것에 대하여는, 「GUID 의 사용법」을 참조할것.

DIACTIONFORMAT diaf;
diaf.dwSize        = sizeof(DIACTIONFORMAT);
diaf.dwActionSize  = sizeof(DIACTION);
diaf.dwDataSize    = NUMBER_OF_ACTIONS * sizeof(DWORD);
diaf.dwNumActions  = NUMBER_OF_ACTIONS;
diaf.guidActionMap = g_AppGuid;
diaf.dwGenre       = DIVIRTUAL_SPACESIM;
diaf.rgoAction     = g_rgGameAction;
diaf.dwBufferSize  = 16;
diaf.lAxisMin      = -100;
diaf.lAxisMax      = 100;
diaf.tszActionMap  = "DI Test";

이 DIACTIONFORMAT 구조체가 열거된 디바이스와 조합되어 「스텝 3 : 디바이스에의 액션의 매핑」으로 최적의 편성이 조사할 수 있다.


스텝 3 : 디바이스에의 액션의 매핑

목적의 매핑을 정의할 수 있으면(자), 물리적 디바이스에 적용할 필요가 있다. IDirectInput8::EnumDevicesBySemantics 는, 다음의 코드로 이 프로세스를 시작 한다. 여기서,m_pDI 는 이전에 정의된 IDirectInput8 오브젝트이다.

HRESULT hr;
hr = m_pDI->EnumDevicesBySemantics(m_strUserName, &m_diaf,
                                EnumSuitableDevicesCB, this, 0L);

최초의 파라미터 m_strUserName 는, 매핑의 설정이 다른 복수의 유저를 대상으로 하는 경우에 유용하다. 다만, 이 예에서는 이 값에는 NULL 를 설정해, 현재 시스템에 로그 온 되고 있는 유저를 나타낸다.

제 2 파라미터는, 매핑 정보를 저장 하는 DIACTIONFORMAT 구조체의 주소이다.

제 3 파라미터는, 시스템상에서 디바이스가 발견될 때마다 불려 가는 콜백 함수의 주소이다. 샘플로 사용되고 있는 함수는,DIEnumDevicesBySemanticsCallback 함수에 근거하고 있다.

제 4 파라미터는, 콜백 함수를 사용할 수 있는 임의의 32 비트값이다. 이 예에서는 this 포인터이며, 이것은, MultiMapper 샘플로, 여러가지 액션 매핑의 설정 및 조작의 함수에 사용되고 있는 클래스 오브젝트를 가리키는 포인터이다. 이것에 의해, 콜백 함수는 클래스의 함수에의 액세스를 취득한다.

마지막 파라미터는 플래그에 사용된다. 이 예에서는 플래그는 사용되어 있지 않다.

EnumSuitableDevicesCB 콜백 함수가 어플리케이션 정의의 함수AddDevices 를 호출해, 다음에 이 함수가 현재 열거 되려고 하고 있는 디바이스 pdidDevice 로 IDirectInputDevice8::BuildActionMap 함수를 호출한다. 다음의 코드는, 이 호출을 나타내고 있다.

hr = pdidDevice->BuildActionMap( &m_diaf, m_strUserName, 0L );

여기에서도 최초의 파라미터는, 액션 맵을 저장 하는 DIACTIONFORMAT 구조체이다.

제 2 파라미터도 같이 유저명을 지정할 수 있지만, 여기에서는 NULL 를 지정한다.

마지막 파라미터는 제어 플래그를 보관 유지한다. 이 예에서는 플래그는 건네받지 않는다.

BuildActionMap 는,DIACTIONFORMAT 구조체로 지정된 컨트롤의 할당 일람을 취득해, 그것을, 열거되고 있는 디바이스의 지정된 디바이스 오브젝트에의 매핑을 시도한다. 매핑의 결과는, 같은 구조체에 돌려주어진다. 건네줄 때마다, 현재 조사할 수 있고 있는 열거 디바이스의 성질에 응해, 다른 컨트롤에 매핑 된다. 예를 들어 키보드는, 특정의 키에의 매핑을 지정하는 컨트롤을 매핑 하지만, 버튼, 슬라이더, 또는 축을 지정하는 컨트롤에 대해서는 매핑 하지 않는다. 다음에 죠이스틱이 열거되었을 경우,BuildActionMap 는 키보드의 키에 매핑 된 컨트롤은 무시하지만, 버튼, 슬라이더, 축은 죠이스틱의 디바이스 오브젝트에의 매핑을 시도한다.

이 디폴트 매핑의 결과를 조사해 조작할 수가 있다. 이것은, 「스텝 4 : 액션 맵의 구성과 적용」으로 실시한다.


스텝 4 : 액션 맵의 구성과 적용

DIACTIONFORMAT 구조체에 매핑이 돌려주어지면(자), 조작하고 나서 IDirectInputDevice8::SetActionMap 에 의해 적용한다.

이 시점에서, 각 DIACTION 구조체의 dwHow 멤버를 조사해 매핑이 성공했는지, 또 각 액션이 매핑 된 디바이스 오브젝트의 선택 기준은 무엇으로 있었는지를 판단할 수가 있다. 예를 들어, 매핑이 하드웨어 메이커에 의한 지정인가, 또는 유저로부터의 요구인지를 판단할 수 있다.

실제의 매핑 그 자체를 변경하려면 , 디폴트 매핑에 돌려주어진 적절한 DIACTION 구조체의 dwSemantic 멤버를 편집한다. 이러한 변경은 가능하지만, 실행은 권유받지 않는다.

액션 맵의 구성이 끝나면(자), 그것을 디바이스에 적용해, 물리적 컨트롤을 게임 액션에 바인드 할 필요가 있다. 이것을 실시하려면 , 다음에 나타내도록(듯이) SetActionMap 를 호출한다.

    hr = pdidDevice->SetActionMap( &m_diaf, m_strUserName, 0L );

생성 된 액션 맵은 유저에 대해서 표시되어 간단하게 변경할 수가 있다. 이것에 대해서는, 「스텝 5 : 액션 맵의 표시」로 설명한다.


스텝 5 : 액션 맵의 표시

액션 매핑에는, 개발자가 특정의 콘트롤러 하드웨어에 의존하지 않고 게임 액션을 정의할 수 있다고 하는 이점외, 유저에 의한 복구성을 용이하게 하는 유저 인터페이스 (UI)가 제공되는 이점도 있다.

UI 는, 텍스트만과 그래픽스의 2 개의 형식에서 표시할 수 있다. 또, 이것들 2 개의 옵션을 표시 전용 모드 또는 편집 모드로 표시할 수 있다.

UI 를 표시하려면 , 사전에 몇개의 설정이 필요하다. 우선,DICOLORSET 구조체가 선언되어 초기화된다. 이 구조체는, 그 이름이 가리키도록(듯이), UI 의 표시에 사용하는 칼라 세트를 기술한다. 다음의 코드는, 이 구조체의 설정을 나타내고 있다.

    DICOLORSET dics;
    ZeroMemory(&dics, sizeof(DICOLORSET));
    dics.dwSize = sizeof(DICOLORSET);

ZeroMemory 함수를 사용해 메모리 블록을 제로로 설정 하면, 디폴트의 칼라 스캠을 사용하는 것을 나타낸다. 이외에는, 초기화를 필요로 하는 요소는 dwSize 멤버뿐이어, 이것은 DICOLORSET 구조체의 사이즈로 설정한다.

DICOLORSET 구조체는, 이 코드에 나타내도록(듯이), 보다 큰 DICONFIGUREDEVICESPARAMS 구조체의 일부로서 포함된다.

    DICONFIGUREDEVICESPARAMS dicdp;
    ZeroMemory(&dicdp, sizeof(dicdp));
    dicdp.dwSize = sizeof(dicdp);
    dicdp.dwcUsers       = 1;
    dicdp.lptszUserNames = m_strUserName;

    dicdp.dwcFormats     = 1;
    dicdp.lprgFormats    = &m_diaf;
    dicdp.hwnd           = m_hWnd;
    dicdp.lpUnkDDSTarget = NULL;

DICONFIGUREDEVICESPARAMS 구조체가 선언되어 이 구조체에 할당할 수 있었던 메모리에 제로만을 저장 하도록(듯이) 설정된다. 여기에서도,dwSize 멤버에는 구조체의 사이즈가 설정된다. 이 예에서는 현재 로그 되고 있는 유저만이 사용되기 (위해)때문에,dwcUsers 는 1 으로 설정된다. 변수 m_strUserName 는 NULL 로 설정되어 있기 (위해)때문에, 유저명은 현재 시스템에 로그 온 하고 있는 유저의 이름이 된다.

액션 맵을 저장 하는 1 개의 DIACTIONFORMAT 구조체만이 건네받기 (위해)때문에,dwcFormats 는 1 으로 설정되어DIACTIONFORMAT 구조체의 주소가 lprgFormats 로서 건네받는다.

변수 hwnd 에는 어플리케이션 윈도우의 핸들을 할당해lpUnkDDSTarget 는 NULL 로 설정해 Microsoft® Windows® Graphics Device Interface (GDI) 함수를 사용해 구성 유저 인터페이스의 이미지를 드로잉(Drawing) 하는 것을 나타낸다.

초기화된 DICONFIGUREDEVICESPARAMS 구조체는, 다음의 코드에 나타내도록(듯이),IDirectInput8::ConfigureDevices 에게 건네진다.

    hr = m_pDI->ConfigureDevices(NULL, &dicdp, dwFlags, NULL);

최초와 마지막 파라미터는 옵션의 콜백 함수와 함께 사용하지만, 이 샘플에서는 사용하지 않기 때문에 NULL 가 설정되어 있다.

제 2 파라미터는, 표시되는 데이터나 그 외 보조 정보를 저장 하는 DICONFIGUREDEVICESPARAMS 구조체의 주소이다.

제 3 파라미터는, 표시가 읽어내기 전용 모드나 편집 모드인지를 결정하는 플래그에 사용된다. 구성을, 변경할 수 없는 참조 목적으로 해 표시하는 경우는, 이 파라미터에 DICD_DEFAULT 플래그를 사용한다. 다만 이 예에서는, 변수 dwFlags 에는 이미 DICD_EDIT 가 설정되어 있기 (위해)때문에, 유저 구성이 가능하다. 이것에 대해서는, 「스텝 6 : 액션 맵의 유저 구성」으로 설명한다.


스텝 6 : 액션 맵의 유저 구성

이 시점에서, 유저 구성 인터페이스가 표시된다. 디바이스 메이커가 그래픽을 제공하고 있는 경우는 디바이스의 이미지가 표시되어 그 이미지의 라벨에는 각 디바이스 오브젝트에 할당할 수 있었던 액션이 나타나고 있다. 그래픽이 없는 경우, 사용할 수 있는 디바이스 오브젝트를 관련지을 수 있었던 액션과 함께, 간단한 텍스트에 의한 일람으로 표시된다. 다음에 그래픽의 예를 나타낸다.

여기서 유저는, 자신의 판단으로 콘트롤러를 액션에 재할인 맞히고 할 수 있다. 변경 결과는,DIACTIONFORMAT 구조체에 반영된다. 유저 인터페이스를 종료 하면, 새로운 액션 맵이 IDirectInputDevice8::SetActionMap 에 보내져 이행 된다.

액션 맵의 컨트롤에 관련지을 수 있었던 데이터의 사용법에 대해서는, 「스텝 7 : 액션 매핑 된 데이터의 취득」으로 설명한다.


스텝 7 : 액션 매핑 된 데이터의 취득

액션 매핑은 버퍼링 데이터를 염두에 두어 설계되고 있어 대부분은 버퍼링 데이터로 사용된다. 액션 매핑 된 디바이스로부터의 데이터 취득과 매핑되어 있지 않은 디바이스로부터의 데이터 취득에서는, 데이터를 취득하는 장소만이 차이가 난다. 액션 매핑이 없는 경우는,DIDEVICEOBJECTDATA 구조체의 dwOfs 멤버를 조사해, 변경의 보고가 있는 디바이스 오브젝트를 판단한다. 그러나 액션 매핑에서는,uAppData 멤버를 조사한다. 데이터는 dwData 멤버로 발견된다.

액션 매핑 된 데이터의 취득의 상세한 것에 대하여는, 「액션 데이터의 취득」을 참조할것.


DirectInput C/C++ 샘플

이하의 샘플 프로그램에는, Microsoft® DirectInput® 의 사용법과 기능이 나타나고 있다.

  • DIConfig 샘플
  • FFConst 샘플
  • Joystick 샘플
  • Keyboard 샘플
  • Mouse 샘플
  • MultiMapper 샘플
  • ReadFFE 샘플
  • Scrawl 샘플

Microsoft DirectX® 의 샘플에는 Microsoft Visual C++® 프로젝트 워크 스페이스 파일이 포함되어 있지만, 독자의 개발 환경에서 올바르게 컴파일 할 수 있을지 어떨지를 확인할 필요가 있다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.


DIConfig 샘플

설명

DIConfig 코드는, Microsoft® DirectInput® Mapper 방식에 근거하는 구성 유저 인터페이스의 이행 방법을 나타내고 있다. 이 샘플 코드는 매우 복잡하고, 학습 툴이라고 하는 것보다는 참고 이행으로서 사용되는 것을 의도하고 있다.

패스

원시 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\DIConfig

실행 가능 파일 :없음 (「프로그래밍 위에의 주의」를 참조할것).

유저즈 가이드

이 샘플 코드에서는 실행 가능 파일이 생성 되지 않기 때문에, 최종 사용자에의 지시 사항은 없다.

프로그래밍 위에의 주의

이 코드는 Diconfig.dll 를 생성한다. 이 파일은, 디폴트의 Mapper UI 로 사용하는 모든 기능을 저장 하는 바이노리필드이다. 이 코드는 매우 복잡하고, DirectInput 베이스의 구성 유저 인터페이스의 참고 이행용이다.

이 샘플의 상세한 것에 대하여는, 샘플 코드내의 코멘트를 참조할것. 다음의 주된 기능을 지원 한다.

  • 디바이스 이미지의 표시.
  • 디바이스의 복구성.
  • 다른 시각을 표시하는 복수 디바이스 뷰의 지원.
  • 오버레이를 액티브하게 하는 컨트롤의 지원.
  • GetImageInfo 메소드의 사용.
  • 동일 컴퓨터를 사용하는 다중 사용자 어플리케이션의 디바이스 소유권.
  • SetActionMap 메소드에 있어서의 유저 설정의 보관 유지.


FFConst 샘플

설명

FFConst 샘플 프로그램은, 실제의 동작을 force feedback 입력 디바이스에 적용해, 시뮬레이터와 같은 어플리케이션으로, force feedback를 사용해, 물리 엔진으로 계산된 포스를 생성하는 방법을 구체적으로 가리킨다.

이 어플리케이션을 동작시키려면 , force feedback 디바이스를 접속해야 한다.

패스

원시 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\FFConst

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\Bin\FFConst.exe

유저즈 가이드

이 어플리케이션을 기동 하면, 십자 커서와 검은 포인트가 윈도우에 표시된다. 윈도우의 클라이언트 에리어내의 임의의 장소에서 마우스를 클릭 하면, 검은 포인트가 이동한다 (디바이스의 핸들을 움직여도 아무것도 일어나지 않는 것에 주의). FFConst 는, 십자 커서로부터의 거리 에 비례해, 포인트의 방향으로부터 디바이스에 정수 포스를 준다. 마우스의 버튼을 계속 누르면(자) , 포인트를 계속적으로 움직일 수도 있다.

프로그래밍 위에의 주의

이 샘플 프로그램은, 입력 디바이스가 몇개 접속되고 있는지를 열거해, 최초로 검출된 force feedback 디바이스를 취득한다. 검출되지 않으면, 메세지를 표시해 프로그램을 종료한다.

검은 포인트를 이동 하면, joySetForcesXY 함수는, 커서의 좌표를 포스의 방향과 매그니튜드로 변환한다. 이 데이터는, 정수 포스 이펙트의 파라미터를 변경하는데 사용된다.


Joystick 샘플

설명

Joystick 샘플 프로그램은, 죠이스틱의 데이터를 취득해 표시한다.

패스

원시 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\Joystick

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\Bin\Joystick.exe

유저즈 가이드

죠이스틱을 작동시키거나 비틀거나 스롯트르호이르를 돌리거나 다양한 편성으로 버튼을 누르거나 했을 때에, 표시된 데이터가 어떻게 변화할까 를 보고 헤아린다.

프로그래밍 위에의 주의

이 어플리케이션은, 다이얼로그 프로시저 내부로 설정된 타이머에 응답해, 죠이스틱의 직접 데이터를 폴링 한다.


Keyboard 샘플

설명

Keyboard 샘플 프로그램에서는, 키보드로부터 데이터를 취득할 때의, foreground대 백그라운드, 배타 협조 레벨대 비배타 협조 레벨, 및 버퍼링 데이터대 직접 데이터의 차이가 나타난다.

패스

원시 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\Keyboard

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\Bin\Keyboard.exe

유저즈 가이드

유저 인터페이스를 개입시켜, 협조 레벨과 데이터 스타일을 임의에 조합해, 그 결과가 되는 키보드의 동작을 관찰할 수 있다. 설정을 선택 하면 설명을 해 디바이스 생성시에 예측되는 동작이 나타난다.

프로그래밍 위에의 주의

직접 모드로 키를 누른 채로 하면(자), 그 키는 무한하게 보관 유지되어 그 후의 키보드의 snapshot는 Microsoft® DirectInput® 에 의해 취득된다. DirectInput 는 매초 12 회의 간격으로 snapshot를 취득하고 있기 (위해)때문에 착각이지만, 직접 모드에서는 그 시점에서의 키보드 상태만이 고려되어 snapshot와 snapshot의 사이에 발생한 상태는 무시되는 것을 나타내고 있다.

버퍼링 모드로 키를 누른 채로 하면(자), 그 키가 밀린 것을 나타내는 데이터가 짧게 표시되어 버퍼로부터 데이터가 플래시 되자마자 클리어 된다. 키를 떼어 놓으면(자), 키가 올랐다고 하는 다른 이벤트가 짧게 표시된다. 이것이, 직접 모드와의 큰 차이이다.


Mouse 샘플

설명

Mouse 샘플은, 마우스로부터 데이터를 취득할 때의, foreground대 백그라운드, 배타 협조 레벨대 비배타 협조 레벨, 및 버퍼링 데이터대 직접 데이터의 차이가 나타난다.

패스

원시 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\Mouse

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\Bin\Mouse.exe

유저즈 가이드

유저 인터페이스를 개입시켜, 협조 레벨과 데이터 스타일을 임의에 조합해, 그 결과가 되는 마우스의 동작을 관찰할 수 있다. 설정을 선택 하면 설명을 해 디바이스 생성시에 예측되는 동작이 나타난다.

프로그래밍 위에의 주의

마우스를 해방하려면 ,Enter 키를 누른다.

직접 모드에서는, 모든 디바이스 오브젝트가 표시되어 마우스의 이동에 수반하는 데이터의 변화를 볼 수가 있다. Microsoft® DirectInput® 는 매초 12 회의 간격으로 snapshot를 취득하고 있기 (위해)때문에 착각이지만, 직접 모드에서는 그 시점에서의 디바이스 상태만이 고려되어 디바이스의 snapshot와 snapshot의 사이에 발생한 상태는 무시되는 것을 나타내고 있다.

버퍼링 모드로 버튼을 누른 채로 하면(자), 그 키가 밀린 것을 나타내는 데이터가 짧게 표시되어 버퍼로부터 데이터가 플래시 되자마자 클리어 된다. 버튼을 떼어 놓으면(자), 버튼이 올랐다고 하는 다른 이벤트가 짧게 표시된다. 이것이, 직접 모드와의 큰 차이이다.


MultiMapper 샘플

설명

MultiMapper 샘플 프로그램은, 액션 매핑 기능에 의한 데이터의 설정, 적용, 및 취득의 방법을 나타내고 있다. 또, 유저 인터페이스에 의한 재매핑의 방법도 설명한다.

패스

원시 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\MultiMapper

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\MultiMapper.exe

유저즈 가이드

우선, 플레이어의 수를 할당한다. MultiMapper 샘플 프로그램에서는, 4 명까지 설정할 수 있다. 플레이어 마다, 키보드나 마우스 등, 1 개의 디바이스가 필요하다. 디바이스의 수부터 플레이어의 수가 많은 경우, 프로그램은, 접속되고 있는 디바이스를 기준으로 한 최대 플레이어수까지 플레이어수를 자동적으로 삭감한다.

MultiMapper 샘플 프로그램은, 스페이스 컴배트 어플리케이션의 형태를 본떠 설계되고 있다. 각 플레이어에게는, 회전, 발사, 반동 추진 엔진의 기동 등, 기본적인 액션 세트를 할당할 수 있다. 다음에, 이러한 액션이 디바이스 컨트롤에 맵 된다. 컨트롤이 액티브하게 되면(자), 표시 윈도우의 데이터에 반영된다.

액션 매핑 유저 인터페이스를 액티브하게 하려면 , D 의 키를 누른다. 각 디바이스에는, 특정의 디바이스를 매핑하기 위한 개별의 탭이 있다. 디바이스 오브젝트의 라벨을 더블 클릭 하면, 그 디바이스 오브젝트에 할당할 수가 있는 액션의 일람이 액티브하게 된다. 액션 일람으로부터 액션을 선택해, 선택한 디바이스 오브젝트에 맵 한다. 또, 플레이어 사이에 디바이스를 재할인 맞히고 할 수도 있다.

프로그래밍 위에의 주의

시스템에 죠이스틱이나 휠등의 콘트롤러가 접속되고 있는 경우, 디바이스의 그래픽에, 액션이 각 디바이스 오브젝트의 콜 아웃으로서 표시된다. 이 그래픽은, 그 디바이스에 비트 맵이 있는 경우에 표시되어 비트 맵이 없으면 표시되지 않는다.


ReadFFE 샘플

설명

ReadFFE 샘플 프로그램은,Force Editor 로 생성 된 DirectInput 이펙트 파일에 저장 되고 있는 Microsoft® DirectInput® force feedback 이펙트 파일을 모두 열거해 재생한다.

패스

원시 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\ReadFFE

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\ReadFFE.exe

미디어 파일 :(SDK 루트) \Samples\Multimedia\Media\*.ffe

유저즈 가이드

[Read File] 를 클릭해, 기존의 Force Feedback Effects (FFE) 파일을 연다. 정상적으로 읽어낼 수 있으면(자),[Play Effects] 를 클릭해, force feedback 디바이스로 이펙트를 재생한다. FFE 는, Microsoft DirectX® SDK 에 패키징 되고 있는 Force Feedback Editor 유틸리티를 사용해 생성 할 수 있다.

프로그래밍 위에의 주의

파일로부터 열거된 이펙트의 각각 붙어,EnumAndCreateEffectsCallback 함수가 IDirectInputEffect 포인터를 초기화해, 그 포인터가 링크된 리스트에 추가한다. OnPlayEffects 함수가 이 리스트를 처리해, 모든 이펙트를 재생한다.


Scrawl 샘플

설명

Scrawl 어플리케이션은, 윈도우 표시 어플리케이션의 배타 모드에서의 마우스의 사용법을 설명하고 있다. 이 경우의 마우스는, 페인트 프로그램의 펜슬 툴과 같이 기능한다.

패스

원시 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\Scrawl

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DirectInput\Bin\Scrawl.exe

유저즈 가이드

드로잉(Drawing) 하려면 , 왼쪽 버튼을 누르면서 마우스를 작동시킨다. 오른쪽 버튼을 클릭 하면, 쇼트 컷 메뉴가 표시된다. 쇼트 컷 메뉴로부터는, 클라이언트 윈도우의 소거, 마우스 감도의 설정, 어플리케이션의 종료를 선택할 수가 있다. 컨트롤 패널의 설정에 의해 mouse button가 교체되면(자), Scrawl 는 이 동작을 검출해 거기에 따른다. Microsoft® DirectInput® 는 컨트롤 패널의 설정을 무시하기 위해(때문에), 어플리케이션 자신으로 변환을 실시할 필요가 있는 것에 주의한다.

프로그래밍 위에의 주의

Scrawl 샘플 프로그램은, 다음과 같은 DirectInput 프로그래밍의 다양한 면을 나타내고 있다.

  • 윈도우 표시 어플리케이션의 비배타 모드로 마우스를 사용한다.
  • 메뉴를 사용하기 위해서(때문에) Microsoft Windows® 가 필요로 했을 때에 마우스를 해방한다.
  • Windows 가 마우스를 필요로 하지 않게 되었을 때에, 마우스를 재취득한다.
  • 디바이스의 버퍼링 데이터를 읽어낸다.
  • 좌표의 이동이 완료할 때까지 화면 표시의 갱신을 연기한다.
  • 디바이스의 활동 상황의 이벤트 통지를 표시한다.
  • 임의의 범위에 커서의 움직임을 제한한다.
  • 사용전에, 미처리의 마우스 좌표를 계측 한다.
  • 상대 좌표 모드를 사용한다.


DirectInput C/C++ 레퍼런스

Microsoft® DirectInput® C/C++ 어플리케이션 프로그래밍 인터페이스 (API)의 레퍼런스 정보는, 다음과 같이 분류된다.

  • 인터페이스
  • 콜백 함수
  • 함수
  • 매크로
  • 구조체
  • 디바이스 정수
  • 액션 매핑 정수
  • 반환값


인터페이스

여기에서는, 이하의 Microsoft® DirectInput® 인터페이스의 메소드에 관한 레퍼런스를 제공한다.

  • IDirectInput8
  • IDirectInputDevice8
  • IDirectInputEffect

주 : 모든 DirectInput 메소드에는, 정의되고 있는 언어에 응해, C 또는 C++ 구문에 전개하는 매크로가 준비되어 있다. 이러한 매크로는 Dinput.h 헤더 파일에 있어, 독립해 기술되고 있는 것은 아니다.


IDirectInput8

어플리케이션은,IDirectInput8 인터페이스의 메소드를 사용해, Microsoft® DirectInput® 디바이스의 열거, 생성, 스테이터스의 취득, DirectInput 오브젝트의 초기화, 및 Windows® 컨트롤 패널의 인스턴스의 기동을 실시한다.

IDirectInput8 는, Microsoft DirectX® 의 이전의 버젼으로 사용되고 있던 IDirectInput,IDirectInput2, 및 IDirectInput7 에 취해 대신하는 인터페이스이다.

IDirectInput8 는 오브젝트의 신규 클래스의 인터페이스이며, 클래스 식별자 CLSID_DirectInput8 로 나타내진다. 클래스 CLSID_DirectInput 의 오브젝트에의 인터페이스에 대해서 QueryInterface 를 호출해도, 취득할 수 없다. 그 대신에,DirectInput8Create 함수를 사용해 IDirectInput8 인터페이스를 취득한다.

IDirectInput8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

디바이스 관리 | ConfigureDevices
 | CreateDevice
 | EnumDevices
 | EnumDevicesBySemantics
 | FindDevice
 | GetDeviceStatus
그 외 | Initialize
 | RunControlPanel

모든 COM 인터페이스와 같게,IDirectInput 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUT 형은 IDirectInput8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirectInput8    *LPDIRECTINPUT8;

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInput8::ConfigureDevices

접속된 입력 디바이스의 프로퍼티 페이지를 표시한다. 유저는 이것을 사용해, 액션을 디바이스 컨트롤에 맵 할 수 있다.

HRESULT IDirectInput8::ConfigureDevices(
   LPDICONFIGUREDEVICESCALLBACK lpdiCallback,
   LPDICONFIGUREDEVICESPARAMS   lpdiCDParams,
   DWORD  dwFlags,
   LPVOID pvRefData
);

파라미터

lpdiCallback
표면의 내용이 변경될 때마다 불려 가는 콜백 함수의 주소. 「DIConfigureDevicesCallback 」를 참조할것. 어플리케이션이 프로퍼티 시트의 표시를 처리하지 않는 경우는, NULL 를 건네준다. 이 경우, Microsoft® DirectInput® 가 프로퍼티 시트를 표시해, 유저가 프로퍼티 시트를 닫으면(자), 어플리케이션에 제어를 돌려준다. 콜백 포인터를 지정하는 경우는,DICONFIGUREDEVICESPARAMS 구조체의 lpUnkDDSTarget 멤버에도 유효한 표면 포인터를 지정할 필요가 있다.
lpdiCDParams
유저 인터페이스의 표시 방법에 관한 정보나, 유저와 게임의 장르에 관한 정보를 저장 하는 DICONFIGUREDEVICESPARAMS 구조체의 주소.
dwFlags
컨트롤 패널의 기동 모드를 지정하는 DWORD 값. DwFlags 는 다음의 값의 언젠가가 아니면 안된다.
DICD_DEFAULT
프로퍼티 시트를 표시 전용 모드로 열린다.
DICD_EDIT
프로퍼티 시트를 편집 모드로 열린다. 이 모드에서는, 유저가 액션과 컨트롤의 매핑을 변경할 수 있다. 호출이 돌아오면(자), 어플리케이션은 현재의 디바이스가 이제(벌써) 유효하지 않으면 가정해, 디바이스 인터페이스를 해방해,IDirectInput8::EnumDevicesBySemantics 를 호출해 그 인터페이스를 초기화한다.
pvRefData
콜백 함수에게 건네지는 어플리케이션 정의의 32 비트의 값.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 반환값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_OUTOFMEMORY

주의

하드웨어 벤더는, 디바이스의 비트 맵 및 그 외의 표시 정보를 제공한다.

이 메소드를 호출하기 전에,DIACTION 구조체의 lptszActionName 멤버내의 값을 변경하는 것으로, 어플리케이션은 각 액션에 관련지을 수 있었던 텍스트 라벨을 변경할 수 있다.

구성은, 게임마다, 디바이스마다, 유저 마다 저장 된다. 정보는 IDirectInputDevice8::BuildActionMap 메소드에 의해 취득할 수 있다.

디폴트에서는, 이하의 픽셀 포맷에 대해서 가속화가 지원 되고 있다.

A1R5G5B5
16 비트의 픽셀 포맷으로, 각 색에 5 비트가, 알파 (투과형 텍셀)에 1 비트가, 각각 확보되고 있다.
A8R8G8B8
알파 첨부의 32 비트 ARGB 픽셀 포맷.
R9G8B8
24 비트 RGB 픽셀 포맷.
X1R5G5B5
16 비트의 픽셀 포맷으로, 그 중 5 비트는 각 색을 위해서(때문에) 확보되고 있다.
X8R8G8B8
32 비트의 RGB 픽셀 포맷으로, 그 중 8 비트는 각 색을 위해서(때문에) 확보되고 있다.

상기 이외의 포맷에서는 칼라 변환이 베풀어져 버려, frame rate가 극적으로 저하한다.

주 : Microsoft Windows® 키는, 어플리케이션의 협조 레벨로 배타 협조 레벨을 통해 수동적으로, 또는 DISCL_NOWINKEY 플래그를 사용해 능동적으로 무효로 하는 경우에서도, 디폴트의 액션 매핑 UI 가 표시되고 있는 동안은 액티브하게 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInput8::CreateDevice

지정의 GUID 에 근거해 디바이스의 인스턴스를 생성 해 초기화해,IDirectInputDevice8 인터페이스를 취득한다.

HRESULT CreateDevice(
  REFGUID rguid,
  LPDIRECTINPUTDEVICE *lplpDirectInputDevice,
  LPUNKNOWN pUnkOuter
);

파라미터

rguid
C++ 의 경우, 목적의 입력 디바이스의 인스턴스 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소 ( 「주의」를 참조할것). 이 GUID 는,IDirectInput8::EnumDevices 메소드를 개입시켜 취득하는지, 또는, 다음일 전정의된 GUID 의 1 개를 사용한다.
GUID_SysKeyboard
디폴트의 시스템키 보드.
GUID_SysMouse
디폴트의 시스템 마우스.

이 GUID 값을 유효하게 하려면 , 어플리케이션은, 원시 파일의 선두에서, 다른 모든 프리프로세서 지시문에 앞서, INITGUID 를 정의하든가, 혹은 DXGUID.LIB 에 링크해야 한다.

lplpDirectInputDevice
성공시에 IDirectInputDevice8 인터페이스 포인터를 취득하는 변수의 주소.
pUnkOuter
COM 집성체에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소. 인터페이스가 집성되어 있지 않은 경우에는 NULL. 보통, 호출측은 NULL 를 건네준다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 반환값의 어느쪽이든을 돌려준다.

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_NOTINITIALIZED
DIERR_OUTOFMEMORY

주의

punkOuter = NULL 를 지정해 이 메소드를 호출하는 것은,CoCreateInstance(&CLSID_DirectInputDevice, NULL, CLSCTX_INPROC_SERVER, riid, lplpDirectInputDevice)를 사용해 오브젝트를 생성 한 후,Initialize 를 사용해 초기화하는 것으로 동등하다.

punkOuter ! = NULL 를 지정해 이 메소드를 호출하는 것은,CoCreateInstance(&CLSID_DirectInputDevice, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInputDevice)를 사용해 오브젝트를 생성 하는 것으로 동등하다. 집성 한 오브젝트는 수동으로 초기화해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInput8::EnumDevices

이용 가능한 디바이스를 열거한다.

HRESULT EnumDevices(
  DWORD dwDevType,
  LPDIENUMCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

파라미터

dwDevType
디바이스 타입의 필터.

디바이스의 형태를 지정해 그 열거를 제한하려면 , 이 파라미터에 DI8DEVTYPE_* 값을 설정한다. 「DIDEVICEINSTANCE 」를 참조할것.

디바이스의 클래스를 열거하려면 , 다음의 몇개의 값을 사용한다.

DI8DEVCLASS_ALL
모든 디바이스.
DI8DEVCLASS_DEVICE
다른 클래스로 분류되지 않는 모든 디바이스.
DI8DEVCLASS_GAMECTRL
모든 게임 콘트롤러.
DI8DEVCLASS_KEYBOARD
모든 키보드. DI8DEVTYPE_KEYBOARD 와 동의이다.
DI8DEVCLASS_POINTER
DI8DEVTYPE_MOUSE 및 DI8DEVTYPE_SCREENPOINTER 형의 모든 디바이스.
lpCallback
열거되는 디바이스 마다 한 번 불려 가는 콜백 함수의 주소. 「DIEnumDevicesCallback 」를 참조할것.
pvRef
어플리케이션 정의의 32 비트값. 열거 콜백 함수가 불릴 때마다 건네받는다.
dwFlags
열거의 범위를 지정하는 플래그값. 다음의 플래그를 지정한다.
DIEDFL_ALLDEVICES
모든 인스톨이 끝난 디바이스가 열거된다. 이것이 디폴트 모드이다.
DIEDFL_ATTACHEDONLY
어태치 상태에 있어, 인스톨 끝난 디바이스만.
DIEDFL_FORCEFEEDBACK
force feedback를 지원 하는 디바이스만.
DIEDFL_INCLUDEALIASES
다른 디바이스의 앨리어스(alias)인 디바이스를 포함한다.
DIEDFL_INCLUDEHIDDEN
은폐 디바이스를 포함한다. 은폐 디바이스의 상세한 것에 대하여는, 「DIDEVCAPS 」를 참조할것.
DIEDFL_INCLUDEPHANTOMS
가상 디바이스 (플레이스홀더)를 포함한다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

모든 인스톨이 끝난 디바이스는, 비록 그것이 현존 하고 있지 않아도 열거 가능하다. 예를 들어, 조종간을, 시스템에 인스톨 할 만큼 해 두어, 당면은 컴퓨터에 접속하지 않고 둘 수도 있다. dwFlags 파라미터를 설정해, 어태치 상태에 있는 디바이스만을 열거하는지, 또는 인스톨 끝난 모든 디바이스를 열거하는지를 지시한다. DIEDFL_ATTACHEDONLY 플래그가 존재하지 않는 경우는, 인스톨 끝난 전디바이스가 열거된다.

선별하고 싶은 디바이스 타입을 dwDevType 필터로서 건네주어, 그 타입의 디바이스만을 열거할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInput8::EnumDevicesBySemantics


IDirectInput8::EnumDevicesBySemantics

어플리케이션 지정의 액션 맵에 가장 일치하는 디바이스를 열거한다.

HRESULT EnumDevicesBySemantics(
  LPCTSTR ptszUserName,
  LPDIACTIONFORMAT lpdiActionFormat,
  LPDIENUMDEVICESBYSEMANTICSCB lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

파라미터

ptszUserName
현재의 유저를 식별하는 캐릭터 라인. 시스템에 로그 온 한 유저를 지정하는 경우는 NULL. 유저명은 디바이스의 열거시에 고려된다. 유저 매핑이 없는 디바이스보다, 유저 매핑을 가지는 디바이스가 우선된다. 디폴트에서는, 다른 유저가 사용중의 디바이스는, 이 유저용으로는 열거되지 않는다.
lpdiActionFormat
열거하는 적절한 디바이스의 액션 맵을 지정하는 DIACTIONFORMAT 구조체의 주소.
lpCallback
열거되는 디바이스 마다 한 번 불려 가는 콜백 함수의 주소. 「DIEnumDevicesBySemanticsCallback 」를 참조할것.
pvRef
어플리케이션 정의의 32 비트값. 열거 콜백 함수가 불릴 때마다 건네받는다.
dwFlags
열거의 범위를 지정하는 플래그값. 다음의 1 개 이상의 플래그를 지정한다.
DIEDBSFL_ATTACHEDONLY
어태치 상태에 있어, 인스톨 끝난 디바이스만을 열거한다.
DIEDBSFL_AVAILABLEDEVICES
미소유 또한 인스톨 끝난 디바이스만을 열거한다.
DIEDBSFL_FORCEFEEDBACK
force feedback를 지원 하는 디바이스만을 열거한다.
DIEDBSFL_MULTIMICEKEYBOARDS
세칸다리 (비시스템) 키보드 및 마우스 디바이스만.
DIEDBSFL_NONGAMINGDEVICES
주요한 목적이 게임 디바이스로서가 아닌, HID 준거의 디바이스만. USB 스피커등의 디바이스, 및 특수한 키보드 위에의 멀티미디어 버튼은, 이 값을 취한다.
DIEDBSFL_THISUSER
ptszUserName 로 식별되는 유저용의 인스톨 끝난 모든 디바이스, 및 미소유의 모든 디바이스를 열거한다.

DIEDBSFL_VALID 도 Dinput.h 에 정의되고 있지만, 어플리케이션으로부터는 사용되지 않는다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

키보드와 마우스는 마지막에 열거된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInput8::EnumDevices , 「액션 매핑」


IDirectInput8::FindDevice

시스템에 새롭게 어태치 된 디바이스의 인스턴스 GUID 를 취득한다. 이 메소드는, Microsoft® Win32® 디바이스 관리 통지에 응답해 불려 간다.

HRESULT FindDevice(
  REFGUID rguidClass,
  LPCTSTR ptszName,
  LPGUID pguidInstance
);

파라미터

rguidClass
어플리케이션이 검색하는 디바이스 클래스의 일의인 식별자. 어플리케이션은, 디바이스 도착 통지로부터 클래스 GUID 를 취득하는 상세한 것에 대하여는, Microsoft Platform Software Development Kit (SDK)의 DBT_DEVICEARRIVAL 이벤트의 주제를 참조할것.
ptszName
디바이스의 이름. 어플리케이션은, 디바이스 도착 통지로부터 이름을 취득한다.
pguidInstance
디바이스가 발견되었을 경우에 디바이스의 인스턴스 GUID 를 받는 변수의 주소. 이 값은 IDirectInput8::CreateDevice 에 건네줄 수가 있다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는 DIERR_DEVICENOTREG 를 돌려준다. GUID 와 이름이, Microsoft® DirectInput® 에 등록되어 있는 디바이스 클래스에 대응하지 않는 경우는, 실패가 된다. 예를 들어, 입력 디바이스는 아니고, 기억 디바이스를 참조하는 경우 등이다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInput8::GetDeviceStatus

지정 디바이스의 스테이터스를 취득한다.

HRESULT GetDeviceStatus(
  REFGUID rguidInstance
);

파라미터

rguidInstance
C++ 의 경우, 체크중의 스테이터스가 속하는 디바이스의 인스턴스를 식별하는 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소.

반환값

메소드가 성공해, 디바이스가 시스템과어태치 상태에 있는 경우는 DI_OK 를 돌려주어, 그렇지 않으면 DI_NOTATTACHED 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_GENERIC
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInput8::Initialize

Microsoft® DirectInput® 오브젝트를 초기화한다. 어플리케이션은, 보통, 이 메소드를 호출할 필요는 없다. DirectInput8Create 함수가 DirectInput 오브젝트를 생성 한 후에, 자동적으로 초기화를 실시한다.

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion
);

파라미터

hinst
DirectInput 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들. DirectInput 는, 이 값을 사용해, 어플리케이션 또는 DLL 가, 오브젝트 생성의 자격을 인정받고 있는지 어떤지를 판단해, 하위 호환성을 위해서(때문에) 취해야 할 특별한 동작을 확정한다.

DLL 가 부모의 어플리케이션의 핸들을 건네주면(자), 에러가 된다. 예를 들어, Web 페이지에 파묻히고 있어 DirectInput 를 사용하는 Microsoft ActiveX® 컨트롤은, Web 브라우저의 핸들은 아니고, 그것 자신의 인스턴스의 핸들을 건네주지 않으면 안 된다. 이것에 의해, DirectInput 가 그 컨트롤을 인식해, 필요라고 생각되는 특별한 동작을 모두 유효하게 하는 것이 확실히 된다.

dwVersion
어플리케이션의 설계 대상인 DirectInput 의 버젼 번호. 이 값은 보통, DIRECTINPUT_VERSION 이다. 이전의 버젼 번호를 건네주면(자), DirectInput 가 그 버젼을 에뮤레이트 하게 된다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_BETADIRECTINPUTVERSION
DIERR_OLDDIRECTINPUTVERSION

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInput8::RunControlPanel

유저가 새로운 입력 디바이스를 인스톨 하거나 구성을 변경하거나 할 수 있도록(듯이), Windows 컨트롤 패널을 실행한다.

HRESULT RunControlPanel(
  HWND hwndOwner,
  DWORD dwFlags
);

파라미터

hwndOwner
이 이후의 유저 인터페이스의 부모 윈도우로서 사용하는 윈도우의 핸들. 이 파라미터가 NULL 라면, 부모 윈도우는 사용되지 않는다.
dwFlags
현재는 미사용이므로, 제로로 설정해야 한다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::RunControlPanel


IDirectInputDevice8

어플리케이션은,IDirectInputDevice8 인터페이스의 메소드를 사용해, Microsoft® DirectInput® 디바이스의 액세스권의 취득과 해방, 디바이스 프로퍼티와 정보의 관리, 동작의 설정, 초기화의 실행, force feedback 이펙트의 생성과 재생, 및 디바이스의 컨트롤 패널의 기동을 실시한다.

IDirectInput8 인터페이스는 IDirectInput8::CreateDevice 메소드를 사용해 취득한다. 예에 대해서는, 「DirectInput 디바이스의 생성」을 참조할것.

IDirectInputDevice8 는, 지금까지의 버젼의 Microsoft® DirectX® 로 사용되고 있던 IDirectInputDevice,IDirectInputDevice2, 및 IDirectInputDevice7 에 취해 대신하는 인터페이스이지만, 그것들로부터 계승은 하지 않는다. 이전의 인터페이스의 메소드와 동명의 메소드는 같은 서비스를 실행하지만, 기능이나 동작이 완전히 같다라고는 한정되지 않는다. QueryInterface 를 사용해 이전의 인터페이스를 취득할 수 없다.

IDirectInputDevice8 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

입력 디바이스의 액세스 | Acquire
 | Unacquire
액션 매핑 | BuildActionMap
 | GetImageInfo
 | SetActionMap
디바이스 정보 | GetCapabilities
 | GetDeviceData
 | GetDeviceInfo
 | GetDeviceState
 | Poll
 | SetDataFormat
 | SetEventNotification
디바이스 오브젝트 | EnumObjects
 | GetObjectInfo
디바이스 프로퍼티 | GetProperty
 | SetCooperativeLevel
 | SetProperty
force feedback | CreateEffect
 | EnumCreatedEffectObjects
 | EnumEffects
 | EnumEffectsInFile
 | Escape
 | GetEffectInfo
 | GetForceFeedbackState
 | SendForceFeedbackCommand
 | WriteEffectToFile
그 외 | Initialize
 | RunControlPanel
 | SendDeviceData

모든 COM 인터페이스와 같게,IDirectInputDevice8 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUTDEVICE8 형은 IDirectInputDevice8 인터페이스에의 포인터로서 정의된다.

typedef struct IDirectInputDevice8    *LPDIRECTINPUTDEVICE8;

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8

Built on 2000년 11월 18일


IDirectInputDevice8::Acquire

입력 디바이스에의 액세스권을 취득한다.

HRESULT Acquire();

파라미터

없음.

반환값

성공했을 경우는, DI_OK 를 돌려준다. 디바이스가 취득이 끝난 상태이면 S_FALSE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OTHERAPPHASPRIO

주의

디바이스 취득전에 IDirectInputDevice8::SetDataFormat 메소드나 IDirectInputDevice8::SetActionMap 메소드를 사용해, 데이터 형식을 설정해야 한다. 데이터 형식이 설정되어 있지 않은 경우,Acquire 는 DIERR_INVALIDPARAM 를 돌려준다.

디바이스에 대해서 IDirectInputDevice8::GetDeviceState 또는 IDirectInputDevice8::GetDeviceData 메소드를 호출하기 전에, 그 디바이스를 취득해 두지 않으면 안 된다.

디바이스 취득에서는,참조 카운트를 사용하지 않는다. 이 때문에, 어플리케이션이 IDirectInputDevice8::Acquire 메소드를 2 회 호출해, 그 후 IDirectInputDevice8::Unacquire 메소드를 1 회 호출하면, 디바이스는 해방된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::BuildActionMap

디바이스의 액션 맵을 구축해, 거기에 관한 정보를 취득한다.

HRESULT BuildActionMap(
  LPDIACTIONFORMAT lpdiaf,
  LPCWSTR lpszUserName
  DWORD  dwFlags
);

파라미터

lpdiaf
액션 맵에 관한 정보를 받는 DIACTIONFORMAT 구조체의 주소.
lpszUserName
어느 유저의 매핑을 요구하고 있는지를 지정하는 캐릭터 라인에의 포인터. NULL 의 경우, 현재의 유저가 상정된다.
dwFlags
매핑을 제어하는 플래그. 이 값은, 다음의 값의 언젠가이다.
DIDBAM_DEFAULT
어플리케이션 지정의 매핑 (즉 DIACTION 구조체에 DIA_APPMAPPED 플래그를 가지는 매핑)을 제외하는 모든 매핑을 덧쓰기한다.
DIDBAM_HWDEFAULTS
어플리케이션 지정의 매핑을 포함해 모든 매핑을 덧쓰기한다. 이 플래그는 DIDBAM_INITIALIZE 에 유사하고 있지만, 유저가 맵 한 액션은, 디바이스 드라이버 또는 Microsoft® DirectInput®로 지정된 디폴트 액션으로 자동적으로 덧쓰기된다.
DIDBAM_INITIALIZE
어플리케이션 지정의 매핑을 포함해 모든 매핑을 덧쓰기한다.
DIDBAM_PRESERVE
이 디바이스, 또는 그 외의 구성이 끝난 디바이스에 할당할 수 있었던 현재의 매핑을 보존한다.

반환값

성공했을 경우는, DI_OK,DI_NOEFFECT 또는 DI_WRITEPROTECT 를 돌려준다. 「주의」를 참조할것.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_MAPFILEFAIL

주의

디바이스에 매핑이 생성되어 있지 않은 경우, 이 메소드는 DI_NOEFFECT 를 돌려준다. 예를 들어, 키보드 또는 마우스가, 장르 고유 액션의 매핑을 제공하지 않는 경우이다.

DIERR_INVALIDPARAM 가 돌려주어지는 경우, 매핑의 1 개 이상이 무효이다. DIACTION 구조체의 dwHow 멤버에는 DIAH_ERROR 가 설정된다. 어플리케이션은, 액션 맵의 전체로 에러의 검출과 수정을 보간 할 수가 있다.

DIEFF_MAPFILEFAIL 가 돌려주어졌을 경우는, 벤더가 제공하는 디바이스 파일의 read중인가, 혹은 디바이스의 유저 구성 파일의 읽어들여 또는 기입해 안에 에러가 발생한 것을 나타낸다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::SetActionMap ,IDirectInputDevice8::SetDataFormat


IDirectInputDevice8::CreateEffect

이펙트의 GUID 에 의해 식별되는 이펙트의 인스턴스를 생성, 초기화한다.

HRESULT CreateEffect(
  REFGUID rguid,
  LPCDIEFFECT lpeff,
  LPDIRECTINPUTEFFECT *ppdeff,
  LPUNKNOWN punkOuter
);

파라미터

rguid
C++ 의 경우, 생성 하는 이펙트를 식별하는 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소. 이것은 사전 정의된 이펙트 GUID 에서도, 혹은 IDirectInputDevice8::EnumEffects 로부터 얻을 수 있는 GUID 이라도 좋다.

이하의 표준 이펙트 GUID 가 정의되고 있다.

  • GUID_ConstantForce
  • GUID_RampForce
  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown
  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction
  • GUID_CustomForce
lpeff
생성 된 이펙트에 파라미터를 지정하는 DIEFFECT 구조체. 이 파라미터는, 옵션이다. NULL 의 경우, 이펙트 오브젝트는, 파라미터없이 생성 된다. 다음에, 어플리케이션은 이펙트를 다운로드하기 전에,IDirectInputEffect::SetParameters 메소드를 호출해, 이펙트의 파라미터를 설정해야 한다.
ppdeff
성공시에 IDirectInputEffect 인터페이스에의 포인터를 받는 변수의 주소.
punkOuter
COM 집성체에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소. 인터페이스가 집성 되지 않는 경우, 값은 NULL 이다. 보통, 호출측은 NULL 를 건네준다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_DEVICEFULL
DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

반환값이 S_OK 인 경우, 이펙트는 생성이 끝난 상태로, 이펙트의 파라미터는 갱신이 끝난 상태이지만, 이펙트는 반드시 다운로드되어 있지 않은 것을 나타낸다. 이펙트를 다운로드하려면 , 디바이스를 배타 모드로 취득해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::EnumCreatedEffectObjects

이 디바이스에 현재 생성 떠날 수 있어 모든 이펙트를 열거한다. IDirectInputDevice8::CreateEffect 에 의해 생성 된 이펙트가 열거된다.

HRESULT EnumCreatedEffectObjects(
  LPDIENUMCREATEDEFFECTOBJECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD fl
);

파라미터

lpCallback
어플리케이션 정의의 콜백 함수의 주소. Microsoft® DirectInput® 는, prototype 함수 DIEnumCreatedEffectObjectsCallback 를 제공하고 있다.
pvRef
콜백용의 레퍼런스 데이터 (문맥).
fl
플래그는 현재 미정도리이다. 이 파라미터는, 제로가 아니면 안된다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

열거의 진행중에, 이펙트를 생성 또는 폐기 하면, 그 결과는 예측할 수 없다. 그러나, 콜백 함수는, 건네받는 이펙트를 확실히 해방한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::EnumEffects

디바이스 위에의 force feedback 시스템이 지원 하는 이펙트를 모두 열거한다. 열거되는 GUID 는, 디바이스 메이커 독자적인 이펙트에 가세해, 사전 정의된 이펙트도 나타낼 수가 있다.

HRESULT EnumEffects(
  LPDIENUMEFFECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwEffType
);

파라미터

lpCallback
어플리케이션 정의의 콜백 함수의 주소. 이 함수의 선언은,DIEnumEffectsCallback prototype의 선언과 같게 실시하지 않으면 안 된다.
pvRef
콜백 함수에 건네주는 어플리케이션 정의의 32 비트의 값. 이 파라미터에는, 임의의 32 비트의 값을 사용할 수 있다. 다만, 편의상,LPVOID 라고 선언되고 있다.
dwEffType
이펙트 타입의 필터. DIEFT_* 값의 1 개를 사용해 열거하는 이펙트 타입을 지시하든가, 혹은 DIEFT_ALL 를 사용해 모든 이펙트 타입을 열거한다. 이러한 값의 리스트에 대해서는, 「DIEFFECTINFO 」를 참조할것.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

콜백 함수가 열거를 도중에 정지 하면, 그 열거는 성공했다고 보여진다.

주의

어플리케이션은,DIEFFECTINFO 구조체의 dwEffType 멤버를 사용해, 이펙트의 타입, 이펙트가 지원 하고 있는포락선과 조건 파라미터가 무엇으로 있는지, 등 이펙트의 일반적 정보를 취득할 수 있다.

이펙트를 최대한으로 이용하려면 , 디바이스 메이커에 문의해, 이펙트의 의미 내용과 그 이펙트 고유의 파라미터에 관한 정보를 입수해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::EnumEffectsInFile

Force Editor 유틸리티나, 같은 파일 형식을 사용하는 다른 어플리케이션으로 생성 된 파일에 포함되는, 모든 이펙트를 열거한다.

HRESULT EnumEffectsInFile(
  LPCSTR lpszFileName,
  LPENUMEFFECTSINFILECALLBACK pec,
  LPVOID pvRef,
  DWORD dwFlags
);

파라미터

lpszFileName
RIFF 파일의 이름.
pec
어플리케이션 정의의 콜백 함수의 주소. 이 함수의 선언은,DIEnumEffectsInFileCallback prototype의 선언과 같게 실시하지 않으면 안 된다.
pvRef
콜백 함수에 건네주는 어플리케이션 정의의 32 비트의 값. 이 파라미터는, 32 비트의 임의의 값을 취할 수가 있다.
dwFlags
DIFEF_DEFAULT (= 0) 혹은 이하의 값의 한편 또는 양쪽 모두를 사용할 수 있다.
DIFEF_INCLUDENONSTANDARD
Microsoft® DirectInput® 로 정의되어 있지 않은 이펙트 타입을 포함한다.
DIFEF_MODIFYIFNEEDED
현재의 디바이스로 재생할 수 있도록(듯이), 생성 한 이펙트를 필요에 따라서 변경하도록(듯이) DirectInput 에 대해서 지시한다. 예를 들어, 2 개의 축으로 대해 생성 된 이펙트는, 디폴트에서는 단일축디바이스에서는 재생되지 않는다. 이 플래그를 설정 하면, 단일축으로 그러한 이펙트가 재생된다. 파라미터는,DIEFFECT 구조 체내에서 변경된다. 이 구조체는, 콜백에게 건네지는 DIFILEEFFECT 구조체의 lpDiEffect 멤버에 의해 참조된다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

콜백 함수가 열거를 도중에 정지 하면, 그 열거는 성공했다고 보여진다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::WriteEffectToFile , 「파일로부터의 이펙트의 read」


IDirectInputDevice8::EnumObjects

디바이스상에서 사용 가능한 입출력 오브젝트를 열거한다.

HRESULT EnumObjects(
  LPDIENUMDEVICEOBJECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

파라미터

lpCallback
DirectInputDevice 오브젝트의 콜백 함수의 주소. Microsoft® DirectInput® 는, 이 함수의 prototype를 DIEnumDeviceObjectsCallback 로서 제공하고 있다.
pvRef
콜백용의 레퍼런스 데이터 (문맥).
dwFlags
열거하는 오브젝트의 타입을 지정하는 플래그. 다음의 플래그는, 열거 대상이 지정된 타입의 오브젝트에 제한한다.
DIDFT_ABSAXIS
절대축.
DIDFT_ALIAS
HID (Human Interface Device) 사용 앨리어스(alias)에 의해 식별되는 컨트롤. 이 플래그는, HID 준거의 USB 디바이스 에 대해서만 적용된다.
DIDFT_ALL
모든 오브젝트.
DIDFT_AXIS
절대축, 상대축의 어느 쪽인지.
DIDFT_BUTTON
푸쉬 버튼 또는 토글버튼.
DIDFT_COLLECTION
휴먼 인터페이스 디바이스 (HID) 링크 콜렉션. HID 링크 콜렉션은, 독자적인 데이터를 생성하지 않는다.
DIDFT_ENUMCOLLECTION(n)
HID 링크 콜렉션 번호 n 에 속하는 오브젝트.
DIDFT_FFACTUATOR
force feedback 액츄에이터를 포함한 오브젝트. 즉, 포스를 이 오브젝트에 적용할 수가 있다.
DIDFT_FFEFFECTTRIGGER
force feedback 이펙트를 방아쇠 하기 위해서 사용할 수 있는 오브젝트.
DIDFT_NOCOLLECTION
HID 링크 콜렉션에 속하지 않는 오브젝트. 즉,DIDEVICEOBJECTINSTANCE 구조체의 wCollectionNumber 멤버가 0 인 오브젝트.
DIDFT_NODATA
데이터를 생성하지 않는 오브젝트.
DIDFT_OUTPUT
IDirectInputDevice8::SendDeviceData 메소드를 이용하는 것에 의해, 데이터를 보낼 수가 있는 오브젝트.
DIDFT_POV
시점 콘트롤러.
DIDFT_PSHBUTTON
푸쉬 버튼. 푸쉬 버튼은, 유저가 눌렀을 때에 다운, 유저가 떼어 놓았을 때에 업이라고 보고된다.
DIDFT_RELAXIS
상대축.
DIDFT_TGLBUTTON
토글버튼. 토글버튼은, 유저가 눌렀을 때에 다운이라고 보고되어 유저가 재차 그 버튼을 누를 때까지 그 상태에 머문다.
DIDFT_VENDORDEFINED
메이커에 의해 정의되는 타입의 오브젝트.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

dwFlags 파라미터에 DIDFT_FFACTUATOR 및 DIDFT_FFEFFECTTRIGGER 플래그를 지정 하면, 열거 대상은, 이 2 개의 플래그로 정의 떠날 수 있어 모든 기준을 채우는 오브젝트로 한정된다. 다른 모든 플래그의 경우는, 이 카테고리로 지정한 플래그로 정의되고 있는 기준을 채우는 오브젝트가 열거된다. 예를 들어, (DIDFT_FFACTUATOR | DIDFT_FFEFFECTTRIGGER)를 지정 하면, 열거 대상을 force feedback 방아쇠 오브젝트로 한정한다. 이것에 대해서, (DIDFT_FFEFFECTRIGGER | DIDFT_TGLBUTTON | DIDFT_PSHBUTTON)를 지정 하면, 이펙트 방아쇠로서 이용할 수 있는 임의의 버튼이 열거된다.

어플리케이션은, 특정의 키보드의 키나 인디케이터(indicator) 램프가 존재할지 어떨지의 판단을, 이 메소드에 의존해서는 안 된다. 이러한 오브젝트는 존재하지 않음에도 불구하고 열거될 가능성이 있다. 이용 가능한 오브젝트의 기본 세트는 디바이스 서브 타입으로부터 결정할 수 있지만, 메뉴 키등의 추가 오브젝트를 이용할 수 있을지 어떨지를 확실히 판단할 수 있는 방법은 없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::Escape

하드웨어 고유의 커멘드를 force feedback 드라이버에 송신한다.

HRESULT Escape(
  LPDIEFFESCAPE pesc
);

파라미터

pesc
송신하는 커멘드를 기술하는 DIEFFESCAPE 구조체. 성공하면(자), 실제로 사용하는 출력 버퍼의 바이트수가 cbOutBuffer 멤버에 저장 된다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_DEVICEFULL
DIERR_NOTINITIALIZED

다른 디바이스 고유 에러 코드를 돌려줄 수도 있다. 하드웨어 메이커로부터 상세 정보를 입수하는 것.

주의

각 드라이버는, 다른 이스케이프를 이행 하고 있으므로, 올바른 드라이버와 통신하고 있을지 어떨지는, 어플리케이션 자체가 확인해야 한다. 이것은,DIDEVICEINSTANCE 구조체의 guidFFDriver 멤버와 어플리케이션이 예측하고 있는 값을 비교하는 것으로써 확인할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::GetCapabilities

DirectInputDevice 오브젝트의 능력을 취득한다.

HRESULT GetCapabilities(
  LPDIDEVCAPS lpDIDevCaps
);

파라미터

lpDIDevCaps
디바이스의 능력을 저장 하는 DIDEVCAPS 구조체의 주소. 이 구조체의 dwSize 멤버는, 이 메소드를 호출하기 전에 초기화해 두지 않으면 안 된다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_POINTER

주의

Microsoft® DirectX® 3 과의 호환성에 대해서는,sizeof(DIDEVCAPS_DX3) 에 초기화한 dwSize 멤버를 포함한 DIDEVCAPS_DX3 구조체를 건네주어도 괜찮다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::GetDeviceData

디바이스로부터 버퍼링 데이터를 취득한다.

HRESULT GetDeviceData(
  DWORD cbObjectData,
  LPDIDEVICEOBJECTDATA rgdod,
  LPDWORD pdwInOut,
  DWORD dwFlags
);

파라미터

cbObjectData
DIDEVICEOBJECTDATA 구조체의 바이트 단위의 사이즈.
rgdod
버퍼링 데이터를 받기 위한 DIDEVICEOBJECTDATA 구조체의 배열. 이 배열의 요소수는,pdwInOut 파라미터의 값과 동일하지 않으면 안 된다. 이 파라미터가 NULL 의 경우, 버퍼링 데이터는 어디에도 저장 되지 않지만, 그 외의 부차 이펙트는 모두 발생한다.
pdwInOut
입력 파라미터는,rgdod 파라미터가 가리키는 배열의 요소수이다. 출력 파라미터는, 실제로 취득된 요소수이다.
dwFlags
데이터를 취득하는 방법을 제어하는 플래그. 제로 또는 다음의 플래그를 지정한다.
DIGDD_PEEK
버퍼로부터 항목을 삭제하지 않는다. 이 이후의 IDirectInputDevice8::GetDeviceData 호출로, 같은 데이터를 읽어낼 수가 있다. 보통, 데이터는 읽어내 후, 버퍼로부터 삭제된다.

반환값

성공했을 경우는, DI_OK 또는 DI_BUFFEROVERFLOW 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTBUFFERED
DIERR_NOTINITIALIZED

주의

디바이스 데이터를 취득하기 전에,IDirectInputDevice8::SetDataFormat 메소드와 IDirectInputDevice8::SetProperty 메소드, 또는 IDirectInputDevice8::SetActionMap 메소드로 데이터 형식과 버퍼 사이즈를 설정해야 한다. 또,IDirectInputDevice8::Acquire 메소드로 디바이스를 취득해야 한다.

이하의 예에서는, 버퍼링 데이터 요소를 최고 10 개까지 읽어낸다. 디바이스 버퍼로부터는, 데이터를 읽어내면서 삭제하고 있다.

DIDEVICEOBJECTDATA rgdod[10];
DWORD dwItems = 10;
hres = IDirectInputDevice8_GetDeviceData(
    sizeof(DIDEVICEOBJECTDATA),
    rgdod,
    &dwItems,
    0);
if (SUCCEEDED(hres)) {
    // dwItems = 읽어내진 요소수 (0 이 된다).
    if (hres == DI_BUFFEROVERFLOW) {
    // 버퍼가 오버플로우 했다.
    }
}

버퍼를 플래시 해, 플래시 한 항목의 수를 취득하려면 ,rgdod 파라미터에 NULL,pdwInOut 파라미터에 INFINITE 를 포함한 변수에의 포인터를 각각 지정한다. 이하의 예로, 그방법을 나타낸다.

dwItems = INFINITE;
hres = IDirectInputDevice8_GetDeviceData(
            pdid,
            sizeof(DIDEVICEOBJECTDATA),
            NULL,
            &dwItems,
            0);
if (SUCCEEDED(hres)) {
    // 버퍼의 플래시에 성공.
    // dwItems = 플래시 한 요소수.
    if (hres == DI_BUFFEROVERFLOW) {
        // 버퍼가 오버플로우 했다.
    }
}

디바이스 버퍼중의 요소수를 조사하려면 ,rgdod 파라미터에 NULL,pdwInOut 파라미터에 INFINITE,dwFlags 에 DIGDD_PEEK 를 각각 지정한다. 이하의 예로, 그방법을 나타낸다.

dwItems = INFINITE;
hres = IDirectInputDevice8_GetDeviceData(
            pdid,
            sizeof(DIDEVICEOBJECTDATA),
            NULL,
            &dwItems,
            DIGDD_PEEK);
if (SUCCEEDED(hres)) {
    // dwItems = 버퍼내의 요소수.
    if (hres == DI_BUFFEROVERFLOW) {
        // 버퍼 오버플로우가 발생. 일부의 데이터
        // 의 캡춰에 실패했다.
    }
}

버퍼 오버플로우가 발생했는지 어떠했는지를 조사하려면 ,rgdod 파라미터에 NULL,pdwInOut 파라미터에 제로를 설정한다. 이하의 예로, 그방법을 나타낸다.

dwItems = 0;
hres = IDirectInputDevice8_GetDeviceData(
            pdid,
            sizeof(DIDEVICEOBJECTDATA),
            NULL,
            &dwItems,
            0);
if (hres == DI_BUFFEROVERFLOW) {
    // 버퍼 오버플로우가 발생.
}

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::Poll , 「폴링과 이벤트 통지」


IDirectInputDevice8::GetDeviceInfo

디바이스의 식별 정보를 취득한다.

HRESULT GetDeviceInfo(
  LPDIDEVICEINSTANCE pdidi
);

파라미터

pdidi
디바이스의 식별 정보를 저장 하는 DIDEVICEINSTANCE 구조체의 주소. 어플리케이션은, 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 초기화해 두지 않으면 안 된다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_POINTER

주의

Microsoft® DirectX® 3 과의 호환성에 대해서는,sizeof(DIDEVICEINSTANCE_DX3) 에 초기화한 dwSize 멤버를 포함한 DIDEVICEINSTANCE_DX3 구조체를 건네주어도 괜찮다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::GetDeviceState

디바이스로부터 직접 데이터를 취득한다.

HRESULT GetDeviceState(
  DWORD cbData,
  LPVOID lpvData
);

파라미터

cbData
lpvData 파라미터내의 바이트 단위의 버퍼 사이즈.
lpvData
디바이스의 현재 상태를 받는 구조체의 주소. IDirectInputDevice8::SetDataFormat 메소드를 호출하기 전에, 데이터 형식을 설정한다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTINITIALIZED
E_PENDING

주의

디바이스 데이터를 취득하기 전에,IDirectInputDevice8::SetCooperativeLevel 메소드로 협조 레벨을 설정한 후,IDirectInputDevice8::SetDataFormat 메소드로 데이터 형식을 설정해,IDirectInputDevice8::Acquire 메소드로 디바이스를 취득한다.

다음 표에 나타내도록(듯이), 5 개의 정의가 끝난 데이터 형식에는, 각각 대응하는 디바이스 상태 구조체가 필요하다.

데이터 형식 | 상태 구조체
c_dfDIMouse | DIMOUSESTATE
c_dfDIMouse2 | DIMOUSESTATE2
c_dfDIKeyboard | 256 바이트의 배열
c_dfDIJoystick | DIJOYSTATE
c_dfDIJoystick2 | DIJOYSTATE2

예를 들어,c_dfDIMouse 형식을 IDirectInputDevice8::SetDataFormat 메소드에 건네주는 경우는,DIMOUSESTATE 구조체를 IDirectInputDevice8::GetDeviceState 메소드에 건네주지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::Poll , 「폴링과 이벤트 통지」, 「버퍼링 데이터와 직접 데이터」


IDirectInputDevice8::GetEffectInfo

이펙트에 관한 정보를 취득한다.

HRESULT GetEffectInfo(
  LPDIEFFECTINFO pdei,
  REFGUID rguid
);

파라미터

pdei
이펙트의 정보를 받는 DIEFFECTINFO 구조체. 호출측은, 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 초기화해 두지 않으면 안 된다.
rguid
C++ 의 경우, 어느 이펙트의 정보가 요구되고 있는지를 식별하는 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_POINTER

주 : 이 메소드가 비force feedback 디바이스로 불려 갔을 경우는, E_POINTER 가 되돌려진다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::GetForceFeedbackState

디바이스의 force feedback 시스템 상태를 취득한다.

HRESULT GetForceFeedbackState(
  LPDWORD pdwOut
);

파라미터

pdwOut
디바이스의 force feedback 시스템의 현재 상태를 나타내는 플래그의 주소.

이 값은, 이하의 정수의 편성이다.

DIGFFS_ACTUATORSOFF
디바이스의 force feedback 액츄에이터가 무효이다.
DIGFFS_ACTUATORSON
디바이스의 force feedback 액츄에이터가 유효하다.
DIGFFS_DEVICELOST
디바이스가 예기치 않은 장해를 입어, 불확정인 상태에 있다. 한 번 디바이스를 해방한 다음에 재취득하는지, 또는 DISFFC_RESET 커멘드를 송신할까 어느 쪽인지로 디바이스를 리셋 해야 한다.
DIGFFS_EMPTY
디바이스는 다운로드된 요소를 가지지 않는다.
DIGFFS_PAUSED
모든 액티브한 이펙트의 재생이 일시정지되고 있다.
DIGFFS_POWEROFF
force feedback 시스템은, 현재 사용할 수 없다. 디바이스가 전원 상태를 보고할 수 없으면, DIFFS_POWERON 및 DIFFS_POWEROFF 의 어느쪽이나 돌려주어지지 않다.
DIGFFS_POWERON
force feedback 시스템의 전원은 현재 들어가 있다. 디바이스가 전원 상태를 보고할 수 없으면, DIFFS_POWERON 및 DIFFS_POWEROFF 의 어느쪽이나 돌려주어지지 않다.
DIGFFS_SAFETYSWITCHOFF
안전 스윗치가 현재 오프이다. 즉, 디바이스는 동작할 수 없다. 디바이스가 안전 스윗치 상태를 보고할 수 없으면, DIFFS_SAFETYSWITCHON 와 DIFFS_SAFETYSWITCHOFF 의 어느쪽이나 돌려주어지지 않다.
DIGFFS_SAFETYSWITCHON
안전 스윗치가 현재 온이다. 즉, 디바이스는 동작할 수 있다. 디바이스가 안전 스윗치 상태를 보고할 수 없으면, DIFFS_SAFETYSWITCHON 와 DIFFS_SAFETYSWITCHOFF 의 어느쪽이나 돌려주어지지 않다.
DIGFFS_STOPPED
재생중의 이펙트는 없고, 디바이스는 중단 상태는 아니다.
DIGFFS_USERFFSWITCHOFF
유저 force feedback 스윗치가 현재 오프이다. 즉, 디바이스는 동작할 수 없다. 디바이스가 유저 force feedback 스윗치 상태를 보고할 수 없으면, DIFFS_USERFFSWITCHON 와 DIFFS_USERFFSWITCHOFF 의 어느쪽이나 돌려주어지지 않다.
DIGFFS_USERFFSWITCHON
유저 force feedback 스윗치가 현재 온이다. 즉, 디바이스는 동작할 수 있다. 디바이스가 유저 force feedback 스윗치 상태를 보고할 수 없으면, DIFFS_USERFFSWITCHON 와 DIFFS_USERFFSWITCHOFF 의 어느쪽이나 돌려주어지지 않다.

Microsoft® DirectInput® 의 장래의 버젼으로, 플래그가 추가 정의될 가능성도 있다. 어플리케이션은, 현재 미정도리의 플래그를 모두 무시할 필요가 있다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::GetImageInfo

구성 프로퍼티 시트로 사용하는 디바이스 이미지에 관한 정보를 취득한다.

HRESULT GetImageInfo(
  LPDIDEVICEIMAGEINFOHEADER lpdiDevImageInfoHeader
);

파라미터

lpdiDevImageInfoHeader
디바이스 이미지에 관한 정보를 받는 DIDEVICEIMAGEINFOHEADER 구조체의 주소.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_MAPFILEFAIL
DIERR_MOREDATA
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::GetObjectInfo

버튼이나 축등의 디바이스 오브젝트의 정보를 취득한다.

HRESULT GetObjectInfo(
  LPDIDEVICEOBJECTINSTANCE pdidoi,
  DWORD dwObj,
  DWORD dwHow
);

파라미터

pdidoi
오브젝트의 정보를 저장 하는 DIDEVICEOBJECTINSTANCE 구조체의 주소. 이 구조체의 dwSize 멤버는, 이 메소드를 호출하기 전에 초기화해 두지 않으면 안 된다.
dwObj
취득하는 정보가 소속하는 오브젝트를 식별하는 값. 이 파라미터로 설정하는 값은,dwHow 파라미터로 지정되고 있는 값에 의존한다.
dwHow
dwObj 파라미터의 해석 방법을 지정하는 값. 이 값은, 다음의 어느쪽이든 1 개(살)이다.
값 | 의미
DIPH_BYOFFSET | dwObj 파라미터는, 액세스 하는 정보가 소속하는 오브젝트의 현재의 데이터 형식에 대한 오프셋(offset)이다.
DIPH_BYID | dwObj 파라미터는, 오브젝트 타입, 또는 인스턴스 식별자이다. 이 식별자는,DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버안에 돌려주어진다. 이 구조체는,IDirectInputDevice8::EnumObjects 메소드에 대하기 이전의 호출로 돌려주어진 것이다.
DIPH_BYUSAGE | dwObj 파라미터는, 오브젝트의 "HID 사용 페이지" 와 "사용 상황" 의 값이다. 이러한 값은 DIMAKEUSAGEDWORD 매크로에 의해 조합할 수 있다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
E_POINTER

주의

Microsoft® DirectX® 3 과의 호환성에 대해서는,sizeof(DIDEVICEOBJECTINSTANCE_DX3) 에 초기화한 dwSize 멤버를 포함한 DIDEVICEOBJECTINSTANCE_DX3 구조체를 건네주어도 괜찮다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::GetProperty

입력 디바이스에 관한 정보를 취득한다.

HRESULT GetProperty(
  REFGUID rguidProp,
  LPDIPROPHEADER pdiph
);

파라미터

rguidProp
C++ 의 경우, 취득하는 프로퍼티를 식별하는 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소. 이 식별자로서 사전 정의된 값의 1 개, 또는 프로퍼티를 식별하는 GUID 에의 포인터를 사용할 수 있다. 입력 디바이스에 대해서는, 다음의 프로퍼티가 사전 정의되고 있다.
DIPROP_APPDATA
게임내의 액션에 관련하는 어플리케이션 정의의 값을 DIPROPPOINTER 로서 취득한다.
DIPROP_AUTOCENTER
디바이스 오브젝트가 자동 센터링을 실시할지 어떨지를 지정한다. 돌려주어지는 값은 DIPROPAUTOCENTER_OFF 또는 DIPROPAUTOCENTER_ON 이다. 상세한 것에 대하여는, 「IDirectInputDevice8::SetProperty 」를 참조할것.
DIPROP_AXISMODE
축모드를 취득한다. 취득되는 값은 DIPROPAXISMODE_ABS 또는 DIPROPAXISMODE_REL 이다.
DIPROP_BUFFERSIZE
입력 버퍼 사이즈를 취득한다.

버퍼 사이즈는,IDirectInputDevice8::GetDeviceData 메소드의 전회와 이번 호출동안에서, 버퍼가 데이터를 잃는 일 없이 보관 유지할 수 있는 데이터의 양을 결정한다. 이 값에 제로를 설정해, 어플리케이션이 디바이스로부터 버퍼링 데이터를 읽어들이지 않게 지정할 수도 있다. DIPROPDWORD 구조체의 dwData 멤버중의 버퍼 사이즈가 너무 커 디바이스가 지원 할 수 없는 경우는, 지원 가능한 최대 버퍼 사이즈가 설정된다. 요구한 버퍼 사이즈가 설정되었는지 어떠했는지를 확인하려면 , 버퍼 사이즈 프로퍼티를 취득해, 설정하려고 한 값과 그 결과를 비교한다.

DIPROP_CALIBRATIONMODE
어플리케이션이 사용하는 것이 아니라, 디바이스 드라이버가 사용한다.
DIPROP_CPOINTS
미가공의 도착 데이터를 조정하기 위해서 사용하는 calibration 포인트를 DIPROPCPOINTS 구조체로서 취득한다.
DIPROP_DEADZONE
0 ~ 10,000 의 범위에서 죠이스틱의데드 존의 값을 취득한다. 여기서, 0 은 데드 존이 존재하지 않는 것, 5,000 은 데드 존이 축을 중심으로 한 물리 범위의 50 퍼센트에까지 퍼지고 있는 것, 및 10,000 은 축의 물리 범위의 전체가 무효라는 점을 각각 가리킨다. 축이 데드 존내에 있으면(자), 축의 범위의 중심에 있는 것이라고 보고된다.
DIPROP_FFGAIN
디바이스의 게인을 취득한다. 상세한 것에 대하여는, 「IDirectInputDevice8::SetProperty 」를 참조할것.
DIPROP_FFLOAD
디바이스의 메모리 로드를 취득한다. 이 설정값은, 개별의 오브젝트는 아니고 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다. 취득되는 값은, 0~100 의 범위에 있다. 이 값은, 사용중의 디바이스 메모리의 퍼센트수를 나타낸다. 디바이스는 배타 모드로 취득해야 한다. 배타 모드가 아닌 경우, 이 메소드는 실패해, 반환값 DIERR_NOTEXCLUSIVEACQUIRED 가 돌려주어진다.
DIPROP_GETPORTDISPLAYNAME
이 디바이스가 접속되고 있는 포토의, 인간이 읽을 수 있는 형식의 표시명을 취득한다. 어플리케이션은 보통은 사용하지 않는다. 등록명이 1 개도 돌려주어지지 않은 경우, 이 메소드는 S_FALSE 를 돌려준다.
DIPROP_GRANULARITY
입력의 세분도를 취득한다. 세분도는, 오브젝트가 이동거리를 보고할 때의 최소량을 나타낸다. 많은 축오브젝트의 세분도는 1 이며, 모든 값을 취할 수가 있다. 축으로야는은, 보다 큰 세분도를 가지는 것도 있다. 예를 들어, 마우스의 휠축의 세분도는 20 으로 할 수도 있다. 보고되는 위치 변화는 모두, 20 의 배수가 된다. 즉, 유저가 휠을 천천히 회전시키면(자), 디바이스는 위치를 0, 20, 40 등이라고 보고한다. 이것은 읽어내 전용 프로퍼티이다.
DIPROP_GUIDANDPATH
디바이스의 클래스 GUID 와 디바이스 인터페이스 (패스)를 취득한다. 상세 설정의 가능한 어플리케이션은, 이 프로퍼티를 사용하는 것으로, Microsoft® DirectInput® 로 지원되어 있지 않은 HID 에 대해서 조작을 실행할 수 있다. 상세한 것에 대하여는,DIPROPGUIDANDPATH 구조체의 레퍼런스를 참조할것.
DIPROP_INSTANCENAME
디바이스의 인스턴스의 등록명을 취득한다. 상세한 것에 대하여는, 「IDirectInputDevice8::SetProperty 」를 참조할것.
DIPROP_JOYSTICKID
죠이스틱의 인스턴스 번호를 취득한다. 이 프로퍼티는 마우스나 키보드에는 이행 되지 않는다.
DIPROP_KEYNAME
키보드 키의 로컬라이즈 된 키명을 DIPROPSTRING 로서 취득한다.
DIPROP_LOGICALRANGE
HID 의 축으로부터 돌려주어지는 미가공 데이터의 범위를 취득한다. 디바이스는 마이너스값을 돌려주는 일이 있다.
DIPROP_PHYSICALRANGE
HID 의 메이커가 지정하는, 축데이터의 범위를 취득한다. 마이너스값이 돌려주어지는 일도 있다. 보통, DirectInput® 는 0 ~ 0xFFFF 의 값을 돌려주지만, DIPROP_RANGE 를 사용해, 메이커 지정의 범위에 맞출 수가 있다.
DIPROP_PRODUCTNAME
디바이스의 제품의 등록명을 취득한다. 상세한 것에 대하여는, 「IDirectInputDevice8::SetProperty 」를 참조할것.
DIPROP_RANGE
오브젝트를 보고할 수 있는 값의 범위를 취득한다. 일부의 디바이스에서는, 이것은 읽어내 전용 프로퍼티이다.
DIPROP_SATURATION
0 ~ 10,000 의 범위에서 죠이스틱의포화 존의 값을 취득한다. 포화 레벨이란, 축이 극한 위치에 있다고 보이는 포인트이다. 예를 들어, 포화 레벨이 9,500 으로 설정되어 있는 경우, 축의 중심 (데드 존)으로부터 축의 구석까지의 물리적 거리의 95% 의 위치가 축의 극한 위치가 된다.
DIPROP_SCANCODE
키보드 키의 스캔 코드를 DIPROPDWORD 로서 취득한다.
DIPROP_USERNAME
디바이스에 현재 할당할 수 있고 있는 유저의 유저명을 DIPROPSTRING 로서 취득한다. 유저명은 IDirectInputDevice8::SetActionMap 를 호출해 설정된다. 유저명이 설정되어 있지 않은 경우, 이 메소드는 S_FALSE 를 돌려준다.
pdiph
멤버로서 DIPROPHEADER 구조체를 가지는 대형 프로퍼티 의존 구조체의,DIPROPHEADER 부분의 주소. 프로퍼티에는 다음의 구조체가 사용된다.
DIPROPDWORD
단일의 수치로 나타내지는 프로퍼티에 사용된다.
DIPROPGUIDANDPATH
DIPROP_GUIDANDPATH 에 사용된다.
DIPROPRANGE
수치의 페어로 나타내지는 프로퍼티에 사용된다. 현재로서는, 이것에 해당하는 프로퍼티는 DIPROP_RANGE 뿐인다.
DIPROPSTRING
캐릭터 라인 프로퍼티에 사용된다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

주의

이하의 C 코드의 예는, DIPROP_BUFFERSIZE 프로퍼티값의 취득 방법을 설명한다.

DIPROPDWORD dipdw;  // DIPROPDWORD 은 DIPROPHEADER 구조체를 저장 한다.
HRESULT hr;
dipdw.diph.dwSize       = sizeof(DIPROPDWORD);
dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);
dipdw.diph.dwObj        = 0; // 디바이스 프로퍼티
dipdw.diph.dwHow        = DIPH_DEVICE;

hr = IDirectInputDevice8_GetProperty(pdid, DIPROP_BUFFERSIZE, &dipdw.diph);
if (SUCCEEDED(hr)) {
    // dipdw.dwData 멤버는 버퍼 사이즈를 저장 한다.
}

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::SetProperty


IDirectInputDevice8::Initialize

DirectInputDevice 오브젝트를 초기화한다. IDirectInput8::CreateDevice 메소드는, 디바이스의 생성 후, 자동적으로 디바이스를 초기화하므로, 어플리케이션은 보통, 이 메소드를 호출할 필요는 없다.

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFGUID rguid
);

파라미터

hinst
DirectInputDevice 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들. Microsoft® DirectInput® 는, 이 값을 사용해, 어플리케이션 또는 DLL 가, 오브젝트 생성의 자격을 인정받고 있는지 어떤지를 판단해, 하위 호환성을 위해서(때문에) 취해야 할 특별한 동작을 확정한다.

DLL 가 부모의 어플리케이션의 핸들을 건네주면(자), 에러가 된다. 예를 들어, Web 페이지에 파묻히고 있어 DirectInput 를 사용하는 Microsoft ActiveX® 컨트롤은, Web 브라우저의 핸들은 아니고, 그것 자신의 인스턴스의 핸들을 건네주지 않으면 안 된다. 이것에 의해, DirectInput 가 그 컨트롤을 인식해, 필요라고 생각되는 특별한 동작을 모두 유효하게 하는 것이 확실히 된다.

dwVersion
어플리케이션의 설계 대상인 DirectInput 의 버젼 번호. 이 값은 보통, DIRECTINPUT_VERSION 이다. 이전의 버젼 번호를 건네주면(자), DirectInput 가 그 버젼을 에뮤레이트 하게 된다.
rguid
C++ 의 경우, 인터페이스를 관련짓는 디바이스의 인스턴스를 식별하는 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소. IDirectInput8::EnumDevices 메소드를 사용하면(자), 시스템이 어느 인스턴스 GUID 를 지원 하고 있는지를 확인할 수가 있다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_ACQUIRED
DIERR_DEVICENOTREG

S_FALSE 가 돌려주어지면,rGUID 를 개입시켜 건네받은 인스턴스 GUID 를 가지는 디바이스는 초기화가 끝난 상태이다.

주의

이 메소드가 실패하는 경우, 기저의 오브젝트는 부정 상태에 있는 것으로 간주해, 사용전에 재초기화해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::Poll

Microsoft® DirectInput® 디바이스 위에의 폴링 대상 오브젝트로부터 데이터를 취득한다. 디바이스에 폴링이 필요없을 때에 이 메소드를 호출해도, 효과는 일절 없다. 폴링 할 필요가 있는 디바이스가 정기적으로 폴링 되지 않는 경우, 이 디바이스로부터 새로운 데이터는 취득되지 않는다. 이 메소드를 호출하면, DirectInput 는 디바이스 상태를 갱신해, 버퍼링 데이터가 사용 가능하면 입력 이벤트를 생성해, 통지가 유효하면 통지 이벤트를 설정한다.

HRESULT Poll()

파라미터

없음.

반환값

성공했을 경우는, DI_OK 를 돌려준다. 디바이스가 폴링을 요구하지 않는 경우는 DI_NOEFFECT 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_NOTINITIALIZED

주의

디바이스 데이터를 폴링 하기 전에,IDirectInputDevice8::SetDataFormat 또는 IDirectInputDevice8::SetActionMap 메소드로 데이터 형식을 설정해,IDirectInputDevice8::Acquire 메소드로 디바이스를 취득해 두지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

폴링과 이벤트 통지


IDirectInputDevice8::RunControlPanel

이 디바이스에 관련지을 수 있었던 Microsoft® DirectInput® 컨트롤 패널을 실행한다. 디바이스에 컨트롤 패널을 관련지을 수 있지 않은 경우는, 디폴트의 컨트롤 패널이 기동된다.

HRESULT RunControlPanel(
  HWND hwndOwner,
  DWORD dwFlags
);

파라미터

hwndOwner
부모 윈도우의 핸들. 이 파라미터가 NULL 라면, 부모 윈도우는 사용되지 않는다.
dwFlags
현재미사용이다. 제로만이 유효한 값이다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::SendDeviceData

출력을 받아들이는 디바이스에 데이터를 송신한다. 디바이스는, 취득 끝난 상태가 아니면 안된다.

HRESULT SendDeviceData(
  DWORD cbObjectData,
  LPCDIDEVICEOBJECTDATA rgdod,
  LPDWORD pdwInOut,
  DWORD fl
);

파라미터

cbObjectData
단일의 DIDEVICEOBJECTDATA 구조체의 사이즈 (바이트 단위).
rgdod
디바이스에 송신하는 데이터를 저장 한 DIDEVICEOBJECTDATA 구조체의 배열. 이것은,*pdwInOut 요소로 구성되어 있지 않으면 안 된다.

DIDEVICEOBJECTDATA 구조체의 dwOfs 필드에는, 데이터의 송신지가 되는 디바이스 오브젝트의 식별자가 포함되지 않으면 안 된다. 이 식별자는,DIDEVICEOBJECTINSTANCE 구조체의 dwType 필드로부터 취득된다. dwTimeStamp 및 dwSequence 멤버는, 제로가 아니면 안된다.

pdwInOut
호출시는, 이 파라미터가 가리키는 변수에는,rgdod 가 가리키는 배열의 요소수가 포함된다. 종료시는, 디바이스에 송신된 요소수가 포함된다.
fl
데이터의 송신 방법을 제어하는 플래그. 제로 또는 다음의 값을 취할 수가 있다.
DISDD_CONTINUE
송신되는 디바이스 데이터는, 이전에 송신된 디바이스 데이터에 덧쓰기된다. 「주의」를 참조할것.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_REPORTFULL
DIERR_UNPLUGGED

주의

개별의 데이터 요소가 특정의 순서로 송신된다고 하는 보증은 없다. 그러나,IDirectInputDevice8::SendDeviceData 의 호출이 성공했을 경우, 송신된 데이터의 사이에 다른 데이터가 섞여 올 것은 없다. 또, 복수의 데이터가 1 회의 호출로 같은 오브젝트에 송신되는 경우, 어느 데이터가 송신될까는 특정되지 않는다.

예를 들어, 데이터를 패킷 단위로 송신할 수 있는 디바이스가 있어, 각 패킷은, A 및 B 라고 하는 2 개의 정보를 나타낸다고 한다. 여기서, 어플리케이션이 3 개의 데이터 요소 (B = 2, A = 1, B =0)를 송신하려고 하면(자) 어떻게 될까.

실제의 디바이스에 송신되는 패킷은 1 개이다. 패킷의 A 필드의 값은 1, 그리고 패킷의 B 필드의 값은 2 나 0 이 된다.

데이터를 지정대로 디바이스에 송신할 필요가 있는 경우는,IDirectInputDevice8::SendDeviceData 를 3 회 호출해, 호출할 것에 데이터 요소를 1 개씩 송신해야 한다.

최초의 호출해에 응답해, A 필드가 공백, B 필드의 값이 2 의 패킷을 디바이스에 송신한다.

2 번째의 호출에서는, A 필드의 값이 1, B 필드가 공백의 패킷을 송신한다.

마지막 3 번째의 호출로, A 필드가 공백, B 필드의 값이 0 의 패킷을 송신한다.

DISDD_CONTINUE 플래그가 설정되어 있는 경우, 송신된 디바이스 데이터는 이전에 송신된 디바이스 데이터에 덧쓰기된다. 그 이외의 경우, 송신되는 디바이스 데이터는, 이전에 송신된 디바이스 데이터를 포함하지 않는다.

예를 들어, Button0 및 Button1 의 2 개의 버튼 출력을 지원 하는 디바이스가 있다고 한다. 어플리케이션이 최초로 IDirectInputDevice8::SendDeviceData 를 호출해 "Button0 압하" 를 건네주면(자), 디바이스에는,"Button0 압하, Button1 미압하" 라고 하는 형식의 패킷이 송신된다. 다음에, 어플리케이션이 한번 더 SendDeviceData 를 호출해 "Button1 압하" 와 DISDD_CONTINUE 플래그를 건네주면(자), 디바이스에는,"Button0 압하, Button1 압하" 라고 하는 형식의 패킷이 송신된다. 그러나, 어플리케이션이 DISDD_CONTINUE 플래그를 건네주지 않았던 경우, 디바이스에 송신되는 패킷은,"Button0 미압하 , Button1 압하" 가 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::SendForceFeedbackCommand

디바이스의 force feedback 시스템에 커멘드를 송신한다.

HRESULT SendForceFeedbackCommand(
  DWORD dwFlags
);

파라미터

dwFlags
목적 상태 변화를 나타내는 단일의 값. 다음의 어느쪽이든 1 개의 값을 취할 수가 있다.
DISFFC_CONTINUE
중단된 모든 액티브한 이펙트의 재생을 계속한다. 디바이스가 중단 상태에 없을 때에 이 커멘드를 송신 하면, 에러가 된다.
DISFFC_PAUSE
모든 액티브 이펙트의 재생을 중단한다. 이 커멘드는 이펙트의 클락도 정지하므로, 재개 하면, 이펙트는 계속 시간을 만료할 때까지 재생이 속행된다.

디바이스가 중단 상태에 있는 동안은, 새로운 이펙트를 시작 하거나 기존의 이펙트를 변경하거나 할 수 없다. 그러한 조작을 실시하면, 이 이후의 DISFFC_CONTINUE 커멘드가 정상적으로 기능하지 않게 되는 일이 있다.

중단을 파기해 모든 이펙트를 정지하려면 , DISFFC_STOPALL 또는 DISFCC_RESET 커멘드를 사용한다.

DISFFC_RESET
디바이스의 force feedback 시스템을 시동 상태로 한다. 모든 이펙트는 디바이스로부터 삭제되어 유효하지 않게 된다. 이러한 이펙트를 다시 사용하려면 , 재생성해야 한다. 디바이스의 액츄에이터는 무효이다.
DISFFC_SETACTUATORSOFF
디바이스의 force feedback 액츄에이터를 무효로 한다. 액츄에이터가 오프의 사이도, 이펙트는 계속해 재생되지만, 디바이스는 그것을 무시한다. 음악 재생 디바이스에 비유하면(자), 이펙트는 일시정지 (포즈)는 아니고, 소음 (뮤트)된 상태이다.
DISFFC_SETACTUATORSON
디바이스의 force feedback 액츄에이터를 유효하게 한다.
DISFFC_STOPALL
모든 액티브한 이펙트의 재생을 정지한다. 액티브한 이펙트는 모두 리셋 되지만, 디바이스에는 보존되고 있어 계속해 유효하다. 디바이스가 중단되고 있는 경우, 그 상태는 없어진다.

이 커멘드는, 재생중의 이펙트 마다 IDirectInputEffect::Stop 메소드를 호출하는 것에 동일하다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::SetActionMap

디바이스의 데이터 형식을 설정해, 어플리케이션 정의의 액션을 디바이스 오브젝트에 맵 한다. 버퍼링 데이터의 버퍼 사이즈도 설정한다.

주 : 이 메소드를 호출하기 전에, 디바이스를 해방해 둘 필요가 있다.

HRESULT SetActionMap(
  LPCDIACTIONFORMAT lpdiActionFormat,
  LPCWSTR lptszUserName,
  DWORD dwFlags
);

파라미터

lpdiActionFormat
적용하는 액션 맵에 관한 정보를 저장 하는,DIACTIONFORMAT 구조체의 주소.
lptszUserName
어느 유저의 액션 맵을 설정해 있을까에 임해서, 유저명을 지정하는 Unicode 캐릭터 라인. NULL 를 지정 하면, 현재 시스템에 로그인하고 있는 유저를 나타낸다.
dwFlags
액션 맵의 적용 방법을 지정하는 DWORD 값. 이 값은, 다음의 값의 언젠가이다.
DIDSAM_DEFAULT
이 유저의 액션 맵을 설정한다. 맵이 현재의 맵과 다른 경우, 새로운 설정이 디스크에 보존된다.
DIDSAM_FORCESAVE
구성을 항상 디스크에 보존한다.
DIDSAM_NOUSER
디폴트의 구성 프로퍼티 시트로 이 디바이스의 유저 소유권을 리셋 한다. 유저 소유권을 리셋 해도, 현재의 액션 맵은 삭제되지 않는다.

반환값

성공했을 경우는, 다음의 몇개의 반환값을 돌려준다.

DI_OK
DI_SETTINGSNOTSAVED
DI_WRITEPROTECT

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_ACQUIRED
DIERR_INVALIDPARAM

주의

이 메소드를 사용하는 것으로, 액션과 컨트롤의 매핑을 디바이스의 디폴트로부터 변경할 수 있다. 어플리케이션은, 이 메소드를 사용해 게임내의 액션을 가상 컨트롤에 맵 할 필요가 있다.

이 메소드에게 건네지는 유저명에 의해, 디바이스의 액션 매핑세트가 특정 유저에게 바인드 된다. 설정이 현재 적용되고 있는 맵과 다른 경우는, 자동적으로 디스크에 보존된다. 복수의 유저로부터 입력을 받아들이는 어플리케이션은, 각 유저의 액션 맵이 경합 할 가능성이 있으므로, 시스템의 마우스나 키보드에 액션 맵을 적용할 때는 주의가 필요하다.

이 메소드는 디바이스가 취득되어 있지 않은 경우에게만 호출할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::BuildActionMap


IDirectInputDevice8::SetCooperativeLevel

디바이스의 인스턴스에 대한 협조 레벨을 확립한다. 협조 레벨은, 이 인스턴스가, 같은 디바이스외의 인스턴스, 및 시스템의 이외의 부분과의 사이로, 어떻게 대화할까를 결정한다.

HRESULT SetCooperativeLevel(
  HWND hwnd,
  DWORD dwFlags
);

파라미터

hwnd
디바이스에 관련지을 수 있고 있는 윈도우 핸들. 이 파라미터는, 이 프로세스에 속하는 최상정도의 유효한 윈도우 핸들이 아니면 안된다. 디바이스에 관련지을 수 있었던 윈도우는, Microsoft® DirectInput® 디바이스 중(안)에서 액티브한 사이는, 파괴해서는 안 된다.
dwFlags
디바이스에 관련짓는 협조 레벨을 나타내는 플래그. 다음의 플래그가 정의되고 있다.
DISCL_BACKGROUND
어플리케이션은, 백그라운드 액세스권을 요구한다. 백그라운드 액세스권이 허가되면(자), 할당할 수 있었던 윈도우가 액티브 윈도우가 아닌 경우에서도, 언제라도 디바이스를 취득할 수 있다.
DISCL_EXCLUSIVE
어플리케이션은, 배타 액세스권을 요구한다. 배타 액세스권이 부여되면(자), 디바이스가 취득되고 있는 동안, 디바이스외의 인스턴스는, 그 디바이스의 배타 액세스권을 취득할 수 없다. 다만, 다른 어플리케이션이 배타 액세스권을 취득하고 있는 경우에서도, 디바이스의 비배타 액세스권은 항상 인정된다.

어플리케이션이 마우스 또는 키보드 디바이스를 배타 모드로 취득하고 있는 경우는, WM_ENTERSIZEMOVE 메세지 및 WM_ENTERMENULOOP 메세지를 받아들이면(자), 항상 디바이스를 해방할 필요가 있다. 그 이외의 경우, 유저는 메뉴를 조작하거나 윈도우를 이동 또는 윈도우의 사이즈를 변경하거나 할 수 없다.

DISCL_FOREGROUND
어플리케이션은 foreground 액세스권을 요구한다. foreground 액세스권이 부여되면(자), 할당할 수 있었던 윈도우가 백그라운드로 이동할 때, 디바이스는 자동적으로 해방된다.
DISCL_NONEXCLUSIVE
어플리케이션은 비배타 액세스권을 요구한다. 디바이스에 대한 액세스권은, 같은 디바이스에 액세스 하고 있는 것 외의 어플리케이션의 방해가 되지 않는다.
DISCL_NOWINKEY
Windows 키를 무효로 한다. 이 플래그를 설정 하면, 유저는 잘못해 어플리케이션을 종료하는 것이 없어진다. 다만, 디폴트의 액션 매핑 UI 가 표시되고 있는 동안은 DISCL_NOWINKEY 플래그는 무효이며, 또, 디폴트의 액션 매핑 UI 가 존재하고 있는 동안은 Microsoft Windows® 키는 보통 대로 기능한다.

어플리케이션은, DISCL_FOREGROUND 또는 DISCL_BACKGROUND 의 어느 쪽인지 한편을 지정해야 한다. 양쪽 모두 지정하는 일도, 전혀 지정하지 않는 것도 에러가 된다. 같이 어플리케이션은, DISCL_EXCLUSIVE 또는 DISCL_NONEXCLUSIVE 의 어느 쪽인지 한편을 지정해야 한다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_HANDLE

주의

시스템 마우스가 배타 모드로 취득되면(자), 마우스 포인터는, 디바이스가 해방될 때까지 화면으로부터 소거된다. 이것에 해당하는 것은, GUID_SysMouse 을 IDirectInput8::CreateDevice 에 건네주어 생성 된 마우스뿐이다.

어플리케이션은,IDirectInputDevice8::Acquire 메소드로 디바이스를 취득하기 전에, 이 메소드를 호출하지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

협조 레벨


IDirectInputDevice8::SetDataFormat

Microsoft® DirectInput® 디바이스의 데이터 형식을 설정한다.

HRESULT SetDataFormat(
  LPCDIDATAFORMAT lpdf
);

파라미터

lpdf
DirectInputDevice 가 돌려주어야 할 데이터 형식을 기술하는 구조체의 주소. 어플리케이션은, 독자적인 DIDATAFORMAT 구조체를 정의하는 일도, 다음일 전정의된 글로벌 변수의 1 개를 사용할 수도 있다.
  • c_dfDIKeyboard
  • c_dfDIMouse
  • c_dfDIMouse2
  • c_dfDIJoystick
  • c_dfDIJoystick2

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_ACQUIRED
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

IDirectInputDevice8::Acquire 로 디바이스를 취득하기 전에, 데이터 형식을 설정해 두지 않으면 안 된다. 데이터 형식은, 한 번 설정하는 것만으로 좋다. 데이터 형식은, 디바이스가 취득되고 있는 동안은 변경할 수 없다.

어플리케이션이 액션 맵을 사용하고 있는 경우는, 대신에 IDirectInputDevice8::SetActionMap 를 호출하는 것으로 데이터 형식이 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::GetDeviceState


IDirectInputDevice8::SetEventNotification

디바이스 상태가 변화했을 때에 설정되는 이벤트를 지정한다. 이벤트 통지를 오프로 하기 위해서(때문에)도 사용된다.

HRESULT SetEventNotification(
  HANDLE hEvent
);

파라미터

hEvent
디바이스 상태가 변화했을 때에 설정되는 이벤트의 핸들. Microsoft® DirectInput® 는 디바이스 상태가 변화했을 때에, 이 핸들에 대해서 Microsoft® Win32 SetEvent 함수를 사용한다. hEvent 파라미터를 NULL 로 하면(자), 통지는 무효가 된다.

어플리케이션은, Microsoft® Win32® CreateEvent 함수를 사용해, 수동 리셋 이벤트 또는 자동 리셋 이벤트로서 핸들을 생성 할 수가 있다. 이벤트를 자동 리셋 이벤트로서 생성 하면, operating system는, 대기 시간이 경과했을 때에 자동적으로 이벤트를 리셋 한다. 이벤트를 수동 리셋 이벤트로서 생성 하면, 어플리케이션은, Win32 ResetEvent 함수를 호출해 이벤트를 리셋 해야 한다. DirectInput 는, 이벤트 통지 핸들에 대해서, Win32 ResetEvent 함수를 호출하지 않는다. 어플리케이션은, 보통, 이벤트를 자동 리셋 이벤트로서 생성 한다.

반환값

성공했을 경우는,DI_POLLEDDEVICE 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_ACQUIRED
DIERR_HANDLEEXISTS
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

디바이스 상태의 변경은 다음의 어느 쪽인가에 정의된다.

  • 축의 위치의 변경
  • 버튼 상태 (누른 상태 또는 떼어 놓은 상태)
  • 시점 컨트롤의 방향의 변경
  • 취득의 상실

DirectInputDevice 오브젝트중에 선택되고 있는 이벤트에 대해서는, Win32 CloseHandle 함수를 호출해서는 안 된다. 이벤트 핸들을 종료하기 전에,hEvent 파라미터에 NULL 를 설정해, 이 메소드를 호출하지 않으면 안 된다.

이벤트 통지 핸들은, 디바이스가 취득되고 있는 동안은 변경할 수 없다. 이 함수가 성공하면, 어플리케이션은, 다른 Win32 이벤트 핸들과 같게, 이 이벤트 핸들을 사용할 수 있다.

이하의 예는, 핸들이 현재 블로킹없이 설정되어 있는지 어떤지를 체크한다.

dwResult = WaitForSingleObject(hEvent, 0);
if (dwResult == WAIT_OBJECT_0) {
    // 이벤트를 설정한다. 이벤트가 자동 리셋으로
    // 생성 되고 있었을 경우는, 동시에 리셋 된다.
}

다음의 예는, 이벤트가 설정될 때까지, 반복 블로킹을 실시하는 처리를 나타내고 있다. 대기 시간이 경과할 때까지, thread는 시스템에 응답할 수 없기 때문에, 이 동작은 엄금이다. 특히, thread는 Windows® 메세지에 응답하지 않게 된다.

dwResult = WaitForSingleObject(hEvent, INFINITE);
if (dwResult == WAIT_OBJECT_0) {
    // 이벤트가 설정되었다. 이벤트가 자동 리셋으로
    // 생성 되고 있었을 경우는, 동시에 리셋 된다.
}

이하의 예는, 2 개의 이벤트를 사용하는 메세지 베이스의 어플리케이션의, 전형적인 메시지 루프를 나타내고 있다.

HANDLE ah[2] = { hEvent1, hEvent2 };

while (TRUE) {

    dwResult = MsgWaitForMultipleObjects(2, ah, FALSE,
                        INFINITE, QS_ALLINPUT);
    switch (dwResult) {
    case WAIT_OBJECT_0:
        // 이벤트 1 이 설정되었다. 이벤트가 자동 리셋으로
        // 생성 되고 있었을 경우는, 동시에 리셋 된다.
        ProcessInputEvent1();
        break;

    case WAIT_OBJECT_0 + 1:
        // 이벤트 2 가 설정되었다. 이벤트가 자동 리셋으로
        // 생성 되고 있었을 경우는, 동시에 리셋 된다.
        ProcessInputEvent2();
        break;

    case WAIT_OBJECT_0 + 2:
        // Windows 메세지를 받아들였다. 이러한
        // 메세지가 없어질 때까지 처리를 계속한다.
        while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)){
            if (msg.message == WM_QUIT) {
                goto exitapp;
            }
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }
        break;

    default:
        // 예기치 않은 에러.
        Panic();
        break;
    }
}

다음의 예는, 2 개의 이벤트를 사용하는 비메세지 베이스의 어플리케이션의, 전형적인 메시지 루프를 나타내고 있다.

HANDLE ah[2] = { hEvent1, hEvent2 };
DWORD dwWait = 0;

while (TRUE) {

    dwResult = MsgWaitForMultipleObjects(2, ah, FALSE,
                                         dwWait, QS_ALLINPUT);
    dwWait = 0;

    switch (dwResult) {
    case WAIT_OBJECT_0:
        // 이벤트 1 이 설정되었다. 이벤트가 자동 리셋으로
        // 생성 되고 있었을 경우는, 동시에
        // 리셋 된다.
        ProcessInputEvent1();
        break;

    case WAIT_OBJECT_0 + 1:
        // 이벤트 2 가 설정되었다. 이벤트가 자동 리셋으로
        // 생성 되고 있었을 경우는, 동시에
        // 리셋 된다.
        ProcessInputEvent2();
        break;

    case WAIT_OBJECT_0 + 2:
        // Windows 메세지를 받아들였다. 이러한
        // 메세지가 없어질 때까지 처리를 계속한다.
        while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)){
            if (msg.message == WM_QUIT) {
                goto exitapp;
            }
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }
        break;

    default:
        // 입력 혹은 대기중의 메세지가 없다.
        // 게임의 프레임을 만든다.
        // 게임이 아이돌 상태이면,
        // 입력 혹은 메세지를 계속 기다린다.
        if (! DoGame()) {
            dwWait = INFINITE;
        }
        break;
    }
}

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

폴링과 이벤트 통지


IDirectInputDevice8::SetProperty

디바이스의 동작을 정의하는 프로퍼티를 설정한다. 이러한 프로퍼티에는, 입력 버퍼 사이즈나 축모드등이 있다.

HRESULT SetProperty(
  REFGUID rguidProp,
  LPCDIPROPHEADER pdiph
);

파라미터

rguidProp
C++ 의 경우, 설정하는 프로퍼티를 식별하는 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소. 이 식별자는, 사전 정의된 값의 1 개에서도, 또는 프로퍼티를 식별하는 GUID 에의 포인터라도 좋다. 이하의 프로퍼티값이 입력 디바이스에 대해서 사전 정의되고 있다.
DIPROP_APPDATA
게임내의 액션과 연결시킬 수 있었던 어플리케이션 정의의 값을 DIPROPPOINTER 로서 설정한다.
DIPROP_AUTOCENTER
디바이스 오브젝트가 자동 센터링을 실시할지 어떨지를 지정한다. 이 설정값은, 개별의 오브젝트는 아니고 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다.

dwData 멤버는, 다음의 어느쪽이든 1 개의 값을 취할 수가 있다.

DIPROPAUTOCENTER_OFF:유저가 디바이스를 떼어 놓아도, 자동적으로 센터링을 실시하지 않는다. force feedback를 사용하는 어플리케이션은, 이펙트의 재생전에 자동 센터링을 무효로 할 필요가 있다.

DIPROPAUTOCENTER_ON:유저가 디바이스를 떼어 놓으면(자), 자동적으로 센터링을 실시한다.

자동 센터링 기능을 지원 하고 있지 않는 디바이스도 있다.

DIPROP_AXISMODE
축모드를 설정한다. 설정값 (DIPROPAXISMODE_ABS 또는 DIPROPAXISMODE_REL) 은, 할당할 수 있었던 DIPROPDWORD 구조체의 dwData 멤버로 지정하지 않으면 안 된다. 자세한 것은 pdiph 파라미터의 설명을 참조할것.

이 설정값은 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다

DIPROP_BUFFERSIZE
입력 버퍼 사이즈를 설정한다. 설정값은, 할당할 수 있었던 DIPROPDWORD 구조체의 dwData 멤버로 지정하지 않으면 안 된다. 「주의」를 참조할것.

이 설정값은 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다

DIPROP_CALIBRATIONMODE
Microsoft® DirectInput® 가 취득하는 데이터가, calibration가 끝난 상태나 calibration전인지를, 어플리케이션을 지정할 수 있도록(듯이) 한다. 디폴트에서는, DirectInput 는 calibration가 끝난 데이터를 취득한다.

디바이스 전체에 대해서 calibration 모드를 설정하는 것은, 각각의 축으로 대해 calibration 모드를 설정하는 것으로 같은 의미를 가진다.

DIPROPDWORD 구조체의 dwData 멤버는 다음의 어느쪽이든 1개의 값을 취할 수가 있다.

DIPROPCALIBRATIONMODE_COOKED:DirectInput 는, calibration 정보의 적용 후의 데이터를 돌려준다. 이것이 디폴트 모드이다.

DIPROPCALIBRATIONMODE_RAW:DirectInput 는, calibration전의 미가공 데이터를 돌려준다. 이 모드는 보통, 컨트롤 패널형의 어플리케이션에서만 사용된다. 미가공 데이터에는 마이너스값이 포함되는 일도 있는 것에 주의 해야 한다.

디바이스를 미가공 모드로 설정 하면,데드 존,포화, 및 범위의 설정이 무시된다.

DIPROP_CPOINTS
미가공의 도착 데이터를 조정하기 위해서 사용하는 calibration 포인트를 설정한다. 설정값은, 할당할 수 있었던 DIPROPCPOINTS 구조체의 cp 배열내의 CPOINT 형으로서 지정해야 한다.

이 설정값은 개별의 디바이스 오브젝트에 적용되므로, 할당할 수 있었던 DIPROPHEADER 구조체의 dwHow 멤버는, DIPH_BYID 또는 DIPH_BYOFFSETT 의 어느 쪽인가에 설정되지 않으면 안 된다.

DIPROP_DEADZONE
0 ~ 10,000 의 범위에서 죠이스틱의데드 존의 값을 설정한다. 여기서, 0 은 데드 존이 존재하지 않는 것, 5,000 은 데드 존이 축을 중심으로 한 물리 범위의 50 퍼센트에까지 퍼지고 있는 것, 및 10,000 은 축의 물리 범위의 전체가 무효라는 점을 각각 가리킨다. 축이 데드 존내에 있으면(자), 축의 범위의 중심에 있는 것이라고 보고된다.

이 설정은, 디바이스 전체 또는 1 개의 특정의 축의 어딘가에 적용할 수 있다.

DIPROP_FFGAIN
디바이스의 게인을 설정한다. 이 설정값은, 개별의 오브젝트는 아니고 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다.

dwData 멤버는, 디바이스상에 생성 된 모든 이펙트에 적용되는 게인값을 저장 한다. 값은, 0 ~ 10,000 의 정수이다. 디바이스에 대한 이펙트의 매그니튜드는, 이 값으로 조정된다. 예를 들어, 10,000 은, 모든 이펙트 매그니튜드를 그대로 적용하는 것을 나타낸다. 9,000 은, 모든 이펙트 매그니튜드를 그 명목 매그니튜드의 90 퍼센트에 압축하는 것을 나타낸다.

게인값의 설정은, 유저의 취향에 응해, 모든 force feedback 이펙트를 1율에 감소하고 싶은 경우에 유효하다.

다른 프로퍼티와는 달라, 게인은 디바이스가 취득 상태에 있는 경우로 설정할 수 있다.

DIPROP_INSTANCENAME
이것은, 상세 설정의 가능한 어플리케이션용으로 설치된 프로퍼티이며, 이것을 사용해 디바이스의 인스턴스의 등록명을 변경 하면, 접속되고 있는 동종의 디바이스를 구별할 수가 있다. 인스턴스의 등록명은,DIDEVICEINSTANCE 구조체의 tszInstanceName 멤버내에 돌려주어진다. 어플리케이션은 보통, 등록명을 변경할 필요는 없다.

이 설정값은 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다

pdiph 파라미터는,DIPROPSTRING 구조체의 diph 멤버에의 포인터가 아니면 안된다.

DIPROP_PRODUCTNAME
이것은, 상세 설정의 가능한 어플리케이션용으로 설치된 프로퍼티이며, 이것을 사용해 디바이스의 제품의 등록명을 변경 하면, 접속되고 있는 동종의 디바이스를 구별할 수가 있다. 제품의 등록명은,DIDEVICEINSTANCE 구조체의 tszProductName 멤버내에 돌려주어진다. 어플리케이션은 보통, 등록명을 변경할 필요는 없다.

이 설정값은 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다

pdiph 파라미터는,DIPROPSTRING 구조체의 diph 멤버에의 포인터가 아니면 안된다.

DIPROP_RANGE
오브젝트가 보고 가능한 값의 범위를 설정한다. 최소 값 및 최대치는, 할당할 수 있었던 DIPROPRANGE 구조체의 lMin 멤버와 lMax 멤버로부터 취득된다.

일부의 디바이스에서는, 이것은 읽어내 전용 프로퍼티이다.

범위의 대소를 반대로는 할 수 없다. lMax 는,lMin 보다 큰 값이 아니면 안된다.

DIPROP_SATURATION
0 ~ 10,000 의 범위에서 죠이스틱의포화 존의 값을 설정한다. 포화 레벨이란, 축이 극한 위치에 있다고 보이는 포인트이다. 예를 들어, 포화 레벨이 9,500 으로 설정되어 있는 경우, 축의 중심 (데드 존)으로부터 축의 구석까지의 물리적 거리의 95% 의 위치가 축의 극한 위치가 된다.

이 설정은, 디바이스 전체 또는 1 개의 특정의 축의 어딘가에 적용할 수 있다.

pdiph
타입 고유의 프로퍼티 구조체에 포함되는 DIPROPHEADER 구조체의 주소.

반환값

성공했을 경우는, DI_OK 또는 DI_PROPNOEFFECT 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

주의

버퍼 사이즈는,IDirectInputDevice8::GetDeviceData 메소드의 전회와 이번 호출동안에서, 버퍼가 데이터를 잃는 일 없이 보관 유지할 수 있는 데이터의 양을 결정한다. 이 값에 제로를 설정해, 어플리케이션이 디바이스로부터 버퍼링 데이터를 읽어들이지 않게 지정할 수도 있다. DIPROPDWORD 구조체의 dwData 멤버중의 버퍼 사이즈가 너무 커 디바이스가 지원 할 수 없는 경우는, 지원 가능한 최대 버퍼 사이즈가 설정된다. 요구한 버퍼 사이즈가 설정되었는지 어떠했는지를 확인하려면 , 버퍼 사이즈 프로퍼티를 취득해, 설정하려고 한 값과 그 결과를 비교한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::GetProperty


IDirectInputDevice8::Unacquire

입력 디바이스에의 액세스권을 해방한다.

HRESULT Unacquire();

파라미터

없음.

반환값

디바이스가 해방되었을 경우는 DI_OK 를 돌려주어, 디바이스가 취득 상태에 없었던 경우는 DI_NOEFFECT 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputDevice8::WriteEffectToFile

1 개(살) 이상의 force feedback 이펙트에 대한 정보를 파일에 보존한다. 이 파일은,IDirectInputDevice8::EnumEffectsInFile 를 사용해 읽어낼 수가 있다. 이것은 주로, 독자적인 포스를 생성하는 어플리케이션을 생성 하고 싶은 개발자전용의 메소드이다.

HRESULT WriteEffectToFile(
  LPCSTR lpszFileName,
  DWORD dwEntries,
  LPCDIFILEEFFECT rgDiFileEft,
  DWORD dwFlags
);

파라미터

lpszFileName
RIFF 파일의 이름.
dwEntries
rgDiFileEft 배열중의 구조체의 수.
rgDiFileEft
DIFILEEFFECT 구조체의 배열.
dwFlags
이펙트의 기술 방법을 제어하는 플래그. DIFEF_DEFAULT (= 0), 또는 다음의 값을 취할 수가 있다.
DIFEF_INCLUDENONSTANDARD
Microsoft® DirectInput® 로 정의되어 있지 않은 이펙트를 포함한다. 이 플래그가 지정되지 않는 경우는, GUID_ConstantForce 등, Dinput.h 에 정의된 GUID 를 가지는 이펙트만이 기술된다.

반환값

메소드가 성공했을 경우는, DI_OK 를 돌려준다.

실패하면 DIERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::EnumEffectsInFile


IDirectInputEffect

어플리케이션은,IDirectInputEffect 인터페이스의 메소드를 사용해, force feedback 디바이스의 이펙트를 관리한다.

이 인터페이스는 IDirectInputDevice8::CreateEffect 메소드를 사용해 취득된다.

IDirectInputEffect 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

이펙트의 정보 | GetEffectGuid
 | GetEffectStatus
 | GetParameters
이펙트의 조작 | Download
 | Initialize
 | SetParameters
 | Start
 | Stop
 | Unload
그 외 | Escape

모든 COM 인터페이스와 같게,IDirectInputEffect 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUTEFFECT 형은 IDirectInputEffect 인터페이스에의 포인터로서 정의된다.

typedef struct IDirectInputEffect    *LPDIRECTINPUTEFFECT;

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::Download

디바이스에 이펙트를 설정한다. 같은 이펙트가 이미 디바이스에 있으면,IDirectInputEffect::SetParameters 메소드로 설정된 값에 적합하도록(듯이), 기존의 이펙트가 갱신된다.

HRESULT Download(void);

파라미터

없음.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_DEVICEFULL
DIERR_EFFECTPLAYING
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

S_FALSE 가 돌려주어졌을 경우, 그 이펙트는 이미 디바이스에 다운로드되고 있다.

주의

이펙트의 재생중에 이펙트를 갱신하는 것은 유효하다. 이 조작의 의미는,IDirectInputEffect::SetParameters 의 레퍼런스 중(안)에서 설명되고 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::Escape

하드웨어 고유의 커멘드를 드라이버에 송신한다.

HRESULT Escape(
  LPDIEFFESCAPE pesc
);

파라미터

pesc
송신하는 커멘드를 기술하는 DIEFFESCAPE 구조체. 성공하면(자), 사용된 출력 버퍼의 바이트수가 cbOutBuffer 멤버에 저장 된다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_NOTINITIALIZED
DIERR_DEVICEFULL

다른 디바이스 고유 에러 코드를 돌려줄 수도 있다. 하드웨어 메이커로부터 상세 정보를 입수하는 것.

주의

각 드라이버는, 다른 이스케이프를 이행 하고 있으므로, 올바른 드라이버와 통신하고 있을지 어떨지는, 어플리케이션 자체가 확인해야 한다. 이것은,DIDEVICEINSTANCE 구조체의 guidFFDriver 멤버와 어플리케이션이 예측하고 있는 값을 비교하는 것으로써 확인할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::GetEffectGuid

IDirectInputEffect 오브젝트가 나타내는 이펙트의 GUID 를 취득한다.

HRESULT GetEffectGuid(
  LPGUID pguid
);

파라미터

pguid
이 메소드에 의해 저장 되는 GUID 구조체.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

취득한 GUID 를 IDirectInputDevice8::GetEffectInfo 에 건네주는 것으로, 그 이펙트에 관한 확장 정보를 취득할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::GetEffectStatus

이펙트의 스테이터스를 취득한다.

HRESULT GetEffectStatus(
  LPDWORD pdwFlags
);

파라미터

pdwFlags
이펙트의 스테이터스 플래그. 제로, 또는 다음의 플래그를 취할 수가 있다.
DIEGES_PLAYING
이펙트는 재생중이다.
DIEGES_EMULATED
이펙트는 에뮤레이트 되고 있다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::GetParameters

이펙트에 관한 정보를 취득한다.

HRESULT GetParameters(
  LPDIEFFECT peff,
  DWORD dwFlags
);

파라미터

peff
이펙트 정보를 받는 DIEFFECT 구조체의 주소. dwSize 멤버는, 이 메소드를 호출하기 전에 어플리케이션에 의해 설정해 두지 않으면 안 된다.
dwFlags
이펙트 정보의 어느 부분을 취득하는지를 지정하는 플래그. 제로, 또는 다음의 플래그를 취할 수가 있다.
DIEP_ALLPARAMS
다른 모든 DIEP_* 플래그가 조합한 것으로,DIEFFECT 구조체의 전멤버를 요구하는 것을 나타낸다.
DIEP_ALLPARAMS_DX5
DIEP_STARTDELAY 플래그를 제외한 모든 DIEP_* 플래그를 조합한 것.
DIEP_AXES
cAxes 및 rgdwAxes 멤버가 데이터를 받는다. 입력 파라미터로서cAxes 는 rgdwAxes 가 가리키는 버퍼의 사이즈 (DWORD 단위)를 저장 한다. 버퍼가 너무 작으면(자), 이 메소드는 DIERR_MOREDATA 를 돌려주어, 필요한 버퍼 사이즈를 cAxes 로 설정한다.
DIEP_DIRECTION
cAxes 및 rglDirection 멤버가 데이터를 받는다. 입력 파라미터로서cAxes 는 rglDirection 가 가리키는 버퍼의 사이즈 (DWORD 단위)를 저장 한다. 버퍼가 너무 작으면(자),GetParameters 메소드는 DIERR_MOREDATA 를 돌려주어, 필요한 버퍼 사이즈를 cAxes 로 설정한다.

dwFlags 멤버에는, 좌표계 플래그 (DIEFF_CARTESIAN, DIEFF_POLAR 또는 DIEFF_SPHERICAL)의 쳐 적어도 1 개(살)이 설정되어 있지 않으면 안 된다. Microsoft® DirectInput® 는, 지정된 1 개의 좌표계로 나타낸 이펙트의 방향을 돌려준다. 그 때, 필요가 있으면 좌표계간에 변환을 실시한다. 종료시에,dwFlags 멤버에는 1 개의 좌표계 플래그가 설정되어 DirectInput 가 사용하는 좌표계를 지시한다. 특별히, 3 개의 좌표계 플래그 모든 것을 건네주면(자), 그러한 좌표를 설정한 것과 완전히 같은 형식에서 좌표가 취득된다.

DIEP_DURATION
dwDuration 멤버가 데이터를 받는다.
DIEP_ENVELOPE
lpEnvelope 멤버는, 데이터를 받는 DIENVELOPE 구조체를 가리킨다. 이펙트에 관계하는 포락선이 없을 때는,lpEnvelope 멤버는 NULL 로 설정된다.
DIEP_GAIN
dwGain 멤버가 데이터를 받는다.
DIEP_SAMPLEPERIOD
dwSamplePeriod 멤버가 데이터를 받는다.
DIEP_STARTDELAY
dwStartDelay 멤버가 데이터를 받는다.
DIEP_TRIGGERBUTTON
dwTriggerButton 멤버가 데이터를 받는다.
DIEP_TRIGGERREPEATINTERVAL
dwTriggerRepeatInterval 멤버가 데이터를 받는다.
DIEP_TYPESPECIFICPARAMS
lpvTypeSpecificParams 멤버는,cbTypeSpecificParams 멤버에 의해 사이즈가 지정되는 버퍼를 가리킨다. 리턴시, 이 버퍼에는, 이펙트에 관계하는 타입 고유 데이터가 저장 되어cbTypeSpecificParams 멤버에는, 카피된 바이트수가 저장 된다. 어플리케이션으로 준비된 버퍼가 너무 작아 타입 고유 데이터 모든 것을 저장 할 수 없는 경우, 이 메소드는 DIERR_MOREDATA 를 돌려주어, 필요하게 되는 버퍼 사이즈의 바이트수가 cbTypeSpecificParams 멤버로 설정된다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INVALIDPARAM
DIERR_MOREDATA
DIERR_NOTINITIALIZED

주의

DIERR_INVALIDPARAM 에러를 발생하는 일반적인 에러에는,DIEFFECT 구조체의 dwSize 멤버의 미설정, 무효인 플래그의 지정, 이펙트 정보의 수취 준비상에서의 DIEFFECT 구조체의 멤버의 부적정인 설정, 등이 있다. 예를 들어, 정보가 dwTriggerButton 멤버에 취득되어야 할 때는, DirectInput 가 버튼을 기술하는 방법을 식별할 수 있도록(듯이),dwFlags 멤버에는, DIEFF_OBJECTIDS 또는 DIEFF_OBJECTOFFSETS 의 어느 쪽인지 한편을 설정해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::Initialize

DirectInputEffect 오브젝트를 초기화한다.

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFGUID rguid
);

파라미터

hinst
DirectInputEffect 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들. Microsoft® DirectInput® 는, 이 값을 사용해, 어플리케이션 또는 DLL 가, 오브젝트 생성의 자격을 인정받고 있는지 어떤지를 판단해, 하위 호환성을 위해서(때문에) 취해야 할 특별한 동작을 확정한다. DLL 가 부모의 어플리케이션의 핸들을 건네주면(자), 에러가 된다.
dwVersion
어플리케이션의 설계 대상인 DirectInput 의 버젼 번호. 이 값은 보통, DIRECTINPUT_VERSION 이다. 이전의 버젼 번호를 건네주면(자), DirectInput 가 그 버젼을 에뮤레이트 하게 된다.
rguid
C++ 의 경우, 인터페이스를 관련지을 수 있고 있는 이펙트를 식별하는 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소. IDirectInputDevice8::EnumEffects 메소드를 사용해, 디바이스가 어느 이펙트 GUID 를 지원 하고 있는지를 확인할 수 있다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는 DIERR_DEVICENOTREG 를 돌려준다.

주의

이 메소드가 실패하는 경우, 기저의 오브젝트는 부정 상태에 있는 것으로 간주해지므로, 다시 초기화하지 않으면 이후의 사용은 할 수 없다.

IDirectInputDevice8::CreateEffect 메소드는, 이펙트를 생성 후, 자동적으로 초기화한다. 어플리케이션은, 보통,Initialize 메소드를 호출할 필요는 없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::SetParameters

이펙트의 특성을 설정한다.

HRESULT SetParameters(
  LPCDIEFFECT peff,
  DWORD dwFlags
);

파라미터

peff
이펙트의 정보를 저장 하는 DIEFFECT 구조체. dwFlags 파라미터의 대응 비트에 의해 지정되고 있는 임의의 멤버와 같이, 이 메소드를 호출하기 전에 어플리케이션에 의해 dwSize 멤버가 설정되어 있지 않으면 안 된다.
dwFlags
이펙트의 정보의 어느 부분을 설정하는지를 지정해, 파라미터의 다운로드 처리의 방법을 지정하는 플래그. 제로, 또는 다음의 플래그를 취할 수가 있다.
DIEP_AXES
cAxes 및 rgdwAxes 멤버가 데이터를 저장 한다.
DIEP_DIRECTION
cAxes 및 rglDirection 멤버가 데이터를 저장 한다. dwFlags 멤버가 (DIEFF_CARTESIAN 또는 DIEFF_POLAR 를 사용해) 값을 해석해야 할 좌표계를 지정한다.
DIEP_DURATION
dwDuration 멤버가 데이터를 저장 한다.
DIEP_ENVELOPE
lpEnvelope 멤버는, 데이터를 저장 하는 DIENVELOPE 구조체를 가리킨다. 이펙트로부터 기존의 포락선을 떼어내려면 , 이 플래그를 건네주어,lpEnvelope 멤버를 NULL 로 설정한다.
DIEP_GAIN
dwGain 멤버가 데이터를 저장 한다.
DIEP_NODOWNLOAD
파라미터의 갱신 후, 보통은 자동 실행되는 IDirectInputEffect::Download 를 억제한다. 「주의」를 참조할것.
DIEP_NORESTART
이펙트의 정지나 재개를 억제해 파라미터를 변경한다. 「주의」를 참조할것.
DIEP_SAMPLEPERIOD
dwSamplePeriod 멤버가 데이터를 저장 한다.
DIEP_START
파라미터의 갱신 후, 이펙트를 시작 (이펙트가 재생중이면, 재개) 시킨다. 디폴트에서는, 이펙트의 재생 상태는 변경되지 않는다.
DIEP_STARTDELAY
dwStartDelay 멤버가 데이터를 저장 한다.
DIEP_TRIGGERBUTTON
dwTriggerButton 멤버가 데이터를 저장 한다.
DIEP_TRIGGERREPEATINTERVAL
dwTriggerRepeatInterval 멤버가 데이터를 저장 한다.
DIEP_TYPESPECIFICPARAMS
DIEFFECT 구조체의 lpvTypeSpecificParams 및 cbTypeSpecificParams 멤버가 이펙트의 타입 고유 데이터의 주소와 사이즈를 저장 한다.

반환값

성공하면 다음의 값의 어느쪽이든을 돌려준다.

DI_DOWNLOADSKIPPED
DI_EFFECTRESTARTED
DI_OK
DI_TRUNCATED
DI_TRUNCATEDANDRESTARTED

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_NOTINITIALIZED
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

주의

이펙트용의 DIEFFECTINFO 구조체의 dwDynamicParams 멤버는, 이펙트의 재생중에 동적으로 갱신할 수 있는 파라미터를 지정한다.

IDirectInputEffect::SetParameters 메소드는, 자동적으로 이펙트를 다운로드하지만, 이 동작은, DIEP_NODOWNLOAD 플래그를 설정하는 것에 의해 억제할 수 있다. 자동 다운로드가 억제되고 있으면,IDirectInputEffect::Download 메소드를 기동해, 이펙트를 수동으로 다운로드할 수가 있다.

이펙트의 재생중에 파라미터가 갱신되면(자), 이펙트의 시작시의 파라미터였는지와 같이, 새로운 파라미터가 유효하게 된다.

예를 들어, 3 초의 계속 시간을 가지는 주기적 이펙트가 시작 되고 있어, 2 초 후에, 이펙트의 방향이 변경된다고 한다. 그 후, 나머지의 1 초의 이펙트는, 새로울 방향으로 계속된다. 포락선, 국면, 진폭등의 이펙트의 파라미터는, 방향이 변경되지 않았는지와 같이 속행된다.

앞의 예와 같은 상황으로, 이번은 2 초 후에 이펙트의 계속 시간이 1.5 초로 변경되었다고 하면, 이펙트는 정지한다.

보통, 드라이버가 재생중의 이펙트의 파라미터를 갱신할 수 없는 경우, 드라이버는 그 이펙트를 정지해, 파라미터를 갱신하고 나서 그 이펙트를 재개할 수가 있다. DIEP_NORESTART 플래그를 건네주면(자), 이 처리가 억제된다. 이펙트의 재생중에 드라이버가 이펙트의 파라미터를 갱신할 수 없을 때는, 에러 코드의 DIERR_EFFECTPLAYING 가 돌려주어져 파라미터는 갱신되지 않는다.

플래그 DIEP_NODOWNLOAD, DIEP_START, DIEP_NORESTART 의 쳐 동시에 2 개(살) 이상을 설정해선 안 된다(아무것도 건네주지 않아도 좋다).

이 3 개의 플래그는, 다음에 나타내도록(듯이), 다운로드 처리와 재생 처리를 제어한다.

DIEP_NODOWNLOAD 를 설정 하면, 이펙트 파라미터는 갱신되지만, 디바이스에 다운로드는 되지 않는다.

DIEP_START 플래그를 설정 하면, 이펙트 파라미터는 갱신되어 디바이스에 다운로드된다. 그리고,IDirectInputEffect::Start 메소드가 dwIterations 파라미터에 1 을 설정해, 플래그없이 불려 갔을 경우와 완전히 똑같이, 이펙트가 시동한다. DIEP_START 로 갱신 처리를 부가한 방법이 Start 메소드를 호출하는 방법보다 조금 고속으로 있다. 이것은 전자의 방법에서는, 디바이스에 송신하는 정보가 적어도 되기 때문에 있다.

DIEP_NODOWNLOAD 와 DIEP_START 의 어느쪽이나 설정되지 않고, 이펙트가 재생하고 있지 않을 때는, 파라미터는 갱신되어 디바이스에 다운로드된다.

DIEP_NODOWNLOAD 와 DIEP_START 의 어느쪽이나 설정되지 않고, 이펙트가 재생중 때는, 디바이스가 실행중 (온더 플라이) 갱신을 지원 하고 있으면, 파라미터는 갱신된다. 상기 이외의 경우, 처리는 DIEP_NORESTART 플래그 상태에 좌우된다. 이 플래그가 설정되어 있으면, 에러 코드 DIERR_EFFECTPLAYING 가 돌려주어진다. 이 플래그가 설정되어 있지 않으면, 이펙트는 정지해, 파라미터가 갱신되어 이펙트가 재개한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::Start

이펙트의 재생을 시작 한다. 이펙트가 이미 재생중이라면, 최초부터 시작 된다. 이펙트가 다운로드되어 있지 않은지, 또는 전회의 다운로드 이래, 변경되고 있는 경우는, 시작전에 이펙트가 다운로드된다. 이 처리는 디폴트로 행해진다. 이것을 억제하려면 , DIES_NODOWNLOAD 플래그를 건네주면 좋다.

HRESULT Start(
  DWORD dwIterations,
  DWORD dwFlags
);

파라미터

dwIterations
연속해 이펙트를 재생하는 회수. 포락선은, 보간 마다 재조정된다.

이펙트를 한 번만 재생하려면 , 1 을 건네준다. 명시적으로 정지 당할 때까지 반복 재생하려면 , INFINITE 를 건네준다. 포락선을 재조정하지 않고, 명시적으로 정지될 때까지 이펙트를 재생하려면 ,IDirectInputEffect::SetParameters 메소드를 사용해 이펙트 파라미터를 수정한 후, 그 dwDuration 멤버를 INFINITE 로 변경한다.

dwFlags
디바이스가 이펙트를 어떻게 재생하는지를 나타내는 플래그. 값은 제로 또는 다음의 플래그의 어느쪽이든을 지정한다.
DIES_SOLO
지정된 이펙트가 재생되기 전에, 디바이스 위에의 다른 모든 이펙트를 정지한다. 이 플래그를 생략 하면, 이펙트는, 디바이스상에서 이미 재생이 시작되어 있는 기존의 이펙트와 혼합되게 된다.
DIES_NODOWNLOAD
이펙트의 자동 다운로드를 실시하지 않는다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INCOMPLETEEFFECT
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.

여러 차례의 보간을 지원 하지 않는 디바이스도 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::Stop

이펙트의 재생을 정지한다.

HRESULT Stop(void);

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


IDirectInputEffect::Unload

디바이스로부터 이펙트를 삭제한다. 이펙트가 재생되고 있는 경우, 이펙트는, 언로드되기 전에 자동적으로 정지한다.

HRESULT Unload(void);

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


콜백 함수

다음의 7 개의 함수는, prototype의 콜백 함수이며, 다양한 열거 메소드와 함께 사용한다. 어플리케이션에서는 이러한 콜백 함수의 1 개를 선언할 수 있다. 그 때, 함수의 이름, 정의 방법은 임의로 좋지만, 파라미터의 타입과 반환값의 타입은, prototype내에서 같지 않으면 안 된다.

  • DIConfigureDevicesCallback
  • DIEnumCreatedEffectObjectsCallback
  • DIEnumDeviceObjectsCallback
  • DIEnumDevicesBySemanticsCallback
  • DIEnumDevicesCallback
  • DIEnumEffectsCallback
  • DIEnumEffectsInFileCallback


DIConfigureDevicesCallback

프로퍼티 시트 이미지가 갱신될 때마다 불려 가는, 어플리케이션 정의의 콜백 함수. 이 함수를 사용할 필요가 있는 것은, 어플리케이션이 독자적인 윈도우에 프로퍼티 시트를 표시하고 있는 경우뿐이다.

BOOL CALLBACK DIConfigureDevicesCallback(
  IUnknown FAR* lpDDSTarget,
  LPVOID pvRef
);

파라미터

lpDDSTarget
IDirectInput8::ConfigureDevices 에게 건네진 DICONFIGUREDEVICESPARAMS 구조체의 lpUnkDDSTarget 멤버중의 표면의 IUnknown 인터페이스에의 포인터.
pvRef
IDirectInput8::ConfigureDevices 에 pvRef 파라미터로서 건네받는 어플리케이션 정의의 값.

반환값

TRUE 또는 FALSE 를 돌려준다. DirectInput® 는 이 반환값을 사용하지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput8.lib 를 사용.


DIEnumCreatedEffectObjectsCallback

IDirectInputDevice8::EnumCreatedEffectObjects 메소드에 대한 호출 결과적으로 DirectInputDevice 이펙트를 받는, 어플리케이션 정의 콜백 함수.

BOOL CALLBACK DIEnumCreatedEffectObjectsCallback(
  LPDIRECTINPUTEFFECT peff,
  LPVOID pvRef
);

파라미터

peff
생성 된 이펙트 오브젝트에의 포인터.
pvRef
EnumCreatedEffectObjects 에 pvRef 파라미터로서 건네받는 어플리케이션 정의의 값.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.


DIEnumDeviceObjectsCallback

IDirectInputDevice8::EnumObjects 메소드에 대한 호출 결과적으로 DirectInputDevice 오브젝트를 받는, 어플리케이션 정의 콜백 함수.

BOOL CALLBACK DIEnumDeviceObjectsCallback(
  LPCDIDEVICEOBJECTINSTANCE lpddoi,
  LPVOID pvRef
);

파라미터

lpddoi
열거 대상의 오브젝트를 나타내는 DIDEVICEOBJECTINSTANCE 구조체.
pvRef
EnumObjects 에 pvRef 파라미터로서 건네받는 어플리케이션 정의의 값.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.


DIEnumDevicesBySemanticsCallback

IDirectInput8::EnumDevicesBySemantics 메소드에 대한 호출 결과적으로 DirectInput® 디바이스를 받는, 어플리케이션 정의 콜백 함수.

BOOL CALLBACK DIEnumDevicesBySemanticsCallback(
  LPCDIDEVICEINSTANCE lpddi,
  LPDIRECTINPUTDEVICE8  lpdid,
  DWORD  dwFlags,
  DWORD  dwRemaining,
  LPVOID pvRef
);

파라미터

lpddi
디바이스 인스턴스를 기술하는 DIDEVICEINSTANCE 구조체의 주소.
lpdid
디바이스의 IDirectInputDevice8 인터페이스에의 포인터.
dwFlags
디바이스의 열거 이유에 관한 정보를 제공하는 플래그. 액션 매핑 플래그의 편성이나, 1 개의 이용 플래그를 사용할 수 있다. 적어도 1 개의 액션 매핑 플래그가 항상 존재한다.

정의 끝난 액션 매핑 플래그는 다음대로.

DIEDBS_MAPPEDPRI1
우선 순위 1 의 액션은 디바이스에 맵 되기 (위해)때문에, 디바이스가 열거된다.
DIEDBS_MAPPEDPRI2
우선 순위 2 의 액션은 디바이스에 맵 되기 (위해)때문에, 디바이스가 열거된다.

정의 끝난 이용 플래그는 다음대로.

DIEDBS_RECENTDEVICE
액션 매핑 플래그로 지정된 커멘드가 최근 사용되었기 때문에, 디바이스를 열거하고 있다.
DIEDBS_NEWDEVICE
디바이스가 최근 인스톨 되었기 때문에, 디바이스를 열거하고 있다. 이 플래그로 지정된 디바이스는, 이 게임에서는 지금까지 사용되어 있지 않다.
dwRemaining
이 디바이스의 뒤에 남아 있는 열거 대상의 디바이스수.
pvRef
IDirectInput8::EnumDevicesBySemantics 에 pvRef 파라미터로서 건네받는 어플리케이션 정의의 값.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

주의

단일의 하드웨어 디바이스가, 복수의 DirectInput® 디바이스 타입으로서 기능할 수가 있는 경우는, 지원 하는 각 디바이스 타입 마다 열거된다. 예를 들어, 편입 마우스 부착의 키보드는, 2 회 열거된다. 1 회는 1 개의 키보드로서 1 회는 1 개의 마우스로서 열거된다. 다만, 제품 GUID 는 각 디바이스에 대해서 같다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.

참조

DIEnumDevicesCallback


DIEnumDevicesCallback

IDirectInput8::EnumDevices 메소드에 대한 호출 결과적으로 DirectInput® 디바이스를 받는, 어플리케이션 정의 콜백 함수.

BOOL CALLBACK DIEnumDevicesCallback(
  LPCDIDEVICEINSTANCE lpddi,
  LPVOID pvRef
);

파라미터

lpddi
디바이스 인스턴스를 기술하는 DIDEVICEINSTANCE 구조체의 주소.
pvRef
EnumDevices 또는 EnumDevicesBySemantics 에 pvRef 파라미터로서 건네받는 어플리케이션 정의의 값.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

주의

단일의 하드웨어 디바이스가, 복수의 DirectInput 디바이스 타입으로서 기능할 수가 있는 경우는, 지원 하는 각 디바이스 타입 마다 열거된다. 예를 들어, 편입 마우스 부착의 키보드는, 2 회 열거된다. 1 회는 1 개의 키보드로서 1 회는 1 개의 마우스로서 열거된다. 다만, 제품 GUID 는 각 디바이스에 대해서 같다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.

참조

DIEnumDevicesBySemanticsCallback


DIEnumEffectsCallback

IDirectInputDevice8::EnumEffects 메소드와 함께 사용하는 어플리케이션 정의 콜백 함수.

BOOL CALLBACK DIEnumEffectsCallback(
  LPCDIEFFECTINFO pdei,
  LPVOID pvRef
);

파라미터

pdei
열거된 이펙트를 기술하는 DIEFFECTINFO 구조체.
pvRef
EnumEffects 에 pvRef 파라미터로서 건네받는 어플리케이션 정의의 값.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.


DIEnumEffectsInFileCallback

IDirectInputDevice8::EnumEffectsInFile 메소드와 함께 사용하는 어플리케이션 정의 콜백 함수.

BOOL CALLBACK DIEnumEffectsInFileCallback(
  LPCDIFILEEFFECT lpDiFileEf,
  LPVOID pvRef
);

파라미터

lpDiFileEf
열거된 이펙트를 나타내는 DIFILEEFFECT 구조체.
pvRef
EnumEffectsInFile 에 pvRef 파라미터로서 건네받는 어플리케이션 정의의 값.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.


함수

여기에서는, COM 인터페이스 메소드 이외의 DirectInput® 함수 및 콜백 함수의 레퍼런스를 제공한다.

이 카테고리에는 다음의 함수가 분류된다.

  • DirectInput8Create


DirectInput8Create

DirectInput® 오브젝트를 생성 해,IDirectInput8 또는 그 이후의 인터페이스를 돌려준다.

HRESULT WINAPI DirectInput8Create(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFIID riidltf,
  LPVOID* ppvOut,
  LPUNKNOWN punkOuter
);

파라미터

hinst
DirectInput 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들. DirectInput 는, 이 값을 사용해, 어플리케이션 또는 DLL 가, 오브젝트 생성의 자격을 인정받고 있는지 어떤지를 판단해, 하위 호환성을 위해서(때문에) 취해야 할 특별한 동작을 확정한다.

DLL 가 부모의 어플리케이션의 핸들을 건네주면(자), 에러가 된다. 예를 들어, Web 페이지에 파묻히고 있어 DirectInput 를 사용하는 ActiveX® 컨트롤은, Web 브라우저의 핸들은 아니고, 그것 자신의 인스턴스의 핸들을 건네주지 않으면 안 된다. 이것에 의해, DirectInput 가 그 컨트롤을 인식해, 필요라고 생각되는 특별한 동작을 모두 유효하게 하는 것이 확실히 된다.

dwVersion
어플리케이션의 설계 대상인 DirectInput 의 버젼 번호. 이 값은 보통, DIRECTINPUT_VERSION 이다. Dinput.h 파일을 인클루드 하기 전에 어플리케이션이 DIRECTINPUT_VERSION 를 정의하는 경우, 그 값은 0x0700 이상이 아니면 안된다. 이전의 버젼에서는 DirectInputCreateEx 를 사용한다. 이것은 Dinput.lib 에 정의되고 있다.
riidltf
목적의 인터페이스의 일의인 식별자. DirectX 8.0 에서는, 이 값은 IID_IDirectInput8A 또는 IID_IDirectInput8W 이다. IID_IDirectInput8 정의를 건네주는 것으로, 컴파일시에 UNICODE 가 정의되고 있는 경우는 Unicode 버젼, 정의되어 있지 않은 경우는 ANSI 버젼의 인터페이스가 선택된다.
ppvOut
콜의 성공시에 인터페이스 포인터를 받는 변수에의 포인터의 주소.
punkOuter
COM 집성체에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소에의 포인터. 인터페이스가 집성되어 있지 않은 경우에는 NULL. 보통, 호출측은 NULL 를 건네준다. 집성이 요구되었을 경우,*ppvOut 에 돌려주어지는 오브젝트는, COM 집성체가 요구하도록(듯이),IUnknown 에의 포인터이다.

반환값

성공했을 경우는, DI_OK 를 돌려준다.

실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_BETADIRECTINPUTVERSION
DIERR_INVALIDPARAM
DIERR_OLDDIRECTINPUTVERSION
DIERR_OUTOFMEMORY

주의

이 함수가 생성 하는 DirectInput 오브젝트는, Dinput8d.dll 에 이행 된다. 이 이행에서는, DirectX 8.0 보다 전의 버젼의 인터페이스를 취득할 수 없다. 이전의 버젼을 사용하려면 ,DirectInputCreate 또는 DirectInputCreateEx 로 DirectInput 오브젝트를 생성 한다. 이것들은 Dinput.lib 에 있다.

punkOuter = NULL 를 지정해 이 함수를 호출하는 것은,CoCreateInstance(&CLSID_DirectInput8, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput8W, lplpDirectInput)를 사용해 오브젝트를 생성 한 후,IDirectInput8::Initialize 로 초기화하는 것으로 동등하다.

punkOuter ! = NULL 를 지정해 이 함수를 호출하는 것은,CoCreateInstance(&CLSID_DirectInput8, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInput)를 사용해 오브젝트를 생성 하는 것으로 동등하다. 집성 한 오브젝트는 수동으로 초기화해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput8.lib 를 사용.


매크로

여기에서는, Microsoft® DirectInput® 로 사용되고 있는 이하의 매크로를 설명한다.

  • DIDFT_GETINSTANCE
  • DIDFT_GETTYPE
  • DIDFT_MAKEINSTANCE
  • DIEFT_GETTYPE
  • DIMAKEUSAGEDWORD
  • DISEQUENCE_COMPARE
  • GET_DIDEVICE_SUBTYPE
  • GET_DIDEVICE_TYPE

Dinput.h 는,IDirectInput8 및 IDirectInputDevice8 양인터페이스의 모든 메소드에 대한 C 의 호출의 매크로도 정의한다. 이러한 매크로를 사용하는 것으로, 메소드 테이블에의 포인터가 불필요하게 된다. 예를 들어, 이하는,IDirectInputDevice8::Release 메소드에 대한 C 에 의한 호출의 예이다.

lpdid->lpVtbl->Release(lpdid));

동등의 매크로 호출은, 이하와 같은 형식이 된다.

IDirectInputDevice8_Release(lpdid);

이러한 매크로는 모두, 메소드 호출의 경우와 동일한 파라미터를 취한다.


DIDFT_GETINSTANCE

DIDFT_GETINSTANCE 매크로는, 데이터 형식 타입으로부터 오브젝트의 인스턴스 번호 코드를 추출한다.

DIDFT_GETINSTANCE(n) LOWORD((n) >> 8)

파라미터

n
Microsoft® DirectInput® 데이터 형식 타입. 이 파라미터로 설정 가능한 값은,DIOBJECTDATAFORMAT 구조체의 dwType 멤버의 값과 같다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

DIDFT_MAKEINSTANCE ,DIDFT_GETTYPE


DIDFT_GETTYPE

DIDFT_GETTYPE 매크로는, 데이터 형식 타입으로부터 오브젝트 타입 코드를 추출한다.

DIDFT_GETTYPE(n)  LOBYTE(n)

파라미터

n
Microsoft® DirectInput® 데이터 형식 타입. 이 파라미터로 설정 가능한 값은,DIOBJECTDATAFORMAT 구조체의 dwType 멤버의 값과 같다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

DIDFT_GETINSTANCE


DIDFT_MAKEINSTANCE

DIDFT_MAKEINSTANCE 매크로는, 디바이스 오브젝트의 인스턴스 식별자를 생성 해,DIOBJECTDATAFORMAT 구조체의 dwType 멤버안에 포함한다.

DIDFT_MAKEINSTANCE(n) ((WORD)(n) << 8)

파라미터

n
오브젝트의 인스턴스. 예를 들어, 마우스의 버튼 1 의 경우는 1.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

DIDFT_GETINSTANCE


DIEFT_GETTYPE

DIDFT_GETTYPE 매크로는, 데이터 형식 타입으로부터 오브젝트 타입 코드를 추출한다.

DIEFT_GETTYPE(n)  LOBYTE(n)

파라미터

n
Microsoft® DirectInput® effect format type. 이 파라미터가 취할 수가 있는 값은,DIEFFECTINFO 구조체의 dwEffType 멤버의 값과 같다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIMAKEUSAGEDWORD

DIMAKEUSAGEDWORD 매크로는, 휴먼 인터페이스 디바이스를 나타내는 디바이스 오브젝트의 "사용 페이지" 와 "사용 상황" 을 조합해,IDirectInputDevice8::GetObjectInfo 메소드에 건네준다.

DWORD DIMAKEUSAGEDWORD(
  WORD UsagePage,
  WORD Usage
);

파라미터

UsagePage
디바이스 오브젝트의 사용 페이지.
Usage
디바이스 오브젝트의 사용 상황.

주의

이 매크로는, Dinput.h 내에서 다음과 같이 선언된다.

#define DIMAKEUSAGEDWORD(UsagePage, Usage) \
        ((DWORD) MAKELONG(Usage, UsagePage))

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DISEQUENCE_COMPARE

DISEQUENCE_COMPARE 매크로는, 2 개의 Microsoft® DirectInput® 순서 번호를 비교해, 순서 번호의 순환을 보정한다.

DISEQUENCE_COMPARE(dwSequence1, cmp, dwSequence2) \
                ((int)((dwSequence1) - (dwSequence2)) cmp 0)

파라미터

dwSequence1
비교하는 제 1 순서 번호.
cmp
비교 연산자 (==,! =, <, >, <=, >=)의 어느쪽이든 1 개(살).
dwSequence2
비교하는 제 2 순서 번호.

반환값

cmp 파라미터로 지정되고 비교 결과가 진정한 경우는 제로 이외를 돌려주어, 가짜의 경우는 제로를 돌려준다.

주의

이하의 예는,dwSequence1 파라미터값이, 시간적으로 dwSequence2 파라미터값에 선행할지 어떨지를 체크한다.

BOOL Sooner = (DISEQUENCE_COMPARE(dwSequence1, <, dwSequence2));

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


GET_DIDEVICE_SUBTYPE

GET_DIDEVICE_SUBTYPE 매크로는, 디바이스 타입 기술 코드로부터 디바이스 서브 타입 코드를 추출한다.

GET_DIDEVICE_SUBTYPE(dwDevType)  HIBYTE(dwDevType)

파라미터

dwDevType
Microsoft® DirectInput® 디바이스 타입 기술 코드. 이 파라미터가 취할 수가 있는 값은,DIDEVICEINSTANCE 구조체의 dwDevType 멤버의 값과 같다.

주의

서브 타입 코드의 해석은, 프라이머리 타입에 의해 바뀐다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

GET_DIDEVICE_TYPE ,DIDEVICEINSTANCE


GET_DIDEVICE_TYPE

GET_DIDEVICE_TYPE 매크로는, 디바이스 타입 기술 코드로부터 디바이스의 프라이머리 타입 코드를 추출한다.

GET_DIDEVICE_TYPE(dwDevType)  LOBYTE(dwDevType)

파라미터

dwDevType
Microsoft® DirectInput® 디바이스 타입 기술 코드. 이 파라미터가 취할 수가 있는 값은,DIDEVICEINSTANCE 구조체의 dwDevType 멤버의 값과 같다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

GET_DIDEVICE_SUBTYPE ,DIDEVICEINSTANCE


구조체

여기에서는, 이하의 Microsoft® DirectInput® 구조체를 설명한다.

  • DIACTION
  • DIACTIONFORMAT
  • DICOLORSET
  • DICONDITION
  • DICONFIGUREDEVICESPARAMS
  • DICONSTANTFORCE
  • DICUSTOMFORCE
  • DIDATAFORMAT
  • DIDEVCAPS
  • DIDEVICEIMAGEINFO
  • DIDEVICEIMAGEINFOHEADER
  • DIDEVICEINSTANCE
  • DIDEVICEOBJECTDATA
  • DIDEVICEOBJECTINSTANCE
  • DIEFFECT
  • DIEFFECTINFO
  • DIEFFESCAPE
  • DIENVELOPE
  • DIFILEEFFECT
  • DIJOYSTATE
  • DIJOYSTATE2
  • DIMOUSESTATE
  • DIMOUSESTATE2
  • DIOBJECTDATAFORMAT
  • DIPERIODIC
  • DIPROPCPOINTS
  • DIPROPDWORD
  • DIPROPGUIDANDPATH
  • DIPROPHEADER
  • DIPROPPOINTER
  • DIPROPRANGE
  • DIPROPSTRING
  • DIRAMPFORCE

주 : 사용전에 모든 DirectX 구조체의 메모리는, 제로에 초기화되지 않으면 안 된다. 또,dwSize 멤버를 포함한 모든 구조체는, 사용전에 dwSize 멤버를 그 구조체의 사이즈로 설정할 필요가 있다. 다음의 예는,DIDEVCAPS 구조체의 동작을 설명하고 있다.

DIDEVCAPS didevcaps; // 이것은 아직 사용할 수 없다.

ZeroMemory(&didevcaps, sizeof(didevcaps));
didevcaps.dwSize = sizeof(didevcaps);

// 이것으로 구조체를 사용할 수 있다.


CPOINT

calibration 포인트에 대해 설명한다. DIPROPCPOINTS 구조체에는,CPOINT 구조체의 배열이 포함된다.

typedef struct _CPOINT
{
    LONG  lP;
    DWORD dwLog;
} CPOINT, *PCPOINT;

멤버

lP
미가공 데이터.
dwLog
lP 번호에 관련지을 수 있고 있는 스케일링값. 최대치에 10000 을 곱한 퍼센티지.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

CPOINT 의 사용법


DIACTION

게임 액션과 디바이스 기능의 1 대 1 의 매핑을 나타낸다. DIACTIONFORMAT 구조체에는,DIACTION 구조체의 배열이 포함된다.

typedef struct _DIACTION {
    UINT_PTR    uAppData;
    DWORD       dwSemantic;
    DWORD       dwFlags;
    union {
        LPCSTR  lptszActionName;
        UINT    uResIdString;
    };
    GUID        guidInstance;
    DWORD       dwObjID;
    DWORD       dwHow;
} DIACTION, *LPDIACTION;

typedef const DIACTION *LPCDIACTION;

멤버

uAppData
액션에 관련지을 수 있었던 컨트롤 상태가 변화할 경우에,IDirectInputDevice8::GetDeviceData 가 어플리케이션에 돌려주는, 어플리케이션 정의의 UINT 값의 주소. 이 값은 DIDEVICEOBJECTDATA 구조체의 uAppData 멤버에 돌려주어진다. 보통, 이 값은 디바이스 오브젝트에 관련지을 수 있었던 어플리케이션 고유의 액션의 식별자이지만, 함수 포인터도 사용할 수 있다.
dwSemantic
죠이스틱의 경우, 이 어플리케이션 장르에 정의된 가상 컨트롤을 나타내는 액션 매핑 정수, 또는 그 장르에 정의되어 있지 않은 컨트롤의 정수. 키보드, 마우스, 또는 Microsoft® DirectPlay® 음성 디바이스의 경우, 특정의 디바이스 오브젝트를 나타내는 정수. 「액션 매핑 정수」를 참조할것.
dwFlags
특정의 속성 또는 처리를 요구하기 위해서 사용되는 플래그. 제로, 또는 다음의 플래그를 지정한다.
DIA_APPFIXED
Microsoft DirectInput® 로 액션의 매핑을 변경할 수 없다.
DIA_APPMAPPED
dwObjID 멤버가 유효하고,IDirectInputDevice8::BuildActionMap 는 어플리케이션 정의의 매핑을 덧쓰기하지 않는다.
DIA_APPNOMAP
이 액션을 맵 하지 않는다.
DIA_FORCEFEEDBACK
액션을 액츄에이터 또는 방아쇠에 맵 한다.
DIA_NORANGE
이 액션에는 디폴트의 범위를 설정하지 않는다. 이 플래그는 절대축액션에게만 설정할 수 있다.
lptszActionName
어플리케이션 정의의 액션명. 이 캐릭터 라인은,IDirectInput8::ConfigureDevices 의 호출시에 디바이스의 프로퍼티 시트에 표시된다.
uResIdString
이 액션으로 사용되는 캐릭터 라인의 리소스 식별자. 이 리소스의 모듈 인스턴스는, 이 구조체를 포함한 DIACTIONFORMAT 구조체의 hInstString 멤버내로 지정된다.
guidInstance
특정의 디바이스가 요구되고 있는 경우, 디바이스의 인스턴스 GUID. 그 이외의 경우는 GUID_NULL.
dwObjID
컨트롤 식별자. DIDFT_GETINSTANCE 및 DIDFT_GETTYPE 매크로를 사용해, 이 값으로부터 인스턴스와 타입을 취득한다.
dwHow
액션을 구성하기 위해서 DirectInput 로 사용된 매핑의 구조를 나타내는 값. IDirectInputDevice8::BuildActionMap 가 이 구조체를 돌려줄 때, 이 멤버가 설정된다. 다음의 값이 정의되고 있다.
DIAH_APPREQUESTED
어플리케이션이 매핑을 구성해,BuildActionMap 의 호출시에 디바이스 (guidInstance) 및 디바이스 오브젝트 (dwObjID)가 지정되었다.
DIAH_DEFAULT
다른 매핑 정보가 없기 때문에, DirectInput 가 매핑을 결정했다.
DIAH_ERROR
에러가 발생했다. 액션이 디바이스의 컨트롤과 일치하지 않는다. 액션 맵의 설정시에, 이 액션은 무시된다.
DIAH_HWAPP
이 게임의 하드웨어 메이커가 매핑을 지정했다.
DIAH_HWDEFAULT
이 장르의 하드웨어 메이커가 매핑을 지정했다.
DIAH_UNMAPPED
적절한 디바이스 오브젝트가 발견되지 않았다.
DIAH_USERCONFIG
유저가 매핑을 구성했다.

액션 맵이 IDirectInputDevice8::SetActionMap 에게 건네지는 경우, 이 멤버는 무시된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInput8::EnumDevicesBySemantics ,IDirectInputDevice8::SetActionMap ,IDirectInput8::ConfigureDevices ,IDirectInputDevice8::BuildActionMap ,액션 매핑


DIACTIONFORMAT

호출원어플리케이션에 관한 정보를 저장 해, 장르의 액션과 컨트롤의 매핑을 정의하는 DIACTION 구조체 배열의 컨테이너로서 동작한다.

typedef struct {
    DWORD              dwSize;
    DWORD              dwActionSize;
    DWORD              dwDataSize;
    DWORD              dwNumActions;
    LPDIACTION         rgoAction;
    GUID               guidActionMap;
    DWORD              dwGenre;
    DWORD              dwBufferSize;
    OPTIONAL LONG      lAxisMin;
    OPTIONAL LONG      lAxisMax;
    OPTIONAL HINSTANCE hInstString;
    FILETIME           ftTimeStamp;
    DWORD              dwCRC;
    TCHAR              tszActionMap[MAX_PATH];
} DIACTIONFORMAT;

멤버

dwSize
DIACTIONFORMAT 구조체의 사이즈를 바이트 단위로 지정하는 DWORD 값.
dwActionSize
DIACTION 구조체의 사이즈를 바이트 단위로 지정하는 DWORD 값.
dwDataSize
디바이스의 직접 데이터를 사용하는 디바이스가 돌려주는, 디바이스 데이터의 사이즈를, 바이트 단위로 지정하는 DWORD 값. 이 멤버는,dwNumActions 를 4 배가 된 값이다.
dwNumActions
rgoAction 배열의 요소수를 지정하는 DWORD 값.
rgoAction
DIACTION 구조체의 배열의 주소. 각 구조체가, 액션과 가상 컨트롤 또는 디바이스 오브젝트의 맵 방법, 및 매핑 정보의 유저에 대한 표시 방법을 나타낸다.
guidActionMap
액션 맵을 식별하는 GUID. 디바이스 메이커는 이 값을 사용해 특정의 타이틀의 매핑을 조정할 수 있다.
dwGenre
어플리케이션의 장르를 지정하는 DWORD 값. 사용할 수 있는 값에 대해서는, 「액션 매핑 정수」를 참조할것.
dwBufferSize
액션 맵이 적용되는 각 디바이스의, 버퍼내의 입력 데이터 패킷수를 지정하는 DWORD 값. IDirectInputDevice8::GetDeviceData 로 데이터를 취득하기 위해서, 버퍼 사이즈를 제로보다 큰 값으로 설정할 필요가 있다. IDirectInputDevice8::SetActionMap 를 호출하기 전에, 어플리케이션이 이 멤버에 목적의 버퍼 사이즈를 설정하는 경우,IDirectInputDevice8::SetProperty 로 DIPROP_BUFFERSIZE 프로퍼티를 설정할 필요는 없다.
lAxisMin
모든 축으로 취득되는 계측 데이터의 범위의 최소 값. DIACTION.dwFlags 에 DIA_NORANGE 플래그가 설정되었을 경우, 이 값은 특정의 액션 축으로 대해 무시된다.

이 값은, 축액션 에 대해서만 유효하고, 그 외의 모든 조작에 대해서는 0 으로 설정할 필요가 있다. IDirectInputDevice8::SetActionMap 로 액션 맵을 적용할 경우에, 절대 축으로 범위 프로퍼티를 설정하기 위해서 DIPROPRANGE.lMin 값으로서 사용된다.

lAxisMax
모든 축으로 취득되는 계측 데이터의 범위의 최대치. DIACTION.dwFlags 에 DIA_NORANGE 플래그가 설정되었을 경우, 이 값은 특정의 액션 축으로 대해 무시된다.

이 값은, 축액션 에 대해서만 유효하고, 그 외의 모든 조작에 대해서는 0 으로 설정할 필요가 있다. IDirectInputDevice8::SetActionMap 로 액션 맵을 적용할 경우에, 절대 축으로 범위 프로퍼티를 설정하기 위해서 DIPROPRANGE.lMax 값으로서 사용된다.

hInstString
각 액션의 DIACTION 구조체의 uResIdString 멤버로 지정된, 액션명의 캐릭터 라인 리소스를 저장 하는 모듈의 핸들. 액션명이 각 액션의 DIACTION 구조체의 lptszActionName 멤버로 지정되고 있는 경우는 제로로 좋다.
ftTimeStamp
액션 맵이 마지막에 디스크에 기입해졌을 때 각을 받는 FILETIME 구조체. 「주의」를 참조할것.
dwCRC
이 맵의 순회 장황 검사 (CRC). 매핑 세트를 디스크에 보존하는 시기를 결정하기 위해서(때문에), Microsoft® DirectInput® 가 내부적으로 사용한다.
tszActionMap
이 액션 맵의 등록명을 지정하는, 최대장 MAX_PATH 의 NULL 종단 캐릭터 라인. 이 캐릭터 라인은, 디폴트 프로퍼티 시트의 드롭 다운 리스트 박스에 표시된다.

주의

ftTimeStamp 멤버에는, 신규 디바이스나 미사용 디바이스에 적용하는 특수값을 저장 할 수 있다. 신규 디바이스란, 이 어플리케이션에서는 열거되지 않고, 액션 맵이 적용되지 않은 디바이스이다. 미사용 디바이스란, 이전에 이 어플리케이션으로 열거되고 있지만, 액션 맵이 적용되지 않은 디바이스이다. 신규 디바이스의 경우,FILETIME 구조체의, 아래의 DWORD 와 위에의 DWORD 에, 각각 DIAFTS_NEWDEVICELOW 와 DIAFTS_NEWDEVICEHIGH 이 항상 설정되어 있어 미사용 디바이스의 경우는, 여기에 DIAFTS_UNUSEDDEVICELOW 와 DIAFTS_UNUSEDDEVICEHIGH 가 설정되어 있다.

어플리케이션은 신규 디바이스의 유무를 체크하기 위해서 ftTimeStamp 를 사용해서는 안된다. 이 방법 대신에, 열거 콜백 함수로 DIEDBS_RECENTDEVICE 와 DIEDBS_NEWDEVICE 플래그가 돌려주어졌는지 어떠했는지를 볼 필요가 있다. 상세한 것에 대하여는, 「DIEnumDevicesBySemanticsCallback 」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInput8::EnumDevicesBySemantics ,IDirectInputDevice8::SetActionMap ,IDirectInput8::ConfigureDevices ,IDirectInputDevice8::BuildActionMap ,액션 매핑


DICOLORSET

디바이스 구성 유저 인터페이스를 드로잉(Drawing) 하는 배색을 나타낸다. 이것은 DICONFIGUREDEVICESPARAMS 구조체의 일부이다.

typedef struct _DICOLORSET {
    DWORD    dwSize
    D3DCOLOR cTextFore;
    D3DCOLOR cTextHighlight;
    D3DCOLOR cCalloutLine;
    D3DCOLOR cCalloutHighlight;
    D3DCOLOR cBorder;
    D3DCOLOR cControlFill;
    D3DCOLOR cHighlightFill;
    D3DCOLOR cAreaFill;
} DICOLORSET, *LPDICOLORSET;

typedef const DICOLORSET *LPCDICOLORSET;

멤버

dwSize
이 구조체의 바이트 단위의 사이즈.
cTextFore
텍스트의 전경색.
cTextHighlight
강조 텍스트의 전경색.
cCalloutLine
콜 아웃선의 표시에 사용되는 색.
cCalloutHighlight
콜 아웃선의 표시에 사용되는 색.
cBorder
화선의 색. 탭이나 버튼등의 컨트롤을 둘러싸는 선을 표시하기 위해서 사용된다.
cControlFill
탭이나 버튼등의 컨트롤의 칠해의 색.
cHighlightFill
강조 텍스트의 칠해의 색.
cAreaFill
탭이나 버튼등의 컨트롤의 외측의 칠해의 색.

주의

텍스트의 배경색은 항상 투명하다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

D3DCOLOR


DICONDITION

DIEFT_CONDITION 로서 마크 되고 있는 이펙트의 타입 고유의 정보를 저장 한다.

이펙트에 관한 DICONDITION 구조체의 배열에의 포인터는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버에게 건네진다. 배열의 요소수는, 이펙트에 관련지을 수 있었던 축의 수에 동일하지 않으면 안 된다.

typedef struct DICONDITION {
    LONG  lOffset;
    LONG  lPositiveCoefficient;
    LONG  lNegativeCoefficient;
    DWORD dwPositiveSaturation;
    DWORD dwNegativeSaturation;
    LONG  lDeadBand;
} DICONDITION, *LPDICONDITION;

typedef const DICONDITION *LPCDICONDITION;

멤버

lOffset
-10, 000 ~ 10.000 의 범위에 있는, 조건의 오프셋(offset).
lPositiveCoefficient
-10, 000 ~ 10.000 의 범위에 있는, 오프셋(offset)의 정측의 계수 정수.
lNegativeCoefficient
-10, 000 ~ 10.000 의 범위에 있는, 오프셋(offset)의 부측의 계수 정수.

디바이스가 정과 부로 나누어진 계수를 지원 하고 있지 않는 경우,lNegativeCoefficient 값은 무시되어lPositiveCoefficient 값이 정부 양쪽 모두의 계수로서 사용된다.

dwPositiveSaturation
0 ~ 10,000 의 범위에 있는, 오프셋(offset)의 정측의 최대 포스 출력.

디바이스가 포스의포화를 지원 하지 않는 경우, 이 멤버값은 무시된다.

dwNegativeSaturation
0 ~ 10,000 의 범위에 있는, 오프셋(offset)의 부측의 최대 포스 출력.

디바이스가 포스의 포화값을 지원 하지 않는 경우, 이 멤버값은 무시된다.

디바이스가 정과 부로 나누어진 포화값을 지원 하고 있지 않는 경우,dwNegativeSaturation 값은 무시되어dwPositiveSaturation 값이 정부 양쪽 모두의 포화값으로서 사용된다.

lDeadBand
0 ~ 10,000 의 범위에 있는, 조건이 액티브하지 않은 lOffset 주변의 영역. 즉,lOffset - lDeadBand 와 lOffset + lDeadBand 의 사이에서는, 조건은 액티브하지 않다.

주의

조건의 타입이 다르면, 파라미터의 의미도 다르지만, 기본적인 생각은, 조건에 기인하는 포스는,A(q - q0) 에 동일해진다고 하는 것이다. 여기서,A 는, 스케일링 계수,q 는 있는 거리이며,q0 는, 그 거리에 대한 중립값이다.

위의 단순한 식은, 데드 밴드에 제로 이외의 값이 지정되었을 경우는 조정해야 한다. 거리가 lOffset - lDeadBand 보다 작으면, 생성되는 포스는, 다음의 식에서 나타난다.

force = lNegativeCoefficient * (q - (lOffset - lDeadBand))

같이 거리가 lOffset + lDeadBand 보다 크면, 생성되는 포스는, 다음의 식에서 나타난다.

force = lPositiveCoefficient * (q - (lOffset + lDeadBand))

스프링 조건은, 축의 위치를 거리로서 사용한다.

댐퍼 조건은, 축의 속도를 거리로서 사용한다.

관성 조건은, 축의 가속도를 거리로서 사용한다.

배열에 포함되는 DICONDITION 구조체의 수가, 이펙트에 대한 축의 수로 동일한 경우, 제 1 의 구조체는 제 1 의 축으로 적용되어 제 2 의 구조체는 제 2 의 축으로 적용된다. 그 이후도 같은 대응 관계를 유지한다. 예를 들어, 2 축의 스프링 조건으로, 양쪽 모두의 DICONDITION 구조체로 lOffset 가 제로로 설정되어 있으면, 죠이스틱의 자동 센터링 스프링과 같은 이펙트를 얻을 수 있다. 이와 같이, 1 개의 조건이 각각의 축으로 대해 정의되고 있는 경우, 이펙트는 회전하지 않는다.

2 개(살) 이상의 축을 가지는 이펙트에 대해서 DICONDITION 구조체가 1 개의 경우,DICONDITION 구조체의 파라미터가 유효가 될 방향은,DIEFFECT 구조체의 rglDirection 필드에게 건네질 방향 파라미터에 의해 결정된다. 예를 들어, 45 번 (극좌표에서) 회전하는 마찰 조건은, 북동에서 남서에의 방향의 죠이스틱의 움직임에는 저항하겠지만, 북서에서 남동에의 방향의 죠이스틱의 움직임에는 아무런 작용을 미치지 않을 것이다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DICONFIGUREDEVICESPARAMS

디바이스 구성 프로퍼티 시트에 관한 정보를 저장 한다. IDirectInput8::ConfigureDevices 메소드로 사용된다.

typedef struct _DICONFIGUREDEVICESPARAMS {
    DWORD            dwSize;
    DWORD            dwcUsers;
    LPSTR            lptszUserNames;
    DWORD            dwcFormats;
    LPDIACTIONFORMAT lprgFormats;
    HWND             hwnd;
    DICOLORSET       dics;
    IUnknown FAR *   lpUnkDDSTarget;
} DICONFIGUREDEVICESPARAMS, *LPDICONFIGUREDEVICESPARAMS;

멤버

dwSize
이 구조체의 바이트 단위의 사이즈.
dwcUsers
lptszUserNames 가 가리키는 버퍼에 포함되는 유저명의 수. lptszUserNames 가 NULL 인 경우 (디폴트 유저명이 사용되는 것을 나타낸다), 이 멤버의 값은 무시된다. dwcUsers 의 값이, 실제로 버퍼내에 있는 엔트리의 수보다 큰 경우, 메소드는 실패해,DIERR_INVALIDPARAM 를 돌려준다.
lptszUserNames
일련의 NULL 종단 이름 캐릭터 라인을 저장 하는 버퍼에의 포인터. 이중 NULL 터미네이터에 의해 지정되는 마지막 요소이다. lptszUserNames 파라미터를 NULL 로 설정해, 디폴트명의 사용을 지정할 수가 있다. 어플리케이션이 지정수이상의 이름을 건네주는 경우, 지정수내의 이름만이 사용된다. 어플리케이션이 현재 디바이스에 할당할 수 있었던 이름과는 다른 이름을 지정하는 경우, 모든 디바이스로 소유권이 삭제되어 일치하지 않는 이름용으로 디폴트명이 생성 되어 모든 디바이스로 인터페이스에 "(No User)" 가 표시된다.
dwcFormats
lprgFormats 가 가리키는 배열내의 구조체의 수.
lprgFormats
게임에서 사용되는 각 장르의 액션 매핑 정보를 저장 하는 DIACTIONFORMAT 구조체의 배열에의 포인터. 입력시, 이 배열에는 액션과 컨트롤의 매핑, 및 각 매핑의 콜 아웃으로서 표시하는 캐릭터 라인이 저장 된다. 구성 인터페이스에서는, 드롭 다운 리스트에 배열내와 같은 순서로 장르가 표시된다.
hwnd
호출원어플리케이션의 최상정도 윈도우에의 핸들. 이 멤버가 필요한 것은, 어플리케이션이 윈도우 표시 모드로 가동하고 있는 경우뿐이어, 그 이외는 무시된다.
dics
구성 유저 인터페이스에 적용하는 배색을 나타내는 DICOLORSET 구조체. 제로로 초기화된 DICOLORSET 구조체를 건네주면(자), 디폴트의 배색이 사용된다.
lpUnkDDSTarget
구성 유저 인터페이스의 이미지가 저장 되는 Microsoft® DirectDraw® 또는 Microsoft Direct3D® 타겟 표면 오브젝트의 IUnknown 인터페이스에의 포인터. 이 이미지는,DIEnumDevicesBySemanticsCallback 함수가 불려 간 시점에 있어서의 유저 인터페이스의 현재 상태를 나타낸다. 타겟 표면은, 전의 DICOLORSET 구조체의 일부로서 건네받은 알파 정보와 하드웨어 메이커에 의해 디바이스 이미지에 encode 된 알파 정보를 보관 유지한다. IUnknown 인터페이스가 참조하는 타겟 표면 오브젝트는,IDirect3DSurface8 또는 IDirectDrawSurface7 를 지원 할 필요가 있다. DirectDraw 를 사용하는 풀 스크린 어플리케이션은, DDSCAPS_SYSTEMEMORY 플래그를 사용해 생성 된 타겟 표면을 가질 필요가 있다.

DirectDraw 를 사용하지 않는 어플리케이션과 DirectDraw 를 사용하지만, 전화면을 사용하는 것이 아니라 윈도우화해 실행되는 어플리케이션은, 이 파라미터에 NULL 를 건네줄 수가 있다. 그 경우, Microsoft DirectInput® 는 Windows GDI (Graphics Device Interface) 함수를 사용해 구성 유저 인터페이스 이미지를 드로잉(Drawing) 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DICONSTANTFORCE

DIEFT_CONSTANTFORCE 로서 마크 되고 있는 이펙트의 타입 고유의 정보를 저장 한다.

이 구조체는, 정수 포스 이펙트를 나타낸다.

이펙트에 관한 단일의 DICONSTANTFORCE 구조체에의 포인터는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버에게 건네진다.

typedef struct DICONSTANTFORCE {
    LONG lMagnitude;
} DICONSTANTFORCE, *LPDICONSTANTFORCE;

typedef const DICONSTANTFORCE *LPCDICONSTANTFORCE;

멤버

lMagnitude
-10. 000 ~ 10,000 의 범위에 있는, 이펙트의 매그니튜드. 포락선이 이 이펙트에 적용되고 있으면, 이 값은,유지 기간의 매그니튜드를 나타낸다. 포락선의 적용이 없으면, 이 값은, 이펙트 전체의 진폭을 나타낸다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DICUSTOMFORCE

DIEFT_CUSTOMFORCE 로서 마크 되고 있는 이펙트의 타입 고유의 정보를 저장 한다.

이 구조체는, 커스텀 또는 유저 정의 포스를 나타낸다.

이펙트의 DICUSTOMFORCE 구조체에의 포인터는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버에게 건네진다.

typedef struct DICUSTOMFORCE {
    DWORD  cChannels;
    DWORD  dwSamplePeriod;
    DWORD  cSamples;
    LPLONG rglForceData;
} DICUSTOMFORCE, *LPDICUSTOMFORCE;

typedef const DICUSTOMFORCE *LPCDICUSTOMFORCE;

멤버

cChannels
이 포스에 의해 영향을 받는 채널 (축)의 수.

1 번째의 채널이, 이펙트에 관련지을 수 있었던 1 번째의 축으로 적용되어 2 번째의 채널이 2 번째의 축으로 적용된다고 하는 것처럼 계속된다. 축보다 채널의 수가 적으면, 여분의 축으로 대하는 관련짓고 하행 깨지지 않는다.

채널이 1 개 밖에 존재하지 않으면, 이펙트는,DIEFFECT 구조체의 rglDirection 멤버가 지정할 방향으로 회전한다. 복수의 채널이 있으면(자), 회전할 수 없다.

커스텀 이펙트의 회전을 지원 하고 있지 않는 디바이스도 있다.

dwSamplePeriod
마이크로 세컨드 단위의 샘플링 간격.
cSamples
rglForceData 내의 샘플의 합계수. cChannels 의 정수배가 아니면 안된다.
rglForceData
커스텀 포스를 나타내는 포스값의 배열에의 포인터. 복수의 채널이 지정되고 있으면, 값은, 차례로 할당할 수 있다. 예를 들어,cChannels 가 3 의 경우에는, 배열의 1 번째의 요소는 1 번째의 채널에, 2 번째의 요소는 2 번째의 채널에, 3 번째의 요소는 3 번째의 채널에 각각 속한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIDATAFORMAT

디바이스의 데이터 형식을 나타낸다. 이 구조체는,IDirectInputDevice8::SetDataFormat 메소드로 사용한다.

typedef struct DIDATAFORMAT {
    DWORD dwSize;
    DWORD dwObjSize;
    DWORD dwFlags;
    DWORD dwDataSize;
    DWORD dwNumObjs;
    LPDIOBJECTDATAFORMAT rgodf;
} DIDATAFORMAT, *LPDIDATAFORMAT;

typedef const DIDATAFORMAT *LPCDIDATAFORMAT;

멤버

dwSize
이 구조체의 바이트 단위의 사이즈.
dwObjSize
DIOBJECTDATAFORMAT 구조체의 바이트 단위의 사이즈.
dwFlags
데이터 형식외의 속성을 나타내는 플래그. 이 값은, 다음의 어느쪽이든 1 개(살)이다.
DIDF_ABSAXIS
축은 절대 모드에 있다. 데이터 형식에 이 플래그를 설정하는 것은,IDirectInputDevice8::SetProperty 메소드를 사용해 축모드 프로퍼티를 수동으로 설정하는 것에 동일하다. 이 값은, DIDF_RELAXIS 플래그와 조합할 수 없다.
DIDF_RELAXIS
축은 상대 모드에 있다. 데이터 형식에 이 플래그를 설정하는 것은,IDirectInputDevice8::SetProperty 메소드를 사용해 축모드 프로퍼티를 수동으로 설정하는 것에 동일하다. 이 값은, DIDF_ABSAXIS 플래그와 조합할 수 없다.
dwDataSize
디바이스가 돌려주는 데이터 패킷의 바이트 단위의 사이즈. 이 값은, 4 의 배수, 한편 데이터 패킷내의 오브젝트 데이터의 최대 오프셋(offset)값보다 크지 않으면 안 된다.
dwNumObjs
rgodf 배열중의 오브젝트수.
rgodf
DIOBJECTDATAFORMAT 구조체의 배열의 주소. 각 구조체는, 1 개의 오브젝트 데이터가 디바이스 데이터 중(안)에서 어떻게 보고되는지를 기술한다. 전형적인 에러로서는, 2 종류의 정보를 같은 위치에 저장 하거나 1 종류의 정보를 복수의 위치에 저장 하거나 하는 것이 있다.

주의

어플리케이션은, 보통,DIDATAFORMAT 구조체를 생성 할 필요는 없다. 어플리케이션은, 사전 정의된 글로벌 데이터 형식 변수의 c_dfDIMouse,c_dfDIMouse2,c_dfDIKeyboard,c_dfDIJoystick, c_dfDIJoystick2 의 어느쪽이든을 사용할 수 있기 때문이다.

이하의 예에서는, 2 개의 축 (절대 좌표로 보고된다)과 2 개의 버튼을 필요로 하는 어플리케이션을 사용할 수 있는 데이터 형식을 설정해 있다.

// 어플리케이션이 다음의 구조체를 사용해,
// 디바이스 데이터를 읽어내면(자) 가정한다.

typedef struct MYDATA {
    LONG  lX;                   // x 축이 여기에 온다.
    LONG  lY;                   // y 축이 여기에 온다.
    BYTE  bButtonA;             // 1 개의 버튼이 여기에 온다.
    BYTE  bButtonB;             // 별의 버튼이 여기에 온다.
    BYTE  bPadding[2];          // 사이즈는, DWORD 의 배수가 아니면 안된다.
} MYDATA;

// 다음의 데이터 형식을 사용할 수 있다.

DIOBJECTDATAFORMAT rgodf[ ] = {
  { &GUID_XAxis, FIELD_OFFSET(MYDATA, lX),
    DIDFT_AXIS | DIDFT_ANYINSTANCE, 0, },
  { &GUID_YAxis, FIELD_OFFSET(MYDATA, lY),
    DIDFT_AXIS | DIDFT_ANYINSTANCE, 0, },
  { &GUID_Button, FIELD_OFFSET(MYDATA, bButtonA),
    DIDFT_BUTTON | DIDFT_ANYINSTANCE, 0, },
  { &GUID_Button, FIELD_OFFSET(MYDATA, bButtonB),
    DIDFT_BUTTON | DIDFT_ANYINSTANCE, 0, },
};
#define numObjects (sizeof(rgodf) / sizeof(rgodf[0]))

DIDATAFORMAT df = {
    sizeof(DIDATAFORMAT),       // 이 구조체의 사이즈
    sizeof(DIOBJECTDATAFORMAT), // 오브젝트 데이터 형식의 사이즈
    DIDF_ABSAXIS,               // 절대축의 좌표
    sizeof(MYDATA),             // 디바이스 데이터의 사이즈
    numObjects,                 // 오브젝트수
    rgodf,                      // 그 위치
};

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

DIACTIONFORMAT


DIDEVCAPS

Microsoft® DirectInput® 디바이스의 능력을 나타낸다. 이 구조체는,IDirectInputDevice8::GetCapabilities 메소드로 사용된다.

typedef struct DIDEVCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwDevType;
    DWORD dwAxes;
    DWORD dwButtons;
    DWORD dwPOVs;
    DWORD dwFFSamplePeriod;
    DWORD dwFFMinTimeResolution;
    DWORD dwFirmwareRevision;
    DWORD dwHardwareRevision;
    DWORD dwFFDriverVersion;
} DIDEVCAPS, *LPDIDEVCAPS;

멤버

dwSize
이 구조체의 바이트 단위의 사이즈. IDirectInputDevice8::GetCapabilities 메소드에 호출하기 전에, 어플리케이션은, 이 멤버를 초기화해 두지 않으면 안 된다.
dwFlags
디바이스에 관련지을 수 있었던 플래그. 이 값은, 이하의 정수의 편성이 된다.
DIDC_ALIAS
디바이스는, 다른 DirectInput 디바이스의 복제이다. 별명의 디바이스는, 디폴트에서는 IDirectInput8::EnumDevices 에 의해 열거되지 않는다.
DIDC_ATTACHED
디바이스는, 물리적으로어태치 상태에 있다.
DIDC_DEADBAND
디바이스는, 적어도 1 개의 force feedback 조건으로 데드 밴드를 지원 하고 있다.
DIDC_EMULATED
이 플래그가 설정되면(자), 데이터는 HID (Human Interface Device)등의 유저 모드 디바이스 인터페이스로부터, 또는 다른 링 3 의 수단에 의해 입력된다. 플래그가 설정되지 않는 경우, 데이터는 커넬 모드 드라이버로부터 직접 입력된다.
DIDC_FORCEFEEDBACK
디바이스는, force feedback를 지원 한다.
DIDC_FFFADE
force feedback 시스템은, 적어도 1 개의 이펙트에 대한페이드 파라미터를 지원 한다. 디바이스가 페이드를 지원 하지 않는 경우, 디바이스는,DIENVELOPE 구조체의 페이드 레벨과 페이드 시간의 양파라미터를 무시한다.

IDirectInputDevice8::GetEffectInfo 메소드의 호출 후, 개별의 이펙트가 페이드를 지원 하고 있으면, DIEFT_FFFADE 플래그가 설정된다.

DIDC_FFATTACK
force feedback 시스템은, 적어도 1 개의 이펙트에 대한어택 파라미터를 지원 한다. 디바이스가 어택을 지원 하지 않는 경우, 디바이스는,DIENVELOPE 구조체의 어택 레벨과 어택 시간의 양파라미터를 무시한다.

IDirectInputDevice8::GetEffectInfo 메소드의 호출 후, 개별의 이펙트가 어택을 지원 하고 있으면, DIEFT_FFATTACK 플래그가 설정된다.

DIDC_HIDDEN
디바이스 드라이버가 키보드 이벤트나 마우스 이벤트를 생성할 수 있도록(듯이) 생성 된 가상 디바이스. 그러한 디바이스는 보통,IDirectInput8::EnumDevices 에 의해 열거되거나IDirectInput8::ConfigureDevices 에 의해 구성 되거나 하지 않는다.
DIDC_PHANTOM
장래 존재할 가능성이 있는 디바이스용의 플레이스홀더. 가상 디바이스는, 디폴트에서는 IDirectInput8::EnumDevices 에 의해 열거되지 않는다.
DIDC_POLLEDDATAFORMAT
현상의 데이터 형식에서 적어도 1 개의 오브젝트가, 세치기 구동은 아니고, 폴링 된다. 이러한 오브젝트를 위해서(때문에), 어플리케이션은 명시적으로 IDirectInputDevice8::Poll 메소드를 호출해, 데이터를 취득해야 한다.
DIDC_POLLEDDEVICE
디바이스 위에의 적어도 1 개의 오브젝트가, 세치기 구동은 아니고, 폴링 된다. 이러한 오브젝트를 위해서(때문에), 어플리케이션은 명시적으로 IDirectInputDevice8::Poll 메소드를 호출해, 데이터를 취득해야 한다. HID 디바이스는, 폴링 오브젝트와 비폴링 오브젝트를 혼재해 저장 할 수 있다.
DIDC_POSNEGCOEFFICIENTS
force feedback 시스템은, 적어도 1 개의 조건에 대해서 조건의 2 개의 계수값을 지원 한다 (한편은, 축의 정이동, 한편은, 축의 부이동). 디바이스가 한편의 계수 밖에 지원 하고 있지 않는 경우,DICONDITION 구조체의 부의 계수는 무시된다.

IDirectInputDevice8::GetEffectInfo 메소드의 호출 후, 개별의 조건이 정과 부의 계수를 따로 따로 지원 하고 있으면, 그 조건에서는, DIEFT_POSNEGCOEFFICIENTS 플래그가 설정된다.

DIDC_POSNEGSATURATION
force feedback 시스템은, 적어도 1 개의 조건에 대해서, 정부의 양쪽 모두의 포스 출력에 대한 최대포화를 지원 한다. 디바이스가 한편의 포화값 밖에 지원 하고 있지 않는 경우,DICONDITION 구조체의 부의 포화값은 무시된다.

IDirectInputDevice8::GetEffectInfo 메소드의 호출 후, 개별의 조건이 정과 부의 포화값을 따로 따로 지원 하고 있으면, 그 조건에서는, DIEFT_POSNEGSATURATION 플래그가 설정된다.

DIDC_SATURATION
force feedback 시스템은, 적어도 1 개의 조건에 대해서 조건 이펙트의포화를 지원 한다. 디바이스가 포화를 지원 하고 있지 않으면, 어느 조건의 아래에서 생성되는 포스는, 디바이스를 생성할 수 있는 최대 포스에 의해서만 제한된다.

IDirectInputDevice8::GetEffectInfo 메소드의 호출 후, 개별의 조건이 포화를 지원 하고 있으면, 그 조건에서는 DIEFT_SATURATION 플래그가 설정된다.

DIDC_STARTDELAY
force feedback 시스템은, 적어도 1 개의 이펙트에 대한 지연 파라미터를 지원 한다. 디바이스가 시작 지연을 지원 하지 않는 경우,DIEFFECT 구조체의 dwStartDelay 멤버는 무시된다.
dwDevType
디바이스 타입 지정자. 이 멤버는,DIDEVICEINSTANCE 구조체의 dwDevType 멤버와 동등한 값을 저장 할 수 있다.
dwAxes
디바이스상에서 사용 가능한 축의 수.
dwButtons
디바이스상에서 사용 가능한 버튼의 수.
dwPOVs
디바이스상에서 사용 가능한 시점 콘트롤러의 수.
dwFFSamplePeriod
미가공의 포스 커멘드를 연속해 재생할 때의 간격을 나타내는, 마이크로 세컨드 단위의 최소 시간.
dwFFMinTimeResolution
마이크로 세컨드 단위의 디바이스의 분해가능의 최소 시간. 디바이스는, 모든 시간을 가장 가까운 증가값에 말다. 예를 들어,dwFFMinTimeResolution 의 값이 1000 의 경우에는, 디바이스는 모든 시간을 가장 가까운 밀리 세컨드에 말다.
dwFirmwareRevision
디바이스의 펌 웨어 리버젼 번호.
dwHardwareRevision
디바이스의 하드웨어 리버젼 번호.
dwFFDriverVersion
디바이스 드라이버의 버젼 번호.

주의

버젼 번호의 붙이는 방법은 디바이스 메이커에 따라서 다르다. 확실한 것은, 새로운 버젼에는 이전의 버젼보다 큰 숫자가 붙는다, 라고 하는 것 뿐이다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

DIDEVICEINSTANCE


DIDEVICEIMAGEINFO

디바이스 이미지를 표시, 또는 이미지에 콜 아웃을 오버레이 하기 위해서 필요한 정보를 저장 한다. 이 구조체는,DIDEVICEIMAGEINFOHEADER 구조 체내의 배열로서 IDirectInputDevice8::GetImageInfo 메소드에게 건네진다.

typedef struct _DIDDEVICEIMAGEINFO {
    TCHAR  tszImagePath[MAX_PATH];
    DWORD  dwFlags;
    // dwFlags 에 DIDIFT_OVERLAY 가 존재하는 경우,
    // 다음의 코드는 유효하다.
    DWORD  dwViewID;
    RECT   rcOverlay;
    DWORD  dwObjID;
    DWORD  dwcValidPts;
    POINT  rgptCalloutLine[5];
    RECT   rcCalloutRect;
    DWORD  dwTextAlign;
} DIDEVICEIMAGEINFO, * LPDIDEVICEIMAGEINFO;

멤버

tszImagePath
디바이스의 이미지를 포함한 파일의 완전 수식 패스. 파일 포맷은 dwFlags 로 지정한다. 디바이스로 이용 가능한 이미지가 없으면, 이 멤버에는 NULL 가 설정된다. 그 경우, 디바이스의 컨트롤의 열거와 디바이스 컨트롤에 대한 디폴트의 액션 일람의 표시는, 어플리케이션측에서 실시할 필요가 있다 (Microsoft® DirectX® 8.0 보다 전의 대부분의 어플리케이션으로 사용되고 있던 방법과 같이).
dwFlags
이미지의 사용 목적을 기술한 플래그.
DIDIFT_CONFIGURATION
파일은, 디바이스에 대한 액션의 현재 구성을 표시하기 위해서 사용된다. 오버레이 이미지의 좌표는, 구성 이미지의 좌상구석을 기점으로 하는 상대 좌표이다.
DIDIFT_OVERLAY
파일 (지정되고 있는 경우)은, 구성 이미지의 오버레이이다. dwViewID,rcOverlay,dwObjID,rgptCalloutLine,rcCalloutRect, 및 dwTextAlign 의 각 멤버는 유효하고, 이것들에 저장 된 데이터를 사용해, 디바이스의 단일 컨트롤의 오버레이와 콜 아웃 정보가 표시된다. 파일이 지정되지 않는 경우 (패스 캐릭터 라인이 NULL),rcOverlay 이외의 관련하는 그 외 모든 멤버가 사용된다.
dwViewID
디바이스 뷰 이미지 (DIDIFT_CONFIGURATION)의 경우, 이것은 디바이스 뷰의 ID 이다. 디바이스 컨트롤 오버레이 (DIDIFT_OVERLAY)의 경우, 이 값은 디바이스 뷰를 ID 에 의해 참조한다. 디바이스 뷰에 의해, 이미지와 콜 아웃 정보가 표시된다.
rcOverlay
디바이스 구성 이미지의 좌상 픽셀을 원점으로 하는 상대 좌표를 사용해, 오버레이 이미지를 페인트 하는 대상의 직사각형. 이 멤버는,dwFlags 에 DIDIFT_OVERLAY 플래그가 포함되는 경우에게만 유효하다.
dwObjID
이 디바이스의 오버레이 이미지가 대응하는 컨트롤 식별자. DIDFT_* 플래그와 인스턴스값의 편성이다. 어플리케이션은 DIDFT_GETINSTANCE 및 DIDFT_GETTYPE 매크로를 사용해, 이 값으로부터 구성 부분을 읽어낸다. 이 멤버는,dwFlags 에 DIDIFT_OVERLAY 플래그가 포함되는 경우에게만 유효하다.
dwcValidPts
rgptCalloutLine 가 가리키는 배열의 포인트수.
rgptCalloutLine
콜 아웃선을 드로잉(Drawing) 하는 포인트의 좌표를 지정하는 POINT 구조체의 배열. 콜 아웃선은, 디바이스 컨트롤과 게임 액션의 캡션을 묶는 선이다. 각 선은, 1 ~ 4 의 세그먼트(segment)를 가질 수가 있다. 이 멤버는,dwFlags 에 DIDIFT_OVERLAY 플래그가 포함되는 경우에게만 유효하다.
rcCalloutRect
게임 액션의 캐릭터 라인이 표시되는 직사각형을 나타내는 RECT 구조체. 캐릭터 라인이 직사각형내에 들어가지 않는 경우는, 어플리케이션측에서 클리핑을 처리할 필요가 있다. 이 멤버는,dwFlags 에 DIDIFT_OVERLAY 플래그가 포함되는 경우에게만 유효하다.
dwTextAlign
rcCalloutRect 멤버가 나타내는 직사각형내의 텍스트의 배치를 지정하는 DWORD 값. 1 개의 수평 방향의 배치 플래그와 1 개의 수직 방향의 배치 플래그의 편성이 아니면 안된다.

정의 끝난 수평 방향 배치 플래그는 다음대로.

DIDAL_LEFTALIGNED
텍스트를 좌 범위선에 가지런히 한다.
DIDAL_CENTERED
텍스트를 수평 방향의 중앙에 댄다.
DIDAL_RIGHTALIGNED
텍스트를 우 범위선에 가지런히 한다.

정의 끝난 수직 방향 배치 플래그는 다음대로.

DIDAL_MIDDLE
텍스트를 수직 방향의 중앙에 댄다.
DIDAL_TOPALIGNED
텍스트를 상 범위 선에 가지런히 한다.
DIDAL_BOTTOMALIGNED
텍스트를 하 범위 선에 가지런히 한다.

이 멤버는,dwFlags 에 DIDIFT_OVERLAY 플래그가 포함되는 경우에게만 유효하다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIDEVICEIMAGEINFOHEADER

디바이스 이미지에 관한 정보를 저장 한다. IDirectInputDevice8::GetImageInfo 메소드로 사용된다.

typedef struct _DIDEVICEIMAGEINFOHEADER{
    DWORD  dwSize;
    DWORD  dwSizeImageInfo;
    DWORD  dwcViews;
    DWORD  dwcButtons;
    DWORD  dwcAxes;
    DWORD  dwcPOVs;
    DWORD  dwBufferSize;
    DWORD  dwBufferUsed;
    DIDEVICEIMAGEINFO *lprgImageInfoArray;
} DIDEVICEIMAGEINFOHEADER, * LPDIDEVICEIMAGEINFOHEADER;

멤버

dwSize
이 구조체의 사이즈를 바이트 단위로 지정하는 DWORD 값. 구조체가 사용 가능하게 되기 전에 초기화할 필요가 있다.
dwSizeImageInfo
DIDEVICEIMAGEINFO 구조체의 사이즈를 바이트 단위로 지정하는 DWORD 값. 이 구조체가 사용 가능하게 되기 전에 초기화할 필요가 있다.
dwcViews
이 디바이스의 뷰수를 받는 DWORD 변수.
dwcButtons
이 디바이스의 버튼수를 받는 DWORD 변수.
dwcAxes
이 디바이스의 축수를 받는 DWORD 변수.
dwcPOVs
이 디바이스의 시점 콘트롤러수를 받는 DWORD 변수.
dwBufferSize
lprgImageInfo 가 가리키는 버퍼의 사이즈를 바이트 단위로 지정하는 DWORD 값. 제로를 설정 하면,IDirectInputDevice8::GetImageInfo 메소드는 그 외 모든 멤버를 무시해, 모든 이미지에 관한 정보의 보관 유지에 필요한 최소 버퍼 사이즈를 돌려준다.
dwBufferUsed
lprgImageInfo 가 가리키는 버퍼의 사이즈를 바이트 단위로 취득하는 DWORD 값. dwBufferSize 에 제로가 설정되면(자),IDirectInputDevice8::GetImageInfo 메소드는, 모든 이미지에 관한 정보의 보관 유지에 필요한 최소 버퍼 사이즈를, 이 멤버로 설정한다.
lprgImageInfoArray
DIDEVICEIMAGEINFO 구조체의 배열을 받는 버퍼에의 포인터. 이러한 구조체는, 모든 디바이스 이미지와 뷰, 오버레이 이미지, 및 콜 아웃 캐릭터 라인 좌표를 나타낸다.

주의

lprgImageInfoArray 가 가리키는 버퍼는, 필요한 이미지 정보 구조체를 모두 보관 유지 가능한 한의 사이즈를 확보할 필요가 있다. 어플리케이션은,dwBufferSize 멤버에 제로를 설정해 IDirectInputDevice8::GetImageInfo 메소드를 호출하는 것으로, 필요한 사이즈를 조회할 수 있다. 호출 후,dwBufferUsed 에는 수정된 메모리량이 바이트 단위로 저장 되고 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIDEVICEINSTANCE

Microsoft® DirectInput® 디바이스의 인스턴스를 나타낸다. 이 구조체는,IDirectInput8::EnumDevices ,IDirectInput8::EnumDevicesBySemantics , 및 IDirectInputDevice8::GetDeviceInfo 메소드로 사용된다.

typedef struct DIDEVICEINSTANCE {
    DWORD dwSize;
    GUID  guidInstance;
    GUID  guidProduct;
    DWORD dwDevType;
    TCHAR tszInstanceName[MAX_PATH];
    TCHAR tszProductName[MAX_PATH];
    GUID  guidFFDriver;
    WORD  wUsagePage;
    WORD  wUsage;
} DIDEVICEINSTANCE, *LPDIDEVICEINSTANCE;

typedef const DIDEVICEINSTANCE  *LPCDIDEVICEINSTANCE;

멤버

dwSize
이 구조체의 바이트 단위의 사이즈. 이 멤버는, 구조체가 사용되기 전에 초기화되지 않으면 안 된다.
guidInstance
디바이스의 인스턴스에 대한 일의인 식별자. 어플리케이션은, 이 인스턴스 GUID 를 구성 파일에 보존해, 다음에 사용할 수도 있다. 인스턴스 GUID 는, 컴퓨터 마다 고유하다. 1 개의 컴퓨터로부터 취득되는 인스턴스 GUID 는, 다른 컴퓨터 위에의 인스턴스 GUID 와는 무관계하다.
guidProduct
제품의 일의인 식별자. 이 식별자는, 디바이스 메이커가 정한다.
dwDevType
디바이스 타입 지정자. 디바이스 타입 기술 코드의 최하정도 바이트는, 디바이스 타입을 지정한다. 최하정도 바이트로부터 1 개 상위의 바이트는, 디바이스 서브 타입을 지정한다. 이 값은,HID (Human Interface Device)를 지정하는 DIDEVTYPE_HID 와 조합할 수도 있다.
tszInstanceName[MAX_PATH]
인스턴스의 등록명. 예를 들어,"Joystick 1".
tszProductName[MAX_PATH]
제품의 등록명.
guidFFDriver
force feedback에 사용되는 드라이버의 일의인 식별자. 드라이버의 메이커가 이 식별자를 설정한다.
wUsagePage
디바이스가 HID (Human Interface Device) 디바이스이면, 이 멤버에는, HID 사용 페이지 코드가 포함된다.
wUsage
디바이스가 HID (Human Interface Device) 디바이스이면, 이 멤버에는, HID 사용 코드가 포함된다.

주의

dwDevType 멤버로 사용할 수 있도록(듯이), 다음의 디바이스 타입과 서브 타입이 정의되고 있다.

DI8DEVTYPE_1STPERSON
대면형의 액션 게임 디바이스. 다음의 서브 타입이 정의된다.
DI8DEVTYPE1STPERSON_LIMITED
액션 매핑 대상의 디바이스 오브젝트의 최소수를 지정하지 않는 디바이스.
DI8DEVTYPE1STPERSON_SHOOTER
대면형의 슈팅 게임용으로 설계된 디바이스.
DI8DEVTYPE1STPERSON_SIXDOF
6 단계 (3 개의 횡방향축과 3 개의 회전축)의 자유를 갖춘 디바이스.
DI8DEVTYPE1STPERSON_UNKNOWN
불명한 서브 타입.
DI8DEVTYPE_DEVICE
다른 카테고리로 분류되지 않는 디바이스.
DI8DEVTYPE_DEVICECTRL
어플리케이션의 문맥으로부터 별타입의 디바이스의 제어에 사용되는 입력 디바이스. 다음의 서브 타입이 정의된다.
DI8DEVTYPEDEVICECTRL_COMMSSELECTION
통신의 선택에 사용되는 컨트롤.
DI8DEVTYPEDEVICECTRL_COMMSSELECTION_HARDWIRED
디폴트의 구성을 사용할 필요가 있어, 매핑을 변경할 수 없는 디바이스.
DI8DEVTYPEDEVICECTRL_UNKNOWN
불명한 서브 타입.
DI8DEVTYPE_DRIVING
스티어링용 디바이스. 다음의 서브 타입이 정의된다.
DI8DEVTYPEDRIVING_COMBINEDPEDALS
단일의 축으로부터 액셀과 브레이키페달의 값을 보고하는 스티어링 디바이스.
DI8DEVTYPEDRIVING_DUALPEDALS
다른 축으로부터 액셀과 브레이키페달의 값을 보고하는 스티어링 디바이스.
DI8DEVTYPEDRIVING_HANDHELD
소형의 스티어링 디바이스.
DI8DEVTYPEDRIVING_LIMITED
액션 매핑 대상의 디바이스 오브젝트의 최소수를 지정하지 않는 스티어링 디바이스.
DI8DEVTYPEDRIVING_THREEPEDALS
다른 축으로부터 액셀, 브레이크, 및 쿠랏치페달의 값을 보고하는 스티어링 디바이스.
DI8DEVTYPE_FLIGHT
플라이트 시뮬레이션용 콘트롤러. 다음의 서브 타입이 정의된다.
DI8DEVTYPEFLIGHT_LIMITED
액션 매핑 대상의 디바이스 오브젝트의 최소수를 지정하지 않는 플라이트 콘트롤러.
DI8DEVTYPEFLIGHT_RC
모형 비행기의 리모트 콘트롤에 근거하는 플라이트 디바이스.
DI8DEVTYPEFLIGHT_STICK
죠이스틱.
DI8DEVTYPEFLIGHT_YOKE
조종고리.
DI8DEVTYPE_GAMEPAD
게임패드. 다음의 서브 타입이 정의된다.
DI8DEVTYPEGAMEPAD_LIMITED
액션 매핑 대상의 디바이스 오브젝트의 최소수를 지정하지 않는 게임패드.
DI8DEVTYPEGAMEPAD_STANDARD
액션 매핑 대상의 디바이스 오브젝트의 최소수를 지정하지 않는 표준 게임패드.
DI8DEVTYPEGAMEPAD_TILT
콘트롤러의 자세로부터 x 축과 y 축의 데이터를 보고하는 게임패드.
DI8DEVTYPE_JOYSTICK
죠이스틱. 다음의 서브 타입이 정의된다.
DI8DEVTYPEJOYSTICK_LIMITED
액션 매핑 대상의 디바이스 오브젝트의 최소수를 지정하지 않는 죠이스틱.
DI8DEVTYPEJOYSTICK_STANDARD
액션 매핑 대상의 디바이스 오브젝트의 최소수를 지정하는 표준 죠이스틱.
DI8DEVTYPE_KEYBOARD
키보드 또는 키보드 유사 디바이스. 다음의 서브 타입이 정의된다.
DI8DEVTYPEKEYBOARD_UNKNOWN
서브 타입은 확정할 수 없다.
DI8DEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 키 키보드
DI8DEVTYPEKEYBOARD_OLIVETTI
Olivetti 102 키 키보드
DI8DEVTYPEKEYBOARD_PCAT
IBM PC/AT 84 키 키보드
DI8DEVTYPEKEYBOARD_PCENH
IBM PC 확장 101/102 키식 키보드 또는 Microsoft 내츄럴 키보드
DI8DEVTYPEKEYBOARD_NOKIA1050
Nokia 1050 키보드
DI8DEVTYPEKEYBOARD_NOKIA9140
Nokia 9140 키보드
DI8DEVTYPEKEYBOARD_NEC98
일본어 NEC PC98 키보드
DI8DEVTYPEKEYBOARD_NEC98LAPTOP
일본어 NEC PC98 랩탑 키보드
DI8DEVTYPEKEYBOARD_NEC98106
일본어 NEC PC98 106 키 키보드
DI8DEVTYPEKEYBOARD_JAPAN106
일본어 106 키 키보드
DI8DEVTYPEKEYBOARD_JAPANAX
일본어 AX 키보드
DI8DEVTYPEKEYBOARD_J3100
일본어 J3100 키보드
DI8DEVTYPE_MOUSE
마우스 또는 마우스 유사 디바이스 (트랙볼 등). 다음의 서브 타입이 정의된다.
DI8DEVTYPEMOUSE_ABSOLUTE
절대축데이터를 돌려주는 마우스.
DI8DEVTYPEMOUSE_FINGERSTICK
FINGER 스틱.
DI8DEVTYPEMOUSE_TOUCHPAD
터치 패드.
DI8DEVTYPEMOUSE_TRACKBALL
트랙볼.
DI8DEVTYPEMOUSE_TRADITIONAL
종래형 마우스.
DI8DEVTYPEMOUSE_UNKNOWN
서브 타입은 확정할 수 없다.
DI8DEVTYPE_REMOTE
리모트 콘트롤 디바이스. 다음의 서브 타입이 정의된다.
DI8DEVTYPEREMOTE_UNKNOWN
서브 타입은 확정할 수 없다.
DI8DEVTYPE_SCREENPOINTER
스크린 포인터. 다음의 서브 타입이 정의된다.
DI8DEVTYPESCREENPTR_UNKNOWN
불명한 서브 타입.
DI8DEVTYPESCREENPTR_LIGHTGUN
라이트 암.
DI8DEVTYPESCREENPTR_LIGHTPEN
light pen.
DI8DEVTYPESCREENPTR_TOUCH
터치 스크린.
DI8DEVTYPE_SUPPLEMENTAL
휠과 함께 사용하는 페달 등, 어플리케이션의 메인 컨트롤에 적합하지 않는 기능을 갖춘 특수 디바이스. 다음의 서브 타입이 정의된다.
DI8DEVTYPESUPPLEMENTAL_2NDHANDCONTROLLER
2 차적 소형 콘트롤러.
DI8DEVTYPESUPPLEMENTAL_COMBINEDPEDALS
주기능으로서 단일의 축으로부터 액셀과 브레이키페달의 값을 보고하는 디바이스.
DI8DEVTYPESUPPLEMENTAL_DUALPEDALS
주기능으로서 다른 축으로부터 액셀과 브레이키페달의 값을 보고하는 디바이스.
DI8DEVTYPESUPPLEMENTAL_HANDTRACKER
손의 이동을 추적하는 디바이스.
DI8DEVTYPESUPPLEMENTAL_HEADTRACKER
머리의 이동을 추적하는 디바이스.
DI8DEVTYPESUPPLEMENTAL_RUDDERPEDALS
방향타 페달을 갖춘 디바이스.
DI8DEVTYPESUPPLEMENTAL_SHIFTER
축으로부터 기어 선택을 보고하는 디바이스.
DI8DEVTYPESUPPLEMENTAL_SHIFTSTICKGATE
버튼 상태로부터 기어 선택을 보고하는 디바이스.
DI8DEVTYPESUPPLEMENTAL_SPLITTHROTTLE
주기능으로서 2 개(살) 이상의 스롯톨값을 보고하는 디바이스. 그 외의 컨트롤을 가지는 경우가 있다.
DI8DEVTYPESUPPLEMENTAL_THREEPEDALS
주기능으로서 다른 축으로부터 액셀, 브레이크, 및 쿠랏치페달의 값을 보고하는 디바이스.
DI8DEVTYPESUPPLEMENTAL_THROTTLE
주기능으로서 단일의 스롯톨값을 보고하는 디바이스. 그 외의 컨트롤을 가지는 경우가 있다.
DI8DEVTYPESUPPLEMENTAL_UNKNOWN
불명한 서브 타입.

Microsoft DirectX® 8.0 보다 전의 버젼의 DirectInput 에서는, 디바이스 타입과 서브 타입의 구성이 일부 다르다. Dinput.h 의 DIDEVTYPExxx 정의를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIDEVICEOBJECTDATA

버퍼링 디바이스의 정보를 저장 한다. 이 구조체는,IDirectInputDevice8::GetDeviceData 및 IDirectInputDevice8::SendDeviceData 메소드로 사용된다.

typedef struct DIDEVICEOBJECTDATA {
    DWORD    dwOfs;
    DWORD    dwData;
    DWORD    dwTimeStamp;
    DWORD    dwSequence;
    UINT_PTR uAppData;
} DIDEVICEOBJECTDATA, *LPDIDEVICEOBJECTDATA;

typedef const DIDEVICEOBJECTDATA *LPCDIDEVICEOBJECTDATA;

멤버

dwOfs
GetDeviceData 의 경우, 데이터의 보고 대상이 되고 있는 오브젝트의, 현재의 데이터 형식에 대한 오프셋(offset)값. 즉,IDirectInputDevice8::GetDeviceState 메소드의 호출에 의해 데이터가 취득되었을 경우, 그 dwData 가 저장 되고 있는 위치가 된다. 디바이스가 마우스, 키보드, 또는 죠이스틱으로서 액세스 되는 경우에, 이 dwOfs 멤버는,마우스 디바이스 정수,키보드 디바이스 정수, 또는죠이스틱 디바이스 정수의 어느 쪽인가에 된다. 커스텀 데이터 형식이 설정되어 있는 경우는, 커스텀 데이터 형식에 관련하는 오프셋(offset)가 된다.

액션 매핑이 사용중이면, 이 멤버를 무시할 수 있다. 그 대신에,uAppData 로부터 액션값을 취득한다.

SendDeviceData 의 경우, 데이터의 송신지인 오브젝트의 인스턴스 ID. 이것은 DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버로부터 취득된다.

dwData
디바이스로부터 취득, 또는 디바이스에 송신되는 데이터.

축으로부터의 입력의 경우, 디바이스가 상대축모드에 있으면, 상대축의 움직임이 보고된다. 디바이스가 절대축모드에 있으면, 절대 좌표가 보고된다.

버튼으로부터의 입력의 경우,dwData 의 하위 바이트만이 의미가 있다. 하위 바이트의 상위 비트는, 버튼이 밀렸을 때에 설정되어 떼어 놓아졌을 때에 소거된다.

dwTimeStamp
입력 이벤트가 생성된 밀리 세컨드 단위의 시스템 시간. 덧붙여 이 값은, 약 50 일에 순환한다. 「주의」를 참조할것.

구조체가 SendDeviceData 메소드와 함께 사용되는 경우, 이 멤버는 반드시 제로가 된다.

dwSequence
이 이벤트에 대한 Microsoft® DirectInput® 순서 번호. 모든 입력 이벤트에는, 승순의 순서 번호를 할당할 수 있고 있다. 이것에 의해, 다른 디바이스로부터의 이벤트를 시간순서에 소트 하는 것이 가능하게 된다. 이 값은, 순환해 초기값에 돌아오므로, 2 개의 순서 번호를 비교하는 경우에는 주의하지 않으면 안 된다. 이 비교를 확실히 실시하려면 ,DISEQUENCE_COMPARE 매크로를 사용하면 좋다.

구조체가 SendDeviceData 메소드와 함께 사용되는 경우, 이 멤버는 반드시 제로가 된다.

uAppData
전회의 IDirectInputDevice8::SetActionMap 의 호출로, 이 오브젝트에 할당할 수 있었던 어플리케이션 정의의 액션값. 이것은, 오브젝트에 관련지을 수 있었던 DIACTION 구조체의 uAppData 멤버의 값이다. 액션 매핑을 사용하고 있지 않는 경우는 이 값을 무시한다.

구조체가 SendDeviceData 메소드와 함께 사용되는 경우, 이 멤버는 반드시 제로가 된다.

주의

dwTimeStamp 가 돌려주는 시스템 시간은, Microsoft® Win32® 의 GetTickCount 또는 timeGetTime 함수가 사용하는 것과 같은 클락에 유래하는 것이지만, 보다 정밀한 값을 나타낸다고 생각된다. 예를 들어, Microsoft® Windows® 95 의 경우,GetTickCount 타이머의 갱신 간격은 55 밀리 세컨드이지만,dwTimeStamp 의 값의 오차는 1 밀리 세컨드 이내이다. 이 때문에,GetTickCount 를 호출해 n 라고 하는 값이 돌려주어져n + n1 라고 하는 타임 스탬프를 가지는 이벤트를 받는 경우, 그 이벤트가 GetTickCount 를 호출하고 나서 정확히 n1 밀리 세컨드 후에 발생했다, 라고 가정할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIDEVICEOBJECTINSTANCE

디바이스 오브젝트의 인스턴스에 관한 정보를 저장 한다. 이 구조체는,IDirectInputDevice8::EnumObjects 메소드로 사용되어DIEnumDeviceObjectsCallback 콜백 함수에 대해서, 축 또는 버튼 등, 디바이스에 관련지을 수 있었던 특정의 오브젝트에 관한 정보를 제공한다. 또, 디바이스 오브젝트의 정보를 취득하기 위해서,IDirectInputDevice8::GetObjectInfo 메소드에서도 사용된다.

typedef struct DIDEVICEOBJECTINSTANCE {
    DWORD dwSize;
    GUID  guidType;
    DWORD dwOfs;
    DWORD dwType;
    DWORD dwFlags;
    TCHAR tszName[MAX_PATH];
    DWORD dwFFMaxForce;
    DWORD dwFFForceResolution;
    WORD  wCollectionNumber;
    WORD  wDesignatorIndex;
    WORD  wUsagePage;
    WORD  wUsage;
    DWORD dwDimension;
    WORD  wExponent;
    WORD  wReportId;
} DIDEVICEOBJECTINSTANCE, *LPDIDEVICEOBJECTINSTANCE;

typedef const DIDEVICEOBJECTINSTANCE *LPCDIDEVICEOBJECTINSTANCE;

멤버

dwSize
이 구조체의 바이트 단위의 사이즈. 열거동안에, 어플리케이션은 이 값을 조사해 구조체의 멤버가 몇개 유효한가를 확인할 수 있다. 구조체가 IDirectInputDevice8::GetObjectInfo 메소드에게 건네질 때, 이 멤버를 sizeof(DIDEVICEOBJECTINSTANCE) 에 초기화해야 한다.
guidType
오브젝트 타입을 나타내는 일의인 식별자. 이 멤버는 옵션이다. 다음의 어느쪽이든 1 개의 값을 취할 수가 있다.
GUID_XAxis
수평축. 예를 들어, 마우스의 좌우의 움직임을 나타낼 수가 있다.
GUID_YAxis
수직축. 예를 들어, 마우스의 전후의 움직임을 나타낼 수가 있다.
GUID_ZAxis
z 축. 예를 들어, 마우스 위에의 휠의 회전, 또는 죠이스틱의 스롯톨 제어의 이동을 나타낼 수가 있다.
GUID_RxAxis
x 축을 중심으로 하는 회전.
GUID_RyAxis
y 축을 중심으로 하는 회전.
GUID_RzAxis
z 축을 중심으로 하는 회전 (방향타의 컨트롤로 자주(잘) 사용된다).
GUID_Slider
슬라이더축.
GUID_Button
mouse button.
GUID_Key
키보드의 키.
GUID_POV
시점 인디케이터(indicator)
GUID_Unknown
확정할 수 없다.

장래, 이외의 오브젝트 타입도 정의될 가능성이 있다.

dwOfs
데이터 형식내의 오프셋(offset)로, 이 오브젝트에 보고되는 데이터의 위치. 이 값은, 메소드 호출해에 있어서의 오브젝트와 DIPH_BYOFFSET 플래그를 받는 구조체안의 오브젝트를 식별하기 위해서 사용된다. 「주의」를 참조할것.
dwType
오브젝트를 나타내는 디바이스 타입. 오브젝트 타입 (축, 버튼등)을 나타내는 DIDFT_* 플래그의 편성이며, 중앙의 16 비트에는, 오브젝트 인스턴스 번호가 저장 된다. 오브젝트 인스턴스 번호를 추출하려면 ,DIDFT_GETINSTANCE 매크로를 사용한다. DIDFT_* 플래그에 대해서는, 「IDirectInputDevice8::EnumObjects 」를 참조할것.
dwFlags
데이터 형식외의 속성을 나타내는 플래그. 이 값은, 다음의 어느쪽이든 1 개(살)이다.
DIDOI_ASPECTACCEL
오브젝트는 가속도 정보를 보고한다.
DIDOI_ASPECTFORCE
오브젝트는 포스 정보를 보고한다.
DIDOI_ASPECTMASK
어스펙트 정보를 보고하기 위한 비트. 1 개의 오브젝트는 최대 1 개의 어스펙트 밖에 나타낼 수가 없다.
DIDOI_ASPECTPOSITION
오브젝트는 위치 정보를 보고한다.
DIDOI_ASPECTVELOCITY
오브젝트는 속도 정보를 보고한다.
DIDOI_FFACTUATOR
오브젝트는, force feedback 이펙트를 자신에게 적용시킬 수가 있다.
DIDOI_FFEFFECTTRIGGER
오브젝트는, force feedback 이펙트의 재생을 방아쇠 한다.
DIDOI_GUIDISUSAGE
DIOBJECTDATAFORMAT 구조체의 pguid 멤버에는, 필요한 사용 페이지와 사용 상황이, 팩 된 DWORD 형식에서 저장 된다. 「DIMAKEUSAGEDWORD 」를 참조할것.
DIDOI_POLLED
IDirectInputDevice8::Poll 메소드가 불려 갈 때까지, 오브젝트는 데이터를 돌려주지 않는다.
tszName[MAX_PATH]
오브젝트의 이름. 예를 들어,"X-Axis" 또는 "Right Shift" 등.
dwFFMaxForce
이 오브젝트에 관련지을 수 있었던 액츄에이터를 만들어 낼 수 있는 최대 포스의 매그니튜드. 포스는, 뉴턴 단위로 표현되어 디바이스를 보통에 조작하고 있는 동안의 손의 위치와의 관련으로 측정된다.
dwFFForceResolution
이 오브젝트에 관련지을 수 있었던 액츄에이터의 포스 분해가능. 반환값은, force feedback 시스템이 0 (포스 없음)으로부터 최대 포스의 범위에서 표현할 수 있는 포스의 단계수 또는 하위 구분의 수를 나타낸다.
wCollectionNumber
오브젝트가 속하는 HID (Human Interface Device) 링크 콜렉션.
wDesignatorIndex
HID 물리 기술자의 지정을 참조하는 인덱스. 이 수치는, 디바이스 오브젝트에 대한 추가 정보를 포함한 HID 해석 라이브러리 (Hidpi.h)의 함수에게 건네진다.
wUsagePage
오브젝트에 관련하는 HID (Human Interface Device) 사용 페이지 (판명되었을 경우). HID 는 항상 사용 페이지를 보고한다. 비 HID 디바이스는 옵션으로 사용 페이지를 보고한다. 비 HID 디바이스가 보고하지 않는 경우, 이 파라미터의 값은 제로가 된다.
wUsage
오브젝트에 관련하는 HID 사용 상황 (판명되었을 경우). HID 는 항상 사용 상황을 보고한다. 비 HID 는 옵션으로 사용 상황을 보고한다. 비 HID 디바이스가 보고하지 않는 경우, 이 파라미터의 값은 제로가 된다.
dwDimension
오브젝트의 값을 보고하는 차원 단위의 HID (Human Interface Device) 코드 (판명하고 있는 경우). 불명한 경우는 제로가 된다.
wExponent
단위에 붙이는 지수 (판명하고 있는 경우). 차원 단위는 항상 정수이므로, 정수 이외의 타입에 단위를 변환하려면 지수가 필요하다.
wReportId
예약이 끝난 상태.

주의

디바이스에 데이터 형식이 설정되었을 경우,dwOfs 의 값은, 그 형식내의 오브젝트 데이터의 오프셋(offset)이다. 형식이 설정되어 있지 않은 경우, 값은, 디바이스가 돌려주는 미가공 데이터내의 오프셋(offset)이다. 데이터 형식이 설정되어 있지 않은 경우, 어플리케이션은 이 값을 사용할 필요가 있다.

어플리케이션은 wUsagePage 및 wUsage 멤버를 사용해, 오브젝트의 설계 목적에 관한 추가 정보를 얻을 수 있다. 예를 들어,wUsagePage 의 값이 0x02 (탈 것의 컨트롤)로,wUsage 의 값이 0xB9 (승강타 트림)의 경우, 오브젝트는, 조종간의 승강타 트림콘트로르로서 설계되고 있다. 항공 시뮬레이션 게임 어플리케이션은 이 정보를 사용해, 디바이스 위에의 오브젝트에 대해서, 보다 적절한 디폴트 동작을 제공할 수가 있다. HID 사용 코드는 USB 표준 위원회에서 정해져 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIEFFECT

IDirectInputDevice8::CreateEffect 메소드가, 새로운 IDirectInputEffect 오브젝트를 초기화하기 위해서 사용한다. IDirectInputEffect::SetParameters 및 IDirectInputEffect::GetParameters 메소드에 의해도 사용된다.

typedef struct DIEFFECT {
    DWORD   dwSize;
    DWORD   dwFlags;
    DWORD   dwDuration;
    DWORD   dwSamplePeriod;
    DWORD   dwGain;
    DWORD   dwTriggerButton;
    DWORD   dwTriggerRepeatInterval;
    DWORD   cAxes;
    LPDWORD rgdwAxes;
    LPLONG  rglDirection;
    LPDIENVELOPE lpEnvelope;
    DWORD   cbTypeSpecificParams;
    LPVOID  lpvTypeSpecificParams;
    DWORD   dwStartDelay;
} DIEFFECT, *LPDIEFFECT;

typedef const DIEFFECT *LPCDIEFFECT;

멤버

dwSize
구조체의 바이트 단위의 사이즈. 이 멤버는, 구조체가 사용되기 전에 초기화되지 않으면 안 된다.
dwFlags
이펙트에 관련지을 수 있었던 플래그. 이 값은, 이하의 값의 1 개 이상의 편성이 된다.
DIEFF_CARTESIAN
rglDirection 의 값은, 데카르트 좌표로서 해석한다.
DIEFF_OBJECTIDS
dwTriggerButton 및 rgdwAxes 의 값은,IDirectInputDevice8::EnumObjects 에 의해 취득되는 오브젝트 식별자이다.
DIEFF_OBJECTOFFSETS
dwTriggerButton 및 rgdwAxes 의 값은, 데이터 형식의 오프셋(offset)이다.
DIEFF_POLAR
rglDirection 의 값은, 극좌표라고 해석한다.
DIEFF_SPHERICAL
rglDirection 의 값은, 구(공)장 좌표라고 해석한다.
dwDuration
이펙트의 마이크로 세컨드 단위의 계속 시간의 합계. 이 값이 INFINITE 이면, 이펙트의 계속 시간은 무한이 된다. 포락선이 이펙트에 적용되고 있으면,어택도 적용되어 무한의유지 기간도 적용되게 된다.
dwSamplePeriod
디바이스가 이펙트를 재생해야 할 간격. 마이크로 세컨드 단위. 이 값이 제로이면, 디폴트의 재생 샘플링 속도를 사용하는 것을 의미한다.

디바이스가 지정의 속도로 이펙트를 재생할 수 없으면, 지정된 값에 가장 가까운 속도를 선택한다.

커스텀 dwSamplePeriod 의 설정은, 특수 효과에 사용할 수 있다. 예를 들어, 싸인파를 의도적으로 큰 샘플링 레이트로 재생 하면, 거슬거슬 한 질감을 가져온다.

dwGain
이펙트에 적용되는 게인. 0 ~ 10,000 의 범위에 있다. 게인이란, 이펙트의 전매그니튜드와 그 포락선에 적용되는 스케일링 계수이다.
dwTriggerButton
이펙트의 재생을 방아쇠 하는데 사용되는 버튼의 식별자 또는 오프셋(offset). DIEFF_OBJECTIDS 및 DIEFF_OBJECTOFFSETS 의 각 플래그가, 이 값의 의미 내용을 결정한다. 이 멤버에 DIEB_NOTRIGGER 가 설정되어 있는 경우, 이펙트에 관련지을 수 있고 있는 방아쇠 버튼은 없다.
dwTriggerRepeatInterval
버튼의 압하 및 계속 눌러 에 의해 이펙트가 방아쇠 되었을 때의, 1 회의 재생의 종료와 시작의 간격을 나타내는, 마이크로 세컨드 단위의 시간. 반복을 억제하려면 , 이 값을 INFINITE 로 설정한다.

DIEFFECTINFO 구조체의 dwStaticParams 멤버에 DIEP_TRIGGERREPEATINTERVAL 플래그가 설정되어 있는 경우는, 1 개의 이펙트의 방아쇠에 의한 반복이 가능하다.

cAxes
이펙트에 관련하고 있는 축의 수. 축리스트 또는 방향 리스트의 변경 또는 설정시에는, 호출측이 이 멤버를 설정해 두지 않으면 안 된다.

이펙트의 축수는, 한 번 설정된다고 변경할 수 없다.

rgdwAxes
(cAxes 요소로부터 완성된다) DWORD 배열에의 포인터. 이 DWORD 배열은, 이펙트를 적용하는 대상의 축을 식별하는 식별자 또는 오프셋(offset)를 저장 한다. DIEFF_OBJECTIDS 및 DIEFF_OBJECTOFFSETS 의 각 플래그가, 배열의 값의 의미 내용을 결정한다.

이펙트에 관련지을 수 있었던 축의 리스트는, 한 번 설정된다고 변경할 수 없다.

단일의 이펙트에 관련지을 수 있는 축의 수는, 32 까지이다.

rglDirection
데카르트 좌표, 극좌표, 또는 구(공)장 좌표를 저장 하는 (cAxes 요소로부터 완성된다) LONG 배열에의 포인터. DIEFF_CARTESIAN, DIEFF_POLAR 및 DIEFF_SPHERICAL 의 각 플래그가 배열의 값의 의미 내용을 결정한다.

데카르트 좌표에서는,rglDirection 의 각 값은,rgdwAxes 의 대응하는 축으로 관련지을 수 있다.

극좌표에서는, 각도는, (0, -1) 방향으로부터 (1, 0)의 방향으로 회전하는 열매 각도의 100 배로 측정된다. 이것이 의미하는 것은, 북쪽은 유저의 정면의 방향이며, 동쪽은 유저의 우측이다고 하는 것이다. 마지막 요소는 사용되지 않는다.

구(공)장 좌표에서는, 제 1 의 각도는, (1,0)의 방향으로부터 (0,1)의 방향에 회전한 열매 각도의 100 배로 계측 된다. 제 2 의 각도는 (축의 수가 3 이상일 때), (0,0,1)로 향하는 열매 각도의 100 배로 계측 된다. 제 3 의 각도는 (축의 수가 4 이상일 때), (0,0,0,1)로 향하는 열매 각도의 100 배로 계측 된다. 이하도 이와 같이 해석한다. 마지막 요소는 사용되지 않는다.

주 : rglDirection 배열은, 극좌표 또는 구(공)장 좌표가 지정되고 있는 경우에서도 cAxes 엔트리를 포함하지 않으면 안 된다. 극좌표 또는 구(공)면좌표의 경우,rglDirection 배열의 마지막 요소는, 장래의 용도를 위해서(때문에) 예약되고 있으므로, 제로가 아니면 안된다.

lpEnvelope
이 이펙트가 사용하는 포락선을 나타내는 DIENVELOPE 구조체에의 옵션 포인터. 모든 이펙트 타입이,포락선을 사용 하면은 한정되지 않는다. 포락선의 적용이 없으면, 이 멤버에는, NULL 를 설정할 필요가 있다.
cbTypeSpecificParams
대응하는 이펙트 타입에 관한 추가의 타입 고유 파라미터의 바이트수.
lpvTypeSpecificParams
타입 고유 파라미터에의 포인터. 타입 고유 파라미터가 존재하지 않는 경우에는 NULL.

이펙트가 DIEFT_CONDITION 형이면, 이 멤버는, 조건의 파라미터를 정의하는 DICONDITION 구조체로부터 되는 배열에의 포인터를 가진다. 1 개의 구조체를 사용해도 괜찮다. 이 경우, 조건은 배열 rglDirection 로 지정된 방향으로 적용된다. 그렇지 않은 경우는, 배열 rgdwAxes 의 축과 같은 순서로, 각각의 축으로 대해 1 개의 구조체가 필요하다. 각각의 축으로 1 개의 구조체를 준비 하면, 이펙트는 회전하지 않는다. 배열 rglDirection 에서는 다음의 값을 사용해야 한다.

  • DIEFF_SPHERICAL: 0, 0, ...
  • DIEFF_POLAR: 9000, 0, ...
  • DIEFF_CARTESIAN: 1, 0, ...

이펙트가 DIEFT_CUSTOMFORCE 형이면, 이 멤버는, 커스텀 포스의 파라미터를 정의하는 DICUSTOMFORCE 구조체에의 포인터를 가진다.

이펙트가 DIEFT_PERIODIC 형이면, 이 멤버는, 이펙트의 파라미터를 정의하는 DIPERIODIC 구조체에의 포인터를 가진다.

이펙트가 DIEFT_CONSTANTFORCE 형이면, 이 멤버는, 정수 포스의 파라미터를 정의하는 DICONSTANTFORCE 구조체에의 포인터를 가진다.

이펙트가 DIEFT_RAMPFORCE 형이면, 이 멤버는, 경사 포스의 파라미터를 정의하는 DIRAMPFORCE 구조체에의 포인터를 가진다.

dwStartDelay
IDirectInputEffect::Start 를 호출하고 나서 이펙트를 재생하기 전에, 디바이스가 대기하는 시간 (마이크로 세컨드 단위). 이 값이 제로이면, 이펙트의 재생은 즉시 시작 된다. 이 멤버는, Microsoft® DirectX® 7.0 보다 전의 버젼에는 존재하지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIEFFECTINFO

디바이스로 지원 되는 이펙트에 관한 정보를 돌려주기 위해서(때문에),IDirectInputDevice8::EnumEffects 및 IDirectInputDevice8::GetEffectInfo 메소드로 사용된다.

typedef struct DIEFFECTINFO {
    DWORD dwSize;
    GUID  guid;
    DWORD dwEffType;
    DWORD dwStaticParams;
    DWORD dwDynamicParams;
    TCHAR tszName[MAX_PATH];
} DIEFFECTINFO, *LPDIEFFECTINFO;

typedef const DIEFFECTINFO  *LPCDIEFFECTINFO;

멤버

dwSize
구조체의 바이트 단위의 사이즈. 열거동안에, 어플리케이션은 이 값을 조사해 구조체의 멤버가 몇개 유효한가를 확인할 수 있다. 이 구조체가 IDirectInputDevice8::GetEffectInfo 메소드에게 건네지기 전에, 이 구조체의 멤버를 초기화해야 한다.
guid
이펙트의 식별자.
dwEffType
제로 또는 이하의 값의 언젠가.
DIEFT_ALL
IDirectInputDevice8::EnumEffects 에 대해서만 유효. 타입에 관계없이 모든 이펙트를 열거한다. 이 플래그는, 다른 어느 플래그와도 배합할 수 없다.
DIEFT_CONDITION
이펙트는, 조건을 나타낸다. 조건을 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버는 DICONDITION 구조체 ( 각 축으로 1 개(살))로부터 완성되는 배열을 가리켜,cbTypeSpecificParams 멤버에는 cAxis * sizeof(DICONDITION) 를 설정해야 한다.

모든 디바이스가, 조건의 모든 파라미터를 지원 하는 것은 아니다. 이펙트의 능력 플래그를 체크해, 어느 능력이 사용 가능한가를 조사한다.

이 플래그는,IDirectInputDevice8::EnumEffects 에 건네주어, 열거 대상을 조건으로 제한할 수가 있다.

DIEFT_CONSTANTFORCE
이펙트는, 정수 포스 이펙트를 나타낸다. 정수 포스 이펙트를 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 DICONSTANTFORCE 구조체를 가리켜,cbTypeSpecificParams 멤버에는 sizeof(DICONSTANTFORCE)를 설정해야 한다.

이 플래그는,IDirectInputDevice8::EnumEffects 에 건네주어, 열거 대상을 정수 포스 이펙트에 제한할 수가 있다.

DIEFT_CUSTOMFORCE
이펙트는, 커스텀 포스 이펙트를 나타낸다. 커스텀 포스 이펙트를 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 DICUSTOMFORCE 구조체를 가리켜,cbTypeSpecificParams 멤버에는 sizeof(DICUSTOMFORCE)를 설정해야 한다.

이 플래그는,IDirectInputDevice8::EnumEffects 에 건네주어, 열거 대상을 커스텀 포스 이펙트에 제한할 수가 있다.

DIEFT_DEADBAND
이 조건 이펙트에 대한 이펙트 제네레이터는,lDeadBand 파라미터를 지원 한다.
DIEFT_FFATTACK
이 이펙트에 대한 이펙트 제네레이터는,어택 포락선 파라미터를 지원 한다. 이펙트 제네레이터가 어택을 지원 하고 있지 않으면,DIENVELOPE 구조체의 어택 레벨과 어택 시간의 파라미터를, 이펙트가 무시한다.

DIEFT_FFATTACK 와 DIEFT_FFFADE 가 양쪽 모두 설정되어 있지 않으면, 이펙트는, 포락선을 지원 하지 않고, 지정의 포락선은, 모두 무시된다.

DIEFT_FFFADE
이 이펙트에 대한 이펙트 제네레이터는,페이드 파라미터를 지원 한다. 이펙트 제네레이터가 페이드를 지원 하고 있지 않으면,DIENVELOPE 구조체의 페이드 레벨과 페이드 시간의 파라미터를, 이펙트가 무시한다.

DIEFT_FFATTACK 와 DIEFT_FFFADE 가 양쪽 모두 설정되어 있지 않으면, 이펙트는, 포락선을 지원 하지 않고, 지정의 포락선은, 모두 무시된다.

DIEFT_HARDWARE
이펙트는, 하드웨어 고유의 이펙트를 나타낸다. 하드웨어 고유 이펙트의 사용의 상세한 것에 대하여는, 하드웨어의 문서를 참조할것.

이 플래그를 IDirectInputDevice8::EnumEffects 메소드에 건네주어, 열거 대상을 하드웨어 고유 이펙트에 제한할 수가 있다.

DIEFT_PERIODIC
이펙트는, 주기적 포스 이펙트를 나타낸다. 주기적 포스 이펙트를 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 DIPERIODIC 구조체를 가리켜,cbTypeSpecificParams 멤버에는 sizeof(DIPERIODIC)를 설정해야 한다.

이 플래그는,IDirectInputDevice8::EnumEffects 에 건네주어, 열거 대상을 주기적 포스 이펙트에 제한할 수가 있다.

DIEFT_POSNEGCOEFFICIENTS
이 이펙트에 대한 이펙트 제네레이터는, 조건에 대한 2 개의 계수값, 한편은 정의 축이동, 한편은 부의 축이동에 대한 계수를 지원 한다. 디바이스가 한방향의 계수 밖에 지원 하지 않는 경우,DICONDITION 구조체의 부의 계수가 무시되어 정의 계수가 양쪽 모두의 방향으로 사용된다.
DIEFT_POSNEGSATURATION
이 이펙트에 대한 이펙트 제네레이터는, 정부의 양쪽 모두의 포스 출력에 대한 최대포화를 지원 한다. 디바이스가 한방향의 포화값 밖에 지원 하지 않는 것이면,DICONDITION 구조체의 부의 포화값이 무시되어 정의 포화값이 양쪽 모두의 방향으로 사용된다.
DIEFT_RAMPFORCE
이펙트는, 경사 포스 이펙트를 나타낸다. 경사 포스 이펙트를 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 DIRAMPFORCE 구조체를 가리켜,cbTypeSpecificParams 멤버에는 sizeof(DIRAMPFORCE )를 설정해야 한다.

이 플래그는,IDirectInputDevice8::EnumEffects 에 건네주어, 열거 대상을 경사 포스 이펙트에 제한할 수가 있다.

DIEFT_SATURATION
이 이펙트에 대한 이펙트 제네레이터는, 조건 이펙트의포화를 지원 한다. 이펙트 제네레이터가 포화를 지원 하고 있지 않으면, 조건이 생성한 포스는, 디바이스를 생성할 수 있는 최대 포스에 의해서만 제한된다.
DIEFT_STARTDELAY
이펙트는, 곧바로 시작 되는 것이 아니라 재생까지 지연이 발생한다. 이 지연을 이용해, 이펙트가 차례대로 재생되도록(듯이) 이펙트의 보정을 한다.
dwStaticParams
이펙트가 지원 하는 파라미터를 나타내는 제로 이상의 DIEP_* 값. 예를 들어, DIEP_ENVELOPE 가 설정되어 있으면, 이펙트는 포락선을 지원 한다. 설정 가능한 값의 일람에 대해서는, 「IDirectInputEffect::GetParameters 」를 참조할것.

디바이스가 지원 하고 있지 않는 이펙트 파라미터를 어플리케이션이 사용하려고 해도, 에러는 되지 않는다. 지원되어 있지 않은 파라미터는, 무시되는 것만으로 있다.

이 정보는, 어플리케이션이 특정의 디바이스의 능력에 force feedback를 적합시켜 사용할 수 있도록(듯이) 하기 위해서 제공되고 있다.

dwDynamicParams
이펙트의 재생중에 수정할 수 있는 이펙트 파라미터를 나타내는 제로 이상의 DIEP_* 값. 설정 가능한 값의 일람에 대해서는, 「IDirectInputEffect::GetParameters 」를 참조할것.

이펙트의 재생중에 어플리케이션이 파라미터를 변경하려고 해도, 드라이버가 그 이펙트를 동적으로 수정하는 기능을 지원 하고 있지 않는 경우는, 드라이버는 그 이펙트를 정지해, 파라미터를 갱신해, 그 후에 이펙트를 재개할 수가 있다. 상세한 것에 대하여는, 「IDirectInputEffect::SetParameters 」를 참조할것.

tszName[MAX_PATH]
이펙트의 이름. 예를 들어,"Sawtooth up" 또는 "Constant Force" 등.

주의

dwEffType 플래그로부터 이펙트 타입을 추출하려면 ,DIEFT_GETTYPE 매크로를 사용한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIEFFESCAPE

하드웨어 데이터를 디바이스 드라이버에 직접, 건네주기 위해서(때문에) IDirectInputDevice8::Escape 및 IDirectInputEffect::Escape 메소드로 사용된다.

typedef struct DIEFFESCAPE {
    DWORD  dwSize;
    DWORD  dwCommand;
    LPVOID lpvInBuffer;
    DWORD  cbInBuffer;
    LPVOID lpvOutBuffer;
    DWORD  cbOutBuffer;
} DIEFFESCAPE, *LPDIEFFESCAPE;

멤버

dwSize
구조체의 바이트 단위의 사이즈. 이 멤버는, 구조체가 사용되기 전에 초기화되지 않으면 안 된다.
dwCommand
드라이버의 커멘드 번호. 유효한 커멘드의 일람에 대해서는, 드라이버의 문서를 참조할것.
lpvInBuffer
조작을 실행하는데 필요한 데이터를 저장 하고 있는 버퍼.
cbInBuffer
lpvInBuffer 버퍼의 바이트 단위의 사이즈.
lpvOutBuffer
조작의 출력 데이터가 돌려주어지는 버퍼.
cbOutBuffer
입력 파라미터로서는,lpvOutBuffer 버퍼의 바이트 단위의 사이즈. 출력 파라미터로서는, 커멘드가 실제로 생성 한 바이트수.

주의

각 드라이버는, 다른 escape sequence를 이행 하고 있으므로, 올바른 드라이버와 통신하고 있을지 어떨지는, 어플리케이션 자체가 확인해야 한다. 이것은,DIDEVICEINSTANCE 구조체의 guidFFDriver 멤버와 어플리케이션이 기대하고 있는 값을 비교하는 것으로써 확인할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIENVELOPE

DIEFFECT 구조체가 이펙트에 대한 옵션의포락선 파라미터를 지정하기 위해서 사용한다. 그 포락선의유지 기간 레벨은,DIPERIODIC 구조체의 dwMagnitude 멤버와 DICONSTANTFORCE 구조체의 lMagnitude 멤버가 가리키는 값이다. 유지 시간은,DIEFFECT 구조체의 dwDuration 멤버가 가리키는 값이다.

typedef struct DIENVELOPE {
    DWORD dwSize;
    DWORD dwAttackLevel;
    DWORD dwAttackTime;
    DWORD dwFadeLevel;
    DWORD dwFadeTime;
} DIENVELOPE, *LPDIENVELOPE;

typedef const DIENVELOPE *LPCDIENVELOPE;

멤버

dwSize
구조체의 바이트 단위의 사이즈. 이 멤버는, 구조체가 사용되기 전에 초기화되지 않으면 안 된다.
dwAttackLevel
기선을 기준으로 하는 포락선의 시점에 있어서의 진폭. 기선에 대한 상대값. 0 ~ 10,000 의 범위이다. 이펙트의 타입 고유 데이터가 기선을 지정하고 있지 않으면, 진폭은 제로를 기준으로 한다.
dwAttackTime
유지 기간 레벨에 도달하는데 필요한, 마이크로 세컨드 단위의 시간.
dwFadeLevel
포락선의 종점에서의 진폭. 기선에 대한 상대값. 0 ~ 10,000 의 범위이다. 이펙트의 타입 고유 데이터가 기선을 지정하고 있지 않으면, 진폭은 제로를 기준으로 한다.
dwFadeTime
페이드 레벨에 도달하는데 필요한 마이크로 세컨드 단위의 시간.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIFILEEFFECT

파일에 보존된 force feedback 이펙트의 데이터를 나타낸다. 이 구조체는,IDirectInputDevice8::EnumEffectsInFile 및 IDirectInputDevice8::WriteEffectToFile 메소드로 사용된다.

typedef struct DIFILEEFFECT{
    DWORD       dwSize;
    GUID        GuidEffect;
    LPCDIEFFECT lpDiEffect;
    CHAR        szFriendlyName[MAX_PATH];
}DIFILEEFFECT, *LPDIFILEEFFECT;

멤버

dwSize
구조체의 바이트 단위의 사이즈. 이 멤버는, 구조체가 사용되기 전에 초기화되지 않으면 안 된다.
GuidEffect
이펙트 타입의 일의인 식별자. GUID_ConstantForce 등, Dinput.h 에 정의된 표준 GUID 나, 데자이나에 의해 생성 된 GUID 를 취할 수가 있다.
lpDiEffect
이펙트에 관한 정보를 저장 하는 DIEFFECT 구조체에의 포인터.
szFriendlyName
이펙트의 이름.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIJOYSTATE

죠이스틱 디바이스 상태를 나타낸다. 이 구조체는,IDirectInputDevice8::GetDeviceState 메소드로 사용한다.

typedef struct DIJOYSTATE {
    LONG    lX;
    LONG    lY;
    LONG    lZ;
    LONG    lRx;
    LONG    lRy;
    LONG    lRz;
    LONG    rglSlider[2];
    DWORD   rgdwPOV[4];
    BYTE    rgbButtons[32];
} DIJOYSTATE, *LPDIJOYSTATE;

멤버

lX
보통은 스틱의 좌우의 움직임을 나타내는 x 축.
lY
보통은 스틱의 전후의 움직임을 나타내는 y 축.
lZ
스롯톨 제어를 나타내는 경우가 있는 z 축. 죠이스틱에 이 축이 없으면, 값은 제로이다.
lRx
x 축회전. 죠이스틱에 이 축이 없으면, 값은 제로이다.
lRy
y 축회전. 죠이스틱에 이 축이 없으면, 값은 제로이다.
lRz
z 축회전 (방향타로 불린다). 죠이스틱에 이 축이 없으면, 값은 제로이다.
rglSlider[2]
2 개의 추가축 (이전에는 u 축과 v 축으로 불리고 있었다). 이 값의 의미는 죠이스틱으로 다르다. 이러한 값의 의미에 대한 정보를 취득하려면 ,IDirectInputDevice8::GetObjectInfo 메소드를 사용한다.
rgdwPOV[4]
시점 하트등의 방향 콘트롤러. 이 정도치는, 북쪽으로부터 (유저의 정면측) 시계회전의 열매 각도의 100 배로 나타내진다. 중심 위치는 보통 -1 이라고 보고되지만, 이것에 대해서는 「주의」를 참조할것. 5 개의 위치 밖에 가지지 않는 인디케이터(indicator)의 경우, 콘트롤러의 값은 -1, 0, 9,000, 18,000, 27,000 의 어떤 것이나 1 개의 값을 취한다.
rgbButtons[32]
버튼의 배열. 바이트의 고차원 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정되어 버튼이 업 상태 또는 존재하지 않을 때에는 소거된다.

주의

죠이스틱형의 액세스가 생기도록(듯이) 디바이스를 준비하려면 ,IDirectInputDevice8::SetDataFormat 메소드를 호출해,c_dfDIJoystick 글로벌 데이터 형식 변수를 건네준다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

POV 인디케이터(indicator)의 중심 위치를 65,535 라고 보고하는 드라이버도 있다. POV 인디케이터(indicator)가 중심 위치에 있을지 어떨지는, 다음과 같이 해 확인한다.

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

주 : Microsoft® DirectX® 7 에서는, 일부의 죠이스틱의 슬라이더를 Z 축으로 할당해 그 이후의 코드로 그 멤버로부터 데이터를 취득할 수가 있었다. DirectX 8 에서는, 같은 슬라이더를 rglSlider 배열에 할당한다. 어플리케이션을 DirectX 8 에 이식하는 경우는, 이 점을 고려할 필요가 있다. rglSlider 배열로부터 슬라이더 데이터를 취득하기 위해서 필요한 변경이 있으면 실시하는 것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

DIJOYSTATE2


DIJOYSTATE2

확장 기능이 붙은 죠이스틱 디바이스 상태를 나타낸다. 이 구조체는,IDirectInputDevice8::GetDeviceState 메소드로 사용한다.

typedef struct DIJOYSTATE2 {
    LONG    lX;
    LONG    lY;
    LONG    lZ;
    LONG    lRx;
    LONG    lRy;
    LONG    lRz;
    LONG    rglSlider[2];
    DWORD   rgdwPOV[4];
    BYTE    rgbButtons[128];
    LONG    lVX;
    LONG    lVY;
    LONG    lVZ;
    LONG    lVRx;
    LONG    lVRy;
    LONG    lVRz;
    LONG    rglVSlider[2];
    LONG    lAX;
    LONG    lAY;
    LONG    lAZ;
    LONG    lARx;
    LONG    lARy;
    LONG    lARz;
    LONG    rglASlider[2];
    LONG    lFX;
    LONG    lFY;
    LONG    lFZ;
    LONG    lFRx;
    LONG    lFRy;
    LONG    lFRz;
    LONG    rglFSlider[2];
} DIJOYSTATE2, *LPDIJOYSTATE2;

멤버

lX
보통은 스틱의 좌우의 움직임을 나타내는 x 축.
lY
보통은 스틱의 전후의 움직임을 나타내는 y 축.
lZ
스롯톨 제어를 나타내는 경우가 있는 z 축. 죠이스틱에 이 축이 없으면, 값은 제로이다.
lRx
x 축회전. 죠이스틱에 이 축이 없으면, 값은 제로이다.
lRy
y 축회전. 죠이스틱에 이 축이 없으면, 값은 제로이다.
lRz
z 축회전 (방향타로 불린다). 죠이스틱에 이 축이 없으면, 값은 제로이다.
rglSlider[2]
2 개의 추가축의 값 (이전에는 u 축과 v 축으로 불리고 있었다). 이 값의 의미는 죠이스틱으로 다르다. 이러한 값의 의미에 대한 정보를 취득하려면 ,IDirectInputDevice8::GetObjectInfo 메소드를 사용한다.
rgdwPOV[4]
시점 하트등의 방향 콘트롤러. 이 정도치는, 북쪽으로부터 (유저의 정면측) 시계회전의 열매 각도의 100 배로 나타내진다. 중심 위치는 보통 -1 이라고 보고되지만, 이것에 대해서는 「주의」를 참조할것. 5 개의 위치 밖에 가지지 않는 인디케이터(indicator)의 경우, 콘트롤러의 값은 -1, 0, 9,000, 18,000, 27,000 의 어떤 것이나 1 개의 값을 취한다.
rgbButtons[128]
버튼의 배열. 바이트의 고차원 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정되어 버튼이 업 상태 또는 존재하지 않을 때에는 소거된다.
lVX
x 축의 속도.
lVY
y 축의 속도.
lVZ
z 축의 속도.
lVRx
x 축의 각속도.
lVRy
y 축의 각속도.
lVRz
z 축의 각속도.
rglVSlider[2]
추가축의 속도.
lAX
x 축의 가속도.
lAY
y 축의 가속도.
lAZ
z 축의 가속도.
lARx
x 축의 모퉁이 가속도.
lARy
y 축의 모퉁이 가속도.
lARz
z 축의 모퉁이 가속도.
rglASlider[2]
추가축의 가속도.
lFX
x 축의 포스.
lFY
y 축의 포스.
lFZ
z 축의 포스.
lFRx
x 축의 토르크.
lFRy
y 축의 토르크.
lFRz
z 축의 토르크.
rglFSlider[2]
2 개의 추가축의 포스.

주의

확장 기능부 죠이스틱의 액세스용으로 디바이스를 준비하려면 ,IDirectInputDevice8::SetDataFormat 메소드를 호출해,c_dfDIJoystick2 글로벌 데이터 형식 변수를 건네준다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

POV 인디케이터(indicator)의 중심 위치를 65,535 라고 보고하는 드라이버도 있다. POV 인디케이터(indicator)가 중심 위치에 있을지 어떨지는, 다음과 같이 해 확인한다.

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

주 : Microsoft® DirectX® 7 에서는, 일부의 죠이스틱의 슬라이더를 Z 축으로 할당해 그 이후의 코드로 그 멤버로부터 데이터를 취득할 수가 있었다. DirectX 8 에서는, 같은 슬라이더를 rglSlider 배열에 할당한다. 어플리케이션을 DirectX 8 에 이식하는 경우는, 이 점을 고려할 필요가 있다. rglSlider 배열로부터 슬라이더 데이터를 취득하기 위해서 필요한 변경이 있으면 실시하는 것.

동작환경

  Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.

  Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.

  헤더 : dinput.h 로 선언.

참조

DIJOYSTATE


DIMOUSESTATE

4 개(살)까지의 버튼을 가지는 마우스 디바이스 상태, 또는 마우스 디바이스와 같이 액세스 되는 그 외의 디바이스 상태를 나타낸다. 이 구조체는,IDirectInputDevice8::GetDeviceState 메소드로 사용한다.

typedef struct DIMOUSESTATE {
    LONG lX;
    LONG lY;
    LONG lZ;
    BYTE rgbButtons[4];
} DIMOUSESTATE, *LPDIMOUSESTATE;

멤버

lX
x 축.
lY
y 축.
lZ
보통은 휠을 나타내는 z 축. 마우스에 z 축이 없으면, 이 값은 제로이다.
rgbButtons
버튼의 배열. 바이트의 고차원 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정된다.

주의

마우스형의 액세스가 생기도록(듯이) 디바이스를 준비하려면 ,IDirectInputDevice8::SetDataFormat 메소드를 호출해,c_dfDIMouse 글로벌 데이터 형식 변수를 건네준다.

마우스는 상대축디바이스이므로, 마우스축의 절대축위치는, 단순하게 상대적인 움직임의 누적으로서 요구된다. 따라서, 절대축위치는, 다른 절대축위치와 비교하는 경우를 제외해 무의미가 된다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

DIMOUSESTATE2


DIMOUSESTATE2

8 개(살)까지의 버튼을 가지는 마우스 디바이스 상태, 또는 마우스 디바이스와 같이 액세스 되는 그 외의 디바이스 상태를 나타낸다. 이 구조체는,IDirectInputDevice8::GetDeviceState 메소드로 사용한다.

typedef struct DIMOUSESTATE {
    LONG lX;
    LONG lY;
    LONG lZ;
    BYTE rgbButtons[8];
} DIMOUSESTATE, *LPDIMOUSESTATE;

멤버

lX
x 축.
lY
y 축.
lZ
보통은 휠을 나타내는 z 축. 마우스에 z 축이 없으면, 이 값은 제로이다.
rgbButtons
버튼의 배열. 바이트의 고차원 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정된다.

주의

마우스형의 액세스가 생기도록(듯이) 디바이스를 준비하려면 ,IDirectInputDevice8::SetDataFormat 메소드를 호출해,c_dfDIMouse2 글로벌 데이터 형식 변수를 건네준다.

마우스는 상대축디바이스이므로, 마우스축의 절대축위치는, 단순하게 상대적인 움직임의 누적으로서 요구된다. 따라서, 절대축위치는, 다른 절대축위치와 비교하는 경우를 제외해 무의미가 된다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

DIMOUSESTATE


DIOBJECTDATAFORMAT

IDirectInputDevice8::SetDataFormat 메소드로 사용하는 디바이스 오브젝트의 데이터 형식을 나타낸다.

typedef struct DIOBJECTDATAFORMAT {
    const GUID * pguid;
    DWORD        dwOfs;
    DWORD        dwType;
    DWORD        dwFlags;
} DIOBJECTDATAFORMAT, *LPDIOBJECTDATAFORMAT;

typedef const DIOBJECTDATAFORMAT *LPCDIOBJECTDATAFORMAT;

멤버

pguid
축, 버튼, 또는 그 외의 입력 소스에 대한 일의인 식별자. 데이터 형식의 요구시, 이 멤버를 NULL 로 하면(자), 모든 타입의 오브젝트를 허가하게 된다.
dwOfs
입력 소스의 데이터를 저장 하는 데이터 패킷내의 오프셋(offset). 이 값은, 축 등,DWORD 사이즈의 데이터에 맞도록(듯이), 4 의 배수가 아니면 안된다. 버튼에 대해서는 바이트 정렬에서도 상관없다.
dwType
오브젝트를 나타내는 디바이스 타입. 오브젝트 타입 (축, 버튼등)을 나타내는 이하의 플래그의 편성이며, 중앙의 16 비트는, 오브젝트 인스턴스 번호를 저장 한다. 데이터 형식의 요구시에, 인스턴스 부분에 DIDFT_ANYINSTANCE 를 설정 하면, 모든 인스턴스를 허가할 수가 있다. DIDFT_MAKEINSTANCE (n)로 설정해, 요구를 인스턴스 n 로 한정할 수도 있다. 「주의」를 참조할것.
DIDFT_ABSAXIS
SetDataFormat 메소드에 의해 선택된 오브젝트는, 절대축이 아니면 안된다.
DIDFT_AXIS
SetDataFormat 메소드에 의해 선택된 오브젝트는, 절대축 혹은 상대축이 아니면 안된다.
DIDFT_BUTTON
SetDataFormat 메소드에 의해 선택된 오브젝트는, 푸쉬 버튼 혹은 토글버튼이 아니면 안된다.
DIDFT_FFACTUATOR
SetDataFormat 메소드에 의해 선택된 오브젝트는, force feedback 액츄에이터를 포함하지 않으면 안 된다. 즉, 포스를 이 오브젝트에 적용할 수가 없으면 안 된다.
DIDFT_FFEFFECTTRIGGER
SetDataFormat 메소드에 의해 선택된 오브젝트는, 유효한 force feedback 이펙트 방아쇠가 아니면 안된다.
DIDFT_POV
SetDataFormat 메소드에 의해 선택된 오브젝트는, 시점 콘트롤러가 아니면 안된다.
DIDFT_PSHBUTTON
SetDataFormat 메소드에 의해 선택된 오브젝트는, 푸쉬 버튼이 아니면 안된다.
DIDFT_RELAXIS
SetDataFormat 에 의해 선택된 오브젝트는, 상대축이 아니면 안된다.
DIDFT_TGLBUTTON
SetDataFormat 에 의해 선택된 오브젝트는, 토글버튼이 아니면 안된다.
DIDFT_VENDORDEFINED
SetDataFormat 에 의해 선택된 오브젝트는, 메이커 정의의 타입이 아니면 안된다.
dwFlags
제로 또는 이하의 값의 언젠가.
DIDOI_ASPECTACCEL
SetDataFormat 에 의해 선택된 오브젝트는, 가속도 정보를 보고하지 않으면 안 된다.
DIDOI_ASPECTFORCE
SetDataFormat 에 의해 선택된 오브젝트는, 포스 정보를 보고하지 않으면 안 된다.
DIDOI_ASPECTPOSITION
SetDataFormat 에 의해 선택된 오브젝트는, 위치 정보를 보고하지 않으면 안 된다.
DIDOI_ASPECTVELOCITY
SetDataFormat 에 의해 선택된 오브젝트는, 속도 정보를 보고하지 않으면 안 된다.

주의

데이터 형식은, 각 오브젝트 (축, 버튼등)가 1 개씩 보유하는 복수의 DIOBJECTDATAFORMAT 구조체로 구성된다. 이러한 구조체의 배열은,IDirectInputDevice8::SetDataFormat 에게 건네지는 DIDATAFORMAT 구조체에 저장 된다. 어플리케이션은, 보통,DIOBJECTDATAFORMAT 구조체로부터 되는 배열을 생성 할 필요는 없고,DIOBJECTDATAFORMAT 에 사전 정의되고 있는 설정값인 c_dfDIMouse,c_dfDIMouse2,c_dfDIKeyboard,c_dfDIJoystick, 또는 c_dfDIJoystick2 등의 사전 정의된 데이터 형식 데이터의 어느쪽이든을 사용할 수 있다.

이하의 오브젝트 데이터 형식은, Microsoft® DirectInput® 가 최초의 사용 가능한 축을 선택해, 그 디바이스 데이터의 오프셋(offset) 4 의 위치에 있는 값을 DWORD 로 보고하지 않으면 안 된다고 하는 것을 지정하고 있다.

DIOBJECTDATAFORMAT dfAnyAxis = {
    0,                              // 와일드 카드
    4,                              // 오프셋(offset)
    DIDFT_AXIS | DIDFT_ANYINSTANCE, // 어느 축이라도 좋다.
    0,                              // 어스펙트를 무시한다.
};

이하의 오브젝트 데이터 형식은, 디바이스의 x 축을 디바이스 데이터의 오프셋(offset) 12 의 위치에 DWORD 로 저장 하도록(듯이) 지정하고 있다. 디바이스가 복수의 x 축을 가지고 있는 경우에는, 최초로 사용 가능한 축이 선택된다.

DIOBJECTDATAFORMAT dfAnyXAxis = {
    &GUID_XAxis,                    // X 축을 지정한다.
    12,                             // 오프셋(offset)
    DIDFT_AXIS | DIDFT_ANYINSTANCE, // 어느 X 축이라도 좋다.
    0,                              // 어스펙트를 무시한다.
};

이하의 오브젝트 데이터 형식은, DirectInput 가 최초로 사용 가능한 버튼을 선택해, 디바이스 데이터의 오프셋(offset) 16 의 위치에 있는 바이트의 상위 비트의 값을 보고하도록(듯이) 지정하고 있다.

DIOBJECTDATAFORMAT dfAnyButton = {
    0,                                // 와일드 카드
    16,                               // 오프셋(offset)
    DIDFT_BUTTON | DIDFT_ANYINSTANCE, // 어느 버튼이라도 좋다.
    0,                                // 어스펙트를 무시한다.
};

이하의 오브젝트 데이터 형식은, 디바이스의 버튼 0 을 디바이스 데이터의 오프셋(offset) 18 의 위치에 저장 되고 있는 바이트의 상위 비트로서 보고하도록(듯이) 지정하고 있다.

디바이스에 버튼 0 이 없으면, 이 데이터 형식의 설정은 실패에 끝난다.

DIOBJECTDATAFORMAT dfButton0 = {
    0,                                    // 와일드 카드
    18,                                   // 오프셋(offset)
    DIDFT_BUTTON | DIDFT_MAKEINSTANCE(0), // 버튼 0
    0,                                    // 어스펙트를 무시한다.
};

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIPERIODIC

DIEFT_PERIODIC 로서 마크 되고 있는 이펙트의 타입 고유의 정보를 저장 한다.

이 구조체는, 주기적 이펙트를 나타낸다.

이펙트를 나타내는 단일의 DIPERIODIC 구조체에의 포인터는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버에게 건네진다.

typedef struct DIPERIODIC {
    DWORD dwMagnitude;
    LONG  lOffset;
    DWORD dwPhase;
    DWORD dwPeriod;
} DIPERIODIC, *LPDIPERIODIC;

typedef const DIPERIODIC *LPCDIPERIODIC;

멤버

dwMagnitude
0 ~ 10,000 의 범위에 있는, 이펙트의 매그니튜드. 포락선이 이 이펙트에 적용되고 있으면, 이 값은,유지 기간의 매그니튜드를 나타낸다. 포락선의 적용이 없으면, 이 값은, 이펙트 전체의 진폭을 나타낸다.
lOffset
이펙트의 식별자. 이펙트가 생성하는 포스의 범위는,lOffset - dwMagnitude 로부터 lOffset + dwMagnitude 까지의 사이가 된다. lOffset 멤버의 값은, 이펙트에 적용되는 모든 포락선에 대한 기선으로도 된다.
dwPhase
0 ~ 35,999 의 범위내에 있는 주기적 이펙트의 재생 시작 위치 좌표. 「주의」를 참조할것.
dwPeriod
마이크로 세컨드 단위의 이펙트의 간격.

주의

디바이스 드라이버는 dwPhase 멤버의 모든 값을 지원 하고 있다고는 할 수는 없다. 지원되어 있지 않은 값은, 바로 옆의 지원값에 말 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIPROPCPOINTS

현재의 인스턴스에 calibration 포인트를 설정한다.

typedef struct DIPROPCPOINTS {
    DIPROPHEADER diph;
    DWORD  dwCPointsNum;
    CPOINT cp[MAXCPOINTSNUM];
} DIPROPCPOINTS, *LPDIPROPCPOINTS;

typedef const DIPROPCPOINTS *LPCDIPROPCPOINTS;

멤버

diph
DIPROPHEADER 구조체. 다음과 같이 초기화한다.
멤버 | 값
dwSize | sizeof(DIPROPCPOINTS)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow 멤버가 DIPH_BYID 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 식별자로 한다.

dwHow 멤버가 DIPH_ BYOFFSET 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 데이터 형식 오프셋(offset)로 한다. 예를 들어,c_dfDIMouse 데이터 형식을 선택하면(자), 이 멤버는 DIMOFS_* 값중 어떤 것이나 1 개로 해야 한다.

dwHow 멤버가 DIPH_BYUSAGE 이면, 디바이스는 HID (Human Interface Device)로 한다. 디바이스 오브젝트는, 팩 된 형식의 HID 사용 페이지 및 사용 상황의 값에 의해 식별된다.

이 프로퍼티는 개별의 디바이스 오브젝트 밖에 적용할 수 없기 때문에, DIPH_DEVICE 는 사용할 수 없다.

dwHow | dwObj 멤버의 해석 방법을 지정한다. 상세한 것에 대하여는, 이 표의 dwObj 멤버의 설명을 참조할것.
dwCPointsNum
저장 되고 있는 calibration 포인트의 수. 사용할 수 있는 calibration 포인트의 최대수는 8 이다.
cp[MAXCPOINTSNUM]
calibration 포인트의 배열.


DIPROPDWORD

DWORD 프로퍼티에 액세스 하기 위해서 사용된다.

typedef struct DIPROPDWORD {
    DIPROPHEADER diph;
    DWORD        dwData;
} DIPROPDWORD, *LPDIPROPDWORD;

typedef const DIPROPDWORD *LPCDIPROPDWORD;

멤버

diph
DIPROPHEADER 구조체. 다음과 같이 초기화한다.
멤버 | 값
dwSize | sizeof(DIPROPDWORD)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow 멤버가 DIPH_DEVICE 이면, 이 멤버는 제로로 한다.

dwHow 멤버가 DIPH_BYID 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 식별자로 한다.

dwHow 멤버가 DIPH_ BYOFFSET 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 데이터 형식 오프셋(offset)로 한다. 예를 들어,c_dfDIMouse 데이터 형식을 선택하면(자), 이 멤버는 DIMOFS_* 값중 어떤 것이나 1 개로 해야 한다.

dwHow 멤버가 DIPH_BYUSAGE 이면, 디바이스는 HID (Human Interface Device)로 한다. 디바이스 오브젝트는, 팩 된 형식의 HID 사용 페이지 및 사용 상황의 값에 의해 식별된다.

dwHow | dwObj 멤버의 해석 방법을 지정한다. 상세한 것에 대하여는, 이 표의 dwObj 멤버의 설명을 참조할것.

dwData
설정 또는 취득되는 프로퍼티값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::GetProperty ,IDirectInputDevice8::SetProperty


DIPROPGUIDANDPATH

GUID 나 패스를 나타내는 값을 가지는 프로퍼티에 액세스 하기 위해서 사용된다.

typedef struct DIPROPGUIDANDPATH {
    DIPROPHEADER diph;
    GUID         guidClass;
    WCHAR        wszPath[MAX_PATH];
} DIPROPGUIDANDPATH, *LPDIPROPGUIDANDPATH;

typedef const DIPROPGUIDANDPATH *LPCDIPROPGUIDANDPATH;

멤버

diph
DIPROPHEADER 구조체. 다음과 같이 초기화한다.
멤버 | 값
dwSize | sizeof(DIPROPGUIDANDPATH)
dwHeaderSize | sizeof(DIPROPHEADER )
dwObj | 이 구조체에서는, 이 멤버는 제로로 설정해야 한다.
dwHow | dwObj 멤버의 해석 방법을 지정한다. 이 구조체에서는,dwHow 는 DIPH_DEVICE 으로 한다.

guidClass
오브젝트의 클래스 GUID.
wszPath
돌려주어지는 오브젝트의 패스. 이것은 Unicode 캐릭터 라인이다.

주의

DIPROPGUIDANDPATH 구조체에 관련지을 수 있었던 DIPROP_GUIDANDPATH 프로퍼티를 사용하면(자), 상세 설정의 가능한 어플리케이션은, Microsoft® DirectInput® 로 지원되어 있지 않은 HID (Human Interface Device)에 대해서 조작을 실행할 수 있다.

어플리케이션은,rguidProp 파라미터에 DIPROP_GUIDANDPATH 를 지정해 IDirectInputDevice8::GetProperty 메소드를 호출한다. 디바이스의 클래스 GUID 는,DIPROPGUIDANDPATH 구조체의 guidClass 멤버에 돌려주어진다. 디바이스 인터페이스의 패스는,wszPath 멤버에 돌려주어진다. 그 후, 어플리케이션은 이 패스에 대해서 CreateFile 함수를 호출해, 디바이스에 직접 액세스 할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIPROPHEADER

모든 프로퍼티 구조체의 헤더로서 기능한다.

typedef struct DIPROPHEADER {
    DWORD    dwSize;
    DWORD    dwHeaderSize;
    DWORD    dwObj;
    DWORD    dwHow;
} DIPROPHEADER, *LPDIPROPHEADER;

typedef const DIPROPHEADER *LPCDIPROPHEADER;

멤버

dwSize
포함 하는 구조체의 사이즈. 이 멤버는, 구조체가 사용되기 전에 초기화되지 않으면 안 된다.
dwHeaderSize
DIPROPHEADER 구조체의 사이즈.
dwObj
액세스 하는 프로퍼티가 속하는 오브젝트. 이 멤버로 설정하는 값은,dwHow 멤버로 지정되고 있는 값에 의존한다.
dwHow
dwObj 멤버의 해석 방법을 지정하는 값. 이 값은, 다음의 어느쪽이든 1 개(살)이다.
값 | 의미
DIPH_DEVICE | dwObj 멤버는, 제로로 한다.
DIPH_BYOFFSET | dwObj 멤버는, 액세스 하고 있는 프로퍼티가 속하는 오브젝트의 현재의 데이터 형식에 대한 오프셋(offset)이다.
DIPH_BYUSAGE | dwObj 멤버는, 팩 된 형식의 HID 사용 페이지 및 사용 상황의 값이다.
DIPH_BYID | dwObj 멤버는, 오브젝트 타입 또는 인스턴스 식별자이다. 이 식별자는,IDirectInputDevice8::EnumObjects 메소드를 전회 호출했을 때의 반환값인 DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버에 돌려주어진다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIPROPPOINTER

UINT_PTR 형의 데이터값의 설정과 취득에 사용한다. 보통, 이 값은 액션 맵의 디바이스 오브젝트에 관련지을 수 있었던 어플리케이션 고유의 액션에 관련지을 수 있었던 값이지만, 함수 포인터도 사용할 수 있다.

typedef struct DIPROPPOINTER {
    DIPROPHEADER diph;
    UINT_PTR     uData;
} DIPROPPOINTER, *LPDIPROPPOINTER;

typedef const DIPROPPOINTER *LPCDIPROPPOINTER;

멤버

diph
DIPROPHEADER 구조체. 다음과 같이 초기화한다.
멤버 | 값
dwSize | sizeof(DIPROPPOINTER)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow 멤버가 DIPH_DEVICE 이면, 이 멤버는 제로로 한다.

dwHow 멤버가 DIPH_BYID 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 식별자로 한다.

dwHow 멤버가 DIPH_ BYOFFSET 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 데이터 형식 오프셋(offset)로 한다. 예를 들어,c_dfDIMouse 데이터 형식을 선택하면(자), 이 멤버는 DIMOFS_* 값중 어떤 것이나 1 개로 해야 한다.

dwHow 멤버가 DIPH_BYUSAGE 이면, 디바이스는 HID (Human Interface Device)로 한다. 디바이스 오브젝트는, 팩 된 형식의 HID 사용 페이지 및 사용 상황의 값에 의해 식별된다.

dwHow | dwObj 멤버의 해석 방법을 지정한다. 상세한 것에 대하여는, 이 표의 dwObj 멤버의 설명을 참조할것.
uData
UINT_PTR 형의 어플리케이션 정의의 값이며, 디바이스 컨트롤에 관련지을 수 있었던 uAppData 값 (액션 맵에 있다)을 나타낸다.


DIPROPRANGE

디바이스내의 오브젝트의 범위에 관한 정보를 저장 한다. 이 구조체는,IDirectInputDevice8::GetProperty 및 IDirectInputDevice8::SetProperty 메소드로 DIPROP_RANGE 플래그를 설정해 사용한다.

typedef struct DIPROPRANGE {
    DIPROPHEADER diph;
    LONG         lMin;
    LONG         lMax;
} DIPROPRANGE, *LPDIPROPRANGE;

typedef const DIPROPRANGE *LPCDIPROPRANGE;

멤버

diph
DIPROPHEADER 구조체. 다음과 같이 초기화한다.
멤버 | 값
dwSize | sizeof(DIPROPRANGE)
dwHeaderSize | sizeof(DIPROPHEADER )
dwObj dwHow 멤버가 DIPH_DEVICE 이면, 이 멤버는 제로로 한다.

dwHow 멤버가 DIPH_BYID 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 식별자로 한다.

dwHow 멤버가 DIPH_ BYOFFSET 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 데이터 형식 오프셋(offset)로 한다. 예를 들어,c_dfDIMouse 데이터 형식을 선택 하면, 이 멤버는 DIMOFS_* 값의 어떤 것이나 1 개로 해야 한다. 취득 또는 설정하는 프로퍼티가 속하는 오브젝트의 식별자.

dwHow 멤버가 DIPH_BYUSAGE 이면, 디바이스는 HID (Human Interface Device)로 한다. 디바이스 오브젝트는, 팩 된 형식의 HID 사용 페이지 및 사용 상황의 값에 의해 식별된다.

dwHow | dwObj 멤버의 해석 방법을 지정한다. 상세한 것에 대하여는, 이 표의 dwObj 멤버의 설명을 참조할것.

lMin
범위의 하한. 디바이스의 범위에 제한이 없으면,IDirectInputDevice8::GetProperty 메소드가 돌아올 때, 이 값은 DIPROPRANGE_NOMIN 가 된다.
lMax
범위의 상한. 디바이스의 범위에 제한이 없으면,IDirectInputDevice8::GetProperty 메소드가 돌아올 때, 이 값은 DIPROPRANGE_ NOMAX 가 된다.

주의

범위에 제한이 없는 디바이스에 대한 범위값은, 순환한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice8::GetProperty ,IDirectInputDevice8::SetProperty


DIPROPSTRING

프로퍼티를 캐릭터 라인으로서 취득한다.

typedef struct DIPROPSTRING {
    DIPROPHEADER diph;
    WCHAR        wsz[MAX_PATH];
} DIPROPSTRING, * LPDIPROPSTRING;;

typedef const DIPROPSTRING *LPCDIPROPSTRING;

멤버

diph
DIPROPHEADER 구조체. 다음과 같이 초기화한다.
멤버 | 값
dwSize | sizeof(DIPROPSTRING)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow 멤버가 DIPH_DEVICE 이면, 이 멤버는 제로로 한다.

dwHow 멤버가 DIPH_BYID 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 식별자로 한다.

dwHow 멤버가 DIPH_ BYOFFSET 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 데이터 형식 오프셋(offset)로 한다. 예를 들어,c_dfDIMouse 데이터 형식을 선택하면(자), 이 멤버는 DIMOFS_* 값중 어떤 것이나 1 개로 해야 한다.

dwHow 멤버가 DIPH_BYUSAGE 이면, 디바이스는 HID (Human Interface Device)로 한다. 디바이스 오브젝트는, 팩 된 형식의 HID 사용 페이지 및 사용 상황의 값에 의해 식별된다.

dwHow | dwObj 멤버의 해석 방법을 지정한다. 상세한 것에 대하여는, 이 표의 dwObj 멤버의 설명을 참조할것.

wsz
프로퍼티를 지정 또는 취득하는 Unicode 캐릭터 라인.

주의

DIPROPSTRING 구조체에 관련지을 수 있었던 DIPROP_INSTANCENAME 및 DIPROP_PRODUCTNAME 프로퍼티를 사용하면(자), 상세 설정의 가능한 어플리케이션은, Microsoft® DirectInput® 로 지원되어 있지 않은 HID (Human Interface Device)에 대해서 조작을 실행할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


DIRAMPFORCE

DIEFT_RAMPFORCE 로서 마크 되고 있는 이펙트의 타입 고유의 정보를 저장 한다. 이 구조체는 경사 포스 이펙트를 나타낸다.

이펙트에 관한 단일의 DIRAMPFORCE 구조체에의 포인터는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버에게 건네진다.

typedef struct DIRAMPFORCE {
    LONG lStart;
    LONG lEnd;
} DIRAMPFORCE, *LPDIRAMPFORCE;

typedef const DIRAMPFORCE *LPCDIRAMPFORCE;

멤버

lStart
-10, 000 ~ 10.000 의 범위에 있는, 이펙트의 시점의 매그니튜드.
lEnd
-10, 000 ~ 10.000 의 범위에 있는, 이펙트의 종점의 매그니튜드.

주의

경사 포스 이펙트의 dwDuration 는, INFINITE 에는 할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dinput.h 로 선언.


디바이스 정수

여기에서는, 키, 버튼 및 축으로 대하는 데이터를 해석하는데 사용하는 정수에 관한 레퍼런스를 제공한다.

  • 키보드 디바이스 정수
  • DirectInput 와 일본어 키보드
  • 마우스 디바이스 정수
  • 죠이스틱 디바이스 정수


키보드 디바이스 정수

Dinput.h 에 정의되고 있는 키보드 디바이스 정수는, 키보드 디바이스의 데이터 패킷 (256 바이트 배열) 내에서의 오프셋(offset)를 나타낸다. 지정의 오프셋(offset) 위치의 데이터는, 키보드 키에 관련지을 수 있고 있다. 보통, 그러한 값은,DIDEVICEOBJECTDATA ,DIOBJECTDATAFORMAT , 또는 DIDEVICEOBJECTINSTANCE 구조체의 dwOfs 멤버 중(안)에서 사용되든가, 혹은 배열의 기법을 사용해 배열내의 데이터에 액세스 하면나무의 인덱스로서 사용된다.

표준 키보드 디바이스 정수는, 이하대로이다.

정수 | 메모
DIK_0 | 메인 키보드상
DIK_1 | 메인 키보드상
DIK_2 | 메인 키보드상
DIK_3 | 메인 키보드상
DIK_4 | 메인 키보드상
DIK_5 | 메인 키보드상
DIK_6 | 메인 키보드상
DIK_7 | 메인 키보드상
DIK_8 | 메인 키보드상
DIK_9 | 메인 키보드상
DIK_A |
DIK_ABNT_C1 | 브라질어 키보드의 숫자 패드상
DIK_ABNT_C2 | 브라질어 키보드의 숫자 패드상
DIK_ADD | 숫자 패드 위에의 플러스 기호 (+)
DIK_APOSTROPHE |
DIK_APPS | 어플리케이션 키
DIK_AT | 일본어 키보드상
DIK_AX | 일본어 키보드상
DIK_B |
DIK_BACK | BackSpace
DIK_BACKSLASH |
DIK_C |
DIK_CALCULATOR |
DIK_CAPITAL | Caps Lock
DIK_COLON | 일본어 키보드상
DIK_COMMA |
DIK_CONVERT | 일본어 키보드상
DIK_D |
DIK_DECIMAL | 숫자 패드 위에의 피리어드 (소수점)
DIK_DELETE |
DIK_DIVIDE | 숫자 패드 위에의 slash (/)
DIK_DOWN | 하 커서 키
DIK_E |
DIK_END |
DIK_EQUALS | 메인 키보드상
DIK_ESCAPE |
DIK_F |
DIK_F1 |
DIK_F2 |
DIK_F3 |
DIK_F4 |
DIK_F5 |
DIK_F6 |
DIK_F7 |
DIK_F8 |
DIK_F9 |
DIK_F10 |
DIK_F11 |
DIK_F12 |
DIK_F13 | NEC PC-98 일본어 키보드상
DIK_F14 | NEC PC-98 일본어 키보드상
DIK_F15 | NEC PC-98 일본어 키보드상
DIK_G |
DIK_GRAVE | 아크상라브 (`) 키
DIK_H |
DIK_HOME |
DIK_I |
DIK_INSERT |
DIK_J |
DIK_K |
DIK_KANA | 일본어 키보드상
DIK_KANJI | 일본어 키보드상
DIK_L |
DIK_LBRACKET | 왼쪽각이나 와 [
DIK_LCONTROL | 왼쪽 Ctrl 키
DIK_LEFT | 왼쪽 커서 키
DIK_LMENU | 왼쪽 Alt 키
DIK_LSHIFT | 왼쪽 Shift 키
DIK_LWIN | 왼쪽 Microsoft® Windows® 키
DIK_M |
DIK_MAIL |
DIK_MEDIASELECT | 시스템으로 지원 되고 있는 미디어 플레이어의 선택을 표시하는, 미디어 선택 키.
DIK_MEDIASTOP |
DIK_MINUS | 메인 키보드상
DIK_MULTIPLY | 숫자 패드 위에의 asterisk (*)
DIK_MUTE |
DIK_MYCOMPUTER |
DIK_N |
DIK_NEXT | PageDown 키
DIK_NEXTTRACK | 다음의 트럭
DIK_NOCONVERT | 일본어 키보드상
DIK_NUMLOCK |
DIK_NUMPAD0 |
DIK_NUMPAD1 |
DIK_NUMPAD2 |
DIK_NUMPAD3 |
DIK_NUMPAD4 |
DIK_NUMPAD5 |
DIK_NUMPAD6 |
DIK_NUMPAD7 |
DIK_NUMPAD8 |
DIK_NUMPAD9 |
DIK_NUMPADCOMMA | NEC PC-98 일본어 키보드 숫자 패드상
DIK_NUMPADENTER |
DIK_NUMPADEQUALS | NEC PC-98 일본어 키보드 숫자 패드상
DIK_O |
DIK_OEM_102 | 영어 키보드 및 독일어 키보드상
DIK_P |
DIK_PAUSE |
DIK_PERIOD | 메인 키보드상
DIK_PLAYPAUSE |
DIK_POWER |
DIK_PREVTRACK | 전의 트럭, 일본어 키보드의 서컴프렉스
DIK_PRIOR | PageUp 키
DIK_Q |
DIK_R |
DIK_RBRACKET | 오른쪽각이나 와 ]
DIK_RCONTROL | 오른쪽 Ctrl 키
DIK_RETURN | 메인 키보드 위에의 Enter 키
DIK_RIGHT | 오른쪽 커서 키
DIK_RMENU | 오른쪽 Alt 키
DIK_RSHIFT | 오른쪽 Shift 키
DIK_RWIN | 오른쪽 Windows 키
DIK_S |
DIK_SCROLL | ScrollLock
DIK_SEMICOLON |
DIK_SLASH | 메인 키보드 위에의 slash (/)
DIK_SLEEP |
DIK_SPACE | 스페이스 키
DIK_STOP | NEC PC-98 일본어 키보드상
DIK_SUBTRACT | 숫자 패드 위에의 마이너스 기호 (-)
DIK_SYSRQ |
DIK_T |
DIK_TAB |
DIK_U |
DIK_UNDERLINE | NEC PC-98 일본어 키보드상
DIK_UNLABELED | 일본어 키보드상
DIK_UP | 상 커서 키
DIK_V |
DIK_VOLUMEDOWN |
DIK_VOLUMEUP |
DIK_W |
DIK_WAKE |
DIK_WEBBACK |
DIK_WEBFAVORITES | Microsoft Internet Explorer 의 [마음에 드는] 리스트, Windows 의 [Favorites] 폴더, 또는 Netscape 의 북마크 리스트를 표시한다.
DIK_WEBFORWARD |
DIK_WEBHOME |
DIK_WEBREFRESH |
DIK_WEBSEARCH |
DIK_WEBSTOP |
DIK_X |
DIK_Y |
DIK_YEN | 일본어 키보드상
DIK_Z |

이하의 대체명도 사용 가능하다.

대체명 | 보통명 | 메모
DIK_BACKSPACE | DIK_BACK | BackSpace
DIK_CAPSLOCK | DIK_CAPITAL | Caps Lock
DIK_CIRCUMFLEX | DIK_PREVTRACK | 일본어 키보드상
DIK_DOWNARROW | DIK_DOWN | 커서 키 패드상
DIK_LALT | DIK_LMENU | 왼쪽 Alt 키
DIK_LEFTARROW | DIK_LEFT | 커서 키 패드상
DIK_NUMPADMINUS | DIK__SUBTRACT | 숫자 패드 위에의 마이너스 기호 (-)
DIK_NUMPADPERIOD | DIK_DECIMAL | 숫자 패드 위에의 피리어드 (소수점)
DIK_NUMPADPLUS | DIK_ADD | 숫자 패드 위에의 플러스 기호 (+)
DIK_NUMPADSLASH | DIK__DIVIDE | 숫자 패드 위에의 slash (/)
DIK_NUMPADSTAR | DIK_MULTIPLY | 숫자 패드 위에의 asterisk (*)
DIK_PGDN | DIK_NEXT | 커서 키 패드상
DIK_PGUP | DIK_PRIOR | 커서 키 패드상
DIK_RALT | DIK_RMENU | 오른쪽 Alt 키
DIK_RIGHTARROW | DIK_RIGHT | 커서 키 패드상
DIK_UPARROW | DIK_UP | 커서 키 패드상

일본어 키보드에 대해서는, 「DirectInput 와 일본어 키보드」를 참조할것.


DirectInput 와 일본어 키보드

이하에, 표준의 US 키보드에는 없지만, 일본어 키보드로 사용 가능한 확장 키와 US 키보드에서는 사용 가능하지만, 많은 일본어 키보드에는 없는 키의 일람을 나타낸다.

Microsoft® Windows® 2000 또는 다른 operating system 위에의 (NEC PC-98 와 같은) 키보드에서는, DIK_CAPSLOCK, DIK_KANJI, 및 DIK_KANA 키는 토글버튼이며, 푸쉬 버튼은 아니다. 이러한 키는, 최초로 밀렸을 때에 다운 이벤트를 생성해, 2 번째에 밀렸을 때에 업 이벤트를 생성한다.

일본어 키보드 | 확장 키 | 빠지는 키
DOS/V 106, NEC PC-98 106 | DIK_AT, DIK_CIRCUMFLEX, DIK_COLON, DIK_CONVERT, DIK_KANA, DIK_KANJI, DIK_NOCONVERT, DIK_YEN | DIK_APOSTROPHE, DIK_EQUALS, DIK_GRAVE
NEC PC-98 | DIK_AT, DIK_CIRCUMFLEX, DIK_COLON, DIK_F13, DIK_F14, DIK_F15, DIK_KANA, DIK_KANJI, DIK_NOCONVERT, DIK_NUMPADCOMMA, DIK_NUMPADEQUALS, DIK_STOP, DIK_UNDERLINE, DIK_YEN | DIK_APOSTROPHE, DIK_BACKSLASH, DIK_EQUALS, DIK_GRAVE, DIK_NUMLOCK, DIK_NUMPADENTER, DIK_RCONTROL, DIK_RMENU, DIK_RSHIFT, DIK_SCROLL
AX | DIK_AX, DIK_CONVERT, DIK_KANJI, DIK_NOCONVERT, DIK_YEN | DIK_RCONTROL, DIK_RMENU
J-3100 | DIK_KANA, DIK_KANJI, DIK_NOLABEL, DIK_YEN | DIK_RCONTROL, DIK_RMENU


마우스 디바이스 정수

Dinput.h 에 정의되고 있는 마우스 디바이스 정수는, 마우스 디바이스의 데이터 패킷인 DIMOUSESTATE 또는 DIMOUSESTATE2 구조체에 대한 오프셋(offset)를 나타낸다. 지정의 오프셋(offset) 위치에 있는 데이터는, 디바이스 오브젝트 (버튼 또는 축)에 관련지을 수 있고 있다. 보통, 그러한 값은,DIDEVICEOBJECTDATA ,DIOBJECTDATAFORMAT , 또는 DIDEVICEOBJECTINSTANCE 구조체의 dwOfs 멤버에 사용된다.

마우스 디바이스 정수는, 이하대로이다.

정수 | 메모
DIMOFS_BUTTON0 |
DIMOFS_BUTTON1 |
DIMOFS_BUTTON2 |
DIMOFS_BUTTON3
DIMOFS_BUTTON4 | DIMOUSESTATE2 마셔
DIMOFS_BUTTON5 | DIMOUSESTATE2 마셔
DIMOFS_BUTTON6 | DIMOUSESTATE2 마셔
DIMOFS_BUTTON7 | DIMOUSESTATE2 마셔
DIMOFS_X |
DIMOFS_Y
DIMOFS_Z |


죠이스틱 디바이스 정수

죠이스틱 디바이스 정수는, 죠이스틱 디바이스의 데이터 패킷인 DIJOYSTATE 구조체에 대한 오프셋(offset)를 나타낸다. 지정의 오프셋(offset)에 있는 데이터는, 디바이스 오브젝트, 즉 버튼 또는 축과 관련지을 수 있고 있다. 보통, 그러한 값은,DIDEVICEOBJECTDATA ,DIOBJECTDATAFORMAT , 또는 DIDEVICEOBJECTINSTANCE 구조체의 dwOfs 멤버에 사용된다.

다음의 매크로는, 항상 상태를 나타내는 데이터의 오프셋(offset)를 돌려주지만, 그 데이터는 DIJOYSTATE 구조체의 선두에 관련지을 수 있었던 특정의 버튼 또는 축으로야는 정해진다.

정수 | 디바이스 오브젝트
DIJOFS_BUTTON0 로부터 DIJOFS_BUTTON31 또는 DIJOFS_BUTTON(n) | 버튼
DIJOFS_POV(n) | 시점 인디케이터(indicator)
DIJOFS_RX | x 축회전
DIJOFS_RY | y 축회전
DIJOFS_RZ | z 축회전 (방향타)
DIJOFS_X | x 축
DIJOFS_Y | y 축
DIJOFS_Z | z 축
DIJOFS_SLIDER(n) | 슬라이더축


액션 매핑 정수

여기에서는, 어플리케이션의 장르와 각 장르내의 액션에 맵 된 컨트롤용으로, Dinput.h 에 정의된 정수의 레퍼런스를 제공한다.

DIAXIS_FIGHTINGH_MOVE 등의 컨트롤 정수는,DIACTION 구조체의 dwSemantic 멤버 중(안)에서, 컨트롤을 어플리케이션내의 액션에 관련짓기 위해서(때문에) 사용된다.

DIVIRTUAL_FIGHTING_HAND2HAND 등의 장르 정수는,DIACTIONFORMAT 구조체의 dwGenre 멤버 중(안)에서 사용된다.

액션 매핑 정수는, 다음의 카테고리의 어플리케이션 장르용으로 제공되고 있다.

  • 액션 장르
  • 아케이드 장르
  • CAD 장르
  • 컨트롤 장르
  • 드라이빙 장르
  • 플라이트 장르
  • 스포츠 장르
  • 스트래터지 장르

DIACTION 구조체의 dwSemantic 멤버를 사용해, 액션을 가상 컨트롤은 아니고 특정의 디바이스 오브젝트에 맵 할 수가 있다. 디바이스 오브젝트 정수는, 다음의 카테고리에 제공되고 있다.

  • 키보드 매핑 정수
  • 마우스 매핑 정수
  • DirectPlay 음성 매핑 정수
  • 임의 컨트롤 정수


액션 장르

다음의 장르에는, 전투 게임이나 액션 게임용의 컨트롤이 포함된다.

  • 격투
  • 슈팅
  • 비대면형의 액션


격투

DIVIRTUAL_FIGHTING_HAND2HAND 장르에는, 소총을 사용하지 않는 대면형의 격투 게임의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_FIGHTINGH_LATERAL
DIAXIS_FIGHTINGH_MOVE
DIBUTTON_FIGHTINGH_BLOCK
DIBUTTON_FIGHTINGH_CROUCH
DIBUTTON_FIGHTINGH_JUMP
DIBUTTON_FIGHTINGH_KICK
DIBUTTON_FIGHTINGH_MENU
DIBUTTON_FIGHTINGH_PUNCH
DIBUTTON_FIGHTINGH_SPECIAL1
DIBUTTON_FIGHTINGH_SPECIAL2

우선 순위 2 의 컨트롤
DIAXIS_FIGHTINGH_ROTATE
DIBUTTON_FIGHTINGH_BACKWARD_LINK
DIBUTTON_FIGHTINGH_DEVICE
DIBUTTON_FIGHTINGH_DISPLAY
DIBUTTON_FIGHTINGH_DODGE
DIBUTTON_FIGHTINGH_FORWARD_LINK
DIBUTTON_FIGHTINGH_LEFT_LINK
DIBUTTON_FIGHTINGH_RIGHT_LINK
DIBUTTON_FIGHTINGH_PAUSE
DIBUTTON_FIGHTINGH_SELECT
DIHATSWITCH_FIGHTINGH_SLIDE


슈팅

DIVIRTUAL_FIGHTING_FPS 장르에는, 소총을 사용하는 대면형의 전투 게임의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_FPS_LOOKUPDOWN
DIAXIS_FPS_MOVE
DIAXIS_FPS_ROTATE
DIBUTTON_FPS_APPLY
DIBUTTON_FPS_CROUCH
DIBUTTON_FPS_FIRE
DIBUTTON_FPS_JUMP
DIBUTTON_FPS_MENU
DIBUTTON_FPS_SELECT
DIBUTTON_FPS_STRAFE
DIBUTTON_FPS_WEAPONS

우선 순위 2 의 컨트롤
DIAXIS_FPS_SIDESTEP
DIBUTTON_FPS_BACKWARD_LINK
DIBUTTON_FPS_DEVICE
DIBUTTON_FPS_DISPLAY
DIBUTTON_FPS_DODGE
DIBUTTON_FPS_FIRESECONDARY
DIBUTTON_FPS_FORWARD_LINK
DIBUTTON_FPS_GLANCE_DOWN_LINK
DIBUTTON_FPS_GLANCE_UP_LINK
DIBUTTON_FPS_GLANCEL
DIBUTTON_FPS_GLANCER
DIBUTTON_FPS_PAUSE
DIBUTTON_FPS_ROTATE_LEFT_LINK
DIBUTTON_FPS_ROTATE_RIGHT_LINK
DIHATSWITCH_FPS_GLANCE


비대면형의 액션

DIVIRTUAL_FIGHTING_THIRDPERSON 장르에는, 비대면형의 액션 게임의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_TPS_MOVE
DIAXIS_TPS_TURN
DIBUTTON_TPS_ACTION
DIBUTTON_TPS_JUMP
DIBUTTON_TPS_MENU
DIBUTTON_TPS_RUN
DIBUTTON_TPS_SELECT
DIBUTTON_TPS_USE

우선 순위 2 의 컨트롤
DIAXIS_TPS_STEP
DIBUTTON_TPS_BACKWARD_LINK
DIBUTTON_TPS_DEVICE
DIBUTTON_TPS_DODGE
DIBUTTON_TPS_FORWARD_LINK
DIBUTTON_TPS_GLANCE_DOWN_LINK
DIBUTTON_TPS_GLANCE_LEFT_LINK
DIBUTTON_TPS_GLANCE_RIGHT_LINK
DIBUTTON_TPS_GLANCE_UP_LINK
DIBUTTON_TPS_INVENTORY
DIBUTTON_TPS_PAUSE
DIBUTTON_TPS_STEPLEFT
DIBUTTON_TPS_STEPRIGHT
DIBUTTON_TPS_TURN_LEFT_LINK
DIBUTTON_TPS_TURN_RIGHT_LINK
DIBUTTON_TPS_VIEW
DIHATSWITCH_TPS_GLANCE


아케이드 장르

다음의 장르에는, 위험한 상황속에서 캐릭터를 움직이는 것을 목적으로 하는, 아케이드형 게임의 컨트롤이 포함된다.

  • 플랫폼
  • 사이드 투 사이드


플랫폼

DIVIRTUAL_ARCADE_PLATFORM 장르에는, 아케이드형 게임의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_ARCADEP_LATERAL
DIAXIS_ARCADEP_MOVE
DIBUTTON_ARCADEP_CROUCH
DIBUTTON_ARCADEP_FIRE
DIBUTTON_ARCADEP_JUMP
DIBUTTON_ARCADEP_MENU
DIBUTTON_ARCADEP_SELECT
DIBUTTON_ARCADEP_SPECIAL

우선 순위 2 의 컨트롤
DIBUTTON_ARCADEP_BACK_LINK
DIBUTTON_ARCADEP_DEVICE
DIBUTTON_ARCADEP_FIRESECONDARY
DIBUTTON_ARCADEP_FORWARD_LINK
DIBUTTON_ARCADEP_LEFT_LINK
DIBUTTON_ARCADEP_PAUSE
DIBUTTON_ARCADEP_RIGHT_LINK
DIBUTTON_ARCADEP_VIEW_DOWN_LINK
DIBUTTON_ARCADEP_VIEW_LEFT_LINK
DIBUTTON_ARCADEP_VIEW_RIGHT_LINK
DIBUTTON_ARCADEP_VIEW_UP_LINK
DIHATSWITCH_ARCADEP_VIEW


사이드 투 사이드

DIVIRTUAL_ARCADE_SIDE2SIDE 장르에는, 아케이드형 2 차원 게임의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_ARCADES_LATERAL
DIAXIS_ARCADES_MOVE
DIBUTTON_ARCADES_ATTACK
DIBUTTON_ARCADES_CARRY
DIBUTTON_ARCADES_MENU
DIBUTTON_ARCADES_SELECT
DIBUTTON_ARCADES_SPECIAL
DIBUTTON_ARCADES_THROW

우선 순위 2 의 컨트롤
DIBUTTON_ARCADES_BACK_LINK
DIBUTTON_ARCADES_DEVICE
DIBUTTON_ARCADES_FORWARD_LINK
DIBUTTON_ARCADES_LEFT_LINK
DIBUTTON_ARCADES_PAUSE
DIBUTTON_ARCADES_RIGHT_LINK
DIBUTTON_ARCADES_VIEW_DOWN_LINK
DIBUTTON_ARCADES_VIEW_LEFT_LINK
DIBUTTON_ARCADES_VIEW_RIGHT_LINK
DIBUTTON_ARCADES_VIEW_UP_LINK
DIHATSWITCH_ARCADES_VIEW


CAD 장르

다음의 장르에는, CAD (Computer-Assisted Drafting) 어플리케이션용의 컨트롤이 포함된다.

  • 2D 오브젝트
  • 3D 모델
  • 3D 네비게이션
  • 3D 오브젝트


2D 오브젝트

DIVIRTUAL_CAD_2DCONTROL 장르에는, 2 차원의 설계 환경에서 오브젝트의 선택, 이동을 행하기 위한 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_2DCONTROL_LATERAL
DIAXIS_2DCONTROL_MOVE
DIAXIS_2DCONTROL_INOUT
DIBUTTON_2DCONTROL_MENU
DIBUTTON_2DCONTROL_SELECT
DIBUTTON_2DCONTROL_SPECIAL
DIBUTTON_2DCONTROL_SPECIAL1
DIBUTTON_2DCONTROL_SPECIAL2

우선 순위 2 의 컨트롤
DIAXIS_2DCONTROL_ROTATEZ
DIBUTTON_2DCONTROL_DEVICE
DIBUTTON_2DCONTROL_DISPLAY
DIBUTTON_2DCONTROL_PAUSE
DIHATSWITCH_2DCONTROL_HATSWITCH


3D 모델

DIVIRTUAL_CAD_MODEL 장르에는, 3 차원 오브젝트 모델링용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_CADM_LATERAL
DIAXIS_CADM_MOVE
DIAXIS_CADM_INOUT
DIBUTTON_CADM_MENU
DIBUTTON_CADM_SELECT
DIBUTTON_CADM_SPECIAL
DIBUTTON_CADM_SPECIAL1
DIBUTTON_CADM_SPECIAL2

우선 순위 2 의 컨트롤
DIAXIS_CADM_ROTATEX
DIAXIS_CADM_ROTATEY
DIAXIS_CADM_ROTATEZ
DIBUTTON_CADM_DEVICE
DIBUTTON_CADM_DISPLAY
DIBUTTON_CADM_PAUSE
DIHATSWITCH_CADM_HATSWITCH


3D 네비게이션

DIVIRTUAL_CAD_FLYBY 장르에는, 3 차원 환경의 프라이즈 루 내비게이션용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_CADF_LATERAL
DIAXIS_CADF_MOVE
DIAXIS_CADF_INOUT
DIBUTTON_CADF_MENU
DIBUTTON_CADF_SELECT
DIBUTTON_CADF_SPECIAL
DIBUTTON_CADF_SPECIAL1
DIBUTTON_CADF_SPECIAL2

우선 순위 2 의 컨트롤
DIAXIS_CADF_ROTATEX
DIAXIS_CADF_ROTATEY
DIAXIS_CADF_ROTATEZ
DIBUTTON_CADF_DEVICE
DIBUTTON_CADF_DISPLAY
DIBUTTON_CADF_PAUSE
DIHATSWITCH_CADF_HATSWITCH


3D 오브젝트

DIVIRTUAL_CAD_3DCONTROL 장르에는, 3 차원의 설계 환경에서 오브젝트의 선택, 이동을 행하기 위한 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_3DCONTROL_LATERAL
DIAXIS_3DCONTROL_MOVE
DIAXIS_3DCONTROL_INOUT
DIBUTTON_3DCONTROL_MENU
DIBUTTON_3DCONTROL_SELECT
DIBUTTON_3DCONTROL_SPECIAL
DIBUTTON_3DCONTROL_SPECIAL1
DIBUTTON_3DCONTROL_SPECIAL2

우선 순위 2 의 컨트롤
DIAXIS_3DCONTROL_ROTATEX
DIAXIS_3DCONTROL_ROTATEY
DIAXIS_3DCONTROL_ROTATEZ
DIBUTTON_3DCONTROL_DEVICE
DIBUTTON_3DCONTROL_DISPLAY
DIBUTTON_3DCONTROL_PAUSE
DIHATSWITCH_3DCONTROL_HATSWITCH


컨트롤 장르

다음의 장르에는, Web 브라우저와 리모트 콘트롤 디바이스로 사용되는 컨트롤이 포함된다.

  • 브라우저
  • 리모트 콘트롤


브라우저

DIVIRTUAL_BROWSER_CONTROL 장르에는, Web 브라우저용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_BROWSER_LATERAL
DIAXIS_BROWSER_MOVE
DIAXIS_BROWSER_VIEW
DIBUTTON_BROWSER_MENU
DIBUTTON_BROWSER_REFRESH
DIBUTTON_BROWSER_SELECT

우선 순위 2 의 컨트롤
DIBUTTON_BROWSER_DEVICE
DIBUTTON_BROWSER_FAVORITES
DIBUTTON_BROWSER_HISTORY
DIBUTTON_BROWSER_HOME
DIBUTTON_BROWSER_NEXT
DIBUTTON_BROWSER_PAUSE
DIBUTTON_BROWSER_PREVIOUS
DIBUTTON_BROWSER_PRINT
DIBUTTON_BROWSER_SEARCH
DIBUTTON_BROWSER_STOP


리모트 콘트롤

DIVIRTUAL_REMOTE_CONTROL 장르에는, 미디어 플레이어등의 장치로 사용되는 리모트 콘트롤 디바이스용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_REMOTE_SLIDER
DIBUTTON_REMOTE_CHANGE
DIBUTTON_REMOTE_CUE
DIBUTTON_REMOTE_MENU
DIBUTTON_REMOTE_MUTE
DIBUTTON_REMOTE_PLAY
DIBUTTON_REMOTE_RECORD
DIBUTTON_REMOTE_REVIEW
DIBUTTON_REMOTE_SELECT

우선 순위 2 의 컨트롤
DIAXIS_REMOTE_SLIDER2
DIBUTTON_REMOTE_ADJUST
DIBUTTON_REMOTE_CABLE
DIBUTTON_REMOTE_CD
DIBUTTON_REMOTE_DEVICE
DIBUTTON_REMOTE_DIGIT0
DIBUTTON_REMOTE_DIGIT1
DIBUTTON_REMOTE_DIGIT2
DIBUTTON_REMOTE_DIGIT3
DIBUTTON_REMOTE_DIGIT4
DIBUTTON_REMOTE_DIGIT5
DIBUTTON_REMOTE_DIGIT6
DIBUTTON_REMOTE_DIGIT7
DIBUTTON_REMOTE_DIGIT8
DIBUTTON_REMOTE_DIGIT9
DIBUTTON_REMOTE_DVD
DIBUTTON_REMOTE_PAUSE
DIBUTTON_REMOTE_TUNER
DIBUTTON_REMOTE_TV
DIBUTTON_REMOTE_VCR


드라이빙 장르

다음의 장르는, 플레이어가 레이싱이나 전투로 차를 제어하는 게임에서 사용된다.

  • 컴배트 레이싱
  • 로보트 전투
  • 레이싱
  • 탱크


컴배트 레이싱

DIVIRTUAL_DRIVING_COMBAT 장르에는, 전투가 있는 탈 것 레이스 게임용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_DRIVINGC_ACCELERATE
DIAXIS_DRIVINGC_BRAKE
DIAXIS_DRIVINGC_STEER
DIBUTTON_DRIVINGC_FIRE
DIBUTTON_DRIVINGC_MENU
DIBUTTON_DRIVINGC_TARGET
DIBUTTON_DRIVINGC_WEAPONS

우선 순위 2 의 컨트롤
DIAXIS_DRIVINGC_ACCEL_AND_BRAKE
DIBUTTON_DRIVINGC_ACCELERATE_LINK
DIBUTTON_DRIVINGC_AIDS
DIBUTTON_DRIVINGC_BRAKE
DIBUTTON_DRIVINGC_DASHBOARD
DIBUTTON_DRIVINGC_DEVICE
DIBUTTON_DRIVINGC_FIRESECONDARY
DIBUTTON_DRIVINGC_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGC_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGC_PAUSE
DIBUTTON_DRIVINGC_SHIFTDOWN
DIBUTTON_DRIVINGC_SHIFTUP
DIBUTTON_DRIVINGC_STEER_LEFT_LINK
DIBUTTON_DRIVINGC_STEER_RIGHT_LINK
DIHATSWITCH_DRIVINGC_GLANCE


로보트 전투

DIVIRTUAL_DRIVING_MECHA 장르에는, 로보트 전투 게임에 있어서의 보행로봇 (맥크) 용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_MECHA_ROTATE
DIAXIS_MECHA_STEER
DIAXIS_MECHA_THROTTLE
DIAXIS_MECHA_TORSO
DIBUTTON_MECHA_FIRE
DIBUTTON_MECHA_JUMP
DIBUTTON_MECHA_MENU
DIBUTTON_MECHA_REVERSE
DIBUTTON_MECHA_TARGET
DIBUTTON_MECHA_WEAPONS
DIBUTTON_MECHA_ZOOM

우선 순위 2 의 컨트롤
DIBUTTON_MECHA_BACK_LINK
DIBUTTON_MECHA_CENTER
DIBUTTON_MECHA_DEVICE
DIBUTTON_MECHA_FASTER_LINK
DIBUTTON_MECHA_FIRESECONDARY
DIBUTTON_MECHA_FORWARD_LINK
DIBUTTON_MECHA_LEFT_LINK
DIBUTTON_MECHA_PAUSE
DIBUTTON_MECHA_RIGHT_LINK
DIBUTTON_MECHA_ROTATE_LEFT_LINK
DIBUTTON_MECHA_ROTATE_RIGHT_LINK
DIBUTTON_MECHA_SLOWER_LINK
DIBUTTON_MECHA_VIEW
DIHATSWITCH_MECHA_GLANCE


레이싱

DIVIRTUAL_DRIVING_RACE 장르에는, 전투가 없는 자동차 레이스 게임용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_DRIVINGR_ACCELERATE
DIAXIS_DRIVINGR_BRAKE
DIAXIS_DRIVINGR_STEER
DIBUTTON_DRIVINGR_MENU
DIBUTTON_DRIVINGR_SHIFTDOWN
DIBUTTON_DRIVINGR_SHIFTUP
DIBUTTON_DRIVINGR_VIEW

우선 순위 2 의 컨트롤
DIAXIS_DRIVINGR_ACCEL_AND_BRAKE
DIBUTTON_DRIVINGR_ACCELERATE_LINK
DIBUTTON_DRIVINGR_AIDS
DIBUTTON_DRIVINGR_BOOST
DIBUTTON_DRIVINGR_BRAKE
DIBUTTON_DRIVINGR_DASHBOARD
DIBUTTON_DRIVINGR_DEVICE
DIBUTTON_DRIVINGR_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGR_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGR_MAP
DIBUTTON_DRIVINGR_PIT
DIBUTTON_DRIVINGR_PAUSE
DIBUTTON_DRIVINGR_STEER_LEFT_LINK
DIBUTTON_DRIVINGR_STEER_RIGHT_LINK
DIHATSWITCH_DRIVINGR_GLANCE


탱크

DIVIRTUAL_DRIVING_TANK 장르에는, 전차 시뮬레이션용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_DRIVINGT_ACCELERATE
DIAXIS_DRIVINGT_BARREL
DIAXIS_DRIVINGT_ROTATE
DIAXIS_DRIVINGT_STEER
DIBUTTON_DRIVINGT_FIRE
DIBUTTON_DRIVINGT_MENU
DIBUTTON_DRIVINGT_TARGET
DIBUTTON_DRIVINGT_WEAPONS

우선 순위 2 의 컨트롤
DIAXIS_DRIVINGT_ACCEL_AND_BRAKE
DIAXIS_DRIVINGT_BRAKE
DIBUTTON_DRIVINGT_ACCELERATE_LINK
DIBUTTON_DRIVINGT_BARREL_UP_LINK
DIBUTTON_DRIVINGT_BARREL_DOWN_LINK
DIBUTTON_DRIVINGT_BRAKE
DIBUTTON_DRIVINGT_DASHBOARD
DIBUTTON_DRIVINGT_DEVICE
DIBUTTON_DRIVINGT_FIRESECONDARY
DIBUTTON_DRIVINGT_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGT_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGT_PAUSE
DIBUTTON_DRIVINGT_ROTATE_LEFT_LINK
DIBUTTON_DRIVINGT_ROTATE_RIGHT_LINK
DIBUTTON_DRIVINGT_STEER_LEFT_LINK
DIBUTTON_DRIVINGT_STEER_RIGHT_LINK
DIBUTTON_DRIVINGT_VIEW
DIHATSWITCH_DRIVINGT_GLANCE


플라이트 장르

다음의 장르는, 플레이어가 항공기나 우주선을 제어하는 게임 및 시뮬레이션으로 사용된다.

  • 공중전
  • 민간기 플라이트
  • 헬리콥터전
  • 우주전


공중전

DIVIRTUAL_FLYING_MILITARY 장르에는, 고정익기에 의한 공중전투시뮬레이션용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_FLYINGM_BANK
DIAXIS_FLYINGM_PITCH
DIAXIS_FLYINGM_THROTTLE
DIBUTTON_FLYINGM_FIRE
DIBUTTON_FLYINGM_MENU
DIBUTTON_FLYINGM_TARGET
DIBUTTON_FLYINGM_WEAPONS

우선 순위 2 의 컨트롤
DIAXIS_FLYINGM_BRAKE
DIAXIS_FLYINGM_FLAPS
DIAXIS_FLYINGM_RUDDER
DIBUTTON_FLYINGM_BRAKE_LINK
DIBUTTON_FLYINGM_COUNTER
DIBUTTON_FLYINGM_DEVICE
DIBUTTON_FLYINGM_DISPLAY
DIBUTTON_FLYINGM_FASTER_LINK
DIBUTTON_FLYINGM_FIRESECONDARY
DIBUTTON_FLYINGM_FLAPSDOWN
DIBUTTON_FLYINGM_FLAPSUP
DIBUTTON_FLYINGM_GEAR
DIBUTTON_FLYINGM_GLANCE_DOWN_LINK
DIBUTTON_FLYINGM_GLANCE_LEFT_LINK
DIBUTTON_FLYINGM_GLANCE_RIGHT_LINK
DIBUTTON_FLYINGM_GLANCE_UP_LINK
DIBUTTON_FLYINGM_PAUSE
DIBUTTON_FLYINGM_SLOWER_LINK
DIBUTTON_FLYINGM_VIEW
DIHATSWITCH_FLYINGM_GLANCE


민간기 플라이트

DIVIRTUAL_FLYING_CIVILIAN 장르에는, 비전투 플라이트 시뮬레이션용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_FLYINGC_BANK
DIAXIS_FLYINGC_PITCH
DIAXIS_FLYINGC_THROTTLE
DIBUTTON_FLYINGC_DISPLAY
DIBUTTON_FLYINGC_GEAR
DIBUTTON_FLYINGC_MENU
DIBUTTON_FLYINGC_VIEW

우선 순위 2 의 컨트롤
DIAXIS_FLYINGC_BRAKE
DIAXIS_FLYINGC_FLAPS
DIAXIS_FLYINGC_RUDDER
DIBUTTON_FLYINGC_BRAKE_LINK
DIBUTTON_FLYINGC_DEVICE
DIBUTTON_FLYINGC_FASTER_LINK
DIBUTTON_FLYINGC_FLAPSDOWN
DIBUTTON_FLYINGC_FLAPSUP
DIBUTTON_FLYINGC_GLANCE_DOWN_LINK
DIBUTTON_FLYINGC_GLANCE_LEFT_LINK
DIBUTTON_FLYINGC_GLANCE_RIGHT_LINK
DIBUTTON_FLYINGC_GLANCE_UP_LINK
DIBUTTON_FLYINGC_PAUSE
DIBUTTON_FLYINGC_SLOWER_LINK
DIHATSWITCH_FLYINGC_GLANCE


헬리콥터전

DIVIRTUAL_FLYING_HELICOPTER 장르에는, 헬리콥터 전투 시뮬레이션용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_FLYINGH_BANK
DIAXIS_FLYINGH_COLLECTIVE
DIAXIS_FLYINGH_PITCH
DIBUTTON_FLYINGH_FIRE
DIBUTTON_FLYINGH_MENU
DIBUTTON_FLYINGH_TARGET
DIBUTTON_FLYINGH_WEAPONS

우선 순위 2 의 컨트롤
DIAXIS_FLYINGH_THROTTLE
DIAXIS_FLYINGH_TORQUE
DIBUTTON_FLYINGH_COUNTER
DIBUTTON_FLYINGH_DEVICE
DIBUTTON_FLYINGH_FASTER_LINK
DIBUTTON_FLYINGH_FIRESECONDARY
DIBUTTON_FLYINGH_GEAR
DIBUTTON_FLYINGH_GLANCE_DOWN_LINK
DIBUTTON_FLYINGH_GLANCE_LEFT_LINK
DIBUTTON_FLYINGH_GLANCE_RIGHT_LINK
DIBUTTON_FLYINGH_GLANCE_UP_LINK
DIBUTTON_FLYINGH_PAUSE
DIBUTTON_FLYINGH_SLOWER_LINK
DIBUTTON_FLYINGH_VIEW
DIHATSWITCH_FLYINGH_GLANCE


우주전

DIVIRTUAL_SPACESIM 장르에는, 우주선 전투 시뮬레이션용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_SPACESIM_LATERAL
DIAXIS_SPACESIM_MOVE
DIAXIS_SPACESIM_THROTTLE
DIBUTTON_SPACESIM_FIRE
DIBUTTON_SPACESIM_MENU
DIBUTTON_SPACESIM_TARGET
DIBUTTON_SPACESIM_WEAPONS

우선 순위 2 의 컨트롤
DIAXIS_SPACESIM_CLIMB
DIAXIS_SPACESIM_ROTATE
DIBUTTON_SPACESIM_BACKWARD_LINK
DIBUTTON_SPACESIM_DEVICE
DIBUTTON_SPACESIM_DISPLAY
DIBUTTON_SPACESIM_FASTER_LINK
DIBUTTON_SPACESIM_FIRESECONDARY
DIBUTTON_SPACESIM_FORWARD_LINK
DIBUTTON_SPACESIM_GEAR
DIBUTTON_SPACESIM_GLANCE_DOWN_LINK
DIBUTTON_SPACESIM_GLANCE_LEFT_LINK
DIBUTTON_SPACESIM_GLANCE_RIGHT_LINK
DIBUTTON_SPACESIM_GLANCE_UP_LINK
DIBUTTON_SPACESIM_LEFT_LINK
DIBUTTON_SPACESIM_LOWER
DIBUTTON_SPACESIM_PAUSE
DIBUTTON_SPACESIM_RAISE
DIBUTTON_SPACESIM_RIGHT_LINK
DIBUTTON_SPACESIM_SLOWER_LINK
DIBUTTON_SPACESIM_TURN_LEFT_LINK
DIBUTTON_SPACESIM_TURN_RIGHT_LINK
DIBUTTON_SPACESIM_VIEW
DIHATSWITCH_SPACESIM_GLANCE


스포츠 장르

다음의 장르에는, 스포츠 게임이나 시뮬레이션용의 컨트롤이 포함된다.

  • 야구 배팅
  • 야구 fielding
  • 야구 피칭
  • 농구 디펜스
  • 농구 오펜스
  • fishing
  • 풋볼 디펜스
  • 풋볼 오펜스
  • 풋볼 플레이
  • 풋볼 쿼터백
  • 골프
  • 핫키 디펜스
  • 핫키 골키퍼
  • 핫키 오펜스
  • 헌팅
  • 마운틴 바이크
  • 라켓
  • 스키
  • 축구 디펜스
  • 축구 오펜스


야구 배팅

DIVIRTUAL_SPORTS_BASEBALL_BAT 장르에는, 야구의 타자용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_BASEBALLB_LATERAL
DIAXIS_BASEBALLB_MOVE
DIBUTTON_BASEBALLB_BUNT
DIBUTTON_BASEBALLB_BURST
DIBUTTON_BASEBALLB_CONTACT
DIBUTTON_BASEBALLB_MENU
DIBUTTON_BASEBALLB_NORMAL
DIBUTTON_BASEBALLB_POWER
DIBUTTON_BASEBALLB_SELECT
DIBUTTON_BASEBALLB_SLIDE
DIBUTTON_BASEBALLB_STEAL

우선 순위 2 의 컨트롤
DIBUTTON_BASEBALLB_BOX
DIBUTTON_BASEBALLB_BACK_LINK
DIBUTTON_BASEBALLB_DEVICE
DIBUTTON_BASEBALLB_FORWARD_LINK
DIBUTTON_BASEBALLB_LEFT_LINK
DIBUTTON_BASEBALLB_NOSTEAL
DIBUTTON_BASEBALLB_PAUSE
DIBUTTON_BASEBALLB_RIGHT_LINK


야구 fielding

DIVIRTUAL_SPORTS_BASEBALL_FIELD 장르에는, 야구의 야수용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_BASEBALLF_LATERAL
DIAXIS_BASEBALLF_MOVE
DIBUTTON_BASEBALLF_BURST
DIBUTTON_BASEBALLF_DIVE
DIBUTTON_BASEBALLF_JUMP
DIBUTTON_BASEBALLF_MENU
DIBUTTON_BASEBALLF_NEAREST
DIBUTTON_BASEBALLF_THROW1
DIBUTTON_BASEBALLF_THROW2

우선 순위 2 의 컨트롤
DIBUTTON_BASEBALLF_AIM_LEFT_LINK
DIBUTTON_BASEBALLF_AIM_RIGHT_LINK
DIBUTTON_BASEBALLF_BACK_LINK
DIBUTTON_BASEBALLF_DEVICE
DIBUTTON_BASEBALLF_FORWARD_LINK
DIBUTTON_BASEBALLF_PAUSE
DIBUTTON_BASEBALLF_SHIFTIN
DIBUTTON_BASEBALLF_SHIFTOUT


야구 피칭

DIVIRTUAL_SPORTS_BASEBALL_PITCH 장르에는, 야구의 투수용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_BASEBALLP_LATERAL
DIAXIS_BASEBALLP_MOVE
DIBUTTON_BASEBALLP_BASE
DIBUTTON_BASEBALLP_FAKE
DIBUTTON_BASEBALLP_MENU
DIBUTTON_BASEBALLP_PITCH
DIBUTTON_BASEBALLP_SELECT
DIBUTTON_BASEBALLP_THROW

우선 순위 2 의 컨트롤
DIBUTTON_BASEBALLP_BACK_LINK
DIBUTTON_BASEBALLP_DEVICE
DIBUTTON_BASEBALLP_FORWARD_LINK
DIBUTTON_BASEBALLP_LEFT_LINK
DIBUTTON_BASEBALLP_LOOK
DIBUTTON_BASEBALLP_PAUSE
DIBUTTON_BASEBALLP_RIGHT_LINK
DIBUTTON_BASEBALLP_WALK


농구 디펜스

DIVIRTUAL_SPORTS_BASKETBALL_DEFENSE 장르에는, 농구의 수비 동작용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_BBALLD_LATERAL
DIAXIS_BBALLD_MOVE
DIBUTTON_BBALLD_BURST
DIBUTTON_BBALLD_FAKE
DIBUTTON_BBALLD_JUMP
DIBUTTON_BBALLD_MENU
DIBUTTON_BBALLD_PLAY
DIBUTTON_BBALLD_PLAYER
DIBUTTON_BBALLD_SPECIAL
DIBUTTON_BBALLD_STEAL

우선 순위 2 의 컨트롤
DIBUTTON_BBALLD_BACK_LINK
DIBUTTON_BBALLD_DEVICE
DIBUTTON_BBALLD_FORWARD_LINK
DIBUTTON_BBALLD_LEFT_LINK
DIBUTTON_BBALLD_PAUSE
DIBUTTON_BBALLD_RIGHT_LINK
DIBUTTON_BBALLD_SUBSTITUTE
DIBUTTON_BBALLD_TIMEOUT
DIHATSWITCH_BBALLD_GLANCE


농구 오펜스

DIVIRTUAL_SPORTS_BASKETBALL_OFFENSE 장르에는, 농구의 시합으로 볼을 가지는 플레이어용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_BBALLO_LATERAL
DIAXIS_BBALLO_MOVE
DIBUTTON_BBALLO_BURST
DIBUTTON_BBALLO_CALL
DIBUTTON_BBALLO_DUNK
DIBUTTON_BBALLO_FAKE
DIBUTTON_BBALLO_MENU
DIBUTTON_BBALLO_PASS
DIBUTTON_BBALLO_PLAYER
DIBUTTON_BBALLO_SHOOT
DIBUTTON_BBALLO_SPECIAL

우선 순위 2 의 컨트롤
DIBUTTON_BBALLO_BACK_LINK
DIBUTTON_BBALLO_DEVICE
DIBUTTON_BBALLO_FORWARD_LINK
DIBUTTON_BBALLO_JAB
DIBUTTON_BBALLO_LEFT_LINK
DIBUTTON_BBALLO_PAUSE
DIBUTTON_BBALLO_PLAY
DIBUTTON_BBALLO_POST
DIBUTTON_BBALLO_RIGHT_LINK
DIBUTTON_BBALLO_SCREEN
DIBUTTON_BBALLO_SUBSTITUTE
DIBUTTON_BBALLO_TIMEOUT
DIHATSWITCH_BBALLO_GLANCE


fishing

DIVIRTUAL_SPORTS_FISHING 장르에는, 스포츠 fishing 시뮬레이션용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_FISHING_LATERAL
DIAXIS_FISHING_MOVE
DIBUTTON_FISHING_BAIT
DIBUTTON_FISHING_BINOCULAR
DIBUTTON_FISHING_CAST
DIBUTTON_FISHING_MAP
DIBUTTON_FISHING_MENU
DIBUTTON_FISHING_TYPE

우선 순위 2 의 컨트롤
DIAXIS_FISHING_ROTATE
DIBUTTON_FISHING_BACK_LINK
DIBUTTON_FISHING_CROUCH
DIBUTTON_FISHING_DEVICE
DIBUTTON_FISHING_DISPLAY
DIBUTTON_FISHING_FORWARD_LINK
DIBUTTON_FISHING_JUMP
DIBUTTON_FISHING_LEFT_LINK
DIBUTTON_FISHING_PAUSE
DIBUTTON_FISHING_RIGHT_LINK
DIBUTTON_FISHING_ROTATE_LEFT_LINK
DIBUTTON_FISHING_ROTATE_RIGHT_LINK
DIHATSWITCH_FISHING_GLANCE


풋볼 디펜스

DIVIRTUAL_SPORTS_FOOTBALL_DEFENSE 장르에는, 미식 축구의 디펜스측의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_FOOTBALLD_LATERAL
DIAXIS_FOOTBALLD_MOVE
DIBUTTON_FOOTBALLD_FAKE
DIBUTTON_FOOTBALLD_JUMP
DIBUTTON_FOOTBALLD_MENU
DIBUTTON_FOOTBALLD_PLAY
DIBUTTON_FOOTBALLD_SELECT
DIBUTTON_FOOTBALLD_SUPERTACKLE
DIBUTTON_FOOTBALLD_TACKLE

우선 순위 2 의 컨트롤
DIBUTTON_FOOTBALLD_AUDIBLE
DIBUTTON_FOOTBALLD_BACK_LINK
DIBUTTON_FOOTBALLD_BULLRUSH
DIBUTTON_FOOTBALLD_DEVICE
DIBUTTON_FOOTBALLD_FORWARD_LINK
DIBUTTON_FOOTBALLD_LEFT_LINK
DIBUTTON_FOOTBALLD_PAUSE
DIBUTTON_FOOTBALLD_RIGHT_LINK
DIBUTTON_FOOTBALLD_RIP
DIBUTTON_FOOTBALLD_SPIN
DIBUTTON_FOOTBALLD_SUBSTITUTE
DIBUTTON_FOOTBALLD_SWIM
DIBUTTON_FOOTBALLD_ZOOM


풋볼 오펜스

DIVIRTUAL_SPORTS_FOOTBALL_OFFENSE 장르에는, 미식 축구의 볼 캐리어용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_FOOTBALLO_LATERAL
DIAXIS_FOOTBALLO_MOVE
DIBUTTON_FOOTBALLO_JUMP
DIBUTTON_FOOTBALLO_LEFTARM
DIBUTTON_FOOTBALLO_MENU
DIBUTTON_FOOTBALLO_RIGHTARM
DIBUTTON_FOOTBALLO_SPIN
DIBUTTON_FOOTBALLO_THROW

우선 순위 2 의 컨트롤
DIBUTTON_FOOTBALLO_BACK_LINK
DIBUTTON_FOOTBALLO_DEVICE
DIBUTTON_FOOTBALLO_DIVE
DIBUTTON_FOOTBALLO_FORWARD_LINK
DIBUTTON_FOOTBALLO_JUKE
DIBUTTON_FOOTBALLO_LEFT_LINK
DIBUTTON_FOOTBALLO_PAUSE
DIBUTTON_FOOTBALLO_RIGHT_LINK
DIBUTTON_FOOTBALLO_SHOULDER
DIBUTTON_FOOTBALLO_SUBSTITUTE
DIBUTTON_FOOTBALLO_TURBO
DIBUTTON_FOOTBALLO_ZOOM


풋볼 플레이

DIVIRTUAL_SPORTS_FOOTBALL_FIELD 장르에는, 미식 축구용의 일반적인 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIBUTTON_FOOTBALLP_HELP
DIBUTTON_FOOTBALLP_MENU
DIBUTTON_FOOTBALLP_PLAY
DIBUTTON_FOOTBALLP_SELECT

우선 순위 2 의 컨트롤
DIBUTTON_FOOTBALLP_DEVICE
DIBUTTON_FOOTBALLP_PAUSE


풋볼 쿼터백

DIVIRTUAL_SPORTS_FOOTBALL_QBCK 장르에는, 미식 축구의 쿼터백용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_FOOTBALLQ_LATERAL
DIAXIS_FOOTBALLQ_MOVE
DIBUTTON_FOOTBALLQ_FAKE
DIBUTTON_FOOTBALLQ_JUMP
DIBUTTON_FOOTBALLQ_MENU
DIBUTTON_FOOTBALLQ_PASS
DIBUTTON_FOOTBALLQ_SELECT
DIBUTTON_FOOTBALLQ_SLIDE
DIBUTTON_FOOTBALLQ_SNAP

우선 순위 2 의 컨트롤
DIBUTTON_FOOTBALLQ_AUDIBLE
DIBUTTON_FOOTBALLQ_BACK_LINK
DIBUTTON_FOOTBALLQ_DEVICE
DIBUTTON_FOOTBALLQ_FAKESNAP
DIBUTTON_FOOTBALLQ_FORWARD_LINK
DIBUTTON_FOOTBALLQ_LEFT_LINK
DIBUTTON_FOOTBALLQ_MOTION
DIBUTTON_FOOTBALLQ_PAUSE
DIBUTTON_FOOTBALLQ_RIGHT_LINK


골프

DIVIRTUAL_SPORTS_GOLF 장르에는, 골프용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_GOLF_LATERAL
DIAXIS_GOLF_MOVE
DIBUTTON_GOLF_DOWN
DIBUTTON_GOLF_FLYBY
DIBUTTON_GOLF_MENU
DIBUTTON_GOLF_SELECT
DIBUTTON_GOLF_SWING
DIBUTTON_GOLF_TERRAIN
DIBUTTON_GOLF_UP

우선 순위 2 의 컨트롤
DIBUTTON_GOLF_BACK_LINK
DIBUTTON_GOLF_DEVICE
DIBUTTON_GOLF_FORWARD_LINK
DIBUTTON_GOLF_LEFT_LINK
DIBUTTON_GOLF_PAUSE
DIBUTTON_GOLF_RIGHT_LINK
DIBUTTON_GOLF_SUBSTITUTE
DIBUTTON_GOLF_TIMEOUT
DIBUTTON_GOLF_ZOOM
DIHATSWITCH_GOLF_SCROLL


핫키 디펜스

DIVIRTUAL_SPORTS_HOCKEY_DEFENSE 장르에는, 핫키의 수비 동작용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_HOCKEYD_LATERAL
DIAXIS_HOCKEYD_MOVE
DIBUTTON_HOCKEYD_BLOCK
DIBUTTON_HOCKEYD_BURST
DIBUTTON_HOCKEYD_FAKE
DIBUTTON_HOCKEYD_MENU
DIBUTTON_HOCKEYD_PLAYER
DIBUTTON_HOCKEYD_STEAL

우선 순위 2 의 컨트롤
DIBUTTON_HOCKEYD_BACK_LINK
DIBUTTON_HOCKEYD_DEVICE
DIBUTTON_HOCKEYO_FORWARD_LINK
DIBUTTON_HOCKEYO_LEFT_LINK
DIBUTTON_HOCKEYD_PAUSE
DIBUTTON_HOCKEYO_RIGHT_LINK
DIBUTTON_HOCKEYD_STRATEGY
DIBUTTON_HOCKEYD_SUBSTITUTE
DIBUTTON_HOCKEYD_TIMEOUT
DIBUTTON_HOCKEYD_ZOOM
DIHATSWITCH_HOCKEYD_SCROLL


핫키 골키퍼

DIVIRTUAL_SPORTS_HOCKEY_GOALIE 장르에는, 핫키의 골키퍼용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_HOCKEYG_LATERAL
DIAXIS_HOCKEYG_MOVE
DIBUTTON_HOCKEYG_BLOCK
DIBUTTON_HOCKEYG_MENU
DIBUTTON_HOCKEYG_PASS
DIBUTTON_HOCKEYG_POKE
DIBUTTON_HOCKEYG_STEAL

우선 순위 2 의 컨트롤
DIBUTTON_HOCKEYG_BACK_LINK
DIBUTTON_HOCKEYG_DEVICE
DIBUTTON_HOCKEYG_FORWARD_LINK
DIBUTTON_HOCKEYG_LEFT_LINK
DIBUTTON_HOCKEYG_PAUSE
DIBUTTON_HOCKEYG_RIGHT_LINK
DIBUTTON_HOCKEYG_STRATEGY
DIBUTTON_HOCKEYG_SUBSTITUTE
DIBUTTON_HOCKEYG_TIMEOUT
DIBUTTON_HOCKEYG_ZOOM
DIHATSWITCH_HOCKEYG_SCROLL


핫키 오펜스

DIVIRTUAL_SPORTS_HOCKEY_OFFENSE 장르에는, 핫키의 공격 동작용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_HOCKEYO_LATERAL
DIAXIS_HOCKEYO_MOVE
DIBUTTON_HOCKEYO_BURST
DIBUTTON_HOCKEYO_FAKE
DIBUTTON_HOCKEYO_MENU
DIBUTTON_HOCKEYO_PASS
DIBUTTON_HOCKEYO_SHOOT
DIBUTTON_HOCKEYO_SPECIAL

우선 순위 2 의 컨트롤
DIBUTTON_HOCKEYO_BACK_LINK
DIBUTTON_HOCKEYO_DEVICE
DIBUTTON_HOCKEYO_FORWARD_LINK
DIBUTTON_HOCKEYO_LEFT_LINK
DIBUTTON_HOCKEYO_PAUSE
DIBUTTON_HOCKEYO_RIGHT_LINK
DIBUTTON_HOCKEYO_STRATEGY
DIBUTTON_HOCKEYO_SUBSTITUTE
DIBUTTON_HOCKEYO_TIMEOUT
DIBUTTON_HOCKEYO_ZOOM
DIHATSWITCH_HOCKEYO_SCROLL


헌팅

DIVIRTUAL_SPORTS_HUNTING 장르에는, 헌팅 시뮬레이션용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_HUNTING_LATERAL
DIAXIS_HUNTING_MOVE
DIBUTTON_HUNTING_AIM
DIBUTTON_HUNTING_BINOCULAR
DIBUTTON_HUNTING_CALL
DIBUTTON_HUNTING_FIRE
DIBUTTON_HUNTING_MAP
DIBUTTON_HUNTING_MENU
DIBUTTON_HUNTING_SPECIAL
DIBUTTON_HUNTING_WEAPON

우선 순위 2 의 컨트롤
DIAXIS_HUNTING_ROTATE
DIBUTTON_HUNTING_BACK_LINK
DIBUTTON_HUNTING_CROUCH
DIBUTTON_HUNTING_DEVICE
DIBUTTON_HUNTING_DISPLAY
DIBUTTON_HUNTING_FIRESECONDARY
DIBUTTON_HUNTING_FORWARD_LINK
DIBUTTON_HUNTING_JUMP
DIBUTTON_HUNTING_LEFT_LINK
DIBUTTON_HUNTING_PAUSE
DIBUTTON_HUNTING_RIGHT_LINK
DIBUTTON_HUNTING_ROTATE_LEFT_LINK
DIBUTTON_HUNTING_ROTATE_RIGHT_LINK
DIHATSWITCH_HUNTING_GLANCE


마운틴 바이크

DIVIRTUAL_SPORTS_BIKING_MOUNTAIN 장르에는, 마운틴 바이크용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_BIKINGM_PEDAL
DIAXIS_BIKINGM_TURN
DIBUTTON_BIKINGM_CAMERA
DIBUTTON_BIKINGM_JUMP
DIBUTTON_BIKINGM_MENU
DIBUTTON_BIKINGM_SELECT
DIBUTTON_BIKINGM_SPECIAL1
DIBUTTON_BIKINGM_SPECIAL2

우선 순위 2 의 컨트롤
DIAXIS_BIKINGM_BRAKE
DIBUTTON_BIKINGM_BRAKE_BUTTON_LINK
DIBUTTON_BIKINGM_DEVICE
DIBUTTON_BIKINGM_FASTER_LINK
DIBUTTON_BIKINGM_LEFT_LINK
DIBUTTON_BIKINGM_PAUSE
DIBUTTON_BIKINGM_RIGHT_LINK
DIBUTTON_BIKINGM_SLOWER_LINK
DIBUTTON_BIKINGM_ZOOM
DIHATSWITCH_BIKINGM_SCROLL


라켓

DIVIRTUAL_SPORTS_RACQUET 장르에는, 테니스, 탁구, 스쿼시등의 라켓 게임용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_RACQUET_LATERAL
DIAXIS_RACQUET_MOVE
DIBUTTON_RACQUET_BACKSWING
DIBUTTON_RACQUET_MENU
DIBUTTON_RACQUET_SELECT
DIBUTTON_RACQUET_SMASH
DIBUTTON_RACQUET_SPECIAL
DIBUTTON_RACQUET_SWING

우선 순위 2 의 컨트롤
DIBUTTON_RACQUET_BACK_LINK
DIBUTTON_RACQUET_DEVICE
DIBUTTON_RACQUET_FORWARD_LINK
DIBUTTON_RACQUET_LEFT_LINK
DIBUTTON_RACQUET_PAUSE
DIBUTTON_RACQUET_RIGHT_LINK
DIBUTTON_RACQUET_SUBSTITUTE
DIBUTTON_RACQUET_TIMEOUT
DIHATSWITCH_RACQUET_GLANCE


스키

DIVIRTUAL_SPORTS_SKIING 장르에는, 스키용의 컨트롤, 및 스노보드나 스케이트보드 등 유사 스포츠의 시뮬레이션용 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_SKIING_SPEED
DIAXIS_SKIING_TURN
DIBUTTON_SKIING_CAMERA
DIBUTTON_SKIING_CROUCH
DIBUTTON_SKIING_JUMP
DIBUTTON_SKIING_MENU
DIBUTTON_SKIING_SELECT
DIBUTTON_SKIING_SPECIAL1
DIBUTTON_SKIING_SPECIAL2

우선 순위 2 의 컨트롤
DIBUTTON_SKIING_DEVICE
DIBUTTON_SKIING_FASTER_LINK
DIBUTTON_SKIING_LEFT_LINK
DIBUTTON_SKIING_PAUSE
DIBUTTON_SKIING_RIGHT_LINK
DIBUTTON_SKIING_SLOWER_LINK
DIBUTTON_SKIING_ZOOM
DIHATSWITCH_SKIING_GLANCE


축구 디펜스

DIVIRTUAL_SPORTS_SOCCER_DEFENSE 장르에는, 축구의 수비 동작용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_SOCCERD_LATERAL
DIAXIS_SOCCERD_MOVE
DIBUTTON_SOCCERD_BLOCK
DIBUTTON_SOCCERD_FAKE
DIBUTTON_SOCCERD_MENU
DIBUTTON_SOCCERD_PLAYER
DIBUTTON_SOCCERD_SELECT
DIBUTTON_SOCCERD_SLIDE
DIBUTTON_SOCCERD_SPECIAL
DIBUTTON_SOCCERD_STEAL

우선 순위 2 의 컨트롤
DIBUTTON_SOCCERD_BACK_LINK
DIBUTTON_SOCCERD_CLEAR
DIBUTTON_SOCCERD_DEVICE
DIBUTTON_SOCCERD_FORWARD_LINK
DIBUTTON_SOCCERD_FOUL
DIBUTTON_SOCCERD_GOALIECHARGE
DIBUTTON_SOCCERD_HEAD
DIBUTTON_SOCCERD_LEFT_LINK
DIBUTTON_SOCCERD_PAUSE
DIBUTTON_SOCCERD_RIGHT_LINK
DIBUTTON_SOCCERD_SUBSTITUTE
DIHATSWITCH_SOCCERD_GLANCE


축구 오펜스

DIVIRTUAL_SPORTS_SOCCER_OFFENSE 장르에는, 축구의 공격 동작용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_SOCCERO_BEND
DIAXIS_SOCCERO_LATERAL
DIAXIS_SOCCERO_MOVE
DIBUTTON_SOCCERO_FAKE
DIBUTTON_SOCCERO_MENU
DIBUTTON_SOCCERO_PASS
DIBUTTON_SOCCERO_PLAYER
DIBUTTON_SOCCERO_SELECT
DIBUTTON_SOCCERO_SHOOT
DIBUTTON_SOCCERO_SPECIAL1

우선 순위 2 의 컨트롤
DIBUTTON_SOCCERO_BACK_LINK
DIBUTTON_SOCCERO_CONTROL
DIBUTTON_SOCCERO_DEVICE
DIBUTTON_SOCCERO_FORWARD_LINK
DIBUTTON_SOCCERO_HEAD
DIBUTTON_SOCCERO_LEFT_LINK
DIBUTTON_SOCCERO_PASSTHRU
DIBUTTON_SOCCERO_PAUSE
DIBUTTON_SOCCERO_RIGHT_LINK
DIBUTTON_SOCCERO_SHOOTHIGH
DIBUTTON_SOCCERO_SHOOTLOW
DIBUTTON_SOCCERO_SPRINT
DIBUTTON_SOCCERO_SUBSTITUTE
DIHATSWITCH_SOCCERO_GLANCE


스트래터지 장르

다음의 장르에는, 스트래터지, 롤플레잉, 및 아드벤체게임용의 컨트롤이 포함된다.

  • 롤플레잉
  • 턴 베이스


롤플레잉

DIVIRTUAL_STRATEGY_ROLEPLAYING 장르에는, 이동, 문제 해결, 및 무기나 마법에 따르는 전투를 주된 활동으로 하는 롤플레잉 게임이나 아드벤체게임용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_STRATEGYR_LATERAL
DIAXIS_STRATEGYR_MOVE
DIBUTTON_STRATEGYR_APPLY
DIBUTTON_STRATEGYR_ATTACK
DIBUTTON_STRATEGYR_CAST
DIBUTTON_STRATEGYR_CROUCH
DIBUTTON_STRATEGYR_GET
DIBUTTON_STRATEGYR_JUMP
DIBUTTON_STRATEGYR_MENU
DIBUTTON_STRATEGYR_SELECT

우선 순위 2 의 컨트롤
DIAXIS_STRATEGYR_ROTATE
DIBUTTON_STRATEGYR_BACK_LINK
DIBUTTON_STRATEGYR_DEVICE
DIBUTTON_STRATEGYR_DISPLAY
DIBUTTON_STRATEGYR_FORWARD_LINK
DIBUTTON_STRATEGYR_LEFT_LINK
DIBUTTON_STRATEGYR_MAP
DIBUTTON_STRATEGYR_PAUSE
DIBUTTON_STRATEGYR_RIGHT_LINK
DIBUTTON_STRATEGYR_ROTATE_LEFT_LINK
DIBUTTON_STRATEGYR_ROTATE_RIGHT_LINK
DIHATSWITCH_STRATEGYR_GLANCE


턴 베이스

DIVIRTUAL_STRATEGY_TURN 장르에는, 턴 베이스의 스트래터지 게임용의 컨트롤이 포함된다.

우선 순위 1 의 컨트롤
DIAXIS_STRATEGYT_LATERAL
DIAXIS_STRATEGYT_MOVE
DIBUTTON_STRATEGYT_APPLY
DIBUTTON_STRATEGYT_INSTRUCT
DIBUTTON_STRATEGYT_MENU
DIBUTTON_STRATEGYT_SELECT
DIBUTTON_STRATEGYT_TEAM
DIBUTTON_STRATEGYT_TURN

우선 순위 2 의 컨트롤
DIBUTTON_STRATEGYT_BACK_LINK
DIBUTTON_STRATEGYT_DEVICE
DIBUTTON_STRATEGYT_DISPLAY
DIBUTTON_STRATEGYT_FORWARD_LINK
DIBUTTON_STRATEGYT_LEFT_LINK
DIBUTTON_STRATEGYT_MAP
DIBUTTON_STRATEGYT_PAUSE
DIBUTTON_STRATEGYT_RIGHT_LINK
DIBUTTON_STRATEGYT_ZOOM


키보드 매핑 정수

다음의 정수는, 액션을 물리 키에 맵 하기 위해서,DIACTION 구조체의 dwSemantic 멤버 중(안)에서 사용된다.

정수 | 메모
DIKEYBOARD_0 | 메인 키보드상
DIKEYBOARD_1 | 메인 키보드상
DIKEYBOARD_2 | 메인 키보드상
DIKEYBOARD_3 | 메인 키보드상
DIKEYBOARD_4 | 메인 키보드상
DIKEYBOARD_5 | 메인 키보드상
DIKEYBOARD_6 | 메인 키보드상
DIKEYBOARD_7 | 메인 키보드상
DIKEYBOARD_8 | 메인 키보드상
DIKEYBOARD_9 | 메인 키보드상
DIKEYBOARD_A |
DIKEYBOARD_ABNT_C1 | 브라질어 키보드의 숫자 패드상
DIKEYBOARD_ABNT_C2 | 브라질어 키보드의 숫자 패드상
DIKEYBOARD_ADD | 숫자 패드 위에의 플러스 기호 (+)
DIKEYBOARD_APOSTROPHE |
DIKEYBOARD_APPS | 어플리케이션 키
DIKEYBOARD_AT | 일본어 키보드상
DIKEYBOARD_AX | 일본어 키보드상
DIKEYBOARD_B |
DIKEYBOARD_BACK | BackSpace
DIKEYBOARD_BACKSLASH |
DIKEYBOARD_C |
DIKEYBOARD_CALCULATOR |
DIKEYBOARD_CAPITAL | Caps Lock
DIKEYBOARD_COLON | 일본어 키보드상
DIKEYBOARD_COMMA |
DIKEYBOARD_CONVERT | 일본어 키보드상
DIKEYBOARD_D |
DIKEYBOARD_DECIMAL | 숫자 패드 위에의 피리어드 (소수점)
DIKEYBOARD_DELETE |
DIKEYBOARD_DIVIDE | 숫자 패드 위에의 slash (/)
DIKEYBOARD_DOWN | 하 커서 키
DIKEYBOARD_E |
DIKEYBOARD_END |
DIKEYBOARD_EQUALS | 메인 키보드상
DIKEYBOARD_ESCAPE |
DIKEYBOARD_F |
DIKEYBOARD_F1 |
DIKEYBOARD_F2 |
DIKEYBOARD_F3 |
DIKEYBOARD_F4 |
DIKEYBOARD_F5 |
DIKEYBOARD_F6 |
DIKEYBOARD_F7 |
DIKEYBOARD_F8 |
DIKEYBOARD_F9 |
DIKEYBOARD_F10 |
DIKEYBOARD_F11 |
DIKEYBOARD_F12 |
DIKEYBOARD_F13 | NEC PC-98 일본어 키보드상
DIKEYBOARD_F14 | NEC PC-98 일본어 키보드상
DIKEYBOARD_F15 | NEC PC-98 일본어 키보드상
DIKEYBOARD_G |
DIKEYBOARD_GRAVE | 아크상라브 (`) 키
DIKEYBOARD_H |
DIKEYBOARD_HOME |
DIKEYBOARD_I |
DIKEYBOARD_INSERT |
DIKEYBOARD_J |
DIKEYBOARD_K |
DIKEYBOARD_KANA | 일본어 키보드상
DIKEYBOARD_KANJI | 일본어 키보드상
DIKEYBOARD_L |
DIKEYBOARD_LBRACKET | 왼쪽각이나 와 [
DIKEYBOARD_LCONTROL | 왼쪽 Ctrl 키
DIKEYBOARD_LEFT | 왼쪽 커서 키
DIKEYBOARD_LMENU | 왼쪽 Alt 키
DIKEYBOARD_LSHIFT | 왼쪽 Shift 키
DIKEYBOARD_LWIN | 왼쪽 Microsoft® Windows® 키
DIKEYBOARD_M |
DIKEYBOARD_MAIL |
DIKEYBOARD_MEDIASELECT | 시스템으로 지원 되고 있는 미디어 플레이어의 선택을 표시하는, 미디어 선택 키.
DIKEYBOARD_MEDIASTOP |
DIKEYBOARD_MINUS | 메인 키보드상
DIKEYBOARD_MULTIPLY | 숫자 패드 위에의 asterisk (*)
DIKEYBOARD_MUTE |
DIKEYBOARD_MYCOMPUTER |
DIKEYBOARD_N |
DIKEYBOARD_NEXT | PageDown 키
DIKEYBOARD_NEXTTRACK | 다음의 트럭
DIKEYBOARD_NOCONVERT | 일본어 키보드상
DIKEYBOARD_NUMLOCK |
DIKEYBOARD_NUMPAD0 |
DIKEYBOARD_NUMPAD1 |
DIKEYBOARD_NUMPAD2 |
DIKEYBOARD_NUMPAD3 |
DIKEYBOARD_NUMPAD4 |
DIKEYBOARD_NUMPAD5 |
DIKEYBOARD_NUMPAD6 |
DIKEYBOARD_NUMPAD7 |
DIKEYBOARD_NUMPAD8 |
DIKEYBOARD_NUMPAD9 |
DIKEYBOARD_NUMPADCOMMA | NEC PC-98 일본어 키보드 숫자 패드상
DIKEYBOARD_NUMPADENTER |
DIKEYBOARD_NUMPADEQUALS | NEC PC-98 일본어 키보드 숫자 패드상
DIKEYBOARD_O |
DIKEYBOARD_OEM_102 | 영어 키보드 및 독일어 키보드상
DIKEYBOARD_P |
DIKEYBOARD_PAUSE |
DIKEYBOARD_PERIOD | 메인 키보드상
DIKEYBOARD_PLAYPAUSE |
DIKEYBOARD_POWER |
DIKEYBOARD_PREVTRACK | 전의 트럭, 일본어 키보드의 서컴프렉스
DIKEYBOARD_PRIOR | PageUp 키
DIKEYBOARD_Q |
DIKEYBOARD_R |
DIKEYBOARD_RBRACKET | 오른쪽각이나 와 ]
DIKEYBOARD_RCONTROL | 오른쪽 Ctrl 키
DIKEYBOARD_RETURN | 메인 키보드 위에의 Enter 키
DIKEYBOARD_RIGHT | 오른쪽 커서 키
DIKEYBOARD_RMENU | 오른쪽 Alt 키
DIKEYBOARD_RSHIFT | 오른쪽 Shift 키
DIKEYBOARD_RWIN | 오른쪽 Windows 키
DIKEYBOARD_S |
DIKEYBOARD_SCROLL | ScrollLock
DIKEYBOARD_SEMICOLON |
DIKEYBOARD_SLASH | 메인 키보드 위에의 slash (/)
DIKEYBOARD_SLEEP |
DIKEYBOARD_SPACE | 스페이스 키
DIKEYBOARD_STOP | NEC PC-98 일본어 키보드상
DIKEYBOARD_SUBTRACT | 숫자 패드 위에의 마이너스 기호 (-)
DIKEYBOARD_SYSRQ |
DIKEYBOARD_T |
DIKEYBOARD_TAB |
DIKEYBOARD_U |
DIKEYBOARD_UNDERLINE | NEC PC-98 일본어 키보드상
DIKEYBOARD_UNLABELED | 일본어 키보드상
DIKEYBOARD_UP | 상 커서 키
DIKEYBOARD_V |
DIKEYBOARD_VOLUMEDOWN |
DIKEYBOARD_VOLUMEUP |
DIKEYBOARD_W |
DIKEYBOARD_WAKE |
DIKEYBOARD_WEBBACK |
DIKEYBOARD_WEBFAVORITES | Microsoft Internet Explorer 의 [마음에 드는] 리스트, Windows 의 [Favorites] 폴더, 또는 Netscape 의 북마크 리스트를 표시한다.
DIKEYBOARD_WEBFORWARD |
DIKEYBOARD_WEBHOME |
DIKEYBOARD_WEBREFRESH |
DIKEYBOARD_WEBSEARCH |
DIKEYBOARD_WEBSTOP |
DIKEYBOARD_X |
DIKEYBOARD_Y |
DIKEYBOARD_YEN | 일본어 키보드상
DIKEYBOARD_Z |


마우스 매핑 정수

다음의 정수는, 액션을 마우스의 물리축이나 버튼에 맵 하기 위해서,DIACTION 구조체의 dwSemantic 멤버 중(안)에서 사용된다.

DIMOUSE_BUTTON0
DIMOUSE_BUTTON1
DIMOUSE_BUTTON2
DIMOUSE_BUTTON3
DIMOUSE_BUTTON4
DIMOUSE_BUTTON5
DIMOUSE_BUTTON6
DIMOUSE_BUTTON7
DIMOUSE_WHEEL
DIMOUSE_XAXIS
DIMOUSE_YAXIS
DIMOUSE_XAXISAB
DIMOUSE_YAXISAB

주 : DIMOUSE_XAXISAB 와 DIMOUSE_YAXISAB 는, 상대축데이터는 아니고 절대축데이터를 돌려주는 마우스의 x 축과 y 축을 나타낸다.


DirectPlay 음성 매핑 정수

다음의 정수는, 액션을 Microsoft® DirectPlay® 의 음성 디바이스의 채널에 맵 하기 위해서,DIACTION 구조체의 dwSemantic 멤버 중(안)에서 사용된다.

DIVOICE_CHANNEL1
DIVOICE_CHANNEL2
DIVOICE_CHANNEL3
DIVOICE_CHANNEL4
DIVOICE_CHANNEL5
DIVOICE_CHANNEL6
DIVOICE_CHANNEL7
DIVOICE_CHANNEL8
DIVOICE_ALL
DIVOICE_TEAM
DIVOICE_PLAYBACKMUTE
DIVOICE_RECORDMUTE
DIVOICE_TRANSMIT
DIVOICE_VOICECOMMAND


임의 컨트롤 정수

다음의 정수는, 디바이스상에서 일치하는 임의의 컨트롤에 액션을 맵 하기 위해서,DIACTION 구조체의 dwSemantic 멤버 중(안)에서 사용된다.

정수 | 디바이스 오브젝트
DIAXIS_ANY_1 | 임의의 축
DIAXIS_ANY_2 | 임의의 축
DIAXIS_ANY_3 | 임의의 축
DIAXIS_ANY_4 | 임의의 축
DIAXIS_ANY_A_1 | 임의의 액셀
DIAXIS_ANY_A_2 | 임의의 액셀
DIAXIS_ANY_B_1 | 임의의 브레이크
DIAXIS_ANY_B_2 | 임의의 브레이크
DIAXIS_ANY_C_1 | 임의의 클러치
DIAXIS_ANY_C_2 | 임의의 클러치
DIAXIS_ANY_R_1 | 임의의 r 축
DIAXIS_ANY_R_2 | 임의의 r 축
DIAXIS_ANY_S_1 | 임의의 s 축
DIAXIS_ANY_S_2 | 임의의 s 축
DIAXIS_ANY_U_1 | 임의의 u 축
DIAXIS_ANY_U_2 | 임의의 u 축
DIAXIS_ANY_V_1 | 임의의 v 축
DIAXIS_ANY_V_2 | 임의의 v 축
DIAXIS_ANY_X_1 | 임의의 x 축
DIAXIS_ANY_X_2 | 임의의 x 축
DIAXIS_ANY_Y_1 | 임의의 y 축
DIAXIS_ANY_Y_2 | 임의의 y 축
DIAXIS_ANY_Z_1 | 임의의 z 축
DIAXIS_ANY_Z_2 | 임의의 z 축
DIBUTTON_ANY(x) | 임의의 버튼
DIPOV_ANY_1 | 임의의 시점 콘트롤러
DIPOV_ANY_2 | 임의의 시점 콘트롤러
DIPOV_ANY_3 | 임의의 시점 콘트롤러
DIPOV_ANY_4 | 임의의 시점 콘트롤러

이러한 정수를 사용해, 특정의 장르에 정의되어 있지 않은 가상 컨트롤에, 어플리케이션 액션을 맵 할 수가 있다. 이러한 액션은, 장르 고유 액션의 뒤에 맵 된다. 맵퍼가 모든 일치하는 컨트롤을 장르 고유 액션에 이미 맵 하고 있었을 경우, 임의 컨트롤 액션은, 맵 되지 않은 채 남겨진다.

임의 컨트롤 액션에 우선도의 차이는 없다. 디바이스에 1 개의 x 축이 있어, 액션 배열이 DIAXIS_ANY_1 및 DIAXIS_ANY_X_1 를 지정하는 경우, x 축으로는, 액션 배열의 선두에 표시되는 액션이 맵 된다.

DIBUTTON_ANY(x)는 0 ~ 255 까지의 임의의 값을 받을 수가 있다. 다만, 한 번 지정한 인덱스를 2 회 이상 사용하지 않는 것. 예를 들어, 다음의 DIACTION 구조체세트는 무효이다.

{eB_MUTE,    DIBUTTON_ANY(0), 0, "Toggle Sound",},
{eB_VOLUP,   DIBUTTON_ANY(0), 0, "Volume Up",   },
{eB_VOLDOWN, DIBUTTON_ANY(0), 0, "Volume Down", },

다음에 나타내도록(듯이) 각각 다른 인덱스를 사용하는 것이 올바른 사용법이다.

{eB_MUTE,    DIBUTTON_ANY(0), 0, "Toggle Sound",}
{eB_VOLUP,   DIBUTTON_ANY(1), 0, "Volume Up",   }
{eB_VOLDOWN, DIBUTTON_ANY(2), 0, "Volume Down", }


반환값

이하는, Microsoft® DirectInput® 메소드와 기능에 의해 돌려주어지는 HRESULT 값의 일람이다. 에러는 부의 값에 의해 나타나 결합할 수가 없다.

각각의 메소드 또는 기능은 에러값을 돌려줄 수가 있지만, 상세한 것에 대하여는 각각의 설명을 참조할것. 본문중의 에러 코드의 일람은, 필연적으로 불완전하게 되어 있다. 예를 들어, 어떤 DirectInput 메소드도 DIERR_OUTOFMEMORY 를 돌려줄 수가 있지만, 본문중에서는, 이 에러 코드는 그 메소드의 반환값으로서는 명시되어 있지 않다.

DI_BUFFEROVERFLOW
디바이스 버퍼가 오버플로우 해, 일부의 입력이 없어졌다. 이 값은, 표준의 COM 반환값인 S_FALSE 에 동일하다.
DI_DOWNLOADSKIPPED
이펙트의 파라미터의 갱신은 성공했지만, 이 이펙트에 관련하는 디바이스가 배타 모드로 취득되어 있지 않기 때문에, 이 이펙트를 다운로드할 수 없다.
DI_EFFECTRESTARTED
이펙트를 정지해, 그 파라미터의 갱신을 실시해, 그 후 이 이펙트를 재개했다.
DI_NOEFFECT
이 조작에 이펙트는 없다. 이 값은, 표준의 COM 반환값인 S_FALSE 에 동일하다.
DI_NOTATTACHED
디바이스는 존재하지만 현재는어태치 상태에 없다. 이 값은, 표준의 COM 반환값인 S_FALSE 에 동일하다.
DI_OK
조작은, 완전하게 종료했다. 이 값은, 표준의 COM 반환값인 S_OK 에 동일하다.
DI_POLLEDDEVICE
디바이스는, 폴링 대상 디바이스이다. 그 결과, 디바이스 버퍼링에서는, 데이터는 일절 수집되지 않고, 이벤트는,IDirectInputDevice8::Poll 메소드가 불려 갈 때까지 통지되지 않는다.
DI_PROPNOEFFECT
디바이스 프로퍼티의 변경은 효과가 없었다. 이 값은, 표준의 COM 반환값인 S_FALSE 에 동일하다.
DI_SETTINGSNOTSAVED
액션 맵은 디바이스에 적용되었지만, 설정 정보는 보존되지 않았다.
DI_TRUNCATED
이펙트의 파라미터의 갱신은 성공했지만, 파라미터중 디바이스의 능력을 넘고 있는 것이 있어, 그것들은 바로 옆의 지원값에 말 수 있었다.
DI_TRUNCATEDANDRESTARTED
DI_EFFECTRESTARTED | DI_TRUNCATED 에 동일하다.
DI_WRITEPROTECT
설정을 변경할 수 없는 것을 나타내는 성공 코드.
DIERR_ACQUIRED
조작은, 디바이스가 취득 상태의 사이는 실행할 수 없다.
DIERR_ALREADYINITIALIZED
이 오브젝트는 초기화가 끝난 상태이다.
DIERR_BADDRIVERVER
오브젝트는, 호환성이 없는 드라이버 버젼, 혹은 부적격 또는 불완전한 드라이버 컴퍼넌트이기 위해서(때문에) 생성 할 수 없었다.
DIERR_BETADIRECTINPUTVERSION
어플리케이션은, DirectInput 의 지원되어 있지 않은 릴리스전의 버젼용으로 생성 된 것이다.
DIERR_DEVICEFULL
디바이스는 풀이다.
DIERR_DEVICENOTREG
디바이스 또는 디바이스 인스턴스가 DirectInput 에 등록되지 않았다. 이 값은, 표준의 COM 반환값인 REGDB_E_CLASSNOTREG 에 동일하다.
DIERR_EFFECTPLAYING
파라미터는, 메모리내에서는 갱신되었지만, 디바이스에는 다운로드되지 않았다. 디바이스가 재생중의 이펙트의 갱신을 지원 하고 있지 않기 때문이다.
DIERR_GENERIC
DirectInput 서브 시스템으로 원인 불명의 에러가 발생했다. 이 값은, 표준의 COM 반환값인 E_FAIL 에 동일하다.
DIERR_HANDLEEXISTS
디바이스는, 이미, 자신에게 이벤트 통지가 관련짓고를 하고 있다. 이 값은, 표준의 COM 반환값인 E_ACCESSDENIED 에 동일하다.
DIERR_HASEFFECTS
디바이스는, 이펙트가 어태치 되고 있기 위해서(때문에) 재초기화할 수 없다.
DIERR_INCOMPLETEEFFECT
필수 정보가 없기 때문에, 이펙트를 다운로드할 수 없었다. 예를 들어, 이펙트에 관련하는 축이 없기도 하고, 타입 고유 정보가 주어지지 않은 경우.
DIERR_INPUTLOST
입력 디바이스의 액세스권을 잃었다. 재취득해야 한다.
DIERR_INVALIDPARAM
무효인 파라미터가 돌아오는 함수에게 건네졌는지, 오브젝트가 그 함수를 호출할 수 있는 상태에 없었다. 이 값은, 표준의 COM 반환값인 E_INVALIDARG 에 동일하다.
DIERR_MAPFILEFAIL
벤더가 제공하는 디바이스의 액션 매핑 파일의 read중인가, 혹은 디바이스의 유저 구성 매핑 파일의 읽어들여 또는 기입해 안에 에러가 발생한 것을 나타낸다.
DIERR_MOREDATA
요구 정보의 일부가 버퍼에 들어가지 않았다.
DIERR_NOAGGREGATION
오브젝트는, 집합화를 지원 하지 않는다.
DIERR_NOINTERFACE
오브젝트는, 지정된 인터페이스를 지원 하고 있지 않다. 이 값은, 표준의 COM 반환값인 E_NOINTERFACE 에 동일하다.
DIERR_NOTACQUIRED
조작은, 디바이스가 취득되지 않는 한 실행할 수 없다.
DIERR_NOTBUFFERED
디바이스는, 버퍼링되어 있지 않다. 버퍼링을 유효하게 하려면 DIPROP_BUFFERSIZE 프로퍼티를 설정한다.
DIERR_NOTDOWNLOADED
이펙트가 다운로드되어 있지 않다.
DIERR_NOTEXCLUSIVEACQUIRED
조작은, 디바이스가 DISCL_EXCLUSIVE 모드로 취득되어 있지 않으면 실행할 수 없다.
DIERR_NOTFOUND
요구된 오브젝트는 존재하지 않는다.
DIERR_NOTINITIALIZED
이 오브젝트는, 초기화되어 있지 않았다.
DIERR_OBJECTNOTFOUND
요구된 오브젝트는 존재하지 않는다.
DIERR_OLDDIRECTINPUTVERSION
어플리케이션은, 보다 새로운 버젼의 DirectInput 를 필요로 한다.
DIERR_OTHERAPPHASPRIO
다른 어플리케이션의 우선 레벨이 높기 때문에, 이 호출의 실행이 잘 되지 않다. 이 값은, 표준의 COM 반환값인 E_ACCESSDENIED 에 동일하다. 이 에러는, 어플리케이션의 디바이스에 대한 액세스권이, foreground 액세스권인 것에도 불구하고, 백그라운드에 있을 때, 디바이스를 취득하려고 했을 경우에 돌려주어진다.
DIERR_OUTOFMEMORY
DirectInput 서브 시스템이 호출을 완료하는데 충분한 메모리를 할당할 수가 없었다. 이 값은, 표준의 COM 반환값인 E_OUTOFMEMORY 에 동일하다.
DIERR_READONLY
지정의 프로퍼티는 변경할 수 없다. 이 값은, 표준의 COM 반환값인 E_ACCESSDENIED 에 동일하다.
DIERR_REPORTFULL
보내지는 정보가, 디바이스에 보낼 수가 있는 정보보다 많다.
DIERR_UNPLUGGED
이 조작은, 디바이스가 접속되어 있지 않을 가능성을 나타낸다.
DIERR_UNSUPPORTED
이 함수 호출은, 이 시점에서는 지원 되지 않는다. 이 값은, 표준의 COM 반환값인 E_NOTIMPL 에 동일하다.
E_HANDLE
이 파라미터는, 이 프로세스에 관계하는 유효한 최상정도의 윈도우 핸들이 아니면 안된다.
E_PENDING
데이터는, 아직 사용 불가이다.
E_POINTER
무효인 포인터 (보통은 NULL)가 파라미터로서 건네받았다.


DirectPlay

Microsoft® DirectPlay® 어플리케이션 프로그래밍 인터페이스 (API)는, Microsoft DirectX® 의 컴퍼넌트이며, 멀티 플레이어 게임등의 네트워크 어플리케이션의 기술을 가능하게 한다.

DirectPlay 는, DirectX 외의 컴퍼넌트와 같이, C, C++, 및 Microsoft Visual Basic® 로 사용할 수 있다.

DirectPlay 헬프 전체의 구성에 대해서는, 「도로지도」를 참조할것.


도로지도

Microsoft® DirectPlay® 에 관한 정보는, 다음과 같이 구성되어 있다.

DirectPlay 의 신기능 . Microsoft DirectX® 8 에서의 이 컴퍼넌트의 새로운 기능. 이전 DirectPlay 를 사용했던 적이 있는 경우는, 이 항목을 최초로 읽는 것. 이 기술은 DirectX 7 이후에 완전하게 재설계되었다.

DirectPlay 의 개요 . DirectPlay 란 무엇인가, 어플리케이션에 있어 어떻게 도움이 될까에 임해서 개요를 나타내, 주요한 오브젝트와 네트워크 어플리케이션을 생성 하기 위해서 필요한 순서를 간단하게 설명한다.

DirectPlay 에 대해 . 기본으로 되는 메카니즘을 상세하게 해설한다. DirectPlay 세션의 이행 방법에 대해서는 설명하지 않지만, 이행의 상세를 취급하는 시점에서 어플리케이션 프로그래밍 인터페이스 (API)를 이해하는데 도움이 된다.

DirectPlay 의 사용법 . API 의 사용에 관한 안내. 이 항목에 있는 목차로 전체를 파악해, 구체적인 정보가 필요하게 되었을 때에 각 부분을 참조할 수 있다. 레퍼런스 정보와 함께 사용하는 것.

DirectPlay C++ 샘플 . SDK 의 C/C++ 샘플 어플리케이션의 가이드.

DirectPlay C/C++ 레퍼런스 . DirectPlay C++ API 의 상세 정보.


DirectPlay 의 신기능

Microsoft® DirectX® 의 네트워크 컴퍼넌트는 크게 변경되었다. Microsoft DirectPlay® 에는, 새로운 인터페이스 세트가 도입되어 하드웨어에의 직접 액세스가 지금까지 이상으로 가능하게 되어, 퍼포먼스가 향상했다.

DirectPlay 의 주된 신기능을 다음에 나타낸다.

인터페이스가 완전하게 고쳐 쓸 수 있었다.
피어 투 피어 세션과 클라이언트/서버 세션을 생성 하는 인터페이스를 분리하는 것으로써, 복잡한 네트워크 어플리케이션의 생성이 용이하게 되었다. DirectPlay 트랜스폴트 세션의 생성에 사용하는 인터페이스를 다음에 나타낸다. 이러한 인터페이스는 Dplay8.h 헤더 파일에 정의되고 있다.
IDirectPlay8Peer
피어 투 피어 세션을 생성 하는 메소드를 제공한다.
IDirectPlay8Client
클라이언트/서버 어플리케이션의 클라이언트 부분을 생성 하는 메소드를 제공한다.
IDirectPlay8Server
클라이언트/서버 어플리케이션의 서버 부분을 생성 하는 메소드를 제공한다.
로비가 DirectPlay 의 나머지의 부분으로부터 떼어내졌다.
로비 클라이언트는 DirectPlay 어플리케이션과 함께 실행할 필요가 없어졌다. 로비 서비스 프로바이더 또는 어플리케이션은, 상대를 고려하는 일 없이, DirectPlay 를 이행 할 수 있게 되었다. 로비의 이행은, Dplobby8.h 헤더 파일에 정의된, 다음의 2 개의 간이 인터페이스에 분할되었다.
IDirectPlay8LobbyClient
이 인터페이스는, 로비 클라이언트의 관리, 및 로비 대응 어플리케이션의 열거와 기동에 사용한다.
IDirectPlay8LobbiedApplication
이 인터페이스를 사용해, 로비 기동 가능한 어플리케이션을 시스템에 등록해, 어플리케이션을 로비 기동할 수 있도록(듯이) 한다. 또, 이 인터페이스를 사용 하면, 로비로부터 접속 정보를 취득해, 유저에게 문의하지 않고 게임을 기동할 수도 있다.
음성 전송이 추가되었다.
DirectPlay Voice 는, 어플리케이션에 리얼타임의 음성 통신을 추가하는 일련의 인터페이스를 제공한다. 다음의 인터페이스가 Dvoice.h 헤더 파일에 정의되고 있다.
IDirectPlayVoiceClient
DirectPlay Voice 세션으로 클라이언트를 생성 해, 관리하는 메소드를 제공한다.
IDirectPlayVoiceServer
DirectPlay Voice 세션을 호스트 해, 관리하는 메소드를 제공한다.
IDirectPlayVoiceTest
DirectPlay Voice 의 오디오 구성의 테스트에 사용한다.
주소 정보가 GUID 베이스의 데이터로부터 URL 베이스의 데이터 형식에 이행 되었다.
DirectPlay 의 이전의 버젼에서는, 이행 하기 어렵고, 인간에게는 읽어내 불가능한 GUID 주소를 사용한 바이너리 데이터를 사용하고 있었다. DirectX 8.0 의 DirectPlay 에서는, URL 형식의 주소 표기가 도입되었다. Dpaddr.h 에 정의되고 있는 일련의 인터페이스를 사용해, 새로운 주소 포맷을 생성 해, 조작할 수 있다.
IDirectPlay8Address
DirectPlay 주소의 생성과 조작에 사용하는 범용 애드레싱 메소드를 제공한다.
IDirectPlay8AddressIP
IP 프로바이더 고유의 애드레싱 서비스를 제공한다.
한층 더 높은 확장성과 개선된 메모리 메니지먼트가 추가되었다.
이용자측의 대역폭의 증가는, 네트워크 게임의 설계와 이행에 큰 영향을 주었다. DirectPlay 에서는, thread 풀 관리가 향상했기 때문에, 개발자는 스케이라불로 보다 견뢰하고, 다수의 멀티 플레이어 온라인 어플리케이션을 지원 할 수 있는 어플리케이션을 간단하게 생성 할 수 있게 되었다.
파이어 월(fire wall)의 지원이 강화되어 네트워크 주소 트랜스레이터가 추가되었다.
네트워크 주소 트랜스레이터 (NAT), 파이어 월(fire wall), 및 그 다른 인터넷 접속 공유 (ICS) 방법을 통과하는 네트워크 게임의 생성은 곤란한 일이 있다. 특히, 비보증 (UDP) 트래픽의 경우, 곤란하다. DirectPlay 8.0 에서는 이러한 문제가 고려되고 있기 (위해)때문에, 가능한 한 NAT 솔루션이 지원 되고 있다. DirectPlay 8 의 TCP/IP 서비스 프로바이더에서는, 게임 데이터용으로서 단일의 UDP 포토를 사용해, 개발자는 그 포토를 선택할 수 있다. 따라서, 파이어 월(fire wall)나 NAT 를 적절히 구성할 수 있다. 또, DirectPlay 는 UDP 를 이용해, 클라이언트/서버 게임에 대해, 일부의 NAT 가 대상으로 하는 클라이언트가 구성을 추가하지 않고 게임에 접속할 수 있게 한다.


DirectPlay 의 개요

Microsoft® DirectPlay® API 는, 게임이나 채팅 클라이언트 등 멀티 플레이어 어플리케이션을 개발하기 위한 툴을 개발자에게 제공한다. 알기 쉽게하기 위해(때문에), 이 메뉴얼에서는, 이러한 어플리케이션을 모두 「게임」이라고 부른다. 멀티 플레이어 어플리케이션에는, 2 개의 기본적 특징이 있다.

  • 각자의 컴퓨터상에 게임 클라이언트를 가지는 복수의 개인 유저가 있다.
  • 유저의 컴퓨터를 상호 접속하기 위한 (아마 중앙 서버 경유의) 네트워크 링크가 있다.

DirectPlay 는, 기본이 되는 네트워크로부터 어플리케이션을 크게 격리하는 계층을 제공한다. 대부분의 용도에서는, 어플리케이션은 단지 DirectPlay API 를 사용해, DirectPlay 가 네트워크 통신의 상세를 처리할 수 있도록(듯이) 한다. DirectPlay 는, 멀티 플레이어 어플리케이션의 다양한 면의 이행 프로세스를 용이하게 하기 위한(해), 이하와 같이 많은 기능을 제공한다.

  • 피어 투 피어 세션과 클라이언트/서버 세션의 양쪽 모두를 생성 해 관리한다.
  • 세션내의 유저와 그룹을 관리한다.
  • 네트워크 링크나 네트워크 조건이 다른 세션 멤버간에서의 메시징을 관리한다.
  • 어플리케이션과 로비와의 대화를 가능하게 한다.
  • 유저 상호의 음성 통신을 가능하게 한다.

이 문서는, DirectPlay 의 능력의 고도의 개요를 해설한다. 이하의 주제에서는, 멀티 플레이어 게임에서의 DirectPlay 의 사용 방법의 상세를 설명한다.

  • 세션의 생성과 관리
  • DirectPlay 네트워크 통신
  • DirectPlay 오브젝트와의 통신
  • DirectPlay 로비 지원
  • DirectPlay 음성 통신


세션의 생성과 관리

게임의세션이란, 특정의 멀티 플레이어 게임의 1 개의 인스턴스이다. 1 개의 세션에는 동시에 플레이 하는 복수의 유저가 있어, 각각이 자신의 컴퓨터상에 게임 클라이언트를 가지고 있다. 플레이어란, 게임안의 엔티티이며, 각 게임에 의해 정의된다. 각 유저가, 1 개의 게임에 1 명 이상의플레이어를 가지는 경우도 있다. 다만, 게임 어플리케이션은, 개별의 Microsoft® DirectPlay® 인터페이스 또는 각 플레이어의 오브젝트를 사용해, 이러한 플레이어를 어플리케이션 자신으로 관리해야 한다.

세션 생성의 최초의 순서는, 유저 그룹의 수집이다. 2 개의 기본적 방법이 있다.

  • 많은 게임 세션은, 리모트 컴퓨터로 실행되고 있는로비 어플리케이션에 의해 어레인지 되고 있다. 이 방법은, 많은 인터넷 베이스의 게임에서 사용되고 있다.
  • 또, 각 유저의 컴퓨터를 서로 통신시켜 게임을 어레인지 할 수도 있다. 이 방법은, 일반적으로, 참가하는 유저 그룹이 모두 같은 LAN 상에 존재하는 것 같은 경우로 한정된다.

세션이 어레인지 되면(자), 게임이 기동해, 게임 플레이가 시작 된다. 세션이 진행되는 것에 따라, 플레이어가 세션으로부터 사라지거나 새로운 플레이어가 추가 되거나 한다. 자세한 것은 개개의 게임에 따라서 다르다.

멀티 플레이어 게임에서는, 각 유저의 UI 는, 세션내외의 모든 유저의 UI 와 동기 할 수가 있다. 따라서, 멀티 플레이어 세션의 관리에는, 유저 사이에서의 계속적인 메세지의 스트림이 필요하다. 예를 들어, 플레이어가 이동할 때마다 메세지가 송신되어 세션내외의 모든 게임 클라이언트상에서의 그 플레이어의 위치가 갱신된다. DirectPlay 의 중요 부분은, 세션내의 모든 컴퓨터간에서의 효율적 한편 유연한 메세지 송신을 지원 하는 API 부분이다.

세션에서의 메세지 송신의위상기하학구축에는, 주로 2 개의 방법이 있다. 피어 투 피어와클라이언트/서버이다. 어느 쪽의 위상기하학에도 이점과 제약이 있기 (위해)때문에, 어느 쪽이 자신의 게임에 적절하고 있는지를 평가할 필요가 있다.

여기에서는 설명하는 주제는, 다음과 같다.

  • 피어 투 피어 위상기하학
  • 클라이언트/서버 위상기하학


피어 투 피어 위상기하학

피어 투 피어의 게임은, 네트워크 링크로 접속된 각 플레이어의 컴퓨터에 의해 구성된다. 4 명의 플레이어에 의한 피어 투 피어 게임의 위상기하학을 도해 하면, 다음과 같이 된다.

게임 플레이는, 각 유저의 게임 클라이언트를 다른 유저의 클라이언트와 직접 통신시키는 것에 의해 처리된다. 예를 들어, 어느 유저가 이동했을 때, 게임 클라이언트는, 다른 유저의 컴퓨터 1 대에 대해서 1 개씩, 합계 3 개의 갱신 메세지를 송신해야 한다.

피어 투 피어 게임은, 유저의 컴퓨터상에 상주하는로비 클라이언트 어플리케이션에 의해 어레인지 되어 기동하는 것이 보통이다. 로비 클라이언트가 세션을 어레인지 하는 경우, 이하와 같은 2 개의 기본적인 방법이 있다.

  • 로비 클라이언트가 다른 잠재적 유저 로비 클라이언트와 직접 통신한다. 이 방법은, 예를 들어 같은 LAN 서브 넷 위에의 유저에게 게임을 어레인지 하는 경우에 사용할 수 있다.
  • 로비 클라이언트가, 리모트 컴퓨터상에서 실행되고 있는 로비 서버 어플리케이션에의 링크로서 기능한다. 인터넷 베이스의 게임은 보통은 이 방법으로 어레인지 되고 있다.

세션이 어레인지 되고 기동 하면, 메세지 송신의 대부분 또는 모든 것이 유저 사이의 메세지가 된다. 로비 서버가 관여하고 있는 경우, 이 서버는, 플레이어가 게임으로부터 멀어졌을 때에 세션 멤버의 리스트를 갱신하거나 새로운 유저가 세션에의 참가를 요구할 수 있도록(듯이) 하는 것만으로 있다. 처리가 필요없는 경우는, 서버는 백그라운드에 머물러, 일반적으로는 송신되고 있는 메세지도 거의 인식할 것은 없다.

서버는, 존재하지 않는지, 적어도 게임 플레이에는 직접 관계되지 않기 때문에, 1 명의 유저가 게임의호스트로 지정된다. 호스트는, 진행중의 세션에의 새로운 플레이어의 참가 등, 논리적인 상세를 처리한다.

피어 투 피어 게임의 이점은, 그 단순함이다. 필요한 것은, 게임 클라이언트를 갖춘 플레이어의 집단과 세션을 정리하는 방법뿐이다. 피어 투 피어 위상기하학의 최대의 약점은, 스케이라비리티에 있다. 유저수가 증가 하면, 거기에 비례해 게임 플레이를 처리하기 위해서 필요한 메세지수도 증가한다. 참가할 수 있는 유저의 최대수는, 게임이나 네트워크의 대역폭에도 밤이, 일반적으로는 20 ~ 30 명 이내이다.


클라이언트/서버 위상기하학

클라이언트/서버 게임은, 중앙의 서버 컴퓨터에 접속된 각 플레이어의 컴퓨터에 의해 구성된다. 4 명의 플레이어에 의한 클라이언트/서버 게임의 위상기하학을 도해 하면, 다음과 같이 된다.

게임 플레이는, 각 유저의 게임 클라이언트를 서버와 통신시키는 것에 의해 처리된다. 서버는, 책임을 가져, 다른 유저에게 정보를 건네준다. 예를 들어, 어느 유저가 이동 하면, 메세지가 서버에 송신된다. 하면 서버는, 다른 플레이어에게 메세지를 송신해, 게임 상태의 변경을 알린다. 서버에는, 몇개의 역할을 할당할 수가 있다.

  • 세션의 메세지 송신 허브로서 기능한다. 각 컴퓨터는, 서버에 메세지를 송신하는 것만으로 좋다. 서버는, 다른 모든 유저를 동기 시키기 위한 로지스틱을 처리한다. 이 방법에서는, 특히 큰 게임의 경우, 메세지의 트래픽을 큰폭으로 삭감할 수가 있다.
  • 게임의 호스트가 된다. 서버는 보통, 피어 투 피어로 세션 호스트가 처리해야 했던 태스크를 맡는다.
  • 게임의 여러가지 면을 지원 한다. 서버는, 많은 경우, 게임의 로지스틱을 지원 하는 이상의 일을 실시한다. 많은 게임, 특히 큰 게임에서는, 「게임 세계」를 유지하기 위한 처리는 거의 서버상에서 실행된다. 게임 클라이언트의 주된 일은, 유저의 UI 를 처리하는 것이다.

보통, 클라이언트/서버 게임은, 유저의 컴퓨터상에 상주하는로비 클라이언트 어플리케이션에 의해 어레인지 되어 기동한다. 로비 클라이언트는, 게임을 호스트 하고 있는 컴퓨터와 같은 리모트 컴퓨터상에서 실행되고 있는 로비 서버 어플리케이션에의 링크로서 기능한다. 게임이 기동 하면, 게임 서버 어플리케이션이 호스트가 되어, 새로운 유저에게로의 참가 허가등의 태스크를 처리한다.

클라이언트/서버 게임에는, 몇개의 이점이 있다.

  • 특히 대규모 게임에서는, 효율성이 높다. 특히, 플레이어가 증가해도 메세지 송신 트래픽의 회선이 증가할 뿐(만큼)이므로, 피어 투 피어보다 스케일적으로 우수하다. 대량의 데이터를 취급하는 멀티 플레이어 게임에는, 클라이언트/서버 위상기하학이 필요하다.
  • 유저의 컴퓨터의 처리 능력에 의한 제한을 받지 않는다. 크고 복잡한 「게임 세계」를 유지하기 위해(때문에) 필요한 처리의 대부분을 1 대의 강력한 컴퓨터상에 배치해, 유저의 컴퓨터에는 UI 를 처리시킬 수가 있다.
  • 게임의 중요한 부분을 중앙의 사이트에서 제어할 수 있다. 예를 들어, 서버 어플리케이션을 변경하는 것만으로, 게임을 갱신하거나 버그를 수정할 수 있어 다수의 게임 클라이언트를 갱신할 필요가 없다.

다만, 피어 투 피어 게임은 개발해 출하하면 실질상 일이 끝난다. 게임 클라이언트는 거의 자기 완결형이다. 클라이언트/서버 게임에서는, 보통의 지원 서비스를 제공하는 것 외에, 유저에 대해서 게임의 진행중도 관계되게 된다. 또, 게임 서버 컴퓨터나 관련 소프트웨어와 함께, 모든 메세지 송신을 처리하기 위한 네트워크 링크를, 어플리케이션의 제품 수명이 계속되는 한, 제공해, 유지해야 한다. 대량의 데이터를 사용하는 멀티 플레이어 게임의 경우, 거의, 또는 완전히 휴일 없이 서버를 운용할 필요가 있어, 유저의 게임 플레이를 중단 하면 유저를 화나게 한다고 하는 리스크도 있다.


DirectPlay 네트워크 통신

Microsoft® DirectPlay® 의 최대의 기능은, 유저에게, 어플리케이션을 기본이 되는 네트워크 하드웨어 및 소프트웨어로부터 크게 격리해, 효율적으로 유연한 메시징 지원을 제공하는 것이다. 상태 갱신을 송신할 필요가 있는 경우, 사용하고 있는 네트워크의 종류에 관계없이, 다만 대응하는 DirectPlay API 를 호출하면 좋다. DirectPlay 네트워크 서비스 프로바이더는, TCP/IP, IPX, 모뎀, 시리얼 링크에 의한 통신을 지원 한다.

여기에서는 설명하는 주제는, 다음과 같다.

  • DirectPlay 트랜스폴트 프로토콜
  • DirectPlay 주소

주

DirectPlay 는 시큐러티에 의한 통신은 지원 하고 있지 않다.

Microsoft Windows® 95 시스템으로 모뎀을 사용하려면 , Telephony API (TAPI)의 버젼 2.0 을 인스톨 할 필요가 있다. TAPI 2.0 은 http://www.microsoft.com/ 로부터 다운로드할 수 있다.


DirectPlay 트랜스폴트 프로토콜

Microsoft® DirectPlay® 네트워킹 능력의 중심은, DirectPlay 프로토콜이다. 이 트랜스폴트 계층 프로토콜은, DirectPlay 8 용으로 완전하게 오버홀 되어 모든 메시징에 사용되고 있다. DirectPlay 프로토콜은, 송신중에 무엇이 일어나고 있는지를 걱정할 필요없고, 송신측 어플리케이션으로부터 타겟 어플리케이션에의 데이터 송신을 간단하게 하는 것에 초점을 두고 있다. 이 프로토콜은, 멀티 플레이어 게임의 필요성에 응해 조정된, 다음과 같은 기능을 제공한다.

  • 신뢰성의 높은 메세지 전달과 신뢰성의 낮은 메세지 전달. 신뢰성의 높은 메세지는, 타겟 어플리케이션이 메세지를 받아들일 때까지 재발송신 된다. 전달의 타입은, 메세지 마다 할당할 수가 있다.
  • 시퀀셜 메세지 전달과 비시퀀셜 메세지 전달. 시퀀셜 메세지는, 송신된 순서에 타겟 어플리케이션에게 건네진다.
  • 메세지의 분할과 재구축. 메세지 사이즈가 네트워크의 용량을 넘는 경우, DirectPlay 는 자동적으로 메세지를 분할해 재구축 한다.
  • 혼잡의 제어. DirectPlay 는, 처리중의 메세지를 타겟을 처리할 수 있는 레벨에 자동적으로억제한다. 이 기능에 의해, 타겟으로 처리할 수 없을 정도 대량의 메세지가 송신되지 않게 한다.
  • 송신의 우선 순위 붙어라. 중요한 메세지(정도)만큼 빨리 송신하기 위해서, DirectPlay 에서는, 메세지에 저, 표준, 고의 우선도를 할당할 수가 있다. 우선도의 높은 메세지가 출력 큐의 정면으로 송신되어 그 후, 표준 우선도, 우선도의 낮은 메세지가 송신된다.
  • 메세지의 타임 아웃. 현재 처리중의 메시지 큐가, 새로운 메세지에 의해 밀린 낡은 메세지로 막히는 것이 없게, DirectPlay 에서는, 모든 메세지에 타임 아웃값을 할당할 수가 있다. 메세지가 타임 아웃 하면, 그 메세지는, 송신이 끝난 상태인가 어떤가에 관계없이, 처리중의 메시지 큐로부터 삭제된다.


DirectPlay 주소

메세지를 전달하려면 , 멀티 플레이어 게임의 각 참가자가 일의의 주소를 가지고 있을 필요가 있다. 주소는, 어플리케이션을 실행하고 있는 컴퓨터를 참조하는지 (디바이스 주소), 어플리케이션이 통신할 필요가 있는 컴퓨터를 참조할 수 있다 (호스트 주소).

Microsoft® DirectPlay® 주소는, URL 캐릭터 라인의 형태를 취한다. 이러한 캐릭터 라인은, 다음에 나타내는 일반 형식의 스킴, 스킴 separator, 및 데이터 캐릭터 라인으로 구성된다.

x-directplay:/[data string]

데이터 캐릭터 라인에는 몇개의 요소가 포함되어 있다. 이러한 요소는, 발신자와 타겟이 각종 네트워크 링크를 개입시켜 통신을 실시하기 위해서(때문에) 필요한 것을 모두 지정한다.

사용해서는, URL 캐릭터 라인은 DirectPlay API 메소드와 교환되는 DirectPlay 주소 오브젝트에 파묻힌다. URL 캐릭터 라인을 직접 조작하는지, 또는 주소 오브젝트에 의해 공개되는 메소드를 사용해, 데이터 캐릭터 라인의 각 요소를 개별적으로 처리할 수 있다.


DirectPlay 오브젝트와의 통신

Microsoft® DirectPlay® 는, 본질적으로는 COM 오브젝트의 1 개의 콜렉션으로 구성되어 있다. 각 오브젝트는, DirectPlay 의 여러가지 면을 제어하기 위한 1 개(살) 이상의 인터페이스를 공개한다. 예를 들어, DirectPlay 피어 오브젝트 (CLSID_DirectPlay8Peer)는, 피어 투 피어 게임의 관리에 사용된다.

DirectPlay 오브젝트와 통신하려면 , 오브젝트의 인터페이스가 공개하는 메소드를 호출한다. 예를 들어, 피어 투 피어 게임에서 다른 유저에게 어떠한 데이터를 송신하려면 ,IDirectPlay8Peer::SendTo 메소드를 호출해 메세지를 송신한다. 그리고 DirectPlay 에 의해, 타겟으로 메세지가 도착된다.

DirectPlay 는, 1 개(살) 또는 복수의콜백 함수를 개입시켜 유저의 어플리케이션과 통신한다. 이러한 함수는 원칙으로서 익숙해진 Window 프로시저 와 유사한다. 어플리케이션은 콜백 함수를 이행 해, 초기화시에, 함수에의 포인터를 DirectPlay 에 건네준다. DirectPlay 가 어플리케이션과 통신할 필요가 있을 때는, 콜백 함수를 호출해, 정보의 2 개의 주요 항목에 건네준다.

  • 메세지의 형태를 식별하는 메세지 ID.
  • 필요한 상세를 제공하는 데이터 블록에의 포인터, 일반적으로는 구조체.

예를 들어, 위의예로 송신된 메세지가 타겟으로 도착하면(자), 타겟 어플리케이션의 콜백 함수는, 메세지가 다른 유저로부터 보내진 것을 나타내는, DPNMSGID_RECEIVE 메세지 ID 가 붙은 메세지를 받아들인다. 부수 하는 구조체에는 데이터가 저장 되고 있다.

DirectPlay 메시징의 상당수는 multi-thread로 실행되기 (위해)때문에, 콜백 함수는 올바르게 이행 하는 것이 중요하다.


DirectPlay 로비 지원

로비는, 플레이어가 게임을 만나거나 어레인지 할 수 있도록(듯이) 하는 것을 주목적으로 하는 어플리케이션이다. 로비는 보통 리모트 컴퓨터상에 있어, 인터넷을 개입시켜 액세스 된다. 또 로비 서버는, 대화방의 호스팅, 뉴스나 정보의 POS 팅, 상품의 판매 등, 여러가지 기능도 실행한다. 로비 서버는 편리한 기능이며, 멀티 플레이어 게임의 어레인지에 일반적으로 사용되지만, 필수 조건은 아니다. 또 멀티 플레이어 게임은, 로비 클라이언트 끼리의 직접 통신에 의해 어레인지 할 수도 있다.

보통, 게임이 로비라고 대화할 수 있도록(듯이) 하기 위해서는, 3 개의 컴퍼넌트가 필요하다.

  • 로비 서버
  • 로비 클라이언트
  • 로비 대응 게임

Microsoft® DirectPlay® 는, 로비 서버 어플리케이션의 이행 방법은 지정하지 않는다. 대신에, DirectPlay 는 로비 클라이언트의 지원을 제공한다. 로비 클라이언트는, 로비 서버 벤더에 의해 이행 되어 각 유저의 시스템에 인스톨 되는 어플리케이션이다. 이것은, 유저와 로비의 링크로서 유용하다. 이러한 통신을 직접 처리할 수도 있지만, 그 때문에(위해)는 자신의 게임을 기동하는 모든 로비의 이행의 상세를 알지 않으면 안 된다.

로비 클라이언트 어플리케이션은, 적절한 프로토콜을 사용해, 관련하는 로비 서버와의 통신의 상세를 처리한다. 로비 클라이언트는, DirectPlay 인터페이스에 의해 유저나 유저의 게임 어플리케이션과 통신한다. 그 때, DirectPlay 는 어플리케이션에 메세지를 건네준다. 또 어플리케이션은, DirectPlay 인터페이스를 사용해 로비 클라이언트에 메세지를 건네줄 수가 있다.

로비는, 실질적으로 어떤 어플리케이션이라도 기동할 수 있다. 다만, 어플리케이션이 로비 기동의 이점을 풀 활용하려면 , 몇개의 특정의 로비아웨아콘포넨트를 가지고 있을 필요가 있다. 특히, 로비 대응 어플리케이션은, 세션 전체를 통해 로비 클라이언트와 통신할 수가 있다. 어플리케이션이 로비 대응으로서 등록되어 있는 경우, 로비 클라이언트는, 호스트의 이행 등, 게임 상태의 여러가지 변경에 대한 갱신도 자동적으로 받는다.


DirectPlay 음성 통신

현재의 경향은 팀 베이스의 멀티 플레이어 게임이기 (위해)때문에, 플레이어끼리의 통신이 게임 플레이의 불가결한 부분이 되고 있다. 역사적으로 플레이어끼리의 통신은 텍스트 베이스에 제약되어 왔다. 플레이어는 팀메이트 앞의 메세지를 키보드로부터 입력하고 있었다. 텍스트 베이스의 통신은, 스피드의 늦은 턴 베이스의 게임에는 적합하지만, 리얼타임 게임에서는 불편하고 밖에 없다. 키보드 입력의 늦은 플레이어가 게임에서 불리하게 될 뿐만이 아니고, 게임이 창출하려고 하고 있는 리얼리티를 현저하게 방해할 수 있다. 이 문제의 명백한 해결책은, 통신 수단으로서 음성을 사용하는 것이다. 이 해결책은, 트레이닝의 필요가 없고, 게임 자체에의 집중을 높인다.

Windows 플랫폼에서는, 비디오 게임 개발자전용으로, 리얼타임 음성 회의의 이행에 필요한 모든 툴이 준비되어 있지만, 게임 개발자의 측에 다대한 노력이 요구된다. 이것은, 극단적으로 대역폭의 적은 상황에 대응할 수 있는 압축 기술의 권리를 취득하는 비용과 곤란함과 함께, 게임에 있어서의 음성 사용의 확대를 방해해 왔다.

Microsoft® DirectPlay® 8.0 은, 게임 개발자에게, 최소한의 노력으로 사용할 수 있는 견뢰한 리얼타임 음성 회의 시스템을 제공한다.


DirectPlay 에 대해

Microsoft® DirectPlay® 문서의 이 섹션에서는, 어플리케이션에서의 DirectPlay API 의 사용법을 이해하기 위해서 필요한 기본적 배경에 대해 설명한다.

  • 피어 투 피어 세션
  • 클라이언트/서버 세션
  • DirectPlay 의 로비
  • 네트워킹의 기본
  • DirectPlay 콜백 함수와 multi-thread에 관한 문제
  • DirectPlay Voice 에 대해


피어 투 피어 세션

피어 투 피어 세션은, 네트워크로 접속된 유저의 집합으로부터 구성된다. 게임의 준비와 기동에는 로비 서버를 사용하는 일이 있지만, 게임의 실행에 필요한 메시징은 유저 사이에 직접 교환한다. 로비 서버와의 통신은, 참가자 리스트의 갱신이라고 한 한정된 목적에게만 사용한다.

피어 투 피어의 게임에서는, 게임의 실행에 필요한 일이 모두 클라이언트 소프트웨어에 속한다. 서버가 관계하지 않기 때문에, 게임 전체를 생성 해, 유지하기 위해서 필요한 처리는, 모두 클라이언트 어플리케이션으로 실시하지 않으면 안 된다. 이 문서에서는, Microsoft® DirectPlay® 에 의한 로비 가능한 피어 투 피어 게임의 기본적 원리를 설명한다. 피어 투 피어 어플리케이션의 간단한 실례에 대해서는, SDK 부속의 SimplePeer 어플리케이션을 참조할것.

  • 피어 투 피어 세션의 시작
  • 피어 투 피어 세션에 사용하는 서비스 프로바이더의 선택
  • 피어 투 피어 세션에 사용하는 호스트의 선택
  • 피어 투 피어 세션에의 접속
  • 피어 투 피어 세션의 관리
  • 호스트의 이행
  • 피어 투 피어 게임의 보통의 플레이
  • 피어 투 피어 세션으로부터의 이탈
  • 피어 투 피어 세션의 종료


피어 투 피어 세션의 시작

피어 투 피어 게임은, 유저가 직접 기동하는 일도, 유저의 컴퓨터에 상주하는 "로비 클라이언트" 어플리케이션으로부터 "로비 기동" 할 수도 있다. 이 문서에서는, 로비 클라이언트와 통신할 수 있는 로비 가능한 게임을 상정해 설명한다.

실행해야 할 최초의 스텝의 1 개는, 게임이 로비 기동으로 기동되고 있는지 어떤지를 판단하는 것이다. 이것에는, 로비 대상 어플리케이션 오브젝트 (CLSID_DirectPlay8LobbiedApplication)를 생성 해, 초기화한다. 이 때, 로비 대상 어플리케이션의 콜백 메세지 핸들러에의 포인터를, 오브젝트에 건네준다. 이 메세지 핸들러는, 로비 대상 오브젝트로부터는 직접, 로비 클라이언트 및 로비로부터는 간접적으로, 메세지를 수신한다.

  • 어플리케이션이 로비 기동으로 기동되고 있으면,IDirectPlay8LobbiedApplication::Initialize 메소드가 로비 클라이언트에의 접속 핸들을 돌려주어, 로비 대상 어플리케이션의 메세지 핸들러에 DPL_MSGID_CONNECT 메세지가 송신된다. 관련하는 구조체의 pdplConnectionSettings 멤버는, 세션 멤버의 주소 오브젝트등의 접속 정보가 들어간 DPL_CONNECTION_SETTINGS 구조체를 가리킨다.
  • 어플리케이션이 로비 기동으로 기동되어 있지 않으면, 접속 핸들도 메세지도 도착하지 않는다. 다만,IDirectPlay8LobbiedApplication::SetAppAvailable 를 호출하면, 로비 클라이언트가, 로비 대상 어플리케이션의 메세지 핸들러에 DPL_MSGID_CONNECT 메세지를 송신하는 것으로써, 실행중의 어플리케이션을 세션에 나중에 접속할 수가 있다.

또, 피어 오브젝트 (CLSID_DirectPlay8Peer)를 생성 해, 초기화할 필요도 있다. 이 오브젝트가, Microsoft® DirectPlay® 및 세션내의 나머지 멤버와의 주된 통신 수단이 된다. 세션에 복수의 플레이어를 참가시키기 위해서(때문에)는, 플레이어 마다 이 오브젝트의 인스턴스를 생성 할 필요가 있다.


피어 투 피어 세션에 사용하는 서비스 프로바이더의 선택

이 경우, 사용중의 네트워크 접속이 서비스 프로바이더가 된다. TCP/IP 또는 모뎀의 서비스 프로바이더를 사용하는 게임이 많지만, Microsoft® DirectPlay® 는 시리얼 접속과 IPX 접속에도 대응하고 있다.

유저가 로비 클라이언트로 세션에 접속되고 있는 경우에는,DPL_MSGID_CONNECT 메세지에 부속되는 DPL_CONNECTION_SETTINGS 구조체를 조사하면, 적절한 서비스 프로바이더를 판단할 수 있다. 그 이외의 경우, 사용하는 서비스 프로바이더를 판단하려면 , 유저에게 조회하는 등 방법을 취할 필요가 있다. 피어 오브젝트의 IDirectPlay8Peer::EnumServiceProviders 메소드를 사용 하면, 이용 가능한 서비스 프로바이더를 열거할 수 있다. 상세한 것에 대하여는,「DirectPlay 열거의 사용법」을 참조할것.

서비스 프로바이더를 선택 하면, 유저의 DirectPlay 주소 오브젝트 (디바이스 주소)를 생성 할 수 있게 된다. DirectPlay 가 많은 메소드에서는, 이 주소를 사용해 디바이스를 식별한다. DirectPlay 주소와 주소 오브젝트의 상세한 것에 대하여는,「DirectPlay 아드레싱」을 참조할것.


피어 투 피어 세션에 사용하는 호스트의 선택

피어 투 피어 게임에는, 개개의 유저가 직접 교환해 처리할 수 있는 요소도 많지만, 단독의 오너가 담당해야 할 작업도 있다. 이러한 작업은, 게임 호스트가 실시한다. 세션에 참가하려면 , 세션 호스트의 주소를 알고 있을 필요가 있다. 보통, 호스트의 선택은 로비 서버를 통해서 실시한다. 이 경우, 유저의 어플리케이션이 세션에 접속되면(자),DPL_MSGID_CONNECT 메세지와 함께 접속 설정이 닿아, 그 접속 설정에 호스트의 주소 오브젝트가 포함되어 있다. 세션 호스트를 조사하려면 , 이하의 처리를 실행한다.

  • 돌려주어진 DPL_CONNECTION_SETTINGS 구조체의 dwFlags 멤버를 조사한다. 이 멤버가 DPLCONNECTSETTINGS_HOST 로 설정되어 있는 경우는, 사용중의 시스템이 호스트이다.
  • DPLCONNECTSETTINGS_HOST 플래그가 설정되어 있지 않은 경우는,pdp8HostAddress 멤버로부터 호스트의 주소를 취득할 수 있다.

또, 자신이 세션 호스트인 것을 공표해, (예를 들어 LAN 서브 넷상에서) 어느 요소를 전요소에 카피하는 세션을 생성 할 수도 있다. 이것에는,IDirectPlay8Peer::SetPeerInfo 를 호출해 플레이어명을 설정하고 나서,IDirectPlay8Peer::Host 를 호출해 자신이 호스트의 후보인 것을 공표한다. 게임의 구성은,IDirectPlay8Peer::Host 의 pdnAppDesc 의 파라미터로 건네주는 DPN_APPLICATION_DESC 구조체에 값을 할당해 지정한다.

이용 가능한 세션과 호스트를 유저에게 알리려면 ,IDirectPlay8Peer::EnumHosts 를 호출하면, 이용 가능한 호스트를 열거할 수 있다. 유저가 세션을 선택 하면, 접속을 요구할 수 있게 된다.


피어 투 피어 세션에의 접속

세션 호스트가 아닌 한, 플레이어를 세션에 접속할 필요가 있다. 이것에는, 세션 호스트의 주소가 필요하게 된다. 어플리케이션이 로비 클라이언트로부터 접속되고 있는 경우는,IDirectPlay8LobbiedApplication::GetConnectionSettings 를 호출하면, 호스트의 주소를 취득할 수 있다. 호스트의 주소는, 이용 가능한 호스트를 열거해 취득할 수도 있다. 열거로부터 돌려주어지는 정보에는, 각 호스트의 주소와 관련하는 세션을 기술하는 DPN_APPLICATION_DESC 구조체가 포함된다.

세션에의 참가를 요구하려면 ,IDirectPlay8Peer::SetPeerInfo 를 호출해 플레이어명을 설정하고 나서, 선택된 호스트의 주소를 지정해 IDirectPlay8Peer::Connect 를 호출하는 것으로 세션에 접속한다.

플레이어가 세션에의 참가를 시도하면(자), 호스트에게 DPN_MSGID_INDICATE_CONNECT 메세지가 도착한다. 플레이어의 참가를 허가하는 경우는, S_OK 를 돌려준다. 요구를 거부하는 경우는, 그 이외의 값을 돌려준다. 어느 쪽의 경우도, 플레이어에게는 응답이 들어간 DPN_MSGID_CONNECT_COMPLETE 메세지가 도착한다. 호스트가 접속을 받아들였을 경우는, 관련하는 구조체의 hResultCode 멤버가 S_OK 로 설정된다. 거부했을 경우는,hResultCode 가 DPNERR_HOSTREJECTEDCONNECTION 로 설정된다.

DPN_MSGID_INDICATE_CONNECT 메세지가 도착하면(자), 호스트는 플레이어 문맥값을 정의할 수 있다. 다만, 플레이어 ID 는 아직 정의되지 않는다. 플레이어 문맥값은, 플레이어 ID 가 들어간 DPN_MSGID_CREATE_PLAYER 메세지를 수신하고 나서에서도 정의할 수 있다. 일반의 플레이어에게 DPN_MSGID_INDICATE_CONNECT 메세지가 도착할 것은 없다.

새로운 플레이어가 접속되면(자), 호스트를 포함한 세션 멤버 전원에게, 새로운 플레이어를 공표하는 DPN_MSGID_CREATE_PLAYER 메세지가 도착한다. 메세지에 관련지을 수 있었던 구조체에는, 플레이어에게로의 메세지 송신에 사용하는 플레이어 ID 가 저장 되고 있다. 호스트 이외의 피어에서는, 이 메세지를 처리할 경우에, 플레이어 문맥값을 정의할 필요가 있다. 피어 또는 호스트가 이 메세지의 처리로부터 복귀 하면, 그 플레이어 문맥값이 세션용으로 설정되어 변경할 수 없게 된다. 플레이어 문맥값의 상세한 것에 대하여는,「플레이어 문맥값의 사용법」을 참조할것.


피어 투 피어 세션의 관리

세션 호스트에서는, 이하와 같은 세션 관리를 실시하지 않으면 안 된다.

  • 세션 멤버와 그 네트워크 주소의 리스트를 관리한다.
  • 새로운 유저의 세션 참가를 허락할지 어떨지를 판단한다.
  • 새로운 유저가 세션에 참가하면(자), 멤버 전원에게 통지해, 새로운 유저의 주소를 건네준다.
  • 새로운 유저에게 현재의 게임 상태를 제공한다.
  • 유저가 세션을 빠지면(자), 유저 전원에게 통지한다.

플레이어가 세션에의 참가를 시도하면(자), 호스트에게 DPN_MSGID_INDICATE_CONNECT 메세지가 도착한다. 플레이어의 참가를 허가하는 경우는, S_OK 를 돌려준다. 요구를 거부하는 경우는, 그 이외의 값을 돌려준다. 어느 쪽의 경우도, 플레이어에게는 응답이 들어간 DPN_MSGID_CONNECT_COMPLETE 메세지가 도착한다.

호스트는 플레이어를 세션으로부터 삭제할 수 있다. 이것에는,IDirectPlay8Peer::DestroyPeer 를 호출한다. 호스트 이외의 멤버는, 이 메소드를 호출하면 실패한다. 플레이어가 다른 플레이어를 세션으로부터 삭제하려면 , Microsoft® DirectPlay® 의 보통의 메시징으로 요구를 호스트에게 송신해, 호스트측에서 처리시킬 필요가 있다.


호스트의 이행

호스트는, 세션의 초기 멤버가 아니면 안되지만, 세션의 종료전에 빠져도 괜찮다. 호스트가 세션을 빠지면(자), 이하의 어느 쪽인가의 결과가 된다.

  • 세션이 종료한다.
  • 호스트가 "이행" 해 다른 유저가 호스트가 된다.

호스트가 이행 가능한가 어떤가는 세션에 따라서 다르다. 호스트의 이행을 유효하게 하려면 , 게임의 셋업시에, 세션의 주최자가 DPN_APPLICATION_DESC 구조체의 dwFlags 멤버에 DPNSESSION_MIGRATE_HOST 플래그를 설정할 필요가 있다. 이 플래그가 설정되어 있지 않은 경우는, 호스트가 빠지면(자) 세션이 종료한다.

DPNSESSION_MIGRATE_HOST 플래그가 설정되어 있어도, 호스트는 IDirectPlay8Peer::TerminateSession 를 호출해 세션을 강제 종료할 수 있다.

DPNSESSION_MIGRATE_HOST 플래그가 설정되어 있는 경우에는, 호스트가 세션을 빠지면(자), Microsoft® DirectPlay® 가 새로운 세션 호스트를 선택한다. 나머지의 세션 멤버 전원에게, 새로운 호스트의 ID 가 포함되는 DPN_MSGID_HOST_MIGRATE 메세지가 도착한다.


피어 투 피어 게임의 보통의 플레이

Microsoft® DirectPlay® 의 메세지는, 기본적으로는, 세션내의 멤버에 송신되는 게임 관련의 데이터 블록이다. DirectPlay 는, 데이터 블록의 내용이나 형식을 한정하지 않고 , 유저 끼리가 데이터를 교환하기 위한 메카니즘만을 제공한다. 게임의 진행중에는, 보통, 각 세션 멤버로부터 나머지의 세션 멤버 전원에 대해서, 메세지가 간단 없게 송신된다. 이러한 메세지의 주된 목적은, 각 유저의 어플리케이션에 같은 UI 를 표시하기 위해서, 게임 상태의 동기를 잡는 것에 있다. 다만, 메세지는, 이것에 한정하지 않고 게임 고유의 다양한 목적으로 사용할 수 있다.

게임 (특히 변화의 빠른 게임)에서는, 메시징을 신중하게 관리해야 하는 경우가 많다. DirectPlay 는, 유출하는 메세지를, 타겟을 처리할 수 있는 레벨에 감속 (슬롯 링)한다. 중요한 메세지를 확실히 보내기 (위해)때문에, 메세지를 그다지 고속으로 송신하지 않게 주의하지 않으면 안 된다. DirectPlay 에서의 효율적인 메시징 처리에 대해서는,「네트워킹의 기본」을 참조할것.

다른 세션 멤버에 메세지를 송신하려면 ,IDirectPlay8Peer::SendTo 를 호출한다. 그 멤버에, 데이터가 붙은 DPN_MSGID_RECEIVE 메세지가 도착한다. 특정의 플레이어에게 메세지를 송신하려면 , 관련하는 DPN_MSGID_CREATE_PLAYER 메세지와 함께 받아들인 플레이어 ID 를,dpnid 파라미터로 설정한다. 또,dpnid 를 DPNID_ALL_PLAYERS_GROUP 로 설정하면, 세션내의 플레이어 전원에게 메세지를 송신할 수 있다. 플레이어의 그룹을 정의 하면,SendTo 를 1 회 호출하는 것만으로, 그룹의 멤버 전원에게 메세지를 송신할 수 있다.

주 다른 유저에게 정보를 송신하려면 ,IDirectPlay8Peer::SetPeerInfo 메소드를 사용해도 괜찮다. 그러한 유저에게, 그 정보가 붙은 DPN_MSGID_PEER_INFO 메세지가 도착한다. 다만, 이 송신 방법은 너무 효율적이 아니기 때문에, 보통의 메시징에서는 사용하지 않는 것.

그룹의 사용

많은 게임은, 플레이어를 그룹 나누고 할 수 있게 되어 있다. 예를 들어 전략형 게임에서는, 보통, 플레이어를 복수의 그룹으로 나누어 그룹 단위로 지시를 내릴 수가 있다. Microsoft® DirectPlay® 에서도, 플레이어의 그룹을 편성할 수 있다. DirectPlay 의 그룹은, 기본적으로는 메시징을 간략화하는 수단이다. 그룹을 정의 하면,IDirectPlay8Peer::SendTo 를 1 회 호출하는 것만으로, 그룹 멤버 전원에게 메세지를 송신할 수 있게 된다. DirectPlay 의 그룹은, 보통은 게임에서 정의되는 그룹에 대응하지만, 그룹 생성의 목적이 한정되고 있는 것은 아니다.

DirectPlay 의 그룹을 생성 하려면 ,IDirectPlay8Peer::CreateGroup 를 호출한다. 이 결과, 세션 멤버 전원에게, 상세가 붙은 DPN_MSGID_CREATE_GROUP 메세지가 도착한다. 이 메세지에는, 그룹에 메세지를 송신하기 위해서 사용하는 그룹 ID 가 포함된다.

그룹을 생성 하면(자), 다음에 IDirectPlay8Peer::AddPlayerToGroup 를 호출해 플레이어를 추가한다. 이 결과, 세션 멤버에, 새롭게 플레이어가 추가된 그룹의 ID 가 붙은 DPN_MSGID_ADD_PLAYER_TO_GROUP 메세지가 도착한다.

그룹을 확립 하면, 그 그룹에 데이터를 송신할 수 있게 된다. 이것에는,dpnid 파라미터에 그룹 ID 를 설정해 IDirectPlay8Peer::SendTo 를 호출한다. 이 결과, 그룹 멤버 전원에게, 데이터가 붙은 DPN_MSGID_RECEIVE 메세지가 도착한다.

그룹으로부터 플레이어를 삭제하려면 ,IDirectPlay8Peer::RemovePlayerFromGroup 를 호출한다. 세션 멤버에, 플레이어의 ID 가 붙은 DPN_MSGID_DESTROY_PLAYER 메세지가 도착한다.

마지막으로, 그룹을 다 사용했으면,IDirectPlay8Peer::DestroyGroup 를 호출하면 파기할 수 있다. 이 결과, 세션 멤버 전원에게, 그룹 ID 가 붙은DPN_MSGID_DESTROY_GROUP 메세지가 도착한다.


피어 투 피어 세션으로부터의 이탈

세션을 빠지려면 ,IDirectPlay8Peer::Close 를 호출해 접속을 종료한다. 세션 멤버에,DPN_MSGID_DESTROY_PLAYER 메세지가 통지된다.

세션 호스트 자신이 세션을 빠지면(자), 세션도 종료한다. 다만, 세션이 호스트의 이행을 허락하도록(듯이) 구성되어 있는 경우는 예외이다. 상세한 것에 대하여는,「호스트의 이행」을 참조할것.


피어 투 피어 세션의 종료

다 사용한 세션은, 호스트가 IDirectPlay8Peer::TerminateSession 를 호출해 종료해야 한다. 이 메소드는, 호스트의 이행이 유효하게 되어 있어도, 호스트 이행을 하지 않고 세션을 종료한다. 세션 멤버 전원에게,DPN_MSGID_TERMINATE_SESSION 메세지가 통지된다. 이 후, 필요한 클린 업이 있으면 실행한다. 다른 세션을 시작 하려면 ,IDirectPlay8Peer::Close 를 호출하고 나서 IDirectPlay8Peer::Initialize 를 호출할 필요가 있다.

IDirectPlay8LobbiedApplication::SetAppAvailable 의 호출에 의해, 어플리케이션이 접속 가능하다라고 등록되어 있는 경우에는, 로비 클라이언트는, 로비 대상 어플리케이션의 메세지 핸들러에 DPL_MSGID_CONNECT 메세지를 송신해, 실행중의 어플리케이션과 새로운 세션의 접속을 시도할 수가 있다. 이 경우는 우선,IDirectPlay8Peer::Close 를 호출하고 나서 IDirectPlay8Peer::Initialize 를 호출해 둘 필요가 있다.


클라이언트/서버 세션

클라이언트/서버 세션은, 중심이 되는 서버와 거기에 접속된 플레이어 (즉 클라이언트)의 집합으로부터 구성된다. Microsoft® DirectPlay® 에 관한한, 클라이언트의 정보는 서버만이 파악해, 클라이언트가 다른 클라이언트에 대해 알 것은 없다. 게임의 실행에 필요한 메세지는, 각 클라이언트와 서버의 사이에 교환된다. 피어 투 피어 세션의 경우와 달리, 클라이언트간에 직접 메시징을 실시할 수 없다.

클라이언트/서버 세션에서는, 이하의 2 개의 완전히 이질의 어플리케이션이 필요하게 된다.

  • 리모트 서버-로 동작하는 서버 어플리케이션. 최저한에서도, 중심이 되는 메시징 허브 및 게임 호스트로서의 기능을 가진다. 서버는, 클라이언트로부터 유입하는 모든 메세지를 수신해 처리해, 적절한 메세지를 답장할 필요가 있다. 클라이언트로부터 다른 클라이언트에의 데이터 전송은, 모두 서버 어플리케이션측에서 처리할 필요가 있다.
  • 각 플레이어의 컴퓨터로 동작하는 클라이언트 어플리케이션. 이 어플리케이션의 주된 기능은, UI 를 처리해, 서버와의 사이에 플레이어의 게임 상태의 동기를 잡는 것이다.

세션의 일부의 요소는, 이러한 어플리케이션의 한편으로 밖에 처리할 수 없다. 예를 들어, 플레이어의 비디오 표시의 갱신은, 클라이언트 어플리케이션이 아니면 실행할 수 없다. 그러나, 게임 전체를 유지하기 위해서 필요한 처리가 많은 요소는, 적어도 원칙적으로는, 어느 쪽의 어플리케이션에서도 실행할 수 있다. 효율적인 클라이언트/서버 게임을 생성 하려면 , 개개의 처리를 2 개의 어플리케이션에 어떻게 배분할까를, 신중하게 판단할 필요가 있다.

이 문서에서는, 클라이언트/서버 게임의 기본적인 원리와 클라이언트/서버 어플리케이션의 이행 방법의 개요를 설명한다.

  • 클라이언트/서버 세션의 시작
  • 클라이언트용 서비스 프로바이더의 선택
  • 클라이언트/서버 호스트의 선택
  • 클라이언트/서버 세션에의 접속
  • 클라이언트/서버 세션의 관리
  • 클라이언트/서버 게임의 보통의 플레이
  • 클라이언트/서버 세션으로부터의 이탈
  • 클라이언트/서버 세션의 종료


클라이언트/서버 세션의 시작

클라이언트/서버 게임은, 로비를 통해서 기동하는 일도, 서버 어플리케이션으로부터 직접 기동할 수도 있다.

서버 어플리케이션

클라이언트/서버 게임은, 로비를 통해서 준비되는 것이 많다. 서버를 기동하는 가장 직접적인 방법은, 서버를 "로비 가능" 어플리케이션으로서 이행 하는 것이다. 이 어프로치에서는, 서버를 기동하는 수단이 제공되어 세션 진행중에 서버와 로비가 통신을 실시할 수가 있다. 상세한 것에 대하여는,「DirectPlay 의 로비」를 참조할것.

서버를 직접 기동하고 나서, 그 서버가 이용 가능한 것을 공표해, 클라이언트로부터의 접속을 기다릴 수도 있다. 상세한 것에 대하여는,「클라이언트/서버 호스트의 선택」을 참조할것.

서버 어플리케이션은, 기동되면(자),IDirectPlay8Server::Initialize 를 호출해 어플리케이션 자체를 초기화해야 한다. 유사하는 Microsoft® DirectPlay® 외의 메소드와 같이, 초기화의 주된 목적은, DirectPlay 에 콜백 메세지 핸들러에의 포인터를 제공하는 것에 있다. 또,IDirectPlay8Server::SetServerInfo 를 호출해 현재의 게임의 기술도 실시하지 않으면 안 된다. 이 메소드가 불려 가지 않으면 클라이언트가 서버에 접속할 수 없다.

클라이언트 어플리케이션

실행해야 할 최초의 스텝의 1 개는, 게임이 로비 기동으로 기동되고 있는지 어떤지를 판단하는 것이다. 이것에는, 로비 대상 어플리케이션 오브젝트 (CLSID_DirectPlay8LobbiedApplication)를 생성 해, 초기화한다. 이 때, 로비 대상 어플리케이션의 콜백 메세지 핸들러에의 포인터를, 오브젝트에 건네준다. 이 메세지 핸들러는, 로비 대상 오브젝트로부터는 직접, 로비 클라이언트 및 로비로부터는 간접적으로, 메세지를 수신한다.

  • 어플리케이션이 로비 기동으로 기동되고 있으면,IDirectPlay8LobbiedApplication::Initialize 메소드가 로비 클라이언트에의 접속 핸들을 돌려주어, 로비 대상 어플리케이션의 메세지 핸들러에 DPL_MSGID_CONNECT 메세지가 송신된다. 관련하는 구조체의 pdplConnectionSettings 멤버는, 서버의 주소 오브젝트등의 접속 정보가 들어간 DPL_CONNECTION_SETTINGS 구조체를 가리킨다.
  • 어플리케이션이 로비 기동으로 기동되어 있지 않으면, 접속 핸들도 메세지도 도착하지 않는다. 다만,IDirectPlay8LobbiedApplication::SetAppAvailable 를 호출하면, 로비 클라이언트가, 로비 대상 어플리케이션의 메세지 핸들러에 DPL_MSGID_CONNECT 메세지를 송신하는 것으로써, 실행중의 어플리케이션을 세션에 나중에 접속할 수가 있다.

또, 클라이언트 오브젝트 (CLSID_DirectPlay8Client)를 생성 해, 초기화할 필요도 있다. 이 오브젝트가, Microsoft® DirectPlay® 및 서버와의 주된 통신 수단이 된다. 세션에 복수의 플레이어를 참가시키기 위해서(때문에)는, 플레이어 마다 이 오브젝트의 인스턴스를 생성 할 필요가 있다.


클라이언트용 서비스 프로바이더의 선택

이 경우, 사용중의 네트워크 접속이 서비스 프로바이더가 된다. TCP/IP 또는 모뎀의 서비스 프로바이더를 사용하는 게임이 많지만, Microsoft® DirectPlay® 는 시리얼 접속과 IPX 접속에도 대응하고 있다.

유저가 로비 클라이언트로 세션에 접속되고 있는 경우에는,DPL_MSGID_CONNECT 메세지에 부속되는 DPL_CONNECTION_SETTINGS 구조체를 조사하면, 적절한 서비스 프로바이더를 판단할 수 있다. 그 이외의 경우, 사용하는 서비스 프로바이더를 판단하려면 , 유저에게 조회하는 등 방법을 취할 필요가 있다. 클라이언트 오브젝트의 IDirectPlay8Client::EnumServiceProviders 메소드를 사용 하면, 이용 가능한 서비스 프로바이더를 열거할 수 있다. 상세한 것에 대하여는,「DirectPlay 열거의 사용법」을 참조할것.

서비스 프로바이더를 선택 하면, 유저의 DirectPlay 주소 오브젝트 (디바이스 주소)를 생성 할 수 있게 된다. DirectPlay 가 많은 메소드에서는, 이 주소를 사용해 디바이스를 식별한다. DirectPlay 주소와 주소 오브젝트의 상세한 것에 대하여는,「DirectPlay 아드레싱」을 참조할것.


클라이언트/서버 호스트의 선택

세션의 호스트는, 당연, 서버 어플리케이션이 담당한다. 세션에 참가하려면 , 클라이언트 어플리케이션으로 호스트 서버의 주소를 판단할 필요가 있다. 보통, 호스트의 선택은 로비 서버를 통해서 실시한다. 이 경우, 유저의 어플리케이션이 세션에 접속되면(자),DPL_MSGID_CONNECT 메세지와 함께 접속 설정이 닿아, 그 접속 설정에 호스트의 주소 오브젝트가 포함되어 있다. 관련하는 구조체의 pdp8HostAddress 멤버는, 호스트의 주소가 들어간 주소 오브젝트를 가리킨다.

또, IP 또는 IPX 서비스 프로바이더를 사용하고 있는 서버에서는, 그 서버가 세션 호스트인 것을 공표해, (예를 들어 LAN 서브 넷상에서) "어느 요소를 전요소에 카피하는 세션" 을 생성 할 수도 있다. 어느 요소를 전요소에 카피하는 세션을 생성 하려면 ,IDirectPlay8Server::SetServerInfo 를 호출해 서버 정보를 설정한다. 다음에 IDirectPlay8Server::Host 를 호출해, 세션 자체가 세션 호스트인 것을 공표한다. 게임의 구성은,IDirectPlay8Server::Host 의 pdnAppDesc 의 파라미터로 건네주는 DPN_APPLICATION_DESC 구조체에 값을 할당해 지정한다.

이용 가능한 세션과 호스트를 유저에게 알리려면 , 클라이언트 어플리케이션으로 IDirectPlay8Client::EnumHosts 를 호출하면, 이용 가능한 호스트를 조회할 수 있다. 유저가 호스트를 선택 하면, 접속을 요구할 수 있게 된다.


클라이언트/서버 세션에의 접속

모든 클라이언트는, 호스트에게 접속해 명시적으로 세션에 참가할 필요가 있다. 이것은, 로비를 통해서 준비된 세션에서도 같다. 접속에 의해, 클라이언트가 세션의 멤버가 되어, 클라이언트와의 통신에 필요한 정보가 호스트에게 제공된다. 호스트에서는, 접속 요구를 받아들이는 일도 거부할 수도 있다.

서버 어플리케이션

클라이언트가 세션에의 참가를 시도하면(자), 호스트에게 DPN_MSGID_INDICATE_CONNECT 메세지가 도착한다. 플레이어의 참가를 허가하는 경우는, S_OK 를 돌려준다. 요구를 거부하는 경우는, 그 이외의 값을 돌려준다. 어느 쪽의 경우도, 클라이언트에는 응답이 들어간 DPN_MSGID_CONNECT_COMPLETE 메세지가 도착한다. 여기서 플레이어 문맥값을 정의해도 괜찮고,DPN_MSGID_CREATE_PLAYER 메세지가 도착할 때까지 기다려도 괜찮다. 플레이어 문맥값의 상세한 것에 대하여는,「플레이어 문맥값의 사용법」을 참조할것.

플레이어가 세션에의 접속에 성공하면(자), 전클라이언트와 서버에, 새로운 플레이어의 ID (DPNID)가 붙은 DPN_MSGID_CREATE_PLAYER 메세지가 도착한다. 플레이어 문맥값을 정의할 필요가 있어, 그것이 아직 끝나지 않은 경우에는, 메세지 핸들러가 이 메세지의 처리로부터 복귀하기까지, 정의해야 한다. 복귀 하면, 플레이어 문맥값을 변경할 수 없게 된다.

클라이언트 어플리케이션

세션에 접속하려면 , 세션 호스트의 주소가 필요하게 된다. 어플리케이션이 로비 클라이언트로부터 접속되고 있는 경우는,IDirectPlay8LobbiedApplication::GetConnectionSettings 를 호출하면, 호스트의 주소를 취득할 수 있다.

세션 호스트의 주소를 모르는 경우, IP 또는 IPX 서비스 프로바이더를 사용하고 있다면,IDirectPlay8Client::EnumHosts 를 호출해 이용 가능한 호스트를 열거하면, 어느 요소를 전요소에 카피하는 세션을 조사할 수가 있다. 호스트의 주소는, 이용 가능한 호스트를 열거해 취득할 수도 있다. 열거로부터 돌려주어지는 정보에는, 각 호스트의 주소, 호스트와의 통신에 사용하는 디바이스, 및 관련지을 수 있었던 세션을 기술하는 DPN_APPLICATION_DESC 구조체가 포함된다.

세션에의 참가를 요구하려면 ,IDirectPlay8Client::SetClientInfo 를 호출해 플레이어명을 설정하고 나서, 선택된 호스트의 주소를 지정해 IDirectPlay8Client::Connect 를 호출하는 것으로 세션에 접속한다.

메세지 핸들러에, 호스트의 응답이 붙은 DPN_MSGID_CONNECT_COMPLETE 메세지가 도착한다. 호스트가 접속을 받아들였을 경우는, 관련하는 구조체의 hResultCode 멤버가 S_OK 로 설정된다. 거부했을 경우는,hResultCode 가 DPNERR_HOSTREJECTEDCONNECTION 로 설정된다.


클라이언트/서버 세션의 관리

호스트로서 서버에는 세션의 진행을 관리할 의무가 있다. 자세한 것은 어플리케이션의 설계에 따라서 다르지만, 세션 호스트가 적어도 이하의 작업을 실시하지 않으면 안 되는 것은 공통이다.

  • 세션 멤버와 그 네트워크 주소의 리스트를 관리한다. 이 작업의 일부는 Microsoft® DirectPlay® 로 행해지지만, 서버 어플리케이션으로 관리해야 하는 플레이어 데이터는, 보통, DirectPlay 로부터 제공되는 데이터 만이 아니다.
  • 새로운 유저의 세션 참가를 허락할지 어떨지를 판단한다.
  • 새로운 유저에게 현재의 게임 상태를 제공한다.

플레이어가 세션에의 참가를 시도하면(자), 호스트에게 DPN_MSGID_INDICATE_CONNECT 메세지가 도착한다. 플레이어의 참가를 허가하는 경우는, S_OK 를 돌려준다. 접속 요구를 거부하는 경우는, 그 이외의 값을 돌려준다. 어느 쪽의 경우도, 플레이어에게는 응답이 들어간 DPN_MSGID_CONNECT_COMPLETE 메세지가 도착한다.

호스트는 플레이어를 세션으로부터 삭제할 수 있다. 이것에는,IDirectPlay8Server::DestroyClient 를 호출한다.


클라이언트/서버 게임의 보통의 플레이

Microsoft® DirectPlay® 의 메세지는, 기본적으로는, 클라이언트와 서버의 사이에 교환되는 게임 관련의 데이터 블록이다. DirectPlay 는, 데이터 블록의 내용이나 형식을 한정하지 않고 , 데이터를 교환하기 위한 메카니즘만을 제공한다. 게임의 진행중에는, 보통, 각 클라이언트와 서버의 사이로, 메세지가 간단 없게 교환된다. 이러한 메세지의 주된 목적은, 각 유저의 어플리케이션에 같은 UI 를 표시하기 위해서, 게임 상태의 동기를 잡는 것에 있다. 다만, 메세지는, 이것에 한정하지 않고 게임 고유의 다양한 목적으로 사용할 수 있다.

게임 (특히 변화의 빠른 게임)에서는, 메시징을 신중하게 관리해야 하는 경우가 많다. DirectPlay 는, 유출하는 메세지를, 타겟을 처리할 수 있는 레벨에 감속 (슬롯 링)한다. 중요한 메세지를 확실히 보내기 (위해)때문에, 메세지를 그다지 고속으로 송신하지 않게 주의하지 않으면 안 된다. DirectPlay 에서의 효율적인 메시징 처리에 대해서는,「네트워킹의 기본」을 참조할것.

서버 어플리케이션

클라이언트에 메세지를 송신하려면 ,IDirectPlay8Server::SendTo 를 호출한다. 클라이언트에, 데이터가 붙은 DPN_MSGID_RECEIVE 메세지가 도착한다.

클라이언트 어플리케이션

서버에 메세지를 송신하려면 ,IDirectPlay8Client::Send 를 호출한다. 서버에, 데이터가 붙은 DPN_MSGID_RECEIVE 메세지가 도착한다.

주 DirectPlay 에는 클라이언트간의 통신 메카니즘은 없고, 클라이언트와 서버의 사이의 통신 메카니즘만이 준비되어 있다. 클라이언트간의 통신은, 모두 서버 어플리케이션으로 이행 할 필요가 있다.

그룹의 사용

많은 게임은, 플레이어를 그룹 나누고 할 수 있게 되어 있다. 예를 들어, 팀 대전형 게임에서는, 팀의 플레이어 전원을 1 개의 그룹의 멤버로 해도 괜찮다. DirectPlay 에서는, 클라이언트/서버 게임의 서버가, 플레이어의 그룹을 생성 할 수 있다. DirectPlay 의 그룹은, 보통은 게임에서 정의되는 그룹에 대응하지만, 그룹 생성의 목적이 한정되고 있는 것은 아니다. DirectPlay 의 그룹은, 기본적으로는 메시징을 간략화하는 수단이다. 그룹을 정의 하면,IDirectPlay8Server::SendTo 를 1 회 호출하는 것만으로, 그룹 멤버 전원에게 메세지를 송신할 수 있게 된다.

DirectPlay 의 그룹을 생성 하려면 ,IDirectPlay8Server::CreateGroup 를 호출한다. 이 결과, 메세지 핸들러에, 상세가 붙은 DPN_MSGID_CREATE_GROUP 메세지가 도착한다. 이 메세지에는, 그룹에 메세지를 송신하기 위해서 사용하는 그룹 ID 가 포함된다. 그룹을 생성 하면(자), 다음에 IDirectPlay8Server::AddPlayerToGroup 를 호출해 플레이어를 추가한다.

그룹을 확립 하면, 그 그룹에 데이터를 송신할 수 있게 된다. 이것에는,dpnid 파라미터에 그룹 ID 를 설정해 IDirectPlay8Server::SendTo 를 호출한다. 이 결과, 그룹 멤버 전원에게, 데이터가 붙은 DPN_MSGID_RECEIVE 메세지가 도착한다.

그룹으로부터 플레이어를 삭제하려면 ,IDirectPlay8Server::RemovePlayerFromGroup 를 호출한다. 마지막으로, 그룹을 다 사용했으면,IDirectPlay8Server::DestroyGroup 를 호출하면 파기할 수 있다.


클라이언트/서버 세션으로부터의 이탈

클라이언트가 세션을 빠지려면 ,IDirectPlay8Client::Close 를 호출한다. 이 결과, 서버에 DPN_MSGID_DESTROY_PLAYER 메세지가 통지된다.


클라이언트/서버 세션의 종료

클라이언트/서버 세션을 종료하려면 , 서버가 IDirectPlay8Server::Close 를 호출한다. 클라이언트/서버 세션의 경우, 호스트는 이행 하지 않기 때문에, 이 메소드에 의해 모든 접속이 종료해, 세션 자체가 종료한다. DPN_MSGID_TERMINATE_SESSION 메세지에 의해, 클라이언트에 세션 종료가 통지된다.

다음에, 서버 자체를 포함한 각 플레이어에게로의 DPN_MSGID_DESTROY_PLAYER 메세지가 서버에 도착한다. IDirectPlay8Server::Close 는, 동기 메소드이며,DPN_MSGID_DESTROY_PLAYER 메세지가 모두 처리될 때까지 복귀하지 않는다. IDirectPlay8Server::Close 로부터 복귀 하면, 서버 어플리케이션을 안전하게 슛다운 할 수 있게 된다.

서버가 세션을 닫을 때, 모든 접속되고 있는 player로부터 DPN_MSGID_DESTROY_PLAYER 를 받는다. 서버는 접속을 해제하고 있는 것을 알고 있으므로, 이것은 보통의 행동이며, 구성된 구조체의 dwReason 멤버에는 DPNDESTROYPLAYERREASON_NORMAL 가 설정된다. DPNDESTROYPLAYERREASON_SESSIONTERMINATED 값은 예기치 못한 접속 해제의 경우에게만 설정된다.


DirectPlay 의 로비

로비와는, 유저가 멀티 플레이어 게임을 준비할 수 있도록(듯이) 하는 것을 주된 목적으로 하는 어플리케이션이다. 로비는, 보통, 리모트 서버-위에서 동작하는 어플리케이션이다. 유저는, (주로 인터넷 경유로) 로비에 액세스 해, 게임 세션을 설정하는지, 또는 누군가가 시작 한 세션에 참가한다. 이 결과, 로비 어플리케이션이 그룹의 각 게임 어플리케이션을 기동해, 게임이 시작된다.

멀티 플레이어 게임의 상당수는 로비를 통해서 준비되므로, Microsoft® DirectPlay® 베이스의 게임의 상당수는, 로비 어플리케이션과 대화할 수 없으면 안 된다. 반대로, 많은 로비는 DirectPlay 베이스의 게임을 지원 할 필요가 있으므로, 로비 어플리케이션은 게임 어플리케이션과 대화할 수 없으면 안 된다. 이 문서에서는, Microsoft DirectX® 의 게임이 로비라고 대화할 수 있도록(듯이) 하는 방법 ( 및 로비가 Microsoft DirectX® 의 게임이라고 대화할 수 있도록(듯이) 하는 방법)을 설명한다.

  • DirectPlay 의 로비 아키텍쳐
  • 로비 서버
  • 로비 클라이언트
  • 로비 가능 어플리케이션


DirectPlay 의 로비 아키텍쳐

Microsoft® DirectPlay® 에 근거하는 멀티 플레이어 게임의 세션을 준비해, 관리하는 프로세스에는, 독립한 5 개의 원가요소가 관계하고 있다. 로비 서버 어플리케이션은, 보통, 리모트 서버-에 상주해, 인터넷을 통해서 액세스 되는 써드파티 어플리케이션이다. 나머지의 4 개의 원가요소는, 각 플레이어의 컴퓨터에 인스톨 된다.

  • 로비 클라이언트. 로비 클라이언트는, 로비 서버와 통신하는 써드파티 어플리케이션이다. 로비 클라이언트는, DirectPlay 로비 클라이언트 오브젝트를 통해서, 유저의 게임 어플리케이션과도 통신한다.
  • 로비 가능 게임 어플리케이션. 로비 가능 게임 어플리케이션은, DirectPlay 로비 대상 어플리케이션 오브젝트를 사용해 로비 클라이언트와 통신해, 로비 클라이언트를 통해서 로비 서버와 통신하는, 써드파티 어플리케이션이다.
  • DirectPlay 로비 클라이언트 오브젝트.
  • DirectPlay 로비 대상 어플리케이션 오브젝트.

이러한 2 개의 DirectPlay 오브젝트는, 게임 어플리케이션과 로비 클라이언트의 사이의 링크로서 기능한다. 이러한 오브젝트는, 사적인 인터페이스를 통해서 교환한다. 다음의 그래픽은, 이러한 원가요소가 링크되어 데이터를 교환하는 모습을 나타내고 있다.


로비 서버

로비 서버는, 플레이어가 모여 게임을 준비할 수 있도록(듯이) 하는 것을 주된 목적으로 하는 어플리케이션이다. 보통은 리모트 컴퓨터에 있어, 인터넷을 통해서 액세스 한다. 로비 서버는, 대화방의 호스트, 뉴스나 정보의 투고, 상품의 판매등이라고 하는 그 외의 다양한 기능을 실행하는 것이 많다.

멀티 플레이어 게임을 관리하기 위해(때문에), 보통, 로비 서버는 이하를 포함한 다양한 작업을 실시한다.

  • 각종의 게임 세션 및 플레이어의 네트워크 주소를 관리한다.
  • 플레이어의 컴퓨터에 있는 관련하는 게임 어플리케이션을 기동해, 세션을 시작 한다.
  • 진행중의 세션에 플레이어를 추가한다.
  • 세션내의 각종 컴퓨터를, 올바른 네트워크 주소에 접속한다.
  • 플레이어가 게임을 빠지는, 게임 호스트가 이행 한다, 라고 하는 세션의 변화를 파악한다.

로비 서버 어플리케이션의 자세한 것은, 벤더가 제공하려고 하고 있는 서비스의 종류에 따라서 다르다. Microsoft® DirectPlay® 에서는, 로비 서버의 이행 방법도, 로비 서버와 유저 컴퓨터의 통신 방법도, 지정되어 있지 않다. 다만, 로비 벤더는, DirectPlay 호환의 로비 클라이언트를 이행 해, 유저에게 배포해야 한다.


로비 클라이언트

로비 클라이언트와는, 로비 서버의 벤더가 이행 해, 각 플레이어의 컴퓨터에 인스톨 되는 어플리케이션이다. 로비 클라이언트는, 플레이어 및 게임 어플리케이션과 로비 서버의 사이의 통신을 처리한다. 로비 클라이언트를 인스톨 하려면 , 보통, 싸인 업 순서의 일부로, 유저에게 로비 서버의 Web 사이트에서 로비 클라이언트를 다운로드시킨다.

일반적인 시나리오는 다음과 같이 된다.

  1. 새로운 플레이어가 Web 사이트에 액세스 해, 싸인 올라간다.
  2. 싸인 업 순서의 일부로, 로비 클라이언트가 클라이언트의 컴퓨터에 다운로드된다.
  3. 플레이어가, 플레이하는 게임을 선택해, 세션에의 참가를 요구한다.
  4. Web 사이트가, 플레이어의 컴퓨터에 있는 로비 클라이언트를 기동한다. 보통의 기동 메카니즘은, 로비 클라이언트의 실행 파일을 가리키는 URL 이다.
  5. 로비 클라이언트가, 순서를 밟아 세션을 준비하고 나서, 유저의 게임 어플리케이션을 기동한다.
  6. 그 게임이 로비 가능 어플리케이션이라면, 로비 클라이언트는, 게임 어플리케이션이 로비 서버와 통신할 수 있도록(듯이) 한다. 이 접속에 의해, 로비 서버는, 플레이어가 게임에 참가하거나 게임으로부터 빠지거나 하는, 호스트가 이행 한다, 라고 하는 이벤트를 파악할 수 있다.

로비 클라이언트는, 리모트 서버-에 링크되어 있지 않아도 좋다. 유저가 로비 클라이언트를 직접 기동한다, 라고 하는 다른 시나리오도 있다. 이 경우, 로비 클라이언트가, (예를 들어 유저의 LAN 서브 넷에 접속되고 있다) 이용 가능한 게임과 세션을 표시한다. 유저가 게임과 세션을 선택하면(자), 로비 클라이언트가 게임을 기동한다.

여기에서는, 로비 클라이언트가 가지는 몇개의 일반적인 기능에 대해 설명한다. 로비 클라이언트와 거기에 관련하는 로비 서버와의 통신의 상세한 것에 대하여는,「로비 가능 게임과의 통신」을 참조할것.

이행의 상세한 것에 대하여는,「로비 클라이언트의 이행」또는 SDK 부속의 샘플 어플리케이션 LobbyClient 를 참조할것.


로비 가능 게임과의 통신

로비 클라이언트와 거기에 관련하는 로비 서버와의 통신은, 적당한 방법으로 자유롭게 처리할 수 있다. Microsoft® DirectPlay® 에서는, 로비 클라이언트가 로비 가능 게임 어플리케이션과 통신하는 방법만이 지정되고 있다.

로비 클라이언트는, 게임 어플리케이션과 직접 통신하지 않는다. 대신에, DirectPlay 로비 클라이언트 오브젝트 (CLSID_DirectPlay8LobbyClient)와 그 IDirectPlay8LobbyClient 인터페이스를 통해서 통신한다. 게임 어플리케이션이 로비 가능하면, 이 결과, 로비 대상 어플리케이션 오브젝트가 게임에 메세지를 건네준다. 로비 클라이언트는,IDirectPlay8LobbyClient 인터페이스를 사용해 이하를 실행할 수 있다.

  • 유저의 시스템에 있는 로비 가능 어플리케이션을 열거한다.
  • 이미 실행중이 아니면 어플리케이션을 기동해, 세션에 접속한다.
  • 어플리케이션을 세션으로부터 해방해, 로비 클라이언트와의 링크를 닫는다.
  • 로비 클라이언트로부터 기동 또는 접속된 로비 대상 어플리케이션에, 메세지를 송신한다.

주 DirectPlay 로비 클라이언트는, 로비 가능한가 어떤가에 관계없이, 모든 어플리케이션을 기동할 수 있다. 다만, 게임의 진행중에 DirectPlay 를 사용해 로비 클라이언트에 응답할 수 있는 것은, 로비 가능 어플리케이션 뿐이다.

로비 클라이언트 오브젝트는, 로비 클라이언트가 이행 한 콜백 함수를 통해서, 로비 클라이언트와 통신한다. 로비 클라이언트 오브젝트에는, 초기화시에 함수 포인터가 건네받는다. 로비 클라이언트 오브젝트는, 이 콜백 함수를 사용해, 이하와 같은 정보를 로비 클라이언트에 송신할 수 있다.

  • 접속 정보.
  • 접속 상태.
  • 세션 상태 (접속, 절단, 호스트의 이행 등).
  • 어플리케이션으로부터 로비 클라이언트에의 메세지.

어플리케이션의 기동

어플리케이션에는, 기동시에 게임 고유의 데이터 블록을 건네줄 수가 있다. 로비 클라이언트로부터 로비 가능 어플리케이션이 기동되면(자), 어플리케이션은 로비 대상 어플리케이션 오브젝트를 생성 해, 초기화한다. 정보는, 이 초기화 메소드를 통해서 게임에게 건네진다.

로비 대상 어플리케이션 오브젝트가 초기화되면(자), 유저가 접속된 것을 나타내는 메세지가 로비 클라이언트에 닿는다. 이 메세지가 가지는 주된 목적의 1 개는, 어플리케이션이 로비 가능한 것을 로비 클라이언트에 알리는 것이다. 기동 후에 있는 정도의 시간이 경과해도, 로비 클라이언트에 접속 메세지가 도착하지 않는 경우에는, 게임이 로비 가능하지 않기 때문에, 이 접속을 포기할 수가 있다.

어플리케이션의 기동 후

로비 가능 게임이 시작되면(자), 로비 클라이언트는 비교적 한가해 진다. 유저의 메세지의 상당수는, 게임 위상기하학에 응해, 다른 플레이어에게 직접 송신되는지, 또는 게임 서버에 송신된다. 다만, 절단이나 호스트의 이행이라고 하는 이벤트가 발생 하면, DirectPlay 로부터 로비 클라이언트에 메세지가 송신된다. 이러한 메세지에 의해, 로비 클라이언트가 로비 서버에 상태 변화를 건네주는 것이 가능하게 된다. 예를 들어, 호스트가 이행 했을 경우, 로비 서버는 UI 에 새로운 호스트를 반영할 수 있다.

어플리케이션은, 로비 클라이언트에 메세지를 건네줄 수도 있다. 이 메세지에는 사실상 모든 데이터를 저장 할 수 있다. 또, 용도에도 제한은 없다. 로비 클라이언트는, 보통, 그 데이터를 로비 서버에 건네주어 처리를 맡긴다. 예를 들어, 게임의 종료시에, 로비 서버의 하이 스코아 일람을 갱신하기 위해(때문에), 어플리케이션으로부터 로비 서버에 메세지를 송신해도 괜찮다.


로비 가능 어플리케이션

로비 가능 어플리케이션은, Microsoft® DirectPlay® 베이스의 로비 클라이언트와 연동하게 되어 있다. 로비 클라이언트는 DirectPlay 를 사용해 임의의 어플리케이션을 기동할 수 있지만, 로비 가능 어플리케이션에는 많은 이점이 있다.

  • 게임 상태가 변화 하면, 로비 클라이언트에 대해서 최신 상태가 자동적으로 보내진다.
  • 로비 클라이언트는, 표준 API 를 사용해 어플리케이션과 통신할 수 있다.
  • 어플리케이션은, 표준 API 를 사용해 로비 클라이언트와 통신할 수 있다.

요컨데, DirectPlay 를 사용하면, 게임 고유 또는 로비 클라이언트 고유의 통신 코드는 거의 필요없다. 특정의 게임이나 로비 클라이언트를 위한 수정을 거의 (또는 완전히) 실시하지 않고 , 무엇이라도 표준 API 를 사용할 수 있다.

여기에서는, 로비 가능 어플리케이션이 가지는 몇개의 일반적인 기능에 대해 설명한다. 상세한 것에 대하여는,「로비 가능 어플리케이션의 기동」을 참조할것.

이행의 상세한 것에 대하여는,「로비 가능 어플리케이션의 이행」또는 SDK 의 샘플 (SimplePeer, StagedPeer 등)을 참조할것.


로비 가능 어플리케이션의 기동

기동된 후에 로비 가능 어플리케이션이 실행해야 할 작업의 1 개는, 로비 대상 어플리케이션 오브젝트를 생성 하는 것이다. 이 오브젝트의 가장 중요한 기능은, 어플리케이션이 로비 기동으로 기동되고 있는지 어떤지를 판단하는 것에 있다. 또, 로비 대상 어플리케이션은, 로비 클라이언트로부터 메세지를 수신하기 위해서, 메세지 핸들러 콜백 함수를 이행 할 필요도 있다. 기본적인 순서는 이하대로이다.

  • 로비 대상 어플리케이션 오브젝트를 생성 한다.
  • 오브젝트를 초기화한다.
  • 초기화 메소드로부터 유효한 접속 핸들이 돌려주어지는 경우, 어플리케이션은 로비 기동으로 기동되고 있다.
  • 초기화 메소드로부터 돌려주어진 유저 문맥값을 조사한다. 이 값에는, 로비 클라이언트로부터의 게임 고유의 정보가 들어가 있는 일이 있다.
  • 로비 대상 어플리케이션의 메세지 핸들러를 통해서 수신한 접속 메세지를 조사한다. 이 메세지에는, 로비 클라이언트에 메세지를 송신할 경우에 사용하는 ID 를 포함한, 각종의 정보가 부속되어 있다.

어플리케이션의 로비 기동으로 기동이 성공하면(자), 호스트의 이행등의 이벤트가 발생했을 때에, Microsoft® DirectPlay® 가 로비 클라이언트에 대해서 최신 상태를 자동적으로 송신할 수 있게 된다. 상태의 자동 갱신을 유효하게 하려면 ,IDirectPlay8Peer,IDirectPlay8Client, 또는 IDirectPlay8Server 인터페이스의 RegisterLobby 메소드를 호출한다. 또, 로비 대상 어플리케이션의 인터페이스를 사용해, 로비 클라이언트에 메세지를 송신할 수도 있다.

메세지 핸들러 함수에는, 초기화 메소드로부터 복귀하기 전에, 로비 클라이언트로부터의 메세지가 도착하는 일이 있으므로, 주의가 필요하다. 접속 메세지에 가세해, 로비 클라이언트가 접속의 설정을 변경했는지, 또는 접속을 절단 했을 때에도, 이 콜백 함수에 메세지가 도착한다. 또, 게임 고유의 정보가 들어간 메세지를, 로비 클라이언트로부터 메세지 핸들러에 직접 송신할 수도 있다.

주 메세지의 발신기지는 단독 thread라고는 할 수 없다. 메시징을 적절히 처리하기 위해(때문에), 로비 대상 어플리케이션의 콜백 함수는, 재입 가능하지 않으면 안 된다.


네트워킹의 기본

여기에서는, Microsoft® DirectPlay® 어플리케이션을 생성 하기 위해서 이해해야 하는 네트워킹 기술에 대해, 기본적인 사항을 몇개인가 설명한다. 네트워킹 기술의 일반적인 설명에 대해서는, 이 분야에 관한 표준적인 문헌 (Andrew Tannenbaum 저의 「Computer Networks」등)을 참조할것. 디폴트의 DirectPlay8 TCP/IP 다이얼로그를 오버라이드(override) 하려고 하는 어플리케이션 개발자는, 접속이나 열거에 사용하는 포토를 유저에게 오버라이드(override) 시키는 솔루션을 반드시 이행 해야 한다. 1 개(살)의 가능한 솔루션은 디폴트의 DIrectPlay8 TCP/IP 다이얼로그가 이행 하고 있도록(듯이) (즉 "host.domain.com:8090" 와 같이), 유저에게 구두점으로 호스트명에 포토를 추가시키는 방법이다. 이제(벌써) 1 개(살)의 가능한 솔루션은 유저가 포토를 입력할 수 있는 다른 UI 필드를 추가하는 것이다.

  • DirectPlay 서비스 프로바이더
  • DirectPlay 아드레싱
  • DirectPlay 프로토콜
  • 네트워크 사용량의 최적화
  • 어플리케이션에 있어서의 DirectX 프로토콜의 사용법


DirectPlay 서비스 프로바이더

Microsoft® DirectPlay® 는, 어플리케이션에 가상의 네트워크 접속을 제공한다. 이 가상 네트워크 접속을 사용 하면, 관계하는 네트워크의 종류에 관계없이 공통의 방법으로, 다른 컴퓨터와 통신할 수가 있다. 이 레벨의 추상화를 실현하기 (위해)때문에, 네트워크 접속은 서비스 프로바이더를 통해서 행해진다. 서비스 프로바이더를 선택 하면, 어플리케이션이, DirectPlay 의 적절한 메소드를 사용해, 세션내외의 컴퓨터와 통신하게 된다. 선택한 네트워크 하드웨어를 이라고 있는 통신의 자세한 것은, 그 서비스 프로바이더로 처리된다.

DirectPlay 에는, TCP/IP, IPX, 모뎀, 및 시리얼의 4 종류의 네트워크 접속에 대응하는 서비스 프로바이더가 포함되어 있다. 서비스 프로바이더의 선택 방법에 대해서는, 「DirectPlay 아드레싱」을 참조할것.

주 DirectPlay 는, TAPI (전화 API)를 사용해 모뎀 접속을 처리한다. 이 API 의 사용은, 전화에의 응답에 사용되는 코드가, 메시지 루프의 thread내에 없으면 안 되는 것을 의미한다. Microsoft Windows® 95 시스템으로 모뎀을 사용하려면 , TAPI 의 버젼 2.0 을 인스톨 할 필요가 있다. TAPI 2.0 은, http://www.microsoft.com/ 로부터 다운로드할 수 있다.


DirectPlay 아드레싱

메세지를 전달하려면 , 멀티 플레이어 게임의 각 참가자가 일의의 주소를 가지고 있을 필요가 있다. 주소는, 어플리케이션을 실행하고 있는 컴퓨터를 참조하는지 (디바이스 주소), 어플리케이션이 통신할 필요가 있는 컴퓨터를 참조할 수 있다 (호스트 주소). 디폴트의 DirectPlay8 TCP/IP 다이얼로그를 오버라이드(override) 하려고 하는 어플리케이션 개발자는, 접속이나 열거에 사용하는 포토를 유저에게 오버라이드(override) 시키는 솔루션을 반드시 이행 해야 한다. 1 개(살)의 가능한 솔루션은 디폴트의 DIrectPlay8 TCP/IP 다이얼로그가 이행 하고 있도록(듯이) (즉 "host.domain.com:8090" 와 같이), 유저에게 구두점으로 호스트명에 포토를 추가시키는 방법이다. 이제(벌써) 1 개(살)의 가능한 솔루션은 유저가 포토를 입력할 수 있는 다른 UI 필드를 추가하는 것이다.

Microsoft® DirectPlay® 8.0 에서는, 주소를 URL 캐릭터 라인의 형태로 표현한다. 이 주소 캐릭터 라인은, 게다가IDirectPlay8Peer::Connect 등의 메소드의 입출력 파라미터로서 건네받는 DirectPlay 주소 오브젝트내에 캡슐화된다.

여기에서는, DirectPlay 주소의 2 개 처리 방법에 대해 설명한다.

  • 「DirectPlay URL 」는, 주소 캐릭터 라인을 직접 구축하는 방법이다.
  • 「DirectPlay 주소 오브젝트」는, 주소 오브젝트의 IDirectPlay8Address 인터페이스로 공개되는 메소드를 사용해, 주소 캐릭터 라인을 조작하는 방법이다.


DirectPlay URL

Microsoft® DirectPlay® 에서는, 주소를 URL 로서 표현한다. 일반적으로, URL 는, 스킴, 스킴 separator, 및 데이터 캐릭터 라인의 3 개의 기본 요소가, 이 순서에 늘어놓을 수 있었던 캐릭터 라인이다.

모든 DirectPlay 주소는, 스킴으로서 "x-directplay" 를 사용해, 스킴의 separator로서 ":/" (구두점과 거기에 계속되는 순서 slash)를 사용한다. separator로서 ":/" 를 사용 하면, 후에 계속되는 데이터가 불투명한 것을 나타낸다. 바꾸어 말하면(자), 데이터 캐릭터 라인은 어느 인터넷 표준에도 적합하고 있지 않고, 수취하는 측 어플리케이션에 그대로 건네줄 필요가 있다. 따라서, DirectPlay 의 모든 URL 는 다음의 일반 형식이 된다.

x-directplay:/[data string]

주 스킴의 separator로서 "://" (구두점과 거기에 계속되는 2 개의 순서 slash)를 사용하지 않는 것. 이 separator는, 후속의 데이터가 인터넷 표준에 적합하고 있어, 그 표준에 따라 해석할 수 있는 것을 나타낸다. 혼란을 피하기 (위해)때문에, DirectPlay 에서는,"://" 을 포함한 모든 URL 가 무효라고 보여진다.

설명하는 주제는, 다음과 같다.

  • 데이터 캐릭터 라인
  • 데이터값
  • 데이터값의 개요
  • 샘플 URL


데이터 캐릭터 라인

데이터 캐릭터 라인에는, 주소 정보가 보관 유지된다. 데이터 캐릭터 라인의 최초의 부분은, 세미콜론 (;)으로 단락지어진 일련의 요소 "keyname=value" 로부터 성립되고 있다. 마지막 값의 뒤에 샤프 기호 (#)를 붙여 어플리케이션으로 정의한 캐릭터 라인을 계속하면(자), 옵션의 유저 데이터를 포함할 수가 있다.

키명은, 데이터를 식별해, 값에 들어가 있는 데이터의 종류를 비명시적으로 나타내는 소문자의 캐릭터 라인이다. 예를 들어,"provider" 라고 하는 키명은, Microsoft® DirectPlay® 서비스 프로바이더의 GUID 가, GUID 캐릭터 라인의 형태로 값에 저장 되고 있는 것을 나타낸다. 이하의 문자는 예약이 끝난 상태이므로, 값의 캐릭터 라인에 사용하지 않는 것.

ampersand(&) (&) | 순서 slash (/)
@ 부호 (@) | 샤프 기호 (#)
구두점 (:) | 물음표 (? )
등호 (=) | 세미콜론 (;)

데이터 캐릭터 라인의 최초의 요소는, 프로바이더가 아니면 안된다. 다른 요소는, 임의의 순서로 계속할 수가 있다. 일반적인 URL 는, 다음과 같이 된다.

x-directplay:/provider=%provider GUID%;[keyname1=value1];[keyname2=value2][...]#[user defined string]


데이터값

데이터 캐릭터 라인에 포함되지 않으면 안 되는 값은, 서비스 프로바이더에 따라서 다르다. 예를 들어, 모뎀 프로바이더의 주소에는 전화번호가 필요하지만, LAN 프로바이더에서는 포토 번호가 필요할지도 모른다. 여기에서는, 표준의 데이터값에 대해 자세하게 설명한다. 또, 캐릭터 라인 그 자체 대신에 사용할 수 있는 키명에 대해서도 접한다. Dpaddr.h 에는, 이하의 이름이 정의되고 있다.

  • Application Instance
  • Baud
  • Device
  • Flow Control
  • Host Name
  • Parity
  • Phone Number
  • Port
  • Program
  • Provider
  • Stop Bits

Application Instance

어플리케이션 인스턴스를 식별하는 옵션의 GUID. 접속처의 게임을 지정할 경우에는, 이 값이 사용된다.

키명 : DPNA_KEY_APPLICATION_INSTANCE

키 캐릭터 라인 : "applicationinstance"

데이터형 : GUID

프로바이더 : 모두.

유효한 값 : 임의의 유효한 어플리케이션 인스턴스 GUID.

Baud

baud rate.

키명 : DPNA_KEY_BAUD

키 캐릭터 라인 : "baud"

데이터형 : DWORD

프로바이더 : 모뎀 및 시리얼.

유효한 값 :임의의 유효한 baud rate. 이 값에는, 적절한 정수를 설정해도 괜찮고, Dpaddr.h 에 미리 정의되고 있는 이하의 값의 어느쪽이든을 사용해도 괜찮다.

DPNA_BAUD_RATE_9600
DPNA_BAUD_RATE_14400
DPNA_BAUD_RATE_19200
DPNA_BAUD_RATE_38400
DPNA_BAUD_RATE_56000

Device

로컬 컴퓨터상에서 사용하는 디바이스를 식별하는 GUID. 서비스 프로바이더가 모든 어댑터를 지원 하고 있으면, 디바이스를 지정할 필요는 없다.

키명 : DPNA_KEY_DEVICE

키 캐릭터 라인 : "device"

데이터형 : GUID

프로바이더 : 모두. 다만 디바이스 주소 전용. 호스트 주소는 제외하다.

유효한 값 : 임의의 유효한 디바이스 GUID.

Flow Control

사용하는 flow control의 종류.

키명 : DPNA_KEY_FLOWCONTROL

키 캐릭터 라인 : "flowcontrol"

데이터형 : String

프로바이더 : 시리얼 및 모뎀.

유효한 값 : Dpaddr.h 에 미리 정의되고 있는 이하의 값의 언젠가.

DPNA_FLOW_CONTROL_NONE | DPNA_FLOW_CONTROL_DTR
DPNA_FLOW_CONTROL_XONXOFF | DPNA_FLOW_CONTROL_RTSDTR
DPNA_FLOW_CONTROL_RTS |

Host Name

리모트 호스트 컴퓨터의 이름.

키명 : DPNA_KEY_HOSTNAME

키 캐릭터 라인 : "hostname"

데이터형 : String

프로바이더 : 모두. 다만 호스트 주소 전용. 디바이스 주소는 제외하다.

유효한 값 : 완전하게 수식된 호스트명인가, 또는 닷이 포함되는 주소.

Parity

접속의 패리티.

키명 : DPNA_KEY_PARITY

키 캐릭터 라인 : "parity"

데이터형 : String

프로바이더 : 시리얼 및 모뎀.

유효한 값 : Dpaddr.h 에 미리 정의되고 있는 이하의 값의 언젠가.

DPNA_PARITY_NONE | DPNA_PARITY_MARK
DPNA_PARITY_EVEN | DPNA_PARITY_SPACE
DPNA_PARITY_ODD |

Phone Number

전화번호.

키명 : DPNA_KEY_PHONENUMBER

키 캐릭터 라인 : "phonenumber"

데이터형 : String

프로바이더 : 모뎀.

유효한 값 : 임의의 유효한 전화번호.

Port

옵션의 포토 번호.

키명 : DPNA_KEY_PORT

키 캐릭터 라인 : "port"

데이터형 : DWORD

프로바이더 : IP 및 IPX.

유효한 값 : 임의의 16 비트 정수. 값의 하위 16 비트만이 의미를 가진다. 포토를 지정하지 않았던 경우는, 자동적으로 선택된다.

Program

옵션의 어플리케이션 GUID.

키명 : DPNA_KEY_PROGRAM

키 캐릭터 라인 : "program"

데이터형 : GUID

프로바이더 : 모두.

유효한 값 : 임의의 유효한 어플리케이션 GUID.

Provider

사용하는 Microsoft® DirectPlay® 서비스 프로바이더를 식별하는 GUID.

키명 : DPNA_KEY_PROVIDER

키 캐릭터 라인 : "provider"

데이터형 : GUID

프로바이더 : 모두.

유효한 값 : 임의의 유효한 서비스 프로바이더 GUID.

Stop Bits

stop bit수.

키명 : DPNA_KEY_STOPBITS

키 캐릭터 라인 : "stopbits"

데이터형 : String

프로바이더 : 시리얼 및 모뎀.

유효한 값 : Dpaddr.h 에 미리 정의되고 있는 이하의 값의 언젠가.

DPNA_STOP_BITS_ONE | DPNA_STOP_BITS_TWO
DPNA_STOP_BITS_ONE_FIVE |


데이터값의 개요

이하의 2 개의 겉(표)는, 표준의 데이터값의 개요이며, 각 타입의 서비스 프로바이더가 호스트 주소와 디바이스 주소의 양쪽 모두에 사용하는 값을 나타내고 있다.

호스트 주소

 | IP | IPX | 시리얼 | 모뎀
Application Instance | 생략 가능 | 생략 가능 | 생략 가능 | 생략 가능
Baud | 미사용 | 미사용 | 필수 |
Device | 미사용 | 생략 가능 | 필수 | 필수
Flow Control | 미사용 | 미사용 | 필수 |
Host Name | 필수 | 필수 | 생략 가능 | 생략 가능
Parity | 미사용 | 미사용 | 필수 |
Phone Number | 미사용 | 미사용 | 미사용 | 필수
Port | 필수 | 필수 | 미사용 | 미사용
Program | 생략 가능 | 생략 가능 | 생략 가능 | 생략 가능
Provider | 필수 | 필수 | 필수 | 필수
Stop Bits | 미사용 | 미사용 | 필수 |

디바이스 주소

 | IP | IPX | 시리얼 | 모뎀
Application Instance | 생략 가능 | 생략 가능 | 생략 가능 | 생략 가능
Baud | 미사용 | 미사용 | 필수 | 미사용
Flow Control | 미사용 | 미사용 | 필수 | 미사용
Host Name | 생략 가능 | 생략 가능 | 생략 가능 | 생략 가능
Device | 생략 가능 | 필수 | 필수 | 필수
Parity | 미사용 | 미사용 | 필수 | 미사용
Phone Number | 미사용 | 미사용 | 미사용 | 미사용
Port | 생략 가능 | 필수 | 미사용 | 미사용
Program | 생략 가능 | 생략 가능 | 생략 가능 | 생략 가능
Provider | 필수 | 필수 | 필수 | 필수
Stop Bits | 미사용 | 미사용 | 필수 | 미사용


샘플 URL

이하의 샘플 URL 는, 4 개의 표준 서비스 프로바이더에 대응하는 Microsoft® DirectPlay® URL의 예를 나타내고 있다.

로컬 IP 주소

x-directplay:/provider=%7BEBFE7BA0-628D-11D2-AE0F-006097B01411%7D;device=%7BIP ADAPTER GUID%7D;port=0000230034#IPUserData

로컬 IPX 주소

x-directplay:/provider=%7B53934290-628D-11D2-AE0F-006097B01411%7D;device=%7BIPX ADAPTER GUID%7D;port=00230#IPXUserData

로컬 시리얼 주소

x-directplay:/provider=%7B743B5D60-628D-11D2-AE0F-006097B01411%7D;device=%7BCOM PORT GUID%7D;baud=57600;stopbits=1;parity=NONE;flowcontrol=RTSDTR#SerialUserData

리모트 모뎀 주소

x-directplay:/provider=%7B6D4A3650-628D-11D2-AE0F-006097B01411%7D;device=%7BMODEM DEVICE GUID%7D;phonenumber=555-1212#ModemUserData


주소의 처리

IDirectPlay8Peer ,IDirectPlay8Client , 또는 IDirectPlay8Server 에서 공개되는 Host,EnumHosts, 또는 Connect 메소드를 호출하는 경우는, 주소 오브젝트를 파라미터로서 건네줄 필요가 있다. Microsoft® DirectPlay® 에 충분한 주소 정보가 없다고 호출한 메소드가 실패해,DPNERR_ADDRESSING 가 돌려주어진다. 다만, 메소드를 호출하면나무에, 주소 오브젝트내의 정보가 모두 갖추어져 있을 필요는 없다.

모든 주소 오브젝트에는, 서비스 프로바이더 GUID 가 설정되어 있을 필요가 있지만, 그 외의 데이터값은 생략 가능하다.

  • 서비스 프로바이더가 모든 어댑터를 지원 하고 있으면, 디바이스를 생략 할 수 있다.
  • IP 및 IPX 서비스 프로바이더에서는,Host,EnumHosts, 및 Connect 메소드의 포토 번호를 생략 할 수 있다. 포토 번호는, DirectPlay 로 할당할 수 있다. 이 번호는 상황에 따라서 다르다.
  • OKTOQUERYFORADDRESSING 플래그를 설정 하면, 주소 기에 부족한 정보를 유저에게 묻는 다이알로그 박스를, 서비스 프로바이더를 표시할 수 있다. 유저가 충분한 정보를 제공하지 않으면, 메소드는 실패한다. OKTOQUERYFORADDRESSING 플래그를 설정하지 않았던 경우, 이 다이알로그 박스는 표시되지 않는다. 메소드에 건네준 주소가 부족하면, 메소드는 실패한다. 마지막 2 개의 경우, 돌려주어지는 에러값은 DPNERR_ADDRESSING 가 된다.

IP 및 IPX 서비스 프로바이더에 관해서는, 중요한 주의 사항이 2 개 있다. 이러한 처리가 적절하지 않으면 어플리케이션이 실패할 가능성이 있다.

  • 열거 메소드를 호출하면나무에 NOBROADCASTFALLBACK 플래그를 설정하는 경우는, 호스트명을 건네줄 필요가 있다. 그렇게 하지 않으면 메소드가 실패해, DPNERR_ADDRESSING 가 돌려주어진다.
  • 포토를 지정하지 않는 경우, DirectPlay 에 의해 항상 같은 포토 번호가 선택된다고 생각해서는 안 된다. 특정의 포토 번호를 사용하는 유일한 방법은, 주소로 그 포토 번호를 지정하는 것이다. 포토 번호를 지정하지 않는 경우는, 다음에 커멘드의 진행중에 실제의 값을 취득할 필요가 있다.

디폴트의 DirectPlay8 TCP/IP 다이얼로그를 오버라이드(override) 하려고 하는 어플리케이션 개발자는, 접속이나 열거에 사용하는 포토를 유저에게 오버라이드(override) 시키는 솔루션을 반드시 이행 해야 한다. 1 개(살)의 가능한 솔루션은 디폴트의 DIrectPlay8 TCP/IP 다이얼로그가 이행 하고 있도록(듯이) (즉 "host.domain.com:8090" 와 같이), 유저에게 구두점으로 호스트명에 포토를 추가시키는 방법이다. 이제(벌써) 1 개(살)의 가능한 솔루션은 유저가 포토를 입력할 수 있는 다른 UI 필드를 추가하는 것이다.


DirectPlay 주소 오브젝트

Microsoft® DirectPlay® 에서는, URL 캐릭터 라인을 직접 처리하지 않는다. 대신에, 캐릭터 라인을 DirectPlay 주소 오브젝트 (CLSID_DirectPlayAddress) 내에 캡슐화할 필요가 있다. 이 오브젝트는,IDirectPlay8Address 인터페이스를 공개한다. 이 인터페이스를 사용 하면, 주소 오브젝트에 URL 정보를 삽입하거나 반대로 주소 오브젝트로부터 URL 정보를 추출하거나 할 수 있다.

DirectPlay 주소를 생성 하려면 ,CoCreateInstance 를 호출해 DirectPlay 주소 오브젝트를 생성 할 필요가 있다. 이 결과, 이하의 2 개의 방법의 어느 쪽인지로 주소를 정의할 수 있게 된다.

  • URL 캐릭터 라인을 직접 생성 한다. 다음에, 생성 한 캐릭터 라인을 IDirectPlay8Address::BuildFromURLA 또는 IDirectPlay8Address::BuildFromURLW 를 사용해 삽입한다.
  • IDirectPlay8Address 메소드를 사용해, 캐릭터 라인을 구성하는 각종의 데이터를 오브젝트에 직접 삽입한다.

주소 오브젝트를 받을 때도, 같은 2 개의 선택사항이 있다.

  • IDirectPlay8Address::GetURLA 또는 IDirectPlay8Address::GetURLW 를 사용해, URL 캐릭터 라인 전체를 추출한다. 다음에, 그 캐릭터 라인을 해석해 필요한 정보를 추출한다.
  • 다른 IDirectPlay8Address 메소드를 사용해, 흥미가 있는 특정의 데이터를 주소 오브젝트로부터 추출한다.


DirectPlay 프로토콜

멀티 플레이어 게임에는, 최고의 퍼포먼스를 제공하기 위해서, 효율적으로 유연한 네트워크 메시징 서비스가 필요하게 된다. Microsoft® DirectPlay® 프로토콜은, 모든 DirectPlay 메시징에 사용되는, 트랜스폴트 계층의 메시징 프로토콜이다. DirectPlay 8.0 에서는, 이 프로토콜이 큰폭으로 개정되고 있다. 새로운 프로토콜은, 어플리케이션이 모든 면에서 원활히 동작하기 위해서 필요한 메시징 지원을 제공한다. DirectPlay 프로토콜에는, 이하의 메시징 지원이 포함된다.

  • 고신뢰성 및 저신뢰성의 메세지 전달
  • 시퀀셜 메세지 전달과 비시퀀셜 메세지 전달
  • 메세지의 분할과 복구성
  • 혼잡의 제어
  • 송신의 우선 순위 붙어라
  • 메세지의 타임 아웃

주 DirectPlay 의 이전의 버젼에서는, DirectPlay 프로토콜은 옵션이며, 명시적으로 지정하지 않으면들이라면 없었다. DirectPlay 8.0 에서는, DirectPlay 의 모든 메시징에 이 프로토콜이 사용된다.

이 문서에서는, DirectX 의 동작의 모습, 및 어플리케이션에 있어서의 DirectX 의 사용법에 대해, 개요를 설명한다.

  • 메세지 처리의 기본
  • 메세지의 카테고리
  • 혼잡의 제어
  • 송신의 우선 순위 붙어라
  • 메시징 통계 정보의 감시
  • 미처리 메시지 큐의 감시


메세지 처리의 기본

메세지라고 하는 용어는, 이 문서로 사용되는 경우, 다른 컴퓨터에 송신할 필요가 있는 데이터 블록을 의미한다. 네트워크 프로토콜은, 데이터 블록에 타겟의 네트워크 주소라고 하는 정보를 보관 유지하는 몇개의 비트를 추가해,"패킷" 을 생성 한다. 이 패킷이, 네트워크 데이터의 기본 단위가 된다. 패킷이 타겟으로 닿으면(자), 타겟의 네트워크 프로토콜이, 여분의 비트를 삭제해, 접수측의 어플리케이션에 그 데이터 블록을 건네준다.

사용법은 비슷하지만,"메세지" 라고 하는 용어와 "패킷" 이라고 하는 용어는 엄밀하게는 호환이 아니다. 이 문서에서는, Microsoft® DirectPlay® API 와 교환하는 정보의 단위를,"메세지" 라고 표현한다. 또, 네트워크가 처리하는 정보의 단위를,"패킷" 이라고 표현한다. 패킷은, DirectPlay 내부에서 처리된다. 매우 드문 예외를 제외해, DirectPlay 어플리케이션에서는 메세지만을 처리하면 좋다.

"메세지" 와 "패킷" 을 구별하는 주된 이유는, 네트워크로 처리되는 패킷의 최대 사이즈가 보통 제한되고 있는 것에 있다. 이 사이즈를, 최대 전송 단위 (MTU)라고 한다. 메세지가 작은 경우는, 메세지가 단독 패킷으로 송신되기 (위해)때문에, 2 개의 용어는 사실상 동의이다. 한편, 큰 메세지는, 복수의 패킷에 분할해 송신해, 접수측에서 복구 이루어 없으면 안 되는 것이 있다. DirectPlay 프로토콜에서는, 메세지의 분할 및 복구성이 필요에 따라서 자동적으로 처리된다. 어느 쪽의 경우도, 어플리케이션에 관한한, 메세지를 송신해, 타겟이 그것을 받는다고 하는 것은 변함없다.

주 DirectPlay 가 전달하는 메세지의 사이즈에 제한은 없다. 다만, 단독 메세지에 필요한 패킷수가 증가하는 만큼, 패킷이 없어져 재발송신 해야 하는 확률이 높아진다. 따라서, 분할 및 복구성이 필요한 큰 메세지에서는, 보통, 단독 패킷의 메세지보다 네트워크의 지연 시간이 커진다. 네트워크의 지연 시간을 최소한으로 억제할 필요가 있는 경우는, (네트워크의 손실이 많은 경우에는 특히) 큰 메세지의 송신을 피하는 것. 현재의 접속으로 단독 패킷에 수용할 수 있는 최대의 메세지 사이즈는,IDirectPlay8Peer ,IDirectPlay8Client , 및 IDirectPlay8Server 인터페이스로 공개되는 GetSPCaps 메소드를 호출해 판단할 수 있다.


메세지의 카테고리

Microsoft® DirectPlay® 프로토콜은, 이하의 2 종류의 기본적인 네트워크 메시징을 처리하게 되어 있다.

  • "고신뢰성" 대 "저신뢰성". 타겟 어플리케이션에 메세지가 확실히 전달되는 것을 보증할지 어떨지가 다르다.
  • "시퀀셜" 대 "비시퀀셜". 송신되었을 때와 같은 순서로, 메세지가 타겟으로 닿을지 어떨지가 다르다.

게임에서는, 다양한 목적으로 메시징이 사용되어 개개의 요구도 다양하다. 메시징에의 이 광범위한 요구에 대응하기 위해(때문에), DirectPlay 프로토콜에서는, 메세지를 이하의 4 개의 카테고리로 분류할 수 있다.

  • 고신뢰성으로 시퀀셜
  • 저신뢰성으로 시퀀셜
  • 고신뢰성으로 비시퀀셜
  • 저신뢰성으로 비시퀀셜

DirectPlay 프로토콜에서는, 메세지 마다 카테고리를 할당해, 메시징 방법을 최적화할 수가 있다.

고신뢰성 메시징과 저신뢰성 메시징

메세지는 전송의 과정에서 없어지는 일이 있다. "고신뢰성" 메시징에서는, 모든 메세지가 타겟으로 닿는 것이 보증된다. 데이터의 손실이 용서되지 않을 때는, 이 종류의 메시징이 필요하게 된다. "고신뢰성" 메시징이 많은 스킴에서는, 타겟으로 대해 각 메세지의 수신 확인을 요구한다. 지정된 타임 아웃 시간내에 수신 확인이 닿지 않는 경우, 발신인은 메세지를 재발송신 한다. 보통, 메세지가 도착한 것을 나타내는 수신 확인을 발신인이 받을 때까지, 이 순서가 반복해진다.

DirectPlay 프로토콜에서는, 재발송신의 회수에 상한이 설정되어 있다. 재발송신을 어느 정도 반복해도 수신 확인이 닿지 않는 경우, DirectPlay 는 접속이 없어진 것이라고 봐, 접속을 닫는다.

저신뢰성 메시징은, 가장 간단한 형태의 네트워크 통신이다. 메세지가 타겟으로 전달되는 것을 보증하지 않기 때문에, 고신뢰성 메시징보다 고속으로 통신할 수 있다. 발신인이 메세지를 송신한다. 타겟으로 메세지가 도착하지 않는 경우, 발신인은 메세지를 재발송신 하지 않고, 패킷은 없어진다.

저신뢰성 메시징은, 주로, 메세지가 없어지지 않는 것보다 속도 또는 대역폭을 우선하는 경우에 사용된다. 예를 들어, 고대역폭의 스트리밍 미디어 어플리케이션에서는, 저신뢰성 메시징을 채용하는 것이 많다. 이러한 어플리케이션에서는, 대역폭을 수신 확인이나 재발송신에 충당할 여유가 없고, 없어진 메세지의 재발송신을 기다리는 일도 할 수 없다. 메세지가 가끔 없어지는 것은, 품질에 거의 영향을 주지 않는 것이 많아, 무시해도 문제 없다.

시퀀셜 메시징과 비시퀀셜 메시징

메세지는 특정의 순서로 발신인의 손을 떠난다. 다만, 송신되었을 때와 같은 순서로 메세지가 타겟의 컴퓨터에 닿는다고 하는 보증은 없다. 예를 들어, 메세지가 없어져 재발송신이 필요하게 되었을 경우, 보통, 그 메세지는 원의 순서로 뒤에 있던 메세지보다 후에 도착한다.

시퀀셜 메시징에서는, 메세지에 파묻힌 순서 정보를 사용해, 메세지가 올바른 순서로 타겟 어플리케이션에게 건네진다. 타겟 어플리케이션이 메세지를 올바른 순서로 수신해야 할 때에는, 이 종류의 메시징이 필요하게 된다. 순서 대로가 아닌 메세지는, 빠져 있는 메세지가 도착할 때까지 버퍼링 된다.

비시퀀셜 메시징에서는, 메세지가, 송신된 순서에 관계없이, 타겟 컴퓨터에 닿는 것과 동시에 타겟으로 건네받는다. 비시퀀셜 메시징은, 빠져 있는 패킷을 기다릴 필요가 없기 때문에, 메세지가 순서대로 닿는 것보다 속도를 우선하는 경우에 사용되는 것이 많다. 순서 대로가 아닌 메세지는 무시된다.

최적인 메세지 카테고리의 선택

메세지에 적절한 카테고리의 선택은, 멀티 플레이어 게임을 개발하는데 중심이 되는 문제이다. DirectPlay 에는 메시징을 관리하기 위한 툴이 준비되어 있지만, 메세지 카테고리의 선택은, 최종적으로는 메세지의 의미와 게임의 성질에 의존한다.

최적인 메세지 카테고리를 선택하기 위한 일반적인 가이드 라인은, 이하와 같이 된다.

  • 내용적으로 문제가 없으면, 비보증의 메시징을 사용한다. 예를 들어, 플레이어의 최신 위치를 빈번하게 송신하는 경우를 생각한다. 갱신 내용은 서로 무관계하고, 새로운 정보는 이전의 정보 모두에게 취해 대신한다. 갱신 내용이 없어져도, 다음번의 갱신으로 플레이어의 게임 상태를 유지할 수 있다. 메세지가 없어져 재발송신 되면(자), 후속의 갱신 메세지보다 후에 도착할 가능성이 있다.
  • 데이터의 손실이 용서되지 않을 때에는, 보증이 있는 메시징을 사용한다. 예를 들어, 텍스트 베이스의 채팅 기능에서는, 모든 문자를 그 타겟으로 전달할 필요가 있다.
  • 메세지의 순서가 중요한 때에는, 시퀀셜 메시징을 사용한다. 예를 들어, 스트리밍 미디어 어플리케이션에서는, 보통, 시퀀셜의 저신뢰성 메시징을 채용한다. 메세지가 가끔 없어지는 것은 용서되지만, 메세지가 순서대로 닿지 않으면 문제가 일어날 가능성이 있다.


혼잡의 제어

이상적인 환경에서는, 메세지를 필요한 만큼 송신할 수 있다. 메세지는 즉시 타겟에 닿아, 즉석에서 처리된다. 게임과 관계되는 모든 컴퓨터가, 충분한 처리 능력을 가져, 부하의 가벼운 고대역폭의 네트워크 링크로 접속되고 있으면, 이 이상적 환경에 가까워질 수가 있다. 게다가, 메세지를 필요한 만큼 송신할 수 있다. 다만, 많은 요인에 의해 "혼잡" 이 발생해, 메시징이 이상보다 늦어지는 일이 있다.

  • 네트워크의 지연 시간. 이상적인 상황에서도, 메세지가 네트워크를 통해서 발신인으로부터 타겟으로 건너려면 , 어느 정도의 시간이 걸린다 (인터넷을 통과하는 경우는 특히). 수신 확인, 없어진 패킷의 재발송신, 또는 순서 대로가 아닌 패킷의 복구성을 하면(자), 이 시간은 한층 더 길어진다.
  • 네트워크의 대역폭. 컴퓨터가 메세지를 송수신 할 수 있는 속도는, 네트워크의 대역폭에 의해 제어된다. 네트워크 링크의 대역폭의 범위는 넓다. 또, 고대역폭의 네트워크여도, 트래픽의 수준이 높으면 속도가 떨어질 가능성이 있다. 저대역폭의 접속을 사용하고 있는 플레이어가 있는 경우, 그러한 플레이어는, 한정된 속도로 밖에 메세지를 송수신 할 수 없다.
  • 처리 속도. 네트워크의 대역폭이 높고, 지연 시간이 적어도, 수신한 메세지를 타겟 어플리케이션이 처리하려면 , 어느 정도의 시간이 걸린다. 세션내에 비교적 저속의 컴퓨터를 사용하고 있는 플레이어가 있는 경우, 이러한 플레이어가 수신한 메세지를 처리할 수 있는 속도는, 메세지의 송신 속도보다 낮아질 가능성이 있다.

메세지의 슬롯 링

메세지의 송신 속도를 제어하지 않으면 대량의 메세지가 타겟으로 닿아, 처리 다 할 수 없을 가능성이 있다. 이 상황을 피하기 (위해)때문에, Microsoft® DirectPlay® 프로토콜에서는, 메세지의 송신 속도를 "슬롯 링" 한다. 슬롯 링의 최종적인 효과는, 타겟이 메세지를 처리할 수 있는 속도에 의해, 메세지가 송신되는 속도가 제어되는 것이다.

슬롯 링은,"sliding window" 메카니즘을 사용해 이행 된다. sliding window는, 기본적으로는 한정된 수의 슬롯을 가지는 큐이며, 수신되어 있지 않은 송신 끝난 메세지를 보관 유지한다. 유출하는 메세지는, 메세지의 카테고리에 관계없이, 모두 이 큐에 넣어진다. 송신이 끝난 메시지 큐가 가득하게 되면(자), 큐내의 메세지중 한쪽이 수신될 때까지, 유출하는 메세지를 받아들일 수 없게 된다.

최고의 퍼포먼스를 제공하기 위해서는, sliding window의 사이즈를 현재의 네트워크 상황에 맞출 필요가 있다. DirectPlay 프로토콜에서는, 송신이 끝난 메시지 큐내의 메세지수나 총바이트수등의 요소가, 자동적으로 감시된다. 다음에, 현재의 네트워크 상황에 맞추어 메시징을 최적화하기 위해(때문에), 이 정보를 사용해 sliding window의 사이즈가 동적으로 조정된다.

접속의 검사

링크가 이용되어 있지 않으면 DirectPlay 프로토콜에서는, 고신뢰성의 하늘 패킷을 송신해 반복 접속을 테스트한다. 재발송신을 어느 정도 반복해도 타겟으로부터 수신 확인이 닿지 않는 경우, DirectPlay 는 접속이 절단 된 것이라고 본다.


송신의 우선 순위 붙어라

메세지의 중요성은, 메세지 마다 다르다. 어느 메세지는 타임 크리티컬로, 할 수 있는 한 빠르게 전달해야 한다. 또, 어느 메세지는, 필요에 따라서 늦출 수가 있고, 송신마저 하지 않아도 좋을지도 모른다. 혼잡의 제어 알고리즘의 1 개의 문제는, 어플리케이션이 메세지를 생성 하는 속도가, 송신 가능한 속도를 웃도는 경우이다. 이러한 경우에는, 유출용의 슬롯이 열릴 때까지, 미송신의 메세지를 큐에 보존할 필요가 있다. 미송신의 메세지를 모두 단독의 미처리 메시지 큐 로 유지하면(자), 우선도의 낮은 메세지가 먼저 송신될 때까지, 우선도의 높은 메세지가 블록 될 가능성이 있다.

Microsoft® DirectPlay® 프로토콜에서는, 3 개의 미처리 메시지 큐 (저우선도, 안우선도, 및 고우선도)를 준비하는 것에 의해, 이 문제를 해결한다. 송신이 끝난 메시지 큐의 슬롯이 열리면(자), 다음에 송신해야 할 메세지가 다음과 같이 선택된다.

  1. 고우선도 큐내에서 가장 낡은 메세지를 송신한다.
  2. 고우선도 큐에 메세지가 없는 경우는, 안우선도 큐내에서 가장 낡은 메세지를 송신한다.
  3. 안우선도 큐에 메세지가 없는 경우는, 저우선도 큐내에서 가장 낡은 메세지를 송신한다.

이 우선도 메카니즘에 의해, 다른 그다지 중요하지 않은 메세지가 이미 발행되고 있어도, 타임 크리티컬인 메세지를 할 수 있는 한 빠르게 처리할 수가 있다.

송신의 타임 아웃

슬롯 링의 1 개의 결과로서, 메세지가 미처리 메시지 큐내에 비교적 장시간 머무는 일이 있다 (우선도가 낮은 경우는 특히). 경우에 따라서는, 메세지가 장시간 보관 유지되고 있는 동안에, 그 메세지에 취해 대신하는 후속 메세지가 도착하는 일이 있다. 이러한 메세지는, 이제(벌써) 불필요하다. 예를 들어, 플레이어의 최신 위치를 나타내는 메세지를 주기적으로 송신하는 경우를 생각한다. 갱신 내용은 서로 무관계하고, 최신의 정보는 이전의 정보 모두에게 취해 대신한다. 미처리 메시지 큐내에 플레이어의 최신 위치가 2 개 있는 경우, 송신할 필요가 있는 것은 가장 새로운 것 뿐이다.

DirectPlay 프로토콜에서는, 생략 가능의 타임 아웃값을 메세지에 추가하는 것으로, 낡은 메세지의 문제에 대응할 수 있다. 타임 아웃 시간이 지났을 때에, 아직 미처리 메시지 큐에 보관 유지되고 있으면(자), 그 메세지는 삭제된다.

절단

어플리케이션이 절단 메세지를 송신 하면, 그 메세지가 저우선도의 미처리 메시지 큐의 마지막에 추가되어 프로토콜이 유출하는 메세지의 접수를 정지한다. 이 처리에 의해, 모든 미처리 메세지가 링크 절단전에 송신된다. 절단 메세지는, 고신뢰성의 시퀀셜 메세지로서 송신되어 타겟으로 닿는 것이 보증되고 있지만, 그 전에 큐내에 있는 것 외의 메세지가 모두 전달된다.


메시징 통계 정보의 감시

메시징의 요소의 상당수는 Microsoft® DirectPlay® 프로토콜로 자동적으로 처리되지만, 메시징의 동작은 어플리케이션으로 감시해야 한다. 예를 들어, 상시 송신하는 메세지의 양에 전달 속도가 따라잡지 않는 것 같으면, 메시징 스킴을 수정할 필요가 있을지도 모른다.

네트워크 상황은 항상 변화하고 있으므로, 네트워크 동작의 감시, 및 그 결과에 응한 메시징 스킴의 조정은, 정기적으로 실시하지 않으면 안 된다. 이것에는, 메시징을 지원 하는 모든 DirectPlay 8.0 인터페이스로 공개되는 GetConnectionInfo 메소드를 호출한다. GetConnectionInfo 는, 이하를 포함한 각종의 통계 정보가 들어간 구조체를 돌려준다. 이 통계 정보를 사용해 메시징 스킴을 미조정할 수가 있다.

  • 왕복 시간
  • throughput
  • 송신 패킷수
  • 수신 패킷수
  • 재발송신패킷수
  • 유실 패킷수
  • 전송 메세지수 (우선도별)

주 메시징 통계 정보를 취득하려면 , 실제의 네트워크 트래픽을 감시한다. 접속을 초기화한 직후에 GetConnectionInfo 를 호출하면, 데이터가 단시간 밖에 수집되지 않기 때문에, 통계 정보가 참고가 되지 않는 것이 있다.


미처리 메시지 큐의 감시

미처리 메시지 큐는, 너무 커지지 않게 감시해야 한다. IDirectPlay8Peer ,IDirectPlay8Client , 및 IDirectPlay8Server 인터페이스는, 모두 GetSendQueueInfo 메소드를 공개한다. 이 메소드를 사용 하면, 큐내의 현재의 메세지수와 바이트수를 확인할 수 있다. 디폴트에서는 3 개의 큐의 합계가 돌려주어지지만, 3 개의 우선도 각각의 값을 취득할 수도 있다.


네트워크 사용량의 최적화

쾌적한 게임 체험의 제공이란, 보통, 최신 정보나 그 외의 정보를, 타겟의 처리 능력을 넘지 않는 범위에서, 할 수 있는 한 빠르게 송신하는 것을 의미한다. Microsoft® DirectPlay® 프로토콜과 비동기 메시징을 조합하면(자), 메시징 방법을 동적으로 최적화해, 유저에게 쾌적한 게임 체험을 제공할 수가 있다.

메시징의 대부분에서는,IDirectPlay8Peer::SendTo ,IDirectPlay8Client::Send , 또는 IDirectPlay8Server::SendTo 메소드를 사용한다. 이러한 메소드는, 보통, 메세지 카테고리에 관계없이 비동기에게 동작한다. 메소드로부터는 즉석에서 복귀해, 메세지가 실제로 송신되면(자), 메세지 핸들러에 DPNMSG_SEND_COMPLETE 메세지가 도착한다. 한편, DPNSEND_SYNC 플래그를 설정하면, 메세지를 동기에 송신할 수 있다. 그 경우, 메소드는 메세지가 실제로 송신될 때까지 블록 한다.

DirectPlay 프로토콜의 슬롯 링 메카니즘에서는, 클라이언트의 처리 능력을 넘는 속도로 메세지가 건네받지 않는 것이 보증된다. 다만, 유출용의 큐에 메세지가 들어가는 빈도는 제어되지 않는다. 이 때문에, 미송신 메세지의 큐에 대량의 메세지가 모여 버리는 일이 있다. 이 상황은 메세지의 송신 빈도를 억제하는 것에 의해 피할 수가 있지만, 이렇게 하면(자) 유저에게 제공되는 게임 체험의 품질이 불필요하게 저하할 수도 있다. 가장 좋은 메시징 방법은, 타겟의 처리 능력을 넘지 않는 범위에서, 메세지를 할 수 있는 한 빠르게 송신하는 것이다.

메시징 방법을 최적화하기 위한 힌트는, 이하와 같이 된다.

  • 메세지는 할 수 있는 한 비동기에 송신한다. 메세지를 동기에 송신 하면, 슬롯 링 메카니즘이 메세지의 송신을 허락할 때까지, 메소드가 블록 한다.
  • 미처리 메시지 큐와 네트워크 통계 정보를 감시한다. 큐에 메세지가 적은지, 또는 전혀 없는 경우는, 전송 속도를 올린다. 큐가 큰지, 또는 급속히 거대화 하고 있는 경우는, 전송 속도를 내려 할 수 있으면 일부의 메세지를 취소한다. 상세한 것에 대하여는,「송신의 우선 순위 붙이고」에 있는 송신 타임 아웃의 설명을 참조할것.
  • 플레이어 마다 미처리 메시지 큐를 분석한다. 메세지의 수신 속도에는, 플레이어 마다 상당한 차이가 있을지도 모른다. 그 경우, 일괄의 통계 정보는 참고가 되지 않는다. 그룹에의 송신은 아니고, 지명에 의한 송신을 검토한다.
  • 개개의 메세지에 적절한 카테고리를 선택한다. 오버헤드가 가장 큰 카테고리는, 가장 중요한 메세지를 위해서(때문에) 예약한다.
  • 메세지에 우선 순위를 붙여, 가장 중요한 메세지가, 비교적 중요하지 않은 메세지를 위해서(때문에) 늦는 일 없이, 즉석에서 송신되도록(듯이) 한다.
  • 미처리 메시지 큐가 너무 커지지 않게 한다. 미처리의 메세지가 많다고 메세지의 전송이 늦을 뿐만 아니라, 메모리 리소스가 대량으로 소비되는 일도 있다.
  • Send 및 SendTo 메소드의 타임 아웃 기능을 사용해, 미처리 메시지 큐로부터 낡은 메세지를 자동적으로 소거한다.
  • 메세지 근처의 데이터량을 최소한으로 억제한다. 보통, 큰 메세지를 소수 송신하는 것보다는, 작은 메세지를 빈번하게 송신하는 것이 좋다.
  • 미처리 메시지 큐를 조사할 때, 루프의 간격을 그다지 짧게 하지 않는 것. 간격의 짧은 루프는, CPU 사이클의 쓸데없다. 대신에, 보통 어느 정도의 시간에 다음의 송신을 할 수 있게 될까를 예상해, 그 시간 sleeve 하는 (분)편이 좋다.


어플리케이션에 있어서의 DirectX 프로토콜의 사용법

여기에서는, 어플리케이션으로부터 Microsoft® DirectPlay® 프로토콜의 기능을 어떻게 사용할 수 있는지를 설명한다.

메세지의 송신에는, 5 개의 DirectPlay 인터페이스를 사용할 수 있다.

  • IDirectPlay8Peer
  • IDirectPlay8Client
  • IDirectPlay8Server
  • IDirectPlay8LobbyClient
  • IDirectPlay8LobbiedApplication

메세지를 송신하려면 , 사용하는 인터페이스에 응해 Send 또는 SendTo 라고 하는 메소드를 호출한다. 이것들 5 개의 메소드의 사용법은 거의 같지만, 자세한 것은 다르다. 상세한 것에 대하여는, 해당하는 레퍼런스 페이지를 참조할것.

Send 및 Sendto 메소드에서는, 파라미터를 사용해 DirectPlay 프로토콜이 가지는 많은 기능을 제어할 수 있다. 예를 들어,IDirectPlay8Peer::SendTo 의 dwFlags 필드에서는 이하를 지정할 수 있다.

  • 메세지의 우선도.
  • 고신뢰성이나 저신뢰성인가.
  • 시퀀셜이나 비시퀀셜인가.

상세한 것에 대하여는, 해당하는 메소드의 레퍼런스를 참조할것.

어플리케이션에 메세지가 도착하면(자), 콜백 함수에 DPN_RECEIVE 메세지가 도착한다. 관련하는 구조체에는, 데이터 블록에의 포인터와 함께, 메세지의 발신기지라고 하는 정보가 저장 되고 있다.


DirectPlay 콜백 함수와 multi-thread에 관한 문제

Microsoft® DirectPlay® 와 DirectPlay Voice 에서는, DirectPlay 가 발행하는 이벤트를 처리하기 위해(때문에), 몇개의 콜백 함수를 독자적으로 이행 할 필요가 있다. DirectPlay 는 multi-thread화 되고 있으므로, 동시에 복수의 이벤트를 발행하는 일이 있다. 이 때문에, 중복 하는 복수의 콜백이 어플리케이션에 닿을 가능성이 있다.

DirectPlay 에는, 콜백의 지시에 대응하기 위해서, thread 풀이 보관 유지되고 있다. 콜백은, DirectPlay 가 보관 유지하는 풀내의 thread로부터 기동된다. Microsoft Windows 2000 에서는, 이 thread 풀의 사이즈를 프로세스 마다 구성할 수 있다. 또, DirectPlay 에서는, Windows 2000 상에서 동작할 경우에 I/O 완료 포토를 사용한다. I/O 완료 포토는 고도의 문제이며, 여기에서는 설명하지 않는다. 이 건에 대해서는, MSDN (Microsoft Developer Network )의 문서나, Win32 의 multi-thread에 관한 현재 입수 가능한 레퍼런스를 참조할것을 추천 한다.

따라서, DirectPlay 콜백으로 올바르게 신뢰성의 높은 데이터 액세스를 실시하려면 , 동기를 multi-thread화하는 수단을 이행 해야 한다. 이것을, 콜백을 "재입가능" 또는 "thread 세이프" 로 한다, 라고 말한다.

Microsoft Windows OS 패밀리에서는, 현재, multi-thread 환경에서 데이터의 동기를 잡기 위해서(때문에), 이하의 3 개의 방법이 준비되어 있다.

  • 뮤텍스 오브젝트
  • semaphore 오브젝트
  • 크리티컬 섹션 오브젝트

크리티컬 섹션 오브젝트를 사용해 동기를 잡는 방법은, DirectX 8.0 SDK 에 부속되는 DirectPlay 의 음성 관련 샘플에 나타나고 있다. 뮤텍스 오브젝트 또는 semaphore 오브젝트를 이행 하는 경우, 이러한 주제는, Microsoft Platform SDK 에도, 많은 레퍼런스 북에도 기재되어 있으므로, 참조할것. 이러한 동기 수단은, 만일 어떠한 문제가 일어났을 경우, 복잡하고 어려운 디버그 작업이 필요하게 된다. 이 때문에, 어느쪽이든을 이행 하려면 , 개개의 분야에 관한 상당히 진행된 지식이 없으면 안 된다.

DirectPlay 의 thread 모델은, 최고의 효율을 얻을 수 있도록(듯이) 최적화되고 있다. 이 때문에,"송신" 처리중, 및 수신 메세지를 포함한 "지시" 메세지중에, thread 문맥이 바뀔 것은 없다.

여기에서는, 「DirectPlay 의 네트워킹 콜백」에 대해 설명한다.

상세한 것에 대하여는,「DirectPlay 와 DirectPlay Voice 에 있어서의 콜백 함수의 이행」을 참조할것.


DirectPlay 의 네트워킹 콜백

Microsoft® DirectPlay® 의 네트워킹 콜백 함수는,PFNDPNMESSAGEHANDLER 형이다. 네트워킹 세션의 종류에 응해,IDirectPlay8Peer::Initialize ,IDirectPlay8Client::Initialize , 또는 IDirectPlay8Server::Initialize 를 사용해 콜백 함수의 주소를 등록한다.

동기에 관한 문제

DirectPlay 콜백에서의 처리중에 게임 데이터의 정합성을 유지하기 위해서(때문에)는, 3 개의 thread 동기 오브젝트의 어느쪽이든을 채용할 필요가 있다.

게임 데이터가 어떻게 파손하는지를 설명하기 위해(때문에), 콜백으로 구조체에 게임 데이터의 패킷을 삽입하는 경우에 대해 생각한다. 1 번째의 콜백이 완료하지 않는 동안에, 다른 thread로부터 콜백이 재귀적으로 실행되면(자), 이 thread도, 메모리내의 같은 장소에 있는 구조체에 액세스 해, 내용을 변경하려고 할 가능성이 있다. 이 결과, 1 번째의 thread가 구조체에 둔 데이터가, 2 번째의 thread가 구조체에 둔 데이터로 덧쓰기된다. 이것은 multi-thread의 매우 간단한 예이며, thread가 정상적으로 동기 하지 않게 되는 원인은 그 밖에도 여러 가지 있으므로, 주의가 필요하다. 또, 자작을 시도하기 전에, multi-thread 콜백의 이행에 관한 고도의 지식을 몸에 걸치는 일도 중요하다.

DirectPlay 네트워킹 세션으로 데이터를 동기 시키는 방법의 예에 대해서는,「크리티컬 섹션 오브젝트를 사용한 DirectPlay 네트워킹 콜백의 이행」을 참조할것.

워커 thread

"워커 thread" 를 자작하는 것도 1 개의 방법이다. 워커 thread는, 어플리케이션으로 정의되는 이제(벌써) 1 개의 multi-thread 콜백이며, DirectPlay 콜백과 관계없이 게임 데이터를 처리하기 위해서 생성 된다. 이 목적을 달성하기 위해서, 가장 일반적인 수단으로서 DirectPlay 의 네트워킹 콜백 thread에서는, 받은 데이터를 버퍼에 보존한다. 다음에, 새로운 thread가 생성 되어 버퍼링 데이터를 처리하도록(듯이) 알리는 메세지가 워커 thread 콜백에 송신된다.

multi-thread의 퍼포먼스에 관한 문제와 비동기 처리

DirectPlay 콜백내에서 메세지의 처리에 걸치는 시간은, 신중하게 검토할 필요가 있다. DirectPlay 콜백내에서 대량의 데이터를 처리해, 데이터를 잠그는 메카니즘을 사용해 thread의 동기를 잡으면(자), 다른 thread가 콜백을 실행하기 위해서 대기할 경우에 블록 문제가 일어난다.

한편, 워커 thread를 이행 해, 게임 데이터의 처리를 다른 콜백에 맡기면(자), 자작의 thread와 DirectPlay 로 생성 된 thread의 사이에 CPU 가 문맥을 바꾸기 (위해)때문에, 오버헤드가 큰폭으로 증가하는 위험성이 있다. 이 방법을 채용할 수 있는 것은, 게임 데이터의 처리에 매우 시간이 걸려, 게임의 리얼 타임 처리에 있어 빠뜨릴 수 없는 데이터가 아닌 경우에 한정된다. 예를 들어, 플레이어의 위치 데이터는, 게임내에서 플레이어를 리얼타임에 배치하기 위해서 빠뜨릴 수 없는 데이터이므로, 워커 thread로 처리하는 것은 추천 되지 않는다.

콜백으로부터 DPNSUCCESS_PENDING 를 돌려주어, 데이터 버퍼에의 포인터를 생성 해, 워커 thread가 그 포인터를 이용할 수 있도록(듯이) 할 수도 있다. 워커 thread는, 게임 데이터를 다 처리하면(자) , 사용하고 있는 위상기하학에 응해 IDirectPlay8Peer 또는 IDirectPlay8Client 의 ReturnBuffer 메소드를 호출한다.


DirectPlay Voice 에 대해

Microsoft® DirectPlay® Voice 는, 네트워크 세션 및 네트워크 전송을 실시하는 DirectPlay 와 통합된, 풀 음성 통신 API 이다.

DirectPlay Voice 는, 음성의 녹음/재생을 실시하기 위해서(때문에), DirectSound 와도 통합되고 있다. 음성 데이터를 다른 재생 버퍼에 배분하는 능력이나, 특수 오디오 이펙트 (3D 사운드포시쇼닝등)의 사용을 포함해 DirectSound 가 가지는 모든 오디오 기능이 계승되고 있다.

DirectPlay Voice 의 네트워킹

DirectPlay Voice 의 위상기하학

음성 호스트의 이행

오디오 디바이스의 테스트

음성 CODEC

자동 게인 제어

전송 제어

캡춰 포커스

지터-버퍼

working set에 대한 가이드 라인


DirectPlay Voice 의 네트워킹

Microsoft® DirectPlay® Voice 는, 미디어에 의존하지 않는 네트워크 전송과 플레이어 관리를 실시하기 위해서(때문에), DirectPlay 세션을 사용한다. DirectPlay Voice API 의 세션 제어 기능은, DirectPlay 와는 다르다. DirectPlay Voice 가 음성 통신을 송수신 하기 위해서는, DirectPlay 네트워크 전송 세션도 사전에 생성 되고 있을 필요가 있다. DirectPlay Voice 는, IDirectPlay4 오브젝트와 IDirectPlay8 오브젝트의 어느쪽이든을, 네트워크 전송에 사용할 수 있다.

DirectPlay Voice 를 멀티 플레이어 게임과 함께 동시 처리로 사용하고 있는 경우에는, 게임 고유의 데이터를 교환하기 위해서, 게임에서도 전송 세션을 사용할 가능성이 높다. 이렇게 하면(자), 게임 데이터와 음성 데이터의 사이에 네트워크 리소스의 사용을 최적화할 수가 있다.

또, 스탠드얼론의 음성 회의 어플리케이션등으로는, 음성 세션 전용의 전송 세션을 생성 해 사용해도 괜찮다.


DirectPlay Voice 의 위상기하학

Microsoft® DirectPlay® Voice 세션은, 음성 통신의 전송에 DirectPlay 네트워크 세션을 사용한다. 네트워크 세션이 생성 되면(자), 3 개의 위상기하학의 어느쪽이든을 사용하는 DirectPlay Voice 오브젝트를 생성 할 수 있게 된다.

  • 피어 투 피어 음성 위상기하학
  • 전송 서버 음성 위상기하학
  • 믹싱 서버 세션

선택해야 할 위상기하학은 다양한 요소에 따라서 다르다. 이러한 요소에 대해서는, DirectPlay Voice 위상기하학의 각 주제로 설명한다. 모든 음성 위상기하학이, 모든 종류의 DirectPlay 네트워킹 세션을 통해서 전송 할 수 있다고는 할 수 없기 때문에, 주의 해야 한다.


피어 투 피어 음성 위상기하학

피어 투 피어 위상기하학을 채용하고 있는 Microsoft® DirectPlay® Voice 세션에서는, 개개의 음성 세션 클라이언트가, 다른 모든 음성 세션 클라이언트에, 그 음성 오디오 데이터를 직접 스트림 한다. 각 클라이언트는, 유입하는 개개의 음성 오디오 스트림을 모두 받아, 받은 스트림을 믹싱 해, 믹싱 끝난 신호를 클라이언트의 컴퓨터로 재생한다.

피어 투 피어 위상기하학을 채용하는 이점은, 음성 세션내의 컴퓨터에, 높은 대역폭이나 프로세서 능력이 필요하지 않은 것에 있다. 다만, 각 클라이언트의 컴퓨터에 있어서의 대역폭과 프로세서의 사용량은, 출입하는 오디오 스트림의 수에 따라서 다르다. 유출하는 음성 오디오 스트림의 수는, 음성 세션에 참가하고 있는 타겟의 수로 동일하다. 다만, 후술 하도록(듯이), 네트워크 프로바이더가 본래의 멀티 캐스트를 실행할 수 있는 경우는 예외이다. 유입하는 음성 오디오 스트림의 수는, 다른 몇개(살)의 음성 세션 클라이언트가 그 클라이언트를 타겟으로 하고 있는지, 및 다른 클라이언트중 몇개(살)이 이야기하고 있을까에 따라서 다르다.

게임 설계의 면으로부터 생각하면(자), 1 개의 음성 세션 클라이언트를, 6 ~ 8개(살)을 넘는 클라이언트가 타겟으로 하는 것은, 실용적이지 않다. 6 ~ 8개의 클라이언트가 모두 동시에 이야기 내면(자), 회화가 혼란해, 클라이언트간의 교환이 곤란하게 될 가능성이 있다.

DirectPlay 네트워크 세션이 본래의 멀티 캐스트를 지원 하고 있으면, 유출하는 음성 오디오 스트림의 수를 상당히 줄일 수가 있다. 전클라이언트를 1 개의 멀티 캐스트 네트워크에 포함해 음성 스트림의 타겟을 1 개의 DirectPlay 그룹으로 하면(자), 유출하는 스트림은 단 1 개(살)이 된다.

피어 투 피어 음성 위상기하학을 채용하고 있는 DirectPlay 음성 세션은,IDirectPlayVoiceClient::Create3DSoundBuffer 메소드를 사용한 음성 데이터의 3D 공간화를 지원 한다.

네트워크 전송이 클라이언트/서버 세션의 경우에는, 음성 피어 투 피어 음성 위상기하학을 채용하고 있는 음성 세션을 사용할 수 없기 때문에, 주의 해야 한다.


전송 서버 음성 위상기하학

전송 서버 위상기하학을 채용하고 있는 Microsoft® DirectPlay® 음성 세션에서는, 세션내의 1 대의 컴퓨터가 전송 서버의 역할을 한다. 음성 세션내의 각 클라이언트는, 음성 데이터를 전송 서버에 스트림 한다. 전송 서버는, 세션내외의 클라이언트 모두에게, 이 음성 데이터를 전송 한다. 각 클라이언트가, 전송 서버로부터 전송 된 유입 오디오 스트림을 모두 받는다. 마지막으로, 각 클라이언트의 컴퓨터가, 유입하는 스트림을 믹싱 해 재생한다.

전송 서버 위상기하학을 채용하고 있는 음성 세션에서는, 유출하는 음성 오디오 스트림이 1 개 밖에 없기 때문에, 개개의 클라이언트에 있어서의 유출 대역폭의 요건은 일정한다. 유입 대역폭과 프로세서의 요건은, 피어 투 피어 위상기하학을 채용하고 있는 음성 세션에서의 요건과 같지만, 유입하는 음성 오디오 스트림의 수에 따라서 다르다.

전송 서버에 의한 DirectPlay 음성 세션에서는, 서버에 개개의 클라이언트보다 큰폭으로 높은 대역폭이 필요하게 된다. 다만, 서버상에서는 음성 데이터의 압축이나 압축 해제가 발생하지 않기 때문에, 프로세서 요건은 높지 않다. 이와 같이 컴퓨터의 프로세서에의 부하가 줄어드는 것은, 컴퓨터 자체의 퍼포먼스를 악화시키는 일도, 게임 서버나 같은 컴퓨터로 동작하고 있는 클라이언트 프로그램의 퍼포먼스를 악화시킬 것도 없고, 높은 대역폭으로 접속하고 있는 개개의 클라이언트의 컴퓨터가, 전송 서버의 호스트가 될 수 있는 것을 의미한다.

피어 투 피어 위상기하학을 채용하고 있는 음성 세션에서는, 개개의 클라이언트에 있어서의 유출 대역폭의 요건이, 유입 대역폭의 요건보다 큰폭으로 높은 것이 보통이다. 따라서, 유출 대역폭의 요건을 오디오 스트림 1 개(살)로 줄이면, 대역폭의 총사용량을 큰폭으로 줄일 수가 있다. 예를 들어, 8 명이 참가하고 있는 음성 세션으로, 전클라이언트가 서로의 소리를 들을 수가 있는 경우에는, 사용하고 있는 컴퓨터로 음성 데이터가 캡춰 및 송신될 때마다, 그 클라이언트로부터 7 개의 음성 스트림이 유출한다. 다만, 전클라이언트가 동시에 이야기하는 것은 거의 없고, 동시에 유입하는 음성 스트림은 2 ~ 3 개(살)보다 적은 것이 보통이다.


믹싱 서버 세션

믹싱 서버 세션에서는, 세션내의 1 대의 컴퓨터가 믹싱 서버의 역할을 한다. 각 클라이언트가, 음성 데이터를 믹싱 서버에 스트림 한다. 믹싱 서버는, 개개의 음성 스트림의 타겟을 조사한 데다가, 적절한 압축 해제, 믹싱, 및 재압축을 실행해, 각 클라이언트에 보내는 오디오 데이터의 믹싱이 끝난 스트림을 생성한다. 각 클라이언트가, 이 믹싱 끝난 단독 스트림을 받아 재생한다.

믹싱 서버 세션내의 클라이언트에서는, 개개의 클라이언트에, 압축 및 송신해야 할 유출 오디오 스트림이 1 개로 압축 해제 및 재생해야 할 유입 오디오 스트림이 1 개 밖에 없기 때문에, 유출 대역폭, 유입 대역폭, 및 CPU 의 요건을 간단하게 예측할 수 있다.

믹싱 서버에 있어서의 대역폭과 CPU 의 요건은, 클라이언트보다 큰폭으로 높다. 보통, 믹싱 서버는, 1 대의 컴퓨터를 완전하게 점유 하는지, 또는 전용의 게임 서버와 컴퓨터를 공유한다.

믹싱 서버 음성 세션은,IDirectPlayVoiceClient::Create3DSoundBuffer 메소드를 사용한 음성 데이터의 3D 공간화를 지원 하지 않는다.

믹싱 서버 음성 세션은, 피어 투 피어 또는 클라이언트/서버 전송 세션을 사용해 실행할 수 있다.


음성 호스트의 이행

피어 투 피어의 Microsoft® DirectPlay® 네트워크 세션에서는, 네트워크 세션내의 1 개의 클라이언트가 호스트의 역할을 한다. 그 호스트가 세션을 빠지는지, 또는 어떠한 이유로써 응답하지 않게 되면(자), 세션내외의 클라이언트가 호스트로 선택된다.

DirectPlay 음성 세션에서는, 피어 투 피어 음성 세션으로 같은 호스트 이행 프로세스가 발생한다. 다만, 음성 호스트는 DirectPlay 네트워크 세션과 무관계하게 이행 한다. 음성 호스트가 이행 하는 것은, 서버가 IDirectPlayVoiceServer::StopSession 를 호출했을 때인가, 또는 음성 호스트가 응답하지 않게 되었을 경우이다. 음성 호스트가 이행 하면, 음성 세션내의 개개의 클라이언트에 DVMSG_HOSTMIGRATED 콜백이 닿는다. 새로운 호스트에게 건네지는 구조체에는 유효한 pdvServerInterface 포인터가 있어,IDirectPlayVoiceServer 의 호출을 시작 할 수 있게 되어 있다.


오디오 디바이스의 테스트

마이크로 폰의 설정은,IDirectPlayVoiceTest 인터페이스에 의해 지원 된다. 이 인터페이스에는,IDirectPlayVoiceTest::CheckAudioSetup 라고 하는 메소드가 1 개 있다. 이 메소드를 사용 하면, 테스트 위저드를 실행할 수 있다. 이 위저드는, 시스템으로 전이중 처리가 올바르게 지원 되고 있는 것으로, 마이크로 폰과 재생이 적절히 설정되어 있는 것을 확인한다. 위저드는, 선택한 재생 및 캡춰 디바이스의 편성 각각 다해 1 회만 실행할 필요가 있다. 어플리케이션에서는, 시작시에 구성을 매회 테스트해야 한다. 이것에는,dwFlags 파라미터를 DVFLAGS_QUERYONLY 로 설정해 IDirectPlayVoiceTest::CheckAudioSetup 를 호출한다. 이렇게 하면(자), 직전의 테스트 후에 디바이스 구성이 변화했는지 어떠했는지를 간단하게 조사할 수 있다. 디바이스가 테스트되어 있지 않으면,IDirectPlayVoiceTest::CheckAudioSetup 를 한번 더 실행해 위저드를 기동한다. 그렇게 하지 않으면IDirectPlayVoiceClient::Connect 가 DVERR_RUNSETUP 를 돌려주어, DirectPlay Voice 를 초기화할 수 없다.

유저의 사운드 카드로 전이중 능력이 없으면 음성 통신을 들을 수 밖에 할 수 없다. 음성 통신을 송신할 수 없는 것은, 보통, 게임에서는 오디오 카드가 재생 모드가 되어 있기 때문에 있다. 문제를 피하기 (위해)때문에, DirectX 8.0 에서는 재생과 캡춰를 동적으로 교체되지 않게 되어 있다. DirectX 의 오디오 설정 위저드를 사용 하면, 시스템의 전이중 능력에 관한 피드백을 얻을 수 있다.

현재에도, 실제로 사용되고 있는 시스템에 전니겹의 사운드 카드가 장비되어 있지 않은 경우는 적지 않기 때문에, 주의가 필요하다. 전니겹사운드 카드는 1998 년에 보급했지만, 당시의 오디오 카드 드라이버로 전니겹처리가 유효한 것은 적다. 1999 년에 새로운 시스템을 구입했을 경우나, 1999 년에 드라이버를 업그레이드 했을 경우에는, 전이중 능력이 있을 가능성이 높다.


음성 CODEC

Microsoft® DirectPlay® 로 전용에 제공되는 압축/압축 해제 (CODEC) 알고리즘은, 음성 품질의 CODEC 이다. 이러한 알고리즘은, 모두 8 kHz 의 16 비트 단청의 형식에 근거하고 있다. 써드파티의 CODEC 는 지원 되지 않는다. 또, DirectPlay Voice 와 함께 사용하는 독자적인 CODEC 를 생성 할 수 없다.

대역폭의 요건이 낮아지면(자), 음성 데이터의 오디오 품질도 저하하므로, 주의가 필요하다.

게임의 음성 세션내에서, CODEC 를 동적으로 바꿀 수 없다. 1 개의 음성 세션내에서는, 모든 유저가 같은 CODEC 를 사용할 필요가 있다. 다만, 적절한 유저 인터페이스를 생성 해, 거기서 현재의 세션을 파기해, 다른 CODEC 를 사용한 새로운 세션을 생성 하는 것에 의해, CODEC 를 강제적으로 바꾸는 일도 가능하다. 게임 어플리케이션의 유저가, 로비 채팅으로부터 게임에 점프 하고 있는 경우에는, 이 방법이 적합하다.

다른 모든 게임 설정 파라미터와 같게, 사용되는 CODEC 는 호스트가 제어해야 한다. 음성 세션 호스트와 게임 데이터의 호스트는, 동일하지 않아 좋다.

어떠한 형태의 네트워크 통신에서도 같지만, 음성 통신의 부하를 분석해, 게임 데이터와 음성 데이터의 통신에 필요한 대역폭을 확보할 수 있을지 어떨지를 확인하는 것이 중요하다. 음성에 의한 대역폭의 사용량은, 간단하게 분석할 수 있다. 동시에 발생 하면 생각되는 음성 스트림의 수를 예측해, CODEC 및 프로토콜 오버헤드에 필요한 대역폭의 합계를, 그 수에 곱셈한다.

CODEC 의 선택에서는, CPU 의 소비라고 하는 이제(벌써) 1 개의 요소도 고려할 필요가 있다. 보통, 대역폭의 낮은 CODEC 조차, 200 MHz Pentium 프로세서이면, 음성 스트림의 encode를 위해서(때문에) 리소스의 약 8 %, 디코드를 위해서(때문에) 게다가 4 % 가 필요하다. 네트워크의 대역폭과 같게, CPU 리소스의 소비도 스트림수에 응해 증가한다.


자동 게인 제어

Microsoft® DirectPlay® Voice 에는, 가능한 한 양호한 녹음 입력 레벨을 제공하기 위해서, 사운드 카드 위에의 하드웨어 입력 음량을 자동조정 하는 기능이 준비되어 있다. 자동 게인 제어를 유효하게 하려면 , 클라이언트 구성을 설정할 경우에,DVCLIENTCONFIG 구조체의 dwFlags 멤버에 DVCLIENTCONFIG_AUTORECORDVOLUME 플래그를 설정한다. 자동 게인 제어의 액티브/비액티브는, 음성 세션내에서 언제라도 바꿀 수가 있다.

게임 어플리케이션에서는, 가능한 한 자동 게인 제어를 사용하는 것. 자동 게인 제어를 사용 하면, 게임 리소스가 아주 조금 필요하게 되지만, 게임내에서 녹음 음량을 제어하지 않고 끝난다. 유저는, 일부러 레벨 설정을 하지 않고 , 고품질로 음성을 송수신 할 수가 있다.


전송 제어

Microsoft® DirectPlay® Voice 의 퍼포먼스 요건을 억제하려면 , 유저가 이야기하고 있을 때만, 음성 데이터를 송신하면 좋다. 음성 데이터의 전송을 제어하려면 , 2 개의 방법이 있다. 사용해야 할 방법은, 게임의 설계 요건에 따라서 다르다.

  • 음성을 액티브하게 한다
  • 푸쉬 투 토크


음성을 액티브하게 한다

음성을 액티브하게 하는 것에 의한 전송 제어에서는, 마이크 입력을 상시 분석하는 것으로, 유저가 이야기하고 있는지 어떤지를 판단한다. 음성을 액티브하게 하려면 2 개의 이점이 있다. 유저는 마이크로 폰에 말을 건네는 것만으로 좋다. 또, 음성 세션의 접속시에, DVCLIENTCONFIG 구조체의 dwFlags 파라미터를 DVCLIENTCONFIG_AUTOVOICEACTIVATED 로 설정하는 것만으로 끝나므로, 간단하게 코딩 할 수 있다.


푸쉬 투 토크

푸쉬 투 토크 전송 제어에서는, 음성 데이터를 송신하는 타이밍을, 유저가 적극적으로 선택한다. 이 전송 제어 방법을 사용 하면, 음성 이외의 데이터가 송신되는 위험이 없다. 이 방법은, 쌍방향 무선기로 [Talk] 버튼을 누르는 것과 같고, 어떤 종류의 게임 (대면형의 슈팅 게임등)에서는, 이 기능에 의해 리얼리티가 늘어난다. 이 방법에는, 이야기하는 타이밍을 유저가 적극적으로 선택해야 하기 때문에, 동시에 이야기하는 유저의 수가 줄어든다고 하는 이점도 있다. 유저 제어의 기능이 필요하기 때문에, 이 전송 제어는 음성을 액티브하게 하는 것으로써 설계와 개발에 시간이 걸린다.


캡춰 포커스

Microsoft® DirectPlay® Voice 를 지원 하는 로비 가능 게임 어플리케이션과 로비 어플리케이션을 생성 하려면 , 포커스를 캡춰 하면 말하는 개념이 불가결하다. 게임 어플리케이션이 포커스 캡춰를 적절히 이행 하고 있지 않는 경우, 로비 어플리케이션으로부터 기동되었을 때에, 음성 통신이 기능하지 않을 가능성이 있다.

이 점을 설명하기 위해(때문에), DirectPlay Voice 를 지원 하는 로비 어플리케이션으로, 2 명의 플레이어가 만나는 경우에 대해 생각한다. 2 명의 플레이어가 게임의 시작에 합의한다. 게임의 시작 후에, 양쪽 모두의 플레이어의 컴퓨터로 로비 어플리케이션이 포커스를 잃어, 게임 어플리케이션의 각 카피가 포커스를 취득한다. 게임 어플리케이션이 로비 어플리케이션으로부터 올바르게 포커스를 취득하지 않으면 게임 어플리케이션의 실행중도, 로비 어플리케이션에 포커스가 남을 가능성이 있다.

예를 들어, 게임 세션 실행중에, 1 번째의 플레이어 로비 어플리케이션이 포커스를 잃지 않고, 2 번째의 플레이어의 게임 세션이 로비 어플리케이션으로부터 포커스를 취득 하면, 이 상황이 발생한다. 2 번째의 플레이어로부터는, 1 번째의 플레이어의 음성 세션이 반이중에 돌아와 버린 것처럼 보인다. 2 번째의 플레이어에게는 1 번째의 플레이어의 목소리가 들리지만, 1 번째의 플레이어에게는 2 번째의 플레이어의 목소리가 들리지 않는다. 1 번째의 플레이어로부터는, 2 번째의 플레이어의 목소리가 들리지 않기 때문에, 음성 세션이 종료한 것처럼 보인다. 또, 1 번째의 플레이어에게는, 2 번째의 플레이어에게 자신의 목소리가 들리고 있는 것을 모른다.

이 동작은, 의도된 것이다. 같은 상황으로, 1 번째의 플레이어가 로비 어플리케이션으로부터 게임 세션을 시작 할 경우에, 문제가 발생해 세션을 시작 할 수 없는 경우에 대해 생각해 보자. 2 번째의 플레이어의 세션이 문제 없게 시작 했을 경우에는, 2 번째의 플레이어에게는 1 번째의 플레이어의 목소리가 들리기 (위해)때문에, 1 번째의 플레이어로부터 2 번째의 플레이어에게 게임 세션의 실패를 알릴 수가 있다. 그러면, 양자 모두 로비로 돌아가, 세션의 시작을 한번 더 시험할 수가 있다.

캡춰 포커스를 적정하게 처리하려면 , 게임 어플리케이션으로, DVSOUNDDEVICECONFIG 구조체의 hwndAppWindow 파라미터를, 게임의 실행중에 포커스를 가지는 윈도우 핸들로 설정할 필요가 있다. 이 결과, Connect 를 호출해 DirectPlay Voice 세션을 생성 할 수 있게 된다. 게임 어플리케이션에서는 다음에, DVMSGID_LOSTFOCUS 메세지와 DVMSGID_GAINFOCUS 메세지를 처리할 필요가 있다.

상세한 것에 대하여는,「포커스 캡춰의 이행」을 참조할것.


지터-버퍼

Microsoft® DirectPlay® Voice 에는, 지터-버퍼라고 하는 특징적인 기능이 있다. 지터-버퍼는, 최소한의 지연 시간에 최적인 음질을 제공하는, 유연한 버퍼링 알고리즘이다.

혼잡한 네트워크에서는, 음성 데이터 정보의 각 패킷이, 호스트 컴퓨터로 encode 되었을 때와 다른 순서로 닿는 일이 있다. 음성 데이터는 본래 연속한 것이므로, 패킷이 만일 늦어도 수신해 순서 자주(잘) 재생하기 위해서, 이러한 유입 패킷은, 당분간 큐에 넣어 둘 필요가 있다.

음성 통신의 품질을 최대로 하도록(듯이) 지터-버퍼를 설정 하면, 필요한 수의 음성 패킷이 닿아, 재생용의 큐에 들어가기까지, 시간이 걸린다. 이 때문에 음성이 늦어 음성 통신을 리얼타임에 들을 수가 없다. 대신에, 음성 데이터가 들리는 타이밍은, 녹음보다 수밀리 세컨드로부터 몇 초(정도)만큼 늦을 가능성이 있다. 플레이어가 서로 협력하는 게임에서는, 이 지연에 의해 문제가 발생한다. 게임내에서 이벤트가 발생했을 때에, 플레이어가 그러한 이벤트에 근거해 리얼타임에 정보를 교환할 수 없기 때문에이다. 예를 들어, 대면형의 슈팅 게임에서, 플레이어가 배후로부터 공격받을 것 같게 되어 동료가 경고하려고 해도, 공격받아 버릴 때까지 음성 통신이 들리지 않을 가능성이 있다.

지연 시간을 줄이도록(듯이) 지터-버퍼를 설정 하면, 큐를 가득하게 하기 위해서 필요한 패킷수가 적게 된다. 다만 이 경우, 연속 패킷의 일부가 시간에 맞지 않고, 그 결과, 재생시에 버퍼내에 음성 데이터가 갖추어지지 않을 가능성이 있다. 음성 통신이 들리는 타이밍은, 실제의 녹음과 거의 일치하고 있다. 다만 이 경우, 음성이 "팽이 조각" 으로 품질은 낮다.

DirectPlay 지터-버퍼에서는, 최소한의 지연 시간에 최고 품질의 음성 통신을 제공하는 방법을, 2 개의 방법에 의해 판단한다. 최초로, 네트워크 상태를 감시해, 지연이나 혼잡 상황을 판단한다. 다음에, 음성의 중단을 최소한으로 억제하면서 지연 시간을 가능한 한 단축하기 위해(때문에), 지터-버퍼 (또는 큐)의 사이즈를 동적으로 조정한다.

DirectPlay Voice 지터-버퍼는, 네트워크 상태에 맞추어 자동적으로 조정된다 (디폴트 동작의 경우). 알고리즘으로 네트워크 상태를 어느 정도 엄밀하게 추적할까는,DVCLIENTCONFIG 구조체의 dwBufferAggressiveness 멤버와dwBufferQuality 멤버를 사용해 수동으로 조정할 수 있다. "아그렛시브네스" 의 레벨을 올리는 만큼, 네트워크 상태가 엄밀하게 감시된다. 보통, 품질의 값이 높을 정도(수록), 음질은 오르지만 지연 시간은 길어진다. 또, 값이 작을 정도(수록), 지연 시간은 짧아지지만 음질은 저하한다.

아그렛시브네스의 레벨은, 게임 어플리케이션 실행중의 네트워크 상태에 맞추어 선택하는 것이 중요하다. 네트워크 퍼포먼스가 안정되어 있을 때 고레벨의 아그렛시브네스가 선택되고 있으면(자), 일시적인 문제가 오 기다려 해석되어 존재 하지 않을 지도 모르는 문제가 과잉에 보정될 가능성이 있기 때문에 있다.


working set에 대한 가이드 라인

전송 위상기하학, 음성 위상기하학, 전송 제어, 및 CODEC 의 최적인 구성은, 개발하는 게임의 종류나 장르, 1 개의 게임 세션에 참가하는 플레이어의 수, 및 타겟이 되는 접속의 종류에 근거하고 판단한다.

음성 세션에 참가하는 플레이어의 수는, 게임 세션에 실제로 참가하는 플레이어의 수로 동일하다고는 할 수 없기 때문에, 주의가 필요하다. 예를 들어, 대면형의 슈팅 게임을 개발하는 경우에는, 게임내에서 기한부의 파워업 아이템으로서 제공되는 무선기나 발신기로, 음성 통신을 표현할 수 있다. 무선기로서 표현 하면, 차내나 이동하지 않는 사령부내에 있는 무선기에, 통신을 제한할 수 있다고 하는 이점도 있다.

2 번째의 예로서 동시에 4 명이 플레이하는 온라인 브릿지 게임에 대해 생각하자. working set가 작기 때문에, 피어 투 피어 네트워크토폴로지상에서 피어 투 피어 음성 위상기하학을 전송 할 방법이 적합하다. 이 작은 working set에서는, 전송 제어의 모드로서 음성을 액티브하게 할 수도 있다. 피어 투 피어 음성 위상기하학은, 이행이 용이해, 플레이어가 서버의 역할을 하지 않아도 좋다. 4 명의 플레이어 전원이 Voxware SC6 CODEC 를 사용 하면, 최대 대역폭은, CODEC 의 프로토콜 오버헤드를 포함해 스피치 스트림 근처 4.2 Kbps 가 된다. 게다가 게임 데이터에 필요한 대역폭을 무시할 수 있는 정도로 작으면 하면, 말하는 사람 각각의 유출에 있어서의 최대의 대역폭 요건은, 나머지 3 명에게로의 스트림 3 개(살) (즉 12.6 Kbps)이 된다. 또, 유입에 있어서의 대역폭은, 어느 클라이언트에서도 0 (나머지 3 명이 입다물고 있을 때) ~ 12.6 Kbps (나머지 3 명 전원이 이야기하고 있을 때)가 된다. CPU 는, encode를 위해서(때문에) 8 %, 디코드를 위해서(때문에) 0 ~ 12 % 가 필요하다. 이 결과, 최악의 경우의 요건은 25.2 Kbps 가 된다. 따라서, 각 플레이어는 14,400 보 이상의 모뎀을 사용할 필요가 있다.

이제(벌써) 1 개의 예로서 32 명까지의 플레이어가 2 팀으로 나누어져 싸우는 팀 대전형 컴배트 게임에 대해 생각한다. 게임 데이터에는, 28,800 보의 모뎀이 필요한 것으로 한다. 이 예에서는, 플레이어수가 많기 때문에, 전송 서버 음성 위상기하학이 적합하다. 여기에서도, 플레이어 전원이 Voxware SC6 CODEC 를 사용 하면 하면, 최대 대역폭은 전술의 브릿지 게임과 같게 4.2 Kbps 가 된다. 이 예에서는, 이야기하고 있을 때 4.2 Kbps 가 유출해, 팀으로부터는 최대 12.6 Kbps 가 유입한다. CPU 는, Pentium 200 이면, encode를 위해서(때문에) 최대 8 %, 수신을 위해서(때문에) 최대 12 % 가 필요하다. 따라서, 게임 데이터를 위한 28.8 Kbps 로 커진 유입 대역폭 12.6 Kbps 를 위해서(때문에), 각 플레이어는 41,400 보 이상의 모뎀을 사용할 필요가 있다.

전송 서버 자체에 있어 최악의 케이스는, 32 명이 전원 동시에 이야기하는 경우이며, 이 때에는 134.4 Kbps 가 필요하게 된다. 서버의 CPU 사용량은 매우 한정되어 있다. 이것은, 서버가 스트림의 encode/디코드를 실시하지 않기 때문이다. 서버는 스트림을 리디렉트 하는 것에 지나지 않는다. 보통은, 16 명이 동시에 이야기하는 것으로서 67.2 Kbps 가 필요하게 된다.

믹싱 서버 음성 위상기하학을 선택하는 경우와 전송 서버 음성 위상기하학을 선택하는 경우의 차이를 설명하기 위해(때문에), 여기에서도 전술의 플레이어 32 사람에 따라 다른 대전형 컴배트 게임에 대해 생각한다. 믹싱 서버 음성 위상기하학을 사용 하면, 각 클라이언트에서는, 송신을 위해서(때문에) 4.2 Kbps, 수신을 위해서(때문에) 4.2 Kbps 가 필요하게 된다. 최악의 경우의 대역폭 요건은, 8.4 Kbps 에 내린다. 또, CPU 요건은, 200 MHz 로 동작하는 Pentium 프로세서의 12 % 이다. 이 결과, 클라이언트의 모뎀 요건도 33,600 보에 내린다.

서버측에서는, CPU 부하가 바뀐다. 서버는, 유입하는 스트림을 모두 디코드 및 재encode 해, 필요에 따라서 스트림의 믹싱도 실시한다. 스트림을 믹싱하기 위한 CPU 부하는, 비교적 낮기 때문에 무시한다. 최악의 케이스는, 동시에 32 의 스트림을 디코드/encode 하는 경우이다. 이 경우, 음성 서비스 단독으로도, 400 MHz 로 동작하는 Pentium II 프로세서가 최저한 필요하게 된다.


DirectPlay 의 사용법

Microsoft® DirectPlay® 문서의 이 섹션에서는, 멀티 플레이어 어플리케이션의 중요한 요소의 몇개인가를, DirectPlay API 를 사용해 이행 하는 방법을 설명한다.

  • DirectPlay 열거의 사용법
  • 플레이어 문맥값의 사용법
  • 로비 클라이언트의 이행
  • 로비 가능 어플리케이션의 이행
  • Netmon 를 사용한 DirectPlay 네트워크 트래픽의 감시
  • DirectPlay 와 DirectPlay Voice 에 있어서의 콜백 함수의 이행
  • 크리티컬 섹션 오브젝트를 사용한 DirectPlay 네트워킹 콜백의 이행
  • DirectPlay DPNSVR 어플리케이션의 사용법


DirectPlay 열거의 사용법

열거란, Microsoft® DirectPlay® 가 어플리케이션에 정보를 제공하는 방법의 1 개이다. 열거는, 몇개의 닮은 요소에 대해 데이터를 모으기 위해서(때문에) 사용한다. 예를 들어, 세션내의 개개의 플레이어에 관한 정보는, 열거를 사용해 취득할 수 있다. 열거를 실행하려면 , 어플리케이션이 DirectPlay 에 있는 종류의 정보를 조회해, DirectPlay 가 관련 요소 각각의 데이터 구조체를 돌려준다. 보통, 이 데이터는 구조체의 배열로서 돌려주어진다.

많은 어플리케이션에서는, 열거를 적어도 1 회 실행할 필요가 있어, 반복 실행해야 하는 경우도 적지 않다. 개개의 DirectPlay 인터페이스에서는, 각각 다른 열거 세트가 지원 된다. 따라서, 자세한 것은 어플리케이션에 따라서 다르다. 이하는, 이용 가능한 열거와 각종의 열거를 지원 하는 인터페이스의 일람이다.

  • 세션 호스트 (IDirectPlay8Peer ,IDirectPlay8Client )
  • 서비스 프로바이더 (IDirectPlay8Peer,IDirectPlay8Client,IDirectPlay8Server )
  • 플레이어 (IDirectPlay8Peer,IDirectPlay8Server)
  • 그룹 (IDirectPlay8Peer,IDirectPlay8Server)
  • 그룹 멤버 (IDirectPlay8Peer,IDirectPlay8Server)
  • 로컬 프로그램 (IDirectPlay8LobbyClient )

상세한 것에 대하여는, 「DirectPlay 열거의 이행」을 참조할것.


DirectPlay 열거의 이행

많은 Microsoft® DirectPlay® 열거는, 적절한 열거 메소드를 호출해, 돌려주어지는 데이터 배열을 조사한다, 라고 하는 표준 패턴에 따른다. 호스트의 열거는, 이 패턴에 따르지 않기 때문에 따로 설명한다.

데이터를 취득하는 메소드를 호출하기 전에, 돌려주어지는 데이터 블록을 저장 할 수 있는 메모리를 할당해 둘 필요가 있다. 다만, 사전에는 필요한 배열의 크기를 모르는 것이 많다. 생각되는 모든 배열을 저장 할 수 있는 블록을 할당하면 좋지만, 효율적인 방법은 아니다. 대신에, DirectPlay 에서는, 필요한 배열 사이즈를 조회하고 나서, 조회를 반복해 구조체 자체를 취득할 수 있다.

다음의 순서는, 피어 투 피어 게임의 그룹의 멤버를 열거하는 방법의 개요이다. 호스트의 열거를 제외해, 다른 종류의 열거도 모두 같은 일반 순서에 따라 행해진다. 열거는, 변화하는 정보의 snapshot를 취득하기 위해서 사용되는 것이 많기 때문에, 루프내에서 성공할 때까지 실행해야 한다.

  1. IDirectPlay8Peer::EnumGroupMembers 를 호출한다. 이 메소드는, 개개의 그룹 멤버의 ID 가 들어간 정수 배열을,prgdpnid 파라미터에 돌려준다. pcdpnid 파라미터는 배열의 요소수를 지시하기 위해서 사용한다. 적절한 값을 요구하려면 ,pcdpnid 파라미터를 0 으로 설정한다. prgdpnid 는 NULL 로 설정한다.
  2. 메소드로부터 복귀했을 때,pcdpnid 는 배열에 저장 되는 요소의 수를 가리킨다.
  3. pcdpnid 에 돌려주어진 값을 사용해 사용하는 배열을 할당해 그 배열을 prgdpnid 파라미터에 할당한다.
  4. pcdpnid 를 최초의 메소드 호출로 돌려주어진 값으로 설정한다.
  5. 한번 더 IDirectPlay8Peer::EnumGroupMembers 를 호출한다.
  6. 메소드로부터 재차 복귀하면(자), 반환값을 확인한다. 성공했을 경우, 메소드는 S_OK 를 돌려주어, 배열에 플레이어의 ID 가 저장 된다.
  7. 메소드가 재차 DPNERR_BUFFERTOOSMALL 를 돌려주는 경우는, 직전의 호출해 이후에 플레이어수가 증가한 것을 나타낸다. 스텝 3. 에 돌아와, 새로운 pcdpnid 값을 사용해 배열 사이즈를 늘린다. 메모리 누수가 일어나지 않게 주의 해야 한다.

메소드가 구조체의 배열을 돌려주는 경우도 있다. 그 경우, 순서는 같지만, 최초의 메소드 호출로 돌려주어지는 값은, 배열의 요소수가 아니고, 바이트수로 나타낸 배열 사이즈이다. 상세한 것에 대하여는, 각 메소드의 레퍼런스를 참조할것.

상세한 것에 대하여는, 「호스트의 열거」를 참조할것.


호스트의 열거

세션을 준비하는 1 개의 방법은, 세션 호스트가 이용 가능하게 된 것을 본인에게 통지시키는 것이다. 이런 종류의 세션을,"어느 요소를 전요소에 카피하는 세션" 이라고 말한다. 피어 또는 클라이언트는, 이용 가능한 호스트를 열거해, 1 개(살)을 선택해, 접속 요구를 송신해 그 게임에 참가하는 것으로써, 참가하는 게임을 찾을 수가 있다. 상세한 것에 대하여는, 「피어 투 피어 세션」또는 「클라이언트/서버 세션」을 참조할것.

다른 열거와 달리, 이용 가능한 호스트의 요구에 응답하기 위해서 필요한 정보는, 로컬 컴퓨터에 기억되어 있지 않다. 대신에, 클라이언트 또는 피어가 요구를 (예를 들어 로컬 서브 넷상에서) 전요소에 카피해, 이용 가능한 호스트로부터의 응답을 기다릴 필요가 있다. 한편, 호스트는, 이러한 요구를 기다리고 나서 적절히 응답할 필요가 있다. 이와 같이, 자신이 세션 멤버의 후보나 세션 호스트 등에 의해서, 순서는 미묘하게 다르다.

다음의 순서는, 피어 투 피어 세션에 이용 가능한 호스트의 열거 방법을 나타내고 있다. 클라이언트/서버 세션용의 순서도, 기본적으로 이것과 같다. IDirectPlay8Peer::EnumHosts 는, 열거를 시작 하는 메소드이다. 주요한 설정 파라미터는,pApplicationDesc,pdpaddrDeviceinfo, 및 pdpaddrHost 이다.

  1. 플레이하고 싶은 게임의 GUID 를 DPN_APPLICATION_DESC 구조체의 guidApplication 멤버에 할당해 그 구조체의 포인터를 pApplicationDesc 파라미터에 할당한다.
  2. 대상의 디바이스의 주소 오브젝트를 생성 해, 그 포인터를 pdpaddrDeviceinfo 에 할당한다. 이 오브젝트에는, 네트워크 접속의 확립에 필요한 정보가 저장 되고 있다.
  3. 이용 가능한 호스트를 특정의 컴퓨터에 조회하려면 , 그 컴퓨터에 대응하는 호스트 주소 오브젝트를 생성 해, 그 포인터를 pdpaddrHost 에 할당한다. 이 파라미터를 NULL 로 설정 하면, Microsoft® DirectPlay® 는,pdpaddrDeviceinfo 에 저장 된 정보에 근거해 주소 오브젝트를 생성 한다. 주소 오브젝트의 상세한 것에 대하여는, 「DirectPlay 아드레싱」을 참조할것. 보통, IP 또는 IPX 서비스 프로바이더를 사용하고 있는 경우는, 이 결과, 사용중의 로컬 서브 넷에 조회는 있는 요소를 전요소에 카피한다. DPNENUMHOSTS_OKTOQUERYFORADDRESSING 플래그를 설정 하면, 서비스 프로바이더가 유저에게 주소 정보를 요구하는 다이알로그 박스를 표시하는 일이 있다.
  4. IDirectPlay8Peer::EnumHosts 를 호출한다.
  5. 이 결과, 콜백 메세지 핸들러에, 응답하는 호스트 각각 붙어 1 개(살)씩 일련의 DPN_MSGID_ENUM_HOSTS_RESPONSE 메세지가 도착한다.
    1. 메세지 핸들러에 돌려주어진 정보를 조사해 세션을 선택해,IDirectPlay8Peer::Connect 를 호출해 그 세션에의 참가를 요구한다.

어느 요소를 전요소에 카피하는 세션의 호스트가 되려면 , 자신이 이용 가능한 일을 통지해, 조회 또는 접속 요구를 기다린다. 다음의 순서는 피어 투 피어 호스트에게 적용되지만, 클라이언트/서버 호스트용의 순서도 기본적으로 이것과 같다.

  1. IDirectPlay8Peer::SetPeerInfo 를 호출해, 플레이어용의 정적인 설정을 지정한다.
  2. DPN_APPLICATION_DESC 구조체에 값을 할당하는 것으로, 게임의 구성을 지정한다.
  3. IDirectPlay8Peer::Host 를 호출해, 자신이 호스트의 후보인 것을 통지한다. pdnAppDesc 파라미터를, 지난 번의 스텝에서 정의한 DPN_APPLICATION_DESC 구조체로 설정한다.
  4. 열거 요구를 기다린다. 열거 요구는, 콜백 메세지 핸들러에 송신되는 DPN_MSGID_ENUM_HOSTS_QUERY 메세지의 형태를 취한다. 열거 요구에 응답하려면 , DPN_APPLICATION_DESC 의 내용을 설정해, S_OK 를 돌려준다. 그 정보가 붙은 DPN_MSGID_ENUM_HOSTS_RESPONSE 메세지가, 피어에 닿는다.
  5. 피어가 세션에의 참가를 결정하면(자),DPN_MSGID_INDICATE_CONNECT 메세지가 도착한다.

게임을 준비 및 기동하는 방법의 상세한 것에 대하여는, 「피어 투 피어 세션」 및 「클라이언트/서버 세션」을 참조할것.


플레이어 문맥값의 사용법

많은 어플리케이션에서는, 개개의 플레이어에게 어떠한 데이터를 관련짓고 싶은 것이 있다. 한편, 플레이어에게 관련하는 메세지를 수신했을 때에는, 그 데이터에 재빠르게 액세스 하기 위해서 어떤 종류의 수단이 필요하게 된다. 플레이어 문맥값의 목적은, 플레이어 데이터에의 효율적인 액세스 수단을 제공하는 것에 있다.

주 플레이어 문맥값을 사용하는 것은,IDirectPlay8Peer 인터페이스 및 IDirectPlay8Server 인터페이스 뿐이다. IDirectPlay8Client 인터페이스에 플레이어 문맥값은 필요없다. 그것은, 클라이언트가, 다른 클라이언트와의 통신은 아니고, 서버와의 통신에만 이 인터페이스를 사용하기 때문이다.

  • 플레이어 문맥값의 정의
  • 플레이어 문맥 데이터의 관리


플레이어 문맥값의 정의

플레이어 문맥값을 사용하려면 , 사용중의 시스템에, 개개의 플레이어에게 대응하는 데이터 블록을, 보통은 구조체의 형태로 보관 유지할 필요가 있다. 플레이어 문맥값은, 보통, 각종 플레이어의 데이터 블록을 가리키는 포인터 배열의 인덱스이다. 플레이어로부터 메세지를 받아들였을 때, 테이블내의 플레이어 ID 를 검색 하면 말한 시간이 걸리는 처리를 하지 않고 끝난다. 플레이어 문맥값에 저장 된 인덱스를 사용 하면, 필요한 포인터를 재빠르게 취득할 수 있다.

플레이어 문맥값은, 게임에 플레이어가 추가된 것을 통지하는 DPN_MSGID_CREATE_PLAYER 메세지를 처리할 경우에 정의한다. 호스트도,DPN_MSGID_INDICATE_CONNECT 메세지를 처리할 경우에, 플레이어 문맥값을 정의하는 일이 있다. 다음의 DPN_MSGID_CREATE_PLAYER 메세지에는, 그 플레이어 문맥값이 설정된다. 호스트는, 그 메세지를 처리할 경우에, 플레이어 문맥값을 변경할 수 있다. 플레이어 문맥값을 생성 하려면 :

  • 플레이어의 데이터를 보관 유지하기 위한 구조체를 할당한다.
  • 플레이어 데이터 배열에 그 구조체 포인터를 추가한다.
  • 메세지의 DPNMSG_CREATE_PLAYER 구조체의 pvPlayerContext 멤버에, 그 포인터의 인덱스를 할당한다.

Microsoft® DirectPlay® 에서는, 데이터를 취득해 구조체에 대입할 방법이 지정되어 있지 않다. 그 문제는, 개개의 게임에서 독자적인 방법에 의해 처리하는 것.

주 플레이어 문맥값은,DPN_MSGID_CREATE_PLAYER 또는 DPN_MSGID_INDICATE_CONNECT 메세지 핸들러내에서만 정의할 수 있다. DPN_MSGID_CREATE_PLAYER 메세지 핸들러로부터 복귀 하면, 플레이어 문맥값이 설정된다. 그 플레이어에게 관련하는 이후의 각 메세지의 플레이어 문맥값은,DPN_MSGID_CREATE_PLAYER 메세지 핸들러가 설정한 값과 동일하다. 관련하는 데이터 구조체의 내용은 수정할 수 있지만, 플레이어 문맥값자체는 변경할 수 없다.


플레이어 문맥 데이터의 관리

플레이어 문맥값은 매우 간단하게 취급할 수 있지만, 주의하는 점이 몇개인가 있다.

플레이어 문맥값은, 메세지가 도착할 때마다 액세스 할 수 있다고 생각되는 유효한 메모리 주소를, 간단하게 취득하는 수단이다. 다만, 어플리케이션내가 다른 부분으로부터, 데이터의 액세스를 동시에 실시하지 않게 주의할 필요가 있다. Microsoft® DirectPlay® 에서는, 특정의 플레이어에게 관련하는 메세지가 순서대로 화 되고 있다. 이 때문에, 같은 플레이어로부터의 메세지를 2 개 동시에 취급하는 상황은 발생하지 않는다. 데이터 구조체는, 콜백 메세지 핸들러로부터 액세스 하는 한, 안전하게 액세스 할 수 있다. 다만, 많은 어플리케이션에서는, 메세지 핸들러 이외로부터 플레이어 데이터에 액세스 할 필요가 있다.

콜백 메세지 핸들러 이외로부터 데이터에 액세스 하는 어플리케이션에서는, 구조체를 잠그는 어떤 종류의 글로벌인 메카니즘을 준비해, 동시 액세스를 피하지 않으면 안 된다. 개발의 초기에는 그러한 락 메카니즘이 필요없다고 해도, 필요하게 되는 경우를 상정해 처음부터 짜넣어 두는 것이 좋다. 플레이어 문맥값이 배열의 인덱스인 경우는, 그 배열을 안전하게 읽어내, 갱신하게도 주의하지 않으면 안 된다.

플레이어의 데이터 구조체의 할당을 잘못해 빨리 해제하지 않는 것. 플레이어가 게임을 빠질 때는, 보통, 플레이어의 데이터 구조체의 할당을 해제해, 관련하는 메모리를 해방할 필요가 있다. 다만,DPN_MSGID_DESTROY_PLAYER 메세지를 받아들이자 마자 구조체의 할당을 해방하는 경우에는 주의가 필요하다. 콜백 메세지 핸들러 이외로부터 구조체에 액세스 하는 어플리케이션에서는, 메세지가 도착했을 때에, 그 데이터가 아직 사용되고 있을 가능성이 있다. 메세지가 도착했다고 해, 곧바로 구조체의 할당을 해제 하면, 어플리케이션외의 부분이 실패하는 일이 있다.

잘못해 빨리 구조체의 할당을 해제하는 것을 피하려면 , 어플리케이션 레벨의 락 메카니즘을 준비할 뿐만 아니라, 어떤 종류의 참조 카운트를 이행 하면이야 있고. 구조체를 생성 하면 와, 및 구조체를 사용할 때마다, 참조 카운트를 인크리먼트(increment) 한다. DPN_MSGID_DESTROY_PLAYER 메세지 핸들러를 포함해 구조체를 다 사용할 때마다 , 참조 카운트를 감소 한다. 참조 카운트가 0 이 아닌 한, 구조체는 어플리케이션의 어딘가로부터 액세스 되고 있다. 참조 카운트가 0 에 돌아올 때까지, 구조체의 할당을 해제하지 않는 것.


로비 클라이언트의 이행

로비 클라이언트와는, 유저의 컴퓨터에 상주하는 어플리케이션이다. 주된 역할은, 유저의 컴퓨터에 있는 게임 어플리케이션과 리모트 컴퓨터에 있는 로비 서버를 링크하는 것에 있다. 다만, 로비 클라이언트는, 스탠드얼론 어플리케이션이라고 해도 기능한다. 예를 들어, 특정의 LAN 서브 넷의 유저에 의한 게임 세션은, 이것들을 사용해 준비할 수 있다.

로비 클라이언트는, 보통, 이하의 작업을 하는 3 개의 주요 컴퍼넌트로부터 구성된다.

  • 외부 (로비 서버 또는 다른 로비 클라이언트)와의 통신.
  • 유저와의 통신. 주로 그래피컬 유저 인터페이스 (GUI)를 사용한다.
  • Microsoft® DirectPlay® 와의 통신.

DirectPlay 에서는, 전의 2 항목의 이행 방법이 지정되어 있지 않다. 로비 클라이언트 벤더가, 개개의 제품에 적절한 방법으로 이행 해야 한다. DirectPlay 는, DirectPlay 와 통신해, 유저 로비 가능한 게임 어플리케이션과 DirectPlay 를 통해서 통신하기 위해서, 로비 클라이언트를 사용할 수 있는 표준 API 를 제공한다.

여기에서는, 로비 클라이언트의 이행에 관한 이하의 중요한 항목에 대해 설명한다.

  • 로비 클라이언트의 초기화
  • 로비 대상 어플리케이션의 기동
  • 로비 클라이언트 메세지 핸들러의 이행
  • 로비 대상 어플리케이션과의 통신
  • 로비 클라이언트의 종료

간단한 로비 클라이언트의 완전한 이행예에 대해서는, 샘플 어플리케이션 LobbyClient 를 참조할것.


로비 클라이언트의 초기화

로비 클라이언트는, 로비 서버가 기동하는지, 유저가 직접 기동한다. 로비 클라이언트는, 기동해도, 초기화될 때까지 어플리케이션을 기동할 수 없다. 초기화에는, 이하의 작업이 필요하게 된다.

  • CoCreateInstance 를 호출해, 로비 클라이언트 오브젝트 (CLSID_DirectPlay8LobbyClient)를 생성 한다. riid 파라미터를 사용해,IDirectPlay8LobbyClient 인터페이스 (IID_IDirectPlay8LobbyClient)를 요구한다.
  • 로비 클라이언트의 IDirectPlay8LobbyClient::Initialize 메소드를 호출한다. 로비 클라이언트의 콜백 메세지 핸들러에의 포인터를, 메소드에 건네준다.
  • IDirectPlay8LobbyClient::EnumLocalPrograms 메소드를 사용해, 유저의 시스템에 있는 로비 가능한 어플리케이션을 열거한다.

전의 2 개의 스텝에서, 로비 클라이언트 오브젝트를 생성 해, 그 오브젝트와 로비 클라이언트의 사이에 통신 링크를 설정한다. 마지막 스텝에서, 유저의 시스템으로 이용할 수 있는 로비 가능한 어플리케이션을 판단한다. 이 정보는, 선택된 어플리케이션을 기동하기 위해서 필요하다.

다음의 샘플 코드는, 로컬 어플리케이션의 열거 방법을 나타내고 있다. 이것은, SDK 의 샘플 LobbyClient 에 있는 EnumRegisteredApplications 함수를 간략화한 것이다. 알기 쉽게하기 위해(때문에), 에러 처리 및 다이알로그 박스 관련의 코드가 삭제되고 있다. 완전한 코드에 대해서는, SDK 의 샘플 LobbyClient 를 참조할것.

HRESULT EnumRegisteredApplications()
{
    HRESULT hr;
    DWORD   dwSize     = 0;
    DWORD   dwPrograms = 0;
    DWORD   iProgram;
    BYTE*   pData   = NULL;

//g_pLobbyClient 는, IDirectPlay8LobbyClient 인터페이스에의 포인터.
//처음은 NULL 데이터 버퍼. 필요한 버퍼 사이즈는
//dwSize. 그리고 돌려주어진다.
  hr = g_pLobbyClient->EnumLocalPrograms( NULL, pData, &dwSize, &dwPrograms, 0 );

  if( dwSize == 0 )
  {
//등록이 끝난 어플리케이션은 없다.
  }
//데이터 버퍼를 적절한 사이즈로 설정한다.
  pData = new BYTE[dwSize];
  hr = g_pLobbyClient->EnumLocalPrograms( NULL, pData, &dwSize, &dwPrograms, 0 )

//돌려주어진 데이터를 적절한 구조 체형에 캐스트 한다.
  DPL_APPLICATION_INFO* pAppInfo = (DPL_APPLICATION_INFO*) pData;

//등록이 끝난 어플리케이션의 이름을 열거한다.
  for( iProgram=0; iProgram<dwPrograms; iProgram++ )
  {
    TCHAR strAppName[MAX_PATH];
    DXUtil_ConvertWideStringToGeneric( strAppName, pAppInfo->pwszApplicationName );

  }
  SAFE_DELETE_ARRAY( pData );
  return S_OK;
}

등록이 끝난 어플리케이션의 어플리케이션 GUID 는, 어플리케이션의 기동에 필요해서, 보존해야 한다.

로비 클라이언트의 설계에 따라서는, 이하의 작업의 몇개인가를 실행할 필요가 있다.

  • 로비 서버와의 링크 확립 등, Microsoft® DirectPlay® 와 관계가 없는 초기화를 실행한다.
  • DirectPlay 피어 오브젝트 (CLSID_DirectPlay8Peer) 또는 DirectPlay 클라이언트 오브젝트 (CLSID_DirectPlay8Client)를 생성 한다.
  • 피어 오브젝트 또는 클라이언트 오브젝트의 열거 메소드를 사용해, 이용 가능한 서비스 프로바이더, 어댑터등을 열거한다.


로비 대상 어플리케이션의 기동

유저가 어플리케이션을 선택해, 유저의 시스템에 그 어플리케이션이 등록되어 있는 것을 로비 클라이언트가 확인 하면, 어플리케이션을 기동할 수 있게 된다. 이것에는,IDirectPlay8LobbyClient::ConnectApplication 를 호출한다. 최초의 파라미터는, 어플리케이션의 기동에 필요한 각종의 정보 (이하를 포함한다)가 저장 된 DPL_CONNECT_INFO 구조체이다.

  • 어플리케이션을 식별하는 GUID.
  • 접속의 설정 (유저의 Microsoft® DirectPlay® 주소를 포함한다). DirectPlay 주소의 상세한 것에 대하여는, 「DirectPlay 아드레싱」을 참조할것.
  • 어플리케이션이 호스트가 될지 어떨지.

IDirectPlay8LobbyClient::ConnectApplication 메소드는, 이후의 모든 통신으로 어플리케이션의 식별로 사용하는 어플리케이션 핸들을 돌려준다. 어플리케이션이 기동해, 접속의 확립이 성공하면(자), 메세지 핸들러에 DPL_MESSAGE_CONNECT 메세지가 도착한다.

주 IDirectPlay8LobbyClient::ConnectApplication 메소드가 성공 코드를 돌려주어 접속을 확인하기 전에, 메세지 핸들러에 DPL_MESSAGE_CONNECT 가 닿는 일이 있다. 메세지 핸들러는, 메소드로부터 복귀하고 있지 않아도, 메세지를 처리할 수 없으면 안 된다.


로비 클라이언트 메세지 핸들러의 이행

메세지 핸들러는, 로비 클라이언트 오브젝트가 로비 클라이언트와의 통신에 사용하는 콜백 함수이다. 로비 클라이언트 메세지 핸들러에는, 이하의 정보를 건네주는 3 개의 파라미터가 있다.

  • 메세지 타입을 나타내는 메세지 ID.
  • 메세지 데이터 블록에의 포인터. 이 파라미터는, 각 메세지가 사용하는 구조체에 캐스트 할 필요가 있다.
  • 어플리케이션으로 정의된 유저 문맥의 데이터 블록 (생략 가능)에의 포인터.

유저 문맥값은,IDirectPlay8LobbyClient::Initialize 를 호출하면나무에 로비 클라이언트가 정의한다. 유저 문맥값은, 다른 오브젝트로부터 송신된 메세지를 구별하는 목적 등에 사용할 수 있다. 메세지 핸들러 함수의 완전한 기술에 대해서는, 「PFNDPNMESSAGEHANDLER」를 참조할것.

메세지 핸들러는, 로비 클라이언트 고유의 이하의 5 개의 메세지를 처리할 수 없으면 안 된다.

  • DPL_MESSAGE_CONNECT
  • DPL_MESSAGE_CONNECTION_SETTINGS
  • DPL_MESSAGE_DISCONNECT
  • DPL_MESSAGE_RECEIVE
  • DPL_MESSAGE_SESSION_STATUS

이러한 메세지의 대부분은, 게임 상태가 변화했을 때, 또는 로비 클라이언트가 정보를 요구했을 때에, 로비 클라이언트 오브젝트가 생성한다. 다만,DPL_MESSAGE_RECEIVE 는 예외이다. 이 메세지는, 게임 어플리케이션으로부터 로비 클라이언트에 데이터를 직접 건네주기 위해서(때문에) 사용된다.

주 Microsoft® DirectPlay® 메세지 핸들러는, multi-thread 환경에서 적절히 동작하도록(듯이) 쓰여져 있을 필요가 있다. 그처럼 쓰여지지 않으면 어플리케이션이 정상적으로 기능하지 않을 가능성이 있다.

DPL_MSGID_CONNECT

이 메세지는, 로비 가능한 어플리케이션의 기동 후에, 로비 클라이언트가 송신한다. 이 메세지는, 어플리케이션의 접속이 성공한 것을 나타낸다. 관련하는 DPL_MESSAGE_CONNECT 구조체에는, 이하를 포함한 각종의 정보가 보관 유지된다.

  • 접속 ID. 로비 클라이언트가,IDirectPlay8LobbyClient::Send 으로 어플리케이션에 데이터를 송신하는지, 또는 IDirectPlay8LobbyClient::ReleaseApplication 로 접속을 해방할 필요가 있을 때는, 이 ID 를 사용한다.
  • 로비 접속 데이터.
  • 접속 문맥값 (생략 가능).

DPL_MSGID_CONNECTION_SETTINGS

이 메세지는, 관련지을 수 있었던 로비 가능한 어플리케이션으로부터, 세션의 접속을 수정하기 위해서 IDirectPlay8LobbiedApplication::SetConnectionSettings 메소드가 불려 갈 때마다, DirectPlay 가 송신한다. 관련지을 수 있었던 DPL_MESSAGE_CONNECTION_SETTINGS 구조체에는, 갱신 끝난 접속 정보가 저장 된다.

DPL_MSGID_DISCONNECT

이 메세지는, 로비 가능한 어플리케이션이 IDirectPlay8LobbiedApplication::Close 를 호출해 세션을 빠질 때, 송신된다. 로비 클라이언트 어플리케이션에서는, 접속을 그 리스트로부터 삭제해, 어플리케이션에 관련지을 수 있었던 데이터를 모두 해방해야 한다.

DPL_MSGID_RECEIVE

이 메세지를 사용 하면, 어플리케이션으로부터 로비 클라이언트에 데이터를 건네줄 수가 있다. DirectPlay 는, 어플리케이션으로부터 로비 클라이언트에,DPL_MESSAGE_RECEIVE 구조체를 사용해 데이터 블록을 건네준다. 이 데이터의 처리는, 로비 클라이언트가 실시하지 않으면 안 된다.

DPL_MSGID_SESSION_STATUS

이 메세지는, 세션 상태에 이하의 6 개의 변화중 한쪽이 발생할 때마다, DirectPlay 가 송신한다.

  • 세션이 접속되었다.
  • 세션을 접속할 수 없다.
  • 세션이 절단 되었다.
  • 세션이 종료했다.
  • 세션 호스트가 이행 했다.
  • 이 컴퓨터가 세션 호스트가 되었다.

상태 변화의 종류는, 관련지을 수 있었던 DPL_MESSAGE_SESSION_STATUS 구조체에 있는 dwStatus 필드의 값에 의해 나타난다.

상세한 것에 대하여는, 「로비 클라이언트 메세지 핸들러의 샘플」을 참조할것.


로비 클라이언트 메세지 핸들러의 샘플

다음의 코드는, SDK 의 샘플 LobbyClient 에 있는 메세지 핸들러를 간략화한 것이다. 알기 쉽게하기 위해(때문에), 에러 처리 코드가 삭제되고 있다. 완전한 코드에 대해서는, 상기 샘플을 참조할것.

HRESULT WINAPI DirectPlayLobbyMessageHandler( PVOID pvUserContext,
                                              DWORD dwMessageId,
                                              PVOID pMsgBuffer )
{
  switch( dwMessageId )
  {
    case DPL_MSGID_DISCONNECT:
    {
      PDPL_MESSAGE_DISCONNECT pDisconnectMsg;
      pDisconnectMsg = (PDPL_MESSAGE_DISCONNECT) pMsgBuffer;

      // 어플리케이션에 관련지을 수 있었던 데이터를 모두 해방해,
      // 리스트로부터 접속을 삭제한다.
      break;
    }
    case DPL_MSGID_RECEIVE:
    {
      PDPL_MESSAGE_RECEIVE pReceiveMsg;
      pReceiveMsg = (PDPL_MESSAGE_RECEIVE) pMsgBuffer;

      // 로비 어플리케이션이 데이터를 송신했다. 데이터를 처리해,
      // 적절히 응답한다.
      break;
    }
    case DPL_MSGID_SESSION_STATUS:
    {
      PDPL_MESSAGE_SESSION_STATUS pStatusMsg;
      pStatusMsg = (PDPL_MESSAGE_SESSION_STATUS) pMsgBuffer;

      switch( pStatusMsg->dwStatus )
      {
        case DPLSESSION_CONNECTED://세션이 접속되었다.
          break;
        case DPLSESSION_COULDNOTCONNECT://세션을 접속할 수 없다.
          break;
        case DPLSESSION_DISCONNECTED://세션이 절단 되었다.
          break;
        case DPLSESSION_TERMINATED://세션이 종료했다.
          break;
        case DPLSESSION_HOSTMIGRATED://호스트가 이행 했다.
          break;
        case DPLSESSION_HOSTMIGRATEDHERE://호스트가 여기로 이행했다.
          break;
      }
      case DPL_MSGID_CONNECTION_SETTINGS:
      {
        PDPL_MESSAGE_CONNECTION_SETTINGS pConnectionStatusMsg;
        pConnectionStatusMsg = (PDPL_MESSAGE_CONNECTION_SETTINGS) pMsgBuffer;
        // 어플리케이션이 접속의 설정을 변경했다.
        break;
      }
  }
  return S_OK;
}


로비 대상 어플리케이션과의 통신

로비 클라이언트와 관련하는 어플리케이션의 교환의 대부분은, 간접적으로 행해진다. 로비 클라이언트가 어플리케이션에 영향을 주는 어떠한 처리를 실행 (또는 반대로 어플리케이션이 로비 클라이언트에 영향을 주는 어떠한 처리를 실행) 하면, Microsoft® DirectPlay® 이 적절한 메세지를 송신한다. 예를 들어, 로비 클라이언트가 접속의 설정을 변경 하면, DirectPlay 가 어플리케이션에 통지해, 새로운 설정 내용을 제공한다. 다만,IDirectPlay8LobbyClient::Send 메소드를 사용하면, 로비 클라이언트로부터 어플리케이션에 메세지를 직접 송신할 수가 있다. DirectPlay 는 어플리케이션에 데이터를 그대로 건네준다. 그 데이터의 처리는, 어플리케이션이 실시하지 않으면 안 된다.

로비 대상 어플리케이션도, 로비 클라이언트에 데이터를 직접 송신할 수가 있다. 데이터는, 로비 클라이언트의 메세지 핸들러에, DPL_MSGID_RECEIVE 메세지로 건네받는다. DirectPlay 는 로비 클라이언트에 데이터를 그대로 건네준다. 이 데이터의 처리는, 로비 클라이언트가 실시하지 않으면 안 된다.


로비 클라이언트의 종료

세션을 종료할 준비를 할 수 있으면(자),IDirectPlay8LobbyClient::ReleaseApplication 를 호출해 어플리케이션을 절단 한다. 어플리케이션에,DPL_MSGID_DISCONNECT 메세지가 도착한다.

어플리케이션을 해방하면(자), 필요에 따라서 클린 업을 실행해,IDirectPlay8LobbyClient::Close 를 호출해 세션을 닫는다. 다음에,IDirectPlay8LobbyClient::Release 를 호출해, 로비 클라이언트 오브젝트를 해방해야 한다.


로비 가능 어플리케이션의 이행

로비 가능 어플리케이션은, 로비 클라이언트와 올바르게 연동하도록(듯이) 설계될 필요가 있다. 로비 클라이언트는 임의의 어플리케이션을 기동할 수 있지만, Microsoft® DirectPlay® 로부터의 메세지, 및 로비 클라이언트로부터의 메세지를 받아들이는 것은,"로비 기동" 어플리케이션 뿐이다. 로비 기동되는 어플리케이션은, 적절히 등록되어 있어, DirectPlay 로비 대상 어플리케이션 오브젝트를 사용해, DirectPlay 및 로비 클라이언트와 통신할 수 없으면 안 된다.

여기에서는, 로비 가능 어플리케이션의 이행 방법에 대해 설명한다.

  • 로비 가능 어플리케이션의 등록
  • 로비 기동의 취급
  • 로비 대상 어플리케이션 콜백 메세지 핸들러의 이행
  • 로비 클라이언트와의 통신
  • 로비 대상 어플리케이션의 종료


로비 가능 어플리케이션의 등록

로비 가능 어플리케이션을 로비 기동하려면 , 사전에 등록할 필요가 있다. 이 등록은, 1 회만 실행될 필요가 있어, 보통은 어플리케이션의 셋업 순서에 포함된다. 어플리케이션을 로비 가능 어플리케이션으로서 등록하기 위해(때문에), 레지스트리를 직접 수정하려고 해서는 안 된다. 대신에, 이하의 처리를 실행한다.

  • CoCreateInstance 를 호출해, 로비 대상 어플리케이션 오브젝트 (CLSID_DirectPlay8LobbiedApplication)를 생성 한다. riid 파라미터를 IID_IDirectPlay8LobbiedApplication 로 설정해,IDirectPlay8LobbiedApplication 인터페이스를 요구한다.
  • IDirectPlay8LobbiedApplication::RegisterProgram 를 호출한다. 이 메소드는, 정보를 받아, 적절한 레지스트리의 키와 값을 생성 한다.

IDirectPlay8LobbiedApplication::RegisterProgram 에는, 이하를 포함한 각종의 정보를 제공할 필요가 있다.

  • 어플리케이션의 식별로 사용하는 GUID.
  • 어플리케이션의 프렌들리명.
  • 어플리케이션의 실행 파일의 장소와 이름.
  • "란체" 어플리케이션 (생략 가능)의 장소와 이름.
  • 기동시에 실행 파일에 건네주지 않으면 안 되는 커멘드 라인 인수.

Microsoft® DirectPlay® 는, 게임 어플리케이션은 아니고, 란체아프리케이션을 기동한다. 다음에, 란체아프리케이션이 게임을 기동한다. 란체아프리케이션은, 예를 들어 불법 복사 대책으로서 사용할 수 있다.

프로그램의 등록을 해제하는데는,IDirectPlay8LobbiedApplication::UnregisterProgram 를 호출한다. 이 메소드는,IDirectPlay8LobbiedApplication::RegisterProgram 로 생성 된 레지스트리 엔트리를 삭제한다.


로비 기동의 취급

로비 가능 어플리케이션이 기동되었을 때에 우선 실행해야 하는 것은, Microsoft® DirectPlay® 로비 대상 어플리케이션 오브젝트의 생성 및 초기화이다. 이것에는, 이하의 처리를 실행한다.

  • CoCreateInstance 를 호출해, 로비 대상 어플리케이션 오브젝트 (CLSID_DirectPlay8LobbiedApplication)를 생성 한다. riid 파라미터를 IID_IDirectPlay8LobbiedApplication 로 설정해,IDirectPlay8LobbiedApplication 인터페이스를 요구한다.
  • IDirectPlay8LobbiedApplication::Initialize 를 호출해, 로비 대상 어플리케이션 오브젝트를 초기화한다. 로비 대상 어플리케이션의 콜백 메세지 핸들러에의 포인터를, 오브젝트에 건네준다.

다음에, 어플리케이션이 로비 기동되었는지 어떠했는지를 판단한다. 로비 기동되고 있는 경우는, 세션을 효율적으로 관리하기 위해서, 어플리케이션으로 DirectPlay 와의 통신 채널을 설정할 필요가 있다. 어플리케이션이 로비 기동되었는지 어떠했는지를 판단하려면 , 이하의 처리를 실행한다.

  • IDirectPlay8LobbiedApplication::Initialize 메소드로부터 복귀했을 때에,pdpnhConnection 파라미터를 조사한다. 이 파라미터가 유효한 접속 핸들로 설정되어 있는 경우, 게임은 로비 기동되고 있다.
  • 메세지 핸들러를 통해서 받은 DPL_MSGID_CONNECT 메세지를 조사한다. 이 메세지에는, 로비 클라이언트에 메세지를 송신할 경우에 사용하는 ID 를 포함한, 각종의 정보가 부속되어 있다.

주 IDirectPlay8LobbiedApplication::Initialize 메소드로부터 복귀하기 전에, 메세지 핸들러에 DPL_MSGID_CONNECT 메세지가 도착하는 일이 있다. 메세지 핸들러는, 이 메세지를 적절히 처리할 준비가 되어 있지 않으면 안 된다.

어플리케이션이 로비 기동되어 있지 않은 경우는,IDirectPlay8LobbiedApplication::SetAppAvailable 를 호출하면, 로비 클라이언트로부터 어플리케이션에 접속 가능한 것을 나타낼 수가 있다. 이 메소드는, 보통, 유저가 어플리케이션을 기동했을 때에 불려 간다. 다만, 유저가 1 개의 세션을 닫았지만, 어플리케이션이 아직 동작하고 있어, 다른 세션으로 이용 가능한 경우에도, 이 메소드를 사용할 수가 있다. 어느 쪽의 경우도, 로비 클라이언트가 어플리케이션을 세션에 접속 하면, 메세지 핸들러에 DPL_MSGID_CONNECT 메세지가 도착한다.

다음의 샘플 코드는, 로비 대상 어플리케이션의 초기화 방법, 및 어플리케이션이 로비 기동되고 있는지 어떤지를 판단하는 방법을 나타내고 있다. 이것은, SDK 의 SimplePeer 어플리케이션으로 사용되는 InitDirectPlay 함수를 간략화한 것이다. 완전한 코드에 대해서는, 상기 샘플 어플리케이션을 참조할것. 알기 쉽게하기 위해(때문에), 주로 에러 처리 코드가 삭제되고 있다. g_bWasLobbyLaunched 는 글로벌 변수이며, 어플리케이션이 로비 기동되고 있는 경우에 TRUE 로 설정된다.

HRESULT InitDirectPlay()
{
  DPNHANDLE hLobbyLaunchedConnection = NULL;
  HRESULT hr;

  // IDirectPlay8LobbiedApplication 를 생성 한다.
  hr = CoCreateInstance( CLSID_DirectPlay8LobbiedApplication, NULL,
                         CLSCTX_INPROC_SERVER,
                         IID_IDirectPlay8LobbiedApplication,
                         (LPVOID*) &g_pLobbiedApp );

  // IDirectPlay8LobbiedApplication 를 초기화한다.
  hr = g_pLobbiedApp->Initialize( NULL,
                                  DirectPlayLobbyMessageHandler,
                                  &hLobbyLaunchedConnection,
                                  0 );
  //유효한 접속 핸들이 없는가 조사한다. NULL 가 아닌 경우
  //어플리케이션은 로비 기동되고 있다.
  g_bWasLobbyLaunched = ( hLobbyLaunchedConnection ! = NULL );

  return S_OK;
}


로비 대상 어플리케이션 콜백 메세지 핸들러의 이행

메세지 핸들러는, 로비 대상 어플리케이션 오브젝트가 로비 대상 어플리케이션과의 통신에 사용하는 콜백 함수이다. 로비 대상 어플리케이션 메세지 핸들러에는, 이하의 정보를 건네주는 3 개의 파라미터가 있다.

  • 메세지 타입을 나타내는 메세지 ID.
  • 메세지 데이터 블록에의 포인터. 이 파라미터는, 각 메세지가 사용하는 구조체에 캐스트 할 필요가 있다.
  • 어플리케이션으로 정의된 유저 문맥의 데이터 블록 (생략 가능)에의 포인터.

유저 문맥값은,IDirectPlay8LobbyClient::Initialize 를 호출하면나무에 로비 클라이언트가 정의한다. 유저 문맥값은, 다른 오브젝트로부터 송신된 메세지를 구별하는 목적 등에 사용할 수 있다. 메세지 핸들러 함수의 완전한 기술에 대해서는, 「PFNDPNMESSAGEHANDLER」를 참조할것.

메세지 핸들러는, 로비 대상 어플리케이션 고유의 이하의 4 개의 메세지를 처리할 수 없으면 안 된다.

  • DPL_MESSAGE_CONNECT
  • DPL_MESSAGE_CONNECTION_SETTINGS
  • DPL_MESSAGE_DISCONNECT
  • DPL_MESSAGE_RECEIVE

이러한 메세지의 대부분은, 접속이 변화했을 때, 또는 로비 대상 어플리케이션이 접속 정보를 요구했을 때에, 로비 대상 어플리케이션 오브젝트가 생성한다. 다만,DPL_MESSAGE_RECEIVE 는 예외이다. 이 메세지는, 로비 클라이언트로부터 게임 어플리케이션에 데이터를 직접 건네주기 위해서(때문에) 사용된다.

주 Microsoft® DirectPlay® 메세지 핸들러는, multi-thread 환경에서 적절히 동작하도록(듯이) 쓰여져 있을 필요가 있다. 그처럼 쓰여지지 않으면 어플리케이션이 정상적으로 기능하지 않을 가능성이 있다.

DPL_MSGID_CONNECT

이 메세지는, 로비 클라이언트가 어플리케이션을 세션에 접속하기 위해서 IDirectPlay8LobbyClient::ConnectApplication 를 호출했을 때에, 로비 대상 어플리케이션 오브젝트가 송신한다. 관련지을 수 있었던 DPL_MESSAGE_CONNECT 구조체에는, 이하의 정보가 포함된다.

  • 접속 ID. 어플리케이션이,IDirectPlay8LobbiedApplication::Send 로 로비 클라이언트에 데이터를 송신하는지, 또는 IDirectPlay8LobbiedApplication::UpdateStatus 로 세션 상태를 갱신할 필요가 있을 때는, 이 ID 를 사용한다.
  • 로비 접속 데이터.
  • 접속 문맥값 (생략 가능).

DPL_MSGID_CONNECTION_SETTINGS

DirectPlay 는, 관련지을 수 있었던 로비 클라이언트로부터, 세션의 접속을 수정하기 위해서 IDirectPlay8LobbyClient::SetConnectionSettings 메소드가 불려 갈 때마다, 이 메세지를 송신한다. 관련지을 수 있었던 DPL_MESSAGE_CONNECTION_SETTINGS 구조체에는, 갱신 끝난 접속 정보가 저장 된다.

DPL_MSGID_DISCONNECT

이 메세지는, 로비 클라이언트가 IDirectPlay8LobbyClient::ReleaseApplication 를 호출해 어플리케이션을 세션으로부터 절단 할 경우에, 송신된다. 어플리케이션에서는, 접속을 그 리스트로부터 삭제해, 세션에 관련지을 수 있었던 데이터를 모두 해방해야 한다.

DPL_MSGID_RECEIVE

이 메세지를 사용 하면, 로비 클라이언트로부터 어플리케이션에 데이터를 건네줄 수가 있다. DirectPlay 는, 로비 클라이언트로부터 어플리케이션에,DPL_MESSAGE_RECEIVE 구조체를 사용해 데이터 블록을 건네준다. 이 데이터의 처리는, 어플리케이션이 실시하지 않으면 안 된다.

상세한 것에 대하여는, 「로비 대상 어플리케이션 메세지 핸들러의 샘플」을 참조할것.


로비 대상 어플리케이션 메세지 핸들러의 샘플

다음의 코드는, SDK 의 샘플 SimplePeer 에 있는 메세지 핸들러를 간략화한 것이다. 알기 쉽게하기 위해(때문에), 에러 처리 코드가 삭제되고 있다. 완전한 코드에 대해서는, 상기 샘플을 참조할것.

HRESULT WINAPI DirectPlayLobbyMessageHandler( PVOID pvUserContext,
                                              DWORD dwMessageId,
                                              PVOID pMsgBuffer )
{
  switch( dwMessageId )
  {
    case DPL_MSGID_CONNECT:
    {
      PDPL_MESSAGE_CONNECT pConnectMsg;
      pConnectMsg = (PDPL_MESSAGE_CONNECT) pMsgBuffer;

      // 접속되었다. 세션을 시작 한다.
      break;
    }
    case DPL_MSGID_DISCONNECT:
    {
      PDPL_MESSAGE_DISCONNECT pDisconnectMsg;
      pDisconnectMsg = (PDPL_MESSAGE_DISCONNECT) pMsgBuffer;

      // 절단 되었다. 로비 클라이언트에 관련지을 수 있었다
      // 데이터를 해방한다.
      break;
    }
    case DPL_MSGID_RECEIVE:
    {
      PDPL_MESSAGE_RECEIVE pReceiveMsg;
      pReceiveMsg = (PDPL_MESSAGE_RECEIVE) pMsgBuffer;

      // 로비 클라이언트가 데이터를 송신했다. 데이터를 처리해,
      // 적절히 응답한다.
      break;
    }

    case DPL_MSGID_CONNECTION_SETTINGS:
    {
      PDPL_MESSAGE_CONNECTION_SETTINGS pConnectionStatusMsg;
      pConnectionStatusMsg = (PDPL_MESSAGE_CONNECTION_SETTINGS) pMsgBuffer;

      // 로비 클라이언트가 접속의 설정을 변경했다.
      break;
    }
  }
  return S_OK;
}


로비 클라이언트와의 통신

로비 대상 어플리케이션과 관련하는 로비 클라이언트의 교환의 대부분은, 간접적으로 행해진다. 어플리케이션이 로비 클라이언트에 영향을 주는 어떠한 처리를 실행 (또는 반대로 로비 클라이언트가 어플리케이션에 영향을 주는 어떠한 처리를 실행) 하면, Microsoft® DirectPlay® 가 적절한 메세지를 송신한다. 예를 들어, 어플리케이션이 접속의 설정을 변경 하면, DirectPlay 가 로비 클라이언트에 통지해, 새로운 설정 내용을 제공한다. 다만, 로비 클라이언트에 정보를 직접 제공하기 위해(때문에), 이하의 2 개의 메소드도 준비되어 있다. IDirectPlay8LobbiedApplication::UpdateStatus 및 IDirectPlay8LobbiedApplication::Send .

게임 상태에 이하의 변화중 한쪽이 발생했을 때에는, 로비 클라이언트에 통지할 필요가 있다.

  • 세션이 접속되었다.
  • 세션을 접속할 수 없다.
  • 세션이 절단 되었다.
  • 세션이 종료했다.
  • 세션 호스트가 이행 했다.
  • 이 컴퓨터가 세션 호스트가 되었다.

로비 클라이언트에 이러한 상태 변화의 어느쪽이든을 통지하려면 ,IDirectPlayLobbiedApplication::UpdateStatus 를 호출해,dwStatus 파라미터를 적절한 값으로 설정한다. 상태의 변화를 알리는 DPL_MSGID_SESSION_STATUS 메세지가, 로비 클라이언트에 닿는다.

IDirectPlay8LobbiedApplication::Send 메소드를 사용 하면, 어플리케이션으로부터 로비 클라이언트에 메세지를 직접 송신할 수가 있다. DirectPlay 는 로비 클라이언트에 데이터를 그대로 건네준다. 그 데이터의 처리는, 로비 클라이언트가 실시하지 않으면 안 된다.

로비 클라이언트도, 어플리케이션에 데이터를 직접 송신할 수가 있다. 데이터는, 로비 클라이언트의 메세지 핸들러에, DPL_MSGID_RECEIVE 메세지로 건네받는다. DirectPlay 는 어플리케이션에 데이터를 그대로 건네준다. 로비 클라이언트는, 이 데이터를 처리해야 한다.


로비 대상 어플리케이션의 종료

세션을 닫으려면 ,IDirectPlay8LobbiedApplication::Close 를 호출한다. 절단을 알리는 DPL_MSGID_DISCONNECT 메세지가, 로비 클라이언트에 닿는다. 어플리케이션을 계속해 실행해, 다른 세션에 접속하려면 ,IDirectPlay8LobbiedApplication::SetAppAvailable 를 호출해, 어플리케이션이 이용 가능한 것을 나타낸다. 그 이외의 경우는,IDirectPlay8LobbiedApplication::Release 를 호출해 로비 대상 어플리케이션 오브젝트를 해방해, 어플리케이션을 종료한다.


Netmon 를 사용한 DirectPlay 네트워크 트래픽의 감시

게임의 개발중 (특히 버그를 해석하고 있을 때)에는, Microsoft® DirectPlay® 의 네트워크 트래픽을 감시 하면 도움이 되는 일이 있다. 네트워크 모니터 (Netmon)는, 네트워크 트래픽을 분석하기 위한 표준 유틸리티이다. DirectPlay 메시징의 4 개의 컴퍼넌트 (서비스 프로바이더 계층, 트랜스폴트 계층, 세션 계층, 및 음성 계층)를 분석하기 (위해)때문에, DirectPlay 에는 Netmon 를 사용한 일련의 퍼서가 준비되어 있다.

  • Netmon 와 DirectPlay 의 연동
  • DirectPlay 향해라 Netmon 의 구성
  • DirectPlay 네트워크 트래픽의 캡춰
  • DirectPlay 로 Netmon 를 사용하기 위한 힌트


Netmon 와 DirectPlay 의 연동

Microsoft® DirectPlay® 의 프로토콜 스택에는, 3 개의 기본 계층이 있다.

  • 음성 계층과 세션 계층은, 스택의 최상정도 레벨을 공유한다. 보통의 메시징은 세션 계층을 대로, 음성 관련의 메시징은 음성 계층을 통과한다.
  • 트랜스폴트 계층은, 스택의 중위에 있다. 음성과 세션의 트래픽은, 어느쪽이나 이 계층을 통과한다. 메세지의 분할과 복구성이나, 소실한 패킷의 재전송등의 작업은, 이 계층이 담당한다.
  • 서비스 프로바이더 계층은, 스택의 맨 밑에 있다. 모든 메시징은 이 계층으로 처리된다. 네트워크와의 통신은, 이 계층이 담당한다. 예를 들어, TCP/IP 네트워킹의 경우, 서비스 프로바이더는 Winsock API 를 사용해 네트워크 탁과 통신을 실시한다. Netmon 로 해석할 수 있는 네트워크 트래픽은, IP 또는 IPX 서비스 프로바이더상을 지나는 것에 한정되어 있다.

DirectPlay 퍼서를 인스톨 하면, Netmon 를 사용해, 이것들 4 개의 계층의 어느쪽이든을 통과하는 네트워크 트래픽을 분석할 수 있다. 서비스 프로바이더 퍼서를 선택 하면, DirectPlay 의 전트래픽을 표시할 수 있다. 또, 상위 레벨의 퍼서의 어느쪽이든을 선택하면, 흥미가 없는 트래픽을 제외할 수가 있다.

트랜스폴트 계층 퍼서를 사용 하면, 음성과 세션의 전트래픽이 표시되어 접속을 위한 핸드쉐이크라고 하는 하위 레벨의 트래픽은 제외된다. 트랜스폴트 계층에서는, MTU (Maximum Transfer Unit)보다 긴 메세지가 1 개 이상의 단편에 분해되므로, 주의 해야 한다.

세션 계층 퍼서와 음성 계층 퍼서를 사용 하면, 세션 관련의 트래픽과 음성 관련의 트래픽을 따로 따로 분석할 수 있다. 이러한 퍼서는, 어느쪽이나 분할을 검지해, 유저에게 알리게 되어 있지만, 분할한 패킷을 분석할 수 없다.


DirectPlay 향해라 Netmon 의 구성

Windows 2000 Server 시스템을 사용하고 있는 경우, Netmon 는 이미 인스톨 되고 있다. Windows 2000 Professional 의 경우는, SMS (Systems Management Server)를 구입할 필요가 있다. Netmon 의 기본적인 사용법에 대해서는, Netmon 의 문서를 참조할것. Microsoft® DirectPlay® 의 트래픽을 감시하기 위해서 Netmon 를 구성하려면 다음의 순서를 실행한다.

  1. 적절한 폴더에 Dp8parser.dll 를 카피한다. Netmon 의 루트 폴더는, 보통, \Winnt\System32 폴더에 인스톨 된다. SMS 가 인스톨 되고 있는 경우, 루트 폴더명은 NetMonFull 가 된다. Windows 2000 Server 의 경우, 루트 폴더명은 NetMon 가 된다. 퍼서 DLL 를 ...\NetMonFull\Parsers 또는 ...\NetMon\parsers 에 카피한다. 카피처는, 사용하고 있는 Netmon 의 버젼에 의존한다.
  2. Netmon 를 기동한다.
  3. [캡춰] - [네트워크...] - [로컬 컴퓨터] 로, 캡춰 하는 어댑터를 설정한다. 이 때,[다이얼 업 접속] 프로퍼티가 오프로 설정된 어댑터를 선택하도록(듯이) 주의한다.

이것으로, 트래픽의 캡춰를 시작 할 수 있다.


DirectPlay 네트워크 트래픽의 캡춰

캡춰 처리를 시작 하려면 ,[Microsoft 네트워크 모니터] 툴바의 [캡춰의 시작] 버튼을 클릭해, 캡춰 표시를 연다. 처음은, 대상의 어댑터를 통과하는 트래픽이 모두 표시된다. 이 생의 트래픽 스트림은, 흥미가 있는 일정한 패킷인 만큼 좁힐 수가 있다. Microsoft® DirectPlay® 의 퍼서를 인스톨 하면, 기본적으로, DirectPlay 지향의 4 개의 필터가 Netmon 에 추가된다. 이러한 필터를 사용 하면, 캡춰 표시로부터 DirectPlay 이외의 모든 트래픽을 제외할 수 있다.

필터를 선택하려면 다음의 순서를 실행한다.

  1. [Microsoft 네트워크 모니터] 툴바의 [캡춰 필터의 편집] 을 클릭한다.
  2. [Protocol == Any] 를 더블 클릭 한다.
  3. [모두 무효] 를 클릭한다.
  4. [무효인 프로토콜] 의 [DPLAYSESSION],[DPLAYSP],[DPLAYTRANSPORT], 및 [DPLAYVOICE] 를 더블 클릭 한다.

[OK] 를 2 회 클릭해 캡춰 표시하러 돌아온다. 이것으로, DirectPlay 트래픽의 표시를 시작 할 수 있다.

캡춰 표시가 아니고, 캡춰 처리 자체에 필터를 적용할 수도 있다. 이렇게 하면(자), 예를 들어, 지정한 포토로부터 지정한 포토에의 IP 패킷만을 캡춰 할 수 있다. 상세한 것에 대하여는, Netmon 의 문서를 참조할것.


DirectPlay 로 Netmon 를 사용하기 위한 힌트

여기에서는, Microsoft® DirectPlay® 로 Netmon 를 사용하기 위한 힌트를 몇개인가 소개한다.

  • 디폴트에서는, 최신의 트래픽 1 MB 만이 캡춰 되게 되어 있다. 이 값은, 10 ~ 20 MB 정도로 더할 필요가 있을지도 모른다.
  • 하드 드라이브에의 스트림은 행해지지 않기 때문에, 확인할 수 있는 트래픽은 현재 캡춰 버퍼내에 있는 내용에 한정된다. 캡춰 끝난 트래픽을 하드 드라이브에 스트림 하려면 , 독자적인 캡춰 처리를 이행 할 필요가 있다. 상세한 것에 대하여는, MSDN 를 참조할것.
  • 디폴트에서는, DirectPlay 의 퍼서는,[2302,2400]U{6073} 포토/소켓 범위를 사용해, IP 및 IPX 패킷을 필터 링 하게 되어 있다. 표준 이외의 포토/소켓 범위를 사용하고 있는 경우에는, 유저 정의의 포토/소켓값을 퍼서에게 인식시킬 수가 있다. 이것에는, \HKEY_CURRENT_USER\Software\Microsoft\DirectX\DirectPlay\Parsers 레지스트리 키에, MinUserPort 와 MaxUserPort 의 2 개의 DWORD 값을 추가한다. 이 결과, 포토/소켓 범위가 [2302,2400]U{6073}U[MinUserPort, MaxUserPort] 에 확장된다.
  • DirectPlay 프로토콜과 RTP 프로토콜은, 어느쪽이나 UDP 프로토콜의 상위 계층이기 (위해)때문에, 양자의 퍼서가 경합 할 가능성이 있다. 따라서, DirectPlay 트래픽을 분석할 때는 RTP 퍼서를 무효로 해, RTP 트래픽을 분석할 때는 DirectPlay 퍼서를 무효로 하지 않으면 안 된다.


DirectPlay 와 DirectPlay Voice 에 있어서의 콜백 함수의 이행

Microsoft® DirectPlay® 와 DirectPlay Voice 에서는, DirectPlay 가 발행하는 이벤트를 처리하기 위해(때문에), 몇개의 콜백 함수를 독자적으로 이행 할 필요가 있다. DirectPlay 는 multi-thread화 되고 있으므로, 동시에 복수의 이벤트를 발행할 가능성이 있다. 따라서, DirectPlay 의 콜백으로 올바르게 신뢰성의 높은 데이터 액세스를 실시하려면 , 동기를 multi-thread화하는 수단을 이행 해야 한다. 이것을, 콜백을 "재입가능" 또는 "thread 세이프" 로 한다, 라고 말한다.

콜백 함수의 구조

콜백의 구조는, 표준적인 Microsoft Windows Win32 API 프로그래밍 가이드 라인에 따른다.

HRESULT WINAPI Callback(
  PVOID pvUserContext,
  DWORD dwMessageType,
  PVOID pMessage );

pvUserContext 는, DirectPlay 에 콜백 함수를 등록할 경우에 지정하는 문맥값이다. 콜백의 등록시에 DirectPlay 에 이 값을 건네주면(자), DirectPlay 로부터 콜백이 기동될 때, 이 문맥값이 돌려주어진다.

dwMessageType is 는, DirectPlay 로부터 콜백에게 건네지는 ID 값의 언젠가이다.

pMessage 에는, DirectPlay 로부터 건네받은 메세지가 저장 된다.

콜백의 등록

Microsoft DirectPlay 의 네트워킹 콜백 함수는,PFNDPNMESSAGEHANDLER 형이다. 콜백 함수의 주소는,IDirectPlay8Peer::Initialize ,IDirectPlay8Client::Initialize , 또는 IDirectPlay8Server::Initialize 를 사용해 등록한다. 사용하는 인터페이스는, 네트워킹 세션의 종류에 의존한다. DirectPlay 음성 콜백 함수를 등록하고 있는 경우, 콜백의 주소는,IDirectPlayVoiceClient::Initialize 또는 IDirectPlayVoiceServer::Initialize 를 사용해 등록한다. 사용하는 인터페이스는, 생성 하는 DirectPlay 음성 세션의 종류에 의존한다.

다음의 코드는, IDirectPlay8Peer 인터페이스를 사용해 콜백 함수를 등록하는 방법을 나타내고 있다.

HRESULT WINAPI Callback(PVOID, DWORD, PVOID);
IDirectPlay8Peer* pdp8Peer;

// 서버 인터페이스를 취득한다.
hr = CoCreateInstance( CLSID_DirectPlay8Peer, ...)
...

// 콜백을 등록한다.
hr = pdp8Peer->Initialize(NULL, Callback, 0);


크리티컬 섹션 오브젝트를 사용한 DirectPlay 네트워킹 콜백의 이행

Microsoft® DirectPlay® 의 네트워킹 및 음성 콜백은, multi-thread화 되고 있다. 따라서, DirectPlay 의 콜백으로 올바르게 신뢰성의 높은 데이터 액세스를 실시하려면 , 동기를 multi-thread화하는 수단을 이행 해야 한다.

현시점에서는, multi-thread 콜백의 데이터의 동기를 잡기 위해서(때문에), 3 개의 수단이 있다.

  • 뮤텍스 오브젝트
  • semaphore 오브젝트
  • 크리티컬 섹션 오브젝트

크리티컬 섹션 오브젝트를 사용해 동기를 잡는 방법은, DirectX 8.0 SDK 에 부속되는 DirectPlay 의 음성 관련 샘플에 나타나고 있다. 크리티컬 섹션 오브젝트의 사용법에 대해서는, 이하의 주제도 참고가 된다. 뮤텍스 오브젝트 또는 semaphore 오브젝트를 이행 하는 경우, 이러한 주제는, SDK (Microsoft Platform Software Development Kit)에도, 많은 레퍼런스 북에도 기재되어 있으므로, 참조할것. 이러한 동기 수단은, 만일 어떠한 문제가 일어났을 경우, 복잡하고 어려운 디버그 작업이 필요하게 된다. 이 때문에, 어느쪽이든을 이행 하려면 , 개개의 분야에 관한 상당히 진행된 지식이 없으면 안 된다.

CRITICAL_SECTION g_csPlayerContext;
InitializeCriticalSection(&g_csPlayerContext);

다음에, DirectPlay 메세지 콜백 핸들러를 이행 한다.

HRESULT WINAPI DirectPlayMessageHandler( PVOID pvUserContext,
                                         DWORD dwMessageId,
                                         PVOID pMsgBuffer )
{
    switch( dwMessageId )
    {
        case DPN_MSGID_CREATE_PLAYER:
        {
             EnterCriticalSection( &g_csPlayerContext );
             //콜백이 락 되었다.
             //플레이어 데이터의 처리를 한다.
             LeaveCriticalSection( &g_csPlayerContext );
        }
    }
}

마지막으로, 어플리케이션의 종료시에,DeleteCriticalSection 함수를 호출해, 크리티컬 섹션 오브젝트에 관련지을 수 있었던 메모리를 해방할 필요가 있다.

DeleteCriticalSection( &g_csPlayerContext );


DirectPlay DPNSVR 어플리케이션의 사용법

Microsoft Windows 에서는, 복수 프로세스간에 단독의 IP 포토 또는 IPX 포토를 공유할 수가 없다. 통신 호스트로서 기능하는 어플리케이션에서는, 각각 다른 포토를 사용해야 한다. 이 제약에 의해, 특히 실행중의 게임을 열거 하면 말한 작업을 실행할 경우에, 이하와 같은 몇개의 문제가 발생한다.

  • 포토의 경합을 피한다. 다른 어플리케이션과 경합 하지 않는 포토를 선택할 필요가 있다.
  • 복수의 통신 호스트를 단독 시스템상에서 관리한다. 호스트는, 인스턴스 마다 다른 포토를 사용해야 한다. 한편, 클라이언트 어플리케이션은, 특정의 호스트가 사용하고 있는 포토를 판단하지 않으면 안 된다.
  • 이미 사용중의 포토를 피한다. 바람직한 포토가 사용중의 경우는, 다른 포토를 사용할 수 없으면 안 된다.

이러한 문제에, DPNSVR 어플리케이션은, 열거 요구의 전송 서비스로서 기능하는 것에 의해 대처한다. 어플리케이션은, 호스트를 시작 하면 와, 동작중의 포토를 DPNSVR 에 알린다. DPNSVR 는, 기존의 포토로 대기해, 시스템 위에의 모든 Microsoft® DirectPlay® 호스트에게, 모든 열거 요구를 전송 한다. 열거 요구에의 응답에는, 호스트가 접속된 실제의 포토가 포함된다. DPNSVR 에 의해, 개발자는 이하의 이점을 얻을 수 있다.

  • 특정의 시스템으로 실행되고 있는 게임을 모두 열거하는 범용 열거 루틴을 생성 할 수 있다.
  • DirectPlay 를 사용해 호스트의 포토를 선택할 수 있다. 클라이언트 어플리케이션이, DPNSVR 의 서비스를 사용해 기존의 포토로 실행중의 게임을 열거 하면, 호스트가 접속된 실제의 포토를 포함한 응답을 얻을 수 있다.
  • 어플리케이션이 요구한 포토를 취득할 수 없는 경우를, 고려할 필요가 없다.
  • 시스템상에 있는 것 외의 어플리케이션과의 경합에 대해, 걱정할 필요가 없다.

많은 어플리케이션에서는 DPNSVR 의 서비스를 사용하지만, DPNSVR 를 무효로 하지 않으면 안 되는 경우도 있다. 그 예를 2 개 가리킨다.

  • 사용해야 할 포토를 알고 있지만, 컴퓨터상에서 그 어플리케이션의 인스턴스가 1 개 밖에 실행되지 않는 경우.
  • 플레이어가 세션을 열거하는 능력을 제한하고 싶은 경우. DPNSVR 를 무효로 하면, 호스트가 접속된 포토를 알고 있는 플레이어만이, 호스트를 열거할 수 있다.

상세한 것에 대하여는,「DPNSVR 의 사용법」을 참조할것.


DPNSVR 의 사용법

대상의 서비스 프로바이더가 DPNSVR 를 지원 하고 있을지 어떨지를 판단하려면 ,IDirectPlay8Peer ,IDirectPlay8Client , 또는 IDirectPlay8Server 로 지원 되는 GetSPCaps 메소드를 호출한다. 서비스 프로바이더가 DPNSVR 를 지원 하고 있으면, 돌려주어지는 DPN_SP_CAPS 구조체의 dwFlags 멤버에 DPNSPCAPS_SUPPORTSDPNSRV 플래그가 설정된다. 현시점에서는, IP 및 IPX 서비스 프로바이더만이 DPNSVR 를 지원 한다.

DPNSVR 는 디폴트로 선택되고 있으므로, 특별한 조작을 하지 않고 사용할 수 있다. 열거 요구를 호스트에게 전송 하고 싶지 않은 경우는,DPN_APPLICATION_DESC 구조체의 dwFlags 멤버에 DPNSESSION_NODPNSVR 플래그를 설정해, DPNSVR 를 명시적으로 무효로 할 필요가 있다.

주 DPNSESSION_NODPNSVR 플래그가 설정되어 있어도, 동작중의 포토를 알고 있으면, 어플리케이션은 언제라도 호스트를 열거할 수가 있다.


포커스 캡춰의 이행

Microsoft® DirectPlay® Voice 를 지원 하는 로비 가능 게임 어플리케이션과 로비 어플리케이션을 생성 하려면 , 포커스를 캡춰 하면 말하는 개념이 불가결하다. 게임 어플리케이션이 포커스 캡춰를 적절히 이행 하고 있지 않는 경우, 로비 어플리케이션으로부터 기동했을 때에, 음성 통신이 기능하지 않을 가능성이 있다.

DirectPlay 음성 세션의 생성전에, 이하와 같이 몇개의 초기화 작업이 완료하고 있지 않으면 안 된다.

// DirectPlay 음성 클라이언트의 인터페이스를 생성 한다.
hr = CoCreateInstance( CLSID_DirectPlayVoiceClient,
                       NULL,
                       CLSCTX_INPROC_SERVER,
                       IID_IDirectPlayVoiceClient,
                       (LPVOID*) &m_pVoiceClient )

// hwndAppWindow 멤버를, 게임 어플리케이션 실행중에
// 포커스가 있는 윈도우로 설정한다.
DVSOUNDDEVICECONFIG dvSoundDeviceConfig;

dvSoundDeviceConfig.hwndAppWindow = hWnd;
// dwFlags 를 DVSOUNDCONFIG_STRICTFOCUS 로 설정한다. 이렇게 하면(자),
// foreground의 어플리케이션 윈도우만이 포커스를 취득한다.
dvSoundDeviceConfig.dwFlags = DVSOUNDCONFIG_STRICTFOCUS;

// 음성 세션에 접속한다.
hr = m_pVoiceClient->Connect( &dvSoundDeviceConfig,
                              pdvClientConfig,
                              DVFLAGS_SYNC )

어플리케이션이 세션에 접속되면(자), DirectPlay 음성 콜백에 메세지가 도착한다. 포커스 캡춰를 적절히 이행 하기 위해서는,DVMSGID_GAINFOCUS 와 DVMSGID_LOSTFOCUS 의 2 개의 메세지를 처리할 필요가 있다.

HRESULT CALLBACK DirectPlayVoiceClientMessageHandler(
                     LPVOID lpvUserContext,
                     DWORD dwMessageType,
                     LPVOID lpMessage )
{
    switch( dwMessageType )
    {
     case DVMSGID_GAINFOCUS:
        // 게임 어플리케이션이 시스템내의 포커스를 취득했다.
            break;
        case DVMSGID_LOSTFOCUS:
        // 게임 어플리케이션이 시스템내의 포커스를 잃었다.
            break;
    }
  ...
}

녹음이 뮤트 되면(자), 포커스가 없어진다. DirectPlay Voice 로부터 콜백에 DVMSGID_LOSTFOCUS 메세지가 도착한다. 녹음의 뮤트가 해제되면(자), 포커스가 돌아온다. 다만, DVSOUNDCONFIG_STRICTFOCUS 를 사용하고 있는 어플리케이션에서는, 어플리케이션 윈도우가 foreground인 경우에게만, 포커스가 돌아온다.

DVCLIENTCONFIG dvClientConfig;
dvClientConfig.dwFlags = DVCLIENTCONFIG_RECORDMUTE;

// 녹음을 뮤트 한다. DVMSGID_LOSTFOCUS 가 DirectPlay 음성 콜백 함수
// 에 송신된다.
m_pVoiceClient->SetClientConfig(dvClientConfig);


DirectPlay C++ 샘플

이하의 샘플 어플리케이션은, C++ 프로그램 언어용 Microsoft® DirectPlay® 어플리케이션 프로그래밍 인터페이스의 사용법 및 능력을 나타내는 것이다. 상세한 것에 대하여는, 개개의 샘플 폴더의 Readme.txt 파일을 참조할것. 샘플 폴더는, 모두 SDK 루트 디렉토리 (보통은 C:\mssdk)아래에 있다.

  • AddressOverride
  • ChatPeer
  • DataRelay
  • LobbyClient
  • Maze
  • SimpleClientServer
  • SimplePeer
  • StagedPeer
  • VoiceClientServer
  • VoiceConnect
  • VoiceGroup
  • VoicePosition


AddressOverride

AddressOverride 는, 네트워크 위에의별 세션의 호스트가 되는지, 또는 그러한 세션에 접속하기 위해서, Microsoft® DirectPlay® 의 아드레싱을 무효로 하는 방법을 나타낸다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\AddressOverride


ChatPeer

샘플 ChatPeer 는,SimplePeer 를 닮은 형태를 하고 있다. 플레이어가 세션의 호스트가 되는지, 또는 세션에 접속 하면, 캐릭터 라인의 수수에 의해 플레이어 끼리가 채팅할 수 있게 된다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\ChatPeer


DataRelay

샘플 DataRelay 는,SimplePeer 와 닮아 있다. 다만, 다이알로그 박스의 UI 로 지정된 옵션이 붙은 데이터 패킷을, 단독의 상대 (또는 전원)에게 송신하게 되어 있다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\DataRelay


LobbyClient

LobbyClient 는, 간단한 로비 클라이언트 어플리케이션이다. 로컬 시스템 위에의 등록이 끝난 Microsoft® DirectPlay® 어플리케이션이, 모두 표시된다. 유저는, 선택한 서비스 프로바이더를 사용해, 그러한 어플리케이션을 1 개 이상 기동할 수 있다. 기동하는 로비 대상 어플리케이션에는, 게임에 참가하는지, 또는 게임의 호스트가 되는 것을 지시할 수 있다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\LobbyClient


Maze

샘플 Maze 는, Microsoft® DirectPlay® 클라이언트/서버 어플리케이션이다. 클라이언트는, 콘솔 베이스의 클라이언트와 D3D 클라이언트의 2 종류가 준비되어 있다. D3D 클라이언트는, 스크린 세이버로서 실행할 수도 있다. 거기에는, Mazeclient.exe 을 자신의 \winnt\system32\ 폴더에 카피해, 이름을 Mazeclient.scr 로 변경한다. 이렇게 하면(자), 화면의 컨트롤 패널 어플리케이션으로부터 검출 가능한 스크린 세이버가 된다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\Maze


SimpleClientServer

샘플 SimpleClientServer 는, 간단한 클라이언트/서버 어플리케이션이다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\SimpleClientServer


SimplePeer

샘플 SimplePeer 는, 간단한 피어 투 피어 어플리케이션의 이행 방법을 나타낸다. 세션에 참가하는지, 또는 세션을 생성 하면, 곧바로 게임이 시작 한다. 진행중의 세션에는, 다른 플레이어도 수시 참가할 수 있다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\SimplePeer


StagedPeer

샘플 StagedPeer 는, 세션에의 참가 또는 세션의 생성에 필요한 접속 설정을 유저에게 재촉하는 2 개의 다이알로그 박스와 플레이어를 접속한다. 유저가 세션에 접속 하면, 같은 세션에 접속된 전플레이어가 채팅할 수 있는 멀티 플레이어 스테이지가 표시된다. 전원의 준비가 갖추어져, 호스트가 시작을 결정하면(자), 플레이어가 새로운 게임을 시작 할 수 있다. 호스트는, 플레이어를 거부하거나 플레이어의 슬롯을 닫거나 할 수가 있다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\StagedPeer


VoiceClientServer

샘플 VoiceClientServer 는, Microsoft® DirectPlay® Voice 베이스의 간단한 클라이언트/서버 어플리케이션이다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\VoiceClientServer


VoiceConnect

샘플 VoiceConnect 는, 다른 플레이어를 네트워크 해, Microsoft® DirectPlay® Voice 의 채팅 세션을 시작 하는 방법을 나타낸다. 세션에 참가하는지, 또는 세션을 생성 하면, 플레이어는 마이크로 폰을 사용해 회화할 수 있게 된다. 진행중의 세션에는, 다른 플레이어도 수시 참가할 수 있다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\VoiceConnect


VoiceGroup

샘플 VoiceGroup 는, Microsoft® DirectPlay® Voice 를 사용해, 유저가 특정의 플레이어 그룹에 말을 건넬 수가 있도록(듯이) 하는 방법을 나타낸다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\VoiceGroup


VoicePosition

샘플 VoicePosition 는, 3D 포지셔닝을 사용한 Microsoft® DirectPlay® Voice 의 사용 방법을 나타낸다. 이 샘플에서는, 간단한 2D 구라두에 의해 플레이 필드가 표현된다. 플레이어는, 플레이 필드내를 이동해, 3D 공간화의 이펙트를 (들)물을 수가 있다.

패스

(SDK 루트) \Samples\Multimedia\DirectPlay\VoicePosition


DirectPlay C/C++ 레퍼런스

Microsoft® DirectPlay® C/C++ 어플리케이션 프로그래밍 인터페이스의 레퍼런스는, 다음과 같이 분류된다.

  • 인터페이스
  • 함수
  • 콜백 함수
  • 시스템 메세지
  • 구조체
  • 반환값


인터페이스

여기에서는, Microsoft® DirectPlay® 의 다음의 인터페이스의 메소드에 관한 레퍼런스를 나타낸다.

  • IDirectPlay8Peer
  • IDirectPlay8Client
  • IDirectPlay8Server
  • IDirectPlayVoiceClient
  • IDirectPlayVoiceServer
  • IDirectPlayVoiceTest
  • IDirectPlay8LobbyClient
  • IDirectPlay8LobbiedApplication
  • IDirectPlay8Address
  • IDirectPlay8AddressIP


IDirectPlay8Peer

어플리케이션에서는,IDirectPlay8Peer 인터페이스의 메소드를 사용해, 피어 투 피어의 Microsoft® DirectPlay® 세션을 생성 한다.

IDirectPlay8Peer 인터페이스의 메소드는, 다음과 같이 분류할 수 있다.

세션 관리 | Close
 | Connect
 | EnumHosts
 | EnumServiceProviders
 | GetApplicationDesc
 | GetCaps
 | GetConnectionInfo
 | GetSPCaps
 | Host
 | SetApplicationDesc
 | SetCaps
 | SetSPCaps
 | TerminateSession
메세지 관리 | GetSendQueueInfo
 | Initialize
 | ReturnBuffer
 | SendTo
플레이어 관리 | DestroyPeer
 | GetPeerInfo
 | SetPeerInfo
 | GetPlayerContext
그룹 관리 | AddPlayerToGroup
 | CreateGroup
 | DestroyGroup
 | EnumPlayersAndGroups
 | EnumGroupMembers
 | GetGroupContext
 | GetGroupInfo
 | RemovePlayerFromGroup
 | SetGroupInfo
그 외 | CancelAsyncOperation
 | GetLocalHostAddresses
 | GetPeerAddress
 | RegisterLobby

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::AddPlayerToGroup

그룹에 피어를 추가한다.

이 메소드가 불려 가면(자), 어플리케이션에 접속 떠날 수 있어 모든 피어는 DPN_MSGID_ADD_PLAYER_TO_GROUP 메세지를 수신한다.

HRESULT AddPlayerToGroup(
const DPNID idGroup,
const DPNID idClient,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

idGroup
피어를 추가하는 그룹의 식별자를 지정하는 DPNID 형의 변수.
idClient
그룹에 추가되는 피어의 식별자를 지정하는 DPNID 형의 변수.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNADDPLAYERTOGROUP_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통의 경우는 DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 몇개의 에러값을 돌려주는 경우도 있다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

주의

피어는 그 자체 또는 다른 피어를 기존의 그룹에 추가할 수 있다. 피어가 그룹에 올바르게 추가되면(자), 그룹에 송신되는 모든 메세지가 그 피어에도 송신된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::CancelAsyncOperation

비동기의 요구를 취소한다. 예를 들어,IDirectPlay8Peer 인터페이스의 몇개의 메소드는 디폴트에서는 비동기에게 실행된다. 상황에 따라, 요구가 처리되기 전에 그 요구를 취소하고 싶은 경우도 있다. 이 인터페이스로 비동기에게 실행할 수 있는 모든 메소드는, hAsyncHandle 파라미터를 돌려준다.

요구의 hAsyncHandle 를 이 메소드의 hAsyncHandle 파라미터에 건네주는 것에 의해, 특정의 요구가 삭제된다. 이 메소드를 호출해,hAsyncHandle 파라미터에 NULL 를,dwFlags 파라미터에 DPNCANCEL_ALL_OPERATIONS 를 지정하는 것에 의해, 대기중의 모든 비동기 처리를 취소할 수가 있다. 특정의 핸들이 이 메소드로 지정되었을 경우는, 어느 플래그도 설정해서는 안 된다.

HRESULT CancelAsyncOperation(
const DPNHANDLE hAsyncHandle,
const DWORD dwFlags
);

파라미터

hAsyncHandle
비동기 처리를 정지하는 핸들. 이 핸들은, 비동기의 처리를 지원 하는 메소드를 호출했을 때에 받는다. 모든 요구 또는 특정의 종류의 비동기 처리를 정지하려면 , 이 값을 NULL 로 설정한다. 그 요구에 특정의 핸들러를 지정했을 경우는,dwFlags 파라미터를 0 으로 한다.
dwFlags
취소하는 비동기 요구를 지정하는 플래그. 다음의 몇개의 플래그를 설정할 수 있다.
DPNCANCEL_ENUM
모든 비동기 IDirectPlay8Peer::EnumHosts 요구를 취소한다. EnumHosts 메소드로부터 돌려주어지는 핸들을 지정하는 것에 의해, 단일의 EnumHosts 요구를 취소할 수가 있다.
DPNCANCEL_CONNECT
비동기 IDirectPlay8Peer::Connect 요구를 취소한다.
DPNCANCEL_SEND
비동기 IDirectPlay8Peer::SendTo 요구를 취소한다.
DPNCANCEL_ALL_OPERATIONS
비동기의 Connect, Send,및 SentTo 의 각 처리를 모두 취소한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_CANNOTCANCEL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE

주의

이 메소드를 사용해,IDirectPlay8Peer::Connect,IDirectPlay8Peer::SendTo, 및 IDirectPlay8Peer::EnumHosts 메소드의 비동기 처리를 취소할 수가 있다. Microsoft® DirectPlay® 8.0 은, 다른 비동기 처리의 취소를 지원 하고 있지 않다.

IDirectPlay8Peer::SendTo 메소드로부터 돌려주어진 핸들을 지정 하면, 송신 요구를 취소할 수가 있다. 그 경우도,DPN_MSGID_SEND_COMPLETE 또는 DPN_CONNECT_COMPLETE 시스템 메세지는, DPNSEND_NOCOMPLETE 플래그를 설정하지 않고 송신된 비동기의 센드 요구 마다, 어플리케이션 메세지 핸들러에 송신된다. 이 메소드로 삭제된 송신 요구는,DPN_MSGID_SEND_COMPLETE 메세지의 hResultCode 멤버에 DPNERR_USERCANCEL 를 돌려준다.

dwFlags 에 DPNCANCEL_ALL_OPERATIONS, DPNCANCEL_CONNECT, DPNCANCEL_SEND, 또는 DPNCANCEL_ENUM 를 설정했을 경우, DirectPlay 는 모든 일치하는 처리를 취소하려고 한다. 이 메소드는, 취소해에 실패한 처리가 있는 경우, 일부의 취소가 성공하고 있어도 에러를 돌려준다.

주 이 메소드가 값을 돌려줄 때까지, 완료 메세지는 도착하지 않는 경우가 있다. DPN_MSGID_SEND_COMPLETE, DPN_MSGID_CONNECT_COMPLETE,또는 DPN_MSGID_ASYNC_OP_COMPLETE 메세지를 받아들일 때까지, 처리가 종료했다고 봐서는 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::Close

세션에 의해 열린 접속을 닫는다. 몇개의 오브젝트가 IDirectPlay8Peer::Initialize 로 정상적으로 초기화되면(자), 이 메소드를 호출할 필요가 있다.

HRESULT Close(
const DWORD dwFlags
);

파라미터

dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_UNINITIALIZED

주의

이 메소드는, 미처리의 처리가 있으면, 그것을 취소한다. 이 메소드는, 다른 thread의 모든 콜백 통지가 돌아갈 때까지, 블록 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::Connect

피어 투 피어 세션으로, 모든 피어에의 접속을 확립한다. 한 번 접속이 확립 하면, 인터페이스 위에의 통신 채널이 열려, 어플리케이션은 메세지의 도착을 대기한다. 접속이 완료할 때까지,IDirectPlay8Peer::SendTo 메소드를 사용해 메세지를 송신할 수 없다.

이 메소드를 호출하기 전에,IDirectPlay8Peer::EnumHosts 를 호출해, 관련지을 수 있고 있는 호스트의 어플리케이션 기술과 주소를 취득할 수 있다. EnumHosts 메소드는, 현재 호스트 되고 있는 어플리케이션 마다 DPN_APPLICATION_DESC 구조체를 돌려준다. 이 구조체는, 어플리케이션의 인스턴스 GUID 를 포함해 어플리케이션을 기술한다.

이 메소드가 비동기에게 불려 가고 (디폴트),DPNSUCCESS_PENDING 를 돌려주었을 경우, 접속이 완료 하면, 어플리케이션의 메세지 핸들러에 DPN_MSGID_CONNECT_COMPLETE 메세지가 송신된다.

HRESULT Connect(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address *const pHostAddr,
IDirectPlay8Address *const pDeviceInfo,
const DPN_SECURITY_DESC *const pdnSecurity,
const DPN_SECURITY_CREDENTIALS *const pdnCredentials,
const void *const pvUserConnectData,
const DWORD dwUserConnectDataSize,
void *const pvPlayerContext,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

pdnAppDesc
어플리케이션을 기술하는 DPN_APPLICATION_DESC 구조체에의 포인터. 이 메소드로 사용되는 것은, 이 구조체의 일부의 멤버뿐이다. 설정해야 하는 멤버는,dwSize 및 guidApplication 뿐인다. guidInstance,pwszPassword, 및 dwFlags 도 설정할 수 있다.
pHostAddr
IDirectPlay8Address 에의 포인터. 이 인터페이스는, 호스트 하는 컴퓨터에의 접속에 사용되는 주소 정보를 지정한다.
pDeviceInfo
IDirectPlay8Address 인터페이스에의 포인터. 이 포인터는, 서버에의 접속에 사용하는 네트워크 어댑터 (NIC, 모뎀등)를 지정한다.
pdnSecurity
예약이 끝난 상태. NULL 로 설정해 둔다.
pdnCredentials
예약이 끝난 상태. NULL 로 설정해 둔다.
pvUserConnectData
접속을 자세하게 확인하기 위해서 호스트 또는 서버에 제공되는 어플리케이션 고유의 데이터에의 포인터. 이 데이터는,pvUserConnectData 멤버의 DPN_MSGID_INDICATE_CONNECT 메세지에 송신된다. 이 파라미터는 옵션이며, 유저 코드에 의한 여분의 접속의 확인이 제공되지 않는 경우는, NULL 로 설정할 수가 있다.
dwUserConnectDataSize
pvUserConnectData 파라미터에 포함되는 데이터의 사이즈를 지정하는 DWORD 형의 변수.
pvPlayerContext
로컬 플레이어의 문맥값에의 포인터. 이 값은, 로컬 컴퓨터가 DPN_MSGID_CREATE_PLAYER 메세지를 처리할 경우에 사전으로 설정된다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_CONNECT_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
phAsyncHandle
DPNHANDLE. 메소드가 값을 돌려주면(자),phAsyncHandle 는,IDirectPlay8Peer::CancelAsyncOperation 에 건네주어 처리를 취소할 수가 있는 핸들을 포인트 한다. dwFlags 에 DPNCONNECT_SYNC 플래그가 설정되어 있는 경우, 이 파라미터는 NULL 로 설정해야 한다.
dwFlags
접속 모드를 기술하는 플래그. 다음의 플래그를 설정할 수 있다.
DPNCONNECT_OKTOQUERYFORADDRESSING
이 플래그를 설정 하면, Microsoft® DirectPlay® 의 표준의 다이알로그 박스가 표시된다. 충분한 정보가 이 메소드에게 건네지지 않은 경우는, 상세한 것에 대하여 물어 합쳐진다.
DPNCONNECT_SYNC
접속 요구를 동기를 잡으면서 처리한다. 그 경우도, 메세지 핸들러는 DPN_MSGID_CONNECT_COMPLETE 메세지를 받아들여, 호스트로부터의 접속 응답을 처리할 수 있다. 이 메세지는,IDirectPlay8Peer::Connect 가 값을 돌려주기까지 받는다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통의 경우는,DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 몇개의 에러값을 돌려주는 경우도 있다.

DPNERR_HOSTREJECTEDCONNECTION
DPNERR_INVALIDAPPLICATION
DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDINSTANCE
DPNERR_INVALIDINTERFACE
DPNERR_INVALIDPASSWORD
DPNERR_NOCONNECTION
DPNERR_NOTHOST
DPNERR_SESSIONFULL

주의

복수의 열거를 동시에 실행해, 1 개의 접속중에 실행할 수 있지만, 인터페이스 마다 1 개의 접속 밖에 이용할 수 없다. 1 개(살) 이상의 어플리케이션에의 접속을 확립하려면 , 다른 인터페이스를 생성 해야 한다.

이 메소드가 비동기에게 불려 갔을 경우 (디폴트), 접속이 완료 하면, 어플리케이션의 메세지 핸들러에 DPN_MSGID_CONNECT_COMPLETE 메세지가 송신된다. 이 메소드가 에러를 돌려주었을 경우, 완료 메세지는 송신되지 않는다.

이 메소드가 불려 가면(자), 호스트의 메세지 핸들러에 DPN_MSGID_INDICATE_CONNECT 메세지가 송신된다. 호스트가 이 메세지를 처리 하면나무는, 플레이어가 받는 접속 응답 데이터를 DPN_MSGID_CONNECT_COMPLETE 메세지로 지정할 수가 있다. 호스트가 접속을 받아들였을 경우, 접속 응답 데이터에는 커스텀 스타트 업 정보가 들어가 있는 경우가 있다. 접속이 거부되었을 경우, 접속 응답 데이터에 거부의 설명이 들어가 있는 경우가 있다.

IDirectPlay8Peer::Close 를 호출해 호스트와의 접속을 종료할 필요가 있다. Connect()에의 호출이 성공한 후, 모든 남아 있는 열거는 DPNERR_USERCANCEL 를 돌려주어 캔슬된다.

주 dwFlags 에 DPNCONNECT_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 서비스 프로바이더는, 다이알로그 박스를 표시해, 유저에게 주소 정보의 입력을 요구하려고 한다. 서비스 프로바이더가 다이알로그 박스의 표시를 시도할 때는, 표시 가능한 윈도우가 존재하고 있을 필요가 있다. 윈도우가 없는 경우, 어플리케이션은 잠근다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::CreateGroup

현재의 세션에 그룹을 생성 한다. 그룹은 플레이어의 논리적인 모임이다.

주 멀티 캐스팅은 이 릴리스에서는 지원되어 있지 않다.

이 메소드가 불려 가면(자), 어플리케이션에 접속 떠날 수 있어 모든 피어가 DPN_MSGID_CREATE_GROUP 시스템 메세지를 받아들인다.

HRESULT CreateGroup(
const DPN_GROUP_INFO *const pdpnGroupInfo,
VOID *const pvGroupContext,
VOID *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

pdpnGroupInfo
그룹의 기술을 보관 유지하는 DPN_GROUP_INFO 구조체에의 포인터.
pvGroupContext
그룹의 문맥값에의 포인터. 이 값은, 로컬 어플리케이션의 메세지 핸들러가 관련하는 DPN_MSGID_CREATE_GROUP 메세지를 받아들였을 때에 사전으로 설정된다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNCREATEGROUP_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통의 경우,DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 에러값을 돌려주는 경우도 있다.

DPNERR_INVALIDFLAGS

주의

Microsoft® DirectPlay® 는, 계층 그룹을 보관 유지하지 않는다. 이것은, 이러한 그룹이 플랫 그룹과 그룹 데이터의 활용에 의해 간단하게 이행 할 수 있기 때문에 있다.

이 메소드가 불려 가면(자), 모든 피어가 DPN_MSGID_CREATE_GROUP 메세지를 받아들인다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::DestroyPeer

세션으로부터 피어를 삭제한다.

HRESULT DestroyPeer(
const DPNID dpnidClient,
void *const pDestroyInfo,
const DWORD dwDestroyInfoSize,
const DWORD dwFlags
);

파라미터

dpnidClient
삭제하는 피어의 식별자를 지정하는 DPNID 형의 변수.
pDestroyInfo
상세한 삭제 데이터 정보를 기술하는 값에의 포인터.
dwDestroyInfoSize
pDestroyInfo 파라미터에 보관 유지되는 데이터의 사이즈를 지정하는 DWORD 형의 변수.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_NOTHOST

주의

플레이어를 삭제할 수 있는 것은, 세션 호스트뿐이다. 삭제된 플레이어는,DPN_MSGID_TERMINATE_SESSION 메세지에 의해 통지된다. 메세지에 관련지을 수 있고 있는 구조체에는,pDestroyInfo 파라미터에 의해 건네받는 데이터가 저장 된다. 다른 세션 멤버가 이 메소드를 호출하면, 메소드는 실패해, DPNERR_NOTHOST 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::DestroyGroup

IDirectPlay8Peer::CreateGroup 메소드에 의해 생성 된 그룹을 삭제한다. 이 메소드는, 세션내의 임의의 피어로부터 호출할 수가 있다.

HRESULT DestroyGroup(
const DPNID idGroup,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

idGroup
DPNID 형의 변수. 삭제하는 그룹의 식별자를 설정한다.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
phAsyncHandle
A DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNDESTROYGROUP_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통의 경우,DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 몇개의 에러값을 돌려주는 경우도 있다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::EnumPlayersAndGroups

세션의 모든 플레이어 또는 그룹의 식별자, 혹은 그 양쪽 모두의 일람을 취득한다.

HRESULT EnumPlayersAndGroups(
DPNID *const prgdpnid,
DWORD *const pcdpnid,
const DWORD dwFlags
);

파라미터

prgdpnid
세션의 그룹 또는 플레이어의 식별자, 혹은 그 양쪽 모두가 데이터로서 저장 되는 배열에의 포인터.
pcdpnid
prgdpnid 가 포인트 하는 버퍼에 저장 할 수 있는 식별자의 수를 지정하는,DWORD 형의 변수에의 포인터. 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 엔트리의 수가 설정된다.
dwFlags
열거의 동작을 기술하는 플래그. 다음의 1 개 또는 양쪽 모두의 플래그를 설정할 수가 있다.
DPNENUM_PLAYERS
플레이어의 식별자의 리스트를 돌려준다.
DPNENUM_GROUPS
그룹의 식별자의 리스트를 돌려준다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS

주의

그룹 및 플레이어의 정보는 빈번하게 변화하기 위해(때문에), 돌려주어지는 필요한 버퍼 사이즈는 이후의 호출로 바뀌는 경우가 있다. 메소드가 성공할 때까지, 버퍼를 확인해, 재할인 맞히고 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::EnumGroupMembers

그룹내의 모든 플레이어의 일람을 취득한다.

HRESULT EnumGroupMembers(
const DPNID dpnid,
DPNID *const prgdpnid,
DWORD *const pcdpnid,
const DWORD dwFlags
);

파라미터

dpnid
열거하는 플레이어를 보관 유지하는 그룹을 지정하는 DPNID 형의 변수.
prgdpnid
그룹의 플레이어의 식별자를 저장 하는 배열에의 포인터.
pcdpnid
dpnid 가 포인트 하는 버퍼에 저장 할 수 있는 식별자의 수를 지정하는,DWORD 형의 변수에의 포인터. 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 엔트리의 수가 설정된다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

주의

플레이어의 정보는 빈번하게 변화하기 위해(때문에), 돌려주어지는 필요한 버퍼 사이즈는 이후의 호출로 바뀌는 경우가 있다. 메소드가 성공할 때까지, 버퍼를 확인해, 재할인 맞히고 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::EnumHosts

Microsoft® DirectPlay® 게임을 호스트 하는 어플리케이션을 열거한다. 열거 기준을 채우는 어플리케이션이 발견되면(자),DPN_MSGID_ENUM_HOSTS_RESPONSE 시스템 메세지에 의해 어플리케이션의 메세지 핸들러가 불려 간다. 메세지에는, 발견된 어플리케이션을 기술하는 DPN_APPLICATION_DESC 구조체가 보관 유지된다.

임의의 수의 열거를 동시에 실행할 수 있다. 다른 복수의 열거에의 응답을 구별하기 위해서,pvUserContext 의 값이 메세지 핸들러에 제공된다.

열거의 처리에는 다양한 방법이 있기 (위해)때문에, 미디어에 관해서 특히 지식이 없는 한, 어플리케이션에서는 dwEnumPeriod,dwRetryInterval, 또는 dwTimeOut 를 지정해서는 안 된다.

디폴트의 열거 카운트값과 타임 아웃값으로,EnumHosts 는 적절한 시간내에 종료한다. 이러한 값은 서비스 프로바이더에 의해 설정되어IDirectPlay8Peer::GetSPCaps 를 호출해 취득할 수 있다. 비동기의 열거는,IDirectPlay8Peer::CancelAsyncOperation 를 호출하는지, 또는 dwFlags 파라미터에 pAsyncHandle 파라미터에 돌려주어진 핸들러를 건네줄까 DPENUM_CANCEL 플래그를 설정하면, 언제라도 정지할 수 있다. 메세지 핸들러로부터 S_OK 이외의 값을 돌려주어, 열거를 정지할 수도 있다.

HRESULT EnumHosts(
PDPN_APPLICATION_DESC const pApplicationDesc,
IDirectPlay8Address *const pdpaddrHost,
IDirectPlay8Address *const pdpaddrDeviceInfo,
PVOID const pvUserEnumData,
const DWORD dwUserEnumDataSize,
const DWORD dwEnumCount,
const DWORD dwRetryInterval,
const DWORD dwTimeOut,
PVOID const pvUserContext,
HANDLE *const pAsyncHandle
const DWORD dwFlags,
);

파라미터

pApplicationDesc
열거하는 어플리케이션의 호스트를 지정하는 DPN_APPLICATION_DESC 구조체에의 포인터. pApplicationDesc. dwSize 멤버를 적절한 값으로 설정해야 한다. 응답의 수를 줄이려면 ,pApplicationDesc. guidApplication 에 검색하는 어플리케이션의 GUID 를 설정한다. 이 멤버가 설정되어 있지 않은 경우, 모든 어플리케이션이 검색 대상이 된다.
pdpaddrHost
어플리케이션을 호스트 하고 있는 컴퓨터의 주소를 지정하는 IDirectPlay8Address 오브젝트에의 포인터. NULL 를 지정 하면, DirectPlay 가 주소를 생성 한다. 디폴트에서는, DirectPlay 는 pdpaddrDeviceInfo 파라미터로부터 주소를 생성 한다. dwFlags 에 DPNENUMHOSTS_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 유저에게 주소 정보를 문의할 수가 있다.
pdpaddrDeviceInfo
열거에 사용하는 서비스 프로바이더 및 로컬 디바이스의 설정을 지정하는 IDirectPlay8Address 오브젝트에의 포인터.
pvUserEnumData
열거 요구로부터 호스트에게 송신되는 데이터 블록에의 포인터. 데이터의 사이즈는, 네트워크의 종류에 의해 제한된다. 정확한 값을 취득하려면 ,IDirectPlay8Peer::GetSPCaps 를 호출한다.
dwUserEnumDataSize
pvUserEnumData 파라미터로 가리키는 데이터의 사이즈를 지정하는 DWORD 형의 변수.
dwEnumCount
열거 데이터를 송신하는 회수를 지정하는 값. 디폴트값을 사용하려면 , 이 파라미터를 0 으로 설정한다. dwEnumCount 의 디폴트값을 취득하려면 ,IDirectPlay8Peer::GetSPCaps 를 호출한다. dwEnumCount 에 INFINITE 가 지정되었을 경우, 열거는 삭제될 때까지 속행된다.
dwRetryInterval
열거의 재시행의 간격을 밀리 세컨드 단위로 지정하는 값. 디폴트값을 사용하려면 , 이 파라미터를 0 으로 설정한다. dwRetryInterval 의 디폴트값을 취득하려면 ,IDirectPlay8Peer::GetSPCaps 를 호출한다.
dwTimeOut
마지막 열거가 송신된 후, DirectPlay 가 응답을 기다리는 시간 (밀리 세컨드)을 지정하는,DWORD 형의 변수. 디폴트값을 사용하려면 , 이 파라미터를 0 으로 설정한다. dwTimeOut 의 디폴트값을 취득하려면 ,IDirectPlay8Peer::GetSPCaps 를 호출한다. INFINITE 가 지정되었을 경우, 열거는 삭제될 때까지 속행된다.
pvUserContext
열거에의 응답과 함께 불려 갔을 경우에, 피어의 메세지 핸들러에 제공되는 문맥. 동시 실행되고 있는 열거의 응답을 구별하는 경우에 도움이 된다.
pAsyncHandle
DPNHANDLE. 메소드가 값을 돌려주면(자),phAsyncHandle 는,IDirectPlay8Peer::CancelAsyncOperation 에 건네주어 처리를 취소할 수가 있는 핸들을 포인트 한다. dwFlags 에 DPNENUMHOSTS_SYNC 플래그가 설정되어 있는 경우, 이 파라미터는 NULL 로 설정해야 한다.
dwFlags
다음의 플래그를 설정할 수 있다.
DPNENUMHOSTS_SYNC
메소드를 동기를 잡으면서 처리한다.
DPNENUMHOSTS_OKTOQUERYFORADDRESSING
이 플래그를 설정 하면, DirectPlay® 의 표준의 다이알로그 박스가 표시된다. 충분한 정보가 이 메소드에게 건네지지 않은 경우는, 상세한 것에 대하여 물어 합쳐진다.
DPNENUMHOSTS_NOBROADCASTFALLBACK
서비스 프로바이더가 있는 요소를 전요소에 카피하는 것을 지원 하고 있는 경우, 이 플래그를 설정 하면 있는 요소를 전요소에 카피하는 기능이 무효가 된다. 이 플래그를 설정하기 전에 DPN_SP_CAPS 구조체를 조사해 있는 요소를 전요소에 카피하는 것이 지원 되고 있는지 어떤지를 확인하는 것.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통의 경우,DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 몇개의 에러값을 돌려주는 경우도 있다.

DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDPARAM
DPNERR_ENUMQUERYTOOLARGE

주의

dwFlags 에 DPNENUMHOSTS_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 서비스 프로바이더는, 다이알로그 박스를 표시해, 유저에게 주소 정보의 입력을 요구하려고 한다. 서비스 프로바이더가 다이알로그 박스의 표시를 시도할 때는, 표시 가능한 윈도우가 존재하고 있을 필요가 있다. 윈도우가 없는 경우, 어플리케이션은 잠근다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::EnumServiceProviders

어플리케이션으로 사용할 수 있는 등록이 끝난 서비스 프로바이더를 모두 열거한다.

HRESULT EnumServiceProviders(
const GUID *const pguidServiceProvider,
const GUID *const pguidApplication,
const DPN_SERVICE_PROVIDER_INFO *const pSPInfoBuffer,
DWORD *const pcbEnumData,
DWORD *const pcReturned
constDWORD dwFlags,
);

파라미터

pguidServiceProvider
서비스 프로바이더를 지정하는 GUID 형의 변수에의 포인터. 이 옵션 파라미터는, 지정한 서비스 프로바이더의 서브 디바이스를 열거시킨다. 보통은 이 값에 NULL 를 설정해, 사용할 수 있는 모든 서비스 프로바이더를 열거한다.
pguidApplication
어플리케이션을 지정하는 GUID 형의 변수에의 포인터. 이 파라미터에 포인터를 건네주면(자), 그 어플리케이션으로 접속할 수 있는 서비스 프로바이더만이 열거된다. 또, NULL 를 건네주면(자), 시스템에 등록되어 모든 서비스 프로바이더를 열거할 수 있다.
pSPInfoBuffer
서비스 프로바이더 정보를 보관 유지하는,DPN_SERVICE_PROVIDER_INFO 구조체의 배열에의 포인터.
pcbEnumData
버퍼가 너무 작은 경우,pEnumData 버퍼의 사이즈가 저장 되는 DWORD 에의 포인터.
pcReturned
pcbEnumData 배열에 돌려주어지는 DPN_SERVICE_PROVIDER_INFO 구조체의 수를 지정하는 DWORD 형의 변수에의 포인터.
dwFlags
다음의 플래그를 지정할 수 있다.
DPNENUMSERVICEPROVIDERS_ALL
어플리케이션으로 사용할 수 없는 프로바이더나 디바이스가 인스톨되어 있지 않은 프로바이더를 포함해 시스템에 대해서 등록되어 모든 서비스 프로바이더를 열거한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM

주의

pguidServiceProvider 파라미터에 NULL 를 지정해 최초로 이 메소드를 호출해, 시스템으로 이용 가능한 베이스 서비스 프로바이더를 결정한다. 다음에,pguidServiceProvider 에 서비스 프로바이더 GUID 에의 포인터를 건네주는 것으로, 서비스 프로바이더용의 특정의 디바이스를 취득할 수 있다. 이것은, 예를 들어, Microsoft® DirectPlay® 서비스 프로바이더의 모뎀 접속을 사용하는 경우 등에 편리하다. dial out에는 다양한 모뎀을 선택해, 호스트에게는 특정의 모뎀을 선택할 수 있다.

pcbEnumData buffer 버퍼에서는 서비스 프로바이더 정보를 보관 유지하는 용량이 부족하는 경우, 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. pcbEnumData 파라미터에는 필요한 버퍼 사이즈가 포함된다. 보통, 제일이야 있고 방법은 길이 0 의 버퍼로 한 번 메소드를 호출해, 필요한 사이즈를 판단하는 것이다. 다음에, 버퍼를 적절한 사이즈로 해 한번 더 호출한다.

보통의 경우, 이 메소드는, 어플리케이션을 사용할 수 있는 서비스 프로바이더만을 돌려준다. 예를 들어, IPX 네트워킹 프로토콜이 인스톨되어 있지 않은 경우, DirectPlay 는 IPX 서비스 프로바이더를 돌려주지 않는다. DirectPlay 가, 사용할 수 없는 프로바이더를 포함해 모든 서비스 프로바이더를 돌려주도록(듯이) 하려면 ,dwFlags 에 DPNENUMSERVICEPROVIDERS_ALL 플래그를 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetApplicationDesc

접속되고 있는 어플리케이션의 완전한 어플리케이션 기술을 취득한다.

HRESULT GetApplicationDesc(
DPN_APPLICATION_DESC *const pAppDescBuffer,
DWORD *const pcbDataSize,
const DWORD dwFlags
);

파라미터

pAppDescBuffer
어플리케이션의 기술 데이터가 기입해지는 DPN_APPLICATION_DESC 구조체에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. pAppDescBuffer 가 NULL 로 설정되어 있지 않은 경우,pAppDescBuffer. dwSize 멤버를 적절한 값으로 설정할 필요가 있다. pcbDataSize 파라미터는, 데이터의 보관 유지에 필요한 사이즈로 설정된다.
pcbDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 DWORD 형의 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 세션 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우, 이 메소드는 에러값 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 버퍼 사이즈가 설정된다. 이 파라미터가 NULL 의 경우, 메소드는 DPNERR_INVALIDPARAM 를 돌려준다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

주의

pAppDescBuffer 파라미터에 NULL 를 건네주어 최초로 이 메소드를 호출해, 필요한 버퍼 사이즈를 취득한다. 2 번째에 이 메소드를 호출해 버퍼에 데이터를 저장 하면나무는, 구조체의 dwSize 멤버를 적절한 값으로 설정한다.

돌려주어진 DPN_APPLICATION_DESC 구조체에는,guidInstance,guidApplication, 및 pwszSessionName 멤버가 설정되어 있다. 이 안에는, 세션에 접속되고 있는 것 외의 클라이언트에 관한 정보는 포함되지 않았다. 이러한 정보는, 서버 어플리케이션만을 취득할 수 있다. 특히,dwCurrentPlayers 멤버는 반드시 0 으로 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetCaps

현재의 인터페이스의 DPN_CAPS 구조체를 취득한다.

HRESULT GetCaps(
DPN_CAPS *const pdpnCaps,
const DWORD dwFlags
);

파라미터

pdpnCaps
Caps 정보를 받는 DPN_CAPS 구조체에의 포인터. 이 구조체의 dwSize 멤버에는 적절한 값을 설정할 필요가 있다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetConnectionInfo

로컬 어플리케이션과 지정된 리모트 플레이어의 접속에 관한 통계 정보를 취득한다.

HRESULT GetConnectionInfo(
const DPNID dpnidEndPoint,
DPN_CONNECTION_INFO *const pdnConnectInfo,
const DWORD dwFlags
);

파라미터

dpnidEndPoint
리모트 플레이어의 DPNID. 플레이어의 접속 정보를 취득한다.
pdnConnectInfo
지정된 접속에 관한 정보를 취득하는 DPN_CONNECTION_INFO 구조체에의 포인터. 이 구조체의 dwSize 멤버에는,DPN_CONNECTION_INFO 구조체의 사이즈를 설정할 필요가 있다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED
DPNERR_INVALIDPLAYER

주의

Host 또는 Connect 의 호출이 성공한 후에게만, 이 메소드를 호출할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetGroupContext

지정된 그룹의 그룹 문맥값을 취득한다.

HRESULT GetGroupContext(
const DPNID dpnid,
PVOID *const ppvGroupContext,
const DWORD dwFlags
);

파라미터

dpnid
그룹의 식별자를 지정하는 DPNID 형의 변수. 이 그룹의 문맥 데이터를 취득한다.
ppvGroupContext
그룹의 문맥값에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDGROUP
DPNERR_INVALIDPARAM

주의

그룹의 문맥값은,DPN_MSGID_CREATE_GROUP 시스템 메세지의 pvGroupContext 멤버를 문맥값의 데이터에 나타내는 것에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetGroupInfo

그룹명 등, 그룹에 관련지을 수 있고 있는 데이터의 블록을 취득한다.

보통, 그룹 데이터가 변경된 것을 나타내는 DPN_MSGID_GROUP_INFO 시스템 메세지가 수신된 후, 이 메소드가 불려 간다.

HRESULT GetGroupInfo(
const DPNID dpnid,
DPN_GROUP_INFO *const pdpnGroupInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

파라미터

dpnid
데이터 블록을 취득하는 그룹의 식별자를 지정하는 DPNID 형의 변수.
pdpnGroupInfo
그룹 데이터를 기술하는 DPN_GROUP_INFO 구조체에의 포인터. pdwSize 가 NULL 로 설정되어 있지 않은 경우,pdpnGroupInfo. dwSize 에 DPN_GROUP_INFO 구조체의 사이즈를 설정할 필요가 있다.
pdwSize
데이터의 사이즈를 pdpnGroupInfo 파라미터에 돌려주는 DWORD 형의 변수에의 포인터. 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 사이즈가 설정된다.
dwFlags
예약이 끝난 상태. 0 으로 설정한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

주의

Microsoft® DirectPlay® 는 DPN_GROUP_INFO 구조체와 연속하는 버퍼에 있는, 이 구조체의 pwszName 멤버와 pvData 멤버에 할당할 수 있었던 포인터를 돌려준다. 이 2 개의 포인터가 설정되는 경우, 구조체에 가세해 2 개의 포인터에도 충분한 메모리를 할당해 둘 필요가 있다. 이 메소드를 사용하는 가장 확실한 방법은, 처음은 pdwSize 를 NULL 로 설정해 이 메소드를 호출하는 것이다. 메소드가 돌아오면(자),pdwSize 가 올바른 값을 포인트 하고 있다. 그 값을 사용해 구조체의 메모리를 재할인 맞히고 해, 한번 더 메소드를 호출해 정보를 취득한다.

메소드가 돌아오면(자), 대응하는 포인터가 NULL 로 설정되어 있는 경우에서도,DPN_GROUP_INFO 구조체의 dwInfoFlags 멤버에는 항상 DPNINFO_DATA 플래그와 DPNINFO_NAME 플래그가 설정되어 있다. 이러한 플래그는 IDirectPlay8Peer::SetGroupInfo 를 호출하면나무에 사용되어 DirectPlay 로 변경된 값을 통지한다.

IDirectPlay8Peer::SetGroupInfo 메소드를 사용 하면 처리에 부담이 가기 (위해)때문에, 비정적 정보는 IDirectPlay8Peer::SendTo 메소드를 사용해 전송 하는 것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetLocalHostAddresses

세션을 호스트 하기 위해서 사용되는 로컬 주소를 취득한다.

HRESULT GetLocalHostAddresses(
IDirectPlay8Address **const prgpAddress,
DWORD *const pcAddress,
const DWORD dwFlags
);

파라미터

prgpAddress
로컬 호스트 주소를 지정하는 IDirectPlay8Address 오브젝트의 배열에의 포인터. 이러한 오브젝트는 불필요하게 되면(자) 해방해야 한다. 해방하지 않았던 경우, 메모리 누수가 발생한다.
pcAddress
prgpAddress 가 포인트 하는 배열에 돌려줄 수가 있는 주소 오브젝트의 최대수. 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 사이즈가 설정된다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED
DPNERR_NOTHOST

주의

이 메소드를 사용하는 가장 확실한 방법은, 처음은 pcAddress 를 0 으로 설정해 이 메소드를 호출하는 것이다. 메소드가 돌아오면(자),pcAddress 가 필요한 값을 포인트 한다. 2 번째에 이 메소드를 호출하면나무는, 그 값을 사용해 정보를 취득한다.

호출측이 세션 호스트가 아닌 경우, 메소드는 DPNERR_NOTHOST 를 돌려준다. 리모트 플레이어의 주소를 취득하려면 ,IDirectPlay8Peer::GetPeerAddress 를 취득한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetPeerAddress

세션의 지정된 플레이어의 주소를 취득한다.

HRESULT GetPeerAddress(
const DPNID dpnid,
IDirectPlay8Address **const pAddress,
const DWORD dwFlags
);

파라미터

dpnid
플레이어의 식별 정보를 지정하는 DPNID 형의 변수.
pAddress
피어의 주소를 지정하는 IDirectPlay8Address 오브젝트에의 포인터의 주소. 이 오브젝트는, 불필요하게 되면(자) 해방해야 한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPLAYER
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

세션에의 접속에 사용할 수 있는 주소를 취득하려면 ,IDirectPlay8Peer::GetLocalHostAddresses 를 사용한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetPeerInfo

지정된 피어로 설정되어 있는 피어 정보를 취득한다.

HRESULT GetPeerInfo(
const DPNID dpnid,
DPN_PLAYER_INFO *const pdpnPlayerInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

파라미터

dpnid
정보의 취득 대상이 되는 피어의 식별자를 지정하는 DPNID 형의 변수.
pdpnPlayerInfo
피어 정보를 저장 하는 DPN_PLAYER_INFO 구조체에의 포인터. pdwSize 가 NULL 로 설정되어 있지 않은 경우,pdpnPlayerInfo. dwSize 에 DPN_PLAYER_INFO 구조체의 사이즈를 설정해야 한다.
pdwSize
pdpnPlayerInfo 파라미터에 돌려주어지는 피어 데이터의 사이즈를 보관 유지하는 DWORD 형의 변수에의 포인터. 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 을 돌려주어, 이 파라미터에는 필요한 버퍼의 사이즈가 들어간다.
dwFlags
예약이 끝난 상태. 0 으로 설정하는 것.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER

주의

피어가 정보를 갱신한 것을 나타내는 DPN_MSGID_PEER_INFO 메세지를 어플리케이션으로부터 수신한 후, 이 메소드를 호출한다.

Microsoft® DirectPlay® 는 DPN_PLAYER_INFO 구조체와 연속하는 버퍼에 있는, 이 구조체의 pwszName 멤버와 pvData 멤버에 할당할 수 있었던 포인터를 돌려준다. 이 2 개의 포인터가 설정되는 경우, 구조체에 가세해 2 개의 포인터에도 충분한 메모리를 할당해 둘 필요가 있다. 이 메소드를 사용하는 가장 확실한 방법은, 처음은 pdwSize 를 NULL 로 설정해 이 메소드를 호출하는 것이다. 메소드가 돌아오면(자),pdwSize 가 올바른 값을 포인트 하고 있다. 그 값을 사용해 구조체의 메모리를 재할인 맞히고 해, 한번 더 메소드를 호출해 정보를 취득한다.

메소드가 돌아오면(자), 대응하는 포인터가 NULL 로 설정되어 있는 경우에서도,DPN_PLAYER_INFO 구조체의 dwInfoFlags 멤버에는 항상 DPNINFO_DATA 플래그와 DPNINFO_NAME 플래그가 설정되어 있다. 이러한 플래그는 IDirectPlay8Peer::SetPeerInfo 를 호출하면나무에 사용되어 DirectPlay 로 변경된 값을 통지한다.

IDirectPlay8Peer::SetPeerInfo 메소드를 사용 하면 처리에 부담이 가기 (위해)때문에, 비정적 정보는 IDirectPlay8Peer::SendTo 메소드를 사용해 전송 하는 것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetPlayerContext

지정된 피어의 플레이어의 문맥값을 취득한다.

HRESULT GetPlayerContext(
const DPNID dpnid,
PVOID *const ppvPlayerContext,
const DWORD dwFlags
);

파라미터

dpnid
문맥 데이터를 취득하는 플레이어의 식별자를 지정하는 DPNID 형의 변수.
ppvPlayerContext
피어의 문맥 데이터에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER

주의

플레이어의 문맥값은,DPN_MSGID_CREATE_PLAYER 시스템 메세지의 pvPlayerContext 멤버를 문맥값의 데이터에 나타내는 것에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetSendQueueInfo

어플리케이션으로 송신 큐의 사이즈를 감시하기 위해서 사용한다. Microsoft® DirectPlay® 는 수신측 컴퓨터를 처리할 수 있는 이상의 속도로 메세지를 송신하지 않는다. 그 때문에, 송신원의 컴퓨터가, 송신지가 받아들이는 속도보다 고속으로 메세지를 송신했을 경우, 메세지는 송신측의 큐에 축적된다. 어플리케이션에 의해, 송신 큐의 사이즈가 너무 크면(자) 등록되었을 경우는, 메세지의 송신 레이트를 저하시킬 필요가 있다.

HRESULT GetSendQueueInfo(
DWORD *const pdwNumMsgs,
DWORD *const pdwNumBytes,
const DWORD dwFlags
);

파라미터

dpnid
송신 큐 정보를 취득하는 플레이어의 DPNID.
pdwNumMsgs
현재 큐에 축적되고 있는 메세지의 수를 보관 유지하는 DWORD 형의 변수에의 포인터. 이 값은 옵션이며, NULL 로 설정할 수 있다.
pdwNumBytes
현재 큐에 축적되고 있는 메세지 데이터의 총바이트수를 지정하는 DWORD 형의 변수에의 포인터. 이 값은 옵션이며, NULL 로 설정할 수 있다.
dwFlags
DPNGETSENDQUEUEINFO_PRIORITY_NORMAL, DPNGETSENDQUEUEINFO_PRIORITY_HIGH, 또는 DPNGETSENDQUEUEINFO_PRIORITY_LOW 플래그를 지정해, 그 우선 순위를 가지는 특정의 메세지에 대해 문의할 수가 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_INVALIDPARAM

주의

pdwNumMsgs 와 pdwNumBytes 의 양쪽 모두를 NULL 로 설정할 수 없다. 적어도 어느쪽이든 1 개(살)은 유효한 포인터로 설정할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::GetSPCaps

지정된 서비스 프로바이더의 DPN_SP_CAPS 구조체를 취득한다.

HRESULT GetSPCaps(
const GUID *const pguidSP,
DPN_SP_CAPS *const pdpnSPCaps,
const DWORD dwFlags
);

파라미터

pguidSP
정보를 취득하고 싶은 서비스 프로바이더를 지정하는 GUID 에의 포인터.
pdpnSPCaps
지정한 서비스 프로바이더에 관한 정보를 받는 DPN_SP_CAPS 구조체에의 포인터. 구조체의 pdpnSPCaps. dwSize 멤버를 설정할 필요가 있다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

이 메소드는, 지정한 서비스 프로바이더에 관한 정보를 취득한다. IDirectPlay8Peer::Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::Host

로컬 컴퓨터가 호스트 하는, 새로운 피어 투 피어 세션을 생성 한다.

HRESULT Host(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address **const prgpDeviceInfo,
const DWORD cDeviceInfo,
const DPN_SECURITY_DESC *const pdpSecurity,
const DPN_SECURITY_CREDENTIALS *const pdpCredentials,
VOID *const pvPlayerContext,
const DWORD dwFlags
);

파라미터

pdnAppDesc
어플리케이션을 기술하는 DPN_APPLICATION_DESC 구조체에의 포인터.
prgpDeviceInfo
어플리케이션을 호스트 하기 위해서 사용하는 디바이스 주소를 보관 유지하는 IDirectPlay8Address 오브젝트의 배열에의 포인터. 이러한 오브젝트는, 불필요하게 되면(자) 해방해야 한다.
cDeviceInfo
prgpDeviceInfo 가 가리키는 배열의 디바이스 주소 오브젝트의 수를 지정하는 DWORD 형의 변수.
pdpSecurity
예약이 끝난 상태. NULL 로 설정해 둔다.
pdpCredentials
예약이 끝난 상태. NULL 로 설정해 둔다.
pvPlayerContext
로컬 플레이어의 문맥값에의 포인터. 이 값은, 로컬 컴퓨터가 DPN_MSGID_CREATE_PLAYER 메세지를 처리할 경우에 사전으로 설정된다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
dwFlags
다음의 플래그를 지정할 수 있다.
DPNHOST_OKTOQUERYFORADDRESSING
이 플래그를 설정 하면, Microsoft® DirectPlay® 의 표준의 다이알로그 박스가 표시된다. 충분한 정보가 이 메소드에게 건네지지 않은 경우는, 상세한 것에 대하여 물어 합쳐진다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_DATATOOLARGE
DPNERR_INVALIDPARAM
DPNERR_INVALIDDEVICEADDRESS

주의

dwFlags 에 DPNHOST_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 서비스 프로바이더는, 다이알로그 박스를 표시해, 유저에게 주소 정보의 입력을 요구하려고 한다. 서비스 프로바이더가 다이알로그 박스의 표시를 시도할 때는, 표시 가능한 윈도우가 존재하고 있을 필요가 있다. 윈도우가 없는 경우, 어플리케이션은 잠근다.

DPN_APPLICATION_DESC 구조체의 pvApplicationReservedData 멤버에 할당하는 어플리케이션 데이터의 최대 사이즈는, 서비스 프로바이더의 Maximum Transmission Unit 에 의해 제한된다. DPNERR_DATATOOLARGE. 어플리케이션 데이터가 너무 큰 경우, 메소드는 실패해, DPNERR_DATATOOLARGE 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::Initialize

IDirectPlay8Peer 인터페이스 및 리모트 피어로부터의 메세지를 모두 수신하는, 피어의 코드내의 엔트리 포인트를 등록한다. 이 메소드를 호출하고 나서, 이 인터페이스의 그 외의 메소드를 호출할 필요가 있다.

HRESULT Initialize(
PVOID const pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
const DWORD dwFlags
);

파라미터

pvUserContext
메세지 핸들러의 호출로 지정되는, 유저 지정의 문맥값. 유저 지정의 문맥값을 사용 하면, 복수의 인터페이스로부터 공통의 메세지 핸들러에 송신된 메세지를 구별할 수 있다.
pfn
PFNDPNMESSAGEHANDLER 콜백 함수에의 포인터. 리모트 피어로부터의 모든 메세지 및 IDirectPlay8Peer 인터페이스로부터의 세션 변경의 통지를 받을 때, 이 함수가 사용된다.
dwFlags
다음의 플래그를 지정할 수 있다.
DPNINITIALIZE_DISABLEPARAMVAL
이 플래그를 건네주면(자), 현재의 오브젝트에 대한 파라미터 타당성의 검증이 무효가 된다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

주의

IDirectPlay8Peer 인터페이스를 취득하려면 ,CoCreateInstance 를 사용한 후에 이 메소드를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::RegisterLobby

기동한 어플리케이션이, 게임 상태를 자동적으로 로비에 전송 할 수 있도록(듯이) 한다.

HRESULT RegisterLobby(
const DPNHANDLE dpnHandle,
IDirectPlay8LobbiedApplication *const pIDP8LobbiedApplication,
const DWORD dwFlags
);

파라미터

dpnHandle
IDirectPlay8LobbiedApplication::UpdateStatus 를 호출하면나무에 사용하는 접속 핸들.
pIDP8LobbiedApplication
어플리케이션을 지정하는 IDirectPlay8LobbiedApplication 오브젝트에의 포인터.
dwFlags
다음의 플래그의 어느쪽이든을 지정한다.
DPNLOBBY_REGISTER
로비를 어플리케이션에 등록한다.
DPNLOBBY_UNREGISTER
어플리케이션에의 로비의 등록을 해제한다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::RemovePlayerFromGroup

그룹으로부터 피어를 삭제한다.

이 메소드를 호출하면, 어플리케이션에 접속 떠날 수 있어 모든 피어는 DPN_MSGID_REMOVE_PLAYER_FROM_GROUP 메세지를 수신한다.

HRESULT RemovePlayerFromGroup(
const DPNID idGroup,
const DPNID idClient,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

idGroup
피어가 삭제되는 그룹의 식별자를 지정하는 DPNID 형의 변수.
idClient
그룹으로부터 삭제되는 피어의 식별자를 지정하는 DPNID 형의 변수.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
A DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNREMOVEPLAYERFROMGROUP_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통의 경우는,DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 몇개의 에러값을 돌려주는 경우도 있다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP
DPNERR_INVALIDPLAYER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::ReturnBuffer

DPN_MSGID_RECEIVE 시스템 메세지의 pReceiveData 멤버에 의해 어플리케이션에 제공되는 메세지 버퍼를 취득한다. 유저의 메세지 핸들러가 RECEIVE 콜백에 DPNSUCCESS_PENDING 를 돌려주었을 경우, 버퍼의 소유권은 어플리케이션으로 이행했다고 보여져 이 호출에 의해 소유권이 Microsoft® DirectPlay® 에 돌아올 때까지 소유권의 해방이나 변경은 행해지지 않는다.

HRESULT ReturnBuffer(
const DPNHANDLE hBufferHandle,
const DWORD dwFlags
);

파라미터

hBufferHandle
메세지용의 버퍼 핸들을 지정하는 DPNHANDLE 형의 변수. 이것은,DPN_MSGID_RECEIVE 시스템 메세지의 hBufferHandle 멤버로 취득한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::SendTo

적절한 메세지 핸들러에 메세지를 보내는 것에 의해, 세션내의 다른 피어 또는 그룹에 데이터를 송신한다. 메세지는 동기 또는 비동기에 송신할 수가 있다.

HRESULT SendTo(
const DPNID dpnid,
const DPN_BUFFER_DESC *const pBufferDesc,
const DWORD cBufferDesc,
const DWORD dwTimeOut,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

dpnid
데이터를 수신하는 피어 또는 그룹의 식별자. 세션내의 모든 플레이어에게 메세지를 송신하는 경우는, 이 파라미터를 DPNID_ALL_PLAYERS_GROUP 로 설정한다.
pBufferDesc
송신하는 데이터를 보관 유지하는 DPN_BUFFER_DESC 구조체에의 포인터.
cBufferDesc
pBufferDesc 가 가리키는 DPN_BUFFER_DESC 구조체의 수. 이 버젼의 Microsoft® DirectPlay® 에서는, 버퍼는 1 개가 아니면 안된다.
dwTimeOut
메세지의 송신을 기다리는 시간 (밀리 세컨드 단위). 메세지가 dwTimeOut 값으로 송신되어 있지 않은 경우, 메세지는 송신되지 않는다. 메세지의 송신에 대해서 타임 아웃이 필요하지 않은 경우는, 이 파라미터를 0 으로 설정한다.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_SEND_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
phAsyncHandle
DPNHANDLE. 메소드가 돌아오면(자),phAsyncHandle 는,IDirectPlay8Peer::CancelAsyncOperation 에 건네주어 처리를 취소할 수가 있는 핸들을 포인트 한다. dwFlags 에 DPNSEND_SYNC 플래그가 설정되어 있는 경우, 이 파라미터는 NULL 로 설정해야 한다.
dwFlags
송신 동작을 기술하는 플래그. 다음의 1 개 이상의 플래그를 설정할 수가 있다.
DPNSEND_SYNC
SendTo 요구를 동기를 잡으면서 처리한다.
DPNSEND_NOCOPY
DPN_BUFFER_DESC 구조체의 데이터를 사용해, 내부 카피는 실시하지 않는다. 이것은, 효율적인 데이터 송신의 방법이다. 그러나, 수신측이 메세지를 처리하기 전에, 송신측이 메세지를 변경할 수 있기 (위해)때문에, 견뢰한 것은 없어진다. 이 플래그를 DPNSEND_NOCOMPLETE 와 조합할 수 없다.
DPNSEND_NOCOMPLETE
메세지 핸들러에 DPN_MSGID_SEND_COMPLETE 를 송신하지 않는다. 이 플래그를 DPNSEND_NOCOPY 또는 DPNSEND_GUARANTEED 와 함께 사용할 수 없다. 또, 이 플래그를 사용하는 경우,pvAsyncContext 는 NULL 가 아니면 안된다.
DPNSEND_COMPLETEONPROCESS
메세지가 타겟으로 전달되어 메세지의 수신을 나타내는 타겟의 메세지 핸들러가 돌려주어질 때,DPN_MSGID_SEND_COMPLETE 를 메세지 핸들러에 송신한다. 이 플래그가 설정되었을 경우는, 여분의 내부 메세지의 오버헤드가 있어, 메세지의 송신 처리가 현저하게 저하할 가능성이 있다. 이 플래그를 설정했을 경우는, DPNSEND_GUARANTEED 도 설정할 필요가 있다.
DPNSEND_GUARANTEED
보증 첨부 전달 방식을 사용해 메세지를 송신한다.
DPNSEND_PRIORITY_HIGH
메세지의 우선 순위를 높게 설정한다. 이 플래그를 DPNSEND_PRIORITY_LOW 와 함께 사용할 수 없다.
DPNSEND_PRIORITY_LOW
메세지의 우선 순위를 낮게 설정한다. 이 플래그를 DPNSEND_PRIORITY_HIGH 와 함께 사용할 수 없다.
DPNSEND_NONSEQUENTIAL
이 플래그가 설정되었을 경우, 타겟 어플리케이션은, 유저의 컴퓨터에 도착한 순서에 메세지를 받아들인다. 이 플래그가 설정되어 있지 않은 경우, 메세지는 시퀀셜에 전달되어 타겟 어플리케이션은 송신된 순서에 메세지를 받아들인다. 따라서, 착신한 메세지를, 결핍 하고 있는 메세지가 도착할 때까지 버퍼에 저장 하는 경우가 있다.
DPNSEND_NOLOOPBACK
로컬 플레이어를 포함한 그룹에 송신하고 있을 때, 메세지 핸들러에의 DPN_MSGID_RECEIVE 시스템 메세지를 억제한다. 예를 들어, 세션 전체에 있는 요소를 전요소에 카피하는 경우는, 이 플래그가 편리하다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통의 경우는,DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 몇개의 에러값을 돌려주는 경우도 있다.

DPNERR_CONNECTIONLOST
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_TIMEDOUT

주의

이 메소드는, 수취하는 측의 메세지 핸들러에 DPN_MSGID_RECEIVE 시스템 메세지를 생성한다. 데이터 버퍼는, 관련지을 수 있고 있는 구조체의 pReceiveData 멤버에 보관 유지되고 있다.

메세지에는, 저, 보통, 고의 3 개의 우선 순위의 어느쪽이든을 설정할 수 있다. 메세지에 낮은 우선 순위 또는 높은 우선 순위를 지정하려면 dwFlags 에 적절한 플래그를 설정한다. 어느 쪽의 우선 순위 플래그도 설정하지 않았던 경우, 메세지는 보통의 우선 순위가 된다. 송신 우선 순위의 상세한 것에 대하여는, 「네트워킹의 기본」을 참조할것.

SendTo 요구가 완료 하면, 송신측의 메세지 핸들러에 DPN_MSGID_SEND_COMPLETE 시스템 메세지가 송신된다. 요구의 성공 또는 실패는, 관련지을 수 있었던 구조체의 hResultCode 멤버에 보관 유지된다. dwFlags 에 DPNSEND_NOCOMPLETE 플래그를 설정 하면, 송신 완료의 시스템 메세지는 송신되지 않는다.

보통, 메세지가 송신되면(자) 즉시, 송신 완료가 송신원의 컴퓨터에 송신된다. 바꾸어 말하면(자), 송신 완료는, 메세지가 타겟상에서 처리된 것을 반드시 의미하지 않는다. 메세지는 아직 큐내에 있을 가능성도 있다. 메세지가 타겟으로 처리된 것을 확인하려면 ,dwFlags 에 DPNSEND_COMPLETEONPROCESS 플래그를 설정한다. 이 플래그를 설정 하면, 타겟의 메세지 핸들러가 메세지를 처리해 돌아올 때까지, 송신 완료는 송신되지 않는다.

어플리케이션은 IDirectPlay8Client,IDirectPlay8Server, 또는 IDirectPlay8Peer 로 Close 를 호출하기 전이나 최종 릴리스를 하기 전에,CancelAsyncOperation 를 호출해 남아 있는 Send 를 캔슬해야 한다. 거기에 실패 하면 예기치 못한 결과가 일어난다.

주 메소드가 돌아올 때까지는, 데이터 버퍼등의 리소스가 유효한 상태인 채이다고 봐서는 안 된다. 이 메소드를 비동기에게 호출하는 경우, 호출이 돌아오기 전에 DPN_MSGID_SEND_COMPLETE 메세지를 받아들여, 메세지 핸들러가 처리해 버리는 일이 있다. 메세지 핸들러가 데이터 버퍼등의 리소스를 할당 해제, 또는 무효로 했을 경우, 메소드가 불려 간 다음에 리소스가 무효가 되는 일이 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::SetApplicationDesc

호스트 되는 어플리케이션의 설정을 변경한다. 변경할 수 있는 것은, 몇개의 설정뿐이다.

HRESULT SetApplicationDesc(
const DPN_APPLICATION_DESC *const pad,
const DWORD dwFlags
);

파라미터

pad
변경하는 어플리케이션의 설정을 기술하는 DPN_APPLICATION_DESC 구조체에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_DATATOOLARGE
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOTHOST

주의

이 메소드를 사용해,DPN_APPLICATION_DESC 구조체의 이하의 멤버만을 변경할 수 있다.

  • dwMaxPlayers
  • pwszSessionName
  • pwszPassword
  • pvApplicationReservedData
  • dwApplicationReservedDataSize

DPN_APPLICATION_DESC 구조체의 pvApplicationReservedData 멤버에 할당하는 어플리케이션 데이터의 최대 사이즈는, 서비스 프로바이더의 Maximum Transmission Unit 에 의해 제한된다. 어플리케이션 데이터가 너무 큰 경우, 메소드는 실패해, DPNERR_DATATOOLARGE 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::SetCaps

현재의 인터페이스의 DPN_CAPS 구조체를 설정한다.

HRESULT SetCaps(
const DPN_CAPS *const pdpCaps,
const DWORD dwFlags
);

파라미터

pdpCaps
현재의 인터페이스에 관한 정보의 설정에 사용되는 DPN_CAPS 구조체에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

이 메소드는, 지정된 서비스 프로바이더에 대한 파라미터를 설정한다. Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::SetGroupInfo

그룹명 등, 그룹에 관련하는 데이터의 블록을 설정한다.

이 메소드를 호출하면,DPN_MSGID_GROUP_INFO 메세지가 생성된다. 이 메세지는, 어플리케이션에 접속 떠날 수 있어 모든 피어에 송신된다.

HRESULT SetGroupInfo(
const DPNID dpnid,
DPN_GROUP_INFO *const pdpnGroupInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

dpnid
데이터 블록을 변경하는 그룹의 식별자를 지정하는 DPNID 형의 변수.
pdpnGroupInfo
설정하는 그룹 데이터를 기술하는 DPN_GROUP_INFO 구조체에의 포인터. pwszName 또는 pvData 멤버의 값을 변경하려면 , 대응하는 DPNINFO_NAME 플래그 또는 DPNINFO_DATA 플래그를 dwInfoFlags 멤버를 설정할 필요가 있다.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 몇개의 값을 설정할 수 있다.
DPNSETGROUPINFO_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통의 경우,DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 몇개의 에러값을 돌려주는 경우도 있다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

주의

IDirectPlay8Peer::SetGroupInfo 메소드를 사용 하면 처리에 부담이 가기 (위해)때문에, 비정적 정보는 IDirectPlay8Peer::SendTo 메소드를 사용해 전송 하는 것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::SetPeerInfo

로컬 피어의 정적 설정을 설정한다. 어플리케이션에 기본적인 플레이어 정보를 전송 하려면 , 접속전에 이 메소드를 호출한다. 피어가 올바르게 어플리케이션에 접속 하면, 다른 플레이어는 이 메소드로 설정된 정보를 IDirectPlay8Peer::GetPeerInfo 메소드를 호출해 취득할 수 있다.

HRESULT SetPeerInfo(
const DPN_PLAYER_INFO *const pdpnPlayerInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

pdpnPlayerInfo
설정하는 피어 정보를 보관 유지하는 DPN_PLAYER_INFO 구조체에의 포인터.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNSETPEERINFO_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통의 경우,DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 몇개의 에러값을 돌려주는 경우도 있다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

주의

이 메소드는, 세션중 언제라도 호출할 수가 있다.

IDirectPlay8Peer::SetPeerInfo 메소드를 사용 하면 처리에 부담이 가기 (위해)때문에, 비정적 정보는 IDirectPlay8Peer::SendTo 메소드를 사용해 전송 하는 것.

어플리케이션에의 접속 후, 이 메소드를 사용해 피어 정보를 변경할 수 있다. 접속 후에 이 메소드를 호출하면, 데이터의 갱신을 알리는 DPN_MSGID_PEER_INFO 시스템 메세지가 모든 플레이어에 대해서 생성된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::SetSPCaps

지정된 서비스 프로바이더의 DPN_SP_CAPS 구조체를 설정한다.

HRESULT SetSPCaps(
const GUID *const pguidSP,
const DPN_SP_CAPS *const pdpSPCaps
);

파라미터

pguidSP
정보를 설정하는 서비스 프로바이더를 지정하는 GUID 에의 포인터.
pdpSPCaps
지정한 서비스 프로바이더에 관한 정보를 설정하는 DPN_SP_CAPS 구조체에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

이 메소드는, 지정된 서비스 프로바이더에 대한 파라미터를 설정한다. Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다. 현재, 이 호출에서는 dwNumThreads 필드만 설정할 수가 있다. dwFlags 필드는 0 이 아니면 안된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Peer::TerminateSession

현재의 Microsoft® DirectPlay® 세션을 종료한다.

HRESULT TerminateSession(
void *const pvTerminateData,
const DWORD dwTerminateDataSize,
const DWORD dwFlags
);

파라미터

pvTerminateData
종료 데이터에의 포인터. 이 데이터는,DPN_MSGID_TERMINATE_SESSION 시스템 메세지의 pvTerminateData 멤버에도 송신된다.
dwTerminateDataSize
pvTerminateData 파라미터에 보관 유지되는 데이터의 사이즈.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

주의

이 메소드는 호스트 플레이어만 호출할 수가 있다.

이 메소드가 불려 가면(자), 세션의 각 플레이어의 메세지 핸들러에 DPN_MSGID_TERMINATE_SESSION 가 송신된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client

어플리케이션은,IDirectPlay8Client 인터페이스의 메소드를 사용해, 클라이언트/서버 세션용의 클라이언트 어플리케이션의 생성과 관리를 실시한다.

IDirectPlay8Client 인터페이스의 메소드는, 다음과 같이 분류할 수 있다.

세션 관리 | Close
 | Connect
 | EnumHosts
 | EnumServiceProviders
 | GetApplicationDesc
 | GetCaps
 | GetSPCaps
 | SetCaps
 | SetSPCaps
메세지 관리 | GetSendQueueInfo
 | Initialize
 | ReturnBuffer
 | Send
클라이언트 정보 | SetClientInfo
서버 정보 | GetServerInfo
그 외 | CancelAsyncOperation
 | RegisterLobby
 | GetConnectionInfo
 | GetServerAddress


IDirectPlay8Client::CancelAsyncOperation

비동기의 요구를 취소한다. 디폴트에서는,IDirectPlay8Client 인터페이스가 많은 메소드가 비동기에게 실행된다. 상황에 따라, 요구가 처리되기 전에 그 요구를 취소하고 싶은 경우도 있다. 이 인터페이스로 비동기에게 실행할 수 있는 모든 메소드는,hAsyncHandle 파라미터를 돌려준다.

요구의 hAsyncHandle 를 이 메소드의 hAsyncHandle 파라미터에 건네주는 것에 의해, 특정의 요구가 삭제된다. 이 메소드를 호출해,hAsyncHandle 파라미터에 NULL 를,dwFlags 파라미터에 DPNCANCEL_ALL_OPERATIONS 를 지정하는 것에 의해, 대기중의 모든 비동기 처리를 취소할 수가 있다. 특정의 핸들이 이 메소드로 지정되었을 경우는, 어느 플래그도 설정해서는 안 된다.

HRESULT CancelAsyncOperation(
const DPNHANDLE hAsyncHandle,
const DWORD dwFlags
);

파라미터

hAsyncHandle
비동기 처리를 정지하는 핸들. 이 핸들은, 비동기의 처리를 지원 하는 메소드를 호출했을 때에 받는다. 모든 요구 또는 특정의 종류의 비동기 요구를 정지하려면 , 이 값을 NULL 로 한다. 특정의 핸들이 지정되고 있는 경우,dwFlags 파라미터는 0 으로 설정할 필요가 있다.
dwFlags
취소하는 비동기 요구를 지정하는 플래그. 다음의 몇개의 플래그를 설정할 수 있다.
DPNCANCEL_ENUM
모든 비동기 IDirectPlay8Client::EnumHosts 요구를 취소한다. EnumHosts 메소드로부터 돌려주어지는 핸들을 지정하는 것에 의해, 단일의 EnumHosts 요구를 취소할 수가 있다.
DPNCANCEL_CONNECT
비동기 IDirectPlay8Client::Connect 요구를 취소한다.
DPNCANCEL_SEND
비동기 IDirectPlay8Client::Send 요구를 취소한다.
DPNCANCEL_ALL_OPERATIONS
모든 비동기 요구를 취소한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_CANNOTCANCEL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNSUCCESS_PENDING

주의

이 메소드를 사용해,IDirectPlay8Client::Connect,IDirectPlay8Client::Send, 및 IDirectPlay8Client::EnumHosts 메소드의 비동기 처리를 취소할 수가 있다. Microsoft® DirectPlay® 8.0 은, 다른 비동기 처리의 취소를 지원 하고 있지 않다.

IDirectPlay8Client::Send 메소드로부터 돌려주어진 핸들을 지정 하면, 송신을 취소할 수가 있다. 그 경우도,DPN_MSGID_SEND_COMPLETE 시스템 메세지는, DPNSEND_NOCOMPLETE 플래그를 설정하지 않고 송신된 비동기 송신 요구 마다, 어플리케이션 메세지 핸들러에 송신된다. 이 메소드로 삭제된 송신은,DPN_MSGID_SEND_COMPLETE 메세지의 hResultCode 멤버에 DPNERR_USERCANCEL 를 돌려준다.

dwFlags 에 DPNCANCEL_ALL_OPERATIONS, DPNCANCEL_CONNECT, DPNCANCEL_SEND, 또는 DPNCANCEL_ENUM 를 설정했을 경우, DirectPlay 는 모든 일치하는 처리를 취소하려고 한다. 이 메소드는, 취소해에 실패한 처리가 있는 경우, 일부의 취소가 성공하고 있어도 에러를 돌려준다.

주 이 메소드가 돌아올 때까지, 완료 메세지가 도착하지 않는 경우가 있다. DPN_MSGID_SEND_COMPLETE, DPN_MSGID_CONNECT_COMPLETE,또는 DPN_MSGID_ASYNC_OP_COMPLETE 메세지를 받아들일 때까지, 처리가 종료했다고 봐서는 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::Close

세션과의 오픈 접속을 닫는다. 이 메소드는,IDirectPlay8Client::Initialize 메소드의 호출에 의해 올바르게 초기화된 모든 오브젝트로 호출할 필요가 있다.

HRESULT Close(
const DWORD dwFlags
);

파라미터

dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_UNINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::Connect

서버에의 접속을 확립한다. 접속이 확립 하면, 인터페이스 위에의 통신 채널이 열려, 어플리케이션은 메세지의 도착을 대기한다. 접속이 완료할 때까지,IDirectPlay8Client::Send 메소드를 사용해 메세지를 송신할 수 없다.

이 메소드를 호출하기 전에,IDirectPlay8Client::EnumHosts 를 호출해 어플리케이션의 기술을 취득할 수가 있다. EnumHosts 메소드는, 호스트 되고 있는 어플리케이션 마다 DPN_APPLICATION_DESC 구조체를 돌려준다. 이 구조체는, 어플리케이션의 GUID 를 포함해 어플리케이션을 기술한다.

이 메소드가 비동기에게 불려 가는 경우 (디폴트), 접속이 완료 하면, 어플리케이션의 메세지 핸들러에 DPN_MSGID_CONNECT_COMPLETE 메세지가 송신된다.

HRESULT Connect(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address *const pHostAddr,
IDirectPlay8Address *const pDeviceInfo,
const DPN_SECURITY_DESC *const pdnSecurity,
const DPN_SECURITY_CREDENTIALS *const pdnCredentials,
const void *const pvUserConnectData,
const DWORD dwUserConnectDataSize,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

pdnAppDesc
어플리케이션을 기술하는 DPN_APPLICATION_DESC 구조체에의 포인터. 설정할 필요가 있는 이 구조체의 유일한 멤버는,guidApplication 멤버이다. 이 메소드로 사용되는 것은, 이 구조체의 일부의 멤버뿐이다. 설정할 필요가 있는 유일한 멤버는,guidApplication 이다. guidInstance,pwszPassword,dwFlags, 및 dwSize 도 설정할 수 있다.
pHostAddr
IDirectPlay8Address 에의 포인터. 이 인터페이스는, 호스트 하는 컴퓨터에의 접속에 사용되는 주소 정보를 지정한다.
pDeviceInfo
IDirectPlay8Address 오브젝트에의 포인터. 이 오브젝트는, 서버와의 접속에 사용하는 네트워크 어댑터 (NIC 나 모뎀등)를 지정한다.
pdnSecurity
예약이 끝난 상태. NULL 로 설정해 둔다.
pdnCredentials
예약이 끝난 상태. NULL 로 설정해 둔다.
pvUserConnectData
접속을 자세하게 확인하기 위해서 호스트 또는 서버에 제공되는 어플리케이션 고유의 데이터에의 포인터. 이 데이터는,pvUserConnectData 멤버의 DPN_MSGID_INDICATE_CONNECT 메세지에 송신된다. 이 파라미터는 옵션이며, NULL 를 건네주면(자), 유저 코드에 의해 제공되는 접속의 확인을 우회도로 할 수가 있다.
dwUserConnectDataSize
pvUserConnectData 에 보관 유지되는 데이터의 사이즈를 지정하는 DWORD 형의 변수.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_CONNECT_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
phAsyncHandle
DPNHANDLE. 메소드가 돌아오면(자),phAsyncHandle 는,IDirectPlay8Client::CancelAsyncOperation 에 건네주어 처리를 취소할 수가 있는 핸들을 포인트 한다. dwFlags 에 DPNCONNECT_SYNC 플래그가 설정되어 있는 경우, 이 파라미터는 NULL 로 설정해야 한다.
dwFlags
접속 모드를 기술하는 플래그. 다음의 플래그를 설정할 수 있다.
DPNCONNECT_OKTOQUERYFORADDRESSING
이 플래그를 설정 하면, Microsoft® DirectPlay® 의 표준의 다이알로그 박스가 표시된다. 충분한 정보가 이 메소드에게 건네지지 않은 경우는, 상세한 것에 대하여 물어 합쳐진다.
DPNCONNECT_SYNC
접속 요구를 동기를 잡으면서 처리한다. 이 플래그를 설정 하면,DPN_MSGID_CONNECT_COMPLETE 시스템 메세지는 생성되지 않는다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 요구가 비동기에 처리되는 경우, 메소드가 즉시 처리되면(자), S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_HOSTREJECTEDCONNECTION
DPNERR_INVALIDAPPLICATION
DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDINSTANCE
DPNERR_INVALIDINTERFACE
DPNERR_INVALIDPASSWORD
DPNERR_NOCONNECTION
DPNERR_NOTHOST
DPNERR_SESSIONFULL
DPNERR_ALREADYCONNECTED

주의

복수의 열거를 동시에 실행해, 1 개의 접속중에 실행할 수 있지만, 인터페이스 마다 1 개의 접속 밖에 이용할 수 없다. 1 개(살) 이상의 어플리케이션에의 접속을 확립하려면 , 다른 인터페이스를 생성 해야 한다.

이 메소드가 불려 가면(자), 서버의 메세지 핸들러에 DPN_MSGID_INDICATE_CONNECT 메세지가 송신된다. 이 메세지의 취득시, 호스트는 접속 응답 데이터를 Connect 메소드에 건네주는 일이 있다. 접속 응답 데이터는, 호스트가 접속을 승인하지 않는 것을 나타내는 메세지를 송신하는 일이 있다. 그 후 호출해 원어플리케이션은, 이 응답을 적절히 처리할 수가 있다.

Connect()가 성공했을 경우, 완료시의 hResultCode 는 S_OK 를 나타낸다. 그 이외의 경우는, 에러를 나타낸다. Host 플레이어가 DPN_MSGID_INDICATE_CONNECT 메세지로부터 S_OK 이외를 돌려주었을 경우, 완료의 에러 코드는 DPNERR_HOSTREJECTEDCONNECTION 인 것이 많다.

접속이 완료 하면, 어플리케이션의 메세지 핸들러에 DPN_MSGID_CONNECT_COMPLETE 메세지가 송신된다.

이 메소드로 확립한 접속을 닫으려면 ,IDirectPlay8Client::Close 메소드를 호출한다. Connect()에의 호출이 성공한 후, 모든 남아 있는 열거는 DPNERR_USERCANCEL 를 돌려주어 캔슬된다.

주 dwFlags 에 DPNCONNECT_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 서비스 프로바이더는, 다이알로그 박스를 표시해, 유저에게 주소 정보의 입력을 요구하려고 한다. 서비스 프로바이더가 다이알로그 박스의 표시를 시도할 때는, 표시 가능한 윈도우가 존재하고 있을 필요가 있다. 윈도우가 없는 경우, 어플리케이션은 잠근다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::EnumHosts

Microsoft® DirectPlay® 게임을 호스트 하는 어플리케이션을 열거한다. 열거 기준을 채우는 어플리케이션이 발견되면(자),DPN_MSGID_ENUM_HOSTS_RESPONSE 시스템 메세지에 의해 어플리케이션의 메세지 핸들러가 불려 간다. 메세지에는, 발견된 어플리케이션을 기술하는 DPN_APPLICATION_DESC 구조체가 보관 유지된다.

임의의 수의 열거를 동시에 실행할 수 있다. 다른 복수의 열거에의 응답을 구별하기 위해서,pvUserContext 의 값이 메세지 핸들러에 제공된다.

열거의 처리에는 다양한 방법이 있기 (위해)때문에, 미디어에 관해서 특히 지식이 없는 한, 어플리케이션에서는 dwEnumPeriod,dwRetryInterval, 또는 dwTimeOut 를 지정하지 않는 것을 추천 한다.

디폴트의 열거 카운트값과 타임 아웃값으로,EnumHosts 는 적절한 시간내에 종료한다. 이러한 값은 서비스 프로바이더에 의해 설정되어IDirectPlay8Client::GetSPCaps 를 호출해 취득할 수 있다. 비동기의 열거는,IDirectPlay8Client::CancelAsyncOperation 를 호출하는지, 또는 dwFlags 파라미터에 pAsyncHandle 파라미터에 돌려주어진 핸들러를 건네줄까 DPENUM_CANCEL 플래그를 설정하면, 언제라도 정지할 수 있다. 메세지 핸들러로부터 S_OK 이외의 값을 돌려주어, 열거를 정지할 수도 있다.

HRESULT EnumHosts(
PDPN_APPLICATION_DESC const pApplicationDesc,
IDirectPlay8Address *const pdpaddrHost,
IDirectPlay8Address *const pdpaddrDeviceInfo,
PVOID const pvUserEnumData,
const DWORD dwUserEnumDataSize,
const DWORD dwEnumCount,
const DWORD dwRetryInterval,
const DWORD dwTimeOut,
PVOID const pvUserContext,
HANDLE *const pAsyncHandle,
const DWORD dwFlags
);

파라미터

pApplicationDesc
열거하는 어플리케이션의 호스트를 지정하는 DPN_APPLICATION_DESC 구조체에의 포인터. pApplicationDesc. dwSize 멤버를 적절한 값으로 설정해야 한다. 응답의 수를 줄이려면 ,pApplicationDesc. guidApplication 에 검색하는 어플리케이션의 GUID 를 설정한다. 이 멤버가 설정되어 있지 않은 경우, 모든 어플리케이션이 검색 대상이 된다.
pdpaddrHost
어플리케이션을 호스트 하고 있는 컴퓨터의 주소를 지정하는 IDirectPlay8Address 오브젝트에의 포인터. NULL 를 지정했을 경우, DirectPlay 가 주소를 생성 한다. 디폴트에서는, DirectPlay 는 pdpaddrDeviceInfo 파라미터로부터 주소를 생성 한다. dwFlags 에 DPNENUMHOSTS_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 유저에게 주소 정보를 조회할 수가 있다.
pdpaddrDeviceInfo
열거에 사용하는 서비스 프로바이더 및 로컬 디바이스의 설정을 지정하는 IDirectPlay8Address 오브젝트에의 포인터.
pvUserEnumData
열거 요구로부터 호스트에게 송신되는 데이터 블록에의 포인터. 데이터의 사이즈는, 네트워크의 타입에 의해 제한된다. IDirectPlay8Client::GetSPCaps 를 호출해 정확한 값을 취득한다.
dwUserEnumDataSize
pvUserEnumData 파라미터로 가리키는 데이터의 사이즈를 지정하는 DWORD 형의 변수.
dwEnumCount
열거 데이터를 송신하는 회수를 지정하는 값. 디폴트값을 사용하려면 , 이 파라미터를 0 으로 설정한다. dwEnumCount 의 디폴트값을 취득하려면 ,IDirectPlay8Client::GetSPCaps 를 호출한다. dwEnumCount 에 INFINITE 가 지정되었을 경우, 열거는 삭제될 때까지 속행된다.
dwRetryInterval
열거의 재시행의 간격을 밀리 세컨드 단위로 지정하는 값. 디폴트값을 사용하려면 , 이 파라미터를 0 으로 설정한다. dwRetryInterval 의 디폴트값을 취득하려면 ,IDirectPlay8Client::GetSPCaps 를 호출한다.
dwTimeOut
마지막 열거가 송신된 후, DirectPlay 가 응답을 기다리는 시간 (밀리 세컨드)을 지정하는,DWORD 형의 변수. 디폴트값을 사용하려면 , 이 파라미터를 0 으로 설정한다. dwTimeOut 의 디폴트값을 취득하려면 ,IDirectPlay8Client::GetSPCaps 를 호출한다. INFINITE 가 지정되었을 경우, 열거는 삭제될 때까지 속행된다.
pvUserContext
열거에의 응답과 함께 불려 갔을 경우에, 클라이언트의 메세지 핸들러에 제공되는 문맥. 동시 실행되고 있는 열거의 응답을 구별하는 경우에 도움이 된다.
pAsyncHandle
DPNHANDLE. 메소드가 돌아오면(자),phAsyncHandle 는,IDirectPlay8Client::CancelAsyncOperation 에 건네주어 처리를 취소할 수가 있는 핸들을 포인트 한다. dwFlags 에 DPNENUMHOSTS_SYNC 플래그가 설정되어 있는 경우, 이 파라미터는 NULL 로 설정해야 한다.
dwFlags
다음의 플래그를 설정할 수 있다.
DPNENUMHOSTS_SYNC
메소드를 동기를 잡으면서 처리한다.
DPNENUMHOSTS_OKTOQUERYFORADDRESSING
이 플래그를 설정 하면, DirectPlay 의 표준 다이알로그 박스가 표시된다. 충분한 정보가 이 메소드에게 건네지지 않은 경우는, 상세한 것에 대하여 물어 합쳐진다.
DPNENUMHOSTS_NOBROADCASTFALLBACK
서비스 프로바이더가 있는 요소를 전요소에 카피하는 것을 지원 하고 있는 경우, 이 플래그를 설정 하면 있는 요소를 전요소에 카피하는 기능이 무효가 된다. 이 플래그를 설정하기 전에 DPN_SP_CAPS 구조체를 조사해 있는 요소를 전요소에 카피하는 것이 지원 되고 있는지 어떤지를 확인하는 것.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 요구가 비동기에 처리되는 경우, 메소드가 즉시 처리되면(자), S_OK 를 돌려주는 경우가 있다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDPARAM
DPNERR_ENUMQUERYTOOLARGE

주의

dwFlags 에 DPNENUMHOSTS_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 서비스 프로바이더는, 다이알로그 박스를 표시해, 유저에게 주소 정보의 입력을 요구하려고 한다. 서비스 프로바이더가 다이알로그 박스의 표시를 시도할 때는, 표시 가능한 윈도우가 존재하고 있을 필요가 있다. 윈도우가 없는 경우, 어플리케이션은 잠근다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::EnumServiceProviders

어플리케이션으로 사용할 수 있는 등록이 끝난 서비스 프로바이더를 열거한다.

HRESULT EnumServiceProviders(
const GUID *const pguidServiceProvider,
const GUID *const pguidApplication,
DPN_SERVICE_PROVIDER_INFO *const pSPInfoBuffer,
PDWORD const pcbEnumData,
PDWORD const pcReturned,
const DWORD dwFlags
);

파라미터

pguidServiceProvider
서비스 프로바이더를 지정하는 GUID 형의 변수에의 포인터. 이 옵션 파라미터는, 지정한 서비스 프로바이더의 서브 디바이스를 열거시킨다. 보통은 이 값에 NULL 를 설정해, 사용할 수 있는 모든 서비스 프로바이더를 열거한다.
pguidApplication
어플리케이션을 지정하는 GUID 형의 변수에의 포인터. 이 파라미터에 포인터가 건네받았을 경우는, 어플리케이션에 접속할 수 있는 서비스 프로바이더만이 열거된다. NULL 를 건네주어, 시스템에 등록을 마친 서비스 프로바이더를 열거할 수도 있다.
pSPInfoBuffer
서비스 프로바이더 정보를 보관 유지하는,DPN_SERVICE_PROVIDER_INFO 구조체의 배열에의 포인터.
pcbEnumData
버퍼가 너무 작은 경우,pEnumData 버퍼의 사이즈가 저장 되는 DWORD 에의 포인터.
pcReturned
pEnumData 배열에 돌려주어지는 DPN_SERVICE_PROVIDER_INFO 구조체의 수를 지정하는 DWORD 형의 변수에의 포인터.
dwFlags
다음의 플래그를 지정할 수 있다.
DPNENUMSERVICEPROVIDERS_ALL
어플리케이션으로 이용할 수 없는 프로바이더나, 디바이스가 인스톨되어 있지 않은 프로바이더를 포함해 시스템에 대해서 등록되어 모든 서비스 프로바이더를 열거한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM

주의

pguidServiceProvider 파라미터에 NULL 를 지정해 최초로 이 메소드를 호출해, 시스템으로 이용 가능한 베이스 서비스 프로바이더를 결정한다. pguidServiceProvider 에 서비스 프로바이더 GUID 에의 포인터를 건네주는 것으로, 서비스 프로바이더용의 특정의 디바이스를 취득할 수 있다. 이것은, 예를 들어, Microsoft® DirectPlay® 서비스 프로바이더의 모뎀 접속을 사용하는 경우 등에 편리하다. dial out에는 다양한 모뎀을 선택해, 호스트에게는 특정의 모뎀을 선택할 수 있다.

pEnumData 버퍼에서는 요구된 서비스 프로바이더 정보를 보관 유지하는 용량이 부족하는 경우, 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. cbEnumData 파라미터에는 필요한 버퍼 사이즈가 포함된다. 보통, 제일이야 있고 방법은 길이 0 의 버퍼로 한 번 메소드를 호출해, 필요한 사이즈를 판단하는 것이다. 다음에, 버퍼를 적절한 사이즈로 해 한번 더 메소드를 호출한다.

보통의 경우, 이 메소드는, 어플리케이션을 사용할 수 있는 서비스 프로바이더만을 돌려준다. 예를 들어, IPX 네트워킹 프로토콜이 인스톨되어 있지 않은 경우, DirectPlay 는 IPX 서비스 프로바이더를 돌려주지 않는다. DirectPlay 가, 사용할 수 없는 프로바이더를 포함해 모든 서비스 프로바이더를 돌려주도록(듯이) 하려면 ,dwFlags 에 DPNENUMSERVICEPROVIDERS_ALL 플래그를 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::GetApplicationDesc

접속되고 있는 어플리케이션의 완전한 어플리케이션 기술을 취득한다.

HRESULT GetApplicationDesc(
DPN_APPLICATION_DESC *const pAppDescBuffer,
DWORD *const pcbDataSize,
const DWORD dwFlags
);

파라미터

pAppDescBuffer
어플리케이션의 기술 데이터가 기입해지는 DPN_APPLICATION_DESC 구조체에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. pAppDescBuffer 가 NULL 로 설정되어 있지 않은 경우,pAppDescBuffer. dwSize 멤버에 적절한 값을 설정해야 한다. pcbDataSize 파라미터는, 데이터의 보관 유지에 필요한 사이즈로 설정된다.
pcbDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 DWORD 형의 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 세션 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우, 이 메소드는 에러값 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 버퍼 사이즈가 설정된다. 이 파라미터가 NULL 의 경우, 메소드는 DPNERR_INVALIDPARAM 를 돌려준다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

주의

pvData 파라미터에 NULL 를 건네주어 최초로 이 메소드를 호출해, 필요한 버퍼 사이즈를 취득한다. 2 번째에 이 메소드를 호출해 버퍼에 데이터를 저장 하면나무는, 구조체의 dwSize 멤버를 적절한 값으로 설정한다.

돌려주어진 DPN_APPLICATION_DESC 구조체에는,guidInstance,guidApplication, 및 pwszSessionName 멤버가 설정되어 있다. 이 안에는, 세션에 접속되고 있는 것 외의 클라이언트에 관한 정보는 포함되지 않았다. 이러한 정보는, 서버 어플리케이션만을 취득할 수 있다. 특히,dwCurrentPlayers 멤버는 반드시 0 으로 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::GetCaps

현재의 인터페이스의 DPN_CAPS 구조체를 취득한다.

HRESULT GetCaps(
DPN_CAPS *const pdpCaps,
const DWORD dwFlags
);

파라미터

pdpnCaps
Caps 정보를 받는 DPN_CAPS 구조체에의 포인터. 이 구조체의 dwSize 멤버를, 적절한 값으로 설정해야 한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::GetConnectionInfo

로컬 클라이언트와 서버와의 접속에 관한 통계 정보를 취득한다.

HRESULT GetConnectionInfo(
DPN_CONNECTION_INFO *const pdnConnectInfo,
const DWORD dwFlags
);

파라미터

pdnConnectInfo
지정된 접속에 관한 정보를 취득하는 DPN_CONNECTION_INFO 구조체에의 포인터. 이 구조체의 dwSize 멤버를, 적절한 값으로 설정해야 한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

Connect 의 호출이 성공한 후에게만, 이 메소드를 호출할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::GetSendQueueInfo

어플리케이션으로 송신 큐의 사이즈를 감시하기 위해서 사용한다. Microsoft® DirectPlay® 에서는, 수취하는 측의 컴퓨터의 처리 속도보다 고속으로 메세지를 송신할 것은 없다. 그 때문에, 송신원의 컴퓨터가, 송신지가 받아들이는 속도보다 고속으로 메세지를 송신했을 경우, 메세지는 송신측의 큐에 축적된다. 어플리케이션에 의해, 송신 큐의 사이즈가 너무 크면(자) 등록되었을 경우는, 메세지의 송신 레이트를 저하시킬 필요가 있다.

HRESULT GetSendQueueInfo(
DWORD *const pdwNumMsgs,
DWORD *const pdwNumBytes,
const DWORD dwFlags
);

파라미터

pdwNumMsgs
현재 큐에 축적되고 있는 메세지의 수를 보관 유지하는 DWORD 형의 변수에의 포인터. 이 값은 옵션이며, NULL 로 설정할 수 있다.
pdwNumBytes
현재 큐에 축적되고 있는 메세지 데이터의 총바이트수를 지정하는 DWORD 형의 변수에의 포인터. 이 값은 옵션이며, NULL 로 설정할 수 있다.
dwFlags
DPNGETSENDQUEUEINFO_PRIORITY_NORMAL, DPNGETSENDQUEUEINFO_PRIORITY_HIGH, 또는 DPNGETSENDQUEUEINFO_PRIORITY_LOW 플래그를 지정해, 그 우선 순위를 가지는 특정의 메세지에 대해 문의할 수가 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_INVALIDPARAM

주의

pdwNumMsgs 와 pdwNumBytes 의 양쪽 모두를 NULL 로 설정할 수 없다. 적어도 어느쪽이든 1 개(살)은 유효한 포인터로 설정할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::GetServerAddress

세션의 서버의 주소를 취득한다.

HRESULT GetServerAddress(
IDirectPlay8Address **const ppAddress,
const DWORD dwFlags
);

파라미터

ppAddress
서버의 주소를 지정하는 IDirectPlay8Address 오브젝트에의 포인터에의 주소. 이 오브젝트는, 불필요하게 되면(자) 해방해야 한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::GetServerInfo

IDirectPlay8Server::SetServerInfo 메소드의 호출에 의해 설정된 서버의 데이터 세트를 취득한다.

HRESULT GetServerInfo(
DPN_PLAYER_INFO *const pdpnPlayerInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

파라미터

pdpnPlayerInfo
서버의 정보를 저장 하는 DPN_PLAYER_INFO 구조체에의 포인터. pdwSize 가 NULL 로 설정되어 있지 않은 경우,pdpnPlayerInfo. dwSize 에 DPN_PLAYER_INFO 구조체의 사이즈를 지정해야 한다.
pdwSize
pdpnPlayerInfo 파라미터에 돌려주어지는 데이터의 사이즈를 보관 유지하는 DWORD 형의 변수에의 포인터. 이 값이 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 버퍼 사이즈가 설정된다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM

주의

이 메소드는, 서버가 정보를 갱신한 것을 나타내는, DPN_MSGID_SERVER_INFO 메세지를 클라이언트가 받은 다음에 호출한다.

Microsoft® DirectPlay® 는 DPN_PLAYER_INFO 구조체와 연속하는 버퍼에 있는, 이 구조체의 pwszName 멤버와 pvData 멤버에 할당할 수 있었던 포인터를 돌려준다. 이 2 개의 포인터가 설정되는 경우, 구조체에 가세해 2 개의 포인터에도 충분한 메모리를 할당해 둘 필요가 있다. 이 메소드를 사용하는 가장 확실한 방법은, 처음은 pdwSize 를 NULL 로 설정해 이 메소드를 호출하는 것이다. 메소드가 돌아오면(자),pcAddress 가 필요한 값을 포인트 한다. 메소드가 돌아오면(자),pdwSize 가 올바른 값을 포인트 하고 있다. 그 값을 사용해 구조체의 메모리를 재할인 맞히고 해, 한번 더 메소드를 호출해 정보를 취득한다.

메소드가 돌아오면(자), 대응하는 포인터가 NULL 로 설정되어 있는 경우에서도,DPN_PLAYER_INFO 구조체의 dwInfoFlags 멤버에는 항상 DPNINFO_DATA 플래그와 DPNINFO_NAME 플래그가 설정되어 있다. 이러한 플래그는 IDirectPlay8Server::SetServerInfo 를 호출하면나무에 사용되어 DirectPlay 로 변경된 값을 통지한다.

IDirectPlay8Server::SetServerInfo 메소드를 사용 하면 처리에 부담이 가기 (위해)때문에, 비정적 정보는 IDirectPlay8Server::SendTo 메소드를 사용해 전송 하는 것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::GetSPCaps

지정된 서비스 프로바이더의 DPN_SP_CAPS 구조체를 취득한다.

HRESULT GetSPCaps(
const GUID *const pguidSP,
DPN_SP_CAPS *const pdpnSPCaps,
const DWORD dwFlags
);

파라미터

pguidSP
정보를 취득하고 싶은 서비스 프로바이더를 지정하는 GUID 에의 포인터.
pdpnSPCaps
지정한 서비스 프로바이더에 관한 정보를 받는 DPN_SP_CAPS 구조체에의 포인터. pdpnSPCaps. dwSize 멤버를 DPN_SP_CAPS 구조체의 사이즈로 설정해야 한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

이 메소드는, 지정한 서비스 프로바이더에 관한 정보를 취득한다. Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::Initialize

IDirectPlay8Client 인터페이스 및 서버로부터 메세지를 수신하는, 클라이언트의 코드내의 엔트리 포인트를 등록한다. 이 메소드를 호출하고 나서, 이 인터페이스의 그 외의 메소드를 호출할 필요가 있다.

HRESULT Initialize(
PVOID const pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
const DWORD dwFlags
);

파라미터

pvUserContext
메세지 핸들러의 호출로 지정되는, 유저 지정의 문맥값. 유저 문맥값을 지정 하면, 복수의 인터페이스로부터 공통의 메세지 핸들러에 송신된 메세지를 구별할 수 있다.
pfn
PFNDPNMESSAGEHANDLER 콜백 함수에의 포인터. 이 함수는, 서버로부터의 모든 메세지를 수신해,IDirectPlay8Client 인터페이스로부터의 세션의 변경 통지를 수신한다.
dwFlags
다음의 플래그를 지정할 수 있다.
DPNINITIALIZE_DISABLEPARAMVAL
현재의 오브젝트에 대한 파라미터의 유효 확인을 무효로 한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

주의

CoCreateInstance 를 사용해 IDirectPlay8Client 인터페이스를 취득한 후, 우선 이 메소드를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::RegisterLobby

기동한 어플리케이션이, 게임 상태를 자동적으로 로비에 전달할 수 있도록(듯이) 한다.

HRESULT RegisterLobby(
const DPNHANDLE dpnHandle,
IDirectPlay8LobbiedApplication *const pIDP8LobbiedApplication,
const DWORD dwFlags
);

파라미터

dpnHandle
IDirectPlay8LobbiedApplication::UpdateStatus 를 호출하면나무에 사용하는 접속 핸들.
pIDP8LobbiedApplication
어플리케이션을 지정하는 IDirectPlay8LobbiedApplication 오브젝트에의 포인터.
dwFlags
다음의 플래그의 어느쪽이든을 지정한다.
DPNLOBBY_REGISTER
로비를 어플리케이션에 등록한다.
DPNLOBBY_UNREGISTER
어플리케이션에의 로비의 등록을 해제한다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::ReturnBuffer

DPN_MSGID_RECEIVE 시스템 메세지의 pReceiveData 멤버에 의해 어플리케이션에 제공된 메세지 버퍼를 취득한다. 유저의 메세지 핸들러가 RECEIVE 콜백에 DPNSUCCESS_PENDING 를 돌려주었을 경우, 버퍼의 소유권은 어플리케이션으로 이행했다고 보여져 이 호출에 의해 소유권이 Microsoft® DirectPlay® 에 돌아올 때까지 소유권의 해방이나 변경은 행해지지 않는다.

HRESULT ReturnBuffer(
const DPNHANDLE hBufferHandle,
const DWORD dwFlags
);

파라미터

hBufferHandle
메세지용의 버퍼 핸들을 지정하는 DPNHANDLE 형의 변수. 이것은,DPNMSG_RECEIVE 시스템 메세지의 hBufferHandle 멤버로 취득한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::Send

데이터를 서버에 전송 한다. 메세지는 동기 또는 비동기에 송신할 수가 있다.

HRESULT Send(
const DPN_BUFFER_DESC *const pBufferDesc,
const DWORD cBufferDesc,
const DWORD dwTimeOut,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

pBufferDesc
송신하는 데이터를 기술하는 DPN_BUFFER_DESC 구조체에의 포인터.
cBufferDesc
pBufferDesc 가 가리키는 DPN_BUFFER_DESC 구조체의 수. 이 버젼의 Microsoft® DirectPlay® 에서는, 버퍼는 1 개가 아니면 안된다.
dwTimeOut
메세지의 송신을 기다리는 시간 (밀리 세컨드 단위). 메세지가 dwTimeOut 값으로 송신되어 있지 않은 경우, 메세지는 송신되지 않는다. 메세지의 송신에 대해서 타임 아웃이 필요하지 않은 경우는, 이 파라미터를 0 으로 설정한다.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_SEND_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
DPNHANDLE. 메소드가 돌아오면(자),phAsyncHandle 는,IDirectPlay8Client::CancelAsyncOperation 에 건네주어 처리를 취소할 수가 있는 핸들을 포인트 한다. dwFlags 에 DPNSEND_SYNC 플래그가 설정되어 있는 경우, 이 파라미터는 NULL 로 설정해야 한다.
dwFlags
송신 동작을 기술하는 플래그. 다음의 1 개 이상의 플래그를 설정할 수가 있다.
DPNSEND_SYNC
Send 요구를 동기를 잡으면서 처리한다.
DPNSEND_NOCOPY
DPN_BUFFER_DESC 구조체의 데이터를 사용해, 내부 카피는 실시하지 않는다. 서버에 데이터를 송신하는 방법으로서는 효율적이 되는 일이 있다. 그러나, 수신측이 메세지를 처리하기 전에, 송신측이 메세지를 변경할 수 있기 (위해)때문에, 견뢰한 것은 없어진다. 이 플래그를 DPNSEND_NOCOMPLETE 와 조합할 수 없다.
DPNSEND_NOCOMPLETE
메세지 핸들러에 DPN_MSGID_SEND_COMPLETE 를 송신하지 않는다. 이 플래그를 DPNSEND_NOCOPY 또는 DPNSEND_GUARANTEED 와 함께 사용할 수 없다. 또, 이 플래그를 사용하는 경우,pvAsyncContext 는 NULL 가 아니면 안된다.
DPNSEND_COMPLETEONPROCESS
메세지 가 타겟으로 전달되어 메세지의 수신을 나타내는 타겟의 메세지 핸들러가 돌려주어질 때,DPN_MSGID_SEND_COMPLETE 를 메세지 핸들러에 송신한다. 이 플래그가 설정되었을 경우는, 여분의 내부 메세지의 오버헤드가 있어, 메세지의 송신 처리가 현저하게 저하할 가능성이 있다. 이 플래그를 설정했을 경우는, DPNSEND_GUARANTEED 도 설정할 필요가 있다.
DPNSEND_GUARANTEED
보증 첨부 전달 방식을 사용해 메세지를 송신한다.
DPNSEND_PRIORITY_HIGH
메세지의 우선 순위를 높게 설정한다. 이 플래그는, DPNSEND_PRIORITY_LOW 와 함께 사용할 수 없다.
DPNSEND_PRIORITY_LOW
메세지의 우선 순위를 낮게 설정한다. 이 플래그는, DPNSEND_PRIORITY_HIGH 와 함께 사용할 수 없다.
DPNSEND_NOLOOPBACK
자신에게 송신하는 경우, 메세지 핸들러에DPN_MSGID_RECEIVE 시스템 메세지를 송신하지 않는다.
DPNSEND_NONSEQUENTIAL
이 플래그를 설정하지 않는 경우, 메세지는 송신순서에 타겟 어플리케이션에 전달된다. 따라서, 순서 대로가 아닌 메세지는, 결핍 하고 있는 메세지가 도착할 때까지 버퍼에 저장 할 필요가 있다. 이 플래그를 설정 하면, 메세지는 수신순서에 타겟 어플리케이션에 전달된다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_TIMEDOUT

주의

이 메소드는, 서버의 메세지 핸들러에 DPN_MSGID_RECEIVE 시스템 메세지를 생성한다. 데이터 버퍼는, 관련지을 수 있고 있는 구조체의 pReceiveData 멤버에 보관 유지되고 있다.

메세지에는, 저, 보통, 고의 3 개의 우선 순위의 어느쪽이든을 설정할 수 있다. dwFlags 메세지에 낮은 우선 순위 또는 높은 우선 순위를 지정하려면 dwFlags 에 적절한 플래그를 설정한다. 어느 쪽의 우선 순위 플래그도 설정하지 않았던 경우, 메세지는 보통의 우선 순위가 된다. 송신 우선 순위의 상세한 것에 대하여는, 「네트워킹의 기본」을 참조할것.

Send 요구가 완료 하면, 송신측의 메세지 핸들러에 DPN_MSGID_SEND_COMPLETE 시스템 메세지가 송신된다. 요구의 성공 또는 실패는, 관련지을 수 있었던 구조체의 hResultCode 멤버에 보관 유지된다. dwflags 에 DPN_NOCOMPLETE 플래그를 설정 하면, 송신 완료의 시스템 메세지는 송신되지 않는다.

보통, 메세지가 송신되면(자) 즉시, 송신 완료가 송신원의 컴퓨터에 송신된다. 바꾸어 말하면(자), 송신 완료는, 메세지가 타겟상에서 처리된 것을 반드시 의미하지 않는다. 메세지는 아직 큐내에 있을 가능성도 있다. 메세지가 타겟으로 처리된 것을 확인하려면 ,dwFlags 에 DPN_COMPLETEONPROCESS 플래그를 설정한다. 이 플래그를 설정 하면, 타겟의 메세지 핸들러가 메세지를 처리해 돌아올 때까지, 송신 완료는 송신되지 않는다.

어플리케이션은 IDirectPlay8Client,IDirectPlay8Server, 또는 IDirectPlay8Peer 로 Close 를 호출하기 전이나 최종 릴리스를 하기 전에,CancelAsyncOperation 를 호출해 남아 있는 Send 를 캔슬해야 한다. 거기에 실패 하면 예기치 못한 결과가 일어난다.

주 메소드가 돌아올 때까지는, 데이터 버퍼등의 리소스가 유효한 상태인 채이다고 봐서는 안 된다. 이 메소드를 비동기에게 호출하는 경우, 호출이 돌아오기 전에 DPN_MSGID_SEND_COMPLETE 메세지를 받아들여, 메세지 핸들러가 처리해 버리는 일이 있다. 메세지 핸들러가 데이터 버퍼등의 리소스를 할당 해제, 또는 무효로 했을 경우, 메소드가 불려 간 다음에 리소스가 무효가 되는 일이 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::SetCaps

현재의 인터페이스의 DPN_CAPS 구조체를 설정한다.

HRESULT SetCaps(
const DPN_CAPS *const pdpCaps,
const DWORD dwFlags
);

파라미터

pdpCaps
현재의 인터페이스에 관한 정보의 설정에 사용되는 DPN_CAPS 구조체에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

주의

이 메소드는, 지정된 서비스 프로바이더에 대한 파라미터를 설정한다. Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::SetClientInfo

클라이언트와 어플리케이션과의 정적 설정을 설정한다. 어플리케이션에 기본적인 플레이어 정보를 전송 하려면 , 접속전에 이 메소드를 호출한다. 클라이언트가 올바르게 어플리케이션에 접속 하면, 서버는 이 메소드로 취득된 정보를 IDirectPlay8Server::GetClientInfo 메소드를 호출해 취득할 수 있다.

HRESULT SetClientInfo(
const DPN_PLAYER_INFO *const pdpnPlayerInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

pdpnPlayerInfo
설정하는 클라이언트 정보를 보관 유지하는 DPN_PLAYER_INFO 구조체에의 포인터.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNSETCLIENTINFO_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 요구가 비동기에 처리되는 경우, 메소드가 즉시 처리되면(자), S_OK 를 돌려주는 경우가 있다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_NOCONNECTION
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

주의

이 메소드는, 세션중 언제라도 호출할 수가 있다.

IDirectPlay8Client::SetClientInfo 메소드를 사용 하면 처리에 부담이 가기 (위해)때문에, 비정적 정보는 IDirectPlay8Client::Send 메소드를 사용해 전송 하는 것.

어플리케이션에의 접속 후, 이 메소드를 사용해 클라이언트 정보를 변경할 수 있다. 접속 후에 이 메소드를 호출하면, 데이터의 갱신을 알리는 DPN_MSGID_CLIENT_INFO 시스템 메세지가 모든 플레이어에 대해서 생성된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Client::SetSPCaps

지정된 서비스 프로바이더의 DPN_SP_CAPS 구조체를 설정한다.

HRESULT SetSPCaps(
const GUID *const pguidSP,
constDPN_SP_CAPS *const pdpnSPCaps
);

파라미터

pguidSP
정보를 설정하는 서비스 프로바이더를 지정하는 GUID 에의 포인터.
pdpnSPCaps
지정한 서비스 프로바이더에 관한 정보를 설정하는 DPN_SP_CAPS 구조체에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

이 메소드는, 지정된 서비스 프로바이더에 대한 파라미터를 설정한다. Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다. 현재, 이 호출에서는 dwNumThreads 멤버만 설정할 수가 있다. dwFlags 는 0 이 아니면 안된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server

어플리케이션은,IDirectPlay8Server 인터페이스의 메소드를 사용해, Microsoft® DirectPlay® 의 클라이언트/서버 트랜스폴트 세션의 생성과 관리를 실시한다.

IDirectPlay8Server 인터페이스의 메소드는, 다음과 같이 분류할 수 있다.

세션 관리 | Close
 | EnumServiceProviders
 | GetApplicationDesc
 | GetCaps
 | GetSPCaps
 | GetSendQueueInfo
 | Host
 | Initialize
 | ReturnBuffer
 | SendTo
 | SetApplicationDesc
 | SetCaps
 | SetServerInfo
 | SetSPCaps
클라이언트 관리 | DestroyClient
 | GetClientInfo
 | GetPlayerContext
그룹 관리 | AddPlayerToGroup
 | CreateGroup
 | DestroyGroup
 | EnumPlayersAndGroups
 | EnumGroupMembers
 | GetGroupContext
 | GetGroupInfo
 | RemovePlayerFromGroup
 | SetGroupInfo
그 외 | CancelAsyncOperation
 | GetClientAddress
 | GetConnectionInfo
 | GetLocalHostAddresses
 | RegisterLobby

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::AddPlayerToGroup

그룹에 클라이언트를 추가한다. 클라이언트가 그룹에 올바르게 추가된 후, 그룹에 송신되는 모든 메세지가 클라이언트에 송신된다.

HRESULT AddPlayerToGroup(
const DPNID idGroup,
const DPNID idClient,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

idGroup
그룹에 추가하는 클라이언트의 식별자를 지정하는 DPNID 형의 변수.
idClient
그룹에 추가하는 클라이언트의 식별자를 지정하는 DPNID 형의 변수.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNADDPLAYERTOGROUP_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP
DPNERR_INVALIDPLAYER

주의

서버는, 서버 자체 또는 클라이언트를 기존의 그룹에 추가할 수 있다. 플레이어가 그룹에 올바르게 추가되면(자), 그룹에 보내진 모든 메세지를 플레이어도 받는다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::CancelAsyncOperation

비동기의 요구를 취소한다. 디폴트에서는,IDirectPlay8Server 인터페이스가 많은 메소드가 비동기에게 실행된다. 상황에 따라, 요구가 처리되기 전에 그 요구를 취소하고 싶은 경우도 있다. 이 인터페이스로 비동기에게 실행할 수 있는 모든 메소드는,hAsyncHandle 파라미터를 돌려준다.

요구의 hAsyncHandle 를 이 메소드의 hAsyncHandle 파라미터에 건네주는 것에 의해, 특정의 요구가 삭제된다. 이 메소드를 호출해,hAsyncHandle 파라미터에 NULL 를,dwFlags 파라미터에 DPNCANCEL_ALL_OPERATIONS 를 지정하는 것에 의해, 대기중의 모든 비동기 처리를 취소할 수가 있다. 특정의 핸들이 이 메소드로 지정되었을 경우는, 어느 플래그도 설정해서는 안 된다.

HRESULT CancelAsyncOperation(
const DPNHANDLE hAsyncHandle,
const DWORD dwFlags
);

파라미터

hAsyncHandle
비동기 처리를 정지하는 핸들. 모든 요구 또는 특정의 종류의 비동기 요구를 정지하려면 , 이 값을 NULL 로 한다. 취소하는 요구에 특정의 핸들이 지정되고 있는 경우,dwFlags 파라미터는 0 으로 설정한다. 이 핸들은, 비동기 처리를 지원 하는 메소드를 호출했을 때에 받는다.
dwFlags
취소하는 비동기 요구를 지정하는 플래그. 다음의 몇개의 플래그를 설정할 수 있다.
DPNCANCEL_SEND
비동기 IDirectPlay8Server::SendTo 요구를 취소한다.
DPNCANCEL_ALL_OPERATIONS
모든 비동기 요구를 취소한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_CANNOTCANCEL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNSUCCESS_PENDING

주의

이 메소드를 사용해,IDirectPlay8Server::SendTo 메소드의 비동기 처리를 취소할 수가 있다. Microsoft® DirectPlay® 8.0 은, 다른 비동기 처리의 취소를 지원 하고 있지 않다.

IDirectPlay8Server::SendTo 메소드로부터 돌려주어진 핸들을 지정 하면,Send 요구를 취소할 수가 있다. 그 경우도,DPN_MSGID_SEND_COMPLETE 시스템 메세지는, DPNSEND_NOCOMPLETE 플래그를 설정하지 않고 송신된 비동기 Send 요구 마다, 어플리케이션 메세지 핸들러에 송신된다. 이 메소드로 삭제된 센드 요구는,DPN_MSGID_SEND_COMPLETE 메세지의 hResultCode 멤버에 DPNERR_USERCANCEL 를 돌려준다.

dwFlags 에 DPNCANCEL_ALL_OPERATIONS 또는 DPNCANCEL_SEND 플래그를 설정했을 경우, DirectPlay 는 모든 일치하는 처리를 취소하려고 한다. 이 메소드는, 취소해에 실패한 처리가 있는 경우, 일부의 취소가 성공하고 있어도 에러를 돌려준다.

주 이 메소드가 값을 돌려줄 때까지, 완료 메세지는 도착하지 않는 경우가 있다. DPN_MSGID_SEND_COMPLETE, DPN_MSGID_CONNECT_COMPLETE,또는 DPN_MSGID_ASYNC_OP_COMPLETE 메세지를 받아들일 때까지, 처리가 종료했다고 봐서는 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::Close

세션에 의해 열린 접속을 닫는다.

HRESULT Close(
const DWORD dwFlags
);

파라미터

dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_UNINITIALIZED

주의

이 메소드는,IDirectPlay8Server::Initialize 로 정상적으로 초기화된 오브젝트의 모두로 불려 가지 않으면 안 된다.

이것은,IDirectPlay8Server::Host 에 대응하는 메소드이다. 서버에 호스트 떠날 수 있어 모든 액티브한 네트워크 접속을 닫는다. 이 메소드는 동기 메소드이며, 서버가 모든 DPN_MSGID_DESTROY_PLAYER 메세지를 처리할 때까지 돌아오지 않는다. 이 기능에 의해,Close 가 돌아오면 서버 어플리케이션을 안전하게 슛다운 할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::CreateGroup

현재의 세션에 그룹을 생성 한다. 이 메소드가 불려 가면(자), 서버의 메세지 핸들러가 DPN_MSGID_CREATE_GROUP 메세지를 받아들인다.

주 멀티 캐스팅은 이 릴리스에서는 지원되어 있지 않다.

HRESULT CreateGroup(
const DPN_GROUP_INFO *const pdpnGroupInfo,
VOID *const pvGroupContext,
VOID *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

pdpnGroupInfo
그룹의 기술을 보관 유지하는 DPN_GROUP_INFO 구조체에의 포인터.
pvGroupContext
그룹의 문맥값에의 포인터. 이 값은, 로컬 어플리케이션의 메세지 핸들러가 DPN_MSGID_CREATE_GROUP 메세지를 처리할 경우에 사전으로 설정된다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNCREATEGROUP_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS

주의

Microsoft® DirectPlay® 는, 계층 그룹을 보관 유지하지 않는다. 이것은, 이러한 그룹이 플랫 그룹과 그룹 데이터의 활용에 의해 간단하게 이행 할 수 있기 때문에 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::DestroyClient

세션으로부터 클라이언트를 삭제한다.

HRESULT DestroyClient(
const DPNID dpnidClient,
const VOID *const pDestroyInfo,
const DWORD dwDestroyInfoSize,
const DWORD dwFlags
);

파라미터

dpnidClient
삭제하는 클라이언트의 식별자를 지정하는 DPNID 형의 변수.
pDestroyInfo
추가의 삭제 데이터 정보를 기술하는 포인터.
dwDestroyInfoSize
pDestroyInfo 파라미터에 보관 유지되는 데이터의 사이즈를 지정하는 DWORD 형의 변수.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_NOTHOST

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::DestroyGroup

IDirectPlay8Server::CreateGroup 메소드에 의해 생성 된 그룹을 삭제한다.

HRESULT DestroyGroup(
const DPNID idGroup,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

idGroup
삭제하는 그룹의 DPNID.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNDESTROYGROUP_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::EnumPlayersAndGroups

어플리케이션의 모든 플레이어 또는 그룹의 식별자, 혹은 그 양쪽 모두의 식별자의 일람을 취득한다.

HRESULT EnumPlayersAndGroups(
DPNID *const prgdpnid,
DWORD *const pcdpnid,
const DWORD dwFlags
);

파라미터

prgdpnid
세션의 그룹 또는 플레이어의 식별자, 혹은 그 양쪽 모두가 데이터로서 저장 되는 배열에의 포인터.
pcdpnid
prgdpnid 파라미터에 보관 유지되는 식별자의 수를 지정하는 DWORD 형의 변수에의 포인터. 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 엔트리의 수가 설정된다.
dwFlags
열거의 동작을 기술하는 플래그. 다음의 1 개 또는 양쪽 모두의 플래그를 설정할 수가 있다.
DPNENUM_PLAYERS
플레이어의 식별자의 리스트를 돌려준다.
DPNENUM_GROUPS
그룹의 식별자의 리스트를 돌려준다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS

주의

그룹 및 플레이어의 정보는 빈번하게 변화하기 위해(때문에), 돌려주어지는 필요한 버퍼 사이즈는 이후의 호출로 바뀌는 경우가 있다. 메소드가 성공할 때까지, 버퍼를 확인해, 재할인 맞히고 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::EnumGroupMembers

그룹내의 모든 플레이어의 일람을 취득한다.

HRESULT EnumGroupMembers(
const DPNID dpnid,
DPNID *const prgdpnid,
DWORD *const pcdpnid,
const DWORD dwFlags
);

파라미터

dpnid
열거하는 플레이어를 보관 유지하는 그룹을 지정하는 DPNID 형의 변수.
prgdpnid
그룹의 플레이어의 식별자를 저장 하는 배열에의 포인터.
pcdpnid
prgdpnid 파라미터에 플레이어의 식별자의 수를 보관 유지하는 DWORD 형의 변수에의 포인터. 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 엔트리의 수가 설정된다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::EnumServiceProviders

어플리케이션으로 이용 가능한 등록이 끝난 서비스 프로바이더를 열거한다.

HRESULT EnumServiceProviders(
const GUID *const pguidServiceProvider,
const GUID *const pguidApplication,
DPN_SERVICE_PROVIDER_INFO *const pSPInfoBuffer,
PDWORD const pcbEnumData,
PDWORD const pcReturned
const DWORD dwFlags
);

파라미터

pguidServiceProvider
서비스 프로바이더를 지정하는 GUID 형의 변수에의 포인터. 이 옵션 파라미터는, 지정한 서비스 프로바이더의 서브 디바이스를 열거시킨다. 보통은 이 값에 NULL 를 설정해, 모든 이용 가능한 서비스 프로바이더를 열거한다.
pguidApplication
어플리케이션을 지정하는 GUID 형의 변수에의 포인터. 이 파라미터에 포인터가 건네받았을 경우는, 어플리케이션에 접속할 수 있는 서비스 프로바이더만이 열거된다. NULL 를 건네주어, 시스템에 등록을 마친 서비스 프로바이더를 열거할 수도 있다.
pSPInfoBuffer
서비스 프로바이더 정보를 보관 유지하는,DPN_SERVICE_PROVIDER_INFO 구조체의 배열에의 포인터.
pcbEnumData
버퍼가 너무 작은 경우,pEnumData 버퍼의 사이즈가 저장 되는 DWORD 에의 포인터.
pcReturned
pEnumData 배열에 돌려주어지는 DPN_SERVICE_PROVIDER_INFO 구조체의 수를 지정하는 DWORD 형의 변수에의 포인터.
dwFlags
다음의 플래그를 지정할 수 있다.
DPNENUMSERVICEPROVIDERS_ALL
어플리케이션으로 이용할 수 없는 프로바이더나, 디바이스가 인스톨되어 있지 않은 프로바이더를 포함해 시스템에 대해서 등록되어 모든 서비스 프로바이더를 열거한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM

주의

pguidServiceProvider 파라미터에 NULL 를 지정해 최초로 이 메소드를 호출해, 시스템으로 이용 가능한 베이스 서비스 프로바이더를 결정한다. pguidServiceProvider 에 특정의 서비스 프로바이더 GUID 에의 포인터를 건네주는 것으로, 서비스 프로바이더용의 디바이스를 취득할 수 있다. 이것은, 예를 들어, Microsoft® DirectPlay® 서비스 프로바이더의 모뎀 접속을 사용하는 경우 등에 편리하다. dial out에는 다양한 모뎀을 선택해, 호스트에게는 특정의 모뎀을 선택할 수 있다.

pEnumData 버퍼에서는 요구된 서비스 프로바이더 정보를 보관 유지하는 용량이 부족하는 경우, 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. cbEnumData 파라미터에는 필요한 버퍼 사이즈가 포함된다. 보통, 제일이야 있고 방법은 길이 0 의 버퍼로 한 번 메소드를 호출해, 필요한 사이즈를 판단하는 것이다. 다음에, 버퍼를 적절한 사이즈로 해 한번 더 메소드를 호출한다.

보통의 경우, 이 메소드는, 어플리케이션을 사용할 수 있는 서비스 프로바이더만을 돌려준다. 예를 들어, IPX 네트워킹 프로토콜이 인스톨되어 있지 않은 경우, DirectPlay 는 IPX 서비스 프로바이더를 돌려주지 않는다. DirectPlay 가, 사용할 수 없는 프로바이더를 포함해 모든 서비스 프로바이더를 돌려주도록(듯이) 하려면 ,dwFlags 에 DPNENUMSERVICEPROVIDERS_ALL 플래그를 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetApplicationDesc

접속되고 있는 어플리케이션의 어플리케이션 기술 전체를 취득한다.

HRESULT GetApplicationDesc(
DPN_APPLICATION_DESC *const pAppDescBuffer,
DWORD *const pcbDataSize,
const DWORD dwFlags
);

파라미터

pAppDescBuffer
어플리케이션의 기술 데이터가 기입해지는 DPN_APPLICATION_DESC 구조체에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. pAppDescBuffer 가 NULL 로 설정되어 있지 않은 경우,pAppDescBuffer. dwSize 멤버에 적절한 값을 설정해야 한다. pcbDataSize 파라미터는, 데이터의 보관 유지에 필요한 사이즈로 설정된다.
pcbDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 DWORD 형의 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 세션 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우, 이 메소드는 에러값 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 버퍼 사이즈가 설정된다. 이 파라미터가 NULL 의 경우, 메소드는 DPNERR_INVALIDPARAM 를 돌려준다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

주의

pvData 파라미터에 NULL 를 건네주어 최초로 이 메소드를 호출해, 필요한 버퍼 사이즈를 취득한다. 2 번째에 이 메소드를 호출해 버퍼에 데이터를 저장 하면나무는, 구조체의 dwSize 멤버를 적절한 값으로 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetCaps

현재의 인터페이스의 DPN_CAPS 구조체를 취득한다.

HRESULT GetCaps(
DPNCAPS *const pdpnCaps,
const DWORD dwFlags
);

파라미터

pdpnCaps
Caps 정보를 받는 DPN_CAPS 구조체에의 포인터. 이 구조체의 dwSize 멤버를 적절한 값으로 설정해야 한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetClientAddress

세션내의 지정된 플레이어의 주소를 취득한다.

HRESULT GetClientAddress(
const DPNID dpnid,
IDirectPlay8Address **const pAddress,
const DWORD dwFlags
);

파라미터

dpnid
플레이어의 식별 정보를 지정하는 DPNID 형의 변수.
pAddress
클라이언트의 주소를 지정하는 IDirectPlay8Address 오브젝트에의 포인터에의 주소. 이 오브젝트는, 불필요하게 되면(자) 해방해야 한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

세션에의 접속에 사용할 수 있는 주소를 취득하려면 ,IDirectPlay8Server::GetLocalHostAddresses 메소드를 사용한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetClientInfo

지정된 클라이언트에 대해서 설정되어 있는 클라이언트 정보를 취득한다.

HRESULT GetClientInfo(
const DPNID dpnid,
DPN_PLAYER_INFO *const pdpnPlayerInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

파라미터

dpnid
정보를 취득하는 클라이언트의 식별자를 지정하는 DPNID 형의 변수.
pdpnPlayerInfo
클라이언트 정보를 저장 하는 DPN_PLAYER_INFO 구조체에의 포인터. pdwSize 가 NULL 로 설정되어 있지 않은 경우,pdpnPlayerInfo. dwSize 에 적절한 값을 설정해야 한다.
pdwSize
pdpnPlayerInfo 파라미터에 돌려주어지는 클라이언트 데이터의 사이즈를 보관 유지하는 DWORD 형의 변수에의 포인터. 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 을 돌려주어, 이 파라미터에는 요구된 버퍼의 사이즈가 들어간다.
dwFlags
클라이언트에 관해서 돌려주어지는 정보를 기술하는 플래그. 현재, 다음의 플래그의 양쪽 모두가 돌려주어진다.
DPNINFO_NAME
DPN_PLAYER_INFO 구조체는 클라이언트의 이름 세트를 보관 유지한다.
DPNINFO_DATA
DPN_PLAYER_INFO 구조체는 클라이언트의 데이터 세트를 보관 유지한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER

주의

서버가 어플리케이션으로부터 DPN_MSGID_CLIENT_INFO 메세지를 수신한 후, 이 메소드를 호출한다. 이 메세지는, 클라이언트가 정보를 갱신한 것을 나타낸다.

Microsoft® DirectPlay® 는 DPN_PLAYER_INFO 구조체와 연속하는 버퍼에 있는, 이 구조체의 pwszName 멤버와 pvData 멤버에 할당할 수 있었던 포인터를 돌려준다. 이 2 개의 포인터가 설정되는 경우, 구조체에 가세해 2 개의 포인터에도 충분한 메모리를 할당해 둘 필요가 있다. 이 메소드를 사용하는 가장 확실한 방법은, 처음은 pdwSize 를 0 으로 설정해 이 메소드를 호출하는 것이다. 메소드가 돌아오면(자),pdwSize 가 올바른 값을 포인트 하고 있다. 그 값을 사용해 구조체에 메모리를 할당해 한번 더 메소드를 호출해 정보를 취득한다.

메소드가 돌아오면(자), 대응하는 포인터가 NULL 로 설정되어 있는 경우에서도,DPN_PLAYER_INFO 구조체의 dwInfoFlags 멤버에는 항상 DPNINFO_DATA 플래그와 DPNINFO_NAME 플래그가 설정되어 있다. 이러한 플래그는 IDirectPlay8Client::SetClientInfo 를 호출하면나무에 사용되어 DirectPlay 로 변경된 값을 통지한다.

IDirectPlay8Client::SetPeerInfo 메소드를 사용 하면 처리에 부담이 가기 (위해)때문에, 비정적 정보는 IDirectPlay8Client::Send 메소드를 사용해 전송 하는 것.

플레이어는,IDirectPlay8Client::SetClientInfo 를 호출해 그 정보를 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetConnectionInfo

로컬 서버와 지정된 리모트 클라이언트와의 접속에 관한 통계 정보를 취득한다.

HRESULT GetConnectionInfo(
const DPNID dpnidEndPoint,
DPN_CONNECTION_INFO *const pdnConnectInfo,
const DWORD dwFlags
);

파라미터

dpnidEndPoint
접속 정보를 취득하는 플레이어의 DPNID.
pdnConnectInfo
지정된 접속에 관한 정보를 취득하는 DPN_CONNECTION_INFO 구조체에의 포인터. 이 구조체의 dwSize 멤버에 DPN_CONNECTION_INFO 구조체의 사이즈를 설정할 필요가 있다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

Host 의 호출이 성공한 후에게만, 이 메소드를 호출할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetGroupContext

그룹에 대한 그룹 문맥값을 취득한다.

HRESULT GetGroupContext(
const DPNID dpnid,
PVOID *const ppvGroupContext,
const DWORD dwFlags
);

파라미터

dpnid
그룹의 식별자를 지정하는 DPNID 형의 변수. 이 그룹의 문맥 데이터를 취득한다.
ppvGroupContext
그룹의 문맥값에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDGROUP
DPNERR_INVALIDPARAM

주의

그룹의 문맥값은,DPN_MSGID_CREATE_GROUP 시스템 메세지의 pvGroupContext 멤버를 문맥값의 데이터에 나타내는 것에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetGroupInfo

그룹명 등, 그룹에 관련지을 수 있고 있는 데이터 블록을 취득한다.

보통, 그룹 데이터가 변경된 것을 나타내는 DPN_MSGID_GROUP_INFO 시스템 메세지가 수신된 후, 이 메소드가 불려 간다.

HRESULT GetGroupInfo(
const DPNID dpnid,
DPN_GROUP_INFO *const pdpnGroupInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

파라미터

dpnid
데이터 블록을 취득하는 그룹의 식별자를 지정하는 DPNID 형의 변수.
pdpnGroupInfo
그룹 데이터를 기술하는 DPN_GROUP_INFO 구조체에의 포인터. pdwSize 가 NULL 로 설정되어 있지 않은 경우,pdpnGroupInfo. dwSize 에 DPN_GROUP_INFO 구조체의 사이즈를 설정할 필요가 있다.
pdwSize
데이터의 사이즈를 pdpnGroupInfo 파라미터에 돌려주는 DWORD 형의 변수에의 포인터. 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다. 이 파라미터에는, 필요한 사이즈가 설정된다.
dwFlags
그룹에 관해서 돌려주어지는 정보를 기술하는 플래그. 현재, 다음의 플래그의 양쪽 모두가 돌려주어진다.
DPNINFO_NAME
DPN_PLAYER_INFO 구조체는 클라이언트의 이름 세트를 보관 유지한다.
DPNINFO_DATA
DPN_PLAYER_INFO 구조체는 클라이언트의 데이터 세트를 보관 유지한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

주의

Microsoft® DirectPlay® 는 DPN_GROUP_INFO 구조체와 연속하는 버퍼에 있는, 이 구조체의 pwszName 멤버와 pvData 멤버에 할당할 수 있었던 포인터를 돌려준다. 이 2 개의 포인터가 설정되는 경우, 구조체에 가세해 2 개의 포인터에도 충분한 메모리를 할당해 둘 필요가 있다. 이 메소드를 사용하는 가장 확실한 방법은, 처음은 pdwSize 를 NULL 로 설정해 이 메소드를 호출하는 것이다. 메소드가 돌아오면(자),pdwSize 가 올바른 값을 포인트 하고 있다. 그 값을 사용해 구조체에 메모리를 할당해 한번 더 메소드를 호출해 정보를 취득한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetLocalHostAddresses

세션을 호스트 하기 위해서 사용되는 로컬 주소를 취득한다.

HRESULT GetLocalHostAddresses(
IDirectPlay8Address **const prgpAddress,
DWORD *const pcAddress,
constDWORD dwFlags
);

파라미터

prgpAddress
로컬 호스트 주소를 지정하는,IDirectPlay8Address 오브젝트의 배열에의 포인터의 주소. 이러한 오브젝트는 불필요하게 되면(자) 해방해야 한다. 해방하지 않았던 경우, 메모리 누수가 발생한다.
pcAddress
prgpAddress 가 포인트 하는 배열 로 유지할 수 있는 주소 오브젝트의 최대수. 버퍼가 너무 작은 경우, 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려주어,pcAddress 가 필요한 값으로 설정된다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

이 메소드를 사용하는 가장 확실한 방법은, 처음은 pcAddress 를 0 으로 설정해 이 메소드를 호출하는 것이다. 메소드가 돌아오면(자),pcAddress 가 필요한 값을 포인트 한다. 2 번째에 이 메소드를 호출하면나무는, 그 값을 사용해 정보를 취득한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetPlayerContext

클라이언트에 대한 플레이어 문맥값을 취득한다.

HRESULT GetPlayerContext(
const DPNID dpnid,
PVOID *const ppvPlayerContext,
const DWORD dwFlags
);

파라미터

dpnid
문맥 데이터를 취득하는 플레이어의 식별자를 지정하는 DPNID 형의 변수.
ppvPlayerContext
클라이언트의 문맥 데이터에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER

주의

플레이어의 문맥값은,DPN_MSGID_CREATE_PLAYER 시스템 메세지의 pvPlayerContext 멤버를 문맥값의 데이터에 나타내는 것에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetSendQueueInfo

어플리케이션으로 송신 큐의 사이즈를 감시하기 위해서 사용한다. Microsoft® DirectPlay® 에서는, 수취하는 측의 컴퓨터의 처리 속도보다 고속으로 메세지를 송신할 것은 없다. 그 때문에, 송신원의 컴퓨터가, 송신지가 받아들이는 속도보다 고속으로 메세지를 송신했을 경우, 메세지는 송신측의 큐에 축적된다. 어플리케이션에 의해, 송신 큐의 사이즈가 너무 크면(자) 등록되었을 경우는, 메세지의 송신 레이트를 저하시킬 필요가 있다.

HRESULT GetSendQueueInfo(
const DPNID dpnid,
DWORD *const pdwNumMsgs,
DWORD *const pdwNumBytes,
const DWORD dwFlags
);

파라미터

dpnid
송신 큐 정보를 취득하는 플레이어의 식별자를 지정하는 DPNID 형의 변수.
pdwNumMsgs
현재 큐에 축적되고 있는 메세지의 수를 보관 유지하는 DWORD 형의 변수에의 포인터. 이 값은 옵션이며, NULL 로 설정할 수 있다.
pdwNumBytes
현재 큐에 축적되고 있는 메세지 데이터의 총바이트수를 지정하는 DWORD 형의 변수에의 포인터. 이 값은 옵션이며, NULL 로 설정할 수 있다.
dwFlags
DPNGETSENDQUEUEINFO_PRIORITY_NORMAL, DPNGETSENDQUEUEINFO_PRIORITY_HIGH, 또는 DPNGETSENDQUEUEINFO_PRIORITY_LOW 플래그를 지정해, 그 우선 순위를 가지는 특정의 메세지에 대해 문의할 수가 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_INVALIDPARAM

주의

pdwNumMsgs 와 pdwNumBytes 의 양쪽 모두를 NULL 로 설정할 수 없다. 적어도 어느쪽이든 1 개(살)은 유효한 포인터로 설정할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::GetSPCaps

지정된 서비스 프로바이더의 DPN_SP_CAPS 구조체를 취득한다.

HRESULT GetSPCaps(
const GUID *const pguidSP,
DPN_SP_CAPS *const pdpnSPCaps,
const DWORD dwFlags
);

파라미터

pguidSP
정보를 취득하고 싶은 서비스 프로바이더를 지정하는 GUID 에의 포인터.
pdpnSPCaps
지정한 서비스 프로바이더에 관한 정보를 받는 DPN_SP_CAPS 구조체에의 포인터. 이 구조체의 pdpnSPCaps. dwSize 멤버를 적절한 값으로 설정할 필요가 있다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

이 메소드는, 지정한 서비스 프로바이더에 관한 정보를 취득한다. Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::Host

로컬 컴퓨터에 의해 호스트 되는, 새로운 클라이언트/서버 세션을 생성 한다.

HRESULT Host(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address **const prgpDeviceInfo,
const DWORD cDeviceInfo,
const DPN_SECURITY_DESC *const pdpSecurity,
const DPN_SECURITY_CREDENTIALS *const pdpCredentials,
VOID *const pvPlayerContext,
const DWORD dwFlags
);

파라미터

pdnAppDesc
어플리케이션을 기술하는 DPN_APPLICATION_DESC 구조체에의 포인터.
prgpDeviceInfo
어플리케이션을 호스트 하기 위해서 사용하는 디바이스 주소를 보관 유지하는,IDirectPlay8Address 오브젝트의 배열에의 포인터.
cDeviceInfo
prgpDeviceInfo 가 가리키는 배열의 디바이스 주소 오브젝트의 수를 지정하는 DWORD 형의 변수.
pdpSecurity
예약이 끝난 상태. NULL 로 설정하는 것.
pdpCredentials
예약이 끝난 상태. NULL 로 설정하는 것.
pvPlayerContext
플레이어의 문맥값에의 포인터. 이 값은, 로컬 컴퓨터가 DPN_MSGID_CREATE_PLAYER 메세지를 처리할 경우에, 사전으로 설정된다. 이 파라미터는 옵션이며, NULL 로 설정할 수 있다.
dwFlags
다음의 플래그를 지정할 수 있다.
DPNHOST_OKTOQUERYFORADDRESSING
이 플래그를 설정 하면, Microsoft® DirectPlay® 의 표준의 다이알로그 박스가 표시된다. 충분한 정보가 이 메소드에게 건네지지 않은 경우는, 상세한 것에 대하여 물어 합쳐진다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 몇개의 에러값을 돌려준다.

DPNERR_DATATOOLARGE
DPNERR_INVALIDPARAM

주의

dwFlags 에 DPNHOST_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 서비스 프로바이더는, 다이알로그 박스를 표시해, 유저에게 주소 정보의 입력을 요구하려고 한다. 서비스 프로바이더가 다이알로그 박스의 표시를 시도할 때는, 표시 가능한 윈도우가 존재하고 있을 필요가 있다. 윈도우가 없는 경우, 어플리케이션은 잠근다.

DPN_APPLICATION_DESC 구조체의 pvApplicationReservedData 멤버에 할당하는 어플리케이션 데이터의 최대 사이즈는, 서비스 프로바이더의 Maximum Transmission Unit 에 의해 제한된다. 어플리케이션 데이터가 너무 큰 경우, 메소드는 실패해, DPNERR_DATATOOLARGE 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::Initialize

IDirectPlay8Server 인터페이스 및 리모트 클라이언트로부터 메세지를 수신하는, 서버의 코드내의 엔트리 포인트를 등록한다. 이 메소드를 호출하고 나서, 이 인터페이스의 그 외의 메소드를 호출할 필요가 있다.

HRESULT Initialize(
PVOID const pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
const DWORD dwFlags
);

파라미터

pvUserContext
메세지 핸들러의 호출로 지정되는, 유저 지정의 문맥값. 유저 지정의 문맥값은, 복수의 인터페이스로부터 공통의 메세지 핸들러에 송신된 메세지를 구별하는데 도움이 된다.
pfn
PFNDPNMESSAGEHANDLER 콜백 함수에의 포인터. 이 함수는, 리모트 클라이언트로부터의 모든 메세지 및 IDirectPlay8Server 인터페이스로부터의 세션 변경의 통지를 받는다.
dwFlags
다음의 플래그를 지정할 수 있다.
DPNINITIALIZE_DISABLEPARAMVAL
이 플래그를 건네주면(자), 현재의 오브젝트에 대한 파라미터 타당성의 검증이 무효가 된다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

주의

IDirectPlay8Server 인터페이스를 취득하려면 ,CoCreateInstance 를 사용한 후에, 우선 이 메소드를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::RegisterLobby

기동한 어플리케이션이 게임 상태를 자동적으로 로비에 전달할 수 있도록(듯이) 한다.

HRESULT RegisterLobby(
const DPNHANDLE dpnHandle,
IDirectPlay8LobbiedApplication *const pIDP8LobbiedApplication,
const DWORD dwFlags
);

파라미터

dpnHandle
IDirectPlay8LobbiedApplication::UpdateStatus 를 호출하면나무에 사용하는 접속 핸들.
pIDP8LobbiedApplication
어플리케이션을 지정하는 IDirectPlay8LobbiedApplication 오브젝트에의 포인터.
dwFlags
다음의 플래그의 어느쪽이든을 지정한다.
DPNLOBBY_REGISTER
로비를 어플리케이션에 등록한다.
DPNLOBBY_UNREGISTER
어플리케이션에의 로비의 등록을 해제한다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::RemovePlayerFromGroup

그룹으로부터 클라이언트를 삭제한다.

HRESULT RemovePlayerFromGroup(
const DPNID idGroup,
const DPNID idClient,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

idGroup
클라이언트의 삭제처 그룹의 식별자를 지정하는 DPNID 형의 변수.
idClient
그룹으로부터 삭제하는 클라이언트의 식별자를 지정하는 DPNID 형의 변수.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNREMOVEPLAYERFROMGROUP_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

주의

이 메소드가 불려 가면(자), 서버의 메세지 핸들러는,DPN_MSGID_REMOVE_PLAYER_FROM_GROUP 메세지를 받아들인다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::ReturnBuffer

DPN_MSGID_RECEIVE 시스템 메세지의 pReceiveData 멤버에 의해 어플리케이션에 제공된 메세지 버퍼를 취득한다. 유저의 메세지 핸들러가 RECEIVE 콜백에 DPNSUCCESS_PENDING 를 돌려주었을 경우, 버퍼의 소유권은 어플리케이션으로 이행했다고 보여져 이 호출에 의해 소유권이 Microsoft® DirectPlay® 에 돌아올 때까지 소유권의 해방이나 변경은 행해지지 않는다.

HRESULT ReturnBuffer(
const DPNHANDLE hBufferHandle,
const DWORD dwFlags
);

파라미터

hBufferHandle
메세지용의 버퍼 핸들을 지정하는 DPNHANDLE 형의 변수. 이것은,DPNMSG_RECEIVE 시스템 메세지의 hBufferHandle 멤버로 취득한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::SendTo

세션내의 클라이언트 또는 그룹에 데이터를 송신한다. 메세지는 동기 또는 비동기에 송신할 수가 있다.

HRESULT SendTo(
const DPNID dpnid,
const DPN_BUFFER_DESC *const pBufferDesc,
const DWORD cBufferDesc,
const DWORD dwTimeOut,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

dpnid
데이터를 수신하는 클라이언트 또는 그룹의 식별자. 세션내의 모든 플레이어에게 메세지를 송신하는 경우는, 이 파라미터를 DPNID_ALL_PLAYERS_GROUP 로 설정한다.
pBufferDesc
송신하는 데이터를 기술하는 DPN_BUFFER_DESC 구조체에의 포인터.
cBufferDesc
pBufferDesc 가 가리키는 DPN_BUFFER_DESC 구조체의 수. 이 버젼의 Microsoft® DirectPlay® 에서는, 버퍼는 1 개가 아니면 안된다.
dwTimeOut
메세지의 송신을 기다리는 시간 (밀리 세컨드 단위). 메세지가 dwTimeOut 값으로 송신되어 있지 않은 경우, 메세지는 송신되지 않는다. 메세지의 송신에 대해서 타임 아웃이 필요하지 않은 경우는, 이 파라미터를 0 으로 설정한다.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_SEND_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
DPNHANDLE. 메소드가 돌아오면(자),phAsyncHandle 는,IDirectPlay8Server::CancelAsyncOperation 에 건네주어 처리를 취소할 수가 있는 핸들을 포인트 한다. dwFlags 에 DPNSEND_SYNC 플래그가 설정되어 있는 경우, 이 파라미터는 NULL 로 설정해야 한다.
dwFlags
송신 동작을 기술하는 플래그. 다음의 1 개 이상의 플래그를 설정할 수가 있다.
DPNSEND_SYNC
SendTo 요구를 동기를 잡으면서 처리한다.
DPNSEND_NOCOPY
DPN_BUFFER_DESC 구조체의 데이터를 사용해, 내부 카피는 실시하지 않는다. 이것은, 효율적인 데이터 송신의 방법이다. 그러나, 수신측이 메세지를 처리하기 전에, 송신측이 메세지를 변경할 수 있기 (위해)때문에, 견뢰한 것은 없어진다. 이 플래그를 DPNSEND_NOCOMPLETE 와 함께 사용할 수 없다.
DPNSEND_NOCOMPLETE
메세지 핸들러에 DPN_MSGID_SEND_COMPLETE 구조체를 송신하지 않는다. 이 플래그를 DPNSEND_NOCOPY 또는 DPNSEND_GUARANTEED 와 함께 사용할 수 없다. 또, 이 플래그를 사용하는 경우,pvAsyncContext 는 NULL 가 아니면 안된다.
DPNSEND_COMPLETEONPROCESS
메세지가 타겟으로 전달되어 메세지의 수신을 나타내는 타겟의 메세지 핸들러가 돌려주어질 때,DPN_MSGID_SEND_COMPLETE 를 메세지 핸들러에 송신한다. 이 플래그가 설정되었을 경우는, 여분의 내부 메세지의 오버헤드가 있어, 메세지의 송신 처리가 현저하게 저하할 가능성이 있다. 이 플래그를 설정했을 경우는, DPNSEND_GUARANTEED 도 설정할 필요가 있다.
DPNSEND_GUARANTEED
보증 첨부 전달 방식을 사용해 메세지를 송신한다.
DPNSEND_PRIORITY_HIGH
메세지의 우선 순위를 높게 설정한다. 이 플래그를 DPNSEND_PRIORITY_LOW 와 함께 사용할 수 없다.
DPNSEND_PRIORITY_LOW
메세지의 우선 순위를 낮게 설정한다. 이 플래그를 DPNSEND_PRIORITY_HIGH 와 함께 사용할 수 없다.
DPNSEND_NOLOOPBACK
로컬 플레이어를 포함한 그룹에 송신하고 있을 때, 메세지 핸들러에의 DPN_MSGID_RECEIVE 시스템 메세지를 억제한다. 예를 들어, 세션 전체에 있는 요소를 전요소에 카피하는 경우는, 이 플래그가 편리하다.
DPNSEND_NONSEQUENTIAL
이 플래그가 설정되었을 경우, 타겟 어플리케이션은, 유저의 컴퓨터에 도착한 순서에 메세지를 받아들인다. 이 플래그가 설정되어 있지 않은 경우, 메세지는 시퀀셜에 전달되어 타겟 어플리케이션은 송신된 순서에 메세지를 받아들인다. 따라서, 착신한 메세지를, 결핍 하고 있는 메세지가 도착할 때까지 버퍼에 저장 하는 경우가 있다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_CONNECTIONLOST
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_TIMEDOUT

주의

이 메소드는, 수취하는 측의 메세지 핸들러에 DPN_MSGID_RECEIVE 시스템 메세지를 생성한다. 데이터는, 관련지을 수 있고 있는 구조체의 pReceiveData 멤버에 보관 유지되고 있다.

메세지에는, 저, 보통, 고의 3 개의 우선 순위의 어느쪽이든을 설정할 수 있다. 메세지에 낮은 우선 순위 또는 높은 우선 순위를 지정하려면 dwFlags 에 적절한 플래그를 설정한다. 어느 쪽의 우선 순위 플래그도 설정하지 않았던 경우, 메세지는 보통의 우선 순위가 된다. 송신 우선 순위의 상세한 것에 대하여는, 「네트워킹의 기본」을 참조할것.

SendTo 요구가 완료 하면, 송신측의 메세지 핸들러에 DPN_MSGID_SEND_COMPLETE 시스템 메세지가 송신된다. 요구의 성공 또는 실패는, 관련지을 수 있었던 구조체의 hResultCode 멤버에 보관 유지된다. dwflags 에 DPNSEND_NOCOMPLETE 플래그를 설정 하면, 송신 완료의 시스템 메세지는 송신되지 않는다.

보통, 메세지가 송신되면(자) 즉시, 송신 완료가 송신원의 컴퓨터에 송신된다. 바꾸어 말하면(자), 송신 완료는, 메세지가 타겟상에서 처리된 것을 반드시 의미하지 않는다. 메세지는 아직 큐내에 있을 가능성도 있다. 메세지가 타겟으로 처리된 것을 확인하려면 ,dwFlags 에 DPNSEND_COMPLETEONPROCESS 플래그를 설정한다. 이 플래그를 설정 하면, 타겟의 메세지 핸들러가 메세지를 처리해 돌아올 때까지, 송신 완료는 송신되지 않는다.

어플리케이션은 IDirectPlay8Client,IDirectPlay8Server, 또는 IDirectPlay8Peer 로 Close 를 호출하기 전이나 최종 릴리스를 하기 전에,CancelAsyncOperation 를 호출해 남아 있는 Send 를 캔슬해야 한다. 거기에 실패 하면 예기치 못한 결과가 일어난다.

주 메소드가 돌아올 때까지는, 데이터 버퍼등의 리소스가 유효한 상태인 채이다고 봐서는 안 된다. 이 메소드를 비동기에게 호출하는 경우, 호출이 돌아오기 전에 DPN_MSGID_SEND_COMPLETE 메세지를 받아들여, 메세지 핸들러가 처리해 버리는 일이 있다. 메세지 핸들러가 데이터 버퍼등의 리소스를 할당 해제, 또는 무효로 했을 경우, 메소드가 불려 간 다음에 리소스가 무효가 되는 일이 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::SetApplicationDesc

호스트 되고 있는 어플리케이션의 설정을 변경한다. 변경할 수 있는 것은, 몇개의 설정뿐이다.

HRESULT SetApplicationDesc(
const DPN_APPLICATION_DESC *const pad,
const DWORD dwFlags
);

파라미터

pad
변경하는 어플리케이션의 설정을 기술하는 DPN_APPLICATION_DESC 구조체에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_DATATOOLARGE
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

주의

이 메소드를 사용해 변경할 수 있는 것은,DPN_APPLICATION_DESC 구조체의 이하의 멤버뿐이다.

  • dwMaxPlayers
  • pwszSessionName
  • pwszPassword
  • pvApplicationReservedData
  • dwApplicationReservedDataSize

DPN_APPLICATION_DESC 구조체의 pvApplicationReservedData 멤버에 할당하는 어플리케이션 데이터의 최대 사이즈는, 서비스 프로바이더의 Maximum Transmission Unit 에 의해 제한된다. 어플리케이션 데이터가 너무 큰 경우, 메소드는 실패해, DPNERR_DATATOOLARGE 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::SetCaps

현재의 인터페이스의 DPN_CAPS 구조체를 설정한다.

HRESULT SetCaps(
const DPNCAPS *const pdpCaps,
const DWORD dwFlags
);

파라미터

pdpCaps
현재의 인터페이스에 관한 정보의 설정에 사용되는 DPN_CAPS 구조체에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

이 메소드는, 지정된 서비스 프로바이더에 대한 파라미터를 설정한다. Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::SetGroupInfo

그룹명 등, 그룹에 관련지을 수 있고 있는 데이터 블록을 설정한다.

HRESULT SetGroupInfo(
const DPNID dpnid,
DPN_GROUP_INFO *const pdpnGroupInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

dpnid
데이터 블록을 변경하는 그룹의 식별자를 지정하는 DPNID 형의 변수.
pdpnGroupInfo
설정하는 그룹 데이터를 기술하는 DPN_GROUP_INFO 구조체에의 포인터. 이 구조체의 pwszName 멤버 또는 pvData 멤버의 값을 변경하려면 ,dwInfoFlags 멤버의 대응하는 DPNINFO_NAME OR DPNINFO_DATA 플래그를 설정할 필요가 있다.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNSETGROUPINFO_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::SetServerInfo

어플리케이션으로 서버의 정적 설정을 설정한다. 클라이언트가 서버에 올바르게 접속되면(자), 클라이언트는 IDirectPlay8Client::GetServerInfo 메소드를 호출하는 것으로, 이 메소드로 설정된 정보를 취득할 수가 있다.

HRESULT SetServerInfo(
const DPN_PLAYER_INFO *const pdpnPlayerInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

파라미터

pdpnPlayerInfo
설정하는 서버 정보를 보관 유지하는 DPN_PLAYER_INFO 구조체에의 포인터.
pvAsyncContext
유저 지정의 문맥에의 포인터. 이것은,DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지의 pvUserContext 멤버에 돌려주어진다.
phAsyncHandle
DPNHANDLE. 값이 돌려주어진다. 다만, Microsoft® DirectPlay® 8.0 에서는 이 조작의 취소는 허가되어 있지 않기 때문에, 값을 사용할 수 없다.
dwFlags
이 메소드가 처리되는 방법을 제어하는 플래그. 이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPNSETSERVERINFO_SYNC
메소드를 동기를 잡으면서 처리한다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 요구가 비동기에 처리되는 경우, 메소드가 즉시 처리되면(자), S_OK 를 돌려주는 경우가 있다. 디폴트에서는, 이 메소드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

주의

이 메소드는,IDirectPlayServer::Host 를 호출하기 전, 및 세션중은 언제라도 호출할 수 있다.

IDirectPlay8Server::SetServerInfo 메소드를 사용 하면 처리에 부담이 가기 (위해)때문에, 비정적 정보는 IDirectPlay8Server::SendTo 메소드를 사용해 전송 하는 것.

클라이언트가 어플리케이션에 접속한 후, 이 메소드를 사용해 서버 정보를 변경할 수 있다. 접속 후에 이 메소드를 호출하면, 데이터의 갱신을 알리는 DPN_MSGID_SERVER_INFO 시스템 메세지가 모든 플레이어에 대해서 생성된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlay8Server::SetSPCaps

지정된 서비스 프로바이더에 대한 DPN_SP_CAPS 구조체를 설정한다.

HRESULT SetSPCaps(
const GUID *const pguidSP,
const DPN_SP_CAPS *const pdpnSPCaps
);

파라미터

pguidSP
정보를 설정하는 서비스 프로바이더를 지정하는 GUID 에의 포인터.
pdpnSPCaps
지정한 서비스 프로바이더에 관한 정보를 설정하는 DPN_SP_CAPS 구조체에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

주의

이 메소드는, 지정된 서비스 프로바이더에 대한 파라미터를 설정한다. Initialize 의 호출이 성공한 후에, 이 메소드를 호출할 필요가 있다. 현재, 이 호출에서는 dwNumThreads 멤버만 설정할 수가 있다. dwFlags 멤버는 0 이 아니면 안된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


IDirectPlayVoiceClient

어플리케이션은,IDirectPlayVoiceClient 인터페이스의 메소드를 사용해, 음성 세션의 클라이언트를 관리한다.

IDirectPlayVoiceClient 인터페이스의 메소드는, 다음과 같이 분류할 수 있다.

버퍼 관리 | Create3DSoundBuffer
 | Delete3DSoundBuffer
그 외 | GetCaps
 | GetCompressionTypes
 | GetSoundDeviceConfig
 | SetNotifyMask
세션 관리 | Connect
 | Disconnect
 | GetClientConfig
 | GetSessionDesc
 | GetTransmitTargets
 | Initialize
 | SetClientConfig
 | SetTransmitTargets

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::Connect

클라이언트를 Microsoft® DirectPlay® Voice 세션에 접속한다.

HRESULT Connect(
PDVSOUNDDEVICECONFIG pSoundDeviceConfig,
PDVCLIENTCONFIG pdvClientConfig,
DWORD dwFlags
);

파라미터

pSoundDeviceConfig
사운드 디바이스 구성을 기술하는 DVSOUNDDEVICECONFIG 구조체에의 포인터.
pdvClientConfig
클라이언트의 일반적 구성을 기술하는 DVCLIENTCONFIG 구조체에의 포인터.
dwFlags
플래그. 다음의 플래그를 지정할 수 있다.
DVFLAGS_SYNC
처리가 완료할 때까지 메소드는 돌아오지 않는다.

반환값

메소드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는, DV_OK 를 돌려준다. 디폴트에서는, 이 메소드는 비동기에게 실행되어DVERR_PENDING 를 돌려준다. 에러의 경우는, 다음의 몇개의 값을 돌려준다.

DVERR_ALREADYPENDING
DVERR_COMPRESSIONNOTSUPPORTED
DVERR_INCOMPATIBLEVERSION
DVERR_INVALIDBUFFER
DVERR_INVALIDDEVICE
DVERR_INVALIDFLAGS
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTINITIALIZED
DVERR_OUTOFMEMORY
DVERR_RUNSETUP
DVERR_SENDERROR
DVERR_SOUNDINITFAILURE
DVERR_TIMEOUT
DVERR_TRANSPORTNOPLAYER
DVERR_TRANSPORTNOSESSION
DVERR_CONNECTED
DVERR_NOVOICESESSION

주의

DirectPlay Voice 세션에 클라이언트를 접속하기 전에 셋업 위저드를 호출해, 재생과 캡춰용으로 선택한 사운드 디바이스를 테스트할 필요가 있다. 어플리케이션의 기동시에는,IDirectPlayVoiceTest::CheckAudioSetup 를 사용해 오디오 구성을 확인한다. 이 메소드가 DVERR_RUNSETUP 를 돌려주는 경우, 지정된 사운드 구성은 테스트되어 있지 않다. 셋업 위저드는 구성 마다 1 회만 실행할 필요가 있다.

버퍼의 형식이 올바르지 않은 경우, 메소드는 DVERR_INVALIDBUFFER 를 돌려준다.

DirectPlay Voice 가 버퍼에 기입하려고 했을 때에 버퍼 또는 버퍼의 일부가 락 되고 있는 경우, 메소드는 DVERR_INVALIDBUFFER 를 돌려주어, DirectPlay Voice 는 세션으로부터 접속 해제된다. 또,DVMSGID_SESSIONLOST 메세지를 받아들인다. 관련지을 수 있고 있는 구조체의 hResult 멤버는 DVERR_LOCKEDBUFFER 로 설정된다. 이 후의 메소드의 호출은,DVERR_NOTCONNECTED 에러 코드를 돌려준다.

전이중 처리가 지원되어 있지 않은 경우, DirectPlay Voice 는 반이중 (청취 전용) 모드에 돌아온다. 반이중 모드인가 어떤가를 조사하려면 , 접속을 완료한 다음에,IDirectPlayVoiceClient::GetSoundDeviceConfig 를 호출한다. 반이중 모드의 경우,DVSOUNDDEVICECONFIG 구조체의 dwFlags 멤버에 DVSOUNDCONFIG_HALFDUPLEX 플래그가 설정되어 있다.

인터페이스의 취득 방법과는 관계없이,DirectPlayVoiceClient 오브젝트에서는,IDirectPlayVoiceClient::Disconnect 가 불려 갈 때까지,AddRef 에 의해, 사용하는 IDirectSound 인터페이스와 IdirectSoundCapture 인터페이스에의 참조가 유지된다. Disconnect 가 불려 가면(자),DirectPlayVoiceClient 오브젝트는 양인터페이스에 대해서 Release 를 호출한다.

DVFLAGS_SYNC 플래그를 설정해, 동기를 잡아 이 메소드를 호출했을 경우, 메세지 핸들러에 DVMSG_CONNECTRESULT 메세지는 송신되지 않는다. 이 경우, 접속 결과는 이 메소드의 반환값에 의해 정해진다.

이 메소드가 비동기에게 불려 갔을 경우 (디폴트), 메소드 호출 직후에 DVERR_PENDING 에러값이 돌려주어져 가방 그라운드에서 접속 요구가 처리된다. DirectPlay Voice 클라이언트가 접속 결과를 포함한 DVMSG_CONNECTRESULT 메세지를 생성할 때까지, 접속 상태는 불명하다.

접속이 보류 상태가 되어 있는 동안에 IDirectPlayVoiceClient::Connect 를 호출하면, DVERR_ALREADYPENDING 가 돌려주어진다. 또, 1 번에 1 개의 접속만을 보류 상태로 할 수 있다.

이 메소드를 호출하기 전에, 특정의 DirectPlay 오브젝트에 대해서 트랜스폴트 세션을 시작 하고 있을 필요가 있다. IDirectPlayVoiceClient::Initialize 의 호출이 성공한 후에 Connect 메소드를 호출할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::Create3DSoundBuffer

플레이어 또는 그룹에 대한 3D 사운드 버퍼를 취득한다. 3D 사운드 버퍼 오브젝트의 메소드를 사용 하면, 지정한 그룹 또는 플레이어로부터 수신한 음성 전송의 가상 3D 위치를 변경할 수 있다.

HRESULT Create3DSoundBuffer(
DVID dvID,
LPDIRECTSOUNDBUFFER lpdsSourceBuffer,
DWORD dwPriority,
DWORD dwFlags,
LPDIRECTSOUND3DBUFFER* lpUserBuffer
);

파라미터

dvID
유저가 버퍼를 보존하는 대상이 되는 플레이어 또는 그룹의 식별 정보를 지정하는 DVID 형의 변수. 또, DVID_REMAINING 를 지정 하면, 유저 버퍼가 없는 모든 플레이어 또는 그룹에 대해서 3D 유저 버퍼를 생성 할 수 있다. DVID_REMAINING 를 지정하는 경우,lpdsBufferDesc 에 NULL 를 지정해,dwPriority 파라미터와 dwFlags 파라미터를 0 으로 설정할 필요가 있다.
lpdsSourceBuffer
Microsoft® DirectPlay® Voice 의 메인 버퍼의 생성에 사용하는,IDirectSoundBuffer 인터페이스에의 포인터. NULL, 또는 유저 생성의 Microsoft DirectSound® 버퍼를 지정할 수 있다. 이 멤버가 NULL 의 경우, DirectPlay Voice 가 버퍼를 생성 한다.
dwPriority
다이레크트파스스르. IDirectSoundBuffer::Play 가 불려 갈 때, 이 값은 dwPriority 파라미터에게 건네진다. 상세한 것에 대하여는, 「IDirectSoundBuffer8::Play 」를 참조할것. lpdsMainBufferDesc 가 NULL 의 경우, 이 파라미터는 0 이 아니면 안된다.
dwFlags
다이레크트파스스르. IDirectSoundBuffer::Play 가 불려 갈 때, 이 값은 dwFlags 파라미터에게 건네진다. 상세한 것에 대하여는, 「IDirectSoundBuffer8::Play 」를 참조할것. lpdsMainBufferDesc 가 NULL 의 경우, 이 파라미터는 0 이 아니면 안된다.
lpUserBuffer
예약된 버퍼가 놓여지는 메모리에의 포인터.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_ALREADYBUFFERED
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTALLOWED
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_OUTOFMEMORY
DVERR_SESSIONLOST

주의

DirectPlay 의 음성 세션이 믹싱 서버 세션의 경우, 이 메소드는 실패해, DVERR_NOTALLOWED 를 돌려준다.

3D 사운드 버퍼 오브젝트의 모든 멤버 함수에 액세스 할 수 있지만, DirectPlay Voice 클라이언트가 버퍼를 사용해 수신 오디오의 스트리밍을 실시하기 (위해)때문에, DirectSound3Dbuffer 오브젝트의 Lock,UnLock,Play 의 각 메소드는 사용하지 않는 것.

여기서 버퍼를 지정했을 경우, DirectPlay 는 그 버퍼를 플레이어 또는 그룹의 버퍼로서 사용한다. 유저 생성의 버퍼에는 다음의 제한이 있다.

  • 버퍼는, 22 Khz, 16 비트, 단청의 포맷이 아니면 안된다.
  • 버퍼의 길이는 1 초 이상이 아니면 안된다.
  • 버퍼는, DSBCAPS_GETCURRENTPOSITION2 및 DSBCAPS_CTRL3D 플래그를 사용해 생성되어 있지 않으면 안 된다.
  • 버퍼는 프라이머리 버퍼여서는 안 된다.
  • DirectPlay 에 버퍼를 건네줄 때는, 버퍼가 재생중에서 만나서는 안 된다.

버퍼의 형식이 올바르지 않은 경우, 메소드는 DVERR_INVALIDBUFFER 를 돌려준다.

DirectPlay 에 버퍼를 건네줄 때는, 버퍼가 락 되고 있어서는 안 된다. 개개의 유저가 불필요하게 되는지, 플레이어가 음성 세션을 떨어지는 경우,IDirectPlayVoiceClient::Delete3DSoundBuffer 를 호출해, 리소스를 해방할 필요가 있다.

DirectPlay Voice 가 버퍼에 기입하려고 했을 때에 버퍼 또는 버퍼의 일부가 락 되고 있는 경우, 메소드는 DVERR_INVALIDBUFFER 를 돌려준다. 메소드가 돌아간 다음에 버퍼를 잠그었을 경우는,DVMSGID_SESSIONLOST 메세지를 받아들인다. 관련지을 수 있었던 구조체의 hResult 멤버에 DVERR_LOCKEDBUFFER 가 설정된다. 이 후의 메소드의 호출은,DVERR_NOTCONNECTED 에러 코드를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::Delete3DSoundBuffer

3D 사운드 버퍼 오브젝트의 배타 제어를 Microsoft® DirectPlay® 음성 클라이언트 오브젝트에 돌려준다.

HRESULT Delete3DSoundBuffer(
DVID dvID
LPDIRECTSOUND3DBUFFER* lpUserBuffer
);

파라미터

dvID
유저가 버퍼를 삭제하는 대상이 되는 플레이어 또는 그룹의 DVID.
lpUserBuffer
삭제하는 유저 버퍼에의 포인터. IDirectPlayVoiceClient::Create3DSoundBuffer 메소드에 의해 취득된 유저 버퍼를 지정할 필요가 있다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_ALREADYBUFFERED
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTALLOWED
DVERR_NOTBUFFERED
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

주의

DirectPlay Voice 세션이 믹싱 서버 세션의 경우, 이 메소드는 실패해, DVERR_NOTALLOWED 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::Disconnect

Microsoft® DirectPlay® Voice 클라이언트를 기존의 DirectPlay Voice 세션으로부터 접속 해제한다.

HRESULT Disconnect(
DWORD dwFlags
);

파라미터

dwFlags
플래그. 다음의 플래그를 지정할 수 있다.

DVFLAGS_SYNC

처리가 완료할 때까지 돌아오지 않는다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_ALREADYPENDING
DVERR_CONNECTABORTING
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_PENDING
DVERR_SESSIONLOST
DVERR_TIMEOUT

주의

이 메소드를 호출하면, 녹음과 재생은 모두 정지한다. 처리중의 접속은, 이 호출에 의해 삭제된다.

DVFLAGS_SYNC 가 지정되어 있지 않은 경우, 메소드 호출 직후에 DVERR_PENDING 에러값이 돌려주어져 가방 그라운드에서 접속 해제 요구가 처리된다. DirectPlay Voice 클라이언트가 접속 해제 결과를 포함한 DVMSG_DISCONNECTRESULT 메세지를 생성할 때까지, 접속 해제 상태는 불명하다. 한 번에 1 개의 접속 해제만을 보류 상태로 할 수 있다. 접속 해제가 보류가 되어 있는 동안에 IDirectPlayVoiceClient::Disconnect 를 호출했을 경우, DirectPlay 는 DVERR_ALREADYPENDING 에러값을 돌려준다.

DVFLAGS_SYNC 플래그를 설정해, 동기를 잡아 이 메소드를 호출했을 경우,Disconnect 메소드가 완료할 때까지 이 메소드는 돌아오지 않는다. 접속 해제의 결과는 이 메소드의 반환값이 가리킨다. DVMSGID_DISCONNECTRESULT 메세지는 생성되지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::GetCaps

Microsoft® DirectPlay® Voice 의 능력을 취득한다.

HRESULT GetCaps(
PDVCAPS pCaps
);

파라미터

pCaps
DirectPlayVoiceClient 오브젝트의 기능을 보관 유지하는 DVCAPS 구조체에의 포인터.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::GetClientConfig

클라이언트의 구성을 취득한다.

HRESULT GetClientConfig(
PDVCLIENTCONFIG pClientConfig
);

파라미터

pClientConfig
로컬 클라이언트의 구성을 보관 유지하는 DVCLIENTCONFIG 구조체에의 포인터.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

주의

이 멤버를 호출하기 전에,DVCLIENTCONFIG 구조체의 dwSize 멤버를 설정할 필요가 있다.

이 메소드는, Microsoft® DirectPlay® Voice 세션과의 접속이 성공한 후에게만, 호출할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::GetCompressionTypes

시스템으로 이용 가능한 압축의 타입을 취득한다.

HRESULT GetCompressionTypes(
PVOID pData,
PDWORD pdwDataSize,
PDWORD pdwNumElements,
DWORD dwFlags
);

파라미터

pData
DVCOMPRESSIONINFO 구조체의 배열을 받는 버퍼에의 포인터. 이 오브젝트로 지원 되고 있는 압축 타입 마다 1 개의 구조체가 포함된다.
pdwDataSize
pData 파라미터에게 건네진 버퍼 사이즈를 바이트 단위로 보관 유지하는 DWORD 에의 포인터.
pdwNumElements
메소드가 DVCOMPRESSIONINFO 구조체의 배열에 돌려주어진 요소의 수를 기입하는 DWORD 에의 포인터. pData 로 지정된 버퍼의 용량이, 정보를 보관 유지할 수 있는 사이즈인 경우에게만, 구조체의 수가 보관 유지된다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 DP_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DVERR_BUFFERTOOSMALL
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER

주의

건네받은 버퍼가 작고, 압축 타입의 리스트가 저장 할 수 없는 경우, 메소드는 DVERR_BUFFERTOOSMALL 를 돌려주어, 최저한 필요한 사이즈가 pdwDataSize 파라미터로 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::GetSessionDesc

세션의 프로퍼티를 취득한다.

HRESULT GetSessionDesc(
PDVSESSIONDESC pvSessionDesc
);

파라미터

pvSessionDesc
세션의 기술을 받는 DVSESSIONDESC 구조체에의 포인터.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

주의

이 메소드를 호출하기 전에,DVSESSIONDESC 구조체의 dwSize 멤버를 설정할 필요가 있다.

이 메소드는, Microsoft® DirectPlay® Voice 세션과의 접속이 성공한 후에게만, 호출할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::GetSoundDeviceConfig

세션의 사운드 디바이스 구성을 취득한다.

HRESULT GetSoundDeviceConfig(
PDVSOUNDDEVICECONFIG pSoundDeviceConfig,
PDWORD pdwSize
);

파라미터

pSoundDeviceConfig
사운드 디바이스의 구성을 저장 하는 DVSOUNDDEVICECONFIG 구조체에의 포인터.
pdwSize
pSoundDeviceConfig 파라미터의 버퍼의 사이즈를 지정하는 DWORD 에의 포인터. 버퍼가 너무 작은 경우, 메소드가 DVERR_BUFFERTOOSMALL 를 돌려주어, 필요한 버퍼의 사이즈가 이 파라미터에 보관 유지된다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

주의

이 메소드는, Microsoft® DirectPlay® Voice 세션과의 접속이 성공한 후에게만, 호출할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::GetTransmitTargets

이 클라이언트로부터의 음성 스트림의 송신 타겟을 취득한다 (존재하는 경우).

HRESULT GetTransmitTargets(
PDVID pdvIDTargets,
PDWORD pdwNumTargets,
DWORD dwFlags
);

파라미터

pdvIDTargets
IDirectPlayVoiceClient::SetTransmitTargets 메소드 또는 IDirectPlayVoiceServer::SetTransmitTargets 메소드에 의해 설정된 타겟을 지정하는 DVID 의 배열을 저장 하는 멤버. 이 파라미터에 NULL 를 지정해, 타겟의 수를 취득할 수가 있다.
pdwNumTargets
배열내의 DVID 의 수. 이 메소드를 호출하는 경우, 이 값은 IDirectPlayVoiceClient::SetTransmitTargets 메소드로 설정된 타겟수로 일치할 필요가 있다. 호출이 성공하면(자), Microsoft® DirectPlay® 는 pdvIDTargets 배열에 기입해진 요소의 수를 돌려준다.

pdvIDTargets 가 NULL 인 경우, 0 으로 설정해 둔다.

dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_BUFFERTOOSMALL
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTALLOWED
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED

주의

pdvIDTargets 파라미터에 돌려주어지는 값은, 플레이어 DVID 나 그룹 DVID, 또는 정수 DVID_ALLPLAYERS 이다.

pdvIDTargets 로 지정된 버퍼가 작고, 타겟의 리스트가 저장 할 수 없는 경우, 이 메소드는 DVERR_INVALIDPOINTER 를 돌려주어, 필요한 요소수가 pdwNumTargets 로 설정된다.

타겟이 지정되어 있지 않은 경우,pdwNumTargets 는 0 으로 설정되어 반환값은 DV_OK 가 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::Initialize

DirectPlayVoiceClient 오브젝트를 DirectPlay 오브젝트와 관련지어 초기화한다. 또, 이 메소드는 메세지 핸들러를 DirectPlayVoiceClient 오브젝트에 등록한다.

IDirectPlayVoiceClient::Connect 메소드를 호출하기 전에, 이 메소드의 호출이 성공하고 있을 필요가 있다.

HRESULT Initialize(
PVOID pVoid,
PDVMESSAGEHANDLER pMessageHandler,
PVOID pUserContext,
PDWORD pdwMessageMask,
DWORD dwMessageMaskElements
);

파라미터

pVoid
이 DirectPlayVoiceClient 오브젝트가 사용하는 DirectPlay 오브젝트에 대한 IUnknown 인터페이스에의 포인터.
pMessageHandler
처리하는 DirectPlayVoiceClient 메세지가 있는 경우에 불려 가는 유저 정의의 콜백 함수. DirectPlayVoiceClient 오브젝트내의 thread가 콜백 함수를 호출하기 (위해)때문에, 프로세스의 메인 thread의 문맥에는 콜백 함수는 불려 가지 않는다.
pUserContext
함수가 불려 갈 때마다 콜백 함수에게 건네지는, 어플리케이션에 의해 정의된 구조체에의 포인터.
pdwMessageMask
DirectPlay Voice 가 유저의 콜백 함수에 송신하는 메세지 식별자를 보관 유지하는 DWORD 의 배열. 메세지 식별자를 이 배열로 지정하지 않는 경우, 메세지는 송신되지 않는다. 각각의 메세지 식별자는 한 번만 배열에 표시된다. 유효한 메세지 식별자만이 허가된다. 예를 들어, DVMSGID_CONNECTRESULT 는 서버의 인터페이스에는 무효이지만, 클라이언트의 인터페이스에 대해서는 유효하다. 모든 메세지를 유효하게 하려면 , 이 값에 NULL 를 지정한다.
dwMessageMaskElements
pdwMessageMask 파라미터로 지정된 요소의 수. pdwMessageMask 가 NULL 인 경우, 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_ALREADYINITIALIZED
DVERR_GENERIC
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOCALLBACK
DVERR_TRANSPORTNOTINIT

주의

IDirectPlayVoiceClient::SetNotifyMask 를 호출해, 음성 세션의 진행중에 통지 마스크를 변경할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::SetClientConfig

클라이언트 구성을 설정한다.

HRESULT SetClientConfig(
PDVCLIENTCONFIG pClientConfig
);

파라미터

pClientConfig
설정하는 구성의 기술을 보관 유지하는 DVCLIENTCONFIG 구조체에의 포인터.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

주의

이 메소드는, Microsoft® DirectPlay® Voice 세션과의 접속이 성공한 후에게만, 호출할 수가 있다.

이 메소드를 호출하면,DVCLIENTCONFIG 구조체의 모든 파라미터가 설정된다. 따라서, 설정을 변경하지 않게 하려면 ,IDirectPlayVoiceClient::GetClientConfig 를 사용해, 현재의 구성을 취득할 필요가 있다. 다음에, 파라미터를 변경해,IDirectPlayVoiceClient::SetClientConfig 를 호출한다.

세션이 반이중으로 실행되고 있는 경우, 녹음에 관련하는 GetClientConfig 의 멤버는 무시된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::SetNotifyMask

메세지 핸들러에 송신하는 메세지를 지정한다.

HRESULT SetNotifyMask(
PDWORD pdwMessageMask,
DWORD dwMessageMaskElements
);

파라미터

pdwMessageMask
Microsoft® DirectPlay® Voice 가 유저의 콜백 함수에 송신하는 메세지 식별자를 보관 유지하는 DWORD 의 배열에의 포인터. 메세지 식별자를 이 배열로 지정하지 않는 경우, 메세지는 송신되지 않는다. 각각의 메세지 식별자는 한 번만 배열에 표시된다. 유효한 메세지 식별자만이 허가된다. 예를 들어, DVMSGID_CONNECTRESULT 는 서버의 인터페이스에는 무효이지만, 클라이언트의 인터페이스에 대해서는 유효하다. 모든 메세지를 유효하게 하려면 , 이 값에 NULL 를 지정한다.
dwMessageMaskElements
pdwMessageMask 파라미터로 지정된 요소의 수. pdwMessageMask 가 NULL 인 경우, 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOCALLBACK
DVERR_NOTINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceClient::SetTransmitTargets

로컬 클라이언트로부터 오디오 송신을 받는 플레이어 또는 그룹, 혹은 그 양쪽 모두를 지정한다.

HRESULT SetTransmitTargets(
PDVID pdvIDTargets,
DWORD dwNumTargets,
DWORD dwFlags
);

파라미터

pdvIDTargets
타겟을 지정하는 DVID 의 배열에의 포인터. 어느 타겟도 지정하지 않는 경우는, 이 파라미터에 NULL 를 건네준다. 게다가 이 파라미터에는 다음의 값도 설정할 수가 있다.
DVID_ALLPLAYERS
클라이언트는 세션의 모든 플레이어를 타겟으로 한다. 배열내의 유일한 요소일 필요가 있다.
dwNumTargets
배열내의 DVID 의 수. 이 값은 64 를 넘어서는 안 된다. pdvIDTargets 가 NULL 의 경우, 이 값은 0 으로 설정한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_INVALIDTARGET
DVERR_NOTINITIALIZED

주의

Microsoft® DirectX® 8.0 의 경우, 송신할 수 있는 개개의 타겟의 수는 64 까지 제한되고 있다. 이 값을 넘으면(자), 메소드는 실패해, DVERR_NOTALLOWED 를 돌려준다. 다만, 65 명 이상의 플레이어에게 송신할 수도 있다. 거기에는, 플레이어를 그룹에 정리해 그룹을 타겟으로서 사용한다.

pdvIDTargets 파라미터는 플레이어 또는 그룹의 DVID 의 배열을 지정한다. 이 파라미터에는 중복 타겟을 지정해서는 안 된다. 또, 엔트리는 모두 유효한 DVID 일 필요가 있다. 타겟이 개개의 DVID 를 가지는 플레이어 및 타겟이 소속하는 그룹내의 플레이어를 포함한 경우, Microsoft® DirectPlay® Voice 는 플레이어에게 중복 음성 패킷이 송신되지 않게 한다.

DVSESSION_SERVERCONTROLTARGET 플래그를 사용해 세션이 생성 되었을 경우, 이 로컬 클라이언트에는 서버 밖에 타겟을 설정할 수 없다. 이 메소드를 호출하면, DVERR_NOTALLOWED 가 돌려주어진다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer

어플리케이션은,IDirectPlayVoiceServer 인터페이스의 메소드를 사용해, 음성 세션의 호스트를 관리한다.

IDirectPlayVoiceServer 인터페이스의 메소드는, 다음과 같이 분류할 수 있다.

그 외 | GetCaps
 | GetCompressionTypes
 | SetNotifyMask
세션 관리 | GetSessionDesc
 | GetTransmitTargets
 | Initialize
 | SetSessionDesc
 | SetTransmitTargets
 | StartSession
 | StopSession

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::GetCaps

이 시스템의 Microsoft® DirectPlay® Voice 서버의 능력을 취득한다.

HRESULT GetCaps(
PDVCAPS pDVCaps
);

파라미터

pDVCaps
DirectPlayVoiceServer 오브젝트의 기능을 보관 유지하는 DVCAPS 구조체에의 포인터.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::GetCompressionTypes

시스템으로 이용 가능한 압축의 타입을 취득한다.

HRESULT GetCompressionTypes(
PVOID pData,
PDWORD pdwDataSize,
PDWORD pdwNumElements,
DWORD dwFlags
);

파라미터

pData
DVCOMPRESSIONINFO 구조체의 배열을 받는 버퍼에의 포인터. 이 구조체는, 이 오브젝트로 지원 되고 있는 압축 타입을 기술한다.
pdwDataSize
pData 파라미터에게 건네진 버퍼 사이즈를 바이트 단위로 보관 유지하는 DWORD 에의 포인터.
pdwNumElements
메소드가 DVCOMPRESSIONINFO 구조체의 배열에 돌려주어진 요소의 수를 기입하는 DWORD 에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_BUFFERTOOSMALL
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER

주의

건네받은 버퍼가 작고, 압축 타입의 리스트가 저장 할 수 없는 경우, 메소드는 DVERR_BUFFERTOOSMALL 를 돌려주어, 최저한 필요한 사이즈가 pdwDataSize 파라미터로 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::GetSessionDesc

Microsoft® DirectPlay® Voice 세션의 설정을 취득한다.

HRESULT GetSessionDesc(
PDVSESSIONDESC pvSessionDesc
);

파라미터

pvSessionDesc
세션의 기술을 받는 DVSESSIONDESC 구조체에의 포인터.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTHOSTING
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

주의

이 메소드를 호출하기 전에,DVSESSIONDESC 구조체의 dwSize 멤버를 설정할 필요가 있다.

이 메소드를 호출하기 전에,IDirectPlayVoiceServer::StartSession 의 호출이 성공하고 있을 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::GetTransmitTargets

세션내의 플레이어에 대한 음성 스트림의 송신 타겟을 취득한다 (존재하는 경우).

HRESULT GetTransmitTargets(
DVID dvSource,
PDVID pdvIDTargets,
PDWORD pdwNumTargets,
DWORD dwFlags
);

파라미터

dvSource
타겟으로 송신하는 유저 또는 그룹의 DVID.
pdvIDTargets
IDirectPlayVoiceServer::SetTransmitTargets 메소드에 의해 설정된 플레이어 또는 그룹의 현재의 타겟을 지정하는 DVID 의 배열. 이 파라미터에 NULL 를 지정해, 타겟의 수를 취득할 수가 있다.
pdwNumTargets
배열내의 DVID 의 수. 이 메소드를 호출하는 경우, 이 값은 IDirectPlayVoiceServer::SetTransmitTargets 메소드로 설정된 타겟수로 일치할 필요가 있다. 호출이 성공하면(자), Microsoft® DirectPlay® 는 pdvIDTargets 배열내의 요소의 수를 돌려준다.

pdvIDTargets 가 NULL 인 경우, 0 으로 설정해 둔다.

dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_BUFFERTOOSMALL
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTALLOWED
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED

주의

이 메소드는, DirectPlay Voice 세션의 생성시에 DVSESSION_SERVERCONTROLTARGET 플래그가 지정되었을 경우에게만 사용할 수 있다. 이 플래그가 지정되어 있지 않은 경우, 메소드는 DVERR_NOTALLOWED 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::Initialize

DirectPlayVoiceServer 오브젝트를, DirectPlay 오브젝트에 관련지어 초기화한다. 또, 이 메소드는 메세지 핸들러를 이 인터페이스에 등록한다.

HRESULT Initialize(
LPVOID lpVoid,
PDVMESSAGEHANDLER pMessageHandler,
PVOID pUserContext,
LPDWORD lpdwMessageMask,
DWORD dwMessageMaskElements
);

파라미터

lpVoid
이 DirectPlayVoiceServer 오브젝트가 사용하는 DirectPlay 오브젝트에 대한 IUnknown 인터페이스에의 포인터.
pMessageHandler
처리하는 DirectPlayVoiceClient 메세지가 있는 경우에 불려 가는 유저 정의의 콜백 함수. DirectPlayVoiceClient 오브젝트내의 thread가 콜백 함수를 호출하기 (위해)때문에, 처리하고 있는 메인 thread의 문맥에는 콜백 함수는 불려 가지 않는다.
pUserContext
메소드가 불려 갈 때마다 콜백 함수에게 건네지는, 어플리케이션에 의해 정의된 구조체에의 포인터.
lpdwMessageMask
DirectPlay Voice 가 유저의 콜백 함수에 송신하는 메세지 식별자를 보관 유지하는 DWORD 의 배열. 메세지 식별자를 이 배열로 지정하지 않는 경우, 메세지는 송신되지 않는다. 각각의 메세지 식별자는 한 번만 배열에 표시된다. 유효한 메세지 식별자만이 허가된다. 예를 들어, DVMSGID_CONNECTRESULT 는 서버의 인터페이스에는 무효이지만, 클라이언트의 인터페이스에 대해서는 유효하다. 모든 메세지를 유효하게 하려면 , 이 값에 NULL 를 지정한다.
dwMessageMaskElements
lpdwMessageMask 파라미터로 지정된 요소수. lpdwMessageMask 가 NULL 인 경우, 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_ALREADYINITIALIZED
DVERR_GENERIC
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOCALLBACK
DVERR_TRANSPORTNOTINIT

주의

IDirectPlayVoiceServer::SetNotifyMask 를 호출해, 음성 세션의 진행중에 통지 마스크를 변경할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::SetNotifyMask

메세지 핸들러에 송신하는 메세지를 지정한다.

HRESULT SetNotifyMask(
PDWORD pdwMessageMask,
DWORD dwMessageMaskElements
);

파라미터

pdwMessageMask
Microsoft® DirectPlay® Voice 가 유저의 콜백 함수에 송신하는 메세지 식별자를 보관 유지하는 DWORD 의 배열에의 포인터. 메세지 식별자를 이 배열로 지정하지 않는 경우, 메세지는 송신되지 않는다. 각각의 메세지 식별자는 한 번만 배열에 표시된다. 유효한 메세지 식별자만이 허가된다. 예를 들어, DVMSGID_CONNECTRESULT 는 서버의 인터페이스에는 무효이지만, 클라이언트의 인터페이스에 대해서는 유효하다. 모든 메세지를 유효하게 하려면 , 이 값에 NULL 를 지정한다.
dwMessageMaskElements
pdwMessageMask 파라미터로 지정된 요소의 수. pdwMessageMask 가 NULL 인 경우, 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOCALLBACK
DVERR_NOTINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::SetSessionDesc

세션 설정을 설정한다.

HRESULT SetSessionDesc(
PDVSESSIONDESC pSessionDesc
);

파라미터

pSessionDesc
세션의 기술을 보관 유지하는 DVSESSIONDESC 구조체에의 포인터.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTHOSTING
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

주의

Microsoft® DirectPlay® Voice 세션이 시작 되면(자),DVSESSIONDESC 구조체의 세션 프로퍼티의 일부는 변경할 수 없다. 상세한 것에 대하여는,DVSESSIONDESC 를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::SetTransmitTargets

클라이언트로부터 세션의 지정된 멤버에의 오디오의 송신을 제어한다.

HRESULT SetTransmitTargets(
DVID dvSource,
PDVID pdvIDTargets,
DWORD dwNumTargets,
DWORD dwFlags
);

파라미터

dvSource
타겟이 설정되는 유저의 DVID.
pdvIDTargets
오디오 송신의 타겟인 플레이어 DVID 또는 그룹 DVID 의 리스트. 어느 타겟도 지정하지 않는 경우는, 이 파라미터에 NULL 를 건네준다. 게다가 이 파라미터에는 다음의 값도 설정할 수가 있다.
DVID_ALLPLAYERS
이 클라이언트는 세션의 모든 플레이어를 타겟으로 한다. 배열내의 유일한 요소일 필요가 있다.
dwNumTargets
배열내의 DVID 의 수. 이 값은 64 를 넘어서는 안 된다. pdvIDTargets 가 NULL 의 경우, 이 값은 0 으로 설정한다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_INVALIDTARGET
DVERR_NOTALLOWED
DVERR_NOTINITIALIZED

주의

Microsoft® DirectX® 8.0 의 경우, 전송 할 수 있는 개개의 타겟의 수는, 64 까지 제한된다. 이 값을 넘으면(자), 메소드는 실패해, DVERR_NOTALLOWED 를 돌려준다. 다만, 65 명 이상의 플레이어에게 전송 할 수도 있다. 그 때문에(위해)는, 플레이어를 그룹에 정리해 그룹을 타겟으로서 사용한다.

이 파라미터에는 중복 타겟을 지정해서는 안 된다. 또, 엔트리는 모두 유효한 DVID 일 필요가 있다. 타겟이 개개의 DVID 를 가지는 플레이어 및 타겟이 소속하는 그룹내의 플레이어를 포함한 경우, Microsoft® DirectPlay® Voice 는 플레이어에게 중복 음성 패킷이 송신되지 않게 한다.

이 메소드는, DirectPlay Voice 세션의 생성시에 DVSESSION_SERVERCONTROLTARGET 플래그가 지정되었을 경우에게만 사용할 수 있다. 이 플래그가 지정되어 있지 않은 경우, 메소드는 DVERR_NOTALLOWED 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::StartSession

실행중의 DirectPlay 트랜스폴트 세션내에서, 초기화 끝난 Microsoft® DirectPlay® Voice 세션을 시작 한다. 이 메소드의 호출이 성공하지 않으면 클라이언트는 음성 세션에의 접속을 완료할 수 없다.

HRESULT StartSession(
PDVSESSIONDESC pSessionDesc,
DWORD dwFlags
);

파라미터

pSessionDesc
세션의 기술을 보관 유지하는 DVSESSIONDESC 구조체에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_ALREADYPENDING
DVERR_HOSTING
DVERR_INVALIDFLAGS
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTINITIALIZED

주의

이 메소드를 호출하기 전에 IDirectPlayVoiceServer::Initialize 메소드를 호출할 필요가 있다. 음성 세션이 피어 투 피어인 경우, 음성 세션은 세션의 임의의 클라이언트에 호스트 할 수 있다. 음성 세션이 피어 투 피어가 아닌 경우, 액티브한 트랜스폴트 세션의 호스트인 트랜스폴트 클라이언트로 호스트 할 필요가 있다.

DVSESSIONDESC 구조체는 시작 하는 음성 세션의 타입을 보관 유지한다. 음성 세션의 타입에 따라서는, 클라이언트와 서버의 CPU 와 대역폭의 사용에 대해, 큰 영향을 주는 일이 있다. DVSESSIONDESC 의 guidCT 멤버를 DPVCTGUID_DEFAULT 로 설정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceServer::StopSession

Microsoft® DirectPlay® Voice 세션을 정지한다.

HRESULT StopSession(
DWORD dwFlags
);

파라미터

dwFlags
플래그. 다음의 플래그를 설정할 수 있다.
DVFLAGS_NOHOSTMIGRATE
세션과 트랜스폴트의 설정에 관계없이, 호스트는 이행 하지 않는다. 음성 세션을 완전하게 슛다운 하는 경우는, 이 플래그를 사용한다.

반환값

성공했을 경우는 DV_OK 를 돌려준다. 또는, 다음의 몇개의 에러값을 돌려준다.

DVERR_ALREADYPENDING
DVERR_INVALIDFLAGS
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_NOTHOSTING
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

주의

다른 thread로 StopSession 요구가 처리되고 있는 동안에 이 메소드가 불려 갔을 경우, DVERR_ALREADYPENDING 에러값이 돌려주어진다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceTest

어플리케이션은,IDirectPlayVoiceTest 인터페이스의 CheckAudioSetup 메소드를 사용해, Microsoft® DirectPlay® Voice 의 오디오 구성을 테스트한다.

오디오 구성 CheckAudioSetup

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlayVoiceTest::CheckAudioSetup

지정된 디바이스에 대해서 오디오 셋업 위저드를 실행한다. 이 위저드는, 디바이스에 몇개의 테스트를 실시해, 전이중 오디오를 이용할 수 있을지 어떨지를 확인한다. 또, 마이크가 접속되고 있어 캡춰 디바이스로 올바르게 동작할지 어떨지를 확인한다.

HRESULT CheckAudioSetup(
const GUID * pguidPlaybackDevice,
const GUID * pguidCaptureDevice,
HWND hwndParent,
DWORD dwFlags
);

파라미터

pguidPlaybackDevice
테스트하는 재생 디바이스를 식별하는 GUID 에의 포인터. 이 파라미터에 NULL 를 건네주었을 경우, Microsoft® DirectPlay® Voice 는 Microsoft® DirectSound® 에 정의되고 있는 시스템의 디폴트 음성 재생 디바이스를 테스트한다. DirectSound 의 디폴트 GUID 의 1 개를 건네줄 수도 있다.
DSDEVID_DefaultPlayback
시스템의 디폴트 재생 디바이스.
DSDEVID_DefaultVoicePlayback
디폴트 음성 재생 디바이스.
pguidCaptureDevice
테스트하는 캡춰 디바이스를 식별하는 GUID 에의 포인터. 이 파라미터에 NULL 를 건네주었을 경우, DirectPlay Voice 는 DirectSound 에 정의되고 있는 시스템의 디폴트의 음성 캡춰 디바이스를 테스트한다. DirectSound 의 디폴트 GUID 의 1 개를 건네줄 수도 있다.
DSDEVID_DefaultCapture
디폴트의 시스템 캡춰 디바이스. 또, 디바이스의 GUID 파라미터에 NULL 포인터를 건네주어, 이 디바이스를 지정할 수도 있다.
DSDEVID_DefaultVoiceCapture
디폴트의 통신 캡춰 디바이스. 일반적으로, 이것은 마이크 첨부의 USB 헤드 세트등의 세칸다리데바이스이다.
hwndParent
이 메소드에 의해 불려 가는 테스트 위저드는 모덜이다. 위저드의 부모 윈도우가 되는 윈도우가 호출해 원의 어플리케이션에 있는 경우, 그 윈도우에의 핸들을 이 파라미터로 건네줄 필요가 있다. 호출원어플리케이션에 윈도우가 없는 경우, NULL 를 건네줄 수가 있다. DVFLAGS_QUERYONLY 플래그를 지정했을 경우, 이 파라미터는 사용되지 않고, 어플리케이션은 NULL 를 건네줄 수가 있다.
dwFlags
플래그. 다음의 플래그를 설정할 수 있다.
DVFLAGS_QUERYONLY
오디오 셋업은 실행되지 않는다. 그 대신해, 메소드는 레지스트리를 조사해 디바이스가 테스트가 끝난 상태인가 어떤가를 체크한다. 디바이스가 테스트되어 있지 않은 경우, 메소드는 DVERR_RUNSETUP 를 돌려준다. 디바이스가 테스트되고 있는 경우, 디바이스가 전이중 오디오를 지원 하고 있으면, 메소드는 DV_FULLDUPLEX 를 돌려주어, 디바이스가 전이중 오디오를 지원 하고 있지 않으면, 메소드는 DV_HALFDUPLEX 를 돌려준다.
DVFLAGS_ALLOWBACK
이 플래그를 건네주면(자), 위저드의 웰컴 페이지로 [Back] 버튼이 유효하게 된다. 유저가 웰컴 페이지의 [Back] 버튼을 클릭 하면, 위저드는 종료해,CheckAudioSetup 는 DVERR_USERBACK 를 돌려준다.

반환값

성공했을 경우는 DP_OK, DV_FULLDUPLEX, 또는 DV_HALFDUPLEX 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DVERR_INVALIDPARAM
DVERR_RUNSETUP
DVERR_INVALIDDEVICE

주의

이 메소드는 유저 인터페이스 (UI)의 요소를 보관 유지해, 다이알로그 박스를 표시한다. DVFLAGS_QUERYONLY 플래그를 지정 하면, 테스트는 실제로는 실행되지 않고, UI 는 기동하지 않는다. 그 대신해, 레지스트리를 조사해 디바이스의 이전의 테스트 결과를 확인한다.

유저가 위저드를 취소하면(자),CheckAudioSetup 는 DVERR_USERCANCEL 를 돌려준다. 그 후, 호출원어플리케이션은 상황에 따라 대처할 수 있다. 예를 들어, 게임 옵션 컨트롤 패널 어플리케이션의 DirectPlay Voice 부분에서, 유저가 [Cancel] 를 클릭했을 경우, 위저드가 삭제되었기 때문에 음성을 사용할 수 없는 것을 나타내는 메세지를 다이알로그 박스에 표시한다.

지정된 디바이스가 존재하지 않는 경우, 이 메소드는 DVERR_INVALIDDEVICE 를 돌려준다. 또, 디폴트의 디바이스를 지정해도 이 메소드가 이 에러를 돌려주는 경우는, 시스템에 사운드 디바이스가 없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


IDirectPlay8LobbyClient

IDirectPlay8LobbyClient 인터페이스는, 로비 클라이언트 어플리케이션으로 사용해, 로컬 컴퓨터로 로비 대응 게임 어플리케이션의 열거와 기동을 실시한다. 또, 실행중의 게임 어플리케이션과의 통신에도 사용한다. 로비 클라이언트는, 로비 및 로비 되는 게임 어플리케이션으로부터의 메세지를 처리하기 위해(때문에), 메세지 핸들러 루틴을 등록할 필요가 있다.

IDirectPlay8LobbyClient 인터페이스에는, 다음의 메소드가 있다.

IDirectPlay8LobbyClient 메소드 | Close
 | ConnectApplication
 | EnumLocalPrograms
 | Initialize
 | ReleaseApplication
 | Send
 | GetConnectionSettings
 | SetConnectionSettings

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbyClient::Close

로비 클라이언트를 삭제한다.

HRESULT Close(
const DWORD dwFlags
);

파라미터

dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_UNINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbyClient::ConnectApplication

로비 대응 어플리케이션을,DPL_CONNECT_INFO 구조체로 지정되고 있는 세션에 접속한다. 어플리케이션이 실행되어 있지 않은 경우, 이 메소드를 사용해 어플리케이션을 기동할 수 있다.

접속이 성공하면(자), 로비 어플리케이션은 메세지 핸들러에 DPL_MSGID_CONNECT 시스템 메세지를 생성한다.

HRESULT ConnectApplication(
DPL_CONNECT_INFO *const pdplConnectionInfo,
const PVOID pvUserApplicationContext,
DPNHANDLE *const phApplication,
const DWORD dwTimeOut,
const DWORD dwFlags
);

파라미터

pdplConnectionInfo
DPL_CONNECT_INFO 구조체에의 포인터. 이 구조체는 접속처 어플리케이션의 GUID 를 포함한, 접속 파라미터를 기술한다.
pvUserApplicationContext
로비 클라이언트용으로 정의된 문맥값에의 포인터. 이 값은, 로비 클라이언트의 메세지 핸들러에의 호출로 건네받는다.
phApplication
이 메소드가 성공했을 경우로 설정되는 어플리케이션 문맥 핸들을 지정하는 DPNHANDLE 에의 포인터. 이 핸들은, 어플리케이션과의 통신에 사용된다. 또, 이 핸들은 IDirectPlay8LobbyClient::ReleaseApplication 메소드의 phApplication 파라미터에서도 사용된다.
dwTimeOut
접속의 처리를 기다리는 시간 (밀리 세컨드 단위)을 지정하는 DWORD 형의 변수.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_CANTLAUNCHAPPLICATION
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_TIMEDOUT

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbyClient::EnumLocalPrograms

시스템에 등록되어 있는 로비 어플리케이션을 열거한다.

HRESULT EnumLocalPrograms(
GUID *const pGuidApplication,
BYTE *const pEnumData,
DWORD *const pdwEnumData,
DWORD *const pdwItems.
const DWORD dwFlags
);

파라미터

pGuidApplication
열거하는 로비 어플리케이션을 지정하는 GUID 형의 변수에의 포인터. 이 파라미터는 옵션이다. NULL 를 건네주면(자), 이용 가능한 모든 로비 어플리케이션이 열거된다.
pEnumData
로비 어플리케이션의 기술을 저장 하는 BYTE 형의 변수에의 포인터.
pdwEnumData
pEnumData 버퍼에 보관 유지되는 바이트수를 지정하는 DWORD 형의 변수에의 포인터. pEnumData 의 버퍼가 너무 작은 경우, 이 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려주어, 필요한 버퍼의 사이즈를 이 파라미터로 설정한다.
pdwItems
pEnumData 버퍼의 DPL_APPLICATION_INFO 구조체의 수를 보관 유지하는 DWORD 형의 변수에의 포인터. 메소드가 성공했을 경우에게만, 이 파라미터에 값이 저장 된다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

주의

보통, 이 메소드는 2 회 불려 간다. 1 번째는, 필요한 버퍼의 사이즈를 취득하기 위해서 불려 간다. 2 번째는, 올바른 버퍼 사이즈를 사용해 불려 간다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbyClient::Initialize

기동된 어플리케이션 상태 변경에 관한 통지를 받는 로비 클라이언트의 코드내의 엔트리 포인트를 등록한다. 또, 메세지 핸들러는 로비 어플리케이션으로부터 메세지를 받아들인다. 이 메소드를 호출하고 나서, 이 인터페이스의 그 외의 메소드를 호출할 필요가 있다.

HRESULT Initialize(
const PVOID pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
const DWORD dwFlags
);

파라미터

pvUserContext
메세지 핸들러의 호출로 지정되는, 유저 지정의 문맥값에의 포인터. 유저 지정의 문맥값은, 복수의 인터페이스로부터 공통의 메세지 핸들러에 송신된 메세지를 구별하는데 도움이 된다.
pfn
IDirectPlay8LobbyClient 인터페이스로부터 모든 메세지, 및 IDirectPlay8LobbiedApplication 인터페이스로부터 세션 변경의 통지를 취득하는 PFNDPNMESSAGEHANDLER 콜백 함수에의 포인터.
dwFlags
다음의 플래그를 지정할 수 있다.
DPLINITIALIZE_DISABLEPARAMVAL
파라미터 타당성의 검증을 무효로 한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

주의

IDirectPlay8LobbyClient 인터페이스를 취득하려면 ,CoCreateInstance 를 사용한 후에 이 메소드를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbyClient::ReleaseApplication

로비 어플리케이션을 해방해, 로비 클라이언트와 어플리케이션의 접속을 종료한다. 로비 클라이언트가 어플리케이션과의 세션을 종료할 때 마다, 이 메소드를 호출할 필요가 있다.

HRESULT ReleaseApplication(
const DPNHANDLE hApplication.
const DWORD dwFlags
);

파라미터

hApplication
해방하는 로비 어플리케이션의 DPNHANDLE. 이 값은,IDirectPlay8LobbyClient::ConnectApplication 메소드의 phApplication 파라미터로 설정된다. 다음의 플래그도 지정할 수 있다.
DPLHANDLE_ALLAPPLICATIONS
모든 어플리케이션 접속을 해방한다.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbyClient::Send

이 로비 클라이언트에 의해 기동 또는 접속된 로비 어플리케이션에 메세지를 송신한다.

이 메소드는, 타겟의 메세지 핸들러에 DPL_MSGID_RECEIVE 시스템 메세지를 송신한다.

HRESULT Send(
const DPNHANDLE hConnection,
BYTE *const pBuffer,
const DWORD pBufferSize,
const DWORD dwFlags
);

파라미터

hConnection
메세지 송신의 타겟을 지정하는 DPNHANDLE 형의 변수. 다음의 플래그도 지정할 수 있다.
DPLHANDLE_ALLAPPLICATIONS
지정한 메세지가, 로비 클라이언트 어플리케이션에 접속 떠날 수 있어 모든 로비 어플리케이션에 송신된다.
pBuffer
메세지를 보관 유지하는 바이트의 배열에의 포인터.
pBufferSize
pBuffer 파라미터에 메세지 버퍼의 사이즈 (바이트 단위)를 지정하는 DWORD 형의 변수. 이 파라미터는 1 바이트 이상, 64 KB 이하가 아니면 안된다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM
DPNERR_SENDTOOLARGE

주의

버퍼 사이즈가 64 KB 보다 큰 경우, 메소드는 DPNERR_SENDTOOLARGE 를 돌려준다. 버퍼 사이즈가 0 으로 설정되어 있는 경우, 메소드는 DPNERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbyClient::GetConnectionSettings

지정된 접속의 접속 설정 세트를 취득한다. 이러한 설정은,IDirectPlay8LobbyClient::ConnectApplication ,IDirectPlay8LobbyClient::SetConnectionSettings 또는 IDirectPlay8LobbiedApplication::SetConnectionSettings 메소드를 호출해 설정할 수 있다.

접속 설정을 취득 하면, 유저에게 돌려주어지는 각 주소 오브젝트에 참조가 추가된다. 따라서, 구조체의 처리가 종료하면(자), 유저는 각 주소 오브젝트에 대해서 Release 를 호출할 필요가 있다.

HRESULT GetConnectionSettings(
const DPNHANDLE hConnection,
DPL_CONNECTION_SETTINGS *const pdplConnectSettings,
DWORD*pdwDataSize,
const DWORD dwFlags
);

파라미터

hConnection
설정을 취득하는 접속의 핸들.
pdplConnectSettings
지정된 접속의 접속 설정을 받는 버퍼에의 포인터.
pdwDataSize
pdplConnectSettings 구조체로 지정된 버퍼의 사이즈 (바이트 단위)를 보관 유지하는 DWORD 에의 포인터. 버퍼가 접속 설정을 보관 유지 가능한 한의 크기가 아닌 경우, DPNERR_BUFFERTOOSMALL 가 돌려주어져 이 값에는 필요한 버퍼 사이즈가 설정된다. 성공했을 경우, 이 값은, 지정된 버퍼에 기입해진 바이트수를 보관 유지한다.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbyClient::SetConnectionSettings

지정된 접속에 관련짓는 접속 설정을 설정한다. 이 메소드를 호출하면,hConnection 로 지정한 클라이언트에 송신하는 DPL_MSGID_CONNECTION_SETTINGS 메세지가 생성된다.

접속 설정을 설정 하면, 호출로 지정한 각 주소 오브젝트에 로비 어플리케이션이 참조를 추가한다.

HRESULT SetConnectionSettings(
const DPNHANDLE hConnection,
const DPL_CONNECTION_SETTINGS *const pdplConnectSettings,
const DWORD dwFlags
);

파라미터

hConnection
설정을 설정하는 접속의 핸들. 다음의 플래그도 지정할 수 있다.
DPLHANDLE_ALLAPPLICATIONS
접속 설정이, 접속하고 있는 모든 로비 어플리케이션에 대해서 갱신된다.
pdplConnectSettings
지정된 접속에 관련지을 수 있었던 설정을 보관 유지하는 DPL_CONNECTION_SETTINGS 구조체에의 포인터.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication

IDirectPlay8LobbiedApplication 인터페이스는, 로비를 지원 하는 어플리케이션으로 사용한다. 이 인터페이스를 사용 하면, 어플리케이션이 로비에서 기동할 수 있도록(듯이), 시스템에 등록할 수 있다. 또, 어플리케이션은, 유저를 조회하지 않고 , 게임의 기동에 필요한 접속 정보를 취득할 수 있다. 마지막으로, 로비 어플리케이션은 이 인터페이스를 사용해, 어플리케이션을 기동한 로비 클라이언트에 메세지와 통지를 송신할 수 있다.

IDirectPlay8LobbiedApplication 인터페이스에는, 다음의 메소드가 있다.

IDirectPlay8LobbiedApplication 메소드 | Close
 | SetAppAvailable
 | Initialize
 | RegisterProgram
 | Send
 | UnRegisterProgram
 | UpdateStatus
 | GetConnectionSettings
 | SetConnectionSettings

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication::Close

로비 어플리케이션을 삭제한다.

HRESULT Close(
const DWORD dwFlags
);

파라미터

dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_UNINITIALIZED
DPNERR_INVALIDOBJECT
DPNERR_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication::SetAppAvailable

로비 클라이언트가 접속하는 어플리케이션을 이용할 수 있도록(듯이) 하거나 이용할 수 없게 한다. 보통, 로비 어플리케이션이 로비 클라이언트에 의해 기동한 것은 아니고, 독립해 기동했을 경우, 이 메소드가 불려 간다. 또, 게임이 종료해, 다른 게임의 시작시에 로비 클라이언트에 접속하기 위해(때문에), 로비 어플리케이션이 필요한 경우도, 이 메소드를 호출한다.

HRESULT SetAppAvailable(
const BOOL fAvailable,
const DWORD dwFlags
);

파라미터

fAvailable
어플리케이션을 이용할 수 있을지 어떨지를 설정하는 불리언 값. 어플리케이션을 이용할 수 있는 것을 나타내는 경우는, 이 값에 TRUE 를 설정해, 이용할 수 없는 것을 나타내려면 FALSE 를 설정한다.
dwFlags
이 메소드에는, 다음의 플래그를 설정할 수 있다.
DPLAVAILABLE_ALLOWMULTIPLECONNECT
이 메소드의 디폴트의 동작에서는, 최초의 접속이 확립된 시점에서, 자동적으로 인터페이스를 이용 불가와 마크 한다. 이 플래그를 지정 하면, 최초의 접속의 확립 후에 인터페이스가 자동적으로 이용 불가와 마크 되는 것이 없기 때문에, 복수의 접속이 가능하다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDOBJECT
DPNERR_UNINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication::Initialize

로비 클라이언트 상태의 변경에 관한 통지 및 로비 클라이언트로부터의 메세지를 받아들이는 메세지 핸들러 함수를 등록한다.

HRESULT Initialize(
const PVOID pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
DPNHANDLE *const pdpnhConnection,
const DWORD dwFlags
);

파라미터

pvUserContext
메세지 핸들러의 호출로 지정되는, 유저 지정의 문맥값. 유저 지정의 문맥값은, 복수의 인터페이스로부터 공통의 메세지 핸들러에 송신된 메세지를 구별하는데 도움이 된다.
pfn
IDirectPlay8LobbyClient 인터페이스로부터 모든 메세지, 및 IDirectPlay8LobbiedApplication 인터페이스로부터 세션 변경의 통지를 취득하는 PFNDPNMESSAGEHANDLER 콜백 함수에의 포인터.
pdpnhConnection
어플리케이션이 로비에서 기동되었는지 어떠했는지를 검출하기 위해서 사용하는 값. 어플리케이션이 로비에서 기동되고 있는 경우, 이 파라미터에는 로비 클라이언트의 접속 핸들이 설정된다. 프로세스가 로비에서 기동되어 있지 않은 경우, 이 파라미터는 NULL 로 설정된다.
dwFlags
다음의 플래그를 지정할 수 있다.
DPLINITIALIZE_DISABLEPARAMVAL
파라미터 타당성의 검증을 무효로 한다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

주의

IDirectPlay8LobbiedApplication 인터페이스를 취득하려면 ,CoCreateInstance 를 사용한 후에 이 메소드를 호출한다.

로비에서 기동했을 경우, 이 메소드는 로비 클라이언트와의 접속을 자동적으로 확립한다. Initialize 를 호출해, 로비에서 기동되고 있는데, 로비 어플리케이션 인터페이스가 로비 클라이언트 프로세스와 통신할 수 없는 경우,Initialize 는 4 초 후에 타임 아웃 한다. 이 경우,Initialize 은 DPNERR_TIMEDOUT 를 돌려주지만, 성공이다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication::RegisterProgram

로비아웨아아프리케이션을 DirectPlay 에 등록한다. 로비에 의한 기동을 가능하게 하려면 , 어플리케이션을 등록할 필요가 있다.

HRESULT RegisterProgram(
PDPL_PROGRAM_DESC pdplProgramDesc,
const DWORD dwFlags
);

파라미터

pdplProgramDesc
등록하는 로비 대응 어플리케이션을 기술하는 DPL_PROGRAM_DESC 구조체에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

주의

어플리케이션의 등록은 한 번만 실시할 필요가 있다. 어플리케이션을 언인스톨 하면 와,IDirectPlay8LobbiedApplication::UnRegisterProgram 메소드를 호출해 등록을 해제할 필요가 있다.

Microsoft DirectX® 8.0 에서는,RegisterProgram 을 사용할 필요가 있다. 어플리케이션 정보를 레지스트리에 수동으로 설정할 수 없다. 이 인터페이스를 사용하지 않으면 어플리케이션은 이식하지 못하고, DirectPlay 의 장래의 버젼과 호환성이 없어진다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication::Send

로비 어플리케이션으로부터 로비 클라이언트에 메세지를 송신한다.

HRESULT Send(
const DPNHANDLE hConnection,
BYTE *const pBuffer,
const DWORD pBufferSize,
const DWORD dwFlags
);

파라미터

hConnection
메세지의 송신지 로비 클라이언트를 지정하는 DPNHANDLE 형의 변수. 다음의 플래그도 지정할 수 있다.
DPLHANDLE_ALLAPPLICATIONS
지정한 메세지가, 접속하고 있는 모든 로비 클라이언트에 송신된다.
pBuffer
메세지 버퍼를 보관 유지하는 BYTE 형의 변수에의 포인터.
pBufferSize
pBuffer 파라미터에 메세지 버퍼의 사이즈 (바이트 단위)를 지정하는 DWORD 형의 변수. 이 파라미터는 1 바이트 이상, 64 KB 이하가 아니면 안된다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM
DPNERR_SENDTOOLARGE

주의

밧파사이스가 64 KB 보다 큰 경우, 메소드는 DPNERR_SENDTOOLARGE 를 돌려준다. 버퍼 사이즈가 0 으로 설정되어 있는 경우, 메소드는 DPNERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication::UnRegisterProgram

IDirectPlay8LobbiedApplication::RegisterProgram 메소드에 의해 등록된 로비아웨아아프리케이션의 등록을 해제한다.

HRESULT UnRegisterProgram(
GUID* pguidApplication,
const DWORD dwFlags

);

파라미터

pguidApplication
등록을 해제하는 어플리케이션의 GUID 에의 포인터.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication::UpdateStatus

접속되고 있는 로비 클라이언트 상태를 갱신한다.

HRESULT UpdateStatus(
const DPNHANDLE hConnection,
const DWORD dwStatus,
const DWORD dwFlags
);

파라미터

hConnection
로비 클라이언트를 지정하는 DPNHANDLE 형의 변수. 다음의 플래그도 지정할 수 있다.
DPLHANDLE_ALLAPPLICATIONS
접속 떠날 수 있어 모든 로비 클라이언트에 상태의 갱신이 송신된다.
dwStatus
로비 클라이언트와 로비 어플리케이션간 상태를 나타내는 다음의 플래그중 한쪽이 저장 되는 DWORD 형의 변수.
DPLSESSION_CONNECTED
로비 클라이언트와 로비 어플리케이션은 현재 접속되고 있다.
DPLSESSION_COULDNOTCONNECT
로비 클라이언트는 로비 어플리케이션에 접속할 수 없었다.
DPLSESSION_DISCONNECTED
로비 클라이언트와 로비 어플리케이션은 현재 접속 해제되고 있다.
DPLSESSION_TERMINATED
로비 클라이언트와 로비 어플리케이션의 사이의 접속은 종료했다.
DPLSESSION_HOSTMIGRATED
접속에 관련지을 수 있었던 피어 오브젝트는, 호스트의 이행을 하는 세션에 관여한다. 로컬 클라이언트는 신규 호스트는 아니다.
DPLSESSION_HOSTMIGRATEDHERE
접속에 관련지을 수 있었던 피어 오브젝트는, 호스트의 이행을 하는 세션에 관여한다. 로컬 클라이언트가 신규 호스트가 된다.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication::GetConnectionSettings

지정된 접속의 접속 설정 세트를 취득한다. 이러한 설정은,IDirectPlay8LobbyClient::ConnectApplication ,IDirectPlay8LobbyClient::SetConnectionSettings , 또는 IDirectPlay8LobbiedApplication::SetConnectionSettings 의 각 메소드의 호출에 의해 설정할 수 있다.

접속 설정을 취득 하면, 유저에게 돌려주어지는 각 주소 오브젝트에 참조가 추가된다. 따라서, 구조체의 처리가 종료하면(자), 유저는 각 주소 오브젝트에 대해서 Release 를 호출할 필요가 있다.

HRESULT GetConnectionSettings(
const DPNHANDLE hLobbyClient,
DPL_CONNECTION_SETTINGS *const pdplSessionInfo,
DWORD* pdwInfoSize,
const DWORD dwFlags
);

파라미터

hLobbyClient
설정을 취득하는 접속의 핸들.
pdplSessionInfo
지정한 접속의 접속 설정을 받는 DPL_CONNECTION_SETTINGS 구조체에의 포인터.
pdwInfoSize
pdplSessionInfo 구조체로 지정된 버퍼의 사이즈 (바이트 단위)를 보관 유지하는 DWORD 에의 포인터. 버퍼가 접속 설정을 보관 유지 가능한 한의 크기가 아닌 경우, DPNERR_BUFFERTOOSMALL 가 돌려주어진다. 이 값에는 필요한 버퍼 사이즈가 설정된다. 성공했을 경우, 지정된 버퍼에 기입해진 바이트수가 이 값에 들어간다.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8LobbiedApplication::SetConnectionSettings

지정된 접속에 관련짓는 접속 설정을 설정한다. 이 메소드를 호출하면,hConnection 로 지정한 클라이언트에 송신하는 DPL_MSGID_CONNECTION_SETTINGS 가 생성된다.

접속 설정을 설정 하면, 호출로 지정한 각 주소 오브젝트에 로비 어플리케이션이 참조를 추가한다.

HRESULT SetConnectionSettings(
const DPNHANDLE hConnection,
const DPL_CONNECTION_SETTINGS *const pdplConnectSettings,
const DWORD dwFlags
);

파라미터

hConnection
설정을 설정하는 접속의 핸들. 다음의 플래그도 지정할 수 있다.
DPLHANDLE_ALLAPPLICATIONS
접속 설정이, 접속 떠날 수 있어 모든 로비 클라이언트에 대해서 갱신된다.
pdplConnectSettings
지정된 접속에 관련지을 수 있었던 설정을 보관 유지하는 DPL_CONNECTION_SETTINGS 구조체에의 포인터.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


IDirectPlay8Address

IDirectPlay8Address 인터페이스는, Microsoft® DirectPlay® 의 주소의 생성과 조작에 사용하는 범용적인 주소 설정 메소드를 갖추고 있다. 이 인터페이스는, CLSID_DirectPlayAddress COM 오브젝트에 의해 이용할 수 있는 인터페이스의 1 개이다. 이 인터페이스를 지원 하는 오브젝트를 생성 하려면 , IID_IDirectPlayAddress8 인터페이스를 지정하는 CLSID CLSID_DirectPlayAddress 의 CoCreateInstanceEx 메소드를 사용한다.

IDirectPlay8Address 인터페이스에는, 다음의 메소드가 있다.

IDirectPlay8Address 메소드 | BuildFromURLW
 | BuildFromURLA
 | Duplicate
 | SetEqual
 | IsEqual
 | Clear
 | GetURLW
 | GetURLA
 | GetSP
 | GetUserData
 | SetSP
 | SetUserData
 | GetNumComponents
 | GetComponentByName
 | GetComponentByIndex
 | AddComponent
 | GetDevice
 | SetDevice
 | BuildFromDPADDRESS

주의

메세지를 전달하려면 , 멀티 플레이어 게임의 각 참가자가 일의의 주소를 가지고 있을 필요가 있다. 주소는, 어플리케이션을 실행하고 있는 컴퓨터를 참조하는지 (디바이스 주소), 어플리케이션이 통신할 필요가 있는 컴퓨터를 참조할 수 있다 (호스트 주소).

DirectPlay 는 주소를 URL 로서 나타낸다. URL 는, DirectPlay API 와의 수수를 할 수 있도록(듯이), 주소 오브젝트에 캡슐화된다. 일반적으로, 주소 URL 는, 다음의 순서에 따르는 3 개의 기본 요소로 구성되는 캐릭터 라인이다. 스킴, 스킴 separator, 및 데이터 캐릭터 라인.

모든 DirectPlay 주소는 "x-directplay" 를 스킴으로서 사용해,":/" 를 스킴 separator로서 사용한다. separator로서 ":/" 를 사용 하면, 후에 계속되는 데이터가 불투명한 것을 나타낸다. 바꾸어 말하면(자), 데이터 캐릭터 라인은 어느 인터넷 표준에도 적합하고 있지 않고, 통지없이 수취하는 측 어플리케이션에 건네줄 필요가 있다. 따라서, DirectPlay 의 모든 URL 는 다음의 형식이 된다.

x-directplay:/[data string]

주소 오브젝트를 처리하려면 , 2 개의 기본적인 방법이 있다.

  • 보통의 캐릭터 라인 조작 방법을 사용해, 데이터 캐릭터 라인을 직접 처리한다.
  • 데이터 캐릭터 라인의 개별의 요소를 취득 또는 수정하려면 ,IDirectPlay8Address 에서 공개되는 메소드를 사용한다.

DirectPlay 주소의 상세한 것에 대하여는, 「DirectPlay 아드레싱」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::BuildFromURLW

오브젝트를, DirectPlay 8 URL 의 주소에 동일하게 설정한다. 또, 오브젝트의 내용을 소거한다.

HRESULT BuildFromURLW(
WCHAR* pwszSourceURL
);

파라미터

pwszSourceURL
올바르고 포맷 된 DirectPlay 8 주소를 보관 유지하는 NULL 로 끝나는 Unicode 캐릭터 라인에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPOINTER
DPNERR_INVALIDURL
DPNERR_NOTALLOWED

주의

Dpaddr.h 헤더 파일은, 리터럴 캐릭터 라인 대신에, URL 의 생성에 사용할 수 있는 표준 캐릭터 라인의 수를 정의한다. 캐릭터 라인명은 모두, DPNA_XXX 라고 하는 형식을 취한다. 예를 들어, URL 헤더를 L"x-directplay:/" 로 하는 대신에, DPNA_HEADER 를 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::BuildFromURLA

오브젝트를 DirectPlay 8 URL 로 지정되고 있는 오브젝트에 동일하게 설정한다. 또, 오브젝트의 내용을 소거한다.

HRESULT BuildFromURLA(
CHAR* pszSourceURL
);

파라미터

pszSourceURL
올바르고 포맷 된 DirectPlay 8 주소를 보관 유지하는 NULL 로 끝나는 ANSI 캐릭터 라인에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPOINTER
DPNERR_INVALIDURL
DPNERR_NOTALLOWED

주의

Dpaddr.h 헤더 파일은, 리터럴 캐릭터 라인 대신에, URL 의 생성에 사용할 수 있는 표준 캐릭터 라인의 수를 정의한다. 캐릭터 라인명은 모두, DPNA_XXX 라고 하는 형식을 취한다. 예를 들어, URL 헤더를 L"x-directplay:/" 로 하는 대신에, DPNA_HEADER 를 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::Duplicate

이 오브젝트의 주소를 복제하는 DirectPlay Address 오브젝트를 생성 한다.

HRESULT Duplicate(
PDIRECTPLAY8ADDRESS* ppdpaNewAddress
);

파라미터

ppdpaNewAddress
복제 오브젝트의 IDirectPlay8Address 포인터를 받는 포인터의 주소. DirectPlay 는, 이 인터페이스에 대한 참조 카운트를 인크리먼트(increment) 한다. 인터페이스가 불필요하게 되면(자), 해방할 필요가 있다.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_GENERIC

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::SetEqual

불려 가는 오브젝트의 내용을 메소드에게 건네지는 주소 오브젝트의 내용에 일치하도록(듯이) 설정한다.

HRESULT SetEqual(
PDIRECTPLAY8ADDRESS pdpaAddress
);

파라미터

pdpaAddress
이 오브젝트가 설정되는 DirectPlay8Address 오브젝트에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDADDRESSFORMAT
DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::IsEqual

2 개의 주소가 동일한가 비교한다.

HRESULT IsEqual(
PDIRECTPLAY8ADDRESS pdpaAddress
);

파라미터

pdpaAddress
오브젝트내에 포함되는 주소와 비교하는 주소.

반환값

성공했을 경우는, 다음의 몇개의 값을 돌려준다.

DPNSUCCESS_EQUAL
2 개의 주소는 동일하다.
DPNSUCCESS_NOTEQUAL
2 개의 주소는 동일하지 않다.

실패했을 경우는, 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDADDRESSFORMAT
DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER

주의

이 메소드는,pdpaAddress 파라미터로 지정된 주소의 내용을 확인해, 이 메소드가 불려 간 오브젝트내에 포함되는 주소와 비교한다. 이 메소드는, 어느 주소의 내용에도 영향을 주지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::Clear

주소 오브젝트를 하늘의 주소에 리셋 한다.

HRESULT Clear();

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_NOTALLOWED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::GetURLW

이 오브젝트에 의해 나타나는 DirectPlay 8 주소의 URL 캐릭터 라인을 취득한다.

HRESULT GetURLW(
WCHAR* pwszURL,
PDWORD pdwNumChars
);

파라미터

pwszURL
이 오브젝트가 나타내는 URL 를 받는 포인터의 주소. pdwNumChars 가 0 을 보관 유지하는 DWORD 를 나타내는 경우, 이 파라미터에 NULL 를 지정할 수 있다.
pdwNumChars
지정한 버퍼를 보관 유지할 수 있는 문자수 (NULL 터미네이터를 포함한다)를 보관 유지하는 DWORD 에의 포인터. 성공의 경우, 이 값에는 지정한 버퍼에 기입해진 문자수 (NULL 터미네이터를 포함한다)가 보관 유지된다. 실패의 경우, 이 값에는 URL 의 보관 유지에 필요한 문자수 (NULL 터미네이터를 포함한다)가 보관 유지되어 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_GENERIC
DPNERR_INVALIDURL
DPNERR_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::GetURLA

오브젝트에 의해 나타나는 Microsoft® DirectPlay® 주소의 URL 캐릭터 라인을 취득한다. (ANSI 버젼)

HRESULT GetURLA(
CHAR* pszURL,
PDWORD pdwNumChars
);

파라미터

pszURL
이 오브젝트가 나타내는 URL 를 받는 포인터의 주소. pdwNumChars 가 0 을 보관 유지하는 DWORD 를 나타내는 경우, 이 파라미터에 NULL 를 지정할 수 있다.
pdwNumChars
지정한 버퍼를 보관 유지할 수 있는 문자수 (NULL 터미네이터를 포함한다)를 보관 유지하는 DWORD 에의 포인터. 성공의 경우, 이 값에는 지정한 버퍼에 기입해진 문자수 (NULL 터미네이터를 포함한다)가 보관 유지된다. 실패의 경우, 이 값에는 URL 의 보관 유지에 필요한 문자수 (NULL 터미네이터를 포함한다)가 보관 유지되어 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_GENERIC
DPNERR_INVALIDURL
DPNERR_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::GetSP

주소 오브젝트의 서비스 프로바이더 GUID 를 취득한다. 서비스 프로바이더가 지정되어 있지 않은 경우, 이 메소드는 DPNERR_DOESNOTEXIST 를 돌려준다.

HRESULT GetSP(
GUID* pguidSP
);

파라미터

pguidSP
주소 오브젝트의 서비스 프로바이더를 받는 GUID 에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_DOESNOTEXIST
DPNERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::GetUserData

주소 오브젝트의 유저 데이터를 취득한다. 이 주소 오브젝트에 유저 데이터가 존재하지 않는 경우, 이 메소드는 DPNERR_DOESNOTEXIST 를 돌려준다.

HRESULT GetUserData(
void* pvUserData,
PDWORD pdwBufferSize
);

파라미터

pvUserData
이 주소로부터 유저 데이터를 받는 버퍼에의 포인터. 필요한 사이즈를 취득하려면 , 이 파라미터에 NULL 를 설정해,pdwBufferSize 의 DWORD 를 0 으로 설정한다.
pdwBufferSize
pvUserData 가 가리키는 버퍼 사이즈 (바이트 단위). pvUserData 가 NULL 의 경우, 이 파라미터는 0 을 보관 유지하는 DWORD 를 나타내지 않으면 안 된다. 출력으로는, 보관 유지되는 DWORD 는 버퍼에 기입해지는 바이트수로 설정된다. 실패의 경우, 여기에는 유저 데이터의 취득에 필요한 바이트수가 보관 유지되어 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_DOESNOTEXIST
DPNERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::SetSP

주소 오브젝트의 서비스 프로바이더 GUID 를 설정한다. 이 주소에 서비스 프로바이더가 지정되고 있는 경우, 덧쓰기된다.

HRESULT SetSP(
const GUID *const pguidSP
);

파라미터

pguidSP
서비스 프로바이더 GUID 에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::SetUserData

주소 오브젝트에 유저 데이터를 설정한다. 이 주소에 유저 데이터가 존재하는 경우는, 이 호출로 덧쓰기된다.

HRESULT SetUserData(
const void *const pvUserData,
const DWORD dwDataSize
);

파라미터

pvUserData
주소의 유저 데이터 섹션에 있는 데이터를 보관 유지하는 버퍼에의 포인터. NULL 로 설정해, 유저 데이터를 소거한다.
dwDataSize
pvUserData 의 데이터 사이즈 (바이트 단위). pvUserData 가 NULL 인 경우, 0 으로 설정해 둔다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::GetNumComponents

주소내의 컴퍼넌트의 수를 취득한다.

HRESULT GetNumComponents(
PDWORD pdwNumComponents
);

파라미터

pdwNumComponents
이 주소 오브젝트의 컴퍼넌트수를 받는 DWORD 에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 다음의 에러값을 돌려준다.

DPNERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::GetComponentByName

지정된 키의 컴퍼넌트에 관한 정보를 취득한다. 컴퍼넌트의 값은 네이티브인 포맷으로 취득된다. 컴퍼넌트 키가 발견되지 않는 경우, DPNERR_DOESNOTEXIST 가 돌려주어진다.

컴퍼넌트의 값은 네이티브인 포맷으로 취득된다. 따라서, 컴퍼넌트의 값이 DWORD 인 경우, 이 호출에 의해 DWORD 가 취득된다. 즉, 버퍼 사이즈는 4 이며,pvBuffer 는 PDWORD 에 재설정된다.

HRESULT GetComponentByName(
const WCHAR *const pwszName,
void* pvBuffer,
PDWORD pdwBufferSize,
PDWORD pdwDataType
);

파라미터

pwszName
취득하는 컴퍼넌트의 이름을 지정하는 String.
pvBuffer
컴퍼넌트의 값에 저장 되는 데이터를 취득하는 버퍼. 필요한 사이즈를 취득하려면 , 이 파라미터에 NULL 를 지정해,pdwBufferSize 가 가리키는 DWORD 에 0 을 지정한다. 이 경우, 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다.
pdwBufferSize
입력으로는,pvBuffer 가 가리키는, 버퍼의 사이즈 (바이트 단위)를 보관 유지하는 DWORD 에의 포인터. 출력으로는, 성공의 경우는 버퍼에 기입해진 바이트수, 실패의 경우는 데이터의 저장에 필요한 바이트수를 보관 유지하는 DWORD 에의 포인터.
pdwDataType
이 파라미터가 가리키는 DWORD. 이 컴퍼넌트에 저장 되는 데이터형으로 설정된다. 다음의 어느 쪽인가에 설정할 수 있다.
DPNA_DATATYPE_STRING
데이터는 NULL 종단 캐릭터 라인이다.
DPNA_DATATYPE_DWORD
데이터는 DWORD 이다.
DPNA_DATATYPE_GUID
데이터는 GUID 이다.
DPNA_DATATYPE_BINARY
데이터는 미처리의 바이너리이다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_DOESNOTEXIST
DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::GetComponentByIndex

지정된 인덱스의 컴퍼넌트에 관한 정보를 취득한다. 컴퍼넌트의 값은 네이티브인 포맷으로 취득된다. 컴퍼넌트 키가 발견되지 않는 경우, 메소드는 DPNERR_DOESNOTEXIST 를 돌려준다.

컴퍼넌트의 값은 네이티브인 포맷으로 취득된다. 따라서, 컴퍼넌트의 값이 DWORD 인 경우, 이 호출에 의해 DWORD 가 취득된다. 즉, 버퍼 사이즈는 4 이며,pvBuffer 는 PDWORD 에 재설정된다.

HRESULT GetComponentByIndex(
const DWORD dwComponentID,
WCHAR* pwszName,
PDWORD pdwNameLen,
void* pvBuffer,
PDWORD pdwBufferSize,
PDWORD pdwDataType
);

파라미터

dwComponentID
취득하는 컴퍼넌트의 인덱스. 이 값은 0 으로부터 시작되어,[0..GetNumComponents()-1] 의 범위로 한다.
pwszName
호출이 성공했을 경우에 컴퍼넌트의 이름을 취득하는 버퍼. 필요한 사이즈를 취득하려면 , 이 파라미터에 NULL 를 지정해,pdwNameBufferSize 가 가리키는 DWORD 에 0 을 지정한다. 이 경우, 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다.
pdwNameLen
입력으로는,pwszName 가 가리키는, 버퍼의 사이즈 (문자 단위, NULL 터미네이터를 포함한다)를 보관 유지하는 DWORD 에의 포인터. 출력으로는, 성공의 경우는 버퍼에 기입해진 문자수 (NULL 터미네이터를 포함한다), 실패의 경우는 이 값의 저장에 필요한 문자수 (NULL 터미네이터를 포함한다)를 보관 유지하는 DWORD 에의 포인터 .
pvBuffer
컴퍼넌트의 값에 저장 되는 데이터를 취득하는 버퍼. 필요한 사이즈를 취득하려면 , 이 파라미터에 NULL 를 지정해,pdwBufferSize 가 가리키는 DWORD 에 0 을 지정한다. 이 경우, 메소드는 DPNERR_BUFFERTOOSMALL 를 돌려준다.
pdwBufferSize
입력으로는,pvBuffer 가 가리키는, 버퍼의 사이즈 (바이트 단위)를 보관 유지하는 DWORD 에의 포인터. 출력으로는, 성공의 경우는 버퍼에 기입해진 바이트수, 실패의 경우는 데이터의 저장에 필요한 바이트수를 보관 유지하는 DWORD 에의 포인터.
pdwDataType
이 파라미터가 가리키는 DWORD. 이 컴퍼넌트에 저장 되는 데이터형으로 설정된다. 다음의 어느 쪽인가에 설정할 수 있다.
DPNA_DATATYPE_STRING
데이터는 NULL 종단 캐릭터 라인이다.
DPNA_DATATYPE_DWORD
데이터는 DWORD 이다.
DPNA_DATATYPE_GUID
데이터는 GUID 이다.
DPNA_DATATYPE_BINARY
데이터는 미처리의 바이너리이다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_DOESNOTEXIST
DPNERR_INVALIDPARAM

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::AddComponent

주소에 컴퍼넌트를 추가한다. 컴퍼넌트가 주소의 일부인 경우, 이 호출에 의해 새로운 값에 옮겨진다.

이 호출을 실시하면, 값은 네이티브인 포맷으로 지정된다. 따라서, lpvData 파라미터는, 네이티브 포맷으로 데이터를 보관 유지하는 변수에 재설정된 포인터로 할 필요가 있다. 예를 들어, 컴퍼넌트가 GUID 인 경우,lpvData 파라미터에는 GUID 에 재설정된 포인터를 지정할 필요가 있다.

이 메소드는, 정의가 끝난 컴포넌트 타입이 올바른 포맷일지 어떨지를 확인한다.

HRESULT AddComponent(
const WCHAR *const pwszName,
const void *const lpvData,
const DWORD dwDataSize,
const DWORD dwDataType
);

파라미터

pwszName
컴퍼넌트의 키를 보관 유지하는, NULL 로 끝나는 Unicode 캐릭터 라인.
lpvData
지정된 키에 관련지을 수 있었던 값을 보관 유지하는 버퍼에의 포인터. 데이터는 네이티브 포맷으로 지정할 필요가 있다.
dwDataSize
lpvData 에 보관 유지되는 버퍼의 데이터 사이즈 (바이트 단위). 사이즈는 데이터형에 따라서 다르다. 사이즈가 올바르게 지정되어 있지 않은 경우, 이 메소드는 DPNERR_INVALIDPARAM 를 돌려준다.
DWORD
사이즈 = sizeof( DWORD )
GUID
사이즈 = sizeof( GUID )
String
사이즈 = NULL 터미네이터를 포함한 캐릭터 라인의 사이즈 (바이트 단위).
dwDataType
이 키에 관련지을 수 있었던 값의 데이터형. 데이터형은, 다음의 어느쪽이든을 사용할 수 있다.
DPNA_DATATYPE_STRING
데이터는 NULL 종단 캐릭터 라인이다.
DPNA_DATATYPE_DWORD
데이터는 DWORD 이다.
DPNA_DATATYPE_GUID
데이터는 GUID 이다.
DPNA_DATATYPE_BINARY
데이터는 미처리의 바이너리 포맷이다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::GetDevice

주소 오브젝트의 로컬 디바이스 GUID 를 취득한다. 디바이스가 지정되어 있지 않은 경우, 이 메소드는 DPNERR_DOESNOTEXIST 를 돌려준다.

HRESULT GetDevice(
GUID* pguidDevice
);

파라미터

pguidDevice
주소 오브젝트의 디바이스를 받는 GUID 에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_DOESNOTEXIST
DPNERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::SetDevice

주소 오브젝트의 로컬 디바이스 GUID 를 설정한다. 이 주소에 로컬 디바이스가 지정되고 있는 경우, 덧쓰기된다.

HRESULT SetDevice(
const GUID *const pguidDevice
);

파라미터

pguidDevice
로컬 디바이스의 GUID 에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8Address::BuildFromDPADDRESS

현재의 오브젝트의 내부 주소에, 지정된 DirectPlay 4 주소에 상당하는 DirectPlay 8 의 주소를 설정한다. 이 메소드의 목적은, 로비 개발자가 낡은 로비 코드를 사용해 새로운 Microsoft® DirectPlay® 인터페이스로 게임을 기동할 수 있도록(듯이) 하는 것에 있다.

이 메소드는, 지정된 주소의 주소 컴퍼넌트를 열거해, 대응하는 요소를 DirectPlay 8 주소에 추가한다.

HRESULT BuildFromDPADDRESS(
LPVOID pvAddress,
DWORD dwDataSize
);

파라미터

pvAddress
DirectPlay 8 주소의 포맷에 변환되는 DirectPlay4 주소에의 포인터.
dwDataSize
pvAddress 파라미터에 보관 유지되는 데이터의 사이즈.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDADDRESSFORMAT
DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER

주의

이 메소드는 DirectPlay4 주소로부터 DirectPlay 8 주소를 생성 한다. 이 메소드는, 새로운 주소를 생성 하기 전에, 모든 요소의 현행 주소를 소거한다.

이 메소드에는 다음의 제한이 있다.

  • 모뎀을 식별 하면 와, DirectPlay 4 에서는 모뎀명을 사용하고 있지만, DirectPlay 8 에서는 GUID 를 사용하고 있기 (위해)때문에, 이 메소드로 DPAID_Modem 주소 요소는 매핑 할 수 없다.
  • 정의 끝난 DirectPlay 4 주소 요소의 일부에서는 없는 DirectPlay 4 주소의 요소는 에러가 되어, 반환값은 DPNERR_INVALIDADDRESSFORMAT 가 된다. DirectPlay 4 주소 요소의 상세한 리스트에 대해서는, DirectPlay 4 의 문서의 DirectPlay 주소에 관한 설명을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8AddressIP

IDirectPlay8AddressIP 는, CLSID_DirectPlayAddress COM 오브젝트로부터 이용할 수 있는 인터페이스이다. 이 인터페이스는 IP 프로바이더 전용의 애드레싱 서비스에 사용된다.

IDirectPlay8AddressIP 인터페이스에는, 다음의 메소드가 있다.

IDirectPlay8AddressIP 메소드 | BuildFromSockAddr
 | BuildAddress
 | BuildLocalAddress
 | GetSockAddress
 | GetLocalAddress
 | GetAddress

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8AddressIP::BuildFromSockAddr

유효한 SOCKADDR 구조체로부터 리모트의 DirectPlay 8 IP 주소를 생성 한다. SOCKADDR 구조체는 IP 주소를 지정할 필요가 있다. 주소의 포맷이 올바르지 않은 경우, DPNERR_INVALIDPARAM 가 돌려주어진다.

호출이 성공했을 경우는, 다음의 요소를 수반하는 유효한 리모트 주소가 된다.

  • DPNA_KEY_PROVIDER = CLSID_DP8SP_TCPIP
  • DPNA_KEY_HOSTNAME = 지정 호스트명
  • DPNA_KEY_PORT = 지정 포토

호출전의 오브젝트에 포함되는 주소 정보는 모두 소거된다.

HRESULT BuildFromSockAddr(
const SOCKADDR *const pSockAddr
);

파라미터

pSockAddr
SOCKADDR 폼으로 지정된 유효한 UDP 주소.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8AddressIP::BuildAddress

호스트명과 포토로부터 리모트의 DirectPlay 8 IP 주소를 생성 한다. 호출이 성공했을 경우는, 다음의 요소를 수반하는 유효한 리모트 주소가 된다.

  • DPNA_KEY_PROVIDER = CLSID_DP8SP_TCPIP
  • DPNA_KEY_HOSTNAME = 지정 호스트명
  • DPNA_KEY_PORT = 지정 포토

호출전의 오브젝트에 포함되는 주소 정보는 모두 소거된다.

HRESULT BuildAddress(
const WCHAR *const wszAddress,
const USHORT usPort
);

파라미터

wszAddress
리모트 호스트 주소에는, 닷으로 단락지어진 인터넷 주소 (127.0. 0.1 등) 또는 유효한 호스트명 (example.microsoft.com 등)을 지정할 수 있다.
usPort
접속처의 리모트 호스트의 포토.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

주의

주 DPNSVR 는, 복수의 프로세스가 열거용으로 단일의 포토를 공유할 수 있도록(듯이) 하는 DirectPlay 의 기능이다. 디바이스 주소를 구축하는 경우, 또는 접속을 실시하는 경우는, DPNA_DPNSVR_PORT 플래그를 사용하지 않는 것. 이 플래그는 열거에만 사용한다. 열거 주소에 포토의 요소를 추가하지 않는 경우, 플래그에 의해 나타내지는 포토가 자동적으로 그 주소에 추가된다. DPNSVR 의 상세한 것에 대하여는, 「DirectPlay DPNSVR 어플리케이션의 사용법」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8AddressIP::BuildLocalAddress

디바이스와 포토로부터 로컬의 DirectPlay 8 IP 주소를 생성 한다. 호출이 성공했을 경우는, 다음의 요소를 수반하는 유효한 리모트 주소가 된다.

  • DPNA_KEY_PROVIDER = CLSID_DP8SP_TCPIP
  • DPNA_KEY_DEVICE= 지정 디바이스
  • DPNA_KEY_PORT = 지정 포토

호출전의 오브젝트에 포함되는 주소 정보는 모두 소거된다.

HRESULT BuildLocalAddress(
const GUID *const pguidAdapter,
const USHORT usPort
);

파라미터

pguidAdapter
호스트 하는 로컬 디바이스의 식별자.
usPort
호스트 하는 로컬 디바이스 위에의 포토. 이 값을 0 으로 설정 하면, DirectPlay 8.0 은 자동적으로 포토를 선택할 수 있다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

주의

주 DPNSVR 는, 복수의 프로세스가 열거용으로 단일의 포토를 공유할 수 있도록(듯이) 하는 DirectPlay 의 기능이다. 디바이스 주소를 구축하는 경우, 또는 접속을 실시하는 경우는, DPNA_DPNSVR_PORT 플래그를 사용하지 않는 것. 이 플래그는 열거에만 사용한다. 열거 주소에 포토의 요소를 추가하지 않는 경우, 플래그에 의해 나타내지는 포토가 자동적으로 그 주소에 추가된다. DPNSVR 의 상세한 것에 대하여는, 「DirectPlay DPNSVR 어플리케이션의 사용법」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8AddressIP::GetSockAddress

이 오브젝트가 나타내는 주소를 기술하는 SOCKADDR 구조체의 리스트를 취득한다. 오브젝트로 지정된 호스트명에 DNS 룩 업이 필요한 경우는, DNS 룩 업이 실행된다. 따라서, DNS 에의 문의중, 이 메소드는 블록 되는 일이 있다. 또, 호스트명은 복수의 주소에 해결되는 일도 있다.

성공하려면 , 보관 유지되고 있는 주소에 적어도 다음의 요소가 포함되어 있을 필요가 있다.

  • DPNA_KEY_PROVIDER
  • DPNA_KEY_HOSTNAME
  • DPNA_KEY_PORT = 지정 포토
HRESULT GetSockAddress(
SOCKADDR* psockAddress,
PDWORD pdwAddressBufferSize
);

파라미터

psockAddress
SOCKADDR 구조체의 배열을 취득하는 버퍼에의 포인터. 호스트가 해결되는 주소 마다 1 개의 SOCKADDR 구조체가 있다.
pdwAddressBufferSize
psockAddresses 로 지정되는 버퍼의 사이즈 (바이트 단위). 성공했을 경우, 지정된 버퍼에 기입해진 바이트수가 이 파라미터에 들어간다. 실패했을 경우,SOCKADDR 구조체의 배열의 취득에 필요한 바이트수가 이 파라미터에 들어간다. 이 파라미터를 SOCKADDR 구조체의 사이즈로 나눗셈 하면, 돌려주어진 배열내에 존재하는 항목수를 알 수 있다.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8AddressIP::GetLocalAddress

DirectPlay 8 IP 주소로부터 로컬 주소 정보를 취득한다. 성공하려면 , 보관 유지되고 있는 주소에 적어도 다음의 요소가 포함되어 있을 필요가 있다.

  • DPNA_KEY_PROVIDER
  • DPNA_KEY_DEVICE
  • DPNA_KEY_PORT
HRESULT GetLocalAddress(
GUID* pguidAdapter,
USHORT* pusPort
);

파라미터

pguidAdapter
이 주소로 지정된 로컬 디바이스의 GUID 를 취득하는 GUID 에의 포인터.
pusPort
이 로컬 주소로 지정된 포토를 보관 유지하는 USHORT 에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


IDirectPlay8AddressIP::GetAddress

리모트의 DirectPlay 8 IP 주소로부터 리모트 주소 정보를 취득한다. 성공하려면 , 보관 유지되고 있는 주소에 적어도 다음의 요소가 포함되어 있을 필요가 있다.

  • DPNA_KEY_PROVIDER
  • DPNA_KEY_HOSTNAME
  • DPNA_KEY_PORT = 지정 포토
HRESULT GetAddress(
WCHAR* wszAddress,
PDWORD pdwAddressLength,
USHORT* psPort
);

파라미터

wszAddress
호스트명을 받는 버퍼에의 포인터. 이 파라미터를 NULL 로 하면(자), 필요한 사이즈를 취득할 수 있다.
pdwAddressLength
wszAddress 로 지정되는 버퍼의 사이즈 (문자 단위, NULL 터미네이터를 포함한다). 성공했을 경우, 이 파라미터에는 지정된 버퍼에 기입해진 문자수가 들어간다 (NULL 터미네이터를 포함한다). 실패했을 경우, 이 파라미터에는, 호스트명의 취득에 필요한 문자수가 들어간다 (NULL 터미네이터를 포함한다).
psPort
이 로컬 주소로 지정된 포토를 보관 유지하는 USHORT 에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려주어, 실패했을 경우는 다음의 몇개의 에러값을 돌려준다.

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dpaddr.h 로 선언.


함수

Microsoft® DirectPlay® 의 함수를 다음에 나타낸다.

  • DirectPlay8Create
  • DirectPlay8LobbyCreate
  • DirectPlay8AddressCreate
  • DirectPlayVoiceCreate


DirectPlay8Create

DirectPlay8Create 함수는, Dplay8.h 헤더 파일로 정의되는 인터페이스를 생성하기 위한 외부 함수이다.

HRESULT WINAPI DirectPlay8Create(
  GUID* pcIID,
  void** ppvInterface,
  IUnknown* pUnknown
);

파라미터

pcIID
생성 하는 인터페이스 ID 에의 포인터. IID_IDirectPlay8Client, IID_IDirectPlay8Server, 또는 IID_IDirectPlay8Peer 의 몇개의 인터페이스 ID 를 지정할 수 있다.
ppvInterface
새로운 인터페이스 포인터를 받는 변수의 주소.
pUnknown
COM 집성체의 경우는, 제어 오브젝트의 IUnknown 인터페이스의 주소. NULL 로 설정해 둔다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DirectPlay8LobbyCreate

DirectPlay8LobbyCreate 함수는, Dplobby8.h 헤더 파일로 정의되는 로비 인터페이스의 1 개를 생성하기 위한 외부 함수이다.

HRESULT WINAPI DirectPlay8LobbyCreate(
  GUID* pcIID,
  void** ppvInterface,
  IUnknown* pUnknown
);

파라미터

pcIID
생성 하는 인터페이스 ID 에의 포인터. IID_IDirectPlay8LobbiedApplication 또는 IID_IDirectPlay8LobbyClient 의 몇개의 인터페이스 ID 를 지정할 수 있다.
ppvInterface
새로운 인터페이스 포인터를 받는 변수의 주소.
pUnknown
COM 집성체의 경우는, 제어 오브젝트의 IUnknown 인터페이스의 주소. NULL 로 설정해 둔다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


DirectPlay8AddressCreate

DirectPlay8AddressCreate 함수는, Dpaddr.h 헤더 파일로 정의되는 애드레싱 인터페이스의 1 개를 생성하기 위한 외부 함수이다.

HRESULT WINAPI DirectPlay8AddressCreate(
  GUID* pcIID,
  void** ppvInterface,
  IUnknown* pUnknown
);

파라미터

pcIID
생성 하는 인터페이스 ID 에의 포인터. IID_IDirectPlay8Address 또는 IID_IDirectPlay8AddressIP 의 몇개의 인터페이스 ID 를 지정할 수 있다.
ppvInterface
새로운 인터페이스 포인터를 받는 변수의 주소.
pUnknown
COM 집성체의 경우는, 제어 오브젝트의 IUnknown 인터페이스의 주소. NULL 로 설정해 둔다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dpaddr.h 로 선언.


DirectPlayVoiceCreate

DirectPlayVoiceCreate 함수는, Dvoice.h 헤더 파일로 정의되어 Microsoft® DirectPlay® Voice 로 사용되는 인터페이스의 1 개를 생성하기 위한 외부 함수이다.

HRESULT WINAPI DirectPlayVoiceCreate(
  GUID* pcIID,
  void** ppvInterface,
  IUnknown* pUnknown
);

파라미터

pcIID
생성 하는 인터페이스 ID 에의 포인터. IID_IDirectPlayVoiceTest, IID_IDirectPlayVoiceClient, 또는 IID_IDirectPlayVoiceServer 의 몇개의 인터페이스 ID 를 지정할 수 있다.
ppvInterface
새로운 인터페이스 포인터를 받는 변수의 주소.
pUnknown
COM 집성체의 경우는, 제어 오브젝트의 IUnknown 인터페이스의 주소. NULL 로 설정해 둔다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


콜백 함수

Microsoft® DirectPlay® 의 콜백 함수를 다음에 나타낸다.

  • PFNDPNMESSAGEHANDLER
  • PDVMESSAGEHANDLER


PFNDPNMESSAGEHANDLER

PFNDPNMESSAGEHANDLER 는, 어플리케이션 정의의 콜백 함수로,IDirectPlay8Peer ,IDirectPlay8Client ,IDirectPlay8Server ,IDirectPlay8LobbyClient , 및IDirectPlay8LobbiedApplication 인터페이스를 사용해 메세지를 처리한다.

typedef HRESULT (WINAPI *PFNDPNMESSAGEHANDLER)(
  PVOID pvUserContext,
  DWORD dwMessageType,
  PVOID pMessage
);

파라미터

pvUserContext
이 콜백 함수에게 건네지는 어플리케이션 정의 구조체에의 포인터. Initialize 메소드의 pvUserContext 파라미터에 정의된다.
dwMessageType
다음의 메세지 타입의 어느쪽이든 1 개(살). IDirectPlay8Peer ,IDirectPlay8Client , 및 IDirectPlay8Server 의 각 인터페이스에 의해 생성된다. 각 인터페이스는, 유효한 메세지 가운데로, 각각 다른 서브 세트를 사용한다. 상세한 것에 대하여는, 인터페이스의 문서를 참조할것.
  • DPN_MSGID_ADD_PLAYER_TO_GROUP
  • DPN_MSGID_ASYNC_OP_COMPLETE
  • DPN_MSGID_CLIENT_INFO
  • DPN_MSGID_CONNECT_COMPLETE
  • DPN_MSGID_CREATE_GROUP
  • DPN_MSGID_CREATE_PLAYER
  • DPN_MSGID_DESTROY_GROUP
  • DPN_MSGID_DESTROY_PLAYER
  • DPN_MSGID_ENUM_HOSTS_QUERY
  • DPN_MSGID_ENUM_HOSTS_RESPONSE
  • DPN_MSGID_GROUP_INFO
  • DPN_MSGID_HOST_MIGRATE
  • DPN_MSGID_INDICATE_CONNECT
  • DPN_MSGID_INDICATED_CONNECT_ABORTED
  • DPN_MSGID_PEER_INFO
  • DPN_MSGID_RECEIVE
  • DPN_MSGID_REMOVE_PLAYER_FROM_GROUP
  • DPN_MSGID_RETURN_BUFFER
  • DPN_MSGID_SEND_COMPLETE
  • DPN_MSGID_SERVER_INFO
  • DPN_MSGID_TERMINATE_SESSION

    또, Microsoft® DirectPlay® 의 로비 기능이 어플리케이션으로 지원 되고 있는 경우,IDirectPlay8LobbyClient 인터페이스 및IDirectPlay8LobbiedApplication 인터페이스로 생성되는 다음의 메세지 타입의 어느쪽이든을 이 파라미터로 지정할 수 있다. 각 인터페이스는, 유효한 메세지 가운데로, 각각 다른 서브 세트를 사용한다. 상세한 것에 대하여는, 인터페이스의 문서를 참조할것.

  • DPL_MSGID_CONNECT
  • DPL_MSGID_CONNECTION_SETTINGS
  • DPL_MSGID_DISCONNECT
  • DPL_MSGID_RECEIVE
  • DPL_MSGID_SESSION_STATUS
pMessage
메세지 정보를 보관 유지하는 구조체.

반환값

적절한 반환값에 대해서는, 각 메세지의 문서를 참조할것. 문서에 기술이 없는 경우, 이 함수는 S_OK 를 돌려준다.

주의

이 함수는, 복수의 thread로부터 재입 가능한 형식에서 불려 갈 가능성이 있기 (위해)때문에, thread 세이프가 아니면 안된다.

같은 플레이어로부터의 콜백 메세지는, 차례로 늘어놓을 수 있다. 플레이어로부터 메세지를 받아들이면(자), 그 메세지를 처리해, 콜백 함수가 되돌려질 때까지 다른 메세지를 받아들일 것은 없다.

메세지 구조체의 이름은 메세지 타입명과 같지만,"DPN_MSGID" 는 "DPNMSG" 가 된다. 예를 들어,DPN_MSGID_CONNECTION_TERMINATED 메세지 타입은,DPNMSG_CONNECTION_TERMINATED 메세지 구조체를 사용해, 실제의 메세지 정보를 보관 유지한다.

이 콜백 함수를 이행 하는 경우는, 최초로 dwMessageType 파라미터에 돌려주어지는 메세지 타입을 조사해 다음에 메세지 구조체 (pMessage)를 그 타입으로 설정해 메세지 정보를 취득한다. 메세지안에는, 파라미터가 없기 때문에, 정의된 구조체를 가지지 않는 것도 있다. 이러한 메세지의 경우,pMessage 파라미터는 NULL 로 한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


PDVMESSAGEHANDLER

PDVMESSAGEHANDLER 은 어플리케이션에 의해 정의된 콜백 함수이며,IDirectPlayVoiceClient 인터페이스 및 IDirectPlayVoiceServer 인터페이스로 유저에게 메세지를 송신할 경우에 사용된다.

typedef HRESULT (FAR PASCAL *PDVMESSAGEHANDLER)(
  LPVOID pvUserContext,
  DWORD dwMessageType,
  LPVOID lpMessage
);

파라미터

pvUserContext
이 콜백 함수에게 건네지는 어플리케이션 정의 구조체에의 포인터. IDirectPlayVoiceServer::Initialize 메소드 및 IDirectPlayVoiceClient::Initialize 메소드의 lpUserContext 파라미터로 정의된다.
dwMessageType
다음의 메세지 타입의 어느쪽이든 1 개(살).
DVMSGID_CONNECTRESULT
DVMSGID_CREATEVOICEPLAYER
DVMSGID_DELETEVOICEPLAYER
DVMSGID_DISCONNECTRESULT
DVMSGID_GAINFOCUS
DVMSGID_HOSTMIGRATED
DVMSGID_INPUTLEVEL
DVMSGID_LOCALHOSTSETUP
DVMSGID_LOSTFOCUS
DVMSGID_OUTPUTLEVEL
DVMSGID_PLAYEROUTPUTLEVEL
DVMSGID_PLAYERVOICESTART
DVMSGID_PLAYERVOICESTOP
DVMSGID_RECORDSTART
DVMSGID_RECORDSTOP
DVMSGID_SESSIONLOST
DVMSGID_SETTARGETS
lpMessage
메세지 정보를 보관 유지하는 구조체.

반환값

적절한 반환값에 대해서는, 각 메세지의 문서를 참조할것. 문서에 기술이 없는 경우, 이 함수는 S_OK 를 돌려준다.

주의

이 콜백 함수를 이행 하는 경우는, 최초로 dwMessageType 파라미터에 돌려주어지는 메세지 타입을 조사해 다음에 메세지 구조체 (lpMessage)를 그 타입으로 설정해 메세지 정보를 취득할 필요가 있다. 메세지안에는, 파라미터가 없기 때문에, 정의된 구조체를 가지지 않는 것도 있다. 이러한 메세지의 경우,lpMessage 파라미터는 NULL 로 한다.

주 : 이 함수는, 복수가 다른 thread로부터 동시에 불려 갈 가능성이 있다. 이 때문에, thread 세이프 또한 재입 가능하지 않으면 안 된다.

모든 메세지 구조체의 이름은 대응하는 메세지 타입명과 같지만, 접두사는 DVMSGID_ 대신에 DVMSG_ 가 된다. 예를 들어,DVMSGID_RECORDSTART 의 구조체는 DVMSG_RECORDSTART 이다.

메세지 핸들러에 송신되는 구조체는, 호출 처리중만 유효하다. 따라서, 함수에게 건네진 정보를 핸들러 함수가 돌아온 후에 사용하는 경우는, 데이터를 카피할 필요가 있다.

같은 플레이어로부터의 콜백 메세지는, 차례로 늘어놓을 수 있다. 플레이어로부터 메세지를 받아들이면(자), 그 메세지를 처리해, 콜백 함수가 되돌려질 때까지 다른 메세지를 받아들일 것은 없다.

IDirectPlayVoiceClient::Initialize ,IDirectPlayVoiceServer::Initialize ,IDirectPlayVoiceClient::SetNotifyMask , 및 IDirectPlayVoiceServer::SetNotifyMask 의 각 메소드의 호출에 의해 메세지 마스크로 지정된 메세지만이 이 콜백 함수에 송신된다.

DVMSGID_GAINFOCUS 메세지 구조체 및 DVMSGID_LOSTFOCUS 메세지 구조체는, Microsoft® DirectPlay® 의 이 릴리스에는 이행되어 있지 않다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


시스템 메세지

Microsoft® DirectPlay® 메세지는, DirectPlay 콜백 메세지 핸들러에 의해 수신된다. DirectPlay 는 이러한 메세지를 사용해, 시스템으로부터 DirectPlay 어플리케이션에 정보를 전달한다.

  • DirectPlay 서버 메세지
  • DirectPlay 클라이언트 메세지
  • DirectPlay 로비 메세지
  • DirectPlay Voice 메세지

DirectPlay 서버 메세지

모든 Microsoft® DirectPlay® 서버 콜백 메세지 핸들러로 처리해야 하는 메세지를 이하에 나타낸다.

  • DPN_MSGID_CREATE_PLAYER
  • DPN_MSGID_DESTROY_PLAYER
  • DPN_MSGID_INDICATE_CONNECT
  • DPN_MSGID_INDICATED_CONNECT_ABORTED
  • DPN_MSGID_RECEIVE
  • DPN_MSGID_RETURN_BUFFER

다음에 나타내는 메세지는, DirectPlay 서버 콜백 메세지 핸들러에 의해 처리할 수 있지만, 필수의 메세지는 아니다.

  • DPN_MSGID_ADD_PLAYER_TO_GROUP
  • DPN_MSGID_ASYNC_OP_COMPLETE
  • DPN_MSGID_CLIENT_INFO
  • DPN_MSGID_CREATE_GROUP
  • DPN_MSGID_DESTROY_GROUP
  • DPN_MSGID_GROUP_INFO
  • DPN_MSGID_ENUM_HOSTS_QUERY
  • DPN_MSGID_REMOVE_PLAYER_FROM_GROUP
  • DPN_MSGID_SEND_COMPLETE
  • DPN_MSGID_SERVER_INFO

DirectPlay 클라이언트 메세지

모든 DirectPlay 클라이언트 콜백 메세지 핸들러가 처리해야 하는 메세지를 다음에 나타낸다.

  • DPN_MSGID_RECEIVE
  • DPN_MSGID_TERMINATE_SESSION
  • DPN_MSGID_RETURN_BUFFER

다음에 나타내는 메세지는, DirectPlay 클라이언트 콜백 메세지 핸들러에 의해 처리할 수 있지만, 필수의 메세지는 아니다.

  • DPN_MSGID_ASYNC_OP_COMPLETE
  • DPN_MSGID_CLIENT_INFO
  • DPN_MSGID_CONNECT_COMPLETE
  • DPN_MSGID_ENUM_HOSTS_RESPONSE
  • DPN_MSGID_SEND_COMPLETE
  • DPN_MSGID_SERVER_INFO
  • DPN_MSGID_GROUP_INFO

DirectPlay 로비 메세지

로비 클라이언트 및 로비 어플리케이션의 콜백 메세지 핸들러가 처리하는 메세지를 다음에 나타낸다.

  • DPL_MSGID_CONNECT
  • DPL_MSGID_CONNECTION_SETTINGS
  • DPL_MSGID_DISCONNECT
  • DPL_MSGID_RECEIVE
  • DPL_MSGID_SESSION_STATUS

DirectPlay Voice 메세지

Microsoft® DirectPlay® 음성 콜백 메세지 핸들러가 처리하는 메세지를 다음에 나타낸다.

  • DVMSGID_CONNECTRESULT
  • DVMSGID_CREATEVOICEPLAYER
  • DVMSGID_DELETEVOICEPLAYER
  • DVMSGID_DISCONNECTRESULT
  • DVMSGID_GAINFOCUS
  • DVMSGID_HOSTMIGRATED
  • DVMSGID_INPUTLEVEL
  • DVMSGID_LOCALHOSTSETUP
  • DVMSGID_LOSTFOCUS
  • DVMSGID_OUTPUTLEVEL
  • DVMSGID_PLAYEROUTPUTLEVEL
  • DVMSGID_PLAYERVOICESTART
  • DVMSGID_PLAYERVOICESTOP
  • DVMSGID_RECORDSTART
  • DVMSGID_RECORDSTOP
  • DVMSGID_SESSIONLOST
  • DVMSGID_SETTARGETS


DPL_MSGID_CONNECT

로비 클라이언트가 IDirectPlay8LobbyClient::ConnectApplication 메소드를 사용해 로비 어플리케이션에 접속 하면 와, DPL_MSGID_CONNECT 메세지가 생성된다.

DPL_MESSAGE_CONNECT

DPL_MESSAGE_CONNECT 구조체는, DPL_MSGID_CONNECT 메세지와 함께 건네받는다.

typedef struct _DPL_MESSAGE_CONNECT{
    DWORD     dwSize;
    DPNHANDLE hConnectId;
    PDPL_CONNECTION_SETTINGS  pdplConnectionSettings;
    PVOID     pvLobbyConnectData;
    DWORD     dwLobbyConnectDataSize;
    PVOID     pvConnectionContext;
} DPL_MESSAGE_CONNECT, *PDPL_MESSAGE_CONNECT;
dwSize
DPL_MESSAGE_CONNECT 메세지 구조체의 사이즈. 어플리케이션은, 이 구조체를 사용하기 전에, 우선 이 멤버를 설정할 필요가 있다.
hConnectId
접속의 식별로 사용되는 핸들. 이 핸들은, 다음에 IDirectPlay8LobbyClient::Send 및 IDirectPlay8LobbyClient::ReleaseApplication 의 호출에 사용된다.
pdplConnectionSettings
접속 정보를 보관 유지하는 DPL_CONNECTION_SETTINGS 구조체에의 포인터.
pvLobbyConnectData
로비 접속 데이터에의 포인터.
dwLobbyConnectDataSize
pvLobbyConnectData 멤버에 보관 유지된 데이터의 사이즈를 지정하는 DWORD 형의 변수.
pvConnectionContext
이 접속에 관련지을 수 있었던 문맥값. 로피아프리케이션의 경우는, 메세지 핸들러가 이 메세지를 받아들였을 때에 이 파라미터를 설정해, 문맥값을 접속에 관련짓는다. NULL 로 설정 하면, 문맥값을 무효로 할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


DPL_MSGID_CONNECTION_SETTINGS

IDirectPlay8LobbyClient::SetConnectionSettings 가 불려 가면(자), DPL_MSGID_CONNECTION_SETTINGS 메세지가 로비 클라이언트로부터 로비 어플리케이션에 송신된다. IDirectPlay8LobbiedApplication::SetConnectionSettings 가 불려 갔을 경우에도, 로비 어플리케이션으로부터 로비 클라이언트에 이 메세지가 송신된다. 메세지의 내용은, 메세지의 콜백 처리중만 유효하다. 따라서, 메세지에 포함되는 데이터를 사용하기 위해서는, 돌아오기 전에 카피를 생성 할 필요가 있다. 게다가 주소 오브젝트를 사용하려면 , 주소 마다 AddRef 를 호출해, 확실히 참조를 보관 유지할 필요가 있다.

DPL_MESSAGE_CONNECTION_SETTINGS

DPL_MESSAGE_CONNECTION_SETTINGS 구조체는, DPL_MSGID_CONNECTION_SETTINGS 메세지와 함께 건네받는다.

typedef struct _DPL_MESSAGE_CONNECTION_SETTINGS{
    DWORD               dwSize;
    DPNHANDLE           hSender;
    PDPL_CONNECTION_SETTINGS   pdplConnectionSettings;
    PVOID               pvConnectionContext
} DPL_MESSAGE_CONNECTION_SETTINGS, *PDPL_MESSAGE_CONNECTION_SETTINGS;
dwSize
DPL_MESSAGE_CONNECTION_SETTINGS 구조체의 사이즈를 보관 유지한다. sizeof( DPL_MESSAGE_CONNECTION_SETTINGS )로 설정할 필요가 있다.
hSender
이 메세지를 송신한 접속의 핸들을 보관 유지한다.
pdplConnectionSettings
지정된 접속의 접속 설정을 기술하는 DPL_CONNECTION_SETTINGS 구조체에의 포인터를 보관 유지한다.
pvConnectionContext
접속에 대해서 설정되어 있는 문맥값에의 포인터.

주의

로비 어플리케이션의 경우, 문맥값은 DPL_MESSAGE_CONNECT 메세지 구조체의 pvConnectionContext 멤버에 의해 설정된다. 메세지 핸들러가 이 메세지를 받아들였을 경우는, 돌아오기 전에 이 멤버로 설정한 값이, 그 접속의 문맥값이 된다.

로비 클라이언트의 경우, 접속이 성공하면(자),IDirectPlay8LobbyClient::ConnectApplication 메소드의 pvConnectionContext 파라미터가 접속의 문맥값으로서 사용된다.

문맥값은, 로비 클라이언트와 로비 어플리케이션의 사이에 공유되지 않는다. 예를 들어, 로비 접속의 문맥값을,IDirectPlay8LobbyClient 인터페이스에서는 포인터 A 에,IDirectPlay8LobbiedApplication 인터페이스에서는 포인터 B 로 설정했을 경우,IDirectPlay8LobbyClient 인터페이스에서는 포인터 A 가 문맥값이 되어,IDirectPlay8LobbiedApplication 인터페이스에서는 포인터 B 가 문맥값이 된다.

이 기능을 사용할 필요가 없는 경우는, 문맥값을 NULL 로 설정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


DPL_MSGID_DISCONNECT

로비 클라이언트가 IDirectPlay8LobbyClient::ReleaseApplication 메소드를 사용해 로비 어플리케이션으로부터 접속 해제 하면, Microsoft® DirectPlay® 에 의해 DPL_MSGID_DISCONNECT 메세지가 생성된다.

DPL_MESSAGE_DISCONNECT

DPL_MESSAGE_DISCONNECT 구조체에는, DPL_MSGID_DISCONNECT 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPL_MESSAGE_DISCONNECT{
    DWORD     dwSize;
    DPNHANDLE hDisconnectId;
    HRESULT   hrReason;
    PVOID     pvConnectionContext;
} DPL_MESSAGE_DISCONNECT, *PDPL_MESSAGE_DISCONNECT;
dwSize
DPL_MESSAGE_DISCONNECT 메세지 구조체의 사이즈. 어플리케이션은, 이 구조체를 사용하기 전에, 우선 이 멤버를 설정할 필요가 있다.
hDisconnectId
접속 해제 ID 를 지정하는 핸들.
hrReason
접속 해제의 이유.
S_OK
보통의 접속 해제.
DPNERR_CONNECTIONLOST
클라이언트 또는 어플리케이션을 실행하고 있는 프로세스가 이상종료(ABEND) 했을 경우로 설정된다.
pvConnectionContext
접속에 대해서 설정되어 있는 문맥값.

주의

로비 어플리케이션의 경우, 문맥값은 DPL_MESSAGE_CONNECT 메세지 구조체의 pvConnectionContext 멤버에 의해 설정된다. 메세지 핸들러가 이 메세지를 받아들였을 경우는, 돌아오기 전에 이 멤버로 설정한 값이, 그 접속의 문맥값이 된다.

로비 클라이언트의 경우, 접속이 성공하면(자),IDirectPlay8LobbyClient::ConnectApplication 메소드의 pvConnectionContext 파라미터가 접속의 문맥값으로서 사용된다.

문맥값은, 로비 클라이언트와 로비 어플리케이션의 사이에 공유되지 않는다. 예를 들어, 로비 접속의 문맥값을,IDirectPlay8LobbyClient 인터페이스에서는 포인터 A 에,IDirectPlay8LobbiedApplication 인터페이스에서는 포인터 B 로 설정했을 경우,IDirectPlay8LobbyClient 인터페이스에서는 포인터 A 가 문맥값이 되어,IDirectPlay8LobbiedApplication 인터페이스에서는 포인터 B 가 문맥값이 된다.

이 기능을 사용할 필요가 없는 경우는, 문맥값을 NULL 로 설정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언. 그리고 선언.


DPL_MSGID_RECEIVE

IDirectPlay8LobbyClient::Send 또는 IDirectPlay8LobbiedApplication::Send 메소드에 의해 송신된 메세지를 타겟이 받으면(자), Microsoft® DirectPlay® 에 의해 DPL_MSGID_RECEIVE 메세지가 생성된다.

DPL_MESSAGE_RECEIVE

DPL_MESSAGE_RECEIVE 구조체에는, DPL_MSGID_RECEIVE 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPL_MESSAGE_RECEIVE{
    DWORD     dwSize;
    DPNHANDLE hSender;
    BYTE*     pBuffer;
    DWORD     dwBufferSize;
    PVOID     pvConnectionContext;
} DPL_MESSAGE_RECEIVE, *PDPL_MESSAGE_RECEIVE;
dwSize
DPL_MESSAGE_RECEIVE 메세지 구조체의 사이즈. 어플리케이션은, 이 구조체를 사용하기 전에, 우선 이 멤버를 설정할 필요가 있다.
hSender
메세지를 송신한 클라이언트의 핸들.
pBuffer
메세지 데이터에의 포인터.
dwBufferSize
pBuffer 멤버에 보관 유지된 메세지의 사이즈.
pvConnectionContext
접속에 대해서 설정되어 있는 문맥값.

주의

로비 어플리케이션의 경우, 문맥값은 DPL_MESSAGE_CONNECT 메세지 구조체의 pvConnectionContext 멤버에 의해 설정된다. 메세지 핸들러가 이 메세지를 받아들였을 경우는, 돌아오기 전에 이 멤버로 설정한 값이, 그 접속의 문맥값이 된다.

로비 클라이언트의 경우, 접속이 성공하면(자),IDirectPlay8LobbyClient::ConnectApplication 메소드의 pvConnectionContext 파라미터가 접속의 문맥값으로서 사용된다.

문맥값은, 로비 클라이언트와 로비 어플리케이션의 사이에 공유되지 않는다. 예를 들어, 로비 접속의 문맥값을,IDirectPlay8LobbyClient 인터페이스에서는 포인터 A 에,IDirectPlay8LobbiedApplication 인터페이스에서는 포인터 B 로 설정했을 경우,IDirectPlay8LobbyClient 인터페이스에서는 포인터 A 가 문맥값이 되어,IDirectPlay8LobbiedApplication 인터페이스에서는 포인터 B 가 문맥값이 된다.

이 기능을 사용할 필요가 없는 경우는, 문맥값을 NULL 로 설정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언. 그리고 선언.


DPL_MSGID_SESSION_STATUS

IDirectPlay8LobbiedApplication::UpdateStatus 메소드의 호출에 의해 세션이 갱신되면(자), Microsoft® DirectPlay® 에 의해 DPL_MSGID_SESSION_STATUS 메세지가 생성된다.

DPL_MESSAGE_SESSION_STATUS

DPL_MESSAGE_SESSION_STATUS 구조체에는, DPL_MSGID_SESSION_STATUS 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPL_MESSAGE_SESSION_STATUS{
    DWORD dwSize;
    DPNHANDLE hSender;
    DWORD dwStatus;
    PVOID pvConnectionContext;
} DPL_MESSAGE_SESSION_STATUS, *PDPL_MESSAGE_SESSION_STATUS;
dwSize
DPL_MESSAGE_SESSION_STATUS 메세지 구조체의 사이즈. 어플리케이션은, 이 구조체를 사용하기 전에, 우선 이 멤버를 설정할 필요가 있다.
hSender
상태 갱신 메세지를 송신한 어플리케이션의 핸들.
dwStatus
세션의 갱신된 상태. 이 멤버에는 이하의 몇개의 값을 설정할 수 있다.
DPLSESSION_CONNECTED
로비 어플리케이션은 현재 세션에 접속되고 있다.
DPLSESSION_COULDNOTCONNECT
로비 어플리케이션을 세션에 접속할 수 없다.
DPLSESSION_DISCONNECTED
로비 어플리케이션은 현재 세션으로부터 접속 해제되고 있다.
DPLSESSION_TERMINATED
세션 호스트와 로비 어플리케이션의 사이의 접속은 종료했다.
DPLSESSION_HOSTMIGRATED
피어 투 피어 세션의 호스트가 이행 되었다. 로컬 클라이언트는 새로운 호스트는 아니다.
DPLSESSION_HOSTMIGRATEDHERE
피어 투 피어 세션의 호스트가 이행 되었다. 로컬 클라이언트가 새로운 호스트이다.
pvConnectionContext
접속에 대해서 설정되어 있는 문맥값.

주의

로비 어플리케이션의 경우, 문맥값은 DPL_MESSAGE_CONNECT 메세지 구조체의 pvConnectionContext 멤버에 의해 설정된다. 메세지 핸들러가 이 메세지를 받아들였을 경우는, 돌아오기 전에 이 멤버로 설정한 값이, 그 접속의 문맥값이 된다.

로비 클라이언트의 경우, 접속이 성공하면(자),IDirectPlay8LobbyClient::ConnectApplication 메소드의 pvConnectionContext 가 접속의 문맥값으로서 사용된다.

문맥값은, 로비 클라이언트와 로비 어플리케이션의 사이에 공유되지 않는다. 예를 들어, 로비 접속의 문맥값을,IDirectPlay8LobbyClient 인터페이스에서는 포인터 A 에,IDirectPlay8LobbiedApplication 인터페이스에서는 포인터 B 로 설정했을 경우,IDirectPlay8LobbyClient 인터페이스에서는 포인터 A 가 문맥값이 되어,IDirectPlay8LobbiedApplication 인터페이스에서는 포인터 B 가 문맥값이 된다.

이 기능을 사용할 필요가 없는 경우는, 문맥값을 NULL 로 설정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언. 그리고 선언.


DPN_MSGID_APPLICATION_DESC

이 메세지는, 어플리케이션 기술이 변경된 것을 나타낸다. 부수 하는 구조체는 없다. 새로운 어플리케이션 기술을 조사하려면 ,IDirectPlay8Peer ,IDirectPlay8Client , 또는 IDirectPlay8Server 인터페이스에 의해 공개되는 GetApplicationDesc 메소드를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언. 그리고 선언.


DPN_MSGID_ADD_PLAYER_TO_GROUP

피어 투 피어 세션 또는 클라이언트/서버 세션의 그룹에 플레이어가 추가되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_ADD_PLAYER_TO_GROUP 메세지가 생성된다.

DPNMSG_ADD_PLAYER_TO_GROUP

DPNMSG_ADD_PLAYER_TO_GROUP 구조체에는, DPN_MSGID_ADD_PLAYER_TO_GROUP 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_ADD_PLAYER_TO_GROUP{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    PVOID  pvGroupContext;
    DPNID  dpnidPlayer;
    PVOID  pvPlayerContext;
} DPNMSG_ADD_PLAYER_TO_GROUP, *PDPNMSG_ADD_PLAYER_TO_GROUP;
dwSize
이 구조체의 사이즈.
dpnidGroup
플레이어를 추가하는 그룹의 DPNID.
pvGroupContext
그룹의 문맥값.
dpnidPlayer
그룹에 추가하는 플레이어의 DPNID.
pvPlayerContext
플레이어의 문맥값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_ASYNC_OP_COMPLETE

비동기 요구가 완료 하면, Microsoft® DirectPlay® 에 의해 DPN_MSGID_ASYNC_OP_COMPLETE 메세지가 생성된다.

DPNMSG_ASYNC_OP_COMPLETE

DPNMSG_ASYNC_OP_COMPLETE 구조체에는, DPN_MSGID_ASYNC_OP_COMPLETE 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_ASYNC_OP_COMPLETE{
    DWORD      dwSize;
    DPNHANDLE  hAsyncOp;
    PVOID      pvUserContext;
    HRESULT    hResultCode;
} DPNMSG_ASYNC_OP_COMPLETE, *PDPNMSG_ASYNC_OP_COMPLETE;
dwSize
이 구조체의 사이즈.
hAsyncOp
비동기 처리 핸들.
pvUserContext
지정된 유저 문맥.
hResultCode
비동기 처리의 결과를 나타내는 HRESULT.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_CLIENT_INFO

클라이언트 데이터가 클라이언트/서버 세션의 사이로 변경되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_CLIENT_INFO 메세지가 생성된다.

DPNMSG_CLIENT_INFO

DPNMSG_CLIENT_INFO 구조체에는, DPN_MSGID_CLIENT_INFO 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_CLIENT_INFO{
    DWORD  dwSize;
    DPNID  dpnidClient;
    PVOID  pvPlayerContext;
} DPNMSG_CLIENT_INFO, *PDPNMSG_CLIENT_INFO;
dwSize
이 구조체의 사이즈.
dpnidClient
클라이언트 정보용의 클라이언트의 DPNID.
pvPlayerContext
플레이어의 문맥값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_CONNECT_COMPLETE

피어 투 피어 세션 또는 클라이언트/서버 세션으로 접속의 시행이 완료 하면, Microsoft® DirectPlay® 에 의해 DPN_MSGID_CONNECT_COMPLETE 메세지가 생성된다. 접속이 성공한 제발에 관계없이, 이 메세지는 생성된다.

DPNMSG_CONNECT_COMPLETE

DPNMSG_CONNECT_COMPLETE 구조체에는, DPN_MSGID_CONNECT_COMPLETE 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_CONNECT_COMPLETE{
    DWORD      dwSize;
    DPNHANDLE  hAsyncOp;
    PVOID      pvUserContext;
    HRESULT    hResultCode;
    PVOID      pvApplicationReplyData;
    DWORD      dwApplicationReplyDataSize;
} DPNMSG_CONNECT_COMPLETE, *PDPNMSG_CONNECT_COMPLETE;
dwSize
이 구조체의 사이즈.
hAsyncOp
비동기 처리 핸들.
pvUserContext
IDirectPlay8Peer::Connect 또는 IDirectPlay8Client::Connect 메소드를 호출했을 때에 제공되는 유저 문맥.
hResultCode
접속의 결과를 기술하는 HRESULT. 상세한 것에 대하여는,IDirectPlay8Peer::Connect 메소드 또는 IDirectPlay8Client::Connect 메소드의 「반환값」을 참조할것. 또, 플레이어가 피어 투 피어 세션에 참가하려고 했을 때에, 세션외의 기존 플레이어의 적어도 1 명이 그 플레이어에게 접속할 수 없으면DPNERR_PLAYERNOTREACHABLE 가 돌려주어진다.
pvApplicationReplyData
호스트 또는 서버로부터 돌려주어진 접속 응답 데이터.
dwApplicationReplyDataSize
pvApplicationReplyData 멤버의 데이터의 사이즈 (바이트 단위).

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_CREATE_GROUP

그룹이 생성 되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_CREATE_GROUP 메세지가 생성된다.

DPNMSG_CREATE_GROUP

DPNMSG_CREATE_GROUP 구조체에는, DPN_MSGID_CREATE_GROUP 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_CREATE_GROUP{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    DPNID  dpnidOwner;
    PVOID  pvGroupContext;
} DPNMSG_CREATE_GROUP, *PDPNMSG_CREATE_GROUP;
dwSize
이 구조체의 사이즈.
dpnidGroup
생성 된 그룹의 DPNID.
dpnidOwner
그룹의 소유자의 DPNID. 이 값은,DPN_GROUP_INFO 구조체의 dwGroupFlags 멤버의 DPNGROUP_AUTODESTRUCT 플래그가 설정되어 있는 그룹에만 설정한다.
pvGroupContext
그룹의 문맥값.

주의

그룹의 문맥값을 설정하는 유일한 방법은, 이 시스템 메세지를 사용하는 것이다. 한 번 설정한 그룹의 문맥값은 변경할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_CREATE_PLAYER

피어 투 피어 세션 또는 클라이언트/서버 세션에 플레이어가 추가되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_CREATE_PLAYER 메세지가 생성된다.

DPNMSG_CREATE_PLAYER

DPNMSG_CREATE_PLAYER 구조체에는, DPN_MSGID_CREATE_PLAYER 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_CREATE_PLAYER{
    DWORD  dwSize;
    DPNID  dpnidPlayer;
    PVOID  pvPlayerContext;
} DPNMSG_CREATE_PLAYER, *PDPNMSG_CREATE_PLAYER;
dwSize
이 구조체의 사이즈.
dpnidPlayer
세션에 추가된 플레이어의 DPNID.
pvPlayerContext
플레이어의 문맥값.

주의

플레이어의 문맥값을 설정하는 유일한 방법은, 이 시스템 메세지를 사용하는 것이다. 플레이어 문맥값은, 이 메세지를 사용해 직접 설정하는지,DPN_MSGID_INDICATE_CONNECT 를 사용해 간접적으로 설정할 수 있다. 플레이어 문맥값은, 한 번 설정 하면 변경할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언. 그리고 선언.


DPN_MSGID_DESTROY_PLAYER

플레이어가 피어 투 피어 세션 또는 클라이언트/서버 세션을 떨어지면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_DESTROY_PLAYER 메세지가 생성된다.

DPNMSG_DESTROY_PLAYER

DPNMSG_DESTROY_PLAYER 구조체에는, DPN_MSGID_DESTROY_PLAYER 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_DESTROY_PLAYER{
    DWORD  dwSize;
    DPNID  dpnidPlayer;
    PVOID  pvPlayerContext;
    DWORD  dwReason;
} DPNMSG_DESTROY_PLAYER, *PDPNMSG_DESTROY_PLAYER;
dwSize
이 구조체의 사이즈.
dpnidPlayer
세션으로부터 삭제되는 플레이어의 DPNID.
pvPlayerContext
플레이어의 문맥값.
dwReason
플레이어가 파기된 이유를 나타내는 다음의 몇개의 플래그.
DPNDESTROYPLAYERREASON_NORMAL
플레이어는 보통의 이유로써 삭제된다.
DPNDESTROYPLAYERREASON_CONNECTIONLOST
접속이 없어졌기 때문에, 플레이어는 삭제된다.
DPNDESTROYPLAYERREASON_SESSIONTERMINATED
세션이 종료했기 때문에, 플레이어는 삭제된다.
DPNDESTROYPLAYERREASON_HOSTDESTROYEDPLAYER
호스트가 IDirectPlay8Peer::DestroyPeer 를 호출했기 때문에, 플레이어는 삭제된다.

주의

클라이언트/서버 모드에서는, 서버만이 이 메세지를 받아들인다. 피어 투 피어 모드에서는, 모든 플레이어가 이 메세지를 받아들인다.

다른 복수의 thread로 DPN_MSGID_CREATE_PLAYER 메세지와 DPN_MSGID_DESTROY_PLAYER 메세지를 받아들이는 일이 있다. 그러나, 콜백 함수가 DPN_MSGID_CREATE_PLAYER 메세지의 수신으로부터 돌아오기 전에 DPN_MSGID_DESTROY_PLAYER 메세지를 받아들일 것은 없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_DESTROY_GROUP

피어 투 피어 세션 또는 클라이언트/서버 세션으로부터 그룹이 파기되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_DESTROY_GROUP 메세지가 생성된다.

DPNMSG_DESTROY_GROUP

DPNMSG_DESTROY_GROUP 구조체에는, DPN_MSGID_DESTROY_GROUP 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_DESTROY_GROUP{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    PVOID  pvGroupContext;
    DWORD  dwReason;
} DPNMSG_DESTROY_GROUP, *PDPNMSG_DESTROY_GROUP;
dwSize
이 구조체의 사이즈.
dpnidGroup
세션으로부터 삭제되는 그룹의 DPNID.
pvGroupContext
그룹의 문맥값.
dwReason
플레이어가 파기된 이유를 나타내는 다음의 몇개의 플래그.
DPNDESTROYGROUPREASON_SESSIONTERMINATED
세션이 종료했기 때문에, 그룹은 삭제된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_ENUM_HOSTS_QUERY

피어 또는 클라이언트가 이용 가능한 호스트를 열거 하면 와, Microsoft® DirectPlay® 은 DPN_MSGID_ENUM_HOSTS_QUERY 메세지를 호스트의 메세지 핸들러에 송신한다.

DPNMSG_ENUM_HOSTS_QUERY

DPNMSG_ENUM_HOSTS_QUERY 구조체에는, DPN_MSGID_ENUM_HOSTS_QUERY 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_ENUM_HOSTS_QUERY{
    DWORD                dwSize;
    IDirectPlay8Address* pAddressSender;
    IDirectPlay8Address* pAddressDevice;
    PVOID                pvReceivedData;
    DWORD                dwReceivedDataSize;
    DWORD                dwMaxResponseDataSize;
    PVOID                pvResponseData;
    DWORD                dwResponseDataSize;
    PVOID                pvResponseContext;
} DPNMSG_ENUM_HOSTS_QUERY, *PDPNMSG_ENUM_HOSTS_QUERY;
dwSize
이 구조체의 사이즈.
pAddressSender
송신자의 주소를 지정하는 IDirectPlay8Address 인터페이스에의 포인터. IDirectPlay8Address::AddRef 를 호출해, 인터페이스의 참조 카운트를 인크리먼트(increment) 할 필요가 있다. 인터페이스가 불필요하게 되었을 때는,IDirectPlay8Address::Release 를 호출한다.
pAddressDevice
디바이스의 주소를 지정하는 IDirectPlay8Address 인터페이스에의 포인터. IDirectPlay8Address::AddRef 를 호출해, 인터페이스의 참조 카운트를 인크리먼트(increment) 할 필요가 있다. 인터페이스가 불필요하게 되었을 때는,IDirectPlay8Address::Release 를 호출한다.
pvReceivedData
열거로부터 받는 데이터에의 포인터.
dwReceivedDataSize
pvReceivedData 멤버가 가리키는 데이터의 사이즈.
dwMaxResponseDataSize
허가되는 열거 응답의 최대 사이즈.
pvResponseData
열거로부터의 응답 데이터에의 포인터. 이 데이터는, 콜백 메세지 핸들러의 범위 이상으로 유효하지 않으면 안 된다. 스택 베이스는 사용할 수 없다. Microsoft® DirectPlay® 가 이 버퍼의 처리를 끝내면(자),DPN_MSGID_RETURN_BUFFER 메세지가 보내진다.
dwResponseDataSize
pvResponseData 멤버가 가리키는 데이터 사이즈.
pvUserContext
응답 문맥값에의 포인터. 이 값은, 관련하는 구조체의 pvUserContext 멤버로서DPN_MSGID_RETURN_BUFFER 메세지와 함께 호스트의 메세지 핸들러에게 건네진다.

주의

이 조회에 보통의 응답을 하면, DirectPlay 는 유저에게 DPN_MSGID_RETURN_BUFFER 메세지를 한 번 송신해, 버퍼는 불필요하게 된다. 이것으로, 버퍼를 안전하게 해방할 수 있다.

조회를 거부하려면 , S_OK 이외의 값을 돌려준다. 다만 조회를 거부 하면, DirectPlay 는 응답을 보내지 않고, 응답 버퍼를 필요로 하지 않고,DPN_MSGID_RETURN_BUFFER 메세지를 생성하지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_ENUM_HOSTS_RESPONSE

Microsoft® DirectPlay® 은, DPN_MSGID_ENUM_HOSTS_RESPONSE 메세지를 피어 또는 클라이언트의 메세지 핸들러에 송신해, 열거 요구에 대한 호스트의 응답을 전한다.

DPNMSG_ENUM_HOSTS_RESPONSE

DPNMSG_ENUM_HOSTS_RESPONSE 구조체에는, DPN_MSGID_ENUM_HOSTS_RESPONSE 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_ENUM_HOSTS_RESPONSE{
    DWORD                         dwSize;
    IDirectPlay8Address*          pAddressSender;
    IDirectPlay8Address*          pAddressDevice;
    const DPN_APPLICATION_DESC*   pApplicationDescription;
    PVOID                         pvResponseData;
    DWORD                         dwResponseDataSize;
    PVOID                         pvUserContext;
    DWORD                         dwRoundTripLatencyMS;
} DPNMSG_ENUM_HOSTS_RESPONSE, *PDPNMSG_ENUM_HOSTS_RESPONSE;
dwSize
이 구조체의 사이즈.
pAddressSender
열거에 응답하는 호스트의 주소를 지정하는 IDirectPlay8Address 인터페이스에의 포인터. IDirectPlay8Address::AddRef 를 호출해, 인터페이스의 참조 카운트를 인크리먼트(increment) 할 필요가 있다. 인터페이스가 불필요하게 되었을 때는,IDirectPlay8Address::Release 를 호출한다.
pAddressDevice
디바이스의 주소를 지정하는 IDirectPlay8Address 인터페이스에의 포인터. IDirectPlay8Address::AddRef 를 호출해, 인터페이스의 참조 카운트를 인크리먼트(increment) 할 필요가 있다. 인터페이스가 불필요하게 되었을 때는,IDirectPlay8Address::Release 를 호출한다.
pApplicationDescription
어플리케이션의 기술을 보관 유지하는 DPN_APPLICATION_DESC 구조체에의 포인터.
pvResponseData
열거로부터의 응답 데이터에의 포인터.
dwResponseDataSize
pvResponseData 멤버가 가리키는 데이터 사이즈.
pvUserContext
유저의 문맥값에의 포인터. 이 값은,IDirectPlay8Peer::EnumHosts 또는 IDirectPlay8Client::EnumHosts 에게 건네지는 유저 문맥값과 같다.
dwRoundTripLatencyMS
밀리 세컨드 단위로 표현된 지연 시간.

주의

데이터를 저장 하는 버퍼가 없기 때문에, 이 메세지는 DPN_MSGID_RETURN_BUFFER 메세지를 생성하지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_GROUP_INFO

그룹 데이터가 피어 투 피어 세션 또는 클라이언트/서버 세션의 사이로 변경되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_GROUP_INFO 메세지가 생성된다.

DPNMSG_GROUP_INFO

DPNMSG_GROUP_INFO 구조체에는, DPN_MSGID_GROUP_INFO 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_GROUP_INFO{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    PVOID  pvGroupContext;
} DPNMSG_GROUP_INFO, *PDPNMSG_GROUP_INFO;
dwSize
이 구조체의 사이즈.
dpnidGroup
그룹 정보용의 그룹의 DPNID.
pvGroupContext
그룹의 문맥값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_HOST_MIGRATE

DPN_APPLICATION_DESC 구조체에 DPNSESSION_MIGRATE_HOST 플래그가 설정되어 호스트가 이행 했을 경우, Microsoft® DirectPlay® 에 의해 DPN_MSGID_HOST_MIGRATE 메세지가 생성된다.

DPNMSG_HOST_MIGRATE

DPNMSG_HOST_MIGRATE 구조체에는, DPN_MSGID_HOST_MIGRATE 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_HOST_MIGRATE{
    DWORD  dwSize;
    DPNID  dpnidNewHost;
    PVOID  pvPlayerContext;
} DPNMSG_HOST_MIGRATE, *PDPNMSG_HOST_MIGRATE;
dwSize
이 구조체의 사이즈.
dpnidNewHost
세션을 현재 호스트 하고 있는 플레이어의 DPNID.
pvPlayerContext
플레이어의 문맥값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_INDICATE_CONNECT

플레이어가 피어 투 피어 세션 또는 클라이언트/서버 세션에 접속하려고 하면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_INDICATE_CONNECT 메세지가 생성된다.

DPNMSG_INDICATE_CONNECT

DPNMSG_INDICATE_CONNECT 구조체에는, DPN_MSGID_INDICATE_CONNECT 시스템 메세지에 관한 정보가 보관 유지된다.

호스트 어플리케이션은 이 구조체를 이용해, 유저 데이터에 근거해 접속의 허가 또는 거부를 실시하거나 접속원어플리케이션에 응답 정보를 제공할 수 있다.

typedef struct {
    DWORD     dwSize;
    PVOID     pvUserConnectData;
    DWORD     dwUserConnectDataSize;
    PVOID     pvReplyData;
    DWORD     dwReplyDataSize;
    PVOID     pvReplyContext;
    PVOID     pvPlayerContext;
    IDirectPlay8Address*  pAddressPlayer;
    IDirectPlay8Address*  pAddressDevice;
} DPNMSG_INDICATE_CONNECT, *PDPNMSG_INDICATE_CONNECT;
dwSize
이 구조체의 사이즈.
pvUserConnectData
접속원플레이어의 데이터.
dwUserConnectDataSize
pvUserConnectData 멤버에 보관 유지된 데이터의 사이즈 (바이트 단위).
pvReplyData
접속 응답 데이터. 이 데이터는, 콜백 메세지 핸들러와는 관계되어 없고 유효하지 않으면 안 된다. Microsoft® DirectPlay® 가 이 버퍼의 처리를 끝내면(자),DPN_MSGID_RETURN_BUFFER 메세지가 보내진다.
dwReplyDataSize
pvReplyData 멤버에 보관 유지된 데이터의 사이즈 (바이트 단위).
pvReplyContext
pvReplyData 의 버퍼 문맥. 이 값은, 관련하는 구조체의 pvUserContext 멤버로서DPN_MSGID_RETURN_BUFFER 메세지와 함께 호스트의 메세지 핸들러에게 건네진다.
pvPlayerContext
기정의 플레이어 문맥.
pAddressPlayer
접속하고 있는 플레이어에 대한 IDirectPlay8Address 인터페이스에의 포인터. IDirectPlay8Address::AddRef 를 호출해, 인터페이스의 참조 카운트를 인크리먼트(increment) 할 필요가 있다. 인터페이스가 불필요하게 되었을 때는,IDirectPlay8Address::Release 를 호출한다.
pAddressDevice
접속의 시도를 수신하는 디바이스의 IDirectPlay8Address 인터페이스에의 포인터. IDirectPlay8Address::AddRef 를 호출해, 인터페이스의 참조 카운트를 인크리먼트(increment) 할 필요가 있다. 인터페이스가 불필요하게 되었을 때는,IDirectPlay8Address::Release 를 호출한다.

주의

플레이어에게 세션에의 참가를 허가하려면 , S_OK 를 돌려준다. 그 외의 반환값은 요구된 접속을 거부한다. 접속이 성공하면(자), 접속을 요구하고 있는 플레이어에게 송신되는hResultCode DPN_MSGID_CONNECT_COMPLETE 메세지에 관련하는 구조체의 hResultCode 멤버에 S_OK 가 설정된다. 접속이 거부되면(자),hResultCode 에는, 이 메세지로부터 돌려주는 값은 아니고 DPNERR_HOSTREJECTEDCONNECTION 가 설정된다.

DPN_MSGID_INDICATE_CONNECT 통지가 호스트 플레이어의 메세지 핸들러에 닿았을 경우, thread를 돌려주기 전에 pvPlayerContext 를 설정 하면, 플레이어의 문맥값은 대응하는 DPN_MSGID_CREATE_PLAYER 통지에 사전 설정된다. 이 기능을 사용해, 플레이어 문맥값을 DPN_MSGID_CREATE_PLAYER 에 건네줄 수가 있다.

플레이어 문맥값을 설정했을 경우, 그 값은, 그 이후의 DPN_MSGID_CREATE_PLAYER 메세지가 처리될 때까지 굳어지지 않는다. 그 때문에,DPN_MSGID_CREATE_PLAYER 를 처리할 경우에 이 플레이어 문맥값을 수정할 수 있다.

서버가 DPN_MSGID_INDICATE_CONNECT 메세지를 처리한 후,DPN_MSGID_CREATE_PLAYER 을 처리하기 전에, 클라이언트가 접속을 삭제 하면, 서버는 DPN_MSGID_INDICATED_CONNECT_ABORTED 메세지를 받아들인다. 이 메세지를 받아들였을 경우는,DPN_MSGID_INDICATE_CONNECT 를 처리하는 동안에 할당한 메모리를 해방하는 것. DPN_MSGID_CREATE_PLAYER 가 처리되면(자),DPN_MSGID_DESTROY_PLAYER 를 처리할 경우에, 이 메모리를 해방할 필요가 있다.

pvUserConnectData 의 데이터를 지정 하면, 그 후로, 버퍼를 안전하게 해방할 수 있는 것을 알리는 DPN_MSGID_RETURN_BUFFER 메세지를 받아들인다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_INDICATED_CONNECT_ABORTED

플레이어의 접속이 호스트상에서 나타난 후,DPN_MSGID_CREATE_PLAYER 을 사용해 세션에 추가되기 전에 삭제되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_INDICATED_CONNECT_ABORTED 메세지가 생성된다.

DPNMSG_INDICATED_CONNECT_ABORTED

DPNMSG_INDICATED_CONNECT_ABORTED 구조체에는, DPN_MSGID_INDICATED_CONNECT_ABORTED 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    PVOID  pvPlayerContext;
} DPNMSG_INDICATED_CONNECT_ABORTED, *PDPNMSG_INDICATED_CONNECT_ABORTED;
dwSize
이 구조체의 사이즈.
pvPlayerContext
플레이어의 문맥값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언. 그리고 선언.


DPN_MSGID_PEER_INFO

피어 데이터가 피어 투 피어 세션의 사이로 변경되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_PEER_INFO 메세지가 생성된다.

DPNMSG_PEER_INFO

DPNMSG_PEER_INFO 구조체에는, DPN_MSGID_PEER_INFO 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    DPNID  dpnidPeer;
    PVOID  pvPlayerContext;
} DPNMSG_PEER_INFO, *PDPNMSG_PEER_INFO;
dwSize
이 구조체의 사이즈.
dpnidPeer
피어 정보용의 피어의 DPNID.
pvPlayerContext
플레이어의 문맥값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_RECEIVE

메세지가 수신 측에야는 처리되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_RECEIVE 메세지가 생성된다.

DPNMSG_RECEIVE

DPNMSG_RECEIVE 구조체에는, DPN_MSGID_RECEIVE 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD      dwSize;
    DPNID      dpnidSender;
    PVOID      pvPlayerContext;
    PBYTE      pReceiveData;
    DWORD      dwReceiveDataSize;
    DPNHANDLE  hBufferHandle;
} DPNMSG_RECEIVE, *PDPNMSG_RECEIVE;
dwSize
이 구조체의 사이즈.
dpnidSender
메세지를 송신한 플레이어의 DPNID.
pvPlayerContext
메세지를 송신한 플레이어의 플레이어 문맥값.
pReceiveData
메세지 데이터 버퍼에의 PBYTE 포인터. 이 버퍼는, 보통의 경우,DPN_MSGID_RECEIVE 메세지가 콜백 메세지 핸들러에 의해 처리되고 있는 동안 마셔 유효하다. 메세지의 총처리 시간이 커지지 않게, 이 데이터를 카피해 메세지를 처리한다. 다른 방법으로서 콜백 메세지 핸들러로부터 DPNSUCCESS_PENDING 를 돌려줄 수도 있다. 이 경우는, 버퍼의 소유권이 어플리케이션으로 옮겨진다. DPNSUCCESS_PENDING 를 돌려주는 경우, 버퍼가 불필요하게 되면(자),IDirectPlay8Peer::ReturnBuffer ,IDirectPlay8Client::ReturnBuffer , 또는 IDirectPlay8Server::ReturnBuffer 를 호출할 필요가 있다. 메소드에,hBufferHandle 멤버로 받은 값을 건네주어, 버퍼를 식별한다. ReturnBuffer 의 호출해에 실패했을 경우는, 메모리 누수가 발생한다.
dwReceiveDataSize
pReceiveData 멤버의 데이터의 사이즈 (바이트 단위).
hBufferHandle
pReceiveData 멤버의 버퍼 핸들. DPNSUCCESS_PENDING 를 돌려주었을 경우, 이 값을 ReturnBuffer 에 건네주어, Microsoft® DirectPlay® 에 버퍼를 해방하도록(듯이) 통지한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_REMOVE_PLAYER_FROM_GROUP

피어 투 피어 세션 또는 클라이언트/서버 세션의 그룹으로부터 플레이어가 삭제되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_REMOVE_PLAYER_FROM_GROUP 메세지가 생성된다.

DPNMSG_REMOVE_PLAYER_FROM_GROUP

DPNMSG_REMOVE_PLAYER_FROM_GROUP 구조체에는, DPN_MSGID_REMOVE_PLAYER_FROM_GROUP 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct _DPNMSG_REMOVE_PLAYER_FROM_GROUP{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    PVOID  pvGroupContext;
    DPNID  dpnidPlayer;
    PVOID  pvPlayerContext;
} DPNMSG_REMOVE_PLAYER_FROM_GROUP, *PDPNMSG_REMOVE_PLAYER_FROM_GROUP;
dwSize
이 구조체의 사이즈.
dpnidGroup
플레이어가 삭제된 그룹의 DPNID.
pvGroupContext
그룹의 문맥값.
dpnidPlayer
그룹으로부터 삭제되는 플레이어의 DPNID.
pvPlayerContext
플레이어의 문맥값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_RETURN_BUFFER

DirectPlay 에 의한 유저 버퍼의 처리가 종료 하면, Microsoft® DirectPlay® 에 의해 DPN_MSGID_RETURN_BUFFER 메세지가 생성된다.

DPNMSG_RETURN_BUFFER

DPNMSG_RETURN_BUFFER 구조체에는, DPN_MSGID_RETURN_BUFFER 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD      dwSize;
    HRESULT    hResultCode;
    PVOID      pvBuffer;
    PVOID      pUserContext;
} DPNMSG_RETURN_BUFFER, *PDPNMSG_RETURN_BUFFER;
dwSize
이 구조체의 사이즈.
hResultCode
처리의 값을 돌려준다. DPN_MSGID_ENUM_HOSTS_QUERY 메세지에의 응답이 너무 큰 경우는, DPNERR_ENUMRESPONSETOOLARGE 가 설정된다.
pvBuffer
돌려주어지는 버퍼에의 포인터.
pUserContext
버퍼에 관련지을 수 있었던 문맥값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_SEND_COMPLETE

송신 메세지 요구가 완료 하면, Microsoft® DirectPlay® 에 의해 DPN_MSGID_SEND_COMPLETE 메세지가 생성된다.

DPNMSG_SEND_COMPLETE

DPNMSG_SEND_COMPLETE 구조체에는, DPN_MSGID_SEND_COMPLETE 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD      dwSize;
    DPNHANDLE  hAsyncOp;
    PVOID      pvUserContext;
    HRESULT    hResultCode;
    DWORD      dwSendTime;
} DPNMSG_SEND_COMPLETE, *PDPNMSG_SEND_COMPLETE;
dwSize
이 구조체의 사이즈.
hAsyncOp
비동기 처리 핸들.
pvUserContext
IDirectPlay8Client::Send 메소드,IDirectPlay8Peer::SendTo 메소드, 및 IDirectPlay8Server::SendTo 메소드로 지정되는 유저 문맥.
hResultCode
송신 메세지 요구의 결과를 나타내는 HRESULT.
dwSendTime
송신 호출로부터 종료할 때까지의 합계 시간 (밀리 세컨드 단위).

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_SERVER_INFO

서버 데이터가 클라이언트/서버 세션의 사이로 변경되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_SERVER_INFO 메세지가 생성된다.

DPNMSG_SERVER_INFO

DPNMSG_SERVER_INFO 구조체에는, DPN_MSGID_SERVER_INFO 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    DPNID  dpnidServer;
    PVOID  pvPlayerContext;
} DPNMSG_SERVER_INFO, *PDPNMSG_SERVER_INFO;
dwSize
이 구조체의 사이즈.
dpnidServer
서버 정보용의 서버의 DPNID.
pvPlayerContext
플레이어의 문맥값.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_MSGID_TERMINATE_SESSION

세션이 호스트에 의해 종료되면(자), Microsoft® DirectPlay® 에 의해 DPN_MSGID_TERMINATE_SESSION 메세지가 생성된다.

DPNMSG_TERMINATE_SESSION

DPNMSG_TERMINATE_SESSION 구조체에는, DPN_MSGID_TERMINATE_SESSION 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD   dwSize;
    HRESULT hResultCode;
    PVOID   pvTerminateData;
    DWORD   dwTerminateDataSize;
} DPNMSG_TERMINATE_SESSION, *PDPNMSG_TERMINATE_SESSION;
dwSize
이 구조체의 사이즈.
hResultCode
세션이 어떻게 종료했는지를 지정한다. 세션이 피어 투 피어로, 호스트가 IDirectPlay8Peer::TerminateSession 를 호출했을 경우, 이 멤버는 DPNERR_HOSTTERMINATEDSESSION 로 설정된다. 호스트가 Close 를 호출해 세션을 종료했을 경우, 또는 호스트가 응답을 정지했을 경우, hResultCode 은 DPNERR_CONNECTIONLOST 로 설정된다.
pvTerminateData
종료 데이터. hResultCode 가 DPNERR_HOSTTERMINATEDSESSION 로 설정되었을 경우,pvTerminateData 는, 호스트가 IDirectPlay8Peer::TerminateSession 의 pvTerminateData 파라미터에 의해 건네준 데이터 블록에의 포인터.
dwTerminateDataSize
pvTerminateData 에 의해 포인트 된 데이터 블록의 사이즈. pvTerminateData 가 NULL 로 설정되어 있는 경우, 이 멤버는 제로가 된다.

주의

호스트의 이행이 허가되는 피어 투 피어 게임에서는, 현재의 호스트가 Close 를 호출할까 응답을 정지했을 경우, 세션은 종료하지 않는다. 그 대신에, 호스트가 이행 해, 호스트 이외의 모든 플레이어는, 호스트의 플레이어에 관한 DPN_MSGID_DESTROY_PLAYER 메세지와 새로운 호스트에 관한 DPN_MSGID_HOST_MIGRATE 메세지를 받아들인다. 호스트의 이행을 실시하지 않기 위해(때문에)는, 호스트가 IDirectPlay8Peer::TerminateSession 를 호출해 세션을 슛다운 해야 한다. 호스트가 이 방법으로 세션을 종료 하면, 모든 플레이어가,hResultCode 를 DPNERR_HOSTTERMINATEDSESSION 로 설정한 DPN_MSGID_TERMINATE_SESSION 메세지를 받아들인다. 세션은 종료해, 플레이어 전원에 대한 DPN_MSGID_DESTROY_PLAYER 메세지가 생성된다.

호스트의 이행을 허가하지 않는 피어 투 피어 게임에서는, 호스트가 IDirectPlay8Peer::Close 을 호출할까 응답을 정지했을 경우, 세션은 종료한다. 그 경우,hResultCode 을 DPNERR_CONNECTIONLOST 로 설정한 DPN_MSGID_TERMINATE_SESSION 가 모든 플레이어에게 송신된다. 세션은 종료해, 플레이어 전원에 대한 DPN_MSGID_DESTROY_PLAYER 메세지가 생성된다.

클라이언트/서버 게임에서도, 호스트가 IDirectPlay8Server::Close 를 호출할까 응답을 정지했을 경우, 세션은 종료한다. 그 경우,hResultCode 을 DPNERR_CONNECTIONLOST 로 설정한 DPN_MSGID_TERMINATE_SESSION 가, 접속하고 있는 모든 클라이언트에 송신된다. DPN_MSGID_DESTROY_PLAYER 메세지는 클라이언트에는 송신되지 않는다. 서버가 IDirectPlay8Server::Close 를 호출해 접속을 해제 하면, 서버는, 서버 자신을 포함한 모든 플레이어에 관한 DPN_MSGID_DESTROY_PLAYER 메세지를 받아들인다. 그 이외의 경우, 서버는 클라이언트의 플레이어에 관한 DPN_MSGID_DESTROY_PLAYER 만을 받는다.

주 DPN_MSGID_TERMINATE_SESSION 메세지는 보통 DPN_MSGID_DESTROY_PLAYER 메세지보다 먼저 도착한다. 다만, 도착의 순서는 보증되어 있지 않다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DVMSGID_CONNECTRESULT

IDirectPlayVoiceClient::Connect 메소드의 호출에 의해 생성된 접속 요구가 완료 하면, Microsoft® DirectPlay® 에 의해 DVMSGID_CONNECTRESULT 메세지가 생성된다. Connect 메소드가 비동기에게 불려 갔을 경우에게만, 이 메세지는 송신된다.

DVMSG_CONNECTRESULT

DVMSG_CONNECTRESULT 구조체에는, DVMSGID_CONNECTRESULT 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD    dwSize;
    HRESULT  hrResult;
} DVMSG_CONNECTRESULT, *LPDVMSG_CONNECTRESULT, *PDVMSG_CONNECTRESULT;
dwSize
DVMSG_CONNECTRESULT 메세지 구조체의 사이즈.
hrResult
접속 시행의 결과.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_CREATEVOICEPLAYER

새로운 플레이어가 음성 세션에 참가 하면, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_CREATEVOICEPLAYER 메세지가 생성된다.

클라이언트는, 음성 세션에 접속 하면, 음성 세션의 플레이어 마다 메세지의 1 개를 수신한다. 이러한 메세지는, 피어 투 피어의 음성 세션의 클라이언트에게만 송신된다.

플레이어가 음성 세션에 참가 하면, 호스트는 이 메세지를 수신한다.

플레이어는,IDirectPlayVoiceClient::Connect 를 호출할 때까지, 음성 세션에 참가하지 않는다. 따라서, 플레이어가 트랜스폴트 세션에는 참가해, 음성 세션에는 참가하고 있지 않는 것도 가능하다.

DVMSG_CREATEVOICEPLAYER

DVMSG_CREATEVOICEPLAYER 구조체에는, DVMSGID_CREATEVOICEPLAYER 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    DVID   dvidPlayer;
    DWORD  dwFlags;
    PVOID  pvPlayerContext;
} DVMSG_CREATEVOICEPLAYER, *LPDVMSG_CREATEVOICEPLAYER, *PDVMSG_CREATEVOICEPLAYER;
dwSize
이 메세지 구조체의 사이즈.
dvidPlayer
접속한 플레이어의 DVID.
dwFlags
플레이어에 관한 정보를 지정하는 플래그.
DVPLAYERCAPS_HALFDUPLEX
지정한 플레이어가 반이중 모드로 동작하고 있다. 플레이어는 음성의 송신은 하지 못하고, 수신 밖에 할 수 없다.
DVPLAYERCAPS_LOCAL
플레이어는 로컬 플레이어이다.
pvPlayerContext
음성 세션의 플레이어의 플레이어 문맥값. 이 값은, 이 메세지가 수신되었을 때에, 이 파라미터에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_DELETEVOICEPLAYER

클라이언트의 경우, 플레이어가 음성 세션을 종료 하면, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_DELETEVOICEPLAYER 메세지가 생성된다. 이 메세지는, 피어 투 피어의 음성 세션의 클라이언트만 이용할 수 있다.

호스트의 경우, 플레이어가 음성 세션을 종료 하면, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_DELETEVOICEPLAYER 메세지가 생성된다.

플레이어가 음성 세션을 떨어지려면 ,IDirectPlayVoiceClient::Disconnect 를 호출하는지, 트랜스폴트 세션으로부터 접속 해제할 필요가 있다. 따라서, 클라이언트가 트랜스폴트 세션에는 참가해, 음성 세션에는 참가하지 않는 것도 가능하다.

DVMSG_DELETEVOICEPLAYER

DVMSG_DELETEVOICEPLAYER 구조체에는, DVMSGID_DELETEVOICEPLAYER 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    DVID   dvidPlayer;
    PVOID  pvPlayerContext;
} DVMSG_DELETEVOICEPLAYER, *LPDVMSG_DELETEVOICEPLAYER, *PDVMSG_DELETEVOICEPLAYER;
dwSize
DVMSG_DELETEVOICEPLAYER 메세지 구조체의 사이즈.
dvidPlayer
접속 해제한 플레이어의 DVID.
pvPlayerContext
플레이어에 대해서 설정된 문맥값에의 포인터. 이 값은,DVMSG_CREATEVOICEPLAYER 메세지 구조체의 pvPlayerContext 멤버에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_DISCONNECTRESULT

IDirectPlayVoiceClient::Disconnect 메소드의 호출에 의해 생성된 접속 해제 요구가 완료 하면, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_DISCONNECTRESULT 메세지가 생성된다. Disconnect 메소드가 비동기에게 불려 갔을 경우만, 이 메세지는 송신된다.

DVMSG_DISCONNECTRESULT

DVMSG_DISCONNECTRESULT 구조체에는, DVMSGID_DISCONNECTRESULT 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD   dwSize;
    HRESULT hrResult;
} DVMSG_DISCONNECTRESULT, *LPDVMSG_DISCONNECTRESULT, *PDVMSG_DISCONNECTRESULT;
dwSize
DVMSG_DISCONNECTRESULT 메세지 구조체의 사이즈.
hrResult
접속 해제 요구의 결과.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_GAINFOCUS

오디오의 캡춰를 시작 한 것을 알리기 (위해)때문에, DVMSGID_GAINFOCUS 메세지가 송신된다. 캡춰의 포커스를 잃은 어플리케이션이 포커스를 회복 하면, 이 메세지가 송신된다. 이 메세지에 관련지을 수 있었던 데이터는 없다. 오디오 캡춰의 상세한 것에 대하여는, Microsoft® DirectSound® 의 문서를 참조할것.


DVMSGID_HOSTMIGRATED

음성 호스트가 변경되면(자), Microsoft® DirectPlay® Voice 에 의해 DVMSGID_HOSTMIGRATED 메세지가 생성된다.

DVMSG_HOSTMIGRATED

DVMSG_HOSTMIGRATED 구조체에는, DVMSGID_HOSTMIGRATED 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD                   dwSize;
    DVID                    dvidNewHostID;
    LPDIRECTPLAYVOICESERVER pdvServerInterface;
} DVMSG_HOSTMIGRATED, *LPDVMSG_HOSTMIGRATED, *PDVMSG_HOSTMIGRATED;
dwSize
DVMSG_HOSTMIGRATED 메세지 구조체의 사이즈.
dvidNewHostID
새로운 호스트의 DVID.
pdvServerInterface
로컬 클라이언트가 새로운 음성 세션 호스트가 되었을 경우, 이 멤버는 새롭게 생성 된 IDirectPlayVoiceServer 오브젝트를 나타낸다. 로컬 클라이언트는, 이 오브젝트를 사용해 호스트 서비스를 제공할 수 있다. 로컬 클라이언트가 새로운 호스트가 아닌 경우, 이 멤버는 NULL 가 된다. 이 파라미터가 IDirectPlayVoiceServer 인터페이스를 포인트 하는 경우,IDirectPlayVoiceServer::AddRef 를 호출해, 인터페이스의 참조 카운트를 인크리먼트(increment) 할 필요가 있다. 인터페이스가 불필요하게 되었을 때는,IDirectPlayVoiceServer::Release 를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_INPUTLEVEL

마이크로부터의 입력 레벨을 유저에게 알리기 (위해)때문에, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_INPUTLEVEL 메세지가 생성된다. 통지의 기간은,DVCLIENTCONFIG 구조체의 dwNotifyPeriod 멤버에 의해 설정된다. 통지의 기간이 0 으로 설정되었을 경우, 이 메세지는 송신되지 않는다. 또, 클라이언트가 반이중 모드로 동작하고 있는 경우, 이 메세지는 이용할 수 없다.

DVMSG_INPUTLEVEL

DVMSG_INPUTLEVEL 구조체에는, DVMSGID_INPUTLEVEL 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD dwSize;
    DWORD dwPeakLevel;
    LONG  lRecordVolume;
    PVOID pvLocalPlayerContext;
} DVMSG_INPUTLEVEL, *LPDVMSG_INPUTLEVEL, *PDVMSG_INPUTLEVEL;
dwSize
DVMSG_INPUTLEVEL 메세지 구조체의 사이즈.
dwPeakLevel
현재의 프레임의 피크 레벨을 나타내는 정수. 오디오 스트림의 약 1/10 초에 상당한다. 일반적으로 현재의 프레임은 리얼타임보다 50 ~ 200 밀리 세컨드 늦는다. 이 값은 0 ~ 99 의 범위가 된다. 0 은 완전하게 무음, 99 는 가능한 최대 입력 레벨을 나타낸다.
lRecordVolume
클라이언트의 현재의 녹음 볼륨. 값의 범위는 -10, 000 ~ 0. 이 멤버는, 자동 게인 제어가 액티브한 때에서도 사용할 수 있다.
pvLocalPlayerContext
로컬 플레이어에 대해서 설정된 문맥값에의 포인터. 이 값은,DVMSG_CREATEVOICEPLAYER 메세지 구조체의 pvPlayerContext 멤버에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_LOCALHOSTSETUP

호스트의 이행의 사이에 로컬 클라이언트가 새로운 음성 호스트로서 선택되면(자), DVMSGID_LOCALHOSTSETUP 메세지가 송신된다. 메세지는 DVMSGID_HOSTMIGRATED 메세지의 전에 송신되어 새로운 호스트 오브젝트를 생성 할 경우에 사용하는 콜백 함수와 문맥값을 설정할 기회를 개발자에게 준다. 개발자가 어느 값도 설정하지 않는 경우, 새로운 서버 인터페이스는 콜백 함수를 가지지 않는다. 어플리케이션이 이 메세지의 처리로부터 돌아오면(자), DVMSGID_HOSTMIGRATED 메세지를 받아들인다. 새로운 메세지에는 다음의 구조체를 관련지을 수 있고 있다. 이 구조체는, 메세지 핸들러의 void * 필드에게 건네진다.

DVMSG_LOCALHOSTSETUP

DVMSG_LOCALHOSTSETUP 구조체에는, DVMSGID_LOCALHOSTSETUP 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD dwSize;
    PVOID pvContext;
    PDVMESSAGEHANDLER pMessageHandler;
} DVMSG_LOCALHOSTSETUP, *LPDVMSG_LOCALHOSTSETUP, *PDVMSG_LOCALHOSTSETUP;
dwSize
DVMSG_LOCALHOSTSETUP 메세지 구조체의 사이즈.
pvContext
새로운 서버에 대해서 설정하는 문맥값을 설정한다.
pMessageHandler
새로운 서버에 사용하는 콜백 함수를 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언. 그리고 선언.


DVMSGID_LOSTFOCUS

오디오의 캡춰를 정지한 것을 알리기 (위해)때문에, DVMSGID_LOSTFOCUS 메세지가 송신된다. 캡춰의 포커스를 가지고 있는 어플리케이션으로부터 다른 어플리케이션에 포커스가 옮기면(자), 이 메세지가 송신된다. 이 메세지에 관련지을 수 있었던 데이터는 없다. 오디오 캡춰의 상세한 것에 대하여는, Microsoft® DirectSound® 의 설명을 참조할것.


DVMSGID_OUTPUTLEVEL

재생의 출력 레벨을 유저에게 알리기 (위해)때문에, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_OUTPUTLEVEL 메세지가 생성된다. 통지의 기간은,DVCLIENTCONFIG 구조체의 dwNotifyPeriod 멤버에 의해 설정된다. 통지의 기간이 0 으로 설정되었을 경우, 이 메세지는 송신되지 않는다.

DVMSG_OUTPUTLEVEL

DVMSG_OUTPUTLEVEL 구조체에는, DVMSGID_OUTPUTLEVEL 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwPeakLevel;
    LONG   lOutputVolume;
    PVOID  pvLocalPlayerContext;
} DVMSG_OUTPUTLEVEL, *LPDVMSG_OUTPUTLEVEL, *PDVMSG_OUTPUTLEVEL;
dwSize
DVMSG_OUTPUTLEVEL 메세지 구조체의 사이즈.
dwPeakLevel
재생의 현재의 출력 레벨을 나타내는 정수. 이 값은 0 ~ 99 의 범위가 된다. 0 은 완전하게 무음, 99 는 가능한 최대 입력 레벨을 나타낸다.
lOutputVolume
클라이언트의 현재의 재생 볼륨.
pvLocalPlayerContext
로컬 플레이어에 대해서 설정된 문맥값에의 포인터. 이 값은,DVMSG_CREATEVOICEPLAYER 메세지 구조체의 pvPlayerContext 멤버에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_PLAYEROUTPUTLEVEL

개개의 플레이어의 음성 스트림의 출력 레벨을 유저에게 알리기 (위해)때문에, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_PLAYEROUTPUTLEVEL 메세지가 정기적으로 생성된다. 개개의 플레이어에게 음성이 재생되고 있는 동안, 이 메세지가 생성된다. 복수의 플레이어의 음성이 재생되는 경우, 각 통지 기간으로, 플레이어의 음성 마다 1 개의 메세지가 송신된다.

통지의 기간은,DVCLIENTCONFIG 구조체의 dwNotifyPeriod 멤버에 의해 설정된다. 통지의 기간이 0 으로 설정되었을 경우, 이 메세지는 송신되지 않는다.

DVMSG_PLAYEROUTPUTLEVEL

DVMSG_PLAYEROUTPUTLEVEL 구조체에는, DVMSGID_PLAYEROUTPUTLEVEL 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    DVID   dvidSourcePlayerID;
    DWORD  dwPeakLevel;
    PVOID  pvPlayerContext;
} DVMSG_PLAYEROUTPUTLEVEL, *LPDVMSG_PLAYEROUTPUTLEVEL, *PDVMSG_PLAYEROUTPUTLEVEL;
dwSize
DVMSG_PLAYEROUTPUTLEVEL 메세지 구조체의 사이즈.
dvidSourcePlayerID
재생되는 음성의 플레이어의 DVID.
dwPeakLevel
플레이어의 음성 스트림의 현재의 출력 레벨을 나타내는 정수. 이 값은 0 ~ 99 의 범위가 된다. 0 은 완전하게 무음, 99 는 가능한 최대 입력 레벨을 나타낸다.
pvPlayerContext
플레이어에 대해서 설정된 문맥값에의 포인터. 이 값은,DVMSG_CREATEVOICEPLAYER 메세지 구조체의 pvPlayerContext 멤버에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_PLAYERVOICESTART

수신 오디오 스트림이 재생을 시작 하면, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_PLAYERVOICESTART 메세지가 생성된다.

DVMSG_PLAYERVOICESTART

DVMSG_PLAYERVOICESTART 구조체에는, DVMSGID_PLAYERVOICESTART 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    DVID   dvidSourcePlayerID;
    PVOID  pvPlayerContext;
} DVMSG_PLAYERVOICESTART, *LPDVMSG_PLAYERVOICESTART, *PDVMSG_PLAYERVOICESTART;
dwSize
DVMSG_PLAYERVOICESTART 메세지 구조체의 사이즈.
dvidSourcePlayerID
음성 전송이 시작 되는 플레이어의 DVID.
pvPlayerContext
플레이어에 대해서 설정된 문맥값에의 포인터. 이 값은,DVMSG_CREATEVOICEPLAYER 메세지 구조체의 pvPlayerContext 멤버에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_PLAYERVOICESTOP

수신 오디오 스트림이 정지 하면, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_PLAYERVOICESTOP 메세지가 생성된다.

DVMSG_PLAYERVOICESTOP

DVMSG_PLAYERVOICESTOP 구조체에는, DVMSGID_PLAYERVOICESTOP 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    DVID   dvidSourcePlayerID;
    PVOID  pvPlayerContext;
} DVMSG_PLAYERVOICESTOP, *LPDVMSG_PLAYERVOICESTOP, *PDVMSG_PLAYERVOICESTOP;
dwSize
DVMSG_PLAYERVOICESTOP 메세지 구조체의 사이즈.
dvidSourcePlayerID
음성 전송이 시작 되는 플레이어의 DVID.
pvPlayerContext
플레이어에 대해서 설정된 문맥값에의 포인터. 이 값은,DVMSG_CREATEVOICEPLAYER 메세지 구조체의 pvPlayerContext 멤버에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_RECORDSTART

로컬 클라이언트의 오디오 입력이 시작 되면(자), Microsoft® DirectPlay® Voice 에 의해 DVMSGID_RECORDSTART 메세지가 생성된다. 음성을 액티브하게 하는 감지 레벨을 넘는지, 푸쉬 투 토크 모드로 유효한 타겟이 지정되었을 경우, 오디오 입력은 시작 된다.

DVMSG_RECORDSTART

DVMSG_RECORDSTART 구조체에는, DVMSGID_RECORDSTART 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwPeakLevel;
    PVOID pvLocalPlayerContext;
} DVMSG_RECORDSTART, *LPDVMSG_RECORDSTART, *PDVMSG_RECORDSTART;
dwSize
DVMSG_RECORDSTART 메세지 구조체의 사이즈.
dwPeakLevel
송신을 시작 하는 음성을 액티브하게 하는 레벨. 푸쉬 투 토크 모드에서는, 이 값은 0 이다.
pvLocalPlayerContext
로컬 플레이어에 대해서 설정된 문맥값에의 포인터. 이 값은,DVMSG_CREATEVOICEPLAYER 메세지 구조체의 pvPlayerContext 멤버에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_RECORDSTOP

로컬 클라이언트의 오디오 입력이 정지 하면, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_RECORDSTOP 메세지가 생성된다. 음성을 액티브하게 하는 레벨에 이르지 않는가, 푸쉬 투 토크 모드로 타겟이 삭제되었을 경우, 오디오 입력은 정지한다.

DVMSG_RECORDSTOP

DVMSG_RECORDSTOP 구조체에는, DVMSGID_RECORDSTOP 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD dwSize;
    DWORD dwPeakLevel;
    PVOID pvLocalPlayerContext;
} DVMSG_RECORDSTOP, *LPDVMSG_RECORDSTOP, *PDVMSG_RECORDSTOP;
dwSize
DVMSG_RECORDSTOP 메세지 구조체의 사이즈.
dwPeakLevel
송신을 정지하는 음성을 액티브하게 하는 레벨. 푸쉬 투 토크 모드에서는, 이 값은 0 이다.
pvLocalPlayerContext
로컬 플레이어에 대해서 설정된 문맥값에의 포인터. 이 값은,DVMSG_CREATEVOICEPLAYER 메세지 구조체의 pvPlayerContext 멤버에 의해 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_SESSIONLOST

음성 세션이 종료 하면, Microsoft® DirectPlay® Voice 에 의해 DVMSGID_SESSIONLOST 메세지가 생성된다.

DVMSG_SESSIONLOST

DVMSG_SESSIONLOST 구조체에는, DVMSGID_SESSIONLOST 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD   dwSize;
    HRESULT hrResult;
} DVMSG_SESSIONLOST, *LPDVMSG_SESSIONLOST, *PDVMSG_SESSIONLOST;
dwSize
DVMSG_SESSIONLOST 메세지 구조체의 사이즈.
hrResult
세션이 종료한 이유를 나타내는 HRESULT.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


DVMSGID_SETTARGETS

IDirectPlayVoiceClient::SetTransmitTargets 메소드 또는 IDirectPlayVoiceServer::SetTransmitTargets 메소드가 불려 가면(자), Microsoft® DirectPlay® Voice 에 의해 DVMSGID_SETTARGETS 메세지가 생성된다.

DVMSG_SETTARGETS

DVMSG_SETTARGETS 구조체에는, DVMSGID_SETTARGETS 시스템 메세지에 관한 정보가 보관 유지된다.

typedef struct {
    DWORD dwSize;
    DWORD dwNumTargets;
    PDVID pdvidTargets;
} DVMSG_SETTARGETS, *LPDVMSG_SETTARGETS, *PDVMSG_SETTARGETS;
dwSize
DVMSG_SETTARGETS 메세지 구조체의 사이즈.
dwNumTargets
pdvidTargets 멤버에 보관 유지되는 DVID 의 수.
pdvidTargets
세트 타겟을 지정하는 DVID 의 배열. 타겟이 없는 경우, NULL 에도 설정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice.h 로 선언.


구조체

Microsoft® DirectPlay® 의 구조체를 다음에 나타낸다.

  • DPL_APPLICATION_INFO
  • DPL_CONNECT_INFO
  • DPL_CONNECTION_SETTINGS
  • DPL_PROGRAM_DESC
  • DPN_APPLICATION_DESC
  • DPN_BUFFER_DESC
  • DPN_CAPS
  • DPN_CONNECTION_INFO
  • DPN_GROUP_INFO
  • DPN_PLAYER_INFO
  • DPN_SECURITY_CREDENTIALS
  • DPN_SECURITY_DESC
  • DPN_SERVICE_PROVIDER_INFO
  • DPN_SP_CAPS
  • DVCAPS
  • DVCLIENTCONFIG
  • DVCOMPRESSIONINFO
  • DVSESSIONDESC
  • DVSOUNDDEVICECONFIG


DPL_APPLICATION_INFO

IDirectPlay8LobbyClient::EnumLocalPrograms 메소드의 pEnumData 파라미터로 사용되어 로비 어플리케이션을 기술한다.

typedef struct _DPL_APPLICATION_INFO {
    GUID  guidApplication;
    PWSTR pwszApplicationName;
    DWORD dwNumRunning;
    DWORD dwNumWaiting;
    DWORD dwFlags;
} DPL_APPLICATION_INFO,  *PDPL_APPLICATION_INFO;

멤버

guidApplication
로비 어플리케이션을 지정하는 GUID 형의 변수.
pwszApplicationName
로비 어플리케이션의 이름을 보관 유지하는 WSTR 형의 변수에의 포인터.
dwNumRunning
어플리케이션의 인스턴스수.
dwNumWaiting
로비 어플리케이션에의 접속을 기다리는 클라이언트수.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


DPL_CONNECT_INFO

IDirectPlay8LobbyClient::ConnectApplication 메소드로 사용해, 로비 어플리케이션에 접속할 경우에 로비 클라이언트의 접속 정보를 지정한다.

typedef struct _DPL_CONNECT_INFO {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidApplication;
    PDPL_CONNECTION_SETTINGS pdplConnectionSettings;
    PVOID pvLobbyConnectData;
    DWORD dwLobbyConnectDataSize;
} DPL_CONNECT_INFO,  *PDPL_CONNECT_INFO;

멤버

dwSize
DPL_CONNECT_INFO 구조체의 사이즈. 어플리케이션은, 이 구조체를 사용하기 전에, 우선 이 멤버를 설정할 필요가 있다.
dwFlags
접속 동작을 결정하는 다음의 몇개의 플래그.
DPLCONNECT_LAUNCHNEW
어플리케이션의 새로운 인스턴스를 기동한다.
DPLCONNECT_LAUNCHNOTFOUND
기동 설정을 제공할 수 있는 어플리케이션이 실행되어 있지 않은 경우에게만, 어플리케이션의 새로운 인스턴스를 기동한다.
guidApplication
어플리케이션을 지정하는 GUID 형의 변수.
pdplConnectionSettings
접속이 확립했을 때에 접속에 관련짓는 접속 설정을 보관 유지한다.
pvLobbyConnectData
로비 어플리케이션에게 건네진 접속 데이터에의 포인터.
dwLobbyConnectDataSize
pvLobbyConnectData 멤버의 데이터 버퍼의 사이즈를 지정하는 DWORD 형의 변수.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언. 그리고 선언.


DPL_CONNECTION_SETTINGS

접속에 관련짓는 설정을 지정하기 위해서 사용한다. 접속 설정에는, Microsoft® DirectPlay® 오브젝트의 초기화와 접속 또는 호스트를 실시하기 위해서(때문에) 필요한, 모든 정보가 포함된다.

typedef struct _DPL_CONNECTION_SETTINGS {
    DWORD                   dwSize;
    DWORD                   dwFlags;
    DPN_APPLICATION_DESC    dpnAppDesc;
    IDirectPlay8Address*    pdp8HostAddress;
    IDirectPlay8Address**   ppdp8DeviceAddresses;
    DWORD                   cNumDeviceAddresses;
    PWSTR                   pwszPlayerName
} DPL_CONNECTION_SETTINGS, *PDPL_CONNECTION_SETTINGS;

멤버

dwSize
DPL_CONNECTION_SETTINGS 구조체의 사이즈. 어플리케이션은, 이 구조체를 사용하기 전에, 이 멤버를 sizeof( DPL_CONNECTION_SETTINGS )로 설정할 필요가 있다.
dwFlags
다음의 플래그의 편성.
DPLCONNECTSETTINGS_CLIENTSERVER
어플리케이션은 클라이언트/서버 세션으로 기동할 필요가 있다.
DPLCONNECTSETTINGS_HOST
어플리케이션은 세션을 호스트 할 필요가 있다.
dpnAppDesc
DirectPlay 가 초기화될 때,Connect 또는 Host 호출에 건네주는 어플리케이션 기술에의 포인터.
pdp8HostAddress
DPLCONNECTSETTINGS_HOST 가 지정되어 있지 않은 경우, 이것은, 클라이언트가 접속해야 하는 세션의 주소이다. DPLCONNECTSETTINGS_HOST 를 지정했을 경우는, 이 멤버는 NULL 가 아니면 안된다.
ppdp8DeviceAddresses
이 구조체에는 디바이스 주소에의 포인터의 배열이 보관 유지된다. DPLCONNECTSETTINGS_HOST 를 지정했을 경우, 이 멤버에는 호스트가 청취하는 주소가 보관 유지된다. DPLCONNECTSETTINGS_HOST 를 지정하지 않는 경우, 이 멤버에는 접속시에 클라이언트가 사용하는 디바이스의 주소가 보관 유지된다.
cNumDeviceAddresses
ppdp8DeviceAddresses 멤버로 지정되고 있는 주소의 수.
pwszPlayerName
기동시에 DirectPlay 오브젝트에 사용시키고 싶은 플레이어명을 건네줄 수가 있다. 이 멤버는 NULL 로 지정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


DPL_PROGRAM_DESC

Microsoft® DirectPlay® 로비 대응 어플리케이션을 기술한다.

typedef struct _DPL_PROGRAM_DESC {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidApplication;
    PWSTR pwszApplicationName;
    PWSTR pwszCommandLine;
    PWSTR pwszCurrentDirectory;
    PWSTR pwszDescription;
    PWSTR pwszExecutableFilename;
    PWSTR pwszExecutablePath;
    PWSTR pwszLauncherFilename;
    PWSTR pwszLauncherPath;
} DPL_PROGRAM_DESC, *PDPL_PROGRAM_DESC;

멤버

dwSize
DPL_PROGRAM_DESC 구조체의 사이즈. 어플리케이션은, 이 구조체를 사용하기 전에, 우선 이 멤버를 설정할 필요가 있다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.
guidApplication
어플리케이션을 지정하는 GUID 형의 변수.
pwszApplicationName
어플리케이션명에의 포인터.
pwszCommandLine
커멘드 라인 인수에의 포인터.
pwszCurrentDirectory
어플리케이션의 작업 디렉토리로서 설정해야 하는 디렉토리에의 포인터.
pwszDescription
어플리케이션의 기술에의 포인터.
pwszExecutableFilename
어플리케이션의 실행 가능 파일명에의 포인터.
pwszExecutablePath
어플리케이션의 실행 가능 파일의 패스에의 포인터.
pwszLauncherFilename
란체의 실행 가능 파일명에의 포인터.
pwszLauncherPath
란체의 실행 가능 파일의 패스에의 포인터.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplobby8.h 로 선언.


DPN_APPLICATION_DESC

Microsoft® DirectPlay® 어플리케이션의 설정을 기술한다.

typedef struct _DPN_APPLICATION_DESC{
    DWORD  dwSize;
    DWORD  dwFlags;
    GUID   guidInstance;
    GUID   guidApplication;
    DWORD  dwMaxPlayers;
    DWORD  dwCurrentPlayers;
    WCHAR* pwszSessionName;
    WCHAR* pwszPassword;
    PVOID  pvReservedData;
    DWORD  dwReservedDataSize;
    PVOID  pvApplicationReservedData;
    DWORD  dwApplicationReservedDataSize;
} DPN_APPLICATION_DESC, *PDPN_APPLICATION_DESC;

멤버

dwSize
DPN_APPLICATION_DESC 구조체의 사이즈. 어플리케이션은, 이 구조체를 사용하기 전에, 우선 이 멤버를 설정할 필요가 있다.
dwFlags
어플리케이션의 동작을 기술하는 다음의 몇개의 플래그.
DPNSESSION_CLIENT_SERVER
이 타입의 세션은 클라이언트/서버이다. 이 플래그를 DPNSESSION_MIGRATE_HOST 와 조합할 수 없다.
DPNSESSION_MIGRATE_HOST
피어 투 피어 세션으로 사용되어 호스트의 이행을 가능하게 한다. 이 플래그를 DPNSESSION_CLIENT_SERVER 와 조합할 수 없다.
DPNSESSION_NODPNSVR
DPNSVR 로부터 호스트에게 열거를 전송 하지 않는다. 상세한 것에 대하여는, 「DirectPlay DPNSVR 어플리케이션의 사용법」을 참조할것.
DPNSESSION_REQUIREPASSWORD
세션을 패스워드에 의해 보호한다. 이 플래그를 설정했을 경우, pwszPassword 에 유효한 캐릭터 라인을 지정할 필요가 있다.
guidInstance
기동시에 DirectPlay 에 의해 생성되어 이 어플리케이션의 인스턴스를 나타내는 글로벌 유니크 식별자 (GUID). 이 멤버는,IDirectPlay8Peer ,IDirectPlay8Client , 및 IDirectPlay8Server 인터페이스로 공개되는 GetApplicationDesc 메소드를 호출하면나무의 [out] 파라미터이다. 또,IDirectPlay8Peer 및 IDirectPlay8Client 인터페이스로 공개되는 Connect 메소드를 호출하면나무의, 옵션의 [in] 파라미터이다. IDirectPlay8Server 및 IDirectPlay8Peer 인터페이스로 공개되는 SetApplicationDesc 메소드를 호출하면나무는, NULL 로 설정할 필요가 있다. IDirectPlay8Server::Host 또는 IDirectPlay8Peer::Host 메소드를 호출해 이 GUID 를 취득할 수 없다. GUID 는 GetApplicationDesc 메소드를 호출해 취득해야 한다.
guidApplication
어플리케이션 GUID.
dwMaxPlayers
세션으로 사용 가능한 플레이어의 최대수를 지정하는 DWORD 형의 변수. 플레이어의 수를 무제한하게 하면나무는, 이 멤버를 0 으로 설정한다.
dwCurrentPlayers
세션에 현재 접속되고 있는 플레이어의 수를 지정하는 DWORD 형의 변수. 이 멤버는,IDirectPlay8Peer,IDirectPlay8Client, 및 IDirectPlay8Server 에서 공개되는 GetApplicationDescription 메소드에 의해서만 설정되는 [out] 파라미터이다.
pwszSessionName
세션의 Unicode™ 명을 지정하는 WCHAR 형의 변수에의 포인터. 이 멤버는, 정보를 전할 뿐(만큼)의 목적으로 호스트 또는 서버에 의해 설정된다. 클라이언트가 이 이름을 사용해 호스트 또는 서버에 접속할 수 없다.
pwszPassword
세션에의 접속에 필요한 Unicode 패스워드를 지정하는 WCHAR 형의 변수에의 포인터. dwFlags 멤버에 DPNSESSION_REQUIREPASSWORD 가 설정되어 있지 않은 경우, 이 값은 NULL 로 할 필요가 있다.
pvReservedData
DirectPlay 의 예약이 끝난 데이터에의 포인터. 어플리케이션은 이 값을 변경해서는 안 된다.
dwReservedDataSize
pvReservedData 멤버에 보관 유지되고 있는 데이터의 사이즈를 지정하는 DWORD 형의 변수. 어플리케이션은 이 값을 변경해서는 안 된다.
pvApplicationReservedData
어플리케이션 고유의 예약이 끝난 데이터에의 포인터. 이 값은 옵션이며, NULL 로 설정할 수 있다.
dwApplicationReservedDataSize
pvApplicationReservedData 멤버의 데이터의 사이즈를 지정하는 DWORD 형의 변수. 이 값은 옵션이며, NULL 로 설정할 수 있다.

주의

dwMaxPlayers,pvApplicationReservedData,dwApplicationReservedDataSize,pwszPassword, 및 pwszSessionName 멤버는,IDirectPlay8Server 및 IDirectPlay8Peer 인터페이스로 공개되는 Host 또는 SetApplicationDesc 메소드를 호출하면나무로 설정할 수 있다. 세션중의 player의 현재의 수보다 작은 값으로 dwMaxPlayers 파라미터를 설정할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_BUFFER_DESC

범용 버퍼 정보에 관해서 Microsoft® DirectPlay® 에 의해 사용된다.

typedef struct _BUFFERDESC{
    DWORD  dwBufferSize;
    BYTE*  pBufferData;
} BUFFERDESC, DPN_BUFFER_DESC;

멤버

dwBufferSize
pBufferData 멤버의 데이터 버퍼의 사이즈를 지정하는 DWORD 형의 변수.
pBufferData
버퍼의 데이터를 보관 유지하는 BYTE 형의 변수에의 포인터.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_CAPS

DirectPlay 용의 범용 파라미터의 설정과 취득에 사용한다.

typedef struct _DPN_CAPS{
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwConnectTimeout;
    DWORD dwConnectRetries;
    DWORD dwTimeoutUntilKeepAlive;
} DPN_CAPS, *PDPN_CAPS;

멤버

dwSize
이 값은, 구조체의 사이즈로 설정할 필요가 있다.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.
dwConnectTimeout
DirectPlay 가 접속 요구를 재발송신 할 때까지 대기하는 시간 (밀리 세컨드 단위).
dwConnectRetries
DirectPlay 가 접속 처리중에 실시하는 접속의 재시행의 회수.
dwTimeoutUntilKeepAlive
DirectPlay 가, 마지막에 엔드 포인트로부터 패킷을 받고 나서 킵얼라이브 메세지를 송신하기까지 대기하는 시간 (밀리 세컨드 단위).

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_CONNECTION_INFO

유저와 유저가 접속되고 있는 리모트 컴퓨터와의 접속에 관한 통계 정보를 취득하기 위해서 사용한다.

typedef struct _DPN_CONNECTION_INFO{
    DWORD   dwSize;
    DWORD   dwRoundTripLatencyMS;
    DWORD   dwThroughputBPS;
    DWORD   dwPeakThroughputBPS;
    DWORD   dwBytesSentGuaranteed;
    DWORD   dwPacketsSentGuaranteed;
    DWORD   dwBytesSentNonGuaranteed;
    DWORD   dwPacketsSentNonGuaranteed;
    DWORD   dwBytesRetried;
    DWORD   dwPacketsRetried;
    DWORD   dwBytesDropped;
    DWORD   dwPacketsDropped;
    DWORD   dwMessagesTransmittedHighPriority;
    DWORD   dwMessagesTimedOutHighPriority;
    DWORD   dwMessagesTransmittedNormalPriority;
    DWORD   dwMessagesTimedOutNormalPriority;
    DWORD   dwMessagesTransmittedLowPriority;
    DWORD   dwMessagesTimedOutLowPriority;
    DWORD   dwBytesReceivedGuaranteed;
    DWORD   dwPacketsReceivedGuaranteed;
    DWORD   dwBytesReceivedNonGuaranteed;
    DWORD   dwPacketsReceivedNonGuaranteed;
    DWORD   dwMessagesReceived;
} DPN_CONNECTION_INFO, *PDPN_CONNECTION_INFO;

멤버

dwSize
구조체의 사이즈.
dwRoundTripLatencyMS
패킷이 리모트 컴퓨터에 도달해, 로컬 컴퓨터에 돌아올 때까지의 시간의 개산값 (밀리 세컨드 단위). 링크의 조건이 변경되기 (위해)때문에, 이 값은 세션 전체에 걸쳐서 변화한다.
dwThroughputBPS
바이트/초 (Bps) 단위로 나타낸 링크의 throughput의 개산값. 링크의 조건이 변경되기 (위해)때문에, 이 값은 세션 전체에 걸쳐서 변화한다. 이 값은 개산이며, 자기 자신의 값을 보다 정확하게 계산할 수도 있다.
dwPeakThroughputBPS
비트/초 (bps) 단위로 나타낸 링크의 피크 throughput값. 링크의 조건이 변경되기 (위해)때문에, 이 값은 세션 전체에 걸쳐서 변화한다. 이 값은 개산이며, 자기 자신의 값을 보다 정확하게 계산할 수도 있다.
dwBytesSentGuaranteed
송신된 보증 첨부 메세지의 총수 (바이트 단위).
dwPacketsSentGuaranteed
송신된 보증 첨부 메세지의 패킷의 수.
dwBytesSentNonGuaranteed
송신된 보증 첨부가 아닌 메세지의 총수 (바이트 단위).
dwPacketsSentNonGuaranteed
송신된 보증 첨부가 아닌 메세지의 패킷의 수.
dwBytesRetried
재시행된 메세지의 총수 (바이트 단위).
dwPacketsRetried
재시행된 패킷의 수.
dwBytesDropped
삭제된 메세지의 총수 (바이트 단위).
dwPacketsDropped
삭제된 패킷의 수.
dwMessagesTransmittedHighPriority
전송 된 우선 순위의 높은 메세지의 수.
dwMessagesTimedOutHighPriority
타임 아웃 한 우선 순위의 높은 메세지의 수.
dwMessagesTransmittedNormalPriority
전송 된 보통 우선 순위의 메세지의 수.
dwMessagesTimedOutNormalPriority
타임 아웃 한 보통 우선 순위의 메세지의 수.
dwMessagesTransmittedLowPriority
전송 된 우선 순위의 낮은 메세지의 수.
dwMessagesTimedOutLowPriority
타임 아웃 한 우선 순위의 낮은 메세지의 수.
dwBytesReceivedGuaranteed
수신된 보증 첨부 메세지의 총수 (바이트 단위).
dwPacketsReceivedGuaranteed
수신된 보증 첨부 메세지의 패킷의 수.
dwBytesReceivedNonGuaranteed
수신된 보증 첨부가 아닌 메세지의 총수 (바이트 단위).
dwPacketsReceivedNonGuaranteed
수신된 보증 첨부가 아닌 메세지의 패킷의 수.
dwMessagesReceived
수신된 메세지의 수.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_GROUP_INFO

정적 그룹 정보를 기술한다.

typedef struct _DPN_GROUP_INFO{
    DWORD  dwSize;
    DWORD  dwInfoFlags;
    PWSTR  pwszName;
    PVOID  pvData;
    DWORD  dwDataSize;
    DWORD  dwGroupFlags;
} DPN_GROUP_INFO, *PDPN_GROUP_INFO;

멤버

dwSize
구조체의 사이즈를 기술하는 DWORD 형의 변수.
dwInfoFlags

이 구조체에 포함되는 형태 정보를 지정하는 플래그를 보관 유지하는 DWORD 형의 변수. GetGroupInfo 메소드가 값을 돌려주면(자),DPN_GROUP_INFO 의 dwInfoFlags 멤버는, 대응하는 포인터가 NULL 로 설정되어 있는 경우에서도, 반드시 양쪽 모두의 플래그가 설정된다. 이러한 플래그는,IDirectPlay8Peer::SetGroupInfo 의 호출에 사용되어 Microsoft® DirectPlay® 로 변경된 값을 알린다.

DPNINFO_NAME
pwszName 멤버에 유효한 데이터가 포함된다.
DPNINFO_DATA
pvData 멤버에 유효한 데이터가 포함된다.
pwszName
그룹의 Unicode 명을 지정하는 PWSTR 형의 변수에의 포인터.
pvData
그룹을 기술하는 데이터에의 포인터.
dwDataSize
pvData 멤버에 포함되는 데이터 사이즈를 지정하는 DWORD 형의 변수.
dwGroupFlags
다음의 기술 플래그를 설정할 수 있는 DWORD 형의 변수.
DPNGROUP_AUTODESTRUCT
그룹의 생성자가 그룹을 떠나면(자), 그룹은 자동적으로 파기된다.

주의

IDirectPlay8Peer::GetGroupInfo 메소드와 IDirectPlay8Server::GetGroupInfo 메소드로 이 구조체를 사용하는 경우,dwInfoFlags 는 0 으로 설정할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_PLAYER_INFO

정적 플레이어 정보를 기술한다.

typedef struct _DPN_PLAYER_INFO{
    DWORD  dwSize;
    DWORD  dwInfoFlags;
    PWSTR  pwszName;
    PVOID  pvData;
    DWORD  dwDataSize;
    DWORD  dwPlayerFlags;
} DPN_PLAYER_INFO, *PDPN_PLAYER_INFO;

멤버

dwSize
구조체의 사이즈를 기술하는 DWORD 형의 변수.
dwInfoFlags
이 구조체에 포함되는 형태 정보를 지정하는 플래그를 보관 유지하는 DWORD 형의 변수. GetPlayerInfo 메소드가 값을 돌려주면(자),DPN_PLAYER_INFO 의 dwInfoFlags 멤버는, 대응하는 포인터가 NULL 로 설정되어 있는 경우에서도, 반드시 양쪽 모두의 플래그가 설정된다. 이러한 플래그는,IDirectPlay8Peer::SetPeerInfo 의 호출에 사용되어 Microsoft® DirectPlay® 로 변경된 값을 알린다.
DPNINFO_NAME
pwszName 멤버에 유효한 데이터가 포함된다.
DPNINFO_DATA
pvData 멤버에 유효한 데이터가 포함된다.
pwszName
플레이어의 Unicode 명을 지정하는 PWSTR 형의 변수에의 포인터.
pvData
플레이어를 기술하는 데이터에의 포인터.
dwDataSize
pvData 멤버에 포함되는 데이터 사이즈를 지정하는 DWORD 형의 변수.
dwPlayerFlags
이하의 몇개의 플래그를 보관 유지하는 DWORD 형의 변수.
DPNPLAYER_LOCAL
이 정보는 로컬 플레이어용이다.
DPNPLAYER_HOST
이 플레이어는 어플리케이션의 호스트이다.

주의

IDirectPlay8Peer::GetPeerInfo 메소드와 IDirectPlay8Server::GetClientInfo 메소드로 이 구조체를 사용하는 경우,dwInfoFlags 는 0 으로 설정할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_SECURITY_CREDENTIALS

이행되어 있지 않다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_SECURITY_DESC

이행되어 있지 않다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_SERVICE_PROVIDER_INFO

특정의 서비스 프로바이더의 정보를 열거하는 경우에 사용한다.

typedef struct _DPN_SERVICE_PROVIDER_INFO{
    DWORD  dwFlags;
    GUID  Guid;
    WCHAR* pwszName;
    PVOID  pvReserved;
    DWORD  dwReserved;
} DPN_SERVICE_PROVIDER_INFO, *PDPN_SERVICE_PROVIDER_INFO;

멤버

dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.
pGuid
서비스 프로바이더의 GUID.
pwszName
서비스 프로바이더의 이름.
pvReserved
예약이 끝난 상태. 0 으로 설정해 둔다.
dwReserved
예약이 끝난 상태. 0 으로 설정해 둔다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DPN_SP_CAPS

서비스 프로바이더용의 파라미터의 설정과 취득에 사용한다.

typedef struct _DPN_SP_CAPS{
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwNumThreads;
    DWORD  dwDefaultEnumCount;
    DWORD  dwDefaultEnumRetryInterval;
    DWORD  dwDefaultEnumTimeout;
    DWORD  dwMaxEnumPayloadSize;
    DWORD  dwBuffersPerThread;
    DWORD  dwSystemBufferSize;

} DPN_SP_CAPS, *PDPN_SP_CAPS;

멤버

dwSize
이 값은, 구조체의 사이즈로 설정할 필요가 있다.
dwFlags
다음의 플래그를 조합해 사용할 수 있다.
DPNSPCAPS_SUPPORTSDPNSRV
DPNSVR.EXE 는 특정의 서비스 프로바이더에 포토 공유를 제공한다. 현재, 이 플래그는 IP 와 IPX 에 대해서만 이용할 수 있다. DPNSVR 의 상세한 것에 대하여는, 「DirectPlay DPNSVR 어플리케이션의 사용법」을 참조할것.
DPNSPCAPS_SUPPORTSBROADCAST
IP 및 IPX 어플리케이션으로, 건네받은 주소 정보가 부족하는 경우, 서비스 프로바이더가 있는 요소를 전요소에 카피해 게임을 검색할 수 있다.
DPNSPCAPS_SUPPORTSALLADAPTERS
서비스 프로바이더는, 시스템 위에의 모든 디바이스를 사용한다. 디바이스 요소를 지정할 필요는 없다.
dwNumThreads
서비스 프로바이더가 네트워크 요구의 서비스에 사용하는 thread의 수. 디폴트값은, 시스템의 프로세서수를 고려한 알고리즘에 근거해 설정된다. 대부분의 어플리케이션에서는 이 값을 변경할 필요가 없다.

프로세스로 서비스 프로바이더가 액티브하게 된 후는, 이 값을 증가할 수 밖에 할 수 없다. 이 값을 감소해도 효과가 없다. 설정은 프로세스 전체에 유효하고, 유저의 현재의 DirectPlay 오브젝트와 프로세스내외의 모든 DirectPlay 오브젝트에 영향을 준다.

EnumHosts,Connect, 또는 Host 를 호출하기 전에 SetSPCaps 메소드를 호출했을 경우, 디폴트값보다 작은 값을 지정할 수 있다.

dwDefaultEnumCount
디폴트의 열거 카운트.
dwDefaultEnumRetryInterval
디폴트의 재시행 간격 (밀리 세컨드 단위).
dwDefaultEnumTimeout
디폴트의 열거 타임 아웃값 (밀리 세컨드 단위).
dwMaxEnumPayloadSize
DPN_MSGID_ENUM_HOST_QUERY 및 DPN_MSGID_ENUM_HOST_RESPONSE 메세지를 수반하는 구조체의 pvResponseData 멤버에 송신할 수 있는 플레이 로드 정보의 최대 사이즈.
dwBuffersPerThread
각 DirectPlay thread에 할당하는 미처리의 수신 버퍼의 수. 수신 버퍼의 수를 증가했을 경우, DirectPlay 은 operating system 버퍼로부터 보다 많은 데이터를 꺼낼 수가 있다. 다만, 어플리케이션의 처리 속도가 데이터의 도착하는 속도를 따라 잡지 않는 경우는, 지연 시간을 연장할 수도 있다.
dwSystemBufferSize
operating system 버퍼의 사이즈. 이 버퍼는, 어플리케이션의 처리 속도가 데이터의 도착하는 속도를 따라 잡지 않을 때, 통신 디바이스로부터의 데이터를 보관 유지한다. 이 버퍼의 목적은, 돌연에 대량의 데이터를 받았을 경우, 또는 수신 thread가 순간적으로 stall 되었을 경우에, 데이터의 손실을 막는 것이다. 어플리케이션이 수신 데이터를 적절한 속도로 처리할 수 없는 경우,dwSystemBufferSize 를 증가 하면 지연 시간이 길어지는 일이 있다. dwSystemBufferSize 를 0 으로 설정 하면, operating system 버퍼를 없앨 수가 있다. 다만, 이것을 실시하면, 수신한 데이터를 도착 후 곧바로 처리할 수 없는 경우에, 데이터가 없어질 우려가 있다.

주의

DirectX 8.0 에서는, IP 및 IPX 서비스 프로바이더는 dwBuffersPerThread 및 dwSystemBufferSize 멤버만을 사용한다. 이러한 멤버의 디폴트값은, 서비스 프로바이더가 설정한다. 디폴트값을 판단하려면 ,GetSPCaps 메소드를 호출한다. 대부분의 어플리케이션에서는, 이것들 2 개의 멤버에 디폴트값을 사용할 필요가 있다. 이러한 멤버는, 기본적으로는, 대량의 데이터를 처리하는 멀티 플레이어 게임용 서버 어플리케이션을 생성 하는 개발자가 사용한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dplay8.h 로 선언.


DVCAPS

Microsoft® DirectPlay® VoiceClient 오브젝트의 능력을 기술한다.

typedef struct{
    DWORD dwSize;
    DWORD dwFlags;
} DVCAPS, *LPDVCAPS, *PDVCAPS;

멤버

dwSize
이 구조체를 사용하기 전에, 이 구조체의 사이즈 (바이트 단위)로 설정할 필요가 있다.
dwFlags
예약이 끝난 상태. 0 으로 설정해 둔다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice8.h 로 선언.


DVCLIENTCONFIG

클라이언트의 실행시의 파라미터를 제어한다. 최초,IDirectPlayVoiceClient::Connect 의 호출해에 이 구조체를 사용해, 파라미터의 초기 상태를 설정한다. 접속의 확립 후, 이 구조체를 취득하려면 IDirectPlayVoiceClient::GetClientConfig 를 호출한다. 이 구조체를 설정하려면 ,IDirectPlayVoiceClient::SetClientConfig 를 사용한다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    LONG   lRecordVolume;
    LONG   lPlaybackVolume;
    DWORD  dwThreshold;
    DWORD  dwBufferQuality;
    DWORD  dwBufferAggressiveness;
    DWORD  dwNotifyPeriod;
} DVCLIENTCONFIG, *LPDVCLIENTCONFIG, *PDVCLIENTCONFIG;

멤버

dwSize
이 구조체를 사용하기 전에, 이 구조체의 사이즈 (바이트 단위)로 설정할 필요가 있다.
dwFlags
다음의 플래그의 편성.
DVCLIENTCONFIG_AUTORECORDVOLUME
자동 게인 제어를 액티브하게 한다. Microsoft® DirectPlay® Voice 에서는, 자동 게인 제어를 사용해, 사운드 카드로 하드웨어 입력 볼륨을 자동조정 해, 입력 레벨을 최적으로 한다. 현재의 입력 볼륨을 조사하려면 ,IDirectPlayVoiceClient::GetClientConfig 를 호출한 후에 lRecordVolume 멤버를 조사하는지,DVMSG_INPUTLEVEL 메세지의 lRecordVolume 멤버를 조사한다.
DVCLIENTCONFIG_ECHOSUPPRESSION
메아리 억제 모드를 액티브하게 한다. 이 모드는, 외부 스피커와 고감도 마이크에 의한 구성으로 발생하는 메아리를 감소시킨다. 리모트 플레이어의 음성은 로컬 스피커로 재생되지만, 마이크는 자동적으로 뮤트 된다. 로컬 플레이어가 발신하는 경우, 로컬 입력이 정지할 때까지, 리모트 플레이어의 음성의 재생은 버퍼에 저장 된다. 로컬 입력이 정지한 후, 재생이 재개한다.
DVCLIENTCONFIG_MUTEGLOBAL
메인 사운드 버퍼의 재생을 뮤트 한다. IDirectPlayVoiceClient::Create3DSoundBuffer 를 호출해 생성 된 사운드 버퍼만이 재생된다.
DVCLIENTCONFIG_PLAYBACKMUTE
모든 DirectPlay Voice 출력의 재생을 뮤트 해, 재생을 정지한다. 또, 수신 패킷의 압축의 복원도 정지하기 위해(때문에), CPU 의 사용량이 감소한다. 이 플래그가 지정되고 있는 동안, 패킷은 실질적으로 폐기된다.
DVCLIENTCONFIG_RECORDMUTE
마이크로부터의 입력을 뮤트 해, 녹음을 정지한다. 또, 압축도 정지하기 위해(때문에), CPU 의 사용량은 감소한다.

위의 플래그에 가세해 다음의 플래그의 어느쪽이든 한편을 설정하는지, 어느쪽이나 지정하지 않는 것으로, 전송 방법을 제어할 수 있다.

DVCLIENTCONFIG_AUTOVOICEACTIVATED
전송 제어 시스템을 자동 음성을 액티브하게 하는 모드로 한다. 이 모드에서는, 음성을 액티브하게 하는 감도는 시스템에 의해 자동적으로 결정된다. 입력 레벨은, 입력 신호에 맞추어 자동적으로 조정된다. 대부분의 어플리케이션에서는, 이 설정을 사용한다. 이 플래그는 DVCLIENTCONFIG_MANUALVOICEACTIVATED 플래그와 서로 배타적이다.
DVCLIENTCONFIG_MANUALVOICEACTIVATED
전송 제어 시스템을 수동 음성을 액티브하게 하는 모드로 한다. 이 모드에서는, 입력 레벨이 dwThreshold 멤버로 지정된 레벨을 넘으면(자), 음성의 전송이 시작 된다. 입력 레벨이 지정 레벨보다 아래가 되면(자), 전송은 정지한다. 이 플래그는 DVCLIENTCONFIG_AUTOVOICEACTIVATED 플래그와 서로 배타적이다.

DVCLIENTCONFIG_MANUALVOICEACTIVATED 및 DVCLIENTCONFIG_AUTOVOICEACTIVATED 의 어느쪽이나 지정하지 않는 경우, 시스템은 푸쉬 투 토크 모드로 동작한다. 푸쉬 투 토크 모드에서는, 유효한 타겟이 지정되고 있는 한, 마이크로부터의 입력은 전송 된다. NULL 타겟이 설정되는지, 현재의 타겟이 세션을 떨어지는지, 또는 현재의 타겟이 파기되었을 경우, 음성 전송은 정지한다.

lRecordVolume
설정하는 녹음의 볼륨을 나타내는 값. 유효한 값에 대해서는, 「IDirectSoundBuffer8::SetVolume 」메소드를 참조할것.

자동 게인 제어가 유효하게 되어 있는 경우, 이 값을 DVRECORDVOLUME_LAST 로 설정할 수 있다. 이 경우, 시스템은, 자동 게인 제어 알고리즘으로 정해진 현재의 볼륨을 사용한다. DVRECORDVOLUME_LAST 이외의 값을 지정해 자동 게인 제어에 조합했을 경우, 지정한 값으로 알고리즘이 재개한다.

IDirectPlayVoiceClient::GetClientConfig 를 호출하면, 이 값에 현재의 녹음 볼륨이 저장 된다. DirectPlay Voice 에서는, 녹음 볼륨을 조정 하면 와, 마이크의 볼륨 (카드용의 마이크의 볼륨이 존재하는 경우) 및 마스터 녹음 볼륨 (카드로 존재하는 경우)을 조정한다. 마이크의 볼륨과 마스터 녹음 볼륨이 어느쪽이나 존재하지 않는 경우, DirectPlay Voice 는 녹음 볼륨을 조정할 수 없다.

lPlaybackVolume
설정하는 재생의 볼륨을 나타내는 값. 이 볼륨을 조정 하면, 메인 버퍼와 모든 3D 사운드 버퍼가 조정된다. 유효한 값에 대해서는, 「IDirectSoundBuffer8::SetVolume 」메소드를 참조할것. DVPLAYBACKVOLUME_DEFAULT 를 지정 하면, 대부분의 상황에 적절한 디폴트값 (풀 볼륨)을 사용할 수 있다.
dwThreshold
dwFlags 멤버에 DVCLIENTCONFIG_MANUALVOICEACTIVATED 플래그를 지정했을 경우에 음성 전송의 방아쇠에 사용되는 입력 레벨. 이 플래그를 지정했을 경우, DVTHRESHOLD_MIN 로부터 DVTHRESHOLD_MAX 까지의 임의의 값을 지정할 수 있다. 또, DVTHRESHOLD_DEFAULT 를 설정 하면, 디폴트값을 사용할 수 있다.

이 구조체의 dwFlags 멤버에 DVCLIENTCONFIG_MANUALVOICEACTIVATED 또는 DVCLIENTCONFIG_AUTOVOICEACTIVATED 를 지정하고 있지 않는 경우 (푸쉬 투 토크 모드를 나타낸다), 이 값은 DVTHRESHOLD_UNUSED 로 지정할 필요가 있다.

dwBufferQuality
적응 버퍼링 알고리즘의 버퍼 품질의 설정. 대부분의 어플리케이션에서는, DVBUFFERQUALITY_DEFAULT 로 설정한다. DVBUFFERQUALITY_MIN 로부터 DVBUFFERQUALITY_MAX 까지의 임의의 값으로 설정할 수 있다. 일반적으로, 값이 큰 만큼 음성의 질은 높아지지만, 지연 시간은 길어진다. 값이 작을 정도 지연 시간은 짧아지지만, 질은 저하한다.
dwBufferAggressiveness
적응 버퍼링 알고리즘의 버퍼의 즉응성의 정도의 설정. 대부분의 어플리케이션에서는, DVBUFFERAGGRESSIVENESS_DEFAULT 로 설정할 수 있다. 또, DVBUFFERAGGRESSIVENESS_MIN 로부터 DVBUFFERAGGRESSIVENESS_MAX 까지의 임의의 값으로 설정할 수 있다. 일반적으로, 값이 큰 만큼 적응 버퍼링은 상황 변화에의 대응이 빨라진다. 값이 작을 정도(수록), 적응 버퍼링은 상황 변화에의 대응이 늦어진다.
dwNotifyPeriod
DVMSGID_OUTPUTLEVEL 메세지와 DVMSGID_INPUTLEVEL 메세지 (세션이 전이중인 경우)를 받아들이는 빈도를 나타내는 값. 이 값을 0 으로 설정했을 경우, 메세지는 무효가 된다. 메세지간의 간격을 밀리 세컨드 단위로 지정한다. DVNOTIFYPERIOD_MINPERIOD 를 지정 하면, 메세지간에 가능한 최소 시간이 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice8.h 로 선언.


DVCOMPRESSIONINFO

Microsoft® DirectPlay® Voice 의 특정의 압축 타입의 속성을 기술한다.

typedef struct{
    DWORD           dwSize;
    GUID            guidType;
    LPWSTR          lpszName;
    LPWSTR          lpszDescription;
    DWORD           dwFlags;
    DWORD           dwMaxBitsPerSecond;
} DVCOMPRESSIONINFO, *LPDVCOMPRESSIONINFO, *PDVCOMPRESSIONINFO;

멤버

dwSize
이 구조체를 사용하기 전에, 이 구조체의 사이즈 (바이트 단위)로 설정할 필요가 있다.
guidType
DirectPlay Voice 가 이 압축 타입의 식별로 사용하는 GUID.
lpszName
CODEC 를 기술하는 이름에의 포인터.
lpszDescription
CODEC 의 긴 이름에의 포인터.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.
dwMaxBitsPerSecond
CODEC 로 주장되고 있는 1 초 쯤의 최대 비트수.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice8.h 로 선언.


DVSESSIONDESC

Microsoft® DirectPlay® Voice 서버의 필요한 세션 설정 또는 현재의 세션 설정을 기술한다. 음성 세션 호스트는, 이 구조체를 사용해 세션을 설정한다. 또, 세션 호스트와 클라이언트는 이 구조체를 사용해, 현재의 세션에 관한 정보를 취득한다. dwFlags, dwSessionType, 및 guidCT 의 각 멤버는, 호스트가 음성 세션을 시작 할 경우에 마셔 설정할 수 있다. 호스트는 언제라도 버퍼 설정을 변경할 수 있다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwSessionType;
    GUID   guidCT;
    DWORD  dwBufferQuality;
    DWORD  dwBufferAggresiveness;
} DVSESSIONDESC, *LPDVSESSIONDESC, *PDVSESSIONDESC;

멤버

dwSize
이 구조체를 사용하기 전에, 이 구조체의 사이즈 (바이트 단위)로 설정할 필요가 있다.
dwFlags
다음의 플래그의 편성.
DVSESSION_NOHOSTMIGRATION
트랜스폴트의 설정에 관계없이, 음성 호스트는 이행 하지 않는다. 이 플래그를 지정하지 않는 경우, 트랜스폴트의 지원이 있으면, 호스트는 이행 한다.
DVSESSION_SERVERCONTROLTARGET
클라이언트는 음성의 타겟을 제어할 수 없다. 서버 플레이어만이 음성의 타겟을 제어할 수 있다. 서버가 이 플래그를 지정하지 않는 경우, 클라이언트만이 음성의 타겟을 제어할 수 있다. 이 플래그는, 멀티 캐스트 및 믹싱 세션에서만 지정할 수 있다.
dwSessionType
실행하는 DirectPlay Voice 세션의 타입. 클라이언트/서버 세션에서는, DVSESSIONTYPE_PEER 플래그는 이용할 수 없다. 다른 모든 플래그는 모든 세션 타입에 유효하다. 이 멤버에는 다음의 몇개의 값을 지정할 수 있다.
DVSESSIONTYPE_PEER
음성 메세지를 플레이어 사이에 직접 송신한다.
DVSESSIONTYPE_MIXING
음성 세션으로 믹싱 서버를 사용한다. 이 처리 모드에서는, 모든 음성 메세지는 서버에 송신된다. 서버는 믹싱 해, 단일의 믹싱이 끝난 스트림을 각 클라이언트에 전송 한다. 서버의 대역폭과 CPU 의 사용량이 증가하는 대신에, 클라이언트의 대역폭과 CPU 의 사용량은 크게 감소한다.
DVSESSIONTYPE_FOWARDING
음성 메세지는 세션 호스트를 경유해 루팅 된다. 서버의 대역폭을 사용하는 대신에 클라이언트의 대역폭은 절약할 수 있다. 세션 호스트가 고속 접속하고 있는 경우에게만, 이 옵션은 도움이 된다.
guidCT
세션의 압축 타입을 지정하는 GUID.
dwBufferQuality
버퍼의 품질 설정. 이 멤버는, 믹싱 세션 이외의 세션 타입에서는 사용하지 않는다. 믹싱 세션 이외의 모든 세션에서는, 이 멤버를 DVBUFFERQUALITY_DEFAULT 로 설정한다.

DVBUFFERQUALITY_MIN 로부터 DVBUFFERQUALITY_MAX 까지의 값을 사용할 수 있다. 또, 이 멤버는 다음의 값에도 설정할 수 있다.

DVBUFFERQUALITY_DEFAULT
이 값을 지정 하면, 시스템의 디폴트값이 사용된다. 디폴트값은, 레지스트리 엔트리를 사용해 조정할 수 있다. 또, 컨트롤 패널의 [사운드] 와 [멀티미디어] 로부터도 설정할 수 있다.
dwBufferAggresiveness
버퍼의 즉응성의 정도의 설정. 이 멤버는, 믹싱 세션 이외의 세션 타입에서는 사용하지 않는다. 믹싱 세션 이외의 모든 세션에서는, 이 멤버를 DVBUFFERAGGRESIVENESS_DEFAULT 로 설정한다.

DVBUFFERAGGRESIVENESS _MIN 로부터 DVBUFFERAGGRESIVENESS _MAX 까지의 값을 사용할 수 있다. 또, 이 멤버는 다음의 값에도 설정할 수 있다.

DVBUFFERAGGRESIVENESS_DEFAULT
이 값을 지정 하면, 시스템의 디폴트값이 사용된다. 디폴트값은, 레지스트리 엔트리를 사용해 조정할 수 있다. 또, 컨트롤 패널로부터도 설정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice8.h 로 선언.


DVSOUNDDEVICECONFIG

사운드 디바이스 구성에 관한 정보의 설정과 취득에 사용한다. 한 번 접속이 확립 하면, 값은 변경할 수 없다. 접속의 확립 후,IDirectPlayVoiceClient::GetSoundDeviceConfig 를 호출하면, 현재의 사운드 디바이스 설정을 취득할 수 있다.

typedef struct {
    DWORD                dwSize;
    DWORD                dwFlags;
    GUID                 guidPlaybackDevice;
    LPDIRECTSOUND        lpdsPlaybackDevice;
    GUID                 guidCaptureDevice;
    LPDIRECTSOUNDCAPTURE lpdsCaptureDevice;
    HWND                 hwndAppWindow;
    LPDIRECTSOUNDBUFFER  lpdsMainBuffer;
    DWORD                dwMainBufferFlags;
    DWORD                dwMainBufferPriority;
} DVSOUNDDEVICECONFIG, *LPDVSOUNDDEVICECONFIG, *PDVSOUNDDEVICECONFIG;

멤버

dwSize
이 구조체를 사용하기 전에, 이 구조체의 사이즈 (바이트 단위)로 설정할 필요가 있다.
dwFlags
다음의 플래그를 조합해 지정한다.
DVSOUNDCONFIG_AUTOSELECT
이 플래그를 지정 하면, Microsoft® DirectPlay® Voice 는, 지정된 녹음 디바이스의 믹서로 마이크 라인을 자동적으로 선택 (또는 뮤트 해제)하려고 한다.
DVSOUNDCONFIG_HALFDUPLEX
DirectPlay Voice 를 반이중 모드로 초기화한다. 반이중 모드에서는 녹음은 행해지지 않는다. 전이중 모드로 사운드 시스템의 초기화가 실패했을 경우, 시스템에 의해 이 플래그가 설정된다.
DVSOUNDCONFIG_NORMALMODE
DirectPlay Voice 에, Microsoft® DirectSound® 의 보통 모드를 사용해 DirectSound 오브젝트를 초기화하도록(듯이) 지시한다. 이 플래그를 지정하지 않는 경우, DirectSound 오브젝트는 DirectSound 의 우선 모드로 초기화된다. 상세한 것에 대하여는, 「IDirectSound8::SetCooperativeLevel 」의 설명을 참조할것. lpdsPlaybackDevice 멤버에 유효한 DirectSound 오브젝트가 지정되었을 경우, 이 플래그는 무시된다.
DVSOUNDCONFIG_SETCONVERSIONQUALITY
CPU 의 사용량이 증가하는 대신에, 고품질의 오디오를 사용할 수 있다.
DVSOUNDCONFIG_NORECVOLAVAILABLE
지정한 녹음 디바이스로 볼륨을 제어할 수 없는 경우, DirectPlay Voice 에 의해 설정된다. 개발자는 이 플래그를 설정할 수 없다.
DVSOUNDCONFIG_NOFOCUS
음성 어플리케이션은 결코 포커스를 잃지 않는다. 바꾸어 말하면(자), 어플리케이션은 결코 사운드 캡춰 디바이스를 해방하지 않는다. 이 플래그의 사용은 추천 되지 않는다.
DVSOUNDCONFIG_STRICTFOCUS
음성 어플리케이션의 윈도우가 foreground 윈도우가 아니게 되면(자), 음성 어플리케이션은 포커스를 잃는다.

주 어플리케이션에서는, 아무래도 필요한 경우에게만, DVSOUNDCONFIG_NOFOCUS 또는 DVSOUNDCONFIG_STRICTFOCUS 플래그를 설정하는 것. 보통은, 어느 플래그도 설정하지 않는 디폴트의 동작을 사용한다.

guidPlaybackDevice
IDirectPlayVoiceClient::Connect 메소드로 이 구조체를 사용하는 경우, 재생에 사용하는 디바이스의 GUID 를 이 멤버로 지정한다. lpdsPlaybackDevice 멤버를 사용하는 경우에서도, 이 값을 지정할 필요가 있다. 또, DirectSound 가 제공하는 다음의 디폴트 GUID 를 사용할 수도 있다.
DSDEVID_DefaultPlayback
시스템의 디폴트 재생 디바이스.
DSDEVID_DefaultVoicePlayback
디폴트 음성 재생 디바이스.

IDirectPlayVoiceClient::GetSoundDeviceConfig 메소드로 이 구조체를 사용했을 경우, 재생에 사용하는 실제의 디바이스 GUID 가 이 멤버에 저장 된다.

lpdsPlaybackDevice
IDirectPlayVoiceClient::Connect 메소드로 이 구조체를 사용하는 경우, DirectPlay Voice 로 재생에 사용하는 DirectSound 오브젝트를 지정한다. guidPlaybackDevice 로 지정하는 GUID 는, 이 파라미터로 지정한 디바이스의 생성에 사용되는 GUID 에 일치할 필요가 있다. DirectSound 오브젝트의 생성시에 디바이스 지정으로 NULL 를 사용했을 경우, 이 멤버에 DSDEVID_DefaultPlayback 를 지정한다.

IDirectPlayVoiceClient::GetSoundDeviceConfig 메소드로 이 구조체를 사용했을 경우, DirectPlay Voice 로 사용되는 DirectSound 오브젝트에의 포인터가 이 멤버에 저장 된다. 이 포인터는,Connect 의 호출로 지정된 오브젝트에의 포인터, 또는 신규 생성 되어 초기화된 DirectSound 오브젝트에의 포인터이다. 이 DirectSound 오브젝트를 사용하는 경우는, 포인터를 기억해, DirectSound 인터페이스로 AddRef 를 호출해 참조 카운트를 인크리먼트(increment) 할 필요가 있다.

guidCaptureDevice
IDirectPlayVoiceClient::Connect 메소드로 이 구조체를 사용하는 경우, 캡춰에 사용하는 디바이스의 GUID 를 이 멤버로 지정한다. lpdsCaptureDevice 멤버를 사용하는 경우에서도, 이 값을 지정할 필요가 있다. DirectSoundCapture 오브젝트의 생성시에 디바이스 지정으로 NULL 를 사용했을 경우, 이 멤버에 DSDEVID_DefaultCapture 를 지정한다.

IDirectPlayVoiceClient::GetSoundDeviceConfig 메소드로 이 구조체를 사용했을 경우, 캡춰에 사용되는 실제의 디바이스 GUID 가 이 멤버에 저장 된다.

lpdsCaptureDevice
IDirectPlayVoiceClient::Connect 메소드로 이 구조체를 사용하는 경우, DirectPlay Voice 로 캡춰에 사용하는 DirectSound 오브젝트를 이 멤버로 지정한다. guidCaptureDevice 로 지정하는 GUID 는, 이 파라미터로 지정한 디바이스의 생성에 사용되는 GUID 에 일치할 필요가 있다. DirectPlay Voice 로 자동적으로 DirectSoundCapture 오브젝트를 생성 하는 경우는, 이 파라미터에 NULL 를 지정한다.

IDirectPlayVoiceClient::GetSoundDeviceConfig 메소드로 이 구조체를 사용했을 경우, DirectPlay Voice 로 사용되는 DirectSoundCapture 오브젝트에의 포인터가 이 멤버에 저장 된다. 이 포인터는,Connect 의 호출로 지정된 오브젝트에의 포인터, 또는 신규 생성 되어 초기화된 DirectSoundCapture 오브젝트에의 포인터이다. 이 DirectSoundCapture 오브젝트를 사용하는 경우는, 포인터를 기억해,IDirectSoundCapture8 인터페이스로 AddRef 를 호출해 참조 카운트를 인크리먼트(increment) 할 필요가 있다. DirectPlay Voice 오브젝트가 반이중 모드로 동작하고 있는 경우, 이 멤버는 NULL 가 된다.

hwndAppWindow
사운드 재생의 포커스의 결정에 사용되는 윈도우의 핸들을 설정한다. DirectSound 의 포커스의 상세한 것에 대하여는, 「IDirectSound8::SetCooperativeLevel 」를 참조할것. 포커스에 사용하는 윈도우가 없는 경우,GetDesktopWindow 를 사용해 데스크탑 윈도우를 사용한다.
lpdsMainBuffer
IDirectSoundBuffer8 인터페이스에의 포인터. 이 인터페이스를 사용해, DirectPlay Voice 의 메인 버퍼를 생성 한다. NULL, 또는 유저 생성의 DirectSound 버퍼를 지정할 수 있다. 이 멤버를 NULL 로 설정 하면, DirectPlay Voice 는 메인 음성 버퍼로서 사용하는 버퍼를 생성 한다. 여기서 버퍼를 지정했을 경우, DirectPlay Voice 는 이 버퍼를 메인의 음성 버퍼로서 사용한다. 유저 생성의 버퍼에는 다음의 제한이 있다.
  • 버퍼는, 22 Khz, 16 비트, 단청의 포맷이 아니면 안된다.
  • 버퍼의 길이는, 1 초 이상이 아니면 안된다.
  • 버퍼는, DSBCAPS_GETCURRENTPOSITION2 및 DSBCAPS_CTRL3D 플래그를 사용해 생성되어 있지 않으면 안 된다.
  • 버퍼는 프라이머리 버퍼여서는 안 된다.
  • 버퍼는, DirectPlay Voice 소프트웨어에게 건네질 때 재생중에서 만나서는 안 된다.
  • 버퍼는, DirectPlay Voice 소프트웨어에게 건네질 때 락 되고 있어서는 안 된다.
dwMainBufferFlags
메인 버퍼에 대해서 Play 를 호출하면,IDirectSoundBuffer8::Play 메소드의 dwFlags 파라미터에 이 멤버가 직접 건네받는다. 이 필드에는, DSBPLAY_LOOPING 플래그가 자동적으로 추가된다. 상세한 것에 대하여는, 「IDirectSoundBuffer8::Play 」의 설명을 참조할것. 이 구조체의 lpdsMainBufferDesc 멤버가 NULL 인 경우, 이 파라미터는 0 으로 설정할 필요가 있다.
dwMainBufferPriority
메인 버퍼에 대해서 Play 를 호출하면,IDirectSoundBuffer8::Play 메소드의 dwPriority 파라미터에 이 멤버가 직접 건네받는다. 상세한 것에 대하여는, 「IDirectSoundBuffer8::Play 」의 설명을 참조할것. lpdsMainBufferDesc 가 NULL 인 경우, 이 멤버는 0 으로 설정할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : Dvoice8.h 로 선언.


반환값

에러는 부의 값으로 나타내져 그것들을 조합할 수 없다.

다음의 표는, 이후에 가리키는 에러값이 적용되는 인터페이스의 리스트이다.

인터페이스 | 인터페이스
IDirectPlay8Address | IDirectPlay8Peer
IDirectPlay8AddressIP | IDirectPlay8Server
IDirectPlay8Client | IDirectPlayVoiceClient
IDirectPlay8LobbiedApplication | IDirectPlayVoiceServer
IDirectPlay8LobbyClient | IDirectPlayVoiceTest

각 메소드에 의해 돌려주어지는 에러값에 대해서는, 개별의 메소드의 설명을 참조할것.

Microsoft® DirectPlay® 의 샘플이 많게는,HRESULT 값을 DirectPlay 에러의 캐릭터 라인명으로 변환하는 GetDirectPlayErrStr 함수가 포함되어 있다. 개발자는, 진단 트레이스나 에러 리포트용으로 각자의 어플리케이션에 이 코드를 카피할 수 있다.

성공 코드

DPNSUCCESS_PENDING
비동기 처리로, 큐에의 설정이 성공하는 곳(중)까지 처리가 진행되었다.
S_OK
조작은 정상적으로 종료했다.

에러 코드

DPNERR_ABORTED
조작은, 완료전에 삭제되었다.
DPNERR_ADDRESSING
지정된 주소가 무효이다.
DPNERR_ALREADYCONNECTED
오브젝트는 벌써 세션에 접속되고 있다.
DPNERR_ALREADYCLOSING
세션에서의 Close 메소드 호출이 여러 차례 행해졌다.
DPNERR_ALREADYDISCONNECTING
클라이언트는 벌써 세션으로부터 접속 해제하고 있다.
DPNERR_ALREADYINITIALIZED
오브젝트는 이미 초기화되고 있다.
DPNERR_BUFFERTOOSMALL
지정된 버퍼가, 요구된 데이터를 저장 하는데 충분한 크기가 아니다.
DPNERR_CANNOTCANCEL
조작을 취소할 수가 없었다.
DPNERR_CANTCREATEGROUP
새로운 그룹을 생성 할 수 없다.
DPNERR_CANTCREATEPLAYER
새로운 플레이어를 생성 할 수 없다.
DPNERR_CANTLAUNCHAPPLICATION
로비는 지정된 어플리케이션을 기동할 수 없다.
DPNERR_CONNECTING
이 메소드는, 네트워크에 접속중이다.
DPNERR_CONNECTIONLOST
데이터의 송신중에 서비스 프로바이더 접속이 리셋 되었다.
DPNERR_DATATOOLARGE
어플리케이션 데이터가, 서비스 프로바이더의 MTU (Maximum Transmission Unit)에 대해서 너무 크다.
DPNERR_DOESNOTEXIST
요구된 요소는 주소의 일부에서는 없다.
DPNERR_ENUMQUERYTOOLARGE
지정된 쿼리 데이터가 너무 크다.
DPNERR_ENUMRESPONSETOOLARGE
열거 쿼리에의 응답이 너무 크다.
DPNERR_EXCEPTION
요구 처리시에 예외가 발생했다.
DPNERR_GENERIC
미정도리 에러 조건이 발생했다.
DPNERR_GROUPNOTEMPTY
지정된 그룹이 하늘은 아니다.
DPNERR_HOSTREJECTEDCONNECTION
DPN_MSGID_INDICATE_CONNECT 시스템 메세지가, 접속 요구에 대해서 S_OK 이외의 값을 돌려주었다.
DPNERR_HOSTTERMINATEDSESSION
피어 투 피어 세션의 호스트 (호스트의 이행이 가능)가 세션을 종료했다.
DPNERR_INCOMPLETEADDRESS
지정된 주소가 불완전하다.
DPNERR_INVALIDADDRESSFORMAT
주소 포맷이 무효이다.
DPNERR_INVALIDAPPLICATION
어플리케이션으로 지정된 GUID 가 무효이다.
DPNERR_INVALIDCOMMAND
지정된 커멘드가 무효이다.
DPNERR_INVALIDDEVICEADDRESS
로컬 컴퓨터 또는 어댑터의 주소가 무효이다.
DPNERR_INVALIDFLAGS
이 메소드에게 건네진 플래그가 무효였다.
DPNERR_INVALIDGROUP
그룹 ID 가, 이 게임 세션의 유효한 그룹 ID 로서 인식되지 않는다.
DPNERR_INVALIDHANDLE
지정된 핸들은 무효이다.
DPNERR_INVALIDHOSTADDRESS
지정된 리모트 주소가 무효이다.
DPNERR_INVALIDINSTANCE
어플리케이션의 인스턴스의 GUID 가 무효이다.
DPNERR_INVALIDINTERFACE
인터페이스 파라미터가 무효이다. 접속원플레이어가 클라이언트/서버 게임의 클라이언트 또는 피어 투 피어 게임의 피어는 아니었던 경우, 접속 요구에 이 값이 돌려주어진다.
DPNERR_INVALIDOBJECT
DirectPlay 오브젝트 포인터가 무효이다.
DPNERR_INVALIDPARAM
메소드에게 건네진 파라미터의 언젠가 또는 몇개인가가 무효이다.
DPNERR_INVALIDPASSWORD
패스워드가 필요한 세션에 참가하려고 했을 때에, 무효인 패스워드가 지정되었다.
DPNERR_INVALIDPLAYER
플레이어 ID 가 이 게임 세션의 유효한 플레이어 ID 로서 인식되지 않는다.
DPNERR_INVALIDPOINTER
파라미터로서 지정된 포인터가 무효이다.
DPNERR_INVALIDPRIORITY
지정된 우선 순위가, 허가되고 있는 우선 순위의 범위 (0 이상 65535 이하) 외이다.
DPNERR_INVALIDSTRING
파라미터로서 지정된 캐릭터 라인이 무효이다.
DPNERR_INVALIDURL
지정된 캐릭터 라인이 무효인 DirectPlay URL 이다.
DPNERR_INVALIDVERSION
DirectPlay 의 무효인 버젼에 접속하려고 했다.
DPNERR_NOCAPS
DirectPlay 가 사용하려고 하고 있는 통신 링크에서는, 이 기능을 사용할 수 없다.
DPNERR_NOCONNECTION
통신 링크가 확립되지 않았다.
DPNERR_NOHOSTPLAYER
현재, 세션의 호스트로서 기능하는 플레이어가 없다.
DPNERR_NOINTERFACE
인터페이스가 지원되어 있지 않다.
DPNERR_NORESPONSE
지정된 타겟으로부터 응답이 없다.
DPNERR_NOTALLOWED
오브젝트는 읽어내 전용이다. 이 오브젝트에 대해서 이 기능은 사용할 수 없다.
DPNERR_NOTHOST
클라이언트가 호스트 이외의 컴퓨터에 접속하려고 했다. 또, 호스트 이외의 컴퓨터가 어플리케이션의 기술을 설정하려고 했을 경우에, 이 에러값이 돌려주어지는 일이 있다.
DPNERR_OUTOFMEMORY
요구된 조작을 실행하려면 , 메모리가 부족하다.
DPNERR_PENDING
에러는 아니다. 이 반환값은, 비동기 처리로, 큐에의 설정이 성공하는 곳(중)까지 처리가 진행된 것을 나타낸다. SUCCEEDED(DPNERR_PENDING)는 TRUE 를 돌려준다. 이 에러값은, DPNERR_SUCCESS 로 옮겨놓을 수 있고 있다. 새로운 어플리케이션에서는, DPNERR_SUCCESS 를 사용해야 한다. DPNERR_PENDING 는, 하위 호환성을 유지하기 위해서(때문에) 도입되고 있다.
DPNERR_PLAYERLOST
플레이어는, 세션에의 접속을 상실했다.
DPNERR_PLAYERNOTREACHABLE
세션내에서 적어도 다른 한사람의 기존 플레이어가, 참가중의 플레이어에게 접속할 수 없는 상태의 피어 투 피어 세션에, 플레이어가 참가하려고 했다.
DPNERR_SESSIONFULL
세션에 할당할 수 있고 있는 플레이어의 최대수에 이르렀기 때문에, 호스트 또는 서버에의 접속 요구가 실패했다.
DPNERR_TIMEDOUT
마감 시간이기 때문에, 조작을 완료할 수 없었다.
DPNERR_UNINITIALIZED
요구된 오브젝트가 초기화되어 있지 않다.
DPNERR_UNSUPPORTED
함수 또는 기능을, 이 이행이나 이 서비스 프로바이더로 사용할 수 없다.
DPNERR_USERCANCEL
유저는 처리를 취소했다.
DV_OK
요구는 정상적으로 종료했다.
DV_FULLDUPLEX
사운드 카드는 전이중 조작이 가능하다.
DV_HALFDUPLEX
사운드 카드는 반이중 모드로 밖에 동작하지 않는다.
DVERR_BUFFERTOOSMALL
지정된 버퍼가, 요구된 데이터를 저장 하는데 충분한 크기가 아니다.
DVERR_EXCEPTION
요구 처리시에 예외가 발생했다.
DVERR_GENERIC
미정도리 에러 조건이 발생했다.
DVERR_INVALIDFLAGS
이 메소드에게 건네진 플래그가 무효였다.
DVERR_INVALIDOBJECT
DirectPlay 오브젝트 포인터가 무효이다.
DVERR_INVALIDPARAM
메소드에게 건네진 파라미터의 언젠가 또는 몇개인가가 무효이다.
DVERR_INVALIDPLAYER
플레이어 ID 가 이 게임 세션의 유효한 플레이어 ID 로서 인식되지 않는다.
DVERR_INVALIDGROUP
그룹 ID 가, 이 게임 세션의 유효한 그룹 ID 로서 인식되지 않는다.
DVERR_INVALIDHANDLE
지정된 핸들은 무효이다.
DVERR_OUTOFMEMORY
요구된 조작을 실행하려면 , 메모리가 부족하다.
DVERR_PENDING
에러는 아니다. 이 반환값은, 비동기 처리로, 큐에의 설정이 성공하는 곳(중)까지 처리가 진행된 것을 나타낸다.
DVERR_NOTSUPPORTED
조작이 지원되어 있지 않다.
DVERR_NOINTERFACE
지정된 인터페이스가 지원되어 있지 않다. 사용한 DirectPlay 의 버젼이 잘못되어 있을 가능성이 있다.
DVERR_SESSIONLOST
트랜스폴트는 세션에의 접속을 상실했다.
DVERR_NOVOICESESSION
지정된 세션은 음성 세션은 아니다.
DVERR_CONNECTIONLOST
음성 세션에의 접속이 상실했다.
DVERR_NOTINITIALIZED
이 메소드를 호출하기 전에,IDirectPlayVoiceClient::Initialize 메소드 또는 IDirectPlayVoiceServer::Initialize 메소드를 호출할 필요가 있다.
DVERR_CONNECTED
DirectPlayVoice 오브젝트가 접속되고 있다.
DVERR_NOTCONNECTED
DirectPlayVoice 오브젝트가 접속되어 있지 않다.
DVERR_CONNECTABORTING
접속 해제중.
DVERR_NOTALLOWED
오브젝트에는, 이 조작을 실행하는 권한이 없다.
DVERR_INVALIDTARGET
지정된 타겟은, 이 음성 세션의 유효한 플레이어 ID 또는 그룹 ID 는 아니다.
DVERR_TRANSPORTNOTHOST
오브젝트는 음성 세션의 호스트는 아니다.
DVERR_COMPRESSIONNOTSUPPORTED
지정된 압축 타입이 로컬 컴퓨터로 지원되어 있지 않다.
DVERR_ALREADYPENDING
이 타입의 비동기 호출이 이미 보류 상태가 되어 있다.
DVERR_ALREADYINITIALIZED
오브젝트는 이미 초기화되고 있다.
DVERR_SOUNDINITFAILURE
사운드 카드의 초기화에 실패했다.
DVERR_TIMEOUT
지정된 시간내에 조작을 실행할 수 없었다.
DVERR_CONNECTABORTED
접속은, 완료전에 삭제되었다.
DVERR_NO3DSOUND
로컬 컴퓨터에서는 3D 사운드를 지원 하고 있지 않다.
DVERR_ALREADYBUFFERED
지정된 ID 에는 이미 유저 버퍼가 있다.
DVERR_NOTBUFFERED
지정된 ID 에는 유저 버퍼가 없다.
DVERR_HOSTING
오브젝트는 세션의 호스트이다.
DVERR_NOTHOSTING
오브젝트는 세션의 호스트는 아니다.
DVERR_INVALIDDEVICE
지정된 디바이스가 무효이다.
DVERR_RECORDSYSTEMERROR
녹음 시스템에 에러가 발생했다.
DVERR_PLAYBACKSYSTEMERROR
재생 시스템에 에러가 발생했다.
DVERR_SENDERROR
데이터의 송신중에 에러가 발생했다.
DVERR_USERCANCEL
유저는 처리를 취소했다.
DVERR_UNKNOWN
불명한 에러가 발생했다.
DVERR_RUNSETUP
지정된 오디오 구성은 테스트되어 있지 않다. IDirectPlayVoiceTest::CheckAudioSetup 메소드를 호출한다.
DVERR_INCOMPATIBLEVERSION
클라이언트는, 호스트와 호환성이 없는 음성 세션에 접속했다.
DVERR_INITIALIZED
오브젝트가 벌써 초기화되고 있기 (위해)때문에,Initialize 메소드가 실패했다.
DVERR_INVALIDPOINTER
지정된 포인터가 무효이다.
DVERR_NOTRANSPORT
지정된 오브젝트는 유효한 트랜스폴트는 아니다.
DVERR_NOCALLBACK
콜백 함수가 지정되어 있지 않기 때문에, 이 조작은 실행할 수 없다.
DVERR_TRANSPORTNOTINIT
지정된 트랜스폴트는 아직 초기화되어 있지 않다.
DVERR_TRANSPORTNOSESSION
지정된 트랜스폴트는 유효하지만, 접속되지 않은가 호스트 하고 있지 않다.
DVERR_TRANSPORTNOPLAYER
지정된 트랜스폴트는 접속되어 호스트 하고 있지만, 로컬 플레이어가 존재하지 않는다.


DirectShow

Microsoft® DirectShow® 어플리케이션 프로그래밍 인터페이스 (API)는, Microsoft® Windows® 플랫폼전용의 미디어 스트리밍 아키텍쳐이다. DirectShow 를 사용 하면, 어플리케이션으로 고품질인 비디오나 오디오의 재생과 캡춰를 실시할 수가 있다. DirectShow 의 문서는, 이하의 주제로 나누어져 있다.

  • DirectShow 의 개요
  • 퍼스트 스텝 가이드
  • DirectShow 에 대해
  • DirectShow 의 사용법
  • 디코더의 개발
  • DirectShow 튜토리얼
  • DirectShow 레퍼런스
  • DirectShow 샘플
  • DirectX Media Object
  • 미디어 파라미터
  • 부록
  • 용어집

주 : 이 아이콘 외부 링크 는, 링크처가 microsoft.com 사이트 이외의 URL 인 것을 나타낸다. 이러한 외부 링크의 대부분은, Microsoft 가 관리하고 있지 않는 사이트를 나타내고 있다. 이러한 사이트의 상세한 것에 대하여는, Microsoft 의 official statement 를 참조할것.


DirectShow 의 개요

Microsoft® DirectShow® 는, Microsoft® Windows® 플랫폼에 있어서의 미디어 스트리밍의 아키텍쳐이다. DirectShow 는, 멀티미디어 스트림의 고품질인 캡춰와 재생을 실현한다. 지원 하는 포맷은 광범위하게 걸쳐, ASF (Advanced Streaming Format), MPWG (Motion Picture Experts Group), AVI (Audio-Video Interleaved), MP3 (MPEG Audio Layer-3), 및 WAV 파일을 포함한다. WDM (Windows Driver Model) 디바이스 및 종래의 Video for Windows 디바이스를 사용한 캡춰를 지원 한다. DirectShow 는, 다른 DirectX 테크놀러지와 통합되고 있다. DirectShow 는, 비디오 및 오디오 가속화 하드웨어가 사용 가능한 경우에는 하드웨어를 자동적으로 검출해 사용하지만, 가속화 하드웨어가 없는 시스템도 지원 하고 있다.

DirectShow 에서는, 미디어 재생, 포맷 변환, 및 캡춰의 작업을 간단하게 실시할 수 있다. 동시에, 커스텀 솔루션을 필요로 하는 어플리케이션에 대해, 기초가 되는 스트림 제어 아키텍쳐에의 액세스를 제공한다. 새로운 포맷 또는 커스텀 이펙트를 지원 하는 독자적인 DirectShow 컴퍼넌트를 생성 할 수도 있다.

DirectShow 를 사용해 생성 할 수 있는 어플리케이션의 종류의 예로서 DVD 플레이어, 비디오 편집 어플리케이션, AVI 로부터 ASF 에의 컨버터, MP3 플레이어, 디지털 비디오 캡춰 어플리케이션이 있다.

DirectShow 는 Component Object Model (COM)에 근거하고 있다. DirectShow 어플리케이션을 생성 하려면 , COM 클라이언트 프로그래밍을 이해하고 있을 필요가 있다. 대부분의 어플리케이션에서는, 독자적인 COM 오브젝트를 이행 할 필요는 없다. DirectShow 에는 유저가 필요로 하는 컴퍼넌트가 준비되어 있다. 다만, 독자적인 컴퍼넌트를 생성 해 DirectShow 를 확장하는 경우는, 컴퍼넌트를 COM 오브젝트로서 이행 할 필요가 있다.

여기에서는 다음의 내용에 대해 설명한다.

  • 도로지도
  • DirectShow 의 신기능
  • DirectShow 로 지원 되는 포맷
  • DirectShow FAQ


도로지도

여기에서는, Microsoft® DirectShow® 의 문서 구성에 대해 설명한다.

  • 지금까지 DirectShow 를 사용하고 있었을 경우는, 「DirectShow 의 신기능」을 참조할것. Microsoft® DirectX® 8 으로 도입된 신기능이 설명되고 있다.
  • 처음으로 DirectShow 를 사용하는 경우는, 「퍼스트 스텝 가이드」로부터 시작하는 것. 다음에, 「DirectShow 의 사용법」으로, 생성 하는 어플리케이션의 종류 (재생, 캡춰, DVD 등)에 응한 개소를 읽는 것. DirectShow 의 아키텍쳐의 상세한 것에 대하여는, 「DirectShow 에 대하며」를 읽는 것.
  • 비디오 편집 어플리케이션에 관심이 있는 경우는, 최초로 「DirectShow 편집 서비스」의 개요를 읽어, 다음에 문서외의 부분을 읽을 수 있다.
  • 지금까지는, 커스텀 데이터 변환을 이행 하기 위해서는 DirectShow 필터를 생성 할 필요가 있었다. 현재는, DirectX Media Object 를 생성 하는 것에 의해, 같은 작업을 간단한 방법으로 실행할 수 있다. 상세한 것에 대하여는, 「DirectX Media Object 」를 참조할것. DirectShow 필터를 생성 할 수도 있다. 상세한 것에 대하여는,DirectShow 필터의 개발」을 참조할것.

DirectShow 에 관한 정보는, 다음의 항목으로 구성되어 있다.

퍼스트 스텝 가이드
DirectShow 의 어플리케이션 개발의 개요. 기본적인 개념을 설명해, DirectShow 프로그래밍을 시작 할 수 있도록(듯이), 간단한 일련의 어플리케이션을 나타낸다. 처음으로 DirectShow 를 사용하는 경우는, 이 항목을 읽는 것.
DirectShow 에 대해
DirectShow 의 아키텍쳐에 관한 대범한 배경 정보를 나타내는 것과 동시에, 그래프의 구축 등, 어플리케이션 개발에 관한 주제가 있다.
DirectShow 의 사용법
DirectShow 어플리케이션을 생성 하기 위해서 필요한 정보를 나타낸다. 이 주제의 내용은, 비디오 캡춰, DVD 재생, 디지털 비디오, 비디오 편집 등, 특정의 어플리케이션 영역으로 나누어져 있다.
디코더의 개발
소프트웨어 디코더를 생성 하는 개발자전용의 정보가 포함되어 있다.
DirectShow 튜토리얼
DirectShow 어플리케이션 프로그래밍에 관한 스텝바이스텝의 튜토리얼. DirectShow 를 생성 할 경우에 알아 둘 필요가 있는 디바이스 열거등이 많은 기본적인 작업에 대해 설명한다.
DirectShow 레퍼런스
DirectShow 어플리케이션 프로그래밍 인터페이스 (API)의 완전한 레퍼런스. DirectShow 로 제공되고 있는 필터에 대해서도 설명한다.
DirectShow 샘플
SDK 에 포함되어 있는 샘플의 어플리케이션과 필터에 대해 설명한다.
DirectX Media Object
DirectX Media Object (DMO)는, 데이터 스트리밍 컴퍼넌트를 생성 하는 새로운 방법이다. DirectShow 필터와 같게, DMO 는 입력 데이터를 받아, 그것을 사용해 출력 데이터를 생성한다. 다만, DMO 는 DirectShow 필터보다 간단하게 생성, 테스트, 사용할 수 있다.
미디어 파라미터
미디어 파라미터는, 오브젝트의 프로퍼티에 대한 실행시의 변경을 지원 하는 새로운 API 세트이다. 미디어 파라미터를 사용 하면, 급속히 변화해, 높은 퍼포먼스와 반복성의 양쪽 모두가 요구되는 프로퍼티를 정확하게 제어할 수 있다.
부록
디버그, C 를 사용한 DirectShow 어플리케이션의 생성, 나라/지역 코드, 폐지된 기능의 일람 등, 그 외의 기술 정보가 포함된다.
용어집
DirectShow 로 사용하는 용어와 개념을 정의하고 있다.


DirectShow 의 신기능

여기에서는, Microsoft® DirectX® 8.0 에서의 Microsoft® DirectShow® 의 신기능에 대해 설명한다.

  • Windows Media 포맷의 지원
  • DirectShow 편집 서비스
  • 새로운 DVD 지원
  • 새로운 MPEG-2 트랜스폴트와 프로그램 스트림 지원
  • Microsoft TV 테크놀러지 (Broadcast Driver Architecture)
  • DirectX 비디오 가속화
  • 새로운 필터
  • 필터 그래프의 신기능
  • 빌드 환경의 변경점
  • GraphEdit 의 신기능
  • DirectX Media Object
  • 미디어 파라미터

Windows Media 포맷의 지원

2 개(살)의 새로운 필터에 의해, DirectShow 어플리케이션으로 Windows Media™ 포맷의 파일을 읽고 쓰기할 수 있다. ASF 리더 필터는, Windows Media 포맷 파일을 읽어내, 해석한다. ASF 라이터 필터는, Windows Media 포맷 파일에 기입한다. 또, 필요한 멀티플렉스화와 압축도 실시한다. DirectShow 와 Windows Media Software Development Kit 는, Windows Media 포맷 스트림의 생성과 재생을 실시하는 어플리케이션을 생성하기 위한 보충 솔루션을 제공한다. 상세한 것에 대하여는, 「Windows Media 어플리케이션」을 참조할것.

DirectShow 편집 서비스

DirectShow 편집 서비스는 비디오 편집과 순서화 된 비디오 재생을 지원 하는 API 이다. 예를 들어,2-3 의 메소드를 호출하는 것만으로, 오디오와 비디오 클립을 함께 순서화하거나 이펙트를 추가하거나 그 결과를 재생하거나 할 수 있다. 혹은, 완전한 비디오 편집 시스템을 생성 하는 일도 가능하다. DEC 는 DirectShow 의 코어 아키텍쳐 위에 구축되고 있다. DES 는, 논리니아비데오 편집 전용에 설계된 인터페이스세트를 제공한다.

DES 는 컷 리스트에 옮겨져서 , 컷 리스트는 이미 지원되어 있지 않다.

새로운 DVD 지원

2 개(살)의 새로운 인터페이스인 IDVDControl2 와 IDVDInfo2 는, DVD 네비게이터의 기능을 큰폭으로 확장한 것이다. 새로운 MSWebDVD ActiveX® 컨트롤을 사용 하면, 스크립트 베이스의 어플리케이션으로 이 기능을 사용할 수 있게 된다. 새로운 DVD 기능의 일부로서 다음의 기능이 있다.

  • Karaoke 멀티 채널 오디오 지원
  • S/PDIF 출력에 대한 AC-3 지원
  • IBasicAudio 인터페이스에 의한 오디오 음량 조절
  • 스탭핑(Stepping)조작과 프레임 단위의 시크 조작
  • DVD 텍스트 정보 캐릭터 라인에의 간단한 액세스
  • 페어 렌탈 락의 개선된 지원

상세한 것에 대하여는, 「DVD 어플리케이션」을 참조할것.

새로운 MPEG-2 트랜스폴트와 프로그램 스트림 지원

새로운 필터,MPEG-2 디멀티플렉서 는 MPEG-2 트랜스폴트 스트림과 프로그램 스트림의 지원을 푸쉬 모드 (라이브 소스로부터 데이터를 받는다)로 제공한다. 상세한 것에 대하여는, 「MPEG-2 디멀티플렉서」 및 「디지털 TV 어플리케이션을 쓴다」를 참조할것.

Microsoft® TV 테크놀러지 (Broadcast Driver Architecture)

Microsoft® TV 테크놀러지에는 새로운 Broadcast Driver Architecture (BDA)와 Microsoft 튜닝 모델의 지원이 포함된다. Broadcast Driver Architecture 는 디지털 TV 나 아날로그 TV 를 수신하는 여러가지 컴퍼넌트 위상기하학을 지원 하는 체제를 정의한다. 거기에는 DVB 나 ATSC 를 포함한 주된 디지털 TV 에 관한, 네트워크 구성의 소프트웨어 컴퍼넌트나, 데마르치프레키싱, 테이블 퍼스, IP 데이터 출력이 포함된다. 튜닝 모델은 일련의 오브젝트이며, 거기에 따라 어플리케이션은 심플해 공통의 방법으로 복수의 네트워크 타입에 용이하게 츄아크세스 할 수 있다. 상세한 것에 대하여는, 「디지털 TV 어플리케이션을 쓴다」를 참조할것.

DirectX 비디오 가속화

디코더 개발자에게 : DirectX 비디오 가속화는 어플리케이션 프로그래밍 인터페이스 (API)이며, DVD 서브 픽쳐와 같은 알파 블렌딩의 지원에 의해, 디지털 비디오 디코딩 처리를 하드웨어 가속화 하는 디바이스 드라이버 인터페이스 (DDI)에 대응하고 있다. 그것은 MPEG-2 "메인 프로파일" 비디오 (공식으로는 ITU-T H. 262 | ISO/IEC 13818-2)의 지원에 초점을 맞힌 인터페이스 정의를 제공하지만, 다른 키가 되는 비디오 CODEC (즉 ITU-T Recommendations H. 263 으로 H. 261, 그리고 MPEG-1 와 MPEG-4)의 지원도 실시한다. 상세한 것에 대하여는, 「DirectX 비디오 가속화」를 참조할것.

새로운 필터

DirectShow 에는 몇개의 새로운 필터가 있다.

  • ASF 라이터 : Windows Media 포맷 파일을 생성 한다.
  • ASF 리더 : Windows Media 포맷 파일을 읽어내, 해석한다.
  • MJPEG 데콘프렛사 : 동영상 JPEG 의 비디오 스트림을 미압축의 비디오에 디코드한다.
  • MJPEG 압력 : 동영상 JPEG 압축을 사용해 미압축의 비디오 스트림을 압축한다.
  • MPEG-2 디멀티플렉서 : 라이브 소스로부터의 MPEG-2 트랜스폴트 스트림과 프로그램 스트림을 데마르치프레크스 한다.
  • Null 렌더러 : 샘플 데이터를 표시 또는 렌더링 하지 않고 샘플을 파기한다. 어플리케이션에서는, 이 필터를 사용해 스트림으로부터 데이터를 파기할 수 있다.
  • 샘플 grabber : 필터 그래프내를 이동하는 미디어 샘플을 취득한다. 어플리케이션에서는, 이 필터를 사용해, 포스터 프레임 또는 그 외의 미디어 데이터를 취득할 수 있다.

필터 그래프의 신기능

필터 그래프 매니저는 복수의 새로운 기능을 지원 하고 있다.

  • 동적인 그래프의 구축. 필터 그래프의 실행중에 그래프로 변경을 더할 수가 있게 되었다. 지금까지는, 어플리케이션으로 필터를 추가 또는 삭제하려면 그래프를 정지하지 않으면 안되어, 데이터의 흐름이 중단되고 있었다. 상세한 것에 대하여는, 「동적 그래프 생성」을 참조할것.
  • 라이브 소스의 동기화. DirectShow 로 라이브 소스의 동기화가 지원 되게 되었다. 예를 들어, 라이브 오디오 스트림을 라이브 비디오 스트림과 동기화할 수 있다. 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.
  • 스탭핑(Stepping). 필터 그래프 매니저는 새로운 IVideoFrameStep 인터페이스를 공개하는, 이것을 사용하면(자) 어플리케이션은 비디오 파일로 1 번에 1 프레임 스텝 할 수 있다.

빌드 환경의 변경점

  • 종래의 헤더 파일 Streams.h 는, DShow.h 라고 하는 새로운 헤더 파일로 옮겨졌다.
  • 필터 base class는 SDK 루트 디렉토리아래의 \Samples\BaseClasses 디렉토리에 저장 되고 있다. 필터 base class를 사용하려면 , base class 라이브러리를 빌드 해, 프로젝트에 링크할 필요가 있다. 상세한 것에 대하여는, 「DirectShow base class의 사용법」을 참조할것.

GraphEdit 의 신기능

GraphEdit 에는, 테스트 및 디버그 툴로서의 용도를 확장하는 몇개의 새로운 기능이 짜넣어지고 있다.

  • "Graph Spy": GraphEdit 는 외부 프로세스에 의해 생성 된 필터 그래프를 로드할 수 있다. 이 기능을 사용 하면, 어플리케이션 정원않고일까 코드를 추가하는 것만으로, 어플리케이션으로 빌드 하는 필터 그래프를 정확하게 알 수 있다. 이 기능의 상세한 것에 대하여는, 「외부 프로세스로부터의 그래프의 로드」를 참조할것.
  • 필터 정보 : [Graph] 메뉴의 [Insert Filters] 를 클릭 하면 표시되는 필터의 일람에, 이점, 핀의 수, 각 핀에 대해서 등록되어 있는 미디어 타입 등, 각 필터의 등록 정보가 나타나게 되었다. 이 정보는, 트리 표시로 각 필터의 옆에 있는 플러스 (+) 기호를 클릭 하면 표시된다.

GraphEdit 의 상세한 것에 대하여는, 「GraphEdit 에 의한 그래프 구축의 시뮬레이션」을 참조할것.

DirectX Media Object

DirectX Media Object (DMO)는, 데이터 스트리밍 컴퍼넌트를 생성 하는 새로운 방법이다. DirectShow 필터와 같게, DMO 는 입력 데이터를 받아, 그것을 사용해 출력 데이터를 생성한다. 다만, DMO 의 어플리케이션 프로그래밍 인터페이스 (API)는, DirectShow 의 API 보다 매우 간단하다. 그 때문에, DMO 는 DirectShow 필터보다 간단하게 생성, 테스트, 및 사용할 수 있다.

DMO 는 DirectShow 와 완전한 호환성이 있다. DMO 는, DirectShow 에 제공되고 있는 그래프 동기화, 인텔리전트 접속, 데이터 플로우의 자동 처리, thread 관리등의 서비스가 필요한 경우에, 필터와 같이 사용할 수 있다. 다만, DMO 는 필터 그래프를 필요로 하지 않기 때문에, 어플리케이션에서는 DirectShow 를 사용하지 않고 DMO 를 사용할 수 있다.

상세한 것에 대하여는, 「DirectX Media Object 」를 참조할것.

미디어 파라미터

미디어 파라미터는, 오브젝트의 프로퍼티에 대한 실행시의 변경을 지원 하는 새로운 API 세트이다. 미디어 파라미터를 사용 하면, 급속히 변화해, 높은 퍼포먼스와 반복성의 양쪽 모두가 요구되는 프로퍼티를 정확하게 제어할 수 있다. 미디어 파라미터를 사용 하면, 프로퍼티에 의해 정현파나 역직사각형 곡선등이 엄밀한 커브를 리얼타임에 보충할 수 있다.

데이터 변환 오브젝트는, 미디어 파라미터를 사용해, 실행시의 동작을 제어하는 표준 인터페이스를 지원 할 수 있다. 미디어 파라미터를 DMO 와 조합해 사용 하면, 오디오 이펙트의 생성으로 편리하다. 예를 들어, 메아리 이펙트에서는, 드라이 (미처리의) 신호에 대한 웨트 (처리필 보고) 신호의 비율이 순조로운 커브를 보충하도록(듯이) 할 수가 있다. 이러한 동작은, 오디오 엔지니어링에 있어 레코딩에 부자연스러운 효과가 도입되는 것을 막기 위해서(때문에) 중요하다.

상세한 것에 대하여는, 「미디어 파라미터」를 참조할것.


DirectShow 로 지원 되는 포맷

DirectShow® 는 오픈 아키텍쳐이다. 즉, 해석 및 디코드를 실시하는 필터가 있는 한, 어떠한 포맷에서도 지원 할 수 있다. Microsoft 가 제공하는 필터는, DirectShow 를 통해서 재배포되는 것이어도, Windows operating system의 컴퍼넌트로서 제공되는 것이어도, 이하의 파일 포맷과 압축 포맷을 디폴트로 지원 한다.

주 asterisk (*)는, DirectShow 어플리케이션도 Windows Media Format SDK 를 사용해 이 포맷을 지원 해야 하는 것을 나타낸다. 상세한 것에 대하여는, 「Windows Media and DirectShow: Choices for Windows-based Media Applications 」를 참조할것.

파일 포맷

  • Windows Media™ Audio (WMA)*
  • Windows Media™ Video (WMV)*
  • ASF (Advanced Streaming Format)*
  • Motion Picture Experts Group (MPEG)
  • Audio-Video Interleaved (AVI)
  • QuickTime (version 2 이전)
  • WAV
  • AIFF
  • AU
  • SND
  • MIDI

압축 포맷

  • Microsoft Windows Media Video CODEC version 7.0*
  • ISO MPEG-4 video version 1.0*
  • Microsoft MPEG-4 version 3*
  • Sipro Labs ACELP*
  • Windows Media Audio*
  • MPEG Audio Layer-3 (MP3) (압축 해제만)
  • Digital Video (DV)
  • MPEG-1
  • MJPEG
  • Indeo
  • Voxware*
  • Cinepak

Microsoft 에서는, MPEG-2 디코더를 제공하고 있지 않다. 몇개의 DirectShow 호환 하드웨어와 소프트와 웨어의 MPEG-2 디코더가, 서드 파티로부터 이용 가능하다.

DirectShow 어플리케이션으로 재배포하기 위해서, 서드 파티의 CODEC 가 이용 가능한가 어떤가에 대해서는, CODEC 의 제조원에 문의하는 것.


DirectShow FAQ

여기에는, Microsoft® DirectShow® 에 관한 자주 있는 질문의 대답이 모아지고 있다. 내용은 다음과 같다.

  • 일반적인 질문
  • 프로그래밍에 관한 질문

일반적인 질문

Q: DirectShow 가 지원 하고 있는 operating system는?

A: DirectShow 는, Microsoft® Windows® 9x, Microsoft® Windows® 2000, 및 Microsoft® Windows® Me 를 지원 하고 있다.

Q: DirectShow 프로그램 하는데 어떠한 COM 지식이 필요한가?

A: 어플리케이션 개발자에게 있어 COM 오브젝트로 처리하기 위한 기본적인 이해 (인스턴스화, 공개하는 인터페이스에의 액세스 방법, 그 인터페이스의 참조 카운트의 올바른 관리)는 필요하다. 필터 개발자에게는 좀 더 COM 의 지식이 필요한 경우가 있다. 상세한 것에 대하여는, 이 헬프 파일의 「DirectX 8.0 의 소개」에 있는 「C 또는 C++ 에 의한 DirectX 프로그래밍」을 참조할것.

Q: 어떠한 포맷을 DirectShow 는 지원 하는지?

A: 「DirectShow 로 지원 되는 포맷」을 참조할것.

Q: DirectShow 하드웨어 호환성 리스트 (HCL)는 존재하는지?

A: 아니오. DirectShow 는 사용 가능한 경우는 Microsoft® DirectDraw® 및 Microsoft® DirectSound® 하드웨어 능력을 사용한다. 전용 하드웨어를 사용할 수 없는 경우, DirectShow 는 GDI 를 사용해 비디오를 드로잉(Drawing) 해,waveOut* 멀티미디어 API 를 사용해 오디오를 재생한다.

Q: DirectShow 어플리케이션을 쓰려면 어떠한 언어를 사용할 수 있는지?

A: DirectShow 는 주로 C++ 개발용으로 설계되고 있다. (C 를 사용하는 일도 가능) Microsoft® Visual Basic® 로 DirectShow API 의 것인지든지의 서브 세트에 액세스 할 수 있지만, Visual Basic 의 지원은 완전하지 않다. DirectShow 는 스크립트 베이스의 DVD 어플리케이션을 지원 하고 있는, 이것은 Microsoft® JScript® 혹은 Visual Basic Scripting Edition 를 사용한다. DirectShow 어플리케이션을 Borland Delphi 를 사용하고 쓰는 일도 가능하지만, SDK 문서는 거기에 대해 설명하고 있지 않다.

상세한 것에 대하여는, 이하의 주제를 참조할것.

  • C 에 의한 필터 그래프의 제어
  • Visual Basic 에서의 DirectShow 의 사용
  • 스크립트 베이스의 DVD 어플리케이션의 기술

Q: DirectShow 에서의 개발에 필요한 컴파일러는?

A: 컴파일러의 환경을 올바르게 설정하면, Component Object Model (COM) 오브젝트의 생성이 가능한 임의의 컴파일러를 사용할 수 있다. Microsoft® Visual C++® 이외의 컴파일러를 사용하는 경우는, 컴파일러간의 상위이기 때문에 base class 라이브러리의 재빌드가 필요한 일이 있다.

Q: DirectShow 는 Microsoft® Windows Media™ 와 어떻게 관련하고 있는지?

A: 「Windows Media 어플리케이션」을 참조할것.

Q: DirectShow 는 Microsoft® DirectX® 외의 컴퍼넌트와 어떻게 관련하고 있는지?

A: 내부적으로는, 하드웨어가 지원 하면 와, DirectShow 는 DirectSound 와 DirectDraw 를 사용한다. (비디오 렌더러는 DirectDraw 7 의 서페이스를 사용한다. 새로운 Microsoft® Direct3D® API 는 사용하지 않는다. ) DirectShow 어플리케이션을 쓰기 위해서(때문에) 다른 DirectX API 를 사용할 필요는 없는, 그러나 그것들을 조합하는 것은 가능하다. 예를 들어, 「텍스쳐 3D 샘플」을 참조할것.

DirectShow 의 전의 버젼은 6.0 이었다. 그것은 원래 DirectX Media SDK 와 함께 출시되었다. DirectX Media SDK 가 없어졌으므로, DirectShow 는 DirectX SDK 로 옮긴, 그리고 그 때문에 DirectShow 의 버젼수는 6.0 에서 8.0 에 점프 했다.

Q: DirectShow 는 Microsoft® ActiveMovie® 와 어떻게 관련하고 있는지?

A: ActiveMovie 는 DirectShow 의 원래의 이름이었다. ActiveMovie 라는 말은 이제 사용되지 않았다.

Q: DirectShow 는 멀티미디어 어플리케이션으로 한정되고 있는지?

A: DirectShow 에 포함되어 있는 디폴트 컴퍼넌트는 멀티미디어용으로 설계되고 있다. 그러나 DirectShow 아키텍쳐는 다른 종류의 데이터 스트리밍 솔루션에도 유효하다.

Q: GraphEdit 유틸리티의 소스는 공개되고 있을까? GraphEdit 는 재배포할 수 있을까?

A: 소스는 공개되어 있지 않다. Graphedt.exe 는 재배포할 수 없다.

Q: DMO 는 DirectShow 필터에 두어 바뀌는지?

A: Microsoft® DirectX® 미디어 오브젝트 (DMO)는 DirectShow 어플리케이션내에서 사용 가능하다. 엔코더, 디코더, 이펙트에 대해서는, DirectShow 필터 대신에 DMO 를 쓰는 것을 권한다. 그 이외의 목적에서는, DirectShow 필터가 보다 적절할지도 모른다. 상세한 것에 대하여는, 「DirectX Media Object 」를 참조할것.

Q: 보다 상세한 정보는 어디서 취득할 수 있는지?

  • World Wide Web:MSDN DirectX Developer Center
  • 메일링리스트 : http://discuss.microsoft.com/archives/DIRECTXAV.html . 이하는 그 특징의 일부이다.

    이 메일링리스트의 기본적인 기능은 Microsoft 의 스트리밍 테크놀러지 (DirectShoud, DirectMusic, DirectShow)를 사용하고 있는 개발자나 컨텐츠 크리에이터들이 정보나 아이디어를 교환할 수 있는 것에 있다. 이 메일링리스트는 초심자로부터 상급 개발자까지의 모든 레벨의 DirectX 전문 지식을 제공한다.

    복수의 Microsoft DirectX 개발 팀이 메일링리스트의 토픽을 읽어, 가능한 코멘트를 쓴다고 기대되고 있지만, DirectXAV 는 Microsoft 지원 포럼에 바뀌기 위한 것은 아니고, Microsoft 의 인간이 직접 질문에 답하는 것이 보증되고 있는 것은 아니다. 많은 경우, 가장 뛰어난 원조는 DirectXAV 커뮤니티의 다른 멤버인, 그들은 과거에 자기 자신으로 같은 문제에 직면해 오고 있기 때문이다.

    이 메일링리스트에 포함되어야 할 트픽스 : DirectMusic Producer 를 사용한 작곡 테크닉, 오디오, 음악, 스토밍 비디오 프로그래밍 테크닉, 사운드 디자인 테크닉, 관계하는 API 에 대한 일반적인 문제나 정보, 코드의 단편, 제안, 힌트와 Tips, 디바이스 드라이버 품질, 장래 feature의 요구, API 를 사용한 실제의 경험, 등.

    DirectX DEV 를 구독하려면 , 메세지 본문에 subscribe directxdev 라고 써 LISTSERV@discuss.microsoft.com 에 메일을 보내는 것. DirectX A/V 를 구독하려면 , 메세지 본문에 subscribe directxav 라고 써 LISTSERV@discuss.microsoft.com 에 메일을 보내는 것.

  • UseNet: microsoft.public.multimedia.directx.dshow.programming

Q: 어플리케이션 / 필터를 개발하는데 있어서 곤란한 문제에 직면하고 있다. 개발 지원은 어디서 받게 되는지?

A: 「마이크로 소프트 지원 기술 정보」에 연락하는 것.

Q: DirectShow 를 설명하는 좋은 책은 있을까?

A: 현재, DirectShow 전용의 책은 없는, 다음과 같은 기존의 DirectX 의 책 중(안)에서 DirectShow 는 조금 설명되고 있다.

  • Sams Teach Yourself DirectX in 24 Hours by Robert Dunlop, Dale Shepherd, and Mark Martin (Sams)
  • DirectX, RDX, RSX, and MMX Technology by Rohan Coelho and Maher Hawash (Addison Wesley)

DirectShow 는 이러한 책으로 조금 접할 수 있고 있지만, 가장 뛰어난 정보 소스는 DirectX SDK 로 제공되는 DirectShow 문서와 샘플 코드이다.

Q: 피드백과 버그 리포트를 하려면 , 어떻게 Microsoft 에 컨택트 하면 좋은 것인지?

A: 일반적인 DirectX 의 문제에 대한 주소는 directx@microsoft.com 이다. 버그 리포트의 발송지는 dxbugs@microsoft.com 이다.

Q: Microsoft 에 의한 DirectShow 개선방법의 아이디어를 가지고 있다.

A: Microsoft 는 제안, 질문, 코멘트를 환영합니다. 당신의 생각을 가르쳐 주세요. 무엇이 우리가 부족한지? 어느 분야를 가장 개선해야 한다고 생각하는지? 어떠한 튜토리얼과 샘플이 필요라고 생각하는지? 당신의 제안이 장래의 작업의 우선 순위부에 도움이 되겠지요. 새로운 DirectShow 문서에 관련하는 질문이나 제안이 있으면, 메세지를 askdshow@microsoft.com 에 보내 주세요.

Q: Windows Media Player 로 AVI 파일 포맷을 재생하고 있다. 오디오는 들리지만, 그 대신 비디오를 볼 수가 없는, 검은 화면만이 보인다. 무엇이 나쁜 것인지?

A: 아마 그 파일은 당신의 시스템으로 지원되어 있지 않은 CODEC 로 encode 되고 있다. AVI 파일 포맷은 공통이지만, AVI 파일은 많은 다른 CODEC (coder/decoder)로 생성 할 수 있다. AVI 파일을 지원되어 있지 않은 CODEC 를 사용해 재생 하면, 오디오 컴퍼넌트는 들릴지도 모르지만, 비디오는 검은 스크린이 표시되는지, 스크린 컨텐츠를 변경할 수 없는 채가 된다.

주 Windows Media Player 는 많은 경우, 시스템에 CODEC 가 없는 경우, 그 CODEC 를 다운로드, 인스톨 하려고 한다.

Windows 2000 에 포함되어 있는 몇개의 공통의 CODEC 는, Radius Cinepak, Duck TrueMotion, Intel Indeo, Microsoft RLE, 그리고 Microsoft Video 1 이다. Windows 2000 시스템의 비디오 CODEC 의 리스트를 보려면 다음과 같이 한다.

  1. 컨트롤 패널을 연다.
  2. [사운드와 멀티미디어] 를 클릭한다.
  3. [하드웨어] 탭을 클릭한다.
  4. [비디오 CODEC] 를 선택한다.
  5. [프로퍼티] 를 클릭한다.
  6. [프로퍼티] 탭을 클릭한다.

Q: 어느 미디어 파일에 어느 CODEC 가 사용되고 있는지를 아는 방법은?

A: 이하와 같이 하는 것.

  • Explorer 로 파일을 오른쪽 클릭한다.
  • [프로퍼티] 를 클릭한다.
  • [Summary] 탭을 클릭한다.

프로그래밍에 관한 질문

Q: 어떻게 어플리케이션을 빌드 하는지? 어느 라이브러리 파일과 헤더 파일이 필요한가?

A: 「빌드 환경의 설정」을 참조할것.

Q: GraphEdit 가 문서에 없는 많은 필터를 표시한다. 이러한 필터는 무엇인가?

A: GraphEdit 는 있는 필터 카테고리로 시스템에 등록되어 모든 필터를 열거한다. 이것은 써드파티 어플리케이션이 인스톨 한 필터나 Windows Media 와 같은 다른 Microsoft 테크놀러지가 인스톨 한 필터를 포함하고 있다. 또 있는 DirectShow 필터는 CODEC 나 하드웨어 디바이스의 래퍼로서 동작하는, 각 CODEC 나 디바이스는 다른 필터로서 표시된다. 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것.

Q: 프로그램적으로 필터의 추가와 접속을 하는 커스텀 그래프의 구축으로 문제가 있다. 어떻게 해 이것에 대한 원조를 얻을 수 있는지?

A: 최초로 모든 것을 Filter Graph Editor (GraphEdit)로 구축하는 것. 이 툴을 사용하면, 많은 가능성을 재빠르게 시뮬레이트 할 수 있어 문제를 시각적으로 수정할 수가 있다. GraphEdit 는 보통, 원시 코드로 구축하려고 하기 전에 그래프를 구축하는 뛰어난 장소이다.

추가 정보: 소스와 비디오 렌더러의 사이의 인텔리전트 접속을 실시하고 있다면, 소스와 렌더러의 사이에 올바른 미디어 타입 변환을 실시하는 일련의 필터의 삽입을 DirectShow 에 가르친다. 그 소스 필터는 오디오와 비디오가 들어가는 1 개의 출력을 가진다. 그러므로, 오디오와 비디오를 다른 스트림으로 하는 필터 (데마르치프렉스)가 추가되지 않으면 안 된다. 따라서 해야 하는 것은 오디오 렌더러를 디멀티플렉서의 오디오 핀에 접속하는 것이다. 소스 미디어 타입에 의해, 사용되는 디멀티플렉서는 복수의 필터 가운데 1 개가 되는 경우가 있다. AVI 에 대해서는, AVI 스플리터가 그 일을 실시한다. MPEG2 에서는, MPEG2 스플리터나 MPEG-2 디멀티플렉서가 될 것이다. 스마트 접속을 사용하고 있다면, 디멀티플렉서를 찾아내 오디오 핀을 찾아내고. 다음에 렌더러에 접속해야 한다.

용이한 방법을 희망한다면 :

  • 소스 필터를 추가한다
  • 가지고 있는 임의의 어플리케이션 고유의 렌더러를 추가한다.
  • 출력 핀으로 "Render" 를 호출한다.

이것은 그래프내에 있는 출력 핀에 대응하는 렌더러를 가지고 있는 경우의 "Connect" 와 등가이다, 그러나 1 개(살)도 가지고 있지 않으면 렌더러를 추가할 것이다. 따라서 오디오도 비디오도 양쪽 모두 접속될 것이다.

Q: 특정의 머신에 DirectShow 가 인스톨 되고 있는지 어떤지를 확인하는 방법은?

A: CoCreateInstance 를 호출해 필터 그래프 매니저의 인스턴스를 생성 한다. 이 호출이 성공했을 경우는, DirectShow 가 머신에 인스톨 되고 있다. 다음의 코드에 호출해 방법을 나타낸다.

IGraphBuilder *pGraph;

HRESULT hr = CoCreateInstance(CLSID_FilterGraph,
    NULL, CLSCTX_INPROC_SERVER,
IID_IGraphBuilder, (void **) &pGraph);

Q: 프로퍼티 페이지를 표시하지 않고 필터의 설정을 변경하는 방법은?

A: 대부분의 필터는, 필터의 프로퍼티를 설정하기 위한 1 개(살) 이상의 인터페이스를 공개하고 있다. 목적의 필터의 레퍼런스 페이지를 조사하는 것 ( 「필터」를 참조).

Q: 왜 「ASF 라이터」와「ASF 리더」필터를 사용할 수 없는 것인지?

A: 어플리케이션을 빌드 하면 와, 소프트웨어의 인증을 제공해야 한다. 「DirectShow 에서의 ASF 파일의 생성」 및 「 Windows Media Format SDK」를 참조할것. 또 GraphEdit 내에서 이러한 필터를 사용할 수 없다.

Q: DirectShow 는 현재의 재생 위치를 정기적으로 어플리케이션에 통지할 수 있을까?

A: 위치의 콜백 통지는 행해지지 않는다. 타이머를 사용해,IMediaSeeking::GetCurrentPosition 메소드를 사용해 현재의 위치를 취득하는 것.

Q: 필터를 썼지만, 어떻게 해 인스톨 하면 좋은가?

A: 「DirectShow 오브젝트의 등록 방법」을 참조할것.

Q: GraphEdit 로 자신의 필터를 테스트할 수 있을까?

A: 필터 개발중에 GrapEdit 는 필터간의 접속을 시각화해, 원조한다. GraphEdit 는 필터 기능의 퀵 테스트도 제공한다. 그러나, 그것은 풍부한 테스트 플랫폼은 아니다. 상세한 것에 대하여는, 「GraphEdit 에 의한 그래프 구축의 시뮬레이션」을 참조할것.

Q: 필터내의 핀의 수를 확인하는 방법은?

A: S_OK 이외의 값을 돌려줄 때까지 IBaseFilter::EnumPins 메소드를 호출해, 다음에 IEnumPins::Next 메소드를 호출한다. 상세한 것에 대하여는, 「필터 그래프내의 오브젝트의 열거」를 참조할것.

Q: 필터는 어느 권한 링으로 동작할까?

A: 필터는 링 3 으로 동작한다. 그러나, 스트리밍 디바이스를 제어하는 필터는 링 0 으로 동작하는 것이 있다. 「하드웨어 디바이스가 필터 그래프에 참가하는 방법」을 참조할것.


퍼스트 스텝 가이드

여기에서는, 어플리케이션 개발에 필요한 Microsoft® DirectShow® 의 기본 개념을 설명한다. DirectShow 의 개요 소개로서 읽을 수 있다. 여기에 나타내는 주제는, 프로그래밍과 미디어에 관한 일반적인 지식만 있으면 이해할 수 있는 내용이 되어 있다.

  • DirectShow 어플리케이션 프로그래밍의 개요
  • 빌드 환경의 설정
  • 파일의 재생법
  • 비디오 윈도우의 설정
  • 이벤트에의 응답


DirectShow 어플리케이션 프로그래밍의 개요

여기에서는, Microsoft® DirectShow® 어플리케이션을 생성 하기 위해서 필요한, 기본적인 용어와 개념에 대해 설명한다. DirectShow 로 사용되는 전문 용어에 대해서도 설명한다. 이 내용을 읽으면(자), 처음의 DirectShow 어플리케이션을 생성 할 준비가 갖추어진다.

여기에서는 다음의 내용에 대해 설명한다.

  • 필터 그래프
  • DirectShow 어플리케이션의 생성

필터 그래프

DirectShow 를 구성하는 기본 요소는, 필터로 불리는 소프트웨어 컴퍼넌트이다. 필터는, 보통, 멀티미디어 스트림에 대해서 단일의 조작을 실행한다. 예를 들어, DirectShow 에는 다음과 같은 필터가 있다.

  • 파일을 읽는다.
  • 비디오 캡춰 디바이스로부터 비디오를 취득한다.
  • MPEG-1 비디오등의 특정의 스트림 포맷을 디코드한다.
  • 그래픽 카드 또는 사운드 카드로 데이터를 건네준다.

필터는 입력을 받아, 출력을 생성한다. 예를 들어, 필터가 MPEG-1 비디오를 디코드하는 경우, 입력은 MPEG 로 encode 된 스트림이며, 출력은 압축되어 있지 않은 RGB 비디오 스트림이다.

지정된 태스크를 실행하기 위해서, 어플리케이션에서는 복수의 필터를 접속해, 1 개의 필터로부터의 출력을 다른 필터의 입력으로 한다. 접속된 필터의 집합은, 필터 그래프로 불린다. 이 개념을 나타내는 그림으로서 AVI 파일을 재생하는 필터 그래프를 다음에 나타낸다.

AVI 파일을 재생하는 필터 그래프

어플리케이션에서는 필터 그래프의 개개의 필터를 관리할 필요가 없다. DirectShow 에는 필터 그래프 매니저로 불리는 상위 레벨의 컴퍼넌트가 준비되어 있다. 필터 그래프 매니저는, 그래프를 통과하는 데이터의 흐름을 제어한다. 어플리케이션에서는, "Run" (그래프의 시작으로부터 마지막까지 데이터를 이동한다)나 "Stop" (데이터의 흐름을 정지한다)등의 상위 레벨의 API 호출을 실시한다. 스트림 조작을 보다 직접적으로 제어할 필요가 있는 경우는, COM 인터페이스를 통해 필터에 직접 액세스 할 수가 있다. 또, 필터 그래프 매니저는 어플리케이션에 이벤트 통지를 건네준다. 거기에 따라, 어플리케이션으로 스트림의 마지막등의 이벤트에 응답할 수 있다.

게다가 필터 그래프 매니저를 사용 하면, 필터 그래프를 구축하는 프로세스가 간단하게 된다. 예를 들어, 파일명을 지정 하면, 그 파일을 재생하는 그래프가 필터 그래프 매니저에 의해 구축된다.

DirectShow 어플리케이션의 생성

일반적인 DirectShow 어플리케이션은, 다음의 그림에 나타내는 3 개의 기본적인 순서를 실행한다.

일반적인 DirectShow 어플리케이션

  1. CoCreateInstance 함수를 사용해 필터 그래프 매니저의 인스턴스를 생성 한다.
  2. 필터 그래프 매니저를 사용해 필터 그래프를 구축한다. 다른 DirectShow 헬퍼 컴퍼넌트를 사용할 수도 있다.
  3. 필터 그래프를 제어해, 이벤트에 응답한다.

DirectShow 로 작업을 시작 하려면 , 「파일의 재생법」을 참조할것. 파일을 재생하는 간단한 콘솔 프로그램이 나타나고 있다. 이 어플리케이션은, 종래의 "Hello World" 프로그램의 DirectShow 판이다. 「비디오 윈도우의 설정」 및 「이벤트에의 응답」에서는, 그 프로그램을 간단한 Windows 어플리케이션에 확장하고 있다.


빌드 환경의 설정

이 주제에서는, Microsoft® DirectShow® 의 어플리케이션과 필터를 빌드 하는 방법을 설명한다. 프로젝트의 구축은, 커멘드 라인으로부터 실시하는 일도, Microsoft® Visual C++® 에 동고 되고 있는 Microsoft® Visual Studio® 환경으로부터 실시할 수도 있다.

  • DirectShow 어플리케이션의 빌드
  • DirectShow 필터의 빌드

DirectShow 어플리케이션의 빌드

헤더 파일

모든 DirectShow 어플리케이션에서는, 다음 표의 헤더 파일이 사용된다.

헤더 파일 | 용도
Dshow.h | 모든 DirectShow 어플리케이션

DirectShow 인터페이스에 따라서는, 추가의 헤더 파일이 필요한 일도 있다. 그 자세한 것은, 인터페이스의 설명에 포함되어 있다.

라이브러리 파일

DirectShow 에서는, 다음 표의 라이브러리 파일이 사용된다.

라이브러리 파일 | 설명
Strmiids.lib | 클래스 식별자 (CLSIDs)와 인터페이스 식별자 (IIDs)의 export. 모든 DirecShow 어플리케이션에는 이 라이브러리가 필요.
Quartz.lib | AMGetErrorText 함수를 export. 이 함수를 호출하지 않으면, 이 라이브러리는 필요없다.
Strmbase.lib | DirectShow base class를 사용하는 경우만 필요.

빌드 환경에 있어서는, SDK 인클루드 디렉토리와 라이브러리 디렉토리는, 검색 패스의 최초의 디렉토리로 해야 한다. 이것에 의해 이러한 파일의 최신 버젼을 사용할 수 있다.

DirectShow 필터의 빌드

DirectShow 필터를 빌드 하는 경우에는, 지금까지의 섹션으로 설명한 스텝 외에, 이하의 스텝을 실행할 필요가 있다.

  • __stdcall 호출 규칙을 사용한다.
  • 리테일 빌드에서는, 프리프로세서 플래그 RELEASE 를 추가한다. 디버그 빌드에서는, 프리프로세서 플래그 DEBUG 를 추가한다.
  • 엔트리 포인트의 심볼을 DllEntryPoint@12 로 설정한다.
  • 필터를 DLL 로서 이행 하는 경우는, DLL 함수를 export 하는 정의 파일 (. def 파일)을 인클루드 한다. 정의 파일의 일례를 이하에 나타낸다. 필터의 출력 파일은 Filter.dll 와 상정되고 있다.
    LIBRARY FILTER.DLL
DESCRIPTION 'Description of my filter'
PROTMODE
EXPORTS
    DllGetClassObject
    DllCanUnloadNow
    DllRegisterServer
    DllUnregisterServer
  • 필터로 SDK 의 필터 base class를 사용하는 경우에는, base class를 구축해, 링크할 필요가 있다. 상세한 것에 대하여는, 「DirectShow base class의 사용법」을 참조할것.


파일의 재생법

이 주제에서는, Microsoft® DirectShow® 로 미디어 파일을 재생하는 방법을 설명해, 미디어 파일을 재생하는 C++ 의 샘플 프로그램을 나타낸다. 이 프로그램은, 고전적인 "Hello World" 프로그램의 DirectShow 판이다.

이 주제는, 이하의 섹션으로 구성된다.

  • 파일의 재생
  • 샘플 코드

파일의 재생

DirectShow 를 사용한 파일의 재생은, 이하의 4 단계의 처리로 행해진다.

  1. 필터 그래프 매니저의 인스턴스를 생성한다.
  2. 필터 그래프 매니저를 사용해, 필터 그래프를 생성 한다.
  3. 필터 그래프 매니저를 사용해, 필터 그래프를 실행한다.
  4. 재생이 종료하는 것을 기다린다.

이 처리에는, 이하의 COM 인터페이스가 필요하다.

  • IGraphBuilder : 필터 그래프를 구축한다.
  • IMediaControl : 필터 그래프내의 미디어 스트리밍을 처리한다.
  • IMediaEvent : 필터 그래프 이벤트의 핸들.

필터 그래프 매니저는 이러한 인터페이스 모든 것을 이행 한다.

COM 라이브러리를 초기화하는 CoInitialize 함수를 호출하는 것에 의해 시작 한다. 다음에 CoCreateInstance 함수를 호출해, 필터 그래프 매니저를 생성 한다 :

IGraphBuilder *pGraph;
CoInitialize(NULL);
CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC_SERVER,
                    IID_IGraphBuilder, (void **) &pGraph);

CoCreateInstance 함수는 필터 그래프 매니저의 IGraphBuilder 인터페이스를 돌려준다. 이 인터페이스 포인터를 사용해, 필요한 2 개의 인터페이스 IMediaControl 와 IMediaEvent 를 쿼리 한다 :

IMediaControl *pMediaControl;
IMediaEvent   *pEvent;
pGraph->QueryInterface(IID_IMediaControl, (void **) &pMediaControl);
pGraph->QueryInterface(IID_IMediaEvent, (void **) &pEvent);

프로그램의 중심부분에 왔다 :

pGraph->RenderFile(L"C:\\Hello_World.avi", NULL);
pMediaControl->Run();
pEvent->WaitForCompletion(INFINITE, &evCode);

IGraphBuilder::RenderFile 메소드는, 지정된 파일을 재생하는 필터 그래프를 구축한다. 최초의 파라미터는, 와이드 문자 (2 바이트)의 Unicode 캐릭터 라인으로 나타내진 파일명이다. 간단하기 때문에, 샘플 프로그램에서는, 유저에게 파일명을 선택시키는 것이 아니라, 리터럴 캐릭터 라인을 지정하고 있다. 프리픽스 "L" 를 붙이면(자), ASCII 캐릭터 라인이 와이드 캐릭터 라인에 변환된다. 2 개째의 파라미터는 예약이 끝난 상태로, NULL 가 아니면 안된다.

필터 그래프를 구축 하면, 필터 그래프 매니저는 재생을 시작 할 수가 있다. IMediaControl::Run 메소드가, 그래프를 실행 모드에 새로 바꾼다. 어플리케이션이 이 메소드를 호출하면, 미디어 데이터는 필터 그래프를 대로 시작해 비디오, 오디오, 또는 양쪽 모두로서 렌더링 된다.

IMediaEvent::WaitForCompletion 메소드는 파일이 재생될 때까지 블록 한다. 재생은 다른 thread로 계속된다. 실제의 어플리케이션에서는 대기 시간을 INFINITE 에 세트 해서는 안되는, 이것은 무제한하게 블록 해 버리기 때문이다. 또 다른 필터 그래프 이벤트에 대응하고 싶은 경우도 있다. 이벤트 핸들링의 상세한 것에 대하여는, 「이벤트에의 응답」을 참조할것.

더욱, 실제의 어플리케이션에서는,RenderFile 의 반환값을 테스트해 필터 그래프의 생성이 성공한 것을 확인해야 한다. 예를 들어, 지정한 파일이 없는 경우,RenderFile 는 실패해 에러 코드 VFW_E_NOT_FOUND 를 돌려준다.

최종적으로, 모든 인터페이스 포인터와 COM 라이브러리를 해방하는 것으로 클린 업 한다 :

pMediaControl->Release();
pEvent->Release();
pGraph->Release();
CoUninitialize();

샘플 코드

이하의 샘플 코드는 파일을 재생한다 :

#include <dshow.h>

void main(void)
{
    IGraphBuilder *pGraph;
    IMediaControl *pMediaControl;
    IMediaEvent   *pEvent;
    CoInitialize(NULL);

    // 필터 그래프 매니저를 생성 해, 인터페이스를 쿼리 한다.
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC_SERVER,
                        IID_IGraphBuilder, (void **) &pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **) &pMediaControl);
    pGraph->QueryInterface(IID_IMediaEvent, (void **) &pEvent);

    // 그래프를 생성. 중요: 사용 시스템의 파일 캐릭터 라인으로 변경하는 것.
    pGraph->RenderFile(L"C:\\Hello_World.avi", NULL);

    // 그래프의 실행.
    pMediaControl->Run();

    // 종료를 기다린다.
    long evCode;
    pEvent->WaitForCompletion(INFINITE, &evCode);

    // 클린 업.
    pMediaControl->Release();
    pEvent->Release();
    pGraph->Release();
    CoUninitialize();
}


비디오 윈도우의 설정

이 주제에서는, 특정의 윈도우에 비디오 재생을 어태치 하는 방법을 해설한다. 샘플 프로그램을 나타내, 샘플을 이해하기 위해서 필요한 생각을 설명한다. 이 샘플 프로그램은, 「파일의 재생법」으로 가리킨 샘플을 기본으로 하고 있다.

이 주제는 이하의 섹션으로 구성된다.

  • 비디오 윈도우
  • IVideoWindow 인터페이스의 사용
  • 샘플 코드

비디오 윈도우

비디오 파일을 렌더링 하면 와, 필터 그래프에는 비디오 렌더링 필터가 포함된다. 비디오 렌더러는, 압축되어 있지 않은 비디오 데이터를 받아, 윈도우내의 화면에 그것을 렌더링 한다. 지정하지 않으면, 비디오 재생 윈도우는, 자신의 경계와 타이틀 바를 가지는 톱 레벨의 윈도우가 된다. 그러나, 어플리케이션으로 생성 한 특정의 윈도우에 비디오를 표시하는 것이 많다. 해결책은, 렌더러의 비디오 윈도우를 어플리케이션 윈도우의 자식 윈도우로 하는 것이다. 이것을 실시하려면 , 비디오 윈도우의 프로퍼티를 설정해, 윈도우의 소유자, 스타일, 및 위치를 지정한다.

비디오 렌더링 필터가 지원 하는 IVideoWindow 인터페이스에, 비디오 윈도우의 프로퍼티를 설정 및 취득하기 위한 메소드가 포함되어 있다. 그러나, 필터 그래프 매니저를 사용해 필터 그래프를 구축했을 경우는, 비디오 렌더링 필터에의 포인터를 가지고 있다고는 할 수 없다. 그 때문에, 필터 그래프 매니저도 IVideoWindow 를 지원 하고 있다. 필터 그래프 매니저는, 그래프내에서 IVideoWindow 를 공개하고 있는 필터의 리스트를 보관 유지해, 필터 그래프 매니저의 IVideoWindow 메소드가 불려 가면(자), 이러한 필터에의 호출을 할당한다. 이와 같이 해, 어플리케이션이 적절한 필터를 찾아내지 않아도, 필터 그래프 매니저가 각각의 필터의 처리를 지원 할 수 있다.

필터 그래프 매니저는, 이것과 같은 방법으로 IBasicVideo2 및 IBasicAudio 인터페이스를 공개하고 있다. 이러한 인터페이스에는, 오디오 및 비디오의 프로퍼티를 설정하기 위한 메소드가 포함된다. 각각의 필터에 대해서 이러한 인터페이스를 호출하는 것이 아니라, 필터 그래프 매니저에 대해서 호출한다.

IVideoWindow 인터페이스의 사용

이 섹션에서는,IVideoWindow 인터페이스를 사용해 소유자나 스타일 등, 비디오 윈도우의 프로퍼티를 설정하는 방법을 설명한다.

주 : 이 주제의 샘플 프로그램에서는, 코드의 대부분은 표준의 윈도우 처리를 실시하는 것이므로, 여기에서는 설명하지 않는다. 특히,WindowProc 및 WinMain 함수에는, Microsoft® Windows® 어플리케이션의 전형적인 체제가 포함되어 있다. 어플리케이션으로 정의하는 함수, PlayFile 및 CleanUp 에 대해서는 설명한다.

우선, 필터 그래프 매니저의 인스턴스를 생성해,IGraphBuilder::RenderFile 메소드를 호출해 필터 그래프를 구축한다. 이 처리의 상세한 것에 대하여는, 「파일의 재생법」을 참조할것.

다음에, 재생을 시작하기 전에, 이하와 같이 비디오 윈도우의 프로퍼티를 설정한다.

  1. 비디오 재생 윈도우를 부모 윈도우에 어태치 한다. 이것을 실시하려면 ,IVideoWindow::put_Owner 메소드를 호출해, 소유자 윈도우에의 핸들을 건네준다. 이 메소드는 OAHWND 형의 변수를 받기 (위해)때문에, 필요한 경우는 핸들을 이 형태에 캐스트 한다.
    IVideoWindow    *pVidWin = NULL;
pGraph->QueryInterface(IID_IVideoWindow, (void **) &pVidWin);
pVidWin->put_Owner((OAHWND) g_hwnd);
  2. 비디오 윈도우의 스타일을 자식 윈도우로 변경한다. 이것을 실시하려면 ,IVideoWindow::put_WindowStyle 메소드를 호출해, 스타일 플래그의 편성을 건네준다. WS_CHILD 플래그는, 윈도우가 자식 윈도우인 것을 지정한다. WS_CLIPSIBLINGS 플래그는, 윈도우가 다른 자식 윈도우의 내부에 그려지지 않게 한다.
    pVidWin->put_WindowStyle(WS_CHILD | WS_CLIPSIBLINGS);
  3. 비디오 윈도우의 위치를 설정한다. 이것에는,IVideoWindow::SetWindowPosition 메소드를 호출한다. 이 메소드는, 윈도우의 좌단 (x-축), 상단 (y-축), 폭, 높이를 지정하는 디바이스 좌표를 받는다. 샘플 프로그램에서는, 부모 윈도우의 전체가 들어가도록(듯이) 비디오 윈도우를 확대하고 있다.
    RECT grc;
GetClientRect(g_hwnd, &grc);
pVidWin->SetWindowPosition(0, 0, grc.right, grc.bottom);

    GetClientRect 함수는,RECT 구조체를 윈도우의 클라이언트 영역의 좌표로 채운다. 이 좌표는, 클라이언트 영역의 좌상구석으로부터의 것이기 (위해)때문에,left 및 top 멤버는 0 으로,right 및 bottom 멤버가 각각 폭과 높이를 정의한다.

어플리케이션이 종료하기 전에, 비디오 윈도우의 표시를 False 로 설정하는 것이 중요하다. 그렇게 하지 않으면 비디오 이미지가 화면에 남아, 유저는 그것을 제거할 수가 없다. 다음에, 소유자를 NULL 에 리셋 한다. 그렇게 하지 않으면 잘못한 윈도우에 메세지가 송신되어 에러가 발생할 가능성이 있다.

HRESULT hr = pVidWin->put_Visible(OAFALSE);
hr = pVidWin->put_Owner(NULL);

샘플 코드

이하의 샘플 프로그램은, Test.avi 라는 이름의 파일을 어플리케이션 윈도우의 내부에 렌더링 한다. 간단하기 때문에, 이하의 기능은 생략 하고 있다.

  • 부모 윈도우의 사이즈가 변경되었을 때, 비디오 윈도우의 사이즈를 변경하지 않는다. 이것을 실시하려면 , 부모 윈도우의 WM_SIZE 메세지에 응해,IVideoWindow::SetWindowPosition 를 한번 더 호출한다.
  • 에러 체크는 실시하지 않는다.
  • 소스의 어스펙트비(가로세로 비율)을 고려하지 않고 , 비디오 윈도우를 확대한다. 어스펙트비(가로세로 비율)을 조사하려면 ,IBasicVideo 인터페이스를 사용한다.
  • 엔드 오브 스트림 이벤트는 취급하지 않는다. 이 방법에 대해서는, 「이벤트에의 응답」을 참조할것.
#include <windows.h>
#include <dshow.h>

#define CLASSNAME "VideoWindow"

IGraphBuilder   *pGraph = NULL;
IMediaControl   *pMediaControl = NULL;
IVideoWindow    *pVidWin = NULL;
HWND            g_hwnd;

void PlayFile(void)
{
    // 필터 그래프 매니저를 생성한다.
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC,
        IID_IGraphBuilder, (void **) &pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **) &pMediaControl);
    pGraph->QueryInterface(IID_IVideoWindow, (void **) &pVidWin);

    // 그래프를 구축한다.
    pGraph->RenderFile(L"Test.avi", NULL);

    // 비디오 윈도우를 설정한다.
    pVidWin->put_Owner((OAHWND) g_hwnd);
    pVidWin->put_WindowStyle(WS_CHILD | WS_CLIPSIBLINGS);

    RECT grc;
    GetClientRect(g_hwnd, &grc);
    pVidWin->SetWindowPosition(0, 0, grc.right, grc.bottom);

// 그래프를 실행한다.
    pMediaControl->Run();
}

void CleanUp(void)
{
    pVidWin->put_Visible(OAFALSE);
    pVidWin->put_Owner(NULL);
    pMediaControl->Release();
    pVidWin->Release();
    pGraph->Release();
}

// 메세지 핸들러
long FAR PASCAL WindowProc( HWND hwnd, UINT msg, UINT wParam, LONG lParam)
{
    switch (msg)
    {
        case WM_DESTROY:
            CleanUp();
            PostQuitMessage(0);
            break;
        default:
            return (DefWindowProc(hwnd, msg, wParam, lParam));
    }
    return(NULL);
}

// 메인
int PASCAL WinMain( HINSTANCE hInst, HINSTANCE hPrevInst, LPSTR  lpCmdLine,
    int nCmdShow )
{
    MSG         msg;
    WNDCLASS    wc;

    CoInitialize(NULL);

    ZeroMemory(&wc, sizeof wc);
    wc.lpfnWndProc  = WindowProc;
    wc.hInstance    = hInst;
    wc.hIcon        = LoadIcon( NULL, IDI_APPLICATION );
    wc.hCursor      = LoadCursor( NULL, IDC_ARROW );
    wc.hbrBackground = (HBRUSH) GetStockObject( BLACK_BRUSH );
    wc.lpszMenuName = NULL;
    wc.lpszClassName = CLASSNAME;
    RegisterClass( &wc );

    g_hwnd = CreateWindow(
        CLASSNAME,
        "DirectShow Sample",
        WS_OVERLAPPEDWINDOW,
        CW_USEDEFAULT,
        CW_USEDEFAULT,
        CW_USEDEFAULT,
        CW_USEDEFAULT,
NULL,
NULL,
        hInst,
        NULL);

    ShowWindow( g_hwnd, nCmdShow );
    UpdateWindow( g_hwnd );
    PlayFile();

    while( GetMessage( &msg, NULL, 0, 0 ) )
    {
        TranslateMessage( &msg );
        DispatchMessage( &msg );
    }

    CoUninitialize();
    return msg.wParam;
}


이벤트에의 응답

이 주제에서는, Microsoft® DirectShow® 어플리케이션으로 발생하는 이벤트에 응답하는 방법을 해설한다. 비디오 윈도우의 설정으로 가리킨 샘플에 근거하는 샘플 프로그램을 나타내지만, 샘플의 모든 코드는 가리키지 않고, 추가가 필요한 약 25 행의 코드에 대한 보고 설명한다.

이 주제는, 이하의 섹션으로 구성된다.

  • 이벤트 통지의 동작
  • 이벤트 통지의 사용법
  • 샘플 코드

이벤트 통지의 동작

DirectShow 어플리케이션의 실행중은, 다양한 시점에서 필터 상태가 변화한다. 예를 들어, 필터는 포즈 상태로부터 실행 상태가 되거나 스트림내에서 에러를 당하거나 비디오 윈도우의 재드로잉(Drawing)를 요구하거나 한다. 필터 그래프 매니저에 변화를 알리기 위해서(때문에), 필터는"이벤트 통지"를 송신한다. 이벤트 통지는, 이벤트의 타입을 나타내는 이벤트 코드와 추가 정보를 주는 2 개의 파라미터로부터 된다. 파라미터의 의미는, 이벤트 코드에 따라서 다르다. 이벤트 코드와 그 파라미터의 완전한 리스트에 대해서는, 「이벤트 통지 코드」를 참조할것.

필터 그래프 매니저는, 비디오 윈도우의 재드로잉(Drawing)의 요구 등, 일부의 이벤트에 대해서는 어플리케이션에 통지하지 않고 처리를 실시해, 그 외의 이벤트는 큐에 넣는다. 어플리케이션은, 큐내의 이벤트를 차례로 꺼내 처리한다. DirectShow 의 이벤트 통지는, 이 점으로써 Microsoft® Windows® 의 멧세이지큐잉과 닮아 있다. 실제, 새로운 이벤트가 발생했을 때, 필터 그래프 매니저에, 지정한 윈도우에 Windows 메세지를 송신시킬 수가 있다. 어플리케이션은, 이 방법으로 윈도우의 메시지 루프중에서 이벤트를 처리할 수가 있다.

어플리케이션은, 그 목적에 따라 몇개의 이벤트 코드를 취급할 필요가 있다. 여기에서는,EC_COMPLETE 와 EC_USERABORT 의 2 개에 중점을 둔다.

  • 렌더링 필터는, 데이터 스트림의 종단에 이르면(자) EC_COMPLETE 를 통지제상태로 한다. 필터 그래프에는, 비디오 스트림과 오디오 스트림 등, 복수의 스트림이 포함되는 경우가 있다. 각 스트림은, 각각의 렌더러에 관련지을 수 있고 있기 (위해)때문에, EC_COMPLETE 이벤트를 따로 따로 발생시킨다. 필터 그래프 매니저는, 모든 EC_COMPLETE 이벤트를 어플리케이션에 전송 하는 것이 아니라, 그래프내의 모든 스트림으로부터 EC_COMPLETE 통지를 1 개씩 받을 때까지 기다려, 모든 통지를 받은 시점에서, 1 개의 EC_COMPLETE 이벤트를 어플리케이션에 보낸다. 어플리케이션이 EC_COMPLETE 이벤트를 받았을 때, 모든 스트림은 종료하고 있다.
  • EC_USERABORT 이벤트는, 유저가 재생을 중단한 것을 알린다. 유저가 비디오 윈도우를 닫으면(자), 비디오 렌더러가 이 이벤트를 송신한다.

이벤트 통지의 사용법

샘플 어플리케이션에서는, 윈도우의 메인 메시지 루프중에서 이벤트를 처리한다. 그 때문에(위해), 새로운 이벤트가 발생했을 때, 필터 그래프 매니저에 메세지를 송신시킨다. 어플리케이션은 거기에 응해, 이벤트를 받아 적절한 처리를 실시한다.

윈도우의 메인 메시지 루프중에서 이벤트를 처리하기 위해서, 새로운 이벤트가 발생했을 때에 어플리케이션에 송신되는 메세지를 정의한다. 이하의 예에 나타내도록(듯이), 어플리케이션은 프라이빗 메세지로서 WM_APP ~ 0xBFFF 의 범위의 메세지 번호를 사용할 수 있다.

#define WM_GRAPHNOTIFY  WM_APP + 1

다음에, 이 메세지를 어플리케이션의 메인 윈도우에 전달하도록(듯이), 필터 그래프 매니저를 설정한다.

pEvent->SetNotifyWindow((OAHWND) g_hwnd, WM_GRAPHNOTIFY, 0);

IMediaEventEx::SetNotifyWindow 메소드는, 지정된 윈도우 (g_hwnd)를 메세지의 수신자로서 지정한다. 필터 그래프를 생성 해, 소유자 윈도우를 지정하면(자), 그래프를 실행하기 전에 이 메소드를 호출한다. 상세한 것에 대하여는, 「샘플 코드」를 참조할것. IMediaEventEx 인터페이스는, 필터 그래프 매니저가 공개한다.

어플리케이션이 WM_GRAPHNOTIFY 메세지를 받아들일 때, 메세지의 lParam 파라미터는,SetNotifyWindow 에 건네준 3 개째의 파라미터와 동일하다. 이 파라미터를 사용하면, 메세지와 함께 인스턴스 데이터를 보낼 수가 있다. 샘플 코드는 이 데이터를 사용하지 않기 때문에, 값 0 을 건네준다. 메세지의 wParam 파라미터는 항상 0 이다.

윈도우의 WindowProc 함수에, WM_GRAPHNOTIFY 메세지용의 case 스테이트먼트를 추가한다 :

case WM_GRAPHNOTIFY:
    HandleEvent();
    break;

WM_GRAPHNOTIFY 는, 보통의 Windows 메세지이며, DirectShow 의 이벤트 통지 큐와는 별도로 송신된다. 이벤트의 순서는 이하대로이다.

  1. 필터가, 필터 그래프 매니저에 이벤트 통지를 송신한다.
  2. 필터 그래프 매니저는 이벤트를 처리하지 않는 경우, 이벤트를 이벤트 큐에 넣는다.
  3. 필터 그래프 매니저가, 어플리케이션 윈도우에 WM_GRAPHNOTIFY 메세지를 송신한다.
  4. 어플리케이션이, 윈도우의 메시지 루프중에서 메세지에 응답한다.
  5. 어플리케이션이, 큐로부터 이벤트 통지를 꺼낸다.

이벤트 핸들러 함수 중(안)에서 IMediaEvent::GetEvent 메소드를 호출해, 큐로부터 이벤트를 꺼낸다.

long evCode, param1, param2;
HRESULT hr;
while (hr = pEvent->GetEvent(&evCode, &param1, &param2, 0), SUCCEEDED(hr))
{
    hr = pEvent->FreeEventParams(evCode, param1, param2);
    if ((EC_COMPLETE == evCode) || (EC_USERABORT == evCode))
    {
        CleanUp();
        break;
    }
}

GetEvent 메소드는, 이벤트 코드와 2 개의 파라미터를 꺼낸다. GetEvent 에의 마지막 파라미터는, 이 메소드가 이벤트를 기다리는 시간을 지정한다. 어플리케이션은, WM_GRAPHNOTIFY 메세지에 응해 이 메소드를 호출한다. 그 때 이벤트는 이미 큐에 들어가 있으므로, 타임 아웃값에 0 을 지정한다.

이벤트 통지와 메시지 루프는 어느쪽이나 비동기에 행해지기 (위해)때문에, 어플리케이션이 메세지에 응답 하면 와까지, 큐에는 복수의 이벤트가 들어가 있을 가능성이 있다. 또, 필터 그래프 매니저는, 이벤트가 무효가 되었을 경우에 큐로부터 이벤트를 소거할 수가 있다. 그 때문에, 큐가 하늘인 것을 나타내는 실패 코드가 돌려주어질 때까지 GetEvent 를 호출한다.

샘플 프로그램은, EC_COMPLETE 또는 EC_USERABORT 이벤트를 받으면(자), 어플리케이션으로 정의된 CleanUp 함수를 호출한다. 이 함수에 의해, 어플리케이션은 신속하게 종료한다. 2 개의 이벤트 파라미터 (param1 와 param2)는 무시된다. 이벤트를 꺼내면(자),IMediaEvent::FreeEventParams 를 호출해, 이벤트 파라미터에 관련하는 리소스를 해방한다. 예를 들어, 파라미터가 BSTR 의 경우, 그 메모리는 필터 그래프 매니저에 의해 할당할 수 있고 있다.

EC_COMPLETE 이벤트가 발생했을 때, 필터 그래프는 자동적으로는 정지상태태에 바뀌지 않기 때문에, 어플리케이션이 그래프를 정지 또는 포즈 해야 한다. 그래프가 정지 하면, 필터는 보관 유지하고 있는 리소스를 해방한다. 그래프가 포즈 했을 경우, 필터는 리소스를 계속 보관 유지한다. 덧붙여 비디오 렌더러는 포즈 했을 때, 최신의 프레임의 정지화면상을 표시한다. 샘플 프로그램은 그래프를 정지한다.

샘플 코드

이하의 코드에는, WinMain 함수나 WindowProc 함수는 포함되지 않았다. 이러한 함수에 대해서는, 「비디오 윈도우의 설정」의 샘플 코드를 참조할것.
#include <windows.h>
#include <dshow.h>

#define WM_GRAPHNOTIFY  WM_APP + 1
#define CLASSNAME "EventNotify"

IGraphBuilder   *pGraph = NULL;
IMediaControl   *pMediaControl = NULL;
IMediaEventEx   *pEvent = NULL;
IVideoWindow    *pVidWin = NULL;
HWND            g_hwnd;

void PlayFile(void)
{
    // 필터 그래프 매니저를 생성 해, 파일을 렌더링 한다.
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC, IID_IGraphBuilder, (void **) &pGraph);
    pGraph->RenderFile(L"C:\\Media\\Boys.avi", NULL);

    // 소유자 윈도우를 지정한다.
    pGraph->QueryInterface(IID_IVideoWindow, (void **) &pVidWin);
    pVidWin->put_Owner((OAHWND) g_hwnd);
    pVidWin->put_WindowStyle( WS_CHILD | WS_CLIPSIBLINGS);

    // 이벤트 통지를 받도록(듯이) 소유자 윈도우를 설정한다.
    pGraph->QueryInterface(IID_IMediaEventEx, (void **) &pEvent);
    pEvent->SetNotifyWindow((OAHWND) g_hwnd, WM_GRAPHNOTIFY, 0);

// 그래프를 실행한다.
    pGraph->QueryInterface(IID_IMediaControl, (void **) &pMediaControl);
    pMediaControl->Run();
}

void CleanUp(void)
{
    pVidWin->put_Visible(OAFALSE);
    pVidWin->put_Owner(NULL);

    // 그래프를 정지한다.
    pMediaControl->Stop();

    pMediaControl->Release();
    pVidWin->Release();
    pEvent->Release();
    pGraph->Release();
    PostQuitMessage(0);
}

void HandleEvent()
{
    long evCode, param1, param2;
    HRESULT hr;
    while (hr = pEvent->GetEvent(&evCode, &param1, &param2, 0), SUCCEEDED(hr))
    {
        hr = pEvent->FreeEventParams(evCode, param1, param2);
        if ((EC_COMPLETE == evCode) || (EC_USERABORT == evCode))
        {
            CleanUp();
            break;
        }
    }
}

/* 여기에 WindowProc 가 들어간다. 이하의 case 스테이트먼트를 추가한다.
        case WM_GRAPHNOTIFY:
            HandleEvent();
            break;
*/

// 여기에 WinMain 가 들어간다.


DirectShow 에 대해

여기에서는 다음의 내용에 대해 설명한다.

  • DirectShow 시스템의 개요
  • 필터 그래프와 그 컴퍼넌트
  • 필터 그래프의 구축
  • 필터 그래프의 데이터 플로우
  • DirectShow 에서의 이벤트 통지
  • 하드웨어 디바이스가 필터 그래프에 참가하는 방법
  • 동적 그래프 생성
  • PID


DirectShow 시스템의 개요

멀티미디어의 과제

멀티미디어를 취급하는 작업에는 몇개의 큰 과제가 있다.

  • 멀티미디어 스트림에는, 매우 고속으로 처리해야 하는 대량의 데이터가 포함되어 있다.
  • 오디오, 비디오 및 임의의 부가 스트림의 모든 것을, 동시에 시작 해 동시에 정지해, 같은 레이트로 재생하도록(듯이) 동기화할 필요가 있다.
  • 스트림의 소스는, 로컬 미디어 파일, 컴퓨터 네트워크, 지상파 방송, 비디오 카메라, 그 외의 미디어 디바이스 등, 다종 다양하다.
  • 스트림의 포맷도, AVI (Audio-Video Interleaved), ASF (Advanced Streaming Format), MPEG (Motion Picture Experts Group), DV (Digital Video), MJPEG (Motion JPEG) 등, 다양하다.
  • 어플리케이션에서는, 최종 사용자의 시스템으로 어떠한 하드웨어 디바이스가 사용되고 있을까를 아는 방법은 없다.

DirectShow 솔루션

DirectShow 는, 이러한 과제에 대처하도록(듯이) 설계되고 있다. 설계의 주된 목표는, 데이터 전송, 하드웨어의 달라, 및 동기화의 문제를 어플리케이션으로부터 떼어내는 것에 의해, Windows® 플랫폼에서의 멀티미디어 어플리케이션 생성 작업을 용이하게 하는 것이다.

DirectShow 에서는, 비디오 및 오디오의 스트리밍에 필요한 throughput를 실현하기 위해서(때문에), DirectDraw® 와 DirectSound® 를 사용해 시스템의 사운드 카드와 그래픽 카드로 데이터를 효율적으로 렌더링 한다. 동기화는, 멀티미디어 데이터를 타임 스탬프 첨부의 미디어 샘플에 캡슐화하는 것에 의해 실현된다. 다양한 소스, 포맷, 및 하드웨어 디바이스를 처리하기 위해서, DirectShow 는 모듈식 아키텍쳐를 사용하고 있다. 이 아키텍쳐에서는, 필터로 불리는 operating system 컴퍼넌트를 조합해, 많은 다른 시나리오에 대한 지원을 제공할 수 있다.

DirectShow 에는, Windows Driver Model (WDM)에 근거하는 최신의 멀티미디어 캡춰 및 튜닝 디바이스를 지원 하는 필터와 종래의 Video for Windows (VfW) 캡춰 카드나 오디오 압축 매니저 (ACM) 및 비디오 압축 매니저 (VCM)의 인터페이스용으로 생성 된 낡은 CODEC 를 지원 하는 필터가 포함되어 있다.

다음의 그림은, 어플리케이션, DirectShow 컴퍼넌트, DirectShow 가 지원 하는 하드웨어 컴퍼넌트 및 소프트웨어 컴퍼넌트의 관계를 나타내고 있다.

이 도화 가리키도록(듯이), DirectShow 를 사용 하면, 로컬 파일, 로컬의 CD 및 DVD 드라이브, 네트워크 위에의 리모트 파일, Windows Driver Model (WDM)에 근거하는 최근의 TV 튜너 카드 및 비디오 캡쳐 카드, 종래의 Video for Windows® 비디오 캡쳐 카드 등, 다양한 소스의 파일과 스트림을 어플리케이션으로 재생할 수 있다. DirectShow 에는 일부의 파일 포맷용의 고유의 압력과 데콘프렛사가 있어, 많은 써드파티 하드웨어 및 소프트웨어 디코더는, DirecShow 와 호환성이 있다. 게다가 DirectShow 는, 비디오 압축 매니저 (VCM) 및 오디오 압축 매니저 (ACM)의 인터페이스에 근거하는 종래의 VfW CODEC 도 지원 한다. 재생에서는, 하드웨어로 지원 되고 있는 경우는, DirectDraw 하드웨어 가속화 및 DirectSound 기능이 최대한으로 이용된다.


필터 그래프와 그 컴퍼넌트

여기에서는, Microsoft® DirectShow® 의 필터 그래프를 구성하는 컴퍼넌트의 개요에 대해 설명한다. 독자적인 커스텀 DirectShow 필터를 생성 하는 개발자와 어플리케이션으로 DirectShow 를 사용할때로 보이지 않는 곳으로 무엇이 일어나고 있는지를 알고 싶다고 생각하고 있는 DirectShow 어플리케이션 개발자를 대상으로 하고 있다. 다만, 어플리케이션에서는 보통 DirectShow 필터 그래프의 내부 동작을 취급할 필요는 없다. 많은 경우, 필터의 추가, 핀의 접속, 동기화 소스의 설정등의 자세한 것은, 필터 그래프 매니저와 필터 및 핀 자신이 자동적으로 처리한다. 필터 개발자전용의 주 : DirectShow 로 독자적인 커스텀 변환 또는 커스텀 이펙트를 사용하는 경우, 네이티브의 DirectShow 필터를 기술할 필요는 없다. 변환을 실행하는 DirectX Media Object (DMO)를 기술해, DMO 래퍼 필터를 통해 필터 그래프로 사용할 수 있다. 이 때문에, 필터 접속과 동기화의 메카니즘의 모든 상세로부터 완전하게 해방된다.

필터 그래프

미디어 파일 또는 스트림을 하등의 방법으로 재생, 기록, 캡춰, 브로드캐스트, 또는 처리하는 경우는, 1 개(살) 이상의 필터가 필터 그래프로 불리는 구성에 접속된다. 그래프를 구축하는 처리는, 어플리케이션으로 수동에 의해, 또는 그래프 빌더 또는 필터 그래프 매니저에 의해 자동적으로 실시할 수가 있다. 어느 경우도, 프로세스는 보통 소스 필터로부터 시작되어, 항상 2 개(살)의 주요한 계수에 근거하고 있다. 1 개(살)은, 필터가 입력으로서 예측하고 있는 스트림의 수와 스트림의 미디어 타입, 이제(벌써) 1 개(살)은, 필터가 출력하는 스트림의 수와 스트림의 미디어 타입이다. 다음의 그림은, 압축된 비디오가 저장 되고 있는 AVI 파일을 재생하는 간단한 필터 그래프를 나타내고 있다.

그래프내의 화살표는, 데이터가 흐를 방향을 나타낸다. 이 소스 필터는비동기 파일 소스이다. 이 필터는, 파일로부터 바이트 스트림을 읽어내, 비디오 압축 스킴을 포함한 AVI (Audio-Video Interleaved) 포맷을 인식하는 AVI 스플리터 필터에 건네준다. AVI 스플리터는, 데이터를 해석해 타임 스탬프 첨부의 미디어 샘플로 해, 비디오 샘플을 다운 스트림의 AVI 데콘프렛사에 건네준다. 비디오의 경우, 각 샘플에 1 개의 비디오 프레임이 포함된다. AVI 데콘프렛사는 올바른 CODEC 를 찾아내 샘플을 압축 해제해, 압축 해제한 비디오 프레임을 비디오 렌더링 필터에 건네준다. 비디오 렌더링 필터가 컴퓨터 화면에 비디오를 표시한다. 오디오 샘플은 압축되어 있지 않기 때문에, AVI 스플리터는디폴트 DirectSound 디바이스에 직접 접속할 수 있다.

필터

필터는 DirectShow 를 구성하는 기본 요소이다. DirectShow 는 멀티미디어 데이터의 처리를 개개의 스텝에 분할해, 필터는 1 개 (또는 경우에 따라서는 복수)의 처리 스텝을 나타낸다. 이것에 의해, 어플리케이션이 필터를 "조합해", 다종 다양한 클래스의 하드웨어 디바이스 및 소프트웨어 디바이스를 사용하고 있는 다양한 미디어 포맷에 대해서, 다양한 조작을 실행하는 것이 가능하게 된다. 예를 들어, 비동기 파일 소스 필터는 디스크로부터 파일을 읽어내, TV 튜너 필터는 TV 캡춰 카드 위에의 채널을 변경해, MPEG-2 스플리터 필터는 MPEG 스트림의 오디오 및 비디오 데이터를 디코드할 수 있도록(듯이) 해석한다. 이러한 필터는, 각각 내부적으로는 매우 고유한 동작을 실행하지만, 어플리케이션측에서 보면(자), 어느 표준적인 특징을 갖춘 DirectShow 필터에 지나지 않는다. 그 특징이란, IBaseFilter 인터페이스의 지원과 다른 1 개(살) 이상의 DirectShow 필터에의 접속을 나타내는 1 개(살) 이상의 입력 핀, 출력 핀, 또는 그 양쪽 모두의 지원이다.

모든 DirectShow 필터는 3 개의 카테고리로 나누어진다. 소스 필터, 변환 필터, 및 렌더링 필터의 3 개이다.

소스 필터

소스 필터는 처리하는 미처리의 멀티미디어 데이터를 나타낸다. 소스 필터는, 하드 디스크 위에의 파일 (위에의도의 비동기 파일 소스 필터와 같이) 혹은 CD 또는 DVD 드라이브로부터 데이터를 취득하는지, 텔레비젼 수신 카드나 디지탈카메라에 접속한 캡춰 카드등의 "라이브 " 소스로부터 데이터를 취득한다. 이것들 모든 시나리오에 대응한 DirectShow 의 소스 필터가, Microsoft Windows 9x 및 Windows 2000 에 부속되어 있다. 퍼서 또는 스플리터 필터에 미처리의 데이터를 건네줄 뿐(만큼)의 소스 필터도 있으면, 해석 스텝까지 실행하는 소스 필터도 있다.

변환 필터

변환 필터는, 미처리의 데이터 또는 부분적으로 처리된 데이터를 받아, 처리하고 나서 건네준다. 변환 필터에는 많은 종류가 있어, 소수가 예를 드는 것만으로도, 미처리의 바이트 스트림을 샘플과 프레임에 분할하는 퍼서, 압력과 데콘프렛사, 포맷 컨버터등이 있다. DirectShow 에는 많은 일반적인 CODEC 가 포함되어 있다. 위에 나타낸 그림에서는, AVI 스플리터와 AVI 데콘프렛사는 양쪽 모두 변환 필터이다. DirectShow 에 제공되어 있지 않은 변환 필터로서 MPEG-2 디코더가 있다. MPEG-2 디코더는 써드파티로부터 하드웨어 또는 소프트웨어에 이행 되어 제공되고 있다.

렌더링 필터

렌더링 필터는 보통 완전하게 처리된 데이터를 받아, 시스템의 모니터나 스피커, 혹은 외부 디바이스를 통해 재생한다. 디스크 또는 그 외의 영속적인 기억장치에 데이터를 보존하는 "파일 라이터 " 필터도, 렌더링 필터의 카테고리에 속한다. 위에의도에 나타낸 것처럼, DirectShow 에 부속되어 있는 비디오 렌더링 필터는 DirectDraw 를 사용해 비디오를 표시해, 디폴트의 오디오 렌더링 필터는 DirectSound 를 사용해 오디오를 재생한다.

DirectShow 에는 다양한 미디어 포맷의 재생, 변환, 및 캡춰용의 필터가 준비되어 있어 Windows 9x 및 Windows 2000 에 부속되어 있다. 개발자는, 커스텀 또는 표준의 데이터 포맷을 처리하기 위한 독자적인 커스텀 필터를 구축할 수도 있다. DirectX 8 에서는, DirectShow 를 사용 하면, 개발자는 DirectX Media Object (DMO)를 기술해, DMO 래퍼 필터에 모든 동기화 및 핀 접속의 상세를 처리시키는 것에 의해, "필터 " 개발을 간략화할 수 있다. DMO 는 필터보다 개발과 테스트가 간단해, DirectShow 필터 그래프 아키텍쳐에 의존하지 않는다. 한 번 기술한 DMO 는, DirectShow 어플리케이션인가 어떤가에 관계없이, 필요한 경우는 언제라도 재이용할 수 있다.

핀

전의 그림에 나타낸 것처럼, 필터 그래프내의 멀티미디어 데이터는, 소스 필터로부터 제로개이상의 중간 필터를 경유해 다운 스트림으로 이동해, 마지막에 렌더링 필터에 도달한다. 핀은, 필터간의 데이터 전송에 대해 저레벨의 상세를 처리한다. 핀은,IPin COM 인터페이스를 지원 해, 방향 (입력 또는 출력)을 가져, 그래프내의 특정의 필터에 관련지을 수 있었던 COM 오브젝트이다. 핀은 다른 필터와의 접속 포인트를 나타낸다. 업 스트림 필터의 출력 핀은, 다운 스트림에 있는 다음의 필터의 입력 핀에 접속한다. 핀은 지원 할 수 있는 미디어 타입을 인식해, 2 개의 필터가 최초로 접속할 경우에 미디어 타입을 조정한다. 미디어 타입을 설정한 후, 핀은, 필터 그래프의 실행 시작 후에 데이터를 전송 하는 방법의 상세를 설정한다.

미디어 샘플

로컬 파일, 캡춰 카드 또는 그 외의 소스로부터 미처리의 바이트 스트림이 그래프에 입력된 후, 바이트 스트림을 미디어 샘플로 불리는 의미가 있는 단위에 해석할 필요가 있다. 소스 필터가 해석을 실행하는 경우도 있으면, 별개의 해석 필터가 해석을 실행하는 경우도 있다. DirectShow 에서는, 미디어 샘플은 IMediaSample2 를 이행 하는 COM 오브젝트에 랩핑 되고 있다. 실제의 멀티미디어 데이터에 가세해, 오브젝트에는 특정의 미디어 타입 및 동기화의 타임을 포함한 정보가 포함되어 있다. 비디오 데이터를 포함한 1 개의 미디어 샘플 오브젝트에는, 비디오 프레임 1 개 분의 데이터가 저장 된다. 오디오의 경우, 1 개의 미디어 샘플 오브젝트에 복수의 오디오 샘플의 데이터가 저장 된다. 어느 경우도, 데이터가 그래프내를 필터로부터 다음의 필터에 다운 스트림 방향으로 이동할 때, 데이터는 미디어 샘플 오브젝트의 포맷이다.

allocater

2 개의 필터가 접속 하면 와, 업 스트림 필터로부터 다운 스트림 필터에 미디어 샘플 오브젝트를 전송 하는 방법의 상세가, 2 개의 필터의 핀으로 일치해야 한다. "접속하는 " 란, 사용하는 샘플의 사이즈, 장소 및 수를 결정하는 것을 의미한다. 샘플의 사이즈는 미디어의 타입과 포맷에 따라서 달라, 버퍼의 장소는, 메인 메모리인가, 또는 비디오 캡쳐 카드등의 하드웨어 디바이스가 된다. 샘플의 생성과 관리는 allocater에 의해 처리된다. allocater는, 보통은 그것 자신이 다운 스트림 필터의 입력 핀에 의해 생성 되는 COM 오브젝트이다.

allocater의 생성, 및 접속시에 입력 핀과 출력 핀이 실행하는 조정의 상세한 것에 대하여는, 「DirectShow 필터의 개발」을 참조할것. 특정의 비디오 캡춰의 시나리오에서는, 할당하는 버퍼의 사이즈를 어플리케이션으로 지정할 필요가 있다. 그 때문의 인터페이스가 제공되고 있다. 대부분의 경우, 버퍼 할당의 자세한 것은 어플리케이션에 대해서 완전하게 투과적이다. 다만, 필터 그래프내의 데이터의 "이동 " 는 반드시 카피 조작을 수반하지 않는다. 접속 프로세스에서는, throughput를 최대화하기 위해서, 핀은 가능한 한 업 스트림 버퍼를 "재이용 " 한다.

클락

멀티미디어에 관련하는 모든 조작으로, 비디오 프레임을 적절한 레이트로 표시하거나 오디오 스트림이 비디오보다 먼저 오지 않게 하기 위해서, 샘플을 동기화하는 것이 중요하다. 따라서, DirectShow 필터 그래프에는 항상, 모든 필터에 의해 미디어 샘플의 타임 스탬프의 설정, 처리 또는 렌더링에 사용되는 클락이 1 개만 포함된다. 필터 그래프 매니저는, 클락을 선택 (또는 필요한 경우는 클락을 지정)해, 동기화 소스로서 그 클락을 이용하는 것을 모든 필터에 지시한다.


필터 그래프의 구축

전의 「필터 그래프와 그 컴퍼넌트」에서는,DirectShow 필터 그래프의 기본적인 원가요소에 대해 설명했다. 여기에서는, 멀티미디어 데이터의 처리를 시작 할 수 있도록(듯이), 이러한 원가요소를 생성 및 접속하는 방법에 대해 설명한다. 최초의 「일반적인 그래프의 구축」에서는, 필터 그래프의 구축에 관한 일반적인 방법에 대해 설명한다. 다음의 「캡춰 그래프의 구축」에서는,캡춰 그래프의 구축에 이용되는 다른 방법에 대해 설명한다. 캡춰 그래프란, DV 캠 코다, USB 카메라, TV 튜너 카드등의 비디오 캡춰 디바이스로부터의 데이터를 처리하는 필터 그래프이다.

일반적인 그래프의 구축

필터 그래프를 생성 하려면 , 반드시 최초로 필터 그래프 매니저의 인스턴스를 생성 해, 다음에 나타내도록(듯이) IGraphBuilder 인터페이스에의 포인터를 취득한다.

IGraphBuilder* pIGB;
HRESULT hr;
hr = CoCreateInstance(CLSID_FilterGraph,
NULL,
CLSCTX_INPROC_SERVER,
IID_IGraphBuilder,
(void **) &pIGB);

IGraphBuilder 인터페이스는, 그 이름대로, 필터 그래프의 메소드를 저장 한다. 이러한 메소드는, 다음과 같은 그래프 구축의 3 종류의 어프로치를 제공한다.

  1. 어플리케이션이 필터 그래프 매니저에 대해서 그래프 전체를 자동 구축하도록 지시한다.
  2. 어플리케이션과 필터 그래프 매니저가, 그래프 구축 작업을 공유한다.
  3. 어플리케이션이 각 필터를 개별적으로 추가 및 접속해, 그래프 전체를 구축한다.

어프로치 #1:필터 그래프 매니저에 의한 그래프 전체의 구축

어프로치 #1 는, AVI, MPEG, WAV, MP3 등, 일부의 기존의 포맷의 파일을 재생할 뿐(만큼)의 경우에 향하고 있다. 이 방법은, 「파일의 재생법」으로 구체적으로 나타나고 있다. DirectShow 에서는, 모니터에 비디오 데이터를 표시하거나 시스템의 스피커로부터 오디오 데이터를 흘리거나 하는 처리를 표현하는데,재생보다렌더링이라고 하는 용어가 사용되는 것이 많다. 필터 그래프 매니저에 대해서, 지정된 파일을 렌더링 할 수 있는 필터 그래프를 자동 생성 하도록 지시하기 위해서, 어플리케이션은 IGraphBuilder::RenderFile 메소드를 사용한다. 다음에, 그래프를 구축하기 위한 필터 그래프 매니저의 기본 순서에 대해 설명한다.

필터의 검색

필터 그래프를 생성 하려면 , 우선 필요한 필터를 검색해 그 인스턴스를 생성 한다. 필터의 선택 처리는, 주로, 처리하는 데이터의 미디어 타입에 근거한다. 이것은, 2 개의 필터의 핀은, 양쪽 모두를 처리할 수 있는 공통의 미디어 타입을 조정할 수 없는 한, 접속할 수 없기 때문에이다. 필터 그래프 매니저는, 다양한 파일명 확장자(extension) (. wma,. avi,. wav 등)에 관련지을 수 있었던 미디어 타입의 레지스트리를 검색하는 것으로, 데이터의 미디어 타입을 결정할 수 있다. 확장자(extension)와의 관련짓고가 존재하지 않는 경우, 필터 그래프 매니저는, 파일내의 특수한체크 바이트를 검색한다. 이러한 체크 바이트로부터, 필터 그래프 매니저는, 대응하는 DirectShow 미디어 타입을 결정해, 그 미디어 타입을 읽어내 가능한 소스 필터의 검색을 시작 할 수 있다. 내부적으로는, RenderFile 논리가 IGraphBuilder::AddSourceFilter 를 호출하는 것으로, 이 태스크를 실행한다.

모든 DirectShow 필터는, 필터의 분류, 지원 하는 미디어 타입, 필터의 메리트 등에 더해, Windows 레지스트리내의 GUID 로 일의에 식별된다. 필터 그래프 매니저는, 이 모든 정보를 검사해, 어느 필터의 인스턴스를 생성 할까를 결정한다. 필터 분류는, 필터의 일반적인 기능을 식별자, 검색 기준을 최초로 좁히기 위해서(때문에) 사용된다. 미디어 타입 정보는, 필터가 입력으로서 받아들일 수가 있는 데이터의 종류, 및 그래프내의 다음의 필터에 출력으로서 제공할 수 있는 데이터의 종류를 기술한다. 메리트의 값은, 그래프의 자동 구축 처리중에 필터가 고려되어야할 것인가 어떤가를 나타낸다. 시스템 위에의 2 개의 필터가 닮은 미디어 타입 정보를 가지는 경우, 필터 그래프 매니저는 메리트값의 비싼 (분)편의 필터를 선택한다(일부의 필터는, 특수한 필터 그래프에서만의 사용을 목적으로 하고 있으므로, 메리트값을 의도적으로 낮게 하고 있다. 그러한 필터는, 어플리케이션에 의해 개별적으로 그래프에 추가할 필요가 있다).

레지스트리를 검색하려면 , 필터 그래프 매니저는 DirectShow 필터 맵퍼 오브젝트의 인스턴스를 생성 해,IFilterMapper2::EnumMatchingFilters 메소드를 호출해, 검색을 실행한다. 이 메소드는, 분류나 미디어 타입 마다 DirectShow 필터 (디코더등의 하드웨어 디바이스와 같이)를 열거할 수 있어 검색 기준에 일치하는 모든 필터 및 하드웨어 디바이스 또는 그 한편에 대한 모니카를 포함한 표준 COM IEnumMoniker 오브젝트를 돌려준다(COM 모니카를 사용하면(자), 이 메소드는, 오브젝트의 인스턴스를 실제로 생성 하지 않아도 오브젝트를 문의하거나 패스를 생성 하거나 하드웨어 디바이스 등, 실제는 COM 오브젝트는 아닌 것을 열거하거나 할 수가 있다).

그래프에의 필터의 추가

지정된 타입의 파일을 읽어낼 수가 있는 소스 필터를 모니카가 찾아내면(자), 필터 그래프 매니저는 CoCreateInstance 를 사용해, 돌려주어진 GUID 를 사용하는 것으로 필터의 인스턴스를 생성 한다. 대부분의 파일 타입에서는, 소스 필터는 파일 소스 (비동기) 필터가 된다. 다음에, 필터 그래프 매니저는,IGraphBuilder::AddFilter 메소드를 호출해 필터 그래프에 필터를 추가한다. 필터가 그래프에 추가되었던 것이 필터에 통지되면(자), 읽어내는 파일의 타입용으로 구성된 출력 핀을 1 개 또는 복수 생성 한다. 핀이 생성 되면(자), 필터 그래프 매니저는, 각 핀이 지원 하는 미디어 타입을 조사해 다음에 그 입력 핀의 미디어 타입을 받아들이고 가능한 필터를 레지스트리로 다시 찾는다. 적합하는 필터가 발견되면(자), 그 필터를 그래프에 추가한다.

필터의 접속

다운 스트림 필터의 추가시에, 필터는 핀을 구성해, 전의 (업 스트림) 필터에 접속할 준비가 완료한다. 필터 그래프 매니저는, 각 필터에 문의해 적절한 핀을 결정해,IGraphBuilder::Connect 메소드를 호출해, 업 스트림 필터의 출력 핀을 다운 스트림 필터의 입력 핀에 접속한다. 다음에, 2 개의 핀은 조정 프로세스를 실행해 데이터의 미디어 타입을 결정해, 미디어 샘플 오브젝트용의 메모리를 할당하는 오브젝트, 및 샘플의 데이터를 보관 유지하는 버퍼는 어느 쪽의 핀이 제공할까를 결정한다. 핀 접속 프로세스의 상세한 것에 대하여는, 「필터 개발자를 위한 DirectShow 아키텍쳐」로 해설된다.

그래프의 완성

2 개의 핀을 접속하면(자), 필터 그래프 매니저는, 새로운 필터의 출력 핀으로 지원 되는 미디어 타입을 조사해 그 미디어 타입을 처리 가능한 필터를 검색한다. 필요한 필터가 모두 그래프에 추가될 때까지, 같은 프로세스가 반복해진다. 파일 재생 그래프에서는, 2 번째의 필터는 보통, 퍼서 또는 스플리터 필터가 된다. 이것은, AVI 나 MPEG 등 미가공의 데이터 스트림을 읽어내, 오디오 스트림과 비디오 스트림에 분할하는 필터이며, 스트림 마다 출력 핀이 생성 된다. 어느 쪽인가의 스트림의 데이터가 압축되고 있는 경우, 각 스트림의 다음의 필터는 데콘프렛사피르타가 되어, 그 후에 렌더링 필터가 계속된다.

그래프가 구축되면(자), 어플리케이션은, 필터 그래프 매니저로부터 IMediaControl 인터페이스를 취득해,Run 메소드를 호출해 파일 재생을 시작 하는 것만으로 좋다.

어프로치 #2:어플리케이션과 필터 그래프 매니저에 의한 그래프 구축 작업의 공유

필터 그래프로 단순하게 파일을 렌더링 하는 이외를 할 필요가 있는 경우, 적어도 그래프 구축 작업의 일부는, 어플리케이션측에서 실행할 필요가 있다. 예를 들어, AVI 파일을 MPEG 파일로 변환하는 필터 그래프를 구축하고 있는 경우,IGraphBuilder::RenderFile 를 호출하는 것으로, 계속 필터 그래프 매니저에 AVI 재생 그래프를 생성 시킬 수도 있지만, 출력을 모니터와 스피커는 아니고 MPEG 파일에 보내기 위해서(때문에), 나중에 그래프를 수정할 필요가 있다. 이것에 수반해, 비디오 및 오디오 렌더링 필터의 접속을 해제해 삭제해 (IGraphBuilder::Disconnect 및 IGraphBuilder::RemoveFilter 를 사용), MPEG 비디오 및 오디오 압력 필터, MPEG Multiplexer 필터, 및 파일 라이터 필터와 옮겨놓을 필요가 있다.

또, 미디어 타입을 MPEG 압력이 받아들이고 가능한 타입으로 변환하기 위해서(때문에), 중간 필터를 추가할 필요가 있다. 어플리케이션에는, 이 중간 필터를 직접 추가하는 방법과IGraphBuilder::Connect 메소드를 사용하는 방법이 있다. 이 메소드를 호출하면, 필터 그래프 매니저는, 우선 필터에 직접 접속하려고 시도한다. 거기서 미디어 타입의 조정이 붙지 않는 경우, 필터 그래프 매니저는 중간 필터를 검색한다. 필터 그래프 매니저가 특정의 미디어 타입을 처리 가능한 필터를 검색 하면나무는 반드시, 그래프에 이미 추가되고 있는 필터를 최초로 시험한다. 필터 그래프 매니저가 중간 필터를 삽입하지 않게 하려면 ,IGraphBuilder::ConnectDirect 메소드를 사용한다.

전의 예에서는, 어플리케이션은 그래프의 다운 스트림 부분을 구축했다. 다른 시나리오에서는, 어플리케이션은 그래프의 업 스트림 부분을 구축해야 하는 것이 있다. 그 경우, 수동으로 추가해야 하는 필터를 한 번 추가해 접속하면(자),IGraphBuilder::Render 메소드를 사용해, 지정된 출력 핀으로부터 자동적으로 그래프를 완성하도록(듯이) 필터 그래프 매니저에 지시할 수 있다. 오디오 핀과 비디오 핀 등, 필터에 2 개의 출력 핀이 있는 경우, 어플리케이션은 각 핀에 대해서 Render 를 호출할 필요가 있다.

어프로치 #3:어플리케이션 자체에 의한 그래프 전체의 구축

어느 시나리오에서는, 어플리케이션이 각 필터를 개별적으로 추가 및 접속해, 그래프 전체를 구축해야 하는 것이 있다. 이 경우는, 어느 필터를 그래프에 추가해야 할까가 명확하게 판명하고 있는 것이 많기 때문에, Filter Mapper 오브젝트를 사용해 필터를 찾아낼 필요는 없다. IGraphBuilder::AddFilter 메소드를 사용해 각 필터를 그래프에 추가해, Connect 또는 ConnectDirect 의 어느 쪽인지를 사용해 필터를 접속하는 것만으로 있다.

캡춰 그래프의 구축

독립계 하드웨어 vender (IHV) 및 가전 메이커에 의해 제공되는 캡춰 디바이스가 다방면에 걸치기 (위해)때문에, 비디오 캡춰 그래프의 구축 프로세스는 꽤 복잡하게 될 가능성이 있다. 어플리케이션 개발자의 부담을 경감하기 위해서, DirectShow 는 별로 Capture Graph Builder 라고 하는 오브젝트를 준비해 있다. 비디오 캡춰 어플리케이션은, 이 오브젝트의 인스턴스를 생성 해, 그 ICaptureGraphBuilder2 인터페이스 메소드를 사용해, 필터 그래프를 구축한다. 그래프 구축의 일반 원칙을 이해하고 있으면, 캡춰 그래프의 구축 작업도 거의 같은 방법으로 실시할 수 있는 것을 알 수 있다. 상세한 것에 대하여는, 「캡춰 어플리케이션의 쓰는 법」을 참조할것.


필터 그래프의 데이터 플로우

여기에서는, Microsoft® DirectShow® 필터 그래프에 있어서의 데이터의 흐름에 대해 설명한다. 내용은 다음과 같다.

  • 샘플과 버퍼
  • 송신의 샘플
  • 정지, 포즈, 및 실행
  • 라이브 캡춰
  • 상세한 것에 대하여의 참조처

샘플과 버퍼

2 개의 핀을 접속 하면, 데이터는 출력 핀으로부터 입력 핀에 이동한다. 출력 핀은 데이터를 송신해, 입력 핀은 데이터를 수신한다. 출력으로부터 입력으로 하는 데이터 플로우의 방향은 다운 스트림으로 불려 그 역의 방향은 업 스트림으로 불린다.

2 개의 핀의 사이를 이동하는 데이터의 타입은, 핀의 이행에 따라서 다르다. 가장 일반적인 케이스에서는, 핀은 메인 메모리에 저장 된 미디어 데이터를 사용해 동작한다. 다만, 이외의 배치도 가능하다. 예를 들어, 2 개의 필터가 비디오 하드웨어를 제어하는 경우는, 하드웨어가 모든 비디오 데이터를 처리해, 핀은 제어 정보를 교환한다. 데이터의 타입, 및 핀의 사이를 데이터가 이동하는 방법은, 전송으로 불린다. 여기에서는, 미디어 데이터가 메인 메모리에 저장 되고 있는 로컬 메모리 전송으로 불리는 전송에 대해 설명한다.

로컬 메모리 전송에서는, 데이터는 미디어 샘플로 불리는 압축된 개별의 오브젝트이다. 미디어 샘플은, 할당할 수 있었던 메모리 버퍼에의 포인터를 저장 하는 COM 오브젝트이다. 미디어 샘플은 IMediaSample 인터페이스를 지원 해,IMediaSample2 인터페이스를 지원 하는 일도 가능하다.

버퍼의 할당과 미디어 샘플의 생성을 실시하는 이제(벌써) 1 개의 COM 오브젝트가 메모리 allocater이다. 접속시, allocater는 버퍼를 위한 메모리를 예약한다. 한층 더 allocater는 미디어 샘플의 집합을 생성 해, 메모리 블록내의 주소에의 포인터를 각 샘플에 건네준다. 버퍼가 해방될 때까지, allocater는 어느 샘플이 사용 가능한가를 나타내는 리스트를 유지한다. 필터는, 새로운 샘플이 필요하게 되면(자), allocater에 샘플을 요구한다. 샘플은, 처리된 후 리스트에 되돌려진다.

이 메카니즘에서는 필터가 같은 버퍼를 재이용하기 위해(때문에), 메모리 할당의 양이 줄어든다. 또, allocater는 사용 가능한 샘플의 리스트를 보관 유지하고 있기 (위해)때문에, 아직 처리가 끝나지 않은 데이터가 필터에 의해 잘못해 오버라이드(override) 되는 것을 방지할 수 있다. 게다가 그래프내의 데이터 이동을 효율적으로 실행할 수 있다. 출력 핀은, 샘플을 송신 하면 와, 샘플의 IMediaSample 인터페이스에의 포인터를 건네준다. 데이터를 카피할 필요는 없다.

다음의 그림은, allocater, 미디어 샘플, 및 필터의 관계를 나타내고 있다.

접속된 복수의 핀이 1 개의 메모리 allocater를 공유한다. 필터는 입력용과 출력용으로 다른 allocater를 사용할 수 있다. 이것은, 데콘프렛사피르타와 같이, 데이터를 전개하는 필터로 일반적이다. 출력이 입력보다 크지 않은 경우는, 필터는 데이터를 새로운 버퍼로 이동하지 않고, 원의 장소에서 처리할 수 있다. 그 경우, 2 개(살) 이상의 핀 접속으로 1 개의 allocater를 공유할 수 있다.

송신의 샘플

로컬 메모리를 지원 하는 입력 핀은 IMemInputPin 인터페이스를 공개한다. 출력 핀은, 입력 핀에 대해서 IMemInputPin::Receive 메소드를 호출하는 것에 의해, 샘플을 송신한다. 입력 핀은 다음의 몇개의 처리를 실행한다.

  • 샘플을 거부한다.
  • 샘플의 처리가 완료할 때까지 블록 한다.
  • 즉시 돌아와, 다른 thread의 샘플을 처리한다.

IMemInputPin::ReceiveCanBlock 메소드는, 입력 핀이 Receive 의 호출을 블록 할지 어떨지를 판별한다. 출력 핀은 이 메소드를 호출해, 적절한 thread 처리 방법을 결정할 수 있다. 워커 thread를 생성 해, 다른 작업을 실행하면서 백그라운드에서 샘플을 송신할 수 있는 필터도 있다. 혹은, 다운 스트림 필터가 다음의 샘플을 받을 준비를 할 수 있을 때까지 블록 하는 필터도 있다.

또, 한 번에 복수의 샘플을 송신하는 IMemInputPin::ReceiveMultiple 라고 하는 메소드도 있다. 이 메소드는 Receive 와 같게 동작하지만, 샘플의 배열을 처리한다.

정지, 포즈, 및 실행

필터에는, 정지, 포즈, 및 실행중이라고 하는 3 개 상태가 있다. 대부분의 필터에서는, 포즈와 실행중은 동일하다.

  • 정지상태태 때, 필터는 샘플을 처리하지 않는다. 업 스트림 필터로부터의 샘플은 거부된다.
  • 포즈 또는 실행중 때, 필터는 샘플을 받아 처리한다. 소스 필터는, 새로운 샘플을 생성해, 다운 스트림에 송신한다.

렌더링 필터는 예외이다. 렌더링 필터가 정지상태태로부터 포즈 상태로 옮기는 경우, 미디어 샘플을 1 개 받은 시점에서 이행이 완료한다. 그 시점에서, 렌더링 필터는 샘플을 보류해,Receive 의 호출을 블록 한다. 비디오 렌더러는 샘플을 정지 프레임으로서 드로잉(Drawing) 한다. 오디오 렌더러는 실행 상태가 되고 나서 샘플을 렌더링 한다. 오디오에서는 "정지 프레임 " 에 상당하는 것은 존재하지 않는다. 어느 경우도, 렌더러는 포즈로부터 실행중에 바뀔 때까지 다음의 샘플을 받지 않는다.

필터 그래프 매니저는 필터 그래프 전체 상태를 제어한다. 유효한 상태 이행으로서 정지와 포즈, 및 포즈와 실행중의 사이의 이행이 있다. 정지와 실행중의 사이의 이행은, 포즈를 경유할 필요가 있다. 정지상태태의 그래프에 대해서 IMediaControl::Run , 또는 실행중의 그래프에 대해서 IMediaControl::Stop 를 호출하면, 필터 그래프 매니저는 최초로 그래프를 포즈 한다.

필터 그래프가 정지로부터 포즈로 옮기는 경우, 다음의 순서가 실행된다.

  • 필터 그래프 매니저는, 렌더링 필터로부터 시작 해, 업 스톰의 각 필터에 대해서 IMediaFilter::Pause 를 호출한다.
  • 각 필터는, 포즈에 바뀌면(자) 업 스트림 필터로부터 샘플을 받을 수가 있게 된다. 각 필터는 다운 스트림에 샘플을 안전하게 송신할 수 있다 (다운 스트림 필터도 포즈 하고 있기 (위해)때문에).
  • 소스 필터는 마지막에 포즈 한다. 그 시점에서, 소스 필터는 샘플의 송신을 시작 한다.
  • 샘플이 다운 스트림으로 이동하는 것에 따라, 중간 필터가 그러한 샘플을 처리한다.
  • 최초의 샘플이 렌더러에 도착하면(자) 렌더러 상태 이행이 완료해, 렌더러는 블록 한다.

이러한 이벤트가 완료할 때까지의 시간은 일정은 아니다. 보통은 길게 걸리지 않지만, 압축 해제를 필요로 하는 소스의 경우는 특히 지연이 현저한 일이 있다. 다만, 그래프는 포즈 상태가 종료 하면, 즉시 데이터의 렌더링을 시작 할 수 있다. 따라서, 그래프의 포즈에는 데이터를 "삽입 " 하는 효과가 있다. 어플리케이션에서는, 이것을 미리 실행해, 다음에 유저로부터의 커멘드에 응해 재빠르게 그래프를 실행중 상태로 전환할 수가 있다.

라이브 캡춰

라이브 캡춰 필터는, 다른 소스 필터와 달리, 포즈 상태 때에 샘플을 송신하지 않는다. pause 커멘드와 run 커멘드의 사이에 어느 정도의 시간이 경과할까는 특정할 수 없다. pause 커멘드의 시점에서 송신된 샘플은 최신이 아닐 가능성이 있다. 유저가 run 커멘드를 발행하기까지 1 시간이 경과했을 경우, 1 시간전에 캡춰 한 비디오 프레임은 아니고 새로운 비디오 프레임을 그래프로 생성할 필요가 있다. 그 때문에, 캡춰 필터는 실행중 때 만일 수 있는 샘플을 송신한다.

다만, 이 동작에 의해 그래프에 문제가 발생하는 경우가 있다. 필터 그래프 매니저는, 모든 필터가 포즈 할 때까지 대기하고 나서 그래프를 실행한다. 그러나, 렌더러는 캡춰 필터로부터의 샘플을 대기하기 위해(때문에), 이 이행은 완료하지 않는다. 이 문제를 회피하기 위해서, 캡춰 필터의 IMediaFilter::GetState 메소드는 VFW_S_CANT_CUE 를 돌려준다. 이 귀가 코드는 필터 그래프 매니저에 대해서, 캡춰 필터가 샘플을 송신하고 있지 않는 것을 알려 렌더러를 대기하지 않게 지시한다.

상세한 것에 대하여의 참조처

데이터 플로우의 상세한 것에 대하여는, 「필터 개발자가 사용하는 데이터 플로우」를 참조할것.


DirectShow 에서의 이벤트 통지

여기에서는, Microsoft® DirectShow® 의 필터 그래프로 어떻게 이벤트가 발생하는지, 및 어플리케이션이 어떻게 이벤트 통지를 취득해, 거기에 응답할까에 임해서 설명한다. 내용은 다음과 같다.

  • 이벤트 통지의 개요
  • 이벤트의 취득
  • 이벤트 발생시의 확인

이벤트 통지의 개요

필터는,이벤트 통지를 송신하는 것에 의해, 필터 그래프 매니저에 이벤트를 통지한다. 이벤트는, 스트림의 마지막과 같이 예측할 수 있는 경우도 있으면, 스트림의 렌더링 실패와 같은 에러의 경우도 있다. 필터 그래프 매니저 자신이 처리하는 필터 이벤트도 있으면, 어플리케이션이 처리하는 필터 이벤트도 있다. 필터 그래프 매니저는, 필터 이벤트를 처리하지 않는 경우, 이벤트 통지를 큐에 넣는다. 필터 그래프는 어플리케이션에 대한 독자적인 이벤트 통지를 큐에 넣을 수도 있다.

어플리케이션은 큐로부터 이벤트를 취득해, 이벤트의 타입에 근거해 응답한다. 그 때문에, DirectShow 에서의 이벤트 통지는 Microsoft® Windows® 의 멧세이지큐잉의 구조를 닮아 있다. 어플리케이션은, 특정의 이벤트 타입에 대한 필터 그래프 매니저의 디폴트 동작을 취소할 수도 있다. 이 경우, 필터 그래프 매니저는 이벤트를 직접 큐에 넣어 어플리케이션에 이벤트를 처리시킬 수가 있다.

이 메카니즘에 의해 다음 일이 가능하게 된다.

  • 필터 그래프 매니저가 어플리케이션과 통신한다.
  • 필터가 어플리케이션 및 필터 그래프 매니저의 양쪽 모두와 통신한다.
  • 어플리케이션이 이벤트 처리와 관계되는 정도를 결정한다.

이벤트의 취득

필터 그래프 매니저는 이벤트 통지를 지원 하는 3 개의 인터페이스를 공개하고 있다.

  • IMediaEventSink 는, 필터가 이벤트를 송신하기 위한 메소드를 포함한다.
  • IMediaEvent 는, 어플리케이션이 이벤트를 취득하기 위한 메소드를 포함한다.
  • IMediaEventEx 는,IMediaEvent 인터페이스를 계승해, 확장한다.

필터는, 필터 그래프 매니저에 대한 IMediaEventSink::Notify 메소드를 호출하는 것에 의해, 이벤트 통지를 송신한다. 이벤트 통지는, 이벤트의 타입을 정의하는 이벤트 코드와 부가 정보를 제공하는 2 개의 DWORD 파라미터로 구성된다. 이벤트 코드에 응해, 파라미터에는 포인터, 귀가 코드, 기준 타임, 또는 그 외의 정보가 포함된다. 모든 이벤트 코드와 파라미터의 일람에 대해서는, 「이벤트 통지 코드」를 참조할것.

큐로부터 이벤트를 취득하기 위해서, 어플리케이션은 필터 그래프 매니저에 대해서 IMediaEvent::GetEvent 메소드를 호출한다. 이 메소드는, 돌려주는 이벤트가 발생할 때까지, 또는 지정된 시간이 경과할 때까지 블록 한다. 큐내에 이벤트가 있어, 메소드가 이벤트 코드와 2 개의 이벤트 파라미터를 돌려주었다고 한다. 어플리케이션은,GetEvent 를 호출한 후 반드시 IMediaEvent::FreeEventParams 메소드를 호출해, 이벤트 파라미터에 관련지을 수 있었던 리소스를 해방할 필요가 있다. 예를 들어, 파라미터는, 필터 그래프에 의해 할당할 수 있었던 BSTR 값인 경우가 있다.

다음의 코드예는, 큐로부터 이벤트를 취득하는 방법의 개요를 나타내고 있다.

long evCode, param1, param2;
HRESULT hr;
while (hr = pEvent->GetEvent(&evCode, &param1, &param2, 0), SUCCEEDED(hr))
{
    switch(evCode)
    {
        // 처리하는 각 타입의 이벤트에 대해서
        // 어플리케이션으로 정의한 함수를 호출한다.
    }

hr = pEvent->FreeEventParams(evCode, param1, param2);
}

이벤트에 대한 필터 그래프 매니저의 디폴트 처리를 오버라이드(override) 하려면 , 파라미터에 이벤트 코드를 지정한 IMediaEvent::CancelDefaultHandling 메소드를 호출한다. 디폴트 처리는,IMediaEvent::RestoreDefaultHandling 메소드를 호출하는 것에 의해 복원할 수 있다. 필터 그래프가 지정된 이벤트 코드에 대해서 디폴트 처리를 실행하지 않는 경우는, 이러한 메소드를 호출해도 효과는 없다.

이벤트 발생시의 확인

전의 「이벤트의 취득」으로 설명한 것처럼 큐로부터 이벤트 통지를 취득하는 것에 가세해, 어플리케이션에는 이벤트가 큐로 대기하고 있는 경우에 그것을 검출할 방법이 필요하다. 필터 그래프 매니저는 그 때문에(위해) 2 개의 방법을 제공하고 있다.

  • 윈도우 통지를 사용하는 경우, 필터 그래프 매니저는, 새로운 이벤트가 있을지 어떨지에 관계없이 어플리케이션 윈도우에 Windows 메세지를 송신한다.
  • 이벤트 핸들러를 사용하는 경우, 어플리케이션은, Windows 의 수동 리셋 이벤트의 핸들을 취득한다. 필터 그래프 매니저는, 큐에 이벤트 통지가 있을 때는 수동 리셋 이벤트를 송신해, 큐가 비우면(자) 그 이벤트를 리셋 한다.

이하의 항목으로 각 테크닉에 대해 설명한다.

  • 윈도우 통지
  • 이벤트 핸들

윈도우 통지

윈도우 통지를 셋업 하려면 ,IMediaEventEx::SetNotifyWindow 메소드를 호출해, 프라이빗 메세지를 지정한다. 어플리케이션에서는, WM_APP 로부터 0xBFFF 까지의 범위의 메세지 번호를 프라이빗 메세지로서 사용할 수 있다. 필터 그래프 매니저는, 새로운 이벤트 통지를 큐에 넣으면(자), 지정된 윈도우에 이 메세지를 송신한다. 어플리케이션은 윈도우의 메시지 루프내로부터 메세지에 응답한다.

다음의 코드예는, 통지 윈도우의 설정 방법법을 나타내고 있다.

#define WM_GRAPHNOTIFY WM_APP + 1   // 프라이빗 메세지.

pEvent->SetNotifyWindow((OAHWND) g_hwnd, WM_GRAPHNOTIFY, 0);

메세지는 보통의 Windows 메세지이며, DirectShow 의 이벤트 통지 큐로부터는 독립해 송신된다. 이 방법의 이점은, 대부분의 어플리케이션이 이미 메시지 루프를 이행 하고 있기 (위해)때문에, 많은 추가 작업을 필요로 하지 않고 DirectShow 의 이벤트 처리를 짜넣을 수 있는 점이다.

다음의 코드예는, 통지 메세지에 응답하는 방법의 개요를 나타내고 있다. 완전한 예에 대해서는, 「이벤트에의 응답」을 참조할것.

LRESULT CALLBACK WindowProc( HWND hwnd, UINT msg, UINT wParam, LONG lParam)
{
    switch (msg)
    {
        case WM_GRAPHNOTIFY:
            HandleEvent();  // 어플리케이션 정의의 함수.
            break;

        // 여기서 다른 Windows 메세지도 처리한다.
    }
    return (DefWindowProc(hwnd, msg, wParam, lParam));
}

이벤트 통지와 메시지 루프는 양쪽 모두 비동기이기 (위해)때문에, 어플리케이션이 메세지에 응답 하면 와까지, 복수의 이벤트가 큐에 들어가 있는 일이 있다. 또, 이벤트가 무효가 되었을 때는 큐로부터 이벤트가 클리어 되는 일이 있다. 따라서, 이벤트 처리 코드에서는, 큐가 하늘인 것을 나타내는 에러 코드가 돌려주어질 때까지 GetEvent 를 호출하는 것.

이벤트 핸들

필터 그래프는, 이벤트 큐 상태를 나타내는 수동 리셋 이벤트를 유지한다. 큐에 보류 상태의 이벤트 통지가 포함되어 있는 경우, 필터 그래프는 수동 리셋 이벤트를 송신한다. 큐가 하늘의 경우는,IMediaEvent::GetEvent 메소드를 호출하면 이벤트가 리셋 된다. 어플리케이션은 이 이벤트를 사용해 큐 상태를 확인할 수 있다.

주 : 여기서 용어에 대해 혼란하지 않는 것. 수동 리셋 이벤트는, Windows 의 CreateEvent 함수에 의해 생성 되는 타입의 이벤트이며, DirectShow 로 정의되고 있는 이벤트 통지와는 무관계하다.

IMediaEvent::GetEventHandle 메소드는, 수동 리셋 이벤트의 핸들을 취득한다. WaitForMultipleObjects 등의 함수를 호출해, 이벤트가 통지제가 될 때까지 대기하는 것. 이벤트가 통지제가 되면 IMediaEvent::GetEvent 메소드를 호출해 이벤트 통지를 취득한다.

다음의 코드예는, 이 처리 방법을 나타내고 있다. 이벤트 핸들을 취득해, 이벤트가 통지제가 되는 것을 100 밀리 세컨드 간격으로 대기한다. 이벤트가 통지제가 되면(자),GetEvent 를 호출해 이벤트 코드와 이벤트 파라미터를 콘솔 윈도우에 출력한다. 재생이 완료한 것을 나타내는 EC_COMPLETE 이벤트가 발생 하면, 루프가 종료한다.

HANDLE  hEvent;
long evCode, param1, param2;
BOOLEAN bDone = FALSE;
HRESULT hr = S_OK;

hr = pEvent->GetEventHandle((OAEVENT*) &hEv);

while(! bDone)
{
    if (WAIT_OBJECT_0 == WaitForSingleObject(hEvent, 100))
    {
 while (hr = pEvent->GetEvent(&evCode, &param1, &param2, 0), SUCCEEDED(hr))
        {
            printf("Event code: %#04x\n    Params: %d, %d\n", evCode, param1, param2);
hr = pEvent->FreeEventParams(evCode, param1, param2);
            bDone = (EC_COMPLETE == evCode);
        }
    }
}

필터 그래프가 적절한 때에 이벤트를 자동적으로 설정 또는 리셋 하므로, 어플리케이션으로 이벤트의 설정 또는 리셋을 실시해서는 안된다. 게다가 필터 그래프를 해방 하면 필터 그래프는 이벤트 핸들을 닫는다. 그 때문에, 그 후는 이벤트 핸들을 사용하지 않는 것.


하드웨어 디바이스가 필터 그래프에 참가하는 방법

래퍼 필터

Microsoft® DirectShow® 는 모두 유저 모드 소프트웨어 컴퍼넌트이다. DirectShow 필터 그래프에 참가하는 캡춰 카드, TV 튜너, 하드웨어 디코더, 사운드 카드와 같은 커넬 모드 하드웨어 디바이스는 필터 그래프내에서는 유저 모드 필터로서 표현되지 않으면 안 된다. 이 기능은 DirectShow 가 제공하는 특수한 「래퍼 필터」가 복수의 타입의 디바이스에 대해서 가고 있다. 이러한 필터는 오디오 캡춰 필터, VFW 캡춰 필터, TV 튜너 필터, 아날로그 비디오 크로스바 필터 그리고, TV 오디오 필터를 포함한다. 이러한 래퍼 필터에 가세해, DirectShow 는 KsProxy 필터를 제공하는, 이것은 임의의 타입의 Windows Driver Model® (WDM) 스트리밍 디바이스를 표현해, 독립계 하드웨어 벤더 (IHV)의 커스텀 기능 지원용으로 확장 가능하다. 이것은 Ksproxy 플러그 인 에 의해 행해져 이 플러그 인은 KsProxy 에 의해 집성 되는 COM 오브젝트이다.

래퍼 필터는 지원 하는 COM 인터페이스에 의해 동작해, 그 인터페이스는 예상되는 디바이스의 성능을 표현한다. 어플리케이션 유저는 그 인터페이스를 사용해 필터에 있는 있고는 필터로부터 정보를 건네준다. 그 필터는 인터페이스의 호출을 디바이스 드라이버가 이해 가능한 정보로 번역하는, 다음에 필터는 커넬 모드의 디바이스에 혹은 디바이스로부터 그 정보를 건네준다. (KsProxy 는 같은 방법으로 동작한다, 그러나 필터 그래프에 공개하는 인터페이스는 표현하는 디바이스에 따라서 다르다) VfW 후캐프체피르타나 오디오 캡춰 필터와 같은 필터에 대해서는, 그 인터페이스는 확장할 수 없다. TV 튜너 필터와 아날로그 비디오 크로스바와 TYV 오디오 필터는 KsProxy 를 베이스로 하고 있지 않지만, IKSPropertySet 인터페이스를 지원 하는, 이것은 커스텀 프로퍼티 세트를 1 개의 인터페이스 경유로 취급하는 범용의 방법이다.

어플리케이션 개발자에게 있어, 유저 모드 필터로서의 랩핑 하드웨어 디바이스에 관한 원칙은, 어플리케이션에서는 그 외 모든 DirectShow 필터를 제어하는 것과 같은 방법으로 디바이스를 제어 하면 말하는 것이다. 어플리케이션의 옆에서 특별한 프로그래밍은 필요없고, 커넬 모드 디바이스와의 통신에 관계하는 모든 자세한 것은 필터 자신중에 캡슐화된다.

Video for Windows 디바이스

초기의 Video for Windows (VfW) 캡춰 카드를 지원 하기 위해서, DirectShow 는 VFW 캡춰 필터를 제공한다. 타겟 시스템에 VfW 카드가 있는 경우는, DirectShow 의시스템 디바이스 열거자를 사용해 검출할 수 있다. 열거자는, 그래프에 VfW 캡춰 필터를 추가해, 추가한 필터가 검출된 카드로 관련짓기 위해서(때문에)도 사용한다. 그 후는 필터 그래프의 나머지의 부분을 보통의 방법으로 생성 할 수 있다. 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것.

오디오 캡춰와 믹싱 디바이스 (사운드 카드)

최근의 사운드 카드는, 마이크 및 그 외의 타입의 디바이스용의 입력 잭을 갖추고 있다. 또, 개개의 입력 마다 볼륨, 고음역, 및 저음역을 제어하는 온보드의 믹싱 능력을 갖추고 있는 것이 일반적이다. DirectShow 에서는, 사운드 카드의 입력과 믹서는오디오 캡춰 필터에 랩핑 되고 있다. 로컬 시스템의 각 사운드 카드는,시스템 디바이스 열거자를 사용해 검출할 수 있다. 이것에 대해서는, 「디바이스와 필터의 열거」로 설명하고 있다. 시스템의 사운드 카드를 표시하려면 , SDK 와 함께 인스톨 되고 있는 GraphEdit 를 열어, 오 디 캡춰 소스의 카테고리로부터 선택한다. 여기에 표시되는 필터는, 각각이 오디오 캡춰 필터의 별개의 인스턴스이다.

WDM 스트리밍 디바이스

최근의 하드웨어 디코더와 캡춰 카드는, Windows Driver Model (WDM) 규격에 적합하고 있다. 이러한 디바이스는, VfW 디바이스에 비해 고기능이며, Windows NT/Windows 2000 와 Windows 98/Me 간의 이식이 가능하다. WDM 비디오 캡쳐 카드는, VfW 에서는 이용할 수 없는 기능을 지원 할 수가 있어 캡춰 포맷 열거, 프로그램에 의한 비디오 파라미터 (색상이나 휘도등)의 제어 , 프로그램에 의한 입력 선택, TVTuner 지원, VBI 지원등이 가능하다.

WDM 스트리밍 디바이스를 지원 하기 위해서, DirectShow 는 KsProxy (ksproxy.ax)로 불리는 필터를 제공하고 있다. KsProxy 는, 그 기능의 다양함으로부터 "아미 나이프 필터 " 로 불려 왔다. 또, 기초가 되는 커넬 모드 드라이버의 능력에 응해, 필터 전체 및 개개의 핀으로 지원 되는 핀과 인터페이스의 수가 다르기 (위해)때문에, "카멜레온 필터 " 라고도 불린다. 필터 그래프에 "KsProxy" 라는 이름으로 표시될 것은 없고, 항상, 레지스트리로 발견된, 디바이스의 "프렌들리" 명이 되어 있다. 이 이름은 원래 드라이버의 . inf 파일로 지정되고 있는 이름이다. 시스템에 WDM 디바이스가 있는 경우는, GraphEdit 유틸리티 프로그램을 열어,[Graph] 의 [Insert Filters] 를 클릭해, WDM 스트리밍 디바이스의 노드까지 아래에 스크롤 한다. 시스템의 WDM 카드가 1 개 밖에 없는 경우에서도, 그 카드로 복수의 디바이스가 포함되는 일이 있다. 각 디바이스는 별개의 필터로서 나타내져 각 필터는 실제로는 KsProxy 이다.

어플리케이션으로 시스템 디바이스 열거자를 사용해, 프로그램에 의해 타겟 시스템의 WDM 데바이스모니카 (예를 들어 TV 튜너 카드)를 찾는 경우, KsProxy (드라이버에 의해 정의된 "프렌들리명 " 를 사용하고 있다)는, 후속의 BindToObject 메소드의 호출로 인스턴스화 된다. KsProxy 는, 모든 종류의 WDM 오디오 디바이스 또는 비디오 디바이스를 나타낼 수가 있지만, 나타내는 디바이스의 종류를 사전에 알 수 없다. 그 때문에, 지원 되고 있는 프로퍼티 세트를 드라이버에 문의할 필요가 있다. 프로퍼티 세트는, WDM 스트림 클래스 드라이버 및 MPEG-2 소프트웨어 디코더등의 일부의 유저 모드 필터에 의해 사용되는 데이터 구조의 콜렉션이다. 다음에, KsProxy 는 자기 자신을 동적으로 구성해, 적절한 인터페이스를 필터 그래프와 어플리케이션에 공개한다. 어플리케이션 및 그 외의 필터가 이러한 인터페이스를 호출하면, KsProxy 는 메소드 파라미터를 프로퍼티 세트로 변환해 드라이버에 송신한다. IHV 는 플러그 인을 제공하는 것에 의해 KsProxy 를 확장할 수 있다. 플러그 인은 디바이스의 특수한 능력을 공개하는 벤더 독자적인 인터페이스이다. 이것들 모든 자세한 것은 어플리케이션에 대해서 은폐 되고 있다. 어플리케이션에서는, KsProxy 를 다른 DirectShow 유저 모드 필터와 같이 사용해, WDM 디바이스로부터 이벤트를 받아, WDM 디바이스의 이벤트를 제어한다.

커넬 스트리밍

WDM 디바이스는 커넬 스트리밍 모델을 지원 하고 있다. 커넬 스트리밍 모델을 사용 하면, 데이터를 유저 모드에 건네주는 일 없이, 완전하게 커넬 모드로 직접 스트리밍 할 수가 있다. 커넬 모드와 유저 모드의 사이에 데이터를 건네주는 조작은 많은 컴퓨터 자원을 소비한다. 커넬 스트리밍에 의해, 호스트 CPU 에 부하를 걸지 않고 고속의 bit rate를 이용할 수 있다. WDM 베이스의 필터는 커넬 스트리밍을 사용해, 시스템의 메인 메모리에 데이터를 카피하는 일 없이, 멀티미디어 데이터를 (그것이 같은 카드여도 아니어도) 있는 하드웨어 디바이스로부터 다른 디바이스에 직접 건네준다.

어플리케이션측에서 보면(자), 그래프내의 멀티미디어 데이터가 1 살의 유저 모드 필터로부터 다음의 유저 모드 필터로 이동해 있는 것처럼 보인다. 실제로는, 데이터가 유저 모드에게 건네질 것은 없고, 커넬 모드 디바이스로부터 다른 커넬 모드 디바이스에 직접 스트리밍 되어 비디오 그래픽 카드로 렌더링 된다. 당연, 파일에의 캡춰의 경우 등, 필터 그래프내가 있는 시점에서 실제로 데이터를 커넬 모드로부터 유저 모드에 건네주지 않으면 안 되는 경우도 있다. 그러나, 유저 모드 액세스에의 이행에서는, 반드시 메모리의 새로운 장소에 데이터가 카피될 필요는 없다. 어플리케이션에서는, 캡춰 그래프를 구축 하면 와, 하드웨어 디바이스로부터 다른 하드웨어 디바이스에, 또는 하드웨어 디바이스로부터 유저 모드 필터에 데이터가 목적의 패스를 보충하도록(듯이), 명시적으로 제어할 수 있다. 상세한 것에 대하여는, 비디오 캡춰에 관한 항목을 참조할것.

보통, 어플리케이션 개발자는 배경 정보로서 밖에 커넬 스트리밍의 상세를 고려할 필요는 없다. WDM, 커넬 스트리밍, KsProxy, 및 관련 주제의 상세한 것에 대하여는, Microsoft DDK 를 참조할것.


동적 그래프 생성

기존의 필터 그래프를 변경할 필요가 있는 경우는, 그래프를 정지해, 변경을 더하고 나서, 그래프를 재기동할 수가 있다. 보통은 이것이 최선의 방법이지만, 이하와 같은 상황에서는, 실행중으로 그래프를 변경하고 싶은 경우도 있다.

  • 재생중에, 어플리케이션이 비디오 이펙트 필터를 삽입한다.
  • 소스 필터가 밋드스트림의 미디어 타입을 새로 바꾸어 경우에 따라서는 새로운 데콘프렛사피르타를 요구한다.
  • 어플리케이션이, 새로운 비디오 스트림을 그래프에 추가한다.

이것들은 모두"동적 그래프 생성"의 예이다. 동적 그래프 생성이란, 실행중에 필터 그래프에 더해지는 다양한 변경을 모두 포함한 용어이다. 동적 그래프 생성은, 어플리케이션 또는 그래프내의 필터에 의해 시작 된다. 이하의 3 종류의 시나리오가 생각된다.

  • 동적 포맷 변경: 필터를 삭제하거나 치환하거나 하지 않고, 2 개의 필터간의 접속 타입을 변경한다.
  • 동적재접속: 필터를 추가하거나 삭제하거나 해, 그래프의 위상기하학을 변경한다.
  • 필터 최인: 필터의 최인을 추가, 삭제, 및 제어한다.

이 주제는, 이하의 섹션으로 구성된다.

  • 동적 포맷 변경
  • 동적재접속
  • 필터 최인

동적 포맷 변경

필터가 출력 포맷을 새로 바꾸는 경우, 핀을 재접속하거나 그래프를 포즈 또는 정지하거나 필터를 치환하거나 하지 않아도, 다운 스트림 필터가 새로운 포맷을 받아들여지는 일도 있다. 그래프의 실행중에, 핀이 새로운 미디어 타입을 받아들여질지 어떨지를 판정하기 위해서, 필터 (또는 어플리케이션)는, 필터의 출력 핀에 접속된 입력 핀의 IPinConnection::DynamicQueryAccept 를 호출한다. 이 메소드는,IPin::QueryAccept 메소드와는 다르다. QueryAccept 는, 필터가 실행을 시작 하고 있으면(자), 핀이 미디어 타입을 받아들이는 것을 보증하지 않는다.

현재의 접속으로 새로운 포맷이 받아들여지지 않는 경우, 다음에 생각되는 해결 방법은, 이하의 섹션으로 설명하는 동적재접속이다.

동적재접속

동적재접속이란, 그래프의 위상기하학을 변경하는 것이다. 데이터를 잃지 않기 위해(때문에), 동적재접속을 시작 하는 어플리케이션 또는 필터는, 이벤트의 순서에 주의하지 않으면 안 된다. 재설정되는 그래프의 섹션에는, 미디어 데이터가 흐르고 있어서는 안 된다. 예로서 다음의 그림의 필터 그래프의 필터 2 를 어플리케이션이 동적으로 치환하는 경우를 생각해 보자.

동적 그래프 생성의 다이어그램

이 필터를 안전하게 삭제해 그래프를 재접속하기 위해서, 어플리케이션은 이하의 조작을 실시하지 않으면 안 된다.

  1. 핀 A 의 데이터 플로우를 블록 한다.
  2. 핀 B 로부터 핀 D 에, 미처리의 데이터를 필터 그래프에 내보낸다.
  3. 필터 2 를 삭제해, 새로운 필터를 삽입해, 그래프를 재설정한다.
  4. 데이터 플로우가 재개하도록(듯이), 핀 A 의 블록을 해제한다.

3 개의 인터페이스가, 이러한 조작을 지원 하고 있다.

  • 업 스트림 출력 핀 (핀 A)의 IPinFlowControl
  • 다운 스트림 입력 핀 (핀 D)의 IPinConnection
  • 필터 그래프 매니저의 IGraphConfig

이하의 섹션으로, 처리 내용을 자세하게 설명한다.

  • 데이터 플로우의 블록
  • 그래프에의 데이터의 송출
  • 그래프의 재설정
  • 샘플 코드

데이터 플로우의 블록

데이터 플로우를 블록 하려면 , 업 스트림의 출력 핀 (핀 A)의 IPinFlowControl::Block 를 호출한다. 이 메소드는, 비동기 또는 동기 시켜 호출할 수가 있다.

  • 비동기 : CreateEvent 함수를 호출해 이벤트 오브젝트를 생성해, 이벤트 핸들을 Block 메소드에 건네준다. 이 메소드는 즉시 돌아가, 처리가 완료 하면 핀이 그 이벤트를 시그널 상태로 한다. WaitForSingleObject 등의 대기 함수를 호출해 이벤트를 기다린다. 다음의 코드에, 이 처리를 나타낸다.

    HANDLE hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
pFlowControl->Block(AM_PIN_FLOW_CONTROL_BLOCK, hEvent);
WaitForSingleObject(hEvent, dwMilliseconds);
  • 동기 : 이벤트 핸들 대신에 NULL 값을 건네준다. 메소드는 처리가 완료할 때까지 돌아오지 않는다. 핀이 샘플을 송신할 수 있게 될 때까지, 메소드는 돌아오지 않는 것도 있다. 필터가 포즈 했을 경우, 이 메소드는 무한하게 블록 할 가능성이 있다. 그 때문에, 어플리케이션의 메인 thread로부터, 동기에게 Block 메소드를 호출해서는 안 된다.

그래프를 재설정하면(자), 최초의 파라미터에 0 을 건네주어 IPinFlowControl::Block 를 호출해, 데이터 플로우의 블록을 해제한다.

업 스트림 필터로 재접속을 시작 하는 경우는,IPinFlowControl::Block 를 호출하지 않아도, 데이터 플로우를 내부에서 제어할 수 있는 일이 있다.

그래프에의 데이터의 송출

디폴트에서는, 다음의 섹션으로 설명하는 IGraphConfig::Reconnect 메소드를 호출하면, 필터 그래프 매니저가 데이터를 자동적으로 그래프에 내보낸다. 그러나, 이 메소드를 사용하지 않고 IGraphConfig::Reconfigure 메소드를 사용하는 경우 등은, 이 처리를 스스로 취급하지 않으면 안 된다. 어느 경우도, 이 처리를 이해해 두면 도움이 된다.

데이터를 그래프에 내보내려면 , 이하의 조작을 실시한다.

  1. 다운 스트림 입력 핀 (핀 D)의 IPinConnection::NotifyEndOfStream 를 호출한다. 이 메소드는, 다음에 엔드 오브 스트림 조건이 발생했을 때의 핀으로부터의 통지를 요구한다. 핀은, 이벤트를 시그널 상태로 해 호출 바탕으로 통지한다.
  2. 곧바로 업 스트림 출력 핀 (핀 B)에 접속되고 있는 입력 핀의 IPin::EndOfStream 를 호출한다. 남아 있는 데이터는, 중간 필터를 통해서 다운 스트림으로 이동하므로, 이러한 필터에 의해 엔드 오브 스트림 통지가 전해진다. 이 예에서는, 중간 필터는 필터 2 뿐이다.
  3. 이벤트를 기다린다. 다운 스트림 입력 핀 (핀 D)은, 엔드 오브 스트림 통지를 받으면(자) 이벤트를 시그널 상태로 한다. 이 시점에서, 미처리의 데이터는 없고, 호출원이 그래프를 재설정해도 안전하다.

그래프의 재설정

그래프를 재설정하려면 ,IGraphConfig::Reconnect 메소드를 호출한다. 이 메소드는 이하의 처리를 실시한다.

  • 중간 필터를 정지해, 그것들을 그래프로부터 삭제한다.
  • 새로운 중간 필터를 추가해, 그러한 입력 및 출력 핀을 접속한다.
  • 새로운 필터를 기동한다.

어떠한 이유로써 IGraphConfig::Reconnect 메소드가 적당하지 않은 경우는, 콜백 메소드로 그래프를 재설정할 수가 있다. IGraphConfigCallback 인터페이스를 이행 해,IGraphConfig::Reconfigure 메소드를 호출한다. 이것이 콜백 메소드를 호출한다. 이 경우는, 데이터를 스스로 필터 그래프에 내보낼 필요가 있다. IGraphConfig::PushThroughData 메소드를 호출한다.

샘플 코드

이하의 예에, 소스 필터와 렌더링 필터의 사이에 변수 pFX 가 가리키는 이펙트 필터를 삽입하는 방법을 나타낸다. 다른 시나리오도 생각할 수 있으므로,IGraphConfig::Reconnect 메소드는 동작을 제어하는 파라미터를 몇개인가 받는다. 상세한 것에 대하여는,IGraphConfig 의 레퍼런스를 참조할것.

    // 그래프가 실행중으로 가정한다.
    IGraphConfig *pConfig;
    pGraph->QueryInterface(IID_IGraphConfig, (void **) &pConfig);

    // 데이터 플로우를 블록 한다.
    IPinFlowControl *pFlowControl;
    pOutPin->QueryInterface(IID_IPinFlowControl, (void **) &pFlowControl);
    pFlowControl->Block(AM_PIN_FLOW_CONTROL_BLOCK, NULL);

    // 그래프를 재설정한다.
    pGraph->AddFilter(pFX, L"Effect Filter");
    pConfig->Reconnect(
            pOutPin,    // 이 출력 핀으로부터 시작 한다.
            NULL,       // 다운 스트림측으로부터 적당한 입력 핀을 찾는다.
            NULL,       // 최초의 접속은 지정하지 않는다.
            pFX,        // 이 필터를 사용한다.
            NULL,
            0);

    pFlowControl->Block(0, NULL);   // 데이터 플로우의 블록을 해제한다.

주 : pOutPin 는, 소스 필터의 출력 핀에의 포인터이라고 가정되고 있다. 필터의 핀에의 포인터의 취득에 대해서는, 「핀의 열거」를 참조할것.

어플리케이션은 아니고 필터가 동적재접속을 실시하는 경우는, thread에 문제가 발생할 가능성이 있다. 특히, 다른 프로세스가 필터를 정지하려고 했을 경우, 필터가 정지하는 것을 그래프가 기다려, 데이터가 그래프에 내보내지는 것을 필터가 기다리고 있는 동안에 데드 록이 발생하는 일이 있다. 전에 설명하고 싶은 구두인가의 메소드에서는, 이것을 막기 위해서(때문에) 이벤트에의 핸들을 받는다. 필터는, 자신의 IMediaFilter::Stop 메소드에의 호출을 받으면(자), 이 이벤트를 시그널 상태로 한다. 상세한 것에 대하여는, 「IGraphConfig 인터페이스」 및 「IPinConnection 인터페이스」를 참조할것.

필터 최인

"필터 최인"이란, 이하의 조건에 합치하는 필터의 모임이다.

  • 최인내의 각 필터는, 최대로, 접속된 입력 핀을 1 개로 접속된 출력 핀을 1 개 가진다.
  • 최인의 외부의 필터를 통하지 않아도, 최인내의 모든 필터를 통과할 수가 있다.

예를 들어, 다음의 그림의 필터 A–B, C–D, 및 F–G–H 가 필터 최인이다. F–G–H 내의 서브 최인 (F–G 및 G–H)도 필터 최인이다. 필터 최인은 1 개의 필터로 구성해도 괜찮기 때문에, 필터 A, B, C, D, F, G, 및 H 도 다른 필터 최인이다. 필터 E 에는 입력 접속이 2 개 있으므로, 필터 E 를 포함한 필터의 모임은 필터 최인은 아니다.

필터 최인 (예 1)

IFilterChain 인터페이스는, 필터 최인을 제어하기 위해서 이하의 메소드를 제공하고 있다.

IFilterChain::StartChain | 최인을 시작 한다.
IFilterChain::StopChain | 최인을 정지한다.
IFilterChain::PauseChain | 최인을 포즈 한다.
IFilterChain::RemoveChain | 최인을 그래프로부터 삭제한다.

최인을 추가하기 위한 전용의 메소드는 없다. 최인을 추가하려면 ,IFilterGraph::AddFilter 메소드를 사용해 새로운 필터를 삽입해,IGraphBuilder::Connect ,IGraphBuilder::Render , 또는 동일한 메소드를 호출해 그러한 필터를 접속한다.

그래프의 실행중, 필터 최인은 실행과 정지동안에서 바뀔 수가 있다. 그래프가 포즈 하고 있을 때, 필터 최인은 포즈와 정지동안에서 바뀔 수가 있다. 필터 최인으로 가능한 상태의 변화는 이만큼이다.

필터 최인의 가이드 라인

IFilterChain 메소드를 사용할때는, 그래프내의 필터가 필터 최인의 조작을 지원 하고 있는 것을 확인해야 한다. 지원 하고 있지 않는 경우, 데드 록이나 그래프 에러가 발생하는 일이 있다. 최인에 접속된 필터는, 최인 상태가 변화해도 올바르게 기능해야 한다.

IFilterChain 를 사용하는 경우는, 최인 처리 전용에 디자인한 필터를 사용하는 것이 최선이다. 이하의 가이드 라인을 사용해, 필터 최인 처리동안에 필터가 안전한 것을 확실히 하는 것. 그러한 포인트를 다음의 그림에 나타낸다.

필터 최인 (예 2)

  • 필터 최인 상태가 바뀌기 전에, 필터 최인의 경계에 있는 데이터 처리의 호출이 모두 완료하고 있지 않으면 안 된다. 이 규칙은,IMemInputPin::Receive ,IPin::NewSegment , 및 IPin::EndOfStream 메소드에 들어맞는다. 최인내의 필터는, 최인 외부의 필터에 의해 행해진 이러한 메소드에의 호출로부터 돌아오지 않으면 안되어, 최인 외부의 필터는, 최인내의 필터에 의해 행해진 호출로부터 돌아오지 않으면 안 된다.

    예를 들어, 위에의도의 필터 B 는, 필터 A 로부터의 데이터 처리의 호출을 완료하지 않으면 안되어, 필터 E 는, 필터 D 로부터의 호출을 완료해야 한다. 핀이 IPinFlowControl 및 IPinConnection 인터페이스를 공개하고 있는 경우는, 「동적재접속」으로 설명한 것처럼,IPinFlowControl::Block 및 IGraphConfig::PushThroughData 메소드를 호출해 데이터를 그래프에 내보낼 수가 있다. 필터가, 데이터를 배웅하기 위한 프라이빗 메소드를 지원 하고 있는 경우도 있다.

  • 업 스트림 필터는, 최인 상태가 변화하는 것을 예측하고 있지 않으면 안 된다. 예를 들어, 위에의도로, 최인이 정지하고 있는데 필터 A 가 IMemInputPin::Receive 를 호출했다고 하자. 이 호출은 실패해, 필터 A 의 응답은 스트림을 정지하는 것이다. 필터 A 가 데이터를 흘리지 않기 때문에, 어플리케이션이 최인을 재기동해도 효과가 없다.
  • 다운 스트림 필터도, 최인 상태가 변화하는 것을 예측하고 있지 않으면 안 된다. 그렇지 않으면, 결코 도착하지 않는 샘플을 기다리고 있는 동안에, 다운 스트림 필터는 블록 해 버릴지도 모른다. 예를 들어, 멀티플렉서 (MUX) 필터는, 그 모든 입력 핀으로부터의 데이터를 필요한 일이 많다. 어느 입력 핀으로부터의 데이터 플로우가 정지 하면, 다른 스트림의 처리가 블록 될지도 모른다. 이것에 의해, 그래프가 데드 록에 빠지는 일이 있다.
  • 최인 외부의 필터로부터 최인 내부의 필터에의 핀 접속에는, 각각 다른 접속과 공유하지 않는 독자적인 allocater를 갖게해야 하는 것이다. 최인 상태가 변화하거나 최인이 그래프로부터 삭제 되거나 하면(자), allocater는 관련을 끊어질지도 모르기 때문이다. 다른 접속이 같은 allocater를 사용하고 있었을 경우, 그러한 접속은 샘플을 처리할 수 없게 된다.
  • 최인에 접속된 필터가 동적 접속 해제를 지원 하고 있지 않는 한, 최인을 삭제해선 안 된다. 보통, 접속된 필터는,IPinConnection 또는 IPinFlowControl 인터페이스를 지원 한다, 그러나 프라이빗 인터페이스를 지원 하는 경우도 있다.


PID

PID 는, 필터 그래프 매니저의 기능을 확장하기 위한 방법이다. PID 는, 필터 그래프 매니저가 실행시에 집성 하는 COM 오브젝트이다. 어플리케이션은, 필터 그래프 매니저를 통해서 PID 에의 액세스를 취득한다.

필터 그래프 매니저에 대해서, 지원 하지 않는 인터페이스에 대해 조회되면(자), 다음의 포맷을 사용해 레지스트리의 키가 검색된다.

HKEY_CLASSES_ROOT\Interface\IID\Distributor

IID 는, 인터페이스 식별자가 포함된 캐릭터 라인이다. 레지스트리에 엔트리가 존재하는 경우, 그 엔트리의 값에 의해, 인터페이스를 지원 하는 PID 의 클래스 식별자 (CLSID)가 정의된다. 필터 그래프 매니저는 PID 를 집성 해, 인터페이스 포인터를 돌려준다. 이것에 의해, PID 의 외부 IUnknown 로서 기능한다. 어플리케이션이 인터페이스상에서 메소드를 호출하면나무는, 실제로는 PID 상에서 호출하고 있다. 그러나, PID 의 존재는 어플리케이션에 대해서는 투과적이다.

distributor 라고 하는 용어는, PID 가 필터 그래프 매니저의 인터페이스에 대해, 외부 IUnknown 포인터에 조회가 가능한 일로 유래하고 있다. PID 는 IFilterGraph::EnumFilters 메소드를 호출하는 것으로, 그래프의 필터를 열거해, 그러한 필터에 메소드 콜을 배포할 수 있다. 이와 같이 해, PID 는 어플리케이션이 필터상에서 메소드를 호출하기 위한, 1 개의 컨트롤 포인트로서의 역할을 완수할 수가 있다.

필터 그래프 매니저가 PID 를 집성 하면나무는,IDistributorNotify 인터페이스에 대해 PID 에 조회한다. PID 가 이 인터페이스를 지원 하고 있는 경우, 필터 그래프 매니저는 이 인터페이스를 사용해, 그래프에서의 변경에 대해 PID 에 통지한다.

  • 필터 그래프가 실행, 포즈, 및 정지의 각 상태를 바꾸려면 ,IDistributorNotify::Run ,IDistributorNotify::Pause , 또는 IDistributorNotify::Stop 를 호출한다.
  • 기준 클락이 설정되면(자), 필터 그래프 매니저는 IDistributorNotify::SetSyncSource 를 호출한다.
  • 필터가 추가 또는 삭제되거나 핀 접속이 변경되면(자), 필터 그래프 매니저는 IDistributorNotify::NotifyGraphChange 를 호출한다.

커스텀 PID 를 이행 하기 위해서는, 집합을 지원 하는 COM 오브젝트를 생성 한다. 이 오브젝트는, 필터 그래프 매니저가 이미 지원 하고 있지 않는 인터페이스를 지원 해야 한다. 또, 옵션으로 IDistributorNotify 인터페이스를 지원 할 수도 있다.

PID 가 필터 그래프 매니저로부터 인터페이스 포인터를 취득할 때는, 그것들을 곧바로 해방할 필요가 있다. 해방하지 않으면 순환 참조 카운트가 생성 되어 필터 그래프 매니저의 파괴를 방해할 가능성이 있다. 어느 경우도, 필터 그래프 매니저가 PID 의 계속 시간을 제어하기 위해(때문에), 필터 그래프 매니저에서의 기준 카운트의 보관 유지는 불필요하다.

PID 는 필터 그래프 매니저에 의한 집성화를 위해서(때문에) 설계되고 있으므로, PID 의 constructor　 　 메소드로 이것을 설정할 수도 있다. 외부 IUnknown 포인터가 NULL 일지 어떨지를 확인해, NULL 인 경우는, 에러 코드 VFW_E_NEED_OWNER 를 돌려준다. 또, 다른 오브젝트가 PID 를 집성화하지 않게 하기 위한(해),IGraphBuilder 인터페이스에 대해 외부 IUnknown 포인터에 조회할 수 있다. 그 오브젝트가 IGraphBuilder 를 공개하고 있지 않으면, 에러 코드를 돌려준다.


DirectShow 의 사용법

여기에서는 다음의 내용에 대해 설명한다.

  • GraphEdit 에 의한 그래프 구축의 시뮬레이션
  • 파일의 재생
  • 오디오 캡춰
  • 비디오 캡춰
  • DirectShow 편집 서비스
  • DVD 어플리케이션
  • Windows Media 어플리케이션
  • Microsoft TV 테크놀러지
  • DirectShow 필터의 개발
  • DirectShow 에서의 디버그
  • 프로그래밍의 힌트


GraphEdit 에 의한 그래프 구축의 시뮬레이션

Microsoft® DirectX® SDK 에는, 필터 그래프의 생성과 테스트에 사용하는 GraphEdit 라고 하는 디버그 유틸리티가 제공되고 있다.

여기에서는 다음의 내용에 대해 설명한다.

  • GraphEdit 의 개요
  • GraphEdit 의 사용법
  • 외부 프로세스로부터의 그래프의 로드

GraphEdit 의 개요

GraphEdit 는, 필터 그래프를 구축하기 위한 비주얼 툴이다. GraphEdit 를 사용 하면, 어플리케이션 코드를 쓰기 전에 필터 그래프를 테스트할 수가 있다. 또, 어플리케이션으로 생성 하는 필터 그래프를 로드해, 어플리케이션으로 올바른 그래프가 구축되는 것을 검증할 수 있다. 커스텀 필터를 개발했을 경우는, GraphEdit 를 사용해 필터를 재빠르게 테스트할 수 있다. 테스트를 실시하려면 , 커스텀 필터를 사용해 그래프를 로드해, 그래프를 실행하는 것만으로 좋다. DirectShow 를 사용했던 적이 없는 경우, GraphEdit 는, 필터 그래프 및 DirectShow 아키텍쳐에 익숙하는 좋은 방법이다.

다음의 그림은, GraphEdit 로 간단한 필터 그래프가 어떻게 표현되는지를 나타내고 있다.

GraphEdit 의 간단한 필터 그래프

각 필터는 직사각형으로 나타내진다. 필터의 주위를 뒤따르고 있는 작은 사각은 핀을 나타낸다. 입력 핀은 필터의 좌측에 있어, 출력 핀은 우측에 있다. 화살표는 핀의 사이의 접속을 나타낸다.

GraphEdit 를 사용 하면, 다음 일이 생긴다.

  • 드래그 앤드 드롭식의 비주얼 인터페이스를 사용해 필터 그래프를 생성, 편집한다.
  • IGraphBuilder::RenderFile 등, 그래프를 구축하기 위한 프로그램에 의한 호출을 시뮬레이션 한다.
  • 그래프를 런, 포즈, 스톱, 시크 한다.
  • 사용하고 있는 컴퓨터에 등록되어 있는 필터를 확인해, 각 필터의 레지스트리 정보를 표시한다.
  • 필터 프로퍼티 페이지를 표시한다.
  • 핀 접속의 미디어 타입을 표시한다.

GraphEdit 의 사용법

DirectX SDK 를 인스톨 하면,[스타트] 메뉴의 [Microsoft DirectX 8 SDK] 아래의 [DX Utilities] 에 GraphEdit 가 표시된다. 실행 모듈 파일은 GraphEdt.exe 로, 디폴트에서는 Mssdk\Bin\DXUtils 폴더에 인스톨 된다. 이러한 어느 장소로부터에서도 GraphEdit 를 열 수가 있다.

다음에, GraphEdit 를 사용해 실행할 수 있는 것에 대하여 간단하게 설명한다. 이러한 기능 ( 및 그 외의 기능)의 상세한 것에 대하여는, GraphEdit 어플리케이션 헬프를 참조할것.

파일 재생 그래프의 구축

GraphEdit 를 사용 하면, 파일을 재생하는 필터 그래프를 구축할 수 있다. 이 기능은, 어플리케이션으로 IGraphBuilder::RenderFile 메소드를 호출하는 것과 같다. [File] 메뉴의 [Render Media File] 를 클릭한다. GraphEdit 의 [Open File] 다이알로그 박스가 표시된다. 멀티미디어 파일을 선택해 [Open] 를 클릭한다. 선택한 파일을 재생하기 위한 필터 그래프가 GraphEdit 로 구축된다.

특정의 URL 에 있는 미디어 파일을 렌더링 할 수도 있다. [File] 메뉴의 [Render URL] 를 클릭한다. URL 를 지정하는 다이알로그 박스가 표시된다.

커스텀 필터 그래프의 구축

GraphEdit 에서는, 시스템에 등록되어 있는 필터를 사용해 커스텀 필터 그래프를 구축할 수 있다. [Graph] 메뉴의 [Insert Filters] 를 클릭한다. 시스템에 등록되어 있는 필터의 일람을 필터 카테고리별로 나타내는 다이알로그 박스가 표시된다. GraphEdit 는 레지스트리의 정보로부터 이 일람을 구축한다. 다음의 그림에 이 다이알로그 박스를 나타낸다.

[Which filters do you want to insert?] 다이얼로그 박스

그래프에 필터를 추가하려면 , 필터의 이름을 선택해 [Insert Filters] 를 클릭하는지, 필터명을 더블 클릭 한다. 필터를 추가한 후, 1 개의 필터의 출력 핀으로부터 이제(벌써) 1 개의 필터의 입력 핀에 마우스를 드러그 하면, 2 개의 필터를 접속할 수 있다. 핀이 접속을 받아들이면(자), 핀을 접속하는 화살표가 표시된다.

2 개의 필터의 접속

그래프의 실행

GraphEdit 로 필터 그래프를 구축한 후, 그래프를 실행해, 그래프가 예측대로 동작할지 어떨지를 확인할 수 있다. [Graph] 메뉴에는,[Play],[Pause], 및 [Stop] 의 메뉴 커멘드가 있다. 이러한 커멘드는 각각,IMediaControl 메소드인 Run ,Pause , 및 Stop 를 호출한다. [GraphEdit] 툴바에도, 이러한 커멘드를 실행하는 버튼이 표시된다.

[Play],[Pause], 및 [Stop] 버튼

주 : GraphEdit 의 [Stop] 커멘드는, 최초로 그래프를 포즈 해, 타임 제로를 시크 한다 (그래프는 시크 가능으로 한다). 파일을 재생하기 위해서, 이 동작으로 비디오 윈도우가 최초로 프레임에 리셋 된다. 다음에, GraphEdit 는 IMediaControl::Stop 를 호출한다.

그래프가 시크 가능한 경우는, 툴바아래에 표시되는 슬라이더 바를 드러그 하면, 그래프를 시크 할 수 있다. 슬라이더 바를 드러그 하면 IMediaSeeking::SetPositions 메소드가 불려 간다.

프로퍼티 페이지의 표시

커스텀 프로퍼티 페이지를 지원 하고 있는 필터도 있다. 커스텀 프로퍼티 페이지는, 필터의 프로퍼티를 설정하기 위한 유저 인터페이스를 제공한다. GraphEdit 로 필터의 프로퍼티 페이지를 표시하려면 , 필터를 오른쪽 클릭해, pop-up 윈도우의 [Properties] 를 클릭한다. 필터에 정의되고 있는 프로퍼티 시트가 있는 경우는, 프로퍼티 시트가 프로퍼티 페이지에 표시된다. 게다가 GraphEdit 에는 필터의 각 핀의 프로퍼티 시트가 포함되어 있다. 핀 프로퍼티 시트는, 필터는 아니고 GraphEdit 에 의해 정의된다. 핀이 접속되고 있는 경우는, 핀 프로퍼티 시트에 접속의 미디어 타입이 표시된다. 핀이 접속되어 있지 않은 경우는, 핀의 우선 미디어 타입이 표시된다.

외부 프로세스로부터의 그래프의 로드

GraphEdit 는 외부 프로세스에 의해 생성 된 필터 그래프를 로드할 수 있다. 이 기능을 사용 하면, 어플리케이션 정원않고일까 코드를 추가하는 것만으로, 어플리케이션으로 구축하는 필터 그래프를 정확하게 알 수 있다.

어플리케이션으로 필터 그래프의 인스턴스를 실행중 오브젝트 테이블 (ROT)에 등록해야 한다. ROT 는, 실행중 오브젝트를 추적 관리하는 글로벌하게 액세스 가능한 룩 업 테이블이다. 오브젝트는 모니카에 의해 ROT 에 등록된다. 그래프에 접속하기 위해서, GraphEdit 는 표시명이 특정의 포맷에 일치하는 모니카를 ROT 로 검색한다.

! FilterGraph X pid Y

X 와 Y 는, 각각 필터 그래프의 주소와 프로세스 id 를 나타내는 16 진수이다.

어플리케이션으로 최초로 필터 그래프를 생성 하려면 , 다음의 함수를 호출한다.

HRESULT AddToRot(IUnknown *pUnkGraph, DWORD *pdwRegister)
{
    IMoniker * pMoniker;
    IRunningObjectTable *pROT;
    if (FAILED(GetRunningObjectTable(0, &pROT))) {
        return E_FAIL;
    }
    WCHAR wsz[256];
    wsprintfW(wsz, L"FilterGraph %08p pid %08x", (DWORD_PTR) pUnkGraph, GetCurrentProcessId());
    HRESULT hr = CreateItemMoniker(L"! ", wsz, &pMoniker);
    if (SUCCEEDED(hr)) {
        hr = pROT->Register(0, pUnkGraph, pMoniker, pdwRegister);
        pMoniker->Release();
    }
    pROT->Release();
    return hr;
}

이 함수는, 필터 그래프의 모니카와 새로운 ROT 항목을 생성 한다. 최초의 파라미터는 필터 그래프의 포인터이다. 2 번째의 파라미터는, 새로운 ROT 항목을 식별하는 값을 받는다. 어플리케이션으로 필터 그래프를 해방하기 전에, 다음의 함수를 호출해 ROT 항목을 삭제한다. pdwRegister 파라미터는, AddToRot 함수로부터 돌려주어지는 식별자이다.

void RemoveFromRot(DWORD pdwRegister)
{
    IRunningObjectTable *pROT;
    if (SUCCEEDED(GetRunningObjectTable(0, &pROT))) {
        pROT->Revoke(pdwRegister);
        pROT->Release();
    }
}

다음의 코드예는, 이러한 함수를 호출하는 방법을 나타내고 있다. 이 예에서는, ROT 항목을 추가 및 삭제하는 코드는 조건부로 컴파일 되어 디버그 빌드에게만 짜넣어진다.

IGraphBuilder *pGraph;
DWORD dwRegister;

// 필터 그래프 매니저를 생성 한다.
CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC_SERVER,
IID_IGraphBuilder, (void **) &pGraph);
#ifdef DEBUG
hr = AddToRot(pGraph, &dwRegister);
#endif

// 어플리케이션의 나머지의 부분 (생략).

#ifdef DEBUG
RemoveFromRot(dwRegister);
#endif
pGraph->Release();

GraphEdit 로 필터 그래프를 표시하려면 , 어플리케이션과 GraphEdit 를 동시에 실행한다. GraphEdit 로 [File] 메뉴의 [Connect] 를 클릭한다. [Connect To Graph] 다이알로그 박스로, 어플리케이션의 프로세스 id (pid)를 선택해,[OK] 를 클릭한다. GraphEdit 는 필터 그래프를 로드해, 표시한다. 예측할 수 없는 결과가 될 가능성이 있으므로, 이 그래프에서는 그 외의 GraphEdit 기능을 사용하지 않는 것. 예를 들어, 필터의 추가, 삭제, 또는 그래프의 정지, 시작은 실시하지 않는 것. GraphEdit 를 종료하고 나서, 어플리케이션을 종료한다.

주 : 어플리케이션에서는, 종료시에 다양한 에러가 발생하는 일이 있다.

다음의 그림에 [Connect To Graph] 다이알로그 박스를 나타낸다.

[Connect To Graph] 다이얼로그 박스


파일의 재생

파일을 재생하기 위해서 필요한 기본 순서에 대해서는, 「파일의 재생법」을 참조할것.

PlayWnd 샘플 어플리케이션에서는, 기본 순서의 상세를 나타내는 것과 동시에, 비디오 윈도우의 사이즈와 위치를 관리하는 방법, 및 실행중 오브젝트 테이블에 어플리케이션의 필터 그래프를 추가해, 생성중의 그래프를 GraphEdit 로 "감시 " 할 수 있도록(듯이) 하는 방법을 나타낸다.


오디오 캡춰

Microsoft® DirectShow® 를 사용 하면, 마이크로 폰이나 테이프 플레이어등의 디바이스로부터 시스템의 사운드 카드에 의한 입력을 개입시켜, 오디오 데이터를 캡춰 할 수 있다. 일반적으로, 다음과 같은 상황에서의 사용이 생각된다.

  • 비디오 스트림을 후일 더빙 할 때에, 음성 오버 나레이션을 녹음
  • 종래의 아날로그 오디오 컨텐츠를 디지털 포맷에 변환
  • 네트워크를 개입시킨 방송으로, 음성이나 음악을 캡춰
최종 사용자가 사운드 카드로부터 하드 디스크에 오디오를 캡춰 하려면 몇개의 옵션이 있다. 많은 사운드 카드에는, 오디오 입력으로부터 믹싱이나 녹음을 행하기 위한 어플리케이션이 부속되어 있다. Microsoft® Windows® operating system에는, 마이크로 폰으로부터의 녹음을 실시하는 단순한 유틸리티 어플리케이션으로서 사운드 레코더가 있다. Windows Media™ Tools 에는, 이러한 태스크를 실행할 수 있는 스탠드얼론 어플리케이션의 Windows Media Encoder 가 있다. 또, Windows Media Encoder 는, DirectShow 어플리케이션에 Microsoft® DirectX® Media Object (DMO)로서 짜넣을 수도 있다. 여기에서는, DirectShow 를 사용한 독자 어플리케이션에 오디오 캡춰 기능을 통합하는 방법에 대해 설명한다.

오디오 캡춰 필터

사운드 카드 위에의 아날로그 입력으로부터의 오디오 캡춰는,오디오 캡춰 필터를 사용하는 것으로 가능하게 된다. 이 필터에서는, Microsoft® Platform SDK waveInXXX API (waveInOpen, waveInStart, waveInGetID 등)를 사용해, 이러한 API 를 드라이버로 지원 하는 임의의 디바이스를 DirectShow 필터 그래프에 추가할 수 있도록(듯이) 한다. 오디오 캡춰 필터에 의해, 마이크로 폰이나 라인 인 입력 등, 사운드 카드 위에의 모든 입력이 공개된다. CD 오디오 입력으로부터 캡춰 할 수도 있지만, 이 경우, 오디오 스트림은 이미 디지털 아날로그 컨버터를 경유하고 있기 (위해)때문에, 오리지날의 CD 와 비교하면(자) 음질이 저하한다. CD 로부터의 직접 디지털 캡춰에 대해서는, Windows Media 7 SDK 를 참조할것.

각 입력 핀의 수, 종류, 성질, 및 이름은, 사운드 카드와 그 드라이버에 의해 다르다. 특정의 사운드 카드의 기능을 완전하게 이해해 이용하려면 , 카드 제조업자로부터 다큐멘테이션을 입수할 필요가 있다.

오디오 캡춰 필터는, 사운드 카드 위에의 입력을 보통의 DirectShow 입력 핀으로서 나타낸다. 이러한 핀은, 드라이버가 입력 믹서 라인으로서 무엇을 공개하는지를 나타낸다. 이러한 핀에 데이터는 흐르지 않는다. 이것들은 각 라인의 레벨을 유효하게 해 설정하기 위한 수단을 제공할 뿐이다. 각 라인으로 이용할 수 있는 컨트롤의 종류는, 드라이버에 의해 다르다, 예를 들어 드라이버에 의한 지원이 있으면, 입력 라인 위에의 저음역부와 고음역부를 제어하기 위해(때문에)인 만큼 핀을 사용할 수 있다.

GraphEdit 유틸리티 프로그램내의 오디오 캡춰 필터를 보려면 , 이하와 같이 한다 :

  • [Graph] 메뉴로부터,[Insert Filters] 를 선택한다.
  • [Audio Capture Sources] 카테고리를 전개한다.
  • 필터를 선택한다.
  • [Insert Filters] 를 클릭한다.

시스템 위에의 각 카드는 필터의 다른 인스턴스에 의해 표현된다. 필터상으로 보이는 핀은 차이가 나는 혹은 다른 이름을 갖고 있을 가능성이 있는, 그것은 시스템의 사운드 카드 드라이버에 의존한다. 그러한 핀은 IAMAudioInputMixer 인터페이스를 지원 하는,IAMAudioInputMixer::put_Enable 를 사용하는 것에 의해 어플리케이션은 입력 (복수도 가능)을 선택할 수 있다.

입력의 유효와 무효를 개별적으로 바꾸는 것에 가세해 어플리케이션은 저음역부, 고음역부, 및 볼륨 레벨도 개별적으로 설정할 수 있다. 복수의 입력을 동시에 캡춰 하는 경우, 필터 자체에 이행 되고 있는 IAMAudioInputMixer 인터페이스를 통해서, 믹싱, 저음역부, 고음역부, 및 볼륨 레벨 전체를 제어할 수 있다. 또, 필터에는 IAMBufferNegotiation 도 이행 되고 있다. 이것은 오디오 프리뷰에 있어서의 지연 시간 제어에 사용한다. 오디오 캡춰 필터의 버퍼 사이즈는, 기정에서는 0.5 초로 설정된다. 이것은 캡춰용으로 최적화되고 있지만, 라이브 오디오를 캡춰 하면서 프리뷰 하는 경우는, 스트림의 렌더링에 0.5 초의 지연이 생기게 된다. 이 지연 시간을 단축하려면 ,IAMBufferNegotiation::SuggestAllocatorProperties 메소드를 사용해,ALLOCATOR_PROPERTIES 구조체의 cbBuffer 멤버에 이것보다 작은 사이즈를 지정한다. 보통은 80 밀리 세컨드의 버퍼가 안전하지만, 30 ~ 40 밀리 세컨드의 버퍼에서도 충분한 일이 많다. 버퍼가 너무 작으면(자), 음질은 저하한다.

캡춰에 이용할 수 있는 샘플링 레이트와 오디오 포맷은, 드라이버에 의해 결정된다. 이용할 수 있는 샘플링 레이트와 포맷을 열거하려면 , 오디오 캡춰 필터의 출력 핀 위에의 IAMStreamConfig 인터페이스를 사용한다. 필터는, 출력 핀의 미디어 타입을 받아들이는 임의의 필터에, 다운 스트림을 접속할 수 있다. 그 후, 오디오 데이터는, 스피커에 의한 렌더링, 커스텀의 변환 필터에 의한 변환, 파일에의 압축 및 기입이 가능하게 된다.

오디오 캡춰 필터 그래프

다음에, 다양한 오디오 캡춰 솔루션에 대해서 생각되는 몇개의 필터 그래프를 나타낸다.

  • 오디오 캡춰 > AVI Mux > 파일 라이터 (오디오 전용 AVI 파일을 생성 하는 경우)
  • 오디오 캡춰 > WavDest > 파일 라이터 (WAV 파일을 생성 하는 경우)
  • 오디오 캡춰 > ASF 라이터 (Windows Media Audio 파일을 생성 하는 경우)

주 WaveDest 필터는 샘플로서 제공되지만, 구축과 등록은 유저 자신이 실시하지 않으면 안 된다.

오디오 캡춰 필터 그래프의 생성

오디오 캡춰 필터 그래프를 생성 하려면 , 다음의 3 개의 기본 작업이 있다.

  1. 그래프의 구축
  2. 오디오 캡춰 소스의 열거
  3. 유저에 의한 입력 라인 선택에의 대응

그래프의 구축

파일에 기입하는 오디오 캡춰 그래프의 구축 방법은, 생성 하는 파일의 포맷에 의해 다르다. AVI 포맷에 보존하는 경우, Capture Graph Builder 를 사용해 그래프를 구축한다. 이것이 가장 간단한 오디오 캡춰 방법이다. 결과의 파일에는, 1 개의 오디오 스트림이 포함되어 비디오 스트림은 포함되지 않는다. ASF 포맷에 보존하는 경우도 Capture Graph Builder 를 사용할 수 있지만, 미리 Windows Media SDK 를 인스톨 해, 언락 하는 소프트웨어 키를 취득할 필요가 있다. Capture Graph Builder 의 사용법의 상세한 것에 대하여는, 「캡춰 어플리케이션의 쓰는 법」을 참조할것. 그 정보의 상당수는, 오디오 전용 그래프에도와 같이 적용할 수 있다.

WAV 파일에 기입하는 경우, 이 파일은 WaveDest 필터를 인식하지 않기 때문에, Capture Graph Builder 를 사용할 수 없다. DirectShow 는 이 필터를 샘플로서의 보고 제공해, 컴파일과 등록은 유저가 실시할 필요가 있다. WaveDest 를 로컬 시스템에 등록하면(자),IFilterGraph::AddFilter 메소드로 오디오 캡춰 필터, WavDest 필터, 및 파일 라이터 필터를 그래프에 추가해,IFilterGraph::ConnectDirect 메소드로 핀을 접속하는 것으로 그래프를 수동으로 구축할 필요가 있다.

오디오 캡춰 소스의 열거

필터 그래프 매니저 및 Capture Graph Builder 또는 그 한편의 인스턴스를 생성 하고 나서, System Device Enumerator 를 사용해, 시스템상에서 이용할 수 있는 모든 오디오 캡춰 디바이스의 일람을 취득한다. 이 방법의 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것. 돌려주어진 일람의 선두에 있는 디바이스는, 유저가 우선 녹음 디바이스로서 선택한 디바이스가 된다 (우선 디바이스를 선택하려면 , 컨트롤 패널의 [사운드와 멀티미디어] 를 클릭한다). 디바이스 열거 튜토리얼도 디바이스를 지정하는 프렌들리 명문자열의 취득 방법을 나타낸다. 하면 이 캐릭터 라인이 리스트 박스에 삽입되어 복수 디바이스로부터 유저가 선택 가능하게 된다

유저에 의한 입력 라인 선택에의 대응

오디오 캡춰 필터를 그래프에 추가하면(자),IAMAudioInputMixer 인터페이스 메소드를 사용해, 유효하게 하는 라인, 및 그 라인의 볼륨, 저음역부, 및 고음역부의 설정을 선택할 수 있다 (드라이버로 지원 되는 경우). 또, 필터의 프로퍼티 페이지를 사용하는 방법에서도, 유저가 이용할 수 있는 핀으로부터 선택하거나 각종 레벨을 설정하거나 할 수가 있다. 상세한 것에 대하여는, 「필터의 프로퍼티 페이지의 표시」 및 「오디오 캡춰 필터」를 참조할것. 그 외에, 어플리케이션의 프로그래밍 코드로 핀을 열거해, 독자적인 유저 인터페이스를 생성 할 수도 있다. 핀의 열거에 대한 정보는, 「핀의 열거」를 참조할것.


비디오 캡춰

여기에서는, Microsoft® DirectShow® 를 사용해 비디오 캡춰 어플리케이션을 생성 하는 방법에 대해 설명한다.

  • 캡춰 어플리케이션의 쓰는 법
  • 디지털 비디오 (DV)
  • WDM 비디오 캡춰에 대해
  • 캡춰 퍼포먼스의 향상
  • 캡춰에 관한 고도의 주제


캡춰 어플리케이션의 쓰는 법

이 주제에서는, Microsoft® DirectShow® 를 사용해 비디오 캡춰 어플리케이션을 쓰는 방법을 설명한다. 이하의 섹션으로 구성된다.

  • DirectShow 에서의 캡춰의 개요
  • 캡춰 그래프의 생성
  • 그래프 프로퍼티의 설정
  • 캡춰 그래프의 제어
  • 디바이스의 삭제

DirectShow 에서의 캡춰의 개요

"캡춰"라고 하는 용어는, 파일에의 기입의 의미가 있지만, 캡춰 한 데이터의 프리뷰나 그 외의 사용 방법의 의미도 포함하고 있다. 캡춰는 비디오 카메라로 한정되는 것은 아니고, 텔레비젼 튜너등도 캡춰 디바이스이다. 여기에서는, 오디오 및 비디오의 캡춰에 대해 설명하지만, 캡춰 데이터에는, 자막 방송이나 수직 동기 간격 (VBI)의 데이터가 포함되는 경우가 있는 것을 기억해 두면 좋겠다.

캡춰 그래프

DirectShow 는, 다른 태스크와 같게 필터 그래프를 사용해 캡춰를 처리한다. 이 종류의 그래프는 "캡춰 그래프" 로 불린다. 다양한 하드웨어 디바이스나 데이터 포맷을 이용할 수 있기 (위해)때문에, 캡춰 그래프는 여러가지 방법으로 설정할 수 있다. 대부분의 캡춰 그래프에는, 이하와 같은 공통점이 있다.

  • 데이터를 캡춰 하기 위해서, 그래프는 1 개 이상의 캡춰 필터를 필요로 한다. 각 캡춰 필터는, 비디오 카메라등의 하드웨어 디바이스를 나타낸다.
  • 데이터를 프리뷰 하기 위해서, 그래프는 오디오 및 비디오의 렌더링 필터를 필요로 한다.
  • 파일 캡춰의 경우, 그래프는 파일을 써내는 필터를 필요로 해, 경우에 따라서는,AVI Mux 필터
    • 등의멀티플렉서 (mux) 필터가 1 개 이상 필요하게 된다.
  • 캡춰 디바이스가 WDM (Windows Driver Model) 드라이버를 사용하는 경우, 그래프에는 캡춰 필터로부터의 필터의 업 스트림이 필요하게 되는 일이 있다. 이러한 필터는, 스트림 클래스 드라이버 필터로 불려 하드웨어가 제공하는 추가 기능을 지원 한다. 예를 들어, 텔레비젼 튜너 카드에는 채널을 설정하기 위한 기능이 있다. 거기에 대응하는 필터가,TV 튜너 필터이다.

다음의 그림은, 전형적인 캡춰 그래프에서의 필터의 종류를 나타낸다. 파선은, 디코더 필터나 스플리터 필터등의 추가 필터가 필요하게 될지도 모르는 부분을 나타내고 있다.

캡춰 그래프의 생성을 간단하게 하기 위해서, DirectShow 는캡춰 그래프 빌더라고 하는 컴퍼넌트를 제공하고 있다. 이 컴퍼넌트가 공개하는 ICaptureGraphBuilder2 인터페이스가, 캡춰 그래프를 생성 해 제어하기 위한 메소드를 가지고 있다. 이 주제에서는, 캡춰 어플리케이션으로 캡춰 그래프 빌더를 사용하는 것을 전제로 하고 있다.

캡춰 필터

캡춰 필터는, 1 개(살) 이상의 출력 핀을 통해서 데이터를 전달한다. 출력 핀은, 전달하는"미디어 타입"과"핀 카테고리"에 의해 분류할 수 있다.

미디어 타입은,메이저 타입 GUID 에 의해 나타내진다. 가장 공통의 미디어 타입은 이하의 겉(표)대로이다.

미디어 타입 | 메이저 타입 GUID
오디오 | MEDIATYPE_Audio
인터리브 된 디지털 비디오 (DV) | MEDIATYPE_Interleaved
MPEG 스트림 | MEDIATYPE_Stream
비디오 | MEDIATYPE_Video

핀 카테고리는 핀의 목적과 기능을 나타내서 , 프로퍼티 세트 GUID 로 나타내진다. 핀 카테고리는 몇개인가 있지만, 여기에서는 이하의 2 개에 대해 설명한다.

  • PIN_CATEGORY_CAPTURE : 핀은 파일 캡춰용 데이터를 제공한다.
  • PIN_CATEGORY_PREVIEW : 핀은 프리뷰용 데이터를 제공한다.

모든 핀 카테고리에 대해서는, 「핀 프로퍼티 세트」를 참조할것.

미디어 타입과 핀 카테고리를, 핀에 직접 문의할 수가 있다. 미디어 타입을 취득하려면 IPin::EnumMediaTypes 메소드를 호출해, 핀 카테고리를 취득하려면 IKsPropertySet::Get 메소드를 호출한다. 다만,ICaptureGraphBuilder2 메소드를 사용하면, 각 핀에 문의하지 않아도, 특정의 미디어 타입 또는 핀 카테고리에 조작을 한정할 수가 있다.

캡춰 그래프의 생성

캡춰 그래프는 이하의 순서로 생성 한다.

  1. 필요한 컴퍼넌트의 생성
  2. 캡춰 디바이스의 선택
  3. 파일 기입 섹션의 생성
  4. 스트림의 렌더링

필요한 컴퍼넌트의 생성

캡춰 그래프의 생성에서는, 우선 하늘의 필터 그래프와 캡춰 그래프 빌더를 생성 한다. 다음에,ICaptureGraphBuilder2::SetFiltergraph 를 호출해, 필터 그래프를 캡춰 그래프 빌더에 관련짓는다. 이하의 코드에 이러한 순서를 나타낸다.

IGraphBuilder *pGraph = NULL;
ICaptureGraphBuilder2 *pBuilder = NULL;

// 필터 그래프를 생성 한다.
CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC,
    IID_IGraphBuilder, (void **) &pGraph);

// 캡춰 그래프 빌더를 생성 한다.
CoCreateInstance(CLSID_CaptureGraphBuilder2, NULL, CLSCTX_INPROC,
    IID_ICaptureGraphBuilder2, (void **) &pBuilder);

pBuilder->SetFiltergraph(pGraph);

캡춰 디바이스의 선택

2 개째의 스텝은,시스템 디바이스 열거자를 사용한 캡춰 디바이스의 선택이다. 상세한 것에 대하여는, 「시스템 디바이스 열거자의 사용」을 참조할것. 이하의 코드는, 비디오 캡춰 디바이스를 열거해, 열거 순서내의 최초의 디바이스를 선택한다.

// 시스템 디바이스 열거자를 생성 한다.
ICreateDevEnum *pDevEnum = NULL;
CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC,
    IID_ICreateDevEnum, (void **) &pDevEnum);

// 비디오 캡춰 디바이스의 열거자를 생성 한다.
IEnumMoniker *pClassEnum = NULL;
pDevEnum->CreateClassEnumerator(CLSID_VideoInputDeviceCategory, &pClassEnum, 0);

ULONG cFetched;
IMoniker *pMoniker = NULL;
IBaseFilter *pSrc = NULL;
if (pClassEnum->Next(1, &pMoniker, &cFetched) == S_OK)
{
    // 최초의 모니카를 필터 오브젝트에 바인드 한다.
    pMoniker->BindToObject(0, 0, IID_IBaseFilter, (void**) &pSrc);
    pMoniker->Release();
}
pClassEnum->Release();
pDevEnum->Release();

일반적으로는, 사용 가능한 디바이스의 이름이 들어간 리스트 박스를 표시해, 유저에게 디바이스를 선택시키는 것이 보통일 것이다. 그렇게 하려면 ,IMoniker::BindToStorage 메소드를 호출해, 데바이스모니카의 프로퍼티 가방을 취득해,IPropertyBag::Read 메소드를 호출해, 디바이스의 프렌들리명을 취득한다. 상세한 것에 대하여는, 「시스템 디바이스 열거자의 사용」을 참조할것.

여기서, 이하와 같이 캡춰 필터를 그래프에 추가한다.

// pSrc 는, 전의 코드의 캡춰 필터이다.
pGraph->AddFilter(pSrc, L"Video Capture");

주 : 오디오와 비디오의 양쪽 모두를 캡춰 하는 디바이스는,[Audio Capture Sources] 와 [Video Capture Sources] 의 2 개의 카테고리에 표시된다. 한편의 카테고리로부터 디바이스를 선택한 후, 필터의 출력 핀의 미디어 타입을 체크한다. 디바이스가 양쪽 모두의 카테고리로 분류되는 경우는, 2 개째의 디바이스를 추가해선 안 된다. 이것은, 인터리브 된 오디오/비디오를 생성하는 디지털 비디오 (DV) 카메라의 경우에도 들어맞는다.

파일 기입 섹션의 생성

파일 캡춰를 실행하기 위해서, 필터 그래프에 파일 기입 섹션을 추가한다(프리뷰 기능만이 필요한 경우는, 이 스텝을 날려도 좋다). ICaptureGraphBuilder2::SetOutputFileName 메소드를 사용한다. 이 메소드는, 필요한 mux 필터와 파일 기입 필터를 그래프에 추가한다. 이 메소드는, 출력 파일의 이름과 포맷을 지정하는 입력 파라미터를 받지만, 포맷에 대해서는 이하의 몇개의 값을 사용할 수 있다.

  • MEDIASUBTYPE_Avi: AVI 파일을 써낸다.
  • MEDIASUBTYPE_Asf: ASF 파일을 써낸다.
  • 멀티플렉서 필터 또는 파일 라이터 필터의 클래스 식별자 (CLSID).

3 개째의 옵션은, 써드파티제의 필터를 사용하기 위한의 것이다. 예를 들어, MPEG 데이터를 건네주는 캡춰 디바이스가 있지만, DirectShow 에는 MPEG 라이터 필터가 부속되지 않기 때문에, MPEG 파일을 써내려면 써드파티제의 필터가 필요하게 된다.

이하의 예에서는, 출력 파일의 이름을 Example.avi 로 설정해, 포맷을 AVI 로 설정해 있다.

IBaseFilter     *ppf = NULL;
IFileSinkFilter *pSink = NULL;
pBuilder->SetOutputFileName(&MEDIASUBTYPE_Avi, L"C:\\Example.avi", &ppf, &pSink);

이 메소드는, 돌아오면(자) "ppf" 파라미터를 멀티플렉서의 IBaseFilter 인터페이스로 설정해,"pSink" 파라미터를 파일 라이터의 IFileSinkFilter 인터페이스로 설정한다. 이것들은 같은 필터여도 괜찮다. 예를 들어,ASF 라이터 필터는 파일 기입과 멀티플렉서 처리의 양쪽 모두를 실시한다.

다음의 그림은, AVI 파일 (왼쪽)과 ASF 파일 ( 오른쪽)의 기입해에 사용하는 필터를 나타낸다.

AVI 파일과 ASF 파일의 기입해에 사용하는 필터

AVI Mux 필터는 IConfigAviMux 인터페이스 및 IConfigInterleaving 인터페이스를 공개해, ASF 라이터 필터는 IConfigAsfWriter 인터페이스를 공개한다. 이러한 인터페이스를 사용해, 출력 파일의 포맷을 설정할 수가 있다. ASF 파일의 경우는, 소프트웨어 증명서도 주지 않으면 안 된다. 상세한 것에 대하여는, 「DirectShow 에서의 ASF 파일의 생성」을 참조할것.

주 : ICaptureGraphBuilder2::AllocCapFile 메소드를 사용해, 캡춰 파일을 미리 할당해 두는 것을 추천한다. 미리 할당한 큰 파일에 캡춰 하면, 캡춰의 퍼포먼스가 향상한다.

스트림의 렌더링

캡춰 그래프 생성의 최종 스텝은, 그래프내의 스트림의 렌더링이다. 파일 캡춰의 경우, 캡춰 핀은, 전에 설명한 파일 기입 섹션에 접속된다. 프리뷰의 경우, 프리뷰 핀은 오디오 및 비디오 렌더러에 접속된다. 다만, 캡춰 필터에 프리뷰 핀이 없는 경우는, 대신에 캡춰 핀을 사용해야 한다. 같은 핀을 캡춰와 프리뷰에 사용하기 위해서는, 캡춰 핀은스마트티 필터 에 접속되어 있지 않으면 안 된다. 이 필터는, 데이터를 캡춰 스트림과 프리뷰 스트림의 2 개 로 분리한다.

다음의 그림은, 스마트티피르타를 사용하는 그래프를 나타낸다.

ICaptureGraphBuilder2::RenderStream 메소드가, 이러한 태스크를 모두 처리해, 필요한 경우는 스마트티피르타를 추가한다. 이 메소드는, WDM 디바이스에 필요한 지원 필터도 자동적으로 추가한다. 이하의 코드는, 파일 캡춰용의 비디오 스트림을 렌더링 한다.

pBuilder->RenderStream(
        &PIN_CATEGORY_CAPTURE,  // 핀 카테고리
        &MEDIATYPE_Video,       // 미디어 타입
        pSrc,                   // 캡춰 필터
        NULL,                   // 압축 필터 (옵션)
        ppf                     // 멀티플렉서 또는 렌더링 필터
    );

최초의 2 개의 파라미터로, 핀 카테고리와 미디어 타입을 지정한다. 거기에 계속되는 3 개의 파라미터는, 이하의 필터에의 포인터이다.

  • 캡춰 필터.
  • 스트림을 압축하기 위한 옵션의 압축 필터 (이 예에서는 사용하고 있지 않다).
  • 멀티플렉서 또는 렌더링 필터. 파일 기입 섹션의 생성으로 설명한 것처럼,SetOutputFileName 메소드의 "ppf" 파라미터로 돌려주어지는 포인터를 사용한다.

프리뷰의 스트림을 렌더링 하려면 , 핀 카테고리에 PIN_CATEGORY_PREVIEW 를 사용해, 마지막 2 개의 파라미터에 NULL 를 사용한다. 캡춰 필터에 프리뷰 핀이 없는 경우, 캡춰 그래프 빌더는 자동적으로 스마트티피르타를 사용한다. 이하의 코드는, 비디오 프리뷰 스트림을 렌더링 한다.

pBuilder->RenderStream(
        &PIN_CATEGORY_PREVIEW,
        &MEDIATYPE_Video,
        pSrc,
        NULL,   // 압축 필터 없음
        NULL    // 디폴트의 렌더러
    );

렌더링 하는 미디어 타입 마다, 이러한 RenderStream 에의 호출을 반복한다.

주 : DV 캡춰 필터안에는, 인터리브 된 데이터 (MEDIATYPE_Interleaved)용으로 1 개의 핀을 가져, 비디오만의 데이터 (MEDIATYPE_Video)용으로별의 핀을 가지는 것이 있다. 양쪽 모두는 아니고, 어느쪽이든 한편을 렌더링 한다. 비디오 전용 핀을 렌더링 하는 경우, 캡춰 데이터는 오디오를 가지지 않는다.

그래프 프로퍼티의 설정

그래프내의 다양한 필터나 핀은, 프로퍼티를 설정 및 취득하기 위한 인터페이스를 공개하고 있는 경우가 있다. ICaptureGraphBuilder2::FindInterface 메소드를 사용해, 그러한 인터페이스에의 포인터를 취득한다.

어플리케이션에 따라서 다르지만, 이하의 겉(표)에 있는 인터페이스가 도움이 된다고 생각된다.

IAMAudioInputMixer | 오디오 입력 프로퍼티를 설정한다.
IAMDroppedFrames | 드롭 프레임 정보를 취득한다.
IAMVfwCaptureDialogs | Microsoft® Video for Windows® 의 캡춰 드라이버용으로 제공되는 다이알로그 박스를 표시한다.
IAMVideoCompression | 압축 파라미터를 설정한다.

이하의 코드는, 인터리브 된 오디오/비디오 핀으로부터 IAMDroppedFrames 인터페이스를 취득한다.

IAMDroppedFrames *pDropped = NULL;
pBuilder->FindInterface(&PIN_CATEGORY_CAPTURE, &MEDIATYPE_Interleaved,
    pSrc, IID_IAMDroppedFrames, (void **) &pDropped);

다만, 비디오 재생 윈도우를 제어하기 위한 메소드가 포함되는 IVideoWindow 인터페이스를 취득하는 경우는,FindInterface 메소드를 호출하지 않는다. 대신에, 필터 그래프에 이 인터페이스의 유무를 문의한다. 그렇게 하지 않으면 화면 해상도등의 이벤트에 필터 그래프가 올바르게 응답하지 않게 된다. IVideoWindow 를 사용 하면, 프리뷰 윈도우를 어플리케이션 윈도우의 자식 윈도우로 할 수 있다. 상세한 것에 대하여는, 「비디오 윈도우의 설정」을 참조할것.

주 : 프리뷰 스트림을 렌더링 하지 않을 때에서도, 캡춰 그래프 빌더는 프리뷰 윈도우를 추가하는 일이 있다. 일부의 하드웨어 디바이스는, 비디오 캡춰를 위해서(때문에) 비디오 포토 extension (VPE)를 사용하므로 프리뷰 윈도우가 필요하게 된다. 그 때문에, 항상 필터 그래프에 IVideoWindow 의 유무를 문의하는 것이 좋을 것이다. 필터 그래프가 이 인터페이스를 공개하고 있는 경우는, 비디오 윈도우를 어플리케이션 윈도우의 자식 윈도우로 한다.

캡춰 그래프의 제어

필터 그래프의 IMediaControl 인터페이스에는, 그래프 전체를 실행, 정지, 및 포즈하기 위한 메소드가 있지만, 그래프에 복수의 스트림이 있는 경우는 그것들을 독립해 제어하고 싶은 것이 있다. 예를 들어, 캡춰 스트림을 정지한 상태로 프리뷰 스트림을 실행하는 경우나, 프리뷰의 사이는 오디오를 뮤트 해, 파일 캡춰의 사이는 유효하게 하는 것 같은 경우다.

ICaptureGraphBuilder2::ControlStream 메소드가, 각각의 스트림의 시작 타임과 종료 타임을 설정하는 수단을 제공한다. IMediaControl::Run 를 호출하기 전에, 이 메소드를 호출한다. Run 를 호출하면,ControlStream 의 호출에 포함되지 않는 스트림이 즉시 시작 된다.

이하의 코드는, 비디오 캡춰 스트림을 2 초의 위치로부터 시작 해, 5 초의 위치에서 정지한다.

IMediaControl   *pControl;
REFERENCE_TIME  rtStart = 20000000,
                rtStop = 50000000;

pBuilder->ControlStream(
        &PIN_CATEGORY_CAPTURE,
        &MEDIATYPE_Video,
        pSrc,       // 소스 필터
        &rtStart,   // 시작 타임
        &rtStop,    // 종료 타임
        0,          // 시작 쿠키
        0           // 정지 쿠키
    );
pGraph->QueryInterface(IID_IMediaControl, (void **) &pControl);
pControl->Run();

최초의 3 개의 파라미터로, 핀 카테고리, 미디어 타입, 및 캡춰 필터에 의해 제어하는 스트림을 지정한다. 마지막 2 개의 파라미터는, 시작 및 정지의 이벤트를 식별하기 위해서 사용할 수 있는 쿠키다. 쿠키는, 어플리케이션으로 정의하는 임의의 값이다. 상세한 것에 대하여는, 「ICaptureGraphBuilder2::ControlStream 」를 참조할것.

복수의 스트림을 한 번에 제어하는 경우는, 미디어 타입과 소스 필터를 생략 한다. 이하의 예에서는, 그래프내의 모든 캡춰 스트림을 제어하고 있다.

pBuilder->ControlStream(&PIN_CATEGORY_CAPTURE, NULL, NULL,
    &rtStart, &rtStop, 0, 0);
pControl->Run();

디바이스의 삭제

그래프가 사용하고 있던 플러그 앤 플레이 디바이스를 유저가 삭제 하면, 필터 그래프 매니저가 EC_DEVICE_LOST 이벤트를 발행한다. 그 디바이스가 다시 사용 가능하게 되면(자), 필터 그래프 매니저는 한번 더 EC_DEVICE_LOST 이벤트를 송신한다. 그러나, 캡춰 그래프의 전 상태는 올바르지 않게 된다. 어플리케이션은, 디바이스를 사용하기 위해서 그래프를 재생성 해야 한다. 상세한 것에 대하여는, 「DirectShow 에서의 이벤트 통지」를 참조할것.


디지털 비디오

이 주제에서는, 디지털 비디오 (DV) 어플리케이션으로 Microsoft® DirectShow® 를 사용하는 방법을 해설한다. 이하의 항목으로 구성된다 :

  • DirectShow 에서의 디지털 비디오
  • DV 캠 코다의 제어


DirectShow 에서의 디지털 비디오

이 주제에서는, Microsoft® DirectShow® 에서의 디지털 비디오 (DV)의 사용 방법의 개요에 대해 설명한다. 이하의 섹션으로 구성된다.

  • DV 의 시나리오
  • type-1 파일과 type-2 파일
  • DirectShow 의 DV 필터
  • MSDV 드라이버

DV 의 시나리오

DV 를 취급하는 경우, 데이터는 디바이스로부터 컴퓨터에 이동하고, 또 디바이스에 돌아온다고 하는 라이프 사이클을 더듬는 것이 보통이다. DirectShow 는, 이하의 겉(표)에 나타나는 것 같은 각 단계를 지원 하고 있다.

단계 | DirectShow 의 지원 | 참조
카메라로부터 파일에의 비디오의 캡춰 | ICaptureGraphBuilder2 | 캡춰 어플리케이션의 쓰는 법
파일의 편집 | DirectShow 편집 서비스 |
파일의 재생 | IGraphBuilder::RenderFile | 파일의 재생법
파일로부터 테이프에의 송신 | WDM 비디오 캡춰 필터의 디바이스 컨트롤 인터페이스 | DV 캠 코다의 제어

type-1 파일과 type-2 파일

DV 카메라는, 인터리브 된 오디오-비디오를 생성한다. 비디오의 각 프레임에는, 오디오 데이터도 포함되어 있다. DV 데이터를 AVI 파일에 보존하는 경우, 이하의 옵션이 있다.

  • 인터리브 된 네이티브 데이터를, 데이터형 ivas 로, 단일의 스트림으로서 AVI 파일에 포함할 수가 있다. 이것을 type-1 파일이라고 부른다.
  • DV 데이터를, 데이터형 auds 및 vids 로서 다른 오디오 스트림과 비디오 스트림에 분할할 수 있다. 이것을 type-2 파일이라고 부른다.

비디오 캡춰의 경우, 최대의 throughput가 괴로운 장면에서는 데이터를 type-1 로서 보존하는 (분)편이 좋다. type-2 파일에는 장황한 데이터가 포함되기 때문이다. type-2 파일의 비디오 스트림에는, 아직 오디오 데이터가 포함되어 있지만, 스트림을 비디오로서 라벨 붙이고 하는 것으로 오디오 데이터는 숨겨지고 있다. 또, 인터리브 된 스트림을 분할하기 위해서, 어느 정도의 프로세서 타임이 필요하게 된다.

한편, type-1 포맷은 리얼타임 편집의 경우에 문제가 있다. 어플리케이션은, 인터리브 된 스트림으로부터 오디오 데이터를 추출해, 편집하고 나서 한번 더 데이터를 인터리브 해야 한다. 또, type-1 포맷은 Microsoft® Video for Windows® (VfW)와 호환성이 없다. DirectShow 는, 양쪽 모두의 타입의 파일을 취급할 수가 있다.

DirectShow 의 DV 필터

DirectShow 는, DV 데이터의 조작용으로 이하의 필터를 제공하고 있다.

  • DV 스플리터 : 인터리브 된 스트림을, 다른 오디오 스트림과 비디오 스트림에 분할한다.
  • DV Muxer : 오디오 스트림과 비디오 스트림을, 1 개의 인터리브 된 스트림에 결합한다.
  • DV 비디오 디코더 : DV 비디오 스트림을 비압축 비디오에 디코드한다.
  • DV 비디오 엔코더 : 비압축 비디오 스트림을 DV 비디오에 encode 한다.

이러한 필터는, 다음의 그림에 나타내도록(듯이) 대가 되어 기능한다. DV 스플리터가 type-1 를 type-2 에 분할해, DV 비디오 디코더가 type-2 비디오를 비압축 비디오로 변환한다.

반대 방향에는, DV 비디오 엔코더가 비압축 비디오를 type-2 비디오로 변환해, DV Muxer 가 type-2 스트림을 type-1 스트림에 결합한다.

DV 비디오 엔코더가 공개하는 IDVEnc 인터페이스에, encode 규격 (NTSC 나 PAL)을 설정하기 위한 메소드가 포함되어 있다. DV 비디오 디코더가 공개하는 IIPDVDec 인터페이스에는, 디코드 해상도를 설정하기 위한 메소드가 포함되어 있다.

MSDV 드라이버

Microsoft® Windows® 는, DV 캠 코다전용 MSDV (Msdv.sys)라고 하는 WDM 드라이버를 제공하고 있다. 이 드라이버는 어플리케이션에 WDM 비디오 캡춰 필터를 export 한다. MSDV 는 그 필터의 참조 페이지에 기술되고 있는 인터페이스의 서브 세트를 지원 한다. 유저의 시스템으로 DV 캠 코다를 사용할 수 있는 경우, 시스템 디바이스를 열거 하면, 비디오 캡춰 소스 카테고리 (CLSID_VideoInputDeviceCategory)에 캠 코다가 나타난다. 그것은 또 렌더링 디바이스로서 표시된다. 그 프렌들리명은, "Microsoft DV Camera and VCR. " 가 된다. 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것.

MSDV 에는 출력 핀이 2 개 있다. 1 개(살)은, 인터리브 된 오디오-비디오 데이터를 출력해, 이제 1 개(살)은 오디오를 포함하지 않는 비디오 데이터를 출력한다. MSDV 에는 입력 핀이 1 개 있어, 이 핀은 데이터를 캠 코다에 송신한다. 캠 코다는 캡춰와 송신을 동시에 실시할 수 없기 때문에, MSDV 가 입출력을 동시에 접속할 것은 없다.

MSDV 의 사용 위에의 힌트:

  • IGraphBuilder::Render 메소드를 사용해 MSDV 의 출력 핀을 접속할 수 없다. 필터 그래프 매니저는, 출력 핀을 MSDV 자체의 입력 핀에 접속하려고 한다. MSDV 는 접속을 거부해, 메소드 호출은 실패한다. 대신에,IGraphBuilder::Connect 또는 ICaptureGraphBuilder2::RenderStream 를 사용하는 것.
  • MSDV 가 필터 그래프내에 있을 때는, MSDV 를 항상 그래프의 기준 클락으로서 기능시켜야 한다. DirectX 8.0 으로부터는, 필터 그래프 매니저가 자동적으로 MSDV 를 기준 클락으로서 선택한다. 그것보다 전의 버젼에서는, 필터 그래프 매니저의 IMediaFilter::SetSyncSource 메소드를 호출하지 않으면 안 된다. 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.


DV 캠 코다의 제어

이 주제에서는, Microsoft® DirectShow® 를 사용해 디지털 비디오 (DV) 캠 코다를 제어하는 방법을 설명한다. 이하의 섹션으로 구성된다.

  • 개요
  • 디바이스의 정보
  • 디바이스의 제어
  • 송신
  • 보충 자료

DirectShow 에서의 DV 의 전반적인 정보에 대해서는, 「DirectShow 에서의 디지털 비디오」를 참조할것.

개요

WDM 비디오 캡춰 필터는, 캠 코다의 제어용으로 이하의 3 개의 인터페이스를 공개하고 있다.

IAMExtDevice | 외부 디바이스 제어용의 기본 인터페이스.
IAMExtTransport | VCR 기능을 제어한다.
IAMTimeCodeReader | 디바이스로부터 타임 코드를 읽어낸다.

캡춰 디바이스를 선택해, 캡춰 필터의 인스턴스를 생성한 후, 필터에 이러한 인터페이스의 유무를 문의한다. 이하의 예에서는, 인터페이스 포인터와 함께, 각 인터페이스의 이용 가능성을 나타내는 불리언 값을 보관 유지하는 커스텀 구조체를 선언하고 있다.

struct _MyDevCap
{
    IAMExtDevice       *pDevice;
    IAMExtTransport    *pTransport;
    IAMTimecodeReader  *pTimecode;
    BOOL                bHasDevice;
    BOOL                bHasTransport;
    BOOL                bHasTimecode;
} MyDevCap;

HRESULT hr;
IBaseFilter *pDVCam;  // 캡춰 필터에의 포인터.

// 캡춰 필터의 인스턴스를 생성한다 (표시되지 않는다).

hr = pDVCam->QueryInterface(IID_IAMExtDevice, (void **) &MyDevCap.pDevice);
MyDevCap.bHasDevice = (SUCCEEDED(hr));

hr = pDVCam->QueryInterface(IID_IAMExtTransport, (void **) &MyDevCap.pTransport);
MyDevCap.bHasTransport = (SUCCEEDED(hr));

hr = pDVCam->QueryInterface(IID_IAMTimecodeReader, (void **) &MyDevCap.pTimecode);
MyDevCap.bHasTimecode = (SUCCEEDED(hr));

주 : DV 캠 코다 드라이버의 Msdv.sys 와 함께 이러한 인터페이스를 사용하는 경우는, 헤더 파일 XPrtDefs.h 를 프로젝트에 포함한다. 이 파일은,msdn.microsoft.com/library/techart/dvsupport.htm 로부터 입수할 수 있다.

디바이스의 정보

디바이스 컨트롤 인터페이스를 사용 하면, 디바이스 상태와 능력을 문의할 수가 있다. 이 섹션에서는, 몇개의 취득 가능하고 유익한 항목에 대해 설명한다. 상세한 것에 대하여는, 인터페이스의 레퍼런스를 참조할것.

디바이스 타입

캡춰 디바이스에 관한 정보로 가장 중요한 것은, 디바이스의 타입이다. 디바이스가 VCR 기능을 가지고 있는지, 단순한 카메라인가라고 하는 정보다. 디바이스 타입을 취득하려면 , 값 ED_DEVCAP_DEVICE_TYPE 를 사용해 IAMExtDevice::GetCapability 메소드를 호출한다. 이 메소드가 값 ED_DEVTYPE_VCR 를 돌려주었을 경우, 디바이스는 VCR 이며, 포즈, 정지, 빨리 감기, 권반환등의 기능을 가지고 있다. 이하의 코드에, 디바이스 타입을 문의하는 방법을 나타낸다.

if (MyDevCap.bHasDevice)
{
    LONG lDeviceType = 0;
    MyDevCap.pDevice->GetCapability(ED_DEVCAP_DEVICE_TYPE, &lDeviceType, 0);

    if (lDeviceType == ED_DEVTYPE_VCR) {
        // 디바이스는 VCR 이다. 모든 VCR 기능을 유효하게 한다.
    }
    else {
        // 디바이스는 카메라이다.
        // 녹화와 녹화 포즈를 유효하게 해, 그 외의 기능은 무효로 한다.
    }
}

주 : 보통, 캠 코다는 VCR 기능과 카메라 기능동안에서 바꿀 수가 있어 거기에 응한 디바이스 타입을 돌려준다. 캠 코다가 오프 라인이 되었을 경우, 다음에 사용 가능하게 되었을 때에 한번 더 문의할 필요가 있다. 디바이스가 삭제되면(자), 필터 그래프 매니저가 EC_DEVICE_LOST 이벤트를 송신한다. 상세한 것에 대하여는, 「캡춰 어플리케이션의 쓰는 법」을 참조할것.

디바이스의 전송 상태

재생, 포즈, 정지 등, 디바이스의 현재 상태를 취득하려면 ,IAMExtTransport::get_Mode 메소드를 호출한다. 이 메소드는, 디바이스 상태를 나타내는 이하와 같은 정수를 취득한다.

값 | 디바이스 상태
ED_MODE_PLAY | 재생
ED_MODE_STOP | 정지
ED_MODE_FREEZE | 포즈
ED_MODE_FF | 빨리 감기
ED_MODE_REW | 되감아
ED_MODE_RECORD | 녹화
ED_MODE_RECORD_FREEZE | 녹화 포즈

타임 코드

DV 테이프가 재생중, 또는 녹화 포즈 모드의 사이는,IAMTimecodeReader::GetTimecode 메소드를 호출해, SMPTE 타임 코드 또는 절대 트럭 번호를 취득할 수가 있다. 이 메소드는, 타임 코드를 기술하는 TIMECODE_SAMPLE 구조체에의 포인터를 받는다. 이 메소드를 호출하기 전에, 구조체의 dwFlags 멤버를 초기화한다. 타임 코드를 취득하는 경우는 값 ED_DEVCAP_TIMECODE_READ 를 사용해, 절대 트럭 번호를 취득하는 경우는 값 ED_DEVCAP_ATN_READ 를 사용한다.

TIMECODE_SAMPLE 구조체의 timecode 멤버가,TIMECODE 구조체이다. 메소드가 돌아오면(자), TIMECODE 구조체의 dwFrames 멤버에 타임 코드 또는 트럭 번호가 저장 되고 있다. 타임 코드의 경우는, 시간, 분, 초, 및 프레임이, hhmmssff 의 포맷으로 2 진화 10 진법 (BCD)의 값으로서 DWORD 에 팩 되고 있다. 비트 마스크를 사용해 각각의 값을 꺼낸다.

이하의 예에서는, 타임 코드와 트럭 번호를 꺼내고 있다. 정보를 표시하는 함수 DisplayTimecode 과 DisplayTrackNum 는, 어플리케이션으로 정의되고 있는 것으로 한다.

if (MyDevCap.bHasTimecode)
{
    TIMECODE_SAMPLE TimecodeSample;
    TimecodeSample.timecode.dwFrames = 0;
    char szBuf[32];

    TimecodeSample.dwFlags = ED_DEVCAP_TIMECODE_READ;
    if (hr = MyDevCap.pTimecode->GetTimecode(&TimecodeSample), SUCCEEDED(hr))
    {
        wsprintf(szBuf, "TIMECODE %. 2x : %. 2x : %. 2x : %. 2x",
                (TimecodeSample.timecode.dwFrames & 0xFF000000) >> 24,
                (TimecodeSample.timecode.dwFrames & 0x00FF0000) >> 16,
                (TimecodeSample.timecode.dwFrames & 0x0000FF00) >> 8,
                (TimecodeSample.timecode.dwFrames & 0x000000FF));
        DisplayTimecode(szBuf);
    }

    TimecodeSample.dwFlags = ED_DEVCAP_ATN_READ;
    if (hr = MyDevCap.pTimecode->GetTimecode(&TimecodeSample), SUCCEEDED(hr))
    {
        wsprintf(szBuf, "%d", TimecodeSample.timecode.dwFrames);
        DisplayTrackNum(szBuf);
    }
}

디바이스의 제어

디바이스를 제어하려면 ,IAMExtTransport::put_Mode 메소드를 호출해, 전의 섹션으로 가리킨 정수의 1 개를 사용해 새로운 상태를 지정한다. 예를 들어, 디바이스를 정지하려면 , 이하의 코드를 사용한다.

MyDevCap.pTransport->put_Mode(ED_MODE_STOP);

다만, 캠 코다는 물리 디바이스이므로, 커멘드를 발행하고 나서 그것이 완료하기까지 어느 정도 시간이 걸린다. 그 때문에, 어플리케이션은 커멘드의 완료를 기다리는 2차 thread를 생성 해 둘 필요가 있다. 커멘드가 완료 하면, 그 thread가 유저 인터페이스를 갱신할 수 있다. 상태 변화가 차례로 행해지도록(듯이), 크리티컬 섹션을 사용한다.

캠 코다안에는, 디바이스 상태가 변화했을 때에 어플리케이션에 통지할 수 있는 것이 있다. 디바이스가 이 기능을 지원 하고 있는 경우, 2차 thread는 그 통지를 기다릴 수가 있다. 지원 하고 있지 않는 경우, 어플리케이션은 디바이스를 정기적으로 폴링 해야 한다.

통지

최초로, 크리티컬 섹션의 변수, 이벤트, 및 thread 핸들을 선언한다. 크리티컬 섹션은, 디바이스 상태를 동기 하기 위해서 사용한다. 이벤트는, 어플리케이션이 종료했을 때에 2차 thread를 종료시키기 위해서(때문에) 사용한다.

CRITICAL_SECTION csIssueCmd;
HANDLE           hThreadEndEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
HANDLE           hThread = 0;

캡춰 필터의 인스턴스를 생성한 후, 2차 thread를 생성 한다.

DWORD ThreadId;
hThread = CreateThread(NULL, 0, ThreadProc, 0, 0, &ThreadId);

2차 thread 중(안)에서,IAMExtTransport::GetStatus 메소드를 2 회 호출한다. 최초의 호출에서는, 값 ED_NOTIFY_HEVENT_GET 를 건네주어, 처리의 완료시에 통지제상태가 되는 이벤트의 핸들을 취득한다.

HANDLE hEvent = NULL;
hr = MyDevCap.pTransport->GetStatus(ED_NOTIFY_HEVENT_GET, (long *) &hEvent);

2 번째의 호출에서는, 디바이스 상태를 받는 변수에의 포인터와 함께, 값 ED_MODE_CHANGE_NOTIFY 를 건네준다.

LONG State;
hr = MyDevCap.pTransport->GetStatus(ED_MODE_CHANGE_NOTIFY, &State);

디바이스가 통지를 지원 하고 있는 경우, 이 호출의 반환값은 E_PENDING 이다. 다음에, 이벤트가 통지제상태가 되는 것을 기다린다. 다음의 처리가 완료 하면, 이벤트가 통지제상태가 되어, State 의 값으로 디바이스의 새로운 상태가 지정된다. 여기서, 새로운 상태를 반영하도록(듯이) 유저 인터페이스를 갱신할 수 있다.

이하의 코드에, 완전한 thread의 처리를 나타낸다. 유저 인터페이스를 갱신하는 UpdateTransportState 함수는, 어플리케이션으로 정의되고 있는 것으로 한다. thread는 2 개의 이벤트를 기다리는 것에 주의하면 좋겠다. 통지 이벤트 (hEvent)와 thread 종료 이벤트 (hThreadEndEvent)이다. 또, 디바이스 상태의 변수를 보호하기 위해서, 크리티컬 섹션을 사용하고 있는 부분에도 주의 해야 한다.

DWORD WINAPI ThreadProc(void *pParam)
{
    HRESULT hr;
    HANDLE  EventHandles[2];
    HANDLE  hEvent = NULL;
    DWORD   WaitStatus;
    LONG    State;

    // 다음의 처리가 완료했을 때에 통지제상태가 되는 이벤트를 취득한다.
    hr = MyDevCap.pTransport->GetStatus(ED_NOTIFY_HEVENT_GET, (long *) &hEvent);

    while (hThread && hEvent && hThreadEndEvent) {
        EnterCriticalSection(&csIssueCmd);
        State = 0;
        hr = MyDevCap.pTransport->GetStatus(ED_MODE_CHANGE_NOTIFY, &State);
        LeaveCriticalSection(&csIssueCmd);

        if(hr == E_PENDING) {             // 디바이스는 통지를 지원 하고 있다.
            EventHandles[0] = hEvent;
            EventHandles[1] = hThreadEndEvent;
            WaitStatus = WaitForMultipleObjects(2, EventHandles, FALSE, INFINITE);
            if(WAIT_OBJECT_0 == WaitStatus) {
                UpdateTransportState(State);
            }
            else {
                break;  // 이 thread를 종료한다.
            }
        }
        else {
            break;  // 이 thread를 종료한다 (디바이스는 통지를 지원 하고 있지 않다).
        }

    } // while

    // 통지를 캔슬한다.
    hr = MyDevCap.pTransport->GetStatus(ED_NOTIFY_HEVENT_RELEASE, (long *) &hEvent);
    return 1;
}

이하와 같이, 디바이스에 커멘드를 발행할 경우에도 크리티컬 섹션을 사용한다.

// "정지 " 커멘드를 발행한다.
EnterCriticalSection(&csIssueCmd);
    if(hr = MyDevCap.pTransport->put_Mode(ED_MODE_STOP), SUCCEEDED(hr))
        UpdateTransportState(ED_MODE_STOP);
LeaveCriticalSection(&csIssueCmd);

어플리케이션이 종료하기 전에, 2차 thread를 종료시킨다.

if (hThread)
{
    // 이 이벤트가 통지제상태가 되면(자), thread가 종료한다.
    if (SetEvent(ThreadEndEvent)) {
        // thread가 종료하는 것을 기다린다.
        WaitForSingleObjectEx(hThread, INFINITE, FALSE);
}
CloseHandle(hThreadEndEvent);
CloseHandle(hThread);

디바이스의 폴링

디바이스가 통지를 지원 하고 있지 않는 경우, 값 ED_MODE_CHANGE_NOTIFY 로 IAMExtTransport::GetStatus 를 호출하면, E_PENDING 이외의 값이 돌려주어진다. 그 경우는, 디바이스를 폴링 해 상태를 판정해야 한다.

여기에서도, 전에 설명한 것처럼 2차 thread와 크리티컬 섹션을 사용해야 하는 것이다. 이 thread는, 일정 간격으로 디바이스에 상태를 문의한다. 이하의 예에, thread의 이행법의 1 개를 나타낸다.

DWORD WINAPI ThreadProc(void *pParam)
{
    HRESULT hr;
    LONG State;
    DWORD WaitStatus;

    while (hThread && hThreadEndEvent)
    {
        EnterCriticalSection(&csIssueCmd);
        State = 0;
        hr = MyDevCap.pTransport->get_Mode(&State);
        LeaveCriticalSection(&csIssueCmd);
        UpdateTransportState(State);

        // 당분간의 사이, 또는 thread가 종료할 때까지 기다린다.
        WaitStatus = WaitForSingleObjectEx(hThreadEndEvent, 200, FALSE);
        if (WaitStatus == WAIT_OBJECT_0)
            break; // 여기서 thread를 종료한다.
                   // 그렇게 하지 않으면, 대기는 타임 아웃이 된다. 한번 더, 폴링을 실시한다.
    }
    return 1;
}

송신

디바이스 컨트롤 인터페이스를 사용해, DV 테이프로부터 컴퓨터 파일에 송신하거나 파일로부터 테이프에 송신하거나 한다.

  • 테이프로부터 파일에: 테이프로부터 파일에 송신하려면 , 생의 비디오를 캡춰 하는 경우와 같이 캡춰 그래프를 생성 한다. 캡춰 그래프의 생성 방법에 대해서는, 「캡춰 어플리케이션의 쓰는 법」을 참조할것. 필터 그래프를 실행하고 나서, 테이프를 재생한다. 송신을 정지하려면 , 테이프와 필터 그래프를 정지한다.
  • 파일로부터 테이프에: 파일로부터 테이프에 송신하려면 ,Async 파일 소스 필터를 디바이스 필터에 접속한다. 디바이스를 녹화 포즈 모드로 하고 나서, 필터 그래프를 포즈 한다. 포즈중, 필터 그래프는 비디오의 최초의 프레임을 반복하는 연속 스트림을 보낸다. 송신을 시작 하려면 , 디바이스를 녹화 모드로 하고 나서, 필터 그래프를 실행한다. 디바이스는, 녹화 헤드가 녹화 가능하게 되기까지 어느 정도 시간이 걸리기 (위해)때문에, 그래프를 실행하기 전에 2 초 정도 기다린다. 이렇게 하면(자), 테이프의 시작부에서 몇개의 프레임이 중복 하지만, 데이터가 없어지는 것이 없어진다.

다음의 그림은, 파일로부터 테이프에 송신하는 경우의 필터 그래프를 나타낸다.

보충 자료

「Digital Video Camcorder Support in Windows 98 and Windows 2000」 (www.microsoft.com/hwdev/vidcap/DVCam.htm )은, DV 캠 코다의 제어를 해설한 화이트 페이퍼이다.


WDM 비디오 캡춰에 대해

여기에서는, Microsoft® Windows® 드라이버 모델 (WDM) 및 Microsoft® DirectShow® 를 사용한 비디오 캡춰의 개요를 나타낸다. WDM 비디오 캡춰와 DirectShow 의 밀접한 관련성에 대해 설명한다.

또, 스트림 클래스와 WDM 접속 및 스트리밍 아키텍쳐 (CSA)의 밀접한 관련성, 비디오 캡춰 미니 드라이버 (스트림 클래스 드라이버의 클라이언트)에 대해 간단하게 설명한다. 다만, 여기서 설명하는 내용을 이해하려면 , 이러한 주제에 관한 기초지식이 필요하다. 배경 정보에 대해서는,http://www.microsoft.com/hwdev/desinit/ 를 참조할것.

여기에서는 다음의 내용에 대해 설명한다.

  • Windows 비디오 캡춰의 간단한 역사
  • WDM 의 개요
  • WDM 비디오 캡춰 아키텍쳐
  • 필터 그래프의 구성
  • WDM 의 캡춰 인터페이스와 필터

Windows 비디오 캡춰의 간단한 역사

마이크로 소프트는 1992 년에 Windows 3.1 용의 Video for Windows 1. x 를 릴리스 해, 디스크에의 동영상의 캡춰용으로 최적화했다. 이후, PCI 버스, bus master 링 콘트롤러, NT 스트라이프 세트, Fast/Wide SCSI 를 채용한 것과 캡춰 한 비디오를 어댑터 메모리로부터 디스크에 직접 전송 해, 데이터 카피를 사용하지 않게 한 것으로, 비디오 캡춰 레이트는 큰폭으로 향상했다. Video for Windows 는 현재 캡춰 레이트가 20 MB/초를 넘어 클라이언트수도 많지만, 비디오 회의의 출현에 의해 Video for Windows 아키텍쳐의 약점이 밝혀진 것으로부터, 새로운 비디오 캡춰 기술을 개발할 필요가 생겼다.

Video for Windows 아키텍쳐에는, 비디오 회의, 텔레비젼 시청, 비디오 필드의 캡춰나,수직 동기 간격 (VBI)등의 그 외의 데이터 스트림용의 중요한 기능이 빠져 있다. 이러한 제한에의 대응책으로서 벤더 각사는 제품 고유의 독자적인 확장 기능을 이행 해 Video for Windows 를 확장해 왔다. 그러나, 표준 인터페이스가 존재하지 않기 때문에, 확장 기능을 이용하는 어플리케이션은 하드웨어에 의존한 코드를 포함하지 않을 수 없다. Video for Windows 의 캡춰 드라이버와 디스플레이 드라이버는 밀접하게 결합하고 있다. 이것은, 캡춰 드라이버를 변경했을 경우는 디스플레이 드라이버도 변경해야 하는 것을 의미한다.

게다가 Video for Windows 의 인터페이스인 AVICap 와 DirectShow 의 편성은 효율적으로 동작하지 않는다. 이유는,AVICap 가 버퍼를 할당하기 때문이다. AVICap 를 통해 DirectShow 에 액세스 하면, 이행 천이의 시점에서 버퍼를 카피할 필요가 있어, 매우 효율이 나쁘다. DVD, MPEG 디코더, 비디오 디코더 및 튜너, 비디오 포토 extension (VPE ) 및 오디오 CODEC 가 단일의 어댑터에 통합된 것에 의해, 이것들 모든 디바이스를 지원 해, 리소스의 경합을 처리하는 통일 드라이버 모델이 요구되고 있었다.

WDM 의 개요

WDM 비디오 캡춰는, Video for Windows 아키텍쳐에 고유의 문제를 해결하기 위해서 개발되었다. WDM 비디오 캡춰의 주된 이점은 다음과 같다.

  • 32 비트 드라이버
  • DirectShow 와 CSA 의 협조
  • 비디오 캡춰 디바이스와 DVD/MPEG 디바이스의 사이에 공유되는, 하드웨어 (비디오 포토나 칩 세트 등) 용의 단일 클래스 드라이버 아키텍쳐
  • 텔레비젼 튜너와 입력 선택, 및 필드, VBI, 비디오 포토 extension (VPE)의 지원
  • Windows 98, Windows NT® 4. x, 및 Windows 2000 플랫폼에서 동작하는 1 종류의 드라이버

Video for Windows 어플리케이션에는 대규모 인스톨 베이스가 있기 (위해)때문에, 주로 동영상의 캡춰에 사용하는 디바이스에서는 Video for Windows 드라이버가 계속해 사용된다. 현재, 이러한 디바이스에 대한 operating system 지원을 제공하는 Video for Windows Version 1.1e 가, Windows 98 에 부속되어 있다. 다만, 주로 TV 의 시청과 비디오 회의에 사용하는 캡춰 디바이스에 대해서는, WDM 비디오 캡춰 아키텍쳐에 의해 최적인 지원이 제공된다.

DirectShow 는, Video for Windows 어플리케이션에 대한 하위 호환성을 갖추고 있어 게다가 Video for Windows 의 미비를 해결한다. WDM 비디오 캡춰의 목적은, USB 회의 카메라, 1394 DV 디바이스, 데스크탑 카메라, TV 시청, 복수 비디오 스트림, 및 VPE 캡춰에 대한 추가 지원을 제공하는 것이다. 이 지원은 커넬 베이스의 스트리밍에 의해 제공된다.

WDM 베이스의 스트리밍에서는, 커넬 접속을 제공해 DirectShow 의 비커넬 스트리밍을 확장하고 있다. 스트리밍 서비스는, WDM 스트림 클래스 드라이버 및 다른 프로세스간 시스템 소프트웨어 컴퍼넌트에 의해 처리된다. WDM 스트림 클래스 드라이버는, 미니 드라이버의 호출도 실시한다. 미니 드라이버는, 디바이스 고유의 컨트롤을 지원 하기 위해서 독립계 하드웨어 벤더 (IHV)에 의해 제공되는 하드웨어 고유의 동적 링크 라이브러리 (DLL)이다. 미니 드라이버와 마이크로 소프트 제공의 WDM 스트림 클래스 드라이버는, 제휴해 동작해, 지연 시간이 가장 적은 스트리밍을 실행하기 위해서 필요한 저레벨의 서비스를 제공한다. DirectShow 는, 어플리케이션에 고유의 상위 레벨의 기능을 제공한다. 스트림 클래스는, 표준 및 커스텀의 데이터형을 처리하는 통일파업 리밍모델을 지원 해, 유저 모드에의 이행이 불필요한 커넬 드라이버간에서의 데이터 전송을 지원 하고 있기 (위해)때문에, 사용 하면 높은 효율을 얻을 수 있는 모드이다.

이전의 DirectShow 필터는, 압축 해제나 렌더링등을 실행 하면 와, 필요에 따라서 커넬과의 데이터 전송을 실시하고 있었다. 그런데 , 그처럼 유저 모드로부터커넬 모드에 데이터 스트림이 이행 할 때마다, 이행 자체에 가세해, 파라미터의 검증과 시큐러티의 검증, 경우에 따라서는 데이터의 카피에 시간이 소비되고 있었다.

커넬 스트리밍에 의해, 유저 모드와 커넬 모드간의 스트림의 이행이 감소한다. 스트림의 일부 또는 전체를 커넬 모드로 생성해, 소비할 수 있다. 스트림을 커넬 모드로 처리하는 경우, DirectShow 의 필터는, 스트림을 송신하기 위한 컨트롤 메카니즘을 공개하는 것만으로 있다. 그 때문에, 몇번이나 반복해지는 모드 이행에 의한 오버헤드를 큰폭으로 삭감할 수 있다.

커넬 스트림은, 어플리케이션에 응한 적절한 시점에서 필터 그래프에 데이터를 건네줄 수가 있다. 다음의 그림은, 유저 모드에의 이행을 나타내고 있다.

비디오 캡춰의 실행시, 스트림 클래스는, 기입해 또는 렌더링하기 위한 압축되어 있지 않은 비디오 데이터를 비디오 캡춰 필터에 건네준다. 또, 커넬 스트리밍은 복수의 스트림을 지원 하기 위한(해), 스트림에 포함되는타임 코드나 클로우즈 캡션등의 다른 타입의 데이터를 동시에 건네주는 것이 가능하다.

WDM 비디오 캡춰 아키텍쳐

다음의 그림은, WDM 캡춰 아키텍쳐의 3 개의 기본 컴퍼넌트를 나타내고 있다.

WDM 캡춰 아키텍쳐

WDM 캡춰 아키텍쳐는 DirectShow 와 순조롭게 통합할 수 있도록(듯이) 설계되고 있기 (위해)때문에, WDM 캡춰 필터를 사용해 DirectShow 로 간단하게 캡춰 그래프를 구축할 수 있다. WDM 캡춰 필터는 DirectShow 로부터 스트리밍 클래스에 제어 메세지를 송신한다. Windows 98 디바이스 드라이버 킷 (DDK)에 포함되는 Ksproxy.ax, Kstune.ax, 및 Ksxbar.ax 필터를 사용 하면, USB (USB) 회의 카메라, 1394 DV 디바이스, TV 시청, 데스크탑 카메라의 데이터등의 WDM 스트리밍 데이터를 스트림 클래스에 의해 제어해, DirectShow 캡춰 그래프에 송신할 수가 있다. 다음의 그림은, 이러한 컴퍼넌트가 어떻게 기본 아키텍쳐에 통합되고 있는지를 나타내고 있다.

WDM 캡춰 아키텍쳐의 컴퍼넌트

이 그림에서는, Ksproxy.ax, Kstune.ax, Ksxbar.ax, 및 그 외의 DirectShow 필터가, 스트림 클래스와 직접 통신한다. Microsoft WDM 스트림 클래스는, CSA 에의 참가를 통해, 커넬 모드 컴퍼넌트간 또는 커넬 모드 드라이버와 유저 모드 컴퍼넌트간으로, 높은 대역폭으로 타임 스탬프 첨부의 지연 시간 중시 데이터 스트림을전송 한다. CSA 를 통해, 스트림 클래스와 DirectShow 의 편성은 다음의 점에 대해 효율적으로 동작한다. 즉, 미디어 타입을 공유하는 것, 유사한 스트리밍 상태 (정지, 포즈, 실행)를 가지는 것, 핀 및 접속에 관해서 같은 개념을 공유하는 것이다. 그 때문에, 스트림 클래스로부터 필터 그래프의 필터에, 데이터의 이행을 간단하게 실시할 수 있다.

Ksproxy.ax, Kstune.ax, 및 Ksxbar.ax 필터에는, 각각을 지원 하는 미니 드라이버 (또는 3 개(살) 모든 것을 지원 하는 미니 드라이버)가 필요하다. 비디오 캡춰 미니 드라이버는, 스트림 클래스의 클라이언트이며, 비디오 이미지와 관련 데이터의 스트림을 생성하는 하드웨어 디바이스를 제어한다. 이 미니 드라이버에는 다음의 기능이 있다.

  • 압축 및 비압축 비디오 스트림, 수직 동기 간격 데이터, 타임 코드, 및 부가 데이터 스트림의 캡춰
  • TV 튜너, 비디오 루팅 디바이스, TV 오디오 컨트롤, 비디오 압력 등, 비디오 스트림에 관련지을 수 있었던 디바이스의 제어
  • WDM-CSA 와의 호환성

스트림 클래스 비디오 캡춰 드라이버는, 복수의 압축 및 비압축 비디오, 타임 코드, 클로우즈 캡션, 미처리의 VBI 데이터와 디코드한 VBI 데이터, 및 커스텀 데이터 포맷의 스트림을 복수 동시에 지원 할 수 있다. 드라이버는, 다른 데이터 타입과 동시에 생성할 수 있는 데이터 타입 마다 새로운 스트림을 생성 할 필요가 있다. 스트림 클래스는 각 스트림을 독립한 WDM-CSA 핀으로서 공개한다. 각 스트림을 다른 WDM-CSA 커넬 필터에 접속하는지, 유저 모드에 이행시켜, DirectShow 유저 모드 필터의출력 핀에 보낼 수가 있다. 각 스트림 (또는 핀)은, 다양한 포맷을 지원 할 수 있다. 예를 들어, 단일의 핀이 RGB16, RGB24, YVU9, 및 JPEG 디지털 비디오를 지원 할 수 있다. 미니 드라이버의 상세한 것에 대하여는, Windows 98 DDK 를 참조할것.

필터 그래프의 구성

DirectShow 필터와 CSA 의 관계에 의해, DirectShow 의 필터는, 커넬 모드의 스트림 클래스 드라이버로부터 데이터를 조작하는 강력해 비교적 안전한 방법이 되고 있다. DirectShow 는 유연하기 때문에, 다양한 필터 구성이 가능하다. 다음의 그림은, 비디오의 프리뷰와 디스크에의 캡춰를 동시에 실시하는 유저 모드 DirectShow 필터의 구성예를 나타내고 있다.

유저 모드 DirectShow 필터의 구성

이 그림에서는, 수신 TV 신호가 튜너 필터를 사용해 튜닝 되어 크로스바 필터를 사용해 루팅 된다. 필터 그래프는, 디스크에 보존하는 다양한 스트림의 데이터를 비디오 또는 오디오 캡춰 필터에 건네준다. 이것에는, 오디오 스트림, 비디오 스트림, 및 SMPTE 타임 코드나 클로우즈 캡션 데이터 등, 다양한 스트림의 그 외의 부가 데이터가 포함된다.

WDM 의 캡춰 인터페이스와 필터

커넬 스트리밍 필터에 의해 공개되는 WDM 캡춰 인터페이스는,IAMTVTuner ,IAMCrossbar ,IAMAnalogVideoDecoder ,IAMVideoProcAmp , 및 IAMCameraControl 이다.

WDM 용의 Windows 98 비디오 캡춰 필터에는, Ksproxy.ax, Kstune.ax, Ksxbar.ax 등이 있다. 이러한 필터의 상세한 것에 대하여는, Windows 98 DDK 를 참조할것.


캡춰 퍼포먼스의 향상

캡춰는, 할 수 있는 한 고속으로 대량의 정보를 디스크에 보존하는 것이 요구되는 하드웨어 집중형 조작이다. 캡춰 하는 정보는 비디오 및 오디오 데이터가 일반적이다. 시스템을 저속화 시키는 보틀 넥의 삭감은, 캡춰 한 동영상의 품질 향상을 위해서(때문에) 매우 중요하다.

여기에서는, 캡춰 어플리케이션을 사용할때나, 캡춰 퍼포먼스가 최적화되도록(듯이) 캡춰 시스템을 셋업 할 경우에 도움이 되는, 추천 되는 일반적인 조작 방법 및 힌트와 조언을 나타낸다.

주 : 반드시 사용하고 있는 캡춰 카드의 문서를 읽어, 캡춰 카드 고유의 정보를 확인하는 것. 시스템도 일정은 아니기 때문에, 여기에 나타내는 정보의 모든 것이 사용하고 있는 시스템 구성에 적용 하면은 한정되지 않는다.

여기에서는 다음의 내용에 대해 설명한다.

  • 캡춰 비디오 데이터의 바이트수의 계산
  • 캡춰에 맞춘 하드 디스크의 최적화
  • Windows 9x 에서의 디스크 설정
  • 캡춰에 관계하지 않는 머신 활동의 삭감
  • 캡춰 퍼포먼스 향상을 위한 그 외의 힌트와 조언

캡춰 비디오 데이터의 바이트수의 계산

캡춰는, 캡춰 카드로부터 디스크에의 대량의 데이터 전송을 수반한다. 특정의 캡춰의 시나리오에 있어서의 데이터의 양으로 요구되는 데이터의 throughput를 이해하기 위해서, 다음의 경우를 생각한다.

높이 320 픽셀, 폭 240 픽셀의 동영상을 캡춰 레이트 30 프레임/초 (fps), 24 비트 칼라 포맷으로 캡춰 하면 한다. 동영상에 소리는 들어가 있지 않다.

모든 이미지 데이터를 캡춰 해 화질을 유지하기 위해서는, 압축되어 있지 않은 데이터를 매초몇 바이트 전송 할 필요가 있을까를, 다음에 나타내는 식을 사용해 결정한다.

전송 하는 비디오 데이터의 바이트수 = 높이 (픽셀 단위) x 폭 (픽셀 단위) x 레이트 (fps 단위) x 색 가지수 (바이트 단위)

이 시나리오의 숫자를 적용시키면(자), 다음의 결과가 된다.

전송 하는 비디오 데이터는 320 x 240 x 30 x 3 = 6912000 바이트

이 동영상을 목적의 사이즈, frame rate, 및 색 가지수로 1 초간 캡춰 하려면 , 약 690 만 바이트의 디스크 영역이 필요하게 된다. 이것에 60 초를 걸면(자), 1 분간의 숫자가 요구된다. 이 경우는 매분의 캡춰에 414,720,000 바이트가 필요하게 된다. 필요한 데이터의 양을 줄이려면 , 이 식의 몇개의 파라미터의 값을 작게 한다. 즉, 사이즈의 작은 이미지를 캡춰 하는지, 매초 쯤의 프레임수를 줄이는지, 색 가지수를 줄인다. 다만, 이미지의 요구가 높기 위해(때문에) 시스템의 부하가 한계에 이르러, 매초 즈음해 가능한 최대 메가바이트수로 캡춰 하는 것이 요구되는 경우는, 시스템을 할 수 있는 한 최적화할 필요가 있다. 최종적으로, 재생시의 동영상의 표시에 영향을 주는 것은, 어떠한 캡춰 설정을 이용하는가 하는 것이다.

전에 나타낸 숫자는 소리가 없는 동영상의 예이다. 비디오와 동시에 오디오도 캡춰 하는 경우는, 필요한 오디오 데이터의 양을 늘릴 필요가 있다. 예를 들어, 44 킬로헤르츠 (kHz), 16 비트의 스테레오로 녹음된 CD 품질의 오디오의 경우, 매초 약 172 킬로바이트 (KB)가 필요하게 된다. 게다가 오디오 캡춰는 매우 CPU 집중형이며, 오디오 데이터와 비디오 데이터의 동기화 (입술의 움직임과 소리를 맞출 때 등)는 지연의 원인으로도 된다.

선택한 설정에 응한 필요한 데이터 전송량을 시스템으로 채울 수 없는 것도 있을 수 있다. 캡춰를 실행하는 경우, 시스템이 포즈 하는, 비디오의 움직임이 일정이 아니고 불안정 (순조롭지 않다), 일부의 프레임이 결핍 하고 있는 (디스크에 보존되어 있지 않다)등의 문제가 일어나는 일이 있다. 이러한 이미지를 재생한 품질은 일반적으로 만족할 수 있는 것은 아니다. 이러한 문제를 피하기 위해서(때문에), 캡춰에 맞추어 시스템을 최적화할 방법이 몇개인가 있다.

여기에 나타내는 추천 사항은, 캡춰 퍼포먼스를 최적화 하면 말하는 목표의 실현에 도움이 된다. 동시에, 시스템은 각각 다르기 (위해)때문에, 어느 시스템으로 퍼포먼스가 향상해도 다른 시스템에서는 효과가 없는 경우도 있으므로 주의 해야 한다.

캡춰에 맞춘 하드 디스크의 최적화

캡춰는 다량으로 하드 디스크를 소비하므로, 캡춰에 사용하는 하드 드라이브 (데이터 드라이브 또는 데이터 디스크라고도 불린다) 위에의 파일을 최적화하는 것은, 캡춰 퍼포먼스 최적화의 가장 중요한 작업이다. 다음의 일람은, 데이터 드라이브 최적화의 목표와 목표를 실현하기 위한 테크닉을 나타낸다. 여기에 나타내는 것은 추천 되는 테크닉이며, 특정의 캡춰 요건에 대해서는 효과적이 아닌 경우도 있다. 사용하는 테크닉은 요건과 자원에 응해 명확하게 정해진다.

  • 캡춰 파일이 데이터 드라이브가 연속한 (단편화하지 않았다) 장소에 저장 되고 있는 것.

    하드 드라이브의 헤드는, 연속적인 파일을 읽고 쓰기하는 (분)편이, 디스크 위에의별의 불연속인 장소를 시크 하지 않고 끝나기 (위해)때문에 효율적이다. Microsoft® Windows® 의 defrag (Defrag.exe)와 같은 툴을 사용해 데이터 디스크를 최적화한다. 데이터 드라이브와 operating system 드라이브의 양쪽 모두를 최적화한다. operating system 드라이브는, 드라이버 (오디오 드라이버나 비디오 드라이버등)를 사용할때, 시스템 캐쉬에 기입할 때, 레지스트리에 기입할 때, 오버레이를 사용할때 등에 사용된다. Windows 9x 스캔 디스크 툴을 실행해, 데이터 드라이브와 operating system 드라이브의 완전성을 확인한다.

  • 보존하는 무비 클립보다 큰 캡춰 파일을 미리 할당한다.

    파일 영역의 할당은 시간을 소비하므로, 캡춰의 전에 파일을 할당할 필요가 있다. 캡춰 한 데이터가 캡춰 파일에 들어가 싫은 있고 경우, 시스템은 파일을 위한 추가 영역을 할당하지 않으면 안되어, 이것도 캡춰 저속화의 원인이 된다. 필요하게 맞은 충분한 크기의 파일을 할당하는 것에 의해, 캡춰 실행중의 파일 영역 할당을 피해 저속화를 막는다. 캡춰 한 데이터를 보존하려면 원의 캡춰 파일과 같은 용량이 필요해서, 캡춰 한 파일을 별파일로서 보존 가능한 한의 빈영역이 하드 디스크에 없으면 안 된다. 캡춰 파일도 정기적으로 최적화하는 것.

  • 캡춰 파일용으로 하드 디스크 전체 또는 디스크 위에의 파티션을 할당한다.

    Microsoft® Windows NT® 4. x 와 Windows 2000 에는 스캔 디스크나 defrag 툴이 부속되지 않기 때문에, 이 테크닉이 특별히 도움이 된다. 디스크 전체 또는 디스크 패티션을 캡춰 파일 전용으로 하면(자), 캡춰 파일 영역이 정리된 연속적인 상태에 유지하기 쉽다. 이러한 디스크 또는 파티션은, 포맷 해 재차 파일 영역의 사전 할당을 실시하는 것이나, 디스크 또는 파티션외의 파일을 신경쓰지 않고 최적화를 실행할 수가 있다. 전용 캡춰 드라이브를 포맷 하면나무는, 디스크 위에의 낡은 데이터를 그대로 남기는 퀵 포맷은 아니고, 완전 포맷을 실행해 디스크를 초기화한다.

    데이터 드라이브가 정리된 상태에 유지하기 위해서(때문에), 캡춰 한 이미지는 데이터 드라이브 또는 데이터 파티션과는 다른 디렉토리에 보존한다. 드라이브 전체를 캡춰 전용으로 할 수 없는 경우는, 캡춰 파일용의 영역을 할당해 파일을 최적화하고 나서, (Windows 9x 의 경우) Windows 9x 스캔 디스크 툴을 실행한다.

  • 데이터 드라이브의 선두 (가장 외측)에 캡춰 파일을 둔다.

    캡춰 파일을 디스크 위에의 유일한 파일로서 할당했을 경우, 또는 디스크의 최초의 파티션의 유일한 파일로서 할당했을 경우는, 파일은 디스크의 외측으로부터 시작 한다. 하드 디스크의 외측의 부분에의 액세스는, 디스크의 안쪽의 부분에의 액세스보다 고속으로 있다. 캡춰 전용으로 할 수 있는 하드 드라이브가 없는 경우는, 디스크 유틸리티를 사용해 캡춰 파일을 디스크의 시작 위치로 이동할 수 있다.

캡춰 세션마다 필요에 따라서 이러한 목표를 재확인해, 디스크가 최적인 퍼포먼스를 실현하도록(듯이) 설정되어 있는 것을 확인하는 것. 매회 캡춰 세션의 전에 데이터 디스크를 최적화해, 보존한 파일을 재생하기 전에, 보존한 이미지를 포함한 드라이브를 최적화한다.

Windows 9x 에서의 디스크 설정

Windows 9x 컨트롤 패널의 [시스템] 아이콘에는, 캡춰 퍼포먼스를 최적화하기 위해서 오프로 할 수 있는 옵션이 몇개인가 있다. 캡춰와 같이 높은 대역폭의 상황에서는, 가능한 최대한의 데이터를 드라이브에 기입하는 것으로, 소프트웨어 최적화 또는 시스템 변경의 체크에 시간을 소비하지 않는 것이 중요하다. 다음의 옵션을 오프로 한다.

  • CD-ROM 드라이브에 CD-ROM 디스크가 삽입되고 있는 경우의 자동 검출
  • 하드 디스크의 예측에 의한 최적화
  • 모든 드라이브의 지연 기입

Windows 9x 로 이러한 옵션에 액세스 하려면 ,[스타트] 메뉴를 클릭한다. [설정] 의 [컨트롤 패널] 을 클릭해,[시스템] 아이콘을 더블 클릭 한다. 목적의 탭을 클릭해, 다음에 나타내도록(듯이) 조작한다.

  • [디바이스 매니저] 탭 : [CD-ROM] 를 클릭해, CD-ROM 드라이브를 클릭한다. [프로퍼티] 를 클릭해,[설정] 탭을 클릭한다. 다음에 [삽입의 자동 통지] 를 오프로 한다.
  • [퍼포먼스] 탭 : [파일 시스템] 을 클릭해,[예측 잡기에 의한 최적화] 의 안주를 드러그 해 [없음] 로 한다 (디폴트는 [최대]). 계속 [파일 시스템의 프로퍼티] 다이알로그 박스로,[트러블 슈팅] 탭을 클릭해,[모든 드라이브에 지연 기입을 실시하지 않는] 을 온으로 한다.

새로운 설정을 유효하게 하려면 , 머신을 재기동할 필요가 있다.

주 : 다른 어플리케이션의 퍼포먼스를 최적화하기 위해서, 캡춰 세션 완료 후는 반드시 이러한 설정을 원의 값에 되돌리는 것.

캡춰에 관계하지 않는 머신 활동의 삭감

캡춰 이외의 목적으로 시스템에 끼어드는 원인 또는 CPU 시간을 소비하는 원인이 되는 것은 모두, 캡춰의 퍼포먼스를 저하시킬 가능성이 있다. 다음의 작업을 실행해 시스템의 퍼포먼스에 영향을 줄지 어떨지를 확인한다.

  • 캡춰 어플리케이션 이외의 모든 어플리케이션을 닫는다.
  • Windows 9x 의 태스크바에 시계를 표시하지 않게 한다. 그 때문에(위해)는, 태스크바를 오른쪽 클릭해,[프로퍼티] 를 클릭한다. 다음에 [태스크바 옵션] 의 [시계를 표시] 를 오프로 한다.
  • 스크린 세이버를 오프로 한다. 그 때문에(위해)는, 데스크탑을 오른쪽 클릭해,[프로퍼티] 를 클릭한다. [스크린 세이버] 탭을 클릭해,[스크린 세이버] 박스의 일람으로 "(없음) " 를 선택한다.
  • 프린터를 오프로 한다.
  • 네트워크 카드가 있는 경우는 무효로 한다. 특히 네트워크상에서 명시적인 조작을 실행하고 있지 않아도, 네트워크를 경유한 데이터의 송수신에 의해 시스템에 세치기가 발생할 가능성이 있다.

캡춰 퍼포먼스 향상을 위한 그 외의 힌트와 조언

여기에서는, 지금까지 가리킨 그 외의 추천 사항을 실행한 후에 시험하는 가치가 있는, 캡춰의 퍼포먼스를 향상시키기 위한 다양한 힌트와 조언을 나타낸다. 추천 사항은 하드웨어 관련과 소프트웨어 관련으로 나눌 수 있고 있다.

소프트웨어

  • Windows 2000 또는 Windows NT 4. x 로 캡춰를 실행하는 것을 검토한다. NT 베이스의 파일 시스템 (NTFS)은 thread를 사용하기 위해(때문에), 일반적으로 종래의 FAT 파일 시스템보다 고속으로 있다. Windows NT 로 동작하는 드라이버를 확인할 필요가 있는 경우는, 사용하고 있는 캡춰 카드의 제조원에 문의한다. 일부가 NTFS, 일부가 FAT 라고 하는 드라이브는 아니고, 완전한 NTFS 드라이브를 사용한다. FAT-32 파일 시스템은 일반적으로 FAT 파일 시스템보다 고속으로 있다.
  • 캡춰 소프트웨어를 사용해 다양한 압축율을 시험해 (예를 들어 2:1 나 1:1) , 보존해야 하는 데이터의 양을 줄인다. 처음은 디폴트의 압축율을 사용해, 프레임의 결핍이 발생할 때까지 압축율을 올린다. 3 으로 우리의 압축율을 시험해, 그 중에 가장 효율의 좋은 것을 사용한다. 캡춰 한 이미지를 다른 드라이브에 보존한 후, 표준 설정으로 스캔 디스크를 실행해, 드라이브를 재빠르게 최적화한다.
  • Windows 3.1 을 인스톨 한 컴퓨터에 Windows 9x 를 덧쓰기 인스톨 했을 경우는, Autoexec.bat 파일에 "verify=off" 를 추가한다. 이 행을 추가 하면, DOS 로 기입해 조작 후에 데이터가 올바르게 기입해진 것을 확인하기 위한 데이터 재독 보고 잡기를 하지 않는다. 검증은 기입해 조작을 저속화 시킨다.

하드웨어

  • PCI 슬롯 0 에 캡춰 카드를 삽입해, 시스템의 그 외의 카드보다 먼저 캡춰 카드가 검사되도록(듯이) 한다.
  • 데이터 드라이브에 대해서 하드 드라이브 캐쉬가 온이 되어 있는 것을 확인한다. 상세한 것에 대하여는, SCSI 카드의 문서를 참조할것.
  • 시스템 내부에 열이 쌓이면(자), 시스템 컴퍼넌트가 소모해 캡춰 퍼포먼스가 저하한다. 한 번에 수시간 연속해 캡춰를 실행하는 경우는, 시스템의 전원, CPU, 및 컴퍼넌트 (카드)에 각각 1 개(살)씩, 3 살의 팬이 뒤따르고 있는 것을 확인한다. 캡춰 한 이미지가 최초의 (분)편에서는 문제 없고, 당분간 캡춰를 계속한 후에 불안정하게 되었을 경우는, 캡춰 카드가 오버히트 하고 있을 가능성이 있다.
  • 일부의 캡춰 카드에는 오디오 카드가 짜넣어지고 있다. 온보드의 오디오 카드를 사용하는지, 독립한 오디오 카드를 사용할까는, 목적에 따라서 다르다. 독립한 오디오 카드를 사용하는 것으로 필요한 기능을 얻을 수 있는 경우도 있으면, 온보드의 오디오 카드로 충분히 목적을 완수할 수 있는 경우도 있다.
  • 일부의 캡춰 카드는 모니터용의 확장 접속을 갖추고 있기 (위해)때문에, 캡춰 하고 있는 내용을 프리뷰 하기 위해서 소프트웨어를 사용할 필요가 없다. 시스템에 프리뷰 윈도우를 표시하는 부하가 걸리지 않기 때문에, 이 기능은 퍼포먼스 향상에 도움이 된다.


캡춰에 관한 고도의 주제

이 주제에서는, 캡춰 어플리케이션에서의 Microsoft® DirectShow® 사용과 관계되는 몇개의 고도의 측면으로 도착해 설명한다. 그러나 대부분의 캡춰 어플리케이션에는 이 정보가 불필요하다. 이 주제는 「캡춰 어플리케이션의 쓰는 법」을 읽은 위에 참조할것.

대부분의 캡춰 어플리케이션에서는,ICaptureGraphBuilder2 인터페이스를 사용해 캡춰 그래프를 구축할 수 있다. 대부분의 캡춰 시나리오에는, 이 인터페이스로 적절히 대응할 수 있다. 다만, 필요한 그래프가 극단적으로 복잡한 경우는, 1 필터씩 수동으로 구축해야 한다. 이 경우에는,ICaptureGraphBuilder2 로 자동적으로 행해지는 처리를 세부까지 이해해 둘 필요가 있다. 또, 그래프를 수동으로 구축하는 경우에서도,ICaptureGraphBuilder2 의 FindInterface 메소드나 FindPin 메소드는 이용할 수 있다.

이 주제는, 이하의 섹션으로 구성된다 :

  • 재드로잉(Drawing) 이벤트
  • 핀 카테고리
  • 스마트티피르타의 사용법
  • 비디오 포토 핀
  • 자막 방송
  • VideoInfo2 포맷 타입
  • WDM 스트림 클래스 드라이버 필터

재드로잉(Drawing) 이벤트

유저가 프리뷰 윈도우에 거듭해 무엇인가를 표시해, 그것을 소거 하면, 비디오 렌더러는 WM_PAINT 메세지를 받아들인다. 디폴트에서는, 윈도우를 재표시하기 위해(때문에), 비디오 렌더러가 새로운 프레임을 요구한다. 파일 캡춰중에 이 상황이 발생 하면, 캡춰 파일이 파손해 사용할 수 없게 된다. 따라서, 캡춰 그래프가 파일에 데이터를 기입하는 경우에는, 재드로잉(Drawing) 이벤트의 디폴트 처리를 취소할 필요가 있다. 이것에는, 필터 그래프 매니저에 IMediaEvent 인터페이스를 조회해, 파라미터에 EC_REPAINT 이벤트 코드를 지정해 IMediaEvent::CancelDefaultHandling 메소드를 호출한다.

상세한 것에 대하여는, 「DirectShow 에서의 이벤트 통지」를 참조할것.

핀 카테고리

캡춰 필터에는, 목적이 다른 복수의 출력 핀을 갖게할 수가 있다. 예를 들어, 캡춰용과 프리뷰용으로 각각 독립한 핀을 가지는 캡춰 필터가 있다. 또, 프라이머리 비디오 스트림과는 별도로, 자막 방송 데이터를 건네주는 캡춰 필터도 있다. 핀의 기능은, 커넬 스트리밍 프로퍼티 세트로 식별한다. 여기에서는, 이하의 핀 카테고리에 대해 설명한다.
카테고리 GUID | 설명
PIN_CATEGORY_CAPTURE | 캡춰 핀
PIN_CATEGORY_PREVIEW | 프리뷰 핀
PIN_CATEGORY_VIDEOPORT | 비디오 포토 (VP) 핀
PIN_CATEGORY_CC | 자막 방송 핀
PIN_CATEGORY_VBI | 수직 동기 간격 (VBI) 핀
PIN_CATEGORY_VIDEOPORT_VBI | VBI 용의 비디오 포토 핀

캡춰 필터에는, 캡춰 핀이 적어도 1 개 있다. 또, 프리뷰 핀과 비디오 포토 핀의 어느 쪽인지가 붙어 있는 일도 있다, 다만 동시에 양쪽 모두가 붙을 것은 없다. 캡춰 핀과 프리뷰 핀은, 각각 다른 미디어 타입을 건네주기 위해서(때문에) 복수 사용할 수 있다. 이와 같이, 1 개의 필터가, 비디오용과 오디오용 각각의 캡춰 핀과 비디오용과 오디오용 각각의 프리뷰 핀을 가지는 일이 있다. 자막 방송과 VBI 는, TV 와 DVD 로 사용한다.

핀의 카테고리를 판단하려면 ,IKsPropertySet::Get 메소드를 호출한다. 이 프로퍼티 세트의 GUID 는 AMPROPSETID_Pin 이며, 프로퍼티 식별자는 AMPROPERTY_PIN_CATEGORY 이다. 이하의 샘플 코드는, 핀의 조회 방법을 나타낸다 :

IPin *pPin; // 캡춰 필터의 출력 핀에의 포인터.
IKsPropertySet *pKs;
HRESULT hr;

hr = pPin->QueryInterface(IID_IKsPropertySet, (void **) &pKs);
if (SUCCEEDED(hr))
{
    GUID PinCategory;
    DWORD cbReturned;
    hr = pKs->Get(AMPROPSETID_Pin, AMPROPERTY_PIN_CATEGORY, NULL, 0,
                        &PinCategory, sizeof(GUID), &cbReturned);
    if (SUCCEEDED(hr))
    {
        // PinCategory 에 카테고리 GUID 가 저장 되고 있다.
    }
    pKs->Release();
}

프로퍼티 세트의 상세한 것에 대하여는, Microsoft® Windows® Driver Development Kit (DDK)의 문서를 참조할것.

스마트티피르타의 사용법

각각 독립한 캡춰 핀과 프리뷰 핀이 있는 필터에서는, 한편으로 프리뷰 하면서, 이제(벌써) 한편으로 캡춰 할 수가 있다. 다만, 필터에 프리뷰 핀이 없는 경우에서도,스마트티 필터 를 사용해 같은 것을 실행할 수 있다. 이 필터는, 캡춰 핀으로부터의 데이터를, 캡춰용과 프리뷰용의 같은 2 개의 스트림에 분할한다.

다음의 그림은, 스마트티피르타가 있는 그래프를 나타낸다.

스마트 티 필터의 사용법

프리뷰와 캡춰를 1 개의 핀으로 커버하기 위해(때문에), 스마트티피르타는 이하의 최적화를 실시한다.

  • 캡춰의 퍼포먼스에 영향을 주지 않을 때에 마셔, 프리뷰 데이터를 건네준다.
  • 프리뷰 스트림으로부터 타임 스탬프를 삭제한다.

2 번째의 최적화에 대해서는 조금 설명이 필요하다. 그래프내에서의지연 시간이 원인이 되어, 라이브 데이터는 렌더링 필터에 조금 늦어 닿는다. 프리뷰 데이터에 타임 스탬프가 있으면(자), 지연을 해소하기 위해서 렌더러로 프레임이 드롭 되는 일이 있지만, 프레임을 아무리 드롭 해도 프레임의 지연은 해소되지 않는다. 타임 스탬프를 삭제하는 것에 의해, 프레임의 불필요한 드롭을 피할 수가 있다. 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

주 : 비디오 포토 핀은 일종의 프리뷰 핀으로서 취급할 수가 있으므로, VP 핀이 있는 필터에 스마트티피르타는 필요없다. 다만, VP 핀에는 특수한 요건이 몇개인가 있다. 다음의 섹션에서는, 이러한 요건에 대해 설명한다.

비디오 포토 핀

하드웨어 비디오 포토가 있는 캡춰 디바이스는, Microsoft® DirectX® 의 비디오 포토 extension (VPE)를 사용할 수 있다. 이 경우, 캡춰 필터는 비디오 포토 (VP) 핀을 가진다. VP 핀은오버레이 믹서 필터에 접속해, 오버레이 믹서는비디오 렌더링 필터에 접속할 필요가 있다.

VP 핀으로부터 필터 그래프를 통해서 비디오 데이터가 건네받을 것은 없다. 대신에, 하드웨어내에서 비디오 프레임이 생성되어 비디오 메모리에 직접 보내진다. VP 핀을 사용 하면, 하드웨어에 컨트롤 메세지를 송신할 수 있다. 캡춰 기능에만 흥미가 있는 경우에서도, VP 핀은 반드시 접속하는 것. 왜냐하면 VP 핀을 접속하지 않으면 캡춰 그래프는 동작하지 않는다. 이 점으로써, 미접속이라도 좋은 프리뷰 핀과는 다르다. VP 핀은 반드시 오버레이 믹서의 입력 핀 0 에 접속하는 것.

비디오 렌더링 필터는, 오버레이 믹서로부터 비디오 데이터를 취득하지 않는다. 다만, 비디오 윈도우는 비디오 렌더링 필터에 의해 제어되므로, 필터 그래프에는 이 필터를 포함할 필요가 있다. 필터 그래프 매니저에 IVideoWindow 인터페이스를 조회 하면, 비디오 윈도우를 어플리케이션 윈도우의 아이로 할 수 있다. 상세한 것에 대하여는, 「비디오 윈도우의 설정」을 참조할것.

다음의 그림은, 비디오 포토 핀이 있는 캡춰 그래프를 나타낸다.

비디오 포토 핀이 있는 필터 그래프

다음의 샘플 코드는, 오버레이 믹서에 비디오 포토 핀을 접속하는 것이다. 여기에서는, 캡춰 필터의 비디오 포토 핀과 오버레이 믹서의 입력 핀 0 을 검색하기 위해서,ICaptureGraphBuilder2::FindPin 메소드를 사용하지만, 대신에 IBaseFilter::EnumPins 메소드를 사용할 수도 있다. 간략화를 위해, 이 코드에서는 에러 체크가 생략 되고 있다.

IPin *pPinOut,  // 캡춰 필터의 비디오 포토 핀.
     *pPinIn;   // 오버레이 믹서의 입력 핀.
IBaseFilter *pOvMix = NULL;

// 비디오 포토 핀을 검색한다.
pCGB->FindPin(
    pCaptureFilter,           // 캡춰 필터에의 포인터.
    PINDIR_OUTPUT,            // 출력 핀을 검색한다.
    &PIN_CATEGORY_VIDEOPORT,  // 비디오 포토 핀을 검색한다.
    NULL,                     // 임의의 미디어 타입.
    TRUE,                     // 핀은 비접속이 아니면 안된다.
    0,                        // 일치하는 최초의 핀을 취득한다.
    &pPinOut                  // 핀에의 포인터의 주소.
);

// 오버레이 믹서를 생성 한다.
CoCreateInstance(CLSID_OverlayMixer, NULL, CLSCTX_INPROC,
        IID_IBaseFilter, (void **) &pOvMix);

// 그것을 필터 그래프에 추가한다.
pGraph->AddFilter(pOvMix, L"Overlay Mixer");

// 오버레이 믹서의 입력 핀 0 을 취득한다.
pCGB->FindPin(pOvMix, PINDIR_INPUT, NULL, NULL, TRUE, 0, &pPinIn);

// 2 개의 핀을 접속한다.
pGraph->Connect(pPinOut, pPinIn);

오버레이 믹서를 비디오 렌더러에 접속하려면 , 이러한 코드를 사용하는지, 또는 오버레이 믹서의 출력 핀을 지정해 IGraphBuilder::Render 를 호출한다.

자막 방송

자막 방송 핀에는, 몇개의 종류가 있다.

  • 자막 방송 핀 (PIN_CATEGORY_CC)
  • VBI 핀 (PIN_CATEGORY_VBI)
  • VBI 비디오 포토 핀 (PIN_CATEGORY_VIDEOPORT_VBI)

접속의 요건은, 핀의 종류에 따라서 다르다.

자막 방송 핀 : 프리뷰에서는, 이 핀을Line 21 디코더 필터에 접속해, 그 필터를 오버레이 믹서의 핀 1 에 접속한다 (핀 0 은 프라이머리 비디오 스트림용으로 예약되고 있다). IGraphBuilder::Connect 를 호출하면, 필터 그래프 매니저에 의해 자동적으로 Line 21 디코더가 추가된다. 파일 캡춰에서는, 오버레이 믹서는 아니고, Mux 필터에 접속한다.

VBI 핀 : 이 핀은, Tee/Sink-to-Sink 컨버터 필터 (VBI 인피닛트티라고도 부른다)에 접속한다. 이 필터에 의해 VBI 데이터가 복수의 스트림에 분할된다. 이 필터를 CC 디코더 필터에 접속한다. 프리뷰에서는, 전에 설명한 것처럼 CC 디코더 필터를 오버레이 믹서에 접속한다. 파일 캡춰에서는, Mux 필터에 접속한다.

VBI 비디오 포토 핀 : 이 핀은 VBI 표면 allocater 필터 (CLSID_VBISurfaces)에 접속한다. 이 필터는, VBI 데이터용의 Microsoft® DirectDraw® 표면을 처리한다. 필터에 VBI 핀과 VBI 비디오 포토 핀의 양쪽 모두가 있는 경우는, 그 양쪽 모두를 접속한다.

프리뷰에서는, 캡춰 필터의 프리뷰 핀을, 오버레이 믹서의 핀 0 에 접속한다. 이것은, PIN_CATEGORY_VIDEOPORT 핀 뿐만이 아니라, PIN_CATEGORY_PREVIEW 핀에도 적용된다. 오버레이 믹서에 의해, 자막 방송이 프라이머리 비디오에 오버레이 된다.

다음의 그림은, VBI 핀과 VBI 비디오 포토 핀이 있는 프리뷰 그래프를 나타낸다.

클로즈드 캡션이 있는 필터 그래프

Tee/Sink-to-Sink 컨버터 필터와 CC 디코더 필터는, 실제는 KSProxy 필터에 랩 된 WDM 미니 드라이버이다. 따라서,CoCreateInstance 의 호출에서는 이러한 필터를 생성 할 수 없다. 대신에,시스템 디바이스 열거자를 사용해 각 필터의 디바이스 카테고리를 열거한다.

필터 | 카테고리
Tee/Sink-to-Sink 컨버터 | AM_KSCATEGORY_SPLITTER (WDM 스트리밍티/스플리터)
CC 디코더 | AM_KSCATEGORY_VBICODEC (WDM 스트리밍 VBI CODEC)

카테고리에 포함되는 각각의 필터의 프렌들리명을 테스트해, 일치하는 캐릭터 라인을 찾아낸다. 다음에,IMoniker::BindToObject 를 호출해 필터의 인스턴스를 생성 한다.

다음의 샘플 코드는, Tee/Sink-to-Sink 컨버터 필터를 생성 한다. 간략화를 위해, 에러 체크는 생략 되고 있다.

IBaseFilter *pFilter = NULL; // 필터의 인스턴스를 받는 포인터.

// 시스템 디바이스 열거자를 생성 한다.
ICreateDevEnum *pDevEnum;
CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC,
    IID_ICreateDevEnum, (void**) &pDevEnum);

// 티/스플리터 카테고리를 열거하는 클래스 열거자를 생성 한다.
IEnumMoniker *pEnum;
pDevEnum->CreateClassEnumerator(AM_KSCATEGORY_SPLITTER, &pEnum, 0);

// 이 카테고리에 포함되는 디바이스를 열거한다.
IMoniker *pMoniker;
ULONG cFetched;
while(pEnum->Next(1, &pMoniker, &cFetched) == S_OK)
{
    IPropertyBag *pBag;
    pMoniker->BindToStorage(0, 0, IID_IPropertyBag, (void **) &pBag);

    // 프렌들리명을 확인한다.
    VARIANT var;
    var.vt = VT_BSTR;
    pBag->Read(L"FriendlyName", &var, NULL);
    if (lstrcmpiW(var.bstrVal, L"Tee/Sink-to-Sink Converter") == 0)
    {
        // 올바른 필터가 발견되었다.
        pMoniker->BindToObject(0, 0, IID_IBaseFilter, (void**) &pFilter);
        SysFreeString(var.bstrVal);
        pBag->Release();
        pMoniker->Release();
        break;
    }
    SysFreeString(var.bstrVal);
    pBag->Release();
    pMoniker->Release();
}
pEnum->Release();
pDevEnum->Release();

VideoInfo2 포맷 타입

프리뷰 핀에는,VIDEOINFOHEADER2 포맷의 미디어 타입이 적합한 경우가 있다. 이 포맷은, 정방형 이외의 픽셀이나 인터레이스 비디오 (프레임 베이스는 아니고 필드 베이스의 비디오)등이 특수한 기능을 지원 한다. 오버레이 믹서 필터에서는, 이 포맷이 지원 된다.

이러한 기능을 이용하려면 , 이하를 실행한다.

  1. IPin::EnumMediaTypes 메소드를 사용해 핀의 우선 미디어 타입을 열거한다.
  2. 최초로 열거되는 미디어 타입을 확인한다.
  3. formattype 의 GUID 가 FORMAT_VideoInfo2 라면, 핀을 오버레이 믹서에 접속한다. 다음에, 오버레이 믹서를 비디오 렌더러에 접속한다 ( 「비디오 포토 핀」참조).

이러한 기능에 흥미가 없으면, 오버레이 믹서를 사용할 필요는 없다.

WDM 스트림 클래스 드라이버 필터

캡춰 디바이스로 WDM (Windows Driver Model) 드라이버를 사용하는 경우에는, 그래프내의 캡춰 필터의 업 스트림에 일정한 필터가 필요하게 되는 일이 있다. 이러한 필터는, "스트림 클래스 드라이버 " 필터 또는 WDM 필터로 불린다. 이러한 필터에서는, 하드웨어가 제공하는 추가 기능이 지원 된다. 예를 들어, TV 튜너 카드에는 채널을 설정하기 위한 기능이 있다. 이것에 대응하는 필터는,IAMTVTuner 인터페이스를 공개하는 TV 튜너 필터이다. 어플리케이션으로부터 이 기능을 이용할 수 있도록(듯이) 하려면 , 캡춰 필터에 TV 튜너 필터를 접속할 필요가 있다.

ICaptureGraphBuilder2 인터페이스는, 그래프에 WDM 필터를 추가하기 위한 가장 간단한 수단이다. 그래프 구축의 어디선가 FindInterface 또는 RenderStream 를 호출한다. 이러한 메소드는, 어느쪽이나 필요한 WDM 필터를 자동적으로 찾아내 캡춰 그래프에 접속한다. WDM 필터를 수동으로 추가하는 방법은, 이 섹션의 후반에 설명한다. 다만, 가능하면, 수동은 아니고 ICaptureGraphBuilder2 의 메소드를 호출하는 것.

WDM 필터의 핀은, 1 개(살) 이상의 "미디어 " 를 지원 한다. 미디어란, 통신의 수단 (버스등)을 정의하는 것이다. 접속하는 핀에서는, 같은 미디어가 지원 되고 있을 필요가 있다. DirectShow 에서는,REGPINMEDIUM 구조체로 미디어가 정의된다. REGPINMEDIUM 구조체는, 커넬 스트리밍 드라이버에 사용되는 KSPIN_MEDIUM 구조체와 동등하다. 핀의 미디어를 취득하려면 ,IKsPin::KsQueryMediums 메소드를 호출한다. 이 메소드는, KSMULTIPLE_ITEM 구조체와 0 개 이상의 REGPINMEDIUM 구조체가 연속해 저장 된 메모리 블록에의 포인터를 돌려준다. REGPINMEDIUM 구조체의 clsMedium 멤버는, 미디어의 클래스 식별자 (CLSID)를 지정하는 것이다.

다음의 헬퍼 함수는, 핀의 미디어를 취득한다.

// 호출원으로 pMedium 를 할당한다.
HRESULT GetMedium(IPin *pPin, REGPINMEDIUM *pMedium)
{
    IKsPin *pKsPin = NULL;
    PKSMULTIPLE_ITEM pmi;

    HRESULT hr = pPin->QueryInterface(IID_IKsPin, (void **) &pKsPin);
    if (FAILED(hr))
        return hr;  // 핀이 IKsPin 를 지원 하고 있지 않다.

    hr = pKsPin->KsQueryMediums(&pmi);
    pKsPin->Release();
    if (FAILED(hr))
        return hr;  // 핀이 미디어를 지원 하고 있지 않다.

    if (pmi->Count == 0) {
        CoTaskMemFree(pmi);
        return E_FAIL;  // 미디어수가 0.
    }
    else {
        // 포인터 연산을 사용해 미디어 구조체를 참조한다.
        REGPINMEDIUM *pTemp = (REGPINMEDIUM*)(pmi + 1);
        memcpy(pMedium, pTemp, sizeof(REGPINMEDIUM));
        CoTaskMemFree(pmi);
        return S_OK;
    }
}

미디어의 CLSID 가 GUID_NULL 또는 KSMEDIUMSETID_Standard 의 경우에는, 핀을 접속하지 않는 것. 이러한 CLSID 는, 핀이 미디어를 지원 하고 있지 않는 것을 나타내는 디폴트값이다.

또, 필터에 그 핀이 접속된 인스턴스가 1 개만 필요한 경우에게만, 핀을 접속하는 것. 그렇게 하지 않으면 접속해서는 안되는 각종의 핀을 어플리케이션이 접속하려고 해, 그 결과, 프로그램이 응답하지 않게 되는 위험성이 있다. 필요한 인스턴스의 수를 조사하려면 , 다음의 샘플 코드와 같이 KSPROPERTY_PIN_NECESSARYINSTANCES 프로퍼티 세트를 취득한다. 간략화를 위해, 이 코드에서는 return code의 테스트와 인터페이스의 해방이 생략 되고 있지만, 어플리케이션에서는 이것들을 양쪽 모두 실행해야 한다.

// 핀 팩토리 식별자를 취득한다.
IKsPinFactory *pPinFactory;
hr = pPin->QueryInterface(IID_IKsPinFactory, (void **) &pPinFactory);

ULONG ulFactoryId;
hr = pPinFactory->KsPinFactory(&ulFactoryId);

// 필터로부터 "인스턴스" 프로퍼티를 취득한다.
IKsControl *pKsControl;
hr = pFilter->QueryInterface(IID_IKsControl, (void **) &pKsControl);

KSP_PIN ksPin;
ksPin.Property.Set = KSPROPSETID_Pin;
ksPin.Property.Id = KSPROPERTY_PIN_NECESSARYINSTANCES;
ksPin.Property.Flags = KSPROPERTY_TYPE_GET;
ksPin.PinId = ulFactoryId;
ksPin.Reserved = 0;

KSPROPERTY ksProp;
ULONG ulInstances, bytes;
pKsControl->KsProperty((PKSPROPERTY) &ksPin, sizeof(ksPin),
    &ulInstances, sizeof(ULONG), &bytes);

if (hr == S_OK && bytes == sizeof(ULONG))
{
    if (ulInstances == 1)
    {
        // 필터에는 이 핀의 인스턴스가 1 개 필요.
        // 이 핀은 OK.
    }
}

다음의 의사 코드는, WDM 필터를 검색 및 접속하는 방법에 대해, 매우 간단한 개요만을 나타낸 것이다. 이 코드에서는, 세세한 처리를 모두 생략 해, 어플리케이션으로 실행해야 할 일반적인 스텝만을 나타낸다.

지원 되는 필터를 추가한다 :
{
    foreach 입력 핀 :
        skip if (핀이 접속되고 있다)

        핀 미디어를 취득한다
        skip if (미디어가 GUID_NULL 또는 KSMEDIUMSETID_Standard)

        필터에 KSPROPERTY_PIN_NECESSARYINSTANCES 프로퍼티를 조회한다
        skip if (필요한 인스턴스수 ! = 1)

        기존의 핀과 비교하는 || 일치하는 필터를 검색한다
}

기존의 핀과 비교한다 :
{
    foreach 그래프내의 필터
        접속되어 있지 않은 foreach 핀
            핀 미디어를 취득한다
            if (미디어가 일치한다)
                그 핀을 접속한다
}

일치하는 필터를 검색한다 :
{
    필터 그래프 매니저에 IFilterMapper2  를 조회한다.
    미디어가 일치하는 출력 핀을 가지는 필터를 검색한다.
    필터를 그래프에 추가한다.
    핀을 접속한다.
    지원 되는 필터를 추가한다 (재귀 호출).
}


DirectShow 편집 서비스

Microsoft® DirectShow® 편집 서비스 (DES)는, 비디오 편집을 지원 하는 어플리케이션 프로그래밍 인터페이스 (API)이다. 이 섹션에서는, DES 의 사용법을 설명하고 있다. 이하의 주제가 포함된다.

  • DirectShow 편집 서비스의 소개
  • DirectShow 편집 서비스의 기초지식
  • DirectShow 편집 서비스의 사용법
  • DirectShow 편집 서비스 레퍼런스


DirectShow 편집 서비스의 소개

Microsoft® DirectShow® 편집 서비스 (DES)는, 비디오 편집에 포함되는 태스크를 큰폭으로 간략화하는 어플리케이션 프로그래밍 인터페이스 (API)이다. DES 는, 코어 DirectShow 아키텍쳐의 최상부에 구축되고 있다. DES 는, DirectShow 의 대부분을 추상화 해, 비디오 편집 프로젝트의 조작 전용에 설계된 인터페이스세트를 제공한다. 어플리케이션 개발자는, 비디오 편집 어플리케이션의 생성에 최적인 체제 중(안)에서 DirectShow 의 이점을 활용할 수 있다.

DirectShow 자체는, 스트림 미디어를 처리하기 위한 강력한 아키텍쳐이다. DirectShow 에 의해, 개발자가 파일 압축등이 귀찮은 문제를 고려하지 않아도, 어플리케이션으로 다양한 포맷의 멀티미디어 컨텐츠를 재생할 수가 있다. 그러나, DES 가 없으면, DirectShow 는 비선형 편집에 필요한 유연성을 갖추지 않았었다.

예를 들어, 어느 비디오 순서를 생성 하는데, 소스 A 로부터 4 초, 다음에 소스 B 로부터 10 초, 마지막에 소스 C 로부터 5 초를 연결하고 싶다고 한다. 이것은, DirectShow API 만을 사용해, 꽤 용이하게 실시할 수가 있다.

그러나, 소스 C 를 소스 B 의 다음에는 없게 전에 가져온 있고 경우나, 소스 A 로부터 4 초는 아니고 8 초 사용하고 싶은 경우, 또 프로덕션 전체로 백그라운드에 다른 오디오 트럭 재생이 필요하게 되었을 경우에는, 어떻게일까. 이러한 작은 변경을 이행 하는 것이 어려운 일이 있다. 그러나, 이러한 작업은 DES 에서는 매우 간단한 편집 프로젝트이며, 메소드를 몇개인가 호출하는 것만으로 실시할 수가 있다.

DES 가 DirectShow 에 가져오는 주된 기능을 이하에 나타낸다.

  • 비디오 및 오디오 트럭을 상자 구조의 계층에 구성해, 최종 프로덕션의 조작을 용이하게 하는 타임 라인 모델
  • 그 자리에서 비디오 프로젝트를 프리뷰 하는 기능
  • XML 베이스의 포맷에 의한 프로젝트의 지속성
  • 비디오 이펙트와 오디오 이펙트, 및 비디오 트럭간의 트란지션 (페이드나 와이프 등)
  • Society of Motion Picture and Television Engineers (SMPTE)에 의해 정의되고 있는 약 100 종류의 표준 와이프
  • 색상, 휘도, RGB 값, 또는 알파값에 근거하는 키잉
  • 프로덕션에서 이종 소스의 사용을 가능하게 하는, frame rate와 오디오 샘플링 레이트의 자동변역
  • 비디오의 사이즈 변경과 크로핑

DES 의 실제의 동작을 보는 가장 빠른 방법은, 샘플 어플리케이션의 XTLTest 샘플을 실행하는 것이다. 이 유틸리티는, XML 로 기술된 DES 프로젝트 파일을 해석해, 화면에 렌더링 한다. 샘플 프로젝트 파일을 수동으로 편집해 렌더링 해, 그 변화를 보는 것으로, XtlTest 를 시험할 수가 있다.


DirectShow 편집 서비스의 기초지식

이 섹션에서는, DirectShow® 편집 서비스 (DES)를 사용하기 시작하기 위해서(때문에) 필요한 기본 개념을 설명한다.

  • DirectShow 편집 서비스의 기본 개념
  • 타임 라인 모델
  • DirectShow 편집 서비스에 있어서의 시간


DirectShow 편집 서비스의 기본 개념

여기에는, 이하의 주제가 포함된다.

  • 아키텍쳐
  • DES 및 DirectShow 코어 API
  • 대표적인 어플리케이션의 구조

아키텍쳐

다음의 그림은, Microsoft® DirectShow® 편집 서비스 (DES)의 아키텍쳐를 나타내고 있다.

DirectShow 편집 서비스의 아키텍쳐

  • 타임 라인 : 비디오 프로덕션을, 상자 구조의트럭세트에 구성되는, 소스 클립, 트란지션, 및 이펙트의 콜렉션으로서 표현한다. 상세한 것에 대하여는, 「타임 라인 모델」을 참조할것.
  • XML 파서 : 타임 라인을 해석해 출력 파일을 생성한다. 또는, 입력 파일을 읽어들여 타임 라인을 생성한다. DES 는, XML 베이스의 영속성 포맷을 지원 하고 있다.
  • 렌더링 엔진 : 타임 라인을, 스트림 미디어로서 렌더링 할 수 있는 포맷으로 변환한다. 디폴트에서는, 렌더링 엔진은 DirectShow 필터 그래프를 생성한다 (다음의 섹션을 참조할것).
  • 미디어 locator : 미디어 요소의 위치의 캐쉬를 보수한다. 미디어 요소를 열려고 실패했을 경우, DES 는 이 캐쉬를 사용해, 성공한 오픈의 역사에 근거해 요소를 검색한다.

DES 및 DirectShow 코어 API

DirectShow 는,필터로 불리는 모듈러 컴퍼넌트를 통해 멀티미디어 데이터의 스트림을 제어한다. 필터는, 미디어 스트림을 입력으로 해, 그에 대해 어떠한 처리를 실시해, 결과를 출력으로서 건네주는 컴퍼넌트이다. 필터는, 복수의 스트림을 결합하는 것, 및 1 개의 스트림을 복수의 출력 스트림에 분할할 수도 있다. 필터 그래프는, 최 이닝 된 필터의 콜렉션이다. 소스 필터는, 원시 파일로부터 미디어 데이타를 뽑아 붐비어, 그것을 필터 그래프에 도입한다. 렌더링 필터는, 스트림을, 비디오나 오디오등의 최종 출력의 타입으로서 렌더링 한다. 미디어 스트림은, 소스 필터로부터, 보통은 다른 필터를 경유해 렌더링 필터에 흐른다.

DES 에 있어서의 타임 라인은, 비디오 편집 프로젝트의 추상 표현이다. 이것은, 프로젝트로 사용되는 소스 클립, 그 시작 타임과 종료 타임, 이펙트와 트란지션의 배치등을 지정한다. 다만, 타임 라인 자체는, 표현되는 비디오 및 오디오를 렌더링 할 수 없다. 그것은, 렌더링 엔진의 기능이다. 렌더링 엔진은, 타임 라인을 필터 그래프로 변환한다. 필터 그래프를 실행 하면, 프로젝트가 프리뷰로서 화면에 직접 렌더링 되는지, 파일에의 출력으로서 렌더링 된다. 어플리케이션에서는, 취급하기 어렵게 에러의 나오기 쉬운 필터 그래프를 직접 조작하는 것이 아니라, 타임 라인을 조작한다.

대표적인 어플리케이션의 구조

아래의 겉(표)는, 일반적인 비디오 편집 어플리케이션으로 행해지는 주요한 태스크와 각 태스크를 지원 하는 DES 인터페이스의 일람이다. 이후의 섹션으로, 이러한 태스크와 인터페이스에 대해 자세하게 설명한다.

태스크 | 인터페이스
타임 라인의 구축 또는 변경 | IAMTimeline 및 다른 IAMTimelineXXXX 인터페이스
프로젝트 파일의 보존과 로드 | IXml2Dex
프로젝트의 프리뷰 또는 파일에의 기입해 | IRenderEngine ,ISmartRenderEngine

이 주요 태스크 외에, 어플리케이션에서는 이하의 2 차적인 태스크의 몇개인가 또는 전부를 실시하는 경우가 있다.

태스크 | 인터페이스
미디어 파일에 관한 정보의 취득 (스트림의 수, 각 스트림의 포맷과 시간폭) | IMediaDet
트란지션과 이펙트의 프로퍼티의 설정 | IPropertySetter
렌더링중에 에러가 발생했을 경우의 통지의 수신 | IAMSetErrorLog ,IAMErrorLog
포스터 프레임의 추출 | IMediaDet,ISampleGrabber


타임 라인 모델

타임 라인은, Microsof® DirectShow® 편집 서비스 (DES)가 비디오 편집 프로젝트를 표현하기 위해서 사용하는 오브젝트이다. 여기에서는, 타임 라인의 개념에 대해 설명해, 타임 라인이 가지고 있는 각종 오브젝트에 대해 해설하고 있다.

여기에는 이하의 섹션이 포함된다.

  • 타임 라인의 구조
  • 타임 라인이 렌더링 되는 방법
  • 트란지션
  • 합성과 겹쳐
  • 이펙트

타임 라인의 구조

비디오 제작은, 비디오 클립, 사운드 파일, 스티르이메이지등의 미가공의 원시 파일의 콜렉션으로부터 시작 된다. 제작자나 비디오 편집자는, 1 개의 클립으로부터 10 초, 다른 클립으로부터 5 초, 한층 더 다른 클립으로부터 30 초 와 같이 , 파일의 일부분을 꺼낸다. 다음에, 특정의 순서로 그것들을 배치한다.

가장 단순한 경우, 클립은 엄밀하게 선형의 순서로 표시되어 각 클립의 뒤에 다음의 클립이 계속된다. 이 기초적인 배치는,트럭이 된다. 따라서, 단순한 제작에서는, 1 개의 비디오 트럭과 오디오 트럭만이 포함된다. 보다 복잡한 제작에서는, 몇개의 오디오 트럭이 믹싱 되는 등, 복수의 트럭이 사용된다. 또, 트럭에는 오디오 효과가 포함되어 1 개의 트럭이 용암 할 경우에, 다른 트럭이 용명 한다. 비디오의 경우는, 1 개의 트럭은 페이드나 와이프를 사용해 다음의 트럭에 트란지션 한다. 이것이,합성의 예이다. 다른 예에는, 1 개의 트럭의 배경이 키 아웃 되어 다른 트럭에 의해 옮겨지는 chroma-key 처리가 있다. chroma-key 처리의 예에는, 위성 사진의 전면에 배치된 일기 예보의 캐스터가 있다.

이와 같이, 비디오 제작에는시간 (있는 클립에 다른 클립이 계속된다)과 계층 (있는 클립이 다른 클립과 겹쳐진다)으로 배치된 소스 클립이 포함된다. DES 에서는, 트리 구조를 사용해 이 배치를 나타낸다.

  • 리프 노드는, 미디어 파일로부터의 개개의 스트림 (오디오 또는 비디오)이다. 각 노드는소스이다.
  • 동일한 미디어 타입 (오디오 또는 비디오)의 소스의 콜렉션이트럭이다.
  • 트럭의 콜렉션이합성이다. 합성은, 포함되는 모든 트럭의 합성으로서 렌더링 된다. 전의 예를 사용하면, 일기 예보의 캐스터와 위성 사진은, 같은 합성내의 다른 트럭에 존재하고 있다. 합성에는 다른 합성을 넣을 수도 있어 트럭의 복잡한 배치가 가능하다.
  • (같은 미디어 타입을 나타낸다) 합성과 트럭의 최상정도 레벨의 콜렉션이그룹이다.
  • 1 개(살) 이상의 그룹세트가타임 라인이 된다. 타임 라인은, 트리의 루트 노드이다.

타임 라인에는, 적어도 1 개의 그룹이 포함되지 않으면 안 된다. 각 그룹은, 최종 프로덕션에 있어서의 단위의 스트림을 나타낸다. 대표적인 프로덕션에는, 비디오 그룹과 오디오 그룹이 1 개씩 포함된다. 합성은 옵션이며, 필요한 경우에 한층 더 구조를 제공하는 것이다.

다음의 그림은, 타임 라인의 구조를 나타내고 있다. 이 그림은, 트리내의 부모와 자식 관계를 나타내고 있지만, 시간 순서를 나타내고 있는 것은 아니다.

타임 라인이 렌더링 되는 방법

전의 섹션의 트리도에서는, 서로 겹치는 트럭과 합성이 어떻게 렌더링 될까는 나타나지 않았다. 그 목적에서는, 타임 라인을, 노드 구조는 아니고 시간 순서로서 파악하는 것이 좋다. 다음의 그림은, 2 개의 비디오 트럭과 2 개의 오디오 트럭이 포함되는 단순한 프로젝트를 나타내고 있다. 선두의 화살표는, 제로로부터 시작되는 타임 라인의 방향을 나타내고 있다.

타임 라인의 그림

우선 최초로, 비디오 그룹에 대해 생각한다. 트럭 1 은, 트럭 0 보다우선 순위가 높다. 트럭 1 에 비디오 소스가 들어가 있는 경우, 그 소스는 트럭 0 의 내용을 은폐 한다. 트럭 1 이 하늘의 경우는, 트럭 0 이 "틈이 날 수 있어 " 보인다. 이 비디오가 렌더링 되면(자), 소스 A 로부터 시작된다. 그리고 소스 C 에 바뀌지만, 소스 A 의 마지막 부분과 소스 B 의 최초의 부분은 안보인다. 마지막에 소스 C 가 끝날 때, 소스 B 에 바뀐다 (B 는 벌써 진행중이다).

오디오 그룹은 이것과는 다른 동작을 한다. 모든 트럭이 단순하게 믹싱 된다. 오디오는 소스 D 로부터 시작되어, 소스 D 와 소스 E 의 믹스에 바뀌어, 소스 D 만으로 되어 종료한다.

트란지션

트란지션은, 페이드나 와이프등의 비주얼 이펙트를 사용해, 비디오 트럭을 다른 비디오 트럭에 사이 없게 연결하는 방법이다. 전의 예에서는, 비디오는 즉석에서 바뀐다. 이번은, 같은 비디오 그룹에 트란지션을 추가하고 생각해 본다.

트란지션을 사용한 타임 라인

트란지션은, 트럭 1 에 존재한다. 이것은, 그 트럭 (트럭 1)과 게다가의 계층 (트럭 0)과의 사이의 트란지션을 나타낸다. 트란지션의 시작시에는, 렌더링 된 출력은 모두 트럭 0 (소스 A)으로부터의 것이다. 종료시에는, 출력은 모두 트럭 1 (소스 C)으로부터의 것이 된다. 그 사이에서는, 출력은 소스 A 로부터 소스 C 에 변환한다. 예를 들어 페드트란지션에서는, 1 개의 소스가 차츰 다른 소스로 페이드 한다.

렌더링 된 출력은, 그림의 맨 밑에 도식화되고 있다. 트란지션리젼 중(안)에서는, 비디오 이미지는 소스 A 로부터 소스 C 에 변환한다. 소스 C 로부터 소스 B 에가 직접 변환이 되는 것은, 트럭의 그 위치에 트란지션이 포함되지 않기 때문이다.

트란지션에는, 특정의 방향이 있는 것에 주의 해야 한다. 트란지션의 시작시에는, 비디오 출력은 대부분이 소스 A 로부터의 것이다. 트란지션의 중간에서는, 비디오는 2 개의 소스가 섞인 것이 된다. 종료시에는, 출력은 대부분이 소스 B 로부터의 것이 된다. 디폴트에서는, 트란지션은 그림에 나타낸 것처럼, 우선 순위의 낮은 트럭으로부터 우선 순위의 비싼 트럭으로 진행한다. 그러나, 역의 동작을 지정할 수도 있다. 다음의 그림은, 그 상황을 나타내는 예이다. 트럭 0 으로부터 트럭 1 에 페이드 해, 트럭 1 으로부터 트럭 0 에 페이드 해 돌아온다. 어느 쪽의 트란지션도 트럭 1 에 존재한다.

2 개의 트란지션이 있는 트럭

합성과 겹쳐

각 비디오 트럭은, 각각 고유의 계층을 차지하는 것이라고 생각할 수가 있다. 트럭의 콜렉션에서는, 최초의 트럭의 우선 순위가 가장 낮고 (우선 순위 0), 이후의 트럭은 우선 순위가 1 레벨씩 높아진다. 각 계층에서는, 계층내의 소스 클립은, 그 계층에 트란지션이 포함되지 않으면, 아래의 계층내의 소스 클립을 은폐 한다. 따라서, DES 는 렌더링을 실시할 때 몇개의 패스를 생성 하면 생각할 수가 있다.

우선, 트럭 0 을 렌더링 한다. 트럭 0 의 "하 " 에는 아무것도 없기 때문에, 하늘의 리젼은 흑일색의 이미지로서 렌더링 된다. 이 계층내의 트란지션은, 흑이미지와 트럭 0 의 사이에 행해진다 (예를 들어, 비디오 클립이 흑으로부터 페이드 한다). DES 는, 트럭 0 위에 트럭 1 을 배치해, 2 개의 트럭의 사이에 트란지션을 생성한다. 그 결과는, 2 개의 트럭의 합성이 된다. 다음에, 이 합성 후에 트럭 2 를 배치한다. 이 계층 위에의 트란지션은, 이 합성과 트럭 2 의 사이에 행해진다. 이 프로세스가, 마지막 트럭 (최고의 우선 순위)이 배치될 때까지 계속된다.

복수의 트럭이 합성되면(자), 그것은 단일의 트럭과 같이 동작한다 (이것은가상 트럭으로 불린다). DES 에서는, 합성 오브젝트가 이 동작을 캡슐화하고 있다. 복수의 트럭을 합성에 삽입할 수 있어 그 합성을 다른 합성에 삽입할 수 있다 (삽입되는 측의 합성에, 다른 트럭 또는 다른 합성이 포함되어 있어도 상관없다). 이 때, 최초의 합성은 큰 합성 중(안)에서 단일의 계층으로서 기능한다.

이 모델에서는, 복잡한 구성이 가능하다. 예를 들어, 어느 비디오 클립이 2 번째의 클립에 와이프 해, 동시에 그 합성 (그 2 개의 클립 및 와이프)이 3 번째의 클립에 페이드 하면 말했던 것이 가능해진다.

이펙트

트란지션과 달리, 이펙트는 단일의 계층에 적용된다. 비디오 이펙트에는, 비디오 이미지의 브라, 칼라 비디오의 흑백에의 변환, 일정한 축으로 따른 이미지의 회전등이 있다. 오디오 이펙트에는, 리바브나 메아리등이 있다. 이펙트는, 개별의 소스, 트럭, 또는 합성 전체에 적용할 수 있다.


DirectShow 편집 서비스에 있어서의 시간

비디오를 편집하기 위해서는, 시간에 관한 중요한 개념을 몇개인가 취급하지 않으면 안 된다. 예를 나타낸다.

  • 각 클립에는, 시간폭이 있다.
  • 클립, 트란지션, 및 이펙트는, 프로젝트내에서 특정의 시점에 시작 된다.
  • 비디오에는, 매초의 프레임수 (fps)로 나타내지는 frame rate가 있다.

Microsoft® DirectShow® 편집 서비스 (DES)에는, 시간이나 frame rate를 취급하는 다수의 메소드가 있어, 그러한 값의 의미는 상황에 따라서 다르다. 여기에서는, DES 로 사용되는 다양한 시간의 계측 단위를 설명한다. 이하의 섹션이 포함된다.

  • 시간의 값
  • frame rate

시간의 값

파라미터가 시간을 나타내는 경우, 3 으로 우리의 의미가 있다.

  • 타임 라인 타임 : 타임 라인의 시점에 대한 시간. 예를 들어, 어느 클립은 타임 라인에 대해 2 초의 시점에서 시작되는, 어느 트란지션은 타임 라인에 대해 15 초의 시점에서 발생하는, 등. 타임 라인에 의해 최종적으로 렌더링 되는 오브젝트가 정해지므로, 타임 라인 시간을 "프로젝트 시간 " 라고 생각할 수도 있다.
  • 미디어 타임 : 원시 파일내에서, 보통의 재생에 대해 달하는, 파일의 선두에 대한 위치. 예를 들어, 10 초간의 비디오 파일이 있는 경우, 파일의 중간 지점은, 미디어 시간에 나타내면(자) 5 초의 위치에 있다.
  • 친타임 : 타임 라인내의 오브젝트에 대한 시간. 예를 들어, 어느 오브젝트가 타임 라인상에서 8 초의 위치에서 시작되어, 그 오브젝트에 포함되는 다른 오브젝트가 타임 라인상에서 10 초의 위치에서 시작되는 경우, 아이 오브젝트는 부모에 대해서 2 초의 위치에서 시작되게 된다. 가상 트럭은 모두, 타임 라인에 대해서 시간 제로로부터 시작된다. 따라서, 가상 트럭내의 오브젝트에 대해서는, 친타임과 타임 라인 타임은 동일해진다.

미디어 타임은, 소스 오브젝트에게만 적용된다. 각 소스 오브젝트에는, 미디어 시작 타임과 미디어 종료 타임이 있다. 예를 들어, 10 초간의 비디오 클립이 있어, 클립의 도중의 5 초간만을 사용하고 싶은 경우, 클립으로부터 최초의 2 초와 마지막 3 초를 트리밍 한다. 이 클립을 프로젝트내에서 (보통의 재생 속도로) 20 초의 위치로부터 시작 하고 싶은 경우, 시작 타임과 종료 타임을 다음과 같이 지정하게 된다.

  • 미디어 시작 타임 : 2 초
  • 미디어 종료 타임 : 7 초
  • 타임 라인 시작 타임 : 20 초
  • 타임 라인 종료 타임 : 25 초

타임 라인에 소스 클립을 삽입한다

frame rate

frame rate는, 미디어 스트림의 "속도 " 이며, 매초의 프레임수로 계측 된다. 시간값의 경우와 같게, frame rate의 의미는 상황에 따라서 다르다.

  • 출력 frame rate : 최종적으로 렌더링 된 프로젝트의 frame rate. 그룹에 의해 정의된다. 프로젝트를 렌더링 하면, 각 그룹은 각각 고유의 frame rate를 가지는 개별의 미디어 스트림이 된다.
  • 소스 frame rate : 원시 파일이 생성 되었을 때의 frame rate. 생성시의 frame rate은, 그룹의 출력 frame rate와 일치하고 있지 않아도 좋다. DES 는, 필요에 따라서 자동적으로 파일의업 샘플 또는다운 샘플을 실시한다. 대부분의 미디어 포맷에 대해, DES 는 포맷을 조사해 frame rate를 특정할 수가 있다. DIB 순서만은 예외로, 그 frame rate는 유저가 지정해야 한다 (상세한 것에 대하여는, 「소스의 조작」을 참조할것).
  • 재생 frame rate : 소스 클립이 프로젝트내에서 시작될 때의 재생 속도. 예를 들어, 10 초간의 비디오를 타임 라인 위에의 5 초간에 거둘 수가 있다. 그 경우, 다음의 그림으로 가리키도록(듯이), 이 클립의 속도는 2 배가 된다.

    소스의 재생 속도를 올린다

    (오디오 소스의 경우는, 피치도 쉬프트 한다). 소스 클립의 재생 레이트는, 다음의 식에 의해 구할 수 있다.
    재생 레이트 = (미디어 종료 타임 - 미디어 시작 타임) / (타임 라인 종료 타임 - 타임 라인 시작 타임)

이상의 3 종류의 레이트는, 각각 외와는 독립하고 있는 점에 주의 해야 한다.

  • 미디어 타임을 조정하는 것으로써, 클립의 속도의 오르내림이 생긴다. 이것은, 최종 출력의 frame rate에는 영향을 주지 않는다.
  • 파일의 재생 속도에 영향을 주지 않고 , 출력 frame rate를 오르내림 할 수가 있다.
  • 같은 그룹내에서는, 생성시의 frame rate가 다른 원시 파일을 혼재시킬 수가 있어 DES 는 각 클립의 업 샘플 또는 다운 샘플을 실시해, 그룹의 frame rate에 일치시킨다.

프로젝트를 렌더링 할 경우에, 모든 시간은, 그룹의 frame rate에 의해 정해지는 가장 가까운 프레임 경계에 말 수 있다. 예를 들어, 비디오 그룹의 frame rate가 30 fps 이다고 한다. 각 프레임은 거의 33 밀리 세컨드 (ms)이다고 한다. 여기서, 타임 라인에 대해서 1.68 초의 소스 클립을 추가해, 이 클립은 시간 제로로부터 시작된다고 한다. 이 소스는, 프레임 경계 정확히에서는 종료하지 않기 때문에, DES 는 종료 타임을 1.6666 초 (50 프레임)에 말다. 렌더링 후의 프로젝트로 1.68 초의 위치를 조사했을 경우, 실제로는 소스가 종료한후 (51 번째의 프레임)를 조사하게 된다.

다만, DES 는 소스의 종료 타임을 고쳐 쓰지는 않는다. 다음에 그룹의 frame rate를 변경하는지, 소스를 타임 라인내의 다른 위치로 이동했을 경우에는, 시간을 만 결과는 다른 것이 된다. 그 때문에, DES 는 원래의 종료 타임을 유지해, 필요한 때에게만 둥근을 실시한다. 상세한 것에 대하여는, 「IAMTimelineObj::FixTimes 」를 참조할것.


DirectShow 편집 서비스의 사용법

이 섹션에서는, Microsoft® DirectShow® 편집 서비스 (DES)를 사용해 비디오 편집 어플리케이션을 개발하는 방법을 상세하게 설명한다. 이하의 섹션이 포함된다.

  • 타임 라인 컴퍼넌트의 개요
  • 프로젝트의 로드와 프리뷰
  • 타임 라인의 구축
  • 소스의 조작
  • 이펙트와 트란지션의 조작
  • 프로젝트의 렌더링
  • 에러의 로그
  • 비디오 편집 프로젝트의 관리
  • 알파 블렌딩
  • 컷 리스트의 타임 라인에의 변환


타임 라인 컴퍼넌트의 개요

Microsoft® DirectShow® 편집 서비스 (DES)의 타임 라인은, COM 컴퍼넌트이다. 타임 라인내의 오브젝트도, COM 컴퍼넌트이다. 여기에서는, 다양한 오브젝트가 공개하는 인터페이스의 개요에 대해 설명한다.

여기에는, 다음의 주제가 포함되어 있다.

  • 타임 라인
  • 타임 라인 오브젝트
  • 서브 오브젝트

타임 라인의 상세한 것에 대하여는, 「타임 라인 모델」을 참조할것. DES 의 컴퍼넌트 일람에 대해서는, 「DirectShow 편집 서비스의 컴퍼넌트」를 참조할것.

타임 라인

타임 라인은,IAMTimeline 인터페이스를 공개한다. 이 인터페이스에는, 타임 라인 위에의 프로퍼티의 설정, 타임 라인에의 그룹의 추가, 및 그룹, 트럭, 소스등의 타임 라인 오브젝트의 생성을 행하기 위한 메소드가 포함되어 있다. 새로운 타임 라인을 생성 하려면 , 다음과 같이 표준의 CoCreateInstance 함수를 호출한다.

IAMTimeline *pTL = NULL;
hr = CoCreateInstance(CLSID_AMTimeline, NULL, CLSCTX_INPROC_SERVER,
        IID_IAMTimeline, (void**) &pTL);

새로운 타임 라인은 하늘이다. 이 시점에서, 기존의 프로젝트 파일 읽어들이는지 (상세한 것에 대하여는 「프로젝트의 로드와 프리뷰」를 참조), 또는 새로운 오브젝트를 생성, 삽입해 타임 라인을 구축할 수 있다 (상세한 것에 대하여는, 「타임 라인의 구축」을 참조할것).

타임 라인 오브젝트

타임 라인의 각 타입의 오브젝트 (소스, 트럭, 이펙트등)는, 명확한 COM 오브젝트이다. 그러나, 어플리케이션은 CoCreateInstance 함수를 사용해 이러한 오브젝트를 생성 하지 않고,IAMTimeline::CreateEmptyNode 메소드를 호출한다. 이 메소드는, 요구된 타입의 오브젝트를 생성 해, 초기화한다. 다음에, 오브젝트에의 포인터를 돌려준다. 상세한 것에 대하여는, 「타임 라인의 구축」을 참조할것.

각 타임 라인 오브젝트는,IAMTimelineObj 인터페이스를 공개한다. 게다가 다양한 오브젝트 타입이, 다음과 같은 특별한 인터페이스를 지원 하고 있다.

  • 소스 : IAMTimelineSrc
  • 트럭 : IAMTimelineTrack
  • 합성 : IAMTimelineComp
  • 그룹 : IAMTimelineComp ,IAMTimelineGroup
  • 이펙트 : IAMTimelineEffect
  • 트란지션 : IAMTimelineTrans

그룹은 합성의 일종이므로,IAMTimelineComp 를 지원함과 함께, 독자적인 IAMTimelineGroup 인터페이스를 지원 하고 있다.

전에 나타낸 인터페이스에 가세해, 타임 라인 오브젝트는 다른 이차적인 인터페이스를 공개한다. 이러한 인터페이스에 의해, 오브젝트 타입간의 관계가 결정된다.

인터페이스 | 의미 | 공개원
IAMTimelineVirtualTrack | 이 오브젝트는 가상 트럭이다. 가상 트럭이란, 트럭과 같이 기능할 수 있는 임의의 오브젝트이다. 가상 트럭은, 합성내에 상주해, 다른 타임 라인 오브젝트를 보관 유지할 수 있다. | 합성, 트럭
IAMTimelineEffectable | 이 오브젝트는 이펙트를 가질 수가 있다. | 합성, 트럭, 소스
IAMTimelineTransable | 이 오브젝트는 트란지션을 가질 수가 있다. | 합성, 트럭
IAMTimelineSplittable | 이 오브젝트는,IAMTimelineSplittable::SplitAt 메소드를 사용해 분할할 수 있다. | 트럭, 소스, 이펙트, 트란지션

서브 오브젝트

소스, 이펙트, 및 트란지션은, 다른 COM 오브젝트에의 내부 포인터를 가지고 있다. 이 포인터는,서브 오브젝트로 불린다. 서브 오브젝트는, 오브젝트의 실제의 조작을 실행한다. 소스의 서브 오브젝트는, 비디오 데이터 또는 오디오 데이터를 생성 하는 컴퍼넌트이다. 이펙트 또는 트란지션의 서브 오브젝트는, 데이터를 변환하는 컴퍼넌트이다. 예를 들어, 비디오 이펙트에서는, 비디오 스트림으로 시각적인 이펙트가 생성 된다.

서브 오브젝트의 타입은, 다음과 같이 오브젝트의 타입에 따라서 다르다.

  • 소스 : 시크를 지원 해, DES 가 지원 하는 포맷을 생성 하는, 임의의 DirectShow 소스 필터 또는 퍼서 필터. 디코드용의 DirectShow 필터가 존재하는 경우, 압축 포맷으로 할 수가 있다.
  • 이펙트 : 비디오에서는, 임의의 1 입력의 Microsoft® DirectX® 2D 변환 오브젝트. 오디오에서는, 임의의 DirectShow 오디오 이펙트 필터.
  • 트란지션 : 비디오에서는, 임의의 2 입력의 DirectX 2D 변환 오브젝트. 오디오는 트란지션을 지원 하고 있지 않다.

그룹, 합성, 및 트럭은, 서브 오브젝트를 가지지 않는다.

어플리케이션은, 서브 오브젝트 포인터를 직접 설정하지 않는다. 이펙트와 트란지션의 경우, 어플리케이션은 IAMTimelineObj::SetSubObjectGUID 메소드를 호출해, 서브 오브젝트의 GUID 를 지정한다. 소스 오브젝트의 경우, 어플리케이션은 보통 IAMTimelineSrc::SetMediaName 를 호출해, 원시 파일의 이름을 지정한다. 그러나,SetSubObjectGUID 메소드는 소스 오브젝트에도 사용해, 필터의 클래스 식별자 (CLSID)를 지정할 수 있다.

상세한 것에 대하여는, 「소스의 조작」 및 「이펙트와 트란지션의 조작」을 참조할것.


프로젝트의 로드와 프리뷰

여기에서는, Microsoft® DirectShow® 편집 서비스 (DES)로 프로젝트를 로드해 프리뷰 하는 방법을 설명하고 있다. 여기에서는, 하늘의 타임 라인에 XML 프로젝트 파일을 로드해, 타임 라인을 프리뷰용으로 렌더링 하는 샘플 어플리케이션을 소개하고 있다. 이 샘플 어플리케이션을 변경해, 이 SDK 에 부속되는 샘플 XML 프로젝트를 취급할 수가 있다.

여기에는, 이하의 주제가 포함된다.

  • 프로젝트 파일의 로드
  • 프로젝트의 프리뷰
  • 클린 업
  • 샘플 코드

프로젝트 파일의 로드

프로젝트 파일을 로드하려면 2 개의 컴퍼넌트가 필요하다. XML 퍼서와 하늘의 타임 라인의 2 개이다. XML 퍼서는, XML 프로젝트 파일을 읽어들여, 파일에 정의되고 있는 각 오브젝트를 생성 한다. 그리고, 생성 한 오브젝트를 타임 라인에 삽입해, 디폴트의 frame rate등의 타임 라인의 속성을 설정한다. 다음의 샘플 코드는, 파일을 로드한다.

HRESULT         hr;
IAMTimeline     *pTL = NULL;
IXml2Dex        *pXML = NULL;

hr = CoCreateInstance(CLSID_AMTimeline,
            NULL, CLSCTX_INPROC_SERVER,
            IID_IAMTimeline, (void**) &pTL);

hr = CoCreateInstance(CLSID_Xml2Dex,
            NULL, CLSCTX_INPROC_SERVER,
            IID_IXml2Dex, (void**) &pXML);

hr = pXML->ReadXMLFile(pTL, L"C:\\example.xtl");
pXML->Release();

퍼서는, 프로젝트 파일의 로드와 보존을 위한 메소드를 가지는 IXml2Dex 인터페이스를 공개한다. 타임 라인은, 타임 라인의 조작과 새로운 타임 라인 오브젝트의 생성을 위한 메소드를 가지는 IAMTimeline 인터페이스를 공개한다. 코드에 나타낸 것처럼,CoCreateInstance 함수를 호출해 각 컴퍼넌트를 생성 한다. 새로운 인스턴스의 생성에 의해, 그 인터페이스의 참조 카운트가 인크리먼트(increment) 되는 것을 잊지 않는 것. 메모리 누수를 회피하려면 , 인터페이스의 사용이 끝나면(자) 반드시 해방할 필요가 있다. 이 예에서는,IXml2Dex 를 가리키는 포인터는 필요없게 되므로, 이 인터페이스를 해방할 수 있다. IAMTimeline 를 가리키는 포인터는, 타임 라인의 프리뷰를 위해서(때문에) 아직 필요하다.

IXml2Dex::ReadXMLFile 메소드는, 지정된 파일을 읽어들여, 그 파일로 정의되고 있는 오브젝트를 타임 라인에 삽입한다. 파일명은,BSTR 값을 사용해 지정된다. 예의 코드를 짧게 하기 위해서, 여기에서는 파일명을 리터럴 캐릭터 라인으로서 지정하고 있다. 보통은,[파일을 여는] 다이알로그 박스등을 사용해 파일명을 취득한다.

ReadXML 메소드는, 동작이 성공했을 경우는 성공 코드를 돌려준다. 그렇지 않은 경우는,VFW_E_INVALID_FILE_FORMAT 등의 에러 코드를 돌려준다. 에러 조건을 올바르게 처리하기 위해서는, 항상 반환값을 체크할 필요가 있다. 예의 코드를 짧게 하기 위해서, 여기에서는 에러를 체크하고 있지 않다.

프로젝트의 프리뷰

프로젝트를 프리뷰 하기 위해서는, 타임 라인으로부터 DirectShow 필터 그래프를 구축하는렌더링 엔진으로 불리는 컴퍼넌트가 필요하다. 필터 그래프가, 프로젝트를 실제로 렌더링 한다. 렌더링 엔진을 사용해, 프로젝트의 프리뷰 및 최종 출력 파일의 기입을 실시할 수가 있다.

여기에서는, 렌더링 엔진의 상세한 것에 대하여는 설명하지 않는다. 프리뷰의 경우는, 몇개의 메소드 호출 밖에 필요로 하지 않는다. 출력 파일을 기입하는 방법등의 상세한 것에 대하여는, 「프로젝트의 렌더링」을 참조할것. 다음의 샘플 코드는, 프리뷰 그래프를 구축하는 방법을 나타내고 있다.

IRenderEngine *pRender = NULL;
hr = CoCreateInstance(CLSID_RenderEngine,
            NULL, CLSCTX_INPROC_SERVER,
            IID_IRenderEngine, (void**) &pRender);

hr = pRender->SetTimelineObject(pTL);
hr = pRender->ConnectFrontEnd( );
hr = pRender->RenderOutputPins( );

CoCreateInstance 함수를 사용해 렌더링 엔진을 생성 한다. 다음에, 렌더링 엔진의 IRenderEngine 인터페이스의 이하의 메소드를 호출한다.

  • SetTimelineObject . 사용하는 타임 라인을 지정한다.
  • ConnectFrontEnd . 필터 그래프를 구축해, 타임 라인내의 각그룹 마다 출력 핀을 1 개 설정한다.
  • RenderOutputPins . 각 출력 핀을 비디오 렌더러 또는 오디오 렌더러에 접속해, 프리뷰 그래프의 구축을 완료시킨다.

그래프가 구축되면, DirectShow 필터 그래프의 경우와 같이, 그 그래프를 실행하는 것으로써 프로젝트를 프리뷰 할 수 있다. 최초로,IRenderEngine::GetFilterGraph 메소드를 호출해, 필터 그래프에의 포인터를 취득한다.

IGraphBuilder   *pGraph = NULL;
hr = pRender->GetFilterGraph(&pGraph);

그 필터 그래프에,IMediaControl 및 IMediaEvent 인터페이스에 대해 조회한다. 이 2 개의 인터페이스를 사용해, 그래프를 실행해, 재생이 완료할 때까지 대기한다. 이러한 인터페이스의 사용법의 상세한 것에 대하여는, 「파일의 재생법」 및 「이벤트에의 응답」을 참조할것. 다음의 코드는, 이러한 인터페이스를 사용하는 방법의 1 개를 나타내고 있다.

IMediaControl   *pControl = NULL;
IMediaEvent     *pEvent = NULL;
long evCode;

pGraph->QueryInterface(IID_IMediaControl, (void **) &pControl);
pGraph->QueryInterface(IID_IMediaEvent, (void **) &pEvent);
hr = pControl->Run();
hr = pEvent->WaitForCompletion(INFINITE, &evCode);
pControl->Stop();

이 예의 코드는,IMediaEvent::WaitForCompletion 메소드 호출의 INFINITE 파라미터에 의해, 재생이 완료할 때까지 프로그램의 실행을 정지시킨다. 다만, 재생중에 문제가 발생했을 경우에는, 프로그램을 응답할 수 없게 될 가능성이 있다. 실제의 어플리케이션에서는, 메시지 루프를 사용해 재생이 완료할 때까지 대기한다. 또, 유저에게 재생을 중단시키는 방법을 제공하는 것이 추천 된다.

클린 업

렌더링 엔진의 사용이 끝나면(자), 반드시 IRenderEngine::ScrapIt 메소드를 호출한다. 이 메소드는, 필터 그래프를 삭제해, 렌더링 엔진이 보관 유지하고 있던 모든 리소스를 해방한다.

pRender->ScrapIt();

샘플 코드

이하는, 여기서 설명한 샘플 어플리케이션 전체의 코드이다.

#include <dshow.h>
#include <qedit.h>

// 타임 라인을 프리뷰 한다.
void PreviewTL(IAMTimeline *pTL, IRenderEngine *pRender)
{
    HRESULT hr;
    IGraphBuilder   *pGraph = NULL;
    IMediaControl   *pControl = NULL;
    IMediaEvent     *pEvent = NULL;

    // 그래프를 구축한다.
    hr = pRender->SetTimelineObject(pTL);
    hr = pRender->ConnectFrontEnd( );
    hr = pRender->RenderOutputPins( );

    // 그래프를 실행한다.
    hr = pRender->GetFilterGraph(&pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **) &pControl);
    pGraph->QueryInterface(IID_IMediaEvent, (void **) &pEvent);
    hr = pControl->Run();

    long evCode;
    hr = pEvent->WaitForCompletion(INFINITE, &evCode);
    pControl->Stop();

    // 클린 업 한다.
    pEvent->Release();
    pControl->Release();
    pGraph->Release();
}

void main( void )
{
    HRESULT         hr;
    IAMTimeline     *pTL = NULL;
    IRenderEngine   *pRender = NULL;
    IXml2Dex        *pXML = NULL;

    CoInitialize(NULL);
    hr = CoCreateInstance(CLSID_AMTimeline,
                NULL, CLSCTX_INPROC_SERVER,
                IID_IAMTimeline, (void**) &pTL);
    hr = CoCreateInstance(CLSID_Xml2Dex,
                NULL, CLSCTX_INPROC_SERVER,
                IID_IXml2Dex, (void**) &pXML);
    hr = CoCreateInstance(CLSID_RenderEngine,
                NULL, CLSCTX_INPROC_SERVER,
                IID_IRenderEngine, (void**) &pRender);

    // 프로젝트 파일을 로드한다.
    hr = pXML->ReadXMLFile(pTL, L"C:\\example.xtl");
    pXML->Release();

    PreviewTL(pTL, pRender);

    // 클린 업 한다.
    pRender->ScrapIt();
    pTL->Release();
    pRender->Release();
    CoUninitialize();
}


타임 라인의 구축

여기에서는, Microsoft® DirectShow® 편집 서비스 (DES)로타임 라인을 구축하는 방법을 설명하고 있다. 타임 라인을 생성 해 렌더링 하는 콘솔 프로그램의 예를 소개한다. 생성 하는 타임 라인은, 소스 클립 1 개(살)만의 단일의 비디오 그룹으로부터 되는 최소 규모의 것이지만, 보다 복잡한 타임 라인의 생성에 필요한 개념의 대부분이 나타나고 있다.

여기에는, 이하의 주제가 포함된다.

  • 타임 라인 오브젝트의 생성
  • 그룹, 합성, 및 트럭의 생성
  • 그룹 미디어 타입의 설정
  • 소스의 추가
  • 샘플 코드

타임 라인 오브젝트의 생성

여기서 소개하는 샘플 코드는 하늘의 타임 라인으로 시작되지만, 기존의 프로젝트를 로드해 오브젝트를 추가하는 경우도, 같은 순서가 적용된다.

타임 라인내에 어떠한 형태의 오브젝트를 생성 하려면 ,IAMTimeline::CreateEmptyNode 메소드를 호출해,합성, 그룹, 또는트럭 등, 생성 하는메이저 타입을 지정한다. 예를 들어, 다음의 코드는 새로운 그룹을 생성 한다.

IAMTimelineObj *pGroupObj = NULL;
pTL->CreateEmptyNode(&pGroupObj, TIMELINE_MAJOR_TYPE_GROUP);

CreateEmptyNode 메소드는, 오브젝트를 생성 해, 그 오브젝트의 IAMTimelineObj 인터페이스를 가리키는 포인터를 돌려준다. 이 메소드는,IAMTimelineObj 인터페이스의 참조 카운트도 인크리먼트(increment) 하므로, 사용을 끝냈을 때에는, 이 인터페이스도 해방해야 한다. CoCreateInstance 함수를 호출해서는 안 된다. 그렇지 않고, 반드시 CreateEmptyNode 를 사용해 타임 라인 오브젝트를 생성 한다. 이것은, 이 메소드가, 타임 라인으로 사용할 수 있도록(듯이) 새로운 오브젝트를 초기화하기 위해(때문에)이다.

IAMTimelineObj 인터페이스는, 범용 인터페이스이다. 이것은, 타임 라인 오브젝트의 모든 타입에 공통의 메소드를 제공한다. 오브젝트의 각 타입은, 다른 인터페이스도 공개한다. 예를 들어, 그룹은 IAMTimelineGroup 인터페이스를 공개한다. 다른 인터페이스를 가리키는 포인터는,QueryInterface 를 호출해 취득할 수 있다.

오브젝트를 생성 한 단계에서는, 아직 그것은 타임 라인의 일부로는 되지 않았다. 오브젝트를 타임 라인에 추가하는 메소드는, 오브젝트의 타입에 따라서 다르다. 다음의 섹션에서는, 그룹, 합성, 및 트럭을 타임 라인에 추가하는 방법을 설명한다.

그룹, 합성, 및 트럭의 생성

그룹, 합성, 및 트럭은, 타임 라인과 소스 클립과의 사이의 중간 계층이다. 이것들은, 그 중에 접어드는 오브젝트의 타입에 의해 구별된다.

  • 트럭에는, 소스 오브젝트가 들어간다.
  • 합성에는, 트럭 및 다른 합성이 들어가지만, 소스 오브젝트는 들어가지 않는다.
  • 그룹은, 최상정도 레벨의 합성이다. 그룹에는, 합성과 트럭이 들어가지만, 합성안에 그룹을 넣을 수 없다.
  • 가상 트럭은, 합성 또는 그룹내에 배치할 수 있는 임의의 오브젝트이다. 이것에는, 트럭 및 합성이 포함된다.

이하의 인터페이스는, 이러한 오브젝트에 의해 공개된다.

인터페이스 | 인터페이스를 공개하는 오브젝트
IAMTimelineTrack | 트럭
IAMTimelineVirtualTrack | 트럭, 합성
IAMTimelineComp | 합성, 그룹
IAMTimelineGroup | 그룹

이러한 인터페이스에는, 오브젝트를 타임 라인에 추가하는 메소드가 포함되어 있다.

  • IAMTimeline::AddGroup : 타임 라인에 그룹을 삽입한다.
  • IAMTimelineComp::VTrackInsBefore : 합성 또는 그룹에 가상 트럭을 삽입한다.
  • IAMTimelineTrack::SrcAdd : 트럭에 소스를 삽입한다.

예를 들어, 다음의 코드는 새로운 트럭을 그룹에 삽입한다. 전의 겉(표)에 나타낸 것처럼, 그룹은 합성의 일종이라고 생각되어 트럭은 가상 트럭의 일종이라고 생각된다. 따라서, 트럭을 그룹에 삽입하려면 , 그룹에 그 IAMTimelineComp 인터페이스에 대해 조회해,IAMTimelineComp::VTrackInsBefore 메소드를 호출하지 않으면 안 된다.

IAMTimelineGroup    *pGroup;
// 새로운 그룹을 생성 한다 (여기에는 나타나지 않았다).

IAMTimelineComp     *pComp = NULL;
IAMTimelineObj      *pTrackObj = NULL;

pTL->CreateEmptyNode(&pTrackObj, TIMELINE_MAJOR_TYPE_TRACK);
pGroup->QueryInterface(IID_IAMTimelineComp, (void **) &pComp);
pComp->VTrackInsBefore(pTrackObj, 0);

VTrackInsBefore 의 2 번째의 파라미터는, 가상 트럭의 우선 순위를 지정한다. 우선 순위 레벨은 제로로부터 시작된다. -1 (을)를 지정했을 경우, 가상 트럭은 우선 순위 리스트의 마지막에 삽입된다. 이미 가상 트럭이 존재하는 레벨의 값을 지정했을 경우, 그 위치 이하의 모든 오브젝트의 우선 순위 레벨이 1 두개 내릴 수 있다. 가상 트럭의 개수보다 큰 우선 순위 레벨의 가상 트럭을 삽입해서는 안 된다. 그것을 실시했을 경우의 동작은 미정도리가 된다.

타임 라인으로부터 오브젝트를 완전하게 삭제하려면 , 그 오브젝트의 IAMTimelineObj::RemoveAll 메소드를 호출한다. 이 메소드는, 오브젝트와 그 아이를 모두 삭제한다. 오브젝트를 타임 라인의 다른 장소에 재삽입하는 목적으로 삭제하려면 , 대신에 IAMTimelineObj::Remove 를 호출한다. RemoveAll 와 달리, 이 메소드는 오브젝트의 아이는 삭제하지 않는다. 타임 라인으로부터 모든 것을 삭제하려면 ,IAMTimeline::ClearAllGroups 를 호출한다.

그룹 미디어 타입의 설정

모든 그룹은, 비압축의 미디어 타입으로서 오디오 또는 비디오를 정의해야 한다. 비압축 미디어 타입은, 재생시에 뷰아가 본다, 또는 듣는 포맷이다. 보통, 최종 출력은 비압축 포맷이다. 상세한 것에 대하여는, 「프로젝트의 렌더링」을 참조할것.

비압축 포맷을 설정하려면 ,AM_MEDIA_TYPE 구조체를 생성 해, 그 멤버로서 적절한 메이저 타입, 서브 타입, 및 포맷 헤더를 설정한다. 비디오의 경우는, 포맷 헤더에 폭, 높이, 및 비트 깊이를 설정한다. 오디오의 경우는, 포맷 헤더에 샘플링 레이트를 설정한다. 메이저 타입만을 설정했을 경우, DES 는 다른 값에 적절한 디폴트를 설정한다. 실제로는, 출력을 명시적으로 제어하는 경우에는 값을 설정할 필요가 있다. CMediaType base class는, AM_MEDIA_TYPE 구조체를 관리하는 편리한 방법을 제공한다. 그러한 차면, AM_MEDIA_TYPE 구조체를 직접 조작할 수도 있다.

미디어 타입 구조체를 초기화한 후,IAMTimelineGroup::SetMediaType 메소드를 호출해 그룹의 미디어 타입을 설정한다.

다음의 예는, 폭 320 픽셀, 높이 240 픽셀의 16 비트 RGB 비디오를 지정하고 있다.

AM_MEDIA_TYPE mtGroup;
mtGroup.majortype = MEDIATYPE_Video;
mtGroup.subtype = MEDIASUBTYPE_RGB555;

// 포맷 헤더를 설정한다.
mtGroup.pbFormat = (BYTE*) CoTaskMemAlloc(sizeof(VIDEOINFOHEADER));
VIDEOINFOHEADER *pVideoHeader = (VIDEOINFOHEADER*) mtGroup.pbFormat;
ZeroMemory(pVideoHeader, sizeof(VIDEOINFOHEADER));
pVideoHeader->bmiHeader.biBitCount = 16;
pVideoHeader->bmiHeader.biWidth = 320;
pVideoHeader->bmiHeader.biHeight = 240;
pVideoHeader->bmiHeader.biPlanes = 1;
pVideoHeader->bmiHeader.biSize = sizeof(BITMAPINFOHEADER);
pVideoHeader->bmiHeader.biSizeImage = DIBSIZE(pVideoHeader->bmiHeader);

mtGroup.formattype = FORMAT_VideoInfo;
mtGroup.bFixedSizeSamples = TRUE;
mtGroup.lSampleSize = DIBSIZE(pVideoHeader->bmiHeader);

// 그룹의 미디어 타입을 설정한다.
pGroup->SetMediaType( &mtGroup );

소스의 추가

소스 오브젝트는, 다른 타임 라인 오브젝트와 같은 방법으로 생성 한다. 다만, 타임 라인에 삽입하기 전에, 적어도 소스 위에의 이하의 프로퍼티를 지정해야 한다.

  • 타임 라인 상대의 시작 타임과 종료 타임. IAMTimelineObj::SetStartStop 메소드를 호출한다.
  • 소스로서 사용하는 미디어 파일. IAMTimelineSrc::SetMediaName 메소드를 호출해, 파일의 이름을 나타내는 와이드 캐릭터 라인을 지정한다.
  • 원의 파일 상대의 미디어 시작 타임과 미디어 종료 타임. IAMTimelineSrc::SetMediaTimes 메소드를 호출한다. 미디어 타임의 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

다음의 예에서는, 소스 클립은 파일내의 4 초의 위치로부터 시작된다. 미디어의 시간폭은 10 초로, 타임 라인의 길이의 2 배이며, 이것은 소스가 보통의 2 배의 속도로 재생되는 것을 의미한다. 정수 UNITS 는, 10000000 (107)으로서 정의되어 이것은 1 초에 동일하다.

pSourceObj->SetStartStop(0, 50000000)
pSource->SetMediaName(L"C:\\Example.avi");
pSource->SetMediaTimes(40000000, 140000000);

주 : 현재 DES 는, 비디오 압축 매니저 (VCM) CODEC 로 압축된 소스는, 동시에 75 개까지 밖에 렌더링 할 수 없다. 또, 그러한 소스가 프로젝트 전체로 75 개를 넘는 경우는, 동적인 재접속을 사용하지 않으면, DES 는 프로젝트를 프리뷰 할 수 없다. 상세한 것에 대하여는, 「IRenderEngine::SetDynamicReconnectLevel 」를 참조할것.

소스의 상세한 것에 대하여는, 「소스의 조작」을 참조할것.

샘플 코드

이하는, 여기서 설명한 샘플 어플리케이션 전체의 코드이다.

주 : 간결하게 하기 위해서, 샘플 코드에서는 에러 체크를 실시하지 않았다. 실제의 어플리케이션에서는, 메소드 호출의 반환값을 체크해, 실패가 없게 할 필요가 있다.

#include <dshow.h>
#include <qedit.h>

// 타임 라인을 프리뷰 한다.
void PreviewTL(IAMTimeline *pTL, IRenderEngine *pRender)
{
    IGraphBuilder   *pGraph = NULL;
    IMediaControl   *pControl = NULL;
    IMediaEvent     *pEvent = NULL;

    // 그래프를 구축한다.
    pRender->SetTimelineObject(pTL);
    pRender->ConnectFrontEnd( );
    pRender->RenderOutputPins( );

    // 그래프를 실행한다.
    pRender->GetFilterGraph(&pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **) &pControl);
    pGraph->QueryInterface(IID_IMediaEvent, (void **) &pEvent);
    pControl->Run();

    long evCode;
    pEvent->WaitForCompletion(INFINITE, &evCode);
    pControl->Stop();

    // 클린 업 한다.
    pEvent->Release();
    pControl->Release();
    pGraph->Release();
}

void main( void )
{
    // 최초로 하늘의 타임 라인을 생성 한다.

    IAMTimeline    *pTL = NULL;
    CoInitialize(NULL);
    CoCreateInstance(CLSID_AMTimeline, NULL, CLSCTX_INPROC_SERVER,
            IID_IAMTimeline, (void**) &pTL);

    // 그룹 :  타임 라인에 비디오 그룹을 추가한다.
    IAMTimelineGroup    *pGroup = NULL;
    IAMTimelineObj      *pGroupObj = NULL;

    pTL->CreateEmptyNode(&pGroupObj, TIMELINE_MAJOR_TYPE_GROUP);
    pGroupObj->QueryInterface(IID_IAMTimelineGroup, (void **) &pGroup);

    // 그룹의 미디어 타입을 설정한다.
    AM_MEDIA_TYPE mtGroup;
    ZeroMemory(&mtGroup, sizeof(AM_MEDIA_TYPE));
    mtGroup.majortype = MEDIATYPE_Video;
    pGroup->SetMediaType(&mtGroup);
    pTL->AddGroup(pGroupObj);
    pGroupObj->Release();

    // 트럭 :  그룹에 트럭을 추가한다.
    IAMTimelineObj      *pTrackObj;
    IAMTimelineTrack    *pTrack;
    IAMTimelineComp     *pComp = NULL;

    pTL->CreateEmptyNode(&pTrackObj, TIMELINE_MAJOR_TYPE_TRACK);
    pGroup->QueryInterface(IID_IAMTimelineComp, (void **) &pComp);
    pComp->VTrackInsBefore(pTrackObj, 0);
    pTrackObj->QueryInterface(IID_IAMTimelineTrack, (void **) &pTrack);

    pTrackObj->Release();
    pComp->Release();
    pGroup->Release();

    // 소스 :  트럭에 소스를 추가한다.
    IAMTimelineSrc      *pSource = NULL;
    IAMTimelineObj      *pSourceObj;
    pTL->CreateEmptyNode(&pSourceObj, TIMELINE_MAJOR_TYPE_SOURCE);
    pSourceObj->QueryInterface(IID_IAMTimelineSrc, (void **) &pSource);

    // 타임과 파일명을 설정한다.
    pSourceObj->SetStartStop(0, 50000000);
    pSource->SetMediaName(L"C:\\Example.avi");
    pSource->SetMediaTimes(40000000, 140000000);
    pTrack->SrcAdd(pSourceObj);

    pSourceObj->Release();
    pSource->Release();
    pTrack->Release();

    // 타임 라인을 프리뷰 한다.
    IRenderEngine       *pRenderEngine = NULL;
    CoCreateInstance(CLSID_RenderEngine, NULL, CLSCTX_INPROC_SERVER,
            IID_IRenderEngine, (void**) &pRenderEngine);
    PreviewTL(pTL, pRenderEngine);

    // 클린 업 한다.
    pRenderEngine->ScrapIt();
    pTL->ClearAllGroups();
    pRenderEngine->Release();
    pTL->Release();
    CoUninitialize();
}


소스의 조작

소스 오브젝트는, 원시 파일로부터의 단일의 미디어 스트림을 나타낸다. 소스는, 프로젝트에 미가공의 소재를 제공한다. 타임 라인내의 그 이외의 것은, 구조 (트럭,합성, 및그룹)를 제공하는지, 소스를 변경하는 (이펙트 및 트란지션) 위해(때문에) 존재한다.

여기에서는, Microsoft® DirectShow® 편집 서비스 (DES)의 소스에 관한 상세를 설명하고 있다. 타임 라인에 소스를 추가하는 기본적인 순서에 대해서는, 「타임 라인의 구축」을 참조할것.

여기에는 이하의 섹션이 포함된다.

  • 소스의 프로퍼티의 설정
  • 미디어 detector의 사용법
  • 미디어 locator의 사용법
  • 스티르이메이지
  • 비디오 칼라 소스

소스의 프로퍼티의 설정

새로운 소스 오브젝트를 생성 할 경우에, 설정할 필요가 있는 프로퍼티와 옵션으로 설정할 수 있는 프로퍼티가 있다. 이하의 프로퍼티는 설정해야 한다.

  • 타임 라인의 나머지의 부분에 상대의 시작 타임과 종료 타임. IAMTimelineObj::SetStartStop 메소드를 호출한다. 같은 트럭내의 소스 오브젝트로 서로 겹치는 시간을 설정해서는 안 된다. 그러한 설정을 실시하면, 미정도리의 동작을 일으킨다.
  • 소스 클립으로서 사용하는 미디어 파일. IAMTimelineSrc::SetMediaName 메소드를 호출한다.
  • 원의 원시 파일 상대의 미디어 시작 타임과 미디어 종료 타임. IAMTimelineSrc::SetMediaTimes 메소드를 호출한다. 예외 : 소스가 스티르이메이지의 경우는, 미디어 타임을 지정해서는 안 된다. 미디어 타임의 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

소스 오브젝트는 친그룹으로부터 미디어 타입을 계승하므로, 미디어 타입을 지정할 필요는 없다.

옵션의 프로퍼티는 다음과 같다.

  • 신축 모드. 신축 모드는, 사이즈가 출력 넓이와 일치하지 않는 소스를 Microsoft® DirectShow® 편집 서비스 (DES)가 렌더링 하는 방법을 지정한다. 디폴트에서는, DES 는 어스펙트비(가로세로 비율)을 유지하지 않고 이미지를 신축한다. DES 는, 이미지를 절약하는 것, 및 레터박스를 생성 할 수도 있다. 신축 모드는,IAMTimelineSrc::SetStretchMode 메소드를 호출해 지정한다.
  • 원시 파일의 시간폭. 미디어 타임을 설정하는 동안에 이 프로퍼티를 설정했을 경우, DES 는 미디어 종료 타임을 검증해, 파일의 시간폭을 넘는 경우는 종료 타임을 앞당긴다. 이것에 의해, 다음에 렌더링 에러가 나오는 것을 막을 수가 있다. 「미디어 detector의 사용법」으로 설명하고 있도록(듯이), 미디어 detector를 사용해 파일의 시간폭을 취득할 수 있다. 파일의 시간폭은,IAMTimelineSrc::SetMediaLength 메소드를 호출해 지정한다.
  • 스트림 번호. 디폴트로 소스 오브젝트는, 파일내에서 친그룹의 미디어 타입에 일치하는 최초의 스트림을 사용한다. 파일에 같은 미디어 타입이 2 개 이상 있는 경우는,IAMTimelineSrc::SetStreamNumber 를 호출해, 사용하는 스트림을 선택한다. 미디어 detector를 사용해, 스트림의 개수를 취득할 수 있다.

미디어 detector의 사용법

미디어 detector는, 스트림의 개수, 타입, 시간폭 등, 파일에 관한 정보를 취득하기 위한 헬퍼 오브젝트이다. 미디어 detector에게는, 비디오 스트림으로부터 포스터 프레임을 취득하는 메소드도 포함되어 있다. 이것은,IMediaDet 인터페이스를 공개한다.

미디어 detector가 기능하는 모드는 2 개 있다. 미디어 detector의 인스턴스를 생성 한 시점에서는, 특정의 원시 파일에는 어태치 하고 있지 않다. 이 모드에서는, 복수의 원시 파일로부터 스트림 정보를 취득할 수 있다. 그러나, 미디어 detector를 사용해 포스터 프레임을 취득 하면, 미디어 detector는비트 맵 포착 모드에 바뀐다. 비트 맵 포착 모드에서는, 미디어 detector는 특정의 비디오 스트림에 어태치 되어 스트림 정보 메소드는 기능하지 않게 된다. 또, 미디어 detector를 기동시의 모드에 되돌리는 방법은 없다. 그 때문에, 스트림 정보의 취득은 포스터 프레임의 취득전에 실시할 필요가 있다. 그렇지 않은 경우는, 스트림 마다 미디어 detector의 새로운 인스턴스를 생성 하게 된다.

스트림 정보를 취득하는 순서는 이하대로이다.

  1. IMediaDet::put_Filename 를 호출해, 원시 파일의 이름을 지정한다.
  2. IMediaDet::get_OutputStreams 를 호출해, 소스내의 스트림의 개수를 취득한다.
  3. IMediaDet::put_CurrentStream 를 호출해, 스트림 번호를 지정한다. 이하의 메소드를 1 개 이상 호출한다.
    • IMediaDet::get_StreamType : 스트림의 미디어 타입을 취득한다.
    • IMediaDet::get_StreamLength : 스트림의 시간폭을 취득한다.
    • IMediaDet::get_FrameRate : 비디오 스트림의 frame rate를 취득한다.

포스터 프레임을 취득하려면 , 전의 순서와 같이 해 스트림 번호를 지정한다. IMediaDet::GetBitmapBits 를 호출해 포스터 프레임을 버퍼에 카피하는지,IMediaDet::WriteBitmapBits 를 호출해 포스터 프레임을 파일에 보존한다.

미디어 locator의 사용법

미디어 locator는, 파일명을 검증해, 로컬 디렉토리 또는 네트워크 디렉토리에서 부족한 파일을 검색하는 헬퍼 오브젝트이다. 미디어 locator는, 과거의 검색으로 파일이 발견된 디렉토리 패스의 캐쉬를 유지한다. 파일을 찾아내기 위해서(때문에), 미디어 locator는 이 캐쉬내의 디렉토리를 검색한다. 거기서 발견되지 않았던 경우, 미디어 locator는 [파일을 여는] 다이얼로그를 표시해, 유저가 수동으로 파일을 찾아낼 수 있도록(듯이) 한다. 유저가 파일을 찾아냈을 경우, 미디어 locator는 그 새로운 디렉토리를 캐쉬에 추가한다. 미디어 locator는 IMediaLocator 인터페이스를 공개한다.

보통, 어플리케이션으로 미디어 locator의 인스턴스를 직접 생성 할 것은 없다. 타임 라인 및 렌더링 엔진은, 미디어 detector를 사용해 파일명을 검증하는 이하의 메소드를 제공하고 있다.

  • 타임 라인으로 파일명을 검증하려면 ,IAMTimeline::ValidateSourceNames 를 호출한다. 옵션으로, 이 메소드는 소스 오브젝트를 올바른 파일명으로 갱신한다.
  • 프로젝트가 렌더링 될 때 파일명을 검증하려면 ,IRenderEngine::SetSourceNameValidation 를 호출한다.

어느 쪽의 메소드도, 미디어 locator의 동작을 제어하는 플래그를 파라미터에 있다. 예를 들어, 검색을 로컬 디렉토리에만 한정할 수 있다.

스티르이메이지

DES 는, 스티르이메이지에 관해서 다음의 파일 포맷을 지원 하고 있다.

  • 비트 맵 (. bmp)
  • GIF (Graphics Interchange Format)
  • JPEG (Joint Photographic Experts Group)
  • 16 비트, 24 비트, 또는 32 비트의 Targa 즉 Truevision Graphics Adapter (. tga) : 모드 2 (비압축 RGB)

이것들은, 스티르이메이지로서 사용하는지, 또는 애니메이션의 생성에 사용할 수 있다. 비트 맵, JPEG, 및 Targa 파일에 관해서, 파일을 스티르이메이지로서 사용하는 경우는,IAMTimelineSrc::SetDefaultFPS 메소드를 호출해, frame rate를 0 으로 설정한다.

DIB 순서

일련의 비트 맵, JPEG, 또는 Targa 파일에 대해서, 렌더링 엔진은디바이스에 의존하지 않는 비트 맵 (DIB)의 순서를 구축할 수 있다. DIB 순서를 생성 하려면 , 파일명에 Image001.bmp, Image002.bmp, Image003.bmp 와 같은 시퀀셜인 숫자를 붙인다. 이 순서의 최초의 파일을 소스로서 사용해,IAMTimelineSrc::SetDefaultFPS 를 호출해, 순서의 frame rate를 설정한다. 렌더링 엔진은, 지정된 frame rate로, 순서 없는 것 이미지를 순서에 처리한다.

지정된 frame rate로, 순서가 시간폭에 못 미친 경우, 시간폭의 나머지는 블랙이 된다. 렌더링중에 에러는 발생하지 않는다.

GIF 소스

DES 는, GIF89a 사양의 사용에 의해, 애니메이션 GIF 및 투과 GIF 를 포함해 GIF 소스를 지원 하고 있다. 애니메이션 GIF 의 경우는, 다른 파일 타입과는 달라, frame rate를 설정할 필요는 없다. GIF 파일은, 애니메이션내의 각 이미지간의 지연을 지정한다.

투과 GIF 를 지원 하기 위해서, DES 는 이미지내의 투과 리젼을 RGB(0,0,0)의 RGB 셋잇단음표로 변환한다. 이것에 의해,키트란지션을 사용해,RGB(0,0,0) 위에의 키에 키트란지션을 사용할 수 있다.

DES 는, RGB(0-7,0-7,0-7)의 범위의 흑의 리젼도, 투과성 인덱스를 제외해, RGB(8,8,8)의 값으로 변환한다. 이 변환은, 목시에서는 확인할 수 없다.

비디오 칼라 소스

비디오 칼라 소스 오브젝트는, 단색의 연속적인 비디오 이미지를 생성 한다. 이 오브젝트의 1 개의 사용법에는, 트란지션시의 계층 생성이 있다. 예를 들어, 이 오브젝트를 사용하면, 비디오의 용명이나 용암을 생성 할 수 있다.


이펙트와 트란지션의 조작

여기에서는, Microsoft® DirectShow® 편집 서비스 (DES)에 있어서의 이펙트와 트란지션의 사용법을 설명하고 있다. 이하의 섹션이 포함된다.

  • 이펙트 및 트란지션오브제크트의 추가
  • 이펙트 및 트란지션의 프리뷰
  • 이펙트 및 트란지션의 열거
  • 이펙트 및 트란지션의 프로퍼티의 설정
  • 트란지션의 방향

이펙트 및 트란지션오브제크트의 추가

이펙트 오브젝트 또는 트란지션오브제크트를 추가하려면 , 이하의 순서를 실행한다.

  1. 이펙트 오브젝트 또는 트란지션오브제크트를 생성 한다.

    IAMTimeline::CreateEmptyNode 메소드를,메이저 타입 TIMELINE_MAJOR_TYPE_EFFECT 또는 TIMELINE_MAJOR_TYPE_TRANSITION 에 의해 호출한다. 이펙트는 IAMTimelineEffect 인터페이스를 공개해, 트란지션은 IAMTimelineTrans 인터페이스를 공개한다. 상세한 것에 대하여는, 「타임 라인 오브젝트의 생성」을 참조할것.

  2. 서브 오브젝트를 설정한다.

    이펙트 오브젝트와 트란지션오브제크트는, 서브 오브젝트를 위한 래퍼이다. 데이터 변환을 이행 하는 것으로써, 서브 오브젝트가 실제의 기능을 완수한다. 이펙트 오브젝트 또는 트란지션오브제크트는, 서브 오브젝트를 사용해 오디오 또는 비디오 스트림을 변환한다. 임의의 단일 입력 Microsoft® DirectX® 변환 오브젝트를 이펙트로서 사용할 수 있어 임의의 쌍입력 DirectX 변환 오브젝트를 트란지션으로서 사용할 수 있다. DirectShow 오디오 이펙트 필터는, 오디오 그룹내의 이펙트로서 기능할 수 있다. DES 는, 볼륨의 설정을 실시하는,볼륨 포락선으로 불리는 특수한 오디오 이펙트도 제공하고 있다. 타임 라인내의 각 오브젝트가 가질 수가 있는 볼륨 포락선 이펙트는, 최대로 1 개이다. 다른 이펙트에 대해서는, 이러한 제한은 없다.

    이펙트 또는 트란지션오브제크트를 생성 하면(자), 서브 오브젝트의 클래스 식별자 (CLSID)를 사용해 IAMTimelineObj::SetSubObjectGUID 를 호출한다. 유저의 시스템상에서 사용 가능한 이펙트와 트란지션을 열거하는 방법에 대해서는, 「이펙트 및 트란지션의 열거」를 참조할것.

  3. 시작 타임과 종료 타임을 설정한다.

    IAMTimelineObj::SetStartStop 메소드를 호출해, 친오브젝트 상대의 시작 타임과 종료 타임을 설정한다.

  4. 프로퍼티를 설정한다.

    다수의 이펙트와 트란지션이, 커스텀 프로퍼티를 지원 하고 있다. 이러한 프로퍼티의 설정 방법법에 대해서는, 「이펙트 및 트란지션의 프로퍼티의 설정」을 참조할것.

  5. 이펙트 오브젝트 또는 트란지션오브제크트를 타임 라인에 삽입한다.

    친오브젝트의, 다음의 몇개의 메소드를 호출한다.

    • 이펙트 : IAMTimelineEffectable::EffectInsBefore
    • 트란지션 : IAMTimelineTransable::TransAdd

    친오브젝트는, 복수의 이펙트 및 트란지션을 가질 수가 있다. 이펙트는 같은 오브젝트에 거듭해 사용할 수 있지만, 트란지션은 그러한 사용법은 할 수 없다. 각 오브젝트 마다, 그 이펙트가, 우선 순위에 따라, 우선 순위 제로로부터 순서에 렌더링 된다 (우선 순위 레벨은,EffectInsBefore 를 호출하면나무로 지정한다).

다음의 샘플 코드에서는,SMPTE 와이프트란지션을 트럭에 추가하고 있다. 여기에서는, 트럭은 벌써 생성 되고 있는 것으로 한다.

// IAMTimeline *pTL;
// IAMTimelineTrack *pTrack;

// 트란지션오브제크트를 생성 한다.
IAMTimelineObj *pTransObj = NULL;
hr = pTL->CreateEmptyNode(&pTransObj, TIMELINE_MAJOR_TYPE_TRANSITION);

// 서브 오브젝트를 설정한다.
hr = pTransObj->SetSubObjectGUID(CLSID_DxtJpeg);  // SMPTE 와이프

// 시작 타임과 종료 타임을 설정한다.
hr = pTransObj->SetStartStop(0000000, 100000000);

// 트란지션오브제크트를 타임 라인에 삽입한다.
IAMTimelineTransable *pTransable = NULL;
hr = pTrack->QueryInterface(IID_IAMTimelineTransable, (void **) &pTransable);
hr = pTransable->TransAdd(pTransObj);
hr = pTransObj->Release();

이펙트 및 트란지션의 프리뷰

일부의 이펙트 및 트란지션은, 외와 비교해 렌더링에 시간이 걸린다. 프리뷰중에, 이것이 원인으로 비디오가 흐트러지거나 오디오와의 동기 금액 빗나가는 경우가 있다. 이펙트 또는 트란지션을 무효로 하는 것으로, 프리뷰의 속도를 올릴 수가 있다.

  • 모든 이펙트를 무효로 하려면 ,IAMTimeline::EnableEffects 를 호출한다.
  • 모든 트란지션을 무효로 하려면 ,IAMTimeline::EnableTransitions 를 호출한다.
  • 특정의 트란지션을 무효로 하려면 ,IAMTimelineTrans::SetCutsOnly 를 호출한다.

이펙트가 무효가 되면(자), 프리뷰시에 이펙트는 렌더링 되지 않는다. 트란지션이 무효가 되면(자), 트란지션은 직접 변환으로서 렌더링 된다. 그런데도 트럭간의 변환 하행 깨지지만, 비주얼 이펙트는 렌더링 되지 않는다.

이펙트 또는 트란지션이 렌더링 할 수 없는 경우, 렌더링 엔진은 디폴트의 이펙트 또는 트란지션에 옮겨놓는다. 디폴트 이펙트의 설정은 IAMTimeline::SetDefaultEffect 메소드를 호출해 실시해, 디폴트의 트란지션의 설정은 IAMTimeline::SetDefaultTransition 메소드를 호출해 실시한다. 디폴트를 지정하고 있지 않는 경우, 또는 지정한 내용으로 에러가 발생했을 경우는, DES 자체의 디폴트가 사용된다.

주 : frame buffer의 용량을 크게 하는 것에 의해도, 프리뷰의 품질을 높일 수가 있다. 상세한 것에 대하여는, 「IAMTimelineGroup::SetOutputBuffering 」를 참조할것.

이펙트 및 트란지션의 열거

DirectShow 는, 디바이스를 열거하기 위한시스템 디바이스 열거자를 제공하고 있다. 이것을 사용해, 유저의 시스템에 인스톨 되고 있는 이펙트 또는 트란지션을 위한 모니카를 취득할 수 있다.

시스템 디바이스 열거자는,ICreateDevEnum 인터페이스를 공개한다. 이것은, 지정된 디바이스 카테고리를 위한 카테고리 열거자를 돌려준다. 카테고리 열거자는,IEnumMoniker 인터페이스를 공개해, 카테고리내의 각 디바이스의 모니카를 돌려준다. ICreateDevEnem 의 사용법의 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것. 이하에, DirectShow 편집 서비스에서의 사용법의 요약을 나타낸다.

이펙트 또는 트란지션을 열거하려면 , 이하의 순서를 실행한다.

  1. 시스템 디바이스 열거자의 인스턴스를 생성 한다.
  2. ICreateDevEnum::CreateClassEnumerator 메소드를 호출해, 카테고리 열거자를 취득한다. 카테고리는, 클래스 식별자 (CLSID)에 의해 정의되고 있다. 이펙트의 경우는 CLSID_VideoEffects1Category, 트란지션의 경우는 CLSID_VideoEffects2Category 를 사용한다.
  3. IEnumMoniker::Next 를 호출해, 열거내의 각 모니카를 취득한다.
  4. 각 모니카 마다 IMoniker::BindToStorage 를 호출해, 관련지을 수 있고 있는프로퍼티 가방을 취득한다.
  5. 프로퍼티 가방에는, 그 이펙트 또는 트란지션의 프렌들리명과 글로벌 유니크 식별자 (GUID)가 들어가 있다. 어플리케이션에서는, 프렌들리명의 리스트를 표시할 수 있어 대응하는 GUID 를 취득할 수 있다.

다음의 샘플 코드는, 이상의 순서를 나타내고 있다.

ICreateDevEnum *pCreateDevEnum;
IEnumMoniker *pEm;
CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER,
        IID_ICreateDevEnum, (void**) &pCreateDevEnum);

pCreateDevEnum->CreateClassEnumerator(
        CLSID_VideoEffects1Category,  // 이펙트의 카테고리.
        &pEnumMoniker, 0);            // 트란지션에 CLSID_VideoEffects2Category 를 사용한다.

ULONG cFetched;
IMoniker *pMoniker;
while(S_OK == pEnumMoniker->Next(1, &pMoniker, &cFetched))
{
    HRESULT hr;
    IPropertyBag *pBag;
    hr = pMoniker->BindToStorage(0, 0, IID_IPropertyBag, (void **) &pBag);
    if(SUCCEEDED(hr))
    {
        VARIANT var;
        var.vt = VT_BSTR;
        hr = pBag->Read(L"FriendlyName", &var, NULL);
        if (SUCCEEDED(hr))
        {
            if ( ... )  // var.bstrVal 가 목적의 이름인가 어떤가 체크한다.
            {
                VARIANT var2;
                GUID guid;
                pBag->Read(L"guid", &var2, NULL);
                GuidFromString(var2.bstrVal, &guid);
                SysFreeString(var2.bstrVal);
                // 이것으로 GUID 는 이펙트의 CLSID 가 된다.
                break;
            }
            SysFreeString(var.bstrVal);
        }
        pBag->Release();
    }
    pMoniker->Release();
}
pEnumMoniker->Release();
pCreateDevEnum->Release();

이펙트 및 트란지션의 프로퍼티의 설정

다수의 이펙트와 트란지션으로, 그 외관을 제어하는 프로퍼티가 지원 되고 있다. 예를 들어,볼륨 포락선 이펙트에는, 볼륨 레벨을 지정하는 프로퍼티가 있다. 어플리케이션에서는,IPropertySetter 인터페이스를 사용해, 시간의 범위를 넘어 프로퍼티의 값을 설정할 수 있다.

프로퍼티를 설정하려면 , 이하의 순서를 실행한다.

  1. 프로파티셋타 (CLSID_PropertySetter)의 인스턴스를 생성 한다.
  2. DEXTER_PARAM 및 DEXTER_VALUE 구조체에, 프로퍼티 데이터를 설정한다. 이 2 개의 구조체에 대해서는 다음에 설명한다.
  3. DEXTER_PARAM 및 DEXTER_VALUE 구조체를 IPropertySetter::AddProp 메소드에 건네준다.
  4. 설정하는 각 프로퍼티 마다, 순서 2 로 3 을 반복한다.
  5. IPropertySetter 인터페이스 포인터를 IAMTimelineObj::SetPropertySetter 메소드에 건네준다.

DEXTER_PARAM 구조체는, 설정 대상의 프로퍼티를 지정한다. 이하의 멤버가 있다.

  • Name : 프로퍼티의 이름
  • dispID : 프로퍼티의 디스팟치 식별자 (DISPID)
  • nValues : 값의 개수

프로퍼티의 DISPID 를 알 수 있고 있는 경우는,dispID 멤버로 설정한다. 보통, 이 멤버는 제로로 설정해,Name 멤버에 프로퍼티의 이름을 설정한다.

DEXTER_VALUE 구조체는, 소정의 시점에서의 프로퍼티의 값을 지정한다. 이하의 멤버가 있다.

  • v : 프로퍼티의 새로운 값을 지정하는 VARIANT 형. 이 VARIANT 의 vt 멤버는, 프로퍼티의 데이터형을 정의한다. VARIANT 형의 상세한 것에 대하여는, 「Platform SDK」를 참조할것.
  • rt : 프로퍼티가 이 값이다고 보여지는, 이펙트 또는 트란지션의 시작 타임 상대의 기준 타임. 이펙트 또는 트란지션의 시작 타임은, 그 친오브젝트의 시작 타임 상대이다.
  • dwInterp : 프로퍼티가 전의 값으로부터 새로운 값에 어떻게 변화하는지를 지정하는 플래그. DEXTERF_JUMP 플래그의 경우, 프로퍼티는 지정된 시점에서 즉석에서 새로운 값에 바뀐다. DEXTERF_INTERPOLATE 플래그의 경우, 프로퍼티는 전의 값으로부터 선형적으로 보간 된다.

vt 멤버를 VT_BSTR 로 설정했을 경우, 프로파티셋타는 필요한 변환을 모두 실시한다. 부동 소수점값의 경우에는, 소수점의 전에 제로가 포함된다. 예를 들어,. 3 은 아니고 0.3 이 된다.

프로퍼티의 값은 시간의 경과에 따라 변화할 수 있으므로,IPropertySetter::AddProp 메소드는 단일의 DEXTER_PARAM 구조체와 DEXTER_VALUE 구조체의 배열에의 포인터를 파라미터에 있다. 이 배열은, 프로퍼티의 시간에 근거하는 값세트를 정의한다. 배열의 멤버는, 승순의 시계열에 따르지 않으면 안되어, DEXTER_PARAM 구조체의 nValues 멤버는 배열의 길이에 동일하지 않으면 안 된다.

다음의 샘플 코드는,SMPTE 와이프트란지션의 프로퍼티 데이터를 생성 한다. 여기에서는 와이프 코드를 120 으로 설정해, 이것은 타원 와이프를 생성 한다. 기준 타임은, 트란지션의 시작시를 나타내는 제로로 설정된다.

IPropertySetter     *pProp;   // 프로파티셋타
IAMTimelineObj      *pTransObj;  // 트란지션오브제크트
// SMPTE 와이프트란지션오브제크트를 생성 한다  (여기에는 나타나지 않았다)

CoCreateInstance(CLSID_PropertySetter,
    NULL, CLSCTX_INPROC_SERVER,
    IID_IPropertySetter, (void**) &pProp);

DEXTER_PARAM param;
DEXTER_VALUE *pValue = (DEXTER_VALUE *) CoTaskMemAlloc(sizeof(DEXTER_VALUE));

// 파라미터를 초기화한다.
param.Name = SysAllocString(L"MaskNum");
param.dispID = 0;
param.nValues = 1;

// 값을 초기화한다.
pValue->v.vt = VT_BSTR;
pValue->v.bstrVal = SysAllocString(L"120"); // 타원
pValue->rt = 0;
pValue->dwInterp = DEXTERF_JUMP;

pProp->AddProp(param, pValue);

// 할당할 수 있고 있던 리소스를 해방한다.
SysFreeString(param.Name);
VariantClear(&(pValue->v));
CoTaskMemFree(pValue);

// 트란지션의 프로퍼티를 설정한다.
pTransObj->SetPropertySetter(pProp);
pProp->Release();

트란지션의 방향

트란지션은 입력 A 로부터 입력 B 로 향해, 타임 t0 으로부터 t1 까지의 사이에 행해진다. 따라서, 트란지션의방향은, 다음의 2 개의 어느쪽이든을 의미한다.

  • 타임 라인 계층으로부터 입력에의 매핑.
  • 계속적인 진행.

전자는입력 방향이며, 후자는진행 방향이다. 이 양쪽 모두의 방향을 제어할 수 있다.

  • 입력 방향 : 디폴트에서는, 트란지션은 우선 순위의 낮은 계층의 합성으로부터, 트란지션이 포함되는 계층으로 향해 행해진다. 이 방향을 반대로 하려면 ,IAMTimelineTrans::SetSwapInputs 메소드를 호출한다.
  • 진행 방향 : 대부분의 트란지션은 표준의 Progress 프로퍼티를 지원 하고 있다. 이 프로퍼티는, 소정의 시점에서 출력에 반영되는 트란지션의 비율을 지정한다. 디폴트에서는,Progress 프로퍼티의 값은 트란지션의 시간폭에 대해서 0.0 에서 1.0 으로 변화한다. 이 진행을 반대로 하려면 ,Progress 프로퍼티가 1.0 에서 0.0 으로 변화하도록(듯이) 설정한다.

다음의 그림은, 입력 방향과 진행 방향의 차이를 나타내고 있다. 여기에서는, 표준의 SMPTE 와이프트란지션의 4 개의 바리에이션이 나타나고 있다.

트란지션은 트럭 1 에 있다. 디폴트에서는, 와이프는 왼쪽에서 오른쪽으로, 트럭 0 에서 1 으로 향해 행해진다. 입력을 바꾸면(자), 와이프는 트럭 1 에서 0 으로 향해 행해지지만, 진행 방향은 왼쪽에서 오른쪽인 채이다. 진행 방향을 반대로 하면, 트란지션은 금방 다른 곳으로 향해 행해진다. 제일왼쪽으로 나타나고 있도록(듯이), 이 양쪽 모두를 조합할 수가 있다.

DES 가 트란지션을 렌더링 하는 방법에 대해서는, 「타임 라인 모델」을 참조할것.


프로젝트의 렌더링

여기에서는, Microsoft® DirectShow® 편집 서비스 (DES)로 비디오 편집 프로젝트를 렌더링 하는 방법을 설명하고 있다. 이하의 주제가 포함된다.

  • 렌더링 엔진에 대해
  • 프로젝트의 프리뷰
  • 파일에의 프로젝트의 기입


렌더링 엔진에 대해

여기에서는, Microsoft DirectShow 편집 서비스 (DES)로 어떻게 비디오 편집 프로젝트가 렌더링 될까에 임해서 설명한다.

DES 에서는, 프로젝트는타임 라인으로서 나타내진다. 타임 라인은, 소스 클립의 재배치나 비디오 이펙트의 추가 등, 비디오 편집으로 가장 빈번하게 행해지는 태스크를 간략화하기 위해서 도움이 된다. 한편, DirectShow 스트림의 아키텍쳐에서는, 필터 그래프가 필요하다. 그 때문에, 프로젝트를 렌더링 하기 위해서는, 타임 라인을 필터 그래프로 변환하지 않으면 안 된다. 이 조작을 실시하는 컴퍼넌트가,렌더링 엔진으로 불린다. DirectShow 에서는, 다음의 2 개의 렌더링 엔진이 제공된다.

  • 기본렌더링 엔진 : 비압축 출력을 제공하는 필터 그래프를 구축한다.
  • 스마트 렌더링 엔진 : 압축 출력을 제공하는 필터 그래프를 구축한다.

스마트 렌더링 엔진은,스마트재압축을 사용해, 퍼포먼스를 향상시킨다. 스마트재압축에서는, 원의 파일 포맷이 최종적인 출력 포맷과 다른 경우에만, 원시 파일이 재압축된다. 포맷이 일치하는 경우는, 원시 파일이 재압축될 것은 없다. 스마트재압축은, 비디오 압축용인 만큼 지원 되어 오디오 압축용으로는 지원 되지 않는다.

프리뷰에는, 기본 렌더링 엔진을 사용한다. 스마트 렌더링 엔진에서도 프리뷰는 할 수 있지만, 압축된 스트림을 압축 해제해야 하기 때문에, 효율이 나쁘다. 파일의 기입에는, 스마트재압축이 필요한 경우에는 스마트 렌더링 엔진을 사용한다. 그 이외의 경우는, 기본 렌더링 엔진을 사용한다. 스마트재압축을 사용하면(자), 파일의 기입에 필요한 시간이 현격히 줄어든다.

중요 : 원시 파일에 ASF 파일이 포함되어 있어, 목적의 파일이 AVI 파일인 경우는, 스마트 렌더링 엔진을 사용하지 않는 것. 파일이 올바르게 재생하지 않을 가능성이 있다. 기본 렌더링 엔진을 사용하는지, 또는 ASF 파일의 기입을 검토한다.

필터 그래프의 구축

필터 그래프는, 2 단계에서 구축된다. 최초의 단계에서는, 렌더링 엔진은 "프론트엔드" 를 생성 한다. 이것은, 필터 그래프의 일부이다. 다음의 그림은, 일반적인 프론트엔드를 나타내고 있다.

필터 그래프의 프런트 엔드

서브 시스템에는, 다양한 특수 필터가 포함되어 있다. 이러한 필터는, 렌더링 엔진이 자동적으로 조립한다. 프론트엔드에는, 타임 라인의 각그룹 마다 1 개의 출력 핀이 포함되어 있다. 기본 렌더링 엔진을 사용하는 경우, 출력 핀은 비압축 데이터를 출력해, 스마트 렌더링 엔진을 사용하는 경우는 압축 데이터를 출력한다.

2 번째의 단계에서는, 출력 핀이 렌더링 필터에 접속된다. 프리뷰에서는, 렌더링 필터는 비디오 렌더러 및 오디오 렌더러가 된다. 파일의 기입에서는, 렌더링 필터는 멀티플렉서 (mux) 필터 및 파일 라이터 필터가 된다.

필터 그래프의 생성

참조

  • 프로젝트의 프리뷰
  • 파일에의 프로젝트의 기입


프로젝트의 프리뷰

프로젝트를 프리뷰 하려면 ,CoCreateInstance 함수를 호출해, 기본 렌더링 엔진의 인스턴스를 생성 한다. 클래스 식별자는,CLSID_RenderEngine 이다. 다음에, 렌더링 엔진의 IRenderEngine 인터페이스로, 다음의 메소드를 호출한다.

  • SetTimelineObject 사용하는 타임 라인을 지정한다.
  • ConnectFrontEnd 그래프의 프론트엔드를 구축한다.
  • RenderOutputPins 각 출력 핀을 비디오 렌더러 또는 오디오 렌더러에 접속해, 프리뷰 그래프를 완료한다.

다음의 샘플 코드는, 이러한 스텝을 나타내고 있다.

IRenderEngine *pRender = NULL;
hr = CoCreateInstance(CLSID_RenderEngine, NULL,
    CLSCTX_INPROC_SERVER, IID_IRenderEngine, (void**) &pRender);

hr = pRender->SetTimelineObject(pTL);
hr = pRender->ConnectFrontEnd( );
hr = pRender->RenderOutputPins( );

이것으로, 필터 그래프를 실행할 수 있게 된다. IRenderEngine::GetFilterGraph 메소드를 호출해, 그래프에의 포인터를 입수한다. 다음의 샘플 코드에 나타내도록(듯이),IMediaControl 인터페이스에 대해 그래프에 조회해,IMediaControl::Run 를 호출한다.

IGraphBuilder   *pGraph = NULL;
IMediaControl   *pControl = NULL;

hr = pRender->GetFilterGraph(&pGraph);
hr = pGraph->QueryInterface(IID_IMediaControl, (void **) &pControl);
hr = pControl->Run();

프로젝트 파일을 읽어들여 프리뷰 하는 완전한 예에 대해서는, 「프로젝트의 로드와 프리뷰」를 참조할것.


파일에의 프로젝트의 기입

여기에서는, 비디오 편집 프로젝트를 파일에 기입하는 방법에 대해 설명한다. 최초로, 기본 렌더링 엔진을 사용해 파일을 기입하는 방법에 대해 설명한다. 다음에, 스마트 렌더링 엔진을 사용한 스마트재압축에 대해 설명한다. 여기에는, 다음의 주제가 포함되어 있다.

  • 기본 렌더링 엔진의 사용
  • 스마트 렌더링 엔진의 사용

Microsoft® DirectShow® 편집 서비스에서의 프로젝트의 렌더링 개요에 대해서는, 「렌더링 엔진에 대하며」를 참조할것.

기본 렌더링 엔진의 사용

다음과 같이, 그래프의 프론트엔드를 최초로 구축한다.

  1. 렌더링 엔진을 생성 한다.
  2. 타임 라인을 지정한다.
  3. 그래프의 프론트엔드를 구축한다.

다음의 샘플 코드는, 그 스텝을 나타내고 있다.

IRenderEngine *pRender = NULL;
hr = CoCreateInstance(CLSID_RenderEngine, NULL, CLSCTX_INPROC,
    IID_IRenderEngine, (void**) &pRender);

hr = pRender->SetTimelineObject(pTL);
hr = pRender->ConnectFrontEnd( );

다음에, 필터 그래프에 멀티플렉서 및 파일 라이터 필터를 추가한다. 그 가장 간단한 방법은, 캡춰 그래프를 구축하기 위한 DirectShow 컴퍼넌트인캡춰 그래프 빌더를 쓰는 것이다. 캡춰 그래프 빌더는,ICaptureGraphBuilder2 인터페이스를 공개한다. 다음의 스텝을 실행한다.

  1. 캡춰 그래프 빌더의 인스턴스를 생성 한다.
  2. 그래프에의 포인터를 취득해, 그래프 빌더에 건네준다.
  3. 출력 파일의 이름과 미디어 타입을 지정한다. 이 스텝에 의해, 다음에 필요하게 되는 mux 필터에의 포인터도 취득된다.

다음의 샘플 코드는, 이 스텝을 나타내고 있다.

CoCreateInstance(CLSID_CaptureGraphBuilder2, NULL, CLSCTX_INPROC,
    IID_ICaptureGraphBuilder2, (void **) &pBuilder);

// 그래프의 프론트엔드에의 포인터를 취득한다.
IGraphBuilder *pGraph;
pRender->GetFilterGraph(&pGraph);
pBuilder->SetFiltergraph(pGraph);

// 파일의 기입 섹션을 생성 한다.
IBaseFilter *pMux;
pBuilder->SetOutputFileName(&MEDIASUBTYPE_Avi, L"Output.avi", &pMux, NULL);

마지막으로, mux 필터에 프론트엔드의 출력 핀을 접속한다.

  1. 그룹수를 취득한다.
  2. 각 핀 마다, 핀에의 포인터를 취득한다.
  3. 옵션으로, 압축 필터의 인스턴스를 생성 해, 스트림을 압축한다. 압력의 타입은, 그룹의 미디어 타입에 따라서 다르다. 시스템 디바이스 열거자를 사용해, 이용 가능한 압축 필터를 열거할 수 있다. 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것.
  4. 옵션으로, 키 frame rate등의 압축 파라미터를 설정한다. 이 스텝에 대해서는, 다음에 상세하게 설명한다.
  5. ICaptureGraphBuilder2::RenderStream 를 호출한다. 이 메소드는, 핀, 압축 필터 (있는 경우), 및 멀티플렉서에 포인터를 이동한다.

다음의 샘플 코드는, 출력 핀의 접속 방법을 나타내고 있다.

long NumGroups;
pTimeline->GetGroupCount(&NumGroups);

// 그룹을 루프 해, 출력 핀을 취득한다.
for (i = 0; i < NumGroups; i++)
{
    IPin *pPin;
    if (pRender->GetGroupOutputPin(i, &pPin) == S_OK)
    {
        IBaseFilter *pCompressor;
        // 압력 필터를 생성 한다 (나타나지 않는다).
        // 압축 파라미터를 설정한다 (나타나지 않는다).

        // 핀을 접속한다.
        pBuilder->RenderStream(NULL, NULL, pPin, pCompressor, pMux);
        pCompressor->Release();
        pPin->Release();
    }
}

압축 파라미터를 설정하려면 (전의 스텝 4) ,IAMVideoCompression 인터페이스를 사용한다. 이 인터페이스는, 압축 필터의 출력 핀에 공개된다. 압축 필터의 핀을 열거해,IAMVideoCompression 에 대해 각 출력 핀에 조회한다. 핀 열거의 상세한 것에 대하여는, 「핀의 열거」를 참조할것. 이 스텝에 대해 취득한 모든 인터페이스 포인터는, 반드시 해방한다.

필터 그래프를 구축한 후는, 필터 그래프 매니저로 IMediaControl::Run 메소드를 호출한다. 필터 그래프는, 실행되면(자) 파일에 데이터를 기입한다. 이벤트 통지를 사용해, 재생이 완료하는 것을 기다린다. 상세한 것에 대하여는, 「이벤트에의 응답」을 참조할것. 재생이 종료하면(자),IMediaControl::Stop 를 명시적으로 호출해, 필터 그래프를 정지해야 한다. 이와 같이 하지 않으면 파일은 올바르게 기입해지지 않다.

스마트 렌더링 엔진의 사용

스마트재압축의 이점을 얻기 위해서(때문에)는, 기본 렌더링 엔진 대신에 스마트 렌더링 엔진을 사용한다. 그래프의 구축 스텝은, 대체로 같다. 주된 차이는, 파일의 기입 섹션은 아니고, 그래프의 프론트엔드로 압축을 하는 것이다.

각 비디오 그룹에는, 그 그룹의 압축 포맷을 지정하는 프로퍼티가 있다. 압축 포맷은, 높이, 폭, 비트수, 및 frame rate에 대해, 그룹의 비압축 포맷에 완전하게 일치해야 한다. 스마트 렌더링 엔진은, 그래프 구축 시에 압축 포맷을 사용한다. 압축 포맷을 설정하기 전에, 반드시 IAMTimelineGroup::SetMediaType 를 호출해, 그 그룹에 비압축 포맷을 지정한다.

그룹의 압축 포맷을 설정하려면 ,IAMTimelineGroup::SetSmartRecompressFormat 메소드를 호출한다. 이 메소드는, 포인터를 SCompFmt0 구조체로 이동한다. 이 구조체에는 2 개의 멤버가 있다. 1 개(살)은 nFormatId 이며, 이 멤버는 제로가 아니면 안 된다. 이제(벌써) 1 개(살)은 MediaType 이며, 이것은 AM_MEDIA_TYPE 구조체이다. 포맷 정보를 사용해 AM_MEDIA_TYPE 구조체를 초기화한다.

주 : 최종적인 프로젝트가 원시 파일의 1 개와 같은 포맷을 가지도록(듯이) 하려면 , 미디어 detector를 사용해 원시 파일로부터 직접 AM_MEDIA_TYPE 구조체를 취득할 수 있다. 상세한 것에 대하여는, 「IMediaDet::get_StreamMediaType 」를 참조할것.

다음의 샘플 코드에 나타내도록(듯이),SCompFmt0 변수를 long 형의 포인터에 캐스트 한다.

SCompFmt0 *pFormat = new SCompFmt0;
memset(pFormat, 0, sizeof(SCompFmt0));
pFormat->nFormatId = 0;

// pFormat->MediaType 를 초기화한다 (나타나지 않는다).

pGroup->SetSmartRecompressFormat( (long*) pFormat );

스마트 렌더링 엔진은, 자동적으로 호환성이 있는 압축 필터를 검색한다. ISmartRenderEngine::SetGroupCompressor 를 호출해도, 그룹의 압축 필터를 지정할 수 있다.

그래프의 구축

그래프를 구축하려면 , 「기본 렌더링 엔진의 사용」으로 설명한 것과 같은 스텝을 사용한다. 그 차이는, 다음에 나타내는 것 뿐이다.

  • 기본 렌더링 엔진은 아니고, 스마트 렌더링 엔진을 사용한다. 클래스 식별자는 CLSID_SmartRenderEngine 이다.
  • 프론트엔드의 구축 후에는 압축 파라미터를 설정하지만, 출력 핀을 렌더링 하기전에실시한다. ISmartRenderEngine::GetGroupCompressor 메소드를 호출해, 그룹의 압축 필터에의 포인터를 취득한다. 다음에, 전에 설명한 것처럼 IAMVideoCompression 인터페이스에 대해 조회한다.
  • 출력 핀을 렌더링 하려면 , 압축 필터를 삽입할 필요는 없다. 스트림은, 이미 압축되고 있다.


에러의 로그

Microsoft® DirectShow® 편집 서비스 (DES)에서는, DES 프로젝트의 읽어들여, 구축, 또는 렌더링시에 발생하는 에러를, 로그에 기록하기 위한 편입 메카니즘이 제공된다. 여기에서는, XML 프로젝트 파일을 읽어들여 렌더링을 시도하는 샘플 콘솔 프로그램에 대해 설명한다. 에러가 일어났을 경우, 이 어플리케이션은 에러 메세지를 콘솔 윈도우에 표시한다. 여기서 소개하는 샘플 코드는, 「프로젝트의 로드와 프리뷰」에 나타난 예에 근거해 구축되고 있다.

주 : 유저 어플리케이션에서는, 에러 로그를 이행 할 필요는 없다. DES 는, 명시적으로 요구하지 않으면 에러를 로그에 기록하지 않는다.

여기에서는, 유저가 COM 클라이언트 프로그래밍 및 DES 타임 라인 모델에 대해 이해하고 있는 것을 상정하고 있다. 또, 유저는 COM 오브젝트 프로그래밍의 기본 사항을 이해하고 있을 필요가 있다. DES 에 있어서의 타임 라인의 상세한 것에 대하여는, 「타임 라인 모델」을 참조할것.

여기에는 이하의 섹션이 포함된다.

  • 에러 로그의 개요
  • 에러 로그 클래스의 생성
  • IAMErrorLog 의 이행
  • 에러 로그의 설정
  • 샘플 코드

에러 로그의 개요

에러 처리에 관해서 최대의 유연성을 어플리케이션에게 주기 위해서(때문에), DES 는 콜백 메카니즘을 사용하고 있다. 유저 어플리케이션에서는, 에러 로그를 취하기 위한 메소드를 이행 한다. 실행시에 에러가 발생했을 경우, DES 는 유저에 의해 제공된 메소드를 호출한다. 이 메소드는, 에러의 상세를 나타내는 파라미터를 취한다. 메소드가 이 정보를 어떻게 처리할까는 프로그래머가 맡길 수 있다. 다만, 프로그램의 실행을 방해할 가능성이 있으므로, 가능한 한 빨리 복귀할 필요가 있다.

에러를 로그에 기록하는 콜백 메소드는, COM 인터페이스 IAMErrorLog 에 포함되어 있다. 유저 어플리케이션은, 이 인터페이스를 이행 해야 한다. 모든 COM 인터페이스와 같게,IAMErrorLog 는 IUnknown 인터페이스를 계승하므로, 유저 어플리케이션은, 이 인터페이스도 이행 해야 한다.

이러한 COM 인터페이스의 이행에는, 몇개의 방법을 선택할 수 있다. IUnknown 메소드의 표준의 이행을 제공하는, Active Template Library (ATL)를 사용할 수 있다. DirectShow 는 C++ base class CUnknown 도 제공하고 있어, 이것에 의해 COM 인터페이스의 이행이 용이하게 된다. CUnknown 의 사용법에 대해서는, 「IUnknown 의 이행 방법」을 참조할것.

후의 샘플 코드에서는, 코드내에 포함되는 C++ 클래스를 정의하고 있다. 이 클래스는,IUnknown 와 IAMErrorLog 의 양쪽 모두를 이행 한다. 다만,CoCreateInstance 를 지원 하고 있지 않기 때문에, 진정한 COM 오브젝트는 생성되지 않는다. 그러나, 이 방법은, 샘플 코드의 목적으로 해 타당한 것이다.

에러 로그 클래스의 생성

최초로, 에러 로그 기록을 이행 하는 클래스를 선언한다. 이 클래스는,IAMErrorLog 인터페이스를 계승한다. 이것에는, 3 개의 IUnknown 메소드와IAMErrorLog 의 1 개의 메소드의 선언이 포함된다. 이 클래스의 선언을 다음에 나타낸다.

class CErrReporter : public IAMErrorLog
{
protected:
    long    m_lRef; // Reference count.

public:
    CErrReporter() { m_lRef = 0; }

    // IUnknown
    STDMETHOD(QueryInterface(REFIID, void**));
    STDMETHOD_(ULONG, AddRef());
    STDMETHOD_(ULONG, Release());

    // IAMErrorLog
    STDMETHOD(LogError(LONG, BSTR, LONG, HRESULT, VARIANT*));
};

이 클래스의 유일한 멤버 변수는, 오브젝트의 참조 카운트를 보관 유지하는 _lRef 이다.

다음에,IUnknown 의 메소드를 정의한다. 상세한 것에 대하여는, 후의 샘플 코드를 참조할것. 이것으로, COM 체제를 사용하는 것으로 IAMErrorLog 인터페이스를 이행 할 수가 있다. 이하에서는, 그방법을 설명하고 있다.

IAMErrorLog 의 이행

IAMErrorLog 인터페이스에는, 단일의 메소드 LogError 가 있다. 이 메소드의 파라미터에는, 발생한 에러에 관한 정보가 포함된다.

STDMETHODIMP LogError(
    LONG Severity,                   // 예약이 끝난 상태. 사용하지 않는 것.
    BSTR ErrorString,                // 상세.
    LONG ErrorCode,                  // 에러 코드.
    HRESULT hresult,                 // 에러를 발생시킨 HRESULT.
    VARIANT *pExtraInfo);            // 에러에 관한 추가 정보.

에러 코드와 에러 캐릭터 라인은, DirectShow 편집 서비스로 정의되고 있다. 에러의 일람에 대해서는, 「렌더링 에러」를 참조할것.

파라미터 pExtraInfo 에는, 에러에 관한 추가 정보를 보관 유지하는 VARIANT 형에의 포인터가 들어간다. 이 VARIANT 형의 데이터형과 내용은, 발생한 개개의 에러에 따라서 다르다.

예를 들어, 부정한 파일명에 의해 에러가 발생했을 경우, VARIANT 는 부정한 파일명의 캐릭터 라인이 된다. 에러에는 추가 정보가 없는 것이 있으므로,pExtraInfo 가 NULL 인 일도 있다. 다음의 코드는, 이 VARIANT 의 vt 멤버를 테스트하는 방법을 나타내고 있다. 이 멤버는, 데이터형을 지정해, 거기에 응해 메세지의 서식을 설정한다.

if( pExtraInfo )    // 만약 있으면, 추가 정보를 리포트한다.
{
    printf("\tExtra info: ");
    if( pExtraInfo->vt == VT_BSTR )      // 추가 정보는 BSTR 이다.
    {
        char szExtra[256];
        WideCharToMultiByte(CP_ACP, 0, pExtraInfo->bstrVal, -1, szExtra, 256, 0, 0);
        printf("%s\n", szExtra);
    }
    else if( pExtraInfo->vt == VT_I4 )   // 추가 정보는 정수이다.
        printf("%d\n", pExtraInfo->lVal);

    else if( pExtraInfo->vt == VT_R8 )   // 추가 정보는 부동 소수점이다.
        printf("%f\n", pExtraInfo->dblVal);
}

주 : pExtraInfo 가 가리키는 VARIANT 를 해방해서는 안 된다. 또, VARIANT 는 메소드가 복귀한 후는 무효가 되므로, 다음에 참조해서는 안 된다.

에러 로그의 설정

에러 로그 클래스를 이행 하면(자), 그 클래스의 새로운 인스턴스를 생성 한다. 다음에, 타임 라인상에서 IAMSetErrorLog::put_ErrorLog 메소드를 호출하는 것으로, 그 인스턴스를 가리키는 포인터를 DES 에게 준다. 타임 라인에 IAMSetErrorLog 인터페이스에 대해 조회한다. 모든 에러가 로그에 기록되도록(듯이) 하려면 , 타임 라인의 읽어들여, 보존, 및 렌더링을 실시하기 전에, 이 메소드를 호출할 필요가 있다.

IAMSetErrorLog  *pSetLog = NULL;
IAMErrorLog     *pLog = new CErrReporter();

pTL->QueryInterface(IID_IAMSetErrorLog, (void **) &pSetLog);
pSetLog->put_ErrorLog(pLog);
pSetLog->Release();

에러 로그에 의해, 어플리케이션으로 메소드를 호출하면나무에 받는 반환값에는 영향은 없다. 에러 로그는, 보통의 에러 처리 방법을 보완하지만, 옮겨놓는 것은 아니다. 견뢰한 어플리케이션을 생성 하기 위해서는, 항상 HRESULT 값을 체크해야 한다.

샘플 코드

다음의 샘플 코드는, 여기서 설명한 에러 로그 클래스를 사용해, XML 프로젝트 파일을 읽어들여 프리뷰 하는, 완전한 콘솔 프로그램이다. 프로젝트 파일의 이름은, 어플리케이션에 하드 코딩 된다.

코드를 간결하게 하기 위한(해), 콘솔 프로그램은 ATL 스마트 포인터를 사용한다. 이것에 의해,QueryInterface 와 Release 를 호출하지 않아도 끝난다. 필요한 경우는, 「프로젝트의 로드와 프리뷰」로 샘플 어플리케이션을 변경할 수 있다. 전에 나타낸 코드를 추가하는 것만으로 좋다.

#include <atlbase.h>
#include <dshow.h>
#include <qedit.h>
#include <stdio.h>

// 에러 로그 클래스
class CErrReporter : public IAMErrorLog
{
protected:
    long    m_lRef; // Reference count.

public:
    CErrReporter() { m_lRef = 0; }

    // IUnknown
    STDMETHOD(QueryInterface(REFIID, void**));
    STDMETHOD_(ULONG, AddRef());
    STDMETHOD_(ULONG, Release());

    // IAMErrorLog
    STDMETHOD(LogError(LONG, BSTR, LONG, HRESULT, VARIANT*));
};

STDMETHODIMP CErrReporter::QueryInterface(REFIID riid, void **ppv)
{
    if (ppv == NULL)
        return E_POINTER;
    *ppv = NULL;

    if (riid == IID_IUnknown)
        *ppv = (IUnknown*) this;
    else if (riid == IID_IAMErrorLog)
        *ppv = (IAMErrorLog*) this;

    if (*ppv)
    {
        AddRef();
        return S_OK;
    }
    return E_NOINTERFACE;
}

STDMETHODIMP_(ULONG) CErrReporter::AddRef()
{
    return InterlockedIncrement(&m_lRef);
}

STDMETHODIMP_(ULONG) CErrReporter::Release()
{
    if (InterlockedDecrement(&m_lRef) == 0)
    {
        delete this;
        return 0;
    }
    return m_lRef;
}

STDMETHODIMP CErrReporter::LogError(
        LONG Severity,
        BSTR ErrorString,
        LONG ErrorCode,
        HRESULT hresult,
        VARIANT *pExtraInfo)
{
    char szError[256];
    WideCharToMultiByte(CP_ACP, 0, ErrorString, -1, szError, 256, 0, 0);
    printf("Error %d: %s\n", ErrorCode, szError);

    if( pExtraInfo )    // 만약 있으면, 추가 정보를 리포트한다.
    {
        printf("\tExtra info: ");
        if( pExtraInfo->vt == VT_BSTR )      // 추가 정보는 BSTR 이다.
        {
            char szExtra[256];
            WideCharToMultiByte(CP_ACP, 0, pExtraInfo->bstrVal, -1, szExtra, 256, 0, 0);
            printf("%s\n", szExtra);
        }
        else if( pExtraInfo->vt == VT_I4 )   // 추가 정보는 정수이다.
            printf("%d\n", pExtraInfo->lVal);

        else if( pExtraInfo->vt == VT_R8 )   // 추가 정보는 부동 소수점이다.
            printf("%f\n", pExtraInfo->dblVal);
    }
    return hresult;
};

void __cdecl main(void)
{
    CoInitialize(NULL);
    {
    HRESULT hr;
    CComPtr< IAMTimeline >   pTL;
    CComPtr< IRenderEngine > pRenderEngine;
    CComPtr< IXml2Dex >      pXML;
    CComPtr< IGraphBuilder > pGraph;

    hr = CoCreateInstance(CLSID_AMTimeline, NULL, CLSCTX_INPROC_SERVER,
                IID_IAMTimeline, (void**) &pTL);

    hr = CoCreateInstance(CLSID_Xml2Dex, NULL, CLSCTX_INPROC_SERVER,
                IID_IXml2Dex, (void**) &pXML);

    hr = CoCreateInstance(CLSID_RenderEngine, NULL, CLSCTX_INPROC_SERVER,
                IID_IRenderEngine, (void**) &pRenderEngine);

    // 에러 로그를 설정한다.
    CComQIPtr<IAMSetErrorLog, &IID_IAMSetErrorLog> pSetLog(pTL);
    if (pSetLog)
    {
        IAMErrorLog *pLog = new CErrReporter;
        pSetLog->put_ErrorLog(pLog);
    }

    // 프로젝트를 읽어들여 프리뷰 한다.
    hr = pXML->ReadXMLFile(pTL, L"C:\\Example.xtl");
    if (SUCCEEDED(hr))
    {
        hr = pRenderEngine->SetTimelineObject(pTL);
        hr = pRenderEngine->ConnectFrontEnd( );
        hr = pRenderEngine->RenderOutputPins( );
        hr = pRenderEngine->GetFilterGraph(&pGraph);

        CComQIPtr<IMediaControl, &IID_IMediaControl> pControl(pGraph);
        CComQIPtr<IMediaEvent, &IID_IMediaEvent> pEvent(pGraph);
        pControl->Run();

        long evCode;
        hr = pEvent->WaitForCompletion(INFINITE, &evCode);
        pControl->Stop();
    }
    // 클린 업 한다.
    pRenderEngine->ScrapIt();
    }
    CoUninitialize();
}


비디오 편집 프로젝트의 관리

여기에서는, Microsoft® DirectShow® 편집 서비스에서의 프로젝트 관리에 도움이 되는 힌트를 나타낸다.

타임 라인에의 변경

  • 필터 그래프를 구축한 후에 타임 라인을 변경하는 경우는, 한번 더 IRenderEngine::ConnectFrontEnd 를 호출해, 프론트엔드를 재구축 한다. 보통, 그래프외의 부분에는 영향은 없다. 렌더링 엔진이 프론트엔드를 재구축 하기 전에는, 그래프 전체를 삭제해야 하는 것이 있다. 예를 들어, 그룹의 추가나 삭제의 경우 등이다. ConnectFrontEnd 메소드는, S_WARN_OUTPUTRESET 를 돌려주어, 그래프를 삭제한 것을 통지한다. 이 경우, 어플리케이션은 그래프의 렌더링 부분을 재구축 해야 한다.
  • 타임 라인으로부터 모든 오브젝트를 완전하게 삭제하려면 ,IAMTimeline::ClearAllGroups 메소드를 호출한다.

클린 업

  • 렌더링 엔진의 사용을 종료하면(자),IRenderEngine::ScrapIt 메소드를 호출한다. 다른 COM 오브젝트와 같이, 사용을 종료하면(자) 각 인터페이스 포인터를 반드시 해방한다.
  • 렌더링 엔진은, 타임 라인상에 참조 카운트를 보관 유지하지 않는다. 사용을 종료하기 전에 타임 라인을 해방해 안되어, 반드시 최초로 렌더링 엔진상에서 ScrapIt 를 호출한다.
  • 타임 라인에의 모든 참조를 해방할 때는, 비록 타임 라인상에 참조 카운트를 보관 유지하고 있었다고 해도, 타임 라인의 어느 오브젝트도 사용해서는 안 된다.

복수의 인스턴스

  • 타임 라인간에 타임 라인 오브젝트를 이동해서는 안 된다. 타임 라인의 모든 오브젝트는, 그 타임 라인에 의해 생성 될 필요가 있다. 타임 라인은, 타임 라인이 생성 하는 오브젝트에 관한 정보를 내장형 캐쉬 로 유지하고 있다. 타임 라인 오브젝트를 이동 하면, 이 캐쉬를 파괴할 가능성이 있다.
  • 복수의 타임 라인을 가지는 렌더링 엔진의 같은 인스턴스는, 결코 사용해서는 안 된다. 렌더링 엔진은, 타임 라인에 관한 정보를 캐쉬 로 유지하고 있다. 복수의 타임 라인이 있으면(자), 캐쉬가 파괴되어 예기치 않은 결과가 발생한다. 2 개(살)의 액티브한 타임 라인이 필요한 경우는, 타임 라인 마다 렌더링 엔진의 다른 인스턴스를 생성 한다.
  • 타임 라인은, 복수의 렌더링 엔진을 사용할 수 있지만, 동시에 사용할 수 없다. 낡은 렌더링 엔진을 삭제하고 나서, 새로운 렌더링 엔진을 사용한다. 예를 들어, 프리뷰를 위해서(때문에) 기본 렌더링 엔진을 사용하고 나서, 파일의 기입을 위해서(때문에) 스마트 렌더링 엔진으로 전환하는 경우이다.

영속성

  • 프로젝트를 XML 파일에 보존할 때에, 필터 그래프는 영속적은 아니다. 그 때문에, 스마트재압축, 압축 포맷, 및 압축 파라미터에 관련한 정보가 없어진다. 프로젝트를 읽어들인 후에 이러한 파라미터를 복원할지 어떨지는, 어플리케이션 독자적으로 결정한다.


알파 블렌딩

여기에서는, Microsoft® DirectShow® 편집 서비스 (DES)로 알파 블렌딩을 실행하는 방법에 대해 설명한다.

알파는, 픽셀 또는 이미지의 투명도를 나타낸다. 32 비트비압축 RGB 비디오에서는, 알파 채널 (A) 및 3 개의 칼라 컴퍼넌트 (RGB)로부터 완성되는, 4 개의 컴퍼넌트에 의해 각 픽셀이 정의된다. 알파값이 제로의 픽셀은 완전하게 투명하고, 알파값이 255 의 픽셀은 불투명하다. 픽셀은, 이러한 값의 사이의 다양한 투명도를 가진다.

DirectShow 에서는, 32 비트 RGB 비디오용으로다음의 2 개의 미디어 타입이 정의된다.

  • MEDIASUBTYPE_ARGB32 : 이 비디오는, 유효한 알파 채널을 가지는 32 비트 RGB 이다.
  • MEDIASUBTYPE_RGB32 : 픽셀은 32 비트이지만, 알파 채널은 반드시 유효하지 않다.

DES 로 알파 블렌딩을 사용하려면 , 최초로 그룹의 비압축 미디어 타입을 MEDIASUBTYPE_ARGB32 로 설정한다. C++ 에서는,IAMTimelineGroup::SetMediaType 메소드를 호출한다. XTL 포맷에서는,GROUP 요소의 BITDEPTH 속성을 32 로 설정해도, 알파 블렌딩을 사용할 수 있다. 상세한 것에 대하여는, 「XML 레퍼런스」를 참조할것.

다음에, 알파 채널이 포함된 비디오 데이터가 필요하다. 그 때문에(위해)는, 다음과 같은 몇개의 옵션이 있다.

  • 이미 알파 데이터와 32 비트 RGB 비디오를 가지고 있는 AVI 파일을 사용할 수 있다. 현재, 알파는 MPEG 또는 Microsoft® Windows Media™ Format (WMF)의 원시 파일에서는 지원되어 있지 않다.
  • DES 는, 알파 데이터를 가지는 32 비트 비트 맵 (. bmp) 및 Targa (. tga) 파일을 지원 하고 있다.
  • 알파를 가지는 32 비트 RGB 를 생성 하는, 커스텀 원시 파일을 쓸 수가 있다. 출력 미디어 타입은, MEDIASUBTYPE_ARGB32 가 아니면 안 된다. 타임 라인 소스 오브젝트로, 필터를 서브 오브젝트로서 사용한다. 상세한 것에 대하여는, 「서브 오브젝트」를 참조할것.

비디오 소스에 알파가 없는 경우는, 알파 데이터를 생성 하는 이펙트를 사용할 수 있다. 아르파셋타 이펙트를 사용하면(자), 이미지 전체의 알파 채널을 정수값으로 설정할 수 있다. 시간과 함께 알파가 변화하도록(듯이) 하려면 ,IPropertySetter 인터페이스를 사용한다. 그룹의 비압축 미디어 타입이 MEDIASUBTYPE_ARGB32 인 한, 원의 소스는 32 비트일 필요는 없다. 또, 알파 데이터를 생성 하는, 유저 독자적인 Microsoft® DirectX® 변환 이펙트를 생성 할 수도 있다.

주 : 알파 데이터가 이미 비디오 소스에 포함되어 있는 경우는, 아르파셋타에페크트를 사용해, 지정하는 비율로 각 픽셀의 알파값을 변경할 수 있다. 상세한 것에 대하여는, 「아르파셋타」를 참조할것.

마지막으로, 알파 블렌딩을 실행하는 이펙트 또는 트란지션에 비디오를 건네준다. 콘포지타 트란지션 및 SMPTE 와이프 트란지션은, 어느쪽이나 알파 블렌딩을 실행한다. 키 트란지션은, 알파값에 의해 키잉 할 수 있다. 서드 파티의 DirectX 변환 오브젝트에도, 알파 블렌딩을 지원 하는 것이 있다.

다음의 샘플 XTL 프로젝트에서는, 알파 블렌딩을 실행하고 있다.

<TIMELINE>
<GROUP TYPE="video" BITDEPTH="32" WIDTH="320" HEIGHT="240">

<TRACK>
  <CLIP START="0" STOP="6" SRC="c:\Example.avi" />
</TRACK>

<TRACK>
  <CLIP START="0" STOP="6" SRC="c:\Example2.avi">

    <! -- 아르파셋타에페크트 -->
    <EFFECT CLSID="{506D89AE-909A-44f7-9444-ABD575896E35}" START="0" STOP="6">
      <PARAM NAME="alpha" VALUE="255">
        <LINEAR TIME="6" VALUE="0" />
      </PARAM>
    </EFFECT>

  </CLIP>

  <! -- 알파 키잉을 사용한 키트란지션 -->
  <TRANSITION CLSID="{C5B19592-145E-11d3-9F04-006008039E37}" START="0" STOP="6">
    <PARAM NAME="KeyType" VALUE="3" />
  </TRANSITION>
</TRACK>


컷 리스트의 타임 라인에의 변환

여기에서는, 기존의 캇트리스트아프리케이션을 Microsoft® DirectShow® 편집 서비스 (DES)로 변환하는 방법에 대해 설명한다.

컷 리스트는, DirectShow 의 이전의 버젼의 기능이며, 비선형 편집을 위해서(때문에) 제한부 지원을 제공했다. Microsoft® DirectX® 8.0 에서는, 컷 리스트는 지원되어 있지 않다. DES 에서의 기능으로부터 기능의 변환은, 간단하게 이행 할 수 있을 필요가 있다. 이것에는, 적어도 다음과 같은 이점이 있다.

  • 이종 소스의 지원
  • 압축 소스의 지원
  • frame rate의 자동변역
  • 비디오를 프레임 전체에 스트렛치 하거나 레터박스를 생성 하는 지원
  • 슬로 모션 및 고속 모션의 오디오와 비디오의 지원
  • 오디오 갭 (무음)의 것보다 좋은 지원

컷 리스트로부터 이행 하면, 프로젝트의 영속성, 복수의 트럭, 이펙트, 트란지션, 포스터 프레임의 합성등의 기능을 추가할 수 있다.

표준적인 캇트리스트아프리케이션은, 다음과 같은 스텝을 실행한다.

  1. 비디오 스트림 및 오디오 스트림용으로 다른 컷 리스트 (IStandardCutList)를 생성 한다.
  2. 각 원시 파일용으로, 비디오 파일 클립, 오디오 파일 클립, 또는 그 양쪽 모두 (IFileClip)를 생성 한다.
  3. 각 파일 클립으로부터, 1 개(살) 또는 복수의 컷 (IAMCutListElement)을 생성 해, 컷 리스트에 추가한다.
  4. 컷 리스트 그래프 빌더 (ICutListGraphBuilder)를 생성 한다.
  5. 각 컷 리스트를 컷 리스트 그래프 빌더에 추가한다.
  6. 옵션으로, 출력 파일명을 설정한다.
  7. 그래프를 렌더링, 재생한다.

다음에 나타내는 것은, DES 에서의 같은 스텝이다.

  1. 타임 라인 (IAMTimeline )을 생성 한다.
  2. 최종적인 프로덕션에서, 각 비디오 스트림 및 오디오 스트림용으로 1 개의 그룹 (IAMTimelineGroup )을 생성 한다.
  3. 1 개(살) 또는 복수의 트럭 (IAMTimelineTrack )을 각 그룹에 추가한다.
  4. 소스 오브젝트 (IAMTimelineSrc )를 생성 해, 트럭에 추가한다.
  5. 렌더링 엔진 (IRenderEngine )을 생성 한다.
  6. 렌더링 엔진에 타임 라인을 추가한다.
  7. 그래프를 렌더링, 재생한다.

다음에 나타내는 것은, 그 주된 차이이다.

파일 클립 : DES 에서는, 파일 클립에 상당하는 오브젝트는 없다. 소스 오브젝트는, 대체로 컷에 상당한다. 컷에서는, 복수의 소스 오브젝트가 같은 원시 파일을 참조할 수 있다.

미디어 타입 : 컷 리스트에서는, 오디오와 비디오용으로 2 개(살)의 명확한 파일 클립 오브젝트가 있어, 각각 독자적인 클래스 식별자가 있다. DES 에서는, 그룹의 미디어 타입에 의해 소스 오브젝트의 미디어 타입이 결정된다.

파일 출력 : DES 에는,ICutListGraphBuilder::SetOutputFileName 메소드에 직접 상당하는 것이 없다. DES 에서는 파일 출력이 얼마인가 복잡하게 되어 있지만, 포맷과 압축 타입에 대해서는, 현격히 제어가 향상하고 있다. 상세한 것에 대하여는, 「파일에의 프로젝트의 기입」을 참조할것.

프로젝트의 변경 : 컷 리스트에서는 새로운 컷을 추가할 수 있지만, 컷의 변경이나 삭제는 할 수 없다. DES 에서는, 소스 오브젝트의 추가, 삭제, 재배치, 또는 변경을 할 수 있다. 상세한 것에 대하여는, 「비디오 편집 프로젝트의 관리」를 참조할것.


DirectShow 편집 서비스 레퍼런스

이 섹션에는, Microsoft® DirectShow® 편집 서비스의 레퍼런스 정보가 모두 포함되어 있다. 레퍼런스 정보는, 이하와 같이 분류되고 있다.

  • 인터페이스
  • 구조체
  • 열거형
  • 정수
  • 트란지션 및 이펙트
  • DirectShow 편집 서비스의 컴퍼넌트
  • XML 레퍼런스
  • 렌더링 에러


인터페이스

이 섹션에는, Microsoft® DirectShow® 편집 서비스의 모든 COM 인터페이스 및 그 메소드의 레퍼런스 정보가 포함되어 있다.

  • IAMErrorLog
  • IAMSetErrorLog
  • IAMTimeline
  • IAMTimelineComp
  • IAMTimelineEffect
  • IAMTimelineEffectable
  • IAMTimelineGroup
  • IAMTimelineObj
  • IAMTimelineSplittable
  • IAMTimelineSrc
  • IAMTimelineTrack
  • IAMTimelineTrans
  • IAMTimelineTransable
  • IAMTimelineVirtualTrack
  • IFindCompressorCB
  • IMediaDet
  • IMediaLocator
  • IPropertySetter
  • IRenderEngine
  • ISmartRenderEngine
  • IXml2Dex


IAMErrorLog 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)에 있어서의 에러 로그를 위한 콜백 메소드를 제공한다.

DES 는, 이 인터페이스를 이행 하고 있지 않다. 에러 로그를 취하기 위해서(때문에)는, 어플리케이션으로 이 인터페이스를 이행 해, 타임 라인으로 IAMSetErrorLog::put_ErrorLog 를 호출한다. 프로젝트를 렌더링 할 경우에 에러가 발생했을 경우, DES 는 어플리케이션에 의해 이행 된 IAMErrorLog::LogError 메소드를 호출한다.

DES 가 에러를 로그에 기록하는 것은,IRenderEngine 인터페이스를 사용해 프로젝트를 렌더링 하면나무뿐이다. 예를 들어, 프로젝트를 DirectShow 필터 그래프 (. grf 포맷)으로서 보존해, 그 그래프 파일을 재생하는 경우에는, 에러 로그는 행해지지 않는다.

이 인터페이스의 사용법의 상세한 것에 대하여는, 「에러의 로그」를 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMErrorLog 메소드 | 설명
LogError | 에러를 로그에 기록한다.

IAMErrorLog::LogError

IAMErrorLog 인터페이스

에러를 로그에 기록한다. 어플리케이션으로 이 메소드를 호출할 필요는 없다. 이 메소드는, 렌더링 에러에의 응답에 대해 내부적으로 불려 간다.

구문

HRESULT LogError(
    LONG Severity,
    BSTR ErrorString,
    LONG ErrorCode,
    HRESULT hresult,
    VARIANT *pExtraInfo
);

파라미터

Severity
예약이 끝난 상태. 사용해서는 안 된다.
ErrorString
에러의 텍스트를 포함한 캐릭터 라인값.
ErrorCode
에러 코드.
hresult
에러를 일으킨 메소드 호출로 돌려주어진 HRESULT 값.
pExtraInfo
[in] 에러에 관한 추가 정보가 포함되는 VARIANT 형에의 포인터.

반환값

HRESULT 값을 돌려준다. hresult 파라미터의 값을 돌려준다.

주의

이 메소드 중(안)에서,pExtraInfo 가 가리키는 VARIANT 를 해방해서는 안 된다. 또, VARIANT 는 메소드가 복귀한 후는 무효가 되므로, 다음에 참조해서는 안 된다.

이 메소드의 이행에서는, 가능한 한 빨리 복귀하도록(듯이) 한다. 이 메소드 중(안)에서, 프로그램의 실행을 금지하는 것 같은 함수 호출을 해서는 안 된다. 예를 들어, 메세지의 송신, 이벤트의 금지 등, 실행의 방해가 되는 Microsoft® Win32® 함수를 호출해서는 안 된다. 그러한 일을 실시하면, 컴퓨터가 응답을 정지하거나"헹 " 하는 일이 있다.

DES 로 정의되고 있는 에러의 일람, 및 pExtraInfo 가 가리키는 VARIANT 의 의미와 데이터형에 대해서는, 「렌더링 에러」를 참조할것.


IAMSetErrorLog 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의 에러 로그를 취득한다. 타임 라인 오브젝트는, 이 인터페이스를 이행 하고 있다. 어플리케이션에서는, 이 인터페이스를 사용해, 실행시에 렌더링 에러를 로그에 기록할 수 있다. 어플리케이션으로 IAMErrorLog 인터페이스를 이행 해, 타임 라인의 IAMSetErrorLog::put_ErrorLog 메소드를 호출한다.

이 인터페이스의 사용법의 상세한 것에 대하여는, 「에러의 로그」를 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMSetErrorLog 메소드 | 설명
get_ErrorLog | 이 오브젝트로 설정되어 있는 에러 로그를 취득한다.
put_ErrorLog | 오브젝트의 에러 로그를 지정한다.

IAMSetErrorLog::get_ErrorLog

IAMSetErrorLog 인터페이스

이 오브젝트로 설정되어 있는 에러 로그를 취득한다.

구문

HRESULT get_ErrorLog(
    IAMErrorLog **pVal
);

파라미터

pVal
[out, retval] 에러 로그의 IAMErrorLog 인터페이스를 받는 포인터의 주소. 타임 라인에 에러 로그가 없는 경우, 값은 NULL 로 설정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

pVal 에 돌려주어진 값이 NULL 이외의 경우,IAMErrorLog 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMSetErrorLog::put_ErrorLog

IAMSetErrorLog 인터페이스

오브젝트의 에러 로그를 지정한다.

구문

HRESULT put_ErrorLog(
    IAMErrorLog *newVal
);

파라미터

newVal
[in] 에러 로그의 IAMErrorLog 인터페이스를 가리키는 포인터.

반환값

S_OK 를 돌려준다.


IAMTimeline 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의 중심적 오브젝트인타임 라인을 조작하는 메소드를 제공한다. 타임 라인은, 비디오 클립, 오디오 클립, 이펙트, 및 클립간의 트란지션 등, 시간순서의 요소의 콜렉션이다. 렌더링 엔진은, 타임 라인을 사용해 필터 그래프를 생성 한다. 어플리케이션은, 필터 그래프로부터 렌더링 된 출력을 생성할 수 있다.

IAMTimeline 는, 3 개의 기본적인 서비스를 실시한다. 이하를 실시한다.

  • 타임 라인내에 오브젝트를 생성 한다.
  • 생성 된 오브젝트의 컨테이너로서 기능한다.
  • 타임 라인의 일반적 파라미터의 설정과 취득을 실시한다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimeline 메소드 | 설명
CreateEmptyNode | 새로운 타임 라인 오브젝트를 생성 한다.
AddGroup | 타임 라인에 그룹을 추가한다.
RemGroupFromList | 지원되어 있지 않다.
GetGroup | 지정된 그룹을 취득한다.
GetGroupCount | 타임 라인에 포함되는 그룹의 개수를 취득한다.
ClearAllGroups | 타임 라인내의 모든 그룹, 및 그것들에 포함되는 모든 오브젝트를 삭제한다.
GetInsertMode | 지원되어 있지 않다.
SetInsertMode | 이행되어 있지 않다.
EnableTransitions | 타임 라인내의 모든 트란지션을 유효 또는 무효로 한다.
TransitionsEnabled | 트란지션이 유효한가 어떤가를 조사한다.
EnableEffects | 타임 라인내의 모든 이펙트를 유효 또는 무효로 한다.
EffectsEnabled | 이펙트가 유효한가 어떤가를 조사한다.
SetInterestRange | 이행되어 있지 않다.
GetDuration | 타임 라인의 시간폭을 취득한다.
GetDuration2 | GetDuration 와 같은 기능이지만,double 형의 파라미터를 취한다.
SetDefaultFPS | 디폴트의 출력 frame rate (매초의 프레임수)를 설정한다.
GetDefaultFPS | 디폴트의 출력 frame rate (매초의 프레임수)를 취득한다.
IsDirty | 지원되어 있지 않다.
GetDirtyRange | 지원되어 있지 않다.
GetCountOfType | 지정된 그룹과 그 모든 아이에게 포함되는, 지정된 타입의 오브젝트의 개수를 취득한다.
ValidateSourceNames | 타임 라인내의 소스명을 검증한다.
SetDefaultTransition | 디폴트의 트란지션을 설정한다.
GetDefaultTransition | 디폴트의 트란지션을 취득한다.
SetDefaultEffect | 디폴트의 이펙트를 설정한다.
GetDefaultEffect | 디폴트의 이펙트를 취득한다.
SetDefaultTransitionB | SetDefaultTransition 와 같은 기능이지만, BSTR 값을 파라미터에 있다.
GetDefaultTransitionB | GetDefaultTransition 와 같은 기능이지만, BSTR 값을 파라미터에 있다.
SetDefaultEffectB | SetDefaultEffect 와 같은 기능이지만, BSTR 값을 파라미터에 있다.
GetDefaultEffectB | GetDefaultEffect 와 같은 기능이지만, BSTR 값을 파라미터에 있다.

IAMTimeline::AddGroup

IAMTimeline 인터페이스

타임 라인에그룹을 추가한다.

구문

HRESULT AddGroup(
    IAMTimelineObj *pGroup
);

파라미터

pGroup
그룹의 IAMTimelineObj 인터페이스에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 그룹의 최대수를 넘었다.
E_NOINTERFACE | 이 오브젝트는 그룹은 아니다.

주의

현재, 타임 라인이 지원 하는 그룹의 최대수는 32 이다.

IAMTimeline::ClearAllGroups

IAMTimeline 인터페이스

타임 라인내의 모든 그룹, 및 그것들에 포함되는 모든 오브젝트를 삭제한다.

구문

HRESULT ClearAllGroups( void );

반환값

S_OK 를 돌려준다.

IAMTimeline::CreateEmptyNode

IAMTimeline 인터페이스

새로운 타임 라인 오브젝트를 생성 한다.

이 메소드는 중요한 초기화 루틴을 실행하므로, 타임 라인의 생성에는 이 메소드를 사용해,CoCreateInstance 함수는 사용하지 않는다. 이 메소드에 의해 생성 되는 오브젝트는, 적어도 IAMTimelineObj 인터페이스를 지원 해, 그것과 함께 그 타입의 오브젝트에 특유의 다른 인터페이스를 지원 한다.

구문

HRESULT CreateEmptyNode(
    IAMTimelineObj **ppObj,
    TIMELINE_MAJOR_TYPE Type
);

파라미터

ppObj
[out] 새로운 오브젝트의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
Type
TIMELINE_MAJOR_TYPE 열거형의 멤버. 생성 하는 오브젝트의 타입을 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 오브젝트 타입이 유효하지 않다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

다른 타임 라인 인스턴스에 새로운 오브젝트를 추가하지 않는 것. 타임 라인의 모든 오브젝트는, 그 타임 라인에 의해 생성 되지 않으면 안 된다.

메소드가 성공했을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimeline::EffectsEnabled

IAMTimeline 인터페이스

이펙트가 유효한가 어떤가를 조사한다. 이펙트가 무효의 경우, 이펙트는 타임 라인내에 존재한 채로이지만, 렌더링은 되지 않는다.

구문

HRESULT EffectsEnabled(
    BOOL *pfEnabled
);

파라미터

pfEnabled
이펙트가 유효한가 어떤가를 나타내는 불리언 값을 받는 변수에의 포인터. TRUE 의 경우, 이펙트는 유효하다. FALSE 의 경우, 이펙트는 무효이다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimeline::EnableEffects

IAMTimeline 인터페이스

타임 라인내의 모든 이펙트를 유효 또는 무효로 한다. 이펙트가 무효의 경우, 이펙트는 타임 라인내에 존재한 채로이지만, 렌더링은 되지 않는다.

구문

HRESULT EnableEffects(
    BOOL fEnabled
);

파라미터

fEnabled
이펙트를 유효 또는 무효의 어느 쪽으로 설정하는지를 나타내는 불리언 값. TRUE 의 경우, 이펙트가 유효하게 된다. FALSE 의 경우, 이펙트는 무효가 된다.

반환값

S_OK 를 돌려준다.

IAMTimeline::EnableTransitions

IAMTimeline 인터페이스

타임 라인내의 모든 트란지션을 유효 또는 무효로 한다. 트란지션이 무효의 경우, 렌더링 엔진은 트란지션을 컷 (직접 바꾸고)으로서 취급한다. 즉, 렌더링 된 출력으로는,트럭으로부터 다음의 트럭에 즉석에서 바뀐다. 디폴트의 컷 포인트는, 트란지션의 시간폭의 중간점이다. 컷 포인트는, 그 트란지션의 IAMTimelineTrans::SetCutPoint 메소드를 호출하는 것으로 변경할 수 있다. 무효가 된 트란지션은, 타임 라인으로부터는 삭제되지 않는다.

구문

HRESULT EnableTransitions(
    BOOL fEnabled
);

파라미터

fEnabled
트란지션을 유효 또는 무효의 어느 쪽으로 설정하는지를 나타내는 불리언 값. TRUE 의 경우, 트란지션이 유효하게 된다. FALSE 의 경우, 트란지션은 무효가 된다.

반환값

S_OK 를 돌려준다.

IAMTimeline::GetCountOfType

IAMTimeline 인터페이스

지정된 그룹과 그 모든 아이에게 포함되는, 지정된 타입의 오브젝트의 개수를 취득한다.

구문

HRESULT GetCountOfType(
    long Group,
    long *pVal,
    long *pValWithComps,
    TIMELINE_MAJOR_TYPE MajorType
);

파라미터

Group
오브젝트의 개수를 취득하는 그룹의 인덱스 번호.
pVal
그룹 및 그 모든가상 트럭에 포함되는 (재귀적으로 내부에 포함되는 오브젝트도 포함한다), 지정된 타입의 오브젝트의 개수를 받는 변수에의 포인터.
pValWithComps
pVal 에 돌려주어진 개수와 이것 자체도 포함해 검색된 합성의 개수를 더한 수를 받는 변수에의 포인터.
MajorType
TIMELINE_MAJOR_TYPE 열거형의 멤버. 개수를 세는 오브젝트의 타입을 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 그룹 번호.
E_POINTER | NULL 포인터 인수.

주의

이 메소드를 호출하는 것은, 지정의 그룹의 IAMTimelineComp::GetCountOfType 를 호출하는 것으로 동등하다. 상세한 것에 대하여는, 그 메소드의 「주의」를 참조할것.

보통, 어플리케이션에서는 이 메소드를 호출하지 않는다. 이것은, 렌더링 엔진에 의해 내부적으로 불려 간다.

IAMTimeline::GetDefaultEffect

IAMTimeline 인터페이스

디폴트의 이펙트를 취득한다. 렌더링 엔진이 이펙트를 렌더링 할 수 없는 경우, 디폴트의 이펙트가 대용된다.

구문

HRESULT GetDefaultEffect(
    GUID *pGuid
);

파라미터

pGuid
디폴트 이펙트의 글로벌 유니크 식별자 (GUID)를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimeline::GetDefaultEffectB

IAMTimeline 인터페이스

디폴트의 이펙트를 취득한다. 이 메소드는 GetDefaultEffect 와 같은 기능이지만, GUID 는 아니고 BSTR 값을 받는다.

구문

HRESULT GetDefaultEffectB(
    BSTR *pGuid
);

파라미터

pGuid
[out, retval] 디폴트 이펙트의 GUID 를 나타내는 BSTR 값을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_OUTOFMEMORY 또는 에러의 발생을 나타내는 그 외의 HRESULT 값을 돌려준다.

주의

이 메소드는, 캐릭터 라인에 필요한 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

IAMTimeline::GetDefaultFPS

IAMTimeline 인터페이스

디폴트의 출력 frame rate (매초의 프레임수, FPS)를 취득한다. 그룹은, 이 값을 디폴트의 frame rate로서 사용한다. 그룹의 frame rate를 설정하려면 , 그 그룹의 IAMTimelineGroup::SetOutputFPS 메소드를 호출한다.

구문

HRESULT GetDefaultFPS(
    double *pFPS
);

파라미터

pFPS
디폴트의 frame rate (매초의 프레임수)를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimeline::GetDefaultTransition

IAMTimeline 인터페이스

디폴트의 트란지션을 취득한다. 렌더링 엔진이 트란지션을 렌더링 할 수 없는 경우, 디폴트의 트란지션이 대용된다.

구문

HRESULT GetDefaultTransition(
    GUID *pGuid
);

파라미터

pGuid
디폴트의 트란지션의 GUID 를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimeline::GetDefaultTransitionB

IAMTimeline 인터페이스

디폴트의 트란지션을 취득한다. 이 메소드는 GetDefaultTransition 와 같은 기능이지만, GUID 는 아니고 BSTR 값을 받는다.

구문

HRESULT GetDefaultTransitionB(
    BSTR *pGuid
);

파라미터

pGuid
[out, retval] 디폴트의 트란지션의 GUID 를 나타내는 BSTR 값을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_OUTOFMEMORY 또는 에러의 발생을 나타내는 그 외의 HRESULT 값을 돌려준다.

주의

이 메소드는, 캐릭터 라인에 필요한 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

IAMTimeline::GetDirtyRange

IAMTimeline 인터페이스

지원되어 있지 않다.

구문

HRESULT GetDirtyRange(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

IAMTimeline::GetDuration

IAMTimeline 인터페이스

타임 라인의 시간폭을 취득한다.

구문

HRESULT GetDuration(
    REFERENCE_TIME *pDuration
);

파라미터

pDuration
타임 라인의 시간폭 (100 나노초단위)을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimeline::GetDuration2

IAMTimeline 인터페이스

타임 라인의 시간폭을 취득한다. 이 메소드는 GetDuration 와 같은 기능이지만,double 형의 파라미터를 취한다.

구문

HRESULT GetDuration2(
    double *pDuration
);

파라미터

pDuration
타임 라인의 시간폭 (소수의 초수)을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimeline::GetGroup

IAMTimeline 인터페이스

지정된 그룹을 취득한다.

구문

HRESULT GetGroup(
    IAMTimelineObj **ppGroup,
    long WhichGroup
);

파라미터

ppGroup
[out] 그룹의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
WhichGroup
취득하는 그룹의 인덱스. 이 인덱스는, 그룹이 타임 라인에 추가된 순서에 근거한다. 타임 라인에 최초로 추가된 그룹의 인덱스는 0 이 된다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

메소드가 성공했을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimeline::GetGroupCount

IAMTimeline 인터페이스

타임 라인에 포함되는 그룹의 개수를 취득한다.

구문

HRESULT GetGroupCount(
    long *pCount
);

파라미터

pCount
타임 라인내의 그룹의 개수를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimeline::GetInsertMode

IAMTimeline 인터페이스

지원되어 있지 않다.

구문

HRESULT GetInsertMode(
    long *pMode
);

IAMTimeline::IsDirty

IAMTimeline 인터페이스

지원되어 있지 않다.

구문

HRESULT IsDirty(
    BOOL *pDirty
);

IAMTimeline::RemGroupFromList

IAMTimeline 인터페이스

지원되어 있지 않다.

구문

HRESULT RemGroupFromList(
    IAMTimelineObj *pGroup
);

IAMTimeline::SetDefaultEffect

IAMTimeline 인터페이스

디폴트의 이펙트를 설정한다. 렌더링 엔진이 이펙트를 렌더링 할 수 없는 경우, 디폴트의 이펙트가 대용된다.

구문

HRESULT SetDefaultEffect(
    GUID *pGuid
);

파라미터

pGuid
디폴트 이펙트의 GUID 를 가지는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

디폴트 이펙트를 설정하고 있지 않는 경우, 또는 디폴트로 지정한 이펙트가 에러를 일으켰을 경우, DES 자체의 디폴트 이펙트가 사용된다.

IAMTimeline::SetDefaultEffectB

IAMTimeline 인터페이스

디폴트의 이펙트를 설정한다. 이 메소드는 SetDefaultEffect 와 같은 기능이지만, GUID 에의 포인터는 아니고 BSTR 값을 파라미터에 있다.

구문

HRESULT SetDefaultEffectB(
    BSTR pGuid
);

파라미터

pGuid
디폴트 이펙트의 GUID 를 나타내는 BSTR 값.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_OUTOFMEMORY 또는 에러의 발생을 나타내는 그 외의 HRESULT 값을 돌려준다.

IAMTimeline::SetDefaultFPS

IAMTimeline 인터페이스

디폴트의 출력 frame rate (매초의 프레임수)를 설정한다. 그룹은, 이 값을 디폴트의 frame rate로서 사용한다. 그룹의 frame rate를 설정하려면 , 그 그룹의 IAMTimelineGroup::SetOutputFPS 메소드를 호출한다.

구문

HRESULT SetDefaultFPS(
    double FPS
);

파라미터

FPS
디폴트의 frame rate (매초의 프레임수).

반환값

S_OK 를 돌려준다.

IAMTimeline::SetDefaultTransition

IAMTimeline 인터페이스

디폴트의 트란지션을 설정한다. 렌더링 엔진이 트란지션을 렌더링 할 수 없는 경우, 디폴트의 트란지션이 대용된다.

구문

HRESULT SetDefaultTransition(
    GUID *pGuid
);

파라미터

pGuid
디폴트의 트란지션의 GUID 를 가지는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

디폴트의 트란지션을 설정하고 있지 않는 경우, 또는 디폴트로 지정한 트란지션이 에러를 일으켰을 경우, DES 자체의 디폴트의 트란지션이 사용된다.

IAMTimeline::SetDefaultTransitionB

IAMTimeline 인터페이스

디폴트의 트란지션을 설정한다. 이 메소드는 SetDefaultTransition 와 같은 기능이지만, GUID 에의 포인터는 아니고 BSTR 값을 파라미터에 있다.

구문

HRESULT SetDefaultTransitionB(
    BSTR pGuid
);

파라미터

pGuid
디폴트의 트란지션의 GUID 를 나타내는 BSTR 값.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_OUTOFMEMORY 또는 에러의 발생을 나타내는 그 외의 HRESULT 값을 돌려준다.

IAMTimeline::SetInsertMode

IAMTimeline 인터페이스

이행되어 있지 않다.

구문

HRESULT SetInsertMode(
    long Mode
);

IAMTimeline::SetInterestRange

IAMTimeline 인터페이스

이행되어 있지 않다.

구문

HRESULT SetInterestRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

IAMTimeline::TransitionsEnabled

IAMTimeline 인터페이스

트란지션이 유효한가 어떤가를 조사한다.

구문

HRESULT TransitionsEnabled(
    BOOL *pfEnabled
);

파라미터

pfEnabled
불리언 값을 받는 변수에의 포인터. TRUE 의 경우, 트란지션은 유효하다. 그렇지 않은 경우, 트란지션은 무효이다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

참조

EnableTransitions

IAMTimeline::ValidateSourceNames

IAMTimeline 인터페이스

미디어 locator를 사용해, 타임 라인내의 소스명을 검증한다. 옵션으로, 이 메소드는 발견된 파일로 소스 오브젝트를 갱신한다.

구문

HRESULT ValidateSourceNames(
    long ValidateFlags,
    IMediaLocator *pOverride,
    long NotifyEventHandle
);

파라미터

ValidateFlags
미디어 locator의 동작을 지정하는플래그의 비트마다의 편성. SFN_VALIDATEF_REPLACE 플래그와 SFN_VALIDATEF_CHECK 플래그는 반드시 존재하고 있지 않으면 안 된다. 그렇지 않은 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.
pOverride
디폴트 대신에 사용하는 미디어 locator의 IMediaLocator 인터페이스에의 옵션의 포인터. 디폴트의 미디어 locator를 사용하려면 , 이 파라미터의 값을 NULL 로 설정한다. 상세한 것에 대하여는, 「주의」를 참조할것.
NotifyEventHandle
이벤트의 핸들. 이 메소드는, 검증이 완료한 다음에 이 이벤트에 시그널 송신한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_INVALIDARG 또는 다른 에러 코드를 돌려준다.

주의

pOverride 파라미터를 사용 하면,IMediaLocator 인터페이스의 독자적인 커스텀 이행을 사용할 수 있다. 예를 들어, 디폴트의 미디어 locator는, 발견된 (또는 발견되지 않았다) 파일에 대해 어플리케이션에 통지를 실시하지 않는다. 이러한 제한을 회피하기 위해서, 커스텀 미디어 locator를 이행 해, 디폴트 버젼의 래퍼로 할 수가 있다. 커스텀 버젼에서는, 디폴트 버젼에 FindMediaFile 호출을 직접 건네주어, 그 반환값을 조사한다.


IAMTimelineComp 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)로,합성 위에의가상 트럭을 삽입 또는 취득한다.

합성은, 합성된 단일의트럭으로서 기능하는, 계층의 콜렉션이다. 예를 들어, 2 개의 트럭과 그러한 사이의 트란지션으로부터 되는 합성은, 그 트란지션을 가지는 합성되어 있지 않은 단일의 트럭으로서 기능한다. 합성에는, 같은 타입 (오디오 또는 비디오)의 미디어만을 넣도록(듯이) 할 필요가 있지만, 이 제한은 강제당하지 않는다. 가상 트럭은, 합성내에 배치할 수 있는, 트럭 및 다른 합성도 포함한 임의의 오브젝트이다.

타임 라인의 최상정도의 노드는그룹이다. 그룹은,IAMTimelineComp 인터페이스 및 IAMTimelineGroup 인터페이스를 이행 한다.

상세한 것에 대하여는, 「타임 라인 모델」 및 「그룹, 합성, 및 트럭」을 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineComp 메소드 | 설명
VTrackInsBefore | 합성으로 지정의 우선 순위로 가상 트럭을 삽입한다.
VTrackSwapPriorities | 2 개의 트럭의 우선 순위 레벨을 바꿔 넣는다.
VTrackGetCount | 합성에 포함되는 가상 트럭의 개수를 취득한다.
GetVTrack | 지정된 우선 순위의 가상 트럭을 취득한다.
GetCountOfType | 이 합성 및 그 모든 가상 트럭에 포함되는 (재귀적으로 내부에 포함되는 오브젝트도 포함한다), 지정된 타입의 오브젝트의 개수를 취득한다.
GetRecursiveLayerOfType | 이 합성에 포함되는 가상 트럭을 깊이의 깊은 순서에 순서 붙여 그 순서로 n 번째의 가상 트럭을 취득한다.
GetRecursiveLayerOfTypeI | 지원되어 있지 않다.
GetNextVTrack | 지정된 가상 트럭의 다음의 가상 트럭을 취득한다.

IAMTimelineComp::GetCountOfType

IAMTimelineComp 인터페이스

이 합성 및 그 모든 가상 트럭에 포함되는 (재귀적으로 내부에 포함되는 오브젝트도 포함한다), 지정된 타입의 오브젝트의 개수를 취득한다.

구문

HRESULT GetCountOfType(
    long *pVal,
    long *pValWithComps,
    TIMELINE_MAJOR_TYPE MajorType
);

파라미터

pVal
이 합성 및 그 모든 가상 트럭에 포함되는 (재귀적으로 내부에 포함되는 오브젝트도 포함한다), 지정된 타입의 오브젝트의 개수를 받는 변수에의 포인터.
pValWithComps
pVal 에 돌려주어진 개수와 이것 자체도 포함해 검색된 합성의 개수를 더한 수를 받는 변수에의 포인터.
MajorType
TIMELINE_MAJOR_TYPE 열거형의 멤버. 개수를 세는 오브젝트의 타입을 지정한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

보통, 어플리케이션에서는 이 메소드를 호출하지 않는다. 이것은, 렌더링 엔진에 의해 불려 간다.

합성의 개수를 조사했을 때,pVal 에 돌려주어지는 값은 제로,pValWithComps 에 돌려주어지는 값이 합성의 개수이다. *pValWithComps 의 값에는, 메소드를 호출한 합성도 포함된다. 예를 들어, 하늘의 합성으로 이 메소드를 호출했을 경우,*pValWithComps 는 1 에 동일하다.

그룹은 합성안에 배치할 수 없기 때문에, 이 메소드로 그룹의 수를 조사할 수 없다 (돌려주어지는 수는 항상 제로가 된다). 그룹의 수를 조사하려면 ,IAMTimeline::GetGroupCount 메소드를 호출한다.

IAMTimelineComp::GetNextVTrack

IAMTimelineComp 인터페이스

지정된 가상 트럭의 다음의 가상 트럭을 취득한다.

구문

HRESULT GetNextVTrack(
    IAMTimelineObj *pVirtualTrack,
    IAMTimelineObj **ppNextVirtualTrack
);

파라미터

pVirtualTrack
전의 가상 트럭에의 포인터. 합성내의 최초의 가상 트럭을 취득하는 경우는 NULL.
ppNextVirtualTrack
[out] 우선 순위의 순서로, 다음의 가상 트럭의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.

반환값

이 메소드는, 가상 트럭을 취득했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

메소드가 성공했을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineComp::GetRecursiveLayerOfType

IAMTimelineComp 인터페이스

이 합성에 포함되는 가상 트럭을 깊이의 깊은 순서에 순서 붙여 그 순서로 n 번째의 가상 트럭을 취득한다.

구문

HRESULT GetRecursiveLayerOfType(
    IAMTimelineObj **ppVirtualTrack,
    long WhichLayer,
    TIMELINE_MAJOR_TYPE Type
);

파라미터

ppVirtualTrack
[out] 가상 트럭의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
WhichLayer
취득하는 가상 트럭을 지정하는, 제로로부터 시작되는 인덱스의 값.
Type
TIMELINE_MAJOR_TYPE 열거형의 멤버. 검색에 트럭을 포함할지 어떨지를 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 지정된 타입의 오브젝트는 없다.
E_POINTER | NULL 포인터 인수.

주의

보통, 어플리케이션으로 이 메소드를 호출할 필요는 없다.

Type 파라미터가 TIMELINE_MAJOR_TYPE_TRACK 의 경우, 깊이의 순서부에 트럭도 포함된다. 그 이외의 경우는, 합성과 그룹만이 포함된다. 그 오브젝트 자체도 순서부에 포함된다.

예를 들어, 합성 A 로부터 시작되는 다음과 같은 배치에서는, 순서는 B, C, F, D, E, A 가 된다.

메소드가 성공했을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineComp::GetRecursiveLayerOfTypeI

IAMTimelineComp 인터페이스

지원되어 있지 않다. 대신에,GetRecursiveLayerOfType 메소드를 호출한다.

구문

HRESULT GetRecursiveLayerOfTypeI(
    IAMTimelineObj **ppVirtualTrack,
    long *pWhichLayer,
    TIMELINE_MAJOR_TYPE Type
);

IAMTimelineComp::GetVTrack

IAMTimelineComp 인터페이스

지정된 우선 순위의 가상 트럭을 취득한다.

구문

HRESULT GetVTrack(
    IAMTimelineObj **ppVirtualTrack,
    long Which
);

파라미터

ppVirtualTrack
[out] 가상 트럭의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
Which
취득하는 가상 트럭의 우선 순위.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 지정된 우선 순위의 가상 트럭은 없다.
E_POINTER | NULL 포인터 인수.

주의

메소드가 성공했을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineComp::VTrackGetCount

IAMTimelineComp 인터페이스

합성에 포함되는 가상 트럭의 개수를 취득한다.

구문

HRESULT VTrackGetCount(
    long *pVal
);

파라미터

pVal
가상 트럭의 개수를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineComp::VTrackInsBefore

IAMTimelineComp 인터페이스

합성으로 지정의 우선 순위로 가상 트럭을 삽입한다.

구문

HRESULT VTrackInsBefore(
    IAMTimelineObj *pVirtualTrack,
    long Priority
);

파라미터

pVirtualTrack
가상 트럭의 IAMTimelineObj 인터페이스에의 포인터.
Priority
가상 트럭을 삽입하는 우선 순위. 우선 순위 리스트의 마지막에 가상 트럭을 삽입하는 경우는 -1.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_NOINTERFACE | 오브젝트는 가상 트럭은 아니다.

주의

우선 순위 레벨은 제로로부터 시작된다. 타임 라인에, 지정된 우선 순위 레벨의 가상 트럭이 이미 존재하는 경우, 우선 순위 리스트의 그 위치 이하의 모든 것이 1 레벨씩 뒤로 돌릴 수 있어 삽입되는 트럭의 장소가 확보된다. 현재의 트럭의 개수보다 큰 값을 우선 순위로 지정했을 경우, 이 메소드는 실패한다.

IAMTimelineComp::VTrackSwapPriorities

IAMTimelineComp 인터페이스

2 개의 트럭의 우선 순위 레벨을 바꿔 넣는다.

이 메소드는, 지정된 2 개의 우선 순위 레벨을 가지는 각각의 가상 트럭의 우선 순위를 바꿔 넣는다. 이 메소드가 복귀했을 때, 최초로 지정된 우선 순위에 있던 트럭의 우선 순위는, 2 번째로 지정된 우선 순위 레벨이 되어, 2 번째로 지정된 우선 순위에 있던 트럭의 우선 순위는, 최초로 지정된 우선 순위 레벨이 되어 있다.

구문

HRESULT VTrackSwapPriorities(
    long VirtualTrackA,
    long VirtualTrackB
);

파라미터

VirtualTrackA
가상 트럭을 바꿔 넣는 최초의 우선 순위 레벨.
VirtualTrackB
가상 트럭을 바꿔 넣는 2 번째의 우선 순위 레벨.

반환값

성공했을 경우는 S_OK, 그 이외의 경우는 E_INVALIDARG 를 돌려준다.


IAMTimelineEffect 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)로 이펙트를 조작하기 위한 메소드를 제공한다. 이펙트 오브젝트는 이 인터페이스를 이행 한다.

이펙트 오브젝트는, DES 가 지원 하는 모든 타입의 단일 입력 이펙트의 래퍼 오브젝트이다. 사용하는 이펙트를 지정하려면 , 그 이펙트의 IAMTimelineObj::SetSubObjectGUID 메소드를 호출한다. 이펙트의 프로퍼티를 설정하려면 ,IPropertySetter 인터페이스를 사용한다. 상세한 것에 대하여는, 「이펙트와 트란지션의 조작」을 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineEffect 메소드 | 설명
EffectGetPriority | 이펙트의 우선 순위 레벨을 취득한다.

IAMTimelineEffect::EffectGetPriority

IAMTimelineEffect 인터페이스

이펙트의 우선 순위 레벨을 취득한다. 지정된 오브젝트에 대해서, 렌더링 엔진은 우선 순위에 따라, 우선 순위 제로로부터 순서에 이펙트를 적용한다.

구문

HRESULT EffectGetPriority(
    long *pVal
);

파라미터

pVal
우선 순위 레벨을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.


IAMTimelineEffectable 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의 타임 라인 오브젝트에 이펙트를 추가하기 위한 메소드, 및 오브젝트의 이펙트를 조작하는 메소드를 제공한다. 자신에게 적용할 수 있는 이펙트를 가지는 오브젝트는, 모두 이 인터페이스를 이행 하고 있다. 이것에는, 소스,트럭, 및합성이 포함된다.

이 인터페이스를 이행 하고 있는 오브젝트는, 이펙트를 몇개에서도 가질 수가 있다. 각 오브젝트 마다, 렌더링 엔진은 우선 순위에 따라, 우선 순위 0 으로부터 순서에 이펙트를 적용한다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineEffectable 메소드 | 설명
EffectInsBefore | 지정된 우선 순위의 오브젝트에 이펙트를 삽입한다.
EffectSwapPriorities | 2 개의 이펙트의 우선 순위 레벨을 바꿔 넣는다.
EffectGetCount | 이 오브젝트에 적용되는 이펙트의 수를 취득한다.
GetEffect | 지정된 우선 순위 레벨의 이펙트를 취득한다.

IAMTimelineEffectable::EffectGetCount

IAMTimelineEffectable 인터페이스

이 오브젝트에 적용되는 이펙트의 수를 취득한다.

구문

HRESULT EffectGetCount(
    long *pCount
);

파라미터

pCount
이펙트의 수를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineEffectable::EffectInsBefore

IAMTimelineEffectable 인터페이스

지정된 우선 순위의 오브젝트에 이펙트를 삽입한다.

구문

HRESULT EffectInsBefore(
    IAMTimelineObj *pFX,
    long Priority
);

파라미터

pFX
이펙트의 IAMTimelineObj 인터페이스에의 포인터.
Priority
이펙트를 삽입하는 우선 순위 레벨. 이펙트를 우선 순위 리스트의 마지막에 삽입하는 경우는, 값으로서 -1 를 사용한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 오브젝트가 이펙트가 아니었던 경우는, E_NOTIMPL 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 다른 HRESULT 값을 돌려준다.

주의

이펙트의 시작 타임과 종료 타임은, 필요에 따라서, 오브젝트의 시간 범위의 경계내에 넣을 수 있다.

지정된 우선 순위 레벨의 이펙트가 이미 존재하는 경우, 우선 순위 리스트의 그 위치 이하의 이펙트가 모두 1 레벨씩 뒤로 돌릴 수 있어 새로운 이펙트의 장소가 확보된다.

IAMTimelineEffectable::EffectSwapPriorities

IAMTimelineEffectable 인터페이스

2 개의 이펙트의 우선 순위 레벨을 바꿔 넣는다.

이 메소드는, 지정된 2 개의 우선 순위 레벨을 가지는 각각의 이펙트의 우선 순위를 바꿔 넣는다. 이 메소드가 복귀했을 때, 최초로 지정된 우선 순위에 있던 이펙트의 우선 순위는, 2 번째로 지정된 우선 순위 레벨이 되어, 2 번째로 지정된 우선 순위에 있던 이펙트의 우선 순위는, 최초로 지정된 우선 순위 레벨이 되어 있다.

구문

HRESULT EffectSwapPriorities(
    long PriorityA,
    long PriorityB
);

파라미터

PriorityA
이펙트를 바꿔 넣는 최초의 우선 순위 레벨.
PriorityB
이펙트를 바꿔 넣는 2 번째의 우선 순위 레벨.

반환값

성공했을 경우는 S_OK, 그 이외의 경우는 E_INVALIDARG 를 돌려준다.

IAMTimelineEffectable::GetEffect

IAMTimelineEffectable 인터페이스

지정된 우선 순위 레벨의 이펙트를 취득한다.

구문

HRESULT GetEffect(
    IAMTimelineObj **ppFx,
    long Which
);

파라미터

ppFX
[out] 이펙트의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
Which
취득하는 이펙트의 우선 순위 레벨.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_FALSE | 지정된 우선 순위 레벨의 이펙트는 없다.
S_OK | 성공.
E_POINTER | NULL 포인터 인수.

주의

메소드가 S_OK 를 돌려주었을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.


IAMTimelineGroup 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)로그룹의 프로퍼티를 설정 및 취득한다.

그룹은 1 개 이상의트럭과 경우에 의해 1 개 이상의합성을 가져, 트럭은 동일 타입 (비디오 또는 오디오)의 소스 클립을 가진다. 그룹은,타임 라인의 최상정도의 합성이며, 또 IAMTimelineComp 인터페이스를 공개한다. 타임 라인은, 복수의 그룹을 가질 수가 있다.

각 그룹에는 이하의 속성이 있다.

  • 관련지을 수 있었던 미디어 타입.
  • 그룹이 렌더링 되는 frame rate (매초의 프레임수, FPS). 모든 편집이 시작되는 시간은, 그룹의 FPS 설정에 의해 정의되는 가장 가까운 프레임 경계에 말 수 있다.
  • 우선 순위 레벨. 같은 미디어 타입의 복수의 스트림을 가지는 파일 (예를 들어, 2 개의 비디오 스트림을 가지는 AVI 파일)을 기입할 때에 사용된다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineGroup 메소드 | 설명
SetTimeline | 지원되어 있지 않다.
GetTimeline | 이 그룹이 소속하는 타임 라인을 취득한다.
GetPriority | 그룹의 우선 순위를 취득한다.
GetMediaType | 그룹의 비압축 미디어 타입을 취득한다.
SetMediaType | 그룹의 비압축 미디어 타입을 설정한다.
SetOutputFPS | 이 그룹의 비압축 출력 frame rate를 설정한다.
GetOutputFPS | 이 그룹의 출력 frame rate를 취득한다.
SetGroupName | 어플리케이션이 정의하는 그룹의 이름을 설정한다.
GetGroupName | 어플리케이션이 정의하는 그룹의 이름을 취득한다.
SetPreviewMode | 그룹의 프리뷰 모드를 설정한다.
GetPreviewMode | 그룹의 프리뷰 모드를 취득한다.
SetMediaTypeForVB | Automation 클라이언트용의 그룹 미디어 타입을 지정한다.
GetOutputBuffering | 프리뷰시에 선행해 렌더링 되는 프레임수를 취득한다.
SetOutputBuffering | 프리뷰시에 선행해 렌더링 되는 프레임수를 지정한다.
SetSmartRecompressFormat | 스마트재압축으로 사용되는 압축 포맷을 지정한다.
GetSmartRecompressFormat | 스마트재압축의 현재의 압축 포맷을 취득한다.
IsSmartRecompressFormatSet | 그룹에 스마트 압축이 설정되어 있는지 어떤지를 조사한다.
IsRecompressFormatDirty | 지원되어 있지 않다.
ClearRecompressFormatDirty | 지원되어 있지 않다.
SetRecompFormatFromSource | 원시 파일의 압축 포맷을 사용해 비디오재압축 포맷을 설정한다.

IAMTimelineGroup::ClearRecompressFormatDirty

IAMTimelineGroup 인터페이스

지원되어 있지 않다.

구문

HRESULT ClearRecompressFormatDirty(void);

IAMTimelineGroup::GetGroupName

IAMTimelineGroup Interface

어플리케이션이 정의하는 그룹의 이름을 취득한다.

구문

HRESULT GetGroupName(
    BSTR *pGroupName
);

파라미터

pGroupName
[out, retval] 그룹의 이름을 받는 BSTR 형의 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 또는 에러의 발생을 나타내는 그 외의 HRESULT 값을 돌려준다.

주의

이 메소드는, 캐릭터 라인에 필요한 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

IAMTimelineGroup::GetMediaType

IAMTimelineGroup 인터페이스

그룹의 비압축 미디어 타입을 취득한다.

구문

HRESULT GetMediaType(
    AM_MEDIA_TYPE *pmt
);

파라미터

pmt
[out] 이 미디어 타입이 설정되어 있는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineGroup::GetOutputBuffering

IAMTimelineGroup 인터페이스

프리뷰시에 선행해 렌더링 되는 프레임수를 취득한다.

구문

HRESULT GetOutputBuffering(
    int *pnBuffer
);

파라미터

pnBuffer
[out] 버퍼링 되는 프레임의 수를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineGroup::GetOutputFPS

IAMTimelineGroup 인터페이스

이 그룹의 출력 frame rate를 취득한다.

구문

HRESULT GetOutputFPS(
    double *pFPS
);

파라미터

pFPS
출력 frame rate (매초의 프레임수)를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineGroup::GetPreviewMode

IAMTimelineGroup 인터페이스

그룹의 프리뷰 모드를 취득한다.

구문

HRESULT GetPreviewMode(
    BOOL *pfPreview
);

파라미터

pfPreview
프리뷰 모드를 나타내는 불리언 값을 받는 변수에의 포인터. TRUE 의 경우, 그룹은 프리뷰 모드이다. FALSE 의 경우, 그룹은 오쏘링 모드이다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

프리뷰 모드에서는, 비디오와 오디오의 동기를 유지하기 위해서, 시간이 걸리는 이펙트 또는 트란지션에서는 프레임 빠짐이 생긴다. 그 때문에, 비디오의 움직임 그림의 기법 여기 없어지는 일이 있다. 오쏘링 모드에서는, 모든 프레임이 렌더링 된다. 오쏘링 모드는 파일에의 기입에 적절하고 있다. 오쏘링 모드로 화면에 프리뷰를 실시하면, 비디오와 오디오의 동기 금액 빗나가는 경우가 있다.

IAMTimelineGroup::GetPriority

IAMTimelineGroup 인터페이스

그룹의 우선 순위를 취득한다.

구문

HRESULT GetPriority(
    long *pPriority
);

파라미터

pPriority
그룹의 우선 순위를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineGroup::GetSmartRecompressFormat

IAMTimelineGroup 인터페이스

스마트재압축의 현재의 압축 포맷을 취득한다.

구문

HRESULT GetSmartRecompressFormat(
   long **ppFormat
);

파라미터

ppFormat
SCompFmt0 구조체에의 포인터를 받는 변수의 주소. long 에의 포인터에 캐스트 된다. 이 메소드가 실패 하면, 값은 NULL 로 설정된다.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.
S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

어플리케이션으로 (SetSmartRecompressFormat 를 호출하는 것에 의해) 스마트 압축 포맷을 설정하고 있지 않는 경우, 이 메소드로 돌려주어지는 포맷은 무효이다. 압축 포맷이 설정되어 있을지 어떨지는,IsSmartRecompressFormatSet 메소드를 호출해 조사한다.

메소드가 성공했을 경우, 호출원래는 돌려주어진 미디어 타입을 해방해, SCompFmt0 구조체를 삭제해야 한다.

if (pFormat) {
    FreeMediaType(pFormat->MediaType);
    delete pFormat;
}

IAMTimelineGroup::GetTimeline

IAMTimelineGroup 인터페이스

이 그룹이 소속하는 타임 라인을 취득한다.

구문

HRESULT GetTimeline(
    IAMTimeline **ppTimeline
);

파라미터

ppTimeline
[out] 타임 라인의 IAMTimeline 인터페이스를 받는 포인터의 주소. 그룹이 타임 라인이 일부에서 없는 경우, 값은 NULL 로 설정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

ppTimeline 에 돌려주어진 값이 NULL 이외의 경우,IAMTimeline 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineGroup::IsRecompressFormatDirty

IAMTimelineGroup 인터페이스

지원되어 있지 않다.

구문

HRESULT IsRecompressFormatDirty(
    BOOL *pVal
);

IAMTimelineGroup::IsSmartRecompressFormatSet

IAMTimelineGroup 인터페이스

그룹에스마트재압축이 설정되어 있는지 어떤지를 조사한다.

구문

HRESULT IsSmartRecompressFormatSet(
    BOOL *pVal
);

파라미터

pVal
압축 포맷이 설정되어 있는지 어떤지를 나타내는 불리언 값을 받는 변수에의 포인터. TRUE 의 경우, 압축 포맷은 설정되어 있다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineGroup::SetGroupName

IAMTimelineGroup 인터페이스

어플리케이션이 정의하는 그룹의 이름을 설정한다.

구문

HRESULT SetGroupName(
    BSTR pGroupName
);

파라미터

pGroupName
그룹의 이름을 지정하는 BSTR.

반환값

S_OK 를 돌려준다.

IAMTimelineGroup::SetMediaType

IAMTimelineGroup 인터페이스

그룹의 비압축 미디어 타입을 설정한다.

구문

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pmt
);

파라미터

pmt
[out] 포맷을 기술하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_INVALIDMEDIATYPE | 지정된 미디어 타입은 무효이다.

주의

현재, 이하의 미디어 타입이 지원 되고 있다.

  • 비압축 RGB 비디오
    • 16 비트/픽셀, 555 포맷
    • 24 비트/픽셀
    • 32 비트/픽셀
  • 16 비트 스테레오 PCM 오디오

그룹의 압축 포맷을 지정하려면 ,SetSmartRecompressFormat 메소드를 호출한다.

IAMTimelineGroup::SetMediaTypeForVB

IAMTimelineGroup 인터페이스

Automation 클라이언트용의 그룹 미디어 타입을 지정한다.

구문

HRESULT SetMediaTypeForVB(
    long Val
);

파라미터

Val
[in] 미디어 타입을 지정하는 값. 비디오의 경우는 값을 0 으로 설정해, 오디오의 경우는 1 으로 설정한다.

반환값

S_OK 를 돌려준다.

주의

이 메소드는, Automation 클라이언트용의 것이다. C++ 어플리케이션용으로는,SetMediaType 메소드를 사용한다.

IAMTimelineGroup::SetOutputBuffering

IAMTimelineGroup 인터페이스

프리뷰시에 선행해 렌더링 되는 프레임수를 지정한다.

구문

HRESULT SetOutputBuffering(
    int nBuffer
);

파라미터

nBuffer
[in] 프리뷰시에 버퍼링 되는 프레임수. 2 이상이 아니면 안된다.

반환값

성공했을 경우는 S_OK, 그 이외의 경우는 E_INVALIDARG 를 돌려준다.

주의

버퍼가 커지면, 필요한 메모리량도 커지지만, 프리뷰는 보다 스무스하게 된다. 특히, 렌더링에 시간이 걸리는 이펙트 또는 트란지션으로, 그것이 현저하다. 디폴트의 버퍼는 30 프레임이다.

IAMTimelineGroup::SetOutputFPS

IAMTimelineGroup 인터페이스

이 그룹의 비압축 출력 frame rate를 설정한다.

구문

HRESULT SetOutputFPS(
    double FPS
);

파라미터

FPS
이 그룹의 출력 frame rate (매초의 프레임수). 이 값은, 제로로 동일하게 하지 못하고, 소수점 이하 8 자리수 이상으로 할 수 없다.

반환값

성공했을 경우는 S_OK, 그 이외의 경우는 E_INVALIDARG 를 돌려준다.

주의

이 그룹으로부터 렌더링 된 출력은, 지정된 frame rate로 실행되어 소스 소재 위에의 모든 편집은, frame rate에 의해 정의되는 가장 가까운 프레임 경계에 말 수 있다.

SetSmartRecompressFormat 메소드는, frame rate를 오버라이드(override) 한다.

IAMTimelineGroup::SetPreviewMode

IAMTimelineGroup 인터페이스

그룹의 프리뷰 모드를 설정한다.

구문

HRESULT SetPreviewMode(
    BOOL fPreview
);

파라미터

fPreview
프리뷰 모드를 지정하는 불리언 값. TRUE 의 경우, 그룹은 프리뷰 모드이다. FALSE 의 경우, 그룹은 오쏘링 모드이다.

반환값

S_OK 를 돌려준다.

주의

프리뷰 모드에서는, 비디오와 오디오의 동기를 유지하기 위해서, 시간이 걸리는 이펙트 또는 트란지션에서는 프레임 빠짐이 생긴다. 그 때문에, 비디오의 움직임 그림의 기법 여기 없어지는 일이 있다. 오쏘링 모드에서는, 모든 프레임이 렌더링 된다. 오쏘링 모드는 파일에의 기입에 적절하고 있다. 오쏘링 모드로 화면에 프리뷰를 실시하면, 비디오와 오디오의 동기 금액 빗나가는 경우가 있다.

IAMTimelineGroup::SetRecompFormatFromSource

IAMTimelineGroup 인터페이스

원시 파일의 압축 포맷을 사용해 비디오재압축 포맷을 설정한다.

구문

HRESULT SetRecompFormatFromSource(
    IAMTimelineSrc *pSource
);

파라미터

pSource
소스 오브젝트의 IAMTimelineSrc 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
E_NO_TIMELINE | 그룹은 타임 라인내에 없다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
VFW_E_INVALIDMEDIATYPE | 무효인 미디어 타입. 그룹이 비디오 그룹이 아닌지, 또는 원시 파일에 비디오 스트림이 없다.

주의

이 메소드는,pSource 에 관련지을 수 있었던 원시 파일을 찾아, 파일의 최초의 비디오 스트림의 미디어 타입을 취득한다. 다음에, 그 타입을 사용해 그룹의 압축 포맷을 설정한다. 압축 포맷의 상세한 것에 대하여는, 「SetSmartRecompressFormat 」를 참조할것.

IAMTimelineGroup::SetSmartRecompressFormat

IAMTimelineGroup 인터페이스

스마트재압축으로 사용되는 압축 포맷을 지정한다.

스마트재압축은, 오디오 그룹에 대해서는 지원 되지 않는다.

구문

HRESULT SetSmartRecompressFormat(
    long *pFormat
);

파라미터

pFormat
압축 포맷을 기술하는 구조체에의 포인터. 현재는,SCompFmt0 구조체만이 유효하다. 이 파라미터는,long 형의 포인터에 캐스트 해야 한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
E_INVALIDARG | 무효인 인수.

주의

이 메소드를 호출해 비압축 포맷을 지정하기 전에, 같은 그룹의 SetMediaType 메소드를 호출한다. 압축 포맷과 비압축 포맷은, 폭, 높이, 및 frame rate가 같지 않으면 안 된다. 이러한 값이 일치하고 있지 않는 경우, 그룹의 출력 핀은, 압축 출력은 아니고, 비압축 출력을 생성한다.

이 메소드는,SetOutputFPS 메소드를 사용해 설정된 frame rate값을 오버라이드(override) 한다.

스마트재압축 포맷은, 지속적은 아니다. 어플리케이션으로 스마트재압축을 사용하는 경우, 프로젝트 파일을 로드할 때 반드시 재압축 포맷을 설정해야 한다.

IAMTimelineGroup::SetTimeline

IAMTimelineGroup 인터페이스

지원되어 있지 않다. 대신에 IAMTimeline::AddGroup 메소드를 호출한다.

구문

HRESULT SetTimeline(
    IAMTimeline *pTimeline
);


IAMTimelineObj 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의타임 라인 오브젝트를 조작하는 메소드를 제공한다. 소스, 이펙트, 트란지션, 트럭, 그룹, 및 합성을 포함한 모든 타임 라인 오브젝트는, 이 인터페이스를 이행 한다. 타임 라인 오브젝트는,IAMTimeline::CreateEmptyNode 메소드를 호출하는 것으로 생성 한다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineObj 메소드 | 설명
GetStartStop | 오브젝트의 친상대의, 오브젝트의 시작 타임과 종료 타임을 취득한다.
GetStartStop2 | GetStartStop 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.
FixTimes | 지정된 시작 타임과 종료 타임을, 친그룹의 frame rate 설정에 의해 정의되는 가장 가까운 프레임 경계에 말다.
FixTimes2 | FixTimes 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
SetStartStop | 타임 라인 상대의 시작 타임과 종료 타임을 설정한다.
SetStartStop2 | SetStartStop 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
GetPropertySetter | 오브젝트의 프로파티셋타를 취득한다.
SetPropertySetter | 오브젝트의 프로파티셋타를 설정한다.
GetSubObject | 이 오브젝트에 관련지을 수 있고 있는 서브 오브젝트를 취득한다.
SetSubObject | 지원되어 있지 않다.
SetSubObjectGUID | 이 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 글로벌 유니크 식별자 (GUID)를 지정한다.
SetSubObjectGUIDB | SetSubObjectGUID 와 같은 기능이지만, BSTR 값을 파라미터에 있다.
GetSubObjectGUID | 이 타임 라인 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 GUID 를 취득한다.
GetSubObjectGUIDB | GetSubObjectGUID 와 같은 기능이지만, BSTR 값을 파라미터에 있다.
GetSubObjectLoaded | 오브젝트의 서브 오브젝트 포인터가 설정되어 있는지 어떤지를 조사한다.
GetTimelineType | 오브젝트의 타입을 취득한다.
SetTimelineType | 지원되어 있지 않다.
SetUserID | 오브젝트에 대한 어플리케이션 정의의 식별자를 설정한다.
GetUserID | 오브젝트의 어플리케이션 정의의 식별자를 취득한다.
GetGenID | 오브젝트의 생성된 식별자를 취득한다.
SetUserName | 오브젝트에 대한 어플리케이션 정의의 이름을 설정한다.
GetUserName | 오브젝트의 어플리케이션 정의의 이름을 취득한다.
SetUserData | 어플리케이션 정의의 지속적 데이터를 설정한다.
GetUserData | 어플리케이션 정의의 지속적 데이터를 취득한다.
SetMuted | 오브젝트의 뮤트 상태를 설정한다.
GetMuted | 오브젝트의 뮤트 상태를 취득한다.
SetLocked | 오브젝트의 편집 상태를 락 또는 락 해제로 설정한다.
GetLocked | 오브젝트의 편집 상태 (락 또는 락 해제)를 취득한다.
GetDirtyRange | 지원되어 있지 않다.
GetDirtyRange2 | 지원되어 있지 않다.
SetDirtyRange | 이행되어 있지 않다.
SetDirtyRange2 | 이행되어 있지 않다.
ClearDirty | 지원되어 있지 않다.
Remove | 이 오브젝트를, 다른 장소에 재삽입할 수 있도록(듯이), 타임 라인으로부터 삭제한다.
RemoveAll | 이 오브젝트를, 서브 오브젝트와 아이를 포함해, 타임 라인으로부터 영속적으로 삭제한다.
GetTimelineNoRef | 이 메소드는 현재 지원되어 있지 않다.
GetGroupIBelongTo | 지원되어 있지 않다.
GetEmbedDepth | 지원되어 있지 않다.

IAMTimelineObj::ClearDirty

IAMTimelineObj 인터페이스

지원되어 있지 않다.

구문

HRESULT ClearDirty( void );

IAMTimelineObj::FixTimes

IAMTimelineObj 인터페이스

지정된 시작 타임과 종료 타임을, 친그룹의 frame rate 설정에 의해 정의되는 가장 가까운 프레임 경계에 말다.

구문

HRESULT FixTimes(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

파라미터

pStart
시작 타임 (100 나노초단위)을 보관 유지하는 변수에의 포인터. 호출이 성공했을 경우, 이 변수는 말 수 있었던 시간으로 설정된다.
pStop
종료 타임 (100 나노초단위)을 보관 유지하는 변수에의 포인터. 호출이 성공했을 경우, 이 변수는 말 수 있었던 시간으로 설정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 오브젝트가 그룹이 일부에서 없는 경우는,E_NOTINTREE 를 돌려준다.

주의

렌더링시에, DES 는 오브젝트의 시작 타임과 종료 타임을, 프레임 경계에 가장 가까운 값에 말다. 다만, DES 는 오브젝트의 시간은 고쳐 쓰지 않는다. 그룹의 frame rate를 변경했을 경우, 말 수 있었던 시간은 반드시 원의 시간부터 계산된다. 상세한 것에 대하여는, 「frame rate」를 참조할것.

이 메소드를 사용해, 렌더링 된 오브젝트내에서의 정확한 시작 타임과 종료 타임을 특정할 수 있다. 예를 들어, 오브젝트의 원의 시작 타임과 종료 타임은 아니고, 말 수 있었던 시간이 필요한 경우가 있다. GetStartStop 를 호출해 원의 시간을 취득해, 그 값을 FixTimes 에 건네준다.

IAMTimelineObj::FixTimes2

IAMTimelineObj 인터페이스

지정된 시작 타임과 종료 타임을, 친그룹의 frame rate 설정에 의해 정의되는 가장 가까운 프레임 경계에 말다. 이 메소드는 FixTimes 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT FixTimes2(
    REFTIME *pStart,
    REFTIME *pStop
);

파라미터

pStart
시작 타임 (초단위)을 보관 유지하는 변수에의 포인터. 호출이 성공했을 경우, 이 변수는 말 수 있었던 시간으로 설정된다.
pStop
종료 타임 (초단위)을 보관 유지하는 변수에의 포인터. 호출이 성공했을 경우, 이 변수는 말 수 있었던 시간으로 설정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 오브젝트가 그룹이 일부에서 없는 경우는,E_NOTINTREE 를 돌려준다.

IAMTimelineObj::GetDirtyRange

IAMTimelineObj 인터페이스

지원되어 있지 않다.

구문

HRESULT GetDirtyRange(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

IAMTimelineObj::GetDirtyRange2

IAMTimelineObj 인터페이스

지원되어 있지 않다.

구문

HRESULT GetDirtyRange2(
    REFTIME *pStart,
    REFTIME *pStop
);

IAMTimelineObj::GetEmbedDepth

IAMTimelineObj 인터페이스

지원되어 있지 않다.

구문

HRESULT GetEmbedDepth(
    long *pVal
);

IAMTimelineObj::GetGenID

IAMTimelineObj 인터페이스

오브젝트의 생성된 식별자를 취득한다. 이 식별자는 예약된 번호이며, 어플리케이션으로 사용해서는 안 된다.

구문

HRESULT GetGenID(
    long *pVal
);

파라미터

pVal
생성된 식별자를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineObj::GetGroupIBelongTo

IAMTimelineObj 인터페이스

지원되어 있지 않다.

구문

HRESULT GetGroupIBelongTo(
    IAMTimelineGroup **ppGroup
);

IAMTimelineObj::GetLocked

IAMTimelineObj 인터페이스

오브젝트의 편집 상태 (락 또는 락 해제)를 취득한다. 락 상태는 오브젝트를 편집해서는 안 되는 것을 나타내, 락 해제 상태는 오브젝트를 편집할 수 있는 것을 나타낸다. 타임 라인측에서는, 락을 강제하지 않는다. 락 상태의 설정은, 어플리케이션측의 편리성을 위해서(때문에) 마셔 존재한다.

구문

GetLocked(
    BOOL *pVal
);

파라미터

pVal
오브젝트의 편집 상태를 받는 불 변수에의 포인터. 이 값이 TRUE 의 경우, 오브젝트는 락 되고 있어 편집해서는 안 된다. FALSE 의 경우, 오브젝트는 락 해제되고 있어 편집할 수 있다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineObj::GetMuted

IAMTimelineObj 인터페이스

오브젝트의 뮤트 상태를 취득한다.

구문

HRESULT GetMuted(
    BOOL *pVal
);

파라미터

pVal
뮤트 상태를 나타내는 값을 받는 불 변수에의 포인터. 이 값이 TRUE 의 경우, 오브젝트와 그 아이는 뮤트 되고 있다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

오브젝트의 부모가 뮤트 되고 있는 경우, 뮤트 상태 (와)는 관계없는 것으로, 그 오브젝트도 뮤트 된 채로된다. 부모의 뮤트가 해제되었을 때에는, 그 오브젝트의 전의 뮤트 상태가 복원된다.

IAMTimelineObj::GetPropertySetter

IAMTimelineObj 인터페이스

오브젝트의 프로파티셋타를 취득한다. 오브젝트가 렌더링 될 때, 프로파티셋타내의 프로퍼티 정보가 오브젝트에 적용된다.

구문

HRESULT GetPropertySetter(
    IPropertySetter **pVal
);

파라미터

pVal
[out, retval] 프로파티셋타의 IPropertySetter 인터페이스를 받는 포인터의 주소. 오브젝트가 프로파티셋타를 가지고 있지 않은 경우, 값은 NULL 로 설정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

pVal 에 돌려주어진 값이 NULL 이외의 경우,IPropertySetter 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineObj::GetStartStop

IAMTimelineObj 인터페이스

오브젝트의 친상대의, 오브젝트의 시작 타임과 종료 타임을 취득한다.

구문

HRESULT GetStartStop(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

파라미터

pStart
시작 타임 (100 나노초단위)을 받는 변수에의 포인터.
pStop
종료 타임 (100 나노초단위)을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

합성, 그룹, 및 트럭의 시작 타임은 항상 0 이다.

렌더링시에, DES 는 오브젝트의 시작 타임과 종료 타임을, 프레임 경계에 가장 가까운 값에 말다. 다만, DES 는 오브젝트의 시간은 고쳐 쓰지 않는다. 그룹의 frame rate를 변경했을 경우, 말 수 있었던 시간은 반드시 원의 시간부터 계산된다. 상세한 것에 대하여는, 「frame rate」를 참조할것.

렌더링 된 프로젝트내에서의 시작 타임을 종료 타임을 조사하려면 ,GetStartStop 이 돌려준 값을 FixTimes 메소드에 건네준다.

IAMTimelineObj::GetStartStop2

IAMTimelineObj 인터페이스

오브젝트의 친상대의, 오브젝트의 시작 타임과 종료 타임을 취득한다. 이 메소드는 GetStartStop 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT GetStartStop2(
    REFTIME *pStart,
    REFTIME *pStop
);

파라미터

pStart
시작 타임 (초단위)을 받는 변수에의 포인터.
pStop
종료 타임 (초단위)을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineObj::GetSubObject

IAMTimelineObj 인터페이스

이 오브젝트에 관련지을 수 있고 있는 서브 오브젝트를 취득한다.

구문

HRESULT GetSubObject(
    IUnknown **pVal
);

파라미터

pVal
[out, retval] 서브 오브젝트의 IUnknown 인터페이스를 받는 포인터의 주소. 오브젝트가 서브 오브젝트를 가지고 있지 않은 경우, 값은 NULL 로 설정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

모든 타임 라인 오브젝트는, 관련지을 수 있었던 서브 오브젝트에의 포인터를 보관 유지할 수가 있다. 예를 들어, 이펙트의 서브 오브젝트는 보통, 이펙트를 생성하는 Microsoft® DirectXt® 변환 오브젝트이다.

pVal 에 돌려주어진 값이 NULL 이외의 경우,IUnknown 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineObj::GetSubObjectGUID

IAMTimelineObj 인터페이스

이 타임 라인 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 GUID 를 취득한다.

구문

HRESULT GetSubObjectGUID(
    GUID *pVal
);

파라미터

pVal
서브 오브젝트의 GUID 를 받는 변수에의 포인터. 또는, 오브젝트가 서브 오브젝트를 가지고 있지 않은 경우는 GUID_NULL.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineObj::GetSubObjectGUIDB

IAMTimelineObj 인터페이스

이 타임 라인 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 GUID 를 취득한다. 이 메소드는 GetSubObjectGUID 와 같은 기능이지만, BSTR 값을 파라미터에 있다.

구문

HRESULT GetSubObjectGUIDB(
    BSTR *pVal
);

파라미터

pVal
[out, retval] 서브 오브젝트의 GUID 를 나타내는 캐릭터 라인을 받는 BSTR 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_OUTOFMEMORY 또는 에러의 발생을 나타내는 그 외의 HRESULT 값을 돌려준다.

주의

이 메소드는, 캐릭터 라인에 필요한 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

IAMTimelineObj::GetSubObjectLoaded

IAMTimelineObj 인터페이스

오브젝트의 서브 오브젝트 포인터가 설정되어 있는지 어떤지를 조사한다.

구문

HRESULT GetSubObjectLoaded(
    BOOL *pVal
);

파라미터

pVal
불리언 값을 받는 변수에의 포인터. 이 값이 TRUE 의 경우, 서브 오브젝트 포인터가 설정되어 있다. FALSE 의 경우, 포인터는 설정되어 있지 않다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineObj::GetTimelineNoRef

IAMTimelineObj 인터페이스

지원되어 있지 않다.

구문

HRESULT GetTimelineNoRef(
    IAMTimeline **ppResult
);

IAMTimelineObj::GetTimelineType

IAMTimelineObj 인터페이스

오브젝트의 타입을 취득한다.

구문

HRESULT GetTimelineType(
    TIMELINE_MAJOR_TYPE *pVal
);

파라미터

pVal
오브젝트의 타입을 나타내는,TIMELINE_MAJOR_TYPE 열거형의 멤버를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineObj::GetUserData

IAMTimelineObj 인터페이스

어플리케이션 정의의 지속적 데이터를 취득한다.

구문

HRESULT GetUserData(
    BYTE *pData,
    long *pSize
);

파라미터

pData
데이터를 받는 버퍼에의 포인터. 할당하는 버퍼의 사이즈를 조사하려면 , 이 파라미터를 NULL 로 설정한다. 필요한 사이즈가 pSize 에 돌려주어진다.
pSize
데이터의 사이즈 (바이트 단위)를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineObj::GetUserID

IAMTimelineObj 인터페이스

오브젝트의 어플리케이션 정의의 식별자를 취득한다.

구문

HRESULT GetUserID(
    long *pVal
);

파라미터

pVal
어플리케이션 정의의 식별자를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineObj::GetUserName

IAMTimelineObj 인터페이스

오브젝트의 어플리케이션 정의의 이름을 취득한다.

구문

HRESULT GetUserName(
    BSTR *pVal
);

파라미터

pVal
[out, retval] 오브젝트의 이름을 받는 BSTR 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_OUTOFMEMORY 또는 에러의 발생을 나타내는 그 외의 HRESULT 값을 돌려준다.

주의

이 메소드는, 캐릭터 라인에 필요한 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

IAMTimelineObj::Remove

IAMTimelineObj 인터페이스

이 오브젝트를 (서브 오브젝트는 포함하지만, 아이는 포함하지 않는다), 다른 장소에 재삽입할 수 있도록(듯이), 타임 라인으로부터 삭제한다.

구문

HRESULT Remove( void );

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 어플리케이션이 즉석에서 그 오브젝트를 타임 라인에 삽입하는 경우에게만 호출한다. 이 메소드의 호출에 이어 오브젝트를 재삽입하지 않는 것은, 무효인 조작이다. 오브젝트를 영속적으로 삭제하려면 ,RemoveAll 를 호출한다.

IAMTimelineObj::RemoveAll

IAMTimelineObj 인터페이스

이 오브젝트를, 서브 오브젝트와 아이를 포함해, 타임 라인으로부터 영속적으로 삭제한다.

구문

HRESULT RemoveAll( void );

반환값

S_OK 를 돌려준다.

주의

오브젝트를 타임 라인의 다른 장소에 재삽입하는 목적으로 삭제하려면 ,Remove 를 호출한다.

IAMTimelineObj::SetDirtyRange

IAMTimelineObj 인터페이스

이행되어 있지 않다.

구문

HRESULT SetDirtyRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

IAMTimelineObj::SetDirtyRange2

IAMTimelineObj 인터페이스

이행되어 있지 않다.

구문

HRESULT SetDirtyRange2(
    REFTIME Start,
    REFTIME Stop
);

IAMTimelineObj::SetLocked

IAMTimelineObj 인터페이스

오브젝트의 편집 상태를 락 또는 락 해제로 설정한다. 락 상태는 오브젝트를 편집해서는 안 되는 것을 나타내, 락 해제 상태는 오브젝트를 편집할 수 있는 것을 나타낸다. 타임 라인측에서는, 락을 강제하지 않는다. 락 상태의 설정은, 어플리케이션측의 편리성을 위해서(때문에) 마셔 존재한다.

구문

HRESULT SetLocked(
    BOOL newVal
);

파라미터

newVal
오브젝트의 편집 모드를 지정하는 불리언 값. TRUE 의 경우, 오브젝트는 락 되고 있어 편집해서는 안 된다. FALSE 의 경우, 오브젝트는 락 해제되고 있어 편집할 수 있다.

반환값

S_OK 를 돌려준다.

IAMTimelineObj::SetMuted

IAMTimelineObj 인터페이스

오브젝트의 뮤트 상태를 설정한다. 뮤트 된 오브젝트는, 렌더링 되지 않지만, 타임 라인내에는 존재한 채로된다.

구문

HRESULT SetMuted(
    BOOL newVal
);

파라미터

newVal
뮤트 상태를 지정하는 플래그. TRUE 의 경우, 오브젝트와 그 모든 아이는 뮤트 되고 있다.

반환값

S_OK 를 돌려준다.

주의

오브젝트를 뮤트 하면, 그 오브젝트가 가지는 아이도 모두 뮤트 된다. 예를 들어, 어느 트럭을 뮤트 하면, 그 트럭내의 트란지션, 소스, 및 이펙트도 모두 뮤트 된다. 오브젝트의 뮤트가 해제되면(자), 그 아이는 각각의 전 상태 (뮤트 또는 뮤트 해제)에 돌아온다.

IAMTimelineObj::SetPropertySetter

IAMTimelineObj 인터페이스

오브젝트의 프로파티셋타를 설정한다. 오브젝트가 렌더링 될 때, 프로파티셋타내의 프로퍼티 정보가 오브젝트에 적용된다. 이 메소드는, 트란지션 및 이펙트 오브젝트로 호출한다.

구문

HRESULT SetPropertySetter(
    IPropertySetter *newVal
);

파라미터

newVal
프로파티셋타의 IPropertySetter 인터페이스에의 포인터.

반환값

S_OK 를 돌려준다.

IAMTimelineObj::SetStartStop

IAMTimelineObj 인터페이스

오브젝트의 친상대의, 오브젝트의 시작 타임과 종료 타임을 설정한다.

구문

HRESULT SetStartStop(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

파라미터

Start
새로운 시작 타임 (100 나노초단위). 기존의 시작 타임을 보관 유지하는 경우는 -1.
Stop
새로운 종료 타임 (100 나노초단위). 기존의 종료 타임을 보관 유지하는 경우는 -1.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 이행되어 있지 않다.

주의

트럭, 합성, 및 그룹은, 이 메소드를 이행 하지 않는다. 이러한 오브젝트에서는, 시작 타임은 항상 제로이며, 종료 타임은 그 오브젝트가 소유최대의 종료 타임이다.

같은 트럭내의 소스 오브젝트로 서로 겹치는 시간을 설정해서는 안 된다. 그러한 설정을 실시하면, 미정도리의 동작을 일으키는 일이 있다.

소스 오브젝트의 경우, 시작 타임과 종료 타임은, 미디어 시작 타임 및 미디어 종료 타임부터 독립하고 있다. 이러한 한편의 조를 변경해도, 이제 한편에 영향은 없다. 미디어 시작 타임과 미디어 종료 타임을 설정하려면 ,IAMTimelineSrc::SetMediaTimes 메소드를 호출한다. 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

IAMTimelineObj::SetStartStop2

IAMTimelineObj 인터페이스

오브젝트의 친상대의, 오브젝트의 시작 타임과 종료 타임을 설정한다. 이 메소드는 SetStartStop 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT SetStartStop2(
    REFTIME Start,
    REFTIME Stop
);

파라미터

Start
새로운 시작 타임 (초단위). 기존의 시작 타임을 보관 유지하는 경우는 -1.
Stop
새로운 종료 타임 (초단위). 기존의 종료 타임을 보관 유지하는 경우는 -1.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 이행되어 있지 않다.

IAMTimelineObj::SetSubObject

IAMTimelineObj 인터페이스

지원되어 있지 않다.

구문

HRESULT SetSubObject(
    IUnknown *newVal
);

IAMTimelineObj::SetSubObjectGUID

IAMTimelineObj 인터페이스

이 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 GUID 를 지정한다.

구문

HRESULT SetSubObjectGUID(
    GUID newVal
);

파라미터

newVal
서브 오브젝트의 GUID.

반환값

S_OK 를 돌려준다.

주의

렌더링 엔진은, 필요에 따라서 서브 오브젝트의 인스턴스를 생성 한다.

IAMTimelineObj::SetSubObjectGUIDB

IAMTimelineObj 인터페이스

이 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 GUID 를 지정한다. 이 메소드는 SetSubObjectGUID 와 같은 기능이지만, BSTR 값을 파라미터에 있다.

구문

HRESULT SetSubObjectGUIDB(
    BSTR newVal
);

파라미터

newVal
서브 오브젝트의 GUID 를 나타내는 BSTR.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 HRESULT 값을 돌려준다.

IAMTimelineObj::SetTimelineType

IAMTimelineObj 인터페이스

지원되어 있지 않다. 새로운 타임 라인 오브젝트를 생성 하려면 ,IAMTimeline::CreateEmptyNode 메소드를 호출한다. 오브젝트가 생성 한 다음에는, 그 타입은 변경할 수 없다.

구문

HRESULT SetTimelineType(
    TIMELINE_MAJOR_TYPE newVal
);

IAMTimelineObj::SetUserData

IAMTimelineObj 인터페이스

어플리케이션 정의의 지속적 데이터를 설정한다.

구문

HRESULT SetUserData(
    BYTE *pData,
    long Size
)

파라미터

pData
데이터를 보관 유지하는 버퍼에의 포인터.
Size
데이터의 사이즈 (바이트 단위).

반환값

성공했을 경우는, S_OK 를 돌려준다. 메모리가 부족한 경우는, E_OUTOFMEMORY 를 돌려준다.

IAMTimelineObj::SetUserID

IAMTimelineObj 인터페이스

오브젝트에 대한 어플리케이션 정의의 식별자를 설정한다.

구문

HRESULT SetUserID(
    long newVal
);

파라미터

newVal
식별자를 지정하는 값. 이 식별자는, 어플리케이션에 의해서만 사용되어 어떠한 값에서도 상관없다.

반환값

S_OK 를 돌려준다.

IAMTimelineObj::SetUserName

IAMTimelineObj 인터페이스

오브젝트에 대한 어플리케이션 정의의 이름을 설정한다.

구문

HRESULT SetUserName(
    BSTR newVal
);

파라미터

newVal
이름을 보관 유지하는 와이드 캐릭터 라인. 256 문자를 넘는 캐릭터 라인은, 절약할 수 있는 일이 있다.

반환값

S_OK 를 돌려준다.


IAMTimelineSplittable 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의 타임 라인 오브젝트를 분할한다. 소스, 이펙트, 트란지션, 및 트럭은 이 인터페이스를 이행 한다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineSplittable 메소드 | 설명
SplitAt | 지정된 시간에 오브젝트를 분할한다.
SplitAt2 | SplitAt 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

IAMTimelineSplittable::SplitAt

IAMTimelineSplittable 인터페이스

지정된 시간에 오브젝트를 분할한다.

구문

HRESULT SplitAt(
    REFERENCE_TIME Time
);

파라미터

Time
오브젝트를 분할하는 시간. 오브젝트의 선두 상대로, 100 나노초단위.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_FALSE | 분할하는 오브젝트가 없다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.

주의

소스, 이펙트, 또는 트란지션을 분할하는 경우, 이 메소드는 같은 타입의 2 번째의 오브젝트를 생성 한다. 원의 오브젝트는, 분할이 지정된 시간까지 절약할 수 있고 절약할 수 있었던 부분이 새로운 오브젝트가 된다. 새로운 오브젝트는, 같은 프로퍼티를 모두 계승한다. 소스 오브젝트에서는, 이 메소드는 분할 시간에 걸리는 이펙트도 분할한다.

트럭으로 이 메소드를 호출하면, 지정된 만큼 비율 시간에 트럭내에 있는 모든 소스, 이펙트, 및 트란지션이 분할된다. 이 경우, 2 번째의 트럭은 생성 되지 않는다 (트럭은, 시간 제로로부터 시작되어, 무한하게 신장한다). 분할 시간이, 트럭내의 모든 것보다 나중이 되는 경우, 이 메소드는 S_FALSE 를 돌려준다.

IAMTimelineSplittable::SplitAt2

IAMTimelineSplittable 인터페이스

지정된 시간에 오브젝트를 분할한다. 이 메소드는 SplitAt 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT SplitAt2(
    REFTIME Time
);

파라미터

Time
오브젝트를 분할하는 시간. 오브젝트의 선두 상대로, 초단위.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_FALSE | 분할하는 오브젝트가 없다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.


IAMTimelineSrc 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의 소스 오브젝트의 조작과 프로퍼티의 설정을 실시하는 메소드를 제공한다. 소스 오브젝트는, 미디어 소스로부터의 1 개의 미디어 스트림을 나타낸다.

미디어 시작 타임과 미디어 종료 타임을 설정하는 것으로써, 원시 파일내의 데이터의 부분을 사용할 수 있다. 이 2 개의 값은, 소스 오브젝트의 시작과 마지막을, 원의 미디어 소스 상대로 지정한다. 미디어 타임은,타임 라인 위에의 오브젝트의 시작 및 종료 타임과는 다른 경우가 있어, 속도를 바꾼 재생이 가능하다 (오디오 소스의 경우, 피치 쉬프트가 생긴다).

상세한 것에 대하여는, 「타임 라인의 구축」 및 「소스의 조작」을 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineSrc 메소드 | 설명
GetMediaTimes | 미디어 시작 타임과 종료 타임을 취득한다.
GetMediaTimes2 | GetMediaTimes 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.
ModifyStopTime | 타임 라인 상대의 종료 타임을 설정한다.
ModifyStopTime2 | ModifyStopTime 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
FixMediaTimes | 지정된 타임값을, 출력 frame rate에 의해 정의되는 가장 가까운 프레임 경계에 말다.
FixMediaTimes2 | FixMediaTimes 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
SetMediaTimes | 미디어 종료 타임과 시작 타임을 설정한다.
SetMediaTimes2 | SetMediaTimes 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
SetMediaLength | 원시 파일의 시간폭을 지정한다.
SetMediaLength2 | SetMediaLength 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
GetMediaLength | 이 소스 오브젝트의 미디어장을 취득한다.
GetMediaLength2 | GetMediaLength 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
GetMediaName | 이 소스 오브젝트가 나타내는 원시 파일의 이름을 취득한다.
SetMediaName | 이 소스 오브젝트가 나타내는 원시 파일의 이름을 지정한다.
SpliceWithNext | 이 소스 오브젝트를 다른 소스 오브젝트에 결합한다.
GetStreamNumber | 소스 오브젝트의 현재의 스트림 번호를 취득한다.
SetStreamNumber | 이 소스 오브젝트에 관련지을 수 있고 있는 원시 파일로부터 읽어들이는 스트림을 지정한다.
IsNormalRate | 클립이 보통의 재생 레이트로 재생될지 어떨지를 나타낸다.
GetDefaultFPS | 소스 오브젝트의 디폴트 frame rate를 취득한다.
SetDefaultFPS | 소스 오브젝트의 디폴트 frame rate를 설정한다.
GetStretchMode | 비디오 소스의 신축 모드를 취득한다.
SetStretchMode | 비디오 소스의 신축 모드를 설정한다.

IAMTimelineSrc::FixMediaTimes

IAMTimelineSrc 인터페이스

지정된 타임값을, 출력 frame rate에 의해 정의되는 가장 가까운 프레임 경계에 말다. 보통, 어플리케이션으로 이 메소드를 호출할 필요는 없다.

구문

HRESULT FixMediaTimes(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

파라미터

pStart
시작 타임 (100 나노초단위)을 보관 유지하는 변수에의 포인터. 호출이 성공했을 경우, 이 변수는 말 수 있었던 시간으로 설정된다.
pStop
종료 타임 (100 나노초단위)을 보관 유지하는 변수에의 포인터. 호출이 성공했을 경우, 이 변수는 말 수 있었던 시간으로 설정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

이 메소드는 IAMTimelineObj::FixTimes 메소드를 닮아 있지만, 미디어 시간과 타임 라인 시간의 원의 비율을 보관 유지한다. 가장 가까운 프레임 경계에 시간을 마는 것으로, 이 비가 변화하는 일이 있다.

IAMTimelineSrc::FixMediaTimes2

IAMTimelineSrc 인터페이스

지정된 타임값을, 출력 frame rate에 의해 정의되는 가장 가까운 프레임 경계에 말다. 이 메소드는 FixMediaTimes 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT FixMediaTimes2(
    REFTIME *pStart,
    REFTIME *pStop
);

파라미터

pStart
시작 타임 (초단위)을 보관 유지하는 변수에의 포인터. 호출이 성공했을 경우, 이 변수는 말 수 있었던 시간으로 설정된다.
pStop
종료 타임 (초단위)을 보관 유지하는 변수에의 포인터. 호출이 성공했을 경우, 이 변수는 말 수 있었던 시간으로 설정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineSrc::GetDefaultFPS

IAMTimelineSrc 인터페이스

소스 오브젝트의 디폴트 frame rate를 취득한다. 렌더링 엔진이 원의 소스로부터 frame rate를 특정할 수 없는 경우, 이 값이 사용된다.

구문

HRESULT GetDefaultFPS(
    double *pFPS
);

파라미터

pFPS
디폴트의 frame rate (매초의 프레임수)를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

파일 포맷으로 frame rate가 지정되고 있는 경우, 디폴트 frame rate는 필요없다. 이것은, 오디오 및 비디오 포맷의 경우에 들어맞는다.

소스가 비트 맵 또는 JPEG 이미지의 경우, 렌더링 엔진은 그것을디바이스에 의존하지 않는 비트 맵 (DIB) 순서의 최초의 이미지로서 사용해, 그 frame rate는 디폴트 frame rate에 동일해진다. DIB 순서는 아니고, 이 스태틱 이미지를 렌더링 하려면 , 디폴트 frame rate를 0 으로 설정한다.

소스가 GIF 의 경우는, frame rate를 설정해서는 안 된다. 애니메이션 GIF 의 경우, GIF 파일이 각 이미지간의 지연을 지정한다.

IAMTimelineSrc::GetMediaLength

IAMTimelineSrc 인터페이스

이 소스 오브젝트의 미디어장을 취득한다.

구문

HRESULT GetMediaLength(
    REFERENCE_TIME *pLength
);

파라미터

pLength
미디어장 (100 나노초단위)을 받는 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_NOTDETERMINED | 이 오브젝트에 미디어 시간은 설정되어 있지 않다.
E_POINTER | NULL 포인터 인수.

참조

SetMediaLength

IAMTimelineSrc::GetMediaLength2

IAMTimelineSrc 인터페이스

이 소스 오브젝트의 미디어장을 취득한다. 이 메소드는 GetMediaLength 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT GetMediaLength2(
    REFTIME *pLength
);

파라미터

pLength
미디어장 (초단위)을 받는 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_NOTDETERMINED | 이 오브젝트에 미디어 시간은 설정되어 있지 않다.
E_POINTER | NULL 포인터 인수.

IAMTimelineSrc::GetMediaName

IAMTimelineSrc 인터페이스

이 소스 오브젝트가 나타내는 원시 파일의 이름을 취득한다.

구문

HRESULT GetMediaName(
    BSTR *pVal
);

파라미터

pVal
[out, retval] 파일의 이름을 받는 캐릭터 라인에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_OUTOFMEMORY 또는 에러의 발생을 나타내는 그 외의 HRESULT 값을 돌려준다.

주의

이 메소드는, 캐릭터 라인에 필요한 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

IAMTimelineSrc::GetMediaTimes

IAMTimelineSrc 인터페이스

미디어 시작 타임과 종료 타임을 취득한다.

구문

HRESULT GetMediaTimes(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

파라미터

pStart
미디어 시작 타임 (100 나노초단위)을 받는 변수에의 포인터.
pStop
미디어 종료 타임 (100 나노초단위)을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

미디어 시간은, 원의 미디어 파일 상대이다. 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

IAMTimelineSrc::GetMediaTimes2

IAMTimelineSrc 인터페이스

미디어 시작 타임과 종료 타임을 취득한다. 이 메소드는 GetMediaTimes 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT GetMediaTimes2(
    REFTIME *pStart,
    REFTIME *pStop
);

파라미터

pStart
미디어 시작 타임 (초단위)을 받는 변수에의 포인터.
pStop
미디어 종료 타임 (초단위)을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineSrc::GetStreamNumber

IAMTimelineSrc 인터페이스

소스 오브젝트의 현재의 스트림 번호를 취득한다.

구문

HRESULT GetStreamNumber(
    long *pVal
);

파라미터

pVal
스트림 번호를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineSrc::GetStretchMode

IAMTimelineSrc 인터페이스

신축 모드를 취득한다. 신축 모드는, 비디오 소스의 사이즈가 출력 넓이와 일치하지 않을 때에, 어떻게 렌더링 되는지를 지정한다.

구문

HRESULT GetStretchMode(
    int *pnStretchMode
);

파라미터

pnStretchMode
현재의 신축 모드를 나타내는 플래그를 받는 변수에의 포인터. 가능한 값은 다음과 같다.
  • RESIZEF_STRETCH
  • RESIZEF_CROP
  • RESIZEF_PRESERVEASPECTRATIO
  • RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineSrc::IsNormalRate

IAMTimelineSrc 인터페이스

클립이 보통의 재생 레이트로 재생될지 어떨지, 즉 원의 파일의 재생 레이트인가 어떤가를 나타낸다.

구문

HRESULT IsNormalRate(
    BOOL *pVal
);

파라미터

pVal
클립의 렌더링 방법을 나타내는 불리언 값을 받는 변수에의 포인터. 값이 TRUE 의 경우, 클립은 보통의 재생 레이트로 재생된다. 그렇지 않은 경우, 보통과는 다른 속도로 재생된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

주의

클립의 재생 레이트는, 타임 라인 상대의 미디어 시작 타임과 미디어 종료 타임에 의해 정해진다.

재생 레이트 = (미디어 종료 타임 - 미디어 시작 타임) / (타임 라인 종료 타임 - 타임 라인 시작 타임)

이 비가 1 에 동일한 경우, 클립은 생성시의 속도로 재생된다. 그렇지 않은 경우, 보통과는 다른 속도로 재생된다. 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

IAMTimelineSrc::ModifyStopTime

IAMTimelineSrc 인터페이스

타임 라인 상대의 종료 타임을 설정한다.

구문

HRESULT ModifyStopTime(
    REFERENCE_TIME Stop
);

파라미터

Stop
새로운 종료 타임 (100 나노초단위).

반환값

S_OK 를 돌려준다. 지정된 시간이 유효하지 않은 경우는 E_INVALIDARG 를 돌려준다.

주의

이 메소드는, 원의 시작 타임과 새로운 종료 타임을 지정해 IAMTimelineObj::SetStartStop 를 호출하는 것과 동등하다.

IAMTimelineSrc::ModifyStopTime2

IAMTimelineSrc 인터페이스

종료 타임을 설정한다. 이 메소드는 ModifyStopTime 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT ModifyStopTime2(
    REFTIME Stop
);

파라미터

Stop
새로운 종료 타임 (초단위).

반환값

성공했을 경우, S_OK 를 돌려준다. 지정된 시간이 유효하지 않은 경우는, E_INVALIDARG 를 돌려준다.

IAMTimelineSrc::SetDefaultFPS

IAMTimelineSrc 인터페이스

소스 오브젝트의 디폴트 frame rate를 설정한다.

구문

HRESULT SetDefaultFPS(
    double FPS
);

파라미터

FPS
디폴트의 frame rate (매초의 프레임수).

반환값

성공했을 경우, S_OK 를 돌려준다. 지정된 frame rate가 제로보다 작은 경우는, E_INVALIDARG 를 돌려준다.

주의

렌더링 엔진이 원의 원시 파일로부터 frame rate를 특정할 수 없는 경우, 이 값이 사용된다.

이 메소드는, 정의 끝난 frame rate를 가지지 않는 원시 파일 에 대해서만 호출한다. 비트 맵 및 JPEG 파일의 경우, 디폴트 frame rate는 제로이며, 그것에 의해 소스는 스티르이메이지로서 렌더링 된다. 이미지를 DIB 순서의 최초의 프레임으로서 사용하려면 , frame rate를 제로보다 큰 값으로 설정한다. 상세한 것에 대하여는, 「소스의 조작」을 참조할것.

IAMTimelineSrc::SetMediaLength

IAMTimelineSrc 인터페이스

원시 파일의 시간폭을 지정한다.

구문

HRESULT SetMediaLength(
    REFERENCE_TIME Length
);

파라미터

Length
미디어장 (100 나노초단위).

반환값

S_OK 를 돌려준다.

주의

미디어 종료 타임을 설정하기 전에 미디어장을 설정하는 것으로써, 잠재적인 렌더링 에러를 회피할 수 있다. 미디어 종료 타임을 설정할 경우에, DES 는 그것을 미디어장과 교제하게 해 체크한다.

이 메소드는 Length 파라미터를 검증하지 않지만, 그 값은 원시 파일의 실제의 시간폭과 동일하지 않으면 안 된다. 원시 파일의 시간폭은,IMediaDet::get_StreamLength 를 호출하는 것으로 취득한다.

IAMTimelineSrc::SetMediaLength2

IAMTimelineSrc 인터페이스

원시 파일의 시간폭을 지정한다. 이 메소드는 SetMediaLength 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT SetMediaLength2(
    REFTIME Length
);

파라미터

Length
미디어장 (초단위).

반환값

S_OK 를 돌려준다.

IAMTimelineSrc::SetMediaName

IAMTimelineSrc 인터페이스

이 소스 오브젝트가 나타내는 원시 파일의 이름을 지정한다.

구문

HRESULT SetMediaName(
    BSTR newVal
);

파라미터

newVal
미디어 파일의 이름을 지정하는 캐릭터 라인.

반환값

S_OK 를 돌려준다.

IAMTimelineSrc::SetMediaTimes

IAMTimelineSrc 인터페이스

미디어 종료 타임과 시작 타임을 설정한다.

구문

HRESULT SetMediaTimes(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

파라미터

Start
미디어 시작 타임 (100 나노초단위).
Stop
미디어 종료 타임 (100 나노초단위).

반환값

S_OK 를 돌려준다.

주의

미디어 타임은, 원의 미디어 파일 상대의 미디어 종료 타임과 미디어 시작 타임이다. 비디오 또는 오디오 소스를 타임 라인에 추가할 경우에는, 반드시 미디어 타임을 설정한다. 그렇게 하지 않으면 렌더링으로 문제가 발생하는 일이 있다. 종료 타임은, 시작 타임보다 크지 않으면 안 된다.

비디오 소스로부터 스티르후레임을 사용하려면 , 시작 타임부터 소수점 이하의 값 (예를 들어 100 나노초)만 큰 종료 타임을 설정한다. 시작 타임과 종료 타임을 같은 값으로 설정 하면, 렌더링 에러가 발생한다.

타임 라인의 시간폭이 미디어의 시간폭과 일치하지 않는 경우, 거기에 맞추어 소스가 신축한다. 이것에 의해, 클립의 재생은, 생성시와는 다른 레이트로 행해지게 된다 (오디오 소스에서는, 피치 쉬프트가 생긴다). 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

원시 파일의 시간폭은,SetMediaLength 메소드를 호출하는 것으로 지정할 수 있다. 미디어 종료 타임이 시간폭을 넘는 경우, DES 는 종료 타임을 앞당긴다.

IAMTimelineSrc::SetMediaTimes2

IAMTimelineSrc 인터페이스

미디어 종료 타임과 시작 타임을 설정한다. 이 메소드는 SetMediaTimes 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT SetMediaTimes2(
    REFTIME Start,
    REFTIME Stop
);

파라미터

Start
미디어 시작 타임 (초단위).
Stop
미디어 종료 타임 (초단위).

반환값

S_OK 를 돌려준다.

IAMTimelineSrc::SetStreamNumber

IAMTimelineSrc 인터페이스

이 소스 오브젝트에 관련지을 수 있고 있는 원시 파일로부터 읽어들이는 스트림을 지정한다.

구문

HRESULT SetStreamNumber(
    long Val
);

파라미터

Val
스트림 번호. 친그룹의, 일치하는 미디어 타입의 스트림세트로부터 얻을 수 있다.

반환값

성공했을 경우, S_OK 를 돌려준다. Val 가 제로보다 작은 경우는, E_INVALIDARG 를 돌려준다.

주의

Val 파라미터는, 친그룹의 미디어 타입에 일치하는 스트림세트에 있어서의 스트림 번호를 지정한다. 이것은, 원시 파일의 스트림세트 전체에 있어서의 번호는 아니다. 예를 들어, 파일에 비디오 스트림이 2 개와 오디오 스트림이 2 개 있는 경우,Val 에 0 을 지정 하면 최초의 비디오 스트림이 선택된다. 호출 바탕으로, 유효한 스트림 번호를 지정할 책임이 있다.

스트림 번호의 디폴트는 제로이다.

IAMTimelineSrc::SetStretchMode

IAMTimelineSrc 인터페이스

신축 모드를 설정한다. 신축 모드는, 비디오 소스의 사이즈가 출력 넓이와 일치하지 않을 때에, 어떻게 렌더링 되는지를 지정한다.

구문

HRESULT SetStretchMode(
    int nStretchMode
);

파라미터

nStretchMode
현재의 신축 모드를 나타내는 플래그. 가능한 값은 다음과 같다.
  • RESIZEF_STRETCH
  • RESIZEF_CROP
  • RESIZEF_PRESERVEASPECTRATIO
  • RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX

반환값

S_OK 를 돌려준다.

IAMTimelineSrc::SpliceWithNext

IAMTimelineSrc 인터페이스

소스 오브젝트를 다른 소스 오브젝트에 결합한다.

구문

HRESULT SpliceWithNext(
    IAMTimelineObj *pNext
);

파라미터

pNext
현재의 소스를 결합하는 소스 오브젝트의 IAMTimelineObj 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 반환값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_NOINTERFACE | pNext 파라미터에 의해 지정된 오브젝트는 소스 오브젝트는 아니다.
E_POINTER | NULL 포인터 인수.

주의

현재의 이행에서는, 이 메소드는 pNext 위에의 이펙트는 파기한다.

이 메소드를 올바르게 동작시키려면 ,pNext 는 현재의 소스 오브젝트의 프레임에 일치하고 있지 않으면 안 된다.

  • 이것은, 같은 원시 파일을 공유하고 있지 않으면 안 된다.
  • 미디어 시작 타임이, 현재의 소스의 미디어 종료 타임과 동일하지 않으면 안 된다.
  • 재생 레이트가 동일하지 않으면 안 된다. 재생 레이트는, 미디어 시간폭을 타임 라인 시간폭으로 나눈 값이다.


IAMTimelineTrack 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의트럭 오브젝트를 조작하는 메소드를 제공한다.

트럭에는, 최종 출력으로 렌더링 되는 소스의 리스트가 들어간다. 같은 트럭내의 소스는, 오버랩 할 수 없다. 비디오 트럭은, 이펙트와 트란지션의 양쪽 모두를 가질 수가 있다. 렌더링 엔진은, 트란지션을 적용하기 전에 이펙트를 적용한다. 오디오 트럭은, 이펙트를 가질 수 있지만, 트란지션을 가질 수 없다.

상세한 것에 대하여는, 「타임 라인 모델」을 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineTrack 메소드 | 설명
SrcAdd | 트럭에 소스를 추가한다.
GetNextSrc | 지정된 시간 이후에 시작하는 다음의 소스의 트럭을 검색한다.
GetNextSrc2 | GetNextSrc 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.
MoveEverythingBy | 지정된 시간 이후에 시작하는 모든 오브젝트를, 타임 라인상에서 지정된 거리만 이동한다.
MoveEverythingBy2 | MoveEverythingBy 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
GetSourcesCount | 트럭내의 소스의 개수를 취득한다.
AreYouBlank | 트럭이 공백 (소스 오브젝트가 들어가 있지 않다) 화도인가 조사한다.
GetSrcAtTime | 지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 소스 오브젝트를 취득한다.
GetSrcAtTime2 | GetSrcAtTime 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
InsertSpace | 지정된 시간에 존재하는 모든 오브젝트를 분할해, 그 사이에 스페이스를 삽입한다.
InsertSpace2 | InsertSpace 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
ZeroBetween | 트럭으로부터, 지정된 시간의 사이에 있는 모든 것을 삭제한다.
ZeroBetween2 | ZeroBetween 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
GetNextSrcEx | 지정된 소스에 계속되는 다음의 소스를 취득한다.

IAMTimelineTrack::AreYouBlank

IAMTimelineTrack 인터페이스

트럭이 공백 (소스 오브젝트가 들어가 있지 않다) 화도인가 조사한다.

구문

HRESULT AreYouBlank(
    long *pVal
);

파라미터

pVal
트럭이 공백인가 어떤가를 지정하는 불리언 값을 받는 변수에의 포인터. 이 값이 TRUE 의 경우, 오브젝트는 공백이며, 소스 오브젝트는 들어가 있지 않다. FALSE 의 경우, 트럭은 공백은 아니다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineTrack::GetNextSrc

IAMTimelineTrack 인터페이스

지정된 시간 이후에 시작하는 다음의 소스의 트럭을 검색한다.

구문

HRESULT GetNextSrc(
    IAMTimelineObj **ppSrc,
    REFERENCE_TIME *pInOut
);

파라미터

ppSrc
[out] 소스 오브젝트의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
pInOut
검색하는 시작 타임 (100 나노초단위)을 보관 유지하는 변수에의 포인터. 이 메소드는, 소스를 취득했을 경우, 이 값을 소스의 종료 타임으로 설정한다. 소스를 취득하지 않았던 경우, 이 값은 무효가 되어, 어플리케이션으로 사용해서는 안 된다.

반환값

이 메소드는, 소스를 취득했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

pInOut 로 지정된 값이 소스의 시작 타임과 종료 타임의 사이에 있으면, 메소드는 그 소스를 취득한다.

메소드가 S_OK 를 돌려주었을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineTrack::GetNextSrc2

IAMTimelineTrack 인터페이스

지정된 시간 이후에 시작하는 다음의 소스의 트럭을 검색한다. 이 메소드는 GetNextSrc 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT GetNextSrc2(
    IAMTimelineObj **ppSrc,
    REFTIME *pInOut
);

파라미터

ppSrc
[out] 소스 오브젝트의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
pInOut
검색의 시작 타임 (초단위)을 보관 유지하는 변수에의 포인터. 이 메소드는, 소스를 취득했을 경우, 이 값을 소스의 종료 타임으로 설정한다. 소스를 취득하지 않았던 경우, 이 값은 무효가 되어, 어플리케이션으로 사용해서는 안 된다.

반환값

이 메소드는, 소스를 취득했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는 S_FALSE 를 돌려준다.

IAMTimelineTrack::GetNextSrcEx

IAMTimelineTrack 인터페이스

지정된 소스에 계속되는 다음의 소스를 취득한다.

구문

HRESULT GetNextSrcEx(
    IAMTimelineObj *pLast,
    IAMTimelineObj **ppNext
);

파라미터

pLast
전의 소스 오브젝트에의 포인터. 트럭내의 최초의 소스를 취득하는 경우는 NULL.
ppNext
[out] 다음의 소스 오브젝트의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.

반환값

이 메소드는, 소스를 취득했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

메소드가 S_OK 를 돌려주었을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineTrack::GetSourcesCount

IAMTimelineTrack 인터페이스

트럭내의 소스의 개수를 취득한다.

구문

HRESULT GetSourcesCount(
    long *pVal
);

파라미터

pVal
트럭내의 소스의 개수를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineTrack::GetSrcAtTime

IAMTimelineTrack 인터페이스

지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 소스 오브젝트를 취득한다.

구문

HRESULT GetSrcAtTime(
    IAMTimelineObj **ppSrc,
    REFERENCE_TIME Time,
    long SearchDirection
);

파라미터

ppSrc
[out] 소스 오브젝트의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
Time
검색의 시작 타임 (100 나노초단위).
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 열거형의 멤버. 검색의 경계 조건을 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 소스 오브젝트가 발견되지 않았다.
S_OK | 소스 오브젝트가 발견되었다.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

메소드가 S_OK 를 돌려주었을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineTrack::GetSrcAtTime2

IAMTimelineTrack 인터페이스

지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 소스 오브젝트를 취득한다. 이 메소드는 GetSrcAtTime 과 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT GetSrcAtTime2(
    IAMTimelineObj **ppSrc,
    REFTIME Time,
    long SearchDirection
);

파라미터

ppSrc
[out] 소스 오브젝트의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
Time
검색의 시작 타임 (초단위).
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 열거형의 멤버. 검색의 경계 조건을 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 소스 오브젝트가 발견되지 않았다.
S_OK | 소스 오브젝트가 발견되었다.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

IAMTimelineTrack::InsertSpace

IAMTimelineTrack 인터페이스

지정된 시간에 존재하는 모든 오브젝트를 분할해, 그 사이에 스페이스를 삽입한다.

구문

HRESULT InsertSpace(
    REFERENCE_TIME rtStart,
    REFERENCE_TIME rtEnd
);

파라미터

rtStart
분할을 실시하는 시간, 또 삽입되는 스페이스의 시점 (100 나노초단위).
rtEnd
삽입되는 스페이스의 종점 (100 나노초단위).

반환값

HRESULT 값을 돌려준다. 가능한 반환값은 다음과 같다.

S_FALSE | 지정된 시간에 오브젝트는 없다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.

IAMTimelineTrack::InsertSpace2

IAMTimelineTrack 인터페이스

지정된 시간에 존재하는 모든 오브젝트를 분할해, 그 사이에 스페이스를 삽입한다. 이 메소드는 InsertSpace 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT InsertSpace2(
    REFTIME rtStart,
    REFTIME rtEnd
);

파라미터

rtStart
분할을 실시하는 시간, 또 삽입되는 스페이스의 시점 (초단위).
rtEnd
삽입되는 스페이스의 종점 (초단위).

반환값

HRESULT 값을 돌려준다. 가능한 반환값은 다음과 같다.

S_FALSE | 지정된 시간에 오브젝트는 없다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.

IAMTimelineTrack::MoveEverythingBy

IAMTimelineTrack 인터페이스

지정된 시간 이후에 시작하는 모든 오브젝트를, 타임 라인상에서 지정된 거리만 이동한다.

구문

HRESULT MoveEverythingBy(
    REFERENCE_TIME Start,
    REFERENCE_TIME MoveBy
);

파라미터

Start
이동의 시작 타임 (100 나노초단위). 이 시간 이후에 시작 하는 오브젝트만이 이동된다.
MoveBy
타임 라인상에서 오브젝트를 이동하는 시간의 양 (100 나노초단위).

반환값

오브젝트가 이동되었을 경우, S_OK 를 돌려준다. 오브젝트가 이동되지 않았던 경우는, S_FALSE 를 돌려준다.

IAMTimelineTrack::MoveEverythingBy2

IAMTimelineTrack 인터페이스

지정된 시간 이후에 시작하는 모든 오브젝트를, 타임 라인상에서 지정된 거리만 이동한다. 이 메소드는 MoveEverythingBy 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT MoveEverythingBy2(
    REFTIME Start,
    REFTIME MoveBy
);

파라미터

Start
이동의 시작 타임 (초단위). 이 시간 이후에 시작 하는 오브젝트만이 이동된다.
MoveBy
타임 라인상에서 오브젝트를 이동하는 시간의 양 (초단위).

반환값

오브젝트가 이동되었을 경우, S_OK 를 돌려준다. 오브젝트가 이동되지 않았던 경우는, S_FALSE 를 돌려준다.

IAMTimelineTrack::SrcAdd

IAMTimelineTrack 인터페이스

트럭에 소스를 추가한다.

구문

HRESULT SrcAdd(
    IAMTimelineObj *pSrc
);

파라미터

pSrc
소스 오브젝트의 IAMTimelineObj 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 오브젝트가 소스 오브젝트가 아닌 경우, E_NOINTERFACE 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드를 호출하기 전에, 소스의 시작 타임과 종료 타임을 설정한다 (IAMTimelineObj::SetStartStop 를 호출한다).

현재 DES 는, 비디오 압축 매니저 (VCM) CODEC 로 압축된 소스는, 동시에 75 개까지 밖에 렌더링 할 수 없다. 또, 그러한 소스가 프로젝트 전체로 75 개를 넘는 경우는, 동적인 재접속을 사용하지 않으면, DES 는 프로젝트를 프리뷰 할 수 없다. 상세한 것에 대하여는, 「IRenderEngine::SetDynamicReconnectLevel 」를 참조할것.

IAMTimelineTrack::ZeroBetween

IAMTimelineTrack 인터페이스

트럭으로부터, 지정된 시간의 사이에 있는 모든 것을 삭제한다. 이 메소드는, 지정된 시간 범위인가는 모든 오브젝트를 분할해, 그 범위내에 있는 부분을 삭제한다.

구문

HRESULT ZeroBetween(
    REFERENCE_TIME rtStart,
    REFERENCE_TIME rtEnd
);

파라미터

rtStart
클리어 하는 범위의 시점 (100 나노초단위).
rtEnd
클리어 하는 범위의 종점 (100 나노초단위).

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_FALSE | 시간 범위가, 트럭내의 모든 것을 넘고 있다.
S_OK | 성공.

IAMTimelineTrack::ZeroBetween2

IAMTimelineTrack 인터페이스

트럭으로부터, 지정된 시간의 사이에 있는 모든 것을 삭제한다. 이 메소드는 ZeroBetween 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT ZeroBetween2(
    REFTIME rtStart,
    REFTIME rtEnd
);

파라미터

rtStart
클리어 하는 범위의 시점 (초단위).
rtEnd
클리어 하는 범위의 종점 (초단위).

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_FALSE | 시간 범위가, 트럭내의 모든 것을 넘고 있다.
S_OK | 성공.


IAMTimelineTrans 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의 트란지션오브제크트를 조작하는 메소드를 제공한다.

트란지션은, 1 개의 계층과 그것보다 낮은 우선 순위의 모든 계층의 렌더링 된 합성과의 사이에 진행한다. 트란지션을 가질 수가 있는 오브젝트는,IAMTimelineTransable 인터페이스를 이행 한다. 트란지션의 프로퍼티를 설정하려면 ,IPropertySetter 인터페이스를 사용한다. 트란지션의 사용에 대해서는, 「이펙트와 트란지션의 조작」을 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineTrans 메소드 | 설명
GetCutPoint | 컷 포인트를 취득한다.
GetCutPoint2 | GetCutPoint 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.
SetCutPoint | 트란지션이 컷으로서 렌더링 되는 경우의, 트란지션이 한편의 소스로부터 다음의 소스에 바뀌는 시간을 설정한다.
SetCutPoint2 | SetCutPoint 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.
GetSwapInputs | 트란지션의 입력이 스왑 될지 어떨지 가리키는 값을 취득한다.
SetSwapInputs | 트란지션의 입력이 스왑 될지 어떨지를 지정한다.
GetCutsOnly | 트란지션이 컷으로서 렌더링 될지 어떨지를 조사한다.
SetCutsOnly | 트란지션이 컷으로서 렌더링 될지 어떨지를 지정한다.

IAMTimelineTrans::GetCutPoint

IAMTimelineTrans 인터페이스

컷 포인트를 취득한다. 트란지션을 컷 (직접 바꾸고)으로서 렌더링 하는 경우, 컷 포인트는 트란지션이 한편의 소스로부터 다음의 소스에 바뀌는 시간이다. 디폴트에서는, 이 값은 트란지션의 중간점이다. 예를 들어, 1 초간의 트란지션에서는, 디폴트의 컷 포인트는 트란지션의 0.5 초의 위치이다.

구문

HRESULT GetCutPoint(
    REFERENCE_TIME *pTLTime
);

파라미터

pTLTime
트란지션의 시작 타임 상대의 컷 포인트 (100 나노초단위)를 받는 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 컷 포인트는 설정되지 않았다. 돌려주어지는 값은 디폴트값이다.
S_OK | 컷 포인트는 디폴트 이외의 값으로 설정되었다.
E_POINTER | NULL 포인터 인수.

참조

SetCutPoint ,GetCutsOnly ,IAMTimeline::TransitionsEnabled

IAMTimelineTrans::GetCutPoint2

IAMTimelineTrans 인터페이스

컷 포인트를 취득한다. 이 메소드는 GetCutPoint 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT GetCutPoint2(
    REFTIME *pTLTime
);

파라미터

pTLTime
트란지션의 시작 타임 상대의 컷 포인트 (초단위)를 받는 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 컷 포인트는 설정되지 않았다. 돌려주어지는 값은 디폴트값이다.
S_OK | 컷 포인트는 디폴트 이외의 값으로 설정되었다.
E_POINTER | NULL 포인터 인수.

IAMTimelineTrans::GetCutsOnly

IAMTimelineTrans 인터페이스

트란지션이 컷으로서 렌더링 될지 어떨지를 조사한다. 컷으로서 렌더링 되는 경우, 트란지션은 컷 포인트로 즉석에서 행해진다.

구문

HRESULT GetCutsOnly(
    BOOL *pVal
);

파라미터

pVal
트란지션이 컷으로서 렌더링 될지 어떨지를 지정하는 불리언 값을 받는 변수에의 포인터. TRUE 의 경우, 트란지션은 즉시 컷이다. FALSE 의 경우, 트란지션은 보통의 시간폭으로 행해진다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

참조

SetCutsOnly ,GetCutPoint ,IAMTimeline::TransitionsEnabled

IAMTimelineTrans::GetSwapInputs

IAMTimelineTrans 인터페이스

트란지션의 입력이 스왑 될지 어떨지 가리키는 값을 취득한다.

디폴트에서는, 트란지션은 우선 순위의 낮은 계층의 합성으로부터, 트란지션이 존재하는 계층으로 향해 행해진다. 이 진행 방향을 반대로 할 수가 있어 그 경우, 트란지션은 트란지션이 존재하는 계층으로부터, 우선 순위의 낮은 계층의 합성으로 향해 행해진다.

구문

HRESULT GetSwapInputs(
    BOOL *pVal
);

파라미터

pVal
불리언 값을 받는 변수에의 포인터. 이 값이 FALSE 의 경우, 트란지션은 우선 순위의 낮은 모든 계층의 합성으로부터, 그 트란지션이 존재하는 계층으로 향해 행해진다. 이 값이 TRUE 의 경우, 트란지션은 역의 방향으로 행해진다. 디폴트값은 FALSE.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IAMTimelineTrans::SetCutPoint

IAMTimelineTrans 인터페이스

트란지션이 컷으로서 렌더링 되는 경우의, 트란지션이 한편의 소스로부터 다음의 소스에 바뀌는 시간을 설정한다.

구문

HRESULT SetCutPoint(
    REFERENCE_TIME TLTime
)

파라미터

TLTime
트란지션의 시점 상대의 컷 포인트 (100 나노초단위). 이 값이 트란지션의 범위의 밖에 있는 경우, 가장 가까운 유효한 시간으로 설정된다.

반환값

S_OK 를 돌려준다.

주의

디폴트에서는, 컷 포인트는 트란지션의 중간점이다. 예를 들어, 1 초간의 트란지션에서는, 디폴트의 컷 포인트는 트란지션의 0.5 초의 위치이다.

IAMTimelineTrans::SetCutPoint2

IAMTimelineTrans 인터페이스

트란지션이 컷으로서 렌더링 되는 경우의, 트란지션이 한편의 소스로부터 다음의 소스에 바뀌는 시간을 설정한다. 이 메소드는 SetCutPoint 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT SetCutPoint2(
    REFTIME TLTime
)

파라미터

TLTime
트란지션의 시점 상대의 컷 포인트 (초단위).

반환값

S_OK 를 돌려준다.

IAMTimelineTrans::SetCutsOnly

IAMTimelineTrans 인터페이스

트란지션이 컷으로서 렌더링 될지 어떨지를 지정한다. 컷으로서 렌더링 되는 경우, 트란지션은 컷 포인트로 즉석에서 행해진다. 트란지션의 렌더링에 시간이 걸리는 경우, 컷으로서 렌더링 해 프리뷰의 시간을 단축할 수 있다.

구문

HRESULT SetCutsOnly(
    BOOL Val
);

파라미터

Val
트란지션을 컷으로서 렌더링 할지 어떨지를 나타내는 불리언 값. TRUE 의 경우, 트란지션은 즉시 컷으로서 렌더링 된다. FALSE 의 경우, 트란지션은 보통의 시간폭으로 렌더링 된다.

반환값

S_OK 를 돌려준다.

주의

컷으로서의 트란지션의 렌더링은, 입력의 스왑과 호환성이 없다. 상세한 것에 대하여는, 「SetSwapInputs 」를 참조할것. 값 TRUE 를 사용해 SetCutsOnly 를 호출하면, 일시적으로 SetSwapInputs 설정에 오버라이드(override) 한다. 컷만의 설정은 프리뷰를 목적으로 한 것이지만, 이 제한에 의해 파일 출력에는 영향이 없다. 그 때문에, 파일을 기입하기 전에는, 값 FALSE 를 사용해 SetCutsOnly 를 호출하면 기억해 두는 것.

IAMTimelineTrans::SetSwapInputs

IAMTimelineTrans 인터페이스

트란지션의 입력이 스왑 될지 어떨지를 지정한다.

디폴트에서는, 트란지션은 우선 순위의 낮은 계층의 합성으로부터, 트란지션이 존재하는 계층으로 향해 행해진다. 이 진행 방향을 반대로 할 수가 있어 그 경우, 트란지션은 트란지션이 존재하는 계층으로부터, 우선 순위의 낮은 계층의 합성으로 향해 행해진다. 상세한 것에 대하여는, 「트란지션의 방향」을 참조할것.

구문

HRESULT SetSwapInputs(
    BOOL Val
);

파라미터

Val
트란지션의 입력이 스왑 될지 어떨지를 지정하는 불리언 값. 이 값이 FALSE 의 경우, 트란지션은 우선 순위의 낮은 모든 계층의 합성으로부터, 그 트란지션이 존재하는 계층으로 향해 행해진다. 이 값이 TRUE 의 경우, 트란지션은 역의 방향으로 행해진다.

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 비주얼 이펙트의 방향은 변경하지 않는다. 예를 들어, 왼쪽에서 오른쪽에의 와이프는, 왼쪽에서 오른쪽에 행해진다. 그 방향을 변경하려면 ,IPropertySetter 인터페이스를 사용해 Progress 프로퍼티를 설정한다.


IAMTimelineTransable 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의 오브젝트에 트란지션을 추가한다. 이 인터페이스는, 적용되는 트란지션을 가질 수가 있는 오브젝트에 의해 공개된다. 그러한 오브젝트에는,트럭,합성, 및그룹이 포함된다. 이 인터페이스를 이행 하고 있는 오브젝트는 트란지션을 몇개에서도 가질 수가 있지만, 그 시간을 오버랩 시킬 수 없다.

주 : 오디오는 트란지션을 지원 하고 있지 않다. 오디오 그룹내의 오브젝트는,IAMTimelineTransable 인터페이스를 공개할 수 있지만, 어플리케이션에서는 그 오브젝트에 트란지션을 추가해서는 안 된다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineTransable 메소드 | 설명
TransAdd | 오브젝트에 트란지션을 추가한다.
TransGetCount | 이 오브젝트의 트란지션의 개수를 취득한다.
GetNextTrans | 지정된 시간 이후에 시작하는 최초의 트란지션을 검색한다.
GetNextTrans2 | GetNextTrans 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.
GetTransAtTime | 지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 트란지션을 취득한다.
GetTransAtTime2 | GetTransAtTime 와 같은 기능이지만, REFTIME 값을 파라미터에 있다.

IAMTimelineTransable::GetNextTrans

IAMTimelineTransable 인터페이스

지정된 시간 이후에 시작하는 최초의 트란지션을 검색한다.

구문

HRESULT GetNextTrans(
    IAMTimelineObj **ppTrans,
    REFERENCE_TIME *pInOut
);

파라미터

ppTrans
[out] 트란지션오브제크트의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
pInOut
시간 (100 나노초단위)을 지정하는 변수에의 포인터. 입력으로는, 이 값은 트란지션의 검색을 시작 할 시간을 지정한다. 출력으로는, 트란지션이 취득되었을 경우, 이 값은 그 트란지션의 종료 타임으로 설정된다.

반환값

이 메소드는, 트란지션을 취득했을 경우는, S_OK 를 돌려준다. 트란지션이 발견되지 않았던 경우는, S_FALSE 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

트란지션의 시작 타임은,pInOut 로 지정하는 시간에 걸려 있으면, 지정 시간보다 작고 상관없다.

메소드가 S_OK 를 돌려주었을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineTransable::GetNextTrans2

IAMTimelineTransable 인터페이스

지정된 시간 이후에 시작하는 최초의 트란지션을 검색한다. 이 메소드는 GetNextTrans 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT GetNextTrans2(
    IAMTimelineObj **ppTrans,
    REFTIME *pInOut
);

파라미터

ppTrans
[out] 트란지션오브제크트의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
pInOut
시간 (초단위)을 지정하는 변수에의 포인터. 입력으로는, 이 값은 트란지션의 검색을 시작 할 시간을 지정한다. 출력으로는, 트란지션이 취득되었을 경우, 이 값은 그 트란지션의 종료 타임으로 설정된다.

반환값

이 메소드는, 트란지션을 취득했을 경우는, S_OK 를 돌려준다. 트란지션이 발견되지 않았던 경우는, S_FALSE 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

IAMTimelineTransable::GetTransAtTime

IAMTimelineTransable 인터페이스

지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 트란지션을 취득한다.

구문

HRESULT GetTransAtTime(
    IAMTimelineObj **ppObj,
    REFERENCE_TIME Time,
    long SearchDirection
);

파라미터

ppObj
[out] 트란지션의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
Time
검색을 시작 할 시간 (100 나노초단위).
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 열거형의 멤버. 검색의 경계 조건을 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 트란지션은 발견되지 않았다.
S_OK | 트란지션이 발견되었다.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

메소드가 S_OK 를 돌려주었을 경우, 돌려주어지는 IAMTimelineObj 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IAMTimelineTransable::GetTransAtTime2

IAMTimelineTransable 인터페이스

지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 트란지션을 취득한다. 이 메소드는 GetTransAtTime 와 같은 기능이지만,REFTIME 값을 파라미터에 있다.

구문

HRESULT GetTransAtTime2(
    IAMTimelineObj **ppObj,
    REFTIME Time,
    long SearchDirection
);

파라미터

ppObj
[out] 트란지션의 IAMTimelineObj 인터페이스를 받는 포인터의 주소.
Time
검색을 시작 할 시간 (초단위).
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 열거형의 멤버. 검색의 경계 조건을 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 트란지션은 발견되지 않았다.
S_OK | 트란지션이 발견되었다.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

IAMTimelineTransable::TransAdd

IAMTimelineTransable 인터페이스

오브젝트에 트란지션을 추가한다. 오브젝트는 복수의 트란지션을 가질 수가 있지만, 그 시간이 오버랩 해서는 안 된다. 트란지션은, 오브젝트의 시간 경계내에 들어가지 않으면 안 된다.

구문

HRESULT TransAdd(
    IAMTimelineObj *pTrans
);

파라미터

pTrans
추가하는 트란지션의 IAMTimelineObj 인터페이스의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 트란지션을 삽입할 수 없다.
E_NOINTERFACE | pTrans 는, 트란지션에의 포인터는 아니다.

주의

삽입하는 트란지션이 기존의 트란지션에 오버랩 하는 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.

IAMTimelineTransable::TransGetCount

IAMTimelineTransable 인터페이스

이 오브젝트의 트란지션의 개수를 취득한다.

구문

HRESULT TransGetCount(
    long *pCount
);

파라미터

pCount
트란지션의 수를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.


IAMTimelineVirtualTrack 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의가상 트럭을 조작하는 메소드를 제공한다. 합성 및트럭은, 이 인터페이스를 지원 한다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimelineVirtualTrack 메소드 | 설명
TrackGetPriority | 오브젝트의 우선 순위 레벨을 취득한다.
SetTrackDirty | 지원되어 있지 않다.

IAMTimelineVirtualTrack::SetTrackDirty

IAMTimelineVirtualTrack 인터페이스

지원되어 있지 않다.

구문

HRESULT SetTrackDirty( void );

IAMTimelineVirtualTrack::TrackGetPriority

IAMTimelineVirtualTrack 인터페이스

오브젝트의 우선 순위 레벨을 취득한다.

구문

HRESULT TrackGetPriority(
    long *pPriority
);

파라미터

pPriority
우선 순위 레벨을 받는 변수에의 포인터. 오브젝트가 타임 라인이 일부에서 없는 경우, 값은 -1 으로 설정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.


IFindCompressorCB 인터페이스

이 인터페이스는, 어플리케이션이 특정의 미디어 타입의 압력을 지정할 수 있는 콜백 메소드를 제공한다.

주 : 이 인터페이스 (스마트 렌더링 엔진)를 사용하도록(듯이) 설계된 컴퍼넌트는, 현재는 그 설계와 같이 이행되어 있지 않다.

스마트재압축을 실시하려면 , 렌더링 엔진은 올바른 압축 필터를 찾아낼 수 없으면 안 된다. IFindCompressorCB 인터페이스는, 어플리케이션이 압력을 선택하는 수단이다. 이 인터페이스를 사용하려면 , 우선 어플리케이션으로 이 인터페이스를 이행 한다. 다음에,ISmartRenderEngine::SetFindCompressorCB 메소드를 호출하는 것으로, 이 인터페이스에의 포인터를 렌더링 엔진에게 준다.

주 : 미리 타임 라인 그룹이 사용해야 하는 압력을 알 수 있고 있는 경우, 보다 직접인 방법으로서 압력에의 포인터를 지정해 ISmartRenderEngine::SetGroupCompressor 메소드를 호출할 수가 있다. 또, 어플리케이션으로 지정되어 있지 않은 경우, 렌더링 엔진은 적절한 압력을 검색한다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFindCompressorCB 메소드 | 설명
GetCompressor | 지정된 미디어 타입용의 압력을 취득한다.

IFindCompressorCB::GetCompressor

IFindCompressorCB 인터페이스

지정된 미디어 타입용의 압력을 취득한다.

구문

HRESULT GetCompressor(
    AM_MEDIA_TYPE *pType,
    AM_MEDIA_TYPE *pCompType,
    IBaseFilter **ppFilter
);

파라미터

pType
비압축의 미디어 타입을 기술하는 AM_MEDIA_TYPE 구조체에의 포인터.
pCompType
압축 포맷을 기술하는 AM_MEDIA_TYPE 구조체에의 포인터.
ppFilter
[out] 압축 필터의 IBaseFilter 인터페이스에의 포인터를 받는 변수의 주소. 실패했을 경우, 이 메소드는 이 포인터에 NULL 를 설정한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 이행에 응한 에러 코드를 돌려준다.


IMediaDet 인터페이스

미디어 파일에 관해서, 스트림의 수, 타입, 시간폭, 각 스트림의 frame rate등의 정보를 취득한다. 이 인터페이스에는, 비디오 스트림으로부터 포스터 프레임을 취득하는 메소드도 포함되어 있다. 미디어 detector는, 이 인터페이스를 공개한다. 이 인터페이스는, Microsoft® DirectShow® 편집 서비스 (DES)로 사용한다.

파일에 관한 정보를 취득하려면 , 이하의 순서를 실행한다.

  1. CoCreateInstance 를 호출하는 것으로, 미디어 detector의 인스턴스를 생성 한다. 클래스 ID 는 CLSID_MediaDet 이다.
  2. put_Filename 를 호출해, 원시 파일의 이름을 지정한다 (다른 방법으로서put_Filter 를 호출한다).
  3. get_OutputStreams 를 호출해, 소스내의 출력 스트림의 개수를 취득한다.
  4. put_CurrentStream 를 호출해, 특정의 스트림을 지정한다.
  5. 다음의 임의의 메소드를 호출한다. get_StreamType ,get_StreamMediaType ,get_StreamLength , 또는 get_FrameRate .

포스터 프레임을 꺼내려면 ,GetBitmapBits 또는 WriteBitmapBits 를 호출한다. 다른 방법으로서EnterBitmapGrabMode 를 호출한 후,GetSampleGrabber 를 호출해 ISampleGrabber 인터페이스에의 포인터를 취득한다. 이러한 3 개의 메소드는 모두, 미디어 detector를비트 맵 글로브 모드라고 하는 새로운 모드로 설정한다. 전술의 정보 취득 메소드는, 이 모드에서는 동작하지 않는다. 그 때문에, 정보의 취득은 포스터 프레임의 취득전에 실시할 필요가 있다. 그렇지 않은 경우는, 스트림 마다 미디어 detector의 새로운 인스턴스를 생성 하게 된다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaDet 인터페이스 | 설명
get_Filter | 미디어 detector가 현재 사용하고 있는 소스 필터에의 포인터를 취득한다.
put_Filter | 미디어 detector로 사용하는 소스 필터를 지정한다.
get_OutputStreams | 미디어 소스에 포함되는 출력 스트림의 개수를 취득한다.
get_CurrentStream | 미디어 detector가 현재 사용하고 있는 스트림 번호를 취득한다.
put_CurrentStream | 미디어 detector로 사용하는 스트림 번호를 지정한다.
get_StreamType | 현재의 스트림의 미디어 타입의 글로벌 유니크 식별자 (GUID)를 취득한다.
get_StreamTypeB | 현재의 스트림의 미디어 타입의 GUID 를 나타내는 캐릭터 라인을 취득한다.
get_StreamLength | 현재의 스트림의 시간폭을 취득한다.
get_Filename | 미디어 detector가 현재 사용하고 있는 원시 파일의 이름을 취득한다.
put_Filename | 미디어 detector로 사용하는 원시 파일의 이름을 지정한다.
GetBitmapBits | 지정된 미디어 타임의 포스터 프레임을 취득한다.
WriteBitmapBits | 지정된 미디어 타임의 포스터 프레임을 취득해, 그것을 파일에 기입한다.
get_StreamMediaType | 현재의 스트림의 미디어 타입을 취득한다.
GetSampleGrabber | ISampleGrabber 인터페이스에의 포인터를 취득한다.
get_FrameRate | 현재의 스트림의 frame rate를 취득한다.
EnterBitmapGrabMode | 미디어 detector를 비트 맵 글로브 모드로 전환해 필터 그래프의 지정의 시간을 시크 한다.

IMediaDet::EnterBitmapGrabMode

IMediaDet 인터페이스

미디어 detector를 비트 맵 글로브 모드로 전환해 필터 그래프의 지정의 시간을 시크 한다.

구문

HRESULT EnterBitmapGrabMode(
    double StreamTime
);

파라미터

StreamTime
그래프를 시크 할 시간 (초단위).

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
VFW_E_INVALIDMEDIATYPE | 파일은 비디오 스트림을 가지고 있지 않다.
VFW_E_TIME_EXPIRED | 시크 할 수 없었다.

주의

이 메소드를 호출하기 전에,put_Filename 및 put_CurrentStream 를 호출해 파일명과 스트림을 설정한다.

이 메소드는,샘플 grabber 필터를 필터 그래프에 삽입한다. 그것에 의해,GetSampleGrabber 를 호출해 ISampleGrabber 인터페이스에의 포인터를 취득할 수 있다. 미디어 detector가 비트 맵 글로브 모드에 들어가고 나서는,IMediaDet 의 각종의 정보 취득 메소드는 기능하지 않는다.

GetBitmapBits 및 WriteBitmapBits 메소드도, 미디어 detector를 비트 맵 글로브 모드로 설정한다.

IMediaDet::GetBitmapBits

IMediaDet 인터페이스

지정된 미디어 타임의 포스터 프레임을 취득한다.

구문

HRESULT GetBitmapBits(
    double StreamTime,
    long *pBufferSize,
    char *pBuffer,
    long Width,
    long Height
);

파라미터

StreamTime
포스터 프레임을 취득하는 시간.
pBufferSize
필요한 버퍼 사이즈를 받는 변수에의 포인터. pBuffer 가 NULL 의 경우, 이 변수는 포스터 프레임의 취득에 필요한 버퍼의 사이즈를 받는다. pBuffer 가 NULL 가 아닌 경우, 이 파라미터는 무시된다.
pBuffer
포스터 프레임을 받는 버퍼에의 포인터.
Width
포스터 프레임 이미지의 폭 (픽셀 단위).
Height
포스터 프레임 이미지의 높이 (픽셀 단위).

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
E_NOINTERFACE | 샘플 grabber 필터를 그래프에 추가할 수 없었다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 에러.
E_UNEXPECTED | 예기치 못한 에러.
VFW_E_INVALIDMEDIATYPE | 무효인 미디어 타입.

주의

이 메소드를 호출하기 전에,put_Filename 및 put_CurrentStream 를 호출해 파일명과 스트림을 설정한다.

필요한 버퍼의 사이즈를 결정하려면 ,pBuffer 를 NULL 로 해 이 메소드를 호출한다. 사이즈는,pBufferSize 가 가리키는 변수에 돌려주어진다. 그리고, 버퍼를 생성 해, 재차 이 메소드를 호출한다. 그 예를 다음의 코드에 나타낸다.

long BufferSize = 0;
GetBitmapBits(StreamTime, &BufferSize, NULL, Width, Height);
char *pBuffer = new char[BufferSize];
GetBitmapBits(StreamTime, 0, pBuffer, Width, Height);

이 메소드는, 미디어 detector를 비트 맵 글로브 모드로 설정한다. 이 메소드가 불려 간 후는, 미디어 detector의 새로운 인스턴스를 생성 하지 않으면,IMediaDet 의 각종의 스트림 정보 취득 메소드는 기능하지 않는다.

IMediaDet::get_CurrentStream

IMediaDet 인터페이스

미디어 detector가 현재 사용하고 있는 스트림 번호를 취득한다.

구문

HRESULT get_CurrentStream(
    long *pVal
);

파라미터

pVal
[out, retval] 현재의 스트림 번호를 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_POINTER 를 돌려준다.

IMediaDet::get_Filename

IMediaDet 인터페이스

미디어 detector가 현재 사용하고 있는 원시 파일의 이름을 취득한다.

구문

HRESULT get_Filename(
    BSTR *pVal
);

파라미터

pVal
[out, retval] 파일명을 받는 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는, 캐릭터 라인에 필요한 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

IMediaDet::get_Filter

IMediaDet 인터페이스

미디어 detector가 현재 사용하고 있는 소스 필터에의 포인터를 취득한다.

구문

HRESULT get_Filter(
    IUnknown **ppVal
);

파라미터

ppVal
[out, retval] 필터의 IUnknown 인터페이스를 받는 포인터의 주소. 사용되고 있는 소스 필터가 없는 경우, 값은 NULL 로 설정된다.

반환값

HRESULT 값을 돌려준다.

주의

메소드가 복귀했을 때에 *ppVal 가 NULL 이외의 경우,IUnknown 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IMediaDet::get_FrameRate

IMediaDet 인터페이스

현재의 스트림의 frame rate를 취득한다. 이 스트림은, 비디오 스트림이 아니면 안된다.

구문

HRESULT get_FrameRate(
    double *pVal
);

파라미터

pVal
[out, retval] frame rate (매초의 프레임수)를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_FALSE | 비디오 포맷 헤더로 frame rate가 지정되어 있지 않다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.
VFW_E_INVALIDMEDIATYPE | 무효인 미디어 타입.

주의

이 메소드는, ASF 파일로부터는 frame rate를 취득할 수 없다.

이 메소드를 호출하기 전에,put_Filename 및 put_CurrentStream 를 호출해 파일명과 스트림을 설정한다.

미디어 detector가 비트 맵 글로브 모드의 경우, 이 메소드는 E_INVALIDARG 를 돌려준다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

IMediaDet::get_OutputStreams

IMediaDet 인터페이스

미디어 소스에 포함되는 출력 스트림의 개수를 취득한다.

구문

HRESULT get_OutputStreams(
    long *pVal
);

파라미터

pVal
[out, retval] 출력 스트림의 개수를 받는 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

이 메소드를 호출하기 전에,put_Filename 를 호출해 파일명을 설정한다.

미디어 detector가 비트 맵 글로브 모드의 경우, 이 메소드는 E_INVALIDARG 를 돌려준다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

IMediaDet::GetSampleGrabber

IMediaDet 인터페이스

ISampleGrabber 인터페이스에의 포인터를 취득한다. 이 인터페이스에 의해, 어플리케이션으로 미디어 스트림으로부터 개개의 샘플을 취득할 수 있다.

구문

HRESULT GetSampleGrabber(
    ISampleGrabber **ppVal
);

파라미터

ppVal
[out] ISampleGrabber 인터페이스를 받는 포인터의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_NOINTERFACE | 미디어 detector가 비트 맵 글로브 모드이기 (위해)때문에, 인터페이스를 취득할 수 없다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드를 호출하기 전에,EnterBitmapGrabMode 를 호출한다. ISampleGrabber 인터페이스에 의해, 스트림으로부터 개개의 미디어 샘플을 취득할 수가 있다. 포스터 프레임용의 비트 맵이 필요한 만큼의 경우는, 대신에 IMediaDet::GetBitmapBits 메소드를 호출한다. ISampleGrabber 인터페이스가 유연성은 있지만, 어플리케이션측에서 필요한 처리도 많아진다.

이 메소드가 성공했을 경우, 돌려주어지는 ISampleGrabber 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IMediaDet::get_StreamLength

IMediaDet 인터페이스

현재의 스트림의 시간폭을 취득한다.

구문

HRESULT get_StreamLength(
    double *pVal
);

파라미터

pVal
[out, retval] 스트림의 시간폭 (초단위)을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

이 메소드를 호출하기 전에,put_Filename 및 put_CurrentStream 를 호출해 파일명과 스트림을 설정한다.

미디어 detector가 비트 맵 글로브 모드의 경우, 이 메소드는 E_INVALIDARG 를 돌려준다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

IMediaDet::get_StreamMediaType

IMediaDet 인터페이스

현재의 스트림의 미디어 타입을 취득한다.

구문

HRESULT get_StreamMediaType(
    AM_MEDIA_TYPE *pVal
);

파라미터

pVal
[out, retval] 이 미디어 타입이 설정되어 있는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

이 메소드를 호출하기 전에,put_Filename 및 put_CurrentStream 를 호출해 파일명과 스트림을 설정한다.

미디어 detector가 비트 맵 글로브 모드의 경우, 이 메소드는 E_INVALIDARG 를 돌려준다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

IMediaDet::get_StreamType

IMediaDet 인터페이스

현재의 스트림의 미디어 타입의 글로벌 유니크 식별자 (GUID)를 취득한다.

구문

HRESULT get_StreamType(
    GUID *pVal
);

파라미터

pVal
[out, retval] 미디어 타입의메이저 타입 GUID 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는,AM_MEDIA_TYPE 구조체의 majortype 멤버를 취득한다. AM_MEDIA_TYPE 구조체는 스트림의 포맷을 기술해,majortype 멤버는 오디오나 비디오등의 범용 카테고리를 나타내는 GUID 이다. 비디오 스트림의 경우, GUID 는 MEDIATYPE_Video 이다. 오디오의 경우는, MEDIATYPE_Audio 이다. AM_MEDIA_TYPE 구조체 전체를 취득하려면 ,get_StreamMediaType 메소드를 호출한다.

이 메소드를 호출하기 전에,put_Filename 및 put_CurrentStream 를 호출해 파일명과 스트림을 설정한다.

미디어 detector가 비트 맵 글로브 모드의 경우, 이 메소드는 E_INVALIDARG 를 돌려준다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

IMediaDet::get_StreamTypeB

IMediaDet 인터페이스

현재의 스트림의 미디어 타입의 GUID 를 나타내는 캐릭터 라인을 취득한다.

구문

HRESULT get_StreamTypeB(
    BSTR *pVal
);

파라미터

pVal
[out, retval] 미디어 타입 GUID 의 캐릭터 라인 표현을 받아들이는 BSTR 에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

돌려주어지는 BSTR 는 다음과 같은 포맷이다. {73647561-0000-0010-8000-00AA00389B71}

이 메소드는, 캐릭터 라인에 필요한 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

이 메소드를 호출하기 전에,put_Filename 및 put_CurrentStream 를 호출해 파일명과 스트림을 설정한다.

미디어 detector가 비트 맵 글로브 모드의 경우, 이 메소드는 E_INVALIDARG 를 돌려준다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

IMediaDet::put_CurrentStream

IMediaDet 인터페이스

미디어 detector로 사용하는 스트림 번호를 지정한다.

구문

HRESULT put_CurrentStream(
    long newVal
);

파라미터

newVal
[in] 스트림 번호.

반환값

성공했을 경우는 S_OK, 그 이외의 경우는 E_INVALIDARG 를 돌려준다.

주의

이 메소드를 호출하기 전에,put_Filename 를 호출해 파일명을 설정한다. get_OutputStreams 를 호출해, 원시 파일에 포함되는 스트림의 개수를 조사한다.

미디어 detector가 비트 맵 글로브 모드의 경우, 이 메소드는 E_INVALIDARG 를 돌려준다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

IMediaDet::put_Filename

IMediaDet 인터페이스

미디어 detector로 사용하는 원시 파일의 이름을 지정한다.

구문

HRESULT put_Filename(
    BSTR newVal
);

파라미터

newVal
[in] 소스의 파일명.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 HRESULT 값을 돌려준다.

IMediaDet::put_Filter

IMediaDet 인터페이스

미디어 detector로 사용하는 소스 필터를 지정한다.

구문

HRESULT put_Filter(
    IUnknown *newVal
);

파라미터

newVal
[in] 소스 필터의 IUnknown 인터페이스를 가리키는 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
E_NOINTERFACE | newVal 는 필터를 가리키지 않았다.
E_POINTER | NULL 포인터 인수.

주의

어플리케이션에서는,put_Filename 를 호출하는 대신에, 소스 필터의 IUnknown 인터페이스에의 포인터를 지정해 이 메소드를 호출할 수가 있다. 이미 필터 그래프에 접속되고 있는 필터를 사용해서는 안 된다.

IMediaDet::WriteBitmapBits

IMediaDet 인터페이스

지정된 미디어 타임의 포스터 프레임을 취득해, 그것을 파일에 기입한다.

구문

HRESULT WriteBitmapBits(
    double StreamTime,
    long Width,
    long Height,
    BSTR Filename
);

파라미터

StreamTime
포스터 프레임을 취득하는 시간.
Width
포스터 프레임 이미지의 폭 (픽셀 단위).
Height
포스터 프레임 이미지의 높이 (픽셀 단위).
Filename
포스터 프레임을 보존하는 파일의 패스. 파일이 이미 존재하는 경우, 이 메소드는 그 파일에 오버라이드(override) 한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 HRESULT 값을 돌려준다. 가능한 에러 코드는 다음과 같다.

E_NOINTERFACE | 샘플 grabber 필터를 그래프에 추가할 수 없었다.
E_FAIL | 실패.
E_OUTOFMEMORY | 메모리 부족.
E_UNEXPECTED | 예기치 못한 에러.
STG_E_ACCESSDENIED | 파일을 오버라이드(override) 할 수 없다.
VFW_E_INVALIDMEDIATYPE | 무효인 미디어 타입.

주의

이 메소드를 호출하기 전에,put_Filename 및 put_CurrentStream 를 호출해 파일명과 스트림을 설정한다.

이 메소드는, 미디어 detector를 비트 맵 글로브 모드로 설정한다. 이 메소드가 불려 간 후는, 미디어 detector의 새로운 인스턴스를 생성 하지 않으면,IMediaDet 의 각종의 스트림 정보 취득 메소드는 기능하지 않는다.


IMediaLocator 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)로 파일명의 타당성을 검증하기 위한 메소드를 제공한다. 이 인터페이스를 사용해, 주어진 파일명 및 패스가 기존의 파일에 대응하고 있는 것을 확인한다. 이 인터페이스는, 다른 장소에 있는 파일을 검색하는 수단, 및 [여는] 다이알로그 박스를 표시해 유저가 파일을 찾을 수 있도록(듯이) 하는 수단도 제공한다.

미디어 locator는, 이 인터페이스를 이행 하고 있다. 타임 라인 및 렌더링 엔진도, 이하의 메소드에 의해 파일명의 검증을 지원 하고 있다.

  • IAMTimeline::ValidateSourceNames : 타임 라인내의 파일명을 검증 및 갱신한다.
  • IRenderEngine::SetSourceNameValidation : 렌더링 엔진이 렌더링시에 파일명을 검증하는 방법을 지정한다.

DES 어플리케이션에서는, 보통은 이러한 메소드를 호출해, 미디어 locator의 인스턴스를 직접 생성 할 것은 없다. 상세한 것에 대하여는, 「미디어 locator의 사용법」을 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaLocator 메소드 | 설명
FindMediaFile | 파일을 검색해, 성공했을 경우는, 그 파일에의 패스를 취득한다.
AddFoundLocation | 디렉토리 캐쉬에 디렉토리를 추가한다.

IMediaLocator::AddFoundLocation

IMediaLocator 인터페이스

디렉토리 캐쉬에 디렉토리를 추가한다.

구문

HRESULT AddFoundLocation(
    BSTR DirectoryName
);

파라미터

DirectoryName
캐쉬에 추가하는 디렉토리 패스.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 HRESULT 값을 돌려준다.

주의

미디어 locator는, 과거의 검색으로 파일이 발견된 디렉토리 패스의 캐쉬를 유지한다. 파일이 발견되었을 경우는, 그 디렉토리를 캐쉬에 추가한다.

IMediaLocator::FindMediaFile

IMediaLocator 인터페이스

파일을 검색해, 성공했을 경우는, 그 파일에의 패스를 취득한다.

구문

HRESULT FindMediaFile(
    BSTR Input,
    BSTR FilterString,
    BSTR *pOutput,
    long Flags
);

파라미터

Input
파일명. 그 파일이 존재하고 있던 것을 알 수 있고 있는 패스도 포함한다. 타임 라인내의 소스 오브젝트의 경우는, 현재의 미디어명을 사용한다.
FilterString
Microsoft® Win32® 의 OPENFILENAME 구조체의 lpstrFilter 멤버로 필요한 서식으로 설정된 필터 캐릭터 라인의 페어를 포함한 BSTR. 미디어 locator는,[여는] 다이알로그 박스를 표시하는 경우에, 이 필터를 사용한다. Flags 파라미터에 SFN_VALIDATEF_POPUP 플래그가 포함되지 않은 경우, 이 값은 NULL 로 할 수가 있다.
pOutput
파일에의 실제의 패스가 Input 내의 값과 다른 경우, 및 메소드를 파일을 찾아낼 수 있었을 경우, 파일의 실제의 패스를 받는 변수에의 포인터.
Flags
이하의 플래그의 0 개 이상의 비트마다의 편성.
  • SFN_VALIDATEF_NOFIND
  • SFN_VALIDATEF_POPUP
  • SFN_VALIDATEF_TELLME
  • SFN_VALIDATEF_USELOCAL

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_FALSE | 파일은 다른 장소에서 발견되었다.
S_OK | 파일은 지정된 장소에서 발견되었다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_POINTER | NULL 포인터 인수.

주의

FilterString 파라미터에 의해 지정되는,[여는] 다이알로그 박스의 필터 캐릭터 라인에는, 내부적인 NULL 캐릭터 라인이 포함된다. 예를 들어,Video\0*.avi\0\0 는 유효한 필터 캐릭터 라인이다. SysAllocStr 함수를 사용해 BSTR 를 할당할 수 없다. 이 함수는, NULL 에 의해 종료하는 캐릭터 라인을 상정하고 있어, 최초의 NULL 문자로 캐릭터 라인을 잘라 버리기 때문에 있다. 그 때문에,SysAllocStringLen 등, 길이에 맞은 명시적인 파라미터가 포함된 함수를 사용하는 것.

BSTR filter = SysAllocStringLen(L"Video\0*.avi\0\0", 13);

유저가 [열리는] 다이알로그 박스를 캔슬 하면, 메소드는 E_FAIL 를 돌려준다.

이 메소드는,pOutput 의 BSTR 에 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.


IPropertySetter 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의 이펙트 또는 트란지션의 프로퍼티를 설정한다.

이 인터페이스를 사용하려면 , 프로파티셋타오브제크트 (CLSID_PropertySetter)의 인스턴스를 생성 해,IAMTimelineObj::SetPropertySetter 메소드를 호출하는 것으로, 그 인스턴스에 이펙트 또는 트란지션을 관련짓는다. 상세한 것에 대하여는, 「이펙트와 트란지션의 조작」을 참조할것.

보통, 어플리케이션에서는 ClearProps 메소드를 호출해 기존의 프로퍼티를 클리어 해,AddProp 메소드를 호출해 새로운 프로퍼티를 추가하는 것만으로 좋다. 이 인터페이스의 다른 메소드는, 다른 DES 컴퍼넌트에 의해 불려 간다.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IPropertySetter 메소드 | 설명
LoadXML | 확장 가능 마크업 언어 (XML)로 표현된 프로퍼티 데이터를 로드한다.
PrintXML | 프로퍼티 데이터를 XML 캐릭터 라인으로 변환한다.
CloneProps | 이 프로파티셋타로부터 프로퍼티세트의 복제를 생성 해, 새로운 프로파티셋타에 추가한다.
AddProp | 프로퍼티가 적용되는 시간의 범위를 정의하는 타임값페어의 배열과 함께, 프로퍼티를 프로파티셋타에 추가한다.
GetProps | 이 오브젝트의 프로퍼티 세트를, 대응하는 값과 함께 취득한다.
FreeProps | GetProps 메소드에 의해 할당할 수 있었던 리소스를 해방한다.
ClearProps | 프로파티셋타로부터, 모든 프로퍼티 데이터를 클리어 한다.
SaveToBlob | 프로퍼티 데이터를 영속성 포맷에 보존한다.
LoadFromBlob | 영속성 포맷화등 프로퍼티 데이터를 로드한다.
SetProps | 타겟 오브젝트의 프로퍼티를, 지정된 시간의 적절한 상태로 설정한다.

IPropertySetter::AddProp

IPropertySetter 인터페이스

프로퍼티가 적용되는 시간의 범위를 정의하는 타임값페어의 배열과 함께, 프로퍼티를 프로파티셋타에 추가한다.

구문

HRESULT AddProp(
    DEXTER_PARAM Param,
    DEXTER_VALUE *paValue
);

파라미터

Param
[in] 프로퍼티를 지정하는 DEXTER_PARAM 구조체. 이 구조체의 nValues 멤버는,paValue 파라미터로 건네받는 배열의 사이즈와 동일하지 않으면 안 된다.
paValue
[in] 타임값페어를 보관 유지하는 DEXTER_VALUE 구조체의 배열에의 포인터. 이 배열내의 시간은, 승순으로 나란해지지 않으면 안 된다. 이 시간은, 이펙트 또는 트란지션의 시작 타임 상대이다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

최초의 DEXTER_VALUE 구조체는, 제로의 기준 타임 및 DEXTERF_JUMP 의 보간 플래그 (dwInterp)를 지정해야 한다. 그렇지 않은 경우, 메소드는 에러를 돌려준다.

IPropertySetter::ClearProps

IPropertySetter 인터페이스

프로파티셋타로부터, 모든 프로퍼티 데이터를 클리어 한다. 어플리케이션에서는, 이 함수의 호출 후에, 새로운 프로퍼티 데이터를 설정할 수 있다.

구문

HRESULT ClearProps( void );

반환값

S_OK 를 돌려준다.

IPropertySetter::CloneProps

IPropertySetter 인터페이스

이 프로파티셋타로부터 프로퍼티세트의 복제를 생성 해, 새로운 프로파티셋타에 추가한다.

구문

HRESULT CloneProps(
    IPropertySetter **ppSetter,
    REFERENCE_TIME rtStart,
    REFERENCE_TIME rtStop
);

파라미터

ppSetter
[out] 새로운 프로파티셋타의 IPropertySetter 인터페이스를 받는 포인터의 주소.
rtStart
복제하는 값의 범위의 시작 타임 (100 나노초단위).
rtStop
[in] 예약이 끝난 상태.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 HRESULT 값을 돌려준다. 가능한 에러 코드는 다음과 같다.

E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

지정된 시작 타임보다 후의 값만이 복제된다. 복제된 값의 시간은, 시작 타임 상대에 조정된다. 예를 들어,rtStart 가 20000000 (2 초)의 경우, 타임 30000000 (3 초)의 값은, 복제되면(자) 타임 10000000 (1 초)이 된다. 마지막으로, 복제된 각 프로퍼티에는, 시작 타임의 원의 프로퍼티의 값에 동일한 초기값이 주어진다 (필요하면 적절한 보간을 한다). 실질적으로, 프로퍼티 데이터는 지정된 시작 타임에 분할된다.

메소드가 성공했을 경우, 돌려주어지는 IPropertySetter 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IPropertySetter::FreeProps

IPropertySetter 인터페이스

GetProps 메소드에 의해 할당할 수 있었던 리소스를 해방한다. GetProps 를 호출한 다음에 이 메소드를 호출해,GetProps 에 의해 돌려주어진 구조체를 건네준다.

구문

HRESULT FreeProps(
    LONG cParams,
    DEXTER_PARAM *paParam,
    DEXTER_VALUE *paValue
);

파라미터

cParams
[in] paParam 파라미터로 주어지는 배열의 사이즈를 지정하는 값.
paParam
[in] DEXTER_PARAM 구조체의 배열에의 포인터.
paValue
[in] DEXTER_VALUE 구조체의 배열에의 포인터.

반환값

S_OK 를 돌려준다.

IPropertySetter::GetProps

IPropertySetter 인터페이스

이 오브젝트의 프로퍼티 세트를, 대응하는 값과 함께 취득한다.

구문

HRESULT GetProps(
    LONG *pcParams,
    DEXTER_PARAM **paParam,
    DEXTER_VALUE **paValue
);

파라미터

pcParams
[out] paParam 에 돌려주어지는 구조체의 개수를 받는 변수에의 포인터.
paParam
[in] DEXTER_PARAM 구조체의 배열에의 포인터의 주소.
paValue
[in] DEXTER_VALUE 구조체의 배열에의 포인터의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

paParam 에 돌려주어지는 각 프로퍼티 마다,nValues 멤버는 그 프로퍼티에 관련지을 수 있고 있는 DEXTER_VALUE 구조체의 개수를 나타낸다. 이러한 페어는, 각 프로퍼티 마다 시간의 승순으로 돌려주어진다.

예를 들어, 다음의 샘플 코드는, 모든 값을 반복 처리 하는 방법을 나타내고 있다.

DEXTER_PARAM *pParam;
DEXTER_VALUE *pValue;
LONG count;

hr = pSetter->GetProps(&count, &pParam, &pValue);

LONG num = 0;
for (LONG i = 0; i < count; i++)
{
    for (LONG j = 0; j < pParam[i]. nValues; j++)
    {
        // pValue[num] 는, pParam[i] 의 순서내의 다음의 값이다.
    }
    num += pParam[i]. nValues;
}

돌려주어진 구조체의 사용이 끝나면(자),FreeProps 를 호출해, 이 메소드에 의해 할당할 수 있고 있던 리소스를 해방한다.

IPropertySetter::LoadFromBlob

IPropertySetter 인터페이스

영속성 포맷화등 프로퍼티 데이터를 로드한다.

구문

HRESULT LoadFromBlob(
    LONG cSize,
    BYTE *pb
);

파라미터

cSize
[in] 데이터의 사이즈 (바이트 단위).
pb
[in] 데이터를 보관 유지하는 바이트의 배열에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_OUTOFMEMORY 또는 다른 에러 코드를 돌려준다.

IPropertySetter::LoadXML

IPropertySetter 인터페이스

확장 가능 마크업 언어 (XML)로 표현된 프로퍼티 데이터를 로드한다.

구문

HRESULT LoadXML(
    IUnknown *pxml
);

파라미터

pxml
[in] Microsoft XML 파서에 의해 생성 된 XML 요소의 IUnknown 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_FALSE | 프로퍼티 데이터 없음.
S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_INVALID_FILE_FORMAT | 무효인 포맷.

주의

보통, 어플리케이션은 이 메소드를 사용하지 않는다. DES 에서는, 이 메소드를 내부적으로 사용해 XTL 파일로부터 프로퍼티를 로드한다.

이 메소드를 사용하려면 ,IXMLDocument 오브젝트를 생성 해, 이 오브젝트를 사용해 XML 파일을 해석한다. 다음에,IXMLDocument 오브젝트를 사용해 IXMLElement 오브젝트를 취득한다. 이 오브젝트에 프로퍼티가 있는 경우는,IXMLElement 포인터를 LoadXML 메소드에 건네줄 수가 있다. 이 메소드는, 프로파티셋타에 프로퍼티를 로드한다.

IPropertySetter::PrintXML

IPropertySetter 인터페이스

프로퍼티 데이터를 확장 가능 마크업 언어 (XML) 캐릭터 라인으로 변환한다.

구문

HRESULT PrintXML(
    char *pszXML,
    int cbXML,
    int *pcbPrinted,
    int indent
);

파라미터

pszXML
[out] XML 캐릭터 라인을 받는 버퍼에의 포인터.
cbXML
[in] pszXML 가 가리키는 버퍼의 사이즈 (바이트 단위).
pcbPrinted
[out] XML 캐릭터 라인의 길이를 받는 변수에의 포인터. NULL 의 경우가 있다.
indent
[in] 가장 외측의 태그의 인덴트 레벨수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 HRESULT 값을 돌려준다. XML 캐릭터 라인이 버퍼보다 길었던 경우, 이 메소드는 E_OUTOFMEMORY 를 돌려준다.

IPropertySetter::SaveToBlob

IPropertySetter 인터페이스

프로퍼티 데이터를 영속성 포맷에 보존한다.

구문

HRESULT SaveToBlob(
    LONG *pcSize,
    BYTE **ppb
);

파라미터

pcSize
[out] 데이터의 사이즈 (바이트 단위)를 받는 변수에의 포인터.
ppb
[in] 데이터를 받는 바이트의 배열에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는, 바이트 배열에 필요한 메모리를 할당한다. 호출원래는 CoTaskMemFree 함수를 사용해, 메모리를 해방해야 한다.

IPropertySetter::SetProps

IPropertySetter 인터페이스

타겟 오브젝트의 프로퍼티를, 지정된 시간의 적절한 상태로 설정한다.

구문

HRESULT SetProps(
    IUnknown *pTarget,
    REFERENCE_TIME rtNow
);

파라미터

pTarget
[in] 프로퍼티를 설정하는 타겟 오브젝트에의 포인터.
rtNow
[in] 프로퍼티를 설정하는 타임 (100 나노초단위). 스태틱 프로퍼티 (시간의 경과에 의해 변화하지 않는 프로퍼티)를 설정하는 경우는 -1.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, DES 에 의해 불려 가 트란지션 또는 이펙트의 프로퍼티를 설정한다. 보통, 어플리케이션에서는 이 메소드를 호출하지 않는다.

pTarget 로 지정되는 오브젝트는,IDispatch 인터페이스를 이행 하고 있지 않으면 안 된다.


IRenderEngine 인터페이스

타임 라인으로부터 필터 그래프를 구축하는 것으로써,Microsoft® DirectShow® 편집 서비스 (DES) 프로젝트를 렌더링 한다.

DES 는, 이 인터페이스를 이행 하는 2 개의 컴퍼넌트를 제공하고 있다.

  • 기본렌더링 엔진은, 압축되어 있지 않은 출력을 생성한다. 이 출력은, 프리뷰에 사용할 수 있어 또 압축 필터를 경유해 최종 출력 파일의 기입에도 사용할 수 있다.
  • 스마트 렌더링 엔진은,스마트재압축을 사용해, 압축된 출력을 생성한다. 스마트재압축을 사용 하면, 원시 파일의 포맷이 출력 포맷과 다른 경우에게만, 원시 파일이 재압축된다. 소스의 포맷이 일치하고 있을 때는, 출력 파일에 직접 기입해진다. 상황에 의해, 스마트재압축에서는 렌더링 시간을 큰폭으로 개선할 수 있다.

스마트 렌더링 엔진은,ISmartRenderEngine 인터페이스도 지원 하고 있다.

어플리케이션으로 필터 그래프를 생성 해 렌더링 엔진에 건네줄 수 있지만, 보통의 상황에서는, 렌더링 엔진에 필터 그래프를 생성 시킨다. 그래프의 생성은, 2 단계의 처리로 행해진다. 우선,ConnectFrontEnd 메소드를 호출해 프론트엔드를 구축한다. 다음에, 프론트엔드의 출력 핀을 목적의 렌더링 필터에 접속한다.

  • 프리뷰용의 비디오 렌더러 및 오디오 렌더러, 또는
  • 압력,멀티플렉서, 및 최종 출력을 생성하는 파일 라이터.

상세한 것에 대하여는, 「프로젝트의 렌더링」을 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IRenderEngine 메소드 | 설명
SetTimelineObject | 사용하는 렌더링 엔진용의 타임 라인을 설정한다.
GetTimelineObject | 렌더링 엔진이 현재 사용하고 있는 타임 라인을 취득한다.
GetFilterGraph | 렌더링 엔진이 구축한 필터 그래프 (있는 경우)를 취득한다.
SetFilterGraph | 사용하는 렌더링 엔진용의 필터 그래프를 지정한다.
SetInterestRange | 지원되어 있지 않다.
SetInterestRange2 | 지원되어 있지 않다.
SetRenderRange | 타임 라인 위에의, 렌더링 되는 시간의 범위를 설정한다.
SetRenderRange2 | SetRenderRange 와 같은 기능이지만,double 형의 파라미터를 취한다.
GetGroupOutputPin | 지정된 그룹의 출력 핀을 취득한다.
ScrapIt | 렌더링 엔진의 필터 그래프 및 관련 붙일 수 있어 모든 오브젝트를 파기한다.
RenderOutputPins | 필터 그래프의 프리뷰 부분을 생성 한다.
GetVendorString | 벤더 캐릭터 라인을 취득한다.
ConnectFrontEnd | 현재의 타임 라인으로부터 필터 그래프의 프론트엔드를 구축한다.
SetSourceConnectCallback | 지원되어 있지 않다.
SetDynamicReconnectLevel | 렌더링시의 동적재접속의 레벨을 설정한다.
DoSmartRecompression | 지원되어 있지 않다.
UseInSmartRecompressionGraph | 지원되어 있지 않다.
SetSourceNameValidation | 렌더링 엔진이 파일명을 검증하는 방법을 지정한다.
Commit | 이행되어 있지 않다.
Decommit | 이행되어 있지 않다.
GetCaps | 이행되어 있지 않다.

IRenderEngine::Commit

IRenderEngine 인터페이스

이행되어 있지 않다.

구문

HRESULT Commit( void );

IRenderEngine::ConnectFrontEnd

IRenderEngine 인터페이스

현재의 타임 라인으로부터 필터 그래프의 프론트엔드를 구축한다.

구문

HRESULT ConnectFrontEnd( void );

반환값

HRESULT 값을 돌려준다. 가능한 반환값은 다음과 같다.

S_OK | 성공.
S_WARN_OUTPUTRESET | 후라후의 렌더링 부분은 삭제되었다.
E_INVALIDARG | 이 렌더링 엔진에는 타임 라인은 설정되어 있지 않다.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.
E_RENDER_ENGINE_IS_BROKEN | 프로젝트가 올바르고 렌더링 되지 않았기 (위해)때문에, 처리에 실패.
E_UNEXPECTED | 예기치 않은 에러.
VFW_E_INVALIDMEDIATYPE | 무효인 미디어 타입.

주의

이 메소드는, 필터 그래프의 렌더링 부분을 구축하지 않는다. 어플리케이션에서는, 프론트엔드의 출력 핀을 목적의 렌더링 필터에 접속해야 한다.

  • 프리뷰를 실시하려면 ,RenderOutputPins 메소드를 호출한다.
  • 파일에 출력하려면 ,GetGroupOutputPin 를 호출해 그룹마다의 출력 핀을 취득하고 나서, 그 핀을 멀티플렉서 필터에 접속한다.

기본 렌더링 엔진을 사용하고 있는 경우, 프론트엔드 위에의 출력 핀은 비압축 데이터를 생성한다. 스마트 렌더링 엔진을 사용하고 있는 경우, 출력 핀은 압축 데이터를 출력한다.

필터 그래프를 구축한 다음에 타임 라인을 변경했을 경우는,ConnectFrontEnd 를 한번 더 호출해 프론트엔드를 재구축 해야 한다. 이 메소드는, 가능하면 그래프의 렌더링 부분을 유지한다. 그러나, 그룹을 추가 또는 삭제했을 경우, 또는 그룹의 순서를 변경했을 경우는,ConnectFrontEnd 는 렌더링 부분을 삭제하기 위해(때문에), 어플리케이션은 렌더링 부분을 재구축 해야 한다. 렌더링 부분을 삭제했을 경우, 이 메소드는 S_WARN_OUTPUTRESET 를 돌려준다.

IRenderEngine::Decommit

IRenderEngine 인터페이스

이행되어 있지 않다.

구문

HRESULT Decommit( void );

IRenderEngine::DoSmartRecompression

IRenderEngine 인터페이스

지원되어 있지 않다.

구문

HRESULT DoSmartRecompression( void );

IRenderEngine::GetCaps

IRenderEngine 인터페이스

이행되어 있지 않다.

구문

HRESULT GetCaps(
    long Index,
    long *pReturn
);

IRenderEngine::GetFilterGraph

IRenderEngine 인터페이스

렌더링 엔진이 구축한 필터 그래프 (있는 경우)를 취득한다.

구문

HRESULT GetFilterGraph(
    IGraphBuilder **ppFG
);

파라미터

ppFG
[out] 필터 그래프의 IGraphBuilder 인터페이스를 받는 포인터의 주소. 필터 그래프가 없는 경우는, 값 NULL 를 받는다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.
E_POINTER | 무효인 포인터.

주의

복귀시에 *ppFG 의 값이 NULL 이외의 경우,IGraphBuilder 인터페이스는 미처리의 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IRenderEngine::GetGroupOutputPin

IRenderEngine 인터페이스

지정된그룹의 출력 핀을 취득한다.

구문

HRESULT GetGroupOutputPin(
    long Group,
    IPin **ppRenderPin
);

파라미터

Group
그룹을 지정하는, 제로로부터 시작되는 인덱스.
ppRenderPin
[out] 출력 핀의 IPin 인터페이스를 받는 포인터의 주소.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_FALSE | 그룹은 출력 핀을 가지고 있지 않다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.
E_POINTER | 무효인 포인터.
E_RENDER_ENGINE_IS_BROKEN | 프로젝트가 올바르고 렌더링 되지 않았기 (위해)때문에, 처리에 실패.
E_UNEXPECTED | 예기치 않은 에러.

주의

이 메소드를 호출하기 전에,ConnectFrontEnd 를 호출해 그래프의 프론트엔드를 구축한다. 각 그룹은 단일의 미디어 스트림을 나타내, 프론트엔드에는 대응하는 출력 핀이 있다.

이 메소드를 사용해, 파일 기입 그래프의 렌더링 부분을 생성 할 수 있다. 출력 핀을 멀티플렉서 및 파일 라이터 필터에 접속한다. 상세한 것에 대하여는, 「프로젝트의 렌더링」을 참조할것.

프리뷰의 경우는, 이 메소드를 호출할 필요는 없다. 단순하게,ConnectFrontEnd 의 뒤에 RenderOutputPins 를 호출하면 좋다.

메소드가 S_OK 를 돌려주었을 경우, 돌려주어지는 IPin 인터페이스는 미처리의 참조 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IRenderEngine::GetTimelineObject

IRenderEngine 인터페이스

렌더링 엔진이 현재 사용하고 있는 타임 라인을 취득한다.

구문

HRESULT GetTimelineObject(
    IAMTimeline **ppTimeline
);

파라미터

ppTimeline
[out] 타임 라인의 IAMTimeline 인터페이스를 받는 포인터의 주소. 타임 라인이 없는 경우는, 값 NULL 를 받는다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 포인터.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.

주의

복귀시에 *ppTimeline 의 값이 NULL 이외의 경우,IAMTimeline 인터페이스는 미처리의 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

IRenderEngine::GetVendorString

IRenderEngine 인터페이스

벤더 캐릭터 라인을 취득한다.

구문

HRESULT GetVendorString(
    BSTR *pVendorID
);

파라미터

pVendorID
[out, retval] 벤더 캐릭터 라인을 가지는 BSTR 를 받는 변수에의 포인터.

반환값

성공했을 경우, 메소드는 S_OK 를 돌려준다. 그 이외의 경우는, 에러의 발생을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는, 캐릭터 라인에 필요한 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

IRenderEngine::RenderOutputPins

IRenderEngine 인터페이스

필터 그래프의 프리뷰 부분을 생성 한다.

구문

HRESULT RenderOutputPins( void );

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
VFW_S_AUDIO_NOT_RENDERED | 오디오 스트림을 재생할 수 없다.
E_INVALIDARG | 무효인 인수.
E_RENDER_ENGINE_IS_BROKEN | 프로젝트가 올바르고 렌더링 되지 않았기 (위해)때문에, 처리에 실패.
E_UNEXPECTED | 예기치 않은 에러.

주의

이 메소드를 호출하기 전에,ConnectFrontEnd 를 호출해 그래프의 프론트엔드를 구축한다. 프리뷰 이외의 처리를 실시하는 경우는, 이 메소드를 호출해서는 안 된다. 대신에,GetGroupOutputPin 를 호출해 출력 핀에의 포인터를 취득한다.

유저의 컴퓨터에 사운드 카드가 없는 경우, 이 메소드는 VFW_S_AUDIO_NOT_RENDERED 를 돌려준다. 이 경우에는 오디오의 프리뷰는 행해지지 않지만, 비디오 프리뷰에는 영향은 없다.

핀이 비디오 그룹으로부터의 것인 경우, 이 메소드는 메세지를 디스팟치 해야 하는, 예를 들어 윈도우를 움직이려면 , 윈도우의 클라이언트 에리어의 마우스 클릭에 대응해야 한다.

IRenderEngine::ScrapIt

IRenderEngine 인터페이스

렌더링 엔진의 필터 그래프 및 관련 붙일 수 있어 모든 오브젝트를 파기한다.

구문

HRESULT ScrapIt( void );

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.

IRenderEngine::SetDynamicReconnectLevel

IRenderEngine 인터페이스

렌더링시의 동적재접속의 레벨을 설정한다.

구문

HRESULT SetDynamicReconnectLevel(
    DWORD Level
);

파라미터

Level
동적재접속 플래그의 편성. 동적재접속의 레벨을 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.

주의

디폴트에서는, 기본 렌더링 엔진은 프로젝트를 렌더링 하기 전에 모든 소스를 로드한다. 이 때문에, 기동 시간이 길어지는 일이 있다. 동적재접속을 사용했을 경우, 소스는 필요한 때에게만 로드 된다. 이것에 의해 기동 시간은 짧아지지만, 스무스한 재생을 방해할 수 있는 일이 있다. 일반적으로는, 프로젝트로 사용하는 소스 클립이 많아지는에 따라, 동적재접속을 사용하는 메리트가 커진다.

스마트 렌더링 엔진은, 이 메소드를 이행 하고 있지 않다.

IRenderEngine::SetFilterGraph

IRenderEngine 인터페이스

사용하는 렌더링 엔진용의 필터 그래프를 지정한다.

구문

HRESULT SetFilterGraph(
    IGraphBuilder *pFG
);

파라미터

pFG
필터 그래프의 IGraphBuilder 인터페이스에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.

주의

대부분의 어플리케이션에서는 이 메소드를 호출할 필요는 없다. 보다 일반적인 방법은,ConnectFrontEnd 메소드를 호출하는 것으로, 렌더링 엔진에 그래프를 구축시키는 것이다.

렌더링 엔진에 이미 필터 그래프가 있는 경우, 이 메소드는 실패한다.

렌더링 엔진이 생성 한 필터 그래프에의 포인터를 취득해, 그것을 파라미터로서 다른 렌더링 엔진으로 이 메소드를 호출해서는 안 된다. 그것을 실시하면, 예기 할 수 없는 결과를 일으키게 된다.

IRenderEngine::SetInterestRange

IRenderEngine 인터페이스

지원되어 있지 않다.

구문

HRESULT SetInterestRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

IRenderEngine::SetInterestRange2

IRenderEngine 인터페이스

지원되어 있지 않다.

구문

HRESULT SetInterestRange2(
    double Start,
    double Stop
);

IRenderEngine::SetRenderRange

IRenderEngine 인터페이스

타임 라인 위에의, 렌더링 되는 시간의 범위를 설정한다. 지정된 범위의 밖에 있는 오브젝트는 렌더링 되지 않고, 그것들에 대해서 리소스는 할당할 수 없다.

구문

HRESULT SetRenderRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

파라미터

Start
시작 타임 (100 나노초단위).
Stop
종료 타임 (100 나노초단위).

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.

IRenderEngine::SetRenderRange2

IRenderEngine 인터페이스

타임 라인 위에의, 렌더링 되는 시간의 범위를 설정한다. 이 메소드는 SetRenderRange 와 같은 기능이지만,double 형의 파라미터를 취한다.

구문

HRESULT SetRenderRange2(
    double Start,
    double Stop
);

파라미터

Start
시작 타임 (초단위).
Stop
종료 타임 (초단위).

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.

IRenderEngine::SetSourceConnectCallback

IRenderEngine 인터페이스

지원되어 있지 않다.

구문

HRESULT SetSourceConnectCallback(
    IGrfCache *pCallback
);

IRenderEngine::SetSourceNameValidation

IRenderEngine 인터페이스

렌더링 엔진이 파일명을 검증하는 방법을 지정한다.

구문

HRESULT SetSourceNameValidation(
    BSTR FilterString,
    IMediaLocator *pOverride,
    LONG Flags
);

파라미터

FilterString
Microsoft® Win32® 의 OPENFILENAME 구조체의 lpstrFilter 멤버로 필요한 서식으로 설정된 필터 캐릭터 라인의 페어를 포함한 BSTR 값. 미디어 locator는, 최종 사용자에 [열리는] 다이알로그 박스를 표시하는 경우에, 이 필터를 사용한다.
pOverride
디폴트 대신에 사용하는 미디어 locator의 IMediaLocator 인터페이스에의 옵션의 포인터. 디폴트의 미디어 locator를 사용하는 경우는, 이 파라미터를 NULL 로 설정한다. 상세한 것에 대하여는, 「주의」를 참조할것.
Flags
미디어 locator의 동작을 지정하는플래그의 비트마다의 편성. SFN_VALIDATEF_CHECK 플래그는, 반드시 설정되어 있지 않으면 안 된다. SFN_VALIDATEF_IGNOREMUTED 플래그는, 이 메소드에서는 의미를 가지지 않는다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.

주의

pOverride 파라미터를 사용 하면,IMediaLocator 인터페이스의 독자적인 커스텀 이행을 사용할 수 있다. 예를 들어, 디폴트의 미디어 locator는, 발견된 (또는 발견되지 않았다) 파일에 대해 어플리케이션에 통지를 실시하지 않는다. 이러한 제한을 회피하기 위해서, 커스텀 미디어 locator를 이행 해, 디폴트 버젼의 래퍼로 할 수가 있다. 그리고, 디폴트 버젼에 IMediaLocator::FindMediaFile 호출을 직접 건네주어, 그 반환값을 조사한다.

현재, 이 메소드는 동적으로 로드 된 소스를 검증하지 않는다. 상세한 것에 대하여는, 「SetDynamicReconnectLevel 」를 참조할것.

IRenderEngine::SetTimelineObject

IRenderEngine 인터페이스

사용하는 렌더링 엔진용의 타임 라인을 설정한다.

구문

HRESULT SetTimelineObject(
    IAMTimeline *pTimeline
);

파라미터

pTimeline
타임 라인 오브젝트의 IAMTimeline 인터페이스에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | 무효인 포인터.

IRenderEngine::UseInSmartRecompressionGraph

IRenderEngine 인터페이스

지원되어 있지 않다.

구문

HRESULT UseInSmartRecompressionGraph( void );


ISmartRenderEngine 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES)의스마트재압축을 지원 하는 메소드를 제공한다. 스마트 렌더링 엔진은, 이 인터페이스를 공개한다. ISmartRenderEngine 의 사용법의 상세한 것에 대하여는, 「프로젝트의 렌더링」을 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
ISmartRenderEngine 메소드 | 설명
SetGroupCompressor | 지정된 그룹을 렌더링 할 경우에 사용하는 압축 필터를 지정한다.
GetGroupCompressor | 지정된 그룹의 압축 필터를 취득한다.
SetFindCompressorCB | 이행되어 있지 않다.

ISmartRenderEngine::GetGroupCompressor

ISmartRenderEngine 인터페이스

지정된그룹의 압축 필터를 취득한다.

구문

HRESULT GetGroupCompressor(
    long Group,
    IBaseFilter **pCompressor
);

파라미터

Group
제로로부터 시작되는 그룹의 인덱스.
pCompressor
[out] 압축 필터의 IBaseFilter 인터페이스를 받는 포인터의 주소. 압축 필터가 없는 경우는, 값 NULL 를 받는다.

반환값

다음의 몇개의 값을 돌려준다.

E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 에러.
S_OK | 성공.

주의

이 메소드를 사용해, 키 frame rate등의 압축 필터의 프로퍼티를 설정한다. 이 메소드는,IRenderEngine::ConnectFrontEnd 를 호출한 후, 프로젝트를 렌더링 하기 전에 호출한다. 다음에, 압축 파라미터 설정용의 메소드가 포함되는 IAMVideoCompression 인터페이스에 대해, 압축 필터의 출력 핀에 조회한다. 사용이 끝나면(자) 인터페이스를 해방한다. 그 이후에 타임 라인으로 변경을 더했을 경우는,ConnectFrontEnd 를 호출하고 나서 GetGroupCompressor 를 호출해, 압축 파라미터를 재설정해야 한다.

복귀시에 *ppCompressor 의 값이 NULL 이외의 경우,IBaseFilter 인터페이스는 미처리의 카운트를 가진다. 다 사용했을 경우는, 인터페이스를 반드시 해방하는 것.

ISmartRenderEngine::SetFindCompressorCB

ISmartRenderEngine 인터페이스

이행되어 있지 않다.

구문

HRESULT SetFindCompressorCB(
    IFindCompressorCB *pCallback
);

ISmartRenderEngine::SetGroupCompressor

ISmartRenderEngine Interface

지정된 그룹을 렌더링 할 경우에 사용하는 압축 필터를 지정한다.

구문

HRESULT SetGroupCompressor(
    long Group,
    IBaseFilter *pCompressor
);

파라미터

Group
제로로부터 시작되는 그룹의 인덱스.
pCompressor
압축 필터의 IBaseFilter 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_INVALIDARG 를 돌려준다.


IXml2Dex 인터페이스

Microsoft® DirectShow® 편집 서비스 (DES) 의, 확장 가능 마크업 언어 (XML)로 기술된 프로젝트 파일의 보존과 로드를 실시한다. 이 인터페이스는, DirectShow 그래프 (. grf) 파일의 read와 기입을 실시하는 메소드도 제공한다.

요건

Qedit.h 를 필요로 한다.

Internet Explorer 4.0 이후를 필요로 한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IXml2Dex 메소드 | 설명
CreateGraphFromFile | 이행되어 있지 않다.
WriteGrfFile | 필터 그래프를 . grf 포맷으로 파일에 기입한다.
WriteXMLFile | 타임 라인을 XML 로 변환해, XML 데이터를 파일에 기입한다.
ReadXMLFile | XML 프로젝트 파일을 로드한다.
Delete | 이행되어 있지 않다.
WriteXMLPart | 이행되어 있지 않다.
PasteXMLFile | 이행되어 있지 않다.
CopyXML | 이행되어 있지 않다.
PasteXML | 이행되어 있지 않다.
Reset | 이행되어 있지 않다.
ReadXML | 이행되어 있지 않다.
WriteXML | 타임 라인을 XML 캐릭터 라인으로 변환한다.

IXml2Dex::CopyXML

IXml2Dex 인터페이스

이행되어 있지 않다.

구문

HRESULT CopyXML(
    IUnknown *pTimeline,
    double dStart,
    double dEnd
);

IXml2Dex::CreateGraphFromFile

IXml2Dex 인터페이스

이행되어 있지 않다.

구문

HRESULT CreateGraphFromFile(
    IUnknown **ppGraph,
    IUnknown *pTimeline,
    BSTR FileName
);

IXml2Dex::Delete

IXml2Dex 인터페이스

이행되어 있지 않다.

구문

HRESULT Delete(
    IUnknown *pTimeline,
    double dStart,
    double dEnd
);

IXml2Dex::PasteXML

IXml2Dex 인터페이스

이행되어 있지 않다.

구문

HRESULT PasteXML(
    IUnknown *pTimeline,
    double dStart
);

IXml2Dex::PasteXMLFile

IXml2Dex 인터페이스

이행되어 있지 않다.

구문

HRESULT PasteXMLFile(
    IUnknown *pTimeline,
    double dStart,
    BSTR FileName
);

IXml2Dex::ReadXML

IXml2Dex 인터페이스

이행되어 있지 않다.

구문

HRESULT ReadXML(
    IUnknown *pTimeline,
    IUnknown *pXML
);

IXml2Dex::ReadXMLFile

IXml2Dex 인터페이스

XML 프로젝트 파일을 로드한다. 이 메소드는, XML 파일로 표현 떠날 수 있어 모든 오브젝트의 인스턴스를 생성 해 타임 라인에 삽입해, frame rate나 디폴트 이펙트등의 소정의 속성을 타임 라인에 적용한다.

구문

HRESULT ReadXMLFile(
    IUnknown *pTimeline,
    BSTR XMLName
);

파라미터

pTimeline
타임 라인 오브젝트의 IUnknown 인터페이스에의 포인터.
XMLName
로드하는 파일의 이름을 지정하는 캐릭터 라인.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그렇지 않은 경우는,VFW_E_INVALID_FILE_FORMAT 등의 다른 에러 코드를 돌려준다.

주의

이 메소드는, XML 파일로 정의되고 있는 새로운 오브젝트를 타임 라인에 삽입하기 전에, 타임 라인으로부터 기존의 오브젝트를 클리어 하지 않는다. 기존의 타임 라인을 갱신할 필요가 있는 경우는, 먼저 IAMTimeline::ClearAllGroups 를 호출한다.

IXml2Dex::Reset

IXml2Dex 인터페이스

이행되어 있지 않다.

구문

HRESULT Reset(void);

IXml2Dex::WriteGrfFile

IXml2Dex 인터페이스

필터 그래프를 . grf 포맷으로 파일에 기입한다.

구문

HRESULT WriteGrfFile(
    IUnknown *pGraph,
    BSTR FileName
);

파라미터

pGraph
필터 그래프의 IUnknown 인터페이스를 가리키는 포인터.
FileName
기입하는 파일의 이름을 지정하는 캐릭터 라인.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
S_OK | 성공.

이 메소드는,IStorage::CreateStream 및 IPersist::Save 메소드의 내부 호출로 돌려주어진 에러 코드를 돌려주는 일도 있다. 상세한 것에 대하여는, Platform SDK 를 참조할것.

IXml2Dex::WriteXML

IXml2Dex 인터페이스

타임 라인을 XML 캐릭터 라인으로 변환한다.

구문

HRESULT WriteXML(
    IUnknown *pTimeline,
    BSTR *pbstrXML
);

파라미터

pTimeline
타임 라인 오브젝트의 IUnknown 인터페이스에의 포인터.
pbstrXML
타임 라인을 기술하는 XML 캐릭터 라인을 받는 BSTR 형의 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 변환에 필요한 메모리가 부족한 경우는, E_OUTOFMEMORY 를 돌려준다. 그 이외의 경우는, 다른 에러 코드를 돌려준다.

주의

이 메소드는, 캐릭터 라인에 메모리를 할당한다. 어플리케이션은 SysFreeString 를 호출해, 메모리를 해방해야 한다.

IXml2Dex::WriteXMLFile

IXml2Dex 인터페이스

타임 라인을 XML 로 변환해, XML 데이터를 파일에 기입한다.

구문

HRESULT WriteXMLFile(
    IUnknown *pTimeline,
    BSTR FileName
);

파라미터

pTimeline
타임 라인 오브젝트의 IUnknown 인터페이스에의 포인터.
FileName
기입하는 파일의 이름을 지정하는 캐릭터 라인.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_INVALIDARG | 인수가 무효.
E_OUTOFMEMORY | 메모리 부족.
S_OK | 성공.

주의

이 메소드는, 타임 라인내의 모든 컴퍼넌트를 나타내는 XML 파일을 생성한다.

IXml2Dex::WriteXMLPart

IXml2Dex 인터페이스

이행되어 있지 않다.

구문

HRESULT WriteXMLPart(
    IUnknown *pTimeline,
    double dStart,
    double dEnd,
    BSTR FileName
);


구조체

Microsoft® DirectShow® 편집 서비스는, 이하의 구조체를 정의하고 있다.

구조체 | 설명
DEXTER_PARAM | 트란지션 또는 이펙트의 프로퍼티를 지정한다.
DEXTER_VALUE | 프로퍼티의 값을 지정한다.
SCompFmt0 | 스마트재압축의 포맷 정보를 보관 유지한다.


DEXTER_PARAM 구조체

프로퍼티가 소정의 시점에서 상정되는 값을 지정한다.

구문

typedef struct {
    BSTR      Name;
    DISPID    dispID;
    LONG      nValues;
} DEXTER_PARAM;

멤버

Name
프로퍼티의 이름.
dispID
프로퍼티의 디스팟치 ID (DISPID). Name 멤버가 지정되고 있는 경우는 제로.
nValues
그 프로퍼티로 상정되는 값의 개수.

주의

오브젝트는,IDispatch 인터페이스를 지원 하고 있지 않으면 안 된다.

프로퍼티의 DISPID 를 알 수 있고 있는 경우는,dispID 멤버를 설정할 수 있다. 다만, 보통은 Name 멤버에 프로퍼티의 텍스트명을 설정해,dispID 는 0 으로 설정한다. 프로파티셋타는,IDispatch::GetIDsOfNames 를 호출해, DISPID 를 취득한다.

참조

IPropertySetter ,DEXTER_VALUE


DEXTER_VALUE 구조체

트란지션 또는 이펙트로 설정되는 프로퍼티를 식별해, 트란지션 또는 이펙트의 시간폭의 경과에 수반해 상정되는 프로퍼티의 값을 지정한다.

구문

typedef struct {
    VARIANT           v;
    REFERENCE_TIME    rt;
    DWORD             dwInterp;
} DEXTER_VALUE;

멤버

v
프로퍼티의 값.
rt
프로퍼티가 이 값이다고 보여지는, 트란지션 또는 이펙트의 시작 타임 상대의 시간.
dwInterp
프로퍼티가 전의 값으로부터 이 값에 어떻게 변화하는지를 나타내는 플래그. 다음의 언젠가가 아니면 안된다.
DEXTERF_JUMP | 프로퍼티는 지정된 시점에서 즉석에서 새로운 값에 바뀐다.
DEXTERF_INTERPOLATE | 프로퍼티는, 전의 값으로부터 시간의 경과에 수반해 선형적으로 보간 된다.

참조

IPropertySetter ,DEXTER_PARAM


SCompFmt0 구조체

스마트재압축의 포맷 정보를 보관 유지한다.

구문

typedef struct _SCompFmt0
{
    long nFormatId;
    AM_MEDIA_TYPE MediaType;
} SCompFmt0;

멤버

nFormatId
예약이 끝난 상태. 제로가 아니면 안된다.
MediaType
압축 포맷을 기술하는 AM_MEDIA_TYPE 구조체.

참조

IAMTimelineGroup::GetSmartRecompressFormat ,IAMTimelineGroup::SetSmartRecompressFormat


열거형

Microsoft® DirectShow® 편집 서비스는, 이하의 열거형을 정의하고 있다.

열거형

DEXTERF_TRACK_SEARCH_FLAGS | 타임 라인내의 오브젝트를 검색할 때의 경계 조건을 지정한다.
TIMELINE_MAJOR_TYPE | 타임 라인 오브젝트의 메이저 타입을 지정한다.


DEXTERF_TRACK_SEARCH_FLAGS 열거형

타임 라인내의 오브젝트를 검색할 때의 경계 조건을 지정한다.

구문

typedef enum
{
    DEXTERF_BOUNDING = -1,
    DEXTERF_EXACTLY_AT = 0,
    DEXTERF_FORWARDS = 1
} DEXTERF_TRACK_SEARCH_FLAGS;

요소

DEXTERF_BOUNDING
지정된 시간에 걸려 있는 오브젝트를 검색한다.
DEXTERF_EXACTLY_AT
지정된 시간에, 정확하게 시작되는 오브젝트를 검색한다.
DEXTERF_FORWARDS
지정된 시간 이후에 시작하는 오브젝트를 검색한다.

주의

이러한 경계 조건의 요약을 다음 표에 나타낸다.

열거값 | 경계 조건
DEXTERF_BOUNDING Start <= Time
Stop > Time
DEXTERF_EXACTLY_AT | Start == Time
DEXTERF_FORWARDS | Start >= Time
  • Start : 취득되는 오브젝트의 시작 타임.
  • Stop : 취득되는 오브젝트의 종료 타임.
  • Time : 검색으로 지정된 시간.

참조

IAMTimelineTrack::GetSrcAtTime


TIMELINE_MAJOR_TYPE 열거형

오브젝트의 메이저 타입을 지정한다.

구문

typedef enum
{
    TIMELINE_MAJOR_TYPE_COMPOSITE = 1,
    TIMELINE_MAJOR_TYPE_TRACK = 2,
    TIMELINE_MAJOR_TYPE_SOURCE = 4,
    TIMELINE_MAJOR_TYPE_TRANSITION = 8,
    TIMELINE_MAJOR_TYPE_EFFECT = 16,
    TIMELINE_MAJOR_TYPE_GROUP = 128
} TIMELINE_MAJOR_TYPE;

요소

TIMELINE_MAJOR_TYPE_COMPOSITE
합성 오브젝트. 1 개(살) 이상의 트럭을 보관 유지한다.
TIMELINE_MAJOR_TYPE_TRACK
트럭 오브젝트. 1 개(살) 이상의 소스를 보관 유지한다.
TIMELINE_MAJOR_TYPE_SOURCE
소스 오브젝트. 미디어 소스에의 참조가 포함된다.
TIMELINE_MAJOR_TYPE_TRANSITION
트란지션오브제크트. 합성, 트럭, 또는 소스간의 트란지션을 정의한다.
TIMELINE_MAJOR_TYPE_EFFECT
이펙트 오브젝트. 합성, 트럭, 또는 소스 오브젝트에 적용되는 단일 입력 이펙트를 정의한다.
TIMELINE_MAJOR_TYPE_GROUP
그룹 오브젝트. 소정의 형태의 1 개 이상의 트럭이 포함된다.

참조

IAMTimeline ,IAMTimelineComp::GetCountOfType ,IAMTimelineObj::GetTimelineType


정수

Microsoft® DirectShow® 편집 서비스는, 이하의 정수를 정의하고 있다.

  • 동적재접속 플래그
  • 파일명 검증 플래그
  • 사이즈 변경 플래그

동적재접속 플래그

이러한 플래그는, 렌더링중에 사용되는 동적재접속의 레벨을 지정한다.

정수 | 값 | 설명
CONNECTF_DYNAMIC_NONE | 0x00 | 동적재접속 없음. 프로젝트를 렌더링 하기 전에 모든 것을 로드한다.
CONNECTF_DYNAMIC_SOURCES | 0x01 | 필요한 때에게만 소스를 로드한다.
CONNECTF_DYNAMIC_EFFECTS | 0x02 | 예약이 끝난 상태. 사용해서는 안 된다.

참조

IRenderEngine::SetDynamicReconnectLevel

파일명 검증 플래그

이러한 플래그는, 미디어 locator의 동작을 지정한다.

정수 | 값 | 설명
SFN_VALIDATEF_CHECK | 0x01 | 파일명의 타당성을 체크한다. 파일명을 검증하기 위해서는, 이 플래그를 설정해야 한다. 이 플래그를 설정하지 않으면 다른 플래그는 의미를 가지지 않는다.
SFN_VALIDATEF_POPUP | 0x02 | 파일이 발견되지 않았던 경우, 최종 사용자에 [파일을 여는] 다이알로그 박스를 표시한다.
SFN_VALIDATEF_TELLME | 0x04 | 부족 파일이 발견되었을 때에, 파일의 이름과 장소를 나타내는 메시지 박스를 단시간 표시한다. 이 플래그는, 거의 테스트용으로만 유용하다. 이 메시지 박스는, 아마 리테일 제품에는 적합하지 않는다.
SFN_VALIDATEF_REPLACE | 0x08 | 부족 파일이 발견되었을 때에, 소스 오브젝트의 이름을 갱신한다 (IAMTimeline::ValidateSourceNames 메소드에서만 유효).
SFN_VALIDATEF_USELOCAL | 0x10 | 비록 그 파일의 별버젼이 네트워크에 있어도, 로컬 파일이 언제나 사용된다. 상세한 것에 대하여는, 「IMediaLocator::FindMediaFile」와「IRenderEngine::SetSourceNameValidation」를 참조할것.
SFN_VALIDATEF_NOFIND | 0x20 | 부족 파일의 검색을 실시하지 않는다. SFN_VALIDATEF_CHECK 플래그를 설정해도, 파일명의 타당성은 검증된다.
SFN_VALIDATEF_IGNOREMUTED | 0x40 | 뮤트 된 소스 오브젝트를 무시한다 (IAMTimeline::ValidateSourceNames 메소드에서만 유효).

참조

IMediaLocator::FindMediaFile ,IRenderEngine::SetSourceNameValidation

사이즈 변경 플래그

이러한 플래그는, 비디오 소스의 사이즈가 출력 넓이와 일치하지 않을 때에, 어떻게 렌더링 되는지를 지정한다.

정수 | 값 | 설명
RESIZEF_STRETCH | 0 | 이미지는, 어스펙트비(가로세로 비율)을 유지하지 않고 , 타겟 프레임의 세로와 가로의 양쪽 모두에 맞추어 신축된다.
RESIZEF_CROP | 1 | 이미지의 사이즈는 변경되지 않는다. 이미지가 타겟 프레임보다 작은 경우, 주위의 영역은 흑이 된다. 이미지가 타겟 프레임보다 큰 경우, 이미지는 절약할 수 있다.
RESIZEF_PRESERVEASPECTRATIO | 2 | 이미지의 사이즈는, 어스펙트비(가로세로 비율)을 유지해, 타겟 프레임의 세로 또는 가로의 어느 쪽인지 한편에 맞추어 변경된다. 이미지의 높이에 대한 폭의 비가 타겟 프레임의 같은 비와 일치하지 않는 경우는, 레터박스가 생성 된다.
RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX | 3 | 이미지의 사이즈는, 어스펙트비(가로세로 비율)을 유지해, 타겟 프레임 전체를 채우도록(듯이) 변경된다. 이 모드에서는, 레터박스는 생성 되지 않고, 이미지의 좌우 또는 상하의 양단을 절약할 수 있다.

이하의 이미지는, 이러한 플래그의 효과를 나타내고 있다.

사이즈 변경 플래그

참조

IAMTimelineSrc::GetStretchMode ,IAMTimelineSrc::SetStretchMode


트란지션 및 이펙트

여기에서는, Microsoft® DirectShow® 편집 서비스로 제공되는 이펙트와 트란지션에 대해 설명한다.

트란지션

콘포지타 | 배경을 변경하지 않고 , 대상의 직사각형에 맞추어 전경을 신축한다.
키 | 크로마, 알파, 색상, 또는 휘도에 근거해 키잉을 실시한다.
SMPTE 와이프 | 표준 SMPTE 와이프를 실시한다.

이펙트

아르파셋타 | 비디오 이미지의 알파 비트를 설정한다.
볼륨 포락선 | 오디오 스트림의 볼륨을 설정한다.

소스 오브젝트

비디오 칼라 소스 단색이 연속한 비디오 이미지를 생성 한다.


아르파셋타에페크트

비디오 이미지에 알파 비트를 설정한다.

클래스 ID (CLSID) : 506D89AE-909A-44f7-9444-ABD575896E35

CLSID 변수명 : CLSID_DxtAlphaSetter

프로퍼티

프로퍼티 | 형 | 디폴트 | 설명
Alpha | BYTE | -1 | 이미지 전체에 알파를 설정한다.
AlphaRamp | double | -1. 0 | 원의 알파값의 비율로서 알파를 설정한다.

주의

부의 값의 프로퍼티는 무시된다. 1 개의 프로퍼티만이 부가 아닌 값을 가질 수가 있다. Alpha 프로퍼티에는, 이미지의 각 픽셀에 일정한 알파값을 지정한다. 이 프로퍼티는, 원의 이미지의 알파값에 오버라이드(override) 된다. AlphaRamp 프로퍼티에는, 각 픽셀의 알파값을 픽셀의 원의 값의 비율로서 0.0 ~ 1.0 으로 지정한다.

참조


콘포지타트란지션

전경의 서브 직사각형을, 배경의 다른 부분을 변경하지 않고 , 배경의 지정된 직사각형에 합성한다. 이 트란지션을 사용해, 스플리트 스크린 또는 피크체인피크체에페크트를 생성 할 수 있다.

다음의 이미지는, 콘포지타트란지션을 나타내고 있다.

클래스 ID (CLSID) : BB44391D-6ABD-422f-9E2E-385C9DFF51FC

CLSID 변수명 : CLSID_DxtCompositor

프로퍼티

프로퍼티 | 형 | 디폴트 | 설명
Height | long | 0 | 타겟 직사각형의 높이 (픽셀 단위).
OffsetX | long | 0 | 타겟 직사각형의 수평 방향의 오프셋(offset) (픽셀 단위).
OffsetY | long | 0 | 타겟 직사각형의 수직 방향의 오프셋(offset) (픽셀 단위).
SrcHeight | long | 0 | 소스의 서브 직사각형의 높이 (픽셀 단위).
SrcOffsetX | long | 0 | 소스의 서브 직사각형의 x 좌표 (픽셀 단위).
SrcOffsetY | long | 0 | 소스의 서브 직사각형의 y 좌표 (픽셀 단위).
SrcWidth | long | 0 | 소스의 서브 직사각형의 폭 (픽셀 단위).
Width | long | 0 | 타겟 직사각형의 폭 (픽셀 단위).

다음의 그림은, 이러한 프로퍼티를 나타내고 있다.


키트란지션

RGB 값,알파값,색상, 또는 휘도에 근거해 키잉을 실행한다.

다음의 이미지는, 키트란지션을 나타내고 있다.

클래스 ID (CLSID) : C5B19592-145E-11D3-9F04-006008039E37

CLSID 변수명 : CLSID_DxtKey

프로퍼티

프로퍼티 | 형 | 유효한 범위 | 설명 | 적용처
Hue | int | 0–360 | 키잉을 실시하는 색상값. | 색상
Invert | BOOL | FALSE 또는 TRUE | 키의 디폴트 처리를 반대로 할지 어떨지를 나타내는 불리언 값. FALSE 의 경우, 위가 되는 이미지의 픽셀은 디폴트의 방법으로 투과로 된다. TRUE 의 경우, 역의 처리를 한다. | 크로마, 색상, 휘도, 비빨강
KeyType | int | 「주의」를 참조. | 키의 타입을 지정한다. 상세한 것에 대하여는, 「주의」를 참조할것. | 모두
Luminance | int | 0–100 | 키잉을 실시하는 휘도값. | 휘도
RGB | DWORD | 0x0 – 0xFFFFFF | 키잉을 실시하는 색. 값은,0xRRGGBB 포맷의 16 진수값이며,RR 는 빨강의 값,GG 는 초록의 값,BB 는 파랑의 값이다 (순색의 적, 초록, 파랑은, 각각 0 xFF0000, 0 x00FF00, 0x0000FF 가 된다). | 크로마, 색상
Similarity | int | 0–100 | 투과가 되는 색데이터의 범위. 높은 값(정도)만큼, 투과가 되는 동계의 색의 범위가 넓어진다. | 크로마, 비빨강

주의

실행되는 키의 타입은,KeyType 프로퍼티의 값에 의해 정해진다. 이 값은, 이하의 언젠가가 아니면 안된다.

값 | 열거값 | 설명
0 | DXTKEY_RGB | chroma-key (RGB 값에 의한 키).
1 | DXTKEY_NONRED | 비빨강 키 (파랑과 초록의 영역이 투과가 된다).
2 | DXTKEY_LUMINANCE | 휘도 키.
3 | DXTKEY_ALPHA | 알파값에 의한 키.
4 | DXTKEY_HUE | 색상에 의한 키.

디폴트의 키 타입은 DXTKEY_ALPHA 이다.


SMPTE 와이프트란지션

Society of Motion Picture and Television Engineers (SMPTE)이 SMPTE 문서 258M-1993 로 정의하고 있는 임의의 표준 와이프를 생성한다. 다만, 쿠앗드스프릿트는 제외하다.

다음의 이미지는, 진행중의 와이프트란지션을 나타내고 있다.

클래스 ID (CLSID) : DE75D012-7A65-11D2-8CEA-00A0C9441E20

CLSID 변수명 : CLSID_DxtJpeg

프로퍼티

프로퍼티 | 형 | 디폴트 | 설명
BorderColor | long | 0x000000 | 와이프 패턴의 구석을 둘러싸는 테두리의 색. 이 속성의 값은,0xRRGGBB 포맷의 16 진수값이며,RR 는 빨강의 16 진값,GG 는 초록의 16 진값,BB 는 파랑의 16 진값이다 (따라, 순색의 적, 초록, 파랑은, 각각 0 xFF000, 0 x00FF00, 0x0000FF 가 된다).
BorderSoftness | long | 0 | 와이프 패턴의 구석을 둘러싸는, 희미해진 리젼의 폭. 희미해진 리젼을 없음으로 하려면 , 제로를 지정한다.
BorderWidth | long | 0 | 와이프 패턴의 구석을 둘러싸는 테두리의 폭. 테두리를 없음으로 하려면 , 제로를 지정한다.
MaskName | BSTR | NULL | NULL 이외의 경우는, 표준의 편입 와이프 대신에 와이프 마스크로서 사용하는 JPEG 파일의 이름을 지정한다. 파일은, 흑백으로, 픽셀 당 8 비트의 경사가 포함되지 않으면 안 된다. 경사는, 와이프의 진행을 정의하는 마스크로서 사용된다.
MaskNum | long | 1 | 사용하는 와이프의 스타일을 지정하는 표준 SMPTE 와이프 코드. 와이프 코드 및 대응하는 스타일의 일람에 대해서는, SMPTE 문서 258M-1993 를 참조할것.
OffsetX | long | 0 | 이미지의 중심점으로부터 와이프의 시작점까지의, 수평 방향의 오프셋(offset).
OffsetY | long | 0 | 이미지의 중심점으로부터 와이프의 시작점까지의, 수직 방향의 오프셋(offset).
ReplicateX | long | 0 | 와이프 패턴을 수평 방향으로 반복하는 회수.
ReplicateY | long | 0 | 와이프 패턴을 수직 방향으로 반복하는 회수.
ScaleX | double | 1.0 | 와이프를 수평 방향으로 신축하는 양. 와이프의 원의 정의에 대한 비율로 지정한다.
ScaleY | double | 1.0 | 와이프를 수직 방향으로 신축하는 양. 와이프의 원의 정의에 대한 비율로 지정한다.


비디오 칼라 소스

단색이 연속한 비디오 이미지를 생성 한다.

클래스 ID (CLSID) : 1c621200-67b2-11d2-9eeb-006008039e37

CLSID 변수 : CLSID_ColorSource

프로퍼티

프로퍼티 | 형 | 디폴트 | 설명
Color | DWORD | 0 | 생성하는 색. 이 속성의 값은 0xAARRGGBB 포맷의 16 진수값이며,AA 는 알파값,RR 는 빨강의 값,GG 는 초록의 값,BB 는 파랑의 값을 나타낸다. 알파값은 0x00 (투명) ~ 0xFF (불투명)의 범위이다. 이 프로퍼티는 정적이고, 시간 제로에 적용되지 않으면 안 된다.

주의

비디오 칼라 소스는, 소스 오브젝트와 함께 사용된다. 최초로, 새로운 소스 오브젝트를 생성 한다. 다음에,IAMTimelineObj::SetSubobjectGUID 메소드를 호출해, 소스 오브젝트의 서브 오브젝트 GUID 에 CLSID_ColorSource 를 설정한다.

색을 설정하려면 ,프로파티셋타 오브젝트 를 생성 해, 시간 제로에 Color 프로퍼티를 적용한다. 비디오 칼라 소스는, 이 프로퍼티에의 동적인 변경을 지원 하고 있지 않다. 이 값은, 시간과 함께 변경할 수 없다.

다음의 샘플 코드는, 이 오브젝트의 사용법을 나타내고 있다. IPropertySetter 의 사용의 상세한 것에 대하여는, 「이펙트 및 트란지션의 프로퍼티의 설정」을 참조할것.

DWORD           dwYellow = 0xFFFF00;
IAMTimelineObj  *pSource = NULL;
IPropertySetter *pProp = NULL;

pTimeline->CreateEmptyNode(&pSourceObj, TIMELINE_MAJOR_TYPE_SOURCE);
pSource->SetStartStop(0, 50000000);
pSource->SetSubObjectGUID(CLSID_ColorSource);

// 프로파티셋타를 생성 한다.
CoCreateInstance(CLSID_PropertySetter, NULL, CLSCTX_INPROC_SERVER,
    IID_IPropertySetter, (void**) &pProp);

// 색을 설정한다.
DEXTER_PARAM param;
DEXTER_VALUE val;

param.Name = SysAllocString(L"Color");
param.dispID = 0;
param.nValues = 1;

val.v.vt = VT_I4;
val.v.lVal = dwYellow;
val.rt = 0;  // 시간은 제로가 아니면 안된다.
val.dwInterp = DEXTERF_JUMP;

pProp->AddProp(param, &val);
pSource->SetPropertySetter(pProp);

// 클린 업 한다.
SysFreeString(param.Name);
VariantClear(&val.v));
pProp->Release();

다음의 샘플 코드는, 전의 예로 생성 한 오브젝트의 XML 표현을 나타내고 있다. 이 경우,PARAM 태그는,AT 태그 및 LINEAR 태그를 지원 하고 있지 않다. 이것은, 오브젝트가 동적인 프로퍼티를 지원 하고 있지 않기 때문이다.

<clip start="0" stop="5" clsid="{0CFDD070-581A-11D2-9EE6-006008039E37}">
<param name="Color" value="16776960"/>
</clip>


볼륨 포락선 이펙트

오디오 스트림의 볼륨을 설정한다.

클래스 ID (CLSID) : 036A9790-C153-11D2-9EF7-006008039E37

CLSID 변수명 : CLSID_AudMixer

프로퍼티

프로퍼티 | 형 | 디폴트 | 설명
Vol | double | 1.0 | 볼륨. 생성시의 볼륨에 대한 비율로 지정한다. 이 프로퍼티값을 시간의 경과에 수반해 변화시키는 것으로, 오디오 페이드를 생성할 수 있다.

주의

타임 라인내의 각 오브젝트가 가질 수가 있는 볼륨 포락선 이펙트는, 최대로 1 개이다. 트럭, 합성, 또는 그룹에서는, 볼륨 포락선은 항상, 다른 오디오 이펙트의 다음에, 마지막에 적용된다 (클립에서는, 볼륨 포락선은, 다른 이펙트와 같게, 우선 순위에 따라 적용된다).


DirectShow 편집 서비스의 컴퍼넌트

Microsoft® DirectShow® 편집 서비스 (DES)에는, 이하의 COM 컴퍼넌트가 포함되어 있다. 「트란지션 및 이펙트」도 참조할것.

  • 합성
  • 이펙트
  • 그룹
  • 미디어 detector
  • 미디어 locator
  • 프로파티셋타
  • 렌더링 엔진 (기본)
  • 렌더링 엔진 (스마트)
  • 소스
  • 타임 라인
  • 트럭
  • 트란지션
  • XML 퍼서

    • 합성

    설명 | 트럭과 다른 합성이 포함된다.
    클래스 식별자 | 이용할 수 없다. 생성 하려면 ,IAMTimeline::CreateEmptyNode 를 사용한다.
    인터페이스
    • IAMTimelineComp
    • IAMTimelineEffectable
    • IAMTimelineObj
    • IAMTimelineTransable
    • IAMTimelineVirtualTrack
    참조 | 타임 라인 모델,타임 라인의 구축

    이펙트

    설명 | 비디오 이펙트 또는 오디오 이펙트를 생성 한다.
    클래스 식별자 | 이용할 수 없다. 생성 하려면 ,IAMTimeline::CreateEmptyNode 를 사용한다.
    인터페이스
    • IAMTimelineEffect
    • IAMTimelineObj
    • IAMTimelineSplittable
    • IPropertyBag
    참조 | 타임 라인 모델,이펙트와 트란지션의 조작

    그룹

    설명 | 최상정도 레벨의 합성.
    클래스 식별자 | 이용할 수 없다. 생성 하려면 ,IAMTimeline::CreateEmptyNode 를 사용한다.
    인터페이스
    • IAMTimelineComp
    • IAMTimelineGroup
    • IAMTimelineObj
    참조 | 타임 라인 모델,타임 라인의 구축

    미디어 detector

    설명 | 정보와 스티르후레임을 파일 소스로부터 취득한다.
    클래스 식별자 | CLSID_MediaDet
    인터페이스
    • IMediaDet
    참조 | 소스의 조작

    미디어 locator

    설명 | 소스 오브젝트에 관련한 파일을 생성 한다.
    클래스 식별자 | CLSID_MediaLocator
    인터페이스
    • IMediaLocator
    참조 | 소스의 조작

    프로파티셋타

    설명 | 타임 라인 오브젝트에 IDispatch 프로퍼티를 설정한다.
    클래스 식별자 | CLSID_PropertySetter
    인터페이스
    • IAMSetErrorLog
    • IPropertySetter
    참조 | 타임 라인 모델,이펙트와 트란지션의 조작

    렌더링 엔진 (기본)

    설명 | 타임 라인으로부터의 비압축 출력을 렌더링 한다.
    클래스 식별자 | CLSID_RenderEngine
    인터페이스
    • IAMSetErrorLog
    • IRenderEngine
    참조 | 프로젝트의 렌더링

    렌더링 엔진 (스마트)

    설명 | 타임 라인으로부터의 압축 출력을 렌더링 한다.
    클래스 식별자 | CLSID_SmartRenderEngine
    인터페이스
    • IAMSetErrorLog
    • IRenderEngine
    • ISmartRenderEngine
    참조 | 프로젝트의 렌더링

    소스

    설명 | 타임 라인의 소스 클립을 나타낸다.
    클래스 식별자 | 이용할 수 없다. 생성 하려면 ,IAMTimeline::CreateEmptyNode 를 사용한다.
    인터페이스
    • IAMTimelineEffectable
    • IAMTimelineObj
    • IAMTimelineSrc
    • IAMTimelineSplittable
    참조 | 타임 라인 모델,소스의 조작

    타임 라인

    설명 | 비디오 편집 프로젝트의 모든 오브젝트가 포함된다.
    클래스 식별자 | CLSID_AMTimeline
    인터페이스
    • IAMTimeline
    • IAMSetErrorLog
    • IPersistStream
    참조 | 타임 라인 모델,타임 라인의 구축

    트럭

    설명 | 소스 오브젝트가 포함된다.
    클래스 식별자 | 이용할 수 없다. 생성 하려면 ,IAMTimeline::CreateEmptyNode 를 사용한다.
    인터페이스
    • IAMTimelineEffectable
    • IAMTimelineObj
    • IAMTimelineSplittable
    • IAMTimelineTrack
    • IAMTimelineTransable
    • IAMTimelineVirtualTrack
    참조 | 타임 라인 모델,타임 라인의 구축

    트란지션

    설명 | 트럭 또는 합성간의 트란지션을 생성 한다.
    클래스 식별자 | 이용할 수 없다. 생성 하려면 ,IAMTimeline::CreateEmptyNode 를 사용한다.
    인터페이스
    • IAMTimelineObj
    • IAMTimelineSplittable
    • IAMTimelineTrans
    참조 | 타임 라인 모델,이펙트와 트란지션의 조작

    XML 퍼서

    설명 | XML 프로젝트 파일을 타임 라인으로 변환한다.
    클래스 식별자 | CLSID_Xml2Dex
    인터페이스
    • IXml2Dex
    참조 | 프로젝트의 로드와 프리뷰


XML 레퍼런스

Microsoft® DirectShow® 편집 서비스는, 확장 가능 마크업 언어 (XML)의 영속성 포맷을 사용하고 있다. 이 포맷은, 이하의 요소를 정의하고 있다.

요소 | 설명
AT | PARAM 요소의 시간 베이스의 설정을 지정한다.
CLIP | 원시 파일을 지정한다.
COMPOSITE | 합성을 정의한다.
EFFECT | 이펙트를 정의한다.
GROUP | 그룹 (오디오 또는 비디오)을 정의한다.
LINEAR | PARAM 요소의 시간 베이스의 설정을 지정한다.
PARAM | 트란지션, 이펙트, 또는 다른 서브 오브젝트의 프로퍼티값을 지정한다.
TIMELINE | 타임 라인을 정의한다.
TRACK | 트럭을 정의한다.
TRANSITION | 트란지션을 정의한다.

속성의 데이터형

이하의 속성의 데이터형에는, 특별한 서식이 필요하다.

Boolean : y,Y,t,T,1은, TRUE 라고 정의된다. n,N,f,F,0 (제로)은, FALSE 라고 정의된다.

CLSID : 클래스 식별자는,{00000000-0000-0000-0000-000000000000} 포맷을 사용해 캐릭터 라인으로서 지정한다.

Float : 모든 부동 소수점값은, 소수점의 전에 제로가 붙지 않으면 안 된다. 예를 들어,. 3 은 아니고 0.3 으로 한다.

Time : 시각의 값에는,hh:mm:ss.ff 포맷을 사용한다. 즉,hh = 시간,mm = 분 ,ss = 초,ff = 초의 소수 부분이다 (예: 1:04:30. 512). 선두의 단위는 생략 할 수 있다. 예를 들어,3:00 (3 분 ) 및 45 (45 초)는, 어느쪽이나 유효하다.


AT 요소

XML 레퍼런스

파라미터가 포함된 트란지션 또는 이펙트의 시작 타임에 대해서 상대적인, 특정의 시간에 있어서의 PARAM 요소의 값을 정의한다. AT 요소는, 어느 시간에 파라미터값을 즉석에서 새로운 값으로 전환한다. 새로운 값에 원활히 변화시키기 위해서(때문에)는,LINEAR 요소를 사용한다.

례

<AT TIME="1" VALUE="0. 5" />

속성

이름 | 설명 | 형
TIME | 파라미터가 새로운 값을 취하는, 트란지션 또는 이펙트의 시작 타임에 대한 상대적인 시간. | Time
VALUE | 지정된 시간에 파라미터가 가지는 값. | 「주의」를 참조.

친/자 정보

친 | PARAM
자 | 없음

주의

VALUE 속성의 데이터형은, 설정된 프로퍼티에 의존한다. 상세한 것에 대하여는, 「트란지션 및 이펙트」를 참조할것.


CLIP 요소

XML 레퍼런스

미디어 소스를 지정한다.

례

<CLIP SRC="sample.avi" START="1:05" STOP="1:42. 5" MSTART="30" />

속성

이름 | 설명 | 형 | C/C++ 로 상당하는 것
CLSID | 소스로서 사용하는 소스 필터의 CLSID. SRC 속성이 지정되고 있는 경우는, 이 속성을 지정해서는 안 된다. | CLSID | IAMTimelineObj::SetSubObjectGUID
FRAMERATE | 디폴트의 frame rate (매초의 프레임수). 이 속성의 디폴트는 0 이며,SRC 속성으로 지정되는 스티르이메이지만이 사용되는 것을 나타낸다. DIB 순서를 유효하게 하려면 , 이 속성을 제로 이외의 값으로 설정한다. 소수점 이하가 8 자리수 이상의 값을 사용해서는 안 된다. | Float | IAMTimelineSrc::SetDefaultFPS
LOCK 클립이 락 되는 (편집해서는 안 된다) 화도인지를 지정한다.
  • TRUE : 클립은 락 된다.
  • FALSE : 클립은 락 되지 않는다 (디폴트).
Boolean IAMTimelineObj::SetLocked
MLENGTH | 원의 파일의 시간폭. 이 값은 실제의 시간폭이 아니면 안된다. 그렇지 않은 경우, 렌더링 에러가 발생하는 일이 있다. | Time | IAMTimelineSrc::SetMediaLength
MSTART | 원의 미디어 파일에 대해서 상대적인, 클립의 시작 타임. | Time | IAMTimelineSrc::SetMediaTimes
MSTOP | 원의 미디어 파일에 대해서 상대적인, 클립의 종료 타임. | Time | IAMTimelineSrc::SetMediaTimes
MUTE 소스의 뮤트 상태를 지정한다.
  • TRUE : 소스는 렌더링 되지 않는다.
  • FALSE : 소스는 렌더링 된다 (디폴트).
Boolean IAMTimelineObj::SetMuted
SRC | 미디어 파일의 패스명. 파일에는, DirectShow 가 지원 하는 임의의 타입, 또는 스티르이메이지를 사용할 수 있다. 스티르이메이지로 지원 되는 포맷에는, 비트 맵, 디바이스에 의존하지 않는 비트 맵, GIF, 및 JPEG 가 있다. 상세한 것에 대하여는, 「주의」를 참조할것. CLSID 속성이 지정되고 있을 때는, 이 속성을 지정해서는 안 된다. | String | IAMTimelineSrc::SetMediaName
START | 타임 라인에 대해서 상대적인, 클립의 시작 타임. | Time | IAMTimelineObj::SetStartStop
STOP | 타임 라인에 대해서 상대적인, 클립의 종료 타임. | Time | IAMTimelineObj::SetStartStop
STREAM | AVI 파일등의 멀티 스트림 파일로, 어느 스트림을 사용하는지를 지정한다. | Integer | IAMTimelineSrc::SetStreamNumber
STRETCHMODE 출력 넓이에 일치하지 않는 이미지를 신축하는 방법을 지정한다. 다음의 몇개의 값을 지정할 수 있다.
  • Stretch : 이미지는, 어스펙트비(가로세로 비율)을 유지하지 않고 , 출력 프레임에 맞추어 신축된다 (디폴트).
  • Crop : 이미지는, 출력 프레임의 사이즈에 맞추어 절약할 수 있다.
  • PreserveAspectRatio : 원의 어스펙트비(가로세로 비율)이 유지되어 짧은 넓이에는 흑의 레터박스가 표시된다.
  • PreserveAspectRatioNoLetterBox : 이미지의 사이즈는, 어스펙트비(가로세로 비율)을 유지해, 타겟 프레임 전체를 채우도록(듯이) 변경된다.
String IAMTimelineSrc::SetStretchMode
USERDATA | 어플리케이션 정의의 영속 데이터. 짝수일 필요가 있다. 값 A ~ F 는, 대문자가 아니면 안 된다. 0x 와 같은 프레픽스를 사용해서는 안 된다 (예 : 123ABC). | Hexadecimal | IAMTimelineObj::SetUserData
USERID | 오브젝트에 대한 어플리케이션 정의의 식별자. | Integer | IAMTimelineObj::SetUserID
USERNAME | 오브젝트에 대한 어플리케이션 정의의 이름. | String | IAMTimelineObj::SetUserName

친/자 정보

친 | TRACK
자 | EFFECT

주의

적어도, 시작 타임 속성의 한편 (START 또는 MSTART)과 종료 타임 속성의 한편 (STOP 또는 MSTOP)을 지정한다. 시작 타임 속성의 한편이 지정되지 않았던 경우, 그 속성은 디폴트로 0 (START 에서는 타임 라인의 선두,MSTART 에서는 클립의 선두)으로 설정된다. 종료 타임 속성의 한편이 지정되지 않았던 경우, DES 는 보통의 재생 레이트를 상정해, 거기에 따라서 미지정의 종료 타임을 계산한다. 종료 타임이 양쪽 모두 지정되었을 경우, 필요하면 재생의 속도는 보통보다 빠르고, 또는 늦어진다.

다음의 예에서는, 타임 라인의 시간폭은 7 초 (STOP - START)가 된다. 보통의 재생 레이트이면, 미디어 종료 타임은 디폴트로 10 초 (시간폭 + MSTART)가 된다.

<CLIP START="2" STOP="9" MSTART="3" />

2 번째의 예에서는, 미디어 시작 타임은 디폴트로 0 이 되어, 그것에 의해 미디어의 시간폭은 10 초가 된다. 타임 라인의 시간폭은 5 초이기 (위해)때문에, 클립의 재생 레이트는 보통의 2 배의 속도가 된다.

<CLIP START="5" STOP="10" MSTOP="10" />

SRC 속성에 스티르이메이지가 지정되었을 경우, DES 는 애니메이션을 생성 하기 위해서 일련의 스티르이메이지를 로드하려고 한다. 예를 들어,SRC 속성이 IMAGE001.BMP 인 경우, DES 는 IMAGE002.BMP,IMAGE003.BMP,IMAGE004.BMP 등의 파일을 검색한다. 그러한 파일이 존재하면, 그 파일명의 숫자의 순서에 따라,FRAMERATE 속성으로 지정된 레이트로 표시된다.


COMPOSITE 요소

XML 레퍼런스

합성을 정의한다. 합성은, 트럭 및 다른 네스트 된 합성의 컨테이너 오브젝트이다.

례

<COMPOSITE> </COMPOSITE>

속성

이름 | 설명 | 형 | C/C++ 로 상당하는 것
LOCK 합성이 락 되는 (편집해서는 안 된다) 화도인지를 지정한다.
  • TRUE : 합성은 락 된다.
  • FALSE : 합성은 락 되지 않는다 (디폴트).
Boolean IAMTimelineObj::SetLocked
MUTE 합성과 그 모든 아이의 뮤트 상태를 지정한다.
  • TRUE : 합성과 그 모든 아이는 렌더링 되지 않는다.
  • FALSE : 합성은 렌더링 된다. 아이는, 각각의 뮤트 상태에 따라 렌더링 된다 (디폴트).
Boolean IAMTimelineObj::SetMuted
USERDATA | 어플리케이션 정의의 영속 데이터. 짝수가 아니면 안 된다. A ~ F 는, 대문자일 필요가 있다. 0x 와 같은 프레픽스를 사용해서는 안 된다 (예 : 123ABC). | Hexadecimal | IAMTimelineObj::SetUserData
USERID | 오브젝트에 대한 어플리케이션 정의의 식별자. | Integer | IAMTimelineObj::SetUserID
USERNAME | 오브젝트에 대한 어플리케이션 정의의 이름. | String | IAMTimelineObj::SetUserName

친/자 정보

친 | COMPOSITE,GROUP
자 | COMPOSITE,EFFECT ,TRACK ,TRANSITION

주의

COMPOSITE 요소 중(안)에서, 네스트 된 계층의 우선 순위는, 태그내로 지정되고 있는 순서에 의해 암묵적으로 결정된다. 최초의 계층은 우선 순위 0 이며, 이후의 계층은 순서에 우선 순서값이 커진다.


EFFECT 요소

XML 레퍼런스

이펙트 오브젝트를 정의한다. 이펙트는, 단일의 스트림 (합성, 트럭, 또는 소스)에 적용되는 단일 입력 변환이다.

례

<EFFECT CLSID="{B05A941C-3CE1-11D2-952A-00C04FA34F05}" START="0" STOP="32" />

속성

이름 | 설명 | 형 | C/C++ 로 상당하는 것
CLSID | 이펙트를 생성 하는 서브 오브젝트의 클래스 식별자 (CLSID). | CLSID | IAMTimelineObj::SetSubObjectGUID
LOCK 이펙트가 락 되는 (편집해서는 안 된다) 화도인지를 지정한다.
  • TRUE : 이펙트는 락 된다.
  • FALSE : 이펙트는 락 되지 않는다 (디폴트).
Boolean IAMTimelineObj::SetLocked
MUTE 이펙트의 뮤트 상태를 지정한다.
  • TRUE : 이펙트는 적용되지 않는다.
  • FALSE : 이펙트는 적용된다 (디폴트).
Boolean IAMTimelineObj::SetMuted
START | 친오브젝트에 대해서 상대적인, 이펙트의 시작 타임. | Time | IAMTimelineObj::SetStartStop
STOP | 친오브젝트에 대해서 상대적인, 이펙트의 종료 타임. | Time | IAMTimelineObj::SetStartStop
USERDATA | 어플리케이션 정의의 영속 데이터. 짝수가 아니면 안 된다. A ~ F 는, 대문자일 필요가 있다. 0x 와 같은 프레픽스를 사용해서는 안 된다 (예 : 123ABC). | Hexadecimal | IAMTimelineObj::SetUserData
USERID | 오브젝트에 대한 어플리케이션 정의의 식별자. | Integer | IAMTimelineObj::SetUserID
USERNAME | 오브젝트에 대한 어플리케이션 정의의 이름. | String | IAMTimelineObj::SetUserName

친/자 정보

친 | COMPOSITE ,GROUP ,CLIP ,TRACK
자 | PARAM


GROUP 요소

XML 레퍼런스

타임 라인내의 최상정도 레벨의 오브젝트인그룹을 정의한다.

례

<GROUP TYPE="video" WIDTH="640" HEIGHT="480" FRAMERATE="30"> </GROUP>

속성

이름 | 설명 | 형 | C/C++ 로 상당하는 것
BITDEPTH | 출력 비디오의 비트수 (픽셀 당의 비트수). 16,24, 또는 32 가 아니면 안된다. 이 속성은,TYPE 속성이비디오의 경우에게만 지정한다. 디폴트값은 16 이다. | Integer
BUFFERING | 프리뷰시에 선행해 렌더링 되는 프레임수. 1 보다 큰 수가 아니면 안된다. 디폴트값은 30 이다. | Integer | IAMTimelineGroup::SetOutputBuffering
FRAMERATE | 출력 frame rate (매초의 프레임수). 소수점 이하가 8 자리수 이상의 값을 사용해서는 안 된다. | Float | IAMTimelineGroup::SetOutputFPS
HEIGHT | 출력 비디오의 높이 (픽셀 단위). 이 속성은,TYPE 속성이비디오의 경우에게만 지정한다. | Integer
LOCK 그룹이 락 되는 (편집해서는 안 된다) 화도인지를 지정한다.
  • TRUE : 그룹은 락 된다.
  • FALSE : 그룹은 락 되지 않는다 (디폴트).
Boolean IAMTimelineObj::SetLocked
MUTE 그룹의 뮤트 상태를 지정한다.
  • TRUE : 그룹과 그 모든 아이는 렌더링 되지 않는다.
  • FALSE : 그룹은 렌더링 된다. 아이는, 각각의 뮤트 상태에 따라 렌더링 된다 (디폴트).
Boolean IAMTimelineObj::SetMuted
PREVIEWMODE 그룹의 프리뷰 모드.
  • TRUE : 프리뷰시에 프레임 빠짐이 생기는 일이 있다 (디폴트).
  • FALSE : 프레임 빠짐은 없다.
디폴트의 설정에서는, 비디오와 오디오의 동기를 유지하기 위해서, 프리뷰시에 시간이 걸리는 이펙트 또는 트란지션에서는 프레임 빠짐이 생긴다. 그 때문에, 비디오의 움직임 그림의 기법 여기 없어지는 일이 있다. 이 속성을 FALSE 로 설정 하면, 프리뷰시에 모든 프레임이 렌더링 되어 그것에 의해 비디오와 오디오의 동기가 잡히지 않게 되는 경우가 있다 (파일에 기입할 때 프레임이 떨어지는 것은 없어진다). 		Boolean IAMTimelineGroup::SetPreviewMode
SAMPLINGRATE | 출력 오디오의 샘플링 레이트 (Hz 단위). 8000,11025,22050,32000,44100, 또는 48000 이 아니면 안된다. 이 속성은,TYPE 속성이오디오의 경우에게만 설정한다. 디폴트값은 44100 이다. | Integer
TYPE | 그룹의 미디어 타입. 비디오또는오디오가 아니면 안된다. | String | IAMTimelineGroup::SetMediaType
USERDATA | 어플리케이션 정의의 영속 데이터. 짝수가 아니면 안 된다. A ~ F 는, 대문자일 필요가 있다. 0x 와 같은 프레픽스를 사용해서는 안 된다 (예 : 123ABC). | Hexadecimal | IAMTimelineObj::SetUserData
USERID | 오브젝트에 대한 어플리케이션 정의의 식별자. | Integer | IAMTimelineObj::SetUserID
USERNAME | 오브젝트에 대한 어플리케이션 정의의 이름. | String | IAMTimelineObj::SetUserName
WIDTH | 출력 비디오의 폭 (픽셀 단위). 이 속성은,TYPE 속성이비디오의 경우에게만 지정한다. | Integer

친/자 정보

친 | TIMELINE
자 | COMPOSITE ,EFFECT ,TRACK

주의

GROUP 요소 중(안)에서, 네스트 된 계층의 우선 순위는, 태그내로 지정되고 있는 순서에 의해 암묵적으로 결정된다. 최초의 계층은 우선 순위 0 이며, 이후의 계층은 순서에 우선 순서값이 커진다.


LINEAR 요소

XML 레퍼런스

특정의 시간에 있어서의 PARAM 요소의 값을, 그 PARAM 요소가 포함된 트란지션 또는 이펙트의 시작 타임에 대해서 상대적으로 정의한다. LINEAR 요소는, 그 파라미터가 전의 값으로부터 새로운 값에 원활히 트란지션 하는 것을 지정한다. 새로운 값에 즉석에서 바꾸려면 ,AT 요소를 사용한다.

례

<LINEAR TIME="6" VALUE="0. 0" />

속성

이름 | 설명 | 형
TIME | 파라미터가 새로운 값을 취하는, 트란지션 또는 이펙트의 시작 타임에 대한 상대적인 시간. | Time
VALUE | 지정된 시간에 파라미터가 가지는 값. | 「주의」를 참조.

친/자 정보

친 | PARAM
자 | 없음

주의

VALUE 속성의 데이터형은, 설정되는 프로퍼티에 의존한다. 상세한 것에 대하여는, 「트란지션 및 이펙트」를 참조할것.


PARAM 요소

XML 레퍼런스

트란지션, 이펙트, 또는 다른 서브 오브젝트의 프로퍼티값을 지정한다.

례

<PARAM NAME="progress" VALUE="1. 0" />

속성

이름 | 설명 | 형
NAME | 설정하는 프로퍼티의 이름. | String
VALUE | 트란지션 또는 이펙트의 시작 타임에 대한 시간 0 에 대해, 프로퍼티가 가지는 값. 0 보다 후의 시간의 값을 지정하려면 ,AT 또는 LINEAR 요소를 사용한다. PARAM 요소에는 AT 또는 LINEAR 요소는 포함되지 않고, 이 속성으로 지정된 값은 이펙트 또는 트란지션 전체에 대해 일정한다. | 프로퍼티에 따라서 다르다.

친/자 정보

친 | CLIP ,EFFECT ,TRANSITION
자 | AT ,LINEAR

주의

다수의 이펙트와 트란지션으로, 그 동작의 다양한 측면을 제어하는 프로퍼티가 지원 되고 있다.

대부분의 트란지션은 표준의 Progress 프로퍼티를 지원 하고 있다. 이 프로퍼티는, 0 에서 1.0 의 범위에서, 출력에 반영되는 트란지션의 비율을 지정한다. Progress = 0.0 의 시점에서는, 트란지션은 그 순서의 시작 (전체가 최초의 비디오 이미지)에 있다. Progress = 0.5 의 시점에서는, 트란지션은 반완료하고 있다 (예를 들어 와이프에서는,Progress = 0.5 의 시점에서, 트란지션 경계는 이미지의 중앙에 있다). Progress = 1.0 의 시점에서, 트란지션은 완료하고 있다 (전체가 2 번째의 이미지). 디폴트에서는, 트란지션은 시작시의 Progress = 0.0 으로부터 시작되어, 종료시의 Progress = 1.0 으로 향해 진행한다.

다른 프로퍼티는, 보통은 1 개의 특정의 트란지션 또는 이펙트에 고유의 것이다. 예를 들어 와이프트란지션은, 트란지션 영역의 폭을 제어하는 GradientSize 프로퍼티를 지원 하고 있다. 프로퍼티의 상세한 것에 대하여는, Microsoft® DirectX® 변환의 문서로 「변환 프로퍼티」를 참조할것.

PARAM 요소를 포함하는 것으로, 트란지션 또는 이펙트의 프로퍼티를 설정할 수 있다. VALUE 속성은, 시간 0 (트란지션 또는 이펙트의 시작 타임 상대)에서의 프로퍼티의 값을 지정한다. PARAM 요소에 자식이 포함되지 않은 경우, 지정된 값은 트란지션 또는 이펙트의 시간폭안 일정한다. 시간의 경과에 수반해 값을 변화시키려면 ,PARAM 요소내에서 AT 또는 LINEAR 요소를 네스트 한다. AT 요소는, 지정된 시간에 프로퍼티를 낡은 값으로부터 새로운 값에 즉석에서 바꾼다. LINEAR 요소는, 새로운 값에의 슴스궶란지션을 생성 한다. 그 경우, DES 는 중간의 값을 보간 한다.

다음의 예에서는,Progress 프로퍼티는 0.0 으로 시작되어, 시간 2 로 1.0 에 직접 바뀌어, 시간 2 에서 6 의 사이에 스무스하게 0.5 에 돌아온다.

<TRANSITION CLSID="{AF279B30-86EB-11D1-81BF-0000F87557DB}" START="0" STOP="6">
    <PARAM NAME="Progress" VALUE="0. 0">
        <AT TIME="2" VALUE="1. 0" />
        <LINEAR TIME="6" VALUE="0. 5" />
    </PARAM>
</TRANSITION>

트란지션을 역방향에 실행하려면 ,Progress 프로퍼티의 디폴트의 동작을 반대로 한다.

<TRANSITION CLSID="{AF279B30-86EB-11D1-81BF-0000F87557DB}" START="0" STOP="6">
    <PARAM NAME="Progress" VALUE="1. 0">
        <LINEAR TIME="6" VALUE="0. 0" />
    </PARAM>
</TRANSITION>


TIMELINE 요소

XML 레퍼런스

타임 라인을 정의한다. 이 요소는, XML 파일내의 루트 노드이다.

례

<TIMELINE> </TIMELINE>

속성

이름 | 설명 | 형 | C/C++ 로 상당하는 것
DEFAULTFX | 디폴트의 이펙트의 CLSID. | CLSID | IAMTimeline::SetDefaultEffect
DEFAULTRANS | 디폴트의 트란지션의 CLSID. | CLSID | IAMTimeline::SetDefaultTransition
ENABLEFX 이펙트가 유효한가 어떤가를 지정한다.
  • TRUE : 이펙트는 렌더링 된다 (디폴트).
  • FALSE : 이펙트는 렌더링 되지 않는다.
Boolean IAMTimeline::EnableEffects
ENABLETRANS 트란지션이 유효한가 어떤가를 지정한다.
  • TRUE : 이펙트는 보통의 방법으로 렌더링 된다 (디폴트).
  • FALSE : 트란지션은 컷 (직접 바꾸고)으로서 렌더링 된다.
Boolean IAMTimeline::EnableTransitions
FRAMERATE | 디폴트의 frame rate (초쯤의 프레임수). 소수점 이하가 8 자리수 이상의 값을 사용해서는 안 된다. 그룹의 FRAMERATE 속성이 지정되고 있는 경우는, 이 값보다 우선된다. | Float | IAMTimeline::SetDefaultFPS

친/자 정보

Parent | 없음. 이 요소는, XML 파일내의 루트 노드가 아니면 안된다.
자 | GROUP


TRACK 요소

XML 레퍼런스

트럭 오브젝트를 정의한다.

례

<TRACK> </TRACK>

속성

이름 | 설명 | 형 | C/C++ 로 상당하는 것
LOCK 트럭이 락 되는 (편집해서는 안 된다) 화도인지를 지정한다.
  • TRUE : 트럭은 락 된다.
  • FALSE : 트럭은 락 되지 않는다 (디폴트).
Boolean IAMTimelineObj::SetLocked
MUTE 트럭의 뮤트 상태를 지정한다.
  • TRUE : 트럭과 그 모든 아이는 렌더링 되지 않는다.
  • FALSE : 트럭은 렌더링 된다. 아이는, 각각의 뮤트 상태에 따라 렌더링 된다 (디폴트).
Boolean IAMTimelineObj::SetMuted
USERDATA | 어플리케이션 정의의 영속 데이터. 짝수가 아니면 안 된다. A ~ F 는, 대문자일 필요가 있다. 0x 와 같은 프레픽스를 사용해서는 안 된다 (예 : 123ABC). | Hexadecimal | IAMTimelineObj::SetUserData
USERID | 오브젝트에 대한 어플리케이션 정의의 식별자. | Integer | IAMTimelineObj::SetUserID
USERNAME | 오브젝트에 대한 어플리케이션 정의의 이름. | String | IAMTimelineObj::SetUserName

친/자 정보

Parent | COMPOSITE ,GROUP
Children | CLIP ,EFFECT ,TRANSITION


TRANSITION 요소

XML 레퍼런스

트란지션오브제크트를 정의한다. 트란지션은, 스트림 (합성이나 트럭등)으로부터 다른 스트림에의 트란지션이 되는 쌍입력 변환이다.

례

<TRANSITION
    CLSID="{2A54C913-07AA-11D2-8D6D-00C04F8EF8E0}"
    START="7"
    STOP="10"
/>

속성

이름 | 설명 | 형 | C/C++ 로 상당하는 것
CLSID | 트란지션을 생성 하는 서브 오브젝트의 클래스 식별자 (CLSID). | CLSID | IAMTimelineObj::SetSubObjectGUID
CUTPOINT | 트란지션이 컷으로서 렌더링 되는 경우의, 트란지션이 한편의 소스로부터 다음의 소스에 바뀌는 시간을 지정한다. 이 값은, 트란지션의 시작과 상대적이다. | Time | IAMTimelineTrans::SetCutPoint
CUTSONLY 트란지션이 컷으로서 렌더링 될지 어떨지를 지정한다.
  • TRUE : 트란지션은 직접 변환 (컷)이 된다.
  • FALSE : 트란지션은 보통의 방법으로 렌더링 된다 (디폴트).
Boolean IAMTimelineTrans::SetCutsOnly
LOCK 트란지션이 락 되는 (편집해서는 안 된다) 화도인지를 지정한다. 다음의 몇개의 값이 아니면 안된다.
  • TRUE : 트란지션은 락 된다.
  • FALSE : 트란지션은 락 되지 않는다 (디폴트).
Boolean IAMTimelineObj::SetLocked
MUTE 트란지션의 뮤트 상태를 지정한다. 다음의 몇개의 값이 아니면 안된다.
  • TRUE : 트란지션은 적용되지 않는다.
  • FALSE : 트란지션은 적용된다 (디폴트).
Boolean IAMTimelineObj::SetMuted
START | 친오브젝트에 대해서 상대적인, 트란지션의 시작 타임. | Time | IAMTimelineObj::SetStartStop
STOP | 친오브젝트에 대해서 상대적인, 트란지션의 종료 타임. | Time | IAMTimelineObj::SetStartStop
SWAPINPUTS 트란지션의 입력을 바꿔 넣을지 어떨지를 지정한다.
  • TRUE : 입력은 바꿔 넣을 수 있다.
  • FALSE : 입력은 바꿔 넣을 수 없다 (디폴트).
Boolean IAMTimelineTrans::SetSwapInputs
USERDATA | 어플리케이션 정의의 영속 데이터. 어플리케이션 정의의 영속 데이터. 짝수가 아니면 안 된다. A ~ F 는, 대문자일 필요가 있다. 0x 와 같은 프레픽스를 사용해서는 안 된다 (예: 123ABC). | Hexadecimal | IAMTimelineObj::SetUserData
USERID | 오브젝트에 대한 어플리케이션 정의의 식별자. | Integer | IAMTimelineObj::SetUserID
USERNAME | 오브젝트에 대한 어플리케이션 정의의 이름. | String | IAMTimelineObj::SetUserName

친/자 정보

친 | COMPOSITE ,TRACK
자 | PARAM

주의

디폴트에서는, 트란지션은 우선 순위의 낮은 계층의 합성으로부터, 트란지션이 존재하는 계층으로 향해 진행한다. SWAPINPUTS 속성이 1 의 경우, 이 방향이 거꾸로 된다. DES 로 사용되는 계층 링 모델에 대해서는, 「타임 라인 모델」을 참조할것.


렌더링 에러

Microsoft® DirectShow® 편집 서비스 (DES)는, 렌더링 에러를 기록하기 위해서 사용되는 각종의 에러 코드를 정의하고 있다. 프로젝트가 올바르고 렌더링 되지 않았던 경우, 렌더링 엔진은 IAMErrorLog::LogError 메소드를 호출한다. 다음의 표는,LogError 에게 건네지는 파라미터를 집계한 것이다.

  • 에러 코드는,ErrorCode 파라미터에 들어가 있다.
  • 설명은,ErrorString 파라미터에 들어가 있다.
  • 추가 정보는 (있는 경우),pExtraInfo 가 가리키는 VARIANT 에 들어가 있다.
  • 추가 정보가 있는 경우, 이 VARIANT 형은,pExtraInfo 가 가리키는 VARIANT 의 vt 멤버에 들어가 있다.

주 : 여기서 설명하는 에러 코드는 HRESULT 값은 아니다. DES 고유의 HRESULT 반환값의 일람에 대해서는, 「에러 코드 및 성공 코드」를 참조할것.

에러 코드 | 설명 | 추가 정보 | Variant 형
DEX_IDS_BAD_SOURCE_NAME | 파일명이 존재하지 않는다. 또는, DirectShow 를 인식할 수 없는 파일 확장자(extension)이다. | 파일명 | BSTR
DEX_IDS_BAD_SOURCE_NAME2 | 파일 타입이 파일 확장자(extension)와 일치하고 있지 않다. 또는, 파일이 망가져 있다. | 파일명 | BSTR
DEX_IDS_MISSING_SOURCE_NAME | 파일명이 필요하지만, 지정되지 않았다. | 없음 | 이용할 수 없다
DEX_IDS_UNKNOWN_SOURCE | 이 소스에 의해 제공된 데이터 소스를 해석할 수 없다. | 없음 | 이용할 수 없다
DEX_IDS_INSTALL_PROBLEM | 예기치 못한 에러. 일부의 DirectShow 컴퍼넌트가 올바르고 인스톨되어 있지 않다. | 없음 | 이용할 수 없다
DEX_IDS_NO_SOURCE_NAMES | 소스 필터가 파일을 받아들이지 않는다. | 없음 | 이용할 수 없다
DEX_IDS_BAD_MEDIATYPE | 그룹의 미디어 타입은 지원되어 있지 않다. | 그룹 번호 | int
DEX_IDS_STREAM_NUMBER | 이 소스에서는 무효인 스트림 번호. | 스트림 번호 | int
DEX_IDS_OUTOFMEMORY | 메모리 부족. | 없음 | 이용할 수 없다
DEX_IDS_DIBSEQ_NOTALLSAME | 순서내의 비트 맵의 타입이 다른 비트 맵과 다르고 있었다. | 비트 맵명 | BSTR
DEX_IDS_CLIPTOOSHORT | 클립의 미디어 타임이 무효이다. 또는, 디바이스에 의존하지 않는 비트 맵 (DIB)의 순서가 단인가 지나다. 주 : 다른 렌더링 에러가 발생하고 있는 경우, 미디어 타임이 유효해도 이 에러가 발생하는 일이 있다. | 없음 | 이용할 수 없다
DEX_IDS_INVALID_DXT | 이펙트 또는 트란지션의 클래스 식별자 (CLSID)가, 유효한 Microsoft® DirectX® 변환 이펙트는 아니다. | CLSID | BSTR
DEX_IDS_INVALID_DEFAULT_DXT | 디폴트의 이펙트 또는 트란지션이, 유효한 DirectX 변환 이펙트는 아니다. | CLSID | BSTR
DEX_IDS_NO_3D | 사용하고 있는 DirectX 의 버젼은, 3 차원 변환을 지원 하고 있지 않다. | CLSID | BSTR
DEX_IDS_BROKEN_DXT | DirectX 변환 이펙트가 올바른 종류가 아닌지, 또는 망가져 있다. | CLSID | BSTR
DEX_IDS_NO_SUCH_PROPERTY | 오브젝트에 그러한 프로퍼티는 존재하지 않는다. | 프로퍼티명 | BSTR
DEX_IDS_ILLEGAL_PROPERTY_VAL | 이 프로퍼티에 부정한 값. | 지정된 값 | VARIANT
DEX_IDS_INVALID_XML | XML 파일내의 구문 에러. | 행 번호 | VT_I4 (4 바이트 정수)
DEX_IDS_CANT_FIND_FILTER | XML 내에서 카테고리와 인스턴스에 의해 지정된 필터가 발견되지 않는다. | 프렌들리명 (인스턴스) | BSTR
DEX_IDS_DISK_WRITE_ERROR | XML 파일의 디스크 기입 에러. | 없음 | 이용할 수 없다
DEX_IDS_INVALID_AUDIO_FX | CLSID 가 유효한 DirectShow 오디오 이펙트 필터는 아니다. | CLSID | BSTR
DEX_IDS_CANT_FIND_COMPRESSOR | 지정된 압축 포맷을 생성하는 압력이 발견되지 않는다. | 없음 | 이용할 수 없다

이하의 에러는 발생하지 않을 것이다. 만일 이러한 에러가 발생했을 경우는,dxmbug.microsoft.com 에 버그 리포트의 송부를 부탁한다.

에러 코드 | 설명
DEX_IDS_TIMELINE_PARSE | 타임 라인 해석의 예기치 못한 에러.
DEX_IDS_GRAPH_ERROR | 필터 그래프 구축의 예기치 못한 에러.
DEX_IDS_GRID_ERROR | 내부 구라두에 관한 예기치 못한 에러.
DEX_IDS_INTERFACE_ERROR | 인터페이스 취득시의 예기치 못한 에러.


DVD 어플리케이션

Microsoft® DirectShow® 에는, DVD 의 조작을 단순화 하는 DVD 네비게이터 소스 필터로 불리는 컴퍼넌트가 포함되어 있다. DVD 네비게이터에게는, 본격적인 스탠드얼론 DVD 플레이어가 갖추는 모든 기능에 가세해, PC상에서 DVD 를 재생하기 위한 추가 기능이 포함되어 있다. DVD 네비게이터와 C++ 및 스크립트 기능을 사용하는 것으로, 개발자는 DVD 의 사양을 참조하는 필요없음에 완전한 기능을 가지는 DVD 플레이어를 생성 할 수 있다. DVD 네비게이터는, 디코더 필터와의 제휴에 의해, 리젼 관리와 저작권 보호 (CSS 및 Macrovision)의 처리도 실시하므로, 어플리케이션 개발자는 이러한 상세한 것에 대하여 작업하지 않아도 된다.

DVD 네비게이터의 필터는 DVD-Video 의 "볼륨" 전체에 걸쳐서 기능한다. 볼륨이란, VIDEO_TS 디렉토리의 파일의 집합이다. 개개의 스트림이나 파일을 처리하는 대부분의 DirectShow 소스 필터와 달리, DVD 네비게이터는 DVD-Video 의 타이틀, 쳅터, 및 타임 코드의 구조를 사용한다. DirectShow 로 개개의 MPEG-2 파일을 재생하고 싶은 개발자는, DVD 네비게이터 필터 대신에 MPEG-2 스플리터 필터를 사용해야 한다. 상세한 것에 대하여는, 「DirectShow 의 MPEG-2 지원」을 참조할것.

C++ 를 사용하는 개발자는, DVD 네비게이터가 공개하는 Component Object Model (COM) 인터페이스를 통해서, DVD 네비게이터를 직접 제어할 수 있다. 스크립트 언어 또는 Microsoft® Visual Basic® 를 사용하는 개발자는,MSWebDVD ActiveX® 컨트롤을 통해서 간접적으로 DVD 네비게이터를 제어할 수 있다.

커스터마이즈 된 인터페이스를 가지는 플레이어, DVD 재생을 제어하는 Web 페이지, 매입 DVD 비디오를 포함한 PowerPoint 프레젠테이션 등, 대부분의 DVD 어플리케이션은, MSWebDVD ActiveX 컨트롤을 사용해 HTML 또는 Visual Basic 로 생성 할 수 있다. 이것은 C++ 를 이용하는 것보다도 간단해 고속으로 있다. C++ 를 사용할 필요가 있는 것은, 게임, 비디오상에 그래픽을 오버레이 하는 프로그램, 커스텀 ActiveX 컨트롤 또는 DLL 등, 보다 전문화된 어플리케이션의 경우 뿐이다.

주 : DirectShow 는, DVD-Video 의 조작과 재생에 필요한 필터를 모두 갖추고 있지만, MPEG-2 디코더는 포함되지 않았다. DirectShow 에 근거한 어플리케이션을 사용해 DVD 를 재생하려면 , 유저의 시스템상에 DirectShow 에 대응한 써드파티제의 하드웨어 디코더 또는 소프트웨어 디코더를 인스톨 할 필요가 있다.

여기에는, 이하의 주제가 포함된다.

  • DirectShow 8.0 의 새로운 DVD 지원 기능
  • DVD 플레이어 어플리케이션의 개발에 필요한 배경 지식
  • DVD 의 기초
  • C++ 에 의한 DVD 플레이어 어플리케이션의 개발
  • C++ DVD 에 관한 참조 페이지로의 쇼트 컷
  • 스크립트에 근거한 DVD 플레이어 어플리케이션의 개발
  • MSWebDVD ActiveX 컨트롤

DVD/MPEG2 디코더의 개발에 대해서는, 「디코더의 개발」을 참조할것.

DVD-ROM 컨텐츠 개발자에게 : DVD-ROM Boilerplate 비디오는, DirectX® 8 Software Development Kit 의 DXF > Extras 폴더에 있다. 이 폴더를 참조하려면 ,[Explore this CD] 를 클릭한다. 이 폴더는, 로컬 드라이브에는 인스톨 되지 않는다. boilerplate 비디오는, DVD 비디오 포맷의 데이터를 포함하지 않는 DVD-ROM 타이틀을 개발자가 제작하기 위해서 제공되고 있다. 적절한 DVD-Video 존이 없는 디스크는, 스탠드얼론 DVD 플레이어에게 삽입 하면, 디스크가 꺼내지거나 록 업 하는 등, 예기치 않은 동작을 할 가능성이 있다. 이러한 바람직하지 않은 상황은, 디스크에 DVD-ROM Boilerplate 비디오를 디스크에 추가하는 것으로 회피할 수 있다. 디스크가 DVD 비디오 플레이어에게 삽입되면(자), 이 디스크는 Microsoft® Windows® 가 실행되는 DVD-ROM PC 용으로 설계되고 있는 것을 유저에게 알리는 메세지가 표시된다.


DirectShow 8.0 에 있어서의 새로운 DVD 지원 기능

DVD 네비게이터의 확장된 기능은,IDvdControl2 (DVD 네비게이터에게 "set" 메소드를 추가한다) 및 IDvdInfo2 ("get"메소드를 추가한다)라고 하는 2 개의 새로운 인터페이스에 의해 공개된다. 최신 기능을 포함한 DVD 네비게이터의 스크립트 기능의 지원은, Microsoft® ActiveX® 컨트롤의 MSWebDVD 에 의해 행해진다.

개발자의 요구에 응해 DVD 네비게이터에게 도입된 각종 기능은, 이하대로이다.

  • 가라오케의 지원 : DVD 네비게이터를 사용해, DVD 가라오케 어플리케이션을 개발할 수 있다. (대응하는 디코더가 필요. )
  • DVD 텍스트 정보의 캐릭터 라인에의 액세스를 단순화 : DVD 네비게이터로 이러한 캐릭터 라인을 해석해, 어플리케이션으로 열거, 식별, 및 검색을 용이하게 실시할 수 있다.
  • IBasic Audio 에 의한 오디오 볼륨의 제어
  • Stop 커멘드의 실행시에 DVD 네비게이터의 동작을 커스터마이즈하기 위한 지원 : 어플리케이션으로 DVD 네비게이터에게 지시해, 필터 그래프를 재기동할 때에 디스크의 현재 위치로부터 재개하는지, 또는 디스크의 최초부터 재생할 수 있다.
  • Digital Theater Systems (DTS) 및 Sony Dynamic Digital Sound (SDDS) 오디오의 지원 : DTS 및 SDDS 오디오 스트림은 DVD 네비게이터에 의해 인식되어 오디오 디코더에게 건네진다. (오디오의 디코드 및 재생을 실시하려면 , DTS 대응 또는 SDDS 대응의 써드파티제 디코더가 필요. )
  • 페어 렌탈 레벨 변경에 대한 지원의 강화 : DVD 네비게이터에 의해, 어플리케이션은 디스크로부터의 페어 렌탈 레벨 변경을 받아들이거나 거부, 또는 무시할 수 있다.
  • DVD 네비게이터 상태의 관리나 커멘드의 동기화에 관한 고도의 옵션
  • 스탭핑(Stepping), 후레임아큐레이트시크, 및 역전 재생의 지원 : 이러한 새로운 기능을 사용하려면 , 지원 할 수 있도록(듯이) 갱신된 비디오 디코더가 필요.
  • 타이틀내의 현재 위치를 보존해, 언제라도 거기로 돌아갈 수가 있는 기능
  • 랜덤인 PGC 타이틀에 있어서의 타임 이벤트에의 지원의 간략화 : 랜덤인 PGC 타이틀의 경우, DVD 네비게이터는 어플리케이션에 대해서 생의 타임 코드 정보를 중계한다.
  • 새롭고, 보다 편리하게 된, 타임 코드 정보를 처리하기 위한 데이터 구조 : DVD_HMSF_TIMECODE 구조를 바이너리코드 10 진 (BCD) 포맷 대신에 사용할 수 있다. DVD_HMSF_TIMECODE 는 시, 분, 초, 프레임에 대한 액세스 하기 쉬운 멤버를 포함하고 있어 ULONG 와의 사이에 캐스트가 가능.
  • 필터 그래프가 시크 동작 후에 플래시 할지 어떨지를 제어하는 기능 : 그래프 버퍼에, 언제라도 몇초간의 비디오를 보존할 수 있다. 그래프에 지시해, 버퍼에 보존된 비디오의 재생을 시크 후에 종료하는지, 또는 새로운 위치로부터 즉석에서 재생을 시작 할 수 있다.
  • 전반적인 파라미터의 레지스터에 값을 설정하는 기능 : DVD 의 사양에 자세하게, 고도의 기능을 이행 하고 싶은 유저를 위한 고도의 기능.
  • 모든 실제적인 목적에 대해서 일의인 수치 디스크 식별자를 생성하는 기능 : 이것은, 디스크를 특정의 Web 베이스의 확장과 관련짓지 않으면 안 되는 MSWebDVD 어플리케이션에 있어 유용한 기능이다.


DVD 어플리케이션의 개발에 필요한 배경 지식

모든 어플리케이션 개발자에게는, 페어 렌탈 락 레벨, 복수의 오디오 및 서브 픽쳐의 스트림, 앵글 블록 등, DVD 테크놀러지가 제공하는 기능에 관한 기본적인 지식이 필요하다. 「DVD 의 기초」에서는, 이러한 기능에 대해 각각 간단하게 설명한다. 상세한 것에 대하여는, 써드파티의 서적을 참조할것. Annex J 커멘드 세트보다 고도의 기능을 이행 하는 경우를 제외해, DVD 의 사양을 참조할 필요는 없다.

Microsoft® DirectShow® Component Object Model (COM)의 어플리케이션 프로그래밍 인터페이스 (API)를 사용하고 있는 C 또는 C++ 의 개발자는, COM 오브젝트의 생성, 및 COM 인터페이스 포인터의 취득이나 해방등의 COM 클라이언트 프로그래밍의 기술을 숙지하고 있을 것이다. 또, 그래프에 대한 직접적인 액세스나 조작이 필요한 경우가 있기 (위해)때문에, 필터 그래프 오퍼레이션의 일반적인 지식도 필요하게 된다.

Microsoft® Visual Basic®, Microsoft® JScript®, 또는 Visual Basic Scripting Edition (VBScript)를 사용하고 있는 경우는, 어플리케이션내의 Microsoft® ActiveX® 컨트롤의 호스팅의 기초에 관해서도 숙지하고 있지 않으면 안 된다. 「스크립트 베이스의 DVD 어플리케이션의 기술」에서는,Web 페이지에 컨트롤을 묻어, 거기로부터 이벤트 통지를 받는 방법을 나타낸다.


DVD 의 기초

소비자에게 있어 매력적인 DVD 의 기능 (심리스인 분기, 복수의 언어, 페어 렌탈 락, 가라오케의 지원, 복수의 앵글)은, 개발자의 작업을 다소 복잡하게 하는 것이다. DVD 플레이어는 오디오 스트림, 비디오 스트림, 및 서브 픽쳐 스트림을 재생하는 것 만이 아니고, 현재 디스크로 이용할 수 있는 조작 옵션을 파악해, 많은 종류의 유저 커멘드를 적절히 처리할 수 없으면 안 된다. DVD 네비게이터에서는, 유저는 그렇게 말한 복잡함을 거의 의식하지 않고 , 완전한 기능을 갖춘 DVD 어플리케이션을 생성 할 수 있다. DVD 의 사양을 참조하는 필요없음에 DVD 네비게이터의 API 를 효과적으로 사용할 수 있지만, 기본적인 DVD 의 조작의 개념은 알아 둘 필요가 있다. 이하에, 필요한 배경 지식을 말한다. DVD 의 지식에 관한 상세한 것에 대하여는, 써드파티의 서적 또는 Web 사이트를 참조할것.

  • 조작 제어의 데이터
  • 오디오, 비디오, 및 서브 픽쳐의 데이터
  • 타이틀과 쳅터
  • 메뉴
  • 페어 렌탈 락 레벨
  • 도메인
  • 유저의 동작 제어

조작 제어의 데이터

DVD-Video 디스크 위에의 오디오 및 비디오의 데이터는, 다양한 조작 제어의 데이터에 의해 일정 간격으로 인터리브 된다. 이 데이터에 의해, 디스크 위에의 특정의 위치로 이동하는 등의 동작을 플레이어에게 지시하거나 또는 단지 정보만의 마커로서 이용해, 그 위치 이후의 내용이 그 이전보다 높은 페어 렌탈 락 레벨을 가지는 것이나, 쳅터의 스킵 동작이 무효라는 점을 플레이어에게 알리거나 할 수 있다. 플레이어가 이 정보를 어플리케이션에 중계 하면, 어플리케이션은 그 정보에 근거한 동작을 실시한다. 이 조작 마커는, DVD 로 비디오 CD 보다 뛰어난 대화 조작성을 유저에게 제공하는 기능의 일부이다. DVD 플레이어의 어플리케이션은, 디스크로 발생하는 이벤트 같이, 유저측에서 발생하는 이벤트도 처리해야 한다.

오디오, 비디오, 및 서브 픽쳐의 데이터

DVD-Video 디스크에는, 비디오, 오디오, 및 서브 픽쳐라고 하는 3 종류의 주요한 데이터 스트림이 포함되어 있다.

  • 비디오 스트림에는 최대 9 개의 "앵글 " (서브 스트림으로 간주해진다)를 포함할 수가 있다. DVD 의 생성자는, 시청자가 같은 장면을 다른 카메라 앵글로부터 볼 수가 있도록(듯이), 임의의 위치에 복수의 앵글을 포함할 수가 있다. 한 번에 액티브하게 할 수 있는 앵글은 1 개뿐이다. 또, Line 21 자막 방송 데이터가 있으면, 그것을 포함할 수도 있다.
  • 최대 8 개의 오디오 스트림 즉 트럭을 포함할 수가 있기 (위해)때문에, 최대 8 개의 멀티 채널 사운드 트랙이 사용 가능하고, DVD 가라오케 디스크로 멀티 채널 오디오를 사용할 수 있다.
  • 또, 메뉴 버튼이나 자막에 사용되는 비트 맵 그래픽을 포함한 서브 픽쳐 스트림을 최대 32 까지 포함할 수가 있다. 비디오의 직사각형내에 표시되면(자) 비슷한 것처럼 보이지만, 서브 픽쳐 데이터 스트림은, 비디오 스트림내의 자막 방송 데이터에는 의존하고 있지 않다. 디스크에 서브 픽쳐와 자막 방송 데이터가 양쪽 모두 포함되어 있는 경우는, 그것들을 동시에 표시할 수 없다.

타이틀과 쳅터

DVD-Video 디스크에 있어서의 주요한 논리적 구분이타이틀이다. 타이틀에 의해 동영상 전체를 나타내는 일도, 또는 30 초의 비디오 클립을 나타낼 수도 있다. 디스크에는 최대 99 타이틀을 포함할 수가 있어 디스크 생성자는 타이틀을 최대 999 의 논리적인 쳅터로 나눌 수가 있다. DVD 위에의 무비 본편에서는, 대부분의 경우, 동영상의 내용은 연속해 재생되는 일련의 쳅터로서 포맷 되고 있다. 그러한 디스크에서는, 쳅터의 마지막 마커에 분기 명령이 포함되어 있어 그것에 의해, 플레이어에게 다음의 쳅터를 연속해 재생하도록(듯이) 지시한다. 이러한 타이틀을, 일련의 시퀀셜 PGC 타이틀이라고 한다. (PGC 와는프로그램 체인의 약어이며, 일련의 쳅터가 속하는 그룹의 별명이다. 이 용어는, DVD 네비게이터의 문서에서는 사용하지 않는다. ) 가라오케 디스크 등 다른 종류의 컨텐츠를 포함한 디스크에 대해서는, 쳅터의 마지막 마커는, 플레이어에게 메뉴를 표시시키거나 단지 플레이어를 정지시키거나 하는데 이용된다.

DVD 어플리케이션의 개발자는 타이틀 및 쳅터 번호를 사용해, 디스크의 특정의 위치에 점프 한다. 상세한 액세스를 실시하려면 , 타이틀 번호와 타임 코드를 사용한다. 타임 코드를 사용할 수 있는 것은 시퀀셜 PGC 타이틀뿐이다. 이것은, 다른 종류에는 타임 코드 맵이 없기 때문에이다.

메뉴

메뉴는, 유저가 기존의 플레이어로 재생되는 DVD 위에의 내용과 교환하기 위한 기본적인 수단이다. 유저는 메뉴를 사용하는 것에 의해, 표시하는 비디오 타이틀, 재생하는 오디오 사운드 트랙, 표시하는 자막이나 카메라 앵글, 및 유효하게 하는 다른 기능을 선택할 수가 있다. DirectShow DVD 어플리케이션의 개발자는, 메뉴를 기존의 플레이어에 있어서의 메뉴로서 유효하게 하는지, 또는, 디스크상에서 생성 된 메뉴를 옮겨놓거나 보충하거나 하는 컴퓨터 베이스의 새로운 인터페이스를 생성 하는지를 선택할 수 있다. 어플리케이션에서는, 프로그램적으로 메뉴 버튼을 선택하거나 액티브하게 하는 것에 의해 유저의 대화 조작을 시뮬레이트 할 수도 있다.

비디오 매니저 메뉴
최상정도의 메뉴는 비디오 매니저 메뉴 (VMGM)이며, 탑 메뉴 또는 타이틀 메뉴라고도 불린다. 메뉴에는 보통, 버튼이 있어, 이 버튼에 의해 유저는 디스크 위에의 메인 타이틀 또는 타이틀의 그룹으로 이동할 수가 있다. 타이틀의 그룹은,타이틀 세트로 불린다. 예를 들어, 무비 본편, "감독 및 캐스트의 인터뷰", "다음의 작품 " 라고 하는 타이틀 세트를 포함한 디스크상에서는, VMGM 의 버튼은 3 개 있다고 생각된다. "다음의 작품 " 버튼을 클릭 하면, 타이틀 세트내에 있는, 각 타이틀용의 버튼이 붙은 비디오 타이틀 세트 메뉴로 이동할 수 있다.

디스크에는, 최대 8 개의 언어에 의한 사운드 트랙을 포함할 수가 있다. 또, 사운드 트랙에 대응하는 언어에 의한 VMGM 를 복수 포함할 수도 있다.

디스크의 최초의 타이틀이 자동 재생 타이틀로서 생성되어 있지 않은 한, 디스크를 재생 하면 VMGM 가 최초로 표시된다. 디스크의 최초의 타이틀이 자동 재생 타이틀로서 생성 되고 있는 경우, VMGM 는 표시되지 않는다. DVD 위에의 무비 본편은, 거의 자동 재생 타이틀로서 생성 되고 있다.

비디오 타이틀 세트 메뉴와 서브 메뉴
비디오 타이틀 세트 메뉴, 별명 루트 메뉴 (루트에는 없다)는 VMGM 의 서브 메뉴이다. 타이틀 세트에는, 1~99 타이틀까지 포함할 수가 있다. VTSM 에는, 유저가 타이틀 세트내의 임의의 타이틀로 이동하기 위한 버튼이 준비되어 있다. 또, 유저가 오디오 스트림, 카메라 앵글, 서브 픽쳐 스트림, 또는 쳅터를 선택하는 옵션으로 이동하기 위한 서브 메뉴도 있다. 이러한 서브 메뉴는, 타이틀 세트내의 타이틀 모두에 대해서 항상 유효하게 되어 있다. 대부분의 DVD 에 대해, VTSM 서브 메뉴는 사용되지 않는다. 루트 메뉴등의 서브 메뉴는 모두 옵션이기 (위해)때문에, VTSM 내의 서브 메뉴가 모두 공통의 루트 메뉴를 가지고 있다고는 할 수 없다.

페어 렌탈 락 레벨

DVD 디스크의 모두 또는 일부는, 1~8 의 페어 렌탈 락 레벨 (PML)로 코드화할 수 있다. 8 은 가장 강한 제한 (성인만)으로, 1 은 가장 약한 제한 (연령 제한 없음)이다. 이 생각은, 부모의 승낙없이 아이가 성인전용 컨텐츠를 보는 것이 없게 해, 어른은 아이가 볼 수 없는 컨텐츠를 볼 수가 있다고 하는 것이다. 미국 및 캐나다에서는, MPAA 의 레이팅 시스템 (G, PG, PG-13, NC-17)에 레벨을 할당하고 있지만, 다른 나라에서는 사정이 다르다.

쳅터는 페어 렌탈 블록내에 논리적으로 존재할 수가 있기 (위해)때문에, 타이틀내에 동일 쳅터의 2 개의 버젼을 포함해, 각각 다른 PML 를 다른 페어 렌탈 블록에 대해 할당할 수가 있다. 예를 들어, 어플리케이션이 PML 를 지원 하고 있으면, 디스크에 로그인한 아이가 쳅터 3 의 1 개의 버젼을 보는 한편으로, 디스크에 로그인한 어른은 다른 버젼을 볼 수가 있다.

타이틀 또는 쳅터에 텐포라리 PML 를 포함할 수도 있다. 전체적으로, 그 내용에는 타이틀 또는 쳅터보다 높은 레이팅이 주어진다. 이것은, 타이틀이 복수의 페어 렌탈 락 레벨을 가질 수 있는 것을 의미하고 있다. 텐포라리 PML 는 일반적으로 앵글 블록으로서 생성 되기 (위해)때문에, 무비의 특정의 장면에 어린이용, 어른용의 2 개의 버젼을 포함할 수가 있다.

페어 렌탈 락 레벨을 적용하는 것은, 플레이어 어플리케이션의 역할이다.

도메인

도메인의 개념은 DVD 의 조작에 있어 매우 중요하지만, 도메인은 타이틀, 메뉴, 및 앵글 블록과 같은 방식에서 디스크상에 물리적으로 마크 되고 있는 것은 아니고, DVD 의 생성자에게는 제어할 수 없다. DVD 도메인은, 5 개(살)의 가능한 값을 가지는 상태 변수의 일종이라고 생각할 수가 있다. DVD 플레이어는, 현재 디스크로부터 읽어내 안의 컨텐츠의 종류를 파악하기 위해서, 이 상태 변수를 감시한다. DVD 플레이어는 도메인을 사용하는 것에 의해, DVD 드라이브에 의미가 없는 커멘드를 발행하지 않게 할 수 있다. 예를 들어, "SelectButton" 커멘드에 의미가 있는 것은 메뉴가 표시되고 있는 경우뿐이어, "FastForward" 커멘드는 플레이어가 현재 정지하고 있는지, 또는 정지화면상인 메뉴를 표시중인 경우는 의미를 만들어내지 않는다. 다음 표에, 도메인의 일람을 나타내, 어플리케이션측에서 본 의미를 나타낸다.
도메인 | DVD 네비게이터가 읽어내 안의 컨텐츠
First Play | 디스크의 최초의 섹션 (FBI 경고 등).
Video Manager Menu | 디스크 전체 또는 디스크의 면의 메인 메뉴. 메뉴 관련의 메소드는 모두 유효.
Video Title Set Menu | 타이틀 또는 타이틀의 그룹의 메뉴, 혹은 서브 메뉴 (서브 픽쳐, 언어, 오디오, 또는 앵글). 메뉴 관련의 메소드는 모두 유효.
Title | 타이틀내의 비디오 컨텐츠. 메뉴 관련의 메소드는 유효하지 않다.
Stop | 없음. 헤드가 디스크로부터 멀어지고 있다. 여기로부터, Play 를 호출할 수 있다.

유저의 동작 제어

유저의 동작 제어 (UOP)는 디스크 위에의 마커이며, DVD 의 생성자는 이 마커를 임의의 위치에 삽입해, 유저의 조작 옵션을 제한할 수가 있다. 대부분의 디스크는, 표준의 UOP 제한으로 준거하고 있다. 예를 들어, 대부분의 디스크는 First Play 도메인에 대해 고속의 빨리 감기나 메뉴의 표시를 유저에게 실시하게 한 없게 하고 있다. 기본적으로는, 커멘드가 현재의 도메인내에서 보통은 유효하게 되는 경우에서도, 모든 디스크에 대해 임의의 UOP 커멘드를 임의의 위치에 삽입할 수가 있다. 예를 들어, 디스크의 특정의 타이틀로 고속의 빨리 감기를 할 수 없게 하거나 유저가 타이틀 도메인을 입력한 후에 특정의 메뉴가 표시되지 않게 할 수가 있다. DVD 네비게이터는, 디스크로부터가 그렇게 말한 커멘드에 모두 준거하고 있어, 어플리케이션이 디스크의 UOP 제어를 오버라이드(override) 하지 않게 하고 있다.


C++ 에 의한 DVD 어플리케이션의 개발

여기에서는, C++ 로 DVD 어플리케이션을 생성하기 위한 주요한 순서에 대해 설명한다. 여기서 가리킨 코드 예의 대부분은, DirectShow 8.0 DVD 샘플 어플리케이션으로부터 취한 것이다. 이 어플리케이션은, DirectShow SDK 의 샘플 디렉토리에 저장 되고 있다. 여기에는, 이하의 주제가 포함된다. DVD 의 기본적인 일반 개념의 배경 정보에 대해서는, 「DVD 의 기초」를 참조할것.

  • DVD 어플리케이션 개발의 기초
  • DVD 필터 그래프의 구성
  • DVD 필터 그래프의 생성
  • DVD 이벤트 통지의 처리
  • DVD 메뉴의 조작
  • 오디오 스트림과 서브 픽쳐 스트림
  • 페어 렌탈 락 레벨의 적용
  • DVD 텍스트 캐릭터 라인의 조작
  • DvdState 오브젝트의 보존과 복원
  • 가라오케 오디오 스트림의 재생
  • DVD 커멘드의 동기화
  • DVD 커멘드 플래그
  • 디스크의 꺼내 처리

DVD 어플리케이션 개발의 기초

DVD 어플리케이션을 개발하려면 , 유저 인터페이스용의 코드를 준비해, Microsoft® DirectShow® 어플리케이션 프로그래밍 인터페이스 (API)를 호출해 DVD 의 재생과 조작을 위한 모든 커멘드를 실행한다. 이것에는, Component Object Model (COM)에 있어서의 DVDGraphBuilder 오브젝트의 CoCreateInstance 메소드의 호출이 포함된다. 이것에 의해, DVD 필터 그래프를 생성 하는 실제의 작업을 한다. 필터 그래프가 생성 되면(자),DVD 네비게이터 소스 필터에 의해 공개되는 IDvdControl2 및 IDvdInfo2 인터페이스에의 포인터를 취득할 수 있다. 인터페이스 포인터를 취득하면(자), 인터페이스를 PlayTitle,Pause 등의 DVD 조작 커멘드에 묶는다. 이 기본 프로세스는 매우 단순해, 다른 종류의 DirectShow 어플리케이션의 생성과 닮아 있다.

DVD 필터 그래프의 구성

일반적으로, DVD 필터 그래프는 자동적으로 생성 되기 (위해)때문에, 어플리케이션 개발자는 그 상세한 것에 대하여 관련될 필요는 없다. 이 주제는, 내부에서 무엇을 하고 있을까를 알고 싶은 사람을 위해서(때문에) 준비되어 있다 (여기서 접하고 있는 개개의 필터의 상세한 것에 대하여는, 「필터」를 참조할것).

다음의 그림에, 표준적인 DVD 필터 그래프를 나타낸다.

DVD 필터 그래프

DVD 네비게이터는, DVD 재생 필터 그래프의 최초의 필터이며, 이하의 작업을 실시한다.

  • 디스크로부터 조작 데이터 및 비디오 데이터를 읽어낸다.
  • 다중화 되고 있는 비디오, 오디오, 및 서브 픽쳐 데이터로부터 개개의 스트림을 꺼낸다.
  • 이후의 처리와 최종적인 렌더링을 위해서(때문에) 스트림을 그래프에 수중에 넣는다.
  • 어플리케이션에 DVD 관련 이벤트를 통지한다.

오디오 스트림에 대해서는, DVD 네비게이터의 뒤에 오디오 디코더가 접속되어 그것은 한층 더 디폴트의 오디오 렌더러인 디폴트 DirectShow 디바이스 필터에 접속된다. 비디오 및 서브 픽쳐 스트림에 대해서는, DVD 네비게이터에게 계속되는 필터로서 써드파티제 비디오 디코더,오버레이 믹서, 및비디오 렌더러가 접속된다. 어플리케이션이 Line 21 자막 방송 데이터를 처리하는 경우에는, DirectShow Line 21 디코더 필터를 그래프에 추가할 필요가 있다. 이것에는 1 개의 메소드 호출이 포함된다. 이 필터는 비디오 디코더와 오버레이 믹서의 사이에 자동적으로 접속된다.

어플리케이션은, DVD 네비게이터가 공개하는 커스텀 인터페이스를 통해서, DVD 네비게이터와 통신해, 그것을 제어한다. 이것은 IDvdControl2 ("set" 메소드)와 IDvdInfo2 ("get" 메소드)이다. 또, 어플리케이션은 그래프의 정지나 시작등의 제어를 실시하기 위해서(때문에), 필터 그래프 매니저와 (IMediaControl 를 통해서) 통신할 필요가 있다. 게다가 경우에 응해, 윈도우 표시와 전화면 표시를 바꾸기 위한 오버레이 믹서 필터 등, 다른 개별의 필터도 제어할 필요가 있다. 상세한 것에 대하여는, 「IMixerPinConfig2 」를 참조할것. 그래프의 엄밀한 구성은, 인스톨 되고 있는 MPEG-2 디코더의 종류, Line 21 자막 방송 데이터를 처리할 필요가 있을지 어떨지 등, 몇개의 조건에 따라서 다르다.

DVD 필터 그래프의 생성

DVD 재생 필터 그래프를 생성 하는 방법으로서는,DVDGraphBuilder 오브젝트에 의해 자동적으로 실시하는 것을 추천 한다. 이 어프로치는, 이하의 설명, 및 DVD 샘플 어플리케이션으로 나타나고 있다. DVD 필터 그래프를 수동으로 생성 할 필요가 있는 경우는, DirectShow 에 관한 다른 문서에 기재되어 있는 그래프 생성의 기본적인 규칙에 따라 생성 할 수가 있다. 일반적으로,DVDGraphBuilder 에 의해 생성 된 그래프에 대해서 개개의 필터를 수동으로 추가, 삭제, 접속, 접속 해제하는 것은 추천 되지 않는다. 그러한 조작을 하면, 클린 업 코드에 의한 처리로 혼란이 생길 가능성이 있다.

DVDGraphBuilder 오브젝트의 인스턴스를 생성 하면, 어플리케이션은 단지 그 IDvdGraphBuilder::RenderDvdVideoVolume 멤버 함수를 호출하면 좋다. 이 함수는, 로컬 시스템에 존재하는 DirectShow 필터와 MPEG-2 디코더로부터 필터 그래프를 생성 한다. 상세한 것에 대하여는, 「필터 그래프의 구축」을 참조할것.

필터 그래프가 생성 되면(자), 어플리케이션은 DVD 네비게이터, 필터 그래프 매니저, 및 비디오 윈도우의 제어에 필요한 포인터를 취득할 수 있다. 이하의 코드예에는, 에러 체크등의 코드를 생략해 단순화 한 기본적인 순서를 나타내고 있다. 완전한 코드는, DirectX8 SDK DXF\samples\multimedia\dshow\dvd 디렉토리에 있는 DirectShow DVDSample 어플리케이션으로 CDvdCore::BuildGraph() 메소드에 포함되어 있다.

   // DVD Graph Builder 오브젝트의 인스턴스를 생성 한다.
   HRESULT hr;
   hr = CoCreateInstance(CLSID_DvdGraphBuilder,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_IDvdGraphBuilder,
                          reinterpret_cast<void**>(&m_pIDvdGB));
   // DVD 필터 그래프를 생성 한다.
   AM_DVD_RENDERSTATUS	buildStatus;
   hr = m_pIDvdGB->RenderDvdVideoVolume(pszwDiscPath, m_dwRenderFlags, &buildStatus);
   // DVD 네비게이터 인터페이스에의 포인터를 취득한다.
   hr = m_pIDvdGB->GetDvdInterface(IID_IDvdInfo2, reinterpret_cast<void**>(&m_pIDvdI2));
   hr = m_pIDvdGB->GetDvdInterface(IID_IDvdControl2, reinterpret_cast<void**>(&m_pIDvdC2));
   ...
   // 필터 그래프 매니저에의 포인터를 취득한다.
   hr = m_pDvdGB->GetFiltergraph(&m_pGraph) ;
   ...
   // 그래프 포인터를 사용해 IMediaControl 에의 포인터를 취득한다.
   // 이것은 필터 그래프를 전체적으로 제어하기 위해서 사용한다.
   hr = m_pGraph->QueryInterface(IID_IMediaControl, reinterpret_cast<void**>(&m_pIMC));
   ...
   // IMediaEventEx 에의 포인터를 취득한다.
   // 이것은 DVD 및 그 외의 필터 그래프 이벤트의 처리에 사용된다.
   hr = m_pGraph->QueryInterface(IID_IMediaEventEx, (LPVOID *) &m_pME) ;
   ...
   // 다시 그래프 빌더 포인터를 사용해 IVideoWindow 인터페이스를 취득한다.
   // 이것은 비디오 렌더링 필터의 윈도우 스타일과 메세지 처리 동작의 설정에 사용된다.
   hr = m_pIDvdGB->GetDvdInterface(IID_IVideoWindow, reinterpret_cast<void**>(&m_pIVW));
   hr = m_pDvdGB->GetDvdInterface(IID_IAMLine21Decoder, (LPVOID *) &pL21Dec) ;

DVD 이벤트 통지의 처리

DVD 네비게이터는, 특정의 이벤트가 발생했을 때에, 어플리케이션으로 지정된 윈도우에 통지를 송신한다. 이것은, DVD 도메인이 변경되었을 경우, 새로운 페어 렌탈 락 레벨을 검출했을 경우, 및 DVD 네비게이터가 앵글 블록에 들어가는 경우 등이다. 이벤트 파라미터에는, 이벤트에 관한 추가 정보를 포함할 수가 있다. 에러 메세지나 경고도 같은 방법으로 송신된다. 어플리케이션은,IMediaEventEx 포인터를 사용해 SetNotifyWindow 를 호출하는 것으로, 이벤트 통지를 처리하는 윈도우를 다음과 같이 지정한다.

    hr = m_pIME->SetNotifyWindow(reinterpret_cast<OAHWND>(m_hWnd), WM_DVD_EVENT, 0);

위의예에 대해, m_hWnd 는 메세지를 수신하는 윈도우의 HWND 이며, WM_DVD_EVENT 는 DVD 이벤트의 발생을 나타내는 어플리케이션 정의 메세지 (WM_USER 보다 크다)이다. 이벤트 자체는, 어플리케이션으로 IMediaEvent::GetEvent 를 호출하는 것으로 취득된다. 특정의 시점에서 이벤트 큐내에 복수의 이벤트가 존재하는 경우가 있기 (위해)때문에, 어플리케이션은 큐내의 모든 이벤트가 취득될 때까지 반복하는 루프 중(안)에서 GetEvent 를 호출할 필요가 있다. 이것을 다음의 코드예에 나타낸다.

while (SUCCEEDED(m_pIME->GetEvent(&lEvent, &lParam1, &lParam2, lTimeOut)))
    {
        HRESULT hr;
        switch(lEvent)
        {

        case EC_DVD_CURRENT_HMSF_TIME:
        {
            DVD_HMSF_TIMECODE * pTC = reinterpret_cast<DVD_HMSF_TIMECODE *>(&lParam1);
            m_CurTime = *pTC;
            ...
        }
        break;
        ...
    }

DVD 이벤트에서는, 위의야 게 lParam1 또는 lParam2 파라미터에 추가 정보가 포함되는 경우가 있다. 여기에서는 lParam1 에 현재의 시각이 포함되어 있다. 이 코드예는 Dvdcore.cpp 의 DVD 샘플 어플리케이션으로부터 취한 것이다. DVD 이벤트와 그 파라미터의 완전한 리스트는, 「DVD 이벤트 통지 코드」를 참조할것.

DVD 메뉴의 조작

DVD 메뉴의 논리적인 구조는, 「DVD 조작의 기초」로 설명하고 있다. 어플리케이션은,IDvdControl2::ShowMenu 를 호출해 표시하고 싶은 메뉴의 인덱스를 건네주는 것으로, 디스크로부터 메뉴를 표시할 수 있다.

버튼을 선택했을 때에는, 단지 그 경계선이 강조 표시되는 것만으로 있는 것에 주의한다. 버튼의 커멘드를 실행하려면 , 버튼을 액티브하게 할 필요가 있다. IDvdControl2 메소드안에는, 지정된 버튼을 선택하는 것과 버튼을 액티브하게 하는 것이 있다. SelectAndActivateButton 는, 그 양쪽 모두를 실시한다. DVD 샘플 어플리케이션의 CDvdCore::OnMouseEvent 에서는, 마우스로 메뉴 버튼을 선택해 액티브하게 할 방법이 나타나고 있다.

어플리케이션에서는,IDvdControl2 의 메뉴 관련 메소드를 사용해 메뉴를 프로그램적으로 제어할 수 있다. 어플리케이션은, 마우스의 이동등의 유저의 동작이나, 그 외의 프로그램 논리에 근거해, 버튼을 강조 표시 (선택)할 수가 있다. 또, DVD 의 리모콘 위에의 버튼을 나타내는 커스텀 메뉴 또는 비트 맵을 이행 해 제어할 수도 있다. DVD 샘플 어플리케이션에서는, 상대 버튼 메뉴 커멘드가 키보드의 커서 키에 관련지을 수 있고 있다 (CDvdCore::OnKeyEvent 를 참조할것). 버튼을 프로그램적으로 액티브하게 하기에는 다양한 방법이 있지만, 액티브하게 하기 전에 반드시 그 버튼을 선택할 필요가 있다.

오디오 스트림과 서브 픽쳐 스트림

DVD-Video 디스크에는, 최대로 8 개의 오디오 스트림을 포함할 수가 있다. 이것에는 0 에서 7 까지의 번호를 붙일 수 있어 각각 6 개(살)까지의 독립한 채널을 가진다 (오디오 스트림과 서브 픽쳐 스트림은 번호가 0 으로부터 시작되지만, 타이틀, 앵글, 및 페어 렌탈 락 레벨은 1 으로부터 시작되는 것에 주의). 이러한 쳐, 동시에 선택할 수 있는 것은 1 개의 스트림 뿐이다. 서브 픽쳐의 경우는, 최대로 32 개의 스트림을 사용할 수 있지만, 동시에 액티브하게 할 수 있는 것은 1 개(살) 뿐이다. 일반적으로, 디스크는 디폴트의 오디오 및 서브 픽쳐 스트림으로 생성 되고 있지만, 어플리케이션에 의해, 유저에게 사용 가능한 스트림의 리스트를 표시해, 희망하는 언어의 스트림을 선택시킬 수도 있다. 이 프로세스에 있어서의 기본적인 순서는, 오디오 스트림의 경우도 서브 픽쳐 스트림의 경우도 같다.

  1. 타이틀에 대해서 사용 가능한 스트림의 수를 결정한다.
  2. 각 스트림을 차례로 봐, 각각의 스트림 속성을 취득한다.
  3. 돌려주어진 로케일 식별자 (LCID)로부터 언어 코드를 취득해, 인간이 읽을 수 있는 캐릭터 라인을 생성 한다.
  4. 유저가 희망의 스트림을 선택할 수 있도록(듯이), 리스트 박스나 그 외의 유저 인터페이스 (UI) 컨트롤을 설정한다.

DVD 샘플 어플리케이션에서는, Dialogs.cpp 의 CAudioLangDlg::MakeAudioStreamList 메소드에 기본적인 순서가 나타나고 있다.

페어 렌탈 락 레벨의 적용

DVD-Video 디스크의 타이틀이나 타이틀의 일부에는, 일반적인 페어 렌탈 락 레벨 (PML) 1 에서 8 까지를 할당할 수가 있다. PML 를 할당할 수 있었던 컨텐츠를 DVD 네비게이터가 읽어내는 경우,"페어 렌탈 블록" 이 걸려 있다고 표현한다. 1 개의 페어 렌탈 블록이, 쳅터의 일부, 복수의 쳅터, 또는 복수의 타이틀로부터 구성되는 경우도 있다. 국제 시장으로 향해 생성 되는 DVD 어플리케이션에서는, 그 페어 렌탈 락 논리에 특정의 레이팅 시스템을 하드 코드 해서는 안된다.

DVD 네비게이터 자체는 PML 를 적용할 것은 없다. 단지, 디스크상에서 PML 정보를 검출했을 때에 어플리케이션에 통지하는 것만으로 있다. 디폴트에서는, DVD 네비게이터는 디스크 위에의 이 정보를 무시해, 최고 레벨의 컨텐츠를 재생한다. PML 를 적용하려면 , 어플리케이션이 어떠한 형태의 패스워드 제어 논리를 이행 해 유저와 레벨을 관련지어 PML 이벤트 통지를 송신하도록(듯이) DVD 네비게이터에게 지시해 (기동시에 DVD_NotifyParentalLevelChange 와 TRUE 의 파라미터로 IDvdControl2::SetOption 를 호출한다), 이 이벤트에 응답하는 것으로 액세스의 가부를 결정할 필요가 있다.

DVD 타이틀에는 전체로 1 개의 PML 를 할당해도 괜찮지만, 디스크 생성자는 그 타이틀의 특정의 부분에 비싼 (제한의 강하다) PML 를 할당할 수도 있다. 이것을 텐포라리 PML 커멘드라고 부른다. 이러한 커멘드에는, 항상 2 개의 분기 명령이 포함된다. 1 개(살)은, 텐포라리 PML 커멘드가 플레이어 어플리케이션에 의해 받아들여졌을 경우에 사용되어 이제(벌써) 1 개(살)은 커멘드가 거부되었을 경우에 사용된다. 이벤트의 순서는 다음과 같이 된다. DVD 네비게이터가 비디오 컨텐츠 (DVD 타이틀 도메인)의 독해중에 디스크상에 텐포라리 PML 커멘드를 검출한다. DVD 네비게이터는 그 내부 플래그를 체크해, 어플리케이션이 이 이벤트의 통지를 요구하고 있을지 어떨지를 조사한다. 플래그가 설정되어 있지 않으면, DVD 의 재생을 계속해 디스크상으로 지정된 "페어 렌탈 락 레벨 변경 거부 " 의 분기를 더듬는다. 플래그가 설정되어 있는 경우는, DVD 는 어플리케이션에 EC_DVD_PARENTAL_LEVEL_CHANGE 이벤트를 송신해, 응답이 돌아갈 때까지 포즈 상태로 기다린다. 어플리케이션은, 이벤트를 수신 하면, 독자적인 논리를 사용해 그 커멘드를 받아들일지 어떨지를 결정한다. 그리고, TRUE 또는 FALSE 의 인수로 IDvdControl2::AcceptParentalLevelChange 를 호출한다. TRUE 의 경우, DVD 네비게이터는 재생을 재개해, 디스크상으로 지정된 "페어 렌탈 락 레벨 변경 수락 " 의 분기를 더듬는다. FALSE 의 경우는, 재생을 재개해, "페어 렌탈 락 레벨 변경 거부 " 의 분기를 더듬는다.

DvdState 오브젝트의 보존과 복원

DvdState 오브젝트에 의해, 어플리케이션은 유저 세션의 snapshot를 보존할 수가 있다. 이것에는, 디스크 위에의 현재 위치, 시청자의 페어 렌탈 락 레벨, 선택되고 있는 오디오 및 서브 픽쳐 스트림등의 정보가 포함된다. 이것은, 유저가 DVD-Video 디스크 위에의 현재 위치를 보존해, 다음에 거기로부터 봐 계속되는 것을 의미한다.

어플리케이션으로 DvdState 오브젝트를 생성 할 수 없다. 이 오브젝트는, 어플리케이션이 IDvdInfo2::GetState 를 호출했을 때에 DVD 네비게이터가 내부에서 자동적으로 생성 한다. DvdState 오브젝트는,IDvdState 인터페이스를 공개해, 어플리케이션이 특정의 정보를 조회할 수 있도록(듯이) 한다.

DVD 샘플 어플리케이션에서는,CDvdCore::RestoreBookmark 및 CDvdCore::SaveBookmark 함수에 DvdState 오브젝트의 보존 및 복원 방법이 나타나고 있다.

DVD 텍스트 캐릭터 라인의 조작

DVD 디스크, 특히 가라오케 디스크에는, 비디오 또는 오디오 컨텐츠를 보충하는 텍스트 정보의 데이타베이스가 포함되어 있는 경우가 있다. 가라오케 디스크 위에의 그러한 텍스트로서는, 곡명, 아티스트명, 레코드 라벨등이 있다. 이 텍스트는, 복수의 언어로 존재할 수가 있다. 이러한 캐릭터 라인은 옵션이며, 디스크상에 반드시 포함하지 않으면 안 되는 것은 아니다. 캐릭터 라인이 포함되는 경우는, DVD 볼륨의 논리적인 계층을 엄밀하게 반영하도록(듯이) 구성된다. 각 캐릭터 라인의 전에는, 그 캐릭터 라인이 디스크 구조의 어느 부분에 속하는지를 식별해, 캐릭터 라인의 내용의 단서가 되는 것 같은 숫자가 부가된다. 캐릭터 라인의 형태의 일부가 DVD_TextStringType 열거에 정의되고 있다.

텍스트 캐릭터 라인에는, 기본적인 형태로서 구조 식별자와 내용 캐릭터 라인의 2 개가 있다. 0x01 ~ 0x20 의 값을 가지는 형태가 구조 식별자이다. 이것은 하늘의 캐릭터 라인이며, 수치 코드는 그 후에 계속되는 내용 캐릭터 라인이 속하는 논리 구조를 식별하기 위해서 사용된다. 이 구조는, DVD 디스크의 내용 (볼륨, 타이틀, 쳅터등)의 논리 구조라든지 되어 엄밀에 대응하고 있다. 이제(벌써) 한편의 형태는, 유저 인터페이스로 시청자에게 표시되는 정보를 보관 유지하는 내용 캐릭터 라인을 식별한다. 내용 캐릭터 라인의 사용 방법은 엄밀하게는 정의되어 있지 않기 때문에, DVD 생성자는 다양한 방법으로 그것을 사용할 수 있다.

지금까지, DVD 텍스트 캐릭터 라인은 거의 가라오케 디스크 전용에 사용되어 왔다. 이러한 디스크는, 대부분의 경우, 0x01 로 0x02 의 구조 식별자와 0x30 의 내용 캐릭터 라인을 사용하고 있다. 그러나, 때가 경과하는 것에 따라, 보다 많은 종류의 DVD-Video 디스크에 텍스트 캐릭터 라인이 포함되게 된다고 생각하는 것이 타당하다. 이러한 캐릭터 라인은, 보다 복잡하게 구성되어 디스크 내용의 상세한 기술을 제공하게 될 것이다.

DVD 텍스트 캐릭터 라인에 대해서는, DVD 포럼의 Web 사이트 (www.dvdforum.org)를 참조할것.

DVD 샘플 어플리케이션의 CDvdCore::GetDvdText 메소드에, DVD 텍스트 캐릭터 라인을 열거해 표시하는 기본적인 순서가 나타나고 있다.

가라오케 오디오 스트림의 재생

DVD 네비게이터는, 가라오케 오디오 스트림을 포함한 DVD-Video 디스크를 재생할 수 있지만, 가라오케의 재생에는 멀티 채널 가라오케 믹싱을 지원 하는 디코더도 필요하다. 구체적으로 말하면, 이 디코더는 DVD 가라오케 프로퍼티 세트 (AM_KSPROPSETID_DvdKaraoke)를 지원 할 필요가 있다.

가라오케 디스크는 DVD-Video 디스크의 일종이며, 같은 조작 구조를 가지고 있다. 곡은 일반적으로 타이틀로서 포맷 되어 타이틀은 연주자나 음악 스타일등의 조건에 근거해 타이틀 세트에 그룹화 할 수 있다. 가라오케 디스크와 다른 종류의 DVD-Video 와의 주된 차이는, 오디오 스트림이다. 모든 가라오케 디스크에는, 멀티 채널 오디오 (보통은 Dolby AC-3)가 포함되어 있다. 채널 0 및 1 에는 항상 백그라운드의 연주가 포함되어 채널 2 ~ 5 에는 각각 가이드 보컬, 가이드 멜로디, 사운드 이펙트의 임의의 편성을 포함할 수가 있다. 가라오케 어플리케이션은, 각 보조 채널에 대해 볼륨과 출력처 스피커를 제어할 수 있다.

DVD 네비게이터는 디스크상에 가라오케 컨텐츠를 검출해 가라오케 모드에 들어가면(자), 디코더에 그것을 통지해, 디코더는 어플리케이션에 의해 명시적으로 온으로 될 때까지 상위 3 개의 채널 (보조 채널)을 무음 상태로 한다. 가라오케 어플리케이션의 기본적인 동작은 다음과 같다.

  1. IDvdInfo2 메소드를 사용해 보조 채널의 수와 그 내용을 확인한다.
  2. IDvdControl2::SelectKaraokeAudioPresentationMode 를 사용해, 채널의 내용을 표시해 유저가 언제라도 임의의 보조 채널을 온 또는 오프로 할 수 있도록(듯이) 하는 유저 인터페이스를 제공한다.

이러한 순서는, DVD 샘플 어플리케이션의 DVDCore.cpp 의 GetAudioAttributes 메소드에 나타나고 있다.

DVD 커멘드의 동기화

여기에는, 이하의 서브 주제가 포함된다.

  • 커멘드의 동기화에 대해
  • 어프로치 1 : 동기화 없음
  • 어프로치 2 : 동기화 없음의 단순한 블로킹
  • 어프로치 3 : 동기화 오브젝트만을 사용
  • 어프로치 4 : 이벤트를 사용한 한 번에 1 커멘드의 동기화
  • 어프로치 5 : 이벤트와 IDvdCmd 오브젝트를 사용한 동기화

커멘드의 동기화에 대해

커멘드의 동기화는, DVD 네비게이터 및 일반적인 DVD 의 조작에 정통한 개발자를 위한 고도의 주제이며, 어플리케이션으로 커멘드의 동기화에 의한 세련된 기능을 필요로 하는 경우에 도움이 된다. 아직 DVD 네비게이터를 사용하기 시작했던 바로 직후인 경우나, 어플리케이션으로 커멘드의 동기화를 필요로 하지 않는 경우에는, 단지 어프로치 1 에 나타나는 각종의 재생 커멘드를 사용한다. 커멘드의 동기화는, 나중에 언제라도 도입할 수가 있다.

IDvdControl2 의 각종의 재생 메소드 (PlayTitle 등)는, 본질적으로 비동기이다. 메소드가 불려 가면(자), 필요한 모든 순서를 실행하기 전에, 메소드는 즉시 결과를 돌려준다. 메소드 호출이 정상적으로 결과를 돌려주고 나서 그 동작이 최종적으로 완료할 때까지 , 다른 커멘드가 실행되어 DVD 네비게이터가 새로운 DVD 도메인 또는 새로운 필터 상태에 들어가, 메소드가 모든 필요한 순서를 정상적으로 완료할 수 없는 경우가 있다. 예를 들어, 어플리케이션이 PlayTitle 를 호출해, 그 후 곧바로 유저가 정지 버튼을 클릭했다고 한다. 커멘드가 동기화되어 있지 않으면 DVD 네비게이터는, 디스크가 지정된 위치에서 재생을 시작 하기 전에 DVD 정지 도메인에 들어가는 경우가 있다. 이것은, 전체의 동작이 실행되기 전에 PlayTitle 가 정상적으로 결과를 돌려주기 때문에 있다. 최종적으로 디스크가 재생을 시작 했을 때에, DVD 네비게이터가 이미 올바른 상태가 아니게 되고 있어, 에러가 생기는 경우가 있다.

많은 메소드 호출이 특정 상태의 DVD 네비게이터에게 의존하고 있기 (위해)때문에, 어플리케이션은 커멘드를 동기화하는 방법을 필요로 한다. 이것에는 다음의 2 개의 기본적인 기능이 포함된다.

  • 비동기 동작이 실제로 완료했을 때에 그것을 인식해, 최종적인 결과가 무엇으로 있는지를 인식한다. 이것은, 동작이 정상적으로 시작 되었는지 어떠했는지를 식별할 뿐(만큼)의 메소드 호출의 반환값과는 다르다.
  • 동작이 완료할 때까지 DVD 네비게이터가 이후의 커멘드를 처리하지 않게 블록 할 수가 있다.

DVD 네비게이터는 어플리케이션에 이러한 기능을 제공해, 커멘드의 동기화를 위한 몇개의 옵션을 제공한다. IDvdControl2 의 각 재생 메소드에는 동기화를 위한 파라미터가 2 개 있다. 1 개(살)은 동기화 오브젝트에의 인터페이스 포인터이며, 이제(벌써) 1 개(살)은 DVD 커멘드 플래그세트이다. 어플리케이션은 이러한 파라미터를 사용해, 커멘드의 동기화를 필요하게 응한 다양한 방법으로 이행 할 수 있다.

어프로치 1 : 동기화 없음

메소드 호출의 비동기의 성질을 보관 유지하려면 , 다음의 구문을 사용한다. 여기서,pDVDControl2 은 IDvdControl2 포인터이다.

HRESULT hres = pDVDControl2->PlayTitle( uTitle,
                                        DVD_CMD_FLAG_None, // = 0
                                        NULL);

어프로치 2 : 동기화 없음의 단순한 블로킹

이 어프로치에서는, DVD 커멘드 플래그를 사용해, 커멘드 동기화 오브젝트를 관리하지 않는 단순한 블로킹을 실현한다. 이것은, 동기화 오브젝트를 관리하거나 이벤트 통지를 처리할 필요가 없기 때문에, 가장 간단한 커멘드의 동기화 방법이지만, 특정의 커멘드의 귀가 상태를 결정할 수 없다.

HRESULT hres = pDVDControl2->PlayTitle( uTitle,
                                        EC_DVD_CMD_FLAG_Block,
                                        NULL);

어프로치 3 : 동기화 오브젝트만을 사용

이 어프로치는, 기능적으로는 어프로치 2 로 등가이다. 이벤트 통지를 처리하지 않고 직접 DVD 네비게이터를 블록 하는 다른 방법을 제공한다. 어플리케이션이 IDvdCmd 포인터의 주소를 건네주면(자), 이 특정의 커멘드에 관련하는 커멘드 동기화 오브젝트를 받는다. 오브젝트의 WaitToEnd 함수를 호출하면, 메소드가 정상적으로 완료할 때까지 DVD 네비게이터가 블록 된다. 그 사이, 새로운 커멘드가 큐에 추가되는 경우가 있다. 오브젝트는, 다 사용했으면 반드시 해방해야 한다.

IDvdCmd* pObj;
HRESULT hr = pDVDControl2->PlayTitle( uTitle,  0, &pObj);
if(SUCCEEDED(hr))
{
    pObj->WaitToEnd();
    pObj->Release();
}

어프로치 4 : 이벤트를 사용한 한 번에 1 커멘드의 동기화

IDvdControl2::SetOption 의 호출로 EC_DVD_CMD_FLAG_SendEvents 플래그를 지정하는 것으로써, DVD 네비게이터는 "재생 " 메소드 호출에 대해서는 블록 되지 않는다. 그 대신해, 커멘드의 시작시, 및 그 비동기 동작의 전체가 완료했을 때에, 어플리케이션에 EC_DVD_CMD_START 및 EC_DVD_CMD_END 이벤트 통지를 송신한다. 이것에 의해,IDvdCmd 오브젝트를 관리하지 않고 단일의 이벤트를 동기화할 수가 있다. 그러나,IDvdCmd 오브젝트를 사용하지 않기 때문에, 이벤트가 어느 커멘드에 관련한 것일까를 정확하게 알 수 없다. 많은 상황에 있어서는, 그러한 정보는 필요하게 되지 않기 때문에, 이 어프로치로 충분하다.

// "SendEvents" 를 사용해 PlayChapterInTitle 를 호출한다.
HRESULT hres = pDVDControl2->PlayChapterInTitle( uTitle, 0x2,
                    DVD_CMD_FLAG_SendEvents, NULL);
…
// 이벤트 통지 핸들러 함수에 대해
switch (lEvent)
{
   case EC_DVD_CMD_END:
     DoSomethingGeneric();
     break;
}

어프로치 5 : 이벤트와 IDvdCmd 오브젝트를 사용한 동기화

이 어프로치는, 커멘드의 동기화에 대해 최고의 제어를 얻을 수 있지만, 이행이 가장 복잡한 어프로치이기도 하다. 어플리케이션은, 이벤트가 어느 커멘드에 관련지을 수 있고 있을까를 알 수 있기 (위해)때문에, EC_DVD_CMD_END 이벤트에의 응답을 적당 조정할 수 있다. 최초의 예에 싱글스 레드의 솔루션을 나타내, 2 번째의 예에 multi-thread의 솔루션을 나타낸다.

// 글로벌 코드에 대해
IDvdCmd* pGlobalObj=0;
…
// pGlobalObj 는 이벤트가 발행되기 "전" 에 Navigator 에 의해
// 할당할 수 있다. 그렇게 하지 않으면 pGlobalObj 를 할당할 수 있기 전의
// (*1)(으)로 이벤트가 발생할 가능성이 있다.
HRESULT hres = pDVDControl2->PlayTitle( uTitle,
DVD_CMD_FLAG_SendEvents, &pGlobalObj );
// (*1)
If( FAILED( hres)) {
pGlobalObj = NULL;
}
…
switch (lEvent)
{
case EC_DVD_CMD_END:
   IDvdCmd* pObj = GetDvdCmd( lParam1 );
   HRESULT hres = HRESULT( lParam2 );
If( NULL ! = pObj ) {
    If(pGlobalObj == pObj ) {
…
pGlobalObj->Release();
pGlobalObj = NULL;
}
pObj->Release();
   }
break;

이 어프로치는, 이벤트 루프가 다른 thread에 존재할 경우에 사용한다.

// 글로벌 코드에 대해
IDvdCmd* pGlobalObj=0;
CcritSect globalCritSect;
…
{
CautoLock(globalCritSect );
HRESULT hres = pDVDControl2->PlayTitle( uTitle,
DVD_CMD_FLAG_SendEvents, &pGlobalObj );
If( FAILED( hres)) {
pGlobalObj = NULL;
}
}
…
switch (lEvent)
{
case EC_DVD_CMD_COMPLETE:
case EC_DVD_CMD_CANCEL:
{
CautoLock(globalCritSect );
IDvdCmd* pObj = GetDvdCmd( lParam1 );
HRESULT hres = HRESULT( lParam2 );
If( NULL ! = pObj ) {
If(pGlobalObj == obj ) {
…
pGlobalObj->Release();
pGlobalObj = NULL;
}
pObj->Release();
}
break;
}

DVD 커멘드 플래그

SetOption 의 dwFlags 파라미터에게 건네지는 DVD 커멘드 플래그는, 동기화 오브젝트에 가세해, 또는 동기화 오브젝트 대신에 사용된다. 이것은, 특정의 메소드 호출에 대해서 어느 어프로치를 사용할까에 따라서 다르다. DVD_CMD_FLAG_Block 의 사용은 어프로치 2 에 나타나 DVD_CMD_FLAG_SendEvents 는 어프로치 4 ~ 6 에 나타나고 있다. 이러한 플래그는 모두, 다른 플래그 DVD_CMD_FLAG_Flush 와 비트 단위의 OR 로 결합할 수도 있다. 이 플래그는, 메소드가 즉시 실행되어 필터 그래프의 버퍼내의 1 ~ 2 초의 비디오가 재생되는 것을 기다리지 않게 한다. 이 플래그를 지정 하면, 유저 입력에의 응답 시간이 짧아진다. 다음의 커멘드가 실행되기 전에 특정의 비디오 세그먼트(segment)를 완전하게 종료시킬 필요가 있는 경우에는, 이 플래그는 사용하지 않는다. 4 개의 플래그와 각각의 의미를 다음 표에 나타낸다.

이름 | 수치 | 의미
DVD_CMD_FLAG_None | 0x00000000 | 플래그 없음. 다음의 커멘드의 전에 버퍼를 플래시 하지 않고, 동작의 완료시에 이벤트를 발행하지 않고, DVD 네비게이터는 메소드가 결과를 돌려준 후에 블록 되지 않는다.
DVD_CMD_FLAG_Flush | 0x00000001 | 버퍼를 비워, 새로운 위치로부터 즉시 재생을 시작 한다.
DVD_CMD_FLAG_SendEvents | 0x00000002 | 어플리케이션에 이벤트를 돌려 보내는 것으로 비동기 동작의 완료와 그 반환값을 통지하도록(듯이), DVD 네비게이터에게 지시한다.
DVD_CMD_FLAG_Block | 0x00000004 | 비동기 동작이 완료할까 삭제될 때까지 DVD 네비게이터를 블록 한다.

디스크의 꺼내 처리

유저가 DVD 를 드라이브로부터 꺼내면(자), DVD 네비게이터는 어플리케이션에 EC_DVD_DISC_EJECTED 메세지를 송신한다. 어플리케이션은 이 메세지를 무시해도 문제 없고, DVD 네비게이터에게 그래프 상태를 관리시킨다. 또, 어플리케이션은, EC_DVD_DISC_EJECTED 메세지를 처리해, 디스크의 꺼내 때에 커스텀 동작을 실현할 수도 있다. 메세지를 처리하는 경우는,SetOption 메소드로 DVD_ResetOnStop 플래그를 TRUE 로 설정하고 나서, 어플리케이션을 닫을까 다른 디스크를 재생하기 전에,IMediaControl::Stop 를 호출할 필요가 있다.


C++ DVD 에 관한 참조 페이지로의 쇼트 컷

C++ 로 DVD 어플리케이션을 기술하는 경우에는, 일반적으로 이하의 인터페이스가 사용된다.
인터페이스 | 목적
IAMLine21Decoder | 자막 방송 표시를 제어한다.
IDvdCmd | 고도의 커멘드 동기화 기법에 대해 커멘드 오브젝트의 제어에 사용된다.
IDvdControl2 | DVD 네비게이터 필터에 커멘드를 투입한다 ("set" 메소드).
IDvdGraphBuilder | DVD 필터 그래프를 생성 한다.
IDvdInfo2 | 스테이트 정보 및 디스크 정보에 대해 DVD 네비게이터에게 문의한다 ("get" 메소드).
IDvdState | 북마크등의 정보를 디스크에 보존한다.
IVideoFrameStep | "스탭핑(Stepping)" 를 제어한다 (디코더로 지원 되고 있는 경우).


스크립트 베이스의 DVD 어플리케이션의 기술

여기에서는, MSWebDVD ActiveX® 컨트롤을 사용해 스크립트 베이스의 DVD 어플리케이션을 기술하는 경우의 기본적인 작업에 대해 설명한다. 이하로 말하는 DVD 조작의 개념에 관한 배경 지식에 대해서는, 「DVD 의 기초」를 참조할것.

  • MSWebDVD 오브젝트의 매입
  • 유저가 DVD 커멘드를 발행할 수 있도록(듯이) 한다
  • DVD 메뉴의 조작
  • 오디오 스트림과 서브 픽쳐 스트림
  • 페어 렌탈 락 레벨의 적용
  • 북마크의 보존과 복원
  • DVD 이벤트 통지의 처리
  • UOP 이벤트 통지의 처리
  • HTML 컨텐츠와 비디오의 동기화
  • LCID 의 조작
  • 가라오케 디스크의 재생
  • DVD 텍스트 캐릭터 라인의 조작

MSWebDVD 오브젝트의 매입

MSWebDVD 오브젝트에 의해, 모든 DVD 조작 커멘드 및 비디오 직사각형 표시가 처리된다. 오브젝트는, 비디오 표시 직사각형으로서 Web 페이지에 표시된다. 따라서, HTML 문서의 BODY 요소에 묻을 필요가 있다. 직사각형의 폭과 높이, 및 어플리케이션에 필요한 모든 프로퍼티의 디폴트값을 설정한다.

<OBJECT CLASSID=clsid:38EE5CEE-4B62-11D3-854F-00A0C9C898E7 ID=DVD
STYLE="height:369px; width:740px">
<PARAM NAME="BackColor" VALUE="1048592">
<PARAM NAME="EnableResetOnStop" VALUE="-1">
<PARAM NAME="ColorKey" VALUE="1048592">
</OBJECT>

유저가 DVD 커멘드를 발행할 수 있도록(듯이) 한다

유저가 DVD 플레이어를 제어할 수 있도록(듯이) 하려면 , "Stop" 나 "Play" 등의 DVD 커멘드를 발행하기 위한 버튼이 붙은 UI 를 생성 할 필요가 있다. 다음의 코드예에서는, 기본적인 HTML 버튼을 MSWebDVD 오브젝트 메소드에 묶는 방법을 나타낸다.

<INPUT ID=button1 NAME="button1" TYPE=button VALUE="Play" onClick='Play();'>
<INPUT ID=button2 NAME="button2" TYPE=button VALUE="Pause" onClick='Pause();'>

<SCRIPT LANGUAGE="JScript">
function Play(){
     DVD.Play();
}

function Pause(){
DVD.Pause();
}

</SCRIPT>

DVD 메뉴의 조작

유저가 마우스로 화면상의 버튼을 클릭 하면, MSWebDVD 는 자동적으로 메뉴 커멘드를 처리한다. 기본적인 마우스의 지원을 이행 하기 위해서, 어플리케이션으로 무엇인가 실시할 필요는 없다. 그러나, 메뉴 버튼의 클릭으로 다른 동작을 하도록(듯이) 하기 위해서, 이 자동적인 마우스의 처리를 어플리케이션에 의해 무효로 할 수 있다. 예를 들어, 유저가 클릭한 버튼에 응해, 특정의 텍스트 또는 이미지를 표시시킬 수가 있다. 커스텀 마우스 처리를 이행 하려면 ,SelectAndActivateButton ,GetButtonAtPosition 등의 MSWebDVD 메뉴 관련 메소드를 사용한다. 자동적인 마우스의 처리를 완전하게 무효로 하려면 ,DisableAutoMouseProcessing 프로퍼티를 TRUE 로 설정한다.

MSWebDVD 에서는,SelectUpperButton 등의 메소드세트에 의해, DVD 리모트 콘트롤을 나타내는 이미지 맵, 및 현재의 메뉴를 상하 좌우에 움직이기 위한 버튼을 Web 페이지에 표시시킬 수가 있다. 문서 중(안)에서는, 이러한 버튼을 "방향 " 버튼 또는 "상대 " 버튼이라고 부르고 있다. DVD 메뉴의 버튼과는 달라, 방향 버튼은 어플리케이션에 의해 표시된다.

오디오 스트림과 서브 픽쳐 스트림

DVD-Video 디스크에는 최대 8 개의 오디오 스트림을 포함할 수가 있다. 이것에는 0 에서 7 까지의 번호를 붙일 수 있어 각각 6 개(살)까지의 독립한 채널을 가진다. 이러한 쳐, 동시에 선택할 수 있는 것은 1 개의 스트림 뿐이다. 서브 픽쳐의 경우는, 최대로 32 개의 스트림을 사용할 수 있어 0 에서 31 까지의 번호를 붙일 수 있고 있다. 이러한 쳐, 동시에 선택할 수 있는 것은 1 개의 스트림 뿐이다. 일반적으로, 디스크는 디폴트의 오디오 및 서브 픽쳐 스트림을 사용해 생성 되고 있지만, 어플리케이션에 의해, 특정의 타이틀에 대해서 사용 가능한 스트림을 유저에게 모두 표시해, 희망하는 언어의 스트림을 선택시킬 수도 있다. 이 프로세스에 있어서의 기본적인 순서는, 오디오 스트림의 경우도, 서브 픽쳐 스트림의 경우도 같다.

  1. 지정된 타이틀에 대해서 사용 가능한 스트림의 수를 결정한다.
  2. 각 스트림을 차례로 봐, 각각의 스트림 속성을 취득한다.
  3. 돌려주어진 로케일 식별자 (LCID)로부터 언어 코드를 취득해, 인간이 읽을 수 있는 캐릭터 라인을 생성 한다.
  4. 유저가 희망의 스트림을 선택할 수 있도록(듯이), "선택 " 박스나 그 외의 유저 인터페이스 컨트롤을 설정한다.

(오디오 및 서브 픽쳐 스트림에는 0 으로부터 번호를 붙일 수 있고 있는데 대해, 타이틀, 앵글, 및 페어 렌탈 락 레벨에는 1 으로부터 번호를 붙일 수 있고 있는 것에 주의한다)

페어 렌탈 락 레벨의 적용

DVD-Video 디스크의 타이틀이나 타이틀의 일부에는, 일반적인 페어 렌탈 락 레벨 (PML) 1 에서 8 까지를 할당할 수가 있다. 8 은 가장 제한의 강한 레벨로, 0 은 가장 제한의 약한 레벨이다. 이것은, 부모의 승낙없이 아이가 성인전용 컨텐츠를 보는 것을 막는 방법을 제공 하면 말하는 생각이다. 각 레벨의 의미는 나라에 의해 다르다. 미국과 캐나다에서는, Motion Picture Association of America 의 레이팅 시스템 (G, PG, PG-13, NC-17)에 레벨을 할당하고 있지만, 다른 나라에서는 사정이 다르다. 국제적인 시장용의 DVD 어플리케이션에서는, 페어 렌탈 락 논리에 특정의 레이팅 시스템을 하드 코드 해서는 안된다.

MSWebDVD 오브젝트는, 디폴트로 디스크 위에의 PML 를 무시한다. 디스크 위에의 PML 마커가 통지되는 어플리케이션의 경우는, NotifyParentalLevels(TRUE)를 호출할 필요가 있다. 그것에 의해 MSWebDVD 는, 디스크상에서 PML 정보를 검출했을 때에 어플리케이션에 통지하게 된다. PML 를 적용하려면 , 유저와 레벨을 관련짓는 어떠한 패스워드 제어 논리를 어플리케이션에 이행 해,EC_DVD_PARENTAL_LEVEL_CHANGE 이벤트에 응답해 액세스의 허가 또는 거부를 적절히 실시하지 않으면 안 된다.

북마크의 보존과 복원

북마크란, 현재의 유저 세션의 snapshot (디스크 위에의 현재 위치, DVD 를 보고 있는 유저의 페어 렌탈 락 레벨, 선택된 오디오 및 서브 픽쳐 스트림, 그 외의 정보)를 생성 하기 위해서 MSWebDVD 오브젝트가 사용하는 내부 데이터 구조이다. 즉, 유저는 DVD-Video 디스크 위에의 위치를 보존해, 다음에 그 위치로부터 재생할 수가 있다.

유저는,SaveBookmark 에 의해 디스크 위에의 위치를 보존해,RestoreBookmark 메소드에 의해 보존한 위치로부터 재생을 재개할 수 있다.

한 번에 보존으로 할 수 있는 북마크는 1 개뿐이다. SaveBookmark 를 2 회 호출하면, 최초의 북마크가 오버라이드(override) 된다. 북마크는, 컴퓨터에 고유의 것이다. 같은 HTML 페이지를 다른 컴퓨터로 동작시켜 RestoreBookmark 를 호출하면, 그 컴퓨터로 마지막에 보존된 북마크가 복원된다. 북마크가 보존되어 있지 않은 경우는 에러가 돌려주어진다.

DVD 이벤트 통지의 처리

MSWebDVD 오브젝트는, 특정의 이벤트가 발생했을 때에, 어플리케이션으로 지정된 메소드에 통지를 송신한다. 이것은, DVD 도메인이 변경되었을 경우, 새로운 페아렌타르록크레베를 검출했을 경우, 및 앵글 블록에 들어가는 경우 등이다. 이벤트 파라미터에는, 이벤트에 관한 추가 정보를 포함할 수가 있다. 에러 메세지나 경고도 같은 방법으로 송신된다. 다양한 DVD 이벤트 통지를 취득하려면 , MSWebDVD 오브젝트의 OBJECT 태그아래에 다음의 HTML SCRIPT 태그를 입력한다.

<SCRIPT LANGUAGE="JScript" FOR=DVD EVENT="DVDNotify(EventCode, Param1, Param2) ">
    ProcessDVDEvent(EventCode, Param1, Param2)
</SCRIPT>

계속되어, 다음의 코드예에 나타내도록(듯이), 스크립트에 대해 이벤트 코드 및 ProcessDVDEvent 함수를 정의한다. (이벤트 처리 함수에는 임의의 이름을 붙일 수가 있다. "ProcessEvents" 일 필요는 없다. ) 이벤트 코드의 상세한 것에 대하여는, 「DVD 이벤트 통지 코드」를 참조할것.

<SCRIPT LANGUAGE="JScript">

// DVD 이벤트 코드에는, 257 에서 283 까지의 값이 설정되어 있다.
var EC_DVDBASE = 256;

var EC_DVD_DOMAIN_CHANGE = (EC_DVDBASE + 1);
var EC_DVD_TITLE_CHANGE = (EC_DVDBASE + 2);
var EC_DVD_CHAPTER_START = (EC_DVDBASE + 3);
var EC_DVD_AUDIO_STREAM_CHANGE = (EC_DVDBASE + 4);
var EC_DVD_SUBPICTURE_STREAM_CHANGE = (EC_DVDBASE + 5);
var EC_DVD_ANGLE_CHANGE  = (EC_DVDBASE + 6);
var EC_DVD_BUTTON_CHANGE = (EC_DVDBASE + 7);
var EC_DVD_VALID_UOPS_CHANGE = (EC_DVDBASE + 8);
var EC_DVD_STILL_ON  = (EC_DVDBASE + 9);
var EC_DVD_STILL_OFF  = (EC_DVDBASE + 10);
var EC_DVD_CURRENT_TIME  = (EC_DVDBASE + 11); // MSWebDVD 에서는 사용하지 않는다
var EC_DVD_ERROR  = (EC_DVDBASE + 12);
var EC_DVD_WARNING  = (EC_DVDBASE + 13);
var EC_DVD_CHAPTER_AUTOSTOP  = (EC_DVDBASE + 14);
var EC_DVD_NO_FP_PGC  = (EC_DVDBASE + 15);
var EC_DVD_PLAYBACK_RATE_CHANGE  = (EC_DVDBASE + 16);
var EC_DVD_PARENTAL_LEVEL_CHANGE  = (EC_DVDBASE + 17);
var EC_DVD_PLAYBACK_STOPPED  = (EC_DVDBASE + 18);
var EC_DVD_ANGLES_AVAILABLE  = (EC_DVDBASE + 19);
var EC_DVD_PLAYPERIOD_AUTOSTOP  = (EC_DVDBASE + 20);
var EC_DVD_BUTTON_AUTO_ACTIVATED  = (EC_DVDBASE + 21);
var EC_DVD_CMD_START  = (EC_DVDBASE + 22);            // MSWebDVD 에서는 사용하지 않는다
var EC_DVD_CMD_END = (EC_DVDBASE + 23);               // MSWebDVD 에서는 사용하지 않는다
var EC_DVD_DISC_EJECTED  = (EC_DVDBASE + 24);
var EC_DVD_DISC_INSERTED  = (EC_DVDBASE + 25);
var EC_DVD_CURRENT_HMSF_TIME  = (EC_DVDBASE + 26);
var EC_DVD_KARAOKE_MODE  = (EC_DVDBASE + 27);

var nCurDomain;
var nCurParentalLevel;

function ProcessDVDEvent(EventCode, Param1, Param2)
{
switch (EventCode)
  {
case EC_DVD_DOMAIN_CHANGE:
nCurDomain = Param1;
// 무엇인가 실시한다.
break;
case EC_DVD_PARENTAL_LEVEL_CHANGE:
nCurParentalLevel = Param1;
// 무엇인가 실시한다
break;

// 다른 이벤트를 처리한다

default:
break;
  }

}
</SCRIPT>

UOP 이벤트 통지의 처리

MSWebDVD 오브젝트는, 디스크에 의해 특정의 유저 동작 (UOP)이 유효 또는 무효가 되었을 때에, UOP 이벤트 통지를 송신해 어플리케이션에 알린다. 각 유저 동작에는 독자적인 이벤트가 있어, 그 동작이 유효한가 무효인지를 나타내는 1 개의 Boolean 파라미터가 설정되어 있다. 개개의 이벤트의 상세한 것에 대하여는, 「MSWebDVD 이벤트」를 참조할것.

처리 대상의 각 이벤트에 대해서, 다음의 예의 같게 이벤트 핸들러를 지정한다. (임의의 핸들러 메소드를 호출할 수가 있다. )

<SCRIPT LANGUAGE="JScript" FOR=DVD EVENT="PlayForwards(bEnabled) ">
    PlayForwardsEventHandler(bEnabled)
</SCRIPT>
다음에, 이벤트에 적절히 응답하도록(듯이) 핸들러 메소드를 정의한다. 여기에서는, "button_Play" 변수는 어플리케이션의 "Play" 버튼의 id 속성이라고 가정한다.
function PlayForwardsEventHander(bEnabled)
{
if(bEnabled == true)
button_Play.disabled = false;
else
button_Play.disabled = true;
}

HTML 컨텐츠와 비디오의 동기화

디스크로부터의 타임 코드 이벤트를 처리하는 것에 의해, Web 어플리케이션은 HTML 컨텐츠를 비디오와 동기화할 수 있다. 예를 들어, 비디오의 지정된 위치에서 페이지 위에의 이미지 또는 텍스트를 변경할 수가 있다. 다음의 코드예에 의해, JScript 함수 호출을 타임 코드 이벤트에 동기화 시키는 방법을 나타낸다.
//DVDTriggerPoints 배열은, 각 방아쇠의 프레임수를 보관 유지한다. 승순이 아니면 안된다.
//timecode2frames()를 사용해, 타임 코드 (hh:mm:ss:ff)를 프레임의 합계수로 변환한다.

var DVDTriggerPoints = new Array(
timecode2frames("01:15:24:00"),
timecode2frames("01:23:02:00"));

//DVDTriggerProcs 배열은, DVDTimePoints 로 정의된 각 방아쇠 포인트로 불려 가는 함수를 보관 유지한다.
var DVDTriggerProcs = new Array(
"showDogPic() ;",
"showCatPic() ;");

//DVDTriggerIndex 는 현재의 방아쇠 (DVDTriggerPoints 및 DVDTriggerProcs 를 나타낸다)를 파악한다.
var DVDTriggerIndex = 0;

//DVD 이벤트를 처리한다
function ProcessDVDEvent(EventCode, Param1, Param2) {
  switch (EventCode) {
case EC_DVD_CURRENT_HMSF_TIME:
          if(MSWebDVD.CurrentDomain == 4) {  //디스크가 재생중이 아니면, 체크는 필요없다.
             if (DVDTriggerIndex < DVDTimePoints.length) {  //체크해야 할 방아쇠 포인트는 남아 있을까?
currentDVDTime = (MSWebDVD.DVDTimeCode2bstr(Param1));
                 if (timecode2frames(currentDVDTime) >= DVDTriggerPoints[DVDTimeIndex]) {
// 방아쇠 포인트가 지나면(자), 관련하는 함수를 실행한다.
eval(DVDTriggerProcs[DVDTimeIndex++]);
                 }
             }
          }
break;

// 다른 이벤트를 처리한다.
   }
}

function timecode2frames(timeCode) {

   if (timeCode ! = "undefined") {
return timeCode.substring(0,2)*108000
+ timeCode.substring(3,5)*1800
+ timeCode.substring(6,8)*30
+ timeCode.substring(9,11);
   } else {
return 0;
   }
}

LCID 의 조작

LCID 즉 "로케일 식별자 " 는, 특정의 지리적인 범위를 식별할 수 있는, 몇개의 다른 값을 포함한 32 비트 데이터형이다. 이 내부값의 1 개가 "프라이머리 언어 ID" 이며, 이것에 의해 영어, 스페인어, 러시아어 등, 지역이나 로케일의 기본적인 언어를 식별한다.

2 개의 메소드 (SelectDefaultAudioLanguage 과 SelectDefaultSubpictureLanguage )에 대한 입력 파라미터로서 MSWebDVD 에는 완전하게 유효한 LCID 가 필요하다. 이것은 Windows® 로 인식되는 유효한 LCID 의 경우도 있으면, 인식되지 않는 LCID 의 경우도 있다. (호스트 시스템이, 폰트, 키보드 매핑등으로 실제로 로케일을 지원 하고 있을 필요는 없다. ) 다음 표에, 일반적인 LCID 및, 그다지 일반적이지 않은 LCID (Windows 가 디폴트에서는 인식하지 않는에도 불구하고 MSWebDVD 에 대해서 유효)를 나타낸다. 이것은, 사용할 수 있는 LCID 의 완전한 리스트는 아니다. Windows 가 인식하는 LCID 의 완전한 리스트 등, LCID 의 상세한 것에 대하여는, MSDN on-line document (http://msdn.microsoft.com )를 참조할것.
유효한 LCID 의 일부
아프리칸스어 | 0x0436 | 알바니아어 | 0x041c | 아라비아어 (알제리아) | 0x1401
아라비아어 (바레인) | 0x3c01 | 아라비아어 (이집트) | 0x0c01 | 아라비아어 (이라크) | 0x0801
아라비아어 (요르단) | 0x2c01 | 아라비아어 (쿠에이트) | 0x3401 | 아라비아어 (레바논) | 0x3001
아라비아어 (리비아) | 0x1001 | 아라비아어 (모로코) | 0x1801 | 아라비아어 (오만) | 0x2001
아라비아어 (카타르) | 0x4001 | 아라비아어 (사우디아라비아) | 0x0401 | 아라비아어 (시리아) | 0x2801
아라비아어 (튀니지) | 0x1c01 | 아라비아어 (아랍 수장국 연방) | 0x3801 | 아라비아어 (예멘) | 0x2401
바스크어 | 0x042d | 벨라루스어 | 0x0423 | 불가리아어 | 0x0402
카타로니아어 | 0x0403 | 중국어 (홍콩) | 0x0c04 | 중국어 (중화 인민 공화국) | 0x0804
중국어 (싱가폴) | 0x1004 | 중국어 (대만) | 0x0404 | 크로아티아어 | 0x041a
체코어 | 0x0405 | 덴마크어 | 0x0406 | 네델란드어 (벨기에) | 0x0813
네델란드어 (표준) | 0x0413 | 영어 (오스트레일리아) | 0x0c09 | 영어 (벨리즈) | 0x2809
영어 (캐나다) | 0x1009 | 영어 (카리브) | 0x2409 | 영어 (아일랜드) | 0x1809
영어 (자메이카) | 0x2009 | 영어 (뉴질랜드) | 0x1409 | 영어 (남아프리카공화국) | 0x1c09
영어 (트리니다드) | 0x2c09 | 영어 (영국) | 0x0809 | 영어 (미국) | 0x0409
에스토니아어 | 0x0425 | 펠로우어 | 0x0438 | 페르시아어 | 0x0429
핀란드어 | 0x040b | 프랑스어 (벨기에) | 0x080c | 프랑스어 (캐나다) | 0x0c0c
프랑스어 (룩셈부르크) | 0x140c | 프랑스어 (표준) | 0x040c | 프랑스어 (스위스) | 0x100c
독일어 (오스트리아) | 0x0c07 | 독일어 (리히텐슈타인) | 0x1407 | 독일어 (룩셈부르크) | 0x1007
독일어 (표준) | 0x0407 | 독일어 (스위스) | 0x0807 | 희랍어 | 0x0408
헤브라이어 | 0x040d | 헝가리어 | 0x040e | 아이슬랜드어 | 0x040f
인도네시아어 | 0x0421 | 이탈리아어 (표준) | 0x0410 | 이탈리아어 (스위스) | 0x0810
일본어 | 0x0411 | 한국어 | 0x0412 | 한국어 (Johab) | 0x0812
라트비아어 | 0x0426 | 리투아니아어 | 0x0427 | 말레이어 (말레이지아) | 0x043e
말레이어 (브루나이) | 0x083e | 노르웨이어 (브크모르) | 0x0414 | 노르웨이어 (니노시크) | 0x0814
폴란드어 | 0x0415 | 포르투갈어 (브라질) | 0x0416 | 포르투갈어 (표준) | 0x0816
루마니아어 | 0x0418 | 러시아어 | 0x0419 | 세르비아어 (키릴) | 0x0c1a
세르비아어 (라틴) | 0x081a | 슬로바키아어 | 0x041b | 슬로베니아어 | 0x0424
스페인어 (아르헨티나) | 0x2c0a | 스페인어 (볼리비아) | 0x400a | 스페인어 (칠레) | 0x340a
Spanish (Colombia) 스페인어 (콜롬비아) | 0x240a | 스페인어 (코스타리카) | 0x140a | 스페인어 (도미니카 공화국) | 0x1c0a
스페인어 (에콰도르) | 0x300a | 스페인어 (엘살바도르) | 0x440a | 스페인어 (과테말라) | 0x100a
스페인어 (온두라스) | 0x480a | 스페인어 (멕시코) | 0x080a | 스페인어 (현대) | 0x0c0a
스페인어 (니카라과) | 0x4c0a | 스페인어 (파나마) | 0x180a | 스페인어 (파라과이) | 0x3c0a
스페인어 (페루) | 0x280a | 스페인어 (푸에르 토르코) | 0x500a | 스페인어 (구래) | 0x040a
스페인어 (우루과이) | 0x380a | 스페인어 (베네주엘라) | 0x200a | 스와히리어 | 0x0441
스웨덴어 | 0x041d | 스웨덴어 (핀란드) | 0x081d | 타이어 | 0x041e
터키어 | 0x041f | 우크라이나어 | 0x0422 |  |

몇개의 MSWebDVD 메소드 및 프로퍼티는, 사운드 트랙 또는 자막으로 이용할 수 있는 언어를 나타내는 로케일 식별자 (LCID) 값을 돌려준다. 이 정보를 이용하려면 , 어플리케이션에 의해, 돌려주어진 LCID 로부터 프라이머리 언어 ID 를 추출할 필요가 있다. 그 때문에(위해)는,iLCID 의 값과 0x3FF 의 사이에 비트마다의 AND 연산을 실행한다. (프라이머리 언어 ID 는, LCID 의 최하정도의 10 비트에 포함되어 있다. ) 다음의 코드예에 의해, 그방법을 나타낸다.

iPrimaryLang = iLCID & 0x3FF;

프라이머리 언어 ID 로부터, 인간이 읽을 수 있는 캐릭터 라인을 취득하려면 , 다음의 예의 같게 GetLangFromLangID 를 호출한다.

sLanguage = DVD.GetLangFromLangID(iPrimaryLang);

LCID 및 언어의 식별자의 상세한 것에 대하여는, Microsoft® Platform SDK 를 참조할것.

다음 표에, 전의 겉(표)의 LCID 에 대한 프라이머리 언어 ID 를 나타낸다.

유효한 프라이머리 언어 ID 의 일부
아프리칸스어 | 0x36 | 알바니아어 | 0x1c | 아라비아어 | 0x01 | 바스크어 | 0x2d
벨라루스어 | 0x23 | 불가리아어 | 0x02 | 카타로니아어 | 0x03 | 중국어 | 0x04
크로아티아어 | 0x1a | 체코어 | 0x05 | 덴마크어 | 0x06 | 네델란드어 | 0x13
영어 | 0x09 | 에스토니아어 | 0x25 | 펠로우어 | 0x38 | 페르시아어 | 0x29
핀란드어 | 0x0b | 프랑스어 | 0x0c | 독일어 | 0x07 | 희랍어 | 0x08
헤브라이어 | 0x0d | 헝가리어 | 0x0e | 아이슬랜드어 | 0x0f | 인도네시아어 | 0x21
이탈리아어 | 0x10 | 일본어 | 0x11 | 한국어 | 0x12 | 라트비아어 | 0x26
리투아니아어 | 0x27 | 말레이어 | 0x3e | 노르웨이어 | 0x14 | 폴란드어 | 0x15
포르투갈어 | 0x16 | 루마니아어 | 0x18 | 러시아어 | 0x19 | 세르비아어 | 0x1a
슬로바키아어 | 0x1b | 슬로베니아어 | 0x24 | 스페인어 | 0x0a | 스와히리어 | 0x41
스웨덴어 | 0x1d | 타이어 | 0x1e | 터키어 | 0x1f | 우크라이나어 | 0x22

가라오케 디스크의 재생

가라오케 디스크는 DVD-Video 디스크의 일종이며, 같은 조작 구조를 가지고 있다. 곡은 일반적으로 타이틀로서 포맷 되어 타이틀은 연주자나 음악 스타일등의 조건에 근거해 타이틀 세트에 그룹화 할 수 있다. 가라오케와 다른 종류의 DVD-Video 와의 주된 차이는 오디오 스트림이다. 모든 가라오케 디스크에는, 멀티 채널 오디오 (보통은 Dolby AC-3)가 포함되어 있다. 채널 0 및 1 에는 항상 백그라운드의 연주가 포함되어 채널 2 ~ 5 에는 각각 가이드 보컬, 가이드 멜로디, 사운드 이펙트를 포함할 수가 있다. 가라오케 어플리케이션은, 각 보조 채널에 대해 볼륨과 출력처 스피커를 제어할 수 있다.

가라오케의 재생에는, DVD 네비게이터로부터 송신되는 멀티 채널 가라오케 믹싱 정보를 지원 하는 디코더도 필요하다. 구체적으로 말하면, 이 디코더는 DVD 가라오케 프로퍼티 세트 (AM_KSPROPSETID_DvdKaraoke)를 지원 할 필요가 있다.

DVD 네비게이터는 디스크상에 가라오케 컨텐츠를 검출해 가라오케 모드에 들어가면(자), 디코더에 그것을 통지해, 디코더는 어플리케이션에 의해 명시적으로 온으로 될 때까지 상위 3 개의 채널 (보조 채널)을 무음 상태로 한다. 가라오케 어플리케이션의 기본적인 동작은 다음과 같다.

  1. 보조 채널수와 그 내용을 확인한다.
  2. 채널의 내용을 표시해 유저가 언제라도 임의의 보조 채널을 온 또는 오프로 할 수 있도록(듯이) 하는 유저 인터페이스를 제공한다.

DVD 텍스트 캐릭터 라인의 조작

DVD 디스크, 특히 가라오케 디스크에는, 비디오 또는 오디오 컨텐츠를 보충하는 텍스트 정보의 데이타베이스가 포함되어 있는 경우가 있다. 가라오케 디스크 위에의 그러한 텍스트로서는, 곡명, 아티스트명, 레코드 라벨등이 있다. 이 텍스트는, 복수의 언어로 존재할 수가 있다. 이러한 캐릭터 라인은 옵션이며, 디스크상에 반드시 포함하지 않으면 안 되는 것은 아니다. 캐릭터 라인이 포함되는 경우는, DVD 볼륨의 논리적인 계층을 엄밀하게 반영하도록(듯이) 구성된다. 각 캐릭터 라인의 전에는, 그 캐릭터 라인이 디스크 구조의 어느 부분에 속하는지를 식별해, 캐릭터 라인의 내용의 단서가 되는 것 같은 숫자가 부가된다.

텍스트 캐릭터 라인에는, 기본적인 형태로서 구조 식별자와 내용 캐릭터 라인의 2 개가 있다. 0x01 ~ 0x20 의 값을 가지는 형태가 구조 식별자이다. 이것은 하늘의 캐릭터 라인이며, 수치 코드는 그 후에 계속되는 내용 캐릭터 라인이 속하는 논리 구조를 식별하기 위해서 사용된다. 이 구조는, DVD 디스크의 내용 (볼륨, 타이틀, 쳅터등)의 논리 구조라든지 되어 엄밀에 대응하고 있다. 이제(벌써) 한편의 형태는, 유저 인터페이스로 시청자에게 표시되는 정보를 보관 유지하는 내용 캐릭터 라인을 식별한다. 내용 캐릭터 라인의 사용 방법은 엄밀하게 정의되어 있지 않기 때문에, DVD 생성자는 다양한 방법으로 그것을 사용할 수 있다.

지금까지, DVD 텍스트 캐릭터 라인은 거의 가라오케 디스크 전용에 사용되어 왔다. 이러한 디스크는, 대부분의 경우, 0x01 로 0x02 의 구조 식별자와 0x30 의 내용 캐릭터 라인을 사용하고 있다. 그러나, 때가 경과하는 것에 따라, 보다 많은 종류의 DVD-Video 디스크에 텍스트 캐릭터 라인이 포함되게 된다고 생각하는 것이 타당하다. 이러한 캐릭터 라인은, 보다 복잡하게 구성되어 디스크의 내용의 상세한 기술을 제공하게 될 것이다.

다음의 코드에 의해, 디스크 위에의 텍스트 캐릭터 라인의 언어 블록의 수를 확인하는 방법, 및 유저가 언어를 선택할 수 있도록 표시하기 위한 인간이 읽을 수 있는 캐릭터 라인을 취득하는 방법을 나타낸다. 이 코드에서는, 캐릭터 라인은 "TextLanguageList" 로 불리는 HTML SELECT 요소에 추가된다. LCID 및 프라이머리 언어의 상세한 것에 대하여는, 「GetLangFromLangID 」를 참조할것.

function GetTextLanguages()
  {
//텍스트 블록의 수를 취득한다.
var numLangs = DVD.GetDVDTextNumberOfLanguages();
      var iLCID;
      var iPrimaryLang;
      var sLanguage;
      var oOption;

    for (j = 0; j < numLangs; j++)
    {
//언어 블록에 대한 로케일 식별자를 취득한다
        iLCID = DVD.GetDVDTextLanguageLCID(j);

//LCID 로부터 프라이머리 언어 ID 를 취득한다
        iPrimaryLang = iLCID & 0x3FF;

//프라이머리 언어 ID 로부터, 인간이 읽을 수 있는 캐릭터 라인을 취득한다
        sLanguage = DVD.GetLangFromLangID(iPrimaryLang);

//HTML  페이지 위에의 SELECT 요소에 추가한다
        oOption = document.createElement("OPTION");
        oOption.text = sLanguage;
        document.all.TextLanguageList.add(oOption);
    }

  } //함수 GetTextStrings 의 마지막

다음의 테스트 코드는, 캐릭터 라인을 열거해 텍스트 캐릭터 라인의 형태를 검사하는 방법을 나타내고 있다. 여기에서는, 수치 캐릭터 라인의 형태를 어떻게 사용해 내용 캐릭터 라인을 편성하는지를 이해하는 목적으로, 단지 결과를 "myTextArea" 로 불리는 HTML TEXTAREA 요소에 덤프 하고 있다. 실제의 어플리케이션에서는 독자적인 데이터 구조를 생성 해 캐릭터 라인을 보관 유지하는지, 또는 시청자에게 있어 편리한 방법으로 캐릭터 라인을 표시한다.

// iLanguage 는, 언어 블록에 대한 0 으로부터 시작되는 인덱스이다
function GetTextStrings(iLanguage)
   {
    var numStrings, stringType, j;
    numStrings = DVD.GetDVDTextNumberOfStrings(iLanguage);

    for( j = 0; j < numStrings; j++)
          {
      stringType = DVD.GetDVDTextStringType(iLanguage, j);

      if(stringType > 0x20) //실제로는 여기서 어떠한 텍스트를 읽어들인다
          {
        myTextArea.value += (stringType + ": " + DVD.GetDVDTextString(iLanguage, j) + "\n");
          }
      else // 볼륨 구조의 레벨을 나타내는 노드이다
            // 다음의 캐릭터 라인을 적용한다
          {
            myTextArea.value += (stringType + "\n");
          }

        }
   } //함수 GetTextStrings 의 마지막

DVD 텍스트 캐릭터 라인의 형태

다음 표에, DVD 텍스트 캐릭터 라인의 형태의 서브 세트의 일람을 나타낸다. 값이 0x20 이하의 모든 형태는 하늘의 캐릭터 라인이며, 디스크의 컨텐츠 데이터 구조에 있어서의 노드 레벨을 나타내는 것만으로 있다. 그 외의 캐릭터 라인은, 내용 캐릭터 라인이다. 대부분의 타이틀 및 곡명의 형태는 0x30 이다. Title, SubTitle, 및 Original 카테고리내의 형태에 의해, 특정의 장르를 상세하게 식별할 수 있다. 이러한 카테고리의 정확한 의미와 사용 목적은 공개 문서에 정의되고 있어 DVD 포럼의 Web 사이트 (www.dvdforum.org)로부터 다운로드할 수 있다.

구조 식별자
Volume | 0x01 | 후에 계속되는 캐릭터 라인이 DVD 볼륨에 관계하는 것을 나타낸다.
Title | 0x02 | 후에 계속되는 캐릭터 라인이 타이틀에 관계하는 것을 나타낸다.
ParentalID | 0x03 | 후에 계속되는 캐릭터 라인이 특정의 페어 렌탈 ID 에 관계하는 것을 나타낸다.
Chapter | 0x04 | 후에 계속되는 캐릭터 라인이 쳅터에 관계하는 것을 나타낸다.
Cell | 0x05 | 후에 계속되는 캐릭터 라인이 셀 (일반적으로 무비의 1 신)에 관계하는 것을 나타낸다.
스트림 식별자
Audio | 0x10 | 후에 계속되는 캐릭터 라인이 오디오 스트림에 관계하는 것을 나타낸다.
Subpicture | 0x11 | 후에 계속되는 캐릭터 라인이 서브 픽쳐 스트림에 관계하는 것을 나타낸다.
Angle | 0x12 | 후에 계속되는 캐릭터 라인이 앵글 블록에 관계하는 것을 나타낸다.
오디오 채널 식별자
Channel | 0x20 | 후에 계속되는 캐릭터 라인이 오디오 스트림의 1 개의 채널에 관계하는 것을 나타낸다.
일반적인 내용 캐릭터 라인
Name | 0x30 | 타이틀명, 쳅터명, 곡명 등에 대하는 가장 일반적인 식별자.
Comments | 0x31 | 타이틀, 쳅터, 곡에 관한 일반적인 코멘트.
타이틀 내용 캐릭터 라인
Series | 0x38 | 타이틀, 쳅터, 곡 등에 관한 추가 정보.
Movie | 0x39 | 무비의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Video | 0x3a | 비디오의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Album | 0x3b | 앨범의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Song | 0x3c | 곡의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Other | 0x3f | 다른 장르 또는 카테고리에 속하는 경우의 타이틀 또는 쳅터에 관한 추가 정보.
2차 타이틀 내용 캐릭터 라인
Series | 0x40 | 타이틀, 쳅터, 곡 등에 관한 추가 정보.
Movie | 0x41 | 무비의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Video | 0x42 | 비디오의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Album | 0x43 | 앨범의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Song | 0x44 | 곡의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Other | 0x45 | 다른 장르 또는 카테고리에 속하는 경우의 타이틀 또는 쳅터에 관한 추가 정보.
오리지날 내용 캐릭터 라인
Series | 0x48 | 타이틀, 쳅터, 곡 등에 관한 추가 정보.
Movie | 0x49 | 무비의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Video | 0x4a | 비디오의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Album | 0x4b | 앨범의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Song | 0x4c | 곡의 경우의 타이틀 또는 쳅터에 관한 추가 정보.
Other | 0x4f | 다른 장르 또는 카테고리에 속하는 경우의 타이틀 또는 쳅터에 관한 추가 정보.
그 외의 정보 내용 캐릭터 라인
Other Scene | 0x50 | 무비의 타이틀 또는 쳅터에 있어서의 대신의 장면에 관한 추가 정보.
Other Cut | 0x51 | 무비의 타이틀 또는 쳅터에 있어서의 대신의 컷에 관한 추가 정보.
Other Take | 0x52 | 무비의 타이틀 또는 쳅터에 있어서의 대신의 테이크에 관한 추가 정보.


MSWebDVD ActiveX 컨트롤

이하의 페이지에는, Microsoft® MSWebDVD ActiveX® 컨트롤에 의해 공개되는 오브젝트의 메소드와 프로퍼티에 대해 기술하고 있다.

오브젝트 | 목적
MSWebDVD | 모든 DVD 커멘드 및 쿼리를 제어한다.
MSDVDAdm | Windows 레지스트리의 디폴트 설정을 제어한다.
DVDRect | 각종의 MSWebDVD 메소드로 사용하는 직사각형을 정의한다.

「MSWebDVD 이벤트」에는,MSWebDVD ActiveX 컨트롤에 의해 어플리케이션에 송신되는 이벤트 통지에 대해 기술하고 있다.


DirectShow 의 MPEG-2 지원

이 항에서는, Microsoft® DirectShow® 를 사용해 MPEG-2 컨텐츠를 재생하기 위해서 사용 가능한 인터페이스와 컴퍼넌트에 대해 설명한다. MPEG-2 에서는, 간단한 파일 재생이 가능하고, 각종의 저장 포맷 (디스크나 떼어내 가능한 미디어)이 지원 되어 오쏘링을 필요로 하지 않는다. 소프트웨어 디코더는 MPEG-2 에 반드시 대응하고 있지만, 낡은 하드웨어 디코더의 일부에는 MPEG-2 에 대응하고 있지 않는 것이 있다. DVD 네비게이터와 IDVDGraphBuilder 컴퍼넌트 및 그 인터페이스를 사용해 DirectShow 로 DVD 베이스의 컨텐츠를 재생하는 방법에 대해서는, 「DVD 어플리케이션」을 참조할것. MPEG-2 의 재생으로 사용되는 인터페이스는,IGraphBuilder 과 IMediaControl 이며, DVD 고유의 IDVDGraphBuilder 와 IDvdControl2 는 아니다.

MPEG-2 재생용으로 DirectShow 가 제공하는 가장 중요한 컴퍼넌트는,MPEG-2 스플리터 필터이다 (DirectShow 의 이전의 버젼의 MPEG-1 스트림 스플리터 컴퍼넌트에 상당한다). DirectShow 는 MPEG-2 디코더를 제공하지 않는다. MPEG-2 스플리터 필터는, MPEG-2 PES (Packetized Elementary Streams)를 받아들이는 DirectShow 호환의 MPEG-2 오디오 디코더 및 MPEG-2 비디오 디코더와 함께 사용할 필요가 있다. 유저는, DirectShow 가 인식하는 MPEG-2 프로그램 스트림의 컨텐츠가 저장 된 파일 (. mpg 를 추천)을 더블 클릭 하는 것에 의해, MPEG-2 스플리터 필터에 의한 파일 재생을 액티브하게 할 수 있다.

상세한 것에 대하여는, 이하의 관련 주제를 참조할것.

  • MPEG-2 스플리터 필터의 사용
  • 타임 스탬프
  • MPEG 샘플의 프로퍼티
  • MPEG-2 커넬 미디어 타입


MPEG-2 스플리터 필터의 사용

MPEG-2 스플리터 필터는, 현재, 이하의 스트림 타입의 쳐 적어도 1 개(살)을 포함한 MPEG-2 프로그램 스트림의 프르모드 재생을 지원 한다.

  • MPEG-2 비디오
  • MPEG-2 오디오
  • DVD-Video 정의에 의해 encode 된 Dolby AC-3 오디오
  • DVD-Video 정의에 의해 encode 된 LPCM (Linear Pulse Code Modulated) 오디오

주 : MPEG-2 스플리터는, 트랜스폴트 스트림에 대응하고 있지 않다. 푸쉬 모드만으로 출력된 전송 스트림에 대해서는,MPEG-2 디멀티플렉서 를 사용한다.

MPEG 오디오의 사양의 상세한 것에 대하여는, 외부 링크 http://www.mpeg.org/MPEG/DVD/Book_B/Audio.html 를 참조할것.

프로그램 스트림내의 개개의 스트림을 처리할 수 있는 Microsoft® DirectShow® 호환의 디코더가 인스톨 되고 있는 경우, MPEG-2 스플리터 필터에서는 이러한 타입의 재생이 지원 된다. MPEG-2 스플리터 필터로 지원 되는 미디어 타입의 일람에 대해서는, 「MPEG-2 스플리터 필터 미디어 타입」을 참조할것.

MPEG-2 스플리터 필터의 사용의 상세한 것에 대하여는, 이하의 주제를 참조할것.

  • MPEG 의 타임 스탬프
  • 스트림의 선택
  • 지원 되는 인터페이스

MPEG 의 타임 스탬프

MPEG-2 프로그램 스트림을 재생 하면 와, MPEG-2 스플리터 필터는, 최초로 나타나는 시스템 클록 참조를, 스트림의 시간의 원점으로서 취급한다. 이 동작은, 프레젠테이션 시간 스탬프를 사용하는 MPEG-1 스트림 스플리터 필터와는 다르다. IAMParse::GetParseTime 메소드는, 처리한 데이터에 대응하는 스트림 시스템 클록 타임을 돌려준다 (추정값의 가능성이 있다) .

MPEG-2 스플리터 필터는, 불연속성의 프로퍼티가 설정된 입력 샘플이 있었을 경우 (불연속성의 프로퍼티는 IMediaSample::SetDiscontinuity 또는 IMediaSample2::SetProperties 로 설정할 수 있다), 데이터내의 최초의 팩까지 스킵 해, 그 팩의 시스템 클록 참조 (SCR)와 불연속의 전의 SCR 시간이 같은 것이라고 보여지도록(듯이), 그 타임 스탬프를 조정한다. SCR 클락이 전이나 후에 1 초를 넘어 점프 하고 있는 경우에는, (MPEG-2 프로그램 스트림의 사양에 따라) 이것도 불연속인 클락으로서 다루어져 다운 스트림 필터에 건너는 타임 스탬프로부터, 분명한 클락차이가 감산된다.

스트림의 선택

MPEG-2 프로그램 스트림을 재생할 경우에는, 프로그램 스트림을 주사 해 최초로 발견된 비디오 스트림과 오디오 스트림이 선택된다. 오디오 출력 핀과 비디오 출력 핀이, 각각 1 개(살)까지 지원 된다. IAMStreamSelect 인터페이스를 사용 하면, 같은 타입의 스트림을 복수 (시스템 헤더에 오디오의 상한으로서 지정된 수까지) 선택할 수 있다. MPEG-2 오디오의 경우, 현시점에서는, 스트림 0xC0 로부터 시작되는 연속한 스트림이 상정되고 있다.

지원 되는 인터페이스

MPEG-2 스플리터 필터는, 이하의 인터페이스를 지원 한다.

  • IAMParse —MPEG-2 프로그램 스트림만
  • IAMStreamSelect —MPEG-2 프로그램 스트림만, 오디오 스트림만
  • IMediaSeeking —바이트 모드의 시크를 포함한다


타임 스탬프

타임 스탬프의 상세한 것에 대하여는,ISO1-11172: "The packet header may contain decoding and/or presentation time stamps (DTS and PTS) that refer to the first access unit in the packet" 의 섹션 2.4. 1 을 참조할것.

MPEG_Stream 메이저 타입의 경우, 시작 타임은,1 초에 대해 1 바이트의 비율로 진행하는 최초의 바이트의 바이트 위치이다. 종료 타임은 마지막 바이트의 바이트 위치이다. 따라서, 연속하는 샘플의 사이에서는, 최초의 패킷의 종료 타임과 다음의 패킷의 시작 타임이 일치해야 한다. Video CD 데이터의 경우, 미디어의 원데이터는, 선두에 표준 RIFF 체크를 가지는, CDFS 에 의해 공개되는 Video-CD 파일의 포맷에 따르지 않으면 안 된다.

MPEG 비디오 패킷 타입 및 유료 하중 타입의 경우, 타임 스탬프는, 화면 시작 코드가 샘플내에서 시작되는 최초의 비디오 프레임의 프레젠테이션 시간이다.

MPEG 오디오 패킷 타입 및 유료 하중 타입의 경우, 타임 스탬프는, 세면대 코드가 샘플내에서 시작되는 최초의 오디오 프레임의 프레젠테이션 시간이다.

타임 스탬프가 없는 패킷 및 유료 하중 데이터는, 데이터를 처리하는 필터에 의해 문제 없고프리로르 되면(자) 상정되고 있다.


MPEG 샘플의 프로퍼티

MPEG 샘플에서는, 다음의 프로퍼티 또는 통지를 사용한다.

Time stamp | 일부의 샘플에는 시작 타임과 종료 타임이 설정되어 있지 않다. 패킷과 유료 하중 데이터의 샘플 종료 타임은, 보통, 시작 타임 플러스 1 으로 설정되지만, 이것은 도움이 되지 않는다. MPEG 패킷 또는 유료 하중 데이터의 샘플에서는, 샘플을 생성한 시스템 계층 패킷이 유효한 PTS 를 가지고 있었을 경우에게만 시작 타임과 종료 타임이 설정된다.
Discontinuity | 예를 들어, 리얼타임 데이터의 갭이나 데이터의 에러 또는 시크 후의 에러에 의해, 스트림에 중단되고가 생기면(자), Discontinuity 프로퍼티가 설정된다. 이 프로퍼티는, 수신된 샘플에 대해서 이 프로퍼티가 설정된 후, 처음으로 송신되는 샘플을 통해서 MPEG-1 스플리터로부터 스트림 핸들러에 송신된다. 이것에 의해, 타임 스탬프가 중단되고가 허용 된다.
End Of Stream | 이것은 샘플의 프로퍼티는 아니고, 독립한 통지이다. 이것을 수신했을 경우는, 모든 버퍼링 된 데이터가 디코더를 통과하는 것을 강제당한다. 이것에 의해, 논리적이게는, 모든 새로운 데이터가 Discontinuity 프로퍼티를 가져 시작 하게 된다.


MPEG-2 커넬 미디어 타입

MPEG-2 커넬 미디어 타입의 GUID 명은, Microsoft® DirectShow® 의 GUID 명과 다르다. 다음의 표는, MPEG-2 에 관련하는 타입의 DirectShow GUID 와 커넬 GUID 를 나타내고 있다.

Ksuuids.h 에서의 이름 | Ksmedia.h 에서의 이름
MEDIATYPE_MPEG2_PES | KSDATAFORMAT_TYPE_MPEG2_PES
MEDIASUBTYPE_MPEG2_VIDEO | KSDATAFORMAT_SUBTYPE_MPEG2_VIDEO
FORMAT_MPEG2Video | KSDATAFORMAT_SPECIFIER_MPEG2_VIDEO
MEDIASUBTYPE_DOLBY_AC3 | KSDATAFORMAT_SUBTYPE_AC3_AUDIO
MEDIATYPE_Video | KSDATAFORMAT_TYPE_VIDEO
MEDIATYPE_Audio | KSDATAFORMAT_TYPE_AUDIO
FORMAT_WaveFormatEx | KSDATAFORMAT_SPECIFIER_WAVEFORMATEX
FORMAT_MPEG2Video | KSDATAFORMAT_SPECIFIER_MPEG2_VIDEO
MEDIASUBTYPE_MPEG2_AUDIO | KSDATAFORMAT_SUBTYPE_MPEG2_AUDIO
MEDIASUBTYPE_DVD_LPCM_AUDIO | KSDATAFORMAT_SUBTYPE_LPCM_AUDIO


Windows Media 어플리케이션

Microsoft® DirectShow® 를 사용 하면, Microsoft® Windows Media™ 포맷 파일을 재생 및 생성 하는 어플리케이션을 생성 할 수 있다. Windows Media 포맷은, 네트워크상에서의 데이터의 스트리밍 및 클라이언트 컴퓨터상에서의 데이터의 렌더링용으로 최적화되고 있다. Windows Media 포맷의 상세한 것에 대하여는,Windows Media Format SDK 를 참조할것.

Windows Media Software Development Kit 에서는, Windows Media 포맷 파일을 생성 하는 대체 솔루션을 제공하고 있다. Windows Media SDK 와 DirectShow SDK 의 비교에 대해서는, 「Windows Media 와 DirectShow: Windows 베이스 미디어 어플리케이션의 선택사항」을 참조할것.

ASF (Advanced Streaming Format)는, Windows Media 포맷의 파일 컨테이너이다. DirectShow ASF 라이터 필터는, Windows Media 포맷 파일 및 WMF 이외의 스트림을 포함한 ASF 파일을 생성 할 수 있다. 「DirectShow 에서의 ASF 파일의 생성」을 참조할것.


DirectShow 에서의 ASF 파일의 생성

ASF 파일 포맷 및 Windows Media Format

여기에서는, Microsoft® DirectShow® 의 ASF 라이터 필터를 사용해, ASF (Advanced Streaming Format)로 파일을 생성 하는 방법을 해설한다. ASF 는, 임의의 종류의 압축 데이터 또는 비압축 데이터를 포함할 수가 있는 파일 포맷이다. AVI 나 WAV 등의 포맷에 대한 ASF 의 1 개의 이점은, ASF 파일의 데이터에는 타임 스탬프를 붙일 수 있는 것이다. Microsoft® Windows Media™ Format 파일은, Windows Media Format Software Development Kit (SDK)로 지정된 특정의 CODEC 를 사용하는 ASF 파일이다. 이러한 파일에서는, Windows Media Audio 파일의 경우에 "wma" 라고 하는 확장자(extension)가 사용되어 Windows Media Video 파일의 경우에 "wmv" 라고 하는 확장자(extension)가 사용된다. Windows Media Format 의 상세한 것에 대하여는,Windows Media Technologies 홈 페이지를 참조할것.

DirectShow SDK 및 Windows Media Format SDK

DirectShow 및 Windows Media Format SDK 에는, Windows Media Format 의 스트림을 생성 및 재생하는 어플리케이션을 쓰기 위한 보충 정보가 주어지고 있다. 상세한 것에 대하여는,http://www.microsoft.com/hwdev/vidcap/WM_DS.htm 에 있는 화이트 페이퍼를 읽는 것.

ASF Writer 필터는, 임의의 수의 입력 스트림을 받아들여 ASF 파일을 생성 한다. 이 필터는, Windows Media Format 사양에 따라 ASF 파일로서의 보존을 실시하기 (위해)때문에, Windows Media Format SDK 를 사용해 비압축 오디오 파일 또는 비디오 파일을 Windows Media Format 로 변환한다. 다른 CODEC 를 사용하거나 비압축 데이터를 ASF 포맷으로 보존하는 경우는, 필터의 압축 메카니즘을 우회도로 할 수가 있다.

디지털 비디오 (DV) 캡춰, 오디오재압축, 네트워크 트리밍의 AVI (Audio-Video Interleaved) 파일, MPEG 멀티미디어 파일의 변환 등, 다양한 상황으로 ASF Writer 를 사용할 수 있다. 이 필터에 의해, DirectShow® 로 Microsoft® Windows Media™ Audio (WMA) 파일 및 Windows Media Video (WMV) 파일을 생성하기 위한 유일한 수단이 제공된다. 이 필터는, Digital Rights Management (DRM)에 의해 보호되고 있는 Windows Media Format 파일을 생성 할 수도 있다.

ASF Writer 필터는, Windows Media Format SDK 와 함께 밖에 사용할 수 없다. 이 필터를 사용하는 어플리케이션을 개발하려면 , 개발 머신에 Windows Media Format SDK 를 인스톨 해 둘 필요가 있다. 이 SDK 를 다운로드 하면, Microsoft 로부터 전자 메일로 소프트웨어 증명서가 송신된다. 이 증명서에 의해, 어플리케이션은 SDK 의 락을 해제해, Digital Rights Management (DRM)를 가지지 않는 임의의 Windows Media Audio 파일 또는 Windows Media Video 파일의 읽고 쓰기를 할 수 있게 된다. 이 증명서가 없으면, 어플리케이션은 ASF Writer 를 필터에 추가할 수가 없다. DRM 가 유효하게 되어 있는 파일을 읽고 쓰기하려면 , Windows Media Technologies Web 사이트에서 설명하고 있도록(듯이), Microsoft 로부터 다른 증명서를 입수할 필요가 있다.

이 주제는, 이하의 섹션으로 구성된다.

  • ASF Writer 의 설정
  • 그래프의 구축
  • Windows Media Format SDK 의 락 해제

ASF Writer 의 설정

ASF Writer 필터의 생성시에는, 디폴트의 시스템 프로파일을 사용해 자동적으로 필터가 설정된다. 시스템 프로파일의 상세한 것에 대하여는, Windows Media Format SDK 로 설명되고 있다. 기본적으로, 시스템 프로파일에는, bit rate, 스트림의 수와 타입, 압축 품질 등, Windows Media Format 파일의 다양한 속성이 기술된다. 디폴트의 프로파일이 적당하지 않은 경우, 어플리케이션은 필터의 IConfigAsfWriter 인터페이스의 메소드를 사용해, 프로파일을 변경할 수 있다. 필터는, 기입하는 Windows Media Format 파일의 종류, 설정하는 입력 핀의 수, 입력 핀이 받아들이는 미디어 타입등의 프로파일을 사용해 판정한다. 필터는, 설정하기 전에 그래프에 추가해, 업 스트림 필터에 접속하기 전으로 설정해야 한다.

ASF Writer 에 프로파일을 지정하는 방법은, 많이 있다. ASF Writer 는, 시스템으로 사용 가능한 프로파일을 일람으로 가리키는 프로퍼티 페이지를 가지고 있다. 이 일람에는, 지정된 입력 스트림을 기본으로 필터로 생성 할 수 있는 스트림의 종류가 나타난다. 프로파일의 기술은, "250 Video—Creates video content for clients with 250 Kbps network connections, such as cable modems, DSL, and LAN connections" 나, "128 CD Quality Audio—creates CD transparency quality audio content for clients with high-speed Internet and LAN connections. Also suited for local playback" 등과 같이, 유저가 읽을 수 있는 캐릭터 라인으로 표시된다. 어플리케이션은, 이 프로퍼티 페이지를 최종 사용자에 공개해, 유저가 프로파일을 선택하도록 할 수 있다. 필터의 프로퍼티 페이지의 표시 방법에 대해서는, 「필터의 프로퍼티 페이지의 표시」를 참조할것. 프로퍼티 페이지를 사용하지 않는 경우는, Windows Media Format SDK 를 사용해 프로파일의 일람을 직접 입수해, 어플리케이션의 유저 인터페이스를 사용해 최종 사용자에 일람을 표시할 수가 있다. 커스텀 프로파일을 생성 해, 그것을 직접 필터에 건네줄 수도 있다. 또, Windows Media Format SDK 의 헤더 파일 Wmsysprf.h 로부터, 프로파일의 글로벌 일의 식별자 (GUID)를 필터에 건네줄 수도 있다.

이 필터에서는, 입력 핀의 접속중에 프로파일을 재설정할 수가 있지만, 1 개의 입력의 오디오 스트림의 프로파일로부터, 2 개의 입력의 오디오 및 비디오 프로파일로 바뀌는 등, 프로파일이 변경되었을 경우는, 전에 접속되고 있던 오디오 스트림만이 재접속된다.

디폴트에서는, ASF Writer 는 압축되어 있지 않은 오디오 및 비디오 스트림을 입력 핀으로 기다려, Windows Media Format SDK 를 사용해 압축을 처리한다. 임의의 데이터 포맷을 ASF 로 변환할 수 있으므로, Windows Media Format SDK 가 적절한 CODEC 를 가지고 있지 않은 데이터 포맷을 변환하고 싶은 경우도 있다. 다만, 그 결과 생성되는 파일은, 완전하게 유효한 ASF 파일이 되지만, WMA 또는 WMV 파일로서는 유효하지 않다. 이러한 경우는, ASF Writer 의 업 스트림에 있는 필터 그래프로 스트림을 압축해, ASF Writer 의 압축 메카니즘을 우회도로 할 필요가 있다. 그 때문에(위해)는, ASF Writer 에 접속되고 있는 업 스트림 출력 핀의 미디어 타입이, 현재의 ASF Writer 프로파일로 사용되고 있는 출력 스트림의 포맷과 완전하게 일치하고 있지 않으면 안 된다. ASF Writer 는, 입력 스트림이 설정 끝난 프로파일과 완전히 같은 것을 검출 하면, 그 이상의 압축을 시도하지 말고 데이터를 ASF 로 변환한다.

IGraphBuilder::Connect 메소드의 호출에 의해, 소스 필터와 ASF Writer 의 사이에 필터가 자동적으로 삽입되면(자), ASF Writer 는 반드시 내부에서 압축을 실시한다. 그 때문에, ASF Writer 의 압축 메카니즘을 우회도로 하려면 , 다음에 설명하도록(듯이) 그래프 전체를 수동으로 생성 해야 한다.

Windows Media Format SDK 를 사용하려면 , 오디오 스트림이 기능하고 있지 않으면 안 된다. 그 때문에, 입력 핀이 더미 스트림, 즉 소음된 저bit rate의 오디오 스트림용의 것이어도, ASF Writer 는 항상 오디오 입력 핀을 가지고 있지 않으면 안 된다. 또, 모든 입력 데이터에 타임 스탬프가 없으면 안되어, 필터를 실행 또는 포즈 하기 전에, 모든 입력 핀이 접속되어 있지 않으면 안 된다.

그래프의 구축

ASF Writer 를 사용해 필터 그래프를 구축하는 방법은 2 서로 통과한다. 1 번째의 방법에서는, 각 필터를 수동으로 그래프에 추가해, 핀을 접속한다. ASF Writer 를 추가한 후, 디폴트의 프로파일이 적당하지 않으면,IConfigAsfWriter 의 메소드를 사용해 프로파일을 설정해, ASF Writer 의 입력 핀을 업 스트림 필터의 대응하는 출력 핀에 접속한다.

2 번째의 방법에서는, ASF 로 변환하는 파일의 이름을 지정해 IGraphBuilder::RenderFile 메소드를 호출한다. RenderFile 는, 파일을 렌더링하기 위한 완전한 그래프를 자동적으로 구축한다. 그 후, 어플리케이션의 코드로, 수동으로 렌더링 필터를 삭제해 ASF Writer 를 삽입한다. 이것에는, 다음의 5 개의 기본스텝이 포함된다.

  1. 그래프에 ASF Writer 를 추가한다.
  2. 렌더링 필터의 접속을 해제해, 그것들이 접속되고 있던 출력 핀을 저장 한다.
  3. 그래프로부터 렌더링 필터를 삭제한다.
  4. ASF Writer 를 설정한다.
  5. IGraphBuilder::Connect 를 사용해, ASF Writer 의 입력 핀을 출력 핀에 접속한다.

다음의 그림은, ASF Writer 필터 그래프의 대표적인 설정을 나타낸다.

ASF Writer 필터 그래프

Windows Media Format SDK 의 락 해제

Windows Media Format SDK 에 액세스 하려면 , 어플리케이션은 실행시에 소프트웨어 증명서 (키라고도 불린다)를 제공해야 한다. 증명서의 입수방법에 대해서는, Windows Media Format SDK 를 참조할것. DirectShow 어플리케이션은, 필터 그래프에 추가될 때 ASF Writer 에 증명서를 제공한다. 어플리케이션은, Component Object Model (COM)의 IServiceProvider 및 IObjectWithSite 인터페이스를 사용해, 키프로바이다로서 등록해야 한다. 이 방법을 이용해, 어플리케이션은 IServiceProvider 로부터 파생된 키프로바이다크라스를 이행 한다. 이 클래스는, COM 의 3 개의 표준 메소드인 AddRef ,QueryInterface , 및 Release 와 함께, 필터 그래프 매니저로부터 불려 가는 추가 메소드 QueryService 를 이행 한다. QueryService 는, Windows Media Format SDK 의 WMCreateCertificate 메소드를 호출해, 생성 한 증명서에의 포인터를 필터 그래프 매니저에 돌려준다. 증명서가 유효한 경우, 필터 그래프 매니저는 그래프의 구축을 진행시키는 것을 허가한다.

주 : 어플리케이션을 구축하려면 ,WMCreateCertificate 의 prototype용으로 Wmsdkidl.h 를 인클루드 해, Microsoft 로부터 받은 Wmstub.lib 에 링크한다.

다음의 샘플 코드에, 이 처리의 기본적인 순서를 나타낸다.

// IServiceProvider 로부터 파생되는 키프로바이다크라스를 선언해 이행 한다.

class CKeyProvider : public IServiceProvider {
public:
    // IUnknown 인터페이스
    STDMETHODIMP QueryInterface(REFIID riid, void ** ppv);
    STDMETHODIMP_(ULONG) AddRef();
    STDMETHODIMP_(ULONG) Release();

    CKeyProvider();

    // IServiceProvider
    STDMETHODIMP QueryService(REFIID siid, REFIID riid, void **ppv);

private:
    ULONG m_cRef;
};

CKeyProvider::CKeyProvider() : m_cRef(0)
{
}

//////////////////////////////////////////////////////////////////////////
//
// IUnknown 의 메소드
//
//////////////////////////////////////////////////////////////////////////

ULONG CKeyProvider::AddRef()
{
    return ++m_cRef;
}

ULONG CKeyProvider::Release()
{
    ASSERT(m_cRef > 0);

    m_cRef--;

    if (m_cRef == 0) {
        delete this;

        // 오브젝트는 이제 존재하지 않기 때문에, m_cRef 는 돌려주지 않는다.
        return((ULONG) 0);
    }

    return(m_cRef);
}

// IUnknown 와 IServiceProvider 만을 지원 한다.
HRESULT CKeyProvider::QueryInterface(REFIID riid, void ** ppv)
{
    if (riid == IID_IServiceProvider || riid == IID_IUnknown) {
        *ppv = (void *) static_cast<IServiceProvider *>(this);
        AddRef();
        return NOERROR;
    }

    return E_NOINTERFACE;
}

STDMETHODIMP CKeyProvider::QueryService(REFIID siid, REFIID riid, void **ppv)
{
    if (siid == __uuidof(IWMReader) && riid == IID_IUnknown) {
        IUnknown *punkCert;

        HRESULT hr = WMCreateCertificate(&punkCert);

        if (SUCCEEDED(hr)) {
            *ppv = (void *) punkCert;
        }

        return hr;
    }
    return E_NOINTERFACE;
}

////////////////////////////////////////////////////////////////////
//
// 이러한 예에, 어플리케이션에서의 메소드 호출의
// 순서를 나타낸다. 간단하기 때문에, 에러 체크는 생략 했다.
//
///////////////////////////////////////////////////////////////////

// 필터 그래프 매니저를 생성 하지만, 필터는 추가하지 않는다.
IGraphBuilder *pGraph;
hr = CreateFilterGraph(&pGraph);

...

// 키프로바이다크라스를 인스턴스화해, COM 가 정적 오브젝트를
// 해방하지 않게 AddRef 의 처리를 한다.

CKeyProvider prov;
prov.AddRef();  // COM 에 정적 오브젝트를 해방시키지 않다.

// 콜백 및 QueryService 용으로, IObjectWithSite 포인터를 그래프에게 준다.
IObjectWithSite* pObjectWithSite = NULL;

hr = pGraph->QueryInterface(IID_IObjectWithSite, (void**) &pObjectWithSite);
if (SUCCEEDED(hr))
   {
// IObjectWithSite 포인터를 사용해, 키프로바이다오브제크트를 지정한다.
// 필터 그래프 매니저는, 이 포인터를 사용해 QueryService 를 호출해,
// 락 해제를 실시한다.
// 락 해제가 성공하면(자), 그래프를 구축할 수 있다.

pObjectWithSite->SetSite((IUnknown *) (IServiceProvider *) &prov);
    pObjectWithSite->Release();
   }

// 「그래프의 구축」으로 설명한 것처럼, 그래프를 구축한다.


Microsoft TV 테크놀러지

이 섹션에서는 아날로그 TV 어플리케이션과 디지털 TV 어플리케이션에 있어서의 Microsoft® DirectShow® 의 사용 방법을 설명한다. 아날로그 섹션은 ATI All-In-Wonder 와 같은 기존의 아날로그 튜닝 카드를 베이스로 한 어플리케이션의 쓰는 법을 설명한다. 디지털 섹션에서는 Microsoft® Broadcast Driver Architecture (BDA)를 지원 하는 신세대의 디지털 / 아날로그 튜너 카드를 베이스로 한 어플리케이션의 쓰는 법을 설명한다.

이 섹션에는 다음의 주제가 포함된다 :

  • 아날로그 TV 어플리케이션을 쓴다
  • 디지털 TV 어플리케이션을 쓴다
  • Microsoft 튜닝 모델
  • BDA 디지털 TV 레퍼런스


아날로그 TV 어플리케이션을 쓴다

이 주제는 이하의 섹션이 포함된다 :

  • 아날로그 TV 하드웨어 디바이스의 클래스
  • 아날로그 TV 필터 그래프
  • 그래프의 생성
  • VBI 데이터의 캡춰 링
  • 아날로그 TV 튜닝

아날로그 TV 필터 그래프는 아날로그 TV 튜너 캡춰 카드를 베이스로 하고 있다. 보통 1 매의 카드로 복수의 디바이스가 포함되는 : 튜너, 신호를 루팅 하는 제로 이상의 크로스바, 아날로그-디지털 컨버터 (아날로그 비디오 디코더라고도 불린다), 그리고 TV 오디오가 다른 디바이스의 경우도 있다. 카드의 각각의 디바이스의 Microsoft® Windows® Driver Model (WDM) 디바이스 드라이버는 제작자 혹은 다른 써드파티로부터 제공된다. 이러한 드라이버는 Microsoft 로부터 제공되는 필터나 플러그 인과 함께 일해, 필터 그래프에 참가할 수가 있다. Microsoft 가 제공하는 컴퍼넌트는 TV 튜너 필터, TV 오디오 필터, 아날로그 비디오 크로스바 필터, 그리고 WDM 비디오 캡춰 플러그 인이다. GraphEdit 로, 이러한 필터는 "WM Streaming" 카테고리에 나타나는, 필터의 프렌들리명은 드라이버에 의해 바뀐다. 어플리케이션은 System Device Enumerator 를 사용해 그러한 필터를 발견한다. 그러한 디바이스를 프로그램상에서 발견하는 방법의 자세한 것은,디바이스와 필터의 열거 를 참조할것. DirectShow 로 하드웨어 디바이스의 사용에 대한 일반적인 정보는,하드웨어 디바이스가 필터 그래프에 참가하는 방법」을 참조할것.

위의 디바이스 필터에 대해서는 더욱, 아날로그 TV 필터 그래프는 DirectShow 의 일부로서 Microsoft 가 제공하는 (KsProxy 베이스의) 커넬 모드 필터와 유저 모드 필터도 포함한다. 이러한 필터는 Tee/Sink-to-Sink 컨버터,VBI 서페이스아로케이타,CC 디코더,Line 21 디코더,오버레이 믹서,비디오 렌더링 등이다. 이러한 필터의 자세한 것은 후의 섹션으로 설명된다.

아날로그 TV 하드웨어 디바이스의 클래스

아날로그 TV 필터 그래프 생성의 문맥에는, 2 개의 기본적인 아날로그 캡춰 카드의 클래스가 있는 : (1) 비디오 데이터를 직접 비디오 메모리에 보내는 것, 이것은 비디오 포토를 호출해 직접 하드웨어와 접속한다, 그리고 (2) 비디오 데이터를 PCI 버스, 혹은 USB 나 IEEE 1394 접속을 통해 우선 호스트의 메모리에 보내, 그리고 그래픽 카드에 보내는 것.

어플리케이션으로부터 보면(자), 필터 그래프내에서 비디오 포토 디바이스와 PCI/USB/1394 디바이스라고 하는 2 개의 기본적인 차이가 있다 :

  1. 비디오 포토 디바이스를 베이스로 한 그래프는 다른 필터 VBI 서페이스아로케이타를 필요로 한다. 이 필터는 VBI 비트 맵용으로 비디오 그래픽스 어댑터에 다른 비디오 메모리 할당을 필요로 한다. 캡춰 필터로 VPVBI 출력 핀과 접속한다. PCI 디바이스에서는 오버레이 믹서가 이 메모리를 할당해 VBI 서페이스아로케이타는 불필요하다.
  2. 비디오 포토 디바이스를 베이스로 한 그래프는 Bt829 캡춰 필터를 사용해, PCI (와 1394/USB) 디바이스를 베이스로 한 그래프는 Bt848 캡춰 그래프를 사용한다. Bt848 필터는 VBI 서페이스아로케이타를 사용하지 않는다.

    아날로그 TV 필터 그래프

    다음의 그림은 ATI All-In-Wonder 카드를 베이스로 한 아날로그 TV 필터 그래프를 나타낸다. 이 그래프는 비디오, 오디오, 자막 방송 텍스트를 렌더링 해, 비디오와 오디오를 비압축 AVI 파일에 캡춰도 한다. (이 필터 그래프는 조금 복잡하지만,캡춰 그래프 빌더와 몇 줄기의 코드만으로 생성 할 수 있다. 그래프의 생성은 이 섹션의 끝에 설명한다. )

    ATI All-In-Wonder 필터 그래프

    TV 튜너 : 실제로는 어떤 데이터도 통하지 않지만, 이 필터는 반드시 그래프의 최초의 필터가 된다. 어플리케이션은 그 IAMTVTuner 인터페이스를 사용해, 채널로부터 주파수에의 매핑을 세트 해 채널 선택을 실시한다, 또 하드웨어가 지원 하는 비디오 규격의 정보를 취득한다.

    아날로그 비디오 크로스바 : 크로스바 필터는 루팅 디바이스이며, 그것을 사용해 어플리케이션은 하드웨어의 입력 신호를 올바른 데이터 패스로 설정한다. 이것 필터는 IAMCrossbar 인터페이스를 지원 한다. 이 필터의 입력 핀은 안테나, 케이블, 또는(VTR 와 같은) AUX 라인으로부터의 물리적인 입력을 나타낸다. 어느 입력 신호도 1 개 이상의 출력 핀에 루팅 될 수 있다. 전술의 ATI 그래프는 2 개의 크로스바 필터를 가지고 있다. 업 스트림 크로스바는 외부 입력용으로, 2 번째는 (AD 컨버터라고도 말한다) 하드웨어 비디오 디코더에의 복수 입력용인, 이것은 그래프내의 캡춰 필터에 의해 표현되고 있다. 다른 카드는 다른 크로스바 구성을 가지는 경우가 있다.

    비디오 캡춰 필터 : 이 커넬 모드 필터는 하드웨어 위에의 AD 컨버터를 표현한다. 그것은 비디오 신호를 실제로 처리하는 최초의 필터이다. Microsoft 는 비디오 포토 디바이스에 사용되는 Brooktee 829 캡춰 팁을 지원 하는 드라이버를 제공해, IHV 는 Brooktree 848, 878 혹은 다른 비디어 칩용의 드라이버를 제공한다. 모든 이러한 드라이버는 WDM 비디오 캡춰 플러그 인을 사용해, 프로퍼티 페이지를 제공해, 그 COM 인터페이스를 공개한다. 그 드라이버와 플러그 인은 어플리케이션에는 1 개의 「필터」로서 나타난다. 어플리케이션은 이 필터의 IAMAnalogVideoDecoder 인터페이스를 사용해, 지원 되고 있는 아날로그 비디오 포맷, 수평 동기 상태, 출력 버스를 취득 혹은 설정한다. 캡춰 필터는 출력으로서 2 개의 다른 비디오 스트림을 생성 할 수가 있는, 다른 한쪽은 렌더링용, 이제(벌써) 다른 한쪽은 캡춰용이다. (VP 혹은 비디오 포토라고 하는 이름의) 렌더링 핀은 반드시 오버레이 믹서의 입력 핀 제로에 접속한다. 「오버레이 믹서 필터」에는 비디오 포토 접속에 대한 상세 정보가 기술되고 있다.

    캡춰 필터는 VBI 데이터를 다른 핀에 출력하는, 어느 카드는 로 VBI 데이터를 출력해, 어느 카드는 하드웨어내에서 VBI 디코드를 실시한다. 모든 Microsoft VBI 필터는 현재 로 데이터와 디코드 데이터의 양쪽 모두를 지원 한다. All-In-Wonder 카드는 비디오 포토를 가지므로, Bt829 필터가 사용되는, 그것은 VBI 서페이스아로케이타에의 출력 핀을 가져, Line 21 디코더가 제공하는 CC 오버레이용으로 비디오 메모리를 올바르게 구성한다. 이 필터는 오버레이 믹서상에서 입력 핀 1 이상의 것과 접속한다.

    AVI 데콘프렛사 : AVI 데콘프렛사피르타는 비디오 압축 매니저 CODEC 의 래퍼 필터이다. 아날로그 TV 캡춰 그래프에서는, 그것은 AVI 멀티플렉서에 보내기 전에 비디오 스트림을 UYVY 로부터 RGB 로 변환하는 MSYUV 칼라 컨버터를 랩 한다.

    오디오 캡춰 : 오디오 캡춰 필터는 크로스바의 오디오 디코더 출력 핀으로부터 디지털화된 오디오를 받는다. 이 핀은 실제로는 사운드 카드의 내부 입력을 표현하는, 그것은 CD 드라이브 만이 아니고 호스트 시스템의 내부 소스의 경우도 있다. 오디오 캡춰 필터의 다른 입력 핀은 보통 마이크로 폰, 테이프 플레이어등이 같은 외부 디바이스로부터의 아날로그 입력을 나타낸다. 정확한 핀의 구성과 이름은 사운드 카드에 따라서 다르다. 전술한 그래프에서는, 오디오 캡춰 필터는 오디오 데이터를 AVI Mux 필터에 출력한다.

    이 그래프에는 오디오 렌더링 필터가 포함되지 않은 것에 주의 해야 한다, 이 필터는 TV 카드가 외부 케이블로 사운드 카드로 (혹은 동글로 사운드 카드의 입력 잭에) 접속되고 있을 때는 필요가 없다. 이 케이블이 사용되지 않으면, 전술과 같이 그래프는스마트티 필터 를 사용해, 오디오 캡춰 필터 다운 스트림으로부터 AVI Mux 에의 출력과 같이디폴트 DirectSound 디바이스에 오디오를 출력한다.

    Tee/Sink-to-Sink 컨버터 : 이 필터는 캡춰 필터로부터 VBI 정보를 취득해, 신호의 각 데이터 서비스에 대응해 다른 스트림에 분할한다. Microsoft 는 VBI CODEC 를 자막 방송, NABTS, World Standard Teletext (WST)에 대해서 제공한다. 상술의 그래프에서는 캡춰에 대한 서비스는 자막 방송 뿐이다.

    CC 디코더 : CC VBI 디코더는 커넬 모드 스트림 클래스 필터이다. 8 개(살)까지의 출력 핀을 가져, 각 핀은 그것 자신의 라인과 서브 스트림을 선택 가능하다. 그 일은 캡춰 된 VBI 라인을 처리해, CC 데이터를 Line 21 디코더나 다른 어플리케이션에 출력하는 것이다. 최초의 출력 핀은 Line 21 디코더에 접속된다.

    Line 21 디코더 : Line 21 디코더는 CC 디코더로부터로 코드 된 자막 방송 데이터를 취득해, 비디오 직사각형에 오버레이 되는 비트 맵을 생성한다. 다음에 이 데이터는 오버레이 믹서에게 건네진다.

    NABTS/FEC VBI CODEC 필터 (그림에는 없다): NABTS/FEC VBI CODEC 는 ring-0 스트림 클래스 필터이다. 그것은 VBI 와 HWNABTS 라고 하는 2 개의 입력 핀을 가진다. 8 개(살)까지의 출력 핀을 가져, 각 핀은 자신의 VBI 스캔 라인과 서브 스트림을 선택할 수가 있다. 그 일은 캡춰 된 VBI 라인을 처리해, 디코드된 혹은 포워드 에러가 붙은 NABTS 데이터를 BDA SLIP 데후레이마 필터에 출력해, 다음에 WinSock 경유로 어플리케이션으로부터 이용 가능한 IP 데이터를 생성 하는 BDA IP 세면대에 보내는 것이다.

    WST CODEC 와 WST 디코더 필터 (그림에는 없다): 이러한 필터는 ring-0 스트림 클래스 필터이며, PAL 시스템의 teletext 데이터를 처리한다. WST CODEC 는 로 VBI 데이터를 받는 1 개의 입력 핀을 가진다. 그것은 8 개까지의 출력 핀을 가져, 각 핀은 자신의 라인과 서브 스트림을 선택할 수 있다. 그 일은 캡춰 된 VBI 라인을 처리해, 디코드된 teletext 데이터를 어플리케이션에 출력하는 일이다. 최초의 출력 핀은 WST 디코더에 접속되어 자막 방송 데이터로 Line 21 디코더가 실시하는 것과 같이 하드웨어 오버레이의 비트 맵을 생성 한다.

    오버레이 믹서 : 이 DirectShow 필터는 시스템의 비디오 메모리로 실제의 비디오의 렌더링을 실시한다. 그것은 비디오 포토 타입과 비비디오 포토 타입 양쪽 모두의 하드웨어로 사용된다.

    비디오 렌더러 : 오버레이 믹서를 사용해 비디오를 렌더링 하는 모든 그래프에서는, 비디오 렌더러는 단순한 윈도우 매니저로서 일해, 오버레이 믹서에 비디오 직사각형을 스크린의 어디에 두는지를 지시한다.

    그래프의 생성

    아날로그 TV 그래프는 단지 1 개의 타입의 WDM 비디오 캡춰 그래프이다. 캡춰 그래프 빌더를 사용해 생성 할 수 있는, 이것은 「캡춰 어플리케이션의 쓰는 법」으로 설명되어AMCap 샘플 어플리케이션으로 데먼스트레이션 되고 있다. AMCap 로 데모 되고 있도록(듯이), 기본 원리는 캡춰 필터로 시작해 다음에 렌더링 혹은 캡춰 하려고 하는 각 입력 핀에 대해서 다운 스트림 필터를 추가한다. 업 스트림 필터는 마지막에 붙은 한다. AMCap 는 자막 방송 데이터를 렌더링 하는 CC 디코더와 Line 21 디코더 필터로 끌여들이는 방법을 나타내지만, NABTS 나 teltetex 데이터의 캡춰 링을 위해서(때문에) 다른 VBI 관련 필터로 끌여들이는 방법은 데모되어 있지 않다.

    VBI 데이터의 캡춰 링

    DirectShow 는 아날로그 TV 방송 신호의 수직 동기 간격 (VBI)으로부터 NABTS 와 (PAL용의) World Standard Teletext (WST)를 캡춰 링 하는 커넬 모드 필터를 제공한다. 이러한 필터는 GraphEdit 내에서 WDM 스트리밍 VBI CODEC 카테고리아래에 표시된다. 캡춰 필터는 로 VBI 데이터를 Tee/Sink-to-Sink 컨버터에 보내는 1 개의 출력 핀을 가져, 그것은 NABTS IP 데이터, Line 21 자막 방송, tetetext 정보의 신호내에 있는 데이터를 조사해 각 데이터 타입의 출력 핀을 생성 한다. 자막 방송이나 teletext 데이터를 디코드하기 위한 필터를 추가하려면 , MSTee 필터의 적절한 출력 핀으로 ICaptureGraphBuilder2::RenderStream 메소드를 사용하는 것. 전술의 그림에서는 CC 데이터의 캡춰 링과 렌더링용의 필터를 나타내고 있어 AMCap 샘플은 자막 방송 데이터를 그래프에 추가하는 방법을 데모 하고 있다. (Web 페이지나 Web 이미지를 포함한 인터랙티브 TV 확장과 같은) NABTS IP 데이터에 대해서는, 비디오 캡춰 필터로부터 필터 다운 스트림의 체인을 수동으로 추가, 접속해야 한다. VBI 데이터를 2 개의 스트림에 분할하려면 Tee/Sink-to-Sink 컨버터 필터의 추가에 주의 해야 한다.

    NABTS (와)과 자막 방송 필터 그래프 세그먼트(segment)

    이러한 커넬 모드 필터상에는 어플리케이션으로부터 호출해 가능한 인터페이스는 없다. 그것들은 SLIP encode 된 IP 패킷을 VBI 신호로부터 추출해, 그것을 Winsock 에 건네주는 데이터 파이프라인으로서의 보고 기능한다.

    teletext 데이터에 대해서는, 필터는 다음의 그림으로 나타나고 있다.

    세계 표준 Teletext 필터 그래프 세그먼트(segment)

    NABTS, teletext, CC 디코딩을 하드웨어로 처리하는 캡춰 디바이스도 있다. 이 경우, 캡춰 필터는 특수한 출력 핀을 공개해, 다운 스트림 디코더는 그 데이터를 수정하지 않고 건네주는 것만으로 있다. 어플리케이션 개발자에게는 특수한 프로그래밍은 필요없다.

    VBI 의 Line 21 에는 자막 방송 텍스트 만이 아니고, 현재의 방송과 제휴한 Web 페이지의 URL 도 포함되어 있다. 이것은 ATVEF 규격의 "Transport B" 로서 기술되고 있다.

    아날로그 TV 튜닝

    TV 튜너를 컨트롤 하면나무의 기본적인 처리순서는 이하대로이다 :

    1. 필요하면, 아날로그 비디오 크로스바 필터로 IAMCrossbar 인터페이스를 사용해, 튜너로부터 비디오 디지타이저 (캡춰 필터)에의 크로스바 경유의 비디오 패스를 구축한다.
    2. IAMTuner::put_Mode 메소드를 호출해, 수신 방송 타입 (TV, AM 오디오, FM 오디오등)의 튜너 카드를 세트
    3. IAMTuner::put_CountryCode 로 나라 코드를 세트 해, 올바른 TV 채널-주파수 매핑을 구축한다. 나라 코드의 상세한 것에 대하여는, 「국제 아날로그 TV의 튜닝」을 참조할것.
    4. 튜너의 각 입력에 대해서,IAMTVTuner::put_InputType 를 호출해, 케이블이나 안테나의 입력 타입을 설정한다. IAMTVTuner::put_ConnectInput 를 사용해, 이용 가능한 튜너 입력의 1 개를 선택한다.
    5. IAMTVTuner::get_TVFormat 를 호출해, 현재의 비디오 포맷을 취득해, 다음에 이 값을 사용해 IAMAnalogVideoDecoder::put_TVFormat 를 호출해 캡춰 필터를 설정한다.
    6. IAMTuner::put_Channel 를 호출해, 시청을 시작 한다.


디지털 TV 어플리케이션을 쓴다

Microsoft® DirectX® 8.0 SDK 와 Microsoft® Broadcast Driver Architecture (BDA)와 호환의 디지털 TV 튜너 카드가 있으면, 디지털 TV 방송을 퍼스널 컴퓨터로 시청 하는 어플리케이션을 생성 할 수가 있다. PC 상에서 디지털 TV 를 지원하기 위한 Microsoft 의 아키텍쳐는 다음의 컴퍼넌트로 나눌 수 있다 :

  • Broadcast Driver Architecture
    • 튜닝과 복조
    • 데마르치프레크스
    • 디지털 TV 규격 지원 (DVB, ATSC)
    • 조건부 액세스 (Microsoft® Windows® operating system의 장래의 버젼으로 릴리스 된다)
    • 전자 프로그램 가이드 (Microsoft Windows operating system의 장래의 버젼으로 릴리스 된다)
    • MSTV 가이드 스토어 (Microsoft Windows operating system의 장래의 버젼으로 릴리스 된다)
    • ATVEF (Microsoft Windows operating system의 장래의 버젼으로 릴리스 된다)
  • 튜닝 모델
    • 튜닝 모델은 여러가지 네트워크 타입에 대한 튜닝의 복잡함을 캡슐화하는 일련의 오브젝트이다. 튜닝 모델을 사용하면(자), 어플리케이션은 단순한 단일의 방법으로 이용 가능한 주파수나 채널을 츄 할 수가 있다.
  • 비디오 컨트롤 아키텍쳐
    • 비디오 컨트롤은 TV 나 DVD 어플리케이션에 대한 스크립팅 API 를 제공하는 ActiveX® 컨트롤이다. 그것은 TV 나 DVD feature의 어플리케이션에의 통합을 현저하게 단순화 한다. (Microsoft Windows operating system의 장래의 버젼으로 릴리스 된다)

DirectX 8.0 에는 기본적인 디지털 TV 필터 그래프의 생성, ATSC (안테나 혹은 케이블)나 DVB-S 방송에의 접속, 그래프의 츄와 서브 스트림의 선택, (전자 프로그램 가이드와 같은) 로 PSI 데이터의 캡춰와 스크린에의 비디오의 렌더링을 하기 위해서 필요한 모든 필터와 컴퍼넌트가 포함되어 있다.

DirectX 8.0 에는 PSI 스트림으로부터 EPG 데이터를 추출하는 MSTV 가이드 스토어나, 인터랙티브 TV 용의 Web 페이지나 Web 이미지와 같은 ATVEF 확장을 렌더링 하는 컴퍼넌트는 포함되지 않았다. DirectX 8.0 은 또 비디오 컨트롤도 제공하지 않는, 즉 어플리케이션이 필터 그래프를 생성 하려면 자기 자신으로 코드를 이행 해야 한다.

이 주제에는 다음의 섹션이 포함된다 :

  • 디지털 TV 필터 그래프
  • 필터 그래프의 생성

디지털 TV 필터 그래프

다음의 그림은 지상파 ATSC 방송을 받기 위해서(때문에) 구성된 기본적인 디지털 TV 필터 그래프를 나타낸다. 튜너, 캡춰, MPRG-2 디코더 필터의 실제의 필터명이나 핀명은 비디오에 의존해 바뀐다.

일반적인 BDA 디지털 TV 필터 그래프

네트워크 프로바이더: BDA 네트워크 프로바이더 필터는 반드시 그래프내의 최초의 필터가 된다. 이 그래프는 ATSC 네트워크 프로바이더를 가지고 있다. Microsoft 는 또 DVB 네트워크 튜닝을 제공하는 DVB 네트워크 프로바이더도 제공한다. 서드-파티는 자기 자신의 네트워크 프로바이더를 가져, 자기 자신의 방송을 커스터마이즈 한다. 네트워크 프로바이더는, 컨텐츠 다중, 변조, 방송 규격을 포함한, 개개의 튜닝 공간에서 다운 스트림 필터를 구성한다. 이 필터는 ITuner 인터페이스를 이행 해, 어플리케이션은 그것을 사용해 지정한 채널이나 주파수에 디바이스를 튜닝 한다.

디지털 TV 튜너: 이 커넬 모드로 KsProxy 베이스의 필터는 하드웨어 디바이스 위에의 튜너를 표현한다. 어플리케이션으로부터 호출해 가능한 인터페이스가 있는 경우와 없는 경우가 있는, 그것은 써드파티의 드라이버의 이행에 의존하고 있다. BDASample 어플리케이션에서는, 튜너 필터는 ITuner 를 지원 하도록(듯이)는 가정되어 있지 않은, 그러므로 튜닝은 튜너 필터와 내부적으로 커뮤니케이션 하는 네트워크 프로바이더를 통해 행해진다.

디지털 TV 캡춰 필터: 이 커넬 모드로 KsProxy 베이스의 필터는 하드웨어 디바이스상에서의 복조/디지털화를 나타낸다. 그 1 개의 출력 핀은 MPEG-2 트랜스폴트 스트림을 MPEG-2 디멀티플렉서에 출력한다.

MPEG-2 디멀티플렉서 : 디지털 TV 그래프에서는, MPEG-2 디멀티플렉서는 MPEG-2 트랜스폴트 스트림을 캡춰 필터로부터 받아, 스트림을 데마르치프레크스 한다. 보통 4 개의 출력 핀을 가진다. 최초의 출력 핀은 로프 로그 램 서비스 정보 (PSI) 패킷을 트랜스폴트 정보 필터에 출력한다. 2 번째의 핀은 비디오 스트림을 MPEG-2 디코더에 출력한다. 3 번째의 핀은 오디오를 오디오 디코더에 출력해, 4 번면의 핀은 인터랙티브 TV 확장과 같은 데이터를 출력한다.

트랜스폴트 정보 필터 : 수신자가 지정한 프로그램에 관한 모든 기본 스트림을 올바르게 받기 위해서(때문에), 또 수신자가 어느 프로그램이 스트림에 포함되어 있는지를 이야기할 수 있기 위해서(때문에), 트랜스폴트 스트림은 트랜스폴트 스트림내에 포함되는 카탈로그 정보로서 일하는 많은 테이블세트를 가진다. 네트워크 프로바이더의 방향으로,MPEG-2 디멀티플렉서는 트랜스폴트 정보 필터에 출력하는 테이블을 출력하는, 그러한 테이블을 퍼스 해, 네트워크 프로바이더에의 정보를 제공해, 그래프내의 다른 수신 필터와 노드를 컨트롤 할 수 있게 된다.

HDTV 성능 MPEG-2 디코더: 디지털 TV 필터 그래프는 고해상도 TV 비디오 스트림의 성능을 가지는 써드파티의 디코더가 필요하다. 오디오와 비디오 양쪽 모두의 스트림을 같은 필터로 조작하는 디코더 이행도 있고, 오디오와 비디오별의 필터를 가지는 디코더도 있다.

오버레이 믹서 : 이 Microsoft® DirectShow® 필터는 실제로는 비디오의 렌더링을 시스템의 비디오 메모리에 실시한다.

비디오 렌더러 : 비디오의 렌더링에 오버레이 믹서를 사용하는 모든 그래프에서는, 비디오 렌더러는 단순한 윈도우 매니저로서 일해, 오버레이 믹서에 비디오 직사각형을 스크린의 어디에 둘까를 전한다.

BDA MPE 필터 : 이 필터는 멀티 프로토콜 캡슐화 (MPE) 스트림으로부터 IP 패킷을 추출해, IP Sink 에 그것을 출력한다.

BDA IP 세면대 : 이 필터는 IP 패킷을 받아, Winsock 경유로 호스트 시스템에 그것을 출력하는, 어플리케이션은 그것을 받아, 인터랙티브 TV 확장과 같은 IP 데이터 스트림을 수신한다.

필터 그래프의 생성

DirectX 8.0 에서는, 어플리케이션은 디지털 TV 그래프를 수동으로 생성 해, 각 필터의 추가나 접속을 해야 한다. 캡춰 그래프 빌더는 사용할 수 없다. 샘플 어플리케이션 BDASample 가 SDK 에 포함되어 있다. 이것은 이 섹션의 후반에 개설하는 스텝에 따라, 기본적인 디지털 TV 필터 그래프의 생성 방법을 데먼스트레이션 한다.

다음의 섹션은 대개 런타임시에 행해지는 전형적인 순서의 순서에 줄지어 있다. 츄리크에스트가 ITuner::put_TuneRequest 메소드로 네트워크 프로바이더에 보내진다음에 필터 그래프의 생성을 실시하는 것에 주의 해야 한다. 왜냐하면 츄리크에스트에는 네트워크 타입과 어느 필터를 그래프에 읽어들일까를 결정하는 다른 상세 정보가 포함되어 있기 때문이다. 그래프는 네트워크 프로바이더가 이 정보를 가질 때까지 생성 되지 않는다. 튜닝 공간, 츄리크에스트, 관련 오브젝트의 상세한 것에 대하여는, 「Microsoft® 튜닝 모델」을 참조할것.

튜닝 공간의 취득

DirectX 8 에서는, Broadcast Driver Architecture 가 로컬 아날로그 케이블과 안테나, 로컬 ATSC 안테나와 케이블, DVB-S 에 대한 디폴트의 튜닝 공간을 제공한다. 어플리케이션에 디지털 케이블 지원을 이행 하려면 , 디지털 케이블 튜닝 공간을 필요한 값으로 over-write 해, 필요하면 디폴트 locator도 제공하는 것. 국제 튜닝이나 디지털 위성방송을 지원 하려면 , 자신의 튜닝 공간을 생성 할 필요가 있다. DVB 튜닝 공간에서는, 어플리케이션은 유저 interface를 제공해야 하는, 유저는 그것을 사용해 어느 디지털 TV 서비스를 구독하는지를 지정할 수가 있다.

튜닝 공간을 취득하려면 , 어플리케이션은 SystemTuningSpaces 오브젝트의 인스턴스를 생성 해,ITuningSpaceContainer::get_EnumTuningSpaces 메소드를 사용해 튜닝 공간의 리스트를 취득하는, 그 리스트로부터 튜닝 공간을 1 개 선택한다. 이 순서는 BDASample 어플리케이션의 LoadTuningSpace 메소드로 데먼스트레이션 되고 있다.

Microsoft 튜닝 모델은 아날로그 튜닝 공간을 지원 하기 위해서 설계되었지만, DirectX 8.0 에는 BDA 필터 그래프내에서의 아날로그 TV 튜닝의 완전한 지원은 포함되지 않았다. 이 지원은 DirectX 와 Microsoft® Windows® 의 장래의 릴리스로 추가된다. 한편 아날로그 TV 그래프는 DirectShow 가 아날로그 TV 캡춰로 지금까지 사용해 온 것과 같은 타입의 필터 그래프로 지원 된다. DirectX 8.0 에서는, 디지털 네트워크 타입만이 BDA 필터 그래프로 지원 된다. 이것은 다음과 같은 일을 의미하고 있다, 예를 들어, 디지털과 아날로그 양쪽 모두의 튜닝을 지원 하는 어플리케이션을 쓰려고 하면, 그 어플리케이션은 2 개의 다른 필터 그래프를 생성 할 필요가 있어, 유저가 아날로그 TV 채널을 선택했을 때는 아날로그 그래프를 사용해, 유저가 디지털 채널이나 주파수를 선택했을 때는 BDA 그래프를 사용한다. Microsoft Windows 의 장래의 릴리스에서는, 그래프 생성 프로세스를 완전하게 취급하는 Automation 호환의 비디오 컨트롤과 함께, 아날로그 TV 와 디지털 TV 와 라디오 튜닝 공간이 모두 제공된다.

츄리크에스트와 네트워크 프로바이더에의 서브 미트

어플리케이션은 츄리크에스트를 직접은 생성 하지 않는다. 그 대신해, 어플리케이션은ITuningSpace::CreateTuneRequest 메소드를 호출해, 그것은 하늘의 초기화되어 있지 않은 츄리크에스트를 돌려준다. 다음에 어플리케이션은 특정의 인터페이스에 대응한 오브젝트의 표준 COM 메소드 QueryInterface 를 호출하는, 그 인터페이스는 IATSCChannelTuneRequest 와 같은 ITuneRequest 로부터 파생한 인터페이스이다. 다음에 어플리케이션은 돌려주어진 인터페이스를 사용해 츄리크에스트를 구성해, 그것을 처리해, 네트워크 프로바이더에 서브 미트 할 수가 있다. 일반 「네트워크 프로바이더」와 같은 것은 실제로 존재하지 않는 것을 이해하는 것은 중요하다, 그렇지 않고 「ATSC 네트워크 프로바이더」나 「DVB 네트워크 프로바이더」가 존재하는 것이다. 생성 된 개별의 오브젝트는 튜닝 공간 오브젝트로부터 취득한 네트워크 CLSID 를 베이스로 하고 있다.

네트워크 프로바이더가 그래프에 추가된 다음에,QueryInterface 메소드를 사용해 그 ITuner 인터페이스를 취득한다. 다음에 ITuner::put_TuneRequest 메소드를 사용해 츄리크에스트를 네트워크 프로바이더에 건네준다. 이 순서는 BDASample 의 graph.cpp 의 LoadNetworkProvider 함수로 데먼스트레이션 되고 있다.

나머지의 필터의 추가와 접속

네트워크 프로바이더가 츄리크에스트로 구성되면(자), 1 개(살) 1 개(살) 각 필터를 추가 접속하는 것으로, 나머지의 필터를 그래프에 추가할 수 있다. BDASample 어플리케이션의 graph.cpp 의 BuildGraph 와 LoadAVSegment 와 LoadIPSegment 함수를 보는 것.

디폴트 우선 컴포넌트 타입의 정의

주 이 순서는 BDASample 에 이행되어 있지 않다.

「컴퍼넌트」는 프로그램 서브 스트림을 참조한다. 디폴트 우선 컴포넌트 타입은, 유저가 디폴트로 액티브하게 하고 싶어하는 것 같은 타입의 서브 스트림이다. 예를 들어, 스페인어 오디오 스트림이 이용 가능한 때는 언제나 플레이 되어야 한다, 어떤 유저는 지정할지도 모르다. 어플리케이션은 하늘의 Components 콜렉션 오브젝트를 인스턴스화해, 게다가 기입하는 것에 의해 우선 컴퍼넌트 세트를 생성 한다. 다음에 어플리케이션은 그 컴퍼넌트 오브젝트를 처리해 튜너에 서브 미트 하는, 하면 튜너는 이용 가능한 서브 스트림으로 변경이 있으면(자) 반드시 그것을 체크한다.

서브 스트림의 선택

주 이 순서는 BDASample 에 이행되어 있지 않다.

> 어느 서브 스트림을 액티브하게 하든가 혹은 비액티브하게 하는을 지정하려면 , 어플리케이션은 최초로 츄리크에스트를 튜너에 서브 미트 해야 한다. 튜너가 지정한 채널이나 주파수를 츄 하면, 튜너는 츄리크에스트내의 컴퍼넌트 콜렉션에 각 서브 스트림이 액티브 혹은 비액티브한가의 정보를 기입한다. 다음에 어플리케이션은 이 콜렉션내의 각 컴퍼넌트를 조사해,IComponent::put_Status 메소드를 사용해 개개의 서브 스트림을 액티브 혹은 비액티브하게 할 수가 있다.

디지털 튜닝

최초의 츄리크에스트가 서브 미트 된 다음에, 다음의 튜닝은 새로운 츄리크에스트를 네트워크 프로바이더에 서브 미트 하는 것에 의해 행해지는, 이것은 BDASample 의 graph.cpp 의 ChannelChange 메소드로 데먼스트레이션 되고 있다.


Microsoft 튜닝 모델

개요

디지털 리시버의 튜닝 프로세스는 네트워크 타입에 따라서 다른 파라미터 세트가 필요하다. 튜닝 모델의 목적은, 이러한 차이를 오브젝트와 그 오브젝트를 조작하는 프로시저의 표준 세트로 캡슐화해, 어플리케이션을 세세한 저레벨의 튜닝 매니지먼트로부터 해방하는 것이다. 어플리케이션이 DVB-S 프로바이더로부터의 프로그램을 튜닝 하든지, 로컬 아날로그 방송으로부터 오는 프로그램을 튜닝 하든지, 기본적인 순서는 같다. 이 순서는 또 그 아래에 있는 하드웨어에도 의존하지 않는다. 튜닝 모델의 모든 오브젝트는 표준 COM 인터페이스 IPersistPropertyBag 를 지원 해, 스토리지 메카니즘의 소트가 가능하다.

Microsoft® DirectX® 8.0 베이스의 어플리케이션은 Microsoft 튜닝 모델의 메리트를 충분히는 받을 수가 없는 것에의 주의는 중요하다, 왜냐하면 DirectX 8.0 은 표준화 된 가이드 스토어와 튜닝 공간을 이해하는 가이드 스토어 로더를 제공하지 않기 때문이다. DirectX 와 Microsoft® Windows® 의 장래의 릴리스에서는 이러한 컴퍼넌트가 포함될 예정이다. 가이드 스토어 로더는 트랜스폴트 정보 필터 위에의 프로그램 서비스 정보 (PSI) 스트림을 모니터 해, 튜닝 공간의 이용 가능한 모든 채널이나 주파수에 대해서 츄리크에스트를 자동적으로 생성 해, 가이드 스토어 데이타베이스에 보존한다. 이러한 컴퍼넌트로, 모든 어플리케이션이 실시하지 않으면 안 되는 것은, 이용 가능한 채널을 보이는 유저 interface를 생성 해, 유저가 선택했을 때, 네트워크 프로바이더에 준비전의 츄리크에스트를 서브 미트 하는 것이다. 그러나 DirectX 8.0 에서는, 어플리케이션은 츄리크에스트의 생성이 필요하다 (거기에는 츄리크에스트의 의미를 모르면 안 된다). 다른 방법은, 자기 자신의 가이드 스토어 로더와 가이드 스토어를 쓰는 것이다.

튜닝 모델 오브젝트

튜닝 오브젝트의 2 개의 기본 오브젝트는 튜닝 공간 과 츄리크에스트 이다. 튜닝 공간은 프로바이더와 송신 소스를 기술한다, 예를 들어, 로컬 케이블 서비스나 디지털 위성 네트워크 등. 어플리케이션은 튜닝 공간 컨테이너를 사용해 로컬 시스템상에서 이용 가능한 튜닝 공간을 열거해, 다음에 튜닝 공간을 사용해 츄리크에스트를 생성 한다. 어플리케이션은 네트워크 프로바이더에 츄리크에스트를 서브 미트 하는, 그것은 그래프내의 소스 필터이다. 네트워크 프로바이더는 필요한 정보를 츄리크에스트로부터 추출해, 그 정보를 커넬 모드 드라이버에 보낸다. 다음의 그림은 어플리케이션과 튜닝 모델 오브젝트와 BDA 필터 그래프와 커넬 모드 드라이버간의 상위 레벨의 관계를 나타내고 있다.

브로드캐스트 아키텍쳐의 개념

튜닝 공간과 츄리크에스트

튜닝 공간은 개별의 네트워크 프로바이더를 기술한다. 튜닝 공간의 예에는, EchoStar®, DirecTV®, 안테나 경유의 로컬 아날로그 방송, 로컬 아날로그 케이블, 안테나 경유의 로컬 디지털 방송이 포함된다. 튜닝 공간 정보에는 네트워크 타입의 정보가 포함된다, 예를 들어 지상파 아날로그 방송, ATSC, DVB-T, DVB-C, DVB-S. 튜닝 공간은 츄리크에스트의 문맥을 정의하는, 각 츄리크에스트는 개별의 튜닝 공간 이외에 취해 의미가 없다. 예를 들어 ATSC 튜닝 공간 오브젝트는 ATSC 츄리크에스트를 생성 해, CVB 튜닝 공간 오브젝트는 DVB-S 츄리크에스트를 생성 하는, 등등. 튜닝 공간 오브젝트와 츄리크에스트오브제크트는 Automation® 호환으로, 스크립트 혹은 Microsoft® Visual Basic®, C/C++ 로부터 구성 가능하다.

튜닝 공간을 츄리크에스트와 네트워크 프로바이더에 대응시킨다

다른 네트워크 타입은 다른 타입의 데이터를 다른 포맷으로 옮기므로, 어느 튜닝 공간은 필터 그래프내에서 고별의 네트워크 프로바이더를 필요로 한다. 예를 들어, ATSC 디지털 포맷 방송의 채널에 대한 츄리크에스트를 생성 하려면 , 어플리케이션은 IATSCTuningSpace 를 지원 하는 ATSC 튜닝 공간에서 시작해 ATSC 의 네트워크 타입을 가져,IATSCLocator 인터페이스로 구성된 (이 세션의 후반에 설명한다) 디폴트 locator와 결합된다. 어플리케이션이 ITuningSpace::CreateTuneRequest 를 호출하면,ITuneRequest 인터페이스 포인터를 반환값으로서 받는다. 어플리케이션은 그 인터페이스를 사용해 IATSCTuneRequest 인터페이스를 쿼리 해, 다음에 그 인터페이스를 사용해 츄리크에스트를 구성한다. 츄리크에스트가 서브 미트 될 때, 그것은 Microsoft ATSC 네트워크 프로바이더 (혹은 ATSC 튜닝 공간과 같게 ITuner 를 지원 하는 써드파티 BDA 호환의 튜너 필터)에 서브 미트 되지 않으면 안 된다.

주 이 버젼의 Microsoft® Broadcast Driver Architecture 에서는, 2 개의 네트워크 프로바이더 필터가 제공되는, 1 개(살)은 ATSC 네트워크이며, 이제(벌써) 1 개(살)은 DVB-S 네트워크이다. DVB-S 프로바이더에 대해서는 디폴트 튜닝 공간은 제공되지 않는, 왜냐하면 그것을 정의하려면 개별의 정보가 필요하기 때문에이다. 어플리케이션은 SystemTuningSpaces 오브젝트를 사용해 (C++ 에서는 ITuningSpaceContainer 인터페이스를 사용해), 유저가 구독하는 서비스에 대해 유저로부터 제공된 기본 정보를 베이스로 한, 어플리케이션 자신의 DVB-S 튜닝 공간을 생성 해야 한다.

다른 튜닝 모델 오브젝트

Microsoft 튜닝 모델은 이 섹션의 시작해에 설명한 것과는 다른 오브젝트를 포함한다. 다음의 그림은 모든 튜닝 모델 오브젝트간의 모든 관계를 나타낸다. C++ 의 용어에서는 이 다이어그램은 base class간의 관계를 나타낸다. 츄리크에스트를 생성, 서브 미트 하는 실제의 프로세스에서는, 어플리케이션은 반드시 같은 타입의 네트워크 모두에게 고유의 상속 클래스를 사용해 동작한다.

일반적인 튜닝 모델 오브젝트의 관계

튜닝 공간 컨테이너 는 시스템으로 이용 가능한 튜닝 공간의 레지스트리를 찾아, 튜닝 공간 오브젝트를 인스턴스화한다.

튜닝 공간 에는 3 개의 기본적 역할이 있다. 개별의 프로그램 소스에서는, 그것은 네트워크 타입과"TV:" 모니카네임스페이스르르의 컨텐츠 퍼스와 츄리크에스트오브제크트의 생성이다. "TV:" Uniform Resource Identifiers (URIs)는 HTML 나 XML 에 짜넣을 수가 있어 올바른 오브젝트 인스턴스에의 바인드용으로 퍼스 되지 않으면 안 된다. 바인드는 COM 오브젝트를 모니카로부터 취득하기 위한 COM 용어이다. 이 경우, 튜닝 공간은 네트워크 고유의 퍼스를 제공하므로,"TV:" URI 에의 바인드는 그 튜닝 공간의 츄리크에스트오브제크트가 된다.

locator 오브젝트는 츄스페이스와 연결시킬 수 있어보다 상세한 정보를 제공하는, 이 정보를 사용해 디바이스 드라이버는 튜닝 공간내에서 지정된 채널 혹은 주파수를 츄 하기 위해서 사용한다.

컴퍼넌트는 MPEG-2 프로그램 스트림내의 기본 스트림을 참조한다, 예를 들어 비디오, 오디오 1, 오디오 2, 오디오 3, 프로그램 서비스 정보 (PSI) 등등. 이러한 값은 새로운 주파수에 츄 된 다음에 네트워크 프로바이더가 기입한다.

각 컴퍼넌트는컴포넌트 타입 오브젝트와 연결시킬 수 있는, 그것은, 어느 언어가 오디오 기본 스트림으로 이야기해져 있는 것과 같은, 컴퍼넌트에 대한 정보를 가진다. 어플리케이션은 각 유저가 참조하는 컴포넌트 타입의 리스트를 유지한다. 현재의 유저의 리스트는 ITuner 를 통해 네트워크 프로바이더에 서브 미트 되는 것이 당연하다. 그러한 리스트가 제공되지 않으면 네트워크 프로바이더는 튜닝 공간내의 디폴트 우선 컴포넌트 타입 리스트를 사용한다. 써드파티는 새로운 우선 컴포넌트 타입을 정의할 수가 있다. 각 유저의 우선 컴포넌트 타입의 리스트를 유지하는 것에 의해, 어플리케이션은 특별한 조건을 제외해 컴퍼넌트와 직접 교환할 것은 없다. 특별한 조건과는 다음과 같은 경우인, 우선 언어가 영어이지만 시청자가 독일어 오디오를 대신에 (듣)묻고 싶다고 했을 때, 우선 오디오 트럭이 AC-3 이지만 사용자가 단청의 트럭으로 변경하려고 했을 때.

네트워크 프로바이더가 츄리크에스트를 받아, 개별의 채널 혹은 주파수에 츄 했을 때, 네트워크 프로바이더는 트랜스폴트 정보 필터가 취득한 PSI 정보를 베이스로 츄리크에스트의 컴퍼넌트 리스트를 기입한다. 다음에 네트워크 프로바이더는 현재의 유저의 우선 컴포넌트 타입과 그 정보를 비교해, 유저의 요구에 적합하는 것이 이용 가능하면, 적절한 기본 스트림에 츄 한다. 이 최초의 츄리크에스트가 서브 미트 된 다음에, 어플리케이션은 현재 아크티브궶츄리크에스트를 취득해, 새로운컴퍼넌트 리스트에 액세스 할 수 있다. 이 츄리크에스트는 유저의 선택 명령으로서 업데이트 된컴퍼넌트 리스트로 재차 서브 미트 된다. 이 예는 오디오 트럭을 디폴트 우선 이외의 언어로 변경하는 경우이다. 우선 컴퍼넌트는츄리크에스트의 컴퍼넌트 리스트가 하늘 혹은 무효의 경우만 사용된다. 다른 컴퍼넌트가 액티브하겠지가 비액티브하겠지가, 츄리크에스트는 몇번이나 재서브 미트 될 수 있으므로 이것은 필요하다.


BDA 디지털 TV 레퍼런스

이 주제는, 이하의 섹션으로부터 구성된다 :

  • BDA COM 인터페이스
  • 튜닝 모델의 스크립트 가능한 오브젝트


BDA COM 인터페이스

이하의 Microsoft® Broadcast Driver Architecture (BDA) COM 인터페이스는, C/C++ 어플리케이션으로부터 액세스 할 수 있다.

튜닝 공간 인터페이스

어플리케이션에서는, ITuningSpaceContainer 를 지원 하는 튜닝 공간 컨테이너 오브젝트를 사용해, 튜닝 공간의 생성 또는 액세스가 생긴다. base class ITuningSpace 인터페이스를 직접 사용할 것은 없다. 항상, 특정의 네트워크 타입에 고유의 파생 인터페이스를 사용한다.

ITuningSpace | 특정의 튜닝 공간 인터페이스를 위한 base class.
IAnalogRadioTuningSpace | 지상파 라디오 네트워크 고유의 튜닝 공간.
IAnalogTVTuningSpace | 아날로그 TV 네트워크 고유의 튜닝 공간.
IATSCTuningSpace | ATSC 네트워크 고유의 튜닝 공간.
IDVBTuningSpace | DVB 네트워크 고유의 튜닝 공간.
ITuningSpaceContainer | 어플리케이션으로부터 사용되어 새로운 튜닝 공간의 생성이나, 기존의 튜닝 공간의 열거 또는 수정을 실시한다.
IEnumTuningSpaces | 튜닝 공간을 열거하는 표준 COM 열거 인터페이스.

튜닝 요구 인터페이스

튜닝 요구를 어플리케이션으로부터 직접 생성 할 것은 없다. 튜닝 요구는, 튜닝 공간 오브젝트의 ITuningSpace::CreateTuneRequest 를 호출해 생성 한다. 어플리케이션에서는, 돌려주어진 오브젝트에의 포인터를 받은 후, 그 오브젝트의 QueryInterface 를 호출해, 튜닝 요구의 수정에 사용하는 네트워크 고유의 인터페이스를 조회한다.

ITuneRequest | 튜닝 요구 오브젝트로 공개된다. 튜닝 요구 오브젝트를 생성 하는 것은, 튜닝 공간 오브젝트이다. 어플리케이션에서는, 튜닝 요구를 수정해 튜너에 발행할 수 있다.
IChannelTuneRequest | 아날로그 TV 네트워크 고유의 튜닝 요구 오브젝트에 이행 된다.
IATSCChannelTuneRequest | ATSC TV 네트워크 고유의 튜닝 요구 오브젝트에 이행 된다.

스트림 컴퍼넌트 인터페이스

이 문맥에서는, 브로드캐스트내의 서브 스트림을 "컴퍼넌트 " 라고 말한다. 어플리케이션에서는, 튜닝 공간에 관련짓는 일련의 디폴트 우선 컴포넌트 타입을 지정하는 것만을 목적으로, Component 오브젝트를 생성 한다. 브로드캐스트 스트림의 실제의 컴퍼넌트는, 수신 시작 다음이 아니면 모른다. 그 시점에서, 네트워크 프로바이더가 Component 오브젝트 정보를 설정 하면, 어플리케이션으로부터 이 정보를 취득해, 이 정보를 사용해, 예를 들어 오디오 스트림을 변경하거나 현재 이용 가능한 오디오 스트림을 판단하거나 할 수 있게 된다.

IComponent | 특정 컴퍼넌트 인터페이스를 위한 base class.
IComponentType | 특정 컴포넌트 타입 인터페이스를 위한 base class.
IComponentTypes | 표준 COM 의 컴포넌트 타입 리스트를 제공한다.
IComponents | 표준 COM 의 컴퍼넌트 리스트를 제공한다.
ILanguageComponentType | 서브 스트림의 언어에 관련지을 수 있었던 컴포넌트 타입.
IMPEG2ComponentType | MPEG-2 스트림 타입에 관련지을 수 있었던 컴포넌트 타입에 이행 된다.
IATSCComponentType | 오디오 스트림이 AC-3 포맷화 제발을 나타내는 컴포넌트 타입에 이행 된다.
IEnumComponents | 현재의 브로드캐스트 스트림에 포함되는 전컴퍼넌트를 (액티브한가 어떤가에 관계없이) 저장 하는 표준 COM 콜렉션 오브젝트에 이행 된다.

locator 인터페이스

locator 오브젝트는, 그래프에 포함되는 네트워크 프로바이더 및 그 외의 필터가, 어떤 종류의 경우에, 튜닝 요구에 응하기 (위해)때문에, 튜닝의 방법과 대상의 판단에 사용한다. 디버그를 목적으로 하는 경우를 제외해, 어플리케이션으로 이러한 인터페이스를 사용할 것은 없다.

ILocator | 네트워크 타입 고유의 튜닝 공간 locator를 위한 base class.
IATSCLocator | 네트워크 프로바이더로부터 불려 가 ATSC 네트워크내에서의 튜닝에 관한 정보를 취득한다. 어플리케이션에서는 사용하지 않는다.

네트워크 프로바이더 인터페이스

이러한 인터페이스는, 네트워크 프로바이더 필터로 공개된다. 필터에서는, 어플리케이션으로부터 발행된 튜닝 요구 및 그 외의 커멘드를, 이러한 인터페이스를 사용해 처리한다.

ITuner | 어플리케이션으로부터 튜닝 요구 및 그 외의 데이터를 받기 위한 base class 인터페이스. 필터 그래프내의 네트워크 프로바이더 필터로 지원 된다.
IScanningTuner | 필터 그래프내의 네트워크 프로바이더 필터로 지원 된다. ITuner 를 계승한다. 디폴트의 네트워크 프로바이더 필터를 사용하고 있는 어플리케이션에서는, QueryInterface 를 사용해 ITuner 는 아니고 IScanningTuner 를 조회해야 한다.


IAnalogRadioTuningSpace 인터페이스

이 인터페이스는, AnalogRadioTuningSpace 오브젝트에 이행 된다.

메소드명 | 설명
ITuningSpace 오브젝트
get_UniqueName | 튜닝 공간의 고유의 명칭을 취득한다. 고유의 명칭은 약칭이나 GUID 이다.
put_UniqueName | 튜닝 공간의 고유의 명칭을 설정한다. 고유의 명칭은 약칭이나 GUID 이다.
get_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 취득한다.
put_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 설정한다.
get_CLSID | 튜닝 공간의 CLSID 를 BSTR 로서 취득한다.
get_NetworkType | 튜닝 공간의 네트워크 타입 GUID 를 BSTR 로서 취득한다.
put_NetworkType | 이 튜닝 공간의 네트워크 타입을 BSTR 로서 설정한다.
get__NetworkType | 튜닝 공간의 네트워크 타입을 GUID 로서 취득한다.
put__NetworkType | 이 튜닝 공간의 네트워크 타입을 REFCLSID 로서 설정한다.
CreateTuneRequest | 하늘의 (초기화되어 있지 않다) 튜닝 요구를 나타내는 COM 오브젝트를 생성 한다.
EnumCategoryGUIDs | DirectShow 카테고리 GUID 를 열거하는 열거자를 생성 한다. 카테고리 GUID 는, 튜닝 공간을 지원 하는 필터의 종류를 나타내는 것이다.
EnumDeviceMonikers | 이 튜닝 공간을 지원 하는 튜너 입력 (필터)을 나타내는 데바이스모니카의 열거자를 생성 한다.
get_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 돌려준다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
put_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 생성 한다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
get_DefaultLocator | 로컬 시스템의 디폴트 locator를 취득한다.
put_DefaultLocator | 로컬 시스템의 디폴트 locator를 설정한다.
IAnalogRadioTuningSpace 메소드
get_MinFrequency | 이 튜닝 공간의 최소 주파수를 취득한다.
put_MinFrequency | 이 튜닝 공간의 최소 주파수를 설정한다.
get_MaxFrequency | 이 튜닝 공간의 최대 주파수를 취득한다.
put_MaxFrequency | 이 튜닝 공간의 최대 주파수를 설정한다.
get_Step | 이 튜닝 공간의 스텝 증분을 취득한다.
put_Step | 이 튜닝 공간의 스텝 증분을 취득한다.

IAnalogRadioTuningSpace::get_MinFrequency

IAnalogRadioTuningSpace 인터페이스

이 튜닝 공간의 최소 주파수를 취득한다.

구문

HRESULT get_MinFrequency(
    long* MinFrequencyVal
    );

파라미터

MinFrequencyVal
[out, retval] 최소 주파수를 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IAnalogRadioTuningSpace::put_MinFrequency

IAnalogRadioTuningSpace 인터페이스

이 튜닝 공간의 최소 주파수를 설정한다.

구문

HRESULT put_MinFrequency(
    long NewMinFrequencyVal
    );

파라미터

NewMinFrequencyVal
[in] 최소 주파수를 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IAnalogRadioTuningSpace::get_MaxFrequency

IAnalogRadioTuningSpace 인터페이스

이 튜닝 공간의 최대 주파수를 취득한다.

구문

HRESULT get_MaxFrequency(
    long* MaxFrequencyVal
    );

파라미터

MaxFrequencyVal
[out, retval] 최대 주파수를 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IAnalogRadioTuningSpace::put_MaxFrequency

IAnalogRadioTuningSpace 인터페이스

이 튜닝 공간의 최대 주파수를 설정한다.

구문

HRESULT put_MaxFrequency(
    long NewMaxFrequencyVal
    );

파라미터

NewMaxFrequencyVal
[in] 최대 주파수를 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IAnalogRadioTuningSpace::get_Step

IAnalogRadioTuningSpace 인터페이스

이 튜닝 공간의 스텝 증분을 취득한다.

구문

HRESULT get_Step(
    long* StepVal
    );

파라미터

StepVal
[out, retval] 스텝값을 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IAnalogRadioTuningSpace::put_Step

IAnalogRadioTuningSpace 인터페이스

이 튜닝 공간의 스텝 증분을 취득한다.

구문

HRESULT put_Step(
    long NewStepVal
    );

파라미터

NewStepVal
[in] 스텝 증분을 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IAnalogTVTuningSpace 인터페이스

네트워크 타입이 아날로그 TV 의 튜닝 공간을 나타낸다.

메소드명 | 설명
ITuningSpace 메소드
get_UniqueName | 튜닝 공간의 고유의 명칭을 취득한다. 고유의 명칭은 약칭이나 GUID 이다.
put_UniqueName | 튜닝 공간의 고유의 명칭을 설정한다. 고유의 명칭은 약칭이나 GUID 이다.
get_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 취득한다.
put_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 설정한다.
get_CLSID | 튜닝 공간의 CLSID 를 BSTR 로서 취득한다.
get_NetworkType | 튜닝 공간의 네트워크 타입 GUID 를 BSTR 로서 취득한다.
put_NetworkType | 튜닝 공간의 네트워크 타입 GUID 를 BSTR 로서 설정한다.
get__NetworkType | 이 튜닝 공간의 네트워크 타입을 GUID 로서 취득한다.
put__NetworkType | 이 튜닝 공간의 네트워크 타입을 REFCLSID 로서 설정한다.
CreateTuneRequest | 하늘의 (초기화되어 있지 않다) 튜닝 요구를 나타내는 COM 오브젝트를 생성 한다.
EnumCategoryGUIDs | DirectShow 카테고리 GUID 를 열거하는 열거자를 생성 한다. 카테고리 GUID 는, 튜닝 공간을 지원 하는 필터의 종류를 나타내는 것이다.
EnumDeviceMonikers | 이 튜닝 공간을 지원 하는 튜너 입력 (필터)을 나타내는 데바이스모니카의 열거자를 생성 한다.
get_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 돌려준다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
put_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 설정한다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
get_DefaultLocator | 로컬 시스템의 디폴트 locator를 취득한다.
put_DefaultLocator | 로컬 시스템의 디폴트 locator를 설정한다.
IAnalogTVTuningSpace 메소드
get_MinChannel | 이 튜닝 공간의 최소 채널 번호를 취득한다.
put_MinChannel | 이 튜닝 공간의 최소 채널 번호를 설정한다.
get_MaxChannel | 이 튜닝 공간의 최대 채널 번호를 취득한다.
put_MaxChannel | 이 튜닝 공간의 최대 채널 번호를 설정한다.
get_InputType | 튜닝 공간에서 사용하는 입력 타입 (안테나 또는 케이블)을 취득한다.
put_InputType | 튜닝 공간에서 사용하는 입력 타입 (안테나 또는 케이블)을 설정한다.
get_CountryCode | 튜닝 공간의 나라 코드를 취득한다 (TAPI 의 나라 코드에 준거).
put_CountryCode | 튜닝 공간의 나라 코드를 설정한다 (TAPI 의 나라 코드에 준거).

IAnalogTVTuningSpace::get_MinChannel

IAnalogTVTuningSpace 인터페이스

이 튜닝 공간의 최소 채널 번호를 취득한다.

구문

HRESULT get_MinChannel(
    short* MinChannelVal
    );

파라미터

MinChannelVal
[out, retval] 최소 채널 번호의 값을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

안테나에 접속된 NTSC 튜닝 공간은, 값 2 를 돌려준다.

IAnalogTVTuningSpace::put_MinChannel

IAnalogTVTuningSpace 인터페이스

이 튜닝 공간의 최소 채널 번호를 설정한다.

구문

HRESULT put_MinChannel(
    short NewMinChannelVal
    );

파라미터

NewMinChannelVal
[in] 최소 채널 번호를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IAnalogTVTuningSpace::get_MaxChannel

IAnalogTVTuningSpace 인터페이스

이 튜닝 공간의 최대 채널 번호를 취득한다.

구문

HRESULT get_MaxChannel(
    short* MaxChannelVal
    );

파라미터

MaxChannelVal
[out, retval] 최대 채널 번호의 값을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

예를 들어, 안테나에 접속된 NTSC 튜닝 공간은 69 를 돌려준다.

IAnalogTVTuningSpace::put_MaxChannel

IAnalogTVTuningSpace 인터페이스

이 튜닝 공간의 최대 채널 번호를 설정한다.

구문

HRESULT put_MaxChannel(
    short NewMaxChannelVal
    );

파라미터

NewMaxChannelVal
[in] 최대 채널 번호를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IAnalogTVTuningSpace::get_InputType

IAnalogTVTuningSpace 인터페이스

튜닝 공간에서 사용하는 입력 타입 (안테나 또는 케이블)을 취득한다.

구문

HRESULT get_InputType(
    TunerInputType* InputTypeVal
    );

파라미터

InputTypeVal
[out, retval] 입력 타입을 받는 TunerInputType 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IAnalogTVTuningSpace::put_InputType

IAnalogTVTuningSpace 인터페이스

튜닝 공간에서 사용하는 입력 타입 (안테나 또는 케이블)을 설정한다.

구문

HRESULT put_InputType(
    TunerInputType NewInputTypeVal
    );

파라미터

NewInputTypeVal
[in] 입력 타입을 지정하는 TunerInputType 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IAnalogTVTuningSpace::get_CountryCode

IAnalogTVTuningSpace 인터페이스

튜닝 공간의 나라 코드를 취득한다 (TAPI 의 나라 코드에 준거).

구문

HRESULT get_CountryCode(
    long* CountryCodeVal
    );

파라미터

CountryCodeVal
[out, retval] 국 코드의 값을 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

튜너는, 이 나라 코드를 사용해, 적합한 채널과 주파수의 매핑을 판단할 수 있다.

IAnalogTVTuningSpace::put_CountryCode

IAnalogTVTuningSpace 인터페이스

튜닝 공간의 나라 코드를 설정한다 (TAPI 의 나라 코드에 준거).

구문

HRESULT put_CountryCode(
    long NewCountryCodeVal
    );

파라미터

NewCountryCodeVal
[in] 국 코드를 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

튜너는, 이 나라 코드를 사용해, 적합한 채널과 주파수의 매핑을 판단할 수 있다.


IATSCChannelTuneRequest 인터페이스

이 인터페이스는, ATSCChannelTuneRequest 오브젝트에 이행 된다.

메소드명 | 설명
ITuneRequest 메소드
get_TuningSpace | 튜닝 공간 오브젝트를 취득한다.
get_Components | IComponent 오브젝트의 콜렉션을 취득한다.
Clone | 이 튜닝 요구의 새로운 카피를 돌려준다.
get_Locator | 네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 취득한다.
put_Locator | 네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 설정한다.
IChannelTuneRequest 메소드
get_Channel | 튜닝 하는 채널을 취득한다.
put_Channel | 튜닝 하는 채널을 설정한다.
IATSCChannelTuneRequest 메소드
get_MinorChannel | 튜닝 하는 마이너 채널을 취득한다.
put_MinorChannel | 튜닝 하는 마이너 채널을 설정한다.

IATSCChannelTuneRequest::get_MinorChannel

IATSCChannelTuneRequest 인터페이스

튜닝 하는 마이너 채널을 취득한다.

구문

HRESULT get_MinorChannel(
    short* MinorChannel
    );

파라미터

MinorChannel
[out, retval] 현재의 마이너 채널을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IATSCChannelTuneRequest::put_MinorChannel

IATSCChannelTuneRequest 인터페이스

튜닝 하는 마이너 채널을 설정한다.

구문

HRESULT put_MinorChannel(
    short MinorChannel
    );

파라미터

MinorChannel
[in] 마이너 채널을 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IATSCComponentType 인터페이스

IATSCComponentType 인터페이스는, ATSCComponentType 오브젝트에 이행 된다. 이 인터페이스를 사용 하면, 스트림 타입이 오디오의 경우에, 어플리케이션으로부터 AC3 스트림인가 어떤가를 판단할 수 있다.

메소드명 | 설명
get_Flags | 오디오 컴퍼넌트가 AC-3 포맷화 제발을 나타내는 플래그를 돌려준다.
put_Flags | 오디오 컴퍼넌트가 AC-3 포맷화 제발을 나타내는 플래그를 설정한다.

IATSCComponentType::get_Flags

IATSCComponentType 인터페이스

오디오 컴퍼넌트가 AC-3 포맷화 제발을 나타내는 플래그를 돌려준다.

구문

HRESULT get_Flags(
    long* Flags
    );

파라미터

*Flags
[out, retval] ATSCComponentTypeFlags 플래그를 받는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

정의되고 있는 플래그는, AC-3 오디오를 나타내는 플래그뿐이다.
    typedef enum ATSCComponentTypeFlags {
        ATSCCT_AC3 = 0x00000001,
    } ATSCComponentTypeFlags;

IATSCComponentType::put_Flags

IATSCComponentType 인터페이스

오디오 컴퍼넌트가 AC-3 포맷화 제발을 나타내는 플래그를 설정한다.

구문

HRESULT put_Flags(
    long flags
    );

파라미터

flags
[in] Long 형의 변수. 0x1 는 오디오 스트림이 AC-3 인 것을 나타낸다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

정의되고 있는 플래그는, AC-3 오디오를 나타내는 플래그뿐이다.
    typedef enum ATSCComponentTypeFlags {
        ATSCCT_AC3 = 0x00000001,
    } ATSCComponentTypeFlags;


IATSCLocator 인터페이스

이 인터페이스는, ATSCLocator 오브젝트에 이행 된다.

ILocator 메소드명 | 설명
Clone | locator의 카피를 생성 한다.
get_CarrierFrequency | RF 신호의 주파수를 취득한다.
get_InnerFEC | 사용하는 내부 전방 잘못 정정의 타입을 취득한다.
get_InnerFECRate | 내부 FEC 레이트를 취득한다.
get_Modulation | 변조 타입을 취득한다.
get_OuterFEC | 사용하는 외부 전방 잘못 정정의 타입을 취득한다.
get_OuterFECRate | 외부 FEC 레이트를 설정한다.
SymbolRate | QPSK 심볼 레이트를 취득한다.
put_CarrierFrequency | RF 신호의 주파수를 설정한다.
put_InnerFEC | 사용하는 내부 전방 잘못 정정의 타입을 설정한다.
put_InnerFECRate | 내부 FEC 레이트를 설정한다.
put_Modulation | 변조 타입을 설정한다.
put_OuterFEC | 사용하는 외부 전방 잘못 정정의 타입을 설정한다.
put_OuterFECRate | 외부 FEC 레이트를 설정한다.
SymbolRate | QPSK 심볼 레이트를 설정한다.
IATSCLocator 메소드명 | 설명
get_PhysicalChannel | 물리 채널을 취득한다.
put_PhysicalChannel | 물리 채널을 설정한다.
get_TSID | 트랜스폴트 스트림 ID 를 취득한다.
put_TSID | 트랜스폴트 스트림 ID 설정한다.

IATSCLocator::get_PhysicalChannel

IATSCLocator 인터페이스

물리 채널을 취득한다.

구문

HRESULT get_PhysicalChannel(
    short* PhysicalChannel
    );

파라미터

*PhysicalChannel
[out, retval] 물리 채널을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IATSCLocator::put_PhysicalChannel

IATSCLocator 인터페이스

물리 채널을 설정한다.

구문

HRESULT put_PhysicalChannel(
    short PhysicalChannel
    );

파라미터

PhysicalChannel
[in] 물리 채널을 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IATSCLocator::get_TSID

IATSCLocator 인터페이스

트랜스폴트 스트림 ID 를 취득한다.

구문

HRESULT get_TSID(
short* TSID
    );

파라미터

*TSID
[out, retval] 트랜스폴트 스트림 ID 를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IATSCLocator::put_TSID

IATSCLocator 인터페이스

트랜스폴트 스트림 ID 를 설정한다.

구문

HRESULT put_TSID(
short TSID
    );

파라미터

TSID
[in] 트랜스폴트 스트림 ID 를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IATSCTuningSpace 인터페이스

IATSCTuningSpace 는,ITuningSpace 및 IAnalogTVTuningSpace 를 계승해, ATSC 네트워크 타입을 나타내는 오브젝트에 이행 된다. 이러한 오브젝트는, 레지스트리내의 정보에 근거해 튜닝 공간 컨테이너가 생성 한다. IATSCTuningSpace 오브젝트는,IATSCChannelTuneRequest 를 공개하는 튜닝 요구를 생성 한다.

메소드명 | 설명
ITuningSpace 메소드
get_UniqueName | 튜닝 공간의 고유의 명칭을 취득한다. 고유의 명칭은 약칭이나 GUID 이다.
put_UniqueName | 튜닝 공간의 고유의 명칭을 설정한다. 고유의 명칭은 약칭이나 GUID 이다.
get_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 취득한다.
put_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 설정한다.
get_CLSID | 튜닝 공간의 CLSID 를 BSTR 로서 취득한다.
get_NetworkType | 튜닝 공간의 네트워크 타입 GUID 를 BSTR 로서 취득한다.
put_NetworkType | 이 튜닝 공간의 네트워크 타입을 BSTR 로서 설정한다.
get__NetworkType | 튜닝 공간의 네트워크 타입을 GUID 로서 취득한다.
put__NetworkType | 이 튜닝 공간의 네트워크 타입을 REFCLSID 로서 설정한다.
CreateTuneRequest | 하늘의 (초기화되어 있지 않다) 튜닝 요구를 나타내는 COM 오브젝트를 생성 한다.
EnumCategoryGUIDs | DirectShow 카테고리 GUID 를 열거하는 열거자를 생성 한다. 카테고리 GUID 는, 튜닝 공간을 지원 하는 필터의 종류를 나타내는 것이다.
EnumDeviceMonikers | 이 튜닝 공간을 지원 하는 튜너 입력 (필터)을 나타내는 데바이스모니카의 열거자를 생성 한다.
get_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 돌려준다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
put_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 설정한다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
get_DefaultLocator | 로컬 시스템의 디폴트 locator를 취득한다.
put_DefaultLocator | 로컬 시스템의 디폴트 locator를 설정한다.
IAnalogTVTuningSpace 메소드
get_MinChannel | 이 튜닝 공간의 최소 채널 번호를 취득한다.
put_MinChannel | 이 튜닝 공간의 최소 채널 번호를 설정한다.
get_MaxChannel | 이 튜닝 공간의 최대 채널 번호를 취득한다.
put_MaxChannel | 이 튜닝 공간의 최대 채널 번호를 설정한다.
get_InputType | 튜닝 공간에서 사용하는 입력 타입 (안테나 또는 케이블)을 취득한다.
put_InputType | 튜닝 공간에서 사용하는 입력 타입 (안테나 또는 케이블)을 설정한다.
get_CountryCode | 튜닝 공간의 나라 코드를 취득한다 (TAPI 의 나라 코드에 준거).
put_CountryCode | 튜닝 공간의 나라 코드를 설정한다 (TAPI 의 나라 코드에 준거).
IATSCTuningSpace 메소드
get_MinMinorChannel | 이 튜닝 공간에 용서되는 최소의 마이너 채널 번호를 취득한다.
put_MinMinorChannel | 이 튜닝 공간에 용서되는 최소의 마이너 채널 번호를 설정한다.
get_MaxMinorChannel | 이 튜닝 공간의 최대 마이너 채널 번호를 취득한다.
put_MaxMinorChannel | 이 튜닝 공간의 최대 마이너 채널 번호를 설정한다.
get_MinPhysicalChannel | 이 튜닝 공간에 용서되는 최소의 물리 채널 번호를 취득한다.
put_MinPhysicalChannel | 이 튜닝 공간에 용서되는 최소의 물리 채널 번호를 설정한다.
get_MaxPhysicalChannel | 이 튜닝 공간에 용서되는 최대의 물리 채널 번호를 취득한다.
put_MaxPhysicalChannel | 이 튜닝 공간에 용서되는 최대의 물리 채널 번호를 설정한다.

IATSCTuningSpace::get_MinMinorChannel

IATSCTuningSpace 인터페이스

이 튜닝 공간에 용서되는 최소의 마이너 채널 번호를 취득한다.

구문

HRESULT get_MinMinorChannel(
    short* MinMinorChannelVal
    );

파라미터

MinMinorChannelVal
[out, retval] 최소 마이너 채널 번호를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IATSCTuningSpace::put_MinMinorChannel

IATSCTuningSpace 인터페이스

이 튜닝 공간에 용서되는 최소의 마이너 채널 번호를 설정한다.

구문

HRESULT put_MinMinorChannel(
    short NewMinMinorChannelVal
    );

파라미터

NewMinMinorChannelVal
[in] 최소 마이너 채널을 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

최소 마이너 채널을 최대 마이너 채널보다 크게 하지 않기 때문에, 이 프로퍼티보다 먼저 MaxMinorChannel 프로퍼티를 설정할 필요가 있다. 어느 쪽의 프로퍼티도, 디폴트값은 -1 (설정 없음)이다.

IATSCTuningSpace::get_MaxMinorChannel

IATSCTuningSpace 인터페이스

이 튜닝 공간의 최대 마이너 채널 번호를 취득한다.

구문

HRESULT get_MaxMinorChannel(
    short* MaxMinorChannelVal
    );

파라미터

MaxMinorChannelVal
[out, retval] 최대 마이너 채널 번호를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IATSCTuningSpace::put_MaxMinorChannel

IATSCTuningSpace 인터페이스

이 튜닝 공간의 최대 마이너 채널 번호를 취득한다.

구문

HRESULT put_MaxMinorChannel(
    short NewMaxMinorChannelVal
    );

파라미터

NewMaxMinorChannelVal
[in] 최대 마이너 채널을 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

최소 마이너 채널을 최대 마이너 채널보다 크게 하지 않기 때문에,MinMinorChannel 프로퍼티보다 먼저 이 프로퍼티를 설정할 필요가 있다. 어느 쪽의 프로퍼티도, 디폴트값은 -1 (설정 없음)이다.

IATSCTuningSpace::get_MinPhysicalChannel

IATSCTuningSpace 인터페이스

이 튜닝 공간의 최소 물리 채널 번호를 설정한다.

구문

HRESULT get_MinPhysicalChannel(
    short* MinPhysicalChannelVal
    );

파라미터

MinPhysicalChannelVal
[out, retval] 최소 물리 채널을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IATSCTuningSpace::put_MinPhysicalChannel

IATSCTuningSpace 인터페이스

이 튜닝 공간의 최소 물리 채널 번호를 설정한다.

구문

HRESULT put_MinPhysicalChannel(
    short NewMinPhysicalChannelVal
    );

파라미터

NewMinPhysicalChannelVal
[in] 최소 물리 채널을 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IATSCTuningSpace::get_MaxPhysicalChannel

IATSCTuningSpace 인터페이스

이 튜닝 공간의 최대 물리 채널 번호를 취득한다.

구문

HRESULT get_MaxPhysicalChannel(
    short* MaxPhysicalChannelVal
    );

파라미터

MaxPhysicalChannelVal
[out, retval] 최대 물리 채널을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IATSCTuningSpace::put_MaxPhysicalChannel

IATSCTuningSpace 인터페이스

이 튜닝 공간의 최대 물리 채널 번호를 설정한다.

구문

HRESULT put_MaxPhysicalChannel(
    short NewMaxPhysicalChannelVal
    );

파라미터

NewMaxPhysicalChannelVal
[in] 최대 물리 채널을 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IChannelTuneRequest 인터페이스

IChannelTuneRequest 인터페이스는, 아날로그 TV 고유의 TuneRequest 오브젝트에 이행 된다. 이 인터페이스를 사용 하면, 어플리케이션으로부터 아날로그 TV 네트워크용의 튜닝 요구를 생성 할 수 있다.

메소드명 | 설명
ITuneRequest 메소드
get_TuningSpace | 튜닝 공간 오브젝트를 취득한다.
get_Components | IComponent 오브젝트의 콜렉션을 취득한다.
Clone | 이 튜닝 요구의 새로운 카피를 돌려준다.
get_Locator | 네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 취득한다.
put_Locator | 네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 설정한다.
IChannelTuneRequest 메소드
get_Channel | 튜닝 하는 채널을 취득한다.
put_Channel | 튜닝 하는 채널을 설정한다.

IChannelTuneRequest::get_Channel

IChannelTuneRequest 인터페이스

튜닝 하는 채널을 취득한다.

구문

HRESULT get_Channel(
    short* Channel
    );

파라미터

Channel
[out, retval] 현재의 채널을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IChannelTuneRequest::put_Channel

IChannelTuneRequest 인터페이스

튜닝 하는 채널을 설정한다.

구문

HRESULT put_Channel(
    short Channel
    );

파라미터

Channel
[in] 채널을 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

Channel 의 지정값이 튜닝 공간으로 설정된 최소 채널보다 작은 경우는, 최대 채널에 "rack-around " 한다. 같이Channel 의 지정값이 튜닝 공간으로 설정된 최대 채널보다 큰 경우는, 최소 채널에 "rack-around " 한다.


IComponent 인터페이스

IComponent 인터페이스는, 모든 Component 오브젝트의 base class 인터페이스이며, 컴퍼넌트 (주로 프로그램 스트림내의 기본 스트림)의 일반적인 특성을 기술한다. IMPEG2Component 등의 파생 인터페이스는, IComponent 를 계승해, 컴퍼넌트에 관한 소정의 네트워크 타입 고유의 프로퍼티를 기술한다. 수신이 시작 하면, 트랜스폴트 정보 필터 (TIF)가, Component 오브젝트를 생성 해 튜닝 요구에 어태치 한다. 모든 Component 오브젝트는, IPersistPropertyBag 를 지원 한다.

메소드명 | 설명
get_Type | 컴퍼넌트의 일반적인 특성을 기술하는 IComponentType 오브젝트를 취득한다.
put_Type | 컴퍼넌트의 일반적인 특성을 기술하는 IComponentType 오브젝트를 설정한다.
get_DescLangID | 설명의 프레젠테이션에 사용하는 언어를 취득한다.
put_DescLangID | 설명의 프레젠테이션에 사용하는 언어를 설정한다.
get_Status | 컴퍼넌트의 요구된 상태 또는 실제 상태를 취득한다.
put_Status | 컴퍼넌트의 요구된 상태 또는 실제 상태를 설정한다.
get_Description | 컴퍼넌트의 설명을 취득한다.
put_Description | 컴퍼넌트의 설명을 설정한다.
Clone | 컴퍼넌트의 새로운 카피를 생성 한다.

IComponent::Clone

IComponent 인터페이스

컴퍼넌트의 새로운 카피를 생성 한다.

구문

HRESULT Clone(
    IComponent** NewComponent
    );

파라미터

NewComponent
[out, retval] 새로운 컴퍼넌트로 설정하는 IComponent 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponent::get_Type

IComponent 인터페이스

컴퍼넌트의 일반적인 특성을 기술하는 IComponentType 오브젝트를 취득한다.

구문

HRESULT get_Type(
    IComponentType** CT
    );

파라미터

CT
[out, retval] 취득한 컴퍼넌트로 설정하는 IComponentType 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponent::put_Type

IComponent 인터페이스

컴퍼넌트의 일반적인 특성을 기술하는 IComponentType 오브젝트를 설정한다.

구문

HRESULT put_Type(
    IComponentType* CT
    );

파라미터

CT
[in] 컴퍼넌트에 대응하는 새로운 값을 지정하는 IComponentType 오브젝트에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

IComponent base class 인터페이스를 사용하고 있을 때는, 타입에 NULL 를 설정할 수 있다. 같은 것을 IMPEG2Component 상속 클래스 인터페이스로 실행하려고 하면(자), 이 메소드는 E_POINTER 를 돌려준다. IMPEG2Component 오브젝트에서는, 설정하는 타입으로서 IComponentType base class 인터페이스를 가질 수가 없다. 이 경우, 메소드는 Type Mismatch (0x80020005)를 돌려준다.

IComponent::get_DescLangID

IComponent 인터페이스

설명의 프레젠테이션에 사용하는 언어를 취득한다.

구문

HRESULT get_DescLangID(
short* LangID
    );

파라미터

*LangID
[out, retval] 언어 ID 를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 언어는, Component 오브젝트에 포함되는 설명 정보의 언어이다. 스트림 컨텐츠의 언어를 정의하는 언어 컴포넌트 타입내의 언어 ID 와는 다르다.

IComponent::put_DescLangID

IComponent 인터페이스

설명의 프레젠테이션에 사용하는 언어를 설정한다.

구문

HRESULT put_DescLangID(
short LangID
    );

파라미터

LangID
[in] 언어 ID 를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 언어는, Component 오브젝트에 포함되는 설명 정보의 언어이다. 스트림 컨텐츠의 언어를 정의하는 언어 컴포넌트 타입내의 언어 ID 와는 다르다. 어플리케이션으로부터 이 값을 수정 하면, 다른 언어의 서브 스트림을 액티브하게 할 수가 있다.

IComponent::get_Status

IComponent 인터페이스

컴퍼넌트의 요구된 상태 또는 실제 상태를 취득한다.

구문

HRESULT get_Status(
    ComponentStatus* Status
    );

파라미터

*Status
[out, retval] 상태의 값을 받는 ComponentStatus 열거형에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

typedef enum ComponentStatus
    {
        [helpstring("Component is selected")] StatusActive,
        [helpstring("Component is not selected")] StatusInactive,
        [helpstring("Component is unavailable")] StatusUnavailable,
    } ComponentStatus;

튜너는, Components 콜렉션에 컴퍼넌트를 추가 하면 와, 컴퍼넌트가 액티브한가 어떤가를 지정할 수 있다. 어플리케이션에서는, 이 상태의 설정을 시도한 데다가, 튜닝 요구를 재발행할 수 있다. 튜너는 상태를 갱신한다. 상태에는 Active, Inactive, Unavailable 의 3 종류가 있지만, Unavailable 는, 액티브하게 하는 것을 요구되었을 때, 컴퍼넌트가 실제로 이용 가능하지 않은 경우에, 튜너만이 설정하는 상태이다.

IComponent::put_Status

IComponent 인터페이스

컴퍼넌트의 요구된 상태 또는 실제 상태를 설정한다.

구문

HRESULT put_Status(
    ComponentStatus Status
    );

파라미터

Status
[in] 상태의 값을 지정하는 ComponentStatus 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

스트림 컴퍼넌트 (서브 스트림)를 액티브/비액티브하게 하려면 , 이 메소드를 사용한다.

참조

get_Status

IComponent::get_Description

IComponent 인터페이스

컴퍼넌트의 설명을 취득한다.

구문

HRESULT get_Description(
    BSTR* Description
    );

파라미터

*Description
[out, retval] 설명을 받아들이는 BSTR 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

IComponent::put_Description

IComponent 인터페이스

컴퍼넌트의 설명을 설정한다.

구문

HRESULT put_Description(
    BSTR Description
    );

파라미터

Description
[in] 새로운 설명이 저장 된 BSTR 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, 어플리케이션은 아니고, 가이드 스토어로부터 불려 간다.


IComponents 인터페이스

디지털 TV 의 문맥에서는, 프로그램 스트림내의 서브 스트림을 "Component" 라고 말한다. 예를 들어, 프로그램 스트림에 언어가 다른 3 개의 오디오 스트림이 있는 경우에는, 개개의 오디오 스트림이 그 프로그램 스트림의 "Component" 가 된다. IComponents 인터페이스는, Component 오브젝트의 콜렉션인 Components 오브젝트에 이행 된다. 어플리케이션에서는, Components 오브젝트에 의해, 프로그램 스트림에 포함되는 컴퍼넌트를 열거해, 콜렉션에 포함되는 개개의 컴퍼넌트에 관련한 처리를 실행할 수가 있다. 모든 Components 오브젝트는, IPersistPropertyBag 도 지원 한다.

메소드명 | 설명
get_Count | 콜렉션에 포함되는 Component 오브젝트의 수를 취득한다.
get__NewEnum | Automation 클라이언트의 For...Each 루프를 지원하기 위한 열거 메소드.
EnumComponents | 콜렉션에 포함되는 컴퍼넌트를 모두 열거하는 IEnumComponents 열거자를 돌려준다.
get_Item | 지정한 인덱스 위치의 컴퍼넌트에 액세스 한다.
Add | 콜렉션에 Component 오브젝트를 추가한다.
Remove | 콜렉션으로부터 Component 오브젝트를 삭제한다.
Clone | 콜렉션의 새로운 카피를 생성 한다.

IComponents::get_Count

IComponents 인터페이스

콜렉션에 포함되는 Component 오브젝트의 수를 취득한다.

구문

HRESULT get_Count(
long* Count
    );

파라미터

Count
[out, retval] 컴퍼넌트수를 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponents::get__NewEnum

IComponents 인터페이스

Automation 클라이언트의 For...Each 루프를 지원하기 위한 열거 메소드.

구문

HRESULT get__NewEnum(
IEnumVARIANT** ppNewEnum
    );

파라미터

ppNewEnum
[out, retval] 열거자를 받는 IEnumVARIANT 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, For...Each 루프의 반복에 의해 콜렉션 전체를 처리하기 위해(때문에), 스크립트 어플리케이션 및 VB 어플리케이션용으로 제공된다. C++ 어플리케이션에서는 EnumComponents 메소드를 사용하는 것.

IComponents::EnumComponents

IComponents 인터페이스

콜렉션에 포함되는 컴퍼넌트를 모두 열거하는 IEnumComponents 열거자를 돌려준다.

구문

HRESULT EnumComponents(
    IEnumComponents** ppNewEnum
    );

파라미터

ppNewEnum
[out, retval] 새로운 열거자를 받는 IEnumComponents 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponents::get_Item

IComponents 인터페이스

지정한 인덱스 위치의 컴퍼넌트에 액세스 한다.

구문

HRESULT get_Item(
VARIANT Index,
    IComponent** ppComponent
    );

파라미터

Index
[in] 콜렉션에 있어서의 0 으로부터 시작되는 인덱스를 지정하는 VARIANT 형 변수.
ppComponent
[out, retval] 지정된 인덱스 위치의 Component 오브젝트를 받는 IComponent 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponents::Add

IComponents 인터페이스

콜렉션에 Component 오브젝트를 추가한다.

구문

HRESULT Add(
    IComponent* Component,
VARIANT* NewIndex
    );

파라미터

Component
[in] 추가하는 Component 오브젝트에의 포인터.
NewIndex
[out, retval] 추가한 컴퍼넌트의 인덱스를 받는 VARIANT 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponents::Remove

IComponents 인터페이스

콜렉션으로부터 Component 오브젝트를 삭제한다.

구문

HRESULT Remove(
VARIANT Index
    );

파라미터

Index
[in] 삭제하는 컴퍼넌트의 인덱스 번호를 지정하는 VARIANT 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponents::Clone

IComponents 인터페이스

콜렉션의 새로운 카피를 생성 한다.

구문

HRESULT Clone(
    IComponents** NewList
    );

파라미터

NewList
[out, retval] 새로운 Components 오브젝트로 설정되는, IComponents 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IComponentType 인터페이스

IComponentType 인터페이스는, ComponentType 오브젝트에 이행 되어 ComponentType 오브젝트에는, 컴퍼넌트의 각종 프로퍼티를 설정 및 취득하기 위한 메소드가 포함된다. 모든 Component 오브젝트에는,get_Type 메소드와 put_Type 메소드로 설정 및 취득하는 ComponentType 오브젝트를 관련지을 수 있고 있다.

메소드명 | 설명
Clone | 이 컴포넌트 타입의 새로운 카피를 생성 한다.
get_Category | 컴퍼넌트의 카테고리를 취득한다.
get_MediaFormatType | DirectShow 의 미디어 포맷 타입을 BSTR 로 취득한다.
get__MediaFormatType | DirectShow 의 미디어 포맷 타입을 GUID 로 취득한다.
get_MediaMajorType | DirectShow 의 미디어 메이저 타입을 BSTR 로 취득한다.
get__MediaMajorType | DirectShow 의 미디어 메이저 타입을 GUID 로 취득한다.
get_MediaSubType | DirectShow 의 미디어 서브 타입을 BSTR 로 취득한다.
get__MediaSubType | DirectShow 의 미디어 서브 타입을 GUID 로 취득한다.
get_MediaType | 컴퍼넌트의 DirectShow AM_MEDIA_TYPE 미디어 타입 구조체를 취득한다.
put_Category | 컴퍼넌트의 카테고리를 설정한다.
put_MediaFormatType | DirectShow 의 미디어 포맷 타입을 설정한다.
put__MediaFormatType | DirectShow 의 미디어 포맷 타입을 설정한다.
put_MediaMajorType | DirectShow 의 미디어 메이저 타입을 설정한다.
put__MediaMajorType | DirectShow 의 미디어 메이저 타입을 설정한다.
put_MediaSubType | DirectShow 의 미디어 서브 타입을 설정한다.
put__MediaSubType | DirectShow 의 미디어 서브 타입을 설정한다.
put_MediaType | 컴퍼넌트의 DirectShow AM_MEDIA_TYPE 미디어 타입 구조체를 설정한다.

IComponentType::Clone

IComponentType 인터페이스

이 컴포넌트 타입의 새로운 카피를 생성 한다.

구문

HRESULT Clone(
    IComponentType** NewCT
    );

파라미터

NewCT
[out, retval] 돌려주어지는 인터페이스로 설정하는 IComponentType 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentType::get_Category

IComponentType 인터페이스

컴퍼넌트의 카테고리를 취득한다.

구문

HRESULT get_Category(
    ComponentCategory* Category
    );

파라미터

Category
[out, retval] 카테고리를 받는 ComponentCategory 데이터형에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

ComponentCategory 열거형은 bdatypes.h 에 다음과 같이 정의되고 있다.
typedef enum ComponentCategory
{
CategoryNotSet = -1,
CategoryOther = 0,
CategoryVideo = 1,
CategoryAudio = 2,
CategoryText = 3,
CategoryData = 4,
} ComponentCategory;

IComponentType::get_MediaFormatType

IComponentType 인터페이스

DirectShow 의 미디어 포맷 타입을 BSTR 로 취득한다.

구문

HRESULT get_MediaFormatType(
    BSTR* MediaFormatType
    );

파라미터

MediaFormatType
[out, retval] GUID 를 받는 BSTR 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentType::get__MediaFormatType

IComponentType 인터페이스

DirectShow 의 미디어 포맷 타입을 GUID 로 취득한다.

구문

HRESULT get__MediaFormatType(
    GUID *MediaFormatType
    );

파라미터

MediaFormatType
[out, retval] 포맷 타입을 받는 GUID 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, C++ 로부터 마셔 이용 가능하다. 메소드명에 안다스코아가 2 개 포함되는 메소드에는, 안다스코아가 1 개 적은 동등의 메소드가 존재해, 후자에서는 파라미터에 BSTR 를 사용한다.

IComponentType::get_MediaMajorType

IComponentType 인터페이스

DirectShow 의 미디어 메이저 타입을 BSTR 로 취득한다.

구문

HRESULT get_MediaMajorType(
    BSTR* MediaMajorType
    );

파라미터

MediaMajorType
[out, retval] GUID 를 받는 BSTR 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentType::get__MediaMajorType

IComponentType 인터페이스

DirectShow 의 미디어 포맷 타입을 GUID 로 취득한다.

구문

HRESULT get__MediaMajorType(
    GUID *MediaMajorType
    );

파라미터

MediaMajorType
[out, retval] 메이저 타입을 받는 GUID 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, C++ 로부터 마셔 이용 가능하다. 메소드명에 안다스코아가 2 개 포함되는 메소드에는, 안다스코아가 1 개 적은 동등의 메소드가 존재해, 후자에서는 파라미터에 BSTR 를 사용한다.

IComponentType::get_MediaSubType

IComponentType 인터페이스

DirectShow 의 미디어 서브 타입을 BSTR 로 취득한다.

구문

HRESULT get_MediaSubType(
    BSTR* MediaSubType
    );

파라미터

MediaSubType
[out, retval] GUID 를 받는 BSTR 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentType::get__MediaSubType

IComponentType 인터페이스

DirectShow 의 미디어 서브 타입을 GUID 로 취득한다.

구문

HRESULT get__MediaSubType(
    GUID *MediaSubType
    );

파라미터

MediaSubType
[out, retval] 메이저 타입을 받는 GUID 에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, C++ 로부터 마셔 이용 가능하다. 메소드명에 안다스코아가 2 개 포함되는 메소드에는, 안다스코아가 1 개 적은 동등의 메소드가 존재해, 후자에서는 파라미터에 BSTR 를 사용한다.

IComponentType::get_MediaType

IComponentType 인터페이스

컴퍼넌트의 DirectShow AM_MEDIA_TYPE 미디어 타입 구조체를 취득한다.

구문

HRESULT get_MediaType(
    AM_MEDIA_TYPE* MediaType
    );

파라미터

MediaType
[out, retval] 현재의 ComponentType 에 관련지을 수 있었던 값이 설정되는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentType::put_Category

IComponentType 인터페이스

컴퍼넌트의 카테고리를 설정한다.

구문

HRESULT put_Category(
    ComponentCategory Category
    );

파라미터

Category
[in] 이 컴포넌트 타입의 새로운 카테고리를 지정하는 ComponentCategory 값.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

ComponentCategory 열거형은 bdatypes.h 에 다음과 같이 정의되고 있다.
typedef enum ComponentCategory
{
CategoryNotSet = -1,
CategoryOther = 0,
CategoryVideo = 1,
CategoryAudio = 2,
CategoryText = 3,
CategoryData = 4,
} ComponentCategory;

IComponentType::put_MediaFormatType

IComponentType 인터페이스

DirectShow 의 미디어 포맷 타입을 설정한다.

구문

HRESULT put_MediaFormatType(
    BSTR MediaFormatType
    );

파라미터

MediaFormatType
[in] GUID 를 지정하는 BSTR.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentType::put__MediaFormatType

IComponentType 인터페이스

DirectShow 의 미디어 포맷 타입을 설정한다.

구문

HRESULT put__MediaFormatType(
    REFCLSID MediaFormatType
    );

파라미터

MediaFormatType
[in] 미디어 포맷 타입을 지정하는 REFCLSID.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, C++ 로부터 마셔 이용 가능하다. 메소드명에 안다스코아가 2 개 포함되는 메소드에는, 안다스코아가 1 개 적은 동등의 메소드가 존재해, 후자에서는 파라미터에 BSTR 를 사용한다.

IComponentType::put_MediaMajorType

IComponentType 인터페이스

DirectShow 의 미디어 메이저 타입을 설정한다.

구문

HRESULT put_MediaMajorType(
    BSTR MediaMajorType
    );

파라미터

MediaMajorType
[in] GUID 를 지정하는 BSTR.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentType::put__MediaMajorType

IComponentType 인터페이스

DirectShow 의 미디어 메이저 타입을 설정한다.

구문

HRESULT put__MediaMajorType(
    REFCLSID MediaMajorType
    );

파라미터

MediaMajorType
[in] 미디어 메이저 타입을 지정하는 REFCLSID.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, C++ 로부터 마셔 이용 가능하다. 메소드명에 안다스코아가 2 개 포함되는 메소드에는, 안다스코아가 1 개 적은 동등의 메소드가 존재해, 후자에서는 파라미터에 BSTR 를 사용한다.

IComponentType::put_MediaSubType

IComponentType 인터페이스

DirectShow 의 미디어 서브 타입을 설정한다.

구문

HRESULT put_MediaSubType(
    BSTR MediaSubType
    );

파라미터

MediaSubType
[in] GUID 를 지정하는 BSTR.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentType::put__MediaSubType

IComponentType 인터페이스

DirectShow 의 미디어 서브 타입을 설정한다.

구문

HRESULT put__MediaSubType(
    REFCLSID MediaSubType
    );

파라미터

MediaSubType
[in] 미디어 서브 타입을 지정하는 REFCLSID.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, C++ 로부터 마셔 이용 가능하다. 메소드명에 안다스코아가 2 개 포함되는 메소드에는, 안다스코아가 1 개 적은 동등의 메소드가 존재해, 후자에서는 파라미터에 BSTR 를 사용한다.

IComponentType::put_MediaType

IComponentType 인터페이스

컴퍼넌트의 DirectShow AM_MEDIA_TYPE 미디어 타입 구조체를 설정한다.

구문

HRESULT put_MediaType(
    AM_MEDIA_TYPE MediaType
    );

파라미터

미디어 타입
[in] 메이저 타입, 서브 타입, 포맷등을 지정하는 AM_MEDIA_TYPE 구조체.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IComponentTypes 인터페이스

ComponentTypes 오브젝트를 사용 하면, 어플리케이션으로부터 개개의 ComponentType 오브젝트를 열거, 추가, 삭제, 및 취득할 수 있다. 모든 ComponentTypes 오브젝트는, IPersistPropertyBag 도 지원 한다.

메소드명 | 설명
get_Count | 콜렉션에 포함되는 ComponentType 의 수를 돌려준다.
get__NewEnum | Automation 클라이언트의 For...Each 루프를 지원하기 위한 열거 메소드.
EnumComponentTypes | 콜렉션에 포함되는 컴포넌트 타입을 모두 열거하는 IEnumComponentTypes 열거자를 돌려준다.
get_Item | 지정된 인덱스 위치의 IComponentType 인터페이스 포인터를 취득한다.
put_Item | 지정된 인덱스 위치의 ComponentType 오브젝트를, 새로운 ComponentType 오브젝트에 옮겨놓는다.
Add | 콜렉션에 새로운 ComponentType 오브젝트를 추가한다.
Remove | 지정된 인덱스 위치의 ComponentType 오브젝트를 삭제한다.
Clone | 콜렉션의 새로운 카피를 생성 한다.

IComponentTypes::Clone

IComponentTypes 인터페이스

콜렉션의 새로운 카피를 생성 한다.

구문

HRESULT Clone(
    IComponentTypes** NewList
    );

파라미터

NewList
[out, retval] 새로운 ComponentTypes 오브젝트에 세트 되는 IComponentTypes 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentTypes::get_Count

IComponentTypes 인터페이스

콜렉션에 포함되는 ComponentType 의 수를 돌려준다.

구문

HRESULT get_Count(
long* Count
    );

파라미터

Count
[out, retval] 콜렉션에 포함되는 항목의 수를 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentTypes::get__NewEnum

IComponentTypes 인터페이스

Automation 클라이언트의 For...Each 루프를 지원하기 위한 열거 메소드.

구문

HRESULT get__NewEnum(
IEnumVARIANT** ppNewEnum
    );

파라미터

ppNewEnum
[out, retval] 새로운 콜렉션을 받는 IEnumVARIANT 오브젝트에의 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, For...Each 루프의 반복에 의해 콜렉션 전체를 처리하기 위해(때문에), 스크립트 어플리케이션 및 VB 어플리케이션용으로 제공된다. C++ 어플리케이션에서는 EnumComponents 메소드를 사용하는 것.

IComponentTypes::EnumComponentTypes

IComponentTypes 인터페이스

콜렉션에 포함되는 컴포넌트 타입을 모두 열거하는 IEnumComponentTypes 열거자를 돌려준다.

구문

HRESULT EnumComponentTypes(
    IEnumComponentTypes** ppNewEnum
    );

파라미터

ppNewEnum
[out, retval] 새로운 콜렉션을 받는 IEnumComponentTypes 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentTypes::get_Item

IComponentTypes 인터페이스

지정된 인덱스 위치의 IComponentType 인터페이스 포인터를 취득한다.

구문

HRESULT get_Item(
VARIANT Index,
    IComponentType** ppComponentType
    );

파라미터

Index
[in] 취득하는 오브젝트의 인덱스 번호.
ppComponentType
[out, retval] 지정된 인덱스 위치의 오브젝트로 설정하는 IComponentType 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentTypes::put_Item

IComponentTypes 인터페이스

지정된 인덱스 위치의 ComponentType 오브젝트를, 새로운 ComponentType 오브젝트에 옮겨놓는다.

구문

HRESULT put_Item(
VARIANT Index,
    IComponentType* ComponentType
    );

파라미터

Index
[in] 옮겨놓는 항목의 인덱스 번호.
ComponentType
[in] 콜렉션에 삽입하는 IComponentType 오브젝트에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentTypes::Add

IComponentTypes 인터페이스

콜렉션에 새로운 ComponentType 오브젝트를 추가한다.

구문

HRESULT Add(
    IComponentType* ComponentType,
VARIANT* NewIndex
    );

파라미터

ComponentType
[in] 콜렉션에 추가하는 IComponentType 오브젝트에의 포인터.
NewIndex
[out, retval] 콜렉션에 추가된 ComponentType 의 인덱스 번호.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IComponentTypes::Remove

IComponentTypes 인터페이스

지정된 인덱스 위치의 ComponentType 오브젝트를 삭제한다.

구문

HRESULT Remove(
VARIANT Index
    );

파라미터

Index
[in] 삭제하는 항목의 인덱스.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IDVBSLocator 인터페이스

이 인터페이스는, DVBSLocator 오브젝트에 이행 되어 튜너가 DVBS 트랜스폴트 스트림을 취득 위해(때문에) 필요한 정보를 제공한다.

ILocator 메소드명 | 설명
Clone | locator의 카피를 생성 한다.
get_CarrierFrequency | RF 신호의 주파수를 취득한다.
get_InnerFEC | 사용하는 내부 전방 잘못 정정의 타입을 취득한다.
get_InnerFECRate | 내부 FEC 레이트를 취득한다.
get_Modulation | 변조 타입을 취득한다.
get_OuterFEC | 사용하는 외부 전방 잘못 정정의 타입을 취득한다.
get_OuterFECRate | 외부 FEC 레이트를 설정한다.
get_SymbolRate | QPSK 심볼 레이트를 취득한다.
put_CarrierFrequency | RF 신호의 주파수를 설정한다.
put_InnerFEC | 사용하는 내부 전방 잘못 정정의 타입을 설정한다.
put_InnerFECRate | 내부 FEC 레이트를 설정한다.
put_Modulation | 변조 타입을 설정한다.
put_OuterFEC | 사용하는 외부 전방 잘못 정정의 타입을 설정한다.
put_OuterFECRate | 외부 FEC 레이트를 설정한다.
put_SymbolRate | QPSK 심볼 레이트를 설정한다.
IDVBSLocator 메소드명 | 설명
get_Azimuth | 위성 안테나의 배치에 사용하는 (분)편 위각 설정을 취득한다.
get_Elevation | 위성의 앙각 (1/10о단위)을 취득한다.
get_OrbitalPosition | 위성의 궤도 위치 설정을 취득한다.
get_SignalPolarisation | 신호의 포라리제이션을 취득한다.
get_WestPosition | 궤도 위치를 서경과 동경의 어디에서 표현하는지를 나타내는 값을 취득한다.
put_Azimuth | 위성 안테나의 배치에 사용하는 (분)편 위각 설정을 조정한다.
put_Elevation | 위성의 앙각 (1/10о단위)을 설정한다.
put_OrbitalPosition | 위성의 궤도 위치 설정을 설정한다.
put_SignalPolarisation | 신호의 포라리제이션을 설정한다.
put_WestPosition | 경도를 서경 또는 동경으로 설정한다.

IDVBSLocator::get_Azimuth

IDVBSLocator 인터페이스

위성 안테나의 배치에 사용하는 (분)편 위각 설정을 취득한다.

구문

HRESULT get_Azimuth(
    short* Azimuth
    );

파라미터

Azimuth
[out, retval] 방위각 (1/10о단위)을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBSLocator::get_Elevation

IDVBSLocator 인터페이스

위성의 앙각 (1/10о단위)을 취득한다.

구문

HRESULT get_Elevation(
    short* Elevation
    );

파라미터

Elevation
[out, retval] 앙각 설정 (1/10о단위)을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBSLocator::get_OrbitalPosition

IDVBSLocator 인터페이스

위성의 궤도 위치 설정을 취득한다.

구문

HRESULT get_OrbitalPosition(
    short* longitude
    );

파라미터

longitude
[out, retval] 경도 설정 (1/10о단위)을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBSLocator::get_SignalPolarisation

IDVBSLocator 인터페이스

신호의 포라리제이션을 취득한다.

구문

HRESULT get_SignalPolarisation(
    Polarisation* PolarisationVal
    );

파라미터

PolarisationVal
[out, retval] 포라리제이션값을 받는 Polarisation 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.
Polarisation 열거형은 bdatypes.h 에 다음과 같이 정의되고 있다.
    typedef enum {
        BDA_POLARISATION_NOT_SET = -1,
        BDA_POLARISATION_NOT_DEFINED = 0,
        BDA_POLARISATION_LINEAR_H = 1,
        BDA_POLARISATION_LINEAR_V = 2,
        BDA_POLARISATION_CIRCULAR_L = 3,
        BDA_POLARISATION_CIRCULAR_R = 4,
        BDA_POLARISATION_MAX = 5
    } Polarisation;

IDVBSLocator::get_WestPosition

IDVBSLocator 인터페이스

궤도 위치를 서경과 동경의 어디에서 표현하는지를 나타내는 값을 취득한다.

구문

HRESULT get_WestPosition(
    VARIANT_BOOL* WestLongitude
    );

파라미터

WestLongitude
[out, retval] VARIANT_BOOL 형 변수에의 포인터. 진정한 값은 "서경 " 를 나타낸다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBSLocator::put_Azimuth

IDVBSLocator 인터페이스

위성 안테나의 배치에 사용하는 (분)편 위각 설정을 조정한다.

구문

HRESULT put_Azimuth(
    short Azimuth
    );

파라미터

Azimuth
[in] 방위각 (1/10о단위)을 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBSLocator::put_Elevation

IDVBSLocator 인터페이스

위성의 앙각 (1/10о단위)을 설정한다.

구문

HRESULT put_Elevation(
    short Elevation
    );

파라미터

longitude
[in] locator를 위해서(때문에) 위성의 앙각 (1/10о단위)을 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBSLocator::put_OrbitalPosition

IDVBSLocator 인터페이스

위성의 궤도 위치 설정을 설정한다.

구문

HRESULT put_OrbitalPosition(
    short longitude
    );

파라미터

longitude
[in] 위성의 경도 (1/10о단위)를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBSLocator::put_SignalPolarisation

IDVBSLocator 인터페이스

신호의 포라리제이션을 설정한다.

구문

HRESULT put_SignalPolarisation(
    Polarisation PolarisationVal
    );

파라미터

PolarisationVal
[in] 포라리제이션값을 지정하는 Polarisation 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

Polarisation 열거형은 bdatypes.h 에 다음과 같이 정의되고 있다.
    typedef enum {
        BDA_POLARISATION_NOT_SET = -1,
        BDA_POLARISATION_NOT_DEFINED = 0,
        BDA_POLARISATION_LINEAR_H = 1,
        BDA_POLARISATION_LINEAR_V = 2,
        BDA_POLARISATION_CIRCULAR_L = 3,
        BDA_POLARISATION_CIRCULAR_R = 4,
        BDA_POLARISATION_MAX = 5
    } Polarisation;

IDVBSLocator::put_WestPosition

IDVBSLocator 인터페이스

경도를 서경 또는 동경으로 설정한다.

구문

HRESULT put_WestPosition(
    VARIANT_BOOL WestLongitude
    );

파라미터

WestLongitude
[in] 지금부터 경도를 서경과 동경의 어디에서 표현하는지를 지정하는 VARIANT_BOOL 형 변수. 진정한 값은 "서경 " 를 나타낸다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IDVBTLocator 인터페이스

이 인터페이스는, DVBTLocator 오브젝트에 이행 되어 튜너가 DVBT 트랜스폴트 스트림을 취득하기 위해서 필요한 정보를 제공한다. 데이터형은 bdatypes.h 에 정의되고 있다. (Microsoft® DirectX® 8 SDK 에 동고 되는 버젼의 Broadcast Architecture 에서는, DVB-T 가 지원 되지 않는다)

ILocator 메소드명 | 설명
Clone | locator의 카피를 생성 한다.
get_CarrierFrequency | RF 신호의 주파수를 취득한다.
get_InnerFEC | 사용하는 내부 전방 잘못 정정의 타입을 취득한다.
get_InnerFECRate | 내부 FEC 레이트를 취득한다.
get_Modulation | 변조 타입을 취득한다.
get_OuterFEC | 사용하는 외부 전방 잘못 정정의 타입을 취득한다.
get_OuterFECRate | 외부 FEC 레이트를 설정한다.
get_SymbolRate | QPSK 심볼 레이트를 취득한다.
put_CarrierFrequency | RF 신호의 주파수를 설정한다.
put_InnerFEC | 사용하는 내부 전방 잘못 정정의 타입을 설정한다.
put_InnerFECRate | 내부 FEC 레이트를 설정한다.
put_Modulation | 변조 타입을 설정한다.
put_OuterFEC | 사용하는 외부 전방 잘못 정정의 타입을 설정한다.
put_OuterFECRate | 외부 FEC 레이트를 설정한다.
put_SymbolRate | QPSK 심볼 레이트를 설정한다.
IDVBTLocator 메소드명 | 설명
get_Bandwidth | 주파수의 대역폭 (MHz)을 취득한다. 보통은 7 또는 8.
get_Guard | 가이드 간격을 취득한다.
get_HAlpha | 계층장 알파를 취득한다.
get_LPInnerFEC | 우선도가 낮은 스트림의 내부 FEC 타입을 취득한다.
get_LPInnerFECRate | 우선도가 낮은 스트림의 내부 FEC 레이트를 취득한다.
get_Mode | 전송 모드를 취득한다.
get_OtherFrequencyInUse | 그 주파수가 다른 DVB-T 브로드 캐스터로 사용되고 있는지 어떤지를 조사한다.
put_Bandwidth | 주파수의 대역폭 (MHz)을 설정한다. 보통은 7 또는 8.
put_Guard | 가이드 간격을 설정한다.
put_HAlpha | 계층장 알파를 설정한다.
put_LPInnerFEC | 우선도가 낮은 스트림의 내부 FEC 타입을 설정한다.
put_LPInnerFECRate | 우선도가 낮은 스트림의 내부 FEC 레이트를 설정한다.
put_Mode | 전송 모드 설정한다.
put_OtherFrequencyInUse | 그 주파수가 다른 DVB-T 브로드 캐스터로 사용되고 있는지 어떤지를 지정한다.

IDVBTLocator::get_Bandwidth

IDVBTLocator 인터페이스

주파수의 대역폭 (MHz)을 취득한다. 보통은 7 또는 8.

구문

HRESULT get_Bandwidth(
    long* BandWidthVal
    );

파라미터

BandWidthVal
[out, retval] 대역폭의 값을 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTLocator::get_Guard

IDVBTLocator 인터페이스

가이드 간격을 취득한다.

구문

HRESULT get_Guard(
    GuardInterval* GI
    );

파라미터

GI
[out, retval] 유효한 GuardInterval 값을 받는 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

typedef enum GuardInterval {
    BDA_GUARD_NOT_SET = -1,
    BDA_GUARD_NOT_DEFINED = 0,
    BDA_GUARD_1_32 = 1, // 가이드 간격은 1/32
    BDA_GUARD_1_16, // 가이드 간격은 1/16
    BDA_GUARD_1_8, // 가이드 간격은 1/8
    BDA_GUARD_1_4, // 가이드 간격은 1/4
    BDA_GUARD_MAX,
} GuardInterval;

IDVBTLocator::get_HAlpha

IDVBTLocator 인터페이스

계층장 알파를 취득한다.

구문

HRESULT get_HAlpha(
    HierarchyAlpha* Alpha
    );

파라미터

Alpha
[out, retval] HierarchyAlpha 열거형에 속하는 값.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

typedef enum HierarchyAlpha {
BDA_HALPHA_NOT_SET = -1,
BDA_HALPHA_NOT_DEFINED = 0,
BDA_HALPHA_1 = 1, // 계층장 알파는 1.
BDA_HALPHA_2, // 계층장 알파는 2.
BDA_HALPHA_4, // 계층장 알파는 4.
BDA_HALPHA_MAX,
} HierarchyAlpha;

IDVBTLocator::get_LPInnerFEC

IDVBTLocator 인터페이스

우선도가 낮은 스트림의 내부 FEC 타입을 취득한다.

구문

HRESULT get_LPInnerFEC(
FECMethod* FEC
    );

파라미터

FEC
[out, retval] FEC 타입을 받는 FECMethod 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTLocator::get_LPInnerFECRate

IDVBTLocator 인터페이스

우선도가 낮은 스트림의 내부 FEC 레이트를 취득한다.

구문

HRESULT get_LPInnerFECRate(
BinaryConvolutionCodeRate* FEC
    );

파라미터

FEC
[out, retval] 내부 FEC 레이트를 받는 BinaryConvolutionCodeRate 값에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

BinaryConvolutionCodeRate 는 bdatypes.h 에 다음과 같이 정의되고 있다.

typedef enum {
BDA_BCC_RATE_NOT_SET = -1,
BDA_BCC_RATE_NOT_DEFINED = 0,
BDA_BCC_RATE_1_2 = 1,
BDA_BCC_RATE_2_3 = 2,
BDA_BCC_RATE_3_4 = 3,
BDA_BCC_RATE_3_5 = 4,
BDA_BCC_RATE_4_5 = 5,
BDA_BCC_RATE_5_6 = 6,
BDA_BCC_RATE_5_11 = 7,
BDA_BCC_RATE_7_8 = 8,
BDA_BCC_RATE_MAX = 9
} BinaryConvolutionCodeRate;

IDVBTLocator::get_Mode

IDVBTLocator 인터페이스

전송 모드를 취득한다.

구문

HRESULT get_Mode(
    TransmissionMode* mode
    );

파라미터

mode
[out, retval] TransmissionMode 열거형에 속하는 값.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

typedef enum TransmissionMode {
    BDA_XMIT_MODE_NOT_SET = -1,
    BDA_XMIT_MODE_NOT_DEFINED = 0,
    BDA_XMIT_MODE_2K = 1, // 전송에 1705 캐리어를 사용한다 (2K FFT 를 사용)
    BDA_XMIT_MODE_8K, // 전송에 6817 캐리어를 사용한다 (8K FFT 를 사용)
    BDA_XMIT_MODE_MAX,
} TransmissionMode;

IDVBTLocator::get_OtherFrequencyInUse

IDVBTLocator 인터페이스

그 주파수가 다른 DVB-T 브로드 캐스터로 사용되고 있는지 어떤지를 조사한다.

구문

HRESULT get_OtherFrequencyInUse(
    VARIANT_BOOL* OtherFrequencyInUseVal
    );

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTLocator::put_Bandwidth

IDVBTLocator 인터페이스

주파수의 대역폭 (MHz)을 설정한다. 보통은 7 또는 8.

구문

HRESULT put_Bandwidth(
    long BandwidthVal
    );

파라미터

BandwidthVal
[in] 대역폭을 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTLocator::put_Guard

IDVBTLocator 인터페이스

가이드 간격을 설정한다.

구문

HRESULT put_Guard(
    GuardInterval GI
    );

파라미터

GI
[in] 가이드 간격을 지정하는 GuardInterval 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTLocator::put_HAlpha

IDVBTLocator 인터페이스

계층장 알파를 설정한다.

구문

HRESULT put_HAlpha(
    HierarchyAlpha Alpha
    );

파라미터

Alpha
[in] 계층장 알파를 지정하는 HierarchyAlpha 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

typedef enum HierarchyAlpha {
BDA_HALPHA_NOT_SET = -1,
BDA_HALPHA_NOT_DEFINED = 0,
BDA_HALPHA_1 = 1, // 계층장 알파는 1.
BDA_HALPHA_2, // 계층장 알파는 2.
BDA_HALPHA_4, // 계층장 알파는 4.
BDA_HALPHA_MAX,
} HierarchyAlpha;

IDVBTLocator::put_LPInnerFEC

IDVBTLocator 인터페이스

우선도가 낮은 스트림의 내부 FEC 타입을 설정한다.

구문

HRESULT put_LPInnerFEC(
FECMethod FEC
    );

파라미터

FEC
[in] FEC 타입을 지정하는 FECMethod 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTLocator::put_LPInnerFECRate

IDVBTLocator 인터페이스

우선도가 낮은 스트림의 내부 FEC 레이트를 설정한다.

구문

HRESULT put_LPInnerFECRate(
BinaryConvolutionCodeRate FEC
    );

파라미터

FEC
[in] 레이트를 지정하는 BinaryConvolutionCodeRate 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTLocator::put_Mode

IDVBTLocator 인터페이스

전송 모드 설정한다.

구문

HRESULT put_Mode(
    TransmissionMode mode
    );

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTLocator::put_OtherFrequencyInUse

IDVBTLocator 인터페이스

그 주파수가 다른 DVB-T 브로드 캐스터로 사용되고 있는지 어떤지를 지정한다.

구문

HRESULT put_OtherFrequencyInUse(
    VARIANT_BOOL OtherFrequencyInUseVal
    );

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IDVBTuneRequest 인터페이스

이 인터페이스는, DVBTuneRequest 오브젝트에 이행 된다.

ITuneRequest 메소드명 | 설명
get_TuningSpace | 튜닝 공간 오브젝트를 취득한다.
get_Components | IComponent 오브젝트의 콜렉션을 취득한다.
Clone | 이 튜닝 요구의 새로운 카피를 돌려준다.
get_Locator | 네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 취득한다.
put_Locator | 네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 설정한다.
IDVBTuneRequest 메소드명 | 설명
get_ONID | 원의 네트워크 ID 를 취득한다.
get_SID | 서비스 ID 를 설정한다.
get_TSID | 트랜스폴트 스트림 ID 를 취득한다.
put_ONID | 원의 네트워크 ID 를 설정한다.
put_SID | 서비스 ID 를 취득한다.
put_TSID | 트랜스폴트 스트림 ID 를 설정한다.

IDVBTuneRequest::get_ONID

IDVBTuneRequest 인터페이스

원의 네트워크 ID 를 취득한다.

구문

HRESULT get_ONID(
    short* ONID
    );

파라미터

ONID
[out, retval] 원의 네트워크 ID 를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTuneRequest::get_SID

IDVBTuneRequest 인터페이스

네트워크의 서비스 ID 를 취득한다.

구문

HRESULT get_SID(
    short* SID
    );

파라미터

SID
[out, retval] 서비스 ID 를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTuneRequest::get_TSID

IDVBTuneRequest 인터페이스

트랜스폴트 스트림 ID 를 취득한다.

구문

HRESULT get_TSID(
short* TSID
    );

파라미터

TSID
[out, retval] 트랜스폴트 스트림 ID 를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTuneRequest::put_ONID

IDVBTuneRequest 인터페이스

원의 네트워크 ID 를 설정한다.

구문

HRESULT put_ONID(
    short ONID
    );

파라미터

ONID
[in] 원의 네트워크 ID 를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTuneRequest::put_SID

IDVBTuneRequest 인터페이스

서비스 ID 를 설정한다.

구문

HRESULT put_SID(
    short SID
    );

파라미터

SID
[in] 서비스 ID 를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IDVBTuneRequest::put_TSID

IDVBTuneRequest 인터페이스

트랜스폴트 스트림 ID 를 설정한다.

구문

HRESULT put_TSID(
short TSID
    );

파라미터

TSID
[in] 트랜스폴트 스트림 ID 를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IDVBTuningSpace 인터페이스

이 인터페이스는, DVBTuningSpace 오브젝트에 이행 된다.

메소드명 | 설명
ITuningSpace 메소드
get_UniqueName | 튜닝 공간의 고유의 명칭을 취득한다. 고유의 명칭은 약칭이나 GUID 이다.
put_UniqueName | 튜닝 공간의 고유의 명칭을 설정한다. 고유의 명칭은 약칭이나 GUID 이다.
get_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 취득한다.
put_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 설정한다.
get_CLSID | 튜닝 공간의 CLSID 를 BSTR 로서 취득한다.
get_NetworkType | 튜닝 공간의 네트워크 타입 GUID 를 BSTR 로서 취득한다.
put_NetworkType | 이 튜닝 공간의 네트워크 타입을 BSTR 로서 설정한다.
get__NetworkType | 튜닝 공간의 네트워크 타입을 GUID 로서 취득한다.
put__NetworkType | 이 튜닝 공간의 네트워크 타입을 REFCLSID 로서 설정한다.
CreateTuneRequest | 하늘의 (초기화되어 있지 않다) 튜닝 요구를 나타내는 COM 오브젝트를 생성 한다.
EnumCategoryGUIDs | (현시점에서는 미이행) DirectShow 카테고리 GUID 를 열거하는 열거자를 생성 한다. 카테고리 GUID 는, 튜닝 공간을 지원 하는 필터의 종류를 나타내는 것이다.
EnumDeviceMonikers | (현시점에서는 미이행) 이 튜닝 공간을 지원 하는 튜너 입력 (필터)을 나타내는 데바이스모니카의 열거자를 생성 한다.
get_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 돌려준다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
put_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 생성 한다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
get_FrequencyMapping | 네트워크 프로바이더가 put_FrequencyMapping 를 호출해 직전에 생성 한 주파수 매핑을 취득한다.
put_FrequencyMapping | 주파수와 채널의 매핑, 주파수와 중계기의 매핑, 또는 캐리어 주파수로부터 주파수 식별자에의, 튜닝 공간에 적절한 그 외의 모든 매핑을 생성 한다.
get_DefaultLocator | 로컬 시스템의 디폴트 locator를 취득한다.
put_DefaultLocator | 로컬 시스템의 디폴트 locator를 설정한다.
IDVBTuningSpace 메소드
get_SystemType | DVB 의 시스템 타입을 취득한다.
put_SystemType | DVB 의 시스템 타입을 설정한다.

IDVBTuningSpace::get_SystemType

IDVBTuningSpace 인터페이스

시스템 타입을 취득한다.

구문

HRESULT get_SystemType(
    DVBSystemType* SysType
    );

파라미터

SysType
[out, retval] 시스템 타입을 받는 DVDSystemType 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

typedef enum DVBSystemType {
DVB_Cable,
DVB_Terrestrial,
DVB_Satellite,
} DVBSystemType;

IDVBTuningSpace::put_SystemType

IDVBTuningSpace 인터페이스

시스템 타입을 설정한다.

구문

HRESULT put_SystemType(
    DVBSystemType SysType
    );

파라미터

SysType
[in] 시스템 타입을 지정하는 DVDSystemType 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

typedef enum DVBSystemType {
DVB_Cable,
DVB_Terrestrial,
DVB_Satellite,
} DVBSystemType;


IEnumComponents 인터페이스

IEnumComponents 인터페이스는, 소정의 프로그램 스트림에 포함되는 컴퍼넌트 (서브 스트림)에 대응하는 표준 COM 열거 오브젝트를 제공한다. C++ 어플리케이션으로부터 특정의 프로그램 스트림에 포함되는 Component 오브젝트를 열거하려면 , IComponents 는 아니고, 이 인터페이스를 사용하는 것.

메소드명 | 설명
Next | 콜렉션의 다음으로부터 시작되는 n 개의 요소를 취득한다.
Skip | 콜렉션에 포함되는 지정된 요소를 스킵 한다 (취득하지 않는다).
Reset | 열거자를 콜렉션 선두에 되돌린다.
Clone | 콜렉션 전체의 새로운 카피를 생성 한다.

IEnumComponents::Next

IEnumComponents 인터페이스

콜렉션의 다음으로부터 시작되는 n 개의 요소를 취득한다.

구문

HRESULT Next(
ULONG celt,
    IComponent** rgelt,
ULONG* pceltFetched
    );

파라미터

celt
[in] 취득하는 요소수를 지정하는 ULONG 형 변수.
rgelt
[out, size_is(celt), length_is(*pceltFetched)] 취득한 Component 오브젝트를 받는 IComponent 인터페이스 포인터 배열의 주소.
pceltFetched
[out] 실제로 취득한 요소수를 받는 ULONG 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumComponents::Skip

IEnumComponents 인터페이스

콜렉션에 포함되는 지정된 요소를 스킵 한다 (취득하지 않는다).

구문

HRESULT Skip(
ULONG celt
    );

파라미터

celt
[in] 스킵 하는 요소를 지정하는 ULONG 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumComponents::Reset

IEnumComponents 인터페이스

열거자를 콜렉션 선두에 되돌린다.

구문

HRESULT Reset();

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumComponents::Clone

IEnumComponents 인터페이스

콜렉션 전체의 새로운 카피를 생성 한다.

구문

HRESULT Clone(
    IEnumComponents** ppEnum
    );

파라미터

ppEnum
[out] 새로운 콜렉션으로 설정하는 IEnumComponents 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

새로운 콜렉션은, 사용후에 어플리케이션측에서 해방할 필요가 있다.


IEnumComponentTypes 인터페이스

이 인터페이스는, 소정의 브로드캐스트 스트림에 관련지을 수 있었던 ComponentType 오브젝트의 표준 COM 콜렉션에 이행 되어 IComponentTypes::EnumComponentTypes 의 호출을 통해서 돌려주어진다.

메소드명 | 설명
Clone | 콜렉션 전체와 그 서브 오브젝트 모든 새로운 카피를 생성 한다.
Next | 콜렉션의 다음으로부터 시작되는 n 개의 요소를 취득한다.
Reset | 반복자를 콜렉션 선두에 되돌린다.
Skip | 지정된 인덱스 위치의 요소를 스킵 한다.

IEnumComponentTypes::Clone

IEnumComponentTypes 인터페이스

콜렉션과 그 서브 오브젝트 모든 새로운 카피를 생성 한다.

구문

HRESULT Clone(
    IEnumComponentTypes** ppEnum
    );

파라미터

ppEnum
[out] 돌려주어지는 콜렉션 오브젝트로 설정하는 IEnumComponentTypes 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumComponentTypes::Next

IEnumComponentTypes 인터페이스

콜렉션의 다음으로부터 시작되는 n 개의 요소를 취득한다.

구문

HRESULT Next(
ULONG celt,
    IComponentType** rgelt,
ULONG* pceltFetched
    );

파라미터

celt
[in] 취득하는 요소수.
rgelt
[out, size_is(celt), length_is(*pceltFetched)] 돌려주어진 ComponentType 오브젝트를 받는 IComponentType 인터페이스 포인터 배열의 주소.
pceltFetched
[out] 실제로 취득한 요소수를 받는 ULONG 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumComponentTypes::Reset

IEnumComponentTypes 인터페이스

반복자를 콜렉션 선두에 되돌린다.

구문

HRESULT Reset();

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumComponentTypes::Skip

IEnumComponentTypes 인터페이스

지정된 인덱스 위치의 요소를 스킵 한다.

구문

HRESULT Skip(
ULONG celt
    );

파라미터

celt
[in] 스킵 하는 요소의 인덱스.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IEnumTuningSpaces 인터페이스

이 인터페이스는, 로컬 시스템 위에의 튜닝 공간 오브젝트의 표준 COM 콜렉션에 이행 되어 ITuningSpaceContainer::EnumTuningSpaces 의 호출을 통해서 돌려주어진다.

메소드명 | 설명
Next | 콜렉션의 다음으로부터 시작되는 n 개의 요소를 취득한다.
Skip | 콜렉션에 포함되는 지정된 요소를 스킵 한다.
Reset | 반복자를 콜렉션 선두에 되돌린다.
Clone | 콜렉션과 그 서브 오브젝트 모든 새로운 카피를 생성 한다.

IEnumTuningSpaces::Next

IEnumTuningSpaces 인터페이스

콜렉션의 다음으로부터 시작되는 n 개의 요소를 취득한다.

구문

HRESULT Next(
ULONG celt,
    ITuningSpace** rgelt,
ULONG* pceltFetched
    );

파라미터

celt
[in] 취득하는 요소수.
rgelt
[out, size_is(celt), length_is(*pceltFetched)] 취득한 튜닝 공간 오브젝트를 받는 ITuningSpace 인터페이스 포인터 배열의 주소.
pceltFetched
[out] 실제로 취득한 요소수를 받는 ULONG 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 이 메소드는,celt 가 0 에서도 성공한다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumTuningSpaces::Skip

IEnumTuningSpaces 인터페이스

콜렉션에 포함되는 지정된 요소를 스킵 한다.

구문

HRESULT Skip(
ULONG celt
    );

파라미터

celt
[in] 스킵 하는 요소의 인덱스.

반환값

성공했을 경우는, S_OK 를 돌려준다. 이 메소드는,celt 가 0 에서도 성공한다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumTuningSpaces::Reset

IEnumTuningSpaces 인터페이스

반복자를 콜렉션 선두에 되돌린다.

구문

HRESULT Reset();

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumTuningSpaces::Clone

IEnumTuningSpaces 인터페이스

콜렉션과 그 서브 오브젝트 모든 새로운 카피를 생성 한다.

구문

HRESULT Clone(
IEnumTuningSpaces** ppEnum
    );

파라미터

ppEnum
[out] 돌려주어진 인터페이스를 받는 IEnumTuningSpaces 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


ILocator 인터페이스

ILocator base class 인터페이스는, 튜닝 공간에 관한 정보가 저장 된 locator 오브젝트에, 그 파생 인터페이스 (IATSCLocator 등)를 통해서 이행 된다. locator 오브젝트는, 보통, 튜너에 의한 트랜스폴트 스트림의 검색 및 취득을 돕기 위해, 네트워크 프로바이더가 사용한다. 디버그를 목적으로 하는 경우를 제외해, 어플리케이션으로 locator 오브젝트를 사용할 것은 없다. 모든 locator 오브젝트는, IPersistPropertyBag 도 지원 한다.

메소드명 | 설명
Clone | locator의 카피를 생성 한다.
get_CarrierFrequency | RF 신호의 주파수를 취득한다.
get_InnerFEC | 사용하는 내부 전방 잘못 정정의 타입을 취득한다.
get_InnerFECRate | 내부 FEC 레이트를 취득한다.
get_Modulation | 변조 타입을 취득한다.
get_OuterFEC | 사용하는 외부 전방 잘못 정정의 타입을 취득한다.
get_OuterFECRate | 외부 FEC 레이트를 설정한다.
SymbolRate | QPSK 심볼 레이트를 취득한다.
put_CarrierFrequency | RF 신호의 주파수를 설정한다.
put_InnerFEC | 사용하는 내부 전방 잘못 정정의 타입을 설정한다.
put_InnerFECRate | 내부 FEC 레이트를 설정한다.
put_Modulation | 변조 타입을 설정한다.
put_OuterFEC | 사용하는 외부 전방 잘못 정정의 타입을 설정한다.
put_OuterFECRate | 외부 FEC 레이트를 설정한다.
SymbolRate | QPSK 심볼 레이트를 설정한다.

ILocator::Clone

ILocator 인터페이스

locator의 카피를 생성 한다.

구문

HRESULT Clone(
    ILocator **NewLocator
    );

파라미터

NewLocator
[out, retval] 돌려주어진 인터페이스를 받는 ILocator 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ILocator::get_CarrierFrequency

ILocator 인터페이스

RF 신호의 주파수를 취득한다.

구문

HRESULT get_CarrierFrequency(
    long* Frequency
    );

파라미터

Frequency
[out, retval] 주파수의 값을 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ILocator::get_InnerFEC

ILocator 인터페이스

사용하는 전방 잘못 정정의 타입을 취득한다.

구문

HRESULT get_InnerFEC(
FECMethod* FEC
    );

파라미터

FEC
[out, retval] 내부 FEC 의 타입을 받는 FECMethod 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

FECMethod 는 bdatypes.h 에 다음과 같이 정의되고 있다.
typedef enum FECMethod {
    BDA_FEC_METHOD_NOT_SET = -1,
    BDA_FEC_METHOD_NOT_DEFINED = 0,
    BDA_FEC_VITERBI = 1,      // FEC 는 비테르비 2 진 접어 포함법.
    BDA_FEC_RS_204_188,       // FEC 는 리드-솔로몬 204/188 (외부 FEC).
    BDA_FEC_MAX,
} FECMethod;

ILocator::get_InnerFECRate

ILocator 인터페이스

내부 FEC 레이트를 취득한다.

구문

HRESULT get_InnerFECRate(
BinaryConvolutionCodeRate* FEC
    );

파라미터

FEC
[out, retval] 내부 FEC 레이트를 받는 BinaryConvolutionCodeRate 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

BinaryConvolutionCodeRate 는 bdatypes.h 에 다음과 같이 정의되고 있다.

typedef enum {
BDA_BCC_RATE_NOT_SET = -1,
BDA_BCC_RATE_NOT_DEFINED = 0,
BDA_BCC_RATE_1_2 = 1,
BDA_BCC_RATE_2_3 = 2,
BDA_BCC_RATE_3_4 = 3,
BDA_BCC_RATE_3_5 = 4,
BDA_BCC_RATE_4_5 = 5,
BDA_BCC_RATE_5_6 = 6,
BDA_BCC_RATE_5_11 = 7,
BDA_BCC_RATE_7_8 = 8,
BDA_BCC_RATE_MAX = 9
} BinaryConvolutionCodeRate;

ILocator::get_Modulation

ILocator 인터페이스

변조 타입을 취득한다.

구문

HRESULT get_Modulation(
    ModulationType* Modulation
    );

파라미터

Modulation
[out, retval] 새로운 변조 타입을 받는 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

ModulationType 의 정의에 대해서는, 「put_Modulation 」를 참조할것.

ILocator::get_OuterFEC

ILocator 인터페이스

사용하는 외부 전방 잘못 정정의 타입을 취득한다.

구문

HRESULT get_OuterFEC(
FECMethod* FEC
    );

파라미터

FEC
[out, retval] 외부 FEC 를 받는 FECMethod 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

FECMethod 의 정의에 대해서는, 「get_InnerFEC 」를 참조할것.

ILocator::get_OuterFECRate

ILocator 인터페이스

외부 FEC 레이트를 취득한다.

구문

HRESULT get_OuterFECRate(
BinaryConvolutionCodeRate* FEC
    );

파라미터

FEC
[out, retval] 외부 FEC 레이트를 받는 BinaryConvolutionCodeRate 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ILocator::get_SymbolRate

ILocator 인터페이스

QPSK 심볼 레이트를 취득한다.

구문

HRESULT get_SymbolRate(
    long* Rate
    );

파라미터

Rate
[out, retval] QPSK 레이트를 받는 long 형 변수에의 포인터.

Return Value

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

QPSK 는 RF 신호에 심볼을 변조한다. 이러한 심볼은 원상회복기에 의해 검출되어 비트 스트림을 재구축 하는데 사용된다. OPSK 는 변경을 위해서(때문에) 변조/복조되는 레이트를 허가한다.

ILocator::put_CarrierFrequency

ILocator 인터페이스

RF 신호의 주파수를 설정한다.

구문

HRESULT put_CarrierFrequency(
    long Frequency
    );

파라미터

Frequency
[in] 주파수의 값을 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ILocator::put_InnerFEC

ILocator 인터페이스

사용하는 내부 전방 잘못 정정의 타입을 설정한다.

구문

HRESULT put_InnerFEC(
FECMethod FEC
    );

파라미터

FEC
[in] 내부 FEC 의 타입을 지정하는 FECMethod 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ILocator::put_InnerFECRate

ILocator 인터페이스

내부 FEC 레이트를 설정한다.

구문

HRESULT put_InnerFECRate(
BinaryConvolutionCodeRate FEC
    );

파라미터

FEC
[in] 내부 FEC 레이트를 지정하는 BinaryConvolutionCodeRate 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ILocator::put_Modulation

ILocator 인터페이스

변조 타입을 설정한다.

구문

HRESULT put_Modulation(
    ModulationType Modulation
    );

파라미터

Modulation
[in] 변조 타입을 지정한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

ModulationType 열거형은 bdatypes.h 에 다음과 같이 정의되고 있다.
typedef enum {
    BDA_MOD_NOT_SET = -1,
    BDA_MOD_NOT_DEFINED = 0,
    BDA_MOD_16QAM = 1,
    BDA_MOD_32QAM = 2,
    BDA_MOD_64QAM = 3,
    BDA_MOD_80QAM = 4,
    BDA_MOD_96QAM = 5,
    BDA_MOD_112QAM = 6,
    BDA_MOD_128QAM = 7,
    BDA_MOD_160QAM = 8,
    BDA_MOD_192QAM = 9,
    BDA_MOD_224QAM = 10,
    BDA_MOD_256QAM = 11,
    BDA_MOD_320QAM = 12,
    BDA_MOD_384QAM = 13,
    BDA_MOD_448QAM = 14,
    BDA_MOD_512QAM = 15,
    BDA_MOD_640QAM = 16,
    BDA_MOD_768QAM = 17,
    BDA_MOD_896QAM = 18,
    BDA_MOD_1024QAM = 19,
    BDA_MOD_QPSK = 20,
    BDA_MOD_BPSK = 21,
    BDA_MOD_OQPSK = 22,
    BDA_MOD_8VSB = 23,
    BDA_MOD_16VSB = 24,
    BDA_MOD_ANALOG_AMPLITUDE = 25,
    BDA_MOD_ANALOG_FREQUENCY = 26,
    BDA_MOD_MAX = 27
} ModulationType;

ILocator::put_OuterFEC

ILocator 인터페이스

사용하는 외부 전방 잘못 정정의 타입을 설정한다.

구문

HRESULT put_OuterFEC(
FECMethod FEC
    );

파라미터

FEC
[in] 외부 전방 잘못 정정의 타입을 지정하는 FECMethod 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ILocator::put_OuterFECRate

ILocator 인터페이스

외부 FEC 레이트를 설정한다.

구문

HRESULT put_OuterFECRate(
BinaryConvolutionCodeRate FEC
    );

파라미터

FEC
[in] 외부 FEC 레이트를 지정하는 BinaryConvolutionCodeRate 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

BinaryConvolutionCodeRate 는 bdatypes.h 에 다음과 같이 정의되고 있다.
typedef enum {
BDA_BCC_RATE_NOT_SET = -1,
BDA_BCC_RATE_NOT_DEFINED = 0,
BDA_BCC_RATE_1_2 = 1,
BDA_BCC_RATE_2_3 = 2,
BDA_BCC_RATE_3_4 = 3,
BDA_BCC_RATE_3_5 = 4,
BDA_BCC_RATE_4_5 = 5,
BDA_BCC_RATE_5_6 = 6,
BDA_BCC_RATE_5_11 = 7,
BDA_BCC_RATE_7_8 = 8,
BDA_BCC_RATE_MAX = 9
} BinaryConvolutionCodeRate;

ILocator::put_SymbolRate

ILocator 인터페이스

QPSK 심볼 레이트를 설정한다.

구문

HRESULT put_SymbolRate(
    long Rate
    );

파라미터

Rate
[in] QPSK 레이트를 지정하는 long 형 변수에의 포인터

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

QPSK 는 RF 신호에 심볼을 변조한다. 이러한 심볼은 원상회복기에 의해 검출되어 비트 스트림을 재구축 하는데 사용된다. OPSK 는 변경을 위해서(때문에) 변조/복조되는 레이트를 허가한다.


ILanguageComponentType 인터페이스

ILanguageComponentType 인터페이스는, 스트림 컨텐츠의 언어를 정의하는 LanguageComponentType 오브젝트에 이행 된다. 모든 스트림에 언어 컴퍼넌트가 있다고는 할 수 없다.

메소드명 | 설명
get_LangID | 스트림 컨텐츠의 언어를 취득한다.
put_LangID | 스트림 컨텐츠의 언어를 설정한다.

ILanguageComponentType::get_LangID

ILanguageComponentType 인터페이스

언어를 식별하는 LCID 를 취득한다.

구문

HRESULT get_LangID(
short* LangID
    );

파라미터

LangID
[out, retval] LCID 를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

LangID 는 Win32 의 LANGID 이다. IComponent base class 인터페이스에는, 설명의 언어를 정의하는 다른 언어 ID 가 있다.

ILanguageComponentType::put_LangID

ILanguageComponentType 인터페이스

언어를 식별하는 LCID 를 지정한다.

구문

HRESULT put_LangID(
short LangID
    );

파라미터

LangID
[in] LCID 를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IMPEG2Component 인터페이스

IMPEG2Component 인터페이스는, MPEG2 기본 스트림에 관한 프로퍼티를 취득 및 설정하기 위한 메소드를 제공한다.

IComponent 메소드명 | 설명
get_Type | 컴퍼넌트의 일반적인 특성을 기술하는 IComponentType 오브젝트를 취득한다.
put_Type | 컴퍼넌트의 일반적인 특성을 기술하는 IComponentType 오브젝트를 설정한다.
get_DescLangID | 설명의 프레젠테이션에 사용하는 언어를 취득한다.
put_DescLangID | 설명의 프레젠테이션에 사용하는 언어를 설정한다.
get_Status | 컴퍼넌트의 요구된 상태 또는 실제 상태를 취득한다.
put_Status | 컴퍼넌트의 요구된 상태 또는 실제 상태를 설정한다.
get_Description | 컴퍼넌트의 설명을 취득한다.
put_Description | 컴퍼넌트의 설명을 설정한다.
Clone | 컴퍼넌트의 새로운 카피를 생성 한다.
IMPEG2Component 메소드명 | 설명
get_PCRPID | 이 서브 스트림의 타임 스탬프에 대응하는 MPEG2 패킷 ID 를 돌려준다.
get_PID | 이 서브 스트림의 패킷 식별자를 취득한다.
get_ProgramNumber | PAT 의 역당겨 참조에 사용하는 프로그램 번호를 취득한다.
put_PCRPID | 이 서브 스트림의 타임 스탬프에 대응하는 MPEG2 패킷 ID 를 설정한다.
put_PID | 이 서브 스트림의 패킷 식별자를 설정한다.
put_ProgramNumber | PAT 의 역당겨 참조에 사용하는 프로그램 번호를 취득한다.

IMPEG2Component::get_PCRPID

IMPEG2Component 인터페이스

이 서브 스트림의 타임 스탬프에 대응하는 MPEG2 패킷 ID 를 돌려준다.

구문

HRESULT get_PCRPID(
    short *PCRPID
    );

파라미터

PCRPID
[out, retval] 패킷 ID 의 값을 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IMPEG2Component::get_PID

IMPEG2Component 인터페이스

이 서브 스트림의 패킷 식별자를 취득한다.

구문

HRESULT get_PID(
    short *PID
    );

파라미터

PID
[out, retval] 패킷 식별자를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IMPEG2Component::get_ProgramNumber

IMPEG2Component 인터페이스

PAT 의 역당겨 참조에 사용하는 프로그램 번호를 취득한다.

구문

HRESULT get_ProgramNumber(
    short *ProgramNumber
    );

파라미터

ProgramNumber
[out, retval] 프로그램 번호를 받는 Short 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IMPEG2Component::put_PCRPID

IMPEG2Component 인터페이스

이 서브 스트림의 타임 스탬프에 대응하는 MPEG2 패킷 ID 를 설정한다.

구문

HRESULT put_PCRPID(
    short PCRPID
    );

파라미터

PCRPID
[in] 패킷 ID 를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IMPEG2Component::put_PID

IMPEG2Component 인터페이스

이 서브 스트림의 패킷 식별자를 설정한다.

구문

HRESULT put_PID(
    short PID
    );

파라미터

PID
[in] 패킷 식별자를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IMPEG2Component::put_ProgramNumber

IMPEG2Component 인터페이스

PAT 의 역당겨 참조에 사용하는 프로그램 번호를 설정한다.

구문

HRESULT put_ProgramNumber(
    short ProgramNumber
    );

파라미터

ProgramNumber
[in] 프로그램 번호를 지정하는 Short 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IMPEG2ComponentType 인터페이스

이 인터페이스는, IComponentLanguageType 를 계승해, IMPEG2ComponentType 오브젝트에 이행 된다. 어플리케이션에서는, 이 인터페이스를 사용해 MPEG2 의 스트림 타입에 관한 정보를 설정 및 취득할 수 있다.

메소드명 | 설명
get_StreamType | 스트림 타입을 취득한다.
put_StreamType | 스트림 타입을 설정한다.

IMPEG2ComponentType::get_StreamType

IMPEG2ComponentType 인터페이스

스트림 타입을 취득한다.

구문

HRESULT get_StreamType(
    MPEG2StreamType* MP2StreamType
    );

파라미터

MP2StreamType
[out, retval] 스트림 타입의 값을 받는 MPEG2StreamType 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

typedef enum MPEG2StreamType {
        BDA_UNITIALIZED_MPEG2STREAMTYPE = -1,
    Reserved1 = 0x0,
    ISO_IEC_11172_2_VIDEO	= Reserved1 + 1,
    ISO_IEC_13818_2_VIDEO	= ISO_IEC_11172_2_VIDEO + 1,
    ISO_IEC_11172_3_AUDIO	= ISO_IEC_13818_2_VIDEO + 1,
    ISO_IEC_13818_3_AUDIO	= ISO_IEC_11172_3_AUDIO + 1,
    ISO_IEC_13818_1_PRIVATE_SECTION = ISO_IEC_13818_3_AUDIO + 1,
    ISO_IEC_13818_1_PES		= ISO_IEC_13818_1_PRIVATE_SECTION + 1,
    ISO_IEC_13522_MHEG		= ISO_IEC_13818_1_PES + 1,
    ANNEX_A_DSM_CC			= ISO_IEC_13522_MHEG + 1,
    ITU_T_REC_H_222_1		= ANNEX_A_DSM_CC + 1,
    ISO_IEC_13818_6_TYPE_A	= ITU_T_REC_H_222_1 + 1,
    ISO_IEC_13818_6_TYPE_B	= ISO_IEC_13818_6_TYPE_A + 1,
    ISO_IEC_13818_6_TYPE_C	= ISO_IEC_13818_6_TYPE_B + 1,
    ISO_IEC_13818_6_TYPE_D	= ISO_IEC_13818_6_TYPE_C + 1,
    ISO_IEC_13818_1_AUXILIARY = ISO_IEC_13818_6_TYPE_D + 1,
    ISO_IEC_13818_1_RESERVED = ISO_IEC_13818_1_AUXILIARY + 1,
    USER_PRIVATE			= ISO_IEC_13818_1_RESERVED + 1
} MPEG2StreamType;

IMPEG2ComponentType::put_StreamType

IMPEG2ComponentType 인터페이스

MPEG2 의 스트림 타입을 설정한다.

구문

HRESULT put_StreamType(
    MPEG2StreamType MP2StreamType
    );

파라미터

MP2StreamType
[in] 스트림 타입을 지정하는 MPEG2StreamType 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

typedef enum MPEG2StreamType {
        BDA_UNITIALIZED_MPEG2STREAMTYPE = -1,
    Reserved1 = 0x0,
    ISO_IEC_11172_2_VIDEO	= Reserved1 + 1,
    ISO_IEC_13818_2_VIDEO	= ISO_IEC_11172_2_VIDEO + 1,
    ISO_IEC_11172_3_AUDIO	= ISO_IEC_13818_2_VIDEO + 1,
    ISO_IEC_13818_3_AUDIO	= ISO_IEC_11172_3_AUDIO + 1,
    ISO_IEC_13818_1_PRIVATE_SECTION = ISO_IEC_13818_3_AUDIO + 1,
    ISO_IEC_13818_1_PES		= ISO_IEC_13818_1_PRIVATE_SECTION + 1,
    ISO_IEC_13522_MHEG		= ISO_IEC_13818_1_PES + 1,
    ANNEX_A_DSM_CC			= ISO_IEC_13522_MHEG + 1,
    ITU_T_REC_H_222_1		= ANNEX_A_DSM_CC + 1,
    ISO_IEC_13818_6_TYPE_A	= ITU_T_REC_H_222_1 + 1,
    ISO_IEC_13818_6_TYPE_B	= ISO_IEC_13818_6_TYPE_A + 1,
    ISO_IEC_13818_6_TYPE_C	= ISO_IEC_13818_6_TYPE_B + 1,
    ISO_IEC_13818_6_TYPE_D	= ISO_IEC_13818_6_TYPE_C + 1,
    ISO_IEC_13818_1_AUXILIARY = ISO_IEC_13818_6_TYPE_D + 1,
    ISO_IEC_13818_1_RESERVED = ISO_IEC_13818_1_AUXILIARY + 1,
    USER_PRIVATE			= ISO_IEC_13818_1_RESERVED + 1
} MPEG2StreamType;


ISignalEvents 인터페이스

이 인터페이스는, 표준 COM IConnectionPoint 인터페이스이다. 어플리케이션으로부터 현재의 신호의 강도에 관한 정보를 받으려면 , 이 인터페이스를 이행 한다. ITuner::TriggerSignalEvents 를 호출하면, 튜너가 어플리케이션에 OnSignal 이벤트를 반복해 송신한다.

ISignalEvents::OnSignal

ISignalEvents 인터페이스

어플리케이션에 현재의 신호의 강도를 알린다.

구문

HRESULT OnSignal(long* Strength );

파라미터

Strength
[out] 새로운 신호 강도값을 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IScanningTuner 인터페이스

IScanningTuner 은,ITuner 를 계승해, 유효한 프로그래밍의 서치를 지원 하는 튜너를 직접 제어한다. 클라이언트는, 이 인터페이스에 포함되는 메소드의 어느쪽이든을 호출하기 전에, 유효한 튜닝 공간을 제공할 필요가 있다 (ITuner::put_TuningSpace 또는 ITuner::put_TuneRequest 를 사용). 이 인터페이스는, 출력용의 ITunerEvents 인터페이스와 함께 사용하게 되어 있다.

메소드명 | 설명
ITuner 메소드
get_TuningSpace | 튜너용의 현재 유효한 튜닝 공간을 취득한다.
put_TuningSpace | 튜너용의 현재 유효한 튜닝 공간을 설정한다.
EnumTuningSpaces | 이 이행으로 우선되는 튜닝 공간을 열거하는 열거자를 생성 한다.
get_TuneRequest | 튜너용의 현재 유효한 튜닝 요구를 취득한다.
put_TuneRequest | 튜너용의 현재 유효한 튜닝 요구를 설정한다.
Validate | 튜닝 요구를 실행할 수 있을지 어떨지를 나타내는 값을 돌려준다.
get_PreferredComponentTypes | 디폴트 컴퍼넌트의 선택에 사용하는 ComponentType 오브젝트의 콜렉션을 취득한다.
put_PreferredComponentTypes | 디폴트 컴퍼넌트의 선택에 사용하는 ComponentType 오브젝트의 콜렉션을 설정한다.
get_SignalStrength | 튜너 고유의 신호 강도 시학을 취득한다.
TriggerSignalEvents | ISignalEvents::OnSignal 가 반복해 불려 가는 모드에 튜너를 바꾼다.
IScanningTuner 메소드
SeekUp | 유효한 프로그래밍을 가지는 1 개(살) 위에의 채널로 전환한다.
SeekDown | 유효한 프로그래밍을 가지는 1 개(살)하의 채널로 전환한다.
ScanUp | 유효한 프로그래밍을 가지는 1 개(살) 위에의 채널로 전환해 지정된 시간 (밀리 세컨드) 포즈 하는 처리를, 삭제될 때까지 반복한다.
ScanDown | 유효한 프로그래밍을 가지는 1 개(살)하의 채널로 전환해 지정된 시간 (밀리 세컨드) 포즈 하는 처리를, 삭제될 때까지 반복한다.
AutoProgram | 유효한 프로그래밍을 가지는 채널을 모두 스캔 한다.

IScanningTuner::SeekUp

IScanningTuner 인터페이스

유효한 프로그래밍을 가지는 1 개(살) 위에의 채널로 전환한다.

구문

HRESULT SeekUp();

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

즉석에서 호출해 원래로 제어가 돌아와, 백그라운드에서 시크가 속행된다. 다른 임의의 튜닝 처리를 호출하면, 시크를 취소할 수가 있다.

IScanningTuner::SeekDown

IScanningTuner 인터페이스

유효한 프로그래밍을 가지는 1 개(살)하의 채널로 전환한다.

구문

HRESULT SeekDown();

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

즉석에서 호출해 원래로 제어가 돌아와, 백그라운드에서 시크가 속행된다. 다른 임의의 튜닝 처리를 호출하면, 시크를 취소할 수가 있다.

IScanningTuner::ScanUp

IScanningTuner 인터페이스

유효한 프로그래밍을 가지는 1 개(살) 위에의 채널로 전환해 지정된 시간 (밀리 세컨드) 포즈 하는 처리를, 삭제될 때까지 반복한다.

구문

HRESULT ScanUp(
long MillisecondsPause
    );

파라미터

MillisecondsPause
[in] 포즈 할 시간 (밀리 세컨드)을 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

즉석에서 호출해 원래로 제어가 돌아와, 백그라운드에서 스캔이 속행된다. 다른 임의의 튜닝 처리를 호출하면, 스캔을 취소할 수가 있다.

IScanningTuner::ScanDown

IScanningTuner 인터페이스

유효한 프로그래밍을 가지는 1 개(살)하의 채널로 전환해 지정된 시간 (밀리 세컨드) 포즈 하는 처리를, 삭제될 때까지 반복한다.

구문

HRESULT ScanDown(
long MillisecondsPause
    );

파라미터

MillisecondsPause
[in] 포즈 할 시간 (밀리 세컨드)을 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

즉석에서 호출해 원래로 제어가 돌아와, 백그라운드에서 스캔이 속행된다. 다른 임의의 튜닝 처리를 호출하면, 스캔을 취소할 수가 있다.

IScanningTuner::AutoProgram

IScanningTuner 인터페이스

유효한 프로그래밍을 가지는 채널을 모두 스캔 한다.

구문

HRESULT AutoProgram();

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드에서는, 즉석에서 호출해 원래로 제어가 돌아와, 백그라운드에서 스캔이 속행된다. 디바이스에 그 능력이 있으면, 다른 임의의 튜닝 처리를 호출하면, 스캔을 취소할 수가 있다. 그 이외의 경우, 스캔은 전채널을 대충 통과할 때까지 계속된다. 대부분의 내부 디바이스에서는, 이 기능의 소프트웨어 이행이 있어, 스캔으로부터 얻을 수 있는 최적 튜닝 정보가 수집된다. 또, 외부 디바이스에서는, 이 기능이 이행 되고 있기 (위해)때문에, 이 메소드가 처리를 시작 하는 수단에 지나지 않는 경우가 많다.


ITuneRequest 인터페이스

모든 ITuneRequest 오브젝트는, IPersistPropertyBag 도 지원 한다.

메소드명 | 설명
get_TuningSpace | 튜닝 공간 오브젝트를 취득한다.
get_Components | IComponent 오브젝트의 콜렉션을 취득한다.
Clone | 이 튜닝 요구의 새로운 카피를 돌려준다.
get_Locator | 네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 취득한다.
put_Locator | 네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 설정한다.

ITuneRequest::get_TuningSpace

ITuneRequest 인터페이스

튜닝 공간 오브젝트를 취득한다.

구문

HRESULT get_TuningSpace(
ITuningSpace** TuningSpace
    );

파라미터

TuningSpace
[out, retval] 돌려주어지는 오브젝트로 설정하는 ITuningSpace 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuneRequest::get_Components

ITuneRequest 인터페이스

IComponent 오브젝트의 콜렉션을 취득한다.

구문

HRESULT get_Components(
    IComponents** Components
    );

파라미터

Components
[out, retval] 돌려주어지는 오브젝트로 설정하는 IComponents 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

튜닝 요구에는 반드시 Components 콜렉션을 관련지을 수 있고 있지만, 이 콜렉션은 하늘일 가능성이 있다.

ITuneRequest::Clone

ITuneRequest 인터페이스

이 튜닝 요구의 새로운 카피를 돌려준다.

구문

HRESULT Clone(
    ITuneRequest** NewTuneRequest
    );

파라미터

NewTuneRequest
[out, retval] 새로운 오브젝트로 설정하는 ITuneRequest 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는 오브젝트의 "딥 카피 " 를 실행한다. 즉, Components, LanguageComponents 등을 포함한 모든 서브 오브젝트도 카피된다.

ITuneRequest::get_Locator

ITuneRequest 인터페이스

네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 취득한다.

구문

HRESULT get_Locator(
    ILocator** Locator
    );

파라미터

Locator
[out, retval] 새로운 오브젝트로 설정하는 ILocator 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

locator는, 요구된 브로드캐스트를 취득하는 방법이나 장소에 관한 정보를 취득하기 위해서, 네트워크 프로바이더와 트랜스폴트 정보 필터 (TIF)로부터 사용된다. 이 정보에는, 변조의 방식, 에러 수정 방식, 및 주파수가 포함된다. 어플리케이션은 하위 레벨의 세세한 튜닝 처리에 관여하지 않기 때문에, 보통, 어플리케이션으로 이 정보를 사용할 것은 없다.

ITuneRequest::put_Locator

ITuneRequest 인터페이스

네트워크 프로바이더로부터 불려 가 요구된 브로드캐스트에 관련지을 수 있었던 ILocator 오브젝트를 설정한다.

구문

HRESULT put_Locator(
    ILocator* Locator
    );

파라미터

Locator
[in] 새로운 locator를 지정하는 ILocator 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


ITunerEvents 인터페이스

이 인터페이스는, 표준 COM IConnectionPoint 인터페이스이다. 어플리케이션에 이 인터페이스를 이행 하면, 새로운 주파수 또는 채널에 튜닝 할 때마다, 튜너 오브젝트로부터 이벤트 통지를 받을 수가 있다. 이 인터페이스는 TuneRequest 오브젝트를 돌려주어, 새로운 채널 또는 주파수로 실제로 이용 가능한 서브 스트림이, 그 Components 콜렉션에 반영되고 있다.

ITunerEvents::OnTune

ITunerEvents 인터페이스

튜너 필터가 새로운 주파수에 튜닝 한 것을 어플리케이션에 알린다.

구문

  HRESULT OnTune(
  ITuneRequest** Request,
  long* Strength
    );

파라미터

Request
[in] TuneRequest 오브젝트를 받는 ITuneRequest 인터페이스 포인터의 주소. 이 오브젝트의 Components 콜렉션에, 새로운 채널 또는 주파수로 이용 가능한 서브 스트림이 반영되고 있다.
Strength
[in] 새로운 채널 또는 주파수의 신호 강도를 나타내는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


ITuningSpace 인터페이스

ITuningSpace 인터페이스는, 네트워크 고유의 튜닝 공간 모두에게 공통의 기능을 제공하는 base class이다. 튜닝 공간 컨테이너에서는, ITuningSpace 만을 공개하는 오브젝트의 인스턴스를 중복 해 생성 할 것은 없고, 반드시, ITuningSpace 로부터 파생하는 어떠한 인터페이스 (IASTCTuningSpace 등)를 지원 하는 오브젝트의 인스턴스를 생성 한다.

메소드명 | 설명
get_UniqueName | 튜닝 공간의 고유의 명칭을 취득한다. 고유의 명칭은 약칭이나 GUID 이다.
put_UniqueName | 튜닝 공간의 고유의 명칭을 설정한다. 고유의 명칭은 약칭이나 GUID 이다.
get_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 취득한다.
put_FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명을 설정한다.
get_CLSID | 튜닝 공간의 CLSID 를 BSTR 로서 취득한다.
put_NetworkType | 이 튜닝 공간의 네트워크 타입을 BSTR 로서 설정한다.
get__NetworkType | 튜닝 공간의 네트워크 타입을 GUID 로서 취득한다.
put__NetworkType | 이 튜닝 공간의 네트워크 타입을 REFCLSID 로서 설정한다.
get_NetworkType | 튜닝 공간의 네트워크 타입을 BSTR 로서 취득한다.
CreateTuneRequest | 하늘의 (초기화되어 있지 않다) 튜닝 요구를 나타내는 COM 오브젝트를 생성 한다.
EnumCategoryGUIDs | (현시점에서는 미이행) DirectShow 카테고리 GUID 를 열거하는 열거자를 생성 한다. 카테고리 GUID 는, 튜닝 공간을 지원 하는 필터의 종류를 나타내는 것이다.
EnumDeviceMonikers | (현시점에서는 미이행) 이 튜닝 공간을 지원 하는 튜너 입력 (필터)을 나타내는 데바이스모니카의 열거자를 생성 한다.
get_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 돌려준다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
put_DefaultPreferredComponentTypes | 우선 컴포넌트 타입의 리스트를 생성 한다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.
get_FrequencyMapping | 네트워크 프로바이더가 put_FrequencyMapping 를 호출해 직전에 생성 한 주파수 매핑을 취득한다.
put_FrequencyMapping | 주파수와 채널의 매핑, 주파수와 중계기의 매핑, 또는 캐리어 주파수로부터 주파수 식별자에의, 튜닝 공간에 적절한 그 외의 모든 매핑을 생성 한다.
get_DefaultLocator | 로컬 시스템의 디폴트 locator를 취득한다.
put_DefaultLocator | 로컬 시스템의 디폴트 locator를 설정한다.
Clone | 튜닝 공간의 새로운 카피를 생성 한다.

ITuningSpace::get_UniqueName

ITuningSpace 인터페이스

튜닝 공간의 고유의 명칭을 취득한다. 고유의 명칭은 약칭이나 GUID 이다.

구문

HRESULT get_UniqueName(
BSTR* Name
    );

파라미터

Name
[out, retval] 고유의 명칭을 받는 BSTR 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

고유의 명칭은, 글로벌하게 일의인 임의의 캐릭터 라인이다.

ITuningSpace::put_UniqueName

ITuningSpace 인터페이스

튜닝 공간의 고유의 명칭을 설정한다. 고유의 명칭은 약칭이나 GUID 이다.

구문

HRESULT put_UniqueName(
BSTR Name
    );

파라미터

Name
[in] 고유의 명칭을 지정하는 BSTR 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpace::get_FriendlyName

ITuningSpace 인터페이스

튜닝 공간의 로컬라이즈 된 프렌들리명을 취득한다.

구문

HRESULT get_FriendlyName(
BSTR* Name
    );

파라미터

Name
[out, retval] 프렌들리명을 받는 BSTR 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpace::put_FriendlyName

ITuningSpace 인터페이스

튜닝 공간의 로컬라이즈 된 프렌들리명을 설정한다.

구문

HRESULT put_FriendlyName(
    BSTR Name
    );

파라미터

Name
[in] 프렌들리명을 지정하는 BSTR 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpace::get_CLSID

ITuningSpace 인터페이스

튜닝 공간의 CLSID 를 BSTR 로서 취득한다.

구문

HRESULT get_CLSID(
    BSTR* SpaceCLSID
    );

파라미터

SpaceCLSID
[out, retval] 튜닝 공간의 CLSID 를 받는 BSTR 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, IPersist::GetClassID 메소드에의 스크립트 액세스를 제공한다.

ITuningSpace::get_NetworkType

ITuningSpace Interface

튜닝 공간의 네트워크 타입을 BSTR 로서 취득한다.

구문

HRESULT get_NetworkType(
    BSTR* NetworkTypeGuid
    );

파라미터

NetworkTypeGuid
[out, retval] 네트워크 타입을 나타내는 GUID 를 받는 BSTR 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

필터 그래프 구축시에는, 이 메소드로 취득한 GUID 를, 네트워크 프로바이더 필터를 생성하기 위한 CLSID 로서 사용한다. 이 메소드는, Visual Basic® 와 스크립트 어플리케이션용으로 제공된다. C++ 어플리케이션에서는,get__NetworkType 를 사용해, 네이티브인 GUID 데이터형으로서 네트워크 타입을 취득하는 것.

ITuningSpace::put_NetworkType

ITuningSpace Interface

튜닝 공간의 네트워크 타입을 BSTR 로서 지정한다.

구문

HRESULT put_NetworkType(
    REFCLSID NetworkTypeGuid
    );

파라미터

NetworkTypeGuid
[in] 네트워크 타입을 지정하는 BSTR 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, Visual Basic® 와 스크립트 어플리케이션용으로 제공된다. C++ 어플리케이션에서는,put__NetworkType 를 사용하는 것.

ITuningSpace::get__NetworkType

ITuningSpace Interface

튜닝 공간의 네트워크 타입을 GUID 로서 취득한다.

구문

HRESULT get_NetworkType(
    GUID* NetworkTypeGuid
    );

파라미터

NetworkTypeGuid
[out, retval] 네트워크 타입을 받는 GUID 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

필터 그래프의 구축시에 네트워크 프로바이더를 생성 하면나무는, 이 메소드로 취득되는 GUID 를 CLSID 로서 사용한다.

ITuningSpace::put__NetworkType

ITuningSpace Interface

튜닝 공간의 네트워크 타입을 REFCLSID 로서 지정한다.

구문

HRESULT put__NetworkType(
    BSTR NetworkTypeGuid
    );

파라미터

NetworkTypeGuid
[in] 네트워크 타입을 지정하는 REFCLSID 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpace::CreateTuneRequest

ITuningSpace 인터페이스

하늘의 (초기화되어 있지 않다) 튜닝 요구를 나타내는 COM 오브젝트를 생성 한다.

구문

HRESULT CreateTuneRequest(
    ITuneRequest** TuneRequest
    );

파라미터

TuneRequest
[out, retval] 새로운 튜닝 요구 오브젝트를 받는 ITuneRequest 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는 ITuneRequest base class 인터페이스를 돌려주지만, 이 인터페이스를 사용해 튜닝 요구를 생성 할 수 없다. 튜닝 요구를 생성 하려면 , 사용하고 있는 튜닝 공간의 타입에 관련지을 수 있었던 파생 인터페이스를 사용할 필요가 있다. 파생 인터페이스를 취득하려면 , 돌려주어진 ITuneRequest 오브젝트의 QueryInterface 를 호출해, 필요한 인터페이스를 지정한다. 다음의 일람은, 튜닝 공간과 튜닝 요구의 관계를 나타낸다.

튜닝 공간 | 튜닝 요구
IAnalogTVTuningSpace | IID_IChannelTuneRequest
IAnalogRadioTuningSpace | IID_IChannelTuneRequest
IDVBTuningSpace | IID_IDVBTuneRequest
IATSCTuningSpace | IID_IATSCChannelTuneRequest

ITuningSpace::EnumCategoryGUIDs

ITuningSpace 인터페이스

(현시점에서는 미이행) DirectShow 카테고리 GUID 를 열거하는 열거자를 생성 한다. 카테고리 GUID 는, 튜닝 공간을 지원 하는 필터의 종류를 나타내는 것이다.

구문

HRESULT EnumCategoryGUIDs(
    IEnumGUID** ppEnum
    );

파라미터

ppEnum
[out, retval] 돌려주어진 열거 오브젝트를 받는 IEnumGUID 인터페이스 포인터의 주소.

반환값

E_NOTIMPL 를 돌려준다.

주의

이 메소드에 오토메이션 언어로부터 액세스 할 수 없다.

ITuningSpace::EnumDeviceMonikers

ITuningSpace 인터페이스

(현시점에서는 미이행) 이 튜닝 공간을 지원 하는 튜너 입력 (필터)을 나타내는 데바이스모니카의 열거자를 생성 한다.

구문

HRESULT EnumDeviceMonikers(
    IEnumMoniker** ppEnum
    );

파라미터

ppEnum
[out, retval] 돌려주어진 열거 오브젝트를 받는 IEnumMoniker 인터페이스 포인터의 주소.

반환값

E_NOTIMPL 를 돌려준다.

주의

이 메소드에 오토메이션 언어로부터 액세스 할 수 없다.

ITuningSpace::get_DefaultPreferredComponentTypes

ITuningSpace 인터페이스

우선 컴포넌트 타입의 리스트를 돌려준다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.

구문

HRESULT get_DefaultPreferredComponentTypes(
    IComponentTypes** ComponentTypes
    );

파라미터

ComponentTypes
[out, retval] 돌려주어진 콜렉션을 받는 IComponentTypes 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 문맥에서는, 프로그램내의 스트림을 "컴퍼넌트 " 라고 말한다. "우선 컴퍼넌트 " 에는, 예를 들어 영어의 오디오 스트림등이 설정되어 있다. 컴퍼넌트 또는 서브 스트림이 다수 있는 경우, 튜너는 반드시 우선 컴퍼넌트를 먼저 재생하려고 한다.

ITuningSpace::put_DefaultPreferredComponentTypes

ITuningSpace 인터페이스

우선 컴포넌트 타입의 리스트를 생성 한다. 우선 컴포넌트 타입은, 우선 오디오 스트림등의 파라미터를 지정하는 것이다.

구문

HRESULT put_DefaultPreferredComponentTypes(
    IComponentTypes* NewComponentTypes
    );

파라미터

NewComponentTypes
[in] 디폴트의 우선 컴포넌트 타입을 지정하는 ComponentTypes 오브젝트의 IComponentTypes 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpace::get_FrequencyMapping

ITuningSpace 인터페이스

네트워크 프로바이더가 put_FrequencyMapping 를 호출해 직전에 생성 한 주파수 매핑을 취득한다.

구문

HRESULT get_FrequencyMapping(
    BSTR* pMapping
    );

파라미터

pMapping
[out, retval] 네트워크 프로바이더가 생성 한 주파수 매핑을 받는 BSTR.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 BSTR 는 바이너리 라지 오브젝트 (BLOB)로서 처리된다. 이 BSTR 에는, NULL 가 파묻혀 네트워크 프로바이더 캔버스 우려 실 판단하는 서식에서 내부적으로 포맷 될 가능성이 있다.

ITuningSpace::put_FrequencyMapping

ITuningSpace 인터페이스

주파수와 채널의 매핑, 주파수와 중계기의 매핑, 또는 캐리어 주파수로부터 주파수 식별자에의, 튜닝 공간에 적절한 그 외의 모든 매핑을 생성 한다.

구문

HRESULT put_FrequencyMapping(
    BSTR Mapping
    );

파라미터

Mapping
[in] 주파수 매핑이 저장 된 BSTR.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, 주파수 매핑이 들어간 캐릭터 라인을 저장 하기 위해서, 네트워크 프로바이더로부터 사용된다.

ITuningSpace::get_DefaultLocator

ITuningSpace 인터페이스

로컬 시스템의 디폴트 locator를 취득한다.

구문

HRESULT get_DefaultLocator(
    ILocator** LocatorVal
    );

파라미터

LocatorVal
[out, retval] 돌려주어진 ILocator 인터페이스를 받는 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

디폴트의 locator는, 인스톨 후에 IScanningTuner 오브젝트의 시점으로서 사용할 수 있다.

ITuningSpace::put_DefaultLocator

ITuningSpace 인터페이스

로컬 시스템의 디폴트 locator를 설정한다.

구문

HRESULT put_DefaultLocator(
    ILocator* LocatorVal
    );

파라미터

LocatorVal
[in] 디폴트의 locator로서 설정하는 오브젝트의 ILocator 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

디폴트의 locator는, 인스톨 후에 IScanningTuner 오브젝트의 시점으로서 사용할 수 있다.

ITuningSpace::Clone

ITuningSpace 인터페이스

새로운 튜닝 공간을 카피한다.

구문

HRESULT Clone(
    ITuningSpace** NewTS
    );

파라미터

NewTS
[out, retval] 새로운 튜닝 공간 오브젝트가 세트 되는 ITuningSpace 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


ITuningSpaces 인터페이스

이 인터페이스는, SystemTuningSpaces 오브젝트에 이행 되어 호스트 시스템으로 이용 가능한 튜닝 공간을 취득하는 메소드를 제공한다.

메소드명 | 설명
get_Count | 콜렉션에 포함되는 튜닝 공간의 수를 취득한다.
get_EnumTuningSpaces | C++ 어플리케이션용의 컨비니언스 함수. VARIANT 데이터형을 unpack 할 필요가 없다.
get_Item | 콜렉션에 포함되는 지정된 항목을 돌려준다.
get__NewEnum | Visual Basic 및 스크립트 어플리케이션용의 헬퍼 메소드. C++ 에서는 사용하지 않는다.

ITuningSpaces::get_Count

ITuningSpaces 인터페이스

콜렉션에 포함되는 튜닝 공간의 수를 취득한다.

구문

HRESULT get_Count(
long* Count
    );

파라미터

Count
[out, retval] 콜렉션에 포함되는 항목의 수를 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다.

ITuningSpaces::get_EnumTuningSpaces

ITuningSpaces 인터페이스

C++ 어플리케이션용의 컨비니언스 함수. VARIANT 데이터형을 unpack 할 필요가 없다.

구문

HRESULT get_EnumTuningSpaces(
    IEnumTuningSpaces** NewEnum
    );

파라미터

NewEnum
[out, retval] 새로운 콜렉션을 받는 IEnumTuningSpaces 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다.

ITuningSpaces::get_Item

ITuningSpaces 인터페이스

콜렉션에 포함되는 지정된 항목을 돌려준다.

구문

HRESULT get_Item(
VARIANT varIndex,
ITuningSpace** TuningSpace
    );

파라미터

varIndex
[in] 돌려주는 항목을 지정하는 캐릭터 라인 또는 인덱스 번호.
TuningSpace
[out, retval] 돌려주어지는 ITuningSpace 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다.

ITuningSpaces::get__NewEnum

ITuningSpaces 인터페이스

Visual Basic 및 스크립트 어플리케이션용의 헬퍼 메소드. C++ 에서는 사용하지 않는다.

구문

HRESULT get__NewEnum(
    IEnumVARIANT** NewEnum
    );

파라미터

NewEnum
[out, retval] IEnumVariant 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다.

주의

Microsoft® Visual Basic® 및 스크립트 어플리케이션으로, For...Next 루프내로부터 항목을 취득하려면 , 이 메소드를 사용한다.


ITuningSpaceContainer 인터페이스

ITuningSpaceContainer 인터페이스는, SystemTuningSpaces 오브젝트에 이행 된다. SystemTuningSpaces 오브젝트를 사용 하면, 어플리케이션으로부터 로컬 시스템에 정의된 전튜닝 공간의 액세스 및 수정을 할 수 있다.

메소드명 | 설명
get_Count | 로컬 시스템상에서 현재 이용 가능한 튜닝 공간의 수를 취득한다.
get__NewEnum | Automation 클라이언트의 For...Each 루프를 지원하기 위한 열거 메소드.
get_Item | 지정된 인덱스 위치의 튜닝 공간 오브젝트를 취득한다.
put_Item | 지정된 인덱스 위치에 튜닝 공간 오브젝트를 보존한다.
TuningSpacesForCLSID | 지정된 CLSID 캐릭터 라인과 일치하는 튜닝 공간의 콜렉션을 취득한다. (Automation 클라이언트로 사용)
_TuningSpacesForCLSID | 지정된 CLSID 캐릭터 라인과 일치하는 튜닝 공간의 콜렉션을 취득한다. (C++ 클라이언트로 사용)
TuningSpacesForName | 프렌들리명으로 일치하는 튜닝 공간의 콜렉션을 취득한다.
FindID | 지정된 튜닝 공간의 로컬 일의 식별자를 취득한다.
Add | 새로운 지속적인 튜닝 공간을 시스템에 추가한다.
get_EnumTuningSpaces | 로컬 시스템상에서 이용 가능한 전튜닝 공간의 콜렉션을 취득한다.
Remove | 튜닝 공간을 시스템으로부터 완전하게 삭제한다.
put_MaxCount | 시스템상에서 용서되는 튜닝 공간의 최대수를 취득한다.
get_MaxCount | 시스템상에서 용서되는 튜닝 공간의 최대수를 설정한다.

ITuningSpaceContainer::get_Count

ITuningSpaceContainer 인터페이스

로컬 시스템상에서 현재 이용 가능한 튜닝 공간의 수를 취득한다.

구문

HRESULT get_Count(
    long *Count
    );

파라미터

Count
[out, retval] 튜닝 공간의 수를 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpaceContainer::get_MaxCount

ITuningSpaceContainer 인터페이스

시스템상에서 용서되는 튜닝 공간의 최대수를 취득한다.

구문

HRESULT get_MaxCount(
    long *MaxCount
    );

파라미터

MaxCount
[out, retval] 튜닝 공간의 최대수를 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpaceContainer::get__NewEnum

ITuningSpaceContainer 인터페이스

Automation 클라이언트의 For...Each 루프를 지원하기 위한 열거 메소드.

구문

HRESULT get__NewEnum(
    IEnumVARIANT **NewEnum
    );

파라미터

NewEnum
[out, retval] 돌려주어지는 콜렉션으로 설정하는 IEnumVARIANT 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드는, For...Each 루프의 반복에 의해 콜렉션 전체를 처리하기 위해(때문에), 스크립트 어플리케이션 및 VB 어플리케이션용으로 제공된다. C++ 어플리케이션에서는 get_EnumTuningSpaces 메소드를 사용하는 것.

ITuningSpaceContainer::get_Item

ITuningSpaceContainer 인터페이스

지정된 인덱스 위치의 ITuningSpace 오브젝트를 취득한다.

구문

HRESULT get_Item(
VARIANT varIndex,
    ITuningSpace **ppTuningSpace
    );

파라미터

varIndex
[in] 취득하는 항목의 인덱스를 지정하는 VARIANT 형 변수.
ppTuningSpace
[out, retval] 돌려주어지는 인터페이스로 설정하는 ITuningSpace 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpaceContainer::put_Item

ITuningSpaceContainer 인터페이스

지정된 인덱스 위치에 튜닝 공간 오브젝트를 보존한다.

구문

HRESULT put_Item(
VARIANT varIndex,
    ITuningSpace *pTuningSpace
    );

파라미터

varIndex
[in] 설정하는 항목의 인덱스를 지정하는 VARIANT 형 변수.
pTuningSpace
[in] 시스템에 지속적으로 보존하는 오브젝트의 ITuningSpace 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

ITuningSpace 의 메소드를 사용 하면, 어플리케이션으로부터 기존의 튜닝 공간을 수정해,ITuningSpaceContainer::put_Item 를 사용해 변경 내용을 디스크에 보존할 수가 있다.

ITuningSpaceContainer::TuningSpacesForCLSID

ITuningSpaceContainer 인터페이스

CLSID 캐릭터 라인과 일치하는 튜닝 공간의 콜렉션을 취득한다. (Automation 클라이언트로 사용)

구문

HRESULT TuningSpacesForCLSID(
    BSTR SpaceCLSID,
    ITuningSpaces **ppTuningSpaces
    );

파라미터

SpaceCLSID
[in] 튜닝 공간의 CLSID 를 나타내는 캐릭터 라인.
ppTuningSpaces
[out, retval] 돌려주어지는 콜렉션으로 설정하는 ITuningSpaces 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드를 사용 하면, Automation 클라이언트로부터 CLSID 를 BSTR 로 지정할 수 있다. 내부적으로는, _TuningSpacesForCLSID 를 호출하고 있는 것만으로 있다.

ITuningSpaceContainer::_TuningSpacesForCLSID

ITuningSpaceContainer 인터페이스

지정된 CLSID 캐릭터 라인과 일치하는 튜닝 공간의 콜렉션을 취득한다. (C++ 클라이언트로 사용)

구문

HRESULT _TuningSpacesForCLSID(
    REFCLSID SpaceCLSID,
    ITuningSpaces **ppTuningSpaces
    );

파라미터

SpaceCLSID
[in] 취득하는 튜닝 공간의 타입을 지정하는 REFCLSID 형 변수.
ppTuningSpaces
[out, retval] 돌려주어지는 콜렉션으로 설정하는 ITuningSpaces 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

C++ 어플리케이션에서는, TuningSpacesForCLSID 는 아니고 이 메소드를 사용하는 것.

ITuningSpaceContainer::TuningSpacesForName

ITuningSpaceContainer 인터페이스

프렌들리명으로 일치하는 튜닝 공간의 콜렉션을 취득한다.

구문

HRESULT TuningSpacesForName(
    BSTR Name,
    ITuningSpaces **ppTuningSpaces
    );

파라미터

Name
[in] 튜닝 공간 타입의 프렌들리명을 나타내는 캐릭터 라인.
ppTuningSpaces
[out, retval] 돌려주어지는 콜렉션으로 설정하는 ITuningSpaces 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpaceContainer::FindID

ITuningSpaceContainer 인터페이스

지정된 튜닝 공간의 로컬 일의 식별자를 취득한다.

구문

HRESULT FindID(
    ITuningSpace *pTuningSpace,
    long *pID
    );

파라미터

pTuningSpace
[in] ID 를 취득하는 오브젝트의 ITuningSpace 인터페이스에의 포인터.
pID
[out, retval] ID 번호를 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. TuningSpace 가 유효한 오브젝트를 가리키지 않은 경우는, E_INVALIDARG 를 돌려준다.

ITuningSpaceContainer::Add

ITuningSpaceContainer 인터페이스

새로운 지속적인 튜닝 공간을 시스템에 추가한다.

구문

HRESULT Add(
    ITuningSpace *pTuningSpace,
    VARIANT *pNewIndex
    );

파라미터

pTuningSpace
[in] 시스템에 추가하는 새로운 튜닝 공간 오브젝트의 ITuningSpace 인터페이스에의 포인터.
pNewIndex
[out, retval] 현재의 콜렉션에 있어서의 새로운 튜닝 공간의 인덱스 번호를 받는 VARIANT 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

ITuningSpaceContainer::Add() 메소드에서는, 추가한 오브젝트의 인덱스가 1 으로부터 시작된다. IComponentTypes::Add() 메소드 및 그 외의 콜렉션에서는, 모두 0 으로부터 시작된다.

ITuningSpaceContainer::get_EnumTuningSpaces

ITuningSpaceContainer 인터페이스

로컬 시스템상에서 이용 가능한 전튜닝 공간의 콜렉션을 취득한다.

구문

HRESULT get_EnumTuningSpaces(
    IEnumTuningSpaces **ppEnum
    );

파라미터

ppEnum
[out, retval] 돌려주어지는 콜렉션으로 설정하는 IEnumTuningSpaces 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

C++ 어플리케이션에서는, 이 메소드를 사용해 로컬 시스템에 정의된 튜닝 공간의 초기 리스트를 취득한다.

ITuningSpaceContainer::put_MaxCount

ITuningSpaceContainer 인터페이스

시스템상에서 용서되는 튜닝 공간의 최대수를 설정한다.

구문

HRESULT put_MaxCount(
    long MaxCount
    );

파라미터

MaxCount
[in] 튜닝 공간의 최대수를 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuningSpaceContainer::Remove

ITuningSpaceContainer 인터페이스

튜닝 공간을 시스템으로부터 완전하게 삭제한다.

구문

HRESULT Remove(
VARIANT Index
    );

파라미터

Index
[in] 시스템으로부터 삭제하는 튜닝 공간의 인덱스 번호를 지정하는 VARIANT 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 지정된 튜닝 공간이 무효인가, 또는 레지스트리내에서 파손하고 있는 경우는, 정보를 모두 삭제해, S_FALSE 를 돌려준다.


ITuner 인터페이스

ITuner 는, 네트워크 프로바이더 필터에 이행 된다.

메소드명 | 설명
get_TuningSpace | 네트워크 프로바이더용의 현재 유효한 튜닝 공간을 취득한다.
put_TuningSpace | 네트워크 프로바이더용의 튜닝 공간을 설정한다.
EnumTuningSpaces | 이 이행으로 우선되는 튜닝 공간의 콜렉션을 생성 한다.
get_TuneRequest | 네트워크 프로바이더용의 현재 유효한 튜닝 요구를 취득한다.
put_TuneRequest | 네트워크 프로바이더용의 튜닝 요구를 설정한다.
Validate | 튜닝 요구를 실행할 수 있을지 어떨지를 나타내는 값을 돌려준다.
get_PreferredComponentTypes | 디폴트 컴퍼넌트의 선택에 사용하는 ComponentType 오브젝트의 콜렉션을 취득한다.
put_PreferredComponentTypes | 디폴트 컴퍼넌트의 선택에 사용하는 ComponentType 오브젝트의 콜렉션을 설정한다.
get_SignalStrength | 네트워크 프로바이더 고유의 신호 강도 시학을 취득한다.
TriggerSignalEvents | ISignalEvents::OnSignal 가 반복해 불려 가는 모드에 네트워크 프로바이더를 바꾼다.

ITuner::get_TuningSpace

ITuner 인터페이스

네트워크 프로바이더용의 현재 유효한 튜닝 공간을 취득한다.

구문

HRESULT get_TuningSpace(
ITuningSpace** TuningSpace
    );

파라미터

TuningSpace
[out, retval] 현재의 튜닝 공간으로 설정하는 ITuningSpace 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuner::put_TuningSpace

ITuner 인터페이스

네트워크 프로바이더용의 튜닝 공간을 설정한다.

구문

HRESULT put_TuningSpace(
ITuningSpace* TuningSpace
    );

파라미터

TuningSpace
[in] 네트워크 프로바이더로 설정하는 튜닝 공간에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

ITuner::EnumTuningSpaces

ITuner 인터페이스

이 이행으로 우선되는 튜닝 공간의 콜렉션을 생성 한다.

구문

HRESULT EnumTuningSpaces(
IEnumTuningSpaces** ppEnum
    );

파라미터

ppEnum
[out, retval] 돌려주어지는 콜렉션으로 설정하는 IEnumTuningSpaces 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 리스트는, 이 이행과 호환성이 있는 튜닝 공간의 서브 세트이다.

ITuner::get_TuneRequest

ITuner 인터페이스

네트워크 프로바이더용의 현재 유효한 튜닝 요구를 취득한다.

구문

HRESULT get_TuneRequest(
ITuneRequest** TuneRequest
    );

파라미터

TuneRequest
[out, retval] 돌려주어지는 오브젝트로 설정하는 ITuneRequest 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

튜너에 튜닝 요구를 발행한 후에, 그 Components 콜렉션의 내용이 설정된다. 어플리케이션에서는, 프로그램에의 튜닝 후에 get_TuneRequest 를 호출해, 그 프로그램으로 현재 이용 가능한 컴퍼넌트를 판단해, 게다가 콜렉션에 포함되는 컴퍼넌트 오브젝트의 IComponent::put_Status 메소드를 사용해, 그 컴퍼넌트를 액티브 또는 비액티브하게 할 수가 있다. 어플리케이션으로 오디오 스트림을 (예를 들어 영어로부터 스페인어에) 바꾸는 경우에는, 이 방법으로 실시한다.

ITuner::put_TuneRequest

ITuner 인터페이스

네트워크 프로바이더용의 현재 유효한 튜닝 요구를 설정한다.

구문

HRESULT put_TuneRequest(
ITuneRequest* TuneRequest
    );

파라미터

TuneRequest
[in] 네트워크 프로바이더의 설정에 사용하는 ITuneRequest 오브젝트에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 메소드를 호출하면, 튜닝 요구의 프로퍼티에 근거해 튜닝 처리가 시작 한다. 튜닝 처리는 비동기에 행해질 가능성이 있다.

ITuner::Validate

ITuner 인터페이스

튜닝 요구를 실행할 수 있을지 어떨지를 나타내는 값을 돌려준다.

구문

HRESULT Validate(
ITuneRequest* TuneRequest
    );

파라미터

TuneRequest
[in] 튜닝 요구 오브젝트에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

입력으로서 IUnknown* 를 받아들인다. 네트워크 프로바이더는, 우선, 우선되는 튜닝 요구 인터페이스를 조회한다. 발견되었을 경우는, 튜닝 요구를 실행할 수 있을지 어떨지를 확인한다. 발견되지 않으면, 우선되는 튜닝 공간 인터페이스를 조회한다. 발견되었을 경우는, 소정의 튜닝 공간에 맞추어 네트워크 프로바이더 자체를 구성할 수 있을지 어떨지를 확인한다.

ITuner::get_PreferredComponentTypes

ITuner 인터페이스

디폴트 컴퍼넌트의 선택에 사용하는 ComponentType 오브젝트의 콜렉션을 취득한다.

구문

HRESULT get_PreferredComponentTypes(
IComponentTypes** ComponentTypes
    );

파라미터

ComponentTypes
[out, retval] ComponentType 오브젝트의 콜렉션을 받는 IComponentTypes 인터페이스 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

프로그램이 종료 하면, 새로운 서브 스트림 ("컴퍼넌트 ")세트가 이용 가능하게 될 가능성이 있다. 이 때문에, 튜너는, 우선 컴포넌트 타입의 리스트를 자동적으로 조사해 그 리스트에 따라 서브 스트림을 선택한다. 리스트가 없는 경우는, 다른 요인에 근거해 선택을 한다. 어플리케이션에서는, 단지 현재의 리스트를 조사하기 (위해)때문에, 이 메소드를 호출한다.

ITuner::put_PreferredComponentTypes

ITuner 인터페이스

디폴트 컴퍼넌트의 선택에 사용하는 ComponentType 오브젝트의 콜렉션을 설정한다.

구문

HRESULT put_PreferredComponentTypes(
IComponentTypes* ComponentTypes
    );

파라미터

ComponentTypes
[in] ComponentType 오브젝트의 콜렉션이 저장 된 IComponentTypes 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

어플리케이션으로 우선 컴포넌트 타입의 리스트를 생성 하려면 , 하늘의 ComponentTypes 콜렉션을 인스턴스화해, 거기에 내용을 설정하고 나서 put_PreferredComponentTypes 를 사용해 튜너에 건네준다.

ITuner::get_SignalStrength

ITuner 인터페이스

네트워크 프로바이더 고유의 신호 강도 시학을 취득한다.

구문

HRESULT get_SignalStrength(
long* Strength
    );

파라미터

Strength
[out, retval] 신호 강도를 받는 Long 형 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

-1 (은)는 신호 강도를 판단할 수 없는 것을 나타내, 0 은 튜닝되어 있지 않은 것을 나타낸다. 또, 큰 값은 강한 신호를 의미한다. 디지털 튜너의 경우, FEC 의 비트 에러 레이트 (BER)도 이와 같이 해석할 수 있다.

ITuner::TriggerSignalEvents

ITuner 인터페이스

ISignalEvents::OnSignal 가 반복해 불려 가는 모드에 네트워크 프로바이더를 바꾼다.

구문

HRESULT TriggerSignalEvents(
long Interval
    );

파라미터

Interval
[in] 트리거 이벤트의 송신 간격을 지정하는 Long 형 변수.

반환값

성공했을 경우는, S_OK 를 돌려준다. 실패했을 경우는, 표준의 IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

이 모드가 지원되어 있지 않은 경우는, E_NOTIMPL 를 돌려준다. 간격에는, Signal 이벤트의 생성 빈도를 밀리 세컨드 단위로 지정한다.


스크립트 가능한 오브젝트

이하의 스크립트 가능한 오브젝트 (Automation 준거의 오브젝트)는, 스크립트 어플리케이션으로부터 액세스 할 수 있다. 이 릴리스에서는, 이러한 오브젝트의 메소드와 프로퍼티를 JScript 의 구문만으로 표현한다. VisualBasic 를 사용하는 경우는, 오브젝트 브라우저로 오브젝트를 표시 하면, 데이터형을 조사할 수가 있다. C++ 를 사용하는 경우, 상세한 것에 대하여는 idl 파일을 조사하는 것.

튜닝 공간 오브젝트

튜닝 공간 오브젝트는, 네트워크 타입이나 네트워크 프로바이더라든지 변해 없고, 특정의 프로그램에 튜닝하기 위한 범용적인 수단을 이행 하기 위해서 사용한다. 가이드 스토어를 사용하는 어플리케이션에서는 독자적인 튜닝 요구를 구축할 필요가 없기 때문에, 보통, 어플리케이션으로 이러한 오브젝트를 사용할 것은 없다. 어플리케이션에서는, 기제의 튜닝 요구를 가이드 스토어로부터 취득해, 그것들을 비디오 컨트롤에 건네준다.

AnalogRadioTuningSpace | 지상파 라디오 네트워크 고유의 튜닝 공간.
AnalogTVTuningSpace | 아날로그 TV 네트워크 고유의 튜닝 공간.
ATSCTuningSpace | ATSC 네트워크 고유의 튜닝 공간.
DVBTuningSpace | DVB 네트워크 고유의 튜닝 공간.
SystemTuningSpaces | 어플리케이션으로부터 사용되어 새로운 튜닝 공간의 생성이나, 기존의 튜닝 공간의 열거 또는 수정을 실시한다.

튜닝 요구 오브젝트

튜닝 요구는, 튜닝 공간 오브젝트의 ITuningSpace::CreateTuneRequest 를 호출해 생성 한다. 보통의 어플리케이션에서는, TuneRequest 를 독자적으로 생성 하지 않고 가이드 스토어로부터 취득한다.

ChannelTuneRequest | 아날로그 TV 네트워크 고유의 튜닝 요구 오브젝트에 이행 된다.
ATSCChannelTuneRequest | ATSC TV 네트워크 고유의 튜닝 요구 오브젝트에 이행 된다.
DVBTuneRequest | DVB TV 네트워크 고유의 튜닝 요구 오브젝트에 이행 된다.

스트림 컴퍼넌트 오브젝트

이 문맥에서는, 브로드캐스트내의 서브 스트림을 "컴퍼넌트 " 라고 말한다. 브로드캐스트 스트림의 실제의 컴퍼넌트는, 수신 시작 다음이 아니면 모른다. 그 시점에서, 네트워크 프로바이더가 Component 오브젝트 정보를 설정한다.

Component | 특정의 Component 오브젝트의 base class.
ComponentType | 특정 컴포넌트 타입 오브젝트의 base class.
ComponentTypes | 표준 COM 의 컴포넌트 타입 리스트를 제공한다.
Components | 표준 COM 의 컴퍼넌트 리스트를 제공한다.
LanguageComponentType | 서브 스트림의 언어에 관련지을 수 있었던 컴포넌트 타입.
MPEG2ComponentType | MPEG-2 스트림 타입에 관련지을 수 있었던 컴포넌트 타입에 이행 된다.
ATSCComponentType | 오디오 스트림이 AC-3 포맷화 제발을 나타내는 컴포넌트 타입에 이행 된다.

locator 오브젝트

locator 오브젝트는, 그래프에 포함되는 네트워크 프로바이더 및 그 외의 필터가, 어떤 종류의 경우에, 튜닝 요구에 응하기 (위해)때문에, 튜닝의 방법과 대상의 판단에 사용한다. 어플리케이션에서는 이러한 오브젝트를 사용하지 않는다.

Locator | 네트워크 타입 고유의 튜닝 공간 locator를 위한 base class.
MPEG2Locator | 네트워크 프로바이더로부터 불려 가 MPEG-2 베이스의 네트워크내에 있어서의 튜닝에 대해 정보를 취득한다. 어플리케이션에서는 사용하지 않는다.
ATSCLocator | 네트워크 프로바이더로부터 불려 가 ATSC 네트워크내에서의 튜닝에 관한 정보를 취득한다. 어플리케이션에서는 사용하지 않는다.
DVBTLocator | 네트워크 프로바이더로부터 불려 가 DVB-T 네트워크내에서의 튜닝에 관한 정보를 취득한다. 어플리케이션에서는 사용하지 않는다.
DVBSLocator | 네트워크 프로바이더로부터 불려 가 DVB-S 네트워크내에서의 튜닝에 관한 정보를 취득한다. 어플리케이션에서는 사용하지 않는다.


AnalogRadioTuningSpace 오브젝트

AnalogRadioTuningSpace 오브젝트는, AM 또는 FM 아날로그 라디오의 튜닝 공간을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
CLSID | 튜닝 공간의 CLSID 를 취득한다.
CreateTuneRequest | 이 튜닝 공간 고유의 튜닝 요구 오브젝트를 생성 한다.
DefaultLocator | 인스톨 후에 튜너를 사용할 수 있는 초기의 디폴트 locator를 설정 또는 취득한다.
DefaultPreferredComponentTypes | 유저 또는 어플리케이션으로부터 지정된 디폴트의 우선 컴포넌트 타입이 들어간 Components 콜렉션 오브젝트.
FriendlyName | 튜닝 공간의 로컬라이즈 된 프렌들리명.
MaxFrequency | 이 튜닝 공간에서 사용 가능한 최대 주파수 (KHz).
MinFrequency | 이 튜닝 공간에서 사용 가능한 최소 주파수 (KHz).
NetworkType | 네트워크 타입의 CLSID.
Step | 이 튜닝 공간에서 사용하는 다음의 주파수까지의 디폴트의 스텝값 (KHz).
UniqueName | 튜닝 공간을 나타내는 글로벌인 고유의 명칭.

AnalogRadioTuningSpace.CLSID 프로퍼티

AnalogRadioTuningSpace 오브젝트

튜닝 공간의 CLSID 를 취득한다.

구문

AnalogRadioTuningSpace. CLSID

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

AnalogRadioTuningSpace.CreateTuneRequest 메소드

AnalogRadioTuningSpace 오브젝트

이 튜닝 공간 고유의 튜닝 요구 오브젝트를 생성 한다.

구문

AnalogRadioTuningSpace. CreateTuneRequest()

반환값

TuneRequest 오브젝트를 돌려준다.

AnalogRadioTuningSpace.DefaultLocator 프로퍼티

AnalogRadioTuningSpace 오브젝트

인스톨 후에 튜너를 사용할 수 있는 초기의 디폴트 Locator 오브젝트를 설정 또는 취득한다.

구문

AnalogRadioTuningSpace. DefaultLocator

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogRadioTuningSpace.DefaultPreferredComponentTypes 프로퍼티

AnalogRadioTuningSpace 오브젝트

유저 또는 어플리케이션으로부터 지정된 디폴트의 우선 컴포넌트 타입이 들어간 Components 콜렉션 오브젝트.

구문

AnalogRadioTuningSpace. DefaultPreferredComponentTypes

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogRadioTuningSpace.FriendlyName 프로퍼티

AnalogRadioTuningSpace 오브젝트

튜닝 공간의 프렌들리명.

구문

AnalogRadioTuningSpace. FriendlyName

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogRadioTuningSpace.MaxFrequency 프로퍼티

AnalogRadioTuningSpace 오브젝트

이 튜닝 공간에서 사용 가능한 최대 주파수 (KHz).

구문

AnalogRadioTuningSpace. MaxFrequency

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogRadioTuningSpace.MinFrequency 프로퍼티

AnalogRadioTuningSpace 오브젝트

이 튜닝 공간에서 사용 가능한 최소 주파수 (KHz).

구문

AnalogRadioTuningSpace. MinFrequency

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogRadioTuningSpace.NetworkType 프로퍼티

AnalogRadioTuningSpace 오브젝트

네트워크 타입의 CLSID.

구문

AnalogRadioTuningSpace. NetworkType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogRadioTuningSpace.Step 프로퍼티

AnalogRadioTuningSpace 오브젝트

이 튜닝 공간에서 사용하는 다음의 주파수까지의 디폴트의 스텝값 (KHz).

구문

AnalogRadioTuningSpace. Step

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogRadioTuningSpace.UniqueName 프로퍼티

AnalogRadioTuningSpace 오브젝트

튜닝 공간을 나타내는 글로벌인 고유의 명칭.

구문

AnalogRadioTuningSpace. UniqueName

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.


AnalogTVTuningSpace 오브젝트

아날로그 TV 의 튜닝 공간을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
CLSID | 튜닝 공간의 CLSID 를 취득한다.
CountryCode | 물리 브로드캐스트 소스에의 발신으로 최초로 다이얼 하는 번호
CreateTuneRequest | 튜닝 요구 오브젝트를 생성 한다.
DefaultLocator | 인스톨 후에 튜너를 사용할 수 있는 초기의 디폴트 locator를 설정 또는 취득한다.
DefaultPreferredComponentTypes | 유저 또는 어플리케이션으로부터 지정된 디폴트의 우선 컴포넌트 타입이 들어간 Components 콜렉션 오브젝트.
FriendlyName | 튜닝 공간의 프렌들리명.
InputType | 이 튜닝 공간의 입력 타입.
MaxChannel | 이 튜닝 공간에서 제공 가능한 최대 채널 번호.
MinChannel | 이 튜닝 공간에서 제공 가능한 최소 채널 번호.
NetworkType | 네트워크 타입 (CLSID).
UniqueName | 튜닝 공간의 고유의 명칭.

AnalogTVTuningSpace.CLSID 프로퍼티

AnalogTVTuningSpace 오브젝트

튜닝 공간의 CLSID 를 취득한다.

구문

AnalogTVTuningSpace. CLSID

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

AnalogTVTuningSpace.CountryCode 프로퍼티

AnalogTVTuningSpace 오브젝트

물리 브로드캐스트 소스에의 발신으로 최초로 다이얼 하는 번호.

구문

AnalogTVTuningSpace. CountryCode

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogTVTuningSpace.CreateTuneRequest 메소드

AnalogTVTuningSpace 오브젝트

튜닝 요구 오브젝트를 생성 한다.

구문

AnalogTVTuningSpace. CreateTuneRequest()

반환값

ChannelTuneRequest 오브젝트를 돌려준다.

AnalogTVTuningSpace.DefaultLocator 프로퍼티

AnalogTVTuningSpace 오브젝트

인스톨 후에 튜너를 사용할 수 있는 초기의 디폴트 Locator 오브젝트를 설정 또는 취득한다.

구문

AnalogTVTuningSpace. DefaultLocator

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogTVTuningSpace.DefaultPreferredComponentTypes 프로퍼티

AnalogTVTuningSpace 오브젝트

유저 또는 어플리케이션으로부터 지정된 디폴트의 우선 컴포넌트 타입이 들어간 Components 콜렉션 오브젝트.

구문

AnalogTVTuningSpace. DefaultPreferredComponentTypes

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogTVTuningSpace.FriendlyName 프로퍼티

AnalogTVTuningSpace 오브젝트

튜닝 공간의 프렌들리명.

구문

AnalogTVTuningSpace. FriendlyName

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogTVTuningSpace.InputType 프로퍼티

AnalogTVTuningSpace 오브젝트

이 튜닝 공간의 입력 타입.

구문

AnalogTVTuningSpace. InputType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogTVTuningSpace.MaxChannel 프로퍼티

AnalogTVTuningSpace 오브젝트

이 튜닝 공간에서 제공 가능한 최대 채널 번호.

구문

AnalogTVTuningSpace. MaxChannel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogTVTuningSpace.MinChannel 프로퍼티

AnalogTVTuningSpace 오브젝트

이 튜닝 공간에서 제공 가능한 최소 채널 번호.

구문

AnalogTVTuningSpace. MinChannel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogTVTuningSpace.NetworkType 프로퍼티

AnalogTVTuningSpace 오브젝트

네트워크 타입 (CLSID).

구문

AnalogTVTuningSpace. NetworkType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

AnalogTVTuningSpace.UniqueName 프로퍼티

AnalogTVTuningSpace 오브젝트

튜닝 공간의 고유의 명칭.

구문

AnalogTVTuningSpace. UniqueName

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.


ATSCChannelTuneRequest 오브젝트

메소드명 또는 프로퍼티명 | 설명
Channel | 채널.
Clone | 이 튜닝 요구의 새로운 카피를 생성 한다.
Components | 컴퍼넌트의 콜렉션.
Locator | locator 오브젝트.
MinorChannel | 마이너 채널.
TuningSpace | 튜닝 공간 오브젝트.

ATSCChannelTuneRequest.Channel 프로퍼티

ATSCChannelTuneRequest 오브젝트

채널.

구문

ATSCChannelTuneRequest. Channel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCChannelTuneRequest.Clone 메소드

ATSCChannelTuneRequest 오브젝트

이 튜닝 요구의 새로운 카피를 생성 한다.

구문

ATSCChannelTuneRequest. Clone()

반환값

현재의 오브젝트의 카피인 ATSCChannelTuneRequest 오브젝트를 돌려준다.

ATSCChannelTuneRequest.Components 프로퍼티

ATSCChannelTuneRequest 오브젝트

컴퍼넌트의 콜렉션.

구문

ATSCChannelTuneRequest. Components

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

ATSCChannelTuneRequest.Locator 프로퍼티

ATSCChannelTuneRequest 오브젝트

locator 오브젝트.

구문

ATSCChannelTuneRequest. Locator

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCChannelTuneRequest.MinorChannel 프로퍼티

ATSCChannelTuneRequest 오브젝트

마이너 채널

구문

ATSCChannelTuneRequest. MinorChannel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCChannelTuneRequest.TuningSpace 프로퍼티

ATSCChannelTuneRequest 오브젝트

튜닝 공간 오브젝트.

구문

ATSCChannelTuneRequest. TuningSpace

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.


ATSCComponentType 오브젝트

ATSC 컴포넌트 타입을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
Category | 컴퍼넌트의 일반 카테고리.
Clone | 이 컴포넌트 타입의 카피를 생성 한다.
Flags | ATSC 컴포넌트 타입의 플래그.
LangID | 서브 스트림 컨텐츠의 언어를 나타내는 언어 식별자.
StreamType | MPEG2 의 스트림 타입.

ATSCComponentType.Category 프로퍼티

ATSCComponentType 오브젝트

컴퍼넌트의 일반 카테고리.

구문

ATSCComponentType. Category

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCComponentType.Clone 메소드

ATSCComponentType 오브젝트

이 컴포넌트 타입의 카피를 생성 한다.

구문

ATSCComponentType. Clone()

반환값

현재의 오브젝트의 카피인 ATSCComponentType 오브젝트를 돌려준다.

ATSCComponentType.Flags 프로퍼티

ATSCComponentType 오브젝트

ATSC 컴포넌트 타입의 플래그.

구문

ATSCComponentType. Flags

가능한 값

오디오 스트림이 AC-3 의 경우는 1. 그 이외의 경우는 0.

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCComponentType.LangID 프로퍼티

ATSCComponentType 오브젝트

서브 스트림 컨텐츠의 언어를 나타내는 언어 식별자.

구문

ATSCComponentType. LangID

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCComponentType.StreamType 프로퍼티

ATSCComponentType 오브젝트

MPEG2 의 스트림 타입.

구문

ATSCComponentType. StreamType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.


ATSCLocator 오브젝트

ATSC 네트워크 타입용의 locator 오브젝트.

메소드명 또는 프로퍼티명 | 설명
CarrierFrequency | 캐리어 주파수 (십 Hz).
Clone | locator를 카피한다.
InnerFEC | 내부 FEC 타입.
InnerFECRate | 내부 FEC 레이트.
InnerFECRate | 내부 FEC 레이트.
Modulation | 변조 타입.
OuterFEC | 외부 FEC 타입.
OuterFECRate | 외부 FEC 레이트.
PhysicalChannel | 물리 채널.
TSID | 트랜스폴트 스트림 ID.
SymbolRate | QPSK 심볼 레이트를 세트 혹은 취득한다.

ATSCLocator.CarrierFrequency 프로퍼티

ATSCLocator 오브젝트

캐리어 주파수 (십 Hz).

구문

ATSCLocator. CarrierFrequency

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCLocator.Clone 메소드

ATSCLocator 오브젝트

locator를 카피한다.

구문

ATSCLocator. Clone()

반환값

현재의 오브젝트의 카피인 ATSCLocator 오브젝트를 돌려준다.

ATSCLocator.InnerFEC 프로퍼티

ATSCLocator 오브젝트

내부 FEC 타입.

구문

ATSCLocator. InnerFEC

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCLocator.InnerFECRate 프로퍼티

ATSCLocator 오브젝트

내부 FEC 레이트.

구문

ATSCLocator. InnerFECRate

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

ATSCLocator.InnerFECRate 프로퍼티

ATSCLocator 오브젝트

내부 FEC 레이트.

구문

ATSCLocator. InnerFECRate

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

ATSCLocator.Modulation 프로퍼티

ATSCLocator 오브젝트

변조 타입.

구문

ATSCLocator. Modulation

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCLocator.OuterFEC 프로퍼티

ATSCLocator 오브젝트

외부 FEC 타입.

구문

ATSCLocator. OuterFEC

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCLocator.OuterFECRate 프로퍼티

ATSCLocator 오브젝트

외부 FEC 레이트.

구문

ATSCLocator. OuterFECRate

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCLocator.PhysicalChannel 프로퍼티

ATSCLocator 오브젝트

물리 채널.

구문

ATSCLocator. PhysicalChannel

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCLocator.TSID 프로퍼티

ATSCLocator 오브젝트

트랜스폴트 스트림 ID.

구문

ATSCLocator. TSID

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCLocator.SymbolRate 프로퍼티

ATSCLocator 오브젝트

QPSK 심볼 레이트를 세트 혹은 취득한다.

구문

ATSCLocator. SymbolRate

주의

이 프로퍼티는 읽고 쓰기 가능한 프로퍼티이다. QPSK 는 RF 신호에 심볼을 변조한다. 이러한 심볼은 원상회복기에 의해 검출되어 비트 스트림을 재구축 하는데 사용된다. OPSK 는 변경을 위해서(때문에) 변조/복조되는 레이트를 허가한다.


ATSCTuningSpace 오브젝트

ATSC 네트워크 타입의 튜닝 공간을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
CLSID | 튜닝 공간의 CLSID 를 취득한다.
CountryCode | 물리 브로드캐스트 소스에의 발신으로 최초로 다이얼 하는 번호.
CreateTuneRequest | 튜닝 요구 오브젝트를 생성 한다.
DefaultLocator | 인스톨 후에 튜너를 사용할 수 있는 초기의 디폴트 locator를 설정 또는 취득한다.
DefaultPreferredComponentTypes | 유저 또는 어플리케이션으로부터 지정된 디폴트의 우선 컴포넌트 타입이 들어간 Components 콜렉션 오브젝트.
FriendlyName | 튜닝 공간의 프렌들리명.
InputType | 이 튜닝 공간의 입력 타입.
MaxChannel | 이 튜닝 공간에서 제공 가능한 최대 채널 번호.
MaxMinorChannel | 이 튜닝 공간에서 제공 가능한 최대의 마이너 채널 번호.
MaxPhysicalChannel | 이 튜닝 공간에서 제공 가능한 최대의 물리 채널 번호.
MinChannel | 이 튜닝 공간에서 제공 가능한 최소 채널 번호.
MinMinorChannel | 이 튜닝 공간에서 제공 가능한 최소의 마이너 채널 번호.
MinPhysicalChannel | 이 튜닝 공간에서 제공 가능한 최소의 물리 채널 번호.
NetworkType | 네트워크 타입 (CLSID).
UniqueName | 튜닝 공간의 고유의 명칭.

ATSCTuningSpace.CLSID 프로퍼티

ATSCTuningSpace 오브젝트

물리 브로드캐스트 소스를 사용하는 나라전용의, 국제 다이야르프레픽스.

구문

ATSCTuningSpace. CLSID

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

ATSCTuningSpace.CountryCode 프로퍼티

ATSCTuningSpace 오브젝트

물리 브로드캐스트 소스에의 발신으로 최초로 다이얼 하는 번호.

구문

ATSCTuningSpace. CountryCode

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.CreateTuneRequest 메소드

ATSCTuningSpace 오브젝트

튜닝 요구 오브젝트를 생성 한다.

구문

ATSCTuningSpace. CreateTuneRequest()

반환값

ATSCChannelTuneRequest 오브젝트를 돌려준다.

ATSCTuningSpace.DefaultLocator 프로퍼티

ATSCTuningSpace 오브젝트

인스톨 후에 튜너를 사용할 수 있는 초기의 디폴트 Locator 오브젝트를 설정 또는 취득한다.

구문

ATSCTuningSpace. DefaultLocator

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.DefaultPreferredComponentTypes 프로퍼티

ATSCTuningSpace 오브젝트

유저 또는 어플리케이션으로부터 지정된 디폴트의 우선 컴포넌트 타입이 들어간 Components 콜렉션 오브젝트.

구문

ATSCTuningSpace. DefaultPreferredComponentTypes

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.FriendlyName 프로퍼티

ATSCTuningSpace 오브젝트

튜닝 공간의 프렌들리명.

구문

ATSCTuningSpace. FriendlyName

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.InputType 프로퍼티

ATSCTuningSpace 오브젝트

이 튜닝 공간의 입력 타입.

구문

ATSCTuningSpace. InputType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.MaxChannel 프로퍼티

ATSCTuningSpace 오브젝트

이 튜닝 공간에서 제공 가능한 최대 채널 번호.

구문

ATSCTuningSpace. MaxChannel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.MaxMinorChannel 프로퍼티

ATSCTuningSpace 오브젝트

이 튜닝 공간에서 제공 가능한 최대의 마이너 채널 번호.

구문

ATSCTuningSpace. MaxMinorChannel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다. 최소 마이너 채널을 최대 마이너 채널보다 크게 하지 않기 때문에,MinMinorChannel 프로퍼티보다 먼저 이 프로퍼티를 설정할 필요가 있다. 어느 쪽의 프로퍼티도, 디폴트값은 -1 (설정 없음)이다.

ATSCTuningSpace.MaxPhysicalChannel 프로퍼티

ATSCTuningSpace 오브젝트

이 튜닝 공간에서 제공 가능한 최대의 물리 채널 번호.

구문

ATSCTuningSpace. MaxPhysicalChannel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.MinChannel 프로퍼티

ATSCTuningSpace 오브젝트

이 튜닝 공간에서 제공 가능한 최소 채널 번호.

구문

ATSCTuningSpace. MinChannel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.MinMinorChannel 프로퍼티

ATSCTuningSpace 오브젝트

이 튜닝 공간에서 제공 가능한 최소의 마이너 채널 번호.

구문

ATSCTuningSpace. MinMinorChannel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다. 최소 마이너 채널을 최대 마이너 채널보다 크게 하지 않기 때문에, 이 프로퍼티보다 먼저 MaxMinorChannel 프로퍼티를 설정할 필요가 있다. 어느 쪽의 프로퍼티도, 디폴트값은 -1 (설정 없음)이다.

ATSCTuningSpace.MinPhysicalChannel 프로퍼티

ATSCTuningSpace 오브젝트

이 튜닝 공간에서 제공 가능한 최소의 물리 채널 번호.

구문

ATSCTuningSpace. MinPhysicalChannel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.MinPhysicalChannel 프로퍼티

ATSCTuningSpace 오브젝트

이 튜닝 공간에서 제공 가능한 최소의 물리 채널 번호.

구문

ATSCTuningSpace. MinPhysicalChannel

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

ATSCTuningSpace.NetworkType 프로퍼티

ATSCTuningSpace 오브젝트

네트워크 타입 (CLSID).

구문

ATSCTuningSpace. NetworkType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ATSCTuningSpace.UniqueName 프로퍼티

ATSCTuningSpace 오브젝트

튜닝 공간의 고유의 명칭.

구문

ATSCTuningSpace. UniqueName

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.


ChannelTuneRequest 오브젝트

아날로그 TV 네트워크 타입용의 유효한 튜닝 요구를 나타낸다.

메소드명 또는 프로퍼티명 | 설명
Channel | 이 튜닝 요구의 채널을 취득 또는 설정한다.
Clone | 이 튜닝 요구의 새로운 카피를 생성 한다.
Components | 컴퍼넌트의 콜렉션.
Locator | locator 오브젝트.
TuningSpace | 튜닝 공간 오브젝트.

ChannelTuneRequest.Channel 프로퍼티

ChannelTuneRequest 오브젝트

채널.

구문

ChannelTuneRequest. Channel

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다. 채널의 지정값이 튜닝 공간으로 설정된 최소 채널보다 작은 경우는, 최대 채널에 "rack-around " 한다. 같이 채널의 지정값이 튜닝 공간으로 설정된 최대 채널보다 큰 경우는, 최소 채널에 "rack-around " 한다.

ChannelTuneRequest.Clone 메소드

ChannelTuneRequest 오브젝트

이 튜닝 요구의 새로운 카피를 생성 한다.

구문

ChannelTuneRequest. Clone(NewTuneRequest)

반환값

현재의 오브젝트의 카피인 ChannelTuneRequest 오브젝트를 돌려준다.

ChannelTuneRequest.Components 프로퍼티

ChannelTuneRequest 오브젝트

컴퍼넌트의 콜렉션.

구문

ChannelTuneRequest. Components

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

ChannelTuneRequest.Locator 프로퍼티

ChannelTuneRequest 오브젝트

locator 오브젝트.

구문

ChannelTuneRequest. Locator

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

ChannelTuneRequest.TuningSpace 프로퍼티

ChannelTuneRequest 오브젝트

튜닝 공간 오브젝트.

구문

ChannelTuneRequest. TuningSpace

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.


Component 오브젝트

현재의 브로드캐스트 스트림에 포함되는 컴퍼넌트 또는 서브 스트림을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
Clone | 컴퍼넌트를 카피한다.
DescLangID | 해설 언어의 언어 식별자.
Description | 컴퍼넌트의 설명.
Status | 컴퍼넌트 상태.
Type | 컴퍼넌트의 타입.

Component.Clone 메소드

Component 오브젝트

컴퍼넌트를 카피한다.

구문

Component. Clone()

반환값

현재의 오브젝트의 카피인 Component 오브젝트를 돌려준다.

Component.DescLangID 프로퍼티.

Component 오브젝트

해설 언어의 언어 식별자.

구문

Component. DescLangID

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

Component.Description 프로퍼티

Component 오브젝트

컴퍼넌트의 설명.

구문

Component. Description

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

Component.Status 프로퍼티

Component 오브젝트

컴퍼넌트 상태.

구문

Component. Status

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

Component.Type 프로퍼티

Component 오브젝트

컴퍼넌트의 타입.

구문

Component. Type

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.


Components 오브젝트

Component 오브젝트의 콜렉션을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
Add | 컴퍼넌트를 콜렉션에 추가한다.
Clone | 이 오브젝트의 새로운 카피를 생성 한다.
Count | 콜렉션에 포함되는 항목의 수.
Item | 지정된 인덱스 위치의 컴퍼넌트를 취득한다.
Remove | 지정된 인덱스 위치의 컴퍼넌트를 삭제한다.

Components.Add 메소드

Components 오브젝트

컴퍼넌트를 콜렉션에 추가한다.

구문

Components. Add(Component)

파라미터

Component 콜렉션에 추가하는 Component 오브젝트.

반환값

성공했을 경우는, 새롭게 추가한 오브젝트의 인덱스값을 돌려준다.

주의

참조

Components.Clone 메소드

Components 오브젝트

이 오브젝트의 새로운 카피를 생성 한다.

구문

Components. Clone

주의

참조

Components.Count 프로퍼티

Components 오브젝트

콜렉션에 포함되는 항목의 수.

구문

Components. Count

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

참조

Components.Item 프로퍼티

Components 오브젝트

지정된 인덱스 위치의 컴퍼넌트를 취득한다.

구문

Components. Item(Index,ppComponent)

파라미터

Index 취득하는 항목의 인덱스.

가능한 값

Component 오브젝트를 돌려준다.

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

참조

Components.Remove 메소드

Components 오브젝트

지정된 인덱스 위치의 컴퍼넌트를 삭제한다.

구문

Components. Remove(Index)

파라미터

Index 콜렉션으로부터 삭제하는 Component 오브젝트의 인덱스값.

반환값

주의

참조


ComponentType 오브젝트

DVB 프로그램 스트림에서는, 오디오 스트림등의 기본 스트림을 컴퍼넌트라고 말한다. 이 기본 스트림의 프로퍼티를 기술하는 것이 ComponentType 오브젝트이다.

메소드명 또는 프로퍼티명 | 설명
Category | 컴퍼넌트의 일반 카테고리.
Clone | 이 컴포넌트 타입의 카피를 생성 한다.
MediaFormatType | DirectShow 미디어 타입의 포맷 GUID.
MediaMajorType | DirectShow 미디어 타입의 메이저 타입 GUID.
MediaSubType | DirectShow 미디어 타입의 서브 타입 GUID.

ComponentType.Category 프로퍼티

ComponentType 오브젝트

컴퍼넌트의 일반 카테고리.

구문

ComponentType. Category

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조

ComponentType.Clone 메소드

ComponentType 오브젝트

이 컴포넌트 타입의 카피를 생성 한다.

구문

ComponentType. Clone();

반환값

현재의 오브젝트와 같은 값을 가지는 새로운 ComponentType 오브젝트를 돌려준다.

주의

참조

ComponentType.MediaFormatType 프로퍼티

ComponentType 오브젝트

DirectShow 미디어 타입의 포맷 GUID.

구문

ComponentType. MediaFormatType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조

ComponentType.MediaMajorType 프로퍼티

ComponentType 오브젝트

DirectShow 미디어 타입의 메이저 타입 GUID.

구문

ComponentType. MediaMajorType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조

ComponentType.MediaSubType 프로퍼티

ComponentType 오브젝트

DirectShow 미디어 타입의 서브 타입 GUID.

구문

ComponentType. MediaSubType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조


ComponentTypes 오브젝트

ComponentType 오브젝트의 콜렉션을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
Add | ComponentType 를 콜렉션에 추가한다.
Clone | 이 오브젝트의 새로운 카피를 생성 한다.
Count | 콜렉션에 포함되는 항목의 수.
Item | 지정된 인덱스 위치의 ComponentType 를 취득한다.
Remove | 콜렉션을 소거한다.

ComponentTypes.Add 메소드

ComponentTypes 오브젝트

ComponentType 를 콜렉션에 추가한다.

구문

ComponentTypes. Add(ComponentType)

파라미터

ComponentType 콜렉션에 추가하는 ComponentType 오브젝트.

반환값

성공했을 경우는, 새롭게 추가한 오브젝트의 인덱스값을 돌려준다.

주의

참조

ComponentTypess.Clone 메소드

ComponentTypes 오브젝트

이 오브젝트의 새로운 카피를 생성 한다.

구문

ComponetTypes. Clone

ComponentTypes.Count 프로퍼티

ComponentTypes 오브젝트

콜렉션에 포함되는 항목의 수.

구문

ComponentTypes. Count

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

참조

ComponentTypes.Item 프로퍼티

ComponentTypes 오브젝트

지정된 인덱스 위치의 ComponentType 를 취득한다.

구문

ComponentTypes. Item(Index,ComponentType)

파라미터

Index 콜렉션에 포함되는 ComponentType 오브젝트의 인덱스.

가능한 값

ComponentType 오브젝트를 돌려준다.

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조

ComponentTypes.Remove 메소드

ComponentTypes 오브젝트

콜렉션을 소거한다.

구문

ComponentTypes. Remove(Index)

파라미터

Index 삭제하는 ComponentType 오브젝트의 인덱스.

반환값

주의

참조


DVBSLocator 오브젝트

DVBS 네트워크 타입용의 locator 오브젝트.

메소드명 또는 프로퍼티명 | 설명
Azimuth | 방위각 (1/10о단위).
CarrierFrequency | 캐리어 주파수 (십 Hz).
Clone | locator를 카피한다.
Elevation | 위성의 앙각 (1/10о단위).
InnerFEC | 내부 FEC 타입.
InnerFECRate | 내부 FEC 레이트.
Modulation | 변조 타입.
OrbitalPosition | 경도 (1/10о단위).
OuterFEC | 외부 FEC 타입.
OuterFECRate | 외부 FEC 레이트.
SignalPolarisation | 신호의 포라리제이션타이프.
SymbolRate | QPSK 심볼 레이트를 세트 혹은 취득한다.
WestPosition | VARIANT_TRUE 는 궤도 위치를 서경으로 표현하는 것을 의미한다.

DVBSLocator.Azimuth 프로퍼티

DVBSLocator 오브젝트

방위각 (1/10о단위).

구문

DVBSLocator. Azimuth

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBSLocator.CarrierFrequency 프로퍼티

DVBSLocator 오브젝트

캐리어 주파수 (십 Hz).

구문

DVBSLocator. CarrierFrequency

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBSLocator.Clone 메소드

DVBSLocator 오브젝트

locator를 카피한다.

구문

DVBSLocator. Clone()

반환값

현재의 오브젝트의 카피인 DVBSLocator 오브젝트를 돌려준다.

DVBSLocator.Elevation 프로퍼티

DVBSLocator 오브젝트

위성의 고도 (1/10о단위).

구문

DVBSLocator. Elevation

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBSLocator.InnerFEC 프로퍼티

DVBSLocator 오브젝트

내부 FEC 타입.

구문

DVBSLocator. InnerFEC

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBSLocator.InnerFECRate 프로퍼티

DVBSLocator 오브젝트

내부 FEC 레이트.

구문

DVBSLocator. InnerFECRate

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

DVBSLocator.Modulation 프로퍼티

DVBSLocator 오브젝트

변조 타입.

구문

DVBSLocator. Modulation

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBSLocator.OrbitalPosition 프로퍼티

DVBSLocator 오브젝트

경도 (1/10о단위).

구문

DVBSLocator. OrbitalPosition

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBSLocator.OuterFEC 프로퍼티

DVBSLocator 오브젝트

외부 FEC 타입.

구문

DVBSLocator. OuterFEC

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBSLocator.OuterFECRate 프로퍼티

DVBSLocator 오브젝트

외부 FEC 레이트.

구문

DVBSLocator. OuterFECRate

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBSLocator.SignalPolarisation 프로퍼티

DVBSLocator 오브젝트

신호의 포라리제이션타이프.

구문

DVBSLocator. SignalPolarisation

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBSLocator.SymbolRate 프로퍼티

DVBSLocator 오브젝트

QPSK 심볼 레이트를 세트 혹은 취득한다.

구문

DVBSLocator. SymbolRate

주의

이 프로퍼티는 읽고 쓰기 가능한 프로퍼티이다. QPSK 는 RF 신호에 심볼을 변조한다. 이러한 심볼은 원상회복기에 의해 검출되어 비트 스트림을 재구축 하는데 사용된다. OPSK 는 변경을 위해서(때문에) 변조/복조되는 레이트를 허가한다.

DVBSLocator.WestPosition 프로퍼티

DVBSLocator 오브젝트

VARIANT_TRUE 는 궤도 위치를 서경으로 표현하는 것을 의미한다.

구문

DVBSLocator. WestPosition

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.


DVBTLocator 오브젝트

DVBT 네트워크 타입용의 locator 오브젝트.

메소드명 또는 프로퍼티명 | 설명
Bandwidth | 대역폭.
CarrierFrequency | 캐리어 주파수 (십 Hz).
Clone | locator를 카피한다.
Guard | 가이드 간격.
HAlpha | 계층장 알파.
InnerFEC | 내부 FEC 타입.
InnerFECRate | 내부 FEC 레이트.
InnerFECRate | 내부 FEC 레이트.
LPInnerFEC | 우선도가 낮은 스트림의 내부 FEC 타입.
LPInnerFECRate | 우선도가 낮은 스트림의 내부 FEC 레이트.
Mode | 전송 모드.
Modulation | 변조 타입.
OtherFrequencyInUse | 계층장 알파.
OuterFEC | 외부 FEC 타입.
OuterFECRate | 외부 FEC 레이트.
SymbolRate | QPSK 심볼 레이트를 세트 혹은 취득한다.

DVBTLocator.Bandwidth 프로퍼티

DVBTLocator 오브젝트

대역폭.

구문

DVBTLocator. Bandwidth

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.CarrierFrequency 프로퍼티

DVBTLocator 오브젝트

캐리어 주파수 (십 Hz).

구문

DVBTLocator. CarrierFrequency

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.Clone 메소드

DVBTLocator 오브젝트

locator를 카피한다.

구문

DVBTLocator. Clone()

반환값

현재의 오브젝트의 카피인 DVBTLocator 오브젝트를 돌려준다.

DVBTLocator.Guard 프로퍼티

DVBTLocator 오브젝트

가이드 간격.

구문

DVBTLocator. Guard

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.HAlpha 프로퍼티

DVBTLocator 오브젝트

계층장 알파.

구문

DVBTLocator. HAlpha

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.InnerFEC 프로퍼티

DVBTLocator 오브젝트

내부 FEC 타입.

구문

DVBTLocator. InnerFEC

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.InnerFECRate 프로퍼티

DVBTLocator 오브젝트

내부 FEC 레이트.

구문

DVBTLocator. InnerFECRate

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

DVBTLocator.InnerFECRate 프로퍼티

DVBTLocator 오브젝트

내부 FEC 레이트.

구문

DVBTLocator. InnerFECRate

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

DVBTLocator.LPInnerFEC 프로퍼티

DVBTLocator 오브젝트

우선도가 낮은 스트림의 내부 FEC 타입.

구문

DVBTLocator. LPInnerFEC

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.LPInnerFECRate 프로퍼티

DVBTLocator 오브젝트

우선도가 낮은 스트림의 내부 FEC 레이트.

구문

DVBTLocator. LPInnerFECRate

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.Mode 프로퍼티

DVBTLocator 오브젝트

전송 모드.

구문

DVBTLocator. Mode

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.Modulation 프로퍼티

DVBTLocator 오브젝트

변조 타입.

구문

DVBTLocator. Modulation

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.OtherFrequencyInUse 프로퍼티

DVBTLocator 오브젝트

계층장 알파.

구문

DVBTLocator. OtherFrequencyInUse

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.OuterFEC 프로퍼티

DVBTLocator 오브젝트

외부 FEC 타입.

구문

DVBTLocator. OuterFEC

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.OuterFECRate 프로퍼티

DVBTLocator 오브젝트

외부 FEC 레이트.

구문

DVBTLocator. OuterFECRate

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTLocator.SymbolRate 프로퍼티

DVBTLocator 오브젝트

QPSK 심볼 레이트를 세트 혹은 취득한다.

구문

DVBTLocator. SymbolRate

주의

이 프로퍼티는 읽고 쓰기 가능한 프로퍼티이다. QPSK 는 RF 신호에 심볼을 변조한다. 이러한 심볼은 원상회복기에 의해 검출되어 비트 스트림을 재구축 하는데 사용된다. OPSK 는 변경을 위해서(때문에) 변조/복조되는 레이트를 허가한다.


DVBTuneRequest 오브젝트

DVB 네트워크 타입용의 유효한 튜닝 요구를 나타낸다.

메소드명 또는 프로퍼티명 | 설명
Clone | 이 튜닝 요구의 새로운 카피를 생성 한다.
Components | 컴퍼넌트의 콜렉션.
Locator | locator 오브젝트.
ONID | 원의 네트워크 ID.
SID | 서비스 ID.
TSID | 트랜스폴트 스트림 ID.
TuningSpace | 튜닝 공간 오브젝트.

DVBTuneRequest.Clone 메소드

DVBTuneRequest 오브젝트

이 튜닝 요구의 새로운 카피를 생성 한다.

구문

DVBTuneRequest. Clone()

반환값

현재의 오브젝트의 카피인 DVBTuneRequest 오브젝트를 돌려준다.

DVBTuneRequest.Components 프로퍼티

DVBTuneRequest 오브젝트

컴퍼넌트의 콜렉션.

구문

DVBTuneRequest. Components

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

DVBTuneRequest.Locator 프로퍼티

DVBTuneRequest 오브젝트

locator 오브젝트.

구문

DVBTuneRequest. Locator

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTuneRequest.ONID 프로퍼티

DVBTuneRequest 오브젝트

원의 네트워크 ID.

구문

DVBTuneRequest. ONID

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTuneRequest.SID 프로퍼티

DVBTuneRequest 오브젝트

서비스 ID.

구문

DVBTuneRequest. SID

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTuneRequest.TSID 프로퍼티

DVBTuneRequest 오브젝트

트랜스폴트 스트림 ID.

구문

DVBTuneRequest. TSID

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTuneRequest.TuningSpace 프로퍼티

DVBTuneRequest 오브젝트

튜닝 공간 오브젝트.

구문

DVBTuneRequest. TuningSpace

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.


DVBTuningSpace 오브젝트

DVB 네트워크 타입의 튜닝 공간을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
CLSID | 튜닝 공간의 CLSID 를 취득한다.
CreateTuneRequest | DVBTuneRequest 오브젝트를 생성 한다.
DefaultLocator | 인스톨 후에 튜너를 사용할 수 있는 초기의 디폴트 locator를 설정 또는 취득한다.
DefaultPreferredComponentTypes | 유저 또는 어플리케이션으로부터 지정된 디폴트의 우선 컴포넌트 타입이 들어간 Components 콜렉션 오브젝트.
FrequencyMapping | 네트워크 프로바이더가 정의하는 채널과 주파수의 매핑이 들어간 캐릭터 라인을 설정 또는 취득한다.
FriendlyName | 튜닝 공간의 프렌들리명.
NetworkType | 네트워크 타입 (CLSID).
SystemType | DVB 시스템의 타입.
UniqueName | 튜닝 공간의 고유의 명칭.

DVBTuningSpace.CLSID 프로퍼티

DVBTuningSpace 오브젝트

튜닝 공간의 CLSID 를 취득한다.

구문

DVBTuningSpace. CLSID

가능한 값

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

DVBTuningSpace.CreateTuneRequest 메소드

DVBTuningSpace 오브젝트

DVBTuneRequest 오브젝트를 생성 한다.

구문

DVBTuningSpace. CreateTuneRequest()

반환값

DVBTuneRequest 오브젝트를 돌려준다.

DVBTuningSpace.DefaultLocator 프로퍼티

DVBTuningSpace 오브젝트

인스톨 후에 튜너를 사용할 수 있는 초기의 디폴트 Locator 오브젝트를 설정 또는 취득한다.

구문

DVBTuningSpace. DefaultLocator

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTuningSpace.DefaultPreferredComponentTypes 프로퍼티

DVBTuningSpace 오브젝트

유저 또는 어플리케이션으로부터 지정된 디폴트의 우선 컴포넌트 타입이 들어간 Components 콜렉션 오브젝트.

구문

DVBTuningSpace. DefaultPreferredComponentTypes

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTuningSpace.FrequencyMapping 프로퍼티

DVBTuningSpace 오브젝트

네트워크 프로바이더가 정의하는 채널과 주파수의 매핑이 들어간 캐릭터 라인을 설정 또는 취득한다.

구문

DVBTuningSpace. FrequencyMapping

가능한 값

네트워크 프로바이더가 정의한 매핑 테이블이 저장 된 캐릭터 라인.

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다. 이 캐릭터 라인에는, 주파수와 채널의 매핑, 주파수와 중계기의 매핑, 또는 캐리어 주파수로부터 주파수 식별자에의, 튜닝 공간에 적절한 그 외의 모든 매핑을 저장 할 수 있다.

DVBTuningSpace.FriendlyName 프로퍼티

DVBTuningSpace 오브젝트

튜닝 공간의 프렌들리명.

구문

DVBTuningSpace. FriendlyName

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTuningSpace.NetworkType 프로퍼티

DVBTuningSpace 오브젝트

네트워크 타입 (CLSID).

구문

DVBTuningSpace. NetworkType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTuningSpace.SystemType 프로퍼티

DVBTuningSpace 오브젝트

DVB 시스템의 타입.

구문

DVBTuningSpace. SystemType

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

DVBTuningSpace.UniqueName 프로퍼티

DVBTuningSpace 오브젝트

튜닝 공간의 고유의 명칭.

구문

DVBTuningSpace. UniqueName

가능한 값

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.


LanguageComponentType 오브젝트

브로드캐스트 스트림에 포함되는 단독 컴퍼넌트 (서브 스트림)의 언어 컴포넌트 타입을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
Category | 컴퍼넌트의 일반 카테고리.
Clone | 이 컴포넌트 타입의 카피를 생성 한다.
LangID | 서브 스트림 컨텐츠의 언어를 나타내는 언어 식별자.

LanguageComponentType.Category 프로퍼티

LanguageComponentType 오브젝트

컴퍼넌트의 일반 카테고리.

구문

LanguageComponentType. Category

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

LanguageComponentType.Clone 메소드

LanguageComponentType 오브젝트

이 컴포넌트 타입의 카피를 생성 한다.

구문

LanguageComponentType. Clone()

반환값

현재의 오브젝트의 카피인 LanguageComponentType 오브젝트를 돌려준다.

LanguageComponentType.LangID 프로퍼티

LanguageComponentType 오브젝트

서브 스트림 컨텐츠의 언어를 나타내는 언어 식별자.

구문

LanguageComponentType. LangID

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.


MPEG2Component 오브젝트

MPEG-2 브로드캐스트 스트림에 포함되는 단독의 컴퍼넌트 (서브 스트림)를 나타낸다.

메소드명 또는 프로퍼티명 | 설명
Clone | 컴퍼넌트를 카피한다.
DescLangID | 해설 언어의 언어 식별자.
Description | 컴퍼넌트의 설명.
PCRPID | 이 서브 스트림의 타임 스탬프에 대응하는 MPEG2 패킷 ID.
PID | 이 서브 스트림의 MPEG2 패킷 ID.
ProgramNumber | MPEG2 의 프로그램 번호.
Status | 컴퍼넌트 상태.
Type | 컴퍼넌트의 타입.

MPEG2Component.Clone 메소드

MPEG2Component 오브젝트

컴퍼넌트를 카피한다.

구문

MPEG2Component. Clone()

반환값

현재의 오브젝트의 카피인 MPEG2Component 오브젝트를 돌려준다.

MPEG2Component.DescLangID 프로퍼티

MPEG2Component 오브젝트

해설 언어의 언어 식별자.

구문

MPEG2Component. DescLangID

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

MPEG2Component.Description 프로퍼티

MPEG2Component 오브젝트

컴퍼넌트의 설명.

구문

MPEG2Component. Description

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

MPEG2Component.PCRPID 프로퍼티

MPEG2Component 오브젝트

이 서브 스트림의 타임 스탬프에 대응하는 MPEG2 패킷 ID.

구문

MPEG2Component. PCRPID

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

MPEG2Component.PID 프로퍼티

MPEG2Component 오브젝트

이 서브 스트림의 MPEG2 패킷 ID.

구문

MPEG2Component. PID

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

MPEG2Component.ProgramNumber 프로퍼티

MPEG2Component 오브젝트

MPEG2 의 프로그램 번호.

구문

MPEG2Component. ProgramNumber

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

MPEG2Component.Status 프로퍼티

MPEG2Component 오브젝트

컴퍼넌트 상태.

구문

MPEG2Component. Status

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

MPEG2Component.Type 프로퍼티

MPEG2Component 오브젝트

컴퍼넌트의 타입.

구문

MPEG2Component. Type

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.


MPEG2ComponentType 오브젝트

MPEG-2 스트림에 포함되는 단독 컴퍼넌트의 스트림 타입을 나타낸다.

메소드명 또는 프로퍼티명 | 설명
Category | 컴퍼넌트의 일반 카테고리.
Clone | 이 컴포넌트 타입의 카피를 생성 한다.
LangID | 서브 스트림 컨텐츠의 언어를 나타내는 언어 식별자.
StreamType | MPEG2 의 스트림 타입.

MPEG2ComponentType.Category 프로퍼티

MPEG2ComponentType 오브젝트

컴퍼넌트의 일반 카테고리.

구문

MPEG2ComponentType. Category

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

MPEG2ComponentType.Clone 메소드

MPEG2ComponentType 오브젝트

이 컴포넌트 타입의 카피를 생성 한다.

구문

MPEG2ComponentType. Clone()

반환값

현재의 오브젝트의 카피인 MPEG2ComponentType 오브젝트를 돌려준다.

MPEG2ComponentType.LangID 프로퍼티

MPEG2ComponentType 오브젝트

서브 스트림 컨텐츠의 언어를 나타내는 언어 식별자.

구문

MPEG2ComponentType. LangID

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

MPEG2ComponentType.StreamType 프로퍼티

MPEG2ComponentType 오브젝트

MPEG2 의 스트림 타입.

구문

MPEG2ComponentType. StreamType

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.


SystemTuningSpaces 오브젝트

SystemTuningSpaces 오브젝트에는, 로컬 시스템상에서 현재 이용 가능한 전튜닝 공간의 콜렉션이 저장 된다. 또, 이 오브젝트는, 새로운 튜닝 공간을 추가하거나 기존의 튜닝 공간을 삭제하거나 하는 메소드를 제공한다.

메소드명 또는 프로퍼티명 | 설명
Add | 콜렉션에 새로운 튜닝 공간을 추가한다. 이 튜닝 공간은 삭제될 때까지 지속한다.
Count | 콜렉션에 포함되는 항목의 수.
FindID | 지정된 튜닝 공간의 로컬인 ID 번호를 검색한다.
Item | 지정된 인덱스를 가지는 튜닝 공간을 검색하는지, 또는 콜렉션에 포함되는 기존의 튜닝 공간을 갱신한다.
MaxCount | 콜렉션내에서 용서되는 항목의 최대수를 취득한다.
Remove | 콜렉션으로부터 튜닝 공간을 삭제한다. 이 튜닝 공간은 레지스트리로부터 삭제된다.
TuningSpacesForCLSID | 같은 이행을 가지는 튜닝 공간의 콜렉션을 돌려준다.
TuningSpacesForName | 이름에 일치하는 튜닝 공간의 콜렉션을 돌려준다.

SystemTuningSpaces.Add 메소드

SystemTuningSpaces 오브젝트

콜렉션에 새로운 튜닝 공간을 추가한다. 이 튜닝 공간은 삭제될 때까지 지속한다.

구문

SystemTuningSpaces. Add(TuningSpace)

파라미터

TuningSpace 추가하는 튜닝 공간 오브젝트 (ATSCTuningSpace, DVBTuningSpace 등).

반환값

성공했을 경우는, 새롭게 추가한 오브젝트의 인덱스를 돌려준다.

SystemTuningSpaces.Count 프로퍼티

SystemTuningSpaces 오브젝트

콜렉션에 포함되는 항목의 수.

구문

SystemTuningSpaces. Count

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

SystemTuningSpaces.FindID 메소드

SystemTuningSpaces 오브젝트

지정된 튜닝 공간의 로컬 일의 식별자를 검색한다.

구문

SystemTuningSpaces. FindID(TuningSpace)

파라미터

TuningSpace 식별자를 취득하는 오브젝트.

반환값

성공했을 경우는, 지정된 오브젝트의 식별자를 돌려준다.

SystemTuningSpaces.Item 프로퍼티

SystemTuningSpaces 오브젝트

지정된 인덱스를 가지는 튜닝 공간을 검색하는지, 또는 콜렉션에 포함되는 기존의 튜닝 공간을 갱신한다.

구문

SystemTuningSpaces. Item(varIndex)

파라미터

varIndex 설정 또는 취득하는 튜닝 공간 오브젝트의 인덱스.

가능한 값

임의의 유효한 튜닝 공간 오브젝트 (ATSCTuningSpace, DVBTuningSpace 등).

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다. 튜닝 공간 오브젝트를 설정 하면, 변경 내용이 배킹 스토어에 지속적으로 보존된다.

SystemTuningSpaces.MaxCount 프로퍼티

SystemTuningSpaces 오브젝트

콜렉션내에서 용서되는 항목의 최대수를 취득한다.

구문

SystemTuningSpaces. MaxCount

주의

이 프로퍼티는, 스크립트로부터는 독해 전용이다. C++ 어플리케이션에서는, 이 값을 수정하는 일도, 레지스트리내에서 수정할 수도 있다.

SystemTuningSpaces.Remove 프로퍼티

SystemTuningSpaces 오브젝트

콜렉션으로부터 튜닝 공간을 삭제한다. 이 튜닝 공간은 레지스트리로부터 삭제된다.

구문

SystemTuningSpaces. Remove

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

SystemTuningSpaces.TuningSpacesForCLSID 메소드

SystemTuningSpaces 오브젝트

같은 이행을 가지는 튜닝 공간의 콜렉션을 돌려준다.

구문

SystemTuningSpaces. TuningSpacesForCLSID(SpaceCLSID)

파라미터

SpaceCLSID 검색하는 튜닝 공간의 CLSID.

반환값

성공했을 경우는, CLSID 에 일치하는 튜닝 공간 오브젝트의 콜렉션이 저장 된 SystemTuningSpaces 오브젝트를 돌려준다.

SystemTuningSpaces.TuningSpacesForName 메소드

SystemTuningSpaces 오브젝트

이름에 일치하는 튜닝 공간의 콜렉션을 돌려준다.

구문

SystemTuningSpaces. TuningSpacesForName(Name)

파라미터

Name 검색하는 튜닝 공간의 로컬인 고유의 명칭.

반환값

성공했을 경우는, 지정된 이름에 일치하는 튜닝 공간이 저장 된 SystemTuningSpaces 오브젝트를 돌려준다.


DirectShow 필터의 개발

Microsoft® DirectShow® 필터 그래프로 사용하는 필터의 개발은, 이 섹션의 주제에 따라 실시한다. 일반적으로, 어플리케이션은 여기서 설명하는 것 같은 레벨로 필터나 필터 그래프에 액세스 할 것은 없기 때문에, 어플리케이션 개발자가 이러한 주제를 참조할 필요는 없다.

  • 필터 개발자를 위한 DirectShow 아키텍쳐
  • DirectShow 와 COM
  • 변환 필터
  • 비디오 렌더러
  • 캡춰 필터
  • 캡춰 포맷과 압축 포맷의 공개
  • 필터의 카테고리
  • 파일 포맷


필터 개발자를 위한 DirectShow 아키텍쳐

이 섹션에서는, Microsoft® DirectShow® 아키텍쳐를 필터 개발자전용의 상세한 레벨로 설명한다. 이 섹션의 토픽을 읽기 전에, 「퍼스트 스텝 가이드」를 참조할것. DirectShow 어플리케이션을 개발할 때에 필터의 개발을 실시하지 않는 경우는, 이 섹션을 날리는지, 대충 대충 훑어보는 정도에서도 문제는 없다.

  • 필터의 접속
  • 필터 개발자가 사용하는 데이터 플로우
  • DirectShow 의 타임과 클락
  • 품질 컨트롤의 관리


필터의 접속

여기에서는, Microsoft® DirectShow® 으로 필터가 어떻게 접속될까에 임해서 설명한다. 이 주제는 필터의 개발자를 대상으로 하고 있다. DirectShow 어플리케이션을 생성 하고 있는 경우, 이 주제의 상세 설명은 반드시 중요하지 않다.

여기에서는, 이하의 항목에 대해 설명한다.

  • 핀 접속
  • 미디어 타입의 조정
  • allocater의 조정
  • 핀의 재접속

핀 접속

필터는 IPin 인터페이스를 개입시켜 핀으로 접속된다. 출력 핀은 입력 핀에 접속한다. 각 핀 접속에는 미디어 타입이 있어,AM_MEDIA_TYPE 구조체에 기술된다.

어플리케이션은, 필터 그래프 매니저로 메소드를 호출하는 것으로, 필터에 접속한다. 필터나 핀 자체에 메소드를 호출하지는 않는다. 어플리케이션은,IFilterGraph::ConnectDirect 메소드나 IGraphBuilder::Connect 메소드를 호출하는 것으로 접속하는 필터를 직접 지정할 수 있다. 또,IGraphBuilder::RenderFile 등의 그래프 구축 메소드의 어느쪽이든을 사용해, 간접적으로 필터에 접속할 수도 있다.

정상적으로 접속하기 위해서, 양쪽 모두의 필터가 필터 그래프내에 없으면 안 된다. 어플리케이션은,IFilterGraph::AddFilter 메소드를 호출하는 것으로, 필터를 필터 그래프에 추가할 수 있다. 필터 그래프 매니저도, 필터를 생성 해 필터 그래프에 추가할 수 있다. 어느 쪽의 경우도, 필터 그래프 매니저는 필터의 IBaseFilter::JoinFilterGraph 메소드를 호출해 필터에 통지한다.

대범한 접속 프로세스는 다음과 같이 된다.

  1. 필터 그래프 매니저가 출력 핀에 대해서 IPin::Connect 를 호출해, 입력 핀에의 포인터를 건네준다.
  2. 출력 핀이 접속을 받아들이는 경우, 입력 핀에 대해서 IPin::ReceiveConnection 를 호출한다.
  3. 입력 핀도 접속을 받아들이는 경우, 접속이 성공해, 핀이 접속된다.

일부의 핀은, 필터가 액티브한 사이에서도 접속 해제나 재접속이 가능하다. 이러한 재접속은동적재접속으로 불린다. 상세한 것에 대하여는, 「동적 그래프 생성」을 참조할것. 다만, 많은 필터는 동적재접속을 지원 하고 있지 않다.

필터는 보통, 다운 스트림순서에 접속된다. 즉 필터의 출력 핀의 전에 입력 핀이 접속된다. 필터는 항상 이 순서에서의 접속을 지원 할 필요가 있다. 일부의 필터는 역순서의 접속도 지원 하고 있다. 즉, 출력 핀이 앞으로, 그 후에 입력 핀이 접속된다. 예를 들어, MUX 필터의 입력 핀을 접속하기 전에, MUX 필터의 출력 핀을 필터 라이터 필터에 접속할 수가 있다.

미디어 타입의 조정

필터 그래프 매니저가 IPin::Connect 메소드를 호출하면나무에, 다음의 옵션으로 미디어 타입을 지정한다.

  • 완전한 타입: 미디어 타입이 상세하게 지정되고 있는 경우, 핀은 그 타입에서의 접속을 시도한다. 접속할 수 없는 경우, 접속은 실패한다.
  • 불완전한 미디어 타입: 메이저 타입, 서브 타입, 또는 포맷 타입중 한쪽이 GUID_NULL 인 경우, 미디어 타입은불완전이다. 값 GUID_NULL 는, 임의의 값을 받아들이고 가능한 것을 나타내는 "와일드 카드 " 로서 기능한다. 핀은 그 불완전한 타입에 일치하는 타입을 결정한다.
  • 미디어 타입 없음: 필터 그래프 매니저가 NULL 포인터를 건네주는 경우, 핀은 양쪽 모두의 핀으로 받아들이고 가능한 임의의 미디어 타입을 사용할 수 있다.

핀이 실제로 접속 하면, 접속은 항상 완전한 미디어 타입을 가진다. 필터 그래프 매니저가 미디어 타입을 지정하는 목적은, 일어날 수 있는 접속 타입을 한정하는 것이다.

조정 프로세스중에, 출력 핀은 입력 핀의 IPin::ReceiveConnection 메소드를 호출하는 것으로, 미디어 타입을 제시한다. 입력 핀은, 제시된 타입의 받아들여 또는 거부를 선택할 수 있다. 입력 핀이 타입을 받아들일 때까지 이 프로세스가 반복해진다. 출력 핀이 모든 타입을 다 제시해 , 모두 거부되었을 경우, 접속은 실패한다.

제시하는 미디어 타입을 출력 핀이 어떻게 선택할까는, 이행에 의해 다르다. DirectShow base class에서는, 출력 핀이 입력 핀에 대해서 IPin::EnumMediaTypes 를 호출한다. 이 메소드는, 입력 핀의 우선 미디어 타입을 열거하는 열거자를 돌려준다. 이것에 실패 하면, 출력 핀은 출력 핀측의 우선 타입을 열거한다.

allocater의 조정

2 개의 핀이 접속 하면, 미디어 데이터를 교환하기 위한 구조가 필요하다. 이 구조는전송으로 불린다. 보통, DirectShow 아키텍쳐는 전송에 관해서 중립적이다. 2 개의 필터는, 양자가 지원 하는 임의의 전송 방법으로 접속하는 것에 합의할 수 있다.

가장 일반적인 전송은,로컬 메모리전송이다. 이 전송에서는, 미디어 데이터는 메인 메모리에 보관 유지된다. allocater로 불리는 오브젝트가, 메모리 버퍼의 할당을 담당한다. allocater는,IMemAllocator 인터페이스를 지원 한다(상세한 것에 대하여는, 「필터 그래프의 데이터 플로우」를 참조할것). 입력 핀은,IMemInputPin 인터페이스를 공개하는 것으로, 메인 메모리 전송을 지원 한다. 출력 핀은, 접속 프로세스중에 이 인터페이스를 문의한다.

양쪽 모두의 핀이 같은 allocater를 공유한다. 핀이 접속 하면, 어느 쪽의 핀이 allocater를 제공할까를 다음의 순서로 조정한다.

  1. 출력 핀이 IMemInputPin::GetAllocatorRequirements 를 호출한다 (생략 가능). 이 메소드는, 메모리 배치 등, 입력 핀의 버퍼 요건을 취득한다. 보통, 출력 핀은, 충분한 이유가 없는 한 입력 핀의 요구를 받아들이게 된다.
  2. 출력 핀이 IMemInputPin::GetAllocator 를 호출한다 (생략 가능). 이 메소드는, 입력 핀으로부터 allocater를 요구한다. 입력 핀은 allocater를 제공하는지, 제공할 수 없는 경우는 에러 코드를 돌려준다.
  3. 출력 핀이 allocater를 선택한다. 입력 핀으로부터 제공된 allocater를 사용하는지, 또는 출력 핀 자체가 allocater를 제공한다. 출력 핀이 IMemInputPin::NotifyAllocator 를 호출해, 입력 핀에 선택 결과를 통지한다.

이 프로세스로 필수적인의는 스텝 3 뿐이는 것에 주의 해야 한다.

필터가 다운 스트림 입력 핀으로부터의 allocater를 선택하는 경우, 필터는 그 입력 핀에 샘플을 제공하기 위해서 마셔, allocater를 사용할 필요가 있다. 이 allocater는, 다른 핀에 샘플을 제공하기 위해서 사용할 수 없다.

핀의 재접속

핀 접속중에, 필터는 다른 핀의 접속을 해제하거나 재접속하거나 해야 하는 것이 있다. 예를 들어 다음과 같은 경우이다.

  • 필터의 입력 핀이 있는 미디어 타입과 이미 접속되고 있는 경우, 출력 핀이 접속하려고 해도, 입력 타입과 호환성이 있는 미디어 타입이 발견되지 않는 것이 있다. 다운 스트림 접속을 실행하려면 , 필터는 입력 핀을 다른 타입으로 재접속할 필요가 있다.
  • 카피를 줄이기 위해서(때문에), 일부의 변환 필터는 데이터를 그 자리에서 변경한다(예에 대해서는 CTransInPlacerFilter base class를 참조할것). 이러한 필터는 독자적인 allocater를 준비하지 않는다. 출력 핀이 접속 하면, 필터는 입력 핀을 재접속해, 업 스트림 필터에 다운 스트림 필터의 allocater를 제공한다. 이와 같이, 3 개의 필터 모든 것이 1 개의 allocater를 공유하는 것으로, 버퍼의 합계 필요량이 최소화된다.

재접속하려면 , 필터는 필터 그래프 매니저에 대해서 IFilterGraph::Reconnect 또는 IFilterGraph2::ReconnectEx 를 호출한다. 필터 그래프 매니저는 비동기에게 핀의 접속 해제와 재접속을 실시한다. 미디어 타입을 지정하므로,ReconnectEx 메소드를 사용하는 것이 바람직하다. 미디어 타입을 지정하지 않는 경우, 재접속을 시작하는 필터가, 목적의 미디어 타입을 내부에 저장 할 필요가 있다.

필터는, 재접속이 성공하는 것이 확실하지 않은 한, 재접속을 시행해서는 안 된다. 재접속에 실패 하면, 핀은 접속이 해제된 채로 있어, 그래프 에러의 원인이 된다. 필터가 새로운 미디어 타입으로 재접속하는 경우는, 기존의 유효한 미디어 타입을 지정해야 한다. 불명한 경우는,IPin::QueryAccept 메소드를 호출한다.

또, 필터는, 같은 thread 위에의 IPin::Connect 메소드중에서 재접속을 요구할 필요가 있다. 어느 thread에 IPin::Connect 메소드가 돌려주어지고 있는 것에도 불구하고, 다른 thread로부터 재접속 요구를 하면(자), 필터 그래프 매니저는, 재접속을 실시하기 전에 그래프를 실행할 가능성이 있어, 그래프 에러의 원인이 된다.


필터 개발자가 사용하는 데이터 플로우

여기에서는, 데이터가 필터 그래프내를 어떻게 이동할까에 임해서 설명한다. 독자적인 커스텀 필터를 생성 하는 개발자를 대상으로 하고 있다. Microsoft® DirectShow® 에서의 데이터 플로우 처리의 개요에 대해서는, 「필터 그래프의 데이터 플로우」를 참조할것.

여기에서는,IMemInputPin 및 IMemAllocator 인터페이스를 사용한 로컬 메모리 전송에 대해 설명한다. 내용은 다음과 같다.

  • 푸쉬와 풀
  • 새로운 샘플의 생성
  • 샘플의 처리
  • 새로운 세그먼트(segment)
  • 스트림의 마지막
  • 플래시
  • thread와 크리티컬 섹션

푸쉬와 풀

소스 필터의 역할은, 데이터를 그래프에 읽어들이는 것이다. 소스 필터는, 푸쉬 모델 또는 프르모델의 몇개의 모델에 따른다.

  • 푸쉬 모델에서는, 소스 필터는 독자적인 thread로 샘플을 생성 해, 다운 스트림 필터에 송신한다. 다운 스트림 필터는 샘플을 처리해, 다음의 필터에 송신한다. 각 필터가 이 스텝을 반복해, 샘플은 렌더러에 도달한다.
  • 프르모델에서는, 소스 필터의 직후의 다운 스트림 필터가, 소스 필터에 데이터를 요구한다. 이 다운 스트림 필터는, 푸쉬 모델과 같게, 다음의 필터에 샘플을 송신한다.

비디오 카메라등의 라이브 소스에서는 푸쉬 모델이 일반적이다. 프르모델은 파일 리더로 일반적이고, 그 경우의 다운 스트림 필터는 AVI 스플리터 필터등의 파일 퍼서이다.

새로운 샘플의 생성

여기에서는, 소스 필터가 미디어 샘플을 생성하는 방법에 대해 설명한다.

푸쉬 모델

푸쉬 모델에서는, 소스 필터는 다음과 같이 처리를 시작 한다.

  1. 소스 필터는 IMemAllocator::GetBuffer 를 호출해, 하늘의 미디어 샘플을 취득한다.
  2. 소스 필터는, 취득한 하늘의 미디어 샘플에 데이터를 삽입한다. 삽입의 방법은, 소스의 종류에 의해 완전하게 다르다.
  3. 소스 필터는, 다운 스트림의 입력 핀에 대해서 IMemInputPin::Receive 를 호출해, 샘플의 IMediaSample 인터페이스에의 포인터를 건네준다.
  4. 다운 스트림 필터는,Receive 로부터 돌아오기 전에 샘플을 처리하든가, 혹은 샘플을 보류해 다음에 처리할 수가 있다. 필터를 보류하는 경우, 다운 스트림 필터는 샘플에 대해서 IUnknown::AddRef 를 호출한다.
  5. 소스 필터는, 샘플에 대해서 IUnknown::Release 를 호출한다.

이 시점에서, 다운 스트림 필터는 샘플의 참조 카운트를 보류해, 소스 필터가 간단하게 샘플을 재이용할 수 없게 한다. 다음의 샘플을 송신하려면 , 소스 필터는, 순서 1 에 나타낸 것처럼 IMemAlloctor::GetBuffer 를 한번 더 호출할 필요가 있다.

주 : 복수의 샘플을 송신하려면 , 소스 필터는 순서 3 으로 대신에 IMemInputPin::ReceiveMultiple 를 호출할 수가 있다.

프르모델

프르모델에서는, 퍼서 필터가 소스 필터에 데이터를 요구한다. 퍼서 필터는 소스 필터의 출력 핀에 대해서, 다음과 같이 IAsyncReader 인터페이스를 사용한다.

  1. 퍼서 필터는 IMemAllocator::GetBuffer 를 호출해, 하늘의 미디어 샘플을 취득한다.
  2. 퍼서 필터는 IAsyncReader::Request 를 호출해, 소스 필터에 데이터를 요구한다.
  3. 소스 필터가 데이터를 취득하는 동안, 퍼서는 IAsyncReader::WaitForNext 를 호출한다. 이 메소드는, 순서 2 의 요구가 완료할 때까지 대기한다.
  4. 퍼서 필터는 데이터를 처리해, 다운 스트림에 송신한다.

순서 2 ~ 3 으로 실행되는 것은 비동기 독해 조작이지만, 퍼서는,IAsyncReader::SyncRead 또는 IAsyncReader::SyncReadAligned 메소드를 사용해, 대신에 동기 독해 조작을 요구할 수도 있다.

샘플의 처리

필터의 입력 핀이 샘플을 받으면(자), 필터는 샘플에 포함되는 데이터를 처리해, 다음의 다운 스트림 필터에 샘플을 송신한다. 전의 「새로운 샘플의 생성」으로 설명한 것처럼, 필터는 Receive 메소드 중(안)에서 모든 처리를 실행하는지, 샘플을 보류해 다음에 처리할 수가 있다.

Receive 의 호출 중(안)에서, 입력 핀은 업 스트림 필터의 호출측 thread를 블록 하는 것이 가능하다. 입력 핀의 동작은,IMemInputPin::ReceiveCanBlock 메소드를 호출하는 것에 의해 확인할 수 있다. 반환값이 S_OK 인 경우, 입력 핀은 Receive 의 호출을 블록 한다. 반환값이 S_FALSE 인 경우, 입력 핀이 Receive 의 호출을 블록 할 것은 없다. 반환값에 근거해, 업 스트림 필터는 별개의 워커 thread를 사용해 샘플을 송신할 수 있다.

데이터를 카피하지 않고 샘플을 원의 장소에서 처리하는 필터도 있다. 데이터를 카피하고 나서 처리하는 필터도 있다. 당연한 일로서 불필요한 카피 조작에 의한 오버헤드를 피하기 위해서(때문에), 가능한 한 데이터를 원의 장소에서 처리하는 (분)편이 바람직하다.

입력 핀은,Receive 메소드로 에러 코드 또는 S_FALSE 를 돌려주는 것에 의해, 샘플을 거부할 수 있다. S_FALSE 라고 하는 값은, 핀이 데이터를 플래시 하는 것을 나타낸다 ( 「플래시」를 참조할것). 에러 코드는, 그것과는 다른 문제를 나타낸다. 예를 들어, 필터가 정지했을 경우, 반환값은 VFW_E_WRONG_STATE 가 된다. 핀이 샘플을 거부했을 경우, 필터는 접속되고 있는 입력 핀에 대해서 IPin::EndOfStream 메소드를 호출한다. 게다가 에러가 발생했을 경우, 필터는 필터 그래프 매니저에 EC_ERRORABORT 이벤트를 송신한다. 핀이 샘플을 거부한 후, 업 스트림 필터는 데이터의 송신을 정지한다. 데이터 송신은, 플래시가 완료한 후, 또는 그래프가 정지 후에 재기동한 시점에서 재개할 수 있다.

필터는 특정의 입력 핀에 대한 모든 Receive 호출을 계속해 처리할 필요가 있다.

새로운 세그먼트(segment)

새로운 각 스트림의 초에, 소스 필터 (또는 퍼서 필터)는 IPin::NewSegment 를 호출할 필요가 있다. 이 메소드는, 스트림의 시작 타임과 종료 타임을 원의 소스에 대해서 상대적으로 지정해, 재생 레이트를 지정한다. 필터는, 스트리밍 시작시, 및 시크 조작 후에 NewSegment 를 호출한다. 새로운 세그먼트(segment) 마다 스트림 시간은 제로에 리셋 되어 새로운 세그먼트(segment)의 뒤에 송신된 샘플에는 제로로부터 시작되는 타임 스탬프가 붙는다.

필터가 샘플을 올바르게 처리하기 위해서 세그먼트(segment) 정보가 필요한 경우도 있다. 예를 들어, MPEG-1 등의 포맷에서는, 중간 프레임을 구성하기 위해서 필터는 종료 타임 이후의 키 프레임을 필요로 한다. 세그먼트(segment) 정보는 필터에 실제의 종료 타임을 알린다. 필터가 세그먼트(segment) 정보를 사용할지 어떨지에 관계없이, 필터는 NewSegment 호출을 다운 스트림에 건네준다. NewSegment 호출은,Receive 등의 다른 스트리밍 호출과 함께 계속해 처리할 필요가 있다.

스트림의 마지막

소스 필터는, 송신하는 데이터가 없어지면(자), 다운 스트림의 입력 핀에 대해서 IPin::EndOfStream 메소드를 호출한다. 다운 스트림 필터는 이 호출을 다음의 필터에 전달한다. 마지막에는 EndOfStream 호출이 렌더링 필터에 도달한다. 렌더링 필터는 필터 그래프 매니저에 EC_COMPLETE 이벤트를 송신한다.

필터 그래프 매니저는, 어플리케이션에 EC_COMPLETE 통지를 즉시 전송 하는 것이 아니라, 모든 스트림으로부터 EC_COMPLETE 가 송신될 때까지 대기한다. 모든 스트림이 완료 하면, 어플리케이션은 EC_COMPLETE 통지를 받는다. 그래프내의 스트림의 수를 확인하기 위해서, 필터 그래프 매니저는 IMediaSeeking 또는 IMediaPosition 를 지원 해, 렌더링 된 입력 핀을 가지는 필터의 수를 카운트 한다. 렌더링 된 입력 핀은, 대응하는 출력이 없는 입력 핀이다. IPin::QueryInternalConnections 메소드는, 렌더링 된 입력 핀에 대해서는 0 을 돌려준다. 다른 옵션으로서 필터는 IAMFilterMiscFlags 인터페이스를 이행 해, AM_FILTER_MISC_FLAGS_IS_RENDERER 플래그를 돌려줄 수가 있다.

필터는,Receive 등의 다른 스트리밍 호출과 함께 EndOfStream 호출을 계속해 처리할 필요가 있다.

플래시

플래시는, 그래프내의 보류 상태의 샘플 모든 것을 파기하는 처리이다. 플래시는, 이벤트에 의해 정상적인 데이터 플로우가 변경되었을 때의 그래프의 응답을 개선한다. 예를 들어, 시크 조작에서는, 새로운 데이터가 읽히기 전에 낡은 데이터를 그래프로부터 플래시 한다. 그래프에 복수의 스트림이 포함되어 있는 경우는, 각 스트림을 따로 따로 플래시 하는 것이 가능하다.

플래시 처리에는 2 개의 단계가 있다.

  • 소스 필터가, 접속되고 있는 입력 핀에 대한 IPin::BeginFlush 를 호출한다. 거기에 응해, 다운 스트림 필터는 업 스트림으로부터의 샘플 수취를 정지한다. BeginFlush 의 호출이 다운 스트림에 전달되어 가 렌더러까지 도달한다.
  • 소스 필터는 입력 핀에 대한 IPin::EndFlush 를 호출한다. 보류 상태의 데이터가 스트림으로부터 플래시 되어 호출이 다운 스트림에 전달된다.

입력 핀의 BeginFlush 메소드를 호출하면 와, 필터는 다음의 동작을 실행한다.

  1. 다운 스트림의 입력 핀에 대한 BeginFlush 를 호출한다.
  2. Receive 나 EndOfStream 등, 데이터의 스트리밍을 실행하는 다음의 호출을 거부한다.
  3. 필터의 allocater로부터의 샘플을 기다려 블록 되고 있는 업 스트림 필터를 비블록으로 한다. 이 목적이기 때문에, 필터는 그 allocater를 데코밋트 하는 것이 많다.
  4. 스트리밍을 블록 하는 대기 상태를 종료한다. 예를 들어, 렌더링 필터는 포즈 하면 블록 한다. 게다가 올바른 스트림 타임에 샘플을 렌더링 하기 위해서 대기하고 있을 때도, 블록 한다. 필터는, 블록을 해제해, 업 스트림의 큐에 있는 샘플을 송신 및 거부할 수 있도록(듯이) 해야 한다. 이 순서에 의해, 스트리밍 체인내의 모든 필터가 최종적으로 블록 해제되는 것이 보증된다.

EndFlush 메소드를 호출하면 와, 필터는 다음의 동작을 실행한다.

  1. 큐에 있는 모든 샘플이 파기될 때까지 대기한다.
  2. 버퍼내의 데이터를 해방한다. 이 순서는 경우에 의해 BeginFlush 메소드로 실행하는 일도 가능하다. 다만,BeginFlush 는 스트리밍 thread와 동기화 되지 않는다. 필터는,BeginFlush 를 호출하고 나서 EndFlush 를 호출할 때까지 , 데이터를 처리하거나 버퍼에 넣을 수 없다.
  3. 보류 상태의 EC_COMPLETE 통지를 클리어 한다.
  4. 다운 스트림의 EndFlush 를 호출한다.

이 시점에서, 필터는 샘플의 수취를 재개할 수 있다. 모든 샘플은 플래시보다 새로운 일이 보증되고 있다.

프르모델에서는, 소스 필터는 아니고 퍼서 필터가 플래시를 시작 한다. 이벤트의 순서는 같지만, 소스 필터의 출력 핀에 대한 BeginFlush 및 EndFlush 도 퍼서가 호출한다.

thread와 크리티컬 섹션

DirectShow 어플리케이션에서는, 최저 2 개(살)의 중요한 thread가 동작하고 있다. 1 번째는 어플리케이션 thread이다. 이 thread는, 필터 그래프 상태의 변경을 시작 한다. 상태 변경에는, 그래프의 실행, 포즈, 및 정지, 핀의 접속과 접속 종료, 그래프에의 필터의 추가, 및 그래프로부터의 필터의 삭제가 있다. 2 번째의 중요한 thread는 스트리밍 thread이다. 핀은 스트리밍 thread내에서 샘플을 받아 송신한다. 어플리케이션 thread가 데이터 플로우를 중단하는 일 없이 블록 할 수 있도록(듯이) (예를 들어, 어플리케이션이 유저와 통신하는 동안), 별개의 스트리밍 thread가 필요하다.

필터는 thread를 생성 할 수도 있다. 예를 들어,IMemInputPin::Receive 메소드에서는, 필터는 즉시 돌아와 수신한 샘플을 다른 thread로 처리할 수 있다. 별개의 thread를 사용해, 송신 기다리는 샘플을 큐에 넣는 필터도 있다.

필터 조작은 multi-thread이기 (위해)때문에, 특정의 조작에서는, 필터가 조작을 계속해 처리하는 것이 매우 중요하다. 그렇게 하지 않으면 경합 상태가 발생할 가능성이 있다. 예를 들어, 다음에 나타내는 코드를 생각한다. 이 코드는 기준 클락의 유무를 확인해, 현재의 시각을 취득한다.

if (m_pClock ! = NULL)  // 기준 클락이 있을까?
{
    m_pClock->GetTime(&rtTimeNow);
    // 이하 코드 생략...
}

스트리밍 thread가 이 코드를 실행해, 코드는 프로텍트되어 있지 않다고 한다. if 스테이트먼트와 다음의 행의 사이에, 어플리케이션 thread가 IMediaFilter::SetSyncSource 를 호출해, 기준 클락을 NULL 로 설정하는 일이 있다. 그 결과, 스트리밍 thread는 NULL 포인터의 참조를 해제한다. 예외가 발생해, 어플리케이션은 크래쉬 한다.

경합 상태를 회피하기 위해서, 필터는 2 개의 크리티컬 섹션을 사용한다. 1 번째는 스트리밍 락이다. 스트리밍 락은 스트리밍 조작을 계속해 처리한다. 2 번째는 필터 락이다. 필터 락은 상태 변경을 계속해 처리해, 스테이트 정보의 정합성을 보호한다.

필터는 다음에 나타내는 메소드 호출을 처리할 경우에 스트리밍 락을 보관 유지한다.

  • IMemInputPin::Receive
  • IMemInputPin::ReceiveMultiple
  • IPin::EndOfStream
  • IPin::NewSegment

필터는 다음에 나타내는 타입의 호출을 처리할 경우에 필터 락을 보관 유지한다.

  • 상태 변경 : IBaseFilter::JoinFilterGraph ,IMediaFilter::Pause ,IMediaFilter::Run ,IMediaFilter::Stop ,IQualityControl::SetSink
  • 기준 클락 : IMediaFilter::GetSyncSource ,IMediaFilter::SetSyncSource
  • 핀 조작 : IBaseFilter::FindPin ,IPin::Connect ,IPin::ConnectedTo ,IPin::ConnectionMediaType ,IPin::Disconnect ,IPin::ReceiveConnection
  • allocater 함수 : IMemInputPin::GetAllocator ,IMemInputPin::NotifyAllocator
  • 플래시 : IPin::BeginFlush ,IPin::EndFlush

이 일람에 나타낸 호출이 모두는 아니다. 필터를 이행 하는 경우는, 필터 상태를 변경하는 메소드는 어떤 것인가, 및 스트리밍 조작을 실행하는 메소드는 어떤 것인지를 고려할 필요가 있다.

크리티컬 섹션은 잠재적으로 데드 록을 발생시킬 가능성이 있다. 데드 록을 회피하려면 , 스트리밍 메소드가 필터 락을 보관 유지해서는 안 된다. 이유는, 필터 그래프 상태 이행이 끝나지 않으면 완료하지 않는 스트리밍 조작이 존재하기 때문이다. 예를 들어 렌더러는, 포즈중은 Receive 호출을 블록 한다. 업 스트림 필터가 Receive 를 호출하면나무에 필터 락을 보관 유지 하면, 순환하는 대기 상태가 발생하는 경우가 있다. 스트리밍 thread는 그래프의 포즈 상태가 종료하는 것을 대기한다. 그러나, 어플리케이션 thread는 필터 락을 취득할 때까지 대기하기 위해(때문에), 그 상태 이행을 하는 것은 있을 수 없다.

다음의 그림은, 이 데드 록을 나타내고 있다.

필터의 데드 록

Stop 및 EndFlush 메소드에서는, 스트리밍 조작을 필터 상태와 동기화할 필요가 있다. 그렇게 하지 않으면 필터는 상태 이행 후도 낡은 샘플을 계속 송신하는 일이 있다. Stop 메소드에서는, 데드 록을 회피하도록(듯이) 주의할 필요가 있다. 최초로 필터 락을 보관 유지해, 입력 핀의 allocater를 데코밋트 한다. 다음에 스트리밍 락을 보관 유지한다. allocater를 데코밋트 하면,Receive 의 호출이 실패해, 따라 블록을 확실히 회피할 수 있다 (이행에 대해서는, 「CTransformFilter::Stop 」를 참조할것). 플래시 처리에서는,BeginFlush 메소드가 샘플의 취득을 시작 해,EndFlush 메소드가 스트리밍 락을 보관 유지한다.


DirectShow 의 타임과 클락

여기에서는, DirectShow® 아키텍쳐에 있어서의 타임과 클락에 대해 개설한다. 이 주제는, 이하의 섹션을 포함하고 있다.

  • 기준 클락
  • 클락 타임
  • 타임 스탬프와 미디어 타임
  • 라이브 소스

기준 클락

필터 그래프 매니저의 1 개의 기능으로서 그래프내의 필터를 동기화 시키는 일이 있다. 이 때문에, 필터 그래프 매니저와 필터는, 기준 클락으로 불리는 동일한 클락을 사용한다. IReferenceClock 인터페이스를 지원 하는 모든 오브젝트는 기준 클락으로서의 서비스를 제공할 수가 있다. 하드웨어 타이머에 액세스 하는 필터는, 클락을 제공하는 것이 성과 (예를 들어 오디오 렌더러), 필터 그래프 매니저는 시스템 타임을 사용하는 클락을 생성 할 수가 있다.

실행시, 필터 그래프 매니저는 기준 클락을 선택해, 모든 필터의 IMediaFilter::SetSyncSource 를 호출해 그 선택 내용을 통지한다. 어플리케이션은, 필터 그래프 매니저의 SetSyncSource 를 호출하는 것에 의해, 필터 그래프 매니저가 선택한 클락을 오버라이드(override) 할 수가 있다. 이 조작은, 다른 클락을 사용하는 명확한 이유가 있는 경우에게만 실시하는 것.

필터 그래프 매니저는, 이하의 조건에 근거해 기준 클락을 선택한다.

  • 그래프내의 필터가 기준 클락을 제공할 수 있는 경우는 그 필터를 사용한다. 예외: 그래프가 라이브 소스를 포함하고 있는 경우는, 소스 필터 클락만을 선택한다.
  • 적절한 클락을 제공하는 필터가 없는 경우는, 시스템 타임을 사용한다.

기준 클락은, 100 나노 초간격으로 타임을 계측 한다. 클락의 현재의 타임을 취득하려면 ,IReferenceClock::GetTime 메소드를 호출한다. 클락의 기선, 즉 카운트를 시작 하는 타임은, 클락의 이행에 의존하므로, 돌려주어지는 특정의 타임값은 본질적으로 의미가 있는 것은 아니다. 중요한 것은, 100 나노초에 1 회의 비율로단조 증가하는 값을 돌려준다고 하는 것이다.

클락 타임

DirectShow 에서는, 기준 타임과 스트림 타임의 2 개의 관련 클락 타임을 정의하고 있다.

  • 기준 타임은, 기준 클락에서 돌려주어지는 절대 타임이다.
  • 스트림 타임은, 그래프가 마지막에 실행을 시작 했을 때를 기준에 정의된다.
    • 그래프가 실행하고 있을 때는, 스트림 타임은, 기준 타임부터 시작 타임을 공제한 값에 동일하다.
    • 그래프가 포즈 하고 있을 때는, 스트림 타임은 포즈 되었을 때의 스트림 타임에 머문다.
    • 그래프가 정지하고 있을 때는, 스트림 타임은 제로이다.
    • 시크 처리 후에는, 스트림 타임은 제로에 리셋 된다.

필터 그래프를 실행하기 위해서 어플리케이션이 IMediaControl::Run 를 호출하면, 필터 그래프 매니저는 각각의 필터로 IMediaFilter::Run 를 호출한다. 각 필터가 실행을 시작 하기까지 필요로 해요 두일까 타임을 보정하기 위해서, 필터 그래프 매니저는, 조금 진행한 시작 타임을 지정한다.

타임 스탬프와 미디어 타임

미디어 샘플은, 타임 스탬프와 미디어 타임의 2 개의 타임 베이스의 프로퍼티를 가진다.

타임 스탬프

타임 스탬프는, 스트림 타임에 나타나는 샘플의 시작 타임과 종료 타임을 정의한다. 타임 스탬프는,프레젠테이션 시간으로 불리는 일도 있다.

필터를 받으면(자), 렌더링 필터는 타임 스탬프에 근거해 렌더링을 스케줄 한다. 샘플의 도착이 늦거나 타임 스탬프가 없는 경우, 필터는 즉석에서 그 샘플의 렌더링을 시작 한다. 그 이외의 경우, 필터는 샘플의 시작 타임까지 기다리고 나서 그 샘플의 렌더링을 시작 한다. (필터는,IReferenceClock::AdviseTime 메소드를 호출해 시작 타임을 기다린다. )

소스 필터와 퍼서 필터는, 처리 대상의 샘플에 적절한 타임 스탬프를 설정할 책임을 진다. 이하의 가이드 라인을 사용한다.

  • 파일의 재생 : 최초의 샘플에는, 제로의 시작 타임의 타임 스탬프가 설정된다. 이후의 타임 스탬프는, 샘플의 길이와 재생 레이트에 의해 결정된다.
  • 비디오 및 오디오의 캡춰 : 모든 샘플에는, 캡춰를 한 스트림 타임에 동일한 시작 타임의 타임 스탬프가 설정된다. 비디오 프리뷰 프레임은 예외이다. 그래프 지연 시간이 있기 위해서(때문에), 현재의 스트림 타임의 타임 스탬프가 설정된 프리뷰 프레임은 반드시 늦어 비디오 렌더러에 도착한다. 이 경우, 렌더러는 품질 컨트롤의 목적으로 프레임을 드롭 할 가능성이 있다. 따라서, 프리뷰 프레임에는 타임 스탬프를 설정해서는 안 된다. 품질 컨트롤에 대해서는, 「품질 컨트롤의 관리」를 참조할것.

샘플에 타임 스탬프를 설정하려면 ,IMediaSample::SetTime 메소드를 호출한다.

미디어 타임

미디어 타임은, 시크 가능한 미디어내의 샘플의 본래의 위치 (예를 들어 디스크 위에의 파일)를 지정한다. 비디오의 경우, 미디어 타임은 프레임 번호를 나타낸다. 오디오의 경우, 미디어 타임은 패킷내의 샘플 번호를 나타낸다. 예를 들어, 각 패킷에 1 초의 44.1 kHz 오디오가 포함되어 있는 경우, 최초의 패킷의 미디어 시작 타임은 제로, 미디어 종료 타임은 44100 이 된다. 렌더링 필터는, 미디어 타임의 갭을 체크하는 것으로, 프레임 또는 샘플이 드롭 되었는지 어떠했는지를 조사할 수가 있다.

타임 스탬프는, 예를 들어 시크 레이트나 재생 레이트등의 소스외의 요인으로 의존하지만, 미디어 타임은 항상 오리지날의 소스를 기준으로서 계산된다.

샘플의 미디어 타임을 설정하려면 ,IMediaSample::SetMediaTime 메소드를 호출한다.

라이브 소스

푸쉬 소스라고도 불리는 라이브 소스는, 미디어 데이터를 리얼타임에 받는다. 예를 들어, 비디오 캡춰나 네트워크 브로드캐스트등이 예로서 들고 있다. 일반적으로, 라이브 소스는 데이터가 도착하는 레이트를 제어할 수 없다. 라이브 소스 필터는, 출력 핀으로 IAMPushSource 인터페이스를 이행 해야 한다. 필터 그래프 매니저는 이 인터페이스를 사용해, 라이브 소스가 렌더링 될 때 발생할 가능성이 있는 2 개의 문제에 대처한다.

  • 지연 시간
  • 레이트 매칭

지연 시간

필터의지연 시간이란, 필터가 샘플을 처리하는데 필요로 하는 시간이다. 라이브 소스의 경우, 지연 시간은 샘플을 보관 유지하기 위한 버퍼의 사이즈에 의해 정해진다. 예를 들어 필터 그래프가 비디오 소스를 렌더링 할 때에 33 밀리 세컨드 (ms)의 지연 시간이 있어, 오디오 소스를 렌더링 할 때에 500 ms 의 지연 시간이 있다고 한다. 이 경우, 각 비디오 프레임은, 대응하는 오디오 샘플이 오디오 렌더러에 도착하는 약 470 ms 전에 비디오 렌더러에 도착한다. 이 차이를 그래프로 보정하지 않으면 오디오와 비디오는 동기 하지 않는다.

어플리케이션이 IAMGraphStreams::SyncUsingStreamOffset 메소드를 호출해 동기화를 유효하게 하지 않는 한, 필터 그래프 매니저는 라이브 소스를 동기화하지 않는다. 동기화가 유효하게 되었을 경우, 필터 그래프 매니저는 각각의 소스 필터에 대해서 IAMPushSource 인터페이스를 조회한다. IAMPushSource 를 지원 하는 모든 필터에 대해서, 그래프는 IAMLatency::GetLatency 를 호출해 필터의 예상 지연 시간을 취득해, 이러한 값으로부터 예상 최대 지연 시간을 요구한다. 그래프는 다음에 IAMPushSource::SetStreamOffset 를 호출해 각 소스 필터에 스트림 오프셋(offset)를 준다. 필터는, 이 스트림 오프셋(offset)를 생성하는 타임 스탬프에 가세한다.

레이트 매칭

렌더링 필터가 1 개의 기준 클락을 사용해 샘플을 스케줄 하는 한편으로, 소스 필터가 다른 클락을 사용해 샘플을 생성했을 경우, 재생시에 그릿치가 발생하는 일이 있다. 렌더러가 소스보다 고속으로 실행 하면, 데이터에 갭이 생긴다. 렌더러가 소스보다 저속에 실행 하면, 샘플의 처리가"따라잡지 않게 되어", 어디선가 데이터를 드롭 해야 하게 된다. 보통, 라이브 소스는 그 프로덕션 레이트를 제어할 수가 없기 때문에, 렌더러측에서 소스와 클럭레이트를 일치시킨다.

레이트 매칭을 실시하기 위해서(때문에)는, 렌더링 필터는 다른 클락에 따라 그 클락을 설정해야 한다. 어느 클락을 사용할까는, 소스 필터가 어떻게 타임 스탬프를 생성할까에 의존한다.

  • 소스 필터가 기준 클락에서 타임 스탬프를 생성해, 렌더러가 같은 클락에 액세스 할 수 있는 경우, 렌더러는 클락을 기준 클락으로 설정한다. 이 경우, 소스 필터는 렌더러의 전용 클락을 기준 클락으로서 사용하고 있어서는 안 된다. 그렇지 않으면 렌더러는 자기 자신과 레이트를 맞추게 되어, 클락의 차이가 발생한다.
  • 소스 필터가 프라이빗 클락, 즉 렌더러가 액세스 할 수 없는 클락에서 타임 스탬프를 생성하는 경우, 렌더러는 입력하는 샘플의 타임 스탬프에 근거해 클럭레이트를 조정한다.
  • 소스 필터가 타임 스탬프를 전혀 생성하지 않는 경우, 렌더러는, 배송된 바이트수와 포맷 블록으로 선언된 1 초 쯤의 바이트수에 근거해 소스 필터의 배송 레이트를 계산한다.

렌더러는, 소스 필터의 IAMPushSource::GetPushSourceFlags 를 호출해, 소스 필터가 어떻게 타임 스탬프를 설정할까를 요구한다. 오디오 재생에 있어서의 그릿치는 비디오에 있어서의 그것보다 현저하기 때문에, 현재, 오디오 렌더러만이 레이트 매칭을 실행한다.


품질 컨트롤의 관리

품질 컨트롤은, 필터 그래프내의 데이터 플로우의 레이트를 실행시의 퍼포먼스에 응해 조정하기 위한 메카니즘이다. 렌더링 필터는, 받는 데이터의 양이 너무 많은 경우 또는 너무 적은 경우, 품질 메세지를 송신할 수 있다. 품질 메세지는 데이터 레이트의 조정을 요구한다. 디폴트에서는, 품질 메세지는, 렌더러로부터 응답 가능한 필터 (존재하는 경우)까지 업 스트림 방향으로 이동한다. 어플리케이션에서는, 커스텀 품질 매니저를 이행 할 수도 있다. 그 경우, 렌더러는 품질 메세지를 어플리케이션의 품질 매니저에 직접 건네준다.

여기서 설명하는 내용은 다음과 같다.

  • 품질 메세지
  • 디폴트의 품질 메세지

품질 메세지

품질 메세지는 Quality 구조체를 사용해 정의한다. 이 구조체에는 다음의 멤버가 포함된다.

  • Type: Famine (필터가 받는 데이터가 너무 적은 것을 나타낸다), 또는 Flood (필터가 받는 데이터가 너무 많은 것을 나타낸다) .
  • Proportion: 요구된 데이터 레이트의 조정 (baseline는 1000). 예를 들어, 750 은 75%, 1500 은 150% 를 나타낸다.
  • Late: 최신의 샘플의 도착이 얼마나 늦었는지를 나타내는 기준 타임. 샘플이 빨리 도착했을 경우는, 이 값이 부가 된다.
  • TimeStamp: 최신 샘플의 타임 스탬프.

예를 들어, 240 밀리 세컨드 (ms)의 타임 스탬프를 가지는 샘플이, 280 ms 의 스트림 타임에 렌더러에 도착했다고 한다. 렌더러는 타입이 Famine 의 품질 메세지를 생성 한다. 샘플은 40 ms 늦어 도착했으므로,Late 멤버는 400000 이 된다 (모든 기준 타임은 100 나노초단위). TimeStamp 멤버는 2400000 이다.

Proportion 멤버에 대해서는, 렌더러는 이동평균을 사용해 값을 계산한다. 샘플은 시간대로 도착하고 있어, 이 샘플은 변칙이다. 그 경우, 렌더러는 몇 안 되는 수정 밖에 요구하지 않는다. 한편, 샘플이 일관해 늦는 경우는, 렌더러는 대폭적인 수정을 요구하게 된다.

품질 컨트롤은 IQualityControl 인터페이스를 통해서 처리된다. 이 인터페이스에는 2 개의 메소드가 있다.

  • Notify : 품질 메세지를 송신한다.
  • SetSink : 커스텀 품질 매니저를 지정한다.

IQualityControl 를 이행 하는 오브젝트는,Notify 메소드를 통해서 품질 메세지를 받아들여, 메세지를 처리하는지, 다른 오브젝트에 메세지를 건네준다. 어플리케이션으로 오브젝트의 SetSink 메소드를 호출하는 경우, 오브젝트는 지정된 품질 매니저에 품질 컨트롤을 위임할 필요가 있다.

디폴트의 품질 메세지

필터 base class는, 비디오 품질 컨트롤에 관한 몇개의 디폴트 동작을 이행 한다.

품질 메세지는 렌더러로 시작 된다. 비디오 렌더러의 base class는 CBaseVideoRenderer 이며, 다음과 같이 동작한다.

  1. 비디오 렌더러는, 샘플을 받으면(자), 샘플의 타임 스탬프를 현재의 기준 타임과 비교한다.
  2. 비디오 렌더러는 품질 메세지를 생성한다. base class에서는, 품질 메세지의 멤버 Proportion 는 500 (50%)에서 2000 (200%)까지의 범위에 제한되고 있다. 값이 이 범위외인 경우는, 품질이 급격하게 변화하는 일이 있다.
  3. 디폴트에서는, 비디오 렌더러는 품질 메세지를 업 스트림의 출력 핀 (렌더러의 입력 핀에 접속되고 있는 핀)에 송신한다. 어플리케이션에서는,SetSink 메소드를 호출하는 것에 의해, 이 동작을 오버라이드(override) 할 수 있다.

다음에 행해지는 처리는, 업 스트림 필터에 따라서 다르다. 보통은 변환 필터가 된다. 변환 필터의 base class은 CTransformFilter 로,CTransformInputPin 및 CTransformOutputPin 클래스를 사용해 입력 핀과 출력 핀을 이행 한다. 이러한 클래스는, 함께 다음과 같이 동작한다.

  1. CTransformOutputPin::Notify 메소드는, 필터 base class에 대한 프라이빗 메소드인 CTransformFilter::AlterQuality 를 호출한다.
  2. 파생 필터는 AlterQuality 를 오버라이드(override) 해 품질 메세지를 처리할 수 있다. 디폴트에서는,AlterQuality 는 품질 메세지를 무시한다.
  3. AlterQuality 가 품질 메세지를 처리하지 않는 경우, 출력 핀은 필터의 입력 핀에 대한 프라이빗 메소드인 CBaseInputPin::PassNotify 를 호출한다.
  4. PassNotify 는, 적절한 장소 즉 다음의 업 스트림 출력 핀이나 커스텀 품질 매니저에 품질 메세지를 건네준다.

변환 필터가 품질 메세지를 처리 하면 상정했을 경우, 메세지는 최종적으로 소스 필터의 출력 핀에 도착한다. base class에서는,CBasePin::Notify 가 E_NOTIMPL 를 돌려준다. 특정의 소스 필터가 품질 메세지를 처리하는 방법은, 소스의 종류에 따라서 다르다. 라이브 비디오 캡춰 등, 유효한 품질 컨트롤을 실행할 수 없는 소스도 있다. 샘플을 송신하는 레이트를 조정할 수 있는 소스도 있다.

다음의 그림은, 디폴트의 동작을 나타내고 있다.

base class의 품질 컨트롤

베이스 비디오 렌더러는 IQualityControl::Notify 를 이행 한다. 이것은, 렌더러 자신에게 품질 메세지를 건네줄 수 있는 것을 의미한다. Proportion 멤버를 1000 미만의 값으로 설정 하면, 비디오 렌더러는 렌더링 하는 각 프레임의 사이에 대기 기간을 삽입해, 그 결과 렌더러의 속도가 늦어진다 (이것은, 예를 들어 system resource의 사용율을 줄이기 위해서(때문에) 실행한다). 상세한 것에 대하여는,CBaseVideoRenderer::ThrottleWait 를 참조할것. Proportion 멤버에 1000 보다 큰 값을 설정해도 무효가 된다.


DirectShow 와 COM

이 섹션은, 이하의 주제를 포함하고 있다.

  • IUnknown 의 이행 방법
  • DLL 의 생성 방법
  • DirectShow 필터의 등록 방법


IUnknown 의 이행 방법

Microsoft® DirectShow® 는, Component Object Model (COM)에 근거하고 있다. 스스로 필터를 쓰는 경우는, 필터를 COM 오브젝트로서 이행 해야 한다. DirectShow 의 base class는, 이러한 작업을 행하기 위한 체제를 제공한다. base class를 사용하는 필연성은 없지만, base class를 사용하면 개발 프로세스를 간략화할 수가 있다. 여기에서는, COM 오브젝트의 내부적인 동작과 DirectShow base class에서의 COM 오브젝트의 이행에 대해 설명한다.

이 주제는, COM 클라이언트 어플리케이션의 프로그래밍을 이해하고 있다, 즉,IUnknown 의 메소드를 이해하고 있는 유저를 대상으로 하고 있지만, COM 오브젝트의 개발 경험이 있는 유저를 전제로 하는 것은 아니다. DirectShow 는, COM 오브젝트의 개발에 관한 대부분을 취급한다. COM 오브젝트의 개발 경험이 있는 유저는,CUnknown base class를 해설하고 있는 「CUnknown 의 사용」섹션을 읽어야 하는 것이다.

COM 는 이행은 아니고 사양이다. COM 는, 컴퍼넌트가 따라야 할 규칙을 정의한다. 규칙을 실제로 적용하는 것은 개발자의 역할이다. DirectShow 에서는, 모든 오브젝트는 C++ 의 base class로부터 파생한다. base class constructor　 　 및 메소드는, 일관한 참조 카운트의 보관 유지등의 COM "부기"처리의 대부분을 실시한다. 필터를 base class로부터 파생시키는 것에 의해, 그 클래스의 기능을 계승할 수가 있다. base class를 효과적으로 사용하기 위해서는, COM 사양이 어떻게 클래스에 이행 되고 있는지를 이해할 필요가 있다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • IUnknown 의 동작
  • CUnknown 의 사용
  • 요약

IUnknown 의 동작

IUnknown 의 메소드를 사용 하면, 어플리케이션은 컴퍼넌트의 인터페이스를 조회하거나 컴퍼넌트의 참조 카운트를 관리할 수가 있다. 이 섹션은, 이하의 주제를 포함하고 있다.

  • 참조 카운트
  • 인터페이스의 조회
  • 집성화와 위임

참조 카운트

참조 카운트는,AddRef 메소드로 인크리먼트(increment) 되고 Release 메소드로 감소 되는 내부 변수이다. base class는, 참조 카운트를 관리해, 복수의 thread간에 참조 카운트에의 액세스를 동기화한다.

인터페이스의 조회

인터페이스의 조회는 알기 쉽다. 호출원래는, 인터페이스 식별자 (IID)와 포인터의 주소의 2 개의 파라미터를 건네준다. 요구된 인터페이스를 컴퍼넌트가 지원 하고 있는 경우, 컴퍼넌트는 그 인터페이스에의 포인터를 설정해, 전용의 참조 카운트를 인크리먼트(increment) 해, S_OK 를 돌려준다. 컴퍼넌트가 그 인터페이스를 지원 하고 있지 않는 경우, 컴퍼넌트는 NULL 에의 포인터를 설정해, E_NOINTERFACE 를 돌려준다. 이하의 의사 코드는,QueryInterface 메소드의 개요를 나타낸다. 다음의 마디로 설명하는 컴퍼넌트의 집성화에서는, 처리가 복잡하게 되어 있다.

if (IID == IID_IUnknown)
    set pointer to (IUnknown *) this
AddRef
return S_OK

else if (IID == IID_ISomeInterface)
    set pointer to (ISomeInterface *) this
AddRef
return S_OK

else if ...

else
    set pointer to NULL
    return E_NOINTERFACE

1 개의 컴퍼넌트의 QueryInterface 메소드와 다른 컴퍼넌트의 QueryInterface 메소드의 유일한 차이는, 각각의 컴퍼넌트가 테스트하는 IID 의 리스트에 있다. 컴퍼넌트가 지원 하는 모든 인터페이스에 대해서, 컴퍼넌트는 그 인터페이스의 IID 의 테스트를 실시하지 않으면 안 된다.

집성화와 위임

컴퍼넌트의 집성은 호출해 바탕으로 대해 투과적이지 않으면 안 된다. 따라서, 집성은, 외부 컴퍼넌트의 이행에 따르는 집성 된 컴퍼넌트를 사용해, 1 개의 IUnknown 인터페이스를 공개해야 한다. 그렇지 않으면 호출원래는 같은 집성내에서 2 개가 다른 IUnknown 인터페이스를 인식하게 된다. 컴퍼넌트가 집성되어 있지 않은 경우, 컴퍼넌트는 독자적인 이행을 사용한다.

이 동작을 지원 하기 위해서는, 컴퍼넌트는 간접적인 레벨을 추가해야 한다. 위임 IUnknown 는, 작업을 적절한 장소에 위임한다. 즉, 인터페이스가 1 개이면 외부 컴퍼넌트인가, 또는 컴퍼넌트의 내부 버젼에 위임한다. 비위임 IUnknown 는, 전의 마디로 설명한 조작을 실시한다.

위임 버젼은 공공적이어,IUnknown 의 이름을 그대로 보관 유지한다. 비위임 버젼은 INonDelegatingUnknown 로 이름이 변경된다. 이것은 퍼블릭 인터페이스는 아니기 때문에, 이 이름은 COM 사양의 일부에서는 없다.

클라이언트가 컴퍼넌트의 인스턴스를 생성 하면 와, 클라이언트는 IClassFactory::CreateInstance 메소드를 호출한다. 파라미터는, 집성 컴퍼넌트의 IUnknown 인터페이스에의 포인터인가, 또는 새로운 인스턴스가 집성되어 있지 않은 경우는 NULL 이다. 이하의 예에 나타내도록(듯이), 컴퍼넌트는 사용하는 IUnknown 인터페이스를 나타내는 멤버 변수를 저장 하기 위해서 이 파라미터를 사용한다.

CMyComponent::CMyComponent(IUnknown *pOuterUnkown)
{
    if (pOuterUnknown == NULL)
        m_pUnknown = (IUnknown *)(INonDelegatingUnknown *) this;
    else
        m_pUnknown = pOuterUnknown;

    [ ... constructor　 　  코드 ... ]
}

위임 IUnknown 의 각 메소드는, 다음의 예에 나타내도록(듯이) 대응하는 비위임 메소드를 호출한다.

HRESULT QueryInterface(REFIID iid, void **ppv)
{
    return m_pUnknown->QueryInterface(iid, ppv);
}

위임 동작의 본질상, 위임 메소드는 모든 컴퍼넌트에 있어 같게 보인다. 비위임 버젼만이 바뀐다.

CUnknown 의 사용

DirectShow 는 CUnknown 로 불리는 base class의 IUnknown 를 이행 한다. 이 CUnknown 를 사용해 다른 클래스를 파생해, 컴퍼넌트간에 바뀌는 메소드만을 오버라이드(override) 할 수가 있다. DirectShow 외의 base class의 대부분은 CUnknown 로부터 파생하므로, 생성 하는 컴퍼넌트를 CUnknown 또는 다른 base class로부터 직접 계승할 수가 있다.

이 섹션은, 이하의 주제를 포함하고 있다.

  • INonDelegatingUnknown
  • IUnknown
  • 클래스 constructor

INonDelegatingUnknown

CUnknown 는 INonDelegatingUnknown 를 이행 한다. CUnknown 는 참조 카운트를 내부적으로 관리해, 대부분의 상황으로 상속 클래스는 같은 2 개의 참조 카운트 메소드를 이행 한다. CUnknown 는 참조 카운트가 제로가 되면(자) 그 자체를 삭제한다. 그 한편에서는,NonDelegatingQueryInterface 를 오버라이드(override) 해야 한다. 왜냐하면, base class의 메소드는 IID_IUnknown 이외의 IID 를 받으면(자) E_NOINTERFACE 를 돌려주기 때문이다. 상속 클래스에서는, 이하의 예에 나타내도록(듯이) 지원 하는 인터페이스의 IID 를 테스트할 필요가 있다.

STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv)
{
    if (riid == IID_ISomeInterface)
    {
    return GetInterface((ISomeInterface*) this, ppv);
    }
    // 디폴트
    return CUnknown::NonDelegatingQueryInterface(riid, ppv);
}

유틸리티 함수 GetInterface 는 포인터를 설정해, thread에 대응한 방법으로 참조 카운트를 이행 해, S_OK 를 돌려준다. 디폴트의 케이스에서는, base class 메소드를 호출해 그 결과를 돌려준다. 다른 base class로부터 파생시켰을 경우는, 그 NonDelegatingQueryInterface 메소드를 대신에 호출한다. 이것에 의해, 친클래스가 지원 하는 모든 인터페이스를 지원 할 수가 있다.

IUnknown

위에서 설명한 바와 같이,IUnknown 의 위임 버젼은, 비위임 버젼의 올바른 인스턴스를 기동할 뿐(만큼)이므로 모든 컴퍼넌트로 같다. 편의상, 헤더 파일 Combase.h 는, 인 라인 메소드로서 3 개의 위임 메소드를 선언하는 매크로 DECLARE_IUNKNOWN 를 포함하고 있다. 이 코드를 이하에 나타낸다.

STDMETHODIMP QueryInterface(REFIID riid, void **ppv) {
    return GetOwner() ->QueryInterface(riid, ppv);
};
STDMETHODIMP_(ULONG) AddRef() {
    return GetOwner() ->AddRef();
};
STDMETHODIMP_(ULONG) Release() {
    return GetOwner() ->Release();
};

유틸리티 함수 GetOwner 는, 이 컴퍼넌트를 소유하는 컴퍼넌트의 IUnknown 인터페이스에의 포인터를 취득한다. 집성 한 컴퍼넌트의 경우, 그 소유자는 외부 컴퍼넌트이다. 그 이외의 경우, 컴퍼넌트는 그 자체를 소유한다. 클래스 정의의 public 섹션에 DECLARE_IUNKNOWN 매크로를 인클루드 한다.

클래스 constructor

클래스에 고유의 조작에 가세해, 클래스 constructor　 　 은, 친클래스의 constructor　 　 메소드를 기동해야 한다. 이하의 예에, 일반적인 constructor　 　 메소드를 나타낸다.

CMyComponent(TCHAR *tszName, LPUNKNOWN pUnk, HRESULT *phr)
: CUnknown(tszName, pUnk, phr)
{
/* 그 외의 초기화 */
};

이 메소드는 이하의 파라미터를 취해 CUnknown constructor　 　 메소드에 직접 건네준다.

  • tszName 는, 컴퍼넌트의 이름을 지정한다.
  • pUnk 는, 집성화 IUnknown 에의 포인터이다.
  • pHr 는, 메소드의 성공 또는 실패를 나타내는 HRESULT 값에의 포인터이다.

요약

이하에,IUnknown 와 ISomeInterface 라는 이름의 가상의 인터페이스를 지원 하는 상속 클래스의 예를 나타낸다.

class CMyComponent : public CUnknown, public ISomeInterface
{
public:

DECLARE_IUNKNOWN;

STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv)
    {
        if( riid == IID_ISomeInterface )
        {
        return GetInterface((ISomeInterface*) this, ppv);
        }
        return CUnknown::NonDelegatingQueryInterface(riid, ppv);
    }

CMyComponent(TCHAR *tszName, LPUNKNOWN pUnk, HRESULT *phr)
: CUnknown(tszName, pUnk, phr)
    {
/* 그 외의 초기화 */
    };

    // 다음에 선언을 추가한다.
};

이 예에서는, 이하의 포인트를 나타내고 있다.

  • CUnknown 클래스는 IUnknown 인터페이스를 이행 한다. 새로운 컴퍼넌트는 CUnknown 및 컴퍼넌트가 지원 하는 모든 인터페이스를 계승한다. 컴퍼넌트는,CUnknown 로부터 계승한 다른 base class로부터 파생할 수가 있다.
  • DECLARE_IUNKNOWN 매크로는, 위임 IUnknown 메소드를 인 라인 메소드로서 선언할 수가 있다.
  • CUnknown 클래스는,INonDelegatingUnknown 의 이행을 제공한다.
  • IUnknown 이외의 인터페이스를 이행 하기 위해서는, 상속 클래스는 NonDelegatingQueryInterface 메소드를 오버라이드(override) 해, 새로운 인터페이스의 IID 의 테스트를 실시할 필요가 있다.
  • 클래스 constructor　 　 은,CUnknown 의 constructor　 　 메소드를 기동한다.

필터 개발에 있어서의 다음의 스텝에서는, 어플리케이션을 유효하게 해 컴퍼넌트의 새로운 인스턴스를 생성 한다. 이 때문에는, DLL 에 관한 지식에 가세해 클래스 팩토리 및 클래스 constructor　 　 메소드와의 관계를 이해하고 있는 것이 필요하게 된다. 상세한 것에 대하여는, 「DLL 의 생성 방법」을 참조할것.


DLL 의 생성 방법

여기에서는, Microsoft® DirectShow® 로 컴퍼넌트를 동적 링크 라이브러리 (DLL)로서 이행 하는 방법을 설명한다. 이 주제는,CUnknown base class로부터 컴퍼넌트를 파생하는 것에 의해 IUnknown 인터페이스를 이행 하는 방법을 설명한 「IUnknown 의 이행 방법」의 계속이다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • 클래스 팩토리와 팩토리 템플릿
  • 팩토리 템플릿의 배열
  • DLL 함수

(범용 COM 오브젝트와는 달라) DirectShow 필터의 등록에는, 여기서 설명하고 있지 않는 몇개의 추가의 스텝이 필요하게 된다. 필터의 등록에 대해서는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

클래스 팩토리와 팩토리 템플릿

클라이언트는 COM 오브젝트의 인스턴스를 생성 하기 전에,CoGetClassObject 함수 호출을 사용해 오브젝트의 클래스 팩토리의 인스턴스를 생성 한다. 다음에 클라이언트는, 클래스 팩토리의 IClassFactory::CreateInstance 메소드를 호출한다. 실제로 컴퍼넌트를 생성 하거나 요구된 인터페이스에의 포인터를 돌려주는 것은 클래스 팩토리이다. (CoCreateInstance 함수는, 이러한 스텝을 함수 호출내에서 조합한다. )

다음의 그림에, 메소드 호출의 순서를 나타낸다.

CoGetClassObject 은, DLL 로 정의된 DllGetClassObject 함수를 호출한다. 이 함수는 클래스 팩토리를 생성 해, 클래스 팩토리 위에의 인터페이스에의 포인터를 돌려준다. DirectShow 는 DllGetClassObject 를 이행 하지만, 이 함수는 특정의 부분에서 코드에 의존한다. 이 동작을 이해하기 위해서는, DirectShow 가 어떻게 클래스 팩토리를 이행 하는지를 이해하는 것이 필요하다.

클래스 팩토리는, 다른 COM 오브젝트를 생성 하는 처리에 특화한 COM 오브젝트이다. 각각의 클래스 팩토리에서는, 생성 하는 오브젝트의 형태가 정해져 있다. DirectShow 에서는, 모든 클래스 팩토리는 같은 C++ 클래스 CClassFactory 의 인스턴스이다. 클래스 팩토리는,팩토리 템플릿으로 불리는 클래스 CFactoryTemplate 에 의해 특화된다. 각 클래스 팩토리는, 팩토리 템플릿에의 포인터를 보관 유지한다. 팩토리 템플릿에는, 특정의 컴퍼넌트에 관한 정보 (컴퍼넌트의 클래스 식별자 (CLSID)등)와 그 컴퍼넌트를 생성 한 함수에의 포인터가 저장 된다.

DLL 는, 팩토리 템플릿의 글로벌 배열을 DLL 내의 각 컴퍼넌트에 1 개씩 선언한다. 새로운 클래스 팩토리를 생성 하면 와,DllGetClassObject 는 같은 CLSID 를 가지는 템플릿의 배열을 찾는다. 해당하는 것이 발견되면(자),DllGetClassObject 는 해당 템플릿에의 포인터를 보관 유지하는 클래스 팩토리를 생성 한다. 클라이언트가 IClassFactory::CreateInstance 를 호출하면, 클래스 팩토리는 템플릿에 정의되고 있는 인스턴스화 함수를 호출한다.

다음의 그림에, 메소드 호출의 순서를 나타낸다.

이 아키텍쳐의 이점은, 클래스 팩토리 전체를 이행 하는 일 없이, 인스턴스화 함수등의 컴퍼넌트에 고유의 몇개의 요소만을 정의하면 좋다고 하는 것이다.

팩토리 템플릿의 배열

팩토리 템플릿은, 이하의 퍼블릭 멤버 변수를 저장 한다.

const WCHAR *              m_Name;                // 이름
const CLSID *              m_ClsID;               // CLSID
LPFNNewCOMObject           m_lpfnNew;             // 컴퍼넌트의 인스턴스
                                                  //   (을)를 생성 하는 함수
LPFNInitRoutine            m_lpfnInit;            // 초기화 함수 (옵션)
const AMOVIESETUP_FILTER * m_pAMovieSetup_Filter; // 셋업 정보 (필터용)

2 개의 함수 포인터 m_lpfnNew 및 m_lpfnInit 는, 이하의 형태 정의를 사용한다.

typedef CUnknown *(CALLBACK *LPFNNewCOMObject)(LPUNKNOWN pUnkOuter, HRESULT *phr);
typedef void (CALLBACK *LPFNInitRoutine)(BOOL bLoading, const CLSID *rclsid);

1 번째의 정의는, 컴퍼넌트의 인스턴스화 함수이다. 2 번째의 정의는, 옵션의 초기화 함수이다. 초기화 함수를 지정했을 경우, 함수는 DLL 엔트리 포인트 함수 내부로부터 불려 간다. (DLL 엔트리 포인트 함수에 대해서는, 후의 마디로 설명한다. )

예를 들어 CUnknown 로부터 계승한 CMyComponent 라는 이름의 컴퍼넌트를 포함한 DLL 를 생성 하면 한다. 이 경우, 이하의 항목을 DLL 에 제공해야 한다.

  • 초기화 함수. CMyComponent 의 새로운 인스턴스를 돌려주는 프라이빗 메소드.
  • g_Templates 라는 이름의 팩토리 템플릿의 글로벌 배열. 이 배열은, CMyComponent 의 팩토리 템플릿을 저장 한다.
  • 배열의 사이즈를 지정하는 g_cTemplates 라는 이름의 글로벌 변수.

이러한 항목을 선언하는 예를 이하에 나타낸다.

// 새로운 인스턴스를 돌려주는 프라이빗 메소드
CUnknown * WINAPI CMyComponent::CreateInstance(LPUNKNOWN pUnk, HRESULT *pHr) {
    CMyComponent *pNewObject = new CMyComponent(NAME("My Component"), pUnk, pHr );
if (pNewObject == NULL) {
*phr = E_OUTOFMEMORY;
    }
return pNewObject;
}

CFactoryTemplate g_Templates[1] =
{
    {
      L"My Component",      // 이름
      &CLSID_MyComponent,         // CLSID
      CMyComponent::CreateInstance,   // MyComponent 의 인스턴스를 생성 하는 메소드
      NULL,                           // 초기화 함수
      NULL                            // 셋업 정보 (필터용)
    }
};
int g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

CreateInstance 메소드는, 클래스 constructor　 　 을 호출해 새로운 클래스 인스턴스에의 포인터를 돌려준다. 파라미터 pUnk 는, 집성화 IUnknown 에의 포인터이다. 이 파라미터를 클래스 constructor　 　 에 건네준다. 파라미터 pHr 는, HRESULT 값에의 포인터이다. 클래스 constructor　 　 은 이것을 적절한 값으로 설정한다. 다만 constructor　 　 이 실패했을 경우는, 값을 E_OUTOFMEMORY 로 설정한다.

NAME 매크로는, 디버그 빌드에 대해 캐릭터 라인을 생성하지만, 리테일 빌드에서는 NULL 에 해결한다. 이 예로 컴퍼넌트에게 줄 수 있고 있는 이름은, 디버그 로그에는 기록되지만, 최종 버젼에서는 메모리를 점유 하지 않는다.

CreateInstance 는 프라이빗 메소드이므로 임의의 이름을 가질 수가 있다. 클래스 팩토리는 CreateInstance 에의 포인터를 팩토리 템플릿내에서 받는다. 다만,g_Templates 과 g_cTemplates 는, 클래스 팩토리가 기대하는 글로벌 변수이므로, 반드시 이 이름을 가지지 않으면 안 된다.

DLL 함수

DLL 의 등록, 등록 해제, 메모리에의 로드를 가능하게 하기 위해서는, DLL 는 이하의 함수를 이행 해야 한다.

  • DllMain : DLL 엔트리 포인트. 이 이름 DllMain 는, 라이브러리에서 정의된 함수명의 플레이스홀더이다. DirectShow 의 이행은,DllEntryPoint 라는 이름을 사용한다. 상세한 것에 대하여는, Platform SDK 를 참조할것.
  • DllGetClassObject : 클래스 팩토리의 인스턴스를 생성 한다. 전의 마디에서 해설이 끝난 상태.
  • DllCanUnloadNow : DLL 가 안전하게 언로드 가능한가 어떤가를 조회한다.
  • DllRegisterServer : DLL 의 레지스트리 엔트리를 생성 한다.
  • DllUnregisterServer : DLL 의 레지스트리 엔트리를 삭제한다.

이러한 쳐, 최초의 3 개는 DirectShow 에 의해 이행 된다. 팩토리 템플릿이 초기화 함수를 m_lpfnInit 멤버 변수로 제공하는 경우, 그 함수는 DLL 엔트리 포인트 함수 내부로부터 불려 간다. 시스템이 DLL 엔트리 포인트 함수를 호출하는 타이밍에 대해서는, Platform SDK 의 DllMain 를 참조할것.

DllRegisterServer 와 DllUnregisterServer 는 스스로 이행 해야 한다. 그러나, DirectShow 에는 필요한 조작을 행하기 위한 AMovieDllRegisterServer2 함수가 제공되고 있다. 다음의 예에 나타내도록(듯이), 단지 이 함수를 컴퍼넌트에 랩 하면 좋다.

STDAPI DllRegisterServer()
{
    return AMovieDllRegisterServer2( TRUE );
}

STDAPI DllUnregisterServer()
{
    return AMovieDllRegisterServer2( FALSE );
}

다만,DllRegisterServer 및 DllUnregisterServer 내에서는, 등록 프로세스를 필요에 따라서 커스터마이즈 할 수가 있다. DLL 에 필터가 포함되어 있다면, 몇개의 추가 작업이 필요하다. 상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

모듈 정의 (. def) 파일내에서, 엔트리 포인트 함수 이외의 모든 DLL 함수를 export 한다. 이하에,. def 파일의 예를 나타낸다.

EXPORTS
    DllGetClassObject PRIVATE
    DllCanUnloadNow PRIVATE
    DllRegisterServer PRIVATE
    DllUnregisterServer PRIVATE

DLL 는 Regsvr32.exe 유틸리티를 사용해 등록할 수가 있다.


DirectShow 오브젝트의 등록 방법

이 주제에서는, Microsoft® DirectShow® 필터를 자기 등록으로 하는 방법을 설명한다. 이하의 섹션으로 구성된다.

  • 레지스트리 키의 레이아웃
  • 필터의 등록
  • 필터의 등록 해제

여기에서는, DLL 의 생성 방법에 대해서는 설명하지 않는다. DLL 생성의 상세한 것에 대하여는, 「DLL 의 생성 방법」을 참조할것.

레지스트리 키의 레이아웃

DirectShow 필터는, 다음의 2 개의 장소에 등록된다.

  • 필터가 포함된 DLL 는, 그 필터의 COM 서버로서 등록된다. 어플리케이션이 CoCreateInstance 를 호출해 필터를 생성 하면, Microsoft® Windows® COM 라이브러리는 그 레지스트리 엔트리를 사용해 DLL 를 찾아낸다.
  • 필터에 관한 정보는, 필터 카테고리의 내부에 등록되므로,시스템 디바이스 열거자와필터 맵퍼는, 이 정보를 찾아낼 수가 있다.

다음에, DLL 의 레지스트리 엔트리를 나타낸다.

HKEY_CLASSES_ROOT
    CLSID
        Filter CLSID
            REG_SZ: (Default) = 프렌들리명

            InprocServer32
                REG_SZ: (Default) = DLL 의 파일명
                REG_SZ: ThreadingModel = Both

다음에, 필터 정보의 레지스트리 엔트리를 나타낸다.

HKEY_CLASSES_ROOT
    CLSID
        Category
            Instance
                Filter CLSID
                    REG_SZ: CLSID = 필터의 CLSID
                    REG_BINARY: Filter Data = 필터 정보
                    REG_SZ: FriendlyName = 프렌들리명

"Category" 는,필터 카테고리의 GUID 이다. 필터 정보는 바이너리 포맷에 팩 된다. IFilterMapper2 인터페이스가, 필터의 레지스트리를 검색할 경우에, 이 데이터를 unpack 한다.

필터의 등록

필터를 등록하려면 , 다음의 조작을 실시한다.

  1. 필터 정보를 선언한다.
  2. 필터의팩토리 템플릿에, 필터 정보에의 포인터를 포함한다.
  3. DllRegisterServer 함수를 이행 한다.

이하에서는, 이러한 조작에 대해 자세하게 설명한다.

필터 정보의 선언

최초의 스텝은, 필터 정보의 선언이다. DirectShow 는, 필터, 핀, 및 미디어 타입을 기술하기 위해서, 다음과 같은 구조체를 정의하고 있다.

AMOVIESETUP_FILTER | 필터를 기술한다.
AMOVIESETUP_PIN | 핀을 기술한다.
AMOVIESETUP_MEDIATYPE | 미디어 타입을 기술한다.

이러한 구조체는 네스트 하고 있다. 필터 구조체는 핀 구조체의 배열에의 포인터를 가져, 각각의 핀 구조체는, 미디어 타입 구조체의 배열에의 포인터를 가지고 있다. 이러한 구조체에 의해,IFilterMapper2 인터페이스가 필터를 찾아내기 위해서(때문에) 필요한 정보가 충분히 주어진다. 구조체에 의해, 필터가 완전하게 기술되는 것은 아니다. 예를 들어, 필터가 같은 핀의 복수의 인스턴스를 생성하는 경우에서도, 그 필터에 대해서 1 개의 AMOVIESETUP_PIN 구조체를 선언하는 것만으로 좋다. 또, 필터는, 등록하는 미디어 타입의 모든 편성을 지원 하도록(듯이) 요구되지는 않았다.

이 셋업 구조체를, DLL 의 내부에서 글로벌 변수로서 선언한다. 다음의 예에, 출력 핀을 1 개 가지는 필터를 나타낸다.

static const WCHAR g_wszName[] = L"Some Filter";

AMOVIESETUP_MEDIATYPE sudMediaTypes[] = {
    { &MEDIATYPE_Video, &MEDIASUBTYPE_RGB24 },
    { &MEDIATYPE_Video, &MEDIASUBTYPE_RGB32 },
};

AMOVIESETUP_PIN sudOutputPin = {
    L"",            // 현재는 사용되어 있지 않다.
    FALSE,          // 이 핀을 렌더링 할까?
    TRUE,           // 이것은 출력 핀인가?
    FALSE,          // 이 필터는 제로 인스턴스를 생성할 수 있을까?
    FALSE,          // 이 필터는 복수의 인스턴스를 생성할까?
    &GUID_NULL,     // 현재는 사용되어 있지 않다.
    NULL,           // 현재는 사용되어 있지 않다.
    2,              // 미디어 타입의 수.
    sudMediaTypes   // 미디어 타입에의 포인터.
};

AMOVIESETUP_FILTER sudFilterReg = {
    &CLSID_SomeFilter,      // 필터의 CLSID
    g_wszName,              // 필터의 이름
    MERIT_NORMAL,           // 메리트
    1,                      // 핀 타입의 수
    &sudPins                // 핀 정보에의 포인터
};

필터명은 다른 장소에서도 사용하므로, 정적 글로벌 변수로서 필터명을 선언하고 있다.

팩토리 템플릿의 선언

다음의 스텝은, 필터용의팩토리 템플릿의 선언이다. 팩토리 템플릿은, 클래스 팩토리의 정보를 저장 하는 C++ 클래스이다. DLL 중(안)에서, DLL 내의 필터 또는 COM 컴퍼넌트 마다 1 개(살)씩, 팩토리 템플릿의 글로벌 배열을 선언한다. 이 배열의 이름은 g_Templates 가 아니면 안된다. 팩토리 템플릿의 상세한 것에 대하여는, 「DLL 의 생성 방법」을 참조할것.

팩토리 템플릿의 m_pAMovieSetup_Filter 멤버는, 전에 설명한 AMOVIESETUP_FILTER 구조체에의 포인터이다. 다음의 예에, 팩토리 템플릿을 나타낸다. 전의 예로 가리킨 구조체를 사용하고 있다.

CFactoryTemplate g_Templates[] =
{
    {
        g_wszName,                      // 이름
        &CLSID_SomeFilter,              // CLSID
        CSomeFilter::CreateInstance,    // 생성 함수
        NULL,
        &sudFilterReg                   // 필터 정보에의 포인터
    }
};
int g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

DllRegisterServer 의 이행

마지막 스텝은,DllRegisterServer 함수의 이행이다. 컴퍼넌트가 포함된 DLL 는, 이 함수를 공개해야 한다. 이 함수는, 셋업 프로그램, 또는 유저가 Regsvr32.exe 툴을 실행했을 때에 불려 간다.

다음의 예에,DlLRegisterServer 의 최소한의 이행을 나타낸다.

STDAPI DllRegisterServer(void)
{
    return AMovieDllRegisterServer2(TRUE);
}

DirectShow 함수인 AMovieDllRegisterServer2 는,g_Templates 배열의 모든 컴퍼넌트용으로 레지스트리의 엔트리를 생성 한다. 다만, 이 함수에는 제한이 몇개인가 있다. 우선, 이 함수는 모든 필터를 CLSID_LegacyAmFilterCategory 카테고리에 할당하지만, 모든 필터가 이 카테고리에 속하는 것은 아니다. 예를 들어, 캡춰 필터나 압축 필터는, 각각의 카테고리를 가지고 있다. 카테고리 일람에 대해서는, 「필터 카테고리」를 참조할것. 다음에, 필터가 하드웨어 디바이스를 지원 하고 있는 경우는,AMovieDLLRegisterServer2 가 처리하지 않는 2 개의 정보, 즉 "미디어" 와 "핀 카테고리" 를 등록할 필요가 있다. 미디어는, 하드웨어 디바이스의 통신 방법 (버스등)을 정의해, 핀 카테고리는, 핀의 기능을 정의한다. 미디어의 상세한 것에 대하여는, Microsoft® Windows® Driver Development Kit (DDK)의 「KSPIN_MEDIUM」를 참조할것. 핀 카테고리의 일람에 대해서는, 「핀 프로퍼티 세트」를 참조할것.

필터 카테고리, 미디어, 또는 핀 카테고리를 지정하는 경우는,DllRegisterServer 내로부터 IFilterMapper2::RegisterFilter 메소드를 호출한다. 이 메소드는,REGFILTER2 구조체에의 포인터를 받는다. REGFILTER2 구조체는, 필터에 관한 정보를 지정한다.

귀찮은 것은, REGFILTER2 구조체가, 핀을 등록하기 위한 포맷을 2 종류 지원 하고 있는 것이다. dwVersion 멤버로, 이 포맷을 지정한다.

  • dwVersion 가 1 의 경우, 핀 포맷은 AMOVIESETUP_PIN (전으로 설명)이다.
  • dwVersion 가 2 의 경우, 핀 포맷은 REGFILTERPINS2 이다.

REGFILTERPINS2 구조체에는, 핀 미디어와 핀 카테고리의 엔트리가 포함된다. 또, 일부의 항목에 대해서는, AMOVIESETUP_PIN 가 불리언 값으로서 선언하는 비트 플래그를 사용한다.

다음의 예에,DllRegisterServer 중에서 IFilterMapper2::RegisterFilter 를 호출하는 방법을 나타낸다.

REGFILTER2 rf2FilterReg = {
    1,              // 버젼 1 (핀 미디어와 핀 카테고리는 없음)
    MERIT_NORMAL,   // 메리트
    1,              // 핀의 수
    &sudPins        // 핀 정보에의 포인터
};

STDAPI DllRegisterServer(void)
{
    HRESULT hr;
    IFilterMapper2 *pFM2 = NULL;

    hr = AMovieDllRegisterServer2(TRUE);
    if (FAILED(hr))
        return hr;

    hr = CoCreateInstance(CLSID_FilterMapper2, NULL, CLSCTX_INPROC_SERVER,
            IID_IFilterMapper2, (void **) &pFM2);

    if (FAILED(hr))
        return hr;

    hr = pFM2->RegisterFilter(
        CLSID_SomeFilter,                // 필터의 CLSID
        g_wszName,                       // 필터의 이름
        NULL,                            // 데바이스모니카
        &CLSID_VideoCompressorCategory,  // 비디오 압력의 카테고리
        g_wszName,                       // 인스턴스 데이터
        &rf2FilterReg                    // 필터 정보에의 포인터
    );
    pFM2->Release();
    return hr;
}

필터의 등록 해제

필터의 등록을 해제하는데는,DllUnregisterServer 함수를 이행 한다. 이 함수 중(안)에서, 값 FALSE 를 사용해 DirectShow AMovieDllRegisterServer2 함수를 호출한다. 필터의 등록시에 IFilterMapper2::RegisterFilter 를 호출했을 경우는, 여기서 IFilterMapper2::UnregisterFilter 메소드를 호출한다.

다음의 예에, 필터의 등록을 해제하는 방법을 나타낸다.

STDAPI DllUnregisterServer()
{
    HRESULT hr;
    IFilterMapper2 *pFM2 = NULL;

    hr = AMovieDllRegisterServer2(FALSE);
    if (FAILED(hr))
        return hr;

    hr = CoCreateInstance(CLSID_FilterMapper2, NULL, CLSCTX_INPROC_SERVER,
            IID_IFilterMapper2, (void **) &pFM2);

    if (FAILED(hr))
        return hr;

    hr = pFM2->UnregisterFilter(&CLSID_VideoCompressorCategory,
            g_wszName, CLSID_SomeFilter);

    pFM2->Release();
    return hr;
}


변환 필터

이 섹션에서는,변환 필터의 생성 방법, 변환 필터의 종류, 변환 base class의 사용 방법, 오버라이드(override) 하는 base class 멤버 함수, 및 변환 필터의 접속 기회와 접속 방법에 대해 설명한다.

  • 변환 필터의 생성
  • 변환 base class CTransformFilter 및 CTransInPlaceFilter 의 사용
  • 변환 필터의 접속
  • C/C++ 에 의한 변환 필터의 개발
  • 압축 필터에 대해
  • 이펙트 필터에 대해


변환 필터의 생성

변환 필터는,입력 핀에 입력된 미디어 데이터를 변환해, 변환 후의 데이터를출력 핀에 송신한다. 변환 필터는, 데이터의 압축이나 압축 해제, 오디오 데이터나 비주얼 데이터의 분할, 콘트라스트나 워브링등의 이펙트의 미디어 데이터에의 적용이라고 하는 용도에 사용할 수가 있다. Microsoft® DirectShow® 에는, 여러가지 변환을 실시하는 몇개의 샘플 변환 필터가 준비되어 있다.

여기에서는, DirectShow C++ 클래스 라이브러리를 사용하는 변환을 생성 하는 스텝을 설명한다. 5 개의 기본스텝을 설명하는 가운데, 마지막 스텝으로서 상속 클래스의 필요한 멤버 함수를 오버라이드(override) 해 변환 필터를 이행 하는 방법을 설명한다. 또, 변환 필터의 생성에 수반하는 2 개의 자주 있는 질문 (어느 base class를 사용해야할 것인가? , 어떻게 멤버 함수를 오버라이드(override) 할까? )에 대한 대답도 가리킨다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • 변환 필터를 생성 한다
  • 필터가 미디어 샘플을 카피하는 필요성을 판단한다
  • 사용하는 base class를 결정한다
  • 필터를 인스턴스화한다
  • 추가한 인터페이스를 NonDelegatingQueryInterface 로 이용할 수 있도록(듯이) 한다
  • base class 멤버 함수를 오버라이드(override) 한다

상세한 것에 대하여는, 이하의 주제를 참조할것.

  • 필터
  • C/C++ 에 의한 변환 필터의 개발
  • 변환 base class CTransformFilter 및 CTransInPlaceFilter 의 사용
  • 변환 필터의 접속

변환 필터를 생성 한다

변환 필터를 생성 하는 작업은, 이하의 스텝으로 나눌 수 있다.

  1. 필터가 미디어 샘플을 카피할 필요가 있는지, 또는 그 자리에서 미디어 샘플을 처리할 수 있을까를 판단한다.

    미디어 스트림내의 카피의 수는 적을 정도 좋다. 그러나, 카피 조작이 필요한 필터도 있다. 이 점이 base class의 선택에 영향을 준다.

  2. 사용하는 base class를 결정해 그 base class로부터 필터 클래스 ( 및 필요하면 핑크 라스)를 파생시킨다.

    이 스텝에서는, 필터의 헤더를 생성 한다. 많은 경우는, 변환 base class를 사용해 적절한 변환 필터 클래스에서 클래스를 파생시켜, 몇개의 멤버 함수를 오버라이드(override) 한다. 또, 범용적인 base class를 사용할 수도 있다. 접속 및 네고시에이션 메카니즘의 대부분은 이러한 클래스에 의해 이행 되지만, 한층 더 멤버 함수를 오버라이드(override) 하는 것에 의해 유연성을 제공할 수가 있다.

  3. 필터를 인스턴스화하는데 필요한 코드를 추가한다.

    이 스텝에서는, 정적인 CreateInstance 멤버 함수를 상속 클래스에 추가해, 한층 더 필터의 이름, CLSID, 및 그 멤버 함수에의 포인터를 저장 하는 글로벌 배열을 추가한다.

  4. 필터의 일의인 인터페이스를 건네주기 위한 NonDelegatingQueryInterface 멤버 함수를 추가한다.

    이 스텝은, Component Object Model (COM)의, base class 이외의 인터페이스의 이행에 관한 측면을 나타내고 있다.

  5. base class 멤버 함수를 오버라이드(override) 한다.

    이 작업에는, 필터에 고유의 변환 함수를 써, allocater 사이즈의 설정이나 미디어 타입의 제공등의, 접속 프로세스에 필요없는 구두인가의 멤버 함수를 오버라이드(override) 하는 것이 포함된다.

필터가 미디어 샘플을 카피하는 필요성을 판단한다

모든 카피 처리는 귀중한 CPU 사이클을 사용하므로, 필터의 개발자는 가능하면 미디어 샘플의 카피 처리를 실시하지 않게 해야 한다. 가장 바람직한 것은, 다른 필터로부터 취득한 allocater상에서 그 자리에서 미디어 샘플을 변경하는 것 같은 필터를 쓰는 것이다. 경우에 따라서는 이러한 처리가 불가능해, 카피 처리를 실행해야 하는 것이 있다.

카피의 필요가 없는변환 인플레이션 의자 필터의 실행시의 오버헤드는, 함수의 거기에 비교해 커진다고 하는 것은 없다. 그러나, 변환을 필터로서 패키지화하는 것으로써, 필터 그래프 아키텍쳐의 완전한 유연성을 손에 넣을 수가 있다.

이하와 같은 경우는, 필터를 변환 인플레이션 의자 필터는 아니고 카피 변환 필터로서 생성 한다.

  • 변환에 의해 생성되는 데이터가, 입력의 allocater (예를 들어 데콘프렛사피르타)로 제공되는 영역보다 큰 경우, 또는 변환에 의해 출력에 생성되는 데이터가 적고, 메모리를 정리해야 하는 경우.
  • 오리지날의 미디어 데이터를 보관 유지해야 하는 경우. 변환 필터가 데이터 스트림을 분할하는 스플리터가 이것에 해당한다.
  • 데콘프렛사피르타가, 델타 정보에 관해서 인접 프레임에 의존하면서 시계열 압축을 실시하고 있는 경우. 이 경우, 별개의 카피를 생성 할 필요가 있다. 이것은, 다른 필터가 오리지날의 데이터에 액세스 해 그것을 변경하는 것을 데콘프렛사가 허가하지 않는 것이 그 주된 이유이다.
  • 필터가 큐에 의존하고 있는 경우. 예를 들어 불규칙하게 간격을 비울 수 있었던 비디오 프레임의 배송을 원활히 하기 위해서 큐를 생성 하는 필터는, 샘플을 카피할 필요가 있다.

사용하는 base class를 결정한다

변환 필터의 base class를 선택하기 전에, 필터에 복수의 입력 핀 및 출력 핀이 필요한가 어떤가를 결정하지 않으면 안 된다. 복수의 핀이 필요한 경우는,CBaseFilter 로부터 필터 클래스를 파생해야 한다.

필터로 비디오 변환을 실시할 필요가 있는 경우는,CVideoTransformFilter 로부터 필터 클래스를 파생해야 한다.

그 이외의 경우는,CTransformFilter 또는 CTransInPlaceFilter 로부터 필터 클래스를 파생한다. 어느 쪽을 사용할까를 결정하기 위해서(때문에)는, 필터가 미디어 샘플을 카피할 필요가 있는지, 또는 미디어 샘플을 그 자리에서 변환할 수가 있을까를 결정하지 않으면 안 된다. 모든 카피 처리는 귀중한 CPU 사이클을 사용하므로, 필터의 개발자는 가능하면 미디어 샘플의 카피 처리를 실시하지 않게 해야 한다. 가장 바람직한 것은, 다른 필터로부터 취득한 allocater상에서 그 자리에서 미디어 샘플을 변경하는 것 같은 필터를 쓰는 것이다. 경우에 따라서는 이러한 처리가 불가능해, 카피 처리를 실행해야 하는 것이 있다.

카피의 필요가 없는 변환 인플레이션 의자 필터의 실행시의 오버헤드는, 함수의 거기에 비교해 커진다고 하는 것은 없다. 그러나, 변환을 필터로서 패키지화하는 것으로써, 필터 그래프 아키텍쳐의 완전한 유연성을 손에 넣을 수가 있다.

이하와 같은 경우는, 필터를 변환 인플레이션 의자 필터는 아니고 카피 변환 필터로서 생성 한다.

  • 변환에 의해 생성되는 데이터가, 입력의 allocater (예를 들어 데콘프렛사피르타)로 제공되는 영역보다 큰 경우, 또는 변환에 의해 출력에 생성되는 데이터가 적고, 메모리를 정리해야 하는 경우.
  • 오리지날의 미디어 데이터를 보관 유지해야 하는 경우. 변환 필터가 데이터 스트림을 분할하는 스플리터가 이것에 해당한다.
  • 데콘프렛사피르타가, 프레임간에 변경된 정보에 관해서 인접 프레임에 의존하면서 시계열 압축을 실시하고 있는 경우. 이 경우, 별개의 카피를 생성 할 필요가 있다. 이것은, 다른 필터가 오리지날의 데이터에 액세스 해 그것을 변경하는 것을 데콘프렛사가 허가하지 않는 것이 그 주된 이유이다.
  • 필터가 큐에 의존하고 있는 경우. 예를 들어 불규칙하게 간격을 비울 수 있었던 비디오 프레임의 배송을 원활히 하기 위해서 큐를 생성 하는 필터는, 샘플을 카피할 필요가 있다.

변환 필터가 미디어 샘플을 카피하는지, 또는 미디어 샘플을 그 자리에서 변환할까를 결정한 후는, 사용하는 base class와 오버라이드(override) 및 이행 하는 멤버 함수를 결정할 필요가 있다. 그 후, 상속 클래스를 정의한다.

base class의 일부의 멤버 함수는, base class로 순수 가상 함수로서 선언되고 있는 (이행을 가지지 않는다)인가, 또는 에러값을 돌려주는 이외의 동작을 실시하지 않는 디폴트 이행을 가지고 있으므로, 상속 클래스로 오버라이드(override) 해야 한다.

필터 클래스는, 변환 base class CTransformFilter ,CTransInPlaceFilter , 또는 CVideoTransformFilter 로부터 파생시키는지, 또는 범용적인 CBaseFilter 필터 클래스로부터 파생시킨다. 접속, 미디어 타입, 및 allocater 네고시에이션 코드의 대부분은 base class로 다루어져 변환 클래스에 의해 계승된다. 변환 클래스를 사용 하면, 1 개의 필터 클래스 (핑크 라스 없음)를 파생시키는 것만으로 필터를 생성 할 수가 있다. 변환 클래스는, 변환 필터를 생성 하는 프로세스를 간단하게 하기 위해서, 변환 필터의 동작을 따라가는 개인가의 가정을 실시하고 있다.

CTransformFilter 및 CTransInPlaceFilter 에 대해, 및 상속 클래스에 의해 보통 오버라이드(override) 되는 멤버 함수에 대해서는, 「변환 base class CTransformFilter 및 CTransInPlaceFilter 의 사용」을 참조할것.

필터를 인스턴스화한다

모든 필터는, base class가 필터를 인스턴스화하기 위한 코드를 추가해야 한다. 필터를 인스턴스화하려면 , 2 종류의 코드를 필터에 추가할 필요가 있다. 1 개(살)은 파생 필터 클래스에 추가하는 정적인 CreateInstance 멤버 함수로, 이제(벌써) 1 개(살)은, 이 함수에의 액세스법을 base class의클래스 팩토리에 통지하기 위한 코드이다.

일반적으로,CreateInstance 멤버 함수는 파생 필터 클래스에 대해서 constructor　 　 을 호출한다. 이하에,CreateInstance 멤버 함수의 이행예를 나타낸다.

CUnknown *CGargle::CreateInstance(LPUNKNOWN punk, HRESULT *phr) {

    CGargle *pNewObject = new CGargle(NAME("Gargle Filter"), punk, phr);
    if (pNewObject == NULL) {
    *phr = E_OUTOFMEMORY;
    }

return pNewObject;
} // CreateInstance

클래스 팩토리와 통신을 실시하기 위해서(때문에)는,CFactoryTemplate 오브젝트의 글로벌 배열을 g_Templates 로서 선언해, 필터의 이름, 필터의 클래스 식별자 (CLSID), 및 필터 오브젝트를 생성 하는 스태틱 CreateInstance 멤버 함수에의 포인터를 지정한다.

// CreateInstance 메카니즘에 필요
CFactoryTemplate g_Templates[2]=
    { { L"Gargle filter"              , &CLSID_Gargle , CGargle::CreateInstance          }
    , { L"Gargle filter Property Page", &CLSID_GargProp, CGargleProperties::CreateInstance}
    };

int g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

필터가 자기 등록을 실시하도록(듯이) 하려면 ,CFactoryTemplate 템플릿에 파라미터를 추가한다. 이 처리에 대해서는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

마지막으로, 필터를 Strmbase.lib 에 링크해,. def 파일을 사용해 DllGetClassObject 및 DllCanUnloadNow 를 export 한다.

추가한 인터페이스를 NonDelegatingQueryInterface 로 이용할 수 있도록(듯이) 한다

IUnknown 멤버 함수 (base class에서는 INonDelegatingUnknown 로 불린다)를 이행 할 필요가 있는 것은, base class에 포함되지 않은 인터페이스 (예를 들어 프로퍼티 페이지의 생성에 필요한 인터페이스)를 추가하는 필터 뿐이다. base class는,IUnknown 메소드의 디폴트의 이행을 제공한다. COM 베이스의 코드내의 IUnknown 메소드는, 오브젝트로부터 인터페이스를 취득해, 그 인터페이스의 참조 카운트를 인크리먼트(increment) 및 감소 한다. 예를 들어,IUnknown::QueryInterface 메소드는 인터페이스를 오브젝트로부터 취득한다.

DirectShow 에서는,INonDelegatingUnknown 라고 하는 특수한 IUnknown 클래스가 정의되고 있어, 이 클래스의 메소드는 IUnknown 와 같은 기능을 가진다. (이름이 변경되고 있는 것은, 오브젝트를 집성 할 수 있도록(듯이) 하기 위한(해)이다. ) NonDelegatingQueryInterface 메소드는, 몇개의 오브젝트 또는 어플리케이션이, 이행 하는 인터페이스에 대해 핀 또는 필터에 조회하는 경우에 불려 간다. base class 이행에 리스트 되고 있는 이외의 인터페이스를 필터가 이행 하는 경우는,NonDelegatingQueryInterface 메소드를 오버라이드(override) 해, 이행 하고 있는 인터페이스에의 포인터를 돌려줄 필요가 있다. 예를 들어, 이하의 코드예는, 멤버 함수를 오버라이드(override) 해,ISpecifyPropertyPages 및 IPersistStream 인터페이스에의 참조를 배포한다.

// 영속 스트림, 프로퍼티 페이지, 및 IGargle 인터페이스를 공개한다.
STDMETHODIMP CGargle::NonDelegatingQueryInterface(REFIID riid, void **ppv) {

if (riid == IID_IGargle) {
return GetInterface((IGargle *) this, ppv);
} else if (riid == IID_ISpecifyPropertyPages) {
return GetInterface((ISpecifyPropertyPages *) this, ppv);
} else if (riid == IID_IPersistStream) {
        AddRef();     // 참조 카운트를 추가한다
*ppv = (void *)(IPersistStream *) this;
return NOERROR;

} else {
return CTransInPlaceFilter::NonDelegatingQueryInterface(riid, ppv);
    }
} // NonDelegatingQueryInterface

주 : 이 샘플은, 멤버 함수의 CTransInPlaceFilter 이행을 호출해 종료 처리를 실시한다.

base class 멤버 함수를 오버라이드(override) 한다

사용하는 base class를 결정하면(자) ( 「사용하는 base class를 결정한다」를 참조), 헤더를 써, 이행 하는 멤버 함수를 정의한다. 이 때, 변환 base class (CTransformFilter 또는 CTransInPlaceFilter ) 또는 범용의 CBaseFilter 필터 클래스의 어느쪽이든들 필터 클래스를 파생시킬까 결정할 필요가 있다. 여기에서는, 이하의 멤버 함수의 이행법에 대해 설명한다.

  • Transform 멤버 함수를 오버라이드(override) 한다
  • CheckInputType 멤버 함수를 오버라이드(override) 한다
  • CheckTransform 멤버 함수를 오버라이드(override) 한다
  • DecideBufferSize 멤버 함수를 오버라이드(override) 한다
  • GetMediaType 멤버 함수를 오버라이드(override) 한다
  • 핀 멤버 함수를 오버라이드(override) 한다
  • CBaseOutput::DecideAllocator 멤버 함수를 오버라이드(override) 한다

Transform 멤버 함수를 오버라이드(override) 한다

상속 클래스의 Transform 멤버 함수는, 다른 샘플을 전송 하기 위해서, 필터의 입력 핀의 IMemInputPin::Receive 메소드가 불려 갈 때 마다 불려 간다. 필터의 실제의 목적의 처리를 실행하는 코드를, 이 멤버 함수 또는 거기로부터 불려 가는 함수에 삽입한다. 일반적으로, 카피 변환 필터는, 변환 코드를 사적인 Copy 멤버 함수에 관련짓지만, 변환 인플레이션 의자 함수는 1 개의 버퍼내의 코드를 변경한다.

CheckInputType 멤버 함수를 오버라이드(override) 한다

핀 접속동안, 제시된 미디어 타입이 받아들이고 가능한가 어떤가를 조사하기 위해서(때문에) 입력 핀의 CheckMediaType 멤버 함수가 불려 간다. CTransformInputPin::CheckMediaType 멤버 함수는, 파생 필터 클래스의 CheckInputType 멤버 함수를 그 미디어 타입으로 호출하도록(듯이) 이행 된다. 필터가 대응하고 있는 미디어 타입을 사용하기 위해서는, 이 멤버 함수를 이행 해야 한다. 이하의 코드예에, MEDIATYPE_Audio 이외의 미디어 타입을 거부하는 CGargle::CheckInputType 멤버 함수의 일부를 나타낸다.

HRESULT CGargle::CheckInputType(const CMediaType *pmt) {
    ...
    // Audio 이외의 타입을 거부한다
    if (pmt->majortype ! = MEDIATYPE_Audio) {
    return E_INVALIDARG;
    }

CheckTransform 멤버 함수를 오버라이드(override) 한다

카피 변환 필터는, 입력 핀으로부터 출력 핀에 미디어 타입을 변환할 수가 있다. 따라서, 출력 핀이 접속되는 (즉 그 미디어 타입이 기존이다) 경우, 접속시에 CTransformInputPin::CheckMediaType 멤버 함수가 불려 가면(자), 입력 타입으로부터 출력 타입에의 변환이 유효한가 어떤가를 조사하기 위해서(때문에), 상속 클래스의 CheckTransform 멤버 함수가 불려 간다. 이 멤버 함수는,CTransformOutputPin::CheckMediaType 가 불려 갔을 때도 불려 간다.

CTransInPlaceFilter 클래스에서는, 이 멤버 함수는 단지 S_OK 를 돌려주기 위해서(때문에) base class의 헤더 파일내에서 이행 된다. 왜냐하면, 이 멤버 함수를 호출하는 CTransformFilter 의 함수는,CheckInputType 를 호출하기 위해서(때문에) CTransInPlaceFilter 으로 오버라이드(override) 되기 때문이다. 이 조작은, 카피 변환 필터의 경우와 같게, 변환 인플레이션 의자 필터내에서 미디어 타입이 변화하지 않는 것을 상정하고 있다.

DecideBufferSize 멤버 함수를 오버라이드(override) 한다

카피 변환 필터는, 카피처의 allocater의 프로퍼티를 설정해야 하는 것이 있다. 이러한 상황은,다운 스트림 필터가 새롭고 생성 된 allocater를 제공했을 경우 (즉, 한층 더 앞의 다운 스트림으로부터의 allocater를 건네주고 있는 것은 아닌 경우)나, 출력 핀이 독자적인 allocater를 생성 해야 하는 경우에 일어나기 쉽다. 이 경우, 순수 가상 CBaseOutputPin::DecideBufferSize 멤버 함수가 CBaseOutputPin::DecideAllocator 멤버 함수로부터 불려 가 상속 클래스가 참조처의 allocater 오브젝트의 IMemAllocator::SetProperties 메소드를 호출하는 것에 의해 버퍼 요구를 채운다.

다른 필터의 allocater는 항상 사용되고 있으므로,CTransInPlaceFilter::DecideBufferSize 메소드가 불려 갈 것은 없다. 이 메소드는 base class의 헤더 파일로 이행 되어 E_UNEXPECTED 를 돌려준다.

GetMediaType 멤버 함수를 오버라이드(override) 한다

핀은, 열거자를 제공해, 다른 오브젝트가 핀의 미디어 타입을 판정할 수 있도록(듯이) 한다. 핀은, 미디어 타입 열거자 (IEnumMediaTypes 인터페이스)를 제공한다 (미디어 타입 열거자는, 핑크 라스의 GetMediaType 멤버 함수를 호출하기 위해서(때문에) 핀 base class가 이행 한다). 카피 변환 필터 클래스에서는, 각각의 핀의 CTransformOutputPin::GetMediaType 멤버 함수는, 필터 클래스의 가상 CTransformFilter::GetMediaType 멤버 함수를 호출하는 것만으로 있다. 이 멤버 함수를 상속 클래스로 이행 해, 미디어 타입의 리스트내의 지원 되고 있는 각 미디어 타입을 제공해야 한다.

변환 인플레이션 의자 클래스에서는, 열거자는, 변환 필터의 업 스트림과 다운 스트림의 필터의 사이에 투과 채널을 형성한다. 변환 필터의 입력 핀이 열거를 실시하지 않으면 안 되는 경우, 입력 핀은 다운 스트림 필터의 입력 핀으로부터 열거자를 취득한다. 출력 핀이 열거를 실시하지 않으면 안 되는 경우, 출력 핀은업 스트림 필터의 출력 핀으로부터 열거자를 취득한다. 따라서, 2 개의 변환 인플레이션 의자 필터를 서로 접속하기 위해서는, 그 중이 적어도 1 개(살)이 그 이외의 것에 접속하고 있지 않으면 안 된다. 왜냐하면, 어느 쪽의 변환 인플레이션 의자 필터도 접속을 위한 미디어 타입을 제시할 수 없기 때문에이다.

핀 멤버 함수를 오버라이드(override) 한다

필터 클래스를 변환 클래스로부터 파생해, 복수의 입력 핀 또는 출력 핀을 사용하는 경우는, 핑크 라스 (예를 들어 CTransformInputPin 또는 CTransformOutputPin )를 오버라이드(override) 할 필요가 있다. 핑크 라스를 오버라이드(override) 하는 경우는,CTransformFilter 또는 CTransInPlaceFilter 의 GetPin 멤버 함수를 오버라이드(override) 해, 상속 클래스로부터 핀 오브젝트를 생성 할 수 있도록(듯이) 해야 한다. 한편의 핑크 라스 (예를 들어 CTransformInputPin)를 오버라이드(override) 해,GetPin 를 오버라이드(override) 해 핀 오브젝트를 생성 하는 경우는, 한층 더 같은 base class의 이제(벌써) 한편의 핀 오브젝트 (예를 들어 CTransformOutputPin)도 생성 하도록(듯이) GetPin 를 오버라이드(override) 해야 한다.

복수의 입력 또는 출력 핀을 사용하는 경우는, 변환 클래스보다 CBaseFilter 로부터 필터를 파생시키는 (분)편이 간단하다.

CBaseOutput::DecideAllocator 멤버 함수를 오버라이드(override) 한다

base class는 CBaseOutputPin::DecideAllocator 를 이행 해, 출력 핀이 자동적으로 다운 스트림 핀의 allocater를 사용하도록(듯이) 한다. 상속 클래스에 있어서의 가장 일반적인 변경은, 오브젝트 독자적인 allocater (또는 업 스트림 필터로부터의 allocater)의 사용을 강제하는 것이다. 예를 들어 DirectShow 의 모델에서는,소스 필터는 미디어 샘플을 다음의 필터에 푸쉬 해, 독자적인 allocater를 필요로 한다. 예를 들어, 변환 인플레이션 의자 필터를 써 그것을 소스 필터와 데콘프렛사피르타의 사이에 배치했을 경우, 변환 필터는 소스 필터의 allocater를 데콘프렛사에 제시해야 한다. 따라서,CBaseOutputPin::DecideAllocator 멤버 함수를 오버라이드(override) 해야 한다.


변환 base class CTransformFilter 및 CTransInPlaceFilter 의 사용

이 주제에서는,변환 필터의 생성용으로 제공되고 있는 클래스에 도착해 설명한다. 「변환 필터의 생성」으로 변환 필터 생성의 구체적인 순서를 보기 전에, 이 주제의 정보를 배경 지식으로서 이해할 필요가 있다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • CTransformFilter 및 CTransInPlaceFilter 클래스의 개요
  • 상속 클래스의 요건
  • 변환 필터 선언의 샘플

CTransformFilter 및 CTransInPlaceFilter 클래스의 개요

변환 필터를 개발하는데 가장 간단한 방법은, 변환 필터 클래스를 사용하는 것이다. 이러한 클래스는, 대부분의 종류의 변환 필터로 기능한다. 보통, 비카피의 변환 필터는 CTransInPlaceFilter 클래스와 그 관련 핑크 라스로부터 파생한다. 카피 변환 필터는,CTransformFilter 클래스와 그 관련 핑크 라스로부터 파생한다.

변환 필터 클래스는 계층적이고, 계층 트리의 최하정도에는 변환 인플레이션 의자 클래스가 위치한다. 다음의 그림에 나타내도록(듯이),CTransInPlaceFilter 는 CTransformFilter 로부터 파생해,CTransformFilter 는 CBaseFilter 로부터 파생한다.

CTransInPlaceFilter 클래스의 계층

다음의 그림에 나타내도록(듯이),CTransInPlaceInputPin 클래스는 CTransformInputPin 클래스로부터 파생해,CTransformInputPin 클래스는 CBaseInputPin 클래스로부터 파생한다.

CTransInPlaceInputPin 클래스의 계층

다음의 그림에 나타내도록(듯이),CTransInPlaceOutputPin 클래스는 CTransformOutputPin 클래스로부터 파생해,CTransformOutputPin 클래스는 CBaseOutputPin 클래스로부터 파생한다.

CTransInPlaceOutputPin 클래스의 계층

카피 변환 클래스와 변환 인플레이션 의자 클래스에서는, 많은 기능이 공통되고 있다. 이것은, 변환 인플레이션 의자 클래스의 멤버 함수가 거의 모두 카피 변환 클래스로부터 파생하기 위해(때문에)이다. base class에 대한 변환 클래스의 주된 확장 내용은, 모든 필요한 핀 멤버 함수가 이행 되고 있는 것이다. 따라서, 디폴트의 이행에서는, 메인의 필터 클래스를 (CTransInPlaceFilter 또는 CTransformFilter 로부터) 파생하는 것만으로 좋다.

상속 클래스의 요건

파생된 필터 클래스는, 몇개의 멤버 함수를 제공할 필요가 있다. 이것은 일반적으로 다음과 같은 목적이기 때문에이다

  • 필터가 미디어 타입을 받아들일지 어떨지를 확인한다.
  • 필요한 allocater의 수와 사이즈를 지정한다 (카피 변환만).
  • 필터의 변환 기능을 제공한다.

모든 파생된 필터 클래스는, 정적인 CFactoryTemplate::CreateInstance 함수를 이행 해야 한다. 또,CBaseFilter::GetSetupData 멤버 함수를 오버라이드(override) 해 필터를 자기 등록으로 할 수도 있다. 그것과는 별도로, 클래스는 변환 base class내의 몇개의 멤버 함수를 오버라이드(override) 할 필요가 있다. 필터의 인스턴스화의 상세한 것에 대하여는, 「변환 필터의 생성」을 참조할것.

파생된 필터 클래스가 CTransformFilter 클래스에 근거하고 있는 경우, 이하의 멤버 함수를 오버라이드(override) 할 필요가 있다.
Transform | 변환을 이행 한다.
CheckInputType | 미디어 타입의 지원을 확인한다.
CheckTransform | 이 타입의 변환의 지원을 확인한다 (디버그용 빌드만).
DecideBufferSize | 카피시의 사이즈와 수를 설정한다.
GetMediaType | 출력 핀의 미디어 타입을 지정한다.

파생된 필터 클래스가 CTransInPlaceFilter 클래스에 근거하고 있는 경우, 이하의 멤버 함수를 오버라이드(override) 할 필요가 있다.
Transform | 변환을 이행 한다.
CheckInputType | 미디어 타입의 지원을 확인한다.

최저한의 오버라이드(override)에 의해 변환 필터에 디폴트의 이행을 제공하는 것 외에, 다른 멤버 함수를 오버라이드(override) 해 동작을 한층 더 특화할 수도 있다. 물론, 어느 멤버 함수를 오버라이드(override) 할까는, 필터에 요구하는 기능에 따라서 다르다. 예를 들어, 필터에 복수의입력 핀과 출력 핀을 갖게하고 싶은 경우는,GetPin 및 GetPinCount 멤버 함수를 오버라이드(override) 할 필요가 있다.

또,BreakConnect 이나 CompleteConnect 등 몇개의 base class 멤버 함수는, 핀을 통한 필터에의 통지로서 불려 간다. 일반적으로, 그러한 멤버 함수의 대부분은, 핀에만 존재한다. CTransformFilter 에 근거하는 클래스에서는, 핀 함수는 필터 클래스내가 닮은 이름의 함수를 호출하도록(듯이) 이행 되고 있다. 이것은, 오버라이드(override)의 필요성이 높은 멤버 함수는 모두 1 개의 필터 클래스에 모아지고 있는 것을 의미한다. 그 때문에, 핑크 라스를 변경하지 않고 끝나, 이행이 작고 간단하게 된다. 이러한 멤버 함수를 이하에 나타낸다.
멤버 함수 | 오버라이드(override) 하는 이유
NonDelegatingQueryInterface | 상속 클래스에 추가된 인터페이스를 배포하기 위해(때문에)
GetPinCount | 변환 필터에 핀을 추가하는 경우
GetPin | 변환 필터에 핀을 추가하는 경우
CheckConnect | 접속시에 추가 인터페이스를 취득하기 위해(때문에), 등
BreakConnect | 접속의 절단시에 추가 인터페이스를 해방하기 위해(때문에), 등
CompleteConnect | 접속의 종료시에 몇개의 동작을 실행하기 위해(때문에) (입력 핀의 재접속 등)
SetMediaType | 미디어 타입이 설정되었을 때에 통지를 받기 (위해)때문에
StartStreaming | 스트리밍 상태에 들어갈 때 통지를 받기 (위해)때문에
StopStreaming | 스트리밍 상태를 나올 때 통지를 받기 (위해)때문에
AlterQuality | 품질 컨트롤 메세지를 단지 건네주는 것 외에 어떠한 조작을 실시하기 (위해)때문에

변환 필터 선언의 샘플

이 샘플은, 완전한 최소 기능 필터를 나타내고 있다. 이것은, 필터에 대해서 필요한 최저한의 이행을 나타내는 것 외에는, 아무것도 하지 않는다. 이 필터는 변환 인플레이션 의자 클래스를 사용해, 그 필터 클래스를 CTransInPlaceFilter 클래스로부터 파생하고 있다. 파생된 필터 클래스 CNullNull 의 클래스 선언을 다음에 나타낸다.

// CNullNull
//
class CNullNull
: public CTransInPlaceFilter
{

public:

    static CUnknown *CreateInstance(LPUNKNOWN punk, HRESULT *phr);

DECLARE_IUNKNOWN;

    LPAMOVIESETUP_FILTER GetSetupData()
    {
        return &sudNullNull;
    }

private:

    // constructor　 　. 단지 base class constructor　 　 을 호출한다.
    CNullNull(TCHAR *tszName, LPUNKNOWN punk, HRESULT *phr)
        : CTransInPlaceFilter (tszName, punk, CLSID_NullNull, phr)
    { }

    // CTransInPlaceFilter base class의 순수 가상 변환을 오버라이드(override) 한다.
    // 변환의 "실제의 일" 는 *pSample 를 변경하는 것으로 행해진다.
    // Null 변환은 *pSample 를 변경하지 않는다.
    HRESULT Transform(IMediaSample *pSample){ return NOERROR; }

    // 이 필터는 모든 입력 타입을 받아들인다.
    // (보통은, 받아들이지 않는 타입에 대해서 S_FALSE 를 돌려준다)
    HRESULT CheckInputType(const CMediaType* mtIn) { return S_OK; }
};

이 예에는, base class로 필요한, 이하의 기본적인 멤버 함수가 나타나고 있다.
CreateInstance | 클래스를 COM 오브젝트로서 인스턴스화하기 위해서(때문에), 모든 클래스에서 필요.
GetSetupData | CBaseFilter::GetSetupData 를 오버라이드(override) 해, 이 특정의 필터를 등록하기 위해서 필요한 정보를 클래스에 제공한다. 여기에서는, SDK 에 포함되는 Nullnull.cpp 파일에 정의된 구조체의 주소를 제공하고 있다.
CNullNull | 클래스 constructor . 보통은 단지 base class constructor 을 호출한다.
Transform | CTransInPlaceFilter::Transform 를 오버라이드(override) 해, CNullNull 의 주된 작업을 실행한다. 여기에서는, 아무것도 하지 않는다.
CheckInputType | CTransInPlaceFilter::CheckInputType 를 오버라이드(override) 해, 접속시의 미디어 타입을 확인한다. 이 함수는 단지 미디어 타입을 다음의 필터에 건네줄 뿐(만큼)이므로, 여기에서는 모든 미디어 타입을 받아들인다.

엄밀하게 말하면,GetSetupData 는 필터를 자기 등록으로 하고 싶은 경우에게만 필요하다. 그러나, 이 기능은 base class로 이행 되어 이행은 간단하게 실시할 수 있으므로, 이것을 base class에 포함해 두는 것을 추천한다.


변환 필터의 접속

여기에서는,변환 필터를 생성 하는 경우의 접속에 관한 몇개의 문제를 설명한다. 임의의 2 개의 필터를 접속하려면 , 어느 미디어 타입을 사용하는지를 조정하거나 샘플을 건네주기 위한 공유의 allocater를 결정하는 것이 필요하게 된다. 변환 필터는 양측으로 접속되어 또 일부의 변환 필터는 그래프내의 다른 필터의 미디어 타입과 allocater를 사용하는 것으로부터, 변환 필터의 접속에 관한 개념을 이해하는 것이 중요하다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • allocater 네고시에이션의 구조
  • 필터 그래프의 접속 : 예
  • 미디어 타입 접속의 확립

allocater 네고시에이션의 구조

미디어 타입이나 allocater 네고시에이션을 포함한 접속 프로세스에 대해서는, 「필터의 접속」을 참조할것. 변환 필터의 특성을 결정하는데, 변환 필터의 allocater 네고시에이션의 모델을 이해해 두면(자) 도움이 된다.

변환 필터로 카피 처리가 필요한 경우, 변환 필터는,입력 핀에 의해 확립된 버퍼로부터출력 핀에 의해 확립된 버퍼에 미디어 샘플을 카피한다. 이러한 버퍼는, allocater에 의해 지정되지만, allocater는 실제로는 다른 필터에 존재하는 경우가 있다. 중간에 있는 필터가 데이터를 카피하지 않는 경우는, 몇개인가처의 필터에 존재하는 일도 있다.

카피 변환 필터의 경우, 보통은 입력 핀에 대해서는업 스트림 필터의 allocater가, 출력 핀에 대해서는다운 스트림 필터의 allocater가 사용된다. 접속 프로세스의 사이, 어느 allocater를 사용해 업 스트림전송을 실시할까는, 업 스트림 필터의 출력 핀에 의해 결정된다. 따라서, 카피 변환의 입력 핀은, 접속되고 있는 출력 핀으로부터 그 IMemInputPin::GetAllocator 메소드가 불려 갔을 경우에, 업 스트림 전송의 allocater를 생성 할 준비가 되어 있지 않으면 안 된다. base class를 사용하는 것으로, 임의의 접속의 입력 핀으로부터 새로운 allocater를 생성 할 수가 있다.

한편,변환 인플레이션 의자 필터는 카피를 생성 하지 않고 , 기존의 버퍼내의 데이터를 변경한다. 이러한 필터는, 반드시 다운 스트림 필터로부터 업 스트림 필터에 allocater를 제공해야 한다. 이 때문에는 재접속이 필요하다. 왜냐하면, 입력 핀이 최초로 접속될 때는, 필터는 다운 스트림 필터에 대해 아무것도 모르기 때문에이다. 또, 인플레이션 의자 변환은 미디어 타입을 변경하지 않기 때문에, 다운 스트림 필터로부터의 미디어 타입을 재접속시에 업 스트림 필터에 제공할 필요가 있다.

필터 그래프의 접속 : 예

변환 인플레이션 의자 필터의 할당 모델을 알기 쉽게 하기 위해서, 이하에 단순하고 일반적인 필터 그래프의 예를 나타낸다.

필터 그래프의 예

이 단순한 예는, 다운 스트림 allocater를 업 스트림 필터에 제공하는 변환 인플레이션 의자 필터의 모델을 나타내고 있다. InPlace E 가 VidRen F 에 접속되었을 경우를 생각해 보자.

접속시, 비디오 렌더러 필터 (VidRen F)는 업 스트림 인플레이션 의자 필터 (InPlace E)로부터 이용할 수 있도록(듯이) allocater을 제공한다. 이것은 변환 인플레이션 의자 필터이므로, InPlace E 는 allocater를 그 전의 업 스트림 필터 InPlace D 에 제공한다. 이 재접속과 재네고시에이션은,소스 필터 또는 카피 변환 필터에 도달할 때까지 반복해진다. 이 경우는 데콘프렛사 CopyDec C 에 도달한다. (카피 변환 필터는 카피 처리를 실행해야 하기 때문에, allocater를 업 스트림에 제공할 수 없다. ) 데콘프렛사는, 비디오 렌더러의 버퍼에 기입을 직접 행한다 (버퍼는 DirectDraw® 표면인 경우도 있다). 이것이, 변환 필터를 변환 인플레이션 의자 필터로서 기술해, 가능하면 렌더러로부터의 allocater를 업 스트림에 건네주는 것이 중요한 것의 이유이다.

다음에, 필터 InPlace B 와 CopyDec C 를 생각해 보자. 변환 인플레이션 의자 필터로부터의 다운 스트림 필터가 렌더러는 아니고 카피 변환 필터이다고 하면 어떻게 되겠지? 이 경우, 카피 변환 필터는, 독자적인 allocater를 입력 핀에 생성 해 (base class가 이 처리를 실시한다), 변환 인플레이션 의자 필터는 재접속시에 그 allocater를 업 스트림에 제공한다 (렌더링 필터에 접속되고 있는 경우와 같다).

다만, CopyDec C 가 (IMemInputPin::GetAllocator 메소드를 사용해) 독자적인 allocater를 생성 할 수가 있는 한편으로, 소스 필터 Source A 는 독자적인 버퍼 (예를 들어 파일)를 사용한다. 따라서, InPlace B 가 CopyDec C 에 접속 하면 와, InPlace B 는 이미 소스 필터의 allocater를 받아들이고 있게 되어, 자신과 데콘프렛사피르타의 사이에 전송을 실시하는 경우에 강제적으로 그 allocater를 사용한다. InPlace B 는 업 스트림 필터의 Source A 에 대해서 CopyDec C 로부터 제공된 allocater를 사용하는 옵션을 제시하지만, 소스 필터는, 파일 버퍼로부터 데콘프렛사의 입력 버퍼에의 여분의 카피를 실행하지 않아도 되도록(듯이), 이 allocater를 거부한다.

따라서, 모든 업 스트림 필터는 그 allocater를 다운 스트림으로 사용하도록(듯이) 강제할 수가 있지만, 그렇게 하는 이유를 가지지 않으면 안 된다 (예를 들어 벌써 버퍼가 있는 등). 이 예에서는, 파일 버퍼와 비디오 메모리의 사이에 (데콘프렛사피르타에 의해) 카피가 1 개만 생성 된다.

미디어 타입 접속의 확립

다른 필터의 핀을 접속하는 경우, 핀간에 교환되는 샘플의 공통의 미디어 타입을 결정하지 않으면 안 된다. 여기에서는, 변환 필터가 어떻게 미디어 타입의 네고시에이션을 취급하는지를 이해하기 위해서, 접속 메카니즘을 간단하게 설명한다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • 접속 프로세스 : 요약
  • 재접속의 타이밍

접속 프로세스 : 요약

필터 그래프 매니저가 있는 필터의 출력 핀을 호출해 2 번째의 필터의 입력 핀에 접속하는 경우,IPin::Connect 메소드가 불려 간다. 다음에 이 메소드는,CBaseOutputPin::CheckConnect 를 호출해 접속하는 핀으로부터 인터페이스를 취득해,CBasePin::AgreeMediaType 를 사용해 공통의 미디어 타입을 조사한다.

AgreeMediaType 은, 미디어 타입 열거자를 사용해 각 핀에 희망의 미디어 타입을 조회하는 CBasePin::TryMediaTypes 를 호출한다. IEnumMediaTypes 는,TryMediaTypes 가 최초로 사용하는, 접속처의 입력 핀 위에의 인터페이스이다. base class는 IEnumMediaTypes 를 사용해, 리스트내의 각각의 미디어 타입에 대해 CBasePin 멤버 함수 GetMediaType 를 반복해 호출한다. 이 멤버 함수를 입력 및 출력 핑크 라스로 사용해, 핀으로 희망되는 미디어 타입을 돌려준다.

TryMediaTypes 는, 돌려주어진 입력 타입 각각 붙어 출력 핀의 CheckMediaType 멤버 함수를 호출한다. CheckMediaType 를 사용해, 이 타입이 허용 될지 어떨지를 확인해야 한다. 미디어 타입이 발견되지 않는 (예를 들어,GetMediaType 가 접속처의 입력 핀으로 사용되어 있지 않은, 또는 허용 할 수 없는 미디어 타입을 돌려줄) 경우,AgreeMediaType 는 출력 핀의 미디어 타입 열거자를 취득해, 차례로 미디어 타입을 조사한다. 여기서, 파생한 출력 핀의 GetMediaType 멤버 함수가 각각의 타입에 대해 다시 불려 간다. 이 경우, 필터의 입력 핀에 의해 확립된 기존의 접속에 관해서 조회를 실시하는 것에 의해 미디어 타입을 판정할 수가 있다.

재접속의 타이밍

입력 핀으로부터 출력 핀의 사이에 미디어 타입을 변경하지 않는 변환 필터 (대부분의 인플레이션 의자 변환 및 많은 카피 변환)의 경우, 다운 스트림 필터의 미디어 타입을 업 스트림 필터에 제공하기 위해서 재접속 스킴이 준비되어 있지 않으면 안 된다. 이것을 이해하기 위해서, 다음의 그림의 변환 인플레이션 의자 Filter B 의 미디어 타입 네고시에이션을 검토한다.

필터와 핀의 배치를 나타내는 그림

Filter B 의 입력 핀이 최초로 접속되어 업 스트림의 출력 핀 (AOutPin)과 미디어 타입을 확립한다. 다음에 Filter B 의 출력 핀을 접속하는 경우, 출력 핀에는 전용의 열거 자식이 없기 때문에, 접속되고 있는 업 스트림 필터의 출력 핀 (AOutPin)으로부터의 열거자를 사용해야 한다.

다운 스트림 필터 CInPin 의 핀이 이 미디어 타입을 받아들였을 경우, 접속은 완료한다. 이번은, Filter C 가 이 미디어 타입을 받아들이지 않고 , Filter B 를 취급할 수 있는 미디어 타입을 처리하는 케이스를 생각해 본다.

미디어 타입을 취급할 수 있을지 어떨지를 판정하기 전에, Filter B 는 AOutPin 의 IPin::QueryAccept 메소드를 호출해, 그 미디어 타입이 허용 되는 것을 확인한다. 모든 필터로 허용 되는 미디어 타입을 검출할 수 없는 경우, BOutPin 로부터 CInPin 에의 접속은 실패한다. (변환 인플레이션 의자 필터가 그 업 스트림 또는 다운 스트림에 접속할 수 있지만, 양쪽 모두에 동시에는 접속할 수 없다. )

적절한 타입이 발견되었을 경우, BOutPin 는 필터 전체에 재접속을 강제해, AOutPin 와 BInPin 가 다시 접속되었을 때에, 확립된 미디어 타입 (CInPin 의 미디어 타입)을 AOutPin 에 건네준다.


C/C++ 에 의한 변환 필터의 개발

변환 필터는, 미디어 입력을 받아, 거기에 어떠한 변경을 더한다. 변환 필터를 설계하는 경우, 필터 클래스는 몇개의 변환 base class (CTransformFilter ,CTransInPlaceFilter , 또는 CVideoTransformFilter )로부터 파생하는지, 보다 일반적인 CBaseFilter 클래스로부터 파생한다. 어느 base class를 선택할까는, 필터가 미디어 샘플을 카피할 필요가 있든가, 혹은 그대로 변환할 수 있을까에 의해 정해진다. 상세한 것에 대하여는, 「사용하는 base class를 결정한다」를 참조할것.

필터 그래프 매니저는, 필터의 파생원의 base class의 함수를 사용해, 필터 그래프에 필터를 삽입해, 필터간의 접속을 자동적으로 생성 한다. 필터 맵퍼는, 필터의 레지스트리 정보를 사용해 필터 그래프를 설정한다.

가장 단순한 변환 필터 (예를 들어,입력 핀과출력 핀이 1 개씩 밖에 없는 필터)의 경우, 필터 클래스를 CTransformFilter 로부터 파생해,Transform 함수와 CheckInputType 함수만을 오버라이드(override) 하면 좋다. 커스텀 기능이 필요하면, 다른 함수를 오버라이드(override) 해 독자적인 접속, 핀, 및 다른 필터 기능을 생성 할 수 있다. 상세한 것에 대하여는, 「base class 멤버 함수를 오버라이드(override) 한다」를 참조할것. 또, 필터 클래스를 CBaseFilter 로부터 파생해, 그 메소드를 오버라이드(override) 할 수도 있다.

이 섹션에서는, 이하의 방법에 대해 설명한다.

  • 필터 클래스의 정의와 인스턴스화
  • CheckInputType 의 오버라이드(override) (CBaseFilter 로부터 파생한 필터 클래스에는 적용되지 않는다)
  • Transform 함수의 오버라이드(override) (CBaseFilter 로부터 파생한 필터 클래스에는 적용되지 않는다)
  • 추가 인터페이스에의 액세스
  • 레지스트리 정보의 생성

모든 변환 필터는, 추가 인터페이스에의 액세스를 제외해, 위의 스텝을 모두 실행하는 코드를 이행 해야 한다.

변환 필터의 배경 정보에 대해서는, 이하의 주제를 참조할것.

  • 사용하는 base class를 결정한다
  • base class 멤버 함수를 오버라이드(override) 한다

필터의 등록과 자기 등록화에 대해서는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

필터 클래스의 정의와 인스턴스화

필터 클래스를 정의해 인스턴스화하기 위한 순서를 이하에 나타낸다.

  1. 필터 클래스 ( 및 필요에 따라서 핑크 라스)를 파생하는 base class를 결정한다. 보통, 변환 필터 클래스는 변환 base class인 CTransformFilter ,CTransInPlaceFilter , 또는 CVideoTransformFilter 로부터 파생하는지, 또는, 보다 일반적인 CBaseFilter 클래스로부터 파생한다. 비디오 미디어 (특히 AVI 데이터)를 변환하고 싶은 경우는,CVideoTransformFilter 로부터 파생한다. 필터가 입력 미디어 샘플을 카피할 필요가 있는 경우는,CTransformFilter 로부터 파생한다. 필터가 미디어 샘플을 그대로 변환할 수 있는 경우는,CTransInPlaceFilter 로부터 파생한다. 변환 base class로 제공되는 단순한 변환 필터 지원 대신에, 독자적인 멤버 함수를 이행 하고 싶은 경우는,CBaseFilter 로부터 파생한다. 상세한 것에 대하여는, 「사용하는 base class를 결정한다」를 참조할것.

    다음의 예에서는, 필터 클래스를 CTransInPlaceFilter 로부터 파생하고 있다.

        class CMyFilter  :public CTransInPlaceFilter
  2. 오브젝트에 대해서 IUnknown 인터페이스를 이행 한다.

    필터 클래스 정의의 퍼블릭 섹션으로 CUnknown 의 인스턴스를 생성 하고 나서,DECLARE_IUNKNOWN 매크로를 호출한다.

    public:
        static CUnknown *WINAPI CreateInstance(LPUNKNOWN punk, HRESULT
    *phr);
DECLARE_IUNKNOWN;
  3. constructor　 　 을 정의한다. 또,Transform 함수와 CheckInputType 함수를 정의한다 (필터 클래스가 CBaseFilter 로부터 파생하고 있는 경우, 이러한 함수는 정의하지 않는다).

    필터 클래스 정의의 프라이빗 섹션으로, constructor　 　 을 정의한다. 이것은, 파생원의 변환 필터 클래스의 constructor　 　 을 호출하는 것으로 실시한다. 다음에, 변환을 실행해 입력 타입을 체크하는 코드를 추가한다. 다음에 예를 나타낸다.

        // CTransInPlaceFilter 의 constructor　 　 을 호출하는 것으로,
    // constructor　 　 을 정의한다.
    CMyFilter(TCHAR *tszName, LPUNKNOWN punk, HRESULT *phr)
    : CTransInPlaceFilter (tszName, punk, CLSID_MyFilter, phr)
    { }

    // 변환 코드를 추가한다.
    HRESULT Transform(IMediaSample *pSample){
    // 여기에 변환 코드가 들어간다.
    }

    // 입력 타입을 체크하는 코드를 추가한다.
    HRESULT CheckInputType(const CMediaType* mtIn) {
    // 여기에 입력 체크 코드가 들어간다.
    }
  4. 필터 오브젝트에 대해서 CreateInstance 를 이행 한다. 보통,CreateInstance 는 필터 클래스의 constructor　 　 을 호출한다. 다음에 예를 나타낸다.
        CUnknown * WINAPI CMyFilter::CreateInstance(LPUNKNOWN punk, HRESULT *phr) {
    CMyFilter *pNewObject = new CMyFilter(NAME("Description of My Filter"),
        punk, phr );
if (pNewObject == NULL) {
*phr = E_OUTOFMEMORY;
    }
return pNewObject;
    }
  5. CFactoryTemplate 오브젝트의 글로벌 배열 g_Templates 를 선언한다. 이것은,CreateInstance 함수에의 액세스 방법을 디폴트의클래스 팩토리 코드에 통지하기 위해서 사용된다.
        CFactoryTemplate g_Templates[]=
        {   { L"My Filter"
            , &CLSID_MyFilter
            , CMyFilter::CreateInstance  // 클래스 팩토리에 의해 불려 가는 함수
            , NULL
            , &sudMyFilter }     // AMOVIESETUP_FILTER 구조체의 주소.
                                 //   구조체가 존재하지 않는 경우는 NULL.
    };
int g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

    g_cTemplates 변수는, 필터에 대한 클래스 팩토리 템플릿 (CFactoryTemplate )의 수를 정의한다. 각 템플릿은 COM 와 필터의 사이의 링크를 제공해, 필터의 베이스 오브젝트를 생성 하기 위해서 사용된다. 필터에는 최악이어도 1 개의 템플릿이 있다. 이것은, 필터 독자적인 CreateInstance 함수의 주소를 제공한다. 이 함수는, 불려 가면(자) 베이스 오브젝트를 생성 한다.

    CFactoryTemplate 템플릿에 파라미터를 추가하는 것으로, 프로퍼티 페이지를 추가할 수 있다. 등록시의 CFactoryTemplate 의 사용법에 대해서는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

  6. 필터 오브젝트의 GUID 를 생성한다.

    GUID 의 생성에 관한 일반적인 정보에 대해서는, Platform SDK 의 "GUID 의 생성과 최적화 " 및 "uuidgen 유틸리티 " 를 참조할것.

    Microsoft® Visual C++® 5. x 로 GUID 를 생성하려면 ,[툴] 메뉴로부터 [Create GUID] 를 선택한다. GUID 의 디폴트의 포맷은 DEFINE_GUID 이며, 이것을 그대로 사용한다. [카피] 버튼을 클릭한다. 원시 파일로 인클루드문아래에 커서를 두어,[편집] 메뉴의 [붙이기] 를 선택한다. 다음의 예에 나타내는 것 같은 코드가 삽입된다. 다만, 번호와 CLSID 는 고유의 것이 들어간다. 헤더 파일 또는 메인 파일의 클래스 정의전에 코드를 삽입한다.

        // {3FA5D260-AF2F-11d0-AE9C-00A0C91F0841}
    DEFINE_GUID(CLSID_MyFilter,
    0x3fa5d260, 0xaf2f, 0x11d0, 0xae, 0x9c, 0x0, 0xa0, 0xc9, 0x1f, 0x8, 0x41);

CheckInputType 의 오버라이드(override)

필터에 대해서 지정된 입력이 올바른지 어떤지 확인하기 위해서,CheckInputType 함수를 오버라이드(override) 한다 (이것은 CBaseFilter 로부터 파생한 필터 클래스에는 적용되지 않는다). 이행에서는, 지원 할 수 없는 미디어 타입에 대해서 에러를 돌려줄 필요가 있다. 필터가 지원 하는 미디어 타입은,AMOVIESETUP_MEDIATYPE 구조체에 리스트 된다. 다음에 예를 나타낸다.

    HRESULT CMyFilter::CheckInputType(const CMediaType *pmt)
    {
       if (pmt->majortype ! = MEDIATYPE_Video) {
           return S_FALSE;
       }
           else return S_OK;
       }

Transform 함수의 오버라이드(override)

입력 미디어에 대해서 필요한 변환을 실행하기 위해서, 변환 base class의 Transform 함수를 오버라이드(override) 하는지, 또는 독자적인 변환 함수를 이행 할 필요가 있다 (이것은 CBaseFilter 로부터 파생한 필터 클래스에는 적용되지 않는다).

예를 들어, 콘트라스트 샘플의 이하의 코드에 대해 생각한다. CContrast::Transform 함수를 다음과 같이 오버라이드(override) 한다.

    HRESULT CContrast::Transform(IMediaSample *pIn, IMediaSample *pOut)
    {
            HRESULT hr = Copy(pIn, pOut);
        if (FAILED(hr)) {
        return hr;
        }
            return Transform(pOut);

    }

최초의 CContrast::Transform 함수는 미디어 데이터를 카피해, (pOut 파라미터가 가리킨다) 그 카피를 다음의 Transform 함수에 건네준다. 콘트라스트 샘플의 최초의 Transform 함수는 overload 된 함수이며, 2 번째의 형태의 Transform 함수는 입력 미디어의 카피에 대해서 인플레이션 의자 변환을 실시한다. 이것을 다음의 코드에 나타낸다.

    HRESULT CContrast::Transform(IMediaSample *pMediaSample)
    {
        signed char ContrastLevel;
        ContrastLevel = m_ContrastLevel;
        AM_MEDIA_TYPE *pAdjustedType = NULL;

        pMediaSample->GetMediaType(&pAdjustedType);
        HRESULT hr = Transform(&AdjustedType, ContrastLevel);
        pMediaSample->SetMediaType(&AdjustedType);
return NOERROR;
    }

2 번째의 형태의 overload 된 Transform 함수는, 게다가 3 번째의 형태의 overload 된 Transform 함수를 호출하는 것에 주의.

추가 인터페이스에의 액세스

필터가 base class에 이행되어 있지 않은 인터페이스를 이행 하는 경우는,NonDelegatingQueryInterface 함수를 오버라이드(override) 해, 이행 된 인터페이스에의 포인터를 돌려줄 필요가 있다.

  1. 필터 클래스 정의의 퍼블릭 섹션으로,NonDelegatingQueryInterface 를 선언한다.
    STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv)
  2. 클래스의 이행 섹션으로,NonDelegatingQueryInterface 함수를 이행 한다. 다음에 예를 나타낸다.
        // 영속 스트림과 프로퍼티 페이지를 공개한다.
    STDMETHODIMP CMyFilter::NonDelegatingQueryInterface(REFIID riid, void **ppv)
    {
        if (riid == IID_IPersistStream) {
          AddRef( );   // 참조 카운트를 추가한다. 종료후에 해방하는 것.
          *ppv = (void *)(IPersistStream *) this;
          return NOERROR;
       }
       } else if (riid == IID_ISpecifyPropertyPages) {
return GetInterface((ISpecifyPropertyPages *) this, ppv);
       }
       else {
return CTransInPlaceFilter::NonDelegatingQueryInterface(riid, ppv);
       }
    }

레지스트리 정보의 생성

필터 그래프 매니저는, 필터의 레지스트리 엔트리를 사용해, 필터와 그 접속을 설정한다. 필터의 레지스트리 정보는,AMOVIESETUP_MEDIATYPE ,AMOVIESETUP_PIN , 및 AMOVIESETUP_FILTER 구조체에 제공한다. 보통, 이러한 구조체는 필터 이행 코드의 선두에 위치한다. 이러한 구조체의 사용법의 상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

필터의 등록에 필요한 3 개의 구조체를 제공하기 위한 순서를 이하에 나타낸다.

  1. AMOVIESETUP_MEDIATYPE 구조체를 제공한다. 이 구조체는, 필터가 지원 하는 미디어 타입에 관한 레지스트리 정보를 보관 유지한다. 다음에 예를 나타낸다.
        const AMOVIESETUP_MEDIATYPE sudPinTypes =
                    { &MEDIATYPE_Video             // 메이저 타입
                    , &MEDIASUBTYPE_NULL}  ;       // 마이너 타입

    메이저 타입은,MEDIATYPE_Stream, MEDIATYPE_Video, MEDIATYPE_Audio 의 언젠가이다.

  2. Provide the AMOVIESETUP_PIN 구조체를 제공한다. 이 구조체는, 필터가 지원 하는 핀에 관한 레지스트리 정보를 보관 유지한다.
  3. AMOVIESETUP_FILTER 구조체를 제공한다. 이 구조체는, 필터 오브젝트에 관한 레지스트리 정보 (CLSID, 설명, 핀수, 핀 구조체의 이름, 필터의메리트)를 보관 유지한다. 메리트 는, 필터 그래프 매니저가 필터에 액세스 하는 순서를 제어한다. 메리트의 값은 MERIT_PREFERRED, MERIT_NORMAL, MERIT_UNLIKELY, MERIT_DO_NOT_USE 의 언젠가이다. 메리트값의 상세한 것에 대하여는, 「IFilterMapper::RegisterFilter 」를 참조할것. 다음의 코드는,AMOVIESETUP_FILTER 구조체의 예를 나타낸다.
        const AMOVIESETUP_FILTER
    sudMyFilter = { &CLSID_MyFilter         // clsID
                , L"My Filter Description"  // strName
                , MERIT_UNLIKELY            // dwMerit
                , 2                         // nPins
                , sudpPins };               // lpPin


압축 필터에 대해

압축 필터는, 특수한 타입의변환 필터이다. 압축 필터 (압력)는, 데이터를 받아, 압축 스킴을 사용해 그 데이터를 변환해, 압축 데이터를 다운 스트림에 건네준다.

Microsoft® DirectShow® 에는, Microsoft Video for Windows® 의 비디오 또는 오디오 CODEC 를 사용해 데이터를 압축하는 AVI 압력 필터와 ACM 래퍼 필터가 포함되어 있다. DirectShow 에 의해 제공되는 디폴트 필터에서는 지원 되지 않는 포맷으로 데이터를 압축할 필요가 있는 경우는, 스스로 압력 필터를 쓸 수가 있다.

압축 필터를 쓰는 경우는, 1 개의입력 핀과 1 개의출력 핀을 가지는 변환 필터를 쓴다. 변환 필터의 쓰는 법에 대해서는, 다음의 주제를 참조할것.

  • 변환 필터의 생성
  • 변환 base class CTransformFilter 및 CTransInPlaceFilter의 사용법
  • 변환 필터의 접속

변환 필터를 써 끝낸 후는, 압축 필터를 생성 할 때에 이하의 포인트를 확인할 필요가 있다.

  • 필터를 등록한다.

    AMovieDllRegisterServer2 함수를 사용해 압축 필터를 등록한다. 이것에 의해, 어플리케이션이 시스템 위에의 다른 압축 필터와 함께 생성 한 필터를 열거하는 것이 가능하게 된다.

  • 추천 압력 인터페이스를 이행 한다.

    모든 압축 필터의 출력 핀에 IAMStreamConfig 인터페이스를 이행 해, 비디오 압력의 출력 핀에 IAMVideoCompression 를 이행 해, 어플리케이션이 필터의 압축기노우에 액세스 할 수 있도록(듯이) 하는 것이 강하고 추천 된다.

    IAMStreamConfig 를 사용 하면, 데이터의 압축 포맷에 대한 정보를 어플리케이션에 통지해, 특정의 데이터형에 압축하기 위해서 어플리케이션이 압력을 구성할 수 있게 된다.

    IAMVideoCompression 를 사용 하면, 어플리케이션은,AM_MEDIA_TYPE 구조체에는 나타나지 않는 비디오 고유의 설정, 예를 들어키 프레임의 빈도등을 설정할 수가 있다.


이펙트 필터에 대해

Microsoft® DirectShow® 에서는,이펙트 필터는, 이펙트를 미디어 데이터에 적용하지만 미디어 타입을 변경하지 않는 필터로서 정의된다.

입력과 출력의 미디어 포맷이 같아, 적용된 이펙트는 포맷을 변경할 수 없기 때문에, 이펙트 필터가 미디어 formatting를 체크하는 코드를 포함하는 일도 있다. 필터가변환 필터의 base class (CTransformFilter 또는 CTransInPlaceFilter ) 로부터 파생했을 경우, 그 필터는 보통,CheckMediaType ,CTransformFilter::CheckInputType , 및 CheckTransform 메소드를 사용해 포맷을 체크한다. 필터가 변환 필터의 몇개의 base class로부터 파생한 것이 아닌 경우, 보통은,CBasePin::CheckMediaType 멤버 함수를 호출하는 것에 의해 핀이 포맷을 체크한다.

이펙트 필터 클래스에는, 필요한 최대의 기능을 제공하는 base class를 선택할 필요가 있다. 변환 필터 base class의 어느쪽이든을 base class로 하는 것은 자주 있다. 필요한 기능을 상위 레벨의 base class가 모두 지원 하고 있지 않는 경우는,CBaseFilter 또는 CBasePin 를 base class로서 선택할 수가 있다.

이펙트 상태를 GraphEdit 에 보존하고 싶은 경우, 이펙트 필터는 IPersistStream 인터페이스를 이행 해야 한다. 이 인터페이스에 액세스 하려면 ,CPersistStream 로부터 이펙트 필터 클래스를 파생해,IPersistStream 인터페이스를 조회한다. 설계시에 필터 상태를 보존해도 도움이 되지 않지만, GraphEdit 가 닫았을 때에 이펙트 필터가 디폴트 상태에 돌아오도록(듯이) 해 두면(자) 편리하다. 이 경우는,IPersistStream 를 이행 할 필요는 없다.

유저가 이펙트를 조작할 수 있도록(듯이) 하려면 , 이펙트 필터의 프로퍼티 페이지를 생성 및 표시해, 한층 더 유저의 입력을 필터에 돌려주기 위한 메카니즘을 제공할 필요가 있다. 이 때문에는. 프로퍼티 페이지 클래스, (프로퍼티 페이지를 공개한다) ISpecifyPropertyPages 인터페이스, 및 프로퍼티 페이지값을 변경하는 커스텀 인터페이스를 이행 해야 한다. 보통, 프로퍼티 페이지는, 슬라이더, 버튼, 체크 박스등의 컨트롤을 사용해 유저 입력을 받는다. 또, 프로퍼티 페이지에 컨트롤을 표시하는 리소스 파일도 제공해야 한다.

프로퍼티 페이지 클래스를 이행 하려면 ,CBasePropertyPage 로부터 파생하는 클래스를 생성 해,OnReceiveMessage 메소드,CPersistStream::SetDirty 메소드, 및 각각의 이펙트 파라미터의 데이터 멤버를 이행 한다. 이 2 개의 인터페이스에 액세스 하려면 , 이펙트 필터 클래스를 ISpecifyPropertyPages 와 커스텀 인터페이스로부터 파생시켜 인터페이스를 조회한다. 이하의 코드예에 나타내도록(듯이),NonDelegatingQueryInterface 메소드를 오버라이드(override) 하는 것에 의해 모든 인터페이스를 조회할 수가 있다 (IGargle 는 커스텀 인터페이스).

STDMETHODIMP CGargle::NonDelegatingQueryInterface(REFIID riid, void **ppv)
{
    CheckPointer(ppv, E_POINTER);
if (riid == IID_IGargle) {
return GetInterface((IGargle *) this, ppv);
} else if (riid == IID_ISpecifyPropertyPages) {
return GetInterface((ISpecifyPropertyPages *) this, ppv);
} else if (riid == IID_IPersistStream) {
        return GetInterface((IPersistStream *) this, ppv);
} else {
return CTransInPlaceFilter::NonDelegatingQueryInterface(riid, ppv);
    }
}

보통, 이펙트 필터의 커스텀 인터페이스는, 각각의 이펙트 파라미터의 put 메소드와 get 메소드를 제공한다. 예를 들어 IGargle 커스텀 인터페이스는, put_GargleRate 및 get_GargleRate 메소드를 제공한다. Contrast 샘플의 IContrast 커스텀 인터페이스는, put_ContrastLevel 및 get_ContrastLevel 메소드를 제공한다. 유저가 프로퍼티 페이지의 몇개의 컨트롤에 액세스 하면, 페이지는 윈도우 메세지를 생성한다. 프로퍼티 페이지 클래스의 OnReceiveMessage 멤버 함수가 이 메세지를 처리한다. Contrast 샘플의 이하의 코드에, 이 메세지 생성 및 처리를 나타낸다. IDB_DEFAULT 는,[Default] 버튼의 리소스 ID 이다. 유저가 이 버튼을 클릭 하면, 비디오의 콘트라스트가 디폴트 상태로 설정된다. CContrastProperties 클래스는 프로퍼티 페이지를 설정해, IContrast::put_DefaultContrastLevel 메소드는 콘트라스트 레벨을 디폴트값으로 설정한다.

BOOL CContrastProperties::OnReceiveMessage(HWND hwnd, UINT uMsg,
    WPARAM wParam, LPARAM lParam)
{
    switch (uMsg)
    {
       case WM_COMMAND:
        {
          if (LOWORD(wParam) == IDB_DEFAULT)
            {
            pIContrast() ->put_DefaultContrastLevel();
            SendMessage(m_hwndSlider, TBM_SETPOS, TRUE, 0L);
              SetDirty();
        }
            return (LRESULT) 1;
        }
...

이펙트 필터는, 크리티컬 섹션을 내부적으로 사용해 글로벌 필터 상태를 보호한다. 이펙트 필터는 크리티컬 섹션을 잠그는 것에 의해, 필터 그래프를 통과하는 데이터 플로우가 직렬화 되어 이펙트가 발생하고 있을 때 글로벌 필터 상태가 변화하지 않는 것을 보증할 수가 있다. DirectShow 는,CAutoLock 클래스 오브젝트를 선언하는 것에 의해 크리티컬 섹션을 잠근다. 보통, 이펙트 필터는 이펙트를 적용하는 함수를 입력 하면 즉석에서 크리티컬 섹션을 잠근다. 예를 들어 이하의 코드로 이펙트를 적용하는 함수는 MessItAbout 이다.

// 이펙트 필터 클래스 정의에 대해
// 크리티컬 섹션의 데이터 멤버를 선언한다.
CCritSec   m_GargleLock;

void CGargle::MessItAbout(PBYTE pb, int cb)
{
    CAutoLock foo(&m_GargleLock);

보통, 이펙트 프로퍼티의 put 및 get 메소드 (예를 들어 put_GargleRate)는 크리티컬 섹션을 잠그므로, 이펙트값은 갱신의 도중에 변화하지 않는다.


비디오 렌더러

이 섹션에서는, 비디오 렌더러의 생성 방법과 사용 방법에 대해 설명한다. 풀 스크린 렌더러와 커스텀 렌더러의 양쪽 모두에 대해 설명한다. 풀 스크린 렌더러를 지원 하는 방법과 이유, 및 커스텀 렌더러로 통지, 상태 변경, 동적 포맷 변경을 처리하는 방법에 대해 설명한다.

  • 풀 스크린 비디오 렌더러
  • 대체 비디오 렌더러
  • 비디오 렌더러에 있어서의 전송원직사각형과 전송처 직사각형


풀 스크린 비디오 렌더러

이 주제에서는, 어플리케이션으로부터 비디오를 풀 스크린 모드로 렌더링 하도록(듯이) 지시받았을 때에 디폴트의 IVideoWindow PID 로 사용되는 논리에 대해 설명한다. 대체렌더러 필터는,IVideoWindow PID 를 사용해 어플리케이션과 교환할 수 있다. 대체 렌더러의 개발자는, 풀 스크린 모드에서의 렌더링이 요구되었을 때에, 풀 스크린 비디오를 표현하기 위한 최선의 수단을 이 PID 가 필터 그래프로부터 어떻게 검색할까를, 알아 둘 필요가 있다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • IVideoWindow PID 를 사용한 풀 스크린 지원의 이행
  • 풀 스크린 모드를 지원 하는 필터의 검색
  • 코스트없이 풀 스크린에 신장 할 수 있는 필터의 검색
  • 풀 스크린 렌더링 필터의 제공
  • 렌더러 출력의 풀 스크린에의 신장
  • 어플리케이션에 대한 풀 스크린 지원의 의미

IVideoWindow PID 를 사용한 풀 스크린 지원의 이행

Microsoft® DirectShow® 는, 이용 가능한 하드웨어 리소스의 종류에 응해, 몇개의 방법으로 풀 스크린 지원을 이행 한다. 어플리케이션은, 필터 그래프 매니저에 의해 제공되는 IVideoWindow 인터페이스를 통해서 풀 스크린 비디오 재생을 지원 할 수 있다. 어플리케이션은, 풀 스크린 재생에 대해서 독자적인 이행을 가질 수도 있지만, 많은 경우 IVideoWindow 이행을 사용하는 편이 리소스의 사용 효율이 좋다.

어플리케이션이 풀 스크린 모드를 요구 하면,IVideoWindow PID 는 풀 스크린 지원을 이행 하기 위해서, 3 개(살)이 다른 옵션을 시험한다. 보통 이 옵션은, 필터 그래프가 최초로 풀 스크린 모드에 들어갈 때 선택된다. 풀 스크린 모드의 사이는,IVideoWindow 메소드가 불려 갈 것은 없다 (풀 스크린 프로퍼티에의 액세스를 제외해). 호출하려고 하면,VFW_E_IN_FULLSCREEN_MODE 메세지가 돌려주어진다. PID 는,IVideoWindow 를 지원 해 이하의 몇개의 특성을 가지는 필터를, 다음의 순서로 검색한다.

  1. 풀 스크린 모드를 직접 제공하는 필터
  2. 그 윈도우를 패널티없이 풀 스크린에 신장 할 수 있는 필터
  3. 풀 스크린 렌더러로 치환가능인 필터

이 3 개의 옵션의 모두 발견되지 않는 경우는, 디폴트로서IVideoWindow 를 지원 하는 필터의 비디오를 단순하게 풀 스크린에 신장 한다. 퍼포먼스 패널티는 고려되지 않는다.

풀 스크린 모드를 지원 하는 필터의 검색

최초의 옵션은, 풀 스크린 모드를 직접 지원 하는 필터를 필터 그래프로부터 검색하는 것이다. 풀 스크린 모드에의 이행을 지시받으면(자),IVideoWindow PID 는 우선 필터 그래프내에서 IVideoWindow 를 지원 하는 필터를 모두 스캔 한다. PID 는 각 필터상에서 IVideoWindow::get_FullScreenMode 를 호출한다. 필터가 E_NOTIMP (디폴트)를 돌려주었을 경우, PID 는 그 필터에는 풀 스크린 재생의 고유 지원이 없으면 가정한다. 필터가 그 이외의 값을 돌려주었을 경우는, 풀 스크린 재생의 후보 필터가 된다. 즉, 풀 스크린 모드를 온 또는 오프로 하기 위한 필터 그래프 매니저에의 호출은, 그 후보 필터에 직접 보내진다. 이 메카니즘에 의해, 필터가 풀 스크린 모드를 직접 지원 하도록(듯이) 확장할 수 있다. 보통의 Windows 베이스의 렌더러의 대부분은, 이 기능을 지원 할 필요가 없다.

코스트없이 풀 스크린에 신장 할 수 있는 필터의 검색

풀 스크린 렌더링 필터가 발견되지 않는 경우, PID 는 IVideoWindow 인터페이스를 지원 하는 필터 가운데, 그 윈도우가 패널티없이 풀 스크린에 신장 할 수 있는 것을 검색한다. 그 때문에(위해) PID 는, 필터 그래프내에서 IVideoWindow 를 지원 하는 필터의 리스트를 스캔 한다. 발견된 각 필터에 대해서, PID 는 IVideoWindow::GetMaxIdealImageSize 를 호출한다. 필터가 그 윈도우가 코스트없이 풀 스크린에 신장 할 수 있는 것을 나타내고 있으면, 그 필터가 후보 필터가 된다.

그 후보 필터에 대해서 풀 스크린에서의 렌더링이 요구되면(자), PID 는 필터의 IVideoWindow 프로퍼티의 몇개인가를 리셋 해, 윈도우를 풀 스크린에 신장 한다. 이것은 보통, 소유자를 NULL 로 설정해, 윈도우의 스타일을 경계 또는 캡션을 표시하지 않게 변경해, 윈도우의 위치를 현재의 표시 사이즈에 일치하도록(듯이) 갱신하는 것을 의미한다. 풀 스크린 모드가 오프가 되면(자), 필터의 프로퍼티는 풀 스크린 모드에 들어가기 전 상태에 돌아온다.

IVideoWindow 를 지원 하는 비디오 렌더러의 대부분은, 액티브 (포즈 또는 실행중)가 되었을 때에 처음으로 리소스를 할당하므로, 지금까지의 사이는 이상적인 최대 이미지 사이즈를 돌려줄 수가 없다. 그 때문에, 필터 그래프가 정지상태태 때에 필터의 리스트를 스캔 하는 경우, PID 는 IVideoWindow::GetMaxIdealImageSize 를 호출하기 전에 각 필터를 포즈 한다. 이 메소드를 호출한 후, 필터는 한번 더 정지된다.

풀 스크린 렌더링 필터의 제공

여기까지의 옵션이 모두 실패했을 경우, PID 는 필터 그래프내에서 IVideoWindow 인터페이스를 지원 하는 최초의 필터를 검색해, 그것이 현재의 비디오 렌더링 필터이라고 가정한다.

IVideoWindow 를 지원 하는 필터가 없는 경우, 풀 스크린 모드로 변경하기 위한 호출은 VFW_E_NO_FULLSCREEN 을 돌려준다. 풀 스크린 모드에의 변경이 요구되면(자), PID 는 현재의 렌더러에 대해서 풀 스크린 모드를 효율적으로 지원 할 수 있을지 어떨지를 문의한다. 효율적으로 지원 할 수 있는 경우, 그래프로 변경은 더해지지 않는다. 그것을 할 수 없는 경우에는, PID 는 필터 그래프가 정지되어 있지 않으면 그것을 정지해, 현재의 렌더러를 떼어내, 그 대신에 DirectShow 풀 스크린 렌더러를 재접속해, 종료후에 원의 필터 그래프를 복원한다. 풀 스크린 모드로부터 나올 때는, 이것과 역의 순서를 밟는다. 즉, 풀 스크린 렌더러가 떼어내져 원의 필터가 재접속된다. 필터 그래프 상태는과 같이 복원된다. 풀 스크린 렌더러는, Microsoft® DirectDraw® 에 의해 제공되는 표시 변경 기능을 사용한 특별한 렌더러이다. 예를 들어, 1024 × 768 으로부터 풀 스크린 표시를 320 × 240 으로 전환하거나 할 수 있다. 낮은 해상도의 모드로 변경하는 것으로써, 이미지를 신장 하는 일 없이 저비용으로 풀 스크린 렌더링을 이행 할 수 있다.

풀 스크린 렌더러는 현재, 320 × 200 × 8/16 비트/픽셀, 320 × 240 × 8/16, 640 × 400 × 8/16, 640 × 400 × 8/16, 640 × 480 × 8/16, 800 × 600 × 8/16, 1024 × 768 × 8/16, 1152 × 864 × 8/16, 1280 × 1024 × 8/16 의 각 표시 모드를 이행 하고 있다. 모드 X 렌더러는 IFullScreenVideo 인터페이스를 지원 한다. 모드 X 렌더러를 접속 하면, 이 렌더러는 DirectDraw 에 의해 이용 가능하게 된 표시 모드를 로드한다. 이용 가능한 모드의 수는,IFullScreenVideo::CountModes 에 의해 취득할 수 있다. 각 모드에 관한 정보는,IFullScreenVideo::GetModeInfo 및 IFullScreenVideo::IsModeAvailable 를 호출하는 것으로 얻을 수 있다. 어플리케이션은, OATRUE 또는 OAFALSE 로 SetEnabled 플래그를 호출하는 것으로, 각 모드를 유효 또는 무효로 할 수 있다. 현재의 값은,IFullScreenVideo::IsModeEnabled 로 조회할 수 있다.

모드를 유효하게 하는 이제(벌써) 1 개의 방법은, 클립 소실 계수를 사용하는 것이다. 이것은, 사용하는 표시 모드를 결정할 때에 없어질 가능성이 있는 비디오의 양을 정의한다. 디코더가 비디오를 압축할 수 없으면 가정했을 경우, 예를 들어 352 × 288 픽셀의 MPEG 파일을 320 × 200 표시로 재생 하면, 이미지의 40 퍼센트 이상이 없어진다. 클립 소실 계수는, 허용 되는 클립 소실의 상한을 지정한다. 표준적인 MPEG 비디오를 320 × 200 으로 재생할 수 있도록(듯이), 디폴트는 50 퍼센트가 되어 있다. 클립 소실 계수는 IFullScreenVideo::SetClipFactor 로 설정할 수 있다.

렌더러 출력의 풀 스크린에의 신장

최초의 3 개의 옵션을 시도한 후는, 풀 스크린 지원을 이행하기 위한 마지막 옵션으로서IVideoWindow 에 의해 유효하게 된 임의의 필터를 사용해, 그 윈도우를 풀 스크린에 신장 한다. 이것은, 결과의 퍼포먼스의 좋음과 좋지 않음에 관계없이 행해진다. 기본적으로, 필터 그래프내에서 IVideoWindow 인터페이스에 의해 유효하게 된 최초의 필터가, 후보 필터가 된다. 이 필터는, 퍼포먼스를 희생하지 않고 풀 스크린 신장 할 수 있는 필터와 완전히 똑같이 사용된다 (즉, 소유자가 리셋 되어 스타일이 변경되어 윈도우 위치는 표시 범위에 맞추어 변경된다).

암묵의 퍼포먼스 패널티가 있는 경우에 윈도우를 풀 스크린에 신장 하는 코스트는, 현재의 표시 해상도에 따라서 다르다. 최악의 케이스는, 유저가 비교적 높은 해상도 (예를 들어, 1024 × 768)를 사용해, 렌더러가 GUI 를 사용해 이미지를 신장 해야 하는 경우이다. 이 경우, 프레임 throughput가 매우 낮아지기 (위해)때문에, 마지막 수단으로서의 보고 사용한다.

어플리케이션에 대한 풀 스크린 지원의 의미

어플리케이션에 공개되는 인터페이스는 비교적 단순하지만, 그 기반이 되는 이행은 복잡하게 되는 경우가 있다. 풀 스크린 렌더러에는, 어플리케이션 개발자가 주의하지 않으면 안 되는 특별한 속성이 있다. 특히, 렌더러가 표시 모드를 변경하는 것은 액티브한 동안 (포즈중 또는 실행중) 뿐인 것에 주의한다. 따라서, 풀 스크린 모드에의 변환시에 필터 그래프가 정지하고 있었을 경우에는, 필터 그래프가 다시 시작 될 때까지 눈에 보이는 변경은 행해지지 않는다. 필터 그래프가 실행되면(자), 표시 모드가 변경되어 풀 스크린 렌더링이 시작 된다.

윈도우가 풀 스크린에 신장 되는 경우 (즉, 풀 스크린 렌더러를 사용하지 않는 경우)는, 상태에 관계없이, 풀 스크린 모드가 설정된 시점에서 변경이 표시된다. 풀 스크린 재생이 필터 그래프내의 필터에 의해 직접 지원 되는 경우는, 풀 스크린 렌더러의 동작에 준해, 액티브한 동안 밖에 풀 스크린으로 전환하지 않는 것도 있다. 풀 스크린 재생을 지원 하는 필터가 그처럼 동작하는 것은, 풀 스크린 재생에 필요한 리소스가 그 시점까지 이용할 수 없는 경우가 있기 때문에 있다. 따라서, 어플리케이션은 정지중에 풀 스크린 모드를 설정하는 것은 피하는 편이 좋다.

이것은 유저 인터페이스의 문맥에도와 같이 들어맞는다. 왜냐하면, 필터 그래프의 정지중에 풀 스크린 모드를 설정 하면, 유저는 풀 스크린 모드로부터 나오는 (즉 원의 어플리케이션에 돌아온다)까지, 그래프의 실행을 시작 할 수 없을 가능성이 있다.

IVideoWindow 를 이행 하는 렌더러는 모두, 그 윈도우가 액티브하게 되었을 때, 또는 비액티브하게 되었을 때에, 필터 그래프 매니저에 이벤트 코드를 송신한다. 풀 스크린 모드의 사이, PID 는 이러한 이벤트 코드를 감시한다. 풀 스크린으로 한 윈도우가 비액티브하게 된 것을 검출 하면, 자동적으로 풀 스크린 모드를 종료해, 어플리케이션 이벤트 큐에 EC_FULLSCREEN_LOST 통지를 송신한다. 이것은 PID 에 의해 행해지는 유일한 개입이다. 이 주제로 설명했던 대로, 그 외 모든 유저 인터페이스는 어플리케이션에 공개되고 있다.

풀 스크린 재생으로 가장 중요한 점의 1 개는, 풀 스크린 모드의 사이, 풀 스크린 윈도우 위에 다른 윈도우를 표시할 수 없는 것이다. 실제, 풀 스크린 렌더러가 표시 모드를 바꾸면(자), 다른 어플리케이션에 대한 GDI 출력이 모두 무효로 되기 (위해)때문에, 풀 스크린 윈도우 위에 윈도우를 표시하는 것은 실제로 불가능하다. 유저가 컴퓨터에 액세스 하려면 , hot key를 사용할 필요가 있다.

PID 는, 풀 스크린 재생의 이행을 위해서(때문에) 최종적으로 어떠한 메카니즘을 사용하는 경우에서도, 재생을 실행하는 윈도우로 항상 메세지 drain 프로퍼티가 설정되도록(듯이) 한다 (메세지 drain는, 렌더러에 송신되는 모든 Windows® 메세지가 전송 되는 윈도우를 지정한다). 그 때문에, 풀 스크린 렌더러가 사용되는 경우에서도, 필터 그래프 매니저의 IVideoWindow 인터페이스로 메세지 drain가 설정되어 있는 한, 모든 메세지가 그 렌더러에게 건네진다.

메세지 drain가 적절한 윈도우로 설정되어 있기 (위해)때문에, 어플리케이션은, 풀 스크린 모드를 이행 하는 필터에 관계없이, 풀 스크린 모드에 대해 모든 마우스 및 키보드 메세지를 수신할 수 있다. 어플리케이션은 거기에 기초를 두어, 시크 등에 대해 hot key 지원을 이행 할 수가 있다. 다만, 프로퍼티는 풀 스크린 모드가 아닐 때에 밖에 설정할 수 없기 때문에, 어플리케이션이 풀 스크린 모드의 사이 밖에 메세지를 포착할 필요가 없는 경우, 풀 스크린 모드를 온으로 하기 전에 메세지 drain를 설정해야 한다. 같이 메세지 drain의 리셋은, 풀 스크린 모드를 오프로 한 다음이 아니면 실시할 수 없다.

어플리케이션에 대해 고려해야 할 이제(벌써) 1 개의 점은, 풀 스크린 모드의 사이,IBasicVideo 로 설정한 전송원직사각형 및 전송처 직사각형이 적용되지 않는다고 하는 것이다. PID 는 풀 스크린 모드로 전환할 때에 이러한 직사각형을 리셋 한다. 이것은, 풀 스크린 지원을 이행 하는 모든 필터가와 같이 IBasicVideo 를 지원 하는 것을 보증할 수 없기 때문에이다.


대체 비디오 렌더러

여기에서는,렌더러의 약간 복잡한 이행 요건의 몇개인가에 대해 설명한다. 비디오에 고유의 요소 (예를 들어 EC_REPAINT 나 그 외의 통지)도 있지만, 이러한 요건은 대부분의 렌더러에 들어맞는다. 여기에서는 특히, 각종의 통지, 상태의 변경, 및 포맷의 변경에 대해 설명한다. 또, 렌더러가 필터 그래프 매니저에 송신하는 통지도 대략적으로 설명한다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • 대체 렌더러를 쓴다
  • 엔드 오브 스트림 통지 및 flushing 통지의 처리
  • 상태의 변경과 포즈의 완료의 처리
  • 종료 처리
  • 동적인 포맷의 변경의 처리
  • 지속 프로퍼티의 처리
  • EC_REPAINT 통지의 처리
  • 풀 스크린 모드에서의 통지의 처리
  • 통지의 요약

대체 렌더러를 쓴다

Microsoft® DirectShow® 는, 윈도우 베이스의 비디오 렌더러를 제공하는 것 외에 런타임 인스톨에서는 풀 스크린 렌더러도 제공한다. DirectShow 의 base class를 사용 하면, 대체 비디오 렌더러를 쓸 수가 있다. 대체 렌더러가 DirectShow 베이스의 어플리케이션과 정상적으로 교환을 실시하기 위해서(때문에)는, 렌더러는 이 주제로 설명하는 가이드 라인에 따르지 않으면 안 된다. CBaseRenderer 및 CBaseVideoRenderer 클래스는, 대체 비디오 렌더러를 이행 할 경우에 이 가이드 라인을 지키는데 도움이 된다. DirectShow 의 개발은 현재도 진행중이므로, 이행을 정기적으로 다시 봐, 렌더러가 최신 버젼의 DirectShow 와의 호환성을 확보하고 있을지 어떨지를 확인하는 것이 중요하다.

여기에서는, 렌더러가 취급해야 할 많은 통지에 대해 설명한다. 그 전에, DirectShow 의 통지를 간단하게 복습해 둔다. 기본적으로, DirectShow 로 발생하는 통지에는 다음의 3 종류의 통지가 있다.

  • 스트림 통지 는, 미디어 스트림내에서 발생해, 어느 필터로부터 다음의 필터에게 건네지는 이벤트이다. 이러한 통지에는, flushing 시작, flushing 종료, 또는 엔드 오브 스트림 통지가 있어,다운 스트림 필터의입력 핀 (예를 들어 IPin::BeginFlush )으로 적절한 메소드를 호출하는 것에 의해 송신된다.
  • 필터 그래프 매니저 통지는, 필터로부터 필터 그래프 매니지에게 건네지는 통지 (예를 들어 EC_COMPLETE )이다. 필터 그래프 매니저의 IMediaEventSink::Notify 메소드를 호출하는 것에 의해 송신된다.
  • 어플리케이션 통지 는, 제어 어플리케이션에 의해 필터 그래프 매니저로부터 취득된다. 어플리케이션은, 필터 그래프 매니저의 IMediaEvent::GetEvent 메소드를 호출해 이러한 이벤트를 취득한다. 자주, 필터 그래프 매니저는, 받은 이벤트를 어플리케이션에 건네준다.

여기에서는, 받은 스트림 통지를 처리해 적절한 필터 그래프 매니저 통지를 송신하는 렌더링 필터의 역할에 대해 설명한다.

엔드 오브 스트림 통지 및 flushing 통지의 처리

엔드 오브 스트림 통지는, 송신해야 할 데이터가 이미 그 이상 없는 것을 검출한업 스트림 필터 (예를 들어소스 필터)가 생성한다. 이 통지는 그래프내의 모든 필터에게 건네져 최종적으로 렌더러에게 건네진다. 이것에 대해서, 렌더러는 EC_COMPLETE 통지를 필터 그래프 매니저에 건네줄 책임을 가진다. 이러한 통지의 처리에 관해서, 렌더러에는 특별한 역할이 주어지고 있다.

입력 핀의 IPin::EndOfStream 메소드가 업 스트림 필터에 불려 가면(자), 렌더러는 엔드 오브 스트림 통지를 받는다. 렌더러는 이 통지를 인식해, 계속해 이미 받고 취해 모든 데이터를 렌더링 해야 한다. 남아 있는 데이터가 모두 수취되면(자), 렌더러는 EC_COMPLETE 통지를 필터 그래프 매니저에 송신해야 한다. EC_COMPLETE 통지는, 엔드 오브 스트림에 도달할 때 마다 렌더러에 의해 1 회만 송신되지 않으면 안 된다. 한층 더 EC_COMPLETE 통지는, 필터 그래프가 실행중이 아닌 한 송신되어서는 안 된다. 따라서, 소스 필터가 엔드 오브 스트림 통지를 송신했을 때에 필터 그래프가 포즈 상태였을 경우는, 필터 그래프가 실행될 때까지는 EC_COMPLETE 가 송신되어서는 안 된다.

엔드 오브 스트림 통지가 통지제가 되면(자), 모든 IMemInputPin::Receive 또는 IMemInputPin::ReceiveMultiple 메소드 호출은 거부되지 않으면 안 된다. 이 경우, 돌려주어지는 에러 메세지로서는 E_UNEXPECTED 가 가장 적합하다.

필터 그래프가 정지상태태에 있을 때는, 캐쉬된 엔드 오브 스트림 통지는 모두 클리어 되지 않으면 안되어, 다음에 시작 되었을 때에 재발송신 되어서는 안 된다. 이것은, 적절한 flushing가 발생하도록(듯이), 필터 그래프 매니저가 필터를 실행하기 직전에 반드시 모든 필터를 포즈 시키기 때문이다. 따라서, 예를 들어 필터 그래프가 포즈 상태로 엔드 오브 스트림 통지가 수취되어 필터 그래프가 정지했을 경우, 렌더러는, 다음에 실행될 때 EC_COMPLETE 통지를 송신해서는 안 된다. 시크가 발생하지 않았던 경우, 소스 필터는, 실행 상태의 전의 포즈 상태에 있는 동안에 자동적으로 다른 엔드 오브 스트림 통지를 송신한다. 한편, 필터 그래프가 정지하고 있는 동안에 시크가 발생했을 경우, 소스 필터는 송신해야 할 데이터를 가지고 있을 가능성이 있다. 따라서, 소스 필터는은 엔드 오브 스트림 통지를 송신하지 않는다.

비디오 렌더러는,EC_COMPLETE 통지를 송신하는 것보다도, 엔드 오브 스트림 통지를 사용하는 것이 많다. 예를 들어 스트림이 재생을 완료해 (즉, 엔드 오브 스트림 통지가 송신되고), 다른 윈도우가 비디오 렌더러 윈도우상에 드러그 되었을 경우, 몇개의 WM_PAINT 윈도우 메세지가 생성된다. 비디오 렌더러를 실행하는 일반적인 방법은, WM_PAINT 메세지를 수신했을 때에, (드로잉(Drawing) 되어야 할 다른 프레임이 수신되면(자) 상정해) 현재의 프레임을 재드로잉(Drawing) 하지 않게 하는 것이다. 다만, 엔드 오브 스트림 통지가 송신되면(자), 렌더러는 대기 상태가 된다. 즉, 렌더러는 실행중이지만 추가의 데이터를 수신하지 않는다. 이러한 상황으로, 렌더러는 보통, 재생 영역을 흑으로 전부 칠한다.

flushing의 처리는, 렌더러에 있어서의 이제(벌써) 1 개의 문제이다. flushing는,BeginFlush 와 EndFlush 의 1 조의 IPin 메소드를 개입시켜 실행된다. 기본적으로, flushing는 렌더러가 처리해야 하는 추가 상태이다. 소스 필터가 EndFlush 를 호출하지 않고 BeginFlush 를 호출하는 것은 부정하다 것으로, 이 상태는 아마 짧아서 연속하지 않았다. 다만 렌더러는, 플래시 이행의 사이에 받은 데이터 또는 통지를 정상적으로 처리해야 한다.

BeginFlush 호출 후에 받은 데이터는, E_UNEXPECTED 를 돌려주는 것에 의해 즉석에서 거부해야 한다. 게다가 캐쉬된 엔드 오브 스트림 통지도, 렌더러가 플래시 될 때 클리어 되지 않으면 안 된다. 보통, 렌더러는 시크에 대해서 플래시 된다. 플래시를 실시하는 것으로, 새로운 샘플이 송신되기 전에 낡은 데이터가 필터 그래프로부터 확실히 클리어 된다. (보통, 스트림의 2 개의 섹션을 계속해 재생하는 경우, 1 개의 섹션이 완료하는 것을 기다리고 나서 시크 커멘드를 발행하는 것보다도, 지연 커멘드를 사용하는 (분)편이 처리적으로 우수하다. )

상태의 변경과 포즈의 완료의 처리

렌더링 필터는, 그 상태가 변화할 경우에 필터 그래프내외의 필터와 같이 동작하지만, 다음과 같은 예외가 있다. 포즈 된 후, 렌더러는 데이터를 큐에 넣는 이후의 실행으로 렌더링을 실시할 준비를 한다. 비디오 렌더러를 정지했을 경우, 렌더러는 이 큐에 들어가 있는 데이터를 보관 유지한다. 이것은, 필터 그래프가 정지상태태 때는 필터는 리소스를 보관 유지해서는 안 된다고 하는 DirectShow 의 규칙에 대한 예외이다.

이 예외의 이유는, 리소스를 보관 유지하는 것으로 렌더러는 WM_PAINT 메세지를 받아들였을 경우에 윈도우를 재드로잉(Drawing) 하는 이미지를 항상 갖는다고 하는 것에 있다. 또 렌더러는, 현재의 이미지의 카피를 요구하는 CBaseControlVideo::GetStaticImage 등의 메소드를 만족하는 이미지를 가진다. 리소스를 보관 유지하는 이제(벌써) 1 개의 효과로서 이미지를 보관 유지하는 것으로 allocater가 데코밋트 되는 것이 없어져, 이미지 버퍼를 이미 할당할 수 있고 있으므로 다음 상태 변경이 보다 신속히 행해지게 된다.

비디오 렌더러는, 실행중에게만, 샘플을 렌더링 및 해방해야 한다. 포즈 상태 때는, 필터가 샘플을 렌더링 하는 것은 있는 (예를 들어 윈도우내에서 스태틱 포스터 이미지를 드로잉(Drawing) 하면나무)가, 샘플을 해방해서는 안 된다. 오디오 렌더러는, 포즈 상태 때는 렌더링을 실시하지 않는다 (다만, 예를 들어 wave 디바이스의 준비등의 다른 처리는 실시할 수 있다). 샘플을 렌더링 하는 타임은, 샘플의스트림 타임과IMediaControl::Run 메소드에의 파라미터로서 건네받은기준 타임을 조합하는 것에 의해 구할 수 있다. 렌더러는, 종료 타임 이하의 시작 타임을 가지는 샘플을 거부해야 한다.

어플리케이션이 필터 그래프를 포즈 하면, 필터 그래프는 렌더러로 큐에 넣어진 데이터가 존재할 때까지 IMediaControl::Pause 메소드로부터 복귀하지 않는다. 이것을 확실히 하기 위해서, 렌더러가 포즈 되었을 때에 렌더링 하는 데이터가 없는 경우는 S_FALSE 를 돌려주지 않으면 안 된다. 큐에 넣어지고 있는 데이터가 있는 경우는, S_OK 를 돌려줄 수가 있다.

필터 그래프 매니저는, 필터 그래프를 포즈 할 경우에 모든 반환값을 체크해, 렌더러가 데이터를 큐에 넣은 것 확인한다. 1 개(살) 또는 복수의 필터의 준비가 갖추어지지 않은 경우, 필터 그래프 매니저는 GetState 호출에 의해 그래프내의 그 필터를 폴링 한다. GetState 메소드는, 타임 아웃 파라미터를 취한다. 상태의 변경을 완료하기 전에 데이터가 도착하는 것을 기다리고 있는 필터 (보통은 렌더러)는,GetState 메소드가 타임 아웃 하면 VFW_S_STATE_INTERMEDIATE 를 돌려준다. 데이터가 렌더러에 도착했을 경우는,GetState 는 S_OK 를 즉석에서 돌려주지 않으면 안 된다.

중간 상태 및 완료 상태의 어느 쪽에 대해도, 보고되는 필터 상태는 State_Paused 가 된다. 필터의 준비가 갖추어지고 있을지 어떨지는, 반환값에 의해 나타난다. 렌더러가 데이터의 도착을 기다리고 있는 경우, 소스 필터는 엔드 오브 스트림 통지를 송신해, 상태 변경을 완료해야 한다.

모든 필터에 대해 렌더링 하는 데이터의 준비가 갖추어지면(자), 필터 그래프는, 포즈 상태의 변경을 완료한다.

종료 처리

비디오 렌더러는, 유저로부터의 종료 이벤트를 정상적으로 처리해야 한다. 이것은, 윈도우를 정상적으로 비표시로 하는 것과 동시에, 윈도우의 표시가 다음에 강제당했을 때에 어떻게 해야 하는가를 아는 것을 의미한다. 비디오 렌더러는, 윈도우를 언제 파기 (정확하게는, 렌더러가 언제 필터 그래프로부터 삭제될까)해 리소스를 해방할까를 필터 그래프 매니저에 통지해야 한다.

유저가 비디오 윈도우를 닫았을 경우 (예를 들어 Alt + F4 키를 눌렀을 경우), 관습에서는 윈도우를 즉석에서 비표시로 해,EC_USERABORT 통지를 필터 그래프 매니저에 송신한다. 이 통지는 어플리케이션에게 건네져 어플리케이션은 그래프의 재생을 중지한다. EC_USERABORT 를 송신한 후는, 비디오 렌더러는 배송되는 모든 샘플을 거부해야 한다.

렌더러는 중단( abort) 플래그를 온에 유지하지 않으면 안되어, 중지되었을 때에, 어플리케이션이 유저 액션을 오버라이드(override) 해 (필요하면) 그래프의 재생을 속행하는 것으로 오도록(듯이) 플래그를 리셋 해야 한다. 비디오의 실행중에 Alt + F4 키가 밀렸을 경우, 윈도우는 비표시가 되어, 그 이후에 배송된 샘플은 모두 거부된다. 윈도우가 그 이후도 표시되는 경우 (IVideoWindow::put_Visible ),EC_REPAINT 통지가 생성되어서는 안 된다.

또, 비디오 렌더러는, 종료할 경우에 EC_WINDOW_DESTROYED 통지를 필터 그래프에 송신해야 한다. 이 처리는, 실제의 비디오 윈도우가 파기될 때까지 기다리는 것보다도, 렌더러의 IBaseFilter::JoinFilterGraph 메소드가 (렌더러가 필터 그래프로부터 삭제 되려고 하고 있는 것을 나타낸다) Null 파라미터를 취해 불려 갔을 때에 실시하는 것이 최적이다. 이 통지를 송신 하면, 필터 그래프 매니저의 PID 가, 윈도우의 포커스에 의존한 리소스를 다른 필터 (예를 들어 오디오 디바이스)에 건네줄 수 있게 된다.

동적인 포맷의 변경의 처리

DirectShow 의 비디오 렌더러는, 효율적으로 드로잉(Drawing) 할 수 있는 비디오 포맷 밖에 받아들이지 않는다. 예를 들어 윈도우 베이스의 런타임 렌더러는, 현재의 디스플레이 디바이스 모드에 일치하는 RGB 포맷 (예를 들어 디스플레이가 65,536 색으로 설정되어 있는 경우는 RGB565)만을 받아들인다. 또, 마지막 수단으로서 비디오 렌더러는, 대부분의 디스플레이 카드로 효율적인 드로잉(Drawing)가 가능한 8 비트의 팔레트화 된 포맷을 받아들인다. Microsoft® DirectDraw® 를 로드했을 경우, 렌더러는 DirectDraw 표면에 기입하거나 디스플레이 하드웨어로부터 직접 드로잉(Drawing) 할 수 있는 것으로 전환하도록(듯이) 다음에 소스 필터에 요구하는 일이 있다. 경우에 따라서는, 비디오의 재생중에 렌더러의 업 스트림 필터가 비디오 포맷을 변경하려고 하는 일도 있다. 이러한 조작은, 비디오 스트림이 팔레트의 변경을 실시했을 때에 자주(잘) 발생한다. 동적인 포맷 변경을 시작 하는 것은, 대부분의 경우 비데오데콘프렛사이다.

포맷을 동적으로 변경하려고 하는 업 스트림 필터는, 렌더러의 입력 핀으로 반드시 IPin::QueryAccept 메소드를 호출하지 않으면 안 된다 (CTransformFilter 에 근거하는 필터의 경우, 이것은 CTransformFilter::CheckInputType 로 이행 된다). 업 스트림 필터가 동적으로 변경하는 대상으로 해 렌더러가 어느 포맷을 허가할까는 부정이다. 다만, 최저한에서도 렌더러는 업 스트림 필터가 팔레트를 변경하는 것을 허가해야 한다. 미디어 타입을 변경하는 경우, 업 스트림 필터는 새로운 타입으로 배송된 최초의 샘플에 포맷을 어태치 한다. 렌더링 되는 것을 기다리고 있는 큐에 많은 샘플이 있는 경우, 렌더러는 타입이 변경된 샘플이 실제로 렌더링 될 때까지, 포맷의 변경을 늦추지 않으면 안 된다.

포맷의 변경을 검출할 때 마다, 비디오 렌더러는 EC_DISPLAY_CHANGED 통지를 송신해야 한다. 대부분의 비디오 렌더러는 접속중에 포맷을 선택해, 그 포맷이 GDI 를 개입시켜 효율적으로 드로잉(Drawing) 되도록(듯이) 한다. 유저가 컴퓨터를 재기동하지 않고 현재의 디스플레이 모드를 변경했을 경우, 렌더러는 그 자체의 이미지 포맷 접속이 불량이다고 판단해 이 통지를 송신해야 한다. 제 1 파라미터는, 재접속이 필요한 핀으로 한다. 필터 그래프 매니저는, 필터 그래프를 정지해 핀의 재접속을 하는 대로 준비한다. 거기에 계속되는 재접속동안, 렌더러는 보다 적절한 포맷을 받아들일 수가 있다.

스트림내에서 팔레트의 변경을 검출할 때 마다, 비디오 렌더러는 EC_PALETTE_CHANGED 통지를 필터 그래프 매니저에 송신해야 한다. DirectShow 비디오 렌더러는, 팔레트가 동적으로 변경되었는지 어떠했는지를 검출한다. 비디오 렌더러는, 송신된 EC_PALETTE_CHANGED 통지를 필터로 제외하는 것 외에, 필요한 팔레트의 생성, 인스톨, 및 삭제 처리의 양을 줄이는 목적으로, 이러한 동작을 실시한다.

마지막으로, 비디오 렌더러는 비디오의 사이즈가 변경된 것을 검출하는 일이 있다. 이 경우, 비디오 렌더러는 EC_VIDEO_SIZE_CHANGED 통지를 송신해야 한다. 어플리케이션은 이 통지를 사용해 복합 문서내의 공간을 조정할 수가 있다. 비디오의 실제의 넓이는,IBasicVideo 컨트롤 인터페이스를 사용해 취득할 수 있다. DirectShow 렌더러는, 이러한 이벤트를 송신하기 전에, 비디오의 사이즈가 변경되었는지 어떠했는지를 검출한다.

지속 프로퍼티의 처리

IBasicVideo 및 IVideoWindow 인터페이스를 개입시켜 설정되는 모든 프로퍼티는, 접속간에 지속성을 가진다고 보인다. 따라서, 렌더러의 접속 해제 및 접속 처리는, 윈도우의 사이즈, 위치, 또는 스타일에 영향을 미쳐서는 안 된다. 그러나, 접속간에 비디오 넓이가 변경되었을 경우, 렌더러는 전송원직사각형 및 전송처 직사각형을 그 디폴트에 리셋 해야 한다. 전송원 및 전송처의 위치는,IBasicVideo 인터페이스를 개입시켜 설정된다.

IBasicVideo 및 IVideoWindow 는, 어느쪽이나 프로퍼티에의 충분한 액세스를 제공해, 인터페이스내의 모든 데이터를 지속 포맷으로 보존 및 복원하는 것을 가능하게 한다. 이것은, 편집 세션중에 필터 그래프의 정확한 구성 및 프로퍼티를 보존해 다음에 복원하지 않으면 안 되는 어플리케이션에 있어 도움이 된다.

EC_REPAINT 통지의 처리

EC_REPAINT 통지는, 렌더러가 포즈 또는 정지상태태 때만 송신된다. 이 통지는, 렌더러가 데이터를 필요로 하고 있는 것을 필터 그래프 매니저에 통지한다. 이러한 통지의 1 개를 받았을 때에 필터 그래프가 정지상태태였을 경우, 필터 그래프 매니저는 필터 그래프를 포즈 상태로 해, (GetState 호출에 의해) 모든 필터가 데이터를 받는 것을 기다려, 재차 필터 그래프를 정지시킨다. 정지상태태 때, 비디오 렌더러는 후속의 WM_PAINT 메세지를 처리할 수 있도록(듯이) 이미지를 보관 유지해야 한다.

따라서, 정지 또는 포즈 상태로 비디오 렌더러가 WM_PAINT 메세지를 받아들여, 윈도우를 드로잉(Drawing) 하는 것이 없는 경우는,EC_REPAINT 를 필터 그래프 매니저에 송신해야 한다. EC_REPAINT 통지가 포즈 상태로 수취되었을 경우, 필터 그래프 매니저는, 현재 위치를 사용해 IMediaPosition::put_CurrentPosition 를 호출한다 (즉 현재 위치에의 시크). 이것에 의해, 소스 필터는 필터 그래프를 플래시 해, 새로운 데이터가 필터 그래프를 개입시켜 송신된다.

렌더러는, 한 번 남을 수 있는들의 통지중 1 개(살)만을 송신해야 한다. 따라서, 통지를 송신했을 경우, 렌더러는 몇개의 샘플이 배송될 때까지 그 이상의 데이터가 송신되지 않는 것을 보증해야 한다. 이것을 실시하는 종래의 방법은, 플래그를 사용해 재드로잉(Drawing)가 송신 가능한가 어떤가를 나타내는 방법이다. 이 경우, 플래그는,EC_REPAINT 통지가 송신된 후에 오프로 설정된다. 이 플래그는, 데이터가 배송되거나 입력 핀이 플래시 되었을 때에 리셋 되지 않으면 안 된다. 다만, 엔드 오브 스트림이 입력 핀에 통지제의 경우는 이것에 들어맞지 않는다.

렌더러가 그 EC_REPAINT 통지를 감시하지 않으면 필터 그래프 매니저는 EC_REPAINT 요구로 넘치게 된다 (매우 고가의 처리가 된다). 예를 들어 드로잉(Drawing) 하는 이미지를 렌더러가 가지지 않고, 풀 드러그 조작으로 다른 윈도우가 렌더러의 윈도우상을 드러그 되었을 경우, 렌더러는 복수의 WM_PAINT 메세지를 받아들인다. 이러한 메세지 가운데 최초의 것만이 렌더러로부터 필터 그래프 매니저에의 EC_REPAINT 이벤트 통지를 생성해야 한다.

렌더러는, 그 입력 핀을 EC_REPAINT 통지의 제 1 파라미터로서 송신해야 한다. 이것에 의해, 어태치 된출력 핀에 대해서 IMediaEventSink 의 조회가 거행되어 지원 되고 있는 경우는 EC_REPAINT 통지가 최초로 송신된다. 이것에 의해, 필터 그래프 이전에 출력 핀이 재드로잉(Drawing)를 취급하는 것이 가능하게 된다. 필터 그래프가 정지상태태의 경우, 데코밋트 된 렌더러 allocater로부터의 버퍼를 이용할 수가 없기 때문에, 이 처리는 행해지지 않는다.

출력 핀이 요구를 처리하지 못하고, 필터 그래프가 실행중의 경우,EC_REPAINT 통지는 무시된다. 출력 핀은,IMediaEventSink::Notify 로부터 NOERROR (S_OK)를 돌려주는 것에 의해, 재드로잉(Drawing) 요구를 정상적으로 처리한 것을 통지해야 한다. 출력 핀은 필터 그래프 매니저의 워커 thread로 불려 간다. 즉, 렌더러가 출력 핀을 직접 호출하지 않게 해 데드 록이 회피되고 한다. 필터 그래프가 정지상태태 또는 포즈 상태로 출력이 요구를 처리하지 않는 경우는, 디폴트의 처리를 한다.

풀 스크린 모드에서의 통지의 처리

필터 그래프의 IVideoWindow PID 는, 풀 스크린 재생을 관리한다. 이 PID 는, 스페셜리스트 풀 스크린 렌더러를 위해서(때문에) 비디오 렌더러를 스왚 아웃 하거나 렌더러의 윈도우를 풀 스크린으로 확대하거나 혹은 렌더러에 풀 스크린 재생을 직접 이행 시킨다. 풀 스크린 프로토콜을 사용하기 위해서(때문에)는, 비디오 렌더러는 윈도우가 액티브 또는 비액티브하게 될 때 마다 EC_ACTIVATE 통지를 송신해야 한다. 즉, 렌더러가 받는 각각의 WM_ACTIVATEAPP 메세지에 대해서 EC_ACTIVATE 통지를 송신해야 한다.

렌더러를 풀 스크린 모드로 사용할때, 이러한 통지는 풀 스크린 모드의 변환을 관리한다. 보통, 윈도우의 비액티브는, 유저가 Alt + Tab 키를 눌러 다른 윈도우로 전환할 때 발생한다. DirectShow 풀 스크린 렌더러는 이것을 큐로서 일반적인 렌더링 모드에 돌아온다.

풀 스크린 모드의 종료시에 EC_ACTIVATE 통지가 필터 그래프 매니저에 송신되면(자), 필터 그래프 매니저는 EC_FULLSCREEN_LOST 통지를 제어 어플리케이션에 송신한다. 어플리케이션은, 예를 들어 이 통지를 사용해 풀 스크린 버튼 상태를 복원한다. EC_ACTIVATE 통지는, 비디오 렌더러로부터 큐가 건네받았을 때의 풀 스크린 변환을 관리하기 위해서 DirectShow 내부에서 사용된다.

통지의 요약

렌더러가 송신 가능한 필터 그래프 통지를 이하에 나타낸다.

이벤트 통지 | 설명
EC_ACTIVATE | 풀 스크린 렌더링 모드의 비디오 렌더러에 의해, 받은 각각의 WM_ACTIVATEAPP 메세지에 대해 송신된다.
EC_COMPLETE | 모든 데이터가 렌더링 된 다음에 렌더러에 의해 송신된다.
EC_DISPLAY_CHANGED | 디스플레이 포맷이 변경되었을 때에 비디오 렌더러에 의해 송신된다.
EC_PALETTE_CHANGED | 비디오 렌더러가 스트림내에서 팔레트의 변경을 검출할 때 마다 송신된다.
EC_REPAINT | WM_PAINT 메세지가 받아 들여져 표시하는 데이터가 없을 때에, 정지 또는 포즈 상태의 비디오 렌더러에 의해 송신된다. 이것에 의해, 필터 그래프 매니저는, 디스플레이에 드로잉(Drawing) 하는 프레임을 생성한다.
EC_USERABORT | 유저가 종료를 요구한 것을 통지하기 위해서 비디오 렌더러에 의해 송신된다 (예를 들어 유저가 비디오 윈도우를 닫았을 경우).
EC_VIDEO_SIZE_CHANGED | 네이티브 비디오 사이즈의 변경이 검출될 때 마다 비디오 렌더러에 의해 송신된다.
EC_WINDOW_DESTROYED | 필터가 삭제 또는 파기되었을 때에 비디오 렌더러에 의해 송신되어 윈도우의 포커스에 의존하는 리소스를 다른 필터에 건네줄 수 있도록(듯이) 한다.


비디오 렌더러에 있어서의 전송원직사각형과 전송처 직사각형

비디오 미디어 타입의 VIDEOINFO ,VIDEOINFOHEADER , 및 VIDEOINFOHEADER2 포맷 구조체에는 3 개의 사이즈가 있다. 여기에서는, 그 내용과 기능에 대해 설명한다.

우선, 이러한 구조체의 bmiHeader 멤버에 사이즈가 있다. bmiHeader 멤버는 BITMAPINFOHEADER 구조체이며, 독자적인 폭멤버와 높이 멤버로서 bmiHeader.biWidth 및 bmiHeader.biHeight 를 가진다.

또, 각 구조체의 rcSource 멤버에 직사각형이 있다. 게다가 각 구조체의 rcTarget 멤버에도 직사각형이 있다.

2 개의 필터 A 와 B 가 있어, 이 2 개(살)이 특정의 비디오 미디어 타입으로 서로 접속되고 있다고 한다. A 가 좌측 (업 스트림), B 가 우측 (다운 스트림)이다.

필터 A 와 필터 B 의 사이의 버퍼에는, 사이즈 (bmiHeader.biWidth,bmiHeader.biHeight)가 있다. 필터 A 는 rcSource 에 의해 결정되는 입력 비디오의 일부를 받아, 그 비디오를 버퍼의 rcTarget 부분에 맞추어 신축한다. 입력 비디오로 사용되는 부분은, 필터 A 및 B 가 최초로 접속되는 미디어 타입의 (biWidth,biHeight) 사이즈와rcSource 와의 비율에 의해 정해진다. rcSource 가 하늘인 경우, 필터 A 는 그 입력 비디오의 전체를 사용한다. rcTarget 가 하늘인 경우, 필터 A 는 출력 버퍼의 전체에 비디오를 거둔다.

예를 들어, 필터 A 가 160 × 120 픽셀의 비디오 데이터를 받으면(자) 가정한다. 또, 필터 A 가 다음의 미디어 타입으로 필터 B 에 접속되고 있다고 한다.

(biWidth, biHeight) : 320, 240
rcSource : (0, 0, 0, 0)
rcTarget : (0, 0, 0, 0)

이 경우, 필터 A 는 받은 비디오를 x 방향과 y 방향의 양쪽 모두에 대해 2 배에 신장 해, 320 × 240 의 출력 버퍼에 거둔다.

이제(벌써) 1 개의 예로서 필터 A 가 160 × 120 의 비디오 데이터를 받아, 다음의 미디어 타입으로 필터 B 에 접속되고 있다고 한다.

(biWidth, biHeight) : 320, 240
rcSource : (0, 0, 160, 240)
rcTarget : (0, 0, 0, 0)

rcSource 멤버는 접속된 버퍼 사이즈 (320, 240)에 대한 값이다. 지정된 rcSource (0, 0, 160, 240)는 버퍼의 왼쪽 반이기 (위해)때문에, 필터 A 는 입력 비디오의 왼쪽 반, 즉 (0, 0, 80, 120) 부분을 받아, 비디오를 사이즈 (320, 240)에 (x 방향으로 4 배, y 방향으로 2 배에) 신장 해, 320 × 240 의 출력 버퍼에 거둔다.

여기서, 필터 A 가 GetBuffer 를 호출해, 돌려주어진 미디어 샘플에 어태치 된 미디어 타입에 의해, 필터 B 가 필터 A 에 그것까지와 다른 사이즈 또는 종류의 비디오를 요구하고 있는 것이 나타난다. 새로운 미디어 타입은 다음과 같다.

(biWidth, biHeight) : 640, 480
rcSource : (0, 0, 160, 120)
rcTarget : (0, 0, 80, 60)

이 경우, 미디어 샘플에는 사이즈가 640 × 480 의 버퍼가 포함된다. rcSource 멤버는, 새로운 미디어 타입 (640, 480)은 아니고 최초로 접속되고 있던 미디어 타입 (320, 240)에 근거한다. 따라서,rcSource 는 입력 비디오의 좌상의 25% 가 사용되는 것을 지정한다. rcTarget 의 것 (0, 0, 80, 60)에 따라, 입력 비디오의 이 부분은 640 × 480 의 출력 버퍼의 좌상의 (80, 60) 픽셀에 배치된다. 필터 A 는 160 × 120 의 비디오를 받기 (위해)때문에, 입력 비디오의 좌상은 (80, 60)된다. 이것은 출력 비트 맵과 같은 사이즈이며, 신축은 불필요하다.

필터 A 는 출력 버퍼의 나머지의 픽셀에는 데이터를 배치하지 않고, 그 부분의 비트는 조작하지 않는다. rcSource 멤버는, 필터 A 와 필터 B 의 사이에 최초로 접속되고 있던 미디어 타입의 biWidth 와 biHeight 에 의해 제한된다. rcTarget 는, 미디어 샘플의 새로운 biWidth 와 biHeight 에 의해 제한된다. 위의예에서는,rcSource 는 (0, 0, 320, 240)의 경계를 나오지 못하고,rcTarget 는 (0, 0, 640, 480)의 경계를 나올 수가 없다.


캡춰 필터

여기에서는, 캡춰 필터를 생성 하는 방법에 대해 설명한다.

  • 비디오 캡춰 필터의 생성
  • 오디오 캡춰 필터의 생성


비디오 캡춰 필터의 개발

이 주제에서는, 비디오 캡춰 필터를 생성 할 때에 고려해야 할 중요한 점에 대해 설명한다. Microsoft® DirectShow® 에는 표준의 VFW 캡춰 필터가 포함되어 있다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • 캡춰 핀과 프리뷰 핀의 요건
  • 캡춰와 프리뷰의 최적화 (옵션)
  • 비디오 캡춰 필터의 등록
  • 데이터의 생성
  • 개개의 스트림의 제어
  • 타임 스탬프
  • frame rate
  • IAMDroppedFrames 의 이행
  • 필요한 인터페이스

캡춰 핀과 프리뷰 핀의 요건

캡춰 필터의 캡춰 핀과 프리뷰 핀 (존재하는 경우)은,IKsPropertySet 인터페이스를 지원 할 필요가 있다. 어플리케이션은 이 인터페이스를 호출해, AMPROPSETID_Pin 프로퍼티 세트의 AMPROPERTY_PIN_CATEGORY 의 값을 취득하는 것으로써 "어느 카테고리의 핀일까 " 를 묻는다. 반환값은, 보통, PIN_CATEGORY_CAPTURE 또는 PIN_CATEGORY_PREVIEW 의 몇개의 GUID 이다. 자세한 것은, 「핀 프로퍼티 세트」를 참조할것. 캡춰 필터는 IKsPropertySet 를 지원 할 필요가 있다. 지원되어 있지 않으면 어플리케이션은 필터 그래프내에서 필터를 접속하는 방법을 지시할 수가 없다.

핀에는 임의의 이름을 붙일 수가 있어 그 외의 필요한 목적을 위해서(때문에)출력 핀을 추가할 수 있다. 핀의 이름이 치르다 (~) 문자로 시작되는 경우, 어플리케이션이 IGraphBuilder::RenderFile 를 호출해도, 필터 그래프는 그 핀에 대해서 자동적인 렌더링을 실시하지 않는다. 예를 들어, 캡춰 필터에 캡춰 핀과 프리뷰 핀이 양쪽 모두 있어, 캡춰 핀에 "~capture" , 프리뷰 핀에 "preview" 라는 이름을 붙였다고 한다. 이 경우, 어플리케이션이 그래프내에서 필터를 렌더링 하면, 프리뷰 핀은 비디오 렌더러에 접속되어 캡춰 핀에는 아무것도 접속되지 않는다. 디폴트로 이러한 설정을 사용하는 것은 일반적이다. 이것은, 렌더링을 실시하지 않는 단순한 정보용의 핀이나, 프로퍼티를 설정하기 위해서 열거할 필요가 있는 핀 등에도 응용할 수 있다.

접머리 글자 치르다 (~)는,RenderFile 와 인텔리전트 접속 (IGraphBuilder::Connect )의 동작에게만 영향을 준다. 그런데도, 이 프로퍼티를 포함하고 있는 핀이 IPin::Connect 메소드를 이행 하고 있으면, 그러한 핀의 접속에 인텔리전트인 접속을 사용할 수 있다. 그러나, 이름이 치르다 문자로 시작되는 접속을 완료하기 위해서 중간 필터를 사용하고 있는 경우는, 인텔리전트 접속에 즈음하여 그 필터의 출력 핀이 접속될 것은 없다.

오디오 캡춰 필터의 상세한 것에 대하여는, 「오디오 캡춰 핀의 요건」을 참조할것.

다음의 샘플 코드에, 캡춰 핀에 IKsPropertySet 를 이행 하는 방법을 나타낸다.

//
// 핀 카테고리 - 이것이 캡춰 핀인 것을 나타낸다.
//

HRESULT CMyCapturePin::Set(REFGUID guidPropSet, DWORD dwPropID,
LPVOID pInstanceData, DWORD cbInstanceData,
                           LPVOID pPropData, DWORD cbPropData)
{
    return E_NOTIMPL;
}

// 프로퍼티를 취득하기 위해서, 호출원래는 호출한 함수가 데이터를 저장하기 위한
// 버퍼를 할당한다. 필요한 버퍼 사이즈를 결정하기 위해서(때문에), pPropData=NULL 및
// cbPropData=0 를 지정해 Get 를 호출한다.
HRESULT CMyCapturePin::Get(REFGUID guidPropSet, DWORD dwPropID,
LPVOID pInstanceData, DWORD cbInstanceData, LPVOID pPropData,
                           DWORD cbPropData, DWORD *pcbReturned)
{
if (guidPropSet ! = AMPROPSETID_Pin)
return E_PROP_SET_UNSUPPORTED;

if (dwPropID ! = AMPROPERTY_PIN_CATEGORY)
return E_PROP_ID_UNSUPPORTED;

    if (pPropData == NULL && pcbReturned == NULL)
return E_POINTER;

    if (pcbReturned)
        *pcbReturned = sizeof(GUID);

    if (pPropData == NULL)
return S_OK;

    if (cbPropData < sizeof(GUID))
        return E_UNEXPECTED;

    *(GUID *) pPropData = PIN_CATEGORY_CAPTURE;
return S_OK;
}

// QuerySupported 는 E_NOTIMPL 를 돌려주는지, 또는, 프로퍼티 세트와 프로퍼티의
// 취득이나 설정이 지원 되고 있는지 어떤지를 올바르게 가리킬 필요가 있다.
// S_OK 는, 프로퍼티 세트와 프로퍼티 ID 의 편성이 올바른 일을 나타낸다.
HRESULT CMyCapturePin::QuerySupported(REFGUID guidPropSet, DWORD dwPropID,
                                      DWORD *pTypeSupport)
{
if (guidPropSet ! = AMPROPSETID_Pin)
return E_PROP_SET_UNSUPPORTED;

if (dwPropID ! = AMPROPERTY_PIN_CATEGORY)
return E_PROP_ID_UNSUPPORTED;

    if (pTypeSupport)
        *pTypeSupport = KSPROPERTY_SUPPORT_GET;
return S_OK;
}

캡춰와 프리뷰의 최적화 (옵션)

필터가 동작중으로, 데이터의 캡춰를 실시하고 있을 때는, 프리뷰 핀과 캡춰 핀의 양쪽 모두로부터 프레임의 카피를 송신할 필요가 있다. 하드웨어 지원 (오버레이등)에 의한 프리뷰가 가능해, 프리뷰 핀을 사용하고 있는 경우는, 그 프리뷰 핀에 대해서 IMemInputPin 인터페이스 대신에 IOverlay 인터페이스전송을 사용할 수 있다. IOverlay 의 사용은 옵션이다. 하드웨어 지원에 의한 프리뷰를 실행할 수 없는 경우는, 빈 시간이 있을 때만 프리뷰 핀으로부터 프레임을 보낸다. 프레임을 드롭 할 우려가 있는 경우는, 이것을 실시하지 않는다. 캡춰 핀이 우선된다.

예를 들어, 캡춰 핀으로부터 즉시 보내야 할 것이 1 개도 없고,다운 스트림 필터가 캡춰 핀으로부터 이전에 배송된 버퍼를 모두 해방되어 있는 경우만, 프리뷰 핀으로부터 프레임을 배송할 수가 있다.

데이터의 포맷을 1 종류 밖에 캡춰 하지 못하고, 그 때문에(위해) 프리뷰 핀과 캡춰 핀이 같은 미디어 타입을 생성할 필요가 있는 경우, 또는, 핀을 적절히 재접속하는 방법의 상세를 알고 싶은 경우는, 앞에 읽어 진행된다. 그 이외의 경우는, 이 토픽을 읽을 필요는 없다.

프리뷰 핀과 캡춰 핀으로부터 같은 포맷의 데이터를 보낸다. 필터 그래프 매니저가 캡춰 핀을 다른 포맷으로 재접속했을 경우는, 프리뷰 핀을 같은 포맷으로 재접속하지 않으면 기능하지 않는다. 캡춰 핀이 접속되고 있어 프리뷰 핀이 접속되어 있지 않은 경우는, 캡춰 핀과 같은 미디어 타입으로 프리뷰 핀만 접속할 필요가 있다. 2 개의 핀은, 일치하고 있지 않으면 안 된다.

다음의 샘플 코드에, 적절한 재접속의 순서를 나타낸다.

// 프리뷰 핀의 접속처의 필터가 새로운 미디어 타입을 받아들이지 않는 경우,
// 캡춰 핀이 그 미디어 타입을 받아들일 수 없다. 프리뷰
// 핀은, 항상 캡춰 핀과 같은 타입을 출력해야 한다.
CCapturePin::CheckMediaType(CMediaType *pmt)
{
    if (m_pMyPreviewPin->IsConnected()) {
        // 프리뷰 핀의 접속은 이 타입과 같은가?
          if (m_pMyPreviewPin->GetConnected() ->QueryAccept(pmt) ! = NOERROR) {
            // 프리뷰 핀은 이 새로운 타입에서는 재접속할 수 없다.
            return E_INVALIDARG;
        }
    }

    // 캡춰 핀의 접속처를 알면, 이 미디어 타입으로
    // 좋은지 어떤지 결정할 수 있을 것이다. 그러나, 그 필요는
    // 없다. 캡춰 핀이 접속되면(자), 같은 포맷을
    // 사용해 재접속된다.

    return NOERROR;
}

// 프리뷰 핀이 받아들이고 가능한 미디어 타입은,
// 캡춰 핀이 사용하고 있는 것 뿐이다.
CPreviewPin::CheckMediaType(CMediaType *pmt)
{
    CMediaType cmt = m_pMyCapturePin->m_mt;
     if (m_pMyCapturePin->IsConnected() && *pmt ! = cmt)
        // 프리뷰 핀은 캡춰 핀과 같다
        // 포맷이 아니면 접속할 수 없다.
        return E_INVALIDARG;

    else if (! m_pMyCapturePin->IsConnected())
        // 캡춰 핀의 접속처를 알면, 이 미디어 타입으로
        // 좋은지 어떤지 결정할 수 있을 것이다. 그러나, 그 필요는
        // 없다. 캡춰 핀이 접속되면(자), 같은 포맷을
        // 사용해 재접속된다.

    // 캡춰 핀이 접속되고 있어, 이것이 같은 미디어 타입이면,
    // OK 이다.
    return NOERROR;
}

// 캡춰 핀은, 특정의 미디어 타입을 사용하도록(듯이) 지정되고 있다.
// 프리뷰 핀에도, 같은 미디어 타입을 사용시키지 않으면 안 된다.
CCapturePin::SetMediaType(CMediaType *pmt);
{
if (m_pMyPreviewPin->IsConnected()) {

    // 이 미디어 타입으로 프리뷰 핀을 재접속할 필요가 있다.
      if (m_pMyPreviewPin->GetConnected() ->QueryAccept(pmt) == NOERROR) {

        // 프리뷰 핀이 접속되고 있는 다른 필터는, 이 새롭다
        // 미디어 타입을 받아들일 수가 있으므로, 그대로재접속한다.
        m_pFilter->m_pGraph->Reconnect(m_pMyPreviewPin);
    }
    }
}

비디오 캡춰 필터의 등록

필터는 비디오 캡춰 필터 카테고리에 등록할 필요가 있다. 상세한 것에 대하여는,AMovieDllRegisterServer2 의 설명을 참조할것.

데이터의 생성

캡춰 핀 및 프리뷰 핀에서의 데이터의 생성은, 필터 그래프가 실행 상태의 경우에만 실시한다. 필터 그래프가 포즈 하고 있는 동안은, 핀으로부터 데이터를 송신해서는 안 된다. 만약 송신 하면, 필터 그래프에 혼란이 생긴다. 이것을 피하려면 CBaseFilter::GetState 함수로부터 VFW_S_CANT_CUE 를 돌려주는 것으로, 필터 그래프에 대해서, 포즈중은 데이터를 송신하지 않는 것을 경고한다. 이것을 다음의 코드에 나타낸다.

CMyVidcapFilter::GetState(DWORD dw, FILTER_STATE *State)
{
*State = m_State;
if (m_State == State_Paused)
return VFW_S_CANT_CUE;
else
return S_OK;
}

개개의 스트림의 제어

출력 핀은 모두 IAMStreamControl 인터페이스를 지원 할 필요가 있기 (위해)때문에, 어플리케이션은 각 핀을 개별적으로 온 또는 오프로 할 수 있다 (예를 들어, 캡춰 하지 않고 프리뷰 하는 경우 등). IAMStreamControl 를 사용 하면, 다른 그래프를 재생성 하지 않아도, 프리뷰와 캡춰의 사이에 바꿀 수가 있다.

타임 스탬프

프레임을 캡춰 해 송신하는 경우, 프레임이 캡춰 되었을 때의 그래프의 클락의 시각에 의해, 프레임에타임 스탬프를 기록한다. 종료 타임은, 시작 타임에 시간폭을 더한 값이다. 예를 들어, 1 초간에 10 프레임이라고 하는 레이트로 캡춰 되어 캡춰 된 시점에서 그래프의 클락이 200,000,000 단위를 나타내고 있는 경우, 샘플의 타임 스탬프는 (200000000, 201000000)된다 (1 초 쯤 10,000,000 단위).

프리뷰 프레임에는 지연 시간의 문제가 있으므로, 타임 스탬프를 기록하지 않는 편이 좋다. 샘플의 타임 스탬프가 프리뷰 핀으로부터 출력되었을 때의 그래프의 시각인 경우, 샘플이 렌더러에 도착하기까지 지연이 생기기 (위해)때문에, 지연 시간이 발생한다. 따라서, 렌더러는 시간을 절약해 "지연을 되찾는 " 위해(때문에), 그 샘플을 드로잉(Drawing) 하지 않는 경우가 있다. 이것은, 라이브 스트림에서는 용서되지 않는다. IAMStreamControl 를 이행 하려면 타임 스탬프가 필요하다. 그 때문에, 프리뷰 핀에는 스트림 컨트롤을 이행 하지 않는지, 처리 기다리는 시작 또는 정지 요구가 있는 경우만 프리뷰 핀 샘플에 타임 스탬프를 기록하든가, 혹은 지연 시간의 문제를 허용 하는지, 의 어느쪽이든을 선택한다.

배송하는 샘플의미디어 타임을 설정해야 한다. 또, 캡춰 핀에 대한 보통의 타임 스탬프의 설정도 필요하다. 미디어 타임은 샘플의 프레임 번호이다. 예를 들어, 프레임의 캡춰와 송신을 실시해, 프레임 3 이 드롭 되는 경우, 미디어 타임값을 (0,1) (1,2) (2,3) (4,5) (5,6)와 같이 설정한다. 이것에 의해, 사용되고 있는 클락이 비디오 디지털화용의 클락은 아니고 보통의 타임 스탬프가 약간 랜덤인 경우에서도, 비디오 프레임에 드롭이 생기면(자), 다운 스트림에 그것을 통지할 수 있다.

또, 실행 상태로부터 포즈 해, 다시 실행하는 경우는, 포즈의 전에 송신된 마지막 타임 스탬프보다 작은 타임 스탬프로 샘플을 송신해서는 안 된다. 타임 스탬프는 시간을 거슬러 올라가지 못하고, 포즈전의 시간에 돌아오는 일도 할 수 없다.

frame rate

필터가 데이터를 생성하는 frame rate는, 출력 핀이 접속되고 있는 미디어 타입의 VIDEOINFOHEADER 의 AvgTimePerFrame 필드에 의해 결정된다. 캡춰는 임의의 frame rate에서는 실시하지 못하고, 특정의 레이트에서만 실시할 수 있다. 핀이 접속되고 있는 미디어 타입으로부터, 실행할 수 없는 frame rate가 요구되었을 경우, 그 레이트보다 낮고, 가장 가까운 값의 실행 가능한 frame rate에 의해 프레임을 제공해야 한다. 예를 들어, 미디어 타입의 AvgTimePerFrame 가 333333 (1 초의 약 1/30, 즉 1 초 쯤 30 프레임)인데 대해, 실행 가능한 frame rate가 1 초에 29.97 프레임 또는 35 프레임인 경우, 1 초 쯤 29.97 프레임이라고 하는 레이트로 하지 않으면 안 된다. 이 frame rate가 실행 가능한 값 중(안)에서 가장 30 에 근처, 30 보다 작은 값이니까이다. AvgTimePerFrame 에는 둥근 오차가 있으므로, 제공하는 frame rate에 의한 프레임의 시간폭이 요구된 값보다 1 마이크로 세컨드 이상 짧게 안 되면, 요구된 값보다 큰 frame rate로 할 수 있다. AvgTimePerFrame 필드가 0 의 경우, 임의의 디폴트 frame rate로 프레임을 공급할 수 있다.

IAMDroppedFrames 의 이행

캡춰 필터의 비디오 출력 핀은, 반드시 IAMDroppedFrames 인터페이스를 이행 해야 한다.

캡춰 필터를 실행 하면, 필터는 0, 1, 2, 3 이라고 하는 순서로 시작되는 프레임 번호를 송신한다 (프레임이 드롭 되었을 경우, 그 번호는 결핍 한다) . 송신된 각 프레임의 타임 스탬프는, 이미지가 디지털화되었을 때의 그래프 클락의 시각에 대응한다. 종료 타임은, 시작 타임에 비디오 프레임의 시간폭을 더한 값이다.

CMediaSample::SetMediaTime 를 사용해, 시작 타임과 종료 타임의 프레임 번호에 근거해, 각 샘플의 미디어 타임을 설정한다. 예를 들어, 시작 타임과 종료 타임의 순서는 (0,1) (1,2) (2,3)와 같이 표시된다. 다운 스트림 필터는, 보통의 타임 스탬프에 있어서의 결핍을 찾는 대신에, 프레임 번호의 순서에 있어서의 결핍을 조사하는 것으로, 프레임이 드롭 되었는지 어떠했는지를 간단하게 확인할 수 있다. 시작 타임과 종료 타임의 순서가 (1,2) (2,3) (4,5) (5,6)이면, 프레임 번호 3 이 드롭 된 것을 알 수 있다.

캡춰 필터에서는, 상태가 State_Stopped 로부터 State_Paused 에 변화할 때마다, 카운트를 모두 0 에 리셋 할 필요가 있다.

필터가 실행 상태로부터 포즈 되어 다시 실행되었을 경우, 포즈 상태와 관계없이 프레임의 배송을 계속할 필요가 있다. 2 번째의 실행의 뒤의 최초의 프레임에는, 포즈의 전에 송신된 마지막 프레임보다 빠른 시각의 타임 스탬프를 기록해서는 안 된다. 즉, 필터는 송신된 각 샘플의 미디어 타임을 항상 증가시킬 필요가 있다. 같은 프레임 번호를 2 회송신 하거나 시간을 거슬러 올라가거나 해서는 안 된다.

필요한 인터페이스

이하의 인터페이스의 설명을 읽어, 그 이행을 고려하는 것. 이러한 인터페이스는 어플리케이션이 사용할 가능성이 있는 기능을 제공하므로, 이행 하는 것을 강하게 추천 한다.

  • 필터 또는 데이터를 송신하는 각 출력 핀에 IAMDroppedFrames 를 이행 한다.
  • 비디오 데이터를 송신하는 각 출력 핀에 IAMStreamConfig 를 이행 한다.
  • 데이터를 송신하는 각 출력 핀에 IAMStreamControl 를 이행 한다.
  • 비디오 데이터를 송신하는 각 출력 핀에 IAMVideoCompression 를 이행 한다.


오디오 캡춰 필터의 개발

이 주제에서는, 오디오 캡춰 필터를 생성 할 때에 고려하는 중요한 점에 대해 설명한다. Microsoft® DirectShow® 에는 표준의오디오 캡춰 필터가 포함된다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • 오디오 캡춰 핀의 요건
  • 오디오 캡춰 필터의 등록
  • 데이터의 생성
  • 개개의 스트림의 제어
  • 타임 스탬프
  • 필요한 인터페이스

오디오 캡춰 핀의 요건

캡춰 필터의 캡춰 핀과 프리뷰 핀 (존재하는 경우)은,IKsPropertySet 인터페이스를 지원 할 필요가 있다. 상세한 것에 대하여는, 「캡춰 핀과 프리뷰 핀의 요건」을 참조할것. 이 주제에는, 캡춰 핀에 IKsPropertySet 를 이행하기 위한 샘플 코드도 포함된다.

캡춰 카드는 오디오를 디지털화하기 전에 몇개의 사운드를 믹싱 할 수가 있지만, 믹싱 하는 각 사운드 출처에 도착해, 각각 1 개의입력 핀이 필요하다. 예를 들어, 사운드 카드로 라인 입력, 마이크 입력, 및 CD-ROM 입력이 있는 경우는, 3 개의 입력 핀을 사용한다. 보통, 이러한 입력 핀을 다른 필터에 접속할 것은 없다. 단지 각 핀상에서 IAMAudioInputMixer 인터페이스를 지원 하는 것만으로 있어, 어플리케이션은 이 인터페이스를 사용해 각 핀의 녹음 레벨, 밸런스, 고음역등을 설정한다.

오디오 캡춰 필터의 등록

필터는 오디오 캡춰 필터의 카테고리에 등록할 필요가 있다. 상세한 것에 대하여는,AMovieDllRegisterServer2 함수의 설명을 참조할것.

데이터의 생성

캡춰 핀에서의 데이터의 생성은, 필터 그래프가 실행 상태의 경우에만 실시한다. 필터 그래프가 포즈 하고 있는 동안은, 핀으로부터 데이터를 송신해서는 안 된다. 만약 송신 하면, 필터 그래프에 혼란이 생긴다. 이것을 피하려면 CBaseFilter::GetState 함수로부터 VFW_S_CANT_CUE 를 돌려주는 것으로, 필터 그래프에 대해서, 포즈중은 데이터를 송신하지 않는 것을 경고한다. 이것을 다음의 코드 샘플에 나타낸다.

CMyVidcapFilter::GetState(DWORD dw, FILTER_STATE *State)
{
*State = m_State;
if (m_State == State_Paused)
return VFW_S_CANT_CUE;
else
return S_OK;
}

개개의 스트림의 제어

출력 핀은 모두 IAMStreamControl 인터페이스를 지원 할 필요가 있기 (위해)때문에, 어플리케이션은 각 핀을 개별적으로 온 또는 오프로 할 수 있다 (예를 들어, 캡춰 하지 않고 프리뷰 하는 경우 등). IAMStreamControl 를 사용 하면, 다른 그래프를 재생성 하지 않아도, 프리뷰와 캡춰의 사이에 바꿀 수가 있다.

타임 스탬프

캡춰 된 오디오 샘플을 송신하는 경우, 각 그룹의 시작타임 스탬프는, 패킷내의 최초의 샘플이 캡춰 되었을 때의 그래프의 클락의 시작 타임에 동일하다. 종료 타임 스탬프는, 시작 타임에 오디오 패킷이 나타내는 시간폭을 더한 값에 동일하다. 오디오 캡춰 필터가 클락을 제공하지 않는 경우, 타임 스탬프는 엄밀하게는 일치하지 않는 (1 개의 패키지의 마지막이 다음의 패키지의 시작 타임 스탬프에 동일하다)가, 이것은 허용 범위이다. 타임 스탬프 설정의 예에 대해서는, 「비디오 캡춰 필터의 개발」을 참조할것.

보통의 타임 스탬프에 가세해, 배송하는 샘플의미디어 타임도 설정할 필요가 있다. 미디어 타임은, 패킷내의 샘플 번호이다. 따라서, 44.1 kHz 오디오의 1 초 패킷을 송신하는 경우는, 미디어 타임값을 (0, 44100), (44100, 88200) ... (와)과 같이 설정한다. 이것에 의해, 사용되고 있는 클락이 오디오 디지털화용의 클락은 아니고 보통의 타임 스탬프가 약간 랜덤인 경우에서도, 오디오 샘플에 드롭이 생기면(자),다운 스트림 필터로 그것을 검출할 수 있다

이제(벌써) 1 개의 주의점으로서 필터 그래프가 실행 상태로부터 포즈 되어 다시 실행되었을 경우, 포즈의 전에 생성한 마지막 타임 스탬프보다 작은 타임 스탬프로 샘플을 생성해서는 안 된다. 타임 스탬프는 시간을 거슬러 올라가지 못하고, 포즈전의 시간에 돌아오는 일도 할 수 없다.

필요한 인터페이스

이하의 인터페이스의 설명을 읽어, 그 이행을 고려하는 것. 이러한 인터페이스는 어플리케이션이 사용할 가능성이 있는 기능을 제공하므로, 이행 하는 것을 강하게 추천 한다.

  • 필터 또는 데이터를 송신하는 각 출력 핀에 IAMDroppedFrames 를 이행 한다.
  • 데이터를 송신하는 각 출력 핀에 IAMStreamConfig 를 이행 한다.
  • 데이터를 송신하는 각 출력 핀에 IAMStreamControl 를 이행 한다.
  • 필터 및 각 입력 핀에 IAMAudioInputMixer 를 이행 한다.


캡춰 포맷과 압축 포맷의 공개

여기에서는,IAMStreamConfig::GetStreamCaps 메소드를 사용해 캡춰 포맷과 압축 포맷을 돌려주는 방법을 설명한다. 이 메소드를 사용하면(자), 받아들일 수 있는 미디어 타입에 관해서, 핀의 미디어 타입을 열거하는 종래의 방법에 비해보다 많은 정보를 취득할 수가 있으므로, 보통은 이 메소드를 사용해야 한다. 종래의 미디어 타입을 열거하는 방법에 대해서는, 「미디어 타입 접속의 확립」을 참조할것. GetStreamCaps 는, 오디오나 비디오에 용서된 각종 포맷에 관한 정보를 돌려준다. 또 여기에서는, 필터가 특정의 출력을 생성할 수 있도록(듯이)변환 필터의입력 핀을 재접속하기 위한 코드예를 나타낸다.

GetStreamCaps 메소드는, 미디어 타입 구조체와 능력 구조체의 페어를 요소로 하는 배열을 돌려준다. 미디어 타입은 AM_MEDIA_TYPE 구조체로, 능력은 AUDIO_STREAM_CONFIG_CAPS 구조체 또는 VIDEO_STREAM_CONFIG_CAPS 구조체로 나타내진다. 여기에서는 최초로 비디오의 예를 나타내, 다음에 오디오의 예를 나타낸다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • 비디오 능력
  • 오디오 능력
  • 특정의 출력 타입을 보증하기 위해서 입력을 재접속한다

비디오 능력

IAMStreamConfig::GetStreamCaps 메소드는,AM_MEDIA_TYPE 구조체와 VIDEO_STREAM_CONFIG_CAPS 구조체의 페어의 배열로 비디오 능력을 나타낸다. 이하에 설명하도록(듯이), 이 메소드를 사용 하면, 핀으로 지원 떠날 수 있어 모든 포맷과 해상도를 공개할 수가 있다.

GetStreamCaps 의 오디오 관련의 예에 대해서는, 「오디오 능력」을 참조할것.

사용하고 있는 캡춰 카드가, 160 × 120 픽셀에서 320 × 240 픽셀의 사이의 모든 해상도로 JPEG 포맷을 지원 하고 있다고 한다. 이 경우, 지원 되고 있는 해상도간의 차이는 1 이다. 왜냐하면, 지원 되고 있는 각 해상도에 대해서 1 픽셀 가산 또는 감산하는 것에 의해, 다음의 지원 되고 있는 해상도를 얻고 있기 때문이다. 지원 되고 있는 해상도간에 있어서의 이 차이는, 세분도로 불린다.

카드가 640 × 480 의 사이즈도 지원 하고 있다고 한다. 이하의 그림에, 이 단독의 해상도와 위의 해상도 범위 (160 × 120 픽셀에서 320 × 240 픽셀까지의 범위의 모든 해상도)를 나타낸다.

160 × 120 픽셀로부터 320 × 240 픽셀까지의 범위의 모든 사이즈, 및 640 × 480 에서의 JPEG 지원

게다가 세분도가 8 으로 160 × 120 에서 320 × 240 까지의 범위의 해상도로 24 비트 칼라의 RGB 포맷을 지원 하고 있다고 한다. 이하의 그림에, 이 경우의 유효 사이즈의 몇개인가를 나타낸다.

세분도가 8 로 160 × 120 로부터 320 × 240 까지의 범위의 사이즈에서의 RGB 지원

구체적으로는, 유효한 해상도로서 이하의 해상도가 있다.

  • 160 × 120
  • 168 × 120
  • 168 × 128
  • 176 × 128
  • 176 × 136
  • ... 중략 ...
  • 312 × 232
  • 320 × 240

GetStreamCaps 를 사용해, 최소 능력 160 × 120, 최대 능력 320 × 240, 세분도 1 을 조합한 320 × 240 JPEG (이것이 디폴트 또는 희망 사이즈의 경우)의 미디어 타입을 제공하는 것에 의해, 이러한 칼라 포맷 및 넓이 능력을 공개한다. GetStreamCaps 를 사용해 다음에 공개하는 페어는, 최소 능력 640 × 480, 최대 능력 640 × 480, 세분도 0 을 조합한 640 × 480 JPEG 의 미디어 타입이 된다. 3 번째의 페어는, 최소 능력 160 × 120, 최대 능력 320 × 240, 세분도 8 을 가지는, 320 × 240 의 24 비트 RGB 의 미디어 타입이다. 이와 같이, 카드가 지원 하는 거의 모든 포맷 및 능력을 공개할 수가 있다. 어떠한 압축 포맷이 제공될까를 모르면 안 되는 어플리케이션은, 모든 페어를 취득해, 미디어 타입의 일의인 서브 타입의 리스트를 생성 할 수가 있다.

필터는, VIDEOINFOHEADER 구조체의 rcSource 및 rcTarget 멤버로부터 미디어 타입의 전송원직사각형 및 전송처 직사각형을 각각 취득한다. 필터는, 전송원직사각형 및 전송처 직사각형을 지원 할 필요는 없다.

IAMStreamConfig 의 해설로 설명한 크로핑 직사각형은,출력 핀의 VIDEOINFOHEADER 구조체의 rcSource 직사각형과 같다.

IAMStreamConfig 의 해설로 설명한 출력 직사각형은, 출력 핀의 BITMAPINFOHEADER 구조체의 biWidth 및 biHeight 멤버와 같다.

필터의 출력 핀이, 하늘이 아닌 전송원직사각형 및 전송처 직사각형을 가지는 미디어 타입에 접속되고 있는 경우, 필터는, 입력 포맷의 전송원서브 직사각형을 출력 포맷의 전송처 서브 직사각형에 신축할 필요가 있다. 전송원서브 직사각형은,VIDEO_STREAM_CONFIG_CAPS 구조체의 InputSize 멤버에 저장 된다.

예를 들어, 이하와 같은 비디오 압력 시나리오를 생각해 보자. 입력 이미지는 RGB 포맷으로, 160 × 120 픽셀의 사이즈를 가진다. 전송원직사각형의 좌상구석의 좌표는 (20,20)으로, 그 우하구석의 좌표는 (30,30)이다. 출력 이미지는, 사이즈가 320 × 240 의 MPEG 포맷이다. 전송처 직사각형의 좌상구석의 좌표는 (0,0)으로, 그 우하구석의 좌표는 (100,100)이다. 이 경우, 필터는, 160 × 120 RGB 의 전송원비트 맵의 10 × 10 부분을 꺼내, 그것을 320 × 240 의 비트 맵의 최초의 100 × 100 영역에 묻어 320 × 240 비트 맵의 나머지의 영역은 그대로 해 두지 않으면 안 된다. 이하의 그림에 이 조작을 나타낸다.

전송원직사각형과 전송처 직사각형의 사이에 이미지의 서브 직사각형을 신축하는 비디오 압력

필터가 이러한 조작을 지원 하고 있지 않는 경우,rcSource 와 rcTarget 가 하늘이 아닌 미디어 타입에의 접속은 실패한다.

VIDEOINFOHEADER 구조체는, 필터의 데이터 레이트 능력에 관한 정보를 공개한다. 예를 들어, 어느 미디어 타입을 가지는 다음의 필터에 (직접적으로, 또는 CMediaType::SetFormat 함수로부터 건네받은 미디어 타입을 사용해) 출력 핀을 접속했다고 한다. 그 미디어 타입의 VIDEOINFOHEADER 포맷 구조체의 dwBitRate 멤버를 보면(자), 비디오의 압축에 사용해야 할 데이터 레이트를 알 수 있다. VIDEOINFOHEADER 구조체의 AvgTimePerFrame 멤버내의 프레임 근처의 타임 단위수에 dwBitRate 멤버내의 데이터 레이트를 걸어 그 결과를 10,000,000 (1 초 쯤의 단위수)으로 나누면(자), 프레임 근처의 바이트수를 요구할 수가 있다. 작은 사이즈의 프레임을 생성할 수 있지만, 큰 사이즈의 프레임은 생성할 수 없다. 비디오 압력 또는 캡춰 필터의 frame rate를 요구하려면 , 출력 핀의 미디어 타입의 AvgTimePerFrame 를 사용한다.

오디오 능력

오디오 능력에 관해서,IAMStreamConfig::GetStreamCaps 는 AM_MEDIA_TYPE 구조체와 AUDIO_STREAM_CONFIG_CAPS 구조체의 페어의 배열을 돌려준다. 비디오의 경우와 같게, 이것을 사용해 핀의 모든 종류의 오디오 능력 (예를 들어 데이터 레이트나 단청의 또는 스테레오의 지원의 유무)을 공개할 수가 있다.

GetStreamCaps 의 비디오 관련의 예에 대해서는, 「비디오 능력」을 참조할것.

매초 11,025, 22,050, 및 44,100 샘플의 샘플링 레이트, 8 비트 또는 16 비트 단청의 또는 스테레오의 PCM (pulse code modulation) wave 포맷 (Microsoft® Win32® PCMWAVEFORMAT 구조체로 나타난다)을 지원 하는 경우를 생각해 본다. 이 경우, 2 개의 구조체 페어를 제공한다. 1 번째의 페어는,AUDIO_STREAM_CONFIG_CAPS 능력 구조체를 가져, 매초 11,025 샘플의 세분도 (세분도는, 지원 되고 있는 값의 차이)로 1 초 쯤최소 11,025 ~최대 22,050 샘플, 1 샘플 근처 8 비트의 세분도로 1 샘플 근처 최소 8 ~최대 16 비트, 최소 1 채널, 최대 2 채널을 지원 하는 것을 나타낸다. 1 번째의 페어의 미디어 타입은, 그 범위내의 디폴트 PCM 포맷이 되어, 22 kHz, 16 비트 스테레오가 된다. 2 번째의 페어는, 1 초 쯤의 최소 및 최대 샘플수가 44,100, 1 샘플 근처 8 비트의 세분도로 1 샘플 근처 8 비트 (최소) 및 16 비트 (최대), 최소 1 채널, 최대 2 채널을 나타낸다. 이 미디어 타입은, 디폴트의 44kHz 포맷이 되어, 44kHz 16 비트 스테레오가 된다.

비 PCM wave 포맷을 지원 하는 경우, 이 메소드로부터 돌려주어지는 미디어 타입은, 지원 하는 비 PCM 포맷 (디폴트의 샘플링 레이트, bit rate, 및 채널)을 나타내, 그 미디어 타입에 수반하는 능력 구조체는, 지원 하는 샘플링 레이트, bit rate, 및 채널을 나타낸다.

특정의 출력 타입을 보증하기 위해서 입력을 재접속한다

필터는, 핀이 접속되기 전에 오디오 또는 비디오 스트림의 포맷을 설정하기 위해서,IAMStreamConfig::SetFormat 메소드를 이행 한다. 또, 출력 핀이 이미 접속되고 있어 새로운 타입을 제공할 수 있는 경우는, 핀을 재접속한다. 필터가 접속되고 있는 앞의 핀이 미디어 타입을 사용할 수 없는 경우, 이 호출은 실패해, 접속은 그대로 된다.

핀이 어떠한 출력 타입을 제공할지 모르는 변환 필터는, 입력 핀이 접속될 때까지, 모든 SetFormat 호출 및 IAMStreamConfig::GetStreamCaps 호출을 에러 코드 VFW_E_NOT_CONNECTED 로 거부해야 한다.

입력이 접속되어 있지 않아도, 핀을 제공할 수 있는 타입을 알 수 있고 있는 경우는, 보통대로 타입을 제시하거나 받아들일 수가 있다. 상세한 것에 대하여는, 「변환 필터의 접속」을 참조할것.

경우에 따라서는, 확립 끝난 접속에 대해서 포맷을 제시할 경우에 핀을 재접속하는 것이 편리한 일도 있다. 예를 들어, 24 비트의 RGB 입력이 있을 때만 비디오를 포맷 X 에 압축할 수 있는 한편으로, 8 비트 RGB 입력을 압축 포맷 Y 에 압축할 수 있는 경우, 다음의 선택사항이 있다.

  1. GetStreamCaps 및 SetFormat 를 사용해 항상 X 와 Y 의 양쪽 모두를 제시 및 받아들인다.
  2. 입력이 24 로서 접속되었을 경우만 포맷 X 를 제시해, 입력이 8 으로서 접속되었을 경우만 포맷 Y 를 제시한다. 입력이 접속되어 있지 않은 경우는,GetStreamCaps 및 SetFormat 의 양쪽 모두를 실패시킨다.

어느 쪽의 방법을 선택했다고 해도, 다음과 같은 재접속을 실시하는 코드가 필요하게 된다.

// 공이 많이 든 재접속을 행하기 위한 오버라이드(override).
//
HRESULT MyOutputPin::CheckMediaType(const CMediaType *pmtOut)
{
HRESULT hr;
    CMediaType *pmtEnum;
    BOOL fFound = FALSE;
    IEnumMediaTypes *pEnum;

    if (! m_pFilter->m_pInput->IsConnected()) {
return VFW_E_NOT_CONNECTED;
    }

    // 미디어 타입이 부정하지 않는 것을 재빠르게 체크한다.
    //

    // SetFormat 가 미리 불려 가고 있는 경우, 미디어 타입이 일치
    // 하지 않으면 이 호출을 실패시킨다.

    // 보통대로 이 출력 타입을 받아들인다. 특별한 조작은 필요없다.
    hr = m_pFilter->CheckTransform(&m_pFilter->m_pInput->CurrentMediaType(),
        pmtOut);
if (hr == NOERROR)
return hr;

    DbgLog((LOG_TRACE, 3, TEXT("Can't accept this output media type")));
    DbgLog((LOG_TRACE, 3, TEXT(" But how about reconnecting the input...")));

    // 입력 핀을 재접속해, 사용 가능한 타입을 찾는다.
    // 입력 핀에 접속되는 핀에 의해, 필요한 타입에 변환 가능한
    // 타입을 알 수 있는 경우도 있다.
    hr = m_pFilter->m_pInput->GetConnected() ->EnumMediaTypes(&pEnum);
if (hr ! = NOERROR)
        return E_FAIL;
    while (1) {
        hr = pEnum->Next(1, (AM_MEDIA_TYPE **) &pmtEnum, &j);

    // 모두 열거형으로부터.
    if (hr == S_FALSE || j == 0) {
break;
    }

    // 핀은 이러한 타입간에 변환을 실시할 수 있을까?
    hr = m_pFilter->CheckTransform(pmtEnum, pmtOut);

if (hr ! = NOERROR) {
DeleteMediaType(pmtEnum);
continue;
    }

    // OK. 사용 가능한 타입이 제시되었다. 지금 곧 받아들일까?
    hr = m_pFilter->m_pInput->GetConnected() ->QueryAccept(pmtEnum);
    // No.
if (hr ! = NOERROR) {
DeleteMediaType(pmtEnum);
continue;
    }
    // OK.
    fFound = TRUE;
    DbgLog((LOG_TRACE, 2, TEXT("This output type is only acceptable after
                                reconnecting the input. ")));

    // 모두 완료.
DeleteMediaType(pmtEnum);
break;
    }
    pEnum->Release();

    if (! fFound)
        DbgLog((LOG_TRACE, 3, TEXT("*NO!  Reconnecting the input won't help")));

    return fFound ?  NOERROR : VFW_E_INVALIDMEDIATYPE;
}

HRESULT MyOutputPin::SetFormat(AM_MEDIA_TYPE *pmt)
{
HRESULT hr;
    LPWAVEFORMATEX lpwfx;
    DWORD dwSize;

    if (pmt == NULL)
return E_POINTER;

    // 스트리밍이 시작/정지가 도중에 없는 것을 확인한다.
    CAutoLock cObjectLock(&m_pFilter->m_csFilter);

    if (m_pFilter->m_State ! = State_Stopped)
    return VFW_E_NOT_STOPPED;

    // 가능한 출력 포맷은 입력 포맷에 의존한다.
    if (! m_pFilter->m_pInput->IsConnected())
return VFW_E_NOT_CONNECTED;

    // 이 포맷은 이미 사용하고 있다.
    if (IsConnected() && CurrentMediaType() == *pmt)
return NOERROR;

    // 이 타입이 사용 가능한가 어떤가를 조사한다.
    if ((hr = CheckMediaType((CMediaType *) pmt)) ! = NOERROR) {
    DbgLog((LOG_TRACE, 2, TEXT("IAMStreamConfig::SetFormat rejected")));
return hr;
    }

    // 다른 필터에 접속하는 경우는, 그 필터가 해당 타입을 받아들이는지 확인한다.
    if (IsConnected()) {
    hr = GetConnected() ->QueryAccept(pmt);
if (hr ! = NOERROR)
        return VFW_E_INVALIDMEDIATYPE;
    }

    // 이후, 이것이 유일 용서되는 포맷이며, 이외의
    // 포맷은 위의 CheckMediaType 코드로 거부하는 것에 주의.

    // 포맷의 변경은, 필요에 따라서 재접속하는 것을 의미한다.
    if (IsConnected())
        m_pFilter->m_pGraph->Reconnect(this);

return NOERROR;
}

// 공이 많이 든 재접속을 완료하기 위해서 오버라이드(override).
//
HRESULT MyWrapper::SetMediaType(PIN_DIRECTION direction, const CMediaType *pmt)
{
HRESULT hr;

    // OUTPUT 타입을 설정한다.
    if (direction == PINDIR_OUTPUT) {

    // 공이 많이 든 재접속의 일부로서 입력 핀은,
    // 다른 타입에 재접속하지 않고에는 제공할 수 없는 미디어 타입을
    // 제공하도록(듯이) 요구된다.
    if (m_pInput && m_pInput->IsConnected()) {

        // 핀이 이 타입을 지금 실제로 제공할 수 있는 경우는 문제 없다.
            hr = CheckTransform(&m_pInput->CurrentMediaType(),
                    &m_pOutput->CurrentMediaType());
if (hr == NOERROR)
return hr;

                DbgLog((LOG_TRACE, 2, TEXT("*Set OUTPUT requires RECONNECT of INPUT! ")));

        // 입력 핀을 재접속한다.
        return m_pGraph->Reconnect(m_pInput);

    }

return NOERROR;
    }

return NOERROR;
}


필터의 카테고리

Microsoft® DirectX® SDK 에 부속의 GraphEdit 샘플 툴을 사용해,[Graph] 메뉴로부터 [Insert Filters] 를 선택 하면, 시스템 위에의 Microsoft® DirectShow® 필터가 몇개의 카테고리로 분류되고 있는 것을 알 수 있다. DirectShow 필터 카테고리는, 대부분의 필터가 포함되는 전반적인 카테고리이다. 새로운 필터는 디폴트로 이 카테고리에 등록된다. GraphEdit 에서는, 하늘의 카테고리는 표시되지 않는다.

다만, 필터가 이하의 몇개의 종류인 경우는, 필터가 각각 적절한 카테고리에 표시되도록(듯이) 할 필요가 있다.

  • 오디오 캡춰 소스—외부 디바이스로부터 오디오 데이터를 생성한다.
  • 오디오 압력—PCM 오디오를 압축한다.
  • 오디오 렌더러—로컬의 스피커 세트로 오디오 데이터를 재생한다.
  • 에스크타나르렌다라—외부 주변기기 (1394 DV 카메라등)에 데이터를 송신한다.
  • 디바이스 컨트롤—비디오 테잎 머신 (1394 DV 카메라등)의 트랜스폴트를 제어한다.
  • MIDI 렌더러—로컬의 스피커 세트로 MIDI 데이터를 재생한다.
  • 비디오 캡춰 소스—외부 디바이스로부터 비디오 데이터를 생성한다.
  • 비디오 압력—RGB 비디오를 압축 비디오로 변환한다.

필터를 카테고리별로 등록하는 방법에 대해서는,AMovieDllRegisterServer2 함수의 주제를 참조할것. 이 주제에는, 비디오 압력 필터를 등록하기 위한 샘플 코드가 포함되어 있다. 상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.


파일 포맷

이 섹션에서는, Microsoft® DirectShow® 로 사용되는 각종 파일의 파일 포맷에 대해 설명한다.

  • AVI 파일 포맷의 DV 데이터
  • 커스텀 파일 타입의 등록


AVI 파일 포맷의 DV 데이터

Microsoft 는 디지털 비디오 (DV) 데이터를 AVI 파일에 보존하기 위한 포맷을 지정하고 있다. 이 사양에 따르는 것으로, 이 포맷으로 생성 된 AVI 파일은 Microsoft® Windows® 플랫폼용의 Microsoft® DirectShow® 디지털 비디오 아키텍쳐의 장래의 버젼에 대해서 호환성을 가지는 것이 보증된다.

이 주제에서는, DV 오디오 및 비디오 데이터를 포함한 AVI (Audio-Video Interleaved) 파일의 포맷을 이해하기 위한 배경 정보를 제공한다. 또, 다른 플랫폼상에서 DV-AVI 파일을 사용하는 프로그래머를 위한 정보도 제공한다. AVI 파일을 읽고 쓰기하는 어플리케이션은,파일 소스 (Async) 필터와 AVI 스플리터 필터, 및 AVI Mux 필터와 파일 라이터 필터, 그리고 DirectShow 아키텍쳐로 제공되는 관련 인터페이스를 사용한다. 그것에 의해, 그러한 서비스를 실행하기 위한 루틴을 개발하지 않아도 된다. 이러한 필터는, AVI 파일에 액세스하기 위한 프로그래밍 위에의 요건을 단순화 한다.

여기에서는 게다가 DV 데이터를 포함한 AVI 파일의 포맷에 대해서도 설명한다. 인터리브 된 DV 데이터 스트림 및 DV 압력/데콘프렛사스트림한드라용의 특정의 FOURCC (4 문자 코드)를 정의해, DV 데이터의 스트림 포맷 구조체를 정의한다. 또, AVI 파일 포맷에 DV 데이터를 저장하기 위한 2 개의 방법의 사양에 대해서도 설명한다.

이 주제는, 독자가 DV 데이터 포맷에 대해 어느 정도 이해하고 있는 것을 전제로 해서 쓰여져 있다. (이 포맷에 대해서는, 「Specification of Consumer-use Digital VCRs」에 정의되고 있다. 이 문서는 Blue Book 라고도 불린다. )

이 주제는, 이하의 섹션을 포함하고 있다.

  • DV AVI 파일의 타입
  • AVI RIFF 파일의 레퍼런스
  • AVI 2.0 파일 포맷 확장

RIFF (Resource Interchange File Format) 파일의 상세한 것에 대하여는, Windows Software Development Kit (SDK)의 「Multimedia Programmer's Guide」와 「Multimedia Programmer's Reference」를 참조할것.

AVI 파일의 상세한 것에 대하여는, Microsoft Video for Windows Development Kit 버젼 1.1 의 「Programmer's Guide」 제 6 장, 및 「OpenDML AVI File Format Extensions」(OpenDML AVI M-JPEG File Format Subcommittee 편, 1996 년 2 월 28 일)의 버젼 1.02 를 참조할것.

압력 및 데콘프렛사의 상세한 것에 대하여는, MSDN 라이브러리에 있는 Windows DDK Documentation 의 「Video Compression and Decompression Drivers」섹션을 참조할것.

DV AVI 파일의 타입

DV AVI 파일에는 다음의 2 개의 타입이 있다.

  • 1 개의 DV 데이터 스트림을 포함한 AVI 파일
  • DV 비디오를 'vids'스트림으로서 포함해 DV 오디오를 'auds'스트림으로서 포함한 AVI 파일

1 개의 DV 데이터 스트림을 포함한 AVI 파일

인터리브 된 DV 데이터는, AVI RIFF 파일내에 1 개의 스트림으로서 그 네이티브 포맷으로 저장 할 수 있다. 이 방법에는, DV 에 대해서 사용하는 데이터 저장 영역의 양이 최소한으로 끝난다고 하는 이점이 있다. 주된 결점으로서는, 이 파일 포맷에는 비디오 'vids'스트림도 오디오 'auds'스트림도 포함되지 않기 때문에, Video for Windows 에 대한 후방 호환성을 가지지 않는 것을 들 수 있다. 인터리브 된 DV 스트림의 지원은, DirectShow 의 DV Muxer 및 DV 스플리터 필터에 의해 제공된다.

DV 데이터를 AVI RIFF 파일내에 1 개의 스트림으로서 저장 하려면 , 'strh'스트림헷다체크의 fccType 멤버에 'iavs' (interleaved audio and video stream) FOURCC (four-character code : 4 문자 코드)를 지정해,fccHandler 멤버에 'dvsd', 'dvhd', 'dvsl'의 몇개의 FOURCC 를 지정한다. 비디오 스트림의 매초의 프레임수를 dwRate 및 dwScale 멤버로 지정해, 'movi'체크내의 비디오 블록의 총수를 dwLength 멤버로 지정한다.

'dvsd'스트림 핸들러 FOURCC 는, DV 데이터가 「Specification of Consumer-use Digital VCRs」의 Part 2 에 따르고 있는 것을 지정한다. 비디오의 포맷은 525 라인, 29.97 Hz (525-60)인가, 또는 625 라인, 25.00 Hz (625-50)이다.

'dvhd'스트림 핸들러 FOURCC 는, DV 데이터가 「Specification of Consumer-use Digital VCRs」의 Part 3 에 따르고 있는 것을 지정한다. 비디오의 포맷은 1125 라인, 30.00 Hz (1125-60)인가, 또는 1250 라인, 25.00 Hz (1250-50)이다.

'dvsl'스트림 핸들러 FOURCC 는, DV 데이터가 「Specification of Consumer-use Digital VCRs」의 Part 6 에 따르고 있는 것을 지정한다. 비디오의 포맷은 고압축 SD (SDL)이다.

주 : 이 주제의 이후의 부분에서는, 'dvsd'스트림의 정의를 제공한다.

스트림헷다체크의 뒤에는,DVINFO 스트림포맛트체크가 계속된다. DVINFO 스트림 포맷에 대해서는, 이하의 데이터 구조체가 정의된다.

typedef struct tag_DVINFO {
    DWORD dwDVAAuxSrc;
    DWORD dwDVAAuxCtl;
    DWORD dwDVAAuxSrc1;
    DWORD dwDVAAuxCtl1;
    DWORD dwDVVAuxSrc;
    DWORD dwDVVAuxCtl;
    DWORD dwDVReserved[2];
} DVINFO, *PDVINFO;
dwDVAAuxSrc
프레임의 최초의 오디오 블록 (525-60 시스템에서는 최초의 5 개의 DV DIF 순서,625-50 시스템에서는 최초의 6 개의 DV DIF 순서)에 대한 Audio Auxiliary Data Source Pack 를 지정한다. DIF 순서는, 150 개의 DIF 블록을 포함한 데이터 블록이다. 각 DIF 블록에는 80 바이트가 포함된다. Audio Auxiliary Data Source Pack 에 대해서는, 「Specification of Consumer-use Digital VCRs」의 Part 2, Annex D 「The Pack Header Table and Contents of Packs」의 섹션 D. 7.1 에 정의되고 있다.
dwDVAAuxCtl
프레임의 최초의 오디오 블록의 Audio Auxiliary Data Source Control Pack 를 지정한다. Audio Auxiliary Data Control Pack 에 대해서는, 「Specification of Consumer-use Digital VCRs」의 Part 2, Annex D 「The Pack Header Table and Contents of Packs」의 섹션 D. 7.2 에 정의되고 있다.
dwDVAAuxSrc1
프레임의 2 번째의 오디오 블록 (525-60 시스템에서는 2 번째의 5 개의 DV DIF 순서,625-50 시스템에서는 2 번째의 6 개의 DV DIF 순서)에 대한 Audio Auxiliary Data Source Pack 를 지정한다.
dwDVAAuxCtl1
프레임의 2 번째의 오디오 블록의 Audio Auxiliary Data Source Control Pack 를 지정한다.
dwDVVAuxSrc
「Specification of Consumer-use Digital VCRs」의 Part 2, Annex D 「The Pack Header Table and Contents of Packs」의 섹션 D. 8.1 에 정의되고 있는 Video Auxiliary Data Source Pack 를 지정한다.
dwDVVAuxCtl
「Specification of Consumer-use Digital VCRs」의 Part 2, Annex D 「The Pack Header Table and Contents of Packs」의 섹션 D. 8.2 에 정의되고 있는 Video Auxiliary Data Source Control Pack 를 지정한다.
DwDVReserved[2]
예약되고 있다. 이 배열은 제로로 설정한다.

실제의 DV 데이터는 'movi'체크내의 '##dc'체크로서 저장 된다 (## 는 스트림 식별자). 각 체크에는, 1 프레임의 데이터가 포함된다. 이것은 525-60 시스템의 경우는 10 개의 DV DIF 순서,625-50 시스템의 경우는 12 개의 DV DIF 순서이다. DV SD ('dvsd') DIF 순서 포맷에 대해서는, 「Specification of Consumer-use Digital VCRs」의 Part 2 로 정의되고 있다.

다음의 그림에, 1 개의 DV 데이터 스트림을 포함한 AVI 파일을 DirectShow 필터 그래프를 사용해 재생하는 예를 나타낸다 (DV 스플리터 및 DV 비디오 디코더 필터는, 특히 DV 데이터를 취급하기 위해서(때문에) DirectShow 에 준비되어 있다). 아래의 겉(표)로, 미디어 타입을 정의한다.

1 개의 DV 데이터 스트림을 포함한 AVI 파일의 재생
미디어 | 메이저 타입 | 서브 타입 | 포맷 구조체
A | MEDIATYPE_Stream | MEDIASUBTYPE_AVI | 없음
B | MEDIATYPE_iavs | MEDIASUBTYPE_dvsd, MEDIASUBTYPE_dvhd, 또는 MEDIASUBTYPE_dvsl | DVINFO
C | MEDIATYPE_VIDEO | MEDIASUBTYPE_dvsd, MEDIASUBTYPE_dvhd, 또는 MEDIASUBTYPE_dvsl | DVINFO
D | MEDIATYPE_AUDIO | NULL | WAVEFORMATEX
E | MEDIATYPE_VIDEO | 표준 비디오 타입 | VIDEOINFO

다음의 그림에, 1 개의 DV 데이터 스트림을 포함한 AVI 파일을 DirectShow 필터 그래프를 사용해 생성 하는 예를 나타낸다 (DV 비디오 엔코더 및 DV Muxer 필터는, 특히 DV 데이터를 취급하기 위해서(때문에) DirectShow 에 준비되어 있다). 미디어 타입은 위에의표에 정의되고 있다. 업 스트림 필터는, 여기에는 나타나지 않지만, 적절한 미디어 타입 D 및 E 를 생성하는 임의의 편성을 사용할 수 있다.

1 개의 DV 데이터 스트림을 포함한 AVI 파일의 생성

다음의 그림에, 1 개의 DV 데이터 스트림을 포함한 AVI 파일을 DirectShow 필터 그래프를 사용해 생성 하는 예를 나타낸다. 여기에서는, 하드웨어 디바이스 드라이버를 통해 DV 디바이스 (1394 베이스의 DV 캠 코다등)와 통신하는소스 필터를 DV 데이터 입력으로서 사용하고 있다 (이 소스 필터는, 특히 DV 데이터를 취급하기 위해서(때문에) DirectShow 에 준비되어 있다). 미디어 타입은 위에의표에 정의되고 있다.

1 개의 DV 데이터 스트림을 포함한 AVI 파일에의 DV 캡춰

다음의 그림에, 1 개의 DV 데이터 스트림을 포함한 AVI 파일을 DirectShow 필터 그래프를 사용해 출력하는 예를 나타낸다. 여기에서는, 하드웨어 디바이스 드라이버를 통해 DV 디바이스 (1394 베이스의 DV 캠 코다등)와 통신하는 세면대 필터를 DV 데이터 출력으로서 사용하고 있다 (이 세면대 필터는, 특히 DV 데이터를 취급하기 위해서(때문에) DirectShow 에 준비되어 있다). 미디어 타입은 위에의표에 정의되고 있다.

1 개의 DV 데이터 스트림을 포함한 AVI 파일의 출력

다음의 예는, 완전한 헷다체크에 의해 확장된, 1 개의 DV 데이터 스트림을 포함한 AVI 파일의 AIFF RIFF 포맷을 나타낸다.

00000000 RIFF (0FAE35D4) 'AVI '
0000000C LIST (00000106) 'hdrl'
00000018 avih (00000038)
dwMicroSecPerFrame    : 33367
dwMaxBytesPerSec      : 3728000
dwPaddingGranularity  : 0
dwFlags               :0x810 HASINDEX | TRUSTCKTYPE
dwTotalFrames         : 2192
dwInitialFrames       : 0
dwStreams             : 1
dwSuggestedBufferSize : 120000
dwWidth               : 720
dwHeight              : 480
dwReserved            :0x0
00000058         LIST (0000006C) 'strl'
00000064             strh (00000038)
fccType               : 'iavs'
fccHandler            :'dvsd'
dwFlags               :0x0
wPriority             : 0
wLanguage             :0x0 undefined
dwInitialFrames       : 0
dwScale               :100 (29.970 Frames/Sec)
dwRate                : 2997
dwStart               : 0
dwLength              : 2192
dwSuggestedBufferSize : 120000
dwQuality             : 0
dwSampleSize          : 0
rcFrame               : 0,0,720,480
000000A4             strf (00000020)
dwDVAAuxSrc     :0x........
dwDVAAuxCtl     :0x........
dwDVAAuxSrc1    :0x........
dwDVAAuxCtl1    :0x........
dwDVVAuxSrc     :0x........
dwDVVAuxCtl     :0x........
dwDVReserved[2] : 0,0
000000CC     LIST (0FADAC00) 'movi'
0FADACD4     idx1 (00008900)

DV 비디오를 'vids'스트림으로서 포함해 DV 오디오를 'auds'스트림으로서 포함한 AVI 파일

인터리브 된 DV 데이터는, AVI RIFF 파일내에서 1 개의 비디오 스트림과 1 개에서 4 개까지의 오디오 스트림에 분할할 수가 있다. 이 파일 포맷에는 표준 비디오 'vids'스트림과 적어도 1 개의 표준 오디오 'auds'스트림이 포함되기 (위해)때문에, Video for Windows 에 대해서 후방 호환성을 갖는다고 하는 이점이 있다. 주된 결점은, 이 파일 포맷에서는 오디오 데이터를 오디오 스트림으로서 장황하게 저장 해야 하는 것이다. "비디오 " 스트림은, 실제로는 네이티브의 인터리브 된 DV 데이터 스트림이다. 다만, 핸들러 타입 'dvsd'의 표준 'vids'스트림으로서DV 비디오 디코더가 사용된다. 또, 이 포맷에서는, "캡춰 된 " 파일을 AVI 파일로서 기입하기 전에,DV 스플리터 필터를 사용해 파일을 분할할 필요가 있다.

DV 데이터는, 1 개의 비디오 스트림과 별로 몇개의 오디오 스트림으로서 AVI RIFF 파일에 저장 할 수 있다. 비디오 스트림은 표준 비디오 스트림 헤더 (fccType 멤버값이 'vids')에 의해 지정된다. fccHandler 멤버는 'dvsd', 'dvhd', 또는 'dvsl'로서 지정된다. 비디오 스트림의 매초의 프레임수를 dwRate 및 dwScale 멤버로 지정해, 'movi'체크내의 비디오 블록의 총수를 dwLength 멤버로 지정한다.

이와 같이 DV 비디오를 'vids'스트림으로서 포함해 DV 오디오를 'auds'스트림 포맷의 DV 로서 포함한 AVI 파일에서는, 비데오스트림포맛트체크는 표준의 BITMAPINFOHEADER 구조체이다. 스트림포맛트체크는, 옵션으로 DVINFO 구조체를 포함하도록(듯이) 확장할 수 있다. 그 경우는, 스트림포맛트체크의 사이즈를 40 바이트 (BITMAPINFOHEADER 구조체의 사이즈)에서 72 바이트 (BITMAPINFOHEADER＋DVINFO 구조체의 사이즈)로 변경해,BITMAPINFOHEADER 데이터 구조체의 직후에 DVINFO 데이터 구조체를 기술한다.

오디오 스트림은 표준 오디오 스트림 헤더 (fccType 멤버값이 'auds')에 의해 지정된다. fccHandler 멤버는, 오디오 스트림에서는 사용하지 않는다.

DV 비디오 데이터는, 전의 「1 개의 DV 데이터 스트림을 포함한 AVI 파일」로 설명했던 대로, '##dc'체크로서 저장 된다. 오디오 데이터는, '##wb'체크로서 'movi'체크에 저장 된다.

다음의 그림에, DV 비디오를 'vids'스트림으로서 포함해 DV 오디오를 'auds'스트림으로서 포함한 AVI 파일을 DirectShow 필터 그래프를 사용해 재생하는 예를 나타낸다 (DV 비디오 디코더 필터는, 특히 DV 데이터를 취급하기 위해서(때문에) DirectShow 에 준비되어 있다). 미디어 타입은,DV 미디어 타입의 겉(표)에 정의되고 있다.

DV 비디오를 'vids' 스트림으로서 포함해 DV 오디오를 'auds' 스트림으로서 포함한 AVI 파일의 재생

다음의 그림에, DV 비디오를 'vids'스트림으로서 포함해 DV 오디오를 'auds'스트림으로서 포함한 AVI 파일을 DirectShow 필터 그래프를 사용해 생성 하는 예를 나타낸다 (DV 비디오 디코더는, 특히 DV 데이터를 취급하기 위해서(때문에) DirectShow 에 준비되어 있다). 미디어 타입은,DV 미디어 타입의 겉(표)에 정의되고 있다. 업 스트림 필터는, 여기에는 나타나지 않지만, 적절한 미디어 타입 D 및 E 를 생성하는 임의의 편성을 사용할 수 있다.

DV 비디오를 'vids' 스트림으로서 포함해 DV 오디오를 'auds' 스트림으로서 포함한 AVI 파일의 생성

다음의 그림에, DV 비디오를 'vids'스트림으로서 포함해 DV 오디오를 'auds'스트림으로서 포함한 AVI 파일을 DirectShow 필터 그래프를 사용해 생성 하는 예를 나타낸다. 여기에서는, 하드웨어 디바이스 드라이버를 통해 DV 디바이스 (1394 베이스의 DV 캠 코다등)와 통신하는 소스 필터를 DV 데이터 입력으로서 사용하고 있다 (이 소스 필터와 DV 스플리터 필터는, 특히 DV 데이터를 취급하기 위해서(때문에) DirectShow 에 준비되어 있다). 미디어 타입은,DV 미디어 타입의 겉(표)에 정의되고 있다.

DV 비디오를 'vids' 스트림으로서 포함해 DV 오디오를 'auds' 스트림으로서 포함한 AVI 파일에의 DV 캡춰

다음의 그림에, DV 비디오를 'vids'스트림으로서 포함해 DV 오디오를 'auds'스트림으로서 포함한 AVI 파일을 DirectShow 필터 그래프를 사용해 출력하는 예를 나타낸다. 여기에서는, 하드웨어 디바이스 드라이버를 통해 DV 디바이스 (1394 베이스의 DV 캠 코다등)와 통신하는 세면대 필터를 DV 데이터 출력으로서 사용하고 있다 (이 세면대 필터와 DV Muxer 필터는, 특히 DV 데이터를 취급하기 위해서(때문에) DirectShow 에 준비되어 있다). 미디어 타입은,DV 미디어 타입의 겉(표)에 정의되고 있다.

DV 비디오를 'vids' 스트림으로서 포함해 DV 오디오를 'auds' 스트림으로서 포함한 AVI 파일의 출력

다음의 예는, 완전한 헷다체크에 의해 확장된, DV 비디오를 'vids'스트림으로서 포함해 DV 오디오를 'auds'스트림으로서 포함한 AVI 파일의 AIFF RIFF 포맷을 나타낸다 ('vids'스트림의 'strf'사브체크에 대해,BITMAPINFO 의 뒤에 옵션으로 DVINFO 데이터가 기술되고 있다).

00000000 RIFF (103E2920) 'AVI '
0000000C LIST (00000146) 'hdrl'
00000018 avih (00000038)
dwMicroSecPerFrame    : 33367
dwMaxBytesPerSec      : 3728000
dwPaddingGranularity  : 0
dwFlags               :0x810 HASINDEX | TRUSTCKTYPE
dwTotalFrames         : 2192
dwInitialFrames       : 0
dwStreams             : 2
dwSuggestedBufferSize : 120000
dwWidth               : 720
dwHeight              : 480
dwReserved            :0x0
00000058         LIST (00000094) 'strl'
00000064             strh (00000038)
fccType               :'vids'
fccHandler            :'dvsd'
dwFlags               :0x0
wPriority             : 0
wLanguage             :0x0 undefined
dwInitialFrames       : 0
dwScale               :100 (29.970 Frames/Sec)
dwRate                : 2997
dwStart               : 0
dwLength              : 2192
dwSuggestedBufferSize : 120000
dwQuality             : 0
dwSampleSize          : 0
rcFrame               : 0,0,720,480
000000A4             strf (00000048)
                         biSize          : 40
                         biWidth         : 720
                         biHeight        : 480
                         biPlanes        : 1
                         biBitCount      : 24
                         biCompression   : 0x64737664 'dvsd'
                         biSizeImage     : 120000
                         biXPelsPerMeter : 0
                         biYPelsPerMeter : 0
                         biClrUsed       : 0
                         biClrImportant  : 0
dwDVAAuxSrc     :0x........
dwDVAAuxCtl     :0x........
dwDVAAuxSrc1    :0x........
dwDVAAuxCtl1    :0x........
dwDVVAuxSrc     :0x........
dwDVVAuxCtl     :0x........
dwDVReserved[2] : 0,0
000000F4         LIST (0000005E) 'strl'
00000100             strh (00000038)
fccType               :'auds'
fccHandler            : '    '
dwFlags               :0x0
wPriority             : 0
wLanguage             :0x0 undefined
dwInitialFrames       : 0
dwScale               : 1 (32000.000 Samples/Sec)
dwRate                : 32000
dwStart               : 0
dwLength              : 2340474
dwSuggestedBufferSize : 4272
dwQuality             : 0
dwSampleSize          : 4
rcFrame               : 0,0,0,0
00000140             strf (00000012)
                         wFormatTag      : 1 PCM
                         nChannels       : 2
                         nSamplesPerSec  : 32000
                         nAvgBytesPerSec : 128000
                         nBlockAlign     : 4
                         wBitsPerSample  : 16
                         cbSize          : 0
00000814     LIST (103D0EF4) 'movi'
103D1710     idx1 (00011210)

AVI RIFF 파일의 레퍼런스

Microsoft AVI 파일 포맷은, 오디오/비디오 순서의 캡춰, 편집, 재생을 실시하는 어플리케이션으로 사용되는 RIFF 파일 사양이다. 일반적으로, AVI 파일에는 다른 종류의 데이터의 스트림이 복수 포함된다. 대부분의 AVI 순서는, 오디오 스트림과 비디오 스트림의 양쪽 모두를 사용한다. 단순한 AVI 순서에서는, 비디오 데이터만을 사용해, 오디오 스트림은 필요로 하지 않는다.

원래의 AVI 파일 사양에 대해서 OpenDML AVI File Format Extensions 로 더해진 변경에 대해서는, 이 섹션에서는 채택하지 않는다. 상세한 것에 대하여는, 「OpenDML AVI File Format Extensions」(OpenDML AVI M-JPEG File Format Subcommittee 편, 1996 년 2 월 28 일)의 버젼 1.02 를 참조할것.

이 섹션에는, 이하의 내용이 포함된다.

  • AVI RIFF 포맷
  • AVI 메인 헤더
  • AVI 스트림 헤더
  • 스트림 데이터 (LIST 'movi'체크)
  • BITMAPINFOHEADER 구조체
  • WAVEFORMATEX 구조체

AVI RIFF 포맷

AVI 파일은, AVI RIFF 포맷을 사용한다. AVI RIFF 포맷은, FOURCC (4 문자 코드) 'AVI '에 의해 식별된다. 모든 AVI 파일에는, 2 개의 필수의 LIST 체크가 포함된다. 이러한 체크는, 스트림과 스트림 데이터의 포맷을 정의한다. AVI 파일에는, 인젝스체크가 포함되는 경우도 있다. 이 옵션의 체크는, 파일내에서의 데이타체크의 위치를 지정한다. 이러한 요소를 포함한 AVI 파일은, 다음과 같은 포맷을 가진다.

RIFF ('AVI '
LIST ('hdrl'
              .
              .
              .
           )
LIST ('movi'
              .
              .
              .
           )
['idx1'<AVI Index>]
     )

LIST 체크와 인젝스체크는, RIFF 'AVI '체크의 사브체크이다. 'AVI '체크는, 파일이 AVI RIFF 파일인 것을 나타낸다. LIST 'hdrl'체크는 데이터의 포맷을 정의해, 이것은 최초의 필수 LIST 체크이다. LIST 'movi'체크는 AVI 순서의 데이터를 포함해, 이것은 2 번째의 필수 체크이다. 'idx1'체크는 인젝스체크이다. AVI 파일에는, 이 3 개의 컴퍼넌트를 적절한 순서로 포함할 필요가 있다.

LIST 'hdrl' 및 LIST 'movi'체크는, 그 데이터에 대해서 사브체크를 사용한다. 다음의 예에, LIST 'hdrl' 및 LIST 'movi'체크를 완성시키는데 필요한 체크를 추가한 AVI RIFF 포맷을 나타낸다.

RIFF ('AVI '
LIST ('hdrl'
            'avih'(<Main AVI Header>)
            LIST ('strl'
                  'strh'(<Stream header>)
                  'strf'(<Stream format>)
                  'strd'(<additional header data>)
                  'strn'(<Stream name>)
                  ...
                 )
             .
             .
             .
           )

LIST ('movi'
            {SubChunk | LIST ('rec '
                              SubChunk1
                              SubChunk2
                                .
                                .
                                .
                             )
               .
               .
               .
            }
            .
            .
            .
           )

['idx1'<AVI Index>]
     )

AVI 메인 헤더

이후의 섹션에서는, LIST 'hdrl' 및 LIST 'movi'체크에 포함되는 체크에 대해 설명한다. 'idx1'체크에 대해서는, 이 문서에서는 설명하지 않는다. AVI 파일의 'idx1'체크 및 인덱스의 상세한 것에 대하여는, 「OpenDML AVI File Format Extensions」(OpenDML AVI M-JPEG File Format Subcommittee 편, 1996 년 2 월 28 일)의 버젼 1.02 를 참조할것.

파일은 메인 헤더로 시작된다. AVI 파일의 경우, 이 헤더는 'avih'라고 하는 FOURCC (4 문자 코드)로 나타난다. 헤더에는, 파일내의 스트림수, AVI 순서의 폭과 높이 등, AVI 파일 전체에 관한 글로벌 정보가 포함된다. AVI 메인 헤더 구조체는, 다음과 같이 정의된다.

typedef struct {
    DWORD dwMicroSecPerFrame;
    DWORD dwMaxBytesPerSec;
    DWORD dwReserved1;
    DWORD dwFlags;
    DWORD dwTotalFrames;
    DWORD dwInitialFrames;
    DWORD dwStreams;
    DWORD dwSuggestedBufferSize;
    DWORD dwWidth;
    DWORD dwHeight;
    DWORD dwReserved[4];
} MainAVIHeader;
dwMicroSecPerFrame
프레임간의 간격을 마이크로 세컨드 단위로 지정한다. 이 값은 파일의 전체의 타이밍을 나타낸다.
dwMaxBytesPerSec
파일의 개산 최대 데이터 레이트를 지정한다. 이 값은, 메인 헤더 및 스트림헷다체크에 포함되는 다른 파라미터에 따라 AVI 순서를 표시하기 위해서, 시스템이 처리해야 하는 매초의 바이트수를 나타낸다.
dwReserved1
예약되고 있다. 제로로 설정하는 것.
dwFlags
파일에 대한 플래그를 포함한다. 이하의 플래그가 정의되고 있다.
AVIF_HASINDEX | AVI 파일의 마지막에 인덱스를 포함한 'idx1'체크가 있는 것을 나타낸다. 양호한 퍼포먼스를 위해서(때문에)는, 모든 AVI 파일이 인덱스를 포함할 필요가 있다.
AVIF_MUSTUSEINDEX | 데이터의 프레젠테이션의 순서를 결정하기 위해서(때문에), 파일내의 체크의 물리적인 순서는 아니고, 인덱스를 사용하는 것을 나타낸다. 예를 들어, 이것을 사용해 프레임의 리스트를 생성 해 편집할 수가 있다.
AVIF_ISINTERLEAVED | AVI 파일이 인터리브 되고 있는 것을 나타낸다.
AVIF_WASCAPTUREFILE | AVI 파일이, 리얼타임 비디오의 캡춰용으로 특별히 할당할 수 있었던 파일인 것을 나타낸다. 어플리케이션은, 이 플래그가 설정된 파일을 오버라이드(override) 하기 전에, 유저에게 경고를 발표할 필요가 있다. 이것은, 유저가 이 파일을 데후라그먼트 하고 있을 가능성이 높기 때문에이다.
AVIF_COPYRIGHTED | AVI 파일에 저작권이 있는 데이터 및 소프트웨어가 포함되어 있는 것을 나타낸다. 이 플래그가 사용되고 있는 경우, 소프트웨어는 데이터의 복제를 허가해서는 안된다.
dwTotalFrames
파일내의 데이터의 프레임의 총수를 지정한다.
dwInitialFrames
인터리브 된 파일의 시작 프레임을 지정한다. 인터리브 된 파일 이외에서는, 제로를 지정한다. 인터리브 된 파일을 생성 하는 경우, 파일내에서 AVI 순서의 시작 프레임보다 전에 있는 프레임수를, 이 멤버로 지정한다. 이 멤버의 내용에 관한 상세한 것에 대하여는, 「Video for Windows Programmer's Guide」의 「Special Information for Interleaved Files」를 참조할것.
dwStreams
파일내의 스트림수를 지정한다. 예를 들어, 오디오와 비디오를 포함한 파일에는 2 개의 스트림이 있다.
dwSuggestedBufferSize
파일을 읽어내기 위한 버퍼 사이즈를 지정한다. 일반적으로, 이 사이즈는 파일내의 최대의 체크를 저장 하는데 충분한 크기로 한다. 제로로 설정하거나 너무 작은 값으로 설정했을 경우, 재생 소프트웨어는 재생중에 메모리를 재할인 맞히고 하지 않으면 안되어, 퍼포먼스가 저하한다. 인터리브 된 파일의 경우, 버퍼 사이즈는 체크는 아니고 레코드 전체를 읽어내는데 충분한 크기가 아니면 안된다.
dwWidth
AVI 파일의 폭을 픽셀 단위로 지정한다.
dwHeight
AVI 파일의 높이를 픽셀 단위로 지정한다.
dwReserved[4]
예약되고 있다. 이 배열은 제로로 설정한다.

AVI 스트림 헤더

메인 헤더의 다음에는, 1 개(살) 이상의 'strl'체크가 계속된다 ('strl'체크는 각 데이터 스트림 마다 필요하다). 이러한 체크에는, 파일내의 스트림에 관한 정보가 포함된다. 각 'strl'체크에는, 스트림헷다체크와 스트림포맛트체크가 반드시 포함된다. 스트림헷다체크는, FOURCC (4 문자 코드) 'strh'로 나타나 스트림포맛트체크는, FOURCC 'strf'로 나타난다. 스트림헷다체크와 스트림포맛트체크에 가세해, 'strl'체크에는 스트림헷다데이타체크와 스트림명 체크가 포함되는 경우가 있다. 스트림헷다데이타체크는 FOURCC 'strd'로 나타난다. 스트림명 체크는 FOURCC 'strn'로 나타난다.

스트림 헤더 구조체에는, 파일내의 단일의 스트림에 대한 헤더 정보가 포함된다.

typedef struct {
    FOURCC fccType;
    FOURCC fccHandler;
    DWORD dwFlags;
    DWORD  dwPriority;
    DWORD dwInitialFrames;
    DWORD  dwScale;
    DWORD  dwRate;
    DWORD  dwStart;
    DWORD  dwLength;
    DWORD dwSuggestedBufferSize;
    DWORD  dwQuality;
    DWORD  dwSampleSize;
    RECT   rcFrame;
} AVIStreamHeader;

스트림 헤더는, FOURCC 를 사용해, 스트림에 포함되는 데이터의 타입 (오디오, 비디오등)을 지정한다.

fccType
스트림에 포함되는 데이터의 타입을 지정하는 FOURCC 를 포함한다. 비디오 및 오디오에 대해서 이하의 표준 AVI 값이 정의되고 있다.
'vids' | 스트림에 비디오 데이터가 포함되는 것을 나타낸다. 스트림포맛트체크에는, 팔레트 정보를 포함하는 것이 가능한 BITMAPINFO 구조체가 포함된다.
'auds' | 스트림에 오디오 데이터가 포함되는 것을 나타낸다. 스트림포맛트체크에는,WAVEFORMATEX 또는 PCMWAVEFORMAT 구조체가 포함된다.
'txts' | 스트림에 텍스트 데이터가 포함되는 것을 나타낸다.
fccHandler
특정의 데이터 핸들러를 나타내는 FOURCC 를 포함한다 (옵션). 데이터 핸들러는, 스트림에 대해서 적절한 핸들러이다. 오디오 및 비디오 스트림의 경우는, 인스톨 가능한 압력 또는 데콘프렛사를 지정한다.
dwFlags
데이터 스트림에 대한 플래그를 포함한다. 이러한 플래그의 상위 워드의 비트는, 스트림에 포함되는 데이터의 타입에 고유하다. 이하의 표준 플래그가 정의되고 있다.
AVISF_DISABLED | 이 스트림을 디폴트로 유효하게 하지 않는 것을 나타낸다.
AVISF_VIDEO_PALCHANGES | 이 비디오 스트림으로 팔레트의 변경이 포함되는 것을 나타낸다. 이 플래그는, 재생 소프트웨어에 대해서, 팔레트를 애니메이션 할 필요가 있는 것을 경고한다.
dwPriority
스트림 타입의 우선 순위를 지정한다. 예를 들어, 복수의 오디오 스트림을 포함한 파일에서는, 우선 순위의 가장 높은 스트림이 디폴트의 스트림이 된다.
dwInitialFrames
인터리브 된 파일로, 오디오 데이터가 비디오 프레임으로부터 어느 정도 skew 되고 있는지를 지정한다. 보통은, 약 0.75 초이다. 인터리브 된 파일을 생성 하는 경우, 파일내에서 AVI 순서의 시작 프레임보다 전에 있는 프레임수를, 이 멤버로 지정한다. 이 멤버의 내용에 관한 상세한 것에 대하여는, 「Video for Windows Programmer's Guide」의 「Special Information for Interleaved Files」를 참조할것.
dwScale
dwRate 와 함께 사용해, 이 스트림이 사용하는 타임즈 케일을 지정한다. dwRate 를 dwScale 로 나누는 것으로, 1 초 쯤의 샘플수가 요구된다. 비디오 스트림의 경우, 이 레이트는 frame rate에 동일해진다. 오디오 스트림의 경우, 이 레이트는 nBlockAlign 바이트의 오디오 데이터에 필요한 시간에 대응한다. 이것은 PCM 오디오의 경우는 샘플 레이트에 동일해진다.
dwRate
dwScale 를 참조할것.
dwStart
AVI 파일의 시작 타임을 지정한다. 단위는, 메인 파일 헤더의 dwRate 및 dwScale 멤버에 의해 정의된다. 보통, 이것은 제로이지만, 파일과 동시에 시작 되지 않는 스트림에 대해서는, 지연 시간을 지정할 수가 있다.
dwLength
이 스트림의 길이를 지정한다. 단위는, 스트림의 헤더의 dwRate 및 dwScale 멤버에 의해 정의된다.
dwSuggestedBufferSize
이 스트림을 읽어내기 위해서(때문에) 필요한 버퍼의 크기를 지정한다. 보통은, 스트림내의 최대의 체크에 대응하는 값이다. 올바른 버퍼 사이즈를 사용하는 것으로, 재생의 효율이 높아진다. 올바른 버퍼 사이즈를 모르는 경우는, 제로를 지정한다.
dwQuality
스트림내의 데이터의 품질을 나타내는 값을 지정한다. 품질은, 0 ~ 10,000 의 범위의 값으로 나타난다. 압축 데이터의 경우, 이것은 보통, 압축 소프트웨어에게 건네지는 품질 파라미터의 값을 나타낸다. –1 로 설정했을 경우, 드라이버는 디폴트의 품질값을 사용한다.
dwSampleSize
데이터의 1 샘플의 사이즈를 지정한다. 샘플의 사이즈가 변화하는 경우는, 제로로 설정한다. 이 값이 제로가 아닌 경우, 파일내에서 복수의 데이터 샘플을 1 개의 체크에 그룹화 할 수 있다. 제로의 경우, 각 데이터 샘플 (비디오 프레임등)은 각각 다른 체크에 포함되지 않으면 안 된다. 비디오 스트림의 경우, 이 값은 보통 제로이지만, 모든 비디오 프레임이 같은 사이즈이면, 제로 이외의 값에도 할 수 있다. 오디오 스트림의 경우, 이 값은 오디오를 기술하는 WAVEFORMATEX 구조체의 nBlockAlign 멤버와 같지 않으면 안 된다.
rcFrame
AVI 메인 헤더 구조체의 dwWidth 및 dwHeight 멤버에 의해 지정되는 동영상 직사각형내의 텍스트 또는 비디오 스트림에 대한 전송처 직사각형을 지정한다. 보통,rcFrame 멤버는, 복수의 비디오 스트림을 지원 하기 위해서 사용된다. 이 직사각형은, 동영상 직사각형에 대응하는 좌표로 설정해, 동영상 직사각형 전체를 갱신한다. 이 멤버의 단위는 픽셀이다. 전송처 직사각형의 좌상구석은, 동영상 직사각형의 좌상구석으로부터의 상대 지정이 된다.

마지막 8 개의 멤버는, 스트림의 재생 특성을 기술한다. 이러한 요소에는, 재생 레이트 (dwScale 와 dwRate), 순서의 시작 타임 (dwStart), 순서의 길이 (dwLength), 재생 버퍼의 사이즈 (dwSuggestedBuffer), 데이터 품질의 지표 (dwQuality), 및 샘플 사이즈 (dwSampleSize)가 포함된다.

스트림 헤더 구조체의 멤버의 몇개인가는, 메인 헤더 구조체에도 포함된다. 메인 헤더의 데이터는 파일 전체에 적용되어 스트림 헤더의 데이터는 스트림에만 적용된다.

스트림 헤더 ('strh') 체크의 다음에는, 스트림 포맷 ('strf') 체크가 계속된다. 스트림포맛트체크는, 스트림내의 데이터의 포맷을 기술한다. 비디오 스트림의 경우, 이 체크내의 정보는 BITMAPINFO 구조체 (해당하는 경우는 팔레트 정보를 포함한다)이다. 오디오 스트림의 경우, 이 체크내의 정보는 WAVEFORMATEX 또는 PCMWAVEFORMAT 구조체이다 (WAVEFORMATEX 구조체는 WAVEFORMAT 구조체의 확장판이다). 이 구조체 및 다른 스트림 타입의 상세한 것에 대하여는, 「New Multimedia Data Types and Data Techniques Standards Update」를 참조할것.

'strl'체크에는, 스트림 헤더 데이터 ('strd') 체크가 추가되는 경우가 있다. 이 체크를 사용하는 경우는, 스트림포맛트체크의 뒤에 기술한다. 이 체크의 포맷과 내용은, 인스톨 가능한 압축 또는 복원 드라이버에 의해 정의된다. 보통, 이러한 드라이버는 이 정보를 사용해 설정을 실시한다. RIFF 파일을 읽고 쓰기하는 어플리케이션은, 이 정보를 디코드할 필요는 없다. 어플리케이션은 드라이버와의 사이에 이 데이터를 메모리 블록으로서 전송 한다.

옵션의 'strn'스트림명 체크는, 스트림에 대해 설명하는 제로 종단 캐릭터 라인을 제공한다. (AVI 파일 함수로 이 체크를 사용하는 것으로써, 어플리케이션은 액세스 하고 싶은 스트림을 이름으로 식별할 수가 있다. )

AVI 플레이어는, 'strl'체크의 순서에 근거해, LIST 'hdrl'체크내의 스트림 헤더를 LIST 'movi'체크내의 스트림 데이터와 관련짓는다. 최초의 'strl'체크는 스트림 0 에 대응해, 2 번째의 'strl'체크는 스트림 1 에 대응해, 이하와 같이 계속된다.

예를 들어, 최초의 'strl'체크가 wave 오디오 데이터를 기술하는 경우, 그 wave 오디오 데이터는 스트림 0 에 포함된다. 같이 2 번째의 'strl'체크가 비디오 데이터를 기술하는 경우, 그 비디오 데이터는 스트림 1 에 포함된다.

스트림 데이터 (LIST 'movi'체크)

헤더 정보의 다음에 계속되는 것은, 스트림내의 실제의 데이터 (화면이나 사운드 그 자체)의 체크를 포함한 LIST 'movi'체크이다. 데이타체크는, LIST 'movi'체크내에 직접 기술하는 경우와'rec'체크에 그룹화 하는 경우가 있다. 'rec'에의 그룹화는, 그룹화 된 체크가 디스크로부터 한 번에 읽어내지는 것을 의미한다. 이것은, CD-ROM 로부터 재생하기 위해서 특별히 인터리브 된 파일의 경우에만 사용된다.

모든 RIFF 체크와 같게, 데이타체크에는 체크타이프를 식별하는 FOURCC (4 문자 코드)가 포함된다. FOURCC 는, 1 문자에서 4 문자의 ASCII 영숫자의 순서로 나타내지는 32 비트량이다 (우측은 공백 몬지를 묻을 수 있다). 각 체크를 식별하는 FOURCC 는, 스트림 번호와 체크내에 캡슐화된 정보의 타입을 정의하는 2 문자의 코드로 구성된다. 예를 들어, 파형 체크는 2 문자 코드 'wb'로 나타난다. 파형 체크가 2 번째의 LIST 'hdrl'스트림 기술에 대응하고 있는 경우, FOURCC 는 '01wb'된다.

주 : 2 문자 코드는 스트림을 기술하는데 편리한 방법이지만, 다른 어플리케이션이 그것을 인식 하면은 한정되지 않는다. 스트림을 생성 하거나 정보를 다른 어플리케이션에 전송 하는 경우에는, FOURCC 를 사용하는 것.

포맷 정보는 모두 헤더에 포함되기 (위해)때문에, 이러한 데이타체크내의 오디오 데이터에 포맷에 관한 정보를 포함해서는 안 된다. 오디오데이타체크의 포맷을 다음에 나타낸다 (## 는 스트림 식별자).

WAVE Bytes '##wb'
BYTE  abBytes[];

음성 데이터는, 압축 DIB 또는 비압축 DIB 이다. 비압축 DIB 의 경우, 관련하는 BITMAPINFO 구조체의 biCompression 멤버에 BI_RGB 가 지정되고 있다. 압축 DIB 의 경우는,biCompression 멤버에 BI_RGB 이외의 값이 지정되고 있다. 압축 포맷의 상세한 것에 대하여는, 「Microsoft Windows Programmer's Reference」로 BITMAPINFOHEADER 데이터 구조체의 설명을 참조할것.

비압축 DIB 의 데이타체크에는 RGB 비디오 데이터가 포함된다. 이러한 체크는, 2 문자 코드 'db' (db 는 DIB bits 의 약어)로 식별된다. 압축 DIB 의 데이타체크는, 2 문자 코드 'dc' (dc 는 DIB compressed 의 약어)로 식별된다. 어느 쪽의 데이타체크도, DIB 에 관한 헤더 정보는 포함하지 않았다. 비압축 DIB 의 데이타체크의 포맷을 다음에 나타낸다.

DIB  Bits  '##db'
BYTE  abBits[];

압축 DIB 의 데이타체크의 포맷을 다음에 나타낸다.

Compressed DIB  Bits  '##dc'
BYTE  abBits[];

비데오데이타체크는, AVI 순서내에서 팔레트를 갱신하기 위한 새로운 팔레트 엔트리를 정의할 수도 있다. 팔레트 정보의 지정의 상세한 것에 대하여는, 「Video for Windows Programmer's Guide」를 참조할것.

텍스트 스트림에는 임의의 2 문자 코드를 사용할 수 있다.

BITMAPINFOHEADER 구조체

BITMAPINFOHEADER 구조체에는, AVI RIFF 파일의 비디오 스트림에 관한 정보가 포함된다. 이 구조체에는 이하의 멤버가 포함된다.

typedef struct tagBITMAPINFOHEADER {
    DWORD  biSize;
    LONG   biWidth;
    LONG   biHeight;
    WORD   biPlanes;
    WORD   biBitCount;
    DWORD  biCompression;
    DWORD  biSizeImage;
    LONG   biXPelsPerMeter;
    LONG   biYPelsPerMeter;
    DWORD  biClrUsed;
    DWORD  biClrImportant;
} BITMAPINFOHEADER;
biSize
구조체가 필요로 하는 바이트수를 지정한다.
biWidth
비트 맵의 폭을 픽셀 단위로 지정한다.
biHeight
비트 맵의 높이를 픽셀 단위로 지정한다. biHeight 의 값이 정인 경우, 비트 맵은 보텀 업 DIB (device-independent bitmap : 디바이스에 의존하지 않는 비트 맵)이며, 왼쪽 하단 모서리가 원점이 된다. biHeight 의 값이 부인 경우, 비트 맵은 탑 다운 DIB 이며, 좌상구석이 원점이 된다.
biPlanes
타겟 디바이스에 대한 면의 수를 지정한다. 이것은 반드시 1 으로 설정한다.
biBitCount
1 픽셀 근처의 비트수를 지정한다. 압축 포맷에 따라서는, 픽셀의 정색해 구디코드하기 위해서 이 정보가 필요하다.
biCompression
사용되고 있다, 또는 요구되고 있는 압축의 타입을 지정한다. 기존의 압축 포맷과 새로운 압축 포맷의 양쪽 모두로 이 멤버를 사용한다.
biSizeImage
이미지의 사이즈를 바이트 단위로 지정한다. 비압축 RGB 비트 맵의 경우는, 0 으로 설정할 수 있다.
biXPelsPerMeter
비트 맵의 타겟 디바이스의 수평 해상도를 1 미터 당의 픽셀 단위로 지정한다. 어플리케이션은 이 값을 사용해, 리소스 그룹중에서 현재의 디바이스의 특성에 가장 적합하는 비트 맵을 선택할 수가 있다.
biYPelsPerMeter
비트 맵의 타겟 디바이스의 수직 해상도를 1 미터 당의 픽셀 단위로 지정한다.
biClrUsed
칼라 테이블내의 칼라 인덱스 가운데, 비트 맵내에서 실제로 사용되는 인덱스의 수를 지정한다. 이 값이 제로의 경우, 비트 맵은,biCompression 로 지정되는 압축 모드에 대해서,biBitCount 멤버의 값에 대응하는 최대 색 가지수를 사용한다.
biClrImportant
비트 맵을 표시하기 위해서 중요로 간주해지는 칼라 인덱스수를 지정한다. 이 값이 제로의 경우는, 모든 색이 중요로 간주해진다.

biBitCount 멤버의 값이 8 보다 큰 값으로 설정되었을 경우, 비디오 드라이버는 비트 맵이 트루 칼라이라고 간주할 수가 있어 칼라 테이블을 사용하지 않는다.

biBitCount 멤버의 값이 8 이하의 값으로 설정되었을 경우, 비디오 드라이버는 비트 맵이 BITMAPINFO 데이터 구조체에 정의된 팔레트 또는 칼라 테이블을 사용하고 있으면(자) 간주할 수가 있다. 이 데이터 구조체는, 이하의 멤버를 가진다.

typedef struct tagBITMAPINFO {
    BITMAPINFOHEADER bmiHeader;
    RGBQUAD          bmiColors[1];
} BITMAPINFO;

BITMAPINFO 의 bmiheader 멤버는,BITMAPINFOHEADER 구조체를 지정한다. BITMAPINFO 의 bmiColors 멤버는, 비트 맵내의 색을 정의하는 RGBQUAD 데이터형의 배열을 지정한다.

WAVEFORMATEX 구조체

WAVEFORMATEX 구조체에는, AVI RIFF 파일의 오디오 데이터 스트림에 관한 정보가 포함된다. 이 구조체에는 이하의 멤버가 포함된다.

typedef struct waveformat_extended_tag {
    WORD  wFormatTag;
    WORD  nChannels;
    DWORD nSamplesPerSec;
    DWORD nAvgBytesPerSec;
    WORD  nBlockAlign;
    WORD  wBitsPerSample;
    WORD  cbSize;
} WAVEFORMATEX;
wFormatTag
오디오 스트림의 오디오 파형 타입을 정의한다. 포맷 태그의 완전한 리스트는, Microsoft® Visual C++® 및 다른 Microsoft 제품에 부속되는 Mmreg.h 헤더 파일에 있다.
nChannels
오디오 스트림내의 채널수를 지정한다. 1 은 물건, 2 는 스테레오를 나타낸다.
nSamplesPerSec
오디오 스트림의 샘플 레이트 주파수를 샘플/초 (Hz)에 지정한다. 예를 들어, 11,025, 22,050, 또는 44,100.
nAvgBytesPerSec
평균 데이터 레이트를 지정한다. 재생 소프트웨어는 이 값을 사용해 버퍼 사이즈를 추측할 수가 있다.
nBlockAlign
데이터의 블록 alignment를 바이트 단위로 지정한다. 재생 소프트웨어가 1 회에 처리하는 데이터의 바이트수는 nBlockAlign 의 정수배가 아니면 안되기 때문에,nBlockAlign 의 값을 사용해 버퍼의 alignment를 실시할 수가 있다.
wBitsPerSample
채널 데이터마다의 1 샘플 근처의 비트수를 지정한다. 각 채널의 샘플 해상도는 같다라고 가정된다. 이필드가 필요없는 경우는, 제로로 설정한다.
cbSize
포맷 헤더내의 추가 정보의 사이즈를 바이트 단위로 지정한다. 이것에는,WAVEFORMATEX 구조체의 사이즈는 포함되지 않는다. 예를 들어,wFormatTag WAVE_FORMAT_IMA_ADPCM 에 대응하는 wave 포맷의 경우,cbSize 는 sizeof(IMAADPCMWAVEFORMAT) - sizeof(WAVEFORMATEX)로서 계산되어 결과는 2 가 된다.

AVI 2.0 파일 포맷 확장

현재 DirectShow 는, 이하의 AVI 2.0 파일 포맷 확장을 지원 하고 있다.

  • 큰 AVI 파일 사이즈 (1 GB 이상)
  • 계층적인 인덱스

「OpenDML AVI File Format Extensions」(OpenDML AVI M-JPEG File Format Subcommittee 편, 1996 년 2 월 28 일)의 버젼 1.02 에 기재된 사양을 참조할것.


커스텀 파일 타입의 등록

이 주제에서는, 파일 리더 소스 필터로 인식할 수 있도록(듯이) 새로운 파일 타입을 등록하는 방법에 대해 설명한다. 여기서 이용되는 메카니즘은 Microsoft® Win32® 의 GetClassFile 함수로 사용되고 있어서 , 특정의 파일명에 관련지을 수 있었던 CLSID 를 돌려준다. Microsoft® DirectShow® 의 미디어 타입에서는 레지스트리내의 4 개의 값세트를 사용하고 있어, 이것은 GetClassFile 의 FileType 등록으로 사용되는 것 것과 같다. 다만, 이 기준에 합치하는 파일은 파일 타입은 아니고 미디어 타입에 관련지을 수 있다. 또, DirectShow 미디어 타입의 레지스트리 엔트리에는, 이 미디어 타입을 읽어내기 위해서(때문에) 사용할 수 있는소스 필터의 CLSID 가 제공된다.

FileType 등록과 MediaType 등록의 머지않아냄새나도, 레지스트리내의 패턴에는 다음의 포맷의 엔트리열이 포함된다.

regdb key = offset, cb, mask, value

미디어 타입은 CLSID 의 페어 {Majortype clsid, Subtype clsid} 로서 정의된다. 파일내의 지정된 오프셋(offset) 위치에 있는 데이터가 HKEY_CLASSES_ROOT\Media Type\{<major type>}\{<subtype>} 내의 패턴과 일치했을 경우, 그 패턴에 관련지을 수 있었던 미디어 타입 CLSID 페어가 파일의 미디어 타입이 된다.

레지스트리 키의 파라미터는 다음과 같이 해석된다. offset 의 값은 파일의 선두 또는 말미로부터의 오프셋(offset)이며,cb 는 길이 (바이트 단위)이다. 이 2 개의 10 진값은, 파일내의 특정의 바이트 범위를 나타낸다 (오프셋(offset)값이 부의 경우는 파일의 말미로부터의 오프셋(offset)를 나타낸다). mask 값은 16 진의 비트 마스크이며,offset 와 cb 로 지정된 바이트 범위와의 논리 AND 연산에 사용된다. 논리 AND 연산의 결과는 value 라고 비교된다. 마스크를 생략 했을 경우는, 모두 1 으로 가정된다. mask 와 value 내의 16 진의 자리수는,cb 의 값의 2 배가 아니면 안된다 (cb 는 바이트 단위이기 (위해)때문에).

레지스트리내의 각 패턴은, 데이타베이스내의 패턴의 순서에 따라 파일이라고 비교된다. 각각의 값이 AND 연산의 결과와 일치한 최초의 패턴이, 파일의 미디어 타입을 결정한다.

각 엔트리에는, 4 개의 값의 조가 복수 포함되는 경우도 있다. 그 경우는, 모든 조가 파일내의 데이터와 일치했을 경우에, 미디어 타입을 파일에 관련지을 수 있다. 1 개의 엔트리에 4 개의 값의 조를 복수 사용하는 예로서는, 바이트 순서를 파일의 선두와 말미의 양쪽 모두와 일치시키는 경우등이 있다. 다음의 예에서는, 파일의 최초의 4 바이트로서 패턴 AB CD 12 34, 파일의 마지막 4 바이트로서 AB AB 00 AB 를 지정하고 있다 (마스크는 적용되지 않았다). 파일을 미디어 타입에 관련지으려면 , 패턴에 대해서 모든 요소가 일치할 필요가 있다.

0 = REG_SZ 0, 4, , ABCD1234,  -4, 4, , ABAB00AB

또, 1 개의 미디어 타입에 대해 복수의 엔트리가 지정되는 경우도 있다. 이 경우, 어느쪽이든 1 개의 엔트리에 일치하면, 파일이 미디어 타입에 관련지을 수 있다.

예를 들어, 다음의 레지스트리 엔트리에 포함되는 패턴에서는, 최초의 3 바이트가 AB CD 12, 4 번째의 바이트가 32, 33, 34, 또는 35, 그리고 마지막 4 바이트가 FE FE FE FE 일 필요가 있다.

HKEY_CLASSES_ROOT
Media Type
{12345678-0000-0001-C000-000000000095}
{87654321-0000-0001-C000-000000000095}
                    0 = REG_SZ 0, 4, FFFFFFFE, ABCD1234, -4, 4, , FEFEFEFE
                    1 = REG_SZ 0, 4, FFFFFFFE, ABCD1232, -4, 4, , FEFEFEFE
                    Source Filter = {56781234-0000-0001-C000-000000000095}

파일에 그러한 패턴이 포함되는 경우는, 미디어 타입 {12345678-0000-0001-C000-000000000095}{87654321-0000-0001-C000-000000000095} 가 이 파일에 관련지을 수 있다. 미디어 타입에 대한 파일 소스 필터는, 미디어 타입의 키에 있는 Source Filter 값의 CLSID 에 의해 식별된다.

미디어 타입을 사용해, 파일을 렌더링하기 위한 필터 핸들러를 찾아낼 수가 있다. 타입에 대응하는 핸들러는, 데이터를 렌더링 하기 전에 파일의 상세한 테스트를 실행해, 파일의 타입을 확인한다.

이 방식으로는, 대체 마스크세트 (. wav 파일)을 사용할 수 있다. 이것에는 RIFF 헤더가 있어도 없어도 좋다.

바이트 확장자(extension)없이의 파일 확장자(extension)의 등록

전에 말한 것처럼, 특정의 파일 확장자(extension)에 대해서 특정의 미디어 타입/서브 타입의 페어 또는 소스 필터 CLSID 를 등록할 수 있다. 이 경우, 미디어 타입의 독해에는 이 타입 및 소스 필터만이 사용된다. 다만, 독자적인 소스 필터를 등록했을 경우는, 이름이 소스 필터에게 건네져 해석되기 (위해)때문에, 실제의 파일명을 나타내는 이름에는 아무 제한도 없다.

레지스트리 엔트리는 다음과 같이 된다.

HKEY_CLASSES_ROOT\Media Type\Extensions

파일 확장자(extension)가 . foo 이면, 키의 내용은 다음과 같이 된다.

. foo
REG_SZ:Media Type
REG_SZ:Subtype
REG_SZ: Source Filter

각각의 값이 GUID 를 나타낸다.


DirectShow 에서의 디버그

이 주제는 Microsoft® DirectShow® 어플리케이션과 필터를 디버그 할 때의 힌트를 몇개인가 제공한다.

이 주제에는 다음의 섹션이 포함된다 :

  • Assert 체크
  • 오브젝트명
  • 디버그 로깅
  • 크리티컬 섹션
  • 포인터의 유효성 확인

참조 : GraphEdit 에 의한 그래프 구축의 시뮬레이션

Assert 체크

Assert 체크 라이브러리를 사용하는 것. Assert는 코드내의 필요 조건, 충분조건에 대해 생성 한 가정을 검증한다. DirectShow 는 몇개의 Assert 매크로를 제공한다. 상세한 것에 대하여는, 「Assert 매크로와 breakpoint 매크로」를 참조할것.

예를 들어, 핑크 라스에 핀이 접속되고 있으면(자) 가정한 프라이빗 메소드가 포함되어 있을지도 모르다. 이하와 같이, Assert를 사용해 이 가정을 테스트할 수 있다 :

ASSERT(IsConnected());  // 핀은 접속되어 있지 않으면 안 된다.

오브젝트명

디버그 빌드에서는,CBaseObject 클래스로부터 파생한 오브젝트의 글로벌 리스트가 있다. 오브젝트가 생성 되면(자), 그것은 리스트에 추가된다. 그 오브젝트가 삭제되면(자), 리스트로부터 소거된다. 오브젝트의 리스트를 표시하려면 ,DbgDumpObjectRegister 함수를 호출하는 것.

CBaseObject base class (와 거기로부터 파생된 대부분의 클래스)의 constructor　 　 메소드에는 오브젝트명에 대한 파라미터가 포함되어 있다. 그것을 식별하는 고유의 이름을 오브젝트에 붙이는 것. 이름의 선언에 NAME 매크로를 사용하면(자), 이름의 캐릭터 라인은 디버그 빌드시에게만 할당할 수 있다. 리테일 빌드에서는, 그 이름은 NULL 가 된다.

디버그 로깅

DbgLog 함수는 프로그램 실행시에 디버그 메세지를 표시한다. 이 함수를 사용해 어플리케이션이나 필터의 예외를 트레이스 하는 것. 반환값이나, 변수의 값, 그 이외의 임의의 관련 정보를 로그 할 수가 있습니다.

모든 디버그 메세지는 LOG_TRACE 나 LOG_ERROR 와 같은 메세지 타입, 메세지의 중요도를 나타내는 디버그 레벨을 가지고 있다. 낮은 디버그 레벨은 높은 레벨보다 중요해진다.

다음의 예에서는, 가짜의 필터가 핀 배열로부터 있는 핀을 접속 해제한다. 접속 해제가 성공하면(자), 필터는 LOG_TRACE 메세지를 표시한다. 그것이 실패 하면, LOG_MESSAGE 를 표시한다 :

hr = m_PinArray[iPin]->Disconnect();
if (FAILED(hr))
{
    DbgLog((LOG_ERROR, 1, TEXT("Could not disconnect pin %d.  HRESULT = %#x", iPin, hr));

   // 에러 핸들링 코드 (생략).
}
DbgLog((LOG_TRACE, 3, TEXT("Disconnected pin %d"), iPin));

디버그중에, 각 메세지 타입의 디버그 레벨을 설정할 수가 있다. 또 각 모듈 (DLL 혹은 실행 모듈)은 자기 자신의 디버그 레벨을 보관 유지한다. 필터를 테스트하고 있다면, 그 필터를 가지는 DLL 의 디버그 레벨을 올리는 것. 상세한 것에 대하여는, 「디버그 출력 함수」를 참조할것.

크리티컬 섹션

데드 블록을 보다 용이하게 트럭 하려면 , 호출 코드가 주어진 크리티컬 섹션 자신을 소유하고 있을지 어떨지를 확인하는 Assert를 인클루드 하는 것. CritCheckIn 와 CritCheckOut 함수는 호출해 원의 thread가 크리티컬 섹션을 소유하고 있을지 어떨지를 나타낸다. 보통, Assert 매크로 내부로부터 이러한 함수가 불려 간다. 상세한 것에 대하여는, 「크리티컬 섹션 디버그 함수」를 참조할것.

크리티컬 섹션이 취득, 해방되었을 때에,DbgLockTrace 함수를 사용해 트레이스 할 수도 있다.

포인터의 유효성 확인

포인터의 유효성을 고려하는 것. 예를 들어,ValidateReadPtr 매크로는 해 하 포인터가 읽어들여 가능한 메모리를 가리키고 있는지 어떤지를 체크한다. 현재, DirectShow 포인터 유효 매크로는 IsBadReadPtr 와 같은 Microsoft® Win32® 포인터 평가 함수를 사용한다. 어느 시스템에서는, 이러한 함수가 지정한 범위에서 페이지 마다 스왑을 일으키는 경우가 있는, 이것은 현저하게 퍼포먼스를 저하시킨다. 상세한 것에 대하여는, 「포인터 유효 매크로」를 참조할것.


프로그래밍의 힌트

여기에는, Microsoft® DirectShow® 어플리케이션을 효과적으로 개발하기 위한 정보가 포함되어 있다.

글로벌 오브젝트

글로벌 C++ 오브젝트는, constructor　 　 메소드로 DirectShow 오브젝트를 생성 하거나 소멸자 메소드로 오브젝트를 해방해서는 안 된다. 이와 같이 하면, 다음과 같은 이유로써 어플리케이션이 무한하게 블록 한다.

thread는, DLL 의 엔트리 포인트 함수내에 있는 동안은 종료할 수 없다. Kernel 32 는, 엔트리 포인트 함수내에서는 글로벌 프로세스를 보관 유지해, 락에 의해 thread를 종료할 수 없게 된다. DirectShow 오브젝트에는 독자적인 thread를 가지는 것이 있으므로, DLL 엔트리 포인트 함수로부터 해방 하면 블록 할 가능성이 있다. 어플리케이션에 글로벌 C++ 오브젝트가 있는 경우, C 런타임 DLL 는 DLL 가 언로드되었을 때에 오브젝트의 소멸자를 호출한다. 소멸자가 DirectShow 오브젝트를 해방 하면, 결과적으로 블록 할 가능성이 있다.

같은 이유로써, DLL 는 엔트리 포인트 루틴으로 DirectShow 오브젝트를 생성 또는 해방해서는 안 된다.

필터 프로퍼티

DirectShow 필터를 생성 할 때는, 어플리케이션의 쓰는 사람에 대해서, 몇개의 방법으로 프로퍼티에의 액세스를 줄 수가 있다. IProvidePropertyPages 인터페이스를 사용해 프로퍼티 페이지를 제공 하면, 어플리케이션이 이 인터페이스를 표시할 수 있다. 어플리케이션이 독자적인 UI 를 제공할 수 있도록(듯이) 하려면 ,IPropertyBag 인터페이스를 지원 해, 어플리케이션이 필터에 조회해 프로퍼티를 발견하도록 할 수 있다. 프로퍼티에 특별한 인터페이스를 제공하는 경우는, 필터 정보와 핀 정보의 독자적인 인터페이스를 생성 할 수도 있다.


디코더의 개발

여기에서는, Microsoft® DirectShow® 디코더 개발의 유저 모드에 관한 측면으로 도착해 설명한다.

  • DirectX 비디오 가속화
  • DVD 디코더의 개발


Microsoft DirectX VA : 비디오 가속화 API/DDI 사양 (Rev 1.0)

Microsoft DirectX 8.0

Microsoft DirectX VA : 비디오 가속화
API/DDI 사양 (Rev 1.0)

주 : 이 스펙(명세서)의 최신판은 Microsoft® Word® 포맷으로 http://www.microsoft.com/hwdev/DirectX_VA/ 로부터 다운로드 가능하다.

요약 : 이 문서에서는, DVD 서브 픽쳐 등에 대응하기 위한 알파 블렌딩의 지원을 포함해 디지털 비디오의 디코드 처리를 하드웨어로 가속화하기 위한 어플리케이션 프로그래밍 인터페이스 (API) 및 거기에 대응하는 디바이스 드라이버 인터페이스 (DDI)에 대해 설명한다. 특히 MPEG-2 의 "메인 프로파일" 비디오 (이전의 ITU-T MPEG-2 | ISO/IEC 13818-2)의 지원에 초점을 맞혀 인터페이스를 해설하지만, 다른 주요한 비디오 CODEC (ITU-T 권고 H. 263 및 H. 261, 및 MPEG-1 및 MPEG-4 등)도 지원 한다.

목차

  • 1 개요
    • 1.1 요약
    • 1.2 목적 및 관련하는 표준 규격
    • 1.3 필요 조건, 퍼포먼스 검증, 스케줄
      • 1.3. 1 비압축 픽쳐 포맷
      • 1.3. 2 가속기의 연속성 필요 조건
      • 1.3. 3 소프트웨어 디코더의 연속성 필요 조건
        • 1.3. 3.1 디코드에 4 개의 비압축 표면을 사용한다
        • 1.3. 3.2 디코드에 5 개 이상의 비압축 표면을 사용한다
    • 1.4 용어
      • 1.4. 1 약어와 기호
      • 1.4. 2 비트 번호부 규칙
      • 1.4. 3 정의
    • 1.5 스테이지
    • 1.6 frame buffer의 구성
  • 2 현재의 표준 규격의 처리
    • 2.1 ITU-T H. 261
    • 2.2 MPEG-1
    • 2.3 MPEG-2 (별명 MPEG-2)
    • 2.4 ITU-T H. 263
    • 2.5 MPEG-4
    • 2.6 예측의 원리
      • 2.6. 1 예측의 스테이지
      • 2.6. 2 매크로 블록 부분
      • 2.6. 3 예측 프레인
  • 3 DirectX VA 데이터 구조와 프로그램 구성
    • 3.1 암호화 지원
    • 3.2 글로벌 제한 모드의 정보
    • 3.3 구성을 프로브 및 잠근다
    • 3.4 버퍼 기술 리스트
    • 3.5 압축 픽쳐의 디코드 (bDXVA_Func=1)
      • 3.5. 1 접속 구성
      • 3.5. 2 최소한의 상호 동작성 구성 세트
      • 3.5. 3 보완적인 추천 구성 세트
      • 3.5. 4 압축 픽쳐의 파라미터
      • 3.5. 5 픽쳐의 매크로 블록의 버퍼 구조
        • 3.5. 5.1 매크로 블록 제어 커멘드
        • 3.5. 5.2 역양자화, IDCT 전포화, 미스매치 제어, 인트라 DC 오프셋(offset), IDCT, 픽쳐 재구축, 및 재구축 클리핑
          • 3.5. 5.2. 1 오프 호스트의 IDCT
            • 3.5. 5.2. 1.1 단일 계수의 데이터 포맷
            • 3.5. 5.2. 1.2 그룹화 된 4 계수의 데이터 포맷
          • 3.5. 5.2. 2 호스트 베이스의 IDCT
            • 3.5. 5.2. 2.1 16 비트 방식
            • 3.5. 5.2. 2.2 8-8 오버플로우 방식
        • 3.5. 5.3 블록 해제 필터 제어
        • 3.5. 5.4 읽어 반환 버퍼
      • 3.5. 6 오프 호스트의 VLD 비트 스트림 디코드 처리
        • 3.5. 6.1 역양자화 행렬 버퍼
        • 3.5. 6.2 슬라이스 제어 버퍼
        • 3.5. 6.3 비트 스트림 데이터 버퍼의 내용
    • 3.6 알파 브렌드 데이터의 로드 (bDXVA_Func=2)
      • 3.6. 1 접속 구성
      • 3.6. 2 최소한의 상호 동작성 구성 세트
      • 3.6. 3 AYUV 알파 블렌딩 표면의 로드
        • 3.6. 3.1 16 엔트리 AYUV 팔레트의 로드
        • 3.6. 3.2 AYUV 표면의 로드
      • 3.6. 4 IA44/AI44 알파 블렌딩 표면의 로드
      • 3.6. 5 DPXD 알파 블렌딩 표면의 로드
      • 3.6. 6 하이라이트 데이터의 로드
      • 3.6. 7 DCCMD 데이터의 로드
    • 3.7 알파 브렌드 콤비네이션 (bDXVA_Func=3)
      • 3.7. 1 접속 구성
      • 3.7. 2 최소한의 상호 동작성 구성 세트
      • 3.7. 3 알파 브렌드 콤비네이션 버퍼
        • 3.7. 3.1 예: MPEG-2 빵-스캔 조작
        • 3.7. 3.2 예: 16:9 픽쳐에서의 DVD 4:3 빵 스캔
        • 3.7. 3.3 예: DVD 704 와이드비빵 스캔 픽쳐 조작
        • 3.7. 3.4 예: DVD 352 와이드 픽쳐 조작
        • 3.7. 3.5 예: DVD 720 와이드 픽쳐 조작
    • 3.8 픽쳐재샘플링 제어 (bDXVA_Func=4)
      • 3.8. 1 접속 구성
      • 3.8. 2 최소한의 상호 동작성 구성 세트
      • 3.8. 3 픽쳐재샘플링 제어 버퍼
  • 4 제한 모드
    • 4.1 신규 제한 프로파일의 추가
    • 4.2 비제한 처리
    • 4.3 H261_A 제한 프로파일
    • 4.4 H261_B 제한 프로파일
    • 4.5 H263_A 제한 프로파일
    • 4.6 H263_B 제한 프로파일
    • 4.7 H263_C 제한 프로파일
    • 4.8 H263_D 제한 프로파일
    • 4.9 H263_E 제한 프로파일
    • 4.10 H263_F 제한 프로파일
    • 4.11 MPEG1_A 제한 프로파일
    • 4.12 MPEG2_A 제한 프로파일
    • 4.13 MPEG2_B 제한 프로파일
    • 4.14 MPEG2_C 제한 프로파일
    • 4.15 MPEG2_D 제한 프로파일
  • 5 IAMVideoAccelerator 처리
    • 5.1 IAMVideoAccelerator 인터페이스
    • 5.2 IAMVideoAccelerator 에의 DirectX VA 의 매핑
      • 5.2. 1 제한 모드 프로파일과 구성의 설정
      • 5.2. 2 DirectX VA IAMVideoAccelerator 처리 사양
      • 5.2. 3 motion compensation 디바이스 드라이버와의 처리 위에의 통신

개요

이 문서에서는, DVD 서브 픽쳐 등에 대응하기 위한 알파 블렌딩의 지원을 포함해 디지털 비디오의 디코드 처리를 가속화하기 위한 어플리케이션 프로그래밍 인터페이스 (API) 및 거기에 대응하는 디바이스 드라이버 인터페이스 (DDI)에 대해 설명한다. 특히 MPEG-2 의 "메인 프로파일" 비디오 (이전의 ITU-T MPEG-2 | ISO/IEC 13818-2)의 지원에 초점을 맞혀 인터페이스를 해설하지만, 다른 주요한 비디오 CODEC (ITU-T 권고 H. 263 및 H. 261, 및 MPEG-1 및 MPEG-4등)도 지원 한다. 여기서 해설하는 설계는 현시점에서는 디코드로 한정되고 있지만, 장래 인터페이스가 한층 더 확장되려면 , encode 기능도 정의될 예정이다. 이 인터페이스는, 각종 CODEC 의 설계 중(안)에서, 다량의 계산을 필요로 하는 가장 기초적인 부분을 뽑아내, 하드웨어내에서의 그러한 가속화를 지원 하도록(듯이) 설계되고 있다.

그래픽 하드웨어 드라이버는, 그래픽 하드웨어 이행의 가속화 기능에 대한 공통의 액세스 방식을 제공하기 위해(때문에), 이 인터페이스를 지원 하는 편이 좋다. 과거에, 그래픽 하드웨어 메이커 몇 회사로부터, 이것과 자주(잘) 닮은 기능이 자사 제품 전용의 것으로 해 정의되었던 적이 있었다. 그러나, 이 사양의 목적은, 소프트웨어 응용 프로그램과 고도의 그래픽 가속화 기능동안에, 벤더에 의존하지 않는 공통 인터페이스를 확립하는 것이다. 공통 인터페이스의 확립에 의해, 비디오를 지원 하는 컴퓨팅 시스템의 능력이 확대되어 이 기능을 제공하는 소프트웨어 어플리케이션의 수요가 증가해, 하이 퍼포먼스인 그래픽 기능에의 수요가 증가하는 것이 기대된다.

1.1 요약

이 사양으로 정의되고 있는 인터페이스는, ITU-T 의 H. 26x 시리즈 및 ISO/IEC JTC1 의 MPEG-x 시리즈를 포함해 현재의 주된 표준 motion compensation 비디오 CODEC 를 지원 할 수가 있다. 당초는, 현재 가장 상업적으로 우세한 비디오 CODEC 인 MPEG-2 (엄밀하게는 ITU-T 권고 MPEG-2 또는 ISO/IEC 13838-2)를 지원 하도록(듯이) 설계되었다.

이 문서로 정의하고 있는 구문은, 이 표준 규격을 매우 직접적으로 지원 하도록(듯이) 설계되고 있기 (위해)때문에, 표준 규격의 구문을 여기서 정의된 포맷으로 변환하려면 , 몇 안 되는 "번역" 밖에 필요없다. 다른 표준 규격을 최대한으로 일관한 방법으로 지원 하기 위해서 필요한 기능도 추가되었다. 또 암호화를 필요로 하는 어플리케이션을 위해서(때문에), 암호화도 지원 되고 있다. 이 인터페이스에서는, 각종의 표준 규격에 공통의 중심적인 기본 처리를 추출해, 또 규격 고유의 몇개의 처리를 호스트 CPU 로 한정하고 있다. 이것에 의해, 규격에 의존하지 않는 높은 유연성을 가지면서, 가속화 하드웨어에 대한 규격마다의 커스터마이즈도 최소한으로 끝나는 비디오 CODEC 하드웨어 가속화의 지원을 가능하게 하고 있다.

1.2 목적 및 관련하는 표준 규격

이 사양은, 1 개(살) 이상의 스테이지를 1 개 이상의 디바이스간에 분할할 수 있도록(듯이) 하는 비디오 디코더 가속화의 언어를 정의하고 있다. 현재 이 문서에서는, ITU-T H. 261, MPEG-1 (ISO/IEC 11172-2), MPEG-2 (ISO/IEC 13818-2 | ITU-T 권고 MPEG-2), ITU-T H. 263, 및 MPEG-4 (ISO/IEC 14496-2)의 일부의, motion compensation 예측 (MCP : motion-compensated prediction) 및 역이산 코사인 변환 (IDCT : inverse discrete-cosine transform) 스테이지를 실행하는 하드웨어 가속기와 호스트 CPU 와의 구분을 설명하고 있다. 종합적인 목적은, CPU 리소스를 낭비하는, 간단해, 게다가 빈번하게 실행되는 처리를, 전용의 목적을 위해서(때문에) 설계된 저비용인 가속기에 off-road 해, 비트 스트림 해석이나 가변장 디코드 (VLD : variable-length decoding)라고 한, 복잡해, 너무 빈번하게 실행되지 않는 처리를 호스트 CPU 에 남기는 것이다.

여기서 설명하고 있는 사양은, 단일의 비디오 스트림의 디코드 에 대해서만 유효하다. 복수의 비디오 스트림은, Microsoft® DirectX® VA API 에서는 명시적으로는 지원되어 있지 않다. 이 때문에, 복수의 비디오 스트림을 지원 하려면 , 비디오 스트림 마다 개별의 DirectX® VA 세션 처리가 필요하다 (예 : 필터 그래프 처리에서의 사용에, 비디오 디코더와 가속화 드라이버에 개별의 출력 핀 및 입력 핀세트).

1.3 필요 조건, 퍼포먼스 검증, 스케줄

이 시방서에 기재된 인터페이스를 사용하는 모든 가속기 드라이버에 대해, 이 시방서의 내용에 준거하고 있는 것을 확인할 필요가 있다. 확인 내용은 다음대로.

  • 이 API 를 사용하는 하드웨어가 실행하는 처리에 의해, 의도했던 대로의 계산 결과를 얻을 수 있는 것
  • 이 API 를 사용하는 소프트웨어 디코더에 의해 얻을 수 있는 퍼포먼스가, 같은 비행기노우를 실행하기 위해서 호스트-소프트웨어 이행이 아니고 이 API 를 사용해야 하는 것을 정당화 할 만하는 속도와 신뢰성을 나타내는 것

Microsoft 에서는, 이것들이 검증되어 있지 않은 이행은, 어디까지나 테스트 목적으로 사용해야 하고, 이 문서로 지정하고 있는 인터페이스를 공개하는 드라이버에 배치해서는 안된다고 생각한다.

중기적 장래에는, 디코더 및 그래픽 가속기의 이행의 인가에, 이 인터페이스의 지원, 및 지원을 위한 퍼포먼스 검증이 필요하다. 엄밀한 테스트 스위트 및 퍼포먼스 측정 방법은 아직 정의되어 있지 않다. 이 문서로 말하고 있는 중기적 장래의 필요 조건은, 하드웨어 비디오 디코드 가속화를 지원 하는 모든 그래픽 가속화 하드웨어, 및 그러한 그래픽 가속화 하드웨어 지원을 사용하는 모든 소프트웨어 디코더에 대해, 2001 년의 반에 있어서의 모든 Microsoft Windows® operating system (Windows 2000, Windows Millennium Edition, 및 Windows 2000 "Whistler")에 적용되는 조건으로서 정의될 예정이다. 이 문서로 말하고 있는 장기적 장래의 필요 조건은, 중기적인 필요 조건의 대략 1 년 후에 적용되는 조건으로서 정의되고 있다. 이 기대되는 요건의 데드라인 일자는 진행 상황에 의해 조정 될 수 있다.

암호화, 구성, 및 제한 모드 지원의 필요 조건에 대해서는, 암호화 지원, 구성, 및 제한 모드에 관한 이후의 각 섹션으로 해설한다. 픽셀 포맷 지원의 필요 조건에 대해서는, 여기서 해설한다.

1.3. 1 비압축 픽쳐 포맷

DirectX VA 로 생성 된 디코드가 끝난비압축 픽쳐를 어플리케이션으로 사용하려면 , 그러한 픽쳐가 인식 가능한 포맷으로 생성 되고 있을 필요가 있다. DirectX VA 가속기가 지원 하는 비압축 픽셀 포맷의 리스트에는, 다음의 픽셀 포맷 리스트의 멤버가 1 개 이상 포함되지 않으면 안 된다 ( 「YUV 포맷」을 참조).

  1. 압축 4:2:2 비디오의 디코드 :
    1. "YUY2" 에서는, 데이터를 부호 없음 char 형의 배열로서 취급할 수가 있다. 최초의 바이트에는 Y 의 최초의 샘플이 저장 되어 2 번째의 바이트에는 Cb 의 최초의 샘플, 3 번째의 바이트에는 Y 의 2 번째의 샘플, 4 번째의 바이트에는 Cr 의 최초의 샘플, 과 같이 계속된다 (예를 들어 2 개의 little endian WORD 형 변수의 배열로서 주소 되었을 경우는, 최초의 WORD 에는 LSB 에 Y0 및 MSB 에 Cb 가 저장 되어 2 번째의 WORD 에는 LSB 에 Y1 및 MSB 에 Cr 가 저장 된다). 이것은, 추천 되는 DirectX VA 4:2:2 픽셀 포맷이며,4:2:2 비디오를 지원 하는 DirectX VA 가속기의 중기적 필요 조건이 될 예정이다.
    2. "UYVY" 는,"YUY2" 와 같지만, 각 워드의 바이트 순서가 거꾸로 된다 (예를 들어 2 개의 little endian WORD 형 변수의 배열로서 주소 되었을 경우는, 최초의 WORD 에는 LSB 에 Cb 및 MSB 에 Y0 가 저장 되어 2 번째의 WORD 에는 LSB 에 Cr 및 MSB 에 Y1 가 저장 된다).
  2. 압축 4:2:0 비디오의 디코드 :
    1. "YUY2" 는, 상기와 같지만, 실제의 4:2:0 Cb 및 Cr 샘플의 각 라인에 대해서, 2 라인의 출력 Cb 및 Cr 샘플이 생성 된다. 각 조의 2 번째의 라인은, 1 번째의 복제인가, 또는 1 번째 및 3 번째의 평균치이다. 사용중의 모든 포맷화등 이 포맷에 "프론트엔드" 변환하는 능력은, 중기적 필요 조건이 될 예정이다.
    2. "UYVY" 는, 상기와 같지만, 실제의 4:2:0 Cb 및 Cr 샘플의 각 라인에 대해서, 2 라인의 출력 Cb 및 Cr 샘플이 생성 된다. 각 조의 2 번째의 라인은, 1 번째의 복제인가, 또는 1 번째 및 3 번째의 평균치이다.
    3. "YV12" 에서는, 모든 Y 샘플이, 부호 없음 char 형 배열로서 메모리의 최초로 존재해 (메모리의 alignment를 위해서(때문에), 보다 큰 보폭이 되어 있을 가능성 있어), 그 직후에 모든 Cr 샘플이 (Y 라인의 반의 보폭, 한편 반의 라인수로) 계속되어, 그 직후에 모든 Cr 샘플이와 같이 계속된다.
    4. "IYUV" 는, YV12 와 같지만, Cb 및 Cr 프레인의 순서가 거꾸로 된다.
    5. "NV12" (참조처 Web 페이지에 기재 없음)에서는, 모든 Y 샘플이, 부호 없음 char 형의 짝수 라인의 배열로서 메모리의 최초로 존재해 (메모리의 alignment를 위해서(때문에), 보다 큰 보폭이 되어 있을 가능성 있어), 그 직후에, Y 샘플과 같은 합계 보폭으로, 인터리브 된 Cb 및 Cr 샘플을 포함한 부호 없음 char 형의 배열이 계속된다 (예를 들어 1 개의 little endian WORD 형으로서 주소 되었을 경우는, Cb 는 LSB 에, Cr 는 MSB 에 들어간다). 이것은 추천 되는 4:2:0 픽셀 포맷이며,4:2:0 비디오를 지원 하는 DirectX VA 가속기의 중기적 필요 조건이 될 예정이다.
    6. "NV21" (참조처 Web 페이지에 기재되지 않은 신어)는, NV12 와 같지만, Cb 및 Cr 샘플이 거꾸로 되고 있어 부호 없음 char 형의 크로마 배열로 각 샘플이 Cr, Cb 의 순서에 줄선다 (예를 들어 1 개의 little endian WORD 형으로서 주소 되었을 경우는, Cr 는 LSB 에, Cb 는 MSB 에 들어간다).
    7. "IMC1" (참조처 Web 페이지에 기재되지 않은 신어)는, YV12 와 같지만, Cb 및 Cr 프레인의 보폭이 Y 프레인에서의 보폭과 같다. 또 Cb 및 Cr 프레인은, 16 라인의 배수인 메모리 경계내에 들어가도록(듯이) 제한되고 있다 (표준에서는 모두 16×16 매크로 블록을 사용하기 위해(때문에), 표준 포맷에서는 이 제한은 의미를 가지지 않는다).
    8. "IMC2" (참조처 Web 페이지에 기재되지 않은 신어)는, IMC1 와 같지만, Cb 및 Cr 라인이 하프 보폭의 경계에서 인터리브 된다. 즉, 색광도 영역의 각 풀 보폭의 라인은, Cb 의 라인으로 시작되어, 다음의 하프 보폭 경계로부터 시작되는 Cr 의 라인이 계속된다. (이 경우, 색광도의 address 공간이 반이 되는 것으로, 합계 address 공간이 25% 삭감되기 (위해)때문에, IMC1 보다 address 공간을 효과적으로 이용할 수 있는 포맷이라고 말할 수 있다. ) 이것은 NV12 보다 비교적 우수하지만, NV12 가 보다 일반적이다라고 된다.
    9. "IMC3" (참조처 Web 페이지에 기재되지 않은 신어)는 Cb 와 Cr 의 스왑 이외는 IMC1 와 같다.
    10. "IMC4" (참조처 Web 페이지에 기재되지 않은 신어)는 Cb 와 Cr 의 스왑 이외는 IMC2 와 같다.

이러한 포맷을 정의하는 제 1 의 목적은, 사용되는 포맷을 문서화해, 압축 해제된 비디오를 그 후의 처리에 사용할 수 있도록(듯이) 하는 것이다 (이 처리에서는, 비디오를 DirectDraw 표면 텍스쳐로서 조작한다). 제 2 의 목적은, 포맷의 종류가 증가하는 것을 막아, 소프트웨어 처리를 단순화 하는 (다종류의 포맷을 사용하는 것에 의해 같은 기능이 중복 하는 것을 피한다) 것이다.

1.3. 2 가속기의 연속성 필요 조건

인터페이스의 조작중에 레이스 컨디션이 예기치 못한 사건을 일으키지 않게하기 위한 기본적인 부담은 하드웨어 가속기는 아니고, 호스트 소프트웨어 디코더상에 있다. 이것에 관해서 가속기에 지게한 요구는, 비압축 표면의 표시가 정지하고 있을까 실행중인지가 거론되었을 때에 올바르게 리포트할 수 있는 일이라고 요구된 조작이 완료했는지 어떠했는지가 거론되었을 때에 올바르게 리포트하는 것이다.

1.3. 3 소프트웨어 디코더의 연속성 필요 조건

여기에서는, 디코드 처리에 대해 연속 처리가 확실히 올바르게 실행되도록, 특정의 필요 조건이 부과되어 있다. 이러한 조건은, 디코드 및 표시때의, 비압축 표면의 취급해에 관한 것이다. 여기서 드는 예는, 블록 해제 필터를 사용하지 않는, 일반적인 I, B, 및 P 구조화 비디오 프레임의 픽쳐 디코드의 취급해에 대한 예이다. 다른 상황에서도, 대개 같은 원칙이 적용된다.

원칙은, 다음과 같이 단순한 것인 : 참조나 표시에 필요한 것에 오버라이드(override) 하지 않는 것, 레이스 컨디션을 피하는 것. 이것은, 다음의 2 살의 룰 로 분해할 수 있다.

  • 디스플레이에 서브 미트 된 픽쳐는, 이미 화면에 표시되고 화면으로부터 지워질 때까지는, 오버라이드(override) 할 수 없는 (화면에 예기치 못한 표시가 나오는 것을 피한다), 그리고
  • 아직 생성되어 있지 않은 픽쳐 생성의 참조로서 필요한 픽쳐에는, 오버라이드(override) 할 수 없다

이것은 다음의 것의 요건이 되는, 소프트웨어 디코더는 가속기 상태를 문의 레이스 컨디션을 피하지 않으면 안 되는, 그리고 디코더는 충분한 수의 비압축 표면을 사용해 그 스페이스가 모든 필요한 조작으로 이용 가능하지 않으면 안 된다.

이 결과, I, B, P 픽쳐의 처리에는 4 개 이상의 비압축 픽쳐 표면이 필요하다. (보다 많은 수가 보통은 기대되고 있어 프론트엔드 알파 블렌딩에 사용하는 것 같은 몇개의 조작에서는, 보다 많은 수가 필요하다. )

이하의 2 개의 서브 섹션에서는, B 픽쳐의 비디오 디코드에 있어서의 4 개(살) 이상의 비압축 표면의 사용에 대해 기술해, 보통은 4 개 이상의 비압축 표면이 필요하고, 지연을 최소한으로 억제할 필요가 없는 어플리케이션에서는 5 개 이상이 추천 되는 것을 결론 붙인다. 추가 표면을 사용하는 것으로, 해결해야 하는 조작에 의한 대기 상태를 현저하게 경감시킬 수가 있다.

압축 버퍼는 압축 표면과 같게, 할당할 수 있었던 버퍼와 같은 것 혹은 그 같은 서브 세트를 재이용하는 것보다, 일반적으로는 모든 유효한 모든 버퍼를 반복해 사용하는 것이 좋은 것에 주의. 그것은 불필요한 의존성을 기다리기 위해서(때문에) 추가된 지연을 요구하는 보틀 넥이 일어날 가능성이 있기 때문이다. 몇개의 경우, 드라이버에 의한 복수 버퍼의 할당은 더블 버퍼나 트리플 버퍼의 반복 사용이 예기치 못한 표시없이 조작하는 올바른 방법인 것을 나타낸다. (이것은 특히 알파 블렌딩 데이터 읽어들여에 적용한다. )

1.3. 3.1 디코드에 4 개의 비압축 표면을 사용한다

그림 1 에, 특정의 상황을 가정한 비디오 디코더를 나타낸다. 이 디코더는, 각 픽쳐의 디코드에 1 프레임 타임 필요로 해, 또 P 픽쳐의 조의 사이에 (최초의 I 픽쳐의 뒤에 있는 0 개의 B 픽쳐로부터 시작되어) 계속 증가하는 B 픽쳐를 포함한 비트 스트림을 디코드하고 있다. 이 예에서는, I, B, P 의 문자가 각 픽쳐의 타입을, 첨자가 각 픽쳐의 일시적인 표시 순서를, 슈퍼 스크립트가 픽쳐를 보관 유지하는 버퍼를, 각각 가리키고 있다. 각 B 픽쳐를 디코드하려면 , 비트 스트림 순서로 선행하는 2 개의 픽쳐가 필요하다. 그 결과, 디코더는, 2 번째의 픽쳐가 디코드될 때까지 (디코드의 3 번째의 타임 슬라이스에 들어갈 때까지), 올바른 타이밍에 픽쳐를 표시하기 시작할 수가 없다. 이 3 번째의 타임 슬라이스의 어디선가, 올바른 타이밍에서의 픽쳐 표시를 시작 할 수 있다.

픽쳐 표시의 시작은, 보통, 픽쳐가 화면에 나타나는 것과 동시에는 실행되지 않는다. 그 대신해, 새로운 픽쳐에의 변환에 적절했을 때가 올 때까지, 표시하도록(듯이) 명령된 픽쳐에 선행하는 다른 픽쳐가 표시계속 된다. 이 때문에, 퍼포먼스를 최적화하려면 , 표면 0 (최초의 I 픽쳐를 보관 유지한다)은 비록 I 픽쳐가 필요없어도, 3 프레임 타임 후에 오는 B 픽쳐에 의해 오버라이드(override) 되어서는 안된다. 그렇지 않고, 4 번째의 표면 (표면 3)은 이상적이게는 B 픽쳐를 보관 유지하기 위해서 이용되어야 한다. 이것에 의해 B 픽쳐를 디코드하기 전에, 최초의 I 픽쳐의 표시 피리어드가 완료해 버렸는지 어떠했는지를 체크할 필요가 없어진다.

위에서 주어진 2 살의 룰의 응용은 최초의 3 개의 디코드된 픽쳐가 다른 표면에 놓여지지 않으면 안 된다고 하는 것이다, 왜냐하면 그 모두가 3 번째의 피리어드 (피리어드 2)의 사이에는 표시되어 버리지 않기 때문에이다. 다음에 4번째의 디코드된 픽쳐는 이상적이게는 4번째의 표면에 놓여져야 하는 것이다, 왜냐하면 최초로 표시된 픽쳐는 4번째의 피리어드 (피리어드 3)의 사이에는 종료하고 있지 않을지도 모르기 때문에이다.

그림 1 으로 일어날 수 있는 처리중의 큰 보틀 넥은, 1 행에 2 개 이상의 B 픽쳐를 가지는 결과적으로, 10번째의 디코드된 픽쳐 (B19) 에서 일어난다. 연속 순서의 3 번째 혹은 그 다음의 B 픽쳐가 왔을 때, 1 개의 B 픽쳐의 표시와 다음의 디코드된 B 픽쳐를 보관 유지하는 표면 사용동안의 타임 러그 허용값은 배제된다. 이 상태에서는, 호스트 디코더는 전의 피리어드로 표시된 B 픽쳐의 디스플레이 상태 (이 경우는, B17)를 체크해 디스플레이로부터 삭제된 것을 확인하지 않으면 안 되는 (필요하면 이것을 기다린다), 다음에 곧바로 같은 표면을 사용해 다음의 B 픽쳐 (이 경우는, B19 에 사용되고 있는 표면 1)를 디코드해야 한다. 참조 I 픽쳐 혹은 P 픽쳐(이 경우는, 표면 0 으로 2, 이것들은 P06 으로 P210 에 사용되고 있다)를 보관 유지하기 위해서 사용되고 있는 어느 쪽의 표면에서도 새로운 B 픽쳐를 디코드할 수 없는, 그리고 같은 인터벌 타임주에 표시되고 있는 표면 (이 경우, B38 에 사용되고 있는 표면 3 )으로 새로운 B 픽쳐를 디코드는 할 수 없다. 따라서 직전의 피리어드로 표시된 표면을 사용하지 않으면 안 된다 (이 경우는, 표면 1).

디코드 처리 | I00 | P11 | P23 | B32 | P06 | B14 | B35 | P210 | B17 | B38 | B19 | P015
표시 처리 |  |  | I00 | P11 | B32 | P23 | B14 | B35 | P06 | B17 | B38 | B19
디코드된 프레임* | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11
디코드 처리 | B311 | B112 | B313 | B114 | P221 | B316 | B117 | B318 | B119 | B320 | P028 | ...
표시 처리 | P210 | B311 | B112 | B313 | B114 | P221 | B316 | B117 | B318 | B119 | B320 | ...
디코드된 프레임* | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | ...
* 인터벌의 시작점.

그림 1 -- 4 프레임 디코더 버퍼링 (우상의 숫자는 버퍼 넘버, 우하의 숫자는 디스플레이 인덱스)

1.3. 3.2 디코드에 5 개 이상의 비압축 표면을 사용한다

버퍼를 5 개 이상 사용할 수 있기 (위해)때문에, 버퍼의 표시 시작과 동버퍼에의 새로운 기입의 시간차이를, 최저 1 표시 주기부터 2 이상으로 넓힐 수가 있다. 이것에 의해, 디코드 처리의 타이밍에 의해 큰 지터를 허가할 수가 있다. 또, 디코드가 끝난 픽쳐의 출력 처리로, 표시 처리의 일환으로서 3 필드의 비인터레이스 처리를 실행할 수 있다 (현재의 픽쳐 뿐만이 아니라 전의 픽쳐도 표시에 이용 가능해서, 전의 픽쳐를 사용해, 문맥을 제공하거나 실제의 표시 처리로 1 필드의 지연을 허락하거나 할 수가 있기 (위해)때문에). 그것은 또 잘못해 설계된 하드웨어 드라이버에 대해서 몇개의 면책을 제공하는, 그것은 픽쳐가 실제로 아직 표시되고 있을까 하지 않는 것인지를 올바르게 인식하지 않고 쓰여져 있는 드라이버이다 (그러한 상태를 제시하지 않는 하드웨어 드라이버에 정확하게는 의존해서는 안되지만). B 픽쳐에 DirectX VA 를 효율적으로 사용하려면 , 버퍼가 적어도 4 개 있으면 충분하다고 생각된다. 다만, 지연의 억제가 요건으로 여겨지지 않는 경우에는, 5 개(살) 이상의 버퍼의 사용을 추천 한다. I, B, P 구조화 된 비디오 디코딩용의 DirectX VA 디코더는 그러므로, 비압축 표면을 할당할 때, 그 최소와 최대의 요구 가능한 비압축 표면 할당수를 적어도 각각 4 로 5 로 설정해야 한다. 1 개(살) 이상의 추가비압축 표면을 사용하는 것은 스무스해, 신뢰성 높고, 티아후리의 조작을 얻는 좋은 방법인 것이 많다.

1.4 용어

1.4. 1 약어와 기호

' ' 2 진값 (왼쪽의 비트가 MSB)

" " 10 진값

0x 16 진값

LSB 최하정도 비트 (Least Significant Bit)

MSB 최상정도 비트 (Most Significant Bit)

// 0 으로 역방향으로 마는 단락

/ 0 방향으로 잘라 버리는 단락

1.4. 2 비트 번호부 규칙

이 시방서로는, 비트 번호를 Microsoft 로 보급되어 있는 규칙에 따라 표현한다. 이 규칙에서는, LSB 가 비트 0 , MSB 가 비트 N-1 가 된다 (비트수가 N 의 경우).

주 : 비디오 코딩 규격에는, 가장 젊은 번호의 비트가 MSB 로 여겨지는 것이 있어, 그 경우는 이 번호부 규칙과는 다르다.

다만, 이 문서로 구조 체내에 8 비트 미만의 필드의 순서가 나타나는 경우, 그 순서는 비디오 코딩 규격으로 사용되고 있는 규칙에 따른다. 즉, 최초로 리스트 되는 요소가 MSB 에 가장 가까운 위치에 있는 것이라고 보여진다. 예를 들어, 단일 비트의 배열 요소 5 개(살)을 구조 기술내에 늘어놓는 경우에는, 구조 기술내에 인덱스가 감소하는 순서로 각 요소가 리스트 된다.

이 어프로치로 보여지는 분열적 현상은, 이 인터페이스 사양의 각 비트가 어디에 위치하는지를 결정하는 최종적인 권한이, 이 문서가 아니고, 이 인터페이스에 관련지을 수 있다 ". h" 파일에 있는 것이라고 보는 편이 좋은 일을 의미한다.

1.4. 3 정의

참조 블록 - 참조 frame buffer로부터 추출된 블록 영역.

예측 블록 - 참조 블록으로부터 필터 된 블록.

예측 프레인 - 매크로 블록 예측을 결합하기 전에 형성되는 샘플의 배열. 각 프레인은, 보통 1 개의 프레임 로케이션으로부터 모아진, 일련의 예측 블록을 나타낸다. 프레인이 결합되어, 단일의 매크로 블록 예측을 형성한다.

예측 매크로 블록 - 모든 색채널을 포함한 매크로 블록 예측.

성분 - 3 개의 색채널 {Y, Cb, Cr } 의 1 개.

호스트 CPU - 비디오 디코드의 기능 전체 (상위 처리)를 제어하는, 프로그램 가능한 프로세서.

가속기 - IDCT, MCP, 표시 포맷 변환이라고 한, 단순하지만 빈번하게 실행되는 처리를 실행하는 기능 단위.

움직임 벡터 계산 - 움직임 벡터를 예측 블록 주소로 변환하는 처리.

예측 주소 - 이행 고유의 설계 중(안)에서, 예측 블록이 있는 위치.

합성 예측 블록 - 속성이 휘도와 색광도의 양쪽 모두에 적용되는 예측 블록.

성분 예측 블록 - 속성이 휘도나 색광도의 어딘가에 적용되는 예측 블록.

인트라 (프레임내) - 디코드 끝난 픽쳐를 참조한 예측을 실시하지 않는 픽쳐 컨텐츠의 표현.

인터 (프레임간) - 우선 디코드 끝난 픽쳐를 사용해 픽쳐의 1 영역의 예측을 encode 해, 그 후 필요에 따라서 예측으로부터의 편차를 나타내는 신호를 추가하는 픽쳐 컨텐츠의 표현.

잔차디코드 - 필요에 따라서, motion compensation 예측 후에 남아 있는 신호를 표현하기 위해(때문에), encode 된 오차 신호를 나타내는 파형을 디코드하는 것. 이 결과, 비예측 파형의 "인트라" 표현만이 사용되는 경우라고 예측 후의 "인터" 차이가 사용되는 경우가 있다.

ReservedBits - 이 사양으로 이름 또는 이름의 일부에 ReservedBits 가 포함되어 있는 필드는, 현재 이 사양에서는 사용되어 있지 않기 때문에, 값은 0 이 아니면 안된다.

~편이 좋은 - 추천 되는 (필수가 아니다) 동작의 기술에 사용되는 표현.

~안 되는 - 필수 (또는 금지된) 동작의 기술에 사용되는 표현.

1.5 스테이지

다음의 그림에 나타내는 스테이지는, MCP 및 IDCT 가속기로 구성되어 있다.

그림 2 -- 디코더의 스테이지

1.6 frame buffer의 구성

모든 픽쳐 버퍼는, MPEG-2 사양 대로, 프레임으로 구성된 버퍼를 보관 유지하고 있다고 보여진다. 주소 단위는, 특히 지정이 없는 한 프레임 좌표로 설정해야 한다. 프레임 좌표로 기술된 예측 블록을, 이행 고유의 변환 계층을 사용해, 손실없이 필드 좌표로 변환할 수가 있다. 예를 들어, 단일 프레임의 움직임 예측은, 상하 2 개(살)의 개별의 매크로 블록 부분 예측에 분할할 수 있다.

3 개의 비디오 성분 채널 {Y, Cb, Cr} 는, 이 사양으로 정의된 인터페이스에 의해 액세스 된다. 2 개의 색광도 성분의 움직임 벡터는, 휘도 성분에 보내진 벡터로부터 파생한다. 이러한 움직임 벡터는, 가속기에 의해 다른 좌표 시스템에 변환된다.

현재의 표준 규격의 처리

그림 3 -- 호스트 및 가속기의 시스템

이하에, H. 261, MPEG-1, MPEG-2 (MPEG-2), H. 263, 및 MPEG-4 의 기본 처리를 연대순에 리스트 해, 이 사양을 사용해 어떻게 실현될 수 있을까를 간단하게 설명한다.

2.1 ITU-T H. 261

정식으로는 "Video CODEC for Audiovisual Services at px64 kbit/s" 로 불리는 ITU-T 권고 H. 261 은, 비교적 높은 압축율을 가지는 실용적인 설계로서는 최초의 디지털 비디오 코딩 표준 규격이었다 (최초의 디지털 비디오 코딩 표준 규격인 H. 120 은 이미 잊을 수 있고 있다). 또, Y, Cb, Cr 성분을 사용한 8 비트 샘플,4:2:0 샘플링, 16×16 "매크로 블록" 베이스의 motion compensation, 8×8 IDCT, 계수의 지그재그역스캔, 스칼라 양자화, 값 0 의 RLE (run-lengths) 및 양자화 인덱스값의 편성에 근거하는 계수의 가변장 코딩이라고 한, 다른 비디오 CODEC 표준으로 후에 사용되는 것과 같은 기본 설계가 사용되고 있었다. 모든 H. 261 예측 블록은, 선행하는 픽쳐로부터 순서 방향만의 예측을 사용한다. H. 261 은 하프 샘플 정밀도의 예측 필터를 가지지 않지만, 그 대신에 "루프 필터" 로 불리는 저패스 필터의 일종을 사용한다 (H. 261 사양의 섹션 3.2. 3). 이 필터는, 각 매크로 블록의 motion compensation 예측중에 온/오프 할 수 있다.

보유 D 그래픽 : H. 261 은 후에,"보유 D 그래픽 전송" 으로 불리는 흥미로운 트릭 모드를 거두어 들였다. 이 가속기 인터페이스에서는, 이 기능에 대한 특별한 지원은 제공되어 있지 않다. 이 사양을 사용해 이 기능을 지원 하려면 , 디코드된 4 개의 픽쳐를 가속기로부터 호스트에게 읽어 되돌려, 거기서 인터리브 해, 고해상도의 그래픽 픽쳐로서 표시할 수가 있다.

2.2 MPEG-1

정식으로는 ISO/IEC 11172-2 로 불리는 MPEG-1 비디오는, H. 261 으로부터 이윽고 해, H. 261 의 설계의 대부분을 거두어 들여 설계되었다. 루프 필터는 없고, 그 대신에, 프레임간의 서브 픽셀의 움직임을 해결하기 위한 심플 하프 샘플 필터를 가진다. 추가된 쌍방향 예측 모드 및 역방향 예측 모드에서는, 참조 프레임이 1 개 여분으로 버퍼 될 필요가 있다. 쌍방향 예측은, 순서 방향으로 예측된 예측 블록과 역방향으로 예측된 예측 블록의 평균을 취한다. 순서 방향과 역방향의 예측 블록을 평균화하는 계산은, 하프 샘플 된 "보간" 예측 블록의 생성을 닮아 있다. 그 외의 기본 구조는 H. 261 과 같다.

2.3 MPEG-2 (별명 MPEG-2)

정식으로는 "Information Technology - Generic Coding of Moving Pictures and Associated Audio Information : Video" ITU-T 권고 MPEG-2 | ISO/IEC 13818-2 로 불리는 MPEG-2 는, 매우 하위의 층으로부터 보면, 기존의 MPEG-1 의 툴에, 기본적인 16×8 형상을 추가했을 뿐의 사양이다. 조금 상위의 층으로부터 보면, MPEG-2 에는, 인터레이스 비디오의 특성을 취급하기 위해서(때문에), 복수의 필드로부터 참조한 예측을 조합하는 많은 방법이 추가되고 있다.

MPEG-2 프레임 구조화 픽쳐 :

  1. 프레임 MC : MPEG-1 예측과 매우 자주(잘) 닮은 16×16 의 예측 블록 형상을 가진다. 이것은, MPEG-2 에서는 유일, 프로그래시브 포맷의 움직임이다 (MPEG-2 의 motion_type 파라미터로 지정된다). MPEG-2 의 macroblock_type 파라미터의 설정에 의해, 1 개의 예측 프레인 (순서 방향만, 또는 역방향만)을 가지는지, 또는 2 개의 예측 프레인 (쌍방향)을 가진다. 참조 블록은, frame buffer로부터의 연속 프레임 라인으로 형성된다. frame buffer는, 디코드 처리의 시멘틱스에 의해 선택된다. 하프 샘플 보간 (MPEG-2 섹션 7.6. 4) 및 쌍방향 보간 (MPEG-2 섹션 7.6. 7.1)의 평균화 처리는, MPEG-1 와 완전히 같다.
  2. 필드 (16×8) MC : 순서 방향 및 역방향의 각 프레인은, 상 16×8 예측 블록, 및 하 16×8 예측 블록으로 구성된다. 각 예측 블록에 대응하는 참조 블록은, 참조 프레임 상 필드 또는 하 필드로부터 추출할 수 있다 (MPEG-2 의 motion_vertical_field_select[r][s] 파라미터에 의해 결정된다). 1 개의 예측 프레인에 대해서 2 개의 예측 블록이 1 세트 있다 (순서 방향만 또는 역방향만. 이 경우는 1 개의 매크로 블록에 합계 2 개의 예측 블록이 존재한다) 경우와 2 개의 예측 프레인에 대해서 복수세트가 있다 (쌍방향. 이 경우는, 1 개의 매크로 블록에 합계 4 개의 예측 블록이 존재한다) 경우가 있다.
  3. 듀얼 프라임 : 앞에서 본 필드 MC 와 같이, 각 프레인 (패리티)은, 상하의 16×8 형상으로 구성된다. 동패리티 프레인과 역패리티 프레인은, 1, 2, 4, 5 의 쌍방향 보간과 같은 평균화 처리에 의해 결합된다. 다른 움직여 타입 (1, 2, 4, 5)과 달리, 듀얼 프라임의 매크로 블록은, 항상 2 세트의 예측 블록 ( 동패리티 및 역패리티)으로 구성되어 1 개의 매크로 블록에 합계 4 개의 예측 블록이 존재한다.

MPEG-2 필드 구조화 픽쳐 :

  4. 필드 (16×16) MC : 각 예측이 16×16 형상을 가지는 점으로써 프레임 MC 를 닮아 있지만, 참조 블록 데이터는, 연속적인 위 또는 아래의 라인만으로부터 형성된다. 프로그래시브 포맷의 움직임과 같이 상하의 라인이 교대로 혼재할 것은 없다. 필드 구조화 픽쳐의 모든 움직임 타입과 같이, 재구축 된 매크로 블록도, 연속적인 위 또는 아래의 라인만 상태로, 현재의 frame buffer에 저장 된다. 상 필드 또는 하 필드의 행선지는, MPEG-2 의 picture_structure 변수에 의해 결정된다.
  5. 16×8 MC : 이 타입의 움직임의 기본적인 예측 블록 형상은, 다른 16×8 형상 (2, 3)과 동일하지만, 같은 방법으로 매크로 블록에 파티션 분할될 것은 없다. 2 개의 파티션은, 매크로 블록내의 상하의 필드가 아니고, 매크로 블록 예측 프레인의 상반분과 하반신에 대응한다 (그림을 참조). 하반신의 16×8 의 엥커 포인트는 16×8 하부 분의 좌상이며, 다른 모든 움직임 타입과 같이 매크로 블록 전체의 좌상은 아니라고 하는 점에는, 특별히 주의하는 편이 좋다.
  6. 듀얼 프라임 : 최하층에 있어서는, 듀얼 프라임과 쌍방향 예측의 필드 구조화 필드 motion compensation의 사이에 실질적인 구별은 없다. 차이는, 참조 블록의 형성원이 되는 frame buffer의 선택에 나타난다. 필드 구조화 픽쳐의 듀얼 프라임 움직임 타입은 항상, 2 개의 16×16 예측 블록 ( 동패리티 예측 및 역패리티 예측)으로 구성된다.

2.4 ITU-T H. 263

정식으로는 "Video Coding for Low Bit Rate Communication" 로 불리는 ITU-T 권고 H. 263 은, H. 261, MPEG-1, MPEG-2 와 비교해 압축 퍼포먼스가 향상한, 비교적 새로운 비디오 코다이다. H. 263 의 가장 기본적인 포맷만을 지원 하는,"baseline" 모드 처리를 포함한다. 또, 각종의 목적으로 사용할 수 있는 다수의 옵션 확장 모드 처리도 포함한다. (1995 년 후반에 승인된 초기 버젼에서는, 옵션 모드는 5 개였지만, 1997 년에 기술적으로 완성한 2 번째의 버젼에서는 몇개의 모드가 추가되어 2000 년에는 한층 더 몇개인가가 추가된다. ) 이 인터페이스에서는, baseline H. 263 예측은 MPEG-1 기능의 서브 세트를 사용해 동작한다. baseline 모드에는 순서 방향 예측만이 포함된다. 쌍방향 예측은 포함되지 않았다.

둥근 제어 : H. 263 옵션 모드안에는, 둥근 제어를 필요로 하는 것이 있다. 이 사양에서는, 둥근 제어는 bRcontrol 플래그에 의해 지원 된다.

H. 263 보유 D 로 정의되고 있도록(듯이), H. 263 옵션 모드안에는, 픽쳐의 경계의 밖에 주소 하는 움직임 벡터를 허가하는 것이 있다. 이 사양에서는, 이 기능은, 가속기가 그러한 움직임을 지원 할 필요가 있을지 어떨지 지정하는 bPicExtrapolation 플래그에 의해 지원 된다. 그러한 움직임을 지원 하려면 , 2 개의 기본적인 방법이 있는 : 1) 각 샘플 페치의 주소의 값을 클리핑 해, 픽쳐의 경계내에 들어가도록(듯이) 한다. 2) 복제한 샘플을 픽쳐에 패딩 해, 픽쳐의 각 경계에 건너가는 매크로 블록의 폭과 높이에 의해 사용되고 있는 실제의 메모리 영역을 넓힌다. 결과는 어느쪽이나 같기 때문에, 가속기는 어느 쪽의 방법에서도 사용할 수 있다.

쌍방향 움직임 예측 : 몇개의 옵션 H. 263 예측 처리로 사용되고 있는 쌍방향 움직임 예측에서는, MPEG-1 과는 달리, 둥근 연산자로서 둥근이 아니게 잘라서 버림의 단락이 사용된다. 이 사양에서는, 이 기능은, bBidirectionalAveragingMode 플래그에 의해 지원 된다.

4 MV motion compensation (4MV) : H. 263 의 각 매크로 블록의 사이즈는 16×16 이지만, 보유 F 및 J 라고 한 몇개의 H. 263 의 옵션 모드에서는, 단일의 매크로 블록에 4 개의 움직임 벡터가 송신되는 것을 허가한다 (매크로 블록내의 각 8×8 휘도 블록에 1 매크로 블록). 대응하는 8×8 색광도 영역은, 파생한 단일의 움직임 벡터를 사용한다.

중복 블록 motion compensation (OBMC : Overlapped Block Motion Compensation) : H. 263 의 보유 F 는, 4MV 지원 외에, 휘도 샘플의 OBMC 도 포함하고 있다. 이 사양에서는, OBMC 예측은, 12 의 움직임 벡터를 매크로 블록의 순서 방향 예측에 송신하는 것을 허가하는 것에 의해 지원 되고 있다.

OBMC 예측 블록은, 이 사양으로 주어진 툴에 의해, 3 살의 프레인에 구성된 예측의 편성으로서 하드웨어내에서 실현된다. 3 살의 프레인이란, 현재의 프레인 ("0"), 상/하 프레인 ("1"), 및 좌/우프레인 ("2")이다. 3 살의 프레인은, H. 263 섹션 F. 3 으로 정의된 q(x, y), r(x, y), 및 s(x, y) 블록의 일시 기억역으로서 사용된다. 3 살의 프레인의 4 블록 모든 것이 묻을 수 있으면(자), H. 263 섹션 F. 3 의 식에 따라 결합되어 H. 263 의 그림 F. 2, F. 3, F. 4 로 나타난 개개의 H 행렬에 의해 중량감을 붙일 수 있다.

예를 들어, OBMC 휘도 매크로 블록 예측은, 8×4 형상상/하 예측 블록 8 개(살), 4x8 형상의 좌/우블록 8 개(살), 및 8×8 형상의 현재의 블록 4 개(살)로 구성된다. 4 살의 프레인 0 움직임 벡터가 같은 움직여 벡터를 가지고 있는 경우 (4MV 매크로 블록이 아닌 경우)는, 단일의 16×16 매크로 블록 예측을 사용해 16×16 프레인 0 전체를 묻을 수가 있다.

이 사양에서의 OBMC 처리의 표현에 관해서는, 10 개의 움직임 벡터가 매크로 블록에 보내진다. 최초의 4 개는 현재의 매크로 블록의 Y0, Y1, Y2, Y3 블록용이다. 다음에 매크로 블록의 위쪽의 왼쪽 반 및 오른쪽 반의 리모트 벡터가 보내진다. 그 후 매크로 블록의 좌측의 상반분 및 하반신의 리모트 벡터, 마지막에 매크로 블록의 우측의 상반분과 하반신의 리모트 벡터, 라고 계속된다. (H. 263 에서는, 매크로 블록 아래 쪽의 왼쪽 반과 오른쪽 반에 별개의 리모트 벡터가 사용되지 않고, 현재의 매크로 블록의 벡터가 재이용된다. )

그림 4 -- OBMC 예측 프레인내의 1 개의 8×8 블록의 H. 263 등록

P-B 프레임 (보유 G & M) : 이 모드에서는, P 프레임 및 의사 B 프레임의 매크로 블록은, 정리해 일의의 "PB 프레임" 픽쳐 코딩 타입에 다중화 된다. 각 매크로 블록의 B 프레임 부분은, 매크로 블록의 P 프레임 부분용으로 encode 된 정보를 거두어 들인다. B 부분의 순서 방향 및 역방향 움직임 벡터는, P 부분의 벡터로부터 스케일 되어 재구축 된 P 부분의 매크로 블록은, B 부분의 역방향 참조로서 사용된다. 역방향 매크로 블록은 같은 PB 매크로 블록에 포함되는 재구축 된 P 매크로 블록 밖에 참조할 수 없기 때문에, PB 에는 의사 B 프레임만이 포함된다. 다만 종래의 B 프레임 시멘틱스와 같이, PB 프레임내의 B 매크로 블록은, 순서 방향 참조 프레임내의 어느 장소에서도 참조할 수 있다.

역방향 참조에 관한 이 제한에 의해, H. 263 도 G. 2 에 나타나고 있는 것 같은, 작은 사이즈의 역방향 예측 블록 형상이 생성 된다. 이 사양에서는, PB 프레임을, 2 개의 움직임 벡터를 가지는 개별의 매크로 블록 타입으로서 라베링 하는 것에 의해 지원 하고 있다.

블록 해제 필터 (보유 J) : 이 사양에는, 블록 해제 필터를 가속화하기 위한 특별한 커멘드가 정의되고 있다. 이 커멘드는, 보유 J 와 같게 루프내에서 사용하는지, 또는 H. 261 픽쳐나 H. 263 baseline 픽쳐의 경우와 같이 루프외에서 사용한다. 호스트 CPU 는, GOB 또는 슬라이스 세그먼트(segment)를 감시하는 블록 해제 커멘드를, 필요에 따라서 생성 해야 한다.

참조 픽쳐 선택 (보유 N 및 U) : 각 예측 블록의 픽쳐 인덱스 선택 필드를 사용하는 가속기에 의해, 복수의 참조 프레임이 지원 된다.

스케이라비리티 (보유 O) : 이 사양의 툴에서는, 일시 스케이라비리티, SNR 스케이라비리티, 및 공간 스케이라비리티가 지원 된다. 이 사양의 H. 263 공간 스케이라비리티 B 프레임은, MPEG-1 의 B 프레임에 매우 비슷하다. 공간 스케이라비리티에서는, 하위층의 참조 픽쳐를 업 샘플 한 데다가, 업 샘플 된 픽쳐를 참조로서 사용할 필요가 있다 (다른 모든 측면에서는, SNR 스케이라비리티 및 일시 스케이라비리티와 기본적으로 동일하다). H. 263 의 잘라서 버림에는, 적절한 쌍방향 평균화 둥근 제어를 설정하는 편이 좋다 (MPEG-1 및 MPEG-2 는 윗쪽 바이어스 평균화를 사용해, H. 263 은 하부 잘라서 버림 평균화를 사용한다).

참조 픽쳐의 재샘플링 (보유 P) : 이 보유의 단순한 포맷이, 참조 버퍼의 재샘플링에 의해 지원 되고 있다. 보다 풍부한 포맷의 보유 P 재샘플링에 대해서는, 참조 프레임으로서 사용되는 재구축 된 프레임이, 외적 방법에 따라 재샘플링 되어 가속기로부터 주소 가능한 참조 frame buffer로서 저장 될 필요가 있다.

해상도 저감 갱신 (Reduced-Resolution Update) 모드 (보유 Q) : H. 263 의 해상도 저감 갱신 모드에서는, 블록 해제 필터의 별포맷 및 고도 예측 OBMC (Advanced Prediction OBMC)의 별포맷이다, 그다지 일반적이지 않은 잔여 업 샘플링 조건이 요구되기 (위해)때문에, 이 사양에서는 현재 지원되어 있지 않다. 다만, 블록 해제 필터 (Deblocking Filter) 모드가 액티브해, 고도 예측 (Advanced Prediction) 모드가 액티브하지 않은 상태에서의 처리는, 호스트 베이스의 IDCT 처리에 의해, 이 인터페이스에서도 지원 할 수 있을 가능성이 있다.

독립 세그먼트(segment) 디코드 (보유 R) : 독립 세그먼트(segment) 경계의 하위 및 가속기 대응은 존재하지 않는다. 보유 R 의 몇개의 포맷은, 특별한 처리없이 지원 가능하다 (baseline와 보유 R 의 편성 등). 픽쳐 세그먼트(segment)의 외부 삽입을 필요로 하는 보유 R 의 포맷은, 각 세그먼트(segment)를 픽쳐로서 디코드해, 그 후 그러한 작은 픽쳐로부터 완전한 출력 픽쳐를 구축하는 것에 의해 지원 가능하다.

그 외의 H. 263 옵션 기능 : 그 외의 H. 263 옵션 기능은, 가속기의 인터페이스에 영향을 주는 일 없이 지원 가능하다. 예를 들어, 보유 I, K, S, 및 T 는, 호스트측의 처리를 변경하는 것으로, 가속기에 영향을 주지 않고 간단하게 처리할 수 있다.

특정의 IDCT : 이 인터페이스에서는, 새로운 H. 263 옵션 기능으로서 가까운 장래 추가된다고 생각되는, 특정의 IDCT 의 지원 사양이 고려되고 있다.

2.5 MPEG-4

MPEG-4 는, 프로그래시브 스캔 코딩에 대해서는 H. 263 의 규격, 인터레이스 및 4:2:0 이외의 칼라 샘플링 포맷의 지원에 대해서는 MPEG-2 의 규격을 큰폭으로 거두어 들이고 있다. 이 사양에 있는, H. 263 및 MPEG-2 를 지원 하는 기능은, MPEG-4 를 지원 하기 위해서 사용할 수 있다. 1 픽셀에 대해서 8 비트 이상을 지원 하기 위해서, BPP 파라미터가 준비되어 있다. 세이프 코딩, 오브젝트 회전, 페이스 모델링, 메쉬 오브젝트, 스프라이트라고 하는 MPEG-4 에 고유의 기능은, 현재의 인터페이스에서는 지원 되지 않는다. 다만, 장래 개발되는 바리에이션으로 추가될 가능성이 있다.

2.6 예측의 원리

블록 motion compensation 예측 (MCP)은, MPEG 및 H. 26x 패밀리의 CODEC 에, JPEG 와 같이 순수한 정지 프레임 코딩 방법에는 없는 이점을 제공하는 기본 툴이다. 일반적인 예측의 예는, CODEC 의 다양한 스테이지에 있지만, MCP 는 가장 많은 처리를 필요로 한다. 움직임 벡터, DCT 계수, 그 외 MCP 처리의 직접적인 일부에서 없는 요소도, 전송 후 상태를 보다 컴팩트하게 하기 위해서 예측을 이용한다. 이러한 예측의 예는, 이 사양에서는 해설하지 않는다. 또 이것들은, 호스트 CPU 프로세서 또는 비트 스트림 퍼서/가변장 디코드 장치로 실행되는 것이라고 본다.

일반적인 예측 코딩 스킴에서는, 먼저 전송 및 디코드된 요소가, 현재의 요소의 예측으로서 사용되어 예측값과 현재의 요소의 실제값과의 차이가 예측 오차로서 보내진다. 전송 된 차이 정보에 의해, 올바른 값, 또는 필요하게 되는 값에 충분히 가까운 값 (MCP 의 경우)에, 예측이 갱신된다. 먼저 디코드된 프레임은, 장래의 프레임이 어떻게 보이는 편이 좋은가를 예측 ("추측")하기 위해서 사용된다. 그 후 차이 데이터 (예측 오차)가 추측을 수정해, 예측과 예측 오차를 조합한 (재구축 된) 이미지를, 압축전의 오리지날의 장래의 프레임으로 할 수 있을 뿐(만큼) 가까이 하려고 한다.

재구축이 끝난 현재의 요소는, 저장 되어 장래의 요소의 예측에 사용된다. 이 반복의 루프는, 예측되는 요소 고유의 각종의 리셋에 의해 부수어지는 경우가 있다. 리셋은, 디코드 처리의 시멘틱스에 의해 기술된다. 예를 들어, 움직임 벡터나 DC 계수 예측은 슬라이스로 리셋 되어 일시 프레임 예측 체인 전체는, 인트라 리프레쉬 프레임에 의해 리셋 된다. 일시 기본 예측 루프는 이 기술에 적합하지만, 예측으로서 사용되는 프레임 전체로부터 꺼내진 수정 데이터와 함께 동작한다. 예측으로서 사용되는 참조 프레임으로부터의 데이터는, 움직임이나, 그 외 시간과 함께 발생하는 변경 내용에 맞추어 수정된다.

그림 5 -- 일반적인 MCP 신호의 흐름

2.6. 1 예측의 스테이지

이 시방서의 목적상, MCP 에 의한 매크로 블록 예측의 구조는, 각각 독립한 일련의 국면으로서 설명해야 한다. 이 점을 인식하고 있으면(자), 이 시방서에서의 MCP 처리에 관한 기술의 포맷이 이해하기 쉬워진다.

그림 6 -- MoComp3 예측 블록의 신호의 흐름

스테이지 1. 참조 프레임의 형성

주 : 필요에 따라서 입력 픽쳐의 재샘플링이 포함되는 경우가 있다.

그림 7 -- MCP 에서의 예측 데이터의 진화

스테이지 2. 참조 블록

참조 블록은, 예측 블록과 같다라고는 한정하지 않고, 예측 필터 링 스테이지에서 필요한 추가 샘플로 구성되는 경우가 많다. 참조 블록은, 이행 고유의 픽쳐 버퍼 보관 유지 방법을 반영한 성질을 가지는 것이 많기 때문에, 이 시방서로는 정의하고 있지 않다. 메모리 단위내에서 하프 샘플 필터 링이 실행되지 않는 이상 16×16 하프 샘플 필터 된 매크로 블록의 참조 블록은, 17x17 의 형상을 가진다. 참조 블록의 사이즈는, 예측 블록의 크기의 함수이기도 해, 예측 블록의 필터 속성이기도 하다. 이 시방서로는, 참조 블록은, motion compensation 예측 (MCP)으로 사용하기 위해서, 참조 frame buffer로부터 추출된 데이터의 블록을 참조해야 한다.

스테이지 3. 예측 블록

필터 된 참조 블록의 결과.

스테이지 4. 결합된 매크로 블록 예측

1 개(살) 또는 복수의 예측 블록의 평균화 처리의 결과.

2.6. 2 매크로 블록 부분

매크로 블록은, 다양한 성질을 가지는 영역을 구분하기 위해서, 보통의 세그먼트(segment)에 분할된다.

그림 8 -- 기본적인 매크로 블록 분할 스킴

MPEG-2 에서는, 매크로 블록의 상부분과 하부분이, 시간적으로 떨어진 (최대 1/50 초) 인스턴스로부터 캡춰 된 2 개(살)이 다른 필드로부터의 라인을 나타낸다. 이 때문에, 매크로 블록의 담당 부분인 프레임 영역의 2 개의 필드간에 큰 움직임이 있었을 경우는, 상부분과 하부분에, 상호 관련성이 전혀 없는 내용이 들어가는 경우가 있다. 예측의 수직 방향의 세분도를 세세하게하기 위해(때문에), 필드 구조화 픽쳐에 16×8 스킴이 추가된다.

그림 9 -- MPEG-2 매크로 블록의 2 개의 16×8 부분

매크로 블록의 파티션 분할에 의해도 예측의 세분도가 세세해져, 움직임의 속도가 다른 경우에서도, 엣지나 작은 오브젝트가 보다 적절히 표현된다. 예측 블록 자체는, 미완성인, 근사 된 형상이며, 예측 블록이 표현하는 매크로 블록의 부분에 속하는 모든 샘플에 대한, 어떤 종류의 평균적 움직임 벡터를 표현하고 있다. 샘플 또는 서브 샘플이 각자의 움직임 벡터를 가지는 것이 이상적이지만, 그렇다면 매우 대량의 비트를 소비해, 처리의 오버헤드도 증가한다. 예측 블록은 적절할 수록 번의 근사 상태를 유지한다.

예측 블록은, 매크로 블록의 1 개의 부분에만 대해 일한다. 예측 블록 전체는, 매크로 블록의 16×16 영역을 담당한다. 이것은, 모든 H. 261 및 MPEG-1 예측으로 공통이다. MPEG-2 에서는, 매크로 블록의 듀얼 필드/프레임이라고 하는 성질에 대응하기 위해(때문에), 16×8 예측 형상이 채용되었다. MPEG-2 필드 구조화 픽쳐로 사용해 예측의 세분도를 세세하게 하기 위해서, 16×8 형상도 받아들여졌다. 8×8 형상은 H. 263 (고도 예측), H. 264, 및 MPEG-4 로 사용되고 있다. 현재 가장 세분도가 세세한 것은, 장래의 "H. 26L" 4×4 예측 블록 형상의 드래프트이다.

보통색광도 예측 블록은, 대응하는 휘도 예측 블록에 비해, 수평 방향에도 수직 방향에도 반의 사이즈이며, 휘도에 사용된 것과 같은 벡터를 공유한다. 이것은, 이 시방서로 취급하고 있는 표준 규격에서는, 움직임을 항상 성분 평면에 공존하는 것으로 하고 있기 때문에 있다. 이 때문에, 각각의 휘도 및 색광도 샘플의 디멘션의 차이를 조정하기 위해(때문에), 색광도 벡터는, 어떠한 수단에 의해 휘도 벡터로부터 스케일 된다. MPEG-2 의 16×8 휘도 예측 블록에는, 대응하는 8×4 색광도 형상이 있다. 휘도 예측 블록이 작아너무 작아 지면(자) , 예외가 많이 발생한다. 예를 들어, H. 263 의 고도 예측 모드에서는, 색광도 예측 블록의 형상은 8×8 인 채로, 색광도 움직임 벡터는, 4 개의 8×8 휘도 움직임 벡터의 평균으로부터 파생한다. 이 문서가 많은 부분에서는, 예측 블록, 프레인, 및 매크로 블록의, 휘도의 범위에만 대해 말한다. 특히 명기하지 않는 한, 색광도에 대해서는 유추 하는 것.

2.6. 3 예측 프레인

그림 10 -- MPEG-2 매크로 블록 예측 프레인

위에의도는, 최종적인 매크로 블록 예측을 형성하기 전에 존재하는, 개념적인 매크로 블록 예측 프레인을 나타내고 있다. MPEG-2 에는, 순서 방향 및 역방향 (쌍방향 예측), 또는 동패리티 및 역패리티 (듀얼 프라임)의 2 살의 프레인이 있다. MPEG-1 및 MPEG-2 에서는, 단순한 평균화 처리에 의해 프레인이 결합된다. H. 263 의 중복 블록 motion compensation 예측 (Overlapped Block Motion Compensation Prediction)이라고 한, 보다 세련된 예측 스킴의 경우는, 3 살의 프레인이 있다. 장래는, 최대 8 또는 그 이상의 예측 프레인을, 보다 세련된 필터를 사용해 결합하는 코딩 방법이 채용될 가능성이 있다.

DirectX VA 데이터 구조와 프로그램 구성

3.1 암호화 지원

어플리케이션의 시큐러티 요구에 따라서는, 비디오의 디코드에 사용되는 데이터의 일부의 암호화가 필요하게 되는 경우가 있다. 그러한 어플리케이션을 지원 하기 위한(해), 이 사양에서는, Direct VA 데이터의 암호화가, 그 처리에 정의된 다음의 3 개의 데이터 구조체에 적용할 수 있게 되어 있다.

  • 매크로 블록 제어 커멘드 데이터 구조체
  • 잔차블록 데이터 구조체
  • 비트 스트림 버퍼의 내용

다만 암호화는, DirectX VA 처리의, 중기적 장래를 향한 옵션이다. 모든 가속기는, 암호화를 사용하지 않고 처리를 실행할 수 없으면 안 된다. 몇개의 암호화 프로토콜은, 장기적 장래에는 필요 조건이 될 예정이다.

내용을 보호하기 위해서는, clear text 데이터 처리를 위한 호스트 베이스의 소프트웨어와 데이터를 이해하기 어렵게 하는 것, 및 암호화 처리를 실행하는 것이 중요하다. 이러한 보호는, 가속기측의 암호 해독 처리에 대해서도와 같이 중요하다 (암호 해독이 하드웨어 베이스의 처리인 경우도 마찬가지).

호스트 디코더 소프트웨어가 암호화를 이용하려면 , 가속기가 어느 타입의 암호화를 지원 하고 있을까를 판단할 필요가 있다. 가속기가 지원 하고 있는 암호화의 타입에 관한 기본 정보는, 비디오 가속기 타입 GUID 로서 호스트에게 공급되는 암호화 타입 GUID 의 리스트에 포함되어 있다. ("암호 없음" 의 GUID 인 DXVA_NoEncrypt 는, 그 지원이 암묵인 필수 조건이 되어 있기 (위해)때문에, 이 리스트로 송신해서는 안 된다. )

호스트가, 적용하는 암호화 프로토콜의 타입을 선택해, 섹션 3.2 로 기술한 것처럼, GUID 를 통해서 그 선택사항을 가속기에 지시한다. 전형적인 암호화의 처리에서는, 암호화 데이터를 올바르고 전송 하기 위해서, 전송전에 한층 더 다음의 2 개의 순서를 실행할 필요가 있다.

  • 호스트 디코더로부터, 가속기가 데이터 수신이 승인되고 있는 것을 검증하도록(듯이) 요구되는 경우가 있다. 이것을 실행하려면 , 인증된 공개 키와 비밀 키의 조를 가속기가 보관 유지하고 있는 것을 증명하는 서명 첨부 데이터 구조체를, 가속기로부터 호스트에게 송신시킨다.
  • 호스트 디코더는 그 후, 암호화 "내용 키" 를 가속기에 송신한다.

암호화 프로토콜을 초기화하는데 필요한 순서의 정확한 수는, 사용되는 암호화의 타입에 따라서 다르다. 암호화 처리의 초기화를 위해서(때문에) 호스트와 가속기의 사이에 교환되는 각 데이터 세트에는, 데이터의 암호화 타입을 구별하기 위해(때문에), 암호화 프로토콜 타입 GUID 가 접두사로서 붙지 않으면 안 된다 (있는 타입의 암호화를 있는 타입의 DirectX VA 버퍼에 사용해, 다른 타입의 암호화를 다른 타입의 DirectX VA 버퍼에 사용하는 경우 등).

암호화 데이터 세트는, 다음에 의해 지정되는, 실행되고 있는 처리가 암호화 프로토콜이다고 하는 지시와 교환된다.

DXVA_EncryptProtocolFunc {
            EncryptProtocolFlag,     // 24b
            bDXVA_Func              //  8b
            }

EncryptProtocolFlag : 실행되고 있는 처리가 암호화 프로토콜 트랜잭션(transaction)인 것을, 24 비트로 가리킨다. EncryptProtocolFlag 는, 호스트 소프트웨어 디코더에 의해 송신될 때는 0xFFFF00 로 동일하고, 가속기에 의해 송신될 때는 0xFFFF08 가 아니면 안된다.

bDXVA_Func : 암호화 프로토콜을 적용하는 DirectX VA 의 bDXVA_Func 기능을 나타낸다. 현재 이 문서로 정의되고 있도록(듯이), 암호화 지원을 요구하는 bDXVA_Func 의 값은 1 뿐이다.

호스트와 가속기의 사이에 교환되는 실제의 데이터 세트에는, 다음의 헤더 정보가 포함되지 않으면 안 된다.

DXVA_EncryptProtocolHeader {
                dwFunction,              // 지시받은 처리
                dwReservedBits[3],       // 3 * 32b alignment
                guidEncryptProtocol     // 128b
                }

dwFunction : 내용이 암호화 프로토콜에 관한 것임을 나타내는 DXVA_EncryptProtocolFunction 가 포함된다.

guidEncryptProtocol : 암호화 프로토콜에 관련지을 수 있었던 GUID 가 포함된다.

3.2 글로벌 제한 모드의 정보

디코더가 이 API 를 사용해 동작하기 위해서는, 디코더와 비디오 가속기의 사이로, 처리에 있어서의 다음의 2 개의 측면으로 도착해 공통의 인식이 성립되고 있을 필요가 있다 :

  1. 디코드되는 비디오 데이터 포맷의 타입. 이것은, DXVA_ConnectMode 데이터 구조체를 사용해 여기에 성문화 된다.
  2. API 의 처리가 어떻게 구성될까. 즉, 어느 중간 데이터 포맷이 사용되어 처리의 어느 측면이 호스트, 어느 측면이 가속기에 속할까. 이것은, 사용되는 DXVA 기능 각각의 접속 구성의 네고시에이션에 의해 확립된다.

DirectX VA 의 글로벌 접속 파라미터는, 다음의 접속 제한 모드이다.

DXVA_ConnectMode {
            guidMode,        // 128b
            wRestrictedMode // 16b
            }

guidMode : 사용되는 제한 모드 프로파일에 관련지을 수 있었던 GUID.

wRestrictedMode : 접속 제한 모드를 나타내는 수치에 의한 식별자 (섹션 4 를 참조).

3.3 구성을 프로브 및 잠근다

구성을 필요로 하는 개개의 DirectX VA 기능 (bDXVA_Func 의 특정값)의 구성을 확립하는 처리는, 다음과 같이 실행된다.

  1. 필요에 따라서, 구성을 가속기에 받아들일 수 있을지 어떨지를 판단하기 위해서(때문에) 프로브 한다.
  2. 구성이 지원 되고 있으면, 그 구성에 잠근다.

특정 구성 지원의 프로브는, 구성을 프로브 하는 특정 bDXVA_Func 에 대응하는 프로브 커멘드를, 가속기에 송신하는 것에 의해 실행된다. 프로브 커멘드와 함께, 프로브로 지원의 유무를 판단하는 구성을 기술하는 (DXVA_Func 의 값에 고유의) 구성 데이터 구조체가 송신된다. 가속기는, 지정된 구성을 지원 하고 있을지 어떨지를 나타내는 S_OK 또는 S_FALSE 를 돌려준다. 게다가 대체로서 제안되는 구성도 돌려주는 경우가 있다.

특정 구성에의 락은, 그 구성에 잠그는 특정 bDXVA_Func 에 대응하는 락 커멘드를, 가속기에 송신하는 것으로써 실행된다. 락 커멘드와 함께, 지원 되고 있는 경우에 잠그는 구성을 기술하는 (bDXVA_Func 의 값에 고유의) 구성 데이터 구조체가 송신된다. 가속기는, 지정된 구성을 가속기가 지원 하고 있을지 어떨지를 나타내는 S_OK 또는 S_FALSE 를 돌려준다. S_OK 의 경우는, 사용에 대비해 지정된 구성에 락 된다. S_FALSE 의 경우는, 대체로서 제안되는 구성이 돌려주어진다.

디코더는, 지정된 구성을 조사하는 프로브 커멘드를 사전에 송신하지 않고 , 락 커멘드를 송신할 가능성이 있다. 가속기는, 특정의 구성을 조사하는 프로브 커멘드에 S_OK 를 돌려주었을 경우는, 같은 구성에의 락 커멘드에도, 특히 명기되어 있지 않은 한 S_OK 를 돌려주지 않으면 안 된다.

락 커멘드를 송신해, 허가를 나타내는 결과가 돌려주어져 사용이 인정되면(자), 지정한 구성에 락 된다. 이것 이후, 같은 값의 bDXVA_Func 에 대응하는 프로브 커멘드 또는 락 커멘드가, 디코더로부터 송신되어서는 안 된다.

모든 DirectX VA 소프트웨어 디코더가, 모든 DirectX VA 가속기와 함께 동작할 수 있도록(듯이), 특정의 bDXVA_Func 를 사용하는 모든 소프트웨어 디코더가 지원 해야 하는 모든 구성세트로서 최소한의 상호 동작성 구성 세트가 정의된다. bDXVA_Func 의 지원을 나타내는 모든 가속기는, 관련지을 수 있었던 비디오 가속기의 GUID 를 공개하는 것으로써, 최소한의 상호 동작성 구성 세트의 쳐 적어도 1 개의 멤버를 지원 해야 한다. 경우에 따라서는, 보완적인 추천 구성 세트도 정의될 가능성이 있다.

프로브 및 락은, 프로브 커멘드 또는 락 커멘드로 송신되는 데이터 구조체의 최초의 멤버로서 건네받는 DXVA_ConfigQueryOrReplyFunc 에 의해 제어된다.

DXVA_ConfigQueryOrReplyFunc {
                QueryOrReplyFlag,        // 24b
                bDXVA_Func              //  8b
                }

QueryOrReplyFlag : 지정하는 조회 또는 응답의 타입. 이하와 같이 정의된다.

  • 0xFFFFF1 : 소프트웨어 디코더가, 프로브 커멘드로서 송신한다.
  • 0xFFFFF5 : 소프트웨어 디코더가, 락 커멘드로서 송신한다.
  • 0xFFFFF8 : 가속기가, 프로브 커멘드 대해 S_OK 응답과 프로브 된 구성의 카피를 돌려주는 경우에, 모두 송신한다.
  • 0xFFFFF9 : 가속기가, 프로브 커멘드에 대해서 S_OK 응답을 돌려주지만, 대체 구성도 제안하는 경우에, 모두 송신한다.
  • 0xFFFFFC : 가속기가, 락 커멘드에 대해서 S_OK 응답과 락 된 구성의 카피를 돌려주는 경우에, 모두 송신한다.
  • 0xFFFFFB : 가속기가, 프로브 커멘드에 대해서 S_FALSE 응답과 제안하는 대체 구성을 돌려주는 경우에, 모두 송신한다.
  • 0xFFFFFF : 가속기가, 락 커멘드에 대해서 S_FALSE 응답과 제안하는 대체 구성을 돌려주는 경우에, 모두 송신한다.
QueryOrReplyFlag 의 하위 4 비트는, 이하와 같이 해석할 수 있다.

  • 비트 3 : 호스트 디코더로부터 송신된 = "0", 가속기로부터 송신된 = "1".
  • 비트 2 : 프로브에 관련지을 수 있고 있는 = "0", 락에 관련지을 수 있고 있는 = "1".
  • 비트 1 : 성공 = "0", 실패 = "1".
  • 비트 0 : 복제된 구성 구조체 = "0", 새로운 구조체 = "1".

bDXVA_Func : 동시에 송신된 구성이 적용되는 bDXVA_Func 기능.

3.4 버퍼 기술 리스트

DirectX VA 는 주로, 데이터의 버퍼를 호스트로부터 가속기에 건네주는 것에 의해 동작한다. DXVA 기능의 파라미터 (bDXVA_Func)에 의해, 건네받을 가능성이 있는 버퍼의 타입, 및 실행되는 DXVA 태스크가 결정된다. 다음과 같은 각종 버퍼 타입이 여기에 정의되고 있다.

  1. 픽쳐 디코드 파라미터 버퍼
  2. 매크로 블록 제어 커멘드 버퍼 (잔차블록 데이터 버퍼와 깊게 관련해, 그것과 1:1 로 대응한다)
  3. 잔차블록 데이터 버퍼
  4. 블록 해제 필터 제어 커멘드 버퍼 (필터 효력의 제한 있어, 또는 제한 없음)
  5. 역양자화 행렬 버퍼 (오프 호스트의 VLD 처리에서만 사용)
  6. 슬라이스 제어 버퍼 (비트 스트림 데이터 버퍼와 깊게 관련하고 있다)
  7. 비트 스트림 데이터 버퍼
  8. AYUV 알파 블렌딩 샘플 버퍼
  9. IA44/AI44 알파 블렌딩 표면 버퍼
  10. DPXD 알파 블렌딩 표면 버퍼
  11. 하이라이트 데이터 버퍼
  12. DCCMD 데이터 버퍼
  13. 알파 브렌드 콤비네이션 버퍼
  14. 픽쳐재샘플링 제어 버퍼
  15. 최종 결과의 픽쳐의 매크로 블록을 호스트에게 읽어 되돌리는 커멘드를 저장 한 읽기 반환 버퍼

버퍼의 1 세트가 호스트로부터 가속기에게 건네질 때, 그러한 버퍼에 관한 추가 데이터도 건네받는다. 이 추가 데이터를, 버퍼 기술 리스트라고 부른다. 버퍼 기술 리스트는, 순서 첨부 리스트로 구성되어 있다. 이 리스트는, 먼저 열거한 최초의 타입의 최초의 버퍼로 시작되어, 다음은 동타입의 다음의 버퍼와 계속되어, 그 후 다음의 타입의 최초의 버퍼, 와 같이 옮겨 간다. 리스트의 각 멤버는, 다음과 같이 정의된 데이터 구조체로 구성되어 있다.

DXVA_BufferDescription {
             dwTypeIndex,       // 32b
             dwBufferIndex,     // 32b
             dwDataOffset,      // 32b
             dwDataSize,        // 32b
             dwFirstMBaddress,  // 32b
             dwNumMBsInBuffer,  // 32b
             dwWidth,           // 32b
             dwHeight,          // 32b
             dwStride,          // 32b
             dwReservedBits     // 32b
            }

dwTypeIndex : 이 섹션으로 전술한 리스트에 있는, 해당하는 버퍼의 타입 번호.

dwBufferIndex : 같은 버퍼 기술 리스트내에서 건네받는 같은 타입의 버퍼내에서의 버퍼의 순서 번호.

dwDataOffset : 버퍼의 선두로부터의 해당 데이터의 오프셋(offset) (바이트 단위). 0 이 아니면 안된다.

dwDataSize : 버퍼내의 해당 데이터의 양 (바이트 단위). 즉, 버퍼 내용의 마지막 바이트의 위치는, dwDataOffset + dwDataSize - 1 으로 주어진다.

dwFirstMBaddress : 라스터 스캔 순서로 나타낸, 버퍼내의 최초의 매크로 블록의 매크로 블록 주소 (0 은 좌상 매크로 블록의 주소, PicWidthInMBminus1 는 우상 매크로 블록의 주소, PicHeightInMBminus1 * PicWidthInMB 는 좌하 매크로 블록의 주소, PicHeightInMBminus1 * PicWidthInMB + PicWidthInMBminus1 는 우하 매크로 블록의 주소가 된다). 데이터 버퍼가, 픽쳐 디코드 파라미터, 역양자화 행렬, 슬라이스 컨트롤, 비트 스트림 데이터, AYUV, IA44/AI44, DPXD, 하이라이트, DCCMD 의 몇개의 타입인 경우는, 0 이 아니면 안된다. 만약 그 데이터 버퍼가 잔차블록 버퍼라면, dwFirstMBaddress 는 대응하는 매크로 블록 컨트롤 커멘드 버퍼와 같은 값을 가져야 하는 것이다.

dwNumMBsInBuffer : 버퍼내의 데이터의 매크로 블록수. 데이터 버퍼가, 픽쳐 디코드 파라미터, 역양자화 행렬, AYUV, IA44/AI44, DPXD, Highlight, DCCMD 의 몇개의 타입인 경우는, 0 이 아니면 안된다. 데이터 버퍼가 매크로 블록 컨트롤 버퍼라면, dwNumMBsInBuffer 은 MBskipsFollowing 의 값과 매크로 블록 컨트롤 블록 버퍼내의 매크로 블록 컨트롤 커멘드의 총수의 화와 동일한 한다. 데이터 버퍼가 잔차블록 데이터 버퍼라면, dwNumMBsInBuffer 는 대응하는 매크로 블록 컨트롤 커멘드 버퍼와 같은 값을 가져야 하는 것이다. 데이터 버퍼가 슬라이스 컨트롤 커멘드 버퍼라면, dwNumMBsInBuffer 은 슬라이스 컨트롤 버퍼내의 wNumberMBsInSlice 의 총수로 동일한 한다. 데이터 버퍼가 비트 스트림 데이터 버퍼라면, dwNumMBsInBuffer 는 대응하는 슬라이스 컨트롤 커멘드 버퍼와 같은 값을 가져야 하는 것이다.

dwWidth, dwHeight, dwStride : 버퍼내의 데이터의 폭, 높이, 및 보폭. 데이터 버퍼가 IA44/AI44 또는 DPXD 의 몇개의 타입이 아닌 한, 0 이 아니면 안된다. 적용되는 버퍼 타입에 대해서는, 가속기가 실행하는 버퍼 할당 셋업에 의해 dwStride 가 결정된다.

주: 디코더는 IA44/AI44 혹은 DPXD 로 지정되고 있는 보폭을 지키는 것에 반드시 주의하지 않으면 안 된다.

3.5 압축 픽쳐의 디코드 (bDXVA_Func=1)

DirectX VA 처리를 위해서(때문에) 정의된 최초의 함수 타입은, 압축 픽쳐의 일부 또는 전부의 디코드이다.

3.5. 1 접속 구성

압축 픽쳐를 디코드하기 위한 DirectX VA 접속 구성 데이터 구조체는, 다음과 같이 정의되지 않으면 안 된다.

DXVA_ConfigPictureDecode {
                dwFunction,                      // 지정된 처리  32b
                dwReservedBits[3],               // 3 * 32b alignment
                guidConfigBitstreamEncryption,   // 암호화 타입의 GUID 128b
                guidConfigMBcontrolEncryption,
                guidConfigResidDiffEncryption,
                bConfigBitstreamRaw,             // 비트 스트림 처리  8b
                bConfigMBcontrolRasterOrder,     // 매크로 블록 제어   8b
                bConfigResidDiffHost,            // 호스트잔차  8b
                bConfigSpatialResid8,            // 8b
                bConfigResid8Subtraction,        // 8b
                bConfigSpatialHost8or9Clipping,  // 8b
                bConfigSpatialResidInterleaved,  // 8b
                bConfigIntraResidUnsigned,       // 8b
                bConfigResidDiffAccelerator,     // 가속기잔차  8b
                bConfigHostInverseScan,          // 8b
                bConfigSpecificIDCT,             // 8b
                bConfig4GroupedCoefs             // 8b
}

dwFunction : 구성 데이터의 구조를 기술하는 DXVA_ConfigQueryOrReplyFunc 를 포함한다.

guidConfigBitstreamEncryption : 비트 스트림 데이터 버퍼의 암호 프로토콜 타입에 관련지을 수 있었던 GUID 를 나타낸다. DXVA_NoEncrypt 라고 하는 값 (관련지을 수 있었던 헤더 파일내에 정의된 GUID 명)은, 암호가 적용되지 않은 것을 의미한다. bConfigBitstreamRaw 가 "0" 의 경우는, DXVA_NoEncrypt 가 아니면 안된다.

guidConfigMBcontrolEncryption : 매크로 블록 제어 데이터 버퍼의 암호 프로토콜 타입에 관련지을 수 있었던 GUID 를 나타낸다. DXVA_NoEncrypt 라고 하는 값 (관련지을 수 있었던 헤더 파일내에 정의된 GUID 명)은, 암호가 적용되지 않은 것을 의미한다. bConfigBitstreamRaw 가 "1" 의 경우는, DXVA_NoEncrypt 가 아니면 안된다.

guidConfigResidDiffEncryption : 잔차디코드 데이터 버퍼 (공간 영역 데이터, 또는 가속기 베이스 IDCT 의 변환 영역 계수 세트를 포함한 버퍼)의 암호 프로토콜 타입에 관련지을 수 있었던 GUID 를 나타낸다. DXVA_NoEncrypt 라고 하는 값 (관련지을 수 있었던 헤더 파일내에 정의된 GUID 명)은, 암호가 적용되지 않은 것을 의미한다. bConfigBitstreamRaw 가 "1" 의 경우는, DXVA_NoEncrypt 가 아니면 안된다.

bConfigBitstreamRaw : 값 "1" 은, 픽쳐의 데이터가, 생의 비트 스트림 컨텐츠로서 비트 스트림 버퍼내에 송신되는 것을 나타낸다. 값 "0" 은, 픽쳐 데이터가 매크로 블록 제어 커멘드 버퍼를 사용해 송신되는 것을 나타낸다. bConfigResidDiffHost 가 "1" 의 경우, 또는 bConfigResidDiffAccelerator 가 "1" 의 경우는,"0" 이 아니면 안된다. 중기적인 조건은,"0" 을 지원 하는 것이다. 게다가 "1" 이 지원 하는 것이 바람직하다.

bConfigMBcontrolRasterOrder : 값 "1" 은, 각 매크로 블록 제어 커멘드 버퍼내의 매크로 블록 제어 커멘드가, 라스터 스캔의 순서로 되어 있지 않으면 안 되는 것을 나타낸다. 값 "0" 은, 임의의 순서인 것을 나타낸다. 비트 스트림의 타입에 따라서는, 라스터 순서를 강제 하면, 처리가 필요한 매크로 블록 제어 버퍼의 수가 매우 증가하거나 제어 정보를 호스트측으로 나란해질 수 있는 바꿀 필요가 생기거나 한다. 이 때문에, 임의의 순서를 지원 하는 것은, 디코드 처리에 유리하다. 예를 들어, H. 261 CIF 해상도의 디코드에서는, 각 버퍼내가 라스터 스캔의 순서가 되어 있을 필요가 있는 경우는, 1 픽쳐 마다 36 의 매크로 블록 제어 버퍼가 필요하다 (H. 263 보유 K 의 임의 슬라이스 순서 및 직사각형 슬라이스 모드에서도 같은 영향이 있다). 중기적인 조건은,"0" 을 지원 하는 것이다. 단기적으로는 "1" 의 지원도 용인되지만, 저레벨의 기능이며, 그다지 추천 되지 않는다.

bConfigResidDiffHost : 값 "1" 은, 몇개의 잔차디코드 데이터가, 공간 영역내의 블록으로서 호스트로부터 송신될 가능성이 있는 것을 나타낸다. 값 "0" 은, 공간 영역 데이터가 송신되지 않는 것을 나타낸다. bConfigBitstreamRaw 가 "1" 의 경우는,"0" 이 아니면 안된다. 중기적인 조건은,"1" 을 지원 하는 것이다. 이것은 추천 되는 값이다.

bConfigSpatialResid8: 호스트 베이스의 잔차디코드를 사용할 때 (ie. bConfigResidDiffHost 가 "1" 때) , 예측되는 (ie 비인트라) 픽쳐의 잔차공간 영역 블록에 이용하는 WORD 사이즈를 나타낸다.

bConfigSpatialResid8 가 "1" 또한 bConfigResidDiffHost 가 "1" 이라면 다음 일을 나타내는, 호스트는 부호 첨부 8 비트 샘플을 사용하는 비인트라 매크로 블록에 대해서는 잔차공간 영역 블록을 보내, 포맷이 bConfigIntraResidUnsigned 에 의존하는 예측된다 (ie. 비인트라) 픽쳐의 인트라 매크로 블록에 대해서는 다음과 같이 된다 :

  • bConfigIntraResidUnsigned 가 "0" 이라면, 인트라 매크로 블록의 공간 영역 블록은 일정 참조값 2(BPP-1) 에 대립된 8 비트 부호 첨부 정수값으로서 보내진다, 그리고
  • bConfigIntraResidUnsigned 가 "1" 이라면, 인트라 매크로 블록의 공간 영역 블록은 일정 참조값 0 에 대립된 8 비트 부호 없음 정수값으로서 보내진다.

bConfigSpatialResid8 가 "0" 또한 bConfigResidDiffHost 가 "1" 이라면 다음 일을 나타내는, 호스트는 부호 첨부 16 비트 샘플을 사용하는 비인트라 매크로 블록에 대해서는 잔차공간 영역 블록을 보내, 포맷이 bConfigIntraResidUnsigned 에 의존하는 예측된다 (ie. 비인트라) 픽쳐의 인트라 매크로 블록에 대해서는 다음과 같이 된다 :

  • bConfigIntraResidUnsigned 가 "0" 이라면, 인트라 매크로 블록의 공간 영역 블록은 일정 참조값 2(BPP-1) 에 대립된 16 비트 부호 첨부 정수값으로서 보내진다, 그리고
  • bConfigIntraResidUnsigned 가 "1" 이라면, 인트라 매크로 블록의 공간 영역 블록은 일정 참조값 0 에 대립된 16 비트 부호 없음 정수값으로서 보내진다.

bConfigResidDiffHost 이 "0" 이라면 bConfigSpatialResid8 는 "0" 이어야 한다. 이 스펙(명세서)는 bConfigResidDiffHost 이 "1" 때, bConfigSpatialResid8 가 가져야 할 값의 참조를 가지지 않는다.

주 : 비예측 (인트라) 픽쳐의 경우, 공간 영역 블록은, BPP = 8 의 경우는 항상 8 비트 샘플을 사용해 송신되어 BPP > 8 의 경우는 16 비트 샘플을 사용해 송신되지 않으면 안 된다. bConfigIntraResidUnsigned 가 "0" 이라면, 이러한 샘플은 일정 참조값 2(BPP-1) 에 대립된 부호 첨부 정수값으로서 보내져 ConfigIntraResidUnsigned 가 "1" 이라면, 일정 참조값 0 에 대립된 부호 없음 정수값으로서 보내진다.

bConfigResid8Subtraction : bConfigSpatialResid8 가 "1" 의 경우에, 값 "1" 은, 8 비트 차이의 오버플로우 블록이 가산이 아니고 감산되는 것을 나타낸다. bConfigSpatialResid8 가 "1" 이 아닌 경우는,"0" 이 아니면 안된다. "1" 의 경우, 이것은 모든 오버플로우 블록이 가산이 아니고 감산되는 것을 나타낸다. 중기적인 조건은, bConfigSpatialResid8 가 "1" 의 경우의 "1" 을 지원 하는 것이다. 차이를 가산하므로 없게 감산할 수 있는 것에 의해, 8 비트 차이 디코드가, 비디오 디코더의 사양으로 필요한 값의 전범위인 ±255 에 완전에 대응할 수 있다. 이것은, 2 개의 부호 첨부 8 비트 수치의 가산으로 +255 를 표현할 수 없지만, 2 개의 부호 첨부 8 비트 수치의 차이를 사용하면 ±255 의 범위의 모든 수치를 표현할 수 있기 때문에 있다 (+255 = +127 마이너스 -128).

bConfigSpatialHost8or9Clipping : bConfigSpatialResid8 = "0" 또한 bConfigResidDiffHost = "1" 의 경우, 값 "1" 은, 인트라 매크로 블록의 공간 영역 블록이 호스트 위에의 8 비트 범위에 클립 되어 비인트라 매크로 블록의 공간 영역 블록이 호스트 위에의 9 비트 범위에 클립 되지 않으면 안 되는 것을 나타낸다. 값 "0" 은, 호스트에 의해 그러한 클리핑이 실행될 필요가 없는 것을 나타낸다. bConfigSpatialResid8 = "0" 으로 bConfigResidDiffHost = "1" 이 아닌 한,"0" 이 아니면 안된다. 중기적인 조건은,"0" 을 지원 하는 것이다. 단기적으로는 "1" 의 지원도 용인되지만, 저레벨의 가속기 기능이며, 그다지 추천 되지 않는다.

bConfigSpatialResidInterleaved : bConfigResidDiffHost 가 "1" 으로, YUV 포맷이 "NV12" 또는 "NV21" 때에 이 값이 "1" 의 경우는, 모든 공간 영역잔차데이터가, YUV 포맷의 크로마인타리브파탄에 일치하는 크로마인타리브포맛트로 송신되지 않으면 안 되는 것을 나타낸다. bConfigResidDiffHost 가 "1" 으로 YUV 포맷이 "NV12" 또는 "NV21" 가 아닌 한,"0" 이 아니면 안된다. 중기적인 조건은,"0" 을 지원 하는 것이다. 단기적으로는 "1" 의 지원도 용인되지만, 저레벨의 가속기 기능이며, 그다지 추천 되지 않는다.

bConfigIntraResidUnsigned: 호스트 베이스의 잔차디코드를 사용할 때 (ie. bConfigResidDiffHost 가 "1" 때) , 인트라 블록에 관한 잔차공간 영역 블록 표시의 메소드를 나타낸다.

bConfigIntraResidUnsigned 가 "0" 또한 bConfigResidDiffHost 가 "1"이라면 다음 일을 나타내는, 인트라 매크로 블록의 공간 영역잔차데이터 블록은 이하와 같이 보내진다 :

  • 비인트라 픽쳐의 경우 bConfigSpatialResid8 가 "0" 이라면, 인트라 매크로 블록의 공간 영역잔차데이터 블록은 일정 참조값 2(BPP-1) 에 대립된 16 비트 부호 첨부 정수값으로서 보내진다.
  • 비인트라 픽쳐의 경우 bConfigSpatialResid8 가 "1" 이라면, 그리고 인트라 픽쳐의 경우 BPP 가 "8" 으로 동일하면 (bConfigSpatialResid8 의 값과는 관계없이), 인트라 매크로 블록의 공간 영역잔차데이터 블록은 일정 참조값 2(BPP-1) 에 대립된 8 비트 부호 첨부 정수값으로서 보내진다.

bConfigIntraResidUnsigned 가 "1" 또한 bConfigResidDiffHost 가 "1" 이라면, 인트라 매크로 블록의 공간 영역잔차데이터 블록은 이하와 같이 보내진다 :

  • 비인트라 픽쳐의 경우 bConfigSpatialResid8 가 "0" 이라면, 인트라 매크로 블록의 공간 영역잔차데이터 블록은 일정 참조값 0 에 대립된 16 비트 부호 첨부 정수값으로서 보내진다.
  • 비인트라 픽쳐의 경우 bConfigSpatialResid8 가 "1" 이라면, 그리고 인트라 픽쳐의 경우 BPP 가 "8" 으로 동일하면 (bConfigSpatialResid8 의 값과는 관계없이), 인트라 매크로 블록의 공간 영역잔차데이터 블록은 일정 참조값 0 에 대립된 8 비트 부호 첨부 정수값으로서 보내진다.

bConfigResidDiffHost 가 "1" 이 아니면, bConfigIntraResidUnsigned 는 "0" 이어야 한다. "1" 으로 동일한 bConfigIntraResidUnsigned 에 의해 가까운 텀(term)의 지원은 허가되지만,"0" 으로 동일한 bConfigIntraResidUnsigned 가 보다 바람직하고, 가속기 능력의 레벨이 낮다고 해석된다.

bConfigResidDiffAccelerator : 값 "1" 은, 계수 데이터의 변환 영역 블록이, 가속기 베이스의 IDCT 를 위해서(때문에) 호스트로부터 송신될 가능성이 있는 것을 나타낸다. 값 "0" 은, 가속기 베이스의 IDCT 가 사용되지 않는 것을 나타낸다. bConfigResidDiffHost 및 bConfigResidDiffAccelerator 의 양쪽 모두가 "1" 의 경우는, 매크로 블록 레벨 제어 커멘드로 나타난 것처럼, 잔차디코드의 일부가 호스트상에서 실행되어 일부가 가속기상에서 실행되는 것을 나타낸다. bConfigBitstreamRaw 가 "1" 의 경우는,"0" 이 아니면 안된다. bConfigResidDiffAccelerator = "1" 의 지원이 필요하지만, 이 지원에 관해서는, 중기적인 조건은 설정되지 않는다. bConfigResidDiffAccelerator 가 "1" 이며, bConfigResidDiffHost 도 "1" 인 경우가 지원 된다고 하는 것은, 잔차디코드가, 매크로 블록 마다, 호스트와 가속기의 사이에 공유할 수 있는 것을 나타낸다. 이것은, bConfigResidDiffAccelerator 가 "1" 이며 bConfigResidDiffHost 가 "0" 인 경우보다 높은 가속기 기능이다고 보여진다

bConfigHostInverseScan : 값 "1" 은, 변환 영역 블록 처리의 역스캔이 호스트상에서 실행되어 변환계수 대신에 절대 인덱스가 송신되는 것을 나타낸다. 값 "0" 은, 역스캔이 가속기상에서 실행되는 것을 나타낸다. bConfigResidDiffAccelerator 가 "0" 의 경우는,"0" 이 아니면 안된다. bConfig4GroupedCoefs 가 "0" 의 경우는,"1" 이 아니면 안된다. 중기적인 조건은, bConfigResidDiffAccelerator 가 "1" 의 경우에 "1" 을 지원 하는 것이다. 단기적으로는 bConfig4GroupedCoefs 가 "1" 의 경우에 "0" 을 지원 하는 일도 용인되지만, 그다지 추천 되지 않는다. 이것은, 저레벨의 가속기 기능이며, 임의의 스캔 패턴을 지원 하는 유연성이 부족해 호스트에서의 역스캔에 의한 호스트 소프트웨어 디코더 처리의 부담증가는 거의 없다고 생각되기 때문에 있다.

bConfigSpecificIDCT : 값 "1" 은, ITU-T 권고 H. 263 의 보유 W 로 정의된 IDCT 가 사용되는 것을 나타내, 값 "0" 은, 오프 호스트의 IDCT 에, 모든 준거 IDCT 를 사용할 수 있는 것을 나타낸다. (주 : 드래프트 단계에 있는 참조처의 보유는, 아직 ITU-T 의 최종 승인을 받고 있지 않다. ITU 내에서 변경이 있었을 경우, 이 비트는 드래프트 버젼이 아니고 최종 버젼을 참조한다. 또, 참조처 드래프트는 MPEG-2 정오표 2 에 있는 IDCT 의 조건을 채우지 않고, 따라 MPEG-2 비디오에 사용하는 경우에 bConfigSpecificIDCT 를 1 으로서는 안 되는 점에도 주의하는 편이 좋다) bConfigResidDiffAccelerator 가 "0" 의 경우는, 0 이 아니면 안된다 (순수하게 호스트 베이스의 잔차디코드인 것을 나타낸다). 중기적인 조건은, bConfigResidDiffAccelerator 가 "1" 의 경우에 "0" 이 지원 되는 것이다. 게다가 "1" 이 지원 되는 것이 바람직하다. 이것들 이외의 값도 장래 정의될 가능성이 있다.

bConfig4GroupedCoefs : 값 "1" 은, 오프 호스트의 IDCT 용의 변환계수가, DXVA_TCoefSingle 데이터 구조체가 아니고 DXVA_TCoef4Group 데이터 구조체를 사용해 송신되는 것을 나타낸다. bConfigResidDiffAccelerator 가 "0" 의 경우, 또는 bConfigHostInverseScan 가 "1" 의 경우는,"0" 이 아니면 안된다. 중기적인 조건은, bConfigResidDiffAccelerator 가 "1" 의 경우에 "0" 이 지원 되는 것이다. 단기적으로는 bConfigHostInverseScan 이 "0" 의 경우에 "1" 을 지원 하는 일도 용인되지만, 저레벨의 가속기 기능이며, 그다지 추천 되지 않는다.

3.5. 2 최소한의 상호 동작성 구성 세트

설계 위에의 조건으로서 모든 DirectX VA 디코더는, 모든 DirectX VA 가속기와 상호 동작할 필요가 있다. 이 때문에는, 모든 DirectX VA 디코더가, 접속 구성 세트의 모든 멤버와 함께 동작할 수 있어 모든 DirectX VA 가속기가, 동세트에 속하는 적어도 1 개의 접속 구성 멤버와 함께 동작할 수 있을 필요가 있다. 최소한의 상호 동작성 세트는 다음과 같이 정의된다.

  1. 이 가장 기본적인 세트의 모든 멤버는 다음의 공통점을 가진다.
    1. guidConfigBitstreamEncryption = DXVA_NoEncrypt
    2. guidConfigMBcontrolEncryption = DXVA_NoEncrypt
    3. guidConfigResidDiffEncryption = DXVA_NoEncrypt
    4. bConfigBitstreamRaw = 0
    5. bConfigHostInverseScan = 0
    6. bConfigSpecificIDCT = 0
  2. 이 세트의 최초의 2 개의 멤버 (여기에 속하는 가속기는, bConfigSpatialHost8or9Clipping = 0 의 바리에이션을 지원 하는 것을 추천 된다)는, 다음에 의해 정의된다.
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 1
    3. bConfigSpatialResid8 = 0
    4. bConfigResid8Subtraction = 0
    5. bConfigSpatialHost8or9Clipping = 0 or 1
    6. bConfigSpatialResidInterleaved = 0
    7. bConfigIntraResidUnsigned = 0
    8. bConfigResidDiffAccelerator = 0
  3. 세트의 3 번째의 멤버 (가속기 이행을 특히 추천 되지 않는다)는, 다음대로.
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 1
    3. bConfigSpatialResid8 = 1
    4. bConfigResid8Subtraction = 0
    5. bConfigSpatialHost8or9Clipping = 0
    6. bConfigSpatialResidInterleaved = 1
    7. bConfigIntraResidUnsigned = 0
    8. bConfigResidDiffAccelerator = 0
  4. 세트의 4 번째의 멤버 (가속기 이행을 특히 추천 되지 않는다)는, 다음대로.
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 1
    3. bConfigSpatialResid8 = 0
    4. bConfigResid8Subtraction = 0
    5. bConfigSpatialHost8or9Clipping = 1
    6. bConfigSpatialResidInterleaved = 0
    7. bConfigIntraResidUnsigned = 1
    8. bConfigResidDiffAccelerator = 0
  5. 이 세트에 포함되는 나머지 2 개의 멤버 (여기에 속하는 가속기는, bConfigResid8Subtraction = 1 의 바리에이션을 지원 하는 것을 추천 된다)는, 다음에 의해 정의된다.
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 1
    3. bConfigSpatialResid8 = 1
    4. bConfigResid8Subtraction = 0 or 1
    5. bConfigSpatialHost8or9Clipping = 0
    6. bConfigSpatialResidInterleaved = 0
    7. bConfigIntraResidUnsigned = 0
    8. bConfigResidDiffAccelerator = 0
  6. 이 세트에 포함되는 나머지 1 개의 멤버는 4장에 설명되어 DXVA_ConnectMode 에 나타나고 있는 MPEG2_C 와 MPEG2_D 한정 모드 프로파일용으로만 정의된다. 다른 프로파일은 최소 인타오페라비리티셋트의 이 구성에는 포함되지 않는다. 이 추가 멤버는 다음에 의해 정의된다.
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 0
    3. bConfigResidDiffAccelerator = 1
    4. bConfigHostInverseScan = 0
    5. bConfig4GroupedCoefs = 1

3.5. 3 보완적인 추천 구성 세트

소프트웨어 디코더에서는, 몇개의 보완적 구성을 지원 하는 것을 추천 한다. 이것은, 양산되는 하드웨어에 이러한 구성이 존재해, 이러한 구성은 최소한의 구성 세트보다 압도적으로 높은 퍼포먼스를 제공할 수 있다고 생각되기 때문이다. 추천 구성 세트는 이하대로.

  1. 이 세트의 멤버 모두에게 공통의 성질은 이하대로.
    1. guidConfigBitstreamEncryption = DXVA_NoEncrypt
    2. guidConfigMBcontrolEncryption = DXVA_NoEncrypt
    3. guidConfigResidDiffEncryption = DXVA_NoEncrypt
    4. bConfigMBcontrolRasterOrder = 0
    5. bConfigResidDiffHost = 0
    6. bConfigSpatialResid8 = 0
    7. bConfigResid8Subtraction = 0
    8. bConfigSpatialHost8or9Clipping = 0
    9. bConfigSpatialResidInterleaved = 0
    10. bConfigSpecificIDCT = 0
  2. 이 세트의 최초의 멤버는, 오프 호스트의 비트 스트림 처리의 가속화를 적절히 지원 하기 위한(해), 다음과 같이 정의된다.
    1. bConfigBitstreamRaw = 1
    2. bConfigResidDiffAccelerator = 0
    3. bConfigHostInverseScan = 0
    4. bConfig4GroupedCoefs = 0
  3. 이 세트의 2 번째의 멤버는, 오프 호스트의 IDCT 가속화를 적절히 지원 하기 위한(해), 다음과 같이 정의된다.
    1. bConfigBitstreamRaw = 0
    2. bConfigResidDiffAccelerator = 1
    3. bConfigHostInverseScan = 1
    4. bConfig4GroupedCoefs = 0
  4. 이 세트의 3 번째의 멤버 (2 번째의 멤버와 비교하면(자) 가속기에는 그다지 추천 되지 않는다)는, 일부의 이행으로 보여진다고 예상되는 오프 호스트 IDCT 를 지원 하기 위한(해), 다음과 같이 정의된다.
    1. bConfigBitstreamRaw = 0
    2. bConfigResidDiffAccelerator = 1
    3. bConfigHostInverseScan = 0
    4. bConfig4GroupedCoefs = 1

추천 구성 세트의 최초의 멤버를 지원 하는 가속기는, 그 가속화 능력의 사용법에 유연성을 갖게하기 (위해)때문에, 2 번째의 멤버도 지원 하는 것을 강하게 추천 한다.

3.5. 4 압축 픽쳐의 파라미터

픽쳐 1 개(살)에 대해, 다음의 변수가 1 회송신 되지 않으면 안 된다.

DXVA_PictureParameters {
                wDecodedPictureIndex        // 16b
                wDeblockedPictureIndex      // 16b

                wForwardRefPictureIndex     // 16b
                wBackwardRefPictureIndex    // 16b

                wPicWidthInMBminus1         // 16b
                wPicHeightInMBminus1        // 16b

                bMacroblockWidthMinus1      // 8b
                bMacroblockHeightMinus1     // 8b

                bBlockWidthMinus1           // 8b
                bBlockHeightMinus1          // 8b

                bBPPminus1                  // 8b

                bPicStructure               // 8b
                bSecondField                // 8b
                bPicIntra                   // 8b
                bPicBackwardPrediction      // 8b

                bBidirectionalAveragingMode // 8b
                bMVprecisionAndChromaRelation   // 8b
                bChromaFormat                   // 8b
                bPicScanFixed                   // 8b
                bPicScanMethod                  // 8b
                bPicReadbackRequests            // 8b

                bRcontrol                       // 8b
                bPicSpatialResid8               // 8b
                bPicOverflowBlocks              // 8b
                bPicExtrapolation               // 8b

                bPicDeblocked                   // 8b
                bPicDeblockConfined             // 8b
                bPic4MVallowed                  // 8b
                bPicOBMC                        // 8b
                bPicBinPB                       // 8b
                bMV_RPS                         // 8b
                bReservedBits                   //  8b (alignment)

                wBitstreamFcodes                // 16b
                wBitstreamPCEelements           // 16b
                bBitstreamConcealmentNeed       // 8b
                bBitstreamConcealmentMethod     // 8b
                }

wDecodedPictureIndex : 디코드된 매크로 블록의 행선지 frame buffer를 지정한다.

wDeblockedPictureIndex : bPicDeblocked 가 "1" 의 경우에, 블록 해제된 출력 픽쳐의 행선지 frame buffer를 지정한다. bPicDeblocked 가 "0" 의 경우는 의미가 없고,"0" 이 아니면 안된다. wDecodedPictureIndex 와 같게 되는 경우가 있다.

wForwardRefPictureIndex : 현재의 픽쳐의 "순서 방향 예측" 의 참조 픽쳐로서 사용되는 픽쳐의 frame buffer 인덱스를 지정한다. wDecodedPictureIndex 와 같게 해서는 안 된다. bPicIntra 가 "1" 이라면 0xFFFF 으로 마땅한이다.

wBackwardRefPictureIndex : 현재의 픽쳐의 "역방향 예측" 의 참조 픽쳐로서 사용되는 픽쳐의 frame buffer 인덱스를 지정한다. 역방향 참조 움직임 예측이 사용되는 경우는, wDecodedPictureIndex 와 같게 해서는 안 된다. bPicBackwardPrediction 가 "0" 이라면 0xFFFF 으로 마땅한이다

wPicWidthInMBminus1 : 크로브록크의 단위로 나타낸, 현재의 픽쳐의 폭마이너스 1 을 지정한다. 파생어인 PicWidthInMB 은, PicWidthInMBminus1 에 1 을 더한 것이다.

wPicHeightInMBminus1 : 매크로 블록의 단위로 나타낸, 현재의 픽쳐의 높이 마이너스 1 을 지정한다. 파생어인 PicHeightInMB 은, PicHeightInMBminus1 에 1 을 더한 것이다.

bMacroblockWidthMinus1 : 매크로 블록의 행선지 휘도 샘플의 폭을 지정한다. MPEG-1, MPEG-2, H. 263, MPEG-4 의 경우는 "15" 가 된다. 파생어인 MacroblockWidth 는, bMacroblockWidthMinus1 에 1 을 더한 것이다.

bMacroblockHeightMinus1 : 매크로 블록의 행선지 휘도 샘플의 높이를 지정한다. MPEG-1, MPEG-2, H. 261, H. 263, MPEG-4 의 경우는 "15" 가 된다. 파생어인 MacroblockHeight 는, bMacroblockHeightMinus1 에 1 을 더한 것이다.

bBlockWidthMinus1 : 잔차블록의 블록폭을 지정한다. MPEG-1, MPEG-2, H. 261, H. 263, MPEG-4 의 경우는 "7" 이 된다. bConfig4GroupedCoefs 가 "1" 의 경우는,"7" 이 아니면 안된다. 매크로 블록내의 잔차블록은, MPEG-2 도 6-10,6-11,6-12 그리고 지정된 순서에 송신된다 (라스터 스캔순서의 Y, 라스터 스캔순서의 Cb 의 전 4:2:0 블록, Cr 의 4:2:0 블록, Cb 의 4:2:2 블록, Cr 의 4:2:2 블록, Cb 의 4:4:4 블록, Cr 의 4:4:4 블록의 순서). 파생어인 WT 는, BlockWidthMinus1 에 1 을 더한 것이다.

bBlockHeightMinus1 : IDCT 블록의 블록의 높이를 지정한다. MPEG-1, MPEG-2, H. 261, H. 263, MPEG-4 의 경우는 "7" 이 된다. bConfig4GroupedCoefs 가 "1" 의 경우는,"7" 이 아니면 안된다. 파생어인 HT 는, BlockHeightMinus1 에 1 을 더한 것이다.

bBPPminus1 : 비디오 샘플값의, 픽셀마다의 비트수를 지정한다. 최소에서도, 8 비트 픽셀을 나타내는 "7" 이 아니면 안된다. MPEG-1, MPEG-2, H. 261, H. 263 의 경우는 "7" 이 된다. MPEG-4 의 몇개의 처리 모드에서는, 1 픽셀마다의 비트수를 대부분 할 수 있다. 파생어인 BPP 는, bBPPminus1 에 1 을 더한 것이다.

bPicStructure : 이 파라미터는, MPEG-2 의 섹션 6.3. 10 및 겉(표) 6-14 로 정의되고 있는 picture_structure 파라미터와 같은 의미를 가져, 현재의 픽쳐가, 상 필드 픽쳐 (값 '01'), 하 필드 픽쳐 (값 '10'), 프레임 픽쳐 (값 '11')의 어떤 것인지를 나타낸다. H. 261 과 같은 프로그래시브 스캔 프레임 구조화 코딩의 경우, bPicStructure 는 '11'가 아니면 안된다. bPicStructure 가 '10' (하 필드)가 아닌 한, 파생 파라미터인 PicCurrentField 는 "0" 으로서 정의되어 그 경우 이 파라미터는 "1" 이 된다.

bSecondField : 필드 구조화 코딩 (bPicStructure 가 '01'또는 '10' 때)의 경우에, 현재의 필드가 픽쳐의 2 번째의 필드일지 어떨지를 나타낸다. 이것은, motion compensation 예측을 위해서(때문에) 역패리티 라인의 참조로서 사용되는 역parity field가, 참조 픽쳐의 역parity field인가, 또는 현재의 픽쳐의 역parity field인지를 결정하는데 사용된다. bSecondField 가 "1" 의 경우, 현재의 필드는, 픽쳐의 제 2 필드이며, motion compensation를 위해서(때문에) 역패리티 라인의 참조로서 사용되는 필드는, 현재의 픽쳐의 역패리티 라인이다. (어느 쪽의 경우도, motion compensation를 위해서(때문에) 동패리티 라인의 참조로서 사용되는 필드는, 참조 픽쳐의 동패리티 라인이다. ) 그 이외의 경우, bSecondField 는 "0" 이 아니면 안된다.

bPicIntra : 이 픽쳐에 대해서 motion compensation 예측이 필요한가 어떤가를 지정한다. bPicIntra 가 "1" 의 경우는, 모든 매크로 블록은 IntraMacroblock 는 "1" 으로 송신된다 (즉, 그 픽쳐에 관해서 motion compensation 예측은 실행되지 않는다). 그 이외의 경우, 픽쳐의 일부 매크로 블록이 IntraMacroblock 가 "0" 이 될 가능성이 있다.

bPicBackwardPrediction : 현재의 픽쳐에 역방향 예측을 포함한 매크로 블록인가 있을지 어떨지를 나타낸다. bPicIntra 가 "1" 의 경우, bPicBackwardPrediction 는 "0" 이 아니면 안된다. 그 이외의 경우, bPicBackwardPrediction 가 "0" 이면, 픽쳐의 전매크로 블록으로 MotionBackward 가 "0" 이 아니면 안된다. bPicBackwardPrediction 가 "1" 이면, 픽쳐의 전매크로 블록으로 MotionBackward 가 "1" 이 아니면 안된다.

bBidirectionalAveragingMode : 이 플래그는, 쌍방향 motion compensation로 예측 프레인을 조합할 때의 둥근 방법을 지정한다 (B 픽쳐 및 듀얼 프라임의 움직임에 사용된다). 값 "0" 은 MPEG-1 와 MPEG-2 의 둥근 평균화 (//2), 및 "1" 은 H. 263 의 잘라서 버림 평균화 (/2)를 포함한다. 쌍방향 평균화가 필요없는 경우는, bBidirectionalAveragingMode 는 "0" 이 아니면 안된다.

bMVprecisionAndChromaRelation : 이 2 비트 필드는, 휘도 움직임 벡터의 정밀도와 휘도 움직임 벡터로부터 색광도 움직임 벡터가 파생되지 않으면 안 되는 방법을 나타낸다.

'00'는, 휘도 움직임 벡터의 정밀도가 하프 샘플이며, 색광도 움직임 벡터가 MPEG-2 의 규칙에 따라 휘도 움직임 벡터로부터 파생되는 것을 나타낸다.

'01'는, 휘도 움직임 벡터의 정밀도가 하프 샘플이며, 색광도 움직임 벡터가 H. 263 의 규칙에 따라 휘도 움직임 벡터로부터 파생되는 것을 나타낸다.

'10'는, 휘도 움직임 벡터의 정밀도가 풀 샘플이며, 색광도 움직임 벡터가 H. 261 섹션 3.2. 2 의 규칙 (2 로 나눗셈 해, 풀 샘플값까지 0 방향으로 잘라 버리고)에 따라 휘도 움직임 벡터로부터 파생되는 것을 나타낸다.

'11'는 예약되고 있다.

bChromaFormat : 가속기에 의해 예기 되는 예측 에러 블록의 수에 영향을 준다. 이 변수는, MPEG-2 의 섹션 6.3. 5 및 겉(표) 6-5 로 정의되고 있다. MPEG-1, MPEG-2 "메인 프로파일", H. 261, H. 263 비트 스트림의 경우, 이 값은 항상 "4:2:0" 포맷을 나타내는 '01'로 설정되지 않으면 안 된다. '10'의 경우는 "4:2:2", '11'의 경우는 "4:4:4" 샘플링을 나타낸다. bConfig4GroupedCoefs 가 "1" 이라면, '01'로 해야 하는 것이다. (왜냐하면 bConfig4GroupedCoefs 는 4:2:2 과 4:4:4 포맷의 계수 데이터에 필요하게 되고 있는 EOB 지시를 포함하지 않기 때문에. )

주 : H. 261, H. 263, 및 MPEG-1 와 MPEG-2 및 MPEG-4 에서는 수평 방향의 크로마 배치가 약간 다르다. 이 차이는, 무시할 수 있는 정도로 작은 것이라고 상정된다.

bPicScanFixed : 잔차블록의 가속기 베이스 IDCT 처리를 사용할 때, 이 플래그의 값이 "1" 의 경우는, 역스캔 방법이 픽쳐내의 모든 매크로 블록에 대해 같은 것을 나타낸다. 값이 "0" 의 경우는 같지 않은 것을 나타낸다. bConfigHostInverseScan 이 "1", 또는 bConfigResidDiffAccelerator 가 "0" 의 경우, 이 값은 "1" 이 아니면 안된다.

bPicScanMethod : bPicScanFixed 가 "1" 의 경우, 이 필드는, 픽쳐의 고정역스캔 방법을 지정한다. bPicScanFixed 가 "0" 의 경우는, 이 필드는 의미가 없고, '00'가 아니면 안된다. bPicScanFixed 가 "1" 의 경우, 이 필드는 다음의 몇개의 값이 아니면 안된다.

  • bConfigHostInverseScan = 0 의 경우, bPicScanMethod 는 다음대로.
    • '00' = 지그재그 스캔 (MPEG-2 도 7-2)
    • '01' = 교호 수직 (MPEG-2 도 7-3)
    • '10' = 교호 수평 (H. 263 도 I. 2 파트 a)
  • bConfigHostInverseScan 가 "1" 의 경우, bPicScanMethod 는 다음대로.
    • '11' = 절대 계수 주소에 의한 임의 스캔

bPicReadbackRequests : 디코드된 (wDecodedPictureIndex 와 동일한 wDeblockedPictureIndex 로 블록 해제가 적용되는 경우에는, 블록도 해제된) 최종 픽쳐내의 매크로 블록의 값을 읽어 되돌리기 위해서(때문에), 현재의 픽쳐에 대해 읽어 반환 제어 요구가 실행될지 어떨지 지정한다. 값 "1" 은, 읽어 반환 요구가 있는 것을 나타낸다. 값 "0" 은 요구가 없는 것을 나타낸다.

bRcontrol : 이 플래그는, H. 263 섹션 6.1. 2 에 정의되고 있어 하프 샘플 motion compensation에 사용되는 둥근 방법을 지정한다. 값 "0" 은, MPEG-1, MPEG-2, 및 최초의 버젼의 H. 263 의 하프 샘플 둥근 방법이 사용되는 것을 나타낸다. 값 "1" 은, H. 263 및 MPEG-4 의 몇개의 옵션 모드로 선택할 수 있는, 하부 평균화 바이어스를 포함한 둥근 방법이 사용되는 것을 나타낸다. H. 261 에는 하프 샘플 motion compensation가 없기 때문에, 이 플래그는 H. 261 에서는 의미를 가지지 않는다. 모든 MPEG-1, 및 MPEG-2 의 비트 스트림의 경우, 이러한 규격으로 정의되고 있는 둥근 연산자에 준거하기 위해서는, 이 값이 "0" 으로 설정되지 않으면 안 된다.

bPicSpatialResid8 : 값 "1" 은, 호스트 베이스의 잔차디코드의 공간 영역 차이 블록이, 8 비트 샘플을 사용해 송신할 수 있는 것을 나타낸다. 값 0 은 송신할 수 없는 것을 나타낸다. bConfigResidDiffHost 가 "0", 또는 BPP > 8 의 경우는, 이 값은 "0" 이 아니면 안된다. BPP = 8 으로 bPicIntra = 1 으로, bConfigResidDiffHost 가 "1" 의 경우는,"1" 이 아니면 안된다. bPicSpatialResid8 가 1 의 경우는, 공간 영역 인트라 매크로 블록이, 정수값 2(BPP-1) 에 대응하는 부호 첨부 8 비트 차이값으로서 송신되어 공간 영역비인트라 매크로 블록 차이가, motion compensation 예측에 대응하는 부호 첨부 8 비트 차이값으로서 송신되는 것을 나타낸다. bPicSpatialResid8 는, 비디오 순서 전체에 대해서 글로벌로 지정하는 것이 아니라, 특정의 픽쳐에 관한 보고 지정 하면 말하는 점으로써, bConfigSpatialResid8 와 다르다. BPP 가 "8" 인 인트라 픽쳐와 같은 경우는, bConfigSpatialResid8 가 "0" 이어도 bPicSpatialResid8 는 "1" 이 된다.

bPicOverflowBlocks : 값 1 은, 픽쳐의 호스트 베이스잔차디코드를 위한 공간 영역 차이 블록이,"오버플로우" 블록을 사용해 송신될 가능성이 있는 것을 나타내, 값 0 은 그 가능성이 없는 것을 나타낸다. bConfigResidDiffHost 이 0 인가, bConfigSpatialResid8 가 "0" 인가, 또는 BPP > 8 의 경우는,"0" 이 아니면 안된다. bPicOverflowBlocks 는, 특정의 픽쳐에 대응하는 오버플로우 블록이 존재할 가능성이 있을지 어떨지를 나타낸다. BPP 가 "8" 의 인트라 픽쳐에서는, 이 경우에 오버플로우 블록은 불필요하기 때문에, bPicOverflowBlocks 는 "0" 이 아니면 안된다.

bPicExtrapolation : 이 플래그는, H. 263 보유 D 및 MPEG-4 로 정의되고 있도록(듯이), 픽쳐 경계를 넘는 움직임 벡터가 허가될지 어떨지를 지정한다. 이것을 실행하려면 , 디코드되는 픽쳐의 사이즈보다 폭이 2 매크로 블록분 넓고 (좌우에 각각 여분의 매크로 블록), 높이가 2 매크로 블록분 높은 (상하에 각각 여분의 매크로 블록) 픽쳐 프레인을 할당하는지, 또는 픽쳐 경계내에서 개개의 픽셀이 액세스 하는 주소를 클리핑 할 필요가 있다. 이 사양에서의 매크로 블록 주소는, 픽쳐 내부의 매크로 블록용이며, 패딩을 포함하지 않는다.

bPicDeblocked : 블록 해제된 출력 픽쳐를 wDeblockedPictureIndex 로 지정된 픽쳐 버퍼내에 생성 하기 위해서, 블록 해제 커멘드가 이 픽쳐용으로 송신될지 어떨지를 나타낸다. bPicDeblocked 가 "1" 의 경우는, 블록 해제 커멘드가 송신되어 블록 해제 프레임이 생성되지 않으면 안 된다. bPicDeblocked 가 "0" 의 경우는, 블록 해제 커멘드가 송신되지 않고, 블록 해제 픽쳐가 생성되어서는 안 된다.

bPicDeblockConfined : 블록 해제 필터 처리의 효력을, 버퍼에 저장 되고 있는 것과 동일한 매크로 블록 세트내로 한정하는 커멘드를, 블록 해제 필터 커멘드 버퍼에 포함할지 어떨지 지정한다.

bPic4MVallowed : H. 263 보유 F 및 J 로 사용되고 있도록(듯이), 매크로 블록 마다 4 개의 순서 방향 참조 움직임 벡터가 허가될지 어떨지를 지정한다.

bPicOBMC : 현재의 픽쳐의 움직임 보정이, H. 263 보유 F 로 정의되고 있도록(듯이), 중복 블록 motion compensation (OBMC)를 사용해 동작할지 어떨지를 지정한다. bPic4MVallowed 가 0 의 경우는, 0 이 아니면 안된다.

bPicBinPB : 픽쳐내의 쌍방향 예측 매크로 블록이 "PB 내의 B" motion compensation를 사용할지 어떨지 지정한다. 이 motion compensation는, H. 263 의 보유 G 및 M 로 정의되고 있도록(듯이), 각 매크로 블록에 대해, 쌍방향에 예측된 영역을, 역참조 픽쳐내의 대응하는 매크로 블록의 리젼으로 한정한다.

bMV_RPS : 움직임 벡터 참조 픽쳐 선택의 사용 방법을 지정한다. "1" 의 경우는, 픽쳐 전체적으로의 순서 방향 및 (경우에 따라서는) 역방향 움직임 픽쳐 인덱스 뿐만이 아니라, 각 움직임 벡터에 대해 참조 픽쳐 인덱스가 송신되는 것을 나타낸다. bMV_RPS 가 "1" 의 경우는, 파라미터 wForwardRefPictureIndex 및 wBackwardRefPictureIndex 는 의미가 없고,"0" 이 아니면 안된다.

wBitstreamFcodes : bConfigBitstreamRaw 가 "1" 의 경우, 이 파라미터는, MPEG-2 에 정의되고 있도록(듯이) 4 개의 움직임 벡터 f_code 값을 가진다. 각 f_code 값은 4 비트를 취한다. 이러한 값은, MPEG-2 와 같이, 다음과 같은 16 비트 워드에 팩 된다.

비트 12 ~ 15 (MSB) : f_code[0][0] : 순서 방향 수평 f_code

비트 8 ~ 11 : f_code[0][1] : 순서 방향 수직 f_code

비트 7 ~ 4 : f_code[1][0] : 역방향 수평 f_code

비트 0 ~ 3 (LSB) : f_code[1][1] : 역방향 수직 f_code

비트 스트림 데이터의 구조상의 이유이기 때문에, 또는 bConfigBitstreamRaw = 0 이기 (위해)때문에, 또는 해당하는 비디오 코딩 비트 스트림 구문 (H. 261 이나 H. 263 등)으로 f_code 파라미터가 필요없기 위해(때문에), 몇개의 f_code 값이 불요 또는 관계없는 경우는, 그 f_code 값은 0xF 가 아니면 안된다.

주 : MPEG-1 비트 스트림은, 이 정보를 다른 포맷으로 제공한다. 이 때문에, MPEG-1 비트 스트림의 경우는, f_code[0][0] 및 f_code[0][1] 은 MPEG-1 의 forward_f_code, f_code[1][0] 및 f_code[1][1] 은 MPEG-1 의 backward_f_code 와 같지 않으면 안 된다.

wBitstreamPCEelements : bConfigBitstreamRaw 가 "1" 의 경우, 이 파라미터에는, MPEG-2 비디오의 비트 스트림 디코드 처리에 필요한 일련의 플래그가 포함된다. bConfigBitstreamRaw 가 "0" 으로, 비 MPEG-2 비디오의 경우는, 이 파라미터는 사용되지 않고, 값은 "0" 이 아니면 안된다. 이 파라미터내의 비트는, 다음과 같이, MPEG-2 픽쳐 코딩 extension의 비트 스트림 요소와의 대응에 의해 정의된다.

비트 14 및 15 : IntraDCprecision = intra_dc_precision

비트 12 및 13 : AnotherPicStructure = picture_structure (bPicStructure 와 같지 않으면 안 된다)

비트 11 : TopFieldFirst = top_field_first

비트 10 : FrameDCTprediction = frame_pred_frame_dct

비트 9 : ConcealmentMVs = concealment_motion_vectors

비트 8 : QuantScaleType = q_scale_type

비트 7 : IntraVLCformat = intra_vlc_format

비트 6 : AlternateScan = alternate_scan

비트 5 : RepeatFirstField = repeat_first_field (가속기는 이것을 필요로 하지 않는다)

비트 4: Chroma420type = chroma_420_type (가속기에는 불필요하고, MPEG-2 에 의해 progressive_frame 와 동일한 값에 제한된다)

비트 3 : ProgressiveFrame = progressive_frame

비트 0, 1, 및 2 (LSB) : ReservedBits

bBitstreamConcealmentNeed : bConfigBitstreamRaw 가 "1" 의 경우, 비트 스트림 데이터에 에러가 포함되어 있을 가능성이 큰지 어떤지를 나타낸다. bConfigBitstreamRaw 가 "0" 의 경우는, 이 값은 "0" 이 아니면 안된다. 비디오 가속기는, 주어진 데이터의 내용에 관계없이, 크래쉬 하거나 록 업 하거나 하지 않게 설계될 필요가 있다. 그러나, 비디오 가속기가, 비트 스트림의 디코드 처리를 늦추는, 보다 복잡한 에러 은닉 알고리즘을 호출할 수 있도록(듯이) 할 필요가 있을지 어떨지를 결정할 때, 구문 에러의 가능성을 호스트가어느 평가하고 있는지를 인식하는 것은 도움이 된다. 이 파라미터에 사용할 수 있는 값은 다음대로 (이외의 값은 모두 예약되고 있다).

"0" : 비트 스트림의 구문 위에의 포맷에, 대량의 에러가 포함되어 있을 가능성이 낮은 일을 나타낸다.

"1" : 비트 스트림에 몇개의 에러가 포함되어 있을 가능성이 있지만, 그것들이 빈번하게 나타나지 않는 (1 시간에 1 ~ 2 회) 것을 나타낸다.

"2" : 비트 스트림에 에러가 포함되어 있어 유저의 사용 상황에 영향을 미치는 정도의 빈도로 발생할 가능성이 높고 (5 ~ 10 분에 몇개의 에러), 그러나 그러한 에러가 일정에는 존재하고 있지 않는 것을 나타낸다.

"3" : 비트 스트림에, 비교적 중대, 심각, 한편 빈번한 구문 포맷 에러가 포함되어 있는 것을 나타낸다 (1 분간에 1 회 이상).

bBitstreamConcealmentMethod : bConfigBitstreamRaw 가 "1" 의 경우, 추천 되는 에러 은닉 처리의 디폴트 방법을 나타낸다. bConfigBitstreamRaw 가 "0" 의 경우는,"0" 이 아니면 안된다. 이 파라미터에 사용할 수 있는 값은 다음대로 (이외의 값은 모두 예약되고 있다).

0 : 추천 되는 은닉 방법이 미지이다, 또는 지정되어 있지 않다.

1 : 추천 되는 은닉 방법은, 픽쳐내에서의, 공간 인트라 픽쳐 은닉의 사용이다.

2 : 추천 되는 은닉 방법은, 인터 픽쳐 은닉의 순서 방향 움직임 참조 픽쳐의 사용이다 (대응하는 역방향 움직임 참조 픽쳐보다 순서 방향 움직임 참조 픽쳐에 일시적으로 근처 되어 있는 P 픽쳐 또는 B 픽쳐내에서 가장 일반적으로 사용된다).

3 : 추천 되는 은닉 방법은, 인터 픽쳐 은닉의 역방향 움직임 참조 픽쳐의 사용이다 (대응하는 순서 방향 움직임 참조 픽쳐보다 역방향 움직임 참조 픽쳐에 일시적으로 근처 되어 있는 B 픽쳐내에서 가장 일반적으로 사용된다).

3.5. 5 픽쳐의 매크로 블록의 버퍼 구조

디코드된 픽쳐에 비트 스트림 데이터 버퍼가 포함되지 않은 경우는, 1 개(살) 또는 복수의 매크로 블록 제어 커멘드 버퍼가 포함되지 않으면 안 된다. 모든 매크로 블록의 디코드 처리는, 사용되는 각 타입의 버퍼내에서 1 번만 주소 되지 않으면 안 된다. 모든 매크로 블록 제어 커멘드 버퍼에 대해, 같은 매크로 블록세트를 가지는, 대응하는 IDCT 잔여 코딩 버퍼가 존재해야 한다. 1 개(살) 또는 복수의 블록 해제 필터 제어 버퍼가 송신되는 경우, 각 블록 해제 필터 제어 버퍼내의 매크로 블록 세트는, 대응하는 매크로 블록 제어 버퍼 및 IDCT 잔여 코딩 버퍼내의 매크로 블록 세트와 동일하지 않으면 안 된다.

픽쳐를 처리하려면 , 각 매크로 블록의 움직임 예측이, IDCT 잔여 데이터의 추가에 선행할 필요가 있다. 이것을 실행하려면 , 우선 움직여 예측 커멘드를 처리하고 나서, IDCT 잔여 코딩 커멘드의 처리중에, 이 데이터를 행선지 픽쳐 버퍼로부터 읽어 되돌리는지, 또는 이러한 2 개의 버퍼를, 통합해 처리한다 (결과를 행선지 픽쳐 버퍼에 기입하기 전에, 잔여 데이터를 예측에 추가한다). 각 매크로 블록의 움직임 예측 커멘드와 IDCT 잔여 코딩 커멘드는, 그 매크로 블록내의 직사각형 리젼에만 영향을 준다.

매크로 블록의 블록 해제 필터 커멘드는, 현재의 매크로 블록 위 및 왼쪽으로 인접하는 샘플의 2 행 2 열의 재구축 된 값, 및 현재의 매크로 블록내의 재구축 된 값을 읽어들이기 위한 액세스를 필요로 하는 경우가 있다. 그 결과, 현재의 매크로 블록 위 및 왼쪽으로 인접하는 샘플의, 1 행 1 열, 및 현재의 매크로 블록내의 최대 3 행 3 열이 수정되는 경우가 있다. 이 때문에, 특정의 매크로 블록의 필터 링 처리를 실행하기 위해서, 사전에 다른 매크로 블록의 재구축이 필요하게 되는 경우가 있다. 여기에서는, 2 개(살)이 다른 타입의 블록 해제 필터 버퍼가 정의되고 있다. 1) 현재의 버퍼의 밖에 있는 매크로 블록의, 재구축 된 샘플의 값에 대한 액세스 및 값의 수정을 필요로 하는 버퍼 타입 (bPicDeblockConfined 가 "0" 의 경우), 및 2) 그것들을 필요로 하지 않는 버퍼 타입 (bPicDeblockConfined 가 "1" 의 경우)이다. 1)의 타입의 블록 해제 커멘드 버퍼를 처리하려면 , 현재의 버퍼내에서 블록 해제 커멘드를 처리하기 전에, 현재의 버퍼의 매크로 블록의 왼쪽 및 위에 있는 매크로 블록에 영향을 주는 모든 버퍼의 재구축이 완료하고 있는 것을, 가속기가 확인할 필요가 있다. 2)의 타입을 처리하는 경우는, 현재의 버퍼내의 값이 사전에 재구축 되고 있으면 좋다. 블록 해제의 포스트프로세싱을 실시하려면 , 우선 버퍼 전체 또는 프레임에 대해서 움직여 예측과 IDCT 잔여 코딩 커멘드를 처리해, 다음에 몇개의 샘플의 값을 읽어 되돌려, 블록 해제 필터 처리의 결과로서 그것들을 수정하는지, 또는 블록 해제 커멘드 버퍼를, IDCT 잔여 코딩 버퍼와 통합해 처리한다 (최종 출력값을 행선지 픽쳐 버퍼에 기입하기 전에, 블록 해제를 실행한다). 블록 해제된 픽쳐의 행선지 픽쳐 버퍼는, 블록 해제전에 재구축 된 픽쳐의 버퍼와는 다른 경우가 있다. 이것은, 포스트프로세싱으로서 다음의 픽쳐의 예측에 사용되는 샘플값에 영향을 주지 않는 "루프외" 블록 해제를 지원 하기 위한(해)이다.

3.5. 5.1 매크로 블록 제어 커멘드

if (bPicIntra)
    NumMV = 0;
else if (PicOBMC) {
    NumMV = 10;
    if (bPicBinPB)
        NumMV++;
}
else {
    NumMV = 4;
    if (bPicBinPB && bPic4MVallowed)
        NumMV++;
}

DXVA_MB_Control {           // 16 바이트에 정렬

  // 일반 매크로 블록 정보
  wMBaddress                // 16b 어느 매크로 블록인가
  wMBtype                   // 16b 제어 비트
  MBskipsFollowing          //  8b

  // 잔차정보
  MBdataLocation            // 24b 버퍼내의 위치
  wPatternCode              // 16b 코드 된 블록

  if(bPicOverflowBlocks==1 &&
     IntraMacroblock==0){
    wPC_Overflow            // 16b wPatternCode 마다
    dwReservedBits2         // 32b
  }
  else if(HostResidDiff)
    ReservedBits3           // 48b
  else if (bChromaFormat == '01')
    for (i = 0; i < 6; i++)
        bNumCoef[i]               //  8b * 6 blocks = 48b
  else {
    wTotalNumCoef                 // 16b
    ReservedBits3                 // 32b
}

  if (bPicIntra ! = 0) {
  // 움직임 예측 정보
    for(i=0; i<NumMV; i++) {
        MVector[i]. horz    // 16b * NumMV 벡터
        MVector[i]. vert    // 16b * NumMV 벡터
    }
    if(bMV_RPS)
      for(i=0; i<NumMV; i++)
        bRefPicSelect[i]       //  8b * NumMV 벡터
        ReservedBits4                   //  16b 바이트 정렬
    }
  }

wMBaddress : 현재의 매크로 블록의 매크로 블록 주소를 라스터 스캔 순서로 지정한다 (0 은 좌상 매크로 블록의 주소, PicWidthInMBminus1 는 우상 매크로 블록의 주소, PicHeightInMBminus1 * PicWidthInMB 는 좌하 매크로 블록의 주소, PicHeightInMBminus1 * PicWidthInMB + PicWidthInMBminus1 는 우하 매크로 블록의 주소).

wMBtype : 처리되는 매크로 블록의 타입을 지정한다. 지정 방법은 다음대로.

  • 비트 15 : MvertFieldSel[3] (MSB)
  • 비트 14 : MvertFieldSel[2]
  • 비트 13 : MvertFieldSel[1]
  • 비트 12 : MvertFieldSel[0] : 매크로 블록 제어 커멘드내에서 후에 송신되는, 대응하는 움직임 벡터의 수직 필드 선택을 지정한다. 자세하게는 후술. 프레임 픽쳐 구조를 가지는 프레임 베이스의 움직임의 경우 (H. 261 및 H. 263 등), 이러한 비트는 모두 0 이 아니면 안된다. 이러한 비트의 사용은, MPEG-2 의 섹션 6.3. 17.2 로 대응하는 비트로 지정되고 있는 것과 같다.
  • 비트 11 : ReservedBits
  • 비트 10 : HostResidDiff : 현재의 매크로 블록의 오프 호스트 IDCT 를 위해서(때문에), 공간 영역잔차디코드가 끝난 블록이 송신될지 어떨지, 또는 변환계수가 송신될지 어떨지를 지정한다. bConfigResidDiffHost 가 "0" 이라면 "0". bConfigResidDiffAccerelator 가 "0" 이라면 "1" .
  • 비트 9 및 8 : MotionType : 픽쳐의 움직임 타입을 지정한다. 자세하게는 후술. 프레임 픽쳐 구조를 가지는 프레임 베이스의 움직임의 경우 (H. 261 등), 이러한 비트는 '10' (프레임 움직임)가 아니면 안된다. 이러한 비트의 사용은, 후의 표 1 에 정의되어 MPEG-2 의 섹션 6.3. 17.1, 겉(표) 6-17 및 6-18 에 있는 frame_motion_type 또는 field_motion_type 비트의 사용과 직접 대응한다 (MPEG-2 에 이러한 비트가 존재하는 경우).

  • 비트 7 및 6 : MBscanMethod : bPicScanFixed 가 "1" 의 경우는, bPicScanMethod 와 동일하지 않으면 안 된다. bConfigHostInverseScan = 0 의 경우, MBscanMethod 는 다음의 값이 아니면 안된다.
    • '00' = 지그재그 스캔 (MPEG-2 도 7-2)
    • '01' = 교호 수직 (MPEG-2 도 7-3)
    • '10' = 교호 수평 (H. 263 도 I. 2 파트 a)

    bConfigHostInverseScan = 1 의 경우, MBscanMethod 는 다음과 동일하지 않으면 안 된다.

    • '11' = 절대 계수 주소에 의한 임의 스캔
  • 비트 5 : FieldResidual : MPEG-2 로 지정되고 있도록(듯이), IDCT 블록이 필드 IDCT 구조를 사용할지 어떨지를 나타내는 플래그.
  • 비트 4 : H261LoopFilter : 현재의 매크로 블록 예측에 대해서 H. 261 루프 필터 (H. 261 의 섹션 3.2. 3)이 액티브한가 어떤가를 지정하는 플래그. H. 261 루프 필터는, H. 261 매크로 블록의 6 개 모든 블록에, (탭의 1 개가 블록외에 떨어지는 블록의 구석은 제외해) 수평에도 수직에도 적용되는, 분할 가능한 ¼,½,¼ 필터이다. 이러한 경우, 필터는 계수 0, 1, 0 을 가지도록(듯이) 변경된다. 2D 필터 처리의 출력시에, 8 비트 정수에의 둥근과 함께, 계산 위에의 완전한 정밀도가 보관 유지된다 (반정수 이상의 값은 말 수 있다).
  • 비트 3 : Motion4MV : H. 263 보유 F 및 J 로 사용되고 있도록(듯이), 순서 방향의 움직임이, 매크로 블록내의 4 개의 휘도 블록 각각 대해, 개별의 움직임 벡터를 사용하는 것을 나타내는 플래그. MotionForward 가 "0" 또는 bPic4MVallowed 가 "0" 의 경우는, Motion4MV 는 "0" 이 아니면 안된다.
  • 비트 2 : MotionBackward : MPEG-2 의 대응하는 macroblock_motion_backward 파라미터로 지정된 것처럼 사용되는 플래그. bPicBackwardPrediction 가 "0" 의 경우, MotionBackward shall 는 0 이 아니면 안된다. 이 플래그의 사용에 관한 자세한 것은 후술.
  • 비트 1 : MotionForward : MPEG-2 의 대응하는 macroblock_motion_forward 파라미터로 지정된 것처럼 사용되는 플래그. 이 플래그의 사용에 관한 자세한 것은 후술.
  • 비트 0 : IntraMacroblock : (LSB) 매크로 블록이 "인트라" 로서 코드 되어 현재의 매크로 블록에는 움직여 벡터가 사용되지 않는 것을 나타내는 플래그. MPEG-2 의 macroblock_intra 에 대응한다. 이 플래그의 사용에 관한 자세한 것은 후술.

MBskipsFollowing : 현재의 매크로 블록에 이어 생성되는,"스킵 되는 매크로 블록" 의 수를 지정한다. 스킵 되는 각 매크로 블록은, wMBaddress 의 값을 증가시켜, 그 후 같은 매크로 블록 제어 커멘드를 반복하는 것과 동등의 계산방법으로 생성되지 않으면 안 된다.

MBskipsFollowing 의 값이 "0" 이 아닌 매크로 블록 제어 커멘드는 모두, 스킵 되는 각 매크로 블록 마다 motion compensation 예측이 어떻게 실행될까에 관한 명시적인 지정을 포함해, 또 (MBskipsFollowing 의 값을 제외해), 스킵 되는 일련의 매크로 블록의 최초의 매크로 블록의 생성에 관한 명시적인 "비스킵" 지정과 동등하다. 이 때문에, MBskipsFollowing 가 "0" 이 아닌 경우는 항상, 다음의 파라미터가 모두 "0" 으로 동일하지 않으면 안 된다.

  • Motion4MV
  • IntraMacroblock
  • wPatternCode
  • wPCOverflow (존재하는 경우)
  • bNumCoef[i] (존재하는 경우)

게다가 후에 계속되는 스킵 되는 매크로 블록의 생성은, 픽쳐내의 매크로 블록의 새로운 행에의 "즉시" 를 포함하지 않게, 디코더에 의해 제한되지 않으면 안 된다. 즉, 매크로 블록의 각 행의 최초의 (그러나 최후일 필요는 없다) 매크로 블록을 생성하기 위해서, 개별의 매크로 블록 제어 커멘드가 송신될 필요가 있다.

주 :

  1. 이 상황에 있어서의, 스킵 되는 매크로 블록의 생성은, MPEG-2 의 섹션 7.6. 6 의 것과는 얼마인가 다르다. 이 사양에서는, 스킵 되는 매크로 블록이 생성되는 방법은, 선행하는 비스킵 매크로 블록 및 픽쳐의 타입으로부터 이끌리므로 없고, 개별의 매크로 블록 제어 커멘드내에서 지정된다 (예를 들어, MPEG-2 에서는, 스킵 되는 매크로 블록의 생성 방법은, 픽쳐가 P 픽쳐일까 B 픽쳐일까에 의존한다). 이 점을 명확하게 하기 위한(해), 다음과 같은 예를 준비했다. MPEG-2 비트 스트림으로, 매크로 블록 0 이 잔차로 코드 되어 매크로 블록 1 이 스킵 되어 매크로 블록 2 가 잔차로 코드 되어 매크로 블록 3, 4, 5 가 스킵 되어 매크로 블록 6 이 잔차로 코드 되고 있다고 한다. 이것들 7 개의 매크로 블록은, 적어도 5 개의 DirectX VA 매크로 블록 제어 커멘드의 생성을 필요로 한다. 최소한의 5 개의 제어 커멘드는, 다음과 같이 특징지울 수 있다.
    1. 최초의 커멘드는 wMBaddress = "0" 및 MBskipsFollowing = "0" 이 된다
    2. 2 번째의 커멘드는 wMBaddress = "1" 및 MBskipsFollowing = "0" 이 된다
    3. 3 번째의 커멘드는 wMBaddress = "2" 및 MBskipsFollowing = "0" 이 된다
    4. 4 번째의 커멘드는 wMBaddress = "3" 및 MBskipsFollowing = "2" 가 된다
    5. 5 번째의 커멘드는 wMBaddress = "6" 및 MBskipsFollowing = "0" 이 된다
  2. 상기로 지정한 것처럼, 다음의 조건이 필요하다.
    1. 스킵 되는 매크로 블록이 잔차를 보관 유지하고 있지 않다
    2. 스킵 되는 매크로 블록이, wMBaddress 를 증가시키면서 매크로 블록 제어 커멘드 처리를 반복하는 것에 의해 생성할 수 있다
    3. 매크로 블록의 스킵이, 매크로 블록의 새로운 행에 되풀이하지 않게 제한되고 있다
  3. 주 2 에 든 3 개의 조건에 의해, 같은 매크로 블록 제어 처리의 MBskipsFollowing+1 반복은 아니고, 휘도 성분의 MacroblockWidth·(MBskipsFollowing+1)와 같은 폭을 가지는 직사각형 ( 및과 같이 지정된 색광도 성분의 직사각형)에의 지정된 움직임 벡터의 적용으로서 가속기가 실제로 motion compensation를 실현할 수 있다 (Motion4MV 가 "0" 의 경우).
  4. 고도 예측 모드 (보유 F)가 유효가 되고 있는 H. 263 으로 스킵과 나타난 매크로 블록을 생성하는 경우, 그러한 매크로 블록내에서 OBMC 효과를 지정하려면 , 이 사양을 사용해, 몇개의 "스킵 된" 매크로 블록을 비스킵 매크로 블록으로서 코딩 할 필요가 있다.

MBdataLocation : IDCT 잔여 코딩 블록 데이터 버퍼에의 인덱스. 현재의 매크로 블록내의 블록의 잔차데이터 위치를, 32 비트의 배수로 가리킨다. 매크로 블록 제어 커멘드 버퍼의 최초의 매크로 블록의 경우는,"0" 이 아니면 안된다.

wPatternCode : 호스트 베이스잔차디코드를 사용하는 경우, wPatternCode (비트 0 이 LSB)의 비트 11-i 는, 블록 i 의 잔차블록이 송신될지 어떨지를 나타낸다. 여기서, i 는, 그림 6-10,6-11, 및 6-12 으로 지정된 매크로 블록내의 블록의 인덱스이다 (라스터 스캔순서의 Y, 라스터 스캔순서의 Cb 의 4:2:0 블록, Cr 의 4:2:0 블록, Cb 의 4:2:2 블록, Cr 의 4:2:2 블록, Cb 의 4:4:4 블록, Cr 의 4:4:4 블록의 순서). 코드 된 블록의 데이터 (비트 11-i 가 1 인 블록)는, 같은 인덱스 순서 (증분 i)의 잔여 코딩 버퍼에 있다. 4:2:0 MPEG-2 데이터의 경우, wPatternCode 의 값은, 디코드된 CBP 의 값을 왼쪽으로 6 비트 위치 쉬프트 한 것에 대응한다 (이러한 하위 비트 위치는,4:2:2 및 4:4:4 크로마포맛트로 사용된다).

bConfigSpatialResidInterleaved 가 "1" 의 경우, 호스트 베이스의 잔차는, 사용되고 있는 YUV 픽셀 포맷에 일치하는 크로마인타리브포맛트로 송신된다. 이 경우, Cb 및 공간적으로 대응하는 Cr 의 블록의 각 조는, 단일의 잔차데이터 구조 단위로서 다루어진다. 이것에 의해 wPatternCode 의 값이나 의미가 변경될 것은 없지만, Cb 및 Cr 데이터 블록의 어느 쪽인지가 wPatternCode 에 대응하는 비트 세트를 가지고 있으면, 이러한 데이터 블록의 각 조의 양쪽 모두의 멤버가 항상 송신되는 것을 의미한다. 특정의 데이터 블록의 wPatternCode 의 비트가 0 의 경우, 이 조가, wPatternCode 비트가 0 인 블록의 잔차데이터 블록의 송신을 필요로 할 때는 항상, 대응하는 잔차데이터값이 0 으로서 송신되지 않으면 안 된다.

wPC_Overflow : bPicOverflowBlocks 가 1, IntraMacroblock 가 0 (8-8 오버플로우 방식)으로 호스트 베이스의 잔차디코드를 사용하는 경우, wPC_Overflow 에는, wPatternCode 와 같은 방법으로 지정된 오버플로우 블록의 패턴 코드가 포함된다. 코드 된 오버플로우 블록의 데이터 (비트 11-i 가 1 인 블록)는, 같은 인덱스 순서 (증분 i)의 잔여 코딩 버퍼에 있다.

bNumCoef[i] : 매크로 블록의 각 블록 i 의, 잔여 코딩 블록 데이터 버퍼내의 계수의 수를 나타낸다. 여기서, i 는, MPEG-2 의 그림 6-10,6-11, 및 6-12 으로 지정된 매크로 블록내의 블록의 인덱스이다(Y 의 라스터 스캔순서, Cb 에 계속되는, Cr 에 계속된다). HostResidDiff 가 "0" 으로 bChromaFormat 가 '01' (4:2:0) 때 마셔 사용된다. (4:2:2 인가 4:2:0 포맷으로 사용되면(자), 전형적인 매크로 블록 컨트롤 커멘드의 사이즈가 증가해, 크리티컬 메모리 할당 경계를 넘어 버린다, 그 때문에 비 4:2:0 의 경우 각 블록의 계수의 수를 결정하는데 EOB 만이 사용된다. ) 이러한 계수의 데이터는 같은 순서의 잔차버퍼내에 있다.

wTotalNumCoef: 전매크로 블록의 잔차데이터 버퍼내의 계수의 전수를 나타낸다. HostResidDiff 가 "0" 또한 bChromaFormat 가 '01'이외 때 (4:2:0) 마셔 사용된다.

MVector[i]. horz, MVector[i]. vert : 수평 방향 및 수직 방향의 움직임 벡터의 값을 지정한다. 이것들 2 개의 값을 2 차원에 통합한 값은, MVvalue[i] 로 불린다. 각 움직임 벡터의 각방향에는, 하프 샘플 단위의 부호 첨부 정수 움직임 오프셋(offset)가 포함된다. bMVprecisionAndChromaRelation 가 '10' (정수 샘플 오프셋(offset)만을 지원 하고 있는 H. 261 포맷의 움직임)의 경우는, 어느 쪽의 요소도 짝수가 아니면 안된다.

bRefPicSelect[i] : 움직임 벡터 참조 픽쳐 선택이 사용중의 경우는, MVvalue[i] 의 예측에 사용되는 참조 픽쳐 버퍼를 지정한다.

IntraMacroblock, MotionForward, MotionBackward, PicMotionType, MvertFieldSel, 및 MVector[i] 의 유효한 편성을, 아래의 표 1 에 나타낸다. 표내에서 지정된 값은, H261LoopFilter, Motion4MV, 및 bPicOBMC 가 모두 0 인 것을 전제로 하고 있다.

표 1 - 각종 움직임 타입에 있어서의 매크로 블록 파라미터의 사용

IntraMacroblock, MotionForward, MotionBackward | MotionType (의의는 픽쳐 타입에 의한다) | MVector[0] MvertFieldSel[0] (1st, dir1) | MVector[1] MvertFieldSel[1] (1st, dir2) | MVector[2] MvertFieldSel[2] (2nd, dir1) | MVector[3] MvertFieldSel[3] (2nd, dir2)
프레임 구조화 픽쳐 (bPicStructure = '11')
1,0,0 (intra) | '00' (intra) | - - | - - | - - | - -
0,0,0 (no motion) | '10' (no motion) | 0 - | - - | - - | - -
0,1,0 | '10' (frame MC) | PMV[0][0] - | - - | - - | - -
0,0,1 | '10' (frame MC) | - - | PMV[0][1] - | - - | - -
0,1,1 | '10' (frame MC) | PMV[0][0] - | PMV[0][1] - | - - | - -
0,1,0 | '01' (field MC) | PMV[0][0] sel[0][0] | - - | PMV[1][0] sel[1][0] | - -
0,0,1 | '01' (field MC) | - - | PMV[0][1] sel[0][1] | - - | PMV[1][1] sel[1][1]
0,1,1 | '01' (field MC) | PMV[0][0] sel[0][0] | PMV[0][1] sel[0][1] | PMV[1][0] sel[1][0] | PMV[1][1] sel[1][1]
0,1,0 | '11' (dual-prime) | PMV[0][0] 0 (top) | vector'[2][0][0], vector'[2][0][1]<<1 1 (bot) | PMV[0][0] 1 | vector'[3][0][0], vector'[3][0][1]<<1 0
필드 구조화 픽쳐 (bPicStructure == '01' or '10')
1,0,0 (intra) | '00' (intra) | - - | - - | - - | - -
0,0,0 (no motion) | '01' (no motion) | 0 PicCurrentField | - - | - - | - -
0,1,0 | '01' (field MC) | PMV[0][0] sel[0][0] | - - | - - | - -
0,0,1 | '01' (field MC) | - - | PMV[0][1] sel[0][1] | - - | - -
0,1,1 | '01' (field MC) | PMV[0][0] sel[0][0] | PMV[0][1] sel[0][1] | - - | - -
0,1,0 | '10' (16×8 MC) | PMV[0][0] sel[0][0] | - - | PMV[1][0] sel[1][0] | - -
0,0,1 | '10' (16×8 MC) | - - | PMV[0][1] sel[0][1] | - - | PMV[1][1] sel[1][1]
0,1,1 | '10' (16×8 MC) | PMV[0][0] sel[0][0] | PMV[0][1] sel[0][1] | PMV[1][0] sel[1][0] | PMV[1][1] sel[1][1]
0,1,0 | '11' (dual-prime) | PMV[0][0] PicCurrentField | vector'[2][0] ! PicCurrentField | - - | - -

주 :

  1. 이 표는 매우 중요하다. 잘 검토해 완전하게 이해할 필요가 있다. 경험상, 표내의 이용되는 모든 매크로 블록 타입 (특히 필드 구조화 픽쳐 또는 듀얼 프라임 움직임)에 적절한 대응을 하고 있지 않는 모든 이행에는, 버그가 포함되어 있다고 생각된다.
  2. 위에의표에, 생의 움직임 벡터값이 아니고 값 PMV 가 사용되고 있는 개소가 있다. 이것은, 프레임 좌표내에 있는 PMV 를, (하프 수직 해상도의) 필드 좌표에 있을 가능성이 있는 움직임 벡터와 구별하기 위해(때문에)이다. 위와 같은 PMV 는 모두, 현재의 움직임 벡터로 갱신한 후의 PMV 값을 의미한다.
  3. vector'[2][0] 으로 vecotor'[3][0] 의 정의는 MPEG-2 섹션 7.6. 3.6 에 있다. 쉬프트 조작은 수직 컴퍼넌트가 프레임 좌표에 수정되는 것을 나타낸다.
  4. 위에의 "움직여 없음" (0,0,0)의 양케이스에서는, 매크로 블록 파라미터가, 움직임 벡터의 값이 0 의 순서 방향 예측 매크로 블록 (0,1,0)을 에뮤레이트 한다 (MPEG-2 섹션 7.6. 3.5 를 참조).

이 다른 가능한 편성은 다음대로.

H261LoopFilter == 1 && bPicOBMC == 0 && Motion4MV == 0 : 순서 방향 움직임 벡터의 1 개가 MVector[0] 에 송신되어 매크로 블록의 순서 방향 예측에 대해서, H. 261 의 섹션 3.2. 3 으로 지정된 H. 261 루프 필터가 액티브한 것을 나타낸다. 이 경우, MotionForward 는 1, IntraMacroblock 와 MotionBackward 의 양쪽 모두는 "0" 이 아니면 안된다.

bPicOBMC == 0 && Motion4MV == 1 : 4 개의 순서 방향 움직임 벡터가 MVector[0, 1, 2, 3] 에 송신되는 것을 나타낸다. 이 경우, MotionForward 가 1, IntraMacroblock 가 "0" 이 아니면 안된다. MotionBackward 가 "1" 의 경우, 5 번째의 움직임 벡터가 역방향 예측을 위해서(때문에) MVector[4] 에 송신된다.

bPicOBMC == 1 && Motion4MV == 0 : 10 개의 순서 방향 움직임 벡터가 OBMC 의 움직임 지정을 위해서(때문에) MVector[0, 1, 2, ..., 9] 에 송신되어 이것들 움직임 벡터의 최초의 4 개의 값이 모두 같은 것을 나타낸다. MotionBackward 가 "1" 의 경우, 11 번째의 움직임 벡터가 역방향 예측을 위해서(때문에) MVector[10] 에 송신된다.

bPicOBMC == 1 && Motion4MV == 1 : 10 개의 순서 방향 움직임 벡터가 OBMC 움직임의 지정을 위해서(때문에) MVvalue[0, 1, 2, ..., 9] 에 송신되어 이것들 움직임 벡터의 최초의 4 개의 값이 모두 다를 가능성이 있는 것을 나타낸다. MotionBackward 가 1 의 경우, 11 번째의 움직임 벡터가 역방향 예측을 위해서(때문에) MVvalue[10] 에 송신된다.

주 : H. 263 표준 규격의 현재의 구성에서는, bPicOBMC == 1, Motion4MV == 1, MotionBackward == 1 이라고 하는 편성은 사용되지 않는다.

PB 내의 H. 263 의 OBMC, 4 MV, B, EP, B 간의 관련에 대한 몇개의 자세한 것은 유효하겠지 :
a) OBMC 는 H. 263 B 혹은 EP 픽쳐내에서는 사용할 수 없다 (H. 263 섹션 5.1. 4.5 제 2 항).
b) OBMC 는 H. 263 PB 픽쳐의 B 파트내에서는 사용할 수 없다 (H. 263 섹션 F. 1 제 1 단락).
c) 4MV 는 H. 263 B 혹은 EP 픽쳐내에는 보낼 수가 없다 (구문 다이어그램의 MVFW 와 MVBW 1 개(살)만, H. 263 표 O. 1 으로 O. 2 내의 4MV 매크로 블록 타입은 없다).
d) H. 263 B 픽쳐의 "직접"예측의 상세한 참조 매크로 블록으로서 사용되는 H. 263 P 픽쳐의 매크로 블록으로 4MV 가 사용된다면, OBMC 는 직접 예측에는 사용되지 않는, 왜냐하면 4 개의 모션 벡터가 H. 263 Annex M 에 따라 사용되기 때문인, 이것은 OBMC 를 적용하지 않는 H. 263 Annex G 와 같이 그것을 이용한다 (H. 263 섹션 O. 4 제 2 단락과 제 2 항목). 그러므로, H. 263 은 OBMC 도 역예측도 동시에는 요구하지 않는, 그리고 역방향에도 4MV 를 사용하지 않는다.

주 : MPEG-1, MPEG-2 하프 샘플 예측 필터 링, 쌍방향 평균화, 및 듀얼 프라임의 동패리티와 역패리티의 편성의 머지않아냄새나도, 평균 연산자는 산술적으로는 같다 ((s1+s2)//2)이다. 이 연산자는, C 언어의 식 (s1+s2+1) >>1 와 같다. H. 263 쌍방향 평균화 연산자는, 다운 쉬프트에 선행해 "+1" 오프셋(offset)로 배정 하지 않는다. bBidirectionalAveragingMode 파라미터는, 이러한 어느 방법을 사용할까를 결정한다.

3.5. 5.2 역양자화, IDCT 전포화, 미스매치 제어, 인트라 DC오프셋(offset), IDCT, 픽쳐 재구축, 및 재구축 클리핑

이 인터페이스는, IDCT 처리를 위한, 3 개의 하위 레벨의 방법을 지원 한다. 어느 경우에서도, 기본적인 역양자화 처리, IDCT 전의 범위 포화, MPEG-2 미스매치 제어 (필요에 따라서), 및 인트라 DC 오프셋(offset) (필요에 따라서)는 호스트측에서 실행되어 최종적인 픽쳐의 재구축 및 재구축 클리핑은 가속기측에서 실행된다. 최초의 방법은, 변환계수의 매크로 블록을, 외부의 IDCT, 픽쳐 재구축, 및 재구축 클리핑을 위해서(때문에) 가속기에 건네주는 것이다. 2 번째와 3 번째의 방법에서는, IDCT 를 호스트상에서 실행해, 외부의 픽쳐 재구축 및 재구축 클리핑을 위해서(때문에) 공간 영역 결과의 블록을 건네준다.

역양자화, IDCT 전포화, 미스매치 제어, 인트라 DC 오프셋(offset), IDCT, 픽쳐의 재구축, 및 재구축 클리핑의 처리는, 다음과 같이 정의된다.

  1. 엔트로피 코드화 된 양자화 인덱스로부터, 일련의 IDCT 계수값 [image] 을 생성 하기 위해서, 필요에 따라서 역양자화 (역양자화 중요 행렬의 적용을 포함한다)를 실행한다 (호스트에 의해 실행).
  2. 제한된 범위내의 값 [image] 을 취득하기 위해서, 변환계수 블록의, 재구축 된 각 계수값 [image] 을 포화시킨다 (호스트에 의해 실행).

  3. 미스매치 제어 (MPEG-2 에만 필요해, 호스트에 의해 실행으로서 설명한다)는, 매크로 블록내의 모든 계수의 포화값을 가산하는 것에 의해 실행된다 (LSB 모든 XOR 와 동등). 합계가 짝수가 되었을 경우는, [image] 이 홀수라면 1 을 빼, [image] 가 짝수라면 1 을 더하는 것으로 (LSB 의 변환과 동등), 마지막 계수의 포화값 [image] 을 수정해야 한다. (합계가 홀수가 되었을 경우는, [image] 의 포화값이 그대로 사용된다. ) 포화 및 미스매치 제어 후의 계수값은, 여기서, [image] 로서 나타내진다.
  4. 주: MPEG-1 는 미스매치 제어에 다른 폼을 가지는, 이것은 그렇게 하지 않으면 역양자화 후우수가 되는 각 계수에 1 을 더하는 혹은 당기는 것으로 값을 바꾸는 것에 의해 구성된다. H. 263 은 개개로 기술되고 있는 의미에서의 미스매치 제어를 요구하지 않는다. 언제라도, 적용 가능하면, 미스매치 제어는 호스트의 책임이다.
  5. 필요에 따라서 인트라 DC 오프셋(offset)를 추가한다 (호스트에 의해 실행). 이것은, 공간 참조 예측값 2(BPP-1) 에의 차이의 추가에 모든 인트라 블록을 대응시키기 때문에 있다. 이러한 오프셋(offset)는, HostResidDiff 가 "1" 또한 bConfigIntraResidUnsigned 가 "1" 때, 모든 참조 비디오 코딩 표준 규격 (H. 261&3 및 MPEG-1&2&4)로 필요하고, 어느 경우에서도 [image] 라고 하는 값을 가진다 (값은, BPP>8 가 허가되는 MPEG-4 이외에서는 모두 1024 가 된다).
  6. 단일의 분할 가능한 변환을 실행한다 (호스트 또는 가속기에 의해 실행).

    각 기호의 의미 :

    C(u)는,u = 0 의 경우는 1, 그 이외의 경우는

    C(v)는,v = 0 의 경우는 1, 그 이외의 경우는

    x 및 y 는, 픽셀 영역내의 수평 및 수직 공간 좌표

    u 및 v 는, 변환 영역의 수평 및 수직 주파수 좌표

    WT 및 HT 는, 변환 블록의 폭 및 높이 (보통은 어느쪽이나 8)

    주 : 이 IDCT 처리의 정밀도는, H. 261&3 및 MPEG-1&2&4 비디오 코딩 표준 규격으로 요구되는 것 (거의 같이)에 준거해야 한다.

  7. 픽쳐의 재구축을 실시하기 (위해)때문에, 공간 영역 잔여 정보를, 비인트라 블록의 경우는 motion compensation 예측값에, 인트라 블록의 경우는 정수 참조값에 추가하는 (이 정수는 HostResidDiff 가 "1" 또한 bConfigIntraResidUnsigned 가 "1" 때 이외는 2(BPP-1) 인, 전술의 경우는 "0").
  8. 픽쳐 재구축을, 최종 결과의 픽쳐 샘플값으로서 보관하기 위해서,[0, (2BPP)-1] 의 범위에 클리핑 한다 (가속기상에서 실행).

3.5. 5.2. 1 오프 호스트의 IDCT

오프 호스트 IDCT 처리를 위한, 매크로 블록 IDCT 계수 데이터의 전송에는, 인덱스의 버퍼와 값의 정보가 포함된다. 인덱스 정보는 16 비트 워드로서 송신되고 (다만 8×8 변환 블록에 정말로 필요한 것은 6 비트만), 변환계수값정보는 부호 첨부 16 비트 워드로서 송신된다 (다만 보통의 8×8 변환 블록의 경우로 BPP=8 의 경우는, 필요한 것은 12 비트만).

변환계수는, DXVA_TCoefSingle 또는 DXVA_TCoef4Group 의 어느 쪽인가의 데이터 구조체로 송신된다. bConfig4GroupedCoefs 가 "0" 의 경우, 계수는 DXVA_TCoefSingle 구조체를 사용해 따로 따로 송신된다. bConfig4GroupedCoefs 가 "1" 의 경우, 계수는 DXVA_TCoef4Group 구조체를 사용해 4 개(살)씩 송신된다. 이것들 양자택일의 데이터 구조체에는, 이하에 정의하는 2 개(살)이 닮은 기본 요소가 포함된다.

TCoefIDX : bConfigHostInverseScan 로부터 결정되었던 대로, 블록내의 계수의 인덱스를 지정한다. TCoefIDX 의 사용에는, 다음의 기본적인 2 개의 방법이 있다.

  1. RLE (Run-length) 순서 : bConfigHostInverseScan 가 "0" 의 경우, MBscanMethod 는, 지그재그, 교호 수직, 또는 교호 수평역스캔을 나타낸다. 이 경우, TCoefIDX 에는, 지정된 스캔 순서로 현재의 계수에 선행해, 블록에 마지막에 보내진 계수에 계속되는 (선행하는 계수가 없으면 블록 선두로부터의), 값 0 의 계수의 수가 포함된다.
  2. 임의의 순서 : bConfigHostInverseScan 가 "1" 의 경우, MBscanMethod 는 임의의 순서를 나타낸다. 이 경우, TCoefIDX 에는, 블록내의 계수의 라스터 인덱스만이 포함된다 (즉, TCoefIDX = u + v·WT).

TCoefIDX 는,WT·HT 이상이 되면 안된다.

TCoefValue : 블록내의 계수의 값. TCoefValue 는, 계수값을 역 DCT 처리를 위해서(때문에) 가속기에 건네주기 전에, 전술의 섹션 3.4. 2 로 가리킨 것처럼, 호스트측에서 적절한 범위에 클립 해야 한다. 필요에 따라서, MPEG-2 미스매치 제어도, 가속기가 아니고 호스트에 의해 실행된다 (이 때문에, 0 이 아닌 여분의 "유령" 계수의 생성이 필요하게 되는 경우가 있다).

3.5. 5.2. 1.1 단일 계수의 데이터 포맷

DXVA_TCoefSingle 데이터 구조체는, bConfig4GroupedCoefs 가 "0" 의 경우에 반드시 사용되어 다음과 같이 정의된다.

DXVA_TCoefSingle {
  TCoefIDX        15 /* 8×8 에 정말로 필요한 것은 6 마셔 */
  TCoefEOB         1
  TCoefValue    16 /* 호스트상에서 포화 */
}

TCoefEOB : 현재의 변환계수가, 계수의 현재의 블록에 관련지을 수 있던 마지막 계수인가 어떤가를 나타낸다. 값 "1" 은, 현재의 계수가 블록의 마지막 1 개(살)인 것을 나타낸다. 값 "0" 은, 그렇지 않은 것을 나타낸다.

3.5. 5.2. 1.2 그룹화 된 4 계수의 데이터 포맷

DXVA_TCoef4Group 데이터 구조체는, bConfig4GroupedCoefs 가 "1", bConfigHostInverseScan 가 "0" 의 경우에만 사용되어 다음과 같이 정의된다.

DXVA_TCoef4Group {
  TCoefIDX[4]    4*8  /* 8x8 에 정말로 필요한 것은 6 마셔 */
  TCoefValue[4]  4*16
}

DXVA_TCoef4Group 데이터 구조체에서는, 그룹화 된 4 개의 변환계수가, RLE (Run-length) 값과 함께 일괄 송신된다. DXVA_TCoef4Group 내의 각 배열의i 번째의 요소에는 실제의 것의 계수나 실행장 리스트의 요소 3-i 가 들어간다 (그러므로, 최초의 계수 혹은 인덱스는 요소 3 이 되는, 요소 2 에 다음...). 송신해야 할 0 이 아닌 계수의 수 NC 가 4 보다 적은 경우, i=NC ~ 3 에 대해, TCoefIDX[i] 는 63 (16진의 0x3F), TCoefValue[i] 는 TCoefValue[NC-1] 이 아니면 안된다.

3.5. 5.2. 2 호스트 베이스의 IDCT

IDCT 는 호스트상에서 실행할 수도 있다. 이 경우, 결과는 API 를 사용해 건네받는다. 결과 송신의 스킴으로서는, 16 비트와 8-8 오버플로우의 2 개의 방법이 지원 된다. 어느 쪽이 사용될까는, bConfigSpatialResid8 에 나타난다.

3.5. 5.2. 2.1 16 비트 방식

16 비트 방식을 사용해 16 비트 데이터를 송신하는 경우는, 데이터의 블록은 연속적으로 송신된다. 공간 영역 데이터의 각 블록은,DXVA_Sample16 의 WT·HT 값으로 구성된다.

A DXVA_Sample16 는 16 비트의 부호 첨부 정수이다. BPP 가 "8" 보다 큰 경우는, 16 비트 방식만을 사용할 수 있다. bPicIntra 가 "1" 으로 BPP 가 "8" 의 경우는, 16 비트 방식은 사용할 수 없다. IntraMacroblock 가 "0" 이라면, 16 비트 샘플은 모션 압축된 예측값에 관한 부호 첨부가 수라고 해 보내진다. IntraMacroblock 가 "1" 이라면, 16 비트 샘플은 이하와 같이 보내진다 :

  • bConfigIntraResidUnsigned 가 "1" 이라면, 샘플은 "0" 의 일정 참조값에 관한 부호 없음이 수라고 해 보내진다.
  • bConfigIntraResidUnsigned 가 "0" 이라면, 샘플은 2(BPP-1) 의 일정 참조값에 관한 부호 없음이 수라고 해 보내진다.

데이터의 블록은, MSB 로부터 LSB 에 1 밸류 비트의 스캔에 의해 지정된 wPatternCode 순서에, 시퀀셜에 보내진다.

주 :

  1. bConfigSpatialHost8or9Clipping 가 "1" 이 아닌 한, 호스트상에서 이러한 값의 클리핑을 했다고 볼 수 없다. 공간 영역 차이 데이터를 적절히 표현하려면 BPP+1 비트 범위에서 충분하지만, 클립되어 있지 않은 경우, 일부의 IDCT 에서는 이 범위를 넘는 수치가 출력될 가능성이 있다. 가속기는, 적어도 15 비트 범위의 값으로 올바르게 동작해야 한다.
  2. 비디오 코딩 표준 규격에서는 보통, 차이값을 예측값에 추가하기 전에, 차이값의 클리핑이 지정되는 (1 샘플 8 비트의 비디오로, 9 비트의 클리핑등)가, 이것은 디코드된 출력 픽쳐에 어떤 영향도 주지 않기 때문에, 이 클리핑은 실제로는 필요없다. 이 때문에, bConfigSpatialHost8or9Clipping 가 "1" 으로 설정되는 것에 의해 가속기 하드웨어가 클리핑을 필요로 하고 있는 것이 분명한 경우 이외는, 클리핑이 여기서 발생 하면 가정하지 않는다.

3.5. 5.2. 2.2 8-8 오버플로우 방식

BPP가 "8" 의 경우는, 8 비트 차이 방식을 사용할 수 있다. bPicIntra 가 "1" 으로 BPP 가 "8" 의 경우는, 이 방식을 사용할 필요가 있다. 그 경우, 각 공간 영역 차이값은, 8 비트만을 사용해 표현된다. 이 경우, 각 공간 영역 차분값은 8 비트만을 사용해 표현된다. 8 비트 메소드를 사용해 데이터를 보낼 때, 8 비트 데이터의 블록은 시퀀셜에 보내진다. 8 비트 공간 영역잔차데이터의 각 블록은 DXVA_Sample8 의 WTxHT 값으로부터 구성된다.

IntraMacroblock 가 1 의 경우는, 8 비트 샘플은 모션 압축 예측에 응해 가산 혹은 감산 (bConfigResid8Subtraction 와 샘플이 최초의 패스 블록과 오버플로우 블록의 어느 쪽에 있을까에 의해 결정)되는 부호 첨부 차이이다. IntraMacroblock 가 0 으로 블록내가 있는 픽셀을 표현하는 차이가 8 비트를 사용하는 표현에 있어 너무 크다면, 샘플의 2 번째의"오버플로우" 블록이 보내지고 얻는다.

IntraMacroblock 가 "1" 이라면, 8 비트 샘플은 다음과 같이 설정된다 :

  • bConfigIntraResidUnsigned 가 "1" 이라면, 8 비트 샘플은 일정 참조값 "0" 에 응한 부호 없음이 수라고 해 보내진다.
  • bConfigIntraResidUnsigned 가 "0" 이라면, 8 비트 샘플은 일정 참조값 2(BPP-1) 에 응한 부호 첨부가 수라고 해 보내진다.
IntraMacroblock 가 "1" 이라면, 오버플로우 블록은 보내져서는 안된다.

데이터의 블록은, MSB 로부터 LSB 에 1 밸류 비트의 스캔에 의해 지정된 wPatternCode 순서에, 시퀀셜에 보내져 다음에 모든 필요한 8 비트 오버플로우 블록이 wPC_Overflow 로 지정되었다고 해서 보내진다. bConfigResid8Subtraction 가 "1" 이라면, 이러한 오버플로우 블록은 가산은 아니고 감산된다.

각 비인트라 매크로 블록의 8 비트 차이의 최초의 패스가 추가된다. bPicOverflowBlocks 가 "0" 혹은 IntraMacroblock 가 "1" 이라면, 2 번째의 패스는 없다. bPicOverflowBlocks 가 "1", IntraMacroblock 가 "0" 으로, bConfigResid8Subtraction 가 "1" 이라면, 각 비인트라 매크로 블록의 8 비트 차이의 2 번째의 패스가 추가된다.

원의 8 비트 블록 및 대응하는 8 비트 오버플로우 블록의 양쪽 모두로, 몇개의 샘플이 0 이 아닌 경우, 다음과 같이 된다.

  • bConfigResid8Subtraction 가 "0" 의 경우, 샘플의 부호는 양쪽 모두의 블록으로 동일하지 않으면 안 된다.
  • bConfigResid8Subtraction 가 "1" 의 경우, 원의 8 비트 블록의 샘플은, 대응하는 8 비트 오버플로우 블록의 샘플의 부정과 부호가 일치해야 한다.

이것에 의해, 2 살의 패스의 각각의 후에, 결과의 8 비트 클리핑과 함께, 샘플을 예측 픽쳐에 추가할 수 있다.

주 : IntraMacroblock 가 0 의 경우, 비디오 코딩 표준 규격에 엄밀하게 준거하지 않게 되므로,8+8 방식으로는 +255 의 잔차값을 표현할 수 없다. 그러나, 여기에서는 이 포맷은 지원 되고 있다. 그 이유는, 이 포맷이, 1) 몇개의 기존의 이행으로 사용되고 있는, 2) 픽쳐를 표현하기 위해서 필요한 데이터량이라고 하는 점으로써 효율적인, 3) 보통은 비디오 품질을 의미가 있게 악화시키는 결과가 되지 않는다고 생각된다, 라고 하는 이유에 의한다.

3.5. 5.3 블록 해제 필터 제어

블록 해제 필터 제어 커멘드가 존재하는 경우, 이 커멘드는, 매크로 블록내의 각 휘도 블록에 대해서 송신되어 색광도 블록의 각 조에 대해서 1 번씩 송신된다. 커멘드는, 매크로 블록내의 라스터 스캔 순서로 송신된다. 색광도의 블록의 전에 휘도의 모든 블록이 송신되어 다음에, 색광도 4:2:0 커멘드 1 개(살), 필요에 따라서 색광도 4:2:2 커멘드 1 개(살), 다음에 필요에 따라서 색광도 4:4:4 커멘드 2 개(살)로 계속된다 (양쪽 모두의 색광도 성분에 같은 필터 링이 적용된다). 각 블록의 필터 링은, 상단에 걸쳐 나타나는 블록 해제의 사양, 및 거기에 계속되는, 좌단에 걸쳐 나타나는 블록 해제의 사양에 의해 지정된다. 색광도의 블록 해제는 한 번만 지정되어 Cb 성분과 Cr 성분의 양쪽 모두에 같은 블록 해제 커멘드가 사용된다. 예를 들어,4:2:0 데이터를 포함한 16x16 의 매크로 블록을, 8x8 블록을 사용해 블록 해제하는 경우, 휘도 블록용으로 상하 2 개의 엣지 필터 링 커멘드를 4 세트 송신해, 다음에 색광도용으로 2 개의 엣지 필터 링 커멘드 1 세트를 송신하는 것에 의해 지정한다. 각 블록 해제 엣지의 지정의 데이터 구조는 다음대로.

DXVA_DeblockingEdgeControl {
    EdgeFilterStrength    7 /* H. 263 에서는 4b 마셔 필요 */
    EdgeFilterOn        1
}

EdgeFilterStrength : 이 파라미터는, H. 263 보유 J 로 지정된, 실행되는 필터 링의 강도를 지정한다.

EdgeFilterOn : 이 플래그는, 엣지가 필터 되는 경우는 1 이 되어, 그 이외의 경우는 "0" 이 아니면 안된다.

EdgeFilterOn 가 "1" 으로 동일한 엣지에 대한 실제의 엣지 필터 링은, H. 263 보유 J 로 지정되고 있도록(듯이), EdgeFilterStrength 로 지정된 값으로, 범위 [0, (2BPP)-1] 에의 출력시의 클리핑을 수반해, 정확하게 실행되지 않으면 안 된다. H. 263 보유 J 로 지정되고 있도록(듯이), 모든 블록의 모든 상 엣지 필터 링은, 어느 블록의 어느 왼쪽 엣지 필터 링보다 "먼저" 실행되지 않으면 안 된다 (상 엣지 필터 링에 사용되는 샘플의 값은, 왼쪽 엣지 필터 링의 어느 블록 해제 필터보다 먼저 재구축 된 값이 아니면 안된다고 하는 의미에 대해).

현재의 블록 해제 필터 커멘드 버퍼의 밖에 있는 매크로 블록의 샘플값이 영향을 받지 않는 것이, 버퍼 타입에 의해 나타나고 있는 경우는, 버퍼내에 블록 해제 필터 커멘드를 가지는 매크로 블록이 담당하는 리젼의 왼쪽 및 위에의 모든 엣지에 대해서, EdgeFilterOn 파라미터는 "0" 이 아니면 안된다.

3.5. 5.4 읽어 반환 버퍼

bPicReadbackRequests 가 "1" 의 경우는, 읽어 반환 커멘드 버퍼가 1 개 존재해, 이것이 가속기에 대해서, 결과의 최종 (적응할 수 있다면 비블록의 다음에) 픽쳐 매크로 블록 데이터를 호스트에게 돌려주도록(듯이) 지령한다. 암호화 프로토콜을 사용중이라면, 가속기는 가베지 데이터를 돌려주는, 캅셀 데이터를 돌려주는 등의 에러 지적 (암호화 프로토콜에 의해 지정된다)을 돌려주어 읽어 반환 리퀘스트에 대응하는 경우가 있다.

가속기에게 건네지는 버퍼에는, 독해 대상의 매크로 블록 1 개(살)에 대해 1 개의 파라미터를 포함한 읽기 반환 커멘드가 포함되지 않으면 안 된다.

wMBaddress : (16 비트) 현재의 매크로 블록의 매크로 블록 주소를 라스터 스캔 순서로 지정한다 ("0" 은 좌상 매크로 블록의 주소, PicWidthInMBminus1 는 우상 매크로 블록의 주소, PicHeightInMBminus1 * PicWidthInMB 는 좌하 매크로 블록의 주소, PicHeightInMBminus1 * PicWidthInMB + PicWidthInMBminus1 은 우하 매크로 블록의 주소).

BPP 가 "8" 의 경우는, 데이터는 부호 없음의 8 비트값 (따라 표면상, 흑은 Y=16, Cb=Cr=128 가 되어, 흰색은 Y=235, Cb=Cr=128 가 된다)으로 돌려주어지지 않으면 안 된다. BPP > 8 의 경우는, 데이터는 부호 없음의 16 비트값으로 돌려주어지지 않으면 안 된다.

데이터는, 가속기로부터 호스트에게, 다음의 포맷으로 돌려주어진다.

  1. 최초로 읽어 반환 커멘드 버퍼 자체의 카피, 그 후 다음의 32 바이트 정렬 경계에의 패딩, 그리고
  2. 읽어 반환 커멘드 버퍼에 송신된 순서로 돌려주어진 매크로 블록 데이터값. 포맷은 각 매크로 블록의 각 블록에 대해서, 블록 마다 WT·HT 샘플. 매크로 블록내의 잔차블록은, MPEG-2 도 6-10,6-11,6-12 그리고 지정된 순서에 돌려주어지지 않으면 안 된다 (라스터 스캔순서의 Y, 라스터 스캔순서의 Cb 의 전 4:2:0 블록, Cr 의 4:2:0 블록, Cb 의 4:2:2 블록, Cr 의 4:2:2 블록, Cb 의 4:4:4 블록, Cr 의 4:4:4 블록의 순서).

3.5. 6 오프 호스트의 VLD 비트 스트림 디코드 처리

생의 비트 스트림 데이터의 가변장 디코드가 가속기상에서 실행되는 경우, 픽쳐의 디코드를 위해서(때문에) 호스트에 의해 송신되는 데이터는, 다음의 3 타입의 버퍼에 분할된다.

  1. 역양자화 행렬 버퍼. 비트 스트림 데이터의 역양자화를 실시하는 방법에 대한 정보를 제공한다.
  2. 슬라이스 제어 버퍼. 각각이 비트 스트림 데이터 버퍼내의 스타트 코드 및 데이터의 위치에 관한 정보를 제공한다.
  3. 비트 스트림 데이터 버퍼. 특정의 비디오 코딩 사양에 근거해 encode 된 생의 데이터 스트림을 포함한다.

3.5. 6.1 역양자화 행렬 버퍼

역양자화 행렬 버퍼는, 오프 호스트에서의 비트 스트림 디코드용으로역양자화 행렬을 초기화하기 위해서 송신된다. 역양자화 행렬 버퍼는, 새로운 역양자화 행렬 버퍼가 공급될 때까지, 비트 스트림내의, 현재 및 거기에 계속되는 모든 비디오의 디코드 방법에 관한 정보를 제공한다. (이 점으로써, 역양자화 행렬은고정적이다. ) 호스트로부터 가속기에 한 번에 복수의 역양자화 행렬 버퍼를 송신해서는 안 된다.

DXVA_QmatrixData {
  for(i=0; i<4; i++)
    bNewQmatrix[i]      // 8b
  for(i=0; i<4; i++)
    if(bNewQmatrix[i] == 1)
      Qmatrix[i]        // WT·HT·16b
}

bNewQmatrix[i] : 타입 i 의 새로운 역양자화 행렬이 버퍼내에 존재할지 어떨지를 나타낸다. bNewQmatrix[i] 가 "1" 의 경우는, 역양자화 행렬 버퍼내에 타입 i 의 새로운 역양자화 행렬이 계속되고 있다. 타입 i=0 는 인트라 휘도 양자화, i=1 는 인터 휘도 양자화, i=2 는 인트라색광도 양자화, i=3 는 인터색광도 양자화이다. 호스트로부터 선행하는 값이 보내지지 않은 경우, 가속기는 역양자화 행렬의 디폴트값을 상정할 수 없다. i=0 및 i=1 의 양쪽 모두에 대해, bNewQmatrix[i] 의 값은 0 이어서는 안 된다.

i=2 또는 i=3 에 대해 bNewQmatrix[i] 의 값이 "0" 의 경우는, 다음과 같이 된다.

  1. bNewQmatrix[i-2] 가 "0" 의 경우, 가속기는 계속해 i 의 직전의 역양자화 행렬을 사용해야 한다.
  2. bNewQmatrix[i-2] 가 "1" 의 경우, i 의 역양자화 행렬을, i-2 의 새로운 역양자화 행렬과 같게 설정해야 한다.

해당하는 비디오 코딩 사양으로 역양자화 행렬이 필요하게 되지 않는 경우 (H. 261 이나 H. 263 등)은, 역양자화 행렬 버퍼를 송신해서는 안 된다. 해당하는 비디오 코딩 사양으로 역양자화 행렬이 필요하게 되는 경우는, 호스트에 의해, 비디오 디코드 처리의 시작시에, 몇개의 비트 스트림 데이터 버퍼의 전송의 전, 또는 전송과 협조해, 이러한 역양자화 행렬을 위해서(때문에) 값이 제공될 필요가 있다.

주 : 호스트로부터 선행하는 값이 보내지지 않은 경우는, 양자화 행렬의 디폴트값은 설정되지 않는다. 해당하는 비디오 코딩 사양으로 디폴트로 사용할 수 있는 값이 포함되어 있다고 해도, 양자화 행렬의 값은, 명시적으로 송신될 필요가 있다.

Qmatrix[i] : 역양자화 행렬. bNewQmatrix[i] 가 "1" 의 경우만 존재한다. 행렬은,WT·HT 부호 없음 워드 ( 각 워드의 하위의 8 비트만이 유력한 비디오 코딩 표준 규격으로 사용된다)로 구성된다. 역양자화 행렬내에서의 데이터값의 순서는, 해당하는 비디오 코딩 사양의 정의에 따르지 않으면 안 된다.

주 : MPEG-2 비트 스트림의 경우, Qmatrix[i] 내의 데이터값은, MPEG-2 의 부절 7.3. 1 및 그림 7-2 으로 지정되고 있는 대로, 지그재그역스캔 순서이다.

3.5. 6.2 슬라이스 제어 버퍼

오프 호스트에서의 VLD 비트 스트림 처리를 선도하기 위해(때문에), 슬라이스 제어 버퍼가 제공되지 않으면 안 된다. 호스트 소프트웨어 디코더는, 비트 스트림내의 "슬라이스 레벨의" 재동기화 포인트를 결정하지 않으면 안 된다. 슬라이스는, 비트 스트림 데이터내에 재동기화 포인트를 포함한 멀티 매크로 블록 계층으로서 정의된다. H. 261 비트 스트림에서는, GOB 를 슬라이스라고 봐, H. 263 비트 스트림에서는, GOB 시작 코드에 계속되는 일련의 GOB 를 슬라이스라고 보고 없으면 안 된다. 슬라이스 제어 버퍼에는, 대응하는 비트 스트림 데이터 버퍼의 내용에 응해, 1 개(살) 이상의 DXVA_SliceInfo 데이터 구조체가 포함되지 않으면 안 된다.

DXVA_SliceInfo {
              wHorizontalPosition       //16b
              wVerticalPosition         //16b
              dwSliceBitsInBuffer       //32b
              dwSliceDataLocation       //32b
              bStartCodeBitOffset       // 8b
              bReservedBits             // 8b
              wMBbitOffset              //16b
              wNumberMBsInSlice         //16b
              wQuantizerScaleCode       //16b
              wBadSliceChopping         //16b
            }

wHorizontalPosition, wVerticalPosition : 슬라이스의 최초의 매크로 블록의 수평 위치 및 수직 위치를, 매크로 블록의 단위로 나타낸 것, 0 은 픽쳐의 맨 위 또는 제일왼쪽의 매크로 블록을 의미한다.

dwSliceBitsInBuffer : 현재의 슬라이스의 데이터를 포함한, 대응하는 비트 스트림 데이터 버퍼내의 합계 비트수. MPEG-1, MPEG-2, 및 MPEG-4 에서는, 슬라이스 시작 코드가 바이트 정렬되기 (위해)때문에, 이 값은 8 의 배수가 아니면 안된다.

dwSliceDataLocation : 비트 스트림 데이터 버퍼내의, 슬라이스의 데이터를 포함한 최초의 바이트의 위치 (슬라이스 시작 코드의 위치 등). 슬라이스의 시작 부분이, 대응하는 비트 스트림 데이터 버퍼내에 없는 경우는, 0 이 아니면 안된다.

bStartCodeBitOffset : 슬라이스의 데이터를 포함하지 않는, dwSliceDataLocation 의 바이트의 MSB 의 수 (MPEG-1, MPEG-2, MPEG-4 에서는, 슬라이스 시작 코드가 바이트 정렬되기 (위해)때문에, 0 이 되지만, H. 261 및 H. 263 에서는, GOB 시작 코드의 바이트 정렬을 강제하지 않기 때문에, 0 이 아닌 경우가 있다). 범위는, 0...7 이 아니면 안된다. 슬라이스의 시작 부분이, 대응하는 비트 스트림 데이터 버퍼내에 없는 경우는, 0 이 아니면 안된다. bStartCodeBitOffset 에 의해, 현재의 슬라이스에 관계하지 않으면 마크 된 MSB 는, 전의 슬라이스의 데이터를 포함한 경우가 있다.

bMBbitOffset : 슬라이스의 시작 부분으로부터, 비트 스트림 버퍼내의 매크로 블록 계층 데이터의 최초의 비트에의 비트수. 예를 들어, wMBbitOffset 가 83 이라면, 슬라이스의 매크로 블록 계층 데이터는 슬라이스 헤더 데이터 83 비트로부터 시작 한다. 슬라이스의 시작 부분이, 대응하는 비트 스트림 데이터 버퍼내에 없는 경우는, 0 이 아니면 안된다.

wNumberMBsInSlice : 스킵 되는 매크로 블록을 포함해 슬라이스내에 있는 데이터의 매크로 블록의 수. 픽쳐의 헤더, 및 비트 스트림내의 현재와 다음의 슬라이스의 헤더와 초기 매크로 블록 데이터로부터, H. 263 의 슬라이스 모드의 임의 슬라이스 순서 서브 모드와 같이 이 수가 곧바로 결정할 수 없는 경우는, 0 의 경우가 있다. H. 261, MPEG-1, MPEG-2, MPEG-4 혹은 H. 263 으로 슬라이스 구조화 모드의 직사각형 슬라이스나 임의 슬라이스 서브 모드를 사용하고 있지 않을 때, 제로여서는 안 된다.

wQuantizerScaleCode : 각각의 비디오 코딩 사양으로 지정된, 비트 스트림의 슬라이스 레벨로부터의 양자화 스케일 코드 (H. 261, MPEG-2, H. 263, MPEG-1, 및 MPEG-4 에 대해서 "1" ~ "31" 의 범위).

wBadSliceChopping : 다음과 같이 정의된 값이 들어가는 파라미터.

"0" : 슬라이스의 모든 비트가, 대응하는 비트 스트림 데이터 버퍼내에 위치한다.

"1" : 슬라이스의 시작 부분의 비트가, 대응하는 비트 스트림 데이터 버퍼내에 있어, 슬라이스의 종료 부분의 비트가 (비트 스트림 데이터 버퍼가 가득하기 때문에), 대응하는 비트 스트림 데이터 버퍼내에 없다.

"2" : 슬라이스의 시작 부분의 비트가 (전의 비트 스트림 데이터 버퍼가 한 잔 선반째), 대응하는 비트 스트림 데이터 버퍼내에 없고, 슬라이스의 종료 부분의 비트가, 대응하는 비트 스트림 데이터 버퍼내에 있다.

"3" : 슬라이스의 시작 부분의 비트가 (전의 비트 스트림 데이터 버퍼가 한 잔 선반째), 대응하는 비트 스트림 데이터 버퍼내에 없고, 또, 슬라이스의 종료 부분의 비트도 (대응하는 비트 스트림 데이터 버퍼도 가득하기 때문에), 대응하는 비트 스트림 데이터 버퍼내에 없다.

wBadSliceChopping 가 0 이외의 값이 되는 것은, 보통, 호스트 소프트웨어 디코더측에서 회피하는 편이 좋다.

3.5. 6.3 비트 스트림 데이터 버퍼의 내용

비트 스트림 버퍼가 사용되는 경우, 가변장 디코드에서의 하위 비트 스트림 해석을 포함한 오프 호스트의 디코드를 지원 하기 위한(해), 버퍼에는 단지, 비디오 비트 스트림으로부터의 생의 바이트가 포함된다.

의도된 설계에 따른 방법으로 비트 스트림 데이터 버퍼가 사용되도록, 버퍼의 내용에는 일정한 제한이 부과된다.

  1. 각 픽쳐의 최초의 비트 스트림 데이터 버퍼는, 비트 스트림내에 있어서의 해당 픽쳐 데이터의 최초의 바이트로 시작되지 않으면 안 된다.
  2. MPEG-1 와 MPEG-2 사용 이외에서는, (전의 픽쳐의 전데이터의 끝에에 이어) 그것이 비트 스트림내의 현재의 픽쳐의 최초의 슬라이스(순서 헤더, 픽쳐 헤더등)에 선행한다면, 각 픽쳐의 비트 스트림 데이터 버퍼는 모든 데이터와 함께 시작 해야 한다.
  3. MPEG-1 와 MPEG-2 사용에 대해서는, 최 각 픽쳐의 첫비트 스트림 데이터 버퍼는 픽쳐의 최초의 슬라이스의 슬라이스 시작 코드로 시작 해야 한다 (순서 헤더나 픽쳐 헤더 등은 없는, 왜냐하면 모든 관련 데이터는 이 스펙(명세서)의 파라미터로 제공되기 때문이다).
  4. , 비트 스트림 데이터의 슬라이스의 선두가, 어느 비트 스트림 데이터 버퍼내에 위치하고 있는 경우, 그 버퍼를 할당할 수 있었던 사이즈까지 가득하지 않은 한, 슬라이스의 말미도 같은 데이터 버퍼내에 위치하고 있지 않으면 안 된다.

디코더에서는, 비트 스트림 데이터 버퍼에의 저장 상황을, 슬라이스가 복수의 버퍼가 될 수 있도록 걸치지 않게 관리하는 편이 좋다.

3.6 알파 브렌드 데이터의 로드 (bDXVA_Func=2)

DirectX VA 기능의 2 번째의 타입은, 비디오 데이터와 브렌드 되는 알파 블렌딩 표면을 지정하는 정보의 로드이다.

3.6. 1 접속 구성

알파 브렌드 데이터를 로드하기 위한 DirectX VA 접속 구성 데이터 구조체는, 다음과 같이 정의해야 한다.

DXVA_ConfigAlphaLoad {
           // 지정된 처리
          dwFunction         //32b
          dwReservedBits[3] // 3 * 32b 정렬
          bConfigDataType //8b
}

dwFunction : 구성 데이터의 구조를 기술하는 DXVA_ConfigQueryOrReplyFunc 가 포함된다.

bConfigDataType : 사용되는 알파 브렌드 데이터의 타입을 지정한다. 다음과 같이 정의된다.

"0" : IA44 알파 블렌딩 표면과 16 엔트리 YUV 팔레트

"1" : AI44 알파 블렌딩 표면과 16 엔트리 AYUV 팔레트

"2" : DXPD, Highlight, 및 DCCMD 데이터와 16 엔트리 AYUV 팔레트

"3" : AYUV 그래픽 표면

단기적인 가속기 이행에서는 bConfigDataType 가 "1" 혹은 "2" 의 지원이 용서되고 있지만, 다른 포맷이 바람직하고, 한정 모드 프로파일이 그 이외를 나타내지 않는 이상 포맷 "1" 으로 "3" 의 양쪽 모두가 중기적으로는 요구된다고 예상된다

3.6. 2 최소한의 상호 동작성 구성 세트

설계 위에의 조건으로서 모든 DirectX VA 디코더는, 모든 DirectX VA 가속기와 상호 동작할 필요가 있다. 이 때문에는, 모든 DirectX VA 디코더가, 접속 구성 세트의 모든 멤버와 함께 동작할 수 있어 모든 DirectX VA 가속기가, 동세트의 최저 1 개의 접속 구성 멤버와 함께 동작할 수 있을 필요가 있다. 알파 블렌딩 데이터를 로드하기 위한 최소한의 상호 동작성 구성 세트는, bConfigDataType 의모두의 정의값으로부터 구성된다.

3.6. 3 AYUV 알파 블렌딩 표면의 로드

AYUV 알파 블렌딩 표면은, 각각 32 비트의 샘플의 배열로서 정의된다. 이 표면은, 그래픽과 디코드가 끝난 비디오 픽쳐를 브렌드 할 때에, 소스로서 사용할 수 있다.

각 AYUV 샘플은 다음과 같이 구성된다.

DXVA_AYUVsample{
            bSampleAlpha8   // 8b (MSB)
            bY_Value        // 8b
            bCbValue        // 8b
            bCrValue        // 8b (LSB)
}

bSampleAlpha8 : 샘플의 불투명성. 값 0 은, 샘플이 투명한 것을 나타낸다 (즉, 다른 엔트리는 브렌드 후의 픽쳐에 영향을 주지 않는다). 값 255 는, 샘플이 불투명한 것을 나타낸다 (즉, 다른 엔트리가 브렌드 후의 픽쳐 샘플의 값을 완전하게 결정한다). SampleAlpha8 의 값이 "0" 이 아닌 경우, 지정된 브렌드는, 그래픽값의 (SampleAlpha8+1) 배를, 픽쳐값의 (255-SampleAlpha8) 배 및 정수 128 에 가산해, 결과를 8 자리수 오른쪽 쉬프트 한다. SampleAlpha8 의 값이 0 의 경우는, 지정된 브렌드는 픽쳐값을 그대로 사용한다.

bY_Value, bCbValue, bCrValue : 부호 첨부 수량으로서 지정되는 Y, Cb, Cr 색공간(color space)내의 색 (ITU-T 권고 601 에 의한다). 예를 들어, BPP=8 의 경우, 표면상, 흑은 Y=16, Cb=Cr=128 로 지정되어 흰색은 Y=235, Cb=Cr=128 로 지정된다.

AYUV 알파 블렌딩 표면의 폭과 높이는, 관련지을 수 있었던 버퍼 기술 리스트내에서 지정된다.

3.6. 3.1 16 엔트리 AYUV 팔레트의 로드

16 엔트리 YUV 팔레트는, 16 개의 DXVA_AYUVsamples 샘플의 배열로서 정의된다. 이 경우, 개개의 샘플의 SampleAlpha8 는 의미를 가지지 않기 때문에,"0" 이 아니면 안된다.

팔레트는, 그래픽과 디코드가 끝난 비디오 픽쳐를 브렌드 할 때에, 소스를 생성 하기 위해서 사용할 수 있다. 이 팔레트는, 이하의 어느쪽이든과 함께, 그래픽 소스의 생성에 사용할 수 있다.

  1. IA44/AI44 알파 블렌딩 표면
  2. DPXD 알파 블렌딩 표면, 하이라이트 버퍼, 및 DCCMD 데이터

3.6. 3.2 AYUV 표면의 로드

16 엔트리 팔레트만을 로드하는 것이 아니라, 그래픽의 내용을 지정하는 AYUV 이미지로서 이미지 그래픽 전체를 직접 로드할 수 있다.

3.6. 4 IA44/AI44 알파 블렌딩 표면의 로드

인덱스 알파 4-4 (IA44) 알파 블렌딩 표면은, 각각 다음과 같이 구성되는 8 비트의 샘플의 배열로서 정의된다.

DXVA_IA44sample{
        SampleIndex4        // 4b (MSB)
        SampleAlpha4        // 4b (LSB)
        }

알파 인덱스 4-4 (AI44) 알파 블렌딩 표면은, 각각 다음과 같이 구성되는 8 비트의 샘플의 배열로서 정의된다.

DXVA_AI44sample{
    SampleAlpha4        // 4b (MSB)
    SampleIndex4        // 4b (LSB)
    }

SampleIndex4 : 샘플의 16 엔트리 팔레트에의 인덱스.

SampleAlpha4 : 샘플의 불투명성. 값 "0" 은, 샘플이 투명한 것을 나타낸다 (즉 SampleIndex4 의 팔레트 엔트리는, 브렌드 후의 픽쳐에 영향을 주지 않는다). 값 15 는, 샘플이 불투명한 것을 나타낸다 (즉 SampleIndex4 의 팔레트 엔트리가, 브렌드 후의 픽쳐 상태를 완전하게 결정한다). SampleAlpha4 의 값이 0 이 아닌 경우, 지정된 브렌드는, 그래픽값의 (SampleAlpha4+1) 배를, 픽쳐값의 (15-SampleAlpha4) 배 및 정수 8 에 가산해, 결과를 4 자리수 오른쪽 쉬프트 한다. SampleAlpha4 의 값이 0 이 아닌 경우, 지정된 브렌드는 픽쳐값을 그대로 사용한다.

IA44 알파 블렌딩 표면의 폭과 높이는, 관련지을 수 있었던 버퍼 기술 리스트내에서 지정된다.

3.6. 5 DPXD 알파 블렌딩 표면의 로드

디코드되는 PXD (DPXD) 알파 블렌딩 표면은, 2 비트 샘플의 팩 된 프레임 구조화 배열로서 정의된다. 이러한 샘플은 각각, 하이라이트 및 DCCMD 데이터에 의해 결정된 4 색칼라 테이블에의 인덱스로서 사용된다. DPXD, 하이라이트, 및 DCCMD 의 편성의 결과는, IA44 표면과 동등하고, 16 엔트리 YUV 팔레트와 함께 블렌딩에 사용된다. 바이트의 배열로서 취급되는 경우, 최초의 2 비트 샘플의 인덱스는, DPXD 데이터의 최초의 바이트의 MSB 에, 다음의 샘플은 다음의 2 비트에, 3번째의 샘플은 다음의 2 비트에, 4 번째의 샘플은 LSB 에, 5 번째의 샘플은 다음의 바이트의 MSB 에, 와 같이 배치해야 한다.

DPXD 알파 블렌딩 표면은, RLE (run-length) encode 포맷의 DVD 위에의 PXD 정보로부터 생성 할 수도 있다. 이 때문에, DVD 위에의 PXD 로부터 DirectX VA 를 위한 DPXD 를 생성 하는 경우, 호스트가, 디스크로부터의 생 데이터의 RLE (run-length) 디코드를 실행할 필요가 있다.

표면의 보폭은, 2 비트 샘플 단위가 아니고, 바이트 단위의 보폭으로서 해석되지 않으면 안 된다. 다만, 폭과 높이는 2 비트 샘플 단위가 아니면 안된다.

주 : DVD 위에의 PXD 는, 필드 구조화 인터레이스 포맷이다. 여기서 정의되고 있는 DPXD 알파 블렌딩 표면은, 필드 구조화 인터레이스 포맷은 아니다. 이 때문에, DVD 의 PXD 데이터로부터 DPXD 를 생성 하는 경우는, 호스트가, 2 개의 필드로부터 데이터를 인터리브 할 필요가 있다.

주 : DVD 서브 픽쳐 정의 및 데이터 필드 해석의 상세한 것에 대하여는, 「DVD Specifications for Read-Only Disk:Part 3 – Video Specification (v. 1.11, May '99)」를 참조할것.

3.6. 6 하이라이트 데이터의 로드

하이라이트 데이터는, DVD ROM 사양에 준거한 방법으로 포맷 되어 알파 블렌딩 표면을 생성 하기 위한(해), DCCMD 데이터와 함께 DPXD 표면에 적용된다. 하이라이트 데이터 버퍼의 내용은, 다음과 같이 정의해야 한다.

DXVA_Highlight {
    wHighlightActive    // 16b
    wHighlightIndices   // 16b
    wHighlightAlphas    // 16b
    HighlightRect       // 128b
}

HighlightActive : 직사각형 하이라이트 영역이 현재 액티브하게 되어 있는지 어떤지를 나타낸다 ("0" 은 비액티브를 나타내,"1" 은 액티브를 나타낸다). 비액티브의 경우, 하이라이트 데이터가 브렌드 후의 픽쳐의 내용에 영향을 주어서는 안 된다.

HighlightIndices : DPXD 내의 각 2 비트 인덱스에 대해, 서브 픽쳐상에서 하이라이트 된 직사각형 영역의 4 비트 팔레트 인덱스를 나타낸다. 4 개의 MSB 는 인덱스 3, 다음의 4 비트는 인덱스 2, 다음의 4 비트는 인덱스 1, 4 개의 LSB 는 인덱스 "0" 에 대응하고 있지 않으면 안 된다.

HighlightAlphas : DPXD 에 사용되는 각 2 비트 인덱스에 대해, 서브 픽쳐상에서 하이라이트 된 직사각형 영역의 4 비트 불투명성을 나타낸다. 4 개의 MSB 는 인덱스 3, 다음의 4 비트는 인덱스 2, 다음의 4 비트는 인덱스 1, 4 개의 LSB 는 인덱스 0 으로 하고 있지 않으면 안 된다. 4 비트 불투명성의 값은, 위에의 SampleAlpha4 에 관한 설명과 같게 해석해야 한다.

HighlightRect : RECT 데이터 타입으로서의, 직사각형 하이라이트 영역의 정의를 포함한다.

RECT 파라미터에는 다음의 제한이 적용된다 :

  • "left" 와 "top" 는 제로 이상이 아니면 안된다.
  • "right" 와 "bottom" 는 각각 "left" 와 "top" 보다 크지 않으면 안 된다
  • "right" 는 720 을 넘지 않은,"bottom" 는 576 을 넘어서는 안 된다.

주 : DVD 의 사양으로 서브 픽쳐 직사각형 영역을 정의하는 방법과 Microsoft 어플리케이션으로 보통 사용되고 있는 방법에는 차이가 있다고 보여진다. 이 사양에서는 Microsoft 의 관례에 따라, 픽쳐의 좌상에 있는 폭 10 높이 10 의 직사각형을, Top = 0, Left = 0, Right = 10, Bottom = 10 으로 정의한다. DVD 의 사양의 관례에서는, Right = 9 및 Bottom = 9 가 사용된다.

3.6. 7 DCCMD 데이터의 로드

DCCMD (디스플레이 제어 커멘드) 데이터는, DVD ROM 사양에 준거한 방법으로 포맷 되어 알파 블렌딩 표면을 생성 하기 위한(해), 하이라이트 데이터와 함께 DPXD 표면에 적용된다. DCCMD 데이터 버퍼의 내용은, DVD 디스플레이 제어 커멘드 (DCCMD)의 리스트로서 포맷 된 데이터로 구성해야 한다.

주 : DVD 서브 픽쳐 정의 및 데이터 필드 해석의 상세한 것에 대하여는, 「DVD Specifications for Read-Only Disk:Part 3 – Video Specification (v. 1.11, May '99)」를 참조할것.

3.7 알파 브렌드 콤비네이션 (bDXVA_Func=3)

알파 브렌드 콤비네이션에서는, 마지막에 로드 되고 있었던 알파 브렌드 소스 정보를 참조 픽쳐와 조합해, 표시용의 브렌드 픽쳐를 생성 한다. 이 처리는, 알파 브렌드 콤비네이션 데이터 버퍼를 사용해 제어된다.

3.7. 1 접속 구성

알파 브렌드 콤비네이션을 위한 DirectX VA 접속 구성 데이터 구조체는, 다음과 같이 정의해야 한다.

DXVA_ConfigAlphaCombine {
  // Operation Indicated
  dwFunction                 // 32b
  dwReservedBits[3]         // 3 * 32b alignment

  bConfigBlendType          // 8b
  bConfigPictureResizing    // 8b
  bConfigOnlyUsePicDestRectArea  //8b
  bConfigGraphicResizing    // 8b
  bConfigWholePlaneAlpha    // 8b
}

dwFunction : 구성 데이터의 구조를 기술하는 DXVA_ConfigQueryOrReplyFunc 가 포함된다.

bConfigBlendType : 실행되는 알파 브렌드 콤비네이션의 타입을 지정한다. 다음과 같이 정의된다.

"0": 프론트엔드의 버퍼간 브렌드

"1": 연구 최종 단계의 하드웨어 브렌드

단기적인 가속기 이행에서는 bConfigBlendType = "1" 의 지원이 용서되고 있지만, 중기적으로는 bConfigBlendType = "0" 의 지원이 필요하게 되는 것으로 예상된다.

bConfigPictureResizing: 서브 픽쳐 블렌딩의 PictureSourceRect16thPel 가 다를지 어떨지를 나타내는, PictureDestinationRect 로부터 (PictureSourceRect16thPel 의 1/16th 샘플 스케일링으로 조정된) 폭과 높이, 또 PictureSourceRect16thPel 의 파라미터가 16의 배수는 아닌지 어떤지를 나타낸다, 거기에 따라 소스 픽쳐에 가속기에 의한 재샘플을 요구한다. "1" 은 (리사이즈 정밀도든, 서브 픽셀 정밀도여라) 재샘플이 지원 되고 있는 것을 나타내,"0" 은 지원되어 있지 않은 것을 나타낸다.

bConfigOnlyUsePicDestRectArea: 디코더가 PictureDestinationRect 외에 떨어지는 생성된 목적지 픽쳐의 출력 범위의 값을 지정하는 커멘드 조작이 가능한가 어떤가를 나타낸다. "0" 은 PictureDestinationRect 의 외부 에리어는 브렌드 콤비네이션 커멘드로 지정 가능한 것을 나타낸다. "1" 은 호스트 디코더는 PictureDestinationRect 가 지정한 밖의 브렌드 된 표면의 값은 신뢰하지 못하고, 그 리젼은 표시할 수 없는 것을 나타낸다.

bConfigGraphicResizing: 서브 픽쳐 블렌딩의 GraphicSourceRect 가 GraphicDestinationRect 의 사이즈와 다른지 어떤지 를 나타낸다, 거기에 따라 알파 블렌딩 그래픽스를 가속기가 재샘플 할지 어떨지를 요구한다. "1" 은 리사이즈가 지원 되고 있는 것을 나타내,"0" 은 지원되어 있지 않은 것을 나타낸다.

bConfigWholePlaneAlpha : 그래픽 데이터에 전프레인아르후파파라메이타를 적용할 수 있을지 어떨지를 지정한다. "1" 은 전프레인 알파가 적용 가능한 일을 나타내,"0" 은 적용할 수 없는 것을 나타낸다.

3.7. 2 최소한의 상호 동작성 구성 세트

설계 위에의 조건으로서 모든 DirectX VA 디코더는, 모든 DirectX VA 가속기와 상호 동작할 필요가 있다. 이 때문에는, 모든 DirectX VA 디코더가, 접속 구성 세트의 모든 멤버와 함께 동작할 수 있어 모든 DirectX VA 가속기가, 동세트의 최저 1 개의 접속 구성 멤버와 함께 동작할 수 있을 필요가 있다. 알파 블렌딩 데이터를 로드하기 위한 최소한의 상호 동작성 구성 세트는 bConfigBlendType 로부터 구성되는, 그것은 DirectX VA 한정 모드 프로파일에 의해 결정할 수 있던 범위의 값을 가진다.

3.7. 3 알파 브렌드 콤비네이션 버퍼

알파 브렌드 콤비네이션 버퍼는, 소스 픽쳐와 알파 블렌딩 정보를 수반하는 그래픽 이미지로부터의, 브렌드 픽쳐의 생성을 제어한다. 소스 픽쳐 및 행선지 픽쳐가 4:4:4 포맷이 아닌 경우는, 서브 샘플링 된 소스의 기준 색정보에 대해서, 그래픽 블렌딩 정보의 샘플이 1 개 두어 (1, 3, 5 등)에, 브렌드 결과를 얻기 위해서(때문에) 적합한 방향 (수직 또는 수평)으로 적용되지 않으면 안 된다.

DXVA_BlendCombination {
          wPictureSourceIndex           //16b
          wBlendedDestinationIndex      //16b
          PictureSourceRect16thPel      //128b
          PictureDestinationRect        //128b
          GraphicSourceRect             //128b
          GraphicDestinationRect        //128b
          wBlendDelay                   //16b
          bBlendOn                      //8b
          bWholePlaneAlpha              //8b
          OutsideYUVcolor               //32b
        }

wPictureSourceIndex : 그래픽과 짜 합쳐지는 픽쳐의 인덱스. 연구 최종 단계의 하드웨어 알파 블렌딩이 사용되고 있는 경우는, 0xFFFF 가 아니면 안된다.

wBlendedDestinationIndex : 생성 되는 편성 픽쳐의 인덱스. 연구 최종 단계의 하드웨어 알파 블렌딩을 사용하고 있는 경우는, 0xFFFF 가 아니면 안된다. wPictureSourceIndex 와 같고 있어서는 안된다.

PictureSourceRect16thPel: 그래픽과 짜 합쳐지는 소스 픽쳐의 범위는 휘도 컴퍼넌트의 1/16th 샘플의 단위로 RECT 데이터 구조체로서 지정된다. 바꾸어 말하면(자), RECT 데이터 구조체의 파라미터는 고정 소수점으로써 표현되는, 바이너리 포인트 전 28 비트와 후 4 비트이다. (이 1/16th 샘플 정밀도에서는 PictureSourceRect16thPel 는 MPEG-2 의 frame_centre_horizontal_offset 와 frame_centre_vertical_offset 빵-스캔 파라미터와 같은 정밀도를 가진다) bConfigPictureResizing 가 "0" 이라면, PictureSourceRect16thPel 의 모든 파라미터는 16 의 정수배가 아니면 안된다.

다음의 제한이 PictureSourceRect16thPel 의 RECT 파라미터에 적용된다 :

  • "left" 와 "top" 는 제로 이상이 아니면 안된다.
  • "right" 와 "bottom" 는 각각 "left" 와 "top" 이상이 아니면 안된다.
  • "right" 가 "left" 와 같은, 혹은 "top" 가 "bottom" 와 같으면, bConfigOnlyUsePicDestRectArea 가 "0" 의 경우만, RECT 파라미터의 모든 값은 "0" 을 가져, 소스 픽쳐를 사용하지 않는 것을 나타낸다.

예를 들어, PictureSourceRect16thPel 을 사용해 전 MPEG-2 디코드된 픽쳐를 선택하면(자), PictureSourceRect16thPel 파라미터는 다음과 같이 계산된다 :

  • left = 0
  • top = 0
  • right = 16×horizontal_size
  • bottom = 16×vertical_size

PictureDestinationRect : 소스 픽쳐로부터의 영역을 보관 유지하는 행선지 픽쳐의 영역. RECT 데이터 구조체로서 지정한다. bConfigPictureResizing 가 "0" 의 경우는, 폭과 높이가 PictureSourceRect16thPel 로 지정된 영역과 같지 않으면 안 된다. PictureDestinationRect 와 PictureSourceRect16thPel 의 사이즈가 다른 경우, 적용되는 재샘플링 방식은 지정되지 않지만, 최악이어도 바이리니아재샘플링과 동등의 품질을 가지고 있는 편이 좋다.

다음의 제한이 RECT 파라미터에 적용된다 :

  • "left" 와 "top" 는 제로 이상이 아니면 안된다.
  • "right" 와 "bottom" 는 각각 "left" 와 "top" 이상이 아니면 안된다.
  • "right" 가 "left" 와 같은, 혹은 "top" 가 "bottom" 와 같으면, bConfigOnlyUsePicDestRectArea 가 "0" 의 경우만, RECT 파라미터의 모든 값은 "0" 을 가져, PictureSourceRect16thPel 도 모든 파라미터가 값 "0" 을 가지는 것을 나타낸다.
  • bConfigBlendType = 0 이라면,"right" 와 "bottom" 는 각각 비압축 목적지 픽쳐 표면에 할당할 수 있었던 폭과 높이를 넘어서는 안 된다.
  • bConfigBlendType = 1 이라면,"right" 와 "bottom" 는 각각 소스 그래픽 표면에 할당할 수 있었던 폭과 높이를 넘어서는 안 된다.

GraphicSourceRect: 소스 픽쳐와 짜 합쳐지는 그래픽 픽쳐의 영역. RECT 데이터 구조체로서 지정한다. 알파 브렌드 데이터 로딩이 bConfigDataType 에 "2" 를 사용한다면, 다음의 제한이 GraphicSourceRect 에 적용된다 :

  1. GraphicSourceRect 의 "top" 와 "left" 파라미터는 제로가 아니면 안된다.
  2. GraphicSourceRect 의 "right" 파라미터는 "End X-coordinate" 로부터 직전의 DVD SET_DAREA DCCMD 의 "Start X-coordinate" 를 당긴 것에 1 을 더한 것과 동일하지 않으면 안 되는, 마지막에 더한 1 은 아래의 주에 설명되어 있도록(듯이) 직사각형 보간의 차이를 조정하는 것이다.
  3. GraphicSourceRect 의 "bottom" 파라미터는 "End Y-coordinate" 로부터 직전의 DVD SET_DAREA DCCMD 의 "Start Y-coordinate" 를 당긴 것에 1 을 더한 것과 동일하지 않으면 안 되는, 마지막에 더한 1 은 아래의 주에 설명되어 있도록(듯이) 직사각형 보간의 차이를 조정하는 것이다.

다음의 제한이 RECT 파라미터에 적용된다 :

  1. "left" 와 "top" 는 제로 이상이 아니면 안된다.
  2. "right" 와 "bottom" 는 각각 "left" 와 "top" 이상이 아니면 안된다.
  3. "right" 가 "left" 와 같은, 혹은 "top" 가 "bottom" 와 같으면, 모든 RECT 파라미터는 값 "0" 을 가지지 않으면 안 되는, 이것은 그래픽 픽쳐를 사용하지 않는 것을 나타낸다.
  4. "right" 와 "bottom" 는 각각 그래픽 소스 표면의 폭과 높이를 넘어서는 안 된다. bConfigDataType = "2" 때, 할당할 수 있었던 폭과 높이는 각각 720 으로 576 이다.

GraphicDestinationRect : 그래픽 픽쳐로부터의 영역을 보관 유지하는 행선지 픽쳐의 영역. RECT 데이터 구조체로서 지정한다. bConfigGraphicResizing 가 "0" 의 경우는, 폭과 높이가 GraphicSourceRect 로 지정된 영역과 같지 않으면 안 된다. GraphicDestinationRect 와 GraphicSourceRect 의 사이즈가 다른 경우, 그래픽에 적용되는 재샘플링 방식은 지정되지 않지만, 최악이어도 블렌딩 정보를 나타내는 AYUV 표면의 바이리니아재샘플링과 동등의 품질을 가지고 있는 편이 좋다.

다음의 제한이 GraphicDestinationRect 의 RECT 파라미터에 적용된다 :

  1. 이 요건이 다음의 패러그래프와 3.7. 3.3 으로 3.7. 3.4 장으로 설명되고 있는 8 샘플에 의한 그래픽의 오프셋(offset)의 필요성과 모순되지 않는 한은,"left" 와 "top" 는 제로 이상이 아니면 안된다.
  2. "right" 와 "bottom" 는 각각 "left" 와 "top" 이상이 아니면 안된다.
  3. "right" 가 "left" 와 같은, 혹은 "top" 가 "bottom" 와 같으면, 모든 RECT 파라미터는 "0" 을 가지지 않으면 안 되는, GraphicSourceRect 도 모든 파라미터가 "0" 을 가지도록(듯이) 지정해야 한다.
  4. bConfigBlendType = 0 이라면,"right" 와 "bottom" 는 각각 비압축 목적지 표면에 할당할 수 있었던 폭과 높이를 넘어서는 안 된다.
  5. bConfigBlendType = 1 이라면,"right" 와 "bottom" 는 각각 소스 그래픽 표면에 할당할 수 있었던 폭과 높이를 넘어서는 안 된다.

알파 브렌드 데이터 로딩이 bConfigDataType 에 "2" 를 사용해, bConfigGraphicResizing에 "0" 을 사용한다면, 다음의 제한이 GraphicSourceRect 에 적용된다 :

  1. "top" 는 직전의 DVD SET_DAREA DCCMD 의 "Start Y-coordinate" 와 동일하지 않으면 안 된다.
  2. "left" 는 직전의 DVD SET_DAREA DCCMD 의 "Start X-coordinate" 있고는 그 값 당기는 8 의 어느 쪽일까하고 동일하지 않으면 안 된다 (3.7. 3.3 장과 3.7. 3.4 장을 참조할것).
  3. GraphicDestinationRect 의 "right" 파라미터는 "left" 플러스 직전의 DVD SET_DAREA DCCMD 의 "End X-coordinate" 마이너스 "Start X-coordinate" 플러스 1 으로 동일하지 않으면 안 된다. 마지막에 더한 1 은 아래의 주에 설명되어 있도록(듯이) 직사각형 보간의 차이를 조정하는 것이다.
  4. GraphicDestinationRect 의 "bottom" 파라미터는 "top" 플러스 직전의 DVD SET_DAREA DCCMD 의 "End Y-coordinate" 마이너스 "Start Y-coordinate" 플러스 1 으로 동일하지 않으면 안 된다. 마지막에 더한 1 은 아래의 주에 설명되어 있도록(듯이) 직사각형 보간의 차이를 조정하는 것이다.

주 : DVD 의 사양으로 서브 픽쳐 직사각형 영역을 정의하는 방법과 Microsoft 어플리케이션으로 보통 사용되고 있는 방법에는 차이가 있다고 보여진다. 이 사양에서는 Microsoft 의 관례에 따라, 픽쳐의 좌상에 있는 폭 10 높이 10 의 직사각형을, Top = 0, Left = 0, Right = 10, Bottom = 10 으로 정의한다. DVD 의 사양의 관례에서는, Right = 9 및 Bottom = 9 가 사용된다.

wBlendDelay : 연구 최종 단계의 하드웨어 블렌딩이 사용되고 있는 경우, wBlendDelay 에는 편성 처리에 의해 효과가 나타날 때까지의 지연 (밀리 세컨드수)이 포함된다. 프론트엔드 블렌딩이 사용되고 있는 경우는, 의미가 없기 때문에, 0 이 아니면 안된다.

bBlendOn : 연구 최종 단계의 하드웨어 블렌딩이 사용되고 있는 경우는, bBlendOn 가 "1" 의 블렌딩 콤비네이션 기능으로 지정된 시간부터, bBlendOn = 1 의 새로운 블렌딩 콤비네이션으로 지정된 실행 시간까지인가, 또는 bBlendOn 가 "0" 의 블렌딩 콤비네이션 기능에 의해 블렌딩이 무효가 될 때까지, 지정된 블렌딩이 적용되지 않으면 안 된다.

bWholePlaneAlpha : 그래픽의 알파 채널의 불투명성을 나타내는 승수가 포함된다. 값 "0" 은, 그래픽이 투명한 것을 나타내 (즉 그래픽의 내용이 브렌드 후의 픽쳐에 영향을 주지 않는다), 값 "255" 는, 그래픽 내용이 샘플의 불투명도를 최대한 사용하는 것을 나타낸다. bWholePlaneAlpha 의 값이 "0" 이 아닌 경우, 지정된 브렌드는, 그래픽 내용의 여러분치의 불투명도에 (bWholePlaneAlpha+1)/256 를 곱셈한다. bWholePlaneAlpha 의 값이 "0" 의 경우, 지정된 브렌드는, 그래픽 내용으로 지정된 불투명도를 그대로 사용한다. bConfigWholePlaneAlpha 가 "0" 의 경우는,"0" 이 아니면 안된다.

OutsideYUVcolor: PictureDestinationRect 외의 범위가 블렌딩 일정색을 가진다고 하여 생성될지 어떨지를 나타내는 식별자가 들어간다, 또 그 경우 그 일정색이 들어간다. OutsideYUVcolor 는 DXVA_AYUVsample 로서 포맷 되어 이하의 결정에 따른다 :

  1. PictureDestinationRect 외의 범위가 블렌딩 일정색으로서 생성된다면, OutsideYUVcolor 의 bSampleAlpha8 의 값은 "255" 가 아니면 안된다.
  2. 이하의 2 개의 경우의 어느 쪽인지이면, OutsideYUVcolor 의 bSampleAlpha8 의 값은 "0" 이 아니면 안된다 :
    1. PictureDestinationRect 외의 범위가 블렌딩에 따라서는 영향을 받지 않는 경우, 혹은
    2. PictureDestinationRect 외의 범위가 사용 될 수 없는 (bConfigStayInPicDestRectArea 가 값 "1" 을 가진다) 경우.
  3. OutsideYUVcolor 의 bSampleAlpha8 외 모든 값은 장래의 사용을 위해서(때문에) 예약되고 있다.

bConfigStayInPicDestRectArea 가 "1" 이라면, OutsideYUVcolor 의 bSampleAlpha8 의 값은 "1" 이 아니면 안된다.

OutsideYUVcolor 의 bSampleAlpha8 가 "0" 이라면, 브렌드의 영향을 받는 목적지 표면의 범위는 PictureDestinationRect 내의 부분이다. OutsideYUVcolor 의 bSampleAlpha8 가 "255" 라면, PictureDestinationRect 외이지만 GraphicDestinationRect 내의 목적지 표면의 범위는 OutsideYUVcolor 의 비알파 파라미터로 지정되는 색으로 블렌딩 한 그래픽에 의해 생성되어 PictureDestinationRect 와 GraphicDestinationRect 양쪽 모두의 밖에 떨어지는 목적지 표면의 전할맞히고 범위는 OutsideYUVcolor 의 비알파 파라미터로 지정된 색으로 설정된다. bConfigBlendType 가 "1" 이라면, OutsideYUVcolor 파라미터는 흑과의 블렌딩을 나타내는 bSampleAlpha8 = 255, bY_Value = 16, bCbValue = bCrValue = 128 을 지정해야 한다.

주 : bConfigBlendType 가 "1" (연구 최종 단계 하드웨어 브렌드)이라면, 실제의 블렌딩 조작은 여기서 설명한 것과는 조금 다른 경우가 있다. 그러나, 표시 결과는 같지 않으면 안 된다. 예를 들어, 비디오 픽쳐를 소스로부터 목적지 사이즈에 맵 하도록(듯이) 지정한 리사이즈는, 역의 방법으로 그래픽 내용을 소스 비디오 픽쳐에 따라 그 올바른 위치에 맵 하도록(듯이) 적용될지도 모른다, 하면 이 조작의 달라 대응해 블렌딩 결과가 표시되는 - 그러나 결과의 최종 시각 효과는 브렌드 콤비네이션 커멘드로 지정되지 않으면 안 된다.

3.7. 3.1 예 : MPEG-2 빵 - 스캔 조작

예를 들어, PictureSourceRect16thPel 을 사용해 MPEG-2 비디오 빵 - 스캔 파라미터가 지정하는 범위를 선택했을 경우, PictureSourceRect16thPel 파라미터는 다음과 같이 조합할 수 있다 (그 계산된 값이 위에의 제한에 반하지 않게 제공되는, MPEG-2 빵 - 스캔 파라미터의 경우와 특히 MPEG-2 DVD 컨텐츠의 경우) :

  1. left = 8×(horizontal_size - display_horizontal_size) - frame_centre_horizontal_offset
  2. top = 8×(vertical_size - display_vertical_size) - frame_centre_vertical_offset
  3. right = left + 16×display_horizontal_size
  4. bottom = top + 16×display_vertical_size

다음에 PictureDestinationRect 는 보통 다음과 같이 생성 된다 :

  1. left = 0 or 8 (3.7. 3.3 장)
  2. top = 0
  3. right = left + display_horizontal_size
  4. bottom = top + display_vertical_size

3.7. 3.2 예 : 16:9 픽쳐에서의 DVD 4:3 빵 스캔

예를 들어,16:9 픽쳐로 4:3 빵 스캔을 MPEG-2 DVD 로 사용하면(자), 빵 스캔 파라미터는 위의 제한을 범하지 않는 범위에 제한되어 더욱 이 경우에는 빵 스캔 파라미터는 다음의 제한에 따른다 :

  1. horizontal_size = 720 or 704
  2. vertical_size = 480 or 576
  3. display_horizontal_size = 540
  4. display_vertical_size = vertical_size
  5. frame_centre_vertical_offset = 0
  6. frame_centre_horizontal_offset 는 다음의 절대치를 가진다
    1. horizontal_size = 720 에 대해서 1440 이하
    2. horizontal_size = 704 에 대해서 1312 이하

다음에 3.7. 3.1 장으로 설명되고 있는 공식이 이 경우 직접 적용된다.

3.7. 3.3 예: DVD 704 와이드비빵 스캔 픽쳐 조작

이제(벌써) 1 개의 예로서 704 와이드 픽쳐로 DVD MPEG-2 를 사용할 때, 디코드된 픽쳐의 경계를 확장하는 3.7. 3.1 장을 사용하면(자) (디코드된 horizontal_size 를 704 에 확장하도록(듯이) display_horizontal_size 에 720 을 지정한다면), 전송원직사각형을 지정한다. 이러한 경우, 호스트 소프트웨어 디코더는 전송원직사각형을 할당할 수 있었던 소스 범위의 밖까지 닿도록(듯이) 크롭 해, 그 크롭에 대해서 목적지 직사각형의 조정을 관리할 필요가 있다. 이 경우, 2 개의 기본적인 경우가 있다. 양쪽 모두 다음과 같은 픽쳐 전송원직사각형의 지정을 요건으로 한다 :

  • left = 0
  • right = 16×(left + horizontal_size) = 11264

2 개의 경우란 :

  1. 픽쳐 목적지 직사각형이 다음과 같이 설정 될 수 있을까 :
    • left = (display_horizontal_size – horizontal_size) / 2 = 8
    • right = left + horizontal_size = 712
    이 경우 직진 방식의 그래픽을 사용한다.
  2. 혹은 픽쳐 목적지 직사각형이 다음과 같이 설정 될 수 있을까 :
    • left = 0
    • right = left + horizontal_size = 704
    이 경우 그래픽 목적지 직사각형은 쉬프트 된 픽쳐 목적지를 보상하는 8 샘플로 왼쪽으로 표시된다.

이러한 2 개의 경우의 쳐 아마 2 번째가 우선된다

3.7. 3.4 예 : DVD 352 와이드 픽쳐 조작

이제(벌써) 1 개의 예는 325 와이드 픽쳐의 DVD 사용인, 이것은 픽쳐 전송원직사각형 (1/16th 샘플 해상도)을 사용해 704 의 폭으로 확대한다 :

  1. left = 0
  2. right = 16×(left + horizontal_size) = 5632
그리고, 픽쳐 목적지 직사각형은 2 개의 경우가 있다 :
  1. 픽쳐 목적지 직사각형이 다음과 같이 설정될까 :
    1. left = 8
    2. right = left + 2×horizontal_size = 712
    3. 이 경우 직진 방식의 그래픽을 사용한다.
  2. 혹은 픽쳐 목적지 직사각형이 다음과 같이 설정 될 수 있을까 :
    1. left = 0
    2. right = left + 2×horizontal_size = 704
    3. 이 경우 그래픽 목적지 직사각형은 쉬프트 된 픽쳐 목적지를 보상하는 8 샘플로 왼쪽으로 표시된다.

이러한 2 개의 경우의 쳐 아마 2 번째가 우선된다

3.7. 3.5 예 : DVD 720 와이드 픽쳐 조작

꽤 작은 예는 720 와이드 픽쳐의 DVD MPEG-2 의 사용인, (1/16 샘플 해상도로) 픽쳐 전송원직사각형은 다음과 같다 :

  1. left = 0
  2. right = left + 16×horizontal_size = 11520
목적지 직사각형은 보통 이하대로이다 :
  1. left = 0
  2. right = left + horizontal_size = 720

3.7. 3.6 예 : 4:3 픽쳐 조작에 있어서의 DVD 16:9 레터박스 높이

이제(벌써) 1 개의 예는 레타복스후레이밍을 가지는 4:3 디스플레이에서의 DVD 16:9 비디오의 사용이다. 이하의 픽쳐 전송원직사각형을 사용하는 것에 의해 지원 된다 :

  1. top = 0
  2. bottom = top + 16×vertical_size = 7680 or 9216
그리고 픽쳐 목적지 직사각형은 이하대로이다 :
  1. top = vertical_size / 8 = 60 or 72
  2. bottom = 7 × vertical_size / 8 = 420 or 504

3.8 픽쳐재샘플링 제어 (bDXVA_Func=4)

픽쳐의 재샘플링 기능은, 공간 스케이라브르비데오코딘그, 참조 픽쳐의 재샘플링, 또는 업 샘플 픽쳐나 표시 픽쳐로서 사용하기 위한 재샘플링이라고 하는 목적으로 정의된다.

재샘플링은, 픽쳐의 엣지에서의 "클리핑" 을 사용해, H. 263 보유 O 「공간 스케이라비리티 (Spatial Scalability)」, 또는 MPEG-2 및 MPEG-4 의 「공간 스케이라비리티 (Spatial Scalability)」의 몇개의 포맷과 같은 H. 263 보유 P 에 정의되고 있도록(듯이) 실행되지 않으면 안 된다. 이 경우, 단순한 2 탭 분할 가능 필터 링이 사용된다.

3.8. 1 접속 구성

픽쳐의 재샘플링 제어에 접속 구성은 불필요하다. 이 처리에는 적절한 제한 모드 GUID 의 지원만이 필요하다.

3.8. 2 최소한의 상호 동작성 구성 세트

픽쳐의 재샘플링 제어에는 접속 구성이 불필요하기 때문에, 이 처리에 최소한의 상호 동작성 세트를 정의할 필요는 없다.

3.8. 3 픽쳐재샘플링 제어 버퍼

재샘플링 처리를 제어하기 위한 버퍼 타입이 1 개 정의되고 있다.

DXVA_PicResample {

  wPicResampleSourcePicIndex    // 16b
  wPicResampleDestPicIndex      // 16b

  wPicResampleRcontrol          // 8b
  bPicResampleExtrapWidth       // 8b
  bPicResampleExtrapHeight

  dwPicResampleSourceWidth      // 32b
  dwPicResampleSourceHeight     // 32b

  dwPicResampleDestWidth        // 32b
  dwPicResampleDestHeight       // 32b

  dwPicResampleFullDestWidth    // 32b
  dwPicResampleFullDestHeight   // 32b
}

wPicResampleRcontrol : 재샘플링 처리의 평균화 둥근 모드를 지정한다. H. 263 보유 O 「공간 스케이라비리티 (Spatial Scalability)」의 경우는, 이 파라미터는 1 이 아니면 안된다. (이것은, H. 263 보유 O 의 공간 스케이라비리티에 필요한 업 샘플링과 동등의, H. 263 보유 P 의 RCRPR 의 값에 대응한다. ) H. 263 보유 P 「참조 픽쳐재샘플링 (Reference Picture Resampling)」의 경우는, 이 파라미터는 H. 263 의 파라미터 RCRPR 와 같지 않으면 안 된다.

bPicResampleExtrapWidth, bPicResampleExtrapHeight : 0 이외로, 한편 픽쳐 경계상에서의 움직여 벡터 사용의 패딩 방법이 가속기상에서 사용되고 있는 경우는, 재샘플링에, 재샘플 된 픽쳐의 패딩이 포함되지 않으면 안 된다. 또, 이 패딩은, 실행되는 재샘플링 처리에 관계없이, 적어도, 재샘플 된 픽쳐의 각 엣지의 주위로 지정된 폭 및 높이를 커버해야 한다.

dwPicResampleSourcePicIndex : 재샘플 대상의 참조 버퍼를 지정한다.

dwPicResampleDestPicIndex : 참조 픽쳐의 재샘플링 처리의 출력에 사용되는 버퍼를 지정한다.

dwPicResampleSourceWidth, dwPicResampleSourceHeight : 행선지 픽쳐에 재샘플 되는 소스 픽쳐의 영역의 폭과 높이.

dwPicResampleDestWidth, dwPicResampleDestHeight : 소스 픽쳐로부터 재샘플 된 데이터를 저장 하는 행선지 픽쳐의 영역의 폭과 높이.

dwPicResampleFullDestWidth, dwPicResampleFullDestHeight : 소스 픽쳐로부터 재샘플 된 데이터를 저장 하는 행선지 픽쳐의 영역 전체의 폭과 높이. 소스재샘플링 영역의 밖에 샘플을 생성하려면 , 클리핑이 사용되지 않으면 안 된다. (이 파라미터는, 휘도의 폭 또는 높이가 16 으로 나눗셈 할 수 없는 커스텀 소스 포맷에 H. 263 보유 P 지원을 제공하기 위해서 필요하다. )

4 제한 모드

많은 제한 모드 프로파일이 이 장으로 정의된다. 이러한 제한 모드 프로파일에 의해, 어느 제한 모드 프로파일을 지원 하고 있을까의 지표를 얻을 수 있으므로, 디코더는 가속기의 성능을 확인할 수가 있다.

여기서 정의되고 있는 몇개의 제한 모드 프로파일은 여기서 정의되는 다른 제한 모드 프로파일의 능력의 단순한 서브 세트로 정의된다 (예를 들어, MPEG2_A 프로파일은 MPEG2_B 프로파일의 능력의 서브 세트이다). 가속기 능력 결정의 논리 구조를 강화하기 위해(때문에) 다음 일이 요구되는, 있는 개별의 제한 모드 프로파일을 지원 하는 가속기는, 문제의 그 프로파일의 능력의 서브 세트로서 정의되는 모든 제한 모드 프로파일도 지원 해야 한다. 예를 들어, MPEG2_A 프로파일은 MPEG2_B 프로파일의 능력의 서브 세트로서 정의되므로, MPEG2_B 프로파일을 지원 하는 모든 가속기는 MPEG2_A 프로파일도 지원 해야 한다.

4.1 신규 제한 프로파일의 추가

이하에 드는 제한 모드 프로파일은, 장래 넓게 지원 된다고 생각되는 기능의 편성을 예측해 정의되었다. Microsoft 에서는, 이것들 이외의, 실용적이고 필요라고 생각되는 각종 기능의 편성을 포함한 신규 프로파일 추가의 제안을 받아들이고 있다. 제한 모드 프로파일은, 디코드에 필요한 일련의 비디오 코딩 "툴" 을 확립하기 위해서, 이 사양으로 정의되고 있다. 가장 중요한 점은, 특정의 비디오 데이터 포맷이, API 를 사용해 어떠한 방법으로 디코드할 수 있을지 어떨지를 결정하는 것이다. 일련의 "툴" 을 확립하는 것에 가세해 디코더는, 그러한 툴을, API 를 사용해 어떻게 조작할까 인식하고 있을 필요가 있다. 이것에 대해서는, 계속되는 구성 정보의 섹션으로 해설한다.

4.2 비제한 처리

이 API/DDI 가, 이하에 정의하는 제한 모드 프로파일에 엄밀하게 준거하지 않고 사용되는 경우, wRestrictedMode 필드는, 제한이 없는 것을 나타내는 값으로 설정되지 않으면 안 된다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = 0xFFFF
    2. 정의 끝난 bDXVA_Func 값이 모두 사용 가능

4.3 H261_A 제한 프로파일

H261_A 제한 프로파일에는, ITU-T 권고 H. 261 을 최소한으로 지원 하는데 필요한 일련의 기능이 포함된다. H. 261 보유 D 그래픽의 가속화 지원은 제외된다. 이 프로파일의 지원은, 중기적인 필요 조건은 아니다. 이 기능 세트는, 다음의 일련의 제한에 의해 정의된다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = "1"
    2. bDXVA_Func = 1
  2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
    1. 프레임 레벨의 제한 :
      • BPP = 8
      • bSecondField = 0
      • (MacroblockWidth, MacroblockHeight) = (16, 16)
      • (WT, HT) = (8, 8)
      • bChromaFormat = '01' (4:2:0)
      • bPicStructure = '11' (프레임 구조화)
      • bMVprecisionAndChromaRelation = '10' (H. 261 정수 샘플 움직임)
      • bPicExtrapolation = 0
      • bPicDeblocked = 0
      • bPic4MVallowed = 0
      • bPicOBMC = 0
      • bMV_RPS = 0
      • bPicScanFixed = 1
    2. 매크로 블록 레벨의 제한 :
      • MotionType = '10' (프레임 움직임) (MotionForward = 1 의 경우)
      • MBscanMethod = '00' (지그재그) (bConfigHostInverseScan = 0 의 경우)
      • FieldResidual = 0 (프레임 잔여)
      • MotionBackward = 0 (역방향 예측 없음)
    3. 비트 스트림 버퍼의 제한 :
      • 모든 비트 스트림 버퍼의 내용은, H. 261 비디오 포맷의 데이터를 포함하지 않으면 안 된다.

    3. 4.4 H261_B 제한 프로파일

    H261_B 제한 프로파일에는, ITU-T 권고 H. 261 을 지원 하는데 필요한 일련의 기능이 포함된다. H. 261 보유 D 그래픽의 가속화 지원은 제외되지만, 블록 해제 필터 포스트프로세싱의 지원은 포함된다. 이 프로파일의 지원은, 중기적인 필요 조건은 아니다. 이 기능 세트는, H261_A 제한 프로파일에 리스트 한 것과 같은 제한에 의해 정의된다. 다만 다음의 항목에 대해서는 다르다.

    1. 접속 모드와 기능 :
      1. wRestrictedMode = "2"
    2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
      1. bPicDeblocked 는 0 또는 1
      2. bPicDeblocked 이 1 의 경우는, wDeblockedPictureIndex 는 wDecodedPictureIndex 와 같고 있어서는 안된다.

    4.5 H263_A 제한 프로파일

H263_A 제한 프로파일에는, ITU-T 권고 H. 263, 및 소수의 특정의 확장 옵션 기능을 지원 하는데 필요한 일련의 기능이 포함된다. 이 프로파일의 지원은, 중기적인 필요 조건이다. 이 기능 세트는, 다음의 일련의 제한에 의해 정의된다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = "3"
    4. bDXVA_Func = 1
  2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
    1. 프레임 레벨의 제한 :
      • BPP = 8
      • bSecondField = 0
      • (MacroblockWidth, MacroblockHeight) = (16, 16)
      • (WT, HT) = (8, 8)
      • bChromaFormat = '01' (4:2:0)
      • bPicStructure = '11' (프레임 구조화)
      • bRcontrol = 0
      • bMVprecisionAndChromaRelation = '01' (H. 263 하프 샘플 움직임)
      • bPicExtrapolation = 0
      • bPicDeblocked = 0
      • bPic4MVallowed = 0
      • bPicOBMC = 0
      • bMV_RPS = 0
      • bPicScanFixed = 1
    2. 매크로 블록 레벨의 제한 :
      • MotionType = '10' (프레임 움직임) (MotionForward = 1 의 경우)
      • MBscanMethod = '00' (지그재그) (bConfigHostInverseScan = 0 의 경우)
      • FieldResidual = 0 (프레임 잔여)
      • H261LoopFilter = 0 (H. 261 루프 필터 없음)
      • MotionBackward = 0 (역방향 움직임 및 쌍방향 움직여 없음)
    3. 비트 스트림 버퍼의 제한 :
      • 모든 비트 스트림 버퍼의 내용은,"baseline" 모드의 H. 263 비디오 포맷 데이터 (옵션 이루어, PLUSPTYPE 없음)를 포함하지 않으면 안 된다. 또는 무시하는 경우는, 보유 L 정보 첨부의 H. 263 비디오 포맷 데이터를 포함하지 않으면 안 된다.

4.6 H263_B 제한 프로파일

H263_B 제한 프로파일에는, ITU-T 권고 H. 263, 및 특정의 확장 옵션 기능을 지원 하는데 필요한 일련의 기능이 포함된다. 이 프로파일의 지원은, 중기적인 필요 조건이다. 이 기능 세트는, H263_A 제한 프로파일에 리스트 한 것과 같은 제한에 의해 정의된다. 다만 다음의 항목에 대해서는 다르다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = "4"
  2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
    1. 프레임 레벨의 제한 :
      • bPicDeblocked 는 0 혹은 1 이라도 좋다
      • bPicDeblocked = 1 의 경우, wDeblockedPictureIndex 는 wDecodedPictureIndex 와 같지도 같지 않아도 좋다
      • bRcontrol 는 0 또는 1
      • bPicExtrapolation 는 0 또는 1
      • Pic4MV 는 0 또는 1
      • Motion4MV 는 0 또는 1
      • bPicScanFixed 는 0 또는 1
    2. 매크로 블록 레벨의 제한 :
      • bConfigHostInverseScan = 0 의 경우, MBscanMethod 는, '00' (지그재그), '01' (교호 수직), 또는 '10' (교호 수평)의 머지않아에서도 상관없다
    3. 비트 스트림 버퍼의 제한 :
      • 모든 비트 스트림 버퍼의 내용은, CPCF, CPFMT, 및 보유 D, I, N (출력 픽쳐 1 개(살)에 대해 1 개의 순서 방향 참조 픽쳐), 및 T 의 서브 세트와 함께, H. 263 비디오 포맷의 데이터도 포함할 수가 있다.

4.7 H263_C 제한 프로파일

H263_C 제한 프로파일에는, ITU-T 권고 H. 263, 및 특정의 확장 옵션 기능을 지원 하는데 필요한 일련의 기능이 포함된다. 이 프로파일의 지원은, 장기적인 필요 조건이다. 이 기능 세트는, H263_B 제한 프로파일에 리스트 한 것과 같은 제한에 의해 정의된다. 다만 다음의 항목에 대해서는 다르다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = "5"
  2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
    1. 프레임 레벨의 제한 :
      • bPicDeblocked 는 1 이라도 좋다
      • bPicDeblocked = 1 의 경우, wDeblockedPictureIndex 는 wDecodedPictureIndex 와 같지도 같지 않아도 좋다
    2. 비트 스트림 버퍼의 제한 :
      • 모든 비트 스트림 버퍼의 내용은, CPCF, CPFMT, 및 보유 D, I, J, N (출력 픽쳐 1 개(살)에 대해 1 개의 순서 방향 참조 픽쳐), 및 T 의 서브 세트와 함께, H. 263 비디오 포맷의 데이터도 포함할 수가 있다.

4.8 H263_D 제한 프로파일

H263_D 제한 프로파일에는, ITU-T 권고 H. 263, 및 특정의 확장 옵션 기능을 지원 하는데 필요한 일련의 기능이 포함된다. 이 프로파일의 지원은, 중기적인 필요 조건이다. 이 기능 세트는, H263_C 제한 프로파일에 리스트 한 것과 같은 제한에 의해 정의된다. 다만 다음의 항목에 대해서는 다르다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = "6"
    2. bDXVA_Func 는 1 (픽쳐의 디코드) 또는 4 (픽쳐의 재샘플링)
  2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
    1. 프레임 레벨의 제한 :
      • bBidirectionalAveragingMode = 1 (H. 263 쌍방향 평균화) 또는 0 (MPEG-2 쌍방향 평균화)
      • bMV_RPS 는 0 또는 1
    2. 매크로 블록 레벨의 제한 :
      • MotionBackward 는 0 또는 1
    3. 비트 스트림 버퍼의 제한 :
      • 모든 비트 스트림 버퍼의 내용은, 보유 K, O, P (한방향 또는 양방향의 클리핑 및 2 의 인수에 의한 사이즈 변경), S, 및 U 의 서브 세트와 함께, H. 263 비디오 포맷의 데이터도 포함할 수가 있다.
  3. bDXVA_Func = 4 (픽쳐의 재샘플링)의 제한 :
    1. PicResampleSourceWidth 와 PicResampleDestWidth 는 같은가, 또는 2 (또는 1/2)의 배수로 비례해야 한다.
    2. PicResampleSourceHeight 와 PicResampleDestHeight 는 같은가, 또는 2 (또는 1/2)의 배수로 비례해야 한다.
    3. PicResampleSourceHeight 와 PicResampleDestHeight 가 동일한 경우는, PicResampleSourceWidth 와 PicResampleDestWidth 는 2 (또는 1/2)의 배수로 비례해야 한다. PicResampleSourceHeight 와 PicResampleDestHeight 가 업 샘플링 처리를 지정하고 있는 경우는, PicResampleSourceWidth 와 PicResampleDestWidth 는 다운 샘플링 처리를 지정해서는 안 된다. 역도 마찬가지.

주 : MotionForward 가 "1" 으로 MotionBackward 가 "1" 의 경우, H. 263 에서는 bBidirectionalAveragingMode 이 "1" 의 지원만이 필요하지만, H263_C 제한 프로파일에서는, bBidirectionalAveragingMode = 0 도 가능하다. 이것은, H263_C 제한 프로파일이, H. 263 비디오에 가세해 MPEG-4 비디오도 지원 할 수 있도록(듯이) 의도해 설계되었다. MPEG-4 는, MPEG-1/MPEG-2 포맷의 쌍방향 평균화를 사용한다.

4.9 H263_E 제한 프로파일

H263_E 제한 프로파일에는, ITU-T 권고 H. 263, 및 특정의 확장 옵션 기능을 지원 하는데 필요한 일련의 기능이 포함된다. 이 프로파일의 지원은, 중기적인 필요 조건은 아니다. 이 기능 세트는, H263_D 제한 프로파일에 리스트 한 것과 같은 제한에 의해 정의된다. 다만 다음의 항목에 대해서는 다르다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = "7"
  2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
    1. 프레임 레벨의 제한 :
      • bPicOBMC 는 0 또는 1 의 언젠가
    2. 매크로 블록 레벨의 제한 :
      • bPicOBMC 가 1 으로 Motion4MV 가 1 의 경우, MotionBackward 는 "0" 이 아니면 안된다.
    3. 비트 스트림 버퍼의 제한 :
      • 모든 비트 스트림 버퍼의 내용은, 보유 F 를 적용한 H. 263 비디오 포맷의 데이터도 포함할 수가 있다.

4.10 H263_F 제한 프로파일

H263_F 제한 프로파일에는, ITU-T 권고 H. 263, 및 특정의 확장 옵션 기능을 지원 하는데 필요한 일련의 기능이 포함된다. 이 프로파일의 지원은, 중기적인 필요 조건은 아니다. 이 기능 세트는, H263_E 제한 프로파일에 리스트 한 것과 같은 제한에 의해 정의된다. 다만 다음의 항목에 대해서는 다르다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = "8"
  2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
    4. 프레임 레벨의 제한 :
      • bPicBinPB may 는 0 또는 1
    5. 비트 스트림 버퍼의 제한 :
      • 모든 비트 스트림 버퍼의 내용은, 보유 G, M, V, W 의 서브 세트와 함께, H. 263 비디오 포맷의 데이터도 포함할 수가 있다.

4.11 MPEG1_A 제한 프로파일

MPEG1_A 제한 프로파일에는, MPEG-1 비디오를 지원 하는데 필요한 일련의 기능이 포함된다. 이 프로파일의 지원은, 중기적인 필요 조건이다. 이 기능 세트는, 다음의 일련의 제한에 의해 정의된다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = "9"
    2. bDXVA_Func = 1
  2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
    1. 프레임 레벨의 제한 :
      • BPP = 8
      • bSecondField = 0
      • (MacroblockWidth, MacroblockHeight) = (16, 16)
      • (WT, HT) = (8, 8)
      • bChromaFormat = '01' (4:2:0)
      • bPicStructure = '11' (프레임 구조화)
      • bRcontrol = 0
      • bBidirectionalAveragingMode = 0 (MPEG-2 쌍방향 평균화)
      • bMVprecisionAndChromaRelation = '00' (MPEG-2 하프 샘플 움직임)
      • bPicExtrapolation = 0
      • bPicDeblocked = 0
      • bPic4MVallowed = 0
      • bPicOBMC = 0
      • bMV_RPS = 0
      • SpecificIDCT = 0
      • bPicScanFixed = 1
    2. 매크로 블록 레벨의 제한 :
      • MotionType = '10' (프레임 움직임)
      • MBscanMethod = '00' (지그재그) (bConfigHostInverseScan = 0 의 경우)
      • FieldResidual = 0 (프레임 잔여)
      • H261LoopFilter = 0 (H. 261 루프 필터 없음)
    3. 비트 스트림 버퍼의 제한 :
      • 모든 비트 스트림 버퍼의 내용은, MPEG-1 메인 프로파일 비디오 포맷의 데이터를 포함하지 않으면 안 된다.

4.12 MPEG2_A 제한 프로파일

MPEG2_A 제한 프로파일에는, MPEG-2 비디오 메인 프로파일을 지원 하는데 필요한 일련의 기능이 포함된다. 이 프로파일의 지원은, 중기적인 필요 조건이다. 이 기능 세트는, 다음의 일련의 제한에 의해 정의된다.

  1. 접속 모드와 기능 :
    1. wRestrictedMode = 0xA
    2. bDXVA_Func = 1
  2. bDXVA_Func = 1 (픽쳐의 디코드)의 제한 :
    1. 프레임 레벨의 제한 :
      • wRestrictedMode = 0xA
      • BPP = 8
      • (MacroblockWidth, MacroblockHeight) = (16, 16)
      • (WT, HT) = (8, 8)
      • bChromaFormat = '01' (4:2:0)
      • bRcontrol = 0
      • bBidirectionalAveragingMode = 0 (MPEG-2 쌍방향 평균화)
      • bMVprecisionAndChromaRelation = '00' (MPEG-2 하프 샘플 움직임)
      • bPicExtrapolation = 0
      • bPicDeblocked = 0
      • bPic4MVallowed = 0
      • bPicOBMC = 0
      • bMV_RPS = 0
      • SpecificIDCT = 0
      • bPicScanFixed = 1
    2. 매크로 블록 레벨의 제한
      • bConfigHostInverseScan = 0 의 경우, MBscanMethod 는 '00' (지그재그) 또는 '01' (교호 수직)의 어디라도 상관없다
      • H261LoopFilter = 0
    3. 비트 스트림 버퍼의 제한 :
      • 모든 비트 스트림 버퍼의 내용은, MPEG-2 메인 프로파일 비디오 포맷의 데이터를 포함하지 않으면 안 된다.
      • bNewQmatrix[i] = 0 (i = 2 및 3)

4.13 MPEG2_B 제한 프로파일

MPEG2_B 제한 프로파일에는, MPEG-2 비디오 메인 프로파일 및 관련하는 프론트엔드 버퍼 토우 버퍼 서브 픽쳐 블렌딩을 사용한 DVD 서브 픽쳐를 지원 하는데 필요한 일련의 기능이 포함된다. 이 프로파일의 지원은, 중기적인 필요 조건은 아니다. 이 기능 세트는, MPEG2_A 제한 프로파일에 리스트 한 것과 같은 제한에 의해 정의된다. 다만 다음의 항목에 대해서는 다르다.

  3. 접속 모드와 기능 :
    1. wRestrictedMode = 0xB
    2. bDXVA_Func = 1 (픽쳐의 디코드), 2 (알파 브렌드 데이터의 로드), 또는 3 (알파 브렌드 콤비네이션) (이러한 모든 값이 지원 되지 않으면 안 된다)

4.14 MPEG2_C 제한 프로파일

The MPEG2_C 제한 프로파일에는 MPEG-2 비디오 메인 프로파일을 지원 하기 위해서 필요한 일련의 feature가 포함된다. 이 프로파일의 지원은 중기적 요건이다. 이 feature 세트는 위의 MPEG2_A 제한 프로파일에 리스트 한 것과 같은 제한에 의해 정의된다, 다만 다음의 항목에 대해서는 다르다 :

  1. 접속 모드와 기능 :
    1. wRestrictedMode = 0xC
    2. 3.5. 2 장으로 설명되고 있는 최소 상호 운용성에 대해, bConfigResidDiffHost=0 와 bConfigResidDiffAccelerator=1 를 가지는 멤버가 1 개 추가된다.

MPEG2_C 제한 프로파일은 MPEG2_A 프로파일의 가속기 프로파일을 완화하는 것에 의해 정의되고 (이것에 의해 가속기는 MPEG2_A 의 최소 상호 운용성 세트의 멤버를 지원 하지 않고 끝난다) , MPEG2_A 를 지원 하는 모든 가속기는 MPEG2_C 프로파일을 지원 해야 한다. 같이 MPEG2_D 프로파일을 지원 하는 모든 가속기는 MPEG2_C 프로파일을 지원 해야 한다.

4.15 MPEG2_D 제한 프로파일

MPEG2_D 제한 프로파일에는 MPEG-2 비디오 메인 프로파일의 지원에 필요한 feature 세트라고 연구 최종 단계 하드웨어 서브 픽쳐 블렌딩을 사용한 DVD 서브 픽쳐를 조합하기 위해서(때문에) 필요한 feature 세트가 포함된다. 이 feature 세트는 위의 MPEG2_B 제한 프로파일에 리스트 한 것과 같은 제한에 의해 정의된다, 다만 다음의 항목에 대해서는 다르다 :

  1. 접속 모드와 기능 :
    1. wRestrictedMode = 0xD
    2. 3.5. 2 장으로 설명되고 있는 최소 상호 운용성에 대해, bConfigResidDiffHost=0 와 bConfigResidDiffAccelerator=1 를 가지는 멤버가 1 개 추가된다.
    3. bConfigBlendType 는 0 이나 1 의 언젠가 (가속기가 결정)
    4. bConfigDataType 는 임의의 값 (가속기가 결정)

MPEG2_D 제한 프로파일은 MPEG2_B 프로파일의 가속기 프로파일을 완화하는 것에 의해 정의되고 (이것에 의해 가속기는 MPEG2_B 의 최소 상호 운용성 세트의 멤버를 지원 하지 않고 끝난다), MPEG2_B 를 지원 하는 모든 가속기는 MPEG2_D 프로파일을 지원 해야 한다.

5 IAMVideoAccelerator 처리

IAMVideoAccelerator 는, Windows 2000 내에 DirectX VA 처리 메카니즘을 갖추기 위한 인터페이스이다. 이 섹션에서는, DirectX VA 데이터 포맷이 이 인터페이스를 개입시켜 어떻게 송신되지 않으면 안 될까를 설명한다.

5.1 IAMVideoAccelerator 인터페이스

이하는, 현재의 Microsoft DirectShow® 문서 세트에 있는 IAMVideoAccelerator 의 사용에 관한 개요 설명을 확장, 또 향상시키는 것을 의도하고 있다.

주 : 이 인터페이스는, Microsoft Windows® 2000 으로 이용 가능하다.

오버레이 믹서의 입력 핀은 IAMVideoAccelerator 인터페이스를 지원 하고 있어, 디코더의 출력 핀은 IAMVideoAcceleratorNotify 인터페이스를 지원 하고 있다. 필터 핀 접속의 이벤트는 다음의 순서로 발생한다.

  1. 필터 그래프 매니저가 디코더의 출력 핀의 IPin::Connect 를 호출한다. AM_MEDIA_TYPE 는 옵션 파라미터이다.
    • AM_MEDIA_TYPE 는, 미디어 타입을 기술하는 데이터 구조체이다. 이 구조체에는, 메이저 타입 GUID (이 경우는 MEDIATYPE_Video), 서브 타입 GUID (이 경우는 비디오 가속기 GUID), 및 그 외 다양한 것이 포함된다. 그 1 개(살)은, 이 경우라면 비압축 비디오 픽쳐의 폭과 높이를 포함한, 미디어에 대한 정보를 저장 한 포맷 타입 GUID 이다 (많은 경우 MPEG1VIDEOINFO ,VIDEOINFOHEADER ,MPEG2VIDEOINFO , 또는 VIDEOINFOHEADER2 구조체).
    • AM_MEDIA_TYPE 가 존재하는 경우는, 디코더에, 지정된 미디어 타입을 사용해 동작하도록 지시한다. 이 지정은,"완전 지정" 의 경우와 "부분 지정" 의 경우가 있다. "완전 지정" 의 경우, 디코더는 보통, 그 미디어 타입을 사용해 동작하려고 한다. "부분 지정" 의 경우,"부분 지정" 미디어 타입과 모순되지 않는 방법에서의 접속에 사용할 수 있는 "완전 지정" 호환 동작 모드를 찾아내려고 한다.
    • 접속에 사용하는 "완전 지정" 미디어 타입을 찾을 때는, 보통,"부분 지정" 미디어 타입과 호환성이 있는, 출력 핀이 지원 하고 있는 모든 "완전 지정" 미디어 타입을 조사해, 접속이 성공할 때까지 1 개(살)씩 시험한다고 하는 방법을 사용한다. IPin::Connect 호출에 AM_MEDIA_TYPE 가 포함되지 않고, 그러나 모든 미디어 타입을 체크할 필요가 있는 출력 핀이 있는 경우, 같은 처리를 한다.
  2. 디코더측에서, 특정의 AM_MEDIA_TYPE (비디오 가속기 GUID 를 포함한다)가 다운 스트림 입력 핀에 의해 지원 되고 있는지 어떤지 조사할 필요가 있는 경우, 그 핀의 IPin::QueryAccept (AM_MEDIA_TYPE 의 서브 타입으로서 비디오 가속기 GUID 를 지정)를 호출하는지, 또는 후술의 항목 5 에 해설하도록(듯이), 그 핀에 접속을 시도하는 것에 의해 조사할 수가 있다.
  3. 디코더측에서, 다운 스트림 입력 핀이 어느 비디오 가속기 GUID 를 지원 하고 있는지를 인식하고 있지 않고, 또 다운 스트림 입력 핀의 IPin::QueryAccept 를 호출하는 것에 의해 특정의 몇개의 비디오 가속기 GUID 만을 지명하는 것을 피하고 싶은 경우, 디코더는,IAMVideoAccelerator::GetVideoAcceleratorGUIDs 를 호출해, 그 핀이 지원 하고 있는 비디오 가속기 GUID 의 일람을 취득할 수가 있다.
  4. 몇개의 특정의 비디오 가속기 GUID 에 대해서는, 디코더는 다운 스트림 입력 핀의 IAMVideoAccelerator::GetUncompFormatsSupported 를 호출해, 특정의 비디오 가속기 GUID 의 생성에 사용할 수 있는 DDPIXELFORMAT 의 일람을 취득할 수가 있다. 돌려주어지는 일람은, 추천의 정도가 높은 것으로부터 순서에 리스트 되고 있는 (가장 추천 되는 포맷이 최초로 기재된다) 것이라고 보는 것이 좋다.
  5. 디코더는 다운 스트림 입력 핀의 IPin::ReceiveConnection 를 호출한다. 그 때, 미디어 타입의 서브 타입으로서 적절한 비디오 가속기 GUID 를 지정한 AM_MEDIA_TYPE 를 건네준다. 이것에 의해, 비압축 출력 표면의 생성을 포함해 동작에 필요한 접속이 설정된다. 이 표면은, AM_MEDIA_TYPE 에 있는 폭과 높이나, 후술 하는 호출에 의해 찾아낼 수 있던, 할당하는 표면의 수나, 그 외 비디오 가속기가 보관 유지하고 있어 표면 생성 목적으로 사용하고 싶은 정보 (비디오 가속기 GUID 자체등)를 사용해 할당할 수 있다. 다운 스트림 입력 핀이, 비디오 가속기 GUID, 또는 그 외의 접속에 관한 어떠한 요소를 거부했을 경우,IPin::ReceiveConnection 가 실패하는 일이 있다. IPin::ReceiveConnection 가 실패했을 경우는, 돌려주어지는 HRESULT 로 그것이 나타난다. 디코더는, AM_MEDIA_TYPE 에 있는 다른 비디오 가속기 GUID 를 사용하는 등 해, 호출을 재시행할 수가 있다.
    • 주 : IPin::ReceiveConnection 를 호출해 접속을 시행해, 접속이 성공했는지 어떠했는지 체크 하면 말하는 것은, 다운 스트림 입력 핀이 지원 하고 있는 미디어 타입을 디코더측에서 조사하는 이제(벌써) 1 개의 방법이며, 가장 확실한 방법이기도 하다.
  6. IPin::ReceiveConnection 의 실행중, 오버레이 믹서는, 할당하는 비압축 표면의 수를 계산하기 위해(때문에), 디코더의 IAMVideoAcceleratorNotify::GetUncompSurfacesInfo 를 호출해, 비디오 가속기 GUID 와 AMVAUncompBufferInfo 구조체를 건네준다. 디코더는, AMVAUncompBufferInfo 구조체를 돌려준다.
    • AMVAUncompBufferInfo 데이터 구조체에는, 특정의 타입에 할당할 수 있는 표면수의 최대치와 최소 값, 및 할당할 수 있는 표면의 픽셀 포맷을 기술한 DDPIXELFORMAT 구조체가 포함된다.
    • 마이너스적인주 : 실제로 IAMVideoAcceleratorNotify::GetUncompSurfacesInfo 의 호출로 디코더에게 건네지는 것은, 비디오 가속기 GUID 뿐인다.
  7. 오버레이 믹서는 디코더의 IAMVideoAcceleratorNotify::SetUncompSurfacesInfo 를 호출한다. 그 때 디코더에, 실제로 할당할 수 있었던 비압축 표면의 수를 건네준다.
  8. 오버레이 믹서는, 비디오 가속기의 초기화에 필요한 데이터를 취득하기 위해(때문에), 디코더의 IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData 를 호출한다.
  9. 디코더는, 일련의 AMVACompBufferInfo 데이터 구조체 (비디오 가속기 GUID 에 사용되는 압축 데이터 버퍼의 각 타입 마다 1 개(살)이 대응한다)를 취득하기 위해(때문에),IAMVideoAccelerator::GetCompBufferInfo 를 호출한다. 그 때, 비디오 가속기 GUID, AMVAUncompDataInfo 구조체, 및 압축 버퍼 타입의 수를 건네준다.
    • AMVAUncompDataInfo 구조체에는, 디코드된 비압축 데이터의 폭과 높이를 픽셀로 나타낸 값과 비압축 픽쳐의 DDPIXELFORMAT 가 포함된다.
    • 돌려주어지는 AMVACompBufferInfo 데이터 구조체에는 각각 다음의 항목이 포함된다.
      • 특정의 타입에 필요한 압축 버퍼의 수.
      • 생성 하는 표면의 폭과 높이 (실제의 의미를 가진다, 또는 가지지 않는 필드).

        주 : DirectDraw 의 압축 버퍼의 표면 할당 처리는, 현재로서는 이러한 표면의 폭 또는 높이가 215 이상이 되는 것을 상정하고 있지 않는, 다만 표면 allocater는 이 제한을 범해도 분명한 실패는 되지 않는다. 이 때문에 드라이버는, 그러한 극단적인 사이즈를 피하도록(듯이), 압축 버퍼 메모리에의 요구를 구성하는 편이 좋다. 예를 들어, 폭이 "1" 으로 높이가 "65536" 의 버퍼보다, 폭이 "1024" 로 높이가 "64" 의 버퍼를 요구하는 편이 좋다.
      • 표면에 의해 사용되는 바이트의 합계수.
      • DirectDrawSurface 오브젝트를 정의해, 압축 데이터를 저장 하는 표면의 생성 기능을 기술한 DDSCAPS2 타입의 구조체.
      • 압축 데이터를 저장 하는 표면의 생성에 사용하는 픽셀 포맷을 기술한 DDPIXELFORMAT (실제의 의미를 가진다, 또는 가지지 않는 필드).
  10. 주 : 몇개의 디코더의 IAMVideoAcceleratorNotify 인터페이스 메소드에의 오버레이 믹서의 호출은, 오버레이 믹서의 IPin::ReceiveConnection 에의 디코더의 호출내에서 발생하는 것이 가능하고, 보통 그처럼 발생한다. 이것은 특히 다음의 경우에 들어맞는다.
    • IAMVideoAcceleratorNotify::GetUncompSurfacesInfo
    • IAMVideoAcceleratorNotify::SetUncompSurfacesInfo
    • IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData
  11. 주 : 동적 포맷 변경을 지원 하기 위한(해), 필터가 접속되고 실행되고 있는 동안, 위의 메소드에 의해 IPin::ReceiveConnection 및 그 외의 메소드를 호출할 수가 있다. 이 기능은 동적 포맷 변경을 지원 하기 위해서 준비되어 있지만, 다만 모든 데이터 세트가 최초부터 한번 더 시작 되어 모든 참조 픽쳐 정보가 없어지는 H. 263 의 동적 포맷 변경은 대상이 되지 않는다.

초기화 후의 처리중의 IAMVideoAccelerator 의 사용에 대해 다음에 해설한다.

  1. 디코더는, 출력 픽쳐의 생성 처리를 시작 하기 위한(해), 각 비압축 데이터 버퍼에 대해서 IAMVideoAccelerator::BeginFrame 를 호출한다. 그 때, AMVABeginFrameInfo 구조체를 송신한다.
    • AMVABeginFrameInfo 구조체에는, 행선지 버퍼의 인덱스, 다운 스트림에 송신하는 데이터에의 포인터, 및 디코더가 읽어내기 위해서(때문에) 가속기가 데이터를 배치할 수 있는 장소를 나타내는 포인터가 포함된다.
    • 주 1 : 가속기는 실제로는 행선지 버퍼의 인덱스를 받지 않고, 인덱스는 다운 스트림에 가기 전에 오버레이 믹서에 의해 변환된다.
    • 주 2 : IAMVideoAccelerator::BeginFrame 는,IAMVideoAccelerator::EndFrame 에의 호출동안에 몇 번이라도 호출할 수가 있다.
    • 주 3 : 인터페이스 처리 중(안)에서는, 비트 스트림내의 개개의 픽쳐를 처리하기 위해서,IAMVideoAccelerator::BeginFrame 및 IAMVideoAccelerator::EndFrame 를 호출할 필요가 있다고 하는 전제는 없다. 인터페이스에 관해서 IAMVideoAccelerator::BeginFrame 가 실행하는 것은 다음의 2 개이다.
      • 오버레이 믹서내에서, 인덱스와 비압축 표면과의 사이에 관련짓고를 생성 한다.
      • 디바이스 드라이버내에서 특정의 함수를 호출하는 수단을 제공한다 (임의의 데이터를 디코더와 디바이스 드라이버의 사이에 교환하는 수단의 지원을 포함한다).

    2. (그렇지만, DirectX VA 조작에는 비트 스트림의 각 픽쳐의 처리에는 IAMVideoAccelerator::BeginFrame 와 IAMVideoAccelerator::EndFrame 호출이 필요하다고 하는 요건이 있는, 이것에 대해서는 후에 설명한다. )

  2. 비압축 데이터를 가속기에 송신하기 위해(때문에), 디코더는 다음의 메소드를 호출한다.
    • IAMVideoAccelerator::GetBuffer . 지정된 버퍼에의 액세스를 락 및 취득하기 위해(때문에) (액세스를 취득하기 위해서 이 메소드를 앞에 두고 호출하지 않은 경우). 이 메소드의 사용법으로서 IAMVideoAccelerator::BeginFrame 의 호출 대상이 된 마지막 비압축 출력 픽쳐의 내용의 카피를 취득하는데 사용할 수 있는 특별한 방법이 있다. 다만 그 행선지 버퍼 인덱스에 대해서 IAMVideoAccelerator::EndFrame 가 불려 가지 않은 것이 조건이 된다. IAMVideoAccelerator::GetBuffer 를 호출하기 위해서(때문에), 디코더는 AMVACompBufferInfo 데이터 구조로부터 몇개의 정보가 필요하다. 이것은,IAMVideoAccelerator::GetCompBufferInfo 또는 IAMVideoAccelerator::GetInternalCompBufferInfo 를 호출하는 것으로 취득할 수 있다 (어느쪽이나 같은 정보를 취득하는 것 같다). 경고 : 디코더가 IAMVideoAccelerator::GetInternalCompBufferInfo 를 호출한 결과, 디바이스 드라이버의 DdMoCompGetInternalInfo 가 불려 갈 것은 없다.
    • IAMVideoAccelerator::Execute . AMVABUFFERINFO 데이터 구조체의 배열로 지시받은 일련의 압축 버퍼에 포함되는 데이터를 처리하는 편이 좋은 일을 나타낸다. 이 호출에서는, 함수 코드 dwFunction 가 드라이버에게 건네진다. 또, 다운 스트림에 송신하는 데이터에의 lpPrivateInputData 포인터, 및 디코더가 읽어내기 위해서(때문에) 다운 스트림 처리가 데이터를 배치할 수 있는 장소를 가리키는 lpPrivateOutputData 포인터도 건네받는다.
    • IAMVideoAccelerator::ReleaseBuffer . 디코더가, 지정된 버퍼의 사용을 완료했기 때문에, 당면은 버퍼에의 락 된 액세스가 필요없게 된 것을 나타낸다. (디코더가 계속해 버퍼를 사용하고 싶은 경우는, 버퍼를 그 이상 사용하지 않다고는 잘라 할 때까지 IAMVideoAccelerator::ReleaseBuffer 를 호출하지 않고 두면,IAMVideoAccelerator::GetBuffer 를 호출하는 필요성을 회피할 수 있다. )
    • IAMVideoAccelerator::QueryRenderStatus . 버퍼가 독해나 기입의 대상으로 해 안전한가 어떤가를 조사하기 (위해)때문에.
  3. 디코더는, 행선지 버퍼의 출력 처리를 완료하기 위해(때문에),IAMVideoAccelerator::EndFrame 를 호출한다. 이 호출 시에 임의의 데이터 다운 스트림을 건네줄 수가 있다 (이 호출의 결과 실행되는 것은, 기본적으로는 이만큼이다). 이 호출에서는 행선지 버퍼의 인덱스는 송신하지 않기 때문에, 여기서 건네주는 임의의 데이터내에서 가리키지 않는 이상 어느 행선지 버퍼가 완료했는지를 가속기에 정확하게 전할 수 없다.
  4. 디코더는, 프레임을 표시하기 위해(때문에), 표시하는 프레임의 인덱스와 시작 및 종료의 타임 스탬프를 포함한 IMediaSample 구조체와 함께,IAMVideoAccelerator::DisplayFrame 를 호출한다.
  5. 마지막으로, 디코더는, 모든 처리가 완료했을 때에,IAMVideoAccelerator::EndFrame 를 호출하는 것에 의해, 시작 된 나머지의 출력 프레임이 모두 완료한 것을 나타내, 미해방의 각 버퍼에 대해서 IAMVideoAccelerator::ReleaseBuffer 를 호출하는 것에 의해, 락 된 버퍼를 모두 해방하는 것이 좋다.

5.2 IAMVideoAccelerator 에의 DirectX VA 의 매핑

5.2. 1 제한 모드 프로파일과 구성의 설정

DirectX VA 로 디코드 가능한 데이터 타입은 다방면에 걸치기 (위해)때문에, 또 이러한 데이터 타입 각각 대해 DirectX VA 에서는 복수의 디코드 구성 (비트 스트림 버퍼, 호스트잔차디코드, 해당 버퍼 타입 마다 암호 있어 또는 암호 없음의 가속기 베이스의 IDCT 등)이 지원 되고 있기 (위해)때문에, 개개의 데이터 타입과 디코드 구성에 각각 일의의 GUID 를 지정하는 것은 너무 좋은 방법이라고는 할 수 없다. 개개로 지정하면(자) GUID 의 수가 너무 많아 지고 (DirectX VA 의 프로파일이 16 개 있어, 각각 16 개의 구성이 있으면(자) 가정하면(자), 256 개의 GUID 를 정의할 필요가 있다), 그것들을 보관 유지하기 위해(때문에)인 만큼 4 KB 의 메모리를 모두 다 써 버려 버린다. DirectX VA 를 IAMVideoAccelerator 에 맵 하는 방법을 결정할 때, 이 점은, 매우 어려운 문제이다. 이것에 대해, 다른 처리 정의는 극히 단순이라고 말할 수 있다. 결과적으로, 우리는 각 데이터 타입 (즉 각 제한 모드 프로파일)에만 대해 일의의 GUID 를 지정해, 추가의 GUID 1 개(살)을, 각 암호 타입에 관련지을 수 있도록(듯이) 한다. 그 후 디코드 구성은, 디코더와 가속기의 사이로, DirectX VA 기능의 개개의 타입에 대해 구성을 확립하기 위한 , 프로브 및 락 처리를 사용한 하위 종속 네고시에이션에 의해 확립된다.

5.2. 2 DirectX VA IAMVideoAccelerator 처리 사양

엄밀한 처리 메카니즘은 다음대로.

  1. 여기서 정의되고 있는 각 제한 모드 프로파일에는 각각, 다운 스트림 입력 핀의 IPin::QueryAccept ,IPin::ReceiveConnection , 및 IAMVideoAccelerator::GetVideoAcceleratorGUIDs 에 리스트 되고 있는 메소드에 의해 지원 가능한 DirectX VA GUID 가 1 개 관련지을 수 있고 있다.
  2. 2) 같이 DirectX VA 로 사용하는 각 암호 프로토콜 타입에는 각각, 다운 스트림 입력 핀의 IPin::QueryAccept ,IPin::ReceiveConnection , 및 IAMVideoAccelerator::GetVideoAcceleratorGUIDs 에 리스트 되고 있는 메소드에 의해 지원 가능한 암호 프로토콜 타입 GUID 가 1 개 관련지을 수 있지 않으면 안 된다. "암호 없음" GUID 인 DXVA_NoEncrypt 의 지원은 암묵의 필수 조건이기 (위해)때문에, 이 리스트에 송신되어서는 안 된다.
  3. 입력 핀에의 다운 스트림에 접속하기 위한 IPin::ReceiveConnection 를 호출한 다음에, 디코더의 IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData 는 그 접속의 접속 모드 정보가 들어가는 DXVA_ConnectMode 데이터 구조체에의 포인터를 돌려주지 않으면 안 된다. IAMVideoAccelerator::GetCompBufferInfo 는 *pdwNumTypesCompBuffers = 16 으로 불려 가지 않으면 안되어, 압축된 버퍼 정보를 돌려주지 않으면 안 되는, 이 정보는 3.4 장으로 정의되고 있도록(듯이) 각 버퍼의 타입수가, 돌아간 AMVACompBufferInfo 데이터 구조체의 배열내에서 제로로부터 시작되는 인덱스로 직접 사용 가능하게 되어 있다. 이것은, 사용되지 않는 버퍼 타입 (버퍼 타입 0 을 포함한, 왜냐하면 그 버퍼 타입에는 사용이 정의 있고 되지 않기 때문에이다)에 대해서는, 가속기 드라이버가 AMVACompBufferInfo 데이터 구조체를 더미 파라미터 (ex. dwNumCompBuffers=0, dwWidthToCreate=0, dwHeightToCreate=0, and dwBytesToAllocate=0) 값의 형태로 제공하는 것을 요구한다.
  4. DXVA 기능의 지시, 및 관련지을 수 있었던 데이터 버퍼는,IAMVideoAccelerator::Execute 를 사용해 송신된다. DXVA 기능은 호출의 dwFunction 파라미터로 지시받는다. 초기화에 있어 의미를 가지는 DXVA 기능은, DXVA_ConfigQueryOrReplyFunc 및 DXVA_EncryptProtocolFunc 뿐이다.
    • dwFunction 에 DXVA_ConfigQueryOrReplyFunc 가 포함되는 경우, 이 호출로 가속기에 데이터를 건네주기 위한 lpPrivateInputData 포인터는, 구성 데이터 구조체를 가리켜, 가속기로부터 정보를 받기 위한 lpPrivateOutputData 포인터는, 대체 또는 복제의 구성 데이터 구조체를 저장 할 수 있는 영역을 가리키지 않으면 안 되는, AMVABUFFERINFO 의 배열의 pamvaBufferInfo 포인터는 NULL, dwNumBuffers 는 제로가 아니면 안된다. 돌려주어지는 HRESULT 는, S_OK 또는 S_FALSE 가 되는지, 또는 프로토콜 실행에 있어서의 심각한 문제가 있으면 (무효인 구성 파라미터 등) E_FAIL 나 E_INVALIDARG 혹은 그 외의 에러를 나타내는 HRESULT 가 된다. DXVA_ConfigQueryOrReplyFunc 의 모든 사용에 대응하는 IAMVideoAccelerator::Execute 의 호출은, 다른 모든 IAMVideoAccelerator::Execute 호출보다 먼저 실행되지 않으면 안 된다.
    • dwFunction 에 DXVA_EncryptProtocolFunc 가 포함되는 경우, 이 호출로 가속기에 데이터를 건네주기 위한 포인터는, DXVA_EncryptProtocolHeader 로 시작되는 암호화 프로토콜 데이터 구조체를 가리켜, 가속기로부터 정보를 받기 위한 포인터는, 암호화 프로토콜로부터 돌려주어지는, DXVA_EncryptProtocolHeader 로 시작되는 데이터 (증명서등)를 저장 할 수 있는 영역을, 가리키지 않으면 안 된다. 돌려주어지는 HRESULT 는, 암호화 프로토콜이 정상적으로 동작하고 있으면 S_OK 가 되어, 프로토콜 실행에 있어서의 심각한 문제가 있으면 E_FAIL 나 E_INVALIDARG 또는 그 외의 에러를 나타내는 HRESULT 가 된다.
    위의 같은 처리의 초기화가 끝난 후, 실제의 디코더의 처리는 다음과 같이 진행한다.
  5. IAMVideoAccelerator::BeginFrame 는 압축된 버퍼 파라미터로 bDXVA_Func 를 보내기 전에 불려 가지 않으면 안 되는, bDXVA_Func 는 비압축 목적지 표면에의 기입을 발생시킨다. DirectX VA 에 있어서의 IAMVideoAccelerator::BeginFrame 의 목적은, 목적지 표면을 인덱스값과 묶어 목적의 비디오 가속기 드라이버에 표면 기입의 초기화를 통지하는 것이다, 이것에 의해 드라이버는 표면이 오버라이드(override) 될 준비가 되어 있을지 어떨지를 나타내 대응할 수가 있다. IAMVideoAccelerator::BeginFrame 내에게 건네지는 AMVABeginFrameInfo 구조체에는 IAMVideoAccelerator::BeginFrame (한편 dwSizeInputData 는 2 가 아니면 안된다) 내에게 건네지는 후레임인젝스와 적합하는 1 WORD wBeginPictureIndex 파라미터의 pInputData 포인터가 들어간다. 이것은 압축 버퍼내에서 표면에 커멘드를 기입하기 위해서(때문에) 이용되는 인덱스이다 (ie. wDecodedPictureIndex, wDeblockedPictureIndex, wBlendedDestinationIndex, wPicResampleDestPicIndex 로서 이용된다). AMVABeginFrameInfo 의 pOutputData 포인터는 NULL 가 아니면 안된다 (한편 dwSizeOutputData 는 "0" 이 아니면 안된다). IAMVideoAccelerator::BeginFrame 가 돌려주는 HRESULT 는 다음대로 :
    • S_OK : 비압축 표면이 유효해 사용 준비 완료.
    • E_PENDING : 비압축 표면은 아직 유효하지 않지만, 곧바로 유효하게 된다 (ie. 비압축 표면은 표시용으로 읽히고 있어 표면의 읽어들여, 표시는 아직 완료하고 있지 않다).
    • E_FAIL 혹은 E_INVALIDARG : 데이터 포맷화 프로곳 에러가 발생했을 경우에게만 나타나는 에러 (dwSizeInputData 혹은 NULL 이외의 pOutputData 와 같이 잘못한 값).
  6. DXVA 기능의 지시, 및 관련지을 수 있었던 데이터 버퍼는,IAMVideoAccelerator::Execute 를 사용해 송신된다. 1 보다 큰 bDXVA_Func 값은 IAMVideoAccelerator::Execute 에의 같은 호출로 나타나는 경우가 있다. bDXVA_Func 값은 호출의 dwFunction 파라미터내에 팩 되지 않으면 안 된다. bDXVA_Func 의 0xFF 값은, bDXVA_Func 는 2 혹은 4 바이트 확장되는 것을 나타낸다. 2 번째의 바이트도 0xFF 라면, 이것은 bDXVA_Func 가 4 바이트에 확장되고 있는 것을 나타낸다. 제 3 바이트의 상위 4 비트가 0xF 또는 0x0 의 경우는, bDXVA_Func 에 DXVA_ConfigQueryOrReplyFunc 또는 DXVA_EncryptProtocolFunc 가 포함되어 있는 것을 나타낸다. 멀티 바이트 커멘드는, dwFunction 종료후의 계속을 지시해서는 안 된다. 다음 일에 디코더는 주위를 기울이지 않으면 안 되는, IAMVideoAccelerator::Execute 에의 같은 호출해로 지정되는 다른 bDXVA_Func 값간에 시퀀셜인 의존성이 없는 것, 그리고 연속적인 IAMVideoAccelerator::Execute 호출전에 IAMVideoAccelerator::BeginFrame 와 IAMVideoAccelerator::QueryRenderStatus 의 적절한 호출에 의해 모든 잠재적인 긴급 조건 (픽쳐 디코딩과 서브 픽쳐 블렌딩의 사이, 서브 픽쳐 로딩과 서브 픽쳐 블렌딩의 사이등)을 피할 수 있는 것.
    • dwFunction 에 DXVA_ConfigQueryOrReplyFunc 가 있다면, 이 호출로 가속기에 데이터를 건네주기 위한 lpPrivateInputData 포인터는 구성 데이터 구조체를 가리키지 않으면 안 되는, 가속기로부터 정보를 받기 위한 lpPrivateOutputData 포인터는 다른 혹은 카피된 구성 데이터 구조체를 둘 수가 있는 범위를 가리키지 않으면 안 되는, AMVABUFFERINFO 의 배열용의 pamvaBufferInfo 포인터는 NULL 가 아니면 안되는, dwNumBuffers 는 제로가 아니면 안된다. 돌아간 HRESULT 에는 쿼리의 결과를 나타내는 S_OK 나 S_FALSE , 혹은 E_FALSE 나 E_INVALIDARG 혹은 (부적절한 구성 파라미터와 같은) 프로토콜 실행의 심각한 문제의 이벤트에 HRESULT 에러 식별자가 들어간다. DXVA_ConfigQueryOrReplyFunc 의 모든 사용에 대응하는 IAMVideoAccelerator::Execute 의 호출은, 다른 모든 IAMVideoAccelerator::Execute 호출보다 먼저 실행되지 않으면 안 된다.
    • dwFunction 에 DXVA_EncryptProtocolFunc 가 포함되는 경우, 이 호출로 가속기에 데이터를 건네주기 위한 lpPrivateInputData 포인터는, DXVA_EncryptProtocolHeader 로 시작되는 암호화 프로토콜 데이터 구조체를 가리켜, 가속기로부터 정보를 받기 위한 lpPrivateOutputData 포인터는, (DXVA_EncryptProtocolHeader 로 시작된다) 암호화 프로토콜로부터 돌려주어지는, DXVA_EncryptProtocolHeader 로 시작되는 데이터 (증명서등)를 저장 할 수 있는 영역을 가리키지 않으면 안 되는, AMVABUFFERINFO 의 배열용의 pamvaBufferInfo 포인터는 NULL 가 아니면 안되는, dwNumBuffers 는 제로가 아니면 안된다. 돌아간 HRESULT 에는 암호화 프로토콜이 보통에 기능하고 있는 한 S_OK 가 들어가, E_FALSE 나 E_INVALIDARG 혹은 프로토콜 실행의 심각한 문제의 이벤트에 HRESULT 에러 식별자가 들어간다.
    • dwFunction 에 DXVA_ConfigQueryOrReplyFunc 또는 DXVA_EncryptProtocolFunc 가 포함되지 않는 경우, 가속기에 데이터를 건네주기 위한 pPrivateInputData 포인터는, 버퍼 기술 리스트를 가리키지 않으면 안 된다. 각 버퍼의 버퍼 기술 리스트 스트럭션체의 최초의 4 엔트리 (dwTypeIndex, dwBufferIndex, dwDataOffset, 및 dwDataSize)는, 동버퍼의 AMVABUFFERINFO 데이터 구조체의 것과 같지 않으면 안 된다. dwFunction 내에 bDXVA_Func 가 "1" 으로 동일하고, bPicReadbackRequests 가 "1" 의 경우, 가속기로부터 정보를 받기 위한 lpPrivateOutputData 포인터는, 가속기로부터의 읽어 반환 데이터가 저장 되는 영속적 메모리 (heap) 영역을 가리키지 않으면 안 되는, 이 영역은 다시 읽어 매크로 블록 데이터로 가속기로부터 기입해진다 (이러한 데이터는 아래의 항목 10 으로 설명되고 있도록(듯이), 같은 픽쳐 파라미터 버퍼를 기입하는 IAMVideoAccelerator::QueryRenderStatus 가 S_OK 를 나타낼 때까지는 존재가 보증되지 않는다). 그 이외의 경우, 가속기로부터 정보를 받기 위한 포인터는, 이하의 몇개의 값이 설정되는 단일의 DWORD 를 가리키지 않으면 안 된다 (특히 오프 호스트의 VLD 처리로 비트 스트림 에러를 보고할 때 유용).
      • "0" : 실행 OK.
      • "1" : 데이터 포맷에 관한 경도의 문제가 발견되었다.
      • "2" : 데이터 포맷에 관한 중대한 문제가 발견되었다.
      • "3" : 데이터 포맷에 관한 심각한 문제가 발견되었다.
      • "4" : 그 외의 심각한 문제가 발견되었다.

      몇개의 타입의 "심각" 인 문제가 나타나는 경우, 대책을 세울 수 없는 한, 소프트웨어 디코더는 기능의 실행을 멈추는 편이 좋다. 가속기로부터 돌려주어지는 이 데이터는, 픽쳐의 버퍼 렌더링이 완료하기 전에, 호스트로부터 읽어내서는 안 된다. 버퍼 렌더링의 완료는,IAMVideoAccelerator::QueryRenderStatus 로 테스트할 수 있다. 돌려주어지는 HRESULT 는, 인터페이스 처리가 정상적으로 동작하고 있으면 S_OK 가 되어, 프로토콜 실행에 있어서의 심각한 문제가 있으면 E_FAIL 나 E_INVALIDARG 또는 그 외의 에러를 나타내는 HRESULT 가 될 가능성이 있다.

  7. 픽쳐 디코딩 파라미터 버퍼는 IAMVideoAccelerator::Execute 의 bDXVA_Func 를 "1" 으로서 사용했을 때, 각 픽쳐의 디코딩에 보내지는 최초의 버퍼에 없으면 안 되는, 그리고 비트 스트림내의 픽쳐를 디코드하는 모든 버퍼는 다음의 픽쳐를 디코드하는 버퍼의 전에 보내지지 않으면 안 된다. 매크로 블록 제어 커멘드 버퍼가 보내지면(자), 대응하는 잔차데이터 버퍼가 같은 IAMVideoAccelerator::Execute 호출로 (같은 매크로 블록에 데이터를 가지고) 보내지지 않으면 안 된다.
  8. IAMVideoAccelerator::EndFrame 는 모든 압축 버퍼가 보내진 다음에 불려 가지 않으면 안 되는, 그것은 지정한 비압축 표면내의 출력 내용을 생성 한다 (ie. wDecodedPictureIndex, wDeblockedPictureIndex, wBlendedDestinationIndex, 혹은 wPicResampleDestPicIndex 로 지정된 조작의 결과). 이 IAMVideoAccelerator::EndFrame 호출의 목적은, 비디오 가속기 하드웨어로 지정한 조작에 필요한 모든 데이터는 보내진 일을 알리는 것이다. IAMVideoAccelerator::EndFrame 경유로 다운 스트림을 보내는 데이터에의 포인터는 종료하고 있는 프레임의 인덱스를 가지는 1 WORD wEndPictureIndex 에의 포인터가 아니면 안된다. 이 파라미터는 관련하는 압축 버퍼에 보내기 전의 IAMVideoAccelerator::BeginFrame 호출로 지정되는 wBeginPictureIndex 값과 일치해야 한다. IAMVideoAccelerator::EndFrame 호출에 이어, IAMVideoAccelerator::BeginFrame 의 다른 호출에 의해 이것이 발생 당하고 결과적으로 S_OK 가 돌아갈 때까지는, 인덱스 wEndPictureIndex 의 비압축 표면은 픽쳐의 wDecodedPictureIndex, wDeblockedPictureIndex, wBlendedDestinationIndex, 혹은 wPicResampleDestPicIndex 내에 있어서는 안 된다. 그러나, 목적지 표면 인덱스는 wForwardRefPictureIndex, wBackwardRefPictureIndex, wPicResampleSourcePicIndex, 혹은 bRefPicSelect[i] 와 같이 계속되어 일어나는 read 액세스 커멘드내에도 있을 지도 모르다. 어떤 종류의 데이터 포맷 에러나 프로토콜 에러가 없는 한, IAMVideoAccelerator::EndFrame 에 의해 돌아가는 HRESULT 는 S_OK 가 아니면 안되는, 위의 에러의 경우 E_FAIL 나 E_INVALIDARG 혹은 다른 에러 식별자가 된다.
  9. 필드 베이스의 디코드의 경우 (ex. MPEG-2 비트 스트림), 비트 스트림내 기능 픽쳐의 가속기 인터페이스의 비압축 표면에의 1 대 1 매핑은 없다. MPEG-2 비트 스트림으로 필드 픽쳐를 디코드 하면 와, 비압축 표면에 1 개의 완전한 출력을 디코드해 생성하기 위한 2 개의"픽쳐"가 있다. DirectX VA 인터페이스 정의에서는, 각 프레임은 wDecodedPictureIndex, wDeblockedPictureIndex, wBlendedDestinationIndex, 혹은 wPicResampleDestPicIndex 의 각 사용에 대응한다. 그러므로, 출력비압축 표면에 필드 픽쳐를 디코드하려면 IAMVideoAccelerator::BeginFrame 와 IAMVideoAccelerator::EndFrame 에의 2 개의 호출 페어가 필요하다.
  10. dwFlags 를 제로로 IAMVideoAccelerator::QueryRenderStatus 를 호출하면, 비압축 표면에의 모든 기입 조작이 완료하면 S_OK 를 돌려주어, 그 조작이 아직 완료하고 있지 않으면 E_PENDING 가 돌아간다. 이 호출은 개별의 wEndPictureIndex 로 IAMVideoAccelerator::EndFrame 를 호출한 후에 일어나는 경우가 있어, wDecodedPictureIndex, wDeblockedPictureIndex, wBlendedDestinationIndex, 혹은 wPicResampleDestPicIndex 내에 wEndPictureIndex 가 설정되어 보내진 버퍼 상태를 체크한다. 프로토콜 에러의 이벤트에서는, E_FAIL 나 E_INVALIDARG 혹은 에러 식별자가 돌아간다.

5.2. 3 motion compensation 디바이스 드라이버와의 처리 위에의 통신

여기에서는, DirectX VA 인터페이스의motion compensation 디바이스 드라이버의 측면으로 도착해 해설한다 ( 「Windows 2000 DDK - Graphics Drivers - Design Guide - 3.0 DirectDraw DDI - 3.12 Motion Compensation 」를 참조). 다음에,DD_MOTIONCOMPCALLBACKS 구조체를 사용해 액세스 되는 엔트리에 관련하는 항목을 열거한다.

  1. 해당 처리의 시작시에, 소프트웨어 디코더가 비디오 가속화 오브젝트의 사용을 시작 하는 것을 드라이버에 통지하기 위해(때문에), 디바이스 드라이버의 DdMoCompCreate 가 사용된다.
  2. IAMVideoAccelerator::GetVideoAcceleratorGUIDs 로부터 수신되는 GUID 는, 디바이스 드라이버의 DdMoCompGetGUIDs 로부터 생긴다.
  3. 다운 스트림 입력 핀의 IAMVideoAccelerator::GetUncompFormatsSupported 에의 호출은, 디바이스 드라이버의 DdMoCompGetFormats 로부터의 데이터를 돌려준다.
  4. 디코더의 IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData 로부터의 DXVA_ConnectMode 데이터 구조체는, 디바이스 드라이버의 DdMoCompCreate 에게 건네진다.
  5. IAMVideoAccelerator::GetCompBufferInfo 로부터 돌려주어지는 데이터는, 디바이스 드라이버의 DdMoCompGetBuffInfo 로부터 생긴다.
  6. IAMVideoAccelerator::Execute 를 사용해 송신된 버퍼는, 디바이스 드라이버의 DdMoCompRender 에 의해 수신된다.
  7. IAMVideoAccelerator::QueryRenderStatus 를 사용 하면, 디바이스 드라이버의 DdMoCompQueryStatus 가 불려 간다. DdMoCompQueryStatus 로부터의 DDERR_WASSTILLDRAWING 의 반환값을 호스트 디코더는 IAMVideoAccelerator::QueryRenderStatus 로부터의 E_PENDING 의 반환값으로서 본다.
  8. IAMVideoAccelerator::BeginFrame 에 송신된 데이터는, 디바이스 드라이버의 DdMoCompBeginFrame 에 의해 수신된다. DdMoCompBeginFrame 로부터의 E_PENDING 의 반환값을 호스트 디코더는 IAMVideoAccelerator::BeginFrame 로부터의 E_PENDING 의 반환값으로서 본다.
  9. IAMVideoAccelerator::EndFrame 에 송신된 데이터는, 디바이스 드라이버의 DdMoCompEndFrame 에 의해 수신된다.
  10. 해당 처리의 마지막으로, 현재의 비디오 가속화 오브젝트가 그 이후 사용되지 않기 때문에, 드라이버가 필요한 클린 업을 실행할 수 있는 것을 드라이버에 통지하기 위해(때문에), 디바이스 드라이버의 DdMocompDestroy 가 사용된다.


DirectShow 에 의한 DVD 디코더의 개발

여기에는, DirectShow 의 모든 프로퍼티 세트 및 인터페이스에 관한 참조 페이지로의 링크가 포함된다. 이러한 프로퍼티 세트 및 인터페이스에는, DVD 전용의 것과 DVD 의 디코드에 대해 광범위하게 사용되는 것이 있다. 여기에 올렸지만 그 밖에, 디코더와 그 핀은 「DirectShow 필터의 개발」에 기재되어 있는 범용의 DirectShow 필터 인터페이스도 지원 할 필요가 있다.

여기에는, 이하의 주제가 포함된다.

  • 디코더의 볼륨 제어
  • Windows 에 있어서의 DVD 의 리젼 변경의 지원

관련 항목

  • DVD 가라오케 프로퍼티 세트
  • DVD 카피 보호 프로퍼티 세트
  • DVD 서브 픽쳐 프로퍼티 세트
  • 핀 프로퍼티 세트
  • IKsPropertySet 인터페이스
  • IVideoFrameStep 인터페이스 (하드웨어 디코더만)
  • IVPConfig 인터페이스 (하드웨어 디코더만)


디코더의 볼륨 제어

어플리케이션은,IBasicAudio 인터페이스를 사용해 오디오의 볼륨을 제어한다. IBasicAudio 인터페이스 핸들러가 KSProxy 에 대해서 제공되고 있다. 디코더가 KSProxy 로부터의 볼륨 커멘드를 처리하려면 , 그 셋업 스크립트에 몇개의 레지스트리 키를 추가할 필요가 있다. 또,KSPROPSETID_Wave 프로퍼티 세트를 지원 하고 있지 않으면 안 된다.

드라이버에 대해서 몇개의 새로운 레지스트리 키를 생성 한다:

  HKLM\SYSTEM\
    CurrentControlSet\Control
      DeviceClasses
        (decoder guid, eg 2721AE....)
          (Pnp id, eg ##? #VDGENDEV#...)
            #GLOBAL
              Device Parameters
                CLSID		REG_SZ	{17CCA...}
                  FriendlyName	REG_SZ	WDM DVD Driver
                    Interfaces <--- 이 키를 생성 한다
                    {b9f8ac3e-0f71-11d2-b72c-00c04fb6bd3d} <-- 이 키도 생성 한다. 이것은 값은 아니다)
      MediaInterfaces
        {b9f8ac3e-0f71-11d2-b72c-00c04fb6bd3d} <-- 이 키를 생성 한다
          (default)		REG_SZ	'KsProxy IBasicAudio handler' <-- 이 값을 설정한다
          IID	REG_SZ	56 a8 68 b3 0a d4 11 ce b0 3a 00 20 af 0b a7 70	<-- 이 캐릭터 라인값을 설정한다

볼륨 제어를 실현하기 위해서(때문에), 드라이버는 KsProperty.Id = KSPROPERTY_WAVE_VOLUME 와 함께 KSPROPSETID_Wave 도 지원 할 필요가 있다. 이 프로퍼티는,IKsPropertySet::Get 및 IKsPropertySet::Set 메소드를 통해 드라이버에게 건네진다. LeftAttenuation 및 RightAttentuation 필드는, 각각 좌측과 우측의 스피커의 볼륨을 0x0000 ~ 0xffff 의 리니어값으로서 지정한다.


DVD 리젼 변경 지원 (Windows)

처음에

여기에서는, DVD 리젼 선택 프로세스가 Microsoft® Windows® 9x 및 Windows 2000 상에서 어떻게 동작할까에 임해서 말한다. 최초로, DVD 리젼 정보의 3 개의 출처에 도착해 설명한다. 다음에, PC 시스템 메이커가 시스템의 초기 DVD 리젼을 어떻게 설정하는지를 설명한다. 마지막으로, DVD 네비게이터가 드라이브, 디코더, 및 디스크간에 어떻게 리젼의 일치를 결정할까에 임해서 설명한다. 여기에서는, 어플리케이션 및 디코더의 개발자가 코드내에 적절한 DVD 리젼 선택 지원을 어떻게 이행 하는지를 나타낸다.

DVD 리젼 정보의 소스

DVD 리젼 정보에는 소스가 3 개 있어, Windows PC 위에의 DVD 의 재생에 대한 리젼은 이 모든 소스에 의해 결정된다.
  • DVD 타이틀
    대부분의 DVD 타이틀에는, 특정의 리젼에 대한 마크가 뒤따르고 있다. 타이틀안에는 1 개의 리젼에서만 재생할 수 있는 것, 복수의 리젼으로 재생할 수 있는 것, 모든 리젼으로 재생할 수 있는 것이 있다.
  • DVD-ROM 드라이브
    DVD-ROM 드라이브에는, RPC Phase 1 으로 RPC Phase 2 (이후는 RPC1 및 RPC2 라고 표기한다)의 2 종류가 있다. RPC1 드라이브에는, 리젼 관리에 대한 하드웨어 지원은 내장되어 있지 않다. 이러한 드라이브의 경우, Windows 는 리젼 변경 회수 정보를 보관 유지해, 리젼은 1 회만 변경할 수 있다. RPC2 드라이브는, 리젼 변경 회수 정보를 하드웨어내 로 유지해, 일반적으로 리젼은 5 회까지 변경할 수 있다.
  • DVD 디코더
    일부의 DVD 디코더, 하드웨어, 소프트웨어는, 특정의 리젼용으로 설정되어 있다. 일반적으로, 유저는 디코더의 리젼을 변경할 수 없다.

Windows 98 및 Windows 2000 에 대해 초기 리젼을 설정하는 방법

PC 의 DVD 드라이브에 대한 초기 DVD 리젼을 선택하는 것은, 시스템 메이커의 역할이다.

  • Windows 98 의 경우
    시스템 메이커는 레지스트리 키 (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\DefaultDVDRegion (바이너리))의 설정에 의해, 드라이브에 대한 디폴트 DVD 리젼을 설정할 수 있다. 이 키의 값은, 최초의 재생에 대해서 설정하는 리젼 번호의 값으로 하지 않으면 안 된다. OPK 빌드를 사용하고 있는 시스템 메이커는 이 값을 "감사 모드 부트 " 의 사이에 레지스트리에 추가할 수 있기 (위해)때문에, 최종 사용자가 초기 리젼을 설정할 것은 없다. DVD 대응 Windows 시스템상에서 DVD 타이틀이 재생되기 전에 이 키가 설정되었을 경우는, Windows 의 컴퍼넌트는 DVD 타이틀의 재생을 최초로 시도할 때 드라이브에 대해서 그 리젼을 선택한다.

    시스템 메이커가 레지스트리에 디폴트 리젼을 설정해, 디폴트 리젼을 포함한 멀티 리젼 디스크를 재생했을 경우, 리젼은 디폴트로 설정되고 디스크가 재생된다. 디스크의 리젼이 디폴트 리젼에 일치하지 않는 경우, 유저는 필요한 리젼에의 변경이 요구된다. (RPC-1 드라이브에 대해서 실시할 수가 있는 변경은 이 한 번 뿐이다. ) 이 디폴트 리젼이 시스템 메이커에 의해 설정되어 있지 않은 경우, Windows 는 operating system의 로케일, 타임 존 등에 기초를 두어 리젼을 선택한다. 최초로 재생되는 디스크가 멀티 리젼 디스크인 경우, Windows 는 로케일, 타임 존 등에 기초를 두어 리젼을 선택해, 가장 작은 리젼 번호와의 일치를 찾는다. 멀티 리젼 디스크 위에의 리젼과 Windows 에 의해 선택된 리젼이 1 개나 일치하지 않았던 경우는, 디스크 위에의 가장 작은 번호를 가지는 리젼이 선택된다.

    메이커가 리젼을 설정하지 않았던 경우, Windows 98 operating system의 베이스콘폰넨트는 operating system 언어 및 타임 존에 근거해 최초의 부트시에 리젼을 선택해, 드라이브를 그 리젼으로 설정한다. 시스템 메이커는 드라이브상에서 리젼을 자유롭게 설정할 수 있지만, 제조 프로세스의 사이로 설정을 하지 않았던 경우는, Windows 가 추측에 근거해 드라이브의 리젼을 선택한다.

  • Windows 2000 의 경우
    Windows 2000 에서는, 머신이 셋업 되고 있는 로케일에 근거해 디폴트 DVD 리젼이 선택된다. Windows 2000 은 항상 이 값을 사용해 DVD 드라이브에 대한 초기 리젼을 설정하지만, 드라이브에 디스크가 들어가 있으면 디스크의 리젼도 사용한다. 시스템 메이커에서는, Windows 2000 의 DVD 드라이버에 대한 초기 리젼을 설정하기 위해서 무엇인가 실시할 필요는 없다.

    RPC1 드라이브의 경우, 부트 업의 사이에 드라이브에 디스크가 없을 때는 머신의 로케일인 만큼 기초를 두어 디폴트 리젼이 설정된다. 부트 업의 사이에 드라이브에 DVD 디스크가 있는 경우는, 디폴트 리젼이 디스크의 리젼과 일치하면 선택되어 드라이브의 리젼이 된다. 일치하지 않는 경우는, 디스크 위에의 가장 작은 번호의 리젼이 드라이브의 초기 리젼으로서 선택된다. 디폴트가 적절하지 않는 경우에, 유저 (또는 시스템 메이커)가 실시할 수 있는 변경은 한 번 뿐이다.

    RPC2 드라이브의 경우, 셋업 프로세스의 사이에 Windows 2000 이 드라이브에 리젼 세트가 없는 것 (프레시 드라이브)을 찾아내면(자), 위의 같은 리젼을 선택하지만, 이것은 드라이브에 디스크가 있는 경우뿐이다. (드라이브에 디스크가 없는 경우, RPC1 드라이브는 리젼을 선택하지 않는다). RPC2 드라이브에 대해서 리젼이 일단 설정되면(자), operating system의 재인스톨 또는 크린 인스톨에 의해 자동적으로 변경될 것은 없다.

Microsoft DVD 네비게이터에 의해 실행되는 것

Microsoft DVD 네비게이터는 이하의 방법을 사용해, PC 상에서 DVD 디스크를 재생중에 리젼의 일치를 확인한다.

DVD 네비게이터는 디스크의 리젼, 드라이버의 리젼, 및 디코더의 리젼을 취득한다. 디스크의 리젼이 "모든 리젼 " 인 경우, DVD 네비게이터는 디스크를 재생한다. 디스크에 모든 리젼에 대한 마크가 뒤따르지 않은 경우, DVD 네비게이터는 디코더에 미리 설정된 리젼이 있을지 어떨지를 확인한다. 디코더에 미리 리젼이 설정되어 있어 그것이 디스크의 리젼과 일치하지 않는 경우는, DVD 네비게이터는 에러를 돌려주어, 현재의 DVD 의 설정에서는 디스크를 재생할 수 없다고 하는 것을 나타낸다. 디코더의 리젼이 디스크의 리젼과 같은 경우, DVD 네비게이터는 드라이브의 리젼이 디스크의 리젼과 같은가 어떤가를 확인한다. 같으면, DVD 네비게이터는 타이틀을 재생한다. 같지 않은 경우는, DVD 네비게이터는 드라이브의 리젼을 변경하기 위한 코드를 호출한다. 사용할 수 있는 리젼 번호가 남지 않은 경우, 리젼 변경의 시도는 실패해, 그 시스템상에서 타이틀을 재생할 수 없다.

다음의 DVD 리젼의 변경

Windows 9x 의 경우, DVD 네비게이터는 DVD 드라이브상에서의 리젼의 변경을 필요하다라고 하는 것이 알면(자), DVDRgn.exe 를 사용해 드라이브 위에의 리젼의 변경을 요구한다. 이 어플리케이션은, operating system의 다른 컴퍼넌트와 합해 리죠나라이즈 된다. 이 어플리케이션은, Windows 98 에 디폴트에서는 인스톨되어 있지 않다. 대상이 되는 시스템에의 인스톨의 방법을 이하에 나타낸다.

Windows 2000 의 경우, DVD 네비게이터는 DVD 매니저로 DVD-ROM 드라이브 디바이스 위에의 프로퍼티 페이지를 호출한다. 리젼을 변경할 필요가 있는 경우는, DVDPlay.exe 어플리케이션에 의해도 프로퍼티 페이지가 불려 간다. 프로퍼티 페이지의 UI 는 DVDRgn.exe 의 UI 에 잘 닮아 있어 operating system에 의해 리죠나라이즈 된다.

RPC1 드라이브의 경우, Windows operating system의 컴퍼넌트가 리젼의 변경을 관리한다. RPC2 드라이브에서는, 리젼 설정은 하드웨어 자체에 보관 유지된다. 사용할 수 있는 변경 번호가 RPC2 드라이브상에 남아 있지 않은 경우, 드라이브는 리젼 변경의 호출해에 실패해, 그것은 operating system내의 리젼 변경 컴퍼넌트에 의해 유저에게 나타난다.

Windows 리젼 변경 지원 컴퍼넌트의 인스톨

어플리케이션 개발자는 Windows 에 짜넣어진 DVD 리젼 변경 지원을 사용해, DVD 재생 어플리케이션내의 리젼을 변경할 수 있다. Windows 9x 및 Windows 2000 플랫폼에 대해 이것을 실행하려면 2 개의 방법이 있다.
  • Windows 9x 의 경우
    Windows 9x 플랫폼에 대해서는, 표준 INF 파일을 사용해 MDM 스트림 클래스 미니 드라이버가 붙은 하드웨어 디코더를 인스톨 했을 경우만, 리젼 변경 어플리케이션의 DVDRgn.exe 가 인스톨 된다. 다른 소프트웨어 디코더 및 업그레이드 마켓의 경우는, 인스톨 프로그램이 사용하는 INF 파일에 이하의 행을 삽입하는 것에 의해, 대상의 시스템에 DVDRgn.exe 를 추가한다.
    [Version]
Signature=$CHICAGO$
LayoutFile=layout.inf

[DestinationDirs]
DvdRgnCopy=25       ; Windows
DefaultDestDir=25   ; Windows

[DefaultInstall]
CopyFiles=DvdRgnCopy

[DvdRgnCopy]
dvdrgn.exe
  • Windows 2000 의 경우
    Windows 2000 시스템에서는, DVD 리젼 변경 지원을 제공하는 컴퍼넌트는 DLL storprop.dll (%windir%\system32 내)에 있다. 이 DLL 는 디폴트로 인스톨 되고 있어 이것이 유효하게하기 위한 추가 순서는 필요없다.

리젼 변경 지원의 어플리케이션에의 통합

이하의 함수는, 디코더 또는 DVD 어플리케이션으로 리젼 변경 지원을 통합하고 싶은 개발자에게 제공된다.
/////////////////////////////////////////////////////////////////////
// ChangeDVDRegion : DVD 드라이브의 리젼을 변경하는 함수
//
// 파라미터 :
//  In : hWnd - 이 함수를 호출하는 어플리케이션
//             의 윈도우 핸들
//  Out : 없음.
//
// 이하의 값을 돌려준다 :
//     TRUE : 드라이브의 리젼 변경이 성공했을 경우
//     FALSE : 리젼 변경이 실패했을 경우 (아마,
//          유효한 DVD-V 디스크가 있는 드라이브가 발견되지 않기 때문에).
/////////////////////////////////////////////////////////////////////
BOOL ChangeDVDRegion(HWND hWnd)
{
typedef BOOL (APIENTRY *DVDPPLAUNCHER) (HWND hWnd, CHAR DriveLetter);
BOOL   bRegionChanged = FALSE;
TCHAR   szCmdLine[MAX_PATH];

// 우선, 유효한 DVD-V 디스크가 있는 DVD 드라이브는 어떤 것인지를 찾아낸다.

TCHAR     szDVDDrive[4];
if (!  GetDriveLetter (szDVDDrive) )
  {
MessageBox(hWnd,
TEXT("No DVD drive was found with DVD-V disc. ")
TEXT("\nCannot change DVD region of the drive. "),
TEXT("Error"), MB_OK | MB_INFORMATION) ;
return FALSE ;
  }

// 실행중의 OS 를 검출한다. Windows NT 의 경우, storprop.dll 를 사용해,
// Windows 9x 의 경우는 DVDRgn.exe 어플리케이션을 사용해 리젼을 변경한다.

OSVERSIONINFO   ver;
ver.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);
GetVersionEx(&ver);
if (VER_PLATFORM_WIN32_NT  == ver.dwPlatformId)
  {
// Windows NT 플랫폼
HINSTANCE       hInstDLL;
DVDPPLAUNCHER    dvdPPLauncher;
CHAR         szDVDDriveA[4];

#ifdef UNICODE
WideCharToMultiByte(0, 0, szDVDDrive, -1,
szDVDDriveA, sizeof(szDVDDriveA),
NULL, NULL );
#else
strcpy(szDVDDriveA, szDVDDrive);
#endif  // UNICODE

GetSystemDirectory(szCmdLine, MAX_PATH);
lstrcat(szCmdLine, TEXT("\\storprop.dll"));

hInstDLL = LoadLibrary (szCmdLine);
if (hInstDLL)
    {
dvdPPLauncher = (DVDPPLAUNCHER) GetProcAddress(hInstDLL,
"DvdLauncher");
if (dvdPPLauncher)
      {
bRegionChanged = dvdPPLauncher(hWnd, szDVDDriveA[0]);
      }
FreeLibrary(hInstDLL);
    }
}  // Windows NT 플랫폼용의 리젼 변경 코드의 마지막
else   // Windows 9x 플랫폼
  {
// 커멘드 라인 캐릭터 라인용의 \windows\dvdrgn.exe 의 패스를 취득한다
GetWindowsDirectory(szCmdLine, MAX_PATH);
lstrcat(szCmdLine, TEXT("\\DVDRgn.exe "));

// 커멘드 라인 파라미터로서 드라이브 문자만 추가한다
lstrncat(szCmdLine, szDVDDrive, 1);

// DVDRgn.exe 실행의 준비를 한다
STARTUPINFO               StartupInfo;
PROCESS_INFORMATION       ProcessInfo;
StartupInfo.cb            = sizeof(StartupInfo);
StartupInfo.dwFlags       = STARTF_USESHOWWINDOW;
StartupInfo.wShowWindow   = SW_SHOWNORMAL;
StartupInfo.lpReserved    = NULL;
StartupInfo.lpDesktop     = NULL;
StartupInfo.lpTitle       = NULL;
StartupInfo.cbReserved2   = 0;
StartupInfo.lpReserved2   = NULL;
if (CreateProcess(csModuleName, szCmdLine,
NULL, NULL, TRUE,
NORMAL_PRIORITY_CLASS,
NULL, NULL, &StartupInfo, &ProcessInfo) )
    {
// DVDRgn.exe 가 종료될 때까지 기다린다
WaitForSingleObject(ProcessInfo.hProcess, INFINITE);
DWORD dwRet = 1;
BOOL bRet = GetExitCodeProcess(ProcessInfo.hProcess,
&dwRet);
// 유저가 드라이브의 리젼 변경에 성공했을 경우,
// DVDRgn.exe 의 종료 코드는 0.
if (bRet && 0 == dwRet)
      {
bRegionChanged = TRUE;
      }
    }
}  // Windows 9x 플랫폼용의 리젼 변경 코드의 마지막

if (bRegionChanged)   // 리젼의 변경이 성공했을 경우
  {
// 낡은 필터 그래프를 삭제해 새로운 필터 그래프를 생성 하기 위해서,
// IDvdGraphBuilder::RenderDvdVideoVolume()를 사용한다.
  }
else   // DVD 리젼이 없었다
  {
MessageBox(hWnd,
TEXT("DVD drive region could not be changed. ")
TEXT("Error"), MB_OK | MB_INFORMATION) ;
  }
} //함수 ChangeDVDRegion 의 마지막

/////////////////////////////////////////////////////////////////////
// GetDriveLetter : 현재 액티브한 드라이브의 드라이브 문자를
//           취득하는 함수
// 파라미터 :
//  In : pDvdC - DVDNavigator 필터의 IDvdControl
//                인터페이스에의 포인터..
//  Out : pszDrive - 유효한 DVD-V 디스크가 있는 것을 알 수 있던,
//                  최초의 DVD 드라이브.
//
// 이하의 값을 돌려준다 :
//     TRUE : DVD 드라이브가 검출되었을 경우 (유효한 디스크와 함께)
//     FALSE : 유효한 DVD-V 디스크가 있는 DVD 드라이브가 검출되지 않았던 경우.
/////////////////////////////////////////////////////////////////////
BOOL GetDriveLetter(IDvdControl *pDvdC, TCHAR *pszDrive)
{
CHAR   szPathA[MAX_PATH];
TCHAR   szPath[MAX_PATH];
ULONG   ulActualSize;
pszDrive[0] = pszDrive[3] = 0;

// 현재의 루트 디렉토리를 취득한다
if (pDvdC ->GetRoot(szPathA, MAX_PATH, &ulActualSize))
  {
#ifdef UNICODE
MultiByteToWideChar(CP_ACP, 0, szPathA, 0, szPath, MAX_PATH);
#else
lstrcpy(szPath, szPathA);
#endif  // UNICODE
lstrcpyn(pszDrive, szPath, 3);
if (DRIVE_CDROM == GetDriveType(pszDrive)) // DVD 드라이브의 경우
return TRUE;
  }

// 유효한 드라이브 전체를 루프 해, 유효한 DVD-V 디스크가 들어가 있다
// DVD 드라이브는 어떤 것인지를 찾아낸다.

// 유효한 드라이브를 모두 취득한다
DWORD dwLeng = GetLogicalDriveStrings(MAX_PATH, szPath);
TCHAR  *pszTemp = szPath;
// 모든 드라이브를 1 개씩 시험한다
for (DWORD dw = 0; dw < dwLeng; dw += 4)
  {
// 필요한 (. ifo) 파일을 가지는 CD-ROM 드라이브만 조사한다
if (DRIVE_CDROM  == GetDriveType(pszTemp))
      {
TCHAR   szDVDPath1[MAX_PATH]
TCHAR   szDVDPath2[MAX_PATH];
lstrcpyn(szDVDPath1, pszTemp, 4);
lstrcpyn(szDVDPath 2, pszTemp, 4);
lstrcat(szDVDPath1, TEXT("Video_ts\\Video_ts.ifo"));
lstrcat(szDVDPath2, TEXT("Video_ts\\Vts_01_0.ifo"));

//  . ifo 파일이 드라이브상에 있는 경우, 그것은 유효한 DVD-V 디스크를 가지고 있다
if (DoesFileExist(achDVDPath1) && DoesFileExist(achDVDPath2))
        {
lstrcpyn(pszDrive, pszTemp, 3);
return TRUE;   // 유효한 DVD-V 디스크를 가지고 있는 최초의 드라이브를 돌려준다
        }
      }
pszTemp += 4;
  }

return FALSE ;   // DVD 드라이브 (DVD-V 컨텐츠를 포함한다)가 발견되지 않았다.
} //함수 GetDriveLetter 의 마지막

/////////////////////////////////////////////////////////////////////
// DoesFileExist : 특정의 파일명이 기존의 파일일지 어떨지를 확인하는 함수.
//
// 파라미터 :
//  In : pszFile - 존재를 확인하는 파일명의 캐릭터 라인
//  Out : 없음.
//
// 이하의 값을 돌려준다 :
//     TRUE : 지정된 파일이 발견되었을 경우.
//      FALSE : 지정된 파일이 발견되지 않았던 경우.
/////////////////////////////////////////////////////////////////////
BOOL DoesFileExist(LPTSTR pszFile)
{
HANDLE    hFile = NULL ;
// 필요한 파일을 열어 읽을 수 있을지 어떨지 테스트를 시도하는 경우에,
// 에러 메시지 박스가 표시되지 않게 하고 싶다.

UINT uErrorMode = SetErrorMode(SEM_FAILCRITICALERRORS |
SEM_NOOPENFILEERRORBOX);
hFile = CreateFile(pszFile, GENERIC_READ,
FILE_SHARE_READ, NULL,
OPEN_EXISTING, FILE_FLAG_SEQUENTIAL_SCAN,
NULL);
SetErrorMode(uErrorMode);  // 에러 모드를 회복한다.
If (INVALID_HANDLE_VALUE  == hFile)
return FALSE ;

CloseHandle(hFile);
return TRUE;
} //함수 DoesFileExist 의 마지막


DirectShow 튜토리얼

여기에서는, Microsoft® DirectShow® 의 튜토리얼을 나타낸다.

  • 디바이스와 필터의 열거
  • 필터 그래프내의 오브젝트의 열거
  • 필터의 프로퍼티 페이지의 표시
  • 스트림내의 시크
  • 미디어 샘플의 입수
  • AVI 파일의 재압축


디바이스와 필터의 열거

어플리케이션이, 유저의 시스템에 있는 특정의 필터를 찾아내지 않으면 안 되는 것이 있다. 예를 들어, 비디오 캡춰 어플리케이션은, 사용 가능한 캡춰 디바이스의 리스트를 표시할 필요가 있다. Microsoft® DirectShow® 는 컴퍼넌트 베이스의 아키텍쳐를 사용하고 있기 (위해)때문에, 시스템에 어느 필터가 인스톨 되고 있을지가 실행시까지 모르는 것이 있다. 하드웨어 디바이스를 나타내는 필터의 경우는 특히 그렇다. 이하에 나타내는 DirectShow 의 2 개의 컴퍼넌트에 의해, 필터를 찾아내기 쉬워진다.

  • 시스템 디바이스 열거자는, 카테고리 마다 필터를 찾아낸다.
  • 필터 맵퍼는, 어플리케이션이 주는 검색 조건에 응해 필터를 찾아낸다.

여기서 논의하는 열거자는, COM 의 열거 인터페이스로 사용되는 표준형에 따른다. 상세한 것에 대하여는, Microsoft Platform SDK 의 IEnumXXXX 의 주제를 참조할것. 이 주제는, 이하의 섹션으로 구성된다.

  • 시스템 디바이스 열거자의 사용
  • 필터 맵퍼의 사용

시스템 디바이스 열거자의 사용

시스템 디바이스 열거자는, 유저의 시스템에 등록되어 있는 필터를 카테고리 마다 열거하기 위한 통일된 방법을 제공한다. 게다가 같은 필터가 복수의 디바이스를 지원 하고 있는 경우에서도, 각각의 하드웨어 디바이스를 구별할 수 있다. 이것은, Windows Driver Model (WDM) 및 KSProxy 필터를 사용하는 디바이스의 경우에 특히 유용하다. 예를 들어, 유저가 복수의 WDM 비디오 캡춰 디바이스를 가져, 그것들 모든 것이 같은 필터에 의해 지원 되는 일이 있다. 시스템 디바이스 열거자는, 이것들을 다른 디바이스 인터페이스로서 취급한다.

시스템 디바이스 열거자는, 오디오 캡춰나 비디오 압축 등, 특정 카테고리전용의 열거자를 생성 하는 것으로 기능한다. 카테고리 열거자는, 그 카테고리내의 각 디바이스에 대한 일의의 모니카를 돌려준다. 또, 관련이 있는 플러그 앤 플레이 디바이스를 자동적으로 카테고리에 포함한다. 카테고리의 리스트에 대해서는, 「필터 카테고리」를 참조할것.

시스템 디바이스 열거자를 생성 하려면 , 클래스 식별자 (CLSID)에 CLSID_SystemDeviceEnum 를 지정해 CoCreateInstance 를 호출한다. 카테고리 열거자를 입수하려면 , 그 카테고리의 CLSID 를 사용해 ICreateDevEnum::CreateClassEnumerator 를 호출한다. 카테고리 열거자는 IEnumMoniker 인터페이스를 지원 하고 있어, 이 인터페이스를 사용해 각각의 모니카를 열거할 수 있다. 모니카의 IMoniker::BindToObject 을 호출해 디바이스 오브젝트를 생성 및 초기화하는지,IMoniker::BindToStorage 를 호출해 디바이스의 프렌들리명을 취득한다 (예를 들어, 유저 인터페이스의 리스트 박스를 채우기 (위해)때문에). 다음의 그림에 이 처리를 나타낸다.

이하의 예에, 시스템 디바이스 열거자의 인스턴스를 생성해, 그것을 사용해 비디오 압력 디바이스를 열거하는 방법을 나타낸다. 간단하기 때문에, 에러 체크는 가지 않았다.

ICreateDevEnum *pSysDevEnum = NULL;
CoCreateInstance(CLSID_SystemDeviceEnum,
    NULL, CLSCTX_INPROC, IID_ICreateDevEnum,
    (void **) &pSysDevEnum);

IEnumMoniker *pEnumCat = NULL;
pSysDevEnum->CreateClassEnumerator(CLSID_VideoCompressorCategory, &pEnumCat, 0);

IMoniker *pMoniker;
ULONG cFetched;
while(pEnumCat->Next(1, &pMoniker, &cFetched) == S_OK)
{
    IPropertyBag *pPropBag;
    pMoniker->BindToStorage(0, 0, IID_IPropertyBag, (void **) &pPropBag);

    VARIANT varName;
    varName.vt = VT_BSTR;
    pPropBag->Read(L"FriendlyName", &varName, 0);

    // 이 이름을 사용해 무엇인가를 실시한다.

    SysFreeString(varName.bstrVal);
    pPropBag->Release();
    pMoniker->Release();
}
pEnumCat->Release();
pSysDevEnum->Release();

필터 맵퍼의 사용

필터 맵퍼는, 다양한 검색 조건에 근거해 필터를 열거하는 COM 오브젝트이다. 필터 맵퍼는 시스템 디바이스 열거자만큼 효율적은 아니기 때문에, 특정의 카테고리의 필터가 필요한 경우는, 시스템 디바이스 열거자를 사용하는 (분)편이 좋다. 그러나, 특정의 미디어 타입의 편성을 지원 하지만, 뚜렷한 카테고리에는 들어가지 않는 필터를 찾아내는 경우는, 필터 맵퍼를 사용할 필요가 있다. 그 예가, 렌더링 필터나 디코더 필터이다.

필터 맵퍼는,IFilterMapper2 인터페이스를 지원 하고 있다. 필터를 찾으려면 ,IFilterMapper2::EnumMatchingFilters 를 호출한다. 이 메소드는, 검색 조건을 정의하는 파라미터를 몇개인가 받아, 조건에 일치하는 필터의 열거자를 돌려준다. 이 열거자는 IEnumMoniker 를 지원 해, 일치하는 각각의 필터에 일의의 모니카를 준다.

이하의 예에서는, 디지털 비디오 (DV) 입력을 받아, 1 개(살) 이상의 출력 핀을 가지는 임의의 미디어 타입의 필터를 열거하고 있다 (DV 비디오 디코더 필터 가 이 조건에 합치한다).

IFilterMapper2 *pMapper = NULL;
IEnumMoniker *pEnum = NULL;

CoCreateInstance(CLSID_FilterMapper2,
    NULL, CLSCTX_INPROC, IID_IFilterMapper2,
    (void **) &pMapper);

GUID arrayInTypes[2];
arrayInTypes[0] = MEDIATYPE_Video;
arrayInTypes[1] = MEDIASUBTYPE_dvsd;

hr = pMapper->EnumMatchingFilters(
        &pEnum,
        0,                  // 예약이 끝난 상태
        TRUE,               // 완전 일치를 사용?
        MERIT_DO_NOT_USE+1, // 최소의 메리트
        TRUE,               // 1 개(살) 이상의 입력 핀?
        1,                  // 입력의 메이저 타입/서브 타입의 대의 수
        arrayInTypes,       // 입력의 메이저 타입/서브 타입의 대의 배열
        NULL,               // 입력 미디어
        NULL,               // 입력 핀의 카테고리
        FALSE,              // 렌더러가 아니면 안될까?
        TRUE,               // 1 개(살) 이상의 출력 핀?
        0,                  // 출력의 메이저 타입/서브 타입의 대의 수
        NULL,               // 출력의 메이저 타입/서브 타입의 대의 배열
        NULL,               // 출력 미디어
        NULL);              // 출력 핀의 카테고리

// 전의 예의 같게, pEnum 를 사용해 열거한다.

EnumMatchingFilters 메소드에는, 위에의예에 코멘트를 붙인 것처럼 상당한 수의 파라미터가 있다. 이 예로 중요한 것은 이하의 파라미터이다.

  • 최소의 메리트값: 필터는, MERIT_DO_NOT_USE 보다 큰 메리트값을 가지고 있지 않으면 안 된다.
  • 입력 타입: 호출원래는, 메이저 타입과 서브 타입의 대를 포함한 배열을 건네준다. 이러한 대중 1 개(살) 이상을 지원 하는 필터만이 합치한다.
  • 완전 일치: 필터는, 메이저 타입, 서브 타입, 핀 카테고리, 또는 미디어에 NULL 값을 등록할 수 있다. 완전 일치를 지정하지 않으면, NULL 값은 와일드 카드로서 기능해, 임의의 지정값과 일치한다. 완전 일치의 경우, 필터는 조건과 완전하게 일치해야 한다. 그러나, 검색 조건에 NULL 파라미터를 주면(자), 그것은 항상 와일드 카드, 즉 "고려되지 않는 " 값으로서 기능해, 임의의 필터와 일치한다.


필터 그래프내의 오브젝트의 열거

Microsoft® DirectShow® 어플리케이션은, 필터 그래프의 메소드를 호출하는 것만으로 좋기 때문에, 각각의 필터에 대해 고민할 필요는 거의 없다. 그러나 때로는, 그래프내의 특정의 필터나, 필터 위에의 특정의 핀을 찾아내지 않으면 안 되는 것도 있다. 예를 들어, 어플리케이션이 필터의 프로퍼티를 설정하기 위해서, 필터가 공개하는 커스텀 인터페이스를 사용하는 경우이다. 혹은, 특수화 한 필터 그래프를 수작업으로 구축하는 경우는, 필터를 접속하기 위해서 각각의 핀의 메소드를 호출할 필요가 있다. 이런 때를 위해서(때문에), DirectShow 에는, 필터 그래프내의 오브젝트를 열거하기 위한 메소드가 몇개인가 준비되어 있다.

여기서 논의하는 열거자는, COM 의 열거 인터페이스로 사용되는 표준형에 따른다. 상세한 것에 대하여는, Platform SDK 의 IEnumXXXX 의 주제를 참조할것. 유저의 컴퓨터에 등록되고 있으면서 , 아직 필터 그래프에는 들어가 있지 않은 필터의 열거에 대해서는, 「디바이스와 필터의 열거」를 참조할것.

이 주제는, 이하의 섹션으로 구성된다.

  • 필터의 열거
  • 핀의 열거
  • 미디어 타입의 열거

필터의 열거

필터 그래프 매니저가 지원 하는 IFilterGraph::EnumFilters 메소드가, 필터 그래프내의 모든 필터를 열거한다. 이것은,IEnumFilters 인터페이스에의 포인터를 돌려준다. IEnumFilters::Next 메소드는,IBaseFilter 인터페이스 포인터를 취득한다.

이하의 예에 나타내는 함수는, 그래프내의 필터를 열거해, 각 필터의 이름이 붙은 메시지 박스를 표시한다. 이 함수는,IBaseFilter::QueryFilterInfo 메소드를 사용해 필터의 이름을 취득한다. 참조 카운트를 감소 하기 위해서, 인터페이스의 IUnknown::Release 를 호출하는 부분에 주의 해야 한다.

void EnumFilters (IFilterGraph *pGraph)
{
    IEnumFilters *pEnum = NULL;
    IBaseFilter *pFilter;
    ULONG cFetched;

    pGraph->EnumFilters(&pEnum);
    while(pEnum->Next(1, &pFilter, &cFetched) == S_OK)
    {
        FILTER_INFO FilterInfo;
        char szName[256];

        pFilter->QueryFilterInfo(&FilterInfo);
        WideCharToMultiByte(CP_ACP, 0, FilterInfo.achName, -1, szName, 256, 0, 0);
        MessageBox(NULL, szName, "Filter name", MB_OK);

        FilterInfo.pGraph->Release();
        pFilter->Release();
    }
    pEnum->Release();
}

핀의 열거

필터가 지원 하는 IBaseFilter::EnumPins 메소드가, 필터로 사용할 수 있는 핀을 열거한다. 이것은,IEnumPins 인터페이스에의 포인터를 돌려준다. IEnumPins::Next 메소드는,IPin 인터페이스 포인터를 취득한다.

이하의 예에 나타내는 함수는, 주어진 필터상에서 주어진 방향 (입력 또는 출력)의 핀을 찾아낸다. 이 함수는,PIN_DIRECTION 의 열거를 사용해 핀의 방향을 지정해,IPin::QueryDirection 메소드를 사용해 열거된 각 핀의 방향을 찾아낸다. 이 함수는, 일치하는 핀을 찾아내면(자), 미처리의 참조 카운트를 가지는 IPin 인터페이스 포인터를 돌려준다. 인터페이스의 해방은, 호출원이 실시하지 않으면 안 된다.

IPin *GetPin(IBaseFilter *pFilter, PIN_DIRECTION PinDir)
{
    BOOL       bFound = FALSE;
    IEnumPins  *pEnum;
    IPin       *pPin;

    pFilter->EnumPins(&pEnum);
    while(pEnum->Next(1, &pPin, 0) == S_OK)
    {
        PIN_DIRECTION PinDirThis;
        pPin->QueryDirection(&PinDirThis);
        if (bFound = (PinDir == PinDirThis))
            break;
        pPin->Release();
    }
    pEnum->Release();
    return (bFound ?  pPin : 0);
}

미디어 타입의 열거

핀이 지원 하는 IPin::EnumMediaTypes 메소드가, 핀의 우선되는 미디어 타입을 열거한다. 이것은,IEnumMediaTypes 인터페이스에의 포인터를 돌려준다. IEnumMediaTypes::Next 메소드는, 미디어 타입을 기술하는 AM_MEDIA_TYPE 구조체에의 포인터를 취득한다.

미디어 타입 열거 자식이 있는 것은, 주로 필터 그래프가 인텔리전트 접속을 실시하기 쉽게하기 위해(때문에)여, 어플리케이션으로 이것을 사용하는 것은 우선 없다. 핀은, 우선되는 미디어 타입을 돌려준다고는 할 수 없지 않고, 돌려주어지는 미디어 타입은 필터의 접속 상태에 따라서 다르다. 예를 들어, 필터의 출력 핀은, 필터의 입력 핀에 어느 미디어 타입이 설정되어 있을까에 따라서 다른 미디어 타입 세트를 돌려준다.


스트림내의 시크

여기에서는, 어플리케이션이 미디어 스트림내의 복수의 위치를 시크 하는 방법에 대해 설명한다. 다음의 주제가 포함된다.

  • 개요
  • 시크 기능
  • 타임 포맷
  • 스트림 위치의 설정과 취득
  • 재생 레이트의 설정
  • 사례 연구법:시크 바의 이행

개요

Microsoft® DirectShow® 는,IMediaSeeking 인터페이스에 의한 시크를 지원 하고 있다. 이 인터페이스를 공개하는 것은 필터 그래프 매니저이지만, 시크 기능을 이행 하는 것은 항상 필터이다.

어플리케이션은 필터 그래프 매니저에 IMediaSeeking 를 문의해 이것을 사용해 시크 커멘드를 발행한다. 필터 그래프 매니저도 IMediaSeeking 인터페이스를 사용해, 그 시크 커멘드를 그래프내의 모든 렌더링 필터에 배포한다. 각 렌더러는, 이러한 커멘드를 실행할 수 있는 필터에 도달할 때까지, 업 스트림 필터의 출력 핀을 개입시켜 커멘드를 업 스트림에 전송 한다. 보통AVI Splitter 등의 소스 필터 또는 퍼서 필터가, 시크 조작을 실행한다.

필터가 시크 조작을 실행 하면, 보류중의 데이터는 모두 플래시 된다. 다운 스트림 필터에서도 데이터가 플래시 된다. 상세한 것에 대하여는, 「필터 개발자가 사용하는 데이터 플로우」를 참조할것. 결과적으로 그래프로부터 기존의 데이터가 플래시 되기 (위해)때문에, 시크 커멘드의 지연 시간이 최소화되게 된다. 다음의 그림은, 처리의 순서를 구체적으로 가리킨다.

퍼서 필터에 복수의 출력 핀이 있는 경우는 보통, 그 중의 1 개가 시크 커멘드를 받도록(듯이) 지정되고 있다. 그 외의 핀이 시크 커멘드를 받아도, 거부하는지 무시한다. 이와 같이, 퍼서는 그 스트림의 모든 것이 동기화하는 상태를 유지한다.

시크 기능

데이터에 따라서는 시크 할 수 없는 것이 있다. 예를 들어, 카메라로부터의 라이브 스트림을 시크 할 수 없다. 스트림이 시크 가능한 경우, 지원 되는 시크의 종류는 다양하다. 시크에는 다음의 종류가 있다.

  • 스트림내의 임의의 위치를 시크 한다.
  • 스트림의 시간폭을 취득한다.
  • 스트림내의 현재 위치를 취득한다.
  • 역방향으로 재생한다.

IMediaSeeking 인터페이스는, 대응 가능한 시크 기능을 나타내는 AM_SEEKING_SEEKING_CAPABILITIES 플래그를 정의한다. 스트림의 기능을 취득하려면 ,IMediaSeeking::GetCapabilities 메소드를 호출한다. 이 메소드에 의해, 비트 단위의 플래그의 편성이 돌려주어진다. 어플리케이션은 & (비트 단위의 AND) 연산자를 사용해, 플래그를 검사할 수 있다. 예를 들어, 다음의 코드는 그래프가 임의의 위치를 시크 할 수 있을지 어떨지를 체크한다.

DWORD dwCap = 0;
HRESULT hr = pSeek->GetCapabilities(&dwCap);
if (AM_SEEKING_CanSeekAbsolute & dwCap)
{
// 그래프는 절대 위치를 시크 할 수 있다.
}

이 밖에,IMediaSeeking::CheckCapabilities 메소드를 사용해, 시크 기능의 서브 세트를 검사할 수 있다. 어플리케이션은, 다음과 같이 플래그의 편성을 비트 단위로 해석한다.

// 체크하는 기능의 플래그를 설정한다.
DWORD dwCaps = AM_SEEKING_CanSeekAbsolute |
AM_SEEKING_CanSeekForwards |
AM_SEEKING_CanSeekBackwards;

HRESULT hr = pMediaSeeking->CheckCapabilities(&dwCaps);

지정한 기능이 지원 되는 경우, 반환값은 S_OK 이다. 지정한 기능이 전혀 지원 되지 않는 경우, 에러 코드가 돌려주어진다. 지정한 기능의 일부가 지원 되는 경우, 반환값은 S_FALSE 이다. 메소드가 돌아온 시점에서, 입력 파라미터에는, 최초로 건네받은 세트는 아니고, 지원 되는 기능의 비트 단위의 편성이 저장 되고 있다. 이 결과는 다음과 같이 검사할 수 있다.

if (hr == S_FALSE) // 요구된 기능의 일부가 지원 되지 않는다.
{
if (dwCaps & AM_SEEKING_CanSeekAbsolute)
// 이 기능이 지원 된다.
        ...
}

타임 포맷

IMediaSeeking 인터페이스는, 미디어 타임 (100 나노초단위), 비디오 프레임, 및 스트림내의 바이트 오프셋(offset) 등, 복수의 타임 포맷을 지원 하고 있다. 각 타임 포맷은, 글로벌 일의 식별자 (GUID)로 정의된다. DirectShow 로 정의되는 타임 포맷의 일람에 대해서는, 「타임 포맷 GUID 」를 참조할것. 써드파티도 커스텀 타임 포맷의 GUID 를 정의할 수 있다.

필터 그래프 매니저의 기정값은 미디어 타임이다. 다른 타임 포맷을 사용하려면 ,IMediaSeeking::SetTimeFormat 메소드를 호출한다. 이 메소드가 정상 종료 하면, 그 후의 모든 시크 커멘드는 새롭게 설정된 포맷을 사용한다. 미디어 스트림이 지정의 타임 포맷을 지원 할지 어떨지를 판단하려면 ,IMediaSeeking::IsFormatSupported 메소드를 호출한다. 다음의 코드는, 타임 포맷을 프레임 단위로 설정해, 그 결과를 다음에 사용하기 위해서 불리언 값의 플래그에 저장 하는 예이다.

hr = pSeek->SetTimeFormat(&TIME_FORMAT_FRAME);
BOOL bTimeInFrames = SUCCEEDED(hr);

스트림 위치의 설정과 취득

필터 그래프가 보관 유지하는 위치값은, 현재 위치와 정지 위치의 2 개이다.

  • 실행중의 그래프에서는, 현재 위치는 렌더링중의 데이터를 반영한다. 정지 또는 포즈 한 그래프에서는, 다음의 실행 커멘드로 스트리밍이 시작 하는 위치를 나타낸다.
  • 정지 위치는 스트림이 종료하는 위치이다. 그래프가 정지 위치에 도달 하면, 그 이후는 데이터가 스트림 되지 않고, 필터 그래프 매니저는 EC_COMPLETE 이벤트를 투입한다(다만, 그래프는 자동적으로는 정지상태태에 바뀌지 않는다. 상세한 것에 대하여는, 「이벤트에의 응답」을 참조할것).

현재 위치를 취득하려면 ,IMediaSeeking::GetCurrentPosition 메소드를 호출한다. 정지 위치를 취득하려면 ,IMediaSeeking::GetStopPosition 메소드를 호출한다. 반환값은, 현재의 타임 포맷의 단위를 사용한다 (전의 「타임 포맷」을 참조할것). 반환값은 항상 원의 미디어 소스에 대한 상대값이다.

새로운 위치를 시크 한다, 또는 새로운 정지 위치를 설정하려면 ,IMediaSeeking::SetPositions 메소드를 호출한다. 다음의 코드는 그 예이다.

#define ONE_SECOND 10000000
REFERENCE_TIME rtNow = 2 * ONE_SECOND, rtStop = 5 * ONE_SECOND;

hr = pSeek->SetPositions(
&rtNow,  AM_SEEKING_AbsolutePositioning,
&rtStop, AM_SEEKING_AbsolutePositioning
    );

이 예에서는, 현재의 타임 포맷이 미디어 타임인 것을 전제로 하고 있다. 이것은 100 나노초단위이다. 1 초는 10,000,000 단위가 된다. 편의상, 예에서는 이 값을 ONE_SECOND 로서 정의하고 있다.

주 DirectShow base class를 사용하고 있는 경우, 같은 값을 가지는 정수 UNITS 가 정의되고 있다. 상세한 것에 대하여는, 「base class」를 참조할것.

rtNow 파라미터는 새로운 위치를 지정한다. 2 번째의 파라미터는,rtNow 의 해석 방법을 정의하는 플래그이다. 이 예의 플래그는,rtNow 가 소스내의 절대 위치로서 정의되는 것을 나타내고 있다. 호출이 돌아오면(자), 필터 그래프는, 스트림의 시작으로부터 2 초의 위치에 시크 한다. rtStop 파라미터는 종료 타임을 지정한다. 마지막 파라미터는, 종료 타임도 절대 위치인 것을 나타내는 플래그이다.

전의 위치값으로부터의 상대 위치를 지정하려면 , AM_SEEKING_RelativePositioning 플래그를 사용한다. 위치값의 어느쪽이든 1 개(살)을 변경하지 않는 채 남기려면 , AM_SEEKING_NoPositioning 플래그를 사용한다. 그 경우, 대응하는 시간 파라미터는 NULL 이라도 좋다. 다음의 예에서는, 정지 위치를 변경하지 않고 , 10 초처까지 시크 한다.

REFERENCE_TIME rtNow = 10 * ONE_SECOND;
hr = pSeek->SetPositions(
&rtNow, AM_SEEKING_RelativePositioning,
NULL, AM_SEEKING_NoPositioning
    );

필터 그래프를 정지 하면, 비디오 렌더러는 시크 조작 후에 이미지를 갱신하지 않는다. 유저에게 있어서는, 시크가 발생하지 않았는지와 같이 보인다. 이미지를 갱신하려면 , 시크 조작 후에 그래프를 포즈 한다. 그래프를 포즈 하는 것으로, 비디오 렌더러에 새로운 비디오 프레임이 삽입된다. IMediaControl::StopWhenReady 메소드를 사용하면(자), 그래프는 포즈 하고 나서 정지상태태에 돌아온다.

재생 레이트의 설정

재생 레이트를 변경하려면 ,IMediaSeeking::SetRate 메소드를 호출한다. 새로운 레이트를 원의 레이트의 비로서 지정한다. 예를 들어, 보통 속도의 2 배로 재생하려면 , 다음과 같이 한다.

pSeek->SetRate(2.0)

레이트는 0 보다 크지 않으면 안 된다. 레이트가 1 보다 커지면(자), 보통보다 고속으로 된다. 레이트가 0 으로 1 의 사이이면, 보통보다 저속이 된다.

재생 레이트에 관계없이, 현재 위치와 정지 위치는 항상 오리지날 소스로부터의 상대로 나타내진다. 예를 들어, 원시 파일이 20 초 (보통의 재생 레이트로)인 경우, 현재 위치를 10 초로 설정해 파일의 중앙에 시크 한다. 정지 위치가 20 초 (파일의 최후)로, 재생 레이트가 2.0 인 경우, 파일은 실시간의 5 초에 재생이 종료한다. 즉, 원시 파일의 나머지 10 초간은 보통의 2 배의 속도로 재생된다.

사례 연구법:시크 바의 이행

여기에서는, 미디어 플레이어 어플리케이션에 시크 바를 이행 하는 방법을 설명한다. 시크 바는 트럭 바 컨트롤로서 이행 된다.

어플리케이션의 기동시에, 트럭 바를 초기화한다.

HWND hTrack = GetDlgItem(hwnd, IDC_SLIDER1);
EnableWindow(hTrack, FALSE);
SendMessage(hTrack, TBM_SETRANGE, TRUE, MAKELONG(0, 100));

트럭 바는, 유저가 미디어 파일을 열 때까지 무효이다. 트럭 바의 범위는 0 에서 100 이 된다. 어플리케이션은 미디어 타임을 파일 시간폭의 퍼센티지로 변환한다. 예를 들어, 트럭 바의 위치 "50" 는 항상 파일의 중앙에 상당한다(이 밖에, 트럭 바의 최대 범위를 파일의 시간폭으로 설정하는 방법도 있다. 다만, 미디어 타임은 64 비트의 정수인데 대해, 트럭 바의 범위는 32 비트에 제한되고 있다).

유저가 파일을 열면(자), 어플리케이션은 파일 재생 그래프를 구축한다. 어플리케이션은, 필터 그래프 매니저에 대해서 IMediaSeeking 인터페이스를 문의한다 (여기에는 나타나지 않는다). 다음에, 어플리케이션은, 그래프가 시크 가능한가 어떤가 및 파일 시간폭을 취득 가능한가 어떤가를 체크한다. 그래프가 이것들 양쪽 모두의 기능을 지원 하는 경우, 어플리케이션은 파일 시간폭을 취득해, 트럭 바를 유효하게 한다.

REFERENCE_TIME g_rtTotalTime;
DWORD caps = AM_SEEKING_CanSeekAbsolute | AM_SEEKING_CanGetDuration;

if (pSeek && S_OK == pSeek->CheckCapabilities(&caps))
{
pSeek->GetDuration(&g_rtTotalTime);
EnableWindow(hTrack, TRUE);
}

유저가 "재생 " 커멘드를 발행 하면, 어플리케이션은 그래프를 실행한다. 또, 트럭 바의 위치를 정기적으로 갱신하는 바다거북 겨이삭띠도 시작 된다. 각 바다거북 겨이삭띠가 액티브하게 되면(자), 타이머 콜백이 현재의 재생 위치를 취득해, 거기에 응해 트럭 바를 설정한다.

#define TICKLEN 100   // 틱의 길이 (트럭 바의 갱신 간격)
MMRESULT wTimerID;

void CALLBACK MediaTimer(UINT wTimerID, UINT msg,
DWORD dwUser, DWORD dw1, DWORD dw2)
{
REFERENCE_TIME rtNow;
pSeek->GetCurrentPosition(&rtNow);
long sliderTick = (long)((rtNow * 100) / g_rtTotalTime);
SendMessage( hScroll, TBM_SETPOS, TRUE, sliderTick );
}

void OnUserPlay()
{
pGraph->Run();
if(wTimerID)        // 바다거북 겨이삭띠는 보류중인가?
    {
timeKillEvent(wTimerID);  // 타이머를 캔슬한다.
wTimerID = 0;
    }
wTimerID = timeSetEvent(TICKLEN, 50, MediaTimer, NULL, TIME_PERIODIC);
}

유저가 그래프를 정지 또는 포즈 하면, 어플리케이션은 바다거북 겨이삭띠를 캔슬한다.

유저가 트럭 바 컨트롤을 드러그 또는 클릭 하면, 어플리케이션은 WM_HSCROLL 이벤트를 받는다. wParam 파라미터의 하위 워드는, 트럭 바 통지 메세지이다. 관계하는 메세지는, 트럭 바 액션의 종료시에 송신되는 TB_ENDTRACK, 및 유저가 트럭 바를 드러그중에 계속적으로 송신되는 TB_THUMBTRACK 이다.

다음의 함수는, 이것들 양쪽 모두의 메세지를 처리한다.

void HandleTrackbar(HWND hTrackbar, short int userReq)
{
// 파일이 시크 가능하지 않은 경우, 트럭 바는 무효가 된다.
// 이 때문에, 시크는 여기에서는 유효하다.

static OAFilterState state;
static BOOL bStartOfScroll = TRUE;

if (userReq == TB_ENDTRACK || userReq == TB_THUMBTRACK)
    {
DWORD Position  = SendMessage(hTrackbar, TBM_GETPOS, 0, 0);

// 스크롤 조작이 시작 하면 포즈 한다.
if (bStartOfScroll)
        {
pControl->GetState(10, &state);
bStartOfScroll = FALSE;
pControl->Pause();
        }

// 위치를 계속적으로 갱신한다.
REFERENCE_TIME newTime = (g_rtTotalTime * Position) / 100;
pSeek->SetPositions(&newTime, AM_SEEKING_AbsolutePositioning,
NULL, AM_SEEKING_NoPositioning);

// 최후로 상태를 복원한다.
if (userReq == TB_ENDTRACK)
        {
if (state == State_Stopped)
pControl->Stop();
else if (state == State_Running)
pControl->Run();
bStartOfScroll = TRUE;
        }
    }
}

유저가 트럭 바를 드러그 하는데 맞추어 시크를 매끄럽게 실시하기 위해서(때문에), 유저가 트럭 바를 떼어 놓을 때까지, 어플리케이션은 그래프를 포즈 하고 있다. 그래프가 실행중에서 만났을 경우, 포즈 모드에서는, 유저가 컨트롤을 드러그 하고 있는 한중간에, 그래프의 재생을 계속할 수 없게 된다. 그래프가 정지하고 있었을 경우, 포즈 모드에서도 비디오 윈도우가 확실히 갱신된다. TB_ENDTRACK 메세지를 받아들이면(자), 함수는 그래프를 당초의 상태에 복원한다.


필터의 프로퍼티 페이지의 표시

프로퍼티 페이지는, 유저가 설정 가능한 프로퍼티를 지원하기 위한 1 개의 방법이다. 여기에서는, 어플리케이션으로 필터의 프로퍼티 페이지를 표시하는 방법을 해설해, 콘솔 프로그램의 샘플을 나타낸다. 이 샘플 어플리케이션은, 파일 재생 그래프를 구축해, 그래프내의 필터가 정의한 프로퍼티 페이지를 표시하고 나서, 파일을 재생한다.

이하의 항으로 구성된다.

  • 프로퍼티 페이지의 표시법
  • 샘플 코드

프로퍼티 페이지의 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.

프로퍼티 페이지의 표시법

프로퍼티 페이지를 가지는 필터는,ISpecifyPropertyPages 인터페이스를 공개한다. 필터가 프로퍼티 페이지를 정의하고 있을지 어떨지를 판단하려면 ,QueryInterface 를 사용해 필터에 이 인터페이스를 조회해, SUCCEEDED 매크로를 사용해 반환값을 검사한다. 이하의 예에 처리의 개요를 나타낸다.

IBaseFilter *pFilter;
// 필터의 IBaseFilter 인터페이스를 취득한다 (표시되지 않는다).

ISpecifyPropertyPages *pSpecify;
HRESULT hr = pFilter->QueryInterface(IID_ISpecifyPropertyPages, (void **) &pSpecify);
if (SUCCEEDED(hr)) {
    // 페이지를 표시한다.
}

필터의 인스턴스를 (CoCreateInstance 를 호출해) 직접 생성했을 경우는, 필터에의 포인터를 이미 가지고 있다. 그렇지 않은 경우는, 이하의 몇개의 조작을 실시한다.

  • IFilterGraph::EnumFilters 메소드를 사용해, 그래프내의 필터를 열거한다. 이하에 나타내는 샘플 코드에서는, 이 방법을 이용하고 있다. 필터의 열거의 상세한 것에 대하여는, 「필터 그래프내의 오브젝트의 열거」를 참조할것.
  • 필터 그래프의 IFilterGraph::FindFilterByName 메소드를 호출한다.

ISpecifyPropertyPages 인터페이스 포인터를 얻을 수 있으면,ISpecifyPropertyPages::GetPages 메소드를 호출해 필터의 프로퍼티 페이지를 꺼낼 수가 있다. 이 메소드는, 글로벌 일의 식별자 (GUID)의 카운트 배열에 각 프로퍼티 페이지의 클래스 식별자 (CLSID)를 기입한다. 카운트 배열은 CAUUID 구조체로 정의된다. 이 구조체는 할당하지 않으면 안 되지만, 초기화할 필요는 없다. 배열 자체는 이 메소드에 의해 할당할 수 있어 CAUUID 구조체의 pElems 멤버에 저장 된다.

CAUUID caGUID;
pSpecify->GetPages(&caGUID);
pSpecify->Release();

이하의 코드에 나타내도록(듯이),OleCreatePropertyFrame 함수에 의해, 모덜 다이알로그 박스에 프로퍼티 페이지를 간단하게 표시하는 수단이 제공된다.

OleCreatePropertyFrame(
    NULL,                   // 부모 윈도우
    0,                      // x (예약이 끝난 상태)
    0,                      // y (예약이 끝난 상태)
    FilterInfo.achName,     // 다이알로그 박스의 캡션
    1,                      // 필터의 수
    (IUnknown **) &pFilter,  // 필터에의 포인터
    caGUID.cElems,          // 프로퍼티 페이지의 수
    caGUID.pElems,          // 프로퍼티 페이지의 CLSID 에의 포인터
    0,                      // 로케일 식별자
    0,                      // 예약이 끝난 상태
    NULL                    // 예약이 끝난 상태
);

샘플 코드에서는, 다이알로그 박스의 캡션에 필터의 이름을 사용하고 있다. 이름은, 필터의 IBaseFilter::QueryFilterInfo 메소드를 호출해 취득한다. 상세한 것에 대하여는, 이하의 샘플 코드를 참조할것. 처리가 끝나면(자), 반드시 CoTaskMemFree 함수를 호출해 GUID 배열을 해방한다.

CoTaskMemFree(caGUID.pElems);

샘플 코드

이하의 샘플 코드는, 콘솔 프로그램이다. 이것은, 커멘드 라인 인수로서 파일명을 받아, 파일을 재생하는 그래프를 구축해, 그래프내의 필터가 정의하는 프로퍼티 페이지를 표시해, 파일을 재생한다.

#include <dshow.h>
#include <stdio.h>

int main(int argc, char *argv[])
{
    HRESULT  hr;
    WCHAR    wPath[MAX_PATH];
    IGraphBuilder *pGraph = NULL;

    if (argc < 2) {
        printf("Usage: %s movie.ext\n", argv[0]);
        exit(0);
    }
    CoInitialize(NULL);
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC_SERVER,
                        IID_IGraphBuilder, (LPVOID *) &pGraph);

    // 파일명을 와이드 캐릭터 라인으로 변환한다.
    MultiByteToWideChar(CP_ACP, 0, argv[1], -1, wPath, MAX_PATH);
    hr = pGraph->RenderFile(wPath, NULL);
    if (FAILED(hr)) {
        printf("Error: Could not open file named %s. \n", argv[1]);
        pGraph->Release();
        CoUninitialize();
        exit(1);
    }

    // 필터를 열거해, 그러한 프로퍼티 페이지를 표시한다.
    IEnumFilters *pEnum;
    IBaseFilter *pFilter = NULL;

    pGraph->EnumFilters(&pEnum);
    while(pEnum->Next(1, &pFilter, NULL) == S_OK)
    {
        ISpecifyPropertyPages *pSpecify;
        hr = pFilter->QueryInterface(IID_ISpecifyPropertyPages, (void **) &pSpecify);
        if (SUCCEEDED(hr)) {
            FILTER_INFO FilterInfo;
            pFilter->QueryFilterInfo(&FilterInfo);

            CAUUID caGUID;
            pSpecify->GetPages(&caGUID);
            pSpecify->Release();

            OleCreatePropertyFrame(
                NULL,                   // 부모 윈도우
                0,                      // x (예약이 끝난 상태)
                0,                      // y (예약이 끝난 상태)
                FilterInfo.achName,     // 다이알로그 박스의 캡션
                1,                      // 필터의 수
                (IUnknown **) &pFilter,  // 필터에의 포인터
                caGUID.cElems,          // 프로퍼티 페이지의 수
                caGUID.pElems,          // 프로퍼티 페이지 CLSID 에의 포인터
                0,                      // 로케일 식별자
                0,                      // 예약이 끝난 상태
                NULL                    // 예약이 끝난 상태
            );
            CoTaskMemFree(caGUID.pElems);
            FilterInfo.pGraph->Release();
        }
        pFilter->Release();
    }
    pEnum->Release();

// 그래프를 실행한다.
    IMediaControl *pMediaControl = NULL;
    pGraph->QueryInterface(IID_IMediaControl, (void **) &pMediaControl);
    pMediaControl->Run();
    MessageBox(NULL, "Click to end playback. ", "DirectShow", MB_OK);

    pMediaControl->Release();
    pGraph->Release();
    CoUninitialize();
    return 0;
}


미디어 샘플의 획득

이 주제에서는,샘플 grabber 필터를 사용해 미디어 샘플을 꺼내는 방법을 해설한다.

Microsoft® DirectShow® 아크테크체에서는, 어플리케이션이 미디어 데이터를 직접 조작할 것은 없다. 미디어 데이터의 변경이 필요한 경우는, 그 때문의 변환 필터 또는 Microsoft® DirectX® Media Object (DMO)를 쓸 필요가 있다. 한편, 비디오 파일로부터 프레임을 표시하는 등, 미디어 데이터를 변경하지 않고 사용할 필요가 있는 경우는, 샘플 grabber 필터를 사용할 수 있다.

이 주제는, 이하의 섹션으로 구성된다.

  • 필터 그래프에의 샘플 grabber의 추가
  • 버퍼와 one-shot 모드
  • 콜백 메소드의 사용

필터 그래프에의 샘플 grabber의 추가

샘플 grabber는,ISampleGrabber 인터페이스를 지원 하는 변환 필터이다. 이 필터는, 모든 샘플을 변경하지 않고 다운 스트림에 보내므로, 데이터 스트림을 변경하지 않아도 필터 그래프에 삽입할 수 있다. 샘플 grabber를 사용 하면, 샘플이 필터를 통과할 경우에 샘플을 획득할 수 있다.

디폴트에서는, 샘플 grabber에는 우선되는 미디어 타입은 없다. 샘플 grabber를 필터 그래프에 삽입하기 전에,ISampleGrabber::SetMediaType 메소드를 호출해 입력 핀의 미디어 타입을 설정한다. 미디어 타입을 설정하는 것으로, 필터 그래프 매니저가 그래프내의 올바른 위치에 샘플 grabber를 삽입하는 것이 보증된다.

SetMediaType 메소드는, 미디어 타입을 기술하는 AM_MEDIA_TYPE 구조체에의 포인터를 받는다. 상황에 따라, 서브 타입 또는 포맷 타입을 GUID_NULL 로 설정할 수 있다. GUID_NULL 는,"미설정" 을 나타낸다. 다음의 예에서는, 샘플 grabber를 필터 그래프에 추가해, 미디어 타입에 24 비트비압축 RGB 비디오를 설정해 있다.

#include <dshow.h>
#include <qedit.h>

IBaseFilter     *pF = NULL;
ISampleGrabber  *pGrab = NULL;  // 이것들은 다음에 반드시 해방하는 것.
AM_MEDIA_TYPE   mt;

CoCreateInstance(CLSID_SampleGrabber, NULL, CLSCTX_INPROC_SERVER,
                    IID_IBaseFilter, (LPVOID *) &pF);
pF->QueryInterface(IID_ISampleGrabber, (void **) &pGrab);

pGraph->AddFilter(pF, L"Grabber");

ZeroMemory(&mt, sizeof(AM_MEDIA_TYPE));
mt.majortype = MEDIATYPE_Video;
mt.subtype = MEDIASUBTYPE_RGB24;
mt.formattype = FORMAT_VideoInfo;
hr = pGrab->SetMediaType(&mt);

이것으로, 그래프의 나머지의 부분을 구축해, 샘플 grabber 필터를 접속할 수 있다. 그 때문에(위해)는, 다양한 방법이 있지만, 그 예를 다음에 나타낸다.

  • IGraphBuilder::RenderFile 를 호출한다. 필터 그래프 매니저는, 이 미디어 타입에 따라, 샘플 grabber를 접속한다.
  • 한 번에 1 개(살)씩 필터를 추가해,IGraphBuilder::Connect 메소드를 사용해 접속한다.
  • ICaptureGraphBuilder2 인터페이스를 사용한다.

예를 들어, 다음의 코드에서는, Example.avi 파일의 재생 그래프가 구축된다.

pGraph->RenderFile(L"C:\\Example.avi", NULL);

샘플 grabber의 미디어 타입은 비압축 비디오로 설정되어 있으므로, 필터 그래프 매니저는, 비압축 비디오 샘플을 받는 장소인, 비데오데콘프렛사와 비디오 렌더러의 사이에 필터를 배치한다.

렌더링 하지 않고 샘플을 획득하고 싶은 경우는, 샘플 grabber의 출력 핀을 Null 렌더링 필터에 접속한다. 이 필터는, 받은 샘플을 파기한다.

버퍼와 one-shot 모드

샘플 grabber는, 내부 버퍼에 받는 샘플을 카피할 수 있다. 버퍼링을 유효하게 하려면 , 값 TRUE 를 지정해 ISampleGrabber::SetBufferSamples 메소드를 호출한다. 샘플의 카피를 취득하려면 ,ISampleGrabber::GetCurrentBuffer 메소드를 호출한다.

각 샘플은, 버퍼에 있기 이전의 샘플에 오버라이드(override) 된다. 스트림의 특정의 포인트로부터 샘플을 획득하려면 , 샘플 grabber를 "one-shot" 모드로 전환한다. one-shot 모드에서는, 샘플 grabber는 1 개의 샘플을 받자마자 그래프를 정지한다. one-shot 모드를 유효하게 하려면 , 값 TRUE 를 지정해 ISampleGrabber::SetOneShot 메소드를 호출한다.

목적의 시간에 시크 해, 그래프를 실행해, 그래프가 정지하는 것을 기다린다. 다음의 코드는, 그방법을 나타내고 있다.

// 이러한 인터페이스 (나타나지 않는다)에 대해 필터 그래프 매니저에 문의한다.
IMediaControl   *pMediaControl = NULL;
IMediaSeeking   *pSeek = NULL;
IMediaEvent     *pEvent = NULL;

// one-shot 모드를 설정한다.
pGrab->SetBufferSamples(TRUE);
pGrab->SetOneShot(TRUE);

// 3 초 시크 한다.
REFERENCE_TIME rtStart = 3 * 10000000;
REFERENCE_TIME rtStop = rtStart;

hr = pSeek->SetPositions(&rtStart, AM_SEEKING_AbsolutePositioning,
                         &rtStop, AM_SEEKING_AbsolutePositioning);

// 그래프를 실행해, 종료를 기다린다.
long evCode;
hr = pMediaControl->Run();
hr = pEvent->WaitForCompletion(INFINITE, &evCode);

다음에,WaitForCompletion 메소드가 돌아가, 샘플 grabber의 버퍼에 비디오 프레임의 카피가 저장 된다. 버퍼에는, 샘플의 미디어 데이터의 부분만큼이 포함되어 포맷 헤더는 포함되지 않았다. 포맷 헤더를 획득하려면 ,ISampleGrabber::GetConnectedMediaType 를 호출한다. 이 메소드는,AM_MEDIA_TYPE 구조체를 돌려준다. 이 구조체의 pbFormat 멤버가, 포맷 헤더를 가리키고 있다. 사용후는, 반드시 버퍼 메모리를 해방하는 것.

예로서 다음의 코드는 포맷 헤더와 샘플 버퍼를 사용해, 비디오 스트림으로부터 디바이스에 의존하지 않는 비트 맵 (DIB)을 생성 한다.

AM_MEDIA_TYPE MediaType;
pGrab->GetConnectedMediaType(&MediaType);

// 비디오 헤더에의 포인터를 획득한다.
VIDEOINFOHEADER *pVideoHeader = (VIDEOINFOHEADER*) MediaType.pbFormat;

// 비디오 헤더에는, 비트 맵 정보가 포함된다.
// 비트 맵 정보를 BITMAPINFO 구조체에 카피한다.
BITMAPINFO BitmapInfo;
ZeroMemory(&BitmapInfo, sizeof(BitmapInfo));
CopyMemory(&BitmapInfo.bmiHeader, &(pVideoHeader->bmiHeader), sizeof(BITMAPINFOHEADER));

// 비트 맵 헤더로부터 DIB 를 생성 해, 버퍼에의 포인터를 획득한다.
void *buffer = NULL;
HBITMAP hBitmap =
    CreateDIBSection(0, &BitmapInfo, DIB_RGB_COLORS, &buffer, NULL, 0);

// 이미지를 버퍼에 카피한다.
hr = pGrab->GetCurrentBuffer(NULL, (long *) buffer);

어플리케이션은,BitBlt 를 호출해 이미지를 표시할 수 있다. 상세한 것에 대하여는, Platform SDK 를 참조할것. 이 예에서는 비디오 스트림을 상정하고 있지만, 샘플 grabber는 오디오 샘플이나 다른 미디어 샘플을 취득할 수 있다. 이미지를 소총탄 하려면 , 다음과 같은 코드를 사용한다.

long Width = pVideoHeader->bmiHeader.biWidth;
long Height = pVideoHeader->bmiHeader.biHeight;

HDC hdcDest = GetDC(hwnd);
HDC hdcSrc = CreateCompatibleDC(NULL);
SelectObject(hdcSrc, hBitmap);
BitBlt(hdcDest, 0, 0, Width, Height, hdcSrc, 0, 0, SRCCOPY);

콜백 메소드의 사용

샘플 grabber는, one-shot 모드에서의 조작 대신에, 받는 샘플 마다 콜백 메소드를 호출할 수가 있다. 어플리케이션은 ISampleGrabberCB 인터페이스를 이행 해야 한다. 이 인터페이스에는, 다음의 메소드가 포함된다.

  • SampleCB : 샘플의 IMediaSample 인터페이스에의 포인터를 받는다.
  • BufferCB : 미디어 데이터가 포함된 버퍼를 받는다.

보통은, 이러한 메소드중 1 개(살)만을 이행 한다. 콜백을 설정하려면 ,ISampleGrabber::SetCallback 메소드를 호출한다. 이 메소드는, 사용하는 콜백 메소드를 지정하는 인덱스값을 취한다. BufferCB 메소드를 지정하는 경우는, 전에 설명한 것처럼,ISampleGrabber::SetBufferSamples 도 호출해 버퍼링을 유효하게 한다.

다음의 예에서는, CGrabCB 라는 이름의 클래스에 콜백 인터페이스를 이행 하고 있다. 이 클래스는, DirectShow SDK 에 포함된 base class의 1 개인 CUnknown 로부터 파생하고 있다. CUnknown 의 사용은 필수는 아니지만, 이것을 사용하는 것으로, 코드가 얼마인가 짧아진다. CUnknown 의 사용의 상세한 것에 대하여는, 「IUnknown 의 이행 방법」을 참조할것.

이 예에서는,SampleCB 메소드가, 각 샘플의 시작 타임을 콘솔 윈도우에 출력한다. BufferCB 메소드는 이행 되지 않고, E_NOTIMPL 를 돌려준다.

#include <streams.h>
// Strmbase.lib 에 링크한다

class CGrabCB: public CUnknown, public ISampleGrabberCB
{
public:
    DECLARE_IUNKNOWN;

    STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv)
    {
        if( riid == IID_ISampleGrabberCB )
        {
            return GetInterface((ISampleGrabberCB*) this, ppv);
        }
        return CUnknown::NonDelegatingQueryInterface(riid, ppv);
    }

    // ISampleGrabberCB 의 메소드
    STDMETHODIMP SampleCB(double SampleTime, IMediaSample *pSample)
    {
        printf("Sample time: %f\n", SampleTime);
        return S_OK;
    }

    STDMETHODIMP BufferCB(double SampleTime, BYTE *pBuffer, long BufferLen)
    {
        return E_NOTIMPL;
    }

    // constructor
    CGrabCB( ) : CUnknown("SGCB", NULL)
    { }
};

이 콜백을 사용하려면 , CGrabCB 클래스의 새로운 인스턴스를 생성해, 그것을 ISampleGrabber::SetCallback 메소드에 건네준다. 다음에, 필터 그래프를 실행한다.

pGrab->SetOneShot(FALSE);
pGrab->SetBufferSamples(FALSE);

CGrabCB *cb = new CGrabCB();
pGrab->SetCallback(cb, 0);


AVI 파일의 재압축

이 주제에서는,캡춰 그래프 빌더를 사용해 AVI (Audio-Video Interleaved) 파일을 재압축하는 방법을 해설한다. 캡춰 그래프 빌더는, 캡춰 그래프나 그 외의 커스텀 필터 그래프를 구축하는 COM 오브젝트이다.

주 : Microsoft® DirectShow® 에 부속되는 캡춰 그래프 빌더에는 2 종류의 버젼이 있다. 각각 다른 클래스 식별자를 가져, 다른 인터페이스를 공개한다. 낡은 (분)편의 버젼은, CLSID_CaptureGraphBuilder 의 클래스 식별자를 가져,ICaptureGraphBuilder 인터페이스를 공개한다. 이것은, 기존의 어플리케이션과의 호환성을 위해서(때문에) 지원 되고 있다. 새로운 버젼은, CLSID_CaptureGraphBuilder2 의 클래스 식별자를 가져, 유연성이 더한 새로운 ICaptureGraphBuilder2 인터페이스를 공개한다.

비디오 캡춰 어플리케이션에서의 ICaptureGraphBuilder2 의 사용에 대해서는, 「캡춰 어플리케이션의 쓰는 법」을 참조할것. 여기에서는,ICaptureGraphBuilder2 를 사용해, 미디어 데이터를 원시 파일로부터 출력 파일에 카피해, 그 도중에 데이터를 재압축한다.

이 주제는, 이하의 섹션으로 구성된다 :

  • 그래프의 생성
  • 렌더링 섹션의 구축
  • 소스 필터의 접속
  • 파일의 기입
  • 샘플 코드

그래프의 생성

우선, 이하의 예에 나타내도록(듯이), 캡춰 그래프 빌더의 인스턴스를 생성한다.

ICaptureGraphBuilder2   *pBuild = NULL;
CoCreateInstance(CLSID_CaptureGraphBuilder2, NULL, CLSCTX_INPROC,
        IID_ICaptureGraphBuilder2, (void **) &pBuild);

캡춰 그래프 빌더는, 자동적으로 필터 그래프 매니저를 생성 한다. 처음은 필터 그래프는 하늘에서, 필터를 가지고 있지 않다. 필터 그래프는, 이하의 2 단계의 처리로 구축한다.

  1. 그래프의 렌더링 섹션을 구축한다. 이 섹션에는,AVI MUX 필터와파일 라이터가 포함된다. MUX 필터는, 비디오 스트림과 오디오 스트림을, 파일 라이터용의 1 개의 AVI 스트림에 결합한다.
  2. 파일 소스 필터를 그래프에 추가해, 그것을 MUX 필터에 접속한다. 캡춰 그래프 빌더는, 파일 포맷을 해석하기 위해서 필요한 스플리터 필터와 디코더 필터를 삽입한다. 필요한 경우는, 오디오 및 비디오 스트림을, 오디오 및 비디오 압축 필터에 통할 수도 있다.

렌더링 섹션의 구축

그래프의 렌더링 섹션을 구축하려면 ,ICaptureGraphBuilder2::SetOutputFileName 메소드를 호출한다. 이 메소드는, 출력의 미디어 서브 타입과 출력 파일의 이름을 지정하는 입력 파라미터를 받아, MUX 필터와 파일 라이터에의 포인터가 저장 된 출력 파라미터를 돌려준다. MUX 필터에의 포인터는, 그래프 구축의 다음의 단계에서 필요하게 된다. 파일 라이터에의 포인터는 이 예에서는 필요없기 때문에, NULL 로 할 수 있다. 코드를 짧게 유지하기 위해서(때문에), 이하의 예에서는 파일명에 리터럴 캐릭터 라인을 사용하고 있다.

IBaseFilter *pMux = NULL;
pBuild->SetOutputFileName(
        &MEDIASUBTYPE_Avi,  // 파일 타입.
        L"Output.avi",// 파일명.
        &pMux,              // 멀티플렉서에의 포인터를 받는다.
        NULL);                  // 파일 라이터에의 포인터를 받는다.

이 메소드가 돌아가면(자), MUX 필터에의 포인터의 참조 카운트가 커지고 있으므로, 어플리케이션은 종료시에 포인터를 해방해야 한다. MUX 필터는, AVI 포맷을 제어하기 위해서 이하의 인터페이스를 공개하고 있다.

  • IConfigInterleaving 에는, 인터리브 모드를 설정하기 위한 메소드가 포함된다.
  • IConfigAviMux 에는, 마스터 스트림과 AVI 호환성 인덱스를 설정하기 위한 메소드가 포함된다.

다음의 그림은, 현상의 필터 그래프를 나타낸다.

필터 그래프의 렌더링 섹션

소스 필터의 접속

다음의 작업은, 그래프의 나머지의 부분에의 소스 필터의 접속이다. 우선,ICaptureGraphBuilder2::GetFiltergraph 메소드를 호출해, 필터 그래프의 IGraphBuilder 인터페이스에의 포인터를 취득한다. 다음에,IGraphBuilder::AddSourceFilter 메소드를 호출한다. 이 메소드는, 파일을 로드해, 파일 소스 필터에의 포인터를 취득한다.

IGraphBuilder   *pGraph = NULL;
IBaseFilter     *pSrc = NULL;

pBuild->GetFiltergraph(&pGraph);
pGraph->AddSourceFilter(L"C:\\Input.avi", L"Source Filter", &pSrc);

다음에, 파일의 재압축에 사용하는 비디오 및 오디오 압축 필터의 인스턴스를 생성한다. 1 개의 방법으로서 유저의 시스템에 있는 압축 디바이스를 열거해, 유저가 디바이스를 선택하도록 할 수 있다. 이 방법에 대해서는, 「디바이스와 필터의 열거」를 참조할것. 다른 방법으로서 사용하고 싶은 압축 필터가 있는 경우는,CoCreateInstance 를 호출해 그 인스턴스를 직접 생성할 수도 있다. 압축 필터의 인스턴스를 생성하면(자),IFilterGraph::AddFilter 를 호출해 인스턴스를 필터 그래프에 추가한다.

이하의 예에서는, 비디오를 압축하는 AVI Compressor 필터의 인스턴스를 생성하고 있다. 오디오는 압축하지 않는 채로 해 있다.

CoCreateInstance(CLSID_AVICo, NULL, CLSCTX_INPROC,
        IID_IBaseFilter, (void **) &pVComp);
pGraph->AddFilter(pVComp, L"Compressor");

다음의 그림에 나타내도록(듯이), 아직 소스 필터와 압축 필터는, 그래프내외의 것과는 접속되어 있지 않다.

소스 필터와 압축 필터를 수반하는 필터 그래프

그래프 구축의 마지막 스텝은,ICaptureGraphBuilder2::RenderStream 메소드를 사용한 비디오 및 오디오 스트림의 렌더링이다. 이 메소드는, 소스 필터의 출력 핀을 그래프의 렌더링 섹션에 접속해, 옵션이 지정되면 압축 필터를 통한다.

ICaptureGraphBuilder2 의 메소드는, 프리뷰 및 캡춰용으로 다른 출력 핀을 가질 수 있는 비디오 카메라 등, 생의 캡춰 소스를 취급할 수 있도록(듯이) 디자인되고 있다. 그러한 상황에서는,RenderStream 의 최초의 2 개의 파라미터로, 핀 카테고리와 미디어 타입을 지정하는 것으로, 어느 핀을 접속하는지를 지정한다. 파일 소스 필터를 사용하는 경우, 출력 핀은 1 개 뿐이므로, 이러한 파라미터를 지정할 필요는 없다.

그 다음의 3 개의 파라미터는, 소스 필터 (또는, 소스 필터의 핀), 압축 필터, 및 세면대 필터에의 포인터이다. 파일에 기입하는 경우는, 이러한 마지막 파라미터는 멀티플렉서에의 포인터가 아니면 안된다.

이하의 코드는, 비디오 압력을 개입시켜 비디오 스트림을 렌더링 한다.

pBuild->RenderStream(
        NULL,       // 출력 핀의 카테고리
        NULL,       // 미디어 타입
        pSrc,       // 소스 필터
        pVComp,     // 압력 필터
        pMux);      // 세면대 필터 (AVI Mux)

다음의 그림은, 현상의 필터 그래프를 나타낸다.

렌더링 된 비디오 스트림

이 그림에서는, 원시 파일에 2 개의 스트림, 즉 오디오 스트림과 비디오 스트림이 있으면(자) 가정하고 있다. 그 경우,AVI 스플리터 필터에는 오디오 스트림용의 출력 핀이 포함되지만, 핀은 그래프내의 아무것도 접속되어 있지 않다. 오디오 스트림을 렌더링 하려면 ,RenderStream 를 한번 더 호출한다.

pBuild->RenderStream(NULL, NULL, pSrc, NULL, pMux);

소스 필터의 유일한 출력 핀은 이미 접속되고 있으므로,RenderStream 메소드는 스플리터 필터의 미접속의 출력 핀을 찾는다. 다음에, 오디오 출력 핀을 찾아내 그것을 MUX 필터에 직접 접속한다. 원시 파일에 비디오 스트림만이 있어, 오디오 스트림이 없는 경우, 2 번째의 RenderStream 의 호출은 예상 대로 실패한다. 그러나,RenderStream 에의 최초의 호출로 그래프는 완성하므로, 2 번째의 호출이 실패해도 문제는 없다. 그래프는 실행된다.

다음의 그림은, 완성한 필터 그래프를 나타낸다.

렌더링 된 오디오 및 비디오 스트림

이 예에서는, 2 회의 호출의 순서가 중요하다. 비디오 스트림은 재압축되지만, 오디오 스트림은 재압축되지 않기 때문이다. 최초의 호출에는 비디오 압력이 포함되어 있으므로, 비디오 스트림이 지정된다. 2 번째의 호출에는 압력이 포함되지 않기 때문에, 어느 스트림 타입에도 적용할 수 있다. 남아 있는 것은 오디오 스트림 뿐이므로, 이 호출은 올바르게 기능한다.

다만, 이하에 나타내도록(듯이), 이 순서가 바뀌었다고 한다.

pBuild->RenderStream(NULL, NULL, pSrc, NULL, pMux);
// 실수. 이것에 의해 비디오 스트림이 렌더링 되는 일도 있다.

pBuild->RenderStream(NULL, NULL, pSrc, pVComp, pMux);
// 하면, 이것은 실패한다.

이 예에서는, 2 번째의 호출로 압력이 지정되고 있다. 최초의 호출에 의해, 비디오 스트림과 오디오 스트림의 어느 쪽이 렌더링 될까는 미확정이지만, 비디오 스트림이 렌더링 되면, 2 번째의 호출은 실패한다.

한편, 이 예로 비디오 압력과 오디오 압력의 양쪽 모두가 사용되었을 경우, 순서는 문제는 아니게 된다. 각각의 호출에 의해, 어느 쪽인가의 스트림이 완전하게 지정되기 때문에 있다. 같은 이유로써, 압축 필터를 사용하지 않는 경우도, 순서는 문제는 아니게 된다. 그 경우, 2 개의 호출은 같게 된다.

원시 파일에 3 개 이상의 스트림이 있는 경우, 필터 그래프는 올바르게 구축되지 않고, 예기치 않은 동작을 나타낸다. 이런 상황은 보기 드물지만, 안전이기 때문에, 최초의 스트림을 렌더링 한 후, 스플리터 필터의 출력 핀을 열거할 필요가 있다. 상세한 것에 대하여는, 「필터 그래프내의 오브젝트의 열거」를 참조할것.

파일의 기입

파일을 기입하기 전에, 압축 필터의 프로퍼티를 설정할 수 있다. 샘플 코드에는, bit rate와키 프레임 레이트를 설정하는 방법을 나타내고 있다. 상세한 것에 대하여는, 후의 샘플 코드를 참조할것.

파일을 기입하려면 , 필터 그래프를 실행해,IMediaControl::Run 메소드를 호출해, 재생이 종료하는 것을 기다리고 나서,IMediaControl::Stop 를 호출해 그래프를 명시적으로 정지해야 한다. 정지하지 않으면 파일은 올바르게 기입해지지 않다. 상세한 것에 대하여는, 「이벤트에의 응답」을 참조할것.

파일 기입 처리의 진행 상황을 표시하려면 ,IMediaSeeking 인터페이스에 관해서 MUX 필터에 문의한다. IMediaSeeking::GetDuration 메소드를 호출해, 파일의 시간폭을 취득한다. 그래프의 실행중은, 정기적으로 IMediaSeeking::GetCurrentPosition 메소드를 호출해, 스트림에서의 그래프의 현재 위치를 취득한다. 현재 위치를 시간폭으로 나누면(자), 완료한 비율을 얻을 수 있다.

주 : 보통, 어플리케이션은 IMediaSeeking 에 관해서는 필터 그래프 매니저에 문의해야 하는 것이어, 개별의 필터에도 문의해야 하는 것이 아니다. 파일의 기입은, 이 규칙의 예외이다. 필터 그래프 매니저는, 필터로부터 현재 위치를 취득하지 않는다. 그 대신해, 시작 위치와 그래프의 실행 시간을 기본으로 해 위치를 계산한다. 파일의 기입에서는, 이것에 의해 잘못한 결과가 생기는 일도 있다. 이것은, 파일의 기입 시간이 파일의 시간폭보다 길어지는 일이 있기 때문에 있다. MUX 필터로부터 위치를 취득 하면, 정확한 결과를 얻을 수 있다.

샘플 코드

보다 간결하게 하기 위한(해), 이하의 코드에서는 에러 체크는 행해지지 않는다.

#include <dshow.h>
#include <stdio.h>

void __cdecl main(void)
{
    ICaptureGraphBuilder2   *pBuild = NULL;
    IGraphBuilder           *pGraph = NULL;
    IBaseFilter             *pSrc = NULL;       // 소스 필터
    IBaseFilter             *pMux = NULL;       // MUX 필터
    IBaseFilter             *pVComp = NULL;     // 비디오 압력 필터

    CoInitialize(NULL);

    // 캡춰 그래프 빌더를 생성 한다.
    CoCreateInstance(CLSID_CaptureGraphBuilder2, NULL, CLSCTX_INPROC,
            IID_ICaptureGraphBuilder2, (void **) &pBuild);

    // 그래프의 렌더링 섹션을 생성 한다.
    pBuild->SetOutputFileName(
            &MEDIASUBTYPE_Avi,  // 파일 타입.
            L"C:\\Output.avi",          // 파일명.
            &pMux,              // 멀티플렉서에의 포인터를 받는다.
            NULL);                  // 파일 라이터에의 포인터를 받는다.

    // 원시 파일을 로드한다.
    pBuild->GetFiltergraph(&pGraph);
    pGraph->AddSourceFilter(L"C:\\Input.avi", L"Source Filter", &pSrc);

    // 압력 필터를 추가한다.
    CoCreateInstance(CLSID_AVICo, NULL, CLSCTX_INPROC,
            IID_IBaseFilter, (void **) &pVComp);
    pGraph->AddFilter(pVComp, L"Compressor");

    // 압력을 개입시켜 비디오 스트림을 렌더링 한다.
    pBuild->RenderStream(
            NULL,       // 출력 핀의 카테고리
            NULL,       // 미디어 타입
            pSrc,       // 소스 필터
            pVComp,     // 압력 필터
            pMux);      // 세면대 필터 (AVI Mux)

    // 오디오 스트림을 렌더링 한다.
    pBuild->RenderStream(NULL, NULL, pSrc, NULL, pMux);

    // 비디오 압축 프로퍼티를 설정한다.
    IAMStreamConfig         *pStreamConfig = NULL;
    IAMVideoCompression     *pCompress = NULL;

    // 100 k/초의 데이터 레이트로 압축한다.
    AM_MEDIA_TYPE *pmt;
    pBuild->FindInterface(NULL, NULL, pVComp, IID_IAMStreamConfig, (void **) &pStreamConfig);
    pStreamConfig->GetFormat(&pmt);
    if (pmt->formattype == FORMAT_VideoInfo)
    {
        ((VIDEOINFOHEADER *)(pmt->pbFormat)) ->dwBitRate = 100000;
        pStreamConfig->SetFormat(pmt);
    }
    DeleteMediaType(pmt);

    // 4 개의 프레임 마다 키 프레임을 요구한다.
    pStreamConfig->QueryInterface(IID_IAMVideoCompression, (void **) &pCompress);
    pCompress->put_KeyFrameRate(4);
    pCompress->Release();
    pStreamConfig->Release();

// 그래프를 실행한다.
    IMediaControl           *pControl = NULL;
    IMediaSeeking   *pSeek = NULL;
    IMediaEvent             *pEvent = NULL;
    pGraph->QueryInterface(IID_IMediaControl, (void **) &pControl);
    pGraph->QueryInterface(IID_IMediaEvent, (void **) &pEvent);

    HRESULT hr = pMux->QueryInterface(IID_IMediaSeeking, (void**) &pSeek);

    pControl->Run();
    printf("Recompressing... \n");
    long evCode;

    if (SUCCEEDED(hr))  // IMediaSeeking 가 지원 된다
    {
        REFERENCE_TIME rtTotal, rtNow = 0;
        pSeek->GetDuration(&rtTotal);
        while ((pEvent->WaitForCompletion(1000, &evCode)) == E_ABORT)
        {
            pSeek->GetCurrentPosition(&rtNow);
            printf("%d%%\n", (rtNow * 100) /rtTotal);
        }
        pSeek->Release();
    }
    else  // 진행 상황을 갱신할 수 없다.
    {

    pEvent->WaitForCompletion(INFINITE, &evCode);
    pControl->Stop();
    printf("All done\n");

    pSrc->Release();
    pMux->Release();
    pVComp->Release();
    pControl->Release();
    pEvent->Release();
    pBuild->Release();
    pGraph->Release();
    CoUninitialize();
}


DirectShow 레퍼런스

이 주제에서는, Microsoft® DirectShow® 의 레퍼런스 정보를 소개한다.

  • 필터
  • 인터페이스
  • 구조체
  • 열거형
  • 정수와 GUID
  • 함수
  • MSWebDVD ActiveX 컨트롤
  • 프로퍼티 세트
  • DirectShow 의 컴퍼넌트
  • DirectShow base class


필터

Microsoft® DirectShow® 에서는, Microsoft® Windows® 와 함께 자동적으로 인스톨 되는, 디폴트 필터의 모임이 제공된다. 이러한 필터는, 수많은 데이터 포맷을 지원 하면 동시에, 높은 하드웨어비의존성을 제공한다. 어플리케이션은, 목적의 시스템에 커스텀 필터를 등록, 인스톨 할 수 있다. 이하에, 디폴트의 필터를 나타낸다.

  • ACM 래퍼
  • 아날로그 비디오 크로스바
  • ASF 라이터
  • ASF 리더
  • 오디오 캡춰
  • 오디오 렌더링
  • AVI 압력
  • AVI 데콘프렛사
  • AVI 드로
  • AVI Mux
  • AVI 스플리터
  • BDA IP 세면대
  • BDA MPE 필터
  • BDA 네트워크 프로바이더
  • BDA SLIP 데후레이마
  • BDA MPEG2 트랜스폴트 정보 필터
  • CC 디코더
  • 칼라 스페이스 변환
  • 디폴트 DirectSound 디바이스
  • DMO 래퍼
  • DV Muxer
  • DV 스플리터
  • DV 비디오 디코더
  • DV 비디오 엔코더
  • DVD 네비게이터
  • 파일 소스 (Async)
  • 파일 소스 (URL)
  • 파일 라이터
  • 풀 스크린 렌더링
  • 인피닛트핀티
  • 내부 스크립 코맨드 렌더링
  • Line 21 디코더
  • MIDI 퍼서
  • MIDI 렌더링
  • MJPEG 압력
  • MJPEG 데콘프렛사
  • MPEG-1 오디오 디코더
  • MPEG-1 스트림 스플리터
  • MPEG-1 비디오 디코더
  • MPEG-2 디멀티플렉서
  • MPEG-2 스플리터
  • MSYUV 칼라 스페이스 변환 CODEC
  • NABTS/FEC CODEC 필터
  • Null 렌더링
  • 오버레이 믹서
  • 오버레이 믹서 2
  • QT 데콘프렛사
  • QuickTime 무비 퍼서 >
  • SAMI (CC) 퍼서
  • 샘플 grabber
  • 스마트티
  • Tee/Sink-to-Sink 컨버터
  • TV 오디오
  • TV 튜너
  • VBI 서페이스아로케이타
  • VFW 캡춰 필터
  • VGA 16 색디자라
  • 비디오 렌더링
  • WAVE 퍼서
  • WDM 비디오 캡춰
  • WST CODEC
  • WST 디코더


ACM 래퍼 필터

ACM 래퍼 필터는, Audio Compression Manager (ACM)를 사용하는 CODEC 가 Microsoft® DirectShow® 필터 그래프에 결합하는 것을 가능하게 한다. 전개는, PCM 오디오 에 대해서만 행해진다. 압력을 랩핑 하는 경우, 이 필터는 오디오 압력 카테고리로 간주해져 추가의 인터페이스를 지원 할 수가 있다. 이 필터는 필터 그래프 매니저에 의해 자동적으로 사용되므로, 수작업으로 그래프에 추가할 필요는 없다. 이 필터는, 재생 또는 샘플 레이트의 변환에게만 사용된다.

필터 인터페이스 | IBaseFilter ,IPersistPropertyBag
입력 핀 미디어 타입 | MEDIATYPE_Audio, MEDIASUBTYPE_NULL, FORMAT_WaveFormatEx
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 MEDIATYPE_Audio, MEDIASUBTYPE_PCM, FORMAT_WaveFormatEx

이하의 임의의 편성이 가능.

  • 1 초 쯤의 샘플수 (kHz) : 44. 1, 22.05, 11.025, 또는 8.0
  • 채널 : 스테레오 또는 물건
  • 1 샘플 근처의 비트수 : 8 또는 16
출력 핀인타페이스 | IAMStreamConfig ,IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_ACMWrapper
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | Quartz.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_AudioCompressorCategory


아날로그 비디오 크로스바 필터

아날로그 비디오 크로스바 필터는, Windows® 드라이버 모델(WDM)을 지원 하는 비디오 캡춰 디바이스로, 비디오 크로스바와 같은 기능을 한다. 1 개의 출력 스트림은, 아날로그 전용선 접속 시스템 비디오의 하드웨어 패스를 나타낸다. 입력 핀 의 1 개는 TV 튜너 (TV 튜너 필터)로부터 입력된다. 다른 입력 핀은, 비디오 스트림을 지원 한다. 그 필터는, 다운 스트림 접속으로 지원 되고 있는, 모든 미디어 서브 타입과 포맷을 지원 한다.

아날로그 비디오 크로스바 필터는, 소정의 소스 선택에 사용되는 IAMCrossbar 인터페이스를 공개한다.

이 필터는, Windows 98 및 Windows® 2000 에 대해 이용할 수 있다.
필터 인터페이스 | IAMCrossbar , ISpecifyPropertyPages, IPersistPropertyBag, IPersistStream
입력 핀 미디어 타입 | MEDIATYPE_AnalogAudio, MEDIATYPE_AnalogVideo
입력 핀인타페이스 | IKsPropertySet
출력 핀 미디어 타입 | MEDIATYPE_AnalogAudio, MEDIATYPE_AnalogVideo
출력 핀인타페이스 | IKsPropertySet
필터 CLSID | CLSID_CrossbarFilter
프로퍼티 페이지 CLSID | CLSID_CrossbarFilterPropertyPage
실행 모듈 | ksxbar.ax
메리트 | 드라이버에 의존한다.
카테고리 | AM_KSCATEGORY_CROSSBAR


ASF 라이터 필터

ASF 라이터는, 가변수의 입력 스트림을 받아들여 ASF (Advanced Streaming Format) 파일을 생성 한다. 이 필터는, 압축과 다중화를 취급한다. 다만, 압축 메카니즘은 우회도로 할 수가 있다. ASF 라이터는, 디지털 비디오 (DV) 캡춰, 오디오재압축, 및 네트워크 트리밍용의 AVI (Audio-Video Interleaved) 파일 또는 MPEG 멀티미디어 파일의 변환 등, 각종의 시나리오로 사용할 수가 있다. 이 필터는, Microsoft® DirectShow® 의 Microsoft® Windows Media™ Audio 파일 및 Windows Media Video 파일을 생성 하는 유일한 방법을 제공한다.

ASF 파일의 기술 방법에 대해서는, 「DirectShow 에서의 ASF 파일의 생성」을 참조할것.

필터 인터페이스 | IAMFilterMiscFlags , IConfigAsfWriter , IFileSinkFilter2 , IMediaSeeking , IPersistStream , ISpecifyPropertyPages
입력 핀인타페이스 | IPin ,IMemInputPin IAMStreamConfig
출력 핀 미디어 타입 | 이용할 수 없다.
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_WWAsfWriter
프로퍼티 페이지 CLSID | CLSID_AsfWriterProperties
실행 모듈 | Qasf.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | 지정 없음.

주의

이 필터에는, Windows Media Format Software Development Kit (SDK)의 유효한 인스톨이 필요하다.

입력 핀의 수는, ASF 스트림의 프로파일 또는 프로파일 식별자에 응해 다르다.

입력 핀상에서 지원 되는 IAMStreamConfig 의 메소드는,IAMStreamConfig::GetFormat 뿐이다. 다른 모든 메소드는 E_NOTIMPL 를 돌려준다. GetFormat 를 호출해, 필터의 구성에 사용된 ASF 프로파일에 근거해, 스트림의 포맷을 판정한다. 상세한 것에 대하여는, 「IConfigAsfWriter )」를 참조할것.


ASF 리더 필터

ASF 파일의 이름이 주어지면(자), ASF 리더는 디스크로부터 파일을 읽어내, 압축된 스트림을 해석해, 각각 출력 핀을 공개한다. 보통, 이 필터는, 전개를 실시하는 오디오 또는 비디오 CODEC 필터에 접속한다. ASF 파일이 시크 가능한 경우는 시크가 지원 된다. ASF 리더는, 스트림을 다운 스트림에 보내기 전에 샘플에 타임 스탬프를 설정한다.

이 필터는, Microsoft® Windows Media™ Software Development Kit (SDK)가 필요하다. 이 필터는, ASF 파일의 디폴트의 소스 필터는 아니다. 이 필터는, 클래스 식별자 (CLSID)를 사용해 명시적으로 그래프에 추가할 필요가 있다. 이 필터는, Microsoft® DirectShow® 의 IFileSourceFilter 인터페이스 및 Windows Media SDK 의 IWMHeaderInfo 인터페이스를 공개한다.

이것은, 파일 재생용의 일반적인 ASF 필터 그래프이다.

필터 인터페이스 | IFileSourceFilter ,IWMHeaderInfo
입력 핀 미디어 타입 | 이용할 수 없다.
입력 핀인타페이스 | 이용할 수 없다.
출력 핀 미디어 타입 | ASF 파일내의 스트림에 응해 다르다.
출력 핀인타페이스 | IMediaSeeking
필터 CLSID | CLSID_WMAsfReader {187463A0-5BB7-11d3-ACBE-0080C75E246E}
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | Qasf.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory


오디오 캡춰 필터

오디오 캡춰 필터는, 오디오 캡춰 디바이스를 나타낸다. 오디오 캡춰 필터에는, 1 개의 캡춰 출력 핀과 (LineIn, Mic, CD, MIDI 등의 카드 위에의 입력의 타입 마다 1 개의) 복수의 입력 핀이 있다.

이 필터는, 복수의 하드웨어 디바이스에 대해서 사용할 수 있다. 시스템 디바이스 열거자는, 이 필터를 사용할 수 있는 각각의 디바이스에 대해서 일의인 모니카를 돌려준다. 프렌들리명은 디바이스의 이름에 대응한다 (이것은, GraphEdit 에 표시되는 이름이다). 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것.

필터 인터페이스 | IAMAudioInputMixer ,IAMFilterMiscFlags ,IAMResourceControl ,IBaseFilter , IPersistPropertyBag,ISpecifyPropertyPages
입력 핀 미디어 타입 | MEDIATYPE_AnalogAudio, MEDIASUBTYPE_NULL
입력 핀인타페이스 | IAMAudioInputMixer ,IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Audio, MEDIASUBTYPE_NULL
출력 핀인타페이스 | IAMBufferNegotiation ,IAMPushSource ,IAMStreamConfig ,IAMStreamControl ,IKsPropertySet ,IPin ,IQualityControl
필터 CLSID | CLSID_AudioRecord
프로퍼티 페이지 CLSID | CLSID_AudioInputMixerProperties
실행 모듈 | qcap.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_AudioInputDeviceCategory

주의

입력 핀은 물리 하드웨어 접속을 나타내, DirectShow 외의 필터에 접속될 것은 없다.


오디오 렌더링 필터

오디오 렌더링 필터는 범용 오디오 렌더링 필터로,비동기 파일 소스,파일 소스 (URL),MPEG-1 스트림 스플리터,AVI 스플리터,WAVE 퍼서, 또는 그 외의 오디오 변환 필터가 WAV 오디오를 포함하고 있는 경우에, 그 출력에 접속할 수가 있다. 이 필터는, 오디오 스트림의 서브 타입을 체크하지 않는다. 포맷 블록으로 건네받는 WAVEFORMAT 또는 WAVEFORMATEX 구조에는, 이 필터에의 접속에 필요한 정보가 들어가 있다.

이 필터는 오디오 드라이버에 의존하는 있는 폭의 샘플 레이트를 지원 한다.

필터 인터페이스 | IAMDirectSound ,IAMResourceControl ,IBaseFilter ,IBasicAudio ,IMediaPosition ,IMediaSeeking ,IPersistPropertyBag,IPersistStream,IQualityControl ,IReferenceClock ,
입력 핀 미디어 타입 | MEDIATYPE_Audio
입력 핀인타페이스 | IMemInputPin ,IPin ,IPinConnection ,IQualityControl
출력 핀 미디어 타입 | 이용할 수 없다.
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_AudioRender
프로퍼티 페이지 CLSID | CLSID_AudioProperties, CLSID_AudioRendererAdvancedProperties
실행 모듈 | quartz.dll
메리트 | MERIT_PREFERRED
카테고리 | CLSID_AudioRendererCategory


AVI 압력 필터

AVI 압력은, Video Compression Manager (VCM) 인터페이스를 지원 하는 인스톨 가능한 비디오 압력의 래퍼 필터이다. VCM 인터페이스는 DirectShow 아키텍쳐에는 포함되지 않기 때문에, 이러한 압력이 필터 그래프의 문맥내에서 기능하기 위해서는 "래퍼 필터 " 가 필요하다. AVI 압력은, 압축 AVI 파일을 새롭게 생성 하거나 기존의 AVI 파일을 재압축하는 그래프에 대해 사용된다. 캡춰 그래프 빌더에 대해서 이 필터를 캡춰 그래프에 추가하도록 지시할 수가 있다.

AVI 압력의 입력 핀은, 전개된 비디오 데이터를 건네주는 필터에 업 스트림을 접속한다. 이러한 필터에는, VFW 캡춰 필터나 WDM 비디오 캡춰 필터 (어느쪽이나 하드웨어 비디오 소스를 랩핑 한다), AVI 스플리터, 칼라 스페이스 변환등의, 전개된 비디오 데이터를 처리할 수 있는 필터가 포함된다. 보통, AVI 압력의 다운 스트림 핀은, 압축 비디오와 ACM 래퍼 필터로부터의 압축 오디오 스트림을 인터리브 하는 AVI MUX 필터에 접속된다. AVI 압력이 VCM 와 함께 동작하는 것과 같게, ACM 래퍼는 Audio Compression Manager 와 함께 동작한다.

압력에 프로퍼티 페이지가 준비되어 있어, 유저가 각종의 압축 파라미터를 설정할 수 있게 되어 있는 경우, 어플리케이션은 AVI 압력의 IAMVfwCompressDialogs 인터페이스를 사용해 그것을 표시할 수가 있다.

주 : MPEG 압력 및 데콘프렛사는 VCM CODEC 로서는 이행 되지 않고 , 네이티브 DirectShow 필터로서의 보고 이행 된다. 같이 DirectShow 로 제공되는 Intel® Indeo® 압력 및 데콘프렛사도 VCM CODEC 로서가 아니고 네이티브 필터로서 이행 된다.

필터 인터페이스 | IAMVfwCompressDialogs ,IBaseFilter ,IPersistPropertyBag,ISpecifyPropertyPages
입력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_NULL
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_NULL
출력 핀인타페이스 | IAMStreamConfig ,IAMVideoCompression ,IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_AVICo
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | qcap.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_VideoCompressorCategory


AVI 데콘프렛사피르타

AVI 데콘프렛사는, Video Compression Manager (VCM) 인터페이스를 지원 하는 인스톨 가능한 비디오 압력의 래퍼 필터이다. VCM 인터페이스는 DirectShow 아키텍쳐에는 포함되지 않기 때문에, 이러한 압력이 필터 그래프의 문맥내에서 기능하기 위해서는 "래퍼 필터 " 가 필요하게 된다.

AVI 파일을 렌더링하기 위한 그래프를 생성 하면 와, 필터 그래프 매니저는 파일의 AVI 헤더내의 FOURCC 를 체크해 그 비디오 스트림이 압축되고 있는지 어떤지를 판정한다. 압축되고 있는 경우, 필터 그래프 매니저는 AVI 데콘프렛사를 추가한다. AVI 데콘프렛사는, 해당 파일을 처리할 수 있는, 인스톨 되고 있는 데콘프렛사를 레지스트리로부터 찾는다 (다만 Intel® Indeo® 압축 스킴으로 AVI 파일이 압축되고 있는 경우는, AVI 데콘프렛사 대신에 네이티브 Indeo DirectShow 필터가 그래프에 사용된다). 이 처리는 모두 자동적으로 행해지므로, 어플리케이션측은 상세하게 관계해 책임을 질 필요는 없다.

업 스트림 핀에서는, AVI 데콘프렛사는 일반적으로 AVI 스플리터에 접속한다. 출력 핀에서는, AVI 데콘프렛사는 일반적으로 비디오 렌더러에 접속한다.
필터 인터페이스 | IBaseFilter
입력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_NULL, FORMAT_VideoInfo 서브 타입은 낡은 포맷의 FOURCC 에 대응할 필요가 있다 (상세한 것에 대하여는, 「FOURCCMap 클래스」를 참조할것).
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_NULL, FORMAT_VideoInfo
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_AVIDec
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory

주의

핀 위에의 미디어 서브 타입은, AVI 파일내의 FourCC 코드로부터 생성 된다.


AVI 드로피르타

AVI 드로는, 외부 NTSC TV 모니터에 비디오를 출력할 경우에 AVI 데콘프렛사 대신에 자동적으로 재생 그래프에 사용된다.

필터 인터페이스 | IBaseFilter
입력 핀 미디어 타입 MEDIATYPE_Video, FORMAT_VideoInfo

다음의 서브 타입이 유효
  • MEDIASUBTYPE_MJPG
  • MEDIASUBTYPE_TVMJ
  • MEDIASUBTYPE_WAKE
  • MEDIASUBTYPE_CFCC
  • MEDIASUBTYPE_IJPG
  • MEDIASUBTYPE_Plum
  • MEDIASUBTYPE_DVCS
  • MEDIASUBTYPE_DVSD
  • MEDIASUBTYPE_MDVF
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_NULL
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IOverlayNotify ,IPin ,IQualityControl
필터 CLSID | CLSID_AVIDraw
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_NORMAL + 100
카테고리 | CLSID_LegacyAmFilterCategory

주의

AVI 드로피르타와 VFW 캡춰 필터는 어느쪽이나 같은 하드웨어에 접속하므로, 같은 필터 그래프내에서 사용할 수 없다.


AVI Mux 필터

AVI Mux 는 복수의 입력 스트림을 받아 그것들을 AVI 포맷에 인터리브 한다. 비디오 캡춰 어플리케이션이나 오쏘링 어플리케이션은, AVI Mux 필터를 사용해 파일을 AVI 포맷으로 디스크에 보존할 수가 있다. 보통, 이 필터는파일 라이터 필터에 접속되지만, 입력 핀으로 IStream 및 IMemInputPin 를 지원 하는 임의의 필터에 접속할 수가 있다. AVI Mux 필터는, 각각의 입력 스트림에 대해서 다른 입력 핀을 생성 한다.

필터 인터페이스 | IBaseFilter ,IConfigAviMux ,IConfigInterleaving ,IMediaSeeking ,IPersistMediaPropertyBag ,ISpecifyPropertyPages
입력 핀 미디어 타입 낡은 포맷의 FOURCC 에 대응하는 메이저 타입, 또는 MEDIATYPE_AUXLine21Data (상세한 것에 대하여는, 「FOURCCMap 클래스」를 참조할것).
  • 메이저 타입이 MEDIATYPE_Audio 인 경우, 포맷은 FORMAT_WaveFormatEx 가 아니면 안된다.
  • 메이저 타입이 MEDIATYPE_Video 인 경우, 포맷은 FORMAT_VideoInfo 또는 FORMAT_DvInfo 가 아니면 안된다.
  • 메이저 타입이 MEDIATYPE_Interleaved 인 경우, 포맷은 FORMAT_DvInfo 가 아니면 안된다.
입력 핀인타페이스 | IAMStreamControl ,IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Stream, MEDIASUBTYPE_avi
출력 핀인타페이스 | IPin ,IPinFlowControl ,IQualityControl
필터 CLSID | CLSID_AviDest
프로퍼티 페이지 CLSID | CLSID_AviMuxProptyPage, CLSID_AviMuxProptyPage1
실행 모듈 | qcap.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_LegacyAmFilterCategory
미디어 | 없음.

주의

이 필터는 복수의 입력 핀과 1 개의 출력 핀을 가진다.


AVI 스플리터 필터

AVI 스플리터 필터는, AVI 파일의 재생에 사용한다. AVI 스플리터 필터는, AVI 포맷의 데이터를 받아, 그것을 구성 스트림에 분할한 이후의 처리나 렌더링에 이용할 수 있도록(듯이) 한다. 이 필터는 IAsyncReader 를 지원 하는 출력 핀을 가지는 임의의 필터에 접속할 수가 있지만, 보통은 입력 핀으로비동기 파일 소스 필터에 접속된다 (AVI Mux 필터는 IAsyncReader 를 지원 하지 않는 것에 주의 해야 한다).

필터 인터페이스 | IAMMediaContent ,IBaseFilter ,IPersistMediaPropertyBag
입력 핀 미디어 타입 | MEDIATYPE_stream, MEDIASUBTYPE_avi
입력 핀인타페이스 | IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIATYPE_audio, 또는 다른 타입 (파일의 내용, 파일이 압축되고 있는지 어떤지, 어떠한 CODEC 가 사용되고 있을까에 응해 다르다).
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_AviSplitter
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory

주의

이 필터는, AVI 재생 필터 그래프를 개입시켜 데이터를 푸쉬 해, 시크를 이행 하므로, 소스 필터로 간주해진다.


BDA IP 세면대

BDA IP 세면대 는 커넬 모드 필터로, BDA 혹은 비 BDA, 아날로그 혹은 디지털, TV 그래프 사용되어(NABTS VBI 스캔 라인에 있는 것 같은) IP 데이터를 Winsock 에 출력한다. 아날로그 그래프에서는, 업 스트림을 BDA SLIP 데후레이마 에 접속한다. 디지털 그래프에서는, 업 스트림을 BDA MPE 필터 에 접속한다. DirectX® 8.0 에서는 다운 스트림에의 접속은 지원되어 있지 않은, 어플리케이션 개발자는 Winsock 로부터 IP 데이터를 받아 처리하려면 , 자신의 컴퍼넌트를 이행 해야 한다. BDA IP 세면대 에는 어플리케이션으로부터 호출해 가능한 인터페이스는 없다.

BDA IP 세면대 는 GrapEdit 내에서"BDA Network Providers" 카테고리에 있다. 이것은 커넬 모드 필터이므로, 어플리케이션은 그것을 직접 Co-Create 할 수 없지만, 「디바이스와 필터의 열거」로 설명되고 있도록(듯이),시스템 디바이스 열거자 를 사용해 그것을 인스턴스화할 수가 있다. 이 필터는 IFilterGraph::AddFilter 를 사용해, 그래프에 수동으로 추가되지 않으면 안 되는,캡춰 그래프 빌더 는 이 필터를 그래프에 추가하기 위해(때문에)는 사용할 수 없다.


BDA MPE 필터

멀티 프로토콜 캡슐화 (MPE)는 IP 데이터를 디지털 TV 네트워크로 흘리기 위한 프로토콜이다. BDA MPE 필터 는 커넬 모드 필터이며, IP 패킷을 MPE 프레임으로부터 추출해, 그것을 BDA IP 세면대 에 최종적으로는 Winsock 에 출력한다, 거기서 흥미를 가지는 어플리케이션은 그 데이터를 (들)물어, 처리한다. BDA SLIP 데후레이마 는 같은 기능을 아날로그 TV 그래프로 실행한다, 여기에서는 SLIP 후레이밍프로트콜이 사용된다.

BDA MPE 필터 는 GrapEdit 내에서 "BDA Network Providers" 카테고리에 있다. 이것은 커넬 모드 필터이므로, 어플리케이션은 직접 co-create 할 수 없지만,디바이스와 필터의 열거 로 설명되고 있도록(듯이),시스템 디바이스 열거자 를 사용해 인스턴스화하지 않으면 안 된다. 이 필터는 IFilterGraph::AddFilter 메소드를 사용해 그래프에 수동으로 추가되지 않으면 안 되는,캡춰 그래프 빌더 는 이 필터를 그래프에 추가하기 위해서는 사용할 수 없다.


BDA 네트워크 프로바이더

Microsoft 는 2 개의 네트워크 프로바이더 필터를 제공하는, 1 개(살)은 ATSC 네트워크용으로, 1 개(살)은 DVB 네트워크용이다. 네트워크 프로바이더는 Microsoft® Broadcast Driver Architecture (BDA)를 베이스로 한 디지털 TV 필터 그래프내의 소스 필터인 이 필터는 BDA 필터 그래프내에서 ITuner 를 지원 하는 것으로써, 디폴트 튜너로서 기능한다. 그것은 기본적인 그래프 구성 태스크를 실행해,BDA MPEG2 트랜스폴트 정보 필터나 MPEG-2 디멀티플렉서와 같은 다운 스트림 필터를 이용 가능하게 한다.

퍼스널 컴퓨터의 TV 리시버는 1 개 이상의 하드웨어로 구성되어 1 개(살) 이상의 소프트웨어 결합되어 동작한다. BDA 는 이 하드웨어와 소프트웨어의 구성과 제어에 대해서 공통의 방법을 제공한다. BDA 네트워크 프로바이더는 이러한 인터페이스를 사용해, 리시버의 하드웨어 컴퍼넌트와 소프트웨어 컴퍼넌트를 구성해, TV 방송을 수신한다. 디지털 TV 방송의 경우, BDA 네트워크 프로바이더는 프로그램 정보를 BDA MPEG2 트랜스폴트 정보 필터 로부터 취득한다. 이 정보를 사용해 리시버 컴퍼넌트를 구성해, 기본 스트림 (예를 들어 비디오, 오디오, 데이터)을 취득해 프로그램을 렌더링 할 수 있도록(듯이) 한다.

Microsoft ATSC 네트워크 프로바이더 필터와 Microsoft DVB 네트워크 프로바이더 필터는 GrapEdit 내에서"BDA Network Providers" 카테고리에 있다. 이 필터는 IFilterGraph::AddFilter 메소드를 사용해 수동으로 그래프에 추가되지 않으면 안 되는, 캡춰 그래프 빌더는 이 필터를 그래프에 추가하기 위해서 이용할 수 없다.


BDA SLIP 데후레이마

BDA SLIP 데후레이마 는 커넬 모드 필터로, BDA 혹은 비BDA 아날로그 TV 그래프의 어디라도 사용할 수 있는, 이 그래프에서는 (NABTS VBI 스캔 라인에 있는 것 같은) IP 데이터의 SLIP 데·후레이밍이 필요하게 된다. 그것은 업 스트림을 NABTS/FEC VBI CODEC 에, 다운 스트림을 BDA IP 세면대 에 접속해, Winsock 경유로 수신하려고 하고 있는 어플리케이션이 IP 패킷을 이용할 수 있도록(듯이) 한다. BDA SLIP 데후레이마 에는 어플리케이션으로부터 호출해 가능한 인터페이스는 없다. 디지털 TV 그래프에서는,BDA MPE 필터 를 사용해 데이터 스트림으로부터 IP 패킷을 추출한다.

BDA SLIP 데후레이마 는 GraphEdit 내의 "BDA Receiver Component" 에 있다. 이것은 커넬 모드 필터이므로, 어플리케이션은 직접 co-create 할 수 없지만,디바이스와 필터의 열거 로 설명되고 있도록(듯이),시스템 디바이스 열거자 를 사용해 인스턴스화하지 않으면 안 된다. 이 필터는 IFilterGraph::AddFilter 메소드를 사용해 그래프에 수동으로 추가되지 않으면 안 되는,캡춰 그래프 빌더 는 이 필터를 그래프에 추가하기 위해서는 사용할 수 없다.


BDA MPEG2 트랜스폴트 정보 필터

디지털 TV 방송은 많은 프로그램과 관련의 기본 스트림(예를 들어 오디오, 비디오, ATVEF 데이터)을 1 개의 트랜스폴트 스트림에 멀티플렉스 한다. 리시버가 모든 개별의 프로그램에 관한 기본 스트림을 올바르게 취득할 수 있기 위해서(때문에), 또 리시버가 어느 프로그램이 스트림에 포함되어 있는지를 이해하기 위해서, 트랜스폴트 스트림은 그 트랜스폴트 스트림에 포함되어 있는 정보의 카탈로그로서 일하는 많은 겉(표)를 가지고 있다. 네트워크 프로바이더 의 디렉션아래에서,MPEG-2 디멀티플렉서 는 이러한 겉(표)를 트랜스폴트 정보 필터에 출력한다. 다음에, 다른 리시버 필터와 그래프내의 노드의 컨트롤이 생기도록(듯이), 트랜스폴트 정보 필터는 이러한 겉(표)를 퍼스 해, 네트워크 프로바이더에 그 정보를 제공한다.

BDA MPE 세면대 는 GrapEdit 내에서 "BDA Transport Information Renderers" 카테고리에 있다. 이 필터는 IFilterGraph::AddFilter 메소드를 사용해 그래프에 수동으로 추가되지 않으면 안 된다. 캡춰 그래프 빌더 는 이 필터를 그래프에 추가하기 위해서는 사용할 수 없다.


CC 디코더 필터

CC VBI 디코더는 커넬 모드 스트림 클래스 필터이다. GraphEdit 에서는 "WDM Streaming VBI CODEC" 카테고리에 있다. 캡춰 된 VBI 라인을 처리해, 디코드된 자막 방송 데이터를 Line 21 디코더 나 적절한 어플리케이션에 출력한다.

이 필터에는 2 개의 입력 핀 VBI 와 HWCC 가 있다. VBI 핀은 로 VBI 데이터용으로 사용되어 HWCC 핀은 VBI 디코드가 캡춰 필터에 의해 하드웨어로 처리될 때 사용된다. 데이터를 HWCC 핀으로 받았을 때, CC 디코더는 "파스스르모드" 로 조작해, 데이터 디렉토리를 아무것도 처리하지 않고 Line 21 디코더에 보낸다.

CC 디코더에는 8 개까지의 출력 핀이 있어, 각각이 자신의 라인과 서브 스트림을 선택할 수가 있다. 최초의 출력 핀은 Line-21 디코더에 접속된다.

이것은 커넬 모드 필터이므로, 어플리케이션은 그것을 직접 co-create 할 수 없지만, 「디바이스와 필터의 열거」로 설명되고 있도록(듯이),시스템 디바이스 열거자 를 사용해 인스턴스화하지 않으면 안 된다.


칼라 스페이스 변환 필터

변환 필터는, 1 개의 RGB 색타입을 다른 RGB 타입으로 변환한다 (예를 들어 24 비트 RGB 색과 8 비트 RGB 색의 변환). 일반적으로 이러한 변환은 비데오데콘프렛사내에서 보다 효율적으로 처리할 수 있으므로, 칼라 스페이스 변환은 주로 스트림 소스가 비압축 RGB 프레임으로부터 구성되는 경우에 사용된다.

필터 인터페이스 | IBaseFilter
입력 핀 미디어 타입 MEDIATYPE_Video, FORMAT_VideoInfo

다음의 서브 타입이 유효
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB32
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 MEDIATYPE_Video, FORMAT_VideoInfo

다음의 서브 타입이 유효
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB32
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_Colour
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory


디폴트 DirectSound 디바이스 필터

이 필터는 범용의 오디오 렌더링 필터로,파일 소스 (Async),URL 파일 소스,MPEG-1 스트림 스플리터,AVI 스플리터,WAVE 퍼서, 또는 그 외의 오디오 변환 필터가 WAV 오디오를 포함하고 있는 경우에, 그 출력에 접속할 수가 있다. 기본적인 사운드 렌더링 기능에 가세해 이 필터는 Microsoft® DirectSound® API 호출을 처리할 수가 있다. 즉,IAMDirectSound 메소드를 사용해 사운드의 재생을 처리하는 윈도우를 설정 및 취득한다. DirectSound 오디오 렌더러는, Microsoft® DirectShow® 의 디폴트의 오디오 렌더링 필터이다.

이 필터는 오디오 드라이버에 관련되지 않고, 100 Hz 에서 100,000 Hz 까지 같은 레이트를 지원 한다.

필터 인터페이스 | IAMDirectSound ,IAMResourceControl ,IBaseFilter ,IBasicAudio ,IDirectSound3DBuffer,IDirectSound3dListener,IMediaPosition ,IMediaSeeking ,IQualityControl ,IReferenceClock
입력 핀 미디어 타입 | MEDIATYPE_Audio, MEDIASUBTYPE_NULL, FORMAT_WaveFormatEx
입력 핀인타페이스 | IMemInputPin ,IPin ,IPinConnection ,IQualityControl
출력 핀 미디어 타입 | 이용할 수 없다.
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_DSoundRender
프로퍼티 페이지 CLSID | CLSID_AudioProperties, CLSID_AudioRendererAdvancedProperties
실행 모듈 | quartz.dll
메리트 |
카테고리 | CLSID_AudioRendererCategory


DMO 래퍼 필터

DMO 래퍼 필터는, Microsoft® DirectShow® 어플리케이션이 필터 그래프내에서 Microsoft® DirectX® Media Object (DMO)를 사용할 수 있도록(듯이) 한다. 이 필터는 DMO 를 랩 해, DMO 와의 데이터의 수수 등, DMO 의 사용에 관한 모든 처리를 취급한다. 또, 이 필터는 DMO 를 집성 하므로, 어플리케이션은 DMO 가 공개하는 모든 COM 인터페이스의 필터에 문의할 수가 있다.

이 필터의 사용 방법에 대해서는, 「DirectShow 어플리케이션에서의 DMO 의 사용」을 참조할것.

필터 인터페이스 | IBaseFilter ,IDMOWrapperFilter ,IPersistStream
입력 핀 미디어 타입 | 「주의」를 참조
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | 「주의」를 참조
출력 핀인타페이스 | IAMStreamConfig , IAMVideoCompression , IPin ,IQualityControl
필터 CLSID | CLSID_DMOWrapperFilter
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음
실행 모듈 | Qasf.dll
메리트 | 「주의」를 참조
카테고리 | 「주의」를 참조

주의

DMO 의 각 입력 스트림에 대해서, 이 필터는 대응하는 입력 핀을 생성 한다. 각 출력 스트림에 대해서는, 대응하는 출력 핀을 생성 한다. 미디어 타입은 DMO 에 의존한다.

DMO 가 비디오 엔코더 또는 오디오 엔코더인 경우, 필터의 출력 핀은 IAMStreamConfig 인터페이스를 공개한다. DMO 가 비디오 엔코더인 경우, 출력 핀도 IAMVideoCompression 인터페이스를 공개한다. 핀은 인터페이스에 대해 DMO 에 조회한다. DMO 가 인터페이스를 지원 하고 있는 경우, 핀은 DMO 에 위임한다. 지원 하고 있지 않는 경우, 핀은 독자적인 이행을 제공한다.

DirectShow 은, 디폴트의 메리트값 MERIT_NORMAL + 0x800 를 모든 DMO 에 할당한다. 이 값은, MERIT_NORMAL 와 MERIT_PREFERRED 의 사이이다. 보통, 디코더 필터의 메리트값은 MERIT_NORMAL 이다. 따라서, 보통, 필터 그래프 매니저는 디코더 필터 대신에 DMO 디코더를 선택한다. 디폴트의 메리트값을 오버라이드(override) 하려면 , HKEY_CLASSES_ROOT\CLSID 내의 DMO 의 레지스트리 키에, 레지스트리 엔트리를 추가한다. 메리트를 지정하는 값을 가지는 Merit 라는 이름의 DWORD 값을 인클루드 한다.

DMO 래퍼 필터는, 단독으로는 어느 카테고리에도 나타나지 않는다. DMO 를 랩 하면, DMO 의 카테고리에 대응한 DirectShow 카테고리로, DMO 명의 부하에게 나타난다. 상세한 것에 대하여는, 「DirectShow 어플리케이션에서의 DMO 의 사용」을 참조할것.


DV Muxer 필터

이 필터는, 디지털 비디오 (DV) encode의 비디오 스트림과 1 개 혹은 2 개의 오디오 스트림을 조합해, 인터리브 DV 스트림을 생성한다. 스트림을 AVI 파일에 기입하려면 , 이 필터를 AVI Mux 필터에 접속한다. 다음에 AVI Mux 를파일 라이터 필터에 접속한다. 상세한 것에 대하여는, 「DirectShow 에서의 디지털 비디오」를 참조할것.

필터 인터페이스 | IBaseFilter ,IMediaSeeking
입력 핀 미디어 타입 | 비디오 : MEDIATYPE_Video, MEDIASUBTYPE_dvsd, FORMAT_VideoInfo 오디오 : MEDIATYPE_Audio, MEDIASUBTYPE_PCM, FORMAT_WaveFormatEx
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Interleaved, MEDIASUBTYPE_dvsd, FORMAT_DvInfo
출력 핀인타페이스 | IPin ,IQualityControl
필터 CLSID | CLSID_DVMux
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | qdv.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory

주의

DX Muxer 는 2 개의 오디오 입력 핀을 생성 할 수 있다. 이하의 겉(표)에 나타나는 오디오 포맷이 지원을 지원 한다 :

오디오 핀 1 | 오디오 핀 2 | 출력 포맷
샘플 레이트 (kHz) | 비트/샘플 | 채널 | 샘플 레이트 | 비트/샘플 | 채널
32 | 16 | 단청의 | 접속하지 않는 | SD 2 채널
32 | 16 | 스테레오 | 접속하지 않는 | SD 4 채널
44.1 or 48 | 16 | 스테레오 or 단청의 | 접속하지 않는 | SD 2 채널
접속하지 않는 | 32 | 16 | 스테레오 or 단청의 | 허가되지 않는다
접속하지 않는 | 44.1 or 48 | 16 | 단청의 | 허가되지 않는다
접속하지 않는 | 44.1 or 48 | 16 | 스테레오 | SD 2 채널
32 | 16 | 단청의 | 32 | 16 | 단청의 | SD 2 채널
32 | 16 | 스테레오 or 단청의* | 32 | 16 | 스테레오 or 단청의* | SD 4 채널
44.1 | 16 | 단청의 | 44.1 | 16 | 단청의 | SD 2 채널
48 | 16 | 단청의 | 48 | 16 | 단청의 | SD 2 채널
* 적어도 1 개의 핀은 스테레오.

이 표에서는, 오디오 핀 1 은 오디오 소스에 접속되고 있는 최초의 입력 핀으로서 정의되어 오디오 핀 2 는 오디오 소스에 접속되고 있는 2 개째의 입력 핀으로서 정의되고 있다. 오디오 핀을 한 번 접속 하면, 양쪽 모두의 오디오 핀이 접속 해제될 때까지, 이 넘버링 스킴은 유효인 채 남는다. 예를 들어, 오디오 핀을 양쪽 모두 접속해, 다음에 오디오 핀 1 만을 접속 해제해도, 남은 핀은 그대로 핀 2 로서 해석된다.

핀 1 에 제공되는 오디오는 DV 프레임의 제 1 오디오 블록 (CH1)에 녹음되어 핀 2 에 제공되는 오디오는 제 2 오디오 블록 (CH2)에 녹음된다. 예외 : 필터가 44.1 kHz 혹은 48 kHz 로 스테레오 입력을 1 개만 가지고 있다면, 왼쪽의 오디오 채널이 제 1 오디오 트럭에, 오른쪽의 오디오 채널이 제 2 오디오 블록에 녹음된다.

SD 4 채널 출력에 대해 : 입력이 스테레오라면, 왼쪽 트럭이 CHa 나 CHc 에 녹음되어 오른쪽 트럭이 CHb 나 CHd 에 녹음된다. 입력이 단청의라면, 오디오는 CHa 나 CHc 에 녹음되어 CHb 와 CHd 는 하늘이다.

오디오 핀 1 을 접속과 접속 해제하는 일에 의해, 허가되어 있지 않은 포맷에 액세스 하는 경우가 있다. 이 경우, 필터의 IMediaFilter::Pause 는 VFW_E_NOT_CONNECTED 를 돌려준다. 이 제한에 의해 최초의 오디오 블록에 오디오가 없는 것 같은 상태를 막을 수가 있지만, 제 2 블록에는 오디오가 있다. 제 1 블록에 오디오가 있는 경우에게만 제 2 블록은 오디오를 가져야 하는 것이다.

DV Muxer 는 다른 샘플링 레이트의 오디오 입력을 허가하지 않는다. 그러나 IGraphBuilder::Connect 와 같은 그래프 빌딩 메소드는 보통 ACM 래퍼 필터를 추가하는, 이것은 제 2 오디오 스트림을 변환해 제 1 스트림의 샘플링 레이트에 맞춘다.

오디오 입력이 48 kHz 나 32 kHz 라면, 오디오 출력은 락 된다. (44.1-kHz 오디오를 잠글 수 없다. )

오디오 핀이 접속되어 있지 않으면 출력에는 입력 DV 프레임으로부터 오디오 데이터가 들어간다. 이것은 무음 또는 유효한 오디오 데이터이다.


DV 스플리터 필터

이 필터는, 인터리브 된 디지털 비디오 (DV) 스트림을 그 컴퍼넌트 비디오와 오디오 스트림에 분할한다.

필터 인터페이스 | IBaseFilter ,IDVSplitter
입력 핀 미디어 타입 | MEDIATYPE_Interleaved, MEDIASUBTYPE_dvsd, FORMAT_DvInfo
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | 비디오 : MEDIATYPE_Video, MEDIASUBTYPE_NULL, FORMAT_DvInfo 오디오 : MEDIATYPE_Audio, MEDIASUBTYPE_PCM, FORMAT_WaveFormatEx
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_DVSplitter
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | qdv.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory

주의

한 번에 1 개의 출력 핀만이 IMediaPosition 및 IMediaSeeking 인터페이스를 공개한다.

DV 스플리터 필터는, 오디오 스트림의 동적인 포맷의 변경을 받아들일 수가 있다. 다만 AVI Mux 필터가 다운 스트림의 경우는, 포맷의 변경을 거부한다. 이 경우, DV 스플리터는 오디오 스트림의 생성을 중지한다.

주 : 이 제한은, 타입 2 의 파일 캡춰에게만 영향을 준다. 프리뷰에 대해서는, AVI Mux 필터 다운 스트림은 없다. 타입 1 의 파일 캡춰의 경우, 인터리브 된 스트림은 원래 분할되지 않는다. DV 소스가 라이브 카메라의 경우, 보통은 오디오 포맷을 변경할 이유는 없다. 다만, 이종의 소스가 함께 편집된 VTR 테이프로부터 전송 하는 경우는, 그러한 상황도 있을 수 있다.


DV 비디오 디코더 필터

이 필터는, 디지털 비디오 (DV) 스트림을 비압축 비디오에 디코드한다. 이 필터는, 디코드 해상도를 설정하기 위한 커스텀 인터페이스 IIPDVDec 를 제공한다.

필터 인터페이스 | IBaseFilter ,IIPDVDec , IPersistStream,ISpecifyPropertyPages
입력 핀 미디어 타입
  • MEDIATYPE_Video
  • MEDIASUBTYPE_dvsd 또는 MEDIASUBTYPE_dvc
  • FORMAT_VideoInfo 또는 FORMAT_DvInfo
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 MEDIATYPE_Video, FORMAT_VideoInfo

다음의 서브 타입이 유효
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_UYVY
  • MEDIASUBTYPE_YUY2
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_DVVideoCodec
프로퍼티 페이지 CLSID | CLSID_DVDecPropertiesPage
실행 모듈 | qdv.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory


DV 비디오 엔코더 필터

이 필터는, 비압축 비디오 스트림을 디지털 비디오 (DV)에 encode 한다. 이 필터는, encode 해상도 및 포맷을 설정하기 위한 커스텀 인터페이스 IDVEnc 를 제공한다.

필터 인터페이스 | IAMVideoCompression ,IBaseFilter ,IDVEnc ,IPersistStream,ISpecifyPropertyPages
입력 핀 미디어 타입 MEDIATYPE_Video, FORMAT_VideoInfo

다음의 서브 타입이 유효
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB555
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_dvsd, FORMAT_VideoInfo
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_DVVideoEnc
프로퍼티 페이지 CLSID | CLSID_DVEncPropertiesPage
실행 모듈 | qdv.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_VideoCompressorCategory

주의

16 비트 비디오 (MEDIASUBTYPE_RGB555 또는 MEDIASUBTYPE_RGB565)의 경우, NTSC 의 입력은 720 x 480 픽셀, PAL 의 입력은 720 x 576 픽셀이 아니면 안된다. 24 비트 비디오의 경우, 입력 사이즈에 관한 제약은 없다.

출력은, NTSC 의 경우는 720 x 480, PAL 의 경우는 720 x 576 에 반드시 된다. 24 비트 비디오는 이 치수에 맞도록(듯이) 스케일링 된다.


DVD 네비게이터 필터

DVD 네비게이터 필터는, DVD-Video 재생 필터 그래프의 소스 필터이다. 이 필터는, DVD-Video 볼륨내의 필요한 파일을 모두 열어, 리니어 DVD-Video . vob 파일내를 안내해 결과의 MPEG-2 프로그램 스트림을 해석해, 스트림을 3 개 (비디오, 오디오, 서브 픽쳐)의 출력 핀에 분할한다.

또, DVD 네비게이터 필터는, DVD 재생 어플리케이션이 DVD-Video 의 재생을 제어할 수 있도록(듯이) 하는 IDVDControl2 인터페이스 및 IDVDInfo2 인터페이스를 이행 한다. 새로운 인터페이스의 채용에 의해, 종래의 IDVDControl 및 IDVDInfo 인터페이스는 사용되지 않는다. 새로운 인터페이스는 완전하게 새로운 이행으로, 종래의 인터페이스를 계승하는 것은 아니다.

필터 인터페이스 | IBaseFilter ,IDVDControl ,IDVDControl2 ,IDVDCmd ,IDVDInfo ,IDVDInfo2 ,IDVDState IFileSourceFilter ,ISpecifyPropertyPages
입력 핀 미디어 타입 | MEDIATYPE_Stream; MEDIASUBTYPE_MPEG2_PROGRAM
입력 핀인타페이스 | 이용할 수 없다.
출력 핀 미디어 타입
  • MEDIATYPE_Audio, MEDIASUBTYPE_MPEG1AudioPayload
  • MEDIATYPE_Video, MEDIASUBTYPE_MPEG2_VIDEO
출력 핀인타페이스 | IPin ,IQualityControl
필터 CLSID | CLSID_DVDNavigator
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | qdvd.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_LegacyAmFilterCategory


파일 소스 (Async) 필터

비동기 파일 소스 필터는, 다양한 다른 데이터 포맷의 로컬 파일을 열어 읽어내, 데이터를 퍼서 필터에 건네준다. Web 로부터 데이터를 다운로드하는 경우는,URL 파일 소스 필터를 사용한다.

필터 인터페이스 | IBaseFilter ,IFileSourceFilter
입력 핀 미디어 타입 | 이용할 수 없다.
입력 핀인타페이스 | 이용할 수 없다.
출력 핀 미디어 타입 | MEDIATYPE_Stream. 서브 타입은 미디어 포맷에 의존한다 (필터가 포맷을 인식하지 않는 경우는 MEDIASUBTYPE_NULL).
출력 핀인타페이스 | IAsyncReader
필터 CLSID | CLSID_AsyncReader
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory


파일 소스 (URL) 필터

URL 파일 소스 필터는 범용의 비동기 소스 필터로, Uniform Resource Locator (URL)에 의해 식별 가능한 원시 파일 가운데, 미디어 메이저 타입이 스트림인 모든 파일에 대해서 사용할 수 있다. 이러한 파일에는, AVI, MOV, MPEG, 및 WAV 파일이 있다. 이 필터를 사용하려면 , 다운 스트림 필터가,MPEG-1 스트림 스플리터,AVI 스플리터, 또는 QuickTime 무비 퍼서등의 퍼서인 것이 필요하다.

필터 인터페이스 | IAMOpenProgress , IBaseFilter , IFileSourceFilter
입력 핀 미디어 타입 | 이용할 수 없다.
입력 핀인타페이스 | 이용할 수 없다.
출력 핀 미디어 타입 | MEDIATYPE_Stream. 서브 타입은 미디어 포맷에 의존한다 (필터가 포맷을 인식하지 않는 경우는 MEDIASUBTYPE_NULL).
출력 핀인타페이스 | IAsyncReader ,IPin
필터 CLSID | CLSID_URLReader
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory

주의

이 필터는, Microsoft® Internet Explorer 의 URLMon 를 사용해, code page를 지원 한다.


파일 라이터 필터

파일 라이터 필터를 사용 하면, 포맷에 관계없이 디스크에 파일을 기입할 수가 있다. 이 필터는 입력 핀으로 받은 것을 단지 디스크에 기입할 뿐(만큼)이므로, 파일을 정상적으로 포맷 할 수 있는 멀티플렉서의 업 스트림에 접속할 필요가 있다. 파일 라이터를 사용해 새로운 출력 파일을 생성 하거나 기존의 파일을 지정할 수가 있다. 파일이 이미 존재하고 있는 경우, 그 파일은 새로운 데이터로 완전하게 오버라이드(override) 된다.

파일 라이터에게 건네지는 샘플의 타임 스탬프는, 파일의 바이트 오프셋(offset)이다. 입력 핀은 IStream 인터페이스를 공개해, 인터페이스의 서브 세트를 지원 한다. 이것에 의해, 그래프가 중지되었을 때에 업 스트림 필터가 데이터를 기입하는 것이 가능하게 된다.

주 : Microsoft® Windows Media™ Software Development Kit 를 사용해 ASF 파일을 기술하는 경우는, ASF 라이터 필터를 사용한다. ASF 라이터는, Microsoft DirectShow 에 대해 Microsoft Windows Media Audio (WMA) 파일을 생성 하는 유일한 방법을 제공한다.

필터 인터페이스 | IAMFilterMiscFlags , IBaseFilter , IFileSinkFilter , IFileSinkFilter2 , IPersistStream
입력 핀 미디어 타입 | MEDIATYPE_Stream, MEDIASUBTYPE_NULL
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl ,IStream
출력 핀 미디어 타입 | 이용할 수 없다.
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_FileWriter
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | qcap.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_LegacyAmFilterCategory


풀 스크린 렌더링 필터

풀 스크린 렌더링 필터는, Microsoft® DirectDraw® 를 사용해, 320x240 비디오를 1024x768 에 즉석에서 확장할 수 없는 낡은 그래픽 카드상에서 풀 스크린 비디오를 렌더링 한다. 이 하드웨어 제한으로 대처하기 위해서, 풀 스크린 렌더러는, 단지 그래픽스 디스플레이 카드를 320x240 모드로 전환한다. 최근의 비디오 카드는 즉석에서 표시를 확장할 수 있으므로,비디오 렌더러 필터를 윈도우 모드와 풀 스크린 모드의 어디라도 사용할 수 있다. 필터 그래프 매니저는 풀 스크린 렌더러를 그래프내에 자동적으로 호출한다. 비디오 카드가 새로울 정도(수록), 이 필터를 사용할 기회가 줄어든다. 이 필터를 수작업으로 그래프에 추가해서는 안 된다. 비디오 렌더러를 선택하는 것은 필터 그래프 매니저의 역할이다.

필터 인터페이스 | IBaseFilter ,IFullScreenVideo ,IFullScreenVideoEx,IMediaPosition ,IMediaSeeking ,IQualityControl ,IQualProp
입력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_Null
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | 이용할 수 없다.
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_ModexRenderer
프로퍼티 페이지 CLSID | CLSID_ModexProperties
실행 모듈 | quartz.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory


인피닛트핀티피르타

이 필터는, 입력 핀에 배송된 샘플을 가변수의 출력 핀에 보낸다. 이 필터의 인스턴스가 생성 되면(자), 인스턴스는 1 개의 출력 핀을 가진다. 출력 핀을 접속할 때 마다, 필터는 다른 출력 핀을 생성 한다. 모든 출력 핀은 입력 핀과 같은 미디어 타입을 공유한다.

필터 인터페이스 | IBaseFilter
입력 핀 미디어 타입 | 임의의 미디어 타입.
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | 임의의 미디어 타입. 입력 핀의 미디어 타입과 같다.
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_InfTee
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | qcap.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_LegacyAmFilterCategory


내부 스크립 코맨드 렌더링 필터

스크립 코맨드를 받아, 어플리케이션에 디스팟치 한다.

이 필터는, 다음의 2 개의 포맷의 어느쪽이든으로 스크립트를 받는다.

  • MEDIATYPE_Text : 각 미디어 샘플에 ANSI 텍스트 캐릭터 라인이 포함된다.
  • MEDIATYPE_ScriptCommand : 각 미디어 샘플에 NULL 종단의 2 개의 Unicode™ 캐릭터 라인이 연결되어 포함된다. 최초의 캐릭터 라인은 커멘드 타입을 나타내, 2 번째의 캐릭터 라인은 스크립 코맨드를 나타낸다.

필터가 샘플을 받으면(자),EC_OLE_EVENT 이벤트 통지를 보낸다. 최초의 이벤트의 파라미터는 커멘드 타입을 가지는 BSTR 인지, 또는 포맷이 MEDIATYPE_Text 인 경우는 Text 이다. 2 번째의 이벤트 파라미터는, 스크립 코맨드를 가지는 BSTR 이다. 어플리케이션은, 이벤트를 취득해, 스크립 코맨드에 응답할 수 있다.

이 필터의 사용법의 예에 대해서는, 「SAMI (CC) 퍼서」를 참조할것.

필터 인터페이스 | IBaseFilter ,IMediaPosition ,IMediaSeeking
입력 핀 미디어 타입
  • MEDIATYPE_ScriptCommand, MEDIASUBTYPE_NULL
  • MEDIATYPE_Text, MEDIASUBTYPE_NULL
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | 이용할 수 없다
출력 핀인타페이스 | 이용할 수 없다
필터 CLSID | {48025243-2D39-11CE-875D-00608CB78066}
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음
실행 모듈 | Quartz.dll
메리트 | MERIT_PREFERRED + 1
카테고리 | CLSID_LegacyAmFilterCategory


Line 21 디코더 필터

Line 21 디코더 필터는, Line 21 데이터를 표준 바이트 페어 포맷, 또는 DVD 의 경우는, 픽쳐 그룹 (GOP) 전체의 패킷으로서 받아들인다. DVD 비디오 스트림내의 모든 GOP 에 관해서, 해당 GOP 의 헤더 정보와 Line 21 데이터를 가지는 유저 데이터 패킷이 존재 가능하다.

입력 핀에서는, 필터는 임의의 Line 21 데이터 프로바이더 (예를 들어, Line 21 데이터 출력 핀을 가지는 DVD 비디오 디코더), 또는 TV 튜너/비디오 캡쳐 카드로부터 들어 오는 VBI 스트림으로부터 Line 21 데이터를 제공하는 CC 디코더 WDM 필터 (KsProxy 경유)에 접속된다.

이 필터는, Line 21 데이터를 비트 맵에 디코드해, 다운 스트림 필터, 즉오버레이 믹서의 세칸다리핀 또는비디오 렌더러에 건네준다 (오버레이 믹서의 프라이머리 핀은 반드시 메인 비디오 스트림을 받는다).

다음의 그림에, Line 21 디코더를 사용한 일반적인 DVD 필터 그래프를 나타낸다.

Line 21 디코더를 사용한 일반적인 DVD 필터 그래프

필터 인터페이스 | IAMLine21Decoder
입력 핀의 미디어 타입 메이저 타입: MEDIATYPE_AUXLine21Data
서브 타입:
  • MEDIASUBTYPE_Line21_BytePair [표준 Line 21]
  • MEDIASUBTYPE_Line21_GOPPacket [DVD Line 21]
포맷 타입 : FORMAT_VideoInfo 또는 이루어
입력 핀인타페이스 | 없음.
출력 핀 미디어 타입 메이저 타입 : MEDIATYPE_Video
서브 타입 :
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB32
포맷 타입 : FORMAT_VideoInfo
출력 핀인타페이스 | 없음
필터 CLSID | CLSID_Line21Decoder
프로퍼티 페이지 CLSID | 없음
실행 모듈 | qdvd.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory


MIDI 퍼서 필터

MIDI 퍼서 필터는,. MID 파일 및 . RMI 파일의 MIDI 데이터를 읽어낸다. 이 필터는,비동기 파일 소스 필터 또는URL 파일 소스 필터로부터의 스트림을 받아, MIDI 샘플을 재생하기 위해서 MIDI 렌더러에 출력한다.

필터 인터페이스 | IAMMediaContent ,IBaseFilter
입력 핀 미디어 타입 | MEDIATYPE_Stream, MEDIASUBTYPE_Midi
입력 핀인타페이스 | IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Midi, MEDIASUBTYPE_NULL
출력 핀인타페이스 | IMediaSeeking ,IQualityControl ,IPin
필터 CLSID | CLSID_MIDIParser {D51BD5A2-7548-11cf-A520-0080C77EF58A}
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory

주의

상세한 것에 대하여는, 「MIDI 렌더러」를 참조할것.


MIDI 렌더링 필터

MIDI 렌더링 필터는,MIDI 퍼서 필터로부터의 MIDI 데이터를 렌더링 한다.

필터 인터페이스 | IAMDirectSound ,IAMResourceControl ,IBaseFilter ,IBasicAudio ,IMediaPosition ,IMediaSeeking ,IQualityControl ,IReferenceClock
입력 핀 미디어 타입 | MEDIATYPE_Midi, MEDIASUBTYPE_NULL
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | 이용할 수 없다.
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_AVIMIDIRender
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_PREFERRED
카테고리 | CLSID_MidiRendererCategory

주의

포맷 타입의 GUID 는 NULL 이지만, 포맷 블록에는 다음의 구조몸이 들어온다 :

typedef struct _MIDIFORMAT {
    DWORD       dwDivision;
    DWORD       dwReserved[7];
} MIDIFORMAT, FAR * LPMIDIFORMAT;

dwDivision 멤버 변수는 파일의 시간 분할을 지정한다. 시간 분할은 표준 MIDI 파일 (SMF)의 헤더의 MThd 체크로 주어지고 있다. MIDI 렌더러는 midiStreamProperty 함수를 호출하는 것에 의해, 이 프로퍼티를 MIDI 데이터 스트림으로 설정한다.

MIDI 퍼서 필터로부터의 샘플에는 1 초의 MIDI 데이터가 들어가 있다. MIDI 렌더러는 midiStreamOut 함수를 사용해 MIDI 데이터를 렌더링 한다. 각 샘플은 살의 동기 포인트 인 : 그 버퍼의 초에는, 그 버퍼를 렌더링하기 위한 올바른 상태를 설정하는데 필요한 모든 커멘드가 포함되어 있다.


MJPEG 압력 필터

이 필터는, 모션 JPEG 압축을 사용해 비압축 비디오 스트림을 압축한다.

필터 인터페이스 | IBaseFilter ,IPersistStream
입력 핀 미디어 타입 | MEDIATYPE_VIDEO, MEDIASUBTYPE_NULL
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_MJPG
출력 핀인타페이스 | IAMStreamConfig ,IAMVideoCompression ,IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_MJPGEnc
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_VideoCompressorCategory

주의

이 필터는, FOURCC 코드 'MJPG' 에 대응하는 미디어 서브 타입 MEDIASUBTYPE_MJPG 를 사용해 encode를 실시한다.


MJPEG 데콘프렛사피르타

이 필터는, 모션 JPEG 로부터 비압축 비디오에 비디오 스트림을 디코드한다. 일부의 디지털 비디오 카메라는, 모션 JPEG 비디오 스트림을 생성한다.

필터 인터페이스 | IBaseFilter
입력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_MJPG
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_VIDEO, MEDIASUBTYPE_NULL
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_MjpegDec
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory

주의

이 필터는, FOURCC 코드 'MJPG' 를 사용하는 모션 JPEG 비디오와의 호환성을 가진다. 이외의 모션 JPEG 는 디코드할 수 없다. 그러한 모션 JPEG 에 대해서는, 써드파티의 디코더 필터를 사용할 필요가 있다.


MPEG-1 오디오 디코더 필터

MPEG-1 Layer I 및 Layer II 오디오를 PCM 에 디코드한다.

필터 인터페이스 | IBaseFilter ,ISpecifyPropertyPages
입력 핀 미디어 타입 MEDIATYPE_Audio, FORMAT_WaveFormatEx

다음의 서브 타입이 유효
  • MEDIASUBTYPE_MPEG1Packet
  • MEDIASUBTYPE_MPEG1Payload
  • MEDIASUBTYPE_MPEG1AudioPayload
  • GUID_NULL
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Audio, MEDIASUBTYPE_PCM
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_CMpegAudioCodec
프로퍼티 페이지 CLSID | CLSID_MpegAudioDecoderPropertyPage
실행 모듈 | quartz.dll
메리트 | 0x03680001
카테고리 | CLSID_LegacyAmFilterCategory


MPEG-1 스트림 스플리터 필터

이 필터는, MPEG-1 시스템 스트림을 그 컴퍼넌트 오디오 및 비디오 스트림에 분할한다.

필터 인터페이스 | IAMMediaContent ,IAMStreamSelect ,IBaseFilter
입력 핀 미디어 타입 MEDIATYPE_Stream

다음의 서브 타입이 유효
  • MEDIASUBTYPE_MPEG1System
  • MEDIASUBTYPE_MPEG1VideoCD
  • MEDIASUBTYPE_Audio
  • MEDIASUBTYPE_Video
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입
  • MEDIATYPE_Video, MEDIASUBTYPE_MPEG1Packet
  • MEDIATYPE_Video, MEDIASUBTYPE_MPEG1Payload
  • MEDIATYPE_Audio, MEDIASUBTYPE_MPEG1Packet
  • MEDIATYPE_Audio, MEDIASUBTYPE_MPEG1Payload
출력 핀인타페이스 | IPin ,IMediaSeeking
필터 CLSID | CLSID_MPEG1Splitter
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory

주의

MPEG-1 컨텐츠는 인덱스를 붙일 수 있지 않기 때문에, 시크 처리가 매우 대략적으로 된다. 보통은, 고정 bit rate의 MPEG-1 시스템 스트림 (보통은 비디오 CD 의 하드웨어로 생성된다)에 사용한다. IAMMediaContent 는 MP3 ID3 컨텐츠에 대해서 공개된다.


MPEG-1 비디오 디코더 필터

MPEG-1 비디오를 디코드한다.

필터 인터페이스 | IBaseFilter ,IMpegVideoDecoder,ISpecifyPropertyPages
입력 핀 미디어 타입 MEDIATYPE_Video, FORMAT_MPEGVideo

다음의 서브 타입이 유효
  • MEDIASUBTYPE_MPEG1Packet
  • MEDIASUBTYPE_MPEG1Payload
입력 핀인타페이스 | IPin ,IMemInputPin
출력 핀 미디어 타입 MEDIATYPE_Video, FORMAT_VideoInfo or FORMAT_VideoInfo2

다음의 서브 타입이 유효
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB32
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_UYVY
  • MEDIASUBTYPE_Y41P
  • MEDIASUBTYPE_YUY2
  • MEDIASUBTYPE_YV12
출력 핀인타페이스 | IPin ,IQualityControl
필터 CLSID | CLSID_CMPEGVideoCodec
프로퍼티 페이지 CLSID | CLSID_MpegVideoDecodePropertyPage
실행 모듈 | quartz.dll
메리트 | 0x40000001
카테고리 | CLSID_LegacyAmFilterCategory

주의

이 필터는, DirectDraw 표면에의 디코드도 가능하다. 이 필터는, 머신이 MMX 를 지원 하고 있으면 MMX 를 사용한다.


MPEG-2 디멀티플렉서

MPEG-2 디멀티플렉서 (Demux)는 푸쉬 모드로 출력되는 MPEG-2 트랜스폴트와 프로그램 스트림을 조작한다. (파일 재생 시나리오와 같은, 프르모드로 출력되는 MPEG-2 프로그램 스트림을에 대해서는,MPEG-2 스플리터 필터를 사용한다. ) 트랜스폴트 스트림상에서 조작 하면 와, Demux 는 트란스포트스림모드 에 있다고 말해진다. 프로그램 스트림상에서 조작 하면 와, Demux 는 프로그램 스트림 모드 에 있다고 말해진다. 트랜스폴트 스트림 모드에서는, 데마르치프레키싱은 1 개 이상의 패킷 ID (PID)의 출력 핀에의 매핑을 베이스로 하고 있다. 프로그램 스트림 모드에서는, 이 매핑은 1 개의 스트림 ID 와 1 개의 출력 핀간이 된다. 어느 PID 혹은 스트림 ID 가 있는 출력 핀에 맵 되지 않으면 Demux 는 파기하는 것만으로 있다.

Demux 는 파스스르모드 에서도 조작할 수 있다. 예를 들어, 어플리케이션은 모든 PID 를 1 개의 출력 핀에 매핑 해, PID 패킷의 스트림을 생성 할 수 있는, 그것은 파일에도 기입할 수 있고, 재차 브로드캐스트에도 할 수 있고, 다른 방법으로 처리할 수도 있다. 패킷의 재multiplexing는 파스스르모드에서는 실행할 수 없는, 출력 스트림은 솔직한 MPEG-2 트랜스폴트 스트림은 아니다. 에러가 있는 패킷은 필터로 출력할 수 없다.

다음의 그림은 Demux 가 트랜스폴트 스트림 모드 때의 가능한 데이터 플로우를 나타낸다.

트랜스폴트 스트림 모드에서의 Demux

필터를 구성한다

Demux 가 최초로 인스턴스화 되고 필터 그래프에 추가되면(자), 입력 핀을 1 개 소유 출력 핀은 가지지 않는다. 디지털 TV 방송을 렌더링 해, Microsoft® Broadcast Driver Architecture (BDA)를 베이스로 하고 있는 필터 그래프에서는,BDA 네트워크 프로바이더 필터는 Demux 위에의 출력 핀을 생성 해, 핀에 PID 를 매핑 할 책임이 있다. 다른 필터 그래프에서는, 핀이 생성 되고 스트림 ID (프로그램 스트림 모드)나 PID (트랜스폴트 스트림 모드)를 각 핀에 매핑 하면 와, 핀의 미디어 타입을 설정하는 것에 의해 출력 핀의 생성과 구성을 하는 것은 어플리케이션의 책임이다.

Demux 는, 어느 타입의 스트림을 필터가 기대하고 있는지를 나타내는 트리거 이벤트가 발생한 다음에, 자기 자신을 내부적으로 각 트랜스폴트 스트림 혹은 프로그램 스트림에 대해서 구성한다. 보통 트리거 이벤트는 최초로 출력 핀이 구성되었을 때에 일어난다. 예를 들어, 프로그램 스트림 모드에서는, 어플리케이션은 필터의 IMpeg2Demultiplexer::CreateOutputPin 메소드를 사용해 새로운 출력 핀을 생성 한다. 이 메소드는 IPin 인터페이스 포인터를 생성 된 핀에 돌려준다. 어플리케이션은 다음에 QueryInterface 를 호출할 때에, 이 포인터를 사용해 IMPEG2StreamIDMap 인터페이스를 취득한다. 이 때에 Demux 는 프로그램 스트림 모드에 자기 자신을 구성한다, 왜냐하면 IMPEG2StreamIDMap 는 프로그램 스트림을 지정하고 있기 때문이다. 어플리케이션이 최초의 출력 핀으로QueryInterface 를 호출해,IMPEG2PIDMap 인터페이스를 요구했을 때, 같은 프로세스가 트랜스폴트 모드로 일어난다. 이제(벌써) 1 개(살)별의 트리거 이벤트는 Demux 의 입력 핀이 접속되었을 때인, 접속 미디어 타입은 입력 스트림이 프로그램 스트림이나 트랜스폴트 스트림인지를 Dexmu 에 나타낸다.

Demux 는 Run 상태가 될 수 있기 전에 구성되지 않으면 안 된다. Demux 가 있는 스트림 타입으로 자기 자신을 1 번 구성 하면별의 스트림 타입으로 복구성 할 수 없다. Demux 를 프로그램 스트림 모드와 트랜스폴트 스트림 모드로 바꾸려면 , 새롭게 필터를 인스턴스화해 시작해 더 없으면 안 된다.

프로그램 스트림 모드로 핀을 구성한다

전의 섹션으로 설명한 것처럼, 출력 핀을 생성 한 다음에, 어플리케이션은 IMPEG2StreamIDMap 인터페이스에 대해서 그 핀을 쿼리 한다. 어플리케이션은 다음에 IMPEG2StreamIDMap::MapStreamId 메소드를 호출해, 그 핀과 지정한 기본 스트림을 조합해 서브 스트림 필터 링이 요구되고 있는지 어떤지를 알린다. MPEG-2 (트랜스폴트 스트림은 아니고) 프로그램 스트림에서는 오디오 기본 스트림은 복수의 서브 스트림에 장래 분할될지도 모른다. 이것은 프라이빗 복수 오디오 트럭으로 일어나는 것이 많다. 어플리케이션은 필요한 서브 스트림 필터 링 정보와 함께 핀을 제공할 책임이 있으므로, 핀은 어느 서브 스트림을 오디오 디코더에 건네줄까를 알고 있다. 자세한 것은 IMPEG2StreamIDMap::MapStreamID 페이지를 참조할것.

트랜스폴트 스트림 모드로 핀을 구성한다

필터 그래프에 BDA Network Provider 필터가 있다면, 이 필터는 자동적으로 모든 필요한 출력 파일을 Demux 상에 생성 해, 각 핀에 PID 를 맵 한다. 오디오와 비디오의 스트림에서는, 일반적으로는 각 핀에 1 개의 PID 가 있다. 프로그램 서비스 정보 (PSI) 스트림에서는, 몇개의 PID 가 트랜스폴트 정보 필터 (TIF)에 접속하는 출력 핀에 매핑 되는 경우가 있다. BDA 네트워크 프로바이더 는 장면의 뒤편에서 TIF 와 함께 동작해, PSI 스트림의 여러가지 겉(표)의 PID 를 취득해, 거기에 따라서 Demux 의 출력 핀을 구성한다. BDA 를 베이스로 하지 않는 커스텀 필터를 통해 트랜스폴트 스트림을 제공하고 있다면, 필터나 어플리케이션중 한쪽이 이 작업을 해야 한다.

Clock Behavior

Demux 는 IReferenceClock 인터페이스를 이행 하는 것으로써, 필터 그래프의 참조 클락으로서 기능한다. 트랜스폴트 스트림과 함께, 이 클락은 마지막에 맵 된 오디오 혹은 비디오 스트림에 대응하는 PCR 스트림에 종속된다. 이외에 PCR 가 존재해도, 그것들은 트럭 되지만, 사용되지 않는다. 프로그램 스트림과 함께, Demux 는 그 클락을 SCR 스트림에 종속시킨다. 클락의 PCR 나 SCR 스트림에의 종속에 의해, 다운 스트림 버퍼의 오버플로우나 언더 플로우(underflow) 상태를 피할 수가 있는, 그렇게 하지 않으면 로컬 시스템 클록과 스트림 클락간의 틀림에 따라 오버플로우나 언더 플로우(underflow)가 일어난다.

Demux 는 다운 스트림 필터에 대해서 단조 증가하는 프레젠테이션 시간을 보증한다. 이것은 예를 들어 다음과 같은 일을 의미하는, 트랜스폴트 스트림이 주프로그램과는 다른 클락으로 생성 된 코머셜과 같은 세그먼트(segment)를 포함하고 있어도, Demux 는 프레젠테이션 시간 스탬프를 조정해, 다운 스트림 디코더와 렌더러로부터 불연속를 숨긴다.

필터 인터페이스 | IMpeg2Demultiplexer ,IBaseFilter ,IReferenceClock ,ISpecifyPropertyPages
입력 핀 미디어 타입 | MEDIATYPE_Stream, MEDIASUBTYPE_MPEG2_TRANSPORT, Format_None MEDIATYPE_Stream, MEDIASUBTYPE_MPEG2_PROGRAM, Format_None
입력 핀인타페이스 | IPin
출력 핀 미디어 타입 | 오디오와 비디오의 기본 스트림은 오디오와 비디오의 메이저 타입을 가지지 않으면 안 된다. Demux 는 미디어 서브 타입에 무제한을 설정한다.
출력 핀인타페이스 | IMPEG2StreamIDMap , IMPEG2PIDMap , IPin
필터 CLSID | CLSID_MPEG2Demultiplexer
프로퍼티 페이지 CLSID | ISpecifyPropertyPages 인터페이스를 사용해 프로퍼티 페이지에 액세스 한다.
실행 모듈 | mpg2splt.ax
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory


MPEG-2 스플리터

MPEG-2 스플리터 필터는, MPEG-2 비디오, MPEG-2 오디오, DVD 비디오의 정의에 따라 encode 된 AC3 오디오, DVD 비디오의 정의에 따라 encode 된 PCM 오디오의 몇개의 스트림 타입을 1 개 이상 포함한 프르모드로 출력된(파일 재생) MPEG-2 프로그램 스트림을 입력으로서 받아들인다. 이 필터는, 스트림을 해석해 각각 대하는 출력 핀을 생성 해, 압축 오디오 또는 비디오 MPEG 패킷을 MPEG-2 디코더 필터에 출력한다.

Microsoft DirectShow 는 MPEG-2 디코더를 제공하지 않는다.

푸쉬 모드 (라이브 소스)로 출력된 MPEG-2 프로그램 스트림과 트랜스폴트 스트림은 MPEG-2 Demultiplexer 를 사용한다.

필터 인터페이스 | IBaseFilter , ISpecifyPropertyPages,IAMParse ,IAMStreamSelect
입력 핀 미디어 타입
  • MEDIATYPE_Stream, MEDIASUBTYPE_MPEG2_PROGRAM
  • MEDIATYPE_Stream, MEDIASUBTYPE_MPEG2_TRANSPORT
  • MEDIATYPE_Stream, MEDIASUBTYPE_MPEG1_Video
  • MEDIATYPE_Stream, MEDIASUBTYPE_NULL
입력 핀인타페이스 | IPin ,IMemInputPin
출력 핀 미디어 타입
출력 핀인타페이스 | IPin ,IMediaSeeking
필터 CLSID | CLSID_MMSPLITTER
프로퍼티 페이지 CLSID | N/A
실행 모듈 | mpg2splt.ax
메리트 | MERIT_NORMAL + 1
카테고리 | CLSID_AudioInputDeviceCategory


MSYUV 칼라 스페이스 변환 CODEC

MSYUV 는 YUV 로부터 RGB 칼라 스페이스에의 컨버터 CODEC 이다. 비록 클라이언트의 비디오 디스플레이 어댑터의 하드웨어 YUV-to-RGB 변환을 사용할 수 없어도, YUV 포맷의 비디오 소스 데이터의 재생을 가능하게 한다. CODEC 는 AVI 데콘프렛사 래퍼 필터를 통해 필터 그래프에 참가한다.

1394 나 USB 인터페이스를 가진 디지털 컨퍼런스 카메라는 복수의 YUV 포맷으로 이미지 데이터를 생성 할 수 있다. 디스플레이 하드웨어가 온보드의 YUV-to-RGB 변환을 지원 하고 있지 않는, 혹은 하드웨어 변환 성능이 있는 다른 이유로써 사용할 수 없으면, YUV 이미지 데이터는 비디오 렌더러에 보내지기 전에 RGB 포맷에 변환되지 않으면 안 된다.

필터 그래프를 구축 하면 와, 그래프 빌더는 출력 핀 미디어 타입의 YUV 포맷을 검지해, 그래프내에 AVI 데콘프렛사를 삽입한다, 그리고 AVI 데콘프렛사는 MSYUV CODEC 를 로드해 RGB 에의 변환을 실시하도록(듯이) 최초로 구성한다. 그래프가 최초로 실행 혹은 포즈로 이행한 다음에, 비디오 렌더링 필터는 비디오 디스플레이 어댑터가 하드웨어 변환 가능한가 어떤가를 검지할 수 있다. 가능하면, AVI 데콘프렛사는 통지를 받아 MSYUV 를 「파스스르모드」로 처리하도록(듯이) 복구성 하는, 그것에 의해 CODEC 는 변환을 스킵 해, YUV 이미지 데이터를 직접 비디오 메모리의 DirectDraw 오바레이서페이스에 카피한다.

이하의 리스트에 나타내도록(듯이), MSYUV 는 팩 된 YUV 포맷을 RGB 로 변환한다 :
  • UYVY -> RGB16, RGB8
  • YUY2 -> RGB16, RGB8
  • YVYU -> RGB16, RGB8

필터의 상세한 것에 대하여는, 「AVI 데콘프렛사」를 참조할것.


NABTS/FEC VBI CODEC 필터

NABTS/FEC VBI CODEC 는 아날로그 TV 필터 그래프내의 커넬 모드 스트림 클래스 필터이다. 캡춰 된 VBI 라인을 처리해, NABTS 데이터 스트림에 포함되는 디코드 처리나 포워드 에러 수정을 하신 SLOP 패킷을 BDA SLIP 데후레이마,BDA IP 세면대 그리고 최종적으로는 Winsock 에 출력한다. 이 필터에는 어플리케이션으로부터 호출해 가능한 인터페이스는 없다.

NABTS/FEC VBI CODEC 는 2 개의 핀을 가지는, VBI 와 HQNABTS 이다. VBI 핀은 캡춰 필터가 로 VBI 데이터를 출력하고 있을 때 이용되어 HWNABTS 는 캡춰 필터가 디코드된 VBI 데이터를 출력하고 있을 때 이용되는, 이 경우,NABTS/FEC VBI CODEC 는 단지 그 데이터를 BDA SLIP 데후레이마 에 건네주는 것만으로 있다.

NABTS/FEC VBI CODEC 는 GrapEdit 내에서 "WDM Streaming VBI CODEC" 카테고리에 있다. 이것은 커넬 모드 필터이므로, 어플리케이션은 직접 co-create 할 수 없지만,디바이스와 필터의 열거 로 설명되고 있도록(듯이),시스템 디바이스 열거자 를 사용해 인스턴스화하지 않으면 안 된다. 이 필터는 IFilterGraph::AddFilter 메소드를 사용해 그래프에 수동으로 추가되지 않으면 안 되는,캡춰 그래프 빌더 는 이 필터를 그래프에 추가하기 위해서는 사용할 수 없다.


Null 렌더링 필터

이 필터는, 샘플 데이터의 표시나 렌더링을 실시하지 않는, 받은 모든 샘플을 파기하는 렌더러이다.

Null 렌더러는, 그래프의 출력 핀과 다운 스트림 접속이 필요하다, 그러나 해당 핀으로부터의 데이터를 렌더링 하지 않는 것에 주의 해야 한다. 출력 핀을 Null 렌더러에 접속하는 것으로, 데이터의 렌더링을 실시하지 않는 접속을 실현할 수 있다.

필터 인터페이스 | IBaseFilter
입력 핀 미디어 타입 | 임의의 미디어 타입.
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | 이용할 수 없다.
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_NullRenderer
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | Qedit.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_LegacyAmFilterCategory


오버레이 믹서 필터

오버레이 믹서 필터는, 기본적으로는 Microsoft® DirectDraw® 베이스의 비디오 렌더러이다. 이 필터는 전송처 칼라 키잉을 사용해, 비디오 표면을 Line 21 자막 방송 또는 디지털 비디오 디스크 (DVD) 서브 픽쳐 데이터등의 시나리오의 오버레이와 믹싱 한다. 이 필터는, 주로 DVD 재생 어플리케이션이나 비디오 캡춰 어플리케이션으로 사용되지만, 비디오 표면에 오버레이를 적용할 필요가 있는 임의의 시나리오로 사용할 수 있다.

어플리케이션이 IDVDGraphBuilder 인터페이스 및 ICaptureGraphBuilder2 인터페이스를 사용해 그래프를 생성 하면, 이 필터는 자동적으로 필터 그래프에 추가된다. 메리트가 MERIT_DO_NOT_USE 이므로, 오버레이 믹서는, 파일의 렌더링시에 필터 그래프 매니저에 의해 자동적으로 그래프에 적용될 것은 없다. 게임 어플리케이션은 오버레이 믹서를 제한부로 사용해, 비디오를 게임 화면에 추가할 수가 있다.

(주 : 오버레이 믹서 2 필터는, 2 개의 점을 제외해 오버레이 믹서와 같다. 오버레이 믹서는, VIDEOINFO 및 VIDEOINFO2 포맷 타입을 지원 하지만, 오버레이 믹서 2 는 VIDEOINFO2 포맷 타입 밖에 지원 하지 않는다. 그리고, 오버레이 믹서 2 의 메리트는 MERIT_UNLIKELY 로, 이것은 필터 그래프 매니저를 사용해 파일을 렌더링 할 경우에, 경우에 따라서는 자동적으로 그래프에 적용되는 일이 있는 것을 의미한다. 이 필터는, 주로 TV 프리뷰/캡춰 그래프에 사용된다. )

어플리케이션은, 오버레이 믹서의 특정의 동작을 IMixerPinConfig2 인터페이스를 개입시켜 제어할 수가 있지만, 이 주제로 설명하도록(듯이), 어플리케이션 개발자는 믹서의 내부 동작을 신경쓸 필요는 없다. 이하의 정보는, 필터 개발자나, 오버레이 믹서의 DirectDraw 배타 모드를 사용하는 게임 개발자를 대상으로 하고 있다.

내부 동작

오버레이 믹서는, 입력 스트림 마다 입력 핀을 공개한다. 일반적으로는, 비디오 데이터용의 핀 0, Line 21 및 DVD 서브 픽쳐 데이터용의 핀 1 및 2 의 3 개의 입력 핀이 있다. 내부적으로는 오버레이 믹서는 DirectDraw 를 사용해 비디오를 렌더링 한다. 오버레이 믹서는, 데스크탑 전체를 구성하는 프라이머리 표면과 핀 0 에 접속된 비디오 스트림의 사이즈에 의해 그 직사각형이 정의되는 오버레이 표면을 가지는 DirectDraw 오브젝트를 생성 한다. 디코더가 칼라 키를 지정하지 않는 경우, 오버레이 믹서는 디폴트의 칼라 키로서 최근의 그래픽 카드의 경우는 다크 회색, 낡은 256 색카드의 경우는 진홍색을 사용한다.

주 : 오버레이 믹서의 현재의 버젼에서는, 오버레이 표면 위에의 같은 장소에서 동시에 렌더링 하는 2 개의 비디오 스트림을 디코더가 건네주었을 경우, 그 결과는 부정이다. 이러한 상황은, 서브 픽쳐와 Line 21 스트림의 양쪽 모두를 포함한 DVD 로 발생하는 일이 있다. 비디오에 플릭커가 발생하는지, 어느쪽이든 한편의 스트림이 표시된다.

비디오 디코더와의 업 스트림 접속

보통, 오버레이 믹서의 입력 핀은, 업 스트림의 비디오 디코더 (다른 디코더가 Line 21 또는 DVD 서브 픽쳐 데이터를 처리하는 경우는 복수의 디코더)에 접속한다. 입력 비디오 데이터는, 반드시 오버레이 믹서의 핀 0 에 접속할 필요가 있다. Line 21 또는 서브 픽쳐 데이터 스트림은, 그것이 같은 비디오 디코더로부터 입력될지 어떨지에 관계없이, 핀 1 또는 그 이후에 접속한다. 디코더가, 호스트 CPU 를 배타적으로 사용하는 소프트웨어 디코더의 경우, 디코더와 오버레이 믹서의 핀 0 과의 사이의 접속은, 표준 IMemInputPin 인터페이스 접속이 된다. 디코더가 하드웨어 가속화를 이용하는 경우, 오버레이 믹서의 핀 0 에의 접속은 IAMVideoAccelerator 접속이 아니면 안된다. 이것들 2 종류의 접속은 서로 배타적이다.

하드웨어 디코더를 랩 해 비디오 포토 경유로 오버레이 믹서에 접속하는 필터는,IVPConfig 를 이행 할 필요가 있다. 오버레이 믹서는 IVPNotify 인터페이스를 이행 한다. 이 필터는, 각종의 제어 정보를 설정 및 취득하기 위해서 디코더 위에의 IVPConfig 로 사용된다. 이 메카니즘에 의해, 디코더가 필요한 오버레이 표면에 관한 정보를 지정할 수 있는 한편, 오버레이 믹서는, 비디오 메모리내에서의 그러한 표면의 위치를 디코더에 통지하는 것이 가능하게 된다. 또 오버레이 믹서는, 비디오 직사각형이 정상적으로 스케일링 되는 것을 보증한다. 비디오 캡춰 시나리오는, 프리뷰 이미지의 스케일링과 인터리브 된 비디오 프레임의 캡춰에 관해서 특정의 문제를 제시한다. 하드웨어 비디오 캡춰 디바이스의 필터 또는 WDM 드라이버의 개발에 관한 상세한 것에 대하여는, 「IVPConfig 」 및 「IVPNotify 」를 참조할것.

오버레이 믹서는, 1394 또는 USB 캡춰 시나리오에서는 사용되지 않는다. 오버레이 믹서는, PCI 버스상에서의 비디오 캡춰에 사용된다.

비디오 렌더러와의 다운 스트림 통신

오버레이 믹서에 접속된 Microsoft® DirectShow® 비디오 렌더러 필터는, 실제는 비디오를 전혀 렌더링 하지 않는다. 그 접속은,IMemInputPin 접속은 아니고,IOverlay 접속이다. 이것에 의해, 오버레이 믹서가 실제의 렌더링을 실시할 수 있게 되어, 비디오 렌더러의 역할은 윈도우의 생성과 데스크탑상에서의 윈도우의 사이즈와 위치의 제어만으로 된다. 이 윈도우는, 최상정도의 윈도우 또는 어플리케이션내의 자식 윈도우를 의미한다. 오버레이 믹서와 비디오 렌더러는, 비디오 렌더러측의 IOverlay 와 오버레이 믹서측의 IOverlayNotify 를 사용해, 그래프 처리중에 연속적으로 대화를 실시한다. 윈도우 사이즈 및 위치 정보에 가세해 비디오 렌더러는, 직사각형 클리핑을 관리하는 DirectDraw 에 윈도우 핸들을 오버레이 믹서 경유로 건네준다. 어플리케이션은,IVideoWindow 인터페이스 및 IBasicVideo2 인터페이스를 개입시켜 비디오 렌더러를 제어할 수가 있다.

DirectDraw 배타 모드

오버레이 믹서의 DirectDraw 배타 모드는, 게임에서 화면의 일부에 비디오를 표시할 수 있도록(듯이) 한다. 이 모드에서는, 오버레이 믹서는, 비디오 렌더러에 의해 제공된 윈도우내는 아니고, 게임 어플리케이션에 의해 생성 된 DirectDraw 표면에 비디오를 직접 렌더링 한다. 이것에 의해, 게임은 칼라 키를 제어할 수 있다. 오버레이 믹서를 DirectDraw 배타 모드로 사용하려면 , 오버레이 믹서의 인스턴스를 생성 해, 필터 그래프를 생성 하기 전에 그 IDDrawExclModeVideo 인터페이스를 취득해, DirectDraw 표면을 오버레이 믹서에 추가한다. 오버레이 믹서에 의해, 렌더링이 DirectDraw 표면으로 행해진다. 이 모드에 관한 1 개(살)의 중요한 제한으로서 게임이 실제의 비디오 비트에 액세스 할 수 없다고 하는 일이 있다. IDDrawExclModeVideo 를 사용했을 경우, 어플리케이션은 프라이머리 표면을 생성 해, 오버레이 믹서는 오버레이 표면을 생성 한다.

또, DirectDraw 배타 모드를 사용해 (예를 들어 Web 페이지내에서) 윈드우레스렌다링을 실시할 수도 있지만, 이러한 처리는 추천 되지 않는다. 그 이유는, 오버레이 믹서가 이 모드로 믹싱을 실시하지 않기 때문에이다. 이것은, Line 21 또는 서브 픽쳐 데이터를 표시할 수 없는 것을 의미한다. 윈드우레스모드로 DVD 재생 어플리케이션을 쓰는 경우는,MSWebDVD ActiveX® 컨트롤을 사용하는 어프로치가 추천 된다.

필터 인터페이스 | IAMOverlayFX , IAMVideoDecimationProperties , IBaseFilter , IDDrawExclModeVideo , IKsPropertySet , IMediaPosition , IMediaSeeking , IQualProp
입력 핀 미디어 타입 메이저 타입 : MEDIATYPE_Video
서브 타입 :
  • MEDIASUBTYPE_Overlay (핀 0 마셔)
  • DirectDraw YUV 포맷 : MEDIASUBTYPE_YUVxx (핀 0 마셔)
  • DirectDraw 비디오 가속화 포맷 : MEDIASUBTYPE_DVAxxx (핀 0 마셔)
  • Microsoft® DirectDraw® RGB 포맷 : MEDIASUBTYPE_RGBxx (모든 입력 핀)
포맷 타입: Format_VIDEOINFO, Format_VIDEOINFO2
입력 핀인타페이스 | IAMVideoAccelerator , IKsPropertySet , IMemInputPin , IMixerPinConfig , IMixerPinConfig2 , IOverlay (핀 0 마셔), IPin , IPinConnection , IQualityControl , IVPNotify , IVPNotify2
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_Overlay
출력 핀인타페이스 | IPin , IQualityControl
필터 CLSID | CLSID_OverlayMixer
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | qdvd.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_LegacyAmFilterCategory


오버레이 믹서 2 필터

오버레이 믹서 2 필터는 기능적으로는 오버레이 믹서와 같지만, 메리트가 높고, 자동적으로 필터 그래프에 추가된다. 오버레이 믹서 2 필터는, TV 캡춰/프리뷰 그래프내의 비 DVD MPEG-2 파일을 렌더링 할 경우에 필터 그래프 매니저가 오버레이 믹서를 그래프에 추가할 수 있도록(듯이) 준비되어 있다. 이러한 처리는, 메리트가 MERIT_DO_NOT_USE 인 오리지날의 오버레이 믹서에서는 불가능하다. 이제(벌써) 1 개의 차이로서 오버레이 믹서가 VIDEOINFO 및 VIDEOINFO2 포맷 타입을 지원 하는데 대해, 오버레이 믹서 2 는 VIDEOINFO2 포맷 타입 밖에 지원 하지 않는다. 오버레이 믹서와 오버레이 믹서 2 의 어느 쪽을 선택할까는, 그래프를 생성 한 컴퍼넌트, 즉 필터 그래프 매니저, 캡춰 그래프 빌더, 또는 DVD 그래프 빌더에 따라서 다르다. 어플리케이션으로부터 보면, 양자는 같은 인터페이스와 기능을 가지는 동일한 필터이다.

오버레이 믹서에 관한 설명도 오버레이 믹서 2 에 들어맞는다.

필터 인터페이스 | IAMOverlayFX , IAMVideoDecimationProperties , IBaseFilter , IDDrawExclModeVideo , IKsPropertySet , IMediaPosition , IMediaSeeking , IQualProp
입력 핀 미디어 타입 메이저 타입 : MEDIATYPE_Video
서브 타입 :
  • MEDIASUBTYPE_Overlay (핀 0 마셔)
  • Microsoft® DirectDraw® RGB 포맷 : MEDIASUBTYPE_RGBxx (모든 입력 핀)
  • DirectDraw YUV 포맷 : MEDIASUBTYPE_YUVxx (핀 0 마셔)
  • DirectDraw 비디오 가속화 포맷 : MEDIASUBTYPE_DVAxxx (핀 0 마셔)
포맷 타입: Format_VIDEOINFO2
입력 핀인타페이스 | IAMVideoAccelerator , IKsPropertySet , IMemInputPin , IMixerPinConfig , IMixerPinConfig2 , IOverlay (핀 0 마셔), IPin , IPinConnection , IQualityControl , IVPNotify , IVPNotify2
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_Overlay
출력 핀인타페이스 | IPin , IQualityControl
필터 CLSID | CLSID_OverlayMixer2
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | qdvd.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory


QT 데콘프렛사피르타

QT 데콘프렛사피르타는, Apple® QuickTime® 2.0 비디오를 압축 해제한다. 보통, 이 포맷은 낡은 QuickTime 파일로 사용되고 있다.

필터 인터페이스 | IBaseFilter
입력 핀 미디어 타입 MEDIATYPE_Video, FORMAT_VideoInfo

다음의 서브 타입이 유효하다.
  • MEDIASUBTYPE_QTRpza
  • MEDIASUBTYPE_QTSmc
  • MEDIASUBTYPE_QTRle
  • MEDIASUBTYPE_QTJpeg
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_NULL, FORMAT_VideoInfo
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_QTDec
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory


QuickTime 무비 퍼서 필터

QuickTime 무비 퍼서 필터는, Apple® QuickTime® 데이터를 오디오 스트림과 비디오 스트림에 분할한다. 이 필터는 QuickTime 2.0 이전을 지원 한다. 입력 핀은,비동기 파일 소스 필터 또는URL 파일 소스 필터등의 소스 필터에 접속된다. 이 퍼서는,AVI 데콘프렛사 또는 QT 데콘프렛사 필터를 사용해, QuickTime 파일을 압축 해제한다. 이 필터는, 비디오 스트림용의 1 개의 출력 핀과 오디오 스트림용의 1 개의 출력 핀을 생성 한다.

필터 인터페이스 | IAMMediaContent ,IBaseFilter
입력 핀 미디어 타입 | MEDIATYPE_Stream, MEDIASUBTYPE_QTMovie;
입력 핀인타페이스 | IPin ,IQualityControl
출력 핀 미디어 타입
  • MEDIATYPE_Video, MEDIASUBTYPE_NULL, FORMAT_VideoInfo
  • MEDIATYPE_Audio, MEDIASUBTYPE_NULL, FORMAT_WaveFormatEx
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_QuickTimeParser
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory


SAMI (CC) 퍼서 필터

SAMI (Synchronized Accessible Media Interchange) 파일로부터의 캡션 데이터를 해석한다.

SAMI 는, HTML 를 닮은 텍스트 포맷이며, 타임 베이스 캡션의 encode에 사용된다. 이 필터는, SAMI 데이터를 텍스트 스트림으로 변환한다. 스트림의 각 샘플에는, 캡션 엔트리와 함께, 포맷 정보가 포함되어 있다. 샘플의 타임 스탬프는, SAMI 파일의 타임 정보로부터 생성된다.

이 필터는,내부 스크립 코맨드 렌더링 필터와 함께 사용하도록(듯이) 설계되고 있다. 내부 스크립 코맨드 렌더러는, 텍스트 샘플을 받아, 이벤트 통지로서 어플리케이션에 보낸다. 상세한 것에 대하여는, 「주의」를 참조할것.

필터 인터페이스 | IAMStreamSelect ,IBaseFilter
입력 핀 미디어 타입 | MEDIATYPE_Stream
입력 핀인타페이스 | IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Text, MEDIASUBTYPE_NULL
출력 핀인타페이스 | IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | {33FACFE0-A9BE-11D0-A520-00A0D10129C0}
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음
실행 모듈 | quartz.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory

주의

다음에 나타내는 것은, 단순한 SAMI 파일이다.

<SAMI>
<Head>
<STYLE TYPE="text/css"> <! --
    . ENCC {Name: English; lang:en-US; SAMI_TYPE: CC;}
    . FRCC {Name: French; lang:fr-FR; SAMI_TYPE: CC;}
    #NORMAL {Name: Normal; font-family: arial;}
    #GREENTEXT {Name: GreenText; color:green; font-family: verdana;}
-->
</STYLE>
</Head>
<BODY>
<Sync Start=1000>
    <P CLASS="ENCC">One
    <P CLASS="FRCC">Un

<Sync Start=2000>
    <P CLASS="ENCC">Two
    <P CLASS="FRCC">Deux

<Sync Start=3000>
    <P CLASS="ENCC">Three
    <P CLASS="FRCC">Trois
</BODY>
</SAMI>

STYLE 태그에서는, 영어 (. ENCC)와 프랑스어 (. FRCC)의 2 개의 언어 설정이 정의된다. 또, #NORMAL 및 #GREENTEXT 라고 하는 2 개의 스타일도 정의된다. 각 SYNC 태그에서는, 캡션의 시작 타임을 밀리 세컨드 단위로 정의한다. P 태그에는 캡션 텍스트가 포함되어CLASS 속성에는 캡션의 적용처가 되는 언어 설정을 지정한다.

각 언어와 스타일에 대해, 필터는 논리 스트림을 생성 한다. 항상, 1 개의 언어 스트림과 1 개의 스타일 스트림을 유효하게 할 수 있다. 필터가 샘플을 생성할 때는, 현재의 언어의 캡션을 선택해, 현재의 스타일을 적용한다. 디폴트에서는, 파일로 선언하는 최초의 언어와 스타일이 유효하게 된다. 어플리케이션은 IAMStreamSelect::Enable 메소드를 사용해, 다른 스트림을 유효하게 할 수 있다.

디폴트의 설정에서는, 샘플 파일의 최초의 캡션에 의해, 다음의 출력이 생성 된다.

<P STYLE=" Name: English; lang:en-US; SAMI_TYPE: CC; Name: Normal; font-family: arial;">One

출력이 내부 스크립 코맨드 렌더러에 보내지면(자), 이 필터는 EC_OLE_EVENT 이벤트 통지를 보낸다. 2 번째의 이벤트 파라미터는, 캡션 텍스트를 가지는 BSTR 이다. 어플리케이션은, 이벤트를 취득해 캡션을 표시할 수 있다.

다음의 샘플 코드는, SAMI 파일의 렌더링 방법, 스트림 정보의 취득 방법, 스트림을 유효하게 하는 방법, 및 캡션 텍스트의 표시 방법에 대해 가리키고 있다. 이 예에서는, 이전의 SAMI 파일이 C:\Sami_test_file.sami 로서 보존되고 있는 것을 상정하고 있다. 간결하게 하기 위해서, 이 샘플 코드에서는,IAMStreamSelect::Enable 메소드를 호출할 때에 하드 코딩 된 스트림 인덱스를 사용하고 있다.

void __cdecl main()
{
    HRESULT hr;
    IGraphBuilder *pGraph;
    IMediaControl *pMediaControl;
    IMediaEventEx *pEv;
    IBaseFilter   *pSAMI;

    CoInitialize(NULL);

    // 필터 그래프 매니저를 생성 한다.
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC,
                        IID_IGraphBuilder, (void **) &pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **) &pMediaControl);
    pGraph->QueryInterface(IID_IMediaEventEx, (void**) &pEv);

    // 그래프를 생성 해, SAMI 퍼서를 찾는다.
    pGraph->RenderFile(L"C:\\Sami_test_file.sami", NULL);
    hr = pGraph->FindFilterByName(L"SAMI (CC) Parser", &pSAMI);
    if (SUCCEEDED(hr))
    {
        IAMStreamSelect *pStrm = NULL;
        hr = pSAMI->QueryInterface(IID_IAMStreamSelect, (void**) &pStrm);
        if (SUCCEEDED(hr))
        {
            DWORD dwStreams = 0;
            pStrm->Count(&dwStreams);
            printf("Stream count: %d\n", dwStreams);

            // 프랑스어 및 "GreenText" 를 선택한다.
            hr = pStrm->Enable(1, AMSTREAMSELECTENABLE_ENABLE);
            hr = pStrm->Enable(3, AMSTREAMSELECTENABLE_ENABLE);

            // 각론리스트림의 이름을 출력한다.
            for (DWORD index = 0; index < dwStreams; index++)
            {
                DWORD dwFlags;
                WCHAR *wszName;
                hr = pStrm->Info(index, NULL, &dwFlags, NULL, NULL, &wszName, NULL, NULL);
                wprintf(L"Stream %d: %s [%s]\n", index, wszName,
                    (dwFlags ?   L"ENABLED" : L"DISABLED"));
                CoTaskMemFree(wszName);
            }
            pStrm->Release();
        }
        pSAMI->Release();
    }

    // 그래프를 실행해, 캡션을 표시한다.
    pMediaControl->Run();
    while (1)
    {
        long evCode, lParam1, lParam2;
        pEv->GetEvent(&evCode, &lParam1, &lParam2, 100);

        if (evCode == EC_OLE_EVENT) {
            wprintf(L"%s\n", (BSTR) lParam2);
        }
        pEv->FreeEventParams(evCode, lParam1, lParam2);

        if (evCode == EC_USERABORT || evCode == EC_COMPLETE || evCode == EC_ERRORABORT)
            break;
    }

    // 클린 업 한다.
    pMediaControl->Release();
    pEv->Release();
    pGraph->Release();
    CoUninitialize();
}

이 필터는,IAsyncReader 인터페이스를 사용해 소스 필터로부터 샘플을 취득하고 있다. 그 때문에, 이 필터는, 입력 핀상에서 IMemInputPin 인터페이스를 지원 하고 있지 않다.


샘플 grabber 필터

샘플 grabber 필터는, 샘플이 필터 그래프를 통과할 경우에 그것을 취득하는 방법을 제공한다. 이 필터는, 1 개의입력 핀과 1 개의출력 핀을 가지는변환 필터이다. 이 필터는, 모든 샘플을 그대로 다운 스트림에 건네주므로, 데이터 스트림을 변경하지 않고 필터 그래프에 삽입할 수가 있다. 이것에 의해, 어플리케이션은 ISampleGrabber 인터페이스로 메소드를 호출하는 것으로, 필터로부터 개개의 샘플을 취득할 수 있다.

데이터를 렌더링 하지 않고 샘플을 취득하는 경우는, 샘플 grabber 필터를 Null 렌더링 필터에 접속한다.

이 필터의 사용 방법에 대해서는, 「미디어 샘플의 입수」를 참조할것.

필터 인터페이스 | IBaseFilter ,ISampleGrabber
입력 핀 미디어 타입 | 임의의 미디어 타입.
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | 임의의 미디어 타입. 입력 미디어 타입과 같다.
출력 핀인타페이스 | IPin ,IQualityControl
필터 CLSID | CLSID_SampleGrabber
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | Qedit.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_LegacyAmFilterCategory


스마트티피르타

스마트티피르타는, 비디오 스트림을 프리뷰 스트림과 캡춰 스트림에 분할하기 위해서 비디오 캡춰 그래프로 사용된다. 이 처리는, 그 밖에 데이터를 카피하는 일 없이 행해진다. 출력 핀은, 다운 스트림 접속에 대해 지원 되는 모든 미디어 타입을 지원 한다.

스마트티피르타는, 비디오 캡춰 필터가 캡춰와 프리뷰용으로 개별의 핀을 제공하지 않는 경우에 편리하다. 스마트티피르타는, 거기에 따라 캡춰 퍼포먼스가 저하하는 것이 없는 경우에게만, 프리뷰 데이터를 배송한다. 또 스마트티피르타는, 프리뷰 스트림으로부터 타임 스탬프를 삭제한다. 캡춰 그래프 빌더는, 필요에 따라서 스마트티피르타를 자동적으로 삽입한다. 상세한 것에 대하여는, 「캡춰 어플리케이션의 쓰는 법」을 참조할것.

이하의 그림에, 스마트티피르타를 사용하는 일반적인 캡춰 그래프를 나타낸다.

스마트 티 필터의 사용법

필터 인터페이스 | IBaseFilter
입력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_NULL
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_NULL
출력 핀인타페이스 | IAMStreamControl , IPin , IQualityControl
필터 CLSID | CLSID_SmartTee
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | qcap.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_LegacyAmFilterCategory


Tee/Sink-to-Sink 컨버터

Tee/Sink-to-Sink 컨버터 는 커넬 모드의 sProxy 베이스의 필터이다. VBI 데이터가 렌더링 되거나 캡춰 되거나 하는 아날로그 비디오 TV 필터 그래프내에서 이용된다. 이 필터는 업 스트림을 WDM 비디오 캡춰 필터에 접속해, 커넬 모드와 유저 모드간의 변환에 부하를 걸지 않고, 커넬 모드내에서 데이터의 스트림을 카피하는 효율적인 방법을 제공한다. 그것은 받은 각 데이터 블록을 모든 출력 핀에 출력해, 다운 스트림 CODEC 는 지정된 디코드나무 VBI 데이터를 찾아낼 책임을 가진다.

Tee/Sink-to-Sink 컨버터 외 중요한 기능은 실제로는 어플리케이션 프로그래머에게는 관계없지만, 여기에서는 완결에 대해 언급한다. "Sink-to-Sink" 성능은 Microsoft® Windows 98® 플랫폼에 대해서, 각각이 들어 오는 IRP 만을 지원 하는 2 개의 드라이버의 접속을 가능하게 하기 위해서 요구되고 있었다. 이 기능은 WDM 아키텍쳐의 다른 컴퍼넌트에 의해 실행되고 있다.

Tee/Sink-to-Sink 컨버터 는 GrapEdit 내에서 "WDM Streaming Tee/Splitter Devices" 카테고리에 있다. 이것은 커넬 모드 필터이므로, 어플리케이션은 직접 co-create 할 수 없지만,디바이스와 필터의 열거 로 설명되고 있도록(듯이),시스템 디바이스 열거자 를 사용해 인스턴스화하지 않으면 안 된다.


TV 오디오 필터

TV 오디오 필터는, 텔레비젼 오디오 디코딩, 스테레오/단청의의 선택, 및 세칸다리오디오프로그람 (SAP)의 선택에 관한 제어를 제공한다.

이 필터는, Microsoft® Windows® 98 및 Windows 2000 으로 이용 가능하다.

필터 인터페이스 | IAMTVAudio ,IPersistPropertyBag,ISpecifyPropertyPages,IKsPropertySet
입력 핀 미디어 타입 | MEDIATYPE_AnalogAudio
입력 핀인타페이스 | IKsPropertySet
출력 핀 미디어 타입 | MEDIATYPE_AnalogAudio
출력 핀인타페이스 | IKsPropertySet
필터 CLSID | CLSID_TVAudioFilter
프로퍼티 페이지 CLSID | CLSID_TVAudioFilterPropertyPage
실행 모듈 |
메리트 |
카테고리 | CLSID_AudioInputDeviceCategory


TV 튜너 필터

TV 튜너 필터는, 아날로그 브로드캐스트 또는 케이블 채널의 어느 쪽을 표시하는지를 선택한다. 이 1 개의 출력 스트림은, 아날로그 전용선 접속 시스템 비디오용의 하드웨어 패스이다. 이 출력은, 아날로그 비디오 크로스바 필터에 접속할 필요가 있다. 입력 핀에는, 케이블 입력과 안테나 입력이 있다.

이 필터는, Microsoft® Windows 98® 및 Windows 2000 으로 이용 가능하다.

필터 인터페이스 | IBaseFilter ,IAMTVTuner ,ISpecifyPropertyPages,IPersistPropertyBag,IKsObject,IKsPropertySet
입력 핀 미디어 타입 | 이용할 수 없다.
입력 핀인타페이스 | 이용할 수 없다.
출력 핀 미디어 타입 | 비디오 : MEDIATYPE_AnalogVideo, KSDATAFORMAT_SUBTYPE_NONE 오디오 : MEDIATYPE_AnalogAudio, MEDIASUBTYPE_NULL
출력 핀인타페이스 | IPin
필터 CLSID | CLSID_CTVTunerFilter
프로퍼티 페이지 CLSID | CLSID_TVTunerFilterPropertyPage
실행 모듈 | KSTVTune.ax
메리트 |
카테고리 | CLSID_VideoInputDeviceCategory


VBI 서페이스아로케이타

VBI 서페이스아로케이타는, 하드웨어의 비디오 포토 캡춰가 있는 아날로그 TV 그래프내의, VBI 버퍼의 할당을 컨트롤 한다. Bt829 디코더등의 디바이스에서는, frame buffer는 복수의 VBI 캡춰 버퍼를 가지고 있을 가능성이 있다. 그 버퍼에는, 일반적으로 비디오 포토로서 알려진, 하드웨어 독자적인 메카니즘을 통해 액세스 한다. VBISurf 필터는 캡춰 필터로부터 다운 스트림 필터와 접속해, 출력 핀을 가지지 않는다. 그 필터는 DirectDraw 를 통해오버레이 믹서와 밀접해 동작해, 같은 한정된 SVGA frame buffer 메모리를 이용해, 하드웨어의 비디오 포토로 조정된 조작을 실시한다.

필터 인터페이스 | IBaseFilter , IVPVBINotify
입력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_VPVBI
입력 핀인타페이스 | IVPVBINotify,IKsPropertySet
출력 핀 미디어 타입 | MEDIATYPE_NULL, MEDIASUBTYPE_NULL (출력 핀에는 아무것도 접속되지 않는다. )
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_VBISurfaces
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | vbisurf.ax
메리트 | MERIT_NORMAL
카테고리 | CLSID_LegacyAmFilterCategory


VFW 캡춰 필터

이 필터는, Video for Windows 를 사용하는 낡은 비디오 캡춰 하드웨어용이다.

이 필터에는 2 개의 출력 핀이 있어, 1 개(살)은 캡춰, 이제(벌써) 1 개(살)은 프리뷰 또는 오버레이로 불린다.

필터 인터페이스 | IPersistPropertyBag,IAMVfwCaptureDialogs ,IAMFilterMiscFlags ,IBaseFilter ,ISpecifyPropertyPages,IVfwCaptureOptions,IOverlayNotify
입력 핀 미디어 타입 | 이용할 수 없다.
입력 핀인타페이스 | 이용할 수 없다.
출력 핀 미디어 타입 | 캡춰 : MEDIATYPE_Video, MEDIASUBTYPE_NULL, FORMAT_VideoInfo 오버레이 : MEDIATYPE_Video, MEDIASUBTYPE_Overlay, FORMAT_VideoInfo 프리뷰 : MEDIATYPE_Video, MEDIASUBTYPE_NULL, FORMAT_VideoInfo
출력 핀인타페이스 | 캡춰 : IAMBufferNegotiation ,IAMDroppedFrames ,IAMPushSource ,IAMStreamConfig ,IAMStreamControl ,IAMVideoCompression ,IKsPropertySet ,IPin ,IQualityControl 오버레이 : IAMStreamControl ,IKsPropertySet ,IPin ,IQualityControl 프리뷰 : IAMPushSource ,IAMStreamControl ,IKsPropertySet ,IPin ,IQualityControl
필터 CLSID | CLSID_VfwCapture
프로퍼티 페이지 CLSID | CLSID_CaptureProperties
실행 모듈 | qcap.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_VideoInputDeviceCategory


VGA 16 색디자라피르타

VGA 16 카라디자라피르타는, 구식의 16 색모니터상에서 AVI 및 MPEG 비디오 스트림을 표시할 수 있도록(듯이), RGB 색타입을 4 비트의 칼라 디스플레이로 변환한다. 이 필터는, 데콘프렛사피르타와 비디오 렌더링 필터와의 사이의 그래프에 삽입된다.

필터 인터페이스 | IBaseFilter
입력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_RGB8
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Video, MEDIASUBTYPE_RGB4
출력 핀인타페이스 | IMediaPosition ,IMediaSeeking ,IPin ,IQualityControl
필터 CLSID | CLSID_Dither
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory


비디오 렌더링 필터

비디오 렌더링 필터는 범용의 비디오 렌더러이며, 압축 해제된 비디오 데이터를 생성하는 임의의 비디오 변환 필터에 접속할 수 있다.

비디오 카드가 지원 하고 있는 경우, 비디오 렌더링 필터는 Microsoft® DirectDraw® 의 메소드를 사용한다. 풀 스크린 렌더링은, 필터 그래프 매니저로부터 유효하게 된다. 필터 그래프 매니저는, 일부의 낡은 그래픽 카드에서는, 필요에 따라서 비디오 렌더러와 풀 스크린 렌더러를 자동적으로 바꾼다. 그 때문에, 사전에 필터 그래프에 풀 스크린 렌더러를 인클루드 할 필요는 없다. 새로운 카드로는, 비디오 렌더러 자신이 풀 스크린 렌더링을 실행한다.

비디오 그래픽 카드가 YUV 오버레이 서비스를 지원 하고 있는 경우, 비디오 렌더러는 YUV 포맷 및 RGB 포맷을 받아들인다. 그러나, 비디오 렌더러가 최초로 업 스트림 필터에 접속되면(자), 반드시 현재의 모니터 설정의 색 가지수와 일치하는 RGB 포맷을 요구하는 것에 주의하는 것이 중요하다. 예를 들어, 유저가 모니터를 24 비트색으로 설정해 있는 경우, 업 스트림 필터는 24 비트 RGB 의 데이터를 제공할 수 없으면 안 된다. 그래프가 실행 상태가 아니게 되면(자), 비디오 렌더러는 적절한 YUV 칼라 공간에의 동적인 포맷 변경을 네고시에이션 한다. 비디오 렌더러는, 비디오를 렌더링 하기 위해서, DirectDraw 의 사용으로부터 GDI 의 사용에 동적으로 바꾸지 않으면 안 되는 것도 있기 (위해)때문에, 최초로 RGB 포맷을 요구한다. GDI 는, YUV 칼라 공간을 지원 하고 있지 않다. 비디오 메모리가 다른 어플리케이션에 의해 사용되고 있는지, 또는 비디오 표시 직사각형이 복수의 모니터 시스템으로 2 개의 모니터에 걸치고 있다, 또는 비디오 직사각형이 완전하게 화면상외의 윈도우에 의해 숨겨지고 있는 경우, 비디오 렌더러는 GDI 로 전환한다.

이 필터는, 필터 그래프 매니저에 독자적인 PID 를 가져, 필터 그래프 매니저상에서 대응하는 인터페이스 메소드를 호출하는 것으로, 어플리케이션은 필터의 프로퍼티를 설정 및 취득할 수 있다. 이 경우 다른 대부분의 Microsoft® DirectShow® 필터는 어플리케이션으로부터는 안보인다.

비디오 렌더러를 co-create 하는 thread는 비디오 렌더러의 윈도우를 생성 한 thread이다. 그 thread는 비디오 렌더러의 윈도우에 메세지를 보내는 메시지 루프를 가지고 있지 않으면 안 된다.

필터 인터페이스 | IBaseFilter , IBasicVideo , IBasicVideo2 , IDirectDrawVideo , IKsPropertySet IMediaPosition , IMediaSeeking , IQualityControl , IQualProp , IVideoWindow
입력 핀 미디어 타입 | MEDIATYPE_Video
입력 핀인타페이스 | IMemInputPin ,IOverlay ,IPin ,IPinConnection ,IQualityControl
출력 핀 미디어 타입 | 이용할 수 없다.
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_VideoRenderer
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_PREFERRED
카테고리 | CLSID_LegacyAmFilterCategory


WAVE 퍼서 필터

WAVE 퍼서 필터는,. wav,. au, 또는 . aif 파일로부터의 WAV 포맷의 오디오 데이터를 해석한다. 업 스트림 필터는,비동기 파일 소스 필터,URL 파일 소스 필터, 또는 WAV 오디오 데이터를 포함한, 써드파티의 호환성의 비동기 소스 필터가 아니면 안된다. 출력 스트림은 오디오 데이터로, 직접 오디오 렌더링 필터에, 또는 사이에 접어드는 오디오 변환 필터에 접속할 수가 있다.

필터 인터페이스 | IAMMediaContent ,IBaseFilter ,IPersistMediaPropertyBag
입력 핀 미디어 타입 MEDIATYPE_Stream

다음의 서브 타입이 유효
  • MEDIASUBTYPE_AIFF
  • MEDIASUBTYPE_AU
  • MEDIASUBTYPE_WAVE
입력 핀인타페이스 | IPin ,IQualityControl
출력 핀 미디어 타입 | MEDIATYPE_Audio, MEDIASUBTYPE_NULL
출력 핀인타페이스 | IPin ",IMediaSeeking
필터 CLSID | CLSID_WAVEParser {D51BD5A1-7548-11cf-A520-0080C77EF58A}
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_UNLIKELY
카테고리 | CLSID_LegacyAmFilterCategory


WDM 비디오 캡춰 필터

WDM 비디오 캡춰 필터는 실제로는 커넬 모드 KsProxy 플러그 인이며, (아날로그 비디오 디코더라고도 불린다) 아날로그 캡춰 디바이스를 제어하는 WDM 드라이버의 프로퍼티 페이지와 COM 인터페이스를 제공한다. 물론, 어플리케이션의 시점으로부터는, 이것은 시스템 디바이스 열거자를 통해 발견 될 수 있는 단순한 이제(벌써) 1 개의 필터이다. KSProxy 를 베이스로 한 필터에서는, 필터의 프렌들리명은 그 아래의 드라이버에 의존하는 시스템 디바이스 열거자는 이 플러그 인을 사용하는 각 디바이스에 고유의 모니카를 돌려준다. 자세한 것은, 「디바이스와 필터의 열거」와「하드웨어 디바이스가 필터 그래프에 참가하는 방법」을 참조할것.

WDM 비디오 캡춰 필터 를 통해 공개되는 모든 디바이스는 이하에 설명되는 모든 인터페이스를 이행 한다. 개별의 디바이스가 어느 인터페이스를 지원 하는지를 확인하는 것은 어플리케이션의 책임이다.

필터 인터페이스 | 디바이스의 WDM 드라이버는, 다음의 1 개 또는 복수의 인터페이스를 지원 하고 있는 경우가 있다. IAMExtDevice ,IAMExtTransport ,IAMTimecodeReader ,IAMCameraControl ,IAMVideoProcAmp ,IAMAnalogVideoDecoder , IAMVideoCompression ,IAMVideoControl
입력 핀 미디어 타입 | 디바이스에 의존한다.
입력 핀인타페이스 | 디바이스에 의존한다.
출력 핀 미디어 타입 | 디바이스에 의존한다.
출력 핀인타페이스 | 디바이스에 의존한다 (비디오가 압축되고 있는 경우). IAMStreamControl 또는 IAMVideoCompression 를 포함한 경우가 있다.
필터 CLSID | 디바이스에 의존한다.
프로퍼티 페이지 CLSID | 디바이스에 의존한다.
플러그 인 실행 모듈 | kswdmcap.ax
메리트 | 디바이스에 의존한다.
카테고리 | CLSID_VideoInputDeviceCategory


WST CODEC

World Standard Teletext (WST)는 PAL 아날로그 TV 신호상에서 VBI 를 사용하는 데이터 송신의 유럽 규격이다. 문자 서비스와 데이터 서비스의 양쪽 모두가 이 규격으로 제공되고 있다. WST CODEC 는 로 VBI 샘플을 받아, (옵션으로서) Teletxt 샘플을 Tee/Sink-to-Sink 컨버터 경유로 캡춰 필터로부터 디코드하는 커넬 모드 필터이다. 이 CODEC 는 WST 디코더 필터로 디코드되어 포워드 에러 수정된 Teletxt 데이터를 디코드와 카피 양쪽 모두 혹은 한편을 한다. WST 디코더 는 다음에 오버레이 믹서에 보내는 비트 맵을 생성 한다.

WST CODEC 는 GrapEdit 내에서 "WDM Streaming VBI CODEC" 카테고리에 있다. 이것은 커넬 모드 필터이므로, 어플리케이션은 직접 co-create 할 수 없지만,디바이스와 필터의 열거 로 설명되고 있도록(듯이),시스템 디바이스 열거자 를 사용해 인스턴스화하지 않으면 안 된다.


WST 디코더

The WST 디코더 는 WST CODEC 로부터 디코드된 World Standard Teletext 데이터를 받아, Microsoft 가 제공하는 폰트를 사용해 오버레이 믹서 의 핀 2 에 비트 맵을 출력하는 커넬 모드 필터이다. 현재 서구의 언어는 규격화되고 있지만, Unicode˜ 폰트는 현재 제공되어 있지 않다. WST 디코더 에는 어플리케이션으로부터 호출해 가능한 인터페이스는 없다.

WST 디코더 는 GrapEdit 내에서 "WDM Streaming VBI CODEC" 카테고리에 있다. 이것은 커넬 모드 필터이므로, 어플리케이션은 직접 co-create 할 수 없지만,디바이스와 필터의 열거 로 설명되고 있도록(듯이),시스템 디바이스 열거자 를 사용해 인스턴스화하지 않으면 안 된다. 이 필터는 WST CODEC 의 출력 핀으로 ICaptureGraphBuilder2::RenderStream 를 호출하는 것에 의해 자동적으로 추가된다.


인터페이스

이 주제에는, Microsoft® DirectShow® COM 인터페이스의 레퍼런스 정보를 기재한다. 다양한 하드웨어, 파일 포맷, 및 스트림 조작을 지원 하기 위한(해), DirectShow 는 다수의 인터페이스를 이행 한다. 이러한 인터페이스의 일부는 어플리케이션으로 사용되어 그 외는 필터 및 다른 DirectShow 컴퍼넌트로 내부적으로 사용된다.

개개의 어플리케이션에서는 일부의 서브 세트만을 사용한다. 필요한 인터페이스는 어플리케이션의 성질에 따라서 다르다. 이하의 일람은, 어플리케이션 레벨의 인터페이스를 목적 마다 집계한 것이다.

  • 필터 그래프의 구축
  • 필터 그래프의 제어
  • 오디오의 캡춰와 렌더링
  • DVD
  • 비디오의 캡춰
  • 비디오의 편집
  • 파일의 encode와 디코드
  • 비디오의 렌더링, 확대 축소, 및 오버레이
  • TV 의 조정
  • 외부 디바이스의 제어

참조 :

  • DirectShow COM 인터페이스의 일람 (알파벳순서)
  • 필터
  • DirectShow 의 컴퍼넌트

필터 그래프의 구축

어플리케이션에서는, 이하의 인터페이스를 사용해 각종의 필터 그래프를 구축한다.

인터페이스 | 목적
ICaptureGraphBuilder2 | 비디오 캡춰용의 필터 그래프를 구축한다.
ICreateDevEnum | 이용 가능한 시스템 디바이스를 열거한다.
IDvdGraphBuilder | DVD 의 네비게이션 및 재생에 사용하는 필터 그래프를 구축한다.
IFilterGraph2 | 필터를 추가, 삭제, 또는 접속한다.
IFilterMapper2 | 유저의 시스템에 등록되어 있는 필터를 열거한다.
IGraphBuilder | 파일의 재생 또는 커스텀 유스에 사용하는 필터 그래프를 구축한다.
IGraphConfig | 필터 그래프를 동적으로 복구성 한다.
IGraphVersion | 그래프의 변경 시기를 판단한다.

필터 그래프의 제어

이하의 인터페이스는, 필터 그래프를 제어하는 메소드를 제공한다.

인터페이스 | 목적
IAMGraphStreams | 필터 그래프의 라이브 스트림의 동기를 잡는다.
IEnumFilters | 그래프의 필터를 열거한다.
IFilterChain | 필터 체인을 제어한다.
IMediaControl | 필터 그래프를 실행, 포즈, 및 정지한다 (그래프를 구축하는 Automation 호환의 메소드도 제공한다).
IMediaEventEx | 그래프내의 이벤트에 응답한다.
IMediaSeeking | 파일내의 시크를 실시한다.
IQueueCommand | 커멘드를 큐에 넣어 다음에 실행한다.
IVideoFrameStep | 비디오 스트림내의 스탭핑(Stepping)를 한다.

오디오의 캡춰와 렌더링

이하의 인터페이스는, 오디오의 캡춰 및 렌더링을 지원 한다.

인터페이스 | 목적
IAMAudioInputMixer | 단청의/스테레오, 믹싱 레벨, 빵 레벨, 라우드네스, 고음역, 저음역 등, 오디오 입력의 특성을 조정한다.
IAMDirectSound | 다른 어플리케이션에 포커스가 있을 때 사운드를 울릴지 어떨지, 어느 어플리케이션 윈도우를 사운드에 관련지을까 등, Microsoft DirectSound® 호환 디바이스의 설정을 제어한다.
IAMResourceControl | 오디오 디바이스를 사전에 확보한다.
IBasicAudio | 오디오의 프로퍼티를 설정한다.

DVD

인터페이스 | 목적
IDvdCmd | 커멘드가 시작 또는 완료할 때까지 DVD 네비게이터를 블록 한다.
IDvdControl2 | 가라오케를 포함한 DVD 비디오의 타이틀을 안내 및 재생한다.
IDvdGraphBuilder | 시스템 위에의 이용 가능한 소프트웨어 및 하드웨어로부터, DVD 비디오 재생에 사용하는 필터 그래프를 구축한다.
IDvdInfo2 | DVD 디스크의 각종 속성 또는 DVD 네비게이터 상태를 조회한다.
IDvdState | 유저 세션 상태를 디스크에 보존한다. 상태에는, 재생 위치, 페어 렌탈 락 레벨, 및 리젼이 포함된다.

비디오의 캡춰

이하의 인터페이스는, Microsoft® Windows® Driver Model (WDM) 디바이스, 또는 구래의 Microsoft® Video for Windows® (VfW) 디바이스를 사용한 비디오 캡춰를 지원 한다.

인터페이스 | 목적
IAMAnalogVideoDecoder | WDM 비디오 캡쳐 카드에 의한 비디오 신호의 디지털화를 제어한다.
IAMAnalogVideoEncoder | 하드웨어 비디오 엔코더를 제어한다.
IAMBufferNegotiation | 핀의 버퍼 할당을 제어한다.
IAMCopyCaptureFileProgress | 파일 카피 조작의 진행 상황을 받는 콜백 인터페이스.
IAMCrossbar | WDM 의 오디오 소스 또는 비디오 소스와 WDM 캡춰 디바이스의 사이의 하드웨어 접속을 확립한다.
IAMDroppedFrames | 캡춰 필터에 캡춰의 퍼포먼스를 조회한다.
IAMStreamControl | 개개의 스트림의 시작 타임 및 종료 타임을 제어한다.
IAMVfwCaptureDialogs | VFW 캡춰 드라이버의 다이알로그 박스를 표시한다.
IAMVideoControl | 캡춰 디바이스로부터의 화면을 제어한다.
IAMVideoProcAmp | 휘도, 콘트라스트, 색상, 포화, 감마, 선명도등의 비디오 신호 품질을 조정한다.
ICaptureGraphBuilder2 | 비디오 캡춰용의 필터 그래프를 구축한다.
IFileSinkFilter2 | 출력 파일의 이름 및 속성을 지정한다.
ISampleGrabber | 필터 그래프내를 지나는 미디어 샘플을 취득한다.

비디오의 편집

DES (DirectShow 편집 서비스)는, 이하의 인터페이스를 제공한다.

인터페이스 | 목적
IAMErrorLog | 에러 로그를 위한 콜백 인터페이스.
IAMSetErrorLog | 에러 로그를 설정 또는 취득한다.
IAMTimeline | 타임 라인의 프로퍼티를 설정 및 취득해, 타임 라인 오브젝트를 생성 한다.
IAMTimelineComp | 합성의 가상 트럭을 삽입 또는 취득한다.
IAMTimelineEffect | 이펙트의 우선 순위를 취득한다.
IAMTimelineEffectable | 타임 라인 오브젝트에 이펙트를 추가한다.
IAMTimelineGroup | 그룹의 프로퍼티를 설정 및 취득한다.
IAMTimelineObj | 타임 라인 오브젝트의 프로퍼티를 설정 및 취득한다.
IAMTimelineSplittable | 타임 라인 오브젝트를 분할한다.
IAMTimelineSrc | 소스의 프로퍼티를 설정 및 취득한다.
IAMTimelineTrack | 트럭의 프로퍼티를 설정 및 취득한다.
IAMTimelineTrans | 트란지션의 프로퍼티를 설정 및 취득한다.
IAMTimelineTransable | 타임 라인 오브젝트에 이행부를 추가한다.
IAMTimelineVirtualTrack | 가상 트럭의 프로퍼티를 설정 및 취득한다.
IMediaDet | 미디어 파일에 관한 정보를 취득한다.
IMediaLocator | 파일명을 검증한다.
IPropertySetter | 이펙트 또는 이행부의 프로퍼티를 설정한다.
IRenderEngine | 비디오 편집 프로젝트를 렌더링 한다.
ISmartRenderEngine | 스마트재압축을 사용해, 비디오 편집 프로젝트를 렌더링 한다.
IXml2Dex | XML (Extensible Markup Language)로 비디오 편집 프로젝트를 보존 및 로드한다.

파일의 encode와 디코드

인터페이스 | 목적
IAMMediaContent | 생성자나 타이틀등의 메타데이타를 스트림으로부터 취득한다.
IAMOpenProgress | 파일을 여는 처리의 진척 상황을 판정한다.
IAMParse | MPEG 스트림의 현재 위치의 해석 시간을 조회, 설정한다.
IAMStreamSelect | 재생하는 논리 스트림을 제어해, 거기에 관한 정보를 취득한다.
IAMVfwCompressDialogs | VFW CODEC 의 다이알로그 박스를 표시한다.
IAMVideoCompression | 비디오 압축의 파라미터를 설정한다.
IConfigAsfWriter | ASF 라이터 필터가 ASF (Advanced Streaming Format) 파일을 기입하는 방법을 제어한다.
IConfigAviMux | AVI Mux 필터가 AVI 파일을 기입하는 방법을 제어한다.
IConfigInterleaving | AVI Mux 필터가 AVI 파일을 기입할 때의 인터리브를 구성한다.
IDVEnc | DV 비디오 엔코더 필터의 encode 해상도를 설정한다.
IDVSplitter | 디지털 비디오 (DV) 스트림의 프레임을 다운 그레이드 한다.
IIPDVDec | DV 비디오 디코더 필터의 디코드 해상도를 설정한다.
IPersistMediaPropertyBag | AVI 스트림의 INFO 체크 및 DISP 체크를 설정, 취득한다.

비디오의 렌더링, 확대 축소, 및 오버레이

인터페이스 | 목적
IAMLine21Decoder | 자막 방송 정보 및 설정에 액세스 한다.
IAMOverlayFX | 비디오 표면에 오버레이 이펙트를 적용한다.
IAMVideoDecimationProperties | 비디오의 본래의 사이즈보다 비디오 윈도우가 작은 경우에, DirectShow 가 비디오 이미지를 확대 축소하는 방법을 제어한다.
IBasicVideo2 | 비디오의 프로퍼티를 설정한다.
IDDrawExclModeVideo | Microsoft® DirectDraw® 의 배타적인 전화면 모드로 비디오를 렌더링 한다.
IDDrawExclModeVideoCallback | 오버레이의 위치, 사이즈, 및 표시/비표시의 변경에 관한 통지를 받는 콜백 인터페이스.
IDirectDrawVideo | 지정된 DirectDraw 능력을 무효로 한다.
IDirectDrawMediaSample | 오버레이 믹서 필터가 할당한 DirectDraw 표면에 액세스 한다.
IFullScreenVideo | 풀 스크린 렌더링 필터를 제어한다.
IMixerPinConfig2 | 복수의 비디오 스트림을 믹싱 할 경우에,오버레이 믹서상에 비디오의 칼라 컨트롤을 설정한다.
IQualProp | 비디오 렌더러에 퍼포먼스 정보를 조회한다.
IVideoWindow | 비디오 윈도우의 프로퍼티를 설정한다.

TV 의 조정

인터페이스 | 목적
IAMTunerNotification | TV 튜너 필터로부터의 이벤트 통지를 받는 콜백 인터페이스.
IAMTVTuner | TV 튜너 디바이스를 제어한다.
IAMTVAudio | TV 튜너로부터의 오디오를 제어한다.
IAMTVAudioNotification | TV 튜너 카드로부터의 이벤트 통지를 받는 콜백 인터페이스.
IAMAnalogVideoDecoder | 수평 락의 표시를 포함한 디지털화 포맷의 선택과 디시타이저의 위상 동기의 시간 정수를 제어하는 메소드가 들어간다.

외부 디바이스의 제어

인터페이스 | 목적
IAMCameraControl | 카메라를 제어한다.
IAMExtDevice | VCR 나 캠코더등의 외부 디바이스를 제어한다.
IAMExtTransport | VCR 의 전송 기능 (재생, 포즈, 녹화, 빨리 감기, 권반환등)을 제어한다.
IAMTimecodeDisplay | SMPTE 타임 코드를 표시하는 디바이스에 프로퍼티를 설정한다.
IAMTimecodeGenerator | SMPTE 타임 코드를 생성하는 디바이스에 프로퍼티를 설정한다.
IAMTimecodeReader | 외부 디바이스로부터 SMPTE 타임 코드를 읽어낸다.


DirectShow COM 인터페이스의 일람 (알파벳순서)

이하는 DirectShow COM 인터페이스의 알파벳순서의 일람이다.

  • IAMAnalogVideoDecoder
  • IAMAnalogVideoEncoder
  • IAMAudioInputMixer
  • IAMBufferNegotiation
  • IAMCameraControl
  • IAMClockAdjust
  • IAMCollection
  • IAMCopyCaptureFileProgress
  • IAMCrossbar
  • IAMDirectSound
  • IAMDroppedFrames
  • IAMErrorLog
  • IAMExtDevice
  • IAMExtTransport
  • IAMFilterMiscFlags
  • IAMGraphStreams
  • IAMLatency
  • IAMLine21Decoder
  • IAMMediaContent
  • IAMOpenProgress
  • IAMOverlayFX
  • IAMParse
  • IAMPushSource
  • IAMResourceControl
  • IAMSetErrorLog
  • IAMStreamConfig
  • IAMStreamControl
  • IAMStreamSelect
  • IAMTimecodeDisplay
  • IAMTimecodeGenerator
  • IAMTimecodeReader
  • IAMTimeline
  • IAMTimelineComp
  • IAMTimelineEffect
  • IAMTimelineEffectable
  • IAMTimelineGroup
  • IAMTimelineObj
  • IAMTimelineSplittable
  • IAMTimelineSrc
  • IAMTimelineTrack
  • IAMTimelineTrans
  • IAMTimelineTransable
  • IAMTimelineVirtualTrack
  • IAMTuner
  • IAMTunerNotification
  • IAMTVAudio
  • IAMTVAudioNotification
  • IAMTVTuner
  • IAMVfwCaptureDialogs
  • IAMVfwCompressDialogs
  • IAMVideoAccelerator
  • IAMVideoAcceleratorNotify
  • IAMVideoCompression
  • IAMVideoControl
  • IAMVideoDecimationProperties
  • IAMVideoProcAmp
  • IAsyncReader
  • IBaseFilter
  • IBasicAudio
  • IBasicVideo
  • IBasicVideo2
  • ICaptureGraphBuilder2
  • IConfigAviMux
  • IConfigInterleaving
  • ICreateDevEnum
  • IDDrawExclModeVideo
  • IDDrawExclModeVideoCallback
  • IDecimateVideoImage
  • IDeferredCommand
  • IDirectDrawVideo
  • IDirectDrawMediaSample
  • IDirectDrawMediaSampleAllocator
  • IDistributorNotify
  • IDMOWrapperFilter
  • IDvdCmd
  • IDvdControl2
  • IDvdGraphBuilder
  • IDvdInfo2
  • IDvdState
  • IDVEnc
  • IDVSplitter
  • IEnumFilters
  • IEnumMediaTypes
  • IEnumPIDMap
  • IEnumPins
  • IEnumStreamIdMap
  • IFileSinkFilter
  • IFileSinkFilter2
  • IFileSourceFilter
  • IFilterChain
  • IFilterGraph
  • IFilterGraph2
  • IFilterInfo
  • IFilterMapper2
  • IFindCompressorCB
  • IFullScreenVideo
  • IGraphBuilder
  • IGraphConfig
  • IGraphConfigCallback
  • IGraphVersion
  • IIPDVDec
  • IKsPropertySet
  • IMediaControl
  • IMediaDet
  • IMediaEvent
  • IMediaEventEx
  • IMediaEventSink
  • IMediaFilter
  • IMediaLocator
  • IMediaPosition
  • IMediaPropertyBag
  • IMediaSample
  • IMediaSample2
  • IMediaSeeking
  • IMediaTypeInfo
  • IMemAllocator
  • IMemInputPin
  • IMixerPinConfig
  • IMixerPinConfig2
  • IMPEG2Demultiplexer
  • IMPEG2PIDMap
  • IMPEG2StreamIdMap
  • IOverlay
  • IOverlayNotify
  • IOverlayNotify2
  • IPersistMediaPropertyBag
  • IPin
  • IPinConnection
  • IPinFlowControl
  • IPinInfo
  • IPropertySetter
  • IQualityControl
  • IQualProp
  • IQueueCommand
  • IReferenceClock
  • IRegFilterInfo
  • IRenderEngine
  • IResourceConsumer
  • IResourceManager
  • ISampleGrabber
  • ISampleGrabberCB
  • ISeekingPassThru
  • ISmartRenderEngine
  • IStreamBuilder
  • IUnknown
  • IVideoFrameStep
  • IVideoWindow
  • IVPBaseConfig
  • IVPBaseNotify
  • IVPConfig
  • IVPNotify
  • IVPNotify2
  • IXml2Dex


IAMAnalogVideoDecoder 인터페이스

IAMAnalogVideoDecoder 인터페이스는,WDM 비디오 캡춰 필터로 이행 된다. 이 인터페이스는, WDM 준거의 비디오 캡쳐 카드로 처리되는 비디오의 디지털화에 관한 정보를 지정 및 취득하는 것이다. 이 인터페이스는, 디지털화 방식을 선택하는 메소드, 수평 락 상태를 나타내는 메소드, 및 디시타이저의 위상 동기 루프 (PLL)에 있어서의 시간 정수를 제어하는 메소드를 갖추고 있다.

어플리케이션은 이 인터페이스를 사용해, 지원 되고 있는 비디오 방식의 취득과 설정, 수평 동기가 락 되고 있는지 어떤지의 판별, 디지털화 방식에 관한 그 외의 각종 정보의 취득 등, 다양한 비디오 디지털화 정보를 선택 및 제어한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMAnalogVideoDecoder 메소드 | 설명
get_AvailableTVFormats | 현재 이용할 수 있는 아날로그 비디오 방식을 취득한다.
put_TVFormat | 현재의 아날로그 비디오 방식을 설정한다.
get_TVFormat | 현재의 아날로그 비디오 방식을 취득한다.
get_HorizontalLocked | 수평 동기가 락 되고 있는지 어떤지를 판별한다.
put_VCRHorizontalLocking | VCR 에의 접속 상태를 설정한다 (PLL 타이밍을 변경한다).
get_VCRHorizontalLocking | 수평 락이 설정되어 있는지 어떤지를 판별한다.
get_NumberOfLines | 현재의 비디오 신호내의 주사선의 수를 취득한다.
put_OutputEnable | 출력 버스를 유효 또는 무효로 한다.
get_OutputEnable | 출력 버스가 유효한가 어떤가를 판별한다.

IAMAnalogVideoDecoder::get_AvailableTVFormats

IAMAnalogVideoDecoder 인터페이스

현재 이용할 수 있는 아날로그 비디오 방식을 취득한다.

구문

HRESULT get_AvailableTVFormats(
    long *lAnalogVideoStandard
    );

파라미터

lAnalogVideoStandard
[out] 이용할 수 있는 아날로그 비디오 방식을 나타내는 정수에의 포인터. AnalogVideoStandard 열거형으로 정의되는 각종의 값을, 비트 OR 로 묶은 논리합이 된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMAnalogVideoDecoder::get_HorizontalLocked

IAMAnalogVideoDecoder 인터페이스

수평 동기가 락 되고 있는지 어떤지를 판별한다.

구문

HRESULT get_HorizontalLocked(
    long *plLocked
    );

파라미터

plLocked
[out] 수평 동기가 락 되고 있는지 어떤지를 나타내는 값에의 포인터. TRUE 는 수평 동기가 락 되고 있는 것을 나타내, FALSE 는 락되어 있지 않은 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMAnalogVideoDecoder::get_NumberOfLines

IAMAnalogVideoDecoder 인터페이스

비디오 신호내의 주사선의 수를 취득한다.

구문

HRESULT get_NumberOfLines(
    long *plNumberOfLines
    );

파라미터

plNumberOfLines
[out] 비디오 신호내의 주사선의 수에의 포인터. NTSC 의 경우, 이 값은 일반적으로 525 이며, PAL/SECAM 의 경우는 보통 625 이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMAnalogVideoDecoder::get_OutputEnable

IAMAnalogVideoDecoder 인터페이스

출력 버스가 유효 또는 무효라는 점을 판별한다.

구문

HRESULT get_OutputEnable(
    long *plOutputEnable
    );

파라미터

plOutputEnable
[out] 출력 버스가 유효한가 어떤가를 나타내는 값에의 포인터. TRUE 는 유효한 것을 나타내, FALSE 는 무효라는 점을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMAnalogVideoDecoder::get_TVFormat

IAMAnalogVideoDecoder 인터페이스

현재의 아날로그 비디오 방식을 취득한다.

구문

HRESULT get_TVFormat(
    long *plAnalogVideoStandard
    );

파라미터

plAnalogVideoStandard
[out] 지원 되는 아날로그 비디오 방식을 정의하고 있는 AnalogVideoStandard 열거형에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMAnalogVideoDecoder::get_VCRHorizontalLocking

IAMAnalogVideoDecoder 인터페이스

수평 락이 설정되어 있는지 어떤지를 판별한다.

구문

HRESULT get_VCRHorizontalLocking(
    long *plVCRHorizontalLocking
    );

파라미터

plVCRHorizontalLocking
[out] 수평 락이 설정되어 있는지 어떤지를 나타내는 값에의 포인터. TRUE 는 수평 락이 설정되어 있는 것을 나타낸다. 그 이외의 경우는 FALSE 가 된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

테이프의 차이, 노이즈, 또는 데이터 탈락, 및 기록 메카니즘의 기계적인 특성이 원인으로, VCR 의 동기 타이밍이 맞지 않는 것이 있다. 수평 락을 설정 하면 디코더의 기준이 완화되어 그 결과, 동기가 잡기 쉬워진다.

IAMAnalogVideoDecoder::put_OutputEnable

IAMAnalogVideoDecoder 인터페이스

출력 버스를 유효 또는 무효로 한다.

구문

HRESULT put_OutputEnable(
    long lOutputEnable
    );

파라미터

lOutputEnable
[in] 출력 버스가 유효한가 어떤가를 나타내는 값. TRUE 는 유효를 지정해, FALSE 는 무효를 지정한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMAnalogVideoDecoder::put_TVFormat

IAMAnalogVideoDecoder 인터페이스

지원 되고 있는 아날로그 비디오 방식의 1 개를 현재의 방식으로 설정한다.

구문

HRESULT put_TVFormat(
    long lAnalogVideoStandard
    );

파라미터

lAnalogVideoStandard
[in] 지원 되는 아날로그 비디오 방식을 정의하고 있는 AnalogVideoStandard 열거형의 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMAnalogVideoDecoder::put_VCRHorizontalLocking

IAMAnalogVideoDecoder 인터페이스

수평 락을 설정할지 어떨지를 지정한다.

구문

HRESULT put_VCRHorizontalLocking(
    long lVCRHorizontalLocking
    );

파라미터

lVCRHorizontalLocking
[in] 수평 락을 설정할지 어떨지를 나타내는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

테이프의 차이, 노이즈, 또는 데이터 탈락, 및 기록 메카니즘의 기계적인 특성이 원인으로, VCR 의 동기 타이밍이 맞지 않는 것이 있다. 이 메소드에 의해 디코더의 기준이 완화되어 그 결과, 동기가 잡기 쉬워진다.


IAMAnalogVideoEncoder 인터페이스

IAMAnalogVideoEncoder 인터페이스는, 어플리케이션이 데이터를 디스크에 스트림 해, 이것을 비디오 테잎에 돌려 보내는 경우에, 비디오 캡춰 처리에 있어서의 하드웨어 비디오 엔코더에 의해 이행 된다. 이 인터페이스는, 비디오 방식을 설정하는 메소드와 자막 방송 및 카피 보호를 유효 또는 무효로 하는 메소드를 갖추고 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMAnalogVideoEncoder 메소드 | 설명
get_AvailableTVFormats | 엔코더가 지원 하는 아날로그 비디오 방식 (NTSC/M, PAL/B, SECAM/K1 등)을 취득한다.
put_TVFormat | 엔코더를 특정의 아날로그 비디오 방식으로 설정한다.
get_TVFormat | 엔코더에 현재 설정되어 있는 아날로그 비디오 방식을 취득한다.
put_CopyProtection | 엔코더의 카피 보호의 레벨을 설정한다.
get_CopyProtection | 카피 보호가 현재 유효한가 어떤가를 판별한다.
put_CCEnable | 자막 방송을 유효 또는 무효로 한다.
get_CCEnable | 자막 방송이 현재 유효한가 어떤가를 판별한다.

IAMAnalogVideoEncoder::get_AvailableTVFormats

IAMAnalogVideoEncoder 인터페이스

엔코더가 지원 하는 아날로그 비디오 방식 (NTSC/M, PAL/B, SECAM/K1 등)을 취득한다.

구문

HRESULT get_AvailableTVFormats(
    long *lAnalogVideoStandard
);

파라미터

lAnalogVideoStandard
[out] AnalogVideoStandard 열거형으로 정의되는 값의 임의의 편성을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다.

IAMAnalogVideoEncoder::get_CCEnable

IAMAnalogVideoEncoder 인터페이스

자막 방송이 현재 유효한가 어떤가를 판별한다.

구문

HRESULT get_CCEnable(
    long *lCCEnable
);

파라미터

lCCEnable
[out] 엔코더의 자막 방송의 현재 상태를 받는 변수에의 포인터. 1 은 자막 방송이 유효한 것을 나타내, 0 은 자막 방송이 무효라는 점을 나타낸다.

반환값

HRESULT 값을 돌려준다.

IAMAnalogVideoEncoder::get_CopyProtection

IAMAnalogVideoEncoder 인터페이스

엔코더의 카피 보호가 현재 유효한가 어떤가를 판별한다.

구문

HRESULT get_CopyProtection(
    long *lVideoCopyProtection
);

파라미터

lVideoCopyProtection
[out] 현재의 카피 보호 레벨을 받는 변수에의 포인터. 카피 보호 레벨은,AM_COPY_MACROVISION_LEVEL 열거형으로 정의된다.

반환값

HRESULT 값을 돌려준다.

IAMAnalogVideoEncoder::get_TVFormat

IAMAnalogVideoEncoder 인터페이스

엔코더에 현재 설정되어 있는 아날로그 비디오 방식 (NTSC/M, PAL/B, SECAM/K1 등)을 취득한다.

구문

HRESULT get_TVFormat(
    long *plAnalogVideoStandard
);

파라미터

plAnalogVideoStandard
[out] 엔코더의 현재의 비디오 방식을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

유효값과 그 의미는,AnalogVideoStandard 열거형으로 정의된다.

IAMAnalogVideoEncoder::put_CCEnable

IAMAnalogVideoEncoder 인터페이스

자막 방송을 유효 또는 무효로 한다.

구문

HRESULT put_CCEnable(
    long lCCEnable
);

파라미터

lCCEnable
[in] 자막 방송을 온 또는 오프로 전환하는 값. 1 은 "온 " 를 나타내, 0 은 "오프 " 를 나타낸다.

반환값

HRESULT 값을 돌려준다.

IAMAnalogVideoEncoder::put_CopyProtection

IAMAnalogVideoEncoder 인터페이스

엔코더의 카피 보호 레벨을 설정한다.

구문

HRESULT put_CopyProtection(
    long lVideoCopyProtection
);

파라미터

lVideoCopyProtection
[in] 설정하는 카피 보호 레벨을 나타내는 값. 카피 보호 레벨은,AM_COPY_MACROVISION_LEVEL 열거형으로 정의된다.

반환값

HRESULT 값을 돌려준다.

IAMAnalogVideoEncoder::put_TVFormat

IAMAnalogVideoEncoder 인터페이스

엔코더를 특정의 아날로그 비디오 방식 (NTSC/M, PAL/B, SECAM/K1 등)으로 설정한다.

구문

HRESULT put_TVFormat(
    long lAnalogVideoStandard
);

파라미터

lAnalogVideoStandard
[in] 엔코더가 설정되는 비디오 방식. 지정할 수 있는 값은 AnalogVideoStandard 열거형으로 정의된다.

반환값

HRESULT 값을 돌려준다.


IAMAudioInputMixer 인터페이스

IAMAudioInputMixer 인터페이스는 Audio Capture Filter 의 각 입력 핀으로 이행 되어 필터에 레벨, 빵, 및 이퀼라이저를 지정한다. "Line in" 나 "Microphone" 와 같은 각 핀의 이름은 입력의 종류를 나타낸다.

오디오 캡춰 필터의 기능은, 관련지을 수 있고 있는 특정의 하드웨어 디바이스에 대응하므로, 디바이스가 지원 하지 않는 인터페이스 메소드를, 필터가 지원 할 수 없다.

어플리케이션 개발자 : 이 인터페이스를 사용해 사운드 카드의 아날로그 입력에 액세스 해, 특정의 입력의 믹싱, 단청의 또는 스테레오의 사용, 믹싱 레벨, 빵 레벨, 라우드네스, 고음역, 저음역의 각종 설정 등, 오디오 캡춰 필터에 있어서의 오디오 입력 특성을 조정할 수 있다.

필터 개발자 : 오디오 캡춰 필터의 각 입력 핀으로 이 인터페이스를 이행 한다. 오디오 캡춰 필터 자체에 이 인터페이스를 이행 해, 오디오 믹싱 후의 전체의 녹음 레벨과 빵을 제어할 수도 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMAudioInputMixer 메소드 | 설명
put_Enable | 믹싱에 있어서의 입력을 유효 또는 무효로 한다
get_Enable | 입력이 유효한가 어떤가를 취득한다.
put_Mono | 입력의 모든 채널을 1 개의 단청의 신호에 정리한다.
get_Mono | 입력의 모든 채널이 1 개의 단청의 신호에 정리하고 있는지 어떤지를 취득한다.
put_MixLevel | 입력의 녹음 레벨을 설정한다.
get_MixLevel | 입력의 녹음 레벨을 취득한다.
put_Pan | 입력의 빵을 설정한다.
get_Pan | 입력의 빵을 취득한다.
put_Loudness | 입력의 라우드네스콘트로르를 온 또는 오프로 한다.
get_Loudness | 입력의 라우드네스콘트로르의 설정을 취득한다.
put_Treble | 입력의 고음역의 에코라이징을 설정한다.
get_Treble | 입력의 고음역의 에코라이징을 취득한다.
get_TrebleRange | 입력의 고음역의 범위를 취득한다.
put_Bass | 입력의 저음역의 에코라이징을 설정한다.
get_Bass | 입력의 저음역의 에코라이징을 취득한다.
get_BassRange | 입력의 저음역의 범위를 취득한다.

IAMAudioInputMixer::get_Bass

IAMAudioInputMixer 인터페이스

이 입력의 저음역의 에코라이징을 취득한다.

구문

HRESULT get_Bass(
  double *pBass
  );

파라미터

pBass
[in] 데시벨 단위의 저음역게인 (부의 값은 감쇠를 나타낸다)을 나타내는 double 타입의 변수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

IAMAudioInputMixer::get_BassRange

IAMAudioInputMixer 인터페이스

이 입력의 저음역의 범위를 취득한다.

구문

HRESULT get_BassRange(
  double *pRange
  );

파라미터

pRange
[out, retval] put_Bass 로 지정되는 저음역의 범위내의 최대치를 나타내는 double 타입의 변수에의 포인터. 예를 들어, 6.0 은 –6. 0 에서 6.0 의 범위의 값이 유효한 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

IAMAudioInputMixer::get_Enable

IAMAudioInputMixer 인터페이스

입력이 유효한가 어떤가를 취득한다.

구문

HRESULT get_Enable(
  BOOL *pfEnable
  );

파라미터

pfEnable
[in] 입력의 믹싱이 유효한가 어떤가를 나타내는 BOOL 타입의 변수에의 포인터. TRUE 는 입력이 유효한 것을 나타내, FALSE 는 입력이 무효라는 점을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 정보를 취득할 수 없다.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

IAMAudioInputMixer::get_Loudness

IAMAudioInputMixer 인터페이스

입력의 라우드네스콘트로르의 설정을 취득한다.

구문

HRESULT get_Loudness(
  int *pfLoudness
  );

파라미터

pfLoudness
[in] 라우드네스콘트로르가 온 또는 오프인 것을 나타내는 int 타입의 변수에의 포인터. TRUE 는 온을 나타내, FALSE 는 오프를 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 에러.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
NOERROR | 성공.

IAMAudioInputMixer::get_MixLevel

IAMAudioInputMixer 인터페이스

이 입력의 녹음 레벨을 취득한다.

구문

HRESULT get_MixLevel(
  double *pLevel
  );

파라미터

[out] pLevel
녹음 레벨을 나타내는 변수에의 포인터. 값은 0 (오프)에서 1 (최대 볼륨)의 범위이다. AMF_AUTOMATICGAIN (-0x0001)는, 이것이 지원 되고 있는 경우, 레벨의 자동조정을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 녹음 레벨의 취득 에러.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

IAMAudioInputMixer::get_Mono

IAMAudioInputMixer 인터페이스

입력의 모든 채널이 1 개의 단청의 신호에 정리하고 있는지 어떤지를 취득한다.

구문

HRESULT get_Mono(
  BOOL *pfMono
  );

파라미터

pfMono
[in] 단청의가 유효한가 어떤가를 나타내는 BOOL 타입의 변수에의 포인터. TRUE 는 단청의가 유효한 것을 나타내, FALSE 는 단청의가 무효라는 점을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 단청의 컨트롤의 취득 에러.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

IAMAudioInputMixer::get_Pan

IAMAudioInputMixer 인터페이스

이 입력의 빵 레벨을 취득한다.

구문

HRESULT get_Pan(
  double *pPan
  );

파라미터

pPan
[in] 빵 레벨을 나타내는 double 타입의 변수에의 포인터. 유효한 레벨은 –1 로부터 1 의 범위이다. 값의 의미는 다음과 같다.
–1 | 좌단
0 | 중앙
1 | 우단

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 빵 레벨의 취득 에러.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 빵 할 수 없는: 스테레오가 아니다.
NOERROR | 성공.

IAMAudioInputMixer::get_Treble

IAMAudioInputMixer 인터페이스

이 입력의 고음역의 에코라이징을 취득한다.

구문

HRESULT get_Treble(
  double *pTreble
  );

파라미터

pTreble
[in] 데시벨 단위의 고음역게인 (부의 값은 감쇠를 나타낸다)을 나타내는 double 타입의 변수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

IAMAudioInputMixer::get_TrebleRange

IAMAudioInputMixer 인터페이스

이 입력의 고음역의 범위를 취득한다.

구문

HRESULT get_TrebleRange(
  double *pRange
  );

파라미터

pRange
[out, retval] put_Treble 로 지정되는 고음역의 범위내의 최대치를 나타내는 double 타입의 변수에의 포인터. 예를 들어, 6.0 은 –6. 0 에서 6.0 의 범위의 값이 유효한 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

IAMAudioInputMixer::put_Bass

IAMAudioInputMixer 인터페이스

이 입력의 저음역의 에코라이징을 설정한다.

구문

HRESULT put_Bass(
  double Bass
  );

파라미터

Bass
[in] 데시벨 단위의 게인 (부의 값은 감쇠를 나타낸다)을 나타내는 double 타입의 변수.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 인수가 무효. get_BassRange 로 지정되는 범위에 없으면 안 된다.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

주의

녹음전에 Bass 로 지정되는 데시벨수만큼 신호의 저음역의 증폭 또는 감쇠를 한다.

IAMAudioInputMixer::put_Enable

IAMAudioInputMixer 인터페이스

믹싱에 있어서의 입력을 유효 또는 무효로 한다.

구문

HRESULT put_Enable(
  BOOL fEnable
  );

파라미터

fEnable
[in] 입력을 유효 또는 무효로 하는지를 나타내는 BOOL 타입의 변수. TRUE 는 입력을 유효하게 해, FALSE 는 입력을 무효로 한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 입력의 유효화 또는 무효화가 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 입력의 유효화 또는 무효화가 성공.

주의

무효의 경우, 이 입력이 녹음 신호의 일부로서 믹싱 될 것은 없다.

IAMAudioInputMixer::put_Loudness

IAMAudioInputMixer 인터페이스

이 입력의 라운드네스콘트로르를 온 또는 오프로 한다.

구문

HRESULT put_Loudness(
  BOOL fLoudness
  );

파라미터

fLoudness
[in] 라우드네스콘트로르가 온인가 어떤가를 나타내는 BOOL 타입의 변수. TRUE 는 라우드네스콘트로르를 온으로 설정해, FALSE 는 라우드네스콘트로르를 오프로 설정한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 라우드네스콘트로르의 설정이 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

주의

IAMAudioInputMixer::put_Loudness 에 의해, 녹음전에 저음역량 신호의 저음역이 증폭되어 작은 소리의 저음역사운드나 그 외의 사운드가 들리지 않는다고 하는 상태가 보정된다.

IAMAudioInputMixer::put_MixLevel

IAMAudioInputMixer 인터페이스

이 입력의 녹음 레벨을 설정한다.

구문

HRESULT put_MixLevel(
  double Level
  );

파라미터

Level
녹음 레벨을 나타내는 double 타입의 변수. 값은 0 (오프)에서 1 (최대 볼륨)의 범위이다. AMF_AUTOMATICGAIN (-0x0001)는, 이것이 지원 되고 있는 경우, 레벨의 자동조정을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 볼륨의 설정 에러.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 녹음 레벨은 0 에서 1 의 범위가 아니면 안된다.
E_NOTIMPL | 자동 게인은 현재 이행되어 있지 않다.
NOERROR | 성공.

IAMAudioInputMixer::put_Mono

IAMAudioInputMixer 인터페이스

입력의 모든 채널을 1 개의 단청의 신호에 정리한다.

구문

HRESULT put_Mono(
  BOOL fMono
  );

파라미터

fMono
[in] 단청의 신호 또는 멀티 채널 신호를 나타내는 BOOL 타입의 변수. TRUE 는 단청의를 나타내, FALSE 는 멀티 채널을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 단청의 컨트롤의 설정 에러.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

주의

단청의 모드로 설정되어 있는 경우, 이 입력을 스테레오 녹음 하면, 양쪽 모두의 채널에 같은 데이터가 저장 된다. 왼쪽 신호와 오른쪽 신호를 맞춘 것을 얻을 수 있다.

IAMAudioInputMixer::put_Pan

IAMAudioInputMixer 인터페이스

이 입력의 빵을 설정한다.

구문

HRESULT put_Pan(
  double Pan
  );

파라미터

Pan
[in] 빵 레벨을 나타내는 double 타입의 변수. Pan 의 유효값은,-1 으로부터 1 의 범위이다. 값의 의미는 다음과 같다.
-1 | 좌단
0 | 중앙
1 | 우단

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 볼륨의 설정 에러.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 빵 레벨은 -1 으로부터 1 의 범위가 아니면 안된다.
E_NOTIMPL | 빵 할 수 없는: 스테레오가 아니다.
NOERROR | 성공.

주의

입력의 빵을 좌단으로 설정 하면, 입력의 신호가 스테레오 녹음의 왼쪽 채널에게만 설정된다. 단청의 녹음에서는 빵의 효과는 없다.

IAMAudioInputMixer::put_Treble

IAMAudioInputMixer 인터페이스

이 입력의 고음역의 에코라이징을 설정한다.

구문

HRESULT put_Treble(
  [in] double Treble
  );

파라미터

Treble
[in] 데시벨 단위의 게인 (부의 값은 감쇠를 나타낸다)을 나타내는 double 타입의 변수.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 인수가 무효. get_TrebleRange 로 지정되는 범위에 없으면 안 된다.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 성공.

주의

이 메소드에 의해, 녹음전으로 지정의 데시벨수만큼 신호의 고음역의 증폭 또는 감쇠를 한다.


IAMBufferNegotiation 인터페이스

IAMBufferNegotiation 인터페이스는, 핀 중(안)에서도 특히 캡춰 필터내의 핀에 대해 이행 된다. 이것에 의해 어플리케이션은, 핀에 있어서의 버퍼의 할당 처리를 제어할 수 있다.

전자 회의 어플리케이션에서는, 이 인터페이스를 사용해 최소의 버퍼수를 지정한다. 이것에 의해, 저속인 캡춰 환경이나 디스크에의 기입을 하는 환경에서의, 정보의 버퍼링에 의한 리소스의 헛됨을 막을 수가 있다.

어플리케이션이, 캡춰 한 오디오를 출력 디바이스에 송신하는 것에 의해 오디오 프리뷰를 실행하고 있어, 지연 시간이 너무 크다고 생각되는 경우는, 버퍼수를 줄여 본다.

IAMBufferNegotiation::SuggestAllocatorProperties 메소드는, 사용하는 allocater의 카운트, 사이즈, alignment, 및 프레픽스의 프로퍼티로 구성되는 ALLOCATOR_PROPERTIES 구조체를 지원 한다. 보통은,ALLOCATOR_PROPERTIES 구조체의 cBuffers 멤버만을 설정한다. 이것은, 지정의 allocater의 버퍼수에 상당한다. 그 외의 모든 프로퍼티에 대해서는, 부의 값을 지정하는 것으로, 캡춰 하드웨어 자체의 디폴트값이 사용된다.

cBuffers 에 대해서 부의 값을 지정 하면, allocater가 필요로 할 뿐(만큼)의 버퍼수의 할당이 시도된다. 그 개수는, 이용 가능한 리소스와 캡춰 frame rate에 따라서 다르다. 큰 값을 지정 하면, 시스템으로 이용 가능한 메모리를 최고로, 보다 많은 버퍼의 할당이 allocater에 의해 시도된다. 버퍼수의 할당이 적으면 경우에 따라서는 드롭 프레임이 발생한다. 전자 회의 어플리케이션에서는, 많은 경우, 이 값을 작은 값으로 설정하는 것이 바람직하다. 예를 들어, 네트워크가, 지정의 비디오 방식과 해상도에서는 2 프레임/초 (fps)의 전송 속도만을 지원 하는 경우는, 2 라고 하는 값이 적절한 설정이다.

어플리케이션에서는,IAMBufferNegotiation::GetAllocatorProperties 메소드를 호출해, 사용하고 있는 allocater의 프로퍼티를 취득할 수 있다.

필터 개발자: IMemInputPin 인터페이스를 사용해 핀을 다른 핀에 접속해, 필터간에 미디어 샘플을 트랜스폴트 할 경우에 사용하는 버퍼 설정을 어플리케이션이 할당하는 경우는, 이 인터페이스를 이행 한다. 어플리케이션이 정확한 버퍼 설정을 지정할 수 있도록(듯이) 하기 위해서는, 모든 캡춰 필터가 이 인터페이스를 지원 할 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMBufferNegotiation 메소드 | 설명
SuggestAllocatorProperties | ALLOCATOR_PROPERTIES 구조체로 설정되어 있는 allocater의 버퍼 프로퍼티를 사용하는 것을, 핀에 대해서 지정한다.
GetAllocatorProperties | 핀이 사용하는, allocater의 프로퍼티를 취득한다.

IAMBufferNegotiation::GetAllocatorProperties

IAMBufferNegotiation 인터페이스

핀이 사용하고 있는, allocater의 프로퍼티를 취득한다.

구문

HRESULT GetAllocatorProperties(
  ALLOCATOR_PROPERTIES *pprop
  );

파라미터

pprop
[out] ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다. 유효한 에러 코드는, 다음과 같다.

E_FAIL | 실패.
E_POINTER | NULL 포인터.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

이 메소드를 호출하는 것은, 핀이 접속한 후에 한정된다.

참조

SuggestAllocatorProperties

IAMBufferNegotiation::SuggestAllocatorProperties

IAMBufferNegotiation 인터페이스

ALLOCATOR_PROPERTIES 구조체로 설정되어 있는 allocater의 버퍼 프로퍼티를 사용하는 것을, 핀에 대해서 지정한다.

구문

HRESULT SuggestAllocatorProperties(
  const ALLOCATOR_PROPERTIES *pprop
  );

파라미터

pprop
[in] ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다. 유효한 에러 코드는, 다음과 같다.

E_FAIL | 실패. (지정의 프로퍼티를 사용할 수 없었다. )
E_POINTER | NULL 포인터.
E_UNEXPECTED | 예기치 못한 실패.
VFW_E_ALREADY_CONNECTED | 핀은 접속이 끝난 상태이다.

주의

어플리케이션에서는, 2 개의 핀을 접속하기 전에 이 함수를 호출할 필요가 있다. 이 메소드를 호출하기 전에 핀이 접속되고 있는 경우, 필터 그래프는 버퍼를 이미 결정하고 있어 어플리케이션이 이것을 사전에 할당하는 것은 안개는 할 수 없다.

어플리케이션에서는, 접속하는 양쪽 모두의 핀에 대해 이 메소드를 호출해, 다른 핀이 어플리케이션의 요구를 고쳐 쓰는 것이 없게 해야 한다. 다만, 한편의 핀이 이 인터페이스를 지원 하고 있지 않는 경우는, 1 회의 호출로 충분하다.

ALLOCATOR_PROPERTIES 구조 체내의 임의의 요소에 대해서 부의 값을 사용 하면, 프로퍼티는 디폴트값으로 설정된다.

참조

IAMBufferNegotiation::GetAllocatorProperties


IAMCameraControl 인터페이스

IAMCameraControl 인터페이스는, 카메라에 대한 로컬 제어 또는 리모트 제어를 제공한다.

이 인터페이스는, 줌, 빵, 짜, 또는 셔터 스피드등의 디바이스 제어를 갖추고 있는, 카메라 디바이스를 제어하는 필터를 대상으로, Microsoft® DirectShow® 중(안)에서 이행 된다. WDM 캡춰 드라이버는, 관련하는 커넬 스트리밍 프로퍼티 세트를 지원 하고 있는 경우, KsProxy.ax 에 있어서의 이 인터페이스를 자동적으로 사용하므로 주의 해야 한다.

어플리케이션은, 이 인터페이스를 사용해, 줌, 빵, 짜, 또는 셔터 스피드등의 디바이스 설정을 제어한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMCameraControl 메소드 | 설명
GetRange | 지정의 카메라 프로퍼티의 범위에 관련지을 수 있고 있는 값을 취득한다.
Set | 카메라 프로퍼티를 설정한다.
Get | 특정의 카메라 제어 프로퍼티의 값을 취득한다.

IAMCameraControl::Get

IAMCameraControl 인터페이스

특정의 카메라 제어 프로퍼티의 값을 취득한다.

구문

HRESULT Get (
     long Property,
     long *lValue,
     long *Flags
    );

파라미터

Property
[in] 조회하는 CameraControlProperty 열거형의 프로퍼티를 지정하는 값.
lValue
[out] 지정의 프로퍼티의 취득값에의 포인터. 유효한 범위와 값에 대해서는, 「주의」를 참조할것.
Flags
[out] 카메라 프로퍼티가 자동 또는 수동인 것을 나타내는,CameraControlFlags 열거형의 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

CameraControlProperty 열거형으로 나타내지는 각 프로퍼티는, 자동 또는 수동의 설정을 가질 수가 있다. Flags 파라미터에 CameraControlFlags 열거형의 CameraControl_Flags_Auto 가 설정되어 있는 경우,lValue 파라미터는 무시된다. lValue 의 범위와 의미는, 조회하는 프로퍼티에 의해 각각 다르다. 다음의 표는, 유효한 값을 나타내고 있다.

프로퍼티 | lValue 의 범위와 의미
Pan | 빵의 설정을 지정하는 값 (번단위). 값은 –180 로부터 +180 의 범위에서, 디폴트값은 0 이다. 정의 값은 원점으로부터 우회전 (위로부터 보았을 경우, 카메라가 우회전으로 회전한다)을 나타내, 부의 값은 원점에서 왼쪽 회전을 나타낸다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다.
Tilt | 틸트의 설정을 지정하는 값 (번단위). 값은 –180 로부터 +180 의 범위에서, 디폴트값은 0 이다. 정의 값은 이미지의 면을 윗방향을 향하는 것을 나타내, 부의 값은 이미지의 면을 아래방향을 향하는 것을 나타낸다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다.
Roll | 롤의 설정을 지정하는 값 (번단위). 값은 –180 로부터 +180 의 범위에서, 디폴트값은 0 이다. 정의 값은 이미지 표시 축으로 따라 카메라를 우회전으로 회전하는 것을 나타내, 부의 값은 카메라의 왼쪽 회전의 회전을 나타낸다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다.
Zoom | 줌의 설정을 지정하는 값 (mm 단위). 값은 10 에서 600 의 범위에서, 디폴트값은 디바이스에 의해 각각 다르다.
Exposure 다음의 식을 바탕으로, 노출의 설정을 지정하는 값 (초단위). 0 미만의 값의 경우, 노출 시간은 1/2n 초이다. 정의 값과 0 의 경우, 노출 시간은 2n 초이다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다. 예를 들어, 디바이스의 범위가 –7 로부터 1 으로, 스텝이 1 으로 한다. 대응하는 노출 시간은, 다음과 같다.
값 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | 1
초 | 1/128 | 1/64 | 1/32 | 1/16 | 1/8 | 1/4 | 1/2 | 1 | 2
Iris | fstop * 10 으로 나타내지는 조임의 설정을 지정하는 값.
Focus | 초점의 설정을, 대상에 대한 최적인 촛점거리로서 지정하는 값 (mm 단위). 범위와 디폴트값은, 디바이스에 의해 각각 다르다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다.

IAMCameraControl::GetRange

IAMCameraControl 인터페이스

지정의 카메라 프로퍼티의 범위에 관련지을 수 있고 있는 값을 취득한다.

구문

HRESULT GetRange (
     long property,
     long *pMin,
     long *pMax,
     long *pSteppingDelta,
     long *pDefault,
     long *pCapsFlags
    );

파라미터

property
[in] 조회하는 CameraControlProperty 열거형의 프로퍼티를 지정하는 값.
pMin
[out] 지정의 프로퍼티의 최소 범위에의 포인터.
pMax
[out] 지정의 프로퍼티의 최대 범위에의 포인터.
pSteppingDelta
[out] 지정의 프로퍼티의 스텝 사이즈에의 포인터. 스텝 사이즈는 프로퍼티의 변화의 단위로, 기본으로 되는 하드웨어에 의해 각각 다르다. 예를 들어, 디지탈카메라의 경우는, 5о두개변경할 수 있다.
pDefault
[out] 지정의 프로퍼티의 디폴트값에의 포인터.
pCapsFlags
[out] 카메라 프로퍼티가 자동 또는 수동인 것을 지정하는 CameraControlFlags 열거형의 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMCameraControl::Set

IAMCameraControl 인터페이스

특정의 카메라 제어 프로퍼티의 값을 설정한다.

구문

HRESULT Set (
     long Property,
     long lValue,
     long Flags
    );

파라미터

Property
[in] 변경하는 CameraControlProperty 열거형의 프로퍼티를 지정하는 값.
lValue
[in] 지정의 프로퍼티의 새로운 값.
Flags
[in] 카메라 프로퍼티가 자동 또는 수동인 것을 지정하는 CameraControlFlags 열거형의 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

CameraControlProperty 열거형으로 나타내지는 각 프로퍼티는, 자동 또는 수동의 설정을 가질 수가 있다. Flags 파라미터에 CameraControlFlags 열거형의 CameraControl_Flags_Auto 가 설정되어 있는 경우,lValue 파라미터는 무시된다. lValue 의 범위와 의미는, 조회하는 프로퍼티에 의해 각각 다르다. 다음의 표는, 유효한 값을 나타내고 있다.

프로퍼티 | lValue 의 범위와 의미
Pan | 빵의 설정을 지정하는 값 (번단위). 값은 –180 로부터 +180 의 범위에서, 디폴트값은 0 이다. 정의 값은 원점으로부터 우회전 (위로부터 보았을 경우, 카메라가 우회전으로 회전한다)을 나타내, 부의 값은 원점에서 왼쪽 회전을 나타낸다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다.
Tilt | 틸트의 설정을 지정하는 값 (번단위). 값은 –180 로부터 +180 의 범위에서, 디폴트값은 0 이다. 정의 값은 이미지의 면을 윗방향을 향하는 것을 나타내, 부의 값은 이미지의 면을 아래방향을 향하는 것을 나타낸다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다.
Roll | 롤의 설정을 지정하는 값 (번단위). 값은 –180 로부터 +180 의 범위에서, 디폴트값은 0 이다. 정의 값은 이미지 표시 축으로 따라 카메라를 우회전으로 회전하는 것을 나타내, 부의 값은 카메라의 왼쪽 회전의 회전을 나타낸다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다.
Zoom | 줌의 설정을 지정하는 값 (mm 단위). 값은 10 에서 600 의 범위에서, 디폴트값은 디바이스에 의해 각각 다르다.
Exposure 다음의 식을 바탕으로, 노출의 설정을 지정하는 값 (초단위). 0 미만의 값의 경우, 노출 시간은 1/2n 초이다. 정의 값과 0 의 경우, 노출 시간은 2n 초이다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다. 예를 들어, 디바이스의 범위가 –7 로부터 1 으로, 스텝 1 으로 한다. 대응하는 노출 시간은, 다음과 같다.
값 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | 1
초 | 1/128 | 1/64 | 1/32 | 1/16 | 1/8 | 1/4 | 1/2 | 1 | 2
Iris | fstop * 10 으로 나타내지는 조임의 설정을 지정하는 값.
Focus | 초점의 설정을, 대상에 대한 최적인 촛점거리로서 지정하는 값 (mm 단위). 범위와 디폴트값은, 디바이스에 의해 각각 다르다. 특정의 디바이스에서는, 이 범위의 서브 세트만이 이행 되는 경우가 있으므로 주의 해야 한다.


IAMClockAdjust 인터페이스

IAMClockAdjust 인터페이스는, 외부 소스로부터 필터 그래프에 타이밍 정보를 제공한다. 멀티미디어 스트림의 상황으로, 어플리케이션이 필터 그래프외의 오디오 스트림과 비디오 스트림을 양쪽 모두 사용하고 있는 경우는, 이 인터페이스를 사용하는 것으로, 필터 그래프에 클락 정보를 전할 수가 있다. 이것을 사용해, 다른 스트림의 동기를 잡을 수가 있다.

Microsoft® DirectShow® 의시스템 기준 클락 오브젝트는, 이 인터페이스를 이행 하고 있다. 상세한 것에 대하여는, 「IReferenceClock 」를 참조할것.

이 인터페이스를 사용 하면, DirectShow 내의 디폴트의 클락 오브젝트를 조정할 수 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMClockAdjust 메소드 | 설명
SetClockDelta | 시간의 증분값을 설정한다. 이것에 의해, 필터 그래프는, 자신의 클락을 외부 소스로부터 갱신할 수 있다.

IAMClockAdjust::SetClockDelta

IAMClockAdjust 인터페이스

필터 그래프에 기준 타임을 건네주는 것에 의해 클락을 조정한다. 시스템 기준 클락 오브젝트에 시간의 증분값이 추가된다.

구문

HRESULT SetClockDelta(
    REFERENCE_TIME rtDelta
);

파라미터

rtDelta
[in] 시간의 차이를 나타내는 값 (밀리 세컨드 단위).

반환값

성공의 경우는 S_OK 를 돌려주어,rtDelta 가 무효인 경우는 E_POINTER 를 돌려준다.


IAMCollection 인터페이스

이 인터페이스는 필터 그래프 매니저가 이행 해, Microsoft® Visual Basic® 나 스크립팅 언어로 쓰여진 어플리케이션이 사용한다.

IAMCollection 에 의해,IPinInfo 인터페이스와 IFilterInfo 인터페이스를 export 하는 오브젝트의 콜렉션 등에 액세스 할 수 있다. 예를 들어,IFilterInfo::get_Pins 메소드는, IAMCollection 인터페이스를 취득해 사용하는 것으로, 필터의 핀에 대응하고 있는 IPinInfo 인터페이스에 액세스 할 수 있다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스팟치인타페이스로 이용 가능한 타입 정보가 있을지 어떨지를 판별한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스팟치인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스팟치인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IAMCollection 메소드 | 설명
get_Count | 콜렉션내의 항목수를 취득한다.
get_NewEnum | 이 콜렉션으로 IEnumVARIANT 를 이행 하고 있는 열거형 오브젝트를 취득한다.
Item | 콜렉션으로부터 인덱스 첨부의 항목을 취득한다.

IAMCollection::get_Count

IAMCollection 인터페이스

콜렉션내의 항목수를 취득한다.

구문

HRESULT get_Count(
    LONG *plCount
    );

파라미터

plCount
[out, retval] 콜렉션내의 항목수에의 포인터.

반환값

HRESULT 값을 돌려준다.

IAMCollection::get_NewEnum

IAMCollection 인터페이스

이 콜렉션으로 IEnumVARIANT 를 이행 하고 있는 열거형 오브젝트를 취득한다.

구문

HRESULT get_NewEnum(
    IUnknown **ppUnk
    );

파라미터

ppUnk
[out, retval] 이 콜렉션으로 IEnumVARIANT 를 이행 하고 있는 오브젝트의,IUnknown 인터페이스에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

IAMCollection::Item

IAMCollection 인터페이스

콜렉션으로부터 인덱스 첨부의 항목을 취득한다.

구문

HRESULT Item(
    long lItem,
    IUnknown **ppUnk
    );

파라미터

lItem
[in] 콜렉션내의 인덱스.
ppUnk
[out] 콜렉션 항목의, 돌려주어진 IUnknown 인터페이스에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

주의

돌려주어지는 ppUnk 파라미터는, 컨테이너내의 오브젝트의 종류에 대응하는 오브젝트를 나타낸다. 이것은,IFilterInfo 오브젝트,IPinInfo 오브젝트, 또는 IMediaTypeInfo 오브젝트의 언젠가이다. 인덱스는 0 으로부터 시작된다.


IAMCopyCaptureFileProgress 인터페이스

IAMCopyCaptureFileProgress 인터페이스는,Progress 라고 하는 메소드를 1 개만 갖추고 있다. ICaptureGraphBuilder::CopyCaptureFile 메소드가 이것을 호출하는 것으로, 카피 처리의 종료 끝난 퍼센티지에 관한 정보를 받을 수가 있다.

캡춰 어플리케이션은 이 메소드를 이행 해, 카피 처리의 진행 상황에 관한 정보를 받는다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMCopyCaptureFileProgress 메소드 | 설명
Progress | 캡춰 조작중에 ICaptureGraphBuilder::CopyCaptureFile 가 정기적으로 호출한다.

IAMCopyCaptureFileProgress::Progress

IAMCopyCaptureFileProgress 인터페이스

ICaptureGraphBuilder::CopyCaptureFile 메소드가 실행하고 있는 카피 처리의 진척 상황 (종료 끝난 퍼센티지)을 어플리케이션에 보낸다.

구문

HRESULT Progress(
  int iProgress
  );

파라미터

iProgress
[in]카피 처리의 종료 끝난 퍼센티지를 나타내는, 0 에서 100 의 범위의 정수.

반환값

성공했을 경우는 S_OK 를 돌려주어, 처리가 중단했을 경우는 S_FALSE 를 돌려준다.

주의

보통 어플리케이션은 iProgress 의 값을 사용해 유저 인터페이스의 progress bar를 업데이트 한다.


IAMCrossbar 인터페이스

IAMCrossbar 인터페이스는 DirectShow® 아날로그 비디오 크로스바 필터이다. 이 필터는 WDM 스트리밍 디바이스 위에의 크로스바의 래퍼 필터이며, 그러므로 언제나 랩핑 하고 있는 디바이스의 프렌들리명을 전제로 하고 있다. 래퍼 필터와 WDM 스트리밍 디바이스의 상세한 것에 대하여는, 「하드웨어 디바이스가 필터 그래프에 참가하는 방법」을 참조할것.

아날로그 비디오 크로스바는 아날로그로부터의 신호와 비디오 캡춰 필터로부터의 디지털 오디오 혹은 비디오 소스를 루팅 한다. 이 필터는 n 입력과 m 출력의 일반적인 스위칭 matrices 이후에 설계되고 있다. 모든 입력 신호는 1 개 혹은 그 이상의 출력에 루팅 된다. 1 개의 크로스바는 비디오와 오디오 양쪽 모두를 루팅 할 수 있다. 비디오 핀을 사용해 합성 신호의 오디오 부분만큼을 루팅 하는 일도 가능하다.

주 : 이 인터페이스가 많은 메소드에서는, 핀인젝스를 파라미터로 지정한다. 핀인젝스는,IEnumPins 열거형을 사용해 계산한다. 입력 핀과 출력 핀의 인덱스값은, 양쪽 모두 0 으로부터 시작된다. get_PinCounts 메소드를 호출하는 것으로, 입력 핀과 출력 핀의 개수를 취득할 수 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMCrossbar 메소드 | 설명
get_PinCounts | 입력 핀과출력 핀의 개수를 취득한다.
CanRoute | 크로스바 필터가 아날로그 신호 또는 디지탈 신호를 루팅 할 수 있을지 어떨지를 판별한다.
Route | 입력 핀을 출력 핀에 루팅 한다.
get_IsRoutedTo | 지정의 출력 핀에 접속하고 있는 입력 핀을 취득한다.
get_CrossbarPinInfo | 지정의 핀에 관련하는 오디오 데이터 또는 비디오 데이터를 가지는 핀을 취득한다.

IAMCrossbar::CanRoute

IAMCrossbar 인터페이스

루팅이 가능한가 어떤가를 판별한다.

구문

HRESULT CanRoute (
  long OutputPinIndex,
  long InputPinIndex
  );

파라미터

OutputPinIndex
[in] 출력 핀.
InputPinIndex
[in] 입력 핀.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMCrossbar::get_CrossbarPinInfo

IAMCrossbar 인터페이스

지정의 핀에 관련하는 오디오 데이터 또는 비디오 데이터를 가지는 핀을 취득한다.

구문

HRESULT get_CrossbarPinInfo (
  BOOL IsInputPin,

  long PinIndex,

  long *PinIndexRelated,

  long *PhysicalType
  );

파라미터

IsInputPin
[in] 입력 핀의 경우는 TRUE 를 지정해, 출력 핀의 경우는 FALSE 를 지정한다.
PinIndex
[in] 관련 핀을 검색하는 기준이 되는 핀.
PinIndexRelated
[out] 관련 핀의 인덱스값에의 포인터.
PhysicalType
[out] 핀의 물리적인 종류 (오디오 또는 비디오)에의 포인터. PhysicalConnectorType 열거형의 멤버를 돌려준다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

예를 들어 이 메소드는, 지정의 비디오 핀에 관련하는 오디오 핀을 취득한다.

IAMCrossbar::get_IsRoutedTo

IAMCrossbar 인터페이스

지정의 출력 핀에 접속하고 있는 입력 핀을 취득한다.

구문

HRESULT get_IsRoutedTo (

  long OutputPinIndex,

  long *InputPinIndex

  );

파라미터

OutputPinIndex
[in] 출력 핀.
InputPinIndex
[out] 접속하고 있는 입력 핀에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMCrossbar::get_PinCounts

IAMCrossbar 인터페이스

입력 핀과 출력 핀의 개수를 취득한다.

구문

HRESULT get_PinCounts(

  long *OutputPinCount,

  long *InputPinCount

  );

파라미터

OutputPinCount
[out] 출력 핀의 개수에의 포인터.
InputPinCount
[out] 입력 핀의 개수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMCrossbar::Route

IAMCrossbar 인터페이스

입력 핀을 출력 핀에 루팅 한다.

구문

HRESULT Route (
  long OutputPinIndex,
  long InputPinIndex
  );

파라미터

OutputPinIndex
[in] 출력 핀.
InputPinIndex
[in] 입력 핀.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

핀의 인덱스는 0 으로부터 시작된다.


IAMDirectSound 인터페이스

이 인터페이스는,DSound 오디오 렌더러 필터로 이행 된다. 어플리케이션에서는,IAMDirectSound 인터페이스를 사용해, 다른 사운드 어플리케이션에 포커스가 설정되어 있는 경우에, 어플리케이션의 사운드가 여전히 들릴지 어떨지를 제어해, 사운드에 관련지을 수 있는 어플리케이션의 윈도우를 제어한다.

주 : 이 인터페이스에 현재 이행 되고 있는 것은,GetWindowFocus 메소드와 SetWindowFocus 메소드 뿐이다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMDirectSound 메소드 | 설명
GetDirectSoundInterface | 현재는 이행되어 있지 않다.
GetPrimaryBufferInterface | 현재는 이행되어 있지 않다.
GetSecondaryBufferInterface | 현재는 이행되어 있지 않다.
ReleaseDirectSoundInterface | 현재는 이행되어 있지 않다.
ReleasePrimaryBufferInterface | 현재는 이행되어 있지 않다.
ReleaseSecondaryBufferInterface | 현재는 이행되어 있지 않다.
SetWindowFocus | 현재의 미디어 파일의 사운드 재생을 처리하는 윈도우를 설정한다.
GetWindowFocus | 현재의 미디어 파일의 사운드 재생을 처리하고 있는 윈도우를 취득한다.

IAMDirectSound::GetDirectSoundInterface

IAMDirectSound 인터페이스

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT GetDirectSoundInterface(
  LPDIRECTSOUND *lplpds
);

파라미터

lplpds
현재의 사운드 디바이스의 인터페이스를 가리키는,IDirectSound 인터페이스에의 포인터의 주소.

반환값

E_NOTIMPL 를 돌려준다.

이행 되면(자), 이 메소드는 다음의 몇개의 값을 돌려준다.

E_FAIL | 이용할 수 있는 사운드 디바이스는 없다.
E_INVALIDARG | lplpds 파라미터가 NULL 이다.
E_NOTIMPL | DirectSound 가 인스톨되어 있지 않다.
NOERROR | 메소드가 성공했다.

IAMDirectSound::GetPrimaryBufferInterface

IAMDirectSound 인터페이스

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT GetDirectSoundInterface(
  LPDIRECTSOUNDBUFFER *lplpdsb
);

파라미터

lplpdsb
현재의 사운드 디바이스의 프라이머리 사운드 버퍼를 가리키는,IDirectSoundBuffer 인터페이스에의 포인터의 주소.

반환값

E_NOTIMPL 를 돌려준다.

이행 되면(자), 이 메소드는 다음의 몇개의 값을 돌려준다.

E_FAIL | 이용할 수 있는 사운드 디바이스는 없다.
E_INVALIDARG | lplpdsb 파라미터가 NULL 이다.
E_NOTIMPL | DirectSound 가 인스톨되어 있지 않다.
NOERROR | 메소드가 성공했다.

IAMDirectSound::GetSecondaryBufferInterface

IAMDirectSound 인터페이스

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT GetSecondaryBufferInterface(
  LPDIRECTSOUNDBUFFER *lplpdsb
);

파라미터

lplpdsb
IDirectSoundBuffer 인터페이스에의 포인터의 주소. 종료시에는, 현재의 사운드 디바이스의 세칸다리사운드밧파를 가리킨다.

반환값

E_NOTIMPL 를 돌려준다.

이행 되면(자), 이 메소드는 다음의 몇개의 값을 돌려준다.

E_FAIL | 이용할 수 있는 사운드 디바이스는 없다.
E_INVALIDARG | lplpdsb 파라미터가 NULL 이다.
E_NOTIMPL | DirectSound 가 인스톨되어 있지 않다.
NOERROR | 메소드가 성공했다.

IAMDirectSound::GetWindowFocus

IAMDirectSound 인터페이스

현재의 미디어 파일의 사운드 재생을 처리하고 있는 윈도우를 취득한다.

구문

HRESULT GetWindowFocus(
  HWND hWnd,
  BOOL bMixingOnOrOff
);

파라미터

hWnd
사운드 재생 윈도우에의 핸들. 이 값이 NULL 의 경우, 사운드는 윈도우에 관련지을 수 있지 않았다. Windows NT® 4.0 에서는, 현재, 윈도우없이의 사운드 재생은 지원되어 있지 않기 때문에 주의 해야 한다.
bMixingOnOrOff
사운드를 믹싱 하는지 (TRUE), 믹싱 하지 않는가 (FALSE)를 나타내는 값.

반환값

다음의 몇개의 값을 돌려준다.
E_FAIL | 이용할 수 있는 사운드 디바이스는 없다.
E_INVALIDARG | 인수 hWnd 가 무효이다.
E_NOTIMPL | DirectSound 가 인스톨되어 있지 않다.
NOERROR | 메소드가 성공했다.

IAMDirectSound::ReleaseDirectSoundInterface

IAMDirectSound 인터페이스

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT ReleaseDirectSoundInterface(
  LPDIRECTSOUND lpds
);

파라미터

lpds
해방하는 IDirectSound 인터페이스에의 포인터.

반환값

E_NOTIMPL 를 돌려준다.

이행 되면(자), 이 메소드는 다음의 몇개의 값을 돌려준다.

E_FAIL | 지정의 IDirectSound 인터페이스에의 참조가 없고, 이것을 해방할 수 없다.
E_INVALIDARG | lpds 파라미터가 NULL 이다.
NOERROR | 메소드가 성공했다.

IAMDirectSound::ReleasePrimaryBufferInterface

IAMDirectSound 인터페이스

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT ReleasePrimaryBufferInterface(
  LPDIRECTSOUNDBUFFER lpdsb

);

파라미터

lpdsb
해방하는 IDirectSoundBuffer 인터페이스에의 포인터.

반환값

E_NOTIMPL 를 돌려준다.

이행 되면(자), 이 메소드는 다음의 몇개의 값을 돌려준다.

E_FAIL | 지정의 IDirectSoundBuffer 인터페이스에의 참조가 없고, 이것을 해방할 수 없다.
E_INVALIDARG | lpdsb 파라미터가 NULL 이다.
NOERROR | 메소드가 성공했다.

IAMDirectSound::ReleaseSecondaryBufferInterface

IAMDirectSound 인터페이스

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT ReleaseSecondaryBufferInterface(
  LPDIRECTSOUNDBUFFER lpdsb
);

파라미터

lpdsb
해방하는 IDirectSoundBuffer 인터페이스에의 포인터.

반환값

E_NOTIMPL 를 돌려준다.

이행 되면(자), 이 메소드는 다음의 몇개의 값을 돌려준다.

E_FAIL | 지정의 IDirectSoundBuffer 인터페이스에의 참조가 없고, 이것을 해방할 수 없다.
E_INVALIDARG | lpdsb 파라미터가 NULL 이다.
NOERROR | 메소드가 성공했다.

IAMDirectSound::SetWindowFocus

IAMDirectSound 인터페이스

현재의 미디어 파일의 사운드 재생을 처리하는 윈도우를 설정한다.

구문

HRESULT SetWindowFocus(
  HWND hWnd,
  BOOL bMixingOnOrOff
);

파라미터

hWnd
사운드 재생 윈도우에의 핸들. 이 값이 NULL 의 경우, 사운드는 윈도우에 관련지을 수 없다. Windows NT 4.0 에서는, 현재, 윈도우없이의 사운드 재생은 지원되어 있지 않기 때문에 주의 해야 한다.
bMixingOnOrOff
사운드를 믹싱 하는지 (TRUE), 믹싱 하지 않는가 (FALSE)를 나타내는 값.

반환값

다음의 몇개의 값을 돌려준다.
E_FAIL | 이용할 수 있는 사운드 디바이스는 없다.
E_INVALIDARG | 인수 hWnd 가 무효이다.
E_NOTIMPL | DirectSound 가 인스톨되어 있지 않다.
NOERROR | 메소드가 성공했다.


IAMDroppedFrames 인터페이스

IAMDroppedFrames 인터페이스는, 캡춰 필터로부터 어플리케이션에 대해서, 필터가 결핍 시킨 프레임 (송신하지 않았던 프레임), 실현된 frame rate (그래프의 실행 시간을 결핍 하지 않았던 프레임수로 나눈 값), 및 실현된 데이터 레이트 (그래프의 실행 시간을 프레임의 평균 사이즈로 나눈 값)에 관한 정보를 제공한다. 드롭 프레임수가 많으면 비디오 클립의 매끄러움이 손상될 가능성이 있다.

어플리케이션이 IAMStreamControl 인터페이스 또는 ICaptureGraphBuilder::ControlStream 를 사용해 핀을 오프로 하고 있는 경우에서도, 결핍 프레임과 비결핍 프레임을, 비디오 캡춰 드라이버가 계속해 카운트 하고 있을 가능성이 있다. 많은 경우, 그 카운트에 의미는 없다. 어플리케이션에 있어, 핀이 온 때 마셔 결핍 프레임과 비결핍 프레임의 개수가 의미를 가지는 경우는,IAMStreamControl::StartAt 또는 ICaptureGraphBuilder::ControlStream 로 핀을 온으로 한 직후에 IAMDroppedFrames::GetNumDropped 및 IAMDroppedFrames::GetNumNotDropped 를 호출하는 것에 의해, 그 값을 요구할 수가 있다. 이 후의 GetNumDropped 또는 GetNumNotDropped 에의 호출로 돌려주어지는 값으로부터 전의 값을 당기는 것에 의해, 핀이 온의 사이에 드롭 된 개수를 얻을 수 있다. 많은 경우, 이 값에 의미가 있다. IAMStreamControl::StartAt 또는 ICaptureGraphBuilder::ControlStream 에의 호출이 핀을 즉석에서 온으로 하지 않고, 지정의 시간이 경과한 다음에 핀을 온으로 하는 경우는, 통지 (EC_STREAM_CONTROL_STARTED)를 받고 나서 최초의 GetNumDropped 및 GetNumNotDropped 를 호출할 필요가 있다. 상세한 것에 대하여는,IAMStreamControl 에 관한 문서를 참조할것. 양쪽 모두의 인터페이스를 적절히 사용하는 캡춰 어플리케이션의 예에 대해서는, CAPTURE 의 샘플을 참조할것.

캡춰 필터의 비디오출력 핀은, 항상 이 인터페이스를 이행 한다.

캡춰 필터가 State_Stopped 로부터 State_Paused 에 변화할 때마다, 모든 카운트를 0 에 리셋 할 필요가 있다.

이 인터페이스의 이행의 상세한 것에 대하여는, 「비디오 캡춰 필터의 개발」을 참조할것.

어플리케이션은, 캡춰때는 항상 이 인터페이스를 사용해, 현재의 캡춰 상태를 갱신한다. 캡춰의 종료후, 어플리케이션은 이 인터페이스를 사용해, 최종적인 캡춰의 결과를 판별한다.

주 : 이 인터페이스의 메소드에는, 이행되어 있지 않은 것이 있다. 많은 필터에서는,GetNumDropped 과 GetNumNotDropped 만이 이행 된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMDroppedFrames 메소드 | 설명
GetNumDropped | 전회의 스트리밍의 시작 이후, 핀이 결핍 시킨 총프레임수를 취득한다.
GetNumNotDropped | 핀이 다운 스트림에 전달한 (결핍 하지 않았다) 총프레임수를 취득한다.
GetDroppedInfo | 드롭 프레임 번호의 배열을 취득한다.
GetAverageFrameSize | 드롭 프레임의 평균 사이즈를 취득한다.

IAMDroppedFrames::GetAverageFrameSize

IAMDroppedFrames 인터페이스

핀이 결핍 시킨 프레임의 평균 사이즈를 취득한다.

구문

HRESULT GetAverageFrameSize(
    long *plAverageSize );

파라미터

plAverageSize
[out, retval] 스트리밍의 시작 이후, 핀이 송신한 프레임의 평균 사이즈에의 포인터 (바이트 단위).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

GetAverageFrameSize 에의 호출로 데이터가 캡춰 되지 않는 경우,plAverageSize 는 값 0 을 돌려준다.

IAMDroppedFrames::GetDroppedInfo

IAMDroppedFrames 인터페이스

핀이 결핍 시킨 프레임 번호의 배열을 취득한다.

구문

HRESULT GetDroppedInfo(
    long lSize,
    long *plArray,
    long *plNumCopied );

파라미터

lSize
[in] 요구되는 배열내의 요소수.
plArray
[out] 배열에의 포인터.
plNumCopied
[out, retval] 설정된 배열 요소수에의 포인터. 필터가 임의의 요소수의 보존을 결정해 요구한 프레임 몇분만큼 이 정보를 보존하지 않는 것이 있으므로, 이 값은 lSize 와 다른 경우가 있다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

필터는, 드롭 프레임의 최초의 lSize 수까지 그 프레임수를 배열에 기입해, 거기에 따라 plNumCopied 를 설정한다.

IAMDroppedFrames::GetNumDropped

IAMDroppedFrames 인터페이스

전회의 스트리밍의 시작 이후, 핀이 결핍 시킨 총프레임수를 취득한다.

구문

HRESULT GetNumDropped(
    long *plDropped );

파라미터

plDropped
[out] 드롭 된 총프레임수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMDroppedFrames::GetNumNotDropped

IAMDroppedFrames 인터페이스

핀이 다운 스트림에 전달한 (결핍 하지 않았다) 총프레임수를 취득한다.

구문

HRESULT GetNumNotDropped(
  long *plNotDropped );

파라미터

plNotDropped
[out] 결핍 하지 않았던 총프레임수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.


IAMExtDevice 인터페이스

IAMExtDevice 인터페이스는, 외부 디바이스를 제어하는 기본 인터페이스이다. 이 인터페이스를 이행 하면, 다양한 종류의 디바이스를 제어할 수 있다. 다만, 현재의 Microsoft® DirectShow® 의 이행에서는 VCR 에 한정된다. IAMExtDevice 인터페이스는 외부 하드웨어의 전반적인 설정을 제어해서 , VCR 의 상세 설정을 제어하는 IAMExtTransport 인터페이스와 조합해 사용하는 것이 상정되고 있다. 필터가 SMPTE (Society of Motion Picture and Television Engineers) 타임 코드를 관리하고 있어, 외부 디바이스가 해당하는 기능을 갖추고 있는 경우는,IAMTimecodeReader ,IAMTimecodeGenerator , 및 IAMTimecodeDisplay 의 각 인터페이스도 이행 할 수 있다.

VCR 등의 외부 디바이스를 제어하는 필터 또는 어플리케이션을 생성 하는 경우는, 이 인터페이스를 이행 한다. 이 인터페이스가 제어하는 것은 디바이스의 전반 정보이므로, 외부 디바이스 고유의 상세한 프로퍼티를 제어하려면 ,IAMExtTransport 인터페이스를 이행 한다.

어플리케이션에서는, VCR 등의 외부 디바이스를 직접 인스턴스화 및 제어할 수 있다. 그러나, 이러한 디바이스가 그래프내의 유일한 필터여도, 항상 필터 그래프의 문맥 중(안)에서 이러한 디바이스를 인스턴스화하는 것이 추천 된다.

이 인터페이스는, 어플리케이션에 외부 디바이스 제어를 추가하는 경우에 사용한다.

어플리케이션에서는, 필터 그래프를 사용해 필터를 열거해, 적절한 필터로부터 IAMExtDevice 인터페이스를 직접 취득한다.

하드웨어의 요건

외부 VCR 를 제어하려면 , 특정의 하드웨어의 요건이 추천 된다. RS-422 시리얼 인터페이스를 가지는 VCR 의 경우는, 특별한 시리얼 포트 카드 또는 외부부착의 RS-232 대 RS-422 어댑터가 필요하다. 게다가 최적인 퍼포먼스를 얻으려면 , 16550 고성능 UART (Universal Asynchronous Receiver/Transmitter)가 짜넣어진 시리얼 포트 카드를 컴퓨터가 장착해, 38.4 보등의 고속의 baud rate를 실현할 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMExtDevice 메소드 | 설명
GetCapability | 외부 디바이스의 기능을 취득한다.
get_ExternalDeviceID | 외부 디바이스의 모델 번호를 취득한다.
get_ExternalDeviceVersion | 외부 디바이스의 오퍼레이팅(operating) 소프트웨어의 버젼 번호를 취득한다.
put_DevicePort | 외부 디바이스의 접속처의 통신 포토를 지정한다.
get_DevicePower | 외부 디바이스의 전원 모드가 온, 오프, 스탠바이의 어떤 것인지를 취득한다.
put_DevicePower | 외부 디바이스의 전원 모드를 온, 오프, 또는 스탠바이로 설정한다.
Calibrate | 외부 디바이스의전송 메카니즘을 캐리브레이트 한다.
get_DevicePort | 외부 디바이스의 접속처의 통신 포토를 취득한다.

IAMExtDevice::Calibrate

IAMExtDevice 인터페이스

외부 디바이스의전송 메카니즘을 캐리브레이트 한다.

구문

HRESULT Calibrate(
    HEVENT hEvent,
    long Mode,
    long *pStatus
);

파라미터

hEvent
[in] 이 프로세스의 종료를 통지하기 위해서 사용하는 이벤트.
Mode
[in] calibration 프로세스를 액티브 또는 비액티브하게 하는 값. 다음의 어느쪽이든을 지정한다.
ED_ACTIVE | calibration 프로세스를 액티브하게 한다.
ED_INACTIVE | calibration 프로세스를 비액티브하게 한다.
NULL | 현재 상태가 액티브 또는 비액티브한 것을 판별할 경우에 사용한다.
pStatus
[out] OATRUE 또는 OAFALSE 로 설정되는 변수에의 포인터. OATRUE 는 이벤트가 액티브한 것을 나타내, OAFALSE 는 비액티브한 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드는, calibration가 필요한 특정의 외부 디바이스로 사용한다. 예를 들어, 테이프를 되감아 카운터를 리셋 하는 경우, 또는 타임 코드 리더나 제네레이터의 프레임 오프셋(offset)를 계산하는 경우등이 이것에 상당한다.

각종 외부 디바이스에 대응하는 필터에서는, 디바이스가 필요로 하는 calibration에 응해, 이 메소드를 각각 다른 포맷으로 이행 할 수 있다. 이 메소드에서는,IMediaEventSink 인터페이스가 이벤트 세면대를 이미 설정해 있다, 또는 다른 이벤트 통지 메소드가 설정되어 있는 것이 전제이다.

IAMExtDevice::GetCapability

IAMExtDevice 인터페이스

외부 디바이스의 기능을 취득한다.

구문

HRESULT GetCapability(
    long Capability,
    long *pValue,
    double *pdblValue
);

파라미터

Capability
[in] 확인하는 기능을 지정하는 값. 다음의 어느쪽이든을 지정한다.
ED_DEVCAP_CAN_RECORD | 디바이스가 기록 가능한가 어떤가를 확인한다.
ED_DEVCAP_CAN_RECORD_STROBE | 디바이스가 싱글 프레임 기록 가능한가 어떤가를 확인한다.
ED_DEVCAP_CAN_SAVE | 디바이스가 데이터를 보존 가능한가 어떤가를 확인한다.
ED_DEVCAP_DEVICE_TYPE | 외부 디바이스의 종류를 확인한다.
ED_DEVCAP_HAS_AUDIO | 디바이스에 오디오 기능이 있을지 어떨지를 확인한다.
ED_DEVCAP_HAS_VIDEO | 디바이스에 비디오 기능이 있을지 어떨지를 확인한다.
ED_DEVCAP_USES_FILES | 디바이스에 파일 시스템이 짜넣어지고 있는지 어떤지를 확인한다.
pValue
[out] Capability 파라미터로 지정된 프로퍼티의 기능을 나타내는 값을 받는 변수에의 포인터. ED_DEVCAP_DEVICE_TYPE 를 제외하는 모든 프로퍼티에서는, 이 변수는 OATRUE 또는 OAFALSE 로 설정된다. OATRUE 는 프로퍼티가 지원 되는 것을 나타내, OAFALSE 는 프로퍼티가 지원 되지 않는 것을 나타낸다. ED_DEVCAP_DEVICE_TYPE 의 경우, 변수는 다음의 몇개의 값으로 설정된다.
ED_DEVTYPE_ATR | 오디오 테이프 레코더
ED_DEVTYPE_CG | 캐릭터 제너레이터
ED_DEVTYPE_DDR | 디지털 디스크 레코더
ED_DEVTYPE_DVE | 디지털 비디오 이펙트 유니트
ED_DEVTYPE_GPI | 범용 인터페이스 방아쇠
ED_DEVTYPE_KEYER | 비데오키야
ED_DEVTYPE_LASERDISK | 레이저 디스크
ED_DEVTYPE_MIXER_AUDIO | 오디오 믹서
ED_DEVTYPE_MIXER_VIDEO | 비디오 믹서
ED_DEVTYPE_ROUTER | 비디오 라우터
ED_DEVTYPE_TBC | 타임 베이스 수집가
ED_DEVTYPE_TCG | 타임 코드 제네레이터/리더
ED_DEVTYPE_VCR | VCR
ED_DEVTYPE_WIPEGEN | 비디오 와이프 제네레이터
ED_DEVTYPE_JOYSTICK | 죠이스틱
ED_DEVTYPE_KEYBOARD | 키보드
pdblValue
[out] 지정의 프로퍼티 (double 형 값의 경우)의 기능을 나타내는 변수에의 포인터. 사용되어 있지 않은 경우는 NULL 가 건네받는다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

큰 값이나 부동 소수점의 값을 돌려주는 경우를 제외해, 모든 반환값은 pValue 로 돌려주어진다. 큰 값이나 부동 소수점의 값은,pdblValue 파라미터로 돌려주어진다.

IAMExtDevice::get_DevicePort

IAMExtDevice 인터페이스

외부 디바이스의 접속처의 통신 포토를 취득한다.

구문

HRESULT get_DevicePort(
    long *pDevicePort
);

파라미터

pDevicePort
[out] 디바이스의 접속처의 포토를 지정하는, 다음의 몇개의 값으로 설정되는 변수에의 포인터.
DEV_PORT_1394 | IEEE 1394 버스
DEV_PORT_ARTI | ARTI 드라이버
DEV_PORT_COM1 | COM1
DEV_PORT_COM2 | COM2
DEV_PORT_COM3 | COM3
DEV_PORT_COM4 | COM4
DEV_PORT_DIAQ | Diaquest 드라이버
DEV_PORT_SIM | 시뮬레이션 포토
DEV_PORT_USB | USB (Universal Serial Bus)

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtDevice::put_DevicePort

IAMExtDevice::get_DevicePower

IAMExtDevice 인터페이스

외부 디바이스의 전원 모드 (온, 오프, 스탠바이)를 취득한다.

구문

HRESULT get_DevicePower(
    long *pPowerMode
);

파라미터

pPowerMode
[out] 외부 디바이스의 전원 모드를 지정하는 다음의 몇개의 값으로 설정되는 변수에의 포인터.
ED_POWER_OFF | 오프
ED_POWER_ON | 온
ED_POWER_STANDBY | 스탠바이

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtDevice::put_DevicePower

IAMExtDevice::get_ExternalDeviceID

IAMExtDevice 인터페이스

외부 디바이스의 모델 번호를 취득한다.

구문

HRESULT get_ExternalDeviceID(
    LPOLESTR *ppszData
);

파라미터

ppszData
[out] 메이커 고유의 ID 번호 또는 캐릭터 라인의 텍스트를 받는 변수에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMExtDevice::get_ExternalDeviceVersion

IAMExtDevice 인터페이스

외부 디바이스의 오퍼레이팅(operating) 소프트웨어의 버젼 번호를 취득한다.

구문

HRESULT get_ExternalDeviceVersion(
    LPOLESTR *ppszData
);

파라미터

ppszData
[out] 외부 디바이스의, 메이커 고유의 오퍼레이팅(operating) 소프트웨어의 버젼 번호를 받는 변수에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMExtDevice::put_DevicePort

IAMExtDevice 인터페이스

외부 디바이스의 접속처의 통신 포토를 지정한다.

구문

HRESULT put_DevicePort(
    long DevicePort
);

파라미터

DevicePort
[in] 디바이스의 접속처의 포토. 다음의 어느쪽이든을 지정한다.
DEV_PORT_1394 | IEEE 1394 버스
DEV_PORT_ARTI | ARTI 드라이버
DEV_PORT_COM1 | COM1
DEV_PORT_COM2 | COM2
DEV_PORT_COM3 | COM3
DEV_PORT_COM4 | COM4
DEV_PORT_DIAQ | Diaquest 드라이버
DEV_PORT_MIN | DEV_PORT_SIM
DEV_PORT_SIM | 시뮬레이션 포토 ("비하드웨어 " 시뮬레이션으로 사용한다)
DEV_PORT_USB | USB (Universal Serial Bus)

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtDevice::get_DevicePort

IAMExtDevice::put_DevicePower

IAMExtDevice 인터페이스

외부 디바이스의 전원 모드를 온, 오프, 또는 스탠바이로 설정한다.

구문

HRESULT put_DevicePower(
    long PowerMode
);

파라미터

PowerMode
[in] 디바이스의 전원 모드를 지정하는 값. 다음의 몇개의 값으로 설정한다.
ED_POWER_OFF | 오프
ED_POWER_ON | 온
ED_POWER_STANDBY | 스탠바이

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtDevice::get_DevicePower


IAMExtTransport 인터페이스

IAMExtTransport 인터페이스는, 외부 VCR 의 특정의 동작을 제어하는 메소드를 갖추고 있다. 이 메소드에서는, 보통, VCR 와 컴퓨터와의 사이의 데이터 변환의 방법을 결정하는,전송 프로퍼티를 설정 및 취득한다. 이 인터페이스는, 트랜스폴트의 특정의 동작을 제어하는 것이므로, 외부 디바이스의 전반적인 동작을 제어하는 IAMExtDevice 인터페이스와 조합해 이행 할 필요가 있다. VCR 이외의 외부 디바이스를 제어하려면 , 2 방법의 방법이 있다. 1 개(살)은, 필요한 메소드를 사용해, 나머지에 대해서는 E_NOTIMPL 를 돌려주는 방법이다. 이제(벌써) 1 개(살)은, 새로운 인터페이스를 설계해,IAMExtDevice 를 집성 하는 방법이다.

이 인터페이스는, 개발자가편집 이벤트를 정의하기 위한 메소드도 갖추고 있다. 편집 이벤트는 컨텐츠의 오쏘링 처리를 촉진해서 ,편집 프로퍼티 세트에 그룹화 되는 개별의 편집 프로퍼티로 구성된다. 편집 프로퍼티 세트에서는, 트랜스폴트상에서의 실제의 기록 순서나, 단순한 위치 지정 커멘드를 정의할 수 있다. 예를 들어, 편집의 특정의 모드의 지정, 기록 순서의 인점과 아웃점의 기록, 또는 북마크로 불리는 위치의 기억등을 실시할 수가 있다. SetEditPropertySet 메소드는, 편집 프로퍼티 세트로 불리는 편집 프로퍼티의 그룹을 생성 또는 등록하는 것이다. 한편 SetEditProperty 에 의해, 각 편집프로퍼티의 파라미터와 값을 어플리케이션으로 정의할 수 있다. 이것은 비교적 고도의 기술을 필요로 하므로, 이행은 상급 개발자가 담당한다.

VCR 등의 외부 디바이스를 제어하는 필터 또는 어플리케이션을 생성 하는 경우는, 이 인터페이스를 이행 한다. 이 인터페이스는 디바이스의 특정의 정보를 제어하는 것이므로,IAMExtDevice 인터페이스와 함께 이행 할 필요가 있다.

어플리케이션에서는, VCR 등을 대상으로 하는, 외부 디바이스 제어 필터를 직접 인스턴스화 및 제어할 수 있다. 그러나, 이것들이 그래프내의 유일한 필터여도, 항상 필터 그래프의 문맥 중(안)에서 인스턴스화하는 것이 강하고 추천 된다.

이행은, 제어되는 외부 디바이스의 종류에 의해 각각 다르다. 디바이스에 따라서는, 메소드를 적용할 수 없는 경우에 E_NOTIMPL 가 돌려주어진다.

이 인터페이스는, 컴퓨터에 접속되고 있는 비디오 테잎 머신과 오디오 테이프 머신을 필터로 제어하는 경우에 사용한다. 이 인터페이스는, 오디오와 비디오의 "배치 캡춰 " 와 "테이프 출력 " 를 이행 하는 어플리케이션에서도 일반적으로 사용된다.

어플리케이션은, 필터 그래프를 사용해 필터를 열거해, 적절한 필터로부터 IAMExtTransport 인터페이스를 직접 취득한다.

하드웨어의 요건

외부 VCR 를 제어하려면 , 특정의 하드웨어의 요건이 추천 된다. RS-422 시리얼 인터페이스를 가지는 VCR 의 경우는, 특별한 시리얼 포트 카드 또는 외부부착의 RS-232 대 RS-422 어댑터가 필요하다. 게다가 최적인 퍼포먼스를 얻으려면 , 16550 고성능 UART (Universal Asynchronous Receiver/Transmitter)가 짜넣어진 시리얼 포트 카드를 컴퓨터가 장착해, 38.4 보등의 고속의 baud rate를 실현할 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMExtTransport 메소드 | 설명
GetCapability | 외부 트랜스폴트의 전반 기능을 취득한다.
put_MediaState | 미디어의 현재 상태를 설정한다.
get_MediaState | 미디어의 현재 상태를 취득한다.
put_LocalControl | 외부 디바이스 상태를 로컬 제어 또는 리모트 제어로 설정한다.
get_LocalControl | 외부 디바이스 상태를 취득한다.
GetStatus | 외부 트랜스폴트 상태를 판별한다.
GetTransportBasicParameters | 외부 트랜스폴트의 기본 파라미터의 설정값을 취득한다.
SetTransportBasicParameters | 외부 트랜스폴트의 기본 파라미터를 설정한다.
GetTransportVideoParameters | 외부 트랜스폴트의 비디오 파라미터의 설정값을 취득한다.
SetTransportVideoParameters | 외부 트랜스폴트의 비디오 파라미터를 설정한다.
GetTransportAudioParameters | 외부 트랜스폴트의 오디오 파라미터의 설정값을 취득한다.
SetTransportAudioParameters | 외부 트랜스폴트의 오디오 파라미터를 설정한다.
put_Mode | 새로운 트랜스폴트 모드 (재생, 정지, 기록, 편집등)에의 이행을 설정한다.
get_Mode | 트랜스폴트의 모드 (재생, 정지, 기록, 편집등)를 취득한다.
put_Rate | 속도 변경이 가능한 외부 디바이스의 재생 속도를 설정한다.
get_Rate | 속도 변경이 가능한 외부 디바이스의 put_Rate 로 설정된 재생 속도를 취득한다.
GetChase | 체이스 모드 상태를 취득한다.
SetChase | 체이스 모드를 유효 또는 무효로 한다.
GetBump | 범프 모드 상태를 취득한다.
SetBump | 복수의 외부 디바이스의 동기를 잡기 위해서(때문에) 재생 속도를 변경한다.
get_AntiClogControl | 헤드 막혀 방지 컨트롤이 유효한가 어떤가를 판별한다.
put_AntiClogControl | 트랜스폴트의 헤드 막혀 방지 컨트롤을 유효 또는 무효로 한다.
GetEditPropertySet | 편집 프로퍼티 세트의 현재 상태를 취득한다.
SetEditPropertySet | 편집 프로퍼티의 그룹을 형성하는 편집 프로퍼티를 등록한다.
GetEditProperty | 특정의 편집 프로퍼티 세트에 관련지을 수 있고 있는 개별의 파라미터와 값을 취득한다.
SetEditProperty | 특정의 편집 프로퍼티 세트에 관련지을 수 있고 있는 개별의 파라미터와 값을 정의한다.
get_EditStart | 외부 트랜스폴트의 편집 컨트롤이 액티브한가 어떤가를 판별한다.
put_EditStart | 트랜스폴트의 에디트 컨트롤을 액티브하게 한다 (가능한 경우).

IAMExtTransport::get_AntiClogControl

IAMExtTransport 인터페이스

헤드 막혀 방지 컨트롤이 유효한가 어떤가를 판별한다.

구문

HRESULT get_AntiClogControl(
    long *pEnabled
);

파라미터

pEnabled
[out] 헤드 막혀 방지가 유효한가 어떤가를 나타내는 값에의 포인터. OATRUE 는 헤드 막혀 방지가 유효한 것을 나타내, OAFALSE 는 무효라는 점을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtTransport::put_AntiClogControl

IAMExtTransport::GetBump

IAMExtTransport 인터페이스

범프 모드 상태를 취득한다.

구문

HRESULT GetBump(
    long *pSpeed,
    long *pDuration
);

파라미터

pSpeed
[out] 일시 속도 (표준 속도의 배수)에의 포인터.
pDuration
[out] 현재의 타임 포맷으로 나타내지는 범프 시간폭에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드는, 액티브한 "범프 " 의 일시 속도와 나머지의 시간폭을 돌려준다.

지원 되는 타임 포맷에 대해서는, (SDK 루트) \Include\Edevdefs.h 안의 "IAMExtTransport Basic Parms" 를 참조할것.

참조

IAMExtTransport::SetBump

IAMExtTransport::GetCapability

IAMExtTransport 인터페이스

외부 트랜스폴트의 전반 기능을 취득한다.

구문

HRESULT GetCapability(
    long Capability,
    long *pValue,
    double *pdblValue
);

파라미터

Capability
[in] 조회하는 기능. 다음의 어느쪽이든을 지정한다.
ED_TRANSCAP_CAN_BUMP_PLAY | 트랜스폴트로, 동기를 잡기 위해서(때문에) 속도를 변경할 수 있을지 어떨지를 확인한다.
ED_TRANSCAP_CAN_DELAY_AUDIO_IN | 트랜스폴트로, 지연 인 오디오 편집을 실시할지 어떨지를 확인한다.
ED_TRANSCAP_CAN_DELAY_AUDIO_OUT | 트랜스폴트로, 지연 아웃 오디오 편집을 실시할지 어떨지를 확인한다.
ED_TRANSCAP_CAN_DELAY_VIDEO_IN | 트랜스폴트로, 지연 인 비디오 편집을 실시할지 어떨지를 확인한다.
ED_TRANSCAP_CAN_DELAY_VIDEO_OUT | 트랜스폴트로, 지연 아웃 비디오 편집을 실시할지 어떨지를 확인한다.
ED_TRANSCAP_CAN_EJECT | 트랜스폴트로, 미디어를 이젝트 할 수 있을지 어떨지를 확인한다.
ED_TRANSCAP_CAN_PLAY_BACKWARDS | 트랜스폴트로, 미디어를 리버스 재생 (부의 레이트)할 수 있을지 어떨지를 확인한다.
ED_TRANSCAP_CAN_SET_EE | 트랜스폴트로, 입력 영상을 출력으로 표시할 수 있을지 어떨지를 확인한다.
ED_TRANSCAP_CAN_SET_PB | 트랜스폴트로, 미디어 재생 영상을 출력으로 표시할 수 있을지 어떨지를 확인한다.
ED_TRANSCAP_FWD_VARIABLE_MAX | 최고 포워드 속도 (재생 속도의 배수)를 pdblValue 로 돌려준다.
ED_TRANSCAP_FWD_VARIABLE_MIN | 최저 포워드 속도 (재생 속도의 배수)를 pdblValue 로 돌려준다.
ED_TRANSCAP_REV_VARIABLE_MAX | 최고 리버스 속도 (재생 속도의 배수)를 pdblValue 로 돌려준다.
ED_TRANSCAP_REV_VARIABLE_MIN | 최저 리버스 속도 (재생 속도의 배수)를 pdblValue 로 돌려준다.
ED_TRANSCAP_FWD_SHUTTLE_MAX | 최고 포워드 셔틀 모드 속도 (재생 속도의 배수)를 pdblValue 로 돌려준다.
ED_TRANSCAP_LTC_TRACK | 리니어 타임 코드 (LTC )의 트럭 번호를 pValue 로 돌려준다.
ED_TRANSCAP_NUM_AUDIO_TRACKS | 오디오 트럭수를 pValue 로 돌려준다.
ED_TRANSCAP_FWD_SHUTTLE_MIN | 최저 포워드 셔틀 모드 속도 (재생 속도의 배수)를 pdblValue 로 돌려준다.
ED_TRANSCAP_REV_SHUTTLE_MAX | 최고 리버스 셔틀 모드 속도 (재생 속도의 배수)를 pdblValue 로 돌려준다.
ED_TRANSCAP_REV_SHUTTLE_MIN | 최저 리버스 셔틀 모드 속도 (재생 속도의 배수)를 pdblValue 로 돌려준다.
ED_TRANSCAP_HAS_DT_OATRUE | 디바이스가 다이나믹 트랙킹을 갖추고 있는 것을 지정한다.
pValue
[out] Capability 로 지정되는 기능이 지원 될지 어떨지를 나타내는 값에의 포인터. 지원 되는 경우는 OATRUE 를 돌려주어, 지원 되지 않는 경우는 OAFALSE 를 돌려준다.
pdblValue
[out] Capability 로 지정되는 프로퍼티의 기능을 나타내는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

모든 OATRUE 값과 OAFALSE 값은 pValue 에 돌려주어진다. 수치는 pValue 또는 pdblValue 에 돌려주어진다. pValue 파라미터에서는 부족한 double 형의 값을 돌려주는 경우,pdblValue 파라미터가 사용된다. 몇개의 파라미터가 불필요한 경우는 NULL 를 돌려준다.

IAMExtTransport::GetChase

IAMExtTransport 인터페이스

체이스 모드 상태를 취득한다.

구문

HRESULT GetChase(
    long *pEnabled,
    long *pOffset,
    HEVENT *phEvent
);

파라미터

pEnabled
[out] 체이스가 유효한가 어떤가를 나타내는 값에의 포인터. OATRUE 는 체이스가 유효한 것을 나타내, OAFALSE 는 체이스가 무효라는 점을 나타낸다.
pOffset
[out] 현시점으로부터의 오프셋(offset)에의 포인터. 이것은, 트랜스폴트가 재생동안 보관 유지하는 오프셋(offset)를 나타낸다.
phEvent
[out] 체이스 오프셋(offset)가 설정되어 있는 것을 전하는 완료 통지에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

pOffset 의 시간은, 현재의 타임 포맷으로 주어진다. 지원 되는 타임 포맷에 대해서는, (SDK 루트) \Include\Edevdefs.h 안의 "IAMExtTransport Basic Parms" 를 참조할것.

참조

IAMExtTransport::SetChase

IAMExtTransport::GetEditProperty

IAMExtTransport 인터페이스

특정의 편집 이벤트에 관련지을 수 있고 있는 파라미터와 값을 취득한다.

구문

HRESULT GetEditProperty(
    long EditID,
    long Param,
    long *pValue
);

파라미터

EditID
[in] 편집 프로퍼티 세트의 ID 번호.
Param
[in] 값을 조사하는 원이 되는 편집 이벤트 파라미터.
pValue
[out] Param 로 지정되는 파라미터의 반환값에의 포인터. OATRUE, OAFALSE, 또는 고유의 값이 돌려주어진다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtTransport::SetEditProperty

IAMExtTransport::GetEditPropertySet

IAMExtTransport 인터페이스

특정의 편집 프로퍼티 세트에 관련지을 수 있고 있는 개별의 파라미터와 값을 취득한다.

구문

HRESULT GetEditPropertySet(
    long EditID,
    long *pState
);

파라미터

EditID
[in] 편집 프로퍼티 세트의 ID 번호.
pState
[out] 편집 프로퍼티 세트 상태에의 포인터. 다음의 어느쪽이든을 취득한다.
DC_SET_ACTIVE | 편집 프로퍼티 세트를 액티브하게 한다.
DC_SET_DELETE | 편집 프로퍼티 세트를 삭제한다.
DC_SET_INACTIVE | 편집 프로퍼티 세트를 비액티브하게 한다.
DC_SET_REGISTER | 편집 프로퍼티 세트를 등록한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtTransport::SetEditPropertySet

IAMExtTransport::get_EditStart

IAMExtTransport 인터페이스

외부 트랜스폴트의 에디트 컨트롤이 액티브한가 어떤가를 판별한다.

구문

HRESULT get_EditStart(
    long *pValue
);

파라미터

pValue
[out] 에디트 컨트롤이 액티브한가 어떤가를 나타내는 값에의 포인터. OATRUE 는 에디트 컨트롤이 액티브한 것을 나타내, OAFALSE 는 액티브하지 않은 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtTransport::put_EditStart

IAMExtTransport::get_LocalControl

IAMExtTransport 인터페이스

외부 디바이스 상태를 취득한다.

구문

HRESULT get_LocalControl(
    long *pState
);

파라미터

pState
[out] 로컬 제어 또는 리모트 제어를 나타내는 값에의 포인터. OATRUE 는 로컬 제어를 나타내, OAFALSE 는 리모트 제어를 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

외부 디바이스를 제어하려면 , 리모트 모드가 아니면 안된다.

참조

IAMExtTransport::put_LocalControl

IAMExtTransport::get_MediaState

IAMExtTransport 인터페이스

put_MediaState 로 설정되는 미디어의 현재 상태를 취득한다.

구문

HRESULT get_MediaState(
    long *pState
);

파라미터

pState
[out] 미디어의 현재 상태를 나타내는 반환값에의 포인터. 값은 디바이스에 따라서 다르지만, 다음의 값이 포함된다.
ED_MEDIA_SPIN_DOWN | 스핀이 정지하고 있다 (디스크 미디어의 경우). 안 thread 하고 있다 (테이프 미디어의 경우).
ED_MEDIA_SPIN_UP | 스핀이 시작 했지만 풀 스피드는 아니다 (디스크 미디어의 경우). 테이프의 thread가 시작 하고 있다 (테이프 미디어의 경우).
ED_MEDIA_UNLOAD | 미디어가 드라이브로부터 이젝트 되고 있다 (디바이스가 이젝트 기능을 지원 하고 있는 경우).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMExtTransport::get_Mode

IAMExtTransport 인터페이스

트랜스폴트의 모드 (재생, 정지, 기록, 편집등)를 취득한다.

구문

HRESULT get_Mode(
    long *pMode
);

파라미터

pMode
[out] 현재의 트랜스폴트 모드에의 포인터. 유효한 모드에 대해서는, 「IAMExtTransport::put_Mode 」를 참조할것.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMExtTransport::get_Rate

IAMExtTransport 인터페이스

속도 변경이 가능한 외부 디바이스의 재생 속도를 취득한다.

구문

HRESULT get_Rate(
    double *pdblRate
);

파라미터

pdblRate
[out] IAMExtTransport::put_Rate 로 설정되는 재생 속도에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMExtTransport::GetStatus

IAMExtTransport 인터페이스

외부 트랜스폴트 상태에 관한 상세 정보를 돌려준다.

구문

HRESULT GetStatus(
    long StatusItem,
    long *pValue
);

파라미터

StatusItem
[in] 상태를 조사하는 원이 되는 항목. 다음의 어느쪽이든을 지정할 수 있다.
ED_MODE_EDIT_CUE | 디바이스가 액티브한 편집 이벤트까지 머리 내 하고 있을지 어떨지를 확인한다.
ED_MODE_FF | 디바이스가 빨리 감기 하고 있을지 어떨지를 확인한다.
ED_MODE_FREEZE | 디바이스가 재생 모드로 포즈 하고 있을지 어떨지를 확인한다.
ED_MODE_LINK_OFF | 트랜스폴트 컨트롤이, 필터 그래프의 실행, 정지, 또는 포즈의 제어에 링크하고 있지 않는지 어떤지를 확인한다.
ED_MODE_LINK_ON | 트랜스폴트 컨트롤이, 필터 그래프의 실행, 정지, 또는 포즈의 제어에 링크하고 있을지 어떨지를 확인한다.
ED_MODE_PLAY | 디바이스가 재생중일지 어떨지를 확인한다.
ED_MODE_RECORD | 디바이스가 기록중일지 어떨지를 확인한다.
ED_MODE_RECORD_STROBE | 디바이스가 싱글 프레임 기록중일지 어떨지를 확인한다.
ED_MODE_RECORD_FREEZE | 디바이스가 기록 모드로 포즈 하고 있을지 어떨지를 확인한다.
ED_MODE_REW | 디바이스가 되감아 안일지 어떨지를 확인한다.
ED_MODE_SHUTTLE | 디바이스가 셔틀 (고속 재생) 중인가 어떤가를 확인한다. 실제의 트랜스폴트 속도를 판별하려면 IAMExtTransport::get_Rate 를 사용한다.
ED_MODE_STEP_FWD 또는 ED_MODE_STEP | 디바이스가 순서 방향으로 싱르스텝 처리 (한 번에 1 개의 프레임을 검색)하고 있을지 어떨지를 확인한다.
ED_MODE_STOP | 디바이스가 정지하고 있을지 어떨지를 확인한다.
pValue
[out] StatusItem 내의 항목이 액티브한가 어떤가를 나타내는 값에의 포인터. OATRUE 는 StatusItem 가 액티브한 것을 나타내, OAFALSE 는 액티브하지 않은 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 인터페이스를 이행 하는 경우, 그 StatusItem 파라미터는 대부분의 DirectShow 인터페이스보다 확장적이고, 코드로 그 다양성에 대처해, 해당하는 파라미터의전송 상태를 확인할 필요가 있으므로 주의 해야 한다.

IAMExtTransport::GetTransportAudioParameters

IAMExtTransport 인터페이스

외부 트랜스폴트의 오디오 파라미터 설정을 취득한다.

구문

HRESULT GetTransportAudioParameters(
    long Param,
    long *pValue
);

파라미터

Param
[in] 값을 취득하는 원이 되는 오디오 파라미터. 다음의 어느쪽이든을 지정한다.
ED_TRANSAUDIO_ENABLE_OUTPUT | 오디오 출력 채널
ED_TRANSAUDIO_ENABLE_RECORD | 오디오 녹음 채널
ED_TRANSAUDIO_ENABLE_SELSYNC | 오디오 selsync 녹음 채널
ED_TRANSAUDIO_SET_MONITOR | 모니터 출력 오디오 채널
ED_TRANSAUDIO_SET_SOURCE | 오디오 소스 채널
pValue
[out] IAMExtTransport::SetTransportAudioParameters 메소드로 설정되는 채널에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMExtTransport::GetTransportBasicParameters

IAMExtTransport 인터페이스

트랜스폴트의 기본 파라미터의 설정값을 취득한다.

구문

HRESULT GetTransportBasicParameters(

  long Param,

  long *pValue,

  LPOLESTR *ppszData
);

파라미터

Param
[in] 설정값을 취득하는 원이 되는 파라미터. 지정할 수 있는 파라미터에 대해서는, Edevdefs.h 안의 "IAMExtTransport Basic Parms" 를 참조할것.
pValue
[out] 파라미터의 설정값이 수치의 경우, 그 설정값에의 포인터.
ppszData
[out] 파라미터의 설정값이 캐릭터 라인의 경우, 그 설정값에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtTransport::SetTransportBasicParameters

IAMExtTransport::GetTransportVideoParameters

IAMExtTransport 인터페이스

외부 트랜스폴트의 비디오 파라미터의 설정값을 취득한다.

구문

HRESULT GetTransportVideoParameters(
    long Param,
    long *pValue
);

파라미터

Param
[in] 설정값을 취득하는 원이 되는 비디오 파라미터. ED_TRANSVIDEO_SET_OUTPUT (비디오 트랜스폴트 출력 파라미터) 또는 ED_TRANSVIDEO_SET_SOURCE (비디오 트랜스폴트 입력 소스)를 지정한다.
pValue
[out] 비디오 파라미터를 받는 변수에의 포인터. Param 에 ED_TRANSVIDEO_SET_SOURCE 가 지정되고 있는 경우,pValue 는 실제의 비디오 입력을 받는다. Param 에 ED_TRANSVIDEO_SET_OUTPUT 가 지정되고 있는 경우,pValue 는 다음의 몇개의 값을 받는다.
ED_E2E | 트랜스폴트 모드에 관계없이, 디바이스의 출력에 입력 영상이 표시된다.
ED_OFF | 영상 출력이 무효이다.
ED_PLAYBACK | 미디어의 재생 영상이 화면상에 표시된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtTransport::SetTransportVideoParameters

IAMExtTransport::put_AntiClogControl

IAMExtTransport 인터페이스

외부 트랜스폴트의 헤드 막혀 방지 컨트롤을 유효 또는 무효로 한다.

구문

HRESULT put_AntiClogControl(
    long Enable
);

파라미터

Enable
[in] 헤드 막혀 방지 컨트롤이 유효한가 어떤가를 나타내는 값. OATRUE 를 지정 하면 유효하게 되어, OAFALSE 를 지정 하면 무효가 된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면, 자동 헤드 클리닝 기능을 갖춘 VCR 의, 비디오 헤드의 힐를 막을 수가 있다.

참조

IAMExtTransport::get_AntiClogControl

IAMExtTransport::put_EditStart

IAMExtTransport 인터페이스

트랜스폴트의 에디트 컨트롤을 액티브하게 한다 (가능한 경우).

구문

HRESULT put_EditStart(
    long Value
);

파라미터

Value
[in] 에디트 컨트롤을 액티브하게 할지 어떨지를 나타내는 값. OATRUE 를 지정 하면 에디트 컨트롤이 액티브하게 되어 OAFALSE 를 지정 하면비 액티브하게 된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면, 에디트 컨트롤을 수동으로 유효하게 할 수 있다. 에디트 컨트롤은, VCR 위에의 개별의 레코드 트럭, 또는 레코드 트럭세트를 정확하게 유효화하는 것으로서 정의된다. 예를 들어, 비디오만의 삽입 편집에서는, 비디오 레코드 헤드만이 유효화 되어 새로운 비디오 신호가 기록된다. 오디오 신호는 변화하지 않는다. 이 메소드를 사용 하면, 이 기능을 가지는 머신상에서 온더 플라이 편집을 제어할 수 있다.

참조

IAMExtTransport::get_EditStart

IAMExtTransport::put_LocalControl

IAMExtTransport 인터페이스

외부 트랜스폴트 상태를 로컬 제어 또는 리모트 제어로 설정한다.

구문

HRESULT put_LocalControl(
    long State
);

파라미터

State
[in] 현재 상태. OATRUE 를 지정 하면 로컬이 되어, OAFALSE 를 지정 하면 리모트가 된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtTransport::get_LocalControl

IAMExtTransport::put_MediaState

IAMExtTransport 인터페이스

미디어의 현재 상태를 설정한다.

구문

HRESULT put_MediaState(
    long State
);

파라미터

State
[in] 상태를 지정하는 값. 다음의 어느쪽이든을 사용한다.
ED_MEDIA_SPIN_DOWN | 스핀을 정지한다 (디스크 미디어의 경우). 테이프를 안 thread 한다 (테이프 미디어의 경우).
ED_MEDIA_SPIN_UP | 스핀을 시작 한다 (디스크 미디어의 경우). 테이프를 thread 한다 (테이프 미디어의 경우).
ED_MEDIA_UNLOAD | 드라이브로부터 미디어를 이젝트 한다 (디바이스가 기능을 지원 하고 있는 경우).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

디스크 미디어와 테이프 미디어에 대해서는, 위에의 파라미터를 사용한다. 다른 디바이스에 대해서는, 경우에 따라서는 새로운 파라미터를 지정할 필요가 있다.

참조

IAMExtTransport::get_MediaState

IAMExtTransport::put_Mode

IAMExtTransport 인터페이스

새로운 트랜스폴트 모드 (재생, 정지, 기록, 편집등)에의 이행을 설정한다

구문

HRESULT put_Mode(
    long Mode
);

파라미터

Mode
[in] 트랜스폴트 모드. 다음의 어느쪽이든을 지정한다.
ED_MODE_PLAY | 재생.
ED_MODE_STOP | 정지.
ED_MODE_FREEZE | 포즈.
ED_MODE_THAW | 재개.
ED_MODE_FF | 빨리 감기.
ED_MODE_REW | 되감아.
ED_MODE_RECORD | 기록.
ED_MODE_RECORD_STROBE | 싱글 프레임 기록.
ED_MODE_STEP_FWD | 순서 방향의 싱르스텝.
ED_MODE_STEP_REV | 역방향의 싱르스텝.
ED_MODE_SHUTTLE | 셔틀 (고속 재생). 트랜스폴트 속도를 설정하려면 ,IAMExtTransport::put_Rate 와 함께 사용한다.
ED_MODE_EDIT_CUE | 액티브한 편집 이벤트의 위치에 머리 내 한다.
ED_MODE_LINK_ON | 이 메소드를 그래프의 IMediaControl::Run ,Stop , 및 Pause 메소드에 링크한다.
ED_MODE_LINK_OFF | 이 메소드를 그래프의 IMediaControl::Run ,Stop , 및 Pause 메소드로부터 해방한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMExtTransport::get_Mode

IAMExtTransport::put_Rate

IAMExtTransport 인터페이스

속도 변경이 가능한 외부 디바이스의 재생 속도를 설정한다.

구문

HRESULT put_Rate(
    double dblRate
);

파라미터

dblRate
[in] 재생 속도의 배수를 지정한다.. 5 는 2 분의 1, 1 은 표준, 2 는 2 배, 3 은 3 배를 나타낸다. 이후에 대해서도 같이이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드에 의해, 어플리케이션은, 보통의 디폴트의 재생 속도를 기준에, 재생을 가속화 또는 저속화할 수 있다. 레이트 1.0 은 보통의 재생 속도를 나타낸다. 2.0 을 지정 하면, 보통의 2 배의 속도로 재생된다.

이 메소드를 IMediaPosition::put_Rate 메소드에 링크해, 표준 속도를 기준에 재생 속도를 설정하는 대체의 수단으로 할 수도 있다.

참조

IAMExtTransport::get_Rate

IAMExtTransport::SetBump

IAMExtTransport 인터페이스

복수의 외부 디바이스의 동기를 잡기 위해서(때문에), 재생 속도를 일시적으로 변경한다.

구문

HRESULT SetBump(
    long Speed,
    long Duration
);

파라미터

Speed
[in] 일시 속도 (표준 속도의 배수).
Duration
[in] 현재의 타임 포맷으로 나타내지는 범프 시간폭.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드에 의해, 물리적인 동기 처리 시에, 트랜스폴트의 속도를 다양한 일시 속도로 변경할 수 있다. 이 메소드는,Duration 로 지정되는 시간이 경과할 때까지 유효하다.

지원 되는 타임 포맷에 대해서는, (SDK 루트) \Include\Edevdefs.h 안의 "IAMExtTransport Basic Parms" 를 참조할것.

참조

IAMExtTransport::GetBump

IAMExtTransport::SetChase

IAMExtTransport 인터페이스

체이스 모드를 유효 또는 무효로 한다.

구문

HRESULT SetChase(
    long Enable,
    long Offset,
    HEVENT hEvent
);

파라미터

Enable
[in] 체이스가 유효한가 어떤가를 나타내는 값. OATRUE 를 지정 하면 체이스는 유효하게 되어, OAFALSE 를 지정 하면 무효가 된다.
Offset
[in] 트랜스폴트가 보관 유지하고 있는 타임 기준으로부터의 오프셋(offset). 현재의 타임 포맷으로 지정한다.
hEvent
[in] 설정되어 있는 오프셋(offset)를 통지하는 이벤트.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

SetChase 메소드는, 외부 트랜스폴트가 고정의 오프셋(offset)로 타임 코드 신호에 연속적으로 따르는 경우에 사용한다. 예를 들어, 컴퓨터가 타임 코드를 생성하고 있는 경우, 체이스의 기능을 갖추고 있는 VCR 에 대해서, 자신은 재생 모드를 설정해, 미디어는 기준 타임 코드로부터의 오프셋(offset)를 보관 유지하는 것을 지정할 수 있다. 오프셋(offset)는, 재생 미디어의 타임 코드와 생성된 기준 타임 코드를 비교하는 것으로 결정한다.

이 메소드는, 메소드가 캔슬 또는 완료할 때까지 유효하다. 또, 필터에 대해서, 트랜스폴트의 타임 코드를 정기적으로 읽어내는 것에 의해, 트랜스폴트가 정말로 고정 오프셋(offset)를 보관 유지하고 있을지 어떨지, 확인하는 것을 요구한다.

Offset 의 시간은, 현재의 타임 포맷으로 지정한다. 지원 되는 타임 포맷에 대해서는, (SDK 루트) \Include\Edevdefs.h 안의 "IAMExtTransport Basic Parms" 를 참조할것.

참조

IAMExtTransport::GetChase

IAMExtTransport::SetEditProperty

IAMExtTransport 인터페이스

특정의 편집 프로퍼티 세트에 관련지을 수 있고 있는 개별의 파라미터와 값을 정의한다.

구문

HRESULT SetEditProperty(
    long EditID,
    long Param,
    long Value
);

파라미터

EditID
[in] 편집 프로퍼티 세트의 ID 번호.
Param
[in] 정의하는 편집 이벤트 파라미터.
Value
[in] Param 로 지정되는 파라미터의 값. OATRUE, OAFALSE, 또는 고유의 값을 사용한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

편집 이벤트는, 실제의 기록 순서를 정의하는 정의 끝난 프로퍼티의 그룹을 참조할것도, 단순한 위치 지정 커멘드를 참조할것도 할 수 있다. 예를 들어, 편집의 특정의 모드의 지정, IN 점과 OUT 점의 기록, 또는 북마크로 불리는 위치의 기억등을 실시할 수가 있다. SetEditPropertySet 메소드는, 편집 프로퍼티 세트로 불리는 편집 프로퍼티의 그룹을 생성 또는 등록하는 것이다. 한편 SetEditProperty 에 의해, 유저는 각 편집이벤트의 파라미터와 값을 정의할 수 있다. 이것은 비교적 고도의 기술을 필요로 하므로, 이행은 상급 개발자가 담당한다.

편집 프로퍼티세트를 정의하려면 , 최초로 편집 프로퍼티 세트를 등록해,SetEditPropertySet 메소드로 EditID 를 취득한다. 다음에,SetEditProperty 메소드를 사용해, 각 편집프로퍼티의 고유의 파라미터와 값을 정의한다. 마지막으로,SetEditPropertySet 메소드로 편집 프로퍼티 세트를 액티브하게 한다.

Edevdefs.h 파일 헤더 파일에는, 편집 프로퍼티 세트의 유효한 파라미터와 값이 일람 되고 있다.

참조

IAMExtTransport::GetEditProperty

IAMExtTransport::SetEditPropertySet

IAMExtTransport 인터페이스

편집 프로퍼티의 그룹인 편집 프로퍼티 세트를 등록한다.

구문

HRESULT SetEditPropertySet(
    long *pEditID,
    long State
);

파라미터

pEditID
[in, out] 편집 프로퍼티 세트의 ID 번호에의 포인터.
State
[in] 편집 프로퍼티 세트 상태. 다음의 어느쪽이든을 지정한다.
DC_SET_ACTIVE | 편집 프로퍼티 세트를 액티브하게 한다.
DC_SET_DELETE | 편집 프로퍼티 세트를 삭제한다.
DC_SET_INACTIVE | 편집 프로퍼티 세트를 비액티브하게 한다.
DC_SET_REGISTER | 편집 프로퍼티 세트를 등록한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

편집 이벤트는, 트랜스폴트 위에의 실제의 기록 순서나 단순한 위치 지정 커멘드를 정의한다, 정의 끝난 프로퍼티의 그룹을 참조한다. 예를 들어, 편집의 특정의 모드의 지정, IN 점과 OUT 점의 기록, 또는 북마크로 불리는 위치의 기억등을 실시할 수가 있다. SetEditPropertySet 메소드는, 편집 프로퍼티 세트로 불리는 편집 프로퍼티의 그룹을 정의 및 등록하는 것이다. 한편 SetEditProperty 에 의해, 유저는 각 편집이벤트 프로퍼티의 파라미터와 값을 정의할 수 있다.

편집 프로퍼티세트를 정의하려면 , 최초로 편집 프로퍼티 세트를 등록해,SetEditPropertySet 메소드로 EditID 를 취득한다. 다음에,SetEditProperty 메소드를 사용해, 각 편집프로퍼티의 고유의 파라미터와 값을 정의한다. 마지막으로,SetEditPropertySet 메소드로 편집 프로퍼티 세트를 액티브하게 한다.

예를 들어, 다음의 코드에서는, 모든 트럭상에서 인서트 편집을 설정한다.

// 편집 프로퍼티 세트 ID 를 등록한다 (메모리를 할당할 수 있다).
SetEditPropertySet(&EditID, ED_REGISTER);

// 편집 모드를 설정한다.
SetEditProperty(EditID, ED_EDIT_MODE, ED_EDIT_MODE_INSERT);

// 이벤트의 상세를 설정한다.
SetEditProperty(EditID, ED_EDIT_TRACK, ED_VIDEO | ED_AUDIO_ALL);
SetEditProperty(EditID, ED_REHEARSE_MODE, ED_EDIT_PERFORM);

// (기록과 소스의 시간등을 설정한다. )

SetEditPropertySet(pEditID, ED_ACTIVE); // 액티브하게 한다.
SetEditProperty(EditID, ED_EDIT_SEEK, OATRUE); // 머신을 머리 내 한다.

// (그래프를 기동한다. )

즉시 편집을 실시하려면 ("온더 플라이"편집), ED_EDIT_IMMEDIATE 편집 프로퍼티를 사용한다.

편집 프로퍼티 세트의 메카니즘을 사용해, 타임 코드 검색을 실시할 수도 있다. 이 때문에는, 다음의 프로퍼티를 설정한다.

  1. ED_EDIT_SRC_INPOINT 에 목적의 타임 코드값을 설정한다.
  2. ED_EDIT_SEEK_MODE 에 ED_EDIT_SEEK_EDIT_IN 를 설정한다.
  3. ED_EDIT_SEEK 에 OATRUE 를 설정한다. 검색 조작이 기동된다.

VCR 제어 필터에서는, 편집과 동기 제어에 관한 각종 모드의 1 개를 지원 할 수 있다.

  • 1 대의 머신을 사용해, 이 머신이 마스터로서 사용되는 모드 : 이것은, 논리니아 편집에 있어 가장 일반적인 구성이다. 1 대의 VCR 로, 소스 머트리얼의 캡춰와 최종 결과의 기록을 한다. VCR 의 타임 코드가, 필터 그래프의 master clock 기준으로서 사용된다. 이 모드에서는, VCR 에 대해 요구되는 기계적인 동기화의 필요성이 가장 적다. 이것은, 외부의 기계 제어의 디바이스에 비해, 디지털 재생 엔진이 간단하게 기준 클락에 동기 할 수가 있기 때문에 있다.
  • 1 대의 머신을 사용해, 기준 클락에 동기 하는 모드 : 1 대의 VCR 로 캡춰와 재생을 실시한다. VCR 는, 필터 그래프의 기준 클락에 동기 한다.
  • 복수의 머신을 사용해, 그 중의 1 개가 마스터로서 사용되는 모드 : 이것은, 리니어 편집 및 하이브리드(hybrid) 편집에 있어 가장 일반적인 구성이다. 필터 그래프의 클락은 마스터 (기록) VCR 에 동기 해, 재생 VCR 는 필터 그래프의 클락에 동기 하는 것이 요구된다.
  • 복수의 머신을 사용해, 모든 머신을 기준 클락에 동기 하는 모드 : 이것도, 리니어 편집 및 하이브리드(hybrid) 편집에 있어 일반적인 구성이다. 모든 VCR 는 필터 그래프의 클락에 동기 한다.

특정의 디바이스의 마스터/종속 모드를 판별하려면 ,IAMExtTransport::GetCapability 메소드로 ED_TRANSCAP_IS_MASTER 의 항목을 확인한다.

SMPTE 타임 코드를 사용해 필터 그래프 재생을 마스터 VCR 에 동기 시키는 것은, 비교적 간단하다. IAMTimecodeReader::GetTimecode 메소드로부터 돌려주어지는 TIMECODE_SAMPLE 에는, VCR 의 프레임 위치와 필터 그래프의 클락과의 사이의 시간의 관계를 나타내는, 기준 클락의 타임 스탬프가 포함된다. 이 오프셋(offset)를 사용하는 것으로, 스트림 컨트롤 인터페이스로 재생의 디지털 캡춰를 기동할 수 있다.

VCR 를 필터 그래프의 클락에 동기 시키려면 , VCR 제어 필터에 목적의 타임 오프셋(offset)를 보낼 필요가 있다. 가장 단순한 케이스에서는,IAMExtTransport::SetChase 메소드를 실행하는 것에 의해 이것을 실현할 수 있다. 1 개(살) 또는 복수의 이벤트 편집을 지원 하고 있는 경우는, 편집 프로퍼티 세트의 ED_EDIT_OFFSET 프로퍼티를 사용한다.

편집 프로퍼티 세트의 유효한 파라미터 및 값의 일람에 대해서는,[DXMedia\Include] 폴더안의 Edevdefs.h 를 참조할것.

참조

IAMExtTransport::GetEditPropertySet

IAMExtTransport::SetTransportAudioParameters

IAMExtTransport 인터페이스

외부 트랜스폴트의 오디오 파라미터의 설정값을 설정한다.

구문

HRESULT SetTransportAudioParameters(
    long Param,
    long Value
);

파라미터

Param
[in] 설정하는 오디오 파라미터. 다음의 어느쪽이든을 지정한다.
ED_TRANSAUDIO_ENABLE_OUTPUT | 출력용의 오디오 채널을 유효하게 한다.
ED_TRANSAUDIO_ENABLE_RECORD | 녹음용의 오디오 채널을 유효하게 한다.
ED_TRANSAUDIO_ENABLE_SELSYNC | selsync 녹음용의 오디오 채널을 유효하게 한다.
ED_TRANSAUDIO_SET_MONITOR | 모니터 출력 소스를 설정한다.
ED_TRANSAUDIO_SET_SOURCE | 액티브한 오디오 입력을 설정한다.
Value
[in] 파라미터를 설정하는 오디오 채널.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

ED_AUDIO_1 로부터 ED_AUDIO_24 의 범위의 어느쪽이든을 선택하는 것에 의해,Value 에 정확한 채널을 지정한다. 복수의 채널을 지정하려면 ,or 스윗치를 사용한다. 모든 채널을 지정하려면 , ED_AUDIO_ALL 를 선택한다.

참조

IAMExtTransport::GetTransportAudioParameters

IAMExtTransport::SetTransportBasicParameters

IAMExtTransport 인터페이스

외부 트랜스폴트의 기본 파라미터를 설정한다.

구문

HRESULT SetTransportBasicParameters(
    long Param,
    long Value,
    LPCOLESTR pszData
);

파라미터

Param
[in] 설정하는 파라미터. 지정할 수 있는 파라미터에 대해서는, Edevdefs.h 안의 "IAMExtTransport Basic Parms" 를 참조할것.
Value
[in] 수치형의 파라미터의 설정값.
pszData
[in] 캐릭터 라인형의 파라미터의 설정값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

기본 설정에는, 타임 포맷, 기록 방식,프리로르 설정,서보 설정등이 포함된다. Edevdefs.h 를 참조할것.

참조

IAMExtTransport::GetTransportBasicParameters

IAMExtTransport::SetTransportVideoParameters

IAMExtTransport 인터페이스

외부 트랜스폴트의 비디오 파라미터를 설정한다.

구문

HRESULT SetTransportVideoParameters(
    long Param,
    long Value
);

파라미터

Param
[in] 설정하는 비디오 파라미터. ED_TRANSVIDEO_SET_OUTPUT (비디오 트랜스폴트 출력 파라미터) 또는 ED_TRANSVIDEO_SET_SOURCE (비디오 트랜스폴트 물리 입력)를 지정한다.
Value
[in] ED_TRANSVIDEO_SET_SOURCE 플래그를 설정하는 경우는, 액티브한 비디오 입력을 지정한다. ED_TRANSVIDEO_SET_OUTPUT 플래그를 설정하는 경우는, 다음의 몇개의 값을 지정한다.
ED_E2E | 트랜스폴트 모드에 관계없이, 디바이스의 출력에 입력 영상이 표시된다.
ED_OFF | 영상 출력이 무효이다.
ED_PLAYBACK | 미디어의 재생 영상이 화면상에 표시된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

ED_TRANSVIDEO_SET_SOURCE 플래그의 경우, 외부 디바이스 필터는 물리적인 핀을 사용해 그 입력을 기술한다. 필터의 핀의 열거형을 호출하면, 인덱스값이 돌려주어진다. 그 값은 Value 파라미터로서 이 메소드에게 건네진다.

참조

IAMExtTransport::GetTransportVideoParameters


IAMFilterMiscFlags 인터페이스

IAMFilterMiscFlags 인터페이스는, 필터 그래프 매니저에 대해서, 필터의 데이터 스트림이 소스 데이터 또는 렌더링 되는 데이터의 어디에서 있는지를 판별하는 수단을 제공한다. 이것을 바탕으로, 예측되는 무비 종료시까지의 EC_COMPLETE 통지의 개수를 판별할 수 있다. 이 인터페이스는,VFW 캡춰 필터,파일 라이터, 및오디오 캡춰 필터로 이행 된다.

어플리케이션으로 이 인터페이스를 사용할 것은 없다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMFilterMiscFlags 메소드 | 설명
GetMiscFlags | 필터 상태 플래그를 취득한다.

IAMFilterMiscFlags::GetMiscFlags

IAMFilterMiscFlags 인터페이스

필터 상태 플래그를 취득한다.

구문

ULONG GetMiscFlags(void);

반환값

스트림이 렌더링 되고 있는 경우는, AM_FILTER_MISC_FLAGS_IS_RENDERED 를 돌려준다. 스트림이 소스 데이터의 경우는, AM_FILTER_MISC_FLAGS_IS_SOURCE 를 돌려준다. 양쪽 모두의 플래그는,AM_FILTER_MISC_FLAGS 열거형으로 정의된다. 필터가 IMediaSeeking 를 지원 해, 몇개의 스트림을 렌더링 하는 경우, AM_FILTER_MISC_FLAGS_IS_RENDERER 가 돌려주어진다.


IAMGraphStreams 인터페이스

이 인터페이스는, 라이브 소스를 렌더링 하는 필터 그래프의, 동작을 제어하는 메소드를 갖추고 있다. 라이브 소스란, 캡춰 디바이스나 네트워크 브로드캐스트와 같이, 리얼타임에 데이터를 스트림 하는 것이다. 필터 그래프 매니저는, 이 인터페이스를 이행 하고 있다.

어플리케이션에서는 이 인터페이스의 메소드를 호출하는 것에 의해, 라이브 소스를 렌더링 할 때의지연 시간과 동기화를, 그래프가 처리하는 방법을 지정할 수 있다. 상세한 것에 대하여는, 「라이브 소스」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMGraphStreams 메소드 | 설명
FindUpstreamInterface | 지정의 핀으로부터 업 스트림 방향으로, 지정의 인터페이스를 지원 하는 핀 또는 필터를 검색한다.
SyncUsingStreamOffset | 타임 스탬프 오프셋(offset)를 사용해 동기화를 유효 또는 무효로 한다.
SetMaxGraphLatency | 그래프의 최대 지연 시간을 설정한다.

IAMGraphStreams::FindUpstreamInterface

IAMGraphStreams 인터페이스

지정의 핀으로부터 업 스트림 방향으로, 지정의 인터페이스를 지원 하는 핀 또는 필터를 검색한다.

구문

HRESULT FindUpstreamInterface(
    IPin *pPin,
    REFIID riid,
    void **ppvInterface,
    DWORD dwFlags
);

파라미터

pPin
[in] 검색을 시작 하는 핀의 IPin 인터페이스에의 포인터.
riid
[in] 검색하는 인터페이스의 참조 식별자.
ppvInterface
[out, iid_is(riid)] void 형 포인터의 주소. 메소드가 성공했을 경우, 이 변수는 riid 로 지정되는 인터페이스에의 포인터를 받는다.
dwFlags
[in] AM_INTF_SEARCH_FLAGS 열거형으로 정의되는 플래그의 편성. 검색 대상 (핀 또는 필터)을 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

E_NOINTERFACE | 인터페이스가 발견되지 않는다.
E_POINTER | 무효인 포인터.
S_OK | 성공.

IAMGraphStreams::SetMaxGraphLatency

IAMGraphStreams 인터페이스

그래프의 최대 지연 시간을 설정한다. 이 메소드를 호출하기 전에,SyncUsingStreamOffset 메소드를 호출할 필요가 있다.

구문

HRESULT SetMaxGraphLatency(
    REFERENCE_TIME rtMaxGraphLatency
);

파라미터

rtMaxGraphLatency
[in] 최대 지연 시간을 지정하는 기준 타임.

반환값

성공했을 경우는, S_OK 를 돌려준다. SyncUsingStreamOffset 가 불려 가지 않은 경우는, E_FAIL 를 돌려준다. 그 이외의 경우는, 다른 HRESULT 값을 돌려준다.

주의

라이브 소스 필터에 따라서는, 접속시에, 최대 지연 시간을 사용해, 할당하는 버퍼의 사이즈를 확인한다. 그래프를 생성 하기 전에 이 메소드를 호출하는 것에 의해, 예기 되는 지연 시간에 대해서 충분한 버퍼를 할당할 수 있고 있는 것을 확인할 수 있다.

IAMGraphStreams::SyncUsingStreamOffset

IAMGraphStreams 인터페이스

타임 스탬프 오프셋(offset)를 사용해, 동기화를 유효 또는 무효로 한다.

구문

HRESULT SyncUsingStreamOffset(
    BOOL bUseStreamOffset
);

파라미터

bUseStreamOffset
[in] 타임 스탬프 오프셋(offset)를 사용할지 어떨지를 나타내는 불리언 값. TRUE 를 지정 하면, 라이브 소스는 타임 스탬프 오프셋(offset)를 사용해 스트림의 동기를 잡는다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

디폴트에서는, 필터 그래프가, 타임 스탬프 오프셋(offset)를 사용해 라이브 스트림의 동기화를 시도할 것은 없다. 필터 그래프에 대해서, 그래프내의 최대 지연 시간을 조사해 거기에 따라서 타임 스탬프를 조정하는 것을 요구하는 경우는, TRUE 의 값을 지정해 이 메소드를 호출한다. 상세한 것에 대하여는, 「IAMPushSource::SetStreamOffset 」를 참조할것.


IAMLatency 인터페이스

이 인터페이스는, 그래프에 적용되는지연 시간을 보고하는, 필터용의 메소드를 갖추고 있다. 지연 시간은, 필터가 샘플을 처리하는데 필요로 하는 시간으로서 정의된다. 소스 필터의 경우, 지연 시간은, 필터의 최대 버퍼 사이즈를 시간의 단위로 나타낸 것이다. 예를 들어, 30 프레임/초의 속도로 1 프레임을 버퍼링 하는 비디오 캡춰 필터의 경우, 지연 시간은 약 33 밀리 세컨드가 된다.

현재로서는, 이 인터페이스 자체의 사용은 지원되어 있지 않다. 라이브 데이터 또는 리얼타임 데이터를 스트림 하는 소스 필터는, 이 인터페이스를 계승하는 IAMPushSource 인터페이스를 이행 할 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMLatency 메소드 | 설명
GetLatency | 이 필터에 관련지을 수 있고 있는, 예기 되는 지연 시간을 취득한다.

IAMLatency::GetLatency

IAMLatency 인터페이스

이 필터에 관련지을 수 있고 있는, 예기 되는 지연 시간을 취득한다.

구문

HRESULT GetLatency(
    REFERENCE_TIME *prtLatency
);

파라미터

prtLatency
[in] 지연 시간을 나타내는 기준 타임을 받는 변수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.


IAMLine21Decoder 인터페이스

IAMLine21Decoder 인터페이스는,Line 21 디코더 필터로 이행 된다. 이 인터페이스는, 자막 방송 정보나 그 설정에 액세스 하는 기능을 갖추고 있어 주로, 어플리케이션이 자막 방송의 표시를 온 또는 오프로 할 경우에 사용된다.

자막 방송 정보는, 텔레비젼 신호의수직 동기 간격 (VBI) 내의필드 1 의 Line 21 상에서 전송 된다. 비디오카세트 레코더는 이 정보를 비디오 테잎에 기록하므로,Line 21 디코더 필터 및 그 외의 Microsoft® DirectShow® 필터를 사용하는 것으로, Line 21 데이터를 캡춰 해, 이것을 AVI (Audio-Video Interleaved)등의 미디어 파일 포맷으로 디스크에 보존할 수 있다. 자막 방송 정보는, 미디어 파일내에서 다른 스트림으로서 표시된다.

자막 방송 텍스트는, 현재, DVD 무비에 가세해 텔레비젼의 생방송 프로그램에서도 사용되고 있다. DVD 무비의 경우는, 비디오 스트림내의 각 GOP (Group of Pictures)의 유저 데이터 섹션의 일부로서 Line 21 데이터를 저장 한다. WDM (Windows Driver Model) 드라이버를 갖춘 텔레비젼 리시버 카드가, Line 21 데이터를 제공한다.

어플리케이션이 GetDrawBackgroundMode 메소드와 SetDrawBackgroundMode 메소드를 호출하는 것에 의해, 유저는 반투명인 자막 방송 표시 또는 불투명한 자막 방송 표시를 선택할 수 있다.

요건

Il21dec.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMLine21Decoder 메소드 | 설명
GetDecoderLevel | 자막 방송 디코더 레벨을 취득한다.
GetCurrentService | 유저에 의해 선택되고 있는 현재의 자막 방송 서비스를 취득한다.
SetCurrentService | 현재의 자막 방송 서비스를 설정한다.
GetServiceState | 자막 방송 서비스 상태 (온 또는 오프)를 취득한다.
SetServiceState | 자막 방송 서비스 상태를 설정한다.
GetOutputFormat | 사이즈나 비트 깊이등의 출력 비디오 특성에 관한 정보를 취득한다.
SetOutputFormat | DirectShow Line 21 디코더 필터에서는 이행 되지 않는다. 사이즈나 비트 깊이등의 출력 비디오 특성에 관한 정보를 설정한다.
GetBackgroundColor | 오버레이의 백그라운드로서 사용하는 물리적인 색을 취득한다.
SetBackgroundColor | 오버레이의 백그라운드로서 사용하는 물리적인 색을 설정한다.
GetRedrawAlways | 렌더러가, 각 샘플의 출력 비트 맵 전체를 재드로잉(Drawing) 할지 어떨지를 취득한다.
SetRedrawAlways | 렌더러가, 각 샘플의 출력 비트 맵 전체를 재드로잉(Drawing) 하는 것을 설정한다.
GetDrawBackgroundMode | 자막 방송 텍스트의 배경이 불투명 또는 투명한가 어떤가를 취득한다.
SetDrawBackgroundMode | 자막 방송 텍스트의 배경을 불투명 또는 투명하게 설정한다.

IAMLine21Decoder::GetBackgroundColor

IAMLine21Decoder 인터페이스

오버레이의 백그라운드로서 사용하는 물리적인 색을 취득한다.

구문

HRESULT GetBackgroundColor(
    DWORD *pdwPhysColor
);

파라미터

pdwPhysColor
백그라운드 칼라를 나타내는 취득값에의 포인터. 칼라값은 DWORD 형으로, 비트 단위의 OR 로 묶은 RGB 3 원색으로 구성된다. 각 칼라 컴퍼넌트의 비트수는, 현재의 비트 깊이에 따라서 다르다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

주의

디폴트의 백그라운드 칼라는 마젠타이다.

참조

IAMLine21Decoder::SetBackgroundColor

IAMLine21Decoder::GetCurrentService

IAMLine21Decoder 인터페이스

유저에 의해 선택되고 있는 현재의 자막 방송 서비스를 취득한다.

구문

HRESULT GetCurrentService(
    AM_LINE21_CCSERVICE *lpService
);

파라미터

lpService
현재의 서비스에의 포인터. 이 값은,AM_LINE21_CCSERVICE 열거형의 멤버이다. 디폴트 서비스는 AM_L21_CCSERVICE_Caption1 이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

참조

IAMLine21Decoder::SetCurrentService

IAMLine21Decoder::GetDecoderLevel

IAMLine21Decoder 인터페이스

자막 방송 디코더 레벨을 취득한다.

구문

HRESULT GetDecoderLevel(
    AM_LINE21_CCLEVEL *lpLevel
);

파라미터

lpLevel
취득되는 디코더 레벨에의 포인터. AM_L21_CCLEVEL_TC2 (TC2)만이 채널 레벨로서 지원 되고 있다. 이것은, 원의 TC1 레벨을 확장한 것으로, 후방 호환성을 갖추고 있다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

주의

이 메소드는, 정보의 참조 전용이다.

TC1 및 TC2 는 텔레비젼 세트의 디코더 레벨로, 텔레비젼이 자막 방송의 바이트 페어를 처리해 목적의 자막 방송을 출력할 수 있을지 어떨지를 나타낸다. Line 21 디코더는 TC2 레벨의 디코드 기능을 갖추고 있어 이것에는 모든 TC1 디코드 기능이 포함된다. 자막 방송 표시 기능이 짜넣어져 제조된 텔레비젼 세트 가운데, 최초의 100,000 대는 TC1 준거였다. 이후의 TV 세트는 TC2 준거이다.

IAMLine21Decoder::GetDrawBackgroundMode

IAMLine21Decoder 인터페이스

자막 방송 텍스트의 백그라운드가 불투명 또는 투명한지 어떤지를 취득한다.

구문

HRESULT GetDrawBackgroundMode(
    AM_LINE21_DRAWBGMODE *lpMode
);

파라미터

lpMode
취득되는 모드에의 포인터. 모드는 AM_L21_DRAWBGMODE_Opaque 또는 AM_L21_DRAWBGMODE_Transparent 이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

주의

디폴트에서는, 자막 방송의 백그라운드는 불투명하다.

참조

IAMLine21Decoder::SetDrawBackgroundMode

IAMLine21Decoder::GetOutputFormat

IAMLine21Decoder 인터페이스

사이즈나 비트 깊이등의 출력 비디오 특성에 관한 정보를 취득한다.

구문

HRESULT GetOutputFormat(
    LPBITMAPINFOHEADER lpbmih
);

파라미터

lpbmih
취득되는 BITMAPINFOHEADER 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

성공의 경우, 디폴트의 이행에서는,다운 스트림 필터가 출력 포맷을 정의하고 있지 않으면 S_FALSE, 출력 포맷이 정의되고 있으면 S_OK 를 돌려준다.

주의

디폴트의 비디오 출력 사이즈는 320 × 240 픽셀이다.

IAMLine21Decoder::GetRedrawAlways

IAMLine21Decoder 인터페이스

렌더러가 각 샘플의 출력 비트 맵 전체를 재드로잉(Drawing) 할지 어떨지를 취득한다.

구문

HRESULT GetRedrawAlways(
    LPBOOL lpbOption
);

파라미터

lpbOption
비트 맵 전체가 재드로잉(Drawing) 될지 어떨지를 나타내는 값. 디폴트값은 FALSE 로, 항상 재드로잉(Drawing) 된다고는 할 수 없는 것을 나타낸다. TRUE 는 항상 재드로잉(Drawing) 되는 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

참조

IAMLine21Decoder::SetRedrawAlways

IAMLine21Decoder::GetServiceState

IAMLine21Decoder 인터페이스

자막 방송 서비스 상태 (온 또는 오프)를 취득한다.

구문

HRESULT GetServiceState(
    AM_LINE21_CCSTATE *lpState
);

파라미터

lpState
취득되는 상태에의 포인터. 지원 되는 상태값은 AM_L21_CCSTATE_On 및 AM_L21_CCSTATE_Off 이다. 디폴트에서는, 자막 방송 텍스트는 오프이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

참조

IAMLine21Decoder::SetServiceState

IAMLine21Decoder::SetBackgroundColor

IAMLine21Decoder 인터페이스

오버레이의 백그라운드로서 사용하는 물리적인 색을 설정한다.

구문

HRESULT SetBackgroundColor(
    DWORD dwPhysColor
);

파라미터

dwPhysColor
물리적인 백그라운드 칼라를 지정하는 DWORD 값. 색은, 비트 단위의 OR 로 묶은 RGB 3 원색으로 지정된다. 각 칼라 컴퍼넌트의 비트수는, 현재의 비트 깊이에 따라서 다르다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

주의

디폴트의 백그라운드 칼라는 마젠타이다.

참조

IAMLine21Decoder::GetBackgroundColor

IAMLine21Decoder::SetCurrentService

IAMLine21Decoder 인터페이스

현재의 자막 방송 서비스를 설정한다.

구문

HRESULT SetCurrentService(
    AM_LINE21_CCSERVICE Service
);

파라미터

Service
설정하는 서비스. 이 값은,AM_LINE21_CCSERVICE 열거형의 멤버이다. 디폴트 서비스는 AM_L21_CCSERVICE_Caption1 이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

참조

IAMLine21Decoder::GetCurrentService

IAMLine21Decoder::SetDrawBackgroundMode

IAMLine21Decoder 인터페이스

자막 방송 텍스트의 백그라운드를 불투명 또는 투명하게 설정한다.

구문

HRESULT SetDrawBackgroundMode(
    AM_LINE21_DRAWBGMODE Mode
);

파라미터

Mode
설정하는 모드. 지원 되는 모드의 값은,AM_L21_DRAWBGMODE_Opaque 및 AM_L21_DRAWBGMODE_Transparent 이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

주의

디폴트에서는, 자막 방송의 백그라운드는 불투명하다.

참조

IAMLine21Decoder::GetDrawBackgroundMode

IAMLine21Decoder::SetOutputFormat

IAMLine21Decoder 인터페이스 이 메소드는, DirectShow® Line 21 디코더 필터에서는 이행 되지 않는다. 사이즈나 비트 깊이등의 출력 비디오 특성에 관한 정보를 설정한다.

구문

HRESULT SetOutputFormat(
    LPBITMAPINFO lpbmi
);

파라미터

lpbmi
목적의 출력 포맷을 저장 하고 있는 지정의 BITMAPINFO 구조체에의 포인터.

반환값

DirectShow Line 21 디코더 필터가 이행 하고 있는 인터페이스의 경우는, E_NOTIMPL 를 돌려준다.

주의

디폴트의 비디오 출력 사이즈는 320 × 240 픽셀이다.

참조

IAMLine21Decoder::GetOutputFormat

IAMLine21Decoder::SetRedrawAlways

IAMLine21Decoder 인터페이스

렌더러가 각 샘플의 출력 비트 맵 전체를 재드로잉(Drawing) 할지 어떨지를 설정한다.

구문

HRESULT SetRedrawAlways(
    BOOL bOption
);

파라미터

bOption
비트 맵 전체를 재드로잉(Drawing) 할지 어떨지를 나타내는 값. TRUE 는 항상 재드로잉(Drawing) 하는 것을 나타내, FALSE 는 항상 재드로잉(Drawing) 하면은 한정되지 않는 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

주의

필터가, Line 21 디코더 필터에 보내는 버퍼를 더티인 상태로 해 버렸을 경우는, 필터로부터 이 메소드를 호출한다. 보통, 믹서 필터는, Line 21 디코더 필터로부터 직접 다운 스트림 하고 있는 필터 그래프안에 있다. 믹서 필터는, 이 메소드를 호출해,bOption 에 TRUE 를 지정해, 비트 맵 전체가 올바르고 재드로잉(Drawing) 되는 것을 지정할 필요가 있다.

다운 스트림 믹서, 또는 그 처리가 필요한 임의의 믹서는, 세칸다리비데오스트림을 믹스 할 경우에 사용하는 버퍼와 같은 버퍼를, Line 21 디코더에 제공하는 경우만,bOption 에 TRUE 를 지정해 이 메소드를 호출할 필요가 있다.

bOption 에 TRUE 를 지정해 재드로잉(Drawing)를 실시하면, 가능한 최적화가 무효가 되므로, 퍼포먼스는 저하해, CPU 의 부하는 증가한다.

참조

IAMLine21Decoder::GetRedrawAlways

IAMLine21Decoder::SetServiceState

IAMLine21Decoder 인터페이스

자막 방송 서비스 상태를 설정한다.

구문

HRESULT SetServiceState(
    AM_LINE21_CCSTATE State
);

파라미터

State
지정하는 상태. 지원 되는 상태값은,AM_L21_CCSTATE_On 및 AM_L21_CCSTATE_Off 이다. 자막 방송 텍스트는, 디폴트에서는 오프이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 파라미터가 무효인 경우는 E_INVALIDARG, 또는 성공을 나타내는 NOERROR 를 돌려준다.

참조

IAMLine21Decoder::GetServiceState


IAMMediaContent 인터페이스

스트림으로부터 메타데이타를 취득한다. 어플리케이션은, 이 인터페이스를 사용해, 생성자, 타이틀, 저작권 등, 스트림에 encode 된 정보를 취득할 수 있다. 보통, 이 인터페이스는 AVI 스플리터나 MPEG-1 스트림 스플리터등의 퍼서 필터에 의해 공개된다.

스트림 타입에 따라서는, 필터는 이 인터페이스로 메소드의 서브 세트를 지원 하는 일이 있다. 예를 들어, AVI 스플리터는 AVI 파일의 INFO 체크로부터, 저작권, 생성자명, 및 타이틀을 취득한다. 다른 메소드는, E_NOTIMPL 를 돌려준다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스의 타입 정보를 이용할 수 있을지 어떨지를 판정한다.
GetTypeInfo | GetTypeInfoCount 가 올바르게 돌아가는 경우에, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | 인수를 포함한, 프로퍼티와 메소드의 텍스트명을, 해당하는 디스팟치 식별자 (DISPID)로 변환한다.
Invoke | DISPID 및 다른 필요한 파라미터가 있는 경우에, 이 디스프인타페이스의 메소드를 호출하는지, 그 프로퍼티에 액세스 한다.
IAMMediaContent 메소드 | 설명
get_AuthorName | 생성자명을 취득한다.
get_Title | 타이틀을 취득한다.
get_Rating | 레이팅을 취득한다.
get_Description | 내용의 설명을 취득한다.
get_Copyright | 저작권 정보를 취득한다.
get_BaseURL | 관련 Web 컨텐츠의 베이스 URL 를 취득한다.
get_LogoURL | 로고의 URL 를 취득한다.
get_LogoIconURL | 로고 아이콘의 URL 를 취득한다.
get_WatermarkURL | 워터 마크의 URL 를 취득한다.
get_MoreInfoURL | 내용에 관한 추가 정보의 URL 를 취득한다.
get_MoreInfoBannerImage | 관련 정보 배너의 이미지를 취득한다.
get_MoreInfoBannerURL | 관련 정보 배너의 URL 를 취득한다.
get_MoreInfoText | 추가 정보를 텍스트로서 취득한다.

IAMMediaContent::get_AuthorName

IAMMediaContent 인터페이스

생성자명을 취득한다.

구문

HRESULT get_AuthorName(
    BSTR *pbstrAuthorName
);

파라미터

pbstrAuthorName
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_Title

IAMMediaContent 인터페이스

타이틀을 취득한다.

구문

HRESULT get_Title(
    BSTR *pbstrTitle
);

파라미터

pbstrTitle
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_Rating

IAMMediaContent 인터페이스

레이팅을 취득한다.

구문

HRESULT get_Rating(
    BSTR *pbstrRating
);

파라미터

pbstrRating
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_Description

IAMMediaContent 인터페이스

내용의 설명을 취득한다.

구문

HRESULT get_Description(
    BSTR *pbstrDescription
);

파라미터

pbstrDescription
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_Copyright

IAMMediaContent 인터페이스

저작권 정보를 취득한다.

구문

HRESULT get_Copyright(
    BSTR *pbstrCopyright
);

파라미터

pbstrCopyright
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_BaseURL

IAMMediaContent 인터페이스

관련 Web 컨텐츠의 베이스 URL 를 취득한다.

구문

HRESULT get_BaseURL(
    BSTR *pbstrBaseURL
);

파라미터

pbstrBaseURL
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_LogoURL

IAMMediaContent 인터페이스

로고의 URL 를 취득한다.

구문

HRESULT get_LogoURL(
    BSTR *pbstrLogoURL
);

파라미터

pbstrLogoURL
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_LogoIconURL

IAMMediaContent 인터페이스

로고 아이콘의 URL 를 취득한다.

구문

HRESULT get_LogoIconURL(
    BSTR *pbstrLogoURL
);

파라미터

pbstrLogoURL
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_WatermarkURL

IAMMediaContent 인터페이스

워터 마크의 URL 를 취득한다.

구문

HRESULT get_WatermarkURL(
    BSTR *pbstrWatermarkURL
);

파라미터

pbstrWatermarkURL
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_MoreInfoURL

IAMMediaContent 인터페이스

내용에 관한 추가 정보의 URL 를 취득한다.

구문

HRESULT get_MoreInfoURL(
    BSTR *pbstrMoreInfoURL
);

파라미터

pbstrMoreInfoURL
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_MoreInfoBannerImage

IAMMediaContent 인터페이스

관련 정보 배너의 이미지를 취득한다.

구문

HRESULT get_MoreInfoBannerImage(
    BSTR *pbstrMoreInfoBannerImage
);

파라미터

pbstrMoreInfoBannerImage
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_MoreInfoBannerURL

IAMMediaContent 인터페이스

관련 정보 배너의 URL 를 취득한다.

구문

HRESULT get_MoreInfoBannerURL(
    BSTR *pbstrMoreInfoBannerURL
);

파라미터

pbstrMoreInfoBannerURL
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.

IAMMediaContent::get_MoreInfoText

IAMMediaContent 인터페이스

추가 정보를 텍스트로서 취득한다.

구문

HRESULT get_MoreInfoText(
    BSTR *pbstrMoreInfoText
);

파라미터

pbstrMoreInfoText
정보를 가지는 BSTR 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_NOT_FOUND | 항목은 발견되지 않았다.

주의

메소드가 성공했을 경우, 호출원래는 SysFreeString 함수를 호출해, 돌려주어진 BSTR 를 해방해야 한다.


IAMOpenProgress 인터페이스

파일 오픈 조작의 진행 상황을 리포트한다.

네트워크 넘어로 파일을 오픈하는 필터는 이 인터페이스를 공개할 수가 있다. 어플리케이션은 그것을 사용해 다운로드의 진행 상황을 문의할 수가 있다. 네트워크의 리스폰스가 나쁘면IGraphBuilder::RenderFile 와 같은 메소드는 무기한으로 블록 해 버릴지도 모른다. 어플리케이션이 블록 하는 것을 막기 위해서(때문에), 진행 상황을 모니터 하는 IAMOpenProgress 를 사용하는 워커 thread를 생성 하는 것. 사전에 정의된 타임 아웃이 일어난다, 혹은 유저로부터의 커멘드에 대응해, 그 워커 thread는 조작을 종료한다.

URL 파일 소스 필터는 이 인터페이스를 지원 한다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMOpenProgress 메소드 | 설명
QueryProgress | 파일 오픈 조작의 진행 상황을 취득한다.
AbortOperation | 파일 오픈 조작의 종료.

IAMOpenProgress::AbortOperation

IAMOpenProgress 인터페이스

파일 오픈 조작의 종료.

구문

HRESULT AbortOperation(void);

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는HRESULT 값을 돌려준다.

IAMOpenProgress::QueryProgress

IAMOpenProgress 인터페이스

파일 오픈 조작의 진행 상황을 취득한다.

구문

HRESULT QueryProgress(
    LONGLONG *pllTotal,
    LONGLONG *pllCurrent
);

파라미터

pllTotal
[out] 전파일의 길이를 받는 변수에의 포인터, 바이트 단위.
pllCurrent
[out] 파일의 다운로드한 길이를 받는 변수에의 포인터, 바이트 단위.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_S_ESTIMATED | 반환값은 평가된다.
E_UNEXPECTED | 예기치 못한 에러.


IAMOverlayFX 인터페이스

IAMOverlayFX 인터페이스는,오버레이 믹서 필터로 이행 된다. 이 인터페이스에 의해, 어플리케이션은, 유저의 화면상에서의 비디오 오버레이의 표시 방법을 제어할 수 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMOverlayFX 메소드 | 설명
QueryOverlayFXCaps | 오버레이 믹서 필터로 유효한 오버레이 이펙트에 관한 정보를 취득한다.
SetOverlayFX | 지정의 이펙트를 오버레이 표면에 적용한다.
GetOverlayFX | 오버레이 표면에 현재 적용되고 있는 이펙트가 있는 경우는, 이것을 취득한다.

IAMOverlayFX::GetOverlayFX

IAMOverlayFX 인터페이스

오버레이 표면에 현재 적용되고 있는 이펙트가 있는 경우는, 이것을 취득한다. 어플리케이션에서는, 필터 그래프의 실행중에 이 메소드를 호출할 수가 있다.

구문

HRESULT GetOverlayFX(
    DWORD *lpdwOverlayFX
);

파라미터

lpdwOverlayFX
[out] 오버레이 표면에 현재 적용되고 있는 이펙트가 있는 경우, 이것을 나타내는 값을 받는 변수에의 포인터. 값은,AMOVERLAYFX 열거형의 플래그의 논리합이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. Microsoft® DirectShow® 의 이행에서는, 성공의 경우는 S_OK 를 돌려준다. NULL 포인터 인수의 경우는 E_POINTER 를 돌려준다.

IAMOverlayFX::SetOverlayFX

IAMOverlayFX 인터페이스

지정의 이펙트를 오버레이 표면에 적용한다.

구문

HRESULT SetOverlayFX(
    DWORD dwOverlayFX
);

파라미터

dwOverlayFX
[in] 적용하는 이펙트를 지정하는 값. 값은,AMOVERLAYFX 열거형 플래그의 논리합이 아니면 안된다. 그 이외의 경우, 메소드는 E_INVALIDARG 를 돌려준다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. DirectShow 의 이행에서는, 다음의 몇개의 값, 또는 이외의 값을 돌려준다.

E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
S_OK | 성공.

주의

어플리케이션은, 필터 그래프의 실행중에 이 메소드를 호출할 필요가 있다. 이펙트는 즉시에 적용된다.

IAMOverlayFX::QueryOverlayFXCaps

IAMOverlayFX 인터페이스

오버레이 믹서 필터로 유효한 오버레이 이펙트에 관한 정보를 취득한다.

구문

HRESULT QueryOverlayFXCaps(
    DWORD *lpdwOverlayFXCaps
);

파라미터

lpdwOverlayFXCaps
[out] 오버레이 표면의 오버레이 이펙트 기능을 나타내는 값을 받는 변수에의 포인터. 값은,AMOVERLAYFX 열거형 플래그의 논리합이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. DirectShow 의 이행에서는, 다음의 몇개의 값을 돌려준다.

E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
S_OK | 성공.


IAMParse 인터페이스

이 인터페이스는,MPEG-2 스플리터로 이행 된다. 이 인터페이스에 의해, 어플리케이션은,해석 시간을 조회 및 설정할 수 있다. 해석 시간과는,퍼서 필터에 제공되는 바이트 스트림내에서의, 현재의 위치에 관련지을 수 있고 있는 개념 위에의 시간이다. 이 시간은타임 스탬프의 시점에도 대응하고 있어, 타임 스탬프의 0 은 해석 시간의 0 에 대응한다.

이 인터페이스를 사용 하면, 현재의 스트림의 해석 시간을 취득 또는 설정할 수 있다. 또는, 현재의 데이터의 데이터 버퍼를 클리어 할 수 있다.

요건

Amparse.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMParse 메소드 | 설명
Flush | 현재의 파일 버퍼를 비운다.
GetParseTime | 현재의 스트림 해석 시간을 취득한다.
SetParseTime | 현재의 스트림 해석 시간을 설정한다.

IAMParse::Flush

IAMParse 인터페이스

현재의 파일 데이터를 클리어 해, 새로운 파일에 한층 더 빨리 바꾼다.

구문

HRESULT Flush(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드에 의해 이행은 한층 더 즉시적으로 행해지지만, 심리스의 정도도 없어진다.

IAMParse::GetParseTime

IAMParse 인터페이스

현재의 스트림 해석 시간을 취득한다. MPEG-2 의 경우, 이것은, 현재의 스트림 위치에 대해서 계산되는 시스템 클록 타임에 대응한다.

구문

HRESULT GetParseTime(
  REFERENCE_TIME *ptrParseTime
  );

파라미터

ptrParseTime
[out] 현재의 해석 시간에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, VFW_E_NOT_CONNECTED 를 돌려준다. 후자는,입력 핀이 접속되어 있지 않기 위해(때문에) 해석 시간을 이용할 수 없는 것을 나타낸다.

주의

MPEG-2 스플리터 필터의 해석 시간은, 현재의 스트림 위치를 시스템 클록으로 나타낸 것이다. 해석 시간의 초기값은 0 이다.

IAMParse::SetParseTime

IAMParse 인터페이스

현재의 스트림 해석 시간을 설정한다. MPEG-2 의 경우, 이것은, 현재의 스트림 위치에 대해서 계산되는 시스템 클록 타임에 대응한다.

구문

HRESULT SetParseTime(
  REFERENCE_TIME rtPosition
  );

파라미터

rtPosition
[in] 현재의 스트림 해석 시간.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, VFW_E_NOT_CONNECTED 를 돌려준다. 후자는, 입력 핀이 접속되어 있지 않기 위해(때문에) 해석 시간을 설정할 수 없었던 것을 나타낸다.

주의

MPEG-2 스플리터 필터의 해석 시간은, 현재의 스트림 위치를 시스템 클록으로 나타낸 것이다. 해석 시간의 초기값은 0 이다.


IAMPushSource 인터페이스

이 인터페이스는, 라이브 소스를 렌더링 하는 필터 그래프의 동기를 잡는 메소드를 갖추고 있다. 라이브 소스란, 캡춰 디바이스나 네트워크 브로드캐스트와 같이, 리얼타임에 데이터를 스트리밍 하는 것이다. 이 인터페이스는,IAMLatency 인터페이스를 계승하고 있다.

라이브 데이터를 스트림 하는 소스 필터는, 그 출력 핀에 대해 이 인터페이스를 공개할 필요가 있다.

일반적으로, 어플리케이션은 이 인터페이스의 메소드를 호출해서는 안 된다. 대신에,IAMGraphStreams 인터페이스를 사용한다. 필터 그래프 매니저는, 이 인터페이스의 메소드를 사용해, 라이브 소스를 렌더링 할 경우에 공통되어 발생하는 2 개의 문제를 해결한다.

  • 지연 시간 : 필터 그래프에 복수의 라이브 소스가 포함되는 경우, 자주 그지연 시간이 각각 다르기 위해서(때문에), 동기가 취할 수 없는 것이 있다. 예를 들어, 오디오 캡춰의 지연 시간이 비디오 캡춰의 지연 시간보다 긴 경우, 필터 그래프가 그 상위를 보정하지 않는 한, 음성이 영상보다 늦어 버린다.
  • 레이트 매칭 : 렌더링 필터가 라이브 소스에 접속하고 있는 경우는, 그 데이터 소비 레이트를 조정해 소스 필터의 생성 레이트에 일치시킬 필요가 있다. 이 조작을 실시하지 않으면 데이터에 갭이 생기거나 (렌더러의 실행 속도가 소스보다 빠른 경우), 데이터가 결핍 해 버린다 (소스의 실행 속도가 빠른 경우).

지연 시간을 보정하기 위해서 필터 그래프는,IAMPushSource 인터페이스를 공개하고 있는 각 출력 핀에 대해 IAMLatency::GetLatency 를 호출해, 그래프내의 최대의 지연 시간을 조사한다. 다음에, 최대 지연 시간보다 지연 시간이 짧은 필터에 대해 IAMPushSource::SetStreamOffset 를 호출해, 각자가 생성하는 타임 스탬프를 올바른 오프셋(offset)로 조정한다.

레이트 매칭을 실행하기 위해서 필터 그래프는, 렌더링 필터가 클럭레이트를 소스 필터에 일치할 수 있을지 어떨지를 조사할 필요가 있다. IAMPushSource::GetPushSourceFlags 메소드에 의해, 렌더러가 레이트를 소스에 일치시켜도 문제가 있는지 없는지를 나타내는 플래그세트가 돌려주어진다.

이러한 문제는, 파일에의 캡춰에는 영향을 주지 않는다. 파일 라이터 필터는, 수신하는 샘플 위에의 타임 스탬프에 근거해 파일에 올바르게 기입한다. 이 후, 재생할 경우에 스트림의 동기화를 한다. 레이트 매칭에 관해서, 데이터는 항상 가능한 한 고속으로 파일에 기입해진다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMLatency 메소드 | 설명
GetLatency | 이 필터에 관련지을 수 있고 있는, 예기 되는 지연 시간을 취득한다.
IAMPushSource 메소드 | 설명
GetPushSourceFlags | 필터의 동작을 나타내는 플래그의 편성을 취득한다.
SetPushSourceFlags | 필터의 동작을 지정하는 플래그를 설정한다.
SetStreamOffset | 이 필터로 생성되는 타임 스탬프의 오프셋(offset)를 설정한다.
GetStreamOffset | 타임 스탬프를 생성할 경우에 필터가 사용하는 오프셋(offset)를 취득한다.
GetMaxStreamOffset | 필터를 지원 할 수 있는 최대 스트림 오프셋(offset)를 취득한다.
SetMaxStreamOffset | 최대 스트림 오프셋(offset)를 지정하는 기준 타임.

IAMPushSource::GetMaxStreamOffset

IAMPushSource 인터페이스

필터를 지원 할 수 있는 최대 스트림 오프셋(offset)를 취득한다.

구문

HRESULT GetMaxStreamOffset(
    REFERENCE_TIME *prtMaxOffset
);

파라미터

prtMaxOffset
[out] 필터를 지원 할 수 있는 최대 오프셋(offset)를 나타내는 기준 타임을 받는 변수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. Microsoft® DirectShow® 의 이행에서는, E_POINTER 또는 S_OK 를 돌려준다.

주의

스트림의 오프셋(offset)가, 지원 되는 최대 오프셋(offset)보다 큰 값으로 설정되는 경우, 오프셋(offset) 전체의 데이터를 보관 유지 가능한 한의 버퍼가, 필터에 준비된다고는 할 수 없다. 다른 버퍼 다운 스트림이 없는 한, 데이터가 없어질 가능성이 있다.

IAMPushSource::GetPushSourceFlags

IAMPushSource 인터페이스

필터의 동작을 나타내는 플래그의 편성을 취득한다.

구문

HRESULT GetPushSourceFlags(
    ULONG *pFlags
);

파라미터

pFlags
[out] AM_PUSHSOURCE_FLAGS 열거형으로 정의되는 플래그의 편성을 받는 변수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면, 렌더링 필터가 클럭레이트를 이 소스 필터에 확실히 일치할 수 있을지 어떨지를 판별할 수 있다.

IAMPushSource::GetStreamOffset

IAMPushSource 인터페이스

필터가 타임 스탬프를 생성할 경우에 사용하는 오프셋(offset)를 취득한다.

구문

HRESULT GetStreamOffset(
    REFERENCE_TIME  *prtOffset
);

파라미터

prtOffset
[out] 현재의 스트림 오프셋(offset)를 나타내는 기준 타임을 받는 변수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMPushSource::SetMaxStreamOffset

IAMPushSource 인터페이스

필터 그래프내에서 가능한 스트림 오프셋(offset)를 지정한다.

구문

HRESULT SetMaxStreamOffset(
    REFERENCE_TIME rtMaxOffset
);

파라미터

rtMaxOffset
[in] 최대 스트림 오프셋(offset)를 지정하는 기준 타임.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

필터를 접속하기 전에 이 메소드를 호출하면, 필터는 적절한 사이즈의 버퍼를 할당할 수가 있다.

IAMPushSource::SetPushSourceFlags

IAMPushSource 인터페이스

필터의 동작을 지정하는 플래그를 설정한다. 현재, 어플리케이션으로 이 메소드를 호출해서는 안 된다. 이것은, 요구 플래그가 지원되어 있지 않기 때문에, 필터가 설정한 플래그를 어플리케이션이 오버라이드(override) 해서는 안 되기 때문이다.

구문

HRESULT SetPushSourceFlags(
    ULONG Flags
);

파라미터

Flags
[in] AM_PUSHSOURCE_FLAGS 열거형으로 정의되는 플래그의 편성.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMPushSource::SetStreamOffset

IAMPushSource 인터페이스

이 필터로 생성되는 타임 스탬프의 오프셋(offset)를 설정한다.

구문

HRESULT SetStreamOffset(
    REFERENCE_TIME rtOffset
);

파라미터

rtOffset
[in] 필터의 새로운 스트림 오프셋(offset).

반환값

지정된 오프셋(offset)가, 필터로 가능한 최대 오프셋(offset)보다 큰 경우는, S_FALSE 를 돌려준다. 그 이외의 경우로, 성공했을 경우는 S_OK 를 돌려준다. 또는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

지연 시간이 각각 다른 스트림의 동기를 잡기 위해서(때문에), 필터 그래프는 이 메소드를 호출해 필터의 스트림 오프셋(offset)를 조정한다.

반환값이 S_FALSE 의 경우, 요구된 오프셋(offset)에 대응 가능한 한의 크기의 버퍼를, 필터가 지원 하지 않을 가능성이 있다. 다른 다운 스트림 버퍼가 없는 한, 데이터가 없어지는 일이 있다. 지원 할 수 있는 필터의 최대 오프셋(offset)를 취득하려면 ,GetMaxStreamOffset 메소드를 호출한다.


IAMResourceControl 인터페이스

IAMResourceControl 인터페이스에 의해, 어플리케이션은, 오디오 디바이스 리소스가 실제로 필요하게 되기 전에, 이것을 오픈해, 보관 유지할 수 있다. 이것에 의해, 재생이 가능한 것을 확인하거나 디바이스를 이용할 수 없는 것을 사전에 알 수 있다.

이용할 수 없는 것이 있는 리소스의 사용에 대비해, 필터에서는 IAMResourceControl 를 이행 할 수 있다. 이 필터는, Microsoft® DirectShow® 의오디오 캡춰 필터 및 오디오 렌더링 필터로 이행 된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMResourceControl 메소드 | 설명
Reserve | 디바이스 리소스를 예약 또는 예약 해제한다.

IAMResourceControl::Reserve

IAMResourceControl Interface

디바이스 리소스를 예약 또는 예약 해제한다.

구문

HRESULT Reserve(
    DWORD dwFlags
     PVOID pvReserved
);

파라미터

dwFlags
[in] 이 디바이스를 예약할지 어떨지를 나타내는 플래그. 지정할 수 있는 값에 대해서는, 「주의」를 참조할것.
pvReserved
[in] NULL 가 아니면 안된다.

반환값

디바이스가 예약 또는 예약 해제되었을 경우는, S_OK 를 돌려준다. 디바이스가 현재 예약되고 있어, 그 예약이 계속되는 경우는, S_FALSE 를 돌려준다. 디바이스를 예약할 수 없었던 경우는,HRESULT 에러 코드를 돌려준다.

주의

dwFlags 로 지정할 수 있는 값은,AMRESCTL_RESERVEFLAGS 열거형으로 정의된다.

중요 리소스는 몇 번이라도 예약할 수 있다. 예약 카운트는, S_OK 가 돌려주어졌을 경우에게만 인크리먼트(increment) 또는 감소 된다. S_OK 가 돌려주어지는, 디바이스를 예약하는 각 호출은, 디바이스의 예약을 해제하는 호출에 대응하고 있을 필요가 있다.


IAMStreamConfig 인터페이스

IAMStreamConfig 인터페이스는, 오디오 캡춰 필터, 비디오 캡춰 필터, 및 압축 필터의 출력 핀에 이행 된다. 이것에는,VFW 캡춰 필터,MJPEG 압력,ACM 래퍼,오디오 캡춰 필터, 및 AVI 압력 이 포함된다. 필터 개발자는, 오디오 데이터 또는 비디오 데이터를 처리하는 임의의 출력 핀에, 이 인터페이스를 이행 할 수 있다.

이 인터페이스에 의해, 어플리케이션은, 출력 핀으로 필터가 지원 하고 있는 포맷 타입에 대해 문의할 수가 있다. 또, 그 핀이, 다운 스트림에 접속되고 있는 핀에 제안하는 포맷을 설정할 수 있다. 이것에 의해, 어플리케이션은 핀으로 IGraphBuilder::Render 를 호출할 수가 있어 그래프 빌더는 목적의 포맷에 대해서 적절한 그래프를 생성 한다.

주 : 어플리케이션이 SetFormat 를 호출한 후에,IPin::EnumMediaTypes 를 사용해 핀으로 지원 되는 미디어 타입을 열거하려고 하면(자), 1 개의 미디어 타입만이 돌아간다.

IAMStreamConfig::GetStreamCaps 메소드는, 그 스트림에 관련한 AM_MEDIA_TYPE 구조체를 취득함과 함께, 스트림의 특성을 상세하게 기술하는 VIDEO_STREAM_CONFIG_CAPS 구조체 또는 AUDIO_STREAM_CONFIG_CAPS 구조체도 취득한다. 비디오에 관해서 취득되는 특성에는, 크로핑, 유연 운동, alignment, 세분도, 데이터 레이트등이 있다. GetStreamCaps 의 상세한 것에 대하여는, 「캡춰 포맷과 압축 포맷의 공개」를 참조할것.

필터 개발자에게 : 비디오 캡춰 필터 혹은 비디오 압축 필터를 쓸 때는, 이 인터페이스를 비디오 출력 핀에 이행 한다. 상세한 것에 대하여는, axextend.idl 의 코멘트를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMStreamConfig 메소드 | 설명
SetFormat | 오디오 스트림 또는 비디오 스트림의 포맷을 설정한다.
GetFormat | 오디오 스트림 또는 비디오 스트림의 포맷을 취득한다.
GetNumberOfCapabilities | 압력의 스트림 기능을 나타내는 구조체의 개수를 취득한다.
GetStreamCaps | pSCC 파라미터로 지정되는 구조체의 타입에 응해, 스트림의 오디오 기능 또는 비디오 기능을 취득한다.

IAMStreamConfig::GetFormat

IAMStreamConfig 인터페이스

오디오 스트림 또는 비디오 스트림의 포맷을 취득한다.

구문

HRESULT GetFormat(
  AM_MEDIA_TYPE **pmt
  );

파라미터

pmt
[out] AM_MEDIA_TYPE 구조체에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

미디어 타입 구조체의 사용이 종료하면(자),DeleteMediaType 함수를 호출해, 구조체를 해방한다.

IAMStreamConfig::GetNumberOfCapabilities

IAMStreamConfig 인터페이스

압력의 스트림 기능을 나타내는 구조체의 개수를 취득한다.

구문

HRESULT GetNumberOfCapabilities(
  int *piCount,
  int *piSize
  );

파라미터

piCount
[out] 지원 되는 VIDEO_STREAM_CONFIG_CAPS 구조체 또는 AUDIO_STREAM_CONFIG_CAPS 구조체의 개수에의 포인터.
piSize
[out] 구성의 구조체 (AUDIO_STREAM_CONFIG_CAPS 또는 VIDEO_STREAM_CONFIG_CAPS )의 사이즈에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMStreamConfig::GetStreamCaps

IAMStreamConfig 인터페이스

pSCC 파라미터로 지정되는 구조체의 타입에 응해, 스트림의 오디오, 비디오, 또는 그 외의 기능을 취득한다.

구문

HRESULT GetStreamCaps(
  int iIndex,
  AM_MEDIA_TYPE **pmt,
  BYTE *pSCC
  );

파라미터

iIndex
[in] 목적의 미디어 타입과 기능의 페어에 대한 인덱스. 이 페어의 총수를 취득하려면 ,GetNumberOfCapabilities 메소드를 사용한다. 지정할 수 있는 인덱스값은, 0 으로부터 (페어의 총수 - 1)의 범위이다.
pmt
[out] AM_MEDIA_TYPE 구조체에의 포인터의 주소.
pSCC
[out] 스트림 구성 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드에 의해, 핀의 미디어 타입을 열거 하면 말하는 종래의 방법보다, 유효한 미디어 타입에 관해서 상세한 정보를 취득할 수 있다. 이 때문에, 보통은, 핀을 열거하는 방법은 아니고 이 메소드를 사용한다. 가능한 비디오 캡춰 레이트, 미디어 타입, 및 사이즈등의 정보는,VIDEO_STREAM_CONFIG_CAPS 구조체로 돌려주어진다. 입력수, 샘플링 레이트, 및 bit rate의 세분도를 시작으로 하는, 필터의 출력 핀의 오디오 기능에 대해서는,AUDIO_STREAM_CONFIG_CAPS 구조체로 돌려주어진다.

DeleteMediaType 를 호출하면,pmt 미디어 타입을 해방할 수 있다.

GetStreamCaps 의 상세한 것에 대하여는, 「캡춰 포맷과 압축 포맷의 공개」를 참조할것.

IAMStreamConfig::SetFormat

IAMStreamConfig 인터페이스

오디오 스트림 또는 비디오 스트림의 포맷을 설정한다.

구문

HRESULT SetFormat(
  AM_MEDIA_TYPE *pmt
  );

파라미터

pmt
[in] AM_MEDIA_TYPE 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

핀이 스트림중의 경우는, 이 메소드를 호출해도 실패한다.

출력 핀이 미접속으로, 이것에 이 미디어 타입을 접속할 수 있는 경우는, 이 메소드로부터 S_OK 가 돌려주어져 지정의 미디어 타입의 열거가 시작 된다. 구체적으로는, 이 포맷을,CTransformOutputPin::GetMediaType 함수의 iPosition 파라미터로, 포맷 번호가 0 으로서 지정한다. 이 타입만을 설정 및 허가하는 것에 의해, 핀에 대해 접속이 발생할 경우에 이 포맷을 사용하도록 할 수 있다.

출력 핀이 접속이 끝난 상태로, 이 타입을 제공할 수 있는 경우는, 핀을 재접속한다. 다만, 다른 핀이 미디어 타입을 허가할 수 없는 경우, 이 호출은 실패해, 지금까지의 접속이 그대로 남겨진다.

파라미터값으로서 NULL 를 건네주면(자), 필터에 따라서는 디폴트 포맷이 설정되어 이 메소드로 지정한 이전의 포맷이 무효가 된다.

필터가 데이터를 생성하는 frame rate는, 출력 핀이 접속하고 있는 미디어 타입의,VIDEOINFOHEADER 의 AvgTimePerFrame 필드에서 정해진다. 임의의 frame rate로 캡춰 하지 못하고, 일정한 레이트에서만 캡춰 할 수 있을 가능성도 있다. 핀에 접속하고 있는 미디어 타입이, 대응할 수 없는 frame rate를 요구하는 경우는, 실현될 수 있는 다음에 가장 낮은 프레임을 제공해야 한다. 예를 들어, 미디어 타입이 AvgTimePerFrame=333333 (1 초의 약 1/30 으로, 1 초 쯤 30 프레임에 상당한다)로, 핀에서는 1 초 쯤 29.97 또는 35 프레임만 캡춰 할 수 있는 경우는, 1 초 쯤 29.97 프레임의 비율로 프레임을 제공할 필요가 있다. 이것은, 이 값이, 제공할 수 있는 가운데 30 에 가장 근처, 한편 30 을 넘지 않는 값이기 때문에이다. 제공하는 frame rate에 의해 생성 되는 프레임의 시간폭이, 요구되는 길이보다 1 마이크로 세컨드 이상 짧아지는 것이 없는 경우는,AvgTimePerFrame 가 단지 둥근 오차를 가지는 경우도 있으므로, 요구되는 frame rate보다 높은 레이트를 제공할 수 있다. AvgTimePerFrame 필드가 0 의 경우는, 임의의 디폴트의 frame rate로 프레임을 제공할 수 있다.


IAMStreamControl 인터페이스

이 인터페이스를 사용 하면, 필터 위에의 스트림을 개별적으로 제어할 수 있다. 몇개의 필터 위에의 핀은, 이 인터페이스를 공개하고 있다. 예를 들어,AVI Mux 필터는, 그 입력 핀으로 이 인터페이스를 지원 해,오디오 캡춰 필터와 WDM 비디오 캡춰 필터는, 각각의 출력 핀으로 이 인터페이스를 지원 한다.

이 인터페이스에 의해, 어플리케이션은, 지정의 시간에 스트림의 온과 오프를 바꿀 수가 있다. 예를 들어, 비디오의 재생중에 오디오 스트림을 오프로 해 음성을 지울 수가 있다. 캡춰 어플리케이션의 경우는, 이 인터페이스를 사용하는 것으로, 캡춰의 정확한 시작 타임과 종료 타임을 지정하거나 캡춰 스트림과 프리뷰 스트림을 서로 독립해 제어할 수 있다.

핀이 스트리밍을 시작 하는 기준 타임을 지정하려면 ,StartAt 메소드를 호출한다. 핀이 스트리밍을 종료하는 시간을 지정하려면 ,StopAt 메소드를 호출한다. 다음에, 필터 그래프 매니저상에서 IMediaControl::Run 를 호출한다.

이 인터페이스를 사용하는 경우는, 다음의 제한 사항에 주의한다.

  • 기준 클락은 필터 그래프가 아니면 안된다.
  • 하드웨어 오버레이를 수반하는 캡춰 카드 위에의 프리뷰 핀은, 이 인터페이스를 지원 하지 않는다.
  • 비디오와 오디오를 인터리브 AVI 파일에 캡춰 하고 있는 경우, AVI Mux 필터는 양쪽 모두의 스트림을 필요로 한다. 한편의 스트림을 정지 하면, 필터는 데이터를 인터리브 할 수 없다. 상세한 것에 대하여는, 「IConfigInterleaving 」를 참조할것.

어플리케이션에 따라서는,ICaptureGraphBuilder2::ControlStream 메소드가 편리한 경우가 있다. 이것은, 이 메소드가 그래프 레벨에서의 스트림 제어를 지원 해, 어플리케이션이 각 필터와 핀을 열거할 필요가 없기 때문에이다.

필터 개발자 : CBaseStreamControl base class는, 이 인터페이스를 이행 한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMStreamControl 메소드 | 설명
StartAt | 핀에 대해서 스트리밍 데이터 송신의 시작 타임을 지정한다.
StopAt | 핀에 대해서 처리와 데이터 송신의 종료 타임을 지정한다.
GetInfo | 현재의 스트리밍 설정에 관한 정보를 취득한다.

IAMStreamControl::GetInfo

IAMStreamControl 인터페이스

시작 타임과 종료 타임을 포함한, 현재의 스트리밍 설정에 관한 정보를 취득한다.

구문

HRESULT GetInfo(
    AM_STREAM_INFO *pInfo
);

파라미터

pInfo
[out] 현재의 스트림 설정이 포함되어 있는 AM_STREAM_INFO 구조체에의 포인터.

반환값

메소드가 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

AM_STREAM_INFO 구조체의 dwFlags 멤버에는, 유효한 시작 타임과 종료 타임이 설정되어 있는지 어떤지를 나타내는 플래그와 필터가 데이터를 파기하고 있을지 어떨지를 나타내는 플래그가 포함된다.

IAMStreamControl::StartAt

IAMStreamControl 인터페이스

핀에 대해서 스트리밍 데이터 송신의 시작 타임을 지정한다. 스트리밍이 실제로 시작 하면, 필터는 EC_STREAM_CONTROL_STARTED 통지 코드를 송신한다.

구문

HRESULT StartAt(
    const REFERENCE_TIME *ptStart,
    DWORD dwCookie
);

파라미터

ptStart
[in] 스트리밍의 시작 타임에의 포인터. NULL 의 경우, 이벤트 통지를 송신하지 않고 즉석에서 시작 한다. MAX_TIME 의 경우, 기존의 시작 요구가 캔슬된다.
dwCookie
[in] 시작시에 이벤트 통지와 함께 송신되는 값. ptStart 가 MAX_TIME 또는 NULL 의 경우는 무시된다.

반환값

메소드가 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

디폴트로 스트림은 유효해서, 이 메소드를 호출할 필요가 있는 것은,StopAt 메소드를 호출한 후 뿐이다.

핀이 실제로 스트리밍을 시작 하면,EC_STREAM_CONTROL_STARTED 이벤트가 통지된다. 선두의 이벤트 파라미터는, 핀의 IPin 인터페이스에의 포인터이며, 2 번째의 파라미터는,dwCookie 파라미터로 지정되는 값이다. 이것에 의해, 어플리케이션은, 이벤트를 각자의 요구에 다시 연결시킬 수가 있다.

시작 타임과 종료 타임이 1 개의 시점에 대해서 스케줄 되고 있는 경우, 순간적으로 시작 해, 그리고 종료한다. 이것을 사용하는 것으로, 1 개의 프레임을 캡춰 할 수 있다.

IAMStreamControl::StopAt

IAMStreamControl 인터페이스

핀에 대해서 처리와 데이터 송신의 종료 타임을 지정한다.

구문

HRESULT StopAt(
    const REFERENCE_TIME *ptStop,
    BOOL bSendExtra,
    DWORD dwCookie
);

파라미터

ptStop
[in] 스트리밍의 종료 타임에의 포인터. NULL 의 경우, 이벤트 통지를 송신하지 않고 즉석에서 종료한다. MAX_TIME 의 경우, 기존의 종료 요구가 캔슬된다.
bSendExtra
[in] 스케줄 되고 있는 종료 타임을 지나고 나서 추가 샘플을 송신할지 어떨지를 나타내는 불리언 값. TRUE 를 지정 하면, 추가 샘플이 송신된다.
dwCookie
[in] 종료시에 이벤트 통지와 함께 송신하는 값. ptStart 가 MAX_TIME 또는 NULL 의 경우는 무시된다.

반환값

메소드가 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

핀이 실제로 스트리밍을 종료 하면,EC_STREAM_CONTROL_STOPPED 이벤트가 통지된다. 선두의 이벤트 파라미터는, 핀의 IPin 인터페이스에의 포인터이며, 2 번째의 파라미터는,dwCookie 파라미터로 지정되는 값이다. 이것에 의해, 어플리케이션은, 이벤트를 각자의 요구에 다시 연결시킬 수가 있다.

비디오 캡춰의 경우는, 일반적으로, 캡춰 필터의 출력 핀과 멀티플렉서의 입력 핀의 양쪽 모두로 이 메소드를 호출해, 멀티플렉서로부터의 통지에만 주위를 기울인다. 이것에 의해, 캡춰 필터가 여분의 프레임을 불필요하게 캡춰 하는 것이 방지되어 그 한편, 멀티플렉서가 마지막 프레임을 실제로 파일에 보존하는 것이 보증된다.

게다가 캡춰 핀의 bSendExtra 파라미터에는 TRUE 를 지정해, 멀티플렉서 핀에는 FALSE 를 지정할 필요가 있다. 추가 프레임이 송신되지 않는 경우, 멀티플렉서는 언제까지나 종료 타임을 기다려, 이미 모든 정보를 캡춰 한 것을 이해하지 않는다. 멀티플렉서는 캡춰 핀이 송신한 추가 프레임을 파기하므로, 이것이 파일에 기입해질 것은 없다. 위에의 케이스에 나타낸 것처럼, 다른 다운 스트림 핀에서도 IAMStreamControl 를 사용하고 있으므로 않은 한,bSendExtra 에 TRUE 를 설정해서는 안 된다.

패킷의 중간의 시간을 지정해 StopAt 를 호출하면, 파기 상태로 이행하기 전에, 필터는 패킷 전체를 전달한다. 또, 시작 타임과 종료 타임이 1 개의 시점에 대해서 스케줄 되고 있는 경우는, 순간적으로 시작 해, 그리고 종료한다. 이것을 사용하는 것으로, 1 개의 프레임을 캡춰 할 수 있다.


IAMStreamSelect 인터페이스

재생하는 논리 스트림을 제어해, 거기에 관한 정보를 취득한다. 논리 스트림을 선택하는 예로서는, 각국어를 코드화하고 있는 오디오 스트림세트로부터의 선택을 들 수 있다. 예를 들어 이 경우, 영어, 독일어, 프랑스어로 구성되는 오디오 스트림세트로부터 영어를 선택할 수 있다.

MPEG-1 스트림 스플리터 필터는, 이 인터페이스를 이행 한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMStreamSelect 메소드 | 설명
Count | 유효한 스트림의 총수를 취득한다.
Info | 지정의 스트림에 관한 정보를 취득한다.
Enable | 지정의 스트림을 유효 또는 무효로 한다.

IAMStreamSelect::Count

IAMStreamSelect 인터페이스

유효한 스트림의 총수를 취득한다.

구문

HRESULT Count(
  DWORD *pcStreams
  );

파라미터

pcStreams
[out] 유효한 스트림수를 나타내는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 Microsoft® DirectShow® 의 이행에서는, S_OK 를 돌려준다.

IAMStreamSelect::Enable

IAMStreamSelect 인터페이스

지정의 스트림을 유효 또는 무효로 한다.

구문

HRESULT Enable(
  long lIndex,
  DWORD dwFlags
  );

파라미터

lIndex
[in] 목적의 스트림의 인덱스 번호. 인덱스 번호는 0 으로부터 시작된다.
dwFlags
[in] 스트림이 유효 또는 무효라는 점을 나타내는 플래그. 다음의 어느쪽이든을 지정한다.
0 | 이 스트림을 포함한 그룹내의 모든 스트림을 무효로 한다.
AMSTREAMSELECTENABLE_ENABLE | 지정의 그룹내의 이 스트림만을 유효하게 해, 다른 모든 스트림을 무효로 한다.
AMSTREAMSELECTENABLE_ENABLEALL | 이 스트림을 포함한 그룹내의 모든 스트림을 유효하게 한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는, 지정의 플래그의 지원이 이행되어 있지 않은 경우는 E_NOTIMPL 를 돌려주어, 스트림 ID 가 무효의 경우는 E_INVALIDARG 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

IAMStreamSelect::Info

IAMStreamSelect 인터페이스

지정의 스트림에 관한 정보를 취득한다.

구문

HRESULT Info(
  long lIndex,
  AM_MEDIA_TYPE **ppmt,
  DWORD *pdwFlags,
  LCID *plcid,
  DWORD *pdwGroup,
  WCHAR **ppszName,
  IUnknown **ppObject,
  IUnknown **ppUnk
  );

파라미터

lIndex
[in] 목적의 스트림의 인덱스 번호. 인덱스 번호는 0 으로부터 시작된다.
ppmt
[out] 스트림의 미디어 타입에의 포인터의 주소. 옵션이다. 종료시에 AM_MEDIA_TYPE 구조체를 해방하려면 ,DeleteMediaType 함수를 사용한다.
pdwFlags
[out] 스트림 상태를 나타내는 플래그에의 옵션의 포인터. 유효한 값은 다음과 같다.
0 | 이 스트림은 무효이다.
AMSTREAMSELECTINFO_ENABLED | 스트림은 유효해, 이 그룹내외의 스트림도 유효하다.
AMSTREAMSELECTINFO_EXCLUSIVE | 그룹내에서 이 스트림만이 유효하다.
plcid
[out] 로케일 문맥 (LCID) 값에의 포인터. LCID 가 없는 경우는, 이 파라미터는 0 값을 가리킨다. 옵션이다.
pdwGroup
[out] 논리 그룹에의 포인터. 옵션이다.
ppszName
[out] 스트림명에의 포인터의 주소. 옵션이다. 종료시에 CoTaskMemFree 함수로 해방된다.
ppObject
[out] 이 스트림에 관련지을 수 있고 있는 핀 또는 필터 오브젝트에의 포인터의 주소. IAMStreamSelect::Enable 메소드가 불려 가면(자), 오브젝트가 바뀔 가능성이 있다. 관련하는 오브젝트가 없는 경우, 이 메소드가 돌려주어지는 곳의 파라미터에는 NULL 값이 포함된다.
ppUnk
[out] 스트림 고유의 인터페이스에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는,lIndex 가 범위외의 경우는 S_FALSE 를 돌려주어, 그 이외의 경우는 S_OK 를 돌려준다.

주의

각 그룹내의 선두의 스트림은 디폴트이다.


IAMTimecodeDisplay 인터페이스

IAMTimecodeDisplay 인터페이스는, 외부의 SMPTE/MIDI 타임 코드 디스플레이 디바이스의 동작을 정의하는 프로퍼티와 메소드를 갖추고 있다. 이 인터페이스는,IAMExtDevice ,IAMExtTransport , 및 그 외의 타임 코드 인터페이스와 함께 이행 해, VCR 등과 같이, 타임 코드 데이터를 읽어내, 생성, 또는 표시할 수 있는 외부 디바이스를 제어한다. 이 인터페이스에서는, VCR 또는 같은 외부 디바이스에 짜넣어지고 있는 물리적인 타임 코드 캐릭터 제너레이터의 표시를 제어한다.

SMPTE 타임 코드의 상세한 것에 대하여는, 「SMPTE 타임 코드」를 참조할것.

외부의 타임 코드 리더 또는 타임 코드 제네레이터에 있어서의 타임 코드 표시를 제어하는 외부 디바이스 필터로, 이 인터페이스를 이행 한다. 타임 코드 리더 또는 타임 코드 제네레이터는, VCR 에 짜넣는 일도, 개별의 외부 디바이스로서 취급할 수도 있다. 외부 디바이스가 타임 코드를 표시할 수 없는 경우, 또는 통합 하드웨어나 오버레이 하드웨어를 가지지 않는 내장 카드에 의해 타임 코드가 생성되고 있는 경우는, 이 인터페이스를 이행 해서는 안 된다.

이 인터페이스는, Microsoft® DirectShow® 필터 그래프내에서의 렌더링을 목적으로 하는 것은 아니다. 순수하게 외부 디바이스의 표시로 사용하는 것이다.

외부 디바이스와 타임 코드 정보의 표시 방법을 어플리케이션으로 제어할 필요가 있는 경우는, 이 인터페이스를 사용한다.

하드웨어의 요건

하드웨어 요건에 대해서는, 「IAMExtTransport 인터페이스」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimecodeDisplay 메소드 | 설명
GetTCDisplayEnable | 외부 디바이스의 타임 코드 캐릭터 제너레이터 출력이 유효한가 어떤가를 판별한다.
SetTCDisplayEnable | 외부 디바이스의 타임 코드 캐릭터 출력 제네레이터를 유효 또는 무효로 한다.
GetTCDisplay | 타임 코드 캐릭터 제너레이터 출력의 현재의 설정을 취득한다.
SetTCDisplay | 타임 코드 캐릭터 제너레이터 출력의 특성을 설정한다.

IAMTimecodeDisplay::GetTCDisplay

IAMTimecodeDisplay 인터페이스

타임 코드 캐릭터 제너레이터 출력의 현재의 설정을 취득한다.

구문

HRESULT GetTCDisplay(
  long Param,
  long *pValue
  );

파라미터

Param
[in] 타임 코드의 표시 특성. 설정을 취득하는 원이 되는, 다음의 항목의 어느쪽이든을 지정한다.
ED_TCD_BORDER | 흑색의 문자로 백색의 경계, 또는 백색의 문자로 흑색의 경계
ED_TCD_INTENSITY | 문자의 휘도 (밝음)
ED_TCD_INVERT | 백색의 백그라운드에 흑색의 문자, 또는 흑색의 백그라운드에 백색의 문자
ED_TCD_POSITION | 문자의 위치
ED_TCD_SIZE | 문자의 사이즈
ED_TCD_SOURCE | 표시하는 데이터의 소스
ED_TCD_TRANSPARENCY | 문자의 투명도
pValue
[out] Param 로 지정되는 파라미터의 현재의 설정값에의 포인터. 이 파라미터는, 다음의 몇개의 값을 취득한다.

ED_TCD_SOURCE 가 Param 로 지정되고 있는 경우는, 다음중 한쪽이 돌려주어진다.
ED_TCG | 타임 코드 제네레이터
ED_TCR | 타임 코드 리더

ED_TCD_SIZE 가 Param 로 지정되고 있는 경우는, 다음중 한쪽이 돌려주어진다.
ED_LARGE | 대
ED_MED | 중
ED_SMALL | 소

ED_TCD_POSITION 가 Param 로 지정되고 있는 경우는, 다음중 한쪽이 돌려주어진다.
ED_BOTTOM | 하
ED_MIDDLE | 중
ED_TOP | 상

위에의값과 다음중 한쪽이 짜 합쳐져 돌려주어진다.
ED_CENTER | 중앙
ED_LEFT | 왼쪽
ED_RIGHT | 오른쪽

ED_TCD_INTENSITY 가 Param 로 지정되고 있는 경우는, 다음중 한쪽이 돌려주어진다.
ED_HIGH | 고
ED_LOW | 저

ED_TCD_TRANSPARENCY 가 Param 로 지정되고 있는 경우는, 0 에서 4 의 범위의 값이 돌려주어진다. 0 은 완전하게 불투명한 일을 나타낸다.

ED_TCD_INVERT 가 Param 로 지정되고 있는 경우는, 다음중 한쪽이 돌려주어진다.
OAFALSE | 백색의 백그라운드에 흑색의 문자
OATRUE | 흑색의 백그라운드에 백색의 문자

ED_TCD_BORDER 가 Param 로 지정되고 있는 경우는, 다음중 한쪽이 돌려주어진다.
OAFALSE | 흑색의 문자로 백색의 경계
OATRUE | 백색의 문자로 흑색의 경계

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMTimecodeDisplay::SetTCDisplay

IAMTimecodeDisplay::GetTCDisplayEnable

IAMTimecodeDisplay 인터페이스

외부 디바이스의 타임 코드 캐릭터 제너레이터 출력이 유효한가 어떤가를 판별한다.

구문

HRESULT GetTCDisplayEnable(
  long *pState
  );

파라미터

pState
[out] 타임 코드 캐릭터 제너레이터 출력이 유효한가 어떤가를 나타내는 값에의 포인터. OATRUE 는 유효한 것을 나타내, OAFALSE 는 무효라는 점을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드는, 필터 그래프내에서의 캐릭터 렌더링을 목적으로 하는 것은 아니고, 순수하게 하드웨어의 표시를 목적으로 하는 것이다. 이 메소드를 사용하기 전에, 외부의 타임 코드 리더 또는 타임 코드 제네레이터가 표시 기능을 갖추고 있는 것을 확인할 필요가 있다.

참조

IAMTimecodeDisplay::SetTCDisplayEnable

IAMTimecodeDisplay::SetTCDisplay

IAMTimecodeDisplay 인터페이스

타임 코드 캐릭터 제너레이터 출력의 특성을 설정한다.

구문

HRESULT SetTCDisplay(
  long Param,
  long Value
  );

파라미터

Param
[in] 타임 코드의 표시 특성. 값을 설정하는 다음의 몇개의 프로퍼티를 지정한다.
ED_TCD_BORDER | 흑색의 문자로 백색의 경계, 또는 백색의 문자로 흑색의 경계
ED_TCD_INTENSITY | 문자의 휘도 (밝음)
ED_TCD_INVERT | 백색의 백그라운드에 흑색의 문자, 또는 흑색의 백그라운드에 백색의 문자
ED_TCD_POSITION | 문자의 위치
ED_TCD_SIZE | 문자의 사이즈
ED_TCD_SOURCE | 표시하는 데이터의 소스
ED_TCD_TRANSPARENCY | 문자의 투명도
Value
[in] Param 로 지정되는 파라미터의 설정값. 다음의 어느쪽이든을 지정할 필요가 있다.

ED_TCD_SOURCE 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
ED_TCG | 타임 코드 제네레이터
ED_TCR | 타임 코드 리더

ED_TCD_SIZE 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
ED_LARGE | 대
ED_MED | 중
ED_SMALL | 소

ED_TCD_POSITION 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
ED_BOTTOM | 하
ED_MIDDLE | 중
ED_TOP | 상

위에의값과 다음의 어느쪽이든을 조합해 지정한다.
ED_CENTER | 중앙
ED_LEFT | 왼쪽
ED_RIGHT | 오른쪽

ED_TCD_INTENSITY 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
ED_HIGH | 고
ED_LOW | 저

ED_TCD_TRANSPARENCY 가 Param 로 지정되고 있는 경우는, 0 에서 4 의 범위의 값을 설정한다. 0 은 완전하고 불투명해서, 4 는 가능한 한 어둡다.

ED_TCD_INVERT 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
OAFALSE | 백색 위에 흑색
OATRUE | 흑색 위에 백색

ED_TCD_BORDER 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
OAFALSE | 흑색의 문자로 백색의 경계
OATRUE | 백색의 문자로 흑색의 경계

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMTimecodeDisplay::GetTCDisplay

IAMTimecodeDisplay::SetTCDisplayEnable

IAMTimecodeDisplay 인터페이스

외부 디바이스의 타임 코드 캐릭터 출력 제네레이터를 유효 또는 무효로 한다.

구문

HRESULT SetTCDisplayEnable(
  long State
  );

파라미터

State
[in] 타임 코드 캐릭터 출력 제네레이터를 유효 또는 무효로 하는 값. OATRUE 를 지정 하면 유효하게 되어, OAFALSE 를 지정 하면 무효가 된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드는, 필터 그래프내에서의 캐릭터 렌더링을 목적으로 하는 것은 아니고, 순수하게 하드웨어의 표시를 목적으로 하는 것이다. 이 메소드를 사용하기 전에, 외부의 타임 코드 리더 또는 타임 코드 제네레이터가 표시 기능을 갖추고 있는 것을 확인할 필요가 있다.

참조

IAMTimecodeDisplay::GetTCDisplayEnable


IAMTimecodeGenerator 인터페이스

IAMTimecodeGenerator 인터페이스는, 외부 SMPTE/MIDI 타임 코드 제네레이터가 필터 그래프에 데이터를 제공하는 방법과 타임 코드가 제공되는 포맷을 지정하는 프로퍼티와 메소드를 갖추고 있다. 이 인터페이스는,IAMExtDevice 인터페이스 및 IAMExtTransport 인터페이스와 함께 이행 해, VCR 등의 외부 디바이스를 제어한다. 이 인터페이스가 갖추고 있는 메소드에 의해, 어플리케이션은, 외부 디바이스가 타임 코드의 생성시에 사용하는 각종의 SMPTE/MIDI 타임 코드 모드 또는 포맷을 지정할 수 있다. 또, 제네레이터가 올바르게 동작하고 있는 것을 확인하는 메소드도 준비되어 있다.

SMPTE 타임 코드는 프레임 애드레싱 시스템으로, 비디오 소스와 오디오 소스를 식별해, 자동 트럭 동기를 실현해, 한층 더 결과에 관한 부가 데이터의 컨테이너로서의 역할을 완수한다. SMPTE 타임 코드의 제일의 목적은, 비디오와 오디오용의, 머신으로 읽어내 가능한 주소를 제공하는 것이다. 이것은 hh:mm:ss:ff 포맷으로 표시되어 ANSI/SMPTE 12-1986 로 정의되고 있다.

SMPTE 타임 코드의 상세한 것에 대하여는, 「SMPTE 타임 코드」를 참조할것.

외부 타임 코드 리더에게 액세스 하는 메소드의 상세한 것에 대하여는, 「IAMTimecodeReader 인터페이스」를 참조할것.

외부 타임 코드 제네레이터가 SMPTE/MIDI 타임 코드 정보를 생성하는 방법을 제어하는 경우는, 외부 디바이스 필터에 대해 이 인터페이스를 이행 한다.

필터상에서 IMediaSeeking 인터페이스를 공개하는 것에 의해, 어플리케이션은 그 IMediaSeeking::ConvertTimeFormat 를 사용해, 타임 코드를 Microsoft® DirectShow® 기준 타임으로 변환할 수 있다.

외부 디바이스는, 타임 코드를 읽어내, 그 컨트롤 인터페이스를 개입시켜 이것을 컴퓨터에 송신할 수 있을 필요가 있다 ( 「하드웨어의 요건」을 참조할것). 외부 디바이스가 이 기능을 갖추지 않은 경우는, 컴퓨터에 타임 코드 리더 카드를 장착하는지, 캡춰 된 비디오 프레임에 파묻히고 있는 VITC , 또는 오디오 신호로서 캡춰 된 LTC 를, DirectShow 타임 코드 샘플로 변환하는 소프트웨어 디코더를 생성 할 필요가 있다.

외부 디바이스 중(안)에서 SMPTE 타임 코드를 생성하는 경우는, 이 인터페이스를 사용한다.

하드웨어의 요건

하드웨어의 요건에 대해서는, 「IAMExtTransport 인터페이스」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimecodeGenerator 메소드 | 설명
GetTCGMode | SMPTE 타임 코드 제네레이터 프로퍼티를 취득한다.
SetTCGMode | SMPTE 타임 코드 제네레이터 프로퍼티를 설정한다.
put_VITCLine | VITC (Vertical Interval Timecode) 정보를 삽입하는 라인을 지정한다.
get_VITCLine | VITC 정보가 삽입된 라인을 취득한다.
SetTimecode | 타임 코드, 유저 비트, 또는 양쪽 모두를 설정한다.
GetTimecode | 스트림내에서 유효한 최신의 타임 코드 또는 유저 비트값을 취득한다.

IAMTimecodeGenerator::GetTCGMode

IAMTimecodeGenerator 인터페이스

SMPTE 타임 코드 제네레이터 프로퍼티를 취득한다.

구문

HRESULT GetTCGMode(
  long Param,
  long *pValue
  );

파라미터

Param
[in] 타임 코드 제네레이터 모드. 설정값을 취득하는 원이 되는, 다음의 몇개의 모드를 지정한다.
ED_TCG_FRAMERATE | frame rate.
ED_TCG_REFERENCE_SOURCE | 카운트값의 소스.
ED_TCG_SYNC_SOURCE | 하드웨어 클락 기준의 소스.
ED_TCG_TIMECODE_TYPE | 제네레이터의 SMPTE 타임 코드 포맷.
pValue
[out] Param 로 지정되는 모드의 현재의 설정값에의 포인터.

ED_TCG_FRAMERATE 가 Param 로 지정되고 있는 경우, 이 파라미터는 다음의 어느쪽이든을 취득한다.
ED_FORMAT_SMPTE_24 | 24 프레임/초.
ED_FORMAT_SMPTE_25 | 25 프레임/초.
ED_FORMAT_SMPTE_30 | 30 프레임/초. 프레임의 결핍 없음.
ED_FORMAT_SMPTE_30DROP | 30 프레임/초. 프레임의 결핍 있어 (실제로는 29.97 프레임/초).

ED_TCG_REFERENCE_SOURCE 가 Param 로 지정되고 있는 경우, 이 파라미터는 다음의 어느쪽이든을 취득한다.
ED_TCG_FREE | 카운트의 기준이 되는 소스는 없다.
ED_TCG_READER | 리더의 값에 동기 한다 (jamsync).

ED_TCG_SYNC_SOURCE 가 Param 로 지정되고 있는 경우, 이 파라미터는 다음의 어느쪽이든을 취득한다.
ED_TCG_FREE | 락 되지 않는다 (freerun).
ED_TCG_READER | 타임 코드 리더에게 잠근다.
ED_TCG_VIDEO | 수신 비디오에 잠근다.

ED_TCG_TIMECODE_TYPE 가 Param 로 지정되고 있는 경우, 이 파라미터는 다음의 어느쪽이든을 취득한다.
ED_TCG_MIDI_FULL | MIDI 풀 프레임 타임 코드.
ED_TCG_MIDI_QF | MIDI 쿼터-프레임 타임 코드.
ED_TCG_SMPTE_LTC | LTC (Liner Timecode).
ED_TCG_SMPTE_VITC | VITC (Vertical Interval Timecode).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드는, 타임 코드 제네레이터의 각종 설정값을 돌려준다. ED_TCG_TIMECODE_TYPE 의 상세한 것에 대하여는, 「IAMTimecodeReader::SetTCRMode 」를 참조할것.

IAMTimecodeGenerator::GetTimecode

IAMTimecodeGenerator 인터페이스

스트림내에서 유효한 최신의 타임 코드 또는 유저 비트값을 취득한다.

구문

HRESULT GetTimecode(
  PTIMECODE_SAMPLE pTimecodeSample
  );

파라미터

pTimecodeSample
[out] TIMECODE_SAMPLE 타임 코드 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면, 스트림내에서 유효한 최신의 타임 코드값을 취득할 수 있다. 이것에 의해 어플리케이션은 타임 코드를 감시해, 제네레이터가 올바르게 동작하고 있는 것을 확인할 수 있다.

참조

IAMTimecodeGenerator::SetTimecode

IAMTimecodeGenerator::get_VITCLine

IAMTimecodeGenerator 인터페이스

VITC (Vertical Interval Timecode) 정보가 삽입된 라인을 취득한다.

구문

HRESULT get_VITCLine(
  long *pLine );

파라미터

pLine
[out] 타임 코드 정보를 저장 하고 있는 라인에의 포인터. 유효한 라인은 11 에서 20 의 범위이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

복수의 라인으로부터 VITC 정보를 취득하려면 , 하이 비트가 세트 되고 있는 목적의 라인 마다 이 메소드를 연속해 호출한다.

참조

IAMTimecodeGenerator::put_VITCLine

IAMTimecodeGenerator::put_VITCLine

IAMTimecodeGenerator 인터페이스

VITC (Vertical Interval Timecode) 정보를 삽입하는 라인을 지정한다.

구문

HRESULT put_VITCLine(
    long Line );

파라미터

Line
[in] 타임 코드 정보를 저장 하는 라인. 유효한 라인은 11 에서 20 의 범위이다. 0 은 자동 선택을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

특정의 복수의 라인상에 VITC 정보를 설정하려면 , 목적의 라인 마다 이 메소드를 연속해 호출한다.

이전으로 설정된 라인에 이 라인을 추가하려면 , 하이 비트를 설정한다.

참조

IAMTimecodeGenerator::get_VITCLine

IAMTimecodeGenerator::SetTCGMode

IAMTimecodeGenerator 인터페이스

SMPTE 타임 코드 제네레이터 프로퍼티를 설정한다.

구문

HRESULT SetTCGMode(
  long Param,
  long Value
  );

파라미터

Param
[in] 타임 코드 제네레이터 모드. 다음의 몇개의 모드를 지정한다.
ED_TCG_FRAMERATE | frame rate.
ED_TCG_REFERENCE_SOURCE | 카운트값의 소스.
ED_TCG_SYNC_SOURCE | 하드웨어 클락 기준의 소스.
ED_TCG_TIMECODE_TYPE | 제네레이터의 SMPTE 타임 코드 포맷.
Value
[in] Param 로 지정되는 모드의 설정값.

ED_TCG_FRAMERATE 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
ED_FORMAT_SMPTE_24 | 24 프레임/초.
ED_FORMAT_SMPTE_25 | 25 프레임/초.
ED_FORMAT_SMPTE_30 | 30 프레임/초. 프레임의 결핍 없음.
ED_FORMAT_SMPTE_30DROP | 30 프레임/초. 프레임의 결핍 있어 (실제로는 29.97 프레임/초).

ED_TCG_REFERENCE_SOURCE 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
ED_TCG_FREE | 카운트의 기준이 되는 소스는 없다.
ED_TCG_READER | 리더값에 동기 한다 (jamsync).

ED_TCG_SYNC_SOURCE 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
ED_TCG_FREE | 락 되지 않는다 (freerun).
ED_TCG_READER | 타임 코드 리더에게 잠근다.
ED_TCG_VIDEO | 수신 비디오에 잠근다.

ED_TCG_TIMECODE_TYPE 가 Param 로 지정되고 있는 경우는, 다음의 어느쪽이든을 설정한다.
ED_TCG_MIDI_FULL | MIDI 풀 프레임 타임 코드.
ED_TCG_MIDI_QF | MIDI 쿼터-프레임 타임 코드.
ED_TCG_SMPTE_LTC | LTC (Liner Timecode).
ED_TCG_SMPTE_VITC | VITC (Vertical Interval Timecode).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

ED_TCG_TIMECODE_TYPE 의 상세한 것에 대하여는, 「IAMTimecodeReader::SetTCRMode 메소드」를 참조할것.

참조

IAMTimecodeGenerator::GetTCGMode

IAMTimecodeGenerator::SetTimecode

IAMTimecodeGenerator 인터페이스

타임 코드,유저 비트값, 또는 양쪽 모두를 설정한다.

구문

HRESULT SetTimecode(
  PTIMECODE_SAMPLE pTimecodeSample
  );

파라미터

pTimecodeSample
[in] TIMECODE_SAMPLE 타임 코드 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

타임 코드만을 설정하는 경우는, 유저 비트값에 NULL 를 설정한다. 반대로 붙어도 같이이다. 제네레이터가 실행하고 있는 경우는, 이러한 값은 즉석에서 반영된다.

참조

IAMTimecodeGenerator::GetTimecode


IAMTimecodeReader 인터페이스

IAMTimecodeReader 인터페이스를 이행 하면, 외부 디바이스로부터의 SMPTE (Society of Motion Picture and Television Engineers) 타임 코드나 MIDI 타임 코드를 읽어낼 수가 있게 된다. 이 인터페이스에서는, 외부 디바이스가 읽어내는 타임 코드 포맷, 및 그 타임 코드를 미디어에 묻는 방법을 지정하는 프로퍼티와 메소드를 갖추고 있다. 이 인터페이스는,IAMExtDevice 인터페이스 및 IAMExtTransport 인터페이스와 함께 사용해, VCR 등과 같이 타임 코드 데이터를 읽어낼 수가 있는 외부 디바이스를 제어하는 것이 요구된다.

SMPTE 타임 코드는 프레임 애드레싱 시스템으로, 비디오 소스와 오디오 소스를 식별해, 자동 트럭 동기를 실현해, 한층 더 소스 머트리얼에 관한 부가 데이터의 컨테이너로서의 역할을 완수한다. SMPTE 타임 코드의 제일의 목적은, 비디오와 오디오용의, 머신으로 읽어내 가능한 주소를 제공하는 것이다. 이것은 hh:mm:ss:ff (시간, 분, 초, 프레임) 포맷으로 표시되어 ANSI/SMPTE 12-1986 로 정의되고 있다.

SMPTE 타임 코드의 상세한 것에 대하여는, 「SMPTE 타임 코드」를 참조할것.

외부 디바이스가 SMPTE/MIDI 타임 코드 정보를 읽어내는 방법을 지정하는 경우는, 외부 디바이스 필터에 대해 이 인터페이스를 이행 한다.

필터상에서 IMediaSeeking 인터페이스를 공개하는 것에 의해, 어플리케이션은 그 IMediaSeeking::ConvertTimeFormat 메소드를 사용해, 타임 코드를 Microsoft® DirectShow® 기준 타임으로 변환할 수 있다.

외부 디바이스는, 타임 코드를 읽어내, 그 컨트롤 인터페이스를 개입시켜 이것을 컴퓨터에 송신할 수 있을 필요가 있다. 외부 디바이스가 이 기능을 갖추지 않은 경우는, 컴퓨터에 타임 코드 리더 카드를 장착하는지, 캡춰 된 비디오 프레임내의 VITC (Vertical Interval Timecode), 또는 오디오 신호로서 캡춰 된 LTC (Linear Timecode)를, DirectShow 타임 코드 샘플로 변환하는 소프트웨어 디코더를 생성 할 필요가 있다.

타임 코드 정보를 읽어내 외부 디바이스를 제어할 필요가 있는 경우, 또는 원의 프로그램 정보를 참조해야 하는 외부 디바이스로부터의 타임 코드 정보를 어플리케이션 중(안)에서 사용하는 경우는, 이 인터페이스를 사용한다.

보통, 어플리케이션이 타임 코드를 보존하려면 2 통과해 방법이 있다. 캡춰 파일에 대해서, 추가의 스트림으로서 기입하는 방법과 확장 AVI 파일 인덱스에 저장 되는 불연속성 테이블로서 기입하는 방법이다. 타임 코드는, 캡춰나 재생을 방아쇠 하는 경우, 또는 최종 결과에 이를 때까지의 소스 머트리얼의 편집 방법을 기술하는 EDL (Edit Decision List) 를 생성 하는 경우에, 일반적으로 사용된다.

타임 코드를 캡춰 하는 경우는, 이것을, 자신의 미디어 타입을 가지는 개별의 스트림으로서 취급한다. 멀티플렉서 필터를 생성 하는 것에 의해, 적절한 파일이 이것을 사용할 수 있다. 다만, 테이프로부터 타임 코드를 읽어내는 경우는, 자주 에러가 발생한다. 이것은, 테이프의 데이터가 빠져 있거나, 테이프에 관한 그 외의 기계적인 문제가 원인이다. 이러한 경우, 타임 코드 소스 필터는 단순하게 샘플을 파기해, 다음의 유효한 샘플에 불연속성의 프로퍼티의 마크를 붙인다.

타임 코드를 사용해, 타임 코드 첨부 ("스트라이프 ") 비디오 테잎으로부터의 캡춰 또는 재생을 방아쇠 하는 경우는, 다음의 순서로 조작을 실시한다.

  1. 캡춰 그래프를 생성 해, 목적의 AVI 파일을 열어, 필요에 따라서 디스크 영역을 사전에 할당한다. 캡춰 하는 머트리얼을 기존의 AVI 파일에 추가하는 경우는, 기입하기 전에 파일의 종단을 시크 한다. 캡춰 그래프는 이 정도치로 포즈 한다.
  2. VCR 의 캡춰 시작점을 검색해, 타임 코드를 기록한다. 이 값은 수동으로 프로그램에 입력하는 일도, 어플리케이션이 자동적으로 읽어낼 수도 있다. 자동 독해의 경우, 그래프가 실행하고 있는 것이 요구된다. 그러나, 파일 멀티플렉서의입력 핀 위에의 스트림 컨트롤 인터페이스가, 수신 샘플을 파기하는 것에 의해 캡춰를 효율적으로 제어하고 있을 필요가 있다.
  3. VCR 를프리로르 위치까지 머리 내 한다. 이것은 보통, 타겟점의 5 초전이다.
  4. VCR 와 그래프를 시작 한다. 방아쇠점, 또는 방아쇠점으로부터 파일 라이터의 프리로르를 당긴 시점에 이르면(자), 스트림 컨트롤 인터페이스는 파일 멀티플렉서를 해방해, 파일 라이터에의 미디어 샘플의 스트리밍을 시작 한다.
  5. 캡춰 처리는 수동으로 정지하는 일도, 스트림 컨트롤 인터페이스로 시간폭의 프로퍼티를 설정하는 것에 의해 정지할 수도 있다.

프리로르시와 캡춰 처리시의 양쪽 모두에 대해, 불연속인 타임 코드를 고려할 필요가 있다. 타임 코드는 일반적으로, 프리로르와 캡춰의 시작점 이후, 연속적, 한편 단조 증가해 나가는 것이 바람직한다. 이 상태이면,IMediaSeeking::ConvertTimeFormat 메소드에 의한, 반드시 명확하지 않은 상대적인스트림 타임을 계산하지 않아도 된다. 또, 타임 코드가, 캡춰를 방아쇠 하는 유일한 제어 신호일 필요도 없다. Intercast 나 자막 방송 데이터 (XDS)등과 같이,수직 동기 간격에 저장 되는 타임 스탬프 첨부 데이터를 사용해, 비디오 데이터와 오디오 데이터의 디스크에의 스트리밍을 시작 할 수 있다.

하드웨어의 요건

하드웨어의 요건에 대해서는, 「IAMExtTransport 인터페이스」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTimecodeReader 메소드 | 설명
GetTCRMode | 타임 코드 리더의 프로퍼티를 취득한다.
SetTCRMode | 타임 코드 리더의 프로퍼티를 설정한다.
put_VITCLine | 타임 코드 리더가 타임 코드를 읽어낼 때 사용하는 VITC (Vertical Interval Timecode) 라인을 지정한다.
get_VITCLine | 타임 코드 리더가 타임 코드를 읽어낼 때 사용하는 VITC 라인을 취득한다.
GetTimecode | 최신의 타임 코드,유저 비트, 및 스트림내에서 유효한 플래그값을 취득한다.

IAMTimecodeReader::GetTCRMode

IAMTimecodeReader 인터페이스

타임 코드 리더의 프로퍼티를 취득한다.

구문

HRESULT GetTCRMode(

  long Param,

  long *pValue

  );

파라미터

Param
[in] 설정값을 취득하는 원이 되는 타임 코드 리더의 프로퍼티 (ED_TCR_SOURCE 또는 ED_TCR_NOTIFY_ENABLE).
pValue
[out] 요구된 타임 코드 리더 프로퍼티의 값에의 포인터. Param 에 ED_TCR_NOTIFY_ENABLE 가 지정되고 있는 경우는, 통지가 유효한 것을 나타내는 OATRUE, 또는 OAFALSE 를 돌려준다. Param 에 ED_TCR_SOURCE 가 지정되고 있는 경우는, 다음의 몇개의 값을 돌려준다.
ED_TCR_CT | 컨트롤 트럭
ED_TCR_LTC | LTC (Linear Timecode)
ED_TCR_VITC | VITC (Vertical Interval Timecode)
ED_TCR_LAST_VALUE | 전회의 독해값

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

LTC 는, 아날로그 오디오 트럭상에서바이페즈마크 encode 신호로서 기록된다. 각 타임 코드 프레임은, 시간폭내의 1 개의 비디오 프레임 타임이다.

VITC 는, 보통, 비디오 신호의 수직 동기 간격의, 11 에서 20 의 범위내의 2 개의 라인에 저장 된다.

컨트롤 트럭은, 테이프 위에의 특별한 트럭에, 1 프레임 근처 1 회 기록되는 신호이다. 헤드 및 드라이브 서보의 메카니즘에서는, 이것을 사용해 모든 것을 잠근다. 또, 타임 코드 기능을 갖추지 않은 머신상에서 카운터를 조작하는데 사용했을 경우에 따라서는 타임 코드 리더가 장비 되고 있는 머신상에서도 사용할 수 있다.

ED_TCR_LAST_VALUE 는, 외부 디바이스에 대해서 다른 타임 코드 요구를 보내는 것이 어플리케이션으로 바람직하지 않는 경우, 타임 코드 통지를 이행 할 경우에 사용된다. 이 방법은 multi-thread에 관한 문제가 있으므로, 프레임의 정확함이 요구되는 어플리케이션에서는, 그 사용은 추천 되지 않는다.

참조

IAMTimecodeReader::SetTCRMode

IAMTimecodeReader::GetTimecode

IAMTimecodeReader 인터페이스

최신의 타임 코드, 유저 비트, 및 스트림내에서 유효한 플래그값을 취득한다.

구문

HRESULT GetTimecode(
  PTIMECODE_SAMPLE pTimecodeSample
  );

파라미터

pTimecodeSample
[out] TIMECODE_SAMPLE 타임 코드 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면, 타임 코드를 감시해, 중복과 불연속성을 해석할 수 있다. 타임 코드를 제공하는 소스 필터, 및 경우에 따라서는다운 스트림 필터에서는, 불연속성이나 에러를 해석하는 것이 바람직한다. 이것은, 최신의 타임 코드를 취득하기 위해서, 모든 샘플을 참조할 필요가 있기 때문에 있다.

어플리케이션에서는, 타임 코드 정보에 미정도리의 비트를 설정해, 동기 정보를 저장 하거나 원의 필름 정보와 오디오 테이프 정보를 encode 할 수 있다. 이러한 미정도리 비트, 즉 유저 비트는, 이 메소드를 호출하는 것에 의해 취득된다.

IAMTimecodeReader::get_VITCLine

IAMTimecodeReader 인터페이스

타임 코드 리더가 타임 코드를 읽어낼 때 사용하는 VITC (Vertical Interval Timecode) 라인을 취득한다.

구문

HRESULT get_VITCLine(
  long *pLine );

파라미터

pLine
[out] 타임 코드 정보를 저장 하고 있는, 11 에서 20 의 범위내의 라인에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

하이 비트는 복수의 라인이 사용되고 있는 것을 나타내, 라인 번호에 대해서 호출이 연속해 행해진다.

참조

IAMTimecodeReader::put_VITCLine

IAMTimecodeReader::put_VITCLine

IAMTimecodeReader 인터페이스

타임 코드 리더가 타임 코드를 읽어낼 때 사용하는 VITC (Vertical Interval Timecode) 라인을 지정한다.

구문

HRESULT put_VITCLine(
  long Line );

파라미터

Line
[in] 타임 코드 정보를 저장 하는, 11 에서 20 의 범위내의 라인.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

IAMTimecodeReader::SetTCRMode 메소드로 VITC 모드가 지정되고 있는 경우는, 타임 코드 정보를 포함한 라인을 지정할 필요가 있다. 특정의 복수의 라인 위에의 VITC 를 읽어내려면 , 목적의 라인 마다 put_VITCLine 를 연속해 호출한다.

하이 비트를 세트 해 라인의 리스트에 추가하는 것에 의해, 리더가 복수의 라인을 조사한다.

참조

IAMTimecodeReader::get_VITCLine

IAMTimecodeReader::SetTCRMode

IAMTimecodeReader 인터페이스

타임 코드 리더의 프로퍼티를 설정한다.

구문

HRESULT SetTCRMode(
  long Param,
  long Value
  );

파라미터

Param
[in] 설정하는 프로퍼티. ED_TCR_SOURCE 또는 ED_TCR_NOTIFY_ENABLE 를 설정한다.
Value
[in] 지정의 프로퍼티의 값. Param 에 ED_TCR_NOTIFY_ENABLE 가 지정되고 있는 경우는, OATRUE 또는 OAFALSE 를 지정한다. Param 에 ED_TCR_SOURCE 가 지정되고 있는 경우는, 다음의 어느쪽이든을 지정한다.
ED_TCR_CT | 컨트롤 트럭
ED_TCR_LTC | LTC (Liner Timecode)
ED_TCR_VITC | VITC (Vertical Interval Timecode)
ED_TCR_LAST_VALUE | 전회의 독해값을 돌려준다

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

LTC 는, 아날로그 오디오 트럭상에서 NRZ 바이페즈마크 encode 신호로서 기록된다. 각 타임 코드 프레임은, 시간폭내의 1 개의 비디오 프레임 타임이다.

VITC 는, 보통, 비디오 신호의 수직 동기 간격의, 10 에서 20 의 범위내의 2 개의 라인에 저장 된다.

컨트롤 트럭은, 테이프 위에의 특별한 트럭에, 1 프레임 근처 1 회 기록되는 신호이다. 헤드 및 드라이브 서보의 메카니즘에서는, 이것을 사용해 모든 것을 잠근다. 또, 타임 코드 기능을 갖추지 않은 머신상에서 카운터를 조작하는데 사용했을 경우에 따라서는 타임 코드 리더가 장비 되고 있는 머신상에서도 사용할 수 있다.

ED_TCR_LAST_VALUE 는, 외부 디바이스에 대해서 다른 타임 코드 요구를 보내는 것이 어플리케이션으로 바람직하지 않는 경우에, 타임 코드 통지를 이행 할 경우에 사용된다. 이 방법은 multi-thread에 관한 문제가 있으므로, 프레임의 정확함이 요구되는 어플리케이션에서는, 그 사용은 추천 되지 않는다.

참조

IAMTimecodeReader::GetTCRMode


IAMTuner 인터페이스

IAMTuner 인터페이스는 IAMTVTuner 의 base class로,IAMTVTuner 는 IAMTuner 의 모든 메소드를 계승한다. Microsoft® DirectShow® 를 사용해 TV 튜너를 제어하는 방법의 상세한 것에 대하여는,IAMTVTuner 의 문서를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTuner 메소드 | 설명
put_Channel | TV 채널을 설정한다.
get_Channel | 튜너로 설정되어 있는 TV 채널을 취득한다.
ChannelMinMax | 사용 가능한 채널의 최대치와 최소 값을 취득한다.
put_CountryCode | 나라 코드를 설정해, 사용하는 주파수를 확립한다.
get_CountryCode | 나라 코드를 취득한다.
put_TuningSpace | 채널 주파수 변환의 지역 매핑의 저장 인덱스를 설정한다.
get_TuningSpace | 지역의 최적 튜닝의 저장 인덱스를 취득한다.
Logon | 유저를 시스템에 로그 온 시킨다.
Logout | 유저를 시스템으로부터 로그 오프 시킨다.
SignalPresent | 지정된 채널의 신호의 강도를 취득한다.
put_Mode | 다기능 튜너가 지정된 모드로 설정한다.
get_Mode | 다기능 튜너의 현재의 모드를 취득한다.
GetAvailableModes | 그 튜너로 지원 되고 있는 모드를 취득한다.
RegisterNotificationCallBack | IAMTunerNotification 인터페이스를 이행 하는 오브젝트가, 튜너 상태가 변화했을 때에 이벤트 통지를 받을 수가 있도록(듯이) 한다.
UnRegisterNotificationCallBack | 이벤트 통지 대상의 오브젝트의 등록을 삭제한다.

IAMTuner::ChannelMinMax

IAMTuner 인터페이스

사용 가능한 채널의 최대치와 최소 값을 취득한다.

구문

HRESULT ChannelMinMax(
    long *lChannelMin,
    long *lChannelMax
);

파라미터

lChannelMin
[out] 최소 채널을 받는 변수에의 포인터.
lChannelMax
[out] 최대 채널을 받는 변수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

국제 아날로그 TV의 튜닝

IAMTuner::get_Channel

IAMTuner 인터페이스

튜너로 설정되어 있는 TV 채널을 취득한다.

구문

HRESULT get_Channel (
    long *plChannel,
    long *plVideoSubChannel,
    long *plAudioSubChannel
);

파라미터

plChannel
[out] 채널을 받는 변수에의 포인터. 주파수에 대해서는, 「국제 아날로그 TV의 튜닝」을 참조할것.
plVideoSubChannel
[out] 정의 끝난 비디오 서브 채널값을 받는 변수에의 포인터. AMTUNER_SUBCHAN_NO_TUNE 는 튜닝 없음을 나타내, AMTUNER_SUBCHAN_DEFAULT 는 디폴트의 서브 채널을 나타낸다.
plAudioSubChannel
[out] 정의 끝난 오디오 서브 채널을 받는 변수에의 포인터. AMTUNER_SUBCHAN_NO_TUNE 는 튜닝 없음을 나타내, AMTUNER_SUBCHAN_DEFAULT 는 디폴트의 서브 채널을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMTuner::get_CountryCode

IAMTuner 인터페이스

현재의 채널과 주파수의 매핑을 확립해 있는 나라 코드를 취득한다.

구문

HRESULT get_CountryCode(
    long *plCountryCode
);

파라미터

plCountryCode
[out] 현재 TV 튜너 필터로 사용되고 있는 나라 코드를 받는 변수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

put_CountryCode 메소드에 의해, 사용하는 채널과 주파수의 매핑 테이블이 결정된다. 이것에 의해, 지정된 나라의 기본 주파수가 확립된다. 특정의 지역의 정확한 주파수를 결정하는 경우는,IAMTVTuner::AutoTune 메소드를 사용한다.

다른 나라의 소스로부터 브로드캐스트 비디오를 수신하는 경우는, 나라 코드를 오버라이드(override) 한다. 나라 코드의 리스트에 대해서는, 「국제 아날로그 TV의 튜닝」을 참조할것.

IAMTuner::get_Mode

IAMTuner 인터페이스

다기능 튜너의 현재의 모드를 취득한다.

구문

HRESULT get_Mode(
    AMTunerModeType *plMode
);

파라미터

plMode
[out] 현재의 모드 설정을 나타내는 플래그를 받는 변수에의 포인터. 취득할 수 있는 값은,AMTunerModeType 열거형으로 정의된다.

반환값

HRESULT 값을 돌려준다.

IAMTuner::get_TuningSpace

IAMTuner 인터페이스

튜닝 공간을 취득한다.

구문

HRESULT get_TuningSpace(
    long *plTuningSpace
);

파라미터

*plTuningSpace
[out] 현재의 튜닝 공간을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

어플리케이션은 이 메소드로 취득한 값을 정의한다. 이 값은,put_TuningSpace 를 호출해 설정한다.

IAMTuner::GetAvailableModes

IAMTuner 인터페이스

튜너로 지원 되고 있는 모드를 취득한다.

구문

HRESULT GetAvailableModes(
    long *plModes
);

파라미터

plModes
[out] AMTunerModeType 열거형으로 지정되고 있는 값의 편성을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다.

IAMTuner::Logon

IAMTuner 인터페이스

유저를 시스템에 로그 온 시킨다.

구문

HRESULT Logon(
    HANDLE hCurrentUser
);

파라미터

hCurrentUser
[in] 현재의 유저를 식별하는 어플리케이션 정의의 데이터 구조체에의 핸들.

반환값

HRESULT 값을 돌려준다.

주의

Logon 및 Logout 를 사용 하면, 유저 액세스의 선택을 실현할 수 있다.

IAMTuner::Logout

IAMTuner 인터페이스

현재의 유저를 로그아웃 시킨다.

구문

HRESULT Logout(void);

반환값

HRESULT 값을 돌려준다.

IAMTuner::put_Channel

IAMTuner 인터페이스

TV 채널을 설정한다.

구문

HRESULT put_Channel(
    long lChannel,
    long lVideoSubChannel,
    long lAudioSubChannel
);

파라미터

lChannel
[in] TV 채널의 번호.
lVideoSubChannel
정의 끝난 비디오 서브 채널값. AMTUNER_SUBCHAN_NO_TUNE 는 튜닝 없음을 나타내, AMTUNER_SUBCHAN_DEFAULT 는 디폴트의 서브 채널을 나타낸다. 위성방송의 경우에게만 유효하다.
lAudioSubChannel
정의 끝난 오디오 서브 채널값. AMTUNER_SUBCHAN_NO_TUNE 는 튜닝 없음을 나타내, AMTUNER_SUBCHAN_DEFAULT 는 디폴트의 서브 채널을 나타낸다. 위성방송의 경우에게만 유효하다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드는, TV 채널을 TV 주파수로 변환하는, 채널 주파수 변환 함수의 호출을 처리한다. 채널에 대한 주파수의 리스트에 대해서는, 「국제 아날로그 TV의 튜닝」을 참조할것.

IAMTuner::put_CountryCode

IAMTuner 인터페이스

나라 코드를 설정해, 사용하는 주파수를 확립한다.

구문

HRESULT put_CountryCode(
    long lCountryCode
);

파라미터

lCountryCode
[in] 국 코드를 나타내는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드에 의해, 지정된 나라의 기본 주파수가 확립된다. 지정된 나라에 관해서 이전에 캐쉬된 설정이 없는 경우, 특정의 지역의 정확한 주파수를 결정하려면 ,IAMTVTuner::AutoTune 메소드를 사용한다.

채널에는 각국에서 다른 주파수가 맵 되고 있으므로, 부록의 「국제 아날로그 TV의 튜닝」으로 세계 각지의 매핑 테이블을 제공하고 있다. 이 부록으로부터 새로운 값을 선택해,put_CountryCode 메소드의 파라미터로서 건네주어, 기존의 나라 코드를 오버라이드(override) 한다. 이것은, 다른 나라의 소스로부터 브로드캐스트 비디오를 수신하는 경우에 편리하다.

IAMTuner::put_Mode

IAMTuner 인터페이스

지정된 모드를 다기능 튜너로 설정한다.

구문

HRESULT put_Mode(
    AMTunerModeType lMode
);

파라미터

lMode
[in] 변환처의 모드를 나타내는 플래그. 지정할 수 있는 값은,AMTunerModeType 열거형으로 정의된다.

또, 카드로 디지털 TV 가 지원 되고 있는 경우에는, 모드를 디지털 TV 로 지정할 수 있다. 이것을 실시하려면 , AMTUNER_MODE_DTV 를 값 0x0010 로 정의한다.

반환값

HRESULT 값을 돌려준다.

IAMTuner::put_TuningSpace

IAMTuner 인터페이스

채널과 주파수의 지역 매핑의 저장 인덱스를 설정한다.

구문

HRESULT put_TuningSpace(
    long lTuningSpace
);

파라미터

lTuningSpace
[in] 현재의 로케일을 나타내는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

TV 튜너를 휴대용 시스템에 탑재하는 경우, 사용 가능한 채널과 그 실제의 주파수를 처리하는 로케일 고유의 매핑을 유지할 필요가 있다. 각 로케일용으로 다른 lTuningSpace 값을 지정하는 것으로, 지역간을 이동하는 경우에 채널과 주파수의 매핑을 바꾸는 수단이 제공된다.

IAMTuner::RegisterNotificationCallBack

IAMTuner 인터페이스

튜너 상태가 변화했을 때에,IAMTunerNotification 인터페이스를 이행 하는 오브젝트가 이벤트 통지를 받을 수가 있도록(듯이) 한다.

구문

HRESULT RegisterNotificationCallBack(
    IAMTunerNotification *pNotify
    long lEvents
);

파라미터

pNotify
[in] 튜너의 이벤트 통지를 받는 오브젝트의 IAMTunerNotification 인터페이스에의 포인터.
lEvents
[in] 이벤트가 발생한 것을 나타내는 플래그. 현재 정의되고 있는 값은, AMTUNER_EVENT_CHANGED 뿐이다.

반환값

HRESULT 값을 돌려준다.

IAMTuner::SignalPresent

IAMTuner 인터페이스

지정된 채널의 신호의 강도를 취득한다.

구문

HRESULT SignalPresent(
    long *plSignalStrength
);

파라미터

plSignalStrength
[out] 현재의 채널로 신호가 존재할지 어떨지를 나타내는 값을 받는 변수에의 포인터. 다음의 몇개의 값을 돌려준다.
AMTUNER_HASNOSIGNALSTRENGTH | -1
AMTUNER_NOSIGNAL | 0
AMTUNER_SIGNALPRESENT | 1

값 AMTUNER_HASNOSIGNALSTRENGTH 는, 이 시점에서는 신호 강도를 확인할 수 없는 것을 의미한다.

반환값

HRESULT 값을 돌려준다.

IAMTuner::UnRegisterNotificationCallBack

IAMTuner 인터페이스

이벤트 통지 대상의 오브젝트의 등록을 삭제한다.

구문

HRESULT UnRegisterNotificationCallBack(
    IAMTunerNotification *pNotify
);

파라미터

pNotify
[in] RegisterNotificationCallBack 를 이전에 호출했을 때에 지정한 IAMTunerNotification 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다.


IAMTunerNotification 인터페이스

텔레비젼 신호의 캡춰 또는 표시를 실시하는 어플리케이션으로 IAMTunerNotification 인터페이스를 이행 하면,IAMTuner::RegisterNotificationCallBack 를 개입시켜 불려 간 TV 튜너 필터로부터의 이벤트 통지를 받을 수가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTunerNotification 메소드 | 설명
OnEvent | TV 튜너 카드로부터의 이벤트를 처리한다.

IAMTunerNotification::OnEvent

IAMTunerNotification 인터페이스

TV 튜너 카드로부터의 이벤트를 처리한다.

구문

HRESULT OnEvent(
    AMTunerEventType Event
);

파라미터

Event
[in] 이벤트의 타입을 식별하는 플래그. 현재 정의되고 있는 값은, AMTUNER_EVENT_CHANGED 뿐이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.


IAMTVAudio 인터페이스

IAMTVAudio 인터페이스는,TV 오디오 필터로 이행 된다. 이 인터페이스에 의해, 어플리케이션은 세칸다리오디오프로그람 (SAP)등의 텔레비젼 소스로부터의 오디오에 특유의 설정, 및 스테레오 또는 단청의의 선택을 제어할 수 있다. 이러한 제어는, 일반적으로 시스템 오디오 믹서의 외부의 디바이스에 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTVAudio 메소드 | 설명
GetHardwareSupportedTVAudioModes | 하드웨어로 사용 가능한 포맷의 비트 마스크를 취득한다.
GetAvailableTVAudioModes | 사용 가능한 모드의 비트 마스크를 취득한다.
get_TVAudioMode | 현재의 TV 오디오 모드를 취득한다.
put_TVAudioMode | 현재의 TV 오디오 모드를 설정한다.

IAMTVAudio::GetHardwareSupportedTVAudioModes

IAMTVAudio 인터페이스

하드웨어로 사용 가능한 포맷의 비트 마스크를 취득한다.

구문

HRESULT GetHardwareSupportedTVAudioModes(
  long *plModes
  );

파라미터

plModes
[out] 오디오 모드를 식별하는 TVAudioMode 열거형에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IAMTVAudio::GetAvailableTVAudioModes

IAMTVAudio 인터페이스

사용 가능한 모드의 비트 마스크를 취득한다.

구문

HRESULT GetAvailableTVAudioModes(
  long *plModes
);

파라미터

plModes
[out] 오디오 모드를 식별하는 TVAudioMode 열거형에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IAMTVAudio::get_TVAudioMode

IAMTVAudio 인터페이스

현재의 TV 오디오 모드를 취득한다.

구문

HRESULT get_TVAudioMode(
  long *plModes
);

파라미터

plModes
[out] 오디오 모드를 식별하는 TVAudioMode 열거형에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IAMTVAudio::put_TVAudioMode

IAMTVAudio 인터페이스

현재의 TV 오디오 모드를 설정한다.

구문

HRESULT put_TVAudioMode(
  long plModes
);

파라미터

plModes
[in] 오디오 모드를 식별하는 TVAudioMode 열거형.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.


IAMTVAudioNotification 인터페이스

TV 오디오 필터를 사용하는 어플리케이션은,IAMTVAudioNotification 인터페이스를 이행 해,IAMTuner::RegisterNotificationCallBack 를 개입시켜 TV 튜너 카드로부터의 이벤트 통지를 받을 수가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTVAudioNotification 메소드 | 설명
OnEvent | IAMTVAudio 인터페이스로 제어되는 TV 튜너 카드로부터의 이벤트를 처리한다.

IAMTVAudioNotification::OnEvent

IAMTVAudioNotification 인터페이스

IAMTVAudio 인터페이스로 제어되는 TV 튜너 카드로부터의 이벤트를 처리한다.

구문

HRESULT OnEvent(
    AMTVAudioEventType Event
);

파라미터

Event
[in] 이벤트의 타입을 식별하는 플래그. 현재 정의되고 있는 값은, AMTVAUDIO_EVENT_CHANGED 뿐이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.


IAMTVTuner 인터페이스

IAMTVTuner 인터페이스는,TV 튜너 필터로 이행 된다. 이 인터페이스는, 어플리케이션이 TV 튜너 디바이스를 제어할 수 있는 메소드를 IAMTuner 로부터 계승해, 제공한다. 이 인터페이스는, 아날로그 방송텔리비전 및 AM/FM 라디오에 대응하고 있다.

IAMTVTuner 는, 복수의입력 핀을 가지는 튜너에 대응하고 있어, 복수의 디바이스 및 복수의 전송 타입을 사용할 수 있다.

IAMTVTuner 는,IAMTuner::put_Channel 메소드 및 IAMTVTuner::AutoTune 메소드를 개입시켜, TV 채널을 특정의 주파수에 맵 한다. 이 2 개의 메소드는, 하드웨어 드라이버가 정확한 주파수를 취득하도록(듯이) 이 변환의 세부를 취급한다. TV 튜너 필터는 세계 각지의 튜닝 범위를 지원 하고 있다.

TV 채널의 설정, 그 채널의 주파수 정보의 취득 또는 설정, 및 사용하는 TV 튜너 카드가 대응하고 있는 아날로그 비디오 규격을 판별하려면 , 어플리케이션으로부터 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMTuner 메소드 | 설명
put_Channel | TV 채널을 설정한다.
get_Channel | 현재 엔코더로 설정되어 있는 TV 채널을 취득한다.
ChannelMinMax | 사용 가능한 채널의 최대치 및 최소 값을 취득한다.
put_CountryCode | 나라 코드를 설정해, 사용하는 주파수를 확립한다.
get_CountryCode | 현재의 채널과 주파수의 매핑을 확립해 있는 나라 코드를 취득한다.
put_TuningSpace | 채널과 주파수의 지역 매핑의 저장 인덱스를 설정한다.
get_TuningSpace | 지역의 최적 튜닝의 저장 인덱스를 취득한다.
Logon | 유저를 시스템에 로그 온 시킨다.
Logout | 유저를 시스템으로부터 로그 오프 시킨다.
SignalPresent | 지정된 채널의 신호의 강도를 취득한다.
put_Mode | 다기능 튜너의 조작 모드를 설정한다.
get_Mode | 다기능 튜너의 조작 모드를 취득한다.
GetAvailableModes | 튜너로 사용 가능한 비디오 모드를 판별한다.
RegisterNotificationCallBack | IAMTunerNotification 인터페이스를 이행 하는 오브젝트가, 튜너 상태가 변화했을 때에 이벤트 통지를 받을 수가 있도록(듯이) 한다.
UnRegisterNotificationCallBack | 이벤트 통지 대상의 오브젝트의 등록을 삭제한다.
IAMTVTuner 메소드 | 설명
get_AvailableTVFormats | 튜너가 지원 하고 있는 아날로그 비디오 TV 규격을 모두 취득한다.
get_TVFormat | 현재 사용되고 있는 아날로그 비디오 TV 규격을 취득한다.
AutoTune | 목적의 채널의 정확한 주파수를 스캔 한다.
StoreAutoTune | 모든 채널의 최적 튜닝 정보를 보존한다.
get_NumInputConnections | 튜너 필터에 접속된 TV 소스의 번호를 취득한다.
put_InputType | 튜너의 입력 타입 (케이블 또는 안테나)을 설정한다.
get_InputType | 입력 타입을 취득한다.
put_ConnectInput | 하드웨어 튜너 입력 접속을 설정한다.
get_ConnectInput | 하드웨어 튜너 입력 접속을 취득한다.
get_VideoFrequency | 현재의 비디오 주파수를 취득한다.
get_AudioFrequency | 현재의 오디오 주파수를 취득한다.

IAMTVTuner::AutoTune

IAMTVTuner 인터페이스

지정한 채널의 주파수의 정확한 신호를 스캔 한다.

구문

HRESULT AutoTune(
    long lChannel,
    long *plFoundSignal
);

파라미터

lChannel
[in] TV 채널의 번호
plFoundSignal
[out] 지정한 채널의 주파수가 검출되었는지 어떠했는지를 나타내는 변수에의 포인터. 0 이외는 검출된 것을 나타내, 0 은 검출되지 않았던 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

보통, TV 채널은, 지역 마다 일의의 주파수에 맵 된다. 복수의 송신기로 같은 채널을 할당할 수 있어 그 송신기가 지리적으로 근접하고 있으면(자), 혼신이 생기는 경우가 있다. 이 혼신을 막기 위해서(때문에), 각 송신기로 몇 안 되는 주파수 오프셋(offset)를 한다. 미국에서의 오프셋(offset) 범위는 최대 +/– 26.25 킬로헤르츠 (kHz)이다.

이 메소드는, 채널과 주파수의 변환을 처리해, 가장 정확한 주파수를 스캔 한다. 이 값은 IAMTVTuner::StoreAutoTune 메소드를 호출해 보존한다. 채널의 기본 주파수에 대해서는, 부록의 「국제 아날로그 TV 튜닝」을 참조할것.

IAMTVTuner::get_AudioFrequency

IAMTVTuner 인터페이스

현재 튜닝 되고 있는 오디오 주파수를 취득한다.

구문

HRESULT get_AudioFrequency(
    long *lFreq
);

파라미터

lFreq
[out] 오디오 주파수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이것은, 지정한 채널로 사용되고 있는 정확한 주파수를 조사할 수 있는 진단 메소드이다.

IAMTVTuner::get_AvailableTVFormats

IAMTVTuner 인터페이스

튜너가 지원 하고 있는 아날로그 비디오 TV 규격을 모두 취득한다.

구문

HRESULT get_AvailableTVFormats(
    long *lAnalogVideoStandard
);

파라미터

lAnalogVideoStandard
[out] 지원 되고 있는 아날로그 비디오 규격의 편성에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

지원 되고 있는 포맷에 대해서는, 「AnalogVideoStandard 열거형」을 참조할것.

IAMTVTuner::get_ConnectInput

IAMTVTuner 인터페이스

하드웨어 튜너 입력 접속을 취득한다.

구문

HRESULT get_ConnectInput (
    long *plIndex
);

파라미터

plIndex
[out] 접속을 취득하는 입력 핀에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMTVTuner::get_InputType

IAMTVTuner 인터페이스

put_InputType 로 설정되어 있는 입력 타입을 취득한다.

구문

HRESULT get_InputType (
    long lIndex,
    TunerInputType *pInputType
);

파라미터

lIndex
[in] 설정 대상의 입력 핀을 지정하는 인덱스값.
pInputType
[out] TunerInputType 접속 열거형에의 포인터. 케이블 (TunerInputCable ) 또는 안테나 (TunerInputAntenna ).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMTVTuner::get_NumInputConnections

IAMTVTuner 인터페이스

튜너 필터에 접속되고 있는 TV 소스의 수를 취득한다.

구문

HRESULT get_NumInputConnections(
    long *plNumInputConnections
);

파라미터

plNumInputConnections
[out] 튜너 필터에 접속되고 있는 TV 소스의 수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMTVTuner::get_TVFormat

IAMTVTuner 인터페이스

현재 사용되고 있는 아날로그 비디오 TV 규격을 취득한다.

구문

HRESULT get_TVFormat(
    long *plAnalogVideoStandard
);

파라미터

plAnalogVideoStandard
[out] 현재 TV 튜너 필터로 사용되고 있는 아날로그 비디오 규격에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

지원 되고 있는 포맷에 대해서는, 「AnalogVideoStandard 열거형」을 참조할것.

IAMTVTuner::get_VideoFrequency

IAMTVTuner 인터페이스

현재의 비디오 주파수를 취득한다.

구문

HRESULT get_VideoFrequency(
    long *lFreq
);

파라미터

lFreq
[out] 비디오 주파수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

이것은, 지정한 채널로 사용되고 있는 정확한 주파수를 조사할 수 있는 진단 메소드이다.

IAMTVTuner::put_ConnectInput

IAMTVTuner 인터페이스

하드웨어 튜너 입력 접속을 설정한다.

구문

HRESULT put_ConnectInput(
    long lIndex
);

파라미터

lIndex
[in] 접속을 설정하는 입력 핀의 인덱스값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMTVTuner::put_InputType

IAMTVTuner 인터페이스

튜너의 입력 타입 (케이블 또는 안테나)을 설정한다.

구문

HRESULT put_InputType(
    long lIndex,
    TunerInputType InputType
);

파라미터

lIndex
[in] 설정 대상의 입력 핀을 지정하는 인덱스값.
InputType
[in] TunerInputType 열거형으로 지정되는 접속 타입을 나타내는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMTVTuner::StoreAutoTune

IAMTVTuner 인터페이스

모든 채널의 최적 튜닝 정보를 보존한다.

구문

HRESULT StoreAutoTune(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드로 보존한 채널과 주파수의 정보를 오버라이드(override) 하려면 ,IAMTuner::put_CountryCode 메소드로 새로운 나라 코드를 설정한다. 나라 코드의 일람에 대해서는, 「국제 아날로그 TV 튜닝」을 참조할것.


IAMVfwCaptureDialogs 인터페이스

IAMVfwCaptureDialogs 인터페이스는,VFW 캡춰 필터로 이행 된다. 이 인터페이스에 의해, 어플리케이션은, Microsoft® Video for Windows® 캡춰 드라이버로 제공되는 3 종류의 다이알로그 박스 (소스, 포맷, 또는 표시)의 어느쪽이든을 표시할 수 있다. 어플리케이션으로, Video for Windows 캡춰 드라이버가 제공하는 다이알로그 박스를 사용해 유저가 설정을 변경할 수 있도록(듯이) 하는 경우는, 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMVfwCaptureDialogs 메소드 | 설명
HasDialog | 지정된 다이알로그 박스가 드라이버내에 존재할지 어떨지를 확인한다.
ShowDialog | 지정된 다이알로그 박스를 표시한다.
SendDriverMessage | 드라이버 고유의 메세지를 송신한다.

IAMVfwCaptureDialogs::HasDialog

IAMVfwCaptureDialogs 인터페이스

지정된 다이알로그 박스가 드라이버내에 존재할지 어떨지를 확인한다.

구문

HRESULT HasDialog(
  int iDialog );

파라미터

iDialog
[in] 필요한 다이알로그 박스. 이 다이알로그 박스는 VfwCaptureDialogs 열거형의 멤버이다.

반환값

드라이버에 목적의 다이알로그 박스가 있는 경우는 S_OK 를 돌려준다. 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

이 메소드는, Video for Windows 의 videoDialog 함수를 호출해, 해당하는 다이알로그 박스가 존재할지 어떨지를 조회한다.

IAMVfwCaptureDialogs::SendDriverMessage

IAMVfwCaptureDialogs 인터페이스

드라이버 고유의 메세지를 송신한다.

구문

HRESULT SendDriverMessage(
  int iDialog,
  int uMsg,
  long dw1,
  long dw2 );

파라미터

iDialog
[in] 드라이버의 다이알로그 박스의 핸들. 이 다이알로그 박스는 VfwCaptureDialogs 열거형의 멤버이다.
uMsg
[in] 드라이버에 송신하는 메세지.
dw1
[in] 메세지 데이터.
dw2
[in] 메세지 데이터.

반환값

반환값은, 각 드라이버내의 이행에 응해 다르다.

주의

이 메소드를 사용할 필요는 없다. 이 메소드를 사용 하면 임의의 프라이빗 메세지를 캡춰 드라이버에 송신할 수 있다. 다만, 임의의 메세지에 응답하는 동작이 결정되어 있지 않은 경우가 있으므로, 이 메소드는 유저의 책임에 대해 사용하는 것.

이 메소드는, Video for Windows 의 videoMessage 함수를 호출해, 목적의 드라이버 메세지를 송신한다.

IAMVfwCaptureDialogs::ShowDialog

IAMVfwCaptureDialogs 인터페이스

지정된 다이알로그 박스를 표시한다.

구문

HRESULT ShowDialog(
  int iDialog,
  long hwnd );

파라미터

iDialog
[in] 표시하는 다이알로그 박스. 이 다이알로그 박스는 VfwCaptureDialogs 열거형의 멤버이다.
hwnd
[in] 다이알로그 박스의 부모 윈도우의 핸들.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

목적의 드라이버가 스트리밍중 또는 다른 다이알로그 박스를 표시하고 있는 경우는, 이 메소드를 사용할 수 없다. 드라이버가 다이알로그 박스를 표시하고 있는 동안은, 필터를 스트림 (정지 또는 실행) 할 수 없다.

IAMVfwCaptureDialogs::ShowDialog 는, Video for Windows® 의 VideoDialog 함수를 호출해, 해당하는 다이알로그 박스를 표시한다.

이 메소드를 사용해 VfwCaptureDialog_Format 다이알로그 박스를 표시하는 경우, 캡춰 필터가 그래프로 이미 접속되고 있어, 기존의 그래프가 새로운 포맷을 받아들일 수가 없으면 VFW_E_CANNOT_CONNECT 에러 코드가 돌려주어진다. 이 에러가 발생했을 경우, 캡춰 어플리케이션은, 필터 그래프의 캡춰 필터의 다운 스트림인 부분을 재구축 할 필요가 있다.


IAMVfwCompressDialogs 인터페이스

IAMVfwCompressDialogs 인터페이스는,AVI 압력 필터로 이행 된다. 이 인터페이스에 의해, 어플리케이션은 Video for Windows CODEC 의 [Configure] 또는 [About] 다이알로그 박스를 표시해, 압력 상태의 설정과 취득을 실시할 수가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMVfwCompressDialogs methods | 설명
ShowDialog | 지정된 다이알로그 박스를 표시한다.
GetState | 현재 사용되고 있는 VCM CODEC 의 현재의 구성 설정을 취득한다.
SetState | VCM CODEC 의 구성을 설정한다.
SendDriverMessage | 드라이버 고유의 메세지를 송신한다.

IAMVfwCompressDialogs::GetState

IAMVfwCompressDialogs 인터페이스

현재 사용되고 있는 VCM CODEC 의 현재의 구성 설정을 취득한다.

구문

HRESULT GetState(

  LPVOID pState,

  int *pcbState

파라미터

pState
[out] VCM CODEC 상태.
pcbState
[in, out] 스테이트 정보의 사이즈에의 포인터.

반환값

반환값은, 각 드라이버내의 이행에 응해 다르다.

주의

이 메소드는, COM ICGetState 매크로를 호출한다.

IAMVfwCompressDialogs::SendDriverMessage

IAMVfwCompressDialogs 인터페이스

드라이버 고유의 메세지를 송신한다.

구문

HRESULT SendDriverMessage(
  int uMsg,
  long dw1,
  long dw2 );

파라미터

uMsg
[in] 드라이버에 송신하는 메세지.
dw1
[in] 메세지 데이터.
dw2
[in] 메세지 데이터.

반환값

반환값은, 각 드라이버내의 이행에 응해 다르다.

주의

이 메소드를 사용할 필요는 없다. 이 메소드를 사용 하면, 임의의 프라이빗 메세지를 비디오 압력 (CODEC)에 송신할 수 있다. 다만, 임의의 메세지에 응답하는 동작이 결정되어 있지 않은 경우가 있으므로, 이 메소드는 유저의 책임에 대해 사용하는 것.

이 메소드는, Video for Windows 의 비디오 압축 매니저 (VCM)의 ICSendMessage 함수를 호출해 메세지를 송신한다.

IAMVfwCompressDialogs::SetState

IAMVfwCompressDialogs 인터페이스

VCM CODEC 의 구성을 설정한다.

구문

HRESULT SetState(
  LPVOID pState,
  int cbState );

파라미터

pState
[in] VCM CODEC 상태.
cbState
[in] 스테이트 정보의 사이즈.

반환값

반환값은, 각 드라이버내의 이행에 응해 다르다.

주의

이 메소드는, COM ICSetState 매크로를 호출한다. 이 매크로는, 비디오 압축 드라이버에 압력 상태를 설정하도록(듯이) 통지한다.

IAMVfwCompressDialogs::ShowDialog

IAMVfwCompressDialogs 인터페이스

지정된 다이알로그 박스를 표시한다.

구문

HRESULT ShowDialog(
  int iDialog,
  long hwnd );

파라미터

iDialog
[in] 표시하는 다이알로그 박스. 이 다이알로그 박스는 VfwCompressDialogs 열거형의 멤버이다.
hwnd
[in] 다이알로그 박스의 부모 윈도우의 핸들.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

목적의 드라이버가 스트리밍중 또는 다른 다이알로그 박스를 표시하고 있는 경우에, 다이알로그 박스의 표시를 요구 하면, 이 메소드는 에러를 돌려준다. 드라이버가 다이알로그 박스를 표시하고 있는 동안은, 필터를 스트림 (정지 또는 실행) 할 수 없다.

IAMVfwCompressDialogs::ShowDialog 는 Video for Windows 의 비디오 압축 매니저 (VCM)의 함수 ICConfigure ,ICAbout ,ICQueryConfigure, 및 ICQueryAbout 를 호출해, 해당하는 다이알로그 박스를 표시하는지, 또는 그 다이알로그 박스가 존재할지 어떨지를 확인한다.

VfwCompressDialogs 열거형의 VfwCompressDialog_QueryConfig 및 VfwCompressDialog_QueryAbout 멤버에 의해, Configure 다이얼로그 또는 About 다이얼로그가 사용 가능한가 어떤가를 알 수 있다. 이 2 개의 플래그중 한쪽이 건네받으면(자), 필터는 다이얼로그가 존재하는 경우는 S_OK 를 돌려주어, 존재하지 않는 경우는 S_FALSE 를 돌려준다. 다이얼로그가 이용 가능한 경우, 값 VfwCompressDialog_Config 또는 VfwCompressDialog_About 를 지정해 ShowDialog 를 호출해, 다이얼로그를 표시한다.


IAMVideoAccelerator 인터페이스

IAMVideoAccelerator 인터페이스에 의해, 비디오 디코더 필터는 비디오 가속기 기능에 액세스 할 수 있다. 오버레이 믹서 필터의 입력 핀은, 이 인터페이스를 지원 하고 있다. 비디오 디코더 필터가 이 인터페이스로 메소드를 호출하는 경우, 디코더의 출력 핀으로 IAMVideoAcceleratorNotify 인터페이스를 지원 하고 있을 필요가 있다. 어플리케이션이, 이 인터페이스로 메소드를 호출할 필요는 없다.

주 : 이 인터페이스는 Microsoft® Windows® 2000 으로 사용할 수 있다.

비디오 디코더 필터의 접속에 관한 이벤트의 순서를 다음에 나타낸다.

  1. 필터 그래프 매니저가, 비디오 디코더 필터의 출력 핀으로 IPin::Connect 메소드를 호출한다.
  2. 비디오 디코더는, 오버레이 믹서의 입력 핀으로 IAMVideoAccelerator::GetVideoAcceleratorGUIDs 메소드를 호출해, 비디오 가속기의 GUID 의 리스트를 취득할 수 있다. 이것은, 오버레이 믹서가 받아들이는 비디오 가속기 포맷을 나타낸다.
  3. 비디오 디코더는, 지정된 비디오 가속기의 GUID 에 관해서 IAMVideoAccelerator::GetUncompFormatsSupported 를 호출해, 제시하는 적절한 픽셀 포맷을 확인한다.
  4. 비디오 디코더는, 오버레이 믹서의 입력 핀으로 IPin::ReceiveConnection 메소드를 호출해, 미디어 타입의서브 타입으로서 비디오 가속기의 GUID 를 지정한다. 이 호출내에서, 오버레이 믹서는, 디코더 필터의 출력 핀으로 다음의 메소드를 호출한다.
    • IAMVideoAcceleratorNotify::GetUncompSurfacesInfo 를 호출해, 생성 하는 출력 표면의 수를 확인한다. 디코더는, 할당하는 표면의 최소수와 최대수, 및 필요한 픽셀 포맷 정보를 돌려준다.
    • IAMVideoAcceleratorNotify::SetUncompSurfacesInfo 를 호출해, 실제로 할당할 수 있고 있는 표면의 수를 비디오 디코더에 통지한다.
    • IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData 를 호출해, 드라이버에 건네주는 비디오 가속기 생성 데이터를 취득해, 그 내부 비디오 가속기 오브젝트를 생성 한다.
  5. 비디오 디코더는 IAMVideoAccelerator::GetCompBufferInfo 를 호출해, 전으로 지정된 비디오 가속기의 GUID 에 관련지을 수 있고 있는 압축이 끝난 데이터 버퍼에 관한 정보를 취득한다.

동적인 포맷의 변경을 지원 하기 위해서, 필터가 접속되어 실행되고 있는 동안에 다음의 순서도 실행할 수 있다.

조작중에, 비디오 디코더가 다음의 순서를 실행한다.

  1. 압축되어 있지 않은 각 데이터 버퍼에 관해서,IAMVideoAccelerator::BeginFrame 를 호출해 출력 프레임의 처리를 시작 한다.
  2. 압축되어 있지 않은 데이터를 비디오 가속기에 보내기 위해서(때문에), 디코더가 다음의 메소드를 호출한다.
    • IAMVideoAccelerator::GetBuffer 를 호출해, 버퍼를 잠그어, 버퍼에의 액세스를 취득한다.
    • Execute 를 호출해, 일련의 압축이 끝난 버퍼내의 데이터를 처리한다.
    • IAMVideoAccelerator::ReleaseBuffer 를 호출해, 버퍼의 락을 해제한다.
    • IAMVideoAccelerator::QueryRenderStatus 를 호출해, 버퍼에 대한 기입 또는 독해가 가능한가 어떤가를 조회한다.
  3. 프레임 처리를 종료하기 위해서,IAMVideoAccelerator::EndFrame 를 호출한다.
  4. 프레임을 표시하기 위해서,IAMVideoAccelerator::DisplayFrame 를 호출한다.

GetBuffer 메소드로 버퍼를 잠그기 전에, 비디오 디코더는, 그 버퍼를 갱신하는 임의의 압축 해제 조작이 완료했는지 어떠했는지를 확인할 필요가 있다. DisplayFrame 에 대해서도 같이 비디오 디코더가 그 프레임을 갱신하는 모든 압축 해제 조작이 완료하고 있을지 어떨지를 확인할 필요가 있다.

요건

Videoacc.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMVideoAccelerator methods | 설명
GetVideoAcceleratorGUIDs | 받아들일 수 있는 비디오 가속기 포맷의 GUID 의 리스트를 취득한다.
GetUncompFormatsSupported | 지정된 비디오 가속기 포맷의 렌더링에 사용할 수 있는 픽셀 포맷의 리스트를 취득한다.
GetInternalMemInfo | 비디오 가속기의 GUID, 압축되어 있지 않은 데이터의 사이즈, 및 픽셀 포맷에 근거해, 압축되어 있지 않은 데이터의 메모리 요건에 관한 정보를 취득한다.
GetCompBufferInfo | 압축이 끝난 버퍼의 정보를 취득한다.
GetInternalCompBufferInfo | 핀이 접속된 후에 불려 가 접속하는 타입이 지정되고 있으면(자), 압축이 끝난 버퍼의 정보를 취득한다.
BeginFrame | 프레임 처리를 시작 한다.
EndFrame | 프레임 처리를 종료해, 각종의 데이터를 비디오 가속기 드라이버에 건네준다.
GetBuffer | 지정된 인덱스 및 타입의 압축이 끝난 버퍼를 취득한다.
ReleaseBuffer | 처리 후에 압축이 끝난 버퍼를 해방한다.
Execute | 압축 해제 조작을 실행한다.
QueryRenderStatus | 일련의 매크로 블록의 디코드 상태를 조회한다.
DisplayFrame | 디코드가 끝난 프레임을 표시한다.

IAMVideoAccelerator::GetVideoAcceleratorGUIDs

IAMVideoAccelerator

받아들일 수 있는 비디오 가속기 포맷의 GUID 의 리스트를 취득한다.

구문

HRESULT GetVideoAcceleratorGUID(
  LPDWORD pdwNumGuidsSupported,
  LPGUID pGuidsSupported
);

파라미터

pdwNumGuidsSupported
[in] [out] pGuidsSupported 가 NULL 의 경우,pdwNumGuidsSupported 는 지원 되고 있는 비디오 가속기 포맷의 GUID 의 수를 돌려준다. NULL 가 아닌 경우, 이 파라미터는 pGuidsSupported 에 돌려주어지는 GUID 의 최대수에의 포인터가 된다. 지원 되고 있는 비디오 가속기 포맷이 이 수보다 적은 경우,pdwNumGuidsSupported 는 실제로 돌려주어진 GUID 의 수에 갱신된다.
pGuidsSupported
[in] [out] 이 파라미터가 NULL 가 아닌 경우, 지원 되고 있는 GUID 가 이 배열에 돌려주어진다. 그 배열의 사이즈는, 바이트 단위로 적어도 sizeof(GUID) * (*pdwNumGuidsSupported) 이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMVideoAccelerator::GetUncompFormatsSupported

IAMVideoAccelerator

지정된 비디오 가속기 포맷의 렌더링에 사용할 수 있는 픽셀 포맷의 리스트를 취득한다.

구문

HRESULT GetUncompFormatsSupported(
    const GUID *pGuid,
    LPDWORD pdwNumFormatsSupported,
    LPDDPIXELFORMAT pFormatsSupported
);

파라미터

pGuid
[in] 비디오 가속기의 GUID 에의 포인터.
pdwNumFormatsSupported
[in] [out] pFormatsSupported 가 NULL 의 경우,pdwNumFormatsSupported 에는,pGuid 로 정의되고 있는 비디오 가속기 포맷화등 변환 가능한 픽셀 포맷의 수가 돌려주어진다. NULL 가 아닌 경우, 이 파라미터는 pFormatsSupported 에 돌려주어지는 픽셀 포맷의 수이다. 메소드가 돌아오면(자), 이 파라미터는 실제로 돌려주어진 픽셀 포맷의 수가 된다.
pFormatsSupported
[in] [out] DDPIXELFORMAT 구조체에의 포인터. 이 파라미터가 NULL 가 아닌 경우, 최대 *pdwNumFormatsSupported 개의 픽셀 포맷이 이 배열에 카피된다. 버퍼의 사이즈는, 적어도 *pdwNumFormatsSupported * sizeof(DDPIXELFORMAT) 이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMVideoAccelerator::GetInternalMemInfo

IAMVideoAccelerator

비디오 가속기의 GUID, 압축되어 있지 않은 데이터의 사이즈, 및 픽셀 포맷에 근거해, 압축되어 있지 않은 데이터의 메모리 요건에 관한 정보를 취득한다.

구문

HRESULT GetInternalMemInfo(
    const GUID *pGuid,
    const AMVAUncompDataInfo *pamvaUncompDataInfo,
    LPAMVAInternalMemInfo pamvaInternalMemInfo
);

파라미터

pGuid
[in] 비디오 가속기의 GUID 에의 포인터.
pamvaUncompDataInfo
[in] 압축되어 있지 않은 데이터의 사이즈와 픽셀 포맷의 정보를 포함한 AMVAUncompDataInfo 구조체에의 포인터.
pamvaInternalMemInfo
[in] [out] scratch memory 요건에 관한 정보를 포함한 AMVAInternalMemInfo 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMVideoAccelerator::GetCompBufferInfo

IAMVideoAccelerator

압축이 끝난 버퍼 정보를 취득한다.

구문

HRESULT GetCompBufferInfo(
    const GUID *pGuid,
    const AMVAUncompDataInfo *pamvaUncompDataInfo,
    LPDWORD pdwNumTypesCompBuffers,
    LPAMVACompBufferInfo pamvaCompBufferInfo
);

파라미터

pGuid
[in] 비디오 가속기 포맷의 GUID 에의 포인터.
pamvaUncompDataInfo
[in] 압축되어 있지 않은 데이터의 사이즈 및 픽셀 포맷의 정보를 포함한 AMVAUncompDataInfo 구조체에의 포인터.
pdwNumTypesCompBuffers
[in] [out] DWORD 형의 변수에의 포인터. pamvaCompBufferInfo 가 NULL 가 아닌 경우, 이 파라미터는, 압축되어 있지 않은 버퍼 타입의 수를 취득한다. NULL 의 경우, 입력이면, 이 파라미터는 돌려주어지는 압축이 끝난 버퍼 타입의 최대수를 지정해, 출력이면, 압축이 끝난 버퍼 타입의 실제의 수를 취득한다.
pamvaCompBufferInfo
[out] NULL 이외의 경우, 최대pdwNumTypesCompBuffers 개의 AMVACompBufferInfo 구조체가 돌려주어진다. 이 데이터에는, 표면의 생성에 사용되는 폭, 높이, 픽셀 포맷, DirectDraw 기능, 및 표면이 점유 하는 사이즈 (바이트 단위)가 포함된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, DirectDraw 를 사용해, 필요한 타입의 비디오 가속기 표면을 생성 하기 위해서 필요한 정보를 돌려준다. 비디오 가속기 드라이버로, 복수의 압축이 끝난 버퍼 타입 (예를 들어, 비디오 가속기 데이터와 역이산 코사인 변환 [IDCT] 데이터)이 지원 되고 있는 경우가 있다.

IAMVideoAccelerator::GetInternalCompBufferInfo

IAMVideoAccelerator

핀이 접속된 후에 불려 가 접속하는 타입이 지정되고 있으면(자), 압축이 끝난 버퍼의 정보를 취득한다.

구문

HRESULT GetInternalCompBufferInfo(
    LPDWORD pdwNumTypesCompBuffers,
    LPAMVACompBufferInfo pamvaCompBufferInfo
);

파라미터

pdwNumTypesCompBuffers
[in] [out] DWORD 형의 변수에의 포인터. pamvaCompBufferInfo 가 NULL 가 아닌 경우, 이 파라미터는 압축되어 있지 않은 버퍼 타입의 수를 취득한다. NULL 의 경우, 입력이면, 이 파라미터는 돌려주어지는 압축이 끝난 버퍼 타입의 최대수를 지정해, 출력이면, 압축이 끝난 버퍼 타입의 실제의 수를 취득한다.
pamvaCompBufferInfo
[out] NULL 이외의 경우, 최대 pdwNumTypesCompBuffers 개의 AMVACompBufferInfo 구조체가 돌려주어진다. 이 데이터에는, 표면의 생성에 사용되는 폭, 높이, 픽셀 포맷, DirectDraw 기능, 및 표면이 점유 하는 사이즈 (바이트 단위)가 포함된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

비디오 가속기 드라이버로, 복수의 압축이 끝난 버퍼 타입 (예를 들어, 비디오 가속기 데이터와 역이산 코사인 변환 [IDCT] 데이터)이 지원 되고 있는 경우가 있다.

IAMVideoAccelerator::BeginFrame

IAMVideoAccelerator

프레임 처리를 시작 한다.

구문

HRESULT BeginFrame(
    const AMVABeginFrameInfo *pamvaBeginFrameInfo
    );

파라미터

pamvaBeginFrameInfo
[in] 프레임 처리의 시작에 필요한 정보를 포함한 AMVABeginFrameInfo 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, 핀이 접속된 후에게만 호출할 수가 있다.

AMVABeginFrameInfo 구조체에는, 전송처 버퍼의 인덱스가 포함된다. 유효한 인덱스값은, 0 으로부터 dwActualUncompSurfacesAllocated–1 의 범위이다. dwActualUncompSurfacesAllocated 의 값은 IAMVideoAcceleratorNotify::SetUncompSurfacesInfo 를 호출해 취득한다.

사용되는 프레임 메모리가 이 후레임인젝스로 마지막에 사용된 메모리와 다른 경우가 있으므로, 디코더가 그 프레임의 초기 컨텐츠에 관한 인계는 실시하지 않게 한다.

비어 있는 frame buffer가 없으면 이 메소드의 호출은 처리중의 조작을 블록 하는 경우가 있다.

IAMVideoAccelerator::EndFrame

IAMVideoAccelerator

프레임 처리를 종료해, 각종의 데이터를 비디오 가속기 드라이버에 건네준다.

구문

HRESULT EndFrame(
    const AMVAEndFrameInfo *pEndFrameInfo
);

파라미터

pEndFrameInfo
[in] 비디오 가속기 드라이버에 건네주는 각종의 데이터가 포함되는 AMVAEndFrameInfo 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IAMVideoAccelerator::GetBuffer

IAMVideoAccelerator

지정된 인덱스 및 타입의 압축이 끝난 버퍼를 취득한다.

구문

HRESULT GetBuffer(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex,
    BOOL bReadOnly,
    LPVOID *ppBuffer,
    LONG *lpStride
);

파라미터

dwTypeIndex
[in] 비디오 가속기 드라이버로 지원 되고 있는 표면 타입에의 0 을 기준으로 하는 인덱스, 또는 0xFFFFFFFF. 「주의」를 참조할것.
dwBufferIndex
[in] 타입내의 버퍼 인덱스. 유효 범위는, 0 으로부터 AMVACompBufferInfo 구조체의 dwNumCompBuffers 멤버의 값까지이다.
bReadOnly
[in] 버퍼가 갱신될지 어떨지를 나타내는 불리언 값. TRUE 의 경우, 버퍼는 갱신되지 않고, Busy인 참조 프레임에 액세스 할 수 있다.
ppBuffer
[out] 압축이 끝난 데이터가 저장 되는 버퍼에의 포인터. 이 버퍼의 사이즈는,GetInternalCompBufferInfo 메소드로부터 dwSurfaceTypeIndex 엔트리에 돌려주어지는 AMVACompBufferInfo 구조체의 dwBytesToAllocate 멤버에 의해 확정된다.
lpStride
[out] 이 압축 타입과 호환성이 있는 보폭. 보통, 이 보폭은,AMVACompBufferInfo 구조체의 dwWidthToCreate 멤버와 동일하다. 출력 디스플레이 버퍼 또는 그 외의 압축되어 있지 않은 타입에 대해서는,dwWidthToCreate 와 동일하지 않은 경우도 있는 것에 주의한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, 단일의 버퍼를 잠그어, 버퍼에의 액세스를 취득한다. 버퍼는 타입과 그 타입내의 인덱스에 의해 식별된다. IAMVideoAccelerator::GetInternalCompBufferInfo 메소드는 pdwNumTypesCompBuffers 파라미터에 타입수를 돌려준다. 이것에 의해 dwTypeIndex 의 유효 범위가 정의된다. 각 타입에 대해서,AMVACompBufferInfo 구조체의 dwNumCompBuffers 멤버는 버퍼의 수를 준다. 이것에 의해 dwBufferIndex 의 유효 범위가 정의된다. dwTypeIndex 와 dwBufferIndex 에는 양쪽 모두 0 을 기준으로 하는 오프셋(offset)를 지정하는 것에 주의 해야 한다.

또, 타입 인덱스 0xFFFFFFFF 를 사용해 출력 버퍼에의 포인터를 취득하는 방법도 있다. 현재, 이것은 BeginFrame 의 호출과 EndFrame 의 호출동안에서만 유효하다. 이 경우, 버퍼 인덱스는, 마지막 BeginFrame 호출에게 건네진 AMVABeginFrameInfo 구조체의 dwDestSurfaceIndex 멤버와 동일할 필요가 있다.

필터의 핀이 접속되어 있지 않으면 이 메소드는 실패한다.

압축이 끝난 버퍼가 모두 해방될 때까지, 이 thread가 Win16 락 또는 DirectDraw 락을 보관 유지하는 일이 있다.

IAMVideoAccelerator::ReleaseBuffer

IAMVideoAccelerator

처리 후에 압축이 끝난 버퍼를 해방한다.

구문

HRESULT ReleaseBuffer(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex
);

파라미터

dwTypeIndex
[in] 비디오 가속기 드라이버로 지원 되고 있는 표면 타입에의 0 을 기준으로 하는 인덱스, 또는 0xFFFFFFFF.
dwBufferIndex
[in] 타입내의 버퍼 인덱스. 유효 범위는, 0 으로부터AMVACompBufferInfo 구조체의 dwNumCompBuffers 멤버의 값까지이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, 핀의 접속 후에 호출했을 경우에게만 유효하다. 이 메소드를 호출하면, 단일의 버퍼의 락이 해제된다. 비디오 디코더는, 버퍼가 더 이상 필요없는 경우에,Execute 가 불려 간 후에 이 메소드를 호출한다. 이 호출의 뒤, 버퍼 포인터는 무효가 되는 것에 주의 해야 한다.

IAMVideoAccelerator::Execute

IAMVideoAccelerator

압축 해제 조작을 실행한다.

구문

HRESULT Execute(
    DWORD dwFunction,
    LPVOID lpPrivateInputData,
    DWORD cbPrivateInputData,
    LPVOID lpPrivateOutputData,
    DWORD cbPrivateOutputData,
    DWORD dwNumBuffers,
    const AMVABUFFERINFO *pamvaBufferInfo
);

파라미터

dwFunction
[in] 함수 번호. 인수가 디폴트인지, 또는 지정하지 않는 경우는, 제로가 된다.
lpPrivateInputData
[in] 드라이버에게 건네지는 프라이빗 입력 데이터에의 포인터.
cbPrivateInputData
[in] 프라이빗 입력 데이터의 길이.
lpPrivateOutputData
[in] 드라이버에게 건네지는 프라이빗 출력 데이터에의 포인터.
cbPrivateOutputData
[in] 프라이빗 데이터 버퍼의 길이.
dwNumBuffers
[in] AMVABUFFERINFO 구조체의 수
pamvaBufferInfo
[in] 건네받는 AMVABUFFERINFO 구조체의 리스트에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, 핀의 접속 후에 호출했을 경우에게만 유효하다.

관련지을 수 있고 있는 버퍼의 리스트는, 함수 번호 (디폴트는 0) 및 압축 해제 조작을 설명하는 필요한 프라이빗 데이터와 함께 건네받는다. 예를 들어, 압축이 해제된 참조 프레임 정보는 버퍼 리스트에게 건네진다. 버퍼 리스트의 순서는 중요해, 실행되는 특정의 압축 해제 조작에 의해 정의된다.

프라이빗 데이터는 드라이버에 건네주는 일도 드라이버로부터 받을 수도 있다.

IAMVideoAccelerator::QueryRenderStatus

IAMVideoAccelerator

일련의 매크로 블록의 디코드 상태를 조회한다.

구문

HRESULT QueryRenderStatus(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex,
    DWORD dwFlags
);

파라미터

dwTypeIndex
[in] 테스트되는 버퍼의 타입 인덱스.
dwBufferIndex
[in] 테스트되는 버퍼의 버퍼 인덱스.
dwFlags
[in] 실행되는 조회의 타입을 나타내는 플래그. 제로의 경우, 표면을 갱신에 사용해도 안전한가 어떤가가 테스트된다. AMVA_QUERYRENDERSTATUSF_READ 의 경우, 표면을 읽어내에 사용해도 안전한가 어떤가가 테스트된다.

반환값

HRESULT 값을 돌려준다. 조작이 완료했을 경우는 S_OK, 조작이 진행중의 경우는 E_PENDING 를 돌려준다. 조작이 실패 하면, 이 메소드는 다른 실패 코드를 돌려준다. 이 코드에는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 포함된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드를 호출하면, 진행 상황과 실패가 보고된다.

IAMVideoAccelerator::DisplayFrame

IAMVideoAccelerator

디코드가 끝난 프레임을 표시한다.

구문

HRESULT DisplayFrame(
    DWORD dwFlipToIndex,
    IMediaSample *pMediaSample
);

파라미터

dwFlipToIndex
[in] 표시하는 압축 해제된 프레임의 표면 인덱스.
pMediaSample
[in] 시작과 정지의 타임 스탬프가 포함되는 IMediaSample 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, 핀의 접속 후에 호출했을 경우에게만 유효하다. 이 호출은 다른 조작을 블록 하지 않는다.

비디오 디코더는, 인덱스가 dwFlipToIndex 인 표면에 대해서 EndFrame 를 호출한 후에, 이 메소드를 호출한다. 이 인덱스는, 전에 BeginFrame 의 호출로 건네받은 AMVABeginFrameInfo 구조체의 dwDestSurfaceIndex 멤버의 값일 필요가 있다.


IAMVideoAcceleratorNotify 인터페이스

IAMVideoAcceleratorNotify 인터페이스는, 비디오 디코더의출력 핀으로 지원 되고 있다. 이 메소드는, 다운 스트림 오버레이 믹서와 핀이 접속하고 있는 동안에 불려 가IAMVideoAccelerator 인터페이스를 설정한다.

주 : 이 인터페이스는, Microsoft® Windows® 2000 으로 사용할 수 있다.

요건

Videoacc.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMVideoAcceleratorNotify 메소드 | 설명
GetUncompSurfacesInfo | 지정된 비디오 가속기의 GUID 에 관한 압축 해제된 버퍼의 정보를 취득한다.
SetUncompSurfacesInfo | 압축되어 있지 않은 버퍼의 정보를 설정한다.
GetCreateVideoAcceleratorData | 비디오 가속기 오브젝트의 생성에 필요한 정보를 취득한다.

IAMVideoAcceleratorNotify::GetUncompSurfacesInfo

IAMVideoAcceleratorNotify

지정된 비디오 가속기의 GUID 에 대한 압축 해제된 버퍼의 정보를 취득한다.

구문

HRESULT GetUncompSurfacesInfo(
    const GUID *pGuid,
    LPAMVAUncompBufferInfo pUncomBufferInfo
);

파라미터

pGuid
[in] 정보 취득 대상의 비디오 가속기를 식별하는 GUID 에의 포인터.
pUncompBufferInfo
[in, out] 압축되어 있지 않은 표면 정보를 포함한 AMVAUncompBufferInfo 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드를 호출하면, 픽셀 포맷 뿐만이 아니라, 표면의 최소수 및 최대수에 대한 비디오 디코더의 요건이 돌려주어진다. 이 메소드는 압축되어 있지 않은 데이터 버퍼의 할당에 필요한 정보를 제공한다.

IAMVideoAcceleratorNotify::SetUncompSurfacesInfo

IAMVideoAcceleratorNotify

압축되어 있지 않은 버퍼의 정보를 설정한다.

구문

HRESULT SetUncompSurfacesInfo(
    DWORD  dwActualUncompSurfacesAllocated
);

파라미터

dwActualUncompSurfacesAllocated
[in] 할당할 수 있는 표면의 수.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드를 호출하면, 실제로 할당할 수 있고 있는 압축 해제된 표면의 수가 비디오 디코더에 통지된다.

IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData

IAMVideoAcceleratorNotify

비디오 가속기 오브젝트의 생성에 필요한 정보를 취득한다.

구문

HRESULT GetCreateVideoAcceleratorData(
    const GUID *pGuid,
    LPWDORD pdwSizeMiscData,
    LPVOID *ppMiscData
);

파라미터

pGuid
[in] 비디오 가속기를 식별하는 GUID 에의 포인터.
pdwSizeMiscData
[out] ppMiscData 에 돌려주어지는 데이터의 사이즈 (바이트 단위)를 받는 변수에의 포인터.
ppMiscData
[out] 각종의 데이터 (pdwSizeMiscData 이 0 의 경우는 NULL)를 받는 void 형의 포인터에의 주소. 이 포인터는 CoTaskMemAlloc (COM 라이브러리의 헬퍼 함수)로 할당할 필요가 있다. 이 주소는 호출해 원이 해방한다. 「주의」를 참조할것.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, 비디오 가속기의 초기화시에 비디오 디코더가 비디오 가속기에 송신할 필요가 있는 각종의 데이터에의 포인터를 취득한다. ppMiscData 에 대해 CoTaskMemFree 를 호출하는 조작은 호출해 원으로 실시한다.


IAMVideoCompression 인터페이스

IAMVideoCompression 핀인타페이스를 사용 하면, 미디어 타입에 포함되지 않은 압축 파라미터를 제어할 수 있다.

put_PFramesPerKeyFrame 메소드 및 get_PFramesPerKeyFrame 메소드는, 예측 (P) 프레임 및 양방향 예측 (B) 프레임을 참조한다. 이것은, MPEG 의 개념으로, 일반적으로 MPEG 보다 단순한 타입의 압력에는 해당하지 않는다.

이 인터페이스를, 압축이 끝난 비디오 데이터를 제공하는 비디오 캡춰 또는 비디오 압력 필터의출력 핀으로 이행 한다.

어플리케이션은, 이 인터페이스를 사용해,키 프레임의 수, 프레임 품질등의 특성을 포함해, 비디오의 압축 방법을 제어한다. 또, 압력의 텍스트 설명, 및 압력의 기능등의 그 외의 입수 가능한 정보의 취득에 사용한다.

주 : 이 인터페이스는, 캡춰 필터의 출력 핀이 그래프내의 다른 필터에 접속하고 있지 않는 경우, 사용할 수 없는 것이 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMVideoCompression methods | 설명
put_KeyFrameRate | 키 frame rate를 설정한다.
get_KeyFrameRate | 키 frame rate를 취득한다.
put_PFramesPerKeyFrame | 예측 (P) 프레임의 간격을 설정한다.
get_PFramesPerKeyFrame | P 프레임의 간격을 취득한다.
put_Quality | 비디오 이미지 압축의 품질을 설정한다.
get_Quality | 현재의 이미지 품질의 설정을 취득한다.
put_WindowSize | 압력이 유지해야 하는 평균 데이터 레이트의 기준이 되는 프레임수를 설정한다.
get_WindowSize | 압력이 유지해야 하는 평균 데이터 레이트의 기준이 되는 프레임수를 취득한다.
GetInfo | 압력의 정보를 취득한다.
OverrideKeyFrame | 특정의 프레임을 키 프레임으로 한다.
OverrideFrameSize | 특정의 프레임의 데이터 레이트를 무효로 한다.

IAMVideoCompression::GetInfo

IAMVideoCompression 인터페이스

압력의 정보를 취득한다.

구문

HRESULT GetInfo(
    WCHAR *pszVersion,
    int *pcbVersion,
    LPWSTR pszDescription,
    int *pcbDescription,
    long *pDefaultKeyFrameRate,
    long *pDefaultPFramesPerKey,
    double *pDefaultQuality,
    long *pCapabilities
    ) PURE;

파라미터

pszVersion
[out] "Version 2.1. 0" 등의 버젼 캐릭터 라인에의 포인터.
pcbVersion
[in, out] 버젼 캐릭터 라인에 필요한 사이즈. 문자수는 아니고 Unicode™ 캐릭터 라인에서의 바이트수에의 포인터. 따라서, 그 캐릭터 라인을 보관 유지할 수 있는 문자수의 2 배가 아니면 안된다. 현재의 사이즈를 취득하는 경우는, 이 파라미터에 NULL 를 설정해 호출한다.
pszDescription
[out] "Awesome Video Compressor" 등의 설명문자열에의 포인터.
pcbDescription
[in, out] 설명문자열에 필요한 사이즈. 문자수는 아니고 Unicode™ 캐릭터 라인에서의 바이트수에의 포인터. 따라서, 그 캐릭터 라인을 보관 유지할 수 있는 문자수의 2 배가 아니면 안된다. 현재의 사이즈를 취득하는 경우는, 이 파라미터에 NULL 를 설정해 호출한다.
pDefaultKeyFrameRate
[out] 디폴트의 키 frame rate를 받기 위한 포인터.
pDefaultPFramesPerKey
[out] 키 프레임마다의 디폴트의 예측 (P) 프레임수를 받기 위한 포인터.
pDefaultQuality
[out] 디폴트의 품질을 받기 위한 포인터.
pCapabilities
[out] 압축기노우의 정보를 받기 위한 포인터. 이 압축기노우의 정보는,CompressionCaps 열거형 플래그의 편성이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMVideoCompression::get_KeyFrameRate

IAMVideoCompression 인터페이스

현재의 키 frame rate를 취득한다.

구문

get_KeyFrameRate(
    long *pKeyFrameRate
    ) PURE;

파라미터

pKeyFrameRate
[out] 압력의 현재의 키 frame rate에의 포인터. 부의 값은, 압력이 비디오 압력의 디폴트의 frame rate를 사용하고 있는 것을 나타낸다. 제로값은, 최초의 프레임만이 키 프레임인 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

압력이 이 메소드를 지원 하고 있을지 어떨지를 확인하려면 ,IAMVideoCompression::GetInfo 메소드의 pCapabilities 파라미터에 돌려주어지는 CompressionCaps_CanKeyFrame 플래그를 조사한다.

참조

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression::get_PFramesPerKeyFrame

IAMVideoCompression 인터페이스

예측 (P) 프레임의 간격을 취득한다.

구문

HRESULT get_PFramesPerKeyFrame(
    long *pPFramesPerKeyFrame
    ) PURE;

파라미터

pPFramesPerKeyFrame
[out] 키 프레임마다의 P 프레임의 수를 받기 위한 포인터. 부의 값은, 압력이 디폴트값을 사용하는 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. Video for Windows 의 캡춰 필터 (VFW 캡춰) 및 AVI 압축 필터 (AVI 압력)에서는, 현재 이 인터페이스가 지원되어 있지 않기 때문에,E_NOTIMPL 가 돌려주어진다.

주의

압력이 이 메소드를 지원 하고 있을지 어떨지를 확인하려면 ,IAMVideoCompression::GetInfo 메소드의 pCapabilities 파라미터에 돌려주어지는 CompressionCaps_CanBFrame 플래그를 조사한다.

각 프레임 타입의 사이의 관계의 예로서 10 프레임 마다 키 프레임이 한 번 발생해, 키 프레임 마다 3 개의 P 프레임이 있는 경우를 상정한다. 이러한 P 프레임은 키 프레임간에 등간격에 발생한다. 키 프레임과 P 프레임의 사이에 있는 것 외의 6 개의 프레임은 양방향 예측 (B) 프레임이다.

참조

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression::get_Quality

IAMVideoCompression 인터페이스

현재의 이미지 품질의 설정을 취득한다.

구문

HRESULT get_Quality(
    double *pQuality
    ) PURE;

파라미터

pQuality
[out] 현재의 품질의 설정에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

품질은, 0 에서 1 의 범위의 값이다. 1 은 최고 품질을 나타내, 0 은 최저 품질을 나타낸다. 부의 값은, 압력의 디폴트가 사용되고 있는 것을 나타낸다. 이 값은 압력에 의해 해석한다. 그 해석은 압력 마다 다르다. 압력이 특정의 데이터 레이트로 압축하고 있는 것은 아닌 경우, 이 값에 의해 이미지 사이즈 또는 품질이 대략적으로 결정된다.

압력이 이 메소드를 지원 하고 있을지 어떨지를 확인하려면 ,IAMVideoCompression::GetInfo 메소드의 pCapabilities 파라미터에 돌려주어지는 CompressionCaps_CanQuality 플래그를 조사한다.

고정 데이터 레이트로 압축하고 있는 경우, 품질값이 높으면 전데이터 레이트가 사용되는 것을 의미한다. 품질값이 낮으면 그 데이터 레이트보다 꽤 낮은 데이터 레이트를 사용할 수 있는 것을 의미한다.

IAMVideoCompression::get_WindowSize

IAMVideoCompression 인터페이스

압력이 유지해야 하는 평균 데이터 레이트의 기준이 되는 프레임수를 취득한다.

구문

HRESULT get_WindowSize(
    DWORDLONG *pWindowSize
    );

파라미터

pWindowSize
[out] 윈도우 사이즈를 받는 DWORDLONG 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IAMVideoCompression::put_WindowSize

IAMVideoCompression::OverrideFrameSize

IAMVideoCompression 인터페이스

프레임의 데이터 레이트를 무효로 한다.

구문

HRESULT OverrideFrameSize(
    long FrameNumber,
    long Size
    ) PURE;

파라미터

FrameNumber
[in] 사이즈를 변경하는 프레임의 번호.
Size
[in] 지정한 프레임에 대한 변경 후의 사이즈 (바이트 단위).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. Video for Windows 의 캡춰 필터 (VFW 캡춰) 및 AVI 압축 필터 (AVI 압력)에서는, 현재 이 인터페이스가 지원되어 있지 않기 때문에,E_NOTIMPL 가 돌려주어진다.

주의

압력이 이 메소드를 지원 하고 있을지 어떨지를 확인하려면 ,IAMVideoCompression::GetInfo 메소드의 pCapabilities 파라미터에 돌려주어지는 CompressionCaps_CanCrunch 플래그를 조사한다. 이 플래그는,dwBitRate 값을 AM_MEDIA_TYPE 의 VIDEOINFOHEADER 구조체로 설정할 수 있는 것을 나타내기 위해서(때문에) 설정되는 경우도 있다.

프레임 번호는, 스트리밍 후에 필터로부터 출력되는 프레임을 가리킨다. 예를 들어, 프레임 0 은, 이 핀이 전달하는 1 번째의 프레임을 나타낸다. 프레임 11 은 핀이 전달하는 12 번째의 프레임을 나타낸다. 이 메소드는, 사이즈 변경 대상의 프레임이 필터에 의해 전달되기 전에 호출하도록(듯이) 한다.

frame size를 무효로 하는 (프레임 "쿠란팅 ")와 본래 예정되어 있던 사이즈는 아니고 이 메소드로 지정된 바이트 또는 그것 이하로 하도록(듯이) 필터에 지시받는다.

IAMVideoCompression::OverrideKeyFrame

IAMVideoCompression 인터페이스

프레임을 키 프레임으로 한다.

구문

HRESULT OverrideKeyFrame(
    long FrameNumber
    ) PURE;

파라미터

FrameNumber
[in] 보통은 키 프레임이 아닌 경우에서도, 그래프의 실행시에 키 프레임으로 되는 프레임의 번호.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. Video for Windows 의 캡춰 필터 (VFW 캡춰) 및 AVI 압축 필터 (AVI 압력)에서는, 현재 이 인터페이스가 지원되어 있지 않기 때문에,E_NOTIMPL 가 돌려주어진다.

주의

압력은, 키 프레임을 생성 한 후에 그 카운트를 리셋 해, 다음에 키 프레임이 발생하는 장소를 결정할 수 있다. 예를 들어, 보통 키 프레임이 10 프레임 걸러서 발생 하면 한다. OverrideKeyFrame 를 사용해 프레임 5 를 키 프레임으로서 설정 하면, 압력은 다음의 키 프레임을 생성 할 때까지 이제(벌써) 10 프레임 기다릴 수가 있다.

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression 인터페이스

키 frame rate를 설정한다.

구문

HRESULT put_KeyFrameRate(
    long KeyFrameRate
    ) PURE;

파라미터

KeyFrameRate
[in] 설정하는 키 frame rate. 부의 값은 비디오 압력이 디폴트의 frame rate를 사용하는 것을 나타낸다. 제로값은 최초의 프레임만이 키 프레임인 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

압력이 이 메소드를 지원 하고 있을지 어떨지를 확인하려면 ,IAMVideoCompression::GetInfo 메소드의 pCapabilities 파라미터에 돌려주어지는 CompressionCaps_CanKeyFrame 플래그를 조사한다.

IAMVideoCompression::put_PFramesPerKeyFrame

IAMVideoCompression 인터페이스

예측 (P) 프레임의 간격을 설정한다.

구문

HRESULT put_PFramesPerKeyFrame(
    long PFramesPerKeyFrame
    ) PURE;

파라미터

PFramesPerKeyFrame
[in] 설정하는 P 프레임의 간격. 부의 값은 비디오 압력이 디폴트의 frame rate를 사용하는 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. Video for Windows 의 캡춰 필터 (VFW 캡춰) 및 AVI 압축 필터 (AVI 압력)에서는, 현재 이 인터페이스가 지원되어 있지 않기 때문에,E_NOTIMPL 가 돌려주어진다.

주의

압력이 이 메소드를 지원 하고 있을지 어떨지를 확인하려면 ,IAMVideoCompression::GetInfo 메소드의 pCapabilities 파라미터에 돌려주어지는 CompressionCaps_CanBFrame 플래그를 조사한다.

각 프레임 타입의 사이의 관계의 예로서 10 프레임 마다 키 프레임이 한 번 발생해, 키 프레임 마다 3 개의 P 프레임이 있는 경우를 상정한다. 이러한 P 프레임은 키 프레임간에 등간격에 발생한다. 키 프레임과 P 프레임의 사이에 있는 것 외의 6 개의 프레임은 양방향 예측 (B) 프레임이다.

IAMVideoCompression::put_Quality

IAMVideoCompression 인터페이스

비디오 이미지의 품질을 설정한다.

구문

HRESULT put_Quality(
    double Quality
    ) PURE;

파라미터

Quality
[in] 설정하는 품질.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

품질은 0 으로 1 을 포함한 0 ~ 1 의 범위의 값이다. 1 은 최고 품질을 나타내, 0 은 최저 품질을 나타낸다. 부의 값은, 압력의 디폴트가 사용되는 것을 나타낸다. 이 값은 압력 (CODEC )에 의해 해석된다. 그 해석은 CODEC 마다 다르다. 압력이 특정의 데이터 레이트로 압축하고 있는 것은 아닌 경우, 이 값에 의해 이미지 사이즈 또는 품질이 대략적으로 결정된다.

압력이 이 메소드를 지원 하고 있을지 어떨지를 확인하려면 ,IAMVideoCompression::GetInfo 메소드의 pCapabilities 파라미터에 돌려주어지는 CompressionCaps_CanQuality 플래그를 조사한다.

고정 데이터 레이트로 압축하고 있는 경우, 품질값이 높으면 전데이터 레이트가 사용되는 것을 의미한다. 품질값이 낮으면 그 데이터 레이트보다 꽤 낮은 데이터 레이트를 사용할 수 있는 것을 의미한다.

IAMVideoCompression::put_WindowSize

IAMVideoCompression 인터페이스

압력이 유지해야 하는 평균 데이터 레이트의 기준이 되는 프레임수를 설정한다.

구문

HRESULT put_WindowSize(
    DWORDLONG WindowSize
    );

파라미터

WindowSize
[in] 윈도우의 사이즈 (프레임수). 그 평균 사이즈는, 압력이 제공하도록(듯이) 요구되고 있는 데이터 레이트를 넘을 수 없다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

사이즈 n 의 윈도우의 경우, 연속한 n 개의 프레임의 평균 frame size는, 그 스트림의 지정된 데이터 레이트를 넘지 않는다. 다만, 각각의 프레임은 그것보다 커도 작아도 상관없다. 예를 들어, 매초 10 프레임 (fps)의 무비에 대해서 매초 100 킬로바이트 (KB)의 데이터 레이트를 설정했을 경우, 보통은, 각 프레임이 10 KB 이하가 아니면 안되는 것을 의미한다. 그러나, 윈도우 사이즈에 n 를 설정하는 것으로, 이것들 n 개의 프레임의 평균의 길이가 10 KB 이하인 한, 각각의 프레임의 크기는 문제가 아닌 것을 지정하게 된다. 예를 들어, 프레임이 10 KB 보다 작아도, 10 KB 보다 커도, 평균이 10 KB 이하 이면 상관없다.

참조

IAMVideoCompression::get_WindowSize


IAMVideoControl 인터페이스

IAMVideoControl 인터페이스에 의해, 수평 방향 및 수직 방향에의 픽쳐의 후립핑, 외부 방아쇠 (유저가 누르는 카메라의 버튼등)의 캡춰를 가능하게하기 위한 스트림의 설정, 소프트웨어에서의 외부 방아쇠의 시뮬레이션, 및 이용 가능한 frame rate의 리스트의 취득을 실시할 수가 있다.

이 인터페이스는,VideoControlFlags 열거형의 비디오 제어 플래그를 사용한다.

필터에 의한 비디오 이미지의 제어 또는 frame rate의 일람의 취득이 필요한 경우에, 이 인터페이스를 이행 한다.

또, 후립핑 및 외부 방아쇠의 캡춰가 가능한 하드웨어상에서 어플리케이션을 실행하는 경우에 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMVideoControl 메소드 | 설명
GetCaps | 기초가 되는 하드웨어의 능력을 취득한다.
SetMode | 조작의 비디오 제어 모드를 설정한다.
GetMode | 조작의 비디오 제어 모드를 취득한다.
GetCurrentActualFrameRate | 디바이스가 스트리밍 하고 있는 실제의 frame rate를 취득한다. 이 메소드는, USB (Universal Serial Bus), IEEE 1394 시리얼 통신규격 대응 카메라 등, 이용 가능한 대역폭에 의해 최대 frame rate가 제한되는 디바이스와 함께 사용한다. 이 메소드는, 비디오 스트리밍중에게만 사용할 수 있다.
GetMaxAvailableFrameRate | USB, IEEE 1394 대응 카메라 디바이스 등, 이용 가능한 대역폭에 의해 최대 frame rate가 제한되는 접속의 버스 대역폭의 사용율에 근거해, 현재 이용 가능한 최대 frame rate를 취득한다.
GetFrameRateList | 이용 가능한 frame rate의 리스트를 취득한다.

IAMVideoControl::GetCaps

IAMVideoControl 인터페이스

기초가 되는 하드웨어의 능력을 취득한다.

구문

HRESULT GetCaps (

  IPin *pPin,

  long *pCapsFlags

  );

파라미터

pPin
[in] 능력의 조회 대상이 되는 핀에의 포인터.
pCapsFlags
[out] VideoControlFlags 열거형의 플래그의 편성을 나타내는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

취득할 수 있는 능력에는, 수평 방향에의 픽쳐의 후립핑, 수직 방향에의 픽쳐의 후립핑, 외부 방아쇠의 유효화, 및 외부 방아쇠의 시뮬레이션 가운데, 1 개 또는 복수가 포함된다.

IAMVideoControl::GetCurrentActualFrameRate

IAMVideoControl 인터페이스

실제의 frame rate를 취득한다. frame rate는 100 나노초단위의 프레임 시간폭으로서 나타내진다. USB (Universal Serial Bus) 및 IEEE 1394 대응 카메라의 경우, 이용 가능한 대역폭에 의해, 요구보다 frame rate가 낮아지는 경우가 있다. 이 메소드는, 비디오 스트리밍중에게만 사용할 수 있다.

구문

HRESULT GetCurrentActualFrameRate (

  IPin *pPin,

  LONGLONG *ActualFrameRate

  );

파라미터

pPin
[in] frame rate의 취득 대상이 되는 핀에의 포인터.
ActualFrameRate
[out] 100 나노초단위의 프레임 시간폭으로 나타내지는 frame rate에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMVideoControl::GetFrameRateList

IAMVideoControl 인터페이스

이용 가능한 frame rate의 리스트를 취득한다.

구문

HRESULT GetFrameRateList (

  IPin *pPin,

  long iIndex,

  SIZE Dimensions,

  long *ListSize,

  LONGLONG **FrameRates

  );

파라미터

pPin
[in] frame rate의 리스트의 조회 대상이 되는 핀에의 포인터.
iIndex
[in] frame rate의 조회 대상이 되는 포맷의 인덱스. 이 인덱스는, 포맷이 IAMStreamConfig::GetStreamCaps 로 열거되는 순서에 대응하고 있다. 값의 범위는, 0 으로부터 IAMStreamConfig::GetNumberOfCapabilities 메소드가 돌려주는 지원 되고 있는 VIDEO_STREAM_CONFIG_CAPS 구조체의 수로부터 1 을 감산한 값까지이다.
Dimensions
[in] 프레임 이미지의 픽셀 단위의 사이즈 (폭과 높이).
ListSize
[out] frame rate의 리스트내의 요소수에의 포인터.
FrameRates
[out] 100 나노초단위의 frame rate의 배열에의 포인터의 주소. ListSize 만을 필요로 하는 경우는, 이 데이터는 NULL 가 될 가능성이 있다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

호출원래는,CoTaskMemFree 를 호출해 메모리를 해방할 필요가 있다.

IAMVideoControl::GetMaxAvailableFrameRate

IAMVideoControl 인터페이스

USB, IEEE 1394 대응 카메라 디바이스 등, 이용 가능한 대역폭에 의해 최대 frame rate가 제한되는 접속에 대한 버스 대역폭의 사용율에 근거해, 현재 이용 가능한 최대 frame rate를 취득한다.

구문

HRESULT GetMaxAvailableFrameRate(

  IPin *pPin,

  long iIndex,

  SIZE Dimensions,

  LONGLONG *MaxAvailableFrameRate

  );

파라미터

pPin
[in] 최대 frame rate의 취득 대상이 되는 핀에의 포인터.
iIndex
[in] 최대 frame rate를 조회 대상이 되는 포맷의 인덱스. 이 인덱스는, 포맷이 IAMStreamConfig::GetStreamCaps 로 열거되고 있는 순서에 대응하고 있다. 값의 범위는, 0 으로부터 IAMStreamConfig::GetNumberOfCapabilities 메소드가 돌려주는 지원 되고 있는 VIDEO_STREAM_CONFIG_CAPS 구조체의 수로부터 1 을 감산한 값까지이다.
Dimensions
[in] 프레임 이미지의 픽셀 단위의 사이즈 (폭과 높이).
MaxAvailableFrameRate
[out] 이용 가능한 최대 frame rate에의 포인터. frame rate는, 100 나노초단위의 프레임 시간폭으로서 나타내진다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IAMVideoControl::GetMode

IAMVideoControl 인터페이스

조작의 비디오 제어 모드를 취득한다.

구문

HRESULT GetMode (

  IPin *pPin,

  long *Mode

  );

파라미터

pPin
[in] 비디오 제어 모드의 취득 대상이 되는 핀에의 포인터.
Mode
[out] 비디오 제어 모드를 지정하는 VideoControlFlags 열거형의 플래그의 편성을 나타내는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

취득할 수 있는 조작 모드에는, 수평 방향에의 픽쳐의 후립핑, 수직 방향에의 픽쳐의 후립핑, 외부 방아쇠의 유효화, 및 외부 방아쇠의 시뮬레이션 가운데, 1 개 또는 복수가 포함된다.

IAMVideoControl::SetMode

IAMVideoControl 인터페이스

조작의 비디오 제어 모드를 설정한다.

구문

HRESULT SetMode (

  IPin *pPin,

  long Mode

  );

파라미터

pPin
[in] 비디오 제어 모드의 설정 대상이 되는 핀에의 포인터.
Mode
[in] 비디오 제어 모드를 설정하는 VideoControlFlags 열거형의 플래그의 편성을 지정하는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

취득할 수 있는 조작 모드에는, 수평 방향에의 픽쳐의 후립핑, 수직 방향에의 픽쳐의 후립핑, 외부 방아쇠의 유효화, 및 외부 방아쇠의 시뮬레이션 가운데, 1 개 또는 복수가 포함된다.


IAMVideoDecimationProperties 인터페이스

IAMVideoDecimationProperties 인터페이스에 의해, 어플리케이션은 비디오 데시 메이션의 발생 장소를 제어할 수 있다. 이 인터페이스는오버레이 믹서 필터로 이행 된다.

비디오 윈도우가 표시중의 비디오의 네이티브 사이즈보다 작은 경우, 비디오 렌더러는 수신 비디오를데시 메이트할 필요가 있다. 즉, 비디오를 작은 사이즈에 축소할 필요가 있다. 데시 메이션은, 다음의 몇개의 장소에서 실행할 수 있다.

  • VGA 팁 위에의 오버레이 하드웨어
  • 비디오 포토에 편입의 스칼라 (접속에 비디오 포토를 사용하는 경우)
  • 비디오를 렌더러에 공급하는 디코더

어플리케이션은 이 인터페이스로 메소드를 호출해, 특정의 데시 메이션 방법을 선택해, 퍼포먼스를 최적화할 수 있다. 다만, 대부분의 어플리케이션의 경우 이 인터페이스를 사용할 것은 없다. 어플리케이션이 특정의 하드웨어를 지원 하도록(듯이) 설계되어 있지 않은 한, 오버레이 믹서의 디폴트의 데시 메이션 동작을 변경할 필요는 없다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMVideoDecimationProperties 메소드 | 설명
QueryDecimationUsage | 현재의 데시 메이션 방법을 취득한다.
SetDecimationUsage | 데시 메이션 방법을 설정한다.

IAMVideoDecimationProperties::QueryDecimationUsage

IAMVideoDecimationProperties 인터페이스

현재의 데시 메이션 방법을 취득한다.

구문

HRESULT QueryDecimationUsage(
    DECIMATION_USAGE *lpUsage
);

파라미터

lpUsage
[out] 데시 메이션의 설정을 취득하는 DECIMATION_USAGE 열거형의 변수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. Microsoft® DirectShow® 의 이행에서는, 성공했을 경우는 S_OK, 그 이외의 경우는 E_FAIL 또는 다른 에러 코드를 돌려준다.

IAMVideoDecimationProperties::SetDecimationUsage

IAMVideoDecimationProperties 인터페이스

데시 메이션 방법을 설정한다.

구문

HRESULT SetDecimationUsage(
    DECIMATION_USAGE Usage
);

파라미터

Usage
[in] 데시 메이션 방법을 지정하는 DECIMATION_USAGE 열거형의 멤버.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. DirectShow 의 이행은, 성공했을 경우는 S_OK 를 돌려주어, 그 이외의 경우는 E_INVALIDARG 를 돌려준다.


IAMVideoProcAmp 인터페이스

IAMVideoProcAmp 인터페이스는,WDM 비디오 캡춰 필터로 이행 된다. 이 인터페이스에 의해, 어플리케이션은 휘도, 콘트라스트,색상,채도, 감마, 선명도 등, 수신하는 비디오 신호의 품질을 조정할 수 있다. 아날로그 도메인과 디지털 도메인의 어디에서 조정했는지를 관계없이, 이러한 설정에 대해서 동일한 범위가 정의된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMVideoProcAmp methods | 설명
GetRange | 설정 프로퍼티의 최소 값, 최대치, 및 디폴트값을 취득한다.
Set | 지정된 프로퍼티의 비디오 품질을 설정한다.
Get | 지정된 프로퍼티의 비디오 품질을 취득한다.

IAMVideoProcAmp::Get

IAMVideoProcAmp 인터페이스

지정된 프로퍼티의 비디오 품질을 취득한다.

구문

HRESULT Get(

  long Property,

  long *lValue,

  long *Flags );

파라미터

Property
[in] 설정의 취득 대상이 되는 특정의 프로퍼티. VideoProcAmpProperty 열거형의 멤버를 지정한다.
lValue
[out] 프로퍼티의 현재의 값에의 포인터.
Flags
[out] VideoProcAmpFlags 열거형의 멤버에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 에러 없음.

IAMVideoProcAmp::GetRange

IAMVideoProcAmp 인터페이스

설정 프로퍼티의 최소 값, 최대치, 및 디폴트값을 취득한다.

구문

HRESULT GetRange(

  long Property,

  long *pMin,

  long *pMax,

  long *pSteppingDelta,

  long *pDefault,

  long *pCapsFlags );

파라미터

Property
[in] 범위의 확인 대상이 되는 특정의 프로퍼티. VideoProcAmpProperty 열거형의 멤버를 지정한다.
pMin
[out] 설정 범위의 최소 값에의 포인터.
pMax
[out] 설정 범위의 최대치에의 포인터.
pSteppingDelta
[out] 스텝 사이즈에의 포인터.
pDefault
[out] 디폴트값에의 포인터.
pCapsFlags
[out] VideoProcAmpFlags 열거형의 멤버에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 에러 없음.

IAMVideoProcAmp::Set

IAMVideoProcAmp 인터페이스

지정된 프로퍼티의 비디오 품질을 설정한다.

구문

HRESULT Set(
  long Property,
  long lValue,
  long Flags );

파라미터

Property
[in] 설정 대상이 되는 특정의 프로퍼티. VideoProcAmpProperty 열거형의 멤버를 지정한다.
lValue
[in] 프로퍼티의 설정을 나타내는 값.
Flags
[in] VideoProcAmpFlags 열거형의 멤버.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 에러 없음.


IAsyncReader 인터페이스

IAsyncReader 인터페이스는 비동기 파일 소스 필터의 출력 핀에 의해 이행 된다. 이 인터페이스에 의해, 미디어 스트림내가 다른 위치로부터 복수의 독해를 오버랩 시킬 수가 있다. 이 인터페이스의 메소드는 다운 스트림 필터의 입력 핀에 의해 불려 간다. 어플리케이션으로 이 인터페이스를 사용할 것은 없다.

필터 개발자: 필터가 소스로부터 MEDIATYPE_Stream 미디어 타입의 데이터를 읽어내는 경우는, 이 인터페이스를 핀으로 이행 한다. 접속중에,IAsyncReader 를 지원 하는출력 핀은, 그 출력 핀의 QueryInterface 메소드가 불려 가 IAsyncReader 인터페이스가 요구되었는지 어떻게를 조사할 필요가 있다. 불려 가지 않으면 접속중에 사용하는 것 외의전송을 확립하지 않는 한, 출력 핀이 접속에 실패한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAsyncReader 메소드 | 설명
RequestAllocator | 실제로 사용되는 allocater를 취득한다.
Request | 데이터 요구를 큐에 넣는다.
WaitForNext | 다음의 샘플이 완료하는지, 또는 타임 아웃이 발생할 때까지 블록 한다.
SyncReadAligned | 위치 맞춤 된 동기 독해를 실행한다.
SyncRead | 동기 독해를 실행한다.
Length | 스트림의 토탈의 길이, 및 현재 이용 가능한 길이를 취득한다.
BeginFlush | 모든 미처리의 독해가 돌려주어진다.
EndFlush | flushing 조작을 완료한다.

IAsyncReader::BeginFlush

IAsyncReader 인터페이스

flushing 조작을 시작 한다.

구문

HRESULT BeginFlush(void);

반환값

성공했을 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

모든 미처리의 독해가 돌려주어진다. 이것에 실패 코드 (VFW_E_TIMEOUT )가 부수 하는 경우도 있다. 이 조작은, 미처리의 독해를 캔슬하는 것을 나타낸다. IAsyncReader::BeginFlush 호출과 IAsyncReader::EndFlush 호출동안에,IAsyncReader::Request 호출이 실패해, 즉석에서 IAsyncReader::WaitForNext 호출이 반드시 완료한다.

IAsyncReader::EndFlush

IAsyncReader 인터페이스

flushing 조작을 완료한다.

구문

HRESULT EndFlush(void);

반환값

성공했을 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

IAsyncReader::BeginFlush 호출과 IAsyncReader::EndFlush 호출동안에,IAsyncReader::Request 호출이 실패해, 즉석에서 IAsyncReader::WaitForNext 호출이 반드시 완료한다. 이 메소드를 호출해, 소스의 thread가 IAsyncReader::WaitForNext 메소드내에서 다시 대기할 수 있는 도록 한다.

IAsyncReader::Length

IAsyncReader 인터페이스

스트림의 토탈의 길이, 및 현재 이용 가능한 길이를 취득한다.

구문

HRESULT Length(

  LONGLONG *pTotal,

  LONGLONG *pAvailable

  );

파라미터

pTotal
할당하고 끝난 토탈의 길이에의 포인터.
pAvailable
이용 가능한 길이에의 포인터.

반환값

성공했을 경우는 S_OK, 파일이 열리지 않은 경우는 E_UNEXPECTED 를 돌려준다.

주의

독해가 토탈의 길이 이내여도 이용 가능한 길이를 넘는 경우, 보통 그 조작은 성공하지만, 장시간 블록 하는 경우가 있다.

IAsyncReader::Request

IAsyncReader 인터페이스

데이터 요구를 큐에 넣는다.

구문

HRESULT Request(

  IMediaSample *pSample,

  DWORD dwUser

  );

파라미터

pSample
요구되고 있는 미디어 샘플에의 포인터.
dwUser
[in] 유저 문맥.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 Microsoft® DirectShow® 의 이행에서의 반환값은, 다음과 같다.
VFW_E_BADALIGN | 무효인 alignment가 지정되었다.
VFW_E_MEDIA_TIME_NOT_SET | 시간이 설정되어 있지 않다.
HRESULT_FROM_WIN32 | 파일의 말미를 넘는 데이터가 요구되고 있다.
NOERROR | 에러 없음.
S_OK | 성공.

주의

미디어 샘플의 시작 타임과 종료 타임에는, 요구되는 절대 바이트 위치가 포함된다. 다만, 시작 위치는 포함되지만, 정지 위치는 포함되지 않는다. 이 메소드는, 합의된 allocater로부터 샘플이 취득되지 않는 경우, 혹은 시작 위치 또는 정지 위치가 합의된 alignment에 일치하지 않는 경우에 실패하는 일이 있다. IAsyncReader::WaitForNext 로부터 돌아오기까지, 소스 핀의 allocater로부터 할당할 수 있었던 샘플에 의해,IMediaSample::GetPointer 가 실패하는 경우가 있다.

정지 위치는 위치 맞춤 되지 않으면 안 된다. 다만, 그 정지 위치가 시간폭을 넘고 있는 경우가 있다. 그 경우는, 완료시에 정지 위치는 위치 맞춤되어 있지 않은 실제의 데이터에 정정된다.

dwUser 파라미터는,IAsyncReader::WaitForNext 메소드로부터 돌려주어지는 샘플을 식별하기 위해서, 호출원이 사용한다. 이것은 IAsyncReader 내에서는 무의미하지만, 샘플 정보를 개별적으로 추적하는 경우에 사용할 수 있다.

IAsyncReader::RequestAllocator

IAsyncReader 인터페이스

실제로 사용되는 allocater를 취득한다.

구문

HRESULT RequestAllocator(

  IMemAllocator *pPreferred,

  ALLOCATOR_PROPERTIES *pProps,

  IMemAllocator **ppActual

  );

파라미터

pPreferred
[in] 우선하는 allocater에의 포인터.
pProps
[in] 우선하는 allocater의 프로퍼티 (사이즈, 카운트, 및 alignment)에의 포인터.
ppActual
[out] 실제로 사용되는 allocater에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
E_FAIL | allocater의 초기화가 실패했다.
VFW_E_BADALIGN | 무효인 alignment가 지정되었다.
S_OK | allocater가 돌려주어졌다.

주의

우선하는 allocater 및 우선하는 allocater의 프로퍼티를 건네줄 필요가 있다. 이 메소드는 실제로 사용되는 allocater를 돌려준다.

선택되고 있는 alignment 및 프레픽스를 조사하려면 , 돌려주어진 allocater에 대해서 IMemAllocator::GetProperties 를 호출한다. 이 allocater에 대해서 위탁 및 데코밋트를 지시하는 것은, 비동기 리더는 아니고, 컨슈머(consumer)이다. IAsyncReader::Request 를 호출하기 전에, 이 메소드를 호출할 필요가 있다.

IAsyncReader::SyncRead

IAsyncReader 인터페이스

동기 독해를 실행한다.

구문

HRESULT SyncRead(

  LONGLONG llPosition,

  LONG lLength,

  BYTE *pBuffer

  );

파라미터

llPosition
[in] 절대 파일 위치.
lLength
[in] 필요한 바이트수.
pBuffer
[out] 데이터가 기입해지고 있는 장소에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
VFW_E_BADALIGN | 무효인 alignment가 지정되었다.
HRESULT_FROM_WIN32 | Microsoft® Win32® 에러.
S_FALSE | 사이즈가 변경되었다 (아마 파일의 말미를 넘었기 때문에).
S_OK | 성공.

주의

SyncRead 메소드는 실행 상태 뿐만이 아니라 정지상태태에서도 동작한다. 독해는 반드시 위치 맞춤 되고 있을 필요는 없다. 독해가 실제의 토탈의 길이를 넘고 있으면(자), 이 메소드는 실패한다.

IAsyncReader::SyncReadAligned

IAsyncReader 인터페이스

데이터의 동기 독해를 실행한다.

구문

HRESULT SyncReadAligned(

  IMediaSample *pSample

  );

파라미터

pSample
읽어들이는 샘플에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
VFW_E_BADALIGN | 무효인 alignment가 지정되었다.
HRESULT_FROM_WIN32 | Win32 에러.
S_FALSE | 사이즈가 변경되었다 (아마 파일의 말미를 넘었기 때문에).
S_OK | 성공.

주의

건네받는 샘플은, 합의된 allocater로부터 취득되어 있지 않으면 안 된다. 시작 위치와 정지 위치는,IAsyncReader::Request /IAsyncReader::WaitForNext 페어에 맞추어 위치 맞춤 되지 않으면 안 되지만,소스 필터 위에의 thread의 필요성은 없어진다.

IAsyncReader::WaitForNext

IAsyncReader 인터페이스

IAsyncReader::Request 를 개입시켜 요구된 다음의 독해가 완료할 때까지, 또는 타임 아웃이 발생할 때까지 블록 한다.

구문

HRESULT WaitForNext(

  DWORD dwTimeout,

  IMediaSample **ppSample,

  DWORD *pdwUser

  );

파라미터

dwTimeout
[in] 타임 아웃 (밀리 세컨드 단위). 제로 또는 INFINITE 도 지정할 수 있다.
ppSample
[out] 완료한 샘플에의 포인터의 주소.
pdwUser
[out] 유저 문맥에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
VFW_E_TIMEOUT | 타임 아웃에 이르렀다.
VFW_E_WRONG_STATE | 필터가 부정한 상태에 있기 (위해)때문에, 조작을 실행할 수 없었다.
E_FAIL | 실패.
S_OK | 성공.

주의

샘플이 차례대로 돌려주어지지 않은 경우가 있다. 하등의 독해 에러가 있는 경우, 소스 필터에 의한 통지가 이미 완료하고 있어,HRESULT 가 에러가 된다. ppSample 가 NULL 는 아니면, 요구는 돌려주어진 결과 코드로 완료하고 있다.

pdwUser 파라미터는, 돌려주어진 샘플에 대응하는 호출원의 문맥 DWORD 를 돌려준다.


IBaseFilter 인터페이스

필터를 제어하는 메소드를 제공한다. 모든 Microsoft® DirectShow® 필터는 이 인터페이스를 공개한다. 이 인터페이스는 IMediaFilter 인터페이스로부터 파생해,IMediaFilter 필터를 통해 IPersist 인터페이스를 계승한다.

필터 그래프 매니저는 이 인터페이스를 사용해 필터를 제어한다. 어플리케이션과 다른 필터는 이 인터페이스를 사용해 핀을 열거해, 필터 정보를 쿼리 할 수가 있다. 어플리케이션은 필터 상태를 변경할 때에 그것을 사용해서는 안된다. 그렇지 않고, 필터 그래프 매니저의 IMediaControl 인터페이스를 호출하는 것.

필터 개발자에게 : 모든 DirectShow 필터로 이 인터페이스를 이행 하는 것. CBaseFilter base class는 이 인터페이스를 이행 한다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaFilter 메소드 | 설명
Stop | 필터를 정지한다.
Pause | 필터를 포즈 한다.
Run | 필터를 실행한다.
GetState | 필터 상태 (실행, 정지, 포즈)를 취득한다.
SetSyncSource | 필터의기준 클락을 설정한다.
GetSyncSource | 필터가 사용하고 있는 기준 클락을 취득한다.
IBaseFilter 메소드 | 설명
EnumPins | 이 필터의 핀을 열거한다.
FindPin | 지정한 식별자로 핀을 취득한다.
QueryFilterInfo | 필터에 대한 정보를 취득한다.
JoinFilterGraph | 필터 그래프에 참가한, 혹은 필터 그래프로부터 멀어진 것을 필터에 통지한다.
QueryVendorInfo | 벤더 정보를 가지는 캐릭터 라인을 취득한다.

IBaseFilter::EnumPins

IBaseFilter 인터페이스

이 필터의 핀을 열거한다.

구문

HRESULT EnumPins(
    IEnumPins **ppEnum
);

파라미터

ppEnum
[out] IEnumPins 인터페이스에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공
E_OUTOFMEMORY | 메모리 부족
E_POINTER | NULL 포인터 인수

주의

이 메소드는 IEnumPins 인터페이스를 지원 하는 열거자를 돌려주는, 그것은 표준 COM 열거자와 같게 동작한다. 상세한 것에 대하여는, 「핀의 열거」를 참조할것.

메소드가 성공하면(자),IEnumPins 인터페이스에 참조 카운트가 남는다. 인터페이스의 해방시에 주의가 필요.

IBaseFilter::FindPin

IBaseFilter 인터페이스

지정한 식별자로 핀을 취득한다.

구문

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

파라미터

Id
[in] 정수에의 포인터, 핀을 나타내는 NULL 로 끝나는 Unicode™ 캐릭터 라인. IPin::QueryId 를 호출해 핀의 식별자를 취득하는 것.
ppPin
[out] 핀의 IPin 인터페이스에의 포인터를 받는 변수의 주소. 메소드가 실패 하면,*ppPin 는 NULL 에 세트 된다.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_NOT_FOUND | 이 식별자에서는 핀을 찾아낼 수 없었다.

주의

이 메소드는 그래프의 영속성을 지원 한다. IPin::QueryId 메소드를 사용해 핀 상태를 세이브해, 이 메소드를 사용해 상태를 restore 하는 것. 핀의 식별자 캐릭터 라인은 필터 이행에 의해 정의된다. 식별자는 필터내에서 독특한 것이 아니면 안된다.

메소드가 성공하면(자), 되돌아 오는 IPin 인터페이스에는 참조 카운트가 남는다. 해방시에는 주의가 필요.

IBaseFilter::JoinFilterGraph

IBaseFilter 인터페이스

필터 그래프에 참가한, 혹은 필터 그래프로부터 멀어진 것을 필터에 통지한다.

구문

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph,
    LPCWSTR pName
);

파라미터

pGraph
[in] 필터 그래프 매니저의 IFilterGraph 인터페이스에의 포인터, 혹은 필터가 그래프를 떨어졌다면 NULL.
pName
[in, string] 필터의 이름을 나타내는 NULL 로 끝나는 Unicode™ 캐릭터 라인에의 포인터.

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

필터 그래프 매니저가 있는 필터를 필터 그래프에 추가 하면 와, 그것은 자기 자신의 포인터로 이 메소드를 호출한다. 그래프로부터 필터를 삭제 하면 와, 이 메소드를 NULL 포인터로 호출한다.

어플리케이션은 이 메소드를 결코 호출해서는 안 된다. 필터를 그래프에 추가하려면 , 필터 그래프 매니저로 IFilterGraph::AddFilter 를 호출하는 것.

필터는 IFilterGraph 인터페이스 포인터를 보존하므로, 이벤트 통지를 보낼 수가 있다. 그러나 이 인터페이스에의 참조 카운트를 추가해서는 안 된다. 그렇다면 참조화운과의 반복을 만드는 일이 된다, 왜냐하면 필터 그래프 매니저는 필터의 참조 카운트를 보관 유지하고 있기 때문이다. 참조의 반복에 의해 인터페이스는 올바르게 해방할 수 없게 된다. 필터 그래프 매니저가 필터에 그래프로부터 삭제된 것을 통지할 때까지는,IFilterGraph 인터페이스는 유효성이 보증된다.

pName 파라미터에게 건네지는 이름은 QueryFilterInfo 메소드를 호출하는 것으로 얻을 수 있다.

IBaseFilter::QueryFilterInfo

IBaseFilter 인터페이스

필터에 대한 정보를 취득한다.

구문

HRESULT QueryFilterInfo(
    FILTER_INFO *pInfo
);

파라미터

pInfo
[out] FILTER_INFO 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공
E_POINTER | NULL 포인터 인수

주의

이 메소드는 FILTER_INFO 구조체에 필터 정보를 기입한다. 돌아갔을 때, FILTER_INFO 구조체의 pGraph 멤버가 NULL 는 아니면,IFilterGraph 인터페이스에는 참조 카운트가 남는다. 해방시에는 주의가 필요.

IBaseFilter::QueryVendorInfo

IBaseFilter 인터페이스

벤더 정보를 가지는 캐릭터 라인을 취득한다.

구문

HRESULT QueryVendorInfo(
    LPWSTR *pVendorInfo
);

파라미터

pVendorInfo
[out] 벤더 정보가 들어가는 와이드 캐릭터 캐릭터 라인에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 다음 표에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는 옵션이다. 필터는 그 지원이 요구되지 않는다.

메소드가 지원 되고 있다면, 그것은 CoTaskMemAlloc 함수를 사용해 캐릭터 라인용의 메모리를 할당한다. 메모리를 해방하려면 CoTaskMemFree 함수를 호출하는 것.


IBasicAudio 인터페이스

IBasicAudio 오토메이션 인터페이스는,오디오 렌더링 필터 및디폴트 DirectSound 디바이스 필터로 이행 되지만,PID 에 의해 필터 그래프 매니저를 개입시켜 공개된다. 어플리케이션은, 항상 필터 그래프 매니저로부터 이 인터페이스를 취득할 필요가 있다. 이 인터페이스를 사용 하면, C++ 및 Microsoft® Visual Basic® 어플리케이션은 오디오 스트림의 기본 볼륨 및 밸런스의 프로퍼티를 제어할 수 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IBasicAudio methods | 설명
put_Volume | 오디오 신호의 볼륨 (진폭)을 설정한다.
get_Volume | 오디오 신호의 볼륨 (진폭)을 취득한다.
put_Balance | 오디오 신호의 밸런스를 설정한다.
get_Balance | 오디오 신호의 밸런스를 취득한다.

IBasicAudio::get_Balance

IBasicAudio 인터페이스

오디오 신호의 밸런스를 취득한다.

구문

HRESULT get_Balance(

  long *plBalance

  );

파라미터

plBalance
[out] Balance 프로퍼티의 반환값에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

Balance 프로퍼티의 값의 범위는, –10, 000 에서 10,000 까지이다. 값 –10, 000 은 오른쪽 스피커가 무효로, 왼쪽 스피커만이 오디오 신호를 받고 있는 것을 나타낸다. 값 0 은 양쪽 모두의 스피커가 동등의 오디오 신호를 받고 있는 것을 나타낸다. 값 10,000 은 왼쪽 스피커가 무효로, 오른쪽 스피커만이 오디오 신호를 받고 있는 것을 나타낸다.

Volume 프로퍼티와 같게,. 01 데시벨 (dB) 단위로 나타내진다 (plBalance 가 정의 값인 경우는, –1 배). 예를 들어, 값 1000 은 오른쪽 채널이 –10 dB로, 왼쪽 채널이 –90 dB 인 것을 나타낸다.

IBasicAudio::get_Volume

IBasicAudio 인터페이스

오디오 신호의 볼륨 (진폭)을 취득한다.

구문

HRESULT get_Volume(

  long *plVolume

  );

파라미터

plVolume
[out] Volume 프로퍼티의 반환값에의 포인터. 100 으로 나눗셈 되어, 데시벨값에 환산된다 (예를 들어, –10, 000 = –100 dB).

반환값

HRESULT 값을 돌려준다.

주의

IBasicAudio::put_Balance

IBasicAudio 인터페이스

오디오 신호의 밸런스를 설정한다.

구문

HRESULT put_Balance(
  long lBalance
  );

파라미터

lBalance
[in] Balance 프로퍼티로 설정하는 값. 유효한 입력 범위는, –10, 000 에서 10,000 까지. 값 0 은 밸런스가 한가운데로 설정된다. 즉, 좌우의 스피커에 같은 진폭의 오디오 신호가 보내진다.

반환값

HRESULT 값을 돌려준다. 값이 유효한 입력 범위외인 경우는 E_INVALIDARG 가 돌려주어져 기초가 되는 디바이스가 에러를 돌려주었을 경우는 E_FAIL 가 돌려주어진다.

주의

Volume 프로퍼티와 같게,. 01 데시벨 (dB) 단위로 나타내진다 (plBalance 가 정의 값인 경우는, –1 배). 예를 들어, 값 1000 은 오른쪽 채널이 –10 dB로, 왼쪽 채널이 –90 dB 인 것을 나타낸다.

IBasicAudio::put_Volume

IBasicAudio 인터페이스

오디오 신호의 볼륨 (진폭)을 설정한다.

구문

HRESULT put_Volume(
  long lVolume
  );

파라미터

lVolume
[in] Volume 프로퍼티로 설정하는 값. 유효한 입력 범위는, –10, 000 에서 0 까지.

반환값

HRESULT 값을 돌려준다. 값이 유효한 입력 범위외인 경우는 E_INVALIDARG 가 돌려주어져 기초가 되는 디바이스가 에러를 돌려주었을 경우는 E_FAIL 가 돌려주어진다.

주의

0 은 최대 볼륨으로, –10, 000 은 무음. 볼륨에는 대수 눈금이 사용된다. 필요한 데시벨 레벨을 100 배가 된다 (예를 들어, –10, 000 = –100 dB).


IBasicVideo 인터페이스

IBasicVideo 인터페이스는,비디오 렌더러 필터로 이행 되어PID 를 개입시켜 필터 그래프 매니저로 공개된다. 어플리케이션은, 항상 필터 그래프 매니저를 개입시켜 이 인터페이스를 취득할 필요가 있다. 이 인터페이스를 사용 하면, 어플리케이션으로, bit rate, 전송처 직사각형, 전송원직사각형등의 비디오 프로퍼티를 설정할 수 있다. 이것은, 듀얼 인터페이스이므로, C++ 뿐만이 아니라 Microsoft® Visual Basic® 로 기술된 어플리케이션으로부터도 액세스 할 수 있다.

IBasicVideo 인터페이스의 메소드를 사용하는 경우, 비디오 렌더러가 접속되고 있는 것만이 필요하게 된다. 접속되어 있지 않으면 인터페이스 메소드는 모두 VFW_E_NOT_CONNECTED 를 돌려준다. 비디오 렌더러로 설정된 프로퍼티는, 연속한 접속과 접속 해제동안에서 보관 유지된다.

비디오를 취급하는 경우, 어플리케이션은 사용하는 비디오의 일부분을 선택할 수 있다. 이 부분은,IBasicVideo 인터페이스가 제어하는 전송원직사각형이 된다. IBasicVideo 를 사용 하면, 이 전송원직사각형을 설정 및 취득할 수 있다. IBasicVideo 가 사용하는 모든 직사각형에는, Microsoft® Win32® 프로그래밍으로 선호되는 top, left, width, 및 height 를 사용해, top, left, right, 및 bottom 는 사용하지 않는다. 전송원직사각형을 설정하고 있지 않는 경우, 그 전송원직사각형의 프로퍼티는 풀 사이즈의 네이티브 비디오를 돌려준다. 직사각형의 넓이는 모두 픽셀 단위로 지정한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IBasicVideo 메소드 | 설명
get_AvgTimePerFrame | 연속하는 프레임간의 평균 시간을 100 나노초단위로 취득한다.
get_BitRate | 비디오 스트림의 대략의 bit rate를 취득한다.
get_BitErrorRate | 비디오 스트림의 대략의 비트 에러 레이트를 취득한다.
get_VideoWidth | 현재의 비디오의 폭을 취득한다.
get_VideoHeight | 현재의 비디오의 높이를 취득한다.
put_SourceLeft | 비디오의 전송원직사각형의 x 축의 좌표를 설정한다.
get_SourceLeft | 비디오의 전송원직사각형의 x 축의 좌표를 취득한다.
put_SourceWidth | 비디오의 전송원직사각형의 폭을 설정한다.
get_SourceWidth | 비디오의 전송원직사각형의 폭을 취득한다.
put_SourceTop | 비디오의 전송원직사각형의 y 축의 좌표를 설정한다.
get_SourceTop | 비디오의 전송원직사각형의 y 축의 좌표를 취득한다.
put_SourceHeight | 비디오의 전송원직사각형의 높이를 설정한다.
get_SourceHeight | 비디오의 전송원직사각형의 높이를 취득한다.
put_DestinationLeft | 비디오의 전송처 직사각형의 x 축의 좌표를 설정한다.
get_DestinationLeft | 비디오의 전송처 직사각형의 x 축의 좌표를 취득한다.
put_DestinationWidth | 비디오의 전송처 직사각형의 폭을 설정한다.
get_DestinationWidth | 비디오의 전송처 직사각형의 폭을 취득한다.
put_DestinationTop | 비디오의 전송처 직사각형의 y 축의 좌표를 설정한다.
get_DestinationTop | 비디오의 전송처 직사각형의 y 축의 좌표를 취득한다.
put_DestinationHeight | 비디오의 전송처 직사각형의 높이를 설정한다.
get_DestinationHeight | 비디오의 전송처 직사각형의 높이를 취득한다.
SetSourcePosition | 비디오의 전송원직사각형을 설정한다.
GetSourcePosition | 비디오의 전송원직사각형을 취득한다.
SetDefaultSourcePosition | 디폴트의 전송원직사각형을 사용하도록(듯이) 렌더러에 지시한다.
SetDestinationPosition | 윈도우에 대한 전송처 직사각형을 설정한다.
GetDestinationPosition | 윈도우에 대한 비디오의 전송처 직사각형을 취득한다.
SetDefaultDestinationPosition | 윈도우에 대한 디폴트의 전송처 위치를 설정한다.
GetVideoSize | 네이티브 비디오의 넓이를 취득한다.
GetVideoPaletteEntries | 비디오로 필요하게 되는 칼라 팔레트의 엔트리를 취득한다.
GetCurrentImage | 렌더러로 대기하고 있는 현재의 이미지의 카피를 돌려준다.
IsUsingDefaultSource | 렌더러가 디폴트의 전송원직사각형을 사용하고 있을지 어떨지를 판별한다.
IsUsingDefaultDestination | 렌더러가 디폴트의 전송처 직사각형을 사용하고 있을지 어떨지를 판별한다.

IBasicVideo::get_AvgTimePerFrame

IBasicVideo 인터페이스

연속하는 프레임간의 평균 시간을 100 나노초단위로 취득한다.

구문

HRESULT get_AvgTimePerFrame(
    REFTIME *pAvgTimePerFrame
);

파라미터

pAvgTimePerFrame
[out] 프레임간의 시간에의 포인터.

반환값

HRESULT 값을 돌려준다.

IBasicVideo::get_BitErrorRate

IBasicVideo 인터페이스

비디오 스트림의 비트 에러 레이트를 취득한다 (거의 이 비트수에 대해서 1 개의 에러).

구문

HRESULT get_BitErrorRate(
    long *pBitErrorRate
);

파라미터

pBitErrorRate
[out] 대략의 비트 에러 레이트에의 포인터.

반환값

HRESULT 값을 돌려준다.

IBasicVideo::get_BitRate

IBasicVideo 인터페이스

비디오 스트림의 대략의 bit rate (비트/초단위)를 취득한다.

구문

HRESULT get_BitRate(
    long *pBitRate
);

파라미터

pBitRate
[out] 대략의 bit rate에의 포인터.

반환값

HRESULT 값을 돌려준다.

IBasicVideo::GetCurrentImage

IBasicVideo 인터페이스

렌더러로 대기하고 있는 현재의 이미지를 취득한다.

구문

HRESULT GetCurrentImage(
    long *pBufferSize,
    long *pDIBImage
);

파라미터

pBufferSize
[in, out] 호출원이 건네주고 있는 버퍼 사이즈에의 포인터.
pDIBImage
[out] 이미지 전체가 디바이스에 의존하지 않는 비트 맵 (DIB) 포맷으로 저장 되는 버퍼에의 포인터. 이 버퍼는 이 함수로 사용할 수 있도록(듯이) long 형의 포인터에 캐스트 될 필요가 있다.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 렌더러로 DirectDraw 가속화가 사용되고 있으면(자) 실패한다. 실패할지 어떨지는 최종 사용자의 하드웨어 구성에 의존하기 위해(때문에), 실제로는 이 메소드를 신뢰할 수 없다. 그래프내의 스트림으로부터 샘플을 취득하는 경우는,ISampleGrabber 인터페이스를 사용하는 (분)편이 좋다.

이 메소드를 호출하기 전에 비디오 렌더러를 포즈 한다. 포즈 하고 있지 않으면VFW_E_NOT_PAUSED 가 돌려주어진다. ImediaCOntrol::GetState 를 호출하는 것에 의해 완료하는 것에 주의 해야 한다. 포즈 조작이 종료하고 있지 않으면 GetCurrentImage 의 호출은 E_UNEXPECTED 를 돌려준다. 소스 필터로 이용 가능하게 되는 데이터에 따라서는, 비디오 렌더러가 이 요구에 응하지 않는 경우도 있다. 이용 가능한 이미지가 없는 경우는, E_FAIL 가 돌려주어진다.

이미지 포인터를 NULL 로 해 이 메소드를 호출하는 것으로, 이미지의 보관 유지에 필요한 버퍼의 사이즈를 취득한다. 이 경우, 버퍼 사이즈에는 필요한 바이트수가 돌려주어진다. 버퍼 사이즈 포인터는 반드시 유효한 필요가 있다. 어플리케이션이 이 메소드를 호출했을 때에, 버퍼 사이즈가 너무 작아 이미지 전체를 보관 유지할 수 없으면 렌더러는 E_OUTOFMEMORY 를 돌려준다.

이 메소드가 성공하면(자), 출력 이미지 포인터에 DIB 이미지 전체가 저장 된다. 이것에는, Microsoft Win32 BITMAPINFOHEADER 구조체, 필요한 임의의 팔레트, 및 Win32 BITMAPINFO 구조체로 정의되고 있는 비트 마스크도 포함된다. 돌려주어지는 이미지의 포맷은 소스 필터가 제공하는 타입에 응해 달라, 미리 명시적으로 정의할 수 없다. 보통, 이미지는 24 비트, 16 비트, 또는 8 비트의 팔레트화 된 이미지가 된다.

IBasicVideo::get_DestinationHeight

IBasicVideo 인터페이스

전송처 직사각형의 높이를 취득한다.

구문

HRESULT get_DestinationHeight(
    long *pDestinationHeight
);

파라미터

pDestinationHeight
[out] 현재의 높이에의 포인터 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

IBasicVideo::get_DestinationLeft

IBasicVideo 인터페이스

전송처 직사각형의 x 축의 기점의 좌표를 취득한다.

구문

HRESULT get_DestinationLeft(
    long *pDestinationLeft
);

파라미터

pDestinationLeft
[out] 현재의 x 축의 기점에의 포인터.

반환값

HRESULT 값을 돌려준다.

IBasicVideo::GetDestinationPosition

IBasicVideo 인터페이스

윈도우 좌표내의 전송처 직사각형의 위치를 취득한다.

구문

HRESULT GetDestinationPosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

파라미터

pLeft
[out] 전송처 윈도우의 x 축의 기점에의 포인터.
pTop
[out] 전송처 윈도우의 y 축의 기점에의 포인터.
pWidth
[out] 전송처 윈도우의 폭에의 포인터 (픽셀 단위).
pHeight
[out] 전송처 윈도우의 높이에의 포인터 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면,IBasicVideo::get_DestinationLeft ,IBasicVideo::get_DestinationTop ,IBasicVideo::get_DestinationWidth , 및 IBasicVideo::get_DestinationHeight 의 각 메소드를 개별적으로 호출했을 경우와 같은 결과를 얻을 수 있다.

IBasicVideo::get_DestinationTop

IBasicVideo 인터페이스

전송처의 y 축의 기점의 좌표를 취득한다.

구문

HRESULT get_DestinationTop(
    long *pDestinationTop
);

파라미터

pDestinationTop
[out] 현재의 y 축의 기점에의 포인터.

반환값

HRESULT 값을 돌려준다.

IBasicVideo::get_DestinationWidth

IBasicVideo 인터페이스

전송처 직사각형의 폭을 취득한다.

구문

HRESULT get_DestinationWidth(
    long *pDestinationWidth
);

파라미터

pDestinationWidth
[out] 현재의 폭에의 포인터 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

IBasicVideo::get_SourceHeight

IBasicVideo 인터페이스

전송원직사각형의 높이를 취득한다.

구문

HRESULT get_SourceHeight(
    long *pSourceHeight
);

파라미터

pSourceHeight
[out] 현재의 직사각형의 높이에의 포인터 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

IBasicVideo::get_SourceLeft

IBasicVideo 인터페이스

전송원직사각형의 x 축의 좌표를 취득한다.

구문

HRESULT get_SourceLeft(
    long *pSourceLeft
);

파라미터

pSourceLeft
[out] 전송원직사각형의 x 축의 기점에의 포인터.

반환값

HRESULT 값을 돌려준다.

IBasicVideo::GetSourcePosition

IBasicVideo 인터페이스

이용 가능한 비디오에 클립 되는 전송원직사각형의 위치를 취득한다.

구문

HRESULT GetSourcePosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

파라미터

pLeft
[out] 전송원윈도우의 x 축의 기점에의 포인터.
pTop
[out] 전송원윈도우의 y 축의 기점에의 포인터.
pWidth
[out] 전송원윈도우의 폭에의 포인터 (픽셀 단위).
pHeight
[out] 전송원윈도우의 높이에의 포인터 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면,IBasicVideo::get_SourceLeft ,IBasicVideo::get_SourceTop ,IBasicVideo::get_SourceWidth , 및 IBasicVideo::get_SourceHeight 의 각 메소드를 개별적으로 호출했을 경우와 같은 결과를 얻을 수 있다.

IBasicVideo::get_SourceTop

IBasicVideo 인터페이스

전송원직사각형의 y 축의 기점의 좌표를 취득한다.

구문

HRESULT get_SourceTop(
    long *pSourceTop
);

파라미터

pSourceTop
[out] 새로운 탑 좌표에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드를 설정해도, 전송원직사각형의 높이에는 영향을 주지 않는다.

IBasicVideo::get_SourceWidth

IBasicVideo 인터페이스

전송원직사각형의 폭을 취득한다.

구문

HRESULT get_SourceWidth(
    long *pSourceWidth
);

파라미터

pSourceWidth
[out] 현재의 폭에의 포인터 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 전송원직사각형의 x 축의 좌표에 영향을 주지 않는다.

IBasicVideo::get_VideoHeight

IBasicVideo 인터페이스

현재의 비디오의 높이를 취득한다.

구문

HRESULT get_VideoHeight(
    long *pVideoHeight
);

파라미터

pVideoHeight
[out] 비디오의 네이티브의 높이에의 포인터 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 렌더러에 공급되는 비디오의 실제의 높이를 돌려준다. 이 메소드는 설정된 전송원직사각형을 대상으로 하지 않고, 단순하게 네이티브의 수직 넓이를 돌려준다. 어플리케이션은 이 메소드를 사용해 매입 컨테이너 문서와의 사이에 사이즈 요건을 네고시에이트 할 수 있다.

IBasicVideo::GetVideoPaletteEntries

IBasicVideo 인터페이스

비디오의 팔레트의 색을 취득한다.

구문

HRESULT GetVideoPaletteEntries(
    long StartIndex,
    long Entries,
    long *pRetrieved,
    long *pPalette
);

파라미터

StartIndex
[in] 팔레트의 시작 인덱스.
Entries
[in] 필요한 팔레트 엔트리의 수.
pRetrieved
[out] 실제로 돌려주어지는 엔트리의 수에의 포인터.
pPalette
[out] Microsoft Win32 PALETTEENTRY 구조체의 배열에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

어플리케이션은, 이 메소드를 사용해, 비디오로 필요한 색 가지수를 조회할 수 있다. 어플리케이션은 NULL 의 pPalette 파라미터를 건네줄 수가 있어pRetrieved 파라미터에는 사용되고 있는 색의 수가 돌려주어진다. pPalette 파라미터는,PALETTEENTRY 구조체의 배열에의 포인터이다. StartIndex 파라미터 및 Entries 파라미터를 사용 하면, 어플리케이션은 1 개의 메소드로 팔레트가 연속하고 있는 섹션을 요구할 수 있다. 이 인터페이스는, Win32 GetSystemPaletteEntries 함수로 모델화 되고 있다.

IBasicVideo::GetVideoSize

IBasicVideo 인터페이스

네이티브 비디오의 넓이를 취득한다.

구문

HRESULT GetVideoSize(
    long *pWidth,
    long *pHeight
);

파라미터

pWidth
[out] 비디오 윈도우의 폭에의 포인터 (픽셀 단위).
pHeight
[out] 비디오 윈도우의 높이에의 포인터 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 설정되어 있을 가능성이 있는 전송원직사각형을 무시해, 네이티브인 비디오의 폭 및 높이를 취득한다. Microsoft® ActiveX® 컨트롤 또는 그 외의 어플리케이션은, 이 정보를 사용해 복합 문서내의 영역을 네고시에이트 할 수 있다.

IBasicVideo::get_VideoWidth

IBasicVideo 인터페이스

현재의 비디오의 폭을 취득한다.

구문

HRESULT get_VideoWidth(
    long *pVideoWidth
);

파라미터

pVideoWidth
[out] 비디오의 네이티브의 폭에의 포인터 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 렌더러에 공급되는 비디오의 실제의 폭을 돌려준다. 이 메소드는 설정된 전송원직사각형을 대상으로 하지 않고, 단순하게 네이티브의 수평 넓이를 돌려준다. 어플리케이션은 이 메소드를 사용해 매입 ActiveX 문서와의 사이에 사이즈 요건을 네고시에이트 할 수 있다.

IBasicVideo::IsUsingDefaultDestination

IBasicVideo 인터페이스

렌더러가 디폴트의 전송처 직사각형을 사용하고 있을지 어떨지를 판별한다.

구문

HRESULT IsUsingDefaultDestination(void);

반환값

HRESULT 값을 돌려준다. 디폴트의 전송처 직사각형이 사용되고 있는 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

필터에 전송처 직사각형의 디폴트 설정을 사용하도록(듯이) 지시하는 경우에,IBasicVideo::SetDefaultDestinationPosition 메소드를 사용할 수 있다. IsUsingDefaultDestination 메소드는, 그 설정이 사용되고 있는지 어떤지를 돌려준다.

IBasicVideo::IsUsingDefaultSource

IBasicVideo 인터페이스

렌더러가 디폴트의 전송원직사각형을 사용하고 있을지 어떨지를 판별한다.

구문

HRESULT IsUsingDefaultSource(void);

반환값

HRESULT 값을 돌려준다. 디폴트의 전송원직사각형이 사용되고 있는 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

필터에 전송원직사각형의 디폴트 설정을 사용하도록(듯이) 지시하는 경우에,IBasicVideo::SetDefaultSourcePosition 메소드를 사용할 수 있다. IsUsingDefaultSource 메소드는 그 설정이 사용되고 있는지 어떤지를 돌려준다.

IBasicVideo::put_DestinationHeight

IBasicVideo 인터페이스

전송처 직사각형의 높이를 설정한다.

구문

HRESULT put_DestinationHeight(
    long DestinationHeight
);

파라미터

DestinationHeight
[in] 새로운 높이 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 좌표를 설정해도, 전송처 직사각형의 y 축의 기점에는 영향을 주지 않는다.

IBasicVideo::put_DestinationLeft

IBasicVideo 인터페이스

전송처의 x 축의 기점의 좌표를 설정한다.

구문

HRESULT put_DestinationLeft(
    long DestinationLeft
);

파라미터

DestinationLeft
[in] 새로운 x 축의 기점.

반환값

HRESULT 값을 돌려준다.

주의

이 좌표를 설정해도, 전송처 직사각형의 폭에는 영향을 주지 않는다.

IBasicVideo::put_DestinationTop

IBasicVideo 인터페이스

전송처의 y 축의 기점의 좌표를 설정한다.

구문

HRESULT put_DestinationTop(
    long DestinationTop
);

파라미터

DestinationTop
[in] 새로운 y 축의 기점.

반환값

HRESULT 값을 돌려준다.

주의

이 좌표를 설정해도, 전송처 직사각형의 높이에는 영향을 주지 않는다.

IBasicVideo::put_DestinationWidth

IBasicVideo 인터페이스

전송처 직사각형의 폭을 설정한다.

구문

HRESULT put_DestinationWidth(
    long DestinationWidth
);

파라미터

DestinationWidth
[in] 새로운 폭 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 좌표를 설정해도, 전송처 직사각형의 x 축의 기점에는 영향을 주지 않는다.

IBasicVideo::put_SourceHeight

IBasicVideo 인터페이스

전송원직사각형의 높이를 설정한다.

구문

HRESULT put_SourceHeight(
    long SourceHeight
);

파라미터

SourceHeight
[in] 새로운 직사각형의 높이 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

전송원직사각형의 높이를 설정해도, 전송원의 y 축의 좌표에는 영향을 주지 않는다.

IBasicVideo::put_SourceLeft

IBasicVideo 인터페이스

전송원직사각형의 x 축의 좌표를 설정한다.

구문

HRESULT put_SourceLeft(
    long SourceLeft
);

파라미터

SourceLeft
[in] 전송원직사각형의 x 축의 기점.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드를 설정해도, 전송원직사각형의 폭에는 영향을 주지 않는다.

IBasicVideo::put_SourceTop

IBasicVideo 인터페이스

전송원직사각형의 y 축의 기점의 좌표를 설정한다.

구문

HRESULT put_SourceTop(
    long SourceTop
);

파라미터

SourceTop
[in] 새로운 탑 좌표.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드를 설정해도, 전송원직사각형의 높이에는 영향을 주지 않는다.

IBasicVideo::put_SourceWidth

IBasicVideo 인터페이스

전송원직사각형의 폭을 설정한다.

구문

HRESULT put_SourceWidth(
    long SourceWidth
);

파라미터

SourceWidth
[in] 전송원직사각형의 새로운 폭 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드를 설정해도, 전송원직사각형의 x 축의 좌표에는 영향을 주지 않는다.

IBasicVideo::SetDefaultDestinationPosition

IBasicVideo 인터페이스

렌더러가 재생에 윈도우 전체를 사용하도록(듯이), 비디오 윈도우의 디폴트의 전송처 위치를 설정한다.

구문

HRESULT SetDefaultDestinationPosition(void);

반환값

HRESULT 값을 돌려준다.

IBasicVideo::SetDefaultSourcePosition

IBasicVideo 인터페이스

디폴트의 전송원직사각형을 사용하도록(듯이) 렌더러에 지시한다.

구문

HRESULT SetDefaultSourcePosition(void);

반환값

HRESULT 값을 돌려준다.

IBasicVideo::SetDestinationPosition

IBasicVideo 인터페이스

윈도우 좌표내에서의 전송처 직사각형의 위치를 설정한다.

구문

HRESULT SetDestinationPosition(
    long Left,
    long Top,
    long Width,
    long Height
);

파라미터

Left
[in] 전송처 윈도우의 x 축의 기점.
Top
[in] 전송처 윈도우의 y 축의 기점.
Width
[in] 전송처 윈도우의 폭 (픽셀 단위).
Height
[in] 전송처 윈도우의 높이 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면,IBasicVideo::put_DestinationLeft ,IBasicVideo::put_DestinationTop ,IBasicVideo::put_DestinationWidth , 및 IBasicVideo::put_DestinationHeight 의 각 메소드를 개별적으로 호출했을 경우와 같은 결과를 얻을 수 있다.

IBasicVideo::SetSourcePosition

IBasicVideo 인터페이스

이용 가능한 비디오에 클립 되는 전송원직사각형을 설정한다.

구문

HRESULT SetSourcePosition(
    long Left,
    long Top,
    long Width,
    long Height
);

파라미터

Left
[in] 전송원윈도우의 x 축의 기점.
Top
[in] 전송원윈도우의 y 축의 기점.
Width
[in] 전송원윈도우의 폭 (픽셀 단위).
Height
[in] 전송원윈도우의 높이 (픽셀 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면,IBasicVideo::put_SourceLeft ,IBasicVideo::put_SourceTop ,IBasicVideo::put_SourceWidth , 및 IBasicVideo::put_SourceHeight 의 각 메소드를 개별적으로 호출했을 경우와 같은 결과를 얻을 수 있다.

이 좌표를 설정해도, 전송처 직사각형의 높이에는 영향을 주지 않는다.


IBasicVideo2 인터페이스

IBasicVideo2 인터페이스는,IBasicVideo 로부터 파생한 인터페이스로, 비디오 스트림의 어스펙트비(가로세로 비율)을 취득하는 다른 방법을 어플리케이션에 제공한다. 이 인터페이스는 비디오 렌더러 필터로 이행 되지만, 필터 그래프 매니저로 어플리케이션에 공개된다. 상세한 것에 대하여는, 「IBasicVideo 」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IBasicVideo 메소드 | 설명
get_AvgTimePerFrame | 연속하는 프레임간의 평균 시간을 100 나노초단위로 취득한다.
get_BitRate | 비디오 스트림의 대략의 bit rate를 취득한다.
get_BitErrorRate | 비디오 스트림의 대략의 비트 에러 레이트를 취득한다.
get_VideoWidth | 현재의 비디오의 폭을 취득한다.
get_VideoHeight | 현재의 비디오의 높이를 취득한다.
put_SourceLeft | 비디오의 전송원직사각형의 x 축의 좌표를 설정한다.
get_SourceLeft | 비디오의 전송원직사각형의 x 축의 좌표를 취득한다.
put_SourceWidth | 비디오의 전송원직사각형의 폭을 설정한다.
get_SourceWidth | 비디오의 전송원직사각형의 폭을 취득한다.
put_SourceTop | 비디오의 전송원직사각형의 y 축의 좌표를 설정한다.
get_SourceTop | 비디오의 전송원직사각형의 y 축의 좌표를 취득한다.
put_SourceHeight | 비디오의 전송원직사각형의 높이를 설정한다.
get_SourceHeight | 비디오의 전송원직사각형의 높이를 취득한다.
put_DestinationLeft | 비디오의 전송처 직사각형의 x 축의 좌표를 설정한다.
get_DestinationLeft | 비디오의 전송처 직사각형의 x 축의 좌표를 취득한다.
put_DestinationWidth | 비디오의 전송처 직사각형의 폭을 설정한다.
get_DestinationWidth | 비디오의 전송처 직사각형의 폭을 취득한다.
put_DestinationTop | 비디오의 전송처 직사각형의 y 축의 좌표를 설정한다.
get_DestinationTop | 비디오의 전송처 직사각형의 y 축의 좌표를 취득한다.
put_DestinationHeight | 비디오의 전송처 직사각형의 높이를 설정한다.
get_DestinationHeight | 비디오의 전송처 직사각형의 높이를 취득한다.
SetSourcePosition | 비디오의 전송원직사각형을 설정한다.
GetSourcePosition | 비디오의 전송원직사각형을 취득한다.
SetDefaultSourcePosition | 디폴트의 전송원직사각형을 사용하도록(듯이) 렌더러에 지시한다.
SetDestinationPosition | 윈도우에 대한 전송처 직사각형을 설정한다.
GetDestinationPosition | 윈도우에 대한 비디오의 전송처 직사각형을 취득한다.
SetDefaultDestinationPosition | 윈도우에 대한 디폴트의 전송처 위치를 설정한다.
GetVideoSize | 네이티브 비디오의 넓이를 취득한다.
GetVideoPaletteEntries | 비디오로 필요하게 되는 칼라 팔레트의 엔트리를 취득한다.
GetCurrentImage | 렌더러로 대기하고 있는 현재의 이미지의 카피를 돌려준다.
IsUsingDefaultSource | 렌더러가 디폴트의 전송원직사각형을 사용하고 있을지 어떨지를 판별한다.
IsUsingDefaultDestination | 렌더러가 디폴트의 전송처 직사각형을 사용하고 있을지 어떨지를 판별한다.
IBasicVideo2 메소드 | 설명
GetPreferredAspectRatio | 무비의 어스펙트비(가로세로 비율)을 취득한다.

IBasicVideo2::GetPreferredAspectRatio

IBasicVideo2 인터페이스

무비의 어스펙트비(가로세로 비율)을 정의하는 비율을 나타내는, 넓이가 포함되지 않은 1 조의 값을 취득한다.

구문

HRESULT GetPreferredAspectRatio (
    long *plAspectX,
    long *plAspectY
    );

파라미터

plAspectX
[out] 무비의 x 축의 어스펙트비(가로세로 비율)을 나타내는 값에의 포인터.
plAspectY
[out] 무비의 y 축의 어스펙트비(가로세로 비율)을 나타내는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
S_OK | 성공.
E_INVALIDARG | 한편 또는 양쪽 모두의 파라미터가 무효.
E_NOINTERFACE | 렌더러로 IBasicVideo2 가 이행되어 있지 않다.

주의

무비의 어스펙트비(가로세로 비율)의 상세한 것에 대하여는,VIDEOINFOHEADER2 구조체의 문서를 참조할것.


ICaptureGraphBuilder2 인터페이스

이 인터페이스는, 캡춰 그래프, 프리뷰 그래프, 파일재압축 그래프를 생성하기 위한 메소드를 갖추고 있다. 캡춰 그래프 빌더가 이 인터페이스를 이행 한다.

이 인터페이스는,ICaptureGraphBuilder 인터페이스를 옮겨놓는 것이다. 이 인터페이스에서는, 오디오와 비디오의 양쪽 모두 등, 복수의 미디어를 캡춰 할 수 있는 Microsoft® Windows® Driver Model (WDM) 캡춰 드라이버를 사용할 수 있다. 종래의 ICaptureGraphBuilder 인터페이스에서는, 비디오와 오디오의 양쪽 모두의 캡춰에 같은 드라이버를 사용하는 디바이스는 사용할 수 없다.

이 인터페이스의 사용법의 상세한 것에 대하여는, 「캡춰 어플리케이션의 쓰는 법」 및 「AVI 파일의 재압축」을 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
ICaptureGraphBuilder2 메소드 | 설명
SetFiltergraph | 캡춰 그래프 빌더가 사용하는 필터 그래프를 지정한다.
GetFiltergraph | 빌더가 사용하고 있는 필터 그래프를 취득한다.
SetOutputFileName | 필터 그래프의 파일 라이팅 섹션을 생성 한다.
FindInterface | 지정된 필터로부터 시작해, 지정된 인터페이스를 그래프내에서 검색한다.
RenderStream | 소스 필터의 출력 핀을, 옵션으로 압축 필터를 경유해, 렌더링 필터에 접속한다.
ControlStream | 캡춰 된 데이터의 1 개 이상의 스트림의 시작 타임과 종료 타임을 설정한다.
AllocCapFile | 캡춰 파일이 지정된 사이즈에 미리 할당한다.
CopyCaptureFile | 캡춰 파일로부터 유효한 미디어 데이터를 카피한다.
FindPin | 필터의 특정의 핀을 취득하는지, 특정의 핀이 지정된 조건에 적합할지 어떨지를 판별한다.

ICaptureGraphBuilder2::AllocCapFile

ICaptureGraphBuilder2 인터페이스

캡춰 파일이 지정된 사이즈에 미리 할당한다. 최선의 결과를 얻으려면 , 항상, 캡춰 데이터보다 사이즈가 크고, 최적화되어 미리 할당할 수 있었던 캡춰 파일에 캡춰 한다.

구문

HRESULT AllocCapFile(
    LPCOLESTR lpwstr,
    DWORDLONG dwlSize
);

파라미터

lpwstr
[in] 생성 또는 사이즈를 변경하는 파일의 이름이 저장 된 Unicode™ 캐릭터 라인에의 포인터.
dwlSize
[in] 할당하는 파일의 사이즈 (바이트 단위).

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

파일이 읽어내 전용의 경우, 이 메소드는 실패한다.

이상적이게는 필요이상으로 큰 가능한 한의 스페이스를 할당하는 것이 가장 바람직하다. 그러나 이것은 비교적 작은 데이터를 가지는 매우 큰 파일을 생성 하게 된다. 예를 들어, 1기가바이트(GB) 캡춰 파일에 수메가바이트의 캡춰 비디오가 들어가는 경우도 있다. CopyCaptureFile 메소드를 사용해 새로운 파일에 데이터를 카피하는 것. 이 메소드는 데이터만을 카피해, 오리지날 파일의 빈부분은 무시한다.

주 : AllocCapFile 메소드는, 미리 할당할 수 있었던 파일 전체에 걸쳐서 기입할 필요가 있기 (위해)때문에, Microsoft® Windows NT® 4. x 플랫폼상 또는 Microsoft® Windows® 2000 플랫폼상에서는, Windows 9x 플랫폼상보다 동작이 늦어진다. 다만, 그런데도 이 메소드는 캡춰의 퍼포먼스가 높기 때문에, 이 메소드를 사용하는 것이 추천 되고 있다.

ICaptureGraphBuilder2::ControlStream

ICaptureGraphBuilder2 인터페이스

캡춰 된 데이터의 1 개 이상의 스트림의 시작 타임과 종료 타임을 설정한다.

이 메소드는, 메소드의 호출로 지정된 검색 조건을 사용해, 캡춰 필터 위에의 출력 핀을 검색한다. 다음에, 이러한 핀에 대해서 IAMStreamControl 메소드를 호출한다. 이 메소드를 이용 하면, 어플리케이션은, 그래프내의 필터나 핀을 열거하지 않고 , 스트림을 제어할 수 있다.

이 메소드는, 프레임 단위의 정밀도가 요구되는 캡춰나, 개별의 캡춰 동작 및 프리뷰 동작의 제어에 사용한다. 예를 들어, 비디오의 프리뷰를 중단하지 않고 , 디스크에의 캡춰를 정지할 수가 있다.

구문

HRESULT ControlStream(
    const GUID *pCategory,
    const GUID *pType,
    IBaseFilter *pFilter,
    REFERENCE_TIME *pstart,
    REFERENCE_TIME *pstop,
    WORD wStartCookie,
    WORD wStopCookie
);

파라미터

pCategory
[in] 핀 카테고리를 지정하는 AMPROPERTY_PIN_CATEGORY 프로퍼티 세트의 멤버에의 포인터. 이 파라미터의 값을 NULL 로 하는 것은 할 수 없다.
pType
[in] 미디어 타입을 지정하는메이저 타입 GUID 에의 포인터 또는 NULL. 이 파라미터가 NULL 의 경우는,pFilter 파라미터도 NULL 로 설정한다. 그렇게 하지 않으면 잘못한 핀이 제어되어 예기치 않은 결과가 생기는 일이 있다.
pFilter
[in] 제어하는 필터를 지정하는 IBaseFilter 인터페이스에의 포인터. 그래프내의 모든 캡춰 필터를 제어하려면 , 이 파라미터를 NULL 로 설정한다.
pstart
[in] 시작 타임이 저장 된 변수에의 포인터. 즉시 시작 하려면 , 값을 NULL 로 설정한다. 전의 시작 요구를 캔슬하려면 , 값을 MAX_TIME 로 설정한다. 전의 요구가 없는 경우, 값을 MAX_TIME 로 하는 것에는 아무 효과도 없다.
pstop
[in] 종료 타임이 저장 된 변수에의 포인터. 즉시 종료하려면 , 값을 NULL 로 설정한다. 전의 종료 요구를 캔슬하려면 , 값을 MAX_TIME 로 설정한다. 전의 요구가 없는 경우, 값을 MAX_TIME 로 하는 것에는 아무 효과도 없다.
wStartCookie
[in] EC_STREAM_CONTROL_STARTED 이벤트 통지의 제 2 파라미터로서 보내지는 값. 상세한 것에 대하여는, 「주의」를 참조할것.
wStopCookie
[in] EC_STREAM_CONTROL_STOPPED 이벤트 통지의 제 2 파라미터로서 보내지는 값. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

HRESULT 값을 돌려준다. 설정되는 값은 다음과 같다.

S_FALSE | 적어도 1 살의 다운 스트림 렌더러가 종료 통지를 보내지 않는다.
S_OK | 성공.
E_FAIL | 적합하는 핀이 발견되지 않는, 또는 핀이 스트림 컨트롤을 지원 하고 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

최초의 3 개의 파라미터는, 제어하는 핀을 지정한다. 캡춰 그래프는, 복수의 캡춰 필터를 갖추고 있는 일이 있다. 예를 들어, 캡춰 그래프는, 비디오용의 필터, 오디오용의 필터, 자막 방송 데이터용의 필터를 갖추고 있는 일이 있다. 또, 캡춰 필터는, 복수의 출력 핀을 갖추고 있는 일이 있다. 일부의 캡춰 필터는, 프리뷰용과 캡춰용의 다른 핀을 갖추어 있거나, 비디오 전용 데이터용과 오디오-비디오 인터리브 데이터용의 다른 핀을 갖추고 있는 일이 있다. 예를 들어, 비디오 프리뷰를 제어하려면 ,pCategory 로서 PIN_CATEGORY_PREVIEW 를 지정해,pType 로서 MEDIATYPE_Video 를 지정한다.

핀을 제어 하면 와, 이 메소드는 IAMStreamControl::StartAt 메소드와 IAMStreamControl::StopAt 메소드를 호출한다. 각 핀은, 시작시에 EC_STREAM_CONTROL_STARTED 이벤트 통지를 보낸다. 이벤트 통지의 제 2 파라미터는,wStartCookie 가 가리키는 값이다. 핀은 정지 하면, EC_STREAM_CONTROL_STOPPED 이벤트 통지를 보낸다. 이 이벤트 통지의 제 2 파라미터는,wStopCookie 가 가리키는 값이다.

이 메소드는, 적합하는 핀을 찾아내면(자), 다운 스트림으로,IAMStreamControl (보통은 멀티플렉서)를 지원 하는 다른 필터를 검색한다. 필터가 발견되면(자), 이 메소드는, 그 필터의 시작 타임과 종료 타임을 설정한다. 이것에 의해, 캡춰 필터용과 다운 스트림 필터용의 2 개의 종료 통지의 페어가 생성된다. 다운 스트림 필터로부터의 종료 통지만이 wStopCookie 파라미터를 사용한다. 이 이벤트를 대기하는 것으로써, 다운 스트림 필터가 마지막 샘플을 받는 것이 보증된다.

IAMStreamControl 를 지원 하는 다운 스트림 필터가 없는 경우, 메소드는 S_FALSE 를 돌려준다. 그 경우는, 마지막 샘플이 렌더링 되기 전에 종료 통지를 받는 일이 있다.

ICaptureGraphBuilder2::CopyCaptureFile

ICaptureGraphBuilder2 인터페이스

캡춰 파일로부터 유효한 미디어 데이터를 카피한다.

보통은, 우선 미리 할당할 수 있던 큰 파일에 캡춰 한다. 이 메소드는 새로운 파일에 유효한 미디어 데이터만을 카피한다. 결과적으로 새로운 파일은 카피원파일보다 훨씬 작아진다.

구문

HRESULT CopyCaptureFile(
    LPOLESTR lpwstrOld,
    LPOLESTR lpwstrNew,
    int fAllowEscAbort,
    IAMCopyCaptureFileProgress *pCallback
);

파라미터

lpwstrOld
[in] 카피원파일명이 저장 된 Unicode™ 캐릭터 라인에의 포인터.
lpwstrNew
[in] 카피처 파일명이 저장 된 Unicode™ 캐릭터 라인에의 포인터. 이 파일에 유효한 데이터가 카피된다.
fAllowEscAbort
[in] Esc 키를 누르면(자) 카피 조작이 중단될지 어떨지를 나타내는 불형의 값. 값이 TRUE 의 경우는, 유저가 Esc 키를 누르면(자) 카피 조작이 중단된다. 값이 FALSE 의 경우, 메소드는 Esc 키 조작을 무시한다.
pCallback
[in] 진행 상황을 표시하는 IAMCopyCaptureFileProgress 인터페이스에의 포인터 또는 NULL. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

HRESULT 값을 돌려준다. 설정되는 값은 다음과 같다.

S_FALSE | 조작이 완료하기 전에 유저가 조작을 캔슬했다.
S_OK | 성공.
E_FAIL | 실패.
E_INVALIDARG | 카피원파일 또는 카피처 파일이 열리지 않는다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

카피원파일과 카피처 파일은 AVI 파일이 아니면 안된다. 다른 파일 타입은 지원되어 있지 않다.

카피 조작의 진행 상황을 표시하려면 ,IAMCopyCaptureFileProgress 인터페이스를 이행 해,pCallback 파라미터를 사용해 포인터를 인터페이스에 건네준다. pCallback 가 NULL 가 아닌 경우, 이 메소드는, 퍼센트 단위의 달성율을 나타내는 0 에서 100 의 사이의 정수를 지정해, 정기적으로 IAMCopyCaptureFileProgress::Progress 메소드를 호출한다.

ICaptureGraphBuilder2::FindInterface

ICaptureGraphBuilder2 인터페이스

지정된 필터로부터 시작해, 지정된 인터페이스를 그래프내에서 검색한다. 검색을 필터의 업 스트림 또는 다운 스트림의 그래프의 섹션으로 한정하거나 특정의 핀 카테고리 또는 미디어 타입으로 한정하거나 할 수가 있다.

구문

HRESULT FindInterface(
    const GUID *pCategory,
    const GUID *pType,
    IBaseFilter *pf,
    REFIID riid,
    void **ppint
);

파라미터

pCategory
[in] 검색 조건을 지정하는 GUID 에의 포인터. 상세한 것에 대하여는, 「주의」를 참조할것. 지정할 수 있는 값은 다음과 같다.
  • LOOK_UPSTREAM_ONLY
  • LOOK_DOWNSTREAM_ONLY
  • 핀 카테고리를 지정하는 AMPROPERTY_PIN_CATEGORY 프로퍼티 세트의 멤버.
  • NULL
pType
[in] 출력 핀의 미디어 타입을 지정하는메이저 타입 GUID 에의 포인터 또는 NULL.
pf
[in] 필터의 IBaseFilter 인터페이스에의 포인터.
riid
[in] 인터페이스의 참조 식별자 (ID).
ppint
[out] 인터페이스 포인터를 받는 변수의 주소. 인터페이스를 사용한 후는, 취득한 인터페이스 포인터를 반드시 해방하는 것.

반환값

HRESULT 값을 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 성공.
E_FAIL | 실패.
E_NOINTERFACE | 그 인터페이스는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

캡춰 그래프에서는, 다양한 필터 및 핀이, 압축 파라미터 (IAMVideoCompression )나 스트림 포맷 (IAMStreamConfig )등의 프로퍼티를 설정하는 인터페이스를 공개할 가능성이 있다. 캡춰 디바이스에 따라서는, 아날로그 신호의 루팅을 실시하는 IAMCrossbar 나, TV 튜너 디바이스를 제어하는 IAMTVTuner 등, 다른 유용한 인터페이스도 사용된다. 이 메소드를 사용하면, 그래프를 대상으로 검색을 행하기 위한 특수한 코드를 쓰지 않아도, 인터페이스를 검색할 수 있다.

중요 : IVideoWindow 인터페이스 포인터를 취득 하면나무는, 이 메소드를 호출하지 않고 , 반드시 필터 그래프 매니저에 이 인터페이스를 문의한다. 그렇게 하지 않으면 필터 그래프 매니저는, 화면 해상도 및 그 외의 이벤트에 올바르게 반응하지 않게 된다.

pCategory 파라미터가 NULL 인 경우, 이 메소드는, 그래프 전체를 대상으로 해 요구된 인터페이스를 검색한다. 이 메소드는,pf 파라미터에 의해 지정된 필터로부터 시작해, 그래프내에서 다음의 오브젝트를 검색한다.

  • 필터
  • 필터의 핀
  • 필터의 핀을 포함한 모든 다운 스트림 필터
  • 필터의 핀을 포함한 모든 업 스트림 필터

pCategory 파라미터와 pType 파라미터를 설정하는 것으로써, 검색을 한정할 수 있다.

  • pCategory 가 &LOOK_UPSTREAM_ONLY 인 경우, 검색은 필터의 입력 핀으로부터 시작되어, 업 스트림 방향으로 계속한다. 필터 자체나 필터의 다운 스트림에 있는 것은 검색의 대상이 되지 않는다. pType 파라미터는 무시된다.
  • pCategory 가 &LOOK_DOWNSTREAM_ONLY 인 경우, 검색은 필터의 출력 핀으로부터 시작되어, 다운 스트림 방향으로 계속한다. 필터 자체나 필터의 업 스트림에 있는 것은 검색의 대상이 되지 않는다. pType 파라미터는 무시된다.
  • pCategory 가 핀 카테고리를 지정하고 있는 경우, 검색의 다운 스트림의 부분은, 핀 카테고리와 pType 파라미터에 의해 지정되는 미디어 타입의 양쪽 모두가 일치하는 필터의 출력 핀으로 한정된다. 그 경우, 메소드는, 필터 및 필터의 업 스트림에 있는 모든 것도 검색한다.

핀 카테고리는, 캡춰 필터의 핀인타페이스를 검색할 경우에 도움이 된다. 예를 들어, 캡춰 필터는, 캡춰용과 프리뷰용의 다른 핀을 갖추고 있는 일이 있다. 핀 카테고리를 지정하는 경우는, 메소드가 올바른 필터와 핀을 선택할 수 있도록(듯이), 미디어 타입도 지정할 필요가 있다.

일부의 비디오 캡춰 필터는, 프리뷰 핀 대신에 비디오 포토 핀 (PIN_CATEGORY_VIDEOPORT)을 갖추고 있다. PIN_CATEGORY_PREVIE 와 MEDIATYPE_Video 를 지정 하면, 메소드는, 모든 비디오 포토 핀을 프리뷰 핀으로서 취급한다. 어플리케이션으로 이 가능성을 테스트할 필요는 없다.

지원 하는 필터. 캡춰 디바이스가 Windows Driver Model (WDM) 드라이버를 사용하는 경우, 그래프는,TV 튜너 필터나아날로그 비디오 크로스바 필터 등,WDM 비디오 캡춰 필터의 업 스트림에 있는 특정의 필터를 필요로 하는 일이 있다. 그래프가 이러한 WDM 필터의 어느쪽이든을 필요로 하는 경우, 이 메소드는 자동적으로 그러한 필터를 그래프에 삽입한다. 메소드는, 캡춰 필터의 입력 핀에 문의해, 입력 핀이 지원 하는 미디어를 판별해, 그러한 미디어를 적합하는 필터에 접속한다.

ICaptureGraphBuilder2::FindPin

ICaptureGraphBuilder2 인터페이스

필터의 특정의 핀을 취득하는지, 특정의 핀이 지정된 조건에 적합할지 어떨지를 판별한다.

구문

HRESULT FindPin(
    IUnknown *pSource,
    PIN_DIRECTION pindir,
    const GUID *pCategory,
    const GUID *pType,
    BOOL fUnconnected,
    int num,
    IPin **ppPin
);

파라미터

pSource
[in] 필터의 인터페이스에의 포인터 또는 핀의 인터페이스에의 포인터.
pindir
[in] 핀의 방향 (입력 또는 출력)을 지정하는 PIN_DIRECTION 열거의 멤버.
pCategory
[in] 핀 카테고리를 지정하는 AMPROPERTY_PIN_CATEGORY 프로퍼티 세트의 멤버. 모든 카테고리가 적합하는 경우는 NULL 를 사용한다.
pType
[in] 미디어 타입을 지정하는메이저 타입 GUID 에의 포인터. 모든 미디어가 적합하는 경우는 NULL 를 사용한다.
fUnconnected
[in] 핀의 접속이 빗나가고 있을 필요가 있을지 어떨지를 지정하는 불형의 값. TRUE 의 경우, 핀의 접속은 빗나가고 있을 필요가 있다. FALSE 의 경우는, 핀이 접속되고 있어도, 접속되어 있지 않아도 좋다.
num
[in] 적합하는 핀세트로부터 취득하는 핀의, 시작값을 제로로 하는 인덱스. pSource 가 필터에의 포인터로, 복수의 핀이 검색 조건에 적합하는 경우는, 이 파라미터로 취득하는 핀을 지정한다. pSource 가 핀에의 포인터인 경우, 이 파라미터는 무시된다.
ppPin
[out] 적합하는 핀의 IPin 인터페이스를 받는 포인터의 주소.

반환값

적합하는 핀이 발견되었을 경우는 S_OK, 그 이외의 경우는 E_FAIL 를 돌려준다.

주의

pSource 가 필터에의 포인터인 경우, 메소드는, 그 필터상에서 검색 조건에 적합하는 n 번째의 핀을 검색한다. n 는 num 파라미터에 의해 지정된다. 메소드는, 적합하는 핀을 찾아내면(자),ppPin 파라미터에 의해 핀에의 포인터를 돌려준다.

pSource 가 핀에의 포인터인 경우, 메소드는, 그 핀이 검색 조건에 적합할지 어떨지를 테스트한다. 핀이 조건에 적합하는 경우, 메소드는 S_OK 를 돌려주어,ppPin 파라미터에 의해 핀의 IPin 인터페이스에의 포인터를 돌려준다. 그 이외의 경우, 메소드는 E_FAIL 를 돌려준다.

어느 경우도, 메소드가 성공하면(자),ppPin 파라미터에 의해 돌려주어지는 IPin 인터페이스에는, 미해결의 참조 카운트가 남는다. 인터페이스를 사용한 후는, 반드시 해방하는 것.

보통, 어플리케이션이 이 메소드를 사용할 필요는 없다. 이 메소드는,RenderStream 메소드에서는 필터 그래프를 생성 할 수 없는, 극히 복잡한 태스크를 처리하기 위해서 준비되어 있다. 이 메소드를 사용해 목적의 핀을 캡춰 필터로부터 취득해, 그래프의 나머지의 부분을 수동으로 생성 한다.

ICaptureGraphBuilder2::GetFiltergraph

ICaptureGraphBuilder2 인터페이스

캡춰 그래프 빌더가 사용하고 있는 필터 그래프를 취득한다.

구문

HRESULT GetFiltergraph(
    IGraphBuilder **ppfg
);

파라미터

ppfg
[out] IGraphBuilder 인터페이스 포인터를 받는 변수의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | 필터 그래프가 없다.

주의

이 메소드는,IGraphBuilder 인터페이스의 참조 카운트를 인크리먼트(increment) 한다. 인터페이스의 사용을 끝마치면(자), 반드시 인터페이스를 해방하는 것.

ICaptureGraphBuilder2::RenderStream

ICaptureGraphBuilder2 인터페이스

소스 필터의 출력 핀을, 옵션으로 압축 필터를 경유해, 렌더링 필터에 접속한다.

구문

HRESULT RenderStream(
    const GUID *pCategory,
    const GUID *pType,
    IUnknown *pSource,
    IBaseFilter *pfCompressor,
    IBaseFilter *pfRenderer
);

파라미터

pCategory
[in] 핀 카테고리를 지정하는 AMPROPERTY_PIN_CATEGORY 프로퍼티 세트의 멤버에의 포인터. 카테고리에 관계없이, 임의의 핀을 사용하는 경우는 NULL 를 지정한다. 보통은, 다음의 값을 지정한다.
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • PIN_CATEGORY_VBI
  • PIN_CATEGORY_CC
pType
[in] 출력 핀의 미디어 타입을 지정하는메이저 타입 GUID 에의 포인터. 미디어 타입에 관계없이, 임의의 핀을 사용하는 경우는 NULL 를 지정한다.
pSource
[in] 소스 필터의 인터페이스에의 포인터 또는 출력 핀의 인터페이스에의 포인터.
pfCompressor
[in] 압축 필터의 IBaseFilter 인터페이스에의 옵션의 포인터.
pfRenderer
[in] 렌더링 필터 또는 멀티플렉서 필터의 IBaseFilter 인터페이스에의 옵션의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 반환값은 다음과 같다.

S_OK | 성공.
VFW_S_NOPREVIEWPIN | 스마트티 필터 를 경유해 프리뷰가 렌더링 되었다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는, 프리뷰 또는 파일에의 기입을 실시할 때에 스트림을 렌더링 한다. 이 메소드는, 캡춰 그래프가 많은 복잡한 처리를 자동적으로 실시한다.

pSource 파라미터에서는, 출력 핀 또는 필터를 지정한다. 출력 핀을 지정했을 경우, 메소드는, 그 핀으로부터의 스트림을 렌더링 한다. 그 경우는,pCategory 파라미터와 pType 파라미터를 NULL 로 설정한다. 필터를 지정했을 경우, 메소드는, 핀 카테고리가 pCategory 파라미터와 일치해, 미디어 타입이 pType 파라미터와 일치하는, 그 필터의 출력 핀을 검색한다.

pfRenderer 파라미터에서는, 세면대 필터를 지정한다. 세면대 필터는, 보통,파일 라이터 필터,AVI Mux 등의 멀티플렉서 필터의 어느 쪽인지이다. 멀티플렉서에의 포인터를 취득하려면 ,SetOutputFileName 메소드를 호출한다. 이 메소드는,ppf 파라미터에 의해 포인터를 돌려준다.

pfRenderer 가 NULL 인 경우, 메소드는, 디폴트의 렌더러, 즉 비디오의 경우는비디오 렌더러, 오디오의 경우는디폴트 DirectSound 디바이스를 사용한다.

pfCompressor 파라미터에서는, 압축 필터 또는 일반적으로는 임의의 변환 필터를 지정한다. 스트림을 압축하지 않는 경우는, 이 파라미터를 NULL 로 설정한다.

스마트티. 일부의 캡춰 필터에는 캡춰 핀은 있지만, 프리뷰 핀이 없다. 프리뷰를 실시하려면 , 캡춰 핀이스마트티 필터 에 접속되고 있을 필요가 있다. 이 필터는, 데이터를 캡춰 스트림과 프리뷰 스트림의 2 개의 스트림에 분할한다. PIN_CATEGORY_PREVIEW 또는 PIN_CATEGORY_CAPTURE 를 지정 하면, 필요에 따라서, 메소드가 스마트티피르타를 삽입한다. 다음에, 메소드는, 스마트티피르타상에서 지정된 스트림의 렌더링을 실시한다. 프리뷰 스트림을 렌더링 할 경우에 메소드가 스마트티피르타를 사용하는 경우, 메소드는 VFW_S_NOPREVIEWPIN 를 돌려준다.

자막 방송. 이 메소드를 사용해 자막 방송의 캡춰 또는 프리뷰를 실시할 수가 있다. 일부의 캡춰 필터는 수직 동기 간격 (VBI) 데이터를 출력해, 다른 캡춰 필터는 자막 방송 데이터를 출력한다. 어느 경우도, 1 회는 PIN_CATEGORY_VBI 를 사용해, 이제(벌써) 1 회는 PIN_CATEGORY_CC 를 사용해, 메소드를 2 회 호출한다. 메소드는, VBI 데이터를 자막 방송으로 변환하는데 필요한 모든 필터를 삽입한다. 데이터의 프리뷰를 실시하려면 ,pfRenderer 파라미터를 NULL 로 설정한다. 데이터를 파일에 캡춰 하려면 , 멀티플렉서 필터의 IBaseFilter 인터페이스 포인터를 사용한다. 같은 그래프로 데이터의 캡춰와 프리뷰를 실시할 수가 있다. 1 번째는 NULL 를 사용해, 2 번째는 멀티플렉서를 사용해 메소드를 호출한다. pfCompressor 파라미터를 NULL 로 설정한다.

비디오 포토 핀. 비디오 포토 extension (VPE) 비디오 캡춰 하드웨어를 사용하는 필터는, 프리뷰 핀 대신에 비디오 포토 핀 (PIN_CATEGORY_VIDEOPORT)을 갖추고 있다. 프리뷰나 캡춰를 기능시키려면 , 비디오 포토 핀이오버레이 믹서 필터에 접속되고 있을 필요가 있다. 세부는 메소드가 처리한다. PIN_CATEGORY_VIDEOPORT 를 지정할 필요는 없다. PIN_CATEGORY_PREVIEW 또는 PIN_CATEGORY_CAPTURE 를 지정하면, 메소드가 핀을 올바르게 접속한다. 이것과 같게, 일부의 필터는, 비디오 포토 핀 (PIN_CATEGORY_VIDEOPORT_VBI)을 사용해 VBI 데이터를 출력한다. PIN_CATEGORY_VIDEOPORT 의 경우와 같게, 메소드가 세부를 처리한다. PIN_CATEGORY_VIDEOPORT_VBI 를 지정할 필요는 없다.

지원 하는 필터. 캡춰 디바이스가 Windows Driver Model (WDM) 드라이버를 사용하는 경우, 그래프는,WDM 비디오 캡춰 필터의 업 스트림에 있는 TV 튜너 필터나아날로그 비디오 크로스바 필터등의 특정의 필터를 필요로 하는 일이 있다. 이 메소드가 올바르게 스트림의 렌더링을 실시하면, 메소드는, 필요하게 되는 모든 WDM 필터를 그래프에 삽입한다. 메소드는, 캡춰 필터의 입력 핀에 문의해, 입력 핀이 지원 하는 미디어를 판별해, 그러한 미디어를 적합하는 필터에 접속한다.

파일 소스. 이 메소드의 본래의 목적은 캡춰 그래프의 생성이지만, 이 메소드는 파일의 트랜스 코드나 재압축에도 사용할 수 있다. 이하의 설명에서는, 파일에 최대에서도 1 개의 비디오 스트림과 1 개의 오디오 스트림 또는 1 개의 인터리브 스트림이 포함되어 있는 것으로 한다. 그 이외의 조건에서는, 메소드는 올바르게 기능하지 않는다. 파일 소스의 출력 핀은 1 개이므로,pCategory 와 pType 를 NULL 로 설정한다. 1 회는 비디오 스트림을 렌더링 하기 위해서, 이제(벌써) 1 회는 오디오 스트림을 렌더링 하기 위해서, 합계 2 회 메소드를 호출한다. 최초의 호출에서는, 소스 필터가 퍼서 필터에 접속되어 퍼서 필터의 출력 핀안의 1 개가 렌더링 된다. 2 번째의 호출에서는, 퍼서의 나머지의 출력 핀이 렌더링 된다. 1 개의 스트림을 압축해, 이제 1 개의 스트림을 압축하지 않는 경우는, 반드시 최초의 호출로 압력 필터 (pfCompressor 파라미터)를 지정하는 것. 최초의 호출로 pfCompressor 를 NULL 로 하면(자), 메소드는 비디오 스트림을 렌더링 하는 일도, 오디오 스트림을 렌더링 하는 일도 있다. 자세한 사용예에 대해서는, 「AVI 파일의 재압축」을 참조할것.

ICaptureGraphBuilder2::SetFiltergraph

ICaptureGraphBuilder2 인터페이스

캡춰 그래프 빌더가 사용하는 필터 그래프를 지정한다.

구문

HRESULT SetFiltergraph(
    IGraphBuilder *pfg
);

파라미터

pfg
[in] 필터 그래프의 IGraphBuilder 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 설정되는 값은 다음과 같다.

E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | 예기치 못한 에러.

주의

이 메소드를 호출하지 않는 경우는, 캡춰 그래프 빌더가, 필요한 때에 자동적으로 필터 그래프를 생성 한다. 캡춰 그래프 빌더가 이미 필터 그래프를 갖추고 있는 경우, 이 메소드는 E_UNEXPECTED 를 돌려준다.

ICaptureGraphBuilder2::SetOutputFileName

ICaptureGraphBuilder2 인터페이스

필터 그래프의 파일 라이팅 섹션을 생성 한다.

구문

HRESULT SetOutputFileName(
    const GUID *pType,
    LPCOLESTR lpwstrFile,
    IBaseFilter **ppf,
    IFileSinkFilter **pSink
);

파라미터

pType
[in] 출력의 미디어 서브 타입 혹은 멀티플렉서 필터 또는 파일 라이터 필터의 클래스 식별자 (CSLID)를 나타내는 GUID 에의 포인터. 지정하는 미디어 서브 타입은, 다음의 언젠가가 아니면 안된다.
MEDIASUBTYPE_Avi | AVI (Audio-Video Interleaved)
MEDIASUBTYPE_Asf | ASF (Advanced Streaming Format)
lpwstrFile
[in] 출력 파일명이 저장 된 Unicode™ 캐릭터 라인에의 포인터.
ppf
[out] 멀티플렉서의 IBaseFilter 인터페이스를 받는 포인터의 주소.
pSink
[out] 파일 라이터의 IFileSinkFilter 인터페이스를 받는 포인터의 주소. NULL 의 경우가 있다.

반환값

HRESULT 값을 돌려준다. 설정되는 값은 다음과 같다.
S_OK | 성공.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.

주의

이 메소드는, 멀티플렉서와 File 라이터 필터를 필터 그래프에 삽입한다. 또, 이 메소드는,IFileSinkFilter::SetFileName 를 호출해 출력 파일명을 설정한다.

ppf 파라미터에 의해 돌려주어지는 멀티플렉서 필터에의 포인터를,RenderStream 메소드의 pfRenderer 파라미터로서 사용할 수 있다.

메소드가 성공하면(자),ppf 파라미터에 의해 돌려주어지는 IBaseFilter 인터페이스에, 미해결의 참조 카운트가 남는다. 메소드가 성공해,pSink 가 NULL 가 아닌 경우는,IFileSinkFilter 인터페이스에도 미해결의 참조 카운트가 남는다. 어느 인터페이스도, 사용한 다음에, 반드시 해방하는 것.


IConfigAviMux 인터페이스

IConfigAviMux 인터페이스는,AVI 멀티플렉서 필터가 디스크에 파일을 기입하는 방법을 제어한다. 현재, Microsoft® DirectShow® 는, AVI 멀티플렉서 필터의 프로퍼티 페이지를 통해서 이 인터페이스를 공개하고 있어, 이것을 이용해, 마스터 스트림과 호환 인덱스를 설정할 수 있다.

IConfigAviMux 는, 구버젼의 Video for Windows® AVI (Audio-Video Interleaved) 인덱스 포맷 (idx1) 및 1 GB 를 넘는 파일 사이즈에 대응하는 확장 AVI 2.0 인덱스 포맷 (indx)과 하위 호환성을 가지고 있다. IConfigAviMux::SetOutputCompatibilityIndex 메소드 및 IConfigAviMux::GetOutputCompatibilityIndex 메소드를 사용해, 호환 인덱스의 설정 및 취득을 실시한다. AVI 2.0 의 상세한 것에 대하여는, 「AVI 2.0 파일 포맷 확장」을 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IConfigAviMux 메소드 | 설명
SetMasterStream | 파일이 디스크에 보존된 후, 다른 스트림을 동기 시킬 때의 기준이 되는 마스터 스트림을 설정한다.
GetMasterStream | 파일이 기입해진 후, 다른 스트림을 동기 시킬 때의 기준이 되는 마스터 스트림을 취득한다.
SetOutputCompatibilityIndex | 멀티플렉서가 보존하는 파일의 AVI 인덱스 포맷을 설정한다.
GetOutputCompatibilityIndex | 멀티플렉서가 기입하는 파일의 AVI 인덱스 포맷을 취득한다.

IConfigAviMux::GetMasterStream

IConfigAviMux 인터페이스

파일이 기입해진 후, 다른 스트림을 동기 시킬 때의 기준이 되는 마스터 스트림을 취득한다.

구문

HRESULT GetMasterStream(
  LONG *pStream
  );

파라미터

pStream
[out] 마스터 스트림에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

오디오 샘플링 레이트와 비디오 frame rate와의 사이에 발생하는 캡춰 드리프트를 없게 하기 위해서, 큰 파일을 캡춰 하면나무는 오디오/비디오 일체형 카드를 사용하는 것을 추천 한다.

참조

IConfigAviMux::SetMasterStream

IConfigAviMux::GetOutputCompatibilityIndex

IConfigAviMux 인터페이스

멀티플렉서가 기입하는 파일의 AVI 인덱스 포맷을 취득한다.

구문

HRESULT GetOutputCompatibilityIndex(
  BOOL *pfOldIndex
  );

파라미터

pfOldIndex
[out] 인덱스 포맷을 나타내는 값에의 포인터. AVI 1.0 (idx1) 인덱스 포맷 또는 AVI 2.0 (indx) 인덱스 포맷이 설정되어 있는 경우는 TRUE 를 돌려주어, AVI 2.0 (indx) 인덱스 포맷만이 설정되어 있는 경우는 FALSE 를 돌려준다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

SetOutputCompatibilityIndex

IConfigAviMux::SetMasterStream

IConfigAviMux 인터페이스

파일이 디스크에 보존된 후, 다른 스트림을 동기 시킬 때의 기준이 되는 마스터 스트림을 설정한다.

구문

HRESULT SetMasterStream(
  LONG iStream
  );

파라미터

iStream
[in] 마스터 입력 스트림. 무효로 할 때는 –1 로 설정한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

다른 오디오 캡춰 카드와 비디오 캡쳐 카드를 사용하고 있는 경우는, 캡춰 시나리오내의 다양한 스트림이 다양한 레이트로 캡춰 될 가능성이 있다. 이 메소드에서는, 마스터 스트림을 지정해, 다른 모든 스트림을 거기에 동기 시키는 것으로, frame rate 또는 오디오 샘플링 레이트를 조정해 레이트의 드리프트를 제거한다.

오디오 샘플링 레이트와 비디오 frame rate와의 사이에 발생하는 캡춰 드리프트를 없애기 위해서(때문에), 큰 파일을 캡춰 하면나무는 오디오/비디오 일체형 카드를 사용하는 것을 추천 한다.

참조

IConfigAviMux::GetMasterStream

IConfigAviMux::SetOutputCompatibilityIndex

IConfigAviMux 인터페이스

멀티플렉서가 보존하는 파일의 AVI 인덱스 포맷을 설정한다.

구문

HRESULT SetOutputCompatibilityIndex(
  BOOL fOldIndex
  );

파라미터

fOldIndex
[in] AVI 인덱스 포맷을 지정하는 값. TRUE 는 AVI 1.0 (idx1) 인덱스 포맷 또는 AVI 2.0 (indx) 인덱스 포맷의 어느쪽이든을 나타내, FALSE 는 AVI 2.0 (indx) 인덱스 포맷만을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

DirectShow 는, Video for Windows® AVI 인덱스 포맷 (idx1)과 하위 호환성을 가지고 있는 것 외에 확장 AVI 2.0 인덱스 포맷 (indx)도 지원 하고 있어, 이 메소드에서는 그것을 지정할 수 있다. AVI 2.0 인덱스 포맷을 이용 하면, AVI 파일 사이즈의 확대 (1 GB 를 넘는다), 계층적 인덱스 붙여 파일의 증분 추가, 및 디스크 시크의 삭감이 가능하게 된다. AVI 2.0 의 상세한 것에 대하여는, 「AVI 2.0 파일 포맷 확장」을 참조할것.

참조

IConfigAviMux::GetOutputCompatibilityIndex


IConfigInterleaving 인터페이스

IConfigInterleaving 인터페이스는 AVI 멀티플렉서 필터에 이행 된다. 이 인터페이스는, 파일을 디스크에 기입하는 방법을 제어해, 주기 파라미터나프리로르 파라미터등의인터리브 구성 정보를 설정하는.

이 인터페이스는, 오디오 샘플 및 비디오 프레임을 디스크에 보존하는 방법을 지정하는 InterleavingMode 열거형을 사용한다. 오쏘링을 즉시 실시하는지, 다음에 실시할까에 응해, INTERLEAVE_NONE 으로부터 INTERLEAVE_FULL 까지의 캡춰 인터리브 설정이 있다.

캡춰 링을 처리하는 비디오 오쏘링 어플리케이션은, 오디오 샘플 및 비디오 프레임을 디스크에 보존하는 방법을 제어할 필요가 있을 때, 이 인터페이스를 사용할 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IConfigInterleaving 메소드 | 설명
put_Mode | 인터리브 품질을 지정하는 것으로써, 오디오 샘플과 비디오 프레임을 디스크에 보존하는 방법을 설정한다.
get_Mode | 인터리브 품질의 설정을 취득한다.
put_Interleaving | 인터리브의 오디오 프리로르타임과 주기를 설정한다.
get_Interleaving | 인터리브의 오디오프리로르타임과 주기를 취득한다.

IConfigInterleaving::get_Interleaving

IConfigInterleaving 인터페이스

인터리브의 오디오프리로르타임과 주기를 취득한다.

구문

HRESULT get_Interleaving(
    REFERENCE_TIME *prtInterleave,
    REFERENCE_TIME *prtPreroll );

파라미터

prtInterleave
[out] 파일내의 스트림의 주기에의 포인터 (100 나노초단위).
prtPreroll
[out] 오디오프리로르에의 포인터 (100 나노초단위).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IConfigInterleaving::put_Interleaving

IConfigInterleaving::get_Mode

IConfigInterleaving 인터페이스

인터리브 품질의 설정을 취득한다.

구문

HRESULT get_Mode(
    InterleavingMode *pMode );

파라미터

pMode
[out] InterleavingMode 열거형으로 지정되는 인터리브 품질의 설정에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

인터리브 모드는,InterleavingMode 열거형에 의해 지정되어IConfigInterleaving::put_Mode 메소드에 의해 설정된다.

참조

IConfigInterleaving::put_Mode

IConfigInterleaving::put_Interleaving

IConfigInterleaving 인터페이스

인터리브의 오디오프리로르타임과 주기를 설정한다.

구문

HRESULT put_Interleaving(
    const REFERENCE_TIME *prtInterleave,
    const REFERENCE_TIME *prtPreroll );

파라미터

prtInterleave
[in] 파일내의 스트림의 주기에의 포인터 (100 나노초단위).
prtPreroll
[in] 오디오프리로르에의 포인터 (100 나노초단위).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

배포용의 파일의 오쏘링을 실시할 때는, 오디오프리로르를 750 밀리 세컨드로 하는 것을 추천 한다.

prtInterleave 의 디폴트값은 1000 밀리 세컨드이다. 다만, 이 값은 조정할 수 있다. 수치를 작게 하는 만큼, 파일이 커진다.

참조

IConfigInterleaving::get_Interleaving

IConfigInterleaving::put_Mode

IConfigInterleaving 인터페이스

인터리브 품질을 지정하는 것으로써, 오디오 샘플과 비디오 프레임을 디스크에 보존하는 방법을 설정한다.

구문

HRESULT put_Mode(
    InterleavingMode mode );

파라미터

mode
[in] InterleavingMode 열거형으로 지정되는 인터리브 품질의 설정.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

다음에 오쏘링을 실시하는 경우, 완전한 인터리브 오쏘링 품질을 필요로 하는 어플리케이션에서는, INTERLEAVE_FULL, INTERLEAVE_CAPTURE, 및 INTERLEAVE_NONE 의 설정을 지정할 필요가 있다.

참조

IConfigInterleaving::get_Mode


ICreateDevEnum 인터페이스

지정된 필터 카테고리내의 필터 및 하드웨어 디바이스의 리스트의 열거자를 생성 한다. 돌려주어지는 열거자는,IEnumMoniker 인터페이스를 지원 한다.

시스템 디바이스 열거자는 이 인터페이스를 공개한다. 같은 필터가 복수의 하드웨어 디바이스를 지원 하고 있는 경우에서도, 이 열거자는, 개개의 하드웨어 디바이스를 구별한다.

어플리케이션은 이 인터페이스를 사용해, 하드웨어 디바이스에 대응하는 필터의 인스턴스를 찾아낼 수가 있다. 우선, 시스템 디바이스 열거자의 인스턴스를 생성 해, 다음에, 그것을 사용해 특정의 카테고리의 디바이스용의 열거자를 생성 한다. 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것.

열거자의 사용법의 상세한 것에 대하여는, Platform SDK 의 문서의 「IEnumXXXX」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
ICreateDevEnum 메소드 | 설명
CreateClassEnumerator | 지정된 카테고리의 클래스 열거자를 생성 한다.

ICreateDevEnum::CreateClassEnumerator

ICreateDevEnum 인터페이스

지정된 타입의 오브젝트의 열거자를 생성 한다.

구문

HRESULT CreateClassEnumerator(

  REFCLSID clsidDeviceClass,

  IEnumMoniker **ppEnumMoniker,

  DWORD dwFlags

  );

파라미터

clsidDeviceClass
[in] 열거하는 디바이스의 타입을 지정하는 REFCLSID 값. ( 「필터 카테고리」를 참조할것. )
ppEnumMoniker
[out] 새로운 클래스 열거자에 의해 이행 되는 Win32 IEnumMoniker (또는 파생) 인터페이스에의 포인터의 주소.
dwFlags
[in] 예약이 끝난 상태. 0 이 아니면 안된다.

반환값

다음의 몇개의 값을 돌려준다.
NOERROR | 성공.
S_OK | 성공.
E_OUTOFMEMORY | 클래스 열거자를 생성 하는데 충분한 메모리를 이용할 수 없다.
S_FALSE | clsidDeviceClass 에 의해 지정된 카테고리가 존재하지 않는다.

주의

디바이스가 발견되지 않는 경우, 메소드는, 요소의 수가 제로의 모니카를 돌려주는 대신에, 모니카를 돌려주지 않는다.

새로운 클래스 열거자는, 이 메소드를 호출한 클래스와 같은 프로세스로 동작하는 비집성 오브젝트이다.


IDDrawExclModeVideo 인터페이스

IDDrawExclModeVideo 인터페이스는오버레이 믹서 필터에 의해 이행 된다. 이 인터페이스를 이용 하면, Microsoft® DirectDraw® 배타 풀 스크린 모드가 되어 있는 동안에서도 비디오를 재생할 수 있다. 게임 어플리케이션은, DirectDraw 를 배타 풀 스크린 모드로 사용하면서 비디오 재생을 계속할 수가 있다. 예를 들어, 백그라운드에서 비디오를 재생하면서, 그 위에 그래픽을 태울 수가 있다. 어플리케이션은, DirectDraw 오브젝트와프라이머리 표면을 건네주어, 그것들이 필터 그래프의오버레이 믹서 필터에게 건네진다.

DVD 그래프 빌더 오브젝트는, DirectDraw 배타 풀 스크린 모드가 되어 있는 동안,IDDrawExclModeVideo 를 사용해 DVD 컨텐츠를 재생한다. 이 인터페이스를 단독으로 사용해, 게임내에서 MPEG-1 비디오 또는 AVI 비디오를 재생할 수도 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDDrawExclModeVideo 메소드 | 설명
SetDDrawObject | 이 이후의 드로잉(Drawing)에 사용되는 DirectDraw 오브젝트를 설정한다.
GetDDrawObject | 오버레이 믹서가 사용하고 있는 DirectDraw 오브젝트를 취득한다.
SetDrawParameters | 원의 비디오의 어느 부분을 화면의 어디에 표시하는지를 지정한다.
SetDDrawSurface | 이 이후의 드로잉(Drawing)에 사용되는 DirectDraw 표면을 설정한다.
GetDDrawSurface | 오버레이 믹서가 사용하고 있는 DirectDraw 표면을 취득한다.
GetNativeVideoProps | 오버레이 믹서의 프라이머리 스트림의 폭, 높이, 및 어스펙트비(가로세로 비율)을 취득한다.
SetCallbackInterface | 오버레이 믹서에의 콜백 인터페이스를 지정해, 호출측 어플리케이션이 비디오의 재생중에 표시의 조정에 관한 통지를 받아들이도록(듯이) 한다.

IDDrawExclModeVideo::GetDDrawObject

IDDrawExclModeVideo 인터페이스

오버레이 믹서 필터가 사용하고 있는 DirectDraw 오브젝트를 취득한다.

구문

HRESULT GetDDrawObject(
    LPDIRECTDRAW *pDDrawObject,
    LPBOOL *pbUsingExternal
);

파라미터

pDDrawObject
[out] 오버레이 믹서가 사용하고 있는 IDirectDraw 인터페이스에의 포인터의 주소.
pbUsingExternal
[out] 오버레이 믹서가 SetDDrawObject 로 지정되고 있는 DirectDraw 오브젝트를 사용하고 있을지 어떨지를 나타내는 값에의 포인터의 주소. 오버레이 믹서가 SetDDrawObject 로 지정되고 있는 DirectDraw 오브젝트를 사용하고 있는 경우는 TRUE, 그 이외의 경우는 FALSE 가 된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재 이행 되고 있는 Microsoft® DirectShow® 는, 다음의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 인수가 무효.
DirectDraw 에러 코드 | 지정된 표면을 오버레이 믹서상에서 설정하려고 했을 때에 DirectDraw 에러가 발생했다.

주의

필터 그래프가 DirectDraw 오브젝트를 설정하고 있지 않고, 오버레이 믹서가 아직 DirectDraw 오브젝트를 할당하지 않은 경우는,pDDrawObject 가 NULL 로 설정되어pbUsingExternal 가 FALSE 로 설정된다.

IDDrawExclModeVideo::GetDDrawSurface

IDDrawExclModeVideo 인터페이스

오버레이 믹서가 사용하고 있는 DirectDraw 표면을 취득한다.

구문

HRESULT GetDDrawSurface(
    LPDIRECTDRAWSURFACE *pDDrawSurface,
    LPBOOL *pdUsingExternal
);

파라미터

pDDrawSurface
[out] 오버레이 믹서가 사용하고 있는 IDirectDrawSurface 인터페이스에의 포인터의 주소.
pdUsingExternal
[out] 오버레이 믹서가 SetDDrawSurface 로 지정되고 있는 DirectDraw 표면을 사용하고 있을지 어떨지를 나타내는 불형의 값에의 포인터의 주소. 오버레이 믹서가 SetDDrawSurface 로 지정되고 있는 DirectDraw 표면을 사용하고 있는 경우는 TRUE, 그 이외의 경우는 FALSE 가 된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 인수가 무효.
DirectDraw 에러 코드 | 지정된 표면을 오버레이 믹서상에서 설정하려고 했을 때에 DirectDraw 에러가 발생했다.

주의

필터 그래프가 DirectDraw 표면을 설정하고 있지 않고, 오버레이 믹서가 아직 DirectDraw 표면을 할당하지 않은 경우는,pDDrawSurface 이 NULL 로 설정되어pbUsingExternal 가 FALSE 로 설정된다.

IDDrawExclModeVideo::GetNativeVideoProps

IDDrawExclModeVideo 인터페이스

오버레이 믹서의 프라이머리 스트림의 현재의 비디오의 사이즈와 어스펙트비(가로세로 비율)을 취득한다.

구문

HRESULT GetNativeVideoProps(
    LPDWORD *pdwVideoWidth,
    LPDWORD *pdwVideoHeight,
    LPDWORD *pdwPictAspectRatioX,
    LPDWORD *pdwPictAspectRatioY
);

파라미터

pdwVideoWidth
[out] 비디오의 폭에의 포인터의 주소.
pdwVideoHeight
[out] 비디오의 높이에의 포인터의 주소.
pdwPictAspectRatioX
[out] 어스펙트비(가로세로 비율)의 x 축에의 포인터의 주소.
pdwPictAspectRatioY
[out] 어스펙트비(가로세로 비율)의 y 축에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 인수가 무효.

주의

필터 그래프는,EC_VIDEO_SIZE_CHANGED 이벤트를 예기 해, 이벤트를 받으면(자), 이 메소드를 호출해 어스펙트비(가로세로 비율)과 위치를 조정할 필요가 있다.

IDDrawExclModeVideo::SetCallbackInterface

IDDrawExclModeVideo 인터페이스

오버레이 믹서의 콜백 인터페이스에의 포인터를 취득해, 호출측 어플리케이션이 비디오를 재생중에 표시의 조정에 관한 통지를 받아들이도록(듯이) 한다.

구문

HRESULT SetCallbackInterface(
    IDDrawExclModeVideoCallback *pCallback
    DWORD dwFlag
);

파라미터

pCallback
[out] IDDrawExclModeVideoCallback 인터페이스를 이행 하는 오브젝트에의 포인터. pCallback 가 NULL 의 경우는, 콜백 인터페이스가 NULL 로 설정되어 그 이후의 콜백은 행해지지 않는다. 전의 콜백 인터페이스가 있었을 경우는, 그 인터페이스가 해방되어 그 이후의 그 인터페이스에의 콜백은 행해지지 않는다. pCallback 가 NULL 이외의 값으로, 이 메소드가 S_OK 를 돌려주는 경우는,pCallback 가 가리키는 오브젝트의 참조 카운트가 인크리먼트(increment) 된다.
dwFlag
[in] 0 이 아니면 안된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 인수가 무효.

주의

어플리케이션은, 이 메소드를 사용해 오버레이의 사이즈, 위치, 칼라 키의 변경이 발생했을 때에 통지를 받아, 거기에 맞추어 비디오를 비표시로 하거나 표시하거나 재생의 시작시, 종료시, 또는 재생중에 비디오를 조정하거나 할 필요가 있다. 어플리케이션은, 이 메소드를 호출하는 것으로,IDDrawExclModeVideoCallback 인터페이스에 액세스 해, 그 인터페이스에의 포인터를 오버레이 믹서에 건네줄 수가 있다.

IDDrawExclModeVideo::SetDDrawObject

IDDrawExclModeVideo 인터페이스

이 이후의 드로잉(Drawing)에 사용되는 DirectDraw 오브젝트를 설정한다.

구문

HRESULT SetDDrawObject(
    LPDIRECTDRAW *pDDrawObject
);

파라미터

pDDrawObject
[in] 사용하는 오브젝트의 IDirectDraw 인터페이스에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 인수가 무효.
DirectDraw 에러 코드 | 지정된 표면을 오버레이 믹서상에서 설정하려고 했을 때에 DirectDraw 에러가 발생했다.

주의

게임 어플리케이션은, 이 메소드를 사용해, 자어플리케이션용으로 생성 한 DirectDraw 오브젝트를오버레이 믹서 필터에 공유시켜,SetDDrawSurface 로 설정되어 있는, 지정된 표면으로 비디오를 드로잉(Drawing) 할 수가 있다.

IDDrawExclModeVideo::SetDrawParameters

IDDrawExclModeVideo 인터페이스

원의 비디오의 어느 부분을 화면의 어디에 표시하는지를 지정한다.

구문

HRESULT SetDrawParameters(
    RECT *pSrcRect,
    RECT *pDestRect
);

파라미터

pSrcRect
[in] 원의 비디오의 RECT 구조체에의 포인터.
pDestRect
[in] 비디오가 화면의 어디에 표시되는지를 나타내는 RECT 에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

참조

IDDrawExclModeVideoCallback

IDDrawExclModeVideo::SetDDrawSurface

IDDrawExclModeVideo 인터페이스

이 이후의 드로잉(Drawing)에 사용되는 DirectDraw 표면을 지정한다.

구문

HRESULT SetDDrawSurface(
    LPDIRECTDRAWSURFACE *pDDrawSurface
);

파라미터

pDDrawSurface
[in] 사용하는 표면의 IDirectDrawSurface 인터페이스에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 인수가 무효.
DirectDraw 에러 코드 | 지정된 표면을 오버레이 믹서상에서 설정하려고 했을 때에 DirectDraw 에러가 발생했다.

주의

게임 어플리케이션은, 이 메소드를 사용해, 자어플리케이션용으로 생성 한 DirectDraw 표면을오버레이 믹서 필터에 공유시켜, 지정된 표면으로 비디오를 드로잉(Drawing) 할 수가 있다. 이 표면은,SetDDrawObject 로 지정된 오브젝트와 관련지을 수 있지 않으면 안 된다.


IDDrawExclModeVideoCallback 인터페이스

IDDrawExclModeVideoCallback 인터페이스를 이용 하면, 어플리케이션은, 오버레이의 위치, 사이즈, 표시/비표시 등에 관한 동기 통지를 취득해, 어플리케이션의 비디오의 표시/비표시, 사이즈, 위치를 조정할 수가 있다. 이것에 의해, 재생의 시작시, 종료시, 또는 도중에 칼라 키후들 다하고가 발생하는 것이 없어진다. 어플리케이션은, 이 인터페이스를 지원 하는 COM 오브젝트를 이행 할 필요가 있다.

IDDrawExclModeVideo 인터페이스를 사용하고 있어, (아마 상시) 콜백 정보를 필요로 하고 있는 경우는, 이 인터페이스를 이행 하는 것.

Microsoft® DirectShow® 오버레이 믹서 필터를 사용하고 있는 경우, 및, 보다 일반적으로는,IDDrawExclModeVideo 를 지원 하는 필터, 또는 어플리케이션이 적절한 타이밍에 칼라 키를 드로잉(Drawing) 할 수 있도록(듯이) 콜백을 생성할 필요가 있는 필터를 쓰고 있는 경우는, 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDDrawExclModeVideoCallback 메소드 | 설명
OnUpdateOverlay | 비디오의 오버레이 표면이 바뀌기 직전에 어플리케이션에 통지한다.
OnColorKeyChange | 칼라 키가 바뀌어, 어플리케이션이 새로운 칼라 키를 사용해 비디오에 그래픽스를 오버레이 할 수 있게 된 것을 어플리케이션에 통지한다.

IDDrawExclModeVideoCallback::OnColorKeyChange

IDDrawExclModeVideoCallback Interface

칼라 키가 바뀌어, 어플리케이션이 새로운 칼라 키를 사용해 비디오에 그래픽스를 오버레이 할 수 있게 된 것을 어플리케이션에 통지한다.

구문

HRESULT OnColorKeyChange (
    COLORKEY const *pKey,
    DWORD dwColor
);

파라미터

pKey
[out] 키 타입과 팔레트 인덱스가 저장 된 COLORKEY 구조체에의 포인터.
dwColor
[out] 현재의 디스플레이 모드가 8 비트로 팔레트화 되고 있는 경우는,pKey 에 의해 돌려주어지는 COLORKEY 의 8 비트 팔레트 인덱스를 나타내는 값. 그 이외의 경우는, 현재의 디스플레이 포맷의 픽셀 포맷으로 나타내는 칼라 키에 상당하는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
S_OK | 성공.
E_INVALIDARG | 파라미터안의 1 개가 무효이다.

IDDrawExclModeVideoCallback::OnUpdateOverlay

IDDrawExclModeVideoCallback 인터페이스

비디오의 오버레이 표면이 표시되기 직전, 비표시가 되기 직전, 사이즈를 바꾸기 직전, 또는 위치를 바꾸기 직전에 어플리케이션에 통지해, 어플리케이션이 거기에 맞추어 윈도우를 재드로잉(Drawing) 할 수 있도록(듯이) 한다.

구문

HRESULT OnUpdateOverlay(
    BOOL bBeforeChange,
    DWORD dwFlags,
    BOOL bOldVisible,
    LPRECT *prcSrcOld,
    LPRECT *prcDestOld,
    BOOL bNewVisible,
    LPRECT *prcSrcNew,
    LPRECT *prcDestNew,
);

파라미터

bBeforeChange
[in] 호출이 오버레이에 관련하는 변경전에 행해지는지, 다음에 행해지는지를 나타내는 불형의 값. TRUE 는 전에 행해지는 것을 나타내, FALSE 는 다음에 행해지는 것을 나타낸다.
dwFlags
[in] 무엇이 바뀌는지, 또는 바뀌었는지를 나타내는 AM_OVERLAY_NOTIFY_FLAGS 데이터형의 값.
bOldVisible
[in] 구윈도우가 표시되고 있는지 어떤지를 나타내는 불형의 값. TRUE 는 구윈도우가 표시되고 있는 것을 나타낸다.
prcSrcOld
[in] DirectDraw 표면의 낡은 소스의 위치를 나타내는 직사각형에의 포인터.
prcDestOld
[in] 오버레이 표면내의 직사각형의 낡은 표시 위치를 나타내는 직사각형에의 포인터.
bNewVisible
[in] 새로운 윈도우가 표시되고 있는지 어떤지를 나타내는 불형의 값. TRUE 는 새로운 윈도우가 표시되고 있는 것을 나타낸다.
prcSrcNew
[in] DirectDraw 표면의 새로운 소스의 위치를 나타내는 직사각형에의 포인터.
prcDestNew
[in] 오버레이 표면내의 직사각형의 새로운 표시 위치를 나타내는 직사각형에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
S_OK | 성공.
E_INVALIDARG | 무효인 파라미터.

주의

어플리케이션은, 오버레이에 관련하는 변경이 발생하기 전에 1 회, 발생한 후에 1 회, 이 메소드를 호출할 필요가 있다. 변경전에 행해지는 호출에서는, 어플리케이션이 이 메소드의 실행을 완료할 때까지 오버레이의 변경은 발생하지 않는다.


IDecimateVideoImage 인터페이스

IDecimateVideoImage 인터페이스는, 디코더 필터 위에의 데시 메이션을 지정한다. 데시 메이션 이란, 비디오 출력을 비디오 본래의 사이즈보다 작게 하는 것을 말한다.

어플리케이션은 이 인터페이스상에서 메소드를 호출해서는 안 된다. 오버레이 믹서 필터는, 이 인터페이스를 사용해 비디오 디코더의 비디오를 데시 메이션 한다.

비디오 출력을 데시 메이션 할 수 있는 디코더 필터는, 이 인터페이스를 지원 할 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDecimateVideoImage 메소드 | 설명
SetDecimationImageSize | 디코더가 어느 사이즈까지 출력 화면을 데시 메이션 하는지를 지정한다.
ResetDecimationImageSize | 디코더가 출력 화면을 데시 메이션 해선 안 되는 것 가리킨다.

IDecimateVideoImage::ResetDecimationImageSize

IDecimateVideoImage 인터페이스

디코더가 출력 화면을 데시 메이션 해선 안 되는 것 가리킨다.

구문

HRESULT ResetDecimationImageSize(void);

반환값

호출이 성공했는지, 실패했는지를 나타내는 HRESULT 값을 돌려준다.

IDecimateVideoImage::SetDecimationImageSize

IDecimateVideoImage 인터페이스

디코더가 어느 사이즈까지 출력 화면을 데시 메이션 하는지를 지정한다.

구문

HRESULT SetDecimationImageSize(
    long lWidth,
    long lHeight
);

파라미터

lWidth
[in] 비디오 화면의 폭 (픽셀 단위).
lHeight
[in] 비디오 화면의 높이 (픽셀 단위).

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

E_FAIL | 디코더가 데시 메이션을 실행할 수 없는, 또는 현재 실행하고 있는 데시 메이션을 중지할 필요가 있다.
S_OK | 디코더가 요구되고 있는 사이즈까지 비디오를 데시 메이션 할 수 있다.


IDeferredCommand 인터페이스

어플리케이션이 IQueueCommand 인터페이스를 사용해 전에 큐에 넣은 그래프 컨트롤 커멘드를 캔슬 또는 변경할 수 있도록(듯이) 한다.

어플리케이션은, 필터 그래프 매니저상에서 IQueueCommand 메소드를 호출하면,IDeferredCommand 인터페이스에의 포인터를 받는다. 어플리케이션은 이 인터페이스를 사용해, 커멘드를 캔슬 또는 연기하거나 커멘드로부터의 반환값을 취득하거나 할 수가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDeferredCommand 메소드 | 설명
Cancel | 어플리케이션이 전에 큐에 넣은 커멘드를 캔슬한다.
Confidence | 요구된 시간에 커멘드가 불려 갈 가능성을 나타내는 콘피덴스레벨을 취득한다.
Postpone | 커멘드의 새로운 호출시간을 지정한다.
GetHResult | 불려 간 커멘드로부터의 반환값을 취득한다.

IDeferredCommand::Cancel

IDeferredCommand 인터페이스

어플리케이션이 전에 큐에 넣은 커멘드를 캔슬한다.

구문

HRESULT Cancel(void);

반환값

성공했을 경우는, S_OK 를 돌려준다. 요구가 이미 캔슬되고 있는 경우는, VFW_E_ALREADY_CANCELLED 를 돌려준다.

IDeferredCommand::Confidence

IDeferredCommand 인터페이스

요구된 시간에 커멘드가 불려 갈 가능성을 나타내는 콘피덴스레벨을 취득한다.

이 메소드는 이행 되지 않고, E_NOTIMPL 를 돌려준다.

구문

HRESULT Confidence(
    LONG *pConfidence
);

파라미터

pConfidence
0 에서 100 의 단계에서 나타내지는 콘피덴스레벨을 받는 변수에의 포인터.

반환값

E_NOTIMPL 를 돌려준다.

IDeferredCommand::GetHResult

IDeferredCommand 인터페이스

불려 간 커멘드로부터의 반환값을 취득한다.

구문

HRESULT GetHResult(
    HRESULT *phrResult
);

파라미터

phrResult
HRESULT 값을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 성공.
E_ABORT | 커멘드가 아직 불려 가지 않았다.
E_POINTER | NULL 포인터 인수.

IDeferredCommand::Postpone

IDeferredCommand 인터페이스

커멘드의 새로운 호출시간을 지정한다.

구문

HRESULT Postpone(
    REFTIME newtime
);

파라미터

newtime
커멘드를 호출하는 새로운 시간.

반환값

성공했을 경우는, S_OK 를 돌려준다. 요구된 시간이 이미 지나고 있는 경우는, VFW_E_TIME_ALREADY_PASSED 를 돌려준다.


IDirectDrawVideo 인터페이스

IDirectDrawVideo 인터페이스는비디오 렌더러에 이행 되어DirectDraw 표면과 하드웨어 기능에 관한 정보를 어플리케이션에 제공한다. 어플리케이션은 이 인터페이스를 사용해, 비디오 렌더러가 이용하는 DirectDraw 기능을 제어한다. 예를 들어, 비디오 렌더러로 하드웨어 오버레이를 이용하지 않는 것이 확실하면,SetSwitches 메소드를 사용해, 하드웨어 오버레이의 사용을 무효로 할 수 있다.

주 : 이 인터페이스를 사용해, 비디오 렌더러에 DirectDraw 의 특정의 기능을 강제적으로 사용시킬 수 없다. 가능한 것은, 비디오 렌더러가 특정의 기능을 사용하지 않게 하는 것 뿐이다.

이 인터페이스는, 일부가 IDirectDraw 인터페이스와 중복 한다. 다만, 이 인터페이스에서는, DirectDraw 프로바이더를 직접 호출하지 않아도, 같은 정보에 간단하게 액세스 할 수 있다.

비디오 렌더러는 접속될 때까지 DirectDraw 를 로드하지 않고, 같이 DirectDraw 는 렌더러의 접속이 절단 될 때까지 언로드되지 않는다. 렌더러가 비디오 재생에 사용하는 DirectDraw 표면을 할당하면(자), 어플리케이션은 그것을 기술하는 DDSURFACEDESC 구조체를 취득할 수 있다. 렌더러는 DDSURFACEDESC 구조체에의 포인터를 건네주는 것에 의해, 현재의 표면에 관한 상세한 데이터를 구조체에 저장 한다. DirectDraw 가 로드되어 있지 않은 경우, 렌더러는, E_FAIL 를 돌려준다. 렌더러가 DCI (DirectDraw 의 전의 버젼)를 사용하고 있는 경우,DDSURFACEDESC 구조체에 데이터는 저장 되지 않고, 호출은 S_FALSE 를 돌려준다. 렌더러가 사용하는 DCI 표면의 타입은,프라이머리 표면에 한정된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDirectDrawVideo 메소드 | 설명
GetCaps | 하드웨어 기능이 저장 된 DirectDraw 정의 DDCAPS 구조체를 취득한다.
GetEmulatedCaps | 에뮤레이트 기능이 저장 된 DirectDraw 정의 DDCAPS 구조체를 취득한다.
CanUseOverlayStretch | 렌더러가 오버레이 제한을 체크할지 어떨지를 결정한다.
CanUseScanLine | 렌더러가 드로잉(Drawing) 할 경우에 현재의 주사선을 체크할지 어떨지를 결정한다.
GetDirectDraw | IDirectDraw 인터페이스를 취득한다.
GetFourCCCodes | 멀티미디어 포맷 타입 FOURCC DWORD 를 취득한다.
GetSurfaceDesc | 사용되고 있는 DirectDraw 표면의 설명을 취득한다.
GetSurfaceType | 실제의 표면 타입을 취득한다.
GetSwitches | 렌더러를 사용할 수 있는 표면 타입을 취득한다.
SetDefault | 현재의 프로퍼티 설정을 글로벌 디폴트로 한다.
SetDirectDraw | 로드 되고 있는 드라이버에 IDirectDraw 인터페이스를 건네준다.
SetSwitches | 렌더러를 사용할 수 있는 표면 타입을 설정한다.
UseOverlayStretch | 렌더러가 오버레이 확대 제한을 체크할 필요가 있을지 어떨지를 결정한다.
UseScanLine | 렌더러가 비디오를 드로잉(Drawing) 할 경우에 현재의 주사선을 체크할 필요가 있을지 어떨지를 결정한다.
UseWhenFullScreen | 풀 스크린 모드에 바뀔 때 DirectShow 가 디스플레이 모드를 변경할 필요가 있을지 어떨지를 결정한다.
WillUseFullScreen | 풀 스크린 모드에 바뀔 때 DirectShow 가 디스플레이 모드를 변경할지 어떨지를 결정한다.

IDirectDrawVideo::CanUseOverlayStretch

IDirectDrawVideo 인터페이스

렌더러가 오버레이 제한을 체크할지 어떨지를 결정한다.

구문

HRESULT CanUseOverlayStretch(
    long *UseOverlayStretch
);

파라미터

UseOverlayStretch
렌더러가 오버레이 제한을 사용할 수 있을지 어떨지를 나타내는 값에의 포인터. OATRUE 는 렌더러가 오버레이 제한을 체크하는 것을 나타내, OAFALSE 는 체크하지 않는 것을 나타낸다.

반환값

HRESULT 값을 돌려준다.

주의

오버레이 확대 기능에 대해서는, 「IDirectDrawVideo::UseOverlayStretch 」를 참조할것.

IDirectDrawVideo::CanUseScanLine

IDirectDrawVideo 인터페이스

렌더러가 드로잉(Drawing) 할 경우에 현재의 주사선을 체크할지 어떨지를 결정한다.

구문

HRESULT CanUseScanLine(
    long *UseScanLine
);

파라미터

UseScanLine
렌더러가 주사선 정보를 사용할지 어떨지를 나타내는 값에의 포인터. OATRUE 는 렌더러가 드로잉(Drawing) 할 경우에 현재의 주사선을 체크하는 것을 나타내, OAFALSE 는 체크하지 않는 것을 나타낸다.

반환값

HRESULT 값을 돌려준다.

주의

DirectShow 비디오 렌더러로 주사선 검출을 사용하는 방법에 대해서는, 「IDirectDrawVideo::UseScanLine 」를 참조할것.

IDirectDrawVideo::GetCaps

IDirectDrawVideo 인터페이스

하드웨어 기능이 저장 된 DirectDraw 정의 DDCAPS 구조체를 취득한다.

구문

HRESULT GetCaps(
    DDCAPS *pCaps
);

파라미터

pCaps
하드웨어 기능이 저장 되고 있는 DDCAPS 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

렌더러가 DirectDraw 를 로드하지 않은 경우, 이 메소드는 E_FAIL 를 돌려준다.

IDirectDrawVideo::GetDirectDraw

IDirectDrawVideo 인터페이스

IDirectDraw 인터페이스를 취득한다.

구문

HRESULT GetDirectDraw(
    LPDIRECTDRAW *ppDirectDraw
);

파라미터

ppDirectDraw
IDirectDraw 인터페이스에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

주의

어플리케이션이 DirectDraw 를 로드하고 싶지만, 렌더러를 표면을 할당할 수 있도록(듯이) 만약 싶은 경우, 어플리케이션은, 렌더러에 DirectDraw 를 로드 시킨 후, 이 메소드를 사용해, 참조가 인크리먼트(increment) 된 DirectDraw 에의 인터페이스를 취득할 수가 있다. 어플리케이션은, 돌려주어진 인터페이스를 사용한 후, 해방할 필요가 있다.

IDirectDrawVideo::GetEmulatedCaps

IDirectDrawVideo 인터페이스

에뮤레이트 기능이 저장 된 DirectDraw 정의 DDCAPS 구조체를 취득한다.

구문

HRESULT GetEmulatedCaps(
    DDCAPS *pCaps
);

파라미터

pCaps
에뮤레이트 기능이 저장 되고 있는 DDCAPS 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 렌더러가 DirectDraw 를 로드하지 않은 경우, 이 메소드는 E_FAIL 를 돌려준다.

IDirectDrawVideo::GetFourCCCodes

IDirectDrawVideo 인터페이스

멀티미디어 포맷 타입을 취득한다.

구문

HRESULT GetFourCCCodes(
    DWORD *pCount,
    DWORD *pCodes
);

파라미터

pCount
pCodes 배열내의 FOURCC 코드의 수에의 포인터.
pCodes
이전 Microsoft 멀티미디어 타입으로 사용되고 있던 DWORD 미디어 태그의 배열에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

최초의 Microsoft® Windows® multimedia API 에서는, 미디어 타입에 FOURCC 코드로 불리는 4 개의 8 비트 문자로부터 생성 되는 32 비트값의 태그를 붙일 수 있고 있었다. FOURCC 코드는 일의이기 (위해)때문에,FOURCC 를 나타내는 40 억개의 GUID 를 할당하는 것에 의해, 1 대 1 의 매핑이 가능했다.

이 메소드는, 현재의 디스플레이 드라이버를 지원 할 수 있는 FOURCC 코드를 취득한다. 이용 가능한 FOURCC 코드의 수를 취득하려면 , 유효한 pCount 포인터를 지정해,pCodes 를 NULL 로 설정해 메소드를 호출한다. 그 경우,pCount 변수에는, 이용 가능한 FOURCC 코드의 수가 저장 된다. 다음에, 어플리케이션은, 취득된 FOURCC 코드의 수에 대응하는 충분한 수의 DWORD 값을 할당해,pCodes 로 배열 포인터를 지정해, 메소드를 다시 호출한다.

IDirectDrawVideo::GetSurfaceDesc

IDirectDrawVideo 인터페이스

현재의 DirectDraw 표면을 기술하는 DDSURFACEDESC 구조체를 취득한다.

구문

HRESULT GetSurfaceDesc(
    DDSURFACEDESC *pSurfaceDesc
);

파라미터

pSurfaceDesc
현재의 DirectDraw 표면을 기술하는 DDSURFACEDESC 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 할당할 수 있고 있는 표면이 없는 경우, 이 메소드는 E_FAIL 를 돌려준다. DCI 프라이머리 표면이 사용되고 있는 경우,DDSURFACEDESC 구조체에는 데이터가 저장 되지 않고, 호출은 S_FALSE 를 돌려준다.

주의

표면은 렌더러가 포즈 하고 있을 때만 할당할 수 있다. 렌더러가 포즈 한 후, 정지했을 때에 표면을 해방할 수 없다.

IDirectDrawVideo::GetSurfaceType

IDirectDrawVideo 인터페이스

실제의 표면 타입을 DirectShow DirectDraw Surface (AMDDS) 정의로서 취득한다.

구문

HRESULT GetSurfaceType(
    DWORD *pSurfaceType
);

파라미터

pSurfaceType
다음의 AMDDS 정의의 리스트로부터 선택된 1 비트 설정이 저장 되고 있는필드에의 포인터.
AMDDS_NONE | DCI/DirectDraw 를 사용하지 않는다.
AMDDS_DCIPS | DCI 프라이머리 표면을 사용한다.
AMDDS_PS | DirectDraw 프라이머리 표면을 사용한다.
AMDDS_RGBOVR | RGB 오버레이 표면.
AMDDS_YUVOVR | YUV 오버레이 표면.
AMDDS_RGBOFF | RGB 오프 스크린 표면.
AMDDS_YUVOFF | YUV 오프 스크린 표면.
AMDDS_RGBFLP | RGB 후립핑서페스.
AMDDS_YUVFLP | YUV 후립핑서페스.
AMDDS_ALL | 상기 모든 플래그.
AMDDS_DEFAULT | 이용 가능한 표면 모든 것을 사용한다.
AMDDS_YUV | (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP).
AMDDS_RGB | (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP).
AMDDS_PRIMARY | (AMDDS_DCIPS | AMDDS_PS).

반환값

HRESULT 값을 돌려준다.

주의

DDSURFACEDESC 구조체를 보았을 뿐은, 사용되고 있는 표면의 종류를 모르는 것이 있다. 따라서, 어플리케이션은 GetSurfaceType 를 호출해, 표면 타입을 취득할 수가 있다. 필드에는, 위의 AMDDS 정의의 리스트로부터 선택된 1 비트 설정이 저장 된다.

IDirectDrawVideo::GetSwitches

IDirectDrawVideo 인터페이스

렌더러를 사용할 수 있는 표면 타입을 취득한다.

구문

HRESULT GetSwitches(
    DWORD *pSwitches
);

파라미터

pSwitches
다음의 DirectShow DirectDraw Surface (AMDDS) 표면 타입안의 1 개 이상이 포함된 비트 마스크에의 포인터.
AMDDS_NONE | DCI/DirectDraw 를 사용하지 않는다.
AMDDS_DCIPS | DCI 프라이머리 표면을 사용한다.
AMDDS_PS | DirectDraw 프라이머리 표면을 사용한다.
AMDDS_RGBOVR | RGB 오버레이 표면.
AMDDS_YUVOVR | YUV 오버레이 표면.
AMDDS_RGBOFF | RGB 오프 스크린 표면.
AMDDS_YUVOFF | YUV 오프 스크린 표면.
AMDDS_RGBFLP | RGB 후립핑서페스.
AMDDS_YUVFLP | YUV 후립핑서페스.
AMDDS_ALL | 상기 모든 플래그.
AMDDS_DEFAULT | 이용 가능한 표면 모든 것을 사용한다.
AMDDS_YUV | (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP).
AMDDS_RGB | (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP).
AMDDS_PRIMARY | (AMDDS_DCIPS | AMDDS_PS).

반환값

HRESULT 값을 돌려준다.

IDirectDrawVideo::SetDefault

IDirectDrawVideo 인터페이스

현재의 프로퍼티 설정을 글로벌 디폴트로 한다.

구문

HRESULT SetDefault(void);

반환값

HRESULT 값을 돌려준다.

주의

IDirectDrawVideo 를 통해서 설정되는 모든 프로퍼티는, 그 특정의 인스턴스에 고유의 프로퍼티이다. 이 메소드를 호출하는 것에 의해,IDirectDrawVideo 의 이 인스턴스에 대해서 설정되어 있는 프로퍼티를, 이 인터페이스의 모든 DirectShow 인스턴스의 글로벌 디폴트로 한다. 메소드가 불려 간 후는, 다른 DirectShow 필터 그래프를 기동하거나 컴퓨터를 재기동하거나 해도, 현재의 프로퍼티 설정이 인계된다.

IDirectDrawVideo::SetDirectDraw

IDirectDrawVideo 인터페이스

로드 되고 있는 드라이버에 IDirectDraw 인터페이스를 건네준다.

구문

HRESULT SetDirectDraw(
    LPDIRECTDRAW pDirectDraw
);

파라미터

pDirectDraw
건네받는 IDirectDraw 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

어플리케이션은 SetDirectDraw 를 호출해 NULL 를 건네주는 것으로,SetDirectDraw 를 통해서 전에 건네준 DirectDraw 인터페이스를 렌더러에 해방시킬 수가 있다. 그러나, 렌더러는, 렌더러의 접속이 절단 될 때까지, 그 DirectDraw 인터페이스를 계속 사용한다. 따라서, NULL 파라미터를 지정해 SetDirectDraw 를 호출해도, 렌더러가 즉시 인터페이스의 사용을 그만두는 것은 아니다.

이 메소드가 만들어진 이유는, DirectX 7.0 이전의 DirectDraw 의 버젼에서는, 1 개의 프로세스에 대해 1 개의 IDirectDraw 의 인스턴스 밖에 로드할 수 없었으니까이다. DirectX 7.0 이후를 사용하고 있는 경우는, 이 메소드를 호출할 필요는 없다. 어플리케이션이 IDirectDraw 를 로드하고 싶지만, 비디오 렌더러를 표면을 할당할 수 있도록(듯이) 만약 싶은 경우, 어플리케이션은,IDirectDraw 자체를 열어,IDirectDrawVideo::SetDirectDraw 를 사용해, 로드 되고 있는 드라이버에 인터페이스를 건네줄 수가 있다. 이 밖에, 어플리케이션이 렌더러에 DirectDraw 를 로드 시킨 후,IDirectDrawVideo::GetDirectDraw 를 사용해, 참조가 인크리먼트(increment) 된 DirectDraw 에의 인터페이스를 취득 하면 말하는 방법도 있다. 다만, DirectShow 에는 최신 버젼의 DirectDraw 가 부속되기 (위해)때문에, 어플리케이션이 디스플레이 모드 자체를 변경해, DirectDraw 오브젝트를 건네주어, 렌더러가 그것을 사용해 표면을 할당할 수 있도록(듯이) 하는 경우를 제외해, 이 메소드는 필요없다.

IDirectDrawVideo::SetSwitches

IDirectDrawVideo 인터페이스

렌더러를 사용할 수 있는 표면 타입을 설정한다.

구문

HRESULT SetSwitches(
    DWORD Switches
);

파라미터

Switches
다음의 DirectShow DirectDraw Surface (AMDDS) 표면 타입안의 1 개 이상이 포함된 비트 마스크.
AMDDS_NONE | DCI/DirectDraw 를 사용하지 않는다.
AMDDS_DCIPS | DCI 프라이머리 표면을 사용한다.
AMDDS_PS | DirectDraw 프라이머리 표면을 사용한다.
AMDDS_RGBOVR | RGB 오버레이 표면.
AMDDS_YUVOVR | YUV 오버레이 표면.
AMDDS_RGBOFF | RGB 오프 스크린 표면.
AMDDS_YUVOFF | YUV 오프 스크린 표면.
AMDDS_RGBFLP | RGB 후립핑서페스.
AMDDS_YUVFLP | YUV 후립핑서페스.
AMDDS_ALL | 상기 모든 플래그.
AMDDS_DEFAULT | 이용 가능한 표면 모든 것을 사용한다.
AMDDS_YUV | (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP).
AMDDS_RGB | (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP).
AMDDS_PRIMARY | (AMDDS_DCIPS | AMDDS_PS).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는 비디오 렌더러가 접속하기 전에 불려 가지 않으면 안 된다.

IDirectDrawVideo::UseOverlayStretch

IDirectDrawVideo 인터페이스

렌더러가 오버레이 확대 제한을 체크할 필요가 있을지 어떨지를 결정한다.

구문

HRESULT UseOverlayStretch(
    long UseOverlayStretch
);

파라미터

UseOverlayStretch
렌더러가 오버레이 확대 기능을 체크할지 어떨지를 지정하는 값. 렌더러에 오버레이 확대 기능을 체크시킬 때는 OATRUE 로 설정해, 그 이외의 경우는, OAFALSE 로 설정한다.

반환값

HRESULT 값을 돌려준다.

주의

일부의 디스플레이 카드는, DirectDraw 를 경유해 오버레이 표면을 사용하는 기능을 갖추고 있다. 오버레이 표면이란, 모니터의 수직 리프레쉬 기간중에 디스플레이에 오버레이 되는 내용이 저장 되고 있는 비디오 메모리의 블록이다. 보통, 오버레이 표면은, 비디오의 화질이 높고, 퍼포먼스가 극히 고속으로 있기 (위해)때문에, DirectShow 는, 가능한 한, 이용 가능한 모든 오버레이 표면을 사용한다. 비교적 높은 비트 깊이로 설정되어 있는 일부의 디스플레이 카드에서는, 디스플레이의 하드웨어 대역폭의 제한으로 대응하기 위해서, 오버레이를 실제의 오버레이의 사이즈보다 큰 화면에 표시할 필요가 있다. 오버레이를 충분히 크게 표시하지 않으면 디스플레이상에서 "순간적인 깜박거림" 으로 불리는 화면의 혼란이 발생할 가능성이 있다.

UseOverlayStretch 가 OATRUE (온, 디폴트)로 설정되어 있으면(자), DirectShow 는, 오버레이를 표시하기 전에, 오버레이가 올바르게 확대되고 있는 것을 확인한다. UseOverlayStretch 가 OAFALSE (오프)로 설정되어 있으면(자), DirectShow 는, 오버레이가 올바르게 확대되고 있는지 어떤지를 체크하지 않기 때문에, 화면의 혼란이 발생할 가능성이 있다. 다만, 가능한 경우에는 오버레이가 사용되는 것은 보증된다.

IDirectDrawVideo::UseScanLine

IDirectDrawVideo 인터페이스

렌더러가 비디오를 드로잉(Drawing) 할 경우에 현재의 주사선을 체크할 필요가 있을지 어떨지를 결정한다.

구문

HRESULT UseScanLine(
    long UseScanLine
);

파라미터

UseScanLine
주사선 정보를 사용할지 어떨지를 지정하는 Long 형 정수값. 주사선 정보를 사용하려면 OATRUE 로 설정해, 주사선 정보를 무시하려면 OAFALSE 로 설정한다.

반환값

인수가 무효인 경우는 E_INVALIDARG 를 돌려주어, 그 이외의 경우는 NOERROR 를 돌려준다.

주의

모니터의 주사선이 화면의 보이는 부분을 주사 하고 있는 동안에 비디오 화면을 비디오 메모리에소총탄 하면, 완성한 화면은, 낡은 화면과 새로운 화면의 복합 화면이 된다. 이 복합 화면은, 분열 비디오 화면으로 불린다. 전의 화면이 완료할 때까지 새로운 화면의 소총탄을 기다리는 것에 의해, 분열 화면의 발생을 피할 수가 있다. 일부의 비디오 카드에서는, 주사선의 현재의 위치를 취득할 수 있다. 이 정보를 이용할 수 있으면, 주사선이 화면의 밖에 나올 때까지 DirectShow 에 새로운 화면의 소총탄을 대기시키는 것에 의해,테아링을 경감할 수가 있다. 다만, 주사선의 위치의 체크는 프로세서의 부하를 증대시키기 (위해)때문에, 화면에 표시되는 비디오 프레임의 양이 감소할 가능성이 있는 것에 주의할 필요가 있다. 주사선 정보를 이용할 수 있으면, DirectShow 는 디폴트로 그것을 이용한다. 다소 화면의 혼란이 있어도 처리 시간을 우선시키고 싶은 경우는,UseScanLine 를 OAFALSE 로 설정한다.

IDirectDrawVideo::UseWhenFullScreen

IDirectDrawVideo 인터페이스

풀 스크린 모드에 바뀔 때 DirectShow 가 디스플레이 모드를 변경할 필요가 있을지 어떨지를 결정한다.

구문

HRESULT UseWhenFullScreen(
    long UseWhenFullScreen
);

파라미터

UseWhenFullScreen
디스플레이 모드를 변경할지 어떨지를 지정하는 값. 렌더러에 DirectShow 를 풀 스크린 모드로 사용하게 하려면 OATRUE 로 설정해, 그 이외의 경우는 OAFALSE 로 설정한다.

반환값

HRESULT 값을 돌려준다.

주의

풀 스크린 모드로 이행하도록(듯이) 요구되었을 경우, DirectShow 에는 많은 선택사항이 있다. 최초의 선택사항은, 그래프내에 풀 스크린 재생을 직접 지원 하는 필터가 있을지 어떨지를 조사하는 것으로, 필터가 있는 경우, 그 필터는 풀 스크린 재생의 지원이 요구된다.

2 번째의 선택사항은, DirectDraw 모드 변경 서비스를 사용하는 특수한 풀 스크린 렌더러를 필터 그래프에 자동적으로 추가해, 비디오를 재생하는 방법이다. 디스플레이 모드를 변경 하면, 비디오는, 디스플레이상의, 보다 큰 영역 (반드시 전영역은 아니다)을 차지한다. 따라서, 예를 들어, 1024 × 768 픽셀 모드에서는 작고 밖에 표시되지 않는 비디오에서도, 디스플레이 모드가 320 × 240 이 되면, 볼품이 훨씬 좋아진다.

3 번째로 마지막 선택사항은,IVideoWindow 인터페이스를 지원 하는 임의의 렌더러를 사용해, 그 렌더러의 윈도우를 풀 스크린에 확대시키는 방법이다. 보통, 이 방법에서는, 풀 스크린의 DirectDraw 대응 렌더러로 전환하는 2 번째의 선택사항보다 퍼포먼스가 낮아진다. UseWhenFullScreen 파라미터를 온 (OATRUE)으로 설정하면, 풀 스크린 재생 때에는 항상 윈도우가 풀 스크린에까지 확대된다. 이 파라미터를 오프 (디폴트)로 설정하면, 필터 그래프 매니저는, DirectDraw 대응의 풀 스크린 렌더러로 전환할 수가 있다.

IDirectDrawVideo::WillUseFullScreen

IDirectDrawVideo 인터페이스

풀 스크린 모드에 바뀔 때 DirectShow 가 디스플레이 모드를 변경할지 어떨지를 결정한다.

구문

HRESULT WillUseFullScreen(
    long *UseWhenFullScreen
);

파라미터

UseWhenFullScreen
DirectShow 가 DirectX 를 풀 스크린 모드로 사용할지 어떨지를 나타내는 값에의 포인터. OATRUE 는, 풀 스크린 모드로 사용하는 것을 나타내, OAFALSE 는 사용하지 않는 것을 나타낸다.

반환값

HRESULT 값을 돌려준다.

주의

이 기능에 대해서는, 「IDirectDrawVideo::UseWhenFullScreen 」를 참조할것.


IDirectDrawMediaSample 인터페이스

IDirectDrawMediaSample 인터페이스는,IMediaSample 도 지원 하는 오브젝트에 의해 지원 된다. 이런 종류의 샘플의 "버퍼 " 는, Microsoft® DirectDraw® 표면이다. 이런 종류의 샘플은,오버레이 믹서와 업 스트림 디코더 필터와의 접속용의 IDirectDrawMediaSampleAllocator 에 의해 할당할 수 있다. 이 인터페이스를 이용 하면, 디코더 필터는, 표면의 락을 해제 하면 동시에 표면을 보관 유지할 수 있기 (위해)때문에, 다른 컴퍼넌트도 표면에 액세스 할 수 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDirectDrawMediaSample 메소드 | 설명
GetSurfaceAndReleaseLock | 샘플이 나타내는 표면을 취득해, 락을 해제한다.
LockMediaSamplePointer | 샘플이 나타내는 표면을 잠근다.

IDirectDrawMediaSample::GetSurfaceAndReleaseLock

IDirectDrawMediaSample Interface

샘플이 나타내는 표면을 취득해, 락을 해제한다.

구문

HRESULT GetSurfaceAndReleaseLock(
    IDirectDrawSurface **ppDirectDrawSurface
    RECT *pRect
);

파라미터

ppDirectDrawSurface
[out] 샘플의 IDirectDrawSurface 인터페이스에의 포인터의 주소.
pRect
[out] 샘플이 나타내는 표면의 부분을 정의하는 직사각형의 주소를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

호출측은, 이 인터페이스의오버레이 믹서 필터의 이행을 호출하는 경우를 제외해, 돌려주어진 표면 포인터를 해방할 필요가 있다.

IDirectDrawMediaSample::LockMediaSamplePointer

IDirectDrawMediaSample 인터페이스

샘플이 나타내는 표면을 잠근다.

구문

HRESULT LockMediaSamplePointer(void);

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 반드시 GetSurfaceAndReleaseLock 를 호출한 후에 호출하는 것.


IDirectDrawMediaSampleAllocator 인터페이스

IDirectDrawMediaSampleAllocator 인터페이스는, 비디오 디코더와의 업 스트림 접속용에오버레이 믹서가 생성 하는 allocater에 이행 된다. 이 allocater는,IMediaSample 인터페이스도 지원 하는 IDirectDrawMediaSample 미디어 샘플을 할당한다.

디코더 필터는, 이 인터페이스를 사용해 오버레이 믹서에 접속할 필요는 없다. 어플리케이션이 이 인터페이스를 사용할 것은 없다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDirectDrawMediaSampleAllocator 메소드 | 설명
GetDirectDraw | 표면의 할당에 사용되는 DirectDraw 의 인스턴스를 취득한다.

IDirectDrawMediaSampleAllocator::GetDirectDraw

IDirectDrawMediaSampleAllocator 인터페이스

표면의 할당에 사용되는 DirectDraw 의 인스턴스에의 포인터를 취득한다.

구문

HRESULT GetDirectDraw(
    IDirectDraw **ppDirectDraw
);

파라미터

ppDirectDraw
[out] DirectDraw 오브젝트의 IDirectDraw 인터페이스를 받는 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

주의

호출측은, 이 인터페이스의오버레이 믹서 필터의 이행을 호출하는 경우를 제외해, 돌려주어진 IDirectDraw 포인터를 해방할 필요가 있다.


IDistributorNotify 인터페이스

IDistributorNotify 인터페이스는,PID 에 필터 그래프 상태의 변화를 통지하기 위해서 사용하는 옵션의 인터페이스이다. 어플리케이션이 이 인터페이스를 사용할 것은 없다.

필터 그래프의 제어와 구성의 변경을 PID 에 통지하고 싶은 경우는, 필터 그래프 매니저에 집성 되는 PID 를 생성 할 경우에, 이 인터페이스를 이행 한다.

PID 가 필터 그래프 매니저상에서 메소드를 사용하는 것은 자주 있다. IDistributorNotify 메소드가 불려 가고 있는 동안은, 필터 그래프 매니저를 호출하는 다른 코드 패스가 보관 유지하고 있을 가능성이 있는 락을 취득해서는 안 된다. 이것을 실시하면, 데드 록이 발생하는 일이 있다.

필터 그래프 매니저는, 필터 그래프 매니저에 집성 되는 모든 PID 에 대해서 이 인터페이스를 문의한다. 인터페이스가 발견되었을 경우, 필터 그래프 매니저는, 각 필터의 IBaseFilter 인터페이스상에서 PID 를 호출하기 전에, 적절한 Run 메소드,Pause 메소드, 또는 SetSyncSource 메소드를 호출한다. 필터가 추가 또는 삭제되었을 경우, 혹은 접속이 변경되었을 경우, 필터 그래프 매니저는 반드시 NotifyGraphChange 메소드를 호출한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDistributorNotify methods | 설명
Stop | 필터 그래프가 정지상태태로 이행할 때 불려 간다.
Pause | 필터 그래프가 포즈 상태로 이행할 때 불려 간다.
Run | 필터 그래프가 실행 상태로 이행할 때 불려 간다.
SetSyncSource | 새로운 클락이 등록될 때 불려 간다.
NotifyGraphChange | 필터 그래프내의 필터세트 또는 그 접속이 변경될 때 불려 간다.

IDistributorNotify::NotifyGraphChange

IDistributorNotify 인터페이스

필터 그래프내의 필터세트 또는 그 접속이 변경될 때 불려 간다.

구문

HRESULT NotifyGraphChange(void);

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는,IFilterGraph::AddFilter 메소드,IFilterGraph::RemoveFilter 메소드, 또는 IFilterGraph::ConnectDirect 메소드가 불려 갔을 때, 또는, 예를 들어 IGraphBuilder::RenderFile 등, 이러한 메소드의 호출로 연결되는 메소드가 불려 갔을 때에, 반드시 불려 간다.

이미 삭제되고 있는 필터로, 보관 유지되고 있는 것이 있으면, 이 시점에서 반드시 그 필터에 대해서 Release 를 사용하는 것. 복수의 다른 통지가 송신되는 일이 있기 (위해)때문에, PID 는, 퍼포먼스 위에의 이유로부터, PID 가 실제로 인터페이스를 필요로 할 때까지 필터를 재스캔 하지 않는 것이 있다. 다만, 캐쉬된 인터페이스는, 즉시 해방하는 것이 중요하다.

IDistributorNotify::Pause

IDistributorNotify 인터페이스

필터 그래프가 포즈 상태로 이행할 때 불려 간다.

구문

HRESULT Pause(void);

반환값

이행이 완료했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 다음의 몇개의 값을 돌려준다.
Error 값 | 이행이 실패했다.
S_FALSE | 이행은 완료하고 있지 않지만, 에러는 발생하지 않았다.

주의

이 메소드는, 필터에 통지를 하기 전에 불려 간다.

IDistributorNotify::Run

IDistributorNotify 인터페이스

필터 그래프가 실행 상태로 이행할 때 불려 간다.

구문

HRESULT Run(
  REFERENCE_TIME tStart
  );

파라미터

tStart
모든 필터의 IMediaFilter::Run 메소드에게 건네지는 스트림 타임 오프셋(offset).

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는, 필터에 통지를 하기 전에 불려 간다.

IDistributorNotify::SetSyncSource

IDistributorNotify 인터페이스

새로운 클락이 등록될 때 불려 간다.

구문

HRESULT SetSyncSource(

  IReferenceClock *pClock

  );

파라미터

pClock
[in] IReferenceClock 인터페이스에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는, 필터에 통지를 하기 전에 불려 간다. PID 가 이 메소드 호출해 이후도 pClock 파라미터를 보관 유지하는 경우는, 반드시 pClock 파라미터에 대해서 AddRef 를 사용하는 것.

IDistributorNotify::Stop

IDistributorNotify 인터페이스

필터 그래프가 정지상태태로 이행할 때 불려 간다.

구문

HRESULT Stop(void);

반환값

이행이 완료했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 다음의 몇개의 값을 돌려준다.
Error 값 | 이행이 실패했다.
S_FALSE | 이행은 완료하고 있지 않지만, 에러는 발생하지 않았다.

주의

이 메소드는, 필터에 통지를 하기 전에 불려 간다.


IDMOWrapperFilter 인터페이스

어플리케이션이 필터 그래프로 Microsoft® DirectX® Media Object (DMO)를 사용할 수 있도록(듯이) 한다. DMO 래퍼 필터는, 이 인터페이스를 공개한다.

DMO 를 필터 그래프에 추가하려면 , DMO 래퍼 필터의 인스턴스를 생성 해, 그 인스턴스에 IDMOWrapperFilter 인터페이스를 문의한다. 다음에,Init 메소드를 호출해 필터를 DMO 로 초기화한다. 상세한 것에 대하여는, 「DirectShow 어플리케이션에서의 DMO 의 사용」을 참조할것.

요건

Dmodshow.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDMOWrapperFilter 메소드 | 설명
Init | 지정된 DMO 로 DMO 래퍼 필터를 초기화한다.

IDMOWrapperFilter::Init

IDMOWrapperFilter 인터페이스

지정된 DMO 로 DMO 래퍼 필터를 초기화한다.

구문

HRESULT Init(
    REFCLSID clsidDMO,
    REFCLSID catDMO
);

파라미터

clsidDMO
DMO 의 클래스 식별자 (CLSID).
catDMO
DMO 의 카테고리를 지정하는 CLSID.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

DMO 카테고리의 일람에 대해서는, 「카테고리 GUID 」를 참조할것. DMO 래퍼 필터는 카테고리에 근거해 최적화를 실행하는 경우가 있다.


IDvdCmd 인터페이스

IDvdCmd 인터페이스는, DVD 네비게이터에 의해 할당할 수 있는 커멘드 동기 오브젝트에 이행 된다. PlayTitle ,PlayAtTimeInTitle 등,IDvdControl2 의 "play" 메소드 호출에 의해 어플리케이션으로부터 지시받으면(자), DVD 네비게이터는, 커멘드 동기 오브젝트를 할당해, 그 커멘드 동기 오브젝트의 IDvdCmd 인터페이스에의 포인터를 어플리케이션에 돌려준다. 커멘드 동기 오브젝트는, 커멘드가 처리를 시작 하는 시작시와 커멘드가 완료하는 종료시에 커멘드의 결과를 저장 한다. 어플리케이션은, 커멘드 동기 오브젝트를 사용해, 커멘드가 시작 또는 종료할 때까지, DVD 네비게이터를 멈출 수가 있다.

커멘드 동기 오브젝트와 IDvdCmd 인터페이스의 사용법의 상세한 것에 대하여는, 「DVD 커멘드의 동기화」를 참조할것. (이 항에서는, 커멘드 동기 오브젝트를 사용하지 않고 커멘드를 동기 시키는 대체 수단에 대해서도 설명하고 있다. )

주의 DVD 네비게이터는 커멘드 동기 오브젝트를 할당하지만, 어플리케이션은, 오브젝트를 다 사용했으면 , 오브젝트에 대한 Release 를 호출할 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDvdCmd 메소드 | 설명
WaitForStart | 이 오브젝트에 관련지을 수 있었던 커멘드가 시작 할 때까지, DVD 네비게이터를 멈춘다.
WaitForEnd | 이 오브젝트에 관련지을 수 있었던 커멘드가 종료하는지, 캔슬될 때까지, DVD 네비게이터를 멈춘다.

IDvdCmd::WaitForEnd

IDvdCmd 인터페이스

이 오브젝트에 관련지을 수 있었던 커멘드가 종료하는지, 캔슬될 때까지, DVD 네비게이터를 멈춘다.

구문

HRESULT WaitForEnd(void);

반환값

성공하면 S_OK 를 돌려주어, 그 이외의 경우는 HRESULT 에러 코드를 돌려준다.

IDvdCmd::WaitForStart

IDvdCmd 인터페이스

이 오브젝트에 관련지을 수 있었던 커멘드가 시작 할 때까지, DVD 네비게이터를 멈춘다.

구문

HRESULT WaitForStart(void);

반환값

성공하면 S_OK 를 돌려주어, 그 이외의 경우는 HRESULT 에러 코드를 돌려준다.


IDvdControl2 인터페이스

Microsoft® DirectShow® DVD 네비게이터 소스 필터는,IDvdControl2 인터페이스를 공개해, 가라오케 타이틀을 포함한 DVD-Video 타이틀의 네비게이션과 재생을 어플리케이션을 실행할 수 있도록(듯이) 한다. DVD 플레이어 어플리케이션은,IDvdGraphBuilder 인터페이스를 사용해 DVD 필터 그래프를 생성 한 후,IDvdControl2 와 IDvdInfo2 의 메소드를 사용해 DVD 네비게이터에게 DVD 커멘드를 송신해, DVD 네비게이터로부터 스테이트 정보를 취득한다.

IDvdControl2 는, 구버젼의 DVD 컨트롤 인터페이스인 IDvdControl 에 비해 큰폭으로 개량되고 있다. 새로운 인터페이스에서는 구인터페이스를 계승하지 않고 , 전면적으로 쇄신 된 이행을 캡슐화하고 있다. IDvdControl2 는, 재생, 메뉴 네비게이션, 및 페어 렌탈 락을 실행하기 위한 메소드외, DVD Annex J 사양으로 규정 떠날 수 있어 모든 기능을 갖추고 있다.

DVD 필터 그래프, 커멘드 동기, 페어 렌탈 락, 메뉴, 및 가라오케 지원에 관한 주제를 포함한 DVD 네비게이터를 사용한 DVD 플레이어 어플리케이션의 생성의 상세한 것에 대하여는, 「DVD 어플리케이션」을 참조할것.

카테고리별의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDvdControl2 메소드 | 설명
재생
Pause | 현재의 위치에서 재생을 포즈 또는 재개한다.
PlayAtTime | 현재의 타이틀의 지정된 시간부터 재생을 시작 한다.
PlayAtTimeInTitle | 지정된 타이틀의 지정된 시간부터 재생을 시작 한다.
PlayBackwards | 지정된 속도로 현재의 위치로부터 역방향으로 재생한다.
PlayChapter | 현재의 타이틀의 지정된 쳅터로부터 재생을 시작 한다.
PlayChapterInTitle | 지정된 타이틀의 지정된 쳅터의 선두로부터 재생을 시작 한다.
PlayChaptersAutoStop | 지정된 타이틀의 지정된 쳅터로부터 지정된 수의 쳅터를 재생한다.
PlayForwards | 지정된 속도로 현재의 위치로부터 순서 방향으로 재생한다.
PlayNextChapter | 현재의 타이틀의 다음의 쳅터의 선두로부터 재생을 시작 한다.
PlayPeriodInTitleAutoStop | 지정된 타이틀이 지정된 시작 타임부터 지정된 종료 타임까지 재생한다.
PlayPrevChapter | 현재의 타이틀의 전의 쳅터의 선두로부터 재생을 시작 한다.
PlayTitle | 지정된 타이틀의 선두로부터 재생을 시작 한다.
ReplayChapter | 현재의 쳅터의 선두로부터 재생을 시작 한다.
Stop | DVD 네비게이터를 DVD Stop 도메인에 이행 시키는 것으로, 타이틀 또는 메뉴의 재생을 정지한다.
메뉴
ActivateAtPosition | 마우스 포인터아래에 있는 메뉴 버튼을 액티브하게 한다.
ActivateButton | 선택되고 있는 메뉴 버튼을 액티브하게 한다.
Resume | 메뉴로부터 빠져 재생을 재개한다.
ReturnFromSubmenu | 표시를 서브 메뉴로부터 그 서브 메뉴의 친메뉴에 되돌린다.
SelectAtPosition | 마우스 포인터아래에 있는 메뉴 버튼을 강조 표시한다.
SelectAndActivateButton | 지정된 메뉴 버튼을 선택해, 액티브하게 한다.
SelectButton | 지정된 메뉴 버튼을 선택한다.
SelectDefaultMenuLanguage | 모든 메뉴와 메뉴 버튼으로 사용되는 디폴트의 언어를 설정한다.
SelectRelativeButton | 지정된 상대 버튼 (상, 하, 우, 좌)을 선택한다.
ShowMenu | 지정된 메뉴가 있으면 표시한다.
비디오 스트림
SelectAngle | DVD 네비게이터가 앵글 블록에 있는 동안, 새로운 앵글을 설정한다.
StillOff | 재생을 재개해, 정지 모드를 캔슬한다.
SelectVideoModePreference | 현재 이후의 비디오 디스플레이 모드를 와이드 스크린,레터박스, 또는빵-스캔의 어느 쪽인가에 설정한다.
오디오 스트림
SelectAudioStream | 재생하는 오디오 스트림을 선택한다.
SelectDefaultAudioLanguage | 디폴트의 오디오 언어를 설정한다.
SelectKaraokeAudioPresentationMode | 가라오케 보조 채널을 왼쪽 스피커 또는 오른쪽 스피커에 보낸다.
서브 픽쳐 스트림
SelectDefaultSubpictureLanguage | 서브 픽쳐 텍스트의 디폴트의 언어를 설정한다.
SelectSubpictureStream | 표시하는 서브 픽쳐 스트림을 설정한다.
SetSubpictureState | 서브 픽쳐의 표시를 온, 오프 한다.
페어 렌탈 락 레벨
AcceptParentalLevelChange | 현재보다 높은 페어 렌탈 락 레벨로 컨텐츠를 재생하는 것을 요구하는 DVD 네비게이터로부터의 요구를 수락 또는 거부한다.
SelectParentalCountry | 페어 렌탈 락 액세스 레벨을 해석해, 디폴트의 언어를 설정 하면나무의 기준이 되는 나라를 설정한다.
SelectParentalLevel | 로그 온 하고 있는 유저의 페어 렌탈 락 액세스 레벨을 설정한다.
DVD 네비게이터 컨트롤
SetDVDDirectory | DVD 네비게이터가 읽어들이는 DVD 드라이브를 설정한다.
SetOption | DVD 네비게이터의 내부 동작 플래그를 유효 또는 무효로 한다.
SetState | 다음에 꺼낼 수 있도록(듯이), 현재의 디스크 위치와 DVD 네비게이터 상태를 보존한다.
SetGPRM | 범용 파라미터 레지스터값을 설정한다.

IDvdControl2::AcceptParentalLevelChange

IDvdControl2 인터페이스

현재보다 높은 페어 렌탈 락 레벨로 컨텐츠를 재생하는 것을 요구하는 DVD 네비게이터로부터의 요구를 수락 또는 거부한다.

구문

HRESULT AcceptParentalLevelChange(
    BOOL bAccept
);

파라미터

bAccept
[in] 어플리케이션이 페어 렌탈 락 레벨의 변경을 받아들일지 어떨지를 나타내는 플래그. 변경을 받아들여, 현재보다 높은 레벨의 컨텐츠를 재생 하면나무는 TRUE 를 지정해, 변경을 거부 하면나무는 FALSE 를 지정한다.

반환값

성공하면 S_OK 를 돌려준다. 그 이외의 경우는 에러 코드를 돌려준다.

주의

일시 페어 렌탈 락 레벨 (PML) 커멘드는, 그 이후의 컨텐츠의 PML 가 타이틀 전체로 지정되고 있는 레벨보다 높은 일을 나타내는 DVD 디스크 위에의 마커이다. 이 마커에는, 변경이 수락 또는 거부되었을 경우의 분기 개소를 나타내는 지시도 포함되어 있다. FALSE 를 지정 하면, DVD 네비게이터는 디스크 위에의 거부시의 분기로 이동한다. TRUE 를 지정 하면, DVD 네비게이터는, 현재보다 높은 레벨의 컨텐츠에 이르는 분기로 이동한다.

AcceptParentalLevelChange 는 SetOption 메소드와 함께 사용한다. 이벤트의 순서는 이하대로이다. 우선,SetOption(DVD_NotifyParentalLevelChange, TRUE) 를 호출해, DVD 네비게이터에 대해서, 어플리케이션에 EC_DVD_PARENTAL_LEVEL_CHANGE 이벤트 통지를 송신한 후는 항상 대기하도록(듯이) 지시한다. 다음에, 변경을 받아들이는지, 거부할까를 결정하기 위한 코드를 이벤트 핸들러에 이행 해,AcceptParentalLevelChange 를 호출해 그 결정을 DVD 네비게이터에게 통지한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
이루어 | 모두

참조

페어 렌탈 락 레벨의 적용

IDvdControl2::ActivateAtPosition

IDvdControl2 인터페이스

마우스 포인터아래에 있는 메뉴 버튼을 액티브하게 한다.

구문

HRESULT ActivateAtPosition(
    POINT point
);

파라미터

point
[in] 화면 픽셀 좌표로 나타내는 클라이언트 윈도우 영역 위에의 위치.

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 강조 표시되고 있는 버튼의 직사각형 영역내에서 마우스가 클릭되어 버튼이 액티브하게 되어 있다.
E_INVALIDARG | 포인터가 유효한 비디오 리젼의 밖에 있다.
E_UNEXPECTED | 버튼은 있지만, 동작하고 있지 않다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 메뉴 도메인내에 없다.
VFW_E_DVD_NO_BUTTON | 마우스 포인터아래에 메뉴 버튼이 없다.
VFW_E_DVD_OPERATION_INHIBITED | 유저 조작 (UOP) 컨트롤에 의해 조작이 금지되고 있다.

주의

마우스 포인터의 좌표의 기준점은 클라이언트 영역의 좌상구석이지만, 비디오의 포맷이 레터박스의 경우는, 클라이언트 영역이 비디오 디스플레이 영역과 일치하지 않는 것이 있다.

유저가 메뉴 버튼상에서 직접 마우스 포인터를 움직이는 것에 의해 메뉴의 네비게이션을 실시하고 있는 경우는, 이 메소드를 사용한다. 유저가 상대 버튼을 사용해 메뉴의 네비게이션을 실시하고 있는 경우는,ActivateAtPosition 는 아니고,ActivateButton 를 사용한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
없음 DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu

참조

DVD 메뉴의 조작

IDvdControl2::ActivateButton

IDvdControl2 인터페이스

선택되고 있는 메뉴 버튼을 액티브하게 한다.

구문

HRESULT ActivateButton(void);

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 무효인 도메인내에 있다.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤에 의해, DVD 네비게이터가 포즈 상태가 되는 것을 금지되고 있다.
VFW_E_DVD_NO_BUTTON | 어느 버튼도 선택되어 있지 않다.

주의

어플리케이션의 비디오 디스플레이상에는, 물리적인 리모트 콘트롤의 버튼에 상당하는 4 개의 상대 버튼이 표시되는 경우도, 표시되지 않는 경우도 있다. 상대 버튼을 사용 하면, 유저는, 메뉴 버튼을 액티브하게 하지 않고 , 선택다 일이 생긴다. 이 경우는, 선택된 버튼을 액티브하게하기 위한 5 번째의 버튼이 필요하게 된다. 5 번째의 버튼이 클릭되었을 경우는, 거기에 응해 ActivateButton 를 호출한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Button_Activate DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

참조

DVD 메뉴의 조작

IDvdControl2::Pause

IDvdControl2 인터페이스

현재의 위치에서 재생을 포즈 또는 재개한다.

구문

HRESULT Pause(
    BOOL bState
);

파라미터

bState
[in] 재생을 포즈 할지 어떨지를 나타내는 불형의 값. TRUE 를 지정 하면 포즈가 실행된다.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 무효인 도메인.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤에 의해, DVD 네비게이터가 포즈 상태가 되는 것을 금지되고 있다.

주의

DVD 네비게이터를 포즈 상태로 하면(자),IMediaControl2::Pause 와 같게, 재생과 모든 내부 타이머가 정지한다. 필터 그래프가 동작하고 있지 않는 경우, 이 메소드는 아무것도 하지 않는다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::Pause」를 참조할것.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
PauseOn/PauseOff DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

IDvdControl2::PlayAtTime

IDvdControl2 인터페이스

현재의 타이틀의 지정된 시간부터 재생을 시작 한다.

구문

HRESULT PlayAtTime(
    DVD_HMSF_TIMECODE *pTime,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

pTime
[in] 재생을 시작 할 시간을 지정하는 DVD_HMSF_TIMECODE 구조체에의 포인터.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::PlayTime」를 참조할것.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
Time_Search | DVD_DOMAIN_Title

참조

DVD 커멘드의 동기화

IDvdControl2::PlayAtTimeInTitle

IDvdControl2 인터페이스

지정된 타이틀의 지정된 시간부터 재생을 시작 한다.

구문

HRESULT PlayAtTimeInTitle(
    ULONG uiTitle,
    DVD_HMSF_TIMECODE *pTime,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

uiTitle
[in] 재생하는 타이틀의 번호를 지정하는 값. 이 값은 1 에서 99 의 사이가 아니면 안된다.
pTime
[in] 재생을 시작 하는 위치를 지정하는 DVD_HMSF_TIMECODE 구조체에의 포인터.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.
E_INVALIDARG | 무효인 인수.

주의

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J command name Valid domains
Time_Play DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

참조

DVD 커멘드의 동기화

IDvdControl2::PlayBackwards

IDvdControl2 인터페이스

지정된 속도로 현재의 위치로부터 역방향으로 재생한다.

구문

HRESULT PlayBackwards(
    double dwSpeed,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

dwSpeed
[in] 역방향의 재생 속도를 지정하는 값. 이 값은, 생성 되었을 때의 속도를 1.0 으로 하는 승수이다. 따라서, 2.5 를 지정 하면, 생성 속도의 2.5 배의 속도로 역방향의 재생을 해 0.5 를 지정 하면 생성 속도의 반의 속도로 역방향의 재생을 한다. 실제의 재생 속도는, 비디오 디코더의 기능에 따라서 달라, 지정된 속도와 다른 일이 있다. 역방향의 재생에서는, 오디오가 뮤트 되어 서브 픽쳐는 표시되지 않는다. 0.00001 미만의 속도는 모두 0.00001 에 변환된다.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::Rewind」를 참조할것. 1 프레임씩 스탭핑(Stepping)하면서 역방향으로 재생하려면 , 샘플 어플리케이션의 CDvdCore::FrameStep 의 사용 예의 같게 IVideoFrameStep 인터페이스를 사용한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Backward_Scan DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

IDvdControl2::PlayChapter

IDvdControl2 인터페이스

현재의 타이틀의 지정된 쳅터로부터 재생을 시작 한다.

구문

HRESULT PlayChapter(
    ULONG ulChapter,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

ulChapter
[in] DVD 네비게이터가 재생을 시작 하는 현재의 타이틀의 쳅터를 지정하는 값. 이 값은 1 에서 999 의 사이가 아니면 안된다.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.
E_INVALIDARG | 무효인 인수.

주의

DVD 네비게이터는, 지정된 쳅터로부터 재생을 시작 해, 그 이후의 쳅터를 계속해 재생한다. 현재의 쳅터만을 재생하려면 ,PlayChaptersAutoStop 를 사용한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::PlayChapter」를 참조할것.
Annex J 커멘드명 | 유효한 도메인
PTT_Search | DVD_DOMAIN_Title

참조

DVD 커멘드의 동기화

IDvdControl2::PlayChapterInTitle

IDvdControl2 인터페이스

지정된 타이틀의 지정된 쳅터의 선두로부터 재생을 시작 한다.

구문

HRESULT PlayChapterInTitle(
    ULONG ulTitle,
    ULONG ulChapter,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

ulTitle
[in] 목적의 쳅터가 포함되어 있는 타이틀을 지정하는 값. 이 값은 1 에서 99 의 사이가 아니면 안된다.
ulChapter
[in] DVD 네비게이터가 재생을 시작 하는 지정된 타이틀의 쳅터를 지정하는 값. 이 값은 1 에서 999 의 사이가 아니면 안된다.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.
E_INVALIDARG | 무효인 인수.

주의

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::PlayChapterInTitle」를 참조할것.
Annex J 커멘드명 유효한 도메인
PTT_Play DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

참조

DVD 커멘드의 동기화

IDvdControl2::PlayChaptersAutoStop

IDvdControl2 인터페이스

지정된 타이틀의 지정된 쳅터로부터 지정된 수의 쳅터를 재생한다.

구문

HRESULT PlayChaptersAutoStop(
    ULONG ulTitle,
    ULONG ulChapter,
    ULONG ulChaptersToPlay,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

ulTitle
[in] 목적의 쳅터가 포함되어 있는 타이틀을 지정하는 값. 이 값은 1 에서 99 의 사이가 아니면 안된다.
ulChapter
[in] DVD 네비게이터가 재생을 시작 하는 지정된 타이틀의 쳅터를 지정하는 값. 이 값은 1 에서 999 의 사이가 아니면 안된다.
ulChaptersToPlay
[in] 시작 쳅터로부터 재생하는 쳅터의 수.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않은, 또는 타이틀이 단일 시퀀셜 PGC 타이틀은 아니다.
E_INVALIDARG | ulTitle 값이 존재하지 않는, 또는 타이틀의 수를 웃돈다. 혹은,ulChapter 가 존재하지 않는, 또는 쳅터의 수를 웃돈다. 혹은,ulChapter 와 ulChaptersToPlay 의 합계가 쳅터의 수를 웃돈다.
VFW_E_DVD_GRAPHNOTREADY | 그래프가 동작 상태로 되어 있지 않다.

주의

이 메소드는 One_Sequential_PGC_Title 에서만 기능한다. DVD 네비게이터는, 지정된 수의 쳅터를 재생한 후, 어플리케이션에 EC_DVD_CHAPTER_AUTOSTOP 이벤트 통지를 보낸다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
이루어 | 모두

참조

EC_DVD_CHAPTER_AUTOSTOP ,DVD 커멘드의 동기화

IDvdControl2::PlayForwards

IDvdControl2 인터페이스

지정된 속도로 현재의 위치로부터 순서 방향으로 재생한다.

구문

HRESULT PlayForwards(
    double dwSpeed,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

dwSpeed
[in] 재생 속도를 지정하는 값. 이 값은, 생성 되었을 때의 속도를 1.0 으로 하는 승수이다. 따라서, 2.5 를 지정 하면, 생성 속도의 2.5 배의 속도로 재생되어 0.5 를 지정 하면 생성 속도의 반의 속도로 재생된다. 실제의 재생 속도는, 비디오 디코더의 기능에 따라서 다르다.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::FastForward」를 참조할것.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Forward_Scan DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

IDvdControl2::PlayNextChapter

IDvdControl2 인터페이스

현재의 타이틀의 다음의 쳅터의 선두로부터 재생을 시작 한다.

구문

HRESULT PlayNextChapter(
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

DVD 네비게이터는, 다음의 쳅터를 재생한 후, 디스크 위에의 분기 명령에 따라 재생을 계속한다. 다음의 쳅터만을 재생하려면 ,PlayChaptersAutoStop 를 호출한다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::NextChapter」를 참조할것.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
NextPG_Search DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

참조

DVD 커멘드의 동기화

IDvdControl2::PlayPeriodInTitleAutoStop

IDvdControl2 인터페이스

지정된 타이틀이 지정된 시작 타임부터 지정된 종료 타임까지 재생한다.

구문

HRESULT PlayPeriodInTitleAutoStop(
    ULONG ulTitle
    DVD_HMSF_TIMECODE *pStartTime
    DVD_HMSF_TIMECODE *pEndTime
    DWORD dwFlags
    IDvdCmd **ppCmd
);

파라미터

ulTitle
[in] 타이틀을 지정하는 값. 이 값은 1 에서 99 의 사이가 아니면 안된다.
pStartTime
[in] 재생을 시작 할 시간을 지정하는 DVD_HMSF_TIMECODE 구조체에의 포인터.
pEndTime
[in] 재생을 정지하는 시간을 지정하는 DVD_HMSF_TIMECODE 구조체에의 포인터.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.
E_INVALIDARG | 무효인 인수.

주의

실제의 시작 타임 및 종료 타임은,DVD_HMSF_TIMECODE 에 의해 지정되는 프레임 번호 또는 그 이전의 시간이다. pStartTime 및 pEndTime 에서는 frame rate 코드는 무시된다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
없음 DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

참조

DVD 커멘드의 동기화

IDvdControl2::PlayPrevChapter

IDvdControl2 인터페이스

현재의 타이틀의 전의 쳅터의 선두로부터 재생을 시작 한다.

구문

HRESULT PlayPrevChapter(
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

dwFlags
커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::PrevChapter」를 참조할것.
Annex J 커멘드명 유효한 도메인
PrevPG_Search DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

참조

DVD 커멘드의 동기화

IDvdControl2::PlayTitle

IDvdControl2 인터페이스

지정된 타이틀의 선두로부터 재생을 시작 한다.

구문

HRESULT PlayTitle(
    ULONG uiTitle
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

uiTitle
타이틀 번호를 지정하는 값. 이 값은 1 에서 99 의 사이가 아니면 안된다.
dwFlags
커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.
E_INVALIDARG | 무효인 인수.

주의

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Title_Play DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

참조

DVD 커멘드의 동기화

IDvdControl2::ReplayChapter

IDvdControl2 인터페이스

현재의 쳅터의 선두로부터 재생을 시작 한다.

구문

HRESULT ReplayChapter(
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

dwFlags
커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
TopPG_Search DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

참조

DVD 커멘드의 동기화

IDvdControl2::Resume

IDvdControl2 인터페이스

메뉴로부터 빠져 재생을 재개한다.

구문

HRESULT Resume(
    DWORD dwFlags,
    IDvdCmd **ppCmd
    );

파라미터

dwFlags
커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.
VFW_E_DVD_NO_RESUME_INFORMATION | 비디오 매니저 메뉴로부터 Resume 가 불려 갔다.

주의

이 메소드에서는, 재생을 중단한 위치로부터 재생이 재개된다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::RootMenu」 및 「CDvdCore::TitleMenu」를 참조할것.
Annex J 커멘드명 유효한 도메인
Resume DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Stop

IDvdControl2::ReturnFromSubmenu

IDvdControl2 인터페이스

표시를 서브 메뉴로부터 서브 메뉴의 친메뉴에 되돌린다.

구문

HRESULT ReturnFromSubmenu(
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

dwFlags
커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

DVD 네비게이터가 최상정도 메뉴에 있는 경우, 이 메소드는 Resume 메소드를 호출해, 재생을 중단한 위치로부터 재생을 재개시킨다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
GoUP DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

참조

DVD 커멘드의 동기화,DVD 메뉴의 조작

IDvdControl2::SelectAndActivateButton

IDvdControl2 인터페이스

지정된 메뉴 버튼을 선택해, 액티브하게 한다.

구문

HRESULT SelectAndActivateButton(
    ULONG ulButton
);

파라미터

ulButton
[in] 선택해, 액티브하게 하는 버튼을 지정하는 1 에서 36 의 사이의 값.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | ulButton 가 범위외이다.
E_UNEXPECTED | ulButton 값은 유효하지만,DVD 네비게이터 필터가 버튼을 액티브하게 할 수가 없었다.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Button_Select_And_Activate DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

참조

DVD 메뉴의 조작

IDvdControl2::SelectAngle

IDvdControl2 인터페이스

DVD 네비게이터가 앵글 블록에 있는 동안, 새로운 앵글을 설정한다.

구문

HRESULT SelectAngle(
    ULONG ulAngle,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

ulAngle
[in] 새로운 앵글의 값. 1 에서 9 의 사이가 아니면 안된다.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | ulAngle 가 범위외이다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 First Play 도메인내에 있다.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

오디오 스트림과 서브 픽쳐 스트림의 인덱스는 시작값이 0 이지만, 앵글과 메뉴 버튼의 인덱스는 시작값이 1 인 점에 주의 해야 한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Angle_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

참조

도메인

IDvdControl2::SelectAtPosition

IDvdControl2 인터페이스

마우스 포인터아래에 있는 메뉴 버튼을 강조 표시한다.

구문

HRESULT SelectAtPosition(
    POINT point
);

파라미터

point
[in] 화면 픽셀 좌표로 나타내는 화면상의 위치.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_NO_BUTTON | 마우스 포인터의 위치에 버튼이 없다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 Stop 도메인내에 있다.

주의

오디오 스트림과 서브 픽쳐 스트림의 인덱스는 시작값이 0 이지만, 앵글과 메뉴 버튼의 인덱스는 시작값이 1 인 점에 주의 해야 한다.

포인터가 메뉴 버튼상에 있는 경우는, 마우스의 클릭에 응해 ActivateButton 를 호출한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

이 메소드의 사용예에 대해서는, DVDSample 의 「CDvdCore::OnMouseEvent」를 참조할것.

Annex J 커멘드명 유효한 도메인
없음 DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_FirstPlay

참조

ActivateAtPosition ,도메인,DVD 메뉴의 조작

IDvdControl2::SelectAudioStream

IDvdControl2 인터페이스

재생하는 오디오 스트림을 선택한다.

구문

HRESULT SelectAudioStream(
    ULONG ulAudio,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

ulAudio
[in] 사용하는 오디오 트럭을 지정하는 값. 0 에서 7 의 사이의 정수값이 아니면 안된다. 디폴트의 스트림을 지정하려면 , DVD_DEFAULT_AUDIO_STREAM 를 지정한다.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | ulAudio 가 범위외인지, 오디오 스트림에 대응하고 있지 않다.
E_UNEXPECTED | ulAudio 값은 유효하지만, 어떠한 이유로써 DVD 네비게이터가 값을 설정할 수 없었다.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.
VFW_E_DVD_STREAM_DISABLED | 지정된 스트림이 무효가 되어 있다.

주의

이 메소드는, 현재의 비디오 타이틀 세트 (VTS)의 오디오를 대상으로 한다. 메뉴내로부터 이 메소드를 호출했을 경우는, 메뉴를 호출한 타이틀의 오디오 스트림이 설정된다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Audio_Stream_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

IDvdControl2::SelectButton

IDvdControl2 인터페이스

지정된 메뉴 버튼을 선택한다.

구문

HRESULT SelectButton(
    ULONG ulButton
);

파라미터

ulButton
[in] 선택하는 버튼을 지정하는 1 에서 36 의 사이의 값.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 무효인 도메인내에 있다.
VFW_E_DVD_NO_BUTTON | 어느 버튼도 선택되어 있지 않다.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤에 의해,DVD 네비게이터가 포즈 상태가 되는 것을 금지되고 있다.

주의

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Button_Select DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

참조

DVD 메뉴의 조작

IDvdControl2::SelectDefaultAudioLanguage

IDvdControl2 인터페이스

디폴트의 오디오 언어를 설정한다.

구문

HRESULT SelectDefaultAudioLanguage(
    LCID Language
    DVD_AUDIO_LANG_EXT audioExtension
);

파라미터

Language
[in] 디폴트 언어를 지정하는 로케일 식별자.
audioExtension
[in] 디폴트의 오디오 언어 확장 기능을 지정하는 DVD_AUDIO_LANG_EXT 값.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | audioExtension 값이 무효이다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터 필터가 Stop 도메인내에 있다.

주의

이 메소드에서는, 디스크를 재생할 경우에 사용하는 디폴트의 언어 및 언어 확장 기능을 선택한다. 예를 들어,Language 가 영어에 상당하는 0x409 로 지정되고 있어audioExtension 가 DVD_AUD_EXT_NotSpecified 로 지정되고 있는 경우, DVD 네비게이터는, 영어의 기본적인 오디오 스트림을 검색한다. audioExtension 가 DVD_AUD_EXT_VisuallyImpaired 로 지정되고 있는 경우, DVD 네비게이터는, 우선, 시력이 약한 사람을 위한 영어의 특수한 오디오 스트림을 검색한다. 디폴트의 스트림이 디스크상에서 발견되지 않는 경우, DVD 네비게이터는, 요구에 가장 가까운 스트림을 선택한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
없음 | DVD_DOMAIN_Stop

IDvdControl2::SelectDefaultMenuLanguage

IDvdControl2 인터페이스

모든 메뉴와 메뉴 버튼으로 사용되는 디폴트의 언어를 설정한다.

구문

HRESULT SelectDefaultMenuLanguage(
    LCID Language
);

파라미터

Language
디폴트 언어를 지정하는 LCID 형의 변수.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터 필터가 유효한 도메인내에 없다.

주의

이 메소드에서는, 디스크를 재생할 경우에 메뉴로 사용하는 디폴트의 텍스트 언어를 선택한다. 예를 들어,Language 가 미국 영어에 상당하는 0x409 로 지정되고 있는 경우, DVD 네비게이터는, 메뉴에 미국 영어의 텍스트를 표시하려고 시도한다. 디폴트의 메뉴 언어가 디스크상에서 발견되지 않는 경우, DVD 네비게이터는 요구에 가장 가까운 언어를 선택한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
없음 | DVD_DOMAIN_Stop

IDvdControl2::SelectDefaultSubpictureLanguage

IDvdControl2 인터페이스

서브 픽쳐 텍스트의 디폴트의 언어를 설정한다.

구문

HRESULT SelectDefaultSubpictureLanguage(
    LCID Language
    DVD_SUBPICTURE_LANG_EXT subpictureExtension
);

파라미터

Language
[in] 디폴트 언어를 지정하는 로케일 식별자.
subpictureExtension
[in] 디폴트의 서브 픽쳐 확장 기능을 지정하는 DVD_SUBPICTURE_LANG_EXT 값.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | Language 가 무효이다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터 필터가 유효한 도메인내에 없다.

주의

이 메소드에서는, 디스크의 재생시에 서브 픽쳐 및 메뉴로 사용하는 디폴트의 언어와 포맷을 선택한다. 예를 들어,Language 가 영어에 상당하는 0x409 로 지정되고 있어subpictureExtension 가 DVD_SP_EXT_Caption_Big 로 지정되고 있는 경우, DVD 네비게이터는, 서브 픽쳐의 텍스트를 "빅 캡션 " 포맷의 미국 영어로 표시하려고 시도한다. 디폴트의 언어 또는 언어 확장 기능이 디스크상에서 발견되지 않는 경우, DVD 네비게이터는 요구에 가장 가까운 것을 선택한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
없음 | DVD_DOMAIN_Stop

IDvdControl2::SelectKaraokeAudioPresentationMode

IDvdControl2 인터페이스

가라오케 보조 채널을 왼쪽 스피커 또는 오른쪽 스피커에 보낸다.

구문

HRESULT SelectKaraokeAudioPresentationMode(
    ULONG ulMode
);

파라미터

ulMode
[in] 5 개의 가라오케 채널을 채널 0 으로 채널 1 에 믹스 다운하는 방법을 나타내는 DVD_KARAOKE_DOWNMIX 플래그의 비트마다의 OR. 보통, 채널 0 으로 채널 1 은 왼쪽 스피커와 오른쪽 스피커에 출력된다.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터 필터가 무효인 도메인내에 있다.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 현재의 조작을 금지하고 있다.

주의

DVD 네비게이터는, 가라오케 모드로 이행하면(자), 오디오 디코더에 가라오케 다운 믹싱을 지원 하고 있을지 어떨지를 문의한다. 디코더가 가라오케 다운 믹싱 지원 하고 있는 경우는, 채널 2 로부터 채널 4 까지 (가이드 보컬, 가이드 멜로디, 음향 효과로부터 구성되는 가라오케 보조 채널)가 뮤트 된다. 이 메소드를 사용해, 채널을 개별적으로 온, 오프 해, 채널 0 으로 채널 1 에 할당한다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CKaraokeDlg::DoModal」를 참조할것.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Karaoke_Audio_Presentation_Mode_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

IDvdControl2::SelectParentalCountry

IDvdControl2 인터페이스

페어 렌탈 락 액세스 레벨을 해석해, 디폴트 언어를 설정 하면나무의 기준이 되는 나라를 설정한다.

구문

HRESULT SelectParentalCountry(
    BYTE country[2]
);

파라미터

country
[in] ISO 3166 에 따라 현재의 나라를 지정하는 BYTE 형의 값의 배열.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터 필터가 유효한 도메인내에 없다.

주의

페어 렌탈 지방은, 8 개의 기본 페어 렌탈 락 레벨의 의미 및 사운드 트랙과 메뉴의 디폴트 언어를 규정한다. 상세한 것에 대하여는, 「페어 렌탈 락 레벨의 적용」을 참조할것.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
Parental_Country_Select | DVD_DOMAIN_Stop

참조

IDvdControl2::SelectParentalLevel

IDvdControl2::SelectParentalLevel

IDvdControl2 인터페이스

로그 온 하고 있는 유저의 페어 렌탈 락 액세스 레벨을 설정한다.

구문

HRESULT SelectParentalLevel(
    ULONG ulParentalLevel
);

파라미터

ulParentalLevel
현재의 유저의 페어 렌탈 락 액세스 레벨을 지정하는 값. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
VFW_E_DVD_INVALIDDOMAIN | 무효인 도메인.

주의

DVD 의 사양에서는, 1 (가장 제한이 많은 레벨)에서 8 (가장 제한의 적은 레벨)까지의 8 개의 기본 페어 렌탈 락 레벨이 정의되고 있다. 이러한 레벨의 의미는 지역에 의해 달라, 현재의 나라에 의존한다 ( 「SelectParentalCountry 」를 참조). 아메리카 합중국과 캐나다 (DVD 리젼 1)에서는, 이하의 레벨이 제창되고 있다.
페어 렌탈 락 레벨 | 의미
1 | 등급은 일반용의 G 이다.
3 | 등급은 보호자의 지도가 바람직한 PG 이다.
4 | 등급은 보호자의 지도가 바람직하고, 13 세 미만의 아이에게는 추천 할 수 없는 PG-13 이다.
6 | 등급은 제한부의 R 이다.
7 | 등급은 17 세 미만에는 부적절한 NC-17 이다.

이 메소드에서는, 현재의 유저의 액세스 레벨을 설정한다. 이 액세스 레벨에 의해, 유저가 재생할 수 있는 미디어 파일이 정해진다. 높은 레벨은 낮은 레벨의 컨텐츠를 재생할 수 있지만, 낮은 레벨은 높은 레벨의 컨텐츠를 재생할 수 없다. 예를 들어, 성인은 어린이용의 컨텐츠를 볼 수가 있지만, 아이는 성인전용의 컨텐츠를 볼 수 없다.

DVD 플레이어 어플리케이션에서는, 현재의 페어 렌탈 락 레벨을 올리는 조작을 패스워드에 의해 보호하는 등, 페어 렌탈 락 레벨의 설정을 강제적으로 제한할 수가 있다. 어플리케이션의 유저 인터페이스에는, 레벨을 설정해, 체크를 완전하게 무효로 하는 수단을 갖게할 필요가 있다. 레벨 8 도 허가하지 않게 디스크를 생성 할 수가 있지만, 이 경우는 페어 렌탈 락이 유효하게 되어 있으면(자), 유효한 레벨이 없기 때문에, 아무도 디스크를 볼 수가 없다. 이러한 디스크를 보려면 , 페어 렌탈 락을 무효로 할 필요가 있다. DVD 네비게이터 필터의 페어 렌탈 락은, 디폴트로 무효가 되어 있다.

유효하게 되어 있는 페어 렌탈 락을 무효로 하려면 ,ulParentalLevel 로서 0xffffffff 를 건네준다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::SetParentalLevel」를 참조할것.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
Parental_Level_Select | DVD_DOMAIN_Stop

IDvdControl2::SelectRelativeButton

IDvdControl2 인터페이스

지정된 상대 버튼 (상, 하, 우, 좌)을 설정한다.

구문

HRESULT SelectRelativeButton(
    DVD_RELATIVE_BUTTON buttonDir,
);

파라미터

buttonDir
선택하는 버튼을 나타내는 DVD_RELATIVE_BUTTON 값.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터 필터가 유효한 도메인내에 없다.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
(Left/Right/Upper/Lower) _Button_Select DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

참조

DVD_RELATIVE_BUTTON ,DVD 메뉴의 조작

IDvdControl2::SelectSubpictureStream

IDvdControl2 인터페이스

표시하는 서브 픽쳐 스트림을 설정한다.

구문

HRESULT SelectSubpictureStream(
    ULONG ulSubPicture,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

ulSubPicture
서브 픽쳐 스트림을 지정하는 값. 0 에서 31 의 사이 또는 63 이 아니면 안된다.
0-31 | 스트림이 유효하다.
63 | 스트림이더미 스트림, 즉 뮤트 된 저bit rate 스트림이다.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | ulSubPicture 가 범위외인지, SP 스트림에 대응하고 있지 않다.
E_UNEXPECTED | ulSubPicture 파라미터는 유효하지만, 어떠한 이유로써 DVD 네비게이터가 이 파라미터를 설정할 수 없다.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.
VFW_E_DVD_INVALIDDOMAIN | 무효인 도메인.
VFW_E_DVD_STREAM_DISABLED | 지정된 스트림이 무효가 되어 있다.

주의

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Sub-picture_Stream_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

참조

오디오 스트림과 서브 픽쳐 스트림

IDvdControl2::SelectVideoModePreference

IDvdControl2 인터페이스

지정된 재생용의 비디오 디스플레이 모드 (와이드 스크린, 레터박스, 또는 빵-스캔)를 설정한다.

구문

HRESULT SelectVideoModePreference(
    ULONG ulPreferredDisplayMode
);

파라미터

ulPreferredDisplayMode
[in] DVD 컨텐츠의 새로운 디스플레이 모드를 지정하는 값. DVD_PREFERRED_DISPLAY_MODE 열거형의 멤버.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
VFW_E_DVD_INVALIDDOMAIN | 무효인 도메인.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

이 메소드에서는, 디폴트의 비디오 윈도우의 어스펙트비(가로세로 비율)을 변경한다. 또, 디폴트의 어스펙트비(가로세로 비율) 변환 메카니즘을 지정할 수도 있다.

720×480 의 소스 비디오를 어스펙트비(가로세로 비율) 16×9 에 잡아늘인 변형 16×9 소스 비디오는, 이하와 같이 표시된다.

와이드 스크린 16×9 비디오를 클라이언트 출력 윈도우의 최대의 16×9 영역에 두어, 확대할 필요가 있다. 하이라이트 영역은 16×9 영역의 안쪽 에 비례한다. 블랙 바를 상하 또는 좌우에 추가해 16×9 영역을 보관 유지할 필요가 있다.

빵 스캔 표시하는 비디오는, 길게 늘어진 16×9 비디오에서 4×3 서브 윈도우를 꺼내는 것에 의해 계산한다. 이 때, 수평 오프셋(offset)는 MPEG-2 비디오 윈도우의 오프셋(offset)로부터 얻는다. 4×3 서브 윈도우를 출력 클라이언트 윈도우의 최대의 4×3 영역에 둔다. 하이라이트 영역의 좌표는 4×3 출력 윈도우 에 비례해, 소스의 16×9 비디오에는 비례하지 않는다. 블랙 바를 상하 또는 좌우에 추가해 4×3 영역을 보관 유지할 필요가 있다.

레터박스 출력 클라이언트 윈도우의 최대의 4×3 영역을 꺼내는 것에 의해 4×3 디스플레이 영역을 형성한다. 블랙 바를 상하 또는 좌우에 추가해 4×3 영역을 보관 유지할 필요가 있다. 소스의 16×9 비디오를 4×3 서브 윈도우 내부의 최대의 16×9 서브 윈도우내에 둔다. 블랙 바를 서브 윈도우의 상하에 추가해 16×9 영역을 보관 유지할 필요가 있다. 하이라이트 영역의 좌표는, 4×3 서브 윈도우 에 비례해, 소스의 16×9 비디오에는 비례하지 않는다. 디스크로, 16×9 영역의 밖이지만, 4×3 윈도우안에 하이라이트 영역이 표시되도록(듯이) 지정하는 것이 기술적으로 가능하다.

4×3 비디오의 경우는, 비디오를 출력 클라이언트 윈도우의 최대의 4×3 출력 영역에 표시한다. 블랙 바를 상하 또는 좌우에 추가해 4×3 영역을 보관 유지할 필요가 있다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Video_PresentationMode_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

IDvdControl2::SetDVDDirectory

IDvdControl2 인터페이스

DVD 네비게이터 필터가 읽어들이는 DVD 드라이브를 설정한다.

구문

HRESULT SetDVDDirectory(
    LPCWSTR  pszwPath
);

파라미터

pszwPath
[in] 루트 디렉토리의 패스를 지정하는 LPCWSTR 형의 변수.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | pszwPath 파라미터가 무효인 DVD 패스를 가리키고 있는지, 열거중에 DVD 드라이브가 발견되지 않는다.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.
S_FALSE | pszwPath 파라미터가 NULL 이며, DVD 네비게이터가 DVD 볼륨을 찾아낼 수 없다.
VFW_E_DVD_INVALIDDOMAIN | 무효인 도메인. 상세한 것에 대하여는 「주의」를 참조할것.

주의

pszwPath 가 NULL 의 경우, DVD 네비게이터는 이용 가능한 모든 드라이브상에서 DVD 볼륨을 선택하려고 시도한다. 기동시, DVD 네비게이터는, 루트 폴더에 VIDEO_TS 폴더를 가지는 드라이브를 드라이브 C 로부터 차례로 자동적으로 검색한다. 따라서,SetDVDDirectory 를 호출할 필요가 있는 것은, 컴퓨터에 복수의 DVD 드라이브가 있는 경우, 또는 DVD 드라이브 문자가 A 또는 B 의 경우에 한정된다. 패스를 지정 하면나무는, vide_ts 폴더를 포함한다.

SetDVDDirectory("e:\video_ts");

일부의 DVD 볼륨에서는, "video_ts" 이외의 디렉토리에 비디오가 저장 되고 있는 일이 있다. 일반적으로, 추가의 "DVD 볼륨 " (보통은 VIDEO_TS 디렉토리에 저장 된다 . IFO. VOB, 및 . BUP 파일세트)를 디스크 위에의 서브 디렉토리에 저장 할 수가 있다. 이 디렉토리를 가리키도록(듯이) 루트를 변경하는 것으로써, MSWebDVD 는 이 DVD 볼륨상에서 동작하게 된다. 그 경우는, 액세스 불능이 되는 VIDEO_TS 루트내의 타이틀과는 다른, 새로운 메뉴, 타이틀등의 세트가 이용 가능하게 된다. 이러한 디렉토리는 "은폐 디렉토리 " 로 불린다. 이하의 예는, 은폐 디렉토리를 루트로서 설정하는 방법을 나타내고 있다. "hidden" 는 디스크의 생성자가 디렉토리에 붙인 이름이 들어가는 플레이스홀더이다.

SetDVDDirectory("d:\\webdvd\\hidden");

필터 그래프가 동작하고 있어, DVD 네비게이터가 pszwPath 에 의해 지정된 디렉토리내에서 DVD 를 찾아내면(자), DVD 네비게이터는 자동적으로 디스크의 재생을 시작 한다. 이 동작은 DVD 의 사양에 준거하고 있어, 이것에 의해 새로운 디스크가 올바르게 초기화되는 것이 보증된다. SetDVDDirectory 으로부터 동작이 돌아온 후, 새로운 디스크를 자동적으로 재생하고 싶지 않은 경우는,SetOption 의 DVD_ResetOnStop 플래그를 TRUE 로 설정해, 필터 그래프 매니저로 IMediaControl::Stop 를 호출하는 것에 의해 필터 그래프를 정지할 필요가 있다. DVD_ResetOnStop 가 FALSE 로 설정되어 있는 경우,SetDVDDirectory 은 VFW_E_DVD_INVALIDDOMAIN 를 돌려준다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::SetDirectory」를 참조할것.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
없음 | DVD_DOMAIN_Stop

IDvdControl2::SetGPRM

IDvdControl2 인터페이스

범용 파라미터 레지스터값을 설정한다.

구문

HRESULT SetGPRM(
    ULONG ulIndex
    WORD wValue
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

ulIndex
[in] 레지스터 인덱스. 0 에서 15 의 값.
wValue
[in] 지정된 레지스터에 저장 되는 16 비트의 값.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | ulIndex 파라미터가 15 를 넘고 있는지, 다른 몇개의 입력 파라미터가 무효이다.

주의

DVD 디스크는 범용 파라미터 레지스터를 사용해 다양한 종류의 정보를 저장 한다. 이러한 레지스터를 1 개 이상 수동으로 설정하는 것으로써, 어플리케이션에 특정의 커스텀 기능을 갖게할 수가 있다. 이것은 고도의 커멘드이며, DVD 의 사양을 완전하게 이해하고 있지 않는 경우는 사용하지 않는 것이 좋다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
이루어 | 모두

참조

IDvdInfo2::GetAllGPRMs

IDvdControl2::SetOption

IDvdControl2 인터페이스

DVD 네비게이터 필터의 내부 동작 플래그를 유효 또는 무효로 한다.

구문

HRESULT SetOption(
    DVD_OPTION_FLAG flag
    BOOL bEnable
);

파라미터

flag
[in] 변경하는 플래그를 지정하는 DVD_OPTION_FLAG 값. 상세한 것에 대하여는 「주의」를 참조할것.
bEnable
[in] flag 를 유효하게 할까 무효로 하는지를 지정하는 BOOL 형의 변수. flag 를 유효하게 하려면 TRUE 로 설정해, 무효로 하려면 FALSE 로 설정한다.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | flag 값이 DVD_ResetOnStop 또는 DVD_NotifyParentalLevelChange 가 아니다.

주의

DVD 네비게이터의 인스턴스를 생성 한 직후, 및 몇개의 동작을 변경하고 싶은 경우는, 반드시 목적의 플래그를 지정해 SetOption 를 호출한다.
플래그 | 의미
DVD_ResetOnStop 이 플래그를 TRUE 로 설정 하면, 필터 그래프가 정지했을 때에, 네비게이터는 DVD Stop 도메인에 들어간다. 이것은 디폴트의 동작이다. 네비게이터가 Stop 도메인으로부터 재생을 재개 하면나무는, 디스크의 선두로부터 재생을 한다. 화면의 해상도가 바뀌거나 스크린 세이버가 기동하거나 컴퓨터가 중지 모드에 들어가거나 하는 것으로써, 혹은 다른 이유에 의해, 필터 그래프가 돌연 정지하는 일이 있기 (위해)때문에, 이 동작은 바람직하지 않은 것이 있다. 그래프가 Stop 상태로 이행했을 때에 네비게이터가 DVD Stop 도메인에 들어가는 것을 방지하려면 , 이 플래그를 FALSE 로 설정한다. 플래그를 FALSE 로 설정 하면, 필터 그래프가 동작을 재개했을 때, 네비게이터는 전회 정지한 위치로부터 재생을 재개한다.

보통, 어플리케이션에서는,IMediaControl::Run 를 호출해 DVD-Video 의 재생을 시작 한 직후 혹은 재생을 시작 하기 전에, 이 플래그를 FALSE 로 설정할 필요가 있다. 어플리케이션은, 재생을 정지하기 위한 명시적인 유저 커멘드에 응해 IMediaControl::Stop 를 호출하기 전에, 이 플래그를 TRUE 로 설정할 필요가 있다.

DVD_NotifyParentalLevelChange 이 플래그에서는, 디스크상에서 페어 렌탈 락 레벨의 변경이 발생했을 때에, DVD 네비게이터가 어플리케이션에 통지할 필요가 있을지 어떨지를 지시한다. 이 플래그를 TRUE 로 설정 하면, 네비게이터는, 일시 페어 렌탈 락 레벨 커멘드가 발생했을 때에, 어플리케이션에 EC_DVD_PARENTAL_LEVEL_CHANGE 이벤트를 송신해, AcceptParentalLevelChange 를 통해서 어플리케이션의 응답을 수신할 때까지, 동작을 블록 한다.

이 플래그가 FALSE 로 설정되어 있으면(자), 네비게이터가 일시 페어 렌탈 락 레벨 커멘드를 받아, 현재의 페어 렌탈 락 레벨이 너무 낮은 경우에, 네비게이터는 커멘드를 자동적으로 거부해, 그 커멘드가 거부되었을 때에 이동하도록(듯이) 디스크상에서 지시받고 있는 패스에 분기 한다. 다음에, 어느 레벨이 필요한가를 어플리케이션에 통지하는 EC_DVD_PARENTAL_LEVEL_CHANGE 이벤트를 송신한다. 다음번의 시행이 성공하도록(듯이), 재생을 정지해, 패스워드 다이알로그 박스를 표시해, 무비의 재생을 재개할지 어떨지는, 어플리케이션측에서 판단한다.

DVD_HMSF_TimeCodeEvents | EC_DVD_CURRENT_TIME 이벤트와 함께 건네받는 구래의 BCD 포맷은 아니고,DVD_HMSF_TIMECODE 포맷으로 EC_DVD_CURRENT_HMSF_TIME 타임 이벤트를 수신할 경우에, 이 플래그를 TRUE 로 설정한다. DVD_HMSF_TIMECODE 포맷이 취급하기 쉽다. BCD 포맷을 사용하는 어플리케이션과의 하위 호환성을 유지하기 위해서(때문에), 이 플래그는, 디폴트에서는 FALSE 로 설정된다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
이루어 | 모두

참조

DVD 커멘드 플래그

IDvdControl2::SetState

IDvdControl2 인터페이스

현재의 디스크의 위치와 DVD 네비게이터 필터 상태를 보존한다.

구문

HRESULT SetState(
    IDvdState*pState,
    DWORD    dwFlags,
    IDvdCmd  **ppCmd
);

파라미터

pState
[in] 스테이트 정보가 저장 되고 있는 오브젝트의 IDvdState 인터페이스에의 포인터.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

성공하면 S_OK 를 돌려준다. 그 이외의 경우는 HRESULT 값을 돌려준다.

주의

DVD 네비게이터는, 지정된 상태 오브젝트에 저장 된 위치 정보를 사용해, 재생 위치를 디스크 위에의 특정의 위치에 되돌린다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::RestoreBookmark」를 참조할것.

IDvdControl2::SetSubpictureState

IDvdControl2 인터페이스

서브 픽쳐의 표시를 온, 오프 한다.

구문

HRESULT SetSubpictureState(
    BOOL bState,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

bState
[in] 서브 픽쳐의 표시를 온으로 할지 어떨지를 지정하는 불형의 값. TRUE 를 지정 하면, 그 이후의 재생으로 서브 픽쳐가 표시된다.
dwFlags
[in] 커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
[out] DVD 커멘드의 동기에게 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 First Play 도메인내에 있다.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

보통, 서브 픽쳐 스트림은, 메뉴에서는 버튼 텍스트나 버튼의 그래픽에, 비디오의 재생에서는 자막, 크레디트, 그 외의 오버레이 그래픽에 사용된다. 서브 픽쳐를 자막 방송과 혼동 해서는 안 된다. 자막 방송은, 비디오 스트림의 내부에 encode 되고 있다. 일반적으로, 이 메소드는, DVD 네비게이터 필터가 DVD Title 도메인내에서 비디오를 재생하고 있는 동안에 비디오에 거듭해 표시되는 서브 픽쳐를 제어하는 것을 목적으로 하고 있다.

이 메소드는, Annex J "Sub-picture_Stream_Change" 커멘드의 제 2 파라미터에 상당한다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Sub-picture_stream_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

참조

SelectSubpictureStream

IDvdControl2::ShowMenu

IDvdControl2 인터페이스

지정된 메뉴가 있으면 표시한다.

구문

HRESULT ShowMenu(
    DVD_MENU_ID MenuID
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

파라미터

MenuID
[in] 표시하는 메뉴를 지정하는 DVD_MENU_ID 값.
dwFlags
커멘드 동기 옵션을 지정하는 1 개(살) 이상의 DVD_CMD_FLAGS 값을 포함한 비트 플래그.
ppCmd
커멘드를 DVD 네비게이터 필터와 동기 시키기 위해서(때문에) 사용할 수 있는 IDvdCmd 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | MenuID 값이 범위외이다.
VFW_E_DVD_INVALIDDOMAIN | 무효인 도메인.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

비디오 매니저 메뉴 (VMGM)는, Title 도메인 또는 Video Title Set 도메인으로부터 액세스 할 수 없으면 안 된다. 비디오 타이틀 세트 메뉴 (VTSM)는, VMGM 를 통해서 밖에 액세스 할 수 없어도 좋다. 각 VTSM (쳅터, 앵글, 오디오 스트림, 서브 픽쳐 스트림용)아래의 서브 메뉴는, 그 VTSM 를 통해서 밖에 액세스 할 수 없다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CDvdCore::RootMenu」 및 「CDvdCore::TitleMenu」를 참조할것.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 | 유효한 도메인
Menu_Call | 모두

참조

DVD 메뉴의 조작

IDvdControl2::StillOff

IDvdControl2 인터페이스

재생을 재개해, 정지 모드를 캔슬한다.

구문

HRESULT StillOff(void);

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_UNEXPECTED | DVD 네비게이터 필터가 메뉴 도메인내에 있어, 메뉴에 버튼이 있다.
VFW_E_DVD_INVALIDDOMAIN | 무효인 도메인.
VFW_E_DVD_OPERATION_INHIBITED | UOP 컨트롤이 처리를 금지하고 있다.

주의

still 는 디스크에 저장 되고 있는 정지화면상이다. 이것은, 유저가 Pause 버튼을 클릭했을 때에 표시되는 정지화면과는 다르다. DVD 네비게이터는 정지화면상을 검출 하면, 어플리케이션에 EC_DVD_STILL_ON 메세지를 송신해, 정지화면 보관 유지 모드로 이행해 화면을 표시해,StillOff 가 불려 갈 때까지 재생을 재개하지 않는다.

DVD 네비게이터가 정지화면 보관 유지 모드로 되어 있지 않은 경우, 이 메소드는 아무것도 하지 않는다.

메뉴를 정지화면으로서 표시할 수도 있지만, 메뉴 도메인에서는 DVD 네비게이터가 재생 재개 위치의 정보를 취득할 수 없기 때문에, 메뉴 도메인내에서 이 메소드를 호출해서는 안 된다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Still_Off DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

IDvdControl2::Stop

IDvdControl2 인터페이스

DVD 네비게이터를 DVD Stop 도메인에 이행 시키는 것으로, 타이틀 또는 메뉴의 재생을 정지한다.

구문

HRESULT Stop(void);

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 무효인 도메인.

주의

이 메소드를 호출하면, DVD 네비게이터는 Stop 도메인으로 이행하지만, DVD 필터 그래프 전체는, 언제라도 재생을 재개할 수 있는 실행 상태에 머무른다. 유저는 Stop 도메인으로부터 메뉴를 표시하거나 임의의 "Play" 메소드를 사용해 재생을 직접 시작 하거나 할 수가 있다.

다음의 표는, 이 메소드명이 대응하는 Annex J 커멘드명, 및 이 메소드가 유효한 도메인을 나타내고 있다.

Annex J 커멘드명 유효한 도메인
Stop DVD_DOMAIN_FirstPlay
DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title


IDvdGraphBuilder 인터페이스

IDvdGraphBuilder 인터페이스는,DVD 그래프 빌더 오브젝트로 이행 된다. RenderDvdVideoVolume 메소드는, 시스템 위에의 이용 가능한 소프트웨어와 하드웨어로부터, DVD 비디오를 재생하기 위한 필터 그래프를 자동적으로 생성 한다. DVD 필터 그래프를 생성 하는 방법과 필요한 모든 인터페이스에의 포인터를 입수하는 방법에 대해서는, 「DVD 필터 그래프의 생성」을 참조할것. DVDSample 어플리케이션의 DvdCore.cpp 에도, 이 과정이 나타나고 있다.

주 : DVD 필터 그래프는, 하드웨어 또는 소프트웨어의 MPEG-2 디코더를 필요로 한다. 이것은 DirectShow 에는 포함되지 않았다. 거기서, DVD 필터 그래프의 생성에 앞서, DirectShow 호환의 써드파티제의 디코더를 컴퓨터에 인스톨 할 필요가 있다.

일반적으로,RenderDvdVideoVolume 로 생성 된 그래프내의 개별의 필터를 추가, 삭제, 접속, 절단, 또는 액세스 해서는 안 된다. 이러한 조작을 실시하면, 클린 업 코드에 혼란을 초래하는 경우가 있다. DvdGraphBuilder 오브젝트의 목적은, DVD 비디오 어플리케이션의 개발을 간략화하는 것이다. 특별한 목적을 가지는 특수한 그래프가 필요한 경우는, 필터 그래프 전체를 수동으로 생성 할 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDvdGraphBuilder 메소드 | 설명
GetFiltergraph | DVD 비디오 그래프 빌더 오브젝트가 사용하는 필터 그래프의 IGraphBuilder 인터페이스를 취득한다.
GetDvdInterface | DVD 비디오 재생 그래프내의 특정의 인터페이스 포인터를 취득한다. 이것에 의해, DVD 비디오 재생의 개발이 간략화된다.
RenderDvdVideoVolume | DVD 비디오의 볼륨 재생에 관한 유저 지정에 따라, 필터 그래프의 생성을 완료한다.

IDvdGraphBuilder::GetDvdInterface

IDvdGraphBuilder 인터페이스

DVD 비디오 재생 그래프내의 특정의 인터페이스 포인터를 취득한다. 이것에 의해, DVD 비디오 재생의 개발이 간략화된다.

구문

HRESULT GetDvdInterface(
    REFIID riid,
    void **ppvIF
    );

파라미터

riid
[in] 목적의 인터페이스의 IID.
ppvIF
[out] 취득된 인터페이스에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

DirectShow 의 이행이 돌려주는 값에는, 다음의 값이 포함된다.
E_INVALIDARG | ppvIF 파라미터가 무효이다.
E_NOINTERFACE | riid 파라미터값이 지원되어 있지 않다.
VFW_E_DVD_GRAPHNOTREADY | 이 인터페이스를 취득하기 이전에,IDvdGraphBuilder::RenderDvdVideoVolume 메소드를 개입시켜 그래프가 생성되어 있지 않다.

주의

이 메소드를 사용해,IDvdControl2 와 IDvdInfo2 인터페이스를 취득해 DVD 비디오 볼륨의 재생을 제어하거나IAMLine21Decoder 인터페이스를 취득해 자막 방송 표시의 온과 오프를 바꾸는 것. 이 메소드를 사용해,IBasicVideo ,IVideoWindow , 및 IBasicAudio 의 각 인터페이스를 취득할 수도 있다. 오디오 렌더러가 오디오를 렌더링 하는 경우만,IBasicAudio 에의 포인터가 필요하다.

인터페이스의 사용이 종료하면(자), 다음의 코드를 사용해 이것을 해방할 필요가 있다.

*ppvIF->Release();

이 인터페이스를 사용 하면, DVD 비디오 재생 그래프내의오버레이 믹서의 선두의 입력 핀 (프라이머리 비디오 스트림)으로부터,IMixerPinConfig2 인터페이스를 취득할 수 있다. DVD 비디오 그래프내의 오버레이 믹서로부터,IDDrawExclModeVideo 인터페이스도 취득할 수 있다. 이 인터페이스는, 게임에 따라서는, DirectDraw 의 배타 모드로 비디오를 재생할 경우에 필요하다. 다른 인터페이스와는 달라,GetDvdInterface 를 호출하기 전에,RenderDvdVideoVolume 메소드를 사용해 그래프를 생성 할 필요는 없다. 이 인터페이스는,RenderDvdVideoVolume 메소드를 사용해 그래프를 생성 하기 전에 취득할 필요가 있다.

IDvdGraphBuilder::GetFiltergraph

IDvdGraphBuilder 인터페이스

DVD 비디오 그래프 빌더 오브젝트가 사용하는 필터 그래프의 IGraphBuilder 인터페이스를 취득한다.

구문

HRESULT GetFiltergraph(
    IGraphBuilder **ppGB
    );

파라미터

ppGB
[out] DVD 비디오 그래프 빌더 오브젝트가 사용하고 있는 IGraphBuilder 인터페이스에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서는,ppGB 가 무효의 경우, E_INVALIDARG 를 돌려준다.

주의

IGraphBuilder 인터페이스의 사용이 종료하면(자), 다음의 코드를 사용해 이것을 해방할 필요가 있다.

*ppGB->Release();

IDvdGraphBuilder::RenderDvdVideoVolume

IDvdGraphBuilder 인터페이스

DVD 비디오의 볼륨 재생에 관한 유저 지정에 따라, 필터 그래프의 생성을 완료한다.

구문

HRESULT RenderDvdVideoVolume(
    LPCWSTR lpcwszPathName,
    DWORD dwFlags,
    AM_DVD_RENDERSTATUS *pStatus
    );

파라미터

lpcwszPathName
[in] 재생하는 DVD 비디오 볼륨의 패스에의 포인터. NULL 의 경우가 있다.
dwFlags
[in] 디코더의 타입을 나타내는 AM_DVD_GRAPH_FLAGS 열거형의 멤버. 디코더의 타입에는, 하드웨어, 소프트웨어, 또는 하드웨어와 소프트웨어의 혼합이 있어, 지정된 디코더가 필터 그래프에 포함된다. 디폴트값은, 최대 하드웨어 디코드 (AM_DVD_HWDEC_PREFER )이다.
pStatus
[out] 취득된 AM_DVD_RENDERSTATUS 구조체에의 포인터. 장해가 있었을 경우는, 그 장해가 구조체에 나타난다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. DirectShow 의 이행의 반환값에는, 다음의 값이 포함된다.
E_INVALIDARG | dwFlags 파라미터가 지정하는 옵션이 경합 하고 있다. 또는,pStatus 의 포인터가 불량이다.
S_FALSE | 그래프는 생성 되었지만, 완전하지 않다. pStatus 파라미터에, 문제의 상세가 돌려주어진다.
S_OK | 성공. 재생 그래프가 올바르고 생성 되어 모든 스트림이 렌더링 되어 DVD 비디오 볼륨이 지정된, 또는 발견되었다.
VFW_E_DVD_DECNOTENOUGH | AM_DVD_HWDEC_ONLY 또는 AM_DVD_SWDEC_ONLY 가 지정되었지만, 하드웨어 또는 소프트웨어의 디코더가 부족하기 위해(때문에), 모든 스트림을 디코드할 수 없다.
VFW_E_DVD_RENDERFAIL | 그래프의 생성중에, 어떠한 기본적인 에러가 발생했다. DVD 네비게이터 필터, 비디오 렌더러, 또는 오디오 렌더러가 인스턴스화되어 있지 않은, 접속이나 핀 열거가 단지 실패한, 또는 스트림이 렌더링 되지 않는, 등이 원인으로서 생각된다.

주의

AM_DVD_RENDERSTATUS 구조체는, 이 메소드의 실패 코드를 나타낸다. 이 메소드가 S_FALSE 를 돌려주는 원인에는, 다음의 것이 포함된다.

  • 그래프는 완전하게 생성 되었지만, 다음의 몇개의 조건이 해당한다.
    • 오버레이 믹싱이 동작하지 않는다. 어플리케이션은 AM_DVD_NOVPE 플래그를 사용하고 있지 않았기 때문에, 비디오 스트림을 오버레이 믹서로 설정할 수 없다. 이 케이스에서는, 비디오가 소프트웨어로 디코드되고 있으면, 어플리케이션은 유저에 대해서, 비디오가 표시되지 않는 것을 전하는 정보를 가질 수가 있다. 하드웨어 디코드 비디오는, 하드웨어 비디오 디코더의 NTSC 출력 포토에 접속하고 있는 TV 상에서만 표시된다.
    • 비디오 디코더가 Line 21 데이터를 생성하지 않는다. 어플리케이션에서는, 디코더가 원인으로 자막 방송을 이용할 수 없는 것을 전하는 경고나 메세지를 표시할 수 있다.
    • 볼륨 패스가 지정되어 있지 않기 때문에, 재생하는 DVD 비디오 볼륨을 DVD 네비게이터가 검색할 수 없다. 재생이 시작 할 경우에, 드라이브에 DVD 비디오디스크가 세트되어 있지 않은 경우, 어플리케이션은 유저에게 디스크를 삽입하도록(듯이) 요구할 수가 있다.
  • 일부의 스트림이 렌더링 되지 않았다, 또는 스트림이 전혀 렌더링 되지 않았다. 어플리케이션에서는, 유저에 대해서, 일부의 스트림을 재생할 수 없는 것을 전할 수가 있다.

이 메소드를 사용 하면, DVD 비디오 필터나 재생하는 볼륨을 이해하고 있지 않아도, 그래프를 생성 할 수 있다. DVD 비디오 그래프 빌더는,lpcwszPathName 가 NULL 이거나 DVD 네비게이터 필터가 디폴트로 재생하는 DVD 비디오 볼륨을 찾아낼 수가 없었던 경우에서도, 그래프를 생성 할 수가 있다. 어플리케이션에서는,IDvdControl::SetRoot 메소드를 사용하는 것으로, 다음에 볼륨을 지정할 수 있다.


IDvdInfo2 인터페이스

DVD 네비게이터 소스 필터에 의해 이행 되는 IDvdInfo2 인터페이스는, 디스크의 다양한 속성이나 DVD 네비게이터 상태를 문의하는 메소드를 갖추고 있다. IDvdInfo2 는,IDvdControl2 와 대가 되는 인터페이스이다. IDvdInfo2 는 DVD 네비게이터의 "get" 메소드의 집합이며,IDvdControl2 는 "set" 메소드의 집합이다. 이것들 2 개의 인터페이스는, DVD Annex J 사양의 범위를 넘는 DVD 의 네비게이션 기능과 재생 기능을 갖추고 있다.

주 : 이러한 메소드의 일부가 제공하는 정보는, DVD 네비게이터로부터 어플리케이션의 메시지 루프에 송신되는 이벤트 통지를 통해서 취득할 수도 있다. 예를 들어, 현재의 DVD 도메인을 취득하려면 ,IDvdInfo2::GetCurrentDomain 를 호출하거나 어플리케이션의 메시지 루프로 EC_DVD_DOMAIN_CHANGE 이벤트를 처리해, 이벤트의 lParam1 파라미터로부터 새로운 도메인을 추출할 수도 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDvdInfo2 메소드 | 설명
메뉴
GetButtonAtPosition | 표시 윈도우내의 지정된 위치에 있는 버튼을 취득한다.
GetButtonRect | 지정된 버튼의 직사각형의 좌표를 취득한다.
GetCurrentButton | 이용할 수 있는 버튼의 수와 현재 선택되고 있는 버튼의 번호를 취득한다.
GetDefaultMenuLanguage | 디폴트의 메뉴 언어를 취득한다.
GetMenuLanguages | 디스크 위에의 모든 메뉴로 이용할 수 있는 모든 언어를 취득한다.
GetVMGAttributes | 비디오 매니저 메뉴의 모든 비디오 스트림, 오디오 스트림, 및 서브 픽쳐 스트림의 속성을 취득한다.
타이틀
GetNumberOfChapters | 지정된 타이틀의 쳅터의 수를 취득한다.
GetTitleAttributes | 지정된 타이틀과 그 메뉴의 모든 비디오 스트림, 오디오 스트림, 및 서브 픽쳐 스트림의 속성을 취득한다.
GetTotalTitleTime | 현재의 타이틀의 총재생 시간을 취득한다.
디스크 정보
GetAllSPRMs | 모든 시스템 파라미터 레지스터 (SPRM)의 현재의 내용을 취득한다.
GetAllGPRMs | 모든 범용 파라미터 레지스터 (GPRM)의 현재의 내용을 취득한다.
GetCurrentUOPS | 컨텐츠의 생성자가 명시적으로 무효로 한 네비게이션 커멘드가 현재의 디스크 위치에 있으면, 그것을 나타내는 플래그세트를 취득한다.
GetDiscID | 지정된 DVD 에 대해서 시스템이 생성한 64 비트의 "일의 " 인 식별 번호를 취득한다.
GetDVDVolumeInfo | 현재의 DVD 볼륨 정보를 취득한다.
비디오 스트림
GetCurrentAngle | 현재의 앵글 블록내의 이용할 수 있는 앵글의 수와 현재 선택되고 있는 앵글 번호를 취득한다.
GetCurrentVideoAttributes | 현재의 타이틀 또는 메뉴의 비디오 속성을 취득한다.
오디오 스트림
GetAudioAttributes | 현재의 타이틀 또는 메뉴의 지정된 오디오 스트림의 속성을 취득한다.
GetAudioLanguage | 현재의 타이틀내의 지정된 오디오 스트림의 언어를 취득한다.
GetCurrentAudio | 이용할 수 있는 오디오 스트림의 수와 현재 선택되고 있는 오디오 스트림의 번호를 취득한다.
GetDecoderCaps | DVD 디코더의 비디오, 오디오, 및 서브 픽쳐의 최대 데이터 레이트 (역방향 및 순서 방향)와 지원 하고 있는 오디오의 종류 (Dolby AC-3, MPEG-2, DTS, SDDS, LPCM)를 취득한다.
GetDefaultAudioLanguage | 디폴트의 오디오 언어를 취득한다.
GetKaraokeAttributes | 현재의 타이틀 또는 메뉴의 지정된 오디오 스트림의 가라오케 속성을 취득한다.
IsAudioStreamEnabled | 지정된 오디오 스트림이 현재의 타이틀로 유효하게 되어 있는지 어떤지를 판별한다.
서브 픽쳐 스트림
GetCurrentSubpicture | 현재의 타이틀의 이용할 수 있는 서브 픽쳐 스트림의 수, 현재 선택되고 있는 서브 픽쳐 스트림 번호, 및 서브 픽쳐 상태를 취득한다.
GetDefaultSubpictureLanguage | 디폴트의 서브 픽쳐 언어를 취득한다.
GetSubpictureAttributes | 현재의 타이틀 또는 메뉴의 지정된 서브 픽쳐 스트림의 속성을 취득한다.
GetSubpictureLanguage | 현재의 타이틀내의 지정된 서브 픽쳐 스트림의 언어를 취득한다.
IsSubpictureStreamEnabled | 지정된 서브 픽쳐 스트림이 현재의 타이틀로 유효하게 되어 있는지 어떤지를 판별한다.
페어 렌탈 락 레벨
GetPlayerParentalLevel | DVD 네비게이터의 현재의 페어 렌탈 락 레벨 및 ISO 3166 국 코드의 설정을 취득한다.
GetTitleParentalLevels | 특정의 타이틀에 정의되고 있는 페어 렌탈 락 레벨을 취득한다.
DVD 네비게이터 스테이트 정보
GetCmdFromEvent | EC_DVD_CMD_START 이벤트, EC_DVD_CMD_END 이벤트 또는 VFW_E_DVD_CMD_CANCELLED 이벤트로부터 IDvdCmd 오브젝트를 취득한다.
GetCurrentDomain | 현재 DVD 네비게이터가 놓여져 있는 DVD 도메인을 취득한다.
GetCurrentLocation | 현재의 재생 위치를 취득한다.
GetDVDDirectory | DVD 네비게이터로 설정되어 있는 루트 디렉토리를 취득한다.
GetState | 디스크 위치와 DVD 네비게이터 스테이트 정보가 저장 되고 있는 북마크를 취득한다.
DVD 텍스트 캐릭터 라인
GetDVDTextNumberOfLanguages | 현재의 DVD 또는 디스크면의 텍스트 언어의 수를 취득한다.
GetDVDTextLanguageInfo | 지정된 텍스트 캐릭터 라인 언어 블록의 정보를 취득한다.
GetDVDTextStringAsNative | 지정된 언어의 텍스트 캐릭터 라인을 바이트의 배열로서 취득한다.
GetDVDTextStringAsUnicode | 지정된 언어의 텍스트 캐릭터 라인을 Unicode™ 로 취득한다.

IDvdInfo2::GetAllGPRMs

IDvdInfo2 인터페이스

모든 범용 파라미터 레지스터 (GPRM)의 현재의 내용을 취득한다.

구문

HRESULT GetAllGPRMs(
  GPRMARRAY *pRegisterArray
);

파라미터

pRegisterArray
[out] 16 개의 현재의 GPRM 값 모든 것을 받는 GPRMARRAY 에의 포인터. 「주의」를 참조할것.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.

주의

GPRM 는, 각 디스크가 일시적으로 데이터를 저장 하기 위해서 각각 독자적인 방법으로 사용할 수 있는 16 비트 레지스터이다. Dvdif.idl 파일에는, 이하의 typedef 가 포함되어 있다.

typedef WORD DVD_REGISTER;
typedef DVD_REGISTER    GPRMARRAY[16];
typedef DVD_REGISTER    SPRMARRAY[24];

주 : DVD 네비게이터를 사용하는 플레이어 어플리케이션은,Annex J 의 재생 기능 또는 네비게이션 제어 기능을 사용하는 한, 이러한 레지스터에 액세스 할 필요는 없다. 이 메소드는, 고도의 기능을 이행 한 플레이어 어플리케이션용으로 준비되어 있다. DVD 의 사양 및 재생하는 특정의 디스크에서의 GPRM 의 사용법이 완전하게 모르는 한, 직접 GPRM 를 변경하지 않는 것이 좋다.

참조

IDvdControl2::SetGPRM

IDvdInfo2::GetAllSPRMs

IDvdInfo2 인터페이스

모든 시스템 파라미터 레지스터 (SPRM)의 현재의 내용을 취득한다.

구문

HRESULT GetAllSPRMs(
  SPRMARRAY *pRegisterArray
);

파라미터

pRegisterArray
[out] SPRM 의 배열의 주소를 받는 SPRMARRAY 형의 변수에의 포인터. 「주의」를 참조할것.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.

주의

24 개의 SPRM 를 사용해, 현재의 언어, 서브 픽쳐, 및 그 외의 네비게이션 데이터에 관한 정보를 저장 한다. Dvdif.idl 파일에는, 이하의 typedef 가 포함되어 있다.

typedef WORD DVD_REGISTER;
typedef DVD_REGISTER    GPRMARRAY[16];
typedef DVD_REGISTER    SPRMARRAY[24];

주 : 플레이어 어플리케이션은, 표준 네비게이션 기능을 사용하는 한, 이러한 레지스터에 액세스 할 필요는 없다. 이러한 레지스터를 유효하게 활용하려면 , 이 문서에 기재되어 있는 내용보다 자세한 DVD 네비게이션 커멘드에 관한 지식이 필요하게 된다. 이하의 겉(표)는, 각 레지스터의 내용의 일람을 나타내고 있다. 워드내의 비트는, b0 (최하정도 비트)로부터 b15 (최상정도 비트)로서 표기되고 있다.

레지스터 | 컨텐츠
0 | ISO-639 언어 코드 (소문자 2 문자의 ASCII 문자). 디폴트의 값이 정의되어 있지 않다.
1 | 하위 4 비트 (b0 ~ b3)에 오디오 스트림 번호 (0 ~ 7) 또는 15 (없음)가 저장 된다. 디폴트값은 15.
2 | 하위 6 비트 (b0 ~ b5)에 서브 픽쳐 번호 (0 ~ 31) 또는 62 (없음) 또는 63 (강제 서브 픽쳐용의 더미 스트림)이 저장 된다. 제 7 비트 (b6)에 서브 픽쳐 표시 플래그 (0 = 서브 픽쳐를 표시하지 않는다)가 저장 된다. 디폴트값은 62.
3 | 하위 4 비트 (b0 ~ b3)에 앵글 번호 (1 ~ 9)가 저장 된다. 디폴트값은 1.
4 | 하위 7 비트 (b0 ~ b6)에 타이틀 번호 (1 ~ 99)가 저장 된다. 디폴트값은 1.
5 | 하위 7 비트 (b0 ~ b6)에 현재의 VTS 내의 타이틀 번호 (1 ~ 99)가 저장 된다. 디폴트값은 1.
6 | 하위 15 비트 (b0 ~ b14)에 현재의 타이틀내의 PGC 번호 (1 ~ 32767)가 저장 된다. 디폴트의 값이 정의되어 있지 않다.
7 | 하위 10 비트 (b0 ~ b9)에 쳅터 번호 (1 ~ 99)가 저장 된다. 디폴트값은 1 이다. 타이틀이 one_sequential_PGC_title 가 아닌 경우, 값은 미정도리가 된다.
8 | 상위 6 비트 (b10 ~ b15)에 버튼 번호 (1 ~ 36)가 저장 된다. 디폴트값은 1024 (버튼 1)이다.
9 | 초 단위의 타이머 카운트 (0 ~ 65535). 디폴트값은 0.
10 | 하위 15 비트 (b0 ~ b14)에 현재의 타이틀내의 PGC 번호 (1 ~ 32767)가 저장 된다. 디폴트의 값이 정의되어 있지 않다.
11 | 6 개의 플래그 (b2: 믹스 ch2 를 ch1 에, b3: 믹스 ch3 를 ch1 에, b4: 믹스 ch4 를 ch1 에, b10: 믹스 ch2 를 ch0 에, b11: 믹스 ch3 를 ch0 에, b12: 믹스 ch4 를 ch0 에). 플래그값 0 은 믹스 하지 않는 것을 의미한다. 모든 플래그의 디폴트값은 0 이다. 가라오케 스트림을 재생하지 않는 경우, 값은 미정도리가 된다.
12 | ISO-3166 국 코드 (대문자 2 문자의 ASCII 문자) 또는 65535 (지정 없음). 디폴트의 값이 정의되어 있지 않다.
13 | 하위 4 비트 (b0 ~ b3)에 페어 렌탈 락 레벨 (1 ~ 8) 또는 15 (없음)가 저장 된다. 디폴트의 값이 정의되어 있지 않다.
14 | b8 ~ b9 에 우선 디스플레이 모드 (0 = 4:3, 3 = 16:9)가 저장 된다. b10 ~ b11 에 현재의 비디오 출력 모드 (0 = 표준 [4:3 또는 16:9], 1 = 빵-스캔, 2 = 레터박스)가 저장 된다. 디폴트의 값이 정의되어 있지 않다.
15 | 9 개의 플래그 (b2: SDDS 가라오케, b3: DTS 가라오케, b4: MPEG 가라오케, b6: Dolby Digital 가라오케, b7: PCM 가라오케, b10: SDDS 재생, b11: DTS 재생, b12: MPEG 재생, b14: Dolby Digital 재생). 플래그값 0 은 기능이 없는 것을 나타내, 플래그값 1 은 기능이 있는 것을 나타낸다. 디폴트의 값이 정의되어 있지 않다.
16 | ISO-639 국 코드 (소문자 2 문자의 ASCII 문자) 또는 65535 (지정 없음). 디폴트값은 65535.
17 | 언어 확장 코드 (0 = 지정 이루어, 1 = 표준 오디오, 2 = 시력의 약한 사람을 위한 오디오, 3 = 디렉터 코멘트 #1, 4 = 디렉터 코멘트 #2). 디폴트값은 0.
18 | ISO-639 국 코드 (소문자 2 문자의 ASCII 문자) 또는 65535 (지정 없음). 디폴트값은 65535. 디폴트값은 65535.
19 | 언어 확장 코드 (0 = 지정 이루어, 1 = 표준 자막, 2 = 큰 자막, 3 = 어린이용 자막, 5 = 표준 자막 방송, 6 = 큰 자막 방송, 7 = 어린이용 자막 방송, 9 = 강제 표시 자막, 13 = 디렉터 코멘트, 14 = 큰 디렉터 코멘트, 15 = 어린이용 디렉터 코멘트). 디폴트값은 0.
20 | 하위 8 비트 (b0 ~ b7)에 지역 번호 (1 ~ 8)가 저장 된다.

IDvdInfo2::GetAudioAttributes

IDvdInfo2 인터페이스

현재의 타이틀 또는 메뉴의 지정된 오디오 스트림의 속성을 취득한다.

구문

HRESULT GetAudioAttributes(
  ULONG ulStream,
  DVD_AudioAttributes *pATR
);

파라미터

ulStream
[in] 문의의 대상이 되는 속성을 가지는 오디오 스트림을 지정하는 ULONG 형의 변수. 「주의」를 참조할것.
pATR
[out] 지정된 오디오 스트림의 속성이 저장 되는 DVD_AudioAttributes 구조체에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.
VFW_E_DVD_NO_ATTRIBUTES | 어떠한 이유에 의해, 스트림의 오디오 속성을 취득할 수 없다.
E_POINTER | 무효인 인수.

주의

ulStream 는 0 에서 7 의 사이의 인덱스 번호 또는 다음의 값이다.

DVD_DEFAULT_AUDIO_STREAM | 디폴트의 오디오 스트림의 속성을 문의한다.
DVD_STREAM_DATA_CURRENT | 현재의 스트림을 문의한다.
DVD_STREAM_DATA_VMGM | VMGM 의 오디오 속성을 문의한다.
DVD_STREAM_DATA_VTSM | VTSM 의 오디오 속성을 문의한다.

이 메소드의 사용예에 대해서는, DVDSample 의 「CDvdCore::GetAudioAttributes()」 및 「CAudioLangDlg::GetAudioLang」를 참조할것.

IDvdInfo2::GetAudioLanguage

IDvdInfo2 인터페이스

현재의 타이틀내의 지정된 오디오 스트림의 언어를 취득한다.

구문

HRESULT GetAudioLanguage(
  ULONG ulStream,
  LCID *pLanguage
);

파라미터

ulStream
[in] 언어를 취득하는 오디오 스트림 번호.
pLanguage
[out] 언어 정보를 받는 LCID 에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | pLanguage 파라미터가 NULL 이다.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 유효한 도메인내에 없다.

주의

이 메소드는 메뉴의 언어는 돌려주지 않는다. 스트림에 미지의 언어가 포함되어 있는 경우, 이 메소드는,pLanguage 가 가리키는 값을 제로로 설정한다. pLanguage 로부터 읽어내 가능한 캐릭터 라인명을 생성 하려면 , 다음과 같이 Microsoft® Win32® GetLocaleInfo 함수를 호출한다. LOCALE_SENGLANGUAGE 는 로케일 정보형이며,pszString 는 요구된 데이터를 받는 버퍼에의 포인터이며,cbSize 는 pszString 의 사이즈를 지정한다.

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

참조

IDvdControl2::SelectAudioStream

IDvdInfo2::GetButtonAtPosition

IDvdInfo2 인터페이스

표시 윈도우내의 지정된 위치에 있는 버튼을 취득한다.

구문

HRESULT GetButtonAtPosition(
  POINT point,
  ULONG *puButtonIndex
);

파라미터

point
[in] Win32 WM_MOUSEMOVE 메세지를 사용해 취득된 현재의 마우스 포인터의 위치.
puButtonIndex
[out] 현재의 마우스 포인터 위치에 있는 버튼의 인덱스 (1 에서 36 의 사이)를 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | puButtonIndex 파라미터가 무효이다.
VFW_E_DVD_NO_BUTTON | point 에 버튼이 없다.

주의

보통, 이 메소드는, DVD 메뉴 표시 윈도우내의 마우스 포인터의 이동에 응해 불려 간다. 버튼 번호를 취득하기 전에, 반드시 HRESULT 로 성공을 확인하는 것. 지정된 위치에 버튼이 있었을 경우, 이 메소드는 puButtonIndex 의 값의 설정만을 실시한다. DVD 버튼은 강조 표시되는 직사각형을 가지지 않는 경우가 있어, 버튼의 직사각형 끼리는 서로 겹치는 일이 있어, 버튼의 직사각형은 반드시 버튼의 외관과 일치하는 것은 아니다.

참조

IDvdControl2::ActivateButton

IDvdInfo2::GetButtonRect

IDvdInfo2 인터페이스

지정된 메뉴 버튼의 직사각형의 좌표를 취득한다. 이 메소드는 현재 이행되어 있지 않다.

구문

HRESULT GetButtonRect(
  ULONG ulButton
  RECT *pRect
);

파라미터

ulButton
[in] 버튼을 지정하는 1 에서 36 의 사이의 ULONG 형의 변수.
pRect
[out] 버튼의 직사각형의 좌표를 받는 RECT 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

E_NOTIMPL 이 메소드는 현재 이행되어 있지 않다.

IDvdInfo2::GetCmdFromEvent

IDvdInfo2 인터페이스

EC_DVD_CMD_START 이벤트 또는 EC_DVD_CMD_END 이벤트로부터 IDvdCmd 오브젝트를 취득한다.

구문

HRESULT GetCmdFromEvent(
  LONG_PTR lParam1,
  IDvdCmd **ppCmdObj
);

파라미터

lParam1
[in] 이벤트 통지의 lParam1 파라미터.
ppCmdObj
[out] 이벤트를 발생시킨 커멘드에 관련지을 수 있고 있는 IDvdCmd 커멘드 오브젝트에의 포인터의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_FAIL | 커멘드가 존재하지 않는다.
E_POINTER | 무효인 인수.

주의

이 메소드는, EC_DVD_CMD_START 이벤트 또는 EC_DVD_CMD_END 이벤트의 lParam1 파라미터를, 이벤트를 발생시킨 커멘드에 관련지을 수 있고 있는 IDvdCmd 오브젝트에 맵 한다. 그 후는,WaitForStart 또는 WaitForEnd 를 호출하는 것으로, 그 커멘드에 관련하는 DVD 네비게이터의 블록 동작을 제어할 수가 있다. IDvdCmd 오브젝트는 DVD 네비게이터에 의해 생성 되어 돌려주어지는 포인터의 참조 카운트는 이미 증가하고 있기 (위해)때문에,WaitForStart 또는 WaitForEnd 로부터 동작이 돌아온 후, IDvdCmd 오브젝트를 해방할 필요가 있다.

참조

DVD 커멘드의 동기화, EC_DVD_CMD_START ,EC_DVD_CMD_END

IDvdInfo2::GetCurrentAngle

IDvdInfo2 인터페이스

현재의 앵글 블록내의 이용할 수 있는 앵글의 수와 현재 선택되고 있는 앵글 번호를 취득한다.

구문

HRESULT GetCurrentAngle(
  ULONG *pulAnglesAvailable,
  ULONG *pulCurrentAngle
);

파라미터

pulAnglesAvailable
[out] 이용할 수 있는 앵글의 수를 받는 ULONG 형의 변수에의 포인터. 1 개의 앵글 블록내에는 최대 9 개의 앵글이 있어, 각각 1 에서 9 의 번호가 차인다. 값이 1 의 경우,DVD 네비게이터는 앵글 블록내에 없다.
pulCurrentAngle
[out] 현재의 앵글 번호를 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 초기화되어 있지 않은, 또는 유효한 도메인내에 없다.

주의

오디오 스트림과 서브 픽쳐 스트림의 인덱스는 시작값이 0 이지만, 앵글과 메뉴 버튼의 인덱스는 시작값이 1 인 점에 주의 해야 한다. DVD 네비게이터는, 앵글 블록에 들어가기 직전에,lParam 파라미터를 1 으로 설정해 EC_DVD_ANGLES_AVAILABLE 이벤트 통지를 어플리케이션에 보낸다. 보통, 어플리케이션은, EC_DVD_ANGLES_AVAILABLE 의 이벤트 핸들러내에서 GetCurrentAngle 및 IDvdControl2::SelectAngle 를 호출한다.

이 메소드의 사용예에 대해서는, DVDSample 어플리케이션의 「CAngleDlg::MakeAngleList」를 참조할것.

참조

IDvdControl2::SelectAngle ,EC_DVD_ANGLES_AVAILABLE ,EC_DVD_ANGLE_CHANGE

IDvdInfo2::GetCurrentAudio

IDvdInfo2 인터페이스

이용할 수 있는 오디오 스트림의 수와 현재 선택되고 있는 오디오 스트림의 번호를 취득한다.

구문

HRESULT GetCurrentAudio(
  ULONG *pulStreamsAvailable,
  ULONG *pulCurrentStream
);

파라미터

pulStreamsAvailable
[out] 이용할 수 있는 오디오 스트림의 수를 받는 ULONG 형의 변수에의 포인터.
pulCurrentStream
[out] 현재의 타이틀내의 현재 선택되고 있는 오디오 스트림 번호를 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 입력된 인수가 무효이다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 초기화되어 있지 않은, 또는 유효한 도메인내에 없다.

주의

디스크 위에의 이용할 수 있는 오디오 언어를 취득하려면 ,GetCurrentAudio 를 호출한 후, 제로로부터 (pulStreamsAvailable - 1)까지의 각 스트림에 대해 GetAudioLanguage 를 호출해, 언어의 내용을 취득한다.

참조

EC_DVD_AUDIO_STREAM_CHANGE ,IDvdControl2::SelectAudioStream

IDvdInfo2::GetCurrentButton

IDvdInfo2 인터페이스

이용할 수 있는 버튼의 수와 현재 선택되고 있는 버튼의 번호를 취득한다.

구문

HRESULT GetCurrentButton(
  ULONG *pulButtonsAvailable,
  ULONG *pulCurrentButton
);

파라미터

pulButtonsAvailable
[out] 이용할 수 있는 버튼의 수를 받는 ULONG 형의 변수에의 포인터.
pulCurrentButton
[out] 현재 선택되고 있는 버튼의 번호 (1 에서 36 의 사이)를 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 포인터 인수의 1 개가 무효이다.

주의

버튼이 존재하지 않는 경우는,pulButtonsAvailable 와 pulCurrentButton 의 양쪽 모두가 제로로 설정된다.

참조

EC_DVD_BUTTON_CHANGE ,IDvdControl2::ActivateButton

IDvdInfo2::GetCurrentDomain

IDvdInfo2 인터페이스

현재 DVD 네비게이터가 놓여져 있는 도메인을 취득한다.

구문

HRESULT GetCurrentDomain(
  DVD_DOMAIN *pDomain
);

파라미터

pDomain
[out] 현재의 도메인을 받는 DVD_DOMAIN 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_UNEXPECTED | 예기치 못한 에러.
E_POINTER | 무효인 인수.

주의

이 메소드를 사용해, DVD 네비게이터가 특정의 타이틀 도메인내에서 재생을 종료했는지 어떠했는지를 테스트할 수 있다. 어플리케이션은,PlayTitle ,PlayForwards 등의 IDvdControl2 메소드를 호출하기 전에 현재의 도메인의 테스트를 실시할 필요는 없다. DVD 네비게이터는, 도메인의 테스트를 실시해, 현재의 커멘드가 도메인에 대해서 무효인 경우는, 아무것도 하지 않고 ,VFW_E_DVD_INVALIDDOMAIN 를 돌려준다.

참조

Domains ,EC_DVD_DOMAIN_CHANGE

IDvdInfo2::GetCurrentLocation

IDvdInfo2 인터페이스

현재의 재생 위치를 취득한다.

구문

HRESULT GetCurrentLocation(
  DVD_PLAYBACK_LOCATION2 *pLocation
);

파라미터

pLocation
[out] 재생 위치 정보를 받는 DVD_PLAYBACK_LOCATION2 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | pLocation 파라미터가 무효이다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 무효인 도메인내에 있다.

주의

이 메소드는, 현재의 위치의 시크를 명시적으로 금지하고 있지 않는 타이틀의 현재의 재생 위치로부터 비디오의 재생을 재개하는데 충분한 정보를 취득한다. 디스크가 배출된 후는, 이 메소드가 돌려주는 정보에서는 재생을 재개하는데 충분하지 않은 경우가 있다. 유저가 나중에 언제라도 같은 위치로 돌아갈 수 있도록(듯이), 현재의 위치와 스테이트 정보를 디스크에 보존하려면 ,GetState 를 사용한다.

IDvdInfo2::GetCurrentSubpicture

IDvdInfo2 인터페이스

현재의 타이틀내의 이용할 수 있는 서브 픽쳐 스트림의 수, 현재 선택되고 있는 서브 픽쳐 스트림 번호, 및 서브 픽쳐 상태를 취득한다.

구문

HRESULT GetCurrentSubpicture(
  ULONG *pulStreamsAvailable,
  ULONG *pulCurrentStream,
  BOOL *pbIsDisabled
);

파라미터

pulStreamsAvailable
[out] 이용할 수 있는 서브 픽쳐 스트림의 수를 받는 ULONG 형의 변수에의 포인터.
pulCurrentStream
[out] 현재 선택되고 있는 서브 픽쳐 스트림의 번호를 받는 ULONG 형의 변수에의 포인터.
pbIsDisabled
[out] 서브 픽쳐의 표시가 무효가 되어 있는지 어떤지를 나타내는 값을 받는 BOOL 형의 변수에의 포인터. TRUE 는 무효를 의미한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 초기화되어 있지 않은지,Title 도메인내에 없다.

주의

DVD 컨텐츠의 생성자는, 디스크 위에의 임의의 서브 픽쳐 스트림을강제적으로 액티브하게 하는 것같게 지정해, 이용자가 보고 싶은지 어떤지에 관계없이, 이 스트림을 반드시 표시하도록(듯이) 요구할 수가 있다. DVD 네비게이터는 그러한 디스크로부터의 모든 커멘드에 따라, 어플리케이션이 IDvdControl2::SetSubpictureState 메소드에 의해 서브 픽쳐의 표시를 무효로 했을 경우에서도, 강제적으로 액티브하게 된 스트림을 표시한다.

참조

EC_DVD_SUBPICTURE_STREAM_CHANGE ,IDvdControl2::SelectSubpictureStream

IDvdInfo2::GetCurrentVideoAttributes

IDvdInfo2 인터페이스

현재의 타이틀 또는 메뉴의 비디오 속성을 취득한다.

구문

HRESULT GetCurrentVideoAttributes(
    DVD_VideoAttributes *pATR
);

파라미터

pATR
[out] 속성을 받는 DVD_VideoAttributes 구조체에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.

주의

이 메소드의 사용예에 대해서는, DVDSample 의 「CDvdCore::GetVideoAttributes()」를 참조할것.

IDvdInfo2::GetDecoderCaps

IDvdInfo2 인터페이스

DVD 디코더의 비디오, 오디오, 및 서브 픽쳐의 최대 데이터 레이트 (역방향 및 순서 방향)와 지원 하고 있는 오디오의 종류 (Dolby AC-3, MPEG-2, DTS, SDDS, LPCM)를 취득한다.

구문

HRESULT GetDecoderCaps(
  DVD_DECODER_CAPS *pCaps
);

파라미터

pCaps
[out] 디코더에 관한 정보를 받는 DVD_DECODER_CAPS 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
VFW_E_WRONG_STATE | 필터 그래프가 초기화되어 있지 않다.

IDvdInfo2::GetDefaultAudioLanguage

IDvdInfo2 인터페이스

디폴트의 오디오 언어를 취득한다.

구문

HRESULT GetDefaultAudioLanguage(
  LCID *pLanguage,
  DVD_AUDIO_LANG_EXT *pAudioExtension
);

파라미터

pLanguage
[out] 디폴트의 언어 정보를 받는 LCID 에의 포인터.
pAudioExtension
디폴트의 DVD 오디오 언어 확장 기능을 나타내는 값을 받는 DVD_AUDIO_LANG_EXT 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | pLanguage 파라미터가 NULL 이다.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 유효한 도메인내에 없다.

참조

IDvdControl2::SelectAudioStream ,IDvdControl2::SelectDefaultAudioLanguage

IDvdInfo2::GetDefaultMenuLanguage

IDvdInfo2 인터페이스

디폴트의 메뉴 언어를 취득한다.

구문

HRESULT GetDefaultMenuLanguage(
  LCID *pLanguage
);

파라미터

pLanguage
[out] 언어 정보를 받는 LCID 에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | pLanguage 파라미터가 NULL 이다.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 유효한 도메인내에 없다.

참조

IDvdControl2::SelectDefaultMenuLanguage

IDvdInfo2::GetDefaultSubpictureLanguage

IDvdInfo2 인터페이스

디폴트의 서브 픽쳐 언어를 취득한다.

구문

HRESULT GetDefaultSubpictureLanguage(
  LCID *pLanguage,
  DVD_SUBPICTURE_LANG_EXT *pSubpictureExtension
);

파라미터

pLanguage
[out] 언어 정보를 받는 LCID 에의 포인터.
pSubpictureExtension
[out] 디폴트의 언어 확장 기능을 나타내는 값으로서 허가되고 있는 값의 1 개를 받는 DVD_SUBPICTURE_LANG_EXT 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | pLanguage 파라미터가 NULL 이다.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 유효한 도메인내에 없다.

참조

IDvdControl2::SelectDefaultSubpictureLanguage

IDvdInfo2::GetDiscID

IDvdInfo2 인터페이스

지정된 DVD 에 대해서 시스템이 생성한 64 비트의 식별 번호를 취득한다.

구문

HRESULT GetDiscID(
    LPCWSTR pszwPath,
    ULONGLONG *pullDiscID
  );

파라미터

pszwPath
[in] 디스크 ID 에 사용하는 볼륨의 패스. 현재의 DVD 볼륨을 사용하려면 , NULL 를 지정한다.
pullDiscID
[out] 64 비트의 디스크 ID 를 받는 ULONGLONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.

주의

DVD 네비게이터는, BCA 값은 아니고, 파일의 사이즈, 일자 그 외의 정보에 근거해 "일의인 " ID 를 계산한다. 이 번호는 디스크가 재생될 때마다 같다라고 하는 것이 보증된다. ID 는, 복제된 디스크의 모든 카피에 적용된다. 즉, 특정의 무비의 모든 카피는 같은 ID 를 가진다. 2 개(살)의 다른 타이틀이 같은 ID 를 가지는 확률은 충분히 낮기 때문에, 이 ID 는, 실용상 "일의 " 인 것이라고 볼 수가 있다.

IDvdInfo2::GetDVDDirectory

IDvdInfo2 인터페이스

DVD 네비게이터로 설정되어 있는 루트 디렉토리를 취득한다.

구문

HRESULT GetDVDDirectory(
  LPWSTR pszwPath,
  ULONG ulMaxSize,
  ULONG *pulActualSize
);

파라미터

pszwPath
[out, size_is(cbMaxSize)] 패스 캐릭터 라인을 받는 버퍼에의 포인터.
ulMaxSize
[in] WCHAR 단위의 버퍼의 사이즈.
pulActualSize
[out] WCHAR 단위로 돌려주어진 실제의 데이터의 사이즈를 받는 변수에의 포인터.

주의

이 메소드의 사용예에 대해서는, DVDSample 의 「CDvdCore::GetDriveLetter」를 참조할것.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 버퍼의 크기가 캐릭터 라인을 저장 하는데 충분하지 않다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 유효한 도메인내에 없다.

IDvdInfo2::GetKaraokeAttributes

IDvdInfo2 인터페이스

현재의 타이틀 또는 메뉴의 지정된 오디오 스트림의 가라오케 속성을 취득한다.

구문

HRESULT GetKaraokeAttributes(
  ULONG ulStream,
  DVD_KaraokeAttributes *pATR
);

파라미터

ulStream
[in] 속성을 문의하는 오디오 스트림의 인덱스를 지정하는 ULONG 형의 변수. 「주의」를 참조할것.
pATR
[out] 가라오케 속성이 저장 되는 DVD_KaraokeAttributes 구조체에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.
VFW_E_DVD_NOT_IN_KARAOKE_MODE | 지정된 스트림이 가라오케 포맷으로 되어 있지 않다.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 타이틀 도메인내에 없다.
VFW_E_DVD_NO_ATTRIBUTES | 어떠한 이유로써, 지정된 스트림의 가라오케 속성을 취득할 수 없다.

주의

이 메소드는, 스트림내의 채널의 수를 명시적으로는 돌려주지 않는다. 그 정보는,IDvdInfo2::GetAudioAttributes 를 호출하는 것에 의해 취득할 수 있다. 이 메소드의 사용예에 대해서는, DVDSample 의 「CKaraokeDlg::DoModal」를 참조할것.

ulStream 파라미터는, 0 에서 7 의 사이의 값 또는 다음의 언젠가이다.
DVD_STREAM_DATA_CURRENT (0x800) | 현재 선택되고 있는 오디오 스트림을 문의한다.
DVD_DEFAULT_AUDIO_STREAM | 디폴트의 오디오 스트림을 문의한다.

IDvdInfo2::GetSubpictureAttributes

IDvdInfo2 인터페이스

지정된 타이틀 또는 메뉴의 지정된 서브 픽쳐 스트림의 속성을 취득한다.

구문

HRESULT GetSubpictureAttributes(
  ULONG ulStream,
  DVD_SubpictureAttributes *pAttributes
  );

파라미터

ulStream
[in] 문의하는 서브 픽쳐 스트림을 나타내는 0 에서 31 의 사이의 인덱스 번호. 「주의」를 참조할것.
pAttributes
[out] 서브 픽쳐의 속성을 받는 DVD_SubpictureAttributes 구조체에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_FAIL | 서브 픽쳐 스트림이 발견되지 않는다.
E_POINTER | 무효인 인수.
VFW_E_ATTRIBUTES_DO_NOT_EXIST | 서브 픽쳐에 속성이 정의되어 있지 않다.

주의

타이틀로서 인덱스수 0-31 가 유효하다. 메뉴는 1 개의 서브 픽쳐 스트림만을 가지는, 그것은 이하의 겉(표)의 1 개를 사용해 지정되지 않으면 안 된다.

DVD_STREAM_DATA_CURRENT (0x800) | 현재 선택되고 있는 서브 픽쳐 스트림을 문의한다.
DVD_STREAM_DATA_VMGM (0x400) | 비디오 매니저 또는 "탑 " 메뉴의 서브 픽쳐 속성을 문의한다.
DVD_STREAM_DATA_VTSM (0x401) | 현재 선택되고 있는 비디오 타이틀 세트 메뉴의 서브 픽쳐 속성을 문의한다.

이 메소드의 사용예에 대해서는, DVDSample 의 「CDvdCore::GetSPAttributes()」 및 「CSPLangDlg::GetSPLang」를 참조할것.

참조

메뉴,IsSubpictureStreamEnabled

IDvdInfo2::GetCurrentUOPS

IDvdInfo2 인터페이스

컨텐츠의 생성자가 명시적으로 무효로 한 네비게이션 커멘드가 현재의 디스크 위치에 있으면, 그것을 나타내는 플래그세트를 취득한다.

구문

HRESULT GetCurrentUOPS(
  ULONG *pulUOPs
);

파라미터

pulUOPs
[out] VALID_UOP_FLAG 값의 비트마다의 OR 인 ULONG 형의 변수에의 포인터. 개개의 비트는, 유저 조작 (UOP) 상태 (유효 또는 무효)를 나타낸다. 비트가 세트 되고 있으면, 유저 조작은 금지되고 있다. 「주의」를 참조할것.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | pulUOPs 가 유효한 포인터는 아니다.

주의

DVD 의 생성자는, 디스크 위에의 거의 모든 위치에서, UOP 커멘드를 삽입하는 것으로써, 보통은 현재의 DVD 도메인내에서 허가되고 있는 네비게이션 커멘드를 금지할 수가 있다. 즉, UOP 커멘드를 이용 하면, 디스크의 생성자는, 보통의 네비게이션 권한을 오버라이드(override) 할 수 있다.

DVD 네비게이터는, 커멘드를 처리하기 전에 자동적으로 모든 UOP 권한을 체크해, 커멘드가 현재의 UOP 에 의해 무효가 되어 있으면, 어느 메소드로부터에서도 VFW_E_DVD_OPERATION_INHIBITED 를 돌려주기 (위해)때문에, 보통은 DVD 프레이야아프리케이쇼가 이 메소드를 사용할 필요는 없다. 어플리케이션으로 현재의 UOP 권한 그 자체를 추적할 필요가 있는 경우는, 현재의 UOP 권한이 필요하게 될 때마다 GetCurrentUOPS 를 호출하는지, 메시지 루프로 EC_DVD_VALID_UOPS_CHANGE 이벤트 통지를 처리해,lParam1 파라미터로부터 UOP 정보를 취득할 수가 있다. 일반적으로, 후자의 방식이 효율이 좋다.

참조

EC_DVD_VALID_UOPS_CHANGE

IDvdInfo2::GetDVDVolumeInfo

IDvdInfo2 인터페이스

현재의 DVD 볼륨 정보를 취득한다.

구문

HRESULT GetDVDVolumeInfo(
    ULONG *pulNumOfVolumes,
    ULONG *pulVolume,
    DVD_DISC_SIDE *pSide,
    ULONG *pulNumOfTitles
    );

파라미터

pulNumOfVolumes
[out] 볼륨 세트내의 볼륨의 수를 받는 ULONG 형의 변수에의 포인터.
pulVolume
[out] 이 루트 디렉토리의 볼륨 번호를 받는 ULONG 형의 변수에의 포인터.
pSide
[out] 현재의 디스크면을 받는 DVD_DISC_SIDE 형의 변수에의 포인터.
pulNumOfTitles
[out] 이 볼륨으로 사용할 수 있는 타이틀의 수를 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.

주의

일부의 디스크는, 멀티 디스크 세트의 일부로서 배포할 수 있다. 그 경우, 여기서 말하는 "볼륨 " 는, 디스크가 생성 된 방법에 따라, "디스크 " 를 의미하는 일도, "디스크면" 를 의미하는 일도 있다.

IDvdInfo2::GetDVDTextLanguageInfo

IDvdInfo2 인터페이스

지정된 텍스트 캐릭터 라인 언어 블록의 정보를 취득한다.

구문

HRESULT GetDVDTextLanguageInfo(
    ULONG ulLangIndex,
    ULONG *pulNumOfStrings,
    LCID pLangCode,
    DVD_TextCharSet *pbCharacterSet
  );

파라미터

ulLangIndex
[in] 언어 블록을 지정하는 인덱스. 「주의」를 참조할것.
pulNumOfStrings
[out] 지정된 언어 블록의 캐릭터 라인의 수를 받는 ULONG 형의 변수에의 포인터.
pLangCode
[out] ISO 639 언어 코드가 저장 되고 있는 LCID 형의 변수에의 포인터.
pbCharacterSet
[out] 지정되고 있는 언어의 어느 캐릭터 세트가 사용되고 있는지를 나타내는 값을 받는 DVD_TextCharSet 열거에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
E_UNEXPECTED | 예기치 않은 내부 에러가 발생했다.

주의

GetDVDTextNumberOfLanguages 를 호출해, 사용할 수 있는 모든 메뉴와 서브 픽쳐의 텍스트 언어의 인덱스를 설정한다. 다음에, 각 인덱스 엔트리에 대해 GetDVDTextLanguageInfo 를 호출해, 특정의 언어의 정보 (캐릭터 라인의 수, 언어 코드, 캐릭터 세트)를 취득한다.

참조

DVD 텍스트 캐릭터 라인의 조작

IDvdInfo2::GetDVDTextNumberOfLanguages

IDvdInfo2 인터페이스

현재의 DVD 또는 디스크면의 텍스트 언어의 수를 취득한다.

구문

HRESULT GetDVDTextNumberOfLanguages(
    ULONG *pulNumOfLangs
  );

파라미터

pulNumOfLangs
[out] 텍스트 언어의 수를 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
E_UNEXPECTED | 예기치 않은 내부 에러가 발생했다.

주의

언어의 수는, 디스크가 생성 된 방법에 따라, 디스크 전체에 대해 유효한 것도, 현재의 디스크면에 대한 보고 유효한 것도 있다.

참조

DVD 텍스트 캐릭터 라인의 조작

IDvdInfo2::GetDVDTextStringAsNative

IDvdInfo2 인터페이스

지정된 언어의 텍스트 캐릭터 라인을 바이트의 배열로서 취득한다.

구문

HRESULT GetDVDTextStringAsNative(
  ULONG ulLangIndex,
  ULONG ulStringIndex,
  BYTE *pchBuffer,
  ULONG ulMaxBufferSize,
  ULONG *pulActualSize,
  DVD_TextStringType *pType
);

파라미터

ulLangIndex
[in] 언어 인덱스.
ulStringIndex
[in] 특정의 언어의 캐릭터 라인 인덱스.
pchBuffer
[out] 텍스트 캐릭터 라인을 받는 버퍼에의 포인터. pchBuffer 가 NULL 의 경우, 이 메소드는 pulActualSize 에 의해 캐릭터 라인의 사이즈만을 돌려준다.
ulMaxBufferSize
[in] 허용 최대 캐릭터 라인 사이즈 (pchBuffer 의 사이즈).
pulActualSize
[out] pchBuffer 에 의해 돌려주어지는, 마지막 NULL 를 포함한 캐릭터 라인의 바이트 단위의 실제의 길이.
pType
[out] 돌려주어진 캐릭터 라인 데이터의 종류를 받는 DVD_TextStringType 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
E_UNEXPECTED | 예기치 않은 내부 에러가 발생했다.

주의

일반적으로, 견뢰한 어플리케이션은 Unicode™ 캐릭터 라인을 처리할 수 있다. 따라서, 보통, 캐릭터 라인을 취득 하면나무는, 우선 GetDVDTextStringAsUnicode 를 호출한다. 그러나, 일부의 캐릭터 라인에는 Unicode™ 로 나타낼 수 없는 문자가 포함되어 있는 일이 있기 (위해)때문에,GetDVDTextStringAsUnicode 가 실패했을 경우, 어플리케이션은 GetDVDTextStringAsNative 를 호출할 수가 있다.

마지막 NULL 가 돌려주어진 캐릭터 라인에 추가된다.

참조

DVD 텍스트 캐릭터 라인의 조작

IDvdInfo2::GetDVDTextStringAsUnicode

IDvdInfo2 인터페이스

지정된 언어와 캐릭터 라인 인덱스의 텍스트 캐릭터 라인을 Unicode™ 로 취득한다.

구문

HRESULT GetDVDTextStringAsUnicode(
    ULONG ulLangIndex,
    ULONG ulStringIndex,
    TCHAR *pchBuffer,
    ULONG ulMaxBufferSize,
    ULONG *pulActualSize,
    enum DVD_TextStringType *pType
  );

파라미터

ulLangIndex
[in] 캐릭터 라인 인덱스.
ulStringIndex
[in] 특정의 언어의 캐릭터 라인 인덱스.
pchBuffer
[out] 텍스트 캐릭터 라인을 받는 버퍼에의 포인터. pchBuffer 가 NULL 의 경우, 이 메소드는 pulActualSize 에 의해 캐릭터 라인의 사이즈만을 돌려준다.
ulMaxBufferSize
[in] sizeof(pchBuffer) /sizeof(*pchBuffer) 에 의해 계산되는 허용 최대 캐릭터 라인 사이즈.
pulActualSize
[out] pchBuffer 에 의해 돌려주어지는, 마지막 NULL 를 포함한 캐릭터 라인의 바이트 단위의 실제의 길이를 받는 ULONG 형의 변수에의 포인터.
pType
[out] 돌려주어진 캐릭터 라인 데이터의 종류를 받는 DVD_TextStringType 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
E_UNEXPECTED | 예기치 않은 내부 에러가 발생했다.

주의

일반적으로, 견뢰한 어플리케이션은 Unicode™ 캐릭터 라인을 처리할 수 있다. 따라서, 보통, 캐릭터 라인을 취득 하면나무는, 우선 GetDVDTextStringAsUnicode 를 호출한다. 그러나, 일부의 캐릭터 라인에는 Unicode™ 로 나타낼 수 없는 문자가 포함되어 있는 일이 있기 (위해)때문에,GetDVDTextStringAsUnicode 가 실패했을 경우, 어플리케이션은 GetDVDTextStringAsNative 를 호출할 수가 있다.

마지막 NULL 가 돌려주어진 캐릭터 라인에 추가된다.

참조

DVD 텍스트 캐릭터 라인의 조작

IDvdInfo2::GetMenuLanguages

IDvdInfo2 인터페이스

디스크 위에의 모든 메뉴로 이용할 수 있는 모든 언어를 취득한다.

구문

HRESULT GetMenuLanguages(
    LCID *pLanguages,
    ULONG ulMaxLanguages,
    ULONG *puActualLanguages
  );

파라미터

pLanguages
[out] 돌려주어진 언어를 받아들이는 LCID 배열에의 포인터. 실제의 언어 자체는 아니고, 메뉴로 사용할 수 있는 언어의 수만큼을 취득하려면 ,pLanguages 에 NULL 를 지정한다.
ulMaxLanguages
[in] 취득하는 언어의 최대수.
puActualLanguages
[out] 취득된 언어의 실제의 수를 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.

IDvdInfo2::GetNumberOfChapters

IDvdInfo2 인터페이스

지정된 타이틀의 쳅터의 수를 취득한다.

구문

HRESULT GetNumberOfChapters(
  ULONG ulTitle,
  ULONG *pulNumOfChapters
);

파라미터

ulTitle
[in] 타이틀을 지정하는 ULONG 형의 변수.
pulNumOfChapters
[out] 지정된 타이틀의 쳅터의 수를 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | 파라미터가 무효이다.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.

주의

IDvdControl2::PlayChapter 를 호출하기 전에, 이 메소드를 호출해 쳅터의 수를 취득해, 지정하는 쳅터 번호가 유효한 것을 확인한다.

IDvdInfo2::GetPlayerParentalLevel

IDvdInfo2 인터페이스

DVD 네비게이터의 현재의 페어 렌탈 락 레벨 및 ISO 3166 국 코드의 설정을 취득한다.

구문

HRESULT GetPlayerParentalLevel(
  ULONG *pulParentalLevel,
  ULONG *pulCountryCode
);

파라미터

pulParentalLevel
[out] 현재의 페어 렌탈 락 레벨을 나타내는 값을 받는 ULONG 형의 변수에의 포인터. 유효한 페어 렌탈 락 레벨은, 페어 렌탈 락이 유효하면 1 에서 8 의 사이이며, 페어 렌탈 락이 무효이면 0xFFFFFFFF 이다.
pulCountryCode
[out] 현재의 나라 코드 (ISO 3166 Alpha-2 코드)를 나타내는 값을 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 파라미터가 무효이다.

주의

DVD 네비게이터에서는, 페어 렌탈 락이 디폴트로 무효가 되어 있다. 이 메소드의 사용예에 대해서는, DVDSample 의 「CDvdCore::GetParentalLevel」를 참조할것.

참조

페어 렌탈 락 레벨의 적용, EC_DVD_PARENTAL_LEVEL_CHANGE

IDvdInfo2::GetState

IDvdInfo2 인터페이스

디스크 위치와 DVD 네비게이터 스테이트 정보가 저장 되고 있는 북마크를 취득한다.

구문

HRESULT GetState(
    IDvdState **pStateData
);

파라미터

pStateData
[out] DVD 네비게이터에 의해 할당할 수 있었던 DVDState 오브젝트의 IDvdState 인터페이스에의 포인터의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.

주의

이 메소드가 불려 가면(자), DVD 네비게이터는 새로운 상태 오브젝트를 생성 해, 그 오브젝트에 현재의 위치, 현재의 페어 렌탈 락 레벨, 및 그 외의 스테이트 정보를 보존한다. 나중에 DVDState 오브젝트를 사용해 IDvdControl2::SetState 를 호출하는 것으로, 보존한 위치에 DVD 네비게이터를 되돌릴 수가 있다. 이것에 의해, 이용자는, 디스크의 도중에 재생을 정지해 그 위치를 보존해, 나중에, 모든 내부 설정을 원대로 복원해, 전에 정지한 위치로부터 재생을 재개할 수가 있다.

DVD 네비게이터는,DvdState 오브젝트를 어플리케이션에 돌려주기 전에,DvdState 오브젝트에 대한 AddRef 를 호출한다. 어플리케이션은, 오브젝트를 사용한 후, 오브젝트에 대한 Release 를 호출할 필요가 있다.

이 메소드의 사용예에 대해서는, DVDSample 의 「CDvdCore::RestoreBookmark」를 참조할것.

IDvdInfo2::GetSubpictureLanguage

IDvdInfo2 인터페이스

현재의 타이틀내의 지정된 서브 픽쳐 스트림의 언어를 취득한다.

구문

HRESULT GetSubpictureLanguage(
  ULONG ulStream,
  LCID *pLanguage
  );

파라미터

ulStream
[in] 언어를 취득하는 서브 픽쳐 스트림의 번호.
pLanguage
[out] 로케일 정보를 받는 LCID 에의 포인터. 언어 정보는, Win32 MAKELANGID 매크로를 사용해 LCID 로부터 추출할 수 있다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 초기화되어 있지 않은, 또는 유효한 도메인내에 없다.

주의

메뉴로 이용할 수 있는 텍스트 언어를 취득하려면 ,GetMenuLanguages 를 호출한다. 스트림에 미지의 언어가 포함되는 경우,GetSubpictureLanguage 는 pLanguage 가 가리키는 값을 제로로 설정한다. pLanguage 로부터 읽어내 가능한 캐릭터 라인명을 생성 하려면 , 다음과 같이 Win32 GetLocaleInfo 함수를 호출한다. LOCALE_SENGLANGUAGE 는 로케일 정보형이며,pszString 는 요구된 데이터를 받는 버퍼에의 포인터이며,cbSize 는 pszString 의 사이즈를 지정한다.

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

IDvdInfo2::GetTitleAttributes

IDvdInfo2 인터페이스

지정된 타이틀과 그 메뉴의 모든 비디오 스트림, 오디오 스트림, 및 서브 픽쳐 스트림의 속성을 취득한다.

구문

HRESULT GetTitleAttributes(
    ULONG ulTitle,
    DVD_MenuAttributes *pMenu,
    DVD_TitleAttributes *pTitle
    );

파라미터

ulTitle
[in] 정보를 요구하는 타이틀 번호를 지정하는 1 에서 99 의 사이의 ULONG 형의 변수. 현재의 타이틀의 정보를 요구하려면 , 0xFFFFFFFF 를 지정한다.
pMenu
[out] 지정된 타이틀에 관련지을 수 있고 있는 메뉴의 속성을 받는 DVD_MenuAttributes 구조체에의 포인터.
pTitle
[out] 지정된 타이틀의 속성을 받는 DVD_TitleAttributes 구조체에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | nTitle 파라미터가 무효이다.
E_INVALIDDOMAIN | DVD 네비게이터가 타이틀 도메인내에 없다.
E_POINTER | pMenu 파라미터 또는 pTitle 파라미터가 무효이다.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않은, 또는 그 이외의 내부 에러가 발생했다.

IDvdInfo2::GetTitleParentalLevels

IDvdInfo2 인터페이스

특정의 타이틀에 정의되고 있는 페어 렌탈 락 레벨을 취득한다.

구문

HRESULT GetTitleParentalLevels(
    ULONG ulTitle,
    ULONG *pulParentalLevels
  );

파라미터

ulTitle
[in] 페어 렌탈 락 레벨을 요구하는 타이틀. 현재의 타이틀의 페어 렌탈 락 레벨을 취득하려면 , 0xfffffff 를 지정한다.
pulParentalLevels
[out] 타이틀에 대해서 정의되고 있는 DVD_PARENTAL_LEVEL 값의 비트마다의 OR 의 편성을 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.

주의

1 개의 타이틀의 다른 섹션에는, 다른 페어 렌탈 락 레벨이 포함되어 있는 일이 있다.

참조

페어 렌탈 락 레벨의 적용

IDvdInfo2::GetTotalTitleTime

IDvdInfo2 인터페이스

현재의 타이틀의 총재생 시간을 취득한다.

구문

HRESULT GetTotalTitleTime(
    DVD_HMSF_TIMECODE *pTotalTime,
    ULONG *pulTimeCodeFlags
  );

파라미터

pTotalTime
[out] 시, 분, 초, 프레임 단위의 총시간을 받는 DVD_HMSF_TIMECODE 형의 변수에의 포인터.
pulTimeCodeFlags
[out] 디스크가 생성 되었을 때의 재생 frame rate를 나타내는 DVD_TIMECODE_FLAGS 값을 받는 ULONG 형의 변수에의 포인터. 타임 코드 정보를 받고 싶지 않은 경우는, NULL 를 지정한다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
VFW_E_DVD_INVALIDDOMAIN | DVD 네비게이터가 타이틀 도메인내에 없다.
VFW_S_DVD_NON_ONE_SEQUENTIAL | 타이틀이 단일 시퀀셜 비디오 타이틀이 아니다.

주의

총타이틀 시간은, 타이틀을 차례로 재생하는데 필요한 시간이며, 정지화면의 재생, 포즈 등에 걸리는 시간은 포함되지 않는다.

이 메소드는, 각 쳅터가 자동적으로 다음의 쳅터에 분기 해, 타이틀 전체가 도중에 정지하는 일 없이 연속적으로 재생되는,단일 시퀀셜 비디오 타이틀에서만 사용된다. 비시퀀셜 비디오 타이틀이란, 자동적으로 차례차례로 쳅터가 재생되지 않는 타이틀이다. DVD 의 생성자에 의해, 비시퀀셜 비디오 타이틀에 시간 정보를 encode 할 방법이 다르기 (위해)때문에, 그러한 타이틀의 총시간을 조사하기 위해서(때문에) 이 메소드를 사용하지 않는 것.

IDvdInfo2::GetVMGAttributes

IDvdInfo2 인터페이스

비디오 매니저 메뉴의 모든 비디오 스트림, 오디오 스트림, 및 서브 픽쳐 스트림의 속성을 취득한다.

구문

HRESULT GetVMGAttributes(
  DVD_MenuAttributes *pATR
);

파라미터

pATR
[out] 속성을 받는 DVD_MenuAttributes 구조체에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.

주의

비디오 매니저 메뉴는 특정의 타이틀 번호에 관련지을 수 있지 않았다.

IDvdInfo2::IsAudioStreamEnabled

IDvdInfo2 인터페이스

지정된 오디오 스트림이 현재의 타이틀로 유효하게 되어 있는지 어떤지를 판별한다.

구문

HRESULT IsAudioStreamEnabled(
    ULONG ulStreamNum,
    BOOL *pbEnabled
    );

파라미터

ulStreamNum
[in] 테스트하는 오디오 스트림 번호.
pbEnabled
[out] 오디오 스트림이 유효하게 되어 있으면 TRUE, 그 이외의 경우는 FALSE 가 되는 값을 받는 BOOL 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.

주의

DVD 에는 최대 8 개의 개별의 오디오 스트림을 포함할 수가 있지만, 보통은, 1 개의 타이틀의 모든 스트림이 유효하게 될 것은 없다. IsAudioStreamEnabled 를 사용해, 특정의 스트림이 현재의 타이틀로 유효한지 어떤지를 조사한 후,IDvdControl2::SelectAudioStream 를 호출해, 몇개의 유효한 스트림을 선택한다.

IDvdInfo2::IsSubpictureStreamEnabled

IDvdInfo2 인터페이스

지정된 서브 픽쳐 스트림이 현재의 타이틀로 유효하게 되어 있는지 어떤지를 판별한다.

구문

HRESULT IsSubpictureStreamEnabled(
    ULONG ulStreamNum,
    BOOL *pbEnabled
);

파라미터

ulStreamNum
[in] 테스트하는 서브 픽쳐 스트림 번호.
pbEnabled
[out] 서브 픽쳐 스트림이 유효하게 되어 있으면 TRUE, 그 이외의 경우는 FALSE 가 되는 값을 받는 BOOL 형의 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.

주의

DVD 에는 최대 32 개의 개별의 서브 픽쳐 스트림을 포함할 수가 있지만, 보통은, 1 개의 타이틀의 모든 스트림이 유효하게 될 것은 없다. IsSubpictureStreamEnabled 를 사용해, 특정의 스트림이 현재의 타이틀로 유효한지 어떤지를 조사한 후,IDvdControl2::SelectSubpictureStream 를 호출해, 몇개의 유효한 스트림을 선택한다.


IDvdState 인터페이스

IDvdState 인터페이스는,DvdState 오브젝트에 의해 이행 된다. DvdState 오브젝트는, 어플리케이션이 IDvdInfo2::GetState 를 호출해, 재생 위치, 페어 렌탈 락 레벨, 리젼을 포함한 유저의 세션 상태를 디스크에 보존할 경우에,DVD 네비게이터 필터에 의해 생성 된다. 어플리케이션은,IDvdState 메소드를 사용해,DvdState 오브젝트에 보존되는 이 정보를 문의할 수가 있다.

DvdState 오브젝트는,IPersist 를 이행 해, 디스크에의 보존을 유효하게 한다. 북마크를 보존하는 방법을 나타내는 샘플 코드에 대해서는, 「DvdState 오브젝트의 보존과 복원」을 참조할것.

DVD 네비게이터는, DVD 위에의 현재의 재생 위치, 유저의 페어 렌탈 락 레벨, 및 DVD 리젼에 의해 DvdState 오브젝트를 초기화한다. 이 방법 대신에, 어플리케이션이 CoCreateInstance: 를 호출하는 것에 의해 상태 오브젝트를 생성 할 수도 있다.

CoCreateInstance( CLSID_DVDState, NULL, CLSCTX_INPROC_SERVER,
    IID_IDvdState, (void **) ppState );

나중에, 페어 렌탈 락 레벨과 리젼의 설정을 복원해,GetState 가 불려 갔을 때에 정지한 위치로부터 재생을 재개하려면 ,IDvdControl2::SetState 를 호출한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDvdState 메소드 | 설명
GetDiscID | 북마크가 생성 된 디스크의 일의인 식별자 (ID)를 취득한다.
GetParentalLevel | DvdState 오브젝트에 보존된 유저의 페어 렌탈 락 레벨을 취득한다.
GetRegion | DvdState 오브젝트에 보존된 DVD 리젼을 취득한다.

IDvdState::GetDiscID

IDvdState 인터페이스

북마크가 생성 된 디스크의 일의인 식별자 (ID)를 취득한다.

구문

HRESULT GetDiscID(
  ULONGLONG *pullUniqueID
  );

파라미터

pullUniqueID
[out] ID 를 받는 ULONGLONG 형의 변수에의 포인터.

반환값

다음 표에 나타나는 몇개의 값을 돌려준다.

S_OK | 성공.
E_POINTER | 무효인 인수.

IDvdState::GetParentalLevel

IDvdState 인터페이스

DvdDState 오브젝트에 보존된 유저의 페어 렌탈 락 레벨을 취득한다.

구문

HRESULT GetParentalLevel(
  ULONG *pulParentalLevel
  );

파라미터

pulParentalLevel
[out] 페어 렌탈 락 레벨을 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 성공.
E_POINTER | 무효인 인수.

IDvdState::GetRegion

IDvdState 인터페이스

DvdState 오브젝트에 보존된 DVD 리젼을 취득한다.

구문

HRESULT GetRegion(
  ULONG *pulRegion
  );

파라미터

pulRegion
[out] 리젼값을 받는 ULONG 형의 변수에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 성공.
E_UNEXPECTED | DVD 네비게이터가 초기화되어 있지 않다.
E_POINTER | 무효인 인수.


IDVEnc 인터페이스

이 인터페이스는,DV 비디오 엔코더 필터의 프로퍼티의 설정 및 취득을 실시하는 메소드를 갖추고 있다.

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDVEnc 메소드 | 설명
get_IFormatResolution | 인코딩 해상도를 취득한다.
put_IFormatResolution | 인코딩 해상도를 설정한다.

IDVEnc::get_IFormatResolution

IDVEnc 인터페이스

인코딩 해상도를 취득한다.

구문

HRESULT get_IFormatResolution(
    int *VideoFormat,
    int *DVFormat,
    int *Resolution,
    BYTE fDVInfo,
    DVINFO *sDVInfo
);

파라미터

VideoFormat
[out] 사용되고 있는 비디오 방식 (NTSC 또는 PAL )을 지정하는 DVENCODERVIDEOFORMAT 열거의 멤버를 받는 변수에의 포인터.
DVFormat
[out] 디지털 비디오 (DV) 포맷을 지정하는 DVENCODERFORMAT 열거의 멤버를 받는 변수에의 포인터.
Resolution
[out] 비디오 해상도를 지정하는 DVENCODERRESOLUTION 열거의 멤버를 받는 변수에의 포인터.
fDVInfo
[in] 스트림 포맷을 지정하는 DVINFO 구조체를 취득할지 어떨지를 지정하는 불형의 값. TRUE 의 경우는,sDVInfo 파라미터에 의해 스트림 포맷이 돌려주어진다.
sDVInfo
[out] 스트림 포맷이 저장 되고 있는 DVINFO 구조체를 받는 변수에의 포인터. (fDVInfo 가 FALSE 의 경우, 이 파라미터는 무시된다. )

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_FAIL 또는 그 외의 에러 코드를 돌려준다.

IDVEnc::put_IFormatResolution

IDVEnc 인터페이스

인코딩 해상도를 설정한다.

구문

HRESULT put_IFormatResolution(
    int VideoFormat,
    int DVFormat,
    int Resolution,
    BYTE fDVInfo,
    DVINFO *sDVInfo
);

파라미터

VideoFormat
[in] 사용하는 비디오 방식 (NTSC 또는 PAL)을 지정하는 DVENCODERVIDEOFORMAT 열거의 멤버.
DVFormat
[in] DV 포맷을 지정하는 DVENCODERFORMAT 열거의 멤버.
Resolution
[in] 비디오 해상도를 지정하는 DVENCODERRESOLUTION 열거의 멤버.
fDVInfo
[in] sDVInfo 파라미터에 유효한 DVINFO 구조체를 저장 할지 어떨지를 지정하는 불형의 값. 스트림 포맷을 설정하려면 , 이 파라미터를 TRUE 로 설정해, 포맛트체크를 sDVInfo 파라미터로 지정한다.
sDVInfo
[in] fDVInfo 가 TRUE 의 경우, 이 파라미터는 스트림 포맷을 기술하는 DVINFO 구조체를 가리킬 필요가 있다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_FAIL 또는 그 외의 에러 코드를 돌려준다.


IDVSplitter 인터페이스

디지털 비디오 (DV) 스트림의 frame rate를 다운 그레이드 한다. DV 스플리터 필터는 이 인터페이스를 공개한다.

어플리케이션은 이 인터페이스를 사용해, 스트림이 DV 비디오 디코더에 닿기 전에 DV 스트림의 frame rate를 삭감한다. 이것은 리얼타임 디코드의 같은 프로세서의 부하의 높은 태스크에 유효와리 얻는다.

Vtable 순서의 메소드

IUnknown methods | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDVSplitter 메소드 | 설명
DiscardAlternateVideoFrames | 비디오 스트림의 프레임의 반을 폐기한다.

IDVSplitter::DiscardAlternateVideoFrames

IDVSplitter 인터페이스

비디오 스트림의 프레임의 반을 폐기한다. NTSC 에서는 frame rate는 매초 30 프레임 (fps)에서 15 fps 에 삭감된다. PAL 에서는 frame rate는 25 fps 에서 12.5 fps 에 삭감된다.

구문

HRESULT DiscardAlternateVideoFrames(
    int nDiscard
);

파라미터

nDiscard
[in] 프레임을 삭감할지 어떨지를 나타내는 플래그. 값이 제로 이외라면, 필터는 1 프레임 걸러서 프레임을 폐기한다. 값이 제로라면, 필터는 모든 프레임을 폐기한다.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_UNEXPECTED | 필터는 포즈 혹은 실행중.


IEnumFilters 인터페이스

IFilterGraph::EnumFilters 메소드는 이 인터페이스를 돌려주는, 그것은 필터 그래프내에서 현재 필터를 가지고 있는 표준적인 Component Object Model (COM) 콜렉션 오브젝트에의 액세스를 제공한다. COM 콜렉션에 대해서는 Platform SDK 의 IEnumXXXX 주제를 참조. 필터의 열거에 대한 상세한 것에 대하여는, 「Enumerating Objects in a Filter Graph 」를 참조할것.

그래프내의 필터 세트가 변경이 되었다면, 이 인터페이스의 몇개의 메소드가 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. Reset 메소드를 호출해 열거자를 재동기 하는 것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IEnumFilters 메소드 | 설명
Next | 열거 순서 중(안)에서, 지정의 필터수를 취득한다.
Skip | 지정의 필터수를 스킵 한다.
Reset | 열거 순서를 선두로부터 리셋 한다.
Clone | 같은 열거 상태로, 열거자의 카피를 생성 한다.

IEnumFilters::Clone

IEnumFilters 인터페이스

같은 열거 상태로, 열거자의 카피를 생성 한다

구문

HRESULT Clone(
    IEnumFilters **ppEnum
);

파라미터

ppEnum
[out] 새로운 열거자 IEnumFilters 에의 포인터를 받는 변수의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | Null 포인터 인수.

IEnumFilters::Next

IEnumFilters 인터페이스

열거 순서 중(안)에서, 지정의 필터수를 취득한다.

구문

HRESULT Next(
    ULONG cFilters,
    IBaseFilter **ppFilter,
    ULONG *pcFetched
);

파라미터

cFilters
[in] 취득하는 필터의 수.
ppFilter
[out] cFilters 사이즈의 배열, 여기에 IBaseFilter 포인터가 배치된다.
pcFetched
[out] 취득한 필터의 수를 받는 변수에의 포인터. cFilters 가 1 이라면, NULL 도 있을 수 있다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 요구된 수와 같은 수의 필터를 취득할 수 없었다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
VFW_E_ENUM_OUT_OF_SYNC | 그래프가 변경되어 이 열거자와 호환성이 없다.

주의

메소드가 성공하면(자),IBaseFilter 포인터 모두에게 참조 카운트가 남는다. 해방시에 주의가 필요.

필터 그래프가 변경되는(예를 들어, 어플리케이션이 있는 필터를 삭제했다)와 열거자는 그 그래프와의 호환성을 없애, 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. 열거자에게로의 그 전의 호출로 취득한 데이터는 폐기하는 것, 왜냐하면 유효하지 않을 가능성이 있기 때문이다. Reset 메소드를 호출해 열거자를 업데이트 하는 것. 그러면 Next 메소드를 안전하게 호출할 수가 있다.

IEnumFilters::Reset

IEnumFilters 인터페이스

열거 순서를 선두로부터 리셋 한다.

구문

HRESULT Reset(void);

반환값

성공을 나타내는 S_OK 를 돌려준다.

IEnumFilters::Skip

IEnumFilters 인터페이스

지정의 필터수를 스킵 한다.

구문

HRESULT Skip(
    ULONG cFilter
);

파라미터

cFilter
[in] 스킵 하는 필터수.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 스킵은 순서의 마지막을 넘겼다.
S_OK | 성공.
VFW_E_ENUM_OUT_OF_SYNC | 그래프는 변경되어, 현재 그 열거자와 호환성이 없다.

주의

필터 그래프가 변경되는(예를 들어, 어플리케이션이 있는 필터를 삭제했다)와 열거자는 그 그래프와의 호환성을 없애, 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. 열거자에게로의 그 전의 호출로 취득한 데이터는 폐기하는 것, 왜냐하면 유효하지 않을 가능성이 있기 때문이다. Reset 메소드를 호출해 열거자를 업데이트 하는 것. 그러면 Skip 메소드를 안전하게 호출할 수가 있다.


IEnumMediaTypes 인터페이스

핀의 허용 하는 포맷을 열거한다.

IPin::EnumMediaTypes 메소드는 이 인터페이스를 돌려준다. 그것은 표준 Component Object Model (COM) 열거자를 베이스로 하고 있다. 상세한 것에 대하여는, Platform SDK 의 IEnumXXXX 주제를 참조할것.

핀이 다른 핀과 접속 하면 와, 핀은 이 인터페이스를 사용한다. 어플리케이션은 그것을 사용해, 핀의 허용 하는 미디어 타입을 시험할 수도 있다. 상세한 것에 대하여는, 「Enumerating Objects in a Filter Graph 」를 참조할것.

핀의 허용 하는 미디어 타입이 변경되면(자), 이 인터페이스가 있는 메소드가 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. Reset 메소드를 호출해 열거자를 재동기 하는 것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IEnumMediaTypes 메소드 | 설명
Next | 지정한 수의 미디어 타입을 취득한다.
Skip | 지정한 수의 미디어 타입을 스킵 한다.
Reset | 열거 순서를 선두로부터 리셋 한다.
Clone | 같은 열거 상태로 열거자의 카피를 생성 한다.

IEnumMediaTypes::Clone

IEnumMediaTypes 인터페이스

같은 열거 상태로 열거자의 카피를 생성 한다.

구문

HRESULT Clone(
    IEnumMediaTypes **ppEnum
);

파라미터

ppEnum
[out] 새로운 열거자의IEnumMediaTypes 인터페이스에의 포인터를 받는 변수의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | Null 포인터 인수.
VFW_E_ENUM_OUT_OF_SYNC | 핀 상태가 변경이 되어, 현재 그 열거자와 호환성이 없다.

주의

미디어 타입이 변경되면(자), 열거자는 그 핀과의 호환성을 없애, 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. 열거자에게로의 그 전의 호출로 취득한 데이터는 폐기하는 것, 왜냐하면 유효하지 않을 가능성이 있기 때문이다. Reset 메소드를 호출해 열거자를 업데이트 하는 것. 그러면 Clone 메소드를 안전하게 호출할 수가 있다.

IEnumMediaTypes::Next

IEnumMediaTypes 인터페이스

지정한 수의 미디어 타입을 취득한다.

구문

HRESULT Next(
    ULONG cMediaTypes,
    AM_MEDIA_TYPE **ppMediaTypes,
    ULONG *pcFetched
);

파라미터

cMediaTypes
[in] 취득하는 미디어 타입수.
ppMediaTypes
[out] cPins 사이즈의 AM_MEDIA_TYPE 구조체에의 포인터의 배열.
pcFetched
[out] 메소드가 돌려준 미디어 타입의 수를 받는 변수에의 포인터. cMediaTypes 가 1 이라면 NULL 의 경우도 있다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 요구된 미디어 타입의 수와 같은 수를 취득할 수 없었다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
VFW_E_ENUM_OUT_OF_SYNC | 핀 상태가 변경이 되어, 현재 그 열거자와 호환성이 없다.

주의

메소드가 성공하면(자),ppMediaTypes 에 의해 지정된 배열에는 AM_MEDIA_TYPE 구조체에의 포인터가 들어간다. 구조체의 수는 *pcFetched 와 동일하다. DeleteMediaType 를 호출해 각 미디어 타입을 해방하는 것.

미디어 타입이 변경되면(자), 열거자는 그 핀과의 호환성을 없애, 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. 열거자에게로의 그 전의 호출로 취득한 데이터는 폐기하는 것, 왜냐하면 유효하지 않을 가능성이 있기 때문이다. Reset 메소드를 호출해 열거자를 업데이트 하는 것. 그러면 Next 메소드를 안전하게 호출할 수가 있다.

IEnumMediaTypes::Reset

IEnumMediaTypes 인터페이스

열거 순서를 선두로부터 리셋 한다.

구문

HRESULT Reset(void);

반환값

S_OK 를 돌려준다.

IEnumMediaTypes::Skip

IEnumMediaTypes 인터페이스

지정한 수의 미디어 타입을 스킵 한다.

구문

HRESULT Skip(
    ULONG cMediaTypes);

파라미터

cMediaTypes
[in] 스킵 하는 미디어 타입의 수.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 스킵은 순서의 마지막을 넘겼다.
S_OK | 성공.
VFW_E_ENUM_OUT_OF_SYNC | 핀 상태가 변경되어 현재 그 열거자와 호환성이 없다.

주의

미디어 타입이 변경되면(자), 열거자는 그 핀과의 호환성을 없애, 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. 열거자에게로의 그 전의 호출로 취득한 데이터는 폐기하는 것, 왜냐하면 유효하지 않을 가능성이 있기 때문이다. Reset 메소드를 호출해 열거자를 업데이트 하는 것. 그러면 Skip 메소드를 안전하게 호출할 수가 있다.


IEnumPIDMap 인터페이스

이 인터페이스는 패킷 ID (PID) 맵의 표준 COM 콜렉션으로 이행 되고 있는, PID 맵은 MPEG-2 디멀티플렉서의 출력 핀의 IMPEG2PIDMap::MapPID 메소드를 호출하는 것으로 생성 된다. 이 인터페이스의 포인터를 취득하려면 ,IMPEG2PIDMap::EnumPIDMap 메소드를 사용한다. 보통, 오디오와 비디오 스트림의 출력 핀은 주어진 시간에 맵 된 PID 를 1 개 밖에 가지지 않는다. 이 콜렉션은 그것이 생성 되었을 때에 맵 된 PID 의 snapshot를 나타낸다. 이 콜렉션은 자동적으로는 업데이트 되지 않는다.

메소드명 | 설명
Clone | 새로운 콜렉션과 그 서브 오브젝트 모든 새로운 카피를 생성 한다.
Next | 콜렉션의 다음의 n 요소를 취득한다.
Reset | 이타레이타를 콜렉션의 선두로 이동한다.
Skip | 콜렉션내의 지정한 요소를 스킵 한다.

IEnumPIDMap::Clone

IEnumPIDMap 인터페이스

콜렉션을 카피한다.

구문

HRESULT Clone(
    IEnumPIDMap** ppIEnumPIDMap
    );

파라미터

ppIEnumPIDMap
[out] 돌려주어지는 콜렉션 오브젝트에 세트 되는 IEnumPIDMap 인터페이스 포인터의 주소.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 표준 COM IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumPIDMap::Next

IEnumPIDMap 인터페이스

콜렉션의 다음의 n 요소를 취득한다.

구문

HRESULT Next(
    ULONG cRequest,
    PID_MAP* pPIDMap,
    ULONG* pcReceived
    );

파라미터

cRequest
[in] 취득하는 요소의 수.
pPIDMap
[in, out, size_is (cRequest)] 호출원이 할당한 배열의 주소, 취득되는 PID_MAP 구조체를 받는 cRequest 요소가 들어간다.
pcReceived
[out] 실제로 취득된 요소의 수가 들어가는 ULONG 형의 변수의 포인터.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 표준 COM IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

cRequest = 0 또한 pcReceived 가 NULL 라면, 콜렉션에 남아 있는 PID 맵의 수가 들어간 pcReceived 가 돌아간다.

IEnumPIDMap::Reset

IEnumPIDMap 인터페이스

이타레이타를 콜렉션의 선두로 이동한다.

구문

HRESULT Reset();

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 표준 COM IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumPIDMap::Skip

IEnumPIDMap 인터페이스

콜렉션내의 지정한 요소를 스킵 한다.

구문

HRESULT Skip(
    ULONG cRecords
    );

파라미터

cRecords
[in] 스킵 하는 요소의 인덱스.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 표준 COM IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IEnumPins 인터페이스

필터 위에의 핀을 열거한다.

IBaseFilter::EnumPins 메소드는, 이 인터페이스를 돌려준다. 이 메소드는, 표준 Component Object Model (COM) 열거자를 기본으로 하고 있다. 상세한 것에 대하여는, Platform SDK 의 「IEnumXXXX」라고 하는 주제를 참조할것.

필터 그래프 매니저는, 필터와 접속 하면 군령의 인터페이스를 사용한다. 어플리케이션은, 이 인터페이스를 사용해, 필터 위에의 핀을 취득할 수가 있다. 상세한 것에 대하여는, 「필터 그래프내의 오브젝트의 열거」를 참조할것.

필터의 핀의 수가 변경이 되면(자), 이 인터페이스의 몇개의 메소드가 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. Reset 를 호출해 열거자를 재동기 한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IEnumPins 메소드 | 설명
Next | 지정한 수의 핀을 취득한다.
Skip | 지정한 수의 핀을 스킵 한다.
Reset | 열거자를 순서의 선두로부터 리셋 한다.
Clone | 같은 열거 상태로 열거자의 카피를 생성 한다.

IEnumPins::Clone

IEnumPins 인터페이스

같은 열거 상태로 열거자의 카피를 생성 한다.

구문

HRESULT Clone(
    IEnumPins **ppEnum
);

파라미터

ppEnum
[out] 새로운 열거자의 IEnumPins 인터페이스에의 포인터를 받는 변수의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | Null 포인터 인수.
VFW_E_ENUM_OUT_OF_SYNC | 필터 상태가 변경이 되어, 현재 그 열거자와 호환성이 없다.

주의

핀의 수가 변경되면(자), 열거자는 그 핀과의 호환성을 없애, 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. 열거자에게로의 그 전의 호출로 취득한 데이터는 폐기하는 것, 왜냐하면 유효하지 않을 가능성이 있기 때문이다. Reset 메소드를 호출해 열거자를 업데이트 하는 것. 그러면 Clone 메소드를 안전하게 호출할 수가 있다.

IEnumPins::Next

IEnumPins 인터페이스

열거 순서로 지정한 수의 핀을 취득한다.

구문

HRESULT Next(
    ULONG cPins,
    IPin **ppPins,
    ULONG *pcFetched
);

파라미터

cPins
[in] 취득하는 핀의 수.
ppPins
[out] IPin 포인터가 기입해지는 cPins 사이즈의 배열.
pcFetched
[out] 취득한 핀의 수를 받는 변수에의 포인터. cPins 가 1 이라면 NULL 의 경우도 있다.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 요구한 수와 같은 수의 핀을 취득할 수 없었다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
VFW_E_ENUM_OUT_OF_SYNC | 필터 상태가 변경이 되어, 현재 그 열거자와 호환성이 없다.

주의

이 메소드는, 열거의 현재 위치로부터 시작 해, 지정한 수의 핀에의 포인터를 취득해, 그것을 지정한 배열에 둔다.

메소드가 성공하면(자),IPin 포인터 모두에게 참조 카운트가 남는다. 해방시에 주의가 필요.

핀의 수가 변경되면(자), 열거자는 그 핀과의 호환성을 없애, 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. 열거자에게로의 그 전의 호출로 취득한 데이터는 폐기하는 것, 왜냐하면 유효하지 않을 가능성이 있기 때문이다. Reset 메소드를 호출해 열거자를 업데이트 하는 것. 그러면 Next 메소드를 안전하게 호출할 수가 있다.

IEnumPins::Reset

IEnumPins 인터페이스

열거자를 순서의 선두로부터 리셋 한다.

구문

HRESULT Reset(void);

반환값

S_OK 를 돌려준다.

IEnumPins::Skip

IEnumPins 인터페이스

지정한 수의 핀을 스킵 한다.

구문

HRESULT Skip(
    ULONG cPins
);

파라미터

cPins
[in] 스킵 하는 핀수.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 스킵은 순서의 마지막을 넘겼다.
S_OK | 성공.
VFW_E_ENUM_OUT_OF_SYNC | 필터 상태가 변경이 되어, 현재 그 열거자와 호환성이 없다.

주의

핀의 수가 변경되면(자), 열거자는 그 핀과의 호환성을 없애, 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. 열거자에게로의 그 전의 호출로 취득한 데이터는 폐기하는 것, 왜냐하면 유효하지 않을 가능성이 있기 때문이다. Reset 메소드를 호출해 열거자를 업데이트 하는 것. 그러면 Skip 메소드를 안전하게 호출할 수가 있다.


IEnumStreamIdMap 인터페이스

이 인터페이스는 MPEG-2 디멀티플렉서의IMPEG2StreamIdMap::MapStreamID 메소드에 의해 생성 된 스트림 ID 맵의 표준 COM 콜렉션으로 이행 되고 있다. 이 인터페이스의 포인터를 취득하려면 ,IMPEG2StreamIdMap::EnumStreamIdMap 메소드를 사용한다. 보통, 출력 핀은 주어진 시간에 그것을 맵 하는 스트림 ID 를 1 이상은 가지지 않는다. 이 콜렉션은 그것이 생성 되었을 때에 맵 된 스트림 ID 의 snapshot를 나타낸다. 이 콜렉션은 자동적으로는 업데이트 되지 않는다.

메소드명 | 설명
Clone | 새로운 콜렉션과 그 서브 오브젝트 모든 새로운 카피를 생성 한다.
Next | 콜렉션의 다음의 n 요소를 취득한다.
Reset | 이타레이타를 콜렉션의 선두로 이동한다.
Skip | 콜렉션내의 지정한 요소를 스킵 한다.

IEnumStreamIdMap::Clone

IEnumStreamIdMap 인터페이스

콜렉션을 카피한다.

구문

HRESULT Clone(
    IEnumStreamIdMap** ppIEnumStreamIdMap
    );

파라미터

ppIEnumStreamIdMap
[out] 돌려주어지는 콜렉션 오브젝트에 세트 되는 IEnumStreamIdMap 인터페이스 포인터의 주소.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 표준 COM IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumStreamIdMap::Next

IEnumStreamIdMap 인터페이스

콜렉션의 다음의 n 요소를 취득한다.

구문

HRESULT Next(
    ULONG cRequest,
    STREAM_ID_MAP* pStreamIdMap,
    ULONG* pcReceived
    );

파라미터

cRequest
[in] 취득하는 요소의 수.
pStreamIdMap
[in, out, size_is (cRequest)] 호출원이 할당한 배열의 주소, 취득되는 STREAM_ID_MAP 구조체를 받는 cRequest 요소가 들어간다.
pcReceived
[out] 실제로 취득된 요소의 수가 들어가는 ULONG 형의 변수의 포인터.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 표준 COM IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

주의

cRequest = 0 또한 pcReceived 가 NULL 라면, 콜렉션에 남아 있는 PID 맵의 수가 들어간 pcReceived 가 돌아간다.

IEnumStreamIdMap::Reset

IEnumStreamIdMap 인터페이스

이타레이타를 콜렉션의 선두로 이동한다.

구문

HRESULT Reset();

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 표준 COM IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.

IEnumStreamIdMap::Skip

IEnumStreamIdMap 인터페이스

콜렉션내의 지정한 요소를 스킵 한다.

구문

HRESULT Skip(
    ULONG cRecords
    );

파라미터

cRecords
[in] 스킵 하는 요소의 인덱스.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 표준 COM IErrorInfo 인터페이스를 사용해 에러 정보를 취득할 수 있다.


IFileSinkFilter 인터페이스

IFileSinkFilter 인터페이스는, 미디어 스트림을 파일에 기입하는 필터에 이행 된다. 예를 들어, 비디오 캡춰용 필터 그래프의 파일 세면대 필터에서는, 비디오압축 필터의 출력을 파일에 기입한다. 보통, 이 필터 그래프를 실행하는 어플리케이션에서는, 유저가 출력처의 파일명을 입력할 수 있을 필요가 있다. 이 인터페이스를 사용 하면, 그 정보를 교환할 수 있다.

Microsoft® ActiveMovie® 1.0 과의 후방 호환성을 유지할 필요가 없는 경우는, 이 인터페이스는 아니고 IFileSinkFilter2 를 사용해도 괜찮다.

출력 파일명을 받을 필요가 있는 필터에서는, 어플리케이션으로부터 파일명을 설정하기 위해(때문에), 이 인터페이스를 공개해야 한다. 현재, 이 인터페이스를 이행 하는 base class는 없다.

파일 세면대 필터의 출력처 파일명을 설정할 필요가 있는 어플리케이션에서는, 이 인터페이스를 사용해 파일명을 취득 및 설정하는 것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFileSinkFilter 메소드 | 설명
SetFileName | 미디어 샘플의 출력처 파일명을 설정한다.
GetCurFile | 미디어 샘플이 기입해지는 현재의 파일 (세면대 파일)의 이름을 취득한다.

IFileSinkFilter::GetCurFile

IFileSinkFilter 인터페이스

미디어 샘플이 기입해지는 현재의 파일 (세면대 파일)의 이름을 취득한다.

구문

HRESULT GetCurFile(
    LPOLESTR *ppszFileName,
    AM_MEDIA_TYPE *pmt
);

파라미터

ppszFileName
[out] 미디어 샘플의 출력처 파일명에의 포인터의 주소.
pmt
[out] 파일에 기입해지는 미디어 샘플의 타입에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

파일명을 할당할 수 없었던 경우, 이 메소드는 E_FAIL 를 돌려준다.

IFileSinkFilter::SetFileName

IFileSinkFilter 인터페이스

미디어 샘플의 출력처 파일명을 설정한다.

구문

HRESULT SetFileName(
    LPCOLESTR pszFileName,
    const AM_MEDIA_TYPE *pmt
);

파라미터

pszFileName
[in] 미디어 샘플의 출력처 파일명에의 포인터.
pmt
[in] 파일에 기입하는 미디어 샘플의 타입과 세면대 필터의입력 핀의 미디어 타입에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

pszFileName 파라미터의 파일이 존재하지 않는 경우에는, 그 파일이 생성 된다. 기존 파일의 경우, 세면대 필터는 파일을 먼저 파기에 오버라이드(override) 한다.


IFileSinkFilter2 인터페이스

IFileSinkFilter2 인터페이스는,IFileSinkFilter 인터페이스로부터 파생하는 것이어, Microsoft® ActiveMovie® 1.0 과의 후방 호환성을 유지할 필요가 없는 경우는, 이쪽의 인터페이스를 사용해도 괜찮다. IFileSinkFilter 같이, 미디어 스트림을 파일에 기입하는 필터에서는, 이 인터페이스를 이행 한다. 예를 들어, 비디오 캡춰용 필터 그래프의 파일 세면대 필터는,압축 필터의 출력을 파일에 보존한다. 보통, 이 필터 그래프를 실행하는 어플리케이션에서는, 유저가 보존처의 파일명을 입력할 수 없으면 안 된다. 이 인터페이스를 사용 하면, 그 정보를 교환할 수 있다. IFileSinkFilter2 에는, 이미 같은 이름의 파일이 있는 경우에 기존 파일을 파기해야할 것인가 제발을 결정하는 옵션이 더해지고 있다. 비디오 캡춰의 경우, 파일 용량을 사전에 할당하려면 매우 시간이 걸리기 (위해)때문에, 이미 생성 한 파일을 파기하지 않는 것. 디폴트에서는, 원의 파일은 파기되지 않는다. 그 이외의 경우, 새롭게 기입하는 파일에 불필요한 데이터를 남기지 않기 때문에, 원의 파일이 파기된다.

출력 파일명을 필요로 하는 필터, 또는 출력 파일의 옵션을 설정할 필요가 있는 필터에서는, 이 인터페이스를 이행 해야 한다. 개발하는 필터와 ActiveMovie 1.0 과의 호환성을 유지하려면 , 종래의 IFileSinkFilter 인터페이스를 이행 한다. 현재, 이 인터페이스를 이행 하는 base class는 없다.

파일 세면대 필터의 출력처 파일명을 설정할 필요가 있는 어플리케이션에서는, 이 인터페이스를 사용해, 파일명을 취득 및 설정하는지, 또는 옵션을 설정해야 한다. 개발하는 어플리케이션과 ActiveMovie 1.0 과의 호환성을 유지하려면 , 종래의 IFileSinkFilter 인터페이스를 사용하는 것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFileSinkFilter 메소드 | 설명
SetFileName | 미디어 샘플의 출력처 파일명을 설정한다.
GetCurFile | 미디어 샘플이 기입해지는 현재의 파일 (세면대 파일)의 이름을 취득한다.
IFileSinkFilter2 메소드 | 설명
SetMode | 신규 파일의 생성시에 파일 라이터가 파일을 파기할지 어떨지를 결정한다.
GetMode | 신규 파일의 생성시에 파일 라이터가 파일을 파기할지 어떨지를 취득한다.

IFileSinkFilter2::GetMode

IFileSinkFilter2 인터페이스

신규 파일의 생성시에 파일 라이터가 파일을 파기할지 어떨지를 취득한다.

구문

HRESULT GetMode(
    DWORD *dwFlags
);

파라미터

dwFlags
[out] 취득된 플래그에의 포인터. 현재 정의되고 있는 플래그는, 파일을 파기하는 것을 나타내는 AM_FILE_OVERWRITE 마셔. 0 은 파일을 파기하지 않는 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IFileSinkFilter2::SetMode

IFileSinkFilter2 인터페이스

신규 파일의 생성시에 파일 라이터가 파일을 파기할지 어떨지를 결정한다.

구문

HRESULT SetMode(
    DWORD dwFlags
);

파라미터

dwFlags
[in] 현재 정의되고 있는 플래그는, 파일을 파기하는 것을 나타내는 AM_FILE_OVERWRITE 마셔. 파일을 파기하지 않기 위해(때문에)는,dwFlags 에 0 을 지정한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.


IFileSourceFilter 인터페이스

IFileSourceFilter 인터페이스는, 렌더링 하는 미디어 파일의 파일명 및 미디어 타입을 설정하기 위해(때문에), 소스 필터로 공개된다. 이 인터페이스는,IPersistFile COM 인터페이스의 생략판이다. 「커스텀 파일 타입의 등록」에 있는 알고리즘으로 판단할 수 있는 타입의 파일의 경우, 그 필터 그래프를 렌더링 하면 와, 필터 그래프 매니저는 추천 된 파일 소스 필터의 CLSID 를 사용한다.

파일을 열 때 파일명이 필요한 필터에서는, 어플리케이션으로부터 파일명을 설정하기 위해(때문에), 이 인터페이스를 공개해야 한다. 현재, 이 인터페이스를 이행 하는 base class는 없다.

파일 소스 필터를 직접 삽입하는 어플리케이션에서는, 이 인터페이스를 조회해, 파일명을 설정해야 한다. 보통, 어플리케이션으로부터 IGraphBuilder::RenderFile 를 호출하면, 필터 그래프 매니저는 이 인터페이스를 사용한다. Graphedt.exe 툴은,IFileSourceFilter 인터페이스를 조회해, 인터페이스를 알 수 있으면(자), 파일명의 입력을 요구하는 prompt를 표시한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFileSourceFilter 메소드 | 설명
Load | 소스 필터에 파일을 로드한다.
GetCurfile | 현재의 파일을 취득한다.

IFileSourceFilter::GetCurfile

IFileSourceFilter 인터페이스

여는 파일에 관한 정보를 수집한다.

구문

HRESULT GetCurfile(
  LPOLESTR *ppszFileName,
  AM_MEDIA_TYPE *pmt
  );

파라미터

ppszFileName
[out] 로드 된 파일의 패스에의 포인터의 주소.
pmt
[out] 미디어 타입에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IFileSourceFilter::Load

IFileSourceFilter 인터페이스

미디어 파일을 로드한다.

구문

HRESULT Load(
  LPCOLESTR pszFileName,
  const AM_MEDIA_TYPE *pmt
  );

파라미터

pszFileName
[in] 여는 파일의 절대 패스에의 포인터.
pmt
[in] 파일의 미디어 타입에의 포인터. NULL 의 경우가 있다.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는 인터페이스의 초기화 메소드이다. 복수 파일을 로드하도록(듯이) 설계되어 있지 않기 때문에, 최초의 호출해 이후의 호출은 모두 실패한다.

pszFileName 로 지정된 파일을 로드하려면 , 이 메소드를 이행 해야 한다.

pszFileName 의 이름은, 디스크 파일명 (예를 들어 Microsoft® Win32® CreateFile 함수에 건네줄 수가 있는 파일명)일 필요는 없다. URL 명이라도 좋다. URL 모니카 필터는,IFileSourceFilter 를 사용해 그 URL 명을 취득해,IGraphBuilder::AddSourceFilter ( 및 IGraphBuilder::RenderFile )가 그것을 적절히 처리한다. 파일이 발견되지 않는 경우,IGraphBuilder::AddSourceFilter 는 고유의 에러 (ERROR_FILE_NOT_FOUND)를 돌려준다. 이 에러는, 지정된 파일이 존재하지 않는다고 하는 의미이며, 필터가 존재하지 않는다고 하는 의미는 아니다.


IFilterChain 인터페이스

이 인터페이스는, 필터 그래프의 필터 체인을 시작, 정지, 또는 삭제하는 메소드를 제공한다. 필터 그래프 매니저가 이 인터페이스를 공개한다.

"필터 체인" 은, 일련의 포르타로부터 완성되는 1 개(살)이 연속한 필터이다. 개개의 필터에는 1 개까지의 입력 핀과 1 개의 출력 핀이 접속된다. 필터 체인은, 체인 선두 필터와 체인 종단 필터에 의해 정의된다 (선두 필터와 종단 필터가 같은 경우는, 필터를 1 개만 포함한 체인이 된다). 정의에 의해, 체인의 선두로부터 다운 스트림에 종단까지 계속되는 단일의 스트림이 생긴다.

이 인터페이스의 메소드는, 네트워크 경유로 복수의 스트림을 수신하는 TV 회의 어플리케이션과 같이, 데이터 스트림 전체가 나타나거나 사라지거나 하는 경우에 이용한다. 상세한 것에 대하여는, 「동적 그래프 생성」을 참조할것. 캡춰 필터 위에의 개개의 스트림을 제어하려면 , 이 인터페이스는 아니고,IAMStreamControl 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFilterChain 메소드 | 설명
StartChain | 필터 체인의 필터를 모두 실행 상태로 전환한다.
StopChain | 필터 체인의 필터를 모두 정지상태태로 전환한다.
RemoveChain | 필터 체인의 필터를 모두 필터 그래프로부터 삭제한다.
PauseChain | 필터 체인의 필터를 모두 일시 포즈 상태로 전환한다.

IFilterChain::PauseChain

IFilterChain 인터페이스

필터 체인의 필터를 모두 포즈 상태로 전환한다.

구문

HRESULT PauseChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter
);

파라미터

pStartFilter
[in] 체인 선두 필터에의 포인터.
pEndFilter
[in] 체인 종단 필터에의 포인터. 이 파라미터가 NULL 의 경우, 메소드는 선두 필터로부터 다운 스트림으로 계속되는 최장의 필터 체인을 사용한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 메소드가 실패했을 경우, 반환값은 VFW_E_NOT_PAUSED 또는 그 외의 HRESULT 값이 된다.

주의

소정의 필터를 포즈 상태로 전환할 수가 할 수 없는 경우, 이 메소드는 체인의 필터를 모두 정지한다. 이 메소드를 호출하면 와, 필터 그래프는 포즈 하고 있지 않으면 안 된다.

IFilterChain::RemoveChain

IFilterChain 인터페이스

필터 체인의 필터를 모두 필터 그래프로부터 삭제한다.

구문

HRESULT RemoveChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter
);

파라미터

pStartFilter
[in] 체인 선두 필터에의 포인터.
pEndFilter
[in] 체인 종단 필터에의 포인터. 이 파라미터가 NULL 의 경우, 메소드는 선두 필터로부터 다운 스트림으로 계속되는 최장의 필터 체인을 사용한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는 그래프 실행중에 호출할 수가 있다. 그 경우, 메소드는 체인내의 필터를 정지하고 나서 필터를 그래프로부터 삭제한다.

IFilterChain::StartChain

IFilterChain 인터페이스

필터 체인의 필터를 모두 실행 상태로 전환한다.

구문

HRESULT StartChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter
);

파라미터

pStartFilter
[in] 체인 선두 필터에의 포인터.
pEndFilter
[in] 체인 종단 필터에의 포인터. 이 파라미터가 NULL 의 경우, 메소드는 선두 필터로부터 다운 스트림으로 계속되는 최장의 필터 체인을 사용한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 메소드가 실패했을 경우, 반환값은 VFW_E_NOT_RUNNING 또는 그 외의 HRESULT 값이 된다.

주의

소정의 필터를 실행 상태로 전환할 수가 할 수 없는 경우, 필터는 모두 정지상태태에 머문다. 이 메소드를 호출하면 와, 필터 그래프는 실행중이 아니면 안된다.

IFilterChain::StopChain

IFilterChain 인터페이스

필터 체인의 필터를 모두 정지상태태로 전환한다.

구문

HRESULT StopChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter
);

파라미터

pStartFilter
[in] 체인 선두 필터에의 포인터.
pEndFilter
[in] 체인 종단 필터에의 포인터. 이 파라미터가 NULL 의 경우, 메소드는 선두 필터로부터 다운 스트림으로 계속되는 최장의 필터 체인을 사용한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다.


IFilterGraph 인터페이스

이 인터페이스는 필터 그래프를 구축하는 메소드를 제공한다. 어플리케이션으로부터 이 인터페이스를 사용해, 그래프에 필터를 추가하거나 필터를 접속 또는 절단 하거나 필터를 삭제하거나 그 외의 기본적인 조작을 실행할 수가 있다. 다만,IGraphBuilder 인터페이스는, 이 인터페이스를 계승해, 한층 더 고도의 메소드를 제공한다. 따라서, 어플리케이션에서는,IFilterGraph 를 직접 사용하지 않고 ,IGraphBuilder 를 사용하는 것.

필터 그래프 매니저가 이 인터페이스를 이행 한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFilterGraph 메소드 | 설명
AddFilter | 그래프에 필터를 추가해, 그 필터에 이름을 붙인다.
RemoveFilter | 그래프로부터 필터를 삭제한다.
EnumFilters | 그래프의 필터 모두에 대해서 열거자를 제공한다.
FindFilterByName | 특정의 이름으로 추가된 필터를 검색한다.
ConnectDirect | 2 개의 핀을 직접 접속한다 (필터를 통하지 않는다).
Reconnect | 기존의 핀 접속을 절단 해, 같은 핀에 재접속한다.
Disconnect | 특정의 핀을 절단 한다.
SetDefaultSyncSource | 디폴트의 동기 기준 (클락)을 설정한다.

IFilterGraph::AddFilter

IFilterGraph 인터페이스

그래프에 필터를 추가해, 그 필터에 이름을 붙인다.

구문

HRESULT AddFilter(
    IBaseFilter *pFilter,
    LPCWSTR pName
);

파라미터

pFilter
[in] 그래프에 추가하는 필터에의 포인터.
pName
[in] 필터명에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음과 같다.

S_OK | 성공.
VFW_S_DUPLICATE_NAME | 이름이 중복 한 필터의 추가에 성공했다.
E_FAIL | 실패.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | Null 포인터 인수.
VFW_E_CERTIFICATION_FAILURE | 이 필터의 사용은, 소프트웨어 키에 의해 제한된다.
VFW_E_DUPLICATE_NAME | 이름이 중복 한 필터의 추가에 실패했다.

주의

필터명은 NULL 의 경우가 있다. 그 경우, 필터 그래프 매니저가 이름을 생성한다. 필터명이 NULL 이외로 일의가 아닌 경우, 이 메소드는, 필터명을 변경해 일의인 이름을 생성하려고 한다. 이것에 성공하면(자), VFW_S_DUPLICATE_NAME 를 돌려준다. 일의인 이름을 생성할 수 없는 경우는, VFW_E_DUPLICATE_NAME 를 돌려준다.

AddFilter 는, 필터의 IBaseFilter::JoinFilterGraph 메소드를 호출해, 필터가 추가된 것을 그 필터에 통지한다. IGraphBuilder::Connect 메소드,IFilterGraph::ConnectDirect 메소드, 또는 IGraphBuilder::Render 메소드를 사용해, 추가한 필터에 속하는 핀을 접속 또는 렌더링 하는 경우에는, 그 전에 AddFilter 를 호출하지 않으면 안 된다.

IFilterGraph::ConnectDirect

IFilterGraph 인터페이스

2 개의 핀을 직접 접속한다 (필터를 통하지 않는다).

구문

HRESULT ConnectDirect(
    IPin *ppinOut,
    IPin *ppinIn,
    const AM_MEDIA_TYPE *pmt
);

파라미터

ppinOut
[in] 출력 핀에의 포인터.
ppinIn
[in] 입력 핀에의 포인터.
pmt
[in] 접속에 사용하는 미디어 타입에의 포인터 (생략, 즉 NULL 도 가능).

반환값

다음의 몇개의 값인가, 또는 IPin::Connect 가 돌려준 에러값을 돌려준다.

S_OK | 성공.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_IN_GRAPH | 지정된 핀중 한쪽이 그래프에 포함되지 않았다.
VFW_E_CIRCULAR_GRAPH | 입력 핀이 출력 핀의 업 스트림에 있기 (위해)때문에, 그래프가 순환한다.

IFilterGraph::Disconnect

IFilterGraph 인터페이스

이 핀을 절단 한다.

구문

HRESULT Disconnect(
    IPin *ppin
);

파라미터

ppin
[in] 절단 하는 핀에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
S_FALSE | 핀이 접속되어 있지 않다. 에러 없음.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_STOPPED | 필터가 정지하고 있지 않지만, 실행 상태에서의 재접속이 지원되어 있지 않다.

주의

이 메소드에서는, 접속이 완전하게는 절단 되지 않는다. 완전하게 절단 하려면 , 양단을 절단 해야 한다.

IFilterGraph::EnumFilters

IFilterGraph 인터페이스

그래프의 필터 모두에 대해서 열거자를 제공한다.

구문

HRESULT EnumFilters(
    IEnumFilters **ppEnum
);

파라미터

ppEnum
[out] 열거자에게로의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족을 위해, 열거자를 생성 할 수 없다.
E_POINTER | Null 포인터 인수.

주의

이 메소드에 의해 돌려주어지는 인터페이스는, 인크리먼트(increment) 되고 있는 참조 카운트를 가지고 있다. 인터페이스를 다 사용했을 경우는, 인터페이스상에서 반드시 IUnknown::Release 를 사용해, 참조 카운트를 감소 하는 것.

IFilterGraph::FindFilterByName

IFilterGraph 인터페이스

특정의 이름으로 필터 그래프에 추가된 필터를 검색한다.

구문

HRESULT FindFilterByName(
    LPCWSTR pName,
    IBaseFilter **ppFilter
);

파라미터

pName
[in, string] 검색하는 이름에의 포인터.
ppFilter
[out] 발견된 필터의 IBaseFilter 인터페이스에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_FOUND | 지정된 이름의 필터가 발견되지 않는다.

주의

필터가 발견되지 않는 경우, 메소드는 ppFilter 파라미터에 NULL 포인터를 돌려준다.

IFilterGraph::Reconnect

IFilterGraph 인터페이스

이 필터 그래프와 핀의 접속을 절단 해, 같은 핀에 재접속한다. 이것에 의해, 접속의 상세 (미디어 타입이나 allocater등)를 네고시에이트 다시 할 수가 있다.

구문

HRESULT Reconnect(
    IPin *ppin
);

파라미터

ppin
[in] 절단 및 재접속하는 핀에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.
VFW_E_WRONG_STATE | 필터가 정지하고 있지 않다.

주의

이 메소드는, 관련하는 락을 보관 유지하지 않는 독립한 thread로 조작을 실행한다. 핀 또는 필터로부터 이 메소드를 호출해, 접속의 네고시에이션을 다시 할 수가 있다. 변환 필터는, 그 입력과 접속할 경우에 미디어 타입을 결정하지 않으면 안 된다. 그 후, 출력을 접속하는 시점에서, 업 스트림과 다운 스트림의 접속을 모두 만족시키려면 , 업 스트림의 접속에 다른 미디어 타입을 선택하는 것이 좋았던 것을 아는 경우가 있다. 그 해결책이 입력 핀의 재접속이다. 재접속은 비동기에게 실행되어 에러를 보고 또는 정정하는 수단이 없기 때문에, 이 메소드의 호출원에서는, 네고시에이션의 재시도가 성공하는 것을 (예를 들어 IPin::QueryAccept 를 호출해) 확인해야 한다.

IFilterGraph::RemoveFilter

IFilterGraph 인터페이스

그래프로부터 필터를 삭제한다.

구문

HRESULT RemoveFilter(
    IBaseFilter *pFilter
);

파라미터

pFilter
[in] 그래프로부터 삭제하는 필터에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.

주의

필터 그래프의 이행은, 인수 NULL 로 IBaseFilter::JoinFilterGraph 메소드를 호출해, 필터가 삭제되는 것을 그 필터에 통지한다. RemoveFilter 를 호출하기 전에 필터의 핀을 떼어낼 필요가 없지만, 필터 그래프는 정지상태태에 해야 한다. 필터가 정지하고 있지 않으면RemoveFilter 는 핀과의 떼어내에 실패해, 그래프로부터의 필터의 삭제에 실패할지도 모른다. IGraphConfig::RemoveFilterEx 를 사용하면(자), 어플리케이션은 핀과의 떼어내 없이 필터를 자동적으로 삭제할 수 있는, 이것은 접속되고 있는 필터를 새로운 그래프로 이동하고 싶을 때 퍼포먼스를 개선한다.

IFilterGraph::SetDefaultSyncSource

IFilterGraph 인터페이스

디폴트의 동기 기준을 설정한다.

구문

HRESULT SetDefaultSyncSource(void);

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우,VFW_E_NOT_STOPPED (그래프가 정지상태태에 없는 것을 나타낸다) 또는 그 외의 에러값을 돌려준다.

주의

이 메소드는, 필터 그래프에 클락이 공급되어 있지 않을 때, 필터 그래프 매니저가 동기 기준으로서 사용하는 클락을 찾기 위해서(때문에) 사용한다. 필터 그래프 매니저는, 렌더러로부터 순서에,IReferenceClock 인터페이스를 제공하는 최초의 필터를 선택하면서, 접속되고 있는 필터를 모두 시험해 간다. 접속되고 있는 필터가 없는 경우, 필터 그래프 매니저는, 클락을 export 하는 접속되어 있지 않은 필터를 선택한다. 보통, 이 때 선택되는 것은 오디오 렌더링 필터이다. 클락을 export 하는 접속되어 있지 않은 필터가 없는 경우, 필터 그래프 매니저는 시스템 클록을 생성 한다.


IFilterGraph2 인터페이스

이 인터페이스는, 필터 그래프를 구축하는 메소드를 제공하는 IFilterGraph 인터페이스 및 IGraphBuilder 인터페이스를 확장한다.

필터 그래프 매니저가 이 인터페이스를 이행 한다. 어플리케이션으로 그래프를 구축 하면 와, 이 인터페이스를 사용 하면, 추가의 메소드를 이용할 수 있다.

IFilterGraph2 에는,IFilterGraph 및 IGraphBuilder 에 없는 2 개의 메소드가 있다.

  • AddSourceFilterForMoniker 메소드는,모니카에 근거한 소스 필터를 생성 해, 그 소스 필터를 그래프에 추가한다.
  • ReconnectEx 메소드는, 미디어 타입을 지정할 수 있도록(듯이) IFilterGraph::Reconnect 메소드를 개량한 것이다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFilterGraph 메소드 | 설명
AddFilter | 그래프에 필터를 추가해, 그 필터에 이름을 붙인다.
RemoveFilter | 그래프로부터 필터를 삭제한다.
EnumFilters | 그래프의 필터 모두에 대해서 열거자를 제공한다.
FindFilterByName | 특정의 이름으로 추가된 필터를 검색한다.
ConnectDirect | 2 개의 핀을 직접 접속한다 (필터를 통하지 않는다).
Reconnect | 기존의 핀 접속을 절단 해, 같은 핀에 재접속한다.
Disconnect | 특정의 핀을 절단 한다.
SetDefaultSyncSource | 디폴트의 동기 기준 (클락)을 설정한다.
IGraphBuilder 메소드 | 설명
Connect | 2 개의 핀을 접속한다. 직접 접속할 수 없는 경우는 변환을 개입시켜 접속한다.
Render | 특정의출력 핀에 필터 체인을 추가해 렌더링 한다.
RenderFile | 지정된 파일을 렌더링 하는 필터 그래프를 구축한다.
AddSourceFilter | 특정의 파일의 필터 그래프에소스 필터를 추가한다. IGraphBuilder::RenderFile 메소드는 이 메소드를 호출해 소스 필터를 검색한다.
SetLogFile | 로그 파일을 설정한다. 조작을 실행하려고 했을 때 행해진 각 액션은, 이 파일에 출력된다.
Abort | 현재의 태스크로부터 생기는 한 빨리 돌아오도록(듯이) 그래프 빌더에 요구한다.
ShouldOperationContinue | 현재의 조작이 계속해야할 것인가 제발을 조회한다.
IFilterGraph2 메소드 | 설명
AddSourceFilterForMoniker | 모니카에 근거한 소스 필터를 추가한다.
ReconnectEx | 기존의 핀 접속을 절단 해, 특정의 미디어 타입을 사용해 같은 핀에 재접속한다.

IFilterGraph2::AddSourceFilterForMoniker

IFilterGraph2 인터페이스

모니카에 근거한 소스 필터를 추가한다. 예를 들어, 비디오 캡춰 디바이스등의 시스템 디바이스용의 모니카를 취득해, 그 디바이스용의 비디오 캡춰 필터를 추가할 수가 있다 (시스템데바이스모니카의 상세한 것에 대하여는, 「ICreateDevEnum 」를 참조할것).

구문

HRESULT AddSourceFilterForMoniker(
  IMoniker *pMoniker,
  IBindCtx *pCtx,
  LPCWSTR lpcwstrFilterName,
  IBaseFilter **ppFilter );

파라미터

pMoniker
[in] IMoniker 인터페이스에의 포인터.
pCtx
[in] 문맥을 바인드 하는 IBindCtx 인터페이스에의 포인터.
lpcwstrFilterName
[in] 필터명에의 포인터.
ppFilter
[out] IBaseFilter 인터페이스에의 포인터의 주소.

반환값

메소드가 성공했을 경우, 반환값은 다음의 몇개의 값이 된다.

S_OK | 성공.
VFW_S_DUPLICATE_NAME | 이름이 중복 한 필터의 추가에 성공했다.

메소드가 실패했을 경우, 반환값은 다음의 몇개의 에러값이 된다.

E_FAIL | 실패.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_DUPLICATE_NAME | 이름이 중복 한 필터의 추가에 실패했다.
VFW_E_CANNOT_LOAD_SOURCE_FILTER | 소스 필터를 로드할 수 없다.
VFW_E_UNKNOWN_FILE_TYPE | 이 파일의 미디어 타입이 인식되지 않는다.

주의

지정된 모니카를 위한소스 필터를 그래프에 추가 하면 와,IMoniker::BindToStorage COM 멤버 함수는 IStream 인터페이스를 조회한다. 이것에 실패 하면,IMoniker::BindToObject 가 IBaseFilter 인터페이스를 취득하려고 한다.

IFilterGraph2::ReconnectEx

IFilterGraph2 인터페이스

기존의 핀 접속을 절단 해, 특정의 미디어 타입을 사용해 같은 핀에 재접속한다.

구문

HRESULT ReconnectEx(

  IPin *ppin,

  const AM_MEDIA_TYPE *pmt );

파라미터

ppin
[in] 절단 및 재접속하는 핀에의 포인터.
pmt
[in] 재접속에 사용하는 미디어 타입에의 포인터. 기존의 미디어 타입을 사용하려면 , NULL 를 지정한다.

반환값

S_OK | 성공.
S_FALSE | 핀이 접속되어 있지 않다. 에러 없음.

메소드가 실패했을 경우, 반환값은 다음의 몇개의 에러값이 된다.

E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_STOPPED | 필터가 정지하고 있지 않지만, 실행중의 재접속이 지원되어 있지 않다.

주의

ReconnectEx 메소드는,IFilterGraph::Reconnect 메소드 같이, 핀과 그 핀이 현재 접속되고 있는 핀의 재접속을 스케줄 한다. 이 메소드를 호출하면나무에 미디어 타입을 지정 하면, 핀측에서, 원의 접속에 사용되고 있던 타입을 확인하거나 가능성이 있는 새로운 타입을 열거하거나 할 필요가 없기 때문에, 재접속이 성공할 가능성이 높아진다.

참조

IFilterGraph::Reconnect


IFilterInfo 인터페이스

IFilterInfo 인터페이스는, 필터에 관한 정보를 관리해, 필터와 필터에 속하는 핀을 나타내는 IPinInfo 인터페이스에의 액세스를 제공한다. 기본적으로는, Automation 를 통해서 액세스 가능한 IBaseFilter 인터페이스와 같은 것이다. 이 인터페이스는, Microsoft® Visual Basic® 어플리케이션으로부터 IBaseFilter 메소드에 액세스 하면 와,IBaseFilter 인터페이스 자체에 있는 Automation 의 오버헤드를 피하기 위해서(때문에) 생성 되었다.

이 인터페이스는, 필터 그래프 매니저로 이행 되어 Microsoft Visual Basic 등의 Automation 클라이언트 어플리케이션으로부터 사용된다.

어플리케이션에서는, 이 인터페이스를 사용해, 필터에 관한 정보를 취득해, 필터의 개개의 핀 오브젝트, 또는 필터에 속하는 모든 핀 오브젝트의 집합을 취득한다. 필터 그래프에 필터를 추가해, 핀 끼리를 접속할 경우에는, 이 인터페이스를 사용할 수 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IFilterInfo 메소드 | 설명
FindPin | 핀을 찾아,IPinInfo 인터페이스를 돌려준다.
get_Name | 필터명을 취득한다.
get_VendorInfo | 지정된 필터에 관한 옵션 정보가 저장 된 벤더 제공의 캐릭터 라인을 취득한다.
get_Filter | 필터에 대응하는 IBaseFilter 인터페이스를 취득한다.
get_Pins | IAMCollection 인터페이스를 취득한다. 이 인터페이스는, 이 필터에 대응하는 IPinInfo 인터페이스에의 액세스를 제공한다.
get_IsFileSource | 필터가 파일 소스 필터인가 어떤가를 판단한다.
get_Filename | 소스 필터에 관련지을 수 있었던 파일명을 취득한다.
put_Filename | 미디어 소스가 저장 된 파일의 이름을 설정한다.

IFilterInfo::FindPin

IFilterInfo 인터페이스

지정된 식별자의 핀을 찾아,IPinInfo 인터페이스를 돌려준다.

구문

HRESULT FindPin(
    BSTR strPinID,
    IDispatch **ppUnk
);

파라미터

strPinID
[in] 핀 식별자의 캐릭터 라인.
ppUnk
[out] IPinInfo 인터페이스에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는 IBaseFilter::FindPin 메소드에 대응하는 것이다. 이 메소드는, Automation 클라이언트에 의한 사용을 위해서(때문에) 공개된다. 퍼포먼스의 제한을 위해, C 또는 C++ 어플리케이션에 의한 사용은 상정되어 있지 않다.

IFilterInfo::get_Filename

IFilterInfo 인터페이스

소스 필터에 관련지을 수 있었던 파일명을 취득한다.

구문

HRESULT get_Filename(
    BSTR *pstrFilename
);

파라미터

pstrFilename
[out, retval] 소스 미디어가 저장 된 파일의 이름에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, Automation 클라이언트에 의한 사용을 위해서(때문에) 공개된다. 퍼포먼스의 제한을 위해, C 또는 C++ 어플리케이션에 의한 사용은 상정되어 있지 않다.

IFilterInfo::get_Filter

IFilterInfo 인터페이스

필터의 IBaseFilter 인터페이스를 취득한다.

구문

HRESULT get_Filter(
    IUnknown **ppUnk
);

파라미터

ppUnk
[out, retval] IFilterInfo 가 나타내는 필터의 IBaseFilter 인터페이스에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

IFilterInfo 를 이행 하는 오브젝트는, 래퍼이며, 필터와 같은 COM 오브젝트는 아니다. 따라서,IBaseFilter 를 조회하기 위해서 IFilterInfo::QueryInterface 를 호출하면 실패한다. 어플리케이션으로부터 필터 오브젝트 자체를 취득하려면 ,IFilterInfo::get_Filter 메소드를 사용한다. 이 메소드는, Automation 클라이언트에 의한 사용을 위해서(때문에) 공개된다. 퍼포먼스의 제한을 위해, C 또는 C++ 어플리케이션에 의한 사용은 상정되어 있지 않다.

IFilterInfo::get_IsFileSource

IFilterInfo 인터페이스

필터가 파일 소스 필터인가 어떤가를 판단한다.

구문

HRESULT get_IsFileSource(
    LONG *pbIsSource
);

파라미터

pbIsSource
[out, retval] 필터가 파일 소스 필터인가 어떤가를 나타내는 돌려주어진 값에의 포인터. 파일 소스 필터의 경우는, OATRUE 를 돌려준다. 그 이외의 경우는, OAFALSE 를 돌려준다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, Automation 클라이언트에 의한 사용을 위해서(때문에) 공개된다. 퍼포먼스의 제한을 위해, C 또는 C++ 어플리케이션에 의한 사용은 상정되어 있지 않다.

IFilterInfo::get_Name

IFilterInfo 인터페이스

필터명을 취득한다.

구문

HRESULT get_Name(
    BSTR *strName
);

파라미터

strName
[out, retval] 필터명에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, Automation 클라이언트에 의한 사용을 위해서(때문에) 공개된다. 퍼포먼스의 제한을 위해, C 또는 C++ 어플리케이션에 의한 사용은 상정되어 있지 않다.

IFilterInfo::get_Pins

IFilterInfo 인터페이스

IAMCollection 인터페이스를 취득한다. 이 인터페이스는, 이 필터에 속하는 핀에 대응하는 IPinInfo 인터페이스에의 액세스를 제공한다.

구문

HRESULT get_Pins(
    IDispatch **ppUnk
);

파라미터

ppUnk
[out, retval] IAMCollection 인터페이스에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, Automation 클라이언트에 의한 사용을 위해서(때문에) 공개된다. 퍼포먼스의 제한을 위해, C 또는 C++ 어플리케이션에서의 사용은 상정되어 있지 않다. Visual Basic 어플리케이션에서는, 이 메소드가 돌려주는 IAMCollection 오브젝트에 포함되는 IPinInfo 인터페이스를,For Each ...Next 라고 하는 구문을 사용해 열거할 수 있다.

IFilterInfo::get_VendorInfo

IFilterInfo 인터페이스

지정된 필터에 관한 옵션 정보가 저장 된 벤더 제공의 캐릭터 라인을 취득한다.

구문

HRESULT get_VendorInfo(
    BSTR *strVendorInfo
);

파라미터

strVendorInfo
[out, retval] 벤더 제공의 정보가 저장 된 캐릭터 라인에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, Automation 클라이언트에 의한 사용을 위해서(때문에) 공개된다. 퍼포먼스의 제한을 위해, C 또는 C++ 어플리케이션에 의한 사용은 상정되어 있지 않다.

IFilterInfo::put_Filename

IFilterInfo 인터페이스

미디어 소스가 저장 된 파일의 이름을 설정한다.

구문

HRESULT put_Filename(
    BSTR strFilename
);

파라미터

strFilename
[in] 소스 필터가 읽어내는 파일의 이름.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

이 메소드는, Automation 클라이언트에 의한 사용을 위해서(때문에) 공개된다. 퍼포먼스의 제한을 위해, C 또는 C++ 어플리케이션에 의한 사용은 상정되어 있지 않다.


IFilterMapper2 인터페이스

이 인터페이스는, 필터를 등록 및 등록 해제해, 레지스트리내의 필터를 검색한다. 필터 맵퍼 헬퍼 오브젝트는, 이 인터페이스를 이행 한다.

필터에서는, 이 인터페이스를 사용해, 필터 자체를 등록 및 등록 해제한다. 필터 그래프 매니저가 필터 그래프를 구축 하면 와, 이 인터페이스를 사용해 필터를 검색해, 필터의 특성을 판단한다. 어플리케이션으로부터도, 이 인터페이스를 사용해 필터를 검색할 수 있다. 상세한 것에 대하여는, 「필터 맵퍼의 사용」 및 「DirectShow 오브젝트의 등록 방법」을 참조할것.

주 : 이 인터페이스는 IFilterMapper 인터페이스에 취해 대신하는 것이다. IFilterMapper2 에서는, 필터 카테고리, 핀 미디어, 및 핀 카테고리가 지원 되고 있다. 더욱 필터의 등록이 1 개의 메소드 호출에 정리하고 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFilterMapper2 메소드 | 설명
CreateCategory | 레지스트리에 새로운 필터 카테고리를 추가한다.
UnregisterFilter | 레지스트리로부터 필터 정보를 삭제한다.
RegisterFilter | 레지스트리에 필터 정보를 추가한다.
EnumMatchingFilters | 지정된 요건을 채우는 등록이 끝난 필터를 열거한다.

IFilterMapper2::CreateCategory

IFilterMapper2 인터페이스

레지스트리에 새로운 필터 카테고리를 추가한다.

구문

HRESULT CreateCategory(
    REFCLSID clsidCategory,
    DWORD dwCategoryMerit,
    LPCWSTR Description
);

파라미터

clsidCategory
[in] 새로운 필터 카테고리의 클래스 식별자 (CLSID).
dwCategoryMerit
[in] 카테고리의메리트값 . 메리트값의 높은 카테고리(정도)만큼 먼저 열거된다.
Description
[in] 카테고리의 내용을 나타내요 셋집 들이마셔 이름.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

필터 그래프 매니저는, 우선 MERIT_DO_NOT_USE 이하의 메리트값을 가지는 카테고리를 모두 제외하는 것에 의해, 그래프의 구축 처리를 가속화 한다. 재생 시에 고려 해서는 안된 필터 카테고리에는, MERIT_DO_NOT_USE 이하의 메리트값을 설정하는 것.

검색 범위를 짜기 (위해)때문에, 1 개의 필터는 1 개 이상의 카테고리에 포함할 수가 있다 (예를 들어 비디오 압력).

IFilterMapper2::EnumMatchingFilters

IFilterMapper2 인터페이스

지정된 요건을 채우는 등록이 끝난 필터를 열거한다.

구문

HRESULT EnumMatchingFilters(
    IEnumMoniker **ppEnum,
    DWORD dwFlags,
    BOOL bExactMatch,
    DWORD dwMerit,
    BOOL bInputNeeded,
    DWORD cInputTypes,
    const GUID *pInputTypes,
    const REGPINMEDIUM *pMedIn,
    const CLSID *pPinCategoryIn,
    BOOL bRender,
    BOOL bOutputNeeded,
    DWORD cOutputTypes,
    const GUID *pOutputTypes,
    const REGPINMEDIUM *pMedOut,
    const CLSID *pPinCategoryOut
);

파라미터

ppEnum
[out] IEnumMoniker 인터페이스를 받는 포인터의 주소. 메소드가 성공했을 경우는, 이 인터페이스 포인터를 사용해, 열거형으로부터 피르타모니카를 취득한다. 인터페이스는 다 사용했으면 해방하는 것.
dwFlags
[in] 예약이 끝난 상태. 0 이 아니면 안된다.
bExactMatch
[in] 완전하게 일치하는 것만을 열거할지 어떨지를 나타내는 불형의 값. 상세한 것에 대하여는, 「주의」를 참조할것.
dwMerit
[in] 최소 메리트값.
bInputNeeded
[in] 필터에입력 핀이 필요한가 어떤가를 나타내는 불형의 값. TRUE 의 경우, 필터에는 입력 핀이 적어도 1 개(살) 필요하다.
cInputTypes
[in] pInputTypes 로 지정하는 입력 미디어 타입의 수.
pInputTypes
[in] 메이저 타입 및 서브 타입을 지정하는 GUID 페어의 배열에의 포인터. 이것들에 일치하는 입력 핀을 열거한다. 배열의 사이즈는 2 * cInputTypes 가 된다. 배열은 NULL 의 경우가 있다. 배열의 개개의 멤버에는, 모든 타입에 일치하는 GUID_NULL 를 지정할 수 있다.
pMedIn
[in] 입력 핀의 미디어를 지정하는 REGPINMEDIUM 구조체에의 포인터. 필요가 없는 경우는, NULL 를 설정한다.
pPinCategoryIn
[in] 입력핀 카테고리를 지정하는 GUID 에의 포인터. 필요가 없는 경우는, NULL 를 설정한다.
bRender
[in] 필터가 그 입력을 렌더링 할 필요가 있을지 어떨지를 지정하는 불형의 값. TRUE 의 경우에는, 지정된 필터가 입력을 렌더링 할 필요가 있다.
bOutputNeeded
[in] 필터에출력 핀이 필요한가 어떤가를 지정하는 불형의 값. TRUE 의 경우, 필터에는 출력 핀이 적어도 1 개(살) 필요하다.
cOutputTypes
[in] pOutputTypes 로 지정하는 출력 미디어 타입의 수.
pOutputTypes
[in] 메이저 타입 및 서브 타입을 지정하는 GUID 페어의 배열에의 포인터. 이것들에 일치하는 출력 핀을 열거한다. 배열의 사이즈는 2 * cOutputTypes 가 된다. 배열은 NULL 의 경우가 있다. 배열의 개개의 멤버에는, 모든 타입에 일치하는 GUID_NULL 를 지정할 수 있다.
pMedOut
[in] 출력 핀의 미디어를 지정하는 REGPINMEDIUM 구조체에의 포인터. 필요가 없는 경우는, NULL 를 설정한다.
pPinCategoryOut
[in] 출력핀 카테고리를 지정하는 GUID 에의 포인터. 필요가 없는 경우는, NULL 를 설정한다.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공
E_FAIL | 실패
E_OUTOFMEMORY | 메모리 부족
E_POINTER | NULL 포인터 인수

주의

입력 핀이 주어진 일련의 미디어 타입과 일치하는 필터를 검색하려면 , 메이저 타입 GUID 와 서브 타입 GUID 의 페어를 순서에 늘어놓은 배열을 선언한다. pInputTypes 파라미터에 배열의 주소를 건네주어,cInputTypes 파라미터에 페어의 수 (즉 배열 사이즈의 반)를 설정한다.

GUID arrayInTypes[2];
arrayInTypes[0] = MEDIATYPE_Video;
arrayInTypes[1] = GUID_NULL;

DWORD cInTypes = 1;

출력 핀의 경우는,pOutputTypes 파라미터에 같은 배열을 건네주어,cOutputTypes 파라미터로 GUID 페어의 수를 지정한다.

bExactMatch 파라미터의 값이 TRUE 의 경우, 이 메소드는, 미디어 타입, 핀 카테고리, 및 핀 미디어로 지정된 값과 완전하게 일치하는 필터를 검색한다. 이 값이 FALSE 의 경우, 이러한 항목의 어느 쪽인가에 값 NULL 가 등록되어 있는 필터도, 일치하는 것이라고 보여진다 (레지스트리내의 값 NULL 는 와일드 카드가 책임을 다한다).

미디어 타입, 핀 카테고리, 또는 핀 미디어에 NULL 를 지정 하면, 모든 필터가 그 파라미터에 일치하는 것이라고 보여진다.

미디어 타입이 등록되지 않은 핀은, 그 미디어 타입에 일치하지 않는 것이라고 보여진다.

IFilterMapper2::RegisterFilter

IFilterMapper2 인터페이스

레지스트리에 필터 정보를 추가한다.

구문

HRESULT RegisterFilter(
    REFCLSID clsidFilter,
    LPCWSTR Name,
    IMoniker **ppMoniker,
    const CLSID *pclsidCategory,
    const OLECHAR *szInstance,
    const REGFILTER2 *prf2
);

파라미터

clsidFilter
[in] 필터의 클래스 식별자 (CLSID).
Name
[in] 필터의 내용을 나타내요 셋집 들이마셔 이름.
ppMoniker
[in, out] 이 필터의 데이터 출력처를 결정하는 디바이스 모니카에의 포인터의 주소. NULL 의 경우가 있다.
pclsidCategory
[in] 필터의필터 카테고리에의 포인터. NULL 라면, 디폴트 카테고리는 CLSID_ActiveMovieFilters 이다.
szInstance
[in] 데바이스모니카의 표시명을 구축하기 위해서 사용하는 인스턴스 데이터. 프렌들리명에서도, 필터의 CLSID 의 캐릭터 라인 표현이라도 좋다. NULL 의 경우는, 필터의 CLSID 가 사용된다.
prf2
[in] 필터 정보가 저장 된 REGFILTER2 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_BAD_KEY | 레지스트리 키를 취득할 수 없다.

주의

이 메소드는, 레지스트리내의 지정된 필터 카테고리에 대응하는 레지스트리 엔트리하에, 필터에 관한 정보를 추가한다. 필터를 생성 하는 인 프로세스 서버 (보통은 DLL)를 등록하는 것은 아니다. 서버를 등록하려면 ,AMovieDllRegisterServer2 함수를 호출하면 좋다.

ppMoniker 파라미터에는, 다음의 어느쪽이든을 사용한다.

  • 기존의 데바이스모니카에 대한 IMoniker 인터페이스 포인터의 주소
  • NULL IMoniker 인터페이스 포인터의 주소
  • NULL

WDM (Windows Driver Model) 디바이스 또는 플러그 앤 플레이 디바이스용의 필터를 등록하는 경우는, 기존의 데바이스모니카의 주소를 건네준다. 이렇게 하면(자), 이 모니카를 사용해 필터가 등록된다. 메소드로부터 돌아올 때,*ppMoniker 에는 NULL 가 설정된다.

그 이외의 경우는, 새로운 모니카가 생성 된다. ppMoniker 가 NULL 가 아닌 경우,*ppMoniker 에 새로운 모니카에의 포인터가 설정된다. 그 어플리케이션에서는, 이 모니카를 사용해 프로퍼티 가방에 사적인 값을 추가할 수 있다. 인터페이스의 해방을 잊지 않는 것.

모니카를 제공 또는 취득할 필요가 없는 경우는,ppMoniker 에 NULL 를 설정한다.

IFilterMapper2::UnregisterFilter

IFilterMapper2 인터페이스

레지스트리로부터 필터 정보를 삭제한다.

구문

HRESULT UnregisterFilter(
    const CLSID *pclsidCategory,
    const OLECHAR *szInstance,
    REFCLSID Filter
);

파라미터

pclsidCategory
[in] 필터를 삭제하는필터 카테고리에의 포인터.
szInstance
[in] 데바이스모니카의 표시명의 구축에 사용한 인스턴스 데이터. RegisterFilter 메소드에 건네준 값을 사용한다.
Filter
[in] 필터의 클래스 식별자 (CLSID).

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

필터가 등록되지 않은 경우, 메소드는 에러를 돌려준다.


IFullScreenVideo 인터페이스

IFullScreenVideo 인터페이스는,풀 스크린 렌더링 필터에 이행 된다. 구식의 그래픽 카드는, 320 x 240 의 비디오를 1024 x 768 에 신장할 때에 시간이 걸린다. 시스템에 이러한 그래픽 카드가 탑재되고 있는 경우, 필터 그래프 매니저는, 풀 스크린 렌더러를 사용해 풀 스크린 비디오를 렌더링 한다. 하드웨어가 가지는 이 제약을 해소하기 위해(때문에), 풀 스크린 렌더러에서는, 그래픽스 디스플레이 카드를 단순하게 320 x 240 모드로 전환한다. 비교적 새로운 비디오 카드의 경우에는, 표시를 고속으로 신장할 수 있으므로, 윈도우 모드에서도 풀 스크린 모드에서도비디오 렌더링 필터를 사용할 수 있다. 표시는, 어플리케이션이 IVideoWindow::put_FullScreenMode 를 호출하면 풀 스크린 모드에 바뀌어, 유저가 Esc 키를 누르면(자) 보통의 윈도우 재생하러 돌아온다.

접속되면(자), 풀 스크린 렌더러는 이용 가능한 디스플레이 모드를 로드한다. 이용 가능한 모드의 수는 IFullScreenVideo::CountModes 로 취득할 수 있다. 개개의 모드에 관한 정보는, 그 후 IFullScreenVideo::GetModeInfo 및 IFullScreenVideo::IsModeAvailable 를 호출해 취득한다. 어플리케이션으로부터 임의의 디스플레이 모드를 유효 및 무효로 하려면 ,IFullScreenVideo::SetEnabled 메소드를 호출한다. 현재의 값은 IFullScreenVideo::IsModeEnabled 를 호출해 조회한다. 어플리케이션으로부터 임의의 디스플레이 모드를 유효 또는 무효로 하려면 , (C/C++ 의 TRUE 값이나 FALSE 값은 아니고) OATRUE 또는 OAFALSE 를 지정해 IFullScreenVideo::SetEnabled 를 호출한다.

풀 스크린 렌더러는, foreground의 액티브 윈도우에서만 기능한다. 풀 스크린 모드중에, 유저가 다른 어플리케이션으로 전환하려고 하면, 비디오는 비표시가 된다. 풀 스크린 렌더러는, 실제로 비디오를 드로잉(Drawing) 하고 있는 윈도우를 최소화하는 것으로써, 이것을 실현한다 (다만 윈도우의 사용은 유저는 모른다). 윈도우를 최대화 하면, 비디오가 복원된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFullScreenVideo 메소드 | 설명
CountModes | 풀 스크린 렌더러 위에의 이용 가능한 모드수를 취득한다.
GetModeInfo | 특정의 모드에 관한 정보를 취득한다.
GetCurrentMode | 현재 유효한 비디오 모드를 취득한다.
IsModeAvailable | 특정의 비디오 모드가 이용 가능한가 어떤가를 판단한다.
IsModeEnabled | 특정의 비디오 모드가 유효한가 어떤가를 판단한다.
SetEnabled | 비디오 모드를 유효 및 무효로 한다.
GetClipFactor | 클립 손실 계수의 현재의 설정을 취득한다.
SetClipFactor | 없어지는 최대의 이미지 영역에 근거해 비디오 모드를 지정한다.
SetMessageDrain | 렌더러 앞의 윈도우 메세지를 받아들이는 윈도우를 지정한다.
GetMessageDrain | 렌더러 앞의 윈도우 메세지를 받아들이는 윈도우를 취득한다.
SetMonitor | 사용중의 모니터를 설정한다 (복수 모니터의 이행시에 사용).
GetMonitor | 사용중의 모니터를 취득한다.
HideOnDeactivate | 윈도우가 액티브하지 않을 때는 표시하지 않는다.
IsHideOnDeactivate | HideOnDeactivate 프로퍼티 상태를 취득한다.
SetCaption | 풀 스크린 윈도우에 관련짓는 캡션을 설정한다.
GetCaption | 풀 스크린 윈도우에 관련지을 수 있었던 캡션을 취득한다.
SetDefault | 풀 스크린 비디오 렌더러의 프로퍼티 모두에게 디폴트값을 설정한다.

IFullScreenVideo::CountModes

IFullScreenVideo 인터페이스

풀 스크린 렌더러 위에의 이용 가능한 모드수를 취득한다.

구문

HRESULT CountModes(
    long *pModes
);

파라미터

pModes
[out] 돌려주어진 모드수에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

DirectShow 의 풀 스크린 렌더러에서는, 8 개의 모드 (320 × 200 × 8/16 비트, 320 × 240 × 8/16, 640 × 400 × 8/16, 및 640 × 480 × 8/16)가 지원 된다. 해상도의 높은 모드보다, 낮은 모드를 우선적으로 사용하는 것. 어플리케이션으로부터 개개의 모드를 유효 및 무효로 하면(자), 이용 가능한 모드를 정확하게 지정할 수 있다. 선택한 모드에 관한 대범한 설정에는, 클립 손실 계수를 사용한다.

IFullScreenVideo::GetCaption

IFullScreenVideo 인터페이스

풀 스크린 윈도우에 관련지을 수 있었던 캡션을 취득한다.

구문

HRESULT GetCaption(
    BSTR *pstrCaption
);

파라미터

pstrCaption
[out] 취득된 캡션에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

Alt + Tab 키를 눌러 다른 윈도우로 전환하면(자), DirectShow 의 풀 스크린 렌더러를 비액티브하게 할 수 있다. 풀 스크린 렌더러는, 비액티브하게 하면 아이콘으로서 표시된다. 타이틀 캐릭터 라인은 이 메소드로 설정할 수 있다. 액티브하지 않을 때에 렌더러가 비표시가 되는 경우, 이 메소드는 성공하지만, 윈도우가 아이콘으로서 표시되지 않기 때문에, 설정에 의한 효과는 없다.

IFullScreenVideo::GetClipFactor

IFullScreenVideo 인터페이스

클립 손실 계수의 현재의 설정을 취득한다.

구문

HRESULT GetClipFactor(
    long *pClipFactor
);

파라미터

pClipFactor
[out] 없어져도 괜찮은 이미지의 최대량에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

클립 손실 계수의 설정의 상세한 것에 대하여는, 「IFullScreenVideo::SetClipFactor 」를 참조할것.

IFullScreenVideo::GetCurrentMode

IFullScreenVideo 인터페이스

현재 유효한 비디오 모드를 취득한다.

구문

HRESULT GetCurrentMode(
    long *pMode
);

파라미터

pMode
[out] 취득된 풀 스크린 비디오 모드에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

접속되면(자), 풀 스크린 비디오 렌더러는 비디오 재생에 사용하는 디스플레이 모드를 선택한다. 선택된 모드는, 이 메소드로 취득할 수 있다. 게다가 IFullScreenVideo::GetModeInfo 를 사용 하면, 그 모드의 상세를 취득할 수 있다.

DirectShow 의 풀 스크린 비디오 렌더러에 이용 가능한 모드의 일람에 대해서는, 「IFullScreenVideo::SetEnabled 」를 참조할것.

IFullScreenVideo::GetMessageDrain

IFullScreenVideo 인터페이스

렌더러 앞의 윈도우 메세지를 받아들이는 윈도우를 취득한다.

구문

HRESULT GetMessageDrain(
    HWND *hwnd
);

파라미터

hwnd
[out] 메세지 drain로서 지정되고 있는 윈도우의 윈도우 핸들에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

풀 스크린 비디오 렌더러는, 받은 마우스 메세지 및 키보드 메세지를, 모두 메세지 drain로서 지정되고 있는 윈도우에 보낸다. 이 때, 메세지의 파라미터는 변환하지 않는다. 건네받는 메세지의 일람은,IVideoWindow::put_MessageDrain 의 경우와 같다. 어플리케이션으로부터 이 메소드를 사용해, 풀 스크린 비디오용의 hot key 지원을 이행 할 수 있다. 예를 들어,Ctrl 키와 P 키의 편성을 감시해, 그것을 신호에 비디오를 포즈 하는 것 같은 처리가 생각된다.

IFullScreenVideo::GetModeInfo

IFullScreenVideo 인터페이스

특정의 모드에 관한 정보를 취득한다.

구문

HRESULT GetModeInfo(
    long Mode,
    long *pWidth,
    long *pHeight,
    long *pDepth
);

파라미터

Mode
[in] 정보를 취득하는 모드.
pWidth
[out] 모드의 이미지 표시의 폭에의 포인터 (픽셀 단위).
pHeight
[out] 모드의 이미지 표시의 높이에의 포인터 (픽셀 단위).
pDepth
[out] 픽셀 근처의 칼라 비트수에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 그 렌더러에 이용 가능한 소정의 모드의 높이, 폭, 및 색깊이를 돌려준다. 이용 가능한 디스플레이 모드의 수는,IFullScreenVideo::CountModes 로 취득할 수 있다.

DirectShow 의 풀 스크린 비디오 렌더러에 이용 가능한 모드의 일람에 대해서는, 「IFullScreenVideo::SetEnabled 」를 참조할것.

IFullScreenVideo::GetMonitor

IFullScreenVideo 인터페이스

사용중의 모니터 타입을 취득한다.

구문

HRESULT GetMonitor(
    long *Monitor
);

파라미터

Monitor
[out] 현재 사용중의 모니터에의 포인터.

반환값

NOERROR 를 돌려준다.

주의

DirectShow 의 풀 스크린 렌더러는, 항상 0 (프라이머리 모니터)을 돌려준다.

IFullScreenVideo::HideOnDeactivate

IFullScreenVideo 인터페이스

풀 스크린 윈도우가 비액티브한 때, 그 윈도우 아이콘을 비표시로 한다.

구문

HRESULT HideOnDeactivate(
    long Hide
);

파라미터

Hide
[in] 풀 스크린 윈도우가 비액티브한 때, 그 비디오 윈도우 아이콘을 비표시로 할지 어떨지를 지정하는 값. 비표시로 하려면 OATRUE, 표시하려면 OAFALSE 를 설정한다.

반환값

성공했을 경우는, NOERROR 를 돌려준다. Hide 가 무효인 경우는, E_INVALIDARG 를 돌려준다.

주의

DirectShow 의 풀 스크린 렌더러용의 디폴트 설정은 OATRUE 가 되어 있다.

풀 스크린 렌더러는, foreground의 액티브 윈도우에서만 기능한다. 풀 스크린 모드중에, 유저가 다른 어플리케이션으로 전환하려고 하면, 비디오가 비표시가 된다. 렌더러는, 실제로 비디오를 드로잉(Drawing) 하고 있는 윈도우를 최소화하는 것으로써, 이것을 실현한다 (다만 윈도우의 사용은 유저는 모른다). 윈도우를 최대화 하면, 비디오가 복원된다.

IFullScreenVideo::IsHideOnDeactivate

IFullScreenVideo 인터페이스

IFullScreenVideo::HideOnDeactivate 프로퍼티 상태를 취득한다.

구문

HRESULT IsHideOnDeactivate(void);

반환값

HideOnDeactivate 에 OATRUE 가 설정되어 있는 경우는, S_OK 를 돌려준다. OAFALSE 가 설정되어 있는 경우는, S_FALSE 를 돌려준다.

IFullScreenVideo::IsModeAvailable

IFullScreenVideo 인터페이스

특정의 비디오 모드가 이용 가능한가 어떤가를 판단한다.

구문

HRESULT IsModeAvailable(
    long Mode
);

파라미터

Mode
[in] 확인하는 풀 스크린 모드.

반환값

그 비디오 모드가 이용 가능한 경우는, S_OK 를 돌려준다. 그 이외의 경우는, S_FALSE 를 돌려준다.

주의

풀 스크린 렌더러로 지원 되는 디스플레이 모드는, 디스플레이 카드 위에의 실제로 이용 가능한 모드와는 다르다. 렌더러가 접속될 때까지는, 이 정보를 이용하기 위해서 필요한 리소스의 할당이 끝나지 않을 가능성이 있기 (위해)때문에, 어플리케이션에서는 렌더러가 접속되고 있을 때에만 이 메소드를 호출하는 것. 모드가 이용 가능해도, 반드시 그 모드가 비디오 재생에 사용된다고는 할 수 없다. 비디오 재생에 사용되는 모드에는, 필터 그래프의 필터와의 호환성도 필요하게 된다.

IFullScreenVideo::IsModeEnabled

IFullScreenVideo 인터페이스

특정의 모드가 유효한가 어떤가를 판단한다.

구문

HRESULT IsModeEnabled(
    long Mode
);

파라미터

Mode
[in] 확인하는 풀 스크린 모드.

반환값

그 비디오 모드가 유효한 경우는, S_OK 를 돌려준다. 그 이외의 경우는, S_FALSE 를 돌려준다.

주의

이 메소드를 사용해, 렌더러로 지원 되고 있는 특정의 디스플레이 모드를 유효 및 무효로 할 수 있다. 모드가 이용 가능해도, 반드시 그 모드가 비디오 재생에 사용된다고는 할 수 없다. 비디오 재생에 사용되는 모드에는, 필터 그래프의 필터와의 호환성도 필요하게 된다.

DirectShow 의 풀 스크린 비디오 렌더러에 이용 가능한 모드의 일람에 대해서는, 「IFullScreenVideo::SetEnabled 」를 참조할것.

참조

IFullScreenVideo::IsModeAvailable

IFullScreenVideo::SetCaption

IFullScreenVideo 인터페이스

풀 스크린 윈도우에 관련짓는 타이틀을 설정한다.

구문

HRESULT SetCaption(
    BSTR strCaption
);

파라미터

strCaption
[in] 캡션이 저장 된 캐릭터 라인.

반환값

HRESULT 값을 돌려준다.

IFullScreenVideo::SetClipFactor

IFullScreenVideo 인터페이스

없어지는 최대의 이미지 영역에 근거해 비디오 모드를 지정한다.

구문

HRESULT SetClipFactor(
    long ClipFactor
);

파라미터

ClipFactor
[in] 없어져도 괜찮은 이미지의 최대량.

반환값

HRESULT 값을 돌려준다.

주의

클립 손실 계수는, 풀 스크린 모드를 유효하게하기 위한 , 어플리케이션으로부터 사용하기 쉽게 범용성이 높은 수단이다. 이 메소드는, 사용하는 디스플레이 모드를 결정할 때, 없어져도 괜찮은 비디오의 양을 정의한다. 예를 들어, 디코더가 비디오를 압축할 수 없는 경우에, MPEG 파일 (예를 들어 352 × 288 픽셀)을, 디스플레이 모드 320 × 200 으로 재생 하면, 이미지의 약 25% 가 없어진다. 클립 손실 계수는, 허용 범위의 상한을 지정한다. 전형적인 QCIF 사이즈의 MPEG 비디오 (352 × 288 픽셀)를, 디스플레이 모드 320 × 200 으로 재생하기 위해(때문에), 디폴트값은 25% 가 되어 있다.

IFullScreenVideo::SetDefault

IFullScreenVideo 인터페이스

풀 스크린 비디오 렌더러의 디폴트 설정을 설정한다.

구문

HRESULT SetDefault(void);

반환값

HRESULT 값을 돌려준다.

주의

이 인터페이스로 설정하는 프로퍼티는, 현재의 렌더러 인스턴스에게만 적용된다. 다만, 이 인터페이스 메소드를 호출해, 그 프로퍼티를 공통의 디폴트값으로 할 수 있다.

IFullScreenVideo::SetEnabled

IFullScreenVideo 인터페이스

비디오 모드를 유효 및 무효로 한다.

구문

HRESULT SetEnabled(
    long Mode,
    long bEnabled
);

파라미터

Mode
[in] 유효 또는 무효로 하는 모드 (아래의 일람을 참조).
bEnabled
[out] 다음의 몇개의 값을 설정한다.
OATRUE | 모드를 유효하게 한다.
OAFALSE | 모드를 무효로 한다.

반환값

HRESULT 값을 돌려준다.

주의

이용 가능한 DirectShow 의 모드는 이하와 같이 정의된다. 다만, 모드의 순서는 변경되는 일이 있으므로,IFullScreenVideo::CountModes 및 IFullScreenVideo::GetModeInfo 의 인터페이스 메소드를 사용해 모드를 열거하는 것.
모드 | 폭 | 높이 | RGB 깊이 (비트 단위)
0 | 320 | 200 | 16
1 | 320 | 200 | 8
2 | 320 | 240 | 16
3 | 320 | 240 | 8
4 | 640 | 400 | 16
5 | 640 | 400 | 8
6 | 640 | 480 | 16
7 | 640 | 480 | 8
8 | 800 | 600 | 16
9 | 800 | 600 | 8
10 | 1024 | 768 | 16
11 | 1024 | 768 | 8
12 | 1152 | 864 | 16
13 | 1152 | 864 | 8
14 | 1280 | 1024 | 16
15 | 1280 | 1024 | 8

IFullScreenVideo::SetMessageDrain

IFullScreenVideo 인터페이스

렌더러 앞의 윈도우 메세지를 받아들이는 윈도우를 지정한다.

구문

HRESULT SetMessageDrain(
    HWND hwnd
);

파라미터

hwnd
[in] 메세지 drain 윈도우의 윈도우 핸들.

반환값

HRESULT 값을 돌려준다.

주의

풀 스크린 비디오 렌더러는, 받은 마우스 메세지 및 키보드 메세지를, 모두 메세지 drain로서 지정되고 있는 윈도우에 보낸다. 이 때, 메세지의 파라미터는 변환하지 않는다. 건네받는 메세지의 일람은,IVideoWindow::put_MessageDrain 의 경우와 같다. 어플리케이션에서는, 이 메소드를 사용해, 풀 스크린 비디오용의 hot key 지원을 이행 할 수 있다. 예를 들어,Ctrl 키와 P 키의 편성을 감시해, 그것을 신호에 비디오를 포즈 하는 것 같은 처리가 생각된다.

IFullScreenVideo::SetMonitor

IFullScreenVideo 인터페이스

사용중의 모니터 타입을 설정한다.

구문

HRESULT SetMonitor(
    long Monitor
);

파라미터

Monitor
[in] 현재 사용하고 있는 모니터.

반환값

HRESULT 값을 돌려준다.

주의

프라이머리 디스플레이 (0) 이외를 설정 하면, 이 메소드는 에러를 돌려준다. DirectShow 의 장래의 버젼에서는, 렌더러가 풀 스크린 비디오를 재생하는 모니터를, 어플리케이션으로 선택할 수 있게 될 가능성이 있다.


IGraphBuilder 인터페이스

이 인터페이스는, 어플리케이션으로부터 필터 그래프를 구축하는 메소드를 제공한다. 필터 그래프 매니저가 이 인터페이스를 이행 한다.

IGraphBuilder 는 IFilterGraph 인터페이스를 계승한다. IFilterGraph 가 제공하는 것은, 그래프에의 필터의 추가, 2 개의 핀의 접속등의 기본적인 조작이다. IGraphBuilder 는, 이것들에 가세해 부분적인 정보로부터 그래프를 구축하는 메소드를 제공한다. 예를 들어,RenderFile 메소드는, 지정된 파일명에 대응하는 파일 재생용의 그래프를 구축한다. 또,Render 메소드는, 출력 핀에 새로운 필터를 접속해, 그 핀으로부터의 데이터를 렌더링 한다.

이러한 메소드를 사용 하면, 그 그래프의 필터와 핀 접속을, 어플리케이션으로부터 개별적으로 지정하는 수고를 생략할 수가 있다. 어플리케이션 대신에, 필터 그래프 매니저가, 유저의 시스템에 등록되어 있는 필터로부터 선택한 필터를, 그래프에 도입해 접속한다. 필터 그래프 매니저는, 내부적으로필터 맵퍼를 사용해 레지스트리내의 필터를 검색한다. 상세한 것에 대하여는, 「IFilterMapper2 」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFilterGraph 메소드 | 설명
AddFilter | 그래프에 필터를 추가해, 그 필터에 이름을 붙인다.
RemoveFilter | 그래프로부터 필터를 삭제한다.
EnumFilters | 그래프의 필터 모두에 대해서 열거자를 제공한다.
FindFilterByName | 특정의 이름으로 추가된 필터를 검색한다.
ConnectDirect | 2 개의 핀을 직접 접속한다 (필터를 통하지 않는다).
Reconnect | 기존의 핀 접속을 절단 해, 같은 핀에 재접속한다.
Disconnect | 특정의 핀을 절단 한다.
SetDefaultSyncSource | 디폴트의 동기 기준 (클락)을 설정한다.
IGraphBuilder 메소드 | 설명
Connect | 2 개의 핀을 접속한다. 직접 접속할 수 없는 경우는 변형을 개입시켜 접속한다.
Render | 특정의출력 핀에 필터 체인을 추가해 렌더링 한다.
RenderFile | 지정된 파일을 렌더링 하는 필터 그래프를 구축한다.
AddSourceFilter | 특정의 파일에 대응하는 필터 그래프에소스 필터를 추가한다.
SetLogFile | 로그 파일을 설정한다. 이 파일에는 조작을 실행하려고 했을 때 행해진 각 액션이 출력된다.
Abort | 현재의 태스크로부터 생기는 한 빨리 돌아오도록(듯이) 그래프 빌더에 요구한다.
ShouldOperationContinue | 현재의 조작이 계속해야할 것인가 제발을 조회한다.

IGraphBuilder::Abort

IGraphBuilder 인터페이스

현재의 태스크로부터 생기는 한 빨리 돌아오도록(듯이) 그래프 빌더에 요구한다.

현재의 태스크가 완료할지 어떨지는 모른다. 그래프 빌더를 현재의 태스크로부터 가장 빨리 되돌리려면 , 그래프 빌더에 그것을 완료시키는 것이 제일이다.

구문

HRESULT Abort(void);

반환값

S_OK 를 돌려준다.

IGraphBuilder::AddSourceFilter

IGraphBuilder 인터페이스

특정의 파일에 대응하는 필터 그래프에 소스 필터를 추가한다. IGraphBuilder::RenderFile 메소드는 이 메소드를 호출해 소스 필터를 검색한다.

구문

HRESULT AddSourceFilter(
    LPCWSTR lpwstrFileName,
    LPCWSTR lpwstrFilterName,
    IBaseFilter **ppFilter
);

파라미터

lpwstrFileName
[in] 파일에의 포인터.
lpwstrFilterName
[in] 추가하는 소스 필터에 붙이는 이름에의 포인터.
ppFilter
[out] 추가된 필터의 IBaseFilter 인터페이스에의 포인터의 주소.

반환값

HRESULT 를 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 성공.
E_NOINTERFACE | 소스 필터로 IFileSourceFilter 인터페이스가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
VFW_E_CANNOT_LOAD_SOURCE_FILTER | 이 파일의 소스 필터를 로드할 수 없다.
VFW_E_NOT_FOUND | 오브젝트 또는 이름이 발견되지 않았다.
VFW_E_UNKNOWN_FILE_TYPE | 이 파일의 미디어 타입이 인식되지 않는다.

주의

이 메소드를 사용 하면, 그래프의 남은 부분의 구축에 대해보다 상세하게 제어해, 정확하게 파악할 수가 있다. 예를 들어,IFilterGraph::AddFilter 메소드를 사용해 기호의렌더러를 추가한 데다가,IGraphBuilder::Connect 메소드를 사용해 2 개의 필터를 접속할 수가 있다. 그 소스 필터가 공개하는 IBaseFilter 인터페이스는,ppFilter 파라미터에 돌려주어져 참조는 IUnknown::AddRef 메소드로 이미 추가되고 있다. lpwstrFilterName 파라미터를 사용 하면, 이 필터 그래프내에서는 이 이름으로 필터를 식별할 수 있다. 상세한 것에 대하여는, 「FindFilterByName 」를 참조할것.

필터 그래프의 남은 부분을 구축하기 위해서, 추가하는 소스 필터의 출력 핀을 찾는 것은, 어플리케이션측의 책임이다. 거기에는, 출력 핀의 IGraphBuilder::Render 를 호출해, 필터 그래프 전체를 자동적으로 구축하는지, 또는 필터를 개별적으로 추가 및 접속한다. 필터를 개별적으로 추가하는 경우, 비동기 파일 리더 소스 필터 및 URL 모니카 소스 필터에서는 데이터가 해석되지 않기 때문에, 이러한 소스 필터의 출력 핀은, MPEG 스플리터 필터등의퍼서 필터에게만 접속할 수 있다.

IGraphBuilder::RenderFile 메소드는 같은 소스 필터를 추가한다.

IGraphBuilder::Connect

IGraphBuilder 인터페이스

2 개의 핀을 접속한다 (필요에 따라서 중간 필터를 사용).

구문

HRESULT Connect(
    IPin *ppinOut,
    IPin *ppinIn
);

파라미터

ppinOut
[in] 출력 핀에의 포인터.
ppinIn
[in] 입력 핀에의 포인터.

반환값

HRESULT 를 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 성공.
VFW_S_PARTIAL_RENDER | 이 무비에 지원 되지 않는 포맷의 스트림이 포함되어 있다.
E_ABORT | 조작이 중지되었다.
E_POINTER | NULL 포인터 인수.
VFW_E_CANNOT_CONNECT | 접속을 확립하는 중간 필터의 편성이 발견되지 않았다.
VFW_E_NOT_IN_GRAPH | 필터 그래프에 존재하지 않는 오브젝트에 요구된 함수를 실행할 수 없다.

주의

이 메소드는, 2 개의 핀을 직접 접속하는지, 또는 필요에 따라서변환 필터를 사용해 간접적으로 접속한다. 실패했을 경우, 메소드는 파일 그래프를 변경하지 않는다. 필터 그래프 매니저는, 우선 핀을 직접 접속하려고 한다. 이것에 실패 하면, 이미 필터 그래프에 속하고 있는 필터가 제공하는 이용 가능한 변환의 어느쪽이든을 사용하려고 한다 (이 때 열거의 순서는 임의이다). 이것에 실패 하면, 게다가 변환을 제공하는 필터를 레지스트리로부터 검색하려고 한다. 이 때는메리트순서에 시험한다.

접속 처리에서는, 중간 필터의 핀명이 ~ (치르다)로 시작되는 경우, 필터 그래프 매니저는 그 필터의 핀을 무시한다. 상세한 것에 대하여는, 「PIN_INFO 」를 참조할것.

IGraphBuilder::Render

IGraphBuilder 인터페이스

이 출력 핀으로부터의 데이터를 렌더링 하는 필터 그래프를 구축한다.

구문

HRESULT Render(
    IPin *ppinOut
);

파라미터

ppinOut
[in] 출력 핀에의 포인터.

반환값

HRESULT 를 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 성공.
VFW_S_AUDIO_NOT_RENDERED | 오디오 스트림을 재생할 수 없다. 적절한 렌더러가 발견되지 않았다.
VFW_S_DUPLICATE_NAME | 이름이 중복 하고 있는 필터의 추가가, 변경 후의 이름으로 성공했다.
VFW_S_PARTIAL_RENDER | 이 무비에 지원 되지 않는 포맷의 스트림이 포함되어 있다.
VFW_S_VIDEO_NOT_RENDERED | 비디오 스트림을 재생할 수 없다. 적절한 렌더러가 발견되지 않았다.
E_ABORT | 조작이 중지되었다.
E_POINTER | NULL 포인터 인수.
VFW_E_CANNOT_CONNECT | 접속을 확립하는 중간 필터의 편성이 발견되지 않았다.
VFW_E_CANNOT_RENDER | 스트림을 렌더링 하는 필터의 편성이 발견되지 않았다.
VFW_E_NO_ACCEPTABLE_TYPES | 이러한 핀에 공통의 미디어 타입이 없다.
VFW_E_NOT_IN_GRAPH | 필터 그래프에 존재하지 않는 오브젝트에 요구된 함수를 실행할 수 없다.

주의

이 메소드는, 렌더링 하는 필터에 이 출력 핀을, 직접 접속하는지, 또는 필요에 따라서 변환 필터를 중간 필터로서 사용해 간접적으로 접속한다. 필터는 IGraphBuilder::Connect 메소드의 경우와 같은 순서로 시험 받는다.

접속 처리에서는, 중간 필터의 핀명이 ~ (치르다)로 시작되는 경우, 필터 그래프 매니저는 그 필터의 핀을 무시한다. 상세한 것에 대하여는, 「PIN_INFO 」를 참조할것.

IGraphBuilder::RenderFile

IGraphBuilder 인터페이스

지정된 파일을 렌더링 하는 필터 그래프를 구축한다.

구문

HRESULT RenderFile(
    LPCWSTR lpwstrFile,
    LPCWSTR lpwstrPlayList
);

파라미터

lpwstrFile
[in] 렌더링 대상 데이터가 저장 된 파일의 이름, 또는 캡춰 디바이스의 모니카에의 포인터.
lpwstrPlayList
[in] 예약이 끝난 상태. NULL 가 아니면 안된다.

반환값

HRESULT 를 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 성공.
VFW_S_AUDIO_NOT_RENDERED | 오디오 스트림을 재생할 수 없다. 적절한 렌더러가 발견되지 않았다.
VFW_S_DUPLICATE_NAME | 이름이 중복 하고 있는 필터의 추가가, 변경 후의 이름으로 성공했다.
VFW_S_PARTIAL_RENDER | 이 무비에 지원 되지 않는 포맷의 스트림이 포함되어 있다.
VFW_S_VIDEO_NOT_RENDERED | 비디오 스트림을 재생할 수 없다. 적절한 렌더러가 발견되지 않았다.
E_ABORT | 조작이 중지되었다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
VFW_E_CANNOT_CONNECT | 접속을 확립하는 중간 필터의 편성이 발견되지 않았다.
VFW_E_CANNOT_LOAD_SOURCE_FILTER | 이 파일의 소스 필터를 로드할 수 없다.
VFW_E_CANNOT_RENDER | 스트림을 렌더링 하는 필터의 편성이 발견되지 않았다.
VFW_E_INVALID_FILE_FORMAT | 파일 포맷이 무효.
VFW_E_NOT_FOUND | 오브젝트 또는 이름이 발견되지 않았다.
VFW_E_NOT_IN_GRAPH | 필터 그래프에 존재하지 않는 오브젝트에 요구된 함수를 실행할 수 없다.
VFW_E_UNKNOWN_FILE_TYPE | 이 파일의 미디어 타입이 인식되지 않는다.
VFW_E_UNSUPPORTED_STREAM | 파일을 재생할 수 없다. 포맷이 지원되어 있지 않다.

주의

이 메소드는, 지정된 파일을 처리할 수 있는 소스 필터를 추가한다. 다음에, 필요에 따라서 중간 필터를 추가해, 그 소스 필터의 출력 핀을 렌더링 한다. 필터는 IGraphBuilder::Connect 메소드의 경우와 같은 순서로 시험 받는다.

접속 처리에서는, 중간 필터의 핀명이 ~ (치르다)로 시작되는 경우, 필터 그래프 매니저는 그 필터의 핀을 무시한다. 상세한 것에 대하여는, 「PIN_INFO 」를 참조할것.

지정한 파일의 미디어 타입과 압축 스킴을 확인하기 위해서, 필터 그래프 매니저는 파일의 최초의 수바이트를 읽어들여,커스텀 파일 타입의 등록에 기술되고 있는 파일 서명을 찾는다.

lpwstrFile 파라미터는 GraphEdit . grf 파일을 지정할 수가 있다. 필터 그래프 매니저는 그래프를 그 파일로부터 로드한다.

lpwstrFile 파라미터는 USB 카메라나 DV 캠 코다와 같은 캡춰 디바이스의 데바이스모니카를 지정할 수도 있다. 필터 그래프 매니저는 단순한 프리뷰 그래프를 생성 한다.

IGraphBuilder::SetLogFile

IGraphBuilder 인터페이스

로그 파일을 설정한다. 이 파일에는 조작을 실행하려고 했을 때 행해진 각 액션이 출력된다.

구문

HRESULT SetLogFile(
    HANDLE hFile
);

파라미터

hFile
로그 파일의 핸들.

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 디버그에 사용해, 필터 그래프의 자동 구축에 실패했을 때, 그 원인을 판단하는 것을 목적으로 하고 있다.

hFile 파라미터는, 연 파일 핸들이 아니면 안된다. 파일을 열어, 로그 출력이 끝나고 나서 파일을 닫는 것은, 어플리케이션측의 책임이다. 파일 핸들을 닫기 전에, 파일 핸들 NULL 로 SetLogFile 를 호출한다. 이렇게 하면(자), 이미 닫은 파일 핸들을 컴퍼넌트가 사용하지 않게 방지할 수 있다.

IGraphBuilder::ShouldOperationContinue

IGraphBuilder 인터페이스

현재의 조작이 계속해야할 것인가 제발을 조회한다. 그래프로부터의 요구에 근거해 어떠한 조작을 실행하고 있는 필터에서는, 이 메소드를 호출해, 그 조작이 계속해야할 것인가 제발을 판단할 수 있다. 보통, 어플리케이션으로부터 이 메소드를 호출할 것은 없다.

구문

HRESULT ShouldOperationContinue(void);

반환값

HRESULT 를 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 현재의 조작은 계속해야 한다.
S_FALSE | 현재의 조작이 계속해서는 안 된다.
E_UNEXPECTED | 예기치 못한 에러.


IGraphConfig 인터페이스

필터 그래프 매니저는, 그래프를 동적으로 구축하는 IGraphConfig 를 공개한다. 이 인터페이스를 사용 하면, 어플리케이션 및 필터로부터, 스트림으로부터의 데이터를 잃지 않고 , 실행 상태에 있는 필터 그래프를 복구성 할 수 있다.

그래프를 동적으로 재구축 하는 가장 직접적인 방법은,Reconnect 메소드를 호출하는 방법이다. 그래프를 동적으로 재구축하기 위한 세세한 처리의 대부분은, 메소드측에서 실행한다. 독자적인 기법을 사용할 필요가 있는 경우를 위해서(때문에),IGraphConfig 는 Reconfigure 메소드도 제공한다. 이 메소드는, 필터 그래프를 잠근 데다가, 어플리케이션측의 콜백 함수를 호출해, 그 함수가 그래프를 복구성 한다. 이 메소드에서는, 처리의 대부분을 어플리케이션측에서 실행한다. 상세한 것에 대하여는, 「동적 그래프 생성」을 참조할것.

필터를 추가 및 삭제하는 처리를 최적화하기 위해(때문에), 필터 그래프는 필터의 캐쉬를 보관 유지한다. Reconnect 메소드의 호출에서는, 그래프로부터 삭제되는 필터를 캐쉬에 추가하도록(듯이) 지정할 수 있다. 또, 필요하게 될 것 같은 필터가 있는 경우는,AddFilterToCache 를 호출해 그 필터를 캐쉬에 직접 추가할 수도 있다. IGraphBuilder::Render 메소드,IGraphBuilder::RenderFile 메소드, 및 IGraphBuilder::Connect 메소드는, 캐쉬내의 필터를 우선적으로 사용한다. 또,Reconnect 메소드에서는, 재접속에 캐쉬내의 필터만을 사용하도록(듯이) 지정할 수도 있다. 캐쉬에 보관 유지되고 있는 필터는, 실제로는 그래프의 일부에서는 없기 때문에 주의 해야 한다. 캐쉬내의 필터는, 핀에는 접속되지 않는 상태로 정지하고 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IGraphConfig 메소드 | 설명
Reconnect | 2 개의 핀의 사이의 동적인 재접속을 실행한다.
Reconfigure | 필터 그래프를 잠그어, 어플리케이션 또는 필터의 콜백 함수를 호출해, 동적인 복구성을 실행한다.
AddFilterToCache | 필터 캐쉬에 필터를 추가한다.
RemoveFilterFromCache | 필터 캐쉬로부터 필터를 삭제한다.
EnumCacheFilter | 필터 캐쉬내의 필터를 열거한다.
GetStartTime | 필터 그래프가 마지막에 실행 상태에 바뀌었을 때에 사용된 기준 타임을 취득한다.
PushThroughData | 지정된 핀에 필터 그래프를 통해서 데이터를 인도한다.
SetFilterFlags | 필터의 구성 정보를 설정한다.
GetFilterFlags | 필터의 구성 정보를 취득한다.
RemoveFilterEx | 필터 그래프로부터 필터를 삭제한다.

IGraphConfig::AddFilterToCache

IGraphConfig 인터페이스

필터 캐쉬에 필터를 추가한다.

구문

HRESULT AddFilterToCache(
    IBaseFilter *pFilter
);

파라미터

pFilter
[in] 필터의 IBaseFilter 인터페이스에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
S_FALSE | 필터는 이미 캐쉬에 들어가 있다.
S_OK | 필터가 캐쉬에 추가되었다.

주의

이 메소드를 호출하기 전에, 필터의 핀을 모두 절단 해야 한다. 절단 하지 않았던 경우, 이 메소드는 실패한다. 필터가 필터 그래프에 포함되어 있는 경우, 그 필터는 삭제된다. 또, 필터가 정지상태태에 없는 경우, 그 필터는 정지상태태로 전환할 수 있다.

IGraphConfig::EnumCacheFilter

IGraphConfig 인터페이스

필터 캐쉬내의 필터를 열거한다.

구문

HRESULT EnumCacheFilter(
    IEnumFilters **pEnum
);

파라미터

pEnum
[out] 필터 열거자의 IEnumFilters 인터페이스에의 포인터의 주소.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

E_OUTOFMEMORY | 필요한 메모리의 할당해에 실패했다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

IGraphConfig::GetFilterFlags

IGraphConfig 인터페이스

필터의 구성 정보를 취득한다.

구문

HRESULT GetFilterFlags(
    IBaseFilter *pFilter,
    DWORD *pdwFlags
);

파라미터

pFilter
[in] 필터 그래프의 필터에의 포인터.
pdwFlags
[out] 현재의 구성 플래그를 받는 DWORD 형 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

E_POINTER | Null 포인터 인수.
S_OK | 성공.
VFW_E_NOT_IN_GRAPH | 필터가 그래프에 포함되지 않았다.

참조

SetFilterFlags

IGraphConfig::GetStartTime

IGraphConfig 인터페이스

필터 그래프가 마지막에 실행 상태에 바뀌었을 때에 사용된 기준 타임을 취득한다.

구문

HRESULT GetStartTime(
    REFERENCE_TIME *prtStart
);

파라미터

prtStart
[out] 시작 타임을 받는 변수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
VFW_E_WRONG_STATE | 필터 그래프가 실행 상태에 없다.

주의

필터 그래프가 현재 실행 상태에 없으면 이 메소드는 실패한다.

IGraphConfig::PushThroughData

IGraphConfig 인터페이스

지정된 핀에 필터 그래프를 통해서 데이터를 인도한다.

구문

HRESULT PushThroughData(
    IPin *pOutputPin,
    IPinConnection *pConnection,
    HANDLE hEventAbort
);

파라미터

pOutputPin
[in] 필터 그래프의 출력 핀에의 포인터.
pConnection
[in] 필터 그래프의 입력 핀에의 포인터, 또는 NULL.
hEventAbort
[in] 이벤트의 핸들. 필터의 데이터 처리 thread의 어느쪽이든으로부터 이 메소드를 호출하는 경우는, 이 파라미터에, 그 필터가 정지상태태에 바뀌었을 때에 통지제가 되는 이벤트의 핸들을 지정해야 한다. 그 이외의 경우, 이 파라미터는 NULL 로 상관없다. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 다음의 몇개의 에러 코드인가, 또는 일람에 나타나지 않은 그 외의 값을 돌려준다.

E_OUTOFMEMORY | 필요한 메모리의 할당해에 실패했다.
VFW_E_NOT_FOUND | 후보가 되는 입력 핀이 발견되지 않는다.
VFW_E_STATE_CHANGED | 조작중에 필터 상태가 변화했다.

주의

이 메소드는, 특정의 출력 핀으로부터 특정의 입력 핀에, 대기중의 데이터를 인도한다. 또, 입력 핀을 지정하지 않으면 필터 그래프로부터 최적인 입력 핀을 검색할 수 있다. 데이터의 인도를 실시하고 있는 thread로부터는, 이 메소드를 호출하지 않는 것.

필터의 데이터 처리 thread의 어느쪽이든으로부터 이 메소드를 호출하면, 데드 록에 빠지는 위험성이 있다. 이 메소드가 필터 그래프를 잠그기 (위해)때문에,IMediaFilter::Stop 의 호출을 받았을 때, 필터를 정지할 수 없을 가능성이 있다. 이 상황을 피하기 (위해)때문에, 이 메소드는 필터가 제공하는 이벤트 오브젝트의 핸들을 이용한다. 필터는, 그 Stop 메소드의 호출을 받으면(자), 이벤트를 통지해야 한다.

IGraphConfig::Reconfigure

IGraphConfig 인터페이스

필터 그래프를 잠그어, 어플리케이션 또는 필터의 콜백 함수를 호출해, 동적인 복구성을 실행한다.

구문

HRESULT Reconfigure(
    IGraphConfigCallback *pCallback,
    PVOID pvContext,
    DWORD dwFlags,
    HANDLE hAbortEvent
);

파라미터

pCallback
[in] 어플리케이션 또는 필터의 IGraphConfigCallback 콜백 인터페이스에의 포인터.
pvContext
[in] 콜백 루틴에 건네주는 PVOID 형 변수에의 포인터.
dwFlags
[in] 콜백 루틴에 건네주는 어플리케이션으로 정의한 플래그.
hAbortEvent
[in] 이벤트의 핸들. 필터의 데이터 처리 thread의 어느쪽이든으로부터 이 메소드를 호출하는 경우는, 이 파라미터에, 필터가 정지상태태에 바뀌었을 때에 통지제가 되는 이벤트의 핸들을 지정해야 한다. 그 이외의 경우, 이 파라미터는 NULL 로 상관없다. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러 코드를 돌려준다. 필터 그래프를 잠글 수 없었던 경우에는, 콜백 루틴이 돌려주는 HRESULT 에 관계없이, 에러 코드는 VFW_E_WRONG_STATE 가 된다. 또, 필터를 실행 상태로 전환할 수 없었던 것을 나타내는 에러 코드도 있다.

주의

이 메소드는, 어플리케이션 또는 필터로 특수한 동적 그래프 구축을 이행 하기 위해서 제공된다. 다만, 보통은 IGraphConfig::Reconnect 메소드로 목적을 달성할 수 있다. 또, 이행의 세세한 처리의 대부분이 메소드측에서 실행된다고 하는 점에서도, IGraphConfig::Reconnect 메소드를 우선적으로 사용하는 것.

이 메소드를 호출하기 전에, 필요에 따라서 스트림을 블록 해, 그래프를 통해서 데이터를 인도하는 것 (상세한 것에 대하여는, 「IPinFlowControl::Block 」 및 「IGraphConfig::PushThroughData 」를 참조할것). 콜백 메소드가 성공했을 경우,IGraphConfig::Reconfigure 는 필터를 모두 실행 상태로 전환하려고 한다 (블록 되고 있는 데이터의 흐름을, 호출원으로 해제해야 한다). 그 이외의 경우는, 콜백 메소드가 돌려준 에러 코드를 돌려준다.

필터의 데이터 처리 thread의 어느쪽이든으로부터 이 메소드를 호출하면, 데드 록에 빠지는 위험성이 있다. 이 메소드가 필터 그래프를 잠그기 (위해)때문에,IMediaFilter::Stop 의 호출을 받았을 때, 필터를 정지할 수 없을 가능성이 있다. 이 상황을 피하기 (위해)때문에, 이 메소드는 필터가 제공하는 이벤트 오브젝트의 핸들을 이용한다. 필터는, 그 Stop 메소드의 호출을 받으면(자), 이벤트를 통지해야 한다.

IGraphConfig::Reconnect

IGraphConfig 인터페이스

2 개의 핀의 사이의 동적인 재접속을 실행한다.

구문

HRESULT Reconnect(
    IPin *pOutputPin,
    IPin *pInputPin,
    const AM_MEDIA_TYPE *pmtFirstConnection,
    IBaseFilter *pUsingFilter,
    HANDLE hAbortEvent,
    DWORD dwFlags
);

파라미터

pOutputPin
[in] 출력 핀에의 포인터. NULL 의 경우가 있다. 그 경우,pInputPin 가 NULL 여서는 안 된다.
pInputPin
[in] 입력 핀에의 포인터. NULL 의 경우가 있다. 그 경우,pOutputPin 가 NULL 여서는 안 된다.
pmtFirstConnection
[in] 재접속의 최초의 핀 접속에 사용하는 미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터. 이 파라미터가 NULL 의 경우, 최초의 접속의 미디어 타입은 한정되지 않는다.
pUsingFilter
[in] 재접속에 사용하는 필터에의 포인터 (생략 가능). 필터는 이미 그래프에 포함되지 않으면 안 된다. NULL 의 경우가 있다.
hAbortEvent
[in] 이벤트의 핸들. 필터의 데이터 처리 thread의 어느쪽이든으로부터 이 메소드를 호출하는 경우는, 이 파라미터에, 필터가 정지상태태에 바뀌었을 때에 통지제가 되는 이벤트의 핸들을 지정해야 한다. 그 이외의 경우, 이 파라미터는 NULL 로 상관없다. 상세한 것에 대하여는, 「주의」를 참조할것.
dwFlags
[in] 재접속의 실행 방법을 지정하는 AM_GRAPH_CONFIG_RECONNECT_FLAGS 열거형의 플래그의 편성.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 다음의 몇개의 에러 코드인가, 또는 일람에 나타나지 않은 그 외의 값을 돌려준다.

E_INVALIDARG | 무효인 인수. 예를 들어,pInputPin 와 pOutputPin 의 양쪽 모두에 NULL 가 지정되었을 경우 등.
E_NOINTERFACE | 입력 핀으로 IPinConnection 가 지원되어 있지 않다.
VFW_E_CANNOT_CONNECT | 필터를 접속할 수 없다.
VFW_E_STATE_CHANGED | 필터 상태가 변화했다. 조작을 완료할 수 없다.

주의

출력 핀을 1 개만 지정 하면, 메소드는 이제(벌써) 한편의 핀을 검색한다. 다만 디폴트에서는,IFilterGraph::AddFilter 메소드로 그래프에 추가한 필터가 발견되면(자) 검색이 실패한다. 이 동작을 오버라이드(override) 하려면 ,IGraphConfig::SetFilterFlags 를 호출해 필터의 AM_FILTER_FLAGS_REMOVABLE 플래그를 설정한다.

재접속은 이하의 스텝에서 실행되어 그 대부분은 이 메소드내에서 처리된다.

  1. 우선, 메소드를 호출하기 전에, 복구성 하려고 하고 있는 패스에 따른 데이터의 흐름을 확실히 블록 한다. 호출원이 어플리케이션의 경우, 이것에는 IPinFlowControl::Block 메소드를 호출하지 않으면 안 된다. 어플리케이션은 아니고 필터로부터 호출하는 경우, 데이터의 흐름을 필터측에서 내부적으로 제어할 수 있을 가능성이 있다.
  2. 지정하는 출력 핀과 입력 핀에 의해, 재접속의 시점과 종점이 정의된다. 입력 핀은 IPinConnection 인터페이스를 지원 해야 한다. 이러한 핀의 어느쪽이든을 지정하지 않는 (NULL 파라미터를 건네준다)와 메소드는, 필터 그래프로부터 재접속의 후보가 되는 핀을 검색한다 (입력 핀은 출력 핀으로부터 다운 스트림에, 출력 핀은 입력 핀으로부터 업 스트림에 검색한다).
  3. 메소드가, 필터 그래프를 통해서 대기중의 데이터를 인도한다 (내부적으로 PushThroughData 을 호출한다).
  4. 그래프에 삽입하는 필터를 지정했을 경우, 그 필터의 입력 핀에 최초의 출력 핀이 접속되어 그 필터의 출력 핀이 마지막 입력 핀에 접속된다. 필터를 지정하지 않았던 경우에는, 출력 핀이 입력 핀에 직접 접속된다. 어느 경우도, 접속의 확립에 필요한 변환 필터가 있으면 삽입된다. 다만, 적절한 플래그를 설정 하면, 이 동작을 오버라이드(override) 할 수 있다 (상세한 것에 대하여는,dwFlags 파라미터의 설명을 참조할것).
  5. 마지막으로, 새로운 필터가 실행 상태로 전환할 수 있다. 데이터의 흐름을 재개하는 것은, 호출원의 책임이다. 호출원이 어플리케이션의 경우, 이것에는, 플래그를 세트 하지 않고 IPinFlowControl::Block 를 호출하면 좋다.

필터의 데이터 처리 thread의 어느쪽이든으로부터 이 메소드를 호출하면, 데드 록에 빠지는 위험성이 있다. 이 메소드가 필터 그래프를 잠그기 (위해)때문에,IMediaFilter::Stop 의 호출을 받았을 때, 필터를 정지할 수 없을 가능성이 있다. 이 상황을 피하기 (위해)때문에, 이 메소드는 필터가 제공하는 이벤트 오브젝트의 핸들을 이용한다. 필터는, 그 Stop 메소드의 호출을 받으면(자), 이벤트를 통지해야 한다.

IGraphConfig::RemoveFilterEx

IGraphConfig 인터페이스

필터 그래프로부터 필터를 삭제한다.

구문

HRESULT RemoveFilterEx(
    IBaseFilter *pFilter,
    DWORD Flags
);

파라미터

pFilter
[in] 그래프로부터 삭제하는 필터에의 포인터.
Flags
[in] REM_FILTER_FLAGS 열거형의 플래그의 편성.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는,IFilterGraph::RemoveFilter 메소드를 메소드의 동작을 지정하는 플래그를 받아들이도록(듯이) 확장한 것이다. 이 플래그를 사용하면(자), 어플리케이션은 자동적으로 핀으로부터 떼어내는 일 없이 필터를 삭제할 수 있는, 그것은 접속되고 있는 필터 그룹을 새로운 그래프로 이동할 때 퍼포먼스를 개선한다.

디폴트에서는, 삭제전에 필터가 절단 된다. 필터를 절단 하지 않기 위해(때문에)는,REMFILTERF_LEAVECONNECTED 플래그를 사용한다.

IGraphConfig::RemoveFilterFromCache

IGraphConfig 인터페이스

필터 캐쉬로부터 필터를 삭제한다.

구문

HRESULT RemoveFilterFromCache(
    IBaseFilter *pFilter
);

파라미터

pFilter
[in] 캐쉬로부터 삭제하는 필터에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

E_POINTER | Null 포인터 인수.
S_FALSE | 필터가 캐쉬에 들어가 있지 않다.
S_OK | 캐쉬로부터의 필터의 삭제에 성공했다.

IGraphConfig::SetFilterFlags

IGraphConfig 인터페이스

필터의 구성 정보를 설정한다.

구문

HRESULT SetFilterFlags(
    IBaseFilter *pFilter,
    DWORD dwFlags
);

파라미터

pFilter
[in] 필터 그래프의 필터에의 포인터.
dwFlags
[in] 새로운 구성 플래그를 지정하는 값. 가능한 값은 다음의 언젠가이다.
제로 (0) | 플래그를 세트 하지 않는다.
AM_FILTER_FLAGS_REMOVABLE | 동적인 재접속동안에 필터를 삭제할 수 있다. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_IN_GRAPH | 필터가 그래프에 포함되지 않았다.

주의

AM_FILTER_FLAGS_REMOVABLE 플래그는,IGraphConfig::Reconnect 메소드의 동작을 변경한다. Reconnect 메소드는, 2 개의 핀의 사이의 동적인 재접속을 실행한다. 한편의 핀만을 지정해, 이제 다른 한쪽의 핀을 지정하지 않았던 경우,Reconnect 는 지정된 핀으로부터 업 스트림 또는 다운 스트림으로 향해 적절한 핀을 검색한다. 다만 디폴트에서는,IFilterGraph::AddFilter 메소드로 그래프에 추가한 필터가 발견되면(자) 검색이 실패한다. 이 동작을 오버라이드(override) 하려면 ,SetFilterFlags 을 호출해 필터의 AM_FILTER_FLAGS_REMOVABLE 플래그를 설정한다.


IGraphConfigCallback 인터페이스

IGraphConfigCallback 인터페이스에는,IGraphConfig::Reconfigure 에게 건네진 콜백 메소드가 저장 된다. 이 인터페이스는, 호출원 (어플리케이션 또는 필터)이 이행 한다. 상세한 것에 대하여는, 「IGraphConfig 」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IGraphConfigCallback 메소드 | 설명
Reconfigure | IGraphConfig::Reconfigure 에 건네주는 콜백 메소드.

IGraphConfigCallback::Reconfigure

IGraphConfigCallback 인터페이스

IGraphConfig::Reconfigure 에 건네주는 콜백 메소드.

구문

HRESULT Reconfigure(
    PVOID pvContext,
    DWORD dwFlags
);

파라미터

pvContext
IGraphConfig::Reconfigure 메소드의 pvContext 파라미터에 건네주는 값.
dwFlags
IGraphConfig::Reconfigure 메소드의 dwFlags 파라미터에 건네주는 값.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

개발하는 어플리케이션 또는 필터로부터 IGraphConfig::Reconfigure 를 호출하는 경우는, 이 메소드를 이행 해 콜백으로서 건네줄 필요가 있다. IGraphConfig::Reconfigure 메소드는, 필터 그래프의 락 후에, 지정된 Reconfigure 메소드를 호출한다. 그래프를 동적으로 구축하기 위한 그 외의 세세한 처리는 모두, 지정된 메소드측에서 실시한다.

이 메소드가 성공하면(자),IGraphConfig::Reconfigure 는 그래프의 필터를 모두 실행 상태에 되돌리려고 한다. 메소드가 실패 하면,IGraphConfig::Reconfigure 는 이 메소드가 돌려주는 에러 코드를 그대로 돌려준다.

이 메소드에서는, 특수한 그래프 구축을 실시할 수 있다. 동적인 그래프 구축을 위한 보다 직접적인 방법에 대해서는, 「IGraphConfig::Reconnect 」를 참조할것.


IGraphVersion 인터페이스

IGraphVersion 인터페이스는, 필터 그래프 매니저에 이행 되어PID 및 어플리케이션으로부터 그래프의 변경 시기를 아는 수단을 제공한다. 그래프가 바뀌었을 때, 어플리케이션 또는 PID 가, 특정의 필터 또는 핀의 인터페이스를 가지고 있는 경우, 그 어플리케이션 또는 PID 는, 그래프에 다시 조회해 , 그 포인터가 아직 유효한가 어떤가 또는 사용해야 할 새로운 포인터가 있을지 어떨지를, 확인해야 한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IGraphVersion 메소드 | 설명
QueryVersion | 현재의 그래프의 버젼 번호를 취득한다.

IGraphVersion::QueryVersion

IGraphVersion 인터페이스

현재의 그래프의 버젼 번호를 취득한다.

구문

HRESULT QueryVersion(
    LONG *pVersion
    );

파라미터

pVersion
현재의 그래프의 버젼에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

버젼 번호는, 그래프의 필터 구성이 바뀌는지, 또는 그것들 필터의 접속이 바뀔 때마다 인크리먼트(increment) 된다. 마지막에 열거하고 나서 버젼 번호가 바뀌었을 경우에는, 그래프를 다시 열거할 필요가 있다.


IIPDVDec 인터페이스

이 인터페이스는,DV 비디오 디코더 필터의 프로퍼티를 설정 및 취득하는 메소드를 제공한다.

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IIPDVDec 메소드 | 설명
get_IPDisplay | 디코드 해상도를 취득한다.
put_IPDisplay | 디코드 해상도를 설정한다.

IIPDVDec::get_IPDisplay

IIPDVDec 인터페이스

디코드 해상도를 취득한다.

구문

HRESULT get_IPDisplay(
    int *displayPix
);

파라미터

displayPix
디코드 해상도를 나타내는 DVDECODERRESOLUTION 열거형의 멤버를 받는 변수에의 포인터.

반환값

S_OK 를 돌려준다.

IIPDVDec::put_IPDisplay

IIPDVDec 인터페이스

디코드 해상도를 설정한다.

구문

HRESULT put_IPDisplay(
    int displayPix
);

파라미터

displayPix
[in] 디코드 해상도를 지정하는 DVDECODERRESOLUTION 열거형의 멤버. 이 값의 의미는 현재의 포맷 (NTSC 또는 PAL )에 따라서 다르다. 적용되는 포맷은 실행시에 필터가 미디어 타입에 근거하고 판단한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_FAIL 또는 그 외의 에러 코드를 돌려준다.

주의

이미 그 필터가 미디어의 데이터를 스트림 하고 있는 경우, 이 메소드는 실패한다.


IKsPropertySet 인터페이스

IKsPropertySet 인터페이스의 본래의 목적은, KSProxy 를 사용해, 유저 모드의 COM 메소드 호출을, WDM 스트리밍 클래스 드라이버가 사용하는 커넬 모드의 "프로퍼티 세트 " 로 변환하는 것에 의해, WDM 드라이버 위에의 디바이스 프로퍼티를 효율적으로 설정 및 취득하는 것이다. 현재는, 이 인터페이스는, 컴퍼넌트간에 정보를 정확하게 교환하는 목적으로도 사용한다. 경우에 따라서는, 컴퍼넌트로 이 인터페이스를 이행 할 필요가 있다. 예를 들어, Microsoft® DVD 네비게이터에게 사용하는 소프트웨어 MPEG-2 디코더를 생성 하는 경우에는, 이 인터페이스를 이행 해, 게다가 IKsPropertySet::Get 메소드 및 IKsPropertySet::Set 메소드를 사용해, 네비게이터가 디코더에 보내는 DVD 관련의 프로퍼티 세트를 지원 해야 한다. 그 핀의 프로퍼티를 다른 핀 또는 필터로부터 설정 또는 취득할 수 있도록(듯이), 핀으로 이 인터페이스를 지원 해도 괜찮다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IKsPropertySet 메소드 | 설명
Set | 프로퍼티 세트 GUID 및 프로퍼티 ID 로 식별되는 프로퍼티를 설정한다.
Get | 프로퍼티 세트 GUID 및 프로퍼티 ID 로 식별되는 프로퍼티를 취득한다.
QuerySupported | 특정의 프로퍼티 세트가 오브젝트로 지원 되고 있는지 어떤지를 판단한다.

IKsPropertySet::Get

IKsPropertySet 인터페이스

프로퍼티 세트 GUID 및 프로퍼티 ID 로 식별되는 프로퍼티를 취득한다.

구문

HRESULT Get(
  REFGUID guidPropSet,
  DWORD dwPropID,
  LPVOID pInstanceData,
  DWORD cbInstanceData,
  LPVOID pPropData,
  DWORD cbPropData,
  DWORD *pcbReturned
  );

파라미터

guidPropSet
[in] 프로퍼티 세트 GUID .
dwPropID
[in] 프로퍼티 세트내에서의 프로퍼티의 식별자.
pInstanceData
[out, size_is(cbInstanceData)] 프로퍼티에 대응하는 인스턴스 데이터에의 포인터.
cbInstanceData
[in] pInstanceData 가 가리키는 버퍼에 포함되는 데이터의 바이트수.
pPropData
[out, size_is(cbPropData)] 프로퍼티의 값이 들어간 취득된 버퍼에의 포인터.
cbPropData
[in] pPropData 가 가리키는 버퍼에 포함되는 데이터의 바이트수.
pcbReturned
[out] pPropData 가 가리키는 버퍼에 돌려주어진 데이터의 바이트수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 Microsoft® DirectShow® 의 이행에서는, 프로퍼티 세트가 지원되어 있지 않은 경우, E_PROP_SET_UNSUPPORTED 를 돌려준다. 또, 지정된 프로퍼티 세트로 그 프로퍼티 ID 가 지원되어 있지 않은 경우에는, E_PROP_ID_UNSUPPORTED 를 돌려준다.

주의

프로퍼티를 취득하려면 , 이 메소드가 데이터를 설정하는 버퍼를 할당하는 것. 필요한 버퍼 사이즈를 판단하려면 ,pPropData 에 NULL,cbPropData 에 0 을 지정한다. 필요한 버퍼 사이즈가 pcbReturned 에 돌려주어진다.

IKsPropertySet::QuerySupported

IKsPropertySet 인터페이스

특정의 프로퍼티 세트가 오브젝트로 지원 되고 있는지 어떤지를 판단한다.

구문

HRESULT QuerySupported(
  REFGUID guidPropSet,
  DWORD dwPropID,
  DWORD *pTypeSupport
  );

파라미터

guidPropSet
[in] 프로퍼티 세트 GUID .
dwPropID
[in] 프로퍼티 세트내에서의 프로퍼티의 식별자.
pTypeSupport
[out] 드라이버의 지원을 나타내는 플래그를 나타내는 값에의 포인터. 지원 되는 플래그는 다음과 같다.
KSPROPERTY_SUPPORT_GET | IKsPropertySet::Get 메소드를 호출해 프로퍼티를 취득할 수 있다.
KSPROPERTY_SUPPORT_SET | IKsPropertySet::Set 메소드를 호출해 프로퍼티를 변경할 수 있다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행이 돌려주는 반환값은 다음과 같다.
E_NOTIMPL | 프로퍼티 세트가 지원되어 있지 않다.
E_PROP_ID_UNSUPPORTED | 지정된 프로퍼티 세트로 그 프로퍼티 ID 가 지원되어 있지 않다.
E_PROP_SET_UNSUPPORTED | 프로퍼티 세트가 지원되어 있지 않다.
S_OK | 지정된 프로퍼티 세트와 프로퍼티 ID 의 편성이 지원 되고 있다.

IKsPropertySet::Set

IKsPropertySet 인터페이스

프로퍼티 세트 GUID 및 프로퍼티 ID 로 식별되는 프로퍼티를 설정한다.

구문

HRESULT Set(
  REFGUID guidPropSet,
  DWORD dwPropID,
  LPVOID pInstanceData,
  DWORD cbInstanceData,
  LPVOID pPropData,
  DWORD cbPropData
  );

파라미터

guidPropSet
[in] 프로퍼티 세트 GUID .
dwPropID
[in] 프로퍼티 세트내에서의 프로퍼티의 식별자.
pInstanceData
[out, size_is(cbInstanceData)] 프로퍼티에 대응하는 인스턴스 데이터에의 포인터.
cbInstanceData
[in] pInstanceData 가 가리키는 버퍼에 포함되는 데이터의 바이트수.
pPropData
[out, size_is(cbPropData)] 프로퍼티의 값이 들어간 취득된 버퍼에의 포인터.
cbPropData
[in] pPropData 가 가리키는 버퍼에 포함되는 데이터의 바이트수.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

현재의 DirectShow 의 이행은, 프로퍼티 세트가 지원되어 있지 않은 경우, E_PROP_SET_UNSUPPORTED 를 돌려주어, 지정된 프로퍼티 세트로 그 프로퍼티 ID 가 지원되어 있지 않은 경우, E_PROP_ID_UNSUPPORTED 를 돌려준다.


IMediaControl 인터페이스

이 인터페이스는, 필터 그래프를 통과하는 데이터의 흐름을 제어하는 메소드를 제공한다. 여기에는, 그래프를 실행, 포즈, 및 정지하는 메소드가 포함된다. 필터 그래프 매니저가 이 인터페이스를 이행 한다. 필터 그래프 상태에 대한 상세한 것에 대하여는, 「필터 그래프의 데이터 플로우」를 참조할것.

IMediaControl 는 그래프를 구축하는 Automation 호환의 메소드도 제공한다. Microsoft® Visual Basic® 어플리케이션에서는, 이러한 메소드를 사용해, 필터 그래프를 구축하거나 그래프에 관한 정보를 취득하거나 할 수가 있다. C/C++ 어플리케이션에서는, 이 인터페이스는 아니고, 효율의 좋은 IGraphBuilder 및 IFilterGraph2 의 메소드를 사용하는 것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 타입 정보가 이용 가능한가 어떤가를 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우에, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 디스팟치 식별자 (DISPID)로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IMediaControl 메소드 | 설명
Run | 필터 그래프의 모든 필터를 실행한다.
Pause | 필터 그래프의 필터를 모두 포즈 한다.
Stop | 필터 그래프의 모든 필터를 정지한다.
StopWhenReady | 필터가 큐에 넣어지도록(듯이) 필터 그래프를 포즈로 해, 다음에 필터 그래프를 정지한다.
GetState | 필터 그래프 상태를 취득한다.
RenderFile | Visual Basic 어플리케이션으로 이용되어 지정한 파일을 렌더링 하는 필터 그래프를 구축한다.
AddSourceFilter | Visual Basic 로 이용되어 주어진 파일명을 읽어들일 수 있는 소스 필터를 그래프에 추가한다.
get_FilterCollection | Visual Basic 어플리케이션으로 이용되어 그래프의 필터를 나타내는 IFilterInfo 인터페이스의 집합을 취득해, 지정한 파일을 렌더링 하는 필터 그래프를 구축한다.
get_RegFilterCollection | Visual Basic 어플리케이션으로 이용되어 로컬 시스템으로 이용 가능한 등록된 필터를 나타내는 IRegFilterInfo 인터페이스의 집합을 취득한다.

IMediaControl::AddSourceFilter

IMediaControl 인터페이스

Visual Basic 로 이용되어 주어진 파일명을 읽어들일 수 있는 소스 필터를 그래프에 추가한다.

구문

HRESULT AddSourceFilter(
    BSTR strFilename,
    IDispatch **ppUnk
);

파라미터

strFilename
[in] 소스 비디오가 저장 된 파일의 이름.
ppUnk
[out] 필터의 IFilterInfo 인터페이스를 받는 포인터의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_CANNOT_LOAD_SOURCE_FILTER | 이 파일의 소스 필터를 로드할 수 없다.
VFW_E_NOT_FOUND | 오브젝트 또는 이름이 발견되지 않았다.
VFW_E_UNKNOWN_FILE_TYPE | 이 파일의 미디어 타입이 인식되지 않는다.

주의

이 메소드는 IDispatch 인터페이스 포인터를 돌려준다. 따라서, 주로 Automation 클라이언트로부터 사용한다. C/C++ 어플리케이션으로 이 조작을 가장 효율적으로 실행하려면 ,IGraphBuilder::AddSourceFilter 메소드를 호출하는 것.

IMediaControl::get_FilterCollection

IMediaControl 인터페이스

Visual Basic 어플리케이션으로 이용되어 그래프의 필터를 나타내는 IFilterInfo 인터페이스의 집합을 취득해, 지정한 파일을 렌더링 하는 필터 그래프를 구축한다.

구문

HRESULT get_FilterCollection(
    IDispatch **ppUnk
);

파라미터

ppUnk
[out, retval] IFilterInfo 오브젝트의 집합의 IAMCollection 인터페이스를 받는 포인터의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.
S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.

주의

이 메소드는 IDispatch 인터페이스 포인터를 돌려준다. 따라서, 주로 Automation 클라이언트로부터 사용한다. C/C++ 어플리케이션으로 이 조작을 가장 효율적으로 실행하려면 ,IFilterGraph::EnumFilters 메소드를 호출하는 것.

IMediaControl::get_RegFilterCollection

IMediaControl 인터페이스

Visual Basic 어플리케이션으로 이용되어 로컬 시스템으로 이용 가능한 등록된 필터를 나타내는 IRegFilterInfo 인터페이스의 집합을 취득한다.

구문

HRESULT get_RegFilterCollection(
    IDispatch **ppUnk
);

파라미터

ppUnk
[out, retval] IAMCollection 오브젝트의 IDispatch 인터페이스를 받는 포인터의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.

주의

이 메소드는 IDispatch 인터페이스 포인터를 돌려준다. 따라서, 주로 Automation 클라이언트로부터 사용한다. C/C++ 어플리케이션으로 이 조작을 가장 효율적으로 실행하려면 ,IFilterMapper::EnumMatchingFilters 메소드를 호출하는 것.

IMediaControl::GetState

IMediaControl 인터페이스

필터 그래프 상태 (포즈, 실행, 또는 정지)를 취득한다.

상태는 반드시 동기 해 이행 하면은 한정되지 않는다. 따라서, 이 메소드를 호출했을 때, 필터 그래프는 새로운 상태로 이행하고 있는 도중일지도 모른다. 그 경우, 이행이 완료하는지, 또는 지정된 타임 아웃 시간이 지날 때까지, 메소드는 블록 한다.

구문

HRESULT GetState(
    LONG msTimeout,
    OAFilterState *pfs
);

파라미터

msTimeout
[in] 타임 아웃의 시간폭 (밀리 세컨드 단위), 또는 타임 아웃 시간이 무제한한 것을 지정하는 INFINITE.
pfs
[out] 돌려주어진 (필터 그래프 ) 상태를 받는 포인터. 이 값은 FILTER_STATE 열거형의 멤버이다.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
VFW_S_STATE_INTERMEDIATE | 필터 그래프는 취득된 상태에 이행중.
VFW_S_CANT_CUE | 필터 그래프는 포즈 하고 있지만, 데이터를 큐에 넣을 수가 없다.
E_FAIL | 실패.

주의

어플리케이션은 이 메소드를 사용해 IMediaControl::Run 호출 후 재생이 시작 되었는지 어떠했는지를 확인할 수가 있다. 일반적으로, 어플리케이션은 필터 그래프를 어느 상태로 했는지를 트럭 하는 메카니즘을 자기 자신으로 가져야 한다. 보통 어플리케이션은 현재 상태를 사용해, 어느 유저 인터페이스 컨트롤이 사용 가능하게 할까를 결정한다. 예를 들어, 그래프가 실행 상태에 있다면, 어플리케이션은 「재생」버튼을 사용 불가로 해, 「정지」와「포즈」버튼을 사용 가능하게 한다.

필터 그래프가 새로운 상태에 이행중인 경우는, 이전 상태는 아니고 새로운 상태가 돌려주어진다.

메소드가 블록 되고 있을 때, 다른 thread로부터 호출해 상태를 변경 하면, 이 메소드는 에러를 돌려준다.

GetState 에서의 대기중에 thread는 메세지를 처리할 수 없기 때문에, 타임 아웃값에의 INFINITE 의 지정은 피하는 것. Windows 메세지를 처리하는 thread로부터 GetState 를 호출하는 경우는, 유저 입력에의 응답에 지장이 없게, 가능한 한 짧은 대기 시간을 지정하는 것. 특히, 네트워크나 인터넷 경유로 소스가 스트림 되는 경우는, 상태의 이행이 완료하기까지 매우 시간이 걸리기 (위해)때문에, 주의가 필요하다.

필터 그래프 상태의 상세한 것에 대하여는, 「필터 그래프의 데이터 플로우」를 참조할것.

IMediaControl::Pause

IMediaControl 인터페이스

필터 그래프의 필터를 모두 포즈 한다.

필터 그래프를 포즈 하면, 다음에 그래프를 실행 하면나무 즉석에서 렌더링 하기 위한(해), 그래프가 큐에 들어간다. 그래프가 포즈 하고 있을 때, 데이터는 처리되지만, 렌더링은 행해지지 않는다. 데이터는, 버퍼에 여유가 있는 한, 그래프에 인도해져변환 필터로 처리되지만, 그 데이터를 렌더링 필터가 렌더링 할 것은 없다. 다만, 비디오 렌더러는 현재의 샘플의 정지한 포스터 프레임을 표시한다.

구문

HRESULT Pause(void);

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_FALSE | 그래프의 포즈에 성공했지만, 상태의 이행이 완료하고 있지 않는 필터가 있다.
S_OK | 그래프의 필터가 모두 포즈 상태에의 이행을 완료했다.

주의

이 메소드가 S_FALSE 를 돌려주는 경우는,GetState 메소드를 호출해, 상태의 이행의 완료를 대기하는지, 또는 이행이 완료하고 있는지 확인하는 것.

실패했을 경우, 메소드는, 돌아오기 전에 그래프를 정지한다.

IMediaControl::RenderFile

IMediaControl 인터페이스

Visual Basic 어플리케이션으로 이용되어 지정한 파일을 렌더링 하는 필터 그래프를 구축한다.

구문

HRESULT RenderFile(
    BSTR strFilename
);

파라미터

strFilename
렌더링 하는 파일의 이름.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
VFW_S_AUDIO_NOT_RENDERED | 오디오 스트림을 재생할 수 없다. 적절한 렌더러가 발견되지 않았다.
VFW_S_DUPLICATE_NAME | 이름이 중복 하고 있는 필터의 추가가, 변경 후의 이름으로 성공했다.
VFW_S_PARTIAL_RENDER | 이 무비에 지원 되지 않는 포맷의 스트림이 포함되어 있다.
VFW_S_VIDEO_NOT_RENDERED | 비디오 스트림을 재생할 수 없다. 적절한 렌더러가 발견되지 않았다.
E_ABORT | 조작이 중지되었다.
VFW_E_CANNOT_CONNECT | 접속을 확립하는 중간 필터의 편성이 발견되지 않았다.
VFW_E_CANNOT_LOAD_SOURCE_FILTER | 이 파일의 소스 필터를 로드할 수 없다.
VFW_E_CANNOT_RENDER | 스트림을 렌더링 하는 필터의 편성이 발견되지 않았다.
VFW_E_INVALID_FILE_FORMAT | 파일 포맷이 무효.
VFW_E_NOT_FOUND | 오브젝트 또는 이름이 발견되지 않았다.
VFW_E_NOT_IN_GRAPH | 필터 그래프에 존재하지 않는 오브젝트에 요구된 함수를 실행할 수 없다.
VFW_E_UNKNOWN_FILE_TYPE | 이 파일의 미디어 타입이 인식되지 않는다.
VFW_E_UNSUPPORTED_STREAM | 파일을 재생할 수 없다. 포맷이 지원되어 있지 않다.

주의

이 메소드에서는, 어플리케이션으로부터 필터 그래프 매니저에, 렌더링 하는 미디어 파일의 이름을 건네줄 수가 있다. 필터 그래프 매니저는, 그 파일의 재생에 필요한 필터의 그래프를 구축한다. 이 메소드는,IGraphBuilder::RenderFile 메소드와 동등의 역할을 하는 Automation 호환의 메소드이다. C/C++ 어플리케이션에서는 이 메소드를 사용하는 것.

IMediaControl::Run

IMediaControl 인터페이스

필터 그래프의 모든 필터를 실행한다. 그래프가 실행중, 데이터는 그래프를 다녀 이동해 렌더링 된다.

구문

HRESULT Run (void);

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_FALSE | 그래프는 실행의 준비를 하고 있지만, 실행 상태에의 이행이 완료하고 있지 않는 필터가 있다.
S_OK | 그래프의 필터가 모두 실행 상태에의 이행을 완료했다.

주의

IMediaControl::Pause 혹은 IMediaControl::Stop 가 불려 갈 때까지, 메소드는 실행 상태가 된다. 재생이 스트림의 끝에 도착했을 때, 필터는 그 이상 데이터를 흘릴 수 없지만, 그래프는 실행인 채이다. 그 때, 어플리케이션은 그래프를 정지 혹은 포즈로 할 수 있다. 엔드 오브 스트림 (EOS) 이벤트의 상세한 것에 대하여는, 「IMediaEvent 」와「EC_COMPLETE 」를 참조할것.

이 메소드는 스트림의 처음까지 시크 하지 않는다. 그래프를 실행해, 그것을 포즈 해, 다음에 재차 그것을 실행 하면, 포즈 위치로부터 재생된다. 엔드 오브 스트림 (EOS)까지 도착한 다음에, 그래프를 실행시키면(자), 아무것도 일어나지 않는다. 그래프를 시크 하려면 ,IMediaSeeking 인터페이스를 사용하는 것.

이 메소드가 S_FALSE 를 돌려주는 경우는,GetState 메소드를 호출해, 상태의 이행의 완료를 대기할 수가 있다. 메소드가 실패했을 경우, 그래프의 일부의 필터는 실행 상태로 전환할 수 있고 있을 가능성이 있다. 스트림이 다수 있는 그래프에서는, 스트림이 모두 정상적으로 재생되는 일도 있다. 그래프를 정지할지 어떨지는 어플리케이션측에서 판단하지 않으면 안 된다.

IMediaControl::Stop

IMediaControl 인터페이스

그래프의 필터를 모두 정지한다.

구문

HRESULT Stop(void);

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

그래프가 실행중이라면, 지금 메소드는 그것을 정지시키기 전에 포즈 시킨다. 포즈중은, 비디오 렌더러는 현재의 프레임을 포스터 프레임으로서 디스플레이에 카피할 수 있다.

이 메소드는 스트림의 처음까지 시크 하지 않는다. 이 메소드를 호출해, 다음에 IMediaControl::Run 를 호출하면, 정지 위치로부터 재생된다. 그래프를 시크 하려면 ,IMediaSeeking 인터페이스를 사용하는 것.

필터 그래프 매니저는 그래프내의 모든 필터로 Pause 를 호출해, 다음에 포즈 조작의 완료를 기다리지 않고 모든 필터로 IMediaFilter::Stop 메소드를 호출한다. 그러므로 포즈 조작의 완료전에 Stop 메소드의 호출을 받는 필터가 있을지도 모른다. 커스텀 렌더링 필터를 개발하고 있다면, 이러한 케이스를 고려해, 실행 상태에 아직 있는 동안에 Stop 를 받으면(자), 최초로 필터를 포즈 하도록(듯이) 해야 한다. 그러나, 대부분의 필터는 이러한 경우에 특히 무엇인가 할 필요는 없다.

참조

StopWhenReady

IMediaControl::StopWhenReady

IMediaControl 인터페이스

필터가 큐에 넣어지도록(듯이) 필터 그래프를 포즈로 해, 다음에 필터 그래프를 정지한다.

구문

HRESULT StopWhenReady(void);

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

그래프가 정지하고 있을 때 필터 그래프를 시크 하고 싶으면, 이 메소드는 유용하다. 필터 그래프가 정지하고 있는 한, 현재 위치의 변경을 해도 새로운 프레임으로 비디오 윈도우를 재드로잉(Drawing)는 하지 않는다. 그러므로,IMediaSeeking::SetPositions 는 비디오 윈도우를 업데이트 하지 않는다. 시크 조작 후 윈도우를 업데이트 하려면 StopWhenReady 를 호출한다. 이 메소드는 그래프를 포즈 상태에 이행시켜, 포즈 처리가 완료하는 것을 기다려, 그래프를 정지상태태에 재차 이행 시킨다. 포즈 처리는 데이터를 그래프의 큐에 넣으므로, 비디오 렌더러는 그것을 받아, 새로운 프레임을 표시한다.

이 메소드는 비동기이다. 그것은 여기의 thread의 포즈가 완료하는 것을 기다린다. 불려 간 thread는 블록 하지 않고, 어플리케이션은 유저 입력에 반응할 수가 있다. 메소드가 돌아가면(자), 포즈 조작이 완료하기 전이어도, 그래프의 논리 상태는 정지가 된다. 이 시점에서 GetState 메소드를 호출하면 State_Stopped 가 돌아간다.

포즈 조작이 완료하기 전으로 (포즈, 실행, 시크와 같은) 상태 변경 커멘드를 받으면(자), 새로운 커멘드는 도중의 stop 커멘드를 캔슬한다. 포즈 조작은 완료하지만, 그래프는 정지하지 않는다.


IMediaEvent 인터페이스

이 인터페이스는,이벤트 통지를 취득하는 메소드와 필터 그래프의 디폴트의 이벤트 처리를 오버라이드(override) 하는 메소드를 제공한다. IMediaEventEx 인터페이스는, 이 인터페이스를 계승해, 확장한다.

필터 그래프 매니저가 이 인터페이스를 이행 한다. 어플리케이션에서는, 이 인터페이스를 사용해, 스트림의 종료, 렌더링 에러 등, 필터 그래프내에서 발생하는 이벤트에 응답할 수 있다. 필터에서는,IMediaEventSink 인터페이스를 사용해 필터 그래프에 이벤트를 보낸다.

이벤트 통지의 상세한 것에 대하여는, 「DirectShow 에서의 이벤트 통지」를 참조할것. 시스템 정의의 이벤트 통지의 일람에 대해서는, 「이벤트 통지 코드」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IMediaEvent 메소드 | 설명
GetEventHandle | 큐에 이벤트 통지가 있는 동안 통지제상태의, 수동 리셋 이벤트에의 핸들을 받는다.
GetEvent | 다음의 통지 이벤트를 이벤트 큐로부터 취득한다.
WaitForCompletion | 필터 그래프가 모든 유효한 데이터를 렌더링 하는 것을 기다린다.
CancelDefaultHandling | 지정한 이벤트에 대한 필터 그래프 매니저의 디폴트 처리를 캔슬한다.
RestoreDefaultHandling | 지정한 이벤트에 대한 필터 그래프 매니저의 디폴트 처리를 restore 한다.
FreeEventParams | 이벤트의 파라미터에 관련지을 수 있었던 리소스를 해방한다.

IMediaEvent::CancelDefaultHandling

IMediaEvent 인터페이스

지정한 이벤트에 대한 필터 그래프 매니저의 디폴트 처리를 캔슬한다.

구문

HRESULT CancelDefaultHandling(
    long lEvCode
);

파라미터

lEvCode
디폴트 처리를 캔슬하는 이벤트 코드.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_INVALIDARG | 이 이벤트에는 디폴트 처리는 없다.

주의

이벤트의 디폴트 처리를 restore 하려면 , 이벤트 코드를 건네주어 RestoreDefaultHandling 메소드를 호출하는 것.

IMediaEvent::FreeEventParams

IMediaEvent 인터페이스

이벤트의 파라미터에 관련지을 수 있었던 리소스를 해방한다.

구문

HRESULT FreeEventParams(
    long lEventCode,
    long lParam1,
    long lParam2
);

파라미터

lEventCode
[in] 이벤트 코드.
lParam1
[in] 제 1 이벤트 파라미터.
lParam2
[in] 제 2 이벤트 파라미터.

반환값

S_OK 를 돌려준다.

주의

IMediaEvent::GetEvent 메소드를 호출해 이벤트 통지를 받은 다음에,FreeEventParams 를 호출하지 않으면 안 된다. 이 메소드는 이벤트 파라미터에 할당할 수 있어 모든 리소스를 해방한다. 다음의 예에 나타내도록(듯이) GetEvent 에 이용한 같은 변수를 건네주는 것 :

hr = pEvent->GetEvent(&evCode, &param1, &param2, 0);
// Handle the event (not shown).
hr = pEvent->FreeEventParams(evCode, param1, param2);

IMediaEvent::GetEvent

IMediaEvent 인터페이스

다음의 통지 이벤트를 이벤트 큐로부터 취득한다.

구문

HRESULT GetEvent(
    long *lEventCode,
    long *lParam1,
    long *lParam2,
    long msTimeout
);

파라미터

IEventCode
[out] 이벤트 코드를 받는 변수에의 포인터.
lParam1
[out] 제 1 이벤트 파라미터를 받는 변수에의 포인터.
lParam2
[out] 제 2 이벤트 파라미터를 받는 변수에의 포인터.
msTimeout
[in] 타임 아웃 시간, 밀리 세컨드 단위. 이벤트가 있는 동안은 INFINITE 를 사용해 블록 한다.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_ABORT | 타임 아웃에 의한 마감 시간.

주의

어플리케이션은 타임 아웃 시간 INFINITE 를 사용하는 것은 피해야 한다, 왜냐하면 thread는 GetEvent 를 기다리는 동안 메세지를 처리할 수가 없기 때문이다. Windows 메 ss-때를 처리하는 같은 thread로부터 GetEvent 를 호출한다면, 유저 입력에의 리스폰스를 유지하기 위해서 대기 시간을 줄이는 것. 인터넷과 같은 소스로부터 데이터를 스트리밍 할 경우에는 이것은 가장 중요하다, 왜냐하면 상태의 이행은 완료할 때까지 매우 시간이 걸리기 때문이다.

GetEvent 를 호출한 다음에,FreeEventParams 메소드를 호출해 이벤트 파라미터에 확보한 모든 리소스를 해방하는 것.

통지 코드 및 파라미터값의 일람에 대해서는, 「이벤트 통지 코드」를 참조할것.

IMediaEvent::GetEventHandle

IMediaEvent 인터페이스

큐에 이벤트 통지가 있는 동안 통지제상태의, 수동 리셋 이벤트에의 핸들을 받는다.

구문

HRESULT GetEventHandle(
    OAEVENT *hEvent
);

파라미터

hEvent
[out] 이벤트 핸들을 받는 변수에의 포인터.

반환값

S_OK 를 돌려준다.

주의

필터 그래프 매니저는 이벤트 큐 상태를 반영한 수동 리셋 이벤트를 보관 유지한다. 큐에 이벤트 통지가 들어가 있으면(자), 수동 리셋 이벤트가 통지제가 된다. 큐가 컬러라면,IMediaEvent::GetEvent 메소드는 그 이벤트를 리셋 한다.

어플리케이션은 이 이벤트를 사용해 큐 상태를 확인할 수가 있다. 최초로 GetEventHandle 를 호출해 이벤트의 핸들을 취득한다. WaitForSingleObject 와 같은 Microsoft® Windows® 함수를 사용해, 이벤트가 통지제가 될 때까지 기다린다. 이벤트가 통지제가 되면(자),GetEvent 메소드를 호출해 다음의 이벤트 통지를 큐로부터 받아들인다. 필터 그래프 매니저는 큐가 비울 때까지 이벤트 통지를 보관 유지해, 그 후 이벤트를 리셋 한다.

주 Automation 와의 호환성이기 때문에, 이 메소드는 OAEVENT 변수에의 포인터를 가진다. C++ 에서는, 다음과 같이 HANDLE 타입의 변수를 선언해 그것을 OAEVENT 타입에 캐스트 한다 :
HANDLE hEvent;
GetEventHandle( (OAEVENT*) &hEvent );

어플리케이션이 이벤트 큐를 모니터 하는 이제(벌써) 1 개의 방법은 IMediaEventEx::SetNotifyWindow 메소드를 호출하는 것이다.

IMediaEvent::RestoreDefaultHandling

IMediaEvent 인터페이스

지정한 이벤트에 대한 필터 그래프 매니저의 디폴트 처리를 restore 한다.

구문

HRESULT RestoreDefaultHandling(
    long lEvCode
);

파라미터

lEvCode
[in] 디폴트 처리에 되돌리는 이벤트 코드.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_INVALIDARG | 이 이벤트에는 디폴트 처리는 없다.

주의

디폴트에서는, 그래프 매니저는 (EC_REPAINT 와 같은) 몇개의 이벤트를 어플리케이션에 건네주지 않고 처리한다. CancelDefaultHandling 메소드를 호출해 이벤트의 디폴트 처리를 오버라이드(override) 하면, 같은 이벤트 코드로 RestoreDefaultHandling 를 코 하는 것으로 디폴트의 처리를 restore 할 수가 있다.

IMediaEvent::WaitForCompletion

IMediaEvent 인터페이스

필터 그래프가 모든 유효한 데이터를 렌더링 하는 것을 기다린다.

구문

HRESULT WaitForCompletion(
    long msTimeout,
    long *pEvCode
);

파라미터

msTimeout
[in] 타임 아웃 시간, 밀리 세컨드 단위. 즉석에서 돌아오려면 0 을 건네준다. 무기한으로 블록 하려면 INFINITE 를 건네준다.
pEvCode
[out] 이벤트 코드를 받는 변수에의 포인터. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_ABORT | 타임 아웃에 의한 마감 시간.
VFW_E_WRONG_STATE | 필터 그래프가 실행중은 아니다.

주의

이 메소드는 타임 아웃이 마감 시간이 될 때까지 블록 한다, 혹은 이하의 이벤트의 1 개를 일으킨다 :

  • EC_COMPLETE
  • EC_ERRORABORT
  • EC_USERABORT

기다리고 있는 동안, 이 메소드는 모든 다른 이벤트 통지를 폐기한다.

반환값이 S_OK 라면,pEvCode 파라미터는 대기 상태 종료의 이벤트 코드를 받는다. 메소드가 돌아가도, 필터 그래프는 아직 실행하고 있다. 어플리케이션은 필요에 따라서 그래프를 포즈 하거나 정지하거나 할 수 있다.


IMediaEventEx 인터페이스

이 인터페이스는,이벤트 통지를 취득하는 메소드와 필터 그래프의 디폴트의 이벤트 처리를 오버라이드(override) 하는 메소드를 제공하는 IMediaEvent 인터페이스를 계승한다. IMediaEventEx 에는, 이벤트 발생시에 어플리케이션 윈도우로 메세지를 받아들이기 위한 메소드가 더해지고 있다. 이 인터페이스는,IMediaEvent 와 달리, Automation 를 통해서 이용할 수 없다. 따라서, Microsoft® Visual Basic® 로부터 직접 호출하는 일도 할 수 없다.

필터 그래프 매니저가 이 인터페이스를 이행 한다.

이벤트 통지의 상세한 것에 대하여는, 「DirectShow 에서의 이벤트 통지」를 참조할것. 시스템 정의의 이벤트 통지의 일람에 대해서는, 「이벤트 통지 코드」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IMediaEvent 메소드 | 설명
GetEventHandle | 큐에 이벤트 통지가 들어가 있는 동안에 통지제상태의 자동 리셋 이벤트의 핸들을 취득한다.
GetEvent | 이벤트 큐로부터 다음의 통지 이벤트를 취득한다.
WaitForCompletion | 필터 그래프가 모든 유효한 데이터를 렌더링 할 때까지 대기한다.
CancelDefaultHandling | 필터 그래프에 의한 지정된 이벤트의 필터 그래프 매니저의 디폴트 처리를 캔슬한다.
RestoreDefaultHandling | 필터 그래프에 의한 지정된 이벤트의 필터 그래프 매니저의 디폴트 처리를 restore 한다.
FreeEventParams | 이벤트의 파라미터에 관련지을 수 있었던 리소스를 해방한다.
IMediaEventEx 메소드 | 설명
SetNotifyWindow | 이벤트 통지를 처리하는 윈도우를 등록한다.
SetNotifyFlags | 이벤트 통지를 이용가능 혹은 불가로 한다.
GetNotifyFlags | 이벤트 통지의 이용가능 혹은 불가를 확인한다.

IMediaEventEx::GetNotifyFlags

IMediaEventEx 인터페이스

이벤트 통지의 이용가능 혹은 불가를 확인한다.

구문

HRESULT GetNotifyFlags(
    long *lplNoNotifyFlags
);

파라미터

lplNoNotifyFlags
[out] 이벤트 통지의 온/오프를 나타내는 값에의 포인터.
  • 제로: 이벤트 통지는 이용 가능.
  • AM_MEDIAEVENT_NONOTIFY: 이벤트 통지는 이용 불가.

반환값

성공했을 경우는, S_OK 를 돌려준다. lplNoNotifyFlags 파라미터가 NULL 의 경우는, E_POINTER 를 돌려준다.

주의

디폴트에서는, 필터 그래프 매니저는 어플리케이션에 이벤트 통지를 보낸다. 이벤트 통지를 이용 불가로 하려면 ,SetNotifyFlags 에 AM_MEDIAEVENT_NONOTIFY 를 인수로서 호출한다.

이벤트 통지가 이용 불가라면, 각 스트림이 끝나면(자) GetEventHandle 메소드로부터 돌아가는 핸들이 통지제가 된다, 즉 필터 그래프 매니저가 EC_COMPLETE 이벤트를 받을 때마다 통지제가 된다.

IMediaEventEx::SetNotifyFlags

IMediaEventEx 인터페이스

이벤트 통지를 이용가능 혹은 불가로 한다.

구문

HRESULT SetNotifyFlags(
    long lNoNotifyFlags
);

파라미터

lNoNotifyFlags
[in] 이벤트 통지를 이용가능으로 할까 불가로 하는지를 나타내는 값. 이하의 값의 1 개가 아니면 안된다 :
  • 제로 : 이벤트 통지를 이용 가능하게 한다.
  • AM_MEDIAEVENT_NONOTIFY: 이벤트 통지를 이용 불가로 한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. lNoNotifyFlags 파라미터가 무효인 경우는, E_INVALIDARG 를 돌려준다.

주의

디폴트에서는, 필터 그래프 매니저는 어플리케이션에 이벤트 통지를 보낸다. 이벤트 통지를 이용 불가로 하려면 ,SetNotifyFlags 메소드를 AM_MEDIAEVENT_NONOTIFY 플래그로 호출한다.

이벤트 통지가 이용 불가라면, 각 스트림이 끝나면(자) GetEventHandle 메소드로부터 돌아가는 핸들이 통지제가 된다, 즉 필터 그래프 매니저가 EC_COMPLETE 이벤트를 받을 때마다 통지제가 된다.

IMediaEventEx::SetNotifyWindow

IMediaEventEx 인터페이스

이벤트 통지를 처리하는 윈도우를 등록한다.

구문

HRESULT SetNotifyWindow(
    OAHWND hwnd,
    long lMsg,
    long lInstanceData
);

파라미터

hwnd
[in] 통지하는 윈도우의 핸들, 혹은 통지를 정지하려면 NULL 를 건네준다.
lMsg
[in] 통지로서 건네주는 윈도우 메세지.
lInstanceData
[in] lMsg 메세지의 lParam 파라미터로서 건네주는 값 .

반환값

성공했을 경우는, S_OK 를 돌려준다. hwnd 파라미터가 유효한 윈도우 핸들이 아닌 경우는, E_INVALIDARG 를 돌려준다.

주의

이 메소드는 이벤트 통지를 처리하는 윈도우를 지시한다. 필터 그래프 매니저가 이벤트를 이벤트 큐에 넣을 때마다, 지정한 윈도우에 메세지도 보낸다. hwnd 파라미터는 윈도우를 지정해,lMsg 파라미터는 메세지를 지정한다. 어플리케이션은 프라이빗 윈도우 메세지를 이 때문에 정의해야 한다. 메세지의 lParam 파라미터에는 lInstanceData 의 값이 세트 되어wParam 파라미터는 제로에 세트 된다.

윈도우가 메세지를 받아들이면(자),GetEvent 메소드를 호출해 이벤트를 취득해야 한다. 이벤트는 비동기이므로, 큐에는 복수의(혹은 제로의) 이벤트가 들어가 있을 가능성이 있다. GetEvent 가 에러 코드를 돌려줄 때까지 반복해 호출하는 것.


IMediaEventSink 인터페이스

필터 그래프 매니저에 필터 그래프내에서 일어난 이벤트를 통지한다. 필터는 이 인터페이스를 사용해 이벤트를 리포트한다. 필터 그래프 매니저는 이 인터페이스를 공개한다.

어플리케이션에서는 IMediaEventSink 를 사용하지 않는다. 어플리케이션으로부터 이벤트를 취득하려면 ,IMediaEventEx 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaEventSink 메소드 | 설명
Notify | 필터 그래프 매니저에 이벤트를 통지한다.

IMediaEventSink::Notify

IMediaEventSink 인터페이스

필터 그래프 매니저에 이벤트를 통지한다.

구문

HRESULT Notify(
long EventCode,
LONG_PTR EventParam1,
LONG_PTR EventParam2
);

파라미터

EventCode
[in] 이벤트의 식별자.
EventParam1
[in] 이벤트의 제 1 파라미터.
EventParam2
[in] 이벤트의 제 2 파라미터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이벤트는 큐에 넣어지지만, 이 thread상에서는 어플리케이션에 통지되지 않는다. 통지 코드 및 파라미터값의 일람에 대해서는, 「이벤트 통지 코드」를 참조할것.


IMediaFilter 인터페이스

필터의 스트리밍 상태를 제어한다.

모든 Microsoft® DirectShow® 필터는, 이 인터페이스를 이행 한다. 이 인터페이스는, 필터 상태 (정지, 포즈, 실행)를 바꾸는 메소드, 필터의 현재 상태를 취득하는 메소드, 및 기준 클락을 설정하는 메소드를 제공한다. 필터 그래프 매니저도, 이 인터페이스를 공개한다. 필터 그래프 매니저는, 필터 그래프내의 필터에, 메소드 호출을 제공한다.

이 인터페이스는, 낮은 레벨의 제어를 그래프에 제공한다. 어플리케이션은, 보다 높은 레벨의 제어를 제공하는 IMediaControl 인터페이스를 사용할 필요가 있다.

IMediaFilter 는,IPersist 인터페이스를 계승한다. IBaseFilter 인터페이스는,IMediaFilter 로부터 계승된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaFilter 메소드 | 설명
Stop | 필터를 정지한다.
Pause | 필터를 포즈 한다.
Run | 필터를 실행한다.
GetState | 필터 상태 (정지, 포즈, 실행)를 취득한다.
SetSyncSource | 필터의 기준 클락을 설정한다.
GetSyncSource | 필터가 사용하고 있는 기준 클락을 취득한다.

IMediaFilter::GetState

IMediaFilter 인터페이스

필터 상태 (정지, 포즈, 실행)를 취득한다.

구문

HRESULT GetState(
  DWORD dwMilliSecsTimeout,
  FILTER_STATE *State
  );

파라미터

dwMilliSecsTimeout
[in] 타임 아웃 시간, 밀리 세컨드 단위. 무기한으로 블록 하려면 INFINITE 를 건네준다.
State
[out] 필터 상태를 나타내는 FILTER_STATE 열거형의 멤버를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_S_STATE_INTERMEDIATE | 상태 이행중.
VFW_S_CANT_CUE | 필터는 액티브하지만, 데이터를 출력할 수가 없다.

주의

상태 이행은 비동기에 실시할 수가 있다. 필터가 새로운 상태로 이행하고 있어, 이행이 완료하기 전에 메소드의 타임 아웃 시간이 왔다면, 메소드는 VFW_S_STATE_INTERMEDIATE 를 돌려준다.

필터가 있는 이유로써 데이터를 출력할 수 없으면,VFW_S_CANT_CUE 를 돌려준다. 라이브 캡춰 필터는, 포즈 상태에서는 데이터를 출력하지 않기 때문에, 포즈중에 이 값을 돌려준다.

상세한 것에 대하여는, 「필터 그래프의 데이터 플로우」를 참조할것.

IMediaFilter::GetSyncSource

IMediaFilter 인터페이스

필터가 사용하고 있는 기준 클락을 취득한다.

구문

HRESULT GetSyncSource(

  IReferenceClock **pClock

  );

파라미터

pClock
[out] 클락의 IReferenceClock 인터페이스에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

E_OK | 성공.
E_POINTER | Null 포인터 인수.

주의

만약 필터가 기준 클락을 사용하지 않으면,*pClock 에 NULL 가 설정된다. 메소드가 돌아갈 때,*pClock 가 NULL 이외라면,IReferenceClock 인터페이스에는 참조 카운트가 남는다. 해방시에는 주의가 필요하다.

IMediaFilter::Pause

IMediaFilter 인터페이스

필터를 포즈 한다.

구문

HRESULT Pause(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 이행이 완료하지 않았다.
S_OK | 성공. 이행은 완료했다.

주의

필터가 포즈 때, 필터는 샘플을 받아, 처리해, 출력할 수가 있다. 그러나, 렌더링 필터는 포즈중은 1 개의 샘플 밖에 액세스 할 수 없다. 그 때문에, 필터 그래프가 포즈 때는, 최초의 샘플이 렌더러에 닿을 때까지는 샘플은 그래프내를 이동한다. 그 때, 스트리밍은 Run 메소드가 불려 갈 때까지 포즈가 된다. 비디오 렌더러는, 최초의 샘플을 정지화면으로서 표시한다.

라이브 캡춰 필터는 포즈중에는 샘플을 출력하지 못하고, 실행중만 출력한다.

상태 이행은 비동기의 경우가 있다. 이행이 완료하기 전에 메소드가 돌아간다면, 반환값은 S_FALSE 이다. 렌더러 필터는, 샘플을 1 개 받을 때까지는 상태 이행을 완료하지 않는다.

IMediaFilter::Run

IMediaFilter 인터페이스

필터를 실행한다.

구문

HRESULT Run(
    REFERENCE_TIME tStart
);

파라미터

tStart
스트림 타임 0 에 대응하는 기준 타임.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 이행이 완료하지 않았다.
S_OK | 성공. 이행은 완료했다.

주의

필터가 포즈 때, 필터는 샘플을 받아, 처리해, 출력할 수가 있다. 그러나, 소스 필터는 새로운 샘플을 생성해, 렌더링 필터는 그것을 렌더링 한다.

상태 이행은 비동기의 경우가 있다. 이행이 완료하기 전에 메소드가 돌아가는 경우, 반환값은 S_FALSE 이다.

스트림 타임은 현재의 기준 타임부터 tStart 를 빼 계산된다. 미디어 샘플이 언제 렌더링 되고인지를 계산하기 위해서, 렌더러는 현재의 스트림 타임과 타임 스탬프를 비교한다. 그 때문에, 타임 스탬프 제로의 미디어 샘플은,tStart 시에 렌더링 될 필요가 있다. 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

어플리케이션이 IMediaControl::Run 메소드를 호출하는 경우에, 필터 그래프 매니저는 각 필터로 IMediaFilter::Run 를 호출한다. 필터 그래프 매니저는 tStart 의 값을 조금 다음에 설정해, 그래프의 지연에 대응한다.

IMediaFilter::SetSyncSource

IMediaFilter 인터페이스

필터의 기준 클락을 설정한다.

구문

HRESULT SetSyncSource(
    IReferenceClock *pClock
);

파라미터

pClock
[in] 클락의 IReferenceClock 인터페이스에의 포인터 또는 NULL .

반환값

성공의 경우 S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

pClock 파라미터가 NULL 의 경우, 필터는 기준 클락을 사용하지 않는다. 렌더링 필터는 기준 클락을 사용해, 언제 샘플이 렌더링 될까를 스케줄 한다. 기준 클락이 없는 경우, 렌더링 필터는, 모든 샘플을 받자마자 렌더링 한다.

필터 그래프내의 모든 필터는, 동기를 취하기 위해서(때문에), 같은 기준 클락을 공유할 필요가 있다. 보통, 필터 그래프 매니저는 기준 클락을 선택한다. 어플리케이션은, 필터 그래프 매니저로 IMediaFilter::SetSyncSource 메소드를 호출해, 디폴트의 클락을 오버라이드(override) 할 수 있다. 다만, 이와 같이 하는 것은, 다른 클락을 선택하는 특별한 이유가 있는 경우뿐이다.

IMediaFilter::Stop

IMediaFilter 인터페이스

필터를 정지한다.

구문

HRESULT Stop(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 이행이 완료하지 않았다.
S_OK | 성공. 이행은 완료했다.

주의

필터가 정지 하면, 필터는 샘플의 처리나 출력은 실시하지 않는다. 또, 업 스트림 필터로부터의 샘플을 거부한다.

상태 이행은 비동기의 경우가 있다. 이행이 완료하기 전에 메소드가 돌아가는 경우, 반환값은 S_FALSE 가 된다.


IMediaPosition 인터페이스

스트림내의 위치를 시크 하는 메소드를 가진다.

IMediaSeeking 인터페이스는 이 인터페이스를 개선하고 있다. C/C++ 로 쓰여진 어플리케이션은 IMediaPosition 대신에 IMediaSeeking 를 사용해야 하는 것이다. 그러나,IMediaSeeking 는 Automation 와 호환성이 없기 때문에, Microsoft® Visual Basic® 로 쓰여진 어플리케이션은 대신에 IMediaPosition 를 사용해야 한다.

이 인터페이스는 개개의 필터가 실시하는 것과 같게 필터 그래프 매니저에 의해 공개되고 있다. 어플리케이션은 IMediaPosition 인터페이스 포인터를 필터로부터는 아니고 필터 그래프 매니저로부터 취득해야 한다. 필터 그래프 매니저는 소스 필터에의 업 스트림 호출을 계승한다. 이벤트의 이 순서에 의해 모든 스트림은 동기 된다.

할당한 호출이 에러를 돌려주면(자), 필터 그래프 매니저는 취득한 최초의 에러값을 돌려준다. 이 경우 할당한 호출의 몇개인가가 성공하고 있을 가능성이 있다. 그러나, 할당한 모든 호출이 E_NOTIMPL 를 돌려줄 때까지, 필터 그래프는 E_NOTIMPL 를 돌려주지 않는다. 그래프내의 적어도 1 개의 필터가 그 메소드를 이행 하면, 필터 그래프 매니저는 E_NOTIMPL 를 돌려주지 않는다.

필터 개발자 : 이 메소드를 이행 해서는 안 된다. 대신에 IMediaSeeking 를 이행 하는 것. 그 필터가 IMediaSeeking 를 지원 한다면, 필터 그래프 매니저는 자동적으로 IMediaPosition 에의 호출을 처리한다.

Vtable 순서의 메소드.

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 오브젝트가 제공하는 타입 정보 인터페이스의 수를 취득한다.
GetTypeInfo | 오브젝트의 타입 정보를 취득하는, 그것을 사용해 인터페이스의 타입 정보를 취득한다.
GetIDsOfNames | 일련의 DISPID 에 대응하는 일련의 이름을 맵 한다.
Invoke | 오브젝트에 의해 공개되는 프로퍼티와 메소드에의 액세스를 제공한다.
IMediaPosition 메소드 | 설명
get_Duration | 스트림의 시간폭을 취득한다.
put_CurrentPosition | 현재의 위치를 설정하는, 스트림의 전시간폭으로부터의 상대값.
get_CurrentPosition | 현재의 위치를 취득하는, 스트림의 전시간폭으로부터의 상대값.
get_StopTime | 재생이 정지하는 시간을 취득하는, 스트림의 전시간폭으로부터의 상대값.
put_StopTime | 재생이 정지하는 시간을 설정하는, 스트림의 전시간폭으로부터의 상대값.
get_PrerollTime | 시작 위치전에 큐에 들어가 있는 데이터의 양을 취득한다.
put_PrerollTime | 시작 위치전에 큐에 들어가 있는 데이터의 양을 설정한다.
put_Rate | 재생 레이트를 설정한다.
get_Rate | 재생 레이트를 취득한다.
CanSeekForward | 필터 그래프가 스트림의 순서 방향으로 시크 가능한가 어떤가를 확인한다.
CanSeekBackward | 필터 그래프가 스트림의 역방향으로 시크 가능한가 어떤가를 확인한다.

IMediaPosition::CanSeekBackward

IMediaPosition 인터페이스

필터 그래프가 스트림의 역방향으로 시크 가능한가 어떤가를 확인한다.

구문

HRESULT CanSeekBackward(
    LONG *pCanSeekBackward
);

파라미터

pCanSeekBackward
[out] 그래프가 역방향으로 시크 가능하면 OATRUE 값을 받아, 시크 할 수 없으면 OAFALSE 를 받는 변수에의 포인터.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

IMediaPosition::CanSeekForward

IMediaPosition 인터페이스

필터 그래프가 스트림의 순서 방향으로 시크 가능한가 어떤가를 확인한다.

구문

HRESULT CanSeekForward(
    LONG *pCanSeekForward
);

파라미터

pCanSeekForward
[out] 그래프가 순서 방향으로 시크 가능하면 OATRUE 값을 받아, 시크 할 수 없으면 OAFALSE 를 받는 변수에의 포인터.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

IMediaPosition::get_CurrentPosition

IMediaPosition 인터페이스

현재의 위치를 취득하는, 스트림의 전시간폭으로부터의 상대값.

구문

HRESULT get_CurrentPosition(
    REFTIME *pllTime
);

파라미터

pllTime
[out] 현재의 위치를 받는 변수에의 포인터, 초단위.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는 재생이 도달한 현재 위치를 돌려준다. 그 값은 재생 레이트와 시작 타임을 무시한다. 예를 들어, 레이트에 2.0 을 세트 해, 시작 타임이 5 초라면 하면, 4 초 그래프를 실행 하면 현재의 위치는 9.0 초가 된다 (5 + 4 × 2.0).

그래프가 포즈 혹은 정지라면, 현재 위치는 재생이 복귀하는 포인트가 된다.

IMediaPosition::get_Duration

IMediaPosition 인터페이스

스트림의 시간폭을 취득한다.

구문

HRESULT get_Duration(
    REFTIME *plength
);

파라미터

plength
[out] 전스트림장을 받는 변수에의 포인터, 초단위.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는 보통 재생 스피드에서의 시간폭을 취득한다. 재생 레이트를 변경해도 그 시간폭에는 영향을 주지 않는다.

IMediaPosition::get_PrerollTime

IMediaPosition 인터페이스

시작 위치전에 큐에 들어가 있는 데이터의 양을 취득한다.

구문

HRESULT get_PrerollTime(
    REFTIME *pllTime
);

파라미터

pllTime
[out] 프리로르 타임을 받는 변수에의 포인터, 초단위.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

프리로르 는 시작 위치보다 전의 타임으로, 테이프 플레이어와 같은 비랜덤 억세스 디바이스에서는 거기로부터 테이프등의 감아 포함이 시작 된다.

그래프내에 이 메소드를 이행 한 필터가 없으면, 필터 그래프 매니저는 *pllTime 의 값을 제로에 세트 해 S_OK 를 돌려준다.

IMediaPosition::get_Rate

IMediaPosition 인터페이스

재생 레이트를 취득한다.

구문

HRESULT get_Rate(
    double *pdRate
);

파라미터

pdRate
[out] 재생 레이트를 받는 변수에의 포인터.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

재생 레이트는 보통 스피드로부터의 비로 표현된다. 그러므로, 1.0 은 보통 재생 스피드로, 0.5 는 반의 스피드, 2.0 은 배의 스피드이다.

IMediaPosition::get_StopTime

IMediaPosition 인터페이스

재생이 정지하는 시간을 취득하는, 스트림의 전시간폭으로부터의 상대값.

구문

HRESULT get_StopTime(
    REFTIME *pllTime
);

파라미터

pllTime
[out] 종료 타임을 받는 변수에의 포인터, 초단위.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

재생 레이트는 이 메소드에 의해 돌아가는 값에 영향을 주지 않는다.

IMediaPosition::put_CurrentPosition

IMediaPosition 인터페이스

현재의 위치를 설정하는, 스트림의 전시간폭으로부터의 상대값.

구문

HRESULT put_CurrentPosition(
    REFTIME llTime
);

파라미터

llTime
[in] 새로운 위치, 초단위.

반환값

Returns an HRESULT 값을 돌려준다. 이하의 몇개의 값 :

S_FALSE | 그래프는 포즈였다, 그리고 실행 상태에 돌아오는 이행중이다.
S_OK | 성공.
E_INVALIDARG | 부적절한 인수.
E_NOTIMPL | 이행되어 있지 않다.

주의

llTime 파라미터에 의해 지정되는 위치는 전시간폭으로부터의 상대값이며, 재생 레이트는 무시된다. 예를 들어, 원시 파일이 10 초의 길이라면, 5.0 의 위치를 설정 하면 그래프는 재생 레이트 (와)는 관계없는 것으로 파일의 한가운데를 시크 한다.

필터 그래프가 실행중이라면, 필터 그래프 매니저는 그래프를 포즈 해, 시크 커멘드를 처리해, 다음에 그래프를 재차 실행한다. 그래프가 실행 상태에의 이행중에 메소드가 돌아가면(자), 반환값은 S_FALSE 가 된다.

시크 커멘드를 받았을 때 필터가 포즈라면, 새로운 위치로부터 그 데이타를 뽑아 붐비기 전에 기존의 데이터를 플래시 해야 한다. 상세한 것에 대하여는,IPin::BeginFlush 」와「IPin::EndFlush 」를 참조할것.

IMediaPosition::put_PrerollTime

IMediaPosition 인터페이스

시작 위치전에 큐에 들어가 있는 데이터의 양을 설정한다.

구문

HRESULT put_PrerollTime(
    REFTIME llTime
);

파라미터

llTime
[in] 프리로르타임, 초단위.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.

주의

프리로르 는 시작 위치보다 전의 타임으로, 테이프 플레이어와 같은 비랜덤 억세스 디바이스에서는 거기로부터 테이프등의 감아 포함이 시작 된다.

IMediaPosition::put_Rate

IMediaPosition 인터페이스

재생 레이트를 설정한다.

구문

HRESULT put_Rate(
    double dRate
);

파라미터

dRate
[in] 재생 레이트, 제로여서는 안 된다.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 이행되어 있지 않다.

주의

재생 레이트는 보통 스피드의 비율로서 표현된다. 따라서, 1.0 은 보통 재생 스피드, 0.5 는 반의 스피드, 2.0 은 배의 스피드이다. 오디오 스트림에 대해서는, 레이트를 바꾸면(자) 그 피치도 바뀐다.

상세한 것에 대하여는, 「IMediaSeeking::SetRate 」를 참조할것.

IMediaPosition::put_StopTime

IMediaPosition 인터페이스

재생이 정지하는 시간을 취득하는, 스트림의 전시간폭으로부터의 상대값.

구문

HRESULT put_StopTime(
    REFTIME llTime
);

파라미터

llTime
[in] 스톱 타임, 초단위.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 이행되어 있지 않다.

주의

스톱 단위는 시작 타임과 재생 레이트를 무시한다. 예를 들어, 시작 타임이 2 초로, 스톱 타임이 12 초로, 재생 레이트가 2.0 이라면, 재생은 (실제의 시간에) 5 초 후에 정지한다.


IMediaPropertyBag 인터페이스

IMediaPropertyBag 인터페이스는,미디어 프로퍼티 가방에서 공개된다. 미디어 프로퍼티 가방이란, 표준적인 COM 의 프로퍼티 가방을 특수화 한 것이어, AVI (Audio-Video Interleaved) 파일의 INFO 체크 및 DISP 체크의 설정 및 취득을 목적으로 하고 있다.

INFO 체크에는, 작자, 저작권 정보 등, 파일에 관한 포괄적인 정보가 저장 되고 있다. DISP 체크에는, 데이터가 클립보드 포맷으로 저장 되고 있다. 상세한 것에 대하여는, RIFF (Resource Interchange File Format)의 사양을 참조할것.

미디어 프로퍼티 가방의 체크는, 다음과 같이 이름/값페어로 저장 된다.

  • INFO 체크 : 이름은 INFO/XXXX 포맷의 캐릭터 라인. 여기서 XXXX 는 포괄적인 정보의 종류를 정의하는 4 문자의 코드이며, 예를 들어 ICOP 는 저작권 정보,IART 는 작자명을 의미한다. 값은 임의의 캐릭터 라인.
  • DISP 체크 : 이름은 DISP/0000000000 포맷의 캐릭터 라인. 여기서 0000000000 은 표준적인 클립보드 포맷과 동등의 10 자리수의 십진수이며, 예를 들어 0000000008 은 CF_DIB 를 의미한다. 값은 표시 데이터가 저장 된 바이트 배열.

이 인터페이스는 IPropertyBag 인터페이스를 계승한다. 이 인터페이스를 IPersistMediaPropertyBag 인터페이스와 함께 사용해, AVI 파일로부터 INFO 체크 및 DISP 체크를 취득한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaPropertyBag 메소드 | 설명
EnumProperty | 프로퍼티와 값의 페어를 취득한다.

IMediaPropertyBag::EnumProperty

IMediaPropertyBag 인터페이스

프로퍼티와 값의 페어를 취득한다.

구문

HRESULT EnumProperty(
    ULONG iProperty,
    VARIANT *pvarPropertyName,
    VARIANT *pvarPropertyValue
);

파라미터

iProperty
[in] 페어의 인덱스값.
pvarPropertyName
[in, out] 프로퍼티의 이름을 받는 VARIANT 에의 포인터.
pvarPropertyValue
[in, out] 프로퍼티의 값을 받는 VARIANT 에의 포인터.

반환값

HRESULT 값을 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS) | 인덱스가 범위외.

주의

이름은 항상 캐릭터 라인이다. 이 메소드를 호출하기 전에, VARIANT 형의 pvarPropertyName 파라미터에 VT_EMPTY 또는 VT_BSTR 를 설정하는 것.

값은 캐릭터 라인 (INFO 체크의 경우) 또는 바이트 배열 (DISP 체크의 경우)이다. VARIANT 형의 pvarPropertyName 파라미터에 VT_EMPTY, VT_BSTR, 또는 (VT_ARRAY | VT_UI1)을 설정한다.


IMediaSample 인터페이스

미디어 샘플의 프로퍼티를 세트 혹은 취득한다. 미디어 샘플은 COM 오브젝트이며 미디어 데이터의 블록이 저장 된다. 미디어 샘플은 필터간의 공유 메모리 버퍼의 사용을 지원 한다.

이 인터페이스는, 미디어 샘플의 프로퍼티를 설정 및 취득하는 메소드를 제공한다. 미디어 샘플이란, 미디어 데이터의 블록이 저장 된 COM 오브젝트이다. 미디어 샘플은, 필터간에서의 공유 메모리 버퍼의 사용을 지원 한다.

IMediaSample2 인터페이스는, 이 인터페이스를 계승한다.

보통, 이 인터페이스의 메소드를, 어플리케이션으로부터 호출할 것은 없다. 필터에서는, 이 인터페이스를 사용해, 샘플의 프로퍼티를 설정해, 다운 스트림 필터에 데이터를 건네준다. 그 다운 스트림 필터에서는, 이 인터페이스를 사용해, 프로퍼티를 취득해, 데이터를 읽어낸다. 필터는, 데이터를 직접 수정하는지, 또는 샘플을 카피하고 나서 변경해, 다운 스트림에 건네준다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaSample 메소드 | 설명
GetPointer | 이 버퍼의 메모리에의 읽어내/기입 포인터를 취득한다.
GetSize | 버퍼의 사이즈를 취득한다.
GetTime | 이 샘플이 시작 및 종료해야 할스트림 타임을 취득한다.
SetTime | 이 샘플이 시작 및 종료해야 할 스트림 타임을 설정한다.
IsSyncPoint | 이 샘플의 시작이 동기 포인트인가 어떤가를 판단한다.
SetSyncPoint | 이 샘플의 시작이 동기 포인트인가 어떤가를 설정한다.
IsPreroll | 이 샘플이 프리로르산풀인가 어떤가를 확인한다.
SetPreroll | 이 샘플이 프리로르산풀인가 어떤가를 지정한다.
GetActualDataLength | 버퍼내의 유효한 데이터의 길이를 취득한다.
SetActualDataLength | 버퍼내의 유효한 데이터의 길이를 설정한다.
GetMediaType | 미디어 타입이 이전의 샘플과 다르다면, 미디어 타입을 취득한다.
SetMediaType | 샘플의 미디어 타입을 설정한다.
IsDiscontinuity | 이 샘플이 데이터 스트림내에서 브레이크를 표시할지 어떨지를 확인한다.
SetDiscontinuity | 이 샘플이 데이터 스트림내에서 브레이크를 표시할지 어떨지를 지정한다.
GetMediaTime | 이 샘플의 미디어 타임을 취득한다.
SetMediaTime | 이 샘플의 미디어 타임을 설정한다.

IMediaSample::GetActualDataLength

IMediaSample 인터페이스

버퍼내의 유효한 데이터의 길이를 취득한다.

구문

LONG GetActualDataLength(void);

반환값

유효한 데이터의 길이를 돌려주는, 바이트 단위.

IMediaSample::GetMediaTime

IMediaSample 인터페이스

이 샘플의 미디어 타임을 취득한다.

구문

HRESULT GetMediaTime(
    LONGLONG *pTimeStart,
    LONGLONG *pTimeEnd
);

파라미터

pTimeStart
[out] 미디어 시작 타임을 받는 변수에의 포인터.
pTimeEnd
[out] 미디어 종료 타임을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_MEDIA_TIME_NOT_SET | 이 샘플에는 미디어 타임이 세트되어 있지 않다.

주의

미디어 타임의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

IMediaSample::GetMediaType

IMediaSample 인터페이스

미디어 타입이 이전의 샘플과 다르다면, 미디어 타입을 취득한다.

구문

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

파라미터

ppMediaType
AM_MEDIA_TYPE 구조체에의 포인터를 받는 변수의 주소. 미디어 타입이 이전의 샘플과 다르지 않으면,*ppMediaType 에는 NULL 가 세트 된다.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 미디어 타입은 이전의 샘플로부터 변경되어 있지 않다.
S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.

주의

이 메소드에 의해 필터는 팔레트 변경과 같은 한정한 미디어 타입의 변경을 실시할 수가 있다. 미디어 타입의 큰 변경을 한다면, 핀은 재접속해, 미디어 타입을 재네고시에이션 할 필요가 있다.

미디어 타입의 취급이 종료하면(자),DeleteMediaType 유틸리티 함수를 호출해 메모리 블록을 해방하는 것.

IMediaSample::GetPointer

IMediaSample 인터페이스

이 버퍼의 메모리에의 읽어내/기입 포인터를 취득한다.

구문

HRESULT GetPointer(
    BYTE **ppBuffer
);

파라미터

ppBuffer
[out] 버퍼에의 포인터의 주소.

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

IMediaSample::GetSize

IMediaSample 인터페이스

버퍼의 사이즈를 취득한다.

구문

ling GetSize(void);

반환값

버퍼의 사이즈를 돌려주는, 바이트 단위.

IMediaSample::GetTime

IMediaSample 인터페이스

이 샘플이 시작 및 종료해야 할 스트림 타임을 취득한다.

구문

HRESULT GetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

파라미터

pTimeStart
[out] 시작 스트림 타임을 받는 변수에의 포인터.
pTimeEnd
[out] 종료 스트림 타임을 받는 변수에의 포인터. 샘플에 종료 타임이 없는 경우, 이 값에는 시작 타임에 1 을 더한 값이 설정된다.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공. 샘플은 유효한 시작 타임과 종료 타임을 가진다.
VFW_S_NO_STOP_TIME | 샘플은 유효한 시작 타임을 가지지만, 종료 타임을 가지지 않는다.
VFW_E_SAMPLE_TIME_NOT_SET | 샘플은 타임 스탬프를 가지지 않는다.

주의

스트림 타임의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

IMediaSample::IsDiscontinuity

IMediaSample 인터페이스

이 샘플이 데이터 스트림내에서 브레이크를 표시할지 어떨지를 확인한다.

구문

HRESULT IsDiscontinuity(void);

반환값

샘플이 데이터 스트림내에 브레이크를 가지고 있다면 S_OK 를 돌려준다. 그렇지 않으면 S_FALSE 를 돌려준다.

주의

필터가 스트림내가 다른 장소를 시크 하면 와, 혹은 필터가 품질 컨트롤을 위해서(때문에) 샘플을 드롭 하면 와, 불연속이 일어난다.

IMediaSample::IsPreroll

IMediaSample 인터페이스

이 샘플이 프리로르산풀인가 어떤가를 확인한다.

구문

HRESULT IsPreroll(void);

반환값

샘플이 프리로르산풀의 경우는 S_OK 를 돌려주어, 그렇지 않으면 S_FALSE 를 돌려준다.

주의

프리로르산풀은 처리되지만 표시는 되지 않는다. 그것은 미디어 스트림내에서 표시하는 샘플의 전에 있다.

IMediaSample::IsSyncPoint

IMediaSample 인터페이스

이 샘플의 시작이 동기 포인트인가 어떤가를 판단한다.

구문

HRESULT IsSyncPoint(void);

반환값

샘플이 동기 포인트의 경우는 S_OK 를 돌려준다. 그렇지 않으면 S_FALSE 를 돌려준다.

주의

필터는 동기 포인트로 스트림을 시작 할 수 있다. 몇개의 압축 타입에서는 스트리밍은 스트림내가 있는 포인터로부터 밖에 시작 할 수 없는, 예를 들어 키 프레임으로부터. AM_MEDIA_TYPE 구조체의 bTemporalCompression 멤버가 FALSE 라면, 모든 샘플이 동기 포인트이다.

IMediaSample::SetActualDataLength

IMediaSample 인터페이스

버퍼내의 유효한 데이터의 길이를 설정한다.

구문

HRESULT SetActualDataLength(
    long lLen
);

파라미터

lLen
미디어 샘플의 데이터의 길이 (바이트 단위).

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_BUFFER_OVERFLOW . | lLen 로 지정된 길이가 버퍼 사이즈보다 길다.

IMediaSample::SetDiscontinuity

IMediaSample 인터페이스

이 샘플이 데이터 스트림내에서 브레이크를 표시할지 어떨지를 지정한다.

구문

HRESULT SetDiscontinuity(
    BOOL bIsDiscontinuity
);

파라미터

bIsDiscontinuity
[in] 이 샘플이 불연속인가 어떤가를 나타내는 불리언 값. TRUE 라면, 미디어 샘플은 이전의 샘플과 불연속이다.

반환값

S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 를 돌려준다.

참조

IMediaSample::IsDiscontinuity

IMediaSample::SetMediaTime

IMediaSample 인터페이스

이 샘플의 미디어 타임을 설정한다.

구문

HRESULT SetMediaTime(
    LONGLONG *pTimeStart,
    LONGLONG *pTimeEnd
);

파라미터

pTimeStart
[in] 시작 미디어 타임에의 포인터.
pTimeEnd
[in] 종료 미디어 타임에의 포인터.

반환값

S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 를 돌려준다.

주의

미디어 타임을 무효로 하려면 ,pTimeStart 와 pTimeEnd 를 NULL 로 설정한다. 이것에 의해 IMediaSample::GetMediaTime 메소드는 VFW_E_MEDIA_TIME_NOT_SET 를 돌려준다.

미디어 타임의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

IMediaSample::SetMediaType

IMediaSample 인터페이스

샘플의 미디어 타입을 설정한다

구문

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pMediaType
);

파라미터

pMediaType
미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.

주의

디폴트에서는, 모든 샘플은 전의 샘플과 같은 미디어 타입을 가진다 (핀 접속이 오리지날의 미디어 타입을 결정한다). 이 메소드를 호출하는 것에 의해 필터는 팔레트 변경과 같은 한정한 미디어 타입의 변경을 실시할 수가 있다. 미디어 타입의 큰 변경을 한다면, 핀은 재접속해, 미디어 타입을 재네고시에이션 할 필요가 있다.

IMediaSample::SetPreroll

IMediaSample 인터페이스

이 샘플이 프리로르산풀인가 어떤가를 지정한다.

구문

HRESULT SetPreroll(
    BOOL bIsPreroll
);

파라미터

bIsPreroll
이것이 프리로르산풀인가 어떤가를 나타내는 불리언 값. TRUE 라면 이것은 프리로르산풀.

반환값

S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

참조

IMediaSample::IsPreroll

IMediaSample::SetSyncPoint

IMediaSample 인터페이스

이 샘플의 시작이 동기 포인트인가 어떤가를 설정한다.

구문

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

파라미터

bIsSyncPoint
[in] 이것이 동기 포인트인가 어떤가를 나타내는 불리언 값. TRUE 라면 이것은 동기 포인트.

반환값

S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

참조

IMediaSample::IsSyncPoint

IMediaSample::SetTime

IMediaSample 인터페이스

이 샘플이 시작 및 종료해야 할 스트림 타임을 설정한다.

구문

HRESULT SetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

파라미터

pTimeStart
[in] 샘플의 시작 스트림 타임에의 포인터, 100 나노초단위.
pTimeEnd
[in] 샘플의 종료 스트림 타임에의 포인터, 100 나노초단위.

반환값

S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

미디어 타임을 무효로 하려면 ,pTimeStart 와 pTimeEnd 를 NULL 로 설정한다. 이것에 의해 IMediaSample::GetTime 메소드는 VFW_E_SAMPLE_TIME_NOT_SET 를 돌려준다.

스트림 타임의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.


IMediaSample2 인터페이스

미디어 샘플의 프로퍼티를 세트 해 취득한다. 이 인터페이스는 IMediaSample 인터페이스를 계승한다. IMediaSample 인터페이스는 각 샘플 프로퍼티에 다른 메소드 호출을 요구한다. IMediaSample2 인터페이스는 복수의 프로퍼티를 한 번에 세트 혹은 취득할 수 있는 메소드를 추가한다.

미디어 샘플은 IMediaSample2 의 지원을 보증하고 있지 않다. 그러나 allocater가 IMediaSample2 를 지원 하는 샘플을 생성 하면, 그것이 지원 하는 모든 샘플은 그 인터페이스를 지원 해야 한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaSample 메소드 | 설명
GetPointer | 이 버퍼의 메모리에의 읽어내/기입 포인터를 취득한다.
GetSize | 버퍼의 사이즈를 취득한다.
GetTime | 이 샘플이 시작 및 종료해야 할스트림 타임을 취득한다.
SetTime | 이 샘플이 시작 및 종료해야 할 스트림 타임을 설정한다.
IsSyncPoint | 샘플의 시작이 동기 포인트인가 어떤가를 판단한다.
SetSyncPoint | 이 샘플의 시작이 동기 포인트인가 어떤가를 지정한다.
IsPreroll | 이 샘플이 프리로르산풀인가 어떤가를 확인한다.
SetPreroll | 이 샘플이 프리로르산풀인가 어떤가를 설정한다.
GetActualDataLength | 버퍼내의 유효한 데이터의 길이를 취득한다.
SetActualDataLength | 버퍼내의 유효한 데이터의 길이를 설정한다.
GetMediaType | 미디어 타입이 이전의 샘플과 다르다면, 미디어 타입을 취득한다.
SetMediaType | 샘플의 미디어 타입을 설정한다.
IsDiscontinuity | 이 샘플이 데이터 스트림내에서 브레이크를 표시할지 어떨지를 확인한다.
SetDiscontinuity | 이 샘플이 데이터 스트림내에서 브레이크를 표시할지 어떨지를 지정한다.
GetMediaTime | 이 샘플의 미디어 타임을 취득한다.
SetMediaTime | 이 샘플의 미디어 타임을 설정한다. 정한다.
IMediaSample2 메소드 | 설명
GetProperties | 미디어 샘플의 프로퍼티를 취득한다.
SetProperties | 미디어 샘플의 프로퍼티를 설정한다.

IMediaSample2::GetProperties

IMediaSample2 인터페이스

미디어 샘플의 프로퍼티를 취득한다.

구문

HRESULT GetProperties(
    DWORD cbProperties,
    BYTE *pbProperties
    );

파라미터

cbProperties
[in] 취득하는 프로퍼티 데이터의 길이 (바이트 단위).
pbProperties
[out] cbProperties 사이즈의 버퍼에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

주의

받은 데이터는 AM_SAMPLE2_PROPERTIES 구조체의 포맷에 따른다. cbProperties 를 AM_SAMPLE2_PROPERTIES 구조체의 사이즈보다 작은 값에 세트 하면, 샘플 프로퍼티의 서브 세트를 취득할 수가 있다.

효율이기 때문에, AM_SAMPLE2_PROPERTIES 에 돌아가는 pMediaType 멤버는 미디어 샘플에 스토어 되고 있는 데이터의 포인터이며, 그 데이터의 카피는 아니다. 샘플이 다른 필터에게 건네진 후, 혹은 입력 핀의 IMemInputPin::Receive 메소드가 완료한 다음에는, 그 포인터는 무효가 될 가능성이 있다. 또 미디어 타입을 해방 혹은 삭제해서는 안 된다.

IMediaSample2::SetProperties

IMediaSample2 인터페이스

미디어 샘플의 프로퍼티를 설정한다.

구문

HRESULT SetProperties(
    DWORD cbProperties,
    const BYTE *pbProperties
    );

파라미터

cbProperties
[in] 설정하는 프로퍼티 데이터의 길이 (바이트 단위).
pbProperties
[in] cbProperties 사이즈의 버퍼에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_INVALIDARG | 부적절한 인수.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

pbProperties 내에 접어드는 데이터는 AM_SAMPLE2_PROPERTIES 구조체의 포맷에 따르지 않으면 안 된다. cbProperties 를 AM_SAMPLE2_PROPERTIES 구조체의 사이즈보다 작은 값에 세트 하면, 샘플 프로퍼티의 서브 세트를 지정할 수가 있다.


IMediaSeeking 인터페이스

스트림내의 위치에 시크 하는 메소드와 재생 레이트를 설정하는 메소드가 포함된다.

필터 그래프 매니저는, 개개의 필터와 같이, 이 인터페이스를 공개한다. 어플리케이션은 필터로부터는 아니고, 필터 그래프 매니저로부터 이 인터페이스를 취득할 필요가 있다. 필터 그래프 매니저는, 메소드를 모든 렌더링 필터에 할당한다. 렌더링 필터는, 그 호출을 소스 필터에의 업 스트림에 보낸다. 모든 스트림은, 이벤트의 이 순서에 의해 동기 된다.

배포되고 싶은 차이인가의 호출이 에러를 돌려주었을 경우, 필터 그래프 매니저는, 배포된 호출의 일부가 성공했을 경우에서도, 최초로 받은 에러값을 돌려준다. 이 예외에는, E_NOTIMPL 가 있다. 필터 그래프 매니저는, 배포된 모든 호출이 E_NOTIMPL 를 돌려주지 않는 이상 E_NOTIMPL 를 돌려주지 않는다.

그래프가 어느 상태 (실행중, 포즈, 정지중)에 있어도, 어플리케이션은 그래프를 시크 할 수 있다. 그래프가 실행중의 경우, 필터 그래프 매니저는 시크 커멘드를 처리하기 전에 그래프를 포즈 한다. 그 후, 그래프를 재차 실행 상태로 한다. 모든 시크 조작은, 현재의 재생 레이트에는 의존하지 않는다. 시크 조작에 의해 남아 있는 미디어 데이터는, 그래프로부터 플래시 된다.

이 인터페이스는,IMediaPosition 인터페이스보다 강화되고 있다. IMediaPosition 의 메소드에서는, 콤마초단위의 타임 파라미터를 필요로 하는데 대해,IMediaSeeking 메소드에서는, 프레임, 바이트, 100 나노초단위 등 임의의 포맷을 사용할 수 있다. 또,IMediaSeeking 는 보다 높은 정밀도를 제공하기 위해서, 64 비트 정수 (LONGLONG )를 사용한다. 한편,IMediaSeeking 는 Automation 와 호환성이 없기 때문에, Microsoft® Visual Basic® 로 쓰여진 어플리케이션은 IMediaPosition 를 사용해야 한다.

타임 및 타임의 단위를 지정하는 IMediaSeeking 의 모든 파라미터는, 현재 사용중의 타임 포맷에는 의존하지 않는다. 타임 포맷을 설정하려면 ,IMediaSeeking::SetTimeFormat 를 호출한다. 타임 포맷은, uuids.h 로 정의되고 있는 글로벌하게 일의의 식별자 (GUID)이다. 상세한 것에 대하여는, 「타임 포맷 GUID 」를 참조할것.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaSeeking 메소드 | 설명
GetCapabilities | 스트림의 모든 시크 능력을 취득한다.
CheckCapabilities | 지정한 시크 능력을 스트림이 가지고 있을지 어떨지를 조회한다.
IsFormatSupported | 지정한 타임 포맷을 스트림이 지원 하고 있을지 어떨지를 확인한다.
QueryPreferredFormat | 스트림의 우선 타임 포맷을 취득한다.
GetTimeFormat | 현재의 타임 포맷을 취득한다.
IsUsingTimeFormat | 지정한 타임 포맷이 현재 사용중의 포맷화 제발을 확인한다.
SetTimeFormat | 타임 포맷을 설정한다.
GetDuration | 스트림의 시간폭을 취득한다.
GetStopPosition | 스트림의 시간폭에 대해서, 재생이 정지하는 타임을 취득한다.
GetCurrentPosition | 스트림의 시간폭에 대한 현재의 위치를 취득한다.
ConvertTimeFormat | 있는 타임 포맷을 다른 포맷으로 변환한다.
SetPositions | 현재의 위치와 정지 위치를 설정한다.
GetPositions | 스트림의 시간폭에 대한, 현재의 위치와 정지 위치를 취득한다.
GetAvailable | 시크가 유효한 타임의 범위를 취득한다.
SetRate | 재생 레이트를 설정한다.
GetRate | 재생 레이트를 취득한다.
GetPreroll | 시작 위치전에 큐에 들어가 있는 데이터의 양을 취득한다.

IMediaSeeking::CheckCapabilities

IMediaSeeking 인터페이스

지정한 시크 능력을 스트림이 가지고 있을지 어떨지를 조회한다.

구문

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

파라미터

pCapabilities
[in, out] AM_SEEKING_SEEKING_CAPABILITIES 속성의 1 개 또는 복수의 비트마다의 편성에의 포인터. 메소드의 반환값은, 어느 속성이 이용 가능한가를 나타낸다.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_FALSE | pCapabilities 의 모든 능력을 가지지는 않았다.
S_OK | pCapabilities 의 모든 능력이 있다.
E_FAIL | pCapabilities 의 능력이 전혀 없다.
E_POINTER | NULL 포인터 인수.

주의

2 ~ 3 의 능력만이 필요한 경우, 모든 스트림의 시크 능력을 체크하는 GetCapabilities 를 호출하는 것보다도, 이 메소드가 효율적이다.

테스트하는 AM_SEEKING_SEEKING_CAPABILITIES 속성의 비트마다의 OR 편성과 동일한 DWORD 를 선언해,pCapabilities 파라미터에 이 값의 포인터를 건네준다. 메소드가 돌아가면(자),pCapabilities 에는 원의 비트의 서브 세트가 들어가, 실제로 어느 능력이 있는지를 나타낸다. 반환값은, 요구한 능력이 없는, 몇개인가 있다, 또는 모두 있는 것을 나타내는 값을 돌려준다.

다음의 코드 샘플은, 스트림이 순서 방향 시크, 역방향 시크, 및 절대 시크를 지원 하고 있을지 어떨지를 조사하는 방법을 나타내고 있다.

// 체크하는 능력의 플래그를 설정한다.
DWORD dwCaps = AM_SEEKING_CanSeekAbsolute |
             AM_SEEKING_CanSeekForwards |
             AM_SEEKING_CanSeekBackwards;

HRESULT hr = pMediaSeeking->CheckCapabilities(&dwCaps);
if(FAILED(hr))
{
    // 스트림에서는 시크는 할 수 없다.
}
else if (hr == S_OK)
{
    // 스트림에서는, 순서 방향 시크, 역방향 시크, 및 절대 시크가 생긴다.
}
else if (hr == S_FALSE) // 스트림은 몇개의 능력을 가질 가능성이 있다.
{
    if (dwCaps & AM_SEEKING_CanSeekAbsolute)
        // 스트림은 절대 위치에의 시크가 생긴다.
    if dwCaps & AM_SEEKING_CanSeekAbsolute)
        // 스트림은 순서 방향에의 시크가 생긴다.
    if (dwCaps & AM_SEEKING_CanSeekBackwards)
        // 스트림은 역방향에의 시크가 생긴다.
}

IMediaSeeking::ConvertTimeFormat

IMediaSeeking 인터페이스

어느 타임 포맷을 다른 포맷으로 변환한다.

구문

HRESULT ConvertTimeFormat(
    LONGLONG *pTarget,
    const GUID *pTargetFormat,
    LONGLONG Source,
    const GUID *pSourceFormat
);

파라미터

pTarget
[out] 변환한 타임값을 받는 변수에의 포인터.
pTargetFormat
[in] 목적의 포맷의타임 포맷 GUID 에의 포인터. NULL 의 경우는, 현재의 포맷이 사용된다.
Source
[in] 변환되는 타임값.
pSourceFormat
[in] 변환하는 포맷의타임 포맷 GUID 에의 포인터. NULL 의 경우는, 현재의 타임 포맷이 사용된다.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_INVALIDARG | 이 타입간의 변환은 지원되어 있지 않다.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

IMediaSeeking::GetAvailable

IMediaSeeking 인터페이스

시크가 유효한 타임의 범위를 취득한다.

구문

HRESULT GetAvailable(
    LONGLONG *pEarliest,
    LONGLONG *pLatest
);

파라미터

pEarliest
[out] 시크가 유효한, 가장 빠른 타임을 받는 변수에의 포인터.
pLatest
[out] 시크가 유효한, 가장 늦은 타임을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는, 주로 네트워크를 넘어 보내져 오는 것 같은, 지연의 큰 미디어 스트림에서의 시크를 대상으로 하고 있다. 반환값은, 용이하게 시크 가능한, 이미 도착 끝난 캐쉬 데이터를 나타낸다. 돌려주어진 파라미터를 넘은 값을 시크 하면, 어플리케이션이 데이터의 도착을 기다리는 동안, 지연이 발생하는 것이 상정되고 있다.

IMediaSeeking::GetCapabilities

IMediaSeeking 인터페이스

스트림의 모든 시크 능력을 취득한다.

구문

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

파라미터

pCapabilities
[out] AM_SEEKING_SEEKING_CAPABILITIES 플래그의 비트마다의 편성을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는, 스트림의 모든 시크 능력에 관한 정보를 돌려준다. 필요한 AM_SEEKING_SEEKING_CAPABILITIES 값에 대해, 비트마다의 AND 조작을 실시해,pCapabilities 를 조사하는 것.

DWORD dwCaps = 0;
pMediaSeeking->GetCapabilities(&dwCaps);

if (dwCaps & AM_SEEKING_CanGetCurrentPos)
{
    // 스트림에서는 현재 위치에의 시크가 생긴다.
}
if (dwCaps & AM_SEEKING_CanPlayBackwards)
{
    // 스트림에서는 재생역방향에의 시크가 생긴다.
}

IMediaSeeking::GetCurrentPosition

IMediaSeeking 인터페이스

스트림의 합계 시간폭에 대한 현재의 위치를 취득한다.

구문

HRESULT GetCurrentPosition(
    LONGLONG *pCurrent
);

파라미터

pCurrent
[out] 현재 위치를 취득하는 변수에의 포인터 (현재의 타임 포맷의 단위).

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는, 재생이 도달한 현재 위치를 돌려준다. 이 값에서는, 재생 레이트와 시작 타임은 무시된다. 예를 들어, 레이트에 2.0 을 설정해, 시작 타임이 5 초라면 하면, 그래프를 4 초 실행 하면 현재의 위치는 9.0 초가 된다 (5 + 4 × 2.0). 반환값은, 현재의 타임 포맷의 단위로 나타내진다. 현재의 타임 포맷을 확인하려면 ,GetTimeFormat 메소드를 호출하는 것.

그래프가 포즈 또는 정지되고 있는 경우, 현재 위치는 재생이 재개되는 포인트가 된다.

필터 그래프 매니저는, 현재의 스트림 타임부터 위치를 계산하므로, 그래프의 필터에 조회할 것은 없다. 파일의 재생에서는, 이것에 의해 재생이 스트림 타임에 동기 되기 (위해)때문에, 정확한 결과를 얻을 수 있다. 파일의 기입에서는, 결과는 정확하게는 안 된다. 파일을 기입하는 그래프로 현재의 위치를 취득하려면 , 멀티플렉서 필터에 조회하는 것. 다만, 라이브 캡춰에서는, 위치는 적절한 것은 되지 않는다.

IMediaSeeking::GetDuration

IMediaSeeking 인터페이스

스트림의 시간폭을 취득한다.

구문

HRESULT GetDuration(
    LONGLONG *pDuration
);

파라미터

pDuration
[out] 시간폭을 받는 변수에의 포인터 (현재의 타임 포맷의 단위).

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는, 보통, 재생 속도에서의 시간폭을 취득한다. 재생 레이트는 이 시간폭에는 영향을 주지 않는다. 반환값은 현재의 타임 포맷 단위로 나타내진다. 현재의 타임 포맷을 확인하려면 ,GetTimeFormat 메소드를 호출하는 것.

IMediaSeeking::GetPositions

IMediaSeeking 인터페이스

스트림의 합계 시간폭에 대한, 현재의 위치와 정지 위치를 취득한다.

구문

HRESULT GetPositions(
    LONGLONG *pCurrent,
    LONGLONG *pStop
);

파라미터

pCurrent
[out] 현재 위치를 받는 변수에의 포인터 (현재의 타임 포맷의 단위).
pStop
[out] 정지 위치를 받는 변수에의 포인터 (현재의 타임 포맷의 단위).

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

현재 위치와 정지 위치는, 양쪽 모두 원의 스트림에 대한 값이며, 재생 레이트에는 의존하지 않는다.

반환값은, 현재의 타임 포맷 단위로 나타내진다. 현재의 타임 포맷을 확인하려면 ,GetTimeFormat 메소드를 호출하는 것.

IMediaSeeking::GetPreroll

IMediaSeeking 인터페이스

시작 위치전에 큐에 들어가 있는 데이터의 양을 취득한다.

구문

HRESULT GetPreroll(
    LONGLONG *pllPreroll
);

파라미터

pllPreroll
[out] 프리로르타임을 받는 변수에의 포인터 (현재의 타임 포맷의 단위).

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

프리로르는, 테이프 플레이어와 같은 비랜덤 억세스 디바이스로, 롤링이 시작 되는 시작 위치보다 전의 타임이다.

IMediaSeeking::GetRate

IMediaSeeking 인터페이스

재생 레이트를 취득한다.

구문

HRESULT GetRate(
    double *dRate
);

파라미터

dRate
[out] 재생 레이트를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

재생 레이트는, 보통, 속도와의 비율로 나타내진다. 따라서, 1.0 은 보통의 재생 속도, 0.5 는 반의 속도, 2.0 은 2 배의 속도를 나타낸다.

IMediaSeeking::GetStopPosition

IMediaSeeking 인터페이스

스트림의 시간폭에 대해서, 재생이 정지하는 타임을 취득한다.

구문

HRESULT GetStopPosition(
    LONGLONG *pStop
);

파라미터

pStop
[out] 정지 위치를 받는 변수에의 포인터 (현재의 타임 포맷의 단위).

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

재생 레이트는, 이 메소드에 의해 돌아가는 값에 영향을 주지 않는다. 반환값은, 현재의 타임 포맷 단위로 나타내진다. 현재의 타임 포맷을 확인하려면 ,GetTimeFormat 메소드를 호출하는 것.

IMediaSeeking::GetTimeFormat

IMediaSeeking 인터페이스

현재의 타임 포맷을 취득한다.

구문

HRESULT GetTimeFormat(
    GUID *pFormat
);

파라미터

pFormat
[out] 타임 포맷 GUID 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

IMediaSeeking::IsFormatSupported

IMediaSeeking 인터페이스

지정한 타임 포맷을 스트림이 지원 하고 있을지 어떨지를 확인한다.

구문

HRESULT IsFormatSupported(
    const GUID *pFormat
);

파라미터

pFormat
[in] 타임 포맷 GUID 에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_FALSE | 포맷은 지원되어 있지 않다.
S_OK | 포맷은 지원 되고 있다.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

IMediaSeeking::IsUsingTimeFormat

IMediaSeeking 인터페이스

지정한 타임 포맷이 현재 사용중의 포맷화 제발을 확인한다.

구문

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

파라미터

pFormat
[in] 타임 포맷 GUID 에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_FALSE | 지정한 포맷은 현재의 포맷은 아니다.
S_OK | 지정한 포맷은 현재의 포맷이다.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는 GUID 를 카피할 필요가 없기 때문에,IMediaSeeking::GetTimeFormat 메소드보다 효율적이다.

IMediaSeeking::QueryPreferredFormat

IMediaSeeking 인터페이스

스트림의 우선 타임 포맷을 취득한다.

구문

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

파라미터

pFormat
[out] 타임 포맷 GUID 에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

돌려주어진 포맷이 불충분한 경우는,IsFormatSupported 메소드를 호출해, 그 밖에 지원 되고 있는 타임 포맷을 조회하는 것.

IMediaSeeking::SetPositions

IMediaSeeking 인터페이스

현재의 위치와 정지 위치를 설정한다.

구문

HRESULT SetPositions(
    LONGLONG *pCurrent,
    DWORD dwCurrentFlags,
    LONGLONG *pStop,
    DWORD dwStopFlags
);

파라미터

pCurrent
[in, out] 현재의 타임을 지정하는 변수에의 포인터 (현재의 타임 포맷의 단위).
dwCurrentFlags
[in] 플래그의 비트마다의 편성 ( 「주의」를 참조).
pStop
[in, out] 현재의 타임을 지정하는 변수에의 포인터 (현재의 타임 포맷의 단위).
dwStopFlags
[in] 플래그의 비트마다의 편성 ( 「주의」를 참조).

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_FALSE | 위치 변경은 없다(양쪽 모두의 플래그가 시크 하지 않으면 지정).
S_OK | 성공.
E_INVALIDARG | 부적절한 인수.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

dwCurrentFlags 파라미터와 dwStopFlags 파라미터에는, 시크 타입을 정의한다. 다음의 플래그가 정의되고 있다.

위치 플래그
AM_SEEKING_NoPositioning | 위치의 변경은 없다. 타임 파라미터는, NULL 로 할 수도 있다.
AM_SEEKING_AbsolutePositioning | 지정한 위치는 절대치이다.
AM_SEEKING_RelativePositioning | 지정한 위치는 이전의 값으로부터의 상대값이다.
AM_SEEKING_IncrementalPositioning | 정지 위치 (pStop)는 현재 위치 (pCurrent)로부터의 상대값이다.
수식 플래그
AM_SEEKING_SeekToKeyFrame | 가장 가까운 키 프레임을 시크 한다. 이것은 고속이지만, 정밀도는 떨어진다.
AM_SEEKING_ReturnTime | 동일한 기준 타임을 돌려준다.
AM_SEEKING_Segment | 세그먼트(segment) 시크를 사용한다.
AM_SEEKING_NoFlush | 플래시 하지 않는다.

각 파라미터에 대해서, 1 개의 위치 플래그를 사용한다. 1 개(살) 또는 복수의 수식자 플래그를 포함할 수도 있다.

AM_SEEKING_ReturnTime 플래그가 지정되면(자), 메소드는 그 위치의 값을 기준 타임으로 변환해,pCurrent 변수 또는 pStop 변수로 돌려준다. 프레임과 같은 다른 타임 포맷을 사용하고 있을 때, 이 플래그는 유용하다.

AM_SEEKING_Segment 와 AM_SEEKING_NoFlush 플래그는, 심리스 루프를 지원 한다.

  • AM_SEEKING_Segment 가 존재하는 경우, 소스 필터는 정지 위치에 도달했을 때에,IPin::EndOfStream 를 호출하는 대신에 EC_END_OF_SEGMENT 이벤트를 보낸다. 어플리케이션은 이 이벤트를 기다려, 이제(벌써) 1 개의 시크 커멘드를 처리할 수가 있다.
  • AM_SEEKING_NoFlush 가 존재하는 경우, 그래프는 시크중에 데이터를 플래시 하지 않는다. 이 플래그는 AM_SEEKING_Segment 와 함께 사용한다.

루프를 실행하기 위해서는, 그래프는 GetCapabilities 메소드의 AM_SEEKING_CanDoSegments 를 보고하지 않으면 안 된다. 현재, 이 기능을 지원 하고 있는 것은 WAVE 퍼서 필터 뿐이다.

IMediaSeeking::SetRate

IMediaSeeking 인터페이스

재생 레이트를 설정한다.

구문

HRESULT SetRate(
    double dRate
);

파라미터

dRate
[in] 재생 레이트. 제로여서는 안 된다.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_INVALIDARG | 지정된 레이트는, 0 또는 부의 값이었다 ( 「주의」를 참조).
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.
VFW_E_UNSUPPORTED_AUDIO | 오디오 디바이스 혹은 필터가 이 레이트를 지원 하고 있지 않다.

주의

재생 레이트는, 보통, 속도와의 비율로 나타내진다. 따라서, 1.0 은 보통의 재생 속도, 0.5 는 반의 속도, 2.0 은 2 배의 속도를 나타낸다. 오디오 스트림에 대해서는, 레이트를 바꾸면(자) 피치도 바뀐다.

마이너스값은 역재생을 나타낸다. 대부분의 필터는 역재생을 지원 하지 않는, 대신에 dRate 파라미터가 마이너스라면 에러 코드를 돌려준다.

어플리케이션이 이 메소드를 필터 그래프 매니저로 호출하면, 필터 그래프 매니저는 이하의 일을 실시한다 :

  1. GetCurrentPosition 메소드를 호출한다. 이 호출에 의해 필터 그래프 매니저가 계산한 현재 위치를 돌려준다.
  2. (그래프가 포즈 혹은 실행중이라면) 필터 그래프를 정지한다.
  3. 현재 위치를 시작 타임으로서SetPositions 메소드를 호출한다. 이것은 스트림 타임을 제로에 리셋 하는 결과가 된다.
  4. 새로운 레이트로, 필터의 SetRate 메소드를 호출한다.
  5. 포즈 혹은 실행중이었다라면, 필터 그래프를 재개한다.

스텝 4 로 에러가 일어나면(자), 필터 그래프 매니저는 이전의 레이트를 다시 사용하려고 한다.

필터는 이하와 같이 레이트 변경에 대응해야 한다 :

퍼서 필터와 소스 필터 : 타임 스탬프를 발생시키고 있는 필터는 SetRate 호출에 대응해야 한다. 보통 이것은 AVI 스플리터 와 같은 퍼서 필터이지만, 소스 필터의 경우도 있다. 시크나 레이트 변경의 뒤, 필터는 IPin::NewSegment 메소드를 새로운 설정으로 호출해야 하는 것이다. 레이트 변경의 뒤, 그 타임 스탬프를 거기에 따라서 조정해야 한다. 레이트 변경은 시크에 우선하므로, 타임 스탬프는 제로로부터 재스타트가 되는, 따라서 필터는 그 레이트로 나눈 새로운 타임 스탬프를 계산할 수가 있다.

디코더 필터 : 디코더는 SetRate 호출에 대해서, 그것들을 업 스트림에 건네주는 이외를 해서는 안된다. 그렇지 않고, 디코더는 업 스트림 퍼서가 내는 NewSegment 호출에 대응해야 한다. 디코더 필터가 새로운 세그먼트(segment) 정보를 받을 때, 그 필터는 그 값을 보존해,NewSegment 호출 다운 스트림에 건네준다. 몇개의 디코더는 그 입력을 보간 하는 것에 의해 추가 타임 스탬프를 생성할 필요가 있다, 그렇다면 나무 어카운트내로 레이트 변경을 건네주어야 하는 것이다.

렌더러 : 비디오 렌더러는 보통 레이트 변경을 무시할 수 있다, 왜냐하면 들어 오는 프레임은 이미 올바른 타임 스탬프를 가지고 있기 때문이다. 오디오 렌더러는 그 재생 레이트를 변경해야 하는, 왜냐하면 오디오 디코더는 보통 레이트 변경 변환을 하지 않기 때문에이다.

IMediaSeeking::SetTimeFormat

IMediaSeeking 인터페이스

타임 포맷을 설정한다.

구문

HRESULT SetTimeFormat(
    const GUID *pFormat
);

파라미터

pFormat
[in] 타임 포맷 GUID 에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_INVALIDARG | 부적절한 인수.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.
VFW_E_WRONG_STATE | 필터 그래프가 정지하고 있지 않다.

주의

이 메소드는,GetPositions 나 SetPositions 등, 다른 IMediaSeeking 메소드를 사용해 타임의 단위를 지정한다. 어느 포맷이 지원 되고 있는지를 확인하려면 ,IsFormatSupported 메소드를 호출하는 것. 현재의 타임 포맷을 취득하려면 ,GetTimeFormat 메소드를 호출해, 우선 타임 포맷을 취득하려면 ,QueryPreferredFormat 메소드를 호출하는 것.

필터 그래프에는, 한 번에 1 개의 타임 포맷 밖에 설정할 수 없다.


IMediaTypeInfo 인터페이스

이 인터페이스는, 핀 접속의 미디어 타입을 취득하는 Automation 호환의 메소드를 제공한다.

Microsoft® Visual Basic® 어플리케이션에서는, 이 인터페이스를 사용해, 핀 접속의 미디어 타입을 취득할 수 있다. IPinInfo::get_ConnectionMediaType 메소드는, 이 인터페이스를 지원 하는 오브젝트를 돌려준다. 메이저 타입 GUID 및 마이너 타입 GUID 는, 이 오브젝트의 프로퍼티로서 취득된다.

C/C++ 어플리케이션에서는, 이 메소드는 아니고,IPin::ConnectionMediaType 메소드를 호출하는 것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IMediaTypeInfo 메소드 | 설명
get_Type | GUID 를 캐릭터 라인으로 취득한다.
get_Subtype | 서브 타입 GUID 를 캐릭터 라인으로 취득한다.

IMediaTypeInfo::get_Subtype

IMediaTypeInfo 인터페이스

서브 타입 GUID 를 캐릭터 라인으로 취득한다.

구문

HRESULT get_Subtype(
    BSTR *strType
);

파라미터

strType
[out, retval] 서브 타입 GUID 가 저장 된 캐릭터 라인에의 포인터.

반환값

HRESULT 값을 돌려준다.

IMediaTypeInfo::get_Type

IMediaTypeInfo 인터페이스

메이저 타입 GUID 를 캐릭터 라인으로 취득한다.

구문

HRESULT get_Type(
    BSTR *strType
);

파라미터

strType
[out, retval] 메이저 타입 GUID 가 저장 된 캐릭터 라인에의 포인터.

반환값

HRESULT 값을 돌려준다.


IMemAllocator 인터페이스

핀간에 데이터를 이동시키기 위해서(때문에), 미디어 샘플을 할당한다.

입력 핀이 IMemInputPin 인터페이스를 공개 하면 와, allocater를 공유하는 핀에 의해 이 인터페이스는 사용된다. 그 핀은 어느 핀이 allocater를 제공할까를 네고시에이트 한다. allocater를 사용해, 메모리 버퍼를 할당해로부터의 버퍼를 취득해, 버퍼를 해방한다. 모든 필터가 그것 자신의 allocater를 생성 하는 것은 아니기 때문에, 1 개의 allocater를 복수의 필터가 사용하는 경우도 있다. 상세한 것에 대하여는, 「필터의 접속」을 참조할것.

어플리케이션은 보통 이 인터페이스를 사용하지 않는다.

allocater를 사용하려면 다음의 스텝을 실시한다.

  1. IMemAllocator::SetProperties 메소드를 호출해, 버퍼의 수와 각 버퍼의 사이즈를 포함한 버퍼 요구를 지정한다.
  2. IMemAllocator::Commit 메소드를 호출해, 버퍼를 할당한다.
  3. Call IMemAllocator::GetBuffer 메소드를 호출해, 미디어 샘플을 취득한다. 이 메소드는 다음의 샘플이 유효하게 될 때까지 블록 한다.
  4. 각 샘플에 대해 종료했을 때, 샘플로 IUnknown::Release 메소드를 호출한다. 샘플은 그 참조 카운트가 제로가 되어도 삭제되지 않는다. 대신에, 샘플은 allocater의 면세표를 돌려준다.
  5. 그 allocater의 사용이 끝났을 때,IMemAllocator::Decommit 메소드를 호출해 버퍼용의 메모리를 해방한다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMemAllocator 메소드 | 설명
SetProperties | 할당하는 버퍼의 수와 각 버퍼의 사이즈를 지정한다.
GetProperties | allocater가 생성 하는 버퍼의 수와 버퍼의 프로퍼티를 취득한다.
Commit | 버퍼 메모리를 할당한다.
Decommit | 버퍼용의 메모리를 해방한다.
GetBuffer | 컬러의 버퍼를 가지는 미디어 샘플을 취득한다.
ReleaseBuffer | 미디어 샘플을 해방한다.

IMemAllocator::Commit

IMemAllocator 인터페이스

버퍼 메모리를 할당한다.

구문

HRESULT Commit(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_SIZENOTSET | 버퍼 요구는 세트 되지 않았다.

주의

이 메소드를 호출하기 전에,IMemAllocator::SetProperties 메소드를 호출해 버퍼 요구를 지정하는 것.

IMemAllocator::GetBuffer 메소드를 호출하기 전에, 반드시 이 메소드를 호출하는 것.

IMemAllocator::Decommit

IMemAllocator 인터페이스

버퍼용의 메모리를 해방한다.

구문

HRESULT Decommit(void);

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

IMemAllocator::GetBuffer 메소드로 기다리고 있는 thread는 에러를 돌려준다. IMemAllocator::Commit 메소드가 불려 갈 때까지는, 이후의 GetBuffer 에의 호출은 실패한다.

IMemAllocator::GetBuffer

IMemAllocator 인터페이스

컬러의 버퍼를 가지는 미디어 샘플을 취득한다.

구문

HRESULT GetBuffer(
    IMediaSample **ppBuffer,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime,
    DWORD dwFlags
);

파라미터

ppBuffer
[out] 버퍼의 IMediaSample 인터페이스에의 포인터를 받는 변수의 주소.
pStartTime
[in] 샘플의 시작 타임에의 포인터, 혹은 NULL .
pEndTime
[in] 샘플의 종료 타임에의 포인터, 혹은 NULL .
dwFlags
[in] 제로 혹은 그 이상의 플래그의 편성.
  • AM_GBF_NOTASYNCPOINT: 이 샘플은 동기 포인트는 아니다. 이 샘플에는 동적인 포맷 변경은 허가되지 않는다.
  • AM_GBF_PREVFRAMESKIPPED: 이 샘플은 불연속 후의 최초이다. (비디오 렌더러만이 이 플래그를 사용한다)
  • AM_GBF_NOWAIT: 버퍼가 유효하게 되는 것을 기다려서는 안된다.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_NOT_COMMITTED | allocater는 데코밋트이다.
VFW_E_TIMEOUT | 타임 아웃.

주의

디폴트에서는, 이 메소드는 프리 샘플을 이용할 수 있을 때까지, 혹은 allocater가 데코밋트가 될 때까지 블록 한다. 호출원이 AM_GBF_NOWAIT 플래그를 지정해, 샘플을 이용할 수 없으면, allocater는 VFW_E_TIMEOUT 값을 되돌리자 마자 돌아간다. 그러나, allocater에 의한 이 플래그의 지원은 필수는 아니다.

ppBuffer 로 돌아가는 샘플은 이용 가능한 버퍼 포인터를 가진다. 호출원래는 샘플의 다른 프로퍼티를 설정할 책임이 있는, 그것은 예를 들어 타임 스탬프나 미디어 타임이나 동기 포인트 프로퍼티 등이다 (상세한 것에 대하여는, 「IMediaSample 」를 참조할것).

pStartTime 파라미터와 pEndTime 파라미터는 샘플에 적용되지 않는다. allocater는 이러한 값을 사용해 어느 버퍼를 취득했는지를 확인하는 경우가 있다. 예를 들어,비디오 렌더러 필터는 이러한 값을 사용해 Microsoft® DirectDraw® 서페이스와의 동기를 스윗치 한다. 샘플의 타임 스탬프를 설정하려면 IMediaSample::SetTime 메소드를 호출하는 것.

이 메소드를 호출하기 전에 IMemAllocator::Commit 메소드를 반드시 호출하지 않으면 안 된다. IMemAllocator::Decommit 메소드가 불려 간 다음에는 이 호출은 실패한다. 메소드가 성공하면(자),IMediaSample 인터페이스에는 참조 카운트가 남는다. 사용했을 때 인터페이스의 해방에 주의.

IMemAllocator::GetProperties

IMemAllocator 인터페이스

allocater가 생성 하는 버퍼의 수와 버퍼의 프로퍼티를 취득한다.

구문

HRESULT GetProperties(
    ALLOCATOR_PROPERTIES *pProps
);

파라미터

pProps
[out] allocater 프로퍼티를 받는 ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

IMemAllocator::Commit 메소드가 불려 갈 때까지, 이 메소드에의 호출은 성공하지 않는 경우가 있다.

IMemAllocator::ReleaseBuffer

IMemAllocator 인터페이스

미디어 샘플을 해방한다.

구문

HRESULT ReleaseBuffer(
    IMediaSample *pBuffer
);

파라미터

pBuffer
[in] 미디어 샘플의 IMediaSample 인터페이스에의 포인터.

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

미디어 샘플의 참조 카운트가 제로가 되면(자), 이 메소드는 pBuffer 에 그것 자신을 넣어 호출한다. 이 메소드는 샘플을 해방해, allocater의 이용 가능한 샘플의 리스트에 되돌린다.

IMemAllocator::SetProperties

IMemAllocator 인터페이스

할당하는 버퍼의 수와 각 버퍼의 사이즈를 지정한다.

구문

HRESULT SetProperties(
    ALLOCATOR_PROPERTIES *pRequest,
    ALLOCATOR_PROPERTIES *pActual
);

파라미터

pRequest
버퍼 요구가 들어가는 ALLOCATOR_PROPERTIES 구조체에의 포인터.
pActual
실제의 버퍼 프로퍼티를 받는 ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_ALREADY_COMMITTED | 필터가 액티브한 동안은 할당한 메모리를 변경할 수 없다.
VFW_E_BADALIGN | 부적절한 인수가 지정되었다.
VFW_E_BUFFERS_OUTSTANDING | 1 개(살) 이상의 버퍼가 아직 액티브.

주의

이 메소드는 버퍼 요구를 지정하지만, 버퍼를 할당하는 것은 아니다. IMemAllocator::Commit 메소드를 호출해 버퍼를 할당하는 것.

호출원래는 2 개의 ALLOCATOR_PROPERTIES 구조체를 할당한다. pRequest 파라미터에는 버퍼의 수와 각 버퍼의 사이즈를 포함한 호출원의 버퍼 요구가 들어간다. 메소드가 돌아가면(자),pActual 파라미터에는 allocater에 의해 세트 된 실제의 버퍼 프로퍼티가 들어간다.

이 메소드가 불려 갈 때, allocater는 위탁되어 있지 않으면 안 되는, 혹은 이용 가능한 버퍼를 가지고 있지 않으면 안 된다.


IMemInputPin 인터페이스

미디어 데이터를입력 핀에 출력한다. 입력 핀이 IMemAllocator 인터페이스를 사용해 버퍼를 할당하는 경우, 입력 핀은 이 인터페이스를 공개한다. 출력 핀이 입력 핀에 접속 하면, 출력 핀은 이 인터페이스를 사용해 allocater 요구를 네고시에이션 해, 입력 핀에 샘플을 출력한다.

보통, 어플리케이션은 이 인터페이스를 사용한다.

필터 개발자에게 : CBaseInputPin 클래스는 이 인터페이스를 이행 한다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMemInputPin 메소드 | 설명
GetAllocator | 이 핀이 제안한 메모리 allocater를 취득한다.
NotifyAllocator | 접속용의 allocater를 지정한다.
GetAllocatorRequirements | 입력 핀이 요구한 allocater 프로퍼티를 취득한다.
Receive | 스트림내의 다음의 미디어 샘플을 취득한다.
ReceiveMultiple | 스트림내의 복수의 샘플을 취득한다.
ReceiveCanBlock | Receive 메소드에의 호출이 블록이 될지 어떨지를 확인한다.

IMemInputPin::GetAllocator

IMemInputPin 인터페이스

이 핀이 제안한 메모리 allocater를 취득한다.

구문

HRESULT GetAllocator(
IMemAllocator **ppAllocator
);

파라미터

ppAllocator
[out] allocater의 IMemAllocator 인터페이스에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_NO_ALLOCATOR | 이용 가능한 allocater가 없다.

주의

출력 핀은 입력 핀과 접속 하면 와, 입력 핀에 메모리 allocater를 결정하도록(듯이) 네고시에이션 한다. 출력 핀은 이 메소드를 호출해 입력 핀이 제안한 allocater를 취득한다. 그것은 NotifyAllocator 메소드를 호출해 어느 allocater가 그것을 선택했는지를 지정한다.

이 메소드가 성공하면(자),IMemAllocator 인터페이스에는 참조 카운트가 남는다. 사용후, 해방시에 주의.

IMemInputPin::GetAllocatorRequirements

IMemInputPin 인터페이스

입력 핀이 요구한 allocater 프로퍼티를 취득한다.

구문

HRESULT GetAllocatorRequirements(
    ALLOCATOR_PROPERTIES *pProps
);

파라미터

pProps
[in] 요구를 기입하는 ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

출력 핀은 메모리 allocater를 초기화 하면 와, 이 메소드를 호출해 입력 핀이 버퍼 요구를 가지고 있을지 어떨지를 확인한다. 입력 핀의 이 메소드의 이행은 필수는 아니다. 필터가 지정한 alignment나 프레픽스의 요구를 가지고 있지 않으면, 이 메소드를 이행 해야 한다.

IMemInputPin::NotifyAllocator

IMemInputPin 인터페이스

접속용의 allocater를 지정한다.

구문

HRESULT NotifyAllocator(
    IMemAllocator *pAllocator,
    BOOL bReadOnly
);

파라미터

pAllocator
[in] allocater의 IMemAllocator 인터페이스에의 포인터.
bReadOnly
[out] 이 allocater로부터의 샘플이 읽어들여 전용인가 어떤가를 지정하는 플래그. TRUE 라면 샘플은 읽어들여 전용.

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

핀 접속중에, 출력 핀은 allocater를 선택해, 이 메소드를 호출해 입력 핀에 통지한다. 출력 핀은 IMemInputPin::GetAllocator 로 입력 핀이 제안한 allocater를 사용하는 경우도 있지만, 그것 자신의 allocater를 제공하는 경우도 있다.

bReadOnly 파라미터가 TRUE 라면, allocater내의 모든 샘플은 읽어들여 전용이다. 필터가 데이터를 수정하려면 그것들을 카피해야 한다.

IMemInputPin::Receive

IMemInputPin 인터페이스

스트림내의 다음의 미디어 샘플을 취득한다.

구문

HRESULT Receive(
    IMediaSample *pSample
);

파라미터

pSample
[in] 샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
S_FALSE | 핀은 현재 플래시 하고 있는, 샘플은 거부되었다.
E_POINTER | NULL 포인터 인수.
VFW_E_INVALIDMEDIATYPE | 부적절한 미디어 타입
VFW_E_RUNTIME_ERROR | 런타임 에러가 일어났다.
VFW_E_WRONG_STATE | 핀은 정지하고 있다.

주의

이 메소드는 동기 하고 있어, 블록의 가능성이 있다. 핀은 이하의 1 개를 실시한다 :

  • 샘플을 거부한다.
  • 곧바로 돌아와, 워커 thread로 샘플을 처리한다.
  • 돌아오기 전에 샘플을 처리한다.

마지막 케이스에서는, 메소드는 무한하게 블록 할 가능성이 있다. 이것이 일어날 것 같으면,ReceiveCanBlock 메소드는 S_OK 를 돌려준다.

핀이 워커 thread를 사용해 샘플을 처리한다면, 그것은 샘플의 참조 카운트를 보관 유지한다. 어느 케이스에서도 출력 핀은 이 샘플을 직접 재사용할 수 없다. IMemAllocator::GetBuffer 메소드를 호출해 새로운 샘플을 취득해야 한다.

IMemInputPin::ReceiveCanBlock

IMemInputPin 인터페이스

Receive 메소드에의 호출이 블록이 될지 어떨지를 확인한다.

구문

HRESULT ReceiveCanBlock(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | Receive 를 호출해도 핀은 블록이 되지 않는다.
S_OK | Receive 를 호출하면 핀은 블록이 될 가능성이 있다.

주의

이 메소드가 S_FALSE 를 돌려준다면,Receive 메소드의 호출은 블록 하지 않는 것이 보증된다. 그렇지 않으면, 블록이 되는 경우가 있다. 업 스트림 필터는 이 메소드를 사용해 그 thread 방침을 결정할 수가 있다. Receive 의 호출이 블록이 될 수 있다면, 업 스트림 필터는, 데이터를 버퍼링 하는 워커 thread의 사용을 결정할 수도 있다.

IMemInputPin::ReceiveMultiple

IMemInputPin 인터페이스

스트림내의 복수의 샘플을 취득한다.

구문

HRESULT ReceiveMultiple(
    IMediaSample **pSamples,
    long nSamples,
    long *nSamplesProcessed
);

파라미터

pSamples
[in] nSamples 사이즈의 IMediaSample 포인터의 배열의 주소.
nSamples
[in] 처리하는 샘플의 수.
nSamplesProcessed
[out] 처리된 샘플의 수를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
S_FALSE | 핀은 현재 플래시 하고 있는, 샘플은 거부되었다.
E_POINTER | NULL 포인터 인수.
VFW_E_INVALIDMEDIATYPE | 부적절한 미디어 타입.
VFW_E_RUNTIME_ERROR | 런타임 에러가 일어났다.
VFW_E_WRONG_STATE | 핀은 정지하고 있다.

주의

이 메소드는 Receive 메소드와 같이 동작하지만, 샘플의 배열을 취득한다.


IMixerPinConfig 인터페이스

IMixerPinConfig 인터페이스는,오버레이 믹서 필터의입력 핀상에서 공개되어 비디오 스트림의 각종 조작을 실행하는 메소드를 제공한다. 오버레이 믹서에는, 비디오 입력 스트림의 추가시에 동적으로 생성 되는 복수의 입력 핀이 있다. 최초의 핀의 비디오 스트림을 "프라이머리 스트림", 그 후의 핀 스트림을 "세칸다리스트림" 이라고 부르는.

각종 비디오 스트림의 믹싱과 관계되는 파라미터를 조작하려면 , 이 인터페이스를 사용한다. 이러한 파라미터에는, 위치, Z 오더, 블렌딩 레벨과 투과성 레벨, 어스펙트비(가로세로 비율) 보정, 및 스트림의 칼라 키의 취득과 설정이 포함된다.

표시 윈도우에서의 비디오 스트림의 위치를 설정 하면,"세칸다리스트림" 모든 디폴트의 상대 위치가 {0, 0, 0, 0} 이 된다. 따라서,"세칸다리스트림" 상에 있는 SetRelativePosition 메소드를 사용해, 확실히 모든 비디오 스트림을 올바르게 배치한다.

어플리케이션에서는, 복수의 비디오 스트림을 믹싱 할 경우에, 이 인터페이스를 사용해 속성을 취득 및 설정한다.

요건

Mpconfig.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMixerPinConfig 메소드 | 설명
SetRelativePosition | 표시 윈도우에서의 스트림의 위치를 설정한다.
GetRelativePosition | 표시 윈도우에서의 스트림의 위치를 설정한다.
SetZOrder | 특정의 비디오 스트림의 Z 오더를 설정한다.
GetZOrder | 특정의 비디오 스트림의 Z 오더를 취득한다.
SetColorKey | 비디오 스트림으로 사용되고 있는 칼라 키를 설정한다.
GetColorKey | 비디오 스트림으로 사용되고 있는 칼라 키를 취득한다.
SetBlendingParameter | 블렌딩 파라미터를 설정한다. 이 파라미터는 세칸다리스트림과 프라이머리 스트림의 브렌드 방법을 정의한다.
GetBlendingParameter | 블렌딩 파라미터의 값을 취득한다. 이 파라미터는 세칸다리스트림과 프라이머리 스트림의 브렌드 방법을 정의한다.
SetAspectRatioMode | 윈도우의 사이즈 변경에서의 어스펙트비(가로세로 비율) 보정 모드를 설정한다.
GetAspectRatioMode | 윈도우의 사이즈 변경에서의 어스펙트비(가로세로 비율) 보정 모드를 취득한다.
SetStreamTransparent | 스트림을 투과로 설정한다.
SetStreamTransparent | 스트림이 투과인가 어떤가를 판단한다.

IMixerPinConfig::GetAspectRatioMode

IMixerPinConfig 인터페이스

윈도우의 사이즈 변경에서의 어스펙트비(가로세로 비율) 보정 모드를 취득한다.

구문

HRESULT GetAspectRatioMode(
    AM_ASPECT_RATIO_MODE *pamAspectRatioMode
    ) PURE;

파라미터

pamAspectRatioMode
[out] AM_ASPECT_RATIO_MODE 열거형 멤버에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
E_NOTIMPL | 세칸다리스트림 위에의 메소드가 불려 갔다.
E_INVALIDARG | 무효인 값 또는 NULL.
NOERROR | 에러 없음.

참조

IMixerPinConfig::SetAspectRatioMode

IMixerPinConfig::GetBlendingParameter

IMixerPinConfig 인터페이스

블렌딩 파라미터의 값을 취득한다. 이 파라미터는 세칸다리스트림과 프라이머리 스트림의 브렌드 방법을 정의한다.

구문

HRESULT GetBlendingParameter(
    DWORD *pdwBlendingParameter
    ) PURE;

파라미터

pdwBlendingParameter
[out] 프라이머리 스트림과 세칸다리스트림의 사이의 브렌드량을 나타내는 0 ~ 255 의 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
E_UNEXPECTED | 프라이머리 스트림 위에의 메소드가 불려 갔다.
E_INVALIDARG | 값이 가능한 범위 (0 ~ 255)를 넘고 있다.
NOERROR | 에러 없음.

주의

값 0 은, 세칸다리스트림이 비표시인 것을 나타낸다. 값 255 는, 세칸다리스트림이 차지하는 영역에서 프라이머리 스트림이 비표시인 것을 나타낸다.

참조

IMixerPinConfig::SetBlendingParameter

IMixerPinConfig::GetColorKey

IMixerPinConfig 인터페이스

비디오 스트림으로 사용되고 있는 칼라 키를 취득한다.

구문

HRESULT GetColorKey(
    COLORKEY *pColorKey,
    DWORD *pColor ) PURE;

파라미터

pColorKey
[out] 키의 종류 및 팔레트 인덱스가 저장 된 COLORKEY 구조체에의 포인터.
pColor
[out] 돌려주어진 값에의 포인터. 값은, 현재의 디스플레이 모드가 8 비트의 팔레트화 모드의 경우, 돌려주어진 COLORKEY 의 8 비트 팔레트 인덱스를 나타낸다. 그 이외의 경우, 칼라 키를 현재의 디스플레이 모드의 픽셀 포맷으로 표현한 것.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
E_INVALIDARG | 무효인 인수. 파라미터가 양쪽 모두 NULL.
E_FAIL | 칼라 키가 불명하기 때문에,GetColorKey 가 실패했다.
NOERROR | 에러 없음.

주의

프라이머리 스트림 위에의값을 취득 하면, 오버레이 표면으로 사용하고 있는 전송처 칼라 키를 얻을 수 있다. 세칸다리핀 위에의값을 취득 하면, 그 스트림으로 사용하고 있는 칼라 키를 얻을 수 있다.

현재의 DirectShow 에 있어서의 이 인터페이스의 이행은,pColorKey 파라미터와 pColor 파라미터의 어딘가에 NULL 를 돌려주는 경우가 있다. 다만, 양쪽 모두가 NULL 의 경우, 메소드는 실패해, E_INVALIDARG 를 돌려준다.

주 : pColor 파라미터로 돌려주어지는 DWORD 값은, 실제로 사용되고 있는 색이다. 따라서, 디스플레이의 비트 깊이가 8, 16, 24, 또는 32 의 경우, 각각,DWORD 의 하위 8, 16, 24, 32 비트가 칼라 키의 실제의 값을 나타낸다.

참조

IMixerPinConfig::SetColorKey

IMixerPinConfig::GetStreamTransparent

IMixerPinConfig 인터페이스

스트림이 투과인가 어떤가를 판단한다.

구문

HRESULT GetStreamTransparent(
    BOOL *pbStreamTransparent
    ) PURE;

파라미터

pbStreamTransparent
[out] 스트림이 투과인가 어떤가를 나타내는 값에의 포인터. TRUE 는 투과인 것을 나타내, FALSE 는 투과가 아닌 것을 나타낸다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 에러 없음.

참조

IMixerPinConfig::SetStreamTransparent

IMixerPinConfig::GetRelativePosition

IMixerPinConfig 인터페이스

표시 윈도우에서의 스트림의 위치를 설정한다.

구문

HRESULT GetRelativePosition(
    DWORD *pdwLeft,
    DWORD *pdwTop,
    DWORD *pdwRight,
    DWORD *pdwBottom ) PURE;

파라미터

pdwLeft
[out] 표시 윈도우의 맨 왼쪽 위쪽의 x 좌표를 나타내는 값에의 포인터.
pdwTop
[out] 표시 윈도우의 맨 왼쪽 위쪽의 y 좌표를 나타내는 값에의 포인터.
pdwRight
[out] 표시 윈도우의 우하각의 x 좌표를 나타내는 값에의 포인터.
pdwBottom
[out] 표시 윈도우의 우하각의 y 좌표를 나타내는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
E_INVALIDARG | 좌표가 {0, 0, 10,000, 10,000} 의 범위를 넘고 있다.
NOERROR | 에러 없음.

주의

이 메소드에서는,{0, 0, 10,000, 10,000} 의 윈도우 좌표가 상정되고 있다. 표시 윈도우의 우하 부분에서 비디오 스트림이 렌더링 되고 있는 경우, 이 메소드는 {5,000, 5,000, 10,000, 10,000} 을 돌려준다.

참조

IMixerPinConfig::SetRelativePosition

IMixerPinConfig::GetZOrder

IMixerPinConfig 인터페이스

특정의 비디오 스트림의 Z 오더를 취득한다.

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT GetZOrder(
    DWORD *pdwZOrder
    ) PURE;

파라미터

pdwZOrder
[out] 스트림간의 클립 순서를 나타내는 값에의 포인터.

반환값

E_NOTIMPL 를 돌려준다.

주의

z 값이 큰 이미지는, z 값이 작은 이미지보다 항상 앞에 있다.

참조

IMixerPinConfig::SetZOrder

IMixerPinConfig::SetAspectRatioMode

IMixerPinConfig 인터페이스

윈도우의 사이즈 변경에서의 어스펙트비(가로세로 비율) 보정 모드를 설정한다.

구문

HRESULT SetAspectRatioMode(
    AM_ASPECT_RATIO_MODE amAspectRatioMode
    ) PURE;

파라미터

amAspectRatioMode
[in] AM_ASPECT_RATIO_MODE 열거형 멤버의 어느쪽이든을 지정하는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
E_NOTIMPL | 세칸다리스트림 위에의 메소드가 불려 갔다.
E_INVALIDARG | 무효인 인수.
NOERROR | 에러 없음.

주의

현재, 이 메소드는,오버레이 믹서 필터의 프라이머리 핀에만 이행 된다. 세칸다리핀의 이 메소드를 호출하면, 에러가 된다.

참조

IMixerPinConfig::GetAspectRatioMode

IMixerPinConfig::SetBlendingParameter

IMixerPinConfig 인터페이스

블렌딩 파라미터를 설정한다. 이 파라미터는 세칸다리스트림과 프라이머리 스트림의 브렌드 방법을 정의한다.

구문

HRESULT SetBlendingParameter(
    DWORD dwBlendingParameter
    ) PURE;

파라미터

dwBlendingParameter
[in] 프라이머리 스트림과 세칸다리스트림의 브렌드의 양을 나타내는 0 ~ 255 의 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
E_UNEXPECTED | 프라이머리 스트림 위에의 메소드가 불려 갔다.
E_INVALIDARG | 값이 가능한 범위 (0 ~ 255)를 넘고 있다.
NOERROR | 에러 없음.

주의

dwBlendingParameter 파라미터에는, 0 ~ 255 의 값을 지정한다. 값 0 에서는, 세칸다리스트림이 비표시가 된다. 또, 값 255 에서는, 세칸다리스트림이 차지하는 영역에서 프라이머리 스트림이 비표시가 된다. 값을 설정하지 않으면 디폴트값 255 가 사용된다.

이 메소드에서는, 프라이머리 스트림상에서의 호출은 상정되어 있지 않다.

주 : 현재의 DirectShow 에 있어서의 이 인터페이스의 이행에서는,dwBlendingParameter 파라미터에 사용할 수 있는 값은 0 ~ 255 뿐인다. 이외의 값은 모두 무효가 된다.

참조

IMixerPinConfig::GetBlendingParameter

IMixerPinConfig::SetColorKey

IMixerPinConfig 인터페이스

비디오 스트림으로 사용되고 있는 칼라 키를 설정한다.

구문

HRESULT SetColorKey(
    COLORKEY *pColorKey
) PURE;

파라미터

pColorKey
[in] COLORKEY 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

칼라 키라고 하는 용어가 가지는 의미는, 대상의 스트림에 따라서 다르다. 프라이머리 스트림의 칼라 키란, 오버레이 표면으로 사용되고 있는 전송처 칼라 키를 의미한다. 세칸다리스트림의 칼라 키란, 오프 스크린 표면으로부터프라이머리 표면에의소총탄으로 사용되는 전송원칼라 키를 의미한다.

어플리케이션에서는, 프라이머리 핀의 칼라 키에 표시되지 않는 색 (데스크탑에 없다고 생각되는 색)을 설정하는 것. 오버레이 믹서 필터는, 눈에 띄지 않는 색을 선택하려고 하지만, 지정된 색이 다른 컨텐츠에 포함되어 있는 것을 알 수 있고 있는 경우는, 어플리케이션측에서 변경하는 것.

세칸다리스트림의 칼라 키를 설정해 스트림을 투과로 하면(자), 직사각형 이외의 이미지가 가능하게 된다. 예를 들어, 세칸다리스트림이 자막 방송 텍스트라면, 자막 방송 텍스트 디코더로, 배경을 순색으로 전부 칠한 데다가, 대응하는 핀의 칼라 키로서 그 칼라를 설정한다. 이 결과, 칼라 키로 지정한 픽셀 이외가 모두 전송 된다. 가능하면, 어플리케이션으로, 세칸다리스트림의 칼라 키에 프라이머리 스트림의 칼라 키와 같은 색을 설정 하면, 퍼포먼스를 약간 올릴 수가 있다.

프라이머리 스트림에 이 값을 설정 하면, 오버레이 표면으로 사용되는 전송처 칼라 키가 설정된다. 디폴트에서는, 투과의 (세칸다리) 스트림 모든 칼라 키로서 전송처 칼라 키가 사용된다.

pColorKey 파라미터로서 유효한 인수에는, CK_INDEX 및 CK_RGB 가 포함된다. 비디오 디스플레이 모드는, CK_INDEX 에서는 256 색으로 설정되어 CK_RGB 에서는 하이칼라-, 24 비트, 32 비트등의 비교적 높은 색깊이로 설정된다. CK_RGB 플래그는, CK_INDEX 와 함께 지정한다. CK_INDEX 플래그를 설정 하면, 256 색모드에서의 팔레트 인덱스로서 그 인덱스가 사용된다. 다만, 디스플레이 모드가 돌연 변경되었을 때에 DirectShow 가 지정된 트루 칼라를 사용할 수 있도록(듯이),COLORREF 에는 유효한 트루 칼라를 제공할 필요가 있다. 이것은, 복수의 트루 칼라는 단독의 팔레트 인덱스에 맵 할 수 있지만, 팔레트 인덱스로부터 트루 칼라에의 맵은 1 대 1 이 아니기 때문이다.

주 : 현재, 이 메소드는 프라이머리 입력 핀용으로만 이행 된다.

참조

IMixerPinConfig::GetColorKey

IMixerPinConfig::SetStreamTransparent

IMixerPinConfig 인터페이스

스트림을 투과로 설정한다.

구문

HRESULT SetStreamTransparent(
    BOOL bStreamTransparent
    ) PURE;

파라미터

bStreamTransparent
[in] 스트림의 투과성을 지정하는 값. 스트림이 투과의 경우는, TRUE 를 건네준다. 투과가 아닌 경우는, FALSE 를 건네준다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 에러 없음.

참조

IMixerPinConfig::GetStreamTransparent

IMixerPinConfig::SetRelativePosition

IMixerPinConfig 인터페이스

표시 윈도우에 있어서의 스트림의 위치를 설정한다.

구문

HRESULT SetRelativePosition(
    DWORD dwLeft,
    DWORD dwTop,
    DWORD dwRight,
    DWORD dwBottom ) PURE;

파라미터

dwLeft
[in] 표시 윈도우의 맨 왼쪽 위쪽의 x 좌표를 지정하는 값.
dwTop
[in] 표시 윈도우의 맨 왼쪽 위쪽의 y 좌표를 지정하는 값.
dwRight
[in] 표시 윈도우의 우하각의 x 좌표를 지정하는 값.
dwBottom
[in] 표시 윈도우의 우하각의 y 좌표를 지정하는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 DirectShow 의 이행에서의 반환값은 다음과 같다.
E_INVALIDARG | 좌표가 {0, 0, 10,000, 10,000} 의 범위를 넘고 있다.
NOERROR | 에러 없음.

주의

이 메소드에서는,{0, 0, 10,000, 10,000} 의 윈도우 좌표가 상정되고 있다. 따라서, 표시 윈도우의 우하 부분에서 비디오 스트림을 렌더링 하려면 , 파라미터에 {5,000, 5,000, 10,000, 10,000} 을 지정해 호출한다.

주 : 10, 000 을 넘는 값은 무효이다. 지정 하면 에러가 된다.

참조

IMixerPinConfig::GetRelativePosition

IMixerPinConfig::SetZOrder

IMixerPinConfig 인터페이스

특정의 비디오 스트림의 Z 오더를 설정한다.

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT SetZOrder(
  DWORD dwZOrder
) PURE;

파라미터

dwZOrder
[in] 스트림간의 클립 순서를 나타내는 값.

반환값

E_NOTIMPL 를 돌려준다.

주의

Z 오더는, 어느 스트림이 어느 스트림을 클립 할 수 있는지를 나타낸다. z 값이 큰 이미지는, z 값이 작은 이미지보다 항상 앞에 있다.

복수 스트림간의 상대 순서는, 그러한 비디오 이미지가 오버랩 하는 경우에게만 의미를 가진다.

오버랩 하는 2 개의 스트림에 같은 Z 오더를 지정 하면, 비디오에 부자연스러운 효과가 나타나는 일이 있다.

참조

IMixerPinConfig::GetZOrder


IMixerPinConfig2 인터페이스

IMixerPinConfig2 인터페이스는,오버레이 믹서의입력 핀상에서 공개되어 비디오의 칼라 컨트롤을 조작을 실행하는 메소드를 제공한다 (다만, VGA 팁이 칼라 컨트롤을 지원 하는 경우).

이 인터페이스는,IMixerPinConfig 인터페이스로부터 파생한다.

어플리케이션에서는, 복수의 비디오 스트림을 믹싱 할 경우에, 이 인터페이스를 사용해 비디오의 칼라 컨트롤을 취득 및 설정한다.

요건

Mpconfig.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMixerPinConfig2 메소드 | 설명
SetOverlaySurfaceColorControls | 지정된 오버레이 표면에 관련지을 수 있었던 칼라 컨트롤을 설정한다.
GetOverlaySurfaceColorControls | 지정된 오버레이 표면에 현재 관련지을 수 있고 있는 칼라 컨트롤을 취득한다.

IMixerPinConfig2::GetOverlaySurfaceColorControls

IMixerPinConfig2 인터페이스

지정된 오버레이 표면에 관련지을 수 있었던 칼라 컨트롤을 취득한다.

구문

HRESULT GetOverlaySurfaceColorControls(
    LPDDCOLORCONTROL pColorControl
    ) PURE;

파라미터

pColorControl
[out] 지정된 표면에 현재 적용되고 있는 칼라값이 들어간 DDCOLORCONTROL 구조체에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 핀 위에의 allocater가 오버레이 표면을 사용하고 있지 않는 경우는, E_FAIL 가 돌려주어진다.

IMixerPinConfig2::SetOverlaySurfaceColorControls

IMixerPinConfig2 인터페이스

지정된 오버레이 표면에 관련지을 수 있었던 칼라 컨트롤을 설정한다.

구문

HRESULT SetOverlaySurfaceColorControls(
    LPDDCOLORCONTROL pColorControl
    ) PURE;

파라미터

pColorControl
[in] 지정된 표면에 적용되는 새로운 값이 들어간 DDCOLORCONTROL 구조체에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 핀 위에의 allocater가 오버레이 표면을 사용하고 있지 않는 경우는, E_FAIL 가 돌려주어진다.


IMpeg2Demultiplexer 인터페이스

이 인터페이스는 MPEG-2 디멀티플렉서 필터 (Demux) 상에서 이행 되어 프로그램 스트림 모드와 트랜스폴트 스트림 모드의 양쪽 모두로 이용된다. 어플리케이션이나 다른 필터가 Demux 상에서 출력 핀을 생성, 구성, 삭제할 때에 불려 간다.

메소드명 | 설명
CreateOutputPin | Demux 에 새로운 출력 핀을 생성 한다.
SetOutputPinMediaType | 지정된 출력 핀의 미디어 타입을 업데이트 한다. (DirectX® 8 에서는 이행되어 있지 않다. )
DeleteOutputPin | 지정된 출력 핀을 삭제한다.

IMpeg2Demultiplexer::CreateOutputPin

IMpeg2Demultiplexer 인터페이스

Demux 에 새로운 출력 핀을 생성 한다.

구문

HRESULT CreateOutputPin(
    AM_MEDIA_TYPE* pMediaType,
     LPWSTR pszPinName,
      IPin** ppIPin
    );

파라미터

pMediaType
[in] 새로운 핀의 미디어 타입 정보를 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.
pszPinName
[in] 새로운 핀의 어플리케이션 정의의 프렌들리명을 지정하는 와이드 캐릭터 캐릭터 라인에의 포인터.
ppIPin
[out] 새로운 핀의 IPin 인터페이스에 세트 되는 포인터.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 에러 정보는 표준 COM IErrorInfo 인터페이스를 사용해 취득할 수 있다.

주의

같은 이름의 핀명은 허가되지 않는다. 돌려주어지는 IPin 인터페이스는 IMPEG2StreamIdMap 인터페이스 (프로그램 스트림용) 혹은 IMPEG2PIDMap 인터페이스 (트랜스폴트 스트림용)에 대해서 새로운 핀을 쿼리 하기 위해서 이용된다. 최초의 출력 핀으로서 어느 인터페이스가 쿼리 될까를 기본으로, Demux 는 자기 자신을 트랜스폴트 스트림 모드 혹은 프로그램 스트림 모드의 어딘가에 구성한다. Demux 가 한 번 구성되면(자), 다른 인터페이스를 취득하는 QueryInterface 에의 호출은 실패한다.

IMpeg2Demultiplexer::SetOutputPinMediaType

IMpeg2Demultiplexer 인터페이스

지정된 출력 핀의 미디어 타입을 업데이트 한다. (DirectX® 8 에서는 이행되어 있지 않다. )

구문

HRESULT SetOutputPinMediaType(
    LPWSTR pszPinName,
    AM_MEDIA_TYPE* pMediaType
    );

파라미터

pszPinName
[in] 핀이 CreateOutputPin 의 호출시에 생성 되었을 때 지정된 핀의 프렌들리명.
pMediaType
[in] 핀에 대해서 새로운 미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 에러 정보는 표준 COM IErrorInfo 인터페이스를 사용해 취득할 수 있다.

주의

DirectX 8 에서는, 핀이 생성 되었을 때의 미디어 타입이 핀에 할당 되지 않으면 안 된다. 그 미디어 타입은 다음에 변경할 수가 없다.

핀은 새로운 미디어 타입으로 언제라도 복구성 가능하다. 접속하고 있지 않으면, 미디어 타입은 단지 업데이트 되는 것만으로 있다. 그 핀이 접속되고 있으면(자), 다운 스트림 입력 핀이 지정된 미디어 타입을 허용 하는지 거부할까에 의해, 그 호출이 성공 혹은 실패한다.

미디어 타입은 Demux 에서는 해석되지 않는다. 그 해석은 출력 핀에 의한 접속 네고시에이션중에만 행해진다. 미디어 샘플의 내용으로부터는 해석되지 않는다. 미디어 샘플의 내용은 PID 가 IMPEG2PIDMap::MapPID 메소드의 MEDIA_SAMPLE_CONTENT 파라미터로 맵 될 때, 혹은 IMPEG2StreamId::MapStreamId 호출에 정의된 값에 의해 정의된다.

IMpeg2Demultiplexer::DeleteOutputPin

IMpeg2Demultiplexer Interface

지정된 출력 핀을 삭제한다.

구문

HRESULT DeleteOutputPin(
    LPWSTR pszPinName
    );

파라미터

pszPinName
[in] 핀이 CreateOutputPin 의 호출시에 생성 되었을 때 지정된 핀의 프렌들리명.

반환값

성공이라면 S_OK 를 돌려준다. 에러 정보는 표준 COM IErrorInfo 인터페이스를 사용해 취득할 수 있다.

주의

필터를 남긴 채로 핀을 삭제할 필요가 있을 때 마셔, 이 메소드를 호출하는 것. 필터는 해방될 때, 출력 핀으로 필요한 모든 클린 업을 실시한다.


IMPEG2PIDMap 인터페이스

이 인터페이스는 MPEG-2 디멀티플렉서 필터 (Demux)의 각 출력 핀으로 이행 되어 트랜스폴트 스트림 모드에서만 사용된다. 어플리케이션이나 다른 필터가 핀과 1 개 이상의 패킷 ID (PID)를 조합하기 위해서(때문에) 이 인터페이스를 호출한다. PID 가 한 번 맵 되면(자), Demux 는 모든 패킷을 출력 핀에 그 ID 로 출력한다

프로그램 스트림에 대해서는,IMPEG2StreamIdMap 인터페이스를 사용한다.

메소드명 | 설명
MapPID | 지정된 PID 의 패킷을 핀에 맵 한다.
UnmapPID | MapPID 에의 이전의 호출로 생성 된 PID 매핑을 해제한다.
EnumPIDMap | 이 핀에 현재 맵 떠날 수 있어 모든 PID 의 콜렉션을 돌려준다.

IMPEG2PIDMap::MapPID

IMPEG2PIDMap 인터페이스

지정된 PID 의 패킷을 핀에 맵 한다.

구문

HRESULT MapPID(
    ULONG culPID,
    ULONG* pulPID,
    MEDIA_SAMPLE_CONTENT MediaSampleContent
);

파라미터

culPID
[in] putPID 배열의 요소수를 지정하는 ULONG 형의 변수.
pulPID
[in] 맵 하는 PID 를 지정하는 ULONG 형의 변수에의 포인터.
MediaSampleContent
[in] 스트림의 내용을 지정하는 MEDIA_SAMPLE_CONTENT 형의 변수.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 에러 정보는 표준 COM IErrorInfo 인터페이스를 사용해 취득할 수 있다.

주의

주어진 시간에 255 보다 많은 다른 PID 를 맵 할 수 없다. 이것은 Demux 가 자기 자신으로 사용하기 위해서 내부적으로 맵 하는 PID 를 포함한, 이 수는 트랜스폴트 스트림에 의존해 바뀐다. 어플리케이션은 주어진 트랜스폴트 스트림상에서 보통 10 에서 12 보다 많은 PID 를 맵 하지 않기 때문에, 이 제한은 문제가 되지 말고 있을것이다.

IMPEG2PIDMap::UnmapPID

IMPEG2PIDMap 인터페이스

MapPID 에의 이전의 호출로 생성 된 PID 매핑을 해제한다.

구문

HRESULT UnmapPID(
    ULONG culPID,
    ULONG* pulPID
);

파라미터

culPID
[in] putPID 배열의 요소수를 지정하는 ULONG 형의 변수.
pulPID
[in] 이 핀에 맵 되는 PID 의 배열.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 에러 정보는 표준 COM IErrorInfo 인터페이스를 사용해 취득할 수 있다.

주의

오디오 스트림과 비디오 스트림의 출력 핀에서는, 주어진 시간에 맵 되는 PID 는 1 개 뿐이다. PSI 스트림을 트랜스폴트 정보 필터에 출력하는 핀과 같은 출력 핀에서는, 1 개의 핀에 복수의 PID 가 맵 되는 경우가 있다. 그 핀에 어느 PID 가 맵 되고 있는지를 확인하려면 ,IEnumPIDMap 메소드를 사용해, 다음에 그 값을 pulPID 배열에 기입하는 것.

IMPEG2PIDMap::EnumPIDMap

IMPEG2PIDMap 인터페이스

이 핀에 현재 맵 떠날 수 있어 모든 PID 의 콜렉션을 돌려준다.

구문

HRESULT EnumPIDMap(
    IEnumPIDMap** ppIEnumPIDMap
);

파라미터

ppIEnumPIDMap
[in] 돌려주어지는 콜렉션에 세트 되는 IEnumPIDMap 인터페이스 포인터.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 에러 정보는 표준 COM IErrorInfo 인터페이스를 사용해 취득할 수 있다.


IMPEG2StreamIdMap 인터페이스

이 인터페이스는 MPEG-2 디멀티플렉서 필터 (Demux)의 각 출력 핀으로 이행 된다. 프로그램 스트림 모드에서만 사용된다. 어플리케이션이나 다른 필터가 핀과 지정된 스트림 ID 를 조합하기 위해서(때문에), 그리고 그 핀에 서브 스트림 필터 링이 스트림에 요구되고 있는지 어떤지를 알리기 위해서(때문에) 이 인터페이스를 호출한다.

트랜스폴트 스트림에 대해서는 IMPEG2PIDMap 인터페이스를 사용한다.

메소드명 | 설명
MapStreamId | MPEG-2 프로그램 스트림내의 기본 스트림의 스트림 ID 를 미디어 내용 타입과 서브 스트림 정보에 맵 한다.
UnmapStreamId | 이전의 MapStreamId 호출로 생성 된 스트림 ID 매핑을 해제한다.
EnumStreamIdMap | 이 핀에 맵 떠날 수 있어 모든 스트림 ID 의 콜렉션을 돌려준다.

IMPEG2StreamIdMap::MapStreamId

IMPEG2StreamIdMap 인터페이스

MPEG-2 프로그램 스트림내의 기본 스트림의 스트림 ID 를 미디어 내용 타입과 서브 스트림 정보에 맵 한다.

구문

HRESULT MapStreamId(
    ULONG ulStreamId,
    DWORD MediaSampleContent,
    ULONG ulSubstreamFilterValue,
    int iDataOffset
);

파라미터

ulStreamId
[in] PES 스트림의 스트림 ID 를 지정하는 ULONG 형의 변수.
MediaSampleContent
[in] 스트림의 내용을 지정하는 ULONG 형의 변수. 현재 지원 되고 있는 값은 MPEG2_PROGRAM_ELEMENTARY_STREAM (axextend.idl 로 0x00000001 로 정의되고 있다) 뿐인다.
ulSubstreamFilterValue
[in] 이 기본 스트림내의 어느 서브 스트림을 다운 스트림 디코더에 건네주는지를 지정하는 ULONG 형의 변수. 저오더 바이트인 만큼 유효한 값이 들어가 있다. iDataOffset = 0 이라면, 이 파라미터는 무시된다.
iDataOffset
[in] 서브 스트림 시작점의 바이트 오프셋(offset)를 지정하는 int 형의 변수.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 에러 정보는 표준 COM IErrorInfo 인터페이스를 사용해 취득할 수 있다.

주의

이 메소드가 맵 하는 스트림 ID 는 PES 헤더내의 스트림 ID 이다. 서브 스트림 필터 링은 1 개의 오디오 스트림으로 복수 채널을 제공하기 위해서 가장 보통으로 사용되고 있다.

IMPEG2StreamIdMap::UnmapStreamId

IMPEG2StreamIdMap 인터페이스

이전의 MapStreamId 호출로 생성 된 스트림 ID 매핑을 해제한다.

구문

HRESULT UnmapStreamId(
    ULONG culStreamId,
    ULONG* pulStreamID
);

파라미터

culStreamId
[in] pulStreamID 배열내의 요소의 수를 지정하는 ULONG 형의 변수.
pulStreamID
[in] 이 핀에 맵 된 스트림 ID 의 배열.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 에러 정보는 표준 COM IErrorInfo 인터페이스를 사용해 취득할 수 있다.

주의

주어진 핀에 맵 되는 스트림 ID 는 보통 1 개(살) 뿐이다, 그러므로 pulStreamID 는 보통 1 개의 요소만을 가진다.

IMPEG2StreamIdMap::EnumStreamIdMap

IMPEG2StreamIdMap 인터페이스

이 핀에 맵 떠날 수 있어 모든 스트림 ID 의 콜렉션을 돌려준다.

구문

HRESULT EnumStreamIdMap(
    IEnumStreamIdMap** ppIEnumStreamIdMap
);

파라미터

ppIEnumStreamIdMap
[in] 돌려주어지는 콜렉션이 세트 되는 IEnumStreamIdMap 인터페이스 포인터.

반환값

성공이라면 S_OK 를 돌려준다. 메소드가 실패 하면, 에러 정보는 표준 COM IErrorInfo 인터페이스를 사용해 취득할 수 있다.

주의

현재, 주어진 핀에 맵 되는 스트림 ID 는 1 개 뿐이다, 그러므로 이 콜렉션은 보통 1 개의 요소만을 가진다.


IOverlay 인터페이스

IOverlay 인터페이스는, 비디오를 올바른 윈도우 위치에 배치한 상태로, 필터로부터 비디오 메모리에 직접 기입하기 위해서(때문에) 필요한 정보를 제공한다. 이 인터페이스는, 비디오 렌더러의입력 핀상에 이행 되어업 스트림 필터 (주로 비데오데콘프렛사피르타)의 IOverlayNotify 메소드를 호출해, 비디오 윈도우에의 변경을 통지하는 것으로써, 그 필터와 통신한다.

이 인터페이스는, DirectDraw® 의 오버레이 능력과는 무관계하다. Microsoft 의 비디오 렌더러는,IMemInputPin 인터페이스를 통해서 받은 데이터를, DirectDraw 오버레이를 사용해 드로잉(Drawing) 한다 (다만 이용 가능한 경우). 이 인터페이스는,IMemInputPin 대신에 사용되어 렌더러의 드로잉(Drawing) 능력을 우회도로 하지만, 디스플레이의 그 외 프로퍼티의 통지를 받을 필요가 있는, 모든 업 스트림 필터에, 통지의 지원을 제공하는 것을 목적으로 하고 있다.

IOverlay 인터페이스와 IOverlayNotify 인터페이스의 제휴의 상세한 것에 대하여는, 「IOverlayNotify 인터페이스」를 참조할것.

렌더링 윈도우에의 변경의 비동기 통지의 상세한 것에 대하여는, 「IOverlayNotify2 인터페이스」를 참조할것.

이 인터페이스는, Microsoft® DirectShow® 비디오 렌더링 필터에 이행 된다. 또, 필요에 따라서, 대체 비디오 렌더링 필터에 이행 할 수도 있다. 그 경우에는, 이 인터페이스를 이행 해, frame buffer에 직접 기입하는 필터, 또는 오버레이를 배치하려고 하는 필터에, 비디오를 어디에 표시하면 좋은가를 알린다. 이 인터페이스를 이행 하려면 , 비디오 프로퍼티의 변경의 통지도 포함해 드로잉(Drawing)를 실시하고 있는 필터의 IOverlayNotify 인터페이스 또는 IOverlayNotify2 인터페이스의 메소드를 사용할 준비가, 렌더러로 할 수 있고 있을 필요가 있다.

DirectShow 의 윈도우 베이스의 렌더러는,IMemInputPin 인터페이스와 IOverlay 인터페이스의 양쪽 모두를 지원 한다. 이것들 2 개의 인터페이스는 서로 배타이다. 필터에서는, 서브 타입이 MEDIASUBTYPE_Overlay 의 미디어 타입을 접속중에 제공하는 것으로써,IOverlay 전송 인터페이스의 (분)편을 사용한다. 접속 후, 필터는 문제 없고 IOverlay 인터페이스를 취득 및 사용할 수 있다. 필터가 다른 비디오 포맷 (MEDIASUBTYPE_RGB8 등)으로 접속하는 경우,IOverlay 를 통해서 호출하려고 하면,VFW_E_NOT_OVERLAY_CONNECTION 가 돌려주어진다.

비디오 오버레이의 프로퍼티를 제어할 필요가 있어, 비디오 데이터 자체의 표시를 처리하려고 하는 업 스트림 필터로부터는, 이 인터페이스의 메소드를 사용하는 것. 이 인터페이스는, 보통, 비디오 하드웨어에의 대체 접속을 가지는 하드웨어 비디오 디코더로 사용된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IOverlay 메소드 | 설명
GetPalette | 현재의 팔레트를 취득한다.
SetPalette | 팔레트를 설정한다.
GetDefaultColorKey | 디폴트의 칼라 키를 취득한다.
GetColorKey | 현재 액티브한 칼라 키의 식별자를 취득한다.
SetColorKey | 칼라 키를 변경한다.
GetWindowHandle | 윈도우 핸들을 돌려준다.
GetClipList | 클립 리스트를 취득한다.
GetVideoPosition | 현재의 비디오의 전송원직사각형 및 전송처 직사각형을 취득한다.
Advise | 오버레이 이벤트용의아드바이즈 링크 를 설정한다.
Unadvise | 아드바이즈린크를 종료한다.

IOverlay::Advise

IOverlay 인터페이스

dwInterests 파라미터로 지정된 오버레이 이벤트용의 아드바이즈린크를 설정한다.

구문

HRESULT Advise(

  IOverlayNotify *pOverlayNotify,

  DWORD dwInterests

  );

파라미터

pOverlayNotify
[in] 통지 인터페이스에의 포인터.
dwInterests
[in] 목적의 콜백. 이하의 이벤트로부터 완성되는 임의의 서브 세트를 지정한다.
ADVISE_NONE | 변경 없음.
ADVISE_CLIPPING | 클리핑 리젼의 변경 (윈도우와 동기 한다).
ADVISE_PALETTE | 팔레트의 변경.
ADVISE_COLORKEY | chroma-key값의 변경.
ADVISE_POSITION | 비디오 윈도우의 위치의 변경 (윈도우와 동기 하지 않는다).
ADVISE_DISPLAY_CHANGE | WM_DISPLAYCHANGE 에 관한 호출. 디스플레이 해상도를 변경 하면, 모든 윈도우에 WM_DISPLAYCHANGE 메세지가 보내진다.
ADVISE_ALL2 | 위에의 모든 이벤트.

반환값

반환값 없음.

주의

이 메소드는,IOverlayNotify 인터페이스가 통지를 받기 위한 아드바이즈린크를 설정한다. 이러한 이벤트중 한쪽이 발생 하면,pOverlayNotify 파라미터에게 건네진 적절한 엔트리 포인트가 불려 간다 (IOverlayNotify::OnClipChange ,IOverlayNotify::OnColorKeyChange ,IOverlayNotify::OnPaletteChange , 또는 IOverlayNotify::OnPositionChange ).

1 개의 IOverlay 인터페이스로 설정할 수 있는 아드바이즈린크는 1 개 뿐이다. 2 번째 이후의 호출로 다른 통지 인터페이스를 설정하려고 하면(자),VFW_E_ADVISE_ALREADY_SET 가 돌려주어진다. 아드바이즈린크를 취소하려면 ,IOverlay::Unadvise 를 사용한다.

IOverlay::GetClipList

IOverlay 인터페이스

클립 리스트를 취득한다.

구문

HRESULT GetClipList(

  RECT *pSourceRect,

  RECT *pDestinationRect,

  RGNDATA **ppRgnData

  );

파라미터

pSourceRect
[out] 클라이언트의 경계 직사각형에의 포인터.
pDestinationRect
[in] 전송처 직사각형에의 포인터.
ppRgnData
[out] 클리핑이 기술된 헤더 및 데이터에의 포인터의 주소. 성공했을 경우는, Microsoft® Win32® CoTaskMemFree 함수로 메모리를 해방해야 한다.

반환값

반환값 없음.

주의

클리핑 직사각형의 메모리는, 사이즈가 가변인 싶은 IOverlay 의 이행에 의해 할당할 수 있다. 이 메소드의 호출원필터에서는, 다 사용했으면 (CoTaskMemFree 를 사용해) 메모리를 해방해야 한다.

IOverlay::GetColorKey

IOverlay 인터페이스

chroma-key 처리에 사용하는 현재의 칼라 키를 취득한다.

구문

HRESULT GetColorKey(

  COLORKEY *pColorKey

  );

파라미터

pColorKey
[out] chroma-key 처리에 사용하는 현재의 칼라 키의 카피처에의 포인터.

반환값

반환값 없음.

주의

IOverlay::SetColorKey 메소드를 사용해 칼라 키를 변경 하면, 모든 아드바이즈린크가, 새로운 색이 지정된 IOverlayNotify::OnColorKeyChange 콜백 메소드를 받는다.

현재 사용되고 있는 칼라 키가 없는 경우, 이 메소드는 VFW_E_NO_COLOR_KEY_SET 를 돌려준다.

IOverlay::GetDefaultColorKey

IOverlay 인터페이스

chroma-key 오버레이에 사용하는 디폴트의 칼라 키를 취득한다.

구문

HRESULT GetDefaultColorKey(

  COLORKEY *pColorKey

  );

파라미터

pColorKey
[out] 디폴트의 칼라 키의 카피처에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

칼라 키를 사용하는 필터는, 비디오 렌더러로부터 디폴트의 색을 취득할 수 있다. 게다가 IOverlay::SetColorKey 를 사용해, 윈도우에 디폴트의 칼라 키를 짜넣을 수 있다. 이 메소드로 돌려주어지는 색은, 현재의 디스플레이 모드에 따라서 다르다. 8 비트의 팔레트화 모드의 경우는, 밝은 시스템 칼라가 돌려주어진다 (진홍색 등). 트루 칼라 모드의 경우는, 흑의 농담이 돌려주어진다.

IOverlay 인터페이스에서는, 같은 컴퓨터에 있는 그 렌더러의 각 인스턴스에, 각각 다른 칼라 키가 건네받게 되어 있기 (위해)때문에, 오버레이의 경합은 발생하지 않는다.

IOverlay::GetPalette

IOverlay 인터페이스

현재의 시스템 팔레트를 취득한다.

구문

HRESULT GetPalette(

  DWORD *pdwColors,

  PALETTEENTRY **ppPalette

  );

파라미터

pdwColors
[out] 존재하는 색의 수에의 포인터.
ppPalette
[out] 취득된 팔레트 구조체에의 포인터의 주소.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IOverlay::GetVideoPosition

IOverlay 인터페이스

현재의 비디오의 전송원직사각형 및 전송처 직사각형을 취득한다.

구문

HRESULT GetVideoPosition(
  [out] RECT *pSourceRect,
  [out] RECT *pDestinationRect
  );

파라미터

pSourceRect
[out] 비디오 클라이언트의 경계 직사각형에의 포인터.
pDestinationRect
[in] 비디오의 전송처 직사각형에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IOverlay::GetWindowHandle

IOverlay 인터페이스

현재의 윈도우 핸들을 취득한다.

구문

HRESULT GetWindowHandle(
  HWND *pHwnd
  );

파라미터

pHwnd
[out] 윈도우 핸들에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IOverlay::SetColorKey

IOverlay 인터페이스

칼라 키를 변경한다.

구문

HRESULT SetColorKey(

  COLORKEY *pColorKey

  );

파라미터

pColorKey
[out] 설정하는 칼라 키값에의 포인터. 성공했을 경우는, 실제로 선택된 칼라 키값이, 이 파라미터에 카피된다.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

IOverlay::SetColorKey 메소드를 사용해 칼라 키를 변경 하면, 모든 아드바이즈린크가, 새로운 색이 지정된 IOverlayNotify::OnColorKeyChange 콜백 메소드를 받는다.

팔레트화 되고 있는 디스플레이상의 IOverlay 를 사용할때, 필터는, 칼라 키를 짜넣는 (IOverlay::SetColorKey 를 사용) 일도, 팔레트를 짜넣는 (IOverlay::SetPalette 를 사용한다) 일도 할 수 있지만, 양쪽 모두를 짜넣을 수 없다. 이것은, 이 모드의 칼라 키에서는 팔레트가 인식될 필요가 있어, 이것이 SetPalette 와 모순되기 때문이다. 칼라 키를 삭제하려면 , CK_NOCOLORKEY 플래그를 지정해 칼라 키를 요구한다. 같이SetPalette 로 짜넣은 팔레트를 삭제하려면 ,SetPalette 를 호출해 NULL 파라미터를 건네준다 (즉 SetPalette(0, NULL)).

칼라 키가 짜넣어지고 있을 때, 팔레트를 설정하려고 하면(자),VFW_E_PALETTE_SET 에러가 돌려주어진다. 팔레트가 짜넣어지고 있을 때, 칼라 키를 설정하려고 하면(자),VFW_E_COLOR_KEY_SET 가 돌려주어진다.

IOverlay::SetPalette

IOverlay 인터페이스

팔레트를 설정한다.

구문

HRESULT SetPalette(

  DWORD dwColors,

  PALETTEENTRY *pPalette

  );

파라미터

dwColors
[in] 존재하는 색의 수.
pPalette
[in] 팔레트에 사용하는 색에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는, 윈도우의 논리 팔레트를 설정한다. 실제의 시스템 디바이스 팔레트로 요구된 색을, 윈도우가 항상 가지고 있다고는 할 수 없다. Microsoft® Windows® operating system에서는, foreground의 액티브 윈도우에게만, 그러한 색이 보증된다. 현재의 디바이스 팔레트를 취득하려면 ,IOverlay::GetPalette 를 호출한다.

디바이스에 팔레트가 없는 경우,VFW_E_NO_DISPLAY_PALETTE 가 돌려주어진다.

오버레이 믹서 필터는, E_NOTIMPL 를 돌려준다.

IOverlay::Unadvise

IOverlay 인터페이스

IOverlayNotify 인터페이스로 확립한 아드바이즈린크를 종료한다.

구문

HRESULT Unadvise(void);

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는,IOverlay::Advise 메소드를 사용해 확립한 아드바이즈린크를 종료한다. 동시에 보관 유지할 수 있는 아드바이즈린크는 1 개 뿐이다.


IOverlayNotify 인터페이스

IOverlayNotify 인터페이스는, 디코더등의 업 스트림 필터에, 렌더링 윈도우에의 변경의 통지를 제공한다. 이 인터페이스에는, 팔레트, 칼라 키, 및 윈도우 위치에의 변경, 및 가시 영역 (클리핑)의 변화에 관한 통지가 포함된다.

많은 소프트웨어 비디오 디코더에서는, 디코더가 렌더러의입력 핀의 IMemInputPin 인터페이스에 미디어 샘플을 건네주어, 그 결과 생성된 압축 해제 후의 이미지를, 비디오 렌더러가 드로잉(Drawing) 한다.

다만, 일부의 비디오 디코드 필터 (주로 하드웨어 압축 해제 보드)에서는, (많은 경우 VGA 연결기를 사용해) 그 디코더내에서 이미지를 드로잉(Drawing) 한다. 이러한 필터에서는,IMemInputPin 를 사용할 필요는 없지만, 대신에, 렌더러의 입력 핀이 제공하는 IOverlay 인터페이스를 사용할 수 있다. 디코더는, 윈도우의 위치 또는 사이즈가 변화했을 때, 또는 현재의 시스템 팔레트가 변화했을 때에, 이 인터페이스를 통해서 통지를 받는 것에 의해, 칼라 키 및 팔레트의 편입이나 변경을 할 수 있다.

독자적인 드로잉(Drawing) 처리를 실시하는 디코더는, 윈도우의 사이즈 또는 위치가 변화했을 때, 현재의 시스템 팔레트가 변화했을 때, 또는 다른 칼라 키가 사용되었을 때에 통지를 받기 위해서(때문에),IOverlayNotify 인터페이스를 이행 해야 한다. 그렇다면, 이 메소드로, 이 인터페이스에의 포인터를, 렌더러의 입력 핀의 IOverlay 인터페이스에 건네주어,아드바이즈 링크 (본래는 콜백 메카니즘)를 설정할 수 있다. 아드바이즈린크의 확립 후에는, 해당하는 이벤트가 발생 하면, 렌더러가 디코더의 IOverlayNotify 메소드를 호출한다. 아드바이즈린크를 취소하려면 ,IOverlay::Unadvise 를 호출한다.

비디오 렌더러는, 이 인터페이스의 메소드를 호출하는 유일한 필터이다. 이 호출은, 디폴트의 렌더러에 의해 자동적으로 행해진다. 대체 비디오 렌더러를 개발하는 경우, 그 필터로 IOverlay 를 지원 해,IOverlay::Advise 의 호출로 필터에 이 인터페이스가 건네받는다면, 이 인터페이스의 메소드를 사용할 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IOverlayNotify 메소드 | 설명
OnPaletteChange | 윈도우의 팔레트가 변화한 것을 나타내는 통지를 제공한다.
OnClipChange | 윈도우의 가시 영역이 변화한 것을 나타내는 통지를 제공한다.
OnColorKeyChange | chroma-key가 변화한 것을 나타내는 통지를 제공한다.
OnPositionChange | 위치가 변화한 것을 나타내는 통지를 제공한다.

IOverlayNotify::OnClipChange

IOverlayNotify 인터페이스

윈도우의 가시 영역이 변화한 것을 나타내는 통지를 제공한다. 메소드로부터 돌아오기 전에, 오버레이 하드웨어 모두에게 가시 영역에의 변경이 반영되지 않으면 안 된다.

구문

HRESULT OnClipChange(
  RECT *pSourceRect,
  RECT *pDestinationRect,
  RGNDATA *pRgnData
  );

파라미터

pSourceRect
[in] 비디오내의 사용하는 영역에의 포인터.
pDestinationRect
[in] 비디오의 전송처에의 포인터.
pRgnData
[in] 클리핑 정보에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

OnClipChange 의 호출은, 윈도우와 동기 해 발생한다. 이 메소드는, 윈도우의 이동전에 비디오를 다운 당하기 위해서(때문에), 하늘의 클립 리스트를 지정해 불려 가 새로운 클립 리스트를 사용해 윈도우가 안정화 되었을 때에, 한번 더 불려 간다.

윈도우 직사각형이 모두 0 의 경우, 윈도우는 비표시이다. AVI 디코더의 경우, 현재의 이미지를 이용해 다음의 이미지를 복호화 한다면, 디코더는 이미지를 보존해야 한다.

IOverlayNotify::OnColorKeyChange

IOverlayNotify 인터페이스

윈도우의 칼라 키가 변화한 것을 나타내는 통지를 제공한다.

구문

HRESULT OnColorKeyChange(

  COLORKEY *pColorKey

  );

파라미터

pColorKey
[in] 새로운 chroma-key에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IOverlayNotify::OnPaletteChange

IOverlayNotify 인터페이스

윈도우의 팔레트가 변화한 것을 나타내는 통지를 제공한다.

구문

HRESULT OnPaletteChange(

  DWORD dwColors,

  const PALETTEENTRY *pPalette

  );

파라미터

dwColors
[in] 존재하는 색의 수.
pPalette
[in] 팔레트 칼라의 배열에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

돌아오기 전에, 필요에 따라서 필터로 RGBQUAD 값의 배열을 카피하는 것.

IOverlayNotify::OnPositionChange

IOverlayNotify 인터페이스

위치가 변화한 것을 나타내는 통지를 제공한다.

구문

HRESULT OnPositionChange(
  const RECT *pSourceRect,
  const RECT *pDestinationRect
  );

파라미터

pSourceRect
[in] 비디오의 전송원직사각형에의 포인터.
pDestinationRect
[in] 비디오의 전송처 직사각형에의 포인터. 표시 가능 영역에 맞추어 클리핑 되지 않기 때문에 주의 해야 한다.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는, 클리핑을 동기 갱신할 필요는 없고, 비디오의 전송원위치 또는 전송처 위치가 변경되었을 때에 마셔 알 필요가 있는, 하드웨어 오버레이 카드에서의 사용을 목적으로 하는 콜백이다.

IOverlayNotify::OnClipChange 메소드와 달리, 이 메소드는 윈도우의 변화와 동기 해 불려 가는 것이 아니라, 윈도우가 변화한 후의 임의의 시점에서 (기본적으로는 WM_SIZE 의 메세지가 도착했을 때) 불려 간다. 따라서, 이 메소드는, 데이터를 frame buffer에 찔러넣지 않는 오버레이 카드에 적절하고 있다.


IOverlayNotify2 인터페이스

IOverlayNotify2 인터페이스는,IOverlayNotify 인터페이스로부터 파생한다. IOverlayNotify2 는, 공개되고 있는 윈도우 영역의 변경을 식별해, 렌더링 윈도우의 변경을 알리는 비동기 통지를 제공한다. 아드바이즈 링크는,IOverlayNotify2::OnDisplayChange 통지를 받아들이기 (위해)때문에, 이 인터페이스를 옵션으로 지원 한다.

표시되는 윈도우 영역이 변화했을 때에 통지를 받기 (위해)때문에, 독자적인 드로잉(Drawing) 처리를 실시하는 디코더는,IOverlayNotify2 인터페이스를 이행 해야 한다.

비디오 렌더러는, 이 인터페이스의 메소드를 호출하는 유일한 필터이다. 이 호출은, 디폴트의 렌더러에 의해 자동적으로 행해진다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IOverlayNotify 메소드 | 설명
OnPaletteChange | 윈도우의 팔레트가 변화한 것을 알리는 통지를 제공한다.
OnClipChange | 윈도우의 가시 리젼이 변화한 것을 알리는 통지를 제공한다.
OnColorKeyChange | chroma-key가 변화한 것을 알리는 통지를 제공한다.
OnPositionChange | 위치가 변화한 것을 알리는 통지를 제공한다.
IOverlayNotify2 메소드 | 설명
OnDisplayChange | 표시되는 윈도우 영역이 변화한 것을 알리는 통지를 제공한다.

IOverlayNotify2::OnDisplayChange

IOverlayNotify2 인터페이스

표시되는 윈도우 영역이 변화한 것을 알리는 통지를 제공한다.

구문

HRESULT OnDisplayChange(
    HMONITOR hMonitor
);

파라미터

hMonitor
[in] 오버레이의 표시에 사용하는 모니터의 핸들.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.


IPersistMediaPropertyBag 인터페이스

IPersistMediaPropertyBag 인터페이스는, AVI (Audio-Video Interleaved) 스트림의 INFO 체크 및 DISP 체크를 설정 및 취득한다. 이 인터페이스는,IMediaPropertyBag 인터페이스를 사용해, 체크를 이름/값페어로서 저장 한다.

AVI 스플리터 필터 및 WAV 퍼서 필터는, AVI 파일 또는 WAV 파일로부터 INFO 체크 및 DISP 체크를 읽어내기 (위해)때문에, 이 인터페이스를 지원 한다. AVI Mux 필터는, 이러한 체크를 파일에 기입하기 (위해)때문에, 이 인터페이스를 지원 한다.

IPersistMediaPropertyBag 는,IPersistPropertyBag 인터페이스를 원형으로 하고 있지만, 계승은 하고 있지 않다. 상세한 것에 대하여는, Platform SDK 를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IPersistMediaPropertyBag 메소드 | 설명
InitNew | 미디어 파일의 헤더 정보를 보관 유지하는 새로운 프로퍼티 가방을 초기화한다.
Load | 미디어 파일로부터 프로퍼티를 취득해, 그것을 프로퍼티 가방에 저장 한다.
Save | 미디어 파일의 프로퍼티를 보존한다.

IPersistMediaPropertyBag::InitNew

IPersistMediaPropertyBag 인터페이스

새로운 프로퍼티를 받는 오브젝트를 초기화한다.

구문

HRESULT InitNew(void);

반환값

S_OK 를 돌려준다.

주의

AVI Mux 필터의 이 메소드를 호출하면,Load 메소드를 사용해 직전으로 설정된 프로퍼티가 모두 소거된다.

AVI 스플리터 필터 또는 WAV 퍼서의 이 메소드는, 호출해도 효과가 없다.

IPersistMediaPropertyBag::Load

IPersistMediaPropertyBag 인터페이스

미디어 프로퍼티 가방으로부터 필터에 프로퍼티를 로드한다.

구문

HRESULT Load(
    IMediaPropertyBag *pPropBag
    IErrorLog *pErrorLog
);

파라미터

pPropBag
[in] 호출원으로 생성 한 미디어 프로퍼티 가방의 IMediaPropertyBag 인터페이스에의 포인터.
pErrorLog
[in] 예약이 끝난 상태. 값에 NULL 를 설정한다.

반환값

HRESULT 값을 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
STG_E_ACCESSDENIED | 액세스가 거부되었다.
VFW_E_WRONG_STATE | 필터 그래프가 정지상태태에 없다.

주의

AVI 스트림에 프로퍼티를 기입하려면 ,AVI Mux 필터의 이 메소드를 호출한다. 다음의 샘플 코드는, 스트림에 IART (작자명) INFO 체크를 기입하는 방법을 나타낸다.

IPersistMediaPropertyBag *pPersist = NULL;
IMediaPropertyBag *pBag = NULL;
VARIANT val;

// AVI Mux 필터에 IPersistMediaPropertyBag (비표시)를 조회한다.

CoCreateInstance(CLSID_MediaPropertyBag, NULL, CLSCTX_INPROC,
        IID_IMediaPropertyBag, (LPVOID *) &pBag);

val.vt = VT_BSTR;
val.bstrVal = SysAllocString(L"Author Name");
pBag->Write(L"INFO/IART", &val);
pPersist->Load(pBag, NULL);
VariantClear(&val);

AVI 스플리터 필터 및 WAV 퍼서는, 이 메소드를 지원 하지 않는다.

IPersistMediaPropertyBag::Save

IPersistMediaPropertyBag 인터페이스

필터로부터의 프로퍼티를 미디어 프로퍼티 가방에 보존한다.

구문

HRESULT Save(
    IMediaPropertyBag *pPropBag
    BOOL fClearDirty
    BOOL fSaveAllProperties
);

파라미터

pPropBag
[in] 호출원으로 생성 한 미디어 프로퍼티 가방의 IMediaPropertyBag 인터페이스에의 포인터.
fClearDirty
[in] 예약이 끝난 상태. 임의의 값.
fSaveAllProperties
[in] 예약이 끝난 상태. 임의의 값.

반환값

HRESULT 값을 돌려준다. 설정되는 값은 다음과 같다.

S_OK | 성공.
E_NOTIMPL | 이행되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
HRESULT_FROM_WIN32(ERROR_INVALID_DATA) | 무효인 데이터.

주의

AVI 스플리터 필터 또는 WAV 퍼서의 이 메소드를 호출하면, 필터는 파일로부터 INFO 체크 및 DISP 체크를 읽어내, 그것을 미디어 프로퍼티 가방에 저장 한다. 이러한 체크를 취득하려면 ,IMediaPropertyBag::Read 메소드 또는 IMediaPropertyBag::EnumProperty 메소드를 사용한다.

AVI Mux 필터는 이 메소드를 이행 하지 않는다.


IPin 인터페이스

이 인터페이스는 모든 입력 핀, 출력 핀에 의해 공개된다.

필터 그래프 매니저는 이 인터페이스를 사용해 핀과 접속해, 플래시 처리를 실시한다. 어플리케이션은 이 인터페이스를 사용해 핀의 정보를 문의할 수가 있다. 어플리케이션은 IPin 메소드를 호출해,Connect 나 Disconnect 나 BeginFlush 나 EndFlush 와 같은 핀 상태의 변경을 일어나서는 안 된다. 핀을 접속하려면 , 어플리케이션은 IGraphBuilder 내의 메소드를 사용해야 한다.

필터 개발자 : CBasePin 와 CBaseInputPin 와 CBaseOutputPin 클래스는 이 인터페이스를 이행 한다. 다른 base class는 이것들 3 개의 클래스로부터 파생한다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IPin 메소드 | 설명
Connect | 핀을 다른 핀과 접속한다.
ReceiveConnection | 다른 핀으로부터의 접속을 허가한다.
Disconnect | 현재의 핀 접속을 해제한다.
ConnectedTo | 이 핀에 접속하고 있는 핀을 취득한다.
ConnectionMediaType | 현재의 핀 접속의 미디어 타입을 취득한다.
QueryPinInfo | 이름, 소유자 필터, 방향등의 핀에 대한 정보를 취득한다.
QueryId | 핀 식별자를 취득한다.
QueryAccept | 지정한 미디어 타입을 핀이 허용 할지 어떨지를 확인한다.
EnumMediaTypes | 핀의 우선 미디어 타입을 열거한다.
QueryInternalConnections | 이 핀에 (필터내에서) 내부적으로 접속하고 있는 핀을 취득한다.
EndOfStream | 추가 데이터는 이제 없는 것을 핀에 통지한다.
BeginFlush | 플래시 처리를 시작 한다.
EndFlush | 플래시 처리를 종료한다.
NewSegment | 이 호출의 뒤에 받은 미디어 샘플이 세그먼트(segment) 그룹인 것을 핀에 통지한다.
QueryDirection | 핀의 방향 (입력 핀이나 출력 핀인지)을 취득한다.

IPin::BeginFlush

IPin 인터페이스

플래시 처리를 시작 한다.

구문

HRESULT BeginFlush(void);

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

플래시 처리중에, 필터는 그것이 처리한 어느 데이터도 폐기한다. 플래시가 완료할 때까지 새로운 데이터는 거절된다. 업 스트림 핀이 IPin::EndFlush 를 호출하면, 플래시는 완료한다. 플래시에 의해 이벤트가 보통의 데이터 플로우를 변경 하면나무의 필터 그래프의 리스폰스가 개선된다. 예를 들어, 시크중에 플래시는 행해진다.

BeginFlush 가 불려 가면(자), 필터 그래프는 이하의 스텝을 실시한다 :

  1. IPin::BeginFlush 호출을 다운 스트림에 건네준다.
  2. IMemInputPin::Receive 와 같은 모든 데이터 스트리밍 메소드를 실패시키는 내부 플래그를 설정한다.
  3. 모든 블록이 Receive 메소드에의 호출을 돌려준다.

BeginFlush 통지가 렌더러 필터에 닿으면(자), 렌더러는 보관 유지하고 있는 모든 샘플을 해방한다.

BeginFlush 가 불려 간 후,IPin::EndFlush 메소드가 불려 갈 때까지, 핀은 업 스트림으로부터의 모든 샘플을 받아들이지 않고 S_FALSE 를 돌려준다.

참조

필터 개발자가 사용하는 데이터 플로우

IPin::Connect

IPin 인터페이스

핀을 다른 핀과 접속한다.

구문

HRESULT Connect(
    IPin *pReceivePin,
    const AM_MEDIA_TYPE *pmt
);

파라미터

pReceivePin
[in] 핀의 IPin 인터페이스를 받는 포인터.
pmt
[in] 접속의 미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터. NULL 가 가능.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
VFW_E_ALREADY_CONNECTED | 핀은 이미 접속되고 있다.
VFW_E_NO_ACCEPTABLE_TYPES | 허가된 미디어 타입을 찾아낼 수가 없었다.
VFW_E_NOT_STOPPED | 필터가 액티브해, 핀이 동적재접속을 지원 하고 있지 않다.
VFW_E_TYPE_NOT_ACCEPTED | 지정한 미디어 타입은 허가되지 않는다.

주의

pmt 파라미터는 NULL 가 가능. 메이저 타입이나 서브 타입이나 포맷에 GUID_NULL 의 값을 넣어 부분적 미디어 타입을 지정하는 일도 가능.

이 메소드는 접속이 가능한 일을 검증한다. 핀이 접속을 거부하면, 메소드는 실패한다. 수신 핀으로 IPin::ReceiveConnection 를 호출하는 것으로, 접속 핀은 미디어 타입을 제안한다.

IPin::ConnectedTo

IPin 인터페이스

만약 있으면, 이 핀에 접속하고 있는 핀을 취득한다.

구문

HRESULT ConnectedTo(
    IPin **ppPin
);

파라미터

ppPin
[out] 다른 핀의 IPin 인터페이스에의 포인터를 받는 변수의 주소. NULL 는 불가.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

메소드가 성공하면, 그것을 돌려주는 IPin 인터페이스는 참조 카운트가 남는다. 사용후, 해방에 주의.

IPin::ConnectionMediaType

IPin 인터페이스

현재의 핀 접속의 미디어 타입을 취득한다.

구문

HRESULT ConnectionMediaType(
    AM_MEDIA_TYPE *pmt
);

파라미터

pmt
[out] 미디어 타입을 받는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

핀이 접속되면(자), 이 메소드는 pmt 에가 지정하는 AM_MEDIA_TYPE 구조체에 미디어 타입을 카피한다. 호출원래는 미디어 타입의 포맷 블록을 해방해야 한다. Microsoft® Win32® CoTaskMemFree 함수인가,FreeMediaType 헬퍼 함수를 사용할 수 있습니다.

핀이 접속되지 않으면 이 메소드는 pmt 가 지정하는 미디어 타입을 클리어 해, 에러 코드를 돌려준다.

IPin::Disconnect

IPin 인터페이스

현재의 핀 접속을 해제한다.

구문

HRESULT Disconnect(void);

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_FALSE | 핀이 접속되어 있지 않았다.
S_OK | 성공.
VFW_E_NOT_STOPPED | 필터가 액티브.

주의

필터가 포즈나 실행중이라면, 이 메소드는 실패한다. 핀이 IPinConnection 인터페이스를 지원 한다면, 필터가 포즈나 실행중 때,IPinConnection::DynamicDisconnect 를 호출해 핀의 접속을 해제하는 것.

핀은 이 메소드를 사용해 접속 해제를 해서는 안 된다.

IPin::EndFlush

IPin 인터페이스

플래시 처리를 종료한다.

구문

HRESULT EndFlush(void);

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드가 불려 갈 때, 필터는 이하의 처리를 한다 :

  1. 큐에 있는 모든 샘플의 폐기를 기다린다.
  2. 버퍼에 있는 모든 데이터를 해방한다.
  3. 남아 있는 EC_COMPLETE 통지를 클리어 한다.
  4. EndFlush 다운 스트림을 호출한다.

메소드가 돌아가면(자), 핀은 새로운 샘플을 허가한다.

참조

필터 개발자가 사용하는 데이터 플로우

IPin::EndOfStream

IPin 인터페이스

새로운 실행 커멘드가 필터에 발행될 때까지는, 추가 데이터는 이제 없는 것을 핀에 통지한다.

구문

HRESULT EndOfStream(void);

반환값

이하의 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_UNEXPECTED | 핀은 이 메소드를 지원 하고 있지 않다.

주의

이 메소드는 입력 핀에서만 호출하는 것. 출력 핀은 E_UNEXPECTED 를 돌려준다.

이 메소드는 엔드 오브 스트림 (end-of-stream) 통지를 핀에 보낸다. 핀은 그 통지를 다운 스트림에 보낸다. IMemInputPin::Receive 를 호출해 엔드 오브 스트림 통지를 계속해 처리해야 한다. 핀이 출력해야 할 미디어 샘플을 큐에 넣는다면, 엔드 오브 스트림 통지도 이와 같이 큐에 넣어야 하는 것이다. IPin::BeginFlush 메소드는 큐내의 모든 엔드 오브 스트림 통지를 플래시 한다.

IPin::EnumMediaTypes

IPin 인터페이스

핀의 우선 미디어 타입을 열거한다.

구문

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

파라미터

ppEnum
[out] IEnumMediaTypes 인터페이스에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

IEnumMediaTypes 인터페이스는 표준 COM 열거자와 같이 동작한다. 상세한 것에 대하여는, 「Enumerating Objects in a Filter Graph 」를 참조할것. 메소드가 성공하면(자),IEnumMediaTypes 인터페이스에 참조 카운트가 남는다. 사용후, 해방에 주의.

IPin::NewSegment

IPin 인터페이스

이 호출의 뒤에 받은 미디어 샘플이, 공통의 시작 타임과 종료 타임과 레이트를 가지는 세그먼트(segment) 그룹인 것을 핀에 통지한다.

구문

HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

파라미터

tStart
세그먼트(segment)의 시작 타임, 오리지날 소스의 상대값, 100 나노초단위.
tStop
세그먼트(segment)의 종료 타임, 오리지날 소스의 상대값, 100 나노초단위
dRate
세그먼트(segment)가 처리되는 레이트, 오리지날 레이트의 퍼센티지.

반환값

성공이라면 S_OK 를 돌려준다, 혹은 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

새로운 스트림을 시작 할 때와 시크 조작이 끝날 때마다, 소스 필터 (혹은 퍼서 필터)는 이 메소드를 호출한다. 이전의 데이터 배치를 출력한 다음에, 새로운 데이터로 IMemInputPin::Receive 를 호출하기 전에, 그것은 다운 스트림 필터의 입력 핀의 메소드를 호출한다. 다운 스트림 필터는 NewSegment 호출을 다운 스트림에 계승한다.

필터는 세그먼트(segment) 정보를 사용해 샘플을 처리한다. 예를 들어, 몇개의 포맷에서는 다음의 프레임없이 델타 프레임을 재구축 할 수 없다. 그러므로, 종료 타임이 델타 프레임에 있으면(자), 소스 필터는 추가 프레임을 보내지 않으면 안 된다. 디코더 필터는 세그먼트(segment) 정보를 기본으로 최종 프레임을 결정한다. 예를 들어, 오디오 렌더러는 샘플링 레이트와 세그먼트(segment) 레이트를 사용해, 오디오 데이터를 올바르게 렌더링 한다.

IPin::QueryAccept

IPin 인터페이스

지정한 미디어 타입을 핀이 허용 할지 어떨지를 확인한다.

구문

HRESULT QueryAccept(
    const AM_MEDIA_TYPE *pmt
);

파라미터

pmt
[in] 미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

미디어 타입이 허용 된다면 S_TRUE 를 돌려준다. 그렇지 않으면, S_FALSE 를 돌려준다.

주의

S_OK 가 돌아간다면, 필터 실행중에 핀이 지정한 포맷으로 변경할 수 있는 것이 보증된다. 필터 실행중으로 포맷을 변경할 필요가 있어, 핀이 IPinConnection 를 지원 한다면,IPinConnection::DynamicQueryAccept 메소드를 호출하는 것.

IPin::QueryDirection

IPin 인터페이스

핀의 방향 (입력 핀이나 출력 핀인지)을 취득한다.

구문

HRESULT QueryDirection(
    PIN_DIRECTION *pPinDir
);

파라미터

pPinDir
[out] PIN_DIRECTION 열거형의 멤버를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

IPin::QueryId

IPin 인터페이스

핀 식별자를 취득한다

구문

HRESULT QueryId(
    LPWSTR *Id
);

파라미터

Id
[out] 핀 식별자가 들어가는 캐릭터 라인을 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는 그래프 영속성을 지원 한다. 이 메소드를 사용해 핀 상태를 보존해,IBaseFilter::FindPin 메소드를 사용해 그 상태를 restore 하는 것. 핀 식별 캐릭터 라인은 필터 이행에 의해 정의되고 있다. 그 식별자는 필터내에서 독특하지 않으면 안 된다.

주 핀 ID 는 반드시QueryPinInfo 메소드가 돌려주는 핀명 과 같지 않다.

필터는 Microsoft® Win32® CoTaskMemAlloc 함수를 사용해 돌아간 캐릭터 라인을 할당한다. 호출원래는 CoTaskMemFree 를 사용해 그것을 해방해야 한다.

IPin::QueryInternalConnections

IPin 인터페이스

이 핀에 (필터내에서) 내부적으로 접속하고 있는 핀을 취득한다.

구문

HRESULT QueryInternalConnections(
    IPin **apPin,
    ULONG *nPin
);

파라미터

apPin
[out] IPin 포인터의 배열의 주소.
nPin
[in, out] 입력시는 배열의 사이즈를 지정한다. 메소드가 돌아가면(자), 이 값은 배열내에 돌아가는 포인터의 수가 세트 된다.

반환값

이하의 HRESULT 값의 1 개를 돌려준다.

S_FALSE | 부적절한 배열 사이즈.
S_OK | 성공.
E_FAIL | 실패.
E_NOTIMPL | 이행되어 있지 않다.

주의

몇개의 필터에서는, 입력 핀은 고유의 출력 핀에 대응하고 있다. 각 핀에 대해, 이 메소드는 대응하는 핀에의 포인터의 배열을 기입한다. 각 입력 핀이 각 출력 핀에 데이터를 제공한다면, 핀은 E_NOTIMPL 를 돌려준다.

메소드가 성공해, 제로 이상의 *nPin 값을 돌려주면(자), 그 배열에는 IPin 인터페이스에의 포인터가 들어간다. 사용후, 각 인터페이스 포인터의 해방에 주의 해야 한다.

IPin::QueryPinInfo

IPin 인터페이스

핀에 대한 정보를 취득한다.

구문

HRESULT QueryPinInfo(
    PIN_INFO *pInfo
);

파라미터

pInfo
[out] 핀 정보를 받는 PIN_INFO 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

주의

메소드가 돌아갈 때, PIN_INFO 구조체의 pFilter 멤버가 NULL 이외라면, 참조 카운트가 남는다. 사용후 인터페이스의 해방에 주의 해야 한다.

IPin::ReceiveConnection

IPin 인터페이스

다른 핀으로부터의 접속을 허가한다.

구문

HRESULT ReceiveConnection(
    IPin *pConnector,
    AM_MEDIA_TYPE *pmt
);

파라미터

pConnector
[in] 접속하고 있는 핀의 IPin 인터페이스에의 포인터.
pmt
[in] 접속의 미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_ALREADY_CONNECTED | 핀은 이미 접속하고 있다.
VFW_E_NOT_STOPPED | 필터가 액티브한 동안은 접속할 수 없다.
VFW_E_TYPE_NOT_ACCEPTED | 지정한 미디어 타입이 허가되지 않는다.

주의

접속을 초기화하는 핀은 이 메소드를 수신 핀으로 호출한다. 수신 핀이 에러 코드를 돌려준다면, 접속은 실패한다.


IPinConnection 인터페이스

이 인터페이스는, 필터가 아직 실행중 때에 입력 핀을 재접속하는 메소드를 제공한다. 필터 그래프는, 동적인 재접속을 실행 하면 와, 이 인터페이스의 메소드를 호출한다 ( 「IGraphConfig 인터페이스」를 참조할것). 상세한 것에 대하여는, 「동적 그래프 생성」을 참조할것.

필터 개발자에게 : 동적인 재접속, 또는 포맷의 동적인 변경을 허락하는 모든 입력 핀에, 이 인터페이스를 이행 하는 것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IPinConnection 메소드 | 설명
DynamicQueryAccept | 현재 이 핀에 접속하고 있는 그래프의 실행중에, 지정된 미디어 타입을 핀이 받아들일 수가 있을지 어떨지를 조회한다.
NotifyEndOfStream | 다음에 엔드 오브 스트림 조건이 발생했을 때 통지하도록(듯이) 핀에 요구한다.
IsEndPin | 재접속의 검색을 이 핀으로 종료해야할 것인가 제발을 나타낸다.
DynamicDisconnect | 필터 실행중에 핀을 절단 한다.

IPinConnection::DynamicDisconnect

IPinConnection 인터페이스

필터가 액티브한 때 (포즈중 또는 실행중)에 핀을 절단 한다. 액티브한 필터의 핀을 절단 하려면 ,IPin::Disconnect 는 아니고 이 메소드를 호출한다.

구문

HRESULT DynamicDisconnect(void)

반환값

핀이 접속되고 있어, 메소드가 성공했을 경우, 반환값은 S_OK 가 된다. 핀이 접속되지 않았던 경우, 반환값은 S_FALSE 가 된다.

메소드가 성공했을 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

IPinConnection::DynamicQueryAccept

IPinConnection 인터페이스

현재 이 핀에 접속하고 있는 그래프의 실행중에, 지정된 미디어 타입을 핀이 받아들일 수가 있을지 어떨지를 조회한다.

구문

HRESULT DynamicQueryAccept(
    const AM_MEDIA_TYPE *pmt
);

파라미터

pmt
[in] 미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 미디어 타입을 받아들일 수 있다.
VFW_E_TYPE_NOT_ACCEPTED | 미디어 타입을 받아들일 수 없다.

주의

이 메소드가 성공했을 경우, 핀은, 다음의 샘플 위에의 미디어 타입, 또는 IPin::ReceiveConnection 의 호출로 지정되는 미디어 타입을 받아들일 수가 있다.

어플리케이션 또는 필터에서는, 이 메소드를 호출해, 필터 그래프를 복구성 할 필요가 있을지 어떨지 판단할 수 있다. 지정한 미디어 타입을 핀이 받아들일 수가 있다면, 그래프를 복구성 할 필요는 없다.

IPin::QueryAccept 메소드는, 핀이 포맷 타입을 받아들일 수가 있을지 어떨지도 판단한다. 다만, 포맷 타입 받아들일 수 있어도, 필터 실행중에 핀이 그 포맷에 바뀔 수가 있다고는 할 수 없다. 필터 실행중에 포맷을 바꿀 필요가 있는 경우는, 대신에 DynamicQueryAccept 를 호출한다.

IPinConnection::IsEndPin

IPinConnection 인터페이스

재접속의 검색을 이 핀으로 종료해야할 것인가 제발을 나타낸다.

구문

HRESULT IsEndPin(void);

반환값

성공했을 경우는, 다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 미디어 타입을 받아들일 수 없다.
S_OK | 미디어 타입을 받아들일 수 있다.

그 이외의 경우는, 발생한 에러를 나타내는 에러 코드를 돌려준다.

주의

필터 또는 어플리케이션에서는, 이 메소드를 호출해, 핀이 동적인 재접속의 후보가 될 수 있을지 어떨지를 판단할 수 있다.

보통, 세면대 필터와 데이터를 분할 또는 머지 하는 필터는, S_OK 를 돌려주지 않으면 안 된다. 그 외의 필터 (예를 들어 단순한 변환 필터)는, S_FALSE 를 돌려주지 않으면 안 된다.

IPinConnection::NotifyEndOfStream

IPinConnection 인터페이스

다음에 엔드 오브 스트림 조건이 발생했을 때 통지하도록(듯이) 핀에 요구한다.

구문

HRESULT NotifyEndOfStream(
    HANDLE hNotifyEvent
);

파라미터

hNotifyEvent
[in] 핀이 통지하는 이벤트 오브젝트의 핸들.

반환값

성공했을 경우는, 다음의 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 이벤트 핸들이 NULL 이지만, 리셋 하는 이벤트 핸들이 존재하지 않았다.
S_OK | 이벤트 핸들이 설정되었다 (이벤트 핸들이 NULL 의 경우, 이벤트 통지는 삭제된다).

그 이외의 경우는, 발생한 에러를 나타내는 에러 코드를 돌려준다.

주의

이 메소드를 사용 하면, 필터 그래프의 이 핀까지의 부분을 통해서, 호출원이 데이터를 인도할 수가 있다.

예를 들어, 호출원이, 어느 필터의 출력 핀 "A" 로부터 다른 필터의 입력 핀 "B" 에, 필요에 따라서 그것들을 접속하는 중간 필터를 사용해 데이터를 인도하는 경우를 생각한다. 이 때, 다음의 일련의 이벤트가 발생한다.

  1. 호출원이, 핀 A 로 데이터를 블록 한다.
  2. 핀 B 의 IPinConnection::NotifyEndOfStream 를 호출한다.
  3. 핀 A 에 접속되고 있는 입력 핀의 IPin::EndOfStream 를 호출한다.
  4. 나머지의 데이터가 중간 필터를 통해서 다운 스트림에 흘러 가면(자), 그러한 필터가 엔드 오브 스트림 통지를 전달한다.
  5. 핀 B 는, 엔드 오브 스트림 통지를 받으면(자),hNotifyEvent 파라미터로 지정된 이벤트를 통지한다. 그 시점에서, 호출원래는 핀 A 와 핀 B 의 사이의 그래프를 안전하게 복구성 할 수 있다.

이 메소드의 목적은, 호출원으로부터 그래프를 동적으로 재구축 해, 접속을 재개하는 것에 있기 (위해)때문에, 엔드 오브 스트림 통지는 스트림 실제의 종료를 의미하지 않는다. 따라서, 핀 B 는, 엔드 오브 스트림 조건을 전달하는 일도, EC_COMPLETE 를 통지할 것도 없다. 필터 그래프내에서의 데이터의 흘러에 있어서의 보통의 규칙으로부터 보면(자), 이것은 예외적인 동작이다.

이 메소드를 한번 더 이벤트 핸들 NULL 로 호출해 통지를 취소하는 것은, 호출원의 책임이다.

필터 그래프에서는,IGraphConfig::Reconnect 메소드내에서 이 메소드를 호출한다. 어플리케이션 또는 필터로 (IGraphConfig::Reconfigure 메소드를 사용해) 그래프에 어떠한 특수한 동적 복구성을 실시하는 경우는, 복구성 하는 그래프의 부분을 통해서 데이터를 인도하기 (위해)때문에, 최초로 이 메소드를 호출할 가능성이 있다.


IPinFlowControl 인터페이스

액티브한 출력 핀으로부터 데이터 플로우를 블록 한다. 이 인터페이스는 동적재접속 가능한 출력 핀에 의해 공개된다. 이 인터페이스를 사용해 필터 그래프없이 동적재접속을 시작 한다. 상세한 것에 대하여는, 「동적 그래프 생성」을 참조할것.

필터 개발자에게 : 동적인 재접속을 지원 하는 퍼서 필터와 캡춰 필터에서는, 그 출력 핀상에서 이 인터페이스를 지원 해야 한다. 보통, 그 외의 타입의 필터에서는, 이 인터페이스를 이행 할 필요는 없다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IPinFlowControl 메소드 | 설명
Block | 핀으로부터의 데이터 플로우를 블록, 혹은 블록 해제한다.

IPinFlowControl::Block

IPinFlowControl 인터페이스

핀으로부터의 데이터 플로우를 블록, 혹은 블록 해제한다.

구문

HRESULT Block(
    DWORD dwBlockFlags,
    HANDLE hEvent,
);

파라미터

dwBlockFlags
[in] 핀을 블록 할까 블록 해제하는지를 나타내는 플래그. 이하의 값이 아니면 안된다 :
  • 제로 : 핀으로부터의 데이터 플로우를 블록 해제한다.
  • AM_PIN_FLOW_CONTROL_BLOCK: 핀으로부터의 데이터 플로우를 블록 한다.
hEvent
[in] 이벤트 오브젝트의 핸들 또는 NULL. 이 파라미터가 NULL 가 아닌 경우, 메소드는 비동기가 되어, 즉석에서 돌아온다. 조작이 완료 하면, 이벤트가 통지제가 된다. 이 파라미터가 NULL 의 경우, 메소드는 동기가 되어, 핀이 블록 될 때까지 완료하지 않는다. dwBlockFlags 가 제로라면, 이 파라미터는 NULL 가 아니면 안된다.

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값.

S_FALSE | 핀은 이미 블록 해제되고 있다.
S_OK | 성공.
VFW_E_PIN_ALREADY_BLOCKED | 핀은 다른 thread에 의해 이미 블록 되고 있다.
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | 핀은 호출하고 있는 thread에 의해 이미 블록 되고 있다.

주의

이 메소드는 동기도 비동기도 가능하다 :

  • 비동기에게 호출하려면 ,CreateEvent 함수를 사용해 이벤트 오브젝트를 생성 한다. 이벤트 핸들을 hEvent 파라미터에 건네준다. 메소드는 곧바로 돌아와, 조작이 완료 하면 이벤트를 통지한다. WaitForSingleObject 와 같이 기다려 함수를 호출해 그 이벤트를 기다리는 것.
  • 동기 해 호출하려면 ,hEvent 파라미터를 NULL 로 설정한다. 그 메소드는 완료할 때까지 블록 한다. 메소드는 핀이 샘플 출력할 준비를 할 수 있을 때까지 완료하지 않을 가능성이 있다. 필터가 포즈라면, 메소드는 완전하게 블록 할 가능성이 있다. 그러므로, 메인의 어플리케이션 thread로부터 이 메소드를 동기 해 호출해서는 안된다.


IPinInfo 인터페이스

이 인터페이스는, 핀에 관한 정보의 취득 및 핀의 접속을 실시하는 Automation 호환의 메소드를 제공한다. 필터 그래프 매니저가 이 인터페이스를 공개한다.

Microsoft® Visual Basic® 어플리케이션에서는, 이 인터페이스를 사용해, 핀에 관한 정보 (미디어 타입, 핀의 방향등)를 취득할 수 있다. 또, 필요에 따라서 중간 필터를 사용해 핀을 접속할 수도 있다.

C/C++ 어플리케이션에서는, 이 인터페이스는 아니고,IGraphBuilder 인터페이스 및 IPin 인터페이스를 사용하는 것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IPinInfo 메소드 | 설명
get_Pin | IPin 인터페이스를 지원 하는 핀 오브젝트를 취득한다.
get_ConnectedTo | 이 핀이 접속하고 있는 대응하는 핀에 대응하는 IPinInfo 오브젝트를 취득한다.
get_ConnectionMediaType | 이 접속의 미디어 타입을 취득한다.
get_FilterInfo | 이 핀이 속하는 필터에 대응하는 IFilterInfo 오브젝트를 취득한다.
get_Name | 이 핀의 이름을 취득한다.
get_Direction | 핀의 방향을 취득한다.
get_PinID | 핀 식별자를 취득한다.
get_MediaTypes | 이 핀이 지원 하는 우선 미디어 타입에의 액세스를 제공하는 IAMCollection 인터페이스를 취득한다.
Connect | 지정된 핀에 접속한다.
ConnectDirect | 지정된 핀에 직접 접속한다.
ConnectWithType | 지정된 미디어 타입만을 사용해, 지정된 핀에 직접 접속한다.
Disconnect | 이 핀을 접속처의 핀으로부터 절단 한다.
Render | 핀의 미디어 타입을 렌더링 할 수 있는 필터 그래프를 생성 한다.

IPinInfo::Connect

IPinInfo 인터페이스

필요에 따라서 다른변환 필터를 사용해, 지정된 핀에 접속한다.

구문

HRESULT Connect(
    IUnknown *pPin
    );

파라미터

pPin
[in] 접속처의 핀에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

pPin 파라미터는,IPin 에서도 IPinInfo 오브젝트라도 좋다. 이 메소드는, 이 핀과 지정된 핀과의 접속을 유효하게 하기 위해서 필요한 변환 필터를, 그래프 빌더를 사용하고 판단한다. 예를 들어, 핀이소스 필터의 출력 핀이며, 요구된 접속처가 비디오 렌더러의입력 핀인 경우는, 유효한 필터 그래프로 하기 위해서(때문에), 적절한 미디어 타입을 가지는 데콘프렛사피르타를 삽입한다. 이 메소드는, 본래,IGraphBuilder::Connect 메소드에 대응하는 Automation 래퍼이다.

IPinInfo::ConnectDirect

IPinInfo 인터페이스

중간 필터를 사용하지 않고 , 소정의 핀에 직접 접속한다.

구문

HRESULT ConnectDirect(
  IUnknown *pPin
  );

파라미터

pPin
[in] 직접 접속하는 접속처의 핀에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

접속하는 핀의 사이에 공통의 미디어 타입을 결정할 수 없는 경우, 이 메소드는 에러를 돌려준다. 이 메소드는, 본래,IFilterGraph::ConnectDirect 메소드에 대응하는 Automation 래퍼이다.

IPinInfo::ConnectWithType

IPinInfo 인터페이스

지정된 미디어 타입을 사용해, 지정된 핀에 직접 접속한다.

구문

HRESULT ConnectWithType(
  IUnknown *pPin,
  IDispatch *pMediaType
  );

파라미터

pPin
[in] 접속처의 핀에의 포인터. pPin 는,IPin 인터페이스 및 IPinInfo 인터페이스의 어느 쪽인지를 지원 하는 오브젝트가 아니면 안된다.
pMediaType
[in] 핀의 접속에 사용하는 미디어 타입에의 포인터. pMediaType 는,IMediaTypeInfo 인터페이스를 지원 할 필요가 있다.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면, 접속의 미디어 타입을 접속시에 핀측에서 결정하는 것이 아니라, 호출원으로 결정할 수가 있다.

IPinInfo::Disconnect

IPinInfo 인터페이스

이 핀을 접속처의 핀으로부터 절단 한다.

구문

HRESULT Disconnect(void);

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 양쪽 모두의 핀의 IPin::Disconnect 를 호출한다.

IPinInfo::get_ConnectedTo

IPinInfo 인터페이스

접속처의 핀에 대응하는 IPinInfo 인터페이스를 취득한다.

구문

HRESULT get_ConnectedTo(
  IDispatch **ppUnk
  );

파라미터

ppUnk
[out, retval] 핀에 대응하는 IPinInfo 인터페이스에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 본래,IPin::ConnectedTo 메소드에 대응하는 Automation 래퍼이다.

IPinInfo::get_ConnectionMediaType

IPinInfo 인터페이스

connection 정보가 저장 된 IMediaTypeInfo 오브젝트를 취득한다.

구문

HRESULT get_ConnectionMediaType(
  IDispatch **ppUnk
  );

파라미터

ppUnk
[out, retval] 돌려주어진 IMediaTypeInfo 인터페이스에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 본래,IPin::ConnectionMediaType 메소드에 대응하는 Automation 래퍼이다.

IPinInfo::get_Direction

IPinInfo 인터페이스

핀의 방향을 취득한다.

구문

HRESULT get_Direction(
  LONG *ppDirection
  );

파라미터

ppDirection
[out, retval] 핀의 방향에의 포인터의 주소. 핀의 방향은, PINDIR_INPUT 와 PINDIR_OUTPUT 의 어느 쪽인지이다.

반환값

HRESULT 값을 돌려준다.

IPinInfo::get_FilterInfo

IPinInfo 인터페이스

이 핀이 속하는 필터에 대응하는 IFilterInfo 인터페이스를 취득한다.

구문

HRESULT get_FilterInfo(
  IDispatch **ppUnk
  );

파라미터

ppUnk
[out, retval] 취득된 IFilterInfo 인터페이스에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

IPinInfo::get_MediaTypes

IPinInfo 인터페이스

이 핀이 지원 하는 우선 미디어 타입에의 액세스를 제공하는 IAMCollection 인터페이스를 취득한다.

구문

HRESULT get_MediaTypes(
  IDispatch **ppUnk
  );

파라미터

ppUnk
[out, retval] IMediaTypeInfo 오브젝트로서 우선되는 미디어 타입이 저장 된 IAMCollection 인터페이스에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 본래,IPin::EnumMediaTypes 메소드에 대응하는 Automation 래퍼이다.

IPinInfo::get_Name

IPinInfo 인터페이스

이 핀의 이름을 취득한다.

구문

HRESULT get_Name(
  BSTR **ppUnk
  );

파라미터

ppUnk
[out, retval] 핀의 이름에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

IPinInfo::get_Pin

IPinInfo 인터페이스

IPin 인터페이스를 지원 하는 핀 오브젝트를 취득한다.

구문

HRESULT get_Pin(
  IUnknown **ppUnk
  );

파라미터

ppUnk
[out, retval] IPin 를 지원 하는 IUnknown 오브젝트에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

주의

IPinInfo 인터페이스는, 래퍼 COM 오브젝트로 이행 된다. 따라서, 이 오브젝트의 IPin 를 조회하는 QueryInterface 는 실패한다. IPinInfo::get_Pin 메소드가 돌려주는 핀 오브젝트로,IPin 인터페이스가 지원 된다.

IPinInfo::get_PinID

IPinInfo 인터페이스

핀의 식별자를 취득한다.

구문

HRESULT get_PinID(
  BSTR *strPinID
  );

파라미터

strPinID
[out, retval] 핀의 식별자 캐릭터 라인에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

strPinID 에 돌려주어진 캐릭터 라인은,IFilterInfo::FindPin 에 건네줄 수가 있다. 이 식별자는, 핀의 이름과 동일한 일이 많지만, 다른 경우도 있다. 2 차 기억에 기입해, 나중에 필터의 다른 인스턴스에 포함되는 같은 핀의 식별로 사용할 수가 있다.

IPinInfo::Render

IPinInfo 인터페이스

이 핀의 출력을 렌더링 하기 위해서, 필요에 따라서 변환 필터 및 렌더링 필터를 사용해, 필터 끼리를 접속한다.

구문

HRESULT Render(void);

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 본래,IGraphBuilder::Render 메소드에 대응하는 Automation 래퍼이다. 또, 이 메소드는 출력 핀에서만 유효하다.


IQualityControl 인터페이스

이 인터페이스는,품질 컨트롤의 지원을 제공한다. 품질 컨트롤 메세지를 생성 또는 취득할 수 있는 오브젝트는, 이 인터페이스를 공개한다. 그러한 오브젝트에는, 렌더링 필터 (보통, 품질 컨트롤 메세지를 생성한다), 핀 (그것들을 받는다), 및 외부의 품질 매니저 (역시 그것들을 받는다)가 포함된다.

렌더링 필터는, 업 스트림 필터의 출력 핀의 IQualityControl::Notify 메소드를 호출해, 품질 컨트롤 메세지를 생성한다. 업 스트림 필터는, 그 메세지를 처리하는지, 또는 업 스트림에 건네준다.

어플리케이션에서는, 독자적인 품질 컨트롤 매니저를 이행 할 수 있다. 품질 컨트롤 메세지의 수신자로서 그 품질 컨트롤 매니저를 지정하려면 , 렌더러의 IQualityControl::SetSink 를 호출한다. 이 메소드를 호출하면, 품질 컨트롤 메세지의 디폴트 처리가 오버라이드(override) 된다.

다만, 많은 어플리케이션에서는, 독자적인 품질 컨트롤 매니저를 이행 하지 않는다. 따라서, 이 특수한 케이스를 제외해, 보통, 어플리케이션으로 이 인터페이스를 사용할 것은 없다. 상세한 것에 대하여는, 「품질 컨트롤의 관리」를 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IQualityControl 메소드 | 설명
Notify | 품질의 변경이 요구된 것을 수신자에게 통지한다.
SetSink | 품질 메세지를 받아들이는 IQualityControl 오브젝트를 설정한다.

IQualityControl::Notify

IQualityControl 인터페이스

품질의 변경이 요구된 것을 필터에 통지한다.

구문

HRESULT Notify(
    IBaseFilter *pSelf,
    Quality q
);

파라미터

pSelf
[in] 품질 통지의 송신원필터에의 포인터.
q
[in] 품질 통지의 구조체.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IQualityControl::SetSink

IQualityControl 인터페이스

품질 메세지를 받아들이는 IQualityControl 오브젝트를 설정한다.

구문

HRESULT SetSink(
    IQualityControl *piqc
);

파라미터

piqc
통지의 송신지 IQualityControl 오브젝트에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드의 호출을 받는 필터는,piqc 를 기록해야 하지만, 거기에 참조 카운트를 추가해서는 안 된다. 포인터가 가리키는 오브젝트는, 품질 매니저이며, 필터 그래프 (예를 들어,PID )의 일부이다. 여기에 참조 카운트를 추가 하면, 순환 참조의 위험성이 있다.

piqc 로 지정된 오브젝트의 참조는, 이 메소드가 값 NULL 로 불려 가까지, 유효하다라고 하는 것이 보증된다.


IQualProp 인터페이스

이 인터페이스는, 비디오 렌더러로부터 퍼포먼스 정보를 취득하는 메소드를 제공한다. 인터페이스를 통해서 돌려주어지는 값은, 필터를 정지할 때마다 리셋 된다. 비디오 렌더링 필터 및풀 스크린 렌더링 필터는, 이 인터페이스를 공개한다.

어플리케이션에서는, 이 인터페이스를 사용해 비디오의 퍼포먼스 정보를 취득할 수 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IQualProp 메소드 | 설명
get_AvgFrameRate | 달성된 평균 frame rate를 취득한다.
get_AvgSyncOffset | 프레임의 목표 렌더링 시간과 렌더링이 실제로 시작 한 시간의 평균 시간차이를 취득한다 (밀리 세컨드 단위의 값으로 돌려주어진다).
get_DevSyncOffset | 프레임의 목표 렌더링 시간과 렌더링이 실제로 시작 한 시간의 평균 시간차이를 취득한다 (표준 편차로 돌려주어진다).
get_FramesDrawn | 스트림 시작 후에 드로잉(Drawing) 된 프레임수를 취득한다.
get_FramesDroppedInRenderer | 렌더러로 드롭 된 프레임수를 취득한다.
get_Jitter | 비디오 렌더러에게 건네지는 연속 프레임간의 평균 시간을 표현한다.

IQualProp::get_AvgFrameRate

IQualProp 인터페이스

스트림 시작 후의 평균 frame rate를 취득한다.

구문

HRESULT get_AvgFrameRate(
    int *piAvgFrameRate
    ) PURE;

파라미터

piAvgFrameRate
스트림 시작 후의 1 초 쯤의 프레임수 (fps)에의 포인터.

반환값

HRESULT 값을 돌려준다.

IQualProp::get_AvgSyncOffset

IQualProp 인터페이스

비디오 프레임의 목표 표시 시간과 실제로 표시된 시간과의 평균 시간차이를 취득한다.

구문

HRESULT get_AvgSyncOffset(
    int *piAvg
    );

파라미터

piAvg
시간차이 (밀리 세컨드 단위)에의 포인터.

반환값

HRESULT 값을 돌려준다.

IQualProp::get_DevSyncOffset

IQualProp 인터페이스

비디오 프레임의 목표 표시 시간과 실제로 표시된 시간과의 평균 시간차이를 취득한다. 이 메소드는, 값이 단순한 평균은 아니고 표준 편차로 돌려주어지는 점을 제외해,IQualProp::get_AvgSyncOffset 메소드와 같다.

구문

HRESULT get_DevSyncOffset(
    int *piDev
    );

파라미터

piDev
표시되는 비디오 프레임의 정밀도를 나타내는 값에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

네트워크로부터의 비디오를 재생 하면 와, 네트워크 상태가 나쁜 경우에는 표시가 중단하는 일이 있다. 이 때문에, 비디오 프레임의 정밀도를 단순한 평균치로 표현하는 것은 적절하지 않다. 표준 편차를 조사하면(자), 전체의 정밀도를 보다 올바르게 파악할 수 있다.

IQualProp::get_FramesDrawn

IQualProp 인터페이스

스트림 시작 후에 드로잉(Drawing) 된 프레임수를 취득한다.

구문

HRESULT get_FramesDrawn(
    int *pcFramesDrawn
    );

파라미터

pcFramesDrawn
스트림 시작 후에 드로잉(Drawing) 된 프레임수에의 포인터.

반환값

HRESULT 값을 돌려준다.

IQualProp::get_FramesDroppedInRenderer

IQualProp 인터페이스

렌더러로 드롭 된 프레임수를 취득한다.

구문

HRESULT get_FramesDroppedInRenderer(
    int *pcFrames
    );

파라미터

pcFrames
렌더러로 드롭 된 프레임수에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

프로퍼티 페이지에서는, 이 메소드를 사용해 렌더러로부터 데이터가 취득된다.

IQualProp::get_Jitter

IQualProp 인터페이스

비디오 렌더러에게 건네지는 연속 프레임간의 평균 시간을 표현한다.

구문

HRESULT get_Jitter(
    int *piJitter
    );

파라미터

piJitter
프레임간 시간 (밀리 세컨드 단위)의 표준 편차에의 포인터.

반환값

HRESULT 값을 돌려준다.


IQueueCommand 인터페이스

특정의 시간에 처리하기 위해서 커멘드를 큐에 넣는다. 필터 그래프 매니저는 그것을 사용해 그래프 관리 커멘드를 먼저 큐에 넣을 수가 있다.

IQueueCommand 내의 메소드는 IDispatch::InvokeAt 메소드의 다음에 설계되었다. 어플리케이션은 인터페이스와 인터페이스의 메소드와 메소드의 파라미터와 기준 타임을 지정한다. 필터 그래프 매니저는 이 정보를 큐에 넣어 다음으로 지정한 시간에 이 메소드를 기동한다. 리퀘스트 된 인터페이스는 IDispatch 를 계승해, 필터 그래프 매니저에 의해 공개되지 않으면 안 된다. 예로서는 IMediaControl ,IMediaEventEx , 및 IMediaPosition 를 들 수 있다.

커멘드가 큐에 넣어지면(자), 필터 그래프 매니저는 IDeferredCommand 인터페이스에의 포인터를 돌려준다. 어플리케이션은, 이 인터페이스를 사용해 그 커멘드를 취소하거나 변경하거나 할 수가 있다.

주 : IQueueCommand 에는,InvokeAtStreamTime 와 InvokeAtPresentationTime 의 2 개의 메소드가 있다. 필터 그래프 매니저의 문맥에서는, 스트림 타임과 프레젠테이션 시간이 동일하기 때문에, 이 2 개의 메소드에 기능상의 차이는 없다. 다만, 그 외의 오브젝트에서는, 그것과는 다른 IQueueCommand 를 이행 할 가능성이 있다. 스트림 타임과 프레젠테이션 시간의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IQueueCommand 메소드 | 설명
InvokeAtStreamTime | 지정된 스트림 타임에 기동하기 위해(때문에), 메소드를 큐에 넣는다.
InvokeAtPresentationTime | 지정된 프레젠테이션 시간에 기동하기 위해(때문에), 메소드를 큐에 넣는다.

IQueueCommand::InvokeAtPresentationTime

IQueueCommand 인터페이스

지정된 스트림 타임에 기동하기 위해(때문에), 메소드를 큐에 넣는다.

구문

HRESULT InvokeAtPresentationTime(
    IDeferredCommand **pCmd,
    REFTIME time,
    GUID *iid,
    long dispidMember,
    short wFlags,
    long cArgs,
    VARIANT *pDispParams,
    VARIANT *pvarResult,
    short *puArgErr
);

파라미터

pCmd
[out] IDeferredCommand 인터페이스 포인터를 받는 변수에의 포인터.
time
[in] 커멘드를 기동하는 시간.
iid
[in] 인터페이스의 인터페이스 식별자 (IID)에의 포인터.
dispidMember
[in] 인터페이스의 메소드 또는 프로퍼티의 디스팟치 식별자 (DISPID). IDispatch::InvokeAt 메소드의 dispIdMember 파라미터와 동등.
wFlags
[in] 호출의 문맥을 기술하는 플래그. IDispatch::InvokeAt 메소드의 wFlags 파라미터와 동등.
cArgs
[in] pDispParams 내의 인수의 수. DISPPARAMS 구조체의 cArgs 멤버와 동등.
pDispParams
[in] 인수가 저장 된 배열에의 포인터. DISPPARAMS 구조체의 rgvarg 멤버와 동등.
pvarResult
[in, out] 결과를 받는 VARIANT 에의 포인터. IDispatch::InvokeAt 메소드의 pVarResult 파라미터와 동등.
puArgErr
[out] 최초로 에러가 발생한 인수의 인덱스를 받는 변수에의 포인터. IDispatch::InvokeAt 메소드의 puArgErr 파라미터와 동등.

반환값

HRESULT 값을 돌려준다.

주의

dispidMember 파라미터를 위한 DISPID 를 취득하려면 ,IDispatch::GetIDsOfNames 메소드를 사용한다.

IQueueCommand::InvokeAtStreamTime

IQueueCommand 인터페이스

특정의 스트림 타임 (즉, 현재의 스트림 타임 오프셋(offset)와 프레젠테이션 시간의 차이)에 실행하기 위해(때문에), 메소드 또는 프로퍼티의 변경을 큐에 넣는다.

구문

HRESULT InvokeAtStreamTime(
    IDeferredCommand **pCmd,
    REFTIME time,
    GUID *iid,
    long dispidMember,
    short wFlags,
    long cArgs,
    VARIANT *pDispParams,
    VARIANT *pvarResult,
    short *puArgErr
);

파라미터

pCmd
[out] IDeferredCommand 인터페이스 포인터를 받는 변수에의 포인터.
time
[in] 커멘드를 기동하는 시간.
iid
[in] 인터페이스의 인터페이스 식별자 (IID)에의 포인터.
dispidMember
[in] 인터페이스의 메소드 또는 프로퍼티의 디스팟치 식별자 (DISPID). IDispatch::InvokeAt 메소드의 dispIdMember 파라미터와 동등.
wFlags
[in] 호출의 문맥을 기술하는 플래그. IDispatch::InvokeAt 메소드의 wFlags 파라미터와 동등.
cArgs
[in] pDispParams 내의 인수의 수. DISPPARAMS 구조체의 cArgs 멤버와 동등.
pDispParams
[in] 인수가 저장 된 배열에의 포인터. DISPPARAMS 구조체의 rgvarg 멤버와 동등.
pvarResult
[in, out] 결과를 받는 VARIANT 에의 포인터. IDispatch::InvokeAt 메소드의 pVarResult 파라미터와 동등.
puArgErr
[out] 최초로 에러가 발생한 인수의 인덱스를 받는 변수에의 포인터. IDispatch::InvokeAt 메소드의 puArgErr 파라미터와 동등.

반환값

HRESULT 값을 돌려준다.

주의

dispidMember 파라미터를 위한 DISPID 를 취득하려면 ,IDispatch::GetIDsOfNames 메소드를 사용한다.


IReferenceClock 인터페이스

필터 그래프에 기준 타임을 제공한다.

기준 클락으로서의 기능을 가지는 필터는, 이 인터페이스를 공개할 수 있다. 이 인터페이스는,시스템 기준 클락에서도 공개된다. 필터 그래프 매니저는, 이 인터페이스를 사용해 필터 그래프의 동기를 잡는다. 어플리케이션에서는, 이 인터페이스를 사용해, 현재의 기준 타임을 취득하거나 경과시간의 통지를 요구하거나 할 수 있다.

상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

필터 개발자에게 : 신뢰성의 높은 클락 타임을 생성하는 필터를 개발하려면 , 이 인터페이스를 이행 하는 것. 예를 들어, 사운드 보드에는 기준 클락이 붙어 있는 것이 많기 때문에,오디오 렌더링 필터는 이 인터페이스를 이행 한다. 이 인터페이스를 이행 하려면 ,CBaseReferenceClock 클래스를 사용하는 것.

비렌더링 필터가 필터 그래프 매니저로부터 참조 클락으로서 선택될 찬스를 늘리려면 , 이하의 스텝 :

  1. 그 필터내에서 IReferenceClock 를 이행 한다.
  2. 그 필터내에서 IAMFilterMiscFlags 를 이행 한다.
  3. IAMFilterMiscFlags::GetMiscFlags 로부터 AM_FILTER_MISC_FLAGS_IS_SOURCE 를 돌려준다.
  4. 모든 출력 핀으로 IAMPushSource 를 이행 한다.
  5. IAMPushSource::GetPushSourceFlags 로부터 (* pFlags) = 0 을 돌려준다.
  6. 모든 다른 IAMPushSource 메소드로부터 E_NOTIMPL 를 돌려준다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IReferenceClock 메소드 | 설명
GetTime | 현재의 기준 타임을 취득한다.
AdviseTime | 단발의 아드바이즈 요구를 생성 한다.
AdvisePeriodic | 주기적인 아드바이즈 요구를 생성 한다.
Unadvise | 보류중의 아드바이즈 요구를 삭제한다.

IReferenceClock::AdvisePeriodic

IReferenceClock 인터페이스

주기적인 아드바이즈 요구를 생성 한다.

구문

HRESULT AdvisePeriodic(
    REFERENCE_TIME rtStartTime,
    REFERENCE_TIME rtPeriodTime,
    HSEMAPHORE hSemaphore,
    DWORD *pdwAdviseCookie
);

파라미터

rtStartTime
[in] 최초의 통지의 타임 (100 나노초단위). 제로 이상, MAX_TIME 이하가 아니면 안 된다.
rtPeriodTime
[in] 통지동안의 타임 (100 나노초단위). 제로 이상이 아니면 안 된다.
hSemaphore
[in] 호출 바탕으로야는 생성 되는 semaphore의 핸들.
pdwAdviseCookie
[out] 이 아드바이즈 요구의 식별자를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_INVALIDARG | 무효인 타임값.
E_OUTOFMEMORY | 실패.
E_POINTER | NULL 포인터 인수.

주의

클락은, 통지마다 hSemaphore 파라미터로 지정된 semaphore를 해방한다. 그 이상 통지가 불필요하게 되었을 경우는 Unadvise 를 호출해, 이 호출에 의해 돌려주어진 pdwAdviseToken 값을 건네준다.

다음의 샘플 코드에서는, 생성 후 5 초, 및 그 이후의 2 초 마다 통지되는 아드바이즈 요구를 생성 하고 있다.

IReferenceClock *pRefClock = NULL;
// IReferenceClock 포인터를 취득한다 (나타나지 않는다).

DWORD          dwAdviseToken;
HANDLE         hSemaphore = CreateSemaphore(NULL, 0, 0x7FFFFFFF, NULL);
REFERENCE_TIME rtPeriodTime = 10000000; // A one-second interval
REFERENCE_TIME rtNow;

pRefClock->GetTime(&rtNow);
pRefClock->AdvisePeriodic(rtNow + (5 * rtPeriodTime),
                          rtPeriodTime,
                          hSemaphore,
                          &dwAdviseToken);
...

pRefClock->Unadvise(dwAdviseToken);

IReferenceClock::AdviseTime

IReferenceClock 인터페이스

단발의 아드바이즈 요구를 생성 한다.

구문

    HRESULT AdviseTime(
    REFERENCE_TIME rtBaseTime,
    REFERENCE_TIME rtStreamTime,
    HEVENT hEvent,
    DWORD *pdwAdviseCookie
);

파라미터

rtBaseTime
[in] 기본이 되는 기준 타임 (100 나노초단위). 「주의」를 참조할것.
rtStreamTime
[in] 스트림 오프셋(offset) 타임 (100 나노초단위). 「주의」를 참조할것.
hEvent
[in] 호출 바탕으로야는 생성 되는 이벤트에의 핸들.
pdwAdviseCookie
[out] 아드바이즈 요구의 식별자를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_INVALIDARG | 무효인 타임값.
E_OUTOFMEMORY | 실패.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는, 기준 타임 baseTime + streamTime 에 대해서 단발의 아드바이즈 요구를 생성 한다. 그 합계는, 제로 이상, MAX_TIME 이하가 아니면 안 된다. 이외의 경우는, E_INVALIDARG 를 돌려준다. 클락은, 요구된 타임에,hEvent 파라미터로 지정된 이벤트를 통지한다.

타임에 도달하기 전에 통지를 취소하려면 ,Unadvise 메소드를 호출해, 호출에 의해 돌려주어진 pdwAdviseToken 값을 건네준다. 통지의 발생 후, 클락은 자동적으로 통지를 소거하므로,Unadvise 를 호출할 필요는 없다. 다만, 호출해도 실수는 아니다.

IReferenceClock::GetTime

IReferenceClock 인터페이스

현재의 시간을 취득한다.

구문

HRESULT GetTime(
    REFERENCE_TIME *pTime
);

파라미터

pTime
[out] 현재의 시간을 받는 변수에의 포인터 (100 나노초단위).

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

POINTER | NULL 포인터 인수.
S_FALSE | 돌려주어진 타임은, 전의 값과 같다.
S_OK | 성공.

IReferenceClock::Unadvise

IReferenceClock 인터페이스

보류중의 아드바이즈 요구를 삭제한다.

구문

HRESULT Unadvise(
    DWORD dwAdviseCookie
);

파라미터

dwAdviseCookie
[in] 삭제하는 요구의 식별자. AdviseTime , 또는 pdwAdviseToken 파라미터의 AdvisePeriodic 로부터 돌려주어진 값을 사용한다.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.
S_FALSE | 발견되지 않았다.
S_OK | 성공.


IRegFilterInfo 인터페이스

Windows® 레지스트리에 있는 필터에의 액세스를 제공해, 등록이 끝난 필터를 필터 그래프에 추가한다.

필터 그래프 매니저는, Microsoft® Visual Basic® 어플리케이션으로부터의 사용을 목적으로, 이 인터페이스를 이행 한다. C/C++ 어플리케이션에서는, 이 인터페이스는 아니고,IFilterMapper2 인터페이스를 사용하는 것.

IMediaControl::get_RegFilterCollection 메소드는,IRegFilterInfo 인터페이스의 집합을 돌려준다. 이 인터페이스를 사용해, 집합에 포함되는 필터의 이름을 조회해, 필터 그래프에 희망의 필터를 추가한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IRegFilterInfo 메소드 | 설명
get_Name | 필터명을 취득한다.
Filter | 이 필터의 인스턴스를 생성 해, 그것을 필터 그래프에 추가한다.

IRegFilterInfo::Filter

IRegFilterInfo 인터페이스

이 필터의 인스턴스를 생성 해, 그것을 필터 그래프에 추가한다.

구문

HRESULT Filter(

  IDispatch **ppUnk

  );

파라미터

ppUnk
[out] 추가된 필터의 IFilterInfo 인터페이스에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

주의

IRegFilterInfo 인터페이스의 집합에 포함되는 이름을 비교해 필터를 검색하려면 ,IRegFilterInfo::get_Name 메소드 (Visual Basic 의 Name 프로퍼티)를 사용한다.

IRegFilterInfo::get_Name

IRegFilterInfo 인터페이스

필터명을 취득한다.

구문

HRESULT get_Name(

  BSTR *strName

  );

파라미터

strName
[out, retval] 필터명에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

보통, Visual Basic 어플리케이션에서는,IRegFilterInfo 인터페이스의 집합에 For Each...Next 구문을 사용해, 추가하고 싶은 필터가 발견될 때까지, 레지스트리에 포함되는 개개의 필터의 이름을 확인한다. 다음에,IRegFilterInfo::Filter 메소드를 사용해, 그 필터를 필터 그래프에 추가할 수 있다.


IResourceConsumer 인터페이스

IResourceManager 인터페이스를 사용하는 오브젝트에, 콜백 메카니즘을 제공한다.

IResourceManager 인터페이스를 사용해 필터 그래프 매니저로부터의 리소스를 요구하는 오브젝트에서는,IResourceConsumer 를 이행 할 필요가 있다. 리소스가 이용 가능하게 되었을 때, 또는 취득한 리소스를 해방해야 할 때에는, 필터 그래프 매니저가 IResourceConsumer 의 메소드를 호출해 그 오브젝트에 통지한다.

보통, 어플리케이션으로 이 인터페이스를 사용 또는 이행 할 것은 없다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 돌려준다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IResourceManager 메소드 | 설명
AcquireResource | 리소스의 사용자에 리소스가 취득 가능한 일을 통지한다.
ReleaseResource | 지정된 리소스를 해방하도록(듯이) 리소스의 사용자에 요구한다.

IResourceConsumer::AcquireResource

IResourceConsumer 인터페이스

리소스가 취득 가능한 일을 리소스의 사용자에 통지한다.

구문

HRESULT AcquireResource(
  LONG idResource
  );

파라미터

idResource
[in] 취득하는 리소스의 리소스 식별자.

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 리소스의 사용자가 리소스의 취득에 성공했다.
S_FALSE | 리소스의 사용자가 리소스를 취득하지 않고, 취득했을 때에 IResourceManager::NotifyAcquire 를 사용한다.
VFW_S_RESOURCE_NOT_NEEDED | 리소스의 사용자가 리소스를 다 사용했다.
에러값 | 리소스의 사용자가 리소스를 취득하려고 했지만, 실패했다.

IResourceConsumer::ReleaseResource

IResourceConsumer 인터페이스

지정된 리소스를 해방하도록(듯이) 리소스의 사용자에 요구한다.

구문

HRESULT ReleaseResource(
  LONG idResource
  );

파라미터

idResource
[in] 해방하는 리소스의 식별자.

반환값

리소스 해방 후에, 이용 가능하게 된 같은 리소스를 리소스의 사용자가 한번 더 요구했을 경우는, S_OK 를 돌려준다. 리소스의 사용자가 리소스를 해방하지 않고, 해방했을 때에 IResourceManager::NotifyRelease 를 사용하는 경우에는, S_FALSE 를 돌려준다.


IResourceManager 인터페이스

system resource의 경합을 해결한다.

필터 그래프 매니저가 이 인터페이스를 공개한다. 필터에서는, 이 인터페이스를 사용해, 다른 오브젝트가 사용할 가능성이 있는 리소스를 요구할 수 있다. 예를 들어,오디오 렌더링 필터에서는, 이 인터페이스를 사용해, 웨이브 출력 디바이스의 경합을 해결해, 사운드와 포커스를 일치시킨다.

보통, 어플리케이션으로 이 인터페이스를 사용할 것은 없다.

오브젝트에서는, 기존의 리소스간에 일어날 가능성이 있는 경합을, 이 인터페이스를 사용해 해결할 수 있다. 우선, 오브젝트는, 인터페이스에 리소스를 등록해, 필요한 때에 그 리소스를 요구한다. 오브젝트는, 유저의 포커스가 변화할 때마다, 필터 그래프 매니저에 통지해야 한다. 이것에 의해, 필터 그래프 매니저는, 경합 하는 디바이스를 유저의 포커스가 있는 오브젝트로 전환할 수가 있다.

이 인터페이스를 사용하는 오브젝트는,IResourceConsumer 인터페이스를 이행 할 필요가 있다. IResourceConsumer 는, 리소스가 이용 가능하게 되었을 때, 또는 취득한 리소스를 오브젝트가 해방 해야 한다고나무에, 필터 그래프 매니저가 오브젝트에 통지하기 위한 콜백 메카니즘을 제공한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IResourceManager 메소드 | 설명
Register | 단독의 이름 첨부 리소스를 리소스 매니저에 등록한다.
RegisterGroup | 이름 첨부 리소스 그룹을 리소스 매니저에 등록한다.
RequestResource | 소정의 등록이 끝난 리소스의 사용을 요구한다.
NotifyAcquire | 리소스 취득의 시도가 완료한 것을 리소스 매니저에 통지한다.
NotifyRelease | 리소스 컨슈머(consumer)이 리소스를 해방한 것을 리소스 매니저에 통지한다.
CancelRequest | 리소스 요구를 취소한다.
SetFocus | 특정의 오브젝트에 유저의 포커스가 주어진 것을 리소스 매니저에 통지한다.
ReleaseFocus | 현재의 포커스 오브젝트가 지정되었을 경우에, 리소스 매니저내의 포커스 오브젝트를 NULL 로 설정한다.

IResourceManager::CancelRequest

IResourceManager 인터페이스

리소스 요구를 취소한다.

구문

HRESULT CancelRequest(
    LONG idResource,
    IResourceConsumer *pConsumer
);

파라미터

idResource
[in] 대기중의 요구의 리소스 식별자.
pConsumer
[in] 요구원의 IResourceConsumer 인터페이스에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

요구한 리소스가 받아 전에 불필요하게 되었을 경우, 요구원의 IResourceConsumer 오브젝트는 이 메소드를 호출할 필요가 있다. 또, 리소스를 이미 받았을 경우에는,IResourceManager::NotifyRelease 메소드를 사용할 필요가 있다.

IResourceManager::NotifyAcquire

IResourceManager 인터페이스

리소스 취득의 시도가 완료한 것을 리소스 매니저에 통지한다.

구문

HRESULT NotifyAcquire(
    LONG idResource,
    IResourceConsumer *pConsumer,
    HRESULT hr
);

파라미터

idResource
[in] 등록이 끝난 리소스에 대응하는 토큰.
pConsumer
[in] 리소스를 요구하고 있는 오브젝트의 IResourceConsumer 인터페이스에의 포인터.
hr
[in] 취득의 성공을 나타내는 값. 리소스가 취득되었을 경우는 S_OK, 그 이외의 경우는 에러값.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는,IResourceConsumer::AcquireResource 메소드가 S_FALSE 값을 돌려준 후에 사용한다. S_FALSE 값은, 취득이 비동기에 행해지는 (즉, 콜백 메카니즘으로 처리된다) 일을 나타낸다. hr 파라미터가 S_OK 의 경우, 리소스 매니저는, 그 리소스가 호출해 바탕으로 보관 유지되고 있는 것이라고 본다. hr 파라미터가 S_OK 가 아닌 경우, 리소스 매니저는, 리소스 취득의 시도가 실패해, 그 리소스가 다른 기회에 또 할당할 수 있는 것이라고 본다.

IResourceManager::NotifyRelease

IResourceManager 인터페이스

IResourceConsumer 가 리소스를 해방한 것을 리소스 매니저에 통지한다.

구문

HRESULT NotifyRelease LONG idResource,
    IResourceConsumer *pConsumer,
    BOOL bStillWant
);

파라미터

idResource
[in] 리소스의 토큰.
pConsumer
[in] 리소스를 해방하려고 하고 있는 오브젝트에의 포인터.
bStillWant
[in] 리소스가 아직 필요한가 어떤가를 지정하는 플래그. 다음에 이용 가능하게 되었을 때에 아직 리소스가 필요한 경우는, TRUE 를 설정한다. 리소스가 필요하지 않은 경우는, FALSE 를 설정한다.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는,IResourceConsumer::ReleaseResource 메소드에의 응답으로서 사용하는지, 또는 리소스를 다 사용했을 때에 사용한다.

IResourceManager::Register

IResourceManager 인터페이스

단독의 이름 첨부 리소스를 리소스 매니저에 등록한다.

구문

HRESULT Register(
    LPCWSTR pName,
    LONG cResource,
    LONG *plToken
);

파라미터

pName
[in] 이름 첨부 리소스.
cResource
[in] 리소스수.
plToken
[out] 돌려주어진 토큰에의 포인터. 이 토큰이 식별하는 리소스를, 이 이후의 호출로 사용한다.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는, 복수의 리소스를 저장 할 수 있는 이름 첨부 리소스를 등록해, 이 리소스를 요구할 경우에 사용하는 토큰을 돌려준다. 리소스가 이미 등록되어 있어도 에러는 되지 않는다. 등록을 마친 수보다 적은 수를 cResource 파라미터에 건네주면(자), 리소스의 할당이가 새로운 수로 변경된다. 리소스의 등록을 해제하는데는,cResource 에 0 을 건네준다.

IResourceManager::RegisterGroup

IResourceManager 인터페이스

이름 첨부 리소스 그룹을 리소스 매니저에 등록한다.

구문

HRESULT RegisterGroup(
    LPCWSTR pName,
    LONG cResource,
    LONG *palTokens,
    LONG *plToken
);

파라미터

pName
[in] 이름 첨부 리소스 그룹.
cResource
[in] 그룹에 포함되는 리소스의 수.
palTokens
[in, size_is(cResource)] 그룹에 포함되는 리소스의 배열에의 포인터.
plToken
[out] 돌려주어진 그룹 리소스 식별자에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

IResourceManager::ReleaseFocus

IResourceManager 인터페이스

현재의 포커스 오브젝트가 지정되었을 경우에, 리소스 매니저내의 포커스 오브젝트를 NULL 로 설정한다.

구문

HRESULT ReleaseFocus(
    IUnknown *pFocusObject
);

파라미터

pFocusObject
[in] 포커스 오브젝트에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는, 포커스 오브젝트를 파기하려고 하고 있을 때, 포커스가 이제 참조되지 않게 하기 위해서 사용한다.

IResourceManager::RequestResource

IResourceManager 인터페이스

소정의 등록이 끝난 리소스의 사용을 요구한다.

구문

HRESULT RequestResource(
    LONG idResource,
    IUnknown *pFocusObject,
    IResourceConsumer *pConsumer
);

파라미터

idResource
[in] 리소스 등록시에 취득된 리소스의 토큰.
pFocusObject
[in] 요구에 관련지을 수 있었던 포커스 오브젝트의 IUnknown 인터페이스 (보통은 필터의 IUnknown 인터페이스)에의 포인터.
pConsumer
[in] 리소스를 요구하고 있는 오브젝트의 IResourceConsumer 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 요구한 리소스가 돌려주어졌을 경우는, S_OK 를 돌려준다. 리소스를 이용할 수 없는 경우는, S_FALSE 를 돌려준다. 이 경우, 리소스 매니저는, 리소스가 이용 가능하게 된 시점에서, 요구원오브젝트를 콜백 한다. 그 이외의 반환값은 모두 에러이다.

주의

그 리소스에의 요구가 다수 있는 경우, 리소스 매니저는, 개개의 요구로 건네받은 포커스 오브젝트를, 최신의 IResourceManager::SetFocus 메소드로 건네받은 포커스 오브젝트와 비교하는 것에 의해, 우선 순위를 결정한다.

요구는 다음의 우선 순위로 처리된다.

  1. 최신의 SetFocus 메소드와 완전히 같은 포커스 오브젝트에 관한 요구.
  2. 포커스 오브젝트와소스 필터를 공유하는 요구.
  3. 포커스 오브젝트와 필터 그래프를 공유하는 요구.
  4. 포커스와 같은 처리로부터의 요구.

이 우선 순위를 조사할 때, 리소스 매니저는, 포커스 오브젝트의 QueryInterface 를 사용해 IID_IFilter 를 조회한다. 발견되었을 경우, 리소스 매니저는,IBaseFilter 메소드를 사용해, 필터 그래프를 조사해 현재의 포커스 오브젝트와 공통의 소스 필터를 찾는다.

필터에서는, 그 필터의 IUnknown 인터페이스를 pFocusObject 파라미터에 건네주지 않으면 안 된다. 필터 그래프 매니저는, 포커스 오브젝트를 조사할 때, 필터를 필터 그래프와 비교해, 공통의 소스 필터까지 필터를 더듬으려고 한다.

포커스 오브젝트는, 요구의 유효기간 전체를 통해 유효한 필요가 있다. 요구의 유효기간이란,IResourceManager::CancelRequest 메소드가 불려 가는지, 또는 bStillWant 파라미터에 FALSE 를 설정해 IResourceManager::NotifyRelease 메소드가 불려 갈 때까지의 기간이다.

IResourceManager::SetFocus

IResourceManager 인터페이스

특정의 오브젝트에 유저 포커스가 주어진 것을 리소스 매니저에 통지한다.

구문

HRESULT SetFocus(
    IUnknown *pFocusObject
);

파라미터

pFocusObject
[in] 유저 포커스가 주어진 오브젝트에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

DirectShow 에서는, 보통, 포커스를 받은 윈도우를 소유하는 비디오 렌더러가, 유저 포커스가 주어지는 오브젝트이다. 리소스 매니저는, 리소스 요구에 다음의 순서로 우선 순위를 준다.

  1. pFocusObject 파라미터로 지정된 포커스 오브젝트에 관한 요구.
  2. 포커스 오브젝트와 소스 필터를 공유하는 요구.
  3. 포커스 오브젝트와 필터 그래프를 공유하는 요구.
  4. 포커스와 같은 처리로부터의 요구.

리소스 매니저는, 포커스가 설정되고 나서 ReleaseFocus 가 불려 갈 때까지, 포커스 오브젝트를 유지해야 한다. 즉, 이 메소드를 호출하면(자), 포커스 오브젝트의 IUnknown 인터페이스가 무효가 되기 전에,ReleaseFocus 를 사용할 필요가 있다. 다만, 다른 오브젝트로부터 그때까지 확실히 SetFocus 가 불려 가는 경우는 예외로 한다. 포커스 오브젝트상에는 참조 카운트가 보관 유지되지 않는다.

리소스 매니저는, 옮겨놓을 수 있을까 삭제될 때까지 이 포인터를 보관 유지해, 리소스 경합의 해결에 사용한다. 리소스 매니저는, 적어도 QueryInterface 를 사용해 IBaseFilter 인터페이스를 조회해, 발견되었을 경우는 이 인터페이스의 메소드를 사용한다. IBaseFilter 의 메소드는, 오디오 렌더러가 2 개 있는 경우에, 어느 쪽을 사용할까 결정하는 (포커스 오브젝트와 소스 필터를 공유하는 것을 선택한다) 위해(때문에) 불려 가 게다가 2 개의 오브젝트가 같은 필터 그래프에 포함될지 어떨지를 판단하기 위해서(때문에) 불려 간다.


ISampleGrabber 인터페이스

이 인터페이스는, 필터 그래프내를 지나는 개개의 미디어 샘플을 취득하는 메소드를 제공한다.

샘플 grabber 필터는, 이 인터페이스를 공개한다. 어플리케이션에서는, 이 인터페이스의 메소드를 호출해, 미디어 샘플을 취득할 수 있다. 상세한 것에 대하여는,「미디어 샘플의 입수」를 참조할것.

요건

Requires Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
ISampleGrabber 메소드 | 설명
SetOneShot | 샘플을 1 개 받으면(자) 필터가 그래프를 정지해야할 것인가 제발을 지정한다.
SetMediaType | 샘플 grabber의 입력 핀 위에의 접속에 사용하는 미디어 타입을 지정한다.
GetConnectedMediaType | 샘플 grabber의 입력 핀 위에의 접속에 사용하는 미디어 타입을 취득한다.
SetBufferSamples | 필터내를 지나는 샘플을 버퍼에 카피할지 어떨지를 지정한다.
GetCurrentBuffer | 필터가 받은 최신 샘플의 카피를 취득한다.
GetCurrentSample | 현재는 이행되어 있지 않다.
SetCallback | 샘플 도착시에 호출하는 콜백 메소드를 지정한다.

ISampleGrabber::GetConnectedMediaType

ISampleGrabber 인터페이스

샘플 grabber의 입력 핀 위에의 접속에 사용하는 미디어 타입을 취득한다.

구문

HRESULT GetConnectedMediaType(
    AM_MEDIA_TYPE *pType
);

파라미터

pType
AM_MEDIA_TYPE 구조체를 받는 변수에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

E_POINTER | NULL 포인터 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 필터가 접속되어 있지 않다.

ISampleGrabber::GetCurrentBuffer

ISampleGrabber 인터페이스

최신 샘플에 관련지을 수 있었던 버퍼의 카피를 취득한다.

구문

HRESULT GetCurrentBuffer(
    long *pBufferSize,
    long *pBuffer
);

파라미터

pBufferSize
[in, out] 버퍼의 사이즈에의 포인터. pBuffer 가 NULL 의 경우, 이 파라미터는 필요한 사이즈를 받는다. pBuffer 가 NULL 가 아닌 경우, 이 파라미터는 버퍼의 사이즈를 나타낸다.
pBuffer
[out] 샘플의 카피를 받는 버퍼에의 포인터, 또는 NULL.

반환값

다음의 몇개의 값을 돌려준다.

E_INVALIDARG | 샘플이 버퍼링되어 있지 않다.
E_POINTER | NULL 포인터 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 필터가 접속되어 있지 않다
VFW_E_WRONG_STATE | 필터가 부적절한 상태에 있다.

주의

버퍼링을 액티브하게 하려면 , 값 TRUE 로 SetBufferSamples 를 호출한다.

ISampleGrabber::GetCurrentSample

ISampleGrabber 인터페이스

현재는 이행되어 있지 않다.

구문

HRESULT GetCurrentSample(
    IMediaSample **ppSample
);

ISampleGrabber::SetBufferSamples

ISampleGrabber 인터페이스

필터내를 지나는 샘플을 버퍼에 카피할지 어떨지를 지정한다.

구문

HRESULT SetBufferSamples(
    BOOL BufferThem
);

파라미터

BufferThem
샘플 데이터를 버퍼링 할지 어떨지를 지정하는 불형의 값. TRUE 의 경우, 필터는 샘플 데이터를 내부 버퍼에 카피한다.

반환값

S_OK 를 돌려준다.

ISampleGrabber::SetCallback

ISampleGrabber 인터페이스

샘플 도착시에 호출하는 콜백 메소드를 지정한다.

구문

HRESULT SetCallback(
    ISampleGrabberCB *pCallback,
    long WhichMethodToCallback
);

파라미터

pCallback
콜백 메소드가 저장 된 ISampleGrabberCB 인터페이스에의 포인터, 또는 NULL. 콜백을 취소하는 경우에, NULL 를 지정한다.
WhichMethodToCallback
콜백 메소드를 지정하는 인덱스. 다음의 몇개의 값을 지정한다.
0 | ISampleGrabberCB::SampleCB 메소드를 호출한다.
1 | ISampleGrabberCB::BufferCB 메소드를 호출한다.

반환값

다음의 몇개의 값을 돌려준다.

E_INVALIDARG | 샘플은 버퍼링되어 있지 않다.
S_OK | 성공.

주의

샘플이 Microsoft® DirectDraw® 표면인 경우, 그 표면은 콜백중에 락 된다. Win16 락 (Win16Mutex 라고도 불린다)도, 락 되는 일이 있다. 이러한 락에 의해, 데드 록의 가능성이 태어난다. 콜백 thread가 DirectDraw API 를 호출하려 하고 있는 thread를 기다리고 있는 경우, 데드 록이 발생할 가능성이 있다. 게다가 Win16 락이 보관 유지되고 있는 경우, 콜백에 크리티컬 섹션이 보관 유지되고 있는지, 또는 다른 thread가 처리를 완료하는 것을 기다리고 있으면(자), 데드 록이 발생할 가능성이 있다.

그 때문에, 콜백은 블록을 발생시킬 가능성이 있는 처리를 실행해서는 안 된다. 이것에는, 크리티컬 섹션의 보관 유지나, 다른 thread 대기가 포함된다. 또, 윈도우를 움직이는 것 같은 GDI 나 USER32.DLL API 를 호출해서는 안 된다. Win16 락에 대한 자세한 것은, Knowledge Base 문장 Q125867 : Understandign Win16Mutex ((http://support.microsoft.com/support/kb/articles/Q125/8/67.asp )를 참조할것.

데이터 처리 thread는, 콜백 메소드로부터 돌아올 때까지 블록 한다. 콜백 메소드로부터 돌아올 시간이 걸리면(자), 재생에 영향이 나올 가능성이 있다.

ISampleGrabber::SetMediaType

ISampleGrabber 인터페이스

샘플 grabber의 입력 핀 위에의 접속에 사용하는 미디어 타입을 지정한다.

구문

HRESULT SetMediaType(
    const AM_MEDIA_TYPE *pType
);

파라미터

pType
미디어 타입을 지정하는 AM_MEDIA_TYPE 형의 변수에의 포인터. 구조체 멤버를 모두 설정할 필요는 없다. 이 파라미터에서는, 메이저 타입만을 지정하거나 메이저 타입과 서브 타입을 지정하거나 메이저 타입, 서브 타입, 및 포맷 타입을 지정하거나 할 수가 있다. 그 외의 구조체 멤버는 무시된다.

반환값

S_OK 를 돌려준다.

주의

디폴트에서는, 샘플 grabber에 우선 미디어 타입은 없다. 샘플 grabber를 올바른 필터에 확실히 접속하려면 , 그래프를 렌더링 하기 전에 이 메소드를 호출한다.

ISampleGrabber::SetOneShot

ISampleGrabber 인터페이스

샘플을 1 개 받으면(자) 필터가 그래프를 정지해야할 것인가 제발을 지정한다.

구문

HRESULT SetOneShot(
    BOOL OneShot
);

파라미터

OneShot
샘플을 1 개 받으면(자) 필터가 그래프를 정지해야할 것인가 제발을 지정하는 불형의 값. TRUE 의 경우, 최초의 샘플을 받으면(자), 필터는 정지해, EC_COMPLETE 를 통지한다. FALSE 의 경우, 필터는 보통 대로 실행을 계속한다.

반환값

S_OK 를 돌려준다.

주의

값 TRUE 로 이 메소드를 호출해, 희망의 시간까지 시크 해, 그래프를 실행 하면, 특정 시간의 샘플을 취득할 수 있다.


ISampleGrabberCB 인터페이스

이 인터페이스는,ISampleGrabber::SetCallback 메소드에 대응하는 콜백 메소드를 제공한다. 이 메소드를 호출하는 어플리케이션에서는, 이 인터페이스를 이행 할 필요가 있다. 상세한 것에 대하여는,「ISampleGrabber 」를 참조할것.

요건

Qedit.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
ISampleGrabberCB 메소드 | 설명
SampleCB | 미디어 샘플에의 포인터를 받는 콜백 메소드.
BufferCB | 샘플 버퍼에의 포인터를 받는 콜백 메소드.

ISampleGrabberCB::BufferCB

ISampleGrabberCB 인터페이스

샘플 버퍼에의 포인터를 받는 콜백 메소드.

구문

HRESULT BufferCB(
    double SampleTime,
    BYTE *pBuffer,
    long BufferLen
);

파라미터

SampleTime
샘플의 시작 타임 (초단위).
pBuffer
샘플 데이터가 저장 된 버퍼에의 포인터.
BufferLen
pBuffer 가 가리키는 버퍼의 길이 (바이트 단위).

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는,HRESULT 에러 코드를 돌려준다.

주의

샘플의 버퍼링을 액티브하게 하려면 ,ISampleGrabber::SetBufferSamples 메소드를 호출한다. 그렇게 하지 않으면 샘플이 버퍼링 되지 않는다.

ISampleGrabberCB::SampleCB

ISampleGrabberCB 인터페이스

미디어 샘플에의 포인터를 받는 콜백 메소드.

구문

HRESULT SampleCB(
    double SampleTime,
    IMediaSample *pSample
);

파라미터

SampleTime
샘플의 시작 타임 (초단위).
pSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는,HRESULT 에러 코드를 돌려준다.


ISeekingPassThru 인터페이스

단독 입력 필터를 위한 시크를 이행 하는 헬퍼 오브젝트를 초기화한다. SeekingPassThru 헬퍼 오브젝트는, 이 인터페이스를 공개한다. 입력 핀이 1 개의 필터에서는, 이 인터페이스를 사용해,IMediaSeeking 인터페이스 및 IMediaPosition 인터페이스를 이행 할 수 있다. 상세한 것에 대하여는, 「CSeekingPassThru 」를 참조할것.

어플리케이션으로 이 인터페이스를 사용할 것은 없다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
ISeekingPassThru 메소드 | 설명
Init | 시크원의 헬퍼 클래스를 초기화한다.

ISeekingPassThru::Init

ISeekingPassThru 인터페이스

시크원의 헬퍼 클래스를 초기화한다.

구문

HRESULT Init(
    BOOL bSupportRendering,
    IPin *pPin
);

파라미터

bSupportRendering
[in] 필터가 렌더러인가 어떤가를 지정하는 불형의 값. 렌더러의 경우는 TRUE 를 사용해, 그 이외의 경우는 FALSE 를 사용한다.
pPin
[in] 필터의 입력 핀 위에의 IPin 인터페이스에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_FAIL | 오브젝트는 이미 초기화되고 있다.
E_OUTOFMEMORY | 메모리 부족을 위해, 오브젝트를 생성 할 수 없다.


IStreamBuilder 인터페이스

이 인터페이스를 사용 하면, 출력 핀으로부터 필터 그래프 매니저에, 필터 그래프의 다운 스트림 부분을 핀 자체가 구축하는 것을 통지할 수 있다. 특수한 접속을 필요로 하는 출력 핀에서는, 이 인터페이스를 이행 해, 필터 그래프 매니저가 사용하는 핀 접속의 디폴트 처리를 오버라이드(override) 할 수 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IStreamBuilder 메소드 | 설명
Render | 이 핀으로부터 시작되는 스트림의 렌더링을 완료한다. 이 때 필요에 따라서, 필터가 필터 그래프에 추가되어 접속된다.
Backout | Render 로 행해진 스텝을 바탕으로 되돌린다. Render 내에서 추가된 필터가 있으면, 그 절단 및 삭제도 행해진다.

IStreamBuilder::Backout

IStreamBuilder 인터페이스

Render 로 행해진 스텝을 바탕으로 되돌린다. Render 내에서 추가된 필터가 있으면, 그 절단 및 삭제도 행해진다.

구문

HRESULT Backout(
   IPin *ppinOut
   IGraphBuilder *pGraph
)

파라미터

ppinOut
[in] 이 핀의 IPin 인터페이스에의 포인터.
pGraph
[in] 필터 그래프 매니저의 IGraphBuilder 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 그래프 빌더에 있어, return code S_OK 는 절단이 성공한 것을 나타낸다.

주의

다음의 코드는, 이 메소드를 출력 핀에 이행 하는 방법을 나타낸다.

STDMETHODIMP CMyOutputPin::BackOut(IPin *pOutputPin, IGraphBuilder *pBuilder)
{
    HRESULT hr = S_OK;
    if (m_Connected ! = NULL) {
        FILTER_INFO fi;

        // 자신의 핀에 접속하고 있는 핀의 필터 포인터를 검색한다.
        hr = m_Connected->QueryFilterInfo(&fi);
        if (SUCCEEDED(hr)) {
            if (fi.pFilter ! = NULL) {
                // 절단 한다.
                pBuilder->Disconnect(m_Connected);
                pBuilder->Disconnect(pOutputPin);
                // 추가한 필터를 그래프로부터 삭제한다.
                pBuilder->RemoveFilter(fi.pFilter);
                fi.pFilter->Release();
            } else {
                hr = E_UNEXPECTED;
            }
        }
    }
    return hr;
}

IStreamBuilder::Render

IStreamBuilder 인터페이스

이 핀으로부터 시작되는 스트림의 렌더링을 완료한다. 이 때 필요에 따라서, 필터가 필터 그래프에 추가되어 접속된다.

구문

HRESULT Render(
    IPin *ppinOut
    IGraphBuilder *pGraph
);

파라미터

ppinOut
[in] 이 핀의 IPin 인터페이스에의 포인터.
pGraph
[in] 필터 그래프 매니저의 IGraphBuilder 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. return code S_OK 는 스트림의 렌더링이 성공한 것을 나타낸다.

주의

다음의 코드는, 이 메소드를 출력 핀에 이행 하는 방법을 나타낸다.

STDMETHODIMP CMyOutputPin::Render(IPin *pOutputPin, IGraphBuilder *pBuilder)
{
    // 이 필터에는 자작의 특수한 렌더러를 접속할 필요가 있다.
    IBaseFilter *pMyRenderer = NULL;
    IPin *pMyRendererInputPin = NULL;
    bool bAddedToGraph = false;

    // 독자적인 렌더러를 생성 한다.
    HRESULT hr = CoCreateInstance(CLSID_MyRenderer, NULL, CLSCTX_INPROC, IID_IBaseFilter, (void **) &pMyRenderer);
    if (SUCCEEDED(hr)) {
        // 렌더러를 필터 그래프에 추가한다.
        hr = pBuilder->AddFilter(pMyRenderer, L"My Renderer");
    }
    // 렌더러의 입력 핀을 검색한다.

    if (SUCCEEDED(hr)) {
            bAddedToGraph = true;
            IEnumPins *pEnumPins;
            hr = pMyRenderer->EnumPins(&pEnumPins);
            if (SUCCEEDED(hr)) {
                DWORD nPins;
                if (S_OK ! = pEnumPins->Next(1, &pMyRendererInputPin, &nPins)) {
                    hr = E_UNEXPECTED;
                }
            }
    }
    if (SUCCEEDED(hr)) {
        // 렌더러를 자신의 출력 핀에 접속한다.
        hr = pBuilder->ConnectDirect(pOutputPin, pMyRendererInputPin);
    }
    if (FAILED(hr)) {
        if (bAddedToGraph) {
            pBuilder->RemoveFilter(pMyRenderer);
        }
        pMyRenderer->Release();
    }
    if (NULL ! = pMyRendererOutputPin) {
        pMyRendererInputPin->Release();
    }
    return hr;
}


IUnknown 인터페이스

COM (Component Object Model) 컴퍼넌트의 유효기간을 관리해, 컴퍼넌트에 그 외의 COM 인터페이스를 조회한다. 그 외의 COM 인터페이스는 모두 IUnknown 를 계승한다.

이 인터페이스 및 이 인터페이스에 포함되는 메소드의 자세한 것은, COM 의 문서에 기재되어 있다. 여기에서는, 퀵 레퍼런스로서 그 개요만을 설명한다.

인터페이스를 이행 하는 경우에는,IUnknown 도 동시에 이행 할 필요가 있다. IUnknown 를 이행하기 위한 편리한 수단은,CUnknown base class로 제공되지만, 독자적인 이행을 개발할 수도 있다. 상세한 것에 대하여는,「IUnknown 의 이행 방법」을 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.

IUnknown::AddRef

IUnknown 인터페이스

오브젝트상에 있는 호출원인터페이스의 참조 카운트를 인크리먼트(increment) 한다. 이 메소드는, 소정의 오브젝트상에 있는 인터페이스를 가리키는 포인터의 새로운 카피 각각 대해 호출하지 않으면 안 된다.

구문

ULONG AddRef(void);

반환값

새로운 참조 카운트를 나타내는 1 ~ n 의 정수를 돌려준다. 이 정보는 진단이나 테스트에서의 사용만을 목적으로 하고 있다. 이 때문에, 상황에 따라서는 불안정한 값을 취하는 일이 있다.

IUnknown::QueryInterface

IUnknown 인터페이스

클라이언트가 현재 인터페이스 포인터를 보관 유지하고 있는 컴퍼넌트상에 있는 특정의 인터페이스를 가리키는 포인터를 취득한다. 이 메소드는, 메소드가 돌려주는 포인터 위에의 IUnknown::AddRef 를 사용할 필요가 있다.

구문

HRESULT QueryInterface(

  REFIID iid,

  void **ppvObject

  );

파라미터

iid
[in] 요구처 인터페이스의 IID 를 지정하는 값.
ppvObject
[out] 오브젝트에의 포인터의 주소 (메소드로부터 돌아왔을 때). iid 로 지정된 인터페이스를 오브젝트가 지원 하고 있지 않는 경우,ppvObject 는 NULL 로 설정된다.

반환값

인터페이스가 지원 되고 있는 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_NOINTERFACE 를 돌려준다.

IUnknown::Release

IUnknown 인터페이스

오브젝트상에 있는 호출원인터페이스의 참조 카운트를 감소 한다. 오브젝트 위에의 참조 카운트가 0 이 되면(자), 오브젝트가 메모리로부터 해방된다.

구문

ULONG Release(void);

반환값

참조 카운트의 새로운 값을 돌려준다. 참조 카운트는 진단이나 테스트의 목적에게만 사용한다. 리소스가 해방된 것을 알 필요가 있는 경우에는, 시멘틱스 레벨이 높은 인터페이스를 사용한다.


IVideoFrameStep 인터페이스

비디오 스트림을 진행시킨다. 이 인터페이스를 사용 하면, DVD 플레이어를 포함한 Microsoft® DirectShow® 어플리케이션으로부터, 비디오 스트림을 1 프레임씩 진행할 수가 있다. 이 인터페이스는, 필터 그래프 매니저로부터 입수한다. 필터 그래프 매니저는,오버레이 믹서 필터 또는비디오 렌더러 필터와 함께, 스탭핑(Stepping)처리를 제어한다. 역방향의 스탭핑(Stepping)처리는, 지원되어 있지 않다.

주 : 하드웨어 디코더로 스탭핑(Stepping)가 기능하려면 , 그 디코더로 AM_KSPROPSETID_FrameStep 프로퍼티 세트가 지원 되고 있을 필요가 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IVideoFrameStep 메소드 | 설명
Step | 지정된 프레임수만큼 필터 그래프를 순서 방향으로 스탭핑(Stepping)한다.
CanStep | 지정된 필터의 스탭핑(Stepping)능력을 판단한다.
CancelStep | 직전의 스탭핑(Stepping)조작을 취소한다.

IVideoFrameStep::CancelStep

IVideoFrameStep 인터페이스

직전의 Step 조작을 취소한다.

구문

HRESULT CancelStep();

반환값

Step 조작의 취소에 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_FAIL 를 돌려준다.

IVideoFrameStep::CanStep

IVideoFrameStep 인터페이스

지정된 필터의 스탭핑(Stepping)능력을 판단한다.

구문

HRESULT CanStep(
   long bMultiple,
   IUnknown *pStepObject
);

파라미터

bMultiple
bMultiple 가 0 의 경우에 메소드가 S_OK 를 돌려주는 경우는, 오브젝트가 1 프레임씩 스탭핑(Stepping)할 수 있는 것을 의미한다. bMultiple 가 정의 경우에 메소드가 S_OK 를 돌려주는 경우는,pStepObject 가 bMultiple 프레임씩 스탭핑(Stepping)할 수 있는 것을 의미한다.
pStepObject
스탭핑(Stepping)조작을 제어하는 필터의 인터페이스에의 포인터. 필터 그래프 매니저에 대해서, 특정의 필터 그래프용의 렌더링 필터를 사용해 스탭핑(Stepping)를 실행하도록(듯이) 지시하려면 , NULL 를 지정한다. 스탭핑(Stepping)를 이행 하는 커스텀 필터가 그래프에 포함되어 있는 경우,pStepObject 는 그 필터의 IBaseFilter 인터페이스를 포인트 할 필요가 있다.

반환값

오브젝트가 스탭핑(Stepping)가능한 경우는, S_OK 를 돌려준다. pStepObject 가 무효인 경우는, E_INVALIDARG 를 돌려준다.

주의

스탭핑(Stepping)는 실시간으로 행해진다. 이것은, 무비를 30 프레임/초에 재생하고 있을 때,bMultiple 에 60 을 설정해 Step 를 호출하면, 실행에 2 초 걸리는 것을 의미한다. 이 인터페이스의 메소드는 모두 비동기이며, 제어는 즉시 어플리케이션에 돌려주어진다.

IVideoFrameStep::Step

IVideoFrameStep 인터페이스

지정된 프레임수만큼 필터 그래프를 순서 방향으로 스탭핑(Stepping)한다.

구문

HRESULT Step(
   DWORD dwFrames,
   IUnknown *pStepObject
);

파라미터

dwFrames
스킵 하는 프레임수를 지정하는 DWORD 형의 변수. dwFrames 가 1 의 경우, 1 프레임, 순서 방향으로 스탭핑(Stepping)하는 것을 의미한다. dwFrames 가 1 보다 큰 값 n 의 경우,n - 1 프레임을 스킵 해,n 번째의 프레임을 표시하는 것을 의미한다.
pStepObject
스탭핑(Stepping)조작을 제어하는 필터의 인터페이스에의 포인터. 필터 그래프 매니저에 대해서, 특정의 필터 그래프용의 렌더링 필터를 사용해 스탭핑(Stepping)를 실행하도록(듯이) 지시하려면 , NULL 를 지정한다. 스탭핑(Stepping)를 이행 하는 커스텀 필터가 그래프에 포함되어 있는 경우,pStepObject 는 그 필터의 IBaseFilter 인터페이스를 포인트 할 필요가 있다.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
VFW_E_FRAME_STEP_UNSUPPORTED | 스탭핑(Stepping)는 지원되어 있지 않다.
E_INVALIDARG | pStepObject 파라미터는 무효이다.

주의

스탭핑(Stepping)조작이 완료 하면, 이 메소드는 필터 그래프 매니저에 EC_STEP_COMPLETE 이벤트 통지를 보낸다. 필터 그래프 매니저는, 이것을 어플리케이션의 이벤트 루프에 건네주어, 필터 그래프를 포즈 상태로 전환한다.


IVideoWindow 인터페이스

IVideoWindow 인터페이스는, Microsoft® DirectShow® 제공의 비디오 렌더링 필터에 이행 되어 필터 그래프 매니저를 통해서 어플리케이션에 공개된다 (주 : C++ 개발자에게 : 이 인터페이스는, 반드시 필터 그래프 매니저의 QueryInterface 를 호출해 취득해, 비디오 렌더러로부터 직접 취득하지 않는 것). IVideoWindow 는, Microsoft® Visual Basic® 어플리케이션으로부터도 Visual C++® 어플리케이션으로부터도 액세스 할 수 있는 듀얼 인터페이스이다. IVideoWindow 는, 비디오를 재생하는 윈도우를 제어하기 위한 메소드 및 프로퍼티를 제공한다.

이 인터페이스의 메소드의 유일한 조건은, 비디오 렌더러가 접속되고 있는 것이다. 비디오 렌더러가 접속되어 있지 않은 경우, 인터페이스의 함수는 모두 VFW_E_NOT_CONNECTED 를 돌려준다. 비디오 렌더러로 설정한 프로퍼티는, 그 이후에 행해지는 접속 및 절단의 사이 훨씬 유효하다. 모든 어플리케이션에서는, 표시를 시작 하기 전에 렌더러의 프로퍼티를 확실히 리셋 하는 것.

이 인터페이스는 Automation 호환이다. 따라서, 메소드가 받아들이는 파라미터에는, 중요한 특징이 2 개 있다. 1 번째는, 돌려주어지는 불리언 값이 OAFALSE (0) 또는 OATRUE (–1)이며, 이것들이 C/C++ 의 정의와 다르고 있는 점이다. 2 번째는, 캐릭터 라인이 모두 BSTR 형으로서 정의되고 있는 점이다. 인터페이스에 보내는 캐릭터 라인은, 모두 Automation 의 SysAllocString 함수를 통해서 할당하지 않으면 안 된다. 같이 인터페이스로부터 돌려주어진 캐릭터 라인은, 모두 Automation 의 SysFreeString 함수를 사용해 해방해야 한다.

대체 비디오 렌더러를 개발하는 경우에는, 이 인터페이스를 이행 한다. Automation 용의 IDispatch 이행을 처리하는 CBaseVideoWindow 클래스를 사용 하면, 이 인터페이스가 이행 하기 쉽다.

주 : 비디오 렌더러가 차일드 윈도우에 있는 MFC 어플리케이션은, 비디오 디스플레이 에리어를 올바르고 재드로잉(Drawing) 시키기 위해서(때문에), 컬러의 WM_ERASEBKGND 메세지 핸들러를 가지지 않으면 안 된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDispatch 메소드 | 설명
GetTypeInfoCount | 이 디스프인타페이스에 이용 가능한 타입 정보가 있을지 어떨지 판단한다.
GetTypeInfo | GetTypeInfoCount 가 성공했을 경우는, 이 디스프인타페이스의 타입 정보를 취득한다.
GetIDsOfNames | (인수를 포함한다) 프로퍼티 및 메소드의 텍스트명을 대응하는 DISPID 로 변환한다.
Invoke | DISPID 및 그 외의 필요한 파라미터가 지정되었을 경우는, 이 디스프인타페이스의 메소드를 호출하는지, 또는 프로퍼티에 액세스 한다.
IVideoWindow 메소드 | 설명
put_Caption | 재생 윈도우의 타이틀 캐릭터 라인을 설정한다.
get_Caption | 재생 윈도우의 타이틀 캐릭터 라인을 취득한다.
put_WindowStyle | 재생 윈도우 스타일을 설정한다.
get_WindowStyle | 비디오 윈도우의 윈도우 스타일을 취득한다.
put_WindowStyleEx | 컨트롤 윈도우의 스타일을 설정한다.
get_WindowStyleEx | 비디오 윈도우의 확장 스타일을 취득한다.
put_AutoShow | 상태가 최초로 변화했을 때에 윈도우가 자동적으로 표시될지 어떨지를 지정한다.
get_AutoShow | 윈도우가 자동적으로 표시될지 어떨지에 관한 정보를 취득한다.
put_WindowState | 현재의 윈도우 상태 (표시/비표시, 최소화등)를 설정한다.
get_WindowState | 현재의 윈도우 상태 (표시/비표시, 최소화등)를 취득한다.
put_BackgroundPalette | 렌더러에 그 팔레트를 백그라운드에서 인식하도록(듯이) 알린다.
get_BackgroundPalette | 필요한 팔레트가 백그라운드에서 인식될지 어떨지에 관한 정보를 취득한다.
put_Visible | 윈도우의 표시/비표시를 설정한다.
get_Visible | 윈도우의 표시/비표시를 취득한다.
put_Left | 비디오 윈도우의 x 축좌표를 설정한다.
get_Left | 비디오 윈도우의 x 축좌표를 취득한다.
put_Width | 비디오 윈도우의 폭을 설정한다.
get_Width | 비디오 윈도우의 폭을 취득한다.
put_Top | 비디오 윈도우의 y 축좌표를 설정한다.
get_Top | 비디오 윈도우의 y 축좌표를 취득한다.
put_Height | 비디오 윈도우의 높이를 설정한다.
get_Height | 비디오 윈도우의 높이를 취득한다.
put_Owner | 비디오 재생 윈도우를 소유하는 부모 윈도우를 설정한다.
get_Owner | 비디오 재생 윈도우를 소유하는 부모 윈도우를 취득한다.
put_MessageDrain | 비디오 윈도우의 메세지의 송신지 윈도우를 지정한다.
get_MessageDrain | 비디오 윈도우의 메세지를 받아들이는 윈도우를 취득한다.
get_BorderColor | 비디오 윈도우의 경계색을 취득한다.
put_BorderColor | 비디오 윈도우의 경계색을 설정한다.
get_FullScreenMode | 이 인터페이스를 지원 하고 있는 비디오 렌더링 필터의 풀 스크린 렌더링 모드를 취득한다.
put_FullScreenMode | 이 인터페이스를 지원 하고 있는 비디오 렌더링 필터의 풀 스크린 모드를 설정한다.
SetWindowForeground | 전면 윈도우에 바뀌도록(듯이) 렌더링 필터에 알린다.
NotifyOwnerMessage | 부모 윈도우로부터 받은 메세지를, 필터가 소유하는 자식 윈도우에 전송 한다.
SetWindowPosition | 디스플레이상의 비디오 윈도우 위치를 설정한다.
GetWindowPosition | 비디오 윈도우 위치를 취득한다.
GetMinIdealImageSize | 비디오 이미지 재생 (클라이언트) 영역의 이론상의 최소 이미지 사이즈를 취득한다.
GetMaxIdealImageSize | 비디오 이미지 재생 (클라이언트) 영역의 이론상의 최대 이미지 사이즈를 취득한다.
GetRestorePosition | 복원되는 윈도우의 보통의 넓이를 취득한다.
HideCursor | 커서를 비표시로 한다.
IsCursorHidden | 커서의 표시/비표시를 판단한다.

IVideoWindow::get_AutoShow

IVideoWindow 인터페이스

윈도우가 자동적으로 표시될지 어떨지에 관한 정보를 취득한다.

구문

HRESULT get_AutoShow(
    long *AutoShow
);

파라미터

AutoShow
[out] 윈도우가 자동적으로 표시될지 어떨지를 나타내는 값에의 포인터. OATRUE 는, 포즈 상태 또는 실행 상태로 바뀌었을 때, 윈도우가 표시되는 것을 나타낸다.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::get_BackgroundPalette

IVideoWindow 인터페이스

필요한 팔레트가 백그라운드에서 인식될지 어떨지에 관한 정보를 취득한다.

구문

HRESULT get_BackgroundPalette(
    long *pBackgroundPalette
);

파라미터

pBackgroundPalette
[out] 팔레트가 백그라운드에서 인식될지 어떨지를 나타내는 값에의 포인터. OATRUE 는 인식되는 것을 나타낸다.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::get_BorderColor

IVideoWindow 인터페이스

비디오 윈도우의 경계색을 취득한다.

구문

HRESULT get_BorderColor(
    long *pColor
);

파라미터

pColor
[out] 취득된 경계색 (Microsoft Win32® COLORREF 값)에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::get_Caption

IVideoWindow 인터페이스

비디오 윈도우의 타이틀 캐릭터 라인을 취득한다.

구문

HRESULT get_Caption(
    BSTR *strCaption
);

파라미터

strCaption
[out] 취득된 윈도우 타이틀 캐릭터 라인에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::get_FullScreenMode

IVideoWindow 인터페이스

이 인터페이스를 지원 하고 있는 렌더링 필터의 풀 스크린 렌더링 능력을 취득한다.

구문

HRESULT get_FullScreenMode(
    long *FullScreenMode
);

파라미터

FullScreenMode
[out] 렌더러에 풀 스크린 능력이 있을지 어떨지를 나타내는 값에의 포인터. 렌더러가 풀 스크린 비디오를 지원 하고 있는 경우는, OATRUE. 지원 하고 있지 않는 경우는, OAFALSE.

반환값

가능한 반환값은 다음과 같다.

E_NOTIMPL | 필터가 풀 스크린 모드를 지원 하고 있지 않다.
E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

필터 그래프 매니저는, 비디오를 풀 스크린 사이즈로 렌더링 하도록(듯이) 요구되면(자), 이 메소드를 호출한다. 렌더러는, 렌더러 자체가 원래 풀 스크린 재생을 지원 하고 있지 않는 경우는 E_NOTIMPL 를 돌려주어, 그 이외의 경우에는 NOERROR 를 돌려주지 않으면 안 된다. 렌더러가 풀 스크린 재생을 지원 하고 있는 경우, 이 메소드는 현재 그것이 온이 되어 있는지 어떤지를 판단한다.

IVideoWindow::get_Height

IVideoWindow 인터페이스

비디오 윈도우의 높이를 취득한다.

구문

HRESULT get_Height(
    long *pHeight
);

파라미터

pHeight
[out] 취득된 비디오 윈도우 수직 넓이에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::get_Left

IVideoWindow 인터페이스

비디오 윈도우의 x 축좌표를 취득한다.

구문

HRESULT get_Left(
    long *pLeft
);

파라미터

pLeft
[out] 취득하는 x 축좌표에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::GetMaxIdealImageSize

IVideoWindow 인터페이스

비디오 이미지 재생 (클라이언트) 영역의 이론상의 최대 이미지 사이즈를 취득한다.

구문

HRESULT GetMaxIdealImageSize(
    long *pWidth,
    long *pHeight
);

파라미터

pWidth
[out] 이미지의 폭에의 포인터 (픽셀 단위).
pHeight
[out] 이미지의 높이에의 포인터 (픽셀 단위).

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_FALSE | 최소 이미지 사이즈를 취득할 수 없다.
S_OK | 성공.
VFW_E_WRONG_STATE | 필터가 정지하고 있다.

주의

이 메소드는 다음과 같이 다양한 상황으로 S_FALSE 를 돌려준다.

  • 필터가 IOverlay 트랜스폴트를 사용하고 있다.
  • UseWhenFullScreen 모드가 온이 되어 있다 ( 「IDirectDrawVideo::UseWhenFullScreen 」를 참조할것).
  • 비디오 표면에 최대 오버레이 신축이 없다 (DDCAPS 구조체의 dwMaxOverlayStretch 멤버가 0). 「IDirectDrawVideo::GetCaps 」를 참조할것.

IVideoWindow::get_MessageDrain

IVideoWindow 인터페이스

비디오 윈도우의 메세지를 받아들이는 윈도우를 취득한다.

구문

HRESULT get_MessageDrain(
    OAHWND *Drain
);

파라미터

Drain
[in] 현재 비디오 윈도우의 메세지의 송신지로서 할당할 수 있고 있는 윈도우에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

메세지 drain로서 지정한 윈도우에게 건네지는 Microsoft Win32® 메세지의 일람은, 「IVideoWindow::put_MessageDrain 」의 설명에 기재되어 있다.

IVideoWindow::GetMinIdealImageSize

IVideoWindow 인터페이스

비디오 이미지 재생 (클라이언트) 영역의 이론상의 최소 이미지 사이즈를 취득한다.

구문

HRESULT GetMinIdealImageSize(
    long *pWidth,
    long *pHeight
);

파라미터

pWidth
[out] 이미지의 폭에의 포인터 (픽셀 단위).
pHeight
[out] 이미지의 높이에의 포인터 (픽셀 단위).

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_FALSE | 최소 이미지 사이즈를 취득할 수 없다.
S_OK | 성공.
VFW_E_WRONG_STATE | 필터가 정지하고 있다.

주의

이 메소드는 다음과 같이 다양한 상황으로 S_FALSE 를 돌려준다.

  • 필터가 IOverlay 트랜스폴트를 사용하고 있다.
  • UseWhenFullScreen 모드가 온이 되어 있다 ( 「IDirectDrawVideo::UseWhenFullScreen 」를 참조할것).
  • 신축 가능한 오프 스크린 표면이 비디오 재생으로 사용되고 있다 (DDCAPS 구조체의 dwCaps 멤버에 DDCAPS_BLTSTRETCH 플래그가 포함되어 있다). 「IDirectDrawVideo::GetCaps 」를 참조할것.
  • 비디오 표면에 최소 오버레이 신축이 없다 (DDCAPS 구조체의 dwMinOverlayStretch 멤버가 0). 「IDirectDrawVideo::GetCaps 」를 참조할것.

IVideoWindow::get_Owner

IVideoWindow 인터페이스

비디오 윈도우를 소유하는 부모 윈도우를 취득한다.

구문

HRESULT get_Owner(
    OAHWND *pOwner
);

파라미터

pOwner
[out] 취득된 윈도우 핸들에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::GetRestorePosition

IVideoWindow 인터페이스

복원되는 윈도우의 보통의 넓이를 취득한다.

구문

HRESULT GetRestorePosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

파라미터

pLeft
[out] 윈도우 좌단의 x 축좌표에의 포인터.
pTop
[out] 윈도우 상단의 y 축좌표에의 포인터.
pWidth
[out] 윈도우의 폭에의 포인터 (픽셀 단위).
pHeight
[out] 윈도우의 높이에의 포인터 (픽셀 단위).

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

윈도우가 최대화 또는 최소화되고 있을 때, 윈도우 위치 관계의 메소드는 실제의 윈도우 사이즈를 돌려준다. 이 메소드에서는, 윈도우가 복원되었을 때의 넓이를 돌려준다. 어플리케이션에서는, 윈도우가 최대화 또는 최소화되고 있는 동안, 윈도우 상태를 보존해 두기 위해서(때문에), 이 메소드를 사용할 수 있다.

IVideoWindow::get_Top

IVideoWindow 인터페이스

비디오 윈도우의 y 축좌표를 취득한다.

구문

HRESULT get_Top(
    long *pTop
);

파라미터

pTop
[out] 취득된 y 축의 기점에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::get_Visible

IVideoWindow 인터페이스

비디오 윈도우의 표시/비표시를 취득한다.

구문

HRESULT get_Visible(
    long *pVisible
);

파라미터

pVisible
[out] 윈도우가 표시되고 있는지 어떤지를 나타내는 값에의 포인터. OATRUE 는 표시되고 있는 것을 나타내, 그 이외의 경우는 비표시를 나타낸다.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::get_Width

IVideoWindow 인터페이스

비디오 윈도우의 폭을 취득한다.

구문

HRESULT get_Width(
    long *pWidth
);

파라미터

pWidth
[out] 취득된 폭에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::GetWindowPosition

IVideoWindow 인터페이스

(클라이언트 직사각형은 아니고) 현재의 윈도우 직사각형을 디바이스 좌표로 취득한다.

구문

HRESULT GetWindowPosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

파라미터

pLeft
[out] 윈도우의 x 축의 기점에의 포인터.
pTop
[out] 윈도우의 y 축의 기점에의 포인터.
pWidth
[out] 윈도우의 폭에의 포인터 (픽셀 단위).
pHeight
[out] 윈도우의 높이에의 포인터 (픽셀 단위).

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드의 효과는,IVideoWindow::get_Left 메소드,IVideoWindow::get_Top 메소드,IVideoWindow::get_Width 메소드, 및 IVideoWindow::get_Height 메소드를 개별적으로 호출했을 경우와 동일하다.

IVideoWindow::get_WindowState

IVideoWindow 인터페이스

비디오 윈도우 상태를 돌려준다.

구문

HRESULT get_WindowState(
    long *WindowState
);

파라미터

WindowState
[out] 비디오 윈도우 상태를 나타내는 플래그에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드는, 윈도우 상태 (즉, SW_MINIMIZE, SW_MAXIMIZE, SW_SHOW, 또는 SW_HIDE)의 프로퍼티의 서브 세트를 취득한다. 이러한 윈도우 상태의 정의는, Win32 ShowWindow 함수와 같다.

IVideoWindow::get_WindowStyle

IVideoWindow 인터페이스

비디오 윈도우의 윈도우 스타일을 취득한다.

구문

HRESULT get_WindowStyle(
    long *pWindowStyle
);

파라미터

pWindowStyle
[out] Win32 GetWindowLong 함수의 GWL_STYLE 값으로 설정할 수 있는 플래그의 서브 세트와 대응하는 플래그 세트에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

윈도우 스타일의 일람에 대해서는, Platform Software Development Kit (SDK)의 「CreateWindow 함수」를 참조할것.

IVideoWindow::get_WindowStyleEx

IVideoWindow 인터페이스

비디오 윈도우의 확장 스타일을 취득한다.

구문

HRESULT get_WindowStyleEx(
    long *pWindowStyleEx
);

파라미터

pWindowStyleEx
[out, retval] Win32 GetWindowLong 함수의 GWL_STYLE 값으로 설정할 수 있는 플래그의 서브 세트와 대응하는 플래그 세트에의 포인터.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드는, 확장 윈도우 스타일을 사용한다. 윈도우 스타일의 일람에 대해서는, Platform SDK 의 「CreateWindow 함수」를 참조할것.

IVideoWindow::HideCursor

IVideoWindow 인터페이스

커서를 비표시로 한다.

구문

HRESULT HideCursor(
    long HideCursor
);

파라미터

HideCursor
[in] 커서를 비표시로 할지 어떨지를 지정하는 값. OATRUE 의 경우는, 커서를 표시하지 않는다. OAFALSE 의 경우는, 커서를 표시한다.

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드는, 보통, 비디오 렌더러가 풀 스크린 모드 (커서를 표시하고 싶지 않은 것이 있다) 때에 사용된다.

IVideoWindow::IsCursorHidden

IVideoWindow 인터페이스

커서의 표시/비표시를 판단한다.

구문

HRESULT IsCursorHidden(
    long *CursorHidden
);

파라미터

CursorHidden
[out] 커서가 비표시가 되어 있는지 어떤지를 나타내는 값에의 포인터. OATRUE 의 경우, 커서는 비표시. OAFALSE 의 경우, 커서는 표시되고 있다.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드는, 보통, 비디오 렌더러가 풀 스크린 모드 (커서를 표시하고 싶지 않은 것이 있다) 때에 사용된다.

IVideoWindow::NotifyOwnerMessage

IVideoWindow 인터페이스

부모 윈도우로부터 받은 메세지를, 필터가 소유하는 자식 윈도우에 전송 한다.

구문

HRESULT NotifyOwnerMessage(
    long hwnd,
    long uMsg,
    long wParam,
    long lParam
    );

파라미터

hwnd
[in] 윈도우 핸들.
uMsg
[in] 보내려 하고 있는 메세지.
wParam
[in] 메세지에게 건네진 wParam.
lParam
[in] 메세지에게 건네진 lParam.

반환값

가능한 반환값은 다음과 같다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드는, 렌더러 윈도우를 자식 윈도우로 하는 윈도우로부터 사용해야 한다. 이 메소드는, 보통이라면 자식 윈도우가 받을리가 없는 다수의 메세지를, 자식 윈도우에 전송 한다. 전송 되는 메세지에는, 다음과 같은 것이 있다.

  • WM_ACTIVATEAPP
  • WM_DEVMODECHANGE
  • WM_DISPLAYCHANGE
  • WM_PALETTECHANGED
  • WM_PALETTEISCHANGING
  • WM_QUERYNEWPALETTE
  • WM_SYSCOLORCHANGE

IVideoWindow::put_AutoShow

IVideoWindow 인터페이스

윈도우가 자동적으로 표시될지 어떨지를 판단한다.

구문

HRESULT put_AutoShow(
    long AutoShow
);

파라미터

AutoShow
[in] 윈도우가 자동적으로 표시될지 어떨지를 지정하는 값. OATRUE (–1)는, 상태가 바뀌면(자) 윈도우가 표시되는 것을 의미한다. OAFALSE (0)의 경우, 명시적으로 표시하지 않는 한, 윈도우는 표시되지 않는다.

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

간단한 어플리케이션에서는, 필터 그래프가 실행 상태에 들어갈 때, 표시된 윈도우가 필요하게 되는 것이 많다. 디폴트에서는,AutoShow 가 OATRUE 가 되어, 그래프가 포즈 상태 또는 실행 상태로 바뀌면(자) 윈도우가 표시된다 (윈도우는 한층 더 전면 윈도우로서 설정된다). 그 후, 포즈 상태 또는 실행 상태로 바뀌어도, 윈도우가 비표시가 될 것은 없다. 스트림의 실행중에 윈도우를 닫았을 경우, 윈도우는 자동적으로 재표시되지 않는다. 다만, 스트림을 정지 후에 한번 더 시작 하면, 윈도우가 자동적으로 재표시된다.

참조

IVideoWindow::put_Visible

IVideoWindow::put_BackgroundPalette

IVideoWindow 인터페이스

필요한 팔레트가 백그라운드에서 인식될지 어떨지를 판단한다.

구문

HRESULT put_BackgroundPalette(
    long BackgroundPalette
);

파라미터

BackgroundPalette
[in] 팔레트가 백그라운드에서 인식될지 어떨지를 지정하는 값. 팔레트를 백그라운드에서 인식하려면 , OATRUE (–1)를 설정한다. 그 이외의 경우는, OAFALSE 를 설정한다.

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

BackgroundPalette 가 OATRUE 의 경우, 렌더러로 비디오에 필요한 팔레트가 백그라운드에서 인식된다. 이것은, 팔레트가 사용하는 색이 모두, 드로잉(Drawing)전에 디스플레이 팔레트내의 가장 가까운 색으로 변경되는 것을 의미한다. 이 결과, 비디오 재생시에 어플리케이션의 팔레트가 영향을 받지 않는다. 다만, 비디오의 퍼포먼스에 큰 영향이 나오므로, 아무래도 필요한 경우 이외는 사용하지 않는 것. 이 프로퍼티의 디폴트값은 OAFALSE.

IVideoWindow::put_BorderColor

IVideoWindow 인터페이스

비디오 윈도우의 경계색을 설정한다.

구문

HRESULT put_BorderColor(
    long Color
);

파라미터

Color
[in] COLORREF 형의 새로운 경계색.

반환값

가능한 반환값은 다음과 같다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

설정하는 전송처 직사각형이, 윈도우의 클라이언트 가시 영역과 다를 때는, 인연의 주위에 경계가 표시된다. 이 메소드를 사용 하면, 어플리케이션으로부터 이 경계의 색을 변경할 수 있다. 경계색의 디폴트값은 흑이다. 시스템 칼라 이외의 색을 건네주면(자), 사용전에 현재의 팔레트에 근거하는 가장 가까운 색에 변환된다 (트루 칼라 디바이스 이외에도 같이). 경계색을 설정 하면, 윈도우의 경계가 새로운 색으로 자동적으로 재드로잉(Drawing) 된다.

IVideoWindow::put_Caption

IVideoWindow 인터페이스

비디오 윈도우의 타이틀 캐릭터 라인을 설정한다.

구문

HRESULT put_Caption(
    BSTR strCaption
);

파라미터

strCaption
[in] 윈도우의 타이틀 캡션.

반환값

가능한 반환값은 다음과 같다.

E_POINTER | NULL 포인터.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::put_FullScreenMode

IVideoWindow 인터페이스

이 인터페이스를 지원 하고 있는 비디오 렌더링 필터의 풀 스크린 모드를 설정한다.

구문

HRESULT put_FullScreenMode(
    long FullScreenMode
);

파라미터

FullScreenMode
[in] 비디오 렌더링 필터가 풀 스크린 모드를 지원 하고 있을지 어떨지를 지정하는 값. 풀 스크린 비디오를 지원 하고 있는 경우는, OATRUE 를 설정한다. 그 이외의 경우는, OAFALSE 를 설정한다.

반환값

가능한 반환값은 다음과 같다.

E_NOTIMPL | 필터가 풀 스크린 모드를 지원 하고 있지 않다.
S_FALSE | 필터가 이미 요구된 모드가 되어 있다.
S_OK | 성공.

주의

이 메소드를 사용 하면, 어플리케이션으로부터 풀 스크린 렌더러를, 풀 스크린 모드로 전환하거나 풀 스크린 모드로부터 바꾸거나 할 수가 있다. 렌더러가 풀 스크린 모드로부터 교체되었을 때의 동작은, 이행에 따라서 다르다. 예를 들어, Microsoft 의 풀 스크린 렌더러에서는, 윈도우 모드에 돌아온다.

필터 그래프 매니저의 IVideoWindow PID 는, 풀 스크린 렌더러의 변환을 이행 한다. PID 는, 풀 스크린 모드를 지원 하는 렌더러를 그래프내로부터 찾아, 발견되지 않는 경우에는, 렌더러를 디폴트의 DirectShow 풀 스크린 렌더러에 일시적으로 옮겨놓는다. IVideoWindow::GetMaxIdealImageSize 를 호출해, 윈도우를 맨 앞면윈도우로 해, 화면 전체에 사이즈 변경할 수가 있을지 어떨지를 판단한다. 필터 그래프는 DirectDraw® 오버레이 또는 하드웨어 디코더 필터를 사용하고 있을 가능성이 있기 (위해)때문에, 렌더러를 교환하는 것보다 이 방법이 바람직하다.

IVideoWindow::put_Height

IVideoWindow 인터페이스

비디오 윈도우의 높이를 설정한다.

구문

HRESULT put_Height(
    long Height
);

파라미터

Height
[in] 비디오 윈도우의 새로운 수직 넓이.

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

비디오 윈도우의 y 축좌표는, 이 메소드의 호출에 의해 영향을 받지 않는다.

IVideoWindow::put_Left

IVideoWindow 인터페이스

비디오 윈도우의 x 축좌표를 설정한다.

구문

HRESULT put_Left(
    long Left
);

파라미터

Left
[in] 설정하는 x 축좌표.

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

비디오 윈도우의 폭은, 이 메소드의 호출에 의해 영향을 받지 않는다.

IVideoWindow::put_MessageDrain

IVideoWindow 인터페이스

비디오 윈도우의 메세지의 송신지 윈도우를 지정한다.

구문

HRESULT put_MessageDrain(
    OAHWND Drain
);

파라미터

Drain
[in] 메세지의 송신지 윈도우.

반환값

가능한 반환값은 다음과 같다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

비디오 렌더러는, Win32 PostMessage 함수를 호출해, 지정된 메세지 drain에 메세지를 건네준다. 이러한 메세지를 사용 하면, 유저의 개입 (비디오 표시의 특정 영역내를 마우스로 클릭하는 등)을 수반하는 어플리케이션을 개발할 수 있다. 어플리케이션에서는, 비디오 윈도우와 긴밀한 관계를 유지해, 유저의 개입을 조사해야 할 시기를 알 수 있다. 렌더러로부터 메세지 drain에 메세지가 건네받을 때, 파라미터 (클라이언트 영역의 좌표등)는 전혀 손보지 않고 보내진다.

어플리케이션이 다음의 메세지를 생성 하면, DirectShow 는 그것을 Drain 파라미터로 지정된 윈도우에 건네준다.

  • WM_KEYDOWN
  • WM_KEYUP
  • WM_LBUTTONDBLCLK
  • WM_LBUTTONDOWN
  • WM_LBUTTONUP
  • WM_MBUTTONDBLCLK
  • WM_MBUTTONDOWN
  • WM_MBUTTONUP
  • WM_MOUSEACTIVATE
  • WM_MOUSEMOVE
  • WM_NCLBUTTONDBLCLK
  • WM_NCLBUTTONDOWN
  • WM_NCLBUTTONUP
  • WM_NCMBUTTONDBLCLK
  • WM_NCMBUTTONDOWN
  • WM_NCMBUTTONUP
  • WM_NCMOUSEMOVE
  • WM_NCRBUTTONDBLCLK
  • WM_NCRBUTTONDOWN
  • WM_NCRBUTTONUP
  • WM_RBUTTONDBLCLK
  • WM_RBUTTONDOWN
  • WM_RBUTTONUP

이 멤버 함수는, 메세지 drain 윈도우를 자식 윈도우로 하지 않기 때문에, 풀 스크린 능력이 있는 어플리케이션으로부터 사용할 수 있다.

IVideoWindow::put_Owner

IVideoWindow 인터페이스

비디오 윈도우를 소유하는 부모 윈도우를 설정한다.

구문

HRESULT put_Owner(
    OAHWND Owner
);

파라미터

Owner
[in] 새로운 소유자 윈도우의 핸들.

반환값

가능한 반환값은 다음과 같다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드는, 어플리케이션으로부터 비디오 윈도우의 소유자를 설정하기 위한 수단을 제공해, 복합 문서내의 비디오를 재생할 경우에 자주(잘) 사용된다. 이 메소드는, 렌더러 윈도우의 부모를 변경해, 비디오 윈도우에 대응하는 WS_CHILD 스타일을 설정한다.

비디오 윈도우 메세지를 부모 윈도우에 전송 하려면 , 부모 윈도우의 윈도우 핸들을 지정해 IVideoWindow::put_MessageDrain 메소드를 사용한다. 이 메세지는, 메세지를 자동적으로 송신하지 않는다.

이 메세지를 사용해 비디오 윈도우의 소유자를 설정했을 경우는, 필터 그래프를 해방하기 전에 (put_Owner(NULL)를 호출해) 소유자를 NULL 에 리셋 할 필요가 있다. 그렇게 하지 않으면 계속해 이 윈도우에 메세지가 보내져 어플리케이션 종료시에 에러가 발생할 가능성이 높다.

IVideoWindow::put_Top

IVideoWindow 인터페이스

비디오 윈도우의 y 축좌표를 설정한다.

구문

HRESULT put_Top(
    long Top
);

파라미터

Top
[in] 비디오 윈도우의 y 축의 기점.

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

비디오 윈도우의 높이는, 이 메소드의 호출에 의해 영향을 받지 않는다.

IVideoWindow::put_Visible

IVideoWindow 인터페이스

비디오 윈도우의 표시/비표시를 변경한다.

구문

HRESULT put_Visible(
    long Visible
);

파라미터

Visible
[in] Automation 호환의 불형 플래그.

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

Visible 파라미터에 OATRUE (–1)를 설정 하면, 윈도우가 표시된다. OAFALSE (0)를 설정 하면, 윈도우가 비표시가 된다.

IVideoWindow::put_Width

IVideoWindow 인터페이스

비디오 윈도우의 폭을 설정한다.

구문

HRESULT put_Width(
    long Width
);

파라미터

Width
[in] 설정하는 폭 (픽셀 단위).

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

비디오 윈도우의 x 축좌표는, 이 메소드의 호출에 의해 영향을 받지 않는다.

IVideoWindow::put_WindowState

IVideoWindow 인터페이스

비디오 윈도우 상태를 설정한다.

구문

HRESULT put_WindowState(
    long WindowState
);

파라미터

WindowState
[in] 비디오 윈도우 상태를 기술한다.

반환값

가능한 반환값은 다음과 같다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드는, Microsoft Win32 ShowWindow 함수의 래퍼이다. WindowState 파라미터는,IVideoWindow::put_WindowState 로부터 CBaseWindow::DoShowWindow 에게 건네져 한층 더 거기로부터 ShowWindow 에게 건네진다. 따라서,WindowState 에는 ShowWindow 에 유효한 임의의 값을 지정할 수 있다.

IVideoWindow::put_WindowStyle

IVideoWindow 인터페이스

비디오 윈도우의 스타일 파라미터를 변경한다.

구문

HRESULT put_WindowStyle(
    long WindowStyle
);

파라미터

WindowStyle
[in] Win32 GetWindowLong 함수의 GWL_STYLE 값으로 설정할 수 있는 플래그의 서브 세트와 대응하는 플래그 세트.

반환값

가능한 반환값은 다음과 같다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 프로퍼티를 사용해, 예를 들어 비디오 윈도우의 경계 및 캡션의 영역을 삭제하는 등, 비디오 윈도우의 전체적인 스타일을 변경한다. 이것은, Microsoft Win32 GetWindowLong 함수의 GWL_STYLE 값의 설정을 제어하는 매우 얇은 래퍼이므로, 취급에는 충분한 주의가 필요하다. 특히, 최초로 현재의 스타일을 취득한 데다가, 필요한 비트 필드를 추가 또는 삭제하는 것은 중요하다. (여기서 설명한다) 일부의 예외를 제외해, 사용 가능한 플래그는, Win32 CreateWindow 함수의 경우와 같다.

이 메소드를 사용해, 윈도우 사이즈에 영향을 주어서는 안 된다. 예를 들어, 윈도우가 최소화되고 있을 때 WS_MAXIMIZE 스타일을 설정했을 경우, 결과는 예측 불가능하다. 윈도우를 최대화 또는 최소화하려면 , 이 메소드는 아니고 IVideoWindow::put_WindowState 메소드를 사용한다.

이하의 스타일에서는, 모두 E_INVALIDARG 를 돌려준다.

  • WS_DISABLED
  • WS_HSCROLL
  • WS_ICONIC
  • WS_MAXIMIZE
  • WS_MINIMIZE
  • WS_VSCROLL

IVideoWindow::put_WindowStyleEx

IVideoWindow 인터페이스

컨트롤 윈도우의 스타일을 설정한다.

구문

HRESULT put_WindowStyleEx(
    long WindowStyleEx
);

파라미터

WindowStyleEx
[in] 컨트롤 윈도우의 스타일을 지정하는 값.

반환값

가능한 반환값은 다음과 같다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드는, 확장 윈도우 스타일을 사용한다. 윈도우 스타일의 일람에 대해서는, Platform SDK 의 「CreateWindowEx 함수」를 참조할것.

이 프로퍼티를 사용해, 예를 들어 비디오 윈도우의 경계 및 캡션의 영역을 삭제하는 등, 비디오 윈도우의 전체적인 스타일을 변경한다. 이것은, Microsoft Win32 GetWindowLong 함수의 GWL_STYLE 값의 설정을 제어하는 매우 얇은 래퍼이므로, 취급에는 충분한 주의가 필요하다. 특히, 최초로 현재의 스타일을 취득한 데다가, 필요한 비트 필드를 추가 또는 삭제하는 것은 중요하다.

다음의 윈도우 스타일은 유효하지 않기 때문에 사용하지 않는 것.

  • WS_DISABLED
  • WS_HSCROLL
  • WS_ICONIC
  • WS_MAXIMIZE
  • WS_MINIMIZE
  • WS_VSCROLL

(여기서 설명한다) 일부의 예외를 제외해, 사용 가능한 플래그는, Win32 CreateWindow 함수의 경우와 같다.

IVideoWindow::SetWindowForeground

IVideoWindow 인터페이스

비디오 윈도우를 전면으로 이동해, 옵션으로 그 윈도우에 포커스를 준다.

구문

HRESULT SetWindowForeground(
    long Focus
);

파라미터

Focus
비디오 윈도우에 포커스를 줄지 어떨지를 지정하는 값. –1 의 경우는, 포커스를 준다. 0 의 경우는, 주지 않는다.

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

IVideoWindow::SetWindowPosition

IVideoWindow 인터페이스

(클라이언트의 직사각형은 아니고) 비디오 윈도우의 위치를 디바이스 좌표로 설정한다.

구문

HRESULT SetWindowPosition(
    long Left,
    long Top,
    long Width,
    long Height
);

파라미터

Left
[in] 윈도우의 x 축의 기점.
Top
[in] 윈도우의 y 축의 기점.
Width
[in] 윈도우의 폭 (픽셀 단위).
Height
[in] 윈도우의 높이 (픽셀 단위).

반환값

가능한 반환값은 다음과 같다.

E_INVALIDARG | 무효인 인수.
S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되지 않는다.

주의

이 메소드의 효과는,IVideoWindow::put_Left 메소드,IVideoWindow::put_Top 메소드,IVideoWindow::put_Width 메소드, 및 IVideoWindow::put_Height 메소드를 개별적으로 호출했을 경우와 동일하다.

비디오의 표시 위치를 윈도우 좌표로 지정한다. 예를 들어, (100,50,200,400)라고 하는 전송처를 설정 하면, 비디오 재생의 기점이 클라이언트 영역의 왼쪽으로부터 100 픽셀, 위로부터 50 픽셀로 설정되어 전체의 사이즈가 200 × 400 픽셀이 된다. 비디오가 이것보다 작은 경우 (또는 전송원직사각형이 비디오보다 작은 사이즈로 지정되고 있는 경우)에는, 이 사이즈에 맞추어 비디오가 신축된다. 같이 비디오가 전송처 직사각형보다 큰 경우에는, 표시 직사각형에 맞추어 비디오가 압축된다. 이러한 처리는 퍼포먼스에 매우 큰 영향을 주므로, 어플리케이션에서는 전송원직사각형과 전송처 직사각형을 가능한 한 동일하게 하는 것.

보통의 상황에서는, 전송처 직사각형이 설정되어 있지 않을 때, (유저에 의한 윈도우의 신축의 정도에 관계없이) 윈도우의 클라이언트 표시 영역 전체가 비디오로 전부 칠해진다. 게다가 전송처 직사각형의 프로퍼티는, 비디오 윈도우의 클라이언트 영역의 올바른 사이즈를 돌려준다.


IVPBaseConfig 인터페이스

IVPBaseConfig 는, 디코더등의 하드웨어 디바이스에 그래픽스 어댑터에의 비디오 포토가 있는 경우에, 이러한 디바이스를 랩 하는 필터에 이행 된다. 이 인터페이스를 사용 하면, 비디오 포토가오버레이 믹서와의 사이에 구성 정보를 교환할 수 있다. IVPConfig 인터페이스는, 이 인터페이스로부터 파생한다. 「IVPBaseNotify 」 및「IVPNotify 」를 참조할것.

어플리케이션으로부터 이 인터페이스를 사용하지 않는 것.

요건

Dvp.h, Vptype.h, Vpconfig.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IVPBaseConfig 메소드 | 설명
GetConnectInfo | connection 정보의 구조체를 취득한다.
SetConnectInfo | 비디오 포토의 현재의 connection 정보의 인덱스를 설정한다.
GetVPDataInfo | 비디오 포토의 현재의 데이터 정보를 취득한다.
GetMaxPixelRate | 소정의 폭 및 높이에 대응하는 최대 레이트 (픽셀/초)를 취득한다.
InformVPInputFormats | 비디오 포토가 지원 하는 비디오 포맷을 디바이스에 알린다.
GetVideoFormats | 디코더가 지원 하는 비디오 포맷을 취득한다.
SetVideoFormat | 비디오가 사용하는 포맷을 설정한다.
SetInvertPolarity | 디코더가 사용하는 현재의 극성을 반전한다.
GetOverlaySurface | 오버레이 믹서가 드라이버의 오버레이 표면을 사용해야할 것인가 제발 판단해, 사용해야 할 경우에는 표면에의 포인터를 취득한다.
SetDirectDrawKernelHandle | 디코더의 미니 드라이버가 사용하는 Microsoft® DirectDraw® 커넬 핸들을 설정한다.
SetVideoPortID | 비디오가 사용하는 포토 ID 를 설정한다.
SetDDSurfaceKernelHandle | DirectDraw 표면이 사용하는 커넬 핸들을 설정한다.
SetSurfaceParameters | 오버레이 믹서 필터 또는 VBI 표면 필터가 대신에 생성 한 표면에 대해, 캡춰 드라이버에 알린다.

IVPBaseConfig::GetConnectInfo

IVPBaseConfig 인터페이스

connection 정보의 구조체를 취득한다.

구문

HRESULT GetConnectInfo(
    LPDWORD pdwNumConnectInfo,
    LPDDVIDEOPORTCONNECT pddVPConnectInfo
    );

파라미터

pdwNumConnectInfo
[in, out] pddVPConnectInfo 파라미터가 가리키는 DDVIDEOPORTCONNECT 구조체의 수가 들어간 버퍼에의 포인터. 실제로 돌려주어진 구조체의 수가 저장 된다. pddVPConnectInfo 가 NULL 의 경우, 이 파라미터는 드라이버로 지원 되는 구조체의 수로 옮겨진다.
pddVPConnectInfo
[in, out] 드라이버가 설정하는 DDVIDEOPORTCONNECT 구조체의 배열에의 포인터. 지원 되는 포맷의 총수를 취득하려면 , NULL 를 지정한다.

반환값

카운트 또는 구조체가 취득되었을 경우는, NOERROR 를 돌려준다. 그 이외의 경우는, 드라이버 에러를 돌려준다.

주의

이 메소드는,GUID 나 포토폭등의 각종 connection 정보의 구조체를,pddVPConnectInfo 로 지정된 구조체의 배열에 취득한다. 호출처에서는, 요구하는 구조체의 수에 적절한 올바른 용량을 할당할 필요가 있다.

connection 정보의 인덱스를 설정하려면 ,IVPBaseConfig::SetConnectInfo 메소드를 사용한다.

IVPBaseConfig::GetMaxPixelRate

IVPBaseConfig 인터페이스

소정의 폭 및 높이에 대응하는 최대 레이트 (픽셀/초)를 취득한다.

구문

HRESULT GetMaxPixelRate(
    LPAMVPSIZE pamvpSize,
    LPDWORD pdwMaxPixelsPerSecond
    );

파라미터

pamvpSize
[in, out] 희망하는 폭 및 높이가 저장 된 AMVPSIZE 구조체에의 포인터. 메소드로부터 돌아올 때는, 이 구조체에 최종적인 넓이가 들어간다.
pdwMaxPixelsPerSecond
[out] 취득된 최대 레이트 (픽셀/초)에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | NULL 포인터 인수.
E_INVALIDARG | 무효인 인수.
NOERROR | 최대 레이트 (픽셀/초)가 취득되었다.

주의

이 메소드는, 소정의 포맷 및 소정의 스케일링 계수로 예상되는 최대 레이트 (픽셀/초)를 취득한다. 디코더가 이러한 스케일링 계수를 지원 하고 있지 않는 경우는, 레이트 및 지원 하는 가장 가까운 스케일링 계수를 돌려준다.

IVPBaseConfig::GetOverlaySurface

IVPBaseConfig 인터페이스

오버레이 믹서가 드라이버의 오버레이 표면을 사용해야할 것인가 제발 판단해, 사용해야 할 경우에는 표면에의 포인터를 취득한다.

구문

HRESULT GetOverlaySurface(
    LPDIRECTDRAWSURFACE *ppddOverlaySurface
    );

파라미터

ppddOverlaySurface
[out] 취득된 DirectDraw® 오버레이 표면 오브젝트에의 포인터의 주소.

반환값

오버레이 표면 오브젝트가 돌려주어졌을 경우는, NOERROR 를 돌려준다 (디폴트의 이행에서는, 표면에 NULL 를 설정해, NOERROR 를 돌려준다).

주의

오버레이 믹서는, 이 함수를 사용해, 오버레이 믹서가 드라이버측의 오버레이 표면을 사용할 필요가 있을지 어떨지 판단해, 필요가 있는 경우에는 그 포인터를 취득한다. 이 함수가 NULL 를 돌려주었을 경우에는, 오버레이 믹서가 독자적인 표면을 할당한다.

IVPBaseConfig::GetVideoFormats

IVPBaseConfig 인터페이스

디코더가 지원 하는 비디오 포맷을 취득한다.

구문

HRESULT GetVideoFormats(
    LPDWORD pdwNumFormats,
    LPDDPIXELFORMAT pddPixelFormats
    );

파라미터

pdwNumFormats
[in, out] pddPixelFormats 파라미터가 가리키는 DDPIXELFORMAT 구조체의 수에의 포인터. 호출하면, 이 메소드는 이 파라미터를 실제로 취득된 구조체의 수에 옮겨놓는다. pddPixelFormats 가 NULL 의 경우, 이 메소드는 이 파라미터를 드라이버가 지원 하는 포맷의 수에 옮겨놓는다.
pddPixelFormats
[in, out] 드라이버가 설정하는 DDPIXELFORMAT 구조체의 배열에의 포인터. 지원 되는 포맷의 총수만을 pdwNumFormats 에 취득하려면 , NULL 를 지정한다.

반환값

수 또는 구조체가 돌려주어졌을 경우는, NOERROR 를 돌려준다. 그 이외의 경우는, 드라이버 에러를 돌려준다.

주의

이 메소드는, 드라이버로 지원 되는 DDPIXELFORMAT 구조체의 수를 조회하는지, 또는 제공된 버퍼에 들어가는 것으로 올 뿐(만큼) 많은 구조체를 취득한다.

호출처에서는, 요구된 구조체의 수에 적절한 올바른 용량을 할당할 필요가 있다.

비디오 포맷을 설정하려면 ,IVPBaseConfig::SetVideoFormat 를 사용한다.

IVPBaseConfig::GetVPDataInfo

IVPBaseConfig 인터페이스

비디오 포토의 현재의 데이터 정보를 취득한다.

구문

HRESULT GetVPDataInfo(
    LPAMVPDATAINFO pamvpDataInfo
    );

파라미터

pamvpDataInfo
[in, out] AMVPDATAINFO 데이터 정보의 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | NULL 포인터 인수.
E_INVALIDARG | 무효인 인수.
NOERROR | 비디오 포토의 데이터 정보가 취득되었다.

IVPBaseConfig::InformVPInputFormats

IVPBaseConfig 인터페이스

비디오 포토가 지원 하는 비디오 포맷을 디바이스에 알린다.

구문

HRESULT InformVPInputFormats(
    DWORD dwNumFormats,
    LPDDPIXELFORMAT pDDPixelFormats
    );

파라미터

dwNumFormats
[in] pDDPixelFormats 파라미터에 저장 된 비디오 포맷의 수.
pDDPixelFormats
[in] 디바이스에 보내는 픽셀 포맷 구조체 (DDPIXELFORMAT )의 배열에의 포인터.

반환값

실패했을 경우는, S_FALSE 를 돌려준다. 그 이외의 경우는, NOERROR 를 돌려준다.

주의

지원 되는 비디오 포토 포맷으로서 지정한 배열에 의해, 디바이스가 그러한 포맷을 제시하는 순서가 정해지는 일이 있다.

IVPBaseConfig::SetConnectInfo

IVPBaseConfig 인터페이스

비디오 포토의 현재의 connection 정보의 인덱스를 설정한다.

구문

HRESULT SetConnectInfo(
    DWORD dwChosenEntry
    );

파라미터

dwChosenEntry
[in] 드라이버에 건네주는 (비디오 포토의) 새로운 connection 정보의 인덱스 (0 베이스).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
NOERROR | 비디오 포토의 connection 정보가 설정되었다.

주의

connection 정보를 취득하려면 ,IVPBaseConfig::GetConnectInfo 를 사용한다.

IVPBaseConfig::SetDDSurfaceKernelHandle

IVPBaseConfig 인터페이스

DirectDraw 표면에 의해 사용되는 커넬 핸들을 설정한다.

구문

HRESULT SetDDSurfaceKernelHandle(
    DWORD dwDDKernelHandle
    );

파라미터

dwDDKernelHandle
[in] 커넬 모드용의 DirectDraw 표면 핸들. DWORD 값으로서 건네준다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
NOERROR | 지정된 핸들의 설정에 성공했다.

주의

이 메소드는, 미니 드라이버에 DirectDraw 핸들을 설정해, 미니 드라이버가 비디오 포토와 직접 통신할 수 있도록(듯이) 한다.

IVPBaseConfig::SetDirectDrawKernelHandle

IVPBaseConfig 인터페이스

디코더의 미니 드라이버가 사용하는 DirectDraw® 커넬 핸들을 설정한다.

구문

HRESULT SetDirectDrawKernelHandle(
    DWORD dwDDKernelHandle
    );

파라미터

dwDDKernelHandle
[in] DirectDraw 커넬 레벨의 핸들. DWORD 값으로서 건네준다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
NOERROR | 지정된 핸들의 설정에 성공했다.

IVPBaseConfig::SetInvertPolarity

IVPBaseConfig 인터페이스

디코더가 사용하는 현재의 극성을 반전한다.

구문

HRESULT SetInvertPolarity(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
NOERROR | 극성이 반전되었다.

주의

극성을 반전 하면은, 디코더에 대해, 짝수필드는 홀수 필드로서 취급해, 반대로 홀수 필드는 짝수 필드로서 취급하도록(듯이) 요구하는 것을 의미한다.

IVPBaseConfig::SetSurfaceParameters

IVPBaseConfig 인터페이스

오버레이 믹서 필터 또는 VBI 표면 필터가 대신에 생성 한 표면에 대해, 캡춰 드라이버에 알린다.

구문

HRESULT SetSurfaceParameters(
    DWORD dwPitch,
    DWORD dwXOrigin,
    DWORD dwYOrigin ) PURE;

파라미터

dwPitch
[in] 표면의 피치. 표면이 연속하는 2 라인의 시작 픽셀간의 거리 (또는 피치). 픽셀 단위로 나타낸다.
dwXOrigin
[in] 유효 데이터가 시작 하는 픽셀의 X 값.
dwYOrigin
[in] 유효 데이터가 시작 하는 픽셀의 Y 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재의 디폴트의 이행은, 호출이 성공했을 경우, NOERROR 를 돌려주어, 메소드가 이행되어 있지 않은 경우, E_NOTIMPL 를 돌려준다.

IVPBaseConfig::SetVideoFormat

IVPBaseConfig 인터페이스

비디오가 사용하는 포맷을 설정한다.

구문

HRESULT SetVideoFormat(
    DWORD dwChosenEntry
    );

파라미터

dwChosenEntry
[in] 비디오의 픽셀 포맷의 인덱스 (0 베이스)를 지정하는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
NOERROR | 새로운 비디오 포맷이 설정되었다.

주의

비디오 포맷을 취득하려면 ,IVPBaseConfig::GetVideoFormats 를 사용한다.

IVPBaseConfig::SetVideoPortID

IVPBaseConfig 인터페이스

비디오가 사용하는 포토 ID 를 설정한다.

구문

HRESULT SetVideoPortID (
    DWORD dwVideoPortID
    );

파라미터

dwVideoPortID
[in] DirectDraw 비디오 포토 ID.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
NOERROR | 지정된 포토 ID 의 설정에 성공했다.

주의

이 메소드는, 미니 드라이버에 DirectDraw 비디오 포토 ID 를 설정해, 미니 드라이버가 비디오 포토와 직접 통신할 수 있도록(듯이) 한다.


IVPBaseNotify 인터페이스

비디오 포토를 사용하는 디코더등의 하드웨어 디바이스의 프로퍼티를,오버레이 믹서로부터 제어할 수 있도록(듯이) 한다. IVPNotify 인터페이스는, 이 인터페이스로부터 파생한다. 「IVPBaseConfig 」 및 「IVPConfig 」를 참조할것.

어플리케이션으로부터 이 인터페이스를 사용해서는 안 된다.

요건

Vptype.h, Vpnotify.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IVPBaseNotify 메소드 | 설명
RenegotiateVPParameters | 디코더와의 접속을 초기화한다.

IVPBaseNotify::RenegotiateVPParameters

IVPBaseNotify 인터페이스

디코더와의 접속을 초기화한다.

구문

HRESULT RenegotiateVPParameters(void) PURE;

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | NULL 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 에러 없음.

주의

오버레이 믹서 필터는, 디코더 또는 드라이버와의 사이에 (IVPBaseConfig 인터페이스를 사용해) 각종 파라미터를 네고시에이트 한다. 그러한 파라미터의 어느쪽이든 (비디오 포맷, 사이즈등)가 바뀌면(자), 이 메소드를 호출한다. 현재의 오버레이 믹서에서는, 접속 처리 전체를 반복한다. 이 메소드는 그래프의 재생 그 중에서 호출할 수가 있다.


IVPConfig 인터페이스

비디오 포토를 가지는 하드웨어 디코더를 랩 하는 필터에서는, 모두 IVPConfig 를 이행 할 필요가 있다. 이 인터페이스를 사용 하면,오버레이 믹서는, 그 IVPNotify 인터페이스를 통해서, 디스플레이 어댑터의 비디오 메모리에 관한 비디오 포토 위에의 구성 정보를 설정 및 취득할 수 있다. 이 인터페이스는,IVPBaseConfig 로부터 파생한다. 「IVPBaseNotify 」 및 「IVPNotify2 」를 참조할것.

어플리케이션으로부터 이 인터페이스를 사용하지 않는 것.

요건

Dvp.h, Vptype.h, Vpconfig.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IVPBaseConfig 메소드 | 설명
GetConnectInfo | 접속 정보의 구조체를 취득한다.
SetConnectInfo | 비디오 포토의 현재의 접속 정보의 인덱스를 설정한다.
GetVPDataInfo | 비디오 포토의 현재의 데이터 정보를 취득한다.
GetMaxPixelRate | 소정의 폭 및 높이에 대응하는 최대 레이트 (픽셀/초)를 취득한다.
InformVPInputFormats | 비디오 포토가 지원 하는 비디오 포맷을 디바이스에 알린다.
GetVideoFormats | 디코더가 지원 하는 비디오 포맷을 취득한다.
SetVideoFormat | 비디오가 사용하는 포맷을 설정한다.
SetInvertPolarity | 디코더가 사용하는 현재의 극성을 반전한다.
GetOverlaySurface | 오버레이 믹서가 드라이버의 오버레이 표면을 사용해야할 것인가 제발 판단해, 또 사용해야 할 경우에는, 표면에의 포인터를 취득한다.
SetDirectDrawKernelHandle | 디코더의 미니 드라이버가 사용하는 DirectDraw® 커넬 핸들을 설정한다.
SetVideoPortID | 비디오가 사용하는 포토 ID 를 설정한다.
SetDDSurfaceKernelHandle | DirectDraw 표면이 사용하는 커넬 핸들을 설정한다.
SetSurfaceParameters | 캡춰 드라이버에, 오버레이 믹서 필터 또는 VBI 표면 필터로 대신에 생성 된 표면에 대해 알린다.
IVPConfig 메소드 | 설명
IsVPDecimationAllowed | 소정의 문맥으로, 비디오 포토에서의 스케일링이 가능한가 어떤가를 취득한다.
SetScalingFactors | 디코더가 비디오 스트림을 스케일 할 때의 계수를 설정한다.

IVPConfig::IsVPDecimationAllowed

IVPConfig 인터페이스

소정의 문맥으로, 비디오 포토에서의 스케일링이 가능한가 어떤가를 취득한다.

구문

HRESULT IsVPDecimationAllowed(
    AMVP_CONTEXT amvpContext,
    LPBOOL pbIsDecimationAllowed
    );

파라미터

amvpContext
[in] VP 의 데시 메이션 능력을 조회하는 문맥 (비디오 또는 VBI).
pbIsDecimationAllowed
[out] 데시 메이션이 가능한가 어떤가를 나타내는 취득된 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | NULL 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
NOERROR | 에러 없음.

주의

오버레이 믹서 필터는, 이 함수를 사용해, 그 드라이버에서는, 비디오 데이터의 데시 메이션을 믹서측이 독자적인 판단으로 실시할 필요가 있을지 어떨지를 판단한다. 프리뷰 첨부의 캡춰로, VP 믹서 필터에 의해 비디오 포토상에서 스케일링을 하면(자) 형편이 나쁜 경우등에는, 이 함수가 특히 편리하다.

IVPConfig::SetScalingFactors

IVPConfig 인터페이스

디코더가 비디오 스트림을 스케일 할 때의 계수를 설정한다.

구문

HRESULT SetScalingFactors(
    LPAMVPSIZE pamvpSize
    );

파라미터

pamvpSize
[in] 폭 및 높이의 지정에 사용하는 새로운 스케일링 사이즈의 구조체 (AMVPSIZE )에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
NOERROR | 새로운 스케일링 계수가 설정되었다.

주의

지정된 스케일링 계수를 지원 하고 있지 않는 경우에는, 지원 가능한 가장 가까운 계수가 설정된다.


IVPNotify 인터페이스

오버레이 믹서 필터와 하드웨어 디코더를 나타내는 VPE 디코더 필터의 사이의, 로컬인 통신 메카니즘을 지원 한다. 이 인터페이스는,IVPBaseNotify 로부터 파생한다. 「IVPBaseConfig 」 및 「IVPConfig 」를 참조할것.

이 인터페이스를 이행 하는 것은, 오버레이 믹서 필터뿐이다. 어플리케이션으로부터 사용해서는 안 된다.

요건

Vptype.h, Vpnotify.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IVPBaseNotify 메소드 | 설명
RenegotiateVPParameters | 디코더와의 접속을 초기화한다.
IVPNotify 메소드 | 설명
SetDeinterlaceMode | 비인터레이스 모드 (Bob ,Weave 등)를 설정한다.
GetDeinterlaceMode | 비인터레이스 모드 (Bob, Weave 등)를 취득한다.

IVPNotify::GetDeinterlaceMode

IVPNotify 인터페이스

모드 (Bob, Weave 등)를 취득한다.

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT GetDeinterlaceMode(
  AMVP_MODE *pmode
) PURE;

파라미터

pmode
[out] 취득된 모드에의 포인터. 이 값은 AMVP_MODE 열거형의 멤버.

반환값

E_NOTIMPL 를 돌려준다.

IVPNotify::SetDeinterlaceMode

IVPNotify 인터페이스

모드 (Bob, Weave 등)를 설정한다.

구문

HRESULT SetDeinterlaceMode(
    AMVP_MODE mode
    ) PURE;

파라미터

mode
[in] 지정된 모드. 이 값은,AMVP_MODE 열거형의 멤버.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.


IVPNotify2 인터페이스

IVPNotify2 인터페이스는,IVPNotify 를 계승하는 것이어,오버레이 믹서 필터에서만 이행 된다. 이 인터페이스를 사용 하면, 오버레이 믹서로부터 IVPConfig 를 이행 하는 (디코더등의 하드웨어 디바이스상에 있다) 비디오 포토와 통신할 수가 있다.

어플리케이션으로부터 이 인터페이스를 사용해서는 안 된다.

요건

Vptype.h, Vpnotify.h 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IVPNotify2 메소드 | 설명
SetVPSyncMaster | 비디오 포토가 VGA 의 수직 동기를 제어할지 어떨지를 설정한다.
GetVPSyncMaster | 비디오 포토가 VGA 의 동기를 제어할지 어떨지를 확인한다.

IVPNotify2::GetVPSyncMaster

IVPNotify2 인터페이스

비디오 포토가 VGA 의 동기를 제어할지 어떨지를 확인한다.

구문

HRESULT GetVPSyncMaster(
    BOOL *pbVPSyncMaster
) PURE;

파라미터

pbVPSyncMaster
[out] 비디오 포토가 VGA 모니터의 수직 동기를 제어할지 어떨지를 나타내는 값에의 포인터. 포토가 모니터의 동기를 제어하는 경우는 TRUE. 그 이외의 경우는 FALSE.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

IVPNotify2::SetVPSyncMaster

IVPNotify2 인터페이스

비디오 포토가 VGA 의 수직 동기를 제어할지 어떨지를 설정한다.

구문

HRESULT GetVPSyncMaster(
    BOOL bVPSyncMaster
) PURE;

파라미터

bVPSyncMaster
[in] 비디오 포토가 VGA 모니터의 수직 동기를 제어할지 어떨지를 지정하는 값. 포토가 모니터의 동기를 제어하는 경우는 TRUE. 그 이외의 경우는 FALSE.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.


구조체

여기에서는, Microsoft® DirectShow® 의 구조체에 대해 설명한다.

구조체 | 설명
ALLOCATOR_PROPERTIES | allocater의 프로퍼티 (카운트, 사이즈, alignment, 및 프레픽스)가 저장 된다.
AM_DVD_RENDERSTATUS | DVD 비디오 재생 상태를 나타내는 코드가 저장 된다. 이 코드는,IDvdGraphBuilder::RenderDvdVideoVolume 메소드로 사용된다.
AM_MEDIA_TYPE | 미디어 샘플의 타입을 기술한다.
AM_SAMPLE2_PROPERTIES | 범용 미디어 샘플의 프로퍼티를 기술한다.
AMOVIESETUP_FILTER | 필터를 등록하기 위한 필터 정보가 저장 된다.
AMOVIESETUP_MEDIATYPE | 필터를 등록하기 위한 미디어 타입 정보가 저장 된다.
AMOVIESETUP_PIN | 필터를 등록하기 위한 핀 정보가 저장 된다.
AM_STREAM_INFO | 핀에게 건네진 시작 및 정지의 정보가 저장 된다.
AMVABeginFrameInfo | 프레임의 처리를 시작 하기 위해서 필요한 정보를 지정한다.
AMVABUFFERINFO | 버퍼 정보를 기술한다.
AMVACompBufferInfo | 할당할 수 있었던 표면 및 압축 버퍼의 정보를 기술한다.
AMVAEndFrameInfo | 프레임의 처리를 종료하기 위한 정보를 지정한다.
AMVAInternalMemInfo | 하드웨어 추상 계층 (HAL)이 내부에서 사용하기 위해서 할당하는 scratch memory의 양을 지정한다.
AMVAUncompBufferInfo | 할당하는 표면을 기술한다.
AMVAUncompDataInfo | 데이터 입력 스트림의 픽셀 포맷 및 넓이 특성을 지정한다.
AMVPDATAINFO | VP 입력 스트림에 관한 데이터 고유의 특성을 지정한다.
AMVPDIMINFO | VP 입력 스트림에 관한 넓이 특성을 지정한다.
AMVPSIZE | VP 이미지의 폭과 높이를 지정한다.
DVD_ATR | DVD 의 속성을 지정한다.
DVD_DECODER_CAPS | 오디오 디코더의 능력에 관한 정보가 저장 된다.
DVD_HMSF_TIMECODE | 낡은 DVD_TIMECODE 구조체보다 사용하기 쉽게 타임 코드 정보를 캡슐화한다. DVD_HMSF_TIMECODE 는 새로운 DVD2 인터페이스와 함께 사용한다.
DVD_KaraokeAttributes | DVD 디스크의 가라오케 오디오 스트림에 관한 정보가 저장 된다.
DVD_MenuAttributes | DVD 디스크의 메뉴에 관한 정보가 저장 된다.
DVD_MUA_Coeff | DVD 의 멀티 채널 오디오에 대응하는 환경 사운드 믹싱 계수에 관한 정보가 저장 된다.
DVD_MUA_MixingInfo | DVD 디스크의 환경 사운드 믹싱 계수에 관한 정보가 저장 된다.
DVD_MultichannelAudioAttributes | DVD 디스크의 멀티 채널 오디오에 관한 정보가 저장 된다.
DVD_PLAYBACK_LOCATION | DVD 의 재생 위치가 저장 된다.
DVD_PLAYBACK_LOCATION2 | DVD 의 재생 위치가 저장 된다. 새로운 DVD2 인터페이스와 함께 사용한다.
DVD_SubpictureAttributes | DVD 디스크의 서브 픽쳐 스트림에 관한 정보가 저장 된다.
DVD_TIMECODE | DVD 의타임 코드 (시, 분, 초, 및 프레임)가 저장 된다.
DVD_TitleAttributes | DVD 디스크의 타이틀에 관한 정보가 저장 된다.
DVD_VideoAttributes | DVD 디스크의 비디오 스트림에 관한 정보가 저장 된다.
FILTER_INFO | 필터에 관한 정보가 저장 된다.
PIN_INFO | 핀의 정보가 저장 된다.
Quality | 렌더러의 퍼포먼스를 최적화하기 위해(때문에),렌더러내가 데이터 과잉이나 데이터 부족한가를 나타내, 프레임을 가감(상태)하는 퍼센티지를 지정하는 것에 의해, 품질 메세지를 기술한다.
REGFILTER | 레지스트리내의 필터를 기술한다.
REGFILTER2 | IFilterMapper2 인터페이스를 통해서 등록하기 위해서 필터를 기술한다.
REGFILTERPINS | 필터를 등록하기 위한 핀 정보가 저장 된다.
REGFILTERPINS2 | IFilterMapper2 인터페이스를 통해서 필터를 등록하기 위한 정보가 저장 된다.
REGPINMEDIUM | IFilterMapper2 인터페이스를 통해서 등록하기 위해서, (Microsoft Windows® NT DDK 에 정의된) 핀의 미디어를 기술한다.
REGPINTYPES | 필터를 등록하기 위한 미디어 타입 정보가 저장 된다.
STREAM_ID_MAP | MPEG-2 스트림내의 기본 스트림에 대한 정보가 저장 된다.

다음의 구조체는, 그래픽 디바이스 인터페이스 (GDI)의 비트 맵 및 디바이스에 의존하지 않는 비트 맵 (DIB)에 관한 정보를 보관 유지한다. CImageAllocator ,CImageSample , 및 CDrawImage 윈도우 유틸리티 클래스만으로 사용된다.

구조체 | 설명
DIBDATA | 개개의 DIB 에 관한 정보가 저장 된다.

이하의 구조체는, 비디오와 비디오의 캡춰 및 압축에 관한 정보를 보관 유지한다.

구조체 | 설명
TRUECOLORINFO | 색정보를 보관 유지한다.
ANALOGVIDEOINFO | 아날로그 비디오 신호의 포맷에 관한 정보를 보관 유지한다.
AUDIO_STREAM_CONFIG_CAPS | 지원 되는 가능한 오디오 포맷 모두에 관한 정보가 저장 된다.
COLORKEY | 렌더러와 다른 필터와의 사이에 칼라 키 정보를 교환한다.
MPEG1VIDEOINFO | MPEG-1 비디오의 추가 시스템 정보가 저장 된다.
MPEG2VIDEOINFO | MPEG-2 비디오의 추가 시스템 정보가 저장 된다.
TIMECODE | 기본적인 타임 코드 프레임 카운트 정보가 저장 된다.
TIMECODE_SAMPLE | 타임 코드의 완전한 정보가 저장 된다.
VIDEO_STREAM_CONFIG_CAPS | 가능한 접속에 관한 정보가 저장 된다.
VIDEOINFO | 비디오 이미지와 그 칼라 팔레트 및 비트 마스크를 지정하는 정보가 저장 된다.
VIDEOINFOHEADER | 비디오 이미지의 비트 맵과 색정보를 기술한다.
VIDEOINFOHEADER2 | 인터레이스, 카피 보호, 및 픽셀의 어스펙트비(가로세로 비율) 정보를 포함한, 비디오 이미지의 비트 맵과 색정보를 기술한다.


ALLOCATOR_PROPERTIES 구조체

구조체

allocater의 프로퍼티 (카운트, 사이즈, alignment, 및 프레픽스)의 기술.

구문

typedef struct _AllocatorProperties {
    long cBuffers;
    long cbBuffer;
    long cbAlign;
    long cbPrefix;
} ALLOCATOR_PROPERTIES;

멤버

cBuffers
이 allocater의 버퍼수.
cbBuffer
프레픽스를 제외한 각 버퍼의 사이즈 (바이트 단위).
cbAlign
버퍼의 alignment. 버퍼는 이 값의 배수로부터 시작된다.
cbPrefix
각 버퍼의 선두에 있는 프레픽스의 바이트수.

주의

IMediaSample::GetPointer 멤버 함수는 버퍼의 선두 포인터를 돌려주지만,cbPrefix 가 설정한 프레픽스의 바이트수는 포함하지 않는다.

alignment는 프레픽스데이타에 적용된다 (있는 경우). 프레픽스의 사이즈가 0 이 아닌 경우, 프레픽스의 선두는 cbAlign 에 따라 alignment 된다.


AM_DVD_RENDERSTATUS 구조체

구조체

DVD 비디오 재생 상태를 나타내는 코드가 저장 된다. 이 코드는,IDvdGraphBuilder::RenderDvdVideoVolume 메소드로 사용된다.

구문

typedef struct {
    HRESULT hrVPEStatus;
    BOOL    bVPEFailed;
    BOOL    bDVDVolInvalid;
    BOOL    bDVDVolUnknown;
    BOOL    bNoLine21In;
    BOOL    bNoLine21Out;
    int     iNumStreams;
    int     iNumStreamsFailed;
    DWORD   dwFailedStreamsFlag;
} AM_DVD_RENDERSTATUS;

멤버

hrVPEStatus
오버레이/VPE 에러 코드. 0 은 성공을 나타내, 그 외의 값은 실패를 나타낸다.
bDVDVolInvalid
재생하도록(듯이) 지정된 DVD 볼륨이 존재하지 않는 경우는, TRUE. 그 이외의 경우는, FALSE.
bDVDVolUnknown
DVD 볼륨이 지정되어 있지 않은지, 또는 발견되지 않는 경우는, TRUE. 그 이외의 경우는, FALSE.
bNoLine21In
비디오 디코더가 Line 21 (자막 방송) 데이터를 생성하지 않는 경우는, TRUE. 그 이외의 경우는, FALSE.
bNoLine21Out
그래프 구축에 문제가 있어, 비디오상에 자막 방송으로서 비디오 디코더를 표시할 수 없는 경우는, TRUE. 그 이외의 경우는, FALSE.
iNumStreams
렌더링 하는 DVD 스트림의 수.
iNumStreamsFailed
렌더링에 실패한 스트림의 수.
dwFailedStreamsFlag
실패한 스트림을 나타내는 AM_DVD_STREAM_FLAGS 플래그의 편성.

참조

IDvdGraphBuilder::RenderDvdVideoVolume


AM_MEDIA_TYPE 구조체

구조체

미디어 샘플의 포맷을 기술.

AM_MEDIA_TYPE 구조체와의 공동 동작에 대해서는, 「미디어 타입 함수」를 참조할것.

구문

typedef struct  _MediaType
{
    GUID      majortype;
    GUID      subtype;
    BOOL      bFixedSizeSamples;
    BOOL      bTemporalCompression;
    ULONG     lSampleSize;
    GUID      formattype;
    IUnknown  *pUnk;
    ULONG     cbFormat;
    /* [size_is] */ BYTE __RPC_FAR *pbFormat;
} AM_MEDIA_TYPE;

멤버

majortype
미디어 샘플의 메이저 타입을 지정하는 글로벌 유니크 식별자 (GUID).
subtype
미디어 샘플의 서브 타입을 지정하는 GUID. 상세한 것에 대하여는, 「미디어 타입」을 참조할것.
bFixedSizeSamples
TRUE 의 경우, 샘플의 사이즈는 고정이다. 이 필드는 참조 전용이다. 보통, 오디오에서는 TRUE 로 설정된다. 비디오에서는, 보통, 압축되어 있지 않으면 TRUE, 압축되고 있으면 FALSE 로 설정된다.
bTemporalCompression
TRUE 의 경우, 샘플은 시계열 (프레임간) 압축 방식에서 압축되고 있다. 값 TRUE 는 프레임이 모두 키 프레임이라고는 할 수 없는 것을 나타낸다. 이 필드는 참조 전용이다.
lSampleSize
샘플의 사이즈 (바이트 단위). 압축 데이터에서는 0 의 경우가 있다.
formattype
포맷 타입을 지정하는 GUID. pbFormat 멤버는 대응하는 포맷 구조체를 가리킨다. 포맷 타입에는 다음의 것이 있다 :
포맷 타입 | 포맷 구조체
FORMAT_None | 포맷 타입 없음
FORMAT_MPEGVideo | MPEG1VIDEOINFO
FORMAT_MPEG2Video | MPEG2VIDEOINFO
FORMAT_VideoInfo | VIDEOINFOHEADER
FORMAT_VideoInfo2 | VIDEOINFOHEADER2
FORMAT_WaveFormatEx | WAVEFORMATEX
pUnk
미사용.
cbFormat
미디어 타입의 포맷 블록의 사이즈.
pbFormat
포맷 구조체에의 포인터. 구조체의 종류는 formattype 멤버로 지정된다. formattype 가 GUID_NULL 또는 FORMAT_None 가 아닌 한, 포맷 구조체가 존재해야 한다.

주의

필터가 접속했을 때, 보통 필터는 미디어 타입을 네고시에이션 한다. 미디어 타입은 필터가 교환하는 데이터의 포맷을 기술한다. 필터가 미디어 타입을 받아들이지 않으면, 접속은 할 수 없다. Microsoft® DirectShow® 는 AM_MEDIA_TYPE 구조체로 미디어 타입을 기술한다.

미디어 타입의 최초의 파트에는 데이터 스트림의 일반 속성이 들어가 있다. 예를 들어,bFixedSizeSamples 멤버는 데이터가 고정 사이즈의 버퍼로 건네받을지 어떨지를 선언한다. 2 번째의 파트는 포맷 블록으로 불리는 포맷 고유의 헤더가 들어가는 가변장 블록의 데이터이다. pbFormat 멤버는 이 블록에의 포인터이다. 포맷 블록의 레이아웃은 스트림내의 데이터 타입에 의존한다. 예를 들어, 데이터 스트림에 비디오 프레임이 들어가 있다면, 그 포맷 블록은 VIDEOINFOHEADER 구조체이다.

스트림 타입은 메이저 타입과 서브 타입으로 불리는 2 개의 GUID 에 의해 지정된다. 메이저 타입은 비디오, 오디오, 혹은 바이트 스트림의 같은 일반적인 카테고리를 정의한다. 서브 타입은 메이저 타입 내부의 것보다 세세한 카테고리를 정의한다. 예를 들어, 8-bit, 16-bit, 24-bit, 그리고 32-bit RGB 를 포함한 비디오 서브 타입.

어느 경우에는, 서브 타입은 (비트 깊이와 같이) 포맷으로 지정된 정보를 카피한다. 그러나 포맷 타입에 GUID_NULL 를 지정 하면 도움이 되는 경우도 있다. 완전한 포맷을 주는 일 없이, 서브 타입에 의해 있는 포맷 정보를 지정할 수가 있다. 예를 들어, 비디오 프레임의 개개의 폭이나 높이를 주는 일 없이, 24 비트 RGB 를 지정할 수가 있다.


AM_SAMPLE2_PROPERTIES 구조체

구조체

범용 미디어 샘플의 프로퍼티를 기술한다. IMediaSample2 인터페이스는 이 구조체를 사용한다.

구문

typedef struct tagAM_SAMPLE2_PROPERTIES
{
    DWORD    cbData;
    DWORD    dwTypeSpecificFlags;
    DWORD    dwSampleFlags;
    LONG     lActual;
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    DWORD    dwStreamId;
    AM_MEDIA_TYPE *pMediaType;
    BYTE    *pbBuffer;
    LONG     cbBuffer;
} AM_SAMPLE2_PROPERTIES;

멤버

cbData
프로퍼티 데이터의 길이 (바이트 단위). 이 구조체 멤버는 확장용이다.
dwTypeSpecificFlags
타입 고유의 플래그 데이터. 플래그는 미디어 타입 마다 정의된다. 디폴트는 0.
dwSampleFlags
데이터 타입을 열거하는 AM_SAMPLE_PROPERTY_FLAGS 플래그의 비트 편성. 미정도리의 비트는 예약되고 있어 제로가 아니면 안된다.
lActual
버퍼내의 유효한 데이터의 길이.
tStart
유효하면, 시작 타임. dwSampleFlags 멤버는 이 멤버가 유효한가 어떤가를 나타낸다.
tStop
유효하면, 종료 타임. dwSampleFlags 멤버는 이 멤버가 유효한가 어떤가를 나타낸다.
dwStreamId
스트림 식별자. 이 값이 AM_STREAM_MEDIA 라면, 스트림에는 미디어 데이터가 들어간다. 이 값이 AM_STREAM_CONTROL 라면, 스트림에는 컨트롤 정보가 들어간다. 어플리케이션은 0x80000000 이상의 값을 어플리케이션 자신의 용도에 사용할 수 있다.
pMediaType
미디어 타입을 나타내는 AM_MEDIA_TYPE 구조체에의 포인터.
pbBuffer
버퍼에의 포인터. 이 프로퍼티는 읽어들여 전용이다.
cbBuffer
버퍼의 사이즈 (바이트 단위). 이 프로퍼티는 읽어들여 전용이다.


AM_STREAM_INFO 구조체

구조체

핀에게 건네진 시작 및 정지의 정보가 들어간다.

구문

typedef struct {
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    DWORD dwStartCookie;
    DWORD dwStopCookie;
    DWORD dwFlags;
} AM_STREAM_INFO;

멤버

tStart
스트리밍의 시작 타임.
tStop
스트리밍의 종료 타임.
dwStartCookie
시작을 지시한 어플리케이션에 이벤트 발생시에게 건네지는 번호.
dwStopCookie
정지를 지시한 어플리케이션에 이벤트 발생시에게 건네지는 번호.
dwFlags
AM_STREAM_INFO_FLAGS 열거형의 플래그.

주의

이 구조체는,IAMStreamControl 인터페이스를 통해서 액세스 한다.


AMOVIESETUP_FILTER 구조체

구조체

필터를 등록하기 위한 정보가 들어간다.

구문

typedef struct _AMOVIESETUP_FILTER
{
    const CLSID           *clsID;
    const WCHAR           *strName;
    DWORD                 dwMerit;
    UINT                  nPins;
    const AMOVIESETUP_PIN *lpPin;
} AMOVIESETUP_FILTER, * PAMOVIESETUP_FILTER, * FAR LPAMOVIESETUP_FILTER;

멤버

clsID
필터의 클래스 식별자.
strName
필터의 이름.
dwMerit
필터의메리트 . IGraphBuilder 인터페이스가 필터 그래프의 구축시에 사용한다.
nPins
필터의 핀의 수.
lpPin
AMOVIESETUP_PIN 구조체의 배열에의 포인터. 배열의 사이즈는 nPins.


AMOVIESETUP_MEDIATYPE 구조체

「REGPINTYPES 」를 참조할것.


AMOVIESETUP_PIN 구조체

「REGFILTERPINS 」를 참조할것.


AMVABeginFrameInfo 구조체

구조체

프레임의 처리를 시작 하기 위해서 필요한 정보를 지정한다.

주 : 이 구조체는, Microsoft® Windows® 98 Second Edition 및 Windows 2000 으로 이용 가능하다.

구문

typedef struct _tag_AMVABeginFrameInfo{
    DWORD dwDestSurfaceIndex;
    LPVOID pInputData;
    DWORD dwSizeInputData;
    LPVOID pOutputData;
    DWORD dwSizeOutputData;
 } AMVABeginFrameInfo, *LPAMVABeginFrameInfo;

멤버

dwDestSurfaceIndex
이 프레임을 디코드하는 전송처 버퍼.
pInputData
그 외의 데이터에의 포인터.
dwSizeInputData
프레임 처리를 시작하기 위한 그 외의 데이터 사이즈.
pOutputData
VGA (Video Graphics Array)에 의해 설정되는 데이터에의 포인터.
dwSizeOutputData
VGA 에 의해 설정되는 데이터의 사이즈.

주의

pInputData 에는 포인터를 저장 할 수 없기 때문에 주의 해야 한다. 이것은, 프레임의 처리를 하는 커넬 모드에서는, 그 주소가 유효하지 않기 때문이다.


AMVABUFFERINFO 구조체

구조체

버퍼 정보를 기술한다.

주 : 이 구조체는, Microsoft® Windows® 98 Second Edition 및 Windows 2000 으로 이용 가능하다.

구문

typedef struct _tag_AMVABUFFERINFO{
    DWORD dwTypeIndex;
    DWORD dwBufferIndex;
    DWORD dwDataOffset;
    DWORD dwDataSize;
 } AMVABUFFERINFO, *LPAMVABUFFERINFO;

멤버

dwTypeIndex
버퍼의 종류.
dwBufferIndex
버퍼의 인덱스.
dwDataOffset
관련 데이터의 버퍼 선두로부터의 오프셋(offset).
dwDataSize
관련 데이터의 사이즈.


AMVACompBufferInfo 구조체

구조체

할당할 수 있었던 표면 및 압축 버퍼의 정보를 기술한다.

주 : 이 구조체는, Microsoft® Windows® 98 Second Edition 및 Windows 2000 으로 이용 가능하다.

구문

typedef struct _tag_AMVACompBufferInfo{
    DWORD dwNumCompBuffers;
    DWORD dwWidthToCreate;
    DWORD dwHeightToCreate;
    DWORD dwBytesToAllocate;
    DDSCAPS2 ddCompCaps;
    DDPIXELFORMAT ddPixelFormat;
 } AMVACompBufferInfo, *LPAMVACompBufferInfo;

멤버

dwNumCompBuffers
압축 데이터용으로 요구된 버퍼의 수.
dwWidthToCreate
생성 하는 표면의 폭.
dwHeightToCreate
생성 하는 표면의 높이.
dwBytesToAllocate
각 표면으로 사용되는 토탈의 바이트수.
ddCompCaps
압축 데이터를 저장 하기 위해서 생성 된 DirectDrawSurface 오브젝트의 능력을 정의하는 DDSCAPS2 구조체.
ddPixelFormat
압축 데이터를 저장 하는 표면의 생성에 사용된 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체.


AMVAEndFrameInfo 구조체

구조체

프레임의 처리를 종료하기 위한 정보를 지정한다.

주 : 이 구조체는, Microsoft® Windows® 98 Second Edition 및 Windows 2000 으로 이용 가능하다.

구문

typedef struct _tag_AMVAEndFrameInfo{
    DWORD dwSizeMiscData;
    LPVOID pMiscData;
 } AMVAEndFrameInfo, *LPAMVAEndFrameInfo;

멤버

dwSizeMiscData
프레임을 시작하기 위한 그 외의 데이터 사이즈.
pMiscData
그 외의 데이터에의 포인터.

주의

pMiscData 에는 포인터를 저장 할 수 없기 때문에 주의 해야 한다.


AMVAInternalMemInfo 구조체

구조체

하드웨어 추상 계층 (HAL)이 내부에서 사용하기 위해서 할당하는 scratch memory의 양을 지정한다.

주 : 이 구조체는, Microsoft® Windows® 98 Second Edition 및 Windows 2000 으로 이용 가능하다.

구문

typedef struct _tag_AMVAInternalMemInfo{
    DWORD dwScratchMemAlloc;
 } AMVAInternalMemInfo, *LPAMVAInternalMemInfo;

멤버

dwScratchMemAlloc
HAL 가 내부에서 사용하기 위해서 할당하는 scratch memory의 양을 지정한다.


AMVAUncompBufferInfo 구조체

구조체

할당하는 표면을 기술한다.

주 : 이 구조체는, Microsoft® Windows® 98 Second Edition 및 Windows 2000 으로 이용 가능하다.

구문

typedef struct _tag_AMVAUncompBufferInfo{
    DWORD dwMinNumSurfaces;
    DWORD dwMaxNumSurfaces;
    DDPIXELFORMAT ddUncompPixelFormat;
 } AMVAUncompBufferInfo, *LPAMVAUncompBufferInfo;

멤버

dwMinNumSurfaces
할당하는 표면의 최소수.
dwMaxNumSurfaces
할당하는 표면의 최대수.
ddUncompPixelFormat
할당하는 표면의 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체.


AMVAUncompDataInfo 구조체

구조체

데이터 입력 스트림의 픽셀 포맷 및 넓이 특성을 지정한다.

주 : 이 구조체는, Microsoft® Windows® 98 Second Edition 및 Windows 2000 으로 이용 가능하다.

구문

typedef struct _tag_AMVAUncompDataInfo{
    DWORD dwUncompWidth;
    DWORD dwUncompHeight;
    DDPIXELFORMAT ddUncompPixelFormat;
 } AMVAUncompDataInfo, *LPAMVAUncompDataInfo;

멤버

dwUncompWidth
비압축 데이터의 폭.
dwUncompHeight
비압축 데이터의 높이.
ddUncompPixelFormat
비압축 데이터의 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체.


AMVPDATAINFO 구조체

구조체

VP 입력 스트림에 관한 데이터 고유의 특성을 지정한다.

구문

typedef struct _AMVPDATAINFO{
    DWORD dwSize;
    DWORD dwMicrosecondsPerField;
    AMVPDIMINFO amvpDimInfo;
    DWORD dwPictAspectRatioX;
    DWORD dwPictAspectRatioY;
    BOOL bEnableDoubleClock;
    BOOL bEnableVACT;
    BOOL bDataIsInterlaced;
    LONG lHalfLinesOdd;
    BOOL bFieldPolarityInverted;
    DWORD dwNumLinesInVREF;
    LONG lHalfLinesEven;
    DWORD dwReserved1;
} AMVPDATAINFO, *LPAMVPDATAINFO;

멤버

dwSize
구조체의 사이즈 (바이트 단위).
dwMicrosecondsPerField
각 필드의 소요 시간.
amvpDimInfo
넓이 정보.
dwPictAspectRatioX
화면 어스펙트비(가로세로 비율)의 x 넓이.
dwPictAspectRatioY
화면 어스펙트비(가로세로 비율)의 y 넓이.
bEnableDoubleClock
비디오 포토는 더블 클록킹을 유효하게 할 필요가 있다.
bEnableVACT
비디오 포토는 외부 VACT 신호를 사용할 필요가 있다.
bDataIsInterlaced
인터레이스 신호인 것을 나타낸다.
lHalfLinesOdd
홀수 필드의 하프 라인수.
bFieldPolarityInverted
비디오 포토는 필드극성을 반전할 필요가 있다.
dwNumLinesInVREF
VREF 의 데이터의 라인수.
lHalfLinesEven
짝수 필드의 하프 라인수.
dwReserved1
장래적인 사용을 위해서(때문에) 예약되고 있다.


AMVPDIMINFO 구조체

구조체

VP 입력 스트림에 관한 넓이 특성을 지정한다.

구문

typedef struct _AMVPDIMINFO{
    DWORD dwFieldWidth;
    DWORD dwFieldHeight;
    DWORD dwVBIWidth;
    DWORD dwVBIHeight;
    RECT rcValidRegion;
} AMVPDIMINFO, *LPAMVPDIMINFO;

멤버

dwFieldWidth
데이터의 필드의 폭.
dwFieldHeight
데이터의 필드의 높이.
dwVBIWidth
VBI 데이터의 폭.
dwVBIHeight
VBI 데이터의 높이.
rcValidRegion
크로핑에 사용하는 유효한 직사각형.


AMVPSIZE 구조체

구조체

VP 이미지의 폭과 높이를 지정한다.

구문

typedef struct _AMVPSIZE{
DWORD dwWidth;
DWORD dwHeight;
} AMVPSIZE, *LPAMVPSIZE;

멤버

dwWidth
폭 (픽셀 단위).
dwHeight
높이.

주의

문맥은 한정되지 않는다 (스케일링, 크로핑 등).


ANALOGVIDEOINFO 구조체

구조체

아날로그 비디오 신호의 포맷에 관한 정보를 보관 유지한다.

구문

typedef struct tagAnalogVideoInfo {
    RECT            rcSource;
    RECT            rcTarget;
    DWORD           dwActiveWidth;
    DWORD           dwActiveHeight;
    REFERENCE_TIME  AvgTimePerFrame;
} ANALOGVIDEOINFO;

멤버

rcSource
소스 비디오의 직사각형.
rcTarget
전송처의 타겟 직사각형.
dwActiveWidth
소스 비디오의 폭.
dwActiveHeight
소스 비디오의 높이 (NTSC 에서는 483,PAL 및 SECAM 에서는 575).
AvgTimePerFrame
프레임의 평균 시간 (100 나노초단위).

주의

보통, 이 포맷을 사용하는 필터는, 메모리 베이스의 전송은 아니고 하드웨어 베이스의 접속에 의해 비디오 신호를 건네준다.

미디어 타입이 아날로그 비디오의 접속이 정의되는 예로서는, "M" 색의 encode를 사용해 NTSC 비디오를 접속하는 경우를 들 수 있다. 이 경우, 메이저 타입, 서브 타입, 및 포맷 타입에, 각각 MEDIATYPE_AnalogVideo, MEDIASUBTYPE_AnalogVideo_NTSC_M, FORMAT_AnalogVideo 가 사용된다.


AUDIO_STREAM_CONFIG_CAPS 구조체

구조체

지원 되는 가능한 오디오 포맷 모두에 관한 정보가 저장 된다.

구문

typedef struct _AUDIO_STREAM_CONFIG_CAPS {
        GUID guid;
        ULONG MinimumChannels;
        ULONG MaximumChannels;
        ULONG ChannelsGranularity;
        ULONG MinimumBitsPerSample;
        ULONG MaximumBitsPerSample;
        ULONG BitsPerSampleGranularity;
        ULONG MinimumSampleFrequency;
        ULONG MaximumSampleFrequency;
        ULONG SampleFrequencyGranularity;
    } AUDIO_STREAM_CONFIG_CAPS;

멤버

guid
오디오 샘플을 나타내는 MEDIATYPE_Audio 로 설정된다.
MinimumChannels
이 핀이 지원 하는 최소 채널수.
MaximumChannels
이 핀이 지원 하는 최대 채널수 (예를 들어 스테레오라면 2).
ChannelsGranularity
채널수의 세분도. 예를 들어, 2 ~ 4 채널을 2 채널 간격으로 지정한다.
MinimumBitsPerSample
샘플 근처의 최소 비트수.
MaximumBitsPerSample
샘플 근처의 최대 비트수.
BitsPerSampleGranularity
비트수의 세분도. 예를 들어, 8 ~ 32 비트를 8 비트 간격으로 지정한다.
MinimumSampleFrequency
사용할 수 있는 최소의 주파수.
MaximumSampleFrequency
사용할 수 있는 최대의 주파수.
SampleFrequencyGranularity
주파수의 세분도. 예를 들어, 11025 ~ 44100 Hz 를 11025 Hz 간격으로 지정한다.

주의

이 구조체는, 오디오 캡춰 필터 또는압축 필터로부터 돌려주어진다.

참조

IAMStreamConfig::GetStreamCaps


COLORKEY 구조체

구조체

렌더러와 다른 필터와의 사이에 칼라 키 정보를 교환한다.

구문

typedef struct tagCOLORKEY
    {
    DWORD           KeyType;
    DWORD           PaletteIndex;
    COLORREF        LowColorValue;
    COLORREF        HighColorValue;
    }    COLORKEY;

멤버

KeyType
키의 종류. CK_NOCOLORKEY ,CK_INDEX , 또는 CK_RGB . CK_INDEX 와 CK_RGB 는, 논리적으로 조합할 수가 있다.
PaletteIndex
팔레트 인덱스.
LowColorValue
RGB 칼라값의 하한.
HighColorValue
RGB 칼라값의 상한.

주의

비디오 렌더러는,IOverlay 인터페이스를 통해서 액세스 되는 데이터 전송을 지원 한다. 이 인터페이스는, 보통, 렌더러에 데이터의 드로잉(Drawing)를 요구하지 않고 , 데이터를 두는 위치를 렌더러로부터 알 필요가 있는 하드웨어 디코더 필터로 사용된다. 이미지를 두는 위치를 알기 위한 1 개의 메카니즘이, 칼라 키를 사용하는 방법이다. 이 구조체는, 칼라 키의 요건을 비디오 렌더러에 설명하기 위해서, 필터 (주로 하드웨어 디코더)로부터 사용된다.


DIBDATA 구조체

구조체

개개의 GDI DIB 에 관한 정보를 보관 유지한다.

구문

typedef struct tagDIBDATA {
    LONG        PaletteVersion;
    DIBSECTION  DibSection;
    HBITMAP     hBitmap;
    HANDLE      hMapping;
    BYTE        *pBase;
} DIBDATA;

멤버

PaletteVersion
현재 사용중의 팔레트 버젼.
DibSection
할당할 수 있었던 DIB 섹션의 상세.
hBitmap
드로잉(Drawing) 하는 비트 맵의 핸들.
hMapping
공유 메모리 블록의 핸들.
pBase
베이스 메모리 주소에의 포인터.

주의

샘플을 생성 하면 와, allocater는 샘플에 DIBSECTION 를 할당한다. 윈도우가 샘플을 받으면(자), 윈도우는, Microsoft Win32® BitBlt 함수를 호출해, 1 개의 디바이스 콘텍스트로부터 다른 디바이스 콘텍스트에, 샘플을 건네줄 수가 있다. 이것은, 이미지 allocater, 이미지 샘플, 및 드로잉(Drawing) 클래스가 서로 비트 맵 정보를 교환하는 메카니즘이다.


DVD_ATR 구조체

구조체

디스크로부터 얻을 수 있는 DVD 의 각종 속성을 기술한다. 이 정보를 해석하려면 , DVD 비디오의 사양을 참조할것.

구문

typedef struct tagDVD_ATR
{
    ULONG    ulCAT;
    BYTE    pbATRI[768];
} DVD_ATR;

멤버

ulCAT
1 볼륨의 경우는 VMG_CAT, 비디오 타이틀 세트 (VTS)의 경우는 VTS_CAT.
pbATRI
비디오 매니저 정보 (VMGI) 또는 비디오 타이틀 세트 정보 (VTSI)의 바이트 256 ~ 1023 으로부터 얻을 수 있는 메뉴 및 타이틀의 전스트림 속성.

주의

이 구조체는 IDVDInfo 인터페이스 (비추천)와 함께 사용한다. 새로운 어플리케이션에서는,IDVDInfo2 인터페이스를 사용해야 하는 것이다.


DVD_DECODER_CAPS 구조체

구조체

DVD 디코더의 능력을 나타낸다. IDvdInfo2::GetDecoderCaps 내에서 사용된다.

구문

typedef struct tagDVD_DECODER_CAPS
{
    DWORD   dwSize ;
    DWORD   dwAudioCaps ;
    double  dFwdMaxRateVideo ;
    double  dFwdMaxRateAudio ;
    double  dFwdMaxRateSP ;
    double  dBwdMaxRateVideo ;
    double  dBwdMaxRateAudio ;
    double  dBwdMaxRateSP ;
    DWORD   dwRes1 ;
    DWORD   dwRes2 ;
    DWORD   dwRes3 ;
    DWORD   dwRes4 ;
} DVD_DECODER_CAPS ;

멤버

dwSize
구조체의 사이즈.
dwAudioCaps
지원 되는 오디오 포맷을 나타낸다. 이하의 값의 비트마다의 OR.
  • DVD_AUDIO_CAPS_AC3 = 0x00000001
  • DVD_AUDIO_CAPS_MPEG2 = 0x00000002
  • DVD_AUDIO_CAPS_LPCM = 0x00000004
  • DVD_AUDIO_CAPS_DTS = 0x00000008
  • DVD_AUDIO_CAPS_SDDS = 0x00000010
dFwdMaxRateVideo
순서 방향의 최대 비디오 데이터 레이트.
dFwdMaxRateAudio
순서 방향의 최대 오디오 데이터 레이트.
dFwdMaxRateSP
순서 방향의 최대 서브 픽쳐 데이터 레이트.
dBwdMaxRateVideo
역방향의 최대 비디오 데이터 레이트 (디코더가 스무드 반전 메카니즘을 지원 하고 있지 않는 경우는 0).
dBwdMaxRateAudio
역방향의 최대 오디오 데이터 레이트 (디코더가 스무드 반전 메카니즘을 지원 하고 있지 않는 경우는 0).
dBwdMaxRateSP
역방향의 최대 서브 픽쳐 데이터 레이트 (디코더가 스무드 반전 메카니즘을 지원 하고 있지 않는 경우는 0).
dwRes1
장래적인 사용을 위해서(때문에) 예약되고 있다.
dwRes2
장래적인 사용을 위해서(때문에) 예약되고 있다.
dwRes3
장래적인 사용을 위해서(때문에) 예약되고 있다.
dwRes4
장래적인 사용을 위해서(때문에) 예약되고 있다.


DVD_HMSF_TIMECODE 구조체

구조체

시, 분, 초, 및 프레임을 DVD 타임 코드에 캡슐화한다.

구문

typedef struct tagDVD_HMSF_TIMECODE
{
    BYTE    bHours;
    BYTE    bMinutes;
    BYTE    bSeconds;
    BYTE    bFrames;
} DVD_HMSF_TIMECODE;

멤버

bHours
시.
bMinutes
분.
bSeconds
초.
bFrames
프레임.

주의

DVD_HMSF_TIMECODE 구조체는,IDvdControl2 및 IDvdInfo2 와 함께 사용한다. 낡은 인터페이스 IDvdControl 및 IDvdInfo 와 함께 사용되고 있던 DVD_TIMECODE 구조체보다 사용하기 쉽게 되어 있다. DVD_HMSF_TIMECODE 구조체와 ULONG 와는 어느 쪽 방향에도 캐스트 할 수 있다. 이것은, 후방 호환성을 유지하기 위해서(때문에) 낡은 BCD 타임 포맷을 사용필요가 있는 경우에,DVD_HMSF_TIMECODE 구조체 대신에 사용할 수 있는 것을 의미한다.


DVD_KaraokeAttributes 구조체

구조체

가라오케 오디오 스트림에 관한 정보가 저장 된다. 특정의 스트림의 DVD_KaraokeAttributes 구조체는,IDvdInfo2::GetKaraokeAttributes 메소드로 설정한다.

구문

typedef struct tagDVD_KaraokeAttributes
{
    BYTE            bVersion;
    BOOL            fMasterOfCeremoniesInGuideVocal1;
    BOOL            fDuet;
    DVD_KARAOKE_ASSIGNMENT  ChannelAssignment;
    WORD            wChannelContents[8];
} DVD_KaraokeAttributes;

멤버

bVersion
가라오케의 현재의 버젼은 1.0 이다.
fMasterOfCeremoniesInGuideVocal1
TRUE 는 "가이드 음성 1" 채널에 "사회 " 의 컨텐츠가 저장 되고 있는 것을 의미한다.
fDuet
듀엣곡인가 어떤가를 나타내는 불리언 값.
ChannelAssignment
전채널의 믹싱 출력처가 되는 스피커의 구성을 나타낸다. 유효한 DVD_KARAOKE_ASSIGNMENT 값의 비트마다의 OR.
wChannelContents
각 채널의 컨텐츠를 식별하는 유효한 DVD_KARAOKE_CONTENTS 값의 배열.


DVD_MenuAttributes 구조체

구조체

DVD 메뉴에 관한 정보가 저장 된다. 특정의 스트림의 DVD_MenuAttributes 구조체는,IDvdInfo2::GetTitleAttributes 메소드로 설정한다.

구문

typedef struct tagDVD_MenuAttributes
{

    BOOL                        fCompatibleRegion[8];
    DVD_VideoAttributes         VideoAttributes;

    BOOL                        fAudioPresent;
    DVD_AudioAttributes         AudioAttributes;

    BOOL                        fSubpicturePresent;
    DVD_SubpictureAttributes    SubpictureAttributes;
} DVD_MenuAttributes;

멤버

fCompatibleRegion
디스크가 생성 된 지역과 호환성이 있는 DVD 리젼을 나타내는 TRUE/FALSE 값의 배열. 배열의 8 개의 인덱스 (0 ~ 7) 각각이, 8 개의 DVD 의 지역 (1 ~ 8)에 대응한다. 이 배열은, Video Manager Menu (디스크 전체의 메인 메뉴)에 대해 조회했을 경우에게만 설정된다.
VideoAttributes
메뉴의 비디오 속성이 저장 된 DVD_VideoAttributes 구조체. 이 구조체는 VMGM 와 VTSM 의 양쪽 모두에 적용된다.
fAudioPresent
메뉴에 오디오 스트림이 있을지 어떨지를 나타내는 불형의 변수.
AudioAttributes
메뉴의 오디오 스트림에 관한 정보가 저장 된 DVD_AudioAttributes 구조체. 이 구조체는 fAudioPresent 가 TRUE 의 경우에게만 설정된다.
fSubpicturePresent
메뉴에 서브 픽쳐 스트림이 있을지 어떨지를 나타내는 불형의 변수.
SubpictureAttributes
메뉴의 서브 픽쳐 스트림에 관한 정보가 저장 된 DVD_SubpictureAttributes 구조체. 이 구조체는 fSubpicturePresent 가 TRUE 의 경우에게만 설정된다.


DVD_MUA_Coeff 구조체

구조체

멀티 채널의 오디오 스트림에 포함되는 1 개의 채널의 믹싱 계수를 정의한다. DVD_MultichannelAudioAttributes 구조체에는, 스트림의 각 채널에 대응하는 DVD_MUA_Coeff 구조체 8 개(살)로부터 완성되는 배열이 저장 된다.

구문

typedef struct tagDVD_MUA_Coeff
{
    double   log2_alpha;
    double   log2_beta;
} DVD_MUA_Coeff;

멤버

log2_alpha
이 채널의 채널 0 에 대한 믹싱 계수를 나타내는 double 형의 변수.
log2_beta
이 채널의 채널 1 에 대한 믹싱 계수를 나타내는 double 형의 변수.

주의

이 구조체에 저장 되는 정보에는, 디지털 비디오 디스크 (DVD)에 명기된 믹싱 계수가 반영된다. 오디오의 디코드도 어플리케이션측에서 실시하는 경우를 제외해, 이 계수를 어플리케이션으로부터 변경하거나 반대로 사용하거나 할 수 없다. 일반적인 DVD 필터 그래프에서는,DVD 네비게이터 필터로부터 디코더에 이 정보를 보낼 것은 없다.

alpha 계수는 오디오 채널 0 에의 믹싱에 사용되어 beta 계수는 오디오 채널 1 에의 믹싱에 사용된다. 보통, 믹싱 계수는 다음의 식에서 계산된다.

Audio channel 0 = coeff[0]. alpha * value[0] + coeff[1]. alpha * value[1] + ...
Audio channel 1 = coeff[0]. beta * value[0]  + coeff[1]. beta * value[1] + ...

참조

DVD_AudioAttributes ,DVD_MUA_MixingInfo


DVD_MUA_MixingInfo 구조체

구조체

특정 타이틀의 1 개의 오디오 스트림에 포함되는 채널의 환경 사운드의 믹싱 정보를 기술한다.

구문

typedef struct tagDVD_MUA_MixingInfo
{
    BOOL    fMixTo0;
    BOOL    fMixTo1;
    BOOL    fMix0InPhase;
    BOOL    fMix1InPhase;
    DWORD   dwSpeakerPosition;
} DVD_MUA_MixingInfo;

멤버

fMixTo0
불형의 변수. TRUE 는 채널이 채널 0 에 믹싱 되는 것을 의미한다.
fMixTo1
불형의 변수. TRUE 는 채널이 채널 1 에 믹싱 되는 것을 의미한다.
fMix0InPhase
불형의 변수. TRUE 는 채널이 채널 0 에 동기 해 믹싱 되는 것을 의미한다.
fMix1InPhase
불형의 변수. TRUE 는 채널이 채널 1 에 동기 해 믹싱 되는 것을 의미한다.
dwSpeakerPosition
이 채널의 출력처 스피커를 나타내는 DWORD 형의 변수. 「주의」를 참조할것.

주의

필터 그래프에 수동으로 삽입된 커스텀인 오디오 디코더와 통신하는 수단을 가지고 있지 않는 이상 이 구조체에 저장 된 정보를 어플리케이션으로부터 사용해 믹싱을 변경할 수 없다. 디폴트의 오디오 디코더는, 믹싱 정보를 사용해, 디지털 비디오 디스크 (DVD)의 LPCM (Linear Pulse Code Modulated) 오디오를 처리하지만, 어플리케이션에는 디코더에 믹싱값의 변경을 지시하는 수단이 없다. 이것은, 현재의 DVD 재생 어플리케이션에서는, 멀티 채널 관련 데이터의 구조체에 액세스 하지 않아도 좋은 일을 의미한다.

DVD_MultichannelAudioAttributes 구조체에는, 특정 타이틀의 1 개의 오디오 스트림에 관한 정보가 저장 된다. 이하의 조건이 채워지는 경우는, 이 구조체에 포함되는 8 개(살) 이내의 DVD_MUA_MixingInfo 구조체로부터 완성되는 배열에, 값이 설정된다.

  • DVD_AudioAttributes.AppMode = DVD_AudioMode_Surround
  • DVD_AudioAttributes.AudioFormat = DVD_AudioFormat_LPCM
  • DVD_AudioAttributes.fHasMultichannelInfo = 1

dwSpeakerPosition 로서 가능한 값은, Ksmedia.h 에 다음과 같이 정의되고 있다.

KSAUDIO_SPEAKER_LEFT | 0x1
KSAUDIO_SPEAKER_RIGHT | 0x2
KSAUDIO_SPEAKER_CENTER | 0x4
KSAUDIO_SPEAKER_SURROUND_LEFT | 0x8
KSAUDIO_SPEAKER_SURROUND_RIGHT | 0x10
KSAUDIO_SPEAKER_SUBWOOFER | 0x20
KSAUDIO_SPEAKER_LEFT_OF_CENTER | 0x40
KSAUDIO_SPEAKER_RIGHT_OF_CENTER | 0x80
KSAUDIO_SPEAKER_SURROUND_MONO | 0x100
KSAUDIO_SPEAKER_SIDE_LEFT | 0x200
KSAUDIO_SPEAKER_SIDE_RIGHT | 0x400
KSAUDIO_SPEAKER_TOP | 0x800

참조

DVD_AudioAttributes


DVD_MultichannelAudioAttributes 구조체

구조체

특정 타이틀에 포함되는 1 개의 오디오 스트림의 멀티 채널 속성을 기술한다.

구문

typedef struct tagDVD_MultichannelAudioAttributes
{
    DVD_MUA_MixingInfo  Info[8];
    DVD_MUA_Coeff       Coeff[8];
} DVD_MultichannelAudioAttributes;

멤버

Info
DVD_MUA_MixingInfo 구조체 8 개(살)로부터 완성되는 배열. 오디오 스트림의 각 채널의 믹싱 정보가 저장 된다.
Coeff
DVD_MUA_Coeff 구조체 8 개(살)로부터 완성되는 배열. 오디오 스트림의 각 채널의 믹싱 계수가 저장 된다.

주의

DVD_TitleAttributes 구조체에는,DVD_MultichannelAudioAttributes 구조체 8 개(살)까지로부터 완성되는 배열이 저장 된다. IDvdInfo2::GetTitleAttributes 메소드의 호출에 의해 DVD_TitleAttributes 가 설정되면(자), 타이틀내의 이용 가능한 오디오 스트림 각각 붙어 1 개의 DVD_MultichannelAudioAttributes 구조체가 배열로 설정된다.


DVD_PLAYBACK_LOCATION 구조체

구조체

DVD 의 재생 위치를 나타낸다.

구문

typedef struct tagDVD_PLAYBACK_LOCATION
{
ULONG   TitleNum;
    ULONG   ChapterNum;
    ULONG   TimeCode;
} DVD_PLAYBACK_LOCATION;

멤버

TitleNum
디스크 전체의 타이틀 번호. 타이틀 트럭 번호 (TTN)이며, 비디오 타이틀 세트의 타이틀 트럭 번호 (VTS_TTN)는 아니다.
ChapterNum
타이틀의 부분을 나타내는 번호. 단순하고 리니어인 무비가 아닌 경우는 0xffffffff.
TimeCode
타임 코드. 현재의 재생 시간에는 DVD_TIMECODE 를 사용한다. 단순 리니어인 무비가 아닌 경우는 0xffffffff.

주의

단순하고 리니어인 무비의 경우,TitleNum 와 ChapterNum 인가,TitleNum 와 TimeCode 조차 있으면, 재생 위치를 보존할 수 있다.


DVD_PLAYBACK_LOCATION2 구조체

구조체

DVD 의 재생 위치를 나타낸다.

구문

typedef struct tagDVD_PLAYBACK_LOCATION2
{
    ULONG   TitleNum;
    ULONG   ChapterNum;
    DVD_HMSF_TIMECODE   TimeCode;
    ULONG   TimeCodeFlags;
} DVD_PLAYBACK_LOCATION2;

멤버

TitleNum
디스크 전체의 타이틀 번호 (비디오 타이틀 세트의 트럭 번호는 아니다).
ChapterNum
타이틀의 부분을 나타내는 번호. 단순하고 리니어인 무비가 아닌 경우는 0xffffffff.
TimeCode
타임 코드. 현재의 재생 시간에는 DVD_HMSF_TIMECODE 를 사용한다. 단순하고 리니어인 무비가 아닌 경우는 0xffffffff.
TimeCodeFlags
DVD_TIMECODE_EVENT_FLAGS 의 편성.

주의

단순하고 리니어인 무비의 경우,TitleNum 와 ChapterNum 인가,TitleNum 와 TimeCode 조차 있으면, 재생 위치를 보존할 수 있다.


DVD_SubpictureAttributes 구조체

구조체

DVD 서브 픽쳐에 관한 정보가 저장 된다. 특정의 스트림의 DVD_SubpictureAttributes 구조체는,IDvdInfo2::GetSubpictureAttributes 메소드로 설정한다.

구문

typedef struct tagDVD_SubpictureAttributes
{
    DVD_SUBPICTURE_TYPE     Type;
    DVD_SUBPICTURE_CODING   CodingMode;
    LCID                    Language;
    DVD_SUBPICTURE_LANG_EXT LanguageExtension;
} DVD_SubpictureAttributes;

멤버

Type
서브 픽쳐에 언어 관련의 컨텐츠가 저장 되고 있는지 어떤지를 나타내는 DVD_SUBPICTURE_TYPE 형의 변수.
CodingMode
서브 픽쳐 그래픽스 스트림의 encode 방법을 나타내는 DVD_SUBPICTURE_CODING 형의 변수.
Language
Type 가 DVD_SPType_Language 의 경우에 서브 픽쳐 언어를 식별하는 LCID 형의 변수.
LanguageExtension
Type 가 DVD_SPType_Language 의 경우에 서브 픽쳐 언어 extension를 식별하는 DVD_SUBPICTURE_LANG_EXT 형의 변수.


DVD_TIMECODE 구조체

구조체

DVD 타임 코드 (시, 분, 초, 및 프레임)가 저장 된다.

구문

typedef struct tagDVD_TIMECODE")
{
   ULONG Hours1   :4;
   ULONG Hours10  :4;

   ULONG Minutes1 :4;
   ULONG Minutes10:4;

   ULONG Seconds1 :4;
   ULONG Seconds10:4;

   ULONG Frames1  :4;
   ULONG Frames10 :2;

   ULONG FrameRateCode:2;
} DVD_TIMECODE;

멤버

Hours1
때 (1 의 자리수).
Hours10
때 (10 의 자리수).
Minutes1
분 (1 의 자리수).
Minutes10
분 (10 의 자리수).
Seconds1
초 (1 의 자리수).
Seconds10
초 (10 의 자리수).
Frames1
프레임 (1 의 자리수).
Frames10
프레임 (10 의 자리수).
FrameRateCode
DVD_FRAMERATE 가 가리키는, 1 초 쯤의 드롭 되는 프레임수, 및 드롭 되지 않는 프레임수.

주의

DVD 타임 코드는, 0xHhMmSsFf 포맷의 BCD (Binary Coded Decimal) 코드이다.

  • H = 시 (10 의 자리수)
  • h = 시 (1 의 자리수)
  • M = 분 (10 의 자리수)
  • m = 분 (1 의 자리수)
  • S = 초 (10 의 자리수)
  • s = 초 (1 의 자리수)
  • F = 프레임 (10 의 자리수)
  • f = 프레임 (1 의 자리수)

BCD 를 사용하려면 , 우선 BCD 를 생성 한다.

ULONG timeCode = 0;	// BCD 를 생성 한다.
// DVD_TIMECODE 구조체에의 포인터를 생성 해, BCD 의 주소를 설정한다.
DVD_TIMECODE * dvdTimeCode = ( DVD_TIMECODE * ) &timeCode;

dvdTimeCode 는 DVD_TIMECODE 구조체로서 사용할 수 있다.

dvdTimeCode->Hours10 = 0;
dvdTimeCode->Hours1 = 2;

마지막으로, timeCode 를 IDvdControl::TimeSearch 메소드에 건네준다.

TimeSearch ( timeCode );


DVD_TitleAttributes 구조체

구조체

DVD 타이틀에 관한 정보가 저장 된다. 특정의 스트림의 DVD_TitleAttributes 구조체는,IDvdInfo2::GetTitleAttributes 메소드로 설정한다.

구문

typedef struct tagDVD_TitleMainAttributes
{

    DVD_TITLE_APPMODE                   AppMode;
    DVD_VideoAttributes                 VideoAttributes;
    ULONG                               ulNumberOfAudioStreams;
    DVD_AudioAttributes                 AudioAttributes[8];
    DVD_MultichannelAudioAttributes     MultichannelAudioAttributes[8];
    ULONG                               ulNumberOfSubpictureStreams;
    DVD_SubpictureAttributes            SubpictureAttributes[32];
} DVD_TitleAttributes;

멤버

AppMode
DVD 네비게이터가 "가라오케 " 모드인가 어떤가를 나타내는 DVD_TITLE_APPMODE 형의 변수.
VideoAttributes
현재의 메뉴 또는 타이틀의 "메인 " 비디오에 관한 정보가 저장 된 DVD_VideoAttributes 구조체.
ulNumberOfAudioStreams
타이틀의 이용 가능한 오디오 스트림수를 나타내는 ULONG 형의 변수.
AudioAttributes
현재의 타이틀에 포함되는 개개의 오디오 스트림에 관한 정보가 저장 된 DVD_AudioAttributes 구조체의 배열.
MultichannelAudioAttributes
멀티 채널 포맷의 이용 가능한 오디오 스트림에 관한 추가 정보가 저장 된 DVD_MultichannelAudioAttributes 구조체의 배열. 스트림의 DVD_AudioAttributes 구조체에 멀티 채널 비트가 세트 되고 있는 경우는, 대응하는 오디오 스트림의 내용이 이 구조체로 설정된다.
ulNumberOfSubpictureStreams
타이틀내의 이용 가능한 서브 픽쳐 스트림수를 나타내는 ULONG 형의 변수.
SubpictureAttributes
타이틀내의 각 서브 픽쳐 스트림에 관한 정보가 저장 된 DVD_SubpictureAttributes 구조체의 배열. DVD_SubpictureAttributes 구조체에는, 타이틀내의 이용 가능한 서브 픽쳐 스트림 각각 관한 정보가 저장 된다.


DVD_VideoAttributes 구조체

구조체

현재의 타이틀 또는 메뉴에 대응하는 비디오 스트림의 속성을 기술한다.

구문

typedef struct tagDVD_VideoAttributes
{
    BOOL                     fPanscanPermitted;
    BOOL                     fLetterboxPermitted;
    ULONG                    ulAspectX;
    ULONG                    ulAspectY;
    ULONG                    ulFrameRate;
    ULONG                    ulFrameHeight;
    DVD_VIDEO_COMPRESSION    Compression;
    BOOL                     fLine21Field1InGOP;
    BOOL                     fLine21Field2InGOP;
    ULONG                    ulSourceResolutionX;
    ULONG                    ulSourceResolutionY;
    BOOL                     fIsSourceLetterboxed;
    BOOL                     fIsFilmMode;
} DVD_VideoAttributes;

멤버

fPanscanPermitted
TRUE 는, 표시 어스펙트비(가로세로 비율)이 4 x 3 때에, 화면을빵-스캔 표시할 수 있는 것을 의미한다.
fLetterboxPermitted
TRUE 는, 표시 어스펙트비(가로세로 비율)이 4 x 3 때에, 화면을레터박스 표시할 수 있는 것을 의미한다.
ulAspectX
비디오 스트림의 x 어스펙트 (4 또는 16).
ulAspectY
비디오 스트림의 y 어스펙트 (3 또는 9).
ulFrameRate
frame rate (50 또는 60). 단위는 Hz.
ulFrameHeight
프레임의 높이 (라인수). frame rate가 60 Hz 의 경우는 525, 50 Hz 의 경우는 625.
Compression
디스크상에서 사용되는 MPEG 압축의 종류를 나타내는 DVD_VIDEO_COMPRESSION 형의 변수.
fLine21Field1InGOP
TRUE 는 Line 21 의 필드 1 에 유저 데이터가 있는 것을 의미한다.
fLine21Field2InGOP
TRUE 는 Line 21 의 필드 2 에 유저 데이터가 있는 것을 의미한다.
ulSourceResolutionX
x 축의 소스 해상도 (352, 704, 또는 720).
ulSourceResolutionY
y 축의 소스 해상도 (240, 480, 288, 또는 576).
fIsSourceLetterboxed
TRUE 는 소스 비디오가 레터박스 포맷인 것을 의미한다. 서브 픽쳐와 메뉴 버튼은, 액티브한 비디오 영역내 밖에 표시할 수 없다.
fIsFilmMode
625/50 Hz 의 시스템으로, TRUE 가 "필름 모드 " 를 의미해, FALSE 가 "카메라 모드 " 를 의미한다.

주의

이 구조체의 값은, 어플리케이션이 IDvdInfo2::GetCurrentVideoAttributes 메소드를 호출하면 설정된다.


FILTER_INFO 구조체

구조체

필터에 관한 정보가 저장 된다.

구문

typedef struct _FilterInfo {
    WCHAR        achName[MAX_FILTER_NAME];
    IFilterGraph * pGraph;
} FILTER_INFO;

멤버

achName
필터명이 저장 된, NULL 로 종료하는 캐릭터 라인.
pGraph
필터가 필터 그래프에 속하고 있는 경우는, 필터 그래프의 IFilterGraph 인터페이스에의 포인터가 들어간다. 필터가 필터 그래프에 속하지 않은 경우는, NULL.

주의

pGraph 멤버가 NULL 가 아닌 경우, 다 사용했으면 , 어플리케이션측에서 IFilterGraph 인터페이스를 해방해야 한다.


MPEG1VIDEOINFO 구조체

구조체

MPEG-1 비디오 스트림을 기술한다.

구문

typedef struct tagMPEG1VIDEOINFO {
    VIDEOINFOHEADER hdr;
    DWORD           dwStartTimeCode;
    DWORD           cbSequenceHeader;
    BYTE            bSequenceHeader[1];
} MPEG1VIDEOINFO;

멤버

hdr
VIDEOINFOHEADER 구조체.
dwStartTimeCode
데이터 선두에 있는 25 비트의 "화면 그룹 (GOP) " 타임 코드.
cbSequenceHeader
bSequenceHeader 의 길이 (바이트 단위).
bSequenceHeader
양자화 매트릭스(있는 경우)를 포함한 순서 헤더.


MPEG2VIDEOINFO 구조체

구조체

MPEG-2 비디오 스트림을 기술한다.

구문

typedef struct tagMPEG2VIDEOINFO {
    VIDEOINFOHEADER2    hdr;
    DWORD               dwStartTimeCode;
    DWORD               cbSequenceHeader;
    DWORD               dwProfile;
    DWORD               dwLevel;
    DWORD               dwFlags;
    DWORD               dwSequenceHeader[1];
} MPEG2VIDEOINFO;

멤버

hdr
VIDEOINFOHEADER2 구조체.
dwStartTimeCode
데이터 선두에 있는 25 비트의 "화면 그룹(GOP) " 타임 코드 (DVD 에서는 사용하지 않는다).
cbSequenceHeader
dwSequenceHeader 의 길이 (바이트 단위). DVD 에서는 0.
dwProfile
MPEG2Profile 열거형의 멤버.
dwLevel
MPEG2Level 열거형의 멤버.
dwFlags
각종 설정을 나타내는 플래그. 이하의 값을 1 개 이상 조합해 설정한다.
AMMPEG2_DoPanScan | 온의 경우, MPEG-2 비디오 디코더는, 화면 표시 extension의빵-스캔 벡터에 근거해 출력 이미지를 도려내, 거기에 맞추어 화면 어스펙트비(가로세로 비율)을 변경해야 한다.
AMMPEG2_DVDLine21Field1 | 온의 경우, MPEG-2 비디오 디코더는, 필드 1 의 Group Of Pictures (GOP) 층에 있는 DVD 스타일의 자막 방송 데이터를 위해서(때문에) 출력 핀을 생성할 수 없으면 안 된다.
AMMPEG2_DVDLine21Field2 | 온의 경우, MPEG-2 비디오 디코더는, 필드 2 의 GOP 층에 있는 DVD 스타일의 자막 방송 데이터를 위해서(때문에) 출력 핀을 생성할 수 없으면 안 된다.
AMMPEG2_SourceIsLetterboxed | 온의 경우, 비디오의 상하에 검은 띠가 encode 되고 있는 것을 나타낸다.
AMMPEG2_FilmCameraMode | 온의 경우는,625/50 (라인/필드)의 컨텐츠에 "필름 모드 " 가 사용되고 있는 것을 나타낸다. 오프의 경우는, "카메라 모드 " 가 사용되고 있는 것을 나타낸다.
미정도리의 플래그는 0 으로 설정하는 것. 0 이외의 경우, 접속은 거부된다.
dwSequenceHeader
양자화 매트릭스 (있는 경우)를 포함한 순서 헤더.


PID_MAP 구조체

구조체

MPEG-2 트랜스폴트 스트림 패킷 ID 의 내용을 나타내는 정보가 들어간다. IEnumPIDMap::Next 메소드와 함께 이용된다.

구문

typedef struct {
    ULONG                   ulPID;
    MEDIA_SAMPLE_CONTENT    MediaSampleContent ;
} PID_MAP ;

멤버

ulPID
패킷 ID 를 지정.
MediaSampleContent
패킷 유료 하중의 내용을 지정.


PIN_INFO 구조체

구조체

핀에 관한 정보가 저장 된다. IPin::QueryPinInfo 메소드와 함께 사용된다.

구문

typedef struct  _PinInfo
{
    IBaseFilter *pFilter;
    PIN_DIRECTION dir;
    WCHAR achName[128];
} PIN_INFO;

멤버

pFilter
소유자 필터의 IBaseFilter 인터페이스에의 포인터.
dir
핀의 방향 (입력/출력).
achName
핀의 이름.

주의

출력 핀의 이름이 ~ (치르다)로부터 시작되는 경우, 필터 그래프 매니저에서는, 그래프의 구축시에 그 출력 핀은 무시된다. IGraphBuilder::Connect ,IGraphBuilder::Render , 또는 IGraphBuilder::RenderFile 의 호출로 중간 필터에 그 핀이 발견되었을 경우, 필터 그래프 매니저는 핀을 렌더링 하지 않는다 (다만 Connect 메소드나 Render 메소드에 명시적으로 핀을 건네주었을 경우는 제외하다).

디폴트에서는 렌더링 되지 않는 세칸다리스트림을 건네주는 핀이나, 올바르고 렌더링 하기 위해서 특수한 코드가 필요하게 되는 핀에는,~ (치르다)를 사용한다. 예를 들어, DVD 필터에서는, 서브 픽쳐 또는 자막 방송 데이터를 건네주는 핀에 사용한다. 또, 비디오 캡춰 필터에서는, 캡춰 핀 (다만 프리뷰 핀 이외)에 사용한다.


Quality 구조체

구조체

렌더러의 퍼포먼스를 최적화하기 위해(때문에), 렌더러내 상태 (데이터 과잉 또는 데이터 부족)를 나타내, 프레임을 가감(상태)하는 퍼센티지를 지정하는 것에 의해, 품질 메세지를 기술한다.

구문

typedef struct{
    QualityMessageType  Type;
    long                Proportion;
    REFERENCE_TIME      Late;
    REFERENCE_TIME      TimeStamp;
} Quality;

멤버

Type
Famine 또는 Flood . 다운 스트림 필터에의 데이터가 부족한지, 또는 과잉인 것을 나타낸다.
Proportion
Microsoft® DirectShow® 가 미디어 샘플의 송신을 계속해야 할 레이트를 지정하는 값. 기저값 1000 은, 레이트를 변경하지 않는 것을 나타낸다. 1000 으로부터의 증감의 비율이, 가감(상태)하는 프레임수의 비율을 나타낸다. 예를 들어 이 값이 800 의 경우, DirectShow 는, 렌더러의 속도에 맞추기 (위해)때문에, 받은 프레임의 20 % 를 드롭 한다.
Late
다운 스트림으로 데이터 부족이 일어나고 있는 경우, 스트림이 늦는 시간의 길이를 나타낸다.
TimeStamp
DirectShow 가 이 구조체를 생성 한 시간을 지정하는 값. 보통, 이 값은 비디오 샘플 위에의 시작 타임이다.


REGFILTER 구조체

구조체

이름과 클래스 식별자 (CLSID)에 의해 필터를 식별한다.

구문

typedef struct {
    CLSID Clsid;
    LPWSTR Name;
} REGFILTER;

멤버

Clsid
필터의 CLSID.
Name
필터의 이름.

주의

폐지된 IEnumRegFilters 인터페이스는, 이 구조체를 사용한다. 다만, 새로운 어플리케이션에서는, 모니카를 열거하는 IFilterMapper2 를 사용하는 것.


REGFILTER2 구조체

구조체

필터를 등록하기 위한 정보가 저장 된다.

구문

typedef struct
{
    DWORD dwVersion;
    DWORD dwMerit;
    union
    {
        struct
        {
            ULONG cPins;
            const REGFILTERPINS *rgPins;
        };
        struct
        {
            ULONG cPins2;
            const REGFILTERPINS2 *rgPins2;
        };
    };
} REGFILTER2;

멤버

dwVersion
필터 등록의 포맷. 값 1 은, 공용체에 이름이 없는 1 번째의 구조체가 저장 되고 있는 것을 나타낸다. 값 2 는, 공용체에 이름이 없는 2 번째의 구조체가 저장 되고 있는 것을 나타낸다.
dwMerit
필터의메리트 . 메리트값이 높은 필터(정도)만큼 먼저 열거된다.
cPins
핀의 수 (dwVersion 가 1 의 경우에만 정의된다).
rgPins
REGFILTERPINS 구조체의 배열에의 포인터 (dwVersion 가 1 의 경우에만 정의된다). 배열의 사이즈는 cPins.
cPins2
핀의 수 (dwVersion 가 2 의 경우에만 정의된다).
rgPins2
REGFILTERPINS2 구조체의 배열에의 포인터 (dwVersion 가 2 의 경우에만 정의된다). 배열의 사이즈는 cPins2.

주의

이 구조체는,IFilterMapper2::RegisterFilter 메소드에게 건네진다.

핀의 미디어 또는 카테고리를 등록하려면 ,dwVersion 에 2 를 설정해, REGFILTERPINS2 구조체를 사용한다.


REGFILTERPINS 구조체

구조체

필터를 등록하기 위한 핀 정보가 저장 된다.

구문

typedef struct
{
    LPWSTR            strName;
    BOOL              bRendered;
    BOOL              bOutput;
    BOOL              bZero;
    BOOL              bMany;
    const CLSID       *clsConnectsToFilter;
    const WCHAR       *strConnectsToPin;
    UINT              nMediaTypes;
    const REGPINTYPES *lpMediaType;
} REGFILTERPINS;

typedef REGFILTERPINS AMOVIESETUP_PIN,
    * PAMOVIESETUP_PIN,
    * FAR LPAMOVIESETUP_PIN;

멤버

strName
핀의 이름. (폐지)
bRendered
TRUE 의 경우, 필터는 이 핀으로부터의 입력을 렌더링 한다 (입력 핀에만 적용된다). 출력 핀의 경우는 항상 FALSE.
bOutput
TRUE 의 경우, 이 핀은 출력 핀이 된다. 그 이외의 경우는, 입력 핀이 된다.
bZero
TRUE 의 경우, 필터가 이 핀의 인스턴스를 1 개도 가지지 않는 것이 있다.
bMany
TRUE 의 경우, 필터가 이 종류의 핀의 인스턴스를 복수 생성 할 수 있다.
clsConnectsToFilter
이 핀이 접속하는 필터의 클래스 식별자 (CLSID). (폐지)
strConnectsToPin
이 핀이 접속하는 핀의 이름. (폐지)
nMediaTypes
이 핀이 지원 하는 미디어 샘플수.
lpMediaType
REGPINTYPES 구조체의 배열에의 포인터. 배열의 사이즈는 nMediaTypes.

주의

이 구조체는, 필터를 등록하기 위해서 IFilterMapper2 인터페이스로 사용된다. 이 구조체를 사용하는 경우에는,REGFILTER2 구조체의 dwVersion 멤버에 1 을 설정한다. 핀의 미디어 또는 카테고리를 등록하려면 ,REGFILTERPINS2 구조체를 사용한다. 이 경우, REGFILTER2 구조체의 dwVersion 멤버에 2 를 설정한다.

클래스 팩토리 템플릿 (CFactoryTemplate )에서는, 동등의 AMOVIESETUP_PIN 형이 사용된다.

strName,clsConnectsToFilter, 및 strConnectsToPin 멤버는 폐지되었다. 이것들 멤버의 값은 레지스트리에 추가되지 않는다.

상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.


REGFILTERPINS2 구조체

구조체

IFilterMapper2 인터페이스를 통해서 필터를 등록하기 위한 정보가 저장 된다.

구문

typedef struct
{
    DWORD               dwFlags;
    UINT                cInstances;
    UINT                nMediaTypes;
    const REGPINTYPES   *lpMediaType;
    UINT                nMediums;
    const REGPINMEDIUM  *lpMedium;
    const CLSID         *clsPinCategory;
} REGFILTERPINS2;

멤버

dwFlags
REG_PINFLAG 플래그의 비트마다의 편성 (0 개라도 좋다).
cInstances
핀의 인스턴스수.
nMediaTypes
이 핀이 지원 하는 미디어 샘플수.
lpMediaType
REGPINTYPES 구조체의 배열에의 포인터. 배열의 사이즈는 nMediaTypes.
nMediums
미디어수. 0 이라도 좋다.
lpMedium
REGPINMEDIUM 구조체의 배열에의 포인터. 배열의 사이즈는 nMediums.
clsPinCategory
핀 프로퍼티 세트로부터 얻을 수 있는 핀 카테고리 (생략 가능).

주의

이 구조체를 사용하는 경우는,REGFILTER2 구조체의 dwVersion 멤버에 2 를 설정한다.


REGPINMEDIUM 구조체

구조체

IFilterMapper2 인터페이스를 통해서 등록하기 위해서 핀 미디어를 기술한다.

구문

typedef struct
{
    CLSID clsMedium;
    DWORD dw1;
    DWORD dw2;
} REGPINMEDIUM;

멤버

clsMedium
미디어를 지정하는 GUID.
dw1
이 미디어의 인스턴스를 지정하는 DWORD 형의 변수. 이것은 2 개의 같은 디바이스가 호스트 시스템에 존재할 경우에 필요하다.
dw2
미사용.

주의

medium 는 1 개의 하드웨어 디바이스내에 있는 있고는 2 개의 디바이스간에 존재하는 커뮤니케이션의 하드웨어 패스를 지정한다. 개발하는 필터가, 커넬 스트리밍 핀상에서 구축되어 같은 필터에 접속할 필요가 있는 경우에는, 미디어를 등록한다.

이 구조체는, 커넬 스트리밍 드라이버가 이용하는 KSPIN_MEDIUM 구조체와 동등하다. 상세한 것에 대하여는, Microsoft® Windows® Driver Development Kit (DDK)를 참조할것.


REGPINTYPES 구조체

구조체

필터를 등록하기 위한 미디어 타입 정보가 저장 된다.

구문

typedef struct
{
    const CLSID *clsMajorType;
    const CLSID *clsMinorType;
} REGPINTYPES;

typedef REGPINTYPES AMOVIESETUP_MEDIATYPE,
    * PAMOVIESETUP_MEDIATYPE,
    * FAR LPAMOVIESETUP_MEDIATYPE;

멤버

clsMajorType
미디어 타입의메이저 타입 GUID .
clsMinorType
미디어 타입의서브 타입 GUID . MEDIASUBTYPE_NULL 이라도 좋다.

주의

이 구조체는, 핀이 지원 하는 미디어 타입을 식별하기 위해서,IFilterMapper2 인터페이스로 사용된다. 클래스 팩토리 템플릿 (CFactoryTemplate )에서는, 동등의 AMOVIESETUP_MEDIATYPE 형이 사용된다.

같은 메이저 타입에 포함되는 서브 타입의 범위를 등록하려면 , 값 MEDIASUBTYPE_NULL 를 사용한다.

상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.


STREAM_ID_MAP 구조체

구조체

MPEG-2 프로그램 스트림내의 기본 스트림을 기술한다. IEnumStreamIdMap 인터페이스 메소드와 함께 이용된다.

구문

typedef struct {
    ULONG   stream_id;
    DWORD   dwMediaSampleContent;
    ULONG   ulSubstreamFilterValue;
    int     iDataOffset;
} STREAM_ID_MAP ;

멤버

stream_id
PES 스트림의 ID 를 지정한다.
dwMediaSampleContent
스트림의 미디어의 내용을 지정한다. 이하의 변수의 언젠가 (axextend.idl 내에서 정의된다) :
    MPEG2_PROGRAM_STREAM_MAP                 0x00000000
    MPEG2_PROGRAM_ELEMENTARY_STREAM          0x00000001
    MPEG2_PROGRAM_DIRECTORY_PES_PACKET       0x00000002
    MPEG2_PROGRAM_PACK_HEADER                0x00000003
    MPEG2_PROGRAM_PES_STREAM                 0x00000004
    MPEG2_PROGRAM_SYSTEM_HEADER              0x00000005
ulSubstreamFilterValue
기본 스트림내의 서브 스트림을 지정한다. 서브 스트림 필터 링이 요구되어 있지 않으면, SUBSTREAM_FILTER_VAL_NONE (0x10000000)를 사용하는 것.
iDataOffset
서브 스트림에 대한 오프셋(offset)를 바이트 단위로 지정한다. 필터 링이 요구되어 있지 않으면 0 을 지정하는 것.


TIMECODE 구조체

구조체

기본적인 타임 코드 프레임 카운트 정보가 저장 된다.

구문

typedef struct tagTIMECODE {
    WORD  wFrameRate;
    WORD  wFrameFract;
    DWORD  dwFrames;
}TIMECODE;

멤버

wFrameRate
1 초 쯤의 프레임수. 이하의 값의 어느쪽이든을 지정한다.
ED_FORMAT_SMPTE_30 | 30 프레임/초.
ED_FORMAT_SMPTE_30DROP | 30 프레임/초의 드롭 프레임 (실제의 레이트는 29.97 fps).
ED_FORMAT_SMPTE_25 | 25 프레임/초.
ED_FORMAT_SMPTE_24 | 24 프레임/초.
wFrameFract
프레임의 분수. 전면적은은 0x1000.
dwFrames
바이너리의 프레임 카운트로 표현된 타임 코드값.

주의

프레임의 분수를 사용 하면, 타임 코드가 실제로 외부 디바이스로부터 읽힌 시간을, 프레임내에 있어서의 시간적인 오프셋(offset)로 가리킬 수가 있다. 예를 들어, wFrameFract=0x7ff 는, 디바이스로부터 읽힌 타임 코드값이, 제 1 비디오 필드의 마지막에 있던 것을 의미한다.

주 : 컴퓨터와의 타임 코드의 교환은, 보통, ASCII 값으로 행해지기 (위해)때문에, 샘플 필터에는, 바이너리의 프레임 카운트와 ASCII 값을 변환하기 위한 헬퍼 메소드가 준비되어 있다.


TIMECODE_SAMPLE 구조체

구조체

타임 코드의 완전한 정보가 저장 된다.

구문

typedef struct tagTIMECODE_SAMPLE {
    LONGLONG  qwTick;
    TIMECODE  timecode;
    DWORD  dwUser;
    DWORD  dwFlags;
} TIMECODE_SAMPLE;

멤버

qwTick
기준 타임 (100 나노초단위).
timecode
TIMECODE 구조체.
dwUser
팩 된 SMPTE 유저 비트 .
dwFlags
타임 코드의 플래그 마스크. 이하의 값을 1 개 이상 조합해 지정한다.
AM_TIMECODE_FLAG_FCM | 프레임 코드의 모드 (0 은 비드롭, 1 은 드롭).
AM_TIMECODE_FLAG_CF | 칼라 프레임 플래그.
AM_TIMECODE_FLAG_FIELD | 필드 플래그.
AM_TIMECODE_FLAG_DF | 드롭 프레임 플래그 (외부 미디어 위에의 실제의 타임 코드에 있는 플래그로부터 얻을 수 있다).
AM_TIMECODE_COLORFRAME | 칼라 프레임의 순서를 지정한다.
AM_TIMECODE_COLORSEQUENCE | 순서 전체의 시간폭 (프레임수).
AM_TIMECODE_FILMSEQUENCE_TYPE | FILM_SEQUENCE_XXX 정의의 1 개.

주의

dwFlags 의 상위 16 비트는, 장래적인 사용을 위해서(때문에) 예약되고 있다. 0 으로 설정한다.


TRUECOLORINFO 구조체

구조체

비디오 이미지의 칼라 팔레트 및 비트 마스크 정보가 저장 된다.

구문

typedef struct tag_TRUECOLORINFO {
    DWORD dwBitMasks[iMASK_COLORS];
    RGBQUAD bmiColors[iPALETTE_COLORS];
} TRUECOLORINFO;

멤버

dwBitMasks[iMASK_COLORS]
색의 마스크의 배열 (색의 요소 마다 1 개(살)씩).
bmiColors[iPALETTE_COLORS]
팔레트색의 배열.

주의

이 구조체는, 일부의 RGB 포맷에는 사용되지 않는다. 각종 상황마다의 유효한 필드에 대해서는, Platform SDK 의 문서의 BITMAPINFO 를 참조할것.

참조

VIDEOINFO


VIDEO_STREAM_CONFIG_CAPS 구조체

구조체

가능한 접속에 관한 정보가 저장 된다.

구문

typedef struct  _VIDEO_STREAM_CONFIG_CAPS
    {
    GUID guid;
    ULONG VideoStandard;
    SIZE InputSize;
    SIZE MinCroppingSize;
    SIZE MaxCroppingSize;
    int CropGranularityX;
    int CropGranularityY;
    int CropAlignX;
    int CropAlignY;
    SIZE MinOutputSize;
    SIZE MaxOutputSize;
    int OutputGranularityX;
    int OutputGranularityY;
    int StretchTapsX;
    int StretchTapsY;
    int ShrinkTapsX;
    int ShrinkTapsY;
    LONGLONG MinFrameInterval;
    LONGLONG MaxFrameInterval;
    LONG MinBitsPerSecond;
    LONG MaxBitsPerSecond;
    }  VIDEO_STREAM_CONFIG_CAPS;

멤버

guid
비디오 샘플을 나타내는 MEDIATYPE_Video 로 설정된다.
VideoStandard
지원 되는 아날로그 비디오 규격. AnalogVideoStandard 열거형이 설정된다 (지원 되지 않는 경우는 0).
InputSize
받는 신호의 사이즈. Win32 SIZE 구조체를 통해서, 이미지 직사각형의 폭 및 높이 (픽셀 단위)로 표현된다. 압력 필터의 경우, 이 사이즈는 입력 핀의 AM_MEDIA_TYPE 구조 체내에 있는 Win32 BITMAPINFOHEADER 구조체의 폭 및 높이의 멤버로부터 취득된다. 캡춰 필터의 경우, 이 사이즈는 필터가 전픽셀이 일의디지털화할 수가 있는 최대의 신호 사이즈이다.
MinCroppingSize
VIDEOINFOHEADER 구조체의 rcSource 멤버로 지정된, 사용할 수 있는 최소의 크로핑 직사각형.
MaxCroppingSize
VIDEOINFOHEADER 구조체의 rcSource 멤버로 지정된, 사용할 수 있는 최대의 크로핑 직사각형.
CropGranularityX
크로핑사이즈의 세분도. 예를 들어, 유효한 폭을 4 의 정수배로 한정한다.
CropGranularityY
크로핑사이즈의 세분도. 예를 들어, 유효한 높이를 4 의 정수배로 한정한다.
CropAlignX
InputSize 내에 있어서의 크로핑 직사각형의 alignment. 예를 들어, 직사각형이 4 의 배수의 경계로부터 시작되도록(듯이) 지정한다.
CropAlignY
InputSize 내에 있어서의 크로핑 직사각형의 alignment. 예를 들어, 직사각형이 4 의 배수의 경계로부터 시작되도록(듯이) 지정한다.
MinOutputSize
이 핀을 생성할 수 있는 최소의 비트 맵.
MaxOutputSize
이 핀을 생성할 수 있는 최대의 비트 맵.
OutputGranularityX
출력 비트 맵의 폭의 세분도.
OutputGranularityY
출력 비트 맵의 높이의 세분도.
StretchTapsX
필터가 이미지의 폭을 잡아늘이는 능력을 나타내는 값. 값 0 은 잡아늘이는 능력이 없는 것을 의미해, 값 1 은피크세르다브링을 사용하는 것을 의미한다. 또, 값 2 는보간 (탭수 2)을 사용해, 값 3 이상은 한층 더 정밀도의 높은 보간을 이행 하는 것을 의미한다.
StretchTapsY
필터가 이미지의 높이를 잡아늘이는 능력을 나타내는 값. 값 0 은 잡아늘이는 능력이 없는 것을 의미해, 값 1 은 피크세르다브링을 사용하는 것을 의미한다. 또, 값 2 는 보간 (탭수 2)을 사용해, 값 3 이상은 한층 더 정밀도의 높은 보간을 이행 하는 것을 의미한다.
ShrinkTapsX
필터가 이미지의 폭을 줄이는 능력을 나타내는 값. 값 0 은 줄이는 능력이 없는 것을 의미해, 값 1 은 일부의 픽셀행을 단순하게 제거하는 것을 의미한다. 또, 값 2 는 보간 (탭수 2)을 사용해, 값 3 이상은 한층 더 정밀도의 높은 보간을 이행 하는 것을 의미한다.
ShrinkTapsY
필터가 이미지의 높이를 줄이는 능력을 나타내는 값. 값 0 은 줄이는 능력이 없는 것을 의미해, 값 1 은 일부의 픽셀행을 단순하게 제거하는 것을 의미한다. 또, 값 2 는 보간 (탭수 2)을 사용해, 값 3 이상은 한층 더 정밀도의 높은 보간을 이행 하는 것을 의미한다.
MinFrameInterval
사용할 수 있는 최소의 frame rate. 캡춰 필터에게만 적용된다.
MaxFrameInterval
사용할 수 있는 최대의 frame rate. 캡춰 필터에게만 적용된다.
MinBitsPerSecond
이 핀을 생성할 수 있는 최소의 데이터 레이트.
MaxBitsPerSecond
이 핀을 생성할 수 있는 최대의 데이터 레이트.

주의

예를 들어, 구조체의 일부의 멤버로서 이하의 값을 상정한다.

  • MinCroppingSize = (160, 120)
  • MaxCroppingSize = (320, 240)
  • CropGranularityX = 4
  • CropGranularityY = 8

이러한 값은, 유효한 크로핑사이즈가,MinCroppingSize 로부터 시작되어, x 방향으로 CropGranularityX 간격, y 방향으로 CropGranularityY 간격으로 증가하는 것을 나타낸다. 이 경우, x 는 160 ~ 320 픽셀의 범위에서 4 간격의 값을 취해, y 는 120 ~ 240 픽셀의 범위에서 8 간격의 값을 취한다.

예를 들어 다음과 같은 사이즈가 유효하다.

  • 160 × 120, 164 × 120, 168 × 120, 172 × 120 등
  • 160 × 128, 164 × 128, 168 × 128, 172 × 128 등
  • 160 × 136, 164 × 136, 168 × 136, 172 × 136 등

CropAlignX 및 CropAlignY 는, 입력 사이즈 직사각형내에 있어서의 크로핑 직사각형의 위치를 나타낸다. 크로핑 직사각형의 사이즈를 160 × 120 으로 해, 이러한 값을 다음과 같이 상정한다.

  • CropAlignX = 2
  • CropAlignY = 4

이 경우,VIDEOINFOHEADER 구조체의 rcSource 멤버로서는, 예를 들어 다음과 같은 값이 유효하다.

  • (0, 0, 160, 120)
  • (2, 0, 162, 120)
  • (2, 4, 162, 124)
  • (2, 8, 162, 128)

같은 alignment로 크로핑 직사각형을 320 × 240 으로 했을 경우, 유효한 직사각형은 (2, 4, 322, 244) 등이 된다.

이 항으로 설명하는 구조체 멤버는, 세트로 기능해, 출력 핀의 미디어 타입을 기술하는 VIDEOINFOHEADER 구조체로서 유효한 rcSource 의 값을 지정한다. 구조체의 나머지의 멤버 가운데,MinOutputSize,MaxOutputSize,OutputGranularityX, 및 OutputGranularityY 는, 출력 핀의 미디어 타입 VIDEOINFOHEADER 구조체에 저장 된 BITMAPINFOHEADER 구조체의 biWidth 멤버 및 biHeight 멤버를 기술한다.


VIDEOINFO 구조체

구조체

비디오 이미지의 비트 맵과 색정보를 기술한다.

구문

typedef struct tagVIDEOINFO {
    RECT            rcSource,
    RECT            rcTarget,
    DWORD           dwBitRate,
    DWORD           dwBitErrorRate,
    REFERENCE_TIME  AvgTimePerFrame;
    BITMAPINFOHEADER    bmiHeader;
union {
        RGBQUAD     bmiColors[iPALETTE_COLORS];
        DWORD       dwBitMasks[iMASK_COLORS];
        TRUECOLORINFO   TrueColorInfo;
    };
} VIDEOINFO;

멤버

rcSource
입력 비디오의 사용 부분.
rcTarget
비디오의 표시처.
dwBitRate
비트 데이터 레이트 (개수).
dwBitErrorRate
이 스트림의 비트 에러 레이트.
AvgTimePerFrame
프레임 근처의 평균 시간 (100 나노초단위).
bmiHeader
데바이즈에 의존하지 않는 비트 맵의 색 및 넓이 정보가 저장 된 Win32 BITMAPINFOHEADER 구조체.
bmiColors
적, 초록, 및 파랑의 휘도로 비디오의 칼라 팔레트를 지정하는 Win32 RGBQUAD 구조체의 배열.
dwBitMasks
트루 칼라의 비트 마스크를 지정하는 DWORD 값의 배열.
TrueColorInfo
칼라 팔레트와 칼라 비트 마스크의 양쪽 모두가 저장 된 TRUECOLORINFO 구조체.

주의

표준의 RGB 포맷 이외를 저장 할 가능성이 있는 경우는, 이 구조체를 사용하지 않는 것. 표준의 RGB 이외를 저장 하면,bmiHeader 구조체의 변수 사이즈가 원인으로 문제가 일어날 가능성이 높다. 대신에 VIDEOINFOHEADER 구조체를 사용하는 것. 어떠한 이유로써 VIDEOINFO 구조체를 사용할 필요가 있는 경우에는,TrueColorInfo,dwBitMasks, 및 bmiColors 에 직접 액세스 하지 않고 ,TRUECOLORINFO 매크로,COLORS 매크로, 및 BITMASKS 매크로를 사용해 색정보에의 포인터를 돌려주는 것. 이러한 멤버중 한쪽이,BITMAPINFOHEADER 구조체에 대응해 유효하게 된다.

최초의 데이터 멤버 5 개(살)은,VIDEOINFOHEADER 구조체와 동등하다. VIDEOINFO 구조체에의 포인터의 처리에 필요한 역참조의 양을 줄이기 위해서(때문에), 이러한 멤버가 완전하게 전개되고 있다.

rcSource 와 rcTarget 멤버의 사용법의 상세한 것에 대하여는, 「비디오 렌더러에 있어서의 전송원직사각형과 전송처 직사각형」을 참조할것.


VIDEOINFOHEADER 구조체

구조체

비디오 이미지의 비트 맵과 색정보를 기술한다.

구문

typedef struct tagVIDEOINFOHEADER {
    RECT                rcSource,
    RECT                rcTarget;
    DWORD               dwBitRate;
    DWORD               dwBitErrorRate;
    REFERENCE_TIME      AvgTimePerFrame;
    BITMAPINFOHEADER    bmiHeader;
} VIDEOINFOHEADER;

멤버

rcSource
전송원비디오 윈도우를 지정하는 RECT 구조체. 소스 비디오 스트림의 일부를 선택하기 위해(때문에), 이 구조체를 클리핑 직사각형이라고 해도 좋다.
rcTarget
전송처 비디오 윈도우를 지정하는 RECT 구조체.
dwBitRate
비디오 스트림의 대체로의 데이터 레이트 (비트/초) .
dwBitErrorRate
비디오 스트림의 데이터 에러 레이트 (비트 에러/초) .
AvgTimePerFrame
비디오 프레임의 평균 표시 시간 (100 나노초단위) .
bmiHeader
비디오 이미지의 색 및 넓이 정보가 저장 된 Win32 BITMAPINFOHEADER 구조체.

주의

rcSource 와 rcTarget 멤버의 사용에 대한 정보는, 「비디오 렌더러에 있어서의 전송원직사각형과 전송처 직사각형」을 참조할것.


VIDEOINFOHEADER2 구조체

구조체

인터레이스, 카피 보호, 및 픽셀의 어스펙트비(가로세로 비율)의 정보를 포함한, 비디오 이미지의 비트 맵 및 색정보를 기술한다.

구문

typedef struct tagVIDEOINFOHEADER2 {
    RECT                rcSource;
    RECT                rcTarget;
    DWORD               dwBitRate;
    DWORD               dwBitErrorRate;
    REFERENCE_TIME      AvgTimePerFrame;
    DWORD               dwInterlaceFlags;
    DWORD               dwCopyProtectFlags;
    DWORD               dwPictAspectRatioX;
    DWORD               dwPictAspectRatioY;
    DWORD               dwReserved1;
    DWORD               dwReserved2;
    BITMAPINFOHEADER    bmiHeader;
} VIDEOINFOHEADER2;

멤버

rcSource
전송처 버퍼에 보내는 소스 스트림의 사용 부분을 지정하는 RECT 구조체. 렌더러에서는, 이 필드를 사용해, 디코더에 신축 또는 클리핑을 지시할 수 있다. 상세한 것에 대하여는, 「비디오 렌더러에 있어서의 전송원직사각형과 전송처 직사각형」을 참조할것.
rcTarget
전송처 버퍼의 어느 부분을 사용하는지를 지정하는 RECT 구조체. 상세한 것에 대하여는, 「비디오 렌더러에 있어서의 전송원직사각형과 전송처 직사각형」을 참조할것.
dwBitRate
비디오 스트림의 대체로의 데이터 레이트 (비트/초).
dwBitErrorRate
비디오 스트림의 데이터 에러 레이트 (비트/초).
AvgTimePerFrame
비디오 프레임의 평균 표시 시간 (100 나노초단위).
dwInterlaceFlags
이하의 플래그의 비트마다의 편성 (0 개라도 좋다). 이 플래그의 상세한 것에 대하여는, 이 페이지의 마지막 겉(표)를 참조할것.
AMINTERLACE_IsInterlaced | 스트림이 인터레이스 방식이다. 이 플래그가 오프의 경우, 다른 비트는 의미가 없다.
AMINTERLACE_1FieldPerSample | 미디어 샘플 근처 1 필드. 이 플래그가 오프의 경우는, 미디어 샘플 마다 2 필드가 된다.
AMINTERLACE_Field1First | 필드 1 이 앞. 이 플래그가 오프의 경우는, 필드 2 가 먼저 된다 (선두 필드는,PAL 에서는 필드 1, NTSC 에서는 필드 2).
AMINTERLACE_FieldPatField1Only | 스트림에 필드 2 는 없다.
AMINTERLACE_FieldPatField2Only | 스트림에 필드 1 은 없다.
AMINTERLACE_FieldPatBothRegular | 필드 1 마다 필드 2 가 반드시 1 개 있다.
AMINTERLACE_FieldPatBothIrregular | 필드 1 으로 필드 2 가 불규칙하게 배치되고 있다.
AMINTERLACE_DisplayModeBobOnly | 디스플레이 모드는 Bob 마셔.
AMINTERLACE_DisplayModeWeaveOnly | 디스플레이 모드는위브만.
AMINTERLACE_DisplayModeBobOrWeave | Bob 와 위브의 양쪽 모두의 모드가 있다.
미정도리의 플래그는 0 으로 설정하는 것. 0 이외의 경우, 접속은 거부된다.
dwCopyProtectFlags
스트림의 중복을 제한해야 하는 것을 나타내는 AMCOPYPROTECT_RestrictDuplication 값이 세트 된 플래그. 미정도리의 경우는, 0 으로 지정하는 것. 0 이외의 경우, 접속은 거부된다.
dwPictAspectRatioX
화면의 어스펙트비(가로세로 비율) (x 넓이). 예를 들어, 16 × 9 인치 디스플레이의 경우는 16.
dwPictAspectRatioY
화면의 어스펙트비(가로세로 비율) (y 넓이). 예를 들어, 16 × 9 인치 디스플레이의 경우는 9.
dwReserved1
예약이 끝난 상태. 제로가 아니면 안 된다.
dwReserved2
장래적인 사용을 위해서(때문에) 예약되고 있다. 제로가 아니면 안 된다.
bmiHeader
비디오 이미지의 색 및 넓이 정보가 저장 된 Microsoft® Win32® BITMAPINFOHEADER 구조체.

주의

dwInterlaceFlags 의 필드 패턴 플래그를 확인하려면 , 다음과 같이 비트 마스크 AMINTERLACE_FieldPatternMask 를 사용한다.

switch (dwInterlaceFlags & AMINTERLACE_FieldPatternMask)
{
    case AMINTERLACE_FieldPatField1Only:
        // 스트림에 필드 2 는 없다.
    case AMINTERLACE_FieldPatField2Only:
        // 스트림에 필드 1 은 없다.
    case AMINTERLACE_FieldPatBothRegular:
        // 필드 1 마다 필드 2 가 반드시 1 개 있다.
    case AMINTERLACE_FieldPatBothIrregular:
        // 필드 1 으로 필드 2 가 불규칙하게 배치되고 있다.
}

dwInterlaceFlags 의 디스플레이 모드 플래그를 확인하려면 , 다음과 같이 비트 마스크 AMINTERLACE_DisplayModeMask 를 사용한다.

switch (dwInterlaceFlags & AMINTERLACE_DisplayModeMask)
{
    case AMINTERLACE_DisplayModeBobOnly:
        // 디스플레이 모드는 Bob 마셔.
    case AMINTERLACE_DisplayModeWeaveOnly:
        // 디스플레이 모드는 위브만.
    case AMINTERLACE_DisplayModeBobOrWeave:
        // Bob 와 위브의 양쪽 모두의 모드가 있다.
}

다음의 표는,오버레이 믹서 필터의 인터레이스 필드/프레임을 표시하기 위한 , 인터페이스 플래그와 샘플 프로퍼티의 유효한 편성을 기술하고 있다. 샘플 프로퍼티는 각 샘플의 AM_SAMPLE2_PROPERTIES 구조체의 dwTypeSpecificFlags 멤버로 지정되고 있다.

디스플레이 모드 | 인터레이스 플래그 | 미디어 샘플 프로퍼티
프레임 | 0 | 0
비인터레이스의 Bob AMINTERLACE_IsInterlaced |
AMINTERLACE_1FieldPerSample |
AMINTERLACE_DisplayModeBobOnly 		AM_VIDEO_FLAG_FIELD1 or AM_VIDEO_FLAG_FIELD2
위브만 AMINTERLACE_IsInterlaced |
AMINTERLACE_FieldPatBothRegular |
AMINTERLACE_DisplayModeWeaveOnly 		AM_VIDEO_FLAG_WEAVE
인터레이스의 Bob 마셔 필드 1 이 최초 AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOnly 		AM_VIDEO_FLAG_FIELD1_FIRST
필드 2 가 최초 AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOnly 		0
Bob 나 위브
(교체 가능) 		Bob, 필드 1 이 최초 AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOrWeave 		AM_VIDEO_FLAG_FIELD1_FIRST
Bob, 필드 2 가 최초 AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOrWeave 		0
위브 AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOrWeave 		AM_VIDEO_FLAG_WEAVE


열거형

이 주제에서는, Microsoft® DirectShow® 의 열거형에 대해 설명한다. 최초의 리스트의 뒤에는, 기능별의 자막 방송, DVD, 및 VPE 열거형을 나타낸다.

열거형 | 설명
AM_ASPECT_RATIO_MODE | 표시 윈도우내의 비디오 이미지의 어스펙트비(가로세로 비율)을 지정한다.
AM_FILTER_MISC_FLAGS | 소스 또는 렌더링 필터 플래그를 포함한다.
AM_GRAPH_CONFIG_RECONNECT_FLAGS | 필터 그래프를 동적으로 재생성 할 경우에 필터의 재접속 방법을 지정한다.
AM_INTF_SEARCH_FLAGS | 필터 그래프 위에의 인터페이스를 검색할 경우에, 검색 대상의 오브젝트의 타입을 지정한다.
AM_OVERLAY_NOTIFY_FLAGS | 오버레이에 의해 무엇이 변경되었는지, 또는 무엇이 변경 되려고 하고 있을까에 대한 정보를 포함한다.
AM_PIN_CONNECTION_BLOCK_FLAGS | 출력 핀으로부터의 데이터 플로우를 블록 하는 방법을 지정하는 플래그를 정의한다.
AM_PUSHSOURCE_FLAGS | 라이브 전송원필터의 동작을 나타낸다.
AM_RESCTL_RESERVEFLAGS | 현재 예약되고 있는 리소스의 수를 인크리먼트(increment) 또는 감소 할지 어떨지를 지정하는 플래그를 포함한다.
AM_SAMPLE_PROPERTY_FLAGS | AM_SAMPLE2_PROPERTIES 구조체의 dwSampleFlags 및 dwStreamId 멤버의 값을 지정한다. 이러한 값은 미디어 샘플의 프로퍼티를 기술한다.
AM_SEEKING_SEEKING_CAPABILITIES | 미디어 스트림의 시크 능력을 지정한다.
AM_STREAM_INFO_FLAGS | AM_STREAM_INFO 구조체의 각종의 컴퍼넌트가 설정되었는지 어떠했는지를 나타낸다.
AMOVERLAYFX | Microsoft® DirectDraw® 하드웨어 오버레이 표면에서의 이펙트를 지정한다.
AMTunerModeType | TV 튜너 (케이블 또는 안테나)의 주파수를 지정한다.
AnalogVideoStandard | 전용선 접속 시스템 아날로그 비디오 신호의 포맷을 지정한다.
CameraControlFlags | 카메라가 자동인가 수동인지를 지정한다.
CameraControlProperty | DirectShow 가 카메라의 어느 부분을 제어하는지를 지정한다.
CL_ELEM_FLAGS | 컷 리스트 요소 플래그를 지정한다.
CL_ELEM_STATUS | 컷 리스트 상태 플래그를 지정한다.
CompressionCaps | 비디오 압축 능력을 나타낸다.
DECIMATION_USAGE | 오버레이 믹서 필터가 사용하는 데시 메이션 방법을 기술한다.
DVDECODERRESOLUTION | 디지털 비디오 (DV)의 디코딩 해상도를 나타낸다.
DVENCODERFORMAT | DV 포맷을 나타낸다.
DVENCODERRESOLUTION | DV 인코딩 해상도를 나타낸다.
DVENCODERVIDEOFORMAT | DV 인코딩용의 비디오 규격 (NTSC 또는 PAL)을 나타낸다.
FILTER_STATE | 필터 상태를 지정한다.
InterleavingMode | 비디오 프레임과 오디오 샘플을 어떻게 디스크에 기입하는지를 지정한다.
MEDIA_SAMPLE_CONTENT | MPEG-2 트랜스폴트 스트림내의 기본 스트림의 요소를 기술한다.
MPEG2Level | MPEG-2 비디오 규격에 규정된 MPEG-2 비디오 레벨을 나타낸다. (ISO13818-2)
MPEG2Profile | MPEG-2 비디오 규격에 규정된 MPEG-2 비디오 프로파일을 나타낸다. (ISO13818-2)
PhysicalConnectorType | 핀의 물리 타입 (오디오 또는 비디오)을 지정한다.
PIN_DIRECTION | 핀의 방향을 나타낸다.
QualityMessageType | 품질 메세지 타입을 기술한다.
REG_PINFLAG | REGFILTERPINS2 구조체의 dwFlags 멤버의 플래그를 나타낸다.
REM_FILTER_FLAGS | 필터 그래프로부터 어떻게 필터를 삭제하는지를 지정한다.
SNDDEV_ERR | 에러가 발생했을 때에 오디오 디바이스가 어떻게 액세스 되고 있었는지를 지정한다.
StreamControlState | 스트림 상태를 지정한다.
TunerInputType | TV 튜너 (케이블 또는 안테나)의 주파수를 지정한다.
TVAudioMode | TV 오디오 제어의 모드를 지정한다.
VfwCaptureDialogs | Microsoft Video for Windows® 의 캡춰 드라이버에 존재 가능한 다이알로그 박스를 지정한다.
VfwCompressDialogs | Microsoft Video for Windows 의 압축 (CODEC ) 드라이버에 존재 가능한 다이알로그 박스를 지정한다.
VideoControlFlags | 비디오 디바이스의 동작 비디오 모드 (수평 또는 수직 플립, 외부 방아쇠 enable, 및 방아쇠 시뮬레이트)를 지정한다.
VideoProcAmpFlags | 비디오 프로퍼티의 설정 방법법을 지정한다.
VideoProcAmpProperty | 비디오 프로퍼티를 지정한다.

자막 방송에 고유의 열거형을 이하에 나타낸다.

자막 방송의 열거형 | 설명
AM_LINE21_CCLEVEL | 자막 방송의 능력 레벨을 나타낸다.
AM_LINE21_CCSERVICE | 자막 방송 디코더 서비스를 나타낸다.
AM_LINE21_CCSTATE | 자막 방송 상태 (온 또는 오프)를 나타낸다.
AM_LINE21_DRAWBGMODE | 자막 방송 텍스트의 백그라운드 모드를 나타낸다.

DVD 에 고유의 열거형을 이하에 나타낸다.

DVD 의 열거형 | 설명
AM_DVD_GRAPH_FLAGS | DVD 필터 그래프로 사용하는 디코더의 타입을 지정한다.
AM_DVD_STREAM_FLAGS | DVD 스트림 타입 (비디오, 오디오, 또는 서브 픽쳐)을 기술한다.
DVD_AUDIO_APPMODE | 현재의 오디오 모드를 나타낸다.
DVD_AUDIO_FORMAT | DVD 의 오디오 포맷을 나타낸다.
DVD_AUDIO_LANG_EXT | 오디오 스트림이 오디오 언어 확장을 포함하고 있는지 어떤지를 나타내는 플래그를 정의한다.
DVD_CMD_FLAGS | DVD 네비게이터 필터가 어떻게 커멘드의 동기화를 처리하는지를 제어하는 플래그를 정의한다.
DVD_DISC_SIDE | DVD 디스크의 면을 나타낸다.
DVD_DOMAIN | DVD 도메인을 지정한다.
DVD_ERROR | DVD 에러 상태를 지정한다.
DVD_FRAMERATE | DVD 를 1 초 쯤 25 프레임으로 재생하도록(듯이) 오쏘링 하는지, 1 초 쯤 30 프레임으로 재생하도록(듯이) 오쏘링 하는지를 나타낸다.
DVD_KARAOKE_ASSIGNMENT | 오디오 채널을 할당하는 스피커를 나타내는 플래그를 정의한다.
DVD_KARAOKE_CONTENTS | 비트 단위의 OR 처리에 대해, 가라오케 타이틀의 오디오 스트림의 각 채널의 컨텐츠를 기술하는 플래그를 지정한다.
DVD_KARAOKE_DOWNMIX | 각 보조 채널이 다운 믹스 되는 스피커가 있는 경우에 그것을 제어하기 위해서 IDvdControl2::SelectKaraokeAudioPresentationMode 메소드가 사용하는 플래그를 정의한다.
DVD_MENU_ID | DVD 비디오 타이틀 설정 (VTS) 메뉴 식별자를 지정한다.
DVD_OPTION_FLAG | DVD 컨텐츠의 재생에 관련하는 DVD 네비게이터 필터의 동작을 제어하는 플래그를 정의한다.
DVD_PARENTAL_LEVEL | DVD 규격으로 규정된 범용 페어 렌탈 락 레벨의 플래그를 식별한다.
DVD_PREFERRED_DISPLAY_MODE | 유저가 우선적으로 사용하는 윈도우의 어스펙트비(가로세로 비율)과 변환 방법을 나타낸다.
DVD_RELATIVE_BUTTON | DVD 메뉴의 네비게이션이나 그 외의 조작에 사용하는 4 개의 방향 버튼을 식별한다.
DVD_SUBPICTURE_CODING | 서브 픽쳐 스트림이 어떠한 종류의 컨텐츠를 포함하고 있는지를 나타낸다.
DVD_SUBPICTURE_LANG_EXT | 지정된 서브 픽쳐 스트림내에서 가능한 언어 확장을 정의한다.
DVD_SUBPICTURE_TYPE | 서브 픽쳐 스트림이 어떠한 종류의 컨텐츠를 포함하고 있을까를 조사하기 위한 플래그를 정의한다.
DVD_TextCharSet | 지정된 캐릭터 라인의 encode에 사용하는 ISO 캐릭터 세트를 정의한다.
DVD_TextStringType | DVD 텍스트 캐릭터 라인 타입의 서브 세트를 정의한다.
DVD_TIMECODE_FLAGS | DVD 가 재생용으로 오쏘링 된 frame rate를 나타낸다.
DVD_TITLE_APPMODE | DVD 타이틀이 가라오케 타이틀인가 어떤가를 나타낸다.
DVD_VALID_UOP_FLAG | DVD 로 현재 어느 유저 오퍼레이션 (UOP) 커멘드가 용서되고 있는지를 나타낸다.
DVD_VIDEO_COMPRESSION | 가능한 DVD 비디오 압축 타입을 정의한다.
DVD_WARNING | DVD 경고 상태를 지정한다.

VPE 에 고유의 열거형을 이하에 나타낸다.

VPE 의 열거형 | 설명
AMVP_MODE | 비디오 포토 (VP)의 각종의 모드를 지정한다.
AMVP_SELECT_FORMAT_BY | 비디오 포맷을 선택하기 위해서 VP 믹서가 사용해야 하는 조건을 지정한다.


AM_ASPECT_RATIO_MODE 열거

열거형

표시 윈도우내의 비디오 이미지의 어스펙트비(가로세로 비율)을 지정한다.

구문

typedef enum _AM_ASPECT_RATIO_MODE
{
    AM_ARMODE_STRETCHED,
    AM_ARMODE_LETTER_BOX,
    AM_ARMODE_CROP,
    AM_ARMODE_STRETCHED_AS_PRIMARY
} AM_ASPECT_RATIO_MODE;

요소

AM_ARMODE_STRETCHED
어스펙트비(가로세로 비율)의 보정을 실시하지 않는다.
AM_ARMODE_LETTER_BOX
비디오를레터박스 포맷으로 한다. 비디오가 비뚤어지지 않게, 여분의 리젼을 백그라운드 칼라로 전부 칠한다.
AM_ARMODE_CROP
비디오를 적절한 어스펙트비(가로세로 비율)에 크로핑 한다.
AM_ARMODE_STRETCHED_AS_PRIMARY
프라이머리 스트림에 현재 설정되어 있는 모드를 사용한다. 이 값은, 세칸다리스트림 에 대해서만 유효하다.

주의

AM_ARMODE_STRETCHED 멤버는, 윈도우의 사이즈 변경시에 비디오를 신축해 비디오 스트림이 표시 윈도우 전체에 표시되도록(듯이) 한다. AM_ARMODE_LETTER_BOX 멤버는, 어스펙트비(가로세로 비율)을 일정에 유지함과 동시에 윈도우의 여분의 리젼을 백그라운드 칼라로 전부 칠하는 것에 의해, 비디오의 신축이나 일그러짐을 발생시키지 않게 한다. AM_ARMODE_CROP 멤버도, 필요에 따라서 이미지를 크로핑 하는 것에 의해, 신축이 발생하지 않게 한다.

참조

IMixerPinConfig::GetAspectRatioMode ,IMixerPinConfig::SetAspectRatioMode


AM_DVD_GRAPH_FLAGS 열거

열거형

DVD 필터 그래프로 사용하는 디코더의 타입을 지정한다.

구문

enum {
    AM_DVD_HWDEC_PREFER,
    AM_DVD_HWDEC_ONLY,
    AM_DVD_SWDEC_PREFER,
    AM_DVD_SWDEC_ONLY,
    AM_DVD_NOVPE
} AM_DVD_GRAPH_FLAGS;

요소

AM_DVD_HWDEC_PREFER
최대 하드웨어 디코딩. 디폴트.
AM_DVD_HWDEC_ONLY
하드웨어 디코딩만.
AM_DVD_SWDEC_PREFER
최대 소프트웨어 디코딩.
AM_DVD_SWDEC_ONLY
소프트웨어 디코딩만.
AM_DVD_NOVPE
컴퓨터 모니터상에 비디오를 표시하지 않는다. 이 플래그는, 하드웨어 DVD-Video 디코더와 TV 접속 가능한 포토를 가지는 디스플레이 디바이스의 조합해 에 대해서만 사용하는 것. DVD-Video 를 재생 가능한 셋탑 박스 타입의 디바이스를 사용 하면, 컴퓨터 모니터는 아니고 TV 상에서 DVD 타이틀을 재생 표시할 수 있다.

주의

하드웨어 플래그 (AM_DVD_HWDEC_*)와 소프트웨어 플래그 (AM_DVD_SWDEC_*)를 조합해서는 안 된다. 다만, AM_DVD_NOVPE 는 임의의 하드웨어 플래그와 조합할 수가 있다.

참조

IDvdGraphBuilder::RenderDvdVideoVolume


AM_DVD_STREAM_FLAGS 열거

열거형

DVD 스트림 타입 (비디오, 오디오, 또는 서브 픽쳐)을 기술한다.

구문

enum {
    AM_DVD_STREAM_VIDEO,
    AM_DVD_STREAM_AUDIO,
    AM_DVD_STREAM_SUBPIC
} AM_DVD_STREAM_FLAGS;

요소

AM_DVD_STREAM_VIDEO
DVD 비디오 스트림.
AM_DVD_STREAM_AUDIO
DVD 오디오 스트림.
AM_DVD_STREAM_SUBPIC
DVD 서브 픽쳐 스트림.

참조

AM_DVD_RENDERSTATUS


AM_FILTER_MISC_FLAGS 열거

열거형

소스 또는 렌더링 필터 플래그가 들어간다.

구문

typedef enum _AM_FILTER_MISC_FLAGS {
    AM_FILTER_MISC_FLAGS_IS_RENDERER = 0x00000001,
    AM_FILTER_MISC_FLAGS_IS_SOURCE   = 0x00000002
};

요소

AM_FILTER_MISC_FLAGS_IS_RENDERER
필터는 렌더러이다.
AM_FILTER_MISC_FLAGS_IS_SOURCE
필터는 소스이다.


AM_GRAPH_CONFIG_RECONNECT_FLAGS 열거

열거형

필터 그래프를 동적으로 재생성 하면나무의 필터의 접속법을 지정한다.

구문

typedef enum _AM_GRAPH_CONFIG_RECONNECT_FLAGS {
    AM_GRAPH_CONFIG_RECONNECT_DIRECTCONNECT = 0x00000001,
    AM_GRAPH_CONFIG_RECONNECT_CACHE_REMOVED_FILTERS = 0x00000002,
    AM_GRAPH_CONFIG_RECONNECT_USE_ONLY_CACHED_FILTERS = 0x00000004
} AM_GRAPH_CONFIG_RECONNECT_FLAGS;

요소

AM_GRAPH_CONFIG_RECONNECT_DIRECTCONNECT
재접속중에, 명시적으로 요구된 필터를 제외해 추가의 필터를 그래프에 삽입하지 않는다.
AM_GRAPH_CONFIG_RECONNECT_CACHE_REMOVED_FILTERS
그래프로부터 삭제된 필터를 필터 캐쉬에 넣는다.
AM_GRAPH_CONFIG_RECONNECT_USE_ONLY_CACHED_FILTERS
추가의 필터를 그래프에 삽입할 경우에, 필터 캐쉬에 현재 들어가 있는 필터만을 사용한다.

참조

IGraphConfig::Reconnect ,IPinFlowControl::Block


AM_INTF_SEARCH_FLAGS 열거

열거형

필터 그래프 위에의 인터페이스를 검색 하면나무의, 검색 대상의 오브젝트의 타입을 지정한다.

구문

enum _AM_INTF_SEARCH_FLAGS {
    AM_INTF_SEARCH_INPUT_PIN  = 0x00000001,
    AM_INTF_SEARCH_OUTPUT_PIN = 0x00000002,
    AM_INTF_SEARCH_FILTER     = 0x00000004
};

요소

AM_INTF_SEARCH_INPUT_PIN
입력 핀을 검색한다.
AM_INTF_SEARCH_OUTPUT_PIN
출력 핀을 검색한다.
AM_INTF_SEARCH_FILTER
필터를 검색한다.

주의

플래그가 세트되어 있지 않은 경우 (디폴트), 모든 플래그의 비트마다의 OR 와 같은 동작을 가진다. 모든 필터 및 핀이 검색된다.

참조

IAMGraphStreams::FindUpstreamInterface


AM_LINE21_CCLEVEL 열거

열거형

자막 방송의 능력 레벨을 나타낸다.

구문

 typedef enum _AM_LINE21_CCLEVEL {
    AM_L21_CCLEVEL_TC2
} AM_LINE21_CCLEVEL, *PAM_LINE21_CCLEVEL ;

요소

AM_L21_CCLEVEL_TC2
능력 레벨 2.

참조

IAMLine21Decoder::GetDecoderLevel


AM_LINE21_CCSERVICE 열거

열거형

자막 방송 디코더 서비스를 나타낸다.

구문

 typedef enum _AM_LINE21_CCSERVICE {
    AM_L21_CCSERVICE_None,
    AM_L21_CCSERVICE_Caption1,
    AM_L21_CCSERVICE_Caption2,
    AM_L21_CCSERVICE_Text1,
    AM_L21_CCSERVICE_Text2,
    AM_L21_CCSERVICE_XDS,
} AM_LINE21_CCSERVICE, *PAM_LINE21_CCSERVICE ;

요소

AM_L21_CCSERVICE_None
현재의 서비스 없음.
AM_L21_CCSERVICE_Caption1
트루 캡션. 1 번째의필드 . 디폴트 서비스.
AM_L21_CCSERVICE_Caption2
제 2 언어의 캐프쇼닝. 2 번째의 필드. 보통은 사용하지 않는다.
AM_L21_CCSERVICE_Text1
1 번째의 텍스트 필드. 장래의 호환성을 위해서(때문에) 제공되고 있는 것만으로, 현시점에서는 이행되어 있지 않다.
AM_L21_CCSERVICE_Text2
2 번째의 텍스트 필드. 장래의 호환성을 위해서(때문에) 제공되고 있는 것만으로, 현시점에서는 이행되어 있지 않다.
AM_L21_CCSERVICE_XDS
확장 데이터 서비스 (XDS 또는 EDS). 장래의 호환성을 위해서(때문에) 제공되고 있는 것만으로, 현시점에서는 이행되어 있지 않다.

참조

IAMLine21Decoder::GetCurrentService ,IAMLine21Decoder::SetCurrentService


AM_LINE21_CCSTATE 열거

열거형

자막 방송 상태 (온 또는 오프)를 나타낸다.

구문

 typedef enum _AM_LINE21_CCSTATE {
    AM_L21_CCSTATE_Off,
    AM_L21_CCSTATE_On
} AM_LINE21_CCSTATE, *PAM_LINE21_CCSTATE ;

요소

AM_L21_CCSTATE_Off
자막 방송은 오프이다.
AM_L21_CCSTATE_On
자막 방송은 온이다.

참조

IAMLine21Decoder::GetServiceState ,IAMLine21Decoder::SetServiceState


AM_LINE21_DRAWBGMODE 열거

열거형

자막 방송 텍스트의 백그라운드 모드를 나타낸다.

구문

 typedef enum _AM_LINE21_DRAWBGMODE {
    AM_L21_DRAWBGMODE_Opaque,
    AM_L21_DRAWBGMODE_Transparent
} AM_LINE21_DRAWBGMODE, *PAM_LINE21_DRAWBGMODE ;

요소

AM_L21_DRAWBGMODE_Opaque
불투명 백그라운드.
AM_L21_DRAWBGMODE_Transparent
투명 백그라운드.

참조

IAMLine21Decoder::GetDrawBackgroundMode ,IAMLine21Decoder::SetDrawBackgroundMode


AM_OVERLAY_NOTIFY_FLAGS 열거

열거형

오버레이에 의해 무엇이 변경되었는지, 또는 무엇이 변경 되려고 하고 있을까에 대한 정보가 들어간다.

구문

typedef enum _AM_OVERLAY_NOTIFY_FLAGS {
    AM_OVERLAY_NOTIFY_FLAGS_VISIBLE_CHANGE = 0x00000001,
    AM_OVERLAY_NOTIFY_FLAGS_SOURCE_CHANGE   = 0x00000002,
    AM_OVERLAY_NOTIFY_FLAGS_DEST_CHANGE   = 0x00000004
};

요소

AM_OVERLAY_NOTIFY_VISIBLE_CHANGE
직사각형이 표시로부터 비표시 설정에, 또는 비표시로부터 표시 설정으로 변경되는 것을 오버레이에 통지한다.
AM_OVERLAY_NOTIFY_SOURCE_CHANGE
전송원직사각형이 변경된, 또는 변경 되려고 하고 있다.
AM_OVERLAY_NOTIFY_DEST_CHANGE
전송처 직사각형이 변경된, 또는 변경 되려고 하고 있다.

주의

IDDrawExclModeVideoCallback::OnUpdateOverlay 메소드는, 어플리케이션이 필요한 처리를 실시할 수 있도록(듯이), 이러한 플래그를 사용해 오버레이가 어떻게 변경되었는지를 나타낸다.

참조

IDDrawExclModeVideoCallback::OnUpdateOverlay


AM_PIN_CONNECTION_BLOCK_FLAGS 열거

열거형

출력 핀으로부터의 데이터 플로우를 블록 하는 방법을 지정하는 플래그를 정의한다.

구문

enum _AM_PIN_CONNECTION_BLOCK_FLAGS {
    AM_PIN_FLOW_CONTROL_BLOCK = 0x00000001,
    AM_PIN_PUSH_THROUGH_DATA = 0x00000002
};

요소

AM_PIN_FLOW_CONTROL_BLOCK
데이터 플로우를 블록 한다.
AM_PIN_PUSH_THROUGH_DATA
데이터를 필터 그래프에 건네준다.

참조

IPinFlowControl::Block


AM_PUSHSOURCE_FLAGS 열거

열거형

라이브 전송원필터의 동작을 나타낸다.

구문

enum _AM_PUSHSOURCE_FLAGS {
    AM_PUSHSOURCECAPS_INTERNAL_RM        = 0x00000001,
    AM_PUSHSOURCECAPS_NOT_LIVE           = 0x00000002,
    AM_PUSHSOURCECAPS_PRIVATE_CLOCK      = 0x00000004,
    AM_PUSHSOURCEREQS_USE_STREAM_CLOCK   = 0x00010000
};

요소

AM_PUSHSOURCECAPS_INTERNAL_RM
필터는, 독자적인 레이트 매칭 메카니즘을 사용한다. 따라서, 렌더러는 이 필터와 레이트를 일치 시키려고 해서는 안 된다.
AM_PUSHSOURCECAPS_NOT_LIVE
필터는 라이브는 아니다. 필터가 IAMPushSource 인터페이스를 공개하고 있어도 그것을 라이브 전송원으로서 취급해서는 안 된다.
AM_PUSHSOURCECAPS_PRIVATE_CLOCK
예약이 끝난 상태. 사용해서는 안 된다.
AM_PUSHSOURCEREQS_USE_STREAM_CLOCK
예약이 끝난 상태. 사용해서는 안 된다.

주의

플래그가 세트되어 있지 않은 경우 (디폴트), 전송원필터는, 라이브이므로 독자적인 레이트 매칭을 실시하지 않는다고 보여진다.


AM_SAMPLE_PROPERTY_FLAGS 열거

열거형

AM_SAMPLE2_PROPERTIES 구조체의 dwSampleFlags 및 dwStreamId 멤버의 값을 지정한다. 이러한 값은 미디어 샘플의 프로퍼티를 기술한다.

구문

enum tagAM_SAMPLE_PROPERTY_FLAGS
     { AM_SAMPLE_SPLICEPOINT        = 0x01,
       AM_SAMPLE_PREROLL            = 0x02,
       AM_SAMPLE_DATADISCONTINUITY  = 0x04,
       AM_SAMPLE_TYPECHANGED        = 0x08,
       AM_SAMPLE_TIMEVALID          = 0x10,
       AM_SAMPLE_TIMEDISCONTINUITY  = 0x40,
       AM_SAMPLE_FLUSH_ON_PAUSE     = 0x80,
       AM_SAMPLE_STOPVALID          = 0x100,
       AM_SAMPLE_ENDOFSTREAM        = 0x200,
       AM_STREAM_MEDIA              = 0,
       AM_STREAM_CONTROL            = 1
     };

요소

AM_SAMPLE_SPLICEPOINT
샘플은 스프라이스포인트이다 (전의 데이터를 참조하지 않고 디코드할 수 있다).
AM_SAMPLE_PREROLL
샘플은프리로르 샘플 이다.
AM_SAMPLE_DATADISCONTINUITY
이 샘플의 초기 데이터는 스프라이스포인트이다. 전의 샘플의 데이터는, 그 후에 이 샘플의 데이터가 계속되는 것을 상정하고 있지 않다. 상세한 것에 대하여는, 「주의」를 참조할것.
AM_SAMPLE_TYPECHANGED
샘플 타입이 변경되었다.
AM_SAMPLE_TIMEVALID
타임이 유효하다.
AM_SAMPLE_TIMEDISCONTINUITY
데이터의 타임 갭이 이 샘플의 나중에 시작된다. AM_SAMPLE2_PROPERTIES 구조체의 pbBuffer 멤버는 NULL 여도 상관없다.
AM_SAMPLE_FLUSH_ON_PAUSE
라이브 데이터만. 포즈 상태에서의 파기를 나타낸다.
AM_SAMPLE_STOPVALID
종료 타임이 유효하다.
AM_SAMPLE_ENDOFSTREAM
이 샘플의 다음에 스트림이 끝나게 되었다. 이것은, 커넬 스트리밍용으로 예약되고 있어 현시점에서 Microsoft® DirectShow® 는 이것을 사용하지 않는다.
AM_STREAM_MEDIA
보통 데이터 스트림 식별자.
AM_STREAM_CONTROL
제어 스트림 식별자. 0x7FFFFFFF 를 넘는 값은, 어플리케이션 정의의 스트림을 나타낸다.

주의

AM_SAMPLE_DATADISCONTINUITY 플래그는, 현재의 미디어 샘플내의 데이터가 전의 샘플의 데이터와 연속하고 있다고는 보여지지 않는 것을 나타낸다. AM_SAMPLE_DATADISCONTINUITY 플래그가 세트 된 샘플을 받은 필터는, 버퍼내의 미처리 데이터를 파기해서는 안 된다. 버퍼에 저장 되고 있는 데이터의 처리를 종료시키기 전에, 입력 데이터를 대기하고 있는 필터는, 버퍼에 저장 되고 있는 데이터를 즉석에서 처리해야 한다. 다만, 버퍼에 저장 된 데이터가 불완전한 경우는 파기되는 경우가 있다.

예를 들어, 비데오데콘프렛사피르타는, 2 개(살)의 완전한 압축 비디오 프레임과 1 개의 불완전한 압축 비디오 프레임을 버퍼에 가지는 경우에, AM_SAMPLE_DATADISCONTINUITY 플래그가 세트 된 미디어 샘플을 받는다. 이러한 경우, 필터는, 현재의 미디어 샘플의 데이터의 처리를 시작 하기 전에, 2 개(살)의 완전한 프레임을 압축 해제해, 불완전한 3 번째의 프레임을 파기한다.

AM_SAMPLE_DATADISCONTINUITY 플래그는, 플래시 또는 정지에 잇고 받은 최초의 샘플에 세트 된다. 게다가 소스내에서 컨텐츠가 교체되었을 때, 채널 ( 및 포맷)의 변경이 발생했을 때, 또는 스트림의 중단이 원인으로 데이터가 없어졌을 때는, AM_SAMPLE_DATADISCONTINUITY 플래그를 사용할 필요가 있다.

AM_SAMPLE_DATADISCONTINUITY 플래그는, S_OK 를 돌려주는 IMediaSample::IsDiscontinuity 메소드에 상당한다.


AM_SEEKING_SEEKING_CAPABILITIES 열거

열거형

미디어 스트림의 시크 능력을 지정한다.

구문

typedef
enum AM_SEEKING_SeekingCapabilities
    {	AM_SEEKING_CanSeekAbsolute    = 0x1,
    AM_SEEKING_CanSeekForwards        = 0x2,
    AM_SEEKING_CanSeekBackwards       = 0x4,
    AM_SEEKING_CanGetCurrentPos       = 0x8,
    AM_SEEKING_CanGetStopPos          = 0x10,
    AM_SEEKING_CanGetDuration         = 0x20,
    AM_SEEKING_CanPlayBackwards       = 0x40,
    AM_SEEKING_CanDoSegments          = 0x80,
    AM_SEEKING_Source                 = 0x100
    }   AM_SEEKING_SEEKING_CAPABILITIES;

요소

AM_SEEKING_CanSeekAbsolute
스트림은 절대 위치에 시크 할 수가 있다.
AM_SEEKING_CanSeekForwards
스트림은 순서 방향으로 시크 할 수가 있다.
AM_SEEKING_CanSeekBackwards
스트림은 역방향으로 시크 할 수가 있다.
AM_SEEKING_CanGetCurrentPos
스트림은 현재 위치에 시크 할 수가 있다.
AM_SEEKING_CanGetStopPos
스트림은 정지 위치에 시크 할 수가 있다.
AM_SEEKING_CanGetDuration
스트림은 시간폭의 합계를 돌려줄 수가 있다.
AM_SEEKING_CanPlayBackwards
스트림은 역방향으로 재생할 수가 있다.
AM_SEEKING_CanDoSegments
스트림은 심리스 루프를 실시할 수가 있다 (IMediaSeeking::SetPositions 를 참조).
AM_SEEKING_Source
예약이 끝난 상태.

참조

IMediaSeeking::GetCapabilities ,IMediaSeeking::CheckCapabilities


AM_STREAM_INFO_FLAGS 열거

열거형

AM_STREAM_INFO 구조체의 각종의 컴퍼넌트가 설정되었는지 어떠했는지를 나타낸다.

구문

typedef enum {
    AM_STREAM_INFO_START_DEFINED = 0x00000001,
    AM_STREAM_INFO_STOP_DEFINED  = 0x00000002,
    AM_STREAM_INFO_DISCARDING    = 0x00000004,
    AM_STREAM_INFO_STOP_SEND_EXTRA = 0x00000010
} AM_STREAM_INFO_FLAGS;

요소

AM_STREAM_INFO_START_DEFINED
유효한 스트림 시작 타임이 설정된 것을 나타낸다.
AM_STREAM_INFO_STOP_DEFINED
유효한 스트림 종료 타임이 설정된 것을 나타낸다.
AM_STREAM_INFO_DISCARDING
스트림의 파기가 현재 액티브한 것을 나타낸다.
AM_STREAM_INFO_STOP_SEND_EXTRA
완료시에 핀이 추가의 스트림 샘플을 송신하는 것을 나타낸다.


AMOVERLAYFX 열거

열거형

Microsoft® DirectDraw® 하드웨어 오버레이 표면에서의 이펙트를 지정한다.

구문

enum AMOVERLAYFX {
    AMOVERFX_NOFX =             0x00000000,
    AMOVERFX_MIRRORLEFTRIGHT =  0x00000002,
    AMOVERFX_MIRRORUPDOWN =     0x00000004,
    AMOVERFX_DEINTERLACE =      0x00000008
};

요소

AMOVERFX_NOFX
노멀 비디오 (이펙트 없음).
AMOVERFX_MIRRORLEFTRIGHT
수직축을 기준에 오버레이를 미러링 한다.
AMOVERFX_MIRRORUPDOWN
수평축을 기준에 오버레이를 미러링 한다.
AMOVERFX_DEINTERLACE
IAMOverlayFX::QueryOverlayFXCaps 내에서 사용할 때, 이 플래그는 하드웨어가 DirectDraw 7 DDOVERFX_DEINTERLACE 힌트를 지원 할 수 있을지 어떨지를 지정한다. GetOverlayFX 혹은 SetOverlayFX 로 사용할 때는, 이 플래그는 가능하면 오버레이는 비인터레이스여야 한다는 것을 나타낸다.

참조

IAMOverlayFX 인터페이스


AMRESCTL_RESERVEFLAGS 열거

열거형

현재 예약되고 있는 리소스의 수를 인크리먼트(increment) 또는 감소 할지 어떨지를 지정한다.

구문

enum _AMRESCTL_RESERVEFLAGS{
    AMRESCTL_RESERVEFLAGS_RESERVE     = 0x00,
    AMRESCTL_RESERVEFLAGS_UNRESERVE   = 0x01
};

요소

AMRESCTL_RESERVEFLAGS_RESERVE
예약되고 있는 리소스의 수를 인크리먼트(increment) 한다.
AMRESCTL_RESERVEFLAGS_UNRESERVE
예약되고 있는 리소스의 수를 감소 한다.


AMTunerModeType 열거

열거형

TV 튜너 (케이블 또는 안테나)의 주파수를 지정한다.

구문

typedef enum tagAMTunerModeType
    {
        AMTUNER_MODE_DEFAULT = 0x0000,
        AMTUNER_MODE_TV = 0x0001,
        AMTUNER_MODE_FM_RADIO = 0x0002,
        AMTUNER_MODE_AM_RADIO = 0x0004,
        AMTUNER_MODE_DSS = 0x0008
    } AMTunerModeType;

요소

AMTUNER_MODE_DEFAULT
디폴트 튜너 모드를 나타낸다.
AMTUNER_MODE_TV
TV 튜너 모드를 나타낸다.
AMTUNER_MODE_FM_RADIO
FM 라디오 튜너 모드를 나타낸다.
AMTUNER_MODE_AM_RADIO
AM 라디오 튜너 모드를 나타낸다.
AMTUNER_MODE_DSS
디지털 위성 서비스 (DSS) 튜너 모드를 나타낸다.


AMVP_MODE 열거

열거형

비디오 포토 (VP)의 각종의 모드를 지정한다.

구문

typedef enum _AMVP_MODE{
AMVP_MODE_WEAVE,
AMVP_MODE_BOBINTERLEAVED,
AMVP_MODE_BOBNONINTERLEAVED,
AMVP_MODE_SKIPEVEN,
AMVP_MODE_SKIPODD
} AMVP_MODE;

요소

AMVP_MODE_WEAVE
Weave .
AMVP_MODE_BOBINTERLEAVED
인터리브 Bob . 예를 들어 다음의 프레임으로 리소스를 할당해 Weave 모드로 전환할 수 있는 Bob 모드.
MODE_BOBNONINTERLEAVED
비인터리브 Bob . 리소스를 할당하지 않고 Weave 모드로 전환할 수 있는 Bob 모드.
AMVP_MODE_SKIPEVEN
짝수필드를 스킵 한다.
AMVP_MODE_SKIPODD
홀수 필드를 스킵 한다.


AMVP_SELECT_FORMAT_BY 열거

열거형

비디오 포맷을 선택하기 위해서오버레이 믹서가 사용해야 하는 조건을 지정한다.

구문

typedef enum _AMVP_SELECT_FORMAT_BY{
AMVP_DO_NOT_CARE,
AMVP_BEST_BANDWIDTH,
AMVP_INPUT_SAME_AS_OUTPUT
} AMVP_SELECT_FORMAT_BY;

요소

AMVP_DO_NOT_CARE
포맷은 고려되지 않는다.
AMVP_BEST_BANDWIDTH
최대 대역폭을 사용한다.
AMVP_INPUT_SAME_AS_OUTPUT
출력 포맷과 같은 입력 포맷을 사용한다.


AnalogVideoStandard 열거

열거형

전용선 접속 시스템 아날로그 비디오 신호의 포맷을 지정한다.

구문

 typedef enum
    {
        AnalogVideo_None       = 0x00000000
        AnalogVideo_NTSC_M     = 0x00000001,
        AnalogVideo_NTSC_M_J   = 0x00000002,
        AnalogVideo_NTSC_433   = 0x00000004,
        AnalogVideo_PAL_B      = 0x00000010,
        AnalogVideo_PAL_D      = 0x00000020,
        AnalogVideo_PAL_H      = 0x00000080,
        AnalogVideo_PAL_I      = 0x00000100,
        AnalogVideo_PAL_M      = 0x00000200,
        AnalogVideo_PAL_N      = 0x00000400,
        AnalogVideo_PAL_60     = 0x00000800,
        AnalogVideo_SECAM_B    = 0x00001000,
        AnalogVideo_SECAM_D    = 0x00002000,
        AnalogVideo_SECAM_G    = 0x00004000,
        AnalogVideo_SECAM_H    = 0x00008000,
        AnalogVideo_SECAM_K    = 0x00010000,
        AnalogVideo_SECAM_K1   = 0x00020000,
        AnalogVideo_SECAM_L    = 0x00040000,
        AnalogVideo_SECAM_L1   = 0x00080000,
        AnalogVideo_PAL_N_COMBO = 0x00100000
    } AnalogVideoStandard;

요소

AnalogVideo_None
디지털 센서
AnalogVideo_NTSC_M
75 IRE Setup
AnalogVideo_NTSC_M_J
일본. 0 IRE Setup
AnalogVideo_PAL_B
PAL_B
AnalogVideo_PAL_D
PAL_D
AnalogVideo_PAL_H
PAL_H
AnalogVideo_PAL_I
PAL_I
AnalogVideo_PAL_M
PAL_M
AnalogVideo_PAL_N
PAL_N
AnalogVideo_SECAM_B
SECAM_B
AnalogVideo_SECAM_D
SECAM_D
AnalogVideo_SECAM_G
SECAM_G
AnalogVideo_SECAM_H
SECAM_H
AnalogVideo_SECAM_K
SECAM_K
AnalogVideo_SECAM_K1
SECAM_K1
AnalogVideo_SECAM_L
SECAM_L
아르헨티나의 PAL N Combo 칼라 규격을 나타낸다.
SECAM_K1


CameraControlFlags 열거

열거형

카메라가 자동인가 수동인지를 지정한다.

구문

typedef enum{
    CameraControl_Flags_Auto    = 0x0001,
    CameraControl_Flags_Manual = 0x0002
} CameraControlFlags;

요소

CameraControl_Flags_Auto
카메라의 자동 플래그를 설정한다.
CameraControl_Flags_Manual
카메라의 수동 플래그를 설정한다.


CameraControlProperty 열거

열거형

Microsoft® DirectShow® 가 카메라의 어느 부분을 제어하는지를 지정한다.

구문

typedef enum
{
    CameraControl_Pan = 1,
    CameraControl_Tilt,
    CameraControl_Roll,
    CameraControl_Zoom,
    CameraControl_Exposure,
    CameraControl_Iris,
    CameraControl_Focus
} CameraControlProperty;

요소

CameraControl_Pan
카메라의 빵 설정을 설정 및 취득한다.
CameraControl_Tilt
카메라의 틸트를 제어한다.
CameraControl_Roll
카메라의 롤을 제어한다.
CameraControl_Zoom
카메라의 줌을 제어한다.
CameraControl_Exposure
카메라의 노출을 제어한다.
CameraControl_Iris
카메라의 조임을 제어한다.
CameraControl_Focus
카메라의 포커스를 제어한다.


CL_ELEM_FLAGS 열거

열거형

컷 리스트 요소 플래그를 나타낸다.

구문

enum CL_ELEM_FLAGS{
     CL_ELEM_FIRST,
     CL_ELEM_LAST,
     CL_ELEM_NULL,
     CL_ELEM_ALL,
     CL_ELEM_NONE};

요소

CL_ELEM_FIRST
최초의 요소.
CL_ELEM_LAST
마지막 요소.
CL_ELEM_NULL
NULL 요소.
CL_ELEM_ALL
모든 요소.
CL_ELEM_NONE
요소 없음.


CL_ELEM_STATUS 열거

열거형

컷 리스트 상태 플래그를 나타낸다.

구문

enum CL_ELEM_STATUS{
     CL_NOT_PLAYED,
     CL_PLAYING,
     CL_FINISHED,
     CL_STATE_INVALID,
     CL_STATE_MASK,
     CL_WAIT_FOR_STATE};

요소

CL_NOT_PLAYED
요소는 재생되어 있지 않다.
CL_PLAYING
요소는 재생중이다.
CL_FINISHED
요소의 재생이 종료했다.
CL_STATE_INVALID
무효인 상태.
CL_STATE_MASK
무효인 상태의 마스크 (CL_STATE_INVALID 와 같다).
CL_WAIT_FOR_STATE
대기 플래그. 입력 파라미터만.


CompressionCaps 열거

열거형

비디오 압축 능력을 나타낸다.

구문

typedef enum {
    CompressionCaps_CanQuality = 0x00000001,
    CompressionCaps_CanCrunch = 0x00000002,
    CompressionCaps_CanKeyFrame = 0x00000004,
    CompressionCaps_CanBFrame = 0x00000008,
    CompressionCaps_CanWindow = 0x0000000A
} CompressionCaps;

요소

CompressionCaps_CanQuality
비디오 압력은,IAMVideoCompression::put_Quality 및 IAMVideoCompression::get_Quality 메소드를 지원 한다.
CompressionCaps_CanCrunch
비디오 압력은, 지정된 데이터 레이트에 비디오를 압축할 수가 있다. 압력에 이 능력이 있는 경우,출력 핀 미디어 타입은,VIDEOINFOHEADER 구조체의 dwBitRate 멤버에 데이터 레이트를 포함한다. 데이터 레이트를 설정하는 유일한 방법은,dwBitRate 를 설정하는 것이다.
CompressionCaps_CanKeyFrame
비디오 압력은,IAMVideoCompression::put_KeyFrameRate 및 IAMVideoCompression::get_KeyFrameRate 메소드를 지원 한다.
CompressionCaps_CanBFrame
비디오 압력은,IAMVideoCompression::put_PFramesPerKeyFrame 및 IAMVideoCompression::get_PFramesPerKeyFrame 메소드를 지원 한다.
CompressionCaps_CanWindow
비디오 압력은,IAMVideoCompression::put_WindowSize 및 IAMVideoCompression::get_WindowSize 메소드를 지원 한다.

참조

IAMVideoCompression


DECIMATION_USAGE 열거

열거형

비디오 이미지를 작은 사이즈에 스케일 다운하기 위해서오버레이 믹서 필터가 사용하는 방법을 기술한다.

구문

typedef enum {
    DECIMATION_LEGACY,
    DECIMATION_USE_DECODER_ONLY,
    DECIMATION_USE_VIDEOPORT_ONLY,
    DECIMATION_USE_OVERLAY_ONLY,
    DECIMATION_DEFAULT
} DECIMATION_USAGE;

요소

DECIMATION_LEGACY
다음의 스텝을 어느쪽이든가 성공할 때까지 순서에 실행해, 비디오를 데시 메이션 한다.
  1. VGA 팁 위에의 오버레이 스켈러의 사용을 시도한다.
  2. 오버레이 믹서가 비디오 포토를 개입시켜 접속되고 있는 경우는, 비디오 포토 위에의 스켈러의 사용을 시도한다.
  3. 비디오 이미지를 크로핑 한다.
DECIMATION_USE_DECODER_ONLY
비디오 디코더 위에의 스켈러를 사용해 데시 메이트 한다. 실패했을 경우는, 비디오 이미지를 크로핑 한다.
DECIMATION_USE_VIDEOPORT_ONLY
비디오 포토의 스켈러를 사용해 데시 메이트 한다. 실패했을 경우는, 비디오 이미지를 크로핑 한다.
DECIMATION_USE_OVERLAY_ONLY
VGA 팁 위에의 오버레이 스켈러를 사용해 데시 메이트 한다. 실패했을 경우는, 비디오 이미지를 크로핑 한다.
DECIMATION_DEFAULT
다음의 스텝을 어느쪽이든가 성공할 때까지 순서에 실행해, 비디오를 데시 메이트 한다.
  1. 비디오 디코더 위에의 스켈러의 사용을 시도한다.
  2. VGA 팁 위에의 오버레이 스켈러의 사용을 시도한다.
  3. 오버레이 믹서가 비디오 포토를 개입시켜 접속되고 있는 경우는, 비디오 포토 위에의 스켈러의 사용을 시도한다.
  4. 비디오 이미지를 크로핑 한다.
이 모드는, 디폴트의 데시 메이션 방법이다.

참조

IAMVideoDecimationProperties


DVD_AUDIO_APPMODE 열거

열거형

IDvdInfo2::GetAudioAttributes 호출로 취득된 현재의 오디오 모드를 나타낸다.

구문

typedef enum tagDVD_AUDIO_APPMODE
{
    DVD_AudioMode_None     = 0,
    DVD_AudioMode_Karaoke  = 1,
    DVD_AudioMode_Surround = 2,
    DVD_AudioMode_Other    = 3,
} DVD_AUDIO_APPMODE;

요소

DVD_AudioMode_None
특수한 오디오 모드 없음. DVD 네비게이터는, 특별한 처리를 하지 않고 오디오를 디코더에 송신한다.
DVD_AudioMode_Karaoke
현재의 오디오 모드는 가라오케 컨텐츠이다.
DVD_AudioMode_Surround
현재의 오디오 모드는 환경 사운드이다.
DVD_AudioMode_Other
인식할 수 없는 오디오 모드.


DVD_AUDIO_FORMAT 열거

열거형

DVD 의 오디오 포맷을 나타낸다.

구문

typedef enum tagDVD_AUDIO_FORMAT
{
    DVD_AudioFormat_AC3       = 0,
    DVD_AudioFormat_MPEG1     = 1,
    DVD_AudioFormat_MPEG1_DRC = 2,
    DVD_AudioFormat_MPEG2     = 3,
    DVD_AudioFormat_MPEG2_DRC = 4,
    DVD_AudioFormat_LPCM      = 5,
    DVD_AudioFormat_DTS       = 6,
    DVD_AudioFormat_SDDS      = 7,
    DVD_AudioFormat_Other     = 8
} DVD_AUDIO_FORMAT;

요소

DVD_AudioFormat_AC3
오디오 포맷은 Dolby AC-3 이다.
DVD_AudioFormat_MPEG1
오디오 포맷은 MPEG-1 이다.
DVD_AudioFormat_MPEG1_DRC
오디오 포맷은 다이나믹 레인지 컨트롤 첨부의 MPEG-1 이다.
DVD_AudioFormat_MPEG2
오디오 포맷은 MPEG-2 이다.
DVD_AudioFormat_MPEG2_DRC
오디오 포맷은 다이나믹 레인지 컨트롤 첨부의 MPEG-2 이다.
DVD_AudioFormat_LPCM
오디오 포맷은 리니어 펄스부호변조 (LPCM)이다.
DVD_AudioFormat_DTS
오디오 포맷은 디지털 극장 시스템 (DTS)이다.
DVD_AudioFormat_SDDS
오디오 포맷은 Sony 다이나믹 디지털 사운드 (SDDS)이다.
DVD_AudioFormat_Other
오디오 포맷을 인식할 수 없다.

주의

이 열거는,DVD_AudioAttributes 구조체의 멤버이다.


DVD_AUDIO_LANG_EXT 열거

열거형

오디오 스트림이 오디오 언어 확장을 포함하고 있는지 어떤지를 나타내는 플래그를 정의한다.

구문

typedef enum tagDVD_AUDIO_LANG_EXT
{
    DVD_AUD_EXT_NotSpecified        = 0,
    DVD_AUD_EXT_Captions            = 1,
    DVD_AUD_EXT_VisuallyImpaired    = 2,
    DVD_AUD_EXT_DirectorComments1   = 3,
    DVD_AUD_EXT_DirectorComments2   = 4
} DVD_AUDIO_LANG_EXT;

요소

DVD_AUD_EXT_NotSpecified
DVD 는, 이 오디오 스트림의 오디오 언어 확장을 지정하고 있지 않다.
DVD_AUD_EXT_Captions
오디오 스트림은 캡션을 포함한다.
DVD_AUD_EXT_VisuallyImpaired
오디오 스트림은, 시력이 약한 사람용의 컨텐츠를 포함한다.
DVD_AUD_EXT_DirectorComments1
오디오 스트림은 "디렉터 코멘트 1" 를 포함한다.
DVD_AUD_EXT_DirectorComments2
오디오 스트림은 "디렉터 코멘트 2" 를 포함한다.

주의

이 열거는, (DVD_AudioAttributes 구조체의 멤버로서) IDvdInfo2::GetAudioAttributes 및 IDvdInfo2::GetDefaultAudioLanguage 메소드로 사용된다.


DVD_CMD_FLAGS 열거

열거형

DVD 네비게이터 필터가 어떻게 커멘드의 동기화를 처리하는지를 제어하는 플래그를 정의한다.

구문

typedef enum {
    DVD_CMD_FLAG_None          = 0x00000000,
    DVD_CMD_FLAG_Flush         = 0x00000001,
    DVD_CMD_FLAG_SendEvents    = 0x00000002,
    DVD_CMD_FLAG_Block         = 0x00000004,
} DVD_CMD_FLAGS;

요소

DVD_CMD_FLAG_None
새로운 커멘드가 발행되었을 때에 버퍼의 플래시를 실시하지 않는, 이벤트를 송신하지 않는, 및 메소드 호출로 실행 thread를 블록 하지 않게 DVD 네비게이터에게 지시한다.
DVD_CMD_FLAG_Flush
PlayTitle ,PlayForwards 등이 새로운 커멘드를 받았을 때, 버퍼에 현재 들어가 있는 약 2 초 상당한 비디오를 파기해 그 새로운 커멘드의 인스턴스를 즉석에서 생성 하도록(듯이), DVD 네비게이터에게 지시한다.
DVD_CMD_FLAG_SendEvents
비동기 처리가 완료하면(자) 어플리케이션에 이벤트를 송신하도록(듯이) DVD 네비게이터에게 지시한다. 이벤트 파라미터는, 처리의 반환값을 포함한다.
DVD_CMD_FLAG_Block
처리가 완료 또는 캔슬될 때까지, 비동기 처리가 블록 되도록(듯이) DVD 네비게이터에게 지시한다.


DVD_DISC_SIDE 열거

열거형

DVD 디스크의 사이드를 나타낸다.

구문

typedef enum tagDVD_DISC_SIDE {
    DVD_SIDE_A,
    DVD_SIDE_B
} DVD_DISC_SIDE;

요소

DVD_SIDE_A
사이드 A.
DVD_SIDE_B
사이드 B.

요소

이 열거는,IDVDInfo2::GetDVDVolumeInfo 메소드로 사용된다.


DVD_DOMAIN 열거

열거형

DVD 도메인을 정의한다.

구문

typedef enum tagDVD_DOMAIN {
    DVD_DOMAIN_FirstPlay,
    DVD_DOMAIN_VideoManagerMenu,
    DVD_DOMAIN_VideoTitleSetMenu,
    DVD_DOMAIN_Title,
    DVD_DOMAIN_Stop
} DVD_DOMAIN;

요소

DVD_DOMAIN_FirstPlay
DVD 디스크의 디폴트의 초기화를 실시한다.
DVD_DOMAIN_VideoManagerMenu
디스크 전체의 메뉴를 표시한다.
DVD_DOMAIN_VideoTitleSetMenu
현재의 타이틀 세트의 메뉴를 표시한다.
DVD_DOMAIN_Title
현재의 타이틀을 표시한다.
DVD_DOMAIN_Stop
DVD 네비게이터는 DVD 정지 도메인에 들어가 있다.

주의

이 열거는,IDVDInfo2::GetCurrentDomain 메소드로 사용된다.

도메인이란, DVD 디스크 위에의 논리 영역이다. 디스크의 메인 메뉴를 표시하고 있는 경우, DVD 네비게이터는 비디오 매니저 도메인에 있다고 한다. 타이틀 고유의 메뉴를 표시하고 있을 때는, 비디오 타이틀 설정 도메인에 있다고 한다. 비디오를 재생하고 있는 경우, 그것은 타이틀 도메인이다. 유저가 Stop 커멘드를 발행 하면, 네비게이터는 정지 도메인에 들어간다.


DVD_ERROR 열거

열거형

DVD 에러 상태를 지정한다.

구문

typedef enum _tagDVD_ERROR {
    DVD_ERROR_Unexpected                          = 1,
    DVD_ERROR_CopyProtectFail                     = 2,
    DVD_ERROR_InvalidDVD1_0Disc                   = 3,
    DVD_ERROR_InvalidDiscRegion                   = 4,
    DVD_ERROR_LowParentalLevel                    = 5,
    DVD_ERROR_MacrovisionFail                     = 6,
    DVD_ERROR_IncompatibleSystemAndDecoderRegions = 7,
    DVD_ERROR_IncompatibleDiscAndDecoderRegions   = 8
} DVD_ERROR;

요소

DVD_ERROR_Unexpected
예기치 않은 에러가 발생했다. 컨텐츠의 오쏘링 방법으로 잘못이 있을 가능성이 있다. 재생은 중지된다.
DVD_ERROR_CopyProtectFail
DVD 카피 보호를 위한 키 교환이 실패했다. 재생은 중지된다.
DVD_ERROR_InvalidDVD1_0Disc
규격 1. x 에 관해서 DVD-Video 디스크의 오쏘링 방법으로 잘못이 있다. 재생은 중지된다.
DVD_ERROR_InvalidDiscRegion
시스템 리젼으로 재생되도록(듯이) 디스크가 오쏘링되어 있지 않기 위해(때문에) DVD-Video 디스크를 재생할 수 없다. 리젼의 부정합은, Dvdrgn.exe 를 사용해 시스템 리젼을 변경하면 수복할 수 있다.
DVD_ERROR_LowParentalLevel
플레이어의 페어 렌탈 락 레벨이 DVD 컨텐츠로 이용 가능한 최저 페어 렌탈 락 레벨보다 낮다. 재생은 중지된다.
DVD_ERROR_MacrovisionFail
Macrovision® 디스트리뷰션이 실패했다. 재생은 중지된다.
DVD_ERROR_IncompatibleSystemAndDecoderRegions
시스템 리젼이 디코더 리젼과 일치하지 않기 때문에 디스크를 재생할 수 없다.
DVD_ERROR_IncompatibleDiscAndDecoderRegions
디코더의 리젼으로 재생되도록(듯이) 디스크가 오쏘링되어 있지 않기 위해(때문에) 디스크를 재생할 수 없다.

참조

EC_DVD_ERROR ,DVD 리젼 변경 지원 (Windows)


DVD_FRAMERATE 열거

열거형

DVD 를 1 초 쯤 25 프레임으로 재생하도록(듯이) 오쏘링 하는지, 1 초 쯤 30 프레임으로 재생하도록(듯이) 오쏘링 하는지를 나타낸다.

구문

typedef enum tagDVD_FRAMERATE
{
    DVD_FPS_25 = 1,
    DVD_FPS_30NonDrop = 3
} DVD_FRAMERATE;

요소

DVD_FPS_25
25 프레임/초.
DVD_FPS_30NonDrop
30 프레임/초.

주의

프레임 카운트를 타임으로 환산하려면 frame rate가 모르면 안 된다.


DVD_KARAOKE_ASSIGNMENT 열거

열거형

오디오 채널을 할당하는 스피커를 나타내는 플래그를 정의한다. 이 열거는,DVD_KaraokeAttributes 구조체의 멤버이다.

구문

typedef enum tagDVD_KARAOKE_ASSIGNMENT
{
    DVD_Assignment_reserved0   = 0,
    DVD_Assignment_reserved1   = 1,
    DVD_Assignment_LR    = 2,
    DVD_Assignment_LRM   = 3,
    DVD_Assignment_LR1   = 4,
    DVD_Assignment_LRM1  = 5,
    DVD_Assignment_LR12  = 6,
    DVD_Assignment_LRM12 = 7
} DVD_KARAOKE_ASSIGNMENT;

요소

DVD_Assignment_reserved0
현재는 사용되지 않는다.
DVD_Assignment_reserved1
현재는 사용되지 않는다.
DVD_Assignment_LR
채널은, 왼쪽 및 오른쪽 스피커에 할당할 수 있다.
DVD_Assignment_LRM
채널은, 좌, 우, 및 중앙 스피커에 할당할 수 있다.
DVD_Assignment_LR1
채널은, 좌, 우, 및 audio1 스피커에 할당할 수 있다.
DVD_Assignment_LRM1
채널은, 좌, 우, 중앙, 및 audio1 스피커에 할당할 수 있다.
DVD_Assignment_LR12
채널은, 좌, 우, 및 audio2 스피커에 할당할 수 있다.
DVD_Assignment_LRM12
채널은, 좌, 우, 중앙, 및 audio2 스피커에 할당할 수 있다.


DVD_KARAOKE_CONTENTS 열거

열거형

비트 단위의 OR 처리에 대해, 가라오케 타이틀의 오디오 스트림의 각 채널의 컨텐츠를 기술하는 플래그를 지정한다.

구문

typedef enum tagDVD_KARAOKE_CONTENTS
{
    DVD_Karaoke_GuideVocal1  = 0x0001,
    DVD_Karaoke_GuideVocal2  = 0x0002,
    DVD_Karaoke_GuideMelody1 = 0x0004,
    DVD_Karaoke_GuideMelody2 = 0x0008,
    DVD_Karaoke_GuideMelodyA = 0x0010,
    DVD_Karaoke_GuideMelodyB = 0x0020,
    DVD_Karaoke_SoundEffectA = 0x0040,
    DVD_Karaoke_SoundEffectB = 0x0080
} DVD_KARAOKE_CONTENTS;

요소

DVD_Karaoke_GuideVocal1
채널은 가이드 보컬 1 을 포함한다.
DVD_Karaoke_GuideVocal2
채널은 가이드 보컬 2 를 포함한다.
DVD_Karaoke_GuideMelody1
채널은 가이드 멜로디 1 을 포함한다.
DVD_Karaoke_GuideMelody2
채널은 가이드 멜로디 2 를 포함한다.
DVD_Karaoke_GuideMelodyA
채널은 가이드 멜로디 A 를 포함한다.
DVD_Karaoke_GuideMelodyB
채널은 가이드 멜로디 B 를 포함한다.
DVD_Karaoke_SoundEffectA
채널은 사운드 이펙트 A 를 포함한다.
DVD_Karaoke_SoundEffectB
채널은 사운드 이펙트 B 를 포함한다.

주의

이 열거는,DVD_KaraokeAttributes 구조체로 사용된다.


DVD_KARAOKE_DOWNMIX 열거

열거형

각 보조 채널이 다운 믹스 되는 스피커가 있는 경우에 그것을 제어하기 위해서 IDvdControl2::SelectKaraokeAudioPresentationMode 메소드가 사용하는 플래그를 정의한다.

구문

typedef enum tagDVD_KARAOKE_DOWNMIX
{
    DVD_Mix_0to0 = 0x0001,
    DVD_Mix_1to0 = 0x0002,
    DVD_Mix_2to0 = 0x0004,
    DVD_Mix_3to0 = 0x0008,
    DVD_Mix_4to0 = 0x0010,
    DVD_Mix_Lto0 = 0x0020,
    DVD_Mix_Rto0 = 0x0040,

    DVD_Mix_0to1 = 0x0100,
    DVD_Mix_1to1 = 0x0200,
    DVD_Mix_2to1 = 0x0400,
    DVD_Mix_3to1 = 0x0800,
    DVD_Mix_4to1 = 0x1000,
    DVD_Mix_Lto1 = 0x2000,
    DVD_Mix_Rto1 = 0x4000,
} DVD_KARAOKE_DOWNMIX;

요소

DVD_Mix_0to0
사용되어 있지 않다. 장래적인 사용을 위해서(때문에) 예약되고 있다.
DVD_Mix_1to0
사용되어 있지 않다. 장래적인 사용을 위해서(때문에) 예약되고 있다.
DVD_Mix_2to0
채널 2 를 왼쪽 스피커에 다운 믹스 한다.
DVD_Mix_3to0
채널 3 을 왼쪽 스피커에 다운 믹스 한다.
DVD_Mix_4to0
채널 4 를 왼쪽 스피커에 다운 믹스 한다.
DVD_Mix_Lto0
사용되어 있지 않다. 장래적인 사용을 위해서(때문에) 예약되고 있다.
DVD_Mix_Rto0
사용되어 있지 않다. 장래적인 사용을 위해서(때문에) 예약되고 있다.
DVD_Mix_0to1
사용되어 있지 않다. 장래적인 사용을 위해서(때문에) 예약되고 있다.
DVD_Mix_1to1
사용되어 있지 않다. 장래적인 사용을 위해서(때문에) 예약되고 있다.
DVD_Mix_2to1
채널 2 를 오른쪽 스피커에 다운 믹스 한다.
DVD_Mix_3to1
채널 3 을 오른쪽 스피커에 다운 믹스 한다.
DVD_Mix_4to1
채널 4 를 오른쪽 스피커에 다운 믹스 한다.
DVD_Mix_Lto1
사용되어 있지 않다. 장래적인 사용을 위해서(때문에) 예약되고 있다.
DVD_Mix_Rto1
사용되어 있지 않다. 장래적인 사용을 위해서(때문에) 예약되고 있다.

주의

오디오 채널은 제로로부터 시작된다. 따라서, 채널 2 ~ 4 는, 3 개의 보조 가라오케 채널이다. 비트 단위의 OR 처리를 사용해 적절한 비트를 설정하는 것으로써, 채널을 왼쪽 스피커 (0), 오른쪽 스피커 (1), 또는 양스피커에 송신하는 것을 지정하는지, 또는 양쪽 모두의 비트를 오프로 해 스피커를 사용하지 않는 것을 지정한다. DVD 네비게이터 필터가 가라오케 모드가 되면(자), 이러한 비트는 디폴트로 모두 오프가 된다.


DVD_MENU_ID 열거

열거형

IDVDControl2::ShowMenu 호출 중(안)에서 DVD 메뉴를 지정한다.

구문

typedef enum tagDVD_MENU_ID {
    DVD_MENU_Title      = 2,
    DVD_MENU_Root       = 3,
    DVD_MENU_Subpicture = 4,
    DVD_MENU_Audio      = 5,
    DVD_MENU_Angle      = 6,
    DVD_MENU_Chapter    = 7
} DVD_MENU_ID;

요소

DVD_MENU_Title
DVD-Video 볼륨의 탑 메뉴를 지정한다. 이 메뉴는, 타이틀 메뉴 또는 비디오 매니저 메뉴라고도 불려 디스크 위에의 모든 VTS (비디오 타이틀 세트) 메뉴에의 액세스를 제공한다.
DVD_MENU_Root
VTS 의 루트 메뉴를 지정한다.
DVD_MENU_Subpicture
VTS 메뉴의 서브 픽쳐 서브 메뉴를 지정한다.
DVD_MENU_Audio
VTS 메뉴의 오디오 서브 메뉴를 지정한다.
DVD_MENU_Angle
VTS 메뉴의 앵글 서브 메뉴를 지정한다.
DVD_MENU_Chapter
VTS 메뉴의 쳅터 서브 메뉴를 선택한다.

주의

루트 메뉴는, 서브 픽쳐, 오디오, 앵글, 및 쳅터 메뉴가 존재하는 경우에 그것들에 액세스 하는 방법을 항상 제공한다.


DVD_OPTION_FLAG 열거

열거형

디지털 비디오 디스크 (DVD) 컨텐츠의 재생에 관련하는 DVD 네비게이터 필터의 동작을 제어하는 플래그를 정의한다.

구문

typedef enum {
    DVD_ResetOnStop               = 1,
    DVD_NotifyParentalLevelChange = 2,
    DVD_HMSF_TimeCodeEvents       = 3
} DVD_OPTION_FLAG;

요소

DVD_ResetOnStop
이 플래그를 설정 하면, DVD 네비게이터는, 필터 그래프가 정지해 재기동되었을 경우에, 디스크의 선두로부터 재생을 재개한다. 이 플래그는, 디폴트로 온이다.
DVD_NotifyParentalLevelChange
디스크상에서 일시 페어 렌탈 락 레벨 커멘드를 검출하면(자) 어플리케이션에 통지하도록(듯이), DVD 네비게이터에게 지시한다. 이 플래그가 세트되어 있지 않은 경우, DVD 네비게이터는 자동적으로 그 커멘드를 거부해 분기 한다. 이 플래그는, 디폴트로 오프이다.
DVD_HMSF_TimeCodeEvents
모든 타임 코드 정보를,DVD_TIMECODE 구조체로 정의되고 있는 종래의 2 진화 10 진 (BCD) 포맷은 아니고, 새로운 DVD_HMSF_Timecode 포맷으로 송신하도록(듯이), DVD 네비게이터에게 지시한다. 이 플래그는, 디폴트로 오프이다.


DVD_PARENTAL_LEVEL 열거

열거형

DVD 규격으로 규정된 범용 페어 렌탈 락 레벨의 플래그를 식별한다.

구문

typedef enum tagDVD_PARENTAL_LEVEL
{
    DVD_PARENTAL_LEVEL_8 = 0x8000,
    DVD_PARENTAL_LEVEL_7 = 0x4000,
    DVD_PARENTAL_LEVEL_6 = 0x2000,
    DVD_PARENTAL_LEVEL_5 = 0x1000,
    DVD_PARENTAL_LEVEL_4 = 0x0800,
    DVD_PARENTAL_LEVEL_3 = 0x0400,
    DVD_PARENTAL_LEVEL_2 = 0x0200,
    DVD_PARENTAL_LEVEL_1 = 0x0100
} DVD_PARENTAL_LEVEL;

주의

DVD_PARENTAL_LEVEL_8 은 가장 제한의 어려운 레벨로, DVD_PARENTAL_LEVEL_1 는 가장 제한의 느슨한 레벨이다. 레벨의 해석 또는 사용 방법은 나라에 의해 다르다. 미국 및 캐나다에서는, 이하의 겉(표)에 나타내도록(듯이) 레벨은 Motion Picture Association of America (MPAA)의 레이팅 레벨에 대응한다.
페어 렌탈 락 레벨 | 의미
1 | 평가액은 G (일반)이다.
3 | 평가액은 PG (보호자 시중드는 사람이 바람직한다)이다.
4 | 평가액은 PG-13 (13 세 미만의 아이에게는 추천 되지 않는, 보호자 시중드는 사람이 바람직한다)이다.
6 | 평가액은 R (제한)이다.
7 | 평가액은 NC-17 (성인용)이다.

이 열거는,IDVDInfo2::GetTitleParentalLevels 메소드로 사용된다.


DVD_PREFERRED_DISPLAY_MODE 열거

열거형

유저가 우선적으로 사용하는 윈도우의 어스펙트비(가로세로 비율)과 변환 방법을 나타낸다.

구문

typedef enum tagDVD_PREFERRED_DISPLAY_MODE
{
    DISPLAY_CONTENT_DEFAULT = 0,
    DISPLAY_16x9 = 1,
    DISPLAY_4x3_PANSCAN_PREFERRED = 2,
    DISPLAY_4x3_LETTERBOX_PREFERRED = 3
} DVD_PREFERRED_DISPLAY_MODE;

요소

DISPLAY_CONTENT_DEFAULT
디폴트의 윈도우 사이즈와 컨텐츠 타입을 사용한다.
DISPLAY_16x9
16 × 9 윈도우를 사용한다.
DISPLAY_4x3_PANSCAN_PREFERRED
4 × 3 윈도우를 사용해, 가능하면빵-스캔으로 변환한다.
DISPLAY_4x3_LETTERBOX_PREFERRED
4 × 3 윈도우를 사용해, 가능하면 레터박스로 변환한다.

주의

DVD_PREFERRED_DISPLAY_MODE 는, 유저가 우선적으로 사용하는 윈도우의 어스펙트비(가로세로 비율)과 16 × 9 의 컨텐츠를 4 × 3 의 윈도우 어스펙트비(가로세로 비율)로 변환하는 방법을 나타낸다. 빵-스캔 및 레터박스 변환은, 2 개의 변환 방법이다. 크로핑 또는 신축을 실시하지 않고 표시 윈도우내에서 비디오를 가능한 한 큰 사이즈로 표시하는 방법은,레터박스 포맷에서의 표시로 불린다. 빵-스캔은, 비디오의 제작자가 정의한 파라미터를 사용해, 16 × 9 의 비디오 화면을 크로핑 해 4 × 3 의 윈도우에 표시한다.

일부의 컨텐츠는 이러한 몇개의 방법으로 밖에 표시할 수 없다고 하는 상황이 있는 것으로부터, 이 열거형은 우선적인 변환 방법을 나타낸다. 4 × 3 의 컨텐츠는, 사이드 박스화에 의해 반드시 16 × 9 윈도우에 변환된다. 이 때, 레터박스화를 사용한 16 × 9 에서 4 × 3 에의 변환으로 화면의 상하에 추가되는 흑색의 바가, 이 변환에서는 화면의 좌우에 추가된다.

이하의 겉(표)에, 실제의 컨텐츠 타입 (1 번째)과 유저의 취향의 표시 설정 (2 번째 이후)과의 사이에 사용되는 변환 방법을 나타낸다.
실제의 컨텐츠 타입 | 16 × 9 | 4 × 3 빵-스캔 | 4 × 3 레터박스
4 × 3 | 사이드 박스화 | 없음 | 없음
16 × 9 레터박스만 | 없음 | 레터박스 | 레터 삭스
16 × 9 빵-스캔만 | 없음 | 빵-스캔 | 빵-스캔
16 × 9 빵-스캔 또는 레터박스 | 없음 | 빵-스캔 | 레터박스

네이티브 윈도우 사이즈는, 항상 유저의 취향의 사이즈가 사용된다.


DVD_RELATIVE_BUTTON 열거

열거형

DVD 메뉴의 네비게이션이나 그 외의 조작에 사용하는 4 개의 방향 버튼을 식별한다.

구문

typedef enum tagDVD_RELATIVE_BUTTON {
    DVD_RELATIVE_BUTTON_Upper = 1,
    DVD_RELATIVE_BUTTON_Lower = 2,
    DVD_RELATIVE_BUTTON_Left =  3,
    DVD_RELATIVE_BUTTON_Right = 4
    } DVD_RELATIVE_BUTTON;

요소

DVD_RELATIVE_BUTTON_Upper
상 버튼.
DVD_RELATIVE_BUTTON_Lower
하 버튼.
DVD_RELATIVE_BUTTON_Left
왼쪽 버튼.
DVD_RELATIVE_BUTTON_Right
오른쪽 버튼.


DVD_SUBPICTURE_LANG_EXT 열거

열거형

지정된 서브 픽쳐 스트림내에서 가능한 언어 확장을 정의한다.

구문

typedef enum tagDVD_SUBPICTURE_LANG_EXT
{
    DVD_SP_EXT_NotSpecified     =0,
    DVD_SP_EXT_Caption_Normal   =1,
    DVD_SP_EXT_Caption_Big      =2,
    DVD_SP_EXT_Caption_Children =3,
    DVD_SP_EXT_CC_Normal        =5,
    DVD_SP_EXT_CC_Big           =6,
    DVD_SP_EXT_CC_Children      =7,
    DVD_SP_EXT_Forced           =9,
    DVD_SP_EXT_DirectorComments_Normal      =13,
    DVD_SP_EXT_DirectorComments_Big         =14,
    DVD_SP_EXT_DirectorComments_Children    =15,
} DVD_SUBPICTURE_LANG_EXT;

요소

DVD_SP_EXT_NotSpecified
언어 확장이 존재하지 않는 것을 나타낸다.
DVD_SP_EXT_Caption_Normal
지정된 스트림이 보통의 캡션을 포함하고 있는 것을 나타낸다.
DVD_SP_EXT_Caption_Big
지정된 스트림이 큰 캡션을 포함하고 있는 것을 나타낸다.
DVD_SP_EXT_Caption_Children
지정된 스트림이 어린이용의 캡션을 포함하고 있는 것을 나타낸다.
DVD_SP_EXT_CC_Normal
지정된 스트림이 보통의 자막 방송을 포함하고 있는 것을 나타낸다.
DVD_SP_EXT_CC_Big
지정된 스트림이 큰 자막 방송을 포함하고 있는 것을 나타낸다.
DVD_SP_EXT_CC_Children
지정된 스트림이 어린이용의 자막 방송을 포함하고 있는 것을 나타낸다.
DVD_SP_EXT_Forced
서브 픽쳐 스트림이 강제적으로 기동된, 즉, 어플리케이션이 서브 픽쳐 스트림을 오프로 할 수 없는 것을 나타낸다.
DVD_SP_EXT_DirectorComments_Normal
지정된 스트림이 보통 사이즈의 디렉터 코멘트를 포함하고 있는 것을 나타낸다.
DVD_SP_EXT_DirectorComments_Big
지정된 스트림이 큰 사이즈의 디렉터 코멘트를 포함하고 있는 것을 나타낸다.
DVD_SP_EXT_DirectorComments_Children
지정된 스트림이 어린이용의 디렉터 코멘트를 포함하고 있는 것을 나타낸다.


DVD_SUBPICTURE_TYPE 열거

열거형

서브 픽쳐 스트림이 어떠한 종류의 컨텐츠를 포함하고 있을까를 조사하기 위한 플래그를 정의한다.

구문

typedef enum tagDVD_SUBPICTURE_TYPE
{
    DVD_SPType_NotSpecified = 0,
    DVD_SPType_Language     = 1,
    DVD_SPType_Other        = 2,
} DVD_SUBPICTURE_TYPE;

요소

DVD_SPType_NotSpecified
DVD 는 서브 픽쳐 타입을 지정하고 있지 않다.
DVD_SPType_Language
서브 픽쳐는, 무비의 서브 타이틀이나 그 외의 텍스트등의 언어 관련의 문맥을 포함하고 있다.
DVD_SPType_Other
서브 픽쳐는, 가라오케 타이틀에 있어서의 바운싱보르등의 언어에 관계없는 컨텐츠를 포함하고 있다.


DVD_SUBPICTURE_CODING 열거

열거형

서브 픽쳐 스트림이 어떠한 종류의 컨텐츠를 포함하고 있는지를 나타낸다.

구문

typedef enum tagDVD_SUBPICTURE_CODING
{
    DVD_SPCoding_RunLength    = 0,
    DVD_SPCoding_Extended     = 1,
    DVD_SPCoding_Other        = 2,
} DVD_SUBPICTURE_CODING;

요소

DVD_SPCoding_RunLength
서브 픽쳐가 런 길이 인코딩을 사용하고 있는 것을 나타낸다.
DVD_SPCoding_Extended
서브 픽쳐가 확장 인코딩을 사용하고 있는 것을 나타낸다.
DVD_SPCoding_Other
서브 픽쳐가 다른 인코딩 스킴을 사용하고 있는 것을 나타낸다.

주의

대부분의 서브 픽쳐 스트림은, 무비의 서브 타이틀과 같은 언어 관련의 컨텐츠를 포함하고 있지만, 가라오케에 있어서의 바운싱보르 또는 그 외의 언어에 관계없는 목적으로 서브 픽쳐를 사용할 수도 있다.


DVD_TextCharSet 열거

열거형

지정된 캐릭터 라인의 encode에 사용하는 캐릭터 세트를 정의한다.

구문

enum DVD_TextCharSet {
    DVD_CharSet_Unicode                       = 0,
    DVD_CharSet_ISO646                        = 1,
    DVD_CharSet_JIS_Roman_Kanji               = 2,
    DVD_CharSet_ISO8859_1                     = 3,
    DVD_CharSet_ShiftJIS_Kanji_Roman_Katakana = 4
};

요소

DVD_CharSet_Unicode
Unicode™ 캐릭터 세트.
DVD_CharSet_ISO646
ISO 646 캐릭터 세트.
DVD_CharSet_JIS_Roman_Kanji
JIS Roman Kanji 캐릭터 세트.
DVD_CharSet_ISO8859_1
ISO 8859-1 캐릭터 세트.
DVD_CharSet_ShiftJIS_Kanji_Roman_Katakana
JIS Kanji-Roman-Katakana 캐릭터 세트.


DVD_TextStringType 열거

열거형

DVD 텍스트 캐릭터 라인 타입의 서브 세트를 정의한다.

구문

enum DVD_TextStringType {
    // 디스크 구조체 식별자 (0x00..0x0f).
    // 이것들은, 그 캐릭터 라인 타입을 사용해
    // 내용 캐릭터 라인을 정리하기 위한 하늘의 캐릭터 라인.
    DVD_Struct_Volume               = 0x01,
    DVD_Struct_Title                = 0x02,
    DVD_Struct_ParentalID           = 0x03,
    DVD_Struct_PartOfTitle          = 0x04,
    DVD_Struct_Cell                 = 0x05,
    // 스트림 (0x10..0x1f).
    DVD_Stream_Audio                = 0x10,
    DVD_Stream_Subpicture           = 0x11,
    DVD_Stream_Angle                = 0x12,
    // 스트림 (0x20..0x2f)의 채널.
    DVD_Channel_Audio               = 0x20,

    // 어플리케이션 정보.
    // 일반 (0x30..0x37).
    // 현재의 노드의 이름, 즉 볼륨 타이틀,
    // 무비 타이틀, 노래 타이틀 등을
    // (을)를 식별하기 위해서 사용된다.
    DVD_General_Name                = 0x30,
    DVD_General_Comments            = 0x31,

    // 타이틀 (0x38..0x3f).
    DVD_Title_Series                = 0x38,
    DVD_Title_Movie                 = 0x39,
    DVD_Title_Video                 = 0x3a,
    DVD_Title_Album                 = 0x3b,
    DVD_Title_Song                  = 0x3c,
    DVD_Title_Other                 = 0x3f,

    // 타이틀 (서브) (0x40..0x47).
    DVD_Title_Sub_Series            = 0x40,
    DVD_Title_Sub_Movie             = 0x41,
    DVD_Title_Sub_Video             = 0x42,
    DVD_Title_Sub_Album             = 0x43,
    DVD_Title_Sub_Song              = 0x44,
    DVD_Title_Sub_Other             = 0x47,

    // 타이틀 (오리지날) (0x48..0x4f).
    DVD_Title_Orig_Series           = 0x48,
    DVD_Title_Orig_Movie            = 0x49,
    DVD_Title_Orig_Video            = 0x4a,
    DVD_Title_Orig_Album            = 0x4b,
    DVD_Title_Orig_Song             = 0x4c,
    DVD_Title_Orig_Other            = 0x4f,

    // 그 외의 정보 (0x50..0x57).
    DVD_Other_Scene                 = 0x50,
    DVD_Other_Cut                   = 0x51,
    DVD_Other_Take                  = 0x52,

    //이하의 사용율의 낮은 카테고리는, DVD 규격
    //그리고 규정되고 있지만, DVD_TextStringType 열거
    //그럼 정의되어 있지 않다.
    // 언어.     0x58..0x5b
    // 워크.         0x5c..0x6b
    // 문자.    0x6c..0x8f
    // 데이터.         0x90..0x93
    // 가라오케.      0x94..0x9b
    // 카테고리.     0x9c..0x9f
    // 가사.       0xa0..0xa3
    // 문서.     0xa4..0xa7
    // 그 외.       0xa8..0xab
    // 예약이 끝난 상태.     0xac..0xaf
    // 관리.        0xb0..0xb7
    // 다른 관리.   0xb8..0xc0
    // 예약이 끝난 상태.     0xd0..0xdf
    // 벤더.       0xe0..0xef
    // 확장.    0xf0..0xf7
    // 예약이 끝난 상태.     0xf8..0xff
};

요소

DVD_Struct_Volume
논리 계층의 최상정도 레벨을 나타낸다. 한 면 디스크 또는 양면 디스크의 1 면의 전내용을 참조한다.
DVD_Struct_Title
다음의 DVD_Struct_Title 까지의, 1 개의 타이틀에 속하는 모든 내용 캐릭터 라인을 나타낸다.
DVD_Struct_ParentalID
다음의 캐릭터 라인의 페어 렌탈 ID 를 나타낸다.
DVD_Struct_PartOfTitle
다음의 DVD_Struct_PartOfTitle 까지의, 1 개의 쳅터에 속하는 모든 내용 캐릭터 라인을 나타낸다.
DVD_Struct_Cell
다음의 DVD_Struct_Cell 까지의, 1 개의 셀에 속하는 모든 내용 캐릭터 라인을 나타낸다. 셀은, 쳅터의 장면에서 만나도 상관없다.
DVD_Stream_Audio
다음의 내용 캐릭터 라인이 오디오 스트림을 참조할것을 나타낸다.
DVD_Stream_Subpicture
다음의 내용 캐릭터 라인이 서브 픽쳐 스트림을 참조할것을 나타낸다.
DVD_Stream_Angle
다음의 내용 캐릭터 라인이 앵글을 참조할것을 나타낸다.
DVD_Channel_Audio
다음의 내용 캐릭터 라인이 오디오 채널을 참조할것을 나타낸다.
DVD_General_Name
가장 중요한 내용 캐릭터 라인을 나타낸다. 이 타입의 캐릭터 라인은, 볼륨, 타이틀, 쳅터등의 이름을 포함해, 임의의 구조체 식별자의 뒤에 계속될 수가 있다.
DVD_General_Comments
DVD_General_Name 캐릭터 라인에 의해 기술된, 타이틀이나 쳅터 등에 관한 추가의 정보를 가지는 내용 캐릭터 라인을 식별한다. 이러한 코멘트의 섬세한 내용 또는 구조는 정의되어 있지 않다.
DVD_Title_Series
타이틀이 속하는 시리즈의 이름을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Movie
메인 무비 타이틀을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Video
비디오 타이틀명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Album
앨범 타이틀명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Song
노래 타이틀명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Other
다른 장르의 타이틀명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Sub_Series
특정의 나라전용으로 로컬라이즈 된 시리즈의 이름을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Sub_Movie
특정의 나라전용으로 로컬라이즈 된 무비 타이틀을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Sub_Video
특정의 나라전용으로 로컬라이즈 된 비디오 타이틀을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Sub_Album
특정의 나라전용으로 로컬라이즈 된 앨범 타이틀을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Sub_Song
특정의 나라전용으로 로컬라이즈 된 노래 타이틀을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Sub_Other
특정의 나라전용으로 로컬라이즈 되고 다른 장르의 타이틀의 이름을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Orig_Series
시리즈의 오리지날명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Orig_Movie
무비의 오리지날명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Orig_Video
비디오의 오리지날명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Orig_Album
앨범의 오리지날명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Orig_Song
노래의 오리지날명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Title_Orig_Other
컨텐츠의 오리지날명을 포함한 내용 캐릭터 라인을 식별한다.
DVD_Other_Scene
무비 또는 비디오의 특정의 장면에 관계하는 내용 캐릭터 라인을 식별한다.
DVD_Other_Cut
무비 또는 비디오의 특정의 컷에 관계하는 내용 캐릭터 라인을 식별한다.
DVD_Other_Take
무비 또는 비디오의 특정의 테이크에 관계하는 내용 캐릭터 라인을 식별한다.

주의

DVD_TextStringType 는,IDvdInfo2::GetDVDTextStringAsUnicode 및 IDvdInfo2::GetDVDTextStringAsNative 메소드로 돌려주어져, 지정된 텍스트 캐릭터 라인을 디스크 제작자가 어떻게 분류했는지를 식별한다. 텍스트 캐릭터 라인에 대해서는, 「DVD 텍스트 캐릭터 라인의 조작」을 참조할것.

이 열거에 대해 정의되어 있지 않은 1 개(살)의 중요한 텍스트 캐릭터 라인 타입은, 확장 소트 텍스트 캐릭터 라인 타입 0xF0 이다. 이 타입의 캐릭터 라인을 사용 하면, 플레이어에 의한 캐릭터 라인 데이터의 소트가 가능하게 된다. 이 타입에는, 일의인 숫자 또는 어순을 바꾼 전의 캐릭터 라인의 편성을 사용할 수가 있다. 예를 들어 "The Greatest Country Hits" 라는 이름을 가지는 캐릭터 라인 타입 0x30 의 뒤에 타입 0xF0 의 캐릭터 라인 "Greatest Country Hits, The" 를 계속할 수가 있다. 내용 캐릭터 라인과 같게, 소트 캐릭터 라인의 사용법은 엄밀하게 정의되어 있지 않다.


DVD_TIMECODE_FLAGS 열거

열거형

DVD 가 재생용으로 오쏘링 된 frame rate를 나타낸다.

구문

typedef enum tagDVD_TIMECODE_FLAGS {
    DVD_TC_FLAG_25fps         = 0x00000001,
    DVD_TC_FLAG_30fps         = 0x00000002,
    DVD_TC_FLAG_DropFrame     = 0x00000004,
    DVD_TC_FLAG_Interpolated  = 0x00000008,
} DVD_TIMECODE_FLAGS;

요소

DVD_TC_FLAG_25fps
디스크는, 25 프레임/초에 재생되도록(듯이) 오쏘링 되고 있다.
DVD_TC_FLAG_30fps
디스크는, 30 프레임/초에 재생되도록(듯이) 오쏘링 되고 있다.
DVD_TC_FLAG_DropFrame
디스크는, 29.97 프레임/초에 재생되도록(듯이) 오쏘링 되고 있다.
DVD_TC_FLAG_Interpolated
DVD 네비게이터 필터에 의한 디스크의 frame rate의 최선의 견적을 나타내는 값.


DVD_TITLE_APPMODE 열거

열거형

디지털 비디오 디스크 (DVD) 타이틀이 가라오케 타이틀인가 어떤가를 나타낸다. 이 열거는, 어플리케이션이 IDvdInfo2::GetTitleAttributes 메소드를 호출했을 때에 값이 넣을 수 있는 DVD_TitleAttributes 구조체의 멤버이다.

구문

typedef enum tagDVD_TITLE_APPMODE
{
    DVD_AppMode_Not_Specified = 0,
    DVD_AppMode_Karaoke  = 1,
    DVD_AppMode_Other    = 3,
} DVD_TITLE_APPMODE;

요소

DVD_AppMode_Not_Specified
디스크는, 이 타이틀에 관한 어플리케이션 모드 정보를 제공하지 않는다.
DVD_AppMode_Karaoke
타이틀은 가라오케 컨텐츠를 포함하고 있다.
DVD_AppMode_Other
타이틀은,DVD 네비게이터 필터를 인식할 수 없는 타입의 컨텐츠를 포함하고 있다. 어플리케이션은 이 타이틀을 보통의 DVD-Video 타이틀로서 취급한다.

주의

디스크상에 가라오케 타이틀을 검출 하면, DVD 네비게이터는 "가라오케 모드 " 에 들어가 오디오 디코더에 통지한다. 디코더는, 최초로 3 개의 보조 채널을 무음으로 하지 않으면 안 된다. 어플리케이션은,IDvdControl2 의 가라오케 관련 메소드를 사용해, 이러한 채널의 볼륨 및 믹싱 구성을 선택적으로 제어한다. 상세한 것에 대하여는, 「가라오케 오디오 스트림의 재생」을 참조할것.


DVD_VIDEO_COMPRESSION 열거

열거형

가능한 DVD 비디오 압축 타입을 정의한다.

구문

typedef enum tagDVD_VIDEO_COMPRESSION
{
    DVD_VideoCompression_Other  = 0,
    DVD_VideoCompression_MPEG1  = 1,
    DVD_VideoCompression_MPEG2  = 2,
} DVD_VIDEO_COMPRESSION;

요소

DVD_VideoCompression_Other
인식할 수 없는 압축 타입.
DVD_VideoCompression_MPEG1
MPEG-1 압축 타입.
DVD_VideoCompression_MPEG2
MPEG-2 압축 타입.

주의

이 열거는,IDvdInfo2::GetCurrentVideoAttributes 메소드 호출에 의해 값이 넣을 수 있는 DVD_VideoAttributes 구조체의 멤버이다.


DVD_WARNING 열거

열거형

DVD 경고 상태를 지정한다.

구문

typedef enum _tagDVD_WARNING {
    DVD_WARNING_InvalidDVD1_0Disc=1,
    DVD_WARNING_FormatNotSupported=2,
    DVD_WARNING_IllegalNavCommand=3
} DVD_WARNING;

요소

DVD_WARNING_InvalidDVD1_0Disc
DVD-Video 디스크의 오쏘링 방법으로 잘못이 있다. 재생은 속행할 수 있지만, 예기치 않은 동작이 발생할 가능성이 있다.
DVD_WARNING_FormatNotSupported
디코더는 현재의 포맷을 지원 하고 있지 않다. 스트림의 재생은 기능하지 않을 가능성이 있다.
DVD_WARNING_IllegalNavCommand
내부 DVD 네비게이션 커멘드 프로세서가 무효인 커멘드를 처리하려고 했다.

참조

EC_DVD_WARNING


DVDECODERRESOLUTION 열거

열거형

디지털 비디오 (DV)의 디코딩 해상도를 나타낸다.

구문

enum _DVDECODERRESOLUTION {
    DVDECODERRESOLUTION_720x480     =   1000,
    DVDECODERRESOLUTION_360x240     =   1001,
    DVDECODERRESOLUTION_180x120     =   1002,
    DVDECODERRESOLUTION_88x60       =   1003
};

enum _DVRESOLUTION {
    DVRESOLUTION_FULL    = 1000,
    DVRESOLUTION_HALF    = 1001,
    DVRESOLUTION_QUARTER = 1002,
    DVRESOLUTION_DC      = 1003
};

요소

DVRESOLUTION_FULL
풀 사이즈로 디코드
DVRESOLUTION_HALF
하프 사이즈로 디코드
DVRESOLUTION_QUARTER
1/4 사이즈로 디코드
DVRESOLUTION_DC
1/8 사이즈로 디코드

주의

DVDECODERRESOLUTION 열거자와 DVRESOLUTION 열거자는 등가인, DVDECODERRESOLUTION 는 기존의 어플리케이션과 호환성을 포함하고 있다.

디코드 해상도는, 현재의 포맷이 NTSC 일까 PAL 일까에 의존한다 :

열거자 | NTSC | PAL
DVRESOLUTION_FULL | 720 x 480 | 720 x 576
DVRESOLUTION_HALF | 360 x 240 | 360 x 288
DVRESOLUTION_QUARTER | 180 x 120 | 180 x 144
DVRESOLUTION_DC | 88 x 60 | 88 x 72

참조

IIPDVDec


DVENCODERFORMAT 열거

열거형

디지털 비디오 (DV) 포맷을 나타낸다.

구문

enum _DVENCODERFORMAT {
    DVENCODERFORMAT_DVSD        =   2007,
    DVENCODERFORMAT_DVHD        =   2008,
    DVENCODERFORMAT_DVSL        =   2009
};

요소

DVENCODERFORMAT_DVSD
'dvsd'스트림 핸들러를 사용한다.
DVENCODERFORMAT_DVHD
'dvhd'스트림 핸들러를 사용한다.
DVENCODERFORMAT_DVSL
'dvsl'스트림 핸들러를 사용한다.

주의

이 열거는, AVI 스트림 헤더의 fccType 멤버를 지정한다. 상세한 것에 대하여는, 「AVI 파일 포맷의 DV 데이터」를 참조할것.

참조

IDVEnc


DVENCODERRESOLUTION 열거

열거형

디지털 비디오 (DV)의 인코딩 해상도를 나타낸다.

구문

enum _DVENCODERRESOLUTION {
    DVENCODERRESOLUTION_720x480     =   2012,
    DVENCODERRESOLUTION_360x240     =   2013,
    DVENCODERRESOLUTION_180x120     =   2014,
    DVENCODERRESOLUTION_88x60       =   2015
};

요소

열거 요소의 의미는, 현재의 포맷이 NTSC 일까 PAL 일까에 따라서 다르다.

요소 | NTSC | PAL
DVENCODERRESOLUTION_720x480 | 720 x 480 | 720 x 576
DVENCODERRESOLUTION_360x240 | 360 x 240 | 360 x 288
DVENCODERRESOLUTION_180x120 | 180 x 120 | 180 x 144
DVENCODERRESOLUTION_88x60 | 88 x 66 | 88 x 72

참조

IDVEnc


DVENCODERVIDEOFORMAT 열거

열거형

디지털 비디오 (DV) 인코딩용의 비디오 규격 (NTSC 또는 PAL )을 나타낸다.

구문

enum _DVENCODERVIDEOFORMAT {
    DVENCODERVIDEOFORMAT_NTSC       =   2000,
    DVENCODERVIDEOFORMAT_PAL        =   2001
};

요소

DVENCODERVIDEOFORMAT_NTSC
NTSC
DVENCODERVIDEOFORMAT_PAL
PAL

참조

IDVEnc


FILTER_STATE 열거

열거형

필터 상태나 (IMediaControl::GetState 로부터 돌아왔을 때) 필터 그래프 상태를 지정한다.

구문

typedef enum _FilterState
{
    State_Stopped   = 0,
    State_Paused    = State_Stopped + 1,
    State_Running   = State_Paused + 1
} FILTER_STATE;

요소

State_Stopped
정지중. 필터는 데이터 처리중이 아니다.
State_Paused
포즈. 필터는 데이터의 렌더링중은 아니지만 처리중이다.
State_Running
실행중. 필터는 데이터의 처리 및 렌더링중이다.

주의

여러가지 필터 상태의 상세한 것에 대하여는, 「정지, 포즈, 및 실행」을 참조할것.


InterleavingMode 열거

열거형

비디오 프레임과 오디오 샘플을 어떻게 디스크에 기입하는지를 지정한다.

구문

  typedef enum
    {
        INTERLEAVE_NONE,
        INTERLEAVE_CAPTURE,
        INTERLEAVE_FULL
    } InterleavingMode;

요소

INTERLEAVE_NONE
입력순서에 프레임을 기입한다 (비인터리브). 다음에 파일을 재생시에 바탕으로 되돌릴 필요가 있다.
INTERLEAVE_CAPTURE
INTERLEAVE_FULL 보다 오버헤드가 적은 대체로의인터리브 . 비디오 캡춰전용.
INTERLEAVE_FULL
오디오 샘플 및 비디오 프레임의 완전한 세밀 인터리브. 오쏘링 및 재생전용.


MEDIA_SAMPLE_CONTENT 열거

열거형

MPEG-2 트랜스폴트 스트림내의 기본 스트림의 요소를 기술한다. 이 열거는 IMPEG2PIDMap 인터페이스로 사용되는, 이것은 MPEG-2 디멀티플렉서 필터의 출력 핀으로 이행 된다.

구문

typedef enum {
    MEDIA_TRANSPORT_PACKET,
    MEDIA_ELEMENTARY_STREAM,
    MEDIA_MPEG2_PSI,
    MEDIA_TRANSPORT_PAYLOAD
} MEDIA_SAMPLE_CONTENT ;

멤버

MEDIA_TRANSPORT_PACKET
처리되지 않고 파스스르 하는 완전한 트랜스폴트 스트림 패킷을 지정한다.
MEDIA_ELEMENTARY_STREAM
오디오 혹은 비디오의 PES 유료 하중을 지정한다.
MEDIA_MPEG2_PSI
PAT, PMT, CAT 혹은 프라이빗 데이터 스트림을 지정한다. 재조립이 필요하게 되지 않는 완전한 PSI 섹션이 있다.
MEDIA_TRANSPORT_PAYLOAD
PES 패킷과 같은, 축적된 TS 패킷 유료 하중을 지정한다.


MPEG2Level 열거

열거형

MPEG-2 비디오 규격에 규정된 MPEG-2 비디오 레벨을 나타낸다. (ISO13818-2)

구문

enum MPEG2Level {
    MPEG2Level_Low = 1,
    MPEG2Level_Main,
    MPEG2Level_High1440,
    MPEG2Level_High
};

요소

MPEG2Level_Low
저레벨.
MPEG2Level_Main
메인 레벨.
MPEG2Level_High1440
고레벨.
MPEG2Level_High
최고 레벨.

주의

DVD MPEG-2 비디오 디코더는, MPEG2Level_Low 또는 MPEG2Level_Main 를 지원 해야 한다.


MPEG2Profile 열거

열거형

MPEG-2 비디오 규격에 규정된 MPEG-2 비디오 프로파일을 나타낸다. (ISO13818-2)

구문

enum MPEG2Profile {
    MPEG2Profile_Simple = 1,
    MPEG2Profile_Main,
    MPEG2Profile_SNRScalable,
    MPEG2Profile_SpatiallyScalable,
    MPEG2Profile_High
};

요소

MPEG2Profile_Simple
심플.
MPEG2Profile_Main
메인.
MPEG2Profile_SNRScalable
신호대 잡음비 (SNR)가 스케이라불.
MPEG2Profile_SpatiallyScalable
공간적으로 스케이라불.
MPEG2Profile_High
하이.

주의

DVD 비디오 디코더는, MPEG2Profile_Simple 또는 MPEG2Profile_Main 를 지원 해야 한다.


PhysicalConnectorType 열거

열거형

핀의 물리 타입 (오디오 또는 비디오)을 지정한다.

구문

  typedef enum
    {
    PhysConn_Video_Tuner = 1,
    PhysConn_Video_Composite,
    PhysConn_Video_SVideo,
    PhysConn_Video_RGB,
    PhysConn_Video_YRYBY,
    PhysConn_Video_SerialDigital,
    PhysConn_Video_ParallelDigital,
    PhysConn_Video_SCSI,
    PhysConn_Video_AUX,
    PhysConn_Video_1394,
    PhysConn_Video_USB,
    PhysConn_Video_VideoDecoder,
    PhysConn_Video_VideoEncoder,
    PhysConn_Video_SCART,

    PhysConn_Audio_Tuner = 4096,
    PhysConn_Audio_Line,
    PhysConn_Audio_Mic,
    PhysConn_Audio_AESDigital,
    PhysConn_Audio_SPDIFDigital,
    PhysConn_Audio_SCSI,
    PhysConn_Audio_AUX,
    PhysConn_Audio_1394,
    PhysConn_Audio_USB,
    PhysConn_Audio_AudioDecoder,
    } PhysicalConnectorType;

요소

PhysConn_Video_Tuner
비디오의 튜너 핀을 지정한다.
PhysConn_Video_Composite
비디오의 콤퍼짓(composite) 핀을 지정한다.
PhysConn_Video_SVideo
S-Video (Y/C 비디오) 핀을 지정한다.
PhysConn_Video_RGB
비디오의 RGB 핀을 지정한다.
PhysConn_Video_YRYBY
비디오의 YRYBY (Y, R-Y, B-Y) 핀을 지정한다.
PhysConn_Video_SerialDigital
비디오의 시리얼 디지털 핀을 지정한다.
PhysConn_Video_ParallelDigital
비디오의 패러렐 디지털 핀을 지정한다.
PhysConn_Video_SCSI
비디오의 SCSI (Small Computer System Interface) 핀을 지정한다.
PhysConn_Video_AUX
비디오의 AUX (보조) 핀을 지정한다.
PhysConn_Video_1394
비디오의 IEEE 1394 핀을 지정한다.
PhysConn_Video_USB
비디오의 USB (Universal Serial Bus) 핀을 지정한다.
PhysConn_Video_VideoDecoder
비디오 디코더 핀을 지정한다.
PhysConn_Video_VideoEncoder
비디오 엔코더 핀을 지정한다.
PhysConn_Video_SCART
비디오의 SCART (Peritel) 핀을 지정한다.
PhysConn_Audio_Tuner
오디오의 튜너 핀을 지정한다.
PhysConn_Audio_Line
오디오의 라인 핀을 지정한다.
PhysConn_Audio_Mic
마이크 핀을 지정한다.
PhysConn_Audio_AESDigital
오디오의 AES/EBU (Audio Engineering Society/European Broadcast Union) 디지털 핀을 지정한다.
PhysConn_Audio_SPDIFDigital
오디오의 S/PDIF (Sony/Philips Digital Interface Format) 디지털 핀을 지정한다.
PhysConn_Audio_SCSI
오디오의 SCSI 핀을 지정한다.
PhysConn_Audio_AUX
오디오의 AUX 핀을 지정한다.
PhysConn_Audio_1394
오디오의 IEEE 1394 핀을 지정한다.
PhysConn_Audio_USB
오디오의 USB 핀을 지정한다.
PhysConn_Audio_AudioDecoder
오디오 디코더 핀을 지정한다.


PIN_DIRECTION 열거

열거형

핀의 방향을 나타낸다.

구문

typedef enum _PinDirection {
    PINDIR_INPUT,
    PINDIR_OUTPUT
} PIN_DIRECTION;

요소

PINDIR_INPUT
입력 핀 .
PINDIR_OUTPUT
출력 핀.


QualityMessageType 열거

열거형

품질 메세지 타입을 기술한다.

구문

typedef enum {
    Famine,
    Flood
} QualityMessageType;

요소

Famine
다운 스트림 필터는, 한층 더 많은 데이터를 필요로 하고 있다.
Flood
다운 스트림 필터는, 한층 더 적은 데이터를 필요로 하고 있다.


REG_PINFLAG 열거

열거형

REGFILTERPINS2 구조체의 dwFlags 멤버의 플래그를 정의한다.

구문

enum
{
    REG_PINFLAG_B_ZERO = 0x1,
    REG_PINFLAG_B_RENDERER = 0x2,
    REG_PINFLAG_B_MANY = 0x4,
    REG_PINFLAG_B_OUTPUT = 0x8
} REG_PINFLAG;

요소

REG_PINFLAG_B_ZERO
필터는, 이 핀의 제로개의 인스턴스를 가질 수가 있다.
REG_PINFLAG_B_RENDERER
필터는, 이 핀으로부터의 입력을 렌더링 한다. (입력 핀인 만큼 해당한다. 출력 핀은 이 플래그를 세트 해서는 안 된다. )
REG_PINFLAG_B_MANY
필터는, 이 핀의 인스턴스를 복수 생성 할 수가 있다.
REG_PINFLAG_B_OUTPUT
이 핀은 출력 핀이다.


REM_FILTER_FLAGS 열거

열거형

필터 그래프로부터 어떻게 필터를 삭제하는지를 지정한다.

구문

enum _REM_FILTER_FLAGS {
    REMFILTERF_LEAVECONNECTED = 0x00000001
};

요소

REMFILTERF_LEAVECONNECTED
필터를 접속한 채로 해 둔다. 디폴트에서는, 필터는 그래프로부터 삭제될 때 접속 해제된다.

참조

IGraphConfig::RemoveFilterEx


SNDDEV_ERR 열거

열거형

에러가 발생했을 때에 오디오 디바이스가 어떻게 액세스 되고 있었는지를 지정한다.

구문

typedef enum _tagSND_DEVICE_ERROR {
    SNDDEV_ERROR_Open             =1,
    SNDDEV_ERROR_Close            =2,
    SNDDEV_ERROR_GetCaps          =3,
    SNDDEV_ERROR_PrepareHeader    =4,
    SNDDEV_ERROR_UnprepareHeader  =5,
    SNDDEV_ERROR_Reset            =6,
    SNDDEV_ERROR_Restart          =7,
    SNDDEV_ERROR_GetPosition      =8,
    SNDDEV_ERROR_Write            =9,
    SNDDEV_ERROR_Pause            =10,
    SNDDEV_ERROR_Stop             =11,
    SNDDEV_ERROR_Start            =12,
    SNDDEV_ERROR_AddBuffer        =13,
    SNDDEV_ERROR_Query            =14,
    } SNDDEV_ERR;

요소

SNDDEV_ERROR_Open
오디오 디바이스를 열려 하고 있었다.
SNDDEV_ERROR_Close
오디오 디바이스를 닫으려 하고 있었다.
SNDDEV_ERROR_GetCaps
기초가 되고 있는 하드웨어의 능력의 취득중에서 만났다.
SNDDEV_ERROR_PrepareHeader
오디오 디바이스의 헤더의 준비중이었다.
SNDDEV_ERROR_UnprepareHeader
오디오 디바이스의 헤더의 준비를 하지 않았었다.
SNDDEV_ERROR_Reset
오디오 디바이스의 리셋을 실시하려 하고 있었다.
SNDDEV_ERROR_Restart
오디오 디바이스의 재기동을 실시하려 하고 있었다.
SNDDEV_ERROR_GetPosition
현재 위치 및 정지 위치 설정의 취득중에서 만났다.
SNDDEV_ERROR_Write
오디오 디바이스에의 기입해 안이었다.
SNDDEV_ERROR_Pause
오디오 디바이스가 포즈 하려고 하고 있었다.
SNDDEV_ERROR_Stop
오디오 디바이스가 정지하려고 하고 있었다.
SNDDEV_ERROR_Start
오디오 디바이스가 기동하려고 하고 있었다.
SNDDEV_ERROR_AddBuffer
오디오 디바이스에 버퍼를 추가하려고 하고 있었다.
SNDDEV_ERROR_Query
오디오 디바이스에의 문의를 하고 있었다.


StreamControlState 열거

열거형

스트림 상태를 지정한다.

구문

enum StreamControlState {
      STREAM_FLOWING,
      STREAM_DISCARDING
    };

요소

STREAM_FLOWING
현재 스트림이 데이터를 전송 하고 있는 것을 나타낸다.
STREAM_DISCARDING
샘플을 받을 때 마다 파기한다.


TunerInputType 열거

열거형

TV 튜너 (케이블 또는 안테나)의 주파수를 지정한다.

구문

typedef enum
    {
        TunerInputCable,
        TunerInputAntenna
    } TunerInputType;

요소

TunerInputCable
케이블의 주파수를 나타낸다.
TunerInputAntenna
브로드캐스트 안테나의 주파수를 나타낸다.


TVAudioMode 열거

열거형

TV 오디오 제어의 모드를 지정한다.

구문

typedef enum tagTVAudioMode
    {
        AMTVAUDIO_MODE_MONO	    = 0x0001,
        AMTVAUDIO_MODE_STEREO       = 0x0002,
        AMTVAUDIO_MODE_LANG_A       = 0x0010,
        AMTVAUDIO_MODE_LANG_B       = 0x0020,
        AMTVAUDIO_MODE_LANG_C       = 0x0040,
    } TVAudioMode;

요소

AMTVAUDIO_MODE_MONO
오디오가 단청의인 것을 지정한다.
AMTVAUDIO_MODE_STEREO
오디오가 스테레오인 것을 지정한다.
AMTVAUDIO_MODE_LANG_A
오디오가 추가 언어인 것을 지정한다. 「주의」를 참조할것.
AMTVAUDIO_MODE_LANG_B
오디오가 추가 언어인 것을 지정한다. 「주의」를 참조할것.
AMTVAUDIO_MODE_LANG_C
오디오가 추가 언어인 것을 지정한다. 「주의」를 참조할것.

주의

일본등의 특정의 나라에 있어 2 개국어 TV 오디오를 사용하는 경우, 요소는 다음과 같이 정의된다.

요소 | 설명
AMTVAUDIO_MODE_LANG_A | 주다언어 오디오 프로그램.
AMTVAUDIO_MODE_LANG_B | 부다언어 오디오 프로그램.
AMTVAUDIO_MODE_LANG_C | 제 3 언어, 또는 주다언어 오디오 프로그램과 부다언어 오디오 프로그램. 예를 들어, 이 요소를 사용해 영어와 일본어를 다른 스피커로부터 출력한다.


VALID_UOP_FLAG 열거

열거형

DVD 로 현재 어느 유저 오퍼레이션 (UOP) 커멘드가 용서되고 있는지를 나타낸다. 이 열거는,IDvdInfo2::GetCurrentUOPS 메소드로 사용된다.

구문

typedef enum {

    UOP_FLAG_Play_Title_Or_AtTime           = 0x00000001,
    UOP_FLAG_Play_Chapter                   = 0x00000002,
    UOP_FLAG_Play_Title                     = 0x00000004,
    UOP_FLAG_Stop                           = 0x00000008,
    UOP_FLAG_ReturnFromSubMenu              = 0x00000010,
    UOP_FLAG_Play_Chapter_Or_AtTime         = 0x00000020,
    UOP_FLAG_PlayPrev_Or_Replay_Chapter     = 0x00000040,
    UOP_FLAG_PlayNext_Chapter               = 0x00000080,
    UOP_FLAG_Play_Forwards                  = 0x00000100,
    UOP_FLAG_Play_Backwards                 = 0x00000200,
    UOP_FLAG_ShowMenu_Title                 = 0x00000400,
    UOP_FLAG_ShowMenu_Root                  = 0x00000800,
    UOP_FLAG_ShowMenu_SubPic                = 0x00001000,
    UOP_FLAG_ShowMenu_Audio                 = 0x00002000,
    UOP_FLAG_ShowMenu_Angle                 = 0x00004000,
    UOP_FLAG_ShowMenu_Chapter               = 0x00008000,
    UOP_FLAG_Resume                         = 0x00010000,
    UOP_FLAG_Select_Or_Activate_Button      = 0x00020000,
    UOP_FLAG_Still_Off                      = 0x00040000,
    UOP_FLAG_Pause_On                       = 0x00080000,
    UOP_FLAG_Select_Audio_Stream            = 0x00100000,
    UOP_FLAG_Select_SubPic_Stream           = 0x00200000,
    UOP_FLAG_Select_Angle                   = 0x00400000,
    UOP_FLAG_Select_Karaoke_Audio_Presentation_Mode = 0x00800000,
    UOP_FLAG_Select_Video_Mode_Preference   = 0x01000000
} VALID_UOP_FLAG ;

요소

UOP_FLAG_Play_Title_Or_AtTime
Annex J 커멘드명 : Title_Or_Time_Play
UOP_FLAG_Play_Chapter
Annex J 커멘드명 : Chapter_Search_Or_Play
UOP_FLAG_Play_Title
Annex J 커멘드명 : Title_Play
UOP_FLAG_Stop
Annex J 커멘드명 : Stop
UOP_FLAG_ReturnFromSubMenu
Annex J 커멘드명 : GoUp
UOP_FLAG_ReturnFromSubMenu
Annex J 커멘드명 : Time_Or_Chapter_Search
UOP_FLAG_PlayPrev_Or_Replay_Chapter
Annex J 커멘드명 : Prev_Or_Top_PG_Search
UOP_FLAG_PlayNext_Chapter
Annex J 커멘드명 : Next_PG_Search
UOP_FLAG_Play_Forwards
Annex J 커멘드명 : Forward_Scan
UOP_FLAG_Play_Backwards
Annex J 커멘드명 : Backward_Scan
UOP_FLAG_ShowMenu_Title
Annex J 커멘드명 : Title_Menu_Call
UOP_FLAG_ShowMenu_Root
Annex J 커멘드명 : Root_Menu_Call
UOP_FLAG_ShowMenu_SubPic
Annex J 커멘드명 : SubPic_Menu_Call
UOP_FLAG_ShowMenu_Audio
Annex J 커멘드명 : Audio_Menu_Call
UOP_FLAG_ShowMenu_Angle
Annex J 커멘드명 : Angle_Menu_Call
UOP_FLAG_ShowMenu_Chapter
Annex J 커멘드명 : Chapter_Menu_Call
UOP_FLAG_Resume
Annex J 커멘드명 : Resume
UOP_FLAG_Select_Or_Activate_Button
Annex J 커멘드명 : Button_Select_Or_Activate
UOP_FLAG_Still_Off
Annex J 커멘드명 : Still_Off
UOP_FLAG_Pause_On
Annex J 커멘드명 : Pause_On
UOP_FLAG_Select_Audio_Stream
Annex J 커멘드명 : Audio_Stream_Change
UOP_FLAG_Select_SubPic_Stream
Annex J 커멘드명 : SubPic_Stream_Change
UOP_FLAG_Select_Angle
Annex J 커멘드명 : Angle_Change
UOP_FLAG_Select_Karaoke_Audio_Presentation_Mode
Annex J 커멘드명 : Karaoke_Audio_Pres_Mode_Change
UOP_FLAG_Select_Video_Mode_Preference
Annex J 커멘드명 : Video_Pres_Mode_Change


VfwCaptureDialogs 열거

열거형

Video for Windows 의 캡춰 드라이버에 존재 가능한 다이알로그 박스를 지정한다.

구문

 typedef enum {
    VfwCaptureDialog_Source = 1,
    VfwCaptureDialog_Format = 2,
    VfwCaptureDialog_Display = 4
} VfwCaptureDialogs;

요소

VfwCaptureDialog_Source
비디오 소스 다이알로그 박스.
VfwCaptureDialog_Format
비디오 포맷 다이알로그 박스.
VfwCaptureDialog_Display
비디오 디스플레이 다이알로그 박스.

주의

IAMVfwCaptureDialogs 인터페이스는 이 열거 데이터형을 사용한다.


VfwCompressDialogs 열거

열거형

Video for Windows 의 압축 (CODEC) 드라이버에 존재 가능한 다이알로그 박스를 지정한다.

구문

typedef enum {
    VfwCompressDialog_Config = 1,
    VfwCompressDialog_About = 2,
    VfwCompressDialog_QueryConfig = 4,
    VfwCompressDialog_QueryAbout = 8
} VfwCompressDialogs;

요소

VfwCompressDialog_Config
[Configure] 다이알로그 박스.
VfwCompressDialog_About
[About] 다이알로그 박스.
VfwCompressDialog_QueryConfig
[Configure] 다이알로그 박스가 이용 가능한가 어떤가를 지정한다.
VfwCompressDialog_QueryAbout
[About] 다이알로그 박스가 이용 가능한가 어떤가를 지정한다.

주의

IAMVfwCompressDialogs 인터페이스는 이 열거 데이터형을 사용한다.


VideoControlFlags 열거

열거형

비디오 디바이스의 동작 비디오 모드를 지정한다.

구문

typedef enum tagVideoControlFlags
{
    VideoControlFlag_FlipHorizontal        = 0x0001,
    VideoControlFlag_FlipVertical          = 0x0002,
    VideoControlFlag_ExternalTriggerEnable = 0x0004,
    VideoControlFlag_Trigger               = 0x0008
} VideoControlFlags;

요소

VideoControlFlag_FlipHorizontal
픽쳐를 수평 방향으로 플립 하는 것을 지정한다.
VideoControlFlag_FlipVertical
픽쳐를 수직 방향으로 플립 하는 것을 지정한다.
VideoControlFlag_ExternalTriggerEnable
외부 소스 (예를 들어 카메라의 누르는 보턴)로부터 캡춰를 방아쇠 하기 위해서 스트림을 셋업 한다. 버퍼는 드라이버의 큐에 넣을 수가 있지만, 외부 이벤트가 발생할 때까지는 WDM 캡춰 드라이버 (파일의 압축, 표시, 또는 기입의 경우)로부터 건네받지 않는다. 「주의」를 참조할것.
VideoControlFlag_Trigger
스트림에 VideoControlFlag_ExternalTriggerEnable 플래그가 세트 되고 있을 때, 소프트웨어로 외부 방아쇠를 시뮬레이트 한다.

주의

IAMVideoControl 인터페이스는 이 열거 데이터형을 사용한다.

복수의 캡춰 버퍼는 캡춰 드라이버의 큐에 넣어져 스트림이 "실행 " 상태가 되면(자) 고정 레이트로 값이 넣을 수 있다. VideoControlFlag_ExternalTriggerEnable 플래그가 세트 되고 있는 경우, 값이 넣을 수 있던 버퍼는 외부 이벤트가 발생할 때까지는 WDM 캡춰 드라이버 (파일의 압축, 표시, 또는 기입의 경우)로부터 건네받지 않는다.


VideoProcAmpFlags 열거

열거형

비디오 프로퍼티의 설정 방법법을 지정한다.

구문

typedef enum tagVideoProcAmpFlags
    {
        VideoProcAmp_Flags_Manual = 0x0000,
        VideoProcAmp_Flags_Auto   = 0x0001,
    } VideoProcAmpFlags;

요소

VideoProcAmp_Flags_Manual
수동으로 프로퍼티를 설정한다.
VideoProcAmp_Flags_Auto
자동 설정을 사용한다.

주의

IAMVideoProcAmp 인터페이스는 이 열거 데이터형을 사용한다.


VideoProcAmpProperty 열거

열거형

비디오 프로퍼티를 지정한다.

구문

typedef enum tagVideoProcAmpProperty
    {
        VideoProcAmp_Brightness,
        VideoProcAmp_Contrast,
        VideoProcAmp_Hue,
        VideoProcAmp_Saturation,
        VideoProcAmp_Sharpness,
        VideoProcAmp_Gamma,
        VideoProcAmp_ColorEnable,
        VideoProcAmp_WhiteBalance,
        VideoProcAmp_BacklightCompensation,
        VideoProcAmp_Gain
    } VideoProcAmpProperty;

요소

VideoProcAmp_Brightness
휘도.
VideoProcAmp_Contrast
콘트라스트.
VideoProcAmp_Hue
색상 .
VideoProcAmp_Saturation
채도 .
VideoProcAmp_Sharpness
샤프니스.
VideoProcAmp_Gamma
감마 .
VideoProcAmp_ColorEnable
색.
VideoProcAmp_WhiteBalance
화이트 밸런스 .
VideoProcAmp_BacklightCompensation
백 라이트 보정.
VideoProcAmp_Gain
게인 조정.

참조

IAMVideoProcAmp


정수와 GUID

여기에서는, Microsoft® DirectShow® 로 정의되고 있는 정수와 글로벌 유니크 식별자 (GUID)에 대해 설명한다.

  • DVD 이벤트 통지 코드
  • 에러 및 성공 코드
  • 이벤트 통지 코드
  • 필터의 카테고리
  • 미디어 타입
  • 메리트
  • 타임 포맷 GUID

참조

  • 필터 클래스 식별자 (CLSIDs): 「필터」를 참조.
  • 다른 컴퍼넌트 CLSID: 「DirectShow 의 컴퍼넌트」를 참조.
  • 내부 식별자 (IID): 모든 DirectShow IID 는, IID_InterfaceName 포맷이다. 예를 들어,IGraphBuilder 인터페이스의 IID 는 IID_IGraphBuilder 이다.


DVD 이벤트 통지 코드

주 : 이 개요 설명은, C++ 개발자만을 대상으로 하고 있다.

Microsoft® DirectShow® 에서는, 필터 그래프내의 필터가 필터 그래프 매니저에 건네주는, 시스템 정의 이벤트를 지원 하고 있다. 필터는,IMediaEventSink::Notify 메소드를 사용해 이러한 이벤트를 필터 그래프 매니저에 건네주어, 어플리케이션은 IMediaEvent::GetEvent 메소드를 사용해 이러한 이벤트를 취득한다.

GetEvent 를 호출해 이벤트를 취득 하면 와, 이벤트는 인터페이스 포인터 또는 할당할 수 있고 있는 메모리에의 포인터를 포함할 수가 있다. 따라서,GetEvent 를 사용하는 코드는, 이벤트의 처리가 끝난 다음에 IMediaEvent::FreeEventParams 를 사용해 이벤트의 파라미터에 관련 붙일 수 있어 모든 리소스를 해방할 필요가 있다.

DVD 이벤트 통지 코드는,Dvdevcod.h 에 기술되고 있다. 비 DVD 이벤트 통지 코드에 대해서는, 「이벤트 통지 코드」를 참조할것. 이하에, DVD 이벤트 통지 코드를 알파벳순서에 나타낸다.
DVD 이벤트 통지 코드 | 설명
EC_DVD_ANGLE_CHANGE | 이용 가능한 앵글의 수 또는 현재의 앵글수가 변경된 것을 통지한다.
EC_DVD_ANGLES_AVAILABLE | 앵글 블록이 재생중으로 앵글의 변경이 가능한가 어떤가를 나타낸다.
EC_DVD_AUDIO_STREAM_CHANGE | 메인 타이틀에 대해서 현재의 오디오 스트림 번호가 변경된 것을 통지한다.
EC_DVD_BUTTON_AUTO_ACTIVATED | 디스크 위에의 명령에 의해 메뉴 버튼이 자동적으로 액티브하게 된 것을 통지한다.
EC_DVD_BUTTON_CHANGE | 이용 가능한 버튼의 수가 변경된, 또는 현재 선택되고 있는 버튼의 번호가 변경된 것을 통지한다.
EC_DVD_CHAPTER_AUTOSTOP | IDvdControl2::PlayChaptersAutoStop 메소드 호출에 의해 재생이 중지된 것을 통지한다.
EC_DVD_CHAPTER_START | DVD 네비게이터가 현재의 타이틀의 새로운 쳅터의 재생을 시작 한 것을 통지한다.
EC_DVD_CMD_START | 특정의 커멘드가 시작 된 것을 통지한다.
EC_DVD_CMD_END | 특정의 커멘드가 완료한 것을 통지한다.
EC_DVD_CURRENT_HMSF_TIME | . 4 ~ 1.0 초 마다 발생하는 모든 VOBU 의 선두에서의 현재의 타임을 DVD_HMSF_TIMECODE 포맷으로 통지한다.
EC_DVD_CURRENT_TIME | 0.4 ~ 1.0 초의 길이를 가지는 비디오 세그먼트(segment)인 비디오 오브젝트 단위 (VOBU)의 시작을 모두 통지한다.
EC_DVD_DISC_EJECTED | 디스크가 드라이브로부터 꺼내진 것을 통지한다.
EC_DVD_DISC_INSERTED | 디스크가 드라이브에 삽입된 것을 통지한다.
EC_DVD_DOMAIN_CHANGE | DVD 네비게이터의 새로운 도메인을 나타낸다.
EC_DVD_ERROR | DVD 에러 상태를 통지한다.
EC_DVD_KARAOKE_MODE | 네비게이터가 가라오케 데이터의 재생을 시작 또는 종료한 것을 나타낸다.
EC_DVD_NO_FP_PGC | DVD 디스크의 포맷이 FP_PGC (First Play Program Chain)가 아닌 것을 나타낸다.
EC_DVD_PARENTAL_LEVEL_CHANGE | 오쏘링 된 컨텐츠의 페어 렌탈 락 레벨이 변경 되려고 하고 있는 것을 통지한다.
EC_DVD_PLAYBACK_RATE_CHANGE | 재생 레이트의 변경이 시작 되어 새로운 레이트가 파라미터로 지정되고 있는 것을 나타낸다.
EC_DVD_PLAYBACK_STOPPED | 재생이 중지된 것을 나타낸다. DVD 네비게이터는 타이틀의 재생을 완료해, 이후의 재생에 대한 분기 명령을 검출하지 않았다.
EC_DVD_PLAYPERIOD_AUTOSTOP | PlayPeriodInTitleAutoStop 호출로 지정된 세그먼트(segment)의 재생을 네비게이터가 완료한 것을 나타낸다.
EC_DVD_STILL_OFF | 정지의 마지막을 통지한다.
EC_DVD_STILL_ON | 정지의 시작을 통지한다.
EC_DVD_SUBPICTURE_STREAM_CHANGE | 메인 타이틀에 대해서 현재의 서브 픽쳐 스트림 번호가 변경된 것을 통지한다.
EC_DVD_TITLE_CHANGE | 현재의 타이틀 번호가 변경된 것을 나타낸다.
EC_DVD_VALID_UOPS_CHANGE | 이용 가능한 IDVDControl2 인터페이스 메소드세트가 변경된 것을 통지한다.
EC_DVD_WARNING | DVD 경고 상태를 통지한다.

EC_DVD_ANGLE_CHANGE

DVD 이벤트 통지 코드

이용 가능한 앵글의 수 또는 현재의 앵글수가 변경된 것을 통지한다.

파라미터

lParam1
이용 가능한 앵글의 수를 나타내는 DWORD 값. 이용 가능한 앵글의 수가 1 의 경우, 현재의 비디오는 다각도는 아니다.
lParam2
현재의 앵글 번호를 나타내는 DWORD 값.

주의

앵글 번호는, 1 ~ 9 의 값으로 나타난다.

현재의 앵글 번호는, 디스크상에서 오쏘링 된 네비게이션 커멘드에 의해 자동적으로 변경할 수가 있다. 또,IDVDControl2 인터페이스를 사용해 어플리케이션으로 제어할 수도 있다.

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_ANGLES_AVAILABLE

DVD 이벤트 통지 코드

앵글 블록이 재생중에서 앵글의 변경이 가능인 제발을 나타낸다.

파라미터

lParam1
앵글 블록이 재생중인가 어떤가를 나타내는 불 (BOOL) 값. 제로 (0)는, 재생이 앵글 블록내는 아니기 때문에 앵글을 이용할 수 없는 것을 나타낸다. 1 은, 앵글 블록이 재생중이며, 앵글의 변경이 가능한 것을 나타낸다.
lParam2
제로.

주의

앵글의 변경은 앵글 블록에 한정되어 않지만, 앵글의 변경의 명시는 앵글 블록내에서만 볼 수가 있다.

EC_DVD_AUDIO_STREAM_CHANGE

DVD 이벤트 통지 코드

메인 타이틀에 대해서 현재의 오디오 스트림 번호가 변경된 것을 통지한다.

파라미터

lParam1
새로운 유저 오디오 스트림 번호를 나타내는 DWORD 값. 오디오 스트림 번호는, 0 ~ 7 의 값으로 나타난다. 스트림 0xFFFFFFFF 는, 스트림이 선택되어 있지 않은 것을 나타낸다.
lParam2
제로.

주의

현재의 오디오 스트림은, 디스크상에서 오쏘링 된 네비게이션 커멘드에 의해 자동적으로 변경할 수가 있다. 또,IDVDControl2 인터페이스를 사용해 어플리케이션으로 제어할 수도 있다.

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_BUTTON_AUTO_ACTIVATED

DVD 이벤트 통지 코드

디스크 위에의 명령에 의해 메뉴 버튼이 자동적으로 액티브하게 된 것을 통지한다. 이 동작은, 메뉴가 타임 아웃 하면 디스크 위에의 특정의 버튼이 자동적으로 액티브하게 되도록(듯이) 지정되고 있는 경우에 발생한다.

파라미터

lParam1
액티브하게 된 버튼을 나타내는 DWORD 값.
lParam2
제로.

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_BUTTON_CHANGE

DVD 이벤트 통지 코드

이용 가능한 버튼의 수가 변경된, 또는 현재 선택되고 있는 버튼의 번호가 변경된 것을 통지한다.

파라미터

lParam1
이용 가능한 버튼의 수를 나타내는 DWORD 값.
lParam2
현재 선택되고 있는 버튼 번호를 나타내는 DWORD 값. 제로의 경우, 버튼이 선택되어 있지 않은 것을 암시한다.

주의

버튼 번호는, 1 ~ 36 의 값으로 나타난다.

현재 선택되고 있는 버튼 번호는, 디스크상에서 오쏘링 된 네비게이션 커멘드에 의해 자동적으로 변경할 수가 있다. 또,IDVDControl2 인터페이스를 사용해 어플리케이션으로 제어할 수도 있다.

이 이벤트는, 임의의 이용 가능한 버튼 번호를 통지할 수가 있다. 이러한 번호는, 버튼의 서브 세트만을 액티브하게 할 수가 있는 IDvdControl::SelectAndActivateButton 로 사용되는 버튼 번호와는 반드시 대응하지 않는다.

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_CHAPTER_AUTOSTOP

DVD 이벤트 통지 코드

IDvdControl::PlayChaptersAutoStop 메소드 호출에 의해 재생이 중지된 것을 통지한다.

파라미터

lParam1
Zero.
lParam2
Zero.

주의

이 이벤트는, 타이틀 도메인으로 발생한다.

EC_DVD_CHAPTER_START

DVD 이벤트 통지 코드

DVD 플레이어가 DVD_DOMAIN_Title 도메인내의 새로운 프로그램의 재생을 시작 한 것을 통지한다.

파라미터

lParam1
새로운 쳅터 (프로그램) 번호를 나타내는 DWORD 값.
lParam2
제로.

주의

단순한 리니어 무비만이 이 이벤트를 통지한다.

이 이벤트는, 타이틀 도메인으로 발생한다.

EC_DVD_CMD_START

DVD 이벤트 통지 코드

특정의 커멘드가 시작 된 것을 통지한다.

파라미터

lParam1
커멘드 ID 및 HRESULT 반환값.
lParam2
제로.

주의

이 이벤트는, 어플리케이션이 몇개의 IDVDControl2::Play... 메소드의 DVD_CMD_FLAG_SendEvents 플래그를 세트 했을 경우에게만 발생한다. 상세한 것에 대하여는 「DVD 커멘드의 동기화」를 참조할것.

이 이벤트는, 타이틀 도메인으로 발생한다.

EC_DVD_CMD_END

DVD 이벤트 통지 코드

특정의 커멘드가 완료한 것을 통지한다.

파라미터

lParam1
커멘드 ID 및 완료 결과.
lParam2
제로.

주의

이 이벤트는, 어플리케이션이 몇개의 IDVDControl2::Play... 메소드의 DVD_CMD_FLAG_SendEvents 플래그를 세트 했을 경우에게만 발생한다. 상세한 것에 대하여는 「DVD 커멘드의 동기화」를 참조할것.

이 이벤트는, 타이틀 도메인으로 발생한다.

EC_DVD_CURRENT_HMSF_TIME

DVD 이벤트 통지 코드

타이틀의 시작시를 기준으로 한 현재의 타임을 DVD_HMSF_TIMECODE 포맷으로 통지한다. 이 이벤트는, 0.4 ~ 1.0 초간격으로 발생하는 VOBU 의 시작 마다 발생한다.

파라미터

lParam1
DVD_HMSF_TIMECODE 구조체를 포함한 ULONG 값. lParam1 를 ULONG 변수에 대입해, 그 변수를 DVD_HMSF_TIMECODE 에 캐스트 해 값에 액세스 한다.
lParam2
DVD_TIMECODE_FLAGS 의 공용체를 포함한 ULONG 값.

주의

DVD_HMSF_TIMECODE 포맷은, EC_DVD_CURRENT_TIME 이벤트로 돌려주어지는 낡은 BCD 포맷 대신에 사용한다. HMSF 타임 코드는 조작이 간단하다. EC_DVD_CURRENT_TIME 이벤트 대신에 네비게이터에게 EC_DVD_CURRENT_HMSF_TIME 이벤트를 송신시키기 위해서(때문에)는, 어플리케이션은 IDVDControl2::SetOption(DVD_HMSF_TimeCodeEvents, TRUE) 를 호출할 필요가 있다. 이 플래그를 세트 했을 경우, 네비게이터는 IDVDControl2 및 IDVDInfo2 메소드내의 모든 타임 파라미터가 DVD_HMSF_TIMECODE 로서 건네받는 것을 상정한다.

이 이벤트는, 타이틀 도메인으로 발생한다.

EC_DVD_CURRENT_TIME

DVD 이벤트 통지 코드

0.4 ~ 1.0 초의 길이를 가지는 비디오 세그먼트(segment)인 비디오 오브젝트 단위 (VOBU)의 시작을 모두 통지한다.

파라미터

lParam1
현재의 재생타임 코드를 2 진화 10 진 (BCD)의 시간, 분, 초, 프레임 (HH:MM:SS:FF) 포맷으로 가리키는 DWORD 값. DVD_TIMECODE 구조체의 멤버.
lParam2
타임 코드를 나타내는 불 (BOOL) 값. 제로 (0)는 25 프레임/초를 나타내, 1 은 30 프레임/초 (비드롭)를 나타낸다. 값 2 는, 재생 타임을 판정할 수 없는 것을 나타낸다.

주의

단순한 리니어 무비만이 이 이벤트를 통지한다.

이 이벤트는, 타이틀 도메인으로 발생한다.

EC_DVD_DISC_EJECTED

DVD 이벤트 통지 코드

디스크가 드라이브로부터 꺼내진 것을 통지한다.

파라미터

lParam1
제로.
lParam2
제로.

주의

디스크가 꺼내지면(자), 재생은 자동적으로 중지된다. 어플리케이션은 이 이벤트에 대해서 특히 조작을 실시할 필요는 없다.

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_DISC_INSERTED

DVD 이벤트 통지 코드

디스크가 드라이브에 삽입된 것을 통지한다.

파라미터

lParam1
제로.
lParam2
제로.

주의

디스크가 삽입되면(자), 재생은 자동적으로 시작 된다. 어플리케이션은 이 이벤트에 대해서 특히 조작을 실시할 필요는 없다.

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_DOMAIN_CHANGE

DVD 이벤트 통지 코드

DVD 플레이어의 새로운 도메인을 나타낸다.

파라미터

lParam1
새로운 도메인을 나타내는 DWORD 값. DVD_DOMAIN 열거 데이터형의 멤버.
lParam2
제로.

주의

DVD 플레이어는, 도메인을 변경할 때 마다 이 이벤트를 통지한다.

이 이벤트는, 모든 DVD 도메인으로 발생한다.

EC_DVD_ERROR

DVD 이벤트 통지 코드

DVD 에러 상태를 통지한다.

파라미터

lParam1
에러 상태를 나타내는 DWORD 값. DVD_ERROR 열거 데이터형의 멤버.
lParam2
디코더 리젼을 비트의 반전 세트로서 HIWORD 에 포함해, 드라이브/시스템 리젼을 비트의 반전 세트로서 LOWORD 에 포함한 DWORD 값. 「주의」를 참조.

주의

이 이벤트는, 모든 도메인으로 발생한다.

lParam1 = DVD_ERROR_IncompatibleSystemAndDecoderRegion 의 경우, (1) 지정된 리젼이 디코더에 있는 것, (2) 드라이브와 디코더 리젼이 일치하지 않는 것을 나타낸다.

lParam1 = DVD_ERROR_IncompatibleDiscAndDecoderRegion 의 경우, (1) 지정된 리젼이 디코더에 있는 것, (2) 디스크와 디코더 리젼이 일치하지 않는 것을 나타낸다.

디스크 리젼은, 디스크상과 완전히 똑같이,lParam2 의 LOWORD 의 비트의 예약 세트로서 encode 된다. 디스크가 리젼내에서 용서되는 경우, 그 비트는오프가 된다. 예를 들어 리젼 2 의 디스크에 대한 반환값은, 최하정도로부터 2 번째의 비트가 오프가 된 253 (1111 1101)이 된다. 복수의 리젼을 가지는 디스크에서는, 이와 같이 오프가 된 비트가 다수 있다.

lParam2 의 HIWORD 의 디코더 리젼도 이와 같이 encode 된다.

EC_DVD_KARAOKE_MODE

DVD 이벤트 통지 코드

네비게이터가 가라오케 데이터의 재생을 시작 또는 종료한 것을 나타낸다.

파라미터

lParam1
BOOL 값. TRUE 는 가라오케 트럭의 재생중인 것을, FALSE 는 가라오케 데이터의 재생중이 아닌 것을 나타낸다.
lParam2
예약이 끝난 상태.

주의

DVD 플레이어는, 도메인을 변경할 때 마다 이 이벤트를 통지한다.

이 이벤트는, 모든 DVD 도메인으로 발생한다.

EC_DVD_NO_FP_PGC

DVD 이벤트 통지 코드

DVD 디스크가 FP_PGC (First Play Program Chain)를 가지지 않고, DVD 네비게이터가 자동적으로 PGC 를 로드해 재생을 시작 하지 않는 것을 통지한다.

주의

이 이벤트는, First Play 도메인으로 발생한다.

EC_DVD_PARENTAL_LEVEL_CHANGE

DVD 이벤트 통지 코드

오쏘링 된 컨텐츠의 페어 렌탈 락 레벨이 변경 되려고 하고 있는 것을 통지한다.

파라미터

lParam1
플레이어로 설정된 새로운 페어 렌탈 락 레벨을 나타내는 LONG 값.
lParam2
제로.

주의

DVD 네비게이터의 소스 필터는, DVD 디스크 위에의 SetTmpPML 커멘드에 대한 "온더 플라이 " 의 페어 렌탈 락 레벨의 변경을 현재 지원 하고 있지 않다.

EC_DVD_PLAYBACK_RATE_CHANGE

DVD 이벤트 통지 코드

재생 레이트의 변경이 시작 된 것을 통지한다. 파라미터 lParam1 는 새로운 재생 레이트를 나타낸다.

파라미터

lParam1
LONG 는 새로운 재생 레이트를 나타낸다. lParam1 < 0 은 역방향 재생 모드를 나타낸다. lParam1 > 0 은 정방향재생 모드를 나타낸다. lParam1 는, 실제의 재생 레이트에 10,000 을 곱한 값을 나타낸다 (즉,lParam1 = playback_rate * 10000) .
lParam2
제로.

주의

이 이벤트는, 타이틀 도메인으로 발생한다.

EC_DVD_PLAYBACK_STOPPED

DVD 이벤트 통지 코드

재생이 중지된 것을 나타낸다. DVD 네비게이터는 타이틀 또는 쳅터의 재생을 완료해, 이후의 재생에 대한 분기 명령을 검출하지 않았다.

파라미터

lParam1
제로.
lParam2
제로.

주의

이 이벤트는 타이틀 도메인으로 발생하지만, 유저가 기동한 Stop 에서는 발생하지 않는다.

EC_DVD_STILL_OFF

DVD 이벤트 통지 코드

정지의 마지막 (PGC, Cell, 또는 VOBU)을 통지한다.

파라미터

lParam1
제로.
lParam2
제로.

주의

이 이벤트는, 현재 액티브한 정지가 해방된 것을 나타낸다.

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_PLAYPERIOD_AUTOSTOP

DVD 이벤트 통지 코드

PlayPeriodInTitleAutoStop 호출로 지정된 세그먼트(segment)의 재생을 네비게이터가 완료한 것을 나타낸다.

파라미터

lParam1
제로.
lParam2
제로.

주의

이 이벤트는, 타이틀 도메인으로 발생한다.

이 이벤트는, 지정된 세그먼트(segment)의 재생을 네비게이터가 완료하기 전에 그 재생이 캔슬되었을 때에도 송신된다.

EC_DVD_STILL_ON

DVD 이벤트 통지 코드

정지의 시작 (PGC, Cell, 또는 VOBU)을 통지한다.

파라미터

lParam1
버튼이 이용 가능한가 어떤가를 나타내는 불 (BOOL) 값. 제로 (0)는, 버튼이 이용 가능해서 IDVDControl2::StillOff 메소드가 기능하지 않는 것을 나타낸다. 1 은, 버튼이 이용 불가능해서 IDVDControl2::StillOff 가 기능하는 것을 나타낸다.
lParam2
정지를 계속하는 초수를 나타내는 DWORD 값. 0xFFFFFFFF 는, 무기한의 정지, 즉 유저가 버튼을 누르는지, 또는 어플리케이션이 IDVDControl2::StillOff 를 호출할 때까지 대기하는 것을 나타낸다.

주의

버튼과 정지는 모든 편성이 가능하다 (버튼이 온으로 정지가 온, 버튼이 온으로 정지가 오프, 버튼이 오프로 정지가 온, 버튼이 오프로 정지가 오프).

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_SUBPICTURE_STREAM_CHANGE

DVD 이벤트 통지 코드

메인 타이틀에 대해서 현재의 서브 픽쳐 스트림 번호가 변경된 것을 통지한다.

파라미터

lParam1
새로운 서브 픽쳐 스트림 번호를 나타내는 DWORD 값. 서브 픽쳐 스트림 번호는, 0 ~ 31 의 값으로 나타난다. 스트림 0xFFFFFFFF 는, 스트림이 선택되어 있지 않은 것을 나타낸다.
lParam2
제로.

주의

서브 픽쳐는, 디스크상에서 오쏘링 된 네비게이션 커멘드에 의해 자동적으로 변경할 수가 있다. 또,IDVDControl2 를 사용해 어플리케이션으로 제어할 수도 있다.

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_TITLE_CHANGE

DVD 이벤트 통지 코드

현재의 타이틀 번호가 변경된 것을 나타낸다.

파라미터

lParam1
새로운 타이틀 번호를 나타낸다　DWORD 값.
lParam2
제로.

주의

타이틀 번호는, 1 ~ 99 의 값으로 나타난다. 이 번호는, 디스크 전체의 타이틀 번호인 TTN 를 나타내서 , 현재의 VTS 에 관한 타이틀 번호인 VTS_TTN 를 나타내는 것은 아니다.

이 이벤트는, 타이틀 도메인으로 발생한다.

EC_DVD_VALID_UOPS_CHANGE

DVD 이벤트 통지 코드

이용 가능한 IDVDControl2 인터페이스 메소드세트가 변경된 것을 통지한다.

파라미터

lParam1
그 비트가 DVD 디스크가 명시적으로 무효로 한 IDVDControl2 커멘드를 나타내고 있는 ULONG 를 나타내는 DWORD 값.
lParam2
제로.

주의

이 이벤트는, DVD 디스크 위에의 컨텐츠에 의해 명시적으로 무효로 된 조작을 나타내는 것만으로, 무효로 되어 있지 않은 메소드의 호출이 유효한 것을 보증하는 것은 아니다. 예를 들어 버튼이 존재하지 않는 경우,IDvdControl::ActivateButton 메소드는 명시적으로 무효에되어 있지 않아도 기능하지 않는다.

이 이벤트는, 모든 도메인으로 발생한다.

EC_DVD_WARNING

DVD 이벤트 통지 코드

DVD 경고 상태를 통지한다.

파라미터

lParam1
경고 상태를 나타내는 DWORD 값. DVD_WARNING 열거 데이터형의 멤버.
lParam2
제로.

주의

이 이벤트는, 모든 도메인으로 발생한다.


에러 및 성공 코드

Microsoft® DirectShow® 는, 에러 및 성공 통지 (귀가 코드)를 HRESULT 값의 포맷으로 어플리케이션에 돌려준다. 귀가 코드의 LOWORD 부분은, 16 진포맷의 귀가 코드 그 자체를 나타낸다. 귀가 코드를 취득한 다음에 AMGetErrorText 함수를 호출하면, 코드의 텍스트 기술이 돌려주어진다. COM Win32 HRESULT 의 문서에는, FAILED 및 SUCCEEDED 매크로를 사용해 반환값을 테스트하는 방법 등, 자세한 정보가 기재되어 있다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • 일반적인 COM HRESULT 값
  • DirectShow 에 고유의 HRESULT 값
  • DirectShow Editing Services 에 고유의 HRESULT 값

일반적인 COM HRESULT 값

이하에, DirectShow 가 돌려주는 일반적인 COM 에러 코드와 성공 코드의 몇개인가를 나타낸다.
값 | 의미
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | 예기치 못한 에러.
NOERROR | 에러 없음. 수치적으로는 S_OK 와 같다.
S_FALSE | 성공. 조건이 FALSE 였다.
S_OK | 성공. 수치적으로는 NOERROR 와 같다.
S_TRUE | 성공. 조건이 TRUE 였다.

DirectShow 에 고유의 HRESULT 값

이하의 겉(표)에, DirectShow 에 고유의 에러 및 성공 코드를 숫자의 순서에 나타낸다. VFW_S_ 로 시작되는 귀가 코드는 전체적으로의 성공을 나타낸다. 처리가 부분적에 성공해 그 이외에 성공을 나타내는 반환값을 돌려주는 일도 있다. 예를 들어 VFW_S_SOME_DATA_IGNORED 는, 프로퍼티 설정의 몇개인가를 무시해 파일이 렌더링 된 것을 나타낸다. VFW_E_ 로 시작되는 귀가 코드는 에러를 나타내, CTL_ (제어 에러 코드)로 시작되는 귀가 코드는 Microsoft® Windows Media™ Player 컨트롤에 관계하는 정보를 나타낸다. 이 표는 가능한 반환값 코드를 모두 망라한 것은 아니고, 특히 DirectShow 에 관계하는 귀가 코드를 리스트 되어 있다. DirectShow 에 고유의 귀가 코드는, Vfwmsgs.h 헤더 파일에도 기술되고 있다. 여기에 리스트되어 있지 않은 에러가 발생했을 경우는, 다른 소스, 예를 들어 COM 또는 Microsoft® Windows® 9x 에러의 일람등을 참조할것. 예를 들어 Microsoft® Visual C++® 유저이면, Winerror.h 인클루드 파일을 보면 COM 또는 Windows 9x 에러를 조사할 수가 있다.

C/C++ 프로그래머는, 완전한 (32 비트) 16 진포맷의 에러 코드를 받는다. 한편, Microsoft® Visual Basic® 프로그래머는, 에러 코드의 선두 16 비트인 만큼 상당하는 10 진값을 받는다. 이 값은, 에러 통지 다이알로그 박스 또는 Err 오브젝트에 런타임 에러로서 표시된다. 에러가 이하의 겉(표)에 나타나지 않은 경우는, 10 진값을 대응하는 16 진값으로 변환하고 나서 전술과 같이 거기에 대응하는 에러를 조사할 필요가 있다. 에러의 16 진값은 최대로 4 자리수이다. 에러를 조사하려면 , 에러 코드표에 기재된 16 진코드의 마지막 4 자리수를, 변환된 런타임 에러와 조합한다.
귀가 코드 | 설명 | 16 진값 | 10 진값 (LOWORD)
CTL_E_ILLEGALFUNCTIONCALL | 함수 호출의 구문에 잘못이 있다. | 0x800A0005 | 5
CTL_E_OVERFLOW | 결과가 너무 커 함수의 귀가형으로 나타낼 수가 없다. | 0x800A0006 | 6
CTL_E_OUTOFMEMORY | 메모리 부족을 위해서(때문에) 요구된 처리를 실시할 수 없다. | 0x800A0007 | 7
CTL_E_DIVISIONBYZERO | 함수가 제로에 의한 나눗셈을 실시한다고 했다. | 0x800A000B | 11
CTL_E_OUTOFSTRINGSPACE | 캐릭터 라인 공간 부족을 위해서(때문에) 요구된 처리를 실시할 수 없다. 일부의 조작 (예를 들어 카피)에서는, 캐릭터 라인 공간을 다 써 버리는 것 같은 약 2시간 마다 써서 보내는 편지자열이 사용되는 일이 있다. | 0x800A000E | 14
CTL_E_OUTOFSTACKSPACE | 캐릭터 라인 공간 부족을 위해서(때문에) 요구된 처리를 실시할 수 없다. 각 thread에는 전용의 스택이 있는 한편으로, 다른 리소스 (예를 들어 heap 메모리)는 프로세스내의 모든 thread로 공용된다. 프로그램이 필요로 하는 추가의 thread의 각각의 스택에 어떤 것정도의 메모리를 할당하는지를 지정해야 한다. operating system는 필요에 따라서 thread의 추가 스택 공간을 할당하지만, 디폴트값은 스스로 지정할 필요가 있다. 필요한 공간을 operating system가 할당할 수가 없는 경우, 이 에러가 발생한다. | 0x800A001C | 28
CTL_E_BADFILENAMEORNUMBER | 함수가 액세스 하려고 한 파일의 파일명 또는 번호가 무효이다. | 0x800A0034 | 52
CTL_E_FILENOTFOUND | 함수가 액세스 하려고 한 파일이 발견되지 않는다. | 0x800A0035 | 53
CTL_E_BADFILEMODE | 함수가 호환성의 없는 파일 모드를 가지는 파일에 대해서 조작을 실시하려고 했다. 파일 모드에는, 추가, 바이너리, 입력, 출력, 랜덤이 있다. | 0x800A0036 | 54
CTL_E_FILEALREADYOPEN | 함수가 이미 열리고 있는 파일을 열려고 했다. | 0x800A0037 | 55
CTL_E_DEVICEIOERROR | 함수의 실행중에 디바이스 I/O 에러가 발생했다. | 0x800A0039 | 57
CTL_E_FILEALREADYEXISTS | 함수가 이미 존재하고 있는 파일을 생성 하려고 했다. | 0x800A003A | 58
CTL_E_BADRECORDLENGTH | 함수가 부정한 파일 레코드에 액세스 하려고 했다. 예를 들어 랜덤 억세스용으로 열리는 파일은, 같은 길이의 레코드로부터 구성되어 있는 것이 상정된다. | 0x800A003B | 59
CTL_E_DISKFULL | 함수가 디스크에 기입을 실시하려고 했지만 디스크가 가득했다. | 0x800A003D | 61
CTL_E_BADRECORDNUMBER | 함수가 부정한 파일 레코드에 액세스 하려고 했다. 레코드 번호는, 레코드 세트 (데이터 소스의 레코드세트) 내의 위치이다. | 0x800A003F | 63
CTL_E_BADFILENAME | 함수가 부정한 파일명에 액세스 하려고 했다. | 0x800A0040 | 64
CTL_E_TOOMANYFILES | 함수가 이미 많은 파일을 너무 열고 상태로 파일을 열려고 했다. | 0x800A0043 | 67
CTL_E_DEVICEUNAVAILABLE | 함수를 이용할 수 없는 디바이스에 액세스 하려고 했다. | 0x800A0044 | 68
CTL_E_PERMISSIONDENIED | 함수가 적절한 권한을 가지지 않는 파일에 액세스 하려고 했다. | 0x800A0046 | 70
CTL_E_DISKNOTREADY | 함수가 디스크의 준비가 갖추어지지 않았는데 파일에 액세스 하려고 했다. | 0x800A0047 | 71
CTL_E_PATHFILEACCESSERROR | 함수가 부정한 또는 권한이 부적절한 파일 또는 패스에 액세스 하려고 했다. | 0x800A004B | 75
CTL_E_PATHNOTFOUND | 함수가 부정한 패스를 가지는 파일에 액세스 하려고 했다. | 0x800A004C | 76
CTL_E_INVALIDPATTERNSTRING | 함수가 무효인 캐릭터 라인으로 불려 갔다. | 0x800A005D | 93
CTL_E_INVALIDUSEOFNULL | 함수가 무효인 NULL 로 불려 갔다. | 0x800A005E | 94
VFW_S_NO_MORE_ITEMS | 리스트에는 이제 항목이 없다. | 0x00040103 | 259
CTL_E_INVALIDFILEFORMAT | 함수가 호환성의 없는 파일 포맷을 가지는 파일에 대해서 조작을 실시하려고 했다. | 0x800A0141 | 321
CTL_E_INVALIDPROPERTYVALUE | 함수가 무효인 프로퍼티값으로 불려 갔다. | 0x800A017C | 380
CTL_E_INVALIDPROPERTYARRAYINDEX | 함수가 무효인 프로퍼티 배열 인덱스로 불려 갔다. | 0x800A017D | 381
CTL_E_SETNOTSUPPORTEDATRUNTIME | 함수가 실행시로 설정할 수 없는 프로퍼티를 설정하려고 했다. | 0x800A017E | 382
CTL_E_SETNOTSUPPORTED | 함수를 설정할 수 없는 프로퍼티를 설정하려고 했다. | 0x800A017F | 383
CTL_E_NEEDPROPERTYARRAYINDEX | 배열 인덱스가 필요한 프로퍼티에 대해서, 함수가 배열 인덱스없이 액세스 하려고 했다. | 0x800A0181 | 385
CTL_E_SETNOTPERMITTED | 함수가 프로퍼티를 설정하는 적절한 권한을 가지지 않고 프로퍼티를 설정하려고 했다. | 0x800A0183 | 387
CTL_E_GETNOTSUPPORTEDATRUNTIME | 함수가 실행시에 취득할 수 없는 프로퍼티를 취득하려고 했다. | 0x800A0189 | 393
CTL_E_GETNOTSUPPORTED | 함수를 취득할 수 없는 프로퍼티를 취득하려고 했다. | 0x800A018A | 394
CTL_E_PROPERTYNOTFOUND | 함수가 취득하려고 한 프로퍼티가 발견되지 않는다. | 0x800A01A6 | 422
CTL_E_INVALIDCLIPBOARDFORMAT | 함수가 무효인 클립보드 포맷으로 조작을 실시하려고 했다. | 0x800A01CC | 460
CTL_E_INVALIDPICTURE | 함수가 무효인 픽쳐 포맷으로 조작을 실시하려고 했다. | 0x800A01E1 | 481
CTL_E_PRINTERERROR | 함수가 인쇄를 실시하려고 했지만 프린터 에러가 발생했다. | 0x800A01E2 | 482
VFW_E_INVALIDMEDIATYPE | 지정된 미디어 타입은 무효이다. | 0x80040200 | 512
VFW_E_INVALIDSUBTYPE | 지정된 미디어 서브 타입은 무효이다. | 0x80040201 | 513
VFW_E_NEED_OWNER | 이 오브젝트는 집성 오브젝트로서의 보고 생성 할 수가 있다. | 0x80040202 | 514
VFW_E_ENUM_OUT_OF_SYNC | 열거 오브젝트 상태가 변화해, 열거자 상태와의 모순이 발생했다. 열거자의 앞의 호출로 취득한 데이터를 파기해, 열거자의 Reset 메소드를 호출해 그 열거자를 갱신하는 것. | 0x80040203 | 515
VFW_E_ALREADY_CONNECTED | 처리에 포함되는 핀이 이미 적어도 1 개(살) 접속되고 있다. | 0x80040204 | 516
VFW_E_FILTER_ACTIVE | 필터가 액티브해서, 이 처리를 실행할 수 없다. | 0x80040205 | 517
VFW_E_NO_TYPES | 지정되고 싶은 차이인가의 핀이 미디어 타입을 지원 하고 있지 않다. | 0x80040206 | 518
VFW_E_NO_ACCEPTABLE_TYPES | 이러한 핀의 사이에 공통의 미디어 타입이 없다. | 0x80040207 | 519
VFW_E_INVALID_DIRECTION | 같은 방향의 핀을 2 개 접속할 수 없다. | 0x80040208 | 520
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다. | 0x80040209 | 521
VFW_E_NO_ALLOCATOR | 샘플 버퍼 allocater가 이용 불가능. | 0x8004020A | 522
VFW_E_RUNTIME_ERROR | 런타임 에러가 발생했다. | 0x8004020B | 523
VFW_E_BUFFER_NOTSET | 버퍼 공간이 설정되어 있지 않다. | 0x8004020C | 524
VFW_E_BUFFER_OVERFLOW | 버퍼가 작다. | 0x8004020D | 525
VFW_E_BADALIGN | 무효인 alignment가 지정되었다. | 0x8004020E | 526
VFW_E_ALREADY_COMMITTED | 필터가 액티브 때는 할당하고가 끝난 메모리를 변경할 수 없다. | 0x8004020F | 527
VFW_E_BUFFERS_OUTSTANDING | 1 개(살) 또는 복수의 버퍼가 액티브하다. | 0x80040210 | 528
VFW_E_NOT_COMMITTED | allocater가 액티브하지 않을 때는 샘플을 할당할 수가 없다. | 0x80040211 | 529
VFW_E_SIZENOTSET | 사이즈가 설정되어 있지 않기 때문에, 메모리를 할당할 수가 없다. | 0x80040212 | 530
VFW_E_NO_CLOCK | 클락이 정의되어 있지 않기 때문에, 동기화를 실시할 수 없다. | 0x80040213 | 531
VFW_E_NO_SINK | 품질 세면대가 정의되어 있지 않기 때문에, 품질 메세지를 송신할 수 없다. | 0x80040214 | 532
VFW_E_NO_INTERFACE | 필요한 인터페이스가 이행되어 있지 않다. | 0x80040215 | 533
VFW_E_NOT_FOUND | 오브젝트 또는 이름이 발견되지 않았다. | 0x80040216 | 534
VFW_E_CANNOT_CONNECT | 접속을 확립하는 중간 필터의 편성이 발견되지 않았다. | 0x80040217 | 535
VFW_E_CANNOT_RENDER | 스트림을 렌더링 하는 필터의 편성이 발견되지 않는다. | 0x80040218 | 536
VFW_E_CHANGING_FORMAT | 포맷을 동적으로 변경할 수 없다. | 0x80040219 | 537
VFW_E_NO_COLOR_KEY_SET | 칼라 키가 설정되어 있지 않다. | 0x8004021A | 538
VFW_E_NOT_OVERLAY_CONNECTION | 현재의 핀 접속은IOverlay 전송을 사용하고 있지 않다. | 0x8004021B | 539
VFW_E_NOT_SAMPLE_CONNECTION | 현재의 핀 접속은 IMemInputPin 전송을 사용하고 있지 않다. | 0x8004021C | 540
VFW_E_PALETTE_SET | 칼라 키를 설정 하면, 이미 설정되어 있는 팔레트와 모순될 가능성이 있다. | 0x8004021D | 541
VFW_E_COLOR_KEY_SET | 팔레트를 설정 하면, 이미 설정되어 있는 칼라 키와 모순될 가능성이 있다. | 0x8004021E | 542
VFW_E_NO_COLOR_KEY_FOUND | 일치하는 칼라 키가 없다. | 0x8004021F | 543
VFW_E_NO_PALETTE_AVAILABLE | 팔레트가 이용 불가능. | 0x80040220 | 544
VFW_E_NO_DISPLAY_PALETTE | 디스플레이는 팔레트를 사용하지 않는다. | 0x80040221 | 545
VFW_E_TOO_MANY_COLORS | 현재의 디스플레이 설정에 대해서 색이 너무 많다. | 0x80040222 | 546
VFW_E_STATE_CHANGED | 샘플의 처리를 기다리고 있는 동안에 상태가 변화했다. | 0x80040223 | 547
VFW_E_NOT_STOPPED | 필터가 정지되어 있지 않기 때문에, 처리를 실행할 수 없다. | 0x80040224 | 548
VFW_E_NOT_PAUSED | 필터가 포즈되어 있지 않기 때문에, 처리를 실행할 수 없다. | 0x80040225 | 549
VFW_E_NOT_RUNNING | 필터가 실행되어 있지 않기 때문에, 처리를 실행할 수 없다. | 0x80040226 | 550
VFW_E_WRONG_STATE | 필터 상태에 잘못이 있으므로, 처리를 실행할 수 없다. | 0x80040227 | 551
VFW_E_START_TIME_AFTER_END | 샘플의 시작 타임이 샘플의 종료 타임이 나중이 되고 있다. | 0x80040228 | 552
VFW_E_INVALID_RECT | 제공된 직사각형이 무효이다. | 0x80040229 | 553
VFW_E_TYPE_NOT_ACCEPTED | 이 핀은, 제공된 미디어 타입을 사용할 수 없다. | 0x8004022A | 554
VFW_E_SAMPLE_REJECTED | 이 샘플은 렌더링 할 수 없다. | 0x8004022B | 555
VFW_E_SAMPLE_REJECTED_EOS | 스트림의 마지막에 도달하고 있으므로, 이 샘플을 렌더링 할 수 없다. | 0x8004022C | 556
VFW_E_DUPLICATE_NAME | 같은 이름의 필터를 추가하려고 했지만 실패했다. | 0x8004022D | 557
VFW_S_DUPLICATE_NAME | 같은 이름의 필터를 추가하려고 했는데, 이름을 변경해 처리가 성공했다. | 0x0004022D | 557
VFW_E_TIMEOUT | 타임 아웃 기간이 지났다. | 0x8004022E | 558
VFW_E_INVALID_FILE_FORMAT | 포맷이 무효이다. | 0x8004022F | 559
VFW_E_ENUM_OUT_OF_RANGE | 리스트가 다 써 버려졌다. | 0x80040230 | 560
VFW_E_CIRCULAR_GRAPH | 필터 그래프가 반복이다. | 0x80040231 | 561
VFW_E_NOT_ALLOWED_TO_SAVE | 이 상태에서의 갱신은 용서되지 않는다. | 0x80040232 | 562
VFW_E_TIME_ALREADY_PASSED | 과거의 타임의 커멘드를 큐에 넣으려고 했다. | 0x80040233 | 563
VFW_E_ALREADY_CANCELLED | 큐에 넣어진 커멘드는 이미 캔슬되고 있었다. | 0x80040234 | 564
VFW_E_CORRUPT_GRAPH_FILE | 파일이 망가져 있으므로 렌더링 할 수 없다. | 0x80040235 | 565
VFW_E_ADVISE_ALREADY_SET | IOverlay 아드바이즈 링크가 이미 존재하고 있다. | 0x80040236 | 566
VFW_S_STATE_INTERMEDIATE | 상태의 이행이 완료하고 있지 않다. | 0x00040237 | 567
VFW_E_NO_MODEX_AVAILABLE | 풀 스크린 모드는 이용할 수 없다. | 0x80040238 | 568
VFW_E_NO_ADVISE_SET | 이 아드바이즈는 정상적으로 설정되어 있지 않기 때문에 캔슬할 수 없다. | 0x80040239 | 569
VFW_E_NO_FULLSCREEN | 풀 스크린 모드는 이용할 수 없다. | 0x8004023A | 570
VFW_E_IN_FULLSCREEN_MODE | 풀 스크린 모드에서는 IVideoWindow 메소드를 호출할 수 없다. | 0x8004023B | 571
VFW_E_UNKNOWN_FILE_TYPE | 이 파일의 미디어 타입이 인식되지 않는다. | 0x80040240 | 576
VFW_E_CANNOT_LOAD_SOURCE_FILTER | 이 파일의소스 필터를 로드할 수 없다. | 0x80040241 | 577
VFW_S_PARTIAL_RENDER | 이 무비의 몇개의 스트림이, 지원되어 있지 않은 포맷을 가진다. | 0x00040242 | 578
VFW_E_FILE_TOO_SHORT | 파일이 불완전하다. | 0x80040243 | 579
VFW_E_INVALID_FILE_VERSION | 파일의 버젼 번호가 무효이다. | 0x80040244 | 580
VFW_S_SOME_DATA_IGNORED | 파일에 몇개의 사용되어 있지 않은 프로퍼티 설정이 포함되어 있다. | 0x00040245 | 581
VFW_S_CONNECTIONS_DEFERRED | 일부의 접속이 실패해 지연 되었다. | 0x00040246 | 582
VFW_E_INVALID_CLSID | 이 파일은 망가져 있다. 무효인 클래스 식별자가 포함되어 있다. | 0x80040247 | 583
VFW_E_INVALID_MEDIA_TYPE | 이 파일은 망가져 있다. 무효인 미디어 타입이 포함되어 있다. | 0x80040248 | 584
VFW_E_SAMPLE_TIME_NOT_SET | 이 샘플에는타임 스탬프가 설정되어 있지 않다. | 0x80040249 | 585
VFW_S_RESOURCE_NOT_NEEDED | 지정된 리소스는 이미 필요없다. | 0x00040250 | 592
VFW_E_MEDIA_TIME_NOT_SET | 이 샘플에는미디어 타임이 설정되어 있지 않다. | 0x80040251 | 593
VFW_E_NO_TIME_FORMAT_SET | 미디어 타임 포맷이 선택되어 있지 않다. | 0x80040252 | 594
VFW_E_MONO_AUDIO_HW | 오디오 디바이스가 단청의 전용이므로, 밸런스를 변경할 수 없다. | 0x80040253 | 595
VFW_S_MEDIA_TYPE_IGNORED | 지속 그래프의 미디어 타입에 접속할 수 없다. | 0x00040254 | 596
VFW_E_NO_DECOMPRESSOR | 비디오 스트림을 재생할 수 없다. 적절한 데콘프렛사가 발견되지 않았다. | 0x80040255 | 597
VFW_E_NO_AUDIO_HARDWARE | 오디오 스트림을 재생할 수 없다. 오디오 하드웨어를 이용할 수 없는, 또는 하드웨어가 지원되어 있지 않다. | 0x80040256 | 598
VFW_S_VIDEO_NOT_RENDERED | 비디오 스트림을 재생할 수 없다. 적절한렌더러가 발견되지 않았다. | 0x00040257 | 599
VFW_S_AUDIO_NOT_RENDERED | 오디오 스트림을 재생할 수 없다. 적절한 렌더러가 발견되지 않았다. | 0x00040258 | 600
VFW_E_RPZA | 비디오 스트림을 재생할 수 없다. 포맷 'RPZA'는 지원되어 있지 않다. | 0x80040259 | 601
VFW_S_RPZA | 비디오 스트림을 재생할 수 없다. 포맷 'RPZA'는 지원되어 있지 않다. | 0x0004025A | 602
VFW_E_PROCESSOR_NOT_SUITABLE | DirectShow 는 이 프로세서상에서 MPEG 무비를 재생할 수 없다. | 0x8004025B | 603
VFW_E_UNSUPPORTED_AUDIO | 오디오 스트림을 재생할 수 없다. 오디오 포맷은 지원되어 있지 않다. | 0x8004025C | 604
VFW_E_UNSUPPORTED_VIDEO | 비디오 스트림을 재생할 수 없다. 비디오 포맷은 지원되어 있지 않다. | 0x8004025D | 605
VFW_E_MPEG_NOT_CONSTRAINED | 이 비디오 스트림은 규격에 준거하고 있지 않았기 때문에 DirectShow 로 재생할 수 없다. | 0x8004025E | 606
VFW_E_NOT_IN_GRAPH | 필터 그래프에 존재하지 않는 오브젝트에 요구된 함수를 실행할 수 없다. | 0x8004025F | 607
VFW_S_ESTIMATED | 돌려주어진 값은 예측값이다. 값의 정확함을 보증할 수 없다. | 0x00040260 | 608
VFW_E_NO_TIME_FORMAT | 오브젝트의 타임 포맷에 액세스 할 수 없다. | 0x80040261 | 609
VFW_E_READ_ONLY | 스트림이 읽어내기 전용으로, 필터에 의해 데이터가 변경되고 있으므로, 접속을 확립할 수 없다. | 0x80040262 | 610
VFW_S_RESERVED | 이 성공 코드는, DirectShow 의 내부 처리용으로 예약되고 있다. | 0x00040263 | 611
VFW_E_BUFFER_UNDERFLOW | 버퍼가 충분히 채워지지 않았다. | 0x80040264 | 612
VFW_E_UNSUPPORTED_STREAM | 파일을 재생할 수 없다. 포맷이 지원되어 있지 않다. | 0x80040265 | 613
VFW_E_NO_TRANSPORT | 같은 전송을 지원 하고 있지 않기 때문에 핀끼리를 접속할 수 없다. | 0x80040266 | 614
VFW_S_STREAM_OFF | 스트림이 오프가 되었다. | 0x00040267 | 615
VFW_S_CANT_CUE | 그래프 필터는 액티브하지만, 데이터를 출력할 수 없다. 「IMediaFilter::GetState 」를 참조할것. | 0x00040268 | 616
VFW_E_BAD_VIDEOCD | 디바이스가 비디오 CD 를 정상적으로 읽어낼 수 없는, 또는 비디오 CD 의 데이터가 망가져 있다. | 0x80040269 | 617
VFW_S_NO_STOP_TIME | 샘플에 종료 타임은 아니고 시작 타임이 설정되어 있었다. 이 경우, 돌려주어지는 종료 타임은 시작 타임에 1 을 더한 값으로 설정된다. | 0x80040270 | 624
VFW_E_OUT_OF_VIDEO_MEMORY | 이 디스플레이 해상도와 색 가지수에 대해서 비디오 메모리가 불충분하다. 해상도를 낮고 하면 좋다. | 0x80040271 | 625
VFW_E_VP_NEGOTIATION_FAILED | 비디오 포토 접속 네고시에이션 프로세스가 실패했다. | 0x80040272 | 626
VFW_E_DDRAW_CAPS_NOT_SUITABLE | Microsoft® DirectDraw® 가 인스톨되어 있지 않은, 또는 비디오 카드의 능력이 적절하지 않다. 디스플레이가 16 색모드가 아닌 것을 확인하는 것. | 0x80040273 | 627
VFW_E_NO_VP_HARDWARE | 비디오 포토 하드웨어를 이용할 수 없는, 또는 하드웨어가 응답하지 않는다. | 0x80040274 | 628
VFW_E_NO_CAPTURE_HARDWARE | 캡춰 하드웨어를 이용할 수 없는, 또는 하드웨어가 응답하지 않는다. | 0x80040275 | 629
VFW_E_DVD_OPERATION_INHIBITED | 이 시점에서 이 유저 조작은 DVD 컨텐츠에 의해 금지되고 있다. | 0x80040276 | 630
VFW_E_DVD_INVALIDDOMAIN | 현재의 도메인으로 이 처리는 허가되어 있지 않다. | 0x80040277 | 631
VFW_E_DVD_NO_BUTTON | 요구된 버튼을 이용할 수 없다. | 0x80040278 | 632
VFW_E_DVD_GRAPHNOTREADY | DVD-Video 재생 그래프가 구축되어 있지 않다. | 0x80040279 | 633
VFW_E_DVD_RENDERFAIL | DVD-Video 재생 그래프의 구축이 실패했다. | 0x8004027A | 634
VFW_E_DVD_DECNOTENOUGH | 디코더가 불충분했던 위해(때문에), DVD-Video 재생 그래프를 구축할 수 없었다. | 0x8004027B | 635
VFW_E_DVD_NOT_IN_KARAOKE_MODE | DVD 네비게이터는 가라오케 모드는 아니다. | 0x8004028B | 651
VFW_E_FRAME_STEP_UNSUPPORTED | 스탭핑(Stepping)가 지원되어 있지 않다. | 0x8004028E | 654
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | 핀은 이미 호출해 옆thread로 블록 되고 있다. | 0x80040293 | 659
VFW_E_PIN_ALREADY_BLOCKED | 핀은 이미 다른 thread로 블록 되고 있다. | 0x80040294 | 660
VFW_E_CERTIFICATION_FAILURE | 이 필터의 사용은 소프트웨어 키에 의해 제한되고 있다. 어플리케이션은, 필터를 락 해제해야 한다. | 0x80040295 | 661
CTL_E_CANTSAVEFILETOTEMP | 파일은 TEMP 디렉토리에 보존할 수 없다. | 0x800A02DF | 735
CTL_E_SEARCHTEXTNOTFOUND | 검색 대상의 텍스트가 발견되지 않는다. | 0x800A02E8 | 744
CTL_E_REPLACEMENTSTOOLONG | 텍스트의 치환이 너무 길다. | 0x800A02EA | 746
VFW_E_BAD_KEY | 레지스트리 엔트리가 망가져 있다. | 0x800403F2 | 1010

DirectShow Editing Services 에 고유의 HRESULT 값

위의값에 가세해 DirectShow Editing Services 에서는 이하의 HRESULT 값이 정의되고 있다.

귀가 코드 | 설명 | 16 진값 | 10 진값 (LOWORD)
S_WARN_OUTPUTRESET | 그래프의 렌더링 부분이 삭제되었다. 어플리케이션은 이것을 재구축 해야 한다. | 0x00040404 | 1028
E_NOTINTREE | 오브젝트가 타임 라인에 포함되지 않았다. | 0x80040400 | 1024
E_RENDER_ENGINE_IS_BROKEN | 프로젝트가 정상적으로 렌더링 되지 않았기 때문에, 처리가 실패했다. | 0x80040401 | 1025
E_MUST_INIT_RENDERER | 렌더링 엔진이 기동되어 있지 않다. | 0x80040402 | 1026
E_NOTDETERMINED | 요구된 값을 판정할 수 없다. | 0x80040403 | 1027
E_NO_TIMELINE | 타임 라인 오브젝트가 없다. | 0x80040404 | 1028


이벤트 통지 코드

Microsoft® DirectShow® 에서는, 시스템 정의 이벤트를 지원 하고 있다. 필터는,IMediaEventSink::Notify 메소드를 사용해 필터 그래프 매니저에 이벤트를 건네준다. 필터 그래프 매니저는, 일부의 이벤트를 처리해, 그 이외의 이벤트를 어플리케이션에 건네준다. 어플리케이션은,IMediaEvent::GetEvent 메소드를 호출하는 것으로, 이벤트를 취득한다. 상세한 것에 대하여는, 「DirectShow 에서의 이벤트 통지」를 참조할것.

여기에서는, DVD 고유 이벤트 이외의 DirectShow 이벤트에 대해 설명한다. DVD 에 고유의 이벤트에 대해서는, 「DVD 이벤트 통지 코드」를 참조할것.

여기에서는, 이벤트 마다 이벤트 코드와 2 개의 이벤트 파라미터의 의미를 나타낸다. 또, 필터 그래프 매니저에 의한 이벤트의 기정 처리가 있는 경우는, 거기에 붙어도 기술한다. 기정 처리를 무효로 하려면 , 어플리케이션으로 IMediaEvent::CancelDefaultHandling 를 호출한다.

이벤트 통지 코드는, 헤더 파일의 Evcode.h 및 Audevcod.h 에 정의되고 있다.

이벤트 통지 코드 | 설명
EC_ACTIVATE | 비디오 윈도우가 액티브 또는 비액티브.
EC_BUFFERING_DATA | 그래프가 데이터를 버퍼링 하고 있다, 또는 데이터의 버퍼링을 정지했다.
EC_CLOCK_CHANGED | 기준 클락이 변경되었다.
EC_COMPLETE | 특정의 스트림으로부터의 모든 데이터를 렌더링 끝마쳤다.
EC_DEVICE_LOST | 플러그 & 플레이 디바이스가 떼어내진, 또는 다시 사용할 수 있게 되었다.
EC_DISPLAY_CHANGED | 표시 모드가 변경되었다.
EC_END_OF_SEGMENT | 세그먼트(segment)의 끝나에 도달했다.
EC_ERROR_STILLPLAYING | 그래프를 실행하는 비동기 커멘드가 실패했다.
EC_ERRORABORT | 에러이기 때문에 조작이 중지되었다.
EC_FULLSCREEN_LOST | 비디오 렌더러가 풀 스크린 모드로부터 빠지려 하고 있다.
EC_GRAPH_CHANGED | 필터 그래프가 변경되었다.
EC_NEED_RESTART | 필터가 그래프의 재개를 요구하고 있다.
EC_NOTIFY_WINDOW | 필터에 비디오 렌더러의 윈도우를 통지한다.
EC_OLE_EVENT | 필터가 어플리케이션에 텍스트 캐릭터 라인을 건네주고 있다.
EC_OPENING_FILE | 그래프가 파일을 열고 있다, 또는 파일을 열어 끝냈다.
EC_PALETTE_CHANGED | 비디오 팔레트가 변경되었다.
EC_PAUSED | 포즈 요구가 완료했다.
EC_QUALITY_CHANGE | 품질관리이기 때문에, 그래프가 샘플을 삭제했다.
EC_REPAINT | 비디오 렌더러가 재드로잉(Drawing)를 요구하고 있다.
EC_SEGMENT_STARTED | 새로운 세그먼트(segment)가 시작 했다.
EC_SHUTTING_DOWN | 필터 그래프가 파기전에 슛다운 하고 있다.
EC_SNDDEV_IN_ERROR | 입력 핀으로 오디오 디바이스 에러가 발생했다.
EC_SNDDEV_OUT_ERROR | 출력 핀으로 오디오 디바이스 에러가 발생했다.
EC_STARVATION | 필터는 충분한 데이터를 받지 않았다.
EC_STEP_COMPLETE | 스탭핑(Stepping)를 실행하고 있는 필터가, 지정수의 스탭핑(Stepping)를 완료했다.
EC_STREAM_CONTROL_STARTED | 스트림 제어 시작 커멘드가 유효하게 되었다.
EC_STREAM_CONTROL_STOPPED | 스트림 제어 정지 커멘드가 유효하게 되었다.
EC_STREAM_ERROR_STILLPLAYING | 스트림내에 에러가 발생했다. 스트림은 계속해 재생중이다.
EC_STREAM_ERROR_STOPPED | 에러이기 때문에 스트림이 정지했다.
EC_USERABORT | 유저가 재생을 강제 종료했다.
EC_VIDEO_SIZE_CHANGED | 네이티브 비디오 사이즈가 변경되었다.
EC_WINDOW_DESTROYED | 비디오 렌더러가 파기 또는 그래프로부터 삭제되었다.

EC_ACTIVATE

비디오 윈도우가 액티브 또는 비액티브.

파라미터

lParam1
윈도우가 액티브하게 되었을 경우는 TRUE, 윈도우가 비액티브하게 되었을 경우는 FALSE.
lParam2
렌더러의 IBaseFilter 인터페이스에의 포인터.

기정 처리

필터 그래프 매니저는,IResourceManager 인터페이스를 개입시켜 포커스를 설정한다. 어플리케이션에는 이벤트 통지를 송신하지 않는다.

주의

비디오 렌더러는, 윈도우가 액티브 또는 비액티브하게 되었을 때 (ACTIVATEAPP 를 받았을 때)에 이 이벤트를 송신한다. 윈도우의 액티브와 비액티브가 발생하는 것은, 윈도우가 포커스를 취득 또는 상실한 것, 또는 렌더러가 풀 스크린 모드와 윈도우 모드를 바꾸었던 것이 원인이다.

이 이벤트에 의해, 필터 그래프 매니저는, 오디오 디바이스 등, 윈도우 포커스에 의존하는 리소스를 할당할 수가 있다.

EC_BUFFERING_DATA

이벤트 통지 코드

그래프가 데이터를 버퍼링 하고 있다, 또는 데이터의 버퍼링을 정지했다.

파라미터

lParam1
그래프가 버퍼링을 시작 하는 경우는 TRUE, 그래프가 버퍼링을 정지하는 경우는 FALSE.
lParam2
제로.

기정 처리

없음.

주의

외부 소스로부터로 다를 버퍼링 할 필요가 있는 경우에, 필터는 이 이벤트를 송신한다(네트워크로부터 데이터를 읽어들이는 경우 등). 어플리케이션은 이 이벤트를 사용해 유저 인터페이스를 조정한다.

EC_CLOCK_CHANGED

이벤트 통지 코드

기준 클락이 변경되었다.

파라미터

lParam1
제로.
lParam2
제로.

기정 처리

없음.

주의

필터 그래프의 IMediaFilter::SetSyncSource 메소드가 불려 가면(자), 필터 그래프는 이 이벤트를 송신한다.

EC_COMPLETE

이벤트 통지 코드

특정의 스트림으로부터의 모든 데이터를 렌더링 끝마쳤다.

파라미터

lParam1
HRESULT 값. S_OK 이라도 좋다.
lParam2
제로, 또는 렌더러의 IBaseFilter 인터페이스에의 포인터.

기정 처리

기정에서는, 필터 그래프 매니저는 이 이벤트를 어플리케이션에는 전송 하지 않는다. 다만, 그래프내의 모든 스트림이 EC_COMPLETE 를 보고한 후, 필터 그래프 매니저는 어플리케이션에 대해서 별로 EC_COMPLETE 이벤트를 송신한다.

이 이벤트의 기정 처리가 무효화되면(자), 어플리케이션은 렌더러로부터 모든 EC_COMPLETE 이벤트를 받는다.

주의

렌더링 필터는 엔드 오브 스트림 통지를 받으면(자), 이 이벤트를 송신한다(엔드 오브 스트림은 IPin::EndOfStream 메소드를 개입시켜 통지제가 된다). 필터는 각 스트림에 대해서 EC_COMPLETE 이벤트를 1 회만 송신한다. 필터는 이 이벤트를 송신하기 전에, 보류중의 샘플을 모두 처리할 필요가 있다. 렌더러를 정지 하면, 캐쉬내의 엔드 오브 스트림 상태가 모두 리셋 된다.

필터는 lParam2 파라미터를 IBaseFilter 포인터로 설정한다. 기정 처리가 유효한 경우, 필터 그래프 매니저는 이 파라미터를 제로로 설정한다.

EC_DEVICE_LOST

이벤트 통지 코드

플러그 & 플레이 디바이스가 떼어내진, 또는 다시 사용할 수 있게 되었다.

파라미터

lParam1
디바이스를 나타내는 필터의 IUnknown 인터페이스에의 포인터.
lParam2
디바이스가 떼어내졌을 경우는 제로, 디바이스가 다시 사용 가능하게 되었을 경우는 1.

기정 처리

없음.

주의

디바이스가 다시 사용 가능하게 되면(자), 디바이스 필터의 전 상태는 이미 유효한 것은 없어진다. 어플리케이션이 디바이스를 사용하기 위해서는, 그래프를 재구축 할 필요가 있다.

EC_DISPLAY_CHANGED

이벤트 통지 코드

표시 모드가 변경되었다.

파라미터

lParam1
비디오 렌더러의 입력 핀의 IPin 인터페이스에의 포인터, 또는 제로.
lParam2
제로.

기정 처리

필터 그래프 매니저는 그래프를 일시적으로 정지하고 나서, 비디오 렌더러의 접속 해제와 재접속을 실시한다. 어플리케이션에는 이벤트를 송신하지 않는다.

주의

비디오 렌더러는, WM_DISPLAYCHANGE 메세지에의 응답으로서 이 이벤트를 송신할 수 있다. WM_DISPLAYCHANGE 메세지는, 유저가 디스플레이 해상도를 변경한 것을 나타낸다.

핀 접속중에, 대부분의 비디오 렌더러는 현재의 디스플레이 모드에 근거해 포맷을 선택한다. 디스플레이 모드가 변경되면(자), 비디오 렌더러는 다른 포맷을 선택해야 하는 것이 많다. 이 메세지를 송신하는 것으로, 렌더러는 재접속할 필요가 있는 것을 필터 그래프 매니저에 대해서 통지한다. 재접속중에, 렌더러는 새로운 포맷을 선택할 수 있다. 재접속에 실패 하면, 필터 그래프 매니저는 어플리케이션에 대해서 EC_ERRORABORT 이벤트를 송신한다.

EC_END_OF_SEGMENT

이벤트 통지 코드

세그먼트(segment)의 끝나에 도달했다.

파라미터

lParam1
세그먼트(segment)의 시작 이후의 누적 스트림 시간을 나타내는 REFERENCE_TIME 값에의 포인터.
lParam2
세그먼트(segment) 번호 (제로로부터 시작)를 나타내는 DWORD 값.

기정 처리

필터 그래프 매니저는, EC_END_OF_SEGMENT 이벤트의 번호와 EC_SEGMENT_STARTED 이벤트의 번호를 비교한다. 일치하는 경우는, EC_END_OF_SEGMENT 이벤트를 어플리케이션에 전송 한다.

주의

이 이벤트 코드는 심리스 looping를 지원 하고 있다. IMediaSeeking::SetPositions 메소드의 호출에 AM_SEEKING_Segment 플래그가 설정되어 있는 경우, 소스 필터는 IPin::EndOfStream 를 호출하는 대신에, 이 이벤트 코드를 송신한다.

EC_ERROR_STILLPLAYING

이벤트 통지 코드

그래프를 실행하는 비동기 커멘드가 실패했다.

파라미터

lParam1
실패한 처리의 HRESULT 값.
lParam2
제로.

기정 처리

없음.

주의

필터 그래프 매니저가 비동기 실행 커멘드를 발행해, 그것이 실패했을 경우, 어플리케이션에 이 이벤트를 송신한다. 그래프는 실행중 상태대로 된다. 기저가 되는 필터 상태는 부정이다. 어느 필터는 실행중일 가능성도 있지만, 다른 필터는 다를 가능성도 있다.

EC_ERRORABORT

이벤트 통지 코드

에러이기 때문에 조작이 중지되었다.

파라미터

lParam1
실패한 처리의 HRESULT 값.
lParam2
제로.

기정 처리

없음.

EC_FULLSCREEN_LOST

이벤트 통지 코드

비디오 렌더러가 풀 스크린 모드로부터 빠지려 하고 있다.

파라미터

lParam1
제로.
lParam2
비디오 렌더러의 IBaseFilter 인터페이스에의 포인터, 또는 NULL.

기정 처리

없음.

주의

풀 스크린 렌더러가 액티브하지 않게 되면(자), 이 이벤트를 송신한다. 다른 비디오 렌더러가 풀 스크린 모드로부터 빠지면(자), 필터 그래프 매니저는, 렌더러로부터의 EC_ACTIVATE 이벤트에의 응답으로서 이 이벤트를 송신한다.

EC_GRAPH_CHANGED

이벤트 통지 코드

필터 그래프가 변경되었다.

파라미터

lParam1
제로.
lParam2
제로.

기정 처리

없음.

주의

이 이벤트 코드는 디버그용이다. 모든 그래프의 변경으로 송신된다고는 할 수 없다.

EC_NEED_RESTART

이벤트 통지 코드

필터가 그래프의 재기동을 요구하고 있다.

파라미터

lParam1
제로.
lParam2
제로.

기정 처리

필터 그래프 매니저는 그래프를 포즈 해 재개한다. 어플리케이션에는 이벤트를 송신하지 않는다.

주의

필터가 스트림 반의 샘플을 거절하는 경우, 업 스트림 핀이 샘플의 전달을 정지한다. 필터는, 이 이벤트를 송신하는 것으로 스트림을 재개할 수 있다. 예를 들어, 오디오 렌더러는, 비디오 윈도우가 포커스를 잃었기 때문에 사운드 디바이스에의 액세스를 잃는 일이 있다. 그 시점에서, 오디오 렌더러는 샘플의 거절을 시작 한다. 사운드 디바이스에의 액세스를 재취득하면(자), 이 이벤트를 송신해, 오디오 스트림을 재개한다.

EC_NOTIFY_WINDOW

이벤트 통지 코드

필터에 비디오 렌더러의 윈도우를 통지한다.

파라미터

lParam1
윈도우의 핸들.
lParam2
제로.

기정 처리

이 이벤트는 DirectShow 로 내부적으로 사용된다. 필터 그래프 매니저는 이 이벤트를 어플리케이션에는 송신하지 않는다. 어플리케이션은, 이 이벤트의 기정 처리를 오버라이드(override) 할 수 없다.

주의

비디오 렌더러가 접속되면(자), 렌더러는, 업 스트림 출력 핀이 IMediaEventSink 인터페이스를 지원 할지 어떨지를 체크한다. 지원 되는 경우, 렌더러는 이 이벤트를 업 스트림 필터에 송신한다.

EC_OLE_EVENT

이벤트 통지 코드

필터가 어플리케이션에 텍스트 캐릭터 라인을 건네주고 있다.

파라미터

lParam1
BSTR 형의 캐릭터 라인.
lParam2
BSTR 형의 캐릭터 라인.

기정 처리

없음.

주의

규약에 의해, 최초의 파라미터에는 타입 정보 (Text 등)를 저장 해, 2 번째의 파라미터에는 텍스트 캐릭터 라인을 저장 한다.

EC_OPENING_FILE

이벤트 통지 코드

그래프가 파일을 열고 있다, 또는 파일을 열어 끝냈다.

파라미터

lParam1
그래프가 파일의 오픈을 시작 하는 경우는 TRUE, 그래프가 파일의 오픈을 실시하지 않은 경우는 FALSE.
lParam2
제로.

기정 처리

없음.

주의

필터는, 파일을 여는데 시간이 걸리는 경우, 이 이벤트를 송신할 수 있다(파일이 네트워크상에 있는 경우 등). 어플리케이션은 이 이벤트를 사용해 유저 인터페이스를 조정한다.

현재로서는, DirectShow 에 포함되는 필터는 모두, 이 이벤트를 송신하지 않는다.

EC_PALETTE_CHANGED

이벤트 통지 코드

비디오 팔레트가 변경되었다.

파라미터

lParam1
제로.
lParam2
제로.

기정 처리

없음.

주의

비디오 렌더러는, 스트림내에서 팔레트의 변경을 검출했을 경우, 이 이벤트를 송신한다.

EC_PAUSED

이벤트 통지 코드

포즈 요구가 완료했다.

파라미터

lParam1
이행 결과를 나타내는 HRESULT 값. 이 값이 S_OK 인 경우, 필터 그래프는 현재 포즈 상태에 있다.
lParam2
제로.

기정 처리

없음.

주의

필터 그래프 매니저는, 비동기 포즈 커멘드가 완료했을 때에, 이 이벤트를 송신한다.

EC_QUALITY_CHANGE

이벤트 통지 코드

품질관리이기 때문에, 그래프가 샘플을 삭제했다.

파라미터

lParam1
제로.
lParam2
제로.

기정 처리

없음.

주의

필터는, 품질 컨트롤 메세지에의 응답으로서 샘플을 삭제하는 경우, 이 이벤트를 송신한다. 이벤트가 송신되는 것은, 품질 레벨을 조정하는 경우뿐이어, 샘플을 삭제할 때마다 송신되는 것은 아니다. 상세한 것에 대하여는, 「품질 컨트롤의 관리」를 참조할것.

EC_REPAINT

이벤트 통지 코드

비디오 렌더러가 재드로잉(Drawing)을 요구하고 있다.

파라미터

lParam1
비디오 렌더러의 입력 핀의 IPin 인터페이스에의 포인터, 또는 NULL.
lParam2
제로.

기정 처리

많은 경우,lParam1 파라미터는, 비디오 렌더러의 입력 핀을 지정한다. 이 경우, 필터 그래프 매니저는, 그 핀에 접속된 출력 핀을 찾아,IMediaEventSink 인터페이스가 있을지 어떨지를 문의한다. 출력 핀이 IMediaEventSink 를 지원 하는 경우, 필터 그래프 매니저는 EC_REPAINT 이벤트 코드를 지정해 IMediaEventSink::Notify 를 호출한다. 이것에 의해, 업 스트림 필터는, 마지막 샘플을 재발송신 할 기회를 얻을 수 있다.

lParam1 가 NULL 인 경우, 출력 핀이 IMediaEventSink 를 지원 하지 않는 경우, 또는 Notify 메소드가 실패했을 경우는, 필터 그래프 매니저 자체가 EC_REPAINT 이벤트를 처리한다. 그 동작은, 그래프 상태에 의해 다음의 어느 쪽인가에 된다.

  • 실행중:이벤트를 무시한다(렌더러가 스트림내의 다음의 샘플을 수신한다).
  • 포즈:그래프의 현재 위치를 시크 한다. 그 때에, 필터는 플래시 되어 데이터는 다시 기다리는 행렬에 넣어진다.
  • 정지:그래프를 포즈 및 정지한다. 그 때에 데이터는 다시 기다리는 행렬에 넣어진다.

기정에서는, 필터 그래프 매니저는 이 이벤트를 어플리케이션에는 송신하지 않는다.

주의

비디오 렌더러는, WM_PAINT 메세지를 받아들여, 표시하는 데이터가 없을 때에, 이 메세지를 송신한다.

EC_SEGMENT_STARTED

이벤트 통지 코드

새로운 세그먼트(segment)가 시작 했다.

파라미터

lParam1
세그먼트(segment)의 시작 이후의 누적 스트림 시간을 나타내는 REFERENCE_TIME 값에의 포인터.
lParam2
세그먼트(segment) 번호 (제로로부터 시작)를 나타내는 DWORD 값.

기정 처리

이 이벤트 통지는 어플리케이션에 송신되지 않는다.

주의

필터가 세그먼트(segment)의 최후로 EC_END_OF_SEGMENT 를 송신할 예정인 경우는, 세그먼트(segment)의 최초로 이 이벤트를 송신한다. 필터 그래프 매니저는, 이 이벤트 통지를 사용해, 세그먼트(segment)의 최후로 몇개의 EC_END_OF_SEGMENT 통지를 받게 되는지를 계산한다.

기정에서는, 필터는 세그먼트(segment)의 마지막에 EC_END_OF_SEGMENT 이벤트를 송신하지 않기 때문에, 이 이벤트를 송신해서는 안된다. 상세한 것에 대하여는, 「AM_SEEKING_Segment 」 및 「IMediaSeeking::SetPositions 」를 참조할것.

EC_SHUTTING_DOWN

이벤트 통지 코드

필터 그래프가 파기전에 슛다운 하고 있다.

파라미터

lParam1
제로.
lParam2
제로.

기정 처리

이 이벤트 통지는 어플리케이션에 송신되지 않는다. 필터 그래프 매니저는,PID 에 대해서 이 이벤트를 송신해, 그래프가 슛다운 하는 것을 통지하는 어플리케이션은, 이 이벤트의 기정 처리를 오버라이드(override) 할 수 없다.

EC_SNDDEV_IN_ERROR

이벤트 통지 코드

입력 핀으로 오디오 디바이스 에러가 발생했다.

파라미터

lParam1
에러가 발생했을 때에 디바이스가 어떻게 액세스 되고 있었는지를 나타내는,SNDDEV_ERR 열거형의 DWORD 값.
lParam2
사운드 디바이스 호출로부터 돌려주어진 에러를 나타내는 DWORD 값.

기정 처리

없음.

EC_SNDDEV_OUT_ERROR

이벤트 통지 코드

출력 핀으로 오디오 디바이스 에러가 발생했다.

파라미터

lParam1
에러가 발생했을 때에 디바이스가 어떻게 액세스 되고 있었는지를 나타내는,SNDDEV_ERR 열거형의 DWORD 값.
lParam2
사운드 디바이스 호출로부터 돌려주어진 에러를 나타내는 DWORD 값.

기정 처리

없음.

EC_STARVATION

이벤트 통지 코드

필터는 충분한 데이터를 받지 않았다.

파라미터

lParam1
제로.
lParam2
제로.

기정 처리

이 이벤트는 어플리케이션에 송신되지 않는다. 필터 그래프가 실행중인 경우, 필터 그래프 매니저는 그래프를 포즈 해, 포즈가 완료할 때까지 대기한다. 그 후, 그래프를 다시 실행한다. 이 이벤트를 송신하는 필터가 포즈 상태에의 이행을 완료하려면 , 재개하는데 충분한 데이터를 받지 않으면 안 된다. 필터 그래프가 실행중이 아닌 경우, 필터 그래프 매니저는 이 이벤트를 무시한다.

주의

도착하는 데이터량이 너무 적은 경우에, 퍼서 또는 소스 필터가 이 이벤트를 송신할 수 있다.

EC_STEP_COMPLETE

이벤트 통지 코드

스탭핑(Stepping)를 실행하고 있는 필터가, 지정수의 스탭핑(Stepping)를 완료했다.

파라미터

lParam1
제로.
lParam2
제로.

기정 처리

필터 그래프 매니저는, 그래프를 포즈 해, 이벤트를 어플리케이션에 건네준다.

관련 항목

IVideoFrameStep::Step

EC_STREAM_CONTROL_STARTED

이벤트 통지 코드

스트림 제어 정지 커멘드가 유효하게 되었다.

파라미터

pSender
스트림을 시작 한 핀의 IPin 인터페이스에의 포인터.
dwCookie
유저 정의의 DWORD 값.

기정 처리

없음.

주의

필터는,IAMStreamControl::StartAt 메소드에의 응답으로서 이 이벤트를 송신한다. 이 메소드는, 스트림 송신을 시작 하는 핀의 기준 시간을 지정한다. 스트림 송신이 실제로 시작 된 시점에서, 필터는 이 이벤트를 송신한다.

pSender 파라미터는, 시작 커멘드를 실행하는 핀을 지정한다. 이행 방법에 의해, 이 핀은,StartAt 호출을 받은 핀과는 다른 경우가 있다.

dwCookie 파라미터는,StartAt 메소드로 어플리케이션에 의해 지정된다. 이 파라미터를 사용하면(자), 어플리케이션은 StartAt 메소드의 복수 호출을 추적할 수 있다.

EC_STREAM_CONTROL_STOPPED

이벤트 통지 코드

스트림 제어 정지 커멘드가 유효하게 되었다.

파라미터

pSender
스트림을 정지한 핀의 IPin 인터페이스에의 포인터.
dwCookie
유저 정의의 DWORD 값.

기정 처리

없음.

주의

필터는,IAMStreamControl::StopAt 메소드에의 응답으로서 이 이벤트를 송신한다. 이 메소드는, 스트림 송신을 정지하는 핀의 기준 시간을 지정한다. 스트림 송신이 실제로 정지된 시점에서, 필터는 이 이벤트를 송신한다.

pSender 파라미터는, 정지 커멘드를 실행하는 핀을 지정한다. 이행 방법에 의해, 이 핀은,StopAt 호출을 받은 핀과는 다른 경우가 있다.

dwCookie 파라미터는,StopAt 메소드로 어플리케이션에 의해 지정된다. 이 파라미터를 사용하면(자), 어플리케이션은 StopAt 메소드의 복수 호출을 추적할 수 있다.

EC_STREAM_ERROR_STILLPLAYING

이벤트 통지 코드

스트림내에 에러가 발생했다. 스트림은 계속해 재생중이다.

파라미터

lParam1
실패한 처리의 HRESULT 값.
lParam2
DWORD 값, 보통은 제로.

기정 처리

없음. 어플리케이션은 그래프를 정지할지 어떨지 결정하지 않으면 안 된다.

EC_STREAM_ERROR_STOPPED

이벤트 통지 코드

에러이기 때문에 스트림이 정지했다.

파라미터

lParam1
실패한 처리의 HRESULT 값.
lParam2
DWORD 값, 보통은 제로.

기정 처리

없음.

EC_USERABORT

이벤트 통지 코드

유저가 재생을 강제 종료했다.

파라미터

lParam1
제로.
lParam2
제로.

기정 처리

없음. 어플리케이션은 그래프를 정지할지 어떨지 결정하지 않으면 안 된다.

주의

이 이벤트 코드는, 유저가 보통의 그래프 재생을 강제 종료한 것을 통지한다. 예를 들어, 비디오 렌더러는, 유저가 비디오 윈도우를 닫았을 경우, 이 이벤트를 송신한다.

이 이벤트의 송신 후, 필터가 정지해 리셋 될 때까지, 필터는 모든 샘플을 거절해,EC_REPAINT 이벤트를 송신하지 않는다.

EC_VIDEO_SIZE_CHANGED

이벤트 통지 코드

네이티브 비디오 사이즈가 변경되었다.

파라미터

lParam1
하위 WORD 가 새로운 폭을 픽셀 단위로 지정해, 상위 WORD 가 새로운 높이를 픽셀 단위로 지정한다.
lParam2
제로.

기정 처리

없음.

주의

비디오 렌더러는, 네이티브 비디오 사이즈의 변경을 검출했을 경우, 이 이벤트를 송신한다.

EC_WINDOW_DESTROYED

이벤트 통지 코드

비디오 렌더러가 파기 또는 그래프로부터 삭제되었다.

파라미터

lParam1
비디오 렌더러의 IBaseFilter 인터페이스에의 포인터.
lParam2
제로.

기정 처리

필터 그래프 매니저는,IResourceManager 인터페이스를 개입시켜, 이 윈도우와 포커스를 해방한다. 어플리케이션에는 이벤트 통지를 송신하지 않는다.

주의

비디오 렌더러는, 필터 그래프를 IBaseFilter::JoinFilterGraph 메소드에 남길 때, 이 이벤트를 송신한다(필터가 파기되는 시점에서, 필터 그래프 매니저도 파기될 가능성이 있으므로, 필터의 파기시에 이 이벤트를 송신하는 것은 너무 늦다).

이 이벤트에 의해, 다른 필터는, 오디오 디바이스 등, 윈도우 포커스에 의존하는 리소스를 취득할 수 있다.


필터 카테고리

다음의 표는, 필터 카테고리의 CLSID 의 일람을 나타내고 있다. 특정의 카테고리의 필터를 열거하려면 , 해당하는 CLSID 를 ICreateDevEnum::CreateClassEnumerator 메소드에 건네준다. 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것.

이러한 카테고리는,[Graph] 메뉴의 [Insert Filters] 를 선택했을 때에도 GraphEdit 에 표시된다. 상세한 것에 대하여는, 「GraphEdit 에 의한 그래프 구축의 시뮬레이션」을 참조할것.

CLSID | 설명
CLSID_AudioInputDeviceCategory | 오디오 캡춰 필터.
CLSID_AudioCompressorCategory | 오디오 압력, 오디오 엔코더.
CLSID_AudioRendererCategory | 오디오 렌더러.
CLSID_LegacyAmFilterCategory | 디코더를 포함한 그 외의 필터.
CLSID_MidiRendererCategory | MIDI 렌더러.
CLSID_VideoInputDeviceCategory | 비디오 캡춰 필터.
CLSID_VideoCompressorCategory | 비디오 압력, 비디오 엔코더.
CLSID_ActiveMovieCategories | 카테고리의 리스트가 포함된 메타카테고리. GraphEdit 는 이 CLSID 를 사용해 모든 카테고리를 열거한다. 보통, 어플리케이션에서는, 이 CLSID 를 사용하지 않는다.


미디어 타입

Microsoft® DirectShow® 에서는,AM_MEDIA_TYPE 구조체를 사용해 미디어 샘플을 기술한다. 이 구조체에는,메이저 타입, 서브 타입, 및포맷 타입의 GUID 멤버 외에, 샘플이 압축되고 있는지 어떤지 등, 샘플의 그 외의 특성을 나타내는 필드가 포함되어 있다. 이 주제에서는, DirectShow 에 의해 등록되는 메이저 타입 및 서브 타입의 옵션의 개요에 대해 설명한다. 이러한 미디어 타입은, Uuids.h 로 정의되고 있다.

이 주제는, 이하의 섹션으로 구성된다.

  • 메이저 타입
  • 오디오 서브 타입
  • Line 21 서브 타입
  • MPEG-2 서브 타입
  • 스트림 서브 타입
  • 비디오 서브 타입
  • 아날로그 비디오 서브 타입

메이저 타입

다음의 표는, 메이저 미디어 타입을 나타내고 있다.

GUID | 설명
MEDIATYPE_AnalogAudio | 아날로그 오디오.
MEDIATYPE_AnalogVideo | 아날로그 비디오.
MEDIATYPE_Audio | 오디오.
MEDIATYPE_AUXLine21Data | Line 21 데이터. 자막 방송에 의해 사용된다.
MEDIATYPE_File | 파일. 자막 방송에 의해 사용된다.
MEDIATYPE_Interleaved | 인터리브. 디지털 비디오 (DV)에 의해 사용된다.
MEDIATYPE_LMRT | 폐지. 사용하지 않는 것.
MEDIATYPE_Midi | MIDI 포맷.
MEDIATYPE_MPEG2_PES | MPEG-2. DVD 에 의해 사용된다.
MEDIATYPE_ScriptCommand | 데이터는, 자막 방송에 의해 사용되는 스크립 코맨드이다.
MEDIATYPE_Stream | 타임 스탬프가 없는 바이트 스트림.
MEDIATYPE_Text | 텍스트.
MEDIATYPE_Timecode | 타임 코드 데이터.
MEDIATYPE_URL_STREAM | 폐지. 사용하지 않는 것.
MEDIATYPE_Video | 비디오.

오디오 서브 타입

다음의 표는, 오디오 미디어 서브 타입을 나타내고 있다.

GUID | 설명
MEDIASUBTYPE_PCMAudio | PCM 오디오
MEDIASUBTYPE_PCMAudioObsolete | 폐지. 사용하지 않는 것.
MEDIASUBTYPE_MPEG1Packet | MPEG1 오디오 패킷
MEDIASUBTYPE_MPEG1Payload | MPEG1 오디오 유료 하중

WAVEFORMATEX 구조체의 wFormatTag 필드는, 오디오 포맷 타입을 지정한다. 일반적으로 포맷 타입은, FORMAT_WaveFormatEx 이다. 미디어 샘플은, 일반적으로,WAVEFORMATEX 구조체의 wBitsPerSample 필드에서 지정되는 샘플 전체이다. 이 조건은, 원이 패킷화 된 스트림일 가능성이 있어, 따라, 반드시 샘플/프레임 경계상에 패키지되어 있지 않은 MPEG 오디오 샘플에는 들어맞지 않는다. MPEG 오디오의 경우, 미디어 샘플의타임 스탬프는, 프레임의 최초의 바이트가 미디어 샘플에 포함되어 있는 최초의 프레임의 타임 스탬프이다.

각각의 wFormatTag 에 대응하는 미디어 서브 타입의 정의를 다음에 나타낸다.

  • 미디어 서브 타입의 Data1 서브 필드는,wFormatTag 값과 같다.
  • Data 2 필드는 0.
  • Data 3 필드는 0x0010.
  • Data 4 필드는, 0 x80, 0 x00, 0 x00, 0 xAA, 0 x00, 0 x38, 0 x9B, 0x71.

따라서, PCM 오디오의 서브 타입 GUID 는, 다음과 같이 된다.

{00000001-0000-0010-8000-00AA00389B71}

낡은 필터에서는, GUID_NULL 를 서브 타입으로서 사용하고 있는 일이 있기 (위해)때문에, 이것을 체크할 필요가 있다. 다만, 명시적인 서브 타입을 사용해 필터를 등록 하면, 특히 특정의 필터가 필요한 것으로 되어 있지 않은 경우는, 그래프의 read 속도가 큰폭으로 향상한다. CreateAudioMediaType 함수를 사용해,WAVEFORMATEX 구조체로부터 AM_MEDIA_TYPE 구조체를 생성 할 수 있다.

Line 21 서브 타입

다음의 표는, Line 21 자막 방송 미디어 서브 타입을 나타내고 있다.

GUID | 설명
MEDIASUBTYPE_Line21_BytePair | 바이트 페어로서의 Line 21 데이터
MEDIASUBTYPE_Line21_GOPPacket | DVD GOP 패킷의 Line 21 데이터
MEDIASUBTYPE_Line21_VBIRawData | 생의 VBI 포맷의 Line 21 데이터

MPEG-2 서브 타입

다음의 표는, MPEG-2 미디어 서브 타입을 나타내고 있다.

GUID | 설명
MEDIASUBTYPE_DVD_SUBPICTURE | 서브 픽쳐 데이터
MEDIASUBTYPE_DOLBY_AC3 | Dolby 데이터
MEDIASUBTYPE_MPEG2_AUDIO | MPEG-2 오디오 데이터
MEDIASUBTYPE_DVD_LPCM_AUDIO | DVD 오디오 데이터
MEDIASUBTYPE_MPEG2_TRANSPORT | MPEG-2 트랜스폴트 스트림
MEDIASUBTYPE_MPEG2_PROGRAM | MPEG2 프로그램 스트림

스트림 서브 타입

다음의 표는, 스트림 미디어 서브 타입을 나타내고 있다.

GUID | 설명
MEDIASUBTYPE_AIFF | AIFF 파일의 데이터
MEDIASUBTYPE_Asf | ASF (Advanced Streaming Format)
MEDIASUBTYPE_Avi | AVI 파일의 데이터
MEDIASUBTYPE_AU | AU 파일의 데이터
MEDIASUBTYPE_DssAudio | Dss Audio
MEDIASUBTYPE_DssVideo | Dss Video
MEDIASUBTYPE_MPEG1Audio | MPEG 오디오
MEDIASUBTYPE_MPEG1System | MPEG 시스템
MEDIASUBTYPE_MPEG1SystemStream | 폐지. 사용하지 않는 것.
MEDIASUBTYPE_MPEG1Video | MPEG 비디오
MEDIASUBTYPE_MPEG1VideoCD | MPEG 비디오 CD
MEDIASUBTYPE_WAVE | WAV 파일의 데이터

타임 스탬프는, 리얼타임은 아니고, 바이트 위치 * 10000000 (1 초에 대해 1 바이트)이다.

비디오 서브 타입

다음의 표는, 비디오 미디어 서브 타입을 나타내고 있다.

GUID | 설명
MEDIASUBTYPE_YVU9 | 표준 YVU9 포맷비압축 데이터. 평면 YUV 포맷. 모든 수평 라인의 모든 픽셀로 Y 의 샘플링을 실시해, 4 픽셀 마다 U 와 V 의 샘플링을 실시한다. 모든 수직 라인으로 Y 의 샘플링을 실시해, 수직 라인 4 개 마다 U 와 V 의 샘플링을 실시한다. 1 픽셀에 대해 9 비트.
MEDIASUBTYPE_Y411 | YUV 411 포맷 데이터. Y41P 와 같다.
MEDIASUBTYPE_Y41P | Y41P 포맷 데이터. 팩 된 YUV 포맷. 모든 수평 라인의 모든 픽셀로 Y 의 샘플링을 실시해, 4 픽셀 마다 U 와 V 의 샘플링을 실시한다. 모든 수직 라인을 샘플링 한다. 바이트의 순서는, 최하정도로부터 순서에, U0, Y0, V0, Y1, U4, Y2, V4, Y3, Y4, Y5, Y6, Y7 이며, 사픽스 0 은 좌단의 픽셀로, 번호가 큰 만큼 픽셀은 오른쪽 가까이가 된다. 12 바이트의 블록이 8 화면 픽셀에 상당한다.
MEDIASUBTYPE_YUY2 | YUY2 포맷 데이터. 픽셀의 순서를 제외해 UYVY 와 같다. 바이트의 순서는, 최하정도로부터 순서에, Y0, U0, Y1, V0, Y2, U2, Y3, V2, Y4, U4, Y5, V4 이며, 사픽스 0 은 좌단의 픽셀로, 번호가 큰 만큼 픽셀은 오른쪽 가까이가 된다. 4 바이트의 블록이 2 화면 픽셀에 상당한다.
MEDIASUBTYPE_YVYU | YVYU 포맷 데이터. 팩 된 YUV 포맷. 픽셀의 순서를 제외해 UYVY 와 같다. 바이트의 순서는, 최하정도로부터 순서에, Y0, V0, Y1, U0, Y2, V2, Y3, U2, Y4, V4, Y5, U4 이며, 사픽스 0 은 좌단의 픽셀로, 번호가 큰 만큼 픽셀은 오른쪽 가까이가 된다. 4 바이트의 블록이 2 화면 픽셀에 상당한다.
MEDIASUBTYPE_UYVY | UYVY 포맷 데이터. 팩 된 YUV 포맷. 모든 수평 라인의 모든 픽셀로 Y 의 샘플링을 실시해, 2 픽셀 마다 U 와 V 의 샘플링을 실시한다. 모든 수직 라인을 샘플링 한다. 다양한 YUV 4:2:2 포맷 중(안)에서도 가장 잘 사용되고 있다. 바이트의 순서는, 최하정도로부터 순서에, U0, Y0, V0, Y1, U2, Y2, V2, Y3, U4, Y4, V4, Y5 이며, 사픽스 0 은 좌단의 픽셀로, 번호가 큰 만큼 픽셀은 오른쪽 가까이가 된다. 4 바이트의 블록이 2 화면 픽셀에 상당한다.
MEDIASUBTYPE_Y211 | YUV 211 포맷 데이터. 팩 된 YUV 포맷. 모든 수평 라인으로 2 픽셀 마다 Y 의 샘플링을 실시해, 4 픽셀 마다 U 와 V 의 샘플링을 실시한다. 모든 수직 라인을 샘플링 한다. 바이트의 순서는, 최하정도로부터 순서에, Y0, U0, Y2, V0, Y4, U4, Y6, V4, Y8, U8, Y10, V8 이며, 사픽스 0 은 좌단의 픽셀로, 번호가 큰 만큼 픽셀은 오른쪽 가까이가 된다. 4 바이트의 블록이 4 화면 픽셀에 상당한다.
MEDIASUBTYPE_CLJR | Y, U, V 샘플 1 개(살)에 대해 8 비트 미만의 Cirrus Logic Jr YUV 411 포맷. Cinepak 에서는 이것을 생성할 수 있어 Cirrus 5440 에서는 이것을 사용해 오버레이를 생성할 수 있다. 모든 수평 라인의 모든 픽셀로 Y 의 샘플링을 실시해, 4 픽셀 마다 U 와 V 의 샘플링을 실시한다. 모든 수직 라인을 샘플링 한다.
MEDIASUBTYPE_IF09 | 마지막 프레임과의 차이에 관한 추가 정보가 포함된, Indeo 로 생성되는 YVU9 포맷. 1 픽셀에 대해 9.5 비트이지만, 9 로서 보고된다.
MEDIASUBTYPE_CPLA | Cinepak UYVY 포맷.
MEDIASUBTYPE_MJPG | Motion JPEG (MJPG) 압축 비디오.
MEDIASUBTYPE_TVMJ | TrueVision MJPG 포맷.
MEDIASUBTYPE_WAKE | 일부의 카드에 의해 생성되는 MJPG 포맷.
MEDIASUBTYPE_CFCC | 일부의 카드에 의해 생성되는 MJPG 포맷.
MEDIASUBTYPE_IJPG | Intergraph JPEG 포맷.
MEDIASUBTYPE_Plum | Plum MJPG 포맷.
MEDIASUBTYPE_RGB1 | 1 픽셀에 대해 RGB 1 비트. 팔레트화 되고 있다.
MEDIASUBTYPE_RGB4 | 1 픽셀에 대해 RGB 4 비트. 팔레트화 되고 있다.
MEDIASUBTYPE_RGB8 | 1 픽셀에 대해 RGB 8 비트. 팔레트화 되고 있다.
MEDIASUBTYPE_RGB565 | RGB 의 565 포맷, 1 픽셀에 대해 16 비트. 비압축 RGB 샘플.
MEDIASUBTYPE_RGB555 | RGB 의 555 포맷, 1 픽셀에 대해 16 비트. 비압축 RGB 샘플.
MEDIASUBTYPE_RGB24 | 1 픽셀에 대해 RGB 24 비트. 비압축 RGB 샘플.
MEDIASUBTYPE_RGB32 | 1 픽셀에 대해 RGB 32 비트. 비압축 RGB 샘플. 이 미디어 타입에서는 알파 비트는 사용하지 않는 것 (MEDIASUBTYPE_ARGB32 와 비교).
MEDIASUBTYPE_ARGB32 | 1 픽셀에 대해 ARGB 32 비트. 유효한 알파 비트를 가지는 비압축 RGB 샘플.
MEDIASUBTYPE_Overlay | 하드웨어 오버레이를 사용해 전달되는 비디오.
MEDIASUBTYPE_QTMovie | Apple® QuickTime® 압축.
MEDIASUBTYPE_QTRpza | Quicktime RPZA 압축 데이터.
MEDIASUBTYPE_QTSmc | Quicktime SMC 압축 데이터.
MEDIASUBTYPE_QTRle | Quicktime RLE 압축 데이터.
MEDIASUBTYPE_QTJpeg | Quicktime JPEG 압축 데이터.
MEDIASUBTYPE_dvsd | 표준 DV 포맷.
MEDIASUBTYPE_dvhd | 고품위 DV 포맷.
MEDIASUBTYPE_dvsl | 롱 플레이 DV 포맷.
MEDIASUBTYPE_MPEG1Packet | MPEG1 비디오 패킷.
MEDIASUBTYPE_MPEG1Payload | MPEG1 비디오 유료 하중.
MEDIASUBTYPE_VideoPort | DVD 로 사용되는 비디오 포토 데이터.
MEDIASUBTYPE_VPVideo | 비디오 포토 비디오 데이터.
MEDIASUBTYPE_VPVBI | 비디오 포토 수직 동기 간격 (VBI) 데이터.

아날로그 비디오 서브 타입

이하의 아날로그 비디오 포맷은 Microsoft® ActiveMovie® 1.0 으로 도입되었지만, 현재는 사용되지 않았다. 그 대신에,IAMAnalogVideoDecoder 인터페이스와 IAMTVTuner 인터페이스는,AnalogVideoStandard 열거를 사용한다.
GUID | 설명
MEDIASUBTYPE_AnalogVideo_NTSC_M | (M) NSTC
MEDIASUBTYPE_AnalogVideo_PAL_B | (B) PAL
MEDIASUBTYPE_AnalogVideo_PAL_D | (D) PAL
MEDIASUBTYPE_AnalogVideo_PAL_G | (G) PAL
MEDIASUBTYPE_AnalogVideo_PAL_H | (H) PAL
MEDIASUBTYPE_AnalogVideo_PAL_I | (I) PAL
MEDIASUBTYPE_AnalogVideo_PAL_M | (M) PAL
MEDIASUBTYPE_AnalogVideo_PAL_N | (N) PAL
MEDIASUBTYPE_AnalogVideo_SECAM_B | (B) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_D | (D) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_G | (G) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_H | (H) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_K | (K) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_K1 | (K1) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_L | (L) SECAM


MPEG-1 미디어 타입

여기에서는, Microsoft® DirectShow® 가 MPEG 데이터에 사용하는 미디어 타입에 대해 설명한다.

MPEG-1 시스템 스트림
메이저 타입 :MEDIATYPE_Stream

마이너 타입 :MEDIASUBTYPE_MPEG1System

포맷:없음

샘플의 내용 :BYTE 스트림, 조정 없음

비디오 CD 의 MPEG-1 시스템 스트림
메이저 타입 :MEDIATYPE_Stream

마이너 타입 :MEDIASUBTYPE_MPEG1VideoCD

포맷:없음

샘플의 내용 :BYTE 스트림, 조정 없음

MPEG-1 오디오 패킷
메이저 타입 :MEDIATYPE_Audio

마이너 타입 :MEDIASUBTYPE_MPEG1Packet

포맷 :MPEG1WAVEFORMAT

샘플의 내용:패킷 헤더가 포함된 단일의 MPEG-1 패킷

MPEG-1 오디오 유료 하중
메이저 타입 :MEDIATYPE_Audio

마이너 타입 :MEDIASUBTYPE_MPEG1Payload

포맷 :MPEG1WAVEFORMAT

샘플의 내용:바이트 조정된 MPEG-1 오디오 데이터

MPEG-1 비디오 패킷
메이저 타입 :MEDIATYPE_Video

마이너 타입 :MEDIASUBTYPE_MPEG1Packet

포맷 :VIDEOINFO + 비디오 순서 헤더

샘플의 내용:패킷 헤더가 포함된 단일의 MPEG-1 패킷

MPEG-1 비디오 유료 하중
메이저 타입 :MEDIATYPE_Video

마이너 타입 :MEDIASUBTYPE_MPEG1Payload

포맷 :VIDEOINFO + 비디오 순서 헤더

샘플의 내용:바이트 조정된 MPEG-1 비디오 데이터

MPEG-1 네이티브 비디오 스트림
메이저 타입 :MEDIATYPE_Stream

마이너 타입: MEDIASUBTYPE_ MPEG1Video

포맷:없음

샘플의 내용:비디오 스트림 바이트의 배열 (시스템 계층 없음)

MPEG-1 네이티브 오디오 스트림
메이저 타입 :MEDIATYPE_Stream

마이너 타입: MEDIASUBTYPE_ MPEG1Audio

포맷:없음

샘플의 내용:오디오 스트림 바이트의 배열 (시스템 계층 없음)

다양한 필터는, 다음과 같이 핀을 지원 한다.

필터 | 방향 | 미디어 타입
시스템 계층 스플리터 | 입력 | MPEG-1 시스템 스트림 비디오 CD 의 MPEG-1 시스템 스트림
시스템 계층 스플리터 | 출력 | MPEG-1 오디오 패킷 또는 MPEG-1 오디오 데이터
시스템 계층 스플리터 | 출력 | MPEG-1 비디오 패킷 또는 MPEG-1 비디오 데이터
소프트웨어 오디오 CODEC | 입력 | MPEG-1 오디오 데이터 또는 MPEG-1 오디오 패킷
소프트웨어 비디오 CODEC | 입력 | MPEG-1 비디오 데이터 또는 MPEG-1 비디오 패킷
소프트웨어 오디오 CODEC | 출력 | PCM 오디오 물건 또는 스테레오, 입력 샘플링 레이트, 입력 샘플링 레이트의 2 분의 1 또는 입력 샘플링 레이트의 4 분의 1
소프트웨어 비디오 CODEC | 출력 | Y41P, YUY2, UYVY, RGB24, RGB32, RGB565, RGB555, RGB8 포맷의 비압축 비디오

순서 헤더가 비디오 재생을 초기화하지 않아도 파일의 도중부터 데이터를 재생할 수 있도록(듯이), MPEG-1 비디오 패킷과 유료 하중의 미디어 타입에는 완전한 순서 헤더가 포함되어 있다.

스트림의 도중부터 재생을 시작 할 수 있도록(듯이), MPEG 비디오의 비디오 데이터 타입에는 비디오 순서 헤더가 추가된다. 이필드의 길이는, 최대 140 바이트이다. 이 필드의 선두 및 최초의 순서 헤더내에서 발견된 양자화 matrices에는, 순서 헤더 시작 코드 —0x000001B3— 가 포함되어 있다.


MPEG-2 스플리터 필터 미디어 타입

현재,MPEG-2 스플리터는, 오디오와 비디오를 지원 하고 있다. Dolby AC-3 는 DVD 로 정의되고 있는 서브 스트림으로서 지원 되고 있다. MPEG-2 오디오도 지원 되고 있다.

비디오의 타입을 다음에 나타낸다.

 | PES 출력 | Payload 출력
타입 | MEDIATYPE_MPEG2_PES | MEDIATYPE_Video
서브 타입 | MEDIASUBTYPE_MPEG2_VIDEO | MEDIASUBTYPE_MPEG2_VIDEO
포맷 | FORMAT_MPEG2Video | FORMAT_MPEG2Video
포맷 블록 | MPEG2VIDEOINFO | MPEG2VIDEOINFO

AC-3 오디오의 타입을 다음에 나타낸다.

 | PES 출력 | Payload 출력
타입 | MEDIATYPE_MPEG2_PES | MEDIATYPE_Audio
서브 타입 | MEDIASUBTYPE_DOLBY_AC3 | MEDIASUBTYPE_DOLBY_AC3
포맷 | FORMAT_WaveFormatEx | FORMAT_WaveFormatEx
포맷 블록 | WAVEFORMATEX | WAVEFORMATEX

AC-3 에 대응하는 WAVEFORMATEX 구조체의 wFormatTag 멤버는, 현재 WAVE_FORMAT_UNKNOWN 이지만, 바뀔 가능성이 있기 (위해)때문에, 확인할 필요가 있다.

MPEG-2 의 타입을 다음에 나타낸다.

 | PES 출력 | Payload 출력
타입 | MEDIATYPE_MPEG2_PES | MEDIATYPE_Audio
서브 타입 | MEDIASUBTYE_MPEG2_AUDIO | MEDIASUBTYPE_MPEG2_AUDIO
포맷 | FORMAT_WaveFormatEx | FORMAT_WaveFormatEx
포맷 블록 | WAVEFORMATEX | WAVEFORMATEX

MPEG-2 오디오에 대응하는 WAVEFORMATEX 구조체의 wFormatTag 멤버는, 현재 WAVE_FORMAT_UNKNOWN 이지만, 바뀔 가능성이 있기 (위해)때문에, 확인할 필요가 있다.

MPEG-2 스플리터에서는, DVD MPEG-2 오디오의 경우와 같게, 스트림 D0 ~ DF 가 멀티 채널 확장 스트림에 사용되고 있으면(자) 상정하고 있기 (위해)때문에, 스트림 Cx 가 선택되고 있으면(자), 스플리터는 반드시 스트림 Dx 의 패킷도 전송 한다.

LPCM 오디오의 타입을 다음에 나타낸다.

 | PES 출력 | Payload 출력
타입 | MEDIATYPE_MPEG2_PES | MEDIATYPE_Audio
서브 타입 | MEDIASUBTYPE_DVD_LPCM_AUDIO | MEDIASUBTYPE_DVD_LPCM_AUDIO
포맷 | FORMAT_WaveFormatEx | FORMAT_WaveFormatEx
포맷 블록 | WAVEFORMATEX | WAVEFORMATEX

LPCM 오디오에 대응하는 WAVEFORMATEX 구조체의 wFormatTag 멤버는, 현재 WAVE_FORMAT_UNKNOWN 이지만, 바뀔 가능성이 있기 (위해)때문에, 확인할 필요가 있다.


메리트

그래프를 구축중에, 필터 그래프 매니저가 필터를 시행하는 순서를 정의한다. 「필터 그래프의 구축」도 참조할것.

구문

enum
{
    MERIT_PREFERRED     = 0x800000,
    MERIT_NORMAL        = 0x600000,
    MERIT_UNLIKELY      = 0x400000,
    MERIT_DO_NOT_USE    = 0x200000,
    MERIT_SW_COMPRESSOR = 0x100000,
    MERIT_HW_COMPRESSOR = 0x100050
};

주의

각 필터에는,메리트값이 등록된다. 필터 그래프 매니저는, 그래프를 구축할 때에, 적절한 미디어 타입에 등록되어 모든 필터를 열거한다. 다음에 필터 그래프 매니저는, 메리트의 상위에서 하위의 순서에 필터를 시행한다. (메리트값이 같은 필터에 대해서는 다른 조건을 적용한다. ) 필터 그래프 매니저는, 메리트값이 MERIT_DO_NOT_USE 이하의 필터는 시행하지 않는다.

보통 재생에 대해 고려되어야 하는 것이 아닌 필터는, MERIT_DO_NOT_USE 이하의 메리트를 가질 필요가 있다. 필터에는, 여기에 올리지 않은 중간값 (예를 들어 MERIT_NORMAL + 1)을 등록할 수가 있다.


타임 포맷 GUID

다음의 글로벌 유니크 식별자 (GUID )는 다른 타임 포맷을 정의한다.

선언 : Uuids.h

GUID | 설명
TIME_FORMAT_NONE | 포맷 없음.
TIME_FORMAT_FRAME | 비디오 포맷.
TIME_FORMAT_SAMPLE | 스트림내의 샘플.
TIME_FORMAT_FIELD | 인터레이스 비디오 포맷.
TIME_FORMAT_BYTE | 스트림내의 바이트 오프셋(offset).
TIME_FORMAT_MEDIA_TIME | 미디어 타임 (100 나노초단위).

참조

IMediaSeeking


함수

Microsoft® DirectShow® 에서는 이하의 함수를 제공한다 :

AMGetErrorText 임의의 메세지 ID 의 에러 메세지 텍스트를 취득한다.

AMGetErrorText

함수

현재의 언어의 설정을 사용해, 귀가 코드에 대응하는 에러 메세지를 취득한다.

이 함수는,HRESULT 의 귀가 코드를 에러 메세지로 변환한다. 정수 MAX_ERROR_TEXT_LEN 는, 에러 메세지의 최대 문자수를 지정한다.

주 : 이 함수를 사용하기 위해서(때문에)는, 어플리케이션은 라이브러리 파일 Quartz.lib 에 링크해야 한다.

구문

DWORD AMGetErrorText(
    HRESULT hr,
    TCHAR *pBuffer,
    DWORD MaxLen
    );

파라미터

hr
HRESULT 값.
pBuffer
에러 메세지를 받아들이는 문자 버퍼에의 포인터.
MaxLen
pBuffer 의 최대 문자수.

반환값

버퍼에 돌려주어진 문자수를 돌려준다. 에러가 발생했을 경우는, 제로를 돌려준다.


MSWebDVD 에 관한 참조 페이지

Microsoft® MSWebDVD ActiveX® 컨트롤을 사용하는 것에 의해, 스크립트 베이스의 DVD 어플리케이션을 생성 할 수 있다. 이 ActiveX 컨트롤은, 이하의 오브젝트 및 이벤트를 어플리케이션에 대해서 공개한다.

  • MSWebDVD
  • MSDVDAdm
  • DVDRect
  • MSWebDVD 이벤트


MSWebDVD 오브젝트

MSWebDVD 오브젝트의 메소드, 프로퍼티, 및 이벤트를 사용 하면, 어플리케이션으로부터 DVD 비디오의 네비게이션 및 재생을 완전하게 제어해, 디스크로부터 정보를 취득할 수가 있다. MSWebDVD 오브젝트는, 네비게이션 처리 자체는 실행하지 않고 ,DVD 네비게이터 필터에 커멘드를 건네준다. 이 필터는, DVD 비디오의 디스크를 읽어내는 Microsoft® DirectShow® 컴퍼넌트이다.

MSWebDVD 의 메소드 및 프로퍼티는, DVD 네비게이터의 현재 상태, 디스크 위에의 정보, 또는 그 양쪽 모두에 작용한다. 페어 렌탈 락 레벨 및 디폴트 언어의 유저 설정 등, 레지스트리내에 있는 어플리케이션 고유의 각종 정보를 저장 및 취득하려면 ,MSDVDAdm 오브젝트의 메소드를 사용한다. 이 오브젝트에 액세스 하려면 ,DVDAdm 프로퍼티를 사용한다.

참조

MSWebDVD 이벤트
스크립트 베이스의 DVD 어플리케이션의 기술

메소드 및 프로퍼티 (카테고리별)

재생
CanStep | 로컬 시스템의 MPEG-2 디코더가 스탭핑(Stepping)를 실행할 수 있을지 어떨지를 판단한다.
Eject | 드라이브의 디스크의 꺼내/삽입을 실시한다.
FramesPerSecond | 현재의 DVD 타이틀의 비디오 frame rate를 취득한다.
Pause | 재생을 현재 위치에서 포즈 한다.
Play | 현재의 DVD 타이틀을 재생한다.
PlayAtTime | 현재의 타이틀의 지정된 시간부터 재생을 시작 한다.
PlayAtTimeInTitle | 지정된 타이틀의 지정된 시간부터 재생을 시작 한다.
PlayBackwards | 지정된 속도로 현재 위치로부터 역방향 재생을 시작 한다.
PlayChapter | 현재의 타이틀의 지정된 쳅터로부터 재생을 시작 한다.
PlayChapterInTitle | 지정된 타이틀의 지정된 쳅터를 재생한다.
PlayChaptersAutoStop | 지정된 타이틀의 지정된 쳅터로부터 지정된 쳅터수의 재생을 시작 한다.
PlayForwards | 지정된 속도로 현재 위치로부터 순서 방향 재생을 시작 한다.
PlayNextChapter | 현재의 타이틀의 다음의 쳅터로부터 재생을 시작 한다.
PlayPeriodInTitleAutoStop | 지정된 타이틀의 지정된 시간부터 지정된 종료 타임까지의 재생을 시작 한다.
PlayPrevChapter | 현재의 타이틀의 직전의 타이틀로부터 재생을 시작 한다.
PlayTitle | 지정된 타이틀의 최초부터 재생을 시작 한다.
ReplayChapter | 현재의 쳅터의 최초부터 재생을 시작 한다.
Resume | 메뉴 표시 후에 재생을 재개한다.
StillOff | 재생을 재개해, 정지 모드를 캔슬한다.
Step | DVD 비디오 스트림이 지정된 프레임수만큼 진행한다.
Stop | 재생을 정지한다.
메뉴
ActivateAtPosition | 메뉴 버튼이 지정된 위치에서 액티브하게 한다.
ActivateButton | 선택된 메뉴 버튼을 액티브하게 한다.
ButtonsAvailable | 현재의 메뉴에 포함되는 버튼의 총수를 취득한다.
CurrentButton | 선택된 버튼의 번호를 취득한다.
DefaultMenuLanguage | 디스크로부터 디폴트의 메뉴 언어를 취득한다.
GetButtonAtPosition | 버튼을 선택 또는 액티브하게 하지 않고 , 지정된 좌표에 있는 버튼의 번호를 취득한다.
GetButtonRect | 지정된 버튼의 직사각형을 윈도우 좌표로 취득한다.
ReturnFromSubmenu | 표시를 서브 메뉴로부터 친메뉴에 되돌린다. 톱 레벨 메뉴라면 현재의 타이틀에 되돌린다.
SelectAndActivateButton | 지정된 버튼을 선택해, 액티브하게 한다.
SelectAtPosition | 지정된 위치에 있는 메뉴 버튼을 선택한다.
SelectLeftButton | 표시된 메뉴로부터 좌방향 버튼을 선택한다.
SelectLowerButton | 표시된 메뉴로부터 아래방향 버튼을 선택한다.
SelectRightButton | 표시된 메뉴로부터 우측향버튼을 선택한다.
SelectUpperButton | 표시된 메뉴로부터 윗방향 버튼을 선택한다.
ShowMenu | 지정된 메뉴를 화면상에 표시한다.
오디오 스트림
AudioStreamsAvailable | 현재의 타이틀내의 이용 가능한 오디오 스트림수를 취득한다.
Balance | 오디오 스트림 출력의 스피커 밸런스를 설정 또는 취득한다.
CurrentAudioStream | 유효한 오디오 스트림의 수를 설정 또는 취득한다.
DefaultAudioLanguage | 디스크로부터 디폴트의 오디오 언어를 취득한다.
DefaultAudioLanguageExt | 디스크로부터 디폴트의 오디오 언어 extension를 취득한다.
GetAudioLanguage | 지정된 오디오 스트림 위에의 이용 가능한 언어를 나타내는 캐릭터 라인을 취득한다.
IsAudioStreamEnabled | 지정된 오디오 스트림이 현재의 타이틀로 유효한가 어떤가를 나타내는 값을 취득한다.
Mute | 오디오 스트림 출력의 온/오프를 바꾼다.
SelectDefaultAudioLanguage | DVD 네비게이터내의 현재의 디폴트 오디오 언어를 설정한다.
Volume | 오디오의 볼륨을 설정 또는 취득한다.
서브 픽쳐 스트림
CurrentSubpictureStream | 선택된 서브 픽쳐 스트림을 취득한다.
DefaultSubpictureLanguage | 디스크로부터 디폴트의 서브 픽쳐 언어를 취득한다.
DefaultSubpictureLanguageExt | 디스크로부터 디폴트의 서브 픽쳐 언어 extension를 취득한다.
GetSubpictureLanguage | 지정된 서브 픽쳐 스트림의 언어를 취득한다.
IsSubpictureStreamEnabled | 지정된 서브 픽쳐 스트림이 현재의 타이틀로 유효한가 어떤가를 나타내는 값을 취득한다.
PreferredSubpictureStream | 현재의 표시 세션에 대응하는 유저 설정의 서브 픽쳐 스트림을 설정 또는 취득한다.
SelectDefaultSubpictureLanguage | DVD 네비게이터내의 현재의 디폴트 서브 픽쳐 언어를 설정한다.
SubpictureOn | 서브 픽쳐의 현재 상태 (온/오프)를 설정 또는 취득한다.
SubpictureStreamsAvailable | 현재의 타이틀내의 이용 가능한 서브 픽쳐 스트림수를 취득한다.
비디오 직사각형
AspectRatio | 디스크에 명기된 현재의 비디오 스트림의 어스펙트비(가로세로 비율)을 취득한다.
BackColor | 네이티브 비디오의 어스펙트비(가로세로 비율)이 오브젝트의 표시 영역의 어스펙트비(가로세로 비율)과 다르고 있을 때, 비디오 직사각형의 인연의 주위에 표시되는 바의 색을 설정 또는 취득한다.
Capture | MSWebDVD 오브젝트가 윈드우레스모드 때에, 비디오 프레임으로부터 정지화면을 캡춰 한다.
FullScreenMode | 표시가 풀 스크린 모드인가 어떤가를 나타내는 값을 설정 또는 취득한다.
GetClipVideoRect | 비디오 표시용으로 정의된 클리핑 직사각형을 취득한다.
GetVideoSize | 네이티브 비디오의 넓이를 취득한다.
SetClipVideoRect | 비디오 표시가 차지하는 클리핑 직사각형을 설정한다.
Zoom | 소정의 화면 좌표를 중심으로, 비디오 표시를 줌인/줌 아웃 한다.
자막 방송
CCActive | 자막 방송의 현재 상태를 설정 또는 취득한다.
ColorKey | 자막 방송으로 사용하는 칼라 키를 설정 또는 취득한다.
CurrentCCService | 현재의 자막 방송 서비스를 설정 또는 취득한다.
앵글 블록
AnglesAvailable | 이용 가능한 앵글수를 취득한다.
CurrentAngle | 앵글 블록내의 현재의 앵글을 설정 또는 취득한다.
가라오케 오디오
GetKaraokeChannelAssignment | 가라오케 채널의 좌우 스피커에의 할당을 나타내는 값을 취득한다.
GetKaraokeChannelContent | 지정된 스트림의 지정된 가라오케 채널의 컨텐츠의 종류를 나타내는 값을 취득한다.
KaraokeAudioPresentationMode | 외부 가라오케 채널의 좌우 스피커 믹싱비를 설정 또는 취득한다.
텍스트
GetDVDTextLanguageLCID | 지정된 텍스트 캐릭터 라인 블록의 로케일 식별자 (LCID)를 취득한다.
GetDVDTextNumberOfLanguages | 현재의 DVD 디렉토리내의 이용 가능한 텍스트 언어수를 취득한다.
GetDVDTextNumberOfStrings | 지정된 언어에 이용 가능한 텍스트의 수를 취득한다.
GetDVDTextString | 지정된 텍스트를 디스크로부터 취득한다.
GetDVDTextStringType | 지정된 DVD 텍스트에 저장 된 정보의 종류를 나타내는 값을 취득한다.
GetLangFromLangID | 소정의 주언어 식별자 (ID)에 대응하는 사람이 읽을 수 있는 캐릭터 라인을 취득한다.
페어 렌탈 락
AcceptParentalLevelChange | 새로운 일시 페어 렌탈 락 레벨을 받아들이든가 또는 거부하도록(듯이) DVD 네비게이터에게 지시한다.
GetPlayerParentalCountry | DVD 네비게이터로 설정된 현재의 나라를 취득한다.
GetPlayerParentalLevel | DVD 네비게이터로 설정된 페어 렌탈 락 레벨을 취득한다.
GetTitleParentalLevels | 지정된 타이틀의 페어 렌탈 락 레벨수를 취득한다.
NotifyParentalLevelChange | 일시 페어 렌탈 락 레벨 커멘드의 이벤트 처리를 유효 또는 무효로 한다.
SelectParentalCountry | 향후의 재생에 사용하는 나라로서 지정된 페어 렌탈 지방을 설정한다.
SelectParentalLevel | 향후의 재생에 사용하는 페어 렌탈 락 레벨로서 지정된 페어 렌탈 락 레벨을 설정한다.
디스크 정보
CurrentChapter | 현재 재생하고 있는 쳅터의 번호를 취득한다.
CurrentDiscSide | DVD 의 현재의 사이드를 취득한다.
CurrentDomain | DVD 네비게이터의 현재의 DVD 도메인을 취득한다.
CurrentTime | 현재의 재생 시간을 취득한다.
CurrentTitle | 현재 재생하고 있는 타이틀의 번호를 취득한다.
CurrentVolume | 현재의 루트 디렉토리의 볼륨 번호를 취득한다.
DVDDirectory | 현재의 DVD 볼륨의 루트 디렉토리를 취득 또는 설정한다.
DVDTimeCode2bstr | 디스크 위에의 현재 시간을 나타내는 캐릭터 라인을 취득한다.
DVDUniqueID | 현재의 DVD 를 일의에 식별하는, 시스템으로 생성된 번호를 취득한다.
GetNumberOfChapters | 지정된 타이틀에 포함되는 쳅터의 수를 취득한다.
TitlesAvailable | DVD 위에의 이용 가능한 타이틀수를 취득한다.
TotalTitleTime | 현재의 타이틀의 총재생 시간을 취득한다.
UOPValid | 지정된 유저 조작이 현재 유효한가 어떤가를 나타내는 값을 취득한다.
VolumesAvailable | 디스크 세트의 볼륨수를 나타내는 값을 취득한다.
오브젝트의 초기화 및 제어
DisableAutoMouseProcessing | 오브젝트의 마우스 처리 기능을 유효 또는 무효로 한다.
DVDAdm | 어플리케이션 및 유저의 정보를 보존하는 메소드 및 프로퍼티가 저장 된 MSDVDAdm 오브젝트에의 액세스를 제공한다.
EnableResetOnStop | 필터 그래프가 정지상태태로부터 이행 할 경우에 재생을 어떻게 재개할까를 결정하는 값을, 설정 또는 취득한다.
PlayState | 현재의 재생 상태를 취득한다.
ReadyState | MSWebDVD 오브젝트의 ReadyState 를 취득한다.
RegionChange | DVD 에 관련지을 수 있었던 리젼을 유저가 변경하기 위한 시스템 다이알로그 박스를 표시한다.
Render | DVD 필터 그래프를 초기화한다.
WindowlessActivation | 윈도우 모드와 윈드우레스모드의 어느 쪽인가에 사용하는 MSWebDVD 오브젝트를 설계시에 초기화한다.
북마크
DeleteBookmark | 현재의 북마크를 삭제한다.
RestoreBookmark | 현재의 북마크가 가리키는 DVD 위에의 위치에 DVD 네비게이터를 이동해, 오디오, 비디오, 및 서브 픽쳐의 설정을 모두 복원한다.
SaveBookmark | 유저가 다음에 같은 장소로 돌아갈 수 있도록(듯이), DVD 네비게이터의 현재의 디스크 위치 및 상태를 디스크에 보존한다.
커서 및 툴 팁
CursorType | 현재의 커서의 종류를 설정 또는 취득한다.
GetDelayTime | MSWebDVD 오브젝트에 관련지을 수 있었던 툴 팁에 대응하는 지연 시간을 취득한다.
SetDelayTime | MSWebDVD 오브젝트에 관련지을 수 있었던 툴 팁에 대응하는 지연 시간을 설정한다.
ShowCursor | DVD 네비게이터가 풀 스크린 모드 때에, 마우스 포인터를 표시한다.
ToolTip | 마우스 포인터가 MSWebDVD 비디오 직사각형과 겹쳐졌을 때에 표시되는 툴 팁의 텍스트를 설정한다.
ToolTipMaxWidth | MSWebDVD 오브젝트에 관련지을 수 있었던 툴 팁의 최대폭을 설정 또는 취득한다.
GPRM 및 SPRM
GetGPRM | 지정된 일반 파라미터 레지스터를 취득한다.
GetSPRM | 지정된 시스템 파라미터 레지스터를 취득한다.
SetGPRM | 지정된 일반 파라미터 레지스터로 지정된 값을 설정한다.

AcceptParentalLevelChange 메소드

MSWebDVD 오브젝트

새로운 일시 페어 렌탈 락 레벨을 받아들이든가 또는 거부하도록(듯이) DVD 네비게이터에게 지시한다.

구문

MSWebDVD. AcceptParentalLevelChange(bAccept);

파라미터

bAccept 새로운 페어 렌탈 레벨을 받아들이는지 거부하는지를 지시하는 불리언 값 (true가 용인).

반환값

No return value.

주의

EC_DVD_PARENTAL_LEVEL_CHANGE 이벤트 통지에 대응해 이 메소드를 호출해, 새로운 페어 렌탈 레벨로 컨텐츠를 재생해야할 것인가 어떤가를 지정하든가, 혹은 새로운 레벨이 거부된다면 디스크의 지정한 곳에 난다.

참조

페어 렌탈 락 레벨의 사용,GetPlayerParentalCountry ,GetPlayerParentalLevel ,GetTitleParentalLevels ,NotifyParentalLevelChange ,SelectParentalCountry ,SelectParentalLevel

ActivateAtPosition 메소드

MSWebDVD 오브젝트

마우스 포인터가 현재 겹치고 있는 메뉴 버튼을 액티브하게 한다.

구문

MSWebDVD. ActivateAtPosition(xPos, yPos);

파라미터

xPos | 마우스 포인터의 x 좌표를 지정하는 정수값.
xPos | 마우스 포인터의 y 좌표를 지정하는 정수값.

반환값

반환값 없음.

주의

DisableAutoMouseProcessing 를 TRUE 로 설정한 후, 커스텀 마우스 핸들링을 이행 하는 경우는, 이 메소드를 사용한다.

참조

ButtonsAvailable ,CurrentButton ,GetButtonAtPosition ,GetButtonRect ,SelectAndActivateButton ,SelectAtPosition

ActivateButton 메소드

MSWebDVD 오브젝트

선택된 메뉴 버튼을 액티브하게 한다.

구문

MSWebDVD. ActivateButton();

반환값

반환값 없음.

주의

DisableAutoMouseProcessing 를 TRUE 로 설정한 후, 커스텀 마우스 핸들링을 이행 하는 경우는, 이 메소드를 사용한다.

이 메소드는,SelectLeftButton 메소드,SelectLowerButton 메소드,SelectUpperButton 메소드, 또는 SelectRightButton 메소드로 선택한 버튼을 액티브하게 하기 위해서 사용한다.

AnglesAvailable 프로퍼티

MSWebDVD 오브젝트

현재 이용 가능한 앵글수를 취득한다.

구문

[ iAngles = ] MSWebDVD. AnglesAvailable

가능한 값

iAngles 현재 이용 가능한 앵글수를 나타내는 1 ~ 9 의 정수값. iAngles = 1 의 경우, 현재 위치에는 앵글 블록이 없다.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

주의

"앵글 블록" 이란, 복수의 앵글로부터 촬영한 비디오 세그먼트(segment)이다. 앵글 블록에는, 앵글이 최대 9 개(살) 포함되어 그것들에 1 ~ 9 의 번호가 붙어 있다. DVD 네비게이터는, 최초로 앵글 블록에 들어가면(자), 앵글 번호를 lParam1 로 설정해, 어플리케이션에 EC_DVD_ANGLES_AVAILABLE 이벤트 통지를 보낸다. 앵글 블록에 들어갔을 때에 이용 가능한 앵글의 메뉴를 자동적으로 표시하는 디스크를 생성 할 수도 있지만, 보통은, 어플리케이션으로, 이용 가능한 앵글수를 판단해, 그 중 1 개(살)을 선택하는 수단을 유저에게 제공할 필요가 있다.

참조

CurrentAngle

AspectRatio 프로퍼티

MSWebDVD 오브젝트

디스크에 명기된 현재의 비디오 스트림의 어스펙트비(가로세로 비율)을 취득한다.

구문

[ nAspectRatio = ] MSWebDVD. AspectRatio

가능한 값

nAspectRatio 디스크에 명기된 현재의 비디오 스트림의 어스펙트비(가로세로 비율)을 나타내는 수치 (어스펙트비(가로세로 비율) 4:3 의 경우는 1.33, 어스펙트비(가로세로 비율) 16:9 의 경우는 1.78).

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

AudioStreamsAvailable 프로퍼티

MSWebDVD 오브젝트

현재의 타이틀내의 이용 가능한 오디오 스트림수를 취득한다.

구문

[ iStreams = ] MSWebDVD. AudioStreamsAvailable

가능한 값

iStreams 현재의 타이틀내의 이용 가능한 오디오 스트림수를 나타내는 1 ~ 8 의 정수값.
이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

주의

복수의 오디오 스트림을 사용하는 주된 목적은, 무비의 사운드 트랙을 복수의 언어로 제공하는 것에 있다. 보통, 디스크에는 일부의 오디오 스트림만이 유효한 타이틀이 포함되어 있다. 예를 들어, 본편에는 3 개국어의 사운드 트랙이 있지만, 예고편에는 영어의 사운드 트랙 밖에 없을지도 모른다. 유저가 스트림을 선택하기 위해서는, 현재의 타이틀내의 이용 가능한 스트림을, 어플리케이션으로 판단할 필요가 있다. 개개의 스트림은 0 ~ 7 의 인덱스로 식별되므로 주의 해야 한다.

보통, 디스크에는 이용 가능한 사운드 트랙을 표시하는 메뉴가 있어, 유효하게 하는 오디오 스트림을 유저가 선택할 수 있게 되어 있다.

참조

GetAudioLanguage

BackColor 프로퍼티

MSWebDVD 오브젝트

네이티브 비디오의 어스펙트비(가로세로 비율)이 오브젝트의 표시 영역의 어스펙트비(가로세로 비율)과 다르고 있을 때, 비디오 직사각형의 인연의 주위에 표시되는 바의 색을 설정 또는 취득한다.

구문

[ iBackColor = ] MSWebDVD. BackColor

가능한 값

iBackColor 배경색의 RGB 값을 나타내는 정수값.

이 프로퍼티는, 디폴트값이 off-black (0x100010)의 읽고 쓰기 가능한 프로퍼티이다.

Balance 프로퍼티

MSWebDVD 오브젝트

오디오 스트림 출력의 스피커 밸런스를 설정 또는 취득한다.

구문

[ iBalance = ] MSWebDVD. Balance

가능한 값

iBalance 밸런스 레벨을 나타내는 정수값. 입력의 허용 범위는 -10, 000 ~ 10,000 이다. 값 0 에서는 균등인 밸런스가 설정된다. 즉, 좌우의 스피커에 같은 진폭의 오디오 신호가 공급된다.

이 프로퍼티는, 양쪽 모두의 스피커에 동등의 오디오 신호가 공급되는 0 을 디폴트값에 가지는, 읽고 쓰기 가능한 프로퍼티이다. Volume 프로퍼티 같이 단위는 . 01 데시벨에 상당한다 (iBalance 의 값이 정의 경우는 1 배 된다). 예를 들어 값 1000 에서는, 오른쪽 채널이 10 dB, 왼쪽 채널이 90 dB 가 된다.

ButtonsAvailable 프로퍼티

MSWebDVD 오브젝트

현재의 메뉴에 포함되는 버튼의 총수를 취득한다.

구문

[ iButtons = ] MSWebDVD. ButtonsAvailable

가능한 값

iButtons 버튼의 수를 나타내는 정수값.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

주의

DisableAutoMouseProcessing 를 TRUE 로 설정한 후, 커스텀 마우스 핸들링을 이행 하는 경우는, 이 메소드를 사용한다.

이 메소드를 호출해, 유효한 버튼수의 범위의 상한을 취득한다.

참조

CurrentButton ,GetButtonAtPosition ,GetButtonRect ,SelectAndActivateButton ,SelectAtPosition

CanStep 메소드

MSWebDVD 오브젝트

로컬 시스템의 MPEG-2 디코더가 스탭핑(Stepping)를 실행할 수 있을지 어떨지를 판단한다.

구문

[ bCanStep = ] MSWebDVD. CanStep(bBackwards);

파라미터

bBackwards 역방향 스탭핑(Stepping)를 문의하는지 어떤지를 지정하는 불리언 값. 디폴트는, 순서 방향 스탭핑(Stepping)를 의미하는 false.

반환값

디코더가 지정된 방향으로 스탭핑(Stepping)가능한가 어떤가를 나타내는 불리언 값을 돌려준다. TRUE 는 가능한 것을 의미한다.

주의

하드웨어 MPEG-2 디코더 모든 것이, DirectShow® 8.0 의 새로운 스탭핑(Stepping)능력을 지원 하면은 한정되지 않는다. 이 메소드는, 디코더가 가지는 스탭핑(Stepping)능력을 조회한다. 디코더가 스탭핑(Stepping)를 실행할 수 있는 경우에는, 어플리케이션으로부터 Step 메소드를 사용해 프레임을 진행시킬 수가 있다. 소프트웨어 디코더를 사용하고 있는 경우, 이 메소드는 항상 TRUE 를 돌려준다.

Capture 메소드

MSWebDVD 오브젝트

MSWebDVD 오브젝트가 윈드우레스모드 때에, 비디오 프레임으로부터 정지화면을 캡춰 한다.

구문

MSWebDVD. Capture();

주의

이 메소드는, DVD 비디오 이미지로부터 현재의 프레임을 캡춰 해, 유저가 이미지를 보존 또는 편집할 수 있는 윈도우에 그것을 드로잉(Drawing) 한다. 이 메소드가 성공하려면 ,MSWebDVD 오브젝트가 윈드우레스모드일 필요가 있다.

CCActive 프로퍼티

MSWebDVD 오브젝트

자막 방송의 현재 상태를 설정 또는 취득한다.

구문

[ bCCActive = ] MSWebDVD. CCActive

가능한 값

bCCActive 자막 방송이 온인가 어떤가를 나타내는 불리언 값.

이 프로퍼티는, 디폴트값이 false 의 읽고 쓰기 가능한 프로퍼티이다.

참조

CurrentCCService

ColorKey 프로퍼티

MSWebDVD 오브젝트

자막 방송으로 사용하는 칼라 키를 설정 또는 취득한다.

구문

[ iColorKey = ] MSWebDVD. ColorKey

가능한 값

iColorKey 자막 방송 텍스트의 투과형 백그라운드로서 사용하는 색을 나타내는 정수값. 디폴트값은, 256 색에서는 진홍색, 그 이외의 색깊이에서는 오프 블랙이 된다.

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

주의

이 프로퍼티는, 자막 방송에게만 적용되고 (존재하는 경우), 서브 픽쳐 스트림에는 적용되지 않는다.

CurrentAngle 프로퍼티

MSWebDVD 오브젝트

앵글 블록내의 현재의 앵글을 설정 또는 취득한다.

구문

[ iCurAngle = ] MSWebDVD. CurrentAngle

가능한 값

iCurAngle 앵글을 나타내는 1 ~ 9 의 정수값.

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다.

참조

AnglesAvailable

CurrentAudioStream 프로퍼티

MSWebDVD 오브젝트

유효한 오디오 스트림의 수를 설정 또는 취득한다.

구문

[ iStream = ] MSWebDVD. CurrentAudioStream

가능한 값

iStream 현재의 오디오 스트림을 나타내는 0 ~ 7 의 정수값.

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다.

주의

새로운 오디오 스트림을 설정하는 경우는, 그 전에 IsAudioStreamEnabled 를 호출해 그 스트림이 이용 가능한가 어떤가 검사한다.

참조

AudioStreamsAvailable

CurrentButton 프로퍼티

MSWebDVD 오브젝트

선택된 메뉴 버튼의 번호를 취득한다.

구문

[ iButton = ] MSWebDVD. CurrentButton

가능한 값

iButton 버튼을 나타내는 정수값.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

주의

DisableAutoMouseProcessing 를 TRUE 로 설정한 후, 커스텀 마우스 핸들링을 이행 하는 경우는, 이 메소드를 사용한다.

참조

ActivateButton ,ButtonsAvailable ,CurrentButton ,GetButtonAtPosition ,GetButtonRect ,SelectAndActivateButton ,SelectAtPosition

CurrentCCService 프로퍼티

MSWebDVD 오브젝트

현재의 자막 방송 서비스를 설정 또는 취득한다.

구문

[ iService = ] MSWebDVD. CurrentCCService

가능한 값

iService 유효한 자막 방송 서비스의 종류를 나타내는 정수값.

이 프로퍼티는, 디폴트값이 0x0 의 읽고 쓰기 가능한 프로퍼티이다.

다음의 일람은,iService 로서 가능한 값이다.
CC 서비스의 종류 | 값
현재의 서비스는 없다. | 0x0
트루 캡션 (필드 1). 디폴트의 서비스. | 0x1
부언어의 캡션 (필드 2). 보통은 사용하지 않는다. | 0x2

참조

CCActive

CurrentChapter 프로퍼티

MSWebDVD 오브젝트

현재 재생하고 있는 쳅터의 번호를 취득한다.

구문

[ iCurChapter = ] MSWebDVD. CurrentChapter

가능한 값

iCurChapter 현재의 타이틀의 현재의 쳅터를 나타내는 정수값.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

CurrentDiscSide 프로퍼티

MSWebDVD 오브젝트

디스크의 현재의 사이드를 취득한다.

구문

[ iCurSide = ] MSWebDVD. CurrentDiscSide

가능한 값

iCurSide 현재의 사이드를 나타내는 정수값. 사이드 A 는 1, 사이드 B 는 2.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

CurrentDomain 프로퍼티

MSWebDVD 오브젝트

MSWebDVD 오브젝트의 현재의 DVD 도메인을 취득한다.

구문

[ iDomain = ] MSWebDVD. CurrentDomain

가능한 값

iDomain 현재의 도메인을 나타내는 1 ~ 5 의 정수값.

iDomain 로서 가능한 값은 다음과 같다.
First Play | 1
Video Manager Menu | 2
Video Title Set Menu | 3
Title | 4
Stop | 5

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

주의

지금부터 호출하는 메소드에 DVD 네비게이터의 도메인이 유효한가 어떤가 확인하려면 , 이 메소드를 호출한다. 예를 들어,PlayTitle 를 호출하기 전에는,CurrentDomain 프로퍼티를 확인해, DVD 네비게이터의 도메인이 Stop 또는 First Play 가 아닌 것을 확인한다.

CurrentSubpictureStream 프로퍼티

MSWebDVD 오브젝트

현재의 서브 픽쳐 스트림을 설정 또는 취득한다.

구문

[ iSPStream = ] MSWebDVD. CurrentSubpictureStream

가능한 값

iSPStream 서브 픽쳐 스트림을 나타내는 0 ~ 31 의 정수값. 63 도 가능 (뮤트 된 bit rate의 낮은 스트림을 나타낸다).

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다.

주의

새로운 서브 픽쳐 스트림을 설정하는 경우는, 그 전에 IsSubpictureStreamEnabled 를 호출해 그 스트림이 이용 가능한가 어떤가 검사한다.

참조

SubpictureOn ,SubpictureStreamsAvailable

CurrentTime 프로퍼티

MSWebDVD 오브젝트

현재의 재생 시간을 취득한다.

구문

[ sCurTime = ] MSWebDVD. CurrentTime

가능한 값

sCurTime 현재의 재생 시간을 나타내는 11 문자의캐릭터 라인. 포맷은 "hh:mm:ss:ff" (시, 분, 초, 프레임).

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

참조

TotalTitleTime

CurrentTitle 프로퍼티

MSWebDVD 오브젝트

현재 재생하고 있는 타이틀의 번호를 취득한다.

구문

[ iCurTitle = ] MSWebDVD. CurrentTitle

가능한 값

iCurTitle 현재의 디스크 타이틀을 나타내는 1 ~ 99 의 정수값.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

참조

TitlesAvailable

CurrentVolume 프로퍼티

MSWebDVD 오브젝트

현재의 루트 디렉토리의 볼륨 번호를 취득한다.

구문

[ iCurVolume = ] DVD.CurrentVolume

가능한 값

iCurVolume 현재의 DVD 볼륨을 나타내는 정수값. 복수 볼륨세트에 포함되는 디스크에서는,iCurVolume 가 0 보다 크지 않으면 안 된다.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

참조

VolumesAvailable

CursorType 프로퍼티

MSWebDVD 오브젝트

현재의 커서의 종류를 설정 또는 취득한다.

구문

[ iCursorType = ] MSWebDVD. CursorType

가능한 값

iCursorType 커서의 종류를 나타내는 정수값.

이 프로퍼티로서 가능한 값은 다음과 같다.
화살표 (Arrow) | 0
확대 (Zoom In) | 1
축소 (Zoom Out) | 2
손바닥 (Hand) | 3
없음 (None) | -1

이 프로퍼티는, 디폴트값이 0 의 읽고 쓰기 가능한 프로퍼티이다.

주의

화면이 줌인 되고 있을 때 CursorType 를손바닥 (Hand) (0x3)로 설정 하면, 어플리케이션이 드러그 모드에 바뀌어, 유저가 비디오 표시 영역내에서 이미지를 이동할 수 있게 된다.

DefaultAudioLanguage 프로퍼티

MSWebDVD 오브젝트

디폴트의 오디오 언어를 취득한다.

구문

[ iLang = ] MSWebDVD. DefaultAudioLanguage

가능한 값

iLang 디폴트 오디오 언어에 대응하는 주언어 ID 가 저장 된 LCID 값. 주된 값의 일람, 및 LCID 로부터의 주언어 ID 의 추출 방법을 나타내는 샘플 코드에 대해서는,「LCID 의 조작」을 참조할것.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

참조

SelectDefaultAudioLanguage

DefaultAudioLanguageExt 프로퍼티

MSWebDVD 오브젝트

디폴트의 DVD 오디오 언어 extension를 취득한다.

구문

[ iLangExt = ] MSWebDVD. DefaultAudioLanguageExt

가능한 값

iLangExt 디폴트의 오디오 언어 extension를 나타내는 정수값. 가능한 값에 대해서는, 「주의」를 참조할것.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다. 다음의 일람은, DVD 오디오 언어 extension로서 가능한 값이다.

extension | 값
지정 없음 (NotSpecified) | 0
캡션 (Captions) | 1
시각 장애자전용 (VisuallyImpaired) | 2
디렉터 코멘트 1 (DirectorComments1) | 3
디렉터 코멘트 2 (DirectorComments2) | 4

참조

SelectDefaultAudioLanguage

DefaultMenuLanguage 프로퍼티

MSWebDVD 오브젝트

디폴트의 메뉴 언어를 취득한다.

구문

[ iLang = ] MSWebDVD. DefaultMenuLanguage

가능한 값

iLang 디폴트 오디오 언어에 대응하는 주언어 ID 가 저장 된 LCID 값. 주된 값의 일람, 및 LCID 로부터의 주언어 ID 의 추출 방법을 나타내는 샘플 코드에 대해서는,「LCID 의 조작」을 참조할것.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다.

DefaultSubpictureLanguage 프로퍼티

MSWebDVD 오브젝트

디폴트의 서브 픽쳐 언어를 취득한다.

구문

[ iLang = ] MSWebDVD. DefaultSubpictureLanguage

가능한 값

iLang 디폴트 오디오 언어에 대응하는 주언어 ID 가 저장 된 LCID 값. 주된 값의 일람, 및 LCID 로부터의 주언어 ID 의 추출 방법을 나타내는 샘플 코드에 대해서는,「LCID 의 조작」을 참조할것.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

참조

SelectDefaultSubpictureLanguage

DefaultSubpictureLanguageExt 프로퍼티

MSWebDVD 오브젝트

디폴트의 DVD 서브 픽쳐 언어 extension를 취득한다.

구문

[ iLangExt = ] MSWebDVD. DefaultSubpictureLanguageExt

가능한 값

iLangExt 디폴트의 DVD 서브 픽쳐 언어 extension를 나타내는 정수값.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다. 다음의 표는, 가능한 값이다.

extension | 값
지정 없음 | 0
캡션 (노멀) | 1
캡션 (대) | 2
캡션 (어린이용) | 3
자막 방송 (노멀) | 5
자막 방송 (대) | 6
자막 방송 (어린이용) | 7
강제 | 9
디렉터 코멘트 (노멀) | 13
디렉터 코멘트 (대) | 14
디렉터 코멘트 (어린이용) | 15

참조

SelectDefaultSubpictureLanguage

DeleteBookmark 메소드

MSWebDVD 오브젝트

보존한 북마크를 삭제한다.

구문

MSWebDVD. DeleteBookmark();

반환값

반환값 없음.

주의

동시에 설정할 수 있는 북마크는 1 개 뿐이다.

DisableAutoMouseProcessing 프로퍼티

MSWebDVD 오브젝트

MSWebDVD 오브젝트의 마우스 처리 기능을 유효 또는 무효로 한다.

구문

[ bMouseProcessing = ] MSWebDVD. DisableAutoMouseProcessing

가능한 값

bMouseProcessing 디폴트의 마우스 처리를 무효로 할지 어떨지를 나타내는 불리언 값.

주의

이 프로퍼티는, 디폴트값이 FALSE 의 읽고 쓰기 가능한 프로퍼티이다.

MSWebDVD 오브젝트는, 디폴트로, DVD 의 스크린 위에의 메뉴에 있어서의 마우스 조작을 자동적으로 처리한다. 어플리케이션으로 특별한 프로그래밍을 하지 않지는, 유저가 메뉴 버튼을 강조 표시해, 액티브하게 할 수가 있다. 이 디폴트의 마우스 처리 기능을 오프로 하려면 , 이 프로퍼티를 TRUE 로 설정한다. 자동의 마우스 처리를 오프로 하는 경우에는, 어플리케이션으로, 버튼 관련의 각종 메소드 및 프로퍼티를 사용해, 스크린 위에의 메뉴에 있어서의 마우스의 이동 및 클릭을 처리할 필요가 있다. 또,DisableAutoMouseProcessing 가 FALSE 로 설정되어 있어도, 버튼 관련의 메소드를 사용해 자동의 마우스 처리를 오버라이드(override) 할 수가 있다.

DVDAdm 프로퍼티

MSWebDVD 오브젝트

어플리케이션 및 유저의 정보를 보존하는 메소드 및 프로퍼티가 저장 된 MSDVDAdm 오브젝트에의 액세스를 제공한다.

구문

MSWebDVD. DVDAdm

주의

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다. MSDVDAdm 오브젝트의 참조를 독자적으로 생성 할 필요는 없다. 오브젝트의 메소드 및 프로퍼티에 액세스 하려면 , 다음과 같이 DVDAdm 프로퍼티를 사용한다.

DVD.DVDAdm. DisableScreenSaver = true;

DVDDirectory 프로퍼티

MSWebDVD 오브젝트

현재의 DVD 볼륨의 현재의 디렉토리를 설정 또는 취득한다.

구문

[ sDirPath = ] MSWebDVD. DVDDirectory

가능한 값

sDirPath DVD 의 루트 디렉토리의 패스를 나타내는 캐릭터 라인값.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다. 시스템에 DVD 드라이브가 다수 있을 때, 루트 패스를 설정하려면 , 이 메소드를 사용한다. 시스템에 있는 드라이브가 1 대만으로, 그 드라이브 문자가 C 보다 큰 경우에는,MSWebDVD 오브젝트가 루트 패스를 자동적으로 검색한다. 표준의 DVD 비디오디스크에서는, 예를 들어 다음과 같이, 루트 패스에 video_ts 디렉토리가 포함되지 않으면 안 된다.

MSWebDVD.DVDDirectory = "e:\\video_ts";

일부의 DVD 볼륨에서는, 비디오가 video_ts 이외의 디렉토리에 저장 되고 있는 일이 있다. 예를 들어, 디스크의 서브 디렉토리에 추가의 "DVD 볼륨 " (보통은 VIDEO_TS 디렉토리에 저장 된다 . IFO, VOB 및 . BUP 파일세트)가 배치되고 있는 경우등을 생각된다. 이 디렉토리를 가리키도록(듯이) 루트를 변경 하면, MSWebDVD 가 그 독립한 DVD 볼륨상에서 동작하게 된다. VIDEO_TS 루트에 있는 타이틀과는 다른, 새로운 메뉴나 타이틀등의 세트가 이용 가능하게 되어, VIDEO_TS 루트는 액세스 할 수 없다. 이러한 디렉토리는, "은폐 디렉토리 " 로 불린다. 다음의 예는, 은폐 디렉토리를 루트로서 설정하는 방법을 나타낸다. "hidden" 는, 디스크의 작자가 디렉토리에 붙인 임의의 이름을 나타내는 플레이스홀더이다.

MSWebDVD.DVDDirectory = "d:\\webdvd\\hidden";

MSWebDVD.DVDTimeCode2bstr 메소드

MSWebDVD 오브젝트

디스크 위에의 현재 시간을 나타내는 캐릭터 라인을 취득한다.

구문

[ sTimeCode = ] MSWebDVD. DVDTimeCode2bstr(nTimeCode);

파라미터

nTimeCode EC_DVD_CURRENT_HMSF_TIME 이벤트를 통해서 취득되는, 타이틀의 시작 타임에 대한 디스크 위에의 현재 시간을 나타내는 수.

반환값

현재의 재생 시간을 정의하는 11 문자의 캐릭터 라인을 돌려준다. 포맷은 "hh:mm:ss:ff" (시, 분, 초, 프레임).

주의

이 프로퍼티는, 독해 전용 프로퍼티이다.

참조

DVD 이벤트 통지의 처리

DVDUniqueID 프로퍼티

MSWebDVD 오브젝트

현재의 디스크를 일의에 식별하는, 시스템으로 생성된 번호를 취득한다.

구문

[ iDiscID = ] MSWebDVD. DVDUniqueID

가능한 값

iDiscID 현재의 디스크를 일의에 식별하는 정수값.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

주의

이 식별자 (ID)는, 완전하게 일의는 아니지만, 실용상은 일의인 것이라고 볼 수가 있다. ID 는, 디스크의 복제 모두에게 적용된다. 즉, 1 개의 무비의 카피는 모두 같은 ID 를 가진다. 또, ID 는, BCA 값은 아니고 파일 사이즈, 일자, 및 그 외의 정보에 근거해 결정된다.

Eject 메소드

MSWebDVD 오브젝트

드라이브의 DVD 의 꺼내/삽입을 실시한다.

구문

MSWebDVD. Eject();

반환값

반환값 없음.

주의

DVD 드라이브에 따라서는, 이 메소드가 타글 동작을 해, 호출할 때마다 취득과 삽입의 동작이 바뀐다. 이 동작은 하드웨어에 의존한다.

EnableResetOnStop 프로퍼티

MSWebDVD 오브젝트

필터 그래프가 정지상태태로부터 이행 할 경우에 재생을 어떻게 재개할까를 결정하는 값을, 설정 또는 취득한다.

구문

[ bEnableReset = ] MSWebDVD. EnableResetOnStop

가능한 값

bEnableReset 필터 그래프의 정지 후에 MSWebDVD 오브젝트가 재생을 재개하는 위치를 나타내는 불리언 값. TRUE 는, DVD 네비게이터가 리셋 후에 디스크의 최초부터 재생을 시작 하는 것을 의미한다. FALSE 는, 지금까지 재생된 마지막 위치로부터 재개하는 것을 의미한다.

주의

이 프로퍼티는, 디폴트값이 TRUE 의 읽고 쓰기 가능한 프로퍼티이다.

FramesPerSecond 프로퍼티

MSWebDVD 오브젝트

현재의 DVD 타이틀의 비디오 frame rate를 취득한다.

구문

[ iFramesPerSec = ] MSWebDVD. FramesPerSecond

가능한 값

iFramesPerSec 비디오의 frame rate를 나타내는 정수값. 25 또는 30 프레임/초.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다. NTSC 비디오 신호는 30 프레임/초에 표시된다. PAL 는 25 프레임/초에 표시된다. 디스크는, NTSC 와 PAL 의 어느 쪽인지로 재생하도록(듯이) encode 되어 양쪽 모두로 재생할 수 없다.

FullScreenMode 프로퍼티

MSWebDVD 오브젝트

표시가 풀 스크린 모드인가 어떤가를 나타내는 값을 설정 또는 취득한다.

구문

[ bFullScreen = ] MSWebDVD. FullScreenMode

가능한 값

bFullScreen 풀 스크린 재생을 유효하게 할까 무효로 하는지를 나타내는 불리언 값. TRUE 는, 풀 스크린 모드를 유효하게 하는 것을 의미한다.

주의

이 프로퍼티는, 디폴트값이 false 의 읽고 쓰기 가능한 프로퍼티이다.

GetAudioLanguage 메소드

MSWebDVD 오브젝트

지정된 오디오 스트림 위에의 이용 가능한 언어를 나타내는 캐릭터 라인을 취득한다.

구문

[ slang = ] MSWebDVD. GetAudioLanguage(iStream);

파라미터

iStream 현재의 타이틀내의 오디오 스트림 번호를 지정하는 정수값.

반환값

현재의 타이틀내의 오디오 스트림의 언어를 식별하는, 사람이 읽을 수 있는 캐릭터 라인을 돌려준다.

GetButtonAtPosition 메소드

MSWebDVD 오브젝트

버튼을 선택 또는 액티브하게 하지 않고 , 지정된 좌표에 있는 버튼의 번호를 취득한다.

구문

[ iButton = ] MSWebDVD. GetButtonAtPosition(xPos, yPos);

파라미터

xPos | 마우스 포인터의 x 좌표를 지정하는 정수값.
yPos | 마우스 포인터의 y 좌표를 지정하는 정수값.

반환값

지정된 위치에 있는 버튼을 나타내는 정수값을 돌려준다 (있는 경우).

주의

지정된 좌표에 버튼이 없는 경우, 이 메소드는 0 을 돌려준다. DisableAutoMouseProcessing 를 TRUE 로 설정한 후, 커스텀 마우스 핸들링을 이행 하는 경우는, 이 메소드를 사용한다.

참조

ActivateButton ,ButtonsAvailable ,CurrentButton ,GetButtonRect ,SelectAndActivateButton ,SelectAtPosition

GetButtonRect 메소드

MSWebDVD 오브젝트

지정된 버튼의 직사각형을 윈도우 좌표로 취득한다.

구문

[ oButton = ] MSWebDVD. GetButtonRect(iButton);

파라미터

iButton 버튼 번호를 지정하는 정수값.

반환값

직사각형을 정의하는 DVDRect 오브젝트를 돌려준다.

주의

DisableAutoMouseProcessing 를 TRUE 로 설정한 후, 커스텀 마우스 핸들링을 이행 하는 경우는, 이 메소드를 사용한다.

참조

ButtonsAvailable ,CurrentButton ,ActivateButton ,SelectAndActivateButton ,SelectAtPosition

GetClipVideoRect 메소드

MSWebDVD 오브젝트

비디오 표시용으로 현재 정의되고 있는 클리핑 직사각형을 취득한다.

구문

[ oClipRect = ] MSWebDVD. GetClipVideoRect();

반환값

직사각형을 정의하는 DVDRect 오브젝트를 돌려준다.

참조

SetClipVideoRect

GetDelayTime 메소드

MSWebDVD 오브젝트

MSWebDVD 오브젝트에 관련지을 수 있었던 툴 팁에 대응하는 지연 시간을 취득한다.

구문

[ iDelay = ] MSWebDVD. GetDelayTime();

반환값

툴 팁의 지연 시간 (밀리 세컨드 단위)을 나타내는 정수값을 돌려준다.

참조

SetDelayTime

GetDVDTextLanguageLCID 메소드

MSWebDVD 오브젝트

지정된 텍스트 블록의 로케일 식별자 (LCID)를 취득한다.

구문

[ iLCID = ] MSWebDVD. GetDVDTextLanguageLCID(iLangIndex);

파라미터

iLangIndex 디스크 위에의 텍스트 언어 블록을 식별하는 정수값.

반환값

텍스트에 사용되는 언어를 나타내는 정보가 저장 된 LCID 값을 돌려준다. LCID 로부터의 주언어 코드의 추출에 대해서는,「LCID 의 조작」을 참조할것.

주의

보충의 텍스트는, 디스크 위에의 연속 블록에 저장 되고 있다. 각각의 언어가 1 개의 텍스트 블록을 가진다. 어플리케이션에서는, 이러한 블록을 인덱스로 지정한다. 인덱스는,GetDVDTextNumberOfLanguages 로 돌려주어지는 값보다 작지 않으면 안 된다.

참조

GetLangFromLangID ,DVD 텍스트 캐릭터 라인의 조작

GetDVDTextNumberOfLanguages 메소드

MSWebDVD 오브젝트

디스크 위에의 이용 가능한 텍스트 언어수를 취득한다.

구문

[ iLanguages = ] MSWebDVD. GetDVDTextNumberOfLanguages();

반환값

이용 가능한 텍스트 언어의 수를 나타내는 정수값을 돌려준다.

참조

DVD 텍스트 캐릭터 라인의 조작

GetDVDTextNumberOfStrings 메소드

MSWebDVD 오브젝트

지정된 언어에 이용 가능한 텍스트의 수를 취득한다.

구문

[ iStrings = ] MSWebDVD. GetDVDTextNumberOfStrings(iLangIndex);

파라미터

iLangIndex 언어를 식별하는 정수값. 유효한 범위는, 0 으로부터,GetDVDTextNumberOfLanguages 로 돌려주어지는 값으로부터 1 당긴 값까지.

반환값

지정된 언어로 저장 된 캐릭터 라인의 수를 나타내는 정수값을 돌려준다.

참조

DVD 텍스트 캐릭터 라인의 조작

GetDVDTextString 메소드

MSWebDVD 오브젝트

지정된 텍스트를 취득한다.

구문

[ sText = ] MSWebDVD. GetDVDTextString(iLangIndex, iStringIndex);

파라미터

iLangIndex | 언어의 인덱스를 지정하는 정수값.
iStringIndex | 텍스트의 인덱스 번호를 지정하는 정수값.

반환값

iStringIndex 로 지정된 캐릭터 라인을 돌려준다.

참조

GetDVDTextNumberOfLanguages ,DVD 텍스트 캐릭터 라인의 조작

GetDVDTextStringType 메소드

MSWebDVD 오브젝트

지정된 DVD 텍스트에 저장 된 정보의 종류를 나타내는 값을 취득한다.

구문

[ iStringType = ] MSWebDVD. GetDVDTextStringType(iLangIndex, iStringIndex);

파라미터

iLangIndex | 텍스트의 언어를 지정하는 정수값.
iStringIndex | 텍스트의 인덱스 번호를 지정하는 정수값.

반환값

캐릭터 라인에 저장 된 정보의 종류를 나타내는 정수값을 돌려준다.

주의

텍스트의 종류와 그 의미의 일람에 대해서는,「DVD 텍스트 캐릭터 라인의 조작」을 참조할것.

GetGPRM 메소드

MSWebDVD 오브젝트

지정된 일반 파라미터 레지스터를 취득한다.

구문

[ iGPRM = ] MSWebDVD. GetGPRM(iIndex);

파라미터

iIndex 취득 레지스터를 나타내는 0 ~ 15 의 정수값.

반환값

지정된 레지스터에 대응하는 정수값을 돌려준다.

주의

이 메소드에는,MSWebDVD 오브젝트를 사용한 DVD 의 네비게이션 기능 또는 재생 기능은 필요없다. 이 메소드는, DVD 의 사양을 충분히 이해한 유저가 고도의 기능을 이행 하기 위해서 제공된다. GPRM 를 사용해, 임의의 값을 저장 해, 자유롭게 읽고 쓰기할 수가 있다. 다만, GPRM 는 디스크 커멘드의 저장에도 사용되므로,SetGPRM 를 사용해 내용을 변경했을 경우, 거기에 따라 일으켜지는 동작은 예측 불가능하다.

참조

SetGPRM

GetKaraokeChannelAssignment 메소드

MSWebDVD 오브젝트

가라오케 채널의 스피커에의 할당을 나타내는 값을 취득한다.

구문

[ iAssignment = ] MSWebDVD. GetKaraokeChannelAssignment(iStream , iChannel);

파라미터

iStream | 오디오 스트림을 지정하는 정수값.
iChannel | 채널을 지정하는 정수값.

반환값

지정된 채널에의 스피커의 할당을 나타내는 정수를 돌려준다. iAssignment 로서 가능한 값은 다음과 같다.
2 | 채널이 왼쪽 및 오른쪽의 스피커에 할당할 수 있고 있다.
3 | 채널이 좌, 오른쪽, 및 중앙의 스피커에 할당할 수 있고 있다.
4 | 채널이 좌, 오른쪽, 및 오디오 1 의 스피커에 할당할 수 있고 있다.
5 | 채널이 좌, 오른쪽, 중앙, 및 오디오 1 의 스피커에 할당할 수 있고 있다.
6 | 채널이 좌, 오른쪽, 및 오디오 2 의 스피커에 할당할 수 있고 있다.
7 | 채널이 좌, 오른쪽, 중앙, 및 오디오 2 의 스피커에 할당할 수 있고 있다.

참조

KaraokeAudioPresentationMode

GetKaraokeChannelContent 메소드

MSWebDVD 오브젝트

지정된 스트림의 지정된 가라오케 채널의 컨텐츠의 종류를 나타내는 값을 취득한다.

구문

[ iContent = ] MSWebDVD. GetKaraokeChannelContent(iStream, iChannel);

파라미터

iStream | 오디오 스트림을 지정하는 0 ~ 7 의 정수값.
iChannel | iStream 내의 가라오케 채널을 지정하는 정수값.

각 체 z넬로 지정 가능한 값은 다음과 같다.

가이드 음성 (Guide Vocal) 1 | 0x0001
가이드 음성 (Guide Vocal) 2 | 0x0002
가이드 멜로디 (Guide Melody) 1 | 0x0004
가이드 멜로디 (Guide Melody) 2 | 0x0008
가이드 멜로디 (Guide Melody) A | 0x0010
가이드 멜로디 (Guide Melody) B | 0x0020
사운드 이펙트 (Sound Effect) A | 0x0040
사운드 이펙트 (Sound Effect) B | 0x0080

반환값

가라오케 채널의 컨텐츠를 각 비트가 가리키는 정수값을 돌려준다.

주의

DVD 오디오 채널의 번호는 0 으로부터 시작되어, 채널 2, 3, 및 4 는 외부 가라오케 채널이 되고 있다. 메소드로부터 돌아온 후,iContent 의 비트마다의 AND 연산을 실행해, 각 채널의 컨텐츠를 판단한다. 1 개의 채널에 기록되고 있는 컨텐츠의 종류는 1 개라고는 할 수 없기 때문에, 일치하는 것이 발견되어도, 그 외의 가능한 값을 모두 테스트해야 한다.

다음의 샘플 코드는, 모든 iContent 를 가능한 값 각각 붙어 테스트하는 방법을 나타내고 있다.

    if(iContent & 0x0001)
        {
            // 체크 박스 또는 그 외의 UI 컨트롤을 온으로 해,
            // 이 채널에 가이드 음성 1 이 있는 것을 나타낸다.
        }
    if(iContent & 0x0002)
        {
            // 체크 박스 또는 그 외의 UI 컨트롤을 온으로 해,
            // 이 채널에 가이드 음성 2 가 있는 것을 나타낸다.
        }
    if(iContent & 0x0004)
        {
            // 체크 박스 또는 그 외의 UI 컨트롤을 온으로 해,
            // 이 채널에 가이드 멜로디 1 이 있는 것을 나타낸다.
        }

    // 각 채널의 가능한 값 각각 붙어 반복한다.

유저는, 각 채널의 컨텐츠를 안 데다가, 필요에 따라서 볼륨을 조정하거나 개개의 채널의 온/오프를 바꾸거나 할 수 없으면 안 된다. 어플리케이션에 이 기능을 이행 하려면 ,KaraokeAudioPresentationMode 프로퍼티를 사용한다.

주 : 가라오케 디스크를 재생하려면 , 유저의 시스템의 오디오 디코더가, DirectShow 8 의 가라오케 이행과 호환이 아니면 안된다.

GetLangFromLangID 메소드

MSWebDVD 오브젝트

소정의 주언어 ID 에 대응하는 사람이 읽을 수 있는 캐릭터 라인을 취득한다.

구문

[ sLanguage = ] MSWebDVD. GetLangFromLangID(iPrimaryLangID)

파라미터

iPrimaryLangID 주언어 ID 를 지정하는 정수. 가능한 값의 주된 일람에 대해서는, 「LCID 의 조작」을 참조할것.

반환값

iPrimaryLangID 가 유효한 경우는, 어플리케이션의 유저 인터페이스에 표시할 수 있는 언어를 캐릭터 라인으로 돌려준다. iPrimaryLangID 가 무효인 경우는, 에러 코드를 돌려준다.

주의

이 메소드의 이름은 GetLangFromLangID 이지만, 호출원으로부터 실제로 건네주는 파라미터는, 주언어 ID 이며, 언어 ID 는 아니다.

참조

LCID 의 조작,GetAudioLanguage ,GetDVDTextLanguageLCID

GetNumberOfChapters 메소드

MSWebDVD 오브젝트

지정된 타이틀에 포함되는 쳅터의 수를 취득한다.

구문

iChapters = MSWebDVD. GetNumberOfChapters(iTitle);

파라미터

iTitle 타이틀을 지정하는 정수값.

반환값

쳅터수를 나타내는 1 ~ 999 의 정수값을 돌려준다.

GetPlayerParentalCountry 메소드

MSWebDVD 오브젝트

MSWebDVD 오브젝트로 설정된 현재의 나라를 취득한다.

구문

iCountryCode = MSWebDVD. GetPlayerParentalCountry();

반환값

국별 코드를 나타내는 정수값을 돌려준다.

참조

페어 렌탈 락 레벨의 적용,GetPlayerParentalLevel ,GetTitleParentalLevels ,SelectParentalCountry ,SelectParentalLevel

GetPlayerParentalLevel 메소드

MSWebDVD 오브젝트

MSWebDVD 오브젝트로 설정된 페어 렌탈 락 레벨을 취득한다.

구문

[ iLevel = ] MSWebDVD. GetPlayerParentalLevel();

반환값

DVD 네비게이터로 설정된 현재의 페어 렌탈 락 레벨을 나타내는 정수값을 돌려준다, 혹은 페어 렌탈 락이 사용 불가라면 -1 .

주의

플레이어 어플리케이션에는, 페어 렌탈 락을 사용할 의무가 있다. 플레이어의 페어 렌탈 락 레벨은, 어플리케이션으로부터 설정해, 현재의 유저가 볼 수가 있는 가장 높은 페어 렌탈 락 레벨을 지정하기 위해서 사용한다. DVD 네비게이터는, 새로운 페어 렌탈 락 레벨이 발견되었을 때, 새로운 페어 렌탈 락 레벨이 SelectParentalLevel 를 통해서 어플리케이션으로부터 설정된 페어 렌탈 락 레벨보다 높은지 어떤지를, 이 메소드를 사용하고 판단한다.

참조

페어 렌탈 락 레벨의 적용,GetTitleParentalLevels ,GetPlayerParentalCountry ,SelectParentalCountry ,SelectParentalLevel

GetSPRM 메소드

MSWebDVD 오브젝트

지정된 시스템 파라미터 레지스터를 취득한다.

구문

[ iSPRM = ] MSWebDVD. GetSPRM(iIndex);

파라미터

iIndex 값을 취득하는 레지스터를 지정하는 0 ~ 23 의 정수값.

반환값

지정된 레지스터의 내용을 나타내는 정수값을 돌려준다.

주의

디스크는 시스템 파라미터 레지스터 (SPRM)를 제어한다. 플레이어 어플리케이션에서는, 표준적인 네비게이션 기능을 위해서(때문에), 이러한 레지스터에 액세스 할 필요는 없다. SPRM 는, 플레이어 상태를 나타낸다. 각각의 의미는, 유저 설정, 디스크 커멘드, 및 어플리케이션으로부터는 직접 제어할 수 없는 그 외의 장면에서 설정된다. SPRM 는, 어플리케이션으로부터 읽어낼 수 있지만, 기입할 수가 없다. SPRM 를 효율적으로 사용하려면 , DVD 네비게이션 커멘드에 대해 이 문서보다 자세한 정보가 필요하게 되는 경우가 있다. 다음의 일람은 각 레지스터의 내용이다. 레지스터 내용의 상세한 것에 대하여는, 「IDVDInfo2::GetAllSPRMs 」를 참조할것.

레지스터 | 내용 | 레지스터 | 내용 | 레지스터 | 내용
0 | 메뉴 언어 코드 | 1 | 오디오 스트림 번호 | 2 | 서브 픽쳐 스트림 번호
3 | 현재의 앵글 번호 | 4 | 현재의 타이틀 번호 | 5 | 타이틀 번호
6 | PGC 번호 | 7 | 현재의 쳅터 번호 (PTT) | 8 | 강조 표시되고 있는 버튼의 번호
9 | 네비게이션 타이머 | 10 | 네비게이션 타이머에 대응하는 PGC 점프 | 11 | 가라오케 오디오의 프레젠테이션 모드
12 | PML 의 국별 코드 | 13 | PML | 14 | 비디오 설정
15 | 오디오 능력 | 16 | 오디오 언어 | 17 | 오디오 언어 extension
18 | 서브 픽쳐 언어 | 19 | 서브 픽쳐 언어 extension | 20 | 플레이어의 지역 코드
21 | 예약이 끝난 | 22 | 예약이 끝난 | 23 | 예약이 끝난 상태

참조

GetGPRM ,SetGPRM

GetSubpictureLanguage 메소드

MSWebDVD 오브젝트

지정된 서브 픽쳐 스트림의 언어를 취득한다.

구문

[ sLang = ] MSWebDVD. GetSubpictureLanguage(iStream);

파라미터

iStream 텍스트 언어를 취득하는 서브 픽쳐 스트림의 번호를 지정하는 정수값.

반환값

현재의 타이틀내의 오디오 스트림의 언어를 식별하는, 사람이 읽을 수 있는 캐릭터 라인을 돌려준다.

GetTitleParentalLevels 메소드

MSWebDVD 오브젝트

지정된 타이틀의 페어 렌탈 락 레벨수를 취득한다.

구문

[ iLevels = ] MSWebDVD. GetTitleParentalLevels(iTitle);

파라미터

iTitle 타이틀을 지정하는 정수값.

반환값

지정된 타이틀로 설정된 페어 렌탈 락 레벨 (PML)을 각 비트가 가리키는 정수값을 돌려준다.

주의

타이틀 전체와 다른 PML 를 가지는 쳅터 (또는 쳅터보다 짧은 세그먼트(segment))가, 타이틀내에 포함되어 있는 일이 있다. 이 메소드를 사용해, 특정의 타이틀을 재생할 경우에 나타나는 모든 PML 를 판단한다. 돌려주어지는 정수는, 아래의 일람에 정의되고 있는 비트 플래그를 조합한 것이다. iLevels 와 가능한 값 각각의 비트마다의 AND 연산을 실행한다. 연산의 결과가 TRUE 가 되는 경우, 이 타이틀의 어디엔가 그 PML 가 나타나는 것을 의미한다.

가능한 레벨 | 16 진값
DVD 페어 렌탈 락 레벨 1 | 0x100
DVD 페어 렌탈 락 레벨 2 | 0x200
DVD 페어 렌탈 락 레벨 3 | 0x400
DVD 페어 렌탈 락 레벨 4 | 0x800
DVD 페어 렌탈 락 레벨 5 | 0x1000
DVD 페어 렌탈 락 레벨 6 | 0x2000
DVD 페어 렌탈 락 레벨 7 | 0x4000
DVD 페어 렌탈 락 레벨 8 | 0x8000
다음의 샘플 코드는, 타이틀 1 의 PML 를 테스트하는 방법을 나타낸다. 이 정보의 1 개의 목적은, 타이틀에 정의된 가장 높은 PML 와 현재의 유저가 할당할 수 있었던 PML 를 비교해, 지정된 타이틀을 재생해야할 것인가 제발 판단하는 것에 있다.
iLevels = oDVD.GetTitleParentalLevels(1);
if(iLevels & 0x100)
 // 이 타이틀에는 PML 1 이 정의되고 있다.
if(iLvels & 0x200)
   // 이 타이틀에는 PML 2 가 정의되고 있다.
if(iLevels & 0x400)
  // 이 타이틀에는 PML 3 이 정의되고 있다.
...   // 레벨 8 까지 반복한다.

참조

페어 렌탈 락 레벨의 적용,SelectParentalLevel ,GetPlayerParentalCountry ,GetPlayerParentalLevel ,SelectParentalCountry

IsAudioStreamEnabled 메소드

MSWebDVD 오브젝트

지정된 오디오 스트림이 현재의 타이틀로 유효한가 어떤가를 나타내는 값을 취득한다.

구문

[ bEnabled = ] MSWebDVD. IsAudioStreamEnabled(iStream)

파라미터

iStream 오디오 스트림을 지정하는 0 ~ 7 의 정수값.

반환값

지정된 오디오 스트림이 현재의 타이틀에 이용 가능한가 어떤가를 나타내는 불리언 값을 돌려준다. TRUE 는 이용 가능한 일을 의미한다.

주의

디스크에는, 독립한 8 개(살)까지의 오디오 스트림이 있지만, 개개의 스트림이 반드시 모든 타이틀에 이용 가능하다고는 할 수 없다. 예를 들어, 본편에는 영어, 스페인어, 일본어의 3 개의 오디오 스트림이 있지만, "예고편 " 에는 영어의 오디오 스트림 밖에 없을 가능성이 있다. CurrentAudioStream 프로퍼티를 설정할 경우에는, 그 전에 타이틀에 그 스트림이 이용 가능한가 어떤가를 반드시 검사한다.

IsSubpictureStreamEnabled 메소드

MSWebDVD 오브젝트

지정된 서브 픽쳐 스트림이 현재의 타이틀로 유효한가 어떤가를 나타내는 값을 취득한다.

구문

[ bEnabled = ] MSWebDVD. IsSubpictureStreamEnabled(iStream)

파라미터

iStream 서브 픽쳐 스트림을 지정하는 0 ~ 31 의 정수값 (또는 뮤트 된 bit rate의 낮은 스트림을 나타내는 63).

반환값

지정된 오디오 스트림이나 현재의 타이틀로 이용 가능한가 어떤가를 나타내는 불리언 값을 돌려준다. TRUE 는 이용 가능한 일을 의미한다.

주의

디스크에는 32 까지의 서브 픽쳐 스트림이 들어가지만, 개개의 스트림이 반드시 모든 타이틀에 이용 가능하다고는 할 수 없다. CurrentSubpictureStream 프로퍼티를 설정할 경우에는, 그 전에 타이틀에 그 스트림이 이용 가능한가 어떤가를 반드시 검사한다.

GetVideoSize 메소드

MSWebDVD 오브젝트

네이티브 비디오의 넓이를 취득한다.

구문

[ oSizeRect = ] MSWebDVD. GetVideoSize();

반환값

(좌상의) x, (좌상의) y, Width, Height 의 4 개의 읽고 쓰기 가능한 프로퍼티가 저장 된 DVDRect 오브젝트를 돌려준다. x 프로퍼티 및 y 프로퍼티에는 0 이 설정되어 다른 2 개의 프로퍼티에는 디스크에 명기된 비디오 직사각형의 폭 및 높이가 반영된다.

KaraokeAudioPresentationMode 프로퍼티

MSWebDVD 오브젝트

외부 가라오케 채널의 좌우 스피커 믹싱비를 설정 또는 취득한다.

구문

[iMode ] = MSWebDVD. KaraokeAudioPresentationMode

가능한 값

iMode 외부 가라오케 채널의 좌우 스피커에의 다운 믹스를 지정하는 비트 플래그의 편성이 저장 된 정수값. 「주의」를 참조할것.

주의

이 프로퍼티는, 디폴트값이 0 의 읽고 쓰기 가능한 프로퍼티이다.

오디오 채널의 번호는 0 으로부터 시작된다. 따라서, 채널 0 및 1 은, 보통, 좌우의 스피커 채널을 나타내, 채널 2 ~ 4 는 3 개의 외부 가라오케 채널이다. MSWebDVD 오브젝트는, 가라오케 모드에 바뀌면(자), 채널 2 이후를 자동적으로 뮤트 한다. 외부 채널을, 좌, 우, 또는 좌우 양쪽 모두 (양쪽 모두의 비트를 온으로 한다)의 스피커에 보내는 경우나, 어느 쪽의 스피커에도 보내지 않는 (양쪽 모두의 비트를 오프로 한다) 경우, 각각 적합한 비트를 설정하려면 , 비트마다의 OR 연산을 실행한다. DVD 네비게이터가 가라오케 모드에 바뀌면(자), 디폴트에서는, 이러한 비트가 모두 오프가 된다. 다음의 일람은, 비트의 값과 그 값에 대응하는 조작을 나타낸다.

조작 | 값
채널 2 를 왼쪽의 스피커에 다운 믹스 하는 | 0x0004
채널 3 을 왼쪽의 스피커에 다운 믹스 하는 | 0x0008
채널 4 를 왼쪽의 스피커에 다운 믹스 하는 | 0x0010
채널 2 를 오른쪽의 스피커에 다운 믹스 하는 | 0x0400
채널 3 을 오른쪽의 스피커에 다운 믹스 하는 | 0x0800
채널 4 를 오른쪽의 스피커에 다운 믹스 하는 | 0x1000

다음의 샘플 코드는, 비트마다의 OR 연산을 사용해, 채널 2 를 왼쪽의 스피커에, 채널 3 및 4 를 오른쪽의 채널에 보내는 방법을 나타낸다.

  var iMode = 0;
  iMode = 0x0004 | 0x0800 | 0x1000 ;
  DVD.KaraokeAudioPresentationMode = iMode;

KaraokeAudioPresentationMode 의 값을 취득하려면 , 다음과 같이, 가능한 값과의 비트마다의 AND 연산을 실행한다.

  if (DVD.KaraokeAudioPresentationMode & 0x0004)
  {
     // 채널 2 는 왼쪽의 스피커에 보내지고 있다.
  }
  if (DVD.KaraokeAudioPresentationMode & 0x0008)
  {
     // 채널 3 은 왼쪽의 스피커에 보내지고 있다.
  }
  // 가능한 값 모두에 임해서 반복한다.

Mute 프로퍼티

MSWebDVD 오브젝트

오디오 스트림 출력의 온/오프를 바꾼다.

구문

[ bMute = ] MSWebDVD. Mute

가능한 값

bMute 오디오 스트림을 뮤트해야할 것인가 제발을 나타내는 불리언 값.

주의

이 프로퍼티는, 디폴트값이 false 의 읽고 쓰기 가능한 프로퍼티이다.

NotifyParentalLevelChange 메소드

MSWebDVD 오브젝트

일시 페어 렌탈 락 레벨 커멘드의 이벤트 처리를 유효 또는 무효로 한다.

구문

MSWebDVD. NotifyParentalLevelChange(bNotify);

파라미터

bNotify 디스크 전체의 레이팅보다 높은 레이팅이 지정된 비디오 세그먼트(segment)가 발견되었을 때에, MSWebDVD 오브젝트가 어플리케이션에 통지할지 어떨지를 지정하는 불리언 값.

반환값

반환값 없음.

주의

페어 렌탈 락 통지는, 디폴트에서는 무효가 되어 있다. 이것은, 디스크로부터의 일시 페어 렌탈 락 레벨 커멘드는, 가능한 것은 않지만 무시되어 디스크가 중단되지 않고 재생되는 것을 의미한다. 디스크로부터의 일시 페어 렌탈 락 레벨 커멘드를 처리하려면 , 어플리케이션의 초기화중에 이 메소드를 호출한다. 유효하게 한 페어 렌탈 락을 무효로 하려면 , 인수에 FALSE 를 지정해 이 메소드를 호출한다. 페어 렌탈 락의 상세한 것에 대하여는, 「AcceptParentalLevelChange 」를 참조할것.

참조

페어 렌탈 락 레벨의 적용,SelectParentalLevel ,GetTitleParentalLevels ,GetPlayerParentalCountry ,GetPlayerParentalLevel ,SelectParentalCountry

Pause 메소드

MSWebDVD 오브젝트

재생을 현재 위치에서 포즈 한다.

구문

MSWebDVD. Pause();

반환값

반환값 없음.

주의

이미 재생이 포즈 하고 있는 경우, 이 메소드는 아무것도 실행하지 않는다.

Play 메소드

MSWebDVD 오브젝트

현재의 DVD 타이틀을 재생한다.

구문

MSWebDVD. Play();

반환값

반환값 없음.

주의

재생이 포즈 또는 정지하고 있어 EnableResetOnStop 가 TRUE 의 경우,Play 를 호출하면, 보통의 속도로 현재 위치로부터 재생이 재개한다. 재생이 정지하고 있어 EnableResetOnStop 가 FALSE 의 경우,Play 를 호출하면, 최초의 타이틀의 처음부터 디스크가 재생된다.

참조

Resume

PlayAtTime 메소드

MSWebDVD 오브젝트

현재의 타이틀의 지정된 시간부터 재생을 시작 한다.

구문

MSWebDVD. PlayAtTime(sTime);

파라미터

sTime 재생을 시작 할 시간을 지정하는 캐릭터 라인값. 포맷은 "hh:mm:ss:ff" (시, 분, 초, 프레임).

반환값

반환값 없음.

참조

PlayAtTimeInTitle

PlayAtTimeInTitle 메소드

MSWebDVD 오브젝트

지정된 타이틀의 지정된 시간부터 재생을 시작 한다.

구문

MSWebDVD. PlayAtTimeInTitle(sTime, iTitle);

파라미터

sTime | 재생을 시작 할 시간을 지정하는 캐릭터 라인값. 포맷은 "hh:mm:ss:ff" (시, 분, 초, 프레임).
iTitle | 타이틀의 인덱스를 지정하는 정수.

반환값

반환값 없음.

참조

CurrentTitle ,PlayAtTime ,TitlesAvailable

PlayBackwards 메소드

MSWebDVD 오브젝트

지정된 속도로 현재 위치로부터 역방향 재생을 시작 한다.

구문

MSWebDVD. PlayBackwards(nSpeed);

파라미터

nSpeed 재생의 속도를 지정하는 수치. 이 값은 승수이며, 예를 들어, 1.0 은 보통의 재생 속도, 2.0 은 배의 속도, 0.5 는 반의 속도를 의미한다. nSpeed 가 1.0 이외의 경우에는, 오디오가 뮤트 되어 서브 픽쳐가 오프가 된다.

반환값

반환값 없음.

참조

PlayForwards

PlayChapter 메소드

MSWebDVD 오브젝트

현재의 타이틀내의 지정된 쳅터로부터 재생을 시작 한다.

구문

MSWebDVD. PlayChapter(iChapter);

파라미터

iChapter 현재의 타이틀내에서의 쳅터 인덱스를 지정하는 정수값.

반환값

반환값 없음.

주의

지정된 쳅터의 마지막에 달하면(자), 그 후에 아직 쳅터가 있으면, 이 메소드는 계속해 그러한 쳅터를 재생한다. 지정한 쳅터만을 재생하려면 ,PlayChaptersAutoStop 를 사용한다.

참조

PlayChapterInTitle

PlayChaptersAutoStop 메소드

MSWebDVD 오브젝트

지정된 타이틀의 지정된 쳅터로부터 지정된 쳅터수의 재생을 시작 한다.

구문

MSWebDVD. PlayChaptersAutoStop(iTitle, iChapter, iChapterCount);

파라미터

iTitle | 타이틀을 지정하는 정수값.
iChapter | 시작 쳅터를 지정하는 정수값.
iChapterCount | 재생하는 쳅터수를 지정하는 정수값.

반환값

반환값 없음.

주의

마지막 쳅터의 재생이 끝나면(자), 이 메소드는, 어플리케이션에 EC_DVD_CHAPTER_AUTOSTOP 이벤트 통지가 보내지도록(듯이) 한다.

PlayChapterInTitle 메소드

MSWebDVD 오브젝트

지정된 타이틀의 지정된 쳅터를 재생한다.

구문

MSWebDVD. PlayChapterInTitle(iTitle, iChapter);

파라미터

iTitle | 타이틀을 지정하는 정수값.
iChapter | 쳅터를 지정하는 정수값.

주의

이 메소드는, 지정된 쳅터로부터 재생을 시작 해, 언제까지나 재생을 계속한다. 특정의 쳅터만을 재생하려면 ,PlayChaptersAutoStop 를 사용한다.

반환값

반환값 없음.

PlayForwards 메소드

MSWebDVD 오브젝트

지정된 속도로 현재 위치로부터 순서 방향 재생을 시작 한다.

구문

MSWebDVD. PlayForwards(nSpeed);

파라미터

nSpeed 재생의 속도를 지정하는 수치. 이 값은 승수이며, 예를 들어, 1.0 은 보통의 재생 속도, 2.0 은 배의 속도, 0.5 는 반의 속도를 의미한다. nSpeed 가 1.0 이외의 경우에는, 오디오가 뮤트 되어 서브 픽쳐가 오프가 된다.

반환값

반환값 없음.

참조

PlayBackwards

PlayNextChapter 메소드

MSWebDVD 오브젝트

현재의 타이틀의 다음의 쳅터로부터 재생을 시작 한다.

구문

MSWebDVD. PlayNextChapter();

반환값

반환값 없음.

참조

PlayPrevChapter

PlayPeriodInTitleAutoStop 메소드

MSWebDVD 오브젝트

지정된 타이틀의 지정된 시간부터 지정된 종료 타임까지의 재생을 시작 한다.

구문

MSWebDVD. PlayPeriodInTitleAutoStop(iTitle, sStartTime, sEndTime);

파라미터

iTitle | 타이틀을 지정하는 정수값.
sStartTime | 시작 타임을 지정하는 캐릭터 라인. 포맷은 "hh:mm:ss:ff" (시, 분, 초, 프레임).
sEndTime | 종료 타임을 지정하는 캐릭터 라인. 포맷은 "hh:mm:ss:ff" (시, 분, 초, 프레임).

반환값

반환값 없음.

참조

PlayChaptersAutoStop

PlayPrevChapter 메소드

MSWebDVD 오브젝트

현재의 타이틀의 직전의 타이틀로부터 재생을 시작 한다.

구문

MSWebDVD. PlayPrevChapter();

반환값

반환값 없음.

참조

PlayNextChapter

PlayState 프로퍼티

MSWebDVD 오브젝트

MSWebDVD 오브젝트의 현재 상태를 취득한다.

구문

[ iState = ] MSWebDVD. PlayState

가능한 값

iState DVD 네비게이터의 현재 상태를 나타내는 정수값. -2 (미정도리),-1 (초기화되어 있지 않다), 0 (정지), 1 (포즈), 2 (실행중)의 언젠가.

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

주의

MSWebDVD 오브젝트는 DirectShow DVD 네비게이터 필터를 제어해, DVD 네비게이션의 실제의 처리는 이 필터가 실시한다. 이 프로퍼티가 참조하는 것은, 실제로는 DVD 네비게이터 상태이다. DVD 네비게이터에게는, 위와 같게 몇개의 상태가 있다. PlayState 프로퍼티는 진단 툴로서 이용할 수 있지만, 보통, 스크립트 어플리케이션으로부터 DVD 네비게이터 상태를 감시할 이유는 없다.

PlayTitle 메소드

MSWebDVD 오브젝트

지정된 타이틀의 최초부터 재생을 시작 한다.

구문

MSWebDVD. PlayTitle(iTitle);

파라미터

iTitle 타이틀을 지정하는 정수값.

반환값

반환값 없음.

참조

PlayPeriodInTitleAutoStop

PreferredSubpictureStream 프로퍼티

MSWebDVD 오브젝트

현재 표시하고 있는 세션의 우선 서브 픽쳐 스트림을 설정 또는 취득한다.

구문

[ iStream = ] MSWebDVD. PreferredSubpictureStream

가능한 값

iStream MSWebDVD 오브젝트내의 현재의 우선 서브 픽쳐 스트림을 나타내는 정수값. 이 값은, Microsoft® Windows® 레지스트리내에 있는 현재의 디폴트의 우선 서브 픽쳐 스트림과 다른 경우가 있다. 디폴트의 우선 서브 픽쳐 스트림은,DVDAdm.DefaultSubpictureLCID 로 설정한다.

ReadyState 프로퍼티

MSWebDVD 오브젝트

MSWebDVD 오브젝트의 ReadyState 를 취득한다.

구문

[ iReadyState = ] MSWebDVD. ReadyState

가능한 값

iReadyState 컨트롤의 ReadyState 를 나타내는 정수값. 가능한 값은, READYSTATE_UNINITIALIZED = 0, READYSTATE_LOADING = 1, READYSTATE_LOADED = 2, READYSTATE_INTERACTIVE = 3, READYSTATE_COMPLETE = 4 의 언젠가.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

ReadyState 프로퍼티는, Web 페이지에 파묻히는 오브젝트로 공개된다. 이 값에는 다음의 의미가 있다.

READYSTATE_UNINITIALIZED | 디폴트의 초기화 상태.
READYSTATE_LOADING | 오브젝트는 프로퍼티를 로드안.
READYSTATE_LOADED | 오브젝트는 초기화되었다.
READYSTATE_INTERACTIVE | 오브젝트는 응답 가능하지만, 이용할 수 없는 데이터가 있다.
READYSTATE_COMPLETE | 오브젝트는 데이터를 모두 받았다.

Render 메소드

MSWebDVD 오브젝트

DVD 필터 그래프를 초기화한다.

구문

MSWebDVD.  Render(iRender = 0);

파라미터

iRender 필터 그래프를 파기 및 재구축 할지 어떨지를 지정하는 정수값. 지정하지 않았던 경우, 값은 0 으로 보여진다. 0 은, 필터 그래프가 이미 존재하는 경우에 파기 및 재구축 하지 않는 것을 의미한다. 그래프를 파기 및 재구축 하려면 , 1 을 지정한다.

반환값

반환값 없음.

주의

Render 메소드를 사용 하면,MSWebDVD 오브젝트로부터, 그 기반이 되는 DirectShow 필터 그래프를 기동시에 완전하게 초기화할 수 있다. 초기화해 두면(자), 유저가 디스크를 재생 또는 메뉴를 표시하기 위해서 최초로 커멘드를 발행했을 때 발생하는 약간의 지연을 없앨 수가 있다. 다른 메소드를 호출하기 전에,Render 를 호출할 필요는 없다. 예를 들어, 필터 그래프의 초기화전에 어플리케이션으로부터 PlayTitle 를 호출하면,MSWebDVD 오브젝트는, 디스크 재생전에 자동적으로 Render 를 호출한다.

ReplayChapter 메소드

MSWebDVD 오브젝트

현재의 쳅터의 최초부터 재생을 시작 한다.

구문

MSWebDVD. ReplayChapter();

반환값

반환값 없음.

참조

PlayChapter ,PlayChaptersAutoStop

RegionChange 메소드

MSWebDVD 오브젝트

DVD 에 관련지을 수 있었던 리젼을 유저가 변경하기 위한 시스템 다이알로그 박스를 표시한다.

구문

MSWebDVD. RegionChange();

주의

DVD 드라이브의 리젼은, 5 회 밖에 변경할 수 없다.

반환값

반환값 없음.

RestoreBookmark 메소드

MSWebDVD 오브젝트

현재의 북마크가 가리키는 디스크 위에의 위치에 MSWebDVD 오브젝트를 이동해, 오디오, 비디오, 및 서브 픽쳐의 설정을 모두 복원한다.

구문

MSWebDVD. RestoreBookmark();

반환값

반환값 없음.

Resume 메소드

MSWebDVD 오브젝트

메뉴 표시 후에 재생을 재개한다.

구문

MSWebDVD. Resume();

반환값

반환값 없음.

ReturnFromSubmenu 메소드

MSWebDVD 오브젝트

표시를 서브 메뉴로부터 친메뉴에 되돌린다. 톱 레벨 메뉴라면 현재의 타이틀에 되돌린다.

구문

MSWebDVD. ReturnFromSubmenu();

반환값

반환값 없음.

SaveBookmark 메소드

MSWebDVD 오브젝트

유저가 다음에 같은 장소로 돌아갈 수 있도록(듯이), MSWebDVD 오브젝트의 현재의 디스크 위치 및 상태를 보존한다.

구문

MSWebDVD. SaveBookmark();

반환값

반환값 없음.

주의

북마크는, DVD 네비게이터의 현재 상태의 snapshot이다. 여기에는, 재생중의 디스크 위치나, 선택하고 있는 오디오 스트림 및 서브 픽쳐 스트림등의 정보가 포함된다. 북마크를 보존 하면, 어플리케이션을 종료해, 컴퓨터를 슛다운 해도, 나중에 전과 완전히 같은 설정으로 디스크의 계속을 보는 것이로 있다. 북마크는 동시에 1 개(살) 밖에 보존할 수 없다. SaveBookmark 를 호출하면, 낡은 북마크에 오버라이드(override) 된다.

참조

RestoreBookmark ,북마크의 보존과 복원

SelectAndActivateButton 메소드

MSWebDVD 오브젝트

지정된 버튼을 선택해, 액티브하게 한다.

구문

MSWebDVD. SelectAndActivateButton(iButton);

파라미터

iButton 버튼을 지정하는 정수값.

반환값

반환값 없음.

주의

DisableAutoMouseProcessing 를 TRUE 로 설정한 후, 커스텀 마우스 핸들링을 이행 하는 경우는, 이 메소드를 사용한다.

이 메소드는, 지정된 버튼을 강조 표시해, 자동적으로 액티브하게 한다.

참조

ButtonsAvailable ,CurrentButton ,ActivateButton ,GetButtonAtPosition ,GetButtonRect ,SelectAtPosition

SelectAtPosition 메소드

MSWebDVD 오브젝트

지정된 (마우스 포인터의) 좌표에 있는 메뉴 버튼을 선택한다.

구문

MSWebDVD. SelectAtPosition(xPos, yPos);

파라미터

xPos | x 좌표를 지정하는 정수값.
yPos | y 좌표를 지정하는 정수값.

반환값

반환값 없음.

주의

DisableAutoMouseProcessing 를 TRUE 로 설정한 후, 커스텀 마우스 핸들링을 이행 하는 경우는, 이 메소드를 사용한다.

버튼을 선택 하면, 그 버튼이 다만 강조 표시된다. 선택한 버튼에 관련지을 수 있었던 커멘드를 보내려면 ,ActivateButton 를 호출한다.

참조

ButtonsAvailable ,CurrentButton ,GetButtonAtPosition ,GetButtonRect ,SelectAndActivateButton

SelectDefaultAudioLanguage 메소드

MSWebDVD 오브젝트

MSWebDVD 오브젝트내의 현재의 디폴트 오디오 언어를 설정한다.

구문

MSWebDVD. SelectDefaultAudioLanguage(iLang, iExt);

파라미터

iLang | 언어를 지정하는 정수의 LCID 값. 가능한 값에 대해서는, 「LCID 의 조작」의 일람을 참조할것.
iExt | DVD 오디오 언어 extension를 지정하는 정수값. 가능한 값에 대해서는, 「주의」를 참조할것.

주의

extension | 값
지정 없음 (NotSpecified) | 0
캡션 (Captions) | 1
시각 장애자전용 (VisuallyImpaired) | 2
디렉터 코멘트 1 (DirectorComments1) | 3
디렉터 코멘트 2 (DirectorComments2) | 4

반환값

반환값 없음.

SelectDefaultSubpictureLanguage 메소드

MSWebDVD 오브젝트

MSWebDVD 오브젝트내의 현재의 디폴트 서브 픽쳐 언어를 설정한다.

구문

MSWebDVD. SelectDefaultSubpictureLanguage(iLang,iExt);

파라미터

iLang | 언어를 지정하는 정수값.
iExt | 서브 픽쳐 언어 extension를 지정하는 정수값. 가능한 값에 대해서는, 「주의」를 참조할것.

반환값

반환값 없음.

주의

서브 픽쳐 언어 extension는, 서브 픽쳐에 관한 상세 정보를 제공한다. 가능한 반환값은 다음과 같다.

extension | 값
지정 없음 | 0
캡션 (노멀) | 1
캡션 (대) | 2
캡션 (어린이용) | 3
자막 방송 (노멀) | 5
자막 방송 (대) | 6
자막 방송 (어린이용) | 7
강제 | 9
디렉터 코멘트 (노멀) | 13
디렉터 코멘트 (대) | 14
디렉터 코멘트 (어린이용) | 15

SelectLeftButton 메소드

MSWebDVD 오브젝트

표시된 메뉴로부터 좌방향 버튼을 선택한다.

구문

MSWebDVD. SelectLeftButton();

반환값

반환값 없음.

참조

ActivateButton ,SelectLowerButton ,SelectRightButton ,SelectUpperButton

SelectLowerButton 메소드

MSWebDVD 오브젝트

표시된 메뉴로부터 아래방향 버튼을 선택한다.

구문

MSWebDVD. SelectLowerButton();

반환값

반환값 없음.

참조

ActivateButton ,SelectLeftButton ,SelectRightButton ,SelectUpperButton

SelectParentalCountry 메소드

MSWebDVD 오브젝트

향후의 재생에 사용하는 나라로서 지정된 페어 렌탈 지방을 설정한다.

구문

MSWebDVD. SelectParentalCountry(iCountry, sUserName, sPassword);

파라미터

iCountry | 국을 지정하는 정수값.
sUserName | 현재의 로그 온 유저를 지정하는 캐릭터 라인값 (현재는 무시된다).
sPassword | 어플리케이션의 패스워드를 지정하는 캐릭터 라인값.

반환값

반환값 없음.

주의

페어 렌탈 지방은 페어 렌탈 락 레벨의 해석을 결정한다.

참조

페어 렌탈 락 레벨의 적용,SelectParentalLevel ,NotifyParentalLevelChange ,GetTitleParentalLevels ,GetPlayerParentalCountry ,GetPlayerParentalLevel ,AcceptParentalLevelChange

SelectParentalLevel 메소드

MSWebDVD 오브젝트

향후의 재생에 사용하는 페어 렌탈 락 레벨로서 지정된 페어 렌탈 락 레벨을 설정한다.

구문

MSWebDVD. SelectParentalLevel(iLevel, sUserName, sPassword);

파라미터

iLevel | 페어 렌탈 락 레벨을 지정하는 정수값 (1 ~ 8). 페어 렌탈 락을 무효로 하려면 ,iLevel 에 -1 를 설정한다.
sUserName | 현재의 유저를 지정하는 캐릭터 라인값 (현재는 무시된다).
sPassword | 레지스트리에 현재 저장 되고 있는 패스워드를 지정하는 캐릭터 라인값.

반환값

반환값 없음.

주의

이 메소드는, MSWebDVD 오브젝트내의 페어 렌탈 락 레벨을 설정한다. 유저가 재생할 수 있는 컨텐츠는 이 페어 렌탈 락 레벨로 정해진다. 높은 레벨에서는 레벨의 낮은 컨텐츠를 재생할 수 있지만, 낮은 레벨에서는 레벨의 높은 컨텐츠를 재생할 수 없다. DVD 의 8 개의 페어 렌탈 락 레벨이 가지는 정확한 의미는 나라에 의해 다르다. 미국 및 캐나다의 경우, 레벨은 MPAA (Motion Picture Association of America)의 레이팅 카테고리에 대응한다. 디폴트에서는, DVD 네비게이터의 페어 렌탈 락은 무효가 되어 있다.

참조

페어 렌탈 락 레벨의 적용,SelectParentalCountry ,NotifyParentalLevelChange ,GetTitleParentalLevels ,GetPlayerParentalCountry ,GetPlayerParentalLevel ,AcceptParentalLevelChange

SelectRightButton 메소드

MSWebDVD 오브젝트

표시된 메뉴로부터 우측향버튼을 선택한다.

구문

MSWebDVD. SelectRightButton();

반환값

반환값 없음.

참조

ActivateButton ,SelectLeftButton ,SelectLowerButton ,SelectUpperButton

SelectUpperButton 메소드

MSWebDVD 오브젝트

표시된 메뉴로부터 윗방향 버튼을 선택한다.

구문

MSWebDVD. SelectUpperButton();

반환값

반환값 없음.

참조

ButtonsAvailable ,CurrentButton ,ActivateButton ,GetButtonAtPosition ,GetButtonRect ,SelectAndActivateButton ,SelectAtPosition ,SelectLeftButton ,SelectLowerButton ,SelectRightButton

SetClipVideoRect 메소드

MSWebDVD 오브젝트

지정된 서브 직사각형에 맞추어 비디오 표시를 줌 한다.

구문

 DVD. SetClipVideoRect(oRect);

파라미터

oRect 클리핑 직사각형을 지정하는 DVDRect 오브젝트.

반환값

반환값 없음.

주의

새로운 클리핑 직사각형을 설정 하면, 오브젝트가 어플리케이션의 표시 넓이 전체에 맞추어 그 영역을 확대한다. 이렇게 하면(자), 화면의 특정 영역에 줌인 하는 이펙트가 생성된다. 직사각형을 지정하려면 , 새로운 DVDRect 오브젝트를 생성 해, 그 프로퍼티를 설정한다.

비디오 표시에는 일반적으로 720 x 540 의 직사각형을 사용한다.

참조

GetClipVideoRect

SetDelayTime

MSWebDVD 오브젝트

MSWebDVD 오브젝트에 관련지을 수 있었던 툴 팁에 대응하는 지연 시간을 설정한다.

구문

MSWebDVD. SetDelayTime(iDelayType, iNewVal)

파라미터

iDelayType | 지연의 종류를 지정하는 정수값. 「주의」를 참조할것.
iNewVal | 지연 시간을 지정하는 정수값 (밀리 세컨드 단위).

반환값

반환값 없음.

주의

다음의 일람은,iDelayType 로서 가능한 값이다.

TTDT_AUTOPOP = 0 | 포인터가 툴의 경계 직사각형내에 일정시간 머물면(자),[툴 팁] 윈도우가 소거된다. 이 시간의 길이 (자동 pop-up의 지연 시간)를 설정한다. 디폴트값에 되돌리려면 , iNewVal 에 -1 를 설정한다.
TTDT_INITIAL = 1 | 포인터가 툴의 경계 직사각형내에 일정시간 정지 하면,[툴 팁] 윈도우가 표시된다. 이 시간의 길이 (첫 시작의 지연 시간)를 설정한다. 디폴트값에 되돌리려면 , iNewVal 에 -1 를 설정한다.
TTDT_RESHOW = 2 | 포인터가 다른 툴로 이동하면(자), 일정시간 후에 다음의 [툴 팁] 윈도우가 표시된다. 이 시간의 길이 (재표시의 지연 시간)를 설정한다. 디폴트값에 되돌리려면 , iNewVal 에 -1 를 설정한다.
TTDT_AUTOMATIC = 3 | 3 개의 지연 시간의 비율을 디폴트에 되돌린다. 자동 pop-up 시간은 초기 시간의 10 배, 재표시 시간은 초기 시간 1/5 이다. 이 플래그를 설정하는 경우, iNewVal 에 정의 값을 사용해 초기 지연 시간 (밀리 세컨드 단위)을 지정한다. 3 개의 지연 시간 모든 것을 각각의 디폴트값에 되돌리려면 , iNewVal 에 부의 값을 설정한다.

SetGPRM 메소드

MSWebDVD 오브젝트

지정된 일반 파라미터 레지스터로 지정된 값을 설정한다.

구문

MSWebDVD. SetGPRM(iIndex, nValue)

파라미터

iIndex | 설정하는 일반 파라미터 레지스터를 지정하는 0 ~ 15 의 정수값.
iValue | 레지스터로 설정하는 새로운 값을 지정하는 정수.

주의

일반 파라미터 레지스터 (GPRM)는, 각 디스크가 일시 데이터의 저장에 자유롭게 사용할 수 있는 16 비트 레지스터이다. 플레이어 어플리케이션에서는,MSWebDVD 오브젝트를 사용해 재생 또는 네비게이션의 표준적인 제어를 위해서(때문에), 이러한 레지스터에 액세스 할 필요는 없다. 이 메소드는, 진행된 기능을 이행 하는 플레이어 어플리케이션을 위해서(때문에) 제공된다. DVD 의 사양과 GPRM 를 사용해 그 디스크가 어떻게 재생될까를 완전하게 이해하고 있지 않는 한, GPRM 를 직접 변경하지 않는 것. GPRM 의 값을 변경했을 경우, 거기에 따라 일으켜지는 동작은 예측 불가능하다.

ShowCursor 메소드

MSWebDVD 오브젝트

MSWebDVD 오브젝트가 풀 스크린 모드 때에 커서를 표시한다.

구문

MSWebDVD. ShowCursor(bShow);

파라미터

bShow 커서를 표시할지 어떨지를 지정하는 불리언 값.

반환값

반환값 없음.

주의

DVD 의 표시가 풀 스크린 모드에 바뀌면(자), 3 ~ 5 초에 커서가 사라진다. 풀 스크린 모드로 어플리케이션의 컨트롤 버튼이 표시되는 경우, 커서를 한번 더 표시하려면 , 이 메소드를 사용한다.

ShowMenu 메소드

MSWebDVD 오브젝트

지정된 메뉴를 화면상에 표시한다.

구문

MSWebDVD. ShowMenu(iMenuID);

파라미터

iMenuID 메뉴를 지정하는 정수값. 가능한 값에 대해서는, 「주의」를 참조할것.

반환값

반환값 없음.

주의

iMenuID 로서 가능한 값은 다음과 같다.
메뉴의 종류 | 값
타이틀 (탑) | 2
루트 | 3
서브 픽쳐 | 4
오디오 | 5
앵글 | 6
쳅터 | 7

DVD 의 메뉴명은 약간 복잡하다. [타이틀(title)] 메뉴는, 디스크 전체의 메인 메뉴인 Video Manager Menu 의 별명이며, 보통, 여기에 디스크내의 이용 가능한 비디오 타이틀 세트가 모두 표시된다. [루트(root)] 메뉴는, 1 개의 비디오 타이틀 세트에 대응하는 메뉴이다. 비디오 타이틀 세트에는, 1 개(살) 이상의 타이틀이 들어가 있다. 타이틀 세트내의 전타이틀은, 같은 [서브 픽쳐(Subpicture)] 메뉴,[오디오(Audio)] 메뉴, 및 [앵글(Angle)] 메뉴를 공유한다.

Step 메소드

MSWebDVD 오브젝트

DVD 비디오 스트림이 지정된 프레임수만큼 진행한다.

구문

MSWebDVD. Step(iFrames)

파라미터

iFrames 스탭핑(Stepping)하는 프레임수를 지정하는 정수값.

반환값

반환값 없음.

주의

이 메소드를 호출하기 전에,CanStep 를 호출해 디코더가 스탭핑(Stepping)를 지원 하고 있을지 어떨지를 판단한다.

DVD 비디오를 반전 모드로 재생하고 있을 때 이 메소드를 호출하면, 디코더가 반전의 스탭핑(Stepping)를 지원 하고 있으면, 스탭핑(Stepping)도 반전으로 행해진다.

StillOff 메소드

MSWebDVD 오브젝트

재생을 재개해, 정지 모드를 캔슬한다.

구문

MSWebDVD. StillOff();

반환값

반환값 없음.

주의

디스크상에 명기된 정지 프레임이 발견되면(자),DVD 네비게이터는, 정지 모드에 바뀌어,EC_DVD_STILL_ON 이벤트를 보내 어플리케이션에 통지한다. DVD 네비게이터의 정지 모드는, 유저 조작의 점으로써 포즈 상태와 다르다. StillOff 를 호출하면, 정지 모드로부터는 재생하러 돌아오지만, 포즈 상태의 DVD 네비게이터는 재개하지 않는다.

Stop 메소드

MSWebDVD 오브젝트

재생을 정지한다.

구문

MSWebDVD. Stop();

반환값

반환값 없음.

주의

EnableResetOnStop 가 TRUE 로 설정되어 있는 경우는,Stop 를 호출하면, DVD 네비게이터가 필터 그래프의 남은 부분과 함께 정지상태태에 바뀐다. 이것은, 유저가 다음에 [재생] 버튼을 누르면(자), 디스크의 최초부터 재생이 시작되는 것을 의미한다. EnableResetOnStop 가 TRUE 로 설정되어 있는 경우는, 유저가 다음의 Play 커멘드를 발행 하면, 마지막에 재생된 위치로부터 재생이 재개한다.

SubpictureOn 프로퍼티

MSWebDVD 오브젝트

서브 픽쳐의 현재 상태 (온/오프)를 설정 또는 취득한다.

구문

[ bState = ] MSWebDVD. SubpictureOn

가능한 값

bState 서브 픽쳐가 표시될지 어떨지를 나타내는 불리언 값.

주의

이 프로퍼티는, 자막 방송의 표시에는 영향을 주지 않는다. 자막 방송은 비디오 스트림내에 파묻히고 있지만, DVD 의 서브 픽쳐는 독립한 스트림으로 트랜스폴트 된다.

이 프로퍼티는, 디폴트값이 false 의 읽고 쓰기 가능한 프로퍼티이다.

SubpictureStreamsAvailable 프로퍼티

MSWebDVD 오브젝트

현재의 타이틀내의 이용 가능한 서브 픽쳐 스트림수를 취득한다.

구문

[ iStreams = ] MSWebDVD. SubpictureStreamsAvailable

가능한 값

iStreams 이용 가능한 오디오 스트림수를 나타내는 정수값.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다. 개개의 스트림에 그 언어 속성을 조회하려면 , 우선 이 메소드를 호출해 상한을 취득한다. 스트림의 번호는 0 으로부터 시작된다.

TitlesAvailable 프로퍼티

MSWebDVD 오브젝트

디스크 위에의 이용 가능한 타이틀수를 취득한다.

구문

[ iTitles = ] MSWebDVD. TitlesAvailable

가능한 값

iTitles 이용 가능한 타이틀수를 나타내는 1 ~ 99 의 정수값.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다.

ToolTip 프로퍼티

MSWebDVD 오브젝트

마우스 포인터가 MSWebDVD 비디오 직사각형과 겹쳐졌을 때에 표시되는 툴 팁의 텍스트를 설정한다.

구문

[ sToolTip = ] MSWebDVD. ToolTip

가능한 값

sToolTip 툴 팁의 텍스트를 지정하는 캐릭터 라인값.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다. 캐릭터 라인이 하늘의 경우, 툴 팁은 표시되지 않는다.

ToolTipMaxWidth 프로퍼티

MSWebDVD 오브젝트

MSWebDVD 오브젝트에 관련지을 수 있었던 툴 팁의 최대폭을 설정 또는 취득한다.

구문

[ iMaxWidth = ] MSWebDVD. ToolTipMaxWidth

가능한 값

iMaxWidth 어플리케이션의 툴 팁의 최대폭을 나타내는 정수값.

주의

이 프로퍼티는, 디폴트값이 200 픽셀의 읽고 쓰기 가능한 프로퍼티이다.

TotalTitleTime 프로퍼티

MSWebDVD 오브젝트

현재의 타이틀의 총재생 시간을 취득한다.

구문

[ sTotalTime = ] MSWebDVD. TotalTitleTime

가능한 값

sTotalTime 현재의 타이틀의 총재생 시간을 나타내는 캐릭터 라인값. 포맷은 "hh:mm:ss:ff".

주의

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다. "hh:mm:ss:ff" (시, 분, 초, 프레임)라고 하는 포맷의 11 문자의 캐릭터 라인이 돌려주어진다.

참조

PlayAtTime ,PlayAtTimeInTitle

UOPValid 메소드

MSWebDVD 오브젝트

지정된 유저 조작 (UOP)이 현재 유효한가 어떤가를 나타내는 값을 취득한다.

구문

[ bIsValid = ] MSWebDVD. UOPValid(iUOP);

파라미터

iUOP UOP 를 지정하는 정수값. 가능한 값에 대해서는, 「주의」를 참조할것.

반환값

지정된 조작이 UOP 컨트롤에 용서될지 어떨지를 나타내는 불리언 값을 돌려준다.

주의

iUOP 로서 가능한 값은 다음과 같이 정의되고 있다.

값 | 유저 함수
0x0 | PlayTitle ,PlayAtTime ,PlayAtTimeInTitle
0x1 | PlayChapter
0x2 | PlayTitle
0x4 | Stop
0x8 | ReturnFromSubmenu
0x10 | PlayChapter
0x20 | PlayPrevChapter ,ReplayChapter
0x40 | PlayNextChapter
0x80 | PlayForwards
0x100 | PlayBackwards
0x200 | ShowMenu 의 인수에 2 (DVD_MENU_Title)를 지정
0x400 | ShowMenu 의 인수에 3 (DVD_MENU_Root)을 지정
0x800 | ShowMenu 의 인수에 4 (DVD_MENU_Subpicture)를 지정
0x1000 | ShowMenu 의 인수에 5 (DVD_MENU_Audio)를 지정
0x2000 | ShowMenu 의 인수에 6 (DVD_MENU_Angle)을 지정
0x4000 | ShowMenu 의 인수에 7 (DVD_MENU_Chapter)을 지정
0x8000 | Resume
0x10000 | SelectLeftButton ,SelectRightButton ,SelectUpperButton ,SelectLowerButton
0x20000 | StillOff
0x40000 | Pause
0x80000 | CurrentAudioStream
0x100000 | CurrentSubpictureStream
0x200000 | CurrentAngle ,SelectParentalLevel
0x400000 | KaraokeAudioPresentationMode

Volume 프로퍼티

MSWebDVD 오브젝트

오디오 스트림 출력의 스피커 볼륨을 설정 또는 취득한다.

구문

[ iVolume = ] MSWebDVD. Volume

가능한 값

iVolume 볼륨을 감쇠 (데시벨)로 표현한 정수값.

주의

이 프로퍼티는, 디폴트값이 0 의 읽고 쓰기 가능한 프로퍼티이다. 최대 볼륨은 0, 무음은 10, 000. 스케일은 대수이다. 목적의 데시벨값을 100 배가 된다 (예를 들어, 10, 000 = 100 dB).

VolumesAvailable 프로퍼티

MSWebDVD 오브젝트

복수 볼륨세트에 포함되는 볼륨수를 취득한다.

구문

[ iVolumes = ] MSWebDVD. VolumesAvailable

가능한 값

iVolumes 세트에 포함되는 볼륨의 수를 나타내는 정수값.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 독해 전용 프로퍼티이다. DVD 타이틀은, 복수의 디스크 세트나 시리즈로 릴리스 되는 일이 있다. 현재의 디스크의 볼륨 번호를 판단하려면 , 이 메소드를 사용한다.

WindowlessActivation 프로퍼티

MSWebDVD 오브젝트

윈도우 모드와 윈드우레스모드의 어느 쪽인가에 사용하는 MSWebDVD 오브젝트를 설계시에 초기화한다.

구문

[ bWindowless = ] MSWebDVD. WindowlessActivation

가능한 값

bWindowless 오브젝트가 윈도우 모드인가 어떤가를 나타내는 불리언 값.

주의

이 프로퍼티는, 디폴트값이 TRUE 의 읽고 쓰기 가능한 프로퍼티이다. 따라서, 이 프로퍼티를 설정해야 하는 것은,MSWebDVD 오브젝트를 윈도우 첨부 컨테이너내에서 실행하고 있는 경우 뿐이다. Microsoft® Internet Explorer 의 Web 페이지내에서는,MSWebDVD 가 항상 윈드우레스모드가 되기 (위해)때문에, 이 프로퍼티를 설정할 필요는 없다.

Zoom 메소드

MSWebDVD 오브젝트

소정의 화면 좌표를 중심으로, 비디오 표시를 줌인/줌 아웃 한다.

구문

MSWebDVD. Zoom(iXPos, iYPos, iZoomRatio);

파라미터

iXPos | 줌 하는 직사각형의 중앙의 x 좌표를 지정하는 정수값.
iYPos | 줌 하는 직사각형의 중앙의 y 좌표를 지정하는 정수값.
iZoomRatio | 현재의 줌값에 적용하는 배율을 지정하는 수치. 줌 후의 최대 사이즈는, 하드웨어 오버레이의 지원에 따라서 다르지만, 보통은 원의 사이즈의 32 ~ 64 배이다.

반환값

반환값 없음.

주의

새로운 줌율은, 원의 사이즈에 되돌리는지, 또는 재차 변경할 때까지 유효하다. 즉,iZoomRatio 에 2 를 지정해 이 메소드를 2 회 호출하면, 줌율이 비디오 본래의 사이즈의 4 배가 된다. 유저가 하드웨어의 능력을 넘어 줌 하려고 했을 경우, 이 메소드는 성공하지만, 아무것도 실행되지 않는다.

줌인에는 SetClipVideoRect 메소드를 사용해도 괜찮다. 2 개의 방법의 유일한 차이는, 줌 직사각형의 지정 방법에 있다.


MSDVDAdm 오브젝트

MSDVDAdm "관리 " 오브젝트의 메소드 및 프로퍼티를 사용 하면, 스크립트 어플리케이션으로부터, Microsoft® Windows® 레지스트리내에 있는 어플리케이션 자체의 디폴트 설정을 수정할 수 있다. 레지스트리는, 모든 Windows 시스템에 있는 데이타베이스이며, 어플리케이션으로부터 어플리케이션 자체에 관한 정보를 저장 해, 초기화 또는 실행시에 사용할 수가 있다.

이러한 메소드 및 프로퍼티의 상당수는,MSWebDVD 오브젝트 자체의 현재가를 설정 또는 취득하는 것은 아니다. 즉, 예를 들어 GetParentalLevel 를 호출했을 때에 돌려주어지는 값은, 오브젝트에 저장 된 현재의 페어 렌탈 락 레벨은 아니다. 돌려주어지는 값은, 레지스트리에 저장 된 디폴트의 페어 렌탈 락 레벨이다. 현재의 페어 렌탈 락 레벨을 취득하려면 ,MSWebDVD 메소드의 GetPlayerParentalLevel 를 호출한다. SaveParentalLevel 를 호출하면, 다만, 새로운 디폴트의 페어 렌탈 락 레벨이 레지스트리에 기입해진다. 그 변경을 즉시 MSWebDVD 오브젝트에 반영하려면 ,MSWebDVD 메소드의 SelectParentalLevel 를 호출할 필요가 있다. 디폴트의 로케일 식별자 (LCID) 관련 메소드도 같은 동작을 한다.

한편,BookmarkOnStop 메소드 및 BookmarkOnClose 메소드에서의 설정은 즉시 반영된다. 이것은,MSWebDVD 오브젝트가, 초기화시는 아니고, 유저가 재생을 정지할까 어플리케이션을 종료하기 직전에, 이러한 설정을 확인하기 위해(때문에)이다.

MSDVDAdm 오브젝트에는,MSWebDVD 의 DVDAdm 프로퍼티를 통해서 액세스 한다. 이 때문에, 예를 들어 MSWebDVD 오브젝트의 이름이 "DVD" 이면, 다음과 같이 ChangePassword 를 호출한다.

DVD.DVDAdm.ChangePassword(sUserName, sOld, sNew);

메소드 및 프로퍼티

다음의 일람은, MSDVDAdm 오브젝트로 공개되는 메소드 및 프로퍼티이다.
메소드
ChangePassword | 어플리케이션의 새로운 패스워드를 레지스트리에 보존한다.
SaveParentalLevel | 새로운 디폴트의 페어 렌탈 락 레벨을 레지스트리에 보존한다.
SaveParentalCountry | 어플리케이션의 새로운 페어 렌탈 지방을 레지스트리에 보존한다.
ConfirmPassword | 지정된 패스워드가 직전에 보존한 패스워드와 일치할지 어떨지 검사한다.
GetParentalLevel | 레지스트리에 마지막에 보존한 페어 렌탈 락 레벨을 취득한다.
GetParentalCountry | 레지스트리에 마지막에 보존한 페어 렌탈 지방을 취득한다.
RestoreScreenSaver | 시스템의 스크린 세이버 설정을 복원한다.
프로퍼티
DisableScreenSaver | 시스템의 스크린 세이버의 온/오프를 바꾼다.
DefaultAudioLCID | 오디오 스트림에 대응하는 유저가 지정한 디폴트 LCID 의 레지스트리 설정을 설정 또는 취득한다.
DefaultSubpictureLCID | 서브 픽쳐 스트림에 대응하는 유저가 지정한 디폴트 LCID 의 레지스트리 설정을 설정 또는 취득한다.
DefaultMenuLCID | 메뉴에 대응하는 유저가 지정한 디폴트 LCID 의 레지스트리 설정을 설정 또는 취득한다.
BookmarkOnStop | MSDVDAdm 오브젝트에, 유저가 [정지] 버튼을 클릭했을 때에 현재 위치와 설정의 북마크를 자동적으로 보존할지 어떨지를 알리는 값을, 설정 또는 취득한다.
BookmarkOnClose | MSDVDAdm 오브젝트에, 유저가 어플리케이션을 종료했을 때에 현재 위치와 설정의 북마크를 자동적으로 보존할지 어떨지를 알리는 값을, 설정 또는 취득한다.

BookmarkOnClose 프로퍼티

MSDVDAdm 오브젝트

MSDVDAdm 오브젝트에, 유저가 어플리케이션을 종료했을 때에 현재 위치와 설정의 북마크를 자동적으로 보존할지 어떨지를 알리는 값을, 설정 또는 취득한다.

구문

[ bBookmarkOnClose = ] DVD. DVDAdm.BookmarkOnClose

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
bBookmarkOnClose | 유저가 DVD 플레이어 어플리케이션을 종료했을 때에, 디스크 위에의 위치, 페어 렌탈 락 레벨, 및 페어 렌탈 지방을 포함한 모든 DVD 설정의 북마크를, MSDVDAdm 컨트롤로 보존할지 어떨지를 나타내는불형의 값.

주의

이 프로퍼티는, 디폴트값이 TRUE 의 읽고 쓰기 가능한 프로퍼티이다.

참조

BookmarkOnStop ,북마크의 보존과 복원

BookmarkOnStop 프로퍼티

MSDVDAdm 오브젝트

MSWebDVD 오브젝트에, 유저가 [정지] 버튼을 클릭했을 때에 현재 위치와 설정의 북마크를 자동적으로 보존할지 어떨지를 알리는 값을, 설정 또는 취득한다.

구문

[ bBookmarkOnStop = ] DVD. DVDAdm.BookmarkOnStop

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
bBookmarkOnStop | 디스크 위에의 위치, 페어 렌탈 락 레벨, 및 페어 렌탈 지방을 포함한 모든 DVD 설정의 북마크를, MSDVDAdm 오브젝트로 보존할지 어떨지를 나타내는불형의 값.

주의

이 프로퍼티는, 디폴트값이 FALSE 의 읽고 쓰기 가능한 프로퍼티이다.

북마크는 그 컴퓨터에서만 유효하다. 다른 컴퓨터로 읽어내기 (위해)때문에, 유저가 북마크를 보존해, 다른 유저에게 보낼 수 없다.

참조

BookmarkOnClose

ChangePassword 메소드

MSDVDAdm 오브젝트

어플리케이션의 새로운 패스워드를 레지스트리에 보존한다.

구문

DVD. DVDAdm.ChangePassword(sUserName, sOld, sNew );

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
sUserName | 현재의 유저의 로그 온명을 지정하는캐릭터 라인형의 값. MSDVDAdm 오브젝트는 이 파라미터를 무시한다. 「주의」를 참조할것.
sOld | 유저의 낡은 패스워드를 지정하는캐릭터 라인형의 값.
sNew | 유저의 새로운 패스워드를 지정하는캐릭터 라인형의 값. NULL 여서는 안 된다.

반환값

반환값 없음.

주의

현재,sUserName 파라미터는, 이 메소드를 포함한 모든 관련 메소드로 무시된다. 이것은, 패스워드를 알고 있는 유저이면, 누구라도 페어 렌탈 락 레벨을 설정할 수 있는 것을 의미한다. 어플리케이션에는, 패스워드와 페어 렌탈 락 레벨이 각각 1 개(살) 밖에 없다. 개개의 유저의 로그 온명 또는 복수 패스워드의 관리는 지원되어 있지 않다. 페어 렌탈 락을 사용하려면 , 어른이 패스워드를 설정한 데다가, 아이에게 적합한 페어 렌탈 락 레벨을 설정할 필요가 있다. 성인전용 컨텐츠가 저장 된 디스크를 어른이 재생하려면 , 페어 렌탈 락 레벨을 변경해, 보고 끝나고 나서 바탕으로 되돌리면 좋다. 패스워드를 모르는 한, 아이는 설정한 페어 렌탈 락 레벨 이하의 컨텐츠 밖에 볼 수가 없다.

참조

ConfirmPassword

ConfirmPassword 메소드

MSDVDAdm 오브젝트

지정된 패스워드가 직전에 보존한 패스워드와 일치할지 어떨지 검사한다.

구문

[ bIsConfirmed = ] DVD. DVDAdm.ConfirmPassword(sUserName, sPassword);

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
sUserName | 유저명을 지정하는캐릭터 라인형의 값. 「주의」를 참조할것.
sPassword | 새로운 패스워드를 지정하는캐릭터 라인형의 값.

반환값

지정된 패스워드가 기존의 패스워드와 일치하는 경우는, TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

주의

현재,sUserName 파라미터는, 이 메소드를 포함한 모든 관련 메소드로 무시된다.

참조

ChangePassword

DefaultAudioLCID 프로퍼티

MSDVDAdm 오브젝트

오디오 스트림에 대응하는 유저가 지정한 디폴트 LCID 의 레지스트리 설정을 설정 또는 취득한다.

구문

[ iAudioLCID = ] DVD. DVDAdm.DefaultAudioLCID

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
iAudioLCID | DVD 어플리케이션에 대응하는 레지스트리 설정에 저장 된, 유저가 지정한 디폴트의 오디오 LCID 를 나타내는정수형의 값. 이 값은, DVD 에 명기된 디폴트의 오디오 스트림과 동일하다고는 할 수 없다. 유효한 LCID 의 범위에 대해서는, Platform SDK 의 Microsoft® Win32® 문서를 참조할것.

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다. 디폴트의 오디오 LCID 를 지정하지 않았던 경우, MSDVDAdm 오브젝트는, 디폴트 스트림으로서 디스크에 마크 된 오디오 스트림을 재생한다.

DefaultMenuLCID 프로퍼티

MSDVDAdm 오브젝트

메뉴에 대응하는 유저가 지정한 디폴트 LCID 의 레지스트리 설정을 설정 또는 취득한다.

구문

[ iMenuLCID = ] DVD. DVDAdm.DefaultMenuLCID

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
iMenuLCID | DVD 어플리케이션에 대응하는 레지스트리 설정에 저장 된 LCID 를 나타내는정수형의 값. 이 값은, DVD 에 명기된 디폴트의 메뉴 언어와 동일하다고는 할 수 없다. 유효한 LCID 의 범위에 대해서는, Platform SDK 의 Win32 문서를 참조할것.

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다. 디폴트의 메뉴 LCID 를 지정하지 않았던 경우, MSDVDAdm 오브젝트는, 디폴트의 메뉴 언어로서 디스크에 마크 된 언어를 사용한다.

DefaultSubpictureLCID 프로퍼티

MSDVDAdm 오브젝트

서브 픽쳐 스트림에 대응하는 유저가 지정한 디폴트 LCID 의 레지스트리 설정을 설정 또는 취득한다.

구문

[ iSubpictureLCID = ] DVD. DVDAdm.DefaultSubpictureLCID

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
iSubpictureLCID | DVD 어플리케이션에 대응하는 레지스트리 설정에 저장 된, 유저가 지정한 디폴트의 서브 픽쳐 LCID 를 나타내는정수형의 값. 이 값은, DVD 에 명기된 디폴트의 서브 픽쳐 스트림과 동일하다고는 할 수 없다. 유효한 LCID 의 범위에 대해서는, Platform SDK 의 Win32 문서를 참조할것.

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다. 디폴트의 서브 픽쳐 LCID 를 지정하지 않았던 경우, MSDVDAdm 오브젝트는, 디폴트 스트림으로서 디스크에 마크 된 서브 픽쳐 스트림을 재생한다.

DisableScreenSaver 프로퍼티

MSDVDAdm 오브젝트

시스템의 스크린 세이버의 온/오프를 바꾼다.

구문

[ bDisabled = ] DVD. DVDAdm.DisableScreenSaver

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
bDisabled | 시스템의 DVD 플레이어 어플리케이션에 대응하는 스크린 세이버 설정이 오프가 되어 있는지 어떤지를 나타내는불형의 값. TRUE 는 오프가 되어 있는 것을 의미한다.

이 프로퍼티는, 디폴트값이 TRUE 의 읽고 쓰기 가능한 프로퍼티이다.

주의

DVD 비디오의 디스크를 볼 때는, 마우스나 키보드를 장시간 사용하지 않는 것이 많다. 이 때문에, MSWebDVD ActiveX® 컨트롤은, 디폴트로 시스템의 스크린 세이버를 무효로 한다.

참조

RestoreScreenSaver

GetParentalCountry 메소드

MSDVDAdm 오브젝트

레지스트리에 마지막에 보존한 페어 렌탈 지방을 취득한다.

구문

[ iParentalCountry = ] DVD. DVDAdm.GetParentalCountry();

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.

반환값

레지스트리에 저장 된 디폴트의 국별 코드를 나타내는 정수를 돌려준다.

주의

이 메소드로 취득하는 페어 렌탈 지방은, MSWebDVD 오브젝트에 현재 저장 되고 있는 나라와 같다고는 할 수 없다.

GetParentalLevel 메소드

MSDVDAdm 오브젝트

레지스트리에 마지막에 보존한 페어 렌탈 락 레벨을 취득한다.

구문

[ iParentalLevel = ] DVD. DVDAdm.GetParentalLevel();

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.

반환값

디폴트의 페어 렌탈 락 레벨을 나타내는 1 ~ 8 의 정수를 돌려준다.

주의

이 메소드로 취득하는 페어 렌탈 락 레벨은, MSWebDVD 컨트롤에 현재 저장 되고 있는 페어 렌탈 락 레벨과 동일하다고는 할 수 없다. 컨트롤에 현재 저장 되고 있는 페어 렌탈 락 레벨을 취득하려면 ,MSWebDVD.GetPlayerParentalLevel 를 호출한다. -1 의 값은 페어 렌탈 락이 무효라는 점을 나타낸다.

RestoreScreenSaver 메소드

MSDVDAdm 오브젝트

시스템의 스크린 세이버 설정을 복원한다.

구문

DVD. DVDAdm.RestoreScreenSaver();

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.

반환값

반환값 없음.

주의

보통, DVD 어플리케이션에서는, 기동시에 DisableScreenSaver 프로퍼티를 TRUE 로 설정해 시스템의 스크린 세이버를 무효로 해, 종료시에 RestoreScreenSaver 를 호출해 스크린 세이버를 한번 더 유효하게 한다. 어플리케이션으로 시스템의 스크린 세이버 설정을 사용하지 않으면, 이 메소드를 호출하거나DisableScreenSaver 프로퍼티를 세트 하거나 할 필요는 없다.

SaveParentalCountry 메소드

MSDVDAdm 오브젝트

어플리케이션의 새로운 페어 렌탈 지방을 레지스트리에 보존한다.

구문

DVD. DVDAdm.SaveParentalCountry( iCountry,  sUserName, sPassword);

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
iCountry | 페어 렌탈 지방을 지정하는정수형의 값.
sUserName | 유저명을 지정하는캐릭터 라인형의 값. 현재는 무시된다.
sPassword | 패스워드를 지정하는캐릭터 라인형의 값.

반환값

반환값 없음.

주의

이 메소드를 사용 하면, 현재의 패스워드를 알고 있는 유저가, 레지스트리에 새로운 페어 렌탈 지방의 설정을 보존할 수 있다. MSDVDAdm 의 전메소드와 같이, 이 메소드는, 플레이어내의 현재의 페어 렌탈 락 레벨은 변경하지 않고 , 레지스트리만을 변경한다. 이 때문에, 새로운 나라에서 열리는 것은, 다음에 생성 한 MSWebDVD 오브젝트이다. 플레이어내의 페어 렌탈 지방을 변경하려면 ,MSWebDVD.SelectParentalCountry 를 호출한다. 이 경우, 레지스트리 설정은 변경되지 않는다.

참조

SaveParentalLevel

SaveParentalLevel 메소드

MSDVDAdm 오브젝트

새로운 디폴트의 페어 렌탈 락 레벨을 레지스트리에 보존한다.

구문

DVD. DVDAdm.SaveParentalLevel( iLevel, sUserName, sPassword);

원가요소

DVD | MSWebDVD 오브젝트를 나타내는 오브젝트식.
DVDAdm | MSWebDVD 오브젝트의 DVDAdm 프로퍼티.
iLevel | 페어 렌탈 락 레벨을 지정하는정수형의 값 (1 ~ 8).
sUserName | 유저명을 지정하는캐릭터 라인형의 값. 현재는 무시된다.
sPassword | 패스워드를 지정하는캐릭터 라인형의 값.

반환값

반환값 없음.

주의

이 메소드를 사용 하면, 현재의 패스워드를 알고 있는 유저가, 레지스트리에 새로운 페어 렌탈 락 레벨 설정을 보존할 수 있다. MSDVDAdm 의 전메소드와 같이, 이 메소드는, 플레이어내의 현재의 페어 렌탈 락 레벨은 변경하지 않고 , 레지스트리만을 변경한다. 이 때문에, 새로운 페어 렌탈 락 레벨로 열리는 것은, 다음에 기동한 MSWebDVD 오브젝트이다. 플레이어내의 페어 렌탈 락 레벨을 변경하려면 ,MSWebDVD.SelectParentallevel 를 호출한다. 이 경우, 레지스트리 설정은 변경되지 않는다. -1 의 값은 페어 렌탈 락이 무효라는 점을 나타낸다.


DVDRect 오브젝트

DVDRect 오브젝트의 프로퍼티를 사용 하면, 스크립트 어플리케이션으로부터,GetButtonRect ,GetClipVideoRect ,GetVideoSize ,SetClipVideoRect 등의 MSWebDVD 메소드의 직사각형 좌표를 지정 및 취득할 수 있다.

프로퍼티

프로퍼티
x | 직사각형의 맨 왼쪽 위쪽의 x 좌표를 설정 또는 취득한다.
y | 직사각형의 맨 왼쪽 위쪽의 y 좌표를 설정 또는 취득한다.
Width | 직사각형의 폭 (픽셀 단위)을 설정 또는 취득한다.
Height | 직사각형의 높이 (픽셀 단위)를 설정 또는 취득한다.

Height 프로퍼티

직사각형의 높이를 설정 또는 취득한다.

구문

[ iHeight = ] DVDRect. Height

원가요소

DVDRect | MSWebDVD 오브젝트를 나타내는 오브젝트식.
iHeight | 직사각형의 높이 (픽셀 단위).

주의

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다.

Width 프로퍼티

직사각형의 폭을 설정 또는 취득한다.

구문

[ iWidth = ] DVDRect. Width

원가요소

DVDRect | MSWebDVD 오브젝트를 나타내는 오브젝트식.
iWidth | 직사각형의 폭 (픽셀 단위).

주의

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다.

x 프로퍼티

직사각형의 맨 왼쪽 위쪽의 x 좌표를 설정 또는 취득한다.

구문

[ iXPos = ] DVDRect. x

원가요소

DVDRect | MSWebDVD 오브젝트를 나타내는 오브젝트식.
iXPos | 직사각형의 맨 왼쪽 위쪽의 x 좌표.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다.

y 프로퍼티

직사각형의 맨 왼쪽 위쪽의 y 좌표를 설정 또는 취득한다.

구문

[ iYPos = ] DVDRect. y

원가요소

DVDRect | MSWebDVD 오브젝트를 나타내는 오브젝트식.
iYPos | 직사각형의 맨 왼쪽 위쪽의 y 좌표.

주의

이 프로퍼티는, 디폴트값을 가지지 않는 읽고 쓰기 가능한 프로퍼티이다.


MSWebDVD 이벤트

MSWebDVD Microsoft® ActiveX® 컨트롤은, 각종의 내부 이벤트가 발생했을 때나, 디스크상에 특정의 정보가 발견되었을 때에, 어플리케이션에 통지한다.

이벤트의 대부분은, 유저 조작 (UOP) 컨트롤에 관련한다. DVD 의 생성자는, 임의의 DVD 커멘드 (PlayForwards,Pause,ShowMenu 등)를 언제라도 무효로 할 수 있도록(듯이) 디스크를 encode 할 수 있다. 예를 들어, 많은 디스크에서는, FBI 에 의한 통고의 재생중에는 조돌리기나 메뉴 표시를 할 수 없지만, 통고가 끝나면(자) 할 수 있게 되어 있다. 어플리케이션에서는, UOP 이벤트를 처리해, 유저 인터페이스를 갱신하는 것에 의해, 현재 그 디스크에 실행할 수 있는 커멘드를 유저에게 알릴 수가 있다. 보통, 이것에는 버튼의 유효/무효를 바꾼다. 예를 들어,bEnabled 가 FALSE 에 세트 된 PlayForwards 이벤트를 받으면(자) [재생] 버튼을 무효로 해,bEnabled 가 TRUE 에 세트 된 PlayForwards 이벤트를 받으면(자) [재생] 버튼을 한번 더 유효하게 한다.

UOP 컨트롤에 관련하지 않는 이벤트는 3 개 있다. DVDNotify 이벤트는, DVD 에 관련하는 각종의 통지를 어플리케이션에 통지한다. 이벤트는 EventCode 파라미터로 식별한다. 이벤트에 따라서는,Param1 파라미터 및 Param2 파라미터에 추가 정보가 건네받는다. ReadyStateChange 이벤트는, ActiveX 컨트롤 모두에게 공통의 프로퍼티인 MSWebDVD ReadyState 프로퍼티의 변화를, 어플리케이션에 통지한다. UpdateOverlay 이벤트는, 윈드우레스모드로 MSWebDVD 의 호스트가 되고 있는 어플리케이션에게만 보내진다. 어플리케이션에서는, 풀 스크린 모드로 비디오 직사각형상에 플로팅 버튼을 표시하고 있는 경우에게만, 이 이벤트에 응답하면 좋다.

참조

이벤트의 처리 방법을 나타내는 샘플 코드에 대해서는, 「DVD 이벤트 통지의 처리」를 참조할것.

MSWebDVD 오브젝트

이벤트

이벤트 | 설명
ChangeCurrentAngle | 디스크로 앵글의 변경이 유효 또는 무효가 되면(자) 송신된다.
ChangeCurrentAudioStream | 디스크로 오디오 스트림의 변경이 유효 또는 무효가 되면(자) 송신된다.
ChangeCurrentSubpictureStream | ChangeCurrentSubpictureStream 커멘드가 유효 또는 무효가 되면(자) 송신된다.
DVDNotify | 각종의 DVD 이벤트 및 디스크 관련 명령을 어플리케이션에 통지한다.
PauseOn | Pause 커멘드가 유효 또는 무효가 되면(자) 송신된다.
PlayAtTime | PlayAtTime 커멘드가 유효 또는 무효가 되면(자) 송신된다.
PlayAtTimeInTitle | PlayAtTimeInTitle 커멘드가 유효 또는 무효가 되면(자) 송신된다.
PlayBackwards | PlayBackwards 커멘드가 유효 또는 무효가 되면(자) 송신된다.
PlayChapter | PlayChapter 커멘드가 유효 또는 무효가 되면(자) 송신된다.
PlayChapterInTitle | PlayChapterInTitle 커멘드가 유효 또는 무효가 되면(자) 송신된다.
PlayForwards | PlayForwards 커멘드가 유효 또는 무효가 되면(자) 송신된다.
PlayNextChapter | PlayNextChapter 커멘드가 유효 또는 무효가 되면(자) 송신된다.
PlayPrevChapter | PlayPrevChapter 커멘드가 유효 또는 무효가 되면(자) 송신된다.
PlayTitle | ReturnFromSubmenu 커멘드가 유효 또는 무효가 되면(자) 송신된다.
ReadyStateChange | MSWebDVD 컨트롤의 ReadyState 프로퍼티가 변화 하면 송신된다.
ReplayChapter | ReplayChapter 커멘드가 유효 또는 무효가 되면(자) 송신된다.
Resume | Resume 커멘드가 유효 또는 무효가 되면(자) 송신된다.
ReturnFromSubmenu | ReturnFromSubmenu 커멘드가 유효 또는 무효가 되면(자) 송신된다.
SelectOrActivatButton | 디스크로 메뉴 버튼의 액티브가 유효 또는 무효가 되면(자) 송신된다.
ShowMenu | 디스크로 메뉴의 표시가 유효 또는 무효가 되면(자) 송신된다.
StillOff | StillOff 커멘드가 유효 또는 무효가 되면(자) 송신된다.
Stop | Stop 커멘드가 유효 또는 무효가 되면(자) 송신된다.
UpdateOverlay | 오버레이 표면이 이동 또는 사이즈 변경되는지, 또는 그 칼라 키가 변화 하면 송신된다.

ChangeCurrentAngle

MSWebDVD 이벤트

디스크로 앵글의 변경이 유효 또는 무효가 되면(자) 송신된다.

구문

ChangeCurrentAngle(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

ChangeCurrentAudioStream

MSWebDVD 이벤트

디스크로 오디오 스트림의 변경이 유효 또는 무효가 되면(자) 송신된다.

구문

ChangeCurrentAudioStream(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

ChangeCurrentSubpictureStream

MSWebDVD 이벤트

디스크로 서브 픽쳐 스트림의 변경이 유효 또는 무효가 되면(자) 송신된다.

구문

ChangeCurrentSubpictureStream(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

DVDNotify

MSWebDVD 이벤트

각종의 DVD 이벤트 및 디스크 관련 명령을 어플리케이션에 통지한다.

구문

DVDNotify(EventCode, Param1, Param2)

파라미터

EventCode | DVD 이벤트를 지정한다.
Param1 | 이벤트에 관련하는 추가 정보가 들어가는 일이 있다.
param2 | 이벤트에 관련하는 추가 정보가 들어가는 일이 있다.

참조

DVD 이벤트 통지 코드와 그 파라미터의 완전한 일람에 대해서는, 「DVD 이벤트 통지 코드」를 참조할것.

PauseOn

MSWebDVD 이벤트

PauseOn 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PauseOn(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

PlayAtTime

MSWebDVD 이벤트

PlayAtTime 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PlayAtTime(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

PlayAtTimeInTitle

MSWebDVD 이벤트

PlayAtTimeInTitle 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PlayAtTimeInTitle(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

PlayBackwards

MSWebDVD 이벤트

PlayBackwards 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PlayBackwards(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

PlayChapter

MSWebDVD 이벤트

PlayChapter 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PlayChapter(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

PlayChapterInTitle

MSWebDVD 이벤트

PlayChapterInTitle 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PlayChapterInTitle(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

PlayForwards

MSWebDVD 이벤트

PlayForwards 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PlayForwards(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

PlayNextChapter

MSWebDVD 이벤트

PlayNextChapter 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PlayNextChapter(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

PlayPrevChapter

MSWebDVD 이벤트

PlayPrevChapter 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PlayPrevChapter(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

PlayTitle

MSWebDVD 이벤트

PlayTitle 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

PlayTitle(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

ReadyStateChange

MSWebDVD 이벤트

MSWebDVD 컨트롤의 ReadyState 프로퍼티가 변화 하면 송신된다.

구문

ReadyStateChange(ReadyState)

파라미터

ReadyState ReadyState 프로퍼티의 새로운 값을 나타낸다. 가능한 값은, READYSTATE_UNINITIALIZED = 0, READYSTATE_LOADING = 1, READYSTATE_LOADED = 2, READYSTATE_INTERACTIVE = 3, READYSTATE_COMPLETE = 4 의 언젠가.

ReplayChapter

MSWebDVD 이벤트

ReplayChapter 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

ReplayChapter(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

Resume

MSWebDVD 이벤트

Resume 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

Resume(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

ReturnFromSubmenu

MSWebDVD 이벤트

ReturnFromSubmenu 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

ReturnFromSubmenu(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

SelectOrActivatButton

MSWebDVD 이벤트

디스크로 메뉴 버튼의 액티브가 유효 또는 무효가 되면(자) 송신된다.

구문

SelectOrActivatButton(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

ShowMenu

MSWebDVD 이벤트

디스크로 메뉴의 표시가 유효 또는 무효가 되면(자) 송신된다.

구문

ShowMenu(DVDMenuIDConstants, bEnabled)

파라미터

DVDMenuIDConstants 유효 또는 무효가 된 메뉴를 나타내는 수치. 가능한 값은 다음의 언젠가이다.
2 | 타이틀
3 | 루트
4 | 서브 픽쳐
5 | 오디오
6 | 앵글
7 | 쳅터
bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

StillOff

MSWebDVD 이벤트

StillOff 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

StillOff(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

Stop

MSWebDVD 이벤트

Stop 커멘드가 유효 또는 무효가 되면(자) 송신된다.

구문

Stop(bEnabled)

파라미터

bEnabled 처리가 유효한가 무효인가 어떤가를 나타내는 불형의 값.

UpdateOverlay

MSWebDVD 이벤트

오버레이 표면이 이동 또는 사이즈 변경되는지, 또는 그 칼라 키가 변화 하면 송신된다.

구문

UpdateOverlay()

주의

어플리케이션에서는, 사이즈 변경 또는 이동되는 오버레이 표면을 신경써서는 안 된다. 그것은 모두 내부적으로 처리된다. 이 이벤트는 칼라 키가 변화했을 때에도 보내진다. 즉, 윈도우가 없는 컨트롤로서 MSWebDVD 의 호스트가 되고 있는 어플리케이션에서는, 풀 스크린 모드로 비디오 표면상에 플로팅 버튼을 표시하고 있는 경우, 버튼을 올바르게 표시하려면 ,ColorKey 프로퍼티의 새로운 값을 취득해 이 이벤트에 응답해야 한다.


프로퍼티 세트

Microsoft® DirectShow® 는, 프로퍼티 세트를 사용해, 하드웨어와 그 관련 드라이버 및 필터가 제공하는 확장 서비스를 지원 한다. 하드웨어 및 필터의 벤더는, 새로운 능력을 프로퍼티로서 정의해, 그것들을 프로퍼티 세트에 정리해 프로퍼티 세트의 사양을 공개할 수가 있다. 어플리케이션 벤더는,IKsPropertySet 인터페이스의 메소드를 사용해, 드라이버나 필터가 특정의 프로퍼티 세트를 지원 하고 있을지 어떨지 판단해, 그러한 프로퍼티를 취득 또는 설정할 수가 있다.

IKsPropertySet 가 공개하는 모든 메소드에서는, 프로퍼티 세트를 식별하는 GUID (guidPropSet 파라미터)와 프로퍼티 세트내의 프로퍼티를 식별하는 DWORD (dwPropID 파라미터)가 필요하게 된다. dwPropID 파라미터는, 보통, 열거형의 멤버이다.

개개의 프로퍼티에는,IKsPropertySet::Set 메소드 및 IKsPropertySet::Get 메소드의 pPropData 파라미터로 지정한 데이터를 관련지을 수가 있다. 이러한 파라미터는,IKsPropertySet 로 내부적으로 정의되지 않고 (데이터형 LPVOID), 프로퍼티 세트 개발자가 개개의 프로퍼티에 적절한 방법으로 사용할 수 있게 되어 있다. 각 프로퍼티의 정의는, 프로퍼티 데이터의 목적을 제공한다.

DirectShow 는, DVD 와 캡춰를 위한 프로퍼티 세트를 제공한다. 이하의 항에서는, 이러한 프로퍼티의 상세한 것에 대하여 설명한다.

  • DVD 카피 보호 프로퍼티 세트
  • DVD 가라오케 프로퍼티 세트
  • DVD 서브 픽쳐 프로퍼티 세트
  • 스탭핑(Stepping)리프로퍼티 세트
  • 핀 프로퍼티 세트


DVD 카피 보호 프로퍼티 세트

DVD 카피 보호 프로퍼티 세트는, 하드웨아데크리프타 또는 소후트웨아데크리프타로부터 얻을 수 있는 카피 보호 정보의 인증을 제공한다. 이 프로퍼티 세트는, DVD 비디오로부터의 불법 복사를 방지하기 위해서 사용한다.

Microsoft 는, 암호화 방식으로 필요한 인증 처리를 돕는 것으로, DVD-ROM 드라이브가 DVD 데크리프타를 사용해 키의 인증 및 전송이 생기도록(듯이) 하는 소프트웨어를 제공한다. 현재로서는 DVD 데크리프타를 제품화할 예정은 없지만, 대신에, 하드웨아데크리프타와 소후트웨아데크리프타의 어느 쪽인가의 인증을 유효하게 하는 에이전트로서 기능하는 시스템 코드를 제공하고 있다.

DVD 네비게이터는 키 교환 처리를 시작 및 제어한다. DVD 미니 드라이버는 이하의 프로퍼티를 이행 하는 것만으로 좋다. 나머지는 그 외의 컴퍼넌트가 처리한다.

카피 보호 프로퍼티는, 개개의 DVD 입력 스트림에 보내진다. 이것은, DVD 스트림을 모두 같은 하드웨어로 제어하는 경우에서도 변함없다.

다음의 정보는,IKsPropertySet 메소드의 호출로 이 프로퍼티 세트에 사용하기 위해서 필요한 정수 및 데이터형의 정보를 나타내고 있다. GUID (guidPropSet), 프로퍼티 ID (dwPropID), 및 프로퍼티의 데이터형 (pPropData) 파라미터의 값을 제공한다.

프로퍼티 세트 GUID: AM_KSPROPSETID_CopyProt
프로퍼티 ID | 지정된 프로퍼티에 의해 사용되는 데이터형
AM_PROPERTY_COPY_MACROVISION | AM_COPY_MACROVISION
AM_PROPERTY_DVDCOPY_CHLG_KEY | AM_DVDCOPY_CHLGKEY
AM_PROPERTY_DVDCOPY_DEC_KEY2 | AM_DVDCOPY_BUSKEY
AM_PROPERTY_DVDCOPY_DISC_KEY | AM_DVDCOPY_DISCKEY
AM_PROPERTY_DVDCOPY_DVD_KEY1 | AM_DVDCOPY_BUSKEY
AM_PROPERTY_DVDCOPY_REGION | DVD_REGION 구조체.
AM_PROPERTY_DVDCOPY_SET_COPY_STATE | AM_DVDCOPY_SET_COPY_STATE
AM_PROPERTY_DVDCOPY_TITLE_KEY | AM_DVDCOPY_TITLEKEY

다음의 일람은, DVD 카피 보호 프로퍼티의 ID 와 그 설명이다.

AM_PROPERTY_COPY_MACROVISION
이것은 설정 전용 프로퍼티이다. 이 프로퍼티는, 수신 핀의 출력 측에 있는 NTSC 엔코더의 매크로 비전 레벨을 설정한다.
AM_PROPERTY_DVDCOPY_CHLG_KEY
이 프로퍼티에서는 설정과 취득의 양쪽 모두의 조작이 지원 되고 있다. 취득 조작에서는, 디코더에 그 버스 챌린지 키의 제공을 요구한다. 설정 조작에서는, DVD 드라이브로부터의 버스 챌린지 키를 디코더에 제공한다. 이 프로퍼티에게 건네지는 데이터는,AM_DVDCOPY_CHLGKEY 형의 구조체이다.
AM_PROPERTY_DVDCOPY_DEC_KEY2
이것은 취득 전용 프로퍼티이다. 이 프로퍼티는, 디코더의 버스 키 2 를 DVD 드라이브에 전송 하도록(듯이) 요구한다. 건네받는 데이터는 AM_DVDCOPY_BUSKEY 형의 구조체이다.
AM_PROPERTY_DVDCOPY_DISC_KEY
이것은 취득 전용 프로퍼티이다. 이 프로퍼티는 디스크 키를 제공한다. 디스크 키는 AM_DVDCOPY_DISCKEY 형의 구조체이다.
AM_PROPERTY_DVDCOPY_DVD_KEY1
이것은 설정 전용 프로퍼티이다. 이 프로퍼티는 DVD 드라이브의 버스 키 1 을 디코더에 제공한다. 건네받는 데이터는 AM_DVDCOPY_BUSKEY 형의 구조체이다.
AM_PROPERTY_DVDCOPY_SET_COPY_STATE
이 프로퍼티에서는 설정과 취득의 양쪽 모두의 조작이 지원 되고 있다. 우선, 인증이 필요한가 어떤가를 판단하기 위해서(때문에) Get 가 불려 간다. 설정 프로퍼티는, 카피 보호의 네고시에이션의 어느 국면에 필터가 들어가려 하고 있는지를 나타낸다. 건네받는 데이터는 AM_DVDCOPY_SET_COPY_STATE 형의 구조체이다.
AM_PROPERTY_DVDCOPY_REGION
지역 코드는, DVD 컨소시엄으로 결정된 그 디코더를 재생에 사용할 수 있는 지역의 정의를 요구한다. 이 지역은 다음의 구조체로 정의된다.
typedef struct _DVD_REGION {
   UCHAR CopySystem;   //디스크가 카피 보호되고 있는지 어떤지를 지정한다.
   UCHAR RegionData;    //디코더로부터의 지역 정보.
   UCHAR SystemRegion;  //DVD 드라이브로부터의 지역 정보.
   UCHAR Reserved; //예약이 끝난 상태.
} DVD_REGION, *PDVD_REGION;
AM_PROPERTY_DVDCOPY_TITLE_KEY
이것은 설정 전용 프로퍼티이다. 이 프로퍼티는, 현재의 컨텐츠로부터의 타이틀 키를 제공한다. 이 키는 AM_DVDCOPY_TITLEKEY 형의 구조체이다.

IKsPropertySet 인터페이스를 사용해, 이러한 프로퍼티를 지원 하기 위해서 설정, 취득, 및 쿼리를 실시한다.

이 프로퍼티 세트에서는, 다음의 데이터형이 사용된다.
데이터형 | 설명
AM_COPY_MACROVISION | NTSC 엔코더의 매크로 비전 레벨.
AM_COPY_MACROVISION_LEVEL | 매크로 비전 레벨. AM_COPY_MACROVISION 구조체는 이 데이터형을 사용한다.
AM_DVDCOPY_BUSKEY | DVD 버스 키.
AM_DVDCOPY_CHLGKEY | DVD 챌린지 키.
AM_DVDCOPY_DISCKEY | DVD 디스크 키.
AM_DVDCOPY_SET_COPY_STATE | 필터의 카피 보호 상태를 판단한다.
AM_DVDCOPYSTATE | 카피 보호 상태. AM_DVDCOPY_SET_COPY_STATE 구조체는 이 데이터형을 사용한다.
AM_DVDCOPY_TITLEKEY | 현재의 컨텐츠로부터의 DVD 타이틀 키.

AM_COPY_MACROVISION

DVD 카피 보호 프로퍼티 세트

NTSC 엔코더의 매크로 비전 레벨.

구문

typedef struct _AM_COPY_MACROVISION {
    ULONG MACROVISIONLevel;
} AM_COPY_MACROVISION, *PAM_COPY_MACROVISION;

멤버

MACROVISIONLevel
NTSC 엔코더의 매크로 비전 레벨. AM_COPY_MACROVISION_LEVEL 열거형의 멤버.

주의

AM_PROPERTY_COPY_MACROVISION 프로퍼티는 이 구조체를 사용한다.

AM_COPY_MACROVISION_LEVEL

DVD 카피 보호 프로퍼티 세트

매크로 비전 레벨.

구문

typedef enum {
    AM_MACROVISION_DISABLED,
    AM_MACROVISION_LEVEL1,
    AM_MACROVISION_LEVEL2,
    AM_MACROVISION_LEVEL3
} AM_COPY_MACROVISION_LEVEL, *PAM_COPY_MACROVISION_LEVEL;

요소

AM_MACROVISION_DISABLED
무효.
AM_MACROVISION_LEVEL1
레벨 1.
AM_MACROVISION_LEVEL2
레벨 2.
AM_MACROVISION_LEVEL3
레벨 3.

주의

AM_COPY_MACROVISION 구조체는 이 데이터형을 사용한다.

AM_DVDCOPY_BUSKEY

DVD 카피 보호 프로퍼티 세트

DVD 버스 키.

구문

 typedef struct _AM_DVDCOPY_BUSKEY {
    BYTE BusKey[5];
    BYTE Reserved[1];
} AM_DVDCOPY_BUSKEY, *PAM_DVDCOPY_BUSKEY;

멤버

BusKey
DVD 드라이브의 버스 키.
Reserved
예약이 끝난 상태.

주의

AM_PROPERTY_DVDCOPY_DVD_KEY1 프로퍼티와 AM_PROPERTY_DVDCOPY_DEC_KEY2 프로퍼티는 이 구조체를 사용한다.

버스 키는, 암호 해제를 위한 DVD CSS 키 교환에 사용한다. 이행자는, CSS 라이센스를 취득해, CSS 로부터의 것보다 자세한 설명을 참조할 필요가 있다. 연락처의 정보에 대해서는, 「DVD 비디오의 사양」을 참조할것.

AM_DVDCOPY_CHLGKEY

DVD 카피 보호 프로퍼티 세트

DVD 챌린지 키.

구문

 typedef struct _AM_DVDCOPY_CHLGKEY {
    BYTE ChlgKey[10];
    BYTE Reserved[2];
} AM_DVDCOPY_CHLGKEY, *PAM_DVDCOPY_CHLGKEY;

멤버

ChlgKey
챌린지 키.
Reserved
예약이 끝난 상태.

주의

AM_PROPERTY_DVDCOPY_CHLG_KEY 프로퍼티는 이 구조체를 사용한다.

챌린지 키는, 암호 해제를 위한 DVD CSS 키 교환에 사용한다. 이행자는, CSS 라이센스를 취득해, CSS 로부터의 것보다 자세한 설명을 참조할 필요가 있다. 연락처의 정보에 대해서는, 「DVD 비디오의 사양」을 참조할것.

AM_DVDCOPY_DISCKEY

DVD 카피 보호 프로퍼티 세트

DVD 디스크 키.

구문

 typedef struct _AM_DVDCOPY_DISCKEY {
    BYTE DiscKey[2048];
} AM_DVDCOPY_DISCKEY, *PAM_DVDCOPY_DISCKEY;

멤버

DiscKey
DVD 디스크 키.

주의

AM_PROPERTY_DVDCOPY_DISC_KEY 프로퍼티는 이 구조체를 사용한다.

디스크 키는, 암호 해제를 위한 DVD CSS 키 교환에 사용한다. 이행자는, CSS 라이센스를 취득해, CSS 로부터의 것보다 자세한 설명을 참조할 필요가 있다. 연락처의 정보에 대해서는, 「DVD 비디오의 사양」을 참조할것.

AM_DVDCOPY_SET_COPY_STATE

DVD 카피 보호 프로퍼티 세트

필터의 카피 보호 상태를 판단한다.

구문

typedef struct AM_DVDCOPY_SET_COPY_STATE {
    ULONG DVDCopyState;
} AM_DVDCOPY_SET_COPY_STATE, *PAM_DVDCOPY_SET_COPY_STATE;

멤버

DVDCopyState
필터의 카피 보호 상태. AM_DVDCOPYSTATE 열거형의 멤버.

주의

이 프로퍼티에서는,IKsPropertySet::Get 메소드와 IKsPropertySet::Set 메소드의 양쪽 모두가 지원 된다. 인증이 필요한가 어떤가를 판단하기 (위해)때문에, 우선 IKsPropertySet::Get 메소드가 불려 간다. 하드웨어 DVD 디코더와 같이, 같은 인증자를 사용하는 복수의 핀을 제공하는 필터가 있는 경우, 키 교환 알고리즘을 1 번만 적용하면 좋은 일을 나타내기 (위해)때문에, 디코더가 일부의 핀에 대해 AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED 로 응답할 가능성이 있다. 이 프로퍼티가 발행되는 최초의 핀의 올바른 카피 보호 상태를 취득하기 위해서는, 이 필터가 AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED 로 응답할 필요가 있다.

IKsPropertySet::Set 메소드는, 카피 보호의 네고시에이션의 어느 국면에 필터가 들어가려 하고 있는지를 나타내기 위해서(때문에) 사용한다. 국면은,AM_DVDCOPYSTATE 열거형의 필요한 플래그를 세트 해 지정한다.

AM_PROPERTY_DVDCOPY_SET_COPY_STATE 프로퍼티는 이 구조체를 사용한다.

AM_DVDCOPYSTATE

DVD 카피 보호 프로퍼티 세트

카피 보호 상태.

구문

typedef enum {
    AM_DVDCOPYSTATE_INITIALIZE,
        AM_DVDCOPYSTATE_INITIALIZE_TITLE,
    AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED,
    AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED,
    AM_DVDCOPYSTATE_DONE
} AM_DVDCOPYSTATE;

요소

AM_DVDCOPYSTATE_INITIALIZE
완전한 키 교환 알고리즘을 시작 한다.
AM_DVDCOPYSTATE_INITIALIZE_TITLE
타이틀 키 교환 알고리즘을 시작 한다.
AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED
인증은 필요없다.
AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED
인증이 필요.
AM_DVDCOPYSTATE_DONE
키 교환의 네고시에이션이 완료했다.

주의

AM_DVDCOPY_SET_COPY_STATE 구조체는 이 데이터형을 사용한다.

AM_DVDCOPY_TITLEKEY

DVD 카피 보호 프로퍼티 세트

현재의 컨텐츠로부터의 DVD 타이틀 키.

구문

 typedef struct AM_DVDCOPY_TITLEKEY {
    ULONG KeyFlags;
    UCHAR TitleKey[6];
    UCHAR Reserved[2];
} AM_DVDCOPY_TITLEKEY, *PAM_DVDCOPY_TITLEKEY;

멤버

KeyFlags
키 플랙.
TitleKey
타이틀 키.
Reserved
예약이 끝난 상태.

주의

AM_PROPERTY_DVDCOPY_TITLE_KEY 프로퍼티는 이 구조체를 사용한다.

타이틀 키는, 암호 해제를 위한 DVD CSS 키 교환에 사용한다. 이행자는, CSS 라이센스를 취득해, CSS 로부터의 것보다 자세한 설명을 참조할 필요가 있다. 연락처의 정보에 대해서는, 「DVD 비디오의 사양」을 참조할것.


DVD 가라오케 프로퍼티 세트

DVD 네비게이터 필터는, 가라오케 모드에 바뀔 때,AM_PROPERTY_DVDKARAOKE_ENABLE 프로퍼티를 통해서 오디오 디코더에 알린다. 디코더는, 외부 채널의 믹싱 방법을 나타내는 AM_DvdKaraokeData 구조체에의 포인터가 지정된 AM_PROPERTY_DVDKARAOKE_DATA 프로퍼티를 DVD 네비게이터로부터 받을 때까지, 오디오 채널 2 ~ 5 를 뮤트 할 필요가 있다.

AM_PROPERTY_DVDKARAOKE

DVD 가라오케 프로퍼티 세트

구문

typedef enum {
    AM_PROPERTY_DVDKARAOKE_ENABLE = 0,  // 불
    AM_PROPERTY_DVDKARAOKE_DATA = 1,
} AM_PROPERTY_DVDKARAOKE;

요소

AM_PROPERTY_DVDKARAOKE_ENABLE
DVD 네비게이터는, 이 프로퍼티를 true 로 설정해 디코더에 보내는 것에 의해 가라오케의 믹스 다운을 유효하게 해,false 로 설정해 보내는 것에 의해 무효로 한다.
AM_PROPERTY_DVDKARAOKE_DATA
DVD 네비게이터는,AM_DvdKaraokeData 구조체에의 포인터가 지정된 AM_PROPERTY_DVDKARAOKE_DATA 프로퍼티를 디코더에 보내, 믹스 다운 구성을 변경한다 (즉, 어느 가라오케 채널의 온/오프를 바꾸어 좌우의 출력 채널에 할당한다).

AM_DvdKaraokeData

DVD 가라오케 프로퍼티 세트

구문

typedef struct tagAM_DvdKaraokeData
{
    DWORD   dwDownmix;
    DWORD   dwSpeakerAssignment;
} AM_DvdKaraokeData;

멤버

dwDownmix
DVD_KARAOKE_DOWNMIX 플래그의 비트화. 채널 0 이나 1 에 믹스 다운하는 채널을 선택한다.
dwSpeakerAssignment
출력처 스피커를 나타내는 유효한 DVD_KARAOKE_ASSIGNMENT 값.

참조

SelectKaraokeAudioPresentationMode


DVD 서브 픽쳐 프로퍼티 세트

DVD 서브 픽쳐 프로퍼티는, 서브 픽쳐 표시의 색, 콘트라스트, 및 출력을 제어한다.

다음의 정보는,IKsPropertySet 메소드의 호출로 이 프로퍼티 세트에 사용하기 위해서 필요한 정수 및 데이터형의 정보를 나타내고 있다. GUID (guidPropSet), 프로퍼티 ID (dwPropID), 및 프로퍼티의 데이터형 (pPropData) 파라미터의 값을 제공한다.

프로퍼티 세트 GUID: AM_KSPROPSETID_DvdSubPic

프로퍼티 ID | 지정된 프로퍼티에 의해 사용되는 데이터형
AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON | AM_PROPERTY_COMPOSIT_ON
AM_PROPERTY_DVDSUBPIC_HLI | AM_PROPERTY_SPHLI
AM_PROPERTY_DVDSUBPIC_PALETTE | AM_PROPERTY_SPPAL

다음의 일람은, 서브 픽쳐 프로퍼티의 ID 와 그 설명이다.

AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON
서브 픽쳐의 표시를 유효 또는 무효(� 설정 전용 프로퍼티. Microsoft® DirectShow® 는, 이 프로퍼티에 대응하는 AM_PROPERTY_COMPOSIT_ON 불형과 이 데이터형에의 포인터인 PAM_PROPERTY_COMPOSIT_ON 를 정의한다. TRUE 는 서브 픽쳐를 표시하는 것을 나타내, FALSE 는 표시하지 않는 것을 나타낸다. 상세한 것에 대하여는, Windows 98 DDK 의 WDM 부분을 참조할것.
AM_PROPERTY_DVDSUBPIC_HLI
색 또는 콘트라스트를 변경하는 서브 픽쳐 또는 화면의 직사각형을 지정하는 설정 전용 프로퍼티. 데이터형은 AM_PROPERTY_SPHLI .

AM_PROPERTY_DVDSUBPIC_HLI 프로퍼티는 설정 전용이다. 이 프로퍼티는, 색 또는 콘트라스트를 변경하는 서브 픽쳐 또는 화면의 직사각형을 지정한다. 여기에서는, 「DVD 비디오의 사양」이라고 달라,Microsoft DVD 네비게이터가 버튼 및 키보드의 정보를 모두 해석해, 강조 표시하는 직사각형을 1 개씩 서브 픽쳐 디코더에 건네준다. 이 결과, 강조 표시 정보가 디코더에 보내지는 회수는, DVD 스트림내에 존재하는 이 정보의 수보다 많아진다.

강조 표시 정보는 데이터 스트림과 비동기에게 도착한다. 디코더는, 강조 표시의 시작과 종료의타임 스탬프를 사용해, 강조 표시 정보와 거기에 관련하는 서브 픽쳐 정보를 대응 붙인다 (존재하는 경우). 요구된 타임 스탬프에 대응하는 서브 픽쳐 스트림 정보가 닿지 않았던 경우, 디코더는, 그 강조 표시 정보를 서브 픽쳐에 관련하지 않는 독립한 정보라고 본다. 이 경우, 색 및 콘트라스트의 정보는, 모두 같은 색으로서 처리된다.

이 데이터는 완전한 DVD 디스크 포맷은 아니다. Microsoft 에서는,AM_PROPERTY_SPHLI 형의 추가의 구조체를 제공한다. 이 구조체는, 이 프로퍼티의 파라미터로서 건네받아 DVD 의 강조 표시 정보로부터 얻을 수 있는 현재 선택되고 있는 버튼을 기술한다.

DVD 네비게이터는, 키스트로크(keystroke) 정보를 모두 처리해, 버튼 상태가 변화할 때마다 새로운 강조 표시 정보를 보낸다. 이 정보는, 1 번에 1 개의 버튼의 1 모드만을 기술한다. 여기에는, 픽셀 좌표로 나타내진 화면의 표시 직사각형, 또는 서브 픽쳐의 표시 (있는 경우)가 포함된다. 구조체에는, 색과 콘트라스트의 정보도 저장 되고 있지만, 이 정보는 현재 선택되고 있는 버튼의 현재 상태에만 대응한다. 포맷은 DVD 의 사양에 정의되고 있다.

강조 표시 정보에는 시작과 종료의 타임 스탬프가 저장 되고 있다. 이러한 단위는 다른 타임 스탬프와 같다. 다만 예외가 2 개만 있다. 0xFFFFFFFF 라고 하는 시작 타임 스탬프는, 강조 표시 프로퍼티가 수취와 동시에 유효하게 되는 것을 의미해, 0xFFFFFFFF 라고 하는 종료 타임 스탬프는, 강조 표시 프로퍼티를 다음에 받을 때까지 유효한 일을 의미한다.

HLISS 필드는, DVD 의 사양에 정의되고 있는 대로이다. 값 0 은, 강조 표시가 모두 무효이며, 디코더로 오프로 하지 않으면 안 되는 것을 나타낸다.

AM_PROPERTY_DVDSUBPIC_PALETTE
서브 픽쳐의 팔레트를 설정한다. 데이터형은 AM_PROPERTY_SPPAL .

IKsPropertySet 인터페이스를 사용해, 이러한 프로퍼티를 지원 하기 위해서 설정, 취득, 및 쿼리를 실시한다.

이 프로퍼티 세트에서는, 다음의 데이터형이 사용된다.

데이터형 | 설명
AM_COLCON | 칼라 콘트라스트를 지정한다. AM_PROPERTY_SPHLI 구조체의 서브 구조체.
AM_DVD_YUV | DVD YUV 서브 픽쳐 데이터를 지정한다. AM_PROPERTY_SPPAL 구조체의 서브 구조체.
AM_PROPERTY_COMPOSIT_ON | AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON 프로퍼티로 사용되는 불리언 값.
AM_PROPERTY_SPHLI | DVD 의 강조 표시 정보로부터 얻을 수 있는 현재 선택되고 있는 버튼을 기술한다.
AM_PROPERTY_SPPAL | DVD 서브 픽쳐의 팔레트를 지정한다.

AM_COLCON

DVD 서브 픽쳐 프로퍼티 세트

DVD 강조 표시 (HLI) 구조체로부터 얻을 수 있는 칼라 콘트라스트의 기술을 나타낸다.

구문

 typedef struct _AM_COLCON {
    UCHAR emph1col:4;
    UCHAR emph2col:4;
    UCHAR backcol:4;
    UCHAR patcol:4;
    UCHAR emph1con:4;
    UCHAR emph2con:4;
    UCHAR backcon:4;
    UCHAR patcon:4;
} AM_COLCON, *PAM_COLCON;

멤버

emph1col
강조색 1.
emph2col
강조색 2.
backcol
배경색.
patcol
패턴색.
emph1con
강조 콘트라스트 1.
emph2con
강조 콘트라스트 2.
backcon
배경 콘트라스트.
patcon
패턴 콘트라스트.

주의

이 구조체는 AM_PROPERTY_SPHLI 구조체에 포함된다.

AM_DVD_YUV

DVD 서브 픽쳐 프로퍼티 세트

DVD YUV 서브 픽쳐 데이터.

구문

 typedef struct _AM_DVD_YUV {
    UCHAR   Reserved;
    UCHAR   Y;
    UCHAR   U;
    UCHAR   V;
} AM_DVD_YUV, *PAM_DVD_YUV;

멤버

Reserved
예약이 끝난 상태.
Y
Y 의 색데이터.
U
U 의 색데이터.
V
V 의 색데이터.

주의

이 구조체는 AM_PROPERTY_SPPAL 구조체에 포함된다.

AM_PROPERTY_SPHLI

DVD 서브 픽쳐 프로퍼티 세트

DVD 의 강조 표시 정보로부터 얻을 수 있는 현재 선택되고 있는 버튼을 기술한다.

구문

 typedef struct _AM_PROPERTY_SPHLI {
    USHORT  HLISS;
    USHORT  Reserved;
    ULONG   StartPTM;
    ULONG   EndPTM;
    USHORT  StartX;
    USHORT  StartY;
    USHORT  StopX;
    USHORT  StopY;
    AM_COLCON  ColCon;
} AM_PROPERTY_SPHLI, *PAM_PROPERTY_SPHLI;

멤버

HLISS
현재 선택되고 있는 버튼의 강조 표시 상태.
Reserved
내부에서 사용하기 위해서 예약이 끝난 상태. 사용 또는 설정하지 않는 것.
StartPTM
시작프레젠테이션 시간을 90,000 으로 나눈 값.
EndPTM
종료 프레젠테이션 시간을 90,000 으로 나눈 값.
StartX
현재 강조 표시되고 있는 버튼의 시작 x 픽셀 좌표.
StartY
현재 강조 표시되고 있는 버튼의 시작 y 픽셀 좌표.
StopX
현재 강조 표시되고 있는 버튼의 종료 x 픽셀 좌표.
StopY
현재 강조 표시되고 있는 버튼의 종료 y 픽셀 좌표.
ColCon
칼라 콘트라스트의 기술. 데이터형은 AM_COLCON .

주의

AM_PROPERTY_DVDSUBPIC_HLI 프로퍼티는 이 구조체를 사용한다.

AM_PROPERTY_SPPAL

DVD 서브 픽쳐 프로퍼티 세트

DVD 서브 픽쳐의 팔레트를 지정한다.

구문

 typedef struct _AM_PROPERTY_SPPAL {
    AM_DVD_YUV sppal[16];
} AM_PROPERTY_SPPAL, *PAM_PROPERTY_SPPAL;

멤버

sppal
YUV 요소 16 개로부터 완성되는 배열. 서브 픽쳐 커멘드 스트림내에서 요구된 4 비트의 색번호에 대응한다. YUV 요소의 데이터형은 AM_DVD_YUV .

주의

AM_PROPERTY_DVDSUBPIC_PALETTE 프로퍼티는 이 구조체를 사용한다.


스탭핑(Stepping)프로퍼티 세트

Microsoft DirectX 8.0

스탭핑(Stepping)리프로퍼티 세트

Microsoft® DirectShow® 하에서 프레임 단위의 시크를 이행 하는 디코더는,AM_KSPROPSETID_FrameStep 프로퍼티 세트를 이행 할 필요가 있다. 이 프로퍼티 세트는,IVideoFrameStep 인터페이스와 함께 사용해, 2 개의 프로퍼티로부터 구성된다. AM_PROPERTY_FRAMESTEP 는, 스탭핑(Stepping)커멘드와 스탭핑(Stepping)능력 정보를 건네주기 위해서(때문에) 사용한다. AM_FRAMESTEP_STEP 는, 스탭핑(Stepping)하는 프레임수를 지정하기 위해서 사용한다.

구문

typedef enum {
        AM_PROPERTY_FRAMESTEP_STEP   = 0x01,
        AM_PROPERTY_FRAMESTEP_CANCEL = 0x02,
        AM_PROPERTY_FRAMESTEP_CANSTEP = 0x03,
        AM_PROPERTY_FRAMESTEP_CANSTEPMULTIPLE = 0x04
} AM_PROPERTY_FRAMESTEP;

멤버

AM_PROPERTY_FRAMESTEP_STEP
디코더에 스탭핑(Stepping)조작의 시작을 지시한다.
AM_PROPERTY_FRAMESTEP_CANCEL
디코더에 현재의 스탭핑(Stepping)조작의 취소를 지시한다.
AM_PROPERTY_FRAMESTEP_CANSTEP
디코더에 스탭핑(Stepping)가 실행 가능한가 어떤가를 조회한다. 실행 가능한 경우는 S_OK 를 돌려주어, 그 이외의 경우는 S_FALSE 를 돌려준다.
AM_PROPERTY_FRAMESTEP_CANSTEPMULTIPLE
동시에 복수의 프레임을 스탭핑(Stepping)할 수 있는 제발을 디코더에 조회한다. 실행 가능한 경우는 S_OK 를 돌려주어, 그 이외의 경우는 S_FALSE 를 돌려준다.
typedef struct _AM_FRAMESTEP_STEP
{
    DWORD dwFramesToStep;
} AM_FRAMESTEP_STEP;

AM_FRAMESTEP_STEP 멤버

dwFramesToStep
스탭핑(Stepping)하는 프레임수를 디코더에 알리는 DWORD 값. 1 이상이 아니면 안된다. 1 보다 큰 경우에는, (n - 1) 프레임을 스킵 해, n 번째의 프레임을 표시하는 것을 의미한다.


핀 프로퍼티 세트

핀 프로퍼티 세트를 사용 하면, 핀이 속하는 카테고리를 취득할 수 있다 (있는 경우). 그 카테고리는 필터가 핀을 생성 할 경우에 그 필터에 의해 세트 되는, 카테고리는 어느 타입의 데이터가 핀을 흐르고 있는지를 나타낸다. 가장 자주(잘) 사용되는 카테고리는 캡춰 필터의 캡춰 핀과 프리뷰 핀에 대하는 것이다. [SDK Root]/samples/multimedia/DirectShow/Capture/AMCap 디렉토리의 AMCaps 샘플은, Windows Driver Model (WDM)의 비디오 캡춰 디바이스를 베이스로 한 필터창을을 구축할 경우에 이 프로퍼티 세트를 어떻게 설정하는지를 나타낸다.

다음의 정보는,IKsPropertySet 메소드의 호출로 이 프로퍼티 세트에 사용하기 위해서 필요한 정수 및 데이터형의 정보를 나타내고 있다. GUID (guidPropSet), 프로퍼티 ID (dwPropID), 및 프로퍼티의 데이터형 (pPropData) 파라미터의 값을 제공한다.

프로퍼티 세트 GUID: AMPROPSETID_Pin

이 프로퍼티 세트는,AMPROPERTY_PIN_CATEGORY 핀 카테고리 프로퍼티만으로 구성된다. 이 프로퍼티는 GUID 데이터형을 사용한다. Microsoft® DirectShow® 에서는, SDK 의 인클루드 디렉토리의 Uuids.h 에, 다음의 핀 카테고리가 정의되고 있다.

카테고리 | 설명
PIN_CATEGORY_ANALOGVIDEOIN | 아날로그 신호를 입력해 디지털화하는 캡춰 필터의입력 핀.
PIN_CATEGORY_CAPTURE | 캡춰 핀.
PIN_CATEGORY_CC | Line 21 으로부터의 자막 방송 데이터를 제공하는 핀.
PIN_CATEGORY_EDS | 확장 데이터 서비스 (Line 21, 짝수필드)를 제공하는 핀.
PIN_CATEGORY_NABTS | 북미 비디오 텍스트 규격 데이터를 제공하는 핀.
PIN_CATEGORY_PREVIEW | 프리뷰 핀.
PIN_CATEGORY_STILL | 정지화면을 제공하는 핀.
PIN_CATEGORY_TELETEXT | 문자방송 (자막 방송의 변종)을 제공하는 핀.
PIN_CATEGORY_TIMECODE | 타임 코드 데이터를 제공하는 핀.
PIN_CATEGORY_VBI | 수직 동기 간격 데이터를 제공하는 핀.
PIN_CATEGORY_VIDEOPORT | Video output pin to be connected to input pin zero on the 오버레이 믹서 의 입력 핀 제로에 접속하는 비디오 출력 핀.
PIN_CATEGORY_VIDEOPORT_VBI | VBISurf 에 접속되는 핀, 비디오 포토가 사용되는 경우의 자막 방송 오버레이와 같은 것에 올바른 비디오 메모리를 할당할 필요가 있는 VBI 서페이스아로케이타피르타. PCI, IEEE 1394, USB 시나리오는 이 필터를 사용하지 않는다. 상세한 것에 대하여는, 「Microsoft TV 테크놀러지」를 참조할것.

IKsPropertySet 인터페이스를 사용해, 이러한 프로퍼티를 지원 하기 위해서 설정, 취득, 및 쿼리를 실시한다.


DirectShow 의 컴퍼넌트

이 주제에서는, Microsoft® DirectShow® 에 포함되는, 필터 이외의 COM 컴퍼넌트를 소개한다. DirectShow 에 포함되는 필터의 일람에 대해서는, 「필터」를 참조할것.

컴퍼넌트 | 설명
캡춰 그래프 빌더 | 비디오 캡춰 그래프를 생성 한다.
DVD 그래프 빌더 | DVD 재생 그래프를 생성 한다.
필터 그래프 매니저 | 필터 그래프를 생성 및 제어한다.
필터 맵퍼 | 등록되어 있는 필터를 레지스트리내에서 검색한다.
미디어 프로퍼티 가방 | AVI 파일의 INFO 및 DISP 체크를 설정 또는 취득한다.
메모리 allocater | 미디어 샘플의 버퍼를 할당한다.
SeekingPassThru | 1 개의 입력 핀을 가지는 필터의 시크를 이행 하는 헬퍼 오브젝트.
시스템 기준 클락 | 기준 클락을 이행 한다.
시스템 디바이스 열거자 | 시스템에 인스톨 되고 있는 필터 및 하드웨어 디바이스를 열거한다.

캡춰 그래프 빌더

비디오 캡춰 그래프를 생성 한다. 비디오 캡춰 또는 편집 어플리케이션은, 이 컴퍼넌트를 사용해 필터 그래프를 생성 할 수가 있다.

클래스 식별자 | CLSID_CaptureGraphBuilder2
인터페이스 | ICaptureGraphBuilder2
참조 | 비디오 캡춰,DirectShow 편집 서비스

DVD 그래프 빌더

DVD 재생 그래프를 생성 한다. 어플리케이션은, 이 컴퍼넌트를 사용해 DVD 재생 및 조작의 필터 그래프를 생성 할 수가 있다.

클래스 식별자 | CLSID_DvdGraphBuilder
인터페이스 | IDvdGraphBuilder
참조 | DVD 어플리케이션

필터 그래프 매니저

필터 그래프를 생성 및 제어한다. 필터 그래프 매니저는, DirectShow 의 중심적 컴퍼넌트이다. 어플리케이션은, 이 컴퍼넌트를 사용해 필터 그래프를 생성 및 제어한다. 또, 필터 그래프 매니저는, 동기화, 이벤트 통지, 및 그 외의 필터 그래프의 측면도 처리한다.

클래스 식별자 | CLSID_FilterGraph
인터페이스 | IAMGraphStreams ,IBasicAudio ,IBasicVideo ,IBasicVideo2 ,IFilterChain ,IFilterGraph ,IFilterGraph2 ,IFilterMapper2 ,IGraphBuilder ,IGraphConfig ,IGraphVersion ,IMediaControl ,IMediaEvent ,IMediaEventEx ,IMediaEventSink ,IMediaFilter ,IMediaPosition ,IMediaSeeking ,IQueueCommand ,IResourceManager ,IVideoFrameStep ,IVideoWindow

필터 맵퍼

등록되어 있는 필터를 레지스트리내에서 검색한다. 필터 그래프 매니저는, 이 컴퍼넌트를 사용해 필터 그래프를 생성 한다. 어플리케이션은, 이 컴퍼넌트를 사용해 특정의 검색 조건에 일치하는 필터를 검색할 수가 있다.

클래스 식별자 | CLSID_FilterMapper2
인터페이스 | IFilterMapper2
참조 | 디바이스와 필터의 열거

미디어 프로퍼티 가방

AVI 파일의 INFO 및 DISP 체크를 설정 또는 취득한다.

클래스 식별자 | CLSID_MediaPropertyBag
인터페이스 | IMediaPropertyBag
참조 | IPersistMediaPropertyBag

메모리 allocater

미디어 샘플의 버퍼를 할당한다. 필터는, 이 컴퍼넌트를 사용해 공유 메모리 버퍼를 할당한다.

클래스 식별자 | CLSID_MemoryAllocator
인터페이스 | IMemAllocator

SeekingPassThru

1 개의 입력 핀을 가지는 필터의 시크를 이행 하는 헬퍼 오브젝트. 단독 입력 필터는, 이 오브젝트를 사용해 IMediaSeeking 인터페이스 및 IMediaPosition 인터페이스를 이행 한다.

클래스 식별자 | CLSID_SeekingPassThru
인터페이스 | ISeekingPassThru
참조 | CPosPassThru ,CRendererPosPassThru

시스템 기준 클락

기준 클락을 이행 한다. 그래프내의 어느 필터도 클락을 제공하지 않는 경우는, 필터 그래프 매니저는 이 컴퍼넌트를 사용해 그래프를 동기화한다.

클래스 식별자 | CLSID_SystemClock
인터페이스 | IAMClockAdjust ,IReferenceClock
참조 | DirectShow 의 타임과 클락

시스템 디바이스 열거자

시스템에 인스톨 되고 있는 필터 및 하드웨어 디바이스를 열거한다. 어플리케이션은, 이 컴퍼넌트를 사용해 임의의 카테고리의 필터 및 디바이스를 검색할 수가 있다.

클래스 식별자 | CLSID_SystemDeviceEnum
인터페이스 | ICreateDevEnum
참조 | 필터 카테고리,디바이스와 필터의 열거


DirectShow base class

Microsoft® DirectShow® base class는 DirectShow 필터를 이행 하기 위해서 설계된 C++ 클래스와 유틸리티 함수세트이다. 어플리케이션 개발자에게는, 몇개의 헬퍼 함수도 유용하다.

  • DirectShow base class의 사용법
  • base class 레퍼런스
  • 유틸리티 함수
  • 디버그 유틸리티


DirectShow base class의 사용법

Microsoft® DirectShow® 의 base class를 사용하려면 , 이하의 디렉토리에 있는 base class 라이브러리를 빌드, 링크해야 한다 :

(SDK root)\Samples\Multimedia\DirectShow\BaseClasses

주 SDK 의 이전의 버젼에서는 바이노리필드로서 라이브러리가 포함되어 있었다. Microsoft® DirectX® 8.0 에서는, base class를 사용하려고 한다면, 이 라이브러리를 자신으로 빌드 해야 한다.

base class의 프로젝트 워크 스페이스는 BaseClasses.dsw 와 이름 붙여지고 있다. 이 프로젝트는 2 개의 버젼의 라이브러리를 빌드 하는, 리테일 버젼 Strmbase.lib 과 디버그 버젼 Strmbasd.lib 이다. 자신의 프로젝트내에서, 헤더 파일 Streams.h 를 인클루드 하는 것. 리테일 빌드나 디버그 빌드화에 의해, 프로젝트에 Strmbase.lib 나 Strmbsd.lib 를 링크하는 것. 디버그 빌드에서는, 헤더 파일을 인클루드 하기 전에 프리프로세서 심볼 DEBUG 를 정의하는 것.

다음의 표는 필요한 파일을 요약한다.

워크 스페이스 | BaseClasses.dsw
리테일 라이브러리 | Strmbase.lib
디버그 라이브러리 | Strmbasd.lib
헤더 파일 | Streams.h

빌드 환경의 셋업의 상세한 것에 대하여는, 「빌드 환경의 설정」을 참조할것.

프리프로세서 심볼

헤더 파일 Streams.h 를 인클루드 하면 와, 다음의 프리프로세서 심볼이 특수한 의미를 가진다 :

  • DEBUG: 디버그 빌드. 이 프리프로세서 심볼을 사용하면(자), 많은 디버그 유틸리티가 사용 가능하게 된다. 상세한 것에 대하여는, 「디버그 유틸리티」를 참조할것.
  • PERF: 예약되고 있다. 이 프리프로세서 심볼을 이용해서는 안된다.
  • VFWROBUST: 포인터 유효성 평가를 가능하게 한다. 상세한 것에 대하여는, 「포인터 유효 매크로」를 참조할것. DEBUG 가 정의되고 있다면, VFWROBUST 를 정의할 필요는 없다.


base class 레퍼런스

여기에는 Microsoft® DirectShow® 의 모든 C++ 클래스, 데이터 멤버, 및 함수의 레퍼런스가 포함된다.

  • 필터 base class에 대해
클래스 | 설명
CAggDirectDraw | IDirectDraw 인터페이스를 집성 한다.
CAggDrawSurface | IDirectDrawSurface 인터페이스를 집성 한다.
CAMEvent | 수동 리셋 및 자동 리셋 이벤트의 래퍼 클래스.
CAMMsgEvent | 메세지 처리를 실시하는 이벤트 오브젝트의 래퍼 클래스.
CAMSchedule | 기준 클락의 스케쥴러.
CAMThread | 워커 thread를 관리하기 위한 base class.
CAutoLock | 블록의 범위의 크리티컬 섹션을 보관 유지한다.
CAutoUsingOutputPin | CDynamicOutputPin 오브젝트에의 액세스를 취득, 해방한다.
CBaseAllocator | allocater의 base class.
CBaseBasicVideo | IBasicVideo 인터페이스의 IDispatch 컴퍼넌트를 처리한다.
CBaseControlVideo | 범용 비디오 윈도우용의 IBasicVideo 인터페이스를 이행 한다.
CBaseControlWindow | IVideoWindow 인터페이스를 이행 한다.
CBaseDispatch | IDispatch 인터페이스를 이행 하는 base class.
CBaseFilter | 필터의 base class.
CBaseInputPin | 입력 핀의 base class.
CBaseList | 속성 리스트의 base class.
CBaseMediaFilter | IMediaFilter 인터페이스를 이행 한다.
CBaseObject | DirectShow 오브젝트를 이행 하는 base class.
CBaseOutputPin | 출력 핀의 base class.
CBasePin | 핀의 base class.
CBasePropertyPage | 프로퍼티 페이지 이행의 base class.
CBaseReferenceClock | 기준 클락을 이행 한다.
CBaseRenderer | 렌더링 필터를 이행 하는 base class.
CBaseStreamControl | IAMStreamControl 인터페이스를 이행 한다.
CBaseVideoRenderer | 비디오 렌더러의 base class.
CBaseVideoWindow | IVideoWindow 인터페이스의 IDispatch 컴퍼넌트를 처리한다.
CBaseWindow | 윈도우를 관리하는 base class.
CBasicAudio | IBasicAudio 인터페이스의 IDispatch 인터페이스 컴퍼넌트를 처리한다.
CCmdQueue | IQueueCommand 인터페이스를 이행 하는 헬퍼 클래스.
CCritSec | thread의 락을 제공한다.
CCrossbar | 크로스바 필터를 조작하는 헬퍼 클래스.
CDeferredCommand | IDeferredCommand 인터페이스의 이행.
CDispParams | DISPPARAMS 구조체의 래퍼 클래스.
CDrawImage | 윈도우 드로잉(Drawing)의 헬퍼 클래스.
CDynamicOutputPin | 동적인 재접속과 포맷 변경을 지원 하는 출력 핀.
CEnumMediaTypes | 우선되는 미디어 타입의 열거자.
CEnumPins | 핀의 열거자.
CFactoryTemplate | 클래스 팩토리의 정보를 제공하는 클래스.
CGenericList | 타입 고유의 리스트를 이행 하는 클래스 템플릿.
CImageAllocator | DIB 섹션의 allocater.
CImageDisplay | 이미지 표시 포맷을 관리하는 헬퍼 클래스.
CImagePalette | 팔레트를 관리하는 헬퍼 클래스.
CImageSample | DIB 섹션을 사용하는 미디어 샘플.
CLoadDirectDraw | Microsoft® DirectDraw® 라이브러리의 로드, 언로드의 헬퍼 클래스.
CMediaControl | IMediaControl 인터페이스의 IDispatch 메소드를 처리한다.
CMediaEvent | IMediaEvent 인터페이스의 IDispatch 메소드를 처리한다.
CMediaPosition | IMediaPosition 인터페이스의 IDispatch 메소드를 처리한다.
CMediaSample | 미디어 샘플.
CMediaType | 미디어 타입을 관리하는 클래스.
CMemAllocator | 메모리 allocater.
CMsg | CMsgThread 오브젝트에 생성 된 관리 리퀘스트의 헬퍼 클래스.
CMsgThread | 동기의 완료로 큐잉 하고 있는 thread에 리퀘스트를 큐에 넣는 워커 thread.
COARefTime | 초와 100 나노초의 사이에 기준 타임의 단위를 변환한다.
COutputQueue | 미디어 샘플을 제공하기 위해(때문에), 큐에 넣는 오브젝트.
CPersistStream | IPersistStream 인터페이스를 이행 하는 base class.
CPosPassThru | 1 개의 입력 핀을 가지는 필터의 시크 커멘드를 처리한다.
CPullPin | IAsyncReader 인터페이스를 지원 하는 출력 핀으로부터 데이터를 꺼내는 헬퍼 클래스.
CQueue | 단순해, 정적으로 사이즈를 할당한 큐를 이행 하는 템플릿.
CRefTime | 기준 타임을 관리하는 헬퍼 클래스.
CRenderedInputPin | 복수 입력 핀을 지원 하는 렌더링 필터의 입력 핀.
CRendererInputPin | CBaseRenderer 클래스의 입력 핀.
CRendererPosPassThru | 렌더링 필터의 시크 커멘드를 처리한다.
CSeekingPassThru | CPosPassThru 오브젝트와 CRendererPosPassThru 오브젝트를 생성 하는, 헬퍼 오브젝트.
CSource | 소스 필터를 이행 하는 base class.
CSourcePosition | IMediaPosition 인터페이스를 이행 하는 추상 클래스. 사용되지 않았다.
CSourceSeeking | 1 개의 출력 핀으로 소스 필터내의 시크를 이행 하는 추상 클래스.
CSourceStream | CSource 클래스의 출력 핀.
CSystemClock | 시스템 클록.
CTransformFilter | 변환 필터를 이행 하는 base class.
CTransformInputPin | CTransformFilter 클래스가 사용하는 입력 핀.
CTransformOutputPin | CTransformFilter 클래스가 사용하는 출력 핀.
CTransInPlaceFilter | 데이터를 카피하지 않는 변환 필터를 이행 하는 클래스.
CTransInPlaceInputPin | CTransInPlaceFilter 클래스의 입력 핀.
CTransInPlaceOutputPin | CTransInPlaceFilter 클래스의 출력 핀.
CUnknown | IUnknown 인터페이스를 이행 한다.
CVideoTransformFilter | 비디오 변환 필터의 base class.
FOURCCMap | GUID 와 FOURCC 간의 변환을 하는 헬퍼 클래스.


필터 base class의 개요

이 주제에서는, Microsoft® DirectShow® 클래스 라이브러리의 개요, base class와 그것이 이행 하는 DirectShow Component Object Model (COM) 인터페이스의 관계, 및 이러한 인터페이스와는 직접 관계가 없는 유틸리티 클래스에 도착해 설명한다. 여기에서는, 각 클래스의 저레벨인 해설이나, 필터를 구축하거나 필터 그래프 매니저를 실행하는 방법등의 특정의 순서에 대한 설명은 실시하지 않는다.

DirectShow C++ 클래스 라이브러리는, 스스로 생성 한 필터에 필요한 인터페이스를 이행 하는 경우에 도움이 된다. 다른 유틸리티 클래스를 사용 하면 크리티컬 섹션이나 thread 관리등의 Microsoft Win32® 의 기능을 짜넣을 수가 있는 한편으로, 대부분의 base class는 인터페이스에 직접 대응한다.

이 주제는, 이하의 섹션을 포함하고 있다.

  • base class
  • 유틸리티 클래스

base class

DirectShow 클래스 라이브러리의 대부분의 base class는 DirectShow COM 인터페이스를 이행 한다. 이러한 클래스는 IUnknown 인터페이스를 제공하는 C++ 오브젝트를 생성하므로, 외부 컴퍼넌트는 그 오브젝트가 지원 하는 인터페이스에 액세스 할 수 있다.

이 섹션에서는, 이하의 항목에 대해 설명한다.

  • CBaseObject 및 CUnknown 클래스
  • 인터페이스를 이행 하는 base class

CBaseObject 및 CUnknown 클래스

CBaseObject 클래스는, 모든 base class의 루트이다. 이 클래스의 주된 목적은, 모든 액티브한 DirectShow 오브젝트의 수를 보관 유지하는 것에 의해 디버그를 지원하는 것이다. 상속 클래스내의 모든 base class constructor　 　 은, 데밧깅오브제크트명을 제 1 파라미터로서 제공하면서 CBaseObject constructor　 　 을 호출한다. 이 base class에 보내진 데밧깅오브제크트명은, 데밧깅모니타상에서 볼 수가 있다.

CUnknown 클래스의 계층

인터페이스를 이행 하는 모든 DirectShow 클래스는,CBaseObject 로부터 파생한 CUnknown 로 불리는 base class로부터 파생한다. CUnknown 는 INonDelegatingUnknown 인터페이스를 이행 한다. 이 인터페이스는 IUnknown 인터페이스와 같게, 인터페이스를 요구하는 메소드나 그 인터페이스에의 참조를 추가 또는 해방하는 메소드를 제공한다.

IUnknown 의 서비스를 이행 하는 인터페이스가 왜 2 개 있는 것일까? 그 이유는,집성 (aggregation) 에 있다. 집성이란, 복수의 오브젝트를 결합해 1 개(살)의 큰 오브젝트로 하는 COM 용어이다. 필터나 핀등의 필터 그래프 오브젝트를 집성 하는 것은 거의 없다. 다만, 장래의 확장성을 확보하거나 필터 그래프 매니저에 의해 집성 되는 오브젝트인 PID 를 이행 하는 목적으로, 그 설계를 거두어 들이는 것은 가능하다. 집성 한 오브젝트에 대해,외부 오브젝트 (다른 오브젝트를 그 중에 포함하고 있는 오브젝트)는,IUnknown 인터페이스를 사용해 오브젝트의 외부와 통신한다. 외부 오브젝트의 IUnknown 인터페이스는, 그 내부 오브젝트의 IUnknown 인터페이스에의 참조를 건네준다. 즉, 어플리케이션이 외부 오브젝트의 IUnknown 인터페이스를 호출해, 그 몇개의 내부 오브젝트에 속하는 인터페이스를 요구 하면, 외부 오브젝트는 내부 오브젝트의 IUnknown 인터페이스를 호출해, 요구된 인터페이스를 취득한다.

내부 오브젝트는 IUnknown 인터페이스를 외부 오브젝트의 IUnknown 에 위임해야 하기 때문에, 내부 오브젝트의 IUnknown 인터페이스를 프라이빗에 (즉 외부 오브젝트의 IUnknown 인터페이스를 경유하지 않고 ) 액세스 해서는 안 된다. 내부 오브젝트의 IUnknown 는, 외부 오브젝트를 개입시킨 통신 전용에 예약되고 있다. 다만, 외부 오브젝트를 경유하지 않고 오브젝트가 다른 오브젝트에 프라이빗에 접속하는 것은 가능하다. 예를 들어 필터의 핀은, 다른 오브젝트의 핀의 인터페이스를 프라이빗에 조회해야 하는 것이 있다.

INonDelegatingUnknown 인터페이스는, 오브젝트가 집성 되고 있는지 어떤지에 관계없이, 인터페이스에의 직접적인 프라이빗 액세스를 제공한다. 직접 액세스는, 핀, allocater, 필터등의 DirectShow 오브젝트간에서의 대부분의 통신에 대해 중요하고, 통신을 실시하는 경우의 디폴트의 방법이다. 실제, base class는, 집성되어 있지 않은 오브젝트 (필터 그래프의 거의 모든 오브젝트)의 IUnknown 인터페이스를 이행 해 비위임 인터페이스를 직접 호출한다.

인터페이스를 이행 하는 base class

DirectShow 클래스 라이브러리에 포함되는 클래스의 대부분은 COM 인터페이스를 이행 해, 다음과 같이 분류된다.

  • 필터 base class는,IBaseFilter 인터페이스를 이행 해,CBaseFilter 및 거기로부터 파생한 클래스를 포함한다.
  • 핑크 라스는,IPin 인터페이스를 이행 해,CBasePin 및 상속 클래스를 포함한다.
  • 열거자 클래스는,CEnumPins 및 CEnumMediaTypes 를 포함한다.
  • 전송 base class는,CMediaSample ,CBaseAllocator ,CMemAllocator , 및 그 상속 클래스를 포함한다. 이러한 클래스는 핀간에 메모리를 공유해, 그 메모리를 사용해 미디어 샘플을 건네준다.
  • 컨트롤 클래스 및 위치 클래스는,CBaseFilter ,CMediaPosition ,CMediaControl ,CBaseMediaFilter ,CSourceSeeking , 및 CBaseStreamControl 를 포함한다.
  • 클락 base class는,CBaseReferenceClock 및 CSystemClock 를 포함한다.

여기에서는, 이하의 항목에 대해 설명한다.

  • 필터 base class
  • 핀 base class
  • 열거자 base class
  • 전송 base class
  • 미디어 컨트롤 및 배치 클래스
  • 클락 base class

필터 base class

DirectShow 의 스트림의 아키텍쳐는, 필터와 핀에 근거하고 있다. 필터는, 필터 그래프 매니저 및 필터의 핀과 통신을 실시한다. 핀은 필터에 접속해, 데이터를 스트림의 하류에 전송 한다.

필터 base class의 계층

CBaseFilter 는, 모든 필터 클래스의 base class이다. 이 클래스는,IBaseFilter 인터페이스를 이행 한다. IBaseFilter 인터페이스가 지정하는 메소드에 의해, 필터 그래프 매니저는 핀의 생성이나 열거, 및 필터 정보의 취득을 실시해, 또, 필터 그래프에 추가된 것을 필터에 통지할 수가 있다. 또,CBaseFilter 는, 필터가 필터 그래프 매니저로부터 실행, 포즈, 및 정지 커멘드를 받기 위한 IMediaFilter 인터페이스 (IBaseFilter 의 파생원)도 이행 한다. 이 base class는, 멤버 함수를 추가해, 핀 카운트의 취득, 개개의 핀에의 포인터의 취득, 및 핀 버젼의 취득을 실시한다.

또,CBaseMediaFilter 클래스는,IMediaFilter 인터페이스도 이행 한다. 다만 IMediaFilter 는 CBaseFilter 에 의해도 이행 되므로, 이 클래스는 PID 를 쓰는 경우를 제외해 거의 사용하지 않는다.

몇개의 클래스는 CBaseFilter 로부터 직접 파생한다. 이러한 클래스의 각각은, 특정의 타입의 필터를 이행하기 위한 base class를 제공한다. 이러한 클래스에는 이하의 클래스가 있다.

  • 소스 필터의 base class인 CSource .
  • 변환 필터의 base class인 CTransformFilter .
  • 렌더러 필터의 base class인 CBaseRenderer .

CSource 필터 클래스는 CSourceStream 핑크 라스와 함께, 소스 필터의 생성을 지원한다. 대부분의 처리는 핑크 라스로 행해져CSource 는 핀 생성 및 삭제 멤버 함수를 추가한다. CSourcePosition 클래스는, 소스 필터를 이행 한다.

CTransformFilter 클래스는, 변환 필터를 이행 한다. 데이터의 카피를 생성 하고 싶은 경우는,CTransformFilter 로부터 변환 클래스를 파생한다. CTransformFilter 으로부터 파생한 CTransInPlaceFilter 클래스를 사용 하면, 데이터의 카피를 생성 하지 않고 그 자리에서 변환이 가능하게 된다. 이러한 변환 필터 클래스는, 같은 이름을 붙일 수 있었던 핑크 라스 (예를 들어 CTransformOutputPin 와 CTransformInputPin )와 함께 동작한다. 핑크 라스의 대부분의 멤버 함수는, 변환 필터 클래스의 멤버 함수를 호출하기 위해서(때문에) 이행 되므로, 보통은 필터 클래스로부터 자신의 필터를 파생시킨 후, 변환 필터를 이행 하는 몇개의 멤버 함수를 오버라이드(override) 하는 것만으로 좋다.

CTransformFilter 는,CBaseFilter 로부터 파생한 클래스에 몇개의 멤버 함수를 추가한다. 그 중에는, 상속 클래스가 오버라이드(override) 해야 하는 순수 가상 멤버 함수가 포함된다. 1 개의 예로서입력 핀이 샘플을 받았을 때에 호출하지 않으면 안 되는 CTransformFilter::Transform 멤버 함수가 있다. 이 멤버 함수는, 변환 기능의 핵부분을 제공한다. 오버라이드(override) 되는 것 외의 멤버 함수에는, 상속 클래스에 고유의 이행 (예를 들어 핀의 미디어 타입의 체크나 적절한 양의 메모리의 할당)도 포함된다. 게다가 몇개의 CTransformFilter 멤버 함수는, 접속 또는 스트리밍 프로세스에 있어서의 각종의 포인트로 불려 간다. 상속 클래스는 이것들을 오버라이드(override) 해, 인터페이스에의 참조의 추가나 해방을 처리한다.

CVideoTransformFilter 클래스는 CTransformFilter 클래스로부터 파생해, 비디오 렌더러가 품질 컨트롤 메세지를 송신했을 때에 프레임을 드롭 하는 것에 의해 렌더링 된 비디오의 품질에 작용하는 필터의 base class로서 사용된다. 이 클래스는, 주로 비데오데콘프렛사에 의해 사용된다.

CBaseRenderer 클래스와 그 상속 클래스인 CBaseVideoRenderer 는, 비디오 렌더링 필터를 이행 하는 베이스 필터 클래스이다. DirectShow 로 사용되는 비디오 렌더링 필터는,CBaseVideoRenderer 로부터 파생한다. 이러한 클래스와 함께 동작하지만 CBaseFilter 로부터 파생하지 않는 렌더러 클래스도 있다. 이러한 클래스에는, 이하의 클래스가 있다.

  • CRendererInputPin
  • CBaseControlVideo 및 그 base class CBaseBasicVideo
  • CBaseControlWindow 및 그 base class CBaseVideoWindow 및 CBaseWindow
  • CAggDirectDraw
  • CAggDrawSurface

다음의 그림은,CBaseFilter 또는 CBasePin 로부터 파생하지 않는, 렌더러를 지원 하는 모든 클래스를 나타내고 있다.

CBaseFilter 또는 CBasePin 으로부터 파생하지 않는, 렌더러를 지원 하는 클래스의 계층

핀 base class

핀의 조작은 필터에 비해 시간이 든다. 핀은, 필터 그래프 매니저가 그것을 다른 필터의 핀에 접속할 수 있도록(듯이), 메소드를 공개해야 한다. 또, 핀은, 어느 미디어 타입을 건네줄까에 임해서, 그리고 미디어 샘플을 전송하기 위한 공유 메모리 allocater를 어느 핀이 제공할까에 임해서, 접속되고 있는 핀 끼리로 조정하기 위해서도 메소드를 공개한다. 출력 핀은, 각각의 미디어 샘플이 접속되고 있는 입력 핀에 건네주는 역할을 가져, 입력 핀은, 그것을 받는 역할을 가진다. 핀은, 인터페이스를 지원 해, 품질 컨트롤 메세지 및 위치 정보가 핀의 사이에 스트림을 개입시켜 건네받도록(듯이) 해야 한다.

다음의 그림은, 핑크 라스를 나타내고 있다. 모든 핑크 라스는,CUnknown 로부터 파생한 base class CBasePin 로부터 파생한다.

핀 base class의 계층

CBasePin 는,IPin 인터페이스를 이행 한다. IPin 인터페이스는, 다른 핀에의 접속, 접속되고 있는 핀으로 사용하는 미디어 타입의 조정, 핀의 내부 접속의 쿼리, 스트림의 액티버티의 핀에의 통지를 행하기 위한 메소드를 지정한다.

IPin 메소드의 이행에 가세해CBasePin 는 IQualityControl 메소드를 이행 해, 필터 그래프를 경유해 핀 끼리로 품질 컨트롤 메세지를 건네줄 수 있도록(듯이) 한다. 품질 컨트롤 메세지를 사용 하면, 예를 들어 렌더러등의 필터는, 샘플 레이트를 조정하기 위해서 다른 필터를 요구할 수 있다. 보통, 품질 컨트롤 메세지는, 렌더러로부터 업 스트림의 소스 필터에게 건네진다. 다만, 비디오 캡춰 필터의 경우에는, 소스 필터 (예를 들어 VTR 리더)는, 품질 컨트롤 메세지를 다운 스트림의 렌더링 필터에 건네주어 레이트를 조정할 수가 있다.

CBasePin 클래스는, 접속 처리, 미디어 타입의 조정, 및 접속 해제 처리를 제공하기 위한 오버라이드(override) 가능한 몇개의 가상 멤버 함수를 제공한다. CBasePin 로부터 파생하는 2 개의 base class는, 이러한 조작이 많은 디폴트 처리를 제공한다.

  • CBaseOutputPin 는 출력 핀을 이행 한다.
  • CBaseInputPin 는 입력 핀을 이행 한다.

CBaseOutputPin 는,CTransformOutputPin 및 CSourceStream 클래스의 base class이다. 같이CBaseInputPin 는,CTransformInputPin 클래스의 base class이다. 이러한 파생 베이스 핑크 라스를 이해하는데 있어서,CBaseOutputPin 및 CBaseInputPin 클래스가 사용하는 기본 모델을 이해하는 것이 중요하다.

2 개의 핀으로 사용되는 접속 및 전송 모델에 대해, 입력 핀은 미디어 샘플을 받을 수가 있도록(듯이) IMemInputPin 인터페이스를 지원 한다. CBaseInputPin 클래스는,IMemInputPin 인터페이스를 이행 한다. 또, 2 개의 핀의 한편은, 핀간에 건네받는 미디어 샘플 오브젝트를 생성하는 IMemAllocator 인터페이스를 포함한 오브젝트인, 공유 메모리 allocater 오브젝트를 제공해야 한다. CBaseInputPin 클래스에 의해 이행 되는 IMemInputPin 메소드는,CMemAllocator 클래스에 의해 이행 되는 이 allocater 오브젝트를 제공한다. 접속되고 있는 출력 핀은, 전용의 allocater를 제공할 수도 있다. 이 경우, 출력 핀은, 어느 allocater를 사용하는지를 입력 핀에 (다른 IMemInputPin 메소드를 개입시켜) 통지해야 한다.

CBaseOutputPin 클래스는 추가의 멤버 함수를 제공해, allocater의 샘플의 사이즈 및 수를 설정해, allocater로부터의 미디어 샘플을 취득해, 그 미디어 샘플이 접속되고 있는 입력 핀에 배송해, 엔드 오브 스트림 메세지 및 플래시의 마지막 메세지를 다운 스트림에 배송한다. 이 클래스는 또, 많은 IPin 메소드도 이행 한다.

CPullPin 는,퍼서 필터의 입력 핀으로 사용되는 클래스이다. 다음의 그림에 나타내도록(듯이), 이 클래스는 CAMThread 클래스로부터 파생한다.

CPullPin 클래스 계층

퍼서 필터는, 비동기 파일 리더 필터를 사용해 디스크로부터 정보를 꺼내거나 URL 모니카 필터를 사용해 인터페이스로부터 정보를 꺼낸다. CPullPin 는, 업 스트림의 소스 리더 필터로 이행 되는 IAsyncReader 인터페이스와 함께 동작한다. CPullPin 는 thread를 시작 해,업 스트림 필터로부터 데이타를 뽑기 시작해, 그 데이터를 다운 스트림에 보낸다. 즉,CPullPin 는, 샘플을 소스로부터 꺼낸 다음에 전용의 IMemInputPin::Receive 메소드를 단지 호출하는 것만으로 좋다 (또는, 동등의 루틴을 어디선가 실행한다).

열거자 base class

열거자란, 요소의 리스트를 더듬는 방법을 제공하는 인터페이스이다. 열거자는 COM 프로그래밍에 대해 사용되어 오브젝트를 열거하는 경우에 DirectShow 모델은 COM 모델의 방법에 따른다. 클래스 라이브러리에서는,IEnumPins 인터페이스를 이행 하는 CEnumPins 와IEnumMediaTypes 인터페이스를 이행 하는 CEnumMediaTypes 의 2 개의 열거자 클래스가 제공되고 있다. 다른 2 개의 DirectShow 열거자 인터페이스인 IEnumFilters 및 IEnumRegFilters 는 필터 그래프 매니저에 의해서만 이행 되므로, base class에 의해 나타내지지 않는다.

열거자 base class의 계층

CEnumPins 클래스는,IBaseFilter::EnumPins 메소드가 불려 가면(자) 열거자를 생성 한다. 이 메소드로부터 돌려주어지는 열거자는,CEnumPins 클래스에 의해 이행 되는 IEnumPins 인터페이스에의 포인터이다. 다음에 CEnumPins 멤버 함수를 호출해, 필터의 각 핀에의 포인터를 취득할 수 있다. 이 처리는, 이 열거 자식이 필터로 CBaseFilter::GetPin 멤버 함수를 호출하는 것에 의해 실현된다. 필터는, base class의 CBaseFilter::GetPin 멤버 함수를 오버라이드(override) 해, 그것이 불려 갈 때 마다 리스트내에서 다음의 핀을 열거자에게 제공해야 한다.

CEnumMediaTypes 클래스는,IPin::EnumMediaTypes 메소드가 불려 가면(자) 열거자를 생성 한다. 핀은, 그것이 지원 하는 미디어 타입의 리스트를 저장 한다. 보통, 미디어 타입의 조정에서는, 접속되고 있는 핀의 EnumMediaTypes 메소드를 한편의 핀이 호출해 열거자를 취득해, 그것을 사용해 미디어 타입을 선택한다. 이러한 열거자 클래스는, 어느쪽이나 COM 프로그래머에게 익숙한 것의 Next,Skip,Reset, 및 Clone 메소드를 지원 한다. 미디어 타입 열거자는, 파생 핑크 라스에 의해 오버라이드(override) 되지 않으면 안 되는 CBasePin::GetMediaType 멤버 함수를 호출해, 그 핀으로 이용 가능한 미디어 타입의 리스트내에서 다음의 미디어 타입을 돌려준다.

열거자는 thread로서 동작해, 핀 미디어 타입 리스트에의 동기 액세스를 가지지 않으면 안 된다. 이 때문에, 열거자를 이행 하는 클래스는, 크리티컬 섹션 관리를 제공하는 CCritSec 클래스를 (복수의 계승을 개입시켜) 계승한다. CCritSec 클래스의 상세한 것에 대하여는, 「Win32 클래스」를 참조할것.

전송 base class

전송 클래스는 핀간에 메모리를 공유해, 그 메모리를 사용해 미디어 샘플을 건네준다. DirectShow 에서는, 로컬 메모리 전송의 이행을 행하기 위한 4 개의 클래스를 제공하고 있다.

  • CBaseAllocator
  • CMemAllocator
  • CMediaSample
  • CImageSample

CBaseAllocator 는, 다음의 그림에 나타내도록(듯이),IMemAllocator 인터페이스를 이행하기 위한 멤버 함수를 제공하는 클래스이다.

전송 base class의 계층

입력 핀의 IMemAllocator 인터페이스는, 할당하는 버퍼의 수 및 사이즈를 설정하기 위한 메소드를 지정해, 그 메모리의 할당과 해방을 실시해,IMediaSample 인터페이스를 포함하고 있는 1 개의 버퍼를 돌려준다. 입력 핀에 접속되고 있는 출력 핀은,IMemAllocator 메소드를 호출한다. CBaseAllocator 는,Commit 및 Decommit 메소드로부터 불려 가는 멤버 함수 Alloc 및 Free 를 제공한다. 상속 클래스는 Alloc 및 Free 멤버 함수를 오버라이드(override) 해, 메모리의 할당 및 해방을 실시하는 전용의 루틴을 제공한다.

CBaseAllocator 는 그 자체로 이행을 거의 실시하지 않기 때문에, 대부분의 핀은,CBaseAllocator 로부터 파생한 CMemAllocator 클래스를 사용한다. CMemAllocator 는,CBaseAllocator::Free 멤버 함수를 오버라이드(override) 해, 시스템 메모리에 근거해 미디어 샘플의 할당을 제공한다. 이 클래스는, allocater가 최종적으로 해방될 때 불려 가는 전용의 멤버 함수인 ReallyFree 를 제공한다.

CMediaSample 는, 미디어 샘플 데이터를 저장 하는 클래스이며, 데이터형이나 시작 및 종료타임 스탬프등의 미디어 샘플의 프로퍼티에 액세스 하는 멤버 함수를 제공한다. 이 클래스는, 메소드의 지정을 제공하는 IMediaSample 인터페이스를 이행 한다. CImageSample 는 CMediaSample 로부터 파생해, 렌더러의 allocater가 사용될 때 비디오 렌더러에 의해 사용된다. CImageSample 는,CMediaSample 인터페이스의 모든 메소드를 사용하는 것 외에DIBSECTION 정보를 설정 및 취득하기 위한 2 개의 메소드를 사용한다. 이것에 의해, 렌더러는, 업 스트림 필터로부터 받은 CMediaSample 포인터를 용이하게 CImageSample 포인터에 캐스트 해, 비디오 프레임의 비트 맵의 핸들을 취득할 수가 있다.

미디어 컨트롤 및 배치 클래스

미디어 컨트롤 인터페이스는, 어플리케이션으로부터 Run,Stop, 또는 Pause 등의 커멘드를 필터 그래프 매니저를 개입시켜 개개의 필터에 건네준다. 필터측에서 봐 필요한 컨트롤 인터페이스는, 이러한 커멘드를 받아들여 이행하기 위한 메소드를 공개하는 IMediaFilter 뿐이다. CBaseFilter 클래스는 이 인터페이스를 이행 한다. 미디어 컨트롤 메소드를 공개하는 것 외의 모든 인터페이스는, 필터 그래프 매니저에 의해 다루어지므로, 이미 이행 되고 있다. CMediaControl 클래스가 존재해,IMediaControl 인터페이스를 이행 했을 경우에서도, 필터 그래프 매니저가 그 기능을 제어하므로, 이 인터페이스는 그다지 사용되지 않는다. 다음의 그림은, 이러한 클래스와 인터페이스의 관계를 나타내고 있다.

미디어 컨트롤 및 배치 base class의 계층

미디어 배치 인터페이스는, 지정된 위치에서 미디어 스트림을 시작 하거나 지정된 기간 스트림을 재생하거나 또는 미디어 스트림의 레이트를 변경한다. IMediaPosition 인터페이스는, 이 기능을 지원 하는 주요한 인터페이스이다. CMediaPosition 클래스는 이 인터페이스를 이행 해,CPosPassThru 및 CSourcePosition 의 2 개의 클래스의 base class로서 기능한다.

보통, 필터 그래프 매니저는, 미디어 스트림을 배치할 경우에 렌더링 필터의 IMediaPosition 인터페이스를 호출한다. 렌더러는, 표시가 예측되는 샘플 타임을 인정해 적절히 배치된 소스 스트림을 제공 가능한 업 스트림의 시크 가능 필터 (예를 들어 원시 파일 필터)에 미디어 배치 데이터를 건네준다. 이 정보를 업 스트림에 건네주기 위해서(때문에)는, 출력 핀은 배치 정보를 받을 수가 없으면 안 된다.

CPosPassThru 클래스는, 필터의 출력 핀의 IMediaPosition 인터페이스 및 IMediaSeeking 인터페이스를 이행 하지만, 다음의 업 스트림 필터의 출력 핀의 대응하는 인터페이스를 호출해 배치 데이터를 건네주는 이외의 처리는 거의 실시하지 않는다. IMediaSeeking 는, 미디어 스트림을 타임 이외의 단위 (예를 들어 MPEG 포맷의 프레임, 샘플, 또는 인덱스 첨부필드)에 시크 가능한 점으로써 IMediaPosition 와는 다르다. 비디오 렌더러에 이행 되는 CRendererPosPassThru 클래스는, 개개의 샘플의 시작 및 종료기준 타임을 설정한다. 따라서, 이 정보에 관해서 언제라도 샘플에 대한 쿼리를 실시할 수가 있다. 이것은 IMediaSeeking 를 사용해 시크를 취급할 때 도움이 되는, 그것은미디어 타임 을 시크 해, 샘플의 기준 타임을 추적하지 않기 때문이다.

그래프내의 모든 필터에 새로운 위치를 연속해 통지하는 이유는, 미디어의 배치에 관계가 있는 필터가 새로운 위치에 대해서 준비할 수 있도록(듯이) 하기 위한(해)이다. 예를 들어 특정의 스트림 스플리터는, 메인 미디어 스트림을 기준으로 한 미디어 위치를 사용해 스트림을 분할하고 있을지도 모른다. 이것이, 필터 그래프 매니저가 단순하게 소스 필터의 IMediaPosition 또는 IMediaSeeking 인터페이스를 직접 호출하지 않는 것의 이유이다.

CSourcePosition 는, 소스 필터가 그 IMediaPosition 인터페이스를 이행 하는 것을 지원하는 클래스이다.

CSourceSeeking 클래스는, 소스 필터가 그 IMediaSeeking 인터페이스를 이행 하는 것을 지원한다. 이 클래스에 의해, 미디어 스트림내의 시작 위치나 정지 위치, 재생 레이트를 변경하는 호출을 소스 필터가 처리하는 것이 가능하게 된다.

CBaseStreamControl 클래스는, 소스 필터가 그 IAMStreamControl 인터페이스를 이행 하는 것을 지원한다. 이 클래스는, 주로 캡춰 필터에 의해 사용된다. 다음의 그림은,CBaseStreamControl 와 그것을 계승한 인터페이스와의 관계를 나타내고 있다.

CBaseStreamControl base class의 계층

클락 base class

DirectShow 에서는, 필터 그래프로 클락을 이행하기 위한 2 개의 클래스로서 CBaseReferenceClock 및 CSystemClock 가 제공된다. 다음의 그림은, 이러한 클래스와 그것이 이행 하는 인터페이스의 관계를 나타내고 있다.

클락 base class의 계층

CBaseReferenceClock 는 IReferenceClock 를 이행 한다. 이것에 의해, 요구되었을 때에 정확한 기준 타임을 돌려주거나 등록된 오브젝트에 특정의 타임이나 시간 간격을이벤트 통지 및 semaphore를 개입시켜아드바이즈 하는 능력이 제공된다.

CSystemClock 는, 타임 정보와 타이밍 신호를 어플리케이션에 제공하는 시스템 클록을 이행 한다. 이 클래스는,CBaseReferenceClock base class를 사용해, 실제의 타임 호출을 오버라이드(override) 하면서 그 기능의 대부분을 제공한다.

유틸리티 클래스

Microsoft® DirectX® SDK 에는, 필수의 Win32 함수, 멀티미디어 데이터 구조체, 및 오브젝트 리스트 및 큐 조작의 대부분을 C++ 클래스에 캡슐화한 것을 제공하는 유틸리티 클래스가 몇개인가 포함되어 있다. 여기에서는, 이러한 클래스에 도착해 간단하게 설명한다.

  • Win32 클래스
  • 리스트 및 큐 클래스
  • 멀티미디어 데이터형 클래스
  • COM 유틸리티 클래스
  • 데밧깅크라스

Win32 클래스

DirectShow 는, Win32 의 thread, 이벤트, 및 크리티컬 섹션을 취급하기 위한 몇개의 클래스를 이행 하고 있다. 이러한 클래스에는, 이하의 클래스가 있다.

  • CAMEvent
  • CCritSec
  • CAutoLock
  • CAMThread
  • CMsgThread
  • CMsg

다음의 그림은, 이러한 클래스를 나타내고 있다.

Win32 유틸리티 클래스의 계층

CAMEvent 는, Win32 이벤트를 C++ 오브젝트로서 취급한다. 이 클래스의 메소드를 사용 하면, 이벤트를 통지제상태로 하거나 미통지 상태에 리셋 할 수 있는 것 외에 이벤트가 통지제가 될 때까지 호출원을 블록 상태로 할 수 있다. 또, 이벤트를 핸들에 캐스트 해 Win32 WaitForMultipleObjects 함수에 건네줄 수도 있다.

CCritSec 는, Win32 크리티컬 섹션을 C++ 오브젝트로서 취급해, 프로세스내 동기화를 제공한다. 이 클래스의 메소드를 사용 하면, 크리티컬 섹션의 생성, 락, 및 락 해제를 실시할 수가 있다.

CAutoLock 는, 크리티컬 섹션 (CCritSec 오브젝트)을 블록 또는 함수의 범위에서 보관 유지한다. 크리티컬 섹션은, constructor　 　 으로 락 되어 소멸자로 락 해제된다.

CAMThread 는, 추상 워커 thread 클래스를 제공해, 생성, 동기화, 다른 워커 thread와의 통신을 가능하게 한다.

CMsgThread 는, 요구를 직접은 아니고 비동기에게 보내는 것이 가능한 워커 thread의 지원을 제공한다. CMsg 오브젝트의 포맷을 가지는 메세지는,CMsgThread 오브젝트에 보낼 수가 있다.

CMsg 는,CMsgThread 오브젝트에게 건네지는 메세지를 포함한 오브젝트를 생성 한다.

리스트 및 큐 클래스

다음의 그림에 나타내도록(듯이), DirectShow 는, 리스트 및 큐를 취급하기 위한 CBaseList ,CGenericList , 및 COutputQueue 클래스를 이행 하고 있다.

리스트 및 큐 유틸리티 클래스의 계층

CBaseList 는,CBaseObject 로부터 파생한 오브젝트에의 형태 없음 포인터의 링크 리스트 데이터 구조체를 나타낸다.

CGenericList 는,CBaseList 멤버 함수를 호출하는 CBaseList 로부터 파생한 템플릿 클래스를 이행 해, 템플릿으로 지정된 타입의 타입 체크를 추가한다.

COutputQueue 는, 필터의 출력 핀으로부터의 미디어 샘플을 큐에 넣는 처리를 지원 한다. 출력 핀은, 접속되고 있는 입력 핀의 메소드를 호출하는 대신에, 이 클래스의 멤버 함수를 호출해 미디어 샘플을 받는다. COutputQueue 클래스가 미디어 샘플을 다운 스트림에 건네주는 처리를 맡는 한편으로, 출력 핀은 블로킹없이 처리를 속행할 수 있다 .

멀티미디어 데이터형 클래스

다음의 그림에 나타내도록(듯이), DirectShow 는,CMediaType ,CRefTime , 및 FOURCCMap 멀티미디어 데이터형 클래스를 이행 하고 있다.

멀티미디어 데이터형 클래스의 계층

CMediaType 는, 미디어 타입 데이터 구조체 및 구조체의 각 멤버에의 액세스를 제공하는 메소드를 포함한 C++ 클래스 오브젝트를 제공한다.

CRefTime 는, 기준 타임에 액세스하기 위한 메소드를 포함한 C++ 클래스 오브젝트, 및 2 개의 CRefTime 오브젝트에 대해서 불 테스트 또는 연산을 행하기 위한 연산자를 제공한다.

FOURCCMap 는, 미디어 타입의 식별과 등록을 실시하기 위해서(때문에) 사용되는 낡은 포맷의 FOURCC 미디어 태그와 DirectShow 로 사용되는 GUID 미디어 서브 타입과의 사이의 변환을 실시한다.

COM 유틸리티 클래스

DirectShow 의 COM 인터페이스 클래스는, 오브젝트 생성과 인터페이스 이행의 2 개로 분류된다. 클래스 팩토리 클래스는, 오브젝트의 생성용으로 제공되어 그 이외의 클래스는, 기존의 COM 인터페이스를 이행 하기 위해서 제공된다.

COM 유틸리티 클래스에는, 이하의 클래스가 있다.

  • CClassFactory
  • CFactoryTemplate
  • CPersistStream
  • CBasePropertyPage

다음의 그림은, COM 클래스와 그것이 이행 하는 인터페이스의 관계를 나타내고 있다.

COM 유틸리티 클래스의 계층

CClassFactory 및 CFactoryTemplate 는, 필터, 핀, 및 그 외의 DirectShow COM 오브젝트의 자동 인스턴스화를 취급하기 위해서(때문에) base class에 의해 이행 된다. 이러한 클래스는, 오브젝트를 생성 하는데 필요한 실제의 COM 요소를 랩핑 해, 오브젝트를 생성 하는데의 기초 부분을 제공한다. CPersistStream 및 CBasePropertyPage 는, COM 지속 스토리지 및 프로퍼티 페이지 인터페이스의 이행에 도움이 된다.

Dllentry.cpp 에 있는 CClassFactory 는 CBaseObject 를 계승한 클래스에서, COM IClassFactory 인터페이스를 이행 한다. 이 인터페이스는,IClassFactory::CreateInstance 를 호출하는 것에 의해 COM 오브젝트를 인스턴스화하는 CoCreateInstance 에 의해 사용된다 (IClassFactory::CreateInstance 는, 상속 클래스의 정적 CreateInstance 멤버 함수를 호출한다).

base class는 CFactoryTemplate 를 사용해, 오브젝트의 CLSID 를 포함한 템플릿과 오브젝트 클래스의 정적 CreateInstance 함수에의 포인터를 CClassFactory 에 제공한다.

CPersistStream 는 COM IPersistStream 를 이행 해, 보존되고 있는 필터 그래프의 필터 프로퍼티의 저장과 취득을 실시한다. 이것에 의해, 저장 되고 있는 필터 그래프는, 정의 끝난 프로퍼티값으로 설정된 필터를 가질 수가 있다. 이 클래스는 또, 스트림내의 데이터의 버젼화를 취급하는 특수한 멤버 함수를 제공한다.

CBasePropertyPage 는, 필터에 관련하는 프로퍼티 페이지의 체제를 제공하는 COM IPropertyPage 인터페이스를 이행 한다.

데밧깅크라스

DirectShow 는, 「데밧깅」레퍼런스 섹션에 설명하도록(듯이), 많은 데밧깅 함수 및 매크로를 제공한다. DirectShow 에는, 데밧깅피르타의 개발에 편리한 3 개의 클래스가 준비되어 있다.

  • CDispBasic
  • CDisp
  • CGuidNameList

다음의 그림은, 이 3 개의 클래스를 나타내고 있다.

데밧깅 유틸리티 클래스의 계층

CDispBasic 는,m_PString 데이터 멤버를 적절한 캐릭터 라인 사이즈로 변환한다.

CDisp 는,CDispBasic 클래스의 m_PString 데이터 멤버를, constructor　 　 의 파라미터로서 사용되는 오브젝트에 관한 적절한 데밧깅 정보를 기술하는 캐릭터 라인으로 설정하는, constructor　 　 을 제공한다. 예를 들어,IPin 포인터를 사용해 생성 되었을 경우,m_PString 는 핀의 이름을 돌려주어, CLSID 를 사용해 생성 되었을 경우,m_PString 는 그것을 나타내는 캐릭터 라인을 돌려준다. 또, 이 클래스는 m_PString 의 값을 돌려주는 LPCTSTR 캐스트 연산자를 제공하므로,LPCTSTR 값으로서 단지 클래스를 캐스트 해, 생성시에 캐릭터 라인을 돌려줄 수가 있다.

CGuidNameList 는, Uuids.h 인클루드 파일내의 GUID (글로벌 유니크 식별자) 명의 배열을 이행 한다. 이것에 의해, 예를 들어 미디어 타입의 GUID 명을 취득할 수가 있다.


CAggDirectDraw 클래스

CAggDirectDraw 클래스의 계층

CAggDirectDraw 클래스는 IDirectDraw 인터페이스를 집성 한다. Microsoft® DirectDraw® 의 인터페이스 (IDirectDraw 및 IDirectDrawSurface)는 본래 집성 할 수가 있지만, 이 기능은 현재 이행되어 있지 않다. Microsoft DirectShow® 의 다양한 파츠는 DirectDraw 인터페이스의 집성을 필요로 한다. 특히, 비디오 렌더러는,IDirectDraw 및 IDirectDrawSurface 를 공개하는 미디어 샘플을 건네준다. 이 클래스 및 CAggDrawSurface 클래스는, DirectDraw 클래스의 메소드를 재공개해, 집성 할 수 있도록(듯이) 한다.

이 클래스의 constructor　 　 이외의 각 멤버 함수,SetDirectDraw 및 NonDelegatingQueryInterface 는, 파라미터를 건네주어 IDirectDraw 인터페이스의 대응하는 메소드를 호출한다.

프로텍트 데이터 멤버

m_pDirectDraw DirectDraw 오브젝트.

멤버 함수

CAggDirectDraw | CAggDirectDraw 오브젝트를 생성 한다.
SetDirectDraw | 이 클래스에 의해 집성 되는 DirectDraw 오브젝트를 설정한다.

오버라이드(override) 가능한 멤버 함수

NonDelegatingQueryInterface 인터페이스를 취득해, 참조 카운트를 인크리먼트(increment) 한다.

이행 되는 IDirectDraw 메소드

이하의 IDirectDraw 메소드가 이행 된다. 상세한 것에 대하여는, DirectDraw 의 문서를 참조할것.

Compact | 비디오 카드 위에의 모든 표면 메모리를 연속 블록으로 이동해, 최대 빈메모리체크를 사용 가능하게 한다.
CreateClipper | DirectDrawClipper 오브젝트를 생성 한다.
CreatePalette | 이 DirectDraw 오브젝트에 대한 DirectDrawPalette 오브젝트를 생성 한다.
CreateSurface | 이 DirectDraw 오브젝트에 대한 DirectDrawSurface 오브젝트를 생성 한다.
DuplicateSurface | DirectDrawSurface 오브젝트를 복제한다.
EnumDisplayModes | 하드웨어가 DirectDraw 오브젝트를 개입시켜 공개하는 디스플레이 모드 가운데, 제공된 표면 기술과 호환성이 있는 모든 디스플레이 모드를 열거한다.
EnumSurfaces | 지정된 검색 기준에 맞는, 기존의 또는 가능한 표면을 모두 열거한다.
FlipToGDISurface | GDI 가 기입하는 표면을프라이머리 표면으로 한다.
GetCaps | 디바이스 드라이버 (하드웨어)나 하드웨어 에뮬레이션 계층 (HEL)의 능력 (나머지의 능력은 아니다)을 저장 한다.
GetDisplayMode | 현재의 디스플레이 모드를 취득한다.
GetFourCCCodes | DirectDraw 오브젝트에 의해 지원 되는 FOURCC 코드를 취득한다.
GetGDISurface | GDI 가 프라이머리 표면으로서 처리하는 표면 메모리를 현재 가리키는 DirectDrawSurface 오브젝트를 취득한다.
GetMonitorFrequency | DirectDraw 오브젝트가 동작하는 모니터의 주파수를 취득한다.
GetScanLine | 모니터상에서 현재 드로잉(Drawing) 되고 있는 주사선을 취득한다.
GetVerticalBlankStatus | 수직 동기 상태를 취득한다.
Initialize | DirectDraw 오브젝트를 초기화한다.
RestoreDisplayMode | 프라이머리 표면의 디스플레이 디바이스 하드웨어의 모드를,CAggDirectDraw::SetDisplayMode 멤버 함수가 불려 가기 전 상태에 리셋 한다.
SetCooperativeLevel | 어플리케이션의 최상정도 동작을 결정한다.
SetDisplayMode | 디스플레이 디바이스 하드웨어의 모드를 설정한다.
WaitForVerticalBlank | 호출원이 수직 동기 간격과 동기 할 수 있도록(듯이) 한다.

CAggDirectDraw::CAggDirectDraw

CAggDirectDraw 클래스

CAggDirectDraw 오브젝트를 생성 한다.

구문

CAggDirectDraw(
TCHAR *pName,
LPUNKNOWN pUnk
    );

파라미터

pName
오브젝트의 이름에의 포인터. 디버그를 위해서(때문에) 사용된다.
pUnk
이 오브젝트의 소유자에게로의 포인터. NULL 이외의 경우,IUnknown 의 호출은 이 오브젝트에 위임된다.

반환값

반환값 없음.

주의

이 멤버 함수는,CUnknown::CUnknown base class constructor　 　 을 호출해,m_pDirectDraw 멤버 변수를 NULL 로 설정한다.

CAggDirectDraw::NonDelegatingQueryInterface

CAggDirectDraw 클래스

인터페이스를 취득해, 참조 카운트를 인크리먼트(increment) 한다.

구문

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 한다. 디폴트에서는,IDirectDraw 에의 참조를 건네주어,CUnknown::NonDelegatingQueryInterface 멤버 함수를 호출해, base class의 인터페이스 참조를 취득한다. 이 클래스를 오버라이드(override) 해, 상속 클래스로 추가된 인터페이스를 돌려준다.

CAggDirectDraw::SetDirectDraw

CAggDirectDraw 클래스

이 클래스에 의해 집성 되는 DirectDraw 오브젝트를 설정한다.

구문

void SetDirectDraw(
LPDIRECTDRAW pDirectDraw
    );

파라미터

pDirectDraw
집성 되는 IDirectDraw 오브젝트에의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는,m_pDirectDraw 데이터 멤버를 pDirectDraw 파라미터로 설정한다.


CAggDrawSurface 클래스

CAggDrawSurface 클래스의 계층

CAggDrawSurface 클래스는 IDirectDrawSurface 인터페이스를 집성 한다. Microsoft® DirectDraw® 의 인터페이스 (IDirectDraw 및 IDirectDrawSurface)는 본래 집성 할 수가 있지만, 이 기능은 현재 이행되어 있지 않다. Microsoft® DirectShow® 의 다양한 파츠는 DirectDraw 인터페이스의 집성을 필요로 한다. 특히, 비디오 렌더러는,IDirectDraw 및 IDirectDrawSurface 를 공개하는 미디어 샘플을 건네준다. 이 클래스 및 CAggDirectDraw 클래스는, DirectDraw 클래스의 메소드를 재공개해, 집성 할 수 있도록(듯이) 한다.

이 클래스의 constructor　 　 이외의 각 멤버 함수,SetDirectDrawSurface 및 NonDelegatingQueryInterface 는, 파라미터를 건네주어 IDirectDrawSurface 인터페이스의 대응하는 메소드를 호출한다.

프로텍트 데이터 멤버

m_pDirectDrawSurface DirectDraw 표면.

멤버 함수

CAggDrawSurface | CAggDrawSurface 오브젝트를 생성 한다.
SetDirectDrawSurface | 이 클래스에 의해 집성 되는 DirectDraw 오브젝트를 설정한다. 이 함수는,IDirectDrawSurface 인터페이스의 메소드를 호출하기 전에 호출하지 않으면 안 된다.

오버라이드(override) 가능한 멤버 함수

NonDelegatingQueryInterface 인터페이스를 취득해, 참조 카운트를 인크리먼트(increment) 한다.

이행 되는 IDirectDrawSurface 메소드

이하의 IDirectDrawSurface 메소드가 이행 된다. 상세한 것에 대하여는, DirectDraw 의 문서를 참조할것.

AddAttachedSurface | 표면을 다른 표면에 어태치 한다. 가능한 어태치의 예로서는, Z 버퍼, 알파 채널, 및 백 버퍼가 있다.
AddOverlayDirtyRect | 다음에 UpdateOverlayDisplay 멤버 함수를 호출했을 때에 갱신해야 하는 직사각형의 리스트를 구축한다.
Blt | 비트 블록 전송을 실행한다.
BltBatch | 복수의 전송원으로부터 단일의 전송 먼저 일련의 CAggDrawSurface::Blt 처리를 실행한다.
BltFast | 전송원 또는 전송처의 칼라 키를 사용해, 전송원카피의 비트 블록 전송 또는 투과형 비트 블록 전송을 실행한다.
DeleteAttachedSurface | 2 개의 표면간의 어태치를 해제한다.
EnumAttachedSurfaces | 주어진 표면에 어태치 되는 모든 표면을 열거한다.
EnumOverlayZOrders | 지정된 전송처의 오버레이를 열거한다. 오버레이는, 프런트로부터 가방, 또는 가방으로부터 프런트의 순서로 열거된다.
Flip | DDSCAPS_BACKBUFFER 표면과 관련지을 수 있었던 표면 메모리를, FRONTBUFFER 표면과 관련짓는다.
GetAttachedSurface | 지정한 능력을 가지는 어태치 된 표면을 취득한다.
GetBltStatus | 비트 블록 전송 상태를 취득한다.
GetCaps | 표면의 능력을 취득한다.
GetClipper | 이 표면에 관련지을 수 있었던 DirectDrawClipper 오브젝트를 취득한다.
GetColorKey | DirectDrawSurface 오브젝트의 칼라 키값을 취득한다.
GetDC | 표면의 GDI 호환 hDC 를 생성 한다.
GetFlipStatus | 호출한 표면으로 후립핑이 종료하고 있는 경우는 OK 를 돌려주어, 그 이외의 경우는 DDERR_WASSTILLDRAWING 를 돌려준다.
GetOverlayPosition | 표시 상태의 액티브한 오버레이 표면 (DDSCAPS_OVERLAY 가 설정되어 있다)이 주어지면(자), 표면의 디스플레이 좌표를 취득한다.
GetPalette | 이 표면에 관련지을 수 있었던 DirectDrawPalette 구조체를 취득한다.
GetPixelFormat | 표면의 칼라와 픽셀 포맷을 취득한다.
GetSurfaceDesc | 현재 상태에 있어서의 표면을 기술하는 DDSURFACEDESC 구조체를 취득한다.
Initialize | DirectDrawSurface 오브젝트를 초기화한다.
IsLost | DirectDrawSurface 오브젝트에 관련지을 수 있었던 표면 메모리가 해방되었는지 어떠했는지를 판단한다.
Lock | 표면 메모리에의 유효한 포인터를 취득한다.
ReleaseDC | CAggDrawSurface::GetDC 에 의해 취득된 GDI 호환 hDC를 해방한다.
Restore | "소실" 한 표면을 restore 한다. DirectDrawSurface 오브젝트에 관련지을 수 있었던 표면 메모리는 해방되고 있다.
SetClipper | DirectDrawClipper 오브젝트를 DirectDrawSurface 오브젝트에 어태치 한다.
SetColorKey | 하드웨어가 표면마다의 칼라 키값을 지원 하고 있는 경우에, DirectDrawSurface 오브젝트의 칼라 키값을 설정한다.
SetOverlayPosition | 오버레이 표면의 디스플레이 좌표를 변경한다.
SetPalette | 지정된 DirectDrawPalette 오브젝트를 DirectDrawSurface 에 어태치 한다.
Unlock | DirectDraw 에 직접 표면 처리가 완료한 것을 통지한다.
UpdateOverlay | 오버레이 표면의 비주얼 속성을 재배치하거나 변경한다. 이러한 표면에는, DDSCAPS_OVERLAY 비트를 설정할 필요가 있다.
UpdateOverlayDisplay | 모든 액티브 오버레이의 더티 직사각형의 리스트에 있는 직사각형을 재드로잉(Drawing) 한다.
UpdateOverlayZOrder | 오버레이의 Z 오더를 설정한다. Z 오더는, 복수의 오버레이를 동시에 표시할 경우에 어느 오버레이가 차단해질까를 결정한다.

CAggDrawSurface::CAggDrawSurface

CAggDrawSurface 클래스

CAggDrawSurface 오브젝트를 생성 한다.

구문

CAggDrawSurface(
  TCHAR *pName,
  LPUNKNOWN pUnk
  );

파라미터

pName
오브젝트의 이름에의 포인터. 디버그를 위해서(때문에) 사용된다.
pUnk
이 오브젝트의 소유자에게로의 포인터. NULL 이외의 경우,IUnknown 인터페이스의 호출은 이 오브젝트에 위임된다.

반환값

반환값 없음.

주의

이 멤버 함수는,CUnknown::CUnknown base class constructor　 　 을 호출해,m_pDirectDrawSurface 멤버 변수를 NULL 로 설정한다.

CAggDrawSurface::NonDelegatingQueryInterface

CAggDrawSurface 클래스

인터페이스를 취득해, 참조 카운트를 인크리먼트(increment) 한다.

구문

HRESULT NonDelegatingQueryInterface(

  REFIID riid,

  void **ppv

  );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 한다. 디폴트에서는,IDirectDrawSurface 에의 참조를 건네주어,CUnknown::NonDelegatingQueryInterface 멤버 함수를 호출해, base class의 인터페이스 참조를 취득한다. 이 클래스를 오버라이드(override) 해, 상속 클래스로 추가된 인터페이스를 돌려준다.

CAggDrawSurface::SetDirectDrawSurface

CAggDrawSurface 클래스

이 집성 오브젝트의 소유자에 의해 불려 가 집성을 하는 실제의 DirectDraw 표면을 설정한다.

구문

void SetDirectDrawSurface(
  LPDIRECTDRAWSURFACE pDirectDrawSurface
  );

파라미터

pDirectDrawSurface
설정되는 IDirectDraw 표면에의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는,IDirectDrawSurface 인터페이스의 메소드를 호출하기 전에 호출하지 않으면 안 된다.


CAMEvent 클래스

CAMEvent 클래스의 계층

수동 및 자동 리셋 이벤트의 래퍼 클래스.

정의: Wxutil.h

이 클래스는 CreateEvent,WaitForSingleObject,ResetEvent 와 같은 Microsoft® Win32® 함수보다 간편한 이벤트 관리 방법을 제공한다.

프로텍트 멤버 변수
m_hEvent | 이벤트 핸들.
Public 메소드
CAMEvent | constructor 메소드.
~CAMEvent | 소멸자 메소드.
Check | 이벤트가 블로킹없이 설정되어 있는지 어떤지를 체크한다.
Reset | 이벤트 상태를 미통지로 설정한다.
Set | 이벤트의 시그널
Wait | 이벤트가 통지제가 되는지, 타임 아웃이 발생할 때까지 블록 한다.
연산자
HANDLE | 이벤트 핸들을 취득한다.

CAMEvent.m_hEvent

CAMEvent 클래스

이벤트 핸들.

구문

HANDLE m_hEvent;

CAMEvent::CAMEvent

CAMEvent 클래스

constructor　 　 메소드.

구문

CAMEvent(
BOOL fManualReset = FALSE
    );

파라미터

fManualReset
오브젝트가 수동 리셋 이벤트 또는 자동 리셋 이벤트의 어디에서 있는지를 지정하는 불형의 값. TRUE 의 경우, 오브젝트는 수동 리셋 이벤트이다. 그 이외의 경우는, 자동 리셋 이벤트이다.

주의

이벤트는 미통지 상태로 시작된다.

자동 리셋 이벤트의 경우,CAMEvent::Wait 메소드는, 메소드가 돌아갈 때 이벤트를 미통지에 리셋 한다. 수동 리셋 이벤트의 경우,CAMEvent::Reset 메소드를 호출할 때까지, 이벤트는 통지제인 채이다.

CAMEvent::~CAMEvent

CAMEvent 클래스

디스트라크타메솟드

구문

~CAMEvent(void);

CAMEvent::Check

CAMEvent 클래스

이벤트가 블로킹없이 설정되어 있는지 어떤지를 체크한다.

구문

BOOL Check(void);

주의

이벤트가 설정되어 있는 경우는 TRUE, 그 이외의 경우는 FALSE 를 돌려준다.

주의

이 메소드는, 타임 아웃에 0 을 지정해 Wait 메소드를 호출한다. 오브젝트가 자동 리셋 이벤트의 경우, 이 메소드는 이벤트를 리셋 한다.

CAMEvent::Reset

CAMEvent 클래스

이벤트 상태를 미통지로 설정한다.

구문

void Reset(void);

CAMEvent::Set

CAMEvent 클래스

이벤트의 시그널.

구문

void Reset(void);

주의

이 행동은 오브젝트가 자동 리셋 이벤트인가, 수동 리셋 이벤트인가에 의존한다 :

  • 자동 리셋 : 임의의 thread가 이 이벤트를 기다리고 있는 경우, 어느 thread가 해방되고 이벤트는 리셋 된다. 이 이벤트를 기다리고 있는 thread가 없는 경우, 이벤트는 통지제인 채 남는다.
  • 수동 리셋 : 이 이벤트대라고 모든 thread가 해방된다. 이벤트는 통지제인 채 남는다.

CAMEvent::Wait

CAMEvent 클래스

이벤트가 통지제가 되는지, 타임 아웃이 발생할 때까지 블록 한다.

구문

BOOL Wait(
DWORD dwTimeout = INFINITE
);

파라미터

dwTimeout
옵션의 타임 아웃값 (밀리 세컨드 단위).

반환값

이벤트가 통지제가 되었을 경우는, TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

주의

자동 리셋 이벤트의 경우, 이 메소드가 돌아가면(자) 이벤트는 미통지 상태에 리셋 된다.

CAMEvent::operator HANDLE

CAMEvent 클래스

이벤트 핸들을 취득한다. 이 연산자는 좌변값은 지원 되지 않는다.

구문

operator HANDLE () const;

반환값

m_hEvent 멤버 변수를 돌려준다.


CAMMsgEvent 클래스

CAMMsgEvent 클래스의 계층

메세지 처리를 실시하는 이벤트 오브젝트의 래퍼 클래스

정의 : Wxutil.h

이 클래스는 CAMEvent 오브젝트로부터 파생하고 있어, 1 개의 메소드 WaitMsg 를 추가한다. 이 메소드는, 대기중에 수신한 메세지를 디스팟치 한다.

Public 메소드
WaitMsg 보내진 메세지를 디스팟치 하면 동시에, 이벤트가 통지제가 되는 것을 기다린다.

CAMMsgEvent::WaitMsg

CAMMsgEvent 클래스

보내진 메세지를 디스팟치 하면 동시에, 이벤트가 통지제가 되는 것을 기다린다, 혹은 지정된 타임 아웃이 일어나는 것을 기다린다.

구문

BOOL WaitMsg(
DWORD dwTimeOut = INFINITE
    );

파라미터

dwTimeOut
옵션의 타임 아웃값 (밀리 세컨드 단위).

반환값

이벤트가 통지제가 되었을 경우는 TRUE, 타임 아웃이 발생했을 경우는 FALSE 를 돌려준다.

주의

이 메소드는 메세지 처리에 PeekMessage 함수를 호출한다. thread가 이벤트를 기다리는 동안에 메세지를 처리할 필요가 있는 경우,CAMEvent::Wait 대신에 이 메소드를 호출한다. thread가 메세지를 처리하지 않고 다른 thread가 메세지를 보냈을 경우, 데드 록이 일어날 가능성이 있다.

예를 들어, thread를 생성 하고 나서 그 thread의 초기화까지 블록 했다고 한다. 그 thread가 SendMessage 함수를 호출해, 윈도우에 메세지를 보내면(자) 데드 록이 된다. 이것은 SendMessage 는 그 메세지가 처리될 때까지 돌아가지 않기 때문이다. WaitMsg 를 사용하면 SendMessage 는 돌아가, 데드 록은 피할 수 있다.


CAMSchedule 클래스

기준 클락의 스케쥴러.

선언: Schedule.h

이 헬퍼 오브젝트는, 기준 클락의 아드바이즈 요구의 리스트를 유지한다. CBaseReferenceClock 클래스는, 이 오브젝트를 사용해 아드바이즈 요구의 스케줄링을 돕는다. 클락은, 이 오브젝트를 다음과 같이 사용한다.

  1. 클락은, 워커 thread를 생성 해 스케줄링을 처리한다.
  2. 워커 thread는 GetEvent 메소드를 호출해, 스케쥴러로부터 이벤트 핸들을 취득한다. thread는, 처음은 무한 타임 아웃을 사용해, 이 이벤트로 대기 상태가 된다.
  3. 새로운 아드바이즈 요구를 스케줄 하기 위한(해), 클락은 AddAdvisePacket 메소드를 호출한다. 아드바이즈 요구는, 단발 또는 주기적인 것으로 할 수가 있다. 스케쥴러는, 시간순서에 요구 리스트를 유지한다.
  4. 리스트의 선두에 요구가 추가되면(자), 스케쥴러는 이벤트를 통지한다. 이 리스트는 처음은 하늘이므로, 최초의 요구가 있으면(자) 이벤트는 확실히 통지된다.
  5. 이벤트가 통지제가 되면(자), 워커 thread는 Advise 메소드를 호출해, 현재의 기준 타임을 지정한다. 보류중의 요구의 유효기간이 끊어지면(자), 스케쥴러는 그러한 요구를 디스팟치 한다.
  6. Advise 메소드는, 다음의 요구의 타임을 돌려준다. 워커 thread는 이 값을 사용해, 새로운 타임 아웃값을 계산한다.
  7. 스텝 2 ~ 6 은, 무한하게 반복해진다.
  8. 워커 thread를 종료하기 위해(때문에), 클락은 내부 플래그를 설정해, 이벤트를 통지한다.

스텝 2 에서는, 이벤트가 통지제가 되는지, 또는 기다리는 타임 아웃이 발생한다. 이벤트가 통지제가 되는 경우는, 새로운 요구가 리스트의 선두에 추가된 것을 의미한다. 워커 thread는 새로운 타임 아웃값을 계산해야 한다. 한편, 기다리는 타임 아웃이 발생하는 경우는, 아드바이즈 요구의 기한 기한이 지나고 있어 디스팟치 되지 않으면 안 되는 것을 의미한다. 어느 경우도, 스텝 5 의 Advise 의 호출에 의해 처리를 한다.

Public 메소드
CAMSchedule | constructor 메소드.
~CAMSchedule | 소멸자 메소드. 가상.
GetAdviseCount | 보류중의 어드바이스 요구수를 취득한다.
GetNextAdviseTime | 다음의 아드바이즈 요구의 타임을 취득한다.
AddAdvisePacket | 보류중의 요구 리스트에 아드바이즈 요구를 추가한다.
Unadvise | 아드바이즈 요구를 삭제한다.
Advise | 특정의 타임 또는 그 이전에 스케줄 된, 모든 요구를 디스팟치 한다.
GetEvent | 이벤트 핸들을 취득한다. 이것은, 다음의 아드바이즈타임의 변경을 통지하기 위해서 사용된다.

CAMSchedule::AddAdvisePacket

CAMSchedule 클래스

새로운 보류중의 통지를 생성 해, 아드바이즈 통지 리스트에 추가한다.

구문

DWORD AddAdvisePacket(
    const REFERENCE_TIME& time1,
    const REFERENCE_TIME& time2,
    HANDLE hNotify,
    BOOL bPeriodic
);

파라미터

time1
아드바이즈의 요구 타임.
time2
주기적인 아드바이즈 요구에서의 통지의 간격. bPeriodic 가 FALSE 의 경우, 이 파라미터는 무시된다.
hNotify
bPeriodic 가 TRUE 의 경우는 semaphore 핸들. bPeriodic 가 FALSE 의 경우는 이벤트 핸들.
bPeriodic
주기적인 통지를 추가하는지, 단발의 통지를 추가하는지를 지정하는 불리언 값. TRUE 의 경우, 통지는 주기적이 된다. time2 파라미터에 의해, 통지의 간격이 지정된다. FALSE 의 경우, 통지는 단발로 발생한다.

반환값

아드바이즈 요구의 식별자 (Cookie)를 돌려준다. 메소드가 실패했을 경우, 반환값은 0 이 된다.

CAMSchedule::Advise

CAMSchedule 클래스

특정의 타임 또는 그 이전에 스케줄 된, 모든 요구를 디스팟치 한다.

구문

REFERENCE_TIME Advise(
    const REFERENCE_TIME& rtTime
);

파라미터

rtTime
현재의 기준 타임을 지정하는 값.

반환값

다음에 스케줄 된 아드바이즈 요구의 기준 타임을 돌려준다. 아드바이즈가 없는 경우는 MAX_TIME 를 돌려준다.

주의

클락이 이 메소드를 호출할 때에, 현재의 기준 타임을 지정한다. 스케쥴러는, 유효기간이 끊어진 아드바이즈를 판정해, 그것들을 디스팟치 한다. 단발 요구의 유효기간이 끊어졌을 경우, 스케쥴러는 그 요구를 삭제한다. 주기적인 요구의 유효기간이 끊어졌을 경우, 스케쥴러는 다음의 아드바이즈타임에 그것들을 재스케줄 한다. 이 메소드는, 보류중의 다음의 요구의 타임을 돌려준다.

아드바이즈 요구를 디스팟치 하기 위한(해), 스케쥴러는,AddAdvisePacket 메소드의 hNotify 파라미터로 지정된 이벤트 또는 semaphore를 통지한다.

CAMSchedule::CAMSchedule

CAMSchedule 클래스

constructor　 　 메소드.

구문

CAMSchedule(
    HANDLE hEvent
);

파라미터

hEvent
자동 리셋 이벤트에의 핸들.

CAMSchedule::~CAMSchedule

CAMSchedule Class

소멸자 메소드.

구문

~CAMSchedule(void);

CAMSchedule::GetAdviseCount

CAMSchedule 클래스

미처리의 어드바이스 요구의 수를 취득한다.

구문

DWORD GetAdviseCount(void);

반환값

미처리의 이벤트의 수를 돌려준다.

CAMSchedule::GetEvent

CAMSchedule 클래스

아드바이즈타임이 재평가를 필요로 하는 경우에, 설정하는 이벤트 핸들을 취득한다.

구문

HANDLE GetEvent(void);

반환값

이 오브젝트의 아드바이즈타임이 재평가를 필요로 하는 경우에, 설정하는 이벤트에의 핸들을 돌려준다.

CAMSchedule::GetNextAdviseTime

CAMSchedule 클래스

다음의 아드바이즈의 타임을 체크한다.

구문

REFERENCE_TIME GetNextAdviseTime(void);

반환값

다음의 아드바이즈가 설정되어 있는 기준 타임을 돌려준다. 이벤트가 스케줄되어 있지 않은 경우는 MAX_TIME 를 돌려준다.

CAMSchedule::Unadvise

CAMSchedule 클래스

아드바이즈리크에스트를 삭제한다.

구문

HRESULT Unadvise(
    DWORD dwAdviseCookie
);

파라미터

dwAdviseCookie
아드바이즈리크에스트의 식별자. 이 값은,AddAdvisePacket 메소드에 의해 돌려주어진다.

반환값

이하의 겉(표)에 있는 HRESULT 값의 1 개를 돌려준다.

S_FALSE | 찾아낼 수 없다
S_OK | 성공


CAMThread 클래스

CAMThread 클래스의 계층

워커 thread를 관리하는 추상 클래스.

선언 : Wxutil.h

이 클래스는 워커 thread의 생성, 그 thread에의 리퀘스트의 송신, 그 thread의 종료의 대기를 제공한다. 이 클래스의 사용 방법은 다음대로 :

  • CAMThread 로부터 클래스를 파생해, 순수한 가상 메소드 ThreadProc 를 오버라이드(override) 한다. 이 메소드는 thread의 시작시에 불려 가는 thread 프로시저이다.
  • 어플리케이션내에서, 상속 클래스의 인스턴스를 생성 한다. thread를 생성 하지 않는 오브젝트를 생성 한다. thread의 생성에는 Create 메소드를 사용한다.
  • thread에 리퀘스트를 보내려면 ,CallWorker 메소드를 호출한다. 이 메소드의 DWORD 파라미터의 의미는 클래스에 의해 정의된다. 이 메소드는 thread가 응답할 때까지 블록 한다(다음을 참조).
  • thread 프로시저로,GetRequest 혹은 CheckRequest 의 어느 쪽인지를 호출하는 것에 의해 응답을 리퀘스트 한다. GetRequest 메소드는 비블로킹으로, 이것에 의해 그 thread는 비동기에게 동작하고 있는 한중간에 새로운 리퀘스트를 체크할 수 있다.
  • thread는 리퀘스트를 받으면(자),Reply 를 호출해 요구 원래의 thread를 비블록으로 한다. Reply 메소드의 DWORD 파라미터는 CallWorker 의 반환값으로서 요구 원래의 thread에게 건네진다.

thread에서의 처리가 종료하면(자),Close 메소드를 호출한다. 이 메소드는 thread의 종료를 대기해, thread 핸들을 닫는다. ThreadProc 메세지는 그것 자신이든,CallWorker 리퀘스트에의 응답이든, 종료를 보증하는 것이 아니면 안된다. 소멸자 메소드도 또 Close 를 호출한다.

다음의 예는 이 스텝을 나타낸다.

class MyThread : public CAMThread
{
protected:
    DWORD ThreadProc(void);
};

DWORD MyThread::ThreadProc()
{
    BOOL bShutDown = FALSE;
    while (! bShutDown)
    {
        DWORD req = GetRequest();
        printf("Request: %d\n", req);
        bShutDown = (req == 0);
        Reply(bShutDown ?  S_FALSE : S_OK);
    }
    printf("Quitting Thread\n");
    return 1;
}

void main()
{
    MyThread thread;
    DWORD reply;

    thread.Create();
    reply = thread.CallWorker(3);
    reply = thread.CallWorker(0); // thread 종료
}

파생한 클래스에서,CallWorker 의 파라미터를 유효하게 하는 멤버 함수를 정의할 수도 있다. 다음의 예는 이것의 일반적인 방법을 나타낸다.

enum Command {CMD_INIT, CMD_RUN, CMD_STOP, CMD_EXIT};

HRESULT Init(void)  { return CallWorker(CMD_INIT); }
HRESULT Run(void)   { return CallWorker(CMD_RUN); }
HRESULT Stop(void)  { return CallWorker(CMD_STOP); }
HRESULT Exit(void)  { return CallWorker(CMD_EXIT); }

CAMThread 클래스는 퍼블릭 멤버 변수로서 2 개의 크리티컬 섹션을 제공한다. m_AccessLock 를 사용해, 다른 thread로부터 액세스 되고 있는 thread를 잠근다. (예를 들어,Create 와 CallWorker 메소드는 이 락을 보관 유지해, thread의 조작을 계속한다. ) m_WorkerLock 를 사용해, thread간에 공유되고 있는 데이터를 잠근다.

Protected 멤버 변수
m_hThread | thread의 핸들.
Public 멤버 함수
m_AccessLock | 다른 thread로부터 액세스 되고 있는 thread를 잠그는 크리티컬 섹션.
m_WorkerLock | thread간에 공유되고 있는 데이터를 잠그는 크리티컬 섹션.
Public 메소드
CAMThread | constructor 메소드.
~CAMThread | 소멸자 메소드. 가상.
InitialThreadProc | thread가 생성 되었을 때 ThreadProc 메소드를 호출한다.
Create | thread의 생성.
CallWorker | thread에 리퀘스트를 통지한다.
Close | thread의 종료를 기다려, 그 리소스를 해방한다.
ThreadExists | thread가 종료했는지 어떠했는지를 조사한다.
GetRequest | 다음의 리퀘스트를 기다린다.
CheckRequest | 리퀘스트가 있으면, 블로킹없이 체크한다.
Reply | 리퀘스트에 응답한다.
GetRequestHandle | CallWorker 메소드로 통지제의 이벤트의 핸들을 취득한다.
GetRequestParam | 최신의 리퀘스트를 취득한다.
CoInitializeHelper | thread의 시작시에 CoInitializeEx 를 호출한다.
순수한 가상 메소드
ThreadProc | thread 프로시저.

CAMThread.m_AccessLock

CAMThread 클래스

다른 thread로부터 액세스 되고 있는 thread를 잠그는 크리티컬 섹션.

구문

CCritSec m_AccessLock;

주의

Create 와 CallWorker 메소드는 이 락을 보관 유지해, thread의 조작을 계속한다.

CAMThread.m_WorkerLock

CAMThread 클래스

thread간에 공유되고 있는 데이터를 잠그는 크리티컬 섹션

구문

CCritSec m_WorkerLock;

CAMThread.m_hThread

CAMThread 클래스

thread의 핸들

구문

HANDLE m_hThread;

주의

이 변수는 NULL 로 초기화된다. Create 메소드는 이 변수를 thread 핸들로 설정한다. thread가 종료했는지 어떠했는지를 지켜보려면 ,ThreadExists 메소드를 호출한다.

CAMThread::CAMThread

CAMThread 클래스

constructor　 　 메소드.

구문

CAMThread(void);

주의

이 constructor　 　 메소드는 thread를 생성 하지 않는다. thread를 생성 하려면 Create 를 호출한다.

CAMThread::~CAMThread

CAMThread 클래스

소멸자 메소드

구문

virtual ~CAMThread(void);

주의

이 소멸자 메소드는 Close 메소드를 호출하는, 이 메소드는 thread의 종료를 기다린다.

CAMThread::CallWorker

CAMThread 클래스

thread에 리퀘스트를 통지한다.

구문

DWORD CallWorker(
    DWORD dwParam
);

파라미터

dwParam
리퀘스트 파라미터. 이 상속 클래스는 파라미터의 의미를 정의한다.

반환값

상속 클래스가 정의한 값을 돌려준다.

주의

GetRequest 와 CheckRequest 메소드는 dwParam 파라미터의 값을 취득한다. GetRequest 메소드는 CallWorker 가 불려 갈 때까지 블록 한다.

이 메소드는 Reply 메소드가 불려 갈 때까지 블록 한다. 반환값은 Reply 에 의해 주어진 파라미터.

이 메소드는 m_AccessLock 락을 hold 해, 리퀘스트를 계속한다. 따라서, thread로부터 혹은 thread의 콘텍스트를 실행하는 멤버 함수로부터 이 메소드를 호출한다.

CAMThread::CheckRequest

CAMThread 클래스

리퀘스트가 있으면, 블로킹없이 체크한다.

구문

BOOL CheckRequest(
    DWORD *pParam
);

파라미터

pParam
CallWorker 메소드의 마지막 호출에 통한 값을 받는 변수의 포인터.

반환값

미처리의 리퀘스트가 있으면 TRUE 를, 그 이외라면 FALSE 를 돌려준다.

주의

이 메소드는 GetRequest 의 비블로킹판이다.

다른 thread가 CallWorker 의 호출을 기다리고 있다면, 이 메소드는 리퀘스트 파라미터를 취득해, TRUE 를 돌려준다. 그 이외의 경우, FALSE 를 돌려준다. 이 메소드가 TRUE 를 돌려주면(자),Reply 메소드를 호출해, thread의 리퀘스트를 취득한다.

CAMThread::Close

CAMThread 클래스

thread의 종료를 기다려, 그 리소스를 해방한다.

구문

void Close(void);

반환값

반환값 없음.

주의

이 메소드를 호출하기 전에, thread를 종료할 수 있도록(듯이) 해야 한다. 예를 들어 ThreadProc 메소드를 사용해, thread에 대해서 종료를 통지하는 리퀘스트를 정의한다. 다음에 CAMThread::CallWorker 메소드를 그 값으로 호출한다.

The ~CAMThread 소멸자 메소드는 이 메소드를 호출한다.

CAMThread::Create

CAMThread 클래스

thread의 생성.

구문

BOOL Create(void);

반환값

성공하면 TRUE 를 돌려주어, 그 이외라면 FALSE 를 돌려준다.

주의

이 메소드는 thread를 생성 하는, 그 때 thread 프로시저로서 InitialThreadProc 메소드를, thread 인수로서 this 를 사용한다.

이 메소드는 thread가 이미 있는 경우 실패한다.

CAMThread::CoInitializeHelper

CAMThread 클래스

thread가 시작 되었을 때 CoInitializeEx 함수를 호출한다.

구문

static HRESULT CoInitializeHelper(void);

반환값

HRESULT 값을 돌려준다. 이하는 그 값이다.

S_FALSE | CoInitializeEx 함수는 유효하지 않다.
S_OK | 성공.
E_FAIL | 실패.

주의

InitialThreadProc 메소드는 CoInitializeEx 함수를 호출하는 이 헬퍼 메소드를 호출한다. COINIT_DISABLE_OLE1DDE 플래그를 사용해, Dynamic Data Exchange (DDE)를 무효로 한다. 상세한 것에 대하여는, Platform SDK 를 참조할것.

CAMThread::GetRequest

CAMThread 클래스

다음의 리퀘스트를 기다린다.

구문

DWORD GetRequest(void);

반환값

상속 클래스가 정의한 값을 돌려준다.

주의

이 메소드는 다른 thread가 CallWorker 메소드를 호출할 때까지 블록 한다. 다음에 CallWorker 에 건네준 파라미터를 돌려준다. Reply 메소드를 호출해 리퀘스트 하고 있는 thread를 해방한다.

CAMThread::GetRequestHandle

CAMThread 클래스

CallWorker 메소드로 통지제의 이벤트의 핸들을 취득한다.

구문

HANDLE GetRequestHandle(void) const;

반환값

이벤트 핸들을 돌려준다.

주의

The CAMEvent 클래스는, 비공개의 수동 리셋 이벤트를 유지한다. 이 이벤트는 CallWorker 에 의해 설정되어Reply 메소드에 의해 리셋 된다.

WaitForMultipleObjects 와 같은 함수를 호출하는 경우,GetRequestHandle 를 사용해 이벤트 핸들을 취득한다.

CAMThread::GetRequestParam

CAMThread 클래스

최신의 리퀘스트를 취득한다.

구문

DWORD GetRequestParam(void) const;

반환값

가장 최근에 CallWorker 메소드에 보내진 파라미터값을 돌려준다.

CAMThread::InitialThreadProc

CAMThread 클래스

thread가 생성 되었을 때,ThreadProc 메소드를 호출한다.

구문

DWORD InitialThreadProc(
    LPVOID pv
);

파라미터

pv
this 포인터.

반환값

CAMThread::ThreadProc 가 돌려준 DWORD 를 돌려준다. 이 값은 상속 클래스가 정의한 것이다.

주의

The Create 메소드는 thread를 생성 할 때, 이 메소드를 thread 프로시저에 사용한다. thread 인수로서 this 포인터를 사용한다.

이 메소드는 CoInitializeHelper 메소드를 호출해, 다음에 ThreadProc 를 호출한다.

CAMThread::Reply

CAMThread 클래스

리퀘스트에 응답한다.

구문

void Reply(
    DWORD dw
);

파라미터

dw
CallWorker 메소드의 반환값.

주의

CallWorker 메소드는 이 메소드가 불려 갈 때까지 블록 한다. dw 파라미터는 CallWorker 의 반환값을 준다. 리퀘스트를 취득한 후에 thread 프로시저로 이 메소드를 호출해, 리퀘스트 하고 있는 thread를 해방한다.

CAMThread::ThreadExists

CAMThread 클래스

thread가 있을지 어떨지 조사한다.

구문

BOOL ThreadExists(void);

반환값

thread가 있는 경우 TRUE 를 돌려주어, thread가 없는 경우 FALSE 를 돌려준다.

CAMThread::ThreadProc

CAMThread 클래스

thread 프로시저.

구문

virtual DWORD ThreadProc(void) = 0;

반환값

Returns a DWORD 값을 돌려주는, 그 의미는 상속 클래스에 의해 정의된다.

주의

이것은 순수한 가상 메소드이다. 이 메소드를 가상 클래스에서 실행해, thread 프로시저에게 준다. Create 메소드가 thread를 생성 하면 와, 순서에 ThreadProc 메소드를 호출하는 InitialThreadProc 메소드의 주소를 준다.

보통 ThreadProc 메소드는(GetRequest 나 CheckRequest 메소드를 호출하는 것으로) 리퀘스트를 취득하는 루프가 되어, 데이터를 처리한다.

이 메소드가 돌아올 때, thread는 종료한다.


CAutoLock 클래스

블록의 범위의 크리티컬 섹션을 보관 유지한다.

선언 : Wxutil.h

이 클래스는, 크리티컬 섹션 오브젝트의 래퍼인 CCritSec 클래스와의 조합해 사용한다. CAutoLock 의 constructor　 　 은 크리티컬 섹션을 잠그어, 소멸자는 락을 해제한다. CAutoLock 오브젝트를 로컬 변수로서 사용해, 모든 코드 패스가 크리티컬 섹션을 락 해제하는 것을 보증하면서, 크리티컬 섹션을 잠글 수가 있다.

다음의 샘플 코드는, 이 클래스의 사용 방법을 나타낸다.

CCritSec csMyLock;  // 크리티컬 섹션은 아직 락되어 있지 않다.

{
CAutoLock cObjectLock(&csMyLock);  // 크리티컬 섹션을 잠근다.

// 코드의 보호된 섹션.

} // 락은 여기서 해제된다.

이 클래스의 메소드는, 오버라이드(override) 되도록(듯이) 설계되어 있지 않다.

프로텍트 멤버 변수
m_pLock | 이 락의 크리티컬 섹션.
Public 메소드
CAutoLock | constructor 메소드. 지정된 크리티컬 섹션 오브젝트를 잠근다.
~CAutoLock | 소멸자 메소드. 크리티컬 섹션 오브젝트의 락을 해제한다.

CAutoLock.m_pLock

CAutoLock 클래스

이 락의 크리티컬 섹션

구문

CCritSec *m_pLock;

CAutoLock::CAutoLock

CAutoLock 클래스

constructor　 　 메소드. 지정된 크리티컬 섹션 오브젝트를 잠근다.

구문

CAutoLock(
CCritSec *plock
);

파라미터

plock
크리티컬 섹션 오브젝트를 포함한 CCritSec 오브젝트에의 포인터.

CAutoLock::~CAutoLock

CAutoLock 클래스

소멸자 메소드. 크리티컬 섹션 오브젝트의 락을 해제한다.

구문

CAutoLock(void);


CAutoUsingOutputPin 클래스

CDynamicOutputPin 오브젝트에의 액세스의 취득과 해방.

선언 : Amfilter.h

어느 메소드가 CDynamicOutputPin 로 불려 갈 때, 호출원래는 핀에의 액세스를 취득해, 다음에 그 액세스를 해방해야 한다. 액세스를 취득하려면 호출원래는 CDynamicOutputPin::StartUsingOutputPin 메소드를 사용한다. 액세스를 해방하려면 CDynamicOutputPin::StopUsingOutputPin 메소드를 호출한다. CAutoUsingOutputPin 클래스는 constructor　 　 과 데콘스트라크타메솟드로 그 태스크를 핸들 하는 헬퍼 클래스이다. 다음의 코드예는 이 클래스의 사용법을 나타낸다.

CDynamicOutputPin *pPin;
HRESULT hr = S_OK;  // 중요! S_OK 로 초기화한다.

// 핀의 포인터를 취득한다 (나타나지 않았다).

{
    CAutoUsingOutputPin UsingPin(pPin, &hr)
    if (SUCCEEDED(hr)) {
        // 핀을 사용할 수 있다.
        pPin->Deliver(pSample);
    }
} // 오브젝트에의 액세스는 여기서 해제한다.

// 핀은 사용할 수 없다.

Public 메소드
CAutoUsingOutputPin | constructor 메소드. 지정한 핀에의 액세스를 취득.
~CAutoUsingOutputPin | 소멸자 메소드. 그 핀에의 액세스를 해방.

CAutoUsingOutputPin

CAutoUsingOutputPin Class

constructor　 　 메소드. 지정한 핀에의 액세스를 취득.

구문

CAutoUsingOutputPin(
    CDynamicOutputPin *pOutputPin,
    HRESULT *phr
);

파라미터

pOutputPin
CDynamicOutputPin 오브젝트에의 포인터
phr
HRESULT 값을 포함한 변수에의 포인터. 그 값은 S_OK 가 아니면 안된다.

주의

메소드가 돌아갔을 때,*phr 의 값은 그 메소드가 성공했는지 실패했는지를 나타낸다.

CAutoLock::~CAutoUsingOutputPin

CAutoUsingOutputPin 클래스

소멸자 메소드. 그 핀에의 액세스를 해방.

구문

~CAutoUsingOutputPin(void);


CBaseAllocator 클래스

CBaseAllocator 클래스의 계층

allocater를 이행 하는 추상 base class. allocater는 IMemAllocator 인터페이스를 공개한다.

선언 : Amfilter.h

allocator 는 메모리 버퍼를 할당하는 오브젝트이다. allocater는 유효한 버퍼의 리스트를 보관 유지한다. 클라이언트(일반적으로는 필터)가 버퍼를 요구 하면, allocater는 그 리스트로부터 1 개를 취득한다. 그 클라이언트는 버퍼를 데이터로 묻어 그 버퍼를 다른 오브젝트에 건네주는 경우도 있다. 최종적으로 그 버퍼는 해방되어 allocater는 프리인 버퍼의 리스트에 그것을 되돌린다.

각 버퍼는 media sample 를 호출하는 오브젝트에 의해 캡슐화된다. 미디어 샘플은 Component Object Model (COM) 체제를 사용해 포인터를 메모리 블록에 패키지 하는 1 개의 방법이다. 미디어 샘플은 IMediaSample 인터페이스를 공개해,CMediaSample 클래스를 사용해 이행 된다. 미디어 샘플은 결합된 버퍼의 포인터를 포함한, 그것은IMediaSample::GetPointer 를 호출하는 것으로 결합되고 있다.

보통, allocater는 연속적인 메모리 블록을 allocate 한다. 다음에 블록내의 주소의 포인터를 포함한 미디어 샘플을 생성 한다. 다음의 그림은 allocater와 미디어 샘플과 메모리 블록의 관계를 나타낸다.

allocater가 샘플을 배달하는 방법

allocater를 사용하려면 , 다음의 스텝을 실행한다.

  1. SetProperties 메소드를 호출해, 버퍼 요구를 지정하는, 이것은 버퍼의 수와 각 버퍼의 사이즈를 포함한다.
  2. Commit 메소드를 호출해, 버퍼를 할당한다.
  3. GetBuffer 메소드를 호출해 미디어 샘플을 취득. 이 메소드는 다음의 샘플이 유효하게 될 때까지 블록 한다.
  4. 각 샘플이 종료하면(자), 샘플에 IUnknown::Release 메소드를 호출한다. 샘플은 그 참조 카운트가 제로가 되어도 삭제되지 않는다. 대신에 샘플은 allocater의 면세표를 돌려준다.
  5. allocater의 사용이 끝나면(자),Decommit 메소드를 호출해, 버퍼의 메모리를 해방한다.

Commit 메소드는 버퍼의 메모리를 할당하는 가상 메소드 Alloc 를 호출한다. Decommit 메소드는 메모리를 해방하는 순수한 가상 메소드 Free 를 호출한다. 상속 클래스는 이 2 개의 메소드를 오버라이드(override) 해야 한다.

CMemAllocator base class는 CBaseAllocator 로부터 파생한다. 필터 base class는 CMemAllocator 클래스를 사용한다.

Protected 멤버 변수
m_lFree | 유효한(프리의) 미디어 샘플의 리스트의 포인터.
m_hSem | 샘플이 유효한 때의 통지제의 semaphore.
m_lWaiting | 샘플을 기다리는 thread의 수.
m_lCount | 제공하는 버퍼의 수.
m_lAllocated | 현재 할당할 수 있고 있는 버퍼의 수.
m_lSize | 각 버퍼의 사이즈.
m_lAlignment | 각 버퍼의 alignment.
m_lPrefix | 각 버퍼의 접두값(prefix)
m_bChanged | 버퍼 요구가 변경되었는지 어떠했는지를 나타내는 플래그.
m_bCommitted | allocater에 위탁되었는지 어떠했는지를 나타내는 플래그.
m_bDecommitInProgress | 위탁되어 있지 않은 조작이 진행중인가 어떤가를 나타내는 플래그.
m_pNotify | 샘플이 해방되었을 때에 불려 가는 콜백 인터페이스의 포인터.
m_fEnableReleaseCallback | 해방 콜백이 유효한가 어떤가를 나타내는 플래그.
Protected 메소드
Alloc | 버퍼의 메모리를 할당한다. 가상.
Public 메소드
CBaseAllocator | constructor 메소드.
~CBaseAllocator | 소멸자 메소드.
SetNotify | 샘플이 해방될 때마다 불려 가는 콜백 메소드를 지정한다.
GetFreeCount | 사용되지 않은 미디어 샘플의 수를 취득.
NotifySample | 샘플을 기다리는 thread를 해방.
SetWaiting | 대기 상태의 thread의 수를 인크리먼트(increment).
Pure Virtual 메소드
Free | 마지막 미디어 샘플이 해방된 후, 데코밋트 조작동안에 버퍼 메모리를 해방한다.
IMemAllocator 메소드
SetProperties | 할당하는 버퍼의 수와 각 버퍼의 사이즈를 지정한다.
GetProperties | allocater가 생성 하는 버퍼의 수와 그 버퍼의 프로퍼티를 취득.
Commit | 버퍼에 메모리를 할당한다.
Decommit | 버퍼를 데코밋트로 한다.
GetBuffer | 버퍼를 포함한 미디어 샘플을 취득.
ReleaseBuffer | 프리 미디어 샘플의 리스트에 미디어 샘플을 돌려준다.

CBaseAllocator.m_lFree

CBaseAllocator 클래스

유효한(프리인) 미디어 샘플 리스트의 포인터.

구문

CSampleList m_lFree;

CBaseAllocator.m_hSem

CBaseAllocator 클래스

샘플이 유효한 때의 통지제의 semaphore.

구문

HANDLE m_hSem;

CBaseAllocator.m_lWaiting

CBaseAllocator 클래스

샘플을 기다리는 thread의 수.

구문

long m_lWaiting

CBaseAllocator.m_lCount

CBaseAllocator 클래스

제공하는 버퍼의 수. SetProperties 메소드는 이 값을 설정한다. 버퍼는 Commit 메소드가 불려 갈 때까지 할당할 수 없다. 현재 할당할 수 있고 있는 버퍼의 수는 m_lAllocated 수치에 의해 지정된다.

구문

long m_lCount;

CBaseAllocator.m_lAllocated

CBaseAllocator 클래스

현재 할당할 수 있고 있는 버퍼의 수.

구문

long m_lAllocated;

CBaseAllocator.m_lSize

CBaseAllocator 클래스

각 버퍼의 사이즈.

구문

long m_lSize;

CBaseAllocator.m_lAlignment

CBaseAllocator 클래스

각 버퍼의 alignment. 각 버퍼의 주소는 복수의 이 값이 아니면 안된다. 접두값(prefix)은 그 alignment 중(안)에서 계산되지 않으면 안 된다. 상세한 것에 대하여는, 「m_lPrefix 」를 참조할것.

구문

long m_lAlignment;

CBaseAllocator.m_lPrefix

CBaseAllocator 클래스

바이트 단위로 가리킨 각 버퍼의 접두값 (prefix). 이 값이 제로가 아닐 때,GetBuffer 메소드에 의해 돌아가는 각 버퍼의 포인터는 사이즈 m_lPrefix 의 복수 바이트의 블록으로 머리에 놓여진다. m_lSize 멤버 변수에는, 접두값은 포함되지 않는다.

구문

long m_lPrefix;

CBaseAllocator.m_bChanged

CBaseAllocator 클래스

버퍼 요구가 변경되었는지 어떠했는지를 나타내는 플래그. SetProperties 메소드는 그 값을 TRUE 로 설정한다. 상속 클래스에서는, 순수한 가상 메소드 Alloc 는 그 값을 FALSE 에 되돌린다. 버퍼를 일단 할당할 수 있으면(자),m_bChanged 가 FALSE 의 사이를 재할인 맞히고 할 필요는 없다.

구문

BOOL m_bChanged;

CBaseAllocator.m_bCommitted

CBaseAllocator 클래스

allocater가 위탁되고 있는지 어떤지를 나타내는 플래그.

구문

BOOL m_bCommitted;

CBaseAllocator.m_bDecommitInProgress

CBaseAllocator 클래스

데코밋트 조작을 하고 있는지 어떤지를 나타내는 플래그. Decommit 메소드가 불려 간 후, 모든 버퍼가 해방되기 전에, 이 값은 TRUE 가 된다. 이 값이 TRUE 라면,GetBuffer 메소드는 실패한다. 또 값이 TRUE 의 사이 allocater는 그것 자신을 삭제해서는 안된다.

구문

BOOL m_bDecommitInProgress;

CBaseAllocator.m_pNotify

CBaseAllocator 클래스

샘플이 해방되었을 때 불려 가는 콜백의 포인터.

구문

IMemAllocatorNotifyCallbackTemp *m_pNotify;

CBaseAllocator.m_fEnableReleaseCallback

CBaseAllocator 클래스

해방 콜백이 유효한가 어떤가를 나타내는 플래그. 이 플래그는 constructor　 　 메소드로 세트 된다. 이 값이 FALSE 때, SetNotify 메소드를 호출하면, (디버그 빌드에서는) assertion to fire 가 된다.

구문

BOOL m_fEnableReleaseCallback;

CBaseAllocator::Alloc

CBaseAllocator 클래스

버퍼의 메모리를 할당한다.

구문

virtual HRESULT Alloc(void);

반환값

다음의 HRESULT 값의 1 개가 돌아간다

S_FALSE | 버퍼 요구는 변경되어 있지 않다.
S_OK | 버퍼 요구는 변경되었다.
VFW_E_SIZENOTSET | 버퍼 요구는 세트되어 있지 않다.

주의

이 메소드는 Commit 메소드에 의해 불려 간다.

base class에서는, 이 메소드는 메모리를 할당하지 않는다. 버퍼 요구가 세트되어 있지 않으면 에러를 돌려주어, 변경되어 있지 않으면 S_FALSE 를 돌려주어, 요구가 변경되고 있으면 S_OK 를 돌려준다.

상속 클래스가 이 메소드를 오버라이드(override) 해 실제의 메모리 할당을 해야 하는 것이다. 보통은 상속 클래스는 다음과 같은 스텝에서 실행한다.

  1. base class의 이행을 호출해, 메모리를 정말로 할당할 필요가 있을지 어떨지를 결정한다.
  2. 메모리를 할당한다.
  3. Create 스텝 2 로부터 메모리의 체크를 포함한 CMediaSample 오브젝트를 생성 한다.
  4. 각 CMediaSample 오브젝트를 프리 샘플 리스트 (m_lFree )에 추가한다.

이 예에 대해서는, 「CMemAllocator::Alloc 」를 참조할것.

CBaseAllocator::CBaseAllocator

CBaseAllocator 클래스

constructor　 　 메소드.

구문

CBaseAllocator(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
    BOOL bEvent = TRUE,
    BOOL fEnableReleaseCallback  = FALSE
);

파라미터

pName
allocater의 이름을 포함한 캐릭터 라인의 포인터.
pUnk
이 오브젝트의 소유자의 포인터. 오브젝트가 집성 되고 있는 경우, 집성 된 오브젝트의 IUnknown 인터페이스의 포인터를 건네준다. 그 이외의 경우는 이 파라미터에는 NULL 를 설정한다.
phr
메소드의 성공이나 실패를 포함한 HRESULT 값을 받는 변수의 포인터.
bEvent
semaphore를 생성 했는지 어떠했는지를 나타내는 불리언 값. TRUE 라면, allocater는 샘플이 유효하게 될 때마다 통지제의 semaphore (m_hSem )를 생성 한다. 이행 하고 있는 상속 클래스가 semaphore를 필요로 하지 않으면, 이 값을 FALSE 로 설정한다.
fEnableReleaseCallback
해방 콜백 메카니즘이 유효한가 어떤가를 나타내는 불리언 값. 버퍼가 해방되었을 때에 불려 가는 콜백 인터페이스를 제공하고 싶으면, 이 값을 TRUE 로 설정한다. SetNotify 메소드의 호출에 의해 콜백을 지정한다.

CBaseAllocator::~CBaseAllocator

CBaseAllocator 클래스

소멸자 메소드

구문

~CBaseAllocator(void);

구문

오브젝트를 소거하기 전에 반드시 Decommit 메소드를 호출하는 것. base class 소멸자는 Decommit 를 호출할 수가 없는, 왜냐하면 그 메소드는 순수 가상 메소드 Free 를 호출하기 때문이다. 상속 클래스는 이 소멸자를 오버라이드(override) 해 Decommit 를 호출한다.

CBaseAllocator::Commit

CBaseAllocator 클래스

버퍼에 메모리를 할당한다. IMemAllocator::Commit 메소드를 이행 한다.

구문

HRESULT Commit(void);

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_SIZENOTSET | 버퍼 요구는 지정되어 있지 않았다.

주의

이 메소드를 호출하기 전에,SetProperties 를 호출해 버퍼 요구를 지정하는 것.

이 메소드는 가상 메소드 Alloc 를 호출해 버퍼에의 메모리의 할당을 실시한다. 상속 클래스는 Alloc 를 오버라이드(override) 할 수가 있다. 데코밋트 조작을 하고 있으면(자), 그것은 캔슬된다.

이 메소드는 GetBuffer 메소드의 전에 불려 가지 않으면 안 된다.

CBaseAllocator::Decommit

CBaseAllocator 클래스

버퍼를 데코밋트로 한다. IMemAllocator::Decommit 메소드를 이행 한다.

구문

HRESULT Decommit(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드를 호출한 다음에,GetBuffer 메소드를 호출하면 실패한다. 샘플은 해방되어, 면세표에 돌아온다. 마지막 샘플이 돌아가면(자), 할당한 메모리를 해방하기 위해(때문에), allocater는 Free 메소드를 호출한다. (base class의 경우,Free 는 순수한 가상 메소드).

더욱, 이 메소드는 GetBuffer 로 블록 된 thread를 해방한다. GetBuffer 를 호출하면 실패한다.

CBaseAllocator::Free

CBaseAllocator 클래스

마지막 미디어 샘플이 해방된 후, 데코밋트 조작중에 버퍼 메모리를 해방한다.

구문

virtual void Free(void) PURE;

주의

Decommit 메소드가 불려 간 다음에, 마지막 미디어 샘플이 해방되었을 때, allocater는 이 메소드를 호출한다. 상속 클래스는 이 메소드를 이행 해야 한다.

CBaseAllocator::GetBuffer

CBaseAllocator 클래스

버퍼를 포함한 미디어 샘플을 취득한다. IMemAllocator::GetBuffer 메소드를 이행 한다.

구문

HRESULT GetBuffer(
    IMediaSample **ppBuffer,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime,
    DWORD dwFlags
);

파라미터

ppBuffer
버퍼의IMediaSample 인터페이스의 포인터를 취득하는 변수의 주소.
pStartTime
샘플의 시작 타임의 포인터.
pEndTime
샘플의 종료 타임의 포인터.
dwFlags
제로 혹은 복수의 플래그의 비트의 편성. base class는 다음의 플래그를 지원 한다.
  • AM_GBF_NOWAIT: 버퍼가 유효하게 되는 것을 기다리지 않는다.

반환값

다음의 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
VFW_E_NOT_COMMITTED | allocater는 위탁은 아니었다.
VFW_E_TIMEOUT | 타임 아웃.

주의

호출원이 dwFlags 로 AM_GBF_NOWAIT 플래그를 지정하지 않아도, 이 메소드는 다음의 샘플이 유효하게 될 때까지 블록 한다.

취득한 미디어 샘플은 할당할 수 있었던 버퍼의 유효한 포인터를 가진다. 호출원래는, 타임 스탬프나 미디어 타임이나 동기 포인트 프로퍼티와 같은, 샘플의 다른 프로퍼티를 설정할 책임을 가진다. 상세한 것에 대하여는, 「IMediaSample 」를 참조할것.

base class에서는,pStartTime 와 pEndTime 파라미터는 무시된다. 상속 클래스는 이러한 값을 사용할 수 있다. 예를 들어,비디오 렌더러 필터의 allocater는 이러한 값을 사용해, Microsoft® DirectDraw® 서페이스간의 변환의 동기를 실시한다.

메소드가 샘플을 기다릴 필요가 있을 때, 대기 오브젝트수 (m_lCount )를 인크리먼트(increment) 해, semaphore (m_hSem )의 WaitForSingleObject 함수를 호출한다. 샘플이 유효하게 되었을 때, allocater의 IBaseAllocator::ReleaseBuffer 메소드를 호출해,m_lCount 에 의해 semaphore 카운트를 인크리먼트(increment) (따라 대기 thread를 해방) 해, m_lCount 를 제로에 되돌린다.

CBaseAllocator::GetFreeCount

CBaseAllocator 클래스

사용되지 않은 미디어 샘플의 수를 취득.

구문

HRESULT GetFreeCount(
    LONG *plBuffersFree
);

파라미터

plBuffersFree
사용되지 않은 샘플의 수를 받는 변수의 주소.

반환값

S_OK 를 돌려준다.

주의

이 값은 면세표 (m_lFree )의 샘플과 삭제되지 않았던 샘플도 포함한다.

CBaseAllocator::GetProperties

CBaseAllocator 클래스

allocater가 생성 한 버퍼의 수와 버퍼 프로퍼티를 취득한다. IMemAllocator::GetProperties 메소드를 이행.

구문

HRESULT GetProperties(
    ALLOCATOR_PROPERTIES *pProps
);

파라미터

pProps
allocater 프로퍼티를 받는 ALLOCATOR_PROPERTIES 구조체의 포인터.

반환값

S_OK 를 돌려준다.

CBaseAllocator::NotifySample

CBaseAllocator 클래스

샘플을 기다리고 있는 thread를 해방한다.

구문

void NotifySample(void);

주의

샘플을 기다리고 있는 thread가 있을 때,m_lWaiting 의 값은 제로보다 크다. m_lWaiting 의 값이 제로보다 크면, 이 메소드는 m_hSem semaphore의 ReleaseSemaphore 함수를 호출해, 기다리고 있는 thread를 액티브하게 한다. 그리고 또 m_lWaiting 를 제로에 리셋 한다.

이 메소드는, 샘플이 면세표에 돌아왔을 때 ReleaseBuffer 메소드로부터 불려 간다. 또 allocater가 데코밋트 때 Decommit 메소드로부터 불려 간다.

CBaseAllocator::ReleaseBuffer

CBaseAllocator 클래스

미디어 샘플을 프리 미디어 샘플의 리스트에 되돌린다. IMemAllocator::ReleaseBuffer 를 이행 한다.

구문

HRESULT ReleaseBuffer(
    IMediaSample *pSample
);

파라미터

pSample
미디어 샘플 오브젝트의 IMediaSample 인터페이스의 포인터.

반환값

S_OK 를 돌려준다.

주의

미디어 샘플의 참조 카운트가 제로가 될 때, 샘플은 ReleaseBuffer 를 자기 자신의 파라미터로서 호출한다. 이 메소드는 다음의 동작을 한다.

  • 미디어 샘플을 면세표 (m_lFree )에 되돌린다.
  • NotifySample 메소드를 호출해, GetBuffer 메소드의 호출로 블록 된 thread를 해방한다.
  • SetNotify 메소드가 이전에 불려 가 아픈들 ,IMemAllocatorNotifyCallbackTemp::NotifyRelease메소드를 호출한다.
  • 마지막 샘플이 해방될 때, 동작중의 Decommit 호출이 있다면,Free 메소드를 호출해, 버퍼 메모리를 해방한다. base class에서는,Free 는 순수한 가상 메소드이다.

CBaseAllocator::SetNotify

CBaseAllocator 클래스

샘플이 해방될 때마다 불려 가는 콜백 메소드를 지정한다.

구문

HRESULT SetNotify(
    IMemAllocatorNotifyCallbackTemp *pNotify
);

파라미터

pNotify
호출 바탕으로 이행 된 IMemAllocatorNotifyCallbackTemp 인터페이스의 포인터.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 m_pNotify 멤버 변수를 pNotify 와 같은 값에 세트 해, 인터페이스의 참조 카운트를 인크리먼트(increment) 한다. m_pNotify 가 NULL 이외라면,ReleaseBuffer 메소드는 IMemAllocatorNotifyCallbackTemp::NotifyRelease 를 호출한다. 이 호출은 임의의 문맥으로 사용되므로,NotifyRelease 메소드를 이행 하면나무는, 호출이 블록 하지 않게 주의할 필요가 있다. 예를 들어, 어느 이벤트의 설정용으로 메소드를 제한 하면인가, 다른 thread에의 메세지의 발송에 제한한다.

CBaseAllocator::SetProperties

CBaseAllocator 클래스

할당할 수 있었던 버퍼의 수와 각 버퍼의 사이즈를 지정. IMemAllocator::SetProperties 메소드를 이행.

구문

HRESULT SetProperties(
    ALLOCATOR_PROPERTIES *pRequest,
    ALLOCATOR_PROPERTIES *pActual
);

파라미터

pRequest
버퍼 요구를 포함한 ALLOCATOR_PROPERTIES 구조체의 포인터.
pActual
실제의 버퍼 프로퍼티를 받는 ALLOCATOR_PROPERTIES 구조체의 포인터.

반환값

이하의HRESULT 의 1 개를 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터값.
VFW_E_ALREADY_COMMITTED | 필터가 액티브한 동안은, 할당한 메모리는 변경할 수 없다.
VFW_E_BADALIGN | 부적절한 alignment가 지정되었다.
VFW_E_BUFFERS_OUTSTANDING | 1 개(살) 혹은 그 이상의 버퍼가 아직 액티브.

주의

이 메소드는 버퍼 요구를 지정하지만, 버퍼를 할당하는 것은 아니다. Commit 메소드를 호출해 버퍼를 할당한다.

호출원래는 2 개의 ALLOCATOR_PROPERTIES 구조체를 할당한다. pRequest 파라미터는 호출해 원의 버퍼의 수와 각 버퍼의 사이즈를 포함한 버퍼 요구를 가진다. 이 메소드가 돌아가면(자),pActual 파라미터는 allocater에 세트 된 실제의 버퍼 프로퍼티를 가진다. 이 메소드는 성공하면(자) 가정되고 있는 base class에서는, 실제의 프로퍼티는 반드시 요구된 프로퍼티와 일치한다. 상속 클래스에서는 이것을 오버라이드(override) 하는 경우도 있다.

allocater는 위탁이어서는 안 되고, 특수한 버퍼여선 안 된다. base class의 경우, alignment는 1이 아니면 안된다. CMemAllocator 클래스는 이 요구를 오버라이드(override) 한다.

CBaseAllocator::SetWaiting

CBaseAllocator 클래스

대기 thread의 수를 인크리먼트(increment) 한다.

구문

void SetWaiting(void);

주의

이 메소드는 m_lWaiting 멤버 변수를 인크리먼트(increment) 한다. thread가 CBaseAllocator::GetBuffer 메소드로 블록 되고 있으면(자), allocater는 SetWaiting 를 호출해, 다음에 m_hSem semaphore가 통지되는 것을 기다린다. ReleaseBuffer 메소드는 semaphore에 통지해,m_lWaiting 를 제로에 되돌린다.


CBaseBasicVideo 클래스

CBaseBasicVideo 클래스의 계층

CBaseBasicVideo 클래스는,IBasicVideo 인터페이스의 IDispatch 컴퍼넌트를 처리해, 프로퍼티 및 메소드는 순수 가상대로 해 둔다.

IDispatch::GetIDsOfNames,IDispatch::GetTypeInfo,IDispatch::GetTypeInfoCount, 및 IDispatch::Invoke 메소드는,IDispatch 인터페이스의 표준적인 이행으로,CBaseDispatch 클래스 ( 및 타입 라이브러리)를 사용해 커멘드를 해석해,IBasicVideo 인터페이스의 순수 가상 메소드에 건네준다.

멤버 함수

CBaseBasicVideo CBaseBasicVideo 오브젝트를 생성 한다.

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingQueryInterface 지정된 참조 카운트의 인터페이스를 돌려준다.

이행 되는 IDispatch 메소드

GetIDsOfNames | 단일의 멤버 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자에 맵 한다. 이 식별자는, 이후의 IDispatch::Invoke 메소드의 호출로 사용할 수 있다.
GetTypeInfo | 타입 정보 오브젝트를 취득한다. 인터페이스의 타입 정보를 취득할 수 있다.
GetTypeInfoCount | 오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.
Invoke | 오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

CBaseBasicVideo::CBaseBasicVideo

CBaseBasicVideo 클래스

CBaseBasicVideo 오브젝트를 생성 한다.

구문

CBaseBasicVideo(

  const TCHAR *pName,

  LPUNKNOWN pUnk

  );

파라미터

pName
디버그를 위해서(때문에) 사용되는 오브젝트의 이름에의 포인터.
pUnk
이 오브젝트의 소유자에게로의 포인터.

반환값

반환값 없음.

주의

스태틱 메모리에 pName 파라미터를 할당한다. 이 이름은, 오브젝트의 생성 및 삭제를 실시하는 데밧깅 단말상에 나타난다.

CBaseBasicVideo::GetIDsOfNames

CBaseBasicVideo 클래스

단일의 멤버 함수 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자에 맵 한다. 이 식별자는, 이후의 CBaseBasicVideo::Invoke 멤버 함수의 호출로 사용할 수 있다.

구문

HRESULT GetIDsOfNames(

  REFIID riid,

  OLECHAR **rgszNames,

  UINT cNames,

  LCID lcid,

  DISPID *rgdispid

  );

파라미터

riid
참조 식별자. 장래적인 사용을 위해서(때문에) 예약되고 있다. NULL 가 아니면 안된다.
rgszNames
건네받은 맵 하는 이름의 배열에의 포인터의 주소.
cNames
맵 되는 이름의 수.
lcid
이름을 해석하는 로케일 문맥.
rgdispid
호출원 할당하고가 끝난 배열에의 포인터. 각 요소에는,rgszNames 배열에게 건네지는 이름의 1 개에 대응하는 ID 가 포함된다. 최초의 요소는 멤버의 이름을 나타내, 이후의 요소는 각 멤버의 파라미터를 나타낸다.

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
DISP_E_UNKNOWNNAME | 1 개(살) 이상의 이름이 불명했다. 돌려주어진 DISPID 에는, 불명한 이름에 대응하는 각 엔트리의 DISPID_UNKNOWN 가 포함된다.
DISP_E_UNKNOWN_CLSID | CLSID 가 인식되지 않았다.

CBaseBasicVideo::GetTypeInfo

CBaseBasicVideo 클래스

타입 정보 오브젝트를 취득한다. 인터페이스의 타입 정보를 취득할 수 있다.

구문

HRESULT GetTypeInfo(

  UINT itinfo,

  LCID lcid,

  ITypeInfo **pptinfo

  );

파라미터

itinfo
돌려주어지는 타입 정보. 제로를 건네주어,IDispatch 이행의 타입 정보를 취득한다.
lcid
타입 정보의 로케일 ID. 로컬라이즈 된 멤버명을 지원 하는 클래스의 경우, 오브젝트는 다른 언어가 다른 타입 정보를 돌려줄 수가 있는 경우가 있다. 로컬라이즈 된 멤버명을 지원 하지 않는 클래스의 경우, 이 파라미터는 무시할 수가 있다.
pptinfo
요구된 타입 정보 오브젝트에의 포인터의 주소.

반환값

pptinfo 가 무효인 경우는, E_POINTER 를 돌려준다. itinfo 가 제로 이외의 경우는, TYPE_E_ELEMENTNOTFOUND 를 돌려준다. 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 타입을 취득하기 위한 호출의 1 개로부터 HRESULT 를 돌려준다. HRESULT 는 에러를 나타내, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.

CBaseBasicVideo::GetTypeInfoCount

CBaseBasicVideo 클래스

오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.

구문

HRESULT GetTypeInfoCount(

  UINT *pctinfo

  );

파라미터

pctinfo
오브젝트가 제공하는 타입 정보 인터페이스의 수를 받는 장소에의 포인터. 오브젝트가 타입 정보를 제공했을 경우, 이 수는 1 이다. 그 이외의 경우는, 0 이다.

반환값

pctinfo 가 무효인 경우는, E_POINTER 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

CBaseBasicVideo::Invoke

CBaseBasicVideo 클래스

오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

구문

HRESULT Invoke(

  DISPID dispidMember,

  REFIID riid,

  LCID lcid,

  WORD wFlags,

  DISPPARAMS *pdispparams,

  VARIANT *pvarResult,

  EXCEPINFO *pexcepinfo,

  UINT *puArgErr

  );

파라미터

dispidMember
멤버의 식별자. 디스팟치 식별자를 취득하려면 ,CBaseBasicVideo::GetIDsOfNames 또는 오브젝트의 문서를 사용한다.
riid
장래적인 사용을 위해서(때문에) 예약되고 있다. IID_NULL 가 아니면 안된다.
lcid
인수를 해석하는 로케일 문맥.
wFlags
CBaseBasicVideo::Invoke 호출의 문맥을 기술하는 플래그.
pdispparams
인수의 배열, 이름 첨부 인수의 인수 디스팟치 ID 의 배열, 및 배열내의 요소의 수를 포함한 구조체에의 포인터.
pvarResult
결과가 저장 되는 포인터, 또는 호출해 원이 결과를 요구하지 않은 경우는 NULL.
pexcepinfo
예외 정보를 포함한 구조체에의 포인터.
puArgErr
rgvarg 배열내에서, 에러가 있는 최초의 인수의 인덱스에의 포인터.

반환값

riid 가 IID_NULL 이외의 경우는, DISP_E_UNKNOWNINTERFACE 를 돌려준다. 호출이 실패했을 경우는,CBaseBasicVideo::GetTypeInfo 로부터 에러 코드의 1 개를 돌려준다. 그 이외의 경우는,IDispatch::Invoke 에의 호출로부터 HRESULT 를 돌려준다.

CBaseBasicVideo::NonDelegatingQueryInterface

CBaseBasicVideo 클래스

지정된 참조 카운트의 인터페이스를 돌려준다.

구문

HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void **ppv
  );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

디폴트에서는,IBasicVideo 및 IUnknown 인터페이스에의 포인터를 돌려준다. 이 메소드를 오버라이드(override) 해, 상속 클래스로 이행 된 추가의 인터페이스를 공개한다.


CBaseControlVideo 클래스

CBaseControlVideo 클래스의 계층

CBaseControlVideo 클래스는,IBasicVideo 듀얼 인터페이스를 이행 해, 범용 비디오 윈도우의 비디오의 프로퍼티를 제어한다. 일반적으로,CBaseControlVideo 오브젝트는, 디스플레이상의 윈도우에 비디오를 드로잉(Drawing) 하는 비디오 렌더러이다.

CBaseControlVideo 클래스는 프로퍼티와 메소드의 양쪽 모두를 지원 한다. 프로퍼티는, 많은 오토메이션 콘트롤러 (Microsoft® Visual Basic® programming environment 등)로부터(분)편이 용이하게 액세스 할 수 있다. 다만, 처리에 따라서는, 어플리케이션으로 복수의 프로퍼티를 동시에 변경할 수 있는 기능이 필요하게 된다. 이 때문에, 복수의 관련하는 프로퍼티를 변경할 수 있는 메소드가 제공되고 있다.

CBaseControlVideo 가 많은 멤버 함수에서는, 비디오 렌더러가 필터 그래프에 접속되고 있을 필요가 있다. 접속되어 있지 않은 경우, 멤버 함수는 VFW_E_NOT_CONNECTED 를 돌려준다. 접속과 절단을 반복해도, 비디오 렌더러로 설정된 프로퍼티는 변화하지 않는다. 모든 어플리케이션으로, 프레젠테이션을 시작 하기 전에 렌더러의 프로퍼티를 리셋 한 것을 확인할 필요가 있다.

비디오를 처리하는 경우, 어플리케이션은 사용하는 비디오의 부분을 선택할 수 있다. 이 부분은,CBaseControlVideo 오브젝트가 제어하는 전송원직사각형이다. CBaseControlVideo 는, 어플리케이션이 전송원직사각형을 설정 및 취득할 수 있도록(듯이) 한다. CBaseControlVideo 가 사용하는 모든 직사각형에서는, Microsoft Win32® 프로그래밍으로 사용되는 상, 좌, 우, 하는 아니고, 상, 좌, 폭, 높이가 사용된다. 전송원직사각형이 설정되어 있지 않은 경우, 전송원직사각형의 프로퍼티는 풀 사이즈의 네이티브 비디오의 사이즈를 돌려준다.

프로텍트 데이터 멤버

m_pFilter | 소유하는 미디어 필터에의 포인터.
m_pInterfaceLock | 외부적으로 정의되는 크리티컬 섹션.
m_pPin | 접속의 미디어 타입의 제어.

멤버 함수

CBaseControlVideo | CBaseControlVideo 오브젝트를 생성 한다.
CopyImage | 비디오 이미지의 메모리 카피를 생성 한다.
GetImageSize | 비디오 이미지의 사이즈 정보를 취득한다.
SetControlVideoPin | 이 오브젝트가 동기 해야 하는 핀을 설정한다.

오버라이드(override) 가능한 멤버 함수

CheckSourceRect | 전송원직사각형이 유효한지 어떤지를 판단한다.
CheckTargetRect | 전송처 직사각형이 유효한지 어떤지를 판단한다.
GetSourceRect | 현재의 비디오의 전송원직사각형을 취득한다 (순수 가상).
GetStaticImage | 메모리 버퍼내의 현재의 이미지를 돌려준다 (순수 가상).
GetTargetRect | 현재의 비디오의 전송처 직사각형을 취득한다 (순수 가상).
GetVideoFormat | 비디오 포맷을 포함한 VIDEOINFOHEADER 구조체를 취득한다.
IsDefaultSourceRect | 렌더러가 디폴트의 전송원직사각형을 사용하고 있을지 어떨지를 판단한다 (순수 가상).
IsDefaultTargetRect | 렌더러가 디폴트의 전송처 직사각형을 사용하고 있을지 어떨지를 판단한다 (순수 가상).
OnUpdateRectangles | 전송원 또는 전송처 직사각형이 변경되면(자) 불려 간다.
OnVideoSizeChange | EC_VIDEO_SIZE_CHANGED 를 어플리케이션에 건네준다.
SetDefaultSourceRect | 디폴트의 비디오의 전송원직사각형을 설정한다 (순수 가상).
SetDefaultTargetRect | 디폴트의 비디오의 전송처 직사각형을 설정한다 (순수 가상).
SetSourceRect | 현재의 비디오의 전송원직사각형을 설정한다 (순수 가상).
SetTargetRect | 현재의 전송처 직사각형을 설정한다 (순수 가상).

이행 되는 IBasicVideo 메소드

get_AvgTimePerFrame | 프레임마다의 대략의 평균 시간을 취득한다.
get_BitErrorRate | 대략의 비트 에러 레이트를 취득한다.
get_BitRate | 비디오의 대략의 bit rate를 취득한다.
GetCurrentImage | 현재의 이미지의 메모리 렌더링을 취득한다.
get_DestinationHeight | 현재의 전송처 직사각형의 높이를 취득한다.
get_DestinationLeft | 현재의 전송처 직사각형의 왼쪽의 좌표를 취득한다.
GetDestinationPosition | 현재의 전송처의 위치를 취득한다.
get_DestinationTop | 현재의 전송처 직사각형의 위에의 좌표를 취득한다.
get_DestinationWidth | 현재의 전송처 직사각형의 폭을 취득한다.
get_SourceHeight | 현재의 전송원직사각형의 높이를 취득한다.
get_SourceLeft | 현재의 전송원직사각형의 왼쪽의 좌표를 취득한다.
GetSourcePosition | 현재의 전송원래의 위치를 취득한다.
get_SourceTop | 현재의 전송원직사각형의 위에의 좌표를 취득한다.
get_SourceWidth | 현재의 전송원직사각형의 폭을 취득한다.
get_VideoHeight | 네이티브 비디오의 높이를 취득한다.
GetVideoPaletteEntries | 비디오의 팔레트 엔트리의 범위를 취득한다.
GetVideoSize | 네이티브 비디오의 폭과 높이를 취득한다.
get_VideoWidth | 네이티브 비디오의 폭을 취득한다.
IsUsingDefaultDestination | 렌더러가 디폴트의 전송처 윈도우를 사용하고 있을지 어떨지를 판단한다.
IsUsingDefaultSource | 렌더러가 디폴트의 전송원윈도우를 사용하고 있을지 어떨지를 판단한다.
put_DestinationHeight | 전송처 직사각형의 높이를 설정한다.
put_DestinationLeft | 전송처 직사각형의 왼쪽의 좌표를 설정한다.
put_DestinationTop | 전송처 직사각형의 위에의 좌표를 설정한다.
put_DestinationWidth | 전송처 직사각형의 폭을 설정한다.
put_SourceHeight | 전송원직사각형의 높이를 설정한다.
put_SourceLeft | 전송원직사각형의 왼쪽의 좌표를 설정한다.
put_SourceTop | 전송원직사각형의 위에의 좌표를 설정한다.
put_SourceWidth | 전송원직사각형의 폭을 설정한다.
SetDefaultDestinationPosition | 디폴트의 전송처의 위치를 재차 설정한다.
SetDefaultSourcePosition | 디폴트의 전송원래의 위치를 재차 설정한다.
SetDestinationPosition | 전송처 직사각형의 위치를 설정한다.
SetSourcePosition | 전송원직사각형의 위치를 설정한다.

CBaseControlVideo::CBaseControlVideo

CBaseControlVideo 클래스

CBaseControlVideo 오브젝트를 생성 한다.

구문

CBaseControlVideo(
CBaseFilter *pFilter,
CCritSec *pInterfaceLock,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
    );

파라미터

pFilter
소유하는 미디어 필터 오브젝트에의 포인터.
pInterfaceLock
락을 위해서(때문에) 사용하는 크리티컬 섹션에의 포인터.
pName
오브젝트 기술에의 포인터.
pUnk
오브젝트가 집성의 일부에서는 없는 경우는, 제어하는 IUnknown 인터페이스에의 포인터. 그 이외의 경우는, NULL 가 아니면 안된다.
phr
constructor　 　 메소드의 성공 또는 실패를 나타내는 HRESULT 값을 받는 변수에의 포인터.

반환값

반환값 없음.

주의

이 오브젝트는,IBasicVideo 컨트롤 인터페이스를 이행 한다.

이 클래스에서 이행 하는 IBasicVideo 의 모든 인터페이스 메소드에서는, 필터가 올바르게 접속되고 있을 필요가 있다. 이 때문에, 이 클래스에는 동기 해야 하는 핀이 건네받는다. 인터페이스 메소드가 불려 가면(자), 오브젝트는 반드시 핀이 접속되고 있는 것을 확인한다.

CBaseControlVideo::CheckSourceRect

CBaseControlVideo 클래스

전송원직사각형이 유효한지 어떤지를 판단한다.

구문

virtual HRESULT CheckSourceRect(
RECT *pSourceRect
    );

파라미터

pSourceRect
체크하는 전송원직사각형에의 포인터.

반환값

유효하지 않는 경우는 E_INVALIDARG 를 돌려준다. 그 이외의 경우는 NOERROR (S_OK)를 돌려준다.

주의

이 멤버 함수는, 요구된 전송원직사각형이, 사용 가능한 전송원비디오보다 크지 않을까 체크한다. 왼쪽 및 위에의 좌표를 부의 값으로 하는 것은 할 수 없다. 또, 폭 및 높이가 비디오의 오른쪽 및 아래를 넘을 수 없다.

CBaseControlVideo::CheckTargetRect

CBaseControlVideo 클래스

전송처 직사각형이 유효한지 어떤지를 판단한다.

구문

virtual HRESULT CheckTargetRect(
RECT *pTargetRect
    );

파라미터

pTargetRect
체크하는 전송처 직사각형에의 포인터.

반환값

유효하지 않는 경우는 E_INVALIDARG 를 돌려준다. 그 이외의 경우는 NOERROR (S_OK)를 돌려준다.

주의

이 멤버 함수는, 요구된 전송처 직사각형이 유효한지 어떤지를 판단한다. 전송처 직사각형은, 윈도우의 논리 클라이언트로 위치를 지정하므로, 최종적인 폭 및 높이를 0 및 부의 값으로 하는 것은 할 수 없지만, 좌표는 부의 값이 되는 경우가 있다.

CBaseControlVideo::CopyImage

CBaseControlVideo 클래스

이미지의 메모리 카피를 생성 한다.

구문

HRESULT CopyImage(
IMediaSample *pMediaSample,
VIDEOINFOHEADER *pVideoInfo,
LONG *pBufferSize,
BYTE *pVideoImage,
RECT *pSourceRect
    );

파라미터

pMediaSample
비디오 이미지를 포함한 샘플에의 포인터.
pVideoInfo
비디오 이미지를 나타내는 포맷에의 포인터.
pBufferSize
출력 버퍼의 사이즈에의 포인터.
pVideoImage
출력 버퍼에의 포인터.
pSourceRect
비디오의 전송원직사각형에의 포인터.

반환값

pVideoImage 파라미터가 NULL 의 경우,pBufferSize 파라미터에는, 이미지를 보존하기 위해서 출력 버퍼가 필요로 하는 바이트수가 저장 된다. 건네받은 버퍼가 너무 작은 경우나, 이 멤버 함수가 충분한 메모리를 할당할 수가 없는 경우, 이 멤버 함수는 E_OUTOFMEMORY 를 돌려준다.

주의

이 멤버 함수는 샘플로부터 이미지를 취득해, 출력 버퍼에 카피한다. 출력 버퍼에 카피된 비디오의 섹션은,IBasicVideo 인터페이스로 설정된 전송원직사각형을 반영한다 (다만, 전송처 직사각형은 반영하지 않는다).

CBaseControlVideo::get_AvgTimePerFrame

CBaseControlVideo 클래스

프레임마다의 평균 시간을 취득한다.

구문

HRESULT get_AvgTimePerFrame(
REFTIME *pAvgTimePerFrame
    );

파라미터

pAvgTimePerFrame
프레임마다의 평균 시간에의 포인터.

반환값

성공했을 경우는 NOERROR 를 돌려준다. 충분한 메모리가 없는 경우는 E_OUTOFMEMORY 를 돌려준다.

주의

이 멤버 함수는,IBasicVideo::get_AvgTimePerFrame 메소드를 이행 한다. 이 멤버 함수는, 순수 가상 멤버 함수 CBaseControlVideo::GetVideoFormat 를 호출해, 상속 클래스로부터 VIDEOINFOHEADER 구조체를 취득한다.

CBaseControlVideo::get_BitErrorRate

CBaseControlVideo 클래스

비디오의 대략의 비트 에러 레이트를 취득한다.

구문

HRESULT get_BitErrorRate(
long *pBitErrorRate
    );

파라미터

pBitErrorRate
비트 에러 레이트 (대략 이 수의 비트에 대해 1 개의 에러)에의 포인터.

반환값

성공했을 경우는 NOERROR 를 돌려준다. 충분한 메모리가 없는 경우는 E_OUTOFMEMORY 를 돌려준다.

주의

이 멤버 함수는,IBasicVideo::get_BitErrorRate 메소드를 이행 한다. 이 멤버 함수는, 순수 가상 멤버 함수 CBaseControlVideo::GetVideoFormat 를 호출해, 상속 클래스로부터 VIDEOINFOHEADER 구조체를 취득한다.

CBaseControlVideo::get_BitRate

CBaseControlVideo 클래스

비디오의 대략의 bit rate를 취득한다.

구문

HRESULT get_BitRate(
long *pBitRate
    );

파라미터

pBitRate
bit rate (비트/초)에의 포인터.

반환값

성공했을 경우는 NOERROR 를 돌려준다. 충분한 메모리가 없는 경우는 E_OUTOFMEMORY 를 돌려준다.

주의

이 멤버 함수는,IBasicVideo::get_BitRate 메소드를 이행 한다. 이 멤버 함수는, 순수 가상 멤버 함수 CBaseControlVideo::GetVideoFormat 를 호출해, 상속 클래스로부터 VIDEOINFOHEADER 구조체를 취득한다.

CBaseControlVideo::GetCurrentImage

CBaseControlVideo 클래스

렌더러의 현재의 이미지의 카피를 취득한다.

구문

HRESULT GetCurrentImage(
long *pBufferSize,
long *pVideoImage
    );

파라미터

pBufferSize
출력 버퍼의 사이즈에의 포인터.
pVideoImage
이미지의 출력 버퍼에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족. pVideoInfo 파라미터가 NULL 의 경우에 돌려주어진다.
NOERROR | 성공.
VFW_E_NOT_PAUSED | 필터가 정지되어 있지 않기 때문에, 처리를 실행할 수 없었다.

주의

이 멤버 함수는 샘플로부터 이미지를 취득해, 출력 버퍼에 카피한다. 출력 버퍼에 카피된 비디오의 섹션은,IBasicVideo 인터페이스로 설정된 전송원직사각형을 반영한다. 전송처의 직사각형은 반영되지 않는다.

CBaseControlVideo::get_DestinationHeight

CBaseControlVideo 클래스

현재의 전송처 직사각형의 높이를 취득한다.

구문

HRESULT get_DestinationHeight(
long *pDestinationHeight
    );

파라미터

pDestinationHeight
전송처의 높이에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

이 멤버 함수는,IBasicVideo::get_DestinationHeight 메소드를 이행 한다.

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 비디오가 재생되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::get_DestinationLeft

CBaseControlVideo 클래스

현재의 전송처 직사각형의 왼쪽의 좌표를 취득한다.

구문

HRESULT get_DestinationLeft(
long *pDestinationLeft
    );

파라미터

pDestinationLeft
전송처 직사각형의 왼쪽의 좌표에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

이 멤버 함수는,IBasicVideo::get_DestinationLeft 메소드를 이행 한다.

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::GetDestinationPosition

CBaseControlVideo 클래스

1 개의 처리로 전송처 직사각형을 취득한다.

구문

HRESULT GetDestinationPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
    );

파라미터

pLeft
전송처 직사각형의 왼쪽의 좌표에의 포인터.
pTop
전송처 직사각형의 위에의 좌표에의 포인터.
pWidth
전송처 직사각형의 폭에의 포인터.
pHeight
전송처 직사각형의 높이에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

이 멤버 함수는,CBaseControlVideo::get_DestinationLeft ,CBaseControlVideo::get_DestinationTop ,CBaseControlVideo::get_DestinationWidth , 및 CBaseControlVideo::get_DestinationHeight 멤버 함수의 개개의 호출 대신에 사용할 수 있다. IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::get_DestinationTop

CBaseControlVideo 클래스

현재의 전송처 직사각형의 위에의 좌표를 취득한다.

구문

HRESULT get_DestinationTop(
long *pDestinationTop
    );

파라미터

pDestinationTop
전송처 직사각형의 위에의 좌표에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

이 멤버 함수는,IBasicVideo::get_DestinationTop 메소드를 이행 한다.

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::get_DestinationWidth

CBaseControlVideo 클래스

현재의 전송처 직사각형의 폭을 취득한다.

구문

HRESULT get_DestinationWidth(
long *pDestinationWidth
    );

파라미터

pDestinationWidth
전송처의 폭에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

이 멤버 함수는,IBasicVideo::get_DestinationWidth 메소드를 이행 한다.

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::GetImageSize

CBaseControlVideo 클래스

비디오 이미지의 사이즈 정보를 취득한다.

구문

HRESULT GetImageSize(
VIDEOINFOHEADER *pVideoInfo,
long *pBufferSize,
RECT *pSourceRect
    );

파라미터

pVideoInfo
저장 되는 VIDEOINFOHEADER 구조체에의 포인터.
pBufferSize
비디오 버퍼의 사이즈에의 포인터.
pSourceRect
비디오의 전송원직사각형의 넓이에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수. 데이터 포맷에 호환성이 없다.
E_UNEXPECTED | 예기치 않은 에러가 발생했다. 1 개(살) 이상의 인수가 NULL 이다.
NOERROR | 성공.

주의

이 멤버 함수는, DIB 이미지의 메모리 이미지 렌더링을 생성 하기 위해서 사용하는 헬퍼 함수이다. 이 멤버 함수에게 건네진 pVideoImage 파라미터가 NULL 인 경우에,CBaseControlVideo::GetCurrentImage 의 base class의 이행으로부터 불려 간다. 이 결과, 이 멤버 함수는 pBufferSize 및 pSourceRect 의 정보를 사용해,VIDEOINFOHEADER 구조체를 구축해 돌려준다.

CBaseControlVideo::get_SourceHeight

CBaseControlVideo 클래스

현재의 전송원직사각형의 높이를 취득한다.

구문

HRESULT get_SourceHeight(
long *pSourceHeight
    );

파라미터

pSourceHeight
전송원직사각형의 높이에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

이 멤버 함수는,IBasicVideo::get_SourceHeight 메소드를 이행 한다.

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::get_SourceLeft

CBaseControlVideo 클래스

현재의 전송원직사각형의 왼쪽의 좌표를 취득한다.

구문

HRESULT get_SourceLeft(
long *pSourceLeft
    );

파라미터

pSourceLeft
현재의 전송원직사각형의 왼쪽의 좌표에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::GetSourcePosition

CBaseControlVideo 클래스

1 개의 처리로 전송원직사각형의 위치 및 넓이를 취득한다.

구문

HRESULT GetSourcePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
    );

파라미터

pLeft
전송원직사각형의 왼쪽의 좌표에의 포인터.
pTop
전송원직사각형의 위에의 좌표에의 포인터.
pWidth
전송원직사각형의 폭에의 포인터.
pHeight
전송원직사각형의 높이에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::GetSourceRect

CBaseControlVideo 클래스

전송원직사각형을 취득한다. 이것은 내부적인 메소드이다.

구문

virtual HRESULT GetSourceRect(
RECT *pSourceRect
) PURE;

파라미터

pSourceRect
취득된 전송원직사각형에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

비디오 렌더러에 의해 보관 유지되고 있는 전송원직사각형을 돌려주려면 , 이 멤버 함수를 상속 클래스로 오버라이드(override) 해야 한다. 이 멤버 함수는, 다음의 CBaseControlVideo 멤버 함수로부터 불려 간다.

  • CBaseControlVideo::GetSourcePosition
  • CBaseControlVideo::put_SourceLeft
  • CBaseControlVideo::get_SourceLeft
  • CBaseControlVideo::put_SourceWidth
  • CBaseControlVideo::get_SourceWidth
  • CBaseControlVideo::put_SourceTop
  • CBaseControlVideo::get_SourceTop
  • CBaseControlVideo::put_SourceHeight
  • CBaseControlVideo::get_SourceHeight

다음의 예는, 이 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다.

// 현재의 전송원직사각형을 돌려준다

HRESULT CVideoText::GetSourceRect(RECT *pSourceRect)
{
ASSERT(pSourceRect);
m_pRenderer->m_DrawImage.GetSourceRect(pSourceRect);
return NOERROR;
}

이 예에서는, CVideoText 는 CBaseControlVideo 으로부터 파생한 클래스이며, m_pRenderer 는 CBaseVideoRenderer 로부터 파생한 클래스의 오브젝트를 보관 유지한다. 또, 상속 클래스로 정의되는 m_DrawImage 데이터 멤버는 CDrawImage 오브젝트를 보관 유지한다.

CBaseControlVideo::get_SourceTop

CBaseControlVideo 클래스

현재의 전송원직사각형의 위에의 좌표를 취득한다.

구문

HRESULT get_SourceTop(
long *pSourceTop
    );

파라미터

pSourceTop
전송원직사각형의 위에의 좌표에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

이 멤버 함수는,IBasicVideo::get_SourceTop 메소드를 이행 한다.

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::get_SourceWidth

CBaseControlVideo 클래스

현재의 전송원직사각형의 폭을 취득한다.

구문

HRESULT get_SourceWidth(
long *pSourceWidth
    );

파라미터

pSourceWidth
현재의 전송원직사각형의 폭에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

주의

이 멤버 함수는,IBasicVideo::get_SourceWidth 메소드를 이행 한다.

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::GetStaticImage

CBaseControlVideo 클래스

상속 클래스로 오버라이드(override) 하는 순수 가상 메소드.

구문

virtual HRESULT GetStaticImage(
long *pBufferSize,
long *pDIBImage
) PURE;

파라미터

pBufferSize
출력 버퍼의 사이즈에의 포인터.
pDIBImage
출력 버퍼에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 메모리 버퍼내에 있는 현재의 이미지의 카피를 요구할 수 있다 (렌더러가 지원 하고 있지 않는 경우는, E_NOIMPL 를 돌려줄 수가 있다). 이미지를 취득하는 방법은, 상속 클래스로 결정한다. 어플리케이션이 CBaseControlVideo::GetStaticImage 를 호출하는 경우, 어플리케이션은, 상속 클래스로 오버라이드(override) 해 이행 할 필요가 있는 이 순수 가상 메소드를 호출한다. 이것은,CBaseControlVideo::GetCurrentImage 멤버 함수에 의해도 불려 간다.

이 클래스는, 이미지를 포함한 샘플을 취득할 수 있는 헬퍼 멤버 함수 CBaseControlVideo::CopyImage 를 제공 이바지한다. 이 멤버 함수는 (현재의 전송원직사각형에 근거해) 이미지의 관련하는 섹션을 카피해, 어플리케이션에 의해 제공된 출력 버퍼에 카피한다.

다음의 예는, 이 멤버 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다. 이 예로, m_pRenderer 는 CBaseVideoRenderer 로부터 파생한 클래스의 오브젝트를 보관 유지한다.

// 비디오 렌더러내의 현재의 이미지의 카피를 돌려준다.

HRESULT CVideoText::GetStaticImage(long *pBufferSize, long *pDIBImage)
{
// 렌더러가 보관 유지하고 있는 샘플을 취득한다.

IMediaSample *pMediaSample = m_pRenderer->GetCurrentSample();
if (pMediaSample == NULL) {
return E_UNEXPECTED;
    }

// base class의 헬퍼 메소드를 호출해 처리를 실시한다.

HRESULT hr = CopyImage(pMediaSample,          // 이미지를 포함한 버퍼
&m_pRenderer->m_mtIn,                // 비트 맵을 나타내는 타입
pBufferSize,                                     // DIB 의 버퍼의 사이즈
(BYTE*) pDIBImage);                   // 출력용의 데이터 버퍼

pMediaSample->Release();
return hr;
}

CBaseControlVideo::GetTargetRect

CBaseControlVideo 클래스

전송처 직사각형을 취득한다. 이것은 내부적인 헬퍼 멤버 함수이다.

구문

virtual HRESULT GetTargetRect(
RECT *pTargetRect
) PURE;

파라미터

pTargetRect
전송처 직사각형에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

비디오 렌더러에 의해 보관 유지되고 있는 전송처 직사각형을 돌려주려면 , 이 멤버 함수를 상속 클래스로 오버라이드(override) 해야 한다. 이 멤버 함수는, 다음의 CBaseControlVideo 멤버 함수로부터 불려 간다.

  • CBaseControlVideo::GetDestinationPosition
  • CBaseControlVideo::put_DestinationLeft
  • CBaseControlVideo::get_DestinationLeft
  • CBaseControlVideo::put_DestinationWidth
  • CBaseControlVideo::get_DestinationWidth
  • CBaseControlVideo::put_DestinationTop
  • CBaseControlVideo::get_DestinationTop
  • CBaseControlVideo::put_DestinationHeight
  • CBaseControlVideo::get_DestinationHeight

다음의 예는, 이 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다.

// 현재의 전송처 직사각형을 돌려준다.

HRESULT CVideoText::GetTargetRect(RECT *pTargetRect)
{
ASSERT(pTargetRect);
m_pRenderer->m_DrawImage.GetTargetRect(pTargetRect);
return NOERROR;
}

이 예에서는, CVideoText 는 CBaseControlVideo 으로부터 파생한 클래스이며, m_pRenderer 는 CBaseVideoRenderer 로부터 파생한 클래스의 오브젝트를 보관 유지한다. 또, 상속 클래스로 정의되는 m_DrawImage 데이터 멤버는 CDrawImage 오브젝트를 보관 유지한다.

CBaseControlVideo::GetVideoFormat

CBaseControlVideo 클래스

현재의 비디오 포맷을 나타내는 비디오 샘플을 취득한다.

구문

virtual VIDEOINFOHEADER * GetVideoFormat(void) PURE;

반환값

현재의 비디오 포맷을 포함한 VIDEOINFOHEADER 구조체에의 포인터를 돌려준다.

주의

IBasicVideo 를 사용해 특정의 정보를 돌려주어 체크하려면 , 오브젝트로 현재의 비디오 포맷을 알 수 있고 있을 필요가 있다. 오브젝트는, 상속 클래스로 오버라이드(override) 할 필요가 있는 이 순수 가상 메소드를 호출하는 것에 의해, 이 정보를 취득한다. 이 멤버 함수는, 다음의 CBaseControlVideo 멤버 함수로부터 불려 간다.

  • CBaseControlVideo::OnVideoSizeChange
  • CBaseControlVideo::get_AvgTimePerFrame
  • CBaseControlVideo::get_BitRate
  • CBaseControlVideo::get_BitErrorRate
  • CBaseControlVideo::get_VideoWidth
  • CBaseControlVideo::get_VideoHeight
  • CBaseControlVideo::GetVideoPaletteEntries
  • CBaseControlVideo::GetVideoSize

CBaseControlVideo::get_VideoHeight

CBaseControlVideo 클래스

네이티브 비디오의 높이를 취득한다.

구문

HRESULT get_VideoHeight(
long *pVideoHeight
    );

파라미터

pVideoHeight
픽셀 단위의 네이티브 비디오의 높이에의 포인터.

반환값

성공했을 경우는 NOERROR 를 돌려준다. 충분한 메모리가 없는 경우는 E_OUTOFMEMORY 를 돌려준다.

주의

이 멤버 함수는,IBasicVideo::get_VideoHeight 메소드를 이행 한다. 이 멤버 함수는, 순수 가상 멤버 함수 CBaseControlVideo::GetVideoFormat 를 호출해, 상속 클래스로부터 VIDEOINFOHEADER 구조체를 취득한다.

CBaseControlVideo::GetVideoPaletteEntries

CBaseControlVideo 클래스

비디오의 팔레트 엔트리의 범위를 취득한다.

구문

HRESULT GetVideoPaletteEntries(
long StartIndex,
long Entries,
long *pRetrieved,
long *pPalette
    );

파라미터

StartIndex
0 으로부터 시작되는 시작 팔레트 엔트리.
Entries
필요한 엔트리의 수.
pRetrieved
취득된 칼라의 수에의 포인터.
pPalette
칼라의 출력 버퍼에의 포인터.

반환값

성공했을 경우는 NOERROR, 비디오 샘플에 칼라 팔레트가 없는 경우는 VFW_E_NO_PALETTE_AVAILABLE, 충분한 메모리가 없는 경우는 E_OUTOFMEMORY,StartIndex 가 무효인 경우는 E_INVALIDARG, 팔레트에 칼라가 없는 경우는 S_FALSE 를 돌려준다.

주의

이 멤버 함수는, 현재의 비디오의 팔레트를, 유저에 의해 할당할 수 있었던 배열로서 돌려준다. 일관성을 유지하기 위해서(때문에), Win32 PALETTEENTRY 구조체의 멤버를 사용해 칼라를 돌려준다. 파라미터는 LONG 이지만,RGBQUAD 구조체의 멤버는 사용하지 않는다. 메모리는 호출해 바탕으로야는 할당할 수 있으므로, 단지 각각을 카피한다. 요구된 엔트리의 수 및 시작 위치의 오프셋(offset)의 양쪽 모두가 유효한 것을 확인한다. 엔트리의 수가 0 인 경우는, S_FALSE 코드를 돌려준다.

CBaseControlVideo::GetVideoSize

CBaseControlVideo 클래스

네이티브 비디오의 폭과 높이를 취득한다.

구문

HRESULT GetVideoSize(
long *pWidth,
long *pHeight
    );

파라미터

pWidth
비디오의 폭에의 포인터.
pHeight
비디오의 높이에의 포인터.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.
NOERROR | 성공.

CBaseControlVideo::get_VideoWidth

CBaseControlVideo 클래스

네이티브 비디오의 폭을 취득한다.

구문

HRESULT get_VideoWidth(
long *pVideoWidth
    );

파라미터

pVideoWidth
픽셀 단위의 네이티브 비디오의 폭에의 포인터.

반환값

성공했을 경우는 NOERROR 를 돌려준다. 충분한 메모리가 없는 경우는 E_OUTOFMEMORY 를 돌려준다.

주의

이 멤버 함수는,IBasicVideo::get_VideoWidth 메소드를 이행 한다. 이 멤버 함수는, 순수 가상 멤버 함수 CBaseControlVideo::GetVideoFormat 를 호출해, 상속 클래스로부터 VIDEOINFOHEADER 구조체를 취득한다.

CBaseControlVideo::IsDefaultSourceRect

CBaseControlVideo 클래스

렌더러가 디폴트의 전송원직사각형을 사용하고 있을지 어떨지를 판단한다 (순수 가상).

구문

virtual HRESULT IsDefaultSourceRect(void) PURE;

반환값

HRESULT 값을 돌려준다. 렌더러가 디폴트의 전송원을 사용하고 있는 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

이 멤버 함수는 상속 클래스로 이행 해야 한다. 이것은,CBaseControlVideo::IsUsingDefaultSource 멤버 함수에 의해 불려 간다.

다음의 예는, 이 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다.

// 디폴트의 전송원을 사용하고 있는 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

HRESULT CVideoText::IsDefaultSourceRect()
{
RECT SourceRect;

VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
m_pRenderer->m_DrawImage.GetSourceRect(&SourceRect);

// 비디오의 넓이에 일치하는 좌표를 체크한다.

if (SourceRect.left ! = 0 || SourceRect.top ! = 0 ||
SourceRect.right ! = pHeader->biWidth ||
SourceRect.bottom ! = pHeader->biHeight) {
return S_FALSE;
    }
return S_OK;
}

이 예에서는, CVideoText 는 CBaseControlVideo 으로부터 파생한 클래스이며, m_pRenderer 는 CBaseVideoRenderer 로부터 파생한 클래스의 오브젝트를 보관 유지한다. 또, 상속 클래스로 정의되는 m_DrawImage 데이터 멤버는 CDrawImage 오브젝트를 보관 유지한다. 이 상속 클래스로 정의되는 m_mtIn 데이터 멤버도,입력 핀의 미디어 타입을 가지는 CMediaType 오브젝트를 보관 유지한다.

CBaseControlVideo::IsDefaultTargetRect

CBaseControlVideo 클래스

렌더러가 디폴트의 전송처 직사각형을 사용하고 있을지 어떨지를 판단한다 (순수 가상).

구문

virtual HRESULT IsDefaultTargetRect(void) PURE;

반환값

HRESULT 값을 돌려준다. 렌더러가 디폴트의 전송처를 사용하고 있는 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

이 멤버 함수는 상속 클래스로 이행 해야 한다. 이것은,CBaseControlVideo::IsUsingDefaultDestination 멤버 함수에 의해 불려 간다.

다음의 예는, 이 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다.

// 디폴트의 전송처를 사용하고 있는 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

HRESULT CVideoText::IsDefaultTargetRect()
{
RECT TargetRect;

VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
m_pRenderer->m_DrawImage.GetTargetRect(&TargetRect);

// 초기 클라이언트 영역에 일치하는 전송처를 체크한다.

if (TargetRect.left ! = 0 || TargetRect.top ! = 0 ||
TargetRect.right ! = m_Size.cx ||
TargetRect.bottom ! = m_Size.cy) {
return S_FALSE;
    }
return S_OK;
}

이 예에서는, CVideoText 는 CBaseControlVideo 으로부터 파생한 클래스이며, m_pRenderer 는 CBaseVideoRenderer 로부터 파생한 클래스의 오브젝트를 보관 유지한다. 또, 상속 클래스로 정의되는 m_DrawImage 데이터 멤버는 CDrawImage 오브젝트를 보관 유지한다. 이 상속 클래스로 정의되는 m_mtIn 데이터 멤버도, 입력 핀의 미디어 타입을 가지는 CMediaType 오브젝트를 보관 유지한다.

CBaseControlVideo::IsUsingDefaultSource

CBaseControlVideo 클래스

렌더러가 디폴트의 전송원윈도우를 사용하고 있을지 어떨지를 판단한다.

구문

virtual HRESULT IsUsingDefaultSource(void);

반환값

HRESULT 값을 돌려준다. 렌더러가 디폴트의 전송원을 사용하고 있는 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

CBaseControlVideo::IsUsingDefaultDestination

CBaseControlVideo 클래스

렌더러가 디폴트의 전송처 윈도우를 사용하고 있을지 어떨지를 판단한다.

구문

virtual HRESULT IsUsingDefaultDestination(void);

반환값

HRESULT 값을 돌려준다. 디폴트의 전송처를 사용하고 있는 경우는 S_OK, 그 이외의 경우는 S_FALSE 를 돌려준다.

CBaseControlVideo::OnUpdateRectangles

CBaseControlVideo 클래스

전송원직사각형 또는 전송처 직사각형중 한쪽이 변경되면(자) 불려 간다.

구문

virtual HRESULT OnUpdateRectangles(void);

반환값

NOERROR 를 돌려준다.

CBaseControlVideo::OnVideoSizeChange

CBaseControlVideo 클래스

EC_VIDEO_SIZE_CHANGED 메세지를 필터 그래프 매니저에 건네준다.

구문

virtual HRESULT OnVideoSizeChange(void);

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_OUTOFMEMORY | 메모리 부족.

주의

비디오 렌더러는 비디오의 사이즈가 변경될 때마다 이 멤버 함수를 호출할 필요가 있다. 보통, 최초의 접속의 뒤에 1 회 불려 간다. 렌더러가 동적인 포맷의 변경 (320 x 240 에서 160 x 120)을 지원 하고 있는 경우, 렌더러는 각 변경의 뒤에도 이 멤버 함수를 호출할 필요가 있다.

CBaseControlVideo::put_DestinationHeight

CBaseControlVideo 클래스

전송처 직사각형의 높이를 설정한다.

구문

HRESULT put_DestinationHeight(
long DestinationHeight
    );

파라미터

DestinationHeight
새로운 전송처의 높이.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::put_DestinationLeft

CBaseControlVideo 클래스

전송처 직사각형의 왼쪽의 좌표를 설정한다.

구문

HRESULT put_DestinationLeft(
long DestinationLeft
    );

파라미터

DestinationLeft
새로운 전송처의 왼쪽의 좌표.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::put_DestinationTop

CBaseControlVideo 클래스

전송처 직사각형의 위에의 좌표를 설정한다.

구문

HRESULT put_DestinationTop(
long DestinationTop
    );

파라미터

DestinationTop
새로운 전송처의 위에의 좌표.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::put_DestinationWidth

CBaseControlVideo 클래스

전송처 직사각형의 폭을 설정한다.

구문

HRESULT put_DestinationWidth(
long DestinationWidth
    );

파라미터

DestinationWidth
새로운 전송처의 폭.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::put_SourceHeight

CBaseControlVideo 클래스

전송원직사각형의 높이를 설정한다.

구문

HRESULT put_SourceHeight(
long SourceHeight
    );

파라미터

SourceHeight
전송원의 높이.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::put_SourceLeft

CBaseControlVideo 클래스

전송원직사각형의 왼쪽의 좌표를 설정한다.

구문

HRESULT put_SourceLeft(
long SourceLeft
    );

파라미터

SourceLeft
새로운 전송원의 왼쪽의 좌표.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::put_SourceTop

CBaseControlVideo 클래스

전송원직사각형의 위에의 좌표를 설정한다.

구문

HRESULT put_SourceTop(
long SourceTop
    );

파라미터

SourceTop
새로운 전송원의 위에의 좌표.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::put_SourceWidth

CBaseControlVideo 클래스

전송원직사각형의 폭을 설정한다.

구문

HRESULT put_SourceWidth(
long SourceWidth
    );

파라미터

SourceWidth
새로운 전송원직사각형의 폭.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::SetControlVideoPin

CBaseControlVideo 클래스

필터에 의해 사용되는 핀을 설정한다.

구문

void SetControlVideoPin(
CBasePin *pPin
    );

파라미터

pPin
인터페이스가 동기 하는 핀에의 포인터.

반환값

반환값 없음.

주의

이 인터페이스는, 필터가 정상적으로 접속되었을 경우에게만 호출할 수가 있다. 오브젝트는, 이 메소드에 의해 동기 되는 핀에게 건네진다. 대부분의 경우, 인터페이스 메소드가 불려 갔을 때에 핀이 접속되고 있는지 어떤지를 판단해, 실패했을 경우는 VFW_E_NOT_CONNECTED 를 돌려준다.

CBaseControlVideo::SetDefaultDestinationPosition

CBaseControlVideo 클래스

렌더러가 디폴트의 전송처의 위치 (보통, 윈도우 클라이언트 영역 전체)를 사용하도록(듯이) 설정한다.

구문

HRESULT SetDefaultDestinationPosition(void);

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::SetDefaultSourcePosition

CBaseControlVideo 클래스

렌더러가 디폴트의 전송원래의 위치 (보통, 모든 네이티브 비디오)를 사용하도록(듯이) 설정한다.

구문

HRESULT SetDefaultSourcePosition(void);

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::SetDefaultSourceRect

CBaseControlVideo 클래스

디폴트의 비디오의 전송원직사각형을 설정한다 (순수 가상). 이것은, 전송원직사각형이 리셋 되었을 때에 불려 가는 내부적인 멤버 함수이다.

구문

virtual HRESULT SetDefaultSourceRect(void) PURE;

반환값

HRESULT 값을 돌려준다.

주의

전송원직사각형을 리셋 하려면 , 상속 클래스로 이것을 오버라이드(override) 할 필요가 있다. 이 멤버 함수는 CBaseControlVideo::SetDefaultSourcePosition 로부터 불려 간다.

다음의 예는, 이 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다.

// 이것은 디폴트의 전송원직사각형을 리셋 하면 불려 간다.

HRESULT CVideoText::SetDefaultSourceRect()
{
VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
RECT SourceRect = {0,0, pHeader->biWidth, pHeader->biHeight};
m_pRenderer->m_DrawImage.SetSourceRect(&SourceRect);
return NOERROR;
}

이 예에서는, CVideoText 는 CBaseControlVideo 으로부터 파생한 클래스이며, m_pRenderer 는 CBaseVideoRenderer 로부터 파생한 클래스의 오브젝트를 보관 유지한다. 또, 상속 클래스로 정의되는 m_DrawImage 데이터 멤버는 CDrawImage 오브젝트를 보관 유지한다. 이 상속 클래스로 정의되는 m_mtIn 데이터 멤버도, 입력 핀의 미디어 타입을 가지는 CMediaType 오브젝트를 보관 유지한다.

CBaseControlVideo::SetDefaultTargetRect

CBaseControlVideo 클래스

디폴트의 비디오의 전송처 직사각형을 설정한다 (순수 가상). 이것은, 전송처 직사각형이 리셋 되었을 때에 불려 가는 내부적인 멤버 함수이다.

구문

virtual HRESULT SetDefaultTargetRect(void) PURE;

반환값

HRESULT 값을 돌려준다.

주의

비디오의 전송처 직사각형을 리셋 하려면 , 상속 클래스로 이것을 오버라이드(override) 할 필요가 있다. 이 멤버 함수는 CBaseControlVideo::SetDefaultDestinationPosition 멤버 함수로부터 불려 간다.

다음의 예는, 이 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다.

// 이것은 디폴트의 전송처 직사각형을 리셋 하면 불려 간다.

HRESULT CVideoText::SetDefaultTargetRect()
{
VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
RECT TargetRect = {0,0, m_Size.cx, m_Size.cy};
m_pRenderer->m_DrawImage.SetTargetRect(&TargetRect);
return NOERROR;
}

이 예에서는, CVideoText 는 CBaseControlVideo 으로부터 파생한 클래스이며, m_pRenderer 는 CBaseVideoRenderer 로부터 파생한 클래스의 오브젝트를 보관 유지한다. 또, 상속 클래스로 정의되는 m_DrawImage 데이터 멤버는 CDrawImage 오브젝트를 보관 유지한다. 이 상속 클래스로 정의되는 m_mtIn 데이터 멤버도, 입력 핀의 미디어 타입을 가지는 CMediaType 오브젝트를 보관 유지한다.

CBaseControlVideo::SetDestinationPosition

CBaseControlVideo 클래스

비디오의 전송처 직사각형을 설정한다.

구문

HRESULT SetDestinationPosition(
long Left,
long Top,
long Width,
long Height
    );

파라미터

Left
새로운 왼쪽의 좌표.
Top
새로운 위에의 좌표.
Width
새로운 폭.
Height
새로운 높이.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::SetSourcePosition

CBaseControlVideo 클래스

비디오의 새로운 전송원래의 위치를 설정한다.

구문

HRESULT SetSourcePosition(
long Left,
long Top,
long Width,
long Height
    );

파라미터

Left
새로운 왼쪽의 좌표.
Top
새로운 위에의 좌표.
Width
새로운 폭.
Height
새로운 높이.

반환값

이행에 응한 HRESULT 값을 돌려준다. 이 값은, 다음의 값의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | Null 포인터 인수.
NOERROR | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않기 때문에, 처리를 실행할 수 없다.

주의

IBasicVideo 인터페이스를 사용해, 어플리케이션으로 비디오의 전송원직사각형 및 전송처 직사각형을 변경할 수가 있다. 전송원직사각형은, 네이티브 비디오 소스의 어느 섹션이 화면상에 표시될까에 영향을 미친다. 전송처 직사각형은, 재생시에 비디오가 표시되는 장소에 영향을 미친다. 전송처 직사각형은, 재생되는 윈도우의 클라이언트 영역 에 비례한다. 윈도우의 맨 왼쪽 위쪽의 좌표는 (0,0)이다.

CBaseControlVideo::SetSourceRect

CBaseControlVideo 클래스

현재의 비디오의 전송원직사각형을 설정한다 (순수 가상). 이것은, 전송원직사각형이 변경되었을 때에 불려 가는 내부적인 멤버 함수이다.

구문

virtual HRESULT SetSourceRect(
RECT *pSourceRect
) PURE;

파라미터

pSourceRect
전송원직사각형에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

전송원직사각형이 변경된 것을 알려면 , 상속 클래스로 이 멤버 함수를 오버라이드(override) 할 필요가 있다. 이 멤버 함수는, 다음의 멤버 함수로부터 불려 간다.

  • CBaseControlVideo::SetSourcePosition
  • CBaseControlVideo::put_SourceLeft
  • CBaseControlVideo::put_SourceWidth
  • CBaseControlVideo::put_SourceTop
  • CBaseControlVideo::put_SourceHeight

다음의 예는, 이 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다.

HRESULT CVideoText::SetSourceRect(RECT *pSourceRect)
{
m_pRenderer->m_DrawImage.SetSourceRect(pSourceRect);
return NOERROR;
}

이 예에서는, CVideoText 는 CBaseControlVideo 으로부터 파생한 클래스이며, m_pRenderer 는 CBaseVideoRenderer 로부터 파생한 클래스의 오브젝트를 보관 유지한다. 또, 상속 클래스로 정의되는 m_DrawImage 데이터 멤버는 CDrawImage 오브젝트를 보관 유지한다.

CBaseControlVideo::SetTargetRect

CBaseControlVideo 클래스

현재의 전송처 직사각형을 설정한다 (순수 가상). 이것은, 전송처 직사각형이 변경되었을 때에 불려 가는 내부적인 멤버 함수이다.

구문

virtual HRESULT SetTargetRect(
RECT *pTargetRect
) PURE;

파라미터

pTargetRect
전송처 직사각형에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

전송처 직사각형이 변경된 것을 알려면 , 상속 클래스로 이 멤버 함수를 오버라이드(override) 할 필요가 있다. 이 멤버 함수는, 다음의 멤버 함수로부터 불려 간다.

  • CBaseControlVideo::SetDestinationPosition
  • CBaseControlVideo::put_DestinationLeft
  • CBaseControlVideo::put_DestinationWidth
  • CBaseControlVideo::put_DestinationTop
  • CBaseControlVideo::put_DestinationHeight

다음의 예는, 이 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다.

HRESULT CVideoText::SetTargetRect(RECT *pTargetRect)
{
m_pRenderer->m_DrawImage.SetTargetRect(pTargetRect);
return NOERROR;
}

이 예에서는, CVideoText 는 CBaseControlVideo 으로부터 파생한 클래스이며, m_pRenderer 는 CBaseVideoRenderer 로부터 파생한 클래스의 오브젝트를 보관 유지한다. 또, 상속 클래스로 정의되는 m_DrawImage 데이터 멤버는 CDrawImage 오브젝트를 보관 유지한다.


CBaseControlWindow 클래스

CBaseControlWindow 클래스의 계층

CBaseControlWindow 클래스는 IVideoWindow 인터페이스를 이행 해, 이것에 관련지을 수 있었던 필터에의 외부의 액세스를 제어한다. 크리티컬 섹션 동기 오브젝트에의 포인터를 건네주는 것에 의해,CBaseControlWindow 오브젝트를 필터와 동기 해야 한다. 크리티컬 섹션 동기 오브젝트의 상세한 것에 대하여는, Platform SDK 를 참조할것. CBaseControlWindow 클래스는, 이 크리티컬 섹션을 처리하지 않고 프로퍼티의 설정을 돌려주는 수많은 메소드를 제공한다. 예를 들어,CBaseControlWindow::get_AutoShow 를 호출해 m_bAutoShow 데이터 멤버의 값을 취득 하면, 크리티컬 섹션은 락 된다. 다만, 필터가 이미 내부 크리티컬 섹션을 잠그고 있는 경우가 있어, 이 경우는 필터의 락 계층에 위반한다. 이 대신에,CBaseControlWindow::IsAutoShowEnabled 멤버 함수를 호출하면, 크리티컬 섹션에 영향을 미치지 않고 필요한 값이 돌려주어진다.

CBaseControlWindow 가 이행 하는 모든 IVideoWindow 메소드에서는, 필터가업 스트림 필터에 올바르게 접속되고 있을 필요가 있다. 이 때문에, 클래스 오브젝트는 동기 핀을 필요로 한다. 동기 핀은,CBaseControlWindow::SetControlWindowPin 메소드를 호출하는 것에 의해 설정된다. IVideoWindow 메소드를 호출하면,CBaseControlWindow 오브젝트는 이 핀이 접속되고 있는 것을 체크한다.

프로텍트 데이터 멤버

m_bAutoShow | 상태가 변화했을 때의 결과.
m_bCursorHidden | 커서가 표시 또는 비표시의 머지않아일까의 판별.
m_BorderColour | 현재의 윈도우의 경계의 칼라.
m_hwndDrain | 수신한 메세지의 송신지의 윈도우 핸들.
m_hwndOwner | 소유하는 윈도우.
m_pFilter | 소유하는 미디어 필터에의 포인터.
m_pInterfaceLock | 외부적으로 정의되는 크리티컬 섹션.
m_pPin | 접속의 미디어 타입의 제어.

멤버 함수

CBaseControlWindow | CBaseControlWindow 오브젝트를 생성 한다.
DoGetWindowStyle | 표준 윈도우 스타일 또는 확장 윈도우 스타일의 어느쪽이든을 취득한다.
DoSetWindowStyle | 표준 윈도우 스타일 또는 확장 윈도우 스타일을 설정한다.
GetBorderColour | 현재의 경계의 칼라를 취득한다. 이것은 헬퍼 멤버 함수이다.
GetOwnerWindow | 소유하는 윈도우를 취득한다. 이것은 헬퍼 멤버 함수이다.
IsAutoShowEnabled | 렌더링 필터가 포즈 또는 실행되었을 때에, 비디오 윈도우가 자동적으로 표시될지 어떨지에 대한 정보를 취득한다.
IsCursorHidden | 크리티컬 섹션을 잠그지 않고 ,m_bCursorHidden 데이터 멤버의 현재 상태를 취득한다. 이것은 헬퍼 멤버 함수이다.
PossiblyEatMessage | 부모 윈도우에 메세지를 전달한다.
SetControlWindowPin | 오브젝트가 적용되는 핀을 오브젝트에 통지한다.

이행 되는 IVideoWindow 메소드

get_AutoShow | 현재의 AutoShow 플래그의 설정을 취득한다.
get_BackgroundPalette | 백그라운드 플래그로 실현된 팔레트를 취득한다.
get_BorderColor | 현재의 경계의 칼라를 취득한다.
get_Caption | 현재의 윈도우 캡션을 취득한다.
get_FullScreenMode | 현재의 풀 스크린 모드를 취득한다.
get_Height | 현재의 윈도우의 높이를 취득한다.
get_Left | 현재의 왼쪽의 윈도우 좌표를 취득한다.
GetMaxIdealImageSize | 이상적인 이미지의 최대 사이즈를 취득한다.
get_MessageDrain | 현재의 메세지 drain를 취득한다.
GetMinIdealImageSize | 이상적인 이미지의 최소 사이즈를 취득한다.
get_Owner | Microsoft® Win32® 부모 윈도우 핸들을 취득한다.
GetRestorePosition | 최대화 또는 최소화했을 때에, 윈도우가 복원되는 위치를 취득한다.
get_Top | 윈도우 상부의 y 좌표를 취득한다.
get_Visible | 윈도우의 현재의 표시의 설정을 취득한다.
get_Width | 윈도우의 폭을 취득한다.
GetWindowPosition | 현재의 윈도우의 좌표를 취득한다.
get_WindowState | 현재의 윈도우 상태를 취득한다.
get_WindowStyle | 표준 윈도우 스타일을 취득한다.
get_WindowStyleEx | 확장 윈도우 스타일을 취득한다.
HideCursor | 커서의 표시/비표시를 바꾼다.
IsCursorHidden | m_bCursorHidden 데이터 멤버의 현재 상태를 취득한다.
NotifyOwnerMessage | 소유하는 윈도우에 송신되는 메세지를 건네준다.
put_AutoShow | AutoShow 프로퍼티를 설정한다.
put_BackgroundPalette | 백그라운드에서 팔레트를 실현하기 위한 플래그를 설정한다.
put_BorderColor | 현재의 경계의 칼라를 설정한다.
put_Caption | 현재의 윈도우 캡션을 설정한다.
put_FullScreenMode | 풀 스크린 모드를 설정한다.
put_Height | 현재의 윈도우의 높이를 설정한다.
put_Left | 윈도우의 왼쪽의 좌표를 설정한다.
put_MessageDrain | 메세지 drain 윈도우를 설정한다.
put_Owner | Microsoft Win32 부모 윈도우 핸들을 설정한다.
put_Top | 윈도우 상부의 위치를 설정한다.
put_Visible | 윈도우의 표시/비표시를 바꾼다.
put_Width | 윈도우의 폭을 설정한다.
put_WindowState | 윈도우 상태를 설정한다.
put_WindowStyle | 표준 윈도우 스타일을 설정한다.
put_WindowStyleEx | 확장 윈도우 스타일을 설정한다.
SetWindowForeground | foreground의 윈도우를 설정한다.
SetWindowPosition | 윈도우의 위치를 설정한다.

CBaseControlWindow::CBaseControlWindow

CBaseControlWindow 클래스

CBaseControlWindow 오브젝트를 생성 한다.

구문

CBaseControlWindow(
CBaseMediaFilter *pFilter,
CCritSec *pInterfaceLock,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
);

파라미터

pFilter
소유하는 미디어 필터 오브젝트에의 포인터.
pInterfaceLock
락을 위해서(때문에) 사용하는 크리티컬 섹션에의 포인터.
pName
오브젝트 기술에의 포인터.
pUnk
오브젝트가 집성의 일부에서는 없는 경우는, 제어하는 IUnknown 인터페이스에의 포인터. 그 이외의 경우는, NULL 가 아니면 안된다.
phr
constructor　 　 메소드의 성공 또는 실패를 나타내는 HRESULT 값을 받는 변수에의 포인터.

반환값

반환값 없음.

CBaseControlWindow::DoGetWindowStyle

CBaseControlWindow 클래스

현재의 표준 윈도우 스타일 또는 확장 윈도우 스타일을 취득한다.

구문

HRESULT DoGetWindowStyle(
long *pStyle,
long WindowLong
);

파라미터

pStyle
스타일 정보를 받는 변수에의 포인터.
WindowLong
취득하는 스타일을 지정하는 값. 다음의 언젠가가 아니면 안된다.
GWL_STYLE | 윈도우 스타일을 취득한다.
GWL_EXSTYLE | 확장 윈도우 스타일을 취득한다.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, Win32 GetWindowLong 함수를 호출해 윈도우 스타일을 취득한다. 이 멤버 함수는,CBaseControlWindow::get_WindowStyle 및 CBaseControlWindow::get_WindowStyleEx 멤버 함수에 의해 불려 간다.

CBaseControlWindow::DoSetWindowStyle

CBaseControlWindow 클래스

표준 윈도우 스타일 또는 확장 윈도우 스타일을 변경한다.

구문

HRESULT DoSetWindowStyle(
long Style,
long WindowLong
);

파라미터

Style
적절한 윈도우 스타일.
WindowLong
설정하는 스타일을 지정하는 값. 다음의 언젠가가 아니면 안된다.
GWL_STYLE | 윈도우 스타일을 취득한다.
GWL_EXSTYLE | 확장 윈도우 스타일을 취득한다.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, Win32 SetWindowLong 함수를 호출해 윈도우 스타일을 설정해, 다음에 현재의 위치에 윈도우를 재표시한다. 이 멤버 함수는,CBaseControlWindow::put_WindowStyle 및 CBaseControlWindow::put_WindowStyleEx 멤버 함수에 의해 불려 간다.

CBaseControlWindow::get_AutoShow

CBaseControlWindow 클래스

현재의 AutoShow 상태 플래그를 취득한다.

구문

HRESULT get_AutoShow(
long *AutoShow
);

파라미터

AutoShow
오토메이션 불형 플래그에의 포인터 (0 은 오프,-1 는 온).

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IVideoWindow::get_AutoShow 메소드를 이행 한다. 이 프로퍼티는, 어플리케이션의 윈도우 표시 액세스를 간소화한다. 이 프로퍼티가 -1 (온)로 설정되어 있는 경우, 보통 필터의 접속 후는 비표시가 되어 있는 윈도우는, 필터가 포즈 또는 실행되면(자) 자동적으로 표시된다. 다만, 필터가 정지했을 경우, 윈도우를 비표시로 해서는 안된다. 이 파라미터가 0 (오프)으로 설정되어 있는 경우, 어플리케이션이 적절한 파라미터를 지정해 CBaseControlWindow::put_Visible 또는 CBaseControlWindow::put_WindowState 를 호출했을 때에 마셔 윈도우가 표시된다.

이 멤버 함수는,IVideoWindow 인터페이스를 사용해 외부 오브젝트에 의해 불려 가는 것을 상정하고 있으므로, 관련지을 수 있었던 필터와 동기 하기 위해서 크리티컬 섹션을 잠근다. 외부 오브젝트로부터 호출하지 않는 경우에, 이 프로퍼티를 취득하려면 ,CBaseControlWindow::IsAutoShowEnabled 멤버 함수를 호출한다.

CBaseControlWindow::get_BackgroundPalette

CBaseControlWindow 클래스

백그라운드 플래그로 실현된 팔레트를 취득한다.

구문

HRESULT get_BackgroundPalette(
long *pBackgroundPalette
);

파라미터

pBackgroundPalette
오토메이션 불형 플래그에의 포인터 (0 은 오프,-1 는 온).

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IVideoWindow::get_BackgroundPalette 메소드를 이행 한다. 비디오를 다른 어플리케이션 또는 문서로 재생하는 경우, 그 어플리케이션으로 독자적인 팔레트를 사용하고 싶은 것이 있다. 이 플래그를 -1 로 설정하는 것에 의해, 어플리케이션은 비디오의 재생에 현재의 foreground 팔레트를 사용하는 것을 요구할 수 있다. 이 플래그가 0 으로 설정되어 있는 경우, 윈도우는 독자적인 우선 팔레트를 인스톨 해 실현된다. 윈도우로 다른 팔레트를 사용하도록(듯이) 지정 하면, 퍼포먼스가 큰폭으로 저하하는 것에 주의가 필요하다.

CBaseControlWindow::get_BorderColor

CBaseControlWindow 클래스

현재의 경계의 칼라를 취득한다.

구문

HRESULT get_BorderColor(
long *Color
);

파라미터

Color
현재의 경계의 칼라에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

어플리케이션은 비디오를 표시하는 전송처 직사각형을 설정할 수 있다. 이 직사각형은, 윈도우의 클라이언트 영역 에 비례한다. 전송처 직사각형을 설정했을 경우 (디폴트에서는 항상 윈도우 전체가 드로잉(Drawing) 된다), 비디오의 주위에 경계가 표시된다. 이 프로퍼티는, 경계에서 사용되는 칼라에 영향을 준다. 이 파라미터는 LONG 형으로서 지정되고 있지만, 실제로는 COLORREF 값이다.

이 멤버 함수는,IVideoWindow 인터페이스를 사용해 외부 오브젝트에 의해 불려 가는 것을 상정하고 있으므로, 관련지을 수 있었던 필터와 동기 하기 위해서 크리티컬 섹션을 잠근다. 외부 오브젝트로부터 호출하지 않는 경우에, 이 프로퍼티를 취득하려면 ,CBaseControlWindow::GetBorderColour 멤버 함수를 호출한다.

CBaseControlWindow::GetBorderColour

CBaseControlWindow 클래스

현재의 윈도우의 경계 칼라 m_BorderColour 를 취득한다.

구문

COLORREF GetBorderColour(void);

반환값

경계의 칼라를 돌려준다.

주의

어플리케이션은 비디오를 표시하는 전송처 직사각형을 설정할 수 있다. 이 직사각형은, 윈도우의 클라이언트 영역 에 비례한다. 전송처 직사각형을 설정했을 경우 (디폴트에서는 항상 윈도우 전체가 드로잉(Drawing) 된다), 비디오를 둘러싸는 영역, 즉 경계가 표시된다. 경계의 칼라는,CBaseControlWindow::put_BorderColor 멤버 함수를 사용해 설정할 수 있다. 이 프로퍼티는, 경계의 칼라에 영향을 준다. IVideoWindow::get_BorderColor 메소드를 사용해 외부로부터 호출하는 경우 이외는,CBaseControlWindow::get_BorderColor 대신에 이 멤버 함수를 사용한다.

CBaseControlWindow::get_Caption

CBaseControlWindow 클래스

현재의 윈도우 캡션을 취득한다.

구문

HRESULT get_Caption(
BSTR *pstrCaption
);

파라미터

pstrCaption
현재의 윈도우 캡션에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

Windows 베이스의 데스크탑 위에의 최상정도 윈도우에는, 타이틀 (캡션)을 관련지을 수 있다. 이 프로퍼티는,IVideoWindow 인터페이스를 사용해 문의 및 설정할 수가 있다. 설정된 캡션은, 윈도우에 WS_CAPTION 스타일이 적용되고 있는 경우에게만 표시된다. 이 스타일이 적용되지 않은 경우, 유저에 대해서는 표시되지 않지만, 캡션은 설정 ( 및 취득)할 수 있다.

CBaseControlWindow::get_FullScreenMode

CBaseControlWindow 클래스

현재의 풀 스크린 모드를 취득한다.

구문

HRESULT get_FullScreenMode(
long *FullScreenMode
);

파라미터

FullScreenMode
현재의 풀 스크린 모드에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 디폴트로 E_NOTIMPL 를 돌려준다. 이것은,IVideoWindow PID 에, 이렌더러가 풀 스크린 렌더러를 이행 하고 있지 않는 것을 통지한다.

CBaseControlWindow::get_Height

CBaseControlWindow 클래스

현재의 윈도우의 높이를 취득한다.

구문

HRESULT get_Height(
long *pHeight
);

파라미터

pHeight
픽셀 단위의 현재의 윈도우의 높이에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

윈도우는 데스크탑상에 위치 좌표를 가진다. 이것은 픽셀 단위의 4 개의 좌표 (좌, 상, 우, 하)에 의해 나타내진다. OLE 에 의해 자동화되는 인터페이스에서는, 보통, 좌, 상, 폭, 및 높이로 이 정도치좌표를 나타낸다. 이것은 Microsoft® DirectShow® 로 채용되고 있는 규칙이다. 좌표는 모두 픽셀 단위로 나타내져 좌표가 변경되면(자) 윈도우가 즉석에서 갱신된다.

왼쪽 또는 위에의 좌표를 설정 하면, 윈도우는 각각 왼쪽 또는 위로 이동한다. 이러한 좌표는 윈도우의 폭이나 높이에는 영향을 주지 않는다. 같이 폭 및 높이의 설정은 왼쪽 및 위에의 좌표에는 영향을 주지 않는다.

CBaseControlWindow::get_Left

CBaseControlWindow 클래스

현재의 왼쪽의 윈도우 좌표를 취득한다.

구문

HRESULT get_Left(
long *pLeft
);

파라미터

pLeft
픽셀 단위의 왼쪽의 좌표에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

윈도우는 데스크탑상에 위치 좌표를 가진다. 이 정도치좌표는 픽셀 단위의 4 개의 좌표 (좌, 상, 우, 하)에 의해 나타내진다. OLE 에 의해 자동화되는 인터페이스에서는, 보통, 좌, 상, 폭, 및 높이로 이 정도치좌표를 나타낸다. 이것은 DirectShow 로 채용되고 있는 규칙이다. 좌표는 모두 픽셀 단위로 나타내져 좌표가 변경되면(자) 윈도우가 즉석에서 갱신된다.

왼쪽 또는 위에의 좌표를 설정 하면, 윈도우는 각각 왼쪽 또는 위로 이동한다. 이러한 좌표는 윈도우의 폭이나 높이에는 영향을 주지 않는다. 같이 폭 및 높이의 설정은 왼쪽 및 위에의 좌표에는 영향을 주지 않는다.

CBaseControlWindow::GetMaxIdealImageSize

CBaseControlWindow 클래스

이상적인 이미지의 최대 사이즈를 취득한다.

구문

HRESULT GetMaxIdealImageSize(
long *pWidth,
long *pHeight
);

파라미터

pWidth
픽셀 단위의 이상적인 최대의 폭에의 포인터.
pHeight
픽셀 단위의 이상적인 최대의 높이에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

다양한 렌더러에는, 표시할 수 있는 이미지의 사이즈에 대해 퍼포먼스 위에의 제한이 있다. 렌더러는 지정된 최대 사이즈보다 큰 이미지를 표시하도록(듯이) 요구되었을 경우에서도 올바르게 기능하지만,IVideoWindow 인터페이스를 사용해, 이상적인 최소 사이즈 및 최대 사이즈를 지정할 수 있다. 이 인터페이스는 필터 그래프가 포즈 또는 실행되고 있는 경우에게만 불려 간다. 이것은, 이 때 처음으로 리소스를 할당할 수 있어 렌더러가 그 제한을 인식할 수 있기 때문이다. 제한이 존재하지 않는 경우는, 렌더러는 pWidth 및 pHeight 파라미터에 네이티브 비디오의 넓이를 저장 해, S_FALSE 를 돌려준다. 제한이 존재하는 경우는, 제한된 폭 및 높이가 입력되어 이 멤버 함수는 S_OK 를 돌려준다.

이 넓이는 전송처 비디오의 사이즈에 적용되어 전체적인 윈도우 사이즈에는 적용되지 않는다. 따라서, 설정하는 윈도우의 사이즈를 계산 하면나무는, 현재의 윈도우 스타일 (WS_CAPTION 나 WS_BORDER 등)을 고려할 필요가 있다.

CBaseControlWindow::get_MessageDrain

CBaseControlWindow 클래스

현재의 메세지 drain를 취득한다.

구문

HRESULT get_MessageDrain(
OAHWND *Drain
);

파라미터

Drain
윈도우 메세지를 받아들이는 현재의 윈도우에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

비디오 렌더링 필터에 송신된 메세지를, 다른 윈도우에 송신할 수 있다. CBaseControlWindow::get_MessageDrain 멤버 함수를 사용해 이 메세지를 수신하도록(듯이) 등록되어 있는 윈도우가, 현재의 메세지 drain이다.

CBaseControlWindow::GetMinIdealImageSize

CBaseControlWindow 클래스

이상적인 이미지의 최소 사이즈를 취득한다.

구문

HRESULT GetMinIdealImageSize(
long *pWidth,
long *pHeight
);

파라미터

pWidth
픽셀 단위의 이상적인 최소의 폭에의 포인터.
pHeight
픽셀 단위의 이상적인 최소의 높이에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

다양한 렌더러에는, 표시할 수 있는 이미지의 사이즈에 대해 퍼포먼스 위에의 제한이 있다. 렌더러는 지정된 최대 사이즈보다 큰 이미지를 표시하도록(듯이) 요구되었을 경우에서도 올바르게 기능하지만,IVideoWindow 인터페이스를 사용해, 이상적인 최소 사이즈 및 최대 사이즈를 지정할 수 있다. 이 인터페이스는 필터 그래프가 포즈 또는 실행되고 있는 경우에게만 불려 간다. 이것은, 이 때 처음으로 리소스를 할당할 수 있어 렌더러가 그 제한을 인식할 수 있기 때문이다. 제한이 존재하지 않는 경우는, 렌더러는 pWidth 및 pHeight 파라미터에 네이티브 비디오의 넓이를 저장 해, S_FALSE 를 돌려준다. 제한이 존재하는 경우는, 제한된 폭 및 높이가 입력되어 이 멤버 함수는 S_OK 를 돌려준다.

이 넓이는 전송처 비디오의 사이즈에 적용되어 전체적인 윈도우 사이즈에는 적용되지 않는다. 따라서, 설정하는 윈도우의 사이즈를 계산 하면나무는, 현재의 윈도우 스타일 (WS_CAPTION 나 WS_BORDER 등)을 고려할 필요가 있다.

CBaseControlWindow::get_Owner

CBaseControlWindow 클래스

현재의 윈도우의 소유자를 취득한다.

구문

HRESULT get_Owner(
OAHWND *Owner
);

파라미터

Owner
윈도우의 소유자에게로의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

비디오 윈도우는 문서 환경내에서 재생할 수 있다. 이것을 실시하려면 , 윈도우는 다른 윈도우의 아이가 아니면 안된다 (윈도우를 적절히 클립 및 이동하기 위해(때문에)). 이 프로퍼티에 의해, 윈도우의 소유자를 설정 및 취득할 수 있다. 윈도우가 다른 윈도우에 의해 소유되고 있는 경우, 그 윈도우는 Microsoft Win32 SetParent 함수를 호출한다. 이 함수를 호출하는 어플리케이션은, 윈도우 스타일을 변경해, WS_CHILD 비트를 온으로 설정한다.

윈도우가 다른 윈도우에 소유되고 있는 경우, 특정의 메세지 (구체적으로는 마우스 및 키보드 메세지)를 자동적으로 전송 한다. 이것에 의해, 어플리케이션은 간단하게 핫 스포트 편집 및 그 외의 상호작용을 실행할 수 있다.

이 멤버 함수는,IVideoWindow 인터페이스를 사용해 외부 오브젝트에 의해 불려 가는 것을 상정하고 있으므로, 관련지을 수 있었던 필터와 동기 하기 위해서 크리티컬 섹션을 잠근다. 외부 오브젝트로부터 호출하지 않는 경우에, 이 프로퍼티를 취득하려면 ,CBaseControlWindow::GetOwnerWindow 멤버 함수를 호출한다.

CBaseControlWindow::GetOwnerWindow

CBaseControlWindow 클래스

소유하는 윈도우 핸들 m_hwndOwner 를 취득한다.

구문

HWND GetOwnerWindow(void);

반환값

소유자 윈도우를 돌려주는 내부적인 메소드를 돌려준다.

주의

이 멤버 함수는, 인터페이스 메소드를 호출하지 않고 , 소유하는 윈도우를 취득한다. IVideoWindow::get_Owner 메소드를 사용해 외부로부터 호출하는 경우 이외는,CBaseControlWindow::get_Owner 대신에 이 멤버 함수를 사용한다.

CBaseControlWindow::GetRestorePosition

CBaseControlWindow 클래스

최대화 또는 최소화하지 않을 때에, 윈도우가 복원되는 위치를 취득한다.

구문

HRESULT GetRestorePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

파라미터

pLeft
가장 왼쪽의 좌표의 값에의 포인터.
pTop
윈도우 상부의 값에의 포인터.
pWidth
윈도우의 폭의 값에의 포인터.
pHeight
윈도우의 높이의 값에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

윈도우가 최대화 또는 최소화되어 있지 않은 경우, 이것은 CBaseControlWindow::GetWindowPosition 함수에 의해 돌려주어지는 값과 같다.

CBaseControlWindow::get_Top

CBaseControlWindow 클래스

위에의 윈도우 좌표를 취득한다.

구문

HRESULT get_Top(
long *pTop
);

파라미터

pTop
픽셀 단위의 위에의 좌표에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

윈도우는 데스크탑상에 위치 좌표를 가진다. 이것은 픽셀 단위의 4 개의 좌표 (좌, 상, 우, 하)에 의해 나타내진다. OLE 에 의해 자동화되는 인터페이스에서는, 보통, 좌, 상, 폭, 및 높이로 이 정도치좌표를 나타낸다. 이것은 DirectShow 로 채용되고 있는 규칙이다. 좌표는 모두 픽셀 단위로 나타내져 좌표가 변경되면(자) 윈도우가 즉석에서 갱신된다.

왼쪽 또는 위에의 좌표를 설정 하면, 윈도우는 각각 왼쪽 또는 위로 이동한다. 이러한 좌표는 윈도우의 폭이나 높이에는 영향을 주지 않는다. 같이 폭 및 높이의 설정은 왼쪽 및 위에의 좌표에는 영향을 주지 않는다.

CBaseControlWindow::get_Visible

CBaseControlWindow 클래스

현재의 윈도우의 표시의 설정을 취득한다.

구문

HRESULT get_Visible(
long *pVisible
);

파라미터

pVisible
오토메이션 불형 플래그에의 포인터 (0 은 오프,-1 는 온).

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 윈도우가 WS_VISIBLE 스타일의 경우는 -1 을 돌려준다. 그 이외의 경우는 0 을 돌려준다.

CBaseControlWindow::get_Width

CBaseControlWindow 클래스

현재의 윈도우의 폭을 취득한다.

구문

HRESULT get_Width(
long *pWidth
);

파라미터

pWidth
픽셀 단위의 윈도우의 폭에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

윈도우는 데스크탑상에 위치 좌표를 가진다. 이것은 픽셀 단위의 4 개의 좌표 (좌, 상, 우, 하)에 의해 나타내진다. OLE 에 의해 자동화되는 인터페이스에서는, 보통, 좌, 상, 폭, 및 높이로 이 정도치좌표를 나타낸다. 이것은 DirectShow 로 채용되고 있는 규칙이다. 좌표는 모두 픽셀 단위로 나타내져 좌표가 변경되면(자) 윈도우가 즉석에서 갱신된다.

왼쪽 또는 위에의 좌표를 설정 하면, 윈도우는 각각 왼쪽 또는 위로 이동한다. 이러한 좌표는 윈도우의 폭이나 높이에는 영향을 주지 않는다. 같이 폭 및 높이의 설정은 왼쪽 및 위에의 좌표에는 영향을 주지 않는다.

CBaseControlWindow::GetWindowPosition

CBaseControlWindow 클래스

현재의 윈도우의 좌표를 취득한다.

구문

HRESULT GetWindowPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

파라미터

pLeft
화면 좌표에서의 왼쪽의 좌표에의 포인터.
pTop
화면 좌표에서의 위에의 좌표에의 포인터.
pWidth
화면 좌표에서의 윈도우의 폭에의 포인터.
pHeight
화면 좌표에서의 윈도우의 높이에의 포인터.

반환값

HRESULT 값을 돌려준다.

CBaseControlWindow::get_WindowState

CBaseControlWindow 클래스

현재의 윈도우 상태를 취득한다.

구문

HRESULT get_WindowState(
long *pWindowState
);

파라미터

pWindowState
윈도우 상태에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, Microsoft Win32 ShowWindow 함수의 파라미터의 서브 세트를 돌려준다. 구체적으로는, 현재의 윈도우의 표시의 설정에 근거해 SW_SHOW 및 SW_HIDE 를 돌려준다. 또, 윈도우가 아이콘화 되고 있는지, 최대화되고 있을까에 응해, SW_MINIMIZE 및 SW_MAXIMIZE 를 돌려준다.

CBaseControlWindow::get_WindowStyle

CBaseControlWindow 클래스

표준 윈도우 스타일을 취득한다.

구문

HRESULT get_WindowStyle(
long *pWindowStyle
);

파라미터

pWindowStyle
윈도우 스타일에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, WS_CHILD 및 WS_VISIBLE 등의 표준 윈도우 스타일을 돌려준다. 이 멤버 함수는,CBaseControlWindow::DoGetWindowStyle 멤버 함수를 호출한다.

CBaseControlWindow::get_WindowStyleEx

CBaseControlWindow 클래스

확장 윈도우 스타일을 취득한다.

구문

HRESULT get_WindowStyleEx(
long *pWindowStyleEx
);

파라미터

pWindowStyleEx
확장 윈도우 스타일에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 확장 윈도우 스타일을 취득한다. 이 멤버 함수는,CBaseControlWindow::DoGetWindowStyle 멤버 함수를 호출한다.

CBaseControlWindow::HideCursor

CBaseControlWindow 클래스

커서의 표시/비표시를 바꾼다.

구문

HRESULT HideCursor(
long HideCursor
);

파라미터

HideCursor
커서를 표시할지 어떨지를 지정하는 값. 커서를 비표시로 하는 경우는 OATRUE 에, 커서를 표시하는 경우는 OAFALSE 로 설정한다.

반환값

HRESULT 값을 돌려준다.

CBaseControlWindow::IsCursorHidden

CBaseControlWindow 클래스

m_bCursorHidden 데이터 멤버의 현재 상태를 취득한다.

구문

HRESULT IsCursorHidden(
long *CursorHidden
);

BOOL IsCursorHidden(void);

파라미터

CursorHidden
m_bCursorHidden 의 값에의 포인터.

반환값

파라미터를 지정하지 않고 호출했을 경우, 커서가 비표시의 경우는 OATRUE, 커서가 표시되고 있는 경우는 OAFALSE 를 돌려준다.

파라미터를 지정해 호출했을 경우는,HRESULT 값을 돌려준다.

주의

내부 오브젝트는, 크리티컬 섹션을 잠그지 않게,CursorHidden 파라미터를 지정하지 않고 이 멤버 함수를 호출하지 않으면 안 된다. 외부 오브젝트는,IVideoWindow::IsCursorHidden 메소드를 사용해 이 멤버 함수에 액세스 한다.

CBaseControlWindow::IsAutoShowEnabled

CBaseControlWindow 클래스

렌더링 필터가 포즈 또는 실행되었을 때에, 비디오 윈도우가 자동적으로 표시될지 어떨지에 대한 정보를 취득한다.

구문

BOOL IsAutoShowEnabled(void);

반환값

m_bAutoShow 멤버가 -1 로 설정되어 있는 경우는 TRUE, 0 으로 설정되어 있는 경우는 FALSE 를 돌려준다.

주의

비표시의 비디오 윈도우에 대해 m_bAutoShow 멤버가 -1 로 설정되어 있는 경우, 필터가 포즈 또는 실행되면(자) 윈도우가 표시된다. 이 멤버가 0 으로 설정되어 있는 경우, 적절한 파라미터를 지정해 CBaseControlWindow::put_Visible 또는 CBaseControlWindow::put_WindowState 를 호출했을 때에 마셔 윈도우가 표시된다.

이 멤버 함수는,m_bAutoShow 멤버의 설정을 취득한다. 그 결과는,IVideoWindow::get_AutoShow 메소드를 사용했을 경우와 같다.

CBaseControlWindow::NotifyOwnerMessage

CBaseControlWindow 클래스

특정의 메세지를 비디오 윈도우에 건네준다.

구문

HRESULT NotifyOwnerMessage(
long hwnd,
long uMsg,
long wParam,
long lParam
);

파라미터

hwnd
비디오 윈도우의 핸들.
uMsg
메세지의 상세.
wParam
최초의 메세지 파라미터.
lParam
2 번째의 메세지 파라미터.

반환값

NO_ERROR 를 돌려준다.

주의

비디오 윈도우가 다른 윈도우의 아이인 경우, 비디오 윈도우는 특정의 최상정도 윈도우의 메세지를 수신하지 않는다. 이러한 메세지는 렌더러의 동작에 영향을 주는 경우가 있으므로, 렌더러에 있어 유용한 일이 있다. NotifyOwnerMessage 는, 이하의 메세지를 비디오 윈도우에 건네준다.

  • WM_ACTIVATEAPP
  • WM_DEVMODECHANGE
  • WM_DISPLAYCHANGE
  • WM_PALETTECHANGED
  • WM_PALETTECHANGED
  • WM_QUERYNEWPALETTE
  • WM_SYSCOLORCHANGE

IVideoWindow PID 에 요구해, 윈도우를 다른 윈도우의 아이로 할 수 있다. 이 경우, PID 는 소유하는 윈도우에 송신된 특정의 메세지를 검색한다. 다음에, PID 는 이러한 메세지가 소유되는 윈도우에 전송 한다. 이 메세지의 디폴트의 처리에서는, Win32 SendMessage 함수를 호출해, 소유되는 윈도우의 프로시저에 동기적으로 메세지가 송신된다.

CBaseControlWindow::PossiblyEatMessage

CBaseControlWindow 클래스

키보드 및 마우스 메세지가 지정된 윈도우에 전송 한다.

구문

BOOL WINAPI PossiblyEatMessage(
HWND hwndDrain,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
    )

파라미터

hwndDrain
메세지가 전송 되는 윈도우의 핸들.
uMsg
전송 되는 메세지.
wParam
최초의 메세지 파라미터.
lParam
2 번째의 메세지 파라미터.

반환값

메세지가 송신되었을 경우는 TRUE, 송신되지 않았던 경우는 FALSE 를 돌려준다.

주의

윈도우가 소유되고 있는 경우, 이 윈도우는 특정의 클래스의 메세지 (키보드 및 마우스 메세지)를 소유하는 윈도우에 건네준다. 이 경우, Win32 PostMessage 함수를 호출해,CBaseControlWindow::put_MessageDrain 로 설정된 hwndDrain 로 지정되고 있는 윈도우에 메세지를 송신한다. 특정의 메세지를 송신할 수 없는 경우, 이 메세지는 FALSE 를 돌려준다.

미변환인 채 건네받아, TRUE 를 돌려주는 메세지의 일람을 이하에 나타낸다.
WM_CHAR | WM_DEADCHAR
WM_KEYDOWN | WM_KEYUP
WM_LBUTTONDBLCLK | WM_LBUTTONDOWN
WM_LBUTTONUP | WM_LBUTTONDBLCLK
WM_MBUTTONDOWN | WM_LBUTTONUP
WM_MOUSEACTIVATE | WM_MOUSEMOVE
WM_NCHITTEST | WM_NCLBUTTONDBLCLK
WM_NCLBUTTONDOWN | WM_NCLBUTTONUP
WM_NCMBUTTONDBLCLK | WM_NCMBUTTONDOWN
WM_NCMBUTTONUP | WM_NCMOUSEMOVE
WM_NCRBUTTONDBLCLK | WM_NCRBUTTONDOWN
WM_NCRBUTTONUP | WM_RBUTTONDBLCLK
WM_RBUTTONDOWN | WM_RBUTTONUP
WM_SYSCHAR | WM_SYSDEADCHAR
WM_SYSKEYDOWN | WM_SYSKEYUP

CBaseControlWindow::put_AutoShow

CBaseControlWindow 클래스

AutoShow 상태 플래그를 설정한다.

구문

HRESULT put_AutoShow(
long AutoShow
);

파라미터

AutoShow
오토메이션 불형 플래그 (0 은 오프,-1 는 온).

반환값

HRESULT 값을 돌려준다.

주의

이 프로퍼티는, 어플리케이션의 윈도우 표시 액세스를 간소화한다. 이 프로퍼티가 -1 (온)로 설정되어 있는 경우, 보통 필터의 접속 후는 비표시가 되어 있는 윈도우는, 필터가 포즈 또는 실행되면(자) 자동적으로 표시된다. 다만, 필터가 정지했을 경우, 윈도우를 비표시로 해서는 안된다. 이 파라미터가 0 (오프)으로 설정되어 있는 경우, 어플리케이션이 적절한 파라미터를 지정해 CBaseControlWindow::put_Visible 또는 CBaseControlWindow::put_WindowState 를 호출했을 때에 마셔 윈도우가 표시된다.

CBaseControlWindow::put_BackgroundPalette

CBaseControlWindow 클래스

백그라운드에서 팔레트를 실현하기 위한 플래그를 설정한다.

구문

HRESULT put_BackgroundPalette(
long BackgroundPalette
);

파라미터

BackgroundPalette
오토메이션 불형 플래그 (0 은 오프,-1 는 온).

반환값

HRESULT 값을 돌려준다.

주의

비디오를 다른 어플리케이션 또는 문서로 재생하기 위해서, 그 어플리케이션으로 독자적인 팔레트를 사용하고 싶은 것이 있다. 이 플래그를 -1 로 설정하는 것에 의해, 어플리케이션은 비디오의 백그라운드 팔레트로서 독자적인 팔레트는 아니고 현재의 foreground 팔레트를 사용하는 것을 요구할 수 있다. 이 플래그가 0 으로 설정되어 있는 경우, 윈도우는 독자적인 우선 팔레트를 인스톨 해 실현된다. 윈도우로 다른 팔레트를 사용하도록(듯이) 지정 하면, 퍼포먼스가 큰폭으로 저하한다.

CBaseControlWindow::put_BorderColor

CBaseControlWindow 클래스

경계의 칼라를 변경한다.

구문

HRESULT put_BorderColor(
long Color
);

파라미터

Color
새로운 경계의 칼라.

반환값

HRESULT 값을 돌려준다.

주의

어플리케이션은 비디오를 표시하는 전송처 직사각형을 설정할 수 있다. 이 직사각형은, 윈도우의 클라이언트 영역 에 비례한다. 전송처 직사각형을 설정했을 경우 (디폴트에서는 항상 윈도우 전체가 드로잉(Drawing) 된다), 비디오의 주위에 경계가 표시된다. 이 프로퍼티는, 경계에서 사용되는 칼라에 영향을 준다. 이 파라미터는 LONG 형으로서 지정되고 있지만, 실제로는 COLORREF 값이다.

CBaseControlWindow::put_Caption

CBaseControlWindow 클래스

윈도우 타이틀 또는 캡션을 설정한다.

구문

HRESULT put_Caption(
BSTR strCaption
);

파라미터

strCaption
새로운 윈도우 캡션.

반환값

HRESULT 값을 돌려준다.

주의

Windows 베이스의 데스크탑 위에의 최상정도 윈도우에는, 타이틀 (캡션)을 관련지을 수 있다. 이 프로퍼티는,IVideoWindow 인터페이스를 사용해 문의 및 설정할 수가 있다. 설정된 캡션은, 윈도우에 WS_CAPTION 스타일이 적용되고 있는 경우에게만 표시된다. 이 스타일이 적용되지 않은 경우, 유저에 대해서는 표시되지 않지만, 캡션은 설정 ( 및 취득)할 수 있다.

CBaseControlWindow::put_FullScreenMode

CBaseControlWindow 클래스

렌더러의 풀 스크린 모드를 설정한다.

구문

HRESULT put_FullScreenMode(
long FullScreenMode
);

파라미터

FullScreenMode
적용하는 풀 스크린 모드.

반환값

HRESULT 값을 돌려준다. 현재의 이행은 E_NOTIMPL 를 돌려준다.

주의

풀 스크린 모드를 이행 하는 비디오 렌더러는, 이 멤버 함수를 오버라이드(override) 해, 지원 하는 모드를 이행 한다.

CBaseControlWindow::put_Height

CBaseControlWindow 클래스

윈도우의 높이를 설정한다.

구문

HRESULT put_Height(
long Height
);

파라미터

Height
픽셀 단위의 새로운 윈도우의 높이.

반환값

HRESULT 값을 돌려준다.

주의

윈도우는 데스크탑상에 위치 좌표를 가진다. 이것은 픽셀 단위의 4 개의 좌표 (좌, 상, 우, 하)에 의해 나타내진다. OLE 에 의해 자동화되는 인터페이스에서는, 보통, 좌, 상, 폭, 및 높이로 이 정도치좌표를 나타낸다. 이것은 DirectShow 로 채용되고 있는 규칙이다. 좌표는 모두 픽셀 단위로 나타내져 좌표가 변경되면(자) 윈도우가 즉석에서 갱신된다.

왼쪽 또는 위에의 좌표를 설정 하면, 윈도우는 각각 왼쪽 또는 위로 이동한다. 이러한 좌표는 윈도우의 폭이나 높이에는 영향을 주지 않는다. 같이 폭 및 높이의 설정은 왼쪽 및 위에의 좌표에는 영향을 주지 않는다.

CBaseControlWindow::put_Left

CBaseControlWindow 클래스

윈도우의 왼쪽의 좌표를 설정한다.

구문

HRESULT put_Left(
long Left
);

파라미터

Left
픽셀 단위의 새로운 왼쪽의 좌표.

반환값

HRESULT 값을 돌려준다.

주의

윈도우는 데스크탑상에 위치 좌표를 가진다. 이것은 픽셀 단위의 4 개의 좌표 (좌, 상, 우, 하)에 의해 나타내진다. OLE 에 의해 자동화되는 인터페이스에서는, 보통, 좌, 상, 폭, 및 높이로 이 정도치좌표를 나타낸다. 이것은 DirectShow 로 채용되고 있는 규칙이다. 좌표는 모두 픽셀 단위로 나타내져 좌표가 변경되면(자) 윈도우가 즉석에서 갱신된다.

왼쪽 또는 위에의 좌표를 설정 하면, 윈도우는 각각 왼쪽 또는 위로 이동한다. 이러한 좌표는 윈도우의 폭이나 높이에는 영향을 주지 않는다. 같이 폭 및 높이의 설정은 왼쪽 및 위에의 좌표에는 영향을 주지 않는다.

CBaseControlWindow::put_MessageDrain

CBaseControlWindow 클래스

비디오 렌더러에 송신된 윈도우 메세지를 수신하는 윈도우를 설정한다.

구문

HRESULT put_MessageDrain(
OAHWND Drain
);

파라미터

Drain
메세지의 송신지의 윈도우.

반환값

HRESULT 값을 돌려준다.

주의

비디오 렌더링 필터에 송신된 메세지를, 다른 윈도우에 송신할 수 있다. 이 멤버 함수는, 이러한 메세지를 수신하는 윈도우를 등록한다. CBaseControlWindow::put_Owner 멤버 함수와는 달라, 이 멤버 함수는 비디오 윈도우를 다른 윈도우의 아이로 하지 않는다. 이 멤버 함수는, 자식 윈도우로 할 수 없는 풀 스크린 비디오 렌더러로 특히 유용하다.

CBaseControlWindow::put_Owner

CBaseControlWindow 클래스

비디오 윈도우의 부모 윈도우를 설정한다. 이 부모 윈도우는 특정의 메세지를 비디오 윈도우에 전송 한다.

구문

HRESULT put_Owner(
OAHWND Owner
);

파라미터

Owner
부모 윈도우의 핸들.

반환값

NOERROR 를 돌려준다.

주의

내부적으로는, 이 메소드는 Microsoft Win32 SetParent 함수를 호출해 새로운 소유자를 설정해, 윈도우의 스타일을 WS_CHILD 로 설정한다. 이 부모 윈도우는 특정의 메세지 (구체적으로는 마우스 및 키보드 메세지)를 비디오 윈도우에 전송 한다.

비디오 윈도우의 소유자를 설정한 후, 필터 그래프를 해방하기 전에, 소유자를 NULL 로 설정해, 소유자의 윈도우 스타일을 WS_OVERLAPPED 및 WS_CLIPCHILDREN 로 설정해야 한다. 소유자를 NULL 로 설정 하면, 이 메소드는 부모 윈도우의 WS_CHILD 비트를 오프로 한다. 소유자를 NULL 로 설정하지 않는 경우, 부모 윈도우는 메세지를 비디오 윈도우에 계속 건네주므로 , 어플리케이션을 종료했을 때에 에러가 발생할 가능성이 있다.

CBaseControlWindow::put_Top

CBaseControlWindow 클래스

위에의 윈도우 좌표를 설정한다.

구문

HRESULT put_Top(
long Top
);

파라미터

Top
픽셀 단위의 새로운 위에의 좌표.

반환값

HRESULT 값을 돌려준다.

주의

윈도우는 데스크탑상에 위치 좌표를 가진다. 이것은 픽셀 단위의 4 개의 좌표 (좌, 상, 우, 하)에 의해 나타내진다. OLE 에 의해 자동화되는 인터페이스에서는, 보통, 좌, 상, 폭, 및 높이로 이 정도치좌표를 나타낸다. 이것은 DirectShow 로 채용되고 있는 규칙이다. 좌표는 모두 픽셀 단위로 나타내져 좌표가 변경되면(자) 윈도우가 즉석에서 갱신된다.

왼쪽 또는 위에의 좌표를 설정 하면, 윈도우는 각각 왼쪽 또는 위로 이동한다. 이러한 좌표는 윈도우의 폭이나 높이에는 영향을 주지 않는다. 같이 폭 및 높이의 설정은 왼쪽 및 위에의 좌표에는 영향을 주지 않는다.

CBaseControlWindow::put_Visible

CBaseControlWindow 클래스

윈도우를 표시 또는 비표시로 한다.

구문

HRESULT put_Visible(
long Visible
);

파라미터

Visible
오토메이션 불형 플래그 (0 의 경우, 윈도우는 비표시. -1 의 경우, 윈도우는 표시된다).

반환값

HRESULT 값을 돌려준다.

CBaseControlWindow::put_Width

CBaseControlWindow 클래스

윈도우의 폭을 설정한다.

구문

HRESULT put_Width(
long Width
);

파라미터

Width
픽셀 단위의 새로운 윈도우의 폭.

반환값

HRESULT 값을 돌려준다.

주의

윈도우는 데스크탑상에 위치 좌표를 가진다. 이것은 픽셀 단위의 4 개의 좌표 (좌, 상, 우, 하)에 의해 나타내진다. OLE 에 의해 자동화되는 인터페이스에서는, 보통, 좌, 상, 폭, 및 높이로 이 정도치좌표를 나타낸다. 이것은 DirectShow 로 채용되고 있는 규칙이다. 좌표는 모두 픽셀 단위로 나타내져 좌표가 변경되면(자) 윈도우가 즉석에서 갱신된다.

왼쪽 또는 위에의 좌표를 설정 하면, 윈도우는 각각 왼쪽 또는 위로 이동한다. 이러한 좌표는 윈도우의 폭이나 높이에는 영향을 주지 않는다. 같이 폭 및 높이의 설정은 왼쪽 및 위에의 좌표에는 영향을 주지 않는다.

CBaseControlWindow::put_WindowState

CBaseControlWindow 클래스

윈도우 상태를 설정한다.

구문

HRESULT put_WindowState(
long WindowState
);

파라미터

WindowState
새로운 윈도우 상태.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, Microsoft Win32 ShowWindow 함수와 같은 파라미터 (WS_SHOWNORMAL, WS_SHOWMINNOACTIVATE, 및 WS_SHOWMAXIMIZED 등)를 취한다.

CBaseControlWindow::put_WindowStyle

CBaseControlWindow 클래스

표준적인 Windows 베이스의 스타일을 설정한다.

구문

HRESULT put_WindowStyle(
long WindowStyle
);

파라미터

WindowStyle
새로운 윈도우의 스타일.

반환값

HRESULT 값을 돌려준다.

주의

윈도우 스타일을 변경하는 경우는 주의가 필요하다. 대부분의 경우, 어플리케이션은 현재의 스타일을 취득해, 비트를 추가 또는 부적절한 비트를 삭제해야 한다. 이 순서에 의해, Windows® 에 의해 사용되는 다양한 내부 윈도우 스타일을 그대로 해 둘 수가 있다.

CBaseControlWindow::put_WindowStyleEx

CBaseControlWindow 클래스

컨트롤 윈도우의 스타일을 설정한다.

구문

HRESULT put_WindowStyleEx(
long WindowStyleEx
);

파라미터

WindowStyleEx
[in] 컨트롤 윈도우의 스타일을 설정하는 값.

반환값

NOERROR 를 돌려준다.

주의

이 메소드는, EX (확장) 윈도우 스타일을 사용한다. 확장 윈도우 스타일의 상세한 것에 대하여는, Microsoft Win32 의 함수 「CreateWindowEx 」를 참조할것. 윈도우 스타일을 변경하려면 , 현재의 윈도우 스타일을 취득해, 다음에 필요한 비트 필드를 추가 또는 삭제한다.

이하의 윈도우 스타일은 유효하지 않기 때문에, 사용해서는 안 된다.

  • WS_DISABLED
  • WS_HSCROLL
  • WS_ICONIC
  • WS_MAXIMIZE
  • WS_MINIMIZE
  • WS_HSCROLL

여기에 나타나고 있는 일부의 예외를 제외해, 사용 가능한 플래그는 Win32 CreateWindow 함수로 사용할 수 있는 플래그와 같다.

CBaseControlWindow::SetControlWindowPin

CBaseControlWindow 클래스

동기 해야 하는 핀을 설정한다.

구문

void SetControlWindowPin(
CBasePin *pPin
);

파라미터

pPin
인터페이스가 동기 하는 핀에의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는,m_pPin 변수를 pPin 파라미터에 동일해지도록(듯이) 설정한다. constructor　 　 으로 설명한 것처럼, 이 인터페이스는, 필터가 정상적으로 접속되었을 경우에게만 호출할 수가 있다. 오브젝트는, 이 멤버 함수에 의해 동기 되는 핀에게 건네진다. 대부분의 경우, 인터페이스 메소드가 불려 갔을 때에 핀이 접속되고 있는지 어떤지를 판단해, 실패했을 경우는 VFW_E_NOT_CONNECTED 를 돌려준다.

CBaseControlWindow::SetWindowForeground

CBaseControlWindow 클래스

비디오 윈도우를 foreground로 이동해, 옵션으로 포커스를 준다.

구문

HRESULT SetWindowForeground(
long Focus
);

파라미터

Focus
비디오 윈도우가 포커스를 받을지 어떨지를 지정하는 값. 값이 -1 의 경우, 윈도우에 포커스가 주어진다. 0 의 경우, 포커스는 주어지지 않는다.

반환값

다음의 몇개의 값을 돌려준다.
NOERROR | 메소드가 성공했다.
E_INVALIDARG | Focus 가 -1 또는 0 은 아니다.
VFW_E_NOT_CONNECTED | 현재의 필터가, 완전한 필터 그래프에 접속되어 있지 않다.

CBaseControlWindow::SetWindowPosition

CBaseControlWindow 클래스

데스크탑 위에의 윈도우의 위치를 설정한다.

구문

HRESULT SetWindowPosition(
long Left,
long Top,
long Width,
long Height
);

파라미터

Left
새로운 왼쪽의 좌표.
Top
새로운 위에의 좌표.
Width
윈도우의 폭.
Height
윈도우의 높이.

반환값

HRESULT 값을 돌려준다.


CBaseDispatch 클래스

CBaseDispatch 클래스의 계층

IDispatch 인터페이스를 이행 하는 base class.

선언 : Ctlutil.h

이 클래스는 DirectShow 타입 라이브러리가 공개하는 오토메이션 호환 인터페이스 QuartzTypeLib 의 지원으로 한정되고 있다. 예를 들어,CMediaControl 와 CMediaPosition 클래스는 CBaseDispatch 을 사용해 각각 IMediaControl 와 IMediaPosition 를 이행 한다. 이 제한에 의해,CBaseDispatch 를 자신의 필터를 직접 사용할 이유는 없다.

이 클래스를 사용하려면 , 다음과 같이 한다 :

  • IDispatch 를 지원 하는 새로운 클래스를 선언.
  • CBaseDispatch 타입의 프라이빗 멤버 변수를 새로운 클래스에게 준다.
  • IDispatch 메소드를 이행. IDispatch 메소드내에서,CBaseDispatch 메소드를 호출한다.

상세한 것에 대하여는, Ctlutil.h 에 선언되고 있는 샘플 클래스의 원시 코드를 참조할것.

IDispatch 메소드의 상세한 것에 대하여는, Microsoft® Platform SDK 에 포함되는 COM 문서를 참조할것.

Public 메소드
CBaseDispatch | constructor 메소드.
~CBaseDispatch | 소멸자 메소드.
GetIDsOfNames | DISPID 에 대응하는 일련의 이름의 맵.
GetTypeInfo | 오브젝트의 타입 정보를 취득, 이것은 인터페이스의 타입 정보를 다음에 취득할 때에 이용된다.
GetTypeInfoCount | 오브젝트가 제공하는 타입 정보 인터페이스의 수를 취득.

CBaseDispatch::CBaseDispatch

CBaseDispatch 클래스

constructor　 　 메소드.

구문

CBaseDispatch(void);

CBaseDispatch::~CBaseDispatch

CBaseDispatch 클래스

소멸자 메소드.

구문

~CBaseDispatch(void);

CBaseDispatch::GetIDsOfNames

CBaseDispatch 클래스

DISPID 에 대응하는 일련의 이름의 맵.

구문

HRESULT GetIDsOfNames(
    REFIID riid,
    OLECHAR **rgszNames,
    UINT cNames,
    LCID lcid,
    DISPID *rgdispid
);

파라미터

riid
인터페이스를 지정하는 인터페이스 ID (IID)에의 참조.
rgszNames
맵 되는 이름을 포함한 와이드 캐릭터 라인의 주소.
cNames
rgszNames 파라미터에 의해 주어지는 배열의 사이즈.
lcid
이름을 해석하는 로케일 문맥. NULL 가 유효.
rgdispid
DISPID 를 취득하는 배열의 포인터. 취득한 각 요소는 rgszNames 파라미터에게 건네진 각 이름에 대응하는 ID.

반환값

HRESULT 값을 돌려준다. 다음의 어느쪽이든을 포함한다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
DISP_E_UNKNOWNNAME | 1 개(살) 혹은 그 이상의 이름이 불명했다. O

주의

이 메소드는 IDispatch::GetIDsOfNames 메소드와 같이 동작하지만,riid 파라미터에 DISPID 를 취득하는 인터페이스를 지정한다. (IDispatch 판에서는,riid 는 미사용. )

이 메소드가 DISP_E_UNKNOWNNAME 를 돌려줄 때, 돌아간 DISPID 는 길의 이름에 대응하는 엔트리로서 DISPID_UNKNOWN 를 포함한다.

CBaseDispatch::GetTypeInfo

CBaseDispatch 클래스

오브젝트의 타입 정보를 취득, 이것은 인터페이스의 타입 정보를 다음에 취득할 때에 이용된다.

구문

HRESULT GetTypeInfo(
    REFIID riid,
    UINT itinfo,
    LCID lcid,
    ITypeInfo **pptinfo
);

파라미터

riid
인터페이스를 지정하는 인터페이스 ID (IID)에의 참조.
itinfo
돌려주는 인터페이스 정보. 반드시 제로.
lcid
로케일 ID.
pptinfo
ITypeInfo 포인터를 취득하는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 다음의 어느쪽이든을 포함한다.

S_OK | 성공.
E_POINTER | Null 포인터 인수.
TYPE_E_ELEMENTNOTFOUND | itinfo 파라미터가 제로는 아니다.

주의

이 메소드는 IDispatch::GetTypeInfo 메소드와 같이 동작한다. 그러나 riid 파라미터가 추가되고 있는, 이것에는 취득하는 타입 정보의 인터페이스를 지정한다.

CBaseDispatch::GetTypeInfoCount

CBaseDispatch 클래스

오브젝트가 제공하는 타입 정보 인터페이스의 수를 취득.

구문

HRESULT GetTypeInfoCount(
    UINT *pctinfo
);

파라미터

pctinfo
오브젝트가 제공하는 타입 정보 인터페이스의 수를 취득하는 변수에의 포인터. 이 메소드가 돌아갔을 때, 이 값은 1 .

반환값

다음의 1 개가 돌아간다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.


CBaseFilter 클래스

CBaseFilter 클래스의 계층

필터를 이행하기 위한 추상 클래스.

선언 : Amfilter.h

CBaseFilter 를 사용해 필터를 이행 하려면 , 최저한다음의 스텝을 실행해야 한다 :

  • CBaseFilter 로부터 새로운 클래스를 파생한다.
  • 필터의 핀을 정의하는 멤버 변수를 인클루드 한다. 이 핀은 CBasePin 클래스 바싹바싹 주어지지 않으면 안 된다.
  • 필터의 핀을 취득하는 순수 가상 메소드 GetPin 를 오버라이드(override) 한다.
  • 핀의 수를 취득하는 순수 가상 메소드 GetPinCount 를 오버라이드(override) 한다.
  • 미디어 샘플의 생성, 처리, 렌더링 메소드를 제공한다.

CSource 나 CBaseRenderer 이나 CTransformFilter 를 포함한 몇개의 base class가 CBaseFilter 로부터 파생된다. 보통 CBaseFilter 를 사용하는 것보다, 이러한 클래스의 1 개를 지정해 필터를 이행 하는 (분)편이 용이하다.

Protected 멤버 변수
m_State | 필터의 현재 상태.
m_pClock | 필터의 기준 클락에의 포인터.
m_tStart | 스트림 타임 제로에 대응한 기준 클락.
m_clsid | 필터의 클래스 ID (CLSID).
m_pLock | 크리티컬 섹션에의 포인터.
m_pName | 필터명.
m_pGraph | 필터 그래프 매니저에의 포인터.
m_pSink | 필터 그래프 매니저의 IMediaEventSink 인터페이스에의 포인터.
m_PinVersion | 이 필터의 일련의 핀의 현재의 버젼.
Public 메소드
CBaseFilter | constructor 메소드.
~CBaseFilter | 소멸자 메소드.
StreamTime | 현재의 스트림 타임을 취득. 가상.
IsActive | 필터가 지금 액티브한가 어떤가(실행중이나 포즈가)를 결정.
IsStopped | 필터가 현재 정지하고 있을지 어떨지를 결정.
NotifyEvent | 이벤트 통지를 필터 그래프 매니저에 보낸다.
GetFilterGraph | 필터 그래프 매니저에의 포인터를 취득.
ReconnectPin | 기존의 핀 접속을 부수어, 지정한 미디어 핀을 사용해, 같은 핀에 그것을 재접속한다.
GetPinVersion | 이 필터의 일련의 핀의 버젼수를 취득. 가상.
IncrementPinVersion | 일련의 핀의 버젼수를 인크리먼트(increment).
GetSetupData | 필터에 대한 등록 데이터를 취득. 가상.
Pure Virtual 메소드
GetPinCount | 핀의 수를 취득.
GetPin | 핀을 취득.
IPersist 메소드
GetClassID | 클래스 ID 를 취득.
IMediaFilter 메소드
GetState | 필터 상태(실행중인가 포즈인지)를 취득.
SetSyncSource | 필터의 기준 클락을 세트.
GetSyncSource | 필터가 사용하고 있는 기준 클락을 취득.
Stop | 필터를 정지.
Pause | 필터를 포즈.
Run | 필터를 실행.
IBaseFilter 메소드
EnumPins | 필터의 핀을 열거한다.
FindPin | 지정한 ID 의 필터를 취득한다.
QueryFilterInfo | 필터에 대한 정보를 취득한다.
JoinFilterGraph | 필터에 필터 그래프에 참가한, 혹은 필터 그래프를 떨어진 것을 통지한다.
QueryVendorInfo | 벤더 정보를 포함한 캐릭터 라인을 취득.
IAMovieSetup 메소드
Register | 레지스트리에 필터를 추가.
Unregister | 레지스트리로부터 필터를 삭제.

CBaseFilter.m_State

CBaseFilter 클래스

필터의 현재 상태.

구문

FILTER_STATE m_State;

CBaseFilter.m_pClock

CBaseFilter 클래스

필터의 기준 클락에의 포인터.

구문

IReferenceClock *m_pClock;

CBaseFilter.m_tStart

CBaseFilter 클래스

스트림 타임 0 에 대응한 기준 클락.

구문

CRefTime m_tStart;

CBaseFilter.m_clsid

CBaseFilter 클래스

필터의 클래스 ID (CLSID).

구문

CLSID m_clsid;

CBaseFilter.m_pLock

CBaseFilter 클래스

크리티컬 섹션에의 포인터.

구문

CCritSec *m_pLock;

주의

상태 이행중 혹은 있는 메소드가 복수의 조작으로 그 상태에 액세스 하고 있을 때, 이 크리티컬 섹션을 보관 유지한다. base class에서는 이하의 메소드로 크리티컬 섹션을 보관 유지한다 :

  • FindPin
  • GetSyncSource
  • JoinFilterGraph
  • IsActive
  • SetSyncSource
  • Pause
  • Run
  • Stop

스트리밍 조작(즉, 샘플을 스트리밍 필터에 출력하고 있다)이라고 해 이 크리티컬 섹션을 보관 유지해서는 안 된다 . 다른 크리티컬 섹션을 사용해 스트림그 조작을 계속한다. 그렇게 하지 않으면 데드 록이 일어날 수 있는.

CBaseFilter.m_pName

CBaseFilter 클래스

필터명.

구문

WCHAR *m_pName;

CBaseFilter.m_pGraph

CBaseFilter 클래스

필터 그래프 매니저에의 포인터.

구문

IFilterGraph *m_pGraph;

CBaseFilter.m_pSink

CBaseFilter 클래스

필터 그래프 매니저의 IMediaEventSink 인터페이스에의 포인터.

구문

IMediaEventSink *m_pSink;

CBaseFilter.m_PinVersion

CBaseFilter 클래스

이 필터의 일련의 핀의 현재의 버젼. 상세한 것에 대하여는, 「GetPinVersion 」를 참조할것.

구문

LONG m_PinVersion;

CBaseFilter::CBaseFilter

CBaseFilter 클래스

constructor　 　 메소드.

구문

CBaseFilter(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    CCritSec *pLock,
    REFCLSID clsid
);

파라미터

pName
디버그 목적으로 사용하는, 필터의 이름을 포함한 캐릭터 라인에의 포인터.
pUnk
오브젝트의 소유자에게로의 포인터. 이 오브젝트가 집성 되고 있다면, 집성 된 오브젝트의 IUnknown 인터페이스를 건네준다. 그 이외에서는 이 파라미터를 NULL 로 설정한다.
pLock
상태 변화를 계속하는 CCritSec 락에의 포인터.
clsid
오브젝트의 클래스 ID.

주의

크리티컬 섹션 오브젝트에 대해서는, 보통다음의 어느 쪽인지를 실시한다 :

  • CBaseFilter 와 CCritSec 의 양쪽 모두를 주는 클래스를 파생. pLock 에 this 포인터를 건네준다.
  • CBaseFilter 를 주어CCritSec 멤버 변수를 포함한 클래스를 파생. pLock 에는 그 변수의 주소를 건네준다.

CBaseFilter::~CBaseFilter

CBaseFilter 클래스

소멸자 메소드.

구문

CBaseFilter(void);

주의

삭제하기 전에 필터를 반드시 정지시키는 것.

CBaseFilter::EnumPins

CBaseFilter 클래스

필터의 핀을 열거한다. IBaseFilter::EnumPins 메소드의 이행.

구문

HRESULT EnumPins(
    IEnumPins **ppEnum
);

파라미터

ppEnum
IEnumPins 인터페이스에의 포인터를 취득하는 변수의 주소.

반환값

다음의 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는 CEnumPins base class의 인터페이스를 생성 해,IEnumPins 타입의 그 오브젝트의 포인터를 돌려준다. 이 메소드가 성공하면(자),IEnumPins 인터페이스는 미처리의 참조 카운트를 가진다. 해방시에는 주의가 필요하다.

CBaseFilter::FindPin

CBaseFilter 클래스

지정한 ID 로 핀을 취득. IBaseFilter::FindPin 메소드의 이행.

구문

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

파라미터

Id
핀을 식별하는 정수, NULL 로 끝나는 Unicode™ 캐릭터 라인의 포인터.
ppPin
핀의 IPin 인터페이스에의 포인터를 취득하는 변수의 주소.

반환값

다음의 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_NOT_FOUND | 적합하는 핀을 찾아낼 수 없었다.

주의

이 메소드는 CBasePin::Name 메소드를 호출해, 각 핀의 이름과 Id 파라미터가 가리키는 캐릭터 라인을 비교한다.

이 메소드가 성공하면(자),IEnumPins 인터페이스는 미처리의 참조 카운트를 가진다. 해방시에는 주의가 필요하다.

CBaseFilter::GetClassID

CBaseFilter 클래스

클래스 ID 를 취득. IPersist::GetClassID 메소드의 이행.

구문

HRESULT GetClassID(
    CLSID *pClsID
    );

파라미터

pClsID
클래스 ID 를 취득하는 변수의 포인터.

반환값

S_OK 혹은 E_POINTER 를 돌려준다.

CBaseFilter::GetFilterGraph

CBaseFilter 클래스

필터 그래프 매니저에의 포인터를 취득.

구문

IFilterGraph *GetFilterGraph(void);

반환값

m_pGraph 의 값을 돌려준다.

CBaseFilter::GetPin

CBaseFilter 클래스

핀을 취득한다.

구문

virtual CBasePin *GetPin(
    int n
) PURE;

파라미터

n
지정된 핀의 수.

반환값

핀을 이행 하는 CBasePin 오브젝트의 포인터를 돌려준다.

주의

상속 클래스는 이 순수 가상 메소드를 이행 해야 한다. 이 필터의 제로로부터 시작되는 n 번째의 핀의 포인터를 돌려준다.

CBaseFilter::GetPinCount

CBaseFilter 클래스

핀의 수를 취득.

구문

virtual int GetPinCount(void) PURE;

반환값

핀의 수를 돌려준다.

주의

상속 클래스는 이 순수 가상 메소드를 이행 해야 한다. 이 필터로 현재 유효한 핀의 수를 돌려준다. 필터는 동적으로 핀을 생성, 삭제할 수 있다.

CBaseFilter::GetPinVersion

CBaseFilter 클래스

필터의 일련의 핀의 버젼수를 취득.

구문

virtual long GetPinVersion(void);

반환값

m_PinVersion 멤버 변수를 돌려준다.

주의

CBaseFilter constructor　 　 은 핀 버젼을 1 으로 초기화한다. base class에서는, 이 수는 변화하지 않는다. 필터가 동적으로 핀을 생성, 삭제 하면 와, 핀이 바뀔 때마다 핀 버젼을 인크리먼트(increment) 해야 하는 것이다. 버젼수를 인크리먼트(increment) 하려면 ,IncrementPinVersion 메소드를 호출하는 것.

CEnumPins 클래스에 의해 이행 되는 핀 열거 오브젝트는 핀 버젼을 사용해, 그 필터와의 동기를 취한다.

CBaseFilter::GetSetupData

CBaseFilter 클래스

필터의 등록 데이터를 취득.

주의 이 메소드는 현재 사용되지 않았다. Register 와 Unregister 메소드에 의해 불려 간다.

구문

virtual LPAMOVIESETUP_FILTER GetSetupData(void);

반환값

필터의 등록 정보를 포함한 AMOVIESETUP_FILTER 구조체에의 포인터를 돌려준다.

주의

base class는 NULL 를 돌려준다.

CBaseFilter::GetState

CBaseFilter 클래스

필터 상태(실행중인가 포즈인지)를 취득. IMediaFilter::GetState 메소드의 이행.

구문

HRESULT GetState(
    DWORD dwMilliSecsTimeout,
    FILTER_STATE *State
);

파라미터

dwMilliSecsTimeout
타임 아웃 간격, 밀리 세컨드.
State
필터 상태를 나타내는 FILTER_STATE 열거형의 멤버를 취득하는 변수의 포인터.

반환값

S_OK 혹은 E_POINTER 를 돌려준다.

주의

base class에서는, 모든 상태 이행은 동기 되어dwMilliSecsTimeout 파라미터는 무시된다. 상속 클래스가 상태 이행을 동기 하려면 , 이 메소드를 오버라이드(override) 해,dwMilliSecsTimeout 밀리 세컨드의 타임 아웃의 사이, 상태 이행을 기다려야 한다.

CBaseFilter::GetSyncSource

CBaseFilter 클래스

필터가 사용하고 있는 기준 클락을 취득. IMediaFilter::GetSyncSource 메소드의 이행.

구문

HRESULT GetSyncSource(
    IReferenceClock **pClock
    );

파라미터

pClock
클락의 IReferenceClock 인터페이스의 포인터를 취득하는 변수의 주소.

반환값

S_OK 혹은 E_POINTER 를 돌려준다.

주의

필터가 기준 클락을 사용하고 있는 경우,*pClock 에는 NULL 가 세트 된다. 이 메소드가 돌아갔을 때,*pClock 가 NULL 이외라면,IReferenceClock 인터페이스가 미처리의 참조 카운트를 가진다. 그 해방시에는 주의가 필요하다.

CBaseFilter::IncrementPinVersion

CBaseFilter 클래스

일련의 핀의 버젼수를 인크리먼트(increment).

구문

void IncrementPinVersion(void);

주의

이 메소드는 m_PinVersion 멤버 변수를 인크리먼트(increment) 한다. 필터가 동적으로 핀을 생성, 삭제하고 말이야 있고, 핀이 변경될 때마다 이 메소드를 호출하는 것. 상세한 것에 대하여는, 「GetPinVersion 」를 참조할것.

CBaseFilter::IsActive

CBaseFilter 클래스

필터가 현재 액티브(실행중 혹은 포즈) 화도인지를 결정한다.

구문

BOOL IsActive(void);

반환값

필터가 포즈 혹은 실행중 때 TRUE 를 돌려주어, 정지하고 있을 때 FALSE 를 돌려준다.

CBaseFilter::IsStopped

CBaseFilter 클래스

필터가 현재 정지하고 있을지 어떨지를 결정.

구문

BOOL IsStopped(void);

반환값

필터가 정지하고 있을 때 TRUE 를 돌려주어, 그 이외라면 FALSE 를 돌려준다.

CBaseFilter::JoinFilterGraph

CBaseFilter 클래스

필터에 필터 그래프에 참가한, 혹은 떨어진 것을 통지한다. IBaseFilter::JoinFilterGraph 메소드의 이행.

구문

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph,
    LPCWSTR pName
);

파라미터

pGraph
필터 그래프 매니저의 IFilterGraph 인터페이스의 포인터, 필터가 떨어졌을 때는 NULL .
pName
필터명을 포함한 Unicode 캐릭터 라인의 [in, string] 포인터.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 m_pGraph 멤버 변수를 pGraph 에 동일하게 설정한다. IMediaEventSink 인터페이스 포인터도 쿼리 해,m_pSink 멤버 변수에 보존한다. 그러나, 이 필터는 이러한 인터페이스의 참조 카운트를 보관 유지하지 않는다. 필터 그래프 매니저는 필터의 참조 카운트를 보관 유지하므로, 이 조작은 반복해 참조 카운트를 생성 하게 된다.

이 메소드는 pName 에 의해 지정된 캐릭터 라인을 m_pName 멤버 변수에 카피한다.

CBaseFilter::NotifyEvent

CBaseFilter 클래스

필터 그래프 매니저에 이벤트 통지를 보낸다.

구문

HRESULT NotifyEvent(
    long EventCode,
    LONG_PTR EventParam1,
    LONG_PTR EventParam2
);

파라미터

EventCode
이벤트 통지 코드.
EventParam1
이벤트의 최초의 파라미터.
EventParam2
이벤트의 2 번째의 파라미터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_FALSE | 필터 그래프 매니저는 이벤트 통지를 받지 않았다.
S_OK | 성공.
E_NOTIMPL | 필터는 IMediaEventSink 인터페이스에의 포인터를 가지고 있지 않다.

주의

통지 코드와 파라미터값의 리스트에 대해서는, 「이벤트 통지 코드」를 참조할것.

base class에서는, 이벤트 코드가 EC_COMPLETE 라면, 메소드는 EventParam2 파라미터를 필터의 IBaseFilter 인터페이스에의 포인터로 설정한다.

CBaseFilter::Pause

CBaseFilter 클래스

필터를 포즈로 한다. IMediaFilter::Pause 메소드의 이행.

구문

HRESULT Pause(void);

반환값

성공하면 S_OK 를 돌려주는, 그 이외의 경우 에러의 원인을 포함한 HRESULT 값을 돌려준다.

주의

이 메소드는 핀에 접속한 각 필터 마다 CBasePin::Active 메소드를 호출한다.

CBaseFilter::QueryFilterInfo

CBaseFilter 클래스

필터의 정보를 취득. IBaseFilter::QueryFilterInfo 메소드의 이행.

구문

HRESULT QueryFilterInfo(
    FILTER_INFO *pInfo
);

파라미터

pInfo
FILTER_INFO 구조체에의 포인터.

반환값

S_OK 혹은 E_POINTER 를 돌려준다.

주의

이 메소드는 m_pName 멤버 변수로부터, FILTER_INFO 구조체의 achName 멤버에 필터의 이름을 카피한다. m_pName 가 NULL 때, 메소드는 achName 를 L'\0' 로 설정한다.

이 메소드는 FILTER_INFO 구조체의 achName 멤버를 m_pGraph 멤버 변수와 동일하게 해, 참조 카운트를 인크리먼트(increment) 한다. 호출원래는 그 인터페이스를 해방해야 한다.

CBaseFilter::QueryVendorInfo

CBaseFilter 클래스

벤더 정보를 포함한 캐릭터 라인을 취득.

구문

HRESULT QueryVendorInfo(
    LPWSTR *pVendorInfo
    );

파라미터

pVendorInfo
벤더 정보를 포함한 와이드 캐릭터 라인의 포인터를 취득하는 변수의 주소.

반환값

E_NOTIMPL 를 돌려준다.

주의

필터의 벤더 정보를 제공해, 이 메소드를 오버라이드(override) 한다. 이 메소드를 이행 할 때,CoTaskMemAlloc 함수를 사용해 캐릭터 라인의 메모리 할당을 실시한다. 호출원래는 CoTaskMemFree 함수를 호출할 책임을 가진다.

CBaseFilter::ReconnectPin

CBaseFilter 클래스

기존의 핀 접속을 부수어, 지정한 미디어 핀을 사용해, 같은 핀에 그것을 재접속한다.

구문

HRESULT ReconnectPin(
    IPin *pPin,
    AM_MEDIA_TYPE const *pmt
);

파라미터

pPin
핀의 IPin 인터페이스에의 포인터.
pmt
미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터 혹은 NULL .

반환값

HRESULT 값을 돌려준다. 이하의 몇개의 값을 돌려준다.

S_OK | 성공.
E_NOINTERFACE | m_pGraph 멤버 변수는 NULL.

주의

이 메소드는 필터 그래프 매니저의 IFilterGraph2::ReconnectEx 메소드를 호출한다. IFilterGraph2 가 무효인들 , 메소드는 IFilterGraph::Reconnect 를 호출한다.

CBaseFilter::Register

CBaseFilter 클래스

필터를 레지스트리에 추가한다. IAMovieSetup::Register 메소드의 이행.

주의 이 IAMovieSetup 인터페이스는 사용되지 않았다. 새로운 필터는 IAMovieSetup 를 요구하지 않는 AMovieDllRegisterServer2 함수를 사용해 레지스트리에 추가해야 한다. 상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

구문

HRESULT Register(void);

반환값

이하의 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
S_FALSE | 유효한 레지스트리 정보는 없다.

주의

이 메소드는 필터의 레지스트리 등록에,AMovieSetupRegisterFilter 함수를 호출한다.

CBaseFilter::Run

CBaseFilter 클래스

필터를 실행한다. IMediaFilter::Run 메소드의 이행.

구문

HRESULT Run(
    REFERENCE_TIME tStart
);

파라미터

tStart
스트림 타임 0 에 대응하는 기준 타임.

반환값

성공하면 S_OK 를 돌려주는, 그 이외의 경우 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

필터가 정지되면(자), 이 메소드는 CBaseFilter::Pause 메소드를 호출해 필터를 포즈로 한다. 다음에 필터에 접속하고 있는 각 핀의CBasePin::Run 메소드를 호출한다. 마지막으로,m_State 멤버 변수를State_Running 로 설정한다.

스트림 타임은 현재의 기준 시간 빼는 tStart 로 계산된다. 타임 스탬프 제로의 미디어 샘플은 tStart 타임에 렌더링 된다.

CBaseFilter::SetSyncSource

CBaseFilter 클래스

필터의 기준 클락을 세트. IMediaFilter::SetSyncSource 메소드의 이행.

구문

HRESULT SetSyncSource(
    IReferenceClock *pClock
    );

파라미터

pClock
클락의 IReferenceClock 인터페이스에의 포인터, 혹은 NULL .

반환값

S_OK 를 돌려준다.

CBaseFilter::Stop

CBaseFilter 클래스

필터를 정지한다. IMediaFilter::Stop 메소드의 이행.

구문

HRESULT Stop(void);

반환값

성공하면(자) S_OK 를 돌려주는, 그 이외의 경우 에러의 원인을 포함한 HRESULT 값을 돌려준다.

주의

이 메소드는 필터에 접속하고 있는 각 핀의 CBasePin::Inactive 메소드를 호출한다.

CBaseFilter::StreamTime

CBaseFilter 클래스

현재의 스트림 타임을 취득.

구문

virtual HRESULT StreamTime(
    CRefTime& rtStream
);

파라미터

rtStream
현재의 스트림 타임을 받는 CRefTime 오브젝트에의 참조.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NO_CLOCK | 유효한 기준 클락은 없다.

주의

스트림 타임은 현재의(기준 클락으로 주어진다) 기준 타임 당기는 (m_tStart 에 의해 지정된다) 시작 타임으로서 정의된다. 미디어 샘플의 타임 스탬프 는 레다링시에 스트림 타임을 지정한다. 현재의 스트림 타임보다 작은 타임 스탬프를 가지는 샘플이 아직 렌더링 되지 않았어들 , 그것은 늦는다.

CBaseFilter::Unregister

CBaseFilter 클래스

레지스트리로부터 필터를 삭제한다. IAMovieSetup::Unregister 메소드의 이행.

주의 이 IAMovieSetup 인터페이스는 사용되지 않았다. 새로운 필터는 레지스트리의 삭제에 AMovieDllRegisterServer2 함수를 사용 한다. 상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

구문

HRESULT Unregister(void);

반환값

성공이라면 S_OK 를 돌려주는, 그 이외의 경우 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는AMovieSetupRegisterFilter 함수를 호출해 필터를 레지스트리로부터 삭제한다.


CBaseInputPin 클래스

CBaseInputPin 클래스의 계층

입력 핀을 이행 하는 추상 base class

선언 : Amfilter.h

이 클래스는 IMemInputPin 인터페이스의 지원을 추가해, 한층 더 CBasePin 에 의해 제공되는 IPin 인터페이스의 지원을 추가한다.

이 클래스를 사용하려면 , 새로운 클래스를 파생해, 적어도 이하의 메소드에 오버라이드(override) 한다.

  • BeginFlush
  • EndFlush
  • Receive
Protected 멤버 변수
m_pAllocator | 메모리 allocater에의 포인터.
m_bReadOnly | allocater가 읽어들여 전용 미디어 샘플을 취급할지 어떨지를 나타내는 플래그.
m_bFlushing | 현재 플래시 하고 있는 핀인가 어떤가를 나타내는 플래그.
m_SampleProps | 최신 샘플의 프로퍼티.
Public 메소드
CBaseInputPin | constructor 메소드.
~CBaseInputPin | 소멸자 메소드.
BreakConnect | 접속으로부터 핀을 해방한다.
IsReadOnly | allocater가 읽어들여 전용 미디어 샘플을 사용할지 어떨지 확인한다.
IsFlushing | 필터가 현재 플래시 하고 있을지 어떨지 확인한다.
CheckStreaming | 핀이 샘플을 받아들일지 어떨지 결정한다. 가상.
PassNotify | 품질 컨트롤 메세지를 적절한 오브젝트에 보낸다.
Inactive | 핀에 필터가 현재 액티브하지 않으면 통지한다. 가상.
SampleProps | 최신 샘플의 프로퍼티를 취득.
IPin 메소드
BeginFlush | 플래시 처리를 시작 한다.
EndFlush | 플래시 처리를 종료한다.
IMemInputPin 메소드
GetAllocator | 이 핀이 제출한 메모리 allocater를 취득한다.
NotifyAllocator | 접속의 allocater를 지정한다.
GetAllocatorRequirements | 입력 핀이 요구한 allocater 프로퍼티를 취득한다.
Receive | 스트림내의 다음의 미디어 샘플을 취득한다.
ReceiveMultiple | 스트림내의 복수의 샘플을 취득한다.
ReceiveCanBlock | Receive 메소드에의 호출이 블록이 될지 어떨지를 결정한다.
IQualityControl 메소드
Notify | 품질 컨트롤 메세지를 취득한다.

CBaseInputPin.m_pAllocator

CBaseInputPin 클래스

메모리 allocater에의 포인터.

구문

IMemAllocator *m_pAllocator;

CBaseInputPin.m_bReadOnly

CBaseInputPin 클래스

allocater가 읽어들여 전용 미디어 샘플을 취급할지 어떨지를 나타내는 플래그. TRUE 라면 allocater는 읽어들여 전용 샘플을 취급한다.

구문

BYTE m_bReadOnly;

CBaseInputPin.m_bFlushing

CBaseInputPin 클래스

현재 플래시 하고 있는 핀인가 어떤가를 나타내는 플래그. TRUE 라면 핀은 플래시 하고 있다.

구문

BYTE m_bFlushing;

CBaseInputPin.m_SampleProps

CBaseInputPin 클래스

최신 샘플의 프로퍼티.

구문

AM_SAMPLE2_PROPERTIES m_SampleProps;

CBaseInputPin::BeginFlush

CBaseInputPin 클래스

플래시 처리를 시작 한다. IPin::BeginFlush 메소드의 이행.

구문

HRESULT BeginFlush(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 m_bFlushing 플래그를 TRUE 로 해, Receive 메소드에 더 이상의 샘플을 거절시킨다.

상속 클래스는 이 메소드를 오버라이드(override) 해, 다음의 스텝을 실행해야 한다.

  1. 다운 스트림 입력 핀의 IPin::BeginFlush 메소드를 호출한다. 핀이 아직 미디어 샘플 다운 스트림을 출력하고 있지 않다면, 이 스텝은 생략 할 수 있다. 출력 핀이 CBaseOutputPin 메소드로부터 출력되고 있는 경우는, CBaseOutputPin::DeliverBeginFlush 를 호출할 수 있다.
  2. base class 메소드를 호출한다.
  3. 큐에 있는 데이터의 폐기를 시작 한다.
  4. 블록 되고 있는 Receive 메소드에의 호출로부터 돌아온다.

CBaseInputPin::BreakConnect

CBaseInputPin 클래스

접속으로부터 핀을 해방.

구문

HRESULT BreakConnect(void);

반환값

성공하면 S_OK 를 돌려주는, 그 이외의 경우 에러의 원인을 포함한 HRESULT 값을 돌려준다.

주의

이 메소드는 CBasePin::BreakConnect 메소드를 오버라이드(override) 한다. allocater를 데코밋트로 해,IMemAllocator 인터페이스를 해방한다.

이 메소드를 오버라이드(override) 할 때는, 오버라이드(override) 하는 메소드로부터 base class 메소드를 호출하는 것. 그렇게 하지 않으면 메모리 누수를 일으킬 가능성이 있다.

CBaseInputPin::CBaseInputPin

CBaseInputPin 클래스

constructor　 　 메소드

구문

CBaseInputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pPinName
);

파라미터

pObjectName
오브젝트의 디버그용의 이름이 들어가는 캐릭터 라인. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pFilter
이 핀을 생성 한 필터에의 포인터.
pLock
CCritSec 락에의 포인터로, 상태 이행을 계속하기 위해서 사용한다. 이것은 필터 락 CBaseFilter.m_pLock 와 같은 크리티컬 섹션이 될 수 있다.
phr
메소드의 성공·실패를 나타내는 HRESULT 값을 취득하는 변수의 포인터.
pPinName
(핀 ID 로서도 사용된다) 핀명이 들어가는 Unicode™ 캐릭터 라인.

주의

모든 파라미터는 직접 CBasePin constructor　 　 에 보내진다.

CBaseInputPin::~CBaseInputPin

CBaseInputPin 클래스

소멸자 메소드.

구문

~CBaseInputPin(void);

CBaseInputPin::CheckStreaming

CBaseInputPin 클래스

핀이 샘플을 받아들일지 어떨지 결정한다.

구문

virtual HRESULT CheckStreaming(void);

반환값

다음 표에 나타내는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
S_FALSE | 핀은 현재 플래시 하고 있다.
VFW_E_RUNTIME_ERROR | 런타임 에러가 일어났다.
VFW_E_WRONG_STATE | 핀은 정지되었다.

주의

상속 클래스는 이 메소드를 오버라이드(override) 해 더욱 체크를 실시할 수가 있다. 오버라이드(override) 하는 메소드에서는 또 base class의 이행을 호출한다.

CBasePin::Receive 메소드는 이 메소드를 호출한다. 같이CBasePin::EndOfStream 메소드를 오버라이드(override) 해, 이 메소드를 호출해야 하는 것이다.

CBaseInputPin::EndFlush

CBaseInputPin 클래스

플래시 처리를 종료한다. IPin::EndFlush 메소드의 이행.

구문

HRESULT EndFlush(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 m_bFlushing 플래그를 TRUE 에 세트 해,Receive 메소드에 샘플을 받아들이게 한다.

상속 클래스는 이 메소드를 오버라이드(override) 해, 다음의 스텝을 실행해야 한다.

  1. 버퍼에 있는 데이터를 해방해, 모든 큐에 있는 샘플을 폐기.
  2. 보류의EC_COMPLETE 통지를 클리어.
  3. base class 메소드를 호출한다.
  4. 다운 스트림 입력 핀의 IPin::EndFlush 를 호출한다. 그 핀이 아직 미디어 샘플 다운 스트림을 아직 배웅하지 않은 경우, 이 스텝은 스킵 할 수 있다. 출력 핀이 CBaseOutputPin 클래스로부터 파생되고 있다면,CBaseOutputPin::DeliverEndFlush 메소드를 호출할 수 있다.

CBaseInputPin::GetAllocator

CBaseInputPin 클래스

이 핀이 제출한 메모리 allocater를 취득한다. IMemInputPin::GetAllocator 메소드의 이행.

구문

HRESULT GetAllocator(
    IMemAllocator **ppAllocator
);

파라미터

ppAllocator
allocater의 IMemAllocator 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공이라면 S_OK 를 돌려주는, 그 이외의 경우 CoCreateInstance 로부터 에러 코드를 돌려준다.

주의

이 메소드는 CMemAllocator 오브젝트를 생성 한다. 필터가 다운 스트림 핀으로부터의 allocater 혹은 커스텀 allocater를 사용한다면, 이 메소드를 오버라이드(override) 해야 한다.

메소드가 성공하면(자),IMemAllocator 인터페이스는 미처리의 참조 카운트를 가진다. 해방시에는 주의가 필요.

CBaseInputPin::GetAllocatorRequirements

CBaseInputPin 클래스

입력 핀이 요구한 allocater 프로퍼티를 취득한다.

구문

HRESULT GetAllocatorRequirements(
    ALLOCATOR_PROPERTIES *pProps
);

파라미터

pProps
요구로 채워진 ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

E_NOTIMPL 를 돌려준다.

주의

출력 핀이 메모리 allocater를 초기화 하면 와, 이 메소드를 호출해 입력 핀이 버퍼 요구를 가지고 있을지 어떨지를 조사할 수가 있다. 상세한 것에 대하여는, 「CBaseOutputPin::DecideAllocator 」를 참조할것.

이 메소드의 이행은 임의이다. 필터가 고유의 alignment나 전치값요구를 가지고 있다면, 이 메소드를 오버라이드(override) 해야 한다.

CBaseInputPin::Inactive

CBaseInputPin 클래스

핀에 필터가 현재 액티브하지 않으면 통지한다.

구문

HRESULT Inactive(void);

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NO_ALLOCATOR | 유효한 메모리 allocater가 없다.

주의

이 메소드는 CBasePin::Inactive 메소드를 오버라이드(override) 한다. 그것은 IMemAllocator::Decommit 메소드를 호출해, 메모리 allocater를 데코밋트로 한다.

이 메소드를 오버라이드(override) 한다면, 그 오버라이드(override) 메소드로부터 base class 메소드를 호출하는 것.

CBaseInputPin::IsFlushing

CBaseInputPin 클래스

필터가 현재 플래시 하고 있을지 어떨지 확인한다.

구문

BOOL IsFlushing(void);

반환값

m_bFlushing 멤버 변수를 돌려준다.

CBaseInputPin::IsReadOnly

CBaseInputPin 클래스

allocater가 읽어들여 전용 미디어 샘플인가 어떤가 확인한다.

구문

BOOL IsReadOnly(void);

반환값

m_bReadOnly 멤버 변수를 돌려준다.

CBaseInputPin::Notify

CBaseInputPin 클래스

품질 변경이 요구된 것을 핀에 알린다. IQualityControl::Notify 메소드의 이행.

구문

HRESULT Notify(
    IBaseFilter *pSelf,
    Quality q
);

파라미터

pSelf
품질 컨트롤 메세지를 보내고 있는 필터에의 포인터.
q
품질 컨트롤 메세지를 포함한 Quality 구조체.

반환값

S_OK 를 돌려준다.

주의

보통, 필터는 품질 컨트롤 메세지를 업 스트림 출력 핀에 보내, 입력 핀에는 보내지 않는다. 그러므로 이 메소드는 아무것도 하지 않는 경우 이외는 S_OK 를 돌려준다.

상세한 것에 대하여는, 「품질 컨트롤의 관리」를 참조할것.

CBaseInputPin::NotifyAllocator

CBaseInputPin 클래스

접속의 allocater를 지정한다. IMemInputPin::NotifyAllocator 메소드의 이행.

구문

HRESULT NotifyAllocator(
    IMemAllocator *pAllocator,
    BOOL bReadOnly
);

파라미터

pAllocator
allocater의 IMemAllocator 인터페이스에의 포인터.
bReadOnly
이 allocater로부터의 샘플이 읽어들여 전용인가 어떤가를 지정하는 플래그. TRUE 이면 샘플은 읽어들여 전용.

반환값

S_OK 를 돌려준다.

주의

핀이 접속하고 있는 동안, 출력 핀은 allocater를 선택해, 이 메소드를 호출해 입력 핀에 통지한다. 출력 핀은 입력 핀이 IMemInputPin::GetAllocator 메소드로 제공한 allocater를 사용할 수 있다, 혹은 자기 자신의 allocater를 제공할 수 있다.

CBaseInputPin::PassNotify

CBaseInputPin 클래스

품질 컨트롤 메세지를 적절한 오브젝트에 보낸다.

구문

HRESULT PassNotify(
    Quality q
);

파라미터

q
품질 컨트롤 메세지를 포함한 Quality 구조체.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NOT_FOUND | 메세지를 받아들이는 오브젝트를 찾아낼 수 없다.

주의

필터가 품질 컨트롤 메세지를 취급하지 않으면, 이 메소드를 호출하는 것. 이 메소드는 오브젝트의 1 개에 다음의 우선순서로 그 메세지를 보낸다 :

  • IQualityControl::SetSink 가 불려 갔다면, 외부 품질 컨트롤 매니저.
  • 업 스트림 출력 핀.

상세한 것에 대하여는, 「품질 컨트롤의 관리」를 참조할것.

CBaseInputPin::Receive

CBaseInputPin 클래스

스트림중의 다음의 미디어 샘플을 취득. IMemInputPin::Receive 의 이행.

구문

HRESULT Receive(
    IMediaSample *pSample
);

파라미터

pSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 값의 언젠가.

S_OK | 성공.
S_FALSE | 핀은 현재 플래시 하고 있는, 샘플은 거부된다.
E_POINTER | NULL 포인터 인수.
VFW_E_INVALIDMEDIATYPE | 부적절한 미디어 타입.
VFW_E_RUNTIME_ERROR | A 런타임 에러가 발생했다.
VFW_E_WRONG_STATE | 핀은 정지중.

주의

업 스트림 출력 핀은 이 메소드를 호출해, 입력 핀에 샘플을 출력한다. 입력 핀은 다음의 1 개를 실시하지 않으면 안 된다 :

  • 돌아오기 전에 샘플을 처리한다.
  • 돌아와, 워커 thread로 샘플을 처리한다.
  • 샘플을 거부한다.

핀이 워커 thread를 사용해 샘플을 처리한다면, 이 메소드내의 샘플에의 참조 카운트를 추가한다. 이 메소드가 돌아온 다음에, 업 스트림 핀은 샘플을 해방한다. 샘플의 참조 카운트가 제로가 되면(자), 샘플은 재사용을 위해서(때문에) allocater를 돌려준다.

이 메소드는 동기 되어 블록 할 수 있다. 메소드가 블록 하면, 핀의 ReceiveCanBlock 메소드는 S_OK 를 돌려준다.

base class에서는, 이 메소드는 다음의 스텝을 실행한다 :

  1. CheckStreaming 메소드를 호출해, 핀이 샘플을 지금 처리할 수 있는 것을 검증한다. 할 수 없는 경우—예를 들어 핀이 정지중—메소드는 실패한다.
  2. 샘플 프로퍼티를 취득해, 그 포맷이 변경되었는지 어떠했는지를 체크(다음을 참조).
  3. 포맷이 변경이 되었다면, 메소드는 CBasePin::CheckMediaType 메소드를 호출해, 새로운 포맷이 받아들이고 가능한가 어떤가를 조사한다.
  4. 새로운 포맷이 받아들이고 가능하지 않으면, 메소드는 CBasePin::EndOfStream 메소드를 호출해, EC_ERRORABORT 이벤트를 포스트해, 에러 코드를 돌려준다.
  5. 에러가 없는 것이면, 메소드는 S_OK 를 돌려준다.

포맷 변경에 대한 테스트는 다음과 같이 실시한다 :

  • 그 샘플이 IMediaSample2 인터페이스를 지원 한다면,AM_SAMPLE2_PROPERTIES 구조체의 dwSampleFlags 멤버를 체크한다. AM_SAMPLE_TYPECHANGED 플래그가 포함되어 있으면, 포맷은 변경되고 있다.
  • 그렇지 않고,IMediaSample2 샘플을 지원 하고 있지 않으면,IMediaSample::GetMediaType 메소드를 호출한다. 메소드가 비 NULL 값으로 돌아간다면, 포맷은 변경되고 있다.

base class에서는, 이 메소드는 샘플을 처리하지 않는다. 상속 클래스는 이 메소드를 오버라이드(override) 해, 처리를 실행해야 한다(이 결과는 필터에 완전하게 의존한다). 상속 클래스는 base class 메소드를 호출해, 이전에 기술된 에러를 체크해야 한다.

CBaseInputPin::ReceiveCanBlock

CBaseInputPin 클래스

IMemInputPin::Receive 메소드에의 호출이 블록 될지 어떨지를 조사한다. IMemInputPin::ReceiveCanBlock 메소드의 이행.

구문

HRESULT ReceiveCanBlock(void);

반환값

Returns an HRESULT 값을 돌려준다. 다음의 값의 언젠가.

S_FALSE | 핀은 Receive 를 호출해도 블록 하지 않는다.
S_OK | 핀은 Receive 를 호출하면 블록 할 가능성이 있다.

주의

Receive 메소드의 호출이 블록 하지 않으면 보증된다면, S_FALSE 를 돌려준다. 그 이외의 경우는, S_OK 나 에러 코드를 돌려준다. Receive 메소드가 다운 스트림 핀의 Receive 를 호출하면, 다운 스트림 핀은 블록 할 가능성이 있는, ReceiveCanBlock 는 어카운트에 그 팩터를 건네주지 않으면 안 된다.

업 스트림 필터는 이 메소드를 사용해, thread 전략을 결정할 수가 있다. Receive 메소드가 블록 할 가능성이 있다면, 업 스트림 필터는 데이터를 버퍼 하는 워커 thread의 사용을 결정하는 일도 가능하다. 이 전략의 이행에 대해서는 「COutputQueue 클래스」를 참조할것.

base class에서는, 다음중 한쪽이 진정한이라고 하고 이 메소드는 S_OK 를 돌려준다 :

  • 필터가 출력 핀을 가지지 않는다.
  • 이 필터에 접속하는 입력 핀이 블록 할지도 모르면 통지한다.
  • 이 필터에 접속되고 있는 입력 핀이 IMemInputPin 인터페이스를 지원 하지 않는다.

CBaseInputPin::ReceiveMultiple

CBaseInputPin 클래스

스트리밍내의 복수의 샘플을 취득한다. IMemInputPin::ReceiveMultiple 메소드의 이행.

구문

HRESULT ReceiveMultiple(
    IMediaSample **pSamples,
    long nSamples,
    long *nSamplesProcessed
);

파라미터

pSamples
nSamples 사이즈의, 복수의 IMediaSample 포인터의 배열의 주소.
nSamples
처리하는 샘플의 수.
nSamplesProcessed
처리된 샘플의 수를 받는 변수의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
S_FALSE | 핀은 현재 플래시 하고 있는, 샘플은 거부되었다.
E_POINTER | NULL 포인터 인수.
VFW_E_INVALIDMEDIATYPE | 부적절한 미디어 타입.
VFW_E_RUNTIME_ERROR | A 런타임 에러가 일어났다.
VFW_E_WRONG_STATE | 핀은 정지중.

주의

이 메소드는 Receive 메소드와 같게 동작하지만, 샘플의 배열을 받는다. base class에서는, 이 메소드는 배열로 루프 해, 각 샘플에 Receive 를 호출한다. 필터가 샘플의 배치를 한 번에 처리하는 것보다 효과적으로 처리할 수 있다면, 이 함수를 오버라이드(override) 하는 것.

CBaseInputPin::SampleProps

CBaseInputPin 클래스

최신의 샘플의 프로퍼티를 AM_SAMPLE2_PROPERTIES 구조체로서 받는다.

구문

AM_SAMPLE2_PROPERTIES *SampleProps(void);

반환값

m_SampleProps 멤버 변수의 주소를 돌려준다.


CBaseList 클래스

CBaseList 클래스의 계층

추상 리스트의 이행. CBaseList 로부터 파생한 CGenericList 클래스 템플릿은 타입 체크와 CBaseList 클래스보다 단순한 API 를 제공한다.

선언 : Wxlist.h

CBaseList 클래스는 Microsoft® Foundation Classes (MFC) 라이브러리에 있는 CObList 의 다음에 생성 되고 있다. 리스트내의 위치는 POSITION 구조체에 의해 나타난다. 호출원래는 POSITION 구조체의 내부 멤버에 액세스 해서는 안되는, 리스트 노드의 포인터로서 취급해야 한다. 리스트내의 오브젝트의 위치는 오브젝트가 삭제될 때까지 계속해 유효하다.

리스트는 그것을 포함한 오브젝트에 의한 지원을 요구하지 않는다. 스토리지 관리나 오브젝트의 카피는 실시하지 않는다. 오브젝트는 복수의 리스트에 존재 할 수 있다.

이 클래스의 약반수의 메소드는 싱글 오브젝트이다. 이러한 메소드는 메소드명에 I 의 접미말을 가진다. 다른 메소드는 완전한 리스트로서 동작한다. 예를 들어,AddAfter 메소드는 있는 리스트를 다른 리스트에 추가하는, 싱글 오브젝트 조작은 POSITION 값을 돌려주는지, 실패시는 NULL 를 돌려준다. 리스트 조작은 성공시에 TRUE 를, 실패시에 FALSE 를 돌려준다.

Protected 멤버 변수
m_Count | 리스트의 항목수.
m_pFirst | 리스트의 선두 노드에의 포인터.
m_pLast | 리스트의 말미 노드에의 포인터.
Protected 메소드
GetNextI | 지정한 위치의 항목을 취득해, 위치를 진행시킨다.
GetI | 지정한 위치의 항목을 취득한다.
FindI | 지정한 항목을 가지는 최초의 위치를 취득한다.
RemoveHeadI | 리스트의 선두 항목을 삭제한다.
RemoveTailI | 리스트의 말미 항목을 삭제한다.
RemoveI | 지정한 위치의 항목을 삭제한다.
AddTailI | 리스트의 말미에 항목을 추가한다.
AddHeadI | 리스트의 선두에 항목을 추가한다.
AddAfterI | 지정한 위치의 뒤에 항목을 삽입한다.
AddBeforeI | 지정한 위치전에 항목을 삽입한다.
Public 메소드
CBaseList | constructor 메소드.
~CBaseList | 소멸자 메소드.
RemoveAll | 리스트로부터 모든 노드를 삭제한다.
GetHeadPositionI | 리스트의 선두 항목의 위치를 취득한다.
GetTailPositionI | 리스트의 말미 항목의 위치를 취득한다.
GetCountI | 리스트의 항목수를 취득한다.
Next | 리스트의 다음의 위치를 취득한다.
Prev | 리스트의 전의 위치를 취득한다.
AddHead | 이 리스트의 전에 다른 리스트를 삽입한다.
AddTail | 이 리스트의 뒤에 다른 리스트를 추가한다.
AddAfter | 지정한 위치의 뒤에 리스트를 삽입한다.
AddBefore | 지정한 위치전에 리스트를 삽입한다.
MoveToTail | 리스트를 분할해, 전측을 다른 리스트의 마지막에 추가한다.
MoveToHead | 리스트를 분할해, 뒤측을 다른 리스트의 전에 삽입한다.
Reverse | 리스트의 차례를 역전한다.

CBaseList.m_Count

CBaseList 클래스

리스트의 항목수.

구문

LONG m_Count;

CBaseList.m_pFirst

CBaseList 클래스

리스트의 선두 노드에의 포인터.

구문

CNode *m_pFirst;

CBaseList.m_pLast

CBaseList 클래스

리스트의 말미 노드에의 포인터.

구문

CNode *m_pLast;

CBaseList::AddAfter

CBaseList 클래스

지정한 위치의 뒤에 리스트를 삽입한다.

구문

BOOL AddAfter(
    POSITION pos,
    CBaseList *pList
);

파라미터

pos
이 뒤로 리스트를 삽입하는 위치.
pList
삽입하는 리스트에의 포인터.

반환값

성공이라면 TRUE, 그 이외라면 FALSE 를 돌려준다.

주의

pos 파라미터로 지정되는 정보를 포함한 기존의 위치 정보는 유효인 채 남아 버린다. 이 메소드가 실패한다면, 몇개의 항목이 이미 추가된 가능성이 있다.

CBaseList::AddAfterI

CBaseList 클래스

지정한 위치의 뒤에 항목을 삽입한다.

구문

POSITION AddAfterI(
    POSITION pos,
    void *pObj
);

파라미터

pos
이 뒤로 항목을 삽입하는 위치.
pObj
추가하는 항목에의 포인터.

반환값

삽입된 항목의 위치 정보가 돌아간다.

주의

pos 가 NULL 라면, 이 메소드는 리스트의 선두에 항목을 추가했다 ( AddHeadI 메소드를 호출한 것과 같다).

CBaseList::AddBefore

CBaseList 클래스

지정한 위치전에 리스트를 삽입한다.

구문

BOOL AddBefore(
    POSITION pos,
    CBaseList *pList
);

파라미터

pos
일전에 리스트를 삽입하는 위치.
pList
추가하는 리스트에의 포인터.

반환값

성공이라면 TRUE, 그 이외라면 FALSE 를 돌려준다.

주의

pos 파라미터로 지정되는 정보를 포함한 기존의 위치 정보는 유효인 채 남아 버린다. 이 메소드가 실패한다면, 몇개의 항목이 이미 추가된 가능성이 있다.

CBaseList::AddBeforeI

CBaseList 클래스

지정한 위치전에 항목을 삽입한다.

구문

POSITION AddBeforeI(
    POSITION pos,
    void *pObj
);

파라미터

pos
일전에 항목을 삽입하는 위치.
pObj
항목에의 포인터.

반환값

삽입된 항목의 위치 정보가 돌아간다.

주의

pos 가 NULL 인 경우, 이 메소드는 리스트의 말미에 항목을 추가한다 (AddTailI 메소드의 호출과 같다).

CBaseList::AddHead

CBaseList 클래스

이 리스트의 전에 다른 리스트를 삽입한다.

구문

BOOL AddHead(
    CBaseList *pList
);

파라미터

pList
추가하는 항목 리스트에의 포인터.

반환값

성공이라면 TRUE, 그 이외라면 FALSE 를 돌려준다.

주의

메소드가 실패한다면, 몇개의 항목이 이미 리스트에 추가된 가능성이 있다.

CBaseList::AddHeadI

CBaseList 클래스

리스트의 최초로 항목을 추가한다.

구문

POSITION AddHeadI(
    void *pObj
);

파라미터

pObj
항목에의 포인터.

반환값

새로운 선두 위치를 나타내는 POSITION 값을 돌려준다.

주의

메소드가 실패 하면, 반환값은 NULL .

CBaseList::AddTail

CBaseList 클래스

이 리스트의 뒤에 다른 리스트를 추가한다.

구문

BOOL AddTail(
    CBaseList *pList
);

파라미터

pList
추가하는 리스트에의 포인터.

반환값

성공이라면 TRUE, 그 이외라면 FALSE 를 돌려준다.

주의

메소드가 실패한다면, 몇개의 항목이 이미 추가된 가능성이 있다.

CBaseList::AddTailI

CBaseList 클래스

리스트의 끝나에 항목을 추가한다.

구문

POSITION AddTailI(
    void *pObj
);

파라미터

pObj
항목에의 포인터.

반환값

새로운 말미 위치를 나타내는 POSITION 값을 돌려준다.

주의

메소드가 실패 하면, 반환값은 NULL .

CBaseList::CBaseList

CBaseList 클래스

constructor　 　 메소드.

구문

CBaseList(
    TCHAR *pName,
    INT iItems
);

CBaseList(
    TCHAR *pName
);

파라미터

pName
리스트명에의 포인터.
iItems
노드 캐쉬의 사이즈.

주의

효율이기 때문에,CBaseList 클래스는 리스트 노드의 캐쉬를 유지한다. 리스트가 가지는 대체로의 항목수를 알고 있다면, constructor　 　 의 제 1 버젼을 사용해야 한다. 제 2 버젼은 디폴트의 캐쉬 사이즈를 사용하는 것.

CBaseList::~CBaseList

CBaseList 클래스

소멸자 메소드.

구문

~CBaseList(void);

CBaseList::FindI

CBaseList 클래스

지정한 항목을 가지는 최초의 위치를 취득한다.

구문

POSITION FindI(
    void *pObj
);

파라미터

pObj
항목에의 포인터.

반환값

POSITION 값을 돌려주는, 리스트내에 항목이 없으면 NULL 를 돌려준다.

CBaseList::GetCountI

CBaseList 클래스

리스트의 항목수를 취득한다.

구문

int GetCountI(void);

반환값

리스트의 항목수를 돌려준다.

CBaseList::GetHeadPositionI

CBaseList 클래스

리스트의 선두 항목의 위치를 취득한다.

구문

POSITION GetHeadPositionI(void);

반환값

POSITION 값을 돌려주는, 리스트가"로부터"의 경우 NULL 를 돌려준다.

CBaseList::GetI

CBaseList 클래스

지정한 위치의 항목을 취득한다.

구문

void *GetI(
    POSITION pos
);

파라미터

pos
취득하는 항목의 위치 정보.

반환값

항목에의 포인터를 돌려준다.

주의

pos 가 NULL 라면, 메소드는 NULL 를 돌려준다.

CBaseList::GetNextI

CBaseList 클래스

지정한 위치의 항목을 취득해, 위치를 진행시킨다.

구문

void *GetNextI(
    POSITION& rp
);

파라미터

rp
POSITION 값에의 참조.

반환값

항목에의 포인터를 돌려준다.

주의

이 메소드는 위치 정보를 다음의 위치하러 진행한다. 위치 정보가 리스트의 말미를 넘었다면, 메소드는 거기에 NULL 를 설정한다.

rp 가 NULL 라면, 메소드는 NULL 를 돌려준다.

CBaseList::GetTailPositionI

CBaseList 클래스

리스트의 말미 항목의 위치를 취득한다.

구문

POSITION GetTailPositionI(void);

반환값

POSITION 값을 돌려주는, 리스트에 아무것도 들어가 있지 않으면 NULL 를 돌려준다.

CBaseList::MoveToHead

CBaseList 클래스

리스트를 분할해, 뒤측을 다른 리스트의 전에 삽입한다.

구문

BOOL MoveToHead(
    POSITION pos,
    CBaseList *pList
);

파라미터

pos
리스트를 분할하는 위치 정보.
pList
다른 리스트에의 포인터.

반환값

성공이라면 TRUE, 그 이외라면 FALSE 를 돌려준다.

주의

이 메소드는 pos 파라미터가 지정하는 위치전에 리스트를 분할한다. 전측의 부분은 리스트에 남는다. 뒤측의 부분은 다른 리스트의 선두에 삽입된다.

CBaseList::MoveToTail

CBaseList 클래스

리스트를 분할해, 전측을 다른 리스트의 마지막에 추가한다.

구문

BOOL MoveToTail(
    POSITION pos,
    CBaseList *pList
);

파라미터

pos
리스트를 분할하는 위치 정보.
pList
다른 리스트에의 포인터.

반환값

성공이라면 TRUE, 그 이외라면 FALSE 를 돌려준다.

주의

이 메소드는 pos 파라미터가 지정하는 위치전에 리스트를 분할한다. 뒤측의 부분은 리스트에 남는다. 전측의 부분은 다른 리스트의 말미에 추가된다.

CBaseList::Next

CBaseList 클래스

리스트의 다음의 위치를 취득한다.

구문

POSITION Next(
    POSITION pos
);

파라미터

pos
POSITION 값

반환값

pos 가 지정하는 위치의 다음의 위치 정보를 돌려준다.

주의

pos 가 리스트의 말미의 위치라면, 메소드는 NULL 를 돌려준다. pos 가 NULL 라면, 메소드는 리스트의 선두 위치를 돌려준다.

CBaseList::Prev

CBaseList 클래스

리스트의 전의 위치를 취득한다.

구문

POSITION Prev(
    POSITION pos
);

파라미터

pos
POSITION 값.

반환값

pos 로 지정되는 위치전의 위치 정보를 돌려준다.

주의

pos 가 리스트의 선두의 위치라면, 메소드는 NULL 를 돌려준다. pos 가 NULL 라면, 메소드는 리스트의 말미의 위치를 돌려준다.

CBaseList::RemoveAll

CBaseList 클래스

리스트로부터 모든 노드를 삭제한다.

구문

void RemoveAll(void);

주의

모든 노드에 포함되는 항목의 삭제는 호출해 원의 책임이다.

CBaseList::RemoveHeadI

CBaseList 클래스

리스트의 선두 항목을 삭제한다.

구문

void *RemoveHeadI(void);

반환값

항목의 포인터를 돌려주는, 리스트에 아무것도 들어가 있지 않으면 NULL 를 돌려준다.

주의

이 메소드는 리스트로부터 노드를 삭제하지만, 노드에 포함되는 항목은 삭제하지 않는다.

CBaseList::RemoveI

CBaseList 클래스

지정한 위치의 항목을 삭제한다.

구문

void *RemoveI(
    POSITION pos
);

파라미터

pos
삭제하는 항목을 나타내는 POSITION 값.

반환값

항목의 포인터를 돌려준다.

주의

이 메소드는 리스트로부터 노드를 삭제하지만, 노드에 포함되는 항목은 삭제하지 않는다.

pos 가 NULL 라면, 메소드는 NULL 를 돌려준다.

CBaseList::RemoveTailI

CBaseList 클래스

리스트의 말미 항목을 삭제한다.

구문

void *RemoveTailI(void);

반환값

항목의 포인터를 돌려주는, 리스트가 매운들 NULL 를 돌려준다.

주의

이 메소드는 리스트로부터 노드를 삭제하지만, 노드에 포함되는 항목은 삭제하지 않는다.

CBaseList::Reverse

CBaseList 클래스

리스트의 차례를 역전한다

구문

void Reverse(void);


CBaseMediaFilter 클래스

CBaseMediaFilter 클래스의 계층

IMediaFilter 인터페이스를 이행 하는 base class. PID , 그 이외에서는 IBaseFilter 인터페이스를 지원 하지 않고 IMediaFilter 를 지원 할 필요가 있는 오브젝트에 대해서는 이 클래스를 사용한다. 필터에 대해서는 이 클래스를 사용해서는 안 된다. 그 대신,CBaseFilter 혹은 CBaseFilter 로부터 파생한 base class를 사용한다.

선언 : Amfilter.h

Protected 멤버 변수
m_State | 오브젝트의 현재 상태.
m_pClock | 오브젝트의 기준 클락에의 포인터.
m_tStart | 스트림 타임 0 에 대응하는 기준 타임.
m_clsid | 오브젝트의 클래스 ID (CLSID).
m_pLock | 크리티컬 섹션에의 포인터.
Public 메소드
CBaseMediaFilter | constructor 메소드.
~CBaseMediaFilter | 소멸자 메소드. 가상.
StreamTime | 현재의 스트림 타임을 취득한다. 가상.
IsActive | 오브젝트가 액티브한가 어떤가(실행중인가 포즈나) 확인한다.
IPersist 메소드
GetClassID | 클래스 ID 를 취득한다.
IMediaFilter 메소드
GetState | 오브젝트가 액티브한가 어떤가(실행중인가, 정지인가, 포즈인지)를 취득한다.
SetSyncSource | 오브젝트의 기준 클락을 설정한다.
GetSyncSource | 오브젝트가 사용중의 기준 클락을 취득한다.
Stop | 오브젝트를 정지한다.
Pause | 오브젝트를 포즈 한다.
Run | 오브젝트를 실행한다.

CBaseMediaFilter.m_State

CBaseMediaFilter 클래스

오브젝트의 현재 상태.

구문

FILTER_STATE m_State;

CBaseMediaFilter.m_pClock

CBaseMediaFilter 클래스

오브젝트의 기준 클락에의 포인터.

구문

IReferenceClock *m_pClock;

CBaseMediaFilter.m_tStart

CBaseMediaFilter 클래스

스트림 타임 0 에 대응하는 기준 타임.

구문

CRefTime m_tStart;

CBaseMediaFilter.m_clsid

CBaseMediaFilter 클래스

오브젝트의 클래스 ID (CLSID).

구문

CLSID m_clsid;

CBaseMediaFilter.m_pLock

CBaseMediaFilter 클래스

크리티컬 섹션에의 포인터.

구문

CCritSec *m_pLock;

주의

기준 클락에 액세스(SetSyncSource 나 GetSyncSource ) 하면 귀로,IsActive 메소드에서는 , 크리티컬 섹션은 상태 이행중 (Run ,Pause ,Stop )에 보관 유지된다.

CBaseMediaFilter::CBaseMediaFilter

CBaseMediaFilter 클래스

constructor　 　 메소드.

구문

CBaseMediaFilter(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    CCritSec *pLock,
    REFCLSID clsid
);

파라미터

pName
오브젝트명을 포함한 캐릭터 라인에의 포인터.
pUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되고 있으면, 집성 된 오브젝트의 IUnknown 인터페이스에의 포인터를 건네준다. 그 이외의 경우, 이 파라미터는 NULL 에 세트.
pLock
CCritSec 락에의 포인터, 상태 이행을 계속하는데 이용한다. l
clsid
오브젝트의 클래스 ID.

주의

다른 오브젝트가 CBaseMediaFilter 를 포함한, 혹은 집성 하고 있다면,CCritSec 락은 CBaseMediaFilter 오브젝트외에서 일어나고 있을 가능성이 있다. 이 경우,pLock 의 락에의 포인터를 건네주는 것.

그 이외에서는 다음과 같이 한다 :

  • CBaseMediaFilter 와 CCritSec 의 양쪽 모두를 계승하는 클래스를 파생시켜,이포인터를 건네준다.
  • CBaseMediaFilter 와 CCritSec 멤버 변수를 계승하는 클래스를 파생시킨다. pLock 에 대해서는, 그 변수의 주소를 건네준다.

CBaseMediaFilter::~CBaseMediaFilter

CBaseMediaFilter 클래스

소멸자 메소드.

구문

CBaseMediaFilter(void);

주의

삭제하기 전에 반드시 오브젝트를 정지시키는 것.

CBaseMediaFilter::GetClassID

CBaseMediaFilter 클래스

클래스 ID 를 취득. IPersist::GetClassID 메소드의 이행.

구문

HRESULT GetClassID(
    CLSID *pClsID
);

파라미터

pClsID
클래스 ID 를 취득하는 변수의 포인터.

반환값

S_OK 나 E_POINTER 를 돌려준다.

CBaseMediaFilter::GetState

CBaseMediaFilter 클래스

오브젝트가 액티브한가 어떤가(실행중인가, 정지인가, 포즈인지)를 취득한다. IMediaFilter::GetState 메소드의 이행.

구문

HRESULT GetState(
    DWORD dwMilliSecsTimeout,
    FILTER_STATE *State
);

파라미터

dwMilliSecsTimeout
타임 아웃 시간 간격, 밀리 세컨드
State
오브젝트 상태를 나타내는 FILTER_STATE 열거형의 멤버를 취득하는 변수의 포인터.

반환값

S_OK 나 E_POINTER 를 돌려준다.

주의

base class에서는, 모든 상태 이행은 동기 되어dwMilliSecsTimeout 파라미터는 무시된다. 상속 클래스가 상태 이행의 동기를 실행한다면, 이 메소드를 오버라이드(override) 해,dwMilliSecsTimeout 밀리 세컨드의 타임 아웃으로, 상태 이행을 기다려야 한다.

CBaseMediaFilter::GetSyncSource

CBaseMediaFilter 클래스

오브젝트가 사용중의 기준 클락을 취득. IMediaFilter::GetSyncSource 메소드의 이행.

구문

HRESULT GetSyncSource(
    IReferenceClock **pClock
);

파라미터

pClock
클락의 IReferenceClock 인터페이스에의 포인터를 취득하는 변수의 주소.

반환값

S_OK 나 E_POINTER 를 돌려준다.

주의

오브젝트가 기준 클락을 사용하고 있지 않으면,*pClock 를 NULL 로 설정한다. 메소드가 돌아왔을 때,*pClock 가 NULL 이외라면,IReferenceClock 인터페이스는 참조 카운트를 남기고 있다. 해방시에는 주의가 필요하다.

CBaseMediaFilter::IsActive

CBaseMediaFilter 클래스

오브젝트가 액티브한가 어떤가(실행중인가 포즈나) 확인한다.

구문

BOOL IsActive(void);

반환값

오브젝트가 실행중이나 포즈이면, TRUE 를 돌려준다. 정지중이면 FALSE 를 돌려준다.

CBaseMediaFilter::Pause

CBaseMediaFilter 클래스

오브젝트를 포즈 한다. IMediaFilter::Pause 메소드의 이행.

구문

HRESULT Pause(void);

반환값

S_OK 를 돌려준다.

주의

base class에서는, 이 메소드는 m_State 멤버 변수를 State_Paused 로 설정하지만, 그 이외는 아무것도 하지 않는다.

CBaseMediaFilter::Run

CBaseMediaFilter 클래스

오브젝트를 실행한다. IMediaFilter::Run 메소드의 이행.

구문

HRESULT Run(
    REFERENCE_TIME tStart
);

파라미터

tStart
스트림 타임 0 에 대응한 기준 타임.

반환값

S_OK 를 돌려준다.

주의

오브젝트가 정지하고 있으면, 이 메소드는 CBaseMediaFilter::Pause 메소드를 호출해 오브젝트를 포즈 한다. 다음에 m_State 멤버 변수를 State_Running 로 설정한다.

스트림 타임은 현재의 기준 타임 당기는 tStart 로 계산된다. 타임 스탬프 제로의 미디어 샘플은 tStart 타임에 렌더링 될 것이다.

CBaseMediaFilter::SetSyncSource

CBaseMediaFilter 클래스

오브젝트의 기준 클락을 설정한다. IMediaFilter::SetSyncSource 메소드의 이행.

구문

HRESULT SetSyncSource(
    IReferenceClock *pClock
);

파라미터

pClock
클락의 IReferenceClock 인터페이스에의 포인터, 혹은 NULL .

반환값

S_OK 를 돌려준다.

CBaseMediaFilter::Stop

CBaseMediaFilter 클래스

오브젝트를 정지한다. IMediaFilter::Stop 메소드의 이행.

구문

HRESULT Stop(void);

반환값

S_OK 를 돌려준다.

주의

base class에서는, 이 메소드는 m_State 멤버 변수를 State_Stopped 로 설정하지만, 그 이외는 아무것도 하지 않는다.

CBaseMediaFilter::StreamTime

CBaseMediaFilter 클래스

현재의 스트림 타임을 취득.

구문

virtual HRESULT StreamTime(
    CRefTime& rtStream
);

파라미터

rtStream
현재의 스트림 타임을 취득하는 CRefTime 오브젝트에의 참조.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NO_CLOCK | 유효한 기준 클락이 없다.

주의

스트림 타임은(기준 클락으로 주어진다) 현재의 기준 타임 마이너스 (m_tStart 로 여) 시작 타임에 의해 정의된다. 미디어 샘플의타임 스탬프는 렌더링 되어야 할 스트림 타임을 지정한다. 현재의 스트림 타임보다 작은 타임 스탬프를 가지는 샘플이 아직 렌더링 되지 않으면, 그것은 늦는다.


CBaseObject 클래스

CBaseObject 클래스의 계층

Microsoft® DirectShow® 오브젝트를 이행하기 위한 추상 클래스.

선언 : Combase.h

이 클래스는, 정적인, 프로세스 전체의 액티브 오브젝트의 수의 카운트를 보관 유지한다. DllCanUnloadNow 함수는, 이 카운트를 사용해 DirectShow DLL 를 언제 언로드할 수 있을까를 판단한다. 어플리케이션에서는, 이 카운트를 사용해, 삭제를 취소한 오브젝트에 의한 메모리 누수를 검출할 수 있다.

Component Object Model (COM) 오브젝트를 이행 하려면 ,CBaseObject 로부터 파생한 CUnknown 클래스를 사용한다.

클래스 메소드
CBaseObject | constructor　 　 메소드.
~CBaseObject | 소멸자 메소드.
ObjectsActive | 액티브 오브젝트의 카운트를 취득한다.

CBaseObject::CBaseObject

CBaseObject 클래스

constructor　 　 메소드.

구문

CBaseObject(
const TCHAR *pName
);

파라미터

pName
디버그를 위해서(때문에) 사용되는 오브젝트의 이름을 포함한 캐릭터 라인.

주의

이 메소드는, 액티브 오브젝트의 카운트를 인크리먼트(increment) 한다. 상세한 것에 대하여는, 「ObjectsActive 」를 참조할것.

스태틱 메모리에 pName 파라미터를 할당한다.

// 올바르다.
CBaseObject *pObject = new CObject(NAME("My Object"));

// 올바르지 않다.
TCHAR ObjectName[] = TEXT("My Object");
CBaseObject *pObject = new CBaseObject(ObjectName);

NAME 매크로는,리테일 빌드에서는 NULL 에 컴파일 되므로, 정적 캐릭터 라인은 디버그 빌드에서만 표시된다. 상세한 것에 대하여는, 「DbgDumpObjectRegister 」를 참조할것.

CBaseObject::~CBaseObject

CBaseObject 클래스

소멸자 메소드.

구문

~CBaseObject(void);

주의

이 메소드는, 액티브 오브젝트의 카운트를 감소 한다. 상세한 것에 대하여는, 「ObjectsActive 」를 참조할것.

CBaseObject::ObjectsActive

CBaseObject 클래스

프로세스 전체의 액티브 오브젝트의 카운트를 취득한다.

구문

static LONG ObjectsActive(void);

반환값

액티브 오브젝트의 수를 돌려준다.


CBaseOutputPin 클래스

CBaseOutputPin 클래스의 계층

출력 핀을 이행 하는 추상 base class.

선언 : Amfilter.h

이 클래스는 CBasePin 로부터 파생한다. 이하의 면에서 CBasePin 와는 다르다.

  • IMemInput 인터페이스를 지원 하는 입력 핀에게만 접속한다.
  • IMemAllocator 인터페이스를 통해, 로컬 메모리 트랜스폴트를 지원 한다.
  • 엔드 오브 스트림, 플래시, 신세그먼트(segment) 통지를 거절한다. (이것들은 출력 핀에 보내져서는 안된다)
  • 샘플 데이터 스트림을 출력하기 위해서 제공된 메소드

핀이 접속 하면 와, 입력 핀으로부터의 메모리 allocater를 요구한다. 그것이 실패 하면, 새로운 allocater 오브젝트를 생성 한다. 출력 핀은 allocater 프로퍼티를 설정할 책임이 있다. 순수 가상 메소드 DecideBufferSize 를 통해 이것을 실시한다. 상속 클래스에서는 이 메소드를 오버라이드(override) 한다. 입력 핀이 버퍼 요구를 가질 때, 그 요구는 DecideBufferSize 메소드에게 건네진다.

공백의 미디어 샘플을 취득하려면 GetDeliveryBuffer 를 호출하는 것. 샘플 다운 스트림을 출력하려면 Deliver 를 호출하는 것.

Protected 멤버 변수
m_pAllocator | 메모리 allocater에의 포인터.
m_pInputPin | 이 핀에 접속하는 입력 핀에의 포인터.
Public 메소드
CBaseOutputPin | constructor 메소드.
CompleteConnect | 입력 핀에의 접속을 완료한다. 가상.
DecideAllocator | 메모리 allocater를 선택한다. 가상.
GetDeliveryBuffer | 공백 버퍼를 가지는 미디어 샘플을 취득. 가상.
Deliver | 미디어 샘플을 접속한 입력 핀에 출력한다. 가상.
InitAllocator | 메모리 allocater를 생성. 가상.
CheckConnect | 핀 접속이 적절한가 어떤가 확인한다.
BreakConnect | 접속으로부터 핀을 해방한다.
Active | 필터가 현재 액티브한 것을 핀에 통지한다.
Inactive | 필터가 이제(벌써) 액티브하지 않는 것을 핀에 통지한다.
DeliverEndOfStream | 엔드 오브 스트림 통지를 접속하는 입력 핀에 출력한다. 가상.
DeliverBeginFlush | 접속하는 입력 핀에 플래시 처리의 시작을 요구한다. 가상.
DeliverEndFlush | 접속한 입력 핀에 플래시 처리의 종료를 요구한다. 가상.
DeliverNewSegment | 신세그먼트(segment) 통지를 접속하는 입력 핀에 출력한다. 가상.
Pure Virtual 메소드
DecideBufferSize | 버퍼 요구를 설정한다.
IPin 메소드
BeginFlush | 플래시 처리를 시작 한다.
EndFlush | 플래시 처리를 종료한다.
EndOfStream | 이후의 데이터는 없는 것을 핀에게 전한다.

CBaseOutputPin.m_pAllocator

CBaseOutputPin 클래스

메모리 allocater에의 포인터.

구문

IMemAllocator *m_pAllocator;

CBaseOutputPin.m_pInputPin

CBaseOutputPin 클래스

이 핀에 접속하는 입력 핀에의 포인터.

구문

IMemInputPin *m_pInputPin;

CBaseOutputPin::Active

CBaseOutputPin 클래스

필터가 현재 액티브한 것을 핀에 통지한다.

구문

HRESULT Active(void);

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NO_ALLOCATOR | 이용 가능한 메모리 allocater가 없다.

주의

이 메소드는 CBasePin::Active 메소드를 오버라이드(override) 한다. allocater의 IMemAllocator::Commit 메소드를 호출해, 버퍼에 메모리를 할당한다.

이 메소드를 오버라이드(override) 한다면, 그 오버라이드(override) 하는 메소드로부터 base class 메소드를 호출하는 것.

CBaseOutputPin::BeginFlush

CBaseOutputPin 클래스

플래시 처리를 시작 한다. IPin::BeginFlush 메소드의 이행.

구문

HRESULT BeginFlush(void);

반환값

E_UNEXPECTED 를 돌려준다.

주의

이 메소드는 입력 핀에서만 불려 가야 하는 것이므로,CBaseOutputPin 를 이행 하면 E_UNEXPECTED 를 돌려준다.

CBaseOutputPin::BreakConnect

CBaseOutputPin 클래스

접속으로부터 핀을 해방한다.

구문

HRESULT BreakConnect(void);

반환값

성공이라면 S_OK 를 돌려주는, 실패라면 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는CBasePin::BreakConnect 메소드를 오버라이드(override) 한다. allocater를 데코밋트로 해,IMemAllocator 와 IPin 인터페이스를 해방한다.

이 메소드를 오버라이드(override) 한다면, 그 오버라이드(override) 하는 메소드로부터 기본 메소드를 호출하는 것. 그렇게 하지 않으면 메모리 누수의 가능성이 있다.

CBaseOutputPin::CBaseOutputPin

CBaseOutputPin 클래스

constructor　 　 메소드.

구문

CBaseOutputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pName
);

파라미터

pObjectName
오브젝트의 디버그명이 들어가는 캐릭터 라인. 상세한 것에 대하여는, 「CbaseObject 」를 참조할것.
pFilter
이 핀을 생성 한 필터에의 포인터.
pLock
CCritSec 락에의 포인터, 상태 이행을 계속하기 위해서 사용. 이것은 필터 락 CBaseFilter.m_pLock 와 같은 크리티컬 섹션이 될 수 있다.
phr
메소드의 성공·실패를 나타내는 HRESULT 값을 취득하는 변수에의 포인터.
pName
(핀 ID 로서도 사용된다) 핀명이 들어가는 Unicode™ 캐릭터 라인.

주의

모든 파라미터는 직접 CBasePin constructor　 　 에 보내진다.

CBaseOutputPin::CheckConnect

CBaseOutputPin 클래스

핀 접속이 적절한가 어떤가 확인한다.

구문

HRESULT CheckConnect(
    IPin *pPin
);

파라미터

pPin
입력 핀의 IPin 인터페이스에의 포인터.

반환값

다음의 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_NOINTERFACE | 입력 핀은 IMemInputPin 를 지원 하고 있지 않다.
VFW_E_INVALID_DIRECTION | 핀의 방향으로 호환성이 없다.

주의

이 메소드는 base class CBasePin::CheckConnect 메소드를 호출해, 다음에 IMemInputPin 인터페이스에 입력 핀을 문의한다.

CBaseOutputPin::CompleteConnect

CBaseOutputPin 클래스

입력 핀에의 접속을 완료한다.

구문

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

파라미터

pReceivePin
입력 핀에의 포인터.

반환값

성공이라면 S_OK 를 돌려주는, 실패라면 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는 CBasePin::CompleteConnect 메소드를 오버라이드(override) 한다. 이 접속에 사용하는 메모리 allocater를 선택하는 DecideAllocator 메소드를 호출한다.

CBaseOutputPin::DecideAllocator

CBaseOutputPin 클래스

메모리 allocater를 선택한다.

구문

virtual HRESULT DecideAllocator(
    IMemInputPin *pPin,
    IMemAllocator **pAlloc
);

파라미터

pPin
입력 핀의 IMemInputPin 인터페이스에의 포인터.
pAlloc
allocater의 IMemAllocator 인터페이스에의 포인터를 취득하는 변수의 주소.

반환값

성공이라면 S_OK 를 돌려주는, 실패라면 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는 핀 접속 프로세스의 마지막에 불려 간다. 다음의 스텝에서 실행한다 :

  1. 만약 있으면,IMemInputPin::GetAllocatorRequirements 메소드를 호출해, 입력 핀의 버퍼 요구를 취득한다.
  2. IMemInputPin::GetAllocator 메소드를 호출해, 입력 핀으로부터 allocater를 요구한다. 그 입력 핀이 allocater를 제공하지 않으면, 출력 핀은 InitAllocator 클래스 메소드를 호출해 allocater를 생성 한다.
  3. DecideBufferSize 클래스 메소드를 호출해, allocater 프로퍼티를 설정한다. 이것은 순수 가상 메소드인, 상속 클래스는 이것을 이행 해야 한다.
  4. IMemInputPin::NotifyAllocator 메소드를 호출해, allocater의 사용을 입력 핀에 통지한다.

CBaseOutputPin::DecideBufferSize

CBaseOutputPin 클래스

버퍼 요구를 설정한다.

구문

virtual HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *ppropInputRequest
) PURE;

파라미터

pAlloc
allocater의 IMemAllocator 인터페이스에의 포인터.
ppropInputRequest
입력 핀의 버퍼 요구를 포함한 ALLOCATOR_PROPERTIES 구조체에의 포인터. 입력 핀이 어떤 요구도 지정하지 않으면, 호출원래는 이 구조체의 멤버를 제로이다.

반환값

성공이라면 S_OK 를 돌려주는, 실패라면 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드를 상속 클래스로 오버라이드(override) 하는 것. 버퍼 요구를 붙여 IMemAllocator::SetProperties 메소드를 호출한다. 보통 상속 클래스는 입력 버퍼의 요구를 존중하지만, 반드시 그것을 할 필요는 없다.

CBaseOutputPin::Deliver

CBaseOutputPin 클래스

미디어 샘플을 접속한 입력 핀에 출력한다.

구문

virtual HRESULT Deliver(
    IMediaSample *pSample
);

파라미터

pSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

이 메소드는 입력 핀의 IMemInputPin::Receive 메소드를 호출한다. IMemInputPin::ReceiveCanBlock 메소드가 S_OK 를 돌려준다면,Receive 는 블록 할 가능성이 있다.

이 메소드를 호출한 다음에, 샘플을 해방하는 것. 입력 핀은 샘플의 참조 카운트를 가진 채로이므로, 샘플을 재사용해서는 안 된다. 반드시 GetDeliveryBuffer 메소드를 호출해, 새로운 샘플을 취득한다.

이 메소드를 호출하기 전에 필터의 크리티컬 섹션을 hold 하는 것. 그렇게 하지 않으면 그 핀은 메소드 호출중에 비접속이 될 가능성이 있다. 필터가 워커 thread를 사용해 샘플을 출력한다면, 필터가 샘플을 출력 가능하게 되었을 때, 크리티컬 섹션을 hold 한다. 그렇지 않으면, 필터의 IMemInputPin::Receive 메소드로 크리티컬 섹션을 hold 한다, 거기서 필터는 샘플을 처리한다.

워커 thread는 데드 록의 가능성을 생성 할 수 있다. thread가 크리티컬 섹션을 hold 하면 와, 필터 상태 이행을 기다릴지도 모른다. 동시에, 상태 이행은 thread가 완료하는 것을 기다려 있을지도 모르다. 이것을 피하기 위해서(때문에), 상태 이행 코드는 thread를 끝내는 이벤트를 통지해, 다음에 thread가 그 통지를 완료할 때까지 기다리는 것.

CBaseOutputPin::DeliverBeginFlush

CBaseOutputPin 클래스

접속하는 입력 핀에 플래시 처리의 시작을 요구한다.

구문

virtual HRESULT DeliverBeginFlush(void);

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

이 메소드는 입력 핀의 IPin::BeginFlush 메소드를 호출한다.

CBaseOutputPin::DeliverEndFlush

CBaseOutputPin 클래스

접속한 입력 핀에 플래시 처리의 종료를 요구한다.

구문

virtual HRESULT DeliverEndFlush(void);

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

이 메소드는 입력 핀의 IPin::EndFlush 메소드를 호출한다.

CBaseOutputPin::DeliverEndOfStream

CBaseOutputPin 클래스

엔드 오브 스트림 통지를 접속하는 입력 핀에 출력한다.

구문

virtual HRESULT DeliverEndOfStream(void);

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

이 메소드는 입력 핀의 IPin::EndOfStream 메소드를 호출한다.

CBaseOutputPin::DeliverNewSegment

CBaseOutputPin 클래스

신세그먼트(segment) 통지를 접속하는 입력 핀에 출력한다.

구문

virtual HRESULT DeliverNewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

파라미터

tStart
세그먼트(segment)의 시작 미디어 위치, 100 나노초단위.
tStop
세그먼트(segment)의 종료 미디어 위치, 100 나노초단위.
dRate
이 세그먼트(segment)가 처리되는 비율, 오리지날의 레이트의 퍼센티지.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

이 메소드는 입력 핀의 IPin::NewSegment 메소드를 호출한다.

CBaseOutputPin::EndFlush

IPin Interface

플래시 처리를 종료한다. IPin::EndFlush 메소드의 이행.

구문

HRESULT EndFlush(void);

반환값

E_UNEXPECTED 를 돌려준다.

주의

이 메소드는 입력 핀에서만 불려 가야 하는 것이므로,CBaseOutputPin 를 이행 하면 E_UNEXPECTED 를 돌려준다.

CBaseOutputPin::EndOfStream

IPin Interface

이후의 데이터는 없는 것을 핀에게 전한다. IPin::EndOfStream 메소드의 실행.

구문

HRESULT EndOfStream(void);

반환값

E_UNEXPECTED 를 돌려준다.

주의

이 메소드는 입력 핀에서만 불려 가야 하는 것이므로,CBaseOutputPin 를 이행 하면 E_UNEXPECTED 를 돌려준다.

CBaseOutputPin::GetDeliveryBuffer

CBaseOutputPin 클래스

공백 버퍼를 가지는 미디어 샘플을 취득.

구문

virtual HRESULT GetDeliveryBuffer(
    IMediaSample **ppSample,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime,
    DWORD dwFlags
);

파라미터

ppSample
버퍼의 IMediaSample 인터페이스의 포인터를 취득하는 변수의 주소.
pStartTime
샘플의 시작 타임에의 포인터, 혹은 NULL .
pEndTime
샘플의 종료 타임에의 포인터, 혹은 NULL .
dwFlags
IMemAllocator::GetBuffer 인터페이스에 의해 지원 되는, 플래그의 비트마다의 편성.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
E_NOINTERFACE | 유효한 메모리 allocater가 없다.

주의

이 메소드는, allocater의 IMemAllocator::GetBuffer 메소드를 호출해, 이 메소드에 파라미터를 건네준다.

CBaseOutputPin::Inactive

CBaseOutputPin 클래스

필터가 이제(벌써) 액티브하지 않는 것을 핀에 통지한다.

구문

HRESULT Inactive(void);

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NO_ALLOCATOR | 유효한 메모리 allocater가 없다.

주의

이 메소드는 CBasePin::Inactive 메소드를 오버라이드(override) 한다. IMemAllocator::Decommit 메소드를 호출해, 메모리 allocater를 데코밋트로 한다.

이 메소드를 오버라이드(override) 한다면, 그 오버라이드(override) 하는 메소드로부터 base class 메소드를 호출하는 것.

CBaseOutputPin::InitAllocator

CBaseOutputPin 클래스

메모리 allocater를 생성.

구문

virtual HRESULT InitAllocator(
    IMemAllocator **ppAlloc
);

파라미터

ppAlloc
allocater의 IMemAllocator 인터페이스에의 포인터를 취득하는 변수의 주소.

반환값

성공이라면 S_OK 를 돌려주는, 실패라면 CoCreateInstance 함수로부터의 에러 코드를 돌려준다.

주의

입력 핀이 메모리 allocater를 제공하지 않으면,DecideAllocator 메소드는 이 메소드를 호출해, allocater를 생성 한다.


CBasePin 클래스

CBasePin 클래스의 계층

범용 핀을 이행 하는 추상 클래스.

선언 : Amfilter.h

  • 접속 처리
  • CBasePin 가 IPin::Connect 를 이행 하는 방법
  • 필터 상태의 이행

접속 처리

필터 그래프 매니저가 모든 핀 접속을 시작 한다. 어플리케이션이 2 개의 핀을 접속할 필요가 있다면, 필터 그래프 매니저의 IFilterGraph::ConnectDirect 메소드를 호출해야 한다.

2 개의 핀이 접속되었을 때,접속 핀과 수신 핀이 존재한다. 필터 그래프 매니저는 접속 핀의 IPin::Connect 메소드를 호출한다. 이것은 수신 핀과 접속하고 있는 가능한 미디어 타입을 지정한다. 접속 핀은 수신 핀의 IPin::ReceiveConnection 메소드를 호출하는 것으로, 접속을 완료한다. 수신 핀은 접속을 받아들이는 일도 거부하는 일도 가능하다.

필터 그래프 매니저가 미디어 타입을 지정 하면, 핀은 그 타입으로 접속하려고 한다. 그렇지 않으면, 핀은 받아들이고 가능한 타입을 네고시에이션 한다. 타입을 일치할 수 없으면 접속은 실패한다. 필터 그래프 매니저는파셜 미디어 타입을 지정하는 경우도 있다. 파셜 미디어 타입은 메이저 타입, 서브 타입, 포맷에 GUID_NULL 값을 가진다. 이 경우, 핀은 지정한 부분의 타입에 맞추려고 해, GUID_NULL 는 와일드 카드로서 일한다.

Microsoft® DirectShow® 의 이행에서는, 접속 핀은 반드시 출력 핀으로, 수신 핀은 반드시 입력 핀이다.

CBasePin 가 IPin::Connect 를 이행 하는 방법

핀이 접속을 받아들일 수가 있는지를 검증하는 것에 의해 CBasePin::Connect 메소드는 시작 한다. 예를 들어, 그것은 핀이 이미 접속되고 있는 것을 체크한다. 다음에, 접속 처리의 나머지의 부분을 protected 클래스 메소드 AgreeMediaType 에 위임한다. 그 이후의 모든 것은 AgreeMediaType 에 의해 실행된다.

미디어 타입이 완전하게 지정되면(자), 핀은 AttemptConnection 메소드를 호출한다. 그렇지 않으면, 다음의 순서로 핀은 복수의 미디어 타입을 시험한다.

  1. 수신 핀이 우선하는 타입.
  2. 접속 핀이 우선하는 타입.

주의 이 차례는 m_bTryMyTypesFirst 플래그를 TRUE 로 설정하는 것에 의해 반대로 할 수 있다.

각각의 경우로, 핀은 IPin::EnumMediaTypes 를 호출해, 열거 오브젝트를 취득한다. 그것은 TryMediaTypes 메소드에 열거 오브젝트를 건네준다. 이 메소드는 열거 자식이 제공하는 모든 미디어 타입에 대해 루프 해, 각 타입에 AttemptConnection 를 호출한다.

AttemptConnection 내에서, 접속 핀은 다음의 메소드를 호출한다 :

  • CheckConnect : 수신 핀이 적절한가 어떤가를 체크한다.
  • CheckMediaType : 미디어 타입을 유효하게 한다.
  • IPin::ReceiveConnection (수신 핀으로): 수신 핀이 접속을 받아들일지 어떨지를 결정한다.
  • CompleteConnect : 접속의 완료.

이하에 주의 :

  • CheckConnect 는 가상 메소드이다. base class에서는, 핀의 방향으로 호환성이 있을지 어떨지 체크한다. 출력 핀은 입력 핀에게만 접속해, 입력 핀은 출력 핀에게만 접속한다. 예를 들어, 어느 인터페이스에 다른 핀을 문의하거나 그 인터페이스를 지원 하지 않는 핀을 거부하거나 한다.
  • CheckMediaType 는 상속 클래스가 반드시 이행 해야 하는 순수 가상 메소드이다.
  • CompleteConnect 는 base class에서는 아무것도 실시하지 않는 가상 메소드이다. 상속 클래스는 이 메소드를 오버라이드(override) 해, 메모리 allocater의 결정과 같은, 접속을 완료시키기 위해서(때문에) 필요한 추가 처리의 실행 메소드를 오버라이드(override) 할 수가 있다.

이러한 스텝이 실패 하면, 핀은 BreakConnect 메소드를 호출해,CheckConnect 에 의해 행해진 스텝을 모두 바탕으로 되돌린다.

수신 사이드에서는,ReceiveConnection 는 수신 핀의 CheckConnect 과 CompleteConnect 메소드를 호출한다. 이러한 어느 쪽인지가 실패 하면, 접속의 시도가 또 실패가 된다.

필터 상태의 이행

핀은, 접속하고 있는 필터 상태가 이행 할 때마다 통지를 받는다. 다음 표에 나타내도록(듯이), 필터는 각각의 상태 이행에 대해, 핀의 대응하는 메소드를 호출한다.

필터 상태 | CBasePin 메소드
정지 | 비액티브
포즈 | 액티브
실행 | 실행

상속 클래스는 이러한 메소드를 오버라이드(override) 해, 상태 이행에 대응해야 한다. 필터에 의해, 핀은 샘플의 출력, 메모리 allocater의 위탁, 위탁등을 실시하는 워커 thread를 사용하는 경우도 있다.

CBasePin 로부터의 파생

CBasePin 를 사용해 핀을 이행 하려면 , base class로부터 새로운 클래스를 파생해, 몇개의 메소드를 오버라이드(override) 해야 한다. 오버라이드(override) 해야 하는 것은, 다음의 메소드이다.

  • CheckMediaType
  • GetMediaType

다음의 메소드에 대해서도, 오버라이드(override)가 필요한 가능성이 높다.

  • Active
  • BreakConnect
  • CheckConnect
  • CompleteConnect
  • EndOfStream
  • Inactive
  • Notify
  • Run

마지막으로, 반드시 IPin::BeginFlush 메소드와 IPin::EndFlush 메소드를 이행 해야 한다.

CBaseInputPin 와 CBaseOutputPin 와 같이, 이러한 메소드의 몇개인가는 CBasePin 로부터 파생한 base class에 이행 되고 있다.

Protected 멤버 변수
m_pName | 핀명.
m_Connected | 이 핀에 접속하고 있는 핀에의 포인터.
m_dir | 핀의 방향.
m_pLock | 크리티컬 섹션 오브젝트에의 포인터.
m_bRunTimeError | 런타임 에러가 일어났는지 어떠했는지를 나타내는 플래그.
m_bCanReconnectWhenActive | 핀이 동적재접속을 지원 할지 어떨지를 나타내는 플래그.
m_bTryMyTypesFirst | 핀이 수신 핀의 허용 하는 미디어 타입의 전에 자기 자신의 그것을 시도할지 어떨지를 나타내는 플래그.
m_pFilter | 핀을 생성 한 필터에의 포인터.
m_pQSink | 품질 메세지를 취급하는 오브젝트에의 포인터.
m_TypeVersion | 허용 미디어 타입 세트의 현재의 버젼.
m_mt | 지금의 핀 접속의 미디어 타입.
m_tStart | 세그먼트(segment) 시작 타임.
m_tStop | 세그먼트(segment) 종료 타임.
m_dRate | 세그먼트(segment) 레이트.
Protected 메소드
DisplayPinInfo | 디버그중에 핀 접속을 트레이스 한다.
DisplayTypeInfo | 디버그중에 미디어 타입 정보를 표시한다.
AttemptConnection | 지정한 미디어 타입을 사용하고 있는 다른 핀에 접속한다.
TryMediaTypes | 미디어 타입의 리스트를 주어 그러한 타입의 1 개를 사용해 접속을 완료하려고 시도한다.
AgreeMediaType | 핀 접속을 하는 미디어 타입을 조사한다.
DisconnectInternal | 현재의 핀 접속을 해제한다.
Public 메소드
CBasePin | constructor 메소드.
~CBasePin | 소멸자 메소드. 가상.
IsConnected | 핀이 다른 핀과 접속하고 있을지 어떨지를 확인한다.
GetConnected | 이 핀에 접속하고 있는 핀을 취득.
IsStopped | 이 핀을 포함한 필터가 정지하고 있을지 어떨지를 확인한다.
GetMediaTypeVersion | 허용 하는 미디어 타입 세트의 버젼수를 취득. 가상.
IncrementTypeVersion | 허용 하는 미디어 타입 세트의 버젼수를 인크리먼트(increment) 한다.
Active | 핀에 필터가 지금 액티브한 것을 통지한다. 가상.
Inactive | 핀에 필터가 지금 이미 액티브하지 않는 것을 통지한다. 가상.
Run | 필터가 지금 실행중인 것을 핀에 알린다. 가상.
SetMediaType | 접속하는 미디어 타입을 설정한다. 가상.
CheckConnect | 핀 접속이 적절한가 어떤가를 확인한다. 가상.
BreakConnect | 접속으로부터 핀을 해방한다. 가상.
CompleteConnect | 다른 핀에의 접속을 완료한다. 가상.
GetMediaType | 허용 하는 미디어 타입을 인덱스값으로 취득한다. 가상.
CurrentStopTime | 세그먼트(segment) 종료 타임을 취득한다.
CurrentStartTime | 세그먼트(segment) 시작 타임을 취득한다.
CurrentRate | 세그먼트(segment) 레이트를 취득한다.
Name | 핀의 식별명을 취득한다.
SetReconnectWhenActive | 핀이 동적재접속을 지원 할지 어떨지를 지정한다.
CanReconnectWhenActive | 핀이 동적재접속을 지원 할지 어떨지를 문의한다.
Pure Virtual 메소드
CheckMediaType | 핀이 지정한 미디어 타입을 받아들이는지를 확인한다.
IBasePin 메소드
Connect | 핀을 다른 핀에 접속한다.
ReceiveConnection | 다른 핀으로부터의 접속을 받아들인다.
Disconnect | 현재의 핀 접속을 해제한다.
ConnectedTo | 이 핀에 접속하고 있는 핀을 취득한다.
ConnectionMediaType | 만약 있으면, 현재의 핀 접속의 미디어 타입을 취득한다.
QueryPinInfo | 핀에 대한 정보를 취득한다.
QueryDirection | 핀의 방향(입력인가 출력인지)을 취득한다.
QueryId | 핀의 ID 를 취득한다.
QueryAccept | 핀이 지정한 미디어 타입을 받아들일지 어떨지를 확인한다.
EnumMediaTypes | 핀의 허용 하는 미디어 타입을 열거한다.
QueryInternalConnections | (필터내에서) 내부적으로 이 핀에 접속하고 있는 핀을 취득한다.
EndOfStream | 핀에 추가 데이터는 이제 없는 것을 통지한다.
NewSegment | 세그먼트(segment)로서 이 호출이 그룹화 된 다음에 미디어 샘플을 받은 것을 핀에 알린다.
IQualityControl 메소드
Notify | 품질 변경이 요구된 것을 핀에 통지한다.
SetSink | 외부의 품질 매니저를 설정한다.

CBasePin.m_pName

CBasePin 클래스

핀명.

구문

WCHAR *m_pName;

주의

The QueryPinInfo 메소드는 이 캐릭터 라인을 핀명으로서 돌려주어,QueryId 메소드는 그것을 핀 ID 로서 돌려준다. 그러나 일반적으로는, 핀명과 핀 ID 는 같다라고 요구되지는 않았다. 핀 ID 는 그래프로 사용된다. 상세한 것에 대하여는, 「IBaseFilter::FindPin 」를 참조할것.

CBasePin.m_Connected

CBasePin 클래스

이 핀에 접속하고 있는 핀에의 포인터.

구문

IPin *m_Connected;

CBasePin.m_dir

CBasePin 클래스

핀의 방향.

구문

PIN_DIRECTION m_dir;

CBasePin.m_pLock

CBasePin 클래스

크리티컬 섹션 오브젝트에의 포인터.

구문

CCritSec *m_pLock;

CBasePin.m_bRunTimeError

CBasePin 클래스

런타임 에러가 일어났는지 어떠했는지를 나타내는 플래그.

구문

bool m_bRunTimeError;

주의

이 플래그는 디폴트에서는 FALSE 이다. 스트리밍중에 런타임 에러가 일어나면(자), 이 플래그를 TRUE 로 설정하는 것. Inactive 메소드가 이 플래그를 FALSE 에 재설정한다.

CBasePin.m_bCanReconnectWhenActive

CBasePin 클래스

핀이 동적재접속을 지원 할지 어떨지를 나타내는 플래그.

구문

bool m_bCanReconnectWhenActive;

주의

이 플래그는 디폴트에서는 FALSE 이다.

CBasePin.m_bTryMyTypesFirst

CBasePin 클래스

핀이 수신 핀의 허용 하는 미디어 타입의 전에 자기 자신의 그것을 시도할지 어떨지를 나타내는 플래그.

구문

bool m_bTryMyTypesFirst;

주의

이 플래그는 디폴트에서는 FALSE 이다. 이 플래그가 TRUE 라면,AgreeMediaType 메소드는 미디어 타입을 시도하는 차례를 역전시킨다.

CBasePin.m_pFilter

CBasePin 클래스

핀을 생성 한 필터에의 포인터.

구문

CBaseFilter *m_pFilter;

CBasePin.m_pQSink

CBasePin 클래스

품질 메세지를 취급하는 오브젝트에의 포인터.

구문

IQualityControl *m_pQSink;

CBasePin.m_TypeVersion

CBasePin 클래스

허용 미디어 타입 세트의 현재의 버젼.

구문

LONG m_TypeVersion;

CBasePin.m_mt

CBasePin 클래스

지금의 핀 접속의 미디어 타입.

구문

CMediaType m_mt;

CBasePin.m_tStart

CBasePin 클래스

세그먼트(segment) 시작 타임.

구문

CRefTime m_tStart;

CBasePin.m_tStop

CBasePin 클래스

세그먼트(segment) 종료 타임.

구문

CRefTime m_tStop;

CBasePin.m_dRate

CBasePin 클래스

세그먼트(segment) 레이트.

구문

double m_dRate;

CBasePin::Active

CBasePin 클래스

핀에 필터가 지금 액티브한 것을 통지한다.

구문

virtual HRESULT Active(void);

반환값

S_OK 를 돌려준다.

주의

필터가 정지로부터 포즈가 될 때,CBaseFilter 클래스는, 필터의 접속된 모두 핀에 이 메소드를 호출한다.

이 메소드는 base class에서는 아무것도 하지 않는다. 상속 클래스는 이 메소드를 오버라이드(override) 할 수 있다, 예를 들어, 핀이 allocater를 데코밋트 하거나 하드웨어 리소스를 취득하거나.

필터 그래프 매니저의 내부 상태는 이 멤버 함수가 돌아갈 때까지 업데이트 되지 않기 때문에, 이 메소드로부터 상태를 테스트해서는 안된다.

CBasePin::AgreeMediaType

CBasePin 클래스

핀 접속을 하는 미디어 타입을 조사한다.

구문

virtual HRESULT AgreeMediaType(
    IPin *pReceivePin,
    const CMediaType *pmt
);

파라미터

pReceivePin
수신 핀의 IPin 인터페이스에의 포인터.
pmt
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터, 혹은 NULL.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NO_ACCEPTABLE_TYPES | 받아들이고 가능한 미디어 타입은 발견되지 않았다.

주의

pmt 파라미터가 NULL 이외로, 미디어 타입을 완전하게 지정하고 싶은들 , 이 메소드는 그 미디어 타입을 사용해 접속을 하려고 한다. 이것이 실패 하면, 이 메소드는 에러를 돌려준다.

pmt 파라미터가 NULL 혹은 파셜 미디어 타입이라면, 이 메소드는 다음의 순서로 미디어 타입을 시도한다 :

  1. 수신 핀의 허용 하는 미디어 타입.
  2. 이 핀의 허용 하는 미디어 타입.

허용 된 미디어 타입은 EnumMediaTypes 메소드로 열거되어 열거된 결과는 TryMediaTypes 메소드에게 건네진다.

CBasePin::AttemptConnection

CBasePin 클래스

지정한 미디어 타입을 사용하고 있는 다른 핀에의 접속.

구문

virtual HRESULT AttemptConnection(
    IPin *pReceivePin,
    const CMediaType *pmt
);

파라미터

pReceivePin
수신 핀의 IPin 인터페이스에의 포인터.
pmt
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_TYPE_NOT_ACCEPTED | 미디어 타입이 받아들여지지 않았다.

주의

이 메소드는 지정한 미디어 타입으로 2 개의 핀을 접속하려고 한다. 그 타입이 받아들여지지 않으면 이 메소드는 다른 미디어 타입을 시도하는 일 없이 실패한다.

미디어 타입이 받아들여졌다면, 이 메소드는 수신 핀의 IPin::ReceiveConnection 메소드를 호출한다. 다음에 CompleteConnect 메소드를 호출해, 접속을 완료한다.

CBasePin::BreakConnect

CBasePin 클래스

접속으로부터 핀을 해방한다

구문

virtual HRESULT BreakConnect(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 Disconnect 메소드에 의해 핀이 접속 해제하고 있는 동안에 불려 간다. CheckConnect 메소드가 실패 하면, 접속을 시도하는 동안에도 불려 간다.

이 메소드는 CheckConnect 메소드가 취득한 모든 리소스를 프리로 하지 않으면 안 된다. 예를 들어,CheckConnect 로 메모리를 할당했다면,BreakConnect 로 메모리를 프리에 해야 한다. CheckConnect 로 인터페이스의 접속 핀을 문의했다면,BreakConnect 로 인터페이스를 프리에 해야 한다.

CBasePin::CanReconnectWhenActive

CBasePin 클래스

핀이 동적재접속을 지원 할지 어떨지를 문의한다.

구문

bool CanReconnectWhenActive(void);

반환값

핀이 동적재접속 가능한가 어떤가를 나타내는 불리언 값을 돌려준다. TRUE 라면, 핀은 동적재접속 가능.

주의

디폴트에서는, 핀의 재접속을 하기 전에 필터를 정지해야 한다. 그러나, 핀이 동적재접속을 지원 한다면, 필터가 액티브한 동안에 재접속이 가능하다. 상세한 것에 대하여는, 「동적 그래프 생성」을 참조할것.

CBasePin::CBasePin

CBasePin 클래스

constructor　 　 메소드.

구문

CBasePin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pName,
    PIN_DIRECTION dir
);

파라미터

pObjectName
오브젝트의 핀명이 들어가는 캐릭터 라인의 포인터. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pFilter
이 핀을 생성 한 필터에의 포인터.
pLock
CCritSec 락에의 포인터, 상태 이행을 계속하기 위해서 이용된다. 필터 락 CBaseFilter.m_pLock 로서 같은 크리티컬 섹션 일수 있다.
phr
메소드의 성공·실패를 나타내는 HRESULT 값을 받는 변수에의 포인터. 이 값을 S_OK 에 초기화하고 나서, 오브젝트를 생성 한다. 이 값은, 에러가 발생했을 경우에만 변경된다.
pName
오브젝트의 핀명이 들어가는 Unicode™ 캐릭터 라인. 핀의 식별명은 그래프 계속성을 지원 한다. 상세한 것에 대하여는, 「QueryPinInfo 」를 참조할것.
dir
핀의 방향을 지정하는 PIN_DIRECTION 열거의 멤버.

주의

pLock 에 의해 지정된 크리티컬 섹션은 핀 상태를 계속하는, 상태와는 접속 상태, allocater의 선택, 미디어 타입, 피랏슈 조작 상태를 포함한다. 이 크리티컬 섹션을 스트리밍 조작의 계속에 사용해서는 안 된다. 상세한 것에 대하여는, 「필터 개발자가 사용하는 데이터 플로우」를 참조할것.

필터는 그 constructor　 　 메소드로 핀을 생성 할 가능성이 있으므로, 이 때 pFilter 포인터는 유효한 오브제트를 참조하지 않는 경우가 있다. 포인터를 스토어 하는 것, 그러나 핀의 constructor　 　 내의 사이는 그것을 재참조해서는 안 된다.

CBasePin::~CBasePin

CBasePin 클래스

소멸자 메소드.

구문

CBasePin(void);

CBasePin::CheckConnect

CBasePin 클래스

핀 접속이 적절한가 어떤가를 확인한다.

구문

virtual HRESULT CheckConnect(
    IPin *pPin
);

파라미터

pPin
다른 핀의 IPin 인터페이스에의 포인터.

반환값

이하의 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
VFW_E_INVALID_DIRECTION | 핀의 방향으로 호환성이 없다.

주의

이 메소드는 접속 처리의 종료시에 양쪽 모두의 핀을 불려 간다. 접속 핀은 CBasePin::Connect 메소드로부터 호출해, 수신 핀은 CBasePin::ReceiveConnection 메소드로부터 호출한다.

이 메소드를 사용해 pPin 파라미터에 의해 지정된 핀이 접속에 적절하고 있는지 어떤지를 확인하는 것. 양쪽 모두의 핀이 같은 향해(양쪽 모두 입력, 혹은 양쪽 모두 출력)라면, base class는 에러를 돌려준다. 상속 클래스는 이 메소드를 오버라이드(override) 해, 핀내의 다른 기능을 검증할 수가 있다. 예를 들어,CBaseOutputPin 클래스는 입력 핀에 그 IMemInputPin 인터페이스를 문의한다.

이 메소드가 실패 하면, 접속은 실패해 핀은 BreakConnect 메소드를 호출한다. CheckConnect 로 취득한 리소스를 프리로 하려면 BreakConnect 를 사용하는 것. 예를 들어,CheckConnect 가 QueryInterface 메소드를 호출한다면,BreakConnect 는 그 인터페이스를 해방해야 한다.

CBasePin::CheckMediaType

CBasePin 클래스

핀이 지정한 미디어 타입을 받아들일까를 묻는다.

구문

virtual HRESULT CheckMediaType(
    const CMediaType *pmt
) PURE;

파라미터

pmt
제안된 미디어 타입 포함한 CMediaType 오브젝트에의 포인터.

반환값

제안된 미디어 타입이 받아들여진다면 S_OK 를 돌려준다. 그렇지 않으면 S_FALSE 나 에러 코드를 돌려준다.

주의

상속 클래스는 이 순수 가상 메소드를 오버라이드(override) 해야 한다.

CBasePin::CompleteConnect

CBasePin 클래스

다른 핀에의 접속을 완료한다.

구문

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

파라미터

pReceivePin
다른 핀의 IPin 인터페이스에의 포인터.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 접속 처리의 마지막에 양쪽 모두의 핀으로 불려 간다. 접속 핀은 CBasePin::Connect 내로부터 호출해, 수신 핀은 CBasePin::ReceiveConnection 내로부터 호출한다.

base class에서는, 이 메소드는 다만 S_OK 를 돌려주는 것만으로 있다. 상속 클래스가 접속을 완료하는 요구를 가지고 있다면, 이 메소드를 오버라이드(override) 해야 한다. 예를 들어,CBaseOutputPin 클래스는 이 메소드를 사용해, 메모리 allocater를 결정한다.

이 메소드가 실패 하면, 모든 접속의 시도도 실패해, 핀은 수신 핀으로부터 떼어내진다.

CBasePin::Connect

CBasePin 클래스

핀을 다른 핀에 접속한다. IPin::Connect 메소드의 이행.

구문

HRESULT Connect(
    IPin *pReceivePin,
    const AM_MEDIA_TYPE *pmt
);

파라미터

pReceivePin
수신 핀의 IPin 인터페이스에의 포인터.
pmt
접속의 미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_ALREADY_CONNECTED | 핀은 이미 접속하고 있다.
VFW_E_NO_ACCEPTABLE_TYPES | 허용 가능한 미디어 타입을 발견할 수 없다.
VFW_E_NOT_STOPPED | 필터가 액티브해, 핀은 동적재접속을 지원 하고 있지 않다.
VFW_E_TYPE_NOT_ACCEPTED | 지정한 미디어 타입은 받아들여지지 않는다.

주의

pmt 파라미터는 NULL 를 취할 수 있다. 메이저 타입이나 서브 타입이나 포맷을 GUID_NULL 값으로 하는 것으로, 그것은 파셜 미디어 타입도 지정 할 수 있다.

base class에서는, 이 메소드는 핀이 벌써 접속되고 있는지, 필터가 정지하고 있는지를 테스트한다. 접속 처리의 나머지는 AgreeMediaType 메소드에 위임한다. /P>

CBasePin::ConnectedTo

CBasePin 클래스

만약 있으면, 이 핀에 접속하고 있는 핀을 취득한다. IPin::ConnectedTo 메소드의 이행.

구문

HRESULT ConnectedTo(
    IPin **ppPin
);

파라미터

ppPin
다른 핀의 IPin 인터페이스에의 포인터를 취득하는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

이 메소드가 성공하면(자), 그것이 돌려주는 IPin 인터페이스에는 참조 카운트가 남는다. 해방시에는 주의가 필요.

CBasePin::ConnectionMediaType

CBasePin 클래스

만약 있으면, 현재의 핀 접속의 미디어 타입을 취득한다. IPin::ConnectionMediaType 메소드의 이행.

구문

HRESULT ConnectionMediaType(
    AM_MEDIA_TYPE *pmt
);

파라미터

pmt
미디어 타입을 받는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
E_POINTER | Null 포인터 인수.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

핀이 접속되고 있다면, 이 메소드는 미디어 타입을 pmt 에 의해 지정되는 AM_MEDIA_TYPE 구조체에 카피한다. 호출원래는 미디어 타입의 포맷 블록을 프리로 하지 않으면 안 된다. Microsoft® Win32® CoTaskMemFree 를 사용한다, 혹은 FreeMediaType 헤르파 함수를 사용할 수가 있다.

만약 핀이 접속되어 있지 않으면, 이 메소드는 pmt 에 의해 지정된 메모리 블록을 제로로 해, 에러 코드를 돌려준다.

CBasePin::CurrentRate

CBasePin 클래스

CBasePin::NewSegment 메소드에 의해 세트 된 세그먼트(segment) 레이트를 취득한다.

구문

double CurrentRate(void);

반환값

m_dRate 의 반환값.

CBasePin::CurrentStartTime

CBasePin 클래스

CBasePin::NewSegment 메소드에 의해 세트 된 세그먼트(segment) 시작 타임을 취득한다.

구문

REFERENCE_TIME CurrentStartTime(void);

반환값

m_tStart 의 반환값.

CBasePin::CurrentStopTime

CBasePin 클래스

CBasePin::NewSegment 메소드에 의해 세트 된 세그먼트(segment) 종료 타임을 취득한다.

구문

REFERENCE_TIME CurrentStopTime(void);

반환값

m_tStop 의 값을 돌려준다.

CBasePin::Disconnect

CBasePin 클래스

현재의 핀 접속을 해제한다. IPin::Disconnect 메소드의 이행.

구문

HRESULT Disconnect(void);

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_FALSE | 핀이 접속되어 있지 않다.
S_OK | 성공.
VFW_E_NOT_STOPPED | 필터가 액티브해, 핀은 동적재접속을 지원 하고 있지 않다.

주의

base class는 일의 대부분을 DisconnectInternal 메소드에 위임한다.

CBasePin::DisconnectInternal

CBasePin 클래스

현재의 핀 접속을 해제한다.

구문

HRESULT DisconnectInternal(void);

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_FALSE | 핀이 접속되어 있지 않다.
S_OK | 성공.
VFW_E_NOT_STOPPED | 필터가 액티브해, 핀은 동적재접속을 지원 하고 있지 않다

주의

Disconnect 메소드는 접속 처리를 이 메소드에 위임한다. 이 메소드는 BreakConnect 메소드를 호출한다. 그것은 또 m_Connected 멤버 변수에 의해 보관 유지되고 있는 다른 핀의 참조 카운트를 해방한다.

CBasePin::DisplayPinInfo

CBasePin 클래스

디버그중에 핀 접속을 트레이스 한다.

구문

void DisplayPinInfo(
    IPin *pReceivePin
);

파라미터

pReceivePin
수신 핀에의 포인터

주의

디버그 빌드에서는, 이 메소드는 DbgLog 함수를 호출해, 접속의 시도를 트레이스 한다. 리테일 빌드에서는 이 메소드는 아무것도 하지 않는다.

CBasePin::DisplayTypeInfo

CBasePin 클래스

디버그중에 미디어 타입 정보를 표시한다.

구문

void DisplayTypeInfo(
    IPin *pPin,
    const CMediaType *pmt
);

파라미터

pPin
무시된다.
pmt
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터.

주의

디버그 빌드에서는, 이 메소드는 DbgLog 함수를 호출해, 접속의 시도를 트레이스 한다. 리테일 빌드에서는 이 메소드는 아무것도 하지 않는다.

CBasePin::EndOfStream

IPin Interface

핀에 추가 데이터는 이제 없는 것을 통지한다. IPin::EndOfStream 메소드의 이행. 이 메소드는 입력 핀에서만 호출하는 것.

구문

HRESULT EndOfStream(void);

반환값

S_OK 를 돌려준다.

주의

필터는 엔드 오브 스트림 통지 다운 스트림을 필터에 접속하고 있는 입력 핀에 건네주어야 하는 것이다. 필터가 렌더러라면,EC_COMPLETE 이벤트 통지를 필터 그래프 매니저에 보내야 하는 것이다. 상세한 것에 대하여는, 「필터 개발자가 사용하는 데이터 플로우」를 참조할것.

base class에서는, 이 메소드는 아무것도 하지 않는다. 상속 클래스는 이 메소드를 오버라이드(override) 해야 한다.

CBasePin::EnumMediaTypes

CBasePin 클래스

핀의 허용 하는 미디어 타입을 열거한다. IPin::EnumMediaTypes 메소드의 이행.

구문

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

파라미터

ppEnum
IEnumMediaTypes 인터페이스에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

입력 핀은 허용 할 수 있는 타입의 열거가 요구되지 않는다. 출력 핀은 적어도 1 개의 허용 타입을 열거해야 한다. 그렇게 하지 않으면 양쪽 모두의 핀에 허용 가능한 타입이 없어져, 접속이 불가능하게 된다.

표준적인 COM 열거자와 같게 IEnumMediaTypes 인터페이스는 동작한다. 상세한 것에 대하여는, 「필터 그래프내의 오브젝트의 열거」를 참조할것. 메소드가 성공하면(자),IEnumMediaTypes 인터페이스에는 참조 카운트가 남는다. 해방시에는 주의가 필요.

CEnumMediaTypes base class는 IEnumMediaTypes 를 이행 한다. 그것은 핀의 CBasePin::GetMediaType 메소드를 호출해, 미디어 타입을 열거한다.

CBasePin::GetConnected

CBasePin 클래스

이 핀에 접속하고 있는 핀을 취득.

구문

IPin *GetConnected(void);

반환값

다른 핀의 IPin 인터페이스에의 포인터를 돌려준다.

주의

핀이 접속하고 있지 않으면, 이 메소드는 NULL 를 돌려준다. CBasePin::IsConnected 메소드를 호출해, 핀이 접속되고 있는지 어떤지를 확인하는 것.

CBasePin::GetMediaType

CBasePin 클래스

허용 하는 미디어 타입을 인덱스값으로 취득한다.

구문

virtual HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

파라미터

iPosition
제로로부터 시작되는 인덱스값.
pMediaType
미디어 타입을 취득하는 CMediaType 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_S_NO_MORE_ITEMS | 인덱스가 범위외이다.
E_INVALIDARG | 인덱스가 제로보다 작다.
E_UNEXPECTED | 예기치 않은 에러.

주의

핀이 허용 가능한 미디어 타입의 리스트로부터, 이 메소드는 iPosition 값으로 그 타입을 돌려준다. CEnumMediaTypes 클래스는 이 메소드를 호출해 허용 가능한 미디어 타입을 열거한다.

base class는 E_UNEXPECTED 를 돌려준다. 상속 클래스로 이 메소드를 오버라이드(override) 하는 것.

CBasePin::GetMediaTypeVersion

CBasePin 클래스

허용 하는 미디어 타입 세트의 버젼수를 취득.

구문

virtual LONG GetMediaTypeVersion(void);

반환값

m_TypeVersion 멤버 변수를 돌려준다.

주의

CBasePin constructor　 　 은 버젼수를 1 으로 초기화한다. base class에서는, 이 수는 결코 변화하지 않는다. 핀이 동적으로 허용 가능한 미디어 타입의 리스트를 변경한다면, 리스트가 변경될 때마다 버젼수를 인크리먼트(increment) 해야 하는 것이다. 버젼수를 인크리먼트(increment) 하려면 ,IncrementTypeVersion 메소드를 호출하는 것.

CEnumMediaTypes 클래스에 의해 이행 되는 미디어 타입 열거자는, 버젼수를 사용해 그것 자신과 핀과의 동기를 유지한다.

CBasePin::Inactive

CBasePin 클래스

핀에 필터가 지금 이미 액티브하지 않는 것을 통지한다.

구문

virtual HRESULT Inactive(void);

반환값

S_OK 를 돌려준다.

주의

필터가 정지 하면,CBaseFilter 클래스는 필터에 접속된 것 모든 핀으로, 이 메소드를 호출한다.

이 메소드는 base class에서는 아무것도 하지 않는다. 상속 클래스는 이 메소드를 오버라이드(override) 해,Active 메소드가 취득한 모든 리소스를 프리에 해야 한다, 예를 들어 핀의 allocater를 데코밋트로 한다.

필터 그래프 매니저의 내부 상태는 이 메소드가 돌아갈 때까지 업데이트 되지 않기 때문에, 이 메소드로부터 상태를 테스트해서는 안 된다.

CBasePin::IncrementTypeVersion

CBasePin 클래스

허용 하는 미디어 타입 세트의 버젼수를 인크리먼트(increment) 한다.

구문

void IncrementTypeVersion(void);

주의

이 메소드는 m_TypeVersion 멤버 변수를 인크리먼트(increment) 한다. 핀이 동적으로 허용 하는 미디어 타입의 리스트를 변경한다면, 리스트가 변경될 때마다 이 메소드를 호출하는 것. 상세한 것에 대하여는, 「GetMediaTypeVersion 」를 참조할것.

CBasePin::IsConnected

CBasePin 클래스

핀이 다른 핀과 접속하고 있을지 어떨지를 확인한다.

구문

BOOL IsConnected(void);

반환값

핀이 접속되고 있으면 TRUE 를 돌려준다. 그렇지 않으면 FALSE 를 돌려준다.

CBasePin::IsStopped

CBasePin 클래스

이 핀을 포함한 필터가 정지하고 있을지 어떨지를 확인한다.

구문

BOOL IsStopped(void);

반환값

필터가 정지하고 있으면 TRUE 를 돌려준다. 그렇지 않으면 FALSE 를 돌려준다.

주의

CBasePin constructor　 　 메소드내로부터 이 메소드를 호출해서는 안 되는, 왜냐하면 필터는 아직 초기화되어 있지 않을 가능성이 있기 때문이다.

CBasePin::Name

CBasePin 클래스

핀의 식별명을 취득한다.

구문

LPWSTR Name(void);

반환값

m_pName 멤버 변수의 값을 돌려준다.

CBasePin::NewSegment

CBasePin 클래스

세그먼트(segment)로서 이 호출이 그룹화 된 다음에 미디어 샘플을 받은 것을 핀에 알린다. IPin::NewSegment 메소드의 이행.

구문

HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

파라미터

tStart
세그먼트(segment)의 시작 미디어 위치, 100 밀리 세컨드 단위.
tStop
세그먼트(segment)의 종료 미디어 위치, 100 밀리 세컨드 단위.
dRate
세그먼트(segment)가 처리되어야 할 레이트, 오리지날 레이트의 퍼센티지.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 m_tStart 와 m_tStop 와 m_dRate 멤버 변수를 설정한다. 상속 클래스에서는, 이 메소드를 오버라이드(override) 해, 통지 다운 스트림에 건네주는 것.

CBasePin::Notify

CBasePin 클래스

품질 변경이 요구된 것을 핀에 통지한다. IQualityControl::Notify 메소드의 이행.

구문

HRESULT Notify(
    IBaseFilter *pSelf,
    Quality q
);

파라미터

pSelf
품질 컨트롤 메세지를 출력하는 필터의 IBaseFilter 인터페이스에의 포인터.
q
품질 컨트롤 메세지를 포함한 Quality 구조체.

반환값

base class는 E_NOTIMPL 를 돌려준다.

주의

출력 핀은 이 메소드를 오버라이드(override) 해 품질 컨트롤 메세지를 접수한다.

외부의 품질 컨트롤 매니저가 인스톨 되고 있다면 ( 「SetSink 」를 참조), 메세지를 그 품질 매니저에 건네주는 것. 그렇지 않으면, 필터는 그 메세지를 자기 자신으로 취급한다, 혹은 메세지 업 스트림에 보내야 하는 것이다. 상세한 것에 대하여는, 「품질 컨트롤의 관리」를 참조할것.

CBasePin::QueryAccept

CBasePin 클래스

핀이 지정한 미디어 타입을 받아들일지 어떨지를 확인한다. IPin::QueryAccept 메소드의 이행.

구문

HRESULT QueryAccept(
    const AM_MEDIA_TYPE *pmt
);

파라미터

pmt
미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

미디어 타입이 받아들이고 가능하면 S_TRUE 를 돌려준다. 그렇지 않으면, S_FALSE 를 돌려준다.

주의

base class에서는, 이 메소드는 CheckMediaType 메소드에 위임한다. CheckMediaType 가 실패 하면,QueryAccept 는 S_FALSE 를 돌려준다.

이 메소드는 핀의 크리티컬 섹션 (m_pLock )을 보관 유지하지 않는다. 상속 클래스로 동적으로 허용 가능한 미디어 타입 세트를 수정한다면, 이 메소드를 오버라이드(override) 해 크리티컬 섹션을 hold 해야 한다.

CBasePin::QueryDirection

CBasePin 클래스

핀의 방향 (입력인가 출력인지)을 취득한다. IPin::QueryDirection 메소드의 이행.

구문

HRESULT QueryDirection(
    PIN_DIRECTION *pPinDir
);

파라미터

pPinDir
PIN_DIRECTION 열거형의 멤버를 받는 변수에의 포인터.

반환값

S_OK 혹은 E_POINTER 를 돌려준다.

CBasePin::QueryId

CBasePin 클래스

핀의 ID 를 취득한다. IPin::QueryId 메소드의 이행.

구문

HRESULT QueryId(
    LPWSTR *Id
);

파라미터

Id
핀의 ID 에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는 m_pName 멤버 변수를 돌려준다.

CBasePin::QueryInternalConnections

CBasePin 클래스

(필터내에서) 내부적으로 이 핀에 접속하고 있는 핀을 취득한다. IPin::QueryInternalConnections 메소드의 이행.

구문

HRESULT QueryInternalConnections(
    IPin *apPin,
    ULONG *nPin
);

파라미터

apPin
IPin 포인터의 배열의 주소.
nPin
입력으로는, 배열의 사이즈를 지정. 이 메소드가 돌아갈 때, 이 값은 배열하러 돌아온 포인터의 수가 세트 된다.

반환값

다음의 HRESULT 값의 1 개가 돌아간다.

S_FALSE | 배열의 사이즈가 부적당.
S_OK | 성공.
E_FAIL | 실패.
E_NOTIMPL | 이행되어 있지 않다.

base class는 E_NOTIMPL 를 돌려준다.

주의

몇개의 필터에서는, 입력 핀은 고유의 출력 핀에 대응하고 있다. 각 핀으로, 이 메소드는 대응하는 핀의 포인터로 배열을 묻는다. 모든 입력 핀이 모든 출력 핀에 데이터를 제공하는 경우는 E_NOTIMPL 를 돌려준다.

CBasePin::QueryPinInfo

CBasePin 클래스

핀에 대한 정보를 취득한다. IPin::QueryPinInfo 메소드의 이행.

구문

HRESULT QueryPinInfo(
    PIN_INFO *pInfo
);

파라미터

pInfo
핀 정보를 받는 PIN_INFO 구조체에의 포인터.

반환값

S_OK 혹은 E_POINTER 를 돌려준다.

주의

이 메소드는 PIN_INFO 구조체의 achName 멤버에 대해서 m_pName 멤버 변수를 사용한다.

메소드가 돌아갈 때, PIN_INFO 구조체의 pFilter 멤버가 NULL 이외라면, 참조 카운트가 남아 있다. 그 인터페이스를 해방하려면 주의가 필요.

CBasePin::ReceiveConnection

CBasePin 클래스

다른 핀으로부터의 접속을 받아들인다. IPin::ReceiveConnection 메소드의 이행.

구문

HRESULT ReceiveConnection(
    IPin *pConnector,
    AM_MEDIA_TYPE *pmt
);

파라미터

pConnector
접속 핀의 IPin 인터페이스에의 포인터.
pmt
미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
E_POINTER | Null 포인터 인수.
VFW_E_ALREADY_CONNECTED | 핀은 이미 접속하고 있다.
VFW_E_NOT_STOPPED | 필터가 액티브해, 핀은 동적재접속을 지원 하고 있지 않다
VFW_E_TYPE_NOT_ACCEPTED | 지정한 미디어 타입은 받아들여지지 않는다.

주의

접속을 시작하려고 하는 핀은 수신 핀으로 이 메소드를 호출한다. 수신 핀이 에러 코드를 돌려준다면, 접속은 실패한다.

base class에서는, 이 메소드는 다음의 스텝을 실행한다 :

  • 핀이 이미 접속하고 있지 않는지 어떤지 체크한다.
  • 필터가 정지하고 있지 않는지 어떤지 체크한다.
  • CheckConnect 메소드를 호출해 접속 핀이 적절한가 어떤가 테스트한다.
  • Calls CheckMediaType 메소드를 호출해 미디어 타입이 받아들이고 가능한가 어떤가 테스트한다.

이러한 모든 스텝이 성공하면(자), 이 메소드는 CompleteConnect 메소드와SetMediaType 메소드를 호출해 접속을 완료한다. CheckConnect 나 CheckMediaType 가 실패 하면, 이 메소드는 BreakConnect 메소드를 호출한다.

CBasePin::Run

CBasePin 클래스

필터가 지금 실행중인 것을 핀에 알린다.

구문

HRESULT Run(
    REFERENCE_TIME tStart
);

파라미터

tStart
필터의 IMediaFilter::Run 메소드에 보내지는 시작 타임.

반환값

S_OK 를 돌려준다.

주의

필터가 포즈로부터 실행이 될 때,CBaseFilter 클래스는 필터의 모든 핀으로 이 메소드를 호출한다.

이 메소드는 base class에서는 아무것도 하지 않는다. 상속 클래스는 이 메소드를 오버라이드(override) 할 수 있다. 예를 들어, 어느 핀은 샘플을 출력하는 워커 thread를 시작 할지도 모른다.

필터 그래프 매니저의 내부 상태는 이 멤버 함수가 돌아갈 때까지 업 데이터 되지 않기 때문에, 이 메소드로부터 상태를 테스트해서는 안 된다.

CBasePin::SetMediaType

CBasePin 클래스

접속하는 미디어 타입을 설정한다.

구문

virtual HRESULT SetMediaType(
    const CMediaType *pmt
);

파라미터

pmt
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 핀 접속의 포맷을 확립한다. 이 메소드를 호출하기 전에, 핀은 CBasePin::CheckMediaType 메소드를 호출해 미디어 타입이 받아들이고 가능한가 어떤가를 확인한다. 따라서,pmt 파라미터는 받아들이고 가능한 미디어 타입으로서 가정되고 있다.

base class에서는, 이 메소드는 m_mt 멤버 변수를 세트 해, S_OK 를 돌려준다. 미디어 타입이 세트 되었을 때 상속 클래스가 통지를 요구한다면, 그 상속 클래스는 이 메소드를 오버라이드(override) 할 수 있다.

CBasePin::SetReconnectWhenActive

CBasePin 클래스

핀이 동적재접속을 지원 할지 어떨지를 지정한다.

구문

void SetReconnectWhenActive(
    bool bCanReconnect
);

파라미터

bCanReconnect
핀이 동적재접속을 지원 할지 어떨지를 나타내는 불리언 값. TRUE 라면 핀은 동적재접속이 가능.

주의

디폴트에서는 핀에의 재접속전에 필터를 정지시키지 않으면 안 된다. 필터가 액티브한 동안에 재접속할 수 있다면, 이 메소드를 값을 TRUE 로 해 호출하는 것. 상세한 것에 대하여는, 「동적 그래프 생성」을 참조할것.

CBasePin::SetSink

CBasePin 클래스

외부의 품질 매니저를 설정한다. IQualityControl::SetSink 메소드의 이행.

구문

HRESULT SetSink(
    IQualityControl *piqc
);

파라미터

piqc
품질 매니저의 IQualityControl 인터페이스에의 포인터.

반환값

S_OK 를 돌려준다.

주의

이 메소드를 호출해 품질 컨트롤 매니저를 외부의 품질 매니저에 리디렉트 하는 것. 상세한 것에 대하여는, 「품질 컨트롤의 관리」를 참조할것.

CBasePin::TryMediaTypes

CBasePin 클래스

미디어 타입의 리스트를 주어 그러한 타입의 1 개를 사용해 접속을 완료하려고 시도한다.

구문

virtual HRESULT TryMediaTypes(
    IPin *pReceivePin,
    const CMediaType *pmt,
    IEnumMediaTypes *pEnum
);

파라미터

pReceivePin
수신 핀의 IPin 인터페이스에의 포인터.
pmt
가능한 미디어 타입을 한정하는 CMediaType 오브젝트에의 포인터, 혹은 NULL.
pEnum
미디어 타입 리스트를 열거하는데 이용한 IEnumMediaTypes 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 다음의 표는, 가능한 값을 나타내고 있다.

S_OK | 성공.
VFW_E_NO_ACCEPTABLE_TYPES | 받아들이고 가능한 미디어 타입이 없다.

주의

IEnumMediaTypes 인터페이스가 돌려준 각 미디어 타입으로, 이 메소드는 AttemptConnection 메소드를 호출해 접속을 시도한다.

pmt 파라미터가 NULL 이외라면, 핀은 이 타입에 적합하지 않는 미디어 타입을 스킵 한다. pmt 파라미터에는 파셜 미디어 타입을 지정할 수가 있다. 파셜 미디어 타입은 메이저 타입, 서브 타입, 포맷중 한쪽이 GUID_NULL 값을 가진다. GUID_NULL 값은 「와일드 카드」값과 같이 어떤 타입과도 적합한다.


CBasePropertyPage 클래스

CBasePropertyPage 클래스의 계층

필터에 프로퍼티 페이지를 이행 해, 필터의 커스텀 프로퍼티에의 액세스를 제공할 수 있다. GraphEdit 는 이러한 프로퍼티 페이지를 표시하므로, 이것은 필터의 개발 및 디버그에 편리하다. 또, Microsoft® Windows Media™ Player 컨트롤은, 그 하위의 필터 그래프내의 필터에, 지원 하는 프로퍼티 페이지를 문의해 그것을 유저에 대해서 공개한다. 이 예로서 프로퍼티 페이지를 사용해 품질관리 정보를 공개하는 비디오 렌더러가 있다.

이 클래스는, 필터에 관련지을 수 있었던 프로퍼티 페이지의 체제를 제공해,IPropertyPage 인터페이스를 이행 한다. 프로퍼티 페이지는 Component Object Model (COM) 오브젝트이며, 필요에 따라서 로드 되는 다이알로그 박스의 리소스 ID 를 사용해 생성 할 필요가 있다. 또, 생성시에 타이틀 캐릭터 라인의 리소스 ID 도 지정해야 한다.

IPropertyPage 인터페이스 메소드의 이행에 가세해, 이 클래스는 상속 클래스로 오버라이드(override) 해 특수화 할 수가 있는 몇개의 가상 멤버 함수 (디폴트에서는 NOERROR 를 돌려준다)를 제공한다. 이러한 가상 멤버 함수는, 특정의 이벤트가 발생 하면 불려 간다. 예를 들어, 프로퍼티 페이지가 액티브 또는 비액티브 되었을 때, 접속 또는 절단 되었을 때, 프로퍼티에 대한 변경이 적용되었을 때, 다이알로그 박스에의 메세지가 수신되었을 때 등이다.

커스텀 프로퍼티 페이지를 공개하는 필터는, 커스텀 인터페이스를 사용해 어플리케이션에도 같은 기능을 공개할 필요가 있다. 기능을 공개하지 않으면 어플리케이션은 프로퍼티 페이지를 표시하지 않고 필터를 제어할 수가 없다. 예를 들어, 비디오 렌더러는 IQualProp 인터페이스를 지원 해, 같은 품질관리 정보에 액세스 한다. 실제, 렌더러의 프로퍼티 페이지는, 이 인터페이스를 사용해 프로퍼티 페이지의 정보를 취득한다. 어플리케이션이 용이하게 커스텀 인터페이스에 액세스 할 수 있도록(듯이), 필터는 PID 도 이행 할 필요가 있다. PID 는, 필터 그래프 매니저에 의해 집성 된 오브젝트이다. 보통, PID 는 어플리케이션으로부터 필터 인터페이스에 호출을 건네주는 것에 의해, 관련지을 수 있었던 필터의 인터페이스를 이행 한다.

프로텍트 데이터 멤버

m_bDirty | 무엇인가가 변경되었는지 어떠했는지를 나타내는 플래그.
m_DialogId | 다이알로그 박스의 리소스 식별자.
m_Dlg | 프로퍼티 페이지의 다이알로그 박스 윈도우 핸들.
m_hwnd | 프로퍼티 페이지의 윈도우 핸들.
m_pPageSite | 필터의 프로퍼티 정보에 액세스 하기 위해서 사용되는 IPropertyPage 인터페이스의 포인터.
m_TitleId | 프로퍼티 페이지의 타이틀의 리소스 식별자.

멤버 함수

CBasePropertyPage CBasePropetyPage 오브젝트를 생성 한다.

오버라이드(override) 가능한 멤버 함수

OnActivate | 프로퍼티 페이지가 액티브하게 되었을 때에 불려 간다.
OnApplyChanges | 유저가 프로퍼티 페이지에 대한 변경을 적용했을 때에 불려 간다.
OnConnect | 프로퍼티 페이지가 필터에 접속되었을 때에 불려 간다.
OnDeactivate | 프로퍼티 페이지가 소거되었을 때에 불려 간다.
OnDisconnect | 프로퍼티 페이지가 소유하는 필터로부터 절단 되었을 때에 불려 간다.
OnReceiveMessage | 메세지가 프로퍼티 페이지의 다이알로그 박스 윈도우에 송신되었을 때에 불려 간다.

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingAddRef | 디폴트의 이행은, 소유하는 필터의 참조 카운트를 인크리먼트(increment) 한다.
NonDelegatingQueryInterface | CBasePropertyPage 인터페이스를 취득하기 위해서 불려 간다. 상속 클래스로 추가되는 인터페이스에 포인터를 건네주려면 , 이 멤버 함수를 오버라이드(override) 한다.
NonDelegatingRelease | 디폴트의 이행은, 소유하는 필터의 참조 카운트를 감소 한다.

이행 되는 IPropertyPage 메소드

Activate | 프로퍼티 페이지의 다이알로그 박스 윈도우를 생성 한다.
Apply | 현재의 프로퍼티 페이지의 값을 하위의 오브젝트에 적용한다.
Deactivate | CBasePropertyPage::Activate 로 생성 한 윈도우를 파기한다.
GetPageInfo | 프로퍼티 페이지에 관한 정보를 취득한다.
Help | 유저 요구에 응답해 헬프를 호출한다.
IsPageDirty | 프로퍼티 페이지가, 액티브하게 된 후, 또는 CBasePropertyPage::Apply 를 마지막으로 호출한 후, 변경되었는지 어떠했는지를 나타낸다.
Move | 프로퍼티 페이지의 다이알로그 박스를 프레임내에 배치 및 사이즈 변경한다.
SetObjects | 이 프로퍼티 페이지에 관련지을 수 있었던 오브젝트의 IUnknown 포인터의 배열을 프로퍼티 페이지에 제공한다.
SetPageSite | 프로퍼티 페이지를 초기화해, 프로퍼티 페이지가 프로퍼티 프레임과 통신하기 위해서 사용하는 IPropertyPageSite 인터페이스에의 포인터를 프로퍼티 페이지에 제공한다.
Show | 프로퍼티 페이지의 다이알로그 박스를 표시 또는 비표시로 한다.
TranslateAccelerator | 처리하는 키스트로크(keystroke)를 지정하는 MSG 구조체에의 포인터를 제공한다.

CBasePropertyPage::Activate

CBasePropertyPage 클래스

프로퍼티 페이지의 다이알로그 박스를 생성 한다.

구문

HRESULT Activate(
HWND hwndParent,
LPCRECT prect,
BOOL fModal
    );

파라미터

hwndParent
다이알로그 박스의 부모 윈도우의 핸들.
prect
다이알로그 박스의 화면상의 위치를 저장 하는 RECT 구조체에의 포인터.
fModal
TRUE 의 경우는 모덜 다이알로그 박스, FALSE 의 경우는 모드레스다이아로그복스를 지정하는 값.

반환값

다이알로그 박스의 생성에 실패했을 경우는 E_OUTOFMEMORY, 프로퍼티 페이지가 이미 존재하고 있는 경우는 E_UNEXPECTED 를 돌려준다.

주의

이 멤버 함수는, COM 의 IPropertyPage::Active 메소드를 이행 한다. 이 메소드는, 부모 윈도우로서 hwndParent 를, 배치 직사각형으로서 prect 를 사용해, (프레임, 캡션, 시스템 메뉴, 또는 컨트롤이 없다) 프로퍼티 페이지의 다이알로그 박스를 생성 한다.

프로퍼티 페이지는 이 처리로 생성 한 윈도우 핸들을 보관 유지해,CBasePropertyPage::Deactivate 로 이 다이알로그 박스를 파기할 경우에 사용한다.

CBasePropertyPage::Apply

CBasePropertyPage 클래스

현재의 프로퍼티 페이지의 값을 하위의 오브젝트에 적용한다.

구문

HRESULT Apply(void);

반환값

CBasePropertyPage::SetObjects 가 불려 가지 않은 경우, 또는 m_pPageSite 데이터 멤버가 필터의 프로퍼티 페이지로의 포인터를 사용해 초기화되어 있지 않은 경우는, E_UNEXPECTED 를 돌려준다.

주의

이 멤버 함수는, COM 의 IPropertyPage::Apply 메소드를 이행 한다. 변경되는 오브젝트는,CBasePropertyPage::SetObjects 에의 이전의 호출에 의해 제공된다. 이것은, 필터의 IUnknown 인터페이스가 아니면 안된다. 따라서, 이 멤버 함수는, 인터페이스가 존재하지 않는 경우에 실패해서는 안 된다.

이 멤버 함수는,m_bDirty 데이터 멤버를 FALSE 로 설정해, 가상 멤버 함수 CBasePropertyPage::OnApplyChanges 를 호출한다. 프로퍼티에 대한 변경을 적용하려면 , 상속 클래스로 이 가상 멤버 함수를 오버라이드(override) 할 필요가 있다.

CBasePropertyPage::CBasePropertyPage

CBasePropertyPage 클래스

CBasePropetyPage 오브젝트를 생성 한다.

구문

CBasePropertyPage(
TCHAR *pName,
LPUNKNOWN pUnk,
int DialogId,
int TitleId
    );

파라미터

pName
디버그를 위해서(때문에) 사용되는 프로퍼티 페이지 오브젝트의 이름에의 포인터.
pUnk
COM 위임 오브젝트에의 포인터.
DialogId
다이알로그 박스의 리소스 ID.
TitleId
다이알로그 박스의 타이틀의 리소스 ID.

주의

이 constructor　 　 은,CBasePropertyPage 데이터 멤버를 다음과 같이 설정한다.

  • m_DialogId 는 DialogId 로 설정된다.
  • m_TitleId 는 TitleId 로 설정된다.
  • m_hwnd 는 NULL 로 설정된다.
  • m_Dlg 는 NULL 로 설정된다.
  • m_pPageSite 는 NULL 로 설정된다.
  • m_bDirty 는 FALSE 로 설정된다.

CBasePropertyPage::Deactivate

CBasePropertyPage 클래스

CBasePropertyPage::Activate 로 생성 한 윈도우를 파기한다.

구문

HRESULT Deactivate(void);

반환값

데이터 멤버 m_hwnd 가 프로퍼티 페이지의 윈도우 핸들을 포함하지 않은 경우는, E_UNEXPECTED 를 돌려준다.

주의

이 멤버 함수는, COM 의 IPropertyPage::Deactivate 메소드를 이행 한다. 이 멤버 함수는, 가상 멤버 함수 CBasePropertyPage::OnDeactivate 를 호출해, 프로퍼티 페이지의 다이알로그 박스를 파기한다.

CBasePropertyPage::GetPageInfo

CBasePropertyPage 클래스

프로퍼티 페이지에 관한 정보를 취득한다.

구문

HRESULT GetPageInfo(
LPPROPPAGEINFO pPageInfo
    );

파라미터

pPageInfo
프로퍼티 페이지가 그 페이지 정보를 저장 하는, 호출원 할당하고가 끝난 PROPPAGEINFO 구조체에의 포인터. 이 구조체에 저장 되는 모든 할당은, 호출원의 책임이 된다.

반환값

함수가 프로퍼티 페이지의 타이틀에 메모리를 할당할 수가 없었던 경우는, E_OUTOFMEMORY 를 돌려준다.

주의

이 멤버 함수는, COM 의 IPropertyPage::GetPageInfo 메소드를 이행 한다. 이 멤버 함수는,GetDialogSize 함수를 호출해, 다이알로그 박스의 사이즈를 취득해, 이 호출이 실패했을 경우는 다이알로그 박스의 사이즈를 디폴트값으로 설정한다.

CBasePropertyPage::Help

CBasePropertyPage 클래스

유저 요구에 응답해 헬프를 호출한다.

구문

HRESULT Help(
LPCWSTR lpszHelpDir
    );

파라미터

lpszHelpDir
레지스트리내에서 프로퍼티 페이지의 CLSID 정보의 HelpDir 키아래에 있는 캐릭터 라인에의 포인터. HelpDir 가 존재하지 않는 경우는, InProcServer32 엔트리로 발견된 패스로부터 서버 파일명을 제외한 것이 된다.

반환값

디폴트에서는 E_NOTIMPL 를 돌려준다.

주의

이 멤버 함수는, COM 의 IPropertyPage::Help 메소드를 이행 하지만, 플레이스홀더로서이다. 이 함수는, E_NOTIMPL 를 돌려주는 이외는 아무것도 하지 않는다.

이 멤버 함수의 호출은,CBasePropertyPage::Activate 의 호출과 CBasePropertyPage::Deactivate 의 호출동안에서 실시할 필요가 있다.

페이지가 이 멤버 함수로 실패했을 경우 (E_NOTIMPL 등), 프레임은 CBasePropertyPage::GetPageInfo 를 사용해 취득된 PROPPAGEINFO 구조체의 pszHelpFile 및 dwHelpContext 필드를 사용하려고 한다. 따라서, 상속 클래스는 CBasePropertyPage::Help 를 이행 하는지,CBasePropertyPage::GetPageInfo 를 사용해 헬프 정보를 돌려줄 필요가 있다.

CBasePropertyPage::IsPageDirty

CBasePropertyPage 클래스

프로퍼티 페이지가, 액티브하게 된 후, 또는 CBasePropertyPage::Apply 를 마지막으로 호출한 후, 변경되었는지 어떠했는지를 나타낸다.

구문

HRESULT IsPageDirty(void);

반환값

프로퍼티 페이지의 값 상태가 더티인 경우, 즉, 값이 변경되어 오브젝트 상태와 다른 경우는, S_OK 를 돌려준다. 페이지의 값 상태가 변경되지 않고, 오브젝트의 현재 상태와 같은 경우는, S_FALSE 를 돌려준다.

주의

이 멤버 함수는, COM 의 IPropertyPage::IsPageDirty 메소드를 이행 한다. 이 멤버 함수는,m_bDirty 데이터 멤버의 값을 돌려준다.

CBasePropertyPage::Move

CBasePropertyPage 클래스

프로퍼티 페이지의 다이알로그 박스를 프레임내에 배치 및 사이즈 변경한다.

구문

HRESULT Move(
LPCRECT prect
    );

파라미터

prect
프로퍼티 페이지의 다이알로그 박스의 위치 정보를 저장 하는 RECT 구조체에의 포인터.

반환값

데이터 멤버 m_hwnd 가 프로퍼티 페이지의 윈도우 핸들을 포함하지 않은 경우는, E_UNEXPECTED 를 돌려준다.

주의

이 멤버 함수는, Microsoft® Win32® MoveWindow 함수를 호출하는 것에 의해, COM 의 IPropertyPage::Move 메소드를 이행 한다. 이 멤버 함수는, 프로퍼티 페이지의 다이알로그 박스를 배치하기 위해서,CBasePropertyPage::Activate 멤버 함수로부터 불려 간다.

CBasePropertyPage::NonDelegatingAddRef

CBasePropertyPage 클래스

인터페이스의 참조 카운트를 인크리먼트(increment) 한다.

구문

ULONG NonDelegatingAddRef(void);

반환값

오브젝트의 참조 카운트를 돌려준다.

주의

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingAddRef 메소드를 이행 한다. 소유하는 필터의 참조 카운트를 인크리먼트(increment) 한다.

CBasePropertyPage::NonDelegatingQueryInterface

CBasePropertyPage 클래스

인터페이스를 취득해, 참조 카운트를 인크리먼트(increment) 한다.

구문

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 해,IPropertyPage 인터페이스에의 참조를 건네준다. 다음에, base class의 멤버 함수 CUnknown::NonDelegatingQueryInterface 를 호출한다. 이 클래스를 오버라이드(override) 해, 상속 클래스의 오브젝트의 그 외의 인터페이스를 돌려준다.

CBasePropertyPage::NonDelegatingRelease

CBasePropertyPage 클래스

인터페이스의 참조 카운트를 감소 한다.

구문

ULONG NonDelegatingRelease(void);

반환값

참조 카운트를 돌려준다.

주의

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingRelease 메소드를 이행 한다. 이것은 소유하는 필터에의 참조 카운트를 해방한다.

CBasePropertyPage::OnActivate

CBasePropertyPage 클래스

프로퍼티 페이지가 액티브하게 되었을 때에 불려 간다.

구문

virtual HRESULT OnActivate(void);

반환값

디폴트에서는 NOERROR 를 돌려준다. 오버라이드(override) 하는 멤버 함수는, 유효한 HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 프로퍼티 페이지가 표시되었을 때에 상속 클래스에 통지하기 위해서,CBasePropertyPage::Activate 멤버 함수로부터 불려 간다. 다이알로그 박스의 값을 초기화하려면 , 이 멤버 함수를 오버라이드(override) 한다. 이 처리는, (오버라이드(override) 된 CBasePropertyPage::OnConnect 멤버 함수로) 프로퍼티 페이지가 접속되었을 때에 초기화된 이전의 데이터 멤버의 값을 사용해 Win32 SetDlgItemText 함수를 호출하는 것에 의해 실시할 수가 있다.

다음에 예를 나타낸다.

// 프로퍼티 페이지의 텍스트 필드를 설정한다.

HRESULT CQualityProperties::OnActivate()
{
SetEditFieldData();
return NOERROR;
}

// 프로퍼티 페이지의 필드를 초기화한다.

void CQualityProperties::SetEditFieldData()
{
ASSERT(m_pQualProp);
TCHAR buffer[50];

wsprintf(buffer,"%d", m_iDropped);
SendDlgItemMessage(m_Dlg, IDD_QDROPPED, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d", m_iDrawn);
SendDlgItemMessage(m_Dlg, IDD_QDRAWN, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d. %02d", m_iFrameRate/100, m_iFrameRate%100);
SendDlgItemMessage(m_Dlg, IDD_QAVGFRM, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d", m_iFrameJitter);
SendDlgItemMessage(m_Dlg, IDD_QJITTER, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d", m_iSyncAvg);
SendDlgItemMessage(m_Dlg, IDD_QSYNCAVG, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d", m_iSyncDev);
SendDlgItemMessage(m_Dlg, IDD_QSYNCDEV, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
}

CBasePropertyPage::OnApplyChanges

CBasePropertyPage 클래스

유저가 프로퍼티 페이지에 대한 변경을 적용했을 때에 불려 간다.

구문

virtual HRESULT OnApplyChanges(void);

반환값

디폴트에서는 NOERROR 를 돌려준다. 오버라이드(override) 하는 멤버 함수는, 유효한 HRESULT 값을 돌려준다.

주의

프로퍼티 페이지로 유저가 프로퍼티값을 설정할 수 있는 경우는, 이 멤버 함수를 오버라이드(override) 한다. 이 멤버 함수가 불려 가면(자), 변경된 프로퍼티가 처리된다. 예를 들어, 상속 클래스로 적절한 데이터 멤버를 새로운 값으로 설정하거나 필터로 메소드를 호출해 프로퍼티를 설정한다. 이 멤버 함수가 종료할 경우에, 오브젝트내의 프로퍼티가 프로퍼티 페이지내의 프로퍼티를 반영하지 않는 경우는, 오버라이드(override) 하는 멤버 함수로 CBasePropertyPage::IsPageDirty 를 호출해 m_bDirty 데이터 멤버를 TRUE 로 설정한다.

CBasePropertyPage::OnConnect

CBasePropertyPage 클래스

프로퍼티 페이지가 필터에 접속되었을 때에 불려 간다.

구문

virtual HRESULT OnConnect(
IUnknown *pUnknown
    );

파라미터

pUnknown
프로퍼티 페이지에 관련지을 수 있었던 필터의 IUnknown 인터페이스에의 포인터.

반환값

디폴트에서는 NOERROR 를 돌려준다. 오버라이드(override) 하는 멤버 함수는, 유효한 HRESULT 값을 돌려준다.

주의

이 멤버 함수는,CBasePropertyPage::SetObjects 멤버 함수로부터 ppUnk 파라미터를 지정해 불려 간다. 이 파라미터는 필터의 IUnknown 인터페이스가 아니면 안된다. 다음에 (CBasePropertyPage::OnActivate 로) 프로퍼티 페이지의 다이알로그 박스에 송신되는 프로퍼티값을 취득하려면 , 이 멤버 함수를 오버라이드(override) 한다.

다음의 예는, 이 멤버 함수의 사용 방법을 나타내고 있다.

// 통신하기 위한 필터를 지정한다.

HRESULT CQualityProperties::OnConnect(IUnknown *pUnknown)
{
ASSERT(m_pQualProp == NULL);

// 렌더러에 IQualProp 인터페이스를 문의한다.

HRESULT hr = pUnknown->QueryInterface(IID_IQualProp, (void **) &m_pQualProp);
if (FAILED(hr)) {
return E_NOINTERFACE;
    }

ASSERT(m_pQualProp);

// 페이지의 품질 데이터를 취득한다.

m_pQualProp->get_FramesDroppedInRenderer(&m_iDropped);
m_pQualProp->get_FramesDrawn(&m_iDrawn);
m_pQualProp->get_AvgFrameRate(&m_iFrameRate);
m_pQualProp->get_Jitter(&m_iFrameJitter);
m_pQualProp->get_AvgSyncOffset(&m_iSyncAvg);
m_pQualProp->get_DevSyncOffset(&m_iSyncDev);
return NOERROR;
}

CBasePropertyPage::OnDeactivate

CBasePropertyPage 클래스

프로퍼티 페이지가 소거되었을 때에 불려 간다.

구문

virtual HRESULT OnDeactivate(void);

반환값

디폴트에서는 NOERROR 를 돌려준다. 오버라이드(override) 하는 멤버 함수는, 유효한 HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 유저가 프로퍼티 페이지를 닫았을 때에,CBasePropertyPage::Deactivate 멤버 함수로부터 불려 간다. 그 시점에서 특별한 처리를 실시하려면 , 이 멤버 함수를 오버라이드(override) 한다.

CBasePropertyPage::OnDisconnect

CBasePropertyPage 클래스

프로퍼티 페이지가 소유하는 필터로부터 절단 되었을 때에 불려 간다.

구문

virtual HRESULT OnDisconnect(void);

반환값

디폴트에서는 NOERROR 를 돌려준다. 오버라이드(override) 하는 멤버 함수는, 유효한 HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 프로퍼티 페이지가 필터로부터 절단 되었을 때에,CBasePropertyPage::SetObjects 멤버 함수로부터 불려 간다. 하위의 프로퍼티 인터페이스로 참조 카운트를 해방하는 등, 그 시점에서 특별한 처리를 실시하려면 , 이 멤버 함수를 오버라이드(override) 한다.

다음의 예는, 이 멤버 함수를 상속 클래스에 이행 하는 방법을 나타내고 있다.

// 보관 유지하고 있는 IQualProp 인터페이스를 해방한다.

HRESULT CQualityProperties::OnDisconnect()
{
// 인터페이스를 해방한다.

if (m_pQualProp == NULL) {
return E_UNEXPECTED;
    }

m_pQualProp->Release();
m_pQualProp = NULL;
return NOERROR;
}

CBasePropertyPage::OnReceiveMessage

CBasePropertyPage 클래스

메세지가 프로퍼티 페이지의 다이알로그 박스에 송신되었을 때에 불려 간다.

구문

virtual BOOL OnReceiveMessage(
HWND hwnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
    );

파라미터

hwnd
메세지를 수신하는 윈도우 프로시저.
uMsg
메세지.
wParam
추가의 메세지 정보. 이 파라미터의 내용은,uMsg 파라미터의 값에 따라서 다르다.
lParam
추가의 메세지 정보. 이 파라미터의 내용은,uMsg 파라미터의 값에 따라서 다르다.

반환값

디폴트에서는, Win32 DefWindowProc 함수에 의해 돌려주어지는 값을 돌려준다.

주의

이 멤버 함수의 디폴트의 이행은, 지정된 파라미터를 사용해 DefWindowProc 를 호출한다. 메세지에 특별한 처리가 필요한 경우는, 이 멤버 함수를 오버라이드(override) 한다.

CBasePropertyPage::SetObjects

CBasePropertyPage 클래스

이 프로퍼티 페이지에 관련지을 수 있었던 오브젝트의 IUnknown 포인터를 프로퍼티 페이지에 제공한다.

구문

HRESULT SetObjects(
ULONG cObjects,
LPUNKNOWN *ppUnk
    );

파라미터

cObjects
ppUnk 로 나타나는 배열내의 IUnknown 포인터의 수. 이 수치는 1 또는 0 이 아니면 안된다. 0 의 경우, 프로퍼티는 이전에 이 메소드에게 건네진 포인터를 해방해야 한다.
ppUnk
이 프로퍼티 페이지 ( 및 그 외의 프로퍼티 페이지)가 표시되는 프로퍼티 시트에 의해 영향을 받는 일의의 오브젝트를 식별하는 단일의 IUnknown 인터페이스에의 포인터의 주소. 프로퍼티 페이지는,IUnknown::AddRef 를 호출하는 것에 의해, 이 포인터를 캐쉬해야 한다.

반환값

ppUnk 가 Null 의 경우는 E_POINTER,cObjects 가 1 보다 큰 경우는 E_UNEXPECTED, 그 이외의 경우는 이 멤버 함수가 호출한 CBasePropertyPage::OnConnect 또는 CBasePropertyPage::OnDisconnect 멤버 함수에 의해 돌려주어진 값을 돌려준다.

주의

이 멤버 함수는, COM 의 IPropertyPage::SetObjects 메소드를 이행 한다. 이 멤버 함수는,cObjects 의 값이 1 의 경우는 가상 멤버 함수 CBasePropertyPage::OnConnect 을 호출해,cObjects 의 값이 0 의 경우는 가상 멤버 함수 CBasePropertyPage::OnDisconnect 를 호출한다. 이 프로퍼티 페이지가 적용되는 인터페이스를 취득하거나 (IUnknown::AddRef 를 호출한다), 해방하려면 (IUnknown::Release 를 호출하기) , 이 가상 멤버 함수를 오버라이드(override) 한다.

호출원래는,CBasePropertyPage::Activate 를 호출하기 전에, 이 오브젝트를 프로퍼티 페이지에 제공해, 페이지를 비액티브하게 하면 와, 또는 오브젝트를 완전하게 해방할 경우에, 파라미터로서 0-v 를 지정해 SetObjects 를 호출할 필요가 있다.

이 멤버 함수에서는, 오브젝트를 1 개만 프로퍼티 페이지에 관련지을 수가 있다.

CBasePropertyPage::SetPageSite

CBasePropertyPage 클래스

프로퍼티 페이지를 초기화해, 프로퍼티 페이지가 프로퍼티 프레임과 통신하기 위해서 사용하는 IPropertyPageSite 인터페이스에의 포인터를 프로퍼티 페이지에 제공한다.

구문

HRESULT SetPageSite(
LPPROPERTYPAGESITE pPageSite
    );

파라미터

pPageSite
프로퍼티 시트내의 이 프로퍼티 페이지를 관리해, 서비스를 제공하는 페이지 사이트의 IPropertyPageSite 인터페이스에의 포인터.

반환값

m_pPageSite 데이터 멤버가 필터의 프로퍼티 페이지로의 포인터를 사용해 초기화되어 있지 않은 경우는, E_UNEXPECTED 를 돌려준다.

주의

이 멤버 함수는, COM 의 IPropertyPage::SetPageInfo 메소드를 이행 한다. IPropertyPageSite 인터페이스가 건네받으면(자), 이 멤버 함수는 인터페이스에의 참조를 카운트 해,m_pPageSite 에 할당한다. Null 값이 건네받으면(자),IPropertyPageSite 인터페이스의 참조 카운트를 해방한다.

CBasePropertyPage::Show

CBasePropertyPage 클래스

프로퍼티 페이지의 다이알로그 박스를 표시 또는 비표시로 한다.

구문

HRESULT Show(
UINT nCmdShow
    );

파라미터

nCmdShow
표시할지 어떨지를 기술하는 커멘드. SW_SHOWNORMAL, SW_SHOW, 및 SW_HIDE 마셔 사용할 수 있다.

반환값

데이터 멤버 m_hwnd 가 프로퍼티 페이지의 윈도우 핸들을 포함하지 않은 경우는, E_UNEXPECTED 를 돌려준다. nCmdShow 파라미터가, SW_SHOW, SW_SHOWNORMAL (표시) 또는 SW_HIDE (비표시)가 아닌 경우는, E_INVALIDARG 를 돌려준다.

주의

페이지가 표시로 설정되었을 경우, 페이지는 그 페이지 자체에 포커스를 설정할 필요가 있다. 구체적으로는, 페이지의 최초의 프로퍼티에 포커스를 설정한다. 이 멤버 함수는, COM 의 IPropertyPage::Show 메소드를 이행 한다. 이 멤버 함수는,nCmdShow 의 값을 SHOW_NORMAL 로 해,CBasePropertyPage::Activate 멤버 함수를 종료하기 직전에 불려 간다.

CBasePropertyPage::TranslateAccelerator

CBasePropertyPage 클래스

처리하는 키스트로크(keystroke)를 지정하는 MSG 구조체에의 포인터를 제공한다.

구문

HRESULT TranslateAccelerator(
LPMSG lpMsg
    );

파라미터

lpMsg
처리하는 키스트로크(keystroke)를 기술하는 MSG 구조체에의 포인터.

반환값

디폴트에서는 E_NOTIMPL 를 돌려준다.

주의

이 멤버 함수는, COM 의 IPropertyPage::TranslateAccelerator 메소드를 이행 한다. 이 멤버 함수의 호출은,CBasePropertyPage::Activate 를 호출한 후, 대응하는 CBasePropertyPage::Deactivate 를 호출하기 전에 실시할 필요가 있다. 프로퍼티 페이지의 단축 키를 이행 하려면 , 이 멤버 함수를 오버라이드(override) 한다.


CBaseReferenceClock 클래스

CBaseReferenceClock 클래스의 계층

선언 : Refclock.h

이 클래스는,IReferenceClock 인터페이스를 지원 하는 기준 클락을 이행 한다. 하드웨어 디바이스에 액세스 하는 등 해, 필터가 필터 그래프에 기준 클락을 제공할 수 있는 경우, 필터는 이 클래스를 사용해 클락을 이행 한다.

CBaseReferenceClock 오브젝트는, 다음의 2 개의 개별의 타임값을 유지한다.

  • 내부적으로는,GetPrivateTime 메소드가, 클락에 의해 유지되고 있는 실제의 타임을 돌려준다.
  • 외부적으로는,GetTime 메소드가, 필터 그래프의 기준 타임을 돌려준다.

내장 시계가 단시간에 걸쳐서 돌아오는 것은 유효하다. 예를 들어, 클락이 진행되었을 경우, 필터는 역방향으로 조정할 수 있다. 상세한 것에 대하여는, 「SetTimeDelta 」를 참조할것. GetTime 메소드는,GetPrivateTime 에 의해 보고된 타임값을 사용한다. 그러나, 기준 타임은단조 증가하고 있다. 즉, 결코 돌아올 것은 없다. 그 때문에, 내장 시계가 돌아왔을 경우,GetTime 는 내장 시계가 따라잡을 때까지 낡은 타임을 계속 보고한다.

예를 들어, 2 개의 메소드가 다음의 순서를 돌려준다고 한다.

GetPrivateTime: 105, 106, 103, 104, 105, 106, 107, 108
GetTime:        105, 106, 106, 106, 106, 106, 107, 108

3 번째의 크로크틱에서는, 내장 시계는 103 에 돌아오고 있다. GetTime 메소드는, 내장 시계가 따라잡을 때까지, 106 을 계속 보고한다.

디폴트에서는,timeGetTime 함수의 호출에 의해,GetPrivateTime 는 시스템 타임을 돌려준다. 외부 디바이스로부터 기준 클락을 제공하고 있는 필터는, 다음의 어느쪽이든을 실시할 수가 있다.

  • GetPrivateTime 를 오버라이드(override) 해, 디바이스로부터의 타임을 돌려준다.
  • 디바이스 타임과 시스템 타임의 차이를 감시해,SetTimeDelta 를 호출해 정정한다.

이 클래스는,CAMSchedule 오브젝트를 사용해 아드바이즈 요구의 스케줄링을 실시한다. 상세한 것에 대하여는,CAMSchedule 클래스의 문서를 참조할것.

프로텍트 멤버 변수
m_pSchedule | 클락의 스케줄 태스크를 처리하는 CAMSchedule 오브젝트.
프로텍트 메소드
~CBaseReferenceClock | 소멸자 메소드.
Public 메소드
CBaseReferenceClock | constructor 메소드.
GetPrivateTime | 클락에서 현재의 타임을 취득한다.
SetTimeDelta | 내장 시계 타임을 조정한다.
GetSchedule | 클락의 스케줄 오브젝트에의 포인터를 취득한다.
TriggerThread | 스케줄링을 처리하는 워커 thread를 기동한다.
IReferenceClock 메소드
GetTime | 현재의 기준 타임을 취득한다.
AdviseTime | 단발의 아드바이즈 요구를 생성 한다.
AdvisePeriodic | 주기적 아드바이즈 요구를 생성 한다.
Unadvise | 보류중의 아드바이즈 요구를 삭제한다.
헬퍼 함수
ConvertToMilliseconds | 기준 타임을 밀리 세컨드로 변환한다.

CBaseReferenceClock.m_pSchedule

CBaseReferenceClock 클래스

클락의 스케줄 태스크를 실시하는 CAMSchedule 오브젝트.

구문

CAMSchedule * const m_pSchedule;

CBaseReferenceClock::AdvisePeriodic

CBaseReferenceClock 클래스

주기적 아드바이즈 요구를 생성 한다. IReferenceClock::AdvisePeriodic 메소드를 이행 한다.

구문

HRESULT AdvisePeriodic(
REFERENCE_TIME StartTime,
REFERENCE_TIME PeriodTime,
HSEMAPHORE hSemaphore,
DWORD *pdwAdviseToken
    );

파라미터

StartTime
최초의 통지의 타임 (100 나노초단위). 제로 이상, MAX_TIME 이하가 아니면 안 된다.
PeriodTime
통지의 간격 (100 나노초단위). 제로 이상이 아니면 안 된다.
hSemaphore
semaphore에의 핸들. 호출 바탕으로야는 생성 된다.
pdwAdviseToken
아드바이즈 요구의 식별자를 받는 변수에의 포인터.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.
S_OK | 성공
E_INVALIDARG | 무효인 타임값
E_OUTOFMEMORY | 실패
E_POINTER | NULL 포인터 인수

주의

요구마다, 클락은 hSemaphore 파라미터로 지정된 semaphore를 해방한다. 이후의 통지가 필요하지 않는 경우는,Unadvise 를 호출해, 이 호출로부터 돌려주어진 pdwAdviseToken 값을 건네준다.

CBaseReferenceClock::AdviseTime

CBaseReferenceClock 클래스

단발의 아드바이즈 요구를 생성 한다. IReferenceClock::AdviseTime 메소드를 이행 한다.

구문

HRESULT AdviseTime(
REFERENCE_TIME baseTime,
REFERENCE_TIME streamTime,
HEVENT hEvent,
DWORD *pdwAdviseToken
    );

파라미터

baseTime
기준 타임 (100 나노초단위).
streamTime
스트림 오프셋(offset) 타임 (100 나노초단위).
hEvent
이벤트에의 핸들. 호출 바탕으로야는 생성 된다.
pdwAdviseToken
아드바이즈 요구의 식별자를 받는 변수에의 포인터.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.
S_OK | 성공
E_INVALIDARG | 무효인 타임값
E_OUTOFMEMORY | 실패
E_POINTER | NULL 포인터 변수

주의

이 메소드는, 기준 타임 baseTime + streamTime 의 단발의 아드바이즈 요구를 생성 한다. 이 합계는, 제로 이상, MAX_TIME 이하가 아니면 안 된다. 그 이외의 경우, E_INVALIDARG 를 돌려준다. 요구마다, 클락은 hEvent 파라미터로 지정되는 이벤트에 통지한다.

지정한 타임이 되기 전에 통지를 취소하려면 ,Unadvise 메소드를 호출해, 이 호출로부터 돌려주어진 pdwAdviseToken 의 값을 건네준다. 통지의 발생 후, 클락은 자동적으로 통지를 취소하므로,Unadvise 를 호출할 필요는 없다. 다만, 호출해도 실수는 아니다.

CBaseReferenceClock::CBaseReferenceClock

CBaseReferenceClock 클래스

constructor　 　 메소드.

구문

CBaseReferenceClock(
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr,
CAMSchedule *pSched = NULL
    );

파라미터

pName
오브젝트의 이름을 포함한 캐릭터 라인에의 포인터. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pUnk
위임 오브젝트의 IUnknown 인터페이스에의 포인터.
phr
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되었을 경우는, 집성 오브젝트의 IUnknown 인터페이스에 포인터를 건네준다. 그 이외의 경우는, 이 파라미터에 NULL 를 설정한다.
pSched
CAMSchedule 오브젝트에의 포인터. NULL 의 경우, 이 메소드는 새로운 CAMSchedule 오브젝트를 생성 한다.

CBaseReferenceClock::~CBaseReferenceClock

CBaseReferenceClock 클래스

소멸자 메소드.

구문

CBaseReferenceClock(void);

CBaseReferenceClock::GetPrivateTime

CBaseReferenceClock 클래스

클락에서 리얼타임을 취득한다.

구문

virtual REFERENCE_TIME GetPrivateTime(void);

반환값

현재의 클락 타임을 돌려준다 (100 나노초단위).

주의

이 메소드는, 클락에 의해 보고되는 리얼타임을 돌려준다. 외부의 호출원래는, 이 메소드를 호출하는 GetTime 메소드를 사용한다. GetTime 메소드와는 달라, 내장 시계는 돌아오는 것이 허가된다. 이 경우,GetTime 메소드는,GetPrivateTime 메소드가 따라잡을 때까지, 마지막에 보고된 타임을 계속 돌려준다.

CBaseReferenceClock::GetSchedule

CBaseReferenceClock 클래스

클락의 스케줄 오브젝트에의 포인터를 취득한다.

구문

CAMSchedule GetSchedule(void);

반환값

m_pSchedule 멤버 변수를 돌려준다.

CBaseReferenceClock::GetTime

CBaseReferenceClock 클래스

현재의 기준 타임을 취득한다. IReferenceClock::GetTime 메소드를 이행 한다.

구문

HRESULT GetTime(
REFERENCE_TIME *pTime
    );

파라미터

pTime
현재의 타임을 받는 변수에의 포인터 (100 나노초단위).

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.

E_POINTER | NULL 포인터 변수.
S_FALSE | 돌려주어진 타임은, 이전의 값과 같다.
S_OK | 성공.

주의

이 메소드는 GetPrivateTime 를 호출해, 실제의 클락 타임을 결정한다. 클락 타임이 엄밀하게 이전의 값보다 큰 경우는,GetTime 는 그 클락 타임을 사용해 S_OK 를 돌려준다. 그 이외의 경우는, 이전의 값을 사용해 S_FALSE 를 돌려준다. 그 때문에, 내장 시계는 단시간에 걸쳐서 돌아올 수가 있지만, 기준 타임이 돌아올 것은 없다. 기준 타임은, 내장 시계가 따라잡을 때까지 같은 값으로 "stall" 상태가 된다.

CBaseReferenceClock::SetTimeDelta

CBaseReferenceClock 클래스

내장 시계 타임을 조정한다.

구문

HRESULT SetTimeDelta(
const REFERENCE_TIME& TimeDelta
    );

파라미터

TimeDelta
클락 타임을 조정하는 양 (100 나노초단위). 정의 값에 의해 클락은 진행되어, 부의 값에 의해 클락은 돌아온다.

반환값

S_OK 를 돌려준다.

주의

파생한 클래스는, 타임 정보를 제공하는 디바이스로부터 타임이 어긋났을 경우에, 이 메소드를 사용해 내장 시계를 조정할 수 있다.

GetTime 메소드는, 감소하는 값을 돌려줄 것은 없다. 클락을 되돌리는 조정을 했을 경우,GetTime 는, 클락이 그 값에 도달할 때까지 이전의 값을 돌려준다.

CBaseReferenceClock::TriggerThread

CBaseReferenceClock 클래스

스케줄링을 처리하는 워커 thread를 기동할 수 있다.

구문

void TriggerThread(void);

반환값

반환값 없음.

주의

클락은, 적절한 때에 CAMSchedule::Advise 메소드를 호출하는 워커 thread를 사용한다. 파생한 클래스는,TriggerThread 를 호출해 워커 thread를 기동할 수 있다.

CBaseReferenceClock::Unadvise

CBaseReferenceClock 클래스

보류중의 아드바이즈 요구를 삭제한다. IReferenceClock::Unadvise 메소드를 이행 한다.

구문

HRESULT Unadvise(
DWORD dwAdviseToken
    );

파라미터

dwAdviseToken
삭제하는 요구의 식별자. AdviseTime 메소드 또는 pdwAdviseToken 파라미터의 AdvisePeriodic 메소드에 의해 돌려주어지는 값을 사용한다.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 발견되지 않는다.
S_OK | 성공.

ConvertToMilliseconds Function

CBaseReferenceClock 클래스

기준 타임을 밀리 세컨드로 변환한다.

구문

LONGLONG ConvertToMilliseconds(
    const REFERENCE_TIME& RT
);

파라미터

RT
기준 타임 (100 나노초단위).

반환값

밀리 세컨드 단위에 변환된 기준 타임을 돌려준다.


CBaseRenderer 클래스

CBaseRenderer 클래스의 계층

렌더링 필터를 이행하기 위한 base class. CRendererInputPin 클래스에 의해 이행 되는 입력 핀을 1 개 지원 한다.

선언 : Renbase.h

이 클래스를 사용하려면 ,CBaseRenderer 를 계승하는 상속 클래스를 선언한다. 상속 클래스에서는, 적어도 이하의 메소드를 이행 할 필요가 있다. 이러한 메소드는, base class내에서 순수 가상 함수로서 선언된다.

  • CheckMediaType : 게시된 미디어 타입을 받아들이는지 거부할까를 판단한다. 필터는, 핀 접속의 처리중에 이 메소드를 호출한다.
  • DoRenderSample : 샘플을 렌더링 한다. 필터는, 실행중에 받는 샘플 각각 붙어, 이 메소드를 호출한다.

상태의 변화 및 동기의 문제를 처리하는 base class. 이 base class는, 샘플의 렌더링의 스케줄도 실시한다. 다만, 품질 컨트롤을 위한 수단은 이행 하지 않는다.

이 base class는, 각종의 "핸들러" 메소드도 선언한다. 이것들은, 스트리밍 처리에 있어서의 각각 고유의 단계에서, 필터가 호출하는 메소드이다. base class에서는 아무것도 하지 않지만, 상속 클래스로 오버라이드(override) 할 수 있다. 후의 일람에서는, 이러한 메소드가 「Public 메소드 : 핸들러」로서 정리하고 있다.

OnReceiveFirstSample 핸들러에는 조금 설명이 필요할 것이다. 필터는 이 메소드를 호출하는 것은, 포즈중에 샘플을 받는 경우이다. 이 상황은, 그래프가 정지로부터 포즈에 바뀌는 경우인가, 또는 포즈중에 그래프가 시크 되는 경우에 발생할 가능성이 있다. 비디오 렌더러는, 보통, 이 샘플을 사용해 정지 프레임을 표시한다. 포즈로부터 실행에 바뀌면(자), 필터는,DoRenderSample 메소드에 스트림내의 최초의 샘플과같은샘플을 보낸다.

스케줄링

업 스트림 필터가 입력 핀의 IMemInputPin::Receive 메소드를 호출해 샘플을 건네주면(자), 핀은 그 호출을 필터의 Receive 메소드에 건네준다. 필터는, 샘플을 드롭 하는지, 즉시 렌더링 하는지, 또는 렌더링을 스케줄 한다.

샘플에 타임 스탬프가 없는 경우, 또는 기준 클락을 이용할 수 없는 경우, 필터는 샘플을 즉시 렌더링 한다. 그 이외의 경우, 필터는 ShouldDrawSampleNow 메소드를 호출해, 실행해야 할 처리를 판단한다. 디폴트에서는, 타임 스탬프에 근거해 샘플이 스케줄 된다. 상속 클래스에서는,ShouldDrawSampleNow 을 오버라이드(override) 해, 품질 컨트롤을 지원 할 수 있다.

샘플을 스케줄 하기 위한(해), 필터는, 아드바이즈 요구를 생성 하는 IReferenceClock::AdviseTime 메소드를 호출한다. 이 결과, 스케줄 된 시간이 되는지, 또는 필터 상태가 변화할 때까지,Receive 메소드가 블록 한다. 블록 하면, 업 스트림 필터는, 현재의 샘플이 렌더링 될 때까지, 다음의 샘플을 건네줄 수가 없게 된다.

업 스트림 필터가 IPin::EndOfStream 메소드를 호출해 엔드 오브 스트림을 통지 하면, 필터는, 필터 그래프 매니저에 EC_COMPLETE 이벤트를 송신한다. 필터는, 이 이벤트를 송신하기 전에, 현재의 샘플의 종료 타임까지 대기한다.

프로텍트 멤버 변수
m_bAbort | 렌더링을 정지해, 이후의 샘플을 거부할지 어떨지를 나타내는 플래그.
m_bEOS | 엔드 오브 스트림에 이르고 있는지 어떤지를 나타내는 플래그.
m_bEOSDelivered | 필터가 EC_COMPLETE 이벤트를 발행했는지 어떠했는지를 나타내는 플래그.
m_bInReceive | 필터가 Receive 호출의 처리중인가 어떤가를 나타내는 플래그.
m_bRepaintStatus | 재드로잉(Drawing) 이벤트를 유효 또는 무효로 하는 플래그.
m_bStreaming | 필터가 데이터의 스트리밍중인가 어떤가를 나타내는 플래그.
m_dwAdvise | 렌더링을 스케줄 하는 바다거북 겨이삭띠의 식별자.
m_EndOfStreamTimer | EC_COMPLETE 통지의 스케줄에 사용되는 바다거북 겨이삭띠의 식별자.
m_evComplete | 상태의 이행이 완료했을 때에 통지제가 되는 이벤트.
m_InterfaceLock | 필터 상태의 락.
m_pInputPin | 필터의 입력 핀에의 포인터.
m_pMediaSample | 현재의 미디어 샘플에의 포인터.
m_pPosition | 업 스트림에 시크 커멘드를 건네주기 위한 헬퍼 오브젝트.
m_pQSink | 품질 컨트롤 메세지를 받아들이는 오브젝트에의 포인터.
m_RendererLock | 스트리밍의 락.
m_RenderEvent | 렌더링의 스케줄에 사용되는 이벤트.
m_SignalTime | 현재의 샘플 위에의 종료 타임.
m_ThreadSignal | 스트리밍 thread를 해방하기 위해서 사용되는 이벤트.
Public 메소드
CancelNotification | 렌더링을 스케줄 하는 바다거북 겨이삭띠를 캔슬한다. 가상.
CBaseRenderer | constructor 메소드.
~CBaseRenderer | 소멸자 메소드.
GetMediaPositionInterface | 필터의 IMediaPosition 및 IMediaSeeking 인터페이스 포인터를 취득한다. 가상.
GetPin | 핀을 취득한다. 가상.
GetPinCount | 핀의 수를 취득한다. 가상.
GetSampleTimes | 샘플로부터 타임 스탬프를 취득한다. 가상.
OnDisplayChange | 필터 그래프 매니저에 EC_DISPLAY_CHANGED 이벤트를 발행한다.
PrepareReceive | 샘플을 렌더링 할 준비를 한다. 가상.
Receive | 스트림의 다음의 미디어 샘플을 취득한다. 가상.
Render | 샘플을 렌더링 한다. 가상.
ScheduleSample | 샘플의 렌더링을 스케줄 한다. 가상.
SendNotifyWindow | 업 스트림 필터에 비디오 윈도우의 핸들을 통지한다.
SendRepaint | 필터 그래프 매니저에 재드로잉(Drawing) 이벤트를 송신한다.
SetMediaType | 핀의 미디어 타입을 설정할 경우에 불려 간다. 가상.
SignalTimerFired | 렌더링의 스케줄에 사용되는 타이머 식별자를 클리어 한다.
SourceThreadCanWait | 스트리밍 thread를 보관 유지 또는 해방한다. 가상.
WaitForReceiveToComplete | Receive 메소드가 완료할 때까지 대기한다.
WaitForRenderTime | 현재의 샘플의 프레젠테이션 시간을 대기한다. 가상.
Public 메소드 : 악 세사
ClearPendingSample | 현재의 샘플을 해방한다. 가상.
GetCurrentSample | 현재의 샘플을 취득한다. 가상.
GetRealState | 필터 상태를 취득한다.
GetRenderEvent | 렌더링을 스케줄 하는 이벤트를 취득한다.
HaveCurrentSample | 필터에 샘플이 있을지 어떨지를 판단한다. 가상.
IsEndOfStream | 엔드 오브 스트림 통지가 수신되었는지 어떠했는지를 조회한다.
IsEndOfStreamDelivered | EC_COMPLETE 이벤트가 필터 그래프 매니저에 전달되었는지 어떠했는지를 조회한다.
IsStreaming | 필터가 데이터의 스트리밍중인가 어떤가를 조회한다.
SetAbortSignal | 렌더링을 정지한 이후의 샘플을 거부할지 어떨지를 나타내는, 중지 플래그를 설정한다.
SetRepaintStatus | 재드로잉(Drawing) 이벤트를 유효 또는 무효로 한다.
Public 메소드 : 상태 변경 관련
Active | 상태가 포즈 또는 실행에 바뀔 때 불려 간다. 가상.
BeginFlush | 플래시 처리를 시작 한다. 가상.
BreakConnect | 접속으로부터 입력 핀을 해방한다. 가상.
CheckReady | 상태의 이행이 완료하고 있을지 어떨지를 조회한다.
CompleteConnect | 입력 핀으로부터 다른 핀에의 접속을 완료한다. 가상.
CompleteStateChange | 포즈 상태에의 이행이 완료하고 있을지 어떨지를 판단한다. 가상.
EndFlush | 플래시 처리를 종료한다. 가상.
Inactive | 상태가 정지에 바뀔 때 불려 간다. 가상.
NotReady | 상태의 이행이 아직 완료하고 있지 않는 것을 통지한다.
Ready | 상태의 이행이 완료하고 있는 것을 통지한다.
StartStreaming | 필터가 실행 상태에 바뀔 때, 스트리밍을 시작 한다. 가상.
StopStreaming | 필터가 실행 상태 이외에 바뀔 때, 스트리밍을 정지한다. 가상.
Public 메소드 : 엔드 오브 스트림 관련
EndOfStream | 입력 핀이 엔드 오브 스트림 통지를 수신한 것을 필터에 알린다. 가상.
NotifyEndOfStream | 필터 그래프 매니저에 EC_COMPLETE 이벤트를 송신한다.
ResetEndOfStream | 엔드 오브 스트림 관련 플래그를 리셋 한다.
ResetEndOfStreamTimer | EC_COMPLETE 통지를 스케줄 하는 타이머를 캔슬한다. 가상.
SendEndOfStream | 엔드 오브 스트림에 이르고 있는 경우에, 필터 그래프 매니저에의 EC_COMPLETE 이벤트를 스케줄 한다. 가상.
TimerCallback | 엔드 오브 스트림용의 바다거북 겨이삭띠로 사용하는 콜백 메소드.
Public 메소드 : 핸들러
OnReceiveFirstSample | 포즈중에 필터가 샘플을 수신할 경우에 불려 간다. 가상.
OnRenderEnd | 샘플이 렌더링 된 다음에 불려 간다. 가상.
OnRenderStart | 렌더링이 시작 되려고 하고 있을 때 불려 간다. 가상.
OnStartStreaming | 필터가 스트리밍을 시작 할 경우에 불려 간다. 가상.
OnStopStreaming | 필터가 스트리밍을 정지할 경우에 불려 간다. 가상.
OnWaitEnd | 필터가 샘플의 프레젠테이션 시간의 대기를 종료할 경우에 불려 간다. 가상.
OnWaitStart | 필터가 샘플의 프레젠테이션 시간의 대기를 시작 할 경우에 불려 간다. 가상.
PrepareRender | 필터가 샘플을 렌더링 하기 전에 불려 간다. 가상.
ShouldDrawSampleNow | 샘플의 렌더링을 스케줄 하는 방법을 판단한다. 가상.
Pure Virtual 메소드
CheckMediaType | 특정의 미디어 타입을 필터가 받아들일지 어떨지를 확인한다.
DoRenderSample | 샘플을 렌더링 한다.
IMediaFilter 메소드
GetState | 필터 상태 (실행, 정지, 포즈)를 취득한다.
Pause | 필터를 포즈 한다.
Run | 필터를 실행한다.
Stop | 필터를 정지한다.
IBaseFilter 메소드
FindPin | 지정된 식별자를 가지는 핀을 취득한다.

CBaseRenderer.m_bAbort

CBaseRenderer 클래스

렌더링을 정지해, 이후의 샘플을 거부할지 어떨지를 나타내는 플래그.

구문

BOOL m_bAbort;

CBaseRenderer.m_bEOS

CBaseRenderer 클래스

엔드 오브 스트림에 이르고 있는지 어떤지를 나타내는 플래그.

구문

BOOL m_bEOS;

CBaseRenderer.m_bEOSDelivered

CBaseRenderer 클래스

필터가 EC_COMPLETE 이벤트를 발행했는지 어떠했는지를 나타내는 플래그.

구문

BOOL m_bEOSDelivered;

CBaseRenderer.m_bInReceive

CBaseRenderer 클래스

필터가 Receive 호출의 처리중인가 어떤가를 나타내는 플래그.

구문

BOOL m_bInReceive;

CBaseRenderer.m_bRepaintStatus

CBaseRenderer 클래스

재드로잉(Drawing) 이벤트를 유효 또는 무효로 하는 플래그.

구문

BOOL m_bRepaintStatus;

CBaseRenderer.m_bStreaming

CBaseRenderer 클래스

필터가 데이터의 스트리밍중인가 어떤가를 나타내는 플래그.

구문

BOOL m_bStreaming;

CBaseRenderer.m_dwAdvise

CBaseRenderer 클래스

렌더링을 스케줄 하는 바다거북 겨이삭띠의 식별자.

구문

DWORD_PTR m_dwAdvise;

CBaseRenderer.m_EndOfStreamTimer

CBaseRenderer 클래스

EC_COMPLETE 통지의 스케줄에 사용되는 바다거북 겨이삭띠의 식별자.

구문

UINT m_EndOfStreamTimer;

CBaseRenderer.m_evComplete

CBaseRenderer 클래스

상태의 이행이 완료했을 때에 통지제가 되는 이벤트.

구문

CAMEvent m_evComplete;

CBaseRenderer.m_InterfaceLock

CBaseRenderer 클래스

필터 상태의 락.

구문

CCritSec m_InterfaceLock;

CBaseRenderer.m_pInputPin

CBaseRenderer 클래스

필터의 입력 핀에의 포인터.

구문

CRendererInputPin *m_pInputPin;

CBaseRenderer.m_pMediaSample

CBaseRenderer 클래스

현재의 미디어 샘플에의 포인터.

구문

IMediaSample *m_pMediaSample;

CBaseRenderer.m_pPosition

CBaseRenderer 클래스

업 스트림에 시크 커멘드를 건네주기 위한 헬퍼 오브젝트.

구문

CRendererPosPassThru *m_pPosition;

CBaseRenderer.m_pQSink

CBaseRenderer 클래스

품질 컨트롤 메세지를 받아들이는 오브젝트에의 포인터.

구문

IQualityControl *m_pQSink;

주의

base class에서는 품질 컨트롤을 이행 하지 않는다. 이 멤버 변수의 디폴트값은 NULL 이다.

CBaseRenderer.m_RendererLock

CBaseRenderer 클래스

스트리밍의 락.

구문

CCritSec m_RendererLock;

CBaseRenderer.m_RenderEvent

CBaseRenderer 클래스

렌더링의 스케줄에 사용되는 이벤트.

구문

CAMEvent m_RenderEvent;

CBaseRenderer.m_SignalTime

CBaseRenderer 클래스

현재의 샘플 위에의 종료 타임.

구문

REFERENCE_TIME m_SignalTime;

CBaseRenderer.m_ThreadSignal

CBaseRenderer 클래스

스트리밍 thread를 해방하기 위해서 사용되는 이벤트.

구문

CAMEvent m_ThreadSignal;

CBaseRenderer::Active

CBaseRenderer 클래스

상태가 포즈 또는 실행에 바뀔 때 불려 간다.

구문

virtual HRESULT Active(void);

반환값

S_OK 를 돌려준다.

주의

입력 핀은, 핀 자체의 CRendererInputPin::Active 메소드로부터 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않는다.

CBaseRenderer::BeginFlush

CBaseRenderer 클래스

플래시 처리를 시작 한다.

구문

virtual HRESULT BeginFlush(void);

반환값

S_OK 를 돌려준다.

주의

필터의 입력 핀은,IPin::BeginFlush 메소드의 호출을 받으면(자), 이 메소드를 호출한다. 필터는, 스트리밍 thread를 해방해, 렌더링을 위해서(때문에) 보관 유지하고 있는 샘플을 모두 해방한다.

CBaseRenderer::BreakConnect

CBaseRenderer 클래스

접속으로부터 입력 핀을 해방한다

구문

virtual HRESULT BreakConnect(void);

반환값

다음의 일람에 포함되는 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 핀이 접속되어 있지 않다.
S_OK | 성공.
VFW_E_NOT_STOPPED | 필터가 아직 액티브하다.

주의

필터의 입력 핀은, 핀 자체의 BreakConnect 메소드 내부로부터 이 메소드를 호출한다 (상세한 것에 대하여는「CBasePin::BreakConnect 」를 참조). 필터는, 엔드 오브 스트림 관련 플래그의 리셋등의 내부적인 정평 처리를 몇개인가 실행한다.

CBaseRenderer::CancelNotification

CBaseRenderer 클래스

렌더링을 스케줄 하는 바다거북 겨이삭띠를 캔슬한다.

구문

virtual HRESULT CancelNotification(void);

반환값

다음의 일람에 포함되는 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 보류되고 있는 바다거북 겨이삭띠가 없다.
S_OK | 성공.

주의

필터는 스트리밍을 정지할 경우에 이 메소드를 호출한다. 메소드는, 스케줄 되고 있는 렌더링을 모두 캔슬한다.

CBaseRenderer::CBaseRenderer

CBaseRenderer 클래스

constructor　 　 메소드.

구문

CBaseRenderer(
    REFCLSID RenderClass,
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr
);

파라미터

RenderClass
렌더러의 클래스 식별자.
pName
디버그 목적으로 사용하는, 필터의 이름을 포함한 캐릭터 라인에의 포인터.
pUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되고 있는 경우는, 집성 오브젝트의 IUnknown 인터페이스에 포인터를 건네준다. 그 이외의 경우는, 이 파라미터를 NULL 로 설정한다.
phr
HRESULT 변수에의 포인터. (무시된다)

CBaseRenderer::~CBaseRenderer

CBaseRenderer 클래스

소멸자 메소드.

구문

~CBaseRenderer(void);

CBaseRenderer::CheckMediaType

CBaseRenderer 클래스

특정의 미디어 타입을 필터가 받아들일지 어떨지를 확인한다.

구문

virtual HRESULT CheckMediaType(
    const CMediaType *pmt
) PURE;

파라미터

pmt
제안된 미디어 타입을 포함한 CMediaType 오브젝트에의 포인터.

반환값

제안된 미디어 타입이 받아들여진다면 S_OK 를 돌려준다. 그렇지 않으면 S_FALSE 나 에러 코드를 돌려준다.

주의

입력 핀은, 핀 자체의 CBasePin::CheckMediaType 메소드로부터 이 메소드를 호출한다. 상속 클래스에서는 이 메소드를 이행 할 필요가 있다.

CBaseRenderer::CheckReady

CBaseRenderer 클래스

상태의 이행이 완료하고 있을지 어떨지를 조회한다.

구문

BOOL CheckReady(void);

반환값

상태의 이행이 완료하고 있는 경우는 TRUE 를 돌려주어, 필터가 아직 새로운 상태에 이행중의 경우는 FALSE 를 돌려준다.

참조

NotReady ,Ready

CBaseRenderer::ClearPendingSample

CBaseRenderer 클래스

현재의 샘플을 해방한다.

구문

virtual HRESULT ClearPendingSample(void);

반환값

S_OK 를 돌려준다.

CBaseRenderer::CompleteConnect

CBaseRenderer 클래스

입력 핀으로부터 다른 핀에의 접속을 완료한다.

구문

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

파라미터

pReceivePin
출력 핀의 IPin 인터페이스에의 포인터.

반환값

S_OK 를 돌려준다.

주의

필터의 입력 핀은, 핀 접속을 완료하기 위해서 불려 가는, 핀 자체의 CompleteConnect 메소드 내부로부터 이 메소드를 호출한다 (상세한 것에 대하여는「CBasePin::CompleteConnect 」를 참조). 필터는,SetRepaintStatus 메소드를 호출해 EC_REPAINT 이벤트를 유효하게 한다.

CBaseRenderer::CompleteStateChange

CBaseRenderer 클래스

포즈 상태에의 이행이 완료하고 있을지 어떨지를 판단한다.

구문

virtual HRESULT CompleteStateChange(
    FILTER_STATE OldState
);

파라미터

OldState
이행의 전 상태.

반환값

이행이 완료하고 있는 경우는, S_OK 를 돌려준다. 그 이외의 경우는, S_FALSE 를 돌려준다.

주의

Pause 메소드는, 이 메소드를 호출해, 이행 상태를 갱신한다. 보통, 포즈 상태에의 이행은, 필터가 샘플을 받을 때까지 완료하지 않는다. 다만, 예를 들어 필터가 접속되어 있지 않은 경우나, 엔드 오브 스트림에 이르고 있는 경우등에는, 이행이 즉시 완료한다. 이 메소드는, 각종의 조건을 확인한 데다가,Ready 메소드 또는 NotReady 메소드를 호출해, 이행 상태를 갱신한다.

CBaseRenderer::DoRenderSample

CBaseRenderer 클래스

샘플을 렌더링 한다.

구문

virtual HRESULT DoRenderSample(
    IMediaSample *pMediaSample
) PURE;

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

상속 클래스에서는 이 메소드를 이행 할 필요가 있다. 메소드의 동작은, 이행 되는 필터의 종류에 의해 완전히 다르다. 예를 들어 비디오 렌더러이면, 샘플에 포함되는 비디오 이미지를 드로잉(Drawing) 한다.

CBaseRenderer::EndFlush

CBaseRenderer 클래스

플래시 처리를 종료한다.

구문

virtual HRESULT EndFlush(void);

반환값

S_OK 를 돌려준다.

주의

필터의 입력 핀은,IPin::EndFlush 메소드의 호출을 받으면(자), 이 메소드를 호출한다.

CBaseRenderer::EndOfStream

CBaseRenderer 클래스

입력 핀이 엔드 오브 스트림 통지를 수신한 것을 필터에 알린다.

구문

HRESULT EndOfStream(void);

반환값

S_OK 를 돌려준다.

주의

필터의 입력 핀은, 엔드 오브 스트림 통지를 수신 하면, 이 메소드를 호출한다.

이 메소드는,m_bEOS 플래그를 TRUE 로 설정해,SendEndOfStream 메소드를 호출해 EC_COMPLETE 이벤트를 스케줄 한다. 필터가 포즈중에 샘플을 대기하고 있는 경우, 이 메소드는 상태의 이행을 완료한다.

CBaseRenderer::FindPin

CBaseRenderer 클래스

지정된 식별자를 가지는 핀을 취득한다.

구문

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

파라미터

Id
핀을 식별하는 정수, NULL 로 끝나는 Unicode 캐릭터 라인의 포인터. L"In" 가 아니면 안된다.
ppPin
핀의 IPin 인터페이스에의 포인터를 받는 변수의 주소. 메소드가 실패 하면,*ppPin 는 NULL 에 세트 된다.

반환값

다음의 일람에 포함되는 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_NOT_FOUND | 발견되지 않았다.

주의

이 메소드는,CBaseFilter::FindPin 메소드를 오버라이드(override) 한다. 필터의 유일한 핀 (입력 핀)에는,In 라는 이름이 붙어 있다.

CBaseRenderer::GetCurrentSample

CBaseRenderer 클래스

현재의 샘플을 취득한다.

구문

virtual IMediaSample *GetCurrentSample(void);

반환값

샘플의 IMediaSample 인터페이스에의 포인터를 돌려주어, 샘플이 없는 경우는 NULL 를 돌려준다.

주의

반환값이 NULL 이외의 경우,IMediaSample 포인터는 미처리의 참조 카운트를 가진다. 이 참조 카운트는 반드시 해방하는 것.

CBaseRenderer::GetMediaPositionInterface

CBaseRenderer 클래스

필터의 IMediaPosition 및 IMediaSeeking 인터페이스 포인터를 취득한다.

구문

virtual HRESULT GetMediaPositionInterface(
    REFIID riid,
    void **ppv
);

파라미터

riid
인터페이스의 참조 식별자.
ppv
인터페이스 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음의 일람대로.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_NOINTERFACE | 인터페이스가 지원되어 있지 않다.

주의

필터는, 업 스트림에의 수수를 하는 CRendererPosPassThru 오브젝트에, 모든 시크 커멘드를 위임한다. 이 메소드는,CRendererPosPassThru 오브젝트가 아직 존재하지 않으면 생성 해, 요구된 인터페이스를 그 오브젝트에 조회한다.

m_pPosition 멤버 변수에는,CRendererPosPassThru 오브젝트에의 포인터가 저장 된다.

CBaseRenderer::GetPin

CBaseRenderer 클래스

핀을 취득한다.

구문

virtual CBasePin *GetPin(
    int n
);

파라미터

n
지정된 핀의 수. 0 이 아니면 안된다.

반환값

m_pInputPin 포인터를 돌려준다.

주의

이 메소드는,CBaseFilter 클래스내의 순수 가상 메소드 CBaseFilter::GetPin 를 이행 한다. 이 필터는, 핀을 1 개만 (입력 핀) 지원 한다. 이 메소드는, 처음으로 불려 갔을 때에, 새로운 CRendererInputPin 오브젝트로서 이 핀을 생성 한다.

CBaseRenderer::GetPinCount

CBaseRenderer 클래스

핀의 수를 취득한다.

구문

virtual int GetPinCount(void);

반환값

1 을 돌려준다.

주의

이 메소드는,CBaseFilter 클래스의 순수 가상 메소드 CBaseFilter::GetPinCount 를 이행 한다.

CBaseRenderer::GetRealState

CBaseRenderer 클래스

필터 상태를 취득한다.

구문

FILTER_STATE GetRealState(void);

반환값

CBaseFilter.m_State 의 값을 돌려준다. 이 값은 FILTER_STATE 열거형의 멤버이다.

주의

이 메소드는,GetState 메소드 대신에 내부적으로 사용할 수 있는, 보다 간단한 수단이다.

CBaseRenderer::GetRenderEvent

CBaseRenderer 클래스

렌더링을 스케줄 하는 이벤트를 취득한다.

구문

CAMEvent *GetRenderEvent(void);

반환값

m_RenderEvent 이벤트에의 포인터를 돌려준다.

CBaseRenderer::GetSampleTimes

CBaseRenderer 클래스

샘플로부터 타임 스탬프를 취득한다.

구문

virtual HRESULT GetSampleTimes(
    IMediaSample *pMediaSample,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.
pStartTime
시작 타임을 받는 변수에의 포인터.
pEndTime
종료 타임을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음의 일람대로.

S_OK | 샘플을 즉시 렌더링 해야 한다.
S_FALSE | 타임 스탬프에 근거해, 샘플의 렌더링을 스케줄 해야 한다.
E_FAIL | 이 샘플을 렌더링 해서는 안 된다.
VFW_E_START_TIME_AFTER_END | 부정한 타임 스탬프 : 종료 타임이 시작 타임보다 빠르다.

주의

필터는, 이 메소드를 호출하는 것으로, 샘플을 어떻게 처리해야할 것인가 제발을 판단한다. 반환값이 S_OK 의 경우, 필터는 즉시 샘플을 렌더링 한다. S_FALSE 의 경우는, 타임 스탬프에 근거해 샘플의 렌더링을 스케줄 한다. 에러 코드의 경우는, 샘플을 거부한다.

샘플에 타임 스탬프가 없는 경우, 또는 필터에 기준 클락이 없는 경우, 이 메소드는 S_OK 를 돌려준다. 그 이외의 경우, 이 메소드는 ShouldDrawSampleNow 메소드의 값을 돌려준다. 이 경우,ShouldDrawSampleNow 는 반드시 S_FALSE 를 돌려준다. 이 동작은 상속 클래스로 오버라이드(override) 할 수 있다. 예를 들어, 상속 클래스가 품질 컨트롤의 관리를 이행 하는 경우는, 샘플을 드롭 하기 위해서 E_FAIL 를 돌려줄 수가 있다.

CBaseRenderer::GetState

CBaseRenderer 클래스

필터 상태 (실행, 정지, 포즈)를 취득한다.

구문

HRESULT GetState(
    DWORD dwMilliSecsTimeout,
    FILTER_STATE *State
);

파라미터

dwMilliSecsTimeout
타임 아웃 간격 (밀리 세컨드 단위).
State
필터 상태를 나타내는 FILTER_STATE 열거형의 멤버를 취득하는 변수의 포인터.

반환값

다음의 일람에 포함되는 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
VFW_S_STATE_INTERMEDIATE | 필터 그래프는 지정된 상태에 이행중.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는,CBaseFilter::GetState 메소드를 오버라이드(override) 한다. 렌더러가 포즈 하고 있으면(자), 상태의 이행은, 렌더링 하는 샘플을 받을 때까지 완료하지 않는다. 상태의 이행이 완료하기 전에 타임 아웃 하면, 메소드는 VFW_S_STATE_INTERMEDIATE 를 돌려준다.

CBaseRenderer::HaveCurrentSample

CBaseRenderer 클래스

필터에 샘플이 있을지 어떨지를 판단한다.

구문

virtual BOOL HaveCurrentSample(void);

반환값

필터에 샘플이 있는 경우는 TRUE 를 돌려주어, 그 이외의 경우는 FALSE 를 돌려준다.

CBaseRenderer::Inactive

CBaseRenderer 클래스

상태가 정지에 바뀔 때 불려 간다.

구문

virtual HRESULT Inactive(void);

반환값

S_OK 를 돌려준다.

주의

입력 핀은, 핀 자체의 CRendererInputPin::Inactive 메소드로부터 이 메소드를 호출한다. 필터는,ClearPendingSample 메소드를 호출해 최신의 샘플을 해방한다.

CBaseRenderer::IsEndOfStream

CBaseRenderer 클래스

엔드 오브 스트림 통지가 수신되었는지 어떠했는지를 조회한다.

구문

BOOL IsEndOfStream(void);

반환값

m_bEOS 플래그를 돌려준다.

CBaseRenderer::IsEndOfStreamDelivered

CBaseRenderer 클래스

EC_COMPLETE 이벤트가 필터 그래프 매니저에 전달되었는지 어떠했는지를 조회한다.

구문

BOOL IsEndOfStreamDelivered(void);

반환값

m_bEOSDelivered 플래그를 돌려준다.

CBaseRenderer::IsStreaming

CBaseRenderer 클래스

필터가 데이터의 스트리밍중인가 어떤가를 조회한다.

구문

BOOL IsStreaming(void);

반환값

m_bStreaming 플래그를 돌려준다.

CBaseRenderer::NotReady

CBaseRenderer 클래스

상태의 이행이 아직 완료하고 있지 않는 것을 통지한다.

구문

void NotReady(void);

주의

이 메소드에 의해,GetState 메소드는 VFW_S_STATE_INTERMEDIATE 를 돌려주게 된다. 이 값은, 필터가 현재 상태에 아직 이행중인 것을 나타낸다. 필터는, 상태의 이행이 보류될 때마다, 이 메소드를 호출한다. 이 상황은, 필터가 포즈 하고 나서, 샘플을 받기까지 발생한다.

참조

CheckReady ,Ready

CBaseRenderer::NotifyEndOfStream

CBaseRenderer 클래스

필터 그래프 매니저에 EC_COMPLETE 이벤트를 송신한다.

구문

void NotifyEndOfStream(void);

참조

EndOfStream ,SendEndOfStream

CBaseRenderer::OnDisplayChange

CBaseRenderer 클래스

필터 그래프 매니저에 EC_DISPLAY_CHANGED 이벤트를 송신한다.

구문

BOOL CBaseRenderer::OnDisplayChange(void);

반환값

이벤트가 발행되었을 경우는 TRUE 를 돌려주어, 그 이외의 경우는 FALSE 를 돌려준다.

주의

비디오 렌더러는, WM_DISPLAYCHANGE 메세지에의 응답으로서 이 메소드를 호출하지 않으면 안 된다. 입력 핀이 접속되고 있는 경우, 메소드는 필터 그래프 매니저에 EC_DISPLAY_CHANGED 이벤트를 송신한다.

CBaseRenderer::OnReceiveFirstSample

CBaseRenderer 클래스

포즈중에 필터가 샘플을 수신할 경우에 불려 간다.

구문

virtual void OnReceiveFirstSample(
    IMediaSample *pMediaSample
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.

주의

Receive 메소드는 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스로 오버라이드(override) 할 수 있다. 이 메소드는, 주로 비디오 렌더러에서의 사용을 목적으로 하고 있다. 비디오 렌더러가 포즈중이라면, 보통은, 최초의 샘플을 정지화면으로서 표시한다.

포즈중에 그래프를 시크 했을 경우에도, 이 메소드가 불려 간다.

CBaseRenderer::OnRenderEnd

CBaseRenderer 클래스

샘플이 렌더링 된 다음에 불려 간다.

구문

virtual void OnRenderEnd(
    IMediaSample *pMediaSample
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.

주의

Render 메소드는 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않지만, 예를 들어 품질 컨트롤 데이터를 수집하도록(듯이), 상속 클래스로 오버라이드(override) 할 수 있다.

CBaseRenderer::OnRenderStart

CBaseRenderer 클래스

렌더링이 시작 되려고 하고 있을 때 불려 간다.

구문

virtual void OnRenderStart(
    IMediaSample *pMediaSample
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.

주의

Render 메소드는 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않지만, 예를 들어 품질 컨트롤 데이터를 수집하도록(듯이), 상속 클래스로 오버라이드(override) 할 수 있다.

CBaseRenderer::OnStartStreaming

CBaseRenderer 클래스

필터가 스트리밍을 시작 할 경우에 불려 간다.

구문

virtual HRESULT OnStartStreaming(void);

반환값

S_OK 를 돌려준다.

주의

StartStreaming 메소드는 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스로 오버라이드(override) 할 수 있다.

CBaseRenderer::OnStopStreaming

CBaseRenderer 클래스

필터가 스트리밍을 정지할 경우에 불려 간다.

구문

virtual HRESULT OnStopStreaming(void);

반환값

S_OK 를 돌려준다.

주의

StopStreaming 메소드는 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스로 오버라이드(override) 할 수 있다.

CBaseRenderer::OnWaitEnd

CBaseRenderer 클래스

필터가 샘플의 프레젠테이션 시간의 대기를 종료할 경우에 불려 간다.

구문

virtual void OnWaitEnd(void);

주의

WaitForRenderTime 메소드는, 샘플의 프레젠테이션 시간의 대기를 종료했을 때, 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스로 오버라이드(override) 할 수 있다.

품질 컨트롤을 이행 하는 경우에는, 이 메소드와 함께 OnWaitStart 메소드를 오버라이드(override) 해도 괜찮다. 이러한 메소드를 사용 하면, 필터의 퍼포먼스를 추적할 수 있다.

CBaseRenderer::OnWaitStart

CBaseRenderer 클래스

필터가 샘플의 프레젠테이션 시간의 대기를 시작 할 경우에 불려 간다.

구문

virtual void OnWaitStart(void);

주의

WaitForRenderTime 메소드는, 샘플의 프레젠테이션 시간의 대기를 시작 하면 와, 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스로 오버라이드(override) 할 수 있다.

품질 컨트롤을 이행 하는 경우에는, 이 메소드와 함께 OnEndStart 메소드를 오버라이드(override) 해도 괜찮다. 이러한 메소드를 사용 하면, 필터의 퍼포먼스를 추적할 수 있다.

CBaseRenderer::Pause

CBaseRenderer 클래스

필터를 포즈 한다.

구문

HRESULT Pause(void);

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음의 일람대로.

S_OK | 이행은 완료하고 있다.
S_FALSE | 이행은 완료하고 있지 않다.

주의

이 메소드는,CBaseFilter::Pause 메소드를 오버라이드(override) 한다. 이하의 스텝을 실행한다.

  • CBaseFilter::Pause 메소드를 호출한다.
  • allocater에 위탁한다 ( 「IMemAllocator::Commit 」를 참조).
  • 직전 상태가 정지였던 경우, 필터는 보관 유지하고 있는 샘플을 모두 해방한다 (그 샘플은 이제 유효하지 않다).
  • CompleteStateChange 메소드를 호출해, 그 값을 돌려준다.

CBaseRenderer::PrepareReceive

CBaseRenderer 클래스

샘플을 렌더링 할 준비를 한다.

구문

virtual HRESULT PrepareReceive(
    IMediaSample *pMediaSample
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음의 일람대로.

S_OK | 성공.
E_FAIL | 실패.
E_UNEXPECTED | 예기치 못한 에러.
VFW_E_SAMPLE_REJECTED | 필터는 이 샘플을 드롭 한다.

주의

필터는, 샘플을 렌더링 하기 전에,Receive 메소드내로부터 이 메소드를 호출한다. 필터가 실행중의 경우, 이 메소드는 샘플의 렌더링을 스케줄 한다.

필터에 이미 보류되고 있는 샘플이 있는 경우, 또는 이미 엔드 오브 스트림에 이르고 있는 경우, 메소드는 E_UNEXPECTED 를 돌려준다. 업 스트림 필터에 의한 스트리밍의 호출 순서가 올바르지 않을 가능성이 있다.

스케줄링 알고리즘에 의해, 샘플을 드롭 해야 한다고 판단되는 경우 ( 「ScheduleSample 」참조), 메소드는 VFW_E_SAMPLE_REJECTED 를 돌려준다. 다만, 샘플의 드롭은 에러가 아니기 때문에, 입력 핀의 IMemInputPin::Receive 메소드는, 이 에러 코드를 업 스트림 필터에 건네주지 않는다.

CBaseRenderer::PrepareRender

CBaseRenderer 클래스

필터가 샘플을 렌더링 하기 전에 불려 간다.

구문

virtual void PrepareRender(void);

주의

필터는,OnReceiveFirstSample 메소드 또는 Render 메소드를 호출하기 전에, 이 메소드를 호출한다. PrepareRender 는 base class에서는 아무것도 하지 않는다. 상속 클래스에서는, 이 메소드를 오버라이드(override) 해, 렌더링전에 필요한 임의의 처리를 실행할 수 있다. 예를 들어, 비디오 렌더러이면, 이 메소드를 오버라이드(override) 해 팔레트를 실현해도 괜찮다.

CBaseRenderer::Ready

CBaseRenderer 클래스

상태의 이행이 완료하고 있는 것을 통지한다.

구문

void Ready(void);

주의

이 메소드에 의해,GetState 메소드는 S_OK 를 돌려주게 된다. 이 값은, 필터가 현재 상태에의 이행을 완료하고 있는 것을 나타낸다. 필터는, 상태의 이행을 완료할 때마다, 이 메소드를 호출한다.

참조

CheckReady ,NotReady

CBaseRenderer::Receive

CBaseRenderer 클래스

스트림내의 다음의 미디어 샘플을 취득한다.

구문

virtual HRESULT Receive(
    IMediaSample *pMediaSample
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

성공이라면 S_OK 를 돌려주어, 그 이외의 경우는 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

입력 핀은, 업 스트림 필터로부터 샘플을 받을 때, 이 메소드를 호출한다.

필터가 실행중의 경우, 이 메소드는 이하의 스텝을 실행한다.

  1. 샘플의 렌더링을 스케줄 한다 (PrepareReceive ).
  2. 스케줄 된 시간을 대기한다 (WaitForRenderTime ).
  3. 샘플을 렌더링 한다 (Render ).
  4. 샘플을 해방한다 (ClearPendingSample ).

필터가 포즈중의 경우, 이 메소드는 다음의 스텝을 실행한다.

  1. 샘플이 이용 가능한 일을 상속 클래스에 통지한다 (OnReceiveFirstSample ).
  2. 스케줄 된 시간을 대기한다.
  3. 샘플을 렌더링 한다.
  4. 샘플을 해방한다.

포즈중의 경우, 메소드는 스텝 2. 그리고 필터가 실행 상태에 바뀔 때까지 대기한다. 이 시점에서, 필터가 샘플을 스케줄 한다.

OnReceiveFirstSample 메소드는 base class에서는 아무것도 하지 않는다. 상속 클래스에서는 이 메소드를 오버라이드(override) 할 수 있다. 예를 들어, 비디오 렌더러가 포즈중이라면, 보통은, 최초의 샘플을 정지화면으로서 표시한다.

CBaseRenderer::Render

CBaseRenderer 클래스

샘플을 렌더링 한다.

구문

virtual HRESULT Render(
    IMediaSample *pMediaSample
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음의 일람대로.

S_FALSE | 필터가 정지하고 있는지, 또는 pMediaSample 가 NULL.
S_OK | 성공.

주의

이 메소드는, 실제의 처리를 하는 순수 가상 메소드 DoRenderSample 를 호출한다. 상속 클래스에서는 DoRenderSample 를 이행 할 필요가 있다.

이 메소드는,DoRenderSample 를 호출하기 직전에 OnRenderStart 메소드를 호출한다. 또, 직후에는 OnRenderEnd 메소드를 호출한다. 상속 클래스에서는, 필요에 따라서 이러한 2 개의 메소드를 오버라이드(override) 할 수 있다.

CBaseRenderer::ResetEndOfStream

CBaseRenderer 클래스

엔드 오브 스트림 관련 플래그를 리셋 한다.

구문

virtual HRESULT ResetEndOfStream(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 직전의 엔드 오브 스트림 상태를 클리어 한다. 그 시점에서, 필터가 새로운 데이터를 받아들이게 된다. Stop 및 BeginFlush 메소드는, 이 메소드를 호출한다.

CBaseRenderer::ResetEndOfStreamTimer

CBaseRenderer 클래스

EC_COMPLETE 통지를 스케줄 하는 타이머를 캔슬한다.

구문

void ResetEndOfStreamTimer(void);

참조

SendEndOfStream ,TimerCallback

CBaseRenderer::Run

CBaseRenderer 클래스

필터를 실행한다.

구문

HRESULT Run(void);

반환값

성공이라면 S_OK 를 돌려주어, 그 이외의 경우는 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는,CBaseFilter::Run 메소드를 오버라이드(override) 한다. 이하의 처리를 실행한다.

  • CBaseFilter::Run 메소드를 호출한다.
  • allocater에 위탁한다 ( 「IMemAllocator::Commit 」를 참조).
  • 직전 상태가 정지였던 경우, 필터는 보관 유지하고 있는 샘플을 모두 해방한다 (그 샘플은 이제 유효하지 않다).
  • StartStreaming 메소드를 호출해, 그 결과를 돌려준다. 샘플이 보류되고 있는 경우,StartStreaming 메소드는 샘플의 렌더링을 스케줄 한다.

필터가 접속되어 있지 않은 경우는, 즉시 EC_COMPLETE 이벤트를 송신한다.

CBaseRenderer::ScheduleSample

CBaseRenderer 클래스

샘플의 렌더링을 스케줄 한다.

구문

virtual BOOL ScheduleSample(
    IMediaSample *pMediaSample
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

샘플이 스케줄 되었을 경우는 TRUE 를 돌려주어, 샘플이 드롭 되었을 경우는 FALSE 를 돌려준다.

주의

이 메소드는, 최초로, 샘플을 즉시 렌더링해야할 것인가, 다음에 렌더링해야할 것인가, 또는 드롭해야할 것인가를 판단한다 (이 때문에 GetSampleTimes 메소드를 호출한다). 즉시 렌더링 하는 경우, 메소드는 m_RenderEvent 이벤트를 통지한다. 다음에 렌더링 하는 경우에는, 스케줄 하기 위해서 IReferenceClock::AdviseTime 메소드를 호출한다.

CBaseRenderer::SendEndOfStream

CBaseRenderer 클래스

엔드 오브 스트림에 이르고 있는 경우에, 필터 그래프 매니저에의 EC_COMPLETE 이벤트를 스케줄 한다.

구문

virtual HRESULT SendEndOfStream(void);

반환값

HRESULT 값을 돌려준다. 가능한 값은 다음의 일람대로.

S_FALSE | 필터 그래프 매니저는 이벤트 통지를 받지 않았다.
S_OK | 성공.

주의

현재의 샘플의 종료 타임보다 전에, 필터에 엔드 오브 스트림 통지가 도착하는 일이 있다. 이 경우, 필터는, 필터 그래프 매니저에 EC_COMPLETE 통지를 송신하기 전에, 대기해야 한다.

따라서, 이하와 같이 된다.

  • 필터가 엔드 오브 스트림 (EOS) 통지를 먼저 받았을 경우, 이 메소드는 바다거북 겨이삭띠를 스케줄 한다. 바다거북 겨이삭띠를 액티브하게 하면, 필터가 EC_COMPLETE 이벤트를 송신한다.
  • 필터가 EOS 통지를나중에 받았을 경우, 이 메소드는 즉시 EC_COMPLETE 이벤트를 송신한다.
  • 필터에 보류되고 있는 EOS 통지가 없는 경우, 메소드는 아무것도 하지 않고 돌아온다.

타이머용의 콜백 메소드는,TimerCallback 이다. EC_COMPLETE 이벤트를 전달하기 위해(때문에), 필터는 NotifyEndOfStream 메소드를 호출한다.

CBaseRenderer::SendNotifyWindow

CBaseRenderer 클래스

업 스트림 필터에 비디오 윈도우의 핸들을 통지한다.

구문

void SendNotifyWindow(
    IPin *pPin,
    HWND hwnd
);

파라미터

pPin
업 스트림 필터의 출력 핀의 IPin 인터페이스에의 포인터.
hwnd
비디오 윈도우의 핸들, 또는 NULL.

반환값

반환값 없음.

주의

업 스트림 필터의출력 핀이 IMediaEventSink 인터페이스를 지원 하는 경우, 이 메소드는, 윈도우 핸들과 함께 EC_NOTIFY_WINDOW 이벤트 코드를 업 스트림 필터에 송신한다.

비디오 렌더러는, 렌더러 자체의 CompleteConnect 메소드를, 이 메소드를 호출하도록(듯이) 오버라이드(override) 할 수 있다. 이것은, 업 스트림 필터에 윈도우 핸들을 알리기 위한 메카니즘이다. 이 경우,BreakConnect 메소드도 오버라이드(override) 해, NULL 핸들을 지정해 SendNotifyWindow 를 호출하도록(듯이) 한다.

CBaseRenderer::SendRepaint

CBaseRenderer 클래스

필터 그래프 매니저에 재드로잉(Drawing) 이벤트를 송신한다.

구문

void SendRepaint(void);

주의

이 메소드는, 이하의 조건이 채워지는 경우, 필터 그래프 매니저에 EC_REPAINT 이벤트를 송신한다.

  • 입력 핀이 접속되고 있다.
  • 필터가 플래시중이 아니다.
  • 엔드 오브 스트림에 이르지 않았다.
  • m_bAbort 플래그가 FALSE.
  • m_bRepaintStatus 플래그가 TRUE.

EC_REPAINT 이벤트의 결과, 그래프 상태에 응해, 업 스트림 필터가 샘플을 재발송신 하는지, 필터 그래프가 현재 위치까지 시크 하는지, 또는 필터 그래프 매니저가 일순간 포즈 한다 ( 「EC_REPAINT 」를 참조). 유효하지 않을 가능성이 있기 (위해)때문에, 이 이벤트는 그다지 사용하지 않는 편이 좋다. 다만, 비디오 렌더러에서는 표시를 리프레쉬 해야 하는 것도 있다.

CBaseRenderer::SetAbortSignal

CBaseRenderer 클래스

렌더링을 정지한 이후의 샘플을 거부할지 어떨지를 나타내는, 중지 플래그를 설정한다.

구문

void SetAbortSignal(
    BOOL bAbort
);

파라미터

bAbort
렌더링을 정지할지 어떨지를 나타내는 불형의 값. TRUE 의 경우, 필터는 이후의 샘플을 렌더링 하지 않는다.

주의

이 메소드는 m_bAbort 플래그를 설정한다.

CBaseRenderer::SetMediaType

CBaseRenderer 클래스

핀의 미디어 타입을 설정할 경우에 불려 간다.

구문

virtual HRESULT SetMediaType(
    const CMediaType *pmt
);

파라미터

pmt
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

S_OK 를 돌려준다.

주의

입력 핀은, 핀 자체의 CRendererInputPin::SetMediaType 메소드로부터 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않는다.

CBaseRenderer::SetRepaintStatus

CBaseRenderer 클래스

재드로잉(Drawing) 이벤트를 유효 또는 무효로 한다.

구문

void SetRepaintStatus(
    BOOL bRepaint
);

파라미터

bRepaint
재드로잉(Drawing) 이벤트가 유효하게 되어 있는지 어떤지를 나타내는 불형의 값. TRUE 의 경우, 필터는 EC_REPAINT 이벤트를 필터 그래프 매니저에 송신한다. 그 이외의 경우는, EC_REPAINT 이벤트를 송신하지 않는다.

주의

이 메소드는, 필터 그래프 매니저에 EC_REPAINT 이벤트가 모이는 것을 막는다. 필터는,EC_REPAINT 이벤트를 송신한 다음에, 값 TRUE 를 지정해 이 메소드를 호출한다. 다음의 데이터를 받을 때까지, 필터는 이후의 EC_REPAINT 이벤트를 송신하지 않는다.

CBaseRenderer::ShouldDrawSampleNow

CBaseRenderer 클래스

샘플의 렌더링을 스케줄 하는 방법을 판단한다.

구문

virtual HRESULT ShouldDrawSampleNow(
    IMediaSample *pMediaSample,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.
pStartTime
샘플의 시작 타임이 저장 된 변수에의 포인터.
pEndTime
샘플의 종료 타임이 저장 된 변수에의 포인터.

반환값

S_FALSE 를 돌려준다. 상속 클래스로 이 메소드를 오버라이드(override) 하는 경우에는, 다음의 일람에 포함되는 몇개의 값을 돌려준다.

S_OK | 샘플을 즉시 렌더링 해야 한다.
S_FALSE | 타임 스탬프에 근거해, 샘플의 렌더링을 스케줄 해야 한다.
에러 코드 | 이 샘플을 렌더링 해서는 안 된다.

주의

GetSampleTimes 메소드는 이 메소드를 호출한다. 디폴트에서는, 샘플의 렌더링이, 항상 타임 스탬프에 근거해 스케줄 된다. 이 메소드는, 예를 들어 품질 컨트롤 데이터를 수집하도록(듯이), 상속 클래스로 오버라이드(override) 할 수 있다.

CBaseRenderer::SignalTimerFired

CBaseRenderer 클래스

렌더링의 스케줄에 사용되는 타이머 식별자를 클리어 한다.

구문

virtual void SignalTimerFired(void);

주의

필터는, 렌더링 타이머를 액티브하게 하면나무 ( 「WaitForRenderTime 」를 참조), 또는 캔슬 하면나무 ( 「CancelNotification 」를 참조)에, 이 메소드를 호출한다. 메소드는,m_dwAdvise 멤버 변수를 0 에 리셋 한다.

CBaseRenderer::SourceThreadCanWait

CBaseRenderer 클래스

스트리밍 thread를 보관 유지 또는 해방한다.

구문

virtual HRESULT SourceThreadCanWait(
    BOOL bCanWait
);

파라미터

bCanWait
스트리밍 thread를 보관 유지할지 어떨지를 나타내는 불형의 값. TRUE 의 경우, 이후의 샘플을 렌더링 할 때까지 필터가 대기하는 동안, 스트리밍 thread가 블록 된다. FALSE 의 경우, 스트리밍 thread는 해방된다.

반환값

S_OK 를 돌려준다.

주의

값 FALSE 를 지정한 SourceThreadCanWait 메소드의 호출은, 블록 된 IMemInputPin::Receive 호출로부터 필터를 강제적으로 복귀시킨다. 필터가 실행중의 경우, 현재의 샘플의 프레젠테이션 시간까지,Receive 의 호출을 블록 한다. 필터가 포즈중의 경우는,Receive 의 호출을 무기한으로 블록 한다. 이 동작에 의해, 스트림내의 데이터의 흐름을 조정한다. 다만, 필터가 정지중 또는 플래시중의 경우, 블록은 실시하지 않는다.

블록은,m_RenderEvent 와 m_ThreadSignal 의 2 개의 이벤트를 대기하는 WaitForRenderTime 메소드가 제어한다. m_RenderEvent 이벤트는, 프레젠테이션 시간이 된다고 통지제가 된다. m_ThreadSignal 이벤트는, 값 FALSE 로 SourceThreadCanWait 를 호출하면 통지제가 된다. 이 이벤트는, 값 TRUE 로 SourceThreadCanWait 를 호출하면 리셋 된다.

Stop 및 BeginFlush 메소드는 값 FALSE 로 SourceThreadCanWait 를 호출한다 (스트리밍 thread를 해방한다). Pause ,Run , 및 EndFlush 메소드는, 값 TRUE 로 SourceThreadCanWait 를 호출한다.

CBaseRenderer::StartStreaming

CBaseRenderer 클래스

필터가 실행 상태에 바뀔 때, 스트리밍을 시작 한다.

구문

virtual HRESULT StartStreaming(void);

반환값

S_OK 또는 그 외의 HRESULT 값을 돌려준다.

주의

필터에 샘플이 있는 경우, 필터는 그 샘플의 렌더링을 스케줄 한다. 그 이외의 경우, 보류되고 있는 엔드 오브 스트림 통지가 있으면, 필터는 필터 그래프 매니저에 EC_COMPLETE 이벤트를 송신한다.

이 메소드는 OnStartStreaming 메소드를 호출한다. OnStartStreaming 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스로 오버라이드(override) 할 수 있다.

CBaseRenderer::Stop

CBaseRenderer 클래스

필터를 정지한다.

구문

HRESULT Stop(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 CBaseFilter::Stop 메소드를 오버라이드(override) 한다. 이하의 처리를 실행한다.

  • CBaseFilter::Stop 를 호출한다.
  • allocater에의 위탁을 해제한다 ( 「IMemAllocator::Decommit 」를 참조).
  • 스케줄 되고 있는 렌더링을 모두 캔슬해, 스트리밍 thread를 해방한다.
  • 보류되고 있는 Receive 호출의 완료를 대기한다.

CBaseRenderer::StopStreaming

CBaseRenderer 클래스

필터가 실행 상태 이외에 바뀔 때, 스트리밍을 정지한다.

구문

virtual HRESULT StopStreaming(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 OnStopStreaming 메소드를 호출한다. OnStopStreaming 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스로 오버라이드(override) 할 수 있다.

CBaseRenderer::TimerCallback

CBaseRenderer 클래스

엔드 오브 스트림용의 바다거북 겨이삭띠로 사용하는 콜백 메소드.

구문

void TimerCallback(void);

주의

SendEndOfStream 메소드는, 바다거북 겨이삭띠를 사용해 EC_COMPLETE 통지를 스케줄 한다. TimerCallback 메소드는, 바다거북 겨이삭띠용의 콜백 함수이다. TimerCallback 메소드가 이제(벌써) 1 번 SendEndOfStream 를 호출해,SendEndOfStream 이 EC_COMPLETE 통지를 송신하는지, 또는 다른 타이머를 설정할까를 판단한다.

ResetEndOfStreamTimer 메소드는, 바다거북 겨이삭띠를 캔슬한다.

CBaseRenderer::WaitForReceiveToComplete

CBaseRenderer 클래스

Receive 메소드가 완료할 때까지 대기한다.

구문

void WaitForReceiveToComplete(void);

주의

Stop 및 BeginFlush 메소드는 이 메소드를 호출해, 상태의 변화와 Receive 메소드의 동기를 잡는다.

즉, 이 메소드는,m_bInReceive 플래그가 FALSE 가 될 때까지 대기하는 동안에, 메세지를 디스팟치 한다. 이 플래그는,PrepareReceive 메소드내에서 TRUE 가 되어,Receive 메소드가 PrepareRender 메소드를 호출한 다음에 FALSE 에 돌아온다. 상속 클래스에서는,PrepareRender 를 사용해 팔레트를 설정할 수 있다. PrepareRender 의 완료를 대기 하면, 상태의 변화가 일어나기 전에, 팔레트 변경 메세지가 확실히 디스팟치 된다. 이 결과, 데드 록의 위험성을 회피할 수 있다.

CBaseRenderer::WaitForRenderTime

CBaseRenderer 클래스

현재의 샘플의 프레젠테이션 시간을 대기한다.

구문

virtual HRESULT WaitForRenderTime(void);

반환값

이하의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
VFW_E_STATE_CHANGED | 프레젠테이션 시간이 되기 전에, 필터 상태가 변화했다.

주의

이 메소드는, 이하중 한쪽이 일어날 때까지 대기한다.

  • 샘플의 프레젠테이션 시간이 된다 (즉, 샘플을 렌더링 할 수 있다).
  • 필터가 데이터의 플래시를 정지 또는 시작 한다.

프레젠테이션 시간이 되면(자),m_RenderEvent 이벤트가 통지제가 된다. 상태가 변화 하면,m_ThreadSignal 이벤트가 통지제가 된다. 이 메소드는, 양쪽 모두의 이벤트를 대기한다. 상속 클래스에서는, 필요에 따라서 이 메소드를 오버라이드(override) 해, 다른 이벤트를 대기할 수 있다.

이 메소드는, 대기를 시작 하면나무 OnWaitStart 메소드를 호출해, 대기를 종료 하면 OnWaitEnd 메소드를 호출한다. 어느 쪽의 메소드도, base class에서는 아무것도 하지 않지만, 상속 클래스로 오버라이드(override) 할 수 있다.


CBaseStreamControl 클래스

CBaseStreamControl 클래스의 계층

이 클래스는, 입력 핀과 출력 핀의 양쪽 모두에 대해,IAMStreamControl 인터페이스를 이행 한다. 이 클래스에 의해, 필터 그래프내의 개개의 스트림의 시작 및 종료를 제어할 수 있다. 상세한 것에 대하여는, 「IAMStreamControl 」를 참조할것.

IAMStreamControl 를 지원 하는 핀을 이행 하는 경우는, 이 base class로부터 계승할 필요가 있다. 입력 핀의 표준적인 선언을 다음에 나타낸다.

class CMyInputPin : public CBaseInputPin, public CBaseStreamControl

NonDelegatingQueryInteface 를 오버라이드(override) 해 IAMStreamControl 를 공개할 필요가 있다. 상세한 것에 대하여는, 「IUnknown 의 이행 방법」을 참조할것.

스트림 제어 상태

이 클래스는,StreamControlState 열거를 사용해 스트림의 현재 상태를 기술한다.

  • STREAM_FLOWING:스트림은 핀을 개입시켜 흐르고 있다.
  • STREAM_DISCARDING:핀이 샘플을 파기하고 있다.

이 클래스는, 현재 상태를 취득하는 헬퍼 함수 CheckStreamState 도 제공한다. 이 클래스로부터 파생한 핀으로, 지정된 샘플의 처리 방법을 판단하려면 , 이 함수를 호출할 필요가 있다.

또, 핀이 기준 클락과 동기 하고 있는 일도 중요하다. 기준 클락과 동기 하고 있지 않는 경우, 핀은 모든 샘플을 즉시 파기하므로, 파일 전체가 필터를 개입시켜 가능한 범위에서 고속으로 푸쉬 되어 다음에 스트림을 재개할 수 없게 되는 경우가 있다. 핀이 올바르고 동기 하고 있는 경우, 핀은 스케줄 된 시간까지 샘플을 보관 유지한 후, 샘플을 파기한다. 기준 클락을 지정하려면 ,SetSyncSource 멤버 함수를 호출한다.

CBaseStreamControl 클래스의 사용

이 base class를 올바르게 사용하려면 , 특정의 시점에서 특정의 멤버 함수를 호출하지 않으면 안 된다. 이하에 그방법과 간단한 코드의 예를 나타낸다. 실제의 코드에서는, 이 예로 생략 되고 있는 그 외의 상세한 처리를 실시하지 않으면 안 되는 경우가 있다.

  • 기준 클락: 필터의 IMediaFilter::SetSyncSource 메소드로, 핀의 기준 클락을 설정한다. IReferenceClock 인터페이스 포인터를 사용해,SetSyncSource 멤버 함수를 호출한다.
    STDMETHODIMP CMyFilter::SetSyncSource(IReferenceClock *pClock)
{
m_pMyPin->SetSyncSource(pClock);
return CBaseFilter::SetSyncSource(pClock);
}
  • 이벤트 세면대: 필터의 JoinFilterGraph 메소드로, 필터가 필터 그래프로부터 IMediaEventSink 인터페이스에의 포인터를 취득한 후,SetFilterGraph 멤버 함수를 호출하는 것에 의해, 그 포인터를 핀에 건네준다.
    STDMETHODIMP CMyFilter::JoinFilterGraph(IFilterGraph * pGraph, LPCWSTR pName)
{
HRESULT hr = CBaseFilter::JoinFilterGraph(pGraph, pName);
if (hr == S_OK)
m_pMyPin->SetFilterGraph(m_pSink);
return hr;
}
  • 필터 상태: 필터 상태가 변화했을 경우는, 핀에 대해 NotifyFilterState 멤버 함수를 호출한다. 다음의 예는, 실행 상태에의 이행을 나타내고 있다.
    STDMETHODIMP CMyFilter::Run(REFERENCE_TIME tStart)
{
m_pMyPin->NotifyFilterState(State_Running, tStart);
return CBaseFilter::Run(tStart);
}
  • 플래시: 핀이 데이터의 플래시를 시작 (IPin::BeginFlush ) 또는 데이터의 플래시를 종료 (IPin::EndFlush )했을 때에는, 각각 TRUE 또는 FALSE 의 값을 지정해 Flushing 멤버 함수를 호출한다.
    HRESULT CMyPin::BeginFlush()
{
Flushing(TRUE);
return CBaseOutputPin::BeginFlush();    // 입력 핀의 경우는, CBaseInputPin
}

HRESULT CMyPin::EndFlush()
{
Flushing(FALSE);
return CBaseOutputPin::EndFlush();   // 입력 핀의 경우는, CBaseInputPin
}
  • 미디어 샘플: 핀의 IMemInputPin::Receive 메소드로,CheckStreamState 함수를 호출해, 샘플을 전달하는지, 파기할까를 판단한다. 출력 핀이 샘플을 파기했을 경우는, 출력 핀이 전달하는 다음의 샘플에 대해, 불연속성의 프로퍼티를 설정해야 한다. 다음의 예에서는, 상속 클래스로 m_fLastSampleDiscarded 라고 하는 멤버 변수를 사용해, 불연속성을 추적하고 있다.
    CMyPin::Receive(IMediaSample *pSample)
{
int iStreamState = CheckStreamState(pSample);
if (iStreamState == STREAM_FLOWING) {
if (m_fLastSampleDiscarded)
pSample->SetDiscontinuity(TRUE);
m_fLastSampleDiscarded = FALSE;
// 샘플을 전달하는지, 그 외의 처리를 실시한다.
    }
else {
m_fLastSampleDiscarded = TRUE;     // 다음의 샘플은 불연속
// 이 샘플을 전달하지 않고 , 파기한다.
    }
}

멤버 함수

CBaseStreamControl | CBaseStreamControl 오브젝트를 생성 한다.
CheckStreamState | 스트림의 현재 상태를 취득한다.
Flushing | 필터가 플래시 할 경우에 핀에 통지한다.
GetInfo | 현재의 스트리밍의 설정에 관한 정보를 취득한다.
NotifyFilterState | 핀에 필터 상태를 통지한다.
SetFilterGraph | 필터 그래프가 사용하는 이벤트 세면대 통지를 설정한다.
SetSyncSource | 필터가 포함되는 그래프에 의해 사용되는기준 클락을 식별한다.
StartAt | 언제 스트리밍 데이터의 송신을 시작 할까를 핀에 통지한다.
StopAt | 언제 데이터의 처리를 정지해, 새로운 샘플을 파기할까를 핀에 통지한다.

CBaseStreamControl::CBaseStreamControl

CBaseStreamControl 클래스

CBaseStreamControl 오브젝트를 생성 한다.

구문

CBaseStreamControl(void);

반환값

반환값 없음.

주의

이 함수는, 시작 타임과 종료 타임의 양쪽 모두를 MAX_TIME 에 초기화해, 스트림의 선두로부터 시작 해, 스트림의 끝까지 정지하지 않는 것을 지정한다.

CBaseStreamControl::CheckStreamState

CBaseStreamControl 클래스

스트림의 현재 상태를 취득한다.

구문

enum StreamControlState CheckStreamState(
IMediaSample *pSample
    );

파라미터

pSample
IMediaSample 인터페이스에의 포인터.

반환값

StreamControlState 열거형을 돌려준다.

주의

필터는, 핀이 전송 하려고 하는 샘플을 수신했을 때에 이 멤버 함수를 호출한다. 1 개(살) 이상의 샘플을 파기한 다음에 최초로 전송 하는 샘플은, 불연속성의 마크를 붙일 필요가 있다.

필터가 IAMDroppedFrames 를 이행 해, 드롭 된 프레임의 수를 카운트 하고 있는 경우, 파기된 프레임을 드롭 된 프레임으로서 카운트 해서는 안 된다.

CBaseStreamControl::Flushing

CBaseStreamControl 클래스

필터가 플래시 하고 있는 것을 핀에 통지한다.

구문

void Flushing(
BOOL bInProgress
    );

파라미터

bInProgress
필터가 플래시 하고 있을지 어떨지를 나타내는 값. TRUE 는 플래시가 진행중인 것을 나타낸다. FALSE 는 플래시 하고 있지 않는 것을 나타낸다.

반환값

반환값 없음.

주의

독자적인 필터를 이행 하는 경우는, 핀으로 BeginFlush 및 EndFlush 를 호출했을 때에 이 멤버 함수를 호출해, 플래시 하고 있는 것을 통지해야 한다.

시크를 지원 하지 않는 캡춰 필터는 이 메소드를 호출하지 않는다.

CBaseStreamControl::GetInfo

CBaseStreamControl 클래스

현재의 스트리밍의 설정에 관한 정보를 취득한다.

구문

HRESULT GetInfo(
AM_STREAM_INFO *pInfo
    );

파라미터

pInfo
AM_STREAM_INFO 구조체에의 포인터.

반환값

S_OK 를 돌려준다.

주의

이 멤버 함수는,IAMStreamControl 인터페이스를 이행 해, 핀이 스트리밍중일지 어떨지를 조사하거나 스트림의 속성을 취득하기 위해서 유저에 의해 불려 간다.

CBaseStreamControl::NotifyFilterState

CBaseStreamControl 클래스

핀에 필터 상태를 통지한다.

구문

void NotifyFilterState(
FILTER_STATE new_state,
REFERENCE_TIME tStart = 0
    );

파라미터

new_state
필터의 새로운 상태.
tStart
스트리밍이 시작 되는 시간 (new_state 가 State_Running 의 경우만 유효).

반환값

반환값 없음.

주의

이 멤버 함수는,FILTER_STATE 열거형 변수를 설정하는 것에 의해, 핀에 필터의 새로운 상태를 통지한다.

독자적인 필터를 이행 하고 있는 경우는, 다음의 예에 나타내도록(듯이), 필터 상태가 변화할 때마다, 핀의 CBaseStreamControl::NotifyFilterState 멤버 함수에 필터 상태를 통지한다.

STDMETHODIMP CMyFilter::Run(REFERENCE_TIME tStart)
{
// 에러 체크가 성공했을 경우
m_pMyPin->NotifyFilterState(State_Running, tStart);

// 다음과 같이, 다음에 실시해야 할 임의의 처리를 속행한다.
return CBaseFilter::Run(tStart);
}

STDMETHODIMP CMyFilter::Pause()
{
// 에러 체크가 성공했을 경우
m_pMyPin->NotifyFilterState(State_Paused, 0);

// 다음과 같이, 다음에 실시해야 할 임의의 처리를 속행한다.
return CBaseFilter::Pause();
}

STDMETHODIMP CMyFilter::Stop()
{
// 에러 체크가 성공했을 경우
m_pMyPin->NotifyFilterState(State_Stopped, 0);

// 다음과 같이, 다음에 실시해야 할 임의의 처리를 속행한다.
return CBaseFilter::Stop(tStart);
}

CBaseStreamControl::SetFilterGraph

CBaseStreamControl 클래스

필터 그래프가 이벤트 통지로 사용하는 이벤트 세면대를 설정한다.

구문

void SetFilterGraph(
IMediaEventSink *pSink
    );

파라미터

pSink
IMediaEventSink 인터페이스에의 포인터.

반환값

반환값 없음.

주의

필터는,IMediaEventSink 를 생성 한 후,JoinFilterGraph 멤버 함수로 이 멤버 함수를 호출한다.

CBaseStreamControl::SetSyncSource

CBaseStreamControl 클래스

필터가 포함되는 그래프에 의해 사용되는 기준 클락을 식별한다.

구문

void SetSyncSource(
IReferenceClock *pRefClock
    );

파라미터

pRefClock
IReferenceClock 인터페이스에의 포인터.

반환값

반환값 없음.

주의

이 클래스를 사용하는 핀을 가지는 필터는, 동기 소스 정보를 이 멤버 함수에 건네주도록(듯이) 할 필요가 있다.

CBaseStreamControl::StartAt

CBaseStreamControl 클래스

언제 스트리밍 데이터의 송신을 시작 할까를 핀에 통지한다.

구문

HRESULT StartAt(
const REFERENCE_TIME *ptStart = NULL,
DWORD dwCookie = 0
    );

파라미터

ptStart
스트리밍을 시작 하는 기준 타임에의 포인터. NULL 의 경우는, 즉시 시작 한다 (통지하지 않는다). MAX_TIME 의 경우, 시작은 삭제되는지, 효과가 없다.
dwCookie
시작시에 통지와 함께 송신되는 0 이외의 값. ptStart 가 NULL 이외 또는 MAX_TIME 의 경우에게만 사용된다.

반환값

NOERROR 를 돌려준다.

주의

스트림은 디폴트로 유효해서, 이 멤버 함수는, 이전에 StopAt 를 호출했을 경우 이외는 효과가 없다.

스트림이 STREAM_FLOWING 상태가 되면(자), 필터는 EC_STREAM_CONTROL_STARTED 이벤트 통지를 필터 그래프 매니저에 송신한다.

주 시작과 종료가 같은 시점에 스케줄 되고 있는 경우, 시작은 종료의 극한소시간전에 행해진다고 보여진다. 이 효과를 사용해, 단일의 프레임을 캡춰 할 수 있다.

CBaseStreamControl::StopAt

CBaseStreamControl 클래스

언제 데이터의 처리를 정지해, 새로운 샘플을 파기할까를 핀에 통지한다.

구문

HRESULT StopAt(
const REFERENCE_TIME *ptStop = NULL,
BOOL bSendExtra = FALSE,
DWORD dwCookie = 0
    );

파라미터

ptStop
스트리밍을 종료하는 기준 타임에의 포인터. NULL 의 경우는, 즉시 종료한다 (통지하지 않는다). MAX_TIME 의 경우는, 종료를 취소한다.
bSendExtra
스케줄 된 ptStop 시간보다 후에 핀이 추가의 샘플을 송신할지 어떨지를 지정하는 플래그. TRUE 는 추가의 샘플을 송신하는 것을 나타낸다. 상세한 것에 대하여는, 「주의」를 참조할것.
dwCookie
종료시에 통지와 함께 송신되는 값. ptStart 가 NULL 이외 또는 MAX_TIME 의 경우에게만 사용된다.

반환값

NOERROR 를 돌려준다.

주의

이 멤버 함수는,IAMStreamControl::StopAt 메소드를 이행 해, 스트림의 종료를 지원 할 필요가 있는 핀 및 필터에 의해 사용된다. 이 멤버 함수는,StreamControlState 열거형을 STREAM_DISCARDING 로 설정한다.

비디오 캡춰의 경우는, 캡춰 필터의 출력 핀과 멀티플렉서의입력 핀의 양쪽 모두로 StopAt 지정해, 멀티플렉서에 종료의 통지를 송신시킨다. 이것에 의해, 캡춰 필터는 불필요하게 여분의 프레임을 캡춰 하는 것이 없어져, 멀티플렉서가 마지막 프레임을 디스크에 기입하는 것을 보증할 수 있다.

게다가 캡춰의 출력 핀에서는 bSendExtra 변수에 TRUE 를 지정해, 다른 모든 핀에서는 FALSE 를 지정할 필요가 있다. 추가의 프레임이 송신되지 않으면 멀티플렉서는 종료 타임을 무한하게 대기하게 되어, 이미 모든 캡춰 정보를 수신하고 있는 것이 인식되지 않는다.

ICaptureGraphBuilder 를 사용하고 있는 경우는,ICaptureGraphBuilder::ControlStream 메소드가 자동적으로 이 처리를 실시한다.

주 패킷의 도중에 종료 타임이 지정되고 있는 경우, 필터는 패킷 전체를 전달한 후, 파기 상태가 된다. 또, 시작과 종료가 같은 시점에 스케줄 되고 있는 경우, 시작은 종료의 극한소시간전에 행해진다고 보여진다. 이 효과를 사용해, 단일의 프레임을 캡춰 할 수 있다.


CBaseVideoRenderer 클래스

CBaseVideoRenderer 클래스의 계층

CBaseVideoRenderer base class는, 비디오 렌더러 필터를 구축하기 위해서 사용된다.

Protected 데이터 멤버

m_bDrawLateFrames | 프레임이 드롭 되지 않는 것을 통지하는 플래그. 디버그 전용. 이것은 동기를 파기한다.
m_bSupplierHandlingQuality | TRUE 는 품질 컨트롤 메세지가 처리되는 것을 나타낸다. 이것에 의해, 렌더러는 프레임 자체가 드롭 할 때까지 대기해, 사프라이야가 프레임을 드롭 한 직후에 다음의 프레임을 표시할 수가 있다.
m_cFramesDrawn | 스트리밍이 시작 된 후에 드로잉(Drawing) 된 프레임의 합계수.
m_cFramesDropped | 스트리밍이 시작 된 후, 렌더러로 드롭 된 누적 프레임수. 프레임은, 렌더러가 인식하지 않고 , 업 스트림에서도 드롭 할 수 있다.
m_idDecision | ShouldDrawSampleNow 의 결정 코드의 MSR_id.
m_idDuration | 프레임의 시간폭의 MSR_id.
m_idFrameAccuracy | 프레임이 지연 한 시간의 퍼포먼스 로그 식별자 (밀리 세컨드 단위).
m_idFrameAvg | 동기 및 품질 컨트롤로 사용되는 평균 프레임 시간의 퍼포먼스 로그 식별자.
m_idQualityRate | 요구된 품질 레이트의 MSR_id.
m_idQualityTime | 요구된 품질 타임의 MSR_id.
m_idRenderAvg | 기록된 평균 렌더러 시간의 퍼포먼스 로그 식별자.
m_idSchLateTime | 스케줄시의 프레임의 지연을 나타내는 MSR_id.
m_idSendQuality | 통지의 타이밍의 MSR_id (사용되지 않는다).
m_idTimeStamp | 프레임의타임 스탬프의 MSR_id.
m_idWait | 기록된 대기 시간의 퍼포먼스 로그 식별자 (사용되지 않는다).
m_idWaitReal | 실제의 대기 시간의 퍼포먼스 로그 식별자.
m_iSumFrameTime | 프레임간의 시간의 합계. 프로퍼티 페이지로 필요하게 된다.
m_iSumSqAcc | 프로퍼티 페이지로 필요한 정밀도 (밀리 세컨드 단위)의 2 승의 합계.
m_iSumSqFrameTime | 프레임간의 시간의 2 승의 합계. 프로퍼티 페이지로 필요하게 된다.
m_iTotAcc | 프로퍼티 페이지로 필요한 정밀도 (밀리 세컨드 단위)의 합계.
m_nNormal | 스케줄 된 시간에 드로잉(Drawing) 되는 연속하는 프레임의 수. 부의 수는, 프레임이 렌더러에 의해 드롭 된 것을 나타낸다.
m_trDuration | 마지막 프레임의 시간폭 (시작 타임과 종료 타임의 차이).
m_trEarliness | 프레임이 드롭 되었을 경우에, 어느 정도 빨리 프레임을 재생할 수 있을까.
m_trFrame | 마지막에 기록된 프레임간의 시간. 통계적 측정으로 사용된다.
m_trFrameAvg | 기준 타임의 단위에서의 프레임간의 평균 시간.
m_trLastDraw | 전의 프레임의 시간. 프레임간의 시간의 참조로 사용된다.
m_trLate | 현재의 프레임이 지연 할 시간. 통계적 측정으로 사용된다.
m_trRenderAvg | 프레임이 비트 블록 전송을 실행하기 위해서 걸리는 시간.
m_trRenderLast | 마지막 프레임의 비트 블록 전송의 시간.
m_trRenderLast | 비트 블록 전송을 시작 할 시간. m_trRenderLast 를 취득하기 위해서 사용된다.
m_trThrottle | 각 프레임을 렌더링 한 후에 삽입하는 시간. 보통, 오디오의 품질을 향상시켰을 때에 사용되어 이것을 실시하기 위해서(때문에) 비디오의 퍼포먼스를 저하시킬 필요가 있다.
m_trWaitAvg | 기준 타임의 단위에서의 평균 대기 시간.
m_tStreamingStart | 프로퍼티 페이지의 통계로 사용된다. 현재의 스트리밍 처리의 시작 타임, 또는 현재 스트리밍을 하지 않은 경우는 전의 스트리밍 처리의 시작 타임을 나타낸다.

멤버 함수

CBaseVideoRenderer | CBaseVideoRenderer 오브젝트를 생성 한다.
GetStdDev | 프레임마다의 통계로서 각 프레임의 예정 시간과 실제로 렌더링 된 시간과의 표준 편차를 예측한다.
PreparePerformanceData | 현재의 프레임의 m_trLate 및 m_trFrame 의 값을 설정한다.
ThrottleWait | 각 프레임의 뒤에 대기 시간을 삽입한다.

오버라이드(override) 가능한 멤버 함수

JoinFilterGraph | 필터가 필터 그래프로부터 삭제되었을 때에,EC_WINDOW_DESTROYED 이벤트 통지를 송신한다.
OnDirectRender | 동기 및 품질 컨트롤을 제어하는 타이밍 정보를 수집한다.
OnRenderEnd | 품질 컨트롤 및 동기의 정보를 기록한다.
OnRenderStart | 품질 컨트롤 및 동기의 정보를 기록한다.
OnStartStreaming | 스트리밍을 제어하는 모든 시간을 리셋 한다.
OnStopStreaming | 프로퍼티 페이지의 리포트용으로 시간을 수정하기 위해서, 스트리밍의 마지막에 불려 간다.
OnWaitEnd | 대기 시간의 종료시에 불려 간다. 퍼포먼스 로그 전용.
OnWaitStart | 대기하고 있던 시간으로 대기하고 있지 않았던 시간을 갱신한다. 퍼포먼스 로그 전용.
RecordFrameLateness | 렌더링이 어느 정도 늦지 않고에 행해졌는지를 기록해, 프로퍼티 페이지의 통계 정보를 수집한다.
ResetStreamingTimes | 스트리밍을 제어하는 모든 시간을 리셋 한다.
ScheduleSample | 클락을 사용해아드바이즈 링크 를 설정한다.
SendQuality | 사프라이야가 품질에 관해서 실행하는 처리를 나타내는 품질 메세지를 송신한다.
ShouldDrawSampleNow | 클락을 사용해 타이머의아드바이즈 링크 를 설정하지 않고 , 비디오를 예정대로에 드로잉(Drawing) 할지 어떨지를 판단한다.

이행 되는 IQualProp 메소드

get_AvgFrameRate | 스트리밍이 시작 된 후의 평균 frame rate를, 100 초 쯤의 프레임수단위로 취득한다.
get_AvgSyncOffset | 각 프레임의 예정 시간과 실제로 렌더링 된 시간의 사이의 평균 시간을 밀리 세컨드 단위로 취득한다. 이것은, 스트리밍이 시작 된 후, 모든 프레임에 적용된다.
get_DevSyncOffset | 스트리밍이 시작 된 후의 모든 프레임에 대해, 각 프레임의 예정 시간과 실제로 렌더링 된 시간의 사이의 밀리 세컨드 단위의 시간의 표준 편차를 취득한다.
get_FramesDrawn | 스트리밍의 시작 후에 드로잉(Drawing) 된 프레임수를 취득한다.
get_FramesDroppedInRenderer | 렌더러에 의해 드롭 된 프레임수를 취득한다. 프레임은 업 스트림에서도 드롭 할 수 있다.
get_Jitter | 각 프레임과 다음의 프레임의 사이의 밀리 세컨드 단위의 시간에 대해 표준 편차를 취득한다. 이것은, 스트리밍이 시작 된 후, 모든 프레임에 적용된다.

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingQueryInterface 다른 인터페이스, 특히 프로퍼티 페이지로의 액세스를 제공한다.

이행 되는 IQualityControl 메소드

Notify | 품질의 변경이 요구된 것을 수신자에게 통지한다.
SetSink | 품질 메세지를 받아들이는 IQualityControl 오브젝트를 설정한다.

CBaseVideoRenderer::CBaseVideoRenderer

CBaseVideoRenderer 클래스

CBaseVideoRenderer 오브젝트를 생성 한다.

구문

CBaseVideoRenderer(
REFCLSID RenderClass,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
    );

파라미터

RenderClass
이 렌더러의 클래스 식별자.
pName
디버그를 위해서(때문에) 사용되는 기술에의 포인터.
pUnk
집성 된 소유자 오브젝트에의 포인터.
phr
HRESULT 값에의 포인터.

반환값

반환값 없음.

CBaseVideoRenderer::get_AvgFrameRate

CBaseVideoRenderer 클래스

도달한 평균 frame rate를 계산해 취득한다.

구문

HRESULT get_AvgFrameRate(
int *piAvgFrameRate
    );

파라미터

piAvgFrameRate
스트리밍 시작 후의 1 초 쯤의 프레임수에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IQualProp::get_AvgFrameRate 메소드를 이행 한다.

CBaseVideoRenderer::get_AvgSyncOffset

CBaseVideoRenderer 클래스

스트리밍이 시작 된 후의 모든 프레임에 대해, 각 프레임의 예정 시간과 실제로 렌더링 된 시간의 사이의 밀리 세컨드 단위의 시간의 평균을 취득한다.

구문

HRESULT get_AvgSyncOffset(
int *piAvg
    );

파라미터

piAvg
이전에 기술된 시간의 평균에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IQualProp::get_AvgSyncOffset 메소드를 이행 한다.

CBaseVideoRenderer::get_DevSyncOffset

CBaseVideoRenderer 클래스

스트리밍이 시작 된 후의 모든 프레임에 대해, 각 프레임의 예정 시간과 실제로 렌더링 된 시간의 사이의 밀리 세컨드 단위의 시간의 표준 편차를 취득한다.

구문

HRESULT get_DevSyncOffset(
int *piDev
    );

파라미터

piDev
이전에 기술된 시간의 표준 편차에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IQualProp::get_DevSyncOffset 메소드를 이행 한다.

CBaseVideoRenderer::get_FramesDrawn

CBaseVideoRenderer 클래스

스트리밍의 시작 후에 드로잉(Drawing) 된 프레임수를 나타내는,m_cFramesDrawn 멤버 변수를 취득한다.

구문

HRESULT get_FramesDrawn(
int *pcFramesDrawn
    );

파라미터

pcFramesDrawn
드로잉(Drawing) 된 프레임의 수에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IQualProp::get_FramesDrawn 메소드를 이행 한다.

CBaseVideoRenderer::get_FramesDroppedInRenderer

CBaseVideoRenderer 클래스

렌더러에 의해 드롭 된 프레임수를 취득한다.

구문

HRESULT get_FramesDroppedInRenderer(
int *pcFramesDropped
    );

파라미터

pcFramesDropped
드롭 된 프레임의 수에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IQualProp::get_FramesDroppedInRenderer 메소드를 이행 한다. 이 방법으로, 프로퍼티 페이지는 스케쥴러로부터의 데이터를 취득할 수 있다. 프레임은, 렌더러가 인식하지 않고 , 업 스트림에서도 드롭 할 수 있다.

CBaseVideoRenderer::get_Jitter

CBaseVideoRenderer 클래스

스트리밍 시작 후의 모든 프레임에 대해, 각 프레임과 다음의 프레임의 사이의 밀리 세컨드 단위의 시간에 대해 표준 편차를 취득한다.

구문

HRESULT get_Jitter(
int *piJitter
    );

파라미터

piJitter
프레임간의 시간의 표준 편차에의 포인터 (밀리 세컨드 단위).

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IQualProp::get_Jitter 메소드를 이행 한다.

CBaseVideoRenderer::GetStdDev

CBaseVideoRenderer 클래스

프레임마다의 통계로서 각 프레임의 예정 시간과 실제로 렌더링 된 시간과의 표준 편차를 예측한다.

구문

HRESULT GetStdDev(
int nSamples,
int *piResult,
LONGLONG llSumSq,
LONGLONG iTot
    );

파라미터

nSamples
비디오 렌더러에 의해 수신된 비디오 샘플의 수를 저장 하는 정수값.
piResult
표준 편차를 저장 하는 정수값에의 포인터.
llSumSq
렌더링 된 모든 비디오 샘플의 밀리 세컨드 단위의 표준 편차를 나타내는 값. 이 값이 작을 정도(수록), 렌더링은 일관성이 있다.
iTot
렌더링 된 모든 비디오 샘플에 대해, 스탬프의 시간으로 렌더링 된 시간과의 밀리 세컨드 단위의 평균치를 나타내는 값.

반환값

NOERROR 를 돌려준다.

CBaseVideoRenderer::JoinFilterGraph

CBaseVideoRenderer 클래스

필터가 필터 그래프로부터 삭제되었을 때에,EC_WINDOW_DESTROYED 이벤트 통지를 송신한다.

구문

HRESULT JoinFilterGraph(
IBaseFilterGraph *pGraph,
LPCWSTR pName
    );

파라미터

pGraph
결합하는 필터 그래프에의 포인터.
pName
[in, string] 추가되는 필터의 이름에의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는,CBaseFilter::JoinFilterGraph 멤버 함수를 오버라이드(override) 한다. 이 함수가, 필터가 필터 그래프를 떨어졌던 것이 필터에 통지되고 있다고 판단했을 경우 (pGraph 가 Null 로,m_pGraph 가 Null 는 아니다),EC_WINDOW_DESTROYED 이벤트 통지를 송신해, 리소스 매니저가 렌더러를 포커스 오브젝트로서 보관 유지하지 않게 한다.

CBaseVideoRenderer::NonDelegatingQueryInterface

CBaseVideoRenderer 클래스

인터페이스를 돌려주어, 참조 카운트를 인크리먼트(increment) 한다.

구문

HRESULT NonDelegatingQueryInterface(
REFIID riid,
VOID **ppv
    );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

CBaseVideoRenderer::Notify

CBaseVideoRenderer 클래스

품질의 변경이 요구된 것을 나타내는 통지를 수신한다.

구문

HRESULT Notify(
IBaseFilter *pSelf,
Quality q
    );

파라미터

pSelf
[in] 품질 통지를 송신하고 있는 필터에의 포인터.
q
[in] 품질 통지 구조체.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 비디오 렌더러에 대해 IQualityControl::Notify 메소드를 이행 한다. 이 멤버 함수는, 품질을 삭감해야 하는 경우에, 보통 필터 그래프 매니저에 의해 불려 간다. 이것은, 오디오의 재생 품질을, 비디오의 재생 품질을 저하시키지 않으면 안 되는 정도까지 향상시켰을 경우에 행해진다.

Notify 는,m_trThrottle 데이터 멤버를,ThrottleWait 에 의해 프레임간에 삽입되는 지연값으로 설정한다.

CBaseVideoRenderer::OnDirectRender

CBaseVideoRenderer 클래스

동기 및 품질 컨트롤을 제어하는 타이밍 정보를 수집한다.

구문

virtual void OnDirectRender(
IMediaSample *pMediaSample
    );

파라미터

pMediaSample
미디어 샘플에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

OnRenderStart 및 OnRenderEnd 대신에, 이 멤버 함수를 호출한다. 이것은, Microsoft® DirectDraw® 비디오 렌더러에 의해 사용된다.

CBaseVideoRenderer::OnRenderEnd

CBaseVideoRenderer 클래스

세치기에 의해 렌더링 시간이 다른 경우에, 스무딩을 실행한다.

구문

void OnRenderEnd(
IMediaSample *pMediaSample
    );

파라미터

pMediaSample
미디어 샘플에의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는, 이미지를 드로잉(Drawing) 한 직후에 호출할 필요가 있다.

이 멤버 함수는,CBaseRenderer::OnRenderEnd 를 오버라이드(override) 한다.

CBaseVideoRenderer::OnRenderStart

CBaseVideoRenderer 클래스

렌더링의 정보를 설정한다.

구문

void OnRenderStart(
IMediaSample *pMediaSample
    );

파라미터

pMediaSample
미디어 샘플에의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는, 시스템으로부터 현재의 클락 타임을 취득해, 드로잉(Drawing)이 완료 혀 했을 때에 사용되는 멤버 변수에 저장 한다. 이 함수는, 퍼포먼스 로그의 기록도 실행한다. 이 멤버 함수는, 드로잉(Drawing)가 시작 되기 직전에 호출할 필요가 있다.

이 멤버 함수는,CBaseRenderer::OnRenderStart 를 오버라이드(override) 한다.

CBaseVideoRenderer::OnStartStreaming

CBaseVideoRenderer 클래스

스트리밍을 제어하는 모든 시간을 리셋 한다.

구문

HRESULT OnStartStreaming(void);

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,CBaseRenderer::OnStartStreaming 를 오버라이드(override) 한다.

CBaseVideoRenderer::OnStopStreaming

CBaseVideoRenderer 클래스

프로퍼티 페이지의 리포트용으로 시간을 수정하기 위해서, 스트리밍의 마지막에 불려 간다.

구문

HRESULT OnStopStreaming(void);

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는 2 회 불려 간다. 1 회는 포즈 했을 때로, 이제(벌써) 1 회는 실제로 정지했을 때이다.

이 멤버 함수는,CBaseRenderer::OnStopStreaming 를 오버라이드(override) 한다.

CBaseVideoRenderer::OnWaitEnd

CBaseVideoRenderer 클래스

대기 시간의 종료시에 불려 간다.

구문

void OnWaitEnd(void);

반환값

반환값 없음.

주의

이 멤버 함수는, 퍼포먼스 로그의 기록만 실행한다. 이 멤버 함수는, thread가 윈도우내에서 기동했을 때, 또는 다음의 샘플의 렌더링이 예정되어 있는 시간에 불려 간다. 결과적으로, 이 멤버 함수를 사용해, 동기를 제어하는 정보를 수집할 수 있다.

CBaseVideoRenderer::OnWaitStart

CBaseVideoRenderer 클래스

대기하고 있던 시간으로 대기하고 있지 않았던 시간을 갱신한다.

구문

void OnWaitStart(void);

반환값

반환값 없음.

주의

이 멤버 함수는, 렌더링 이벤트의 대기를 시작 했을 때에 불려 간다. 이 멤버 함수는, 퍼포먼스 측정을 위해서(때문에) 마셔 사용된다.

CBaseVideoRenderer::PreparePerformanceData

CBaseVideoRenderer 클래스

현재의 프레임의 m_trLate 및 m_trFrame 의 값을 설정한다.

구문

void PreparePerformanceData(
int trLate,
int trFrame
    );

파라미터

trLate
기준 타임의 단위로, 샘플이 예정 시간부터 어느 정도 지연 하는지를 나타내는 값.
trFrame
기준 타임의 단위에서의 프레임간의 시간.

반환값

반환값 없음.

주의

이 멤버 함수는,m_trLate 를 trLate 의 값에,m_trFrame 를 trFrame 의 값으로 설정한다.

CBaseVideoRenderer::RecordFrameLateness 멤버 함수가,CBaseVideoRenderer::OnRenderStart 또는 CBaseVideoRenderer::OnDirectRender 의 어느쪽이든으로부터 불려 가면(자), 통계 정보를 갱신하기 위해서 m_trLate 및 m_trFrame 의 값을 건네준다. PreparePerformanceData 는, 이러한 데이터 멤버값을 설정하기 위해서 CBaseVideoRenderer::OnWaitEnd 로부터 불려 간다.

CBaseVideoRenderer::RecordFrameLateness

CBaseVideoRenderer 클래스

렌더링이 어느 정도 늦지 않고에 행해졌는지를 기록해, 프로퍼티 페이지의 통계 정보를 수집한다.

구문

virtual void RecordFrameLateness(
int trLate,
int trFrame
    );

파라미터

trLate
기준 타임의 단위로, 샘플이 예정 시간부터 어느 정도 지연 하는지를 나타내는 값.
trFrame
기준 타임의 단위에서의 프레임간의 시간.

반환값

반환값 없음.

CBaseVideoRenderer::ResetStreamingTimes

CBaseVideoRenderer 클래스

스트리밍을 제어하는 모든 시간을 리셋 한다.

구문

virtual HRESULT ResetStreamingTimes(void);

반환값

HRESULT 값을 돌려준다.

주의

이 시간은, 프레임이 처음은 드롭 되지 않고, 최초의 프레임이 드로잉(Drawing) 되도록(듯이) 하기 위해서 설정된다.

CBaseVideoRenderer::ScheduleSample

CBaseVideoRenderer 클래스

드로잉(Drawing) 및 드롭 된 샘플수를 보관 유지하는 주된 처리를 실행하는 base class를 오버라이드(override) 한다. IQualProp 의 이행에 의해 사용된다.

구문

BOOL ScheduleSample(
IMediaSample *pMediaSample
    );

파라미터

pMediaSample
미디어 샘플에의 포인터.

반환값

샘플이 스케줄 되고 있는 경우는 TRUE 를 돌려준다. 그 이외의 경우는 FALSE 를 돌려준다.

CBaseVideoRenderer::SendQuality

CBaseVideoRenderer 클래스

사프라이야가 품질에 관해서 실행하는 처리를 나타내는 품질 메세지를 송신한다.

구문

virtual HRESULT SendQuality(
REFERENCE_TIME trLate,
REFERENCE_TIME trRealStream
    );

파라미터

trLate
프레임이 지연 할 시간.
trRealStream
현재의스트림 타임 .

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 품질관리를 제어하기 위해서, 품질 컨트롤 메세지를 업 스트림에 송신한다. 품질 메세지의 성질 (즉, 샘플수를 증가시키는지, 감소시킬까)은, 이 상속 클래스에서의 품질관리의 이행으로 정해진다. 「CBaseVideoRenderer::ShouldDrawSampleNow 」를 참조할것.

CBaseVideoRenderer::SetSink

CBaseVideoRenderer 클래스

품질 메세지를 받아들이는 IQualityControl 오브젝트를 설정한다.

구문

HRESULT SetSink(
IQualityControl *piqc
    );

파라미터

piqc
통지의 송신지의 IQualityControl 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 비디오 렌더러에 대해 IQualityControl::SetSink 메소드를 이행 한다.

CBaseVideoRenderer::ShouldDrawSampleNow

CBaseVideoRenderer 클래스

클락을 사용해 타이머의 아드바이즈린크를 설정하지 않고 , 비디오를 드로잉(Drawing) 할지 어떨지를 판단한다.

구문

virtual HRESULT ShouldDrawSampleNow(
IMediaSample *pMediaSample,
REFERENCE_TIME *ptrStart,
REFERENCE_TIME *ptrEnd
    );

파라미터

pMediaSample
이 샘플의 IMediaSample 인터페이스에의 포인터.
ptrStart
렌더링을 시작 할 시간에의 포인터.
ptrEnd
렌더링을 종료하는 시간에의 포인터.

반환값

HRESULT 값을 돌려준다. 대기하지 않고 , 즉시 드로잉(Drawing) 하는 경우는 S_OK 를 돌려준다. 시간 ptrStart 에 드로잉(Drawing) 하는 경우는 S_FALSE 를 돌려준다. 샘플을 드로잉(Drawing) 하지 않는 경우는 에러를 돌려주어, 그 샘플을 스킵 해 시간을 절약한다.

주의

이 멤버 함수는,CBaseRenderer::ShouldDrawSampleNow 를 오버라이드(override) 한다.

CBaseVideoRenderer::ThrottleWait

CBaseVideoRenderer 클래스

각 프레임의 뒤에 대기 시간을 삽입한다.

구문

void ThrottleWait(void);

반환값

반환값 없음.

주의

이 멤버 함수는,m_trThrottle 데이터 멤버로부터 취득된 시간 대기한다.


CBaseVideoWindow 클래스

CBaseVideoWindow 클래스의 계층

CBaseVideoWindow 클래스는,IVideoWindow 인터페이스의 IDispatch 컴퍼넌트를 처리해,IVideoWindow 의 프로퍼티 및 메소드는 순수 가상대로 해 둔다.

멤버 함수

CBaseVideoWindow CBaseVideoWindow 오브젝트를 생성 한다.

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingQueryInterface 지정된 참조 카운트의 인터페이스를 돌려준다.

이행 되는 IDispatch 메소드

GetIDsOfNames | 단일의 멤버 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자에 맵 한다. 이 식별자는, 이후의 IDispatch::Invoke 메소드의 호출로 사용할 수 있다.
GetTypeInfo | 타입 정보 오브젝트를 취득한다. 인터페이스의 타입 정보를 취득할 수 있다.
GetTypeInfoCount | 오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.
Invoke | 오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

CBaseVideoWindow::CBaseVideoWindow

CBaseVideoWindow 클래스

CBaseVideoWindow 오브젝트를 생성 한다.

구문

CBaseVideoWindow(
  const TCHAR *pName,
  LPUNKNOWN pUnk
  );

파라미터

pName
디버그를 위해서(때문에) CBaseVideoWindow constructor　 　 으로 사용되는 오브젝트의 이름에의 포인터.
pUnk
이 오브젝트의 소유자에게로의 포인터.

반환값

반환값 없음.

주의

스태틱 메모리에 pName 파라미터를 할당한다. 이 이름은, 오브젝트의 생성 및 삭제를 실시하는 데밧깅 단말상에 나타난다.

CBaseVideoWindow::GetIDsOfNames

CBaseVideoWindow 클래스

단일의 멤버 함수 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자에 맵 한다. 이 식별자는, 이후의 CBaseVideoWindow::Invoke 멤버 함수의 호출로 사용할 수 있다.

구문

HRESULT GetIDsOfNames(

  REFIID riid,

  OLECHAR **rgszNames,

  UINT cNames,

  LCID lcid,

  DISPID *rgdispid

  );

파라미터

riid
참조 식별자. 장래적인 사용을 위해서(때문에) 예약되고 있다. NULL 가 아니면 안된다.
rgszNames
건네받은 맵 하는 이름의 배열에의 포인터의 주소.
cNames
맵 되는 이름의 수.
lcid
이름을 해석하는 로케일 문맥.
rgdispid
호출원 할당하고가 끝난 배열에의 포인터. 각 요소에는,rgszNames 배열에게 건네지는 이름의 1 개에 대응하는 ID 가 포함된다. 최초의 요소는 멤버의 이름을 나타내, 이후의 요소는 각 멤버의 파라미터를 나타낸다.

반환값

다음의 몇개의 값을 돌려준다.
DISP_E_UNKNOWN_CLSID | CLSID 가 인식되지 않았다.
DISP_E_UNKNOWNNAME | 1 개(살) 이상의 이름이 불명했다. 돌려주어진 DISPID 에는, 불명한 이름에 대응하는 각 엔트리의 DISPID_UNKNOWN 가 포함된다.
E_OUTOFMEMORY | 메모리 부족.
S_OK | 성공.

CBaseVideoWindow::GetTypeInfo

CBaseVideoWindow 클래스

타입 정보 오브젝트를 취득한다. 인터페이스의 타입 정보를 취득할 수 있다.

구문

HRESULT GetTypeInfo(

  UINT itinfo,

  LCID lcid,

  ITypeInfo **pptinfo

  );

파라미터

itinfo
돌려주어지는 타입 정보. 제로를 건네주어,IDispatch 이행의 타입 정보를 취득한다.
lcid
타입 정보의 로케일 ID. 로컬라이즈 된 멤버명을 지원 하는 클래스의 경우, 오브젝트는 다른 언어가 다른 타입 정보를 돌려줄 수가 있는 경우가 있다. 로컬라이즈 된 멤버명을 지원 하지 않는 클래스의 경우, 이 파라미터는 무시할 수가 있다.
pptinfo
요구된 타입 정보 오브젝트에의 포인터의 주소.

반환값

pptinfo 가 무효인 경우는, E_POINTER 를 돌려준다. itinfo 가 제로 이외의 경우는, TYPE_E_ELEMENTNOTFOUND 를 돌려준다. 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 타입을 취득하기 위한 호출의 1 개로부터 HRESULT 를 돌려준다. HRESULT 는 에러를 나타내, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.

CBaseVideoWindow::GetTypeInfoCount

CBaseVideoWindow 클래스

오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.

구문

HRESULT GetTypeInfoCount(

  UINT *pctinfo

  );

파라미터

pctinfo
오브젝트가 제공하는 타입 정보 인터페이스의 수를 받는 장소에의 포인터. 오브젝트가 타입 정보를 제공했을 경우, 이 수는 1 이다. 그 이외의 경우는, 0 이다.

반환값

pctinfo 가 무효인 경우는, E_POINTER 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

CBaseVideoWindow::Invoke

CBaseVideoWindow 클래스

오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

구문

HRESULT Invoke(

  DISPID dispidMember,

  REFIID riid,

  LCID lcid,

  WORD wFlags,

  DISPPARAMS *pdispparams,

  VARIANT *pvarResult,

  EXCEPINFO *pexcepinfo,

  UINT *puArgErr

  );

파라미터

dispidMember
멤버의 식별자. 디스팟치 식별자를 취득하려면 ,CBaseVideoWindow::GetIDsOfNames 또는 오브젝트의 문서를 사용한다.
riid
장래적인 사용을 위해서(때문에) 예약되고 있다. IID_NULL 가 아니면 안된다.
lcid
인수를 해석하는 로케일 문맥.
wFlags
CBaseVideoWindow::Invoke 호출의 문맥을 기술하는 플래그.
pdispparams
인수의 배열, 이름 첨부 인수의 인수 디스팟치 ID 의 배열, 및 배열내의 요소의 수를 포함한 DISPPARAMS 구조체에의 포인터.
pvarResult
결과가 저장 되는 포인터, 또는 호출해 원이 결과를 요구하지 않은 경우는 NULL.
pexcepinfo
예외 정보를 포함한 구조체에의 포인터.
puArgErr
rgvarg 배열내에서, 에러가 있는 최초의 인수의 인덱스에의 포인터. rgvarg 배열은 DISPPARAMS 구조체의 멤버이다.

반환값

riid 가 IID_NULL 이외의 경우는, DISP_E_UNKNOWNINTERFACE 를 돌려준다. 호출이 실패했을 경우는,CBaseVideoWindow::GetTypeInfo 로부터 에러 코드의 1 개를 돌려준다. 그 이외의 경우는,IDispatch::Invoke 에의 호출로부터 HRESULT 를 돌려준다.

CBaseVideoWindow::NonDelegatingQueryInterface

CBaseVideoWindow 클래스

지정된 참조 카운트의 인터페이스를 돌려준다.

구문

HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void **ppv
  );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

디폴트에서는,IVideoWindow 및 IUnknown 인터페이스에의 포인터를 돌려준다. 이 메소드를 오버라이드(override) 해, 상속 클래스로 이행 된 추가의 인터페이스를 공개한다.

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 한다.


CBaseWindow 클래스

CBaseWindow 클래스의 계층

윈도우를 관리하는 base class. 비디오 렌더러는 이 클래스를 사용해 비디오 윈도우를 생성 한다.

선언 : Winutil.h

이 클래스를 사용하려면 ,CBaseWindow 로부터 계승한 상속 클래스를 생성 하는 것. 상속 클래스에서는 :

  • 윈도우 스타일을 정의하는 순수 가상 메소드 GetClassWindowStyles 를 이행 한다.
  • 윈도우 메세지를 핸들 하는 OnReceiveMessage 메소드를 오버라이드(override) 한다.
  • DoneWithWindow 메소드를 호출하는 소멸자를 이행 한다.

상속 클래스의 인스턴스를 사용하기 전에,PrepareWindow 메소드를 호출하는 것.

Protected 멤버 변수
m_hInstance | 모듈 인스턴스의 핸들.
m_hwnd | 오브젝트의 윈도우의 핸들.
m_hdc | 윈도우의 디바이스 콘텍스트의 핸들.
m_Width | 클라이언트 에리어의 폭, 픽셀.
m_Height | 클라이언트 에리어의 높이, 픽셀.
m_bActivated | 윈도우가 액티브하게 되어 있는지 어떤지를 나타내는 플래그.
m_pClassName | 윈도우 클래스의 이름을 포함한 정적 캐릭터 라인.
m_ClassStyles | 윈도우의 클래스 스타일.
m_WindowStyles | 윈도우의 윈도우 스타일.
m_WindowStylesEx | 윈도우의 확장 윈도우 스타일.
m_ShowStageMessage | 윈도우를 foreground로 하는 프라이빗 메세지.
m_ShowStageTop | 윈도우 스타일을 WS_EX_TOPMOST 로 설정하는 프라이빗 메세지.
m_RealizePalette | 팔레트를 적용시키는 프라이빗 메세지.
m_MemoryDC | 메모리 디바이스 콘텍스트의 핸들.
m_hPalette | 윈도우의 팔레트의 핸들.
m_bNoRealize | 윈도우가 그 팔레트를 적용했는지 어떠했는지를 나타내는 플래그.
m_bBackground | 팔레트가 백그라운드 팔레트여야할 것인가 어떤가를 나타내는 플래그.
m_bRealizing | 새로운 팔레트가 적용되었는지 어떠했는지를 나타내는 플래그.
m_WindowLock | 크리티컬 섹션, 오브젝트의 액세스를 계속시킨다.
m_bDoGetDC | 디바이스 콘텍스트를 취득했는지 어떠했는지를 나타내는 플래그.
m_bDoPostToDestroy | 윈도우가 그 데스트라크션멧세이지에 PostMessage 를 사용할까 SendMessage 를 사용하는지를 지정하는 플래그.
Protected 메소드
OnPaletteChange | 팔레트 변경 메세지를 취급한다. 가상.
Public 메소드
CBaseWindow | constructor 메소드.
DoneWithWindow | 윈도우를 삭제한다. 가상.
PrepareWindow | 윈도우를 생성 한다. 가상.
InactivateWindow | 윈도우를 비액티브하게 한다. 가상.
ActivateWindow | 상속 클래스의 요구에 따라 윈도우를 액티브하게 한다. 가상.
OnSize | WM_SIZE 메세지를 취급한다. 가상.
OnClose | WM_CLOSE 메세지를 취급한다. 가상.
GetDefaultRect | 클라이언트 에리어의 디폴트 사이즈를 취득한다. 가상.
UninitialiseWindow | 윈도우의 리소스를 해방한다. 가상.
InitialiseWindow | 윈도우를 초기화한다. 가상.
CompleteConnect | 윈도우에 렌더러의 입력 핀이 접속된 것을 통지한다.
DoCreateWindow | 윈도우를 생성 한다.
PerformanceAlignWindow | 퍼포먼스를 최고로 하기 위해서 윈도우를 DWORD 경계에 갖춘다.
DoShowWindow | 윈도우의 표시 상태를 설정한다.
PaintWindow | 윈도우를 재드로잉(Drawing) 시킨다.
DoSetWindowForeground | 윈도우를 foreground에 가져온다.
SetPalette | 윈도우에 팔레트를 인스톨 한다. 가상.
SetRealize | 윈도우가 팔레트를 적용할지 어떨지를 지정한다.
DoRealisePalette | 윈도우의 현재의 팔레트를 적용한다. 가상.
PossiblyEatMessage | 상속 클래스에 다른 윈도우에의 메세지의 전송을 허가한다. 가상.
GetWindowWidth | 윈도우의 현재의 폭을 취득한다.
GetWindowHeight | 윈도우의 현재의 높이를 취득한다.
GetWindowHWND | 윈도우의 핸들을 취득한다.
GetMemoryHDC | 메모리 디바이스 콘텍스트의 핸들을 취득한다.
GetWindowHDC | 윈도우의 디바이스 콘텍스트의 핸들을 취득한다.
OnReceiveMessage | 윈도우 메세지를 취급한다. 가상.
Pure Virtual 메소드
GetClassWindowStyles | 윈도우의 클래스 스타일을 취득한다.

CBaseWindow.m_hInstance

CBaseWindow 클래스

모듈 인스턴스의 핸들.

구문

HINSTANCE m_hInstance;

주의

DLL 엔트리 포인트 함수는 글로벌 변수를 모듈 인스턴스의 핸들로 설정한다. CBaseWindow 클래스는 이 핸들을 그 constructor　 　 메소드에 스토어 한다.

CBaseWindow.m_hwnd

CBaseWindow 클래스

오브젝트의 윈도우의 핸들.

구문

HWND m_hwnd;

CBaseWindow.m_hdc

CBaseWindow 클래스

윈도우의 디바이스 콘텍스트의 핸들.

구문

HDC m_hdc;

CBaseWindow.m_Width

CBaseWindow 클래스

클라이언트 에리어의 폭, 픽셀.

구문

LONG m_Width;

CBaseWindow.m_Height

CBaseWindow 클래스

클라이언트 에리어의 높이, 픽셀.

구문

LONG m_Height;

CBaseWindow.m_bActivated

CBaseWindow 클래스

윈도우가 액티브하게 되어 제발을 나타내는 플래그. TRUE 라면, 윈도우는 액티브하게 되어 있다.

구문

BOOL m_bActivated;

CBaseWindow.m_pClassName

CBaseWindow 클래스

윈도우 클래스의 이름을 포함한 정적 (static) 캐릭터 라인.

구문

LPTSTR m_pClassName;

CBaseWindow.m_ClassStyles

CBaseWindow 클래스

윈도우의 클래스 스타일.

구문

DWORD m_ClassStyles;

CBaseWindow.m_WindowStyles

CBaseWindow 클래스

윈도우의 윈도우 스타일.

구문

DWORD m_WindowStyles;

CBaseWindow.m_WindowStylesEx

CBaseWindow 클래스

윈도우의 확장 윈도우 스타일.

구문

DWORD m_WindowStylesEx;

CBaseWindow.m_ShowStageMessage

CBaseWindow 클래스

윈도우를 foreground로 하는 프라이빗 메세지.

구문

UINT m_ShowStageMessage;

주의

DoSetWindowForeground 메소드는 이 메세지를 송신한다.

CBaseWindow.m_ShowStageTop

CBaseWindow 클래스

윈도우 스타일을 WS_EX_TOPMOST 로 설정하는 프라이빗 메세지.

구문

UINT m_ShowStageTop;

주의

비디오 렌더러가 풀 스크린 모드로 변경하고 싶은들 , 비디오 렌더러는 이 메세지를 윈도우에 보내야 하는 것이다.

CBaseWindow.m_RealizePalette

CBaseWindow 클래스

팔레트를 적용시키는 프라이빗 메세지.

구문

UINT m_RealizePalette;

주의

SetPalette 메소드는 이 메세지를 보낸다.

CBaseWindow.m_MemoryDC

CBaseWindow 클래스

메모리 디바이스 콘텍스트의 핸들.

구문

HDC m_MemoryDC;

CBaseWindow.m_hPalette

CBaseWindow 클래스

윈도우의 팔레트의 핸들.

구문

HPALETTE m_hPalette;

CBaseWindow.m_bNoRealize

CBaseWindow 클래스

윈도우가 그 팔레트를 적용했는지 어떠했는지를 나타내는 플래그. TRUE 라면, 윈도우는 그 팔레트를 적용하고 있지 않다. 디폴트값은 FALSE .

구문

BYTE m_bNoRealize;

CBaseWindow.m_bBackground

CBaseWindow 클래스

팔레트가 백그라운드 팔레트여야할 것인가 어떤가를 나타내는 플래그. TRUE 라면, 그 팔레트는 백그라운드 팔레트로서 선택된다.

구문

m_bBackground;

CBaseWindow.m_bRealizing

CBaseWindow 클래스

새로운 팔레트가 적용되었는지 어떠했는지를 나타내는 플래그. 디버그 빌드에서는, 팔레트가 변하는 동안 이 값은 TRUE, 그 이외라면 FALSE. 이 변수는 리테일 빌드에서는 사용되지 않는다.

구문

BYTE m_bRealizing;

CBaseWindow.m_WindowLock

CBaseWindow 클래스

크리티컬 섹션, 오브젝트의 액세스를 계속시킨다.

구문

CCritSec m_WindowLock;

CBaseWindow.m_bDoGetDC

CBaseWindow 클래스

디바이스 콘텍스트 (DC)를 취득했는지 어떠했는지를 나타내는 플래그. TRUE 라면, 오브젝트는 윈도우의 DC 를 취득해 메모리 DC 를 생성 한다.

구문

BOOL m_bDoGetDC;

CBaseWindow.m_bDoPostToDestroy

CBaseWindow Class

윈도우가 그 데스트라크션멧세이지에 PostMessage 를 사용할까 SendMessage 를 사용하는지를 지정하는 플래그. TRUE 라면,DoneWithWindow 메소드는 PostMessage 함수를 사용해 자신에게 프라이베이트데스트라크션멧세이지를 보낸다. FALSE 라면,DoneWithWindow 는 SendMessage 를 사용해 메세지를 보낸다. 디폴트에서는 이 값은 FALSE 이다.

구문

BOOL m_bDoPostToDestroy;

CBaseWindow::ActivateWindow

CBaseWindow 클래스

상속 클래스의 요구에 따라 윈도우를 액티브하게 한다.

구문

virtual HRESULT ActivateWindow(void);

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_FALSE | 윈도우는 이미 액티브하게 되어 있다.
S_OK | 성공.

주의

이 메소드는 CBaseWindow::GetDefaultRect 를 호출해 윈도우 사이즈를 결정한다. 상속 클래스는 GetDefaultRect 를 오버라이드(override) 해 표시 이미지의 사이즈를 돌려주어야 한다.

윈도우가 이미 액티브하면,ActivateWindow 의 호출은 윈도우를 Z 순서의 맨 위에 움직인다, 그러나 윈도우의 리사이즈는 하지 않는다. 윈도우가 parent를 가지고 있어도 같이이다.

CBaseWindow::CBaseWindow

CBaseWindow 클래스

constructor　 　 메소드.

구문

CBaseWindow(
    BOOL bDoGetDC = TRUE
    BOOL bPostToDestroy = FALSE
);

파라미터

bDoGetDC
디바이스 콘텍스트를 취득했는지 어떠했는지를 나타내는 불리언 값.
bPostToDestroy
m_bDoPostToDestroy 멤버 변수를 지정하는 불리언 값.

주의

오브젝트를 생성 한 다음에,PrepareWindow 메소드를 호출해 윈도우를 생성 한다. 그것은 이것도 또 가상 메소드인 InitialiseWindow 를 호출한다. 이러한 메소드는 constructor　 　 으로부터 분리되어 있으므로, 필요하면 상속 클래스는 그것들을 오버라이드(override) 할 수가 있다.

bDoGetDC 의 값이 TRUE 라면,CBaseWindow 오브젝트는 윈도우의 디바이스 콘텍스트 (DC)의 핸들을 취득해, 그것을 m_hdc 멤버 변수에 스토어 한다. 그 오브젝트는 또m_MemoryDC 멤버 변수에 스토어 되고 있는 호환 메모리 DC 도 생성 한다. 이러한 처리는 InitialiseWindow 내에서 행해진다.

CBaseWindow::CompleteConnect

CBaseWindow 클래스

윈도우에 렌더러의 입력 핀이 접속된 것을 통지한다.

구문

HRESULT CompleteConnect(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 윈도우의 액티브 플래그 (m_bActivated )를 FALSE 에 리셋 한다. 비디오 렌더러가 핀 접속을 완료했을 때,ActivateWindow 를 호출해 윈도우의 사이즈와 위치를 설정할 가능성이 있다. ActivateWindow 에 이러한 속성을 재계산시키려면 , 최초로 CompleteConnect 메소드를 호출하는 것.

CBaseWindow::DoCreateWindow

CBaseWindow 클래스

윈도우를 생성 한다.

구문

HRESULT DoCreateWindow(void);

반환값

성공이라면 S_OK 를 돌려주는, 실패라면 그 원인을 나타내는 HRESULT 값을 돌려준다.

주의

PrepareWindow 메소드는 이 메소드를 호출한다.

CBaseWindow::DoneWithWindow

CBaseWindow 클래스

윈도우를 삭제한다.

구문

virtual HRESULT DoneWithWindow(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드를 파생 오브젝트의 소멸자 메소드로부터 호출하는 것.

지금 메소드가 윈도우를 생성 한 같은 thread로부터 불려 간다면, 메소드는 다음의 처리를 실시한다 :

  • InactivateWindow 메소드를 호출해, 윈도우를 비액티브하게 한다 .
  • UninitialiseWindow 메소드를 호출해, 윈도우에 사용되거나 소스를 해방한다.
  • 윈도우를 삭제한다.

DoneWithWindow 를 호출하는 thread가 그 윈도우를 생성 한 thread는 아니면, 메소드는 프라이빗 「destroy」메세지를 그 윈도우에 보낸다. 그 윈도우는 이 메세지를 받아들이면(자), 자기 자신에게 DoneWithWindow 를 호출한다. (만약 m_bDoPostToDestroy 가 TRUE 라면, 그 윈도우는 PostMessage 를 사용한다. )

CBaseWindow::DoRealisePalette

CBaseWindow 클래스

윈도우의 현재의 팔레트를 적용한다.

구문

virtual HRESULT DoRealisePalette(
    BOOL bForceBackground
);

파라미터

bForceBackground
팔레트를 백그라운드 팔레트로 할지 어떨지를 지정하는 불리언 값. 상세한 것에 대하여는, Platform SDK 의 「SelectPalette」를 참조할것.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_FALSE | GdiFlush 에의 내부 호출이 에러를 돌려주었다.
S_OK | 성공.

주의

CBaseWindow::OnPaletteChange 메소드는 이 메소드를 호출한다. 새로운 팔레트를 설정하려면 ,CBaseWindow::SetPalette 메소드를 호출하는 것.

CBaseWindow::DoSetWindowForeground

CBaseWindow 클래스

윈도우를 foreground에 가져온다.

구문

void DoSetWindowForeground(
    BOOL bFocus
);

파라미터

bFocus
윈도우에 포커스를 줄지 어떨지를 나타내는 불리언 값. 이 값이 TRUE 라면, 윈도우는 포커스를 얻는다.

CBaseWindow::DoShowWindow

CBaseWindow 클래스

윈도우의 표시 상태를 설정한다.

구문

HRESULT DoShowWindow(
    LONG ShowCmd
);

파라미터

ShowCmd
어떻게 윈도우를 표시 상태로 하는지를 지정하는 플래그. 이 값은 Microsoft® Windows® ShowWindow 함수의 nCmdShow 파라미터로 정의되는 정수를 취할 수 있다. 상세한 것에 대하여는, Platform SDK 를 참조할것.

반환값

S_OK 를 돌려준다.

CBaseWindow::GetClassWindowStyles

CBaseWindow 클래스

윈도우의 클래스 스타일을 취득한다.

구문

virtual LPTSTR GetClassWindowStyles(
    DWORD *pClassStyles,
    DWORD *pWindowStyles,
    DWORD *pWindowStylesEx
) PURE;

파라미터

pClassStyles
클래스 스타일을 받는 변수에의 포인터.
pWindowStyles
윈도우 스타일을 받는 변수에의 포인터.
pWindowStylesEx
확장 윈도우 스타일을 받는 변수에의 포인터.

반환값

클래스명을 포함한 정적 텍스트 캐릭터 라인을 돌려준다.

주의

CBaseWindow::PrepareWindow 메소드는 이 메소드를 호출해, 윈도우의 클래스 스타일과 윈도우 스타일을 취득한다.

이 메소드는 순수 가상, 상속 클래스는 그것을 이행 해야 한다. 다음의 샘플은 그 이행예를 나타낸다.

LPTSTR CMyWindowClass::GetClassWindowStyles(DWORD *pClassStyles,
                                            DWORD *pWindowStyles,
                                            DWORD *pWindowStylesEx)
{
    *pClassStyles = CS_HREDRAW | CS_VREDRAW;
    *pWindowStyles = WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN;
    *pWindowStylesEx = WS_EX_WINDOWEDGE;
    return TEXT("MyWindowClass");
}

이 오브젝트는 RegisterClass 함수에 보내지는 WNDCLASS 구조체의 lpszClassName 멤버의 클래스 스타일을 사용한다. 이 오브젝트는 CreateWindowEx 함수의 dwExStyle 와 dwStyle 파라미터의 윈도우 스타일을 사용한다. 상세한 것에 대하여는, Platform SDK 를 참조할것.

CBaseWindow::GetDefaultRect

CBaseWindow 클래스

클라이언트 에리어의 디폴트 사이즈를 취득한다.

구문

virtual RECT GetDefaultRect(void);

반환값

디폴트 직사각형을 돌려준다.

주의

윈도우가 액티브하게 될 때, 오브젝트는 이 메소드를 호출해, 윈도우의 클라이언트 에리어를 어느 크기로 하는지를 확인한다. base class에서는, 이 메소드는 정수 DEFHEIGHT 와 DEFWIDTH 로 정의되는 높이와 폭의 직사각형을 돌려준다. 비디오 렌더러-에서는, 보통 상속 클래스는 네이티브인 비디오 이미지의 사이즈를 돌려준다.

CBaseWindow::GetMemoryHDC

CBaseWindow 클래스

메모리 디바이스 콘텍스트 (DC)의 핸들을 취득한다.

구문

virtual HDC GetMemoryHDC(void);

반환값

메모리 DC 의 핸들을 돌려준다.

CBaseWindow::GetWindowHDC

CBaseWindow 클래스

윈도우의 디바이스 콘텍스트 (DC)의 핸들을 취득한다.

구문

HDC GetWindowHDC(void);

반환값

DC 의 핸들을 돌려준다.

CBaseWindow::GetWindowHeight

CBaseWindow 클래스

윈도우의 현재의 높이를 취득한다.

구문

LONG GetWindowHeight(void);

반환값

윈도우의 높이를 돌려주는, 픽셀값.

CBaseWindow::GetWindowHWND

CBaseWindow 클래스

윈도우의 핸들을 취득한다.

구문

HWND GetWindowHWND(void);

반환값

윈도우의 핸들을 돌려준다.

CBaseWindow::GetWindowWidth

CBaseWindow 클래스

윈도우의 현재의 폭을 취득한다.

구문

LONG GetWindowWidth(void);

반환값

윈도우의 폭을 돌려주는, 픽셀값.

CBaseWindow::InactivateWindow

CBaseWindow 클래스

윈도우를 비액티브하게 한다. base class에서는, 이 메소드는 윈도우를 숨긴다.

구문

virtual HRESULT InactivateWindow(void);

반환값

다음 표에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
S_FALSE | 윈도우는 이미 비액티브.

CBaseWindow::InitialiseWindow

CBaseWindow 클래스

윈도우를 초기화한다.

구문

virtual InitialiseWindow(
    HWND hwnd
);

파라미터

hwnd
윈도우의 핸들.

반환값

S_OK 를 돌려준다.

주의

디폴트에서는, 이 메소드는 윈도우의 디바이스 콘텍스트 (DC)를 취득해, 호환의 메모리 DC 를 생성 한다. 그러나 m_bDoGetDC 플래그의 값이 FALSE 라면, 이 메소드는 디바이스 콘텍스트를 취득하지 않는다. 메모리 DC 는 윈도우에 비트 맵을 소총탄 하기 전에 비트 맵을 선택할 때에 유용하다.

DoCreateWindow 메소드는 이 메소드를 호출한다.

CBaseWindow::OnClose

CBaseWindow 클래스

WM_CLOSE 메세지를 취급한다.

구문

virtual BOOL OnClose(void);

반환값

TRUE 를 돌려준다.

주의

base class에서는, 이 메소드는 단지 윈도우를 숨기는 것만으로 있다. 보통, 상속 클래스는 이 메소드를 오버라이드(override) 해,EC_USERABORT 이벤트를 동시에 보낸다. 이 메소드를 오버라이드(override) 해 윈도우를 삭제해서는 안 된다. 그 대신해, 자신의 필터가 삭제될 때,CBaseWindow::DoneWithWindow 메소드를 호출하는 것.

CBaseWindow::OnPaletteChange

CBaseWindow 클래스

팔레트 변경 메세지를 취급한다.

구문

virtual LRESULT OnPaletteChange(
    HWND hwnd,
    UINT Message
);

파라미터

hwnd
윈도우의 핸들.
Message
메세지 ID.

반환값

메세지가 처리되면(자) 0 을 돌려주어, 메세지가 처리되지 않았으면 1 을 돌려준다.

주의

이 메소드는 WM_PALETTECHANGED 와 WM_QUERYNEWPALETTE 메세지를 취급한다. DoRealisePalette 메소드를 호출해 새로운 팔레트를 적용한다.

CBaseWindow::OnReceiveMessage

CBaseWindow 클래스

윈도우 메세지를 취급한다.

구문

virtual LRESULT OnReceiveMessage(
    HWND hwnd,
    INT uMsg,
    WPARAM wParam,
    LPARAM lParam
);

파라미터

hwnd
윈도우의 핸들.
uMsg
메세지 ID.
wParam
제 1 메세지 파라미터.
lParam
제 2 메세지 파라미터.

반환값

메세지가 처리되면(자) 0 을 돌려주어, 메세지가 처리되지 않았으면 1 을 돌려준다.

주의

base class는 다음의 메세지를 취급한다.

  • WM_CLOSE
  • WM_MOVE
  • WM_PALETTECHANGED
  • WM_QUERYNEWPALETTE
  • WM_SIZE
  • WM_SYSCOLORCHANGE

상속 클래스는 이 메소드를 오버라이드(override) 해, 다른 메세지를 취급할 수가 있다. 상속 클래스는 base class 메소드를 호출해, 그 상속 클래스에서는 무시되는 메세지를 취급해야 한다.

CBaseWindow::OnSize

CBaseWindow 클래스

WM_SIZE 메세지를 취급한다.

구문

virtual BOOL OnSize(
    LONG Width,
    LONG Height
);

파라미터

Width
클라이언트 에리어의 폭, 픽셀값.
Height
클라이언트 에리어의 높이, 픽셀값.

반환값

TRUE 를 돌려준다.

주의

이 메소드는 새로운 폭과 높이를 스토어 한다. 받은 값에 대해서,CBaseWindow::GetWindowHeight 와 CBaseWindow::GetWindowWidth 메소드를 호출하는 것.

CBaseWindow::PaintWindow

CBaseWindow 클래스

윈도우를 재드로잉(Drawing) 시킨다.

구문

void PaintWindow(
    BOOL bErase
);

파라미터

bErase
백그라운드가 소거할지 어떨지를 지정하는 값. 이 값이 TRUE 라면, 백그라운드는 소거된다.

주의

이 메소드는 윈도우의 전클라이언트 에리어를 무효로 하는 것에 의해 WM_PAINT 메세지를 생성한다.

CBaseWindow::PerformanceAlignWindow

CBaseWindow 클래스

퍼포먼스를 최고로 하기 위해서 윈도우를 DWORD 경계에 갖춘다.

구문

HRESULT PerformanceAlignWindow(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 왼쪽과 위에의단을 DWORD 경계에 갖추어 퍼포먼스를 개선한다. 윈도우가 parent를 가지고 있어도, 이 메소드는 S_OK 를 돌려주지만 경계에의 갖추고를 실행한다.

CBaseWindow::PossiblyEatMessage

CBaseWindow 클래스

상속 클래스에 다른 윈도우에의 메세지의 전송을 허가한다.

구문

virtual BOOL PossiblyEatMessage(
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam
);

파라미터

uMsg
메세지 ID.
wParam
제 1 메세지 파라미터.
lParam
제 2 메세지 파라미터.

반환값

메세지가 전송 되면(자) TRUE 를 돌려주는, 실패하면(자) FALSE 를 돌려준다. base class는 FALSE 를 돌려준다.

주의

CBaseWindow::OnReceiveMessage 메소드는 메세지를 취급하기 전에 PossiblyEatMessage 를 호출한다. PossiblyEatMessage 가 TRUE 를 돌려주면(자),PossiblyEatMessage 는 그 메세지를 무시한다. 상속 클래스는 PossiblyEatMessage 를 오버라이드(override) 해, 소유자 윈도우에 메세지를 전송 할 수가 있다. 예를 들어,CBaseWindow 로부터 파생한 CBaseControlWindow 클래스는 키보드와 마우스의 메세지를 전송 한다.

CBaseWindow::PrepareWindow

CBaseWindow 클래스

윈도우를 생성 한다.

구문

virtual HRESULT PrepareWindow(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_FAIL | 실패.

주의

이 메소드는 오브젝트를 생성 한 다음에 호출하는 것. 이 메소드는 몇개의 초기 등록을 실시하고 나서 DoCreateWindow 메소드를 호출해 윈도우를 생성 한다.

CBaseWindow::SetPalette

CBaseWindow 클래스

윈도우에 팔레트를 인스톨 한다.

구문

virtual HRESULT SetPalette(
    HPALETTE hPalette
);

HRESULT SetPalette(void);

파라미터

hPalette
새로운 팔레트의 핸들. NULL 는 불가.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_FALSE | GdiFlush 에의 내부 호출이 에러를 돌려주었다.
S_OK | 성공.

주의

hPalette 파라미터는 새로운 팔레트를 지정한다. 메소드가 파라미터없이 불려 가면(자),m_hPalette 멤버 변수에 의해 주어지는 팔레트가 선택된다. 호출원래는 m_hPalette 의 유효성을 확인해야 한다.

m_bNoRealize 멤버 변수의 값이 FALSE (디폴트)라면, 이 메소드는 그 팔레트를 선택해 그것을 적용한다. 그렇지 않으면, 팔레트를 선택하지만, 그것을 적용하지 않는다. 오브젝트는 사용되고 있던 이전의 팔레트를 삭제하지 않는다. 호출원래는 팔레트 삭제의 책임을 가진다.

그 윈도우를 소유자로 하는 thread가 아니어도, thread는 이 메소드를 안전하게 호출할 수가 있다. 윈도우는 그것 자신에게 OnPaletteChange 메소드에의 호출을 킥 하는 프라이빗 메세지를 보낸다.

CBaseWindow::SetRealize

CBaseWindow 클래스

윈도우가 팔레트를 적용할지 어떨지를 지정한다.

구문

void SetRealize(
    BOOL bRealize
);

파라미터

bRealize
팔레트를 리아라이즈 할지 어떨지를 지정하는 불리언 값. 만약 TRUE 라면,SetPalette 메소드가 팔레트를 리아라이즈 한다.

주의

디폴트에서는,SetPalette 메소드는 지정한 팔레트를 적용한다. 이 메소드를 호출해 디폴트를 변경하는 것, 그렇다면 복수의 팔레트가 선택되지만 적용되지 않는다. 이 메소드는 m_bNoRealize 멤버 변수를 설정한다.

CBaseWindow::UninitialiseWindow

CBaseWindow 클래스

윈도우의 리소스를 해방한다.

구문

virtual UninitialiseWindow(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 InitialiseWindow 메소드에 의해 취득된 리소스를 프리로 한다. DoneWithWindow 메소드는 이 메소드를 호출한다.


CBasicAudio 클래스

CBasicAudio 클래스의 계층

CBaseBasicAudio 클래스는,IBasicAudio 인터페이스의 IDispatch 인터페이스 컴퍼넌트를 처리해, 파생 필터 클래스에 의해 이행 되는 IBasicAudio 의 프로퍼티 및 메소드는 순수 가상대로 해 둔다.

CBasicAudio::GetIDsOfNames ,CBasicAudio::GetTypeInfo ,CBasicAudio::GetTypeInfoCount , 및 CBasicAudio::Invoke 멤버 함수는,IDispatch 인터페이스의 표준적인 이행으로,CBaseDispatch 클래스 ( 및 타입 라이브러리)를 사용해 커멘드를 해석해,IBasicAudio 인터페이스의 순수 가상 메소드에 건네준다.

Microsoft® DirectShow® 에서는, 볼륨의 스케일로서 100 분의 1 데시벨의 단위를 사용한다. 이 값이 0 의 경우, 디바이스로 지원 되고 있는 최대 볼륨을 나타낸다. 이 값이 -10, 000 의 경우는, 최소 볼륨 (보통, 무음)이다. 밸런스는 -10, 000 ~ 10,000 의 범위에서 나타내져 0 이 중간이다. 밸런스값이 부의 경우, 오른쪽 채널이 그 데시벨값의 분만큼 감쇠되는 (즉 소리가 작아진다) 일을 의미한다. 같이 밸런스값이 정의 경우는, 오른쪽 채널의 소리가 왼쪽 채널보다 커진다. 즉, 왼쪽 채널이 그 데시벨값의 분만큼 감쇠된다.

멤버 함수

CBasicAudio CBasicAudio 오브젝트를 생성 한다.

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingQueryInterface 지정된 참조 카운트의 인터페이스를 취득한다.

이행 되는 IDispatch 메소드

GetIDsOfNames | 단일의 멤버 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자에 맵 한다. 이 식별자는, 이후의 CBasicAudio::Invoke 멤버 함수의 호출로 사용할 수 있다.
GetTypeInfo | 타입 정보 오브젝트를 취득한다. 인터페이스의 타입 정보를 취득할 수 있다.
GetTypeInfoCount | 오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.
Invoke | 오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

CBasicAudio::CBasicAudio

CBasicAudio 클래스

CBasicAudio 오브젝트를 생성 한다.

구문

CBasicAudio(
  const TCHAR *pName,
  LPUNKNOWN pUnk
  );

파라미터

pName
디버그를 위해서(때문에) CBasicAudio constructor　 　 으로 사용되는 오브젝트의 이름에의 포인터.
pUnk
이 오브젝트의 소유자에게로의 포인터.

반환값

반환값 없음.

주의

스태틱 메모리에 pName 파라미터를 할당한다. 오브젝트를 생성 및 삭제할 경우에, 디버그 화면에 이 이름이 표시된다.

CBasicAudio::GetIDsOfNames

CBasicAudio 클래스

단일의 멤버 함수 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자에 맵 한다. 이 식별자는, 이후의 CBasicAudio::Invoke 멤버 함수의 호출로 사용할 수 있다.

구문

HRESULT GetIDsOfNames(

  REFIID riid,

  OLECHAR **rgszNames,

  UINT cNames,

  LCID lcid,

  DISPID *rgdispid

  );

파라미터

riid
참조 식별자. 장래적인 사용을 위해서(때문에) 예약되고 있다. NULL 가 아니면 안된다.
rgszNames
건네받은 맵 하는 이름의 배열에의 포인터의 주소.
cNames
맵 되는 이름의 수.
lcid
이름을 해석하는 로케일 문맥.
rgdispid
호출원 할당하고가 끝난 배열에의 포인터. 각 요소에는,rgszNames 배열에게 건네지는 이름의 1 개에 대응하는 ID 가 포함된다. 최초의 요소는 멤버의 이름을 나타내, 이후의 요소는 각 멤버의 파라미터를 나타낸다.

반환값

다음의 몇개의 값을 돌려준다.
DISP_E_UNKNOWN_CLSID | CLSID 가 인식되지 않았다.
DISP_E_UNKNOWNNAME | 1 개(살) 이상의 이름이 불명했다. 돌려주어진 DISPID 에는, 불명한 이름에 대응하는 각 엔트리의 DISPID_UNKNOWN 가 포함된다.
E_OUTOFMEMORY | 메모리 부족.
S_OK | 성공.

CBasicAudio::GetTypeInfo

CBasicAudio 클래스

타입 정보 오브젝트를 취득한다. 인터페이스의 타입 정보를 취득할 수 있다.

구문

HRESULT GetTypeInfo(

  UINT itinfo,

  LCID lcid,

  ITypeInfo **pptinfo

  );

파라미터

itinfo
돌려주어지는 타입 정보. 제로를 건네주어,IDispatch 이행의 타입 정보를 취득한다.
lcid
타입 정보의 로케일 ID. 로컬라이즈 된 멤버명을 지원 하는 클래스의 경우, 오브젝트는 다른 언어가 다른 타입 정보를 돌려줄 수가 있는 경우가 있다. 이것은, 로컬라이즈 된 멤버명을 지원 하는 클래스에서 중요하다. 로컬라이즈 된 멤버명을 지원 하지 않는 클래스의 경우, 이 파라미터는 무시할 수가 있다.
pptinfo
요구된 타입 정보 오브젝트에의 포인터의 주소.

반환값

pptinfo 가 무효인 경우는, E_POINTER 를 돌려준다. itinfo 가 제로 이외의 경우는, TYPE_E_ELEMENTNOTFOUND 를 돌려준다. 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 타입을 취득하기 위한 호출의 1 개로부터 HRESULT 를 돌려준다. HRESULT 는 에러를 나타내, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.

CBasicAudio::GetTypeInfoCount

CBasicAudio 클래스

오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.

구문

HRESULT GetTypeInfoCount(

  UINT *pctinfo

  );

파라미터

pctinfo
오브젝트가 제공하는 타입 정보 인터페이스의 수를 받는 장소에의 포인터. 오브젝트가 타입 정보를 제공했을 경우, 이 수는 1 이다. 그 이외의 경우는, 0 이다.

반환값

pctinfo 가 무효인 경우는, E_POINTER 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

CBasicAudio::Invoke

CBasicAudio 클래스

오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

구문

HRESULT Invoke(

  DISPID dispidMember,

  REFIID riid,

  LCID lcid,

  WORD wFlags,

  DISPPARAMS *pdispparams,

  VARIANT *pvarResult,

  EXCEPINFO *pexcepinfo,

  UINT *puArgErr

  );

파라미터

dispidMember
멤버의 식별자. 디스팟치 식별자를 취득하려면 ,CBasicAudio::GetIDsOfNames 또는 오브젝트의 문서를 사용한다.
riid
장래적인 사용을 위해서(때문에) 예약되고 있다. IID_NULL 가 아니면 안된다.
lcid
인수를 해석하는 로케일 문맥.
wFlags
CBasicAudio::Invoke 호출의 문맥을 기술하는 플래그.
pdispparams
인수의 배열, 이름 첨부 인수의 인수 디스팟치 ID 의 배열, 및 배열내의 요소의 수를 포함한 DISPPARAMS 구조체에의 포인터.
pvarResult
결과가 저장 되는 포인터, 또는 호출해 원이 결과를 요구하지 않은 경우는 NULL.
pexcepinfo
예외 정보를 포함한 구조체에의 포인터.
puArgErr
rgvarg 배열내에서, 에러가 있는 최초의 인수의 인덱스에의 포인터. rgvarg 배열은 DISPPARAMS 구조체의 멤버이다.

반환값

riid 가 IID_NULL 이외의 경우는, DISP_E_UNKNOWNINTERFACE 를 돌려준다. 호출이 실패했을 경우는,CBasicAudio::GetTypeInfo 로부터 에러 코드의 1 개를 돌려준다. 그 이외의 경우는,IDispatch::Invoke 에의 호출로부터 HRESULT 를 돌려준다.

CBasicAudio::NonDelegatingQueryInterface

CBasicAudio 클래스

지정된 참조 카운트의 인터페이스를 돌려준다.

구문

HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void **ppv
  );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

디폴트에서는,IBasicAudio 및 IUnknown 인터페이스에의 포인터를 돌려준다. 이 멤버 함수를 오버라이드(override) 해, 상속 클래스로 이행 된 추가의 인터페이스를 공개한다.

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 한다.


CCmdQueue 클래스

CCmdQueue 클래스는,CDeferredCommand 오브젝트의 큐, 및 큐에 넣어진 커멘드의 추가, 삭제, 상태의 체크, 및 실행하기 위한 멤버 함수를 제공하는 base class이다. CCmdQueue 오브젝트는,IQueueCommand 메소드를 이행 하는 오브젝트의 일부이다. 필터 그래프 매니저는,IQueueCommand 메소드를 이행 해, 어플리케이션이 필터 그래프에 대한 커멘드를 큐에 넣을 수가 있도록(듯이) 한다. IQueueCommand 인터페이스를 이행 하는 필터는, 이 클래스를 직접 사용한다. CDeferredCommand 오브젝트를 사용하는 경우는, 이 클래스로부터 큐를 파생시키지 않으면 안 된다.

동기에게는, 「엉성하다」와「정확」의 2 개의 모드가 있다. 엉성한 모드에서는, 어플리케이션은 지정된 시간까지 대기한 후, 커멘드를 실행한다. 정확 모드에서는, 어플리케이션은, 그 시간에 표시되는 샘플에 대한 처리가 시작 될 때까지 대기한 후, 커멘드를 실행한다. 어느 쪽을 이행 할까는, 필터에 의해 정해진다. 필터 그래프 매니저는, 필터 그래프 매니저의 큐에 넣어지는 커멘드에 대해, 항상 엉성한 모드를 이행 한다.

엉성한 동기가 필요한 경우, 실행해야 할 커멘드가 큐에 넣어질 때까지 대기한 후, 커멘드를 실행할 수가 있다. 이것은,CCmdQueue::GetDueCommand 를 호출하는 것에 의해 실행할 수 있다. 복수의 항목을 대기하고 있는 경우는,CCmdQueue::GetDueHandle 으로부터 이벤트 핸들을 취득해, 통지제가 되면 CCmdQueue::GetDueCommand 를 호출한다. 스트림 타임은,CCmdQueue::Run 멤버 함수와 CCmdQueue::EndRun 멤버 함수의 호출동안에서만 진행된다. 핸들이 설정되어 있어도, 커멘드의 준비가 되어 있다고 하는 보증은 없다. 이벤트가 통지제가 될 때마다, (타임 아웃을 0 으로 해) GetDueCommand 멤버 함수를 호출한다. 이것에 의해, 커멘드의 준비가 되어 있지 않은 경우, E_ABORT 를 돌려줄 수가 있다.

정확한 동기가 필요한 경우는,CCmdQueue::GetCommandDueFor 멤버 함수를 호출해, 처리하려고 하고 있는 샘플을 파라미터로서 건네준다. 이것은, 다음의 것을 돌려준다.

  • 스트림 타임시 또는 그 전에 실행해야 하는 스트림 타임 커멘드.
  • 스트림 타임의 프레젠테이션시 또는 그 전에 실행해야 하는 프레젠테이션 타임 커멘드. 이것은,CCmdQueue::Run 및 CCmdQueue::EndRun 멤버 함수의 사이에서만 실시한다. 이 범위외의 경우, 스트림 타임부터 프레젠테이션 시간에의 매핑이 인식되지 않는다.
  • 현재 실행해야 하는 프레젠테이션 타임 커멘드.

포즈 모드시에 처리될 가능성이 있는 샘플에 대해 정확한 동기가 필요한 경우는, 스트림 타임 커멘드를 사용해야 한다.

모든 경우에 대해, 커멘드는 불려 가는지, 삭제될 때까지 큐에 남는다. 이벤트 핸들의 설정 및 리셋은, 모두 이 큐 오브젝트에 의해 관리된다.

Protected 데이터 멤버

m_bRunning | 실행 상태의 플래그. 실행중의 경우는 TRUE 로 설정된다.
m_dwAdvise | 기준 클락에서의아드바이즈 식별자 (미처리의 아드바이즈가 없는 경우는 0).
m_evDue | 커멘드를 실행하는 시간을 설정한다.
m_listPresentation | 프레젠테이션 시간의 큐에 넣어진 커멘드를 저장 한다.
m_listStream | 스트림 타임의 큐에 넣어진 커멘드를 저장 한다.
m_Lock | 리스트에의 액세스를 보호한다.
m_pClock | 현재의 기준 클락.
m_StreamTimeOffset | m_bRunning 가 TRUE 인 경우의 스트림 타임의 오프셋(offset)를 저장 한다.
m_tCurrentAdvise | 아드바이즈타임은 이 프레젠테이션 시간용이다.

멤버 함수

CCmdQueue | CCmdQueue 오브젝트를 생성 한다.
CheckTime | 지정된 시간이 되었는지 어떠했는지를 판단한다.
GetDueHandle | 통지제가 되는 이벤트 핸들을 취득한다.

오버라이드(override) 가능한 멤버 함수

EndRun | 정지 또는 포즈 모드로 전환한다.
GetCommandDueFor | 지정된 시간에 스케줄 되고 있는 지연 커멘드를 취득한다.
GetDueCommand | 다음에 실행할 예정의 커멘드에의 포인터를 취득한다.
Insert | CDeferredCommand 오브젝트를 큐에 추가한다.
New | 실행하는 커멘드를 초기화해, 새로운 CDeferredCommand 오브젝트를 돌려준다.
Remove | CDeferredCommand 오브젝트를 큐로부터 삭제한다.
Run | 실행 모드로 전환한다.
SetSyncSource | 타이밍에 사용하는 클락을 설정한다.
SetTimeAdvise | 기준 클락을 사용해 바다거북 겨이삭띠를 설정한다.

CCmdQueue::CCmdQueue

CCmdQueue 클래스

CCmdQueue 오브젝트를 생성 한다.

구문

CCmdQueue(void);

반환값

반환값 없음.

CCmdQueue::CheckTime

CCmdQueue 클래스

지정된 시간이 되었는지 어떠했는지를 판단한다.

구문

BOOL CheckTime(
CRefTime time,
BOOL bStream
    );

파라미터

time
체크하는 시간.
bStream
time 파라미터가 스트림 타임값의 경우는 TRUE,time 가 프레젠테이션 타임값의 경우는 FALSE.

반환값

아직 지정된 시간을 지나지 않은 경우는, TRUE 를 돌려준다.

CCmdQueue::EndRun

CCmdQueue 클래스

정지 또는 포즈 모드로 전환한다.

구문

virtual HRESULT EndRun(void);

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는 에러를 나타내, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
S_OK 또는 NOERROR | 성공.

주의

이 멤버 함수를 호출한 후의 스트림 타임과 프레젠테이션 시간과의 시간의 매핑은 불명하다. CCmdQueue::Run 멤버 함수를 호출해, 이 매핑을 실행한다.

CCmdQueue::GetCommandDueFor

CCmdQueue 클래스

지정된 시간에 스케줄 되고 있는 지연 커멘드를 취득한다.

구문

virtual HRESULT GetCommandDueFor(
REFERENCE_TIME tStream,
CDeferredCommand **ppCmd
    );

파라미터

tStream
커멘드가 스케줄 되고 있는 시간.
ppCmd
tStream 파라미터로 지정된 시간에 실행되는 지연 커멘드에의 포인터의 주소.

반환값

실행하는 커멘드가 없는 경우는 VFW_E_NOT_FOUND 를 돌려준다. 그 이외의 경우는 S_OK 를 돌려준다.

주의

이 멤버 함수는, 스트림 타임을 취해, 그 시간에 스케줄 되고 있는 지연 커멘드를 돌려준다. 실제의 스트림 타임의 오프셋(offset)는, 커멘드 큐를 실행할 경우에 계산된다. 커멘드는, 실행되는지, 삭제될 때까지 큐에 남는다. 이 멤버 함수는 블록 하지 않는다.

CCmdQueue::GetDueCommand

CCmdQueue 클래스

다음에 실행할 예정의 커멘드에의 포인터를 취득한다.

구문

virtual HRESULT GetDueCommand(
CDeferredCommand **ppCmd,
long msTimeout
    );

파라미터

ppCmd
지연 커멘드에의 포인터의 주소.
msTimeout
타임 아웃을 실행하기까지 대기하는 시간.

반환값

타임 아웃이 발생했을 경우는, E_ABORT 를 돌려준다. 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 에러를 돌려준다. IUnknown::AddRef 를 사용해 인크리먼트(increment) 된 오브젝트를 돌려준다.

주의

이 멤버 함수는, 보류중의 커멘드가 실행될 때까지 블록 한다. 이 멤버 함수는,msTimeout 파라미터로 밀리 세컨드 단위로 지정된 시간 블록 한다. 스트림 타임 커멘드는,CCmdQueue::Run 멤버 함수와 CCmdQueue::EndRun 멤버 함수의 호출동안에서만 실행된다. 이 커멘드는, 실행되는지, 삭제될 때까지 큐에 남는다.

CCmdQueue::GetDueHandle

CCmdQueue 클래스

통지제의 이벤트 핸들을 취득한다.

구문

HANDLE GetDueHandle(void);

반환값

이벤트 핸들을 돌려준다.

주의

실행할 예정의 지연 커멘드가 있는 경우는 이벤트 핸들을 돌려준다 (CCmdQueue::GetDueCommand 가 블록 하는 경우).

CCmdQueue::Insert

CCmdQueue 클래스

CDeferredCommand 오브젝트를 큐에 추가한다.

구문

virtual HRESULT Insert(
CDeferredCommand *pCmd
    );

파라미터

pCmd
큐에 추가하는 CDeferredCommand 오브젝트에의 포인터.

반환값

디폴트의 이행에서는 S_OK 를 돌려준다.

CCmdQueue::New

CCmdQueue 클래스

실행하는 커멘드를 초기화해, 새로운 CDeferredCommand 오브젝트를 돌려준다.

구문

virtual HRESULT New(
CDeferredCommand **ppCmd,
LPUNKNOWN pUnk,
REFTIME time,
GUID *iid,
long dispidMethod,
short wFlags,
long cArgs,
VARIANT *pDispParams,
VARIANT *pvarResult,
short *puArgErr,
BOOL bStream
    );

파라미터

ppCmd
CDeferredCommand 오브젝트에의 포인터의 주소. 이것에 의해, 어플리케이션은 커멘드를 취소하거나 커멘드의 새로운 프레젠테이션 시간을 설정하거나 예측 정보를 취득할 수가 있다.
pUnk
커멘드를 실행하는 오브젝트에의 포인터.
time
큐에 넣어진 커멘드를 실행하는 시간.
iid
호출하는 인터페이스의 글로벌 유니크 식별자 (GUID )에의 포인터.
dispidMethod
불려 가는 인터페이스 위에의 메소드.
wFlags
호출의 문맥을 기술하는 플래그. 이 파라미터는, OLE IDispatch::Invoke 메소드와 같은 플래그를 지원 한다.
cArgs
건네받는 인수의 수.
pDispParams
디스팟치파라메이타에 관련지을 수 있었던 변형형의 리스트에의 포인터.
pvarResult
결과가 돌려주어지는 리스트에의 포인터.
puArgErr
마지막 에러가 발생한 pDispParams 파라미터 리스트내의 인덱스에의 포인터.
bStream
time 파라미터가 스트림 타임값 (TRUE)인지, 프레젠테이션 타임값 (FALSE)인지를 나타내는 값.

반환값

성공했을 경우는, S_OK 를 돌려준다. ppCmd 가 새로운 CDeferredCommand 오브젝트의 생성시에 NULL 를 돌려주는 경우는, E_OUTOFMEMORY 를 돌려준다. 그 이외의 경우는, 새로운 CDeferredCommand 오브젝트를 생성 사용으로 했을 때의 에러를 나타내는 HRESULT 를 돌려준다. 에러가 발생했을 경우는, 오브젝트는 큐에 넣어지지 않는다.

주의

새로운 CDeferredCommand 오브젝트는 파라미터를 사용해 초기화되어 생성중에 큐에 추가된다. 이 메소드는, OLE IDispatch::Invoke 메소드를 닮아 있다.

wFlags 파라미터는, 다음과 같은 값이 된다.
DISPATCH_METHOD | 멤버는 메소드로서 실행되고 있다. 프로퍼티가 같은 이름인 경우는, 이것과 DISPATCH_PROPERTYGET 플래그의 양쪽 모두를 설정할 수 있다.
DISPATCH_PROPERTYGET | 멤버는 프로퍼티 또는 데이터 멤버로서 취득되고 있다.
DISPATCH_PROPERTYPUT | 멤버는 프로퍼티 또는 데이터 멤버로서 변경되고 있다.
DISPATCH_PROPERTYPUTREF | 멤버는, 값의 할당은 아니고, 참조의 할당에 의해 변경되고 있다. 이 값은, 프로퍼티가 오브젝트에의 참조를 받아들이는 경우에게만 유효하다.

CCmdQueue::Remove

CCmdQueue 클래스

CDeferredCommand 오브젝트를 큐로부터 삭제한다.

구문

virtual HRESULT Remove(
CDeferredCommand *pCmd
    );

파라미터

pCmd
큐로부터 삭제하는 CDeferredCommand 오브젝트에의 포인터.

반환값

큐내에 오브젝트가 발견되지 않았던 경우는 VFW_E_NOT_FOUND 을 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

CCmdQueue::Run

CCmdQueue 클래스

스트림 타임에 의해 지연 되고 있는 커멘드를 실행할 수 있도록(듯이) 실행 모드로 전환한다.

구문

virtual HRESULT Run(
REFERENCE_TIME tStreamTimeOffset
    );

파라미터

tStreamTimeOffset
오프셋(offset) 타임.

반환값

디폴트의 이행에서는 S_OK 를 돌려준다.

주의

실행 모드에서는, 스트림 타임과 프레젠테이션 시간의 매핑이 인식된다.

CCmdQueue::SetSyncSource

CCmdQueue 클래스

타이밍에 사용하는 클락을 설정한다.

구문

virtual HRESULT SetSyncSource(
IReferenceClock *pIrc
    );

파라미터

pIrc
IReferenceClock 인터페이스에의 포인터.

반환값

디폴트의 이행에서는 S_OK 를 돌려준다.

CCmdQueue::SetTimeAdvise

CCmdQueue 클래스

기준 클락을 사용해 바다거북 겨이삭띠를 설정한다.

구문

void SetTimeAdvise(void);

반환값

반환값 없음.

주의

이 멤버 함수는,IReferenceClock::AdviseTime 메소드를 호출해, 큐내에서 필요한 가장 빠른 시간의 통지를 설정한다. 지연 되는 프레젠테이션 시간 커멘드는 항상 체크된다. 필터 그래프가 실행 모드인 경우, 스트림 타임을 사용하는 지연 커멘드도 체크된다.


CCritSec 클래스

CCritSec 클래스의 계층

thread의 락을 제공한다.

선언 : Wxutil.h

이 클래스는 크리티컬 섹션의 래퍼이다. Lock 및 Unlock 메소드를 호출하는 것에 의해, thread를 락 및 락 해제할 수가 있다. 다만, 이 클래스와 CAutoLock 클래스를 조합해 사용하는 (분)편이 안전하다. CAutoLock 클래스가 스코프의 범위외인 경우는, 자동적으로 CCritSec 오브젝트의 락을 해제한다. 게다가 효율적인 인라인 코드에 컴파일 한다.

Puvlic 멤버 변수
m_currentOwner | 소유하는 thread의 thread 식별자.
m_lockCount | 이 오브젝트에 대해 미처리의 락의 수.
m_fTrace | 이 락을 트레이스 할지 어떨지를 지정하는 불형의 값.
Public 메소드
CCritSec | constructor 메소드.
~CCritSec | 소멸자 메소드.
Lock | 크리티컬 섹션 오브젝트를 잠근다.
Unlock | 크리티컬 섹션 오브젝트의 락을 해제한다.

CCritSec.m_currentOwner

CCritSec 클래스

소유하는 thread의 thread 식별자.

구문

DWORD m_currentOwner;

주의

이 멤버 변수는, base class의 디버그 버젼에서만 정의된다. CCritSec debug 함수는 이 멤버를 사용한다.

CCritSec.m_lockCount

CCritSec 클래스

이 오브젝트에 대해 미처리의 락의 수.

구문

DWORD m_lockCount;

주의

이 멤버 변수는, base class의 디버그 버젼에서만 정의된다. CCritSec debug 함수는 이 멤버를 사용한다.

CCritSec.m_fTrace

CCritSec 클래스

이 락을 트레이스 할지 어떨지를 지정하는 불형의 값.

구문

BOOL m_fTrace;

주의

이 멤버 변수는, base class의 디버그 버젼에서만 정의된다. 이 변수가 TRUE 의 경우, 락 상태의 트레이스가 디버그 로그에 기입해진다. 크리티컬 섹션의 디버그 로그가 액티브하지 않으면 안 된다. 상세한 것에 대하여는, 「DbgLockTrace 」를 참조할것.

CCritSec::CCritSec

CCritSec 클래스

constructor　 　 메소드.

구문

CCritSec(void);

주의

이 메소드는, Microsoft® Win32® InitializeCriticalSection 함수를 호출해, 크리티컬 섹션을 초기화한다.

CCritSec::~CCritSec

CCritSec 클래스

소멸자 메소드.

구문

~CCritSec(void);

주의

이 메소드는, Microsoft® Win32® DeleteCriticalSection 함수를 호출해, 크리티컬 섹션을 삭제한다.

CCritSec::Lock

CCritSec 클래스

크리티컬 섹션 오브젝트를 잠근다.

구문

void Lock(void);

반환값

반환값 없음.

주의

이 메소드는, Microsoft® Win32® EnterCriticalSection 메소드를 호출한다.

크리티컬 섹션의 락을 해제하는데는,CCritSec::Unlock 멤버 함수를 호출한다. 같은 thread에 대해,Lock 메소드를 복수 호출할 수가 있다. 같은 회수만 Unlock 호출할 필요가 있다.

오브젝트가 이미 다른 thread에 의해 락 되고 있는 경우,CCritSec::Lock 메소드는, 그 오브젝트가 해방될 때까지, 또는 가능성이 있는 데드 록 예외가 발생할 때까지 블록 한다.

CCritSec::Unlock

CCritSec 클래스

크리티컬 섹션 오브젝트의 락을 해제한다.

구문

void Unlock(void);

반환값

반환값 없음.

주의

이 메소드는, Microsoft® Win32® LeaveCriticalSection 메소드를 호출한다.

Lock 메소드의 각 호출에 대해, 이 메소드를 1 회 호출한다.


CCrossbar 클래스

CCrossbar 는, 어플리케이션으로 사용해, 아날로그 TV 튜너 카드등의 디바이스로 아날로그 비디오 크로스바 필터를 제어할 수 있는 헬퍼 클래스이다. 보통, 이러한 카드는 복수의 입력 (콤퍼짓(composite) 비디오, S 비디오, TV 오디오용등)을 가진다. 크로스바 필터는, 특정의 입력에 보내진 신호가 하드웨어로 루팅 되기 위한, 가능한 모든 방법을 나타낸다. 디바이스에는, 연속해 접속된 복수의 크로스바를 이행 하는 것도 있으면, 크로스바를 가지지 않는 것도 있다.

CCrossbar 는, 임의의 복잡한 크로스바 필터의 그래프를 지원 하고 있다. 이러한 필터를 계층-화할 수가 있어 무효인 입력 및 출력을 포함할 수가 있다. CCrossbar 는 가능한 모든 입력을 열거해, 기록 및 표시하기 위한 단일의 입력을 선택할 수 있다.

시작입력 핀을 지정 하면 (보통, 캡춰 필터에의 아날로그 비디오 입력), 이 클래스는 모든 가변 입력을 검색해 재귀적으로 업 스트림을 트레이스 한다. 입력이 비디오 핀이며, 접속되어 있지 않은지,IAMCrossbar 인터페이스를 지원 하고 있지 않는 필터에 접속되고 있는 경우, 가변이다고 보여진다. 이 클래스의 사용에 대해서는, DirectX® 8 SDK 의 AMCap 샘플 어플리케이션으로 데모가 나타나고 있다.

멤버 함수

CCrossbar | CCrossbar 오브젝트를 생성 한다.
GetInputCount | 선택할 수 있는 일의의 비디오 입력의 수를 취득한다.
GetInputIndex | 현재 선택되고 있는 입력을 취득한다.
GetInputName | 사람이 읽어 이해할 수 있는 각 입력의 타입을 나타내는 캐릭터 라인을 취득한다.
GetInputType | 컴퓨터로 인식되는 각 입력의 물리적인 타입을 취득한다.
SetInputIndex | 특정의 입력을 선택한다.

CCrossbar::CCrossbar

CCrossbar 클래스

CCrossbar 오브젝트를 생성 한다.

구문

CCrossbar(
IPin *pPin);

파라미터

pPin
시작 입력 핀에의 포인터.

반환값

반환값 없음.

CCrossbar::GetInputCount

CCrossbar 클래스

선택할 수 있는 일의의 비디오 입력의 수를 취득한다.

구문

HRESULT GetInputCount(
LONG *pCount);

파라미터

pCount
비디오 입력의 수에의 포인터.

반환값

S_OK 를 돌려준다.

CCrossbar::GetInputIndex

CCrossbar 클래스

현재 선택되고 있는 입력을 취득한다.

구문

HRESULT GetInputIndex(
LONG *Index);

파라미터

Index
현재의 루팅 인덱스에의 포인터.

반환값

S_OK 를 돌려준다.

CCrossbar::GetInputName

CCrossbar 클래스

사람이 읽어 이해할 수 있는 각 입력의 타입을 나타내는 캐릭터 라인을 취득한다.

구문

HRESULT GetInputName(
LONG Index,
TCHAR *pName,
LONG NameSize);

파라미터

Index
현재의 루팅 인덱스.
pName
텍스트 버젼의 현재의 루팅 입력을 수신하는 버퍼에의 포인터. 메소드를 호출하기 전은, NULL 로 하는 것은 할 수 없다. NULL 로 하면(자), 처리는 실패한다. 예를 들어, 현재의 루팅 입력의 타입이 PhysConn_Video_Tuner 인 경우, 이 함수는 이 파라미터에 "Video Tuner" 라고 하는 캐릭터 라인을 돌려준다. 상세한 것에 대하여는, 「주의」를 참조할것.
NameSize
텍스트 버젼의 현재의 루팅 입력을 수신하는 버퍼의 사이즈. pName 로 나타나는 버퍼는, 마지막 NULL 문자를 포함할 수가 있는 사이즈가 아니면 안된다.

반환값

버퍼가 충분한 크기로, 캐릭터 라인명을 카피할 수 있는 경우, 이 메소드는 S_OK 를 돌려준다. 그 이외의 경우는, E_FAIL 를 돌려준다.

주의

다음 표에, 현재의 루팅 타입에 응해,pName 파라미터가 돌려주는 값을 나타낸다.

물리적인 타입 | pName
PhysConn_Video_Tuner | Video Tuner
PhysConn_Video_Composite | Video Composite
PhysConn_Video_SVideo | Video SVideo
PhysConn_Video_RGB | Video RGB
PhysConn_Video_YRYBY | Video YRYBY
PhysConn_Video_SerialDigital | Video SerialDigital
PhysConn_Video_ParallelDigital | Video ParallelDigital
PhysConn_Video_SCSI | Video SCSI
PhysConn_Video_AUX | Video AUX
PhysConn_Video_1394 | Video 1394
PhysConn_Video_USB | Video USB
PhysConn_Video_VideoDecoder | Video Decoder
PhysConn_Video_VideoEncoder | Video Encoder
PhysConn_Audio_Tuner | Audio Tuner
PhysConn_Audio_Line | Audio Line
PhysConn_Audio_Mic | Audio Mic
PhysConn_Audio_AESDigital | Audio AESDigital
PhysConn_Audio_SPDIFDigital | Audio SPDIFDigital
PhysConn_Audio_SCSI | Audio SCSI
PhysConn_Audio_AUX | Audio AUX
PhysConn_Audio_1394 | Audio 1394
PhysConn_Audio_USB | Audio USB
PhysConn_Audio_AudioDecoder | Audio Decoder

CCrossbar::GetInputType

CCrossbar 클래스

컴퓨터로 인식되는 각 입력의 물리적인 타입을 취득한다.

구문

HRESULT GetInputType(
LONG Index,
LONG *PhysicalType);

파라미터

Index
현재의 루팅 인덱스.
PhysicalType
핀 (비디오)의 물리적인 이름에의 포인터. PhysicalConnectorType 열거 데이터형의 멤버를 돌려준다.

반환값

Index 파라미터가 범위외의 경우는 E_FAIL 를 돌려준다. 그 이외의 경우는 S_OK 를 돌려준다.

CCrossbar::SetInputIndex

CCrossbar 클래스

특정의 입력을 선택한다.

구문

HRESULT SetInputIndex(
LONG Index);

파라미터

Index
설정되는 루팅 인덱스.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, E_FAIL 를 돌려준다.


CDeferredCommand 클래스

CDeferredCommand 클래스의 계층

지연 커멘드는,IQueueCommand 인터페이스에서의 메소드의 호출에 의해 큐에 넣어져 필터 그래프 매니저 및 일부의 필터에 의해 공개된다. 이러한 메소드의 호출이 성공하면(자), 큐에 넣어진 커멘드를 나타내는 IDeferredCommand 인터페이스가 돌려주어진다.

CDeferredCommand 오브젝트는 단일의 지연 커멘드를 나타내,IDeferredCommand 인터페이스 및 타임 체크와 실제의 실행을 가능하게 하는 그 외의 메소드를 공개한다. CDeferredCommand 오브젝트에는, 넣을 수 있는 큐가 되는 CCmdQueue 오브젝트에의 참조가 포함된다.

참조 카운트에 의해,CDeferredCommand 클래스의 유효기간이 제어된다. CDeferredCommand::Invoke 멤버 함수를 호출하면, 호출원의 어플리케이션은 참조가 카운트 된 인터페이스 포인터를 취득해,CCmdQueue 오브젝트도 지연 커멘드의 참조 카운트를 보관 유지한다. IDeferredCommand::Cancel 멤버 함수를 호출하면, 지연 커멘드는 커멘드 큐로부터 삭제되어 참조 카운트는 1 줄여진다. 커멘드를 큐로부터 삭제 하면, 큐에 되돌릴 수 없다.

프로텍트 데이터 멤버

m_bStream | 메소드를 호출하기 위해서(때문에) 건네받는스트림 타임 또는프레젠테이션 시간의 플래그.
m_Dispatch | ITypeInfo 인터페이스에 액세스 한다.
m_dispidMethod | 실행하는 인터페이스 위에의 메소드.
m_DispParams | DISPPARAMS 파라미터 리스트를 포함한 CDispParams 오브젝트.
m_hrResult | 돌려주어지는 HRESULT 값을 저장 한다.
m_iid | 인터페이스의 글로벌 유니크 식별자 (GUID ).
m_pQueue | IQueueCommand 인터페이스를 공개하는 CCmdQueue 오브젝트에의 포인터.
m_pUnk | 커멘드가 실행되는 인터페이스에의 IUnknown 포인터.
m_pvarResult | 불려 간 메소드로부터의 결과의 정보.
m_time | 커멘드가 실행되는 시간.
m_wFlags | 호출의 문맥을 지정하는 플래그.

멤버 함수

CDeferredCommand | CDeferredCommand 오브젝트를 생성 한다.
GetFlags | 이 지연 커멘드에 관련지을 수 있었던 문맥 플래그를 취득한다.
GetIID | 메소드가 실행되는 인터페이스의 인터페이스 식별자 (IID)를 취득한다.
GetMethod | 실행되는 메소드의 디스팟치 식별자를 취득한다.
GetParams | 메소드에 대한 DISPPARAMS 인수 리스트를 취득한다.
GetResult | 존재하는 경우는, 결과의 인수 리스트를 취득한다.
GetTime | 메소드가 실행되는 시간을 취득한다.
Invoke | 오브젝트에 의해 공개되는 메소드 및 프로퍼티에의 액세스를 제공한다.
IsStreamTime | 커멘드를 스트림 타임 또는 프레젠테이션 시간의 어디에서 실행하는지를 지정한다.

이행 되는 IDeferredCommand 메소드

Cancel | 이전에 큐에 넣어진 CDeferredCommand::Invoke 요구를 취소한다.
Confidence | 현재는 이행되어 있지 않다.
Postpone | 이전에 큐에 넣어진 커멘드의 새로운 프레젠테이션 시간을 지정한다.
GetHResult | 호출한 메소드의 HRESULT 값을 취득한다.

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingQueryInterface 지정된 참조 카운트의 인터페이스를 취득한다.

CDeferredCommand::Cancel

CDeferredCommand 클래스

이전에 큐에 넣어진 CDeferredCommand::Invoke 요구를 취소한다.

구문

HRESULT Cancel(void);

반환값

m_pQueue 가 NULL 의 경우는, VFW_E_ALREADY_CANCELLED 를 돌려준다. 호출이 에러를 생성하는 경우는,CCmdQueue::Remove 로부터의 HRESULT 를 돌려준다. 성공했을 경우는, S_OK 를 돌려준다.

주의

이 멤버 함수는,IDeferredCommand::Cancel 메소드를 이행 한다.

CDeferredCommand::CDeferredCommand

CDeferredCommand 클래스

CDeferredCommand 오브젝트를 생성 한다.

구문

CDeferredCommand(
CCmdQueue *pQ,
LPUNKNOWN pUnk,
HRESULT *phr,
LPUNKNOWN pUnkExecutor,
REFTIME time,
GUID *iid,
long dispidMethod,
short wFlags,
long cArgs,
VARIANT *pDispParams,
VARIANT *pvarResult,
short *puArgErr,
BOOL bStream
    );

파라미터

pQ
IQueueCommand 인터페이스를 공개하는 오브젝트에의 포인터.
pUnk
집성을 위한 외부 IUnknown 인터페이스에의 포인터.
phr
돌려주어진 HRESULT 값에의 포인터.
pUnkExecutor
이 커멘드를 실행하는 오브젝트에의 포인터.
time
커멘드가 실행되는 시간.
iid
메소드를 포함한 인터페이스의 글로벌 유니크 식별자 (GUID )에의 포인터.
dispidMethod
호출하는 인터페이스 위에의 메소드.
wFlags
호출의 문맥.
cArgs
건네받는 인수의 수.
pDispParams
인수 변형형의 리스트에의 포인터.
pvarResult
돌려주어진 변형형 리스트에의 포인터.
puArgErr
에러가 발생한 pDispParams 파라미터 리스트내의 마지막 인수에의 포인터.
bStream
지연 커멘드의 시간이 스트림 타임 (TRUE)인지, 프레젠테이션 타임 (FALSE)인지를 나타내는 값.

반환값

반환값 없음.

CDeferredCommand::Confidence

CDeferredCommand 클래스

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT Confidence(
LONG *pConfidence
    );

파라미터

pConfidence
콘피덴스레벨에의 포인터.

반환값

E_NOTIMPL 를 돌려준다.

주의

이 메소드의 이행에 대해서는, 「IDeferredCommand::Confidence 」를 참조할것.

CDeferredCommand::GetFlags

CDeferredCommand 클래스

이 지연 커멘드에 관련지을 수 있었던 문맥 플래그를 취득한다.

구문

short GetFlags(void);

반환값

취득되는 값은 다음의 몇개의 값이 된다.
DISPATCH_METHOD | 멤버를 메소드로서 실행한다. 프로퍼티가 같은 이름인 경우는, 이것과 DISPATCH_PROPERTYGET 플래그의 양쪽 모두를 설정할 수 있다.
DISPATCH_PROPERTYGET | 멤버는 프로퍼티 또는 데이터 멤버로서 취득되고 있다.
DISPATCH_PROPERTYPUT | 멤버는 프로퍼티 또는 데이터 멤버로서 변경되고 있다.
DISPATCH_PROPERTYPUTREF | 멤버는, 값의 할당은 아니고, 참조의 할당에 의해 변경되고 있다. 이 플래그는, 프로퍼티가 오브젝트에의 참조를 받아들이는 경우에게만 유효하다.

CDeferredCommand::GetHResult

CDeferredCommand 클래스

호출한 커멘드로부터의 HRESULT 값을 취득한다.

구문

HRESULT GetHResult(
HRESULT *phrResult
    );

파라미터

phrResult
HRESULT 값에의 포인터.

반환값

m_pQueue 가 NULL 의 경우는, E_ABORT 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

주의

이 멤버 함수는,IDeferredCommand::GetHResult 메소드를 이행 한다.

CDeferredCommand::GetIID

CDeferredCommand 클래스

메소드가 실행되는 인터페이스의 인터페이스 식별자 (IID)를 취득한다.

구문

REFIID GetIID(void);

반환값

메소드가 실행되는 인터페이스의 IID 를 취득한다.

CDeferredCommand::GetMethod

CDeferredCommand 클래스

실행되는 메소드의 디스팟치 식별자 (DISPID)를 취득한다.

구문

long GetMethod(void);

반환값

실행하는 메소드의 DISPID 를 돌려준다.

CDeferredCommand::GetParams

CDeferredCommand 클래스

메소드에 대한 DISPPARAMS 인수 리스트를 취득한다.

구문

DISPPARAMS* GetParams(void);

반환값

DISPPARAMS 인수 리스트를 돌려준다.

CDeferredCommand::GetResult

CDeferredCommand 클래스

존재하는 경우는, 결과의 인수 리스트를 취득한다.

구문

VARIANT* GetResult(void);

반환값

존재하는 경우는, 메소드의 인수 리스트를 포함한 변형을 돌려준다.

CDeferredCommand::GetTime

CDeferredCommand 클래스

메소드가 실행되는 시간을 취득한다.

구문

CRefTime GetTime(void);

반환값

기준 타임을 포함한 CRefTime 오브젝트를 돌려준다.

CDeferredCommand::Invoke

CDeferredCommand 클래스

오브젝트에 의해 공개되는 메소드 및 프로퍼티에의 액세스를 제공한다.

구문

HRESULT Invoke(void);

반환값

m_pQueue 가 NULL 의 경우는, VFW_E_ALREADY_CANCELLED 를 돌려준다. 그 이외의 경우는,IDispatch::GetTypeInfo 또는 IUnknown::QueryInterface 의 호출의 결과의 HRESULT 를 돌려준다.

CDeferredCommand::IsStreamTime

CDeferredCommand 클래스

커멘드를 스트림 타임 또는 프레젠테이션 시간의 어디에서 실행하는지를 지정한다.

구문

BOOL IsStreamTime(void);

반환값

스트림 타임으로 설정되어 있는 경우는 TRUE 를 돌려준다. 그 이외의 경우는 FALSE 를 돌려준다.

CDeferredCommand::NonDelegatingQueryInterface

CDeferredCommand 클래스

지정된 참조 카운트의 인터페이스를 취득한다.

구문

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

디폴트에서는,IDeferredCommand 및 IUnknown 인터페이스에의 포인터를 돌려준다. 이 메소드를 오버라이드(override) 해, 상속 클래스로 이행 된 추가의 인터페이스를 공개한다.

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 한다.

CDeferredCommand::Postpone

CDeferredCommand 클래스

이전에 큐에 넣어진 커멘드의 새로운 프레젠테이션 시간을 지정한다.

구문

HRESULT Postpone(
REFTIME newtime
    );

파라미터

newtime
새로운 프레젠테이션 시간.

반환값

newtime 가 이미 지나고 있는 경우는, VFW_E_TIME_ALREADY_PASSED 를 돌려준다. 그 이외의 경우는,CCmdQueue::Remove (리스트로부터 삭제하는 경우) 또는 CCmdQueue::Insert (변경한 시간에 다시 삽입하는 경우)의 호출의 결과의 HRESULT 를 돌려준다.

주의

이 멤버 함수는,IDeferredCommand::Postpone 메소드를 이행 한다.


CDispParams 클래스

CDispParams 클래스의 계층

CDispParams 클래스는, C++ 의 base class로서 Automation 로 사용되는 DISPPARAMS 구조체를 이행 한다. IDispatch::Invoke 메소드는, OLE DISPPARAMS 구조체를 사용해, 메소드 또는 프로퍼티에게 건네지는 인수를 저장 한다.

DISPPARAMS 구조체는 다음과 같이 정의된다.

typedef struct FARSTRUCT tagDISPPARAMS{
VARIANTARG FAR* rgvarg;               // 인수의 배열
DISPID FAR* rgdispidNamedArgs;     // 이름을 붙인 인수의 디스팟치 ID
unsigned int cArgs;                // 인수의 수
unsigned int cNamedArgs;           // 이름을 붙인 인수의 수
} DISPPARAMS;

멤버 함수

CDispParams CDispParams 오브젝트를 생성 한다.

CDispParams::CDispParams

CDispParams 클래스

CDispParams 오브젝트를 생성 한다.

구문

CDispParams(

  UINT nArgs,

  VARIANT *pArgs

  );

파라미터

nArgs
메소드 또는 프로퍼티에게 건네지는 인수의 수.
pArgs
인수의 리스트에의 포인터. 리스트내에서, 각 인수는 변형형으로 저장 된다.

반환값

반환값 없음.


CDrawImage 클래스

CDrawImage 클래스는, 소유하는 CBaseWindow 오브젝트의 워커 클래스이다. 이 클래스는, 그 클래스로부터의 실제의 드로잉(Drawing) 조작을 처리한다. 이 클래스를 사용하려면 , allocater가 합의했을 때에 CDrawImage::NotifyAllocator 를 호출해, 합의되었을 때에 CMediaType 오브젝트에의 포인터 (포인터는 카피를 생성 하는 것이 아니라, 이 클래스에서 관리되므로, 스택 베이스여서는 안 된다)를 지정해 CDrawImage::NotifyMediaType 를 호출할 필요가 있다.

팔레트가 변경되었을 경우는,CDrawImage::IncrementPaletteVersion 을 호출해, 렌더링의 전에 CDrawImage::SetDrawContext 를 호출해, 이 클래스가 소유하는 CBaseWindow 오브젝트로부터 디바이스 콘텍스트 핸들 (HDC)을 취득할 수 있도록(듯이) 한다.

Protected 데이터 멤버

m_bStretch | 이미지를 신축하는 플래그.
m_bUsingImageAllocator | 샘플이 DIBSECTION 구조체를 공유할지 어떨지를 판단하는 플래그.
m_EndSample | 현재의 샘플의 종료 타임.
m_hdc | 메인 윈도우의 디바이스 콘텍스트 (DC).
m_MemoryDC | 오프 스크린 드로잉(Drawing) DC.
m_pBaseWindow | 소유하는 비디오 윈도우 오브젝트.
m_PaletteVersion | 현재의 팔레트의 버젼 토큰.
m_perfidRenderNow | 드로잉(Drawing)로부터 돌아간 순간 (퍼포먼스 로그용).
m_perfidRenderNow | 이미지의 렌더링에 걸린 시간 (퍼포먼스 로그용).
m_pMediaType | 현재의 미디어 타입 포맷에의 포인터.
m_SourceRect | 전송원이미지 직사각형.
m_StartSample | 현재의 샘플의 시작 타임.
m_TargetRect | 전송처 직사각형.

멤버 함수

CDrawImage | CDrawImage 오브젝트를 생성 한다.
DisplaySampleTimes | 이미지의 선두의 샘플의타임 스탬프를 표시한다.
DrawImage | 윈도우에의 이미지의 드로잉(Drawing)를 처리한다.
FastRender | BitBlt 및 StretchBlt 를 사용해 이미지를 드로잉(Drawing) 한다.
GetPaletteVersion | 현재 인스톨 되고 있는 팔레트의 버젼을 취득한다.
GetSourceRect | 현재의 전송원직사각형을 취득한다.
GetTargetRect | 현재의 전송처 직사각형을 취득한다.
IncrementPaletteVersion | 현재의 팔레트의 버젼을 인크리먼트(increment) 한다.
NotifyAllocator | 사용하는 allocater를 드로잉(Drawing) 오브젝트에 통지한다.
NotifyEndDraw | 이미지 렌더링의 종료를 지정한다.
NotifyMediaType | 접속시에 확립된 미디어 타입을 건네준다.
NotifyStartDraw | 이미지 렌더링의 시작을 지정한다.
ResetPaletteVersion | 현재의 팔레트의 버젼을 리셋 한다.
ScaleSourceRect | 지정된 전송원직사각형의 스케일링 된 버젼을 취득한다.
SetDrawContext | 드로잉(Drawing)에 사용하는 윈도우 및 오프 스크린 디바이스 콘텍스트를 설정한다.
SetSourceRect | 비디오의 전송원직사각형을 설정한다.
SetStretchMode | 신축할 필요가 있을지 어떨지를 판단한다.
SetTargetRect | 윈도우의 전송처 직사각형을 설정한다.
SlowRender | Microsoft® Win32® SetDIBitsToDevice 및 StretchDIBits 함수를 사용해 이미지를 드로잉(Drawing) 한다.
UpdateColourTable | DIBSECTION 구조체에 보관 유지되고 있는 팔레트를 갱신한다.
UsingImageAllocator | 드로잉(Drawing) 되는 샘플의 타입을 취득한다.

CDrawImage::CDrawImage

CDrawImage 클래스

CDrawImage 오브젝트를 생성 한다.

구문

CDrawImage(
CBaseWindow *pBaseWindow
);

파라미터

pBaseWindow
드로잉(Drawing)를 하는 윈도우에의 포인터.

반환값

반환값 없음.

주의

이 클래스는, GDI 에 의한 이미지의 드로잉(Drawing)를 처리한다. 이 클래스는,CImageAllocator 및 CBaseWindow 클래스와 밀접하게 제휴해 기능한다. 드로잉(Drawing) 코드는, 그것이 건네받는 버퍼가 Microsoft® Win32® CreateDIBSection 함수에 의해 생성 되고 있는 경우, 고속의 드로잉(Drawing)를 이행 할 수 있으므로, 이 클래스는 CImageAllocator 클래스를 인식하고 있을 필요가 있다. 이미지 allocater는 이 타입의 샘플을 생성 한다. CDrawImage::NotifyAllocator 멤버 함수를 사용해,CImageAllocator 오브젝트 (또는 상속 클래스)에 의해 버퍼를 할당할 수 있고 있는지 어떤지가, 이 클래스에 통지된다.

드로잉(Drawing)에 사용하는 버퍼가 호환성이 있는 allocater에 의해 할당할 수 있지 않은 경우, 버퍼는 Win32 SetDIBitsToDevice 패밀리의 API 를 사용해 드로잉(Drawing) 한다. CBaseWindow 클래스는, 이미지가 드로잉(Drawing) 되는 윈도우 핸들을 취득한다. 드로잉(Drawing) 코드가 사용하는 디바이스 콘텍스트는,CDrawImage::SetDrawContext 멤버 함수를 사용해 건네받는다.

CImageAllocator ,CImageSample , 및 CDrawImage 클래스는, 모두 밀접하게 관련하고 있다. 이미지 allocater가 사용하는 버퍼는, Win32 CreateDIBSection 함수를 사용해 생성 된다. 다음에, allocater는 CImageSample 클래스에 근거해 독자적인 샘플을 생성 한다. 이미지 샘플은, 버퍼 포인터와 그 길이를 사용해 초기화된다. 샘플은,CreateDIBSection 함수로부터 취득된 다양한 정보를 보관 유지하는 구조체 (DIBDATA 구조체)에도 건네받는다.

이러한 샘플을 드로잉(Drawing) 오브젝트에 건네줄 수가 있다. 드로잉(Drawing) 오브젝트는, 샘플의 프라이빗 포맷, 및 샘플로부터 DIBDATA 구조체를 취득하는 방법을 인식하고 있다. 드로잉(Drawing) 오브젝트는, 이 정보를 취득한 후, 샘플에 포함되는 이미지를 드로잉(Drawing) 할 경우에,DIBDATA 구조체에 저장 된 비트 맵 핸들을 GDI 에 건네줄 수가 있다. 드로잉(Drawing)시에 버퍼 포인터 (샘플이 CImageSample 가 아닌 경우에 사용된다)는 아니고, 샘플로부터 취득한 비트 맵 핸들을 사용하는 것에 의해, 퍼포먼스가 약간 향상한다.

CDrawImage::DisplaySampleTimes

CDrawImage 클래스

이미지의 선두의 샘플의 타임 스탬프를 표시한다.

구문

void DisplaySampleTimes(
IMediaSample *pSample
);

파라미터

pSample
타임 스탬프를 포함한 샘플에의 포인터.

반환값

반환값 없음.

주의

디버그 빌드에서는, 오브젝트가 드로잉(Drawing) 하고 있는 이미지의 타임 스탬프를 확인하는 것이 중요하게 되는 경우가 있다. 이 멤버 함수는, 샘플이 보관 유지하고 있는 이미지의 데이터 포인터와 함께, 그 타임 스탬프를 취득한다. 다음에, 오프 스크린 디바이스 콘텍스트를 사용해, 이미지 위로부터 약 80 퍼센트의 위치에, 중앙에 가지런히 해 시간을 드로잉(Drawing) 한다.

이것은 프로텍트 멤버 함수이다.

CDrawImage::DrawImage

CDrawImage 클래스

이미지를 드로잉(Drawing) 한다.

구문

BOOL DrawImage(
IMediaSample *pMediaSample
);

파라미터

pMediaSample
드로잉(Drawing) 하는 샘플에의 포인터.

반환값

반환값 없음.

주의

샘플이 CImageAllocator 오브젝트 (또는 상속 클래스)로 할당할 수 있고 있는 경우, 이 샘플이 포함한 이미지는 Microsoft Win32 BitBlt 또는 StretchBlt 함수를 사용해 드로잉(Drawing) 된다. 그 이외의 경우는,SetDIBitsToDevice 또는 StretchDIBits 를 사용해 드로잉(Drawing) 된다. 클라이언트는, 이 멤버 함수를 호출하기 전에 CDrawImage::NotifyAllocator 를 호출해, 이미지 버퍼를 어떻게 할당할 수 있고 있을까를 CDrawImage 오브젝트에 통지해야 한다. 전송원 또는 전송처가 (CDrawImage::SetSourceRect 및 CDrawImage::SetTargetRect 멤버 함수에 의해) 변경될 때마다, 이 오브젝트에 통지된다. 오브젝트는 이 정보를 사용해, 드로잉(Drawing)시에 이미지를 신축할 필요가 있을지 어떨지를 판단한다.

CDrawImage::FastRender

CDrawImage 클래스

Microsoft Win32 BitBlt 및 StretchBlt 함수를 사용해, 샘플 이미지를 드로잉(Drawing) 한다.

구문

void FastRender(
IMediaSample *pMediaSample
);

파라미터

pMediaSample
드로잉(Drawing) 하는 샘플에의 포인터.

반환값

반환값 없음.

주의

이 프로텍트 멤버 함수는, 이미지 버퍼를 포함한 샘플을 지정해 CDrawImage 에 의해 불려 간다. 이 이미지 버퍼는, Win32 CreateDIBSection 함수 및 CImageAllocator 오브젝트 (또는 상속 클래스)를 사용해 할당할 수 있지 않으면 안 된다. 이 메카니즘을 사용해 생성 된 이미지를 드로잉(Drawing) 하는 것에 의해, 약간 퍼포먼스가 향상한다.

CDrawImage::GetPaletteVersion

CDrawImage 클래스

현재의 팔레트의 버젼을 취득한다.

구문

LONG GetPaletteVersion(void);

반환값

팔레트의 버젼을 돌려준다.

주의

이 멤버 함수는,CImageAllocator (또는 상속 클래스의) 오브젝트를 통해 할당할 수 있었던 샘플을 사용했을 경우에게만 적용 가능하다. 팔레트의 처리의 상세한 것에 대하여는, 「CDrawImage::UpdateColourTable 멤버 함수」를 참조할것.

CDrawImage::GetSourceRect

CDrawImage 클래스

드로잉(Drawing) 오브젝트가 사용하는 현재의 전송원직사각형을 취득한다.

구문

void GetSourceRect(
RECT *pSourceRect
);

파라미터

pSourceRect
전송원직사각형에의 포인터.

반환값

반환값 없음.

CDrawImage::GetTargetRect

CDrawImage 클래스

드로잉(Drawing) 오브젝트가 사용하는 현재의 전송처 직사각형을 취득한다.

구문

void GetTargetRect(
RECT *pTargetRect
);

파라미터

pTargetRect
전송처 직사각형에의 포인터.

반환값

반환값 없음.

CDrawImage::IncrementPaletteVersion

CDrawImage 클래스

현재의 팔레트의 버젼을 인크리먼트(increment) 한다.

구문

void IncrementPaletteVersion(void);

반환값

반환값 없음.

주의

이 멤버 함수는,CImageAllocator (또는 상속 클래스의) 오브젝트를 통해 할당할 수 있었던 샘플을 사용했을 경우에게만 적용 가능하다. 팔레트의 처리의 상세한 것에 대하여는, 「CDrawImage::UpdateColourTable 멤버 함수」를 참조할것.

CDrawImage::NotifyAllocator

CDrawImage 클래스

출력 핀이 실제로 사용하는 allocater를 드로잉(Drawing) 오브젝트에 통지한다.

구문

void NotifyAllocator(
BOOL bUsingImageAllocator
);

파라미터

bUsingImageAllocator
CImageAllocator 오브젝트 allocater를 사용할지 어떨지를 지정하는 플래그. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

반환값 없음.

주의

이 멤버 함수는, 사용하는 allocater를 드로잉(Drawing) 오브젝트에 통지한다. 필터가 Microsoft® DirectShow® CImageAllocator base class에 근거하는 allocater를 사용하는 것에 합의하고 있는 경우는, TRUE 를 지정해 이 멤버 함수를 호출할 필요가 있다. 이러한 이미지 버퍼는,CreateDIBSection 를 사용해 생성 된다. 그 이외의 경우는, FALSE 를 지정해 이 멤버 함수를 호출할 필요가 있어, 이미지는 SetDIBitsToDevice 및 StretchDIBits 를 사용해 드로잉(Drawing) 된다.

CDrawImage::NotifyEndDraw

CDrawImage 클래스

이미지 렌더링의 종료를 지정한다.

구문

void NotifyEndDraw(void);

반환값

반환값 없음.

주의

이 멤버 함수는 퍼포먼스 측정을 위해서(때문에) 사용되어MSR_STOP 매크로를 호출한다.

CDrawImage::NotifyMediaType

CDrawImage 클래스

드로잉(Drawing) 오브젝트에 이미지 포맷을 제공한다.

구문

void NotifyMediaType(
CMediaType *pMediaType
);

파라미터

pMediaType
미디어 타입에의 포인터.

반환값

반환값 없음.

주의

드로잉(Drawing) 오브젝트는, 드로잉(Drawing) 하는 이미지의 포맷을 인식해야 한다. 대부분의 경우, 이것은 이미지가 8 비트 팔레트화 되고 있는 경우에 팔레트를 취득할 수 있도록(듯이) 하기 위한(해)이다. 드로잉(Drawing) 클래스를 사용하는 필터는, 보통, 접속을 완료한 후, 이것을 호출한다.

이 함수는, 퍼포먼스 위에의 이유로부터, 미디어 타입의 카피를 생성 하지 않고 , 포인터를 저장 하는 것만으로 있다. 따라서, 호출원래는 미디어 타입이 잘못해 파기되어 있지 않은 것을 확인할 필요가 있다.

CDrawImage::NotifyStartDraw

CDrawImage 클래스

이미지 렌더링의 시작을 지정한다.

구문

void NotifyStartDraw(void);

반환값

반환값 없음.

주의

이 멤버 함수는 퍼포먼스 측정을 위해서(때문에) 사용되어MSR_START 매크로를 호출한다.

CDrawImage::ResetPaletteVersion

CDrawImage 클래스

현재의 팔레트의 버젼을 리셋 한다.

구문

void ResetPaletteVersion(void);

반환값

반환값 없음.

주의

이 멤버 함수는,CImageAllocator (또는 상속 클래스의) 오브젝트를 통해 할당할 수 있었던 샘플을 사용했을 경우에게만 적용 가능하다. 팔레트의 처리의 상세한 것에 대하여는, 「CDrawImage::UpdateColourTable 멤버 함수」를 참조할것.

CDrawImage::ScaleSourceRect

CDrawImage 클래스

지정된 전송원직사각형의 스케일링 된 버젼을 취득한다.

구문

virtual RECT ScaleSourceRect(
const RECT *pSource
);

파라미터

pSource
스케일링되어 있지 않은 전송원직사각형에의 포인터.

반환값

스케일링 된 전송원직사각형을 돌려준다. 디폴트에서는, 스케일링되어 있지 않은 pSource 를 돌려준다.

주의

base class의 이행은, 전송원직사각형을 스케일링 하지 않는다. 상속 클래스는 이것을 오버라이드(override) 해, 필요에 따라서 스케일링을 이행 할 수 있다.

CDrawImage::SetDrawContext

CDrawImage 클래스

드로잉(Drawing)에 사용되는 디바이스 콘텍스트를 설정한다.

구문

void SetDrawContext(void);

반환값

반환값 없음.

주의

드로잉(Drawing) 오브젝트는, 항상, 이미지를 드로잉(Drawing) 하는 윈도우의 디바이스 콘텍스트를 필요로 한다. 또,DIBSECTION 버퍼를 사용하는 경우에 비트 맵을 선택하는 오프 스크린 디바이스 콘텍스트를 필요로 한다. DIBSECTION 버퍼 및 CreateDIBSection 의 상세한 것에 대하여는, Microsoft Platform SDK 의 문서를 참조할것. 이 멤버 함수는, 보통, 이 클래스를 사용하는 필터가 윈도우를 초기화한 후, 이 필터에 의해 불려 간다.

CDrawImage::SetSourceRect

CDrawImage 클래스

비디오의 전송원직사각형을 설정한다.

구문

void SetSourceRect(
RECT *pSourceRect
);

파라미터

pSourceRect
새로운 전송원직사각형에의 포인터.

반환값

반환값 없음.

주의

지정된 전송원직사각형이 사용 가능한 비디오의 경계를 넘지 않게 하기 위해서, 이 멤버 함수를 호출하기 전에, 전송원직사각형이 유효하게 되어 있을 필요가 있다.

CDrawImage::SetStretchMode

CDrawImage 클래스

비디오를 신축할지 어떨지를 판단한다.

구문

void SetStretchMode(void);

반환값

반환값 없음.

주의

오브젝트에 이미지의 드로잉(Drawing)를 지시하는 경우, 오브젝트는 비디오가 신축되고 있는지 어떤지를 인식할 필요가 있다. 이것은, 오브젝트가 호출하는 함수 (BitBlt 또는 StretchBlt 등)에 영향을 주기 때문이다. 각 프레임에 대해 이것을 계산하는 것이 아니라, 전송원직사각형 또는 전송처 직사각형이 갱신되었을 때에 1 회만 계산한다. 이 멤버 함수는, 이 계산을 실시하기 위해서(때문에),SetSourceRect 및 SetTargetRect 에 의해 불려 간다.

이것은 프로텍트 멤버 함수이다.

CDrawImage::SetTargetRect

CDrawImage 클래스

비디오의 전송처 직사각형을 설정한다.

구문

void SetTargetRect(
RECT *pTargetRect
);

파라미터

pTargetRect
새로운 전송처 직사각형에의 포인터.

반환값

반환값 없음.

주의

지정된 전송처가 하늘의 재생 영역을 정의하지 않게, 이 멤버 함수를 호출하기 전에 전송처 직사각형이 유효하게 되어 있을 필요가 있다.

CDrawImage::SlowRender

CDrawImage 클래스

SetDIBitsToDevice 및 StretchDIBits 를 사용해 이미지를 드로잉(Drawing) 한다.

구문

void SlowRender(
IMediaSample *pMediaSample
);

파라미터

pMediaSample
드로잉(Drawing) 하는 샘플에의 포인터.

반환값

반환값 없음.

주의

지정된 샘플은, 드로잉(Drawing) 하는 이미지를 포함하고 있어NotifyMediaType 를 사용해 드로잉(Drawing) 오브젝트에 대해서 지정된 포맷과 일치하고 있을 필요가 있다.

이것은 프로텍트 멤버 함수이다.

CDrawImage::UpdateColourTable

CDrawImage 클래스

샘플에 관련지을 수 있었던 팔레트를 갱신한다.

구문

void UpdateColourTable(
HDC hdc,
BITMAPINFOHEADER *pbmi
);

파라미터

hdc
샘플의 이미지를 포함한 디바이스 콘텍스트.
pbmi
새로운 팔레트를 저장 하는 BITMAPINFO 구조체에의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는,CImageAllocator (또는 상속 클래스의) 오브젝트를 통해 할당할 수 있었던 샘플을 사용했을 경우에게만 적용 가능하다. CImageAllocator 는, Microsoft Win32 CreateDIBSection 함수를 사용해 생성 된 샘플을 생성 한다. 팔레트화 된 버퍼가 CreateDIBSection 를 사용해 할당할 수 있고 있는 경우, 그 버퍼에 관련지을 수 있었던 팔레트가 건네받는다.

팔레트가 변경되었을 경우, 새로운 팔레트를 드로잉(Drawing) 하기 전에, 그 팔레트를 버퍼에 관련지을 필요가 있다. 이것은, Win32 SetDIBColorTable 함수, 및 내부적으로는 UpdateColourTable 멤버 함수에 의해 처리된다. 샘플내에 저장 된 팔레트의 버젼과 팔레트가 내부 로 유지하고 있는 팔레트의 버젼이 다르므로, 드로잉(Drawing) 코드로 팔레트의 갱신이 인식된다.

기본적으로, 샘플은, 생성시에 초기 팔레트 버젼을 취득한다. 팔레트가 필터등에 의해 변경되었을 경우, 팔레트는,IncrementPaletteVersion 멤버 함수를 사용해 팔레트의 버젼을 인크리먼트(increment) 하도록(듯이), 드로잉(Drawing) 오브젝트에 지시한다. 드로잉(Drawing) 오브젝트가 다음에 샘플을 드로잉(Drawing) 할 경우에는, 샘플의 팔레트의 버젼이 낡은 일을 인식해, 그 샘플에 대해 UpdateColourTable 를 호출한다.

드로잉(Drawing) 오브젝트는,NotifyAllocator 멤버 함수를 사용해, 샘플로 사용되는 버퍼의 타입을 인식한다. TRUE 를 지정해 불려 갔을 경우, 이 멤버 함수에게 건네지는 버퍼는,CImageAllocator (또는 상속 클래스의) 오브젝트에 의해 할당할 수 있다. FALSE 를 지정해 불려 갔을 경우, 버퍼는 표준의 시스템 메모리 (또는 같은 방법으로 GDI 로부터 액세스 할 수 있는 그 외의 메모리) 내에서 할당할 수 있다.

allocater가 데코밋트 되면(자), 보통, allocater가 보관 유지하고 있는 모든 샘플이 삭제된다. 그 후, allocater가 위탁되면(자), 샘플은 최초의 팔레트 버젼을 사용해 다시 생성 된다. 이 시점에서, allocater는 드로잉(Drawing) 오브젝트내의 팔레트의 버젼을 리셋 해, 동기 시킬 필요가 있다. allocater는,ResetPaletteVersion 멤버 함수를 호출하는 것에 의해, 이 처리를 실행할 수 있다.

이것은 프로텍트 멤버 함수이다.

CDrawImage::UsingImageAllocator

CDrawImage 클래스

드로잉(Drawing) 되는 샘플의 타입을 취득한다.

구문

BOOL UsingImageAllocator(void);

반환값

다음의 몇개의 값을 돌려준다.
TRUE | CreateDIBSection 를 사용해 할당할 수 있었다.
FALSE | CreateDIBSection 를 사용해 할당할 수 있지 않았다.

주의

이 멤버 함수는,CImageAllocator (또는 상속 클래스의) 오브젝트를 통해 할당할 수 있었던 샘플을 사용했을 경우에게만 적용 가능하다. 팔레트 처리와 이미지 allocater의 상세한 것에 대하여는, 「CDrawImage::UpdateColourTable 멤버 함수」를 참조할것.


CDynamicOutputPin 클래스

동적재접속과 포맷 변경을 지원 하는 출력 핀을 이행 한다.

선언 : Amfilter.h

이 클래스는 CBaseOutputPin 핀으로부터 파생해,IPinFlowControl 인터페이스를 이행 한다. 그것은 동적 그래프 생성 에 중요한 몇개의 조작을 지원 한다 :

  • 동적재접속 : 필터가 액티브 (포즈나 실행중)의 사이에, 핀이 끊어지거나 재접속하거나 할 수 있다.
  • 동적 필터 변경 : 필터가 액티브한 동안에 재접속없이, 핀이 새로운 미디어 타입을 처리할 수 있다.
  • 플로우 컨트롤 : 필터를 정지하지 않고 , 자기 자신의 필터 (또는 어플리케이션)가 데이터 플로우를 블록 할 수 있다.

이 핀은 3 개 상태가 가능한: 블록 되고 있는 (Blocked), 블록 해제되고 있는 (not Blocked), 대기 상태 (Pending). 대기 상태에서는, 핀이 블록 된 상태가 되기 전에, 다른 thread 조작이 완료하는 것을 기다리고 있다. 핀이 블록 되고 있는 동안, 필터는 데이터를 핀으로부터 출력할 수 없는, 혹은 핀의 접속을 변경할 수 없다.

소유하는 필터는, 복수의 thread간의 조정을 실시하는에 위해(때문에), 어느 룰에 따르지 않으면 안 된다. 필터 그래프의 thread의 상세한 것에 대하여는, 「thread와 크리티컬 섹션」을 참조할것. 최초로, 스트리밍 thread는, 다음의 메소드의 어느쪽이든을 호출하기 전에, 반드시StartUsingOutputPin 메소드를 호출하지 않으면 안 된다.

  • ChangeOutputFormat
  • ChangeMediaType
  • DynamicReconnect
  • CBaseOutputPin::Deliver
  • CBaseOutputPin::DeliverEndOfStream
  • CBaseOutputPin::DeliverNewSegment
  • IMemInputPin::Receive
  • IMemInputPin::ReceiveMultiple
  • IPin::EndOfStream
  • IPin::NewSegment

그 후로,StopUsingOutputPin 메소드를 호출하지 않으면 안 된다.

다음에, 어플리케이션 thread는 전술의 일람에 있는 어느 메소드도 호출해서는 안 된다. 또, 스트리밍 thread는, 핀을 블록 또는 블록 해제하는 클래스 메소드를 호출해서는 안 된다. 이러한 메소드에는,Block ,SynchronousBlockOutputPin ,AsynchronousBlockOutputPin , 및 UnblockOutputPin 가 있다.

이러한 룰은 스트리밍 thread가 핀을 사용중에, 어플리케이션 thread가 그 핀을 블록 할 수 없게하기 위해(때문에) (또는 역도)이다. 스트리밍 thread가 StartUsingOutputPin 를 호출한 후, 그 thread가 StopUsingOutputPin 를 호출할 때까지, 핀은 블록 되지 않는다. 반대로 핀이 블록 되면(자),StartUsingOutputPin 는 핀이 비블록이 될 때까지 기다린다.

StopUsingOutputPin 의 호출을 잊지 않기 위해(때문에),CAutoUsingOutputPin 클래스를 사용할 수 있다. 그것은 종료하기 전에 자동적으로 StopUsingOutputPin 를 호출한다.

(IBaseFilter::JoinFilterGraph 메소드내에서) 자신의 필터가 필터 그래프에 참가 혹은 퇴출 하면 와, 핀의 SetConfigInfo 메소드를 호출하지 않으면 안 된다.

Protected 멤버 변수
m_BlockStateLock | 블록 상태를 보호하는 크리티컬 섹션.
m_hUnblockOutputPinEvent | 핀이 블록되어 있지 않을 때에 통지제의 이벤트.
m_hNotifyCallerPinBlockedEvent | 핀의 블록에 성공했을 때, 혹은 유저가 대기 블록을 캔슬할 수 없을 때, 통지제의 이벤트.
m_BlockState | 블록 상태.
m_dwBlockCallerThreadID | 이 핀으로 마지막에 IPinFlowControl::Block 메소드를 호출한 thread의 ID.
m_dwNumOutstandingOutputPinUsers | 이 핀을 사용하고 있는 스트리밍 thread의 수.
m_hStopEvent | 필터가 정지한, 혹은 핀이 데이터를 플래시 했을 때, 통지제의 이벤트.
m_pGraphConfig | 동적재접속을 실행하는 IGraphConfig 인터페이스에의 포인터.
m_bPinUsesReadOnlyAllocator | 핀의 allocater로부터의 샘플이 읽어들여 전용인가 어떤가를 지정하는 플래그.
Protected 메소드
SynchronousBlockOutputPin | 핀을 블록 한다. 핀이 블록 될 때까지 돌아가지 않는다.
AsynchronousBlockOutputPin | 핀을 블록 한다. 핀이 블록 될 때까지 돌아가는 일이 있다.
UnblockOutputPin | 핀을 블록 해제한다.
BlockOutputPin | 핀을 블록 한다.
WaitEvent | 지정한 이벤트가 통지제가 될 때까지 기다린다.
Public 메소드
CDynamicOutputPin | constructor 메소드.
~CDynamicOutputPin | 소멸자 메소드.
SetConfigInfo | IGraphConfig 포인터와 정지 이벤트를 지정한다.
DeliverBeginFlush | 접속한 입력 핀에 플래시 처리를 요구한다.
DeliverEndFlush | 접속한 입력 핀에 플래시 처리의 종료를 요구한다.
Inactive | 핀에 필터가 정지하고 있는 것을 통지한다.
Active | 핀에 필터가 지금 액티브한 것을 통지한다.
CompleteConnect | 입력 핀에의 접속을 완료한다. 가상.
StartUsingOutputPin | 스트리밍 조작으로 핀의 액세스를 획득한다. 가상.
StopUsingOutputPin | 스트리밍 조작의 뒤핀에의 액세스를 해방한다. 가상.
StreamingThreadUsingOutputPin | thread가 핀으로 스트리밍 조작을 실시하고 있는지 어떤지를 확인한다. 가상.
ChangeOutputFormat | 접속하고 있는 미디어 타입을 동적으로 변경해, 새로운 세그먼트(segment) 정보를 출력한다.
ChangeMediaType | 접속하고 있는 미디어 타입을 동적으로 변경한다.
DynamicReconnect | 새로운 미디어 타입과 동적재접속을 실시한다.
IPin 메소드
Disconnect | 현재의 핀 접속을 해제한다.
IPinFlowControl 메소드
Block | 핀으로부터의 데이터의 플로우를 블록, 혹은 블록 해제한다.

CDynamicOutputPin.m_BlockStateLock

CDynamicOutputPin 클래스

블록 상태를 보호하는 크리티컬 섹션.

구문

CCritSec m_BlockStateLock;

주의

다음의 멤버 함수를 사용하기 전에 이 크리티컬 세션을 보관 유지하는 것 :

  • m_BlockState
  • m_dwBlockCallerThreadID
  • m_dwNumOutstandingOutputPinUsers
  • m_hNotifyCallerPinBlockedEvent

CDynamicOutputPin.m_hUnblockOutputPinEvent

CDynamicOutputPin 클래스

핀이 블록되어 있지 않을 때에 통지제의 이벤트.

구문

HANDLE m_hUnblockOutputPinEvent;

CDynamicOutputPin.m_hNotifyCallerPinBlockedEvent

CDynamicOutputPin 클래스

핀의 블록이 성공했을 때, 혹은 유저가 블록 대기를 캔슬했을 때에 통지제의 이벤트.

구문

HANDLE m_hNotifyCallerPinBlockedEvent;

주의

이 변수에 액세스 하기 전에,m_BlockStateLock 크리티컬 섹션을 보관 유지하는 것.

CDynamicOutputPin.m_BlockState

CDynamicOutputPin 클래스

블록 상태.

구문

BLOCK_STATE m_BlockState;

주의

다음 상태를 확인한다.

  • NOT_BLOCKED
  • PENDING
  • BLOCKED

이 변수에 액세스 하기 전에,m_BlockStateLock 크리티컬 섹션을 보관 유지하는 것.

CDynamicOutputPin.m_dwBlockCallerThreadID

CDynamicOutputPin 클래스

이 핀으로 마지막에 IPinFlowControl::Block 메소드를 호출한 thread의 식별자. 이 멤버 변수는, 핀이 블록 되고 있을 때만 유효하다.

구문

DWORD m_dwBlockCallerThreadID;

주의

이 변수에 액세스 하기 전에,m_BlockStateLock 크리티컬 섹션을 보관 유지하는 것.

CDynamicOutputPin.m_dwNumOutstandingOutputPinUsers

CDynamicOutputPin 클래스

이 핀을 사용하고 있는 스트리밍 thread의 수.

구문

DWORD m_dwNumOutstandingOutputPinUsers;

주의

StartUsingOutputPin 메소드는 이 변수를 인크리먼트(increment) 해,StopUsingOutputPin 메소드는 감소 한다. 이 값이 제로보다 클 때, 몇개의 thread가 이 핀을 사용해 데이터를 스트림 하고 있다, 혹은 접속 타입을 변경하고 있다. 이전은 핀을 블록 상태로 할 수 없다.

이 변수에 액세스 하기 전에,m_BlockStateLock 크리티컬 섹션을 보관 유지하는 것.

참조

StreamingThreadUsingOutputPin

CDynamicOutputPin.m_hStopEvent

CDynamicOutputPin 클래스

필터가 정지한, 혹은 핀이 데이터를 플래시 했을 때, 통지제의 이벤트.

구문

HANDLE m_hStopEvent;

CDynamicOutputPin.m_pGraphConfig

CDynamicOutputPin 클래스

동적재접속을 실행하는 IGraphConfig 인터페이스에의 포인터.

구문

IGraphConfig* m_pGraphConfig;

CDynamicOutputPin.m_bPinUsesReadOnlyAllocator

CDynamicOutputPin 클래스

핀의 allocater로부터의 샘플이 읽어들여 전용인가 어떤가를 지정하는 플래그. 이 값이 TRUE 라면 샘플은 읽어들여 전용. 디폴트값은 FALSE.

구문

BOOL m_bPinUsesReadOnlyAllocator;

CDynamicOutputPin::Active

CDynamicOutputPin 클래스

필터가 액티브하게 된 것을 핀에 통지한다.

구문

HRESULT Active(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_FAIL | 실패. SetConfigInfo 가 불려 가지 않았다.

주의

이 메소드는,CBaseOutputPin::Active 메소드를 오버라이드(override) 한다. 또,m_hStopEvent 이벤트를 리셋 한다. 소유하는 필터가 SetConfigInfo 를 호출하지 않은 경우, 이 메소드는 E_FAIL 를 돌려준다.

CDynamicOutputPin::AsynchronousBlockOutputPin

CDynamicOutputPin 클래스

핀을 블록 한다. 핀이 블록 되기 전에 돌아가는 일이 있다.

구문

HRESULT AsynchronousBlockOutputPin(
    HANDLE hNotifyCallerPinBlockedEvent
);

파라미터

hNotifyCallerPinBlockedEvent
이벤트에의 핸들. 출력 핀이 블록 되는지, 호출원이 블록 처리를 취소하면(자), 이벤트는 통지제가 된다.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_PIN_ALREADY_BLOCKED | 핀은 이미 다른 thread로 블록 되고 있다.
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | 핀은 이미 호출해 원의 thread로 블록 되고 있다.

주의

스트리밍 thread로부터 이 메소드를 호출해서는 안 된다.

다른 스트리밍 thread가 핀을 사용하지 않은 경우, 이 메소드는 곧바로 핀을 블록 한다. 그 이외의 경우, 이 메소드는 핀 상태를 "보류중" 으로 해 돌아간다. 스트리밍 처리가 완료 하면, 스트리밍 thread는 StopUsingOutputPin 메소드를 호출해 핀을 블록 해,hNotifyCallerPinBlockedEvent 이벤트에 통지한다. 보류중의 블록을 취소하려면 ,UnblockOutputPin 메소드를 호출한다.

CDynamicOutputPin::Block

CDynamicOutputPin 클래스

핀으로부터의 데이터의 흐름을 블록, 또는 블록 해제한다. IPinFlowControl::Block 메소드를 이행 한다.

구문

HRESULT Block(
    DWORD dwBlockFlags,
    HANDLE hEvent
);

파라미터

dwBlockFlags
핀을 블록 하는지, 블록 해제하는지를 나타내는 플래그. 다음의 몇개의 값이 아니면 안 된다.
  • 제로 : 핀으로부터의 데이터의 흐름을 블록 해제한다.
  • AM_PIN_FLOW_CONTROL_BLOCK : 핀으로부터의 데이터의 흐름을 블록 한다.
hEvent
이벤트 오브젝트에의 핸들, 또는 NULL.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 핀은 이미 블록 해제되고 있다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.
VFW_E_PIN_ALREADY_BLOCKED | 핀은 다른 thread로 이미 블록 되고 있다.
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | 핀은 호출해 원thread로 이미 블록 되고 있다.

주의

이 메소드의 상세한 것에 대하여는, 「IPinFlowControl::Block 」를 참조할것. 이 메소드는, 내부적으로는 다음의 프로텍트 메소드의 어느쪽이든을 호출한다.

  • 블록 (비동기) : AsynchronousBlockOutputPin
  • 블록 (동기) : SynchronousBlockOutputPin
  • 블록 해제 : UnblockOutputPin

블록 해제는, 항상 동기에게 실행된다.

CDynamicOutputPin::BlockOutputPin

CDynamicOutputPin 클래스

핀을 블록 한다. 핀이 블록 되고 있는 동안은,StartUsingOutputPin 메소드가 핀의 블록 해제를 기다린다. 블록 상태에 의해, 출력 핀은 샘플의 출력, 출력 포맷의 변경, 또는 재접속을 할 수 없게 된다.

구문

void BlockOutputPin(void);

주의

이 메소드를 호출하기 전에,m_BlockStateLock 크리티컬 섹션을 보관 유지하는 것. 스트리밍 thread가 이 핀을 사용하고 있다, 혹은 데이터를 출력하고 있다, 혹은 접속을 변경하고 있다면, 이 메소드를 호출해서는 안 된다. 스트리밍 thread가 이 핀을 사용하고 있을지 어떨지를 체크하려면 ,StreamingThreadUsingOutputPin 메소드를 호출하는 것.

CDynamicOutputPin::CDynamicOutputPin

CDynamicOutputPin 클래스

constructor　 　 메소드.

구문

CDynamicOutputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pName
);

파라미터

pObjectName
오브젝트의 이름을 포함한 캐릭터 라인에의 포인터. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pFilter
이 핀을 생성 한 필터에의 포인터.
pLock
상태 변경을 계속하기 위해서 이용하는 CCritSec 락에의 포인터. 필터 락 CBaseFilter.m_pLock 와 같은 크리티컬 섹션을 사용하는 것.
phr
메소드의 성공 또는 실패를 나타내는 HRESULT 값을 받는 변수에의 포인터. 값을 S_OK 에 초기화하고 나서 오브젝트를 생성 한다. 이 값은, 에러가 발생했을 때만 변경된다.
pName
핀 식별자를 포함한 Unicode™ 캐릭터 라인에의 포인터. 상세한 것에 대하여는, 「IPin::QueryId 」를 참조할것.

CDynamicOutputPin::~CDynamicOutputPin

CDynamicOutputPin 클래스

소멸자 메소드.

구문

~CDynamicOutputPin(void);

CDynamicOutputPin::ChangeMediaType

CDynamicOutputPin 클래스

접속의 미디어 타입을 동적으로 변경한다. 이 변경은, 필터 그래프의 실행중에만 발생한다. 이 메소드가 불려 가면(자), 낡은 미디어 타입의 샘플은, 출력할 수 없게 된다. 호출원래는, 낡은 샘플이 대기중이 아닌 것을 확인해야 한다.

구문

HRESULT ChangeMediaType(
    const CMediaType *pmt
);

파라미터

pmt
미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_FAIL | 실패. 소유하는 필터가 SetConfigInfo 를 호출하지 않았던 가능성이 높다.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

이 메소드를 호출하기 전에 StartUsingOutputPin 메소드를 호출하는 것.

이 메소드는 최초로 다운 스트림 입력 핀이 재접속없이 새로운 포맷을 받아들일지 어떨지를 체크한다. 그것은 IPinConnection 인터페이스로 입력 핀에 문의한다. 입력 핀이 IPinConnection 를 지원 한다면, 메소드는 제안된 미디어 타입으로 IPinConnection::DynamicQueryAccept 메소드를 호출한다. 입력 핀이 새로운 미디어 타입을 받아들인다면, 메소드는 IPin::ReceiveConnection 메소드를 호출해, allocater 요구를 재처리 한다.

한편, 다운 스트림 핀이 IPinConnection 를 지원 하지 않는, 혹은 새로운 미디어 타입을 거부하고 싶은들 , 메소드는 DynamicReconnect 메소드를 호출해 동적재접속을 실행한다.

CDynamicOutputPin::ChangeOutputFormat

CDynamicOutputPin 클래스

접속하고 있는 미디어 타입을 동적으로 변경해, 새로운 세그먼트(segment) 정보를 출력한다. 이 메소드가 불려 가면(자), 낡은 미디어 타입의 샘플은, 출력할 수 없게 된다. 호출원래는, 낡은 샘플이 대기중이 아닌 것을 확인해야 한다.

구문

HRESULT ChangeOutputFormat(
    const AM_MEDIA_TYPE *pmt,
    REFERENCE_TIME tSegmentStart,
    REFERENCE_TIME tSegmentStop,
    double dSegmentRate
);

파라미터

pmt
미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.
tSegmentStart
세그먼트(segment)의 시작 타임.
tSegmentStop
세그먼트(segment)의 종료 타임.
dSegmentRate
세그먼트(segment) 레이트.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_FAIL | 실패. 아마 소유자인 필터가 SetConfigInfo 를 호출하지 않았다.
VFW_E_NOT_CONNECTED | 핀이 접속되어 있지 않다.

주의

이 메소드는 필터 실행중에 포맷 타입을 변경한다. 다운 스트림 핀이 새로운 포맷을 승인하면, 재접속은 불필요하다. 그렇지 않으면, 메소드는 핀을 재접속하려고 한다. 메소드는 포맷의 변경에 성공하면(자), 신세그먼트(segment) 정보를 출력한다. 이 메소드는 ChangeMediaType 메소드를 호출해 포맷 변경을 실행한다.

이 메소드를 호출하기 전에 StartUsingOutputPin 메소드를 호출하지 않으면 안 된다.

CDynamicOutputPin::CompleteConnect

CDynamicOutputPin 클래스

입력 핀에의 접속을 완료한다.

구문

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

파라미터

pReceivePin
입력 핀의 IPin 인터페이스에의 포인터.

반환값

성공했을 경우는 S_OK 를 돌려준다. 또는,HRESULT 값을 돌려주어, 실패의 원인을 나타낸다.

주의

이 메소드는,CBaseOutputPin::CompleteConnect 메소드에 오버라이드(override) 한다. 동적인 재접속을 지원 하기 위한(해), 이 메소드는, 필터가 액티브한 경우에 allocater를 위탁한다. base class에서는, 필터가 정지하고 있을 때인 만큼 접속은 발생하므로, allocater는 항상 CBaseOutputPin::Active 메소드로 위탁된다.

CDynamicOutputPin::DeliverBeginFlush

CDynamicOutputPin 클래스

접속한 입력 핀에 플래시 처리를 요구한다.

구문

HRESULT DeliverBeginFlush(void);

반환값

성공이라면 S_OK 를 돌려주는, 그 이외라면 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는 CBaseOutputPin::DeliverBeginFlush 메소드를 오버라이드(override) 한다. 그것은 m_hStopEvent 이벤트를 설정한다.

CDynamicOutputPin::DeliverEndFlush

CDynamicOutputPin 클래스

접속한 입력 핀에 플래시 처리의 종료를 요구한다.

구문

HRESULT DeliverEndFlush(void);

반환값

성공이라면 S_OK 를 돌려주는, 그 이외라면 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는 CBaseOutputPin::DeliverEndFlush 메소드를 오버라이드(override) 한다. 그것은 m_hStopEvent 이벤트를 리셋 한다.

CDynamicOutputPin::Disconnect

CDynamicOutputPin 클래스

현재의 핀 접속을 해제한다. IPin::Disconnect 메소드를 이행 한다.

구문

HRESULT Disconnect(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 핀은 접속되지 않았다.
S_OK | 성공.

주의

이 메소드는,CBasePin::Disconnect 메소드에 오버라이드(override) 해, 필터가 액티브한 동안에 절단이 생기도록(듯이) 한다.

CDynamicOutputPin::DynamicReconnect

CDynamicOutputPin 클래스

새로운 미디어 타입을 사용해 동적인 재접속을 실시한다. 재접속은, 필터 그래프가 실행중에 실시할 수가 있다.

구문

HRESULT DynamicReconnect(
    const CMediaType *pmt
);

파라미터

pmt
미디어 타입을 지정하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_FAIL | 실패. 소유하는 필터가,SetConfigInfo 메소드를 호출하지 않았던 가능성이 높다.

주의

이 메소드는, 핀에 데이터를 제공하는 thread와 같은 thread로부터 불려 가지 않으면 안 된다. 이 메소드가 불려 가면(자), 낡은 미디어 타입의 샘플은 제공할 수 없게 된다. 호출원래는, 낡은 샘플이 대기중이 아닌 것을 확인해야 한다.

StartUsingOutputPin 를 호출해, 이 메소드를 호출한다.

CDynamicOutputPin::Inactive

CDynamicOutputPin 클래스

핀에 필터가 정지하고 있는 것을 통지한다.

구문

HRESULT Inactive(void);

반환값

성공이라면 S_OK 를 돌려주는, 그 이외라면 실패의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는 CBaseOutputPin::Inactive 메소드를 오버라이드(override) 한다. 그것은 m_hStopEvent 이벤트를 설정한다.

CDynamicOutputPin::SetConfigInfo

CDynamicOutputPin 클래스

IGraphConfig 포인터를 지정해, 이벤트를 정지한다.

구문

void SetConfigInfo(
    IGraphConfig *pGraphConfig,
    HANDLE hStopEvent
);

파라미터

pGraphConfig
IGraphConfig 인터페이스에의 포인터, 혹은 NULL.
hStopEvent
필터가 정지할 경우에 통지제의 이벤트에의 핸들, 혹은 NULL.

주의

필터는, 필터 그래프에 참가할 경우에, 이 메소드를 호출하지 않으면 안 된다. 필터 그래프 매니저는,IGraphConfig 를 지원 하고 있다. hStopEvent 파라미터에 대해서는, 수동 리셋 이벤트를 생성 한다. 필터가 필터 그래프로부터 퇴출 하면 와, 양쪽 모두의 파라미터를 NULL 로 해, 이 메소드를 한번 더 호출한다.

CDynamicOutputPin::StartUsingOutputPin

CDynamicOutputPin 클래스

스트리밍 조작으로 핀의 액세스를 획득한다.

구문

virtual HRESULT StartUsingOutputPin(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_UNEXPECTED | 예기치 못한 에러.
VFW_E_STATE_CHANGED | 필터는 정지되었다. 또는, 핀이 flushing를 시작 했다.

주의

접속된 입력 핀에 데이터를 출력하는 메소드, 또는 접속의 미디어 타입을 변경하는 메소드를 호출하기 전에, 이 메소드를 호출하는 것. 다음의 일람은, 이 룰의 적용처가 되는 메소드의 예를 나타내고 있다.

  • ChangeOutputFormat
  • ChangeMediaType
  • DynamicReconnect
  • CBaseOutputPin::Deliver
  • CBaseOutputPin::DeliverEndOfStream
  • CBaseOutputPin::DeliverNewSegment
  • IMemInputPin::Receive
  • IMemInputPin::ReceiveMultiple
  • IPin::EndOfStream
  • IPin::NewSegment

그 후로,StopUsingOutputPin 메소드를 호출해 핀에의 액세스를 해방한다.

핀이 블록 되고 있다면,StartUsingOutputPin 는 핀이 블록 해제가 될 때까지 기다린다. 이 메소드가 기다리고 있는 동안 필터가 정지한다면, 메소드는 곧바로 VFW_E_STATE_CHANGED 를 돌려준다. 핀은 StopUsingOutputPin 에의 대응하는 호출 없이 몇번StartUsingOutputPin 가 불려 갔는가라고 하는 수를 유지한다. 이 카운트가 제로 이외 때에, 다른 thread가 핀을 블록 하려고 하면(자), 핀은 그 블록 상태를 「대기」로 설정한다. 최종적인 StopUsingOutputPin 호출로, 핀은 스트리밍 조작이 모두 완료한 다음에 블록 상태가 된다.

이 메소드를 호출하면나무는,m_BlockStateLock 크리티컬 섹션을 보관 유지해서는 안 된다. 그렇지 않으면 핀이 블록 되었을 때 블록 해제를 할 수 없게 되어 데드 록을 일으킨다.

CDynamicOutputPin::StopUsingOutputPin

CDynamicOutputPin 클래스

스트리밍 조작의 뒤핀에의 액세스를 해방한다.

구문

virtual void StopUsingOutputPin(void);

참조

StartUsingOutputPin

CDynamicOutputPin::StreamingThreadUsingOutputPin

CDynamicOutputPin 클래스

thread가 핀으로 스트리밍 조작을 실시하고 있는지 어떤지를 확인한다.

구문

virtual bool StreamingThreadUsingOutputPin(void);

반환값

thread가 핀으로 스트리밍 조작을 실시하고 있으면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

주의

StartUsingOutputPin 메소드로부터 올바르게 돌려주어진 thread가 있어, 대응하는 StopUsingOutputPin 메소드를 호출하지 않으면 이 메소드는 TRUE 를 돌려준다.

CDynamicOutputPin::SynchronousBlockOutputPin

CDynamicOutputPin 클래스

핀을 블록 한다. 핀이 블록 해제될 때까지 돌아가지 않는다.

구문

HRESULT SynchronousBlockOutputPin(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_PIN_ALREADY_BLOCKED | 핀은 이미 다른 thread로 블록 되고 있다.
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | 핀은 이미 호출해 원thread로 블록 되고 있다.

주의

스트리밍 thread로부터 이 메소드를 호출하지 않는 것.

CDynamicOutputPin::UnblockOutputPin

CDynamicOutputPin 클래스

핀을 블록 해제한다. 핀이 블록 해제되면(자), 샘플의 출력, 출력 포맷의 변경, 및 재접속을 할 수 있게 된다.

구문

HRESULT UnblockOutputPin(void);

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.

S_FALSE | Pin 는 이미 블록 해제되고 있다.
S_OK | 성공.

CDynamicOutputPin::WaitEvent

CDynamicOutputPin 클래스

지정된 이벤트가 통지제가 될 때까지 기다린다.

구문

static HRESULT WaitEvent(
    HANDLE hEvent
);

파라미터

hEvent
이벤트에의 핸들.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_UNEXPECTED | 예기치 않은 에러.


CEnumMediaTypes 클래스

CEnumMediaTypes 클래스의 계층

허용 하는 미디어 타입의 열거자

선언 : Amfilter.h

이 클래스는 IEnumMediaTypes 인터페이스를 이행 한다. 이하의 CBasePin 메소드를 호출한다 :

  • GetMediaType : 제로로 시작되는 ID 로 참조되는 미디어 타입을 취득한다.
  • GetMediaTypeVersion : 허용 하는 타입의 리스트가 변경되었는지 어떠했는지를 확인한다.

핀이 허용 하는 미디어 타입의 리스트를 변경할 때마다, 핀은 미디어 typebar 존수를 인크리먼트(increment) 한다. 이것이 일어나면(자), 열거 오브젝트는 핀과는 이제 동기 하지 않고, 클래스 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. 열거자를 동기 하려면 Reset 를 호출하는 것.

Public 메소드
CEnumMediaTypes | constructor 메소드.
~CEnumMediaTypes | 소멸자 메소드. 가상.
IEnumMediaTypes 메소드.
Clone | 같은 열거 상태로 열거자의 카피를 생성 한다.
Next | 지정한 수만큼 미디어 타입을 취득한다.
Reset | 열거 순서를 시작 상태에 리셋 한다.
Skip | 지정한 수만큼 미디어 타입을 스킵 한다.

CEnumMediaTypes::CEnumMediaTypes

CEnumMediaTypes 클래스

constructor　 　 메소드.

구문

CEnumMediaTypes(
    CBasePin *pPin,
    CEnumMediaTypes *pEnumMediaTypes
);

파라미터

pPin
열거를 해야 할 핀에의 포인터.
pEnumMediaTypes
카피하는 열거자의 IEnumMediaTypes 인터페이스에의 포인터, 혹은 NULL .

주의

pEnumMediaTypes 가 NULL 라면, 이 메소드는 열거 순서의 초기 상태에 열거자를 초기화한다. 그렇지 않으면, 그것은 pEnumMediaTypes 로 지정되는 열거자의 내부 상태를 카피한다.

CEnumMediaTypes::~CEnumMediaTypes

CEnumMediaTypes 클래스

소멸자 메소드.

구문

virtual ~CEnumMediaTypes(void);

CEnumMediaTypes::Clone

CEnumMediaTypes 클래스

같은 열거 상태로 열거자의 카피를 만든다. IEnumMediaTypes::Clone 메소드의 이행.

구문

HRESULT Clone(
    IEnumMediaTypes **ppEnum
);

파라미터

ppEnum
새로운 열거자의 IEnumMediaTypes 인터페이스에의 포인터를 받는 변수의 주소.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
VFW_E_ENUM_OUT_OF_SYNC | 핀 상태는 변경되어 현재 그 열거자와는 모순되고 있다.

CEnumMediaTypes::Next

CEnumMediaTypes 클래스

지정한 수만큼 미디어 타입을 취득한다. IEnumMediaTypes::Next 메소드의 이행.

구문

HRESULT Next(
    ULONG cMediaTypes,
    AM_MEDIA_TYPE **ppMediaTypes,
    ULONG *pcFetched
);

파라미터

cMediaTypes
취득하는 미디어 타입의 수.
ppMediaTypes
사이즈 cPins 의 AM_MEDIA_TYPE 구조체에의 포인터의 배열.
pcFetched
메소드가 돌려주는 미디어 타입의 수를 받는 변수의 포인터. cMediaTypes 가 1 이라면, NULL 를 취할 수 있다.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_FALSE | 요구된 수의 미디어 타입을 취득할 수 없었다.
S_OK | 성공.
E_INVALIDARG | 부적절한 인수.
E_POINTER | NULL 포인터 인수.
VFW_E_ENUM_OUT_OF_SYNC | 핀 상태는 변경되어 현재 그 열거자와는 모순되고 있다.

주의

메소드가 성공하면(자),ppMediaTypes 에 의해 지정되는 배열에는 AM_MEDIA_TYPE 구조체에의 포인터가 들어간다. 구조체의 수는 *pcFetched 와 동일하다. DeleteMediaType 를 호출해, 각 미디어 타입을 프리로 하는 것.

이 미디어는 핀의 CBasePin::GetMediaType 메소드를 호출해 미디어 타입을 취득한다.

CEnumMediaTypes::Reset

CEnumMediaTypes 클래스

열거 순서를 시작 상태에 리셋 한다. IEnumMediaTypes::Reset 메소드의 이행.

구문

HRESULT Reset(void);

반환값

S_OK 를 돌려준다.

CEnumMediaTypes::Skip

CEnumMediaTypes 클래스

지정한 수만큼 미디어 타입을 스킵 한다. IEnumMediaTypes::Skip 메소드의 이행.

구문

HRESULT Skip(
    ULONG cMediaTypes
);

파라미터

cMediaTypes
스킵 하는 미디어 타입의 수.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_FALSE | 순서의 끝까지 스킵 했다.
S_OK | 성공.
VFW_E_ENUM_OUT_OF_SYNC | 핀 상태는 변경되어 현재 그 열거자와는 모순된다.


CEnumPins 클래스

CEnumPins 클래스의 계층

핀의 열거자.

선언 : Amfilter.h

이 클래스는 IEnumPins 인터페이스를 이행 한다. 다음의 CBaseFilter 메소드를 호출한다 :

  • GetPin : 제로로부터 시작되는 ID 로 참조되는 필터의 핀을 취득한다.
  • GetPinCount : 필터의 핀의 총수를 취득한다.
  • GetPinVersion : 핀이 변경되었는지 어떠했는지를 확인한다.

필터가 동적으로 핀을 생성 하거나 삭제하거나 한다면, 핀이 변경될 때마다 핀의 버젼을 인크리먼트(increment) 한다. 버젼수가 변경되면(자), 열거 오브젝트는 이제 그 필터와는 동기 하지 않는다. 열거 자식이 동기부터 제외되면(자),CEnumPins 내의 메소드는 VFW_E_ENUM_OUT_OF_SYNC 를 돌려준다. Reset 메소드를 호출해 열거자와 재동기 하는 것.

Public 메소드
CEnumPins | constructor 메소드.
~CEnumPins | 소멸자 메소드. 가상.
IEnumPins 메소드
Clone | 같은 열거 상태로 열거자의 카피를 만든다.
Next | 지정한 수의 핀을 취득한다.
Reset | 열거 순서를 초기 상태에 리셋 한다.
Skip | 지정한 핀의 수만큼 스킵 한다.

CEnumPins::CEnumPins

CEnumPins 클래스

constructor　 　 메소드.

구문

CEnumPins(
    CBaseFilter *pFilter,
    CEnumPins *pEnumPins
);

파라미터

pFilter
핀을 열거하는 필터에의 포인터.
pEnumPins
카피하는 열거자의 IEnumPins 인터페이스에의 포인터, 혹은 NULL .

주의

pEnumPins 가 NULL 라면, 이 메소드는 열거자를 열거 순서의 초기 상태에 초기화한다. 그 이외라면,pEnumPins 가 지정하는 열거자의 내부 상태를 카피한다.

CEnumPins::~CEnumPins

CEnumPins 클래스

소멸자 메소드.

구문

virtual ~CEnumPins(void);

CEnumPins::Clone

CEnumPins 클래스

같은 열거 상태로 열거자의 카피를 만든다. IEnumPins::Clone 의 이행.

구문

HRESULT Clone(
    IEnumPins **ppEnum
);

파라미터

ppEnum
새로운 열거자의 IEnumPins 인터페이스에의 포인터를 받는 변수의 주소.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
VFW_E_ENUM_OUT_OF_SYNC | 필터 상태는 변경되어 현재 이 열거자와는 모순된다.

CEnumPins::Next

CEnumPins 클래스

지정한 수의 핀을 취득한다. IEnumPins::Next 메소드의 이행.

구문

HRESULT Next(
    ULONG cPins,
    IPin **ppPins,
    ULONG *pcFetched
);

파라미터

cPins
취득하는 핀의 수.
ppPins
IPin 포인터로 묻을 수 있는 cPins 사이즈의 배열.
pcFetched
취득하는 핀의 수를 받는 변수의 포인터. cPins 가 1 이라면 NULL 가 가능.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_FALSE | 요구된 수의 핀을 취득할 수 없었다.
S_OK | 성공.
E_INVALIDARG | 부적절한 인수.
E_POINTER | NULL 포인터 인수.
VFW_E_ENUM_OUT_OF_SYNC | 필터 상태는 변경되어 현재 이 열거자와는 모순된다.

주의

이 메소드는 지정한 수의 핀의 포인터를 취득해, 열거자의 현재 위치로부터 시작 해, 그 포인터를 지정한 배열에 둔다.

이 메소드는 필터의 CBaseFilter::GetPin 메소드를 호출해 핀을 취득한다.

메소드가 성공하면(자),IPin 포인터는 모두 참조 카운트가 남는다. 해방시에 주의가 필요.

CEnumPins::Reset

CEnumPins 클래스

열거 순서를 초기 상태에 리셋 한다. IEnumPins::Reset 메소드의 이행.

구문

HRESULT Reset(void);

반환값

S_OK 를 돌려준다.

CEnumPins::Skip

CEnumPins 클래스

지정한 핀의 수만큼 스킵 한다. IEnumPins::Skip 메소드의 이행.

구문

HRESULT Skip(
    ULONG cPins
);

파라미터

cPins
스킵 하는 핀의 수.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_FALSE | 순서의 마지막까지 스킵 했다.
S_OK | 성공.
VFW_E_ENUM_OUT_OF_SYNC | 필터 상태는 변경되어 현재 이 열거자와는 모순된다.


CFactoryTemplate 클래스

클래스 팩토리를 생성 하는 템플릿을 제공한다.

선언 : Combase.h

Microsoft® DirectShow® 에서는, 클래스 팩토리는 CFactoryTemplate 클래스를 사용해 특수화 되고 있어factory template 를 호출한다. 각 클래스 팩토리는 팩토리 템플릿에의 포인터를 보관 유지한다. 팩토리 템플릿은 오브젝트의 클래스 ID (CLSID)와 오브젝트를 생성 한 함수에의 포인터를 포함한 COM 오브젝트의 정보를 가진다.

자신의 DLL 로,g_Templates 와 이름 붙여진 팩토리 템플릿의 글로벌 배열을 선언하는 것. DllGetClassObject 함수가 새로운 클래스 팩토리를 생성 하면 와, 적합하는 CLSID 로 템플릿의 배열을 찾는다. 1 개(살) 찾아내면(자), 적합한 템플릿에의 포인터를 보관 유지하는 클래스 팩토리를 생성 한다. 클라이언트가 IClassFactory::CreateInstance 를 호출하면 와, 그 클래스 팩토리는 템플릿에 정의된 인스턴스화 함수를 호출한다.

상세한 것에 대하여는, 「DLL 의 생성 방법」을 참조할것.

Public 멤버 변수
m_Name | 필터의 이름.
m_ClsID | 오브젝트의 CLSID 에의 포인터.
m_lpfnNew | 오브젝트의 인스턴스를 생성 하는 함수에의 포인터.
m_lpfnInit | DLL 엔트리 포인트로부터 불려 가는 함수의 포인터.
m_pAMovieSetup_Filter | AMOVIESETUP_FILTER 구조체에의 포인터.
Public 메소드
IsClassID | CLSID 가 이 클래스 템플릿과 맞을지 어떨지를 확인한다.
CreateInstance | 그 클래스의 오브젝트 생성 함수를 호출한다.

CFactoryTemplate.m_Name

CFactoryTemplate 클래스

필터의 이름이 들어가는 와이드 캐릭터 캐릭터 라인

구문

const WCHAR *m_Name;

CFactoryTemplate.m_ClsID

CFactoryTemplate 클래스

오브젝트의 CLSID 에의 포인터.

구문

const CLSID *m_ClsID;

CFactoryTemplate.m_lpfnNew

CFactoryTemplate 클래스

오브젝트의 인스턴스를 생성 하는 함수에의 포인터.

구문

typedef CUnknown *(CALLBACK *LPFNNewCOMObject)(LPUNKNOWN pUnkOuter, HRESULT *phr);

LPFNNewCOMObject m_lpfnNew;

주의

자신의 DLL 로, 오브젝트의 새로운 인스턴스에의 포인터를 돌려주는 정적인 함수를 선언하는 것. 팩토리 템플릿에서는, 이 정적인 함수의 주소에 m_lpfnNew 멤버 변수를 설정한다.

다음의 예는 m_lpfnNew 의 전형적인 함수를 나타낸다 :

CUnknown * WINAPI CMyComponent::CreateInstance(LPUNKNOWN pUnk, HRESULT *pHr)
{
    CMyComponent *pNewObject = new CMyComponent(NAME("My Component"), pUnk, pHr );
    if (pNewObject == NULL)
{
        *phr = E_OUTOFMEMORY;
    }
    return pNewObject;
}

CFactoryTemplate.m_lpfnInit

CFactoryTemplate 클래스

DLL 엔트리 포인트로부터 불려 가는 함수의 포인터. NULL 도 가능.

구문

typedef void (CALLBACK *LPFNInitRoutine)(BOOL bLoading, const CLSID *rclsid);

LPFNInitRoutine m_lpfnInit;

주의

이 함수를 자신의 DLL 로 제공 하면, DLL 엔트리 포인트 함수는 다음의 파라미터로 그것을 호출한다 :

  • bLoading: DLL 가 로드 되고 있을 때 TRUE, DLL 가 로드되어 있지 않을 때 FALSE.
  • rclsid: m_ClsID 멤버 함수로 지정되는 오브젝트의 CLISD 에의 포인터.

CFactoryTemplate.m_pAMovieSetup_Filter

CFactoryTemplate 클래스

AMOVIESETUP_FILTER 구조체에의 포인터.

구문

const AMOVIESETUP_FILTER *m_pAMovieSetup_Filter;

주의

이 구조체를 사용해 필터를 레지스트리 자기 등록으로 한다. 그 컴퍼넌트가 필터는 아니면, 이 멤버 변수는 NULL 도 가능하다. 상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

CFactoryTemplate::CreateInstance

CFactoryTemplate 클래스

그 클래스의 오브젝트 생성 함수를 호출한다.

구문

CUnknown *CreateInstance(
    LPUNKNOWN pUnk,
    HRESULT *phr
);

파라미터

pUnk
집성 한 IUnknown 인터페이스에의 포인터.
phr
메소드의 성공·실패를 나타내는 HRESULT 값을 받는 변수에의 포인터.

반환값

클래스 오브젝트의 인스턴스를 돌려준다.

주의

IClassFactory::CreateInstance 메소드는 이 클래스 메소드를 호출한다. 이 메소드는 m_lpfnNew 멤버 변수에 의해 포인트 되는 함수를 호출한다.

CFactoryTemplate::IsClassID

CFactoryTemplate 클래스

CLSID 가 이 클래스 템플릿과 맞을지 어떨지를 확인한다.

구문

BOOL IsClassID(
    REFCLSID rclsid
);

파라미터

rclsid
CLSID 를 돌려준다.

반환값

rclsid 파라미터가 m_ClsID 와 같은 CLSID 라면 TRUE 를 돌려주어, 그 이외라면 FALSE 를 돌려준다.


CGenericList 클래스

CGenericList 클래스의 계층

타입 고유의 리스트를 이행 하는 클래스 템플릿. 상세한 것에 대하여는, 「CBaseList 」를 참조할것.

선언 : Wxlist.h

이 템플릿을 사용하려면 , 리스트내의 오브젝트의 타입을 정의하는 템플릿 인수로, 타입 CGenericList 의 변수를 선언한다. 예를 들어, 다음의 기술은 CBaseFilter 오브젝트의 리스트를 선언하고 있다 :

CGenericList<CBaseFilter> myFilterList("Filters");

편의상 다음의 리스트 타입이 정의되고 있다 :

typedef CGenericList<CBaseObject> CBaseObjectList;
typedef CGenericList<IUnknown> CBaseInterfaceList;

Public 메소드
CGenericList | constructor 메소드.
~CGenericList | 소멸자 메소드.
GetHeadPosition | 리스트내의 최초의 항목의 위치를 취득한다.
GetTailPosition | 리스트내의 마지막 항목의 위치를 취득한다.
GetCount | 리스트내의 항목의 수를 취득한다.
GetNext | 지정한 위치의 항목을 취득해, 위치를 진행시킨다.
Get | 지정한 위치의 항목을 취득한다.
GetHead | 리스트의 선두 항목을 취득한다.
RemoveHead | 리스트내의 최초의 항목을 삭제한다.
RemoveTail | 리스트내의 마지막 항목을 삭제한다.
Remove | 지정한 위치의 항목을 삭제한다.
AddBefore | 지정한 위치전에 항목이나 리스트를 삽입한다.
AddAfter | 지정한 위치의 뒤에 항목이나 리스트를 삽입한다.
AddHead | 리스트의 선두에 항목이나 리스트를 추가한다.
AddTail | 항목의 말미에 항목이나 리스트를 덧붙인다.
Find | 지정한 항목을 보관 유지하는 최초의 위치를 취득한다.

CGenericList::AddAfter

CGenericList 클래스

지정한 위치의 뒤에 항목이나 리스트를 삽입한다.

구문

POSITION AddAfter(
    POSITION p,
    OBJECT *pObj
);

파라미터

p
그 후에 항목을 추가하는 위치. p 가 NULL 라면, 메소드는 항목을 리스트의 선두에 추가한다.
pObj
타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터.

반환값

삽입된 항목의 위치의 ID 를 돌려준다.

구문

BOOL AddAfter(
    POSITION pos,
    CGenericList<OBJECT> *pList
);

파라미터

pos
그 후에 항목을 추가하는 위치.
pList
삽입하는 리스트에의 포인터.

반환값

성공이라면 TRUE 를, 그 이외라면 FALSE 를 돌려준다.

CGenericList::AddBefore

CGenericList 클래스

지정한 위치전에 항목이나 리스트를 삽입한다.

구문

POSITION AddBefore(
    POSITION p,
    OBJECT *pObj
);

파라미터

p
그 전에 항목을 추가하는 위치. p 가 NULL 라면, 메소드는 항목을 리스트의 말미에 추가한다.
pObj
타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터.

반환값

삽입된 항목의 위치의 ID 를 돌려준다.

구문

BOOL AddBefore(
    POSITION pos,
    CGenericList<OBJECT> *pList
);

파라미터

pos
그 전에 리스트를 삽입하는 위치.
pList
삽입하는 리스트에의 포인터.

반환값

성공이라면 TRUE 를, 그 이외라면 FALSE 를 돌려준다.

CGenericList::AddHead

CGenericList 클래스

리스트의 선두에 항목이나 리스트를 추가한다.

구문

POSITION AddHead(
    OBJECT *pObj
);

파라미터

pObj
타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터.

반환값

새로운 선두 위치를 나타내는 POSITION 값을 돌려준다. 메소드가 실패 하면, 반환값은 NULL 가 된다.

구문

BOOL AddHead(
    CGenericList<OBJECT> *pList
);

파라미터

pList
추가하는 항목 리스트에의 포인터.

반환값

성공이라면 TRUE 를, 그 이외라면 FALSE 를 돌려준다.

CGenericList::AddTail

CGenericList 클래스

항목의 말미에 항목이나 리스트를 덧붙인다.

구문

POSITION AddTail(
    OBJECT *pObj
);

파라미터

pObj
타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터.

반환값

새로운 말미 위치의 POSITION 값을 돌려준다. 메소드가 실패 하면, 반환값은 NULL 가 된다.

구문

BOOL AddTail(
    CGenericList<OBJECT> *pList
);

파라미터

pList
덧붙이는 리스트에의 포인터.

반환값

성공이라면 TRUE 를, 그 이외라면 FALSE 를 돌려준다.

CGenericList::CGenericList

CGenericList 클래스

constructor　 　 메소드.

구문

CGenericList(
    TCHAR *pName,
    INT iItems,
    BOOL bLock,
    BOOL bAlert
);

CGenericList(
    TCHAR *pName
);

파라미터

pName
리스트명에의 포인터.
iItems
노드 캐쉬의 사이즈.
bLock
미사용.
bAlert
미사용.

주의

효율이기 때문에,CGenericList 클래스는 리스트 노드의 캐쉬를 유지한다. 리스트가 보관 유지하는 대체로의 항목수를 알고 있다면, constructor　 　 의 제 1 버젼을 사용해야 하는 것이다. 제 2 버젼은 디폴트의 캐쉬 사이즈를 사용한다.

CGenericList::~CGenericList

CGenericList 클래스

소멸자 메소드.

구문

CGenericList(void);

CGenericList::Find

CGenericList 클래스

지정한 항목을 보관 유지하는 최초의 위치를 취득한다.

구문

POSITION Find(
    OBJECT *pObj
);

파라미터

pObj
타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터.

반환값

POSITION 값을 돌려주는, 리스트에 그 항목이 없으면 NULL 를 돌려준다.

CGenericList::Get

CGenericList 클래스

지정한 위치의 항목을 취득한다.

구문

OBJECT *Get(
    POSITION pos
);

파라미터

pos
취득해야 할 항목의 위치 ID.

반환값

Returns a 타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터.

주의

pos 가 NULL 라면, 메소드는 NULL 를 돌려준다.

CGenericList::GetCount

CGenericList 클래스

리스트내의 항목의 수를 취득한다.

구문

int GetCount(void);

반환값

리스트내의 항목수를 돌려준다.

CGenericList::GetHead

CGenericList 클래스

리스트의 선두 항목을 취득한다.

구문

OBJECT GetHead(void);

반환값

Returns a 타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터.

CGenericList::GetHeadPosition

CGenericList 클래스

리스트내의 최초의 항목의 위치를 취득한다.

구문

POSITION GetHeadPosition(void);

반환값

POSITION 값을 돌려주는, 리스트가 컬러라면 NULL 를 돌려준다.

CGenericList::GetNext

CGenericList 클래스

지정한 위치의 항목을 취득해, 위치를 진행시킨다.

구문

OBJECT *GetNext(
    POSITION& rp
);

파라미터

rp
POSITION 값에의 참조.

반환값

타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터.

주의

이 메소드는 위치 ID 를 다음의 위치하러 진행한다. 위치 ID 가 리스트의 말미를 넘었다면, 메소드는 NULL 를 설정한다.

rp 가 NULL 라면, 메소드는 NULL 를 돌려준다.

CGenericList::GetTailPosition

CGenericList 클래스

리스트내의 마지막 항목의 위치를 취득한다.

구문

POSITION GetTailPosition(void);

반환값

POSITION 값을 돌려주는, 리스트가 컬러라면 NULL 를 돌려준다.

CGenericList::Remove

CGenericList 클래스

지정한 위치의 항목을 삭제한다.

구문

OBJECT *Remove(
    POSITION pos
    );

파라미터

pos
삭제해야 할 항목을 나타내는 POSITION 값.

반환값

타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터.

주의

이 메소드는 리스트로부터 노드를 삭제하지만, 그 노드에 포함되는 항목은 삭제하지 않는다.

rp 가 NULL 라면, 메소드는 NULL 를 돌려준다.

CGenericList::RemoveHead

CGenericList 클래스

리스트내의 최초의 항목을 삭제한다.

구문

OBJECT *RemoveHead(void);

반환값

타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터, 리스트가 컬러라면 NULL 를 돌려준다.

주의

이 메소드는 리스트 노드를 삭제하지만, 노드에 포함되는 항목은 삭제하지 않는다.

CGenericList::RemoveTail

CGenericList 클래스

리스트내의 마지막 항목을 삭제한다.

구문

OBJECT *RemoveTail(void);

반환값

타입 OBJECT (템플릿 타입)의 오브젝트에의 포인터, 리스트가 컬러라면 NULL 를 돌려준다.

주의

이 메소드는 리스트 노드를 삭제하지만, 노드에 포함되는 항목은 삭제하지 않는다.


CImageAllocator 클래스

CImageAllocator 클래스의 계층

CImageAllocator 클래스는, 공유 메모리로 샘플 버퍼를 할당하는 CBaseAllocator 클래스를 계승한다. 블록의 수, 사이즈, 및 alignment는, 접속된출력 핀이 CImageAllocator::SetProperties (IMemAllocator::SetProperties 를 이행 한다)를 호출했을 때에 결정된다. 공유 메모리 블록은, 그 이후의 Microsoft® Win32® CreateDIBSection 함수의 호출로 사용된다. 출력 핀은 이러한 버퍼에 데이터를 저장 할 수가 있어 이 버퍼는 BitBlt 를 사용해 GDI 에게 건네진다.

프로텍트 데이터 멤버

m_pFilter | 이 오브젝트를 소유하는 필터.
m_pMediaType | 현재의 미디어 타입 포맷.

멤버 함수

Alloc | CreateDIBSection 를 사용해 샘플을 할당한다.
CheckSizes | allocater의 조건을 체크한다.
CImageAllocator | CImageAllocator 오브젝트를 생성 한다.
CreateDIB | 디바이스에 의존하지 않는 비트 맵 (DIB)을 생성 한다.
Free | 할당할 수 있던 모든 샘플의 리소스를 해방해 삭제한다.
NotifyMediaType | 합의된 미디어 타입을 allocater에 통지한다.

오버라이드(override) 가능한 멤버 함수

CreateImageSample 샘플을 생성 한다.

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingAddRef | 인터페이스의 참조 카운트를 인크리먼트(increment) 한다.
NonDelegatingRelease | 인터페이스의 참조 카운트를 감소 한다.

이행 되는 IMemAllocator 메소드

SetProperties allocater의 버퍼링의 조건을 지정한다.

CImageAllocator::Alloc

CImageAllocator 클래스

CreateDIBSection 에 근거해 이미지 샘플을 생성 한다.

구문

HRESULT Alloc(void);

반환값

HRESULT 값을 돌려준다.

주의

필터는,CImageAllocator::SetProperties 멤버 함수를 사용해, 필요한 버퍼의 사이즈 및 수를 정의한다. 이 allocater가 파생한 베이스 allocater 클래스는, 실제로 메모리를 위탁할 필요가 있을 때, 이 내부 가상 멤버 함수를 호출한다. 이 allocater는, 생성 하는 각 샘플에 대해, Microsoft Win32 CreateDIBSection 함수를 사용해 DIBSECTION 오브젝트를 생성 한다. 이 호출로부터 취득한 정보를 사용해, 버퍼의 포인터 및 길이를 건네주어 가상 멤버 함수 CreateImageSample 를 호출한다. 이미지 샘플의 생성에 성공하면(자), 그 외의 정보중에서,DIBSECTION 구조체를 사용해 이미지 샘플을 초기화한다.

이것은 프로텍트 멤버 함수이다.

CImageAllocator::CheckSizes

CImageAllocator 클래스

필요한 버퍼링의 프로퍼티를 체크하는 내부 멤버 함수.

구문

HRESULT CheckSizes(
  ALLOCATOR_PROPERTIES *pRequest
  );

파라미터

pRequest
요구된 allocater의 프로퍼티에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이미지 allocater는, Microsoft Win32 CreateDIBSection 함수를 사용해 샘플을 할당한다. CreateDIBSection 함수는, 필요한 비트 맵이 기술된 BITMAPINFO 구조체에의 포인터를 입력으로서 받아들인다. 비트 맵의 사이즈는, 비디오의 BITMAPINFO 구조체에 응해 고정되므로, 이것보다 큰 버퍼를 allocater에 요구해도 받아들일 수 없다. 따라서, 이 멤버 함수는, 요구된 사이즈가 비트 맵의 사이즈보다 커지지 않게, 요구된 사이즈를 조정한다. 요구된 사이즈가 비트 맵의 사이즈보다 작은 경우는, E_INVALIDARG 를 돌려준다.

이것은 프로텍트 멤버 함수이다.

CImageAllocator::CImageAllocator

CImageAllocator 클래스

CImageAllocator 오브젝트를 생성 한다.

구문

CImageAllocator(
  CBaseFilter *pFilter,
  TCHAR *pName,
  HRESULT *phr
  );

파라미터

pFilter
소유하는 필터 오브젝트에의 포인터.
pName
디버그 전용의 캐릭터 라인의 기술에의 포인터.
phr
COM 귀가 코드에의 포인터.

반환값

반환값 없음.

주의

CImageAllocator ,CImageSample , 및 CDrawImage 클래스는, 모두 밀접하게 관련하고 있다. 이미지 allocater가 사용하는 버퍼는, Microsoft Win32 CreateDIBSection 함수를 사용해 생성 된다. 다음에, allocater는 CImageSample 클래스에 근거해 독자적인 샘플을 생성 한다. 이미지 샘플은, 버퍼 포인터와 그 길이를 사용해 초기화된다. 샘플은,CreateDIBSection 의 호출로부터 취득된 다양한 정보를 보관 유지하는 구조체 (DIBDATA 구조체)에도 건네받는다.

이러한 샘플을 드로잉(Drawing) 오브젝트에 건네줄 수가 있다. 드로잉(Drawing) 오브젝트는, 샘플의 프라이빗 포맷, 및 샘플로부터 DIBDATA 구조체를 취득하는 방법을 인식하고 있다. 드로잉(Drawing) 오브젝트는, 이 정보를 취득한 후, 샘플에 포함되는 이미지를 드로잉(Drawing) 할 경우에,DIBDATA 구조체에 저장 된 비트 맵 핸들을 GDI 에 건네줄 수가 있다. 드로잉(Drawing)시에 버퍼 포인터 (샘플이 CImageSample 가 아닌 경우에 사용된다)는 아니고, 샘플로부터 취득한 비트 맵 핸들을 사용하는 것에 의해, 퍼포먼스가 약간 향상한다.

이것은 프로텍트 멤버 함수이다.

CImageAllocator::CreateDIB

CImageAllocator 클래스

Win32 CreateDIBSection 함수를 호출해, 디바이스에 의존하지 않는 비트 맵 (DIB)을 생성 한다.

구문

HRESULT CreateDIB(
  LONG InSize,
  DIBDATA &DibData
  );

파라미터

InSize
필요한 비트 맵의 사이즈.
DibData
상세를 저장 하는 구조체.

반환값

HRESULT 값을 돌려준다.

주의

이것은 프로텍트 멤버 함수이다.

CImageAllocator::CreateImageSample

CImageAllocator 클래스

CImageSample 오브젝트를 생성 한다.

구문

virtual CImageSample *CreateImageSample(
  LPBYTE pData,
  LONG Length
  );

파라미터

pData
샘플이 처리하는 데이터 버퍼에의 포인터.
Length
관련지을 수 있었던 버퍼의 길이.

반환값

새로운 CImageSample 샘플 오브젝트를 돌려준다.

주의

이 가상 멤버 함수는, allocater의 실제의 샘플을 생성 한다. 샘플에는, 데이터 버퍼와 저장 하는 길이가 건네받는다. IMediaSample::GetPointer 를 사용해, 샘플에 추가의 버퍼를 요구 하면, 이 포인터가 돌려주어진다. 이것이 다른 가상 멤버 함수에 분할되고 있는 주된 이유는,CImageAllocator 의 상속 클래스가 CImageSample 로부터도 클래스를 파생시켜, 샘플을 생성하기 위한 장소를 확보할 수 있도록(듯이) 하기 위한(해)이다.

이것은 프로텍트 멤버 함수이다.

CImageAllocator::Free

CImageAllocator 클래스

샘플을 삭제해, 그 리소스를 해방한다.

구문

void Free(void);

반환값

반환값 없음.

주의

베이스 allocater는, 이 allocater를 데코밋트 할 경우에, 이 내부 가상 멤버 함수를 호출한다.

이것은 프로텍트 멤버 함수이다.

CImageAllocator::NonDelegatingAddRef

CImageAllocator 클래스

소유하는 필터의 참조 카운트를 인크리먼트(increment) 한다.

구문

HRESULT NonDelegatingAddRef(void);

반환값

HRESULT 값을 돌려준다.

주의

allocater는, allocater를 생성 하는 필터와는 개념적으로 독립한 오브젝트이다. 다만, 이미지 allocater는, allocater를 생성 한 필터에 의존해, 접속된 미디어 타입등의 추가 정보를 제공한다. 따라서, allocater는 그 자체의 NonDelegatingQueryInterface 함수를 처리하지만, 모든 참조 카운트를 소유하는 필터에 위임한다. 이 때문에, 예를 들어, allocater가 NonDelegatingAddRef 함수의 대상이 되는 경우, 실제로 참조가 카운트 되는 것은, 이 allocater를 소유하는 필터이다.

CImageAllocator::NonDelegatingRelease

CImageAllocator 클래스

소유하는 필터의 참조 카운트를 감소 한다.

구문

HRESULT NonDelegatingRelease(void);

반환값

HRESULT 값을 돌려준다.

주의

allocater는, allocater를 생성 하는 필터와는 개념적으로 독립한 오브젝트이다. 다만, 이미지 allocater는, allocater를 생성 한 필터에 의존해, 접속된 미디어 타입등의 추가 정보를 제공한다. 따라서, allocater는 그 자체의 NonDelegatingQueryInterface 함수를 처리하지만, 모든 참조 카운트를 소유하는 필터에 위임한다. 이 때문에, 예를 들어, allocater가 해방되는 경우, 실제로 NonDelegatingRelease 함수에 의해 해방되는 것은, 이 allocater를 소유하는 필터이다.

CImageAllocator::NotifyMediaType

CImageAllocator 클래스

필터로부터 allocater에 미디어 타입을 건네준다.

구문

void NotifyMediaType(
  CMediaType *pMediaType
  );

파라미터

pMediaType
필터가 확립한 미디어 타입에의 포인터.

반환값

반환값 없음.

주의

이미지 allocater가 생성 하는 버퍼는,CreateDIBSection 에 근거하고 있어 이 함수에는, 필터가 생성 할 필요가 있는 비트 맵의 종류를 지시해야 한다. 필터는, allocater에 대해 이 멤버 함수를 호출하는 것에 의해 이것을 처리한다. 필터는, 보통, 핀의 접속시에 미디어 타입에 대해 합의한 후, 이 멤버 함수를 호출한다. 이 멤버 함수에게 건네지는 미디어 타입은 포인터이다. allocater는, 미디어 타입의 카피는 아니고, 이 포인터를 저장 한다. 이것은, 미디어 타입을 카피하려면 시간이 걸린다고 하는 퍼포먼스 위에의 이유로부터이다. 따라서, 이 멤버 함수를 호출하는 필터는, 이 allocater에 대해 다음에 미디어 타입을 설정하는지, NULL 형을 지정해 불려 갈 때까지, 미디어 타입이 항상 유효한 것을 확인할 필요가 있다.

CImageAllocator::SetProperties

CImageAllocator 클래스

사이즈, 수, 및 블록의 alignment를 판단한다.

구문

HRESULT SetProperties(

  ALLOCATOR_PROPERTIES *pRequest,

  ALLOCATOR_PROPERTIES *pActual

  );

파라미터

pRequest
요구된 allocater의 프로퍼티에의 포인터.
pActual
실제로 설정된 allocater의 프로퍼티에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

pRequest 파라미터에는,ALLOCATOR_PROPERTIES 구조체에 의해 지정되고 있는 카운트, 수, 및 alignment에 대해 요구된 값이, 호출 바탕으로야는 저장 된다. pActual 파라미터에는, 요구에 대해서 제공 가능한 가장 가까운 값이 allocater에 의해 저장 된다. 이 멤버 함수는, allocater가 IMemAllocator::Decommit 메소드를 사용해 데코밋트 될 때까지 호출할 수가 없다.


CImageDisplay 클래스

CImageDisplay 클래스의 계층

CImageDisplay 클래스는 디스플레이 포맷을 사용해 그 자체를 초기화해, 다른 오브젝트가 디스플레이 타입을 문의하거나 리셋 할 수 있도록(듯이) 한다. 또, 디스플레이 포맷을 체크하거나 GDI 의 호출을 사용해 효율적으로 렌더링 할 수 있는 비디오 포맷만을 받아들이기 위한 멤버 함수도 제공한다.

프로텍트 데이터 멤버

m_Display 현재의 디바이스 디스플레이 타입에 대응하는 VIDEOINFO 구조체.

멤버 함수

CheckBitFields | VIDEOINFO 구조체의 비트 필드가 올바른 일을 체크한다.
CheckHeaderValidity | BITMAPINFOHEADER 구조체가 유효한지 어떤지를 판단한다.
CheckMediaType | 필터가출력 핀에 의해 지정된 미디어 타입을 지원 할 수 있을지 어떨지를 판단한다.
CheckPaletteHeader | VIDEOINFO 구조체의 팔레트가 올바른지 어떤지를 판단한다.
CheckVideoType | 비디오 타입을 비교해, 현재의 디스플레이 모드와 호환성이 있을지 어떨지를 판단한다.
CImageDisplay | CImageDisplay 오브젝트를 생성 한다.
CountPrefixBits | 프레픽스빗트의 수를 카운트 한다.
CountSetBits | 필드내에서 설정된 비트의 합계수를 카운트 한다.
GetBitMasks | VIDEOINFO 구조체로 제공된 칼라 요소의 비트 마스크세트를 취득한다.
GetColourMask | 개개의 칼라 요소의 마스크세트를 취득한다.
GetDisplayDepth | 현재의 디스플레이 모드의 비트 깊이를 취득한다.
GetDisplayFormat | 현재의 디스플레이 모드를 나타내는 VIDEOINFO 구조체를 취득한다.
IsPalettized | 디스플레이가 팔레트를 사용할지 어떨지를 판단한다.
RefreshDisplayType | 현재의 디스플레이 타입을 사용해 CImageDisplay 오브젝트를 갱신한다.
UpdateFormat | VIDEOINFO 구조체를 갱신해 암묵의 가정을 삭제한다.

CImageDisplay::CheckBitFields

CImageDisplay 클래스

VIDEOINFO 구조체의 비트 필드가 올바른 일을 체크한다.

구문

BOOL CheckBitFields(
const VIDEOINFO *pInput
    );

파라미터

pInput
체크하는 VIDEOINFO 구조체에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.
TRUE | 비트 필드는 올바르다.
FALSE | 비트 필드에 에러가 포함되어 있다.

주의

오브젝트 전체로, 칼라 컴퍼넌트를 저장 하기 위해서 사용할 수 있는 비트 마스크는 최대 8 비트이라고 가정되고 있다. 이 멤버 함수는, 이 비트 카운트의 가정이 실시되고 있는 것을 체크해, 모든 비트 세트가 연속하고 있는 일도 확인한다.

이것은 프로텍트 멤버 함수이다.

CImageDisplay::CheckHeaderValidity

CImageDisplay 클래스

BITMAPINFOHEADER 구조체가 유효한지 어떤지를 판단한다.

구문

BOOL CheckHeaderValidity(
const VIDEOINFO *pInput
    );

파라미터

pInput
비트 맵의 상세를 저장 하는 VIDEOINFO 구조체에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.
TRUE | 포맷은 유효하다.
FALSE | 포맷에 에러가 포함되어 있다.

주의

BITMAPINFOHEADER 구조체는, 많은 이유로써 거부되는 경우가 있다. 예를 들어, 프레인수의 엔트리가 1 보다 큰가 작은, 이 구조체의 사이즈가 BITMAPINFOHEADER 의 사이즈와 동일하지 않은, 또는 YUV 포맷을 확인하도록(듯이) 지시받았다 (이 멤버 함수는 RGB 포맷만 확인한다. YUV 타입에 대해서는 항상 FALSE 를 돌려준다)등의 이유이다.

CImageDisplay::CheckMediaType

CImageDisplay 클래스

필터가 출력 핀에 의해 지정된 미디어 타입을 지원 할 수 있을지 어떨지를 판단한다.

구문

HRESULT CheckMediaType(
const CMediaType *pmtIn
    );

파라미터

pmtIn
체크하는 미디어 타입에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 헬퍼 함수를 사용해, 비디오의 미디어 타입을 확인할 수 있다. 이 헬퍼 함수는, 메이저 타입 및서브 타입의 GUID 를 조사해 포맷 GUID 가 VIDEOINFO 구조체를 정의하고 있는 것을 확인한다.

CImageDisplay::CheckPaletteHeader

CImageDisplay 클래스

VIDEOINFO 구조체의 팔레트가 올바른지 어떤지를 판단한다.

구문

BOOL CheckPaletteHeader(
const VIDEOINFO *pInput
    );

파라미터

pInput
확인하는 VIDEOINFO 구조체에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.
TRUE | 팔레트는 올바르다.
FALSE | 유효한 팔레트가 없다.

주의

포맷이 팔레트를 사용하지 않는 것을 지정하고 있는 경우 (트루 칼라 포맷등의 경우), 이 멤버 함수는 FALSE 를 돌려준다. 또, 사용되는 (또는 중요한) 팔레트 칼라의 수가 비디오 포맷으로 지정되고 있는 수를 넘고 있는 경우도, FALSE 를 돌려준다.

CImageDisplay::CheckVideoType

CImageDisplay 클래스

비디오 타입을 비교해, 현재의 디스플레이 모드와 호환성이 있을지 어떨지를 판단한다.

구문

HRESULT CheckVideoType(
const VIDEOINFO *pInput
    );

파라미터

pInput
확인하는 VIDEOINFO 구조체에의 포인터.

반환값

성공했을 경우는 NOERROR 를 돌려준다. 그 이외의 경우는 E_INVALIDARG 를 돌려준다.

주의

많은 비디오 렌더링 필터는, 지정된 포맷을 사용할 수 있을지 어떨지를 판단하는 함수를 필요로 한다. 이 멤버 함수는, 미디어 타입으로서 건네받은 VIDEOINFO 구조체를 체크해, 미디어 타입이 유효한 경우는 NOERROR 를 돌려준다. 그 이외의 경우는 E_INVALIDARG434 를 돌려준다. 다만, 현재의 디스플레이 디바이스로 용이하게 표시할 수 있는 포맷만 사용할 수 있다. 예를 들어, 16 비트 디바이스로 24 비트 이미지는 사용할 수 없다. 많은 디스플레이는 8 비트의 팔레트화 된 이미지를 효율적으로 표시할 수 있으므로, 디스플레이가 16 색 VGA 가 아닌 한, 이 포맷은 항상 사용할 수 있다.

CImageDisplay::CImageDisplay

CImageDisplay 클래스

CImageDisplay 오브젝트를 생성 한다.

구문

CImageDisplay(void);

반환값

반환값 없음.

주의

CImageDisplay 클래스는, 현재의 디스플레이 모드의 포맷을 판단할 필요가 있는렌더러를 보조한다. 이 멤버 함수는, 디스플레이 모드를 취득해, 그 포맷을 나타내는 VIDEOINFO 구조체를 생성 한다. 이 클래스는,IsPalettized 및 GetDisplayFormat 등의 멤버 함수에 의해, 그 포맷을 클라이언트에 제공한다. 클라이언트는 디스플레이 포맷이 변경된 것을 검출했을 (클라이언트가 WM_DISPLAYCHANGED 메세지를 수신한다) 경우,RefreshDisplayType 를 호출할 필요가 있다.

CImageDisplay::CountPrefixBits

CImageDisplay 클래스

프레픽스빗트의 수를 카운트 한다.

구문

DWORD CountPrefixBits(
const DWORD Field
    );

파라미터

Field
입력 비트 마스크 필드.

반환값

반환값 없음.

주의

비트 마스크를 지정 하면, 이 헬퍼 함수는, 최하정도로 설정되어 있는 비트까지, 0 의 비트의 수를 카운트 한다. 따라서, 2 진값 00000100 의 경우, 이 멤버 함수는 2 (10 진값)를 돌려준다. 다만, 이 멤버 함수는 DWORD 값에 대해서 기능하므로, 최하정도 비트로부터 DWORD 를 다녀, 최종 비트 (0x80000000)까지 카운트 한다. 비트가 발견되지 않는 경우, 이 멤버 함수는 불가능한 값 32 (10 진값)를 돌려준다.

이것은 프로텍트 멤버 함수이다.

CImageDisplay::CountSetBits

CImageDisplay 클래스

필드내에서 설정된 비트의 합계수를 카운트 한다.

구문

DWORD CountSetBits(
const DWORD Field
    );

파라미터

Field
비트 세트를 카운트 하는 필드.

반환값

비트 세트의 수를 돌려준다.

주의

이것은 프로텍트 멤버 함수이다.

CImageDisplay::GetBitMasks

CImageDisplay 클래스

VIDEOINFO 구조체로 제공된 칼라 요소의 비트 마스크세트를 취득한다.

구문

const DWORD *GetBitMasks(
const VIDEOINFO *pVideoInfo
    );

파라미터

pVideoInfo
입력 VIDEOINFO 구조체 포맷에의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는, RGB 포맷에 대한 보고 호출할 필요가 있다. RGB 포맷의 픽셀 근처의 비트 깊이는 16/32 비트이며, 적, 록, 청의 개개의 칼라 요소의 비트 마스크 (RGB565 의 경우는 0 xF800, 0 x07E0, 및 0x001F 등)를 돌려준다. RGB24 의 경우, 이 멤버 함수는 0 xFF0000, 0 xFF00, 및 0xFF 를 돌려준다. 팔레트화 된 포맷의 경우, 이 멤버 함수는 모두 0 을 돌려준다.

CImageDisplay::GetColourMask

CImageDisplay 클래스

개개의 칼라 요소의 마스크세트를 취득한다.

구문

BOOL GetColourMask(
DWORD *pMaskRed,
DWORD *pMaskGreen,
DWORD *pMaskBlue
    );

파라미터

pMaskRed
빨강의 마스크에의 포인터.
pMaskGreen
초록의 마스크에의 포인터.
pMaskBlue
파랑의 마스크에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.
TRUE | 마스크가 올바르게 저장 되었다.
FALSE | 디스플레이로 사용할 수 있는 마스크가 없었다.

주의

VIDEOINFO 구조체에 의해 나타내지는 비디오 포맷을 지정 하면, 이 멤버 함수는 이 타입의 사용 가능한 칼라의 범위를 취득하기 위해서 사용되는 마스크를 돌려준다. 예를 들어, 24 비트 트루 칼라 포맷의 마스크는 모든 경우로 0xFF 이다. 16 비트 5:6:5 디스플레이 포맷은, 0 xF8, 0 xFC, 및 0xF8 를 사용한다. 따라서, RGB 셋잇단음표를 지정 하면, 이 멤버 함수는, 비트마다의 AND 연산을 사용해, 디스플레이 포맷과 호환성이 있는 포맷을 검색할 수 있다.

CImageDisplay::GetDisplayDepth

CImageDisplay 클래스

현재의 디스플레이 모드의 비트 깊이를 취득한다.

구문

WORD GetDisplayDepth(void);

반환값

디스플레이상에서 사용되는 픽셀 근처의 비트수를 돌려준다.

CImageDisplay::GetDisplayFormat

CImageDisplay 클래스

현재의 디스플레이 모드를 나타내는 VIDEOINFO 구조체를 취득한다.

구문

const VIDEOINFO *GetDisplayFormat(void);

반환값

디스플레이 포맷을 나타내는 VIDEOINFO 구조체를 돌려준다.

CImageDisplay::IsPalettized

CImageDisplay 클래스

디스플레이가 팔레트를 사용할지 어떨지를 판단한다.

구문

BOOL IsPalettized(void);

반환값

디스플레이가 팔레트를 사용하는 경우는 TRUE 를 돌려준다. 그 이외의 경우는 FALSE 를 돌려준다.

CImageDisplay::RefreshDisplayType

CImageDisplay 클래스

현재의 디스플레이 타입을 사용해 CImageDisplay 오브젝트를 갱신한다.

구문

HRESULT RefreshDisplayType(
LPSTR szDeviceName
    );

파라미터

szDeviceName
갱신하는 디바이스의 이름. 생략 했을 경우, 이 파라미터의 디폴트는 메인 디바이스가 된다.

반환값

성공했을 경우는 NOERROR 를 돌려준다. 그 이외의 경우는 E_FAIL 를 돌려준다.

주의

이 멤버 함수는, WM_DISPLAYCHANGED 메세지를 수신했을 때에 호출할 필요가 있다.

CImageDisplay::UpdateFormat

CImageDisplay 클래스

VIDEOINFO 구조체를 갱신해 암묵의 가정을 삭제한다.

구문

HRESULT UpdateFormat(
VIDEOINFO *pVideoInfo
    );

파라미터

pVideoInfo
갱신하는 VIDEOINFO 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 현재의 이행에서는 NOERROR 를 돌려준다.

주의

이 멤버 함수는, 특정의 필터에서의 사용에게만 적합하다. BITMAPINFO 구조체에는, 명확하게 지정되어 있지 않은 특정의 필드가 포함되어 있다. 구체적으로는, 팔레트에 대해 지정되는 칼라의 수를 0 으로 할 수 있어 이 경우, 그포맷 타입의 최대치로서 정의된다. 이 멤버 함수는 이러한 필드를 갱신해, 그 내용이 명시적이 되도록(듯이) 한다.


CImagePalette 클래스

CImagePalette 클래스는, 팔레트를 생성 및 관리해야 하는 이미지 렌더러용의 특수한 클래스이다. 이 클래스를 사용해, 포맷 블록에 VIDEOINFO 구조체를 저장 하는 미디어 포맷화등 팔레트 핸들을 생성 할 수가 있다. 퍼포먼스를 최대화하기 위해서, 이 클래스는 동일 팔레트 (현재의 시스템 팔레트와 같은 팔레트)인 팔레트를 생성 해, 갱신전과 비교해, 실제로 필요한 경우에게만 팔레트를 변경한다.

프로텍트 데이터 멤버

m_hPalette | 이 오브젝트에 의해 소유되는 팔레트 핸들.
m_pBaseWindow | 팔레트가 실현되는 윈도우.
m_pDrawImage | 드로잉(Drawing)를 실행하는 오브젝트.
m_pMediaFilter | 이벤트의 송신지의 미디어 필터.

멤버 함수

CImagePalette | CImagePalette 오브젝트를 생성 한다.
CopyPalette | YUV 또는 트루 칼라의 VIDEOINFOHEADER 구조체로부터 팔레트화 된 VIDEOINFOHEADER 구조체에 팔레트를 카피한다.
MakeIdentityPalette | 팔레트 엔트리를 동일 팔레트로 한다.
MakePalette | 지정된 비디오 이미지로부터 칼라 팔레트를 취득한다.
PreparePalette | 팔레트의 갱신 및 생성의 엔트리 포인트를 지정한다.
RemovePalette | 할당할 수 있던 모든 팔레트 리소스를 해방한다.
ShouldUpdate | 팔레트를 동적으로 갱신하기 위한 내부 헬퍼 멤버 함수를 지정한다.

CImagePalette::CImagePalette

CImagePalette 클래스

CImagePalette 오브젝트를 생성 한다.

구문

CImagePalette(
CBaseFilter *pBaseFilter,
CBaseWindow *pBaseWindow,
CDrawImage *pDrawImage
);

파라미터

pBaseFilter
이 클래스를 소유하는 필터에의 포인터.
pBaseWindow
팔레트를 실현하는 윈도우에의 포인터.
pDrawImage
이 팔레트를 사용해 드로잉(Drawing) 하는 오브젝트에의 포인터.

반환값

반환값 없음.

주의

이 클래스는, 윈도우 팔레트의 생성, 관리, 및 삭제를 처리한다. 이 클래스는, 팔레트에 관련하는 것 외가 많은 오브젝트에게 건네진다. 이 클래스는, 새로운 칼라세트가 현재세트와 다른 경우에게만, 요구된 팔레트의 변경을 실행하도록(듯이) 최적화되고 있다. 팔레트의 변경은 시간이 걸리는 처리이므로, 이것은 퍼포먼스 위에의 최적화이다.

이 constructor　 　 에는, 소유하는 필터 (pBaseFilter)가 건네받는다. 이것은 유효한 포인터가 아니면 안된다. 이 클래스가 실제로 팔레트를 생성 하는 경우, 이 클래스는, 소유하는 필터에 EC_PALETTE_CHANGED 메세지를 필터 그래프 매니저에 송신하도록 지시한다. 이 constructor　 　 에는, 게다가 2 개의 오브젝트 포인터가 건네받는다. pBaseWindow 가 Null 가 아닌 경우, 렌더러가 새로운 팔레트를 생성 할 경우에, 이 클래스는 자동적으로 그 팔레트를 이 윈도우에 인스톨 한다. 팔레트를 삭제하도록(듯이) 지시받았을 경우, 이 클래스는 베이스 윈도우로부터 팔레트를 삭제해, 그 대신에 표준 VGA 팔레트를 인스톨 한다.

이 constructor　 　 에는,CDrawImage 클래스로부터 파생한 드로잉(Drawing) 오브젝트를 건네줄 수도 있다. 이 드로잉(Drawing) 오브젝트가 NULL 이외의 경우, 새로운 팔레트를 생성 할 경우에, 이 클래스는 드로잉(Drawing) 오브젝트로 팔레트가 변경된 것을 통지한다. 이것은, 보통, 윈도우 오브젝트와 조합해 사용된다. 이것에 의해, 팔레트가 변경되면(자) 드로잉(Drawing) 오브젝트에 통지되어 드로잉(Drawing) 오브젝트는,CreateDIBSection 를 사용해 생성 된, 그 오브젝트가 소유하는 샘플을 갱신할 수 있다. 이것은 샘플의 내부 칼라 테이블을 갱신해야 하는 것이 있기 때문에 있다.

CImagePalette::CopyPalette

CImagePalette 클래스

YUV 또는 트루 칼라의 VIDEOINFOHEADER 구조체로부터 팔레트화 된 VIDEOINFOHEADER 구조체에 팔레트를 카피한다.

구문

HRESULT CopyPalette(
const CMediaType *pSrc,
const CMediaType *pDest
);

파라미터

pSrc
카피원미디어 타입에의 포인터.
pDest
카피처 미디어 타입에의 포인터.

반환값

성공했을 경우는 NOERROR 를 돌려준다. 사용할 수 있는 팔레트가 없는 경우는 S_FALSE 를 돌려준다.

주의

이 멤버 함수는, DirectDraw® 샘플에 대해 팔레트를 변경했을 때에 사용된다. 렌더러에의 카피 바탕으로 되는 필터는, 팔레트를 임의의 버퍼에 어태치 해, 새로운 VIDEOINFOHEADER 포맷으로서 렌더러에 건네줄 수가 있다. 다음에, 렌더러는 CopyPalette 를 호출해, 그 포맷화등 새로운 팔레트를 생성 해, 팔레트 칼라를 새로운 접속 타입에 카피한다.

CImagePalette::MakeIdentityPalette

CImagePalette 클래스

PALETTEENTRY 구조체를 변경해, 동일 팔레트를 생성 한다.

구문

HRESULT MakeIdentityPalette(
PALETTEENTRY *pEntry,
INT iColours,
LPSTR szDevice
);

파라미터

pEntry
예측되는 팔레트 칼라의 배열에의 포인터.
iColours
배열의 칼라의 수.
szDevice
전송처 디바이스의 이름을 포함한 캐릭터 라인에의 포인터. 생략 했을 경우, 이 파라미터의 디폴트는 메인 디바이스가 된다.

반환값

성공했을 경우는 NOERROR 를 돌려준다. 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

팔레트가 윈도우에 인스톨 되면(자), GDI 는 가능하면 요구된 칼라를 압축한다. 따라서, 예를 들어, 배열에 흑의 엔트리가 5 개 포함되는 경우, 이것들은 1 개의 팔레트 엔트리에 압축된다. 이것은, 많은 어플리케이션으로 편리하다. 다만, 비디오를 드로잉(Drawing) 하는 경우, 이것에 의해 GDI 는 지정된 이미지내의 픽셀이 압축된 팔레트에 맵 해야 한다. 이 경우, 퍼포먼스는 큰폭으로 저하한다.

따라서, 지정된 PALETTEENTRY 필드를 조정해, 칼라가 압축되지 않게 해야 한다. 이것은, 이미지를 표시하는 윈도우가 foreground 포커스를 가지는 경우에, 이 오브젝트에 의해 생성 된 팔레트가, 디스플레이 디바이스로 선택된 팔레트 (동일 팔레트)에 직접 맵 하는 것을 의미한다.

CImagePalette::MakePalette

CImagePalette 클래스

지정된 비디오 이미지로부터 칼라 팔레트를 취득한다.

구문

HPALETTE MakePalette(
const VIDEOINFOHEADER *pVideoInfo,
LPSTR szDevice
);

파라미터

pVideoInfo
필요한 팔레트 칼라의 컨테이너에의 포인터.
szDevice
전송처 디바이스의 이름을 포함한 캐릭터 라인에의 포인터. 생략 했을 경우, 이 파라미터의 디폴트는 메인 디바이스가 된다.

반환값

새로운 팔레트의 핸들을 돌려준다. 실패했을 경우는 NULL 를 돌려준다.

CImagePalette::PreparePalette

CImagePalette 클래스

팔레트의 생성 및 인스톨의 엔트리 포인트를 지정한다.

구문

HRESULT PreparePalette(
const CMediaType *pmtNew,
const CMediaType *pmtOld,
LPSTR szDevice
);

파라미터

pmtNew
새로운 팔레트 정보를 보관 유지하는 미디어 타입에의 포인터.
pmtOld
낡은 팔레트 정보를 보관 유지하는 미디어 타입에의 포인터.
szDevice
전송처 디바이스의 이름을 포함한 캐릭터 라인에의 포인터. 생략 했을 경우, 이 파라미터의 디폴트는 메인 디바이스가 된다.

반환값

HRESULT 값을 돌려준다.

주의

이것은, 새로운 팔레트를 생성하기 위한 메인 엔트리 포인트이다. 이 멤버 함수는, 요구된 팔레트 칼라가 변경되어 있지 않다고 하는 상황을 검출하려고 한다. 팔레트 칼라가 변경되어 있지 않은 경우는, 새로운 팔레트를 생성 할 필요가 없다. 낡은 미디어 타입을 사용해, 칼라가 변경되었는지 어떠했는지를 판단한다. 또, 옵션으로 윈도우에의 팔레트의 인스톨 (지정되었을 경우)이나, 필터 그래프 매니저에의 팔레트의 변경의 통지 (이 때문에, constructor　 　 에게 건네진 필터를 사용한다)를 처리한다. 마지막으로, 드로잉(Drawing) 오브젝트에의 팔레트의 변경의 통지를 처리한다. 이것도, constructor　 　 에 드로잉(Drawing) 오브젝트가 건네받았는지 어떠했는지에 응해 옵션이다.

CImagePalette::RemovePalette

CImagePalette 클래스

이전에 생성 한 팔레트를 삭제한다.

구문

HRESULT RemovePalette(void);

반환값

HRESULT 값을 돌려준다. 현재의 이행에서는 NOERROR 를 돌려준다.

CImagePalette::ShouldUpdate

CImagePalette 클래스

새로운 팔레트를 생성 할 필요가 있을지 어떨지를 판단한다.

구문

BOOL ShouldUpdate(
const VIDEOINFOHEADER *pNewInfo,
const VIDEOINFOHEADER *pOldInfo
);

파라미터

pNewInfo
새로운 칼라세트를 저장 하는 VIDEOINFOHEADER 구조체에의 포인터.
pOldInfo
낡은 칼라세트를 저장 하는 VIDEOINFOHEADER 구조체에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.
TRUE | 새로운 팔레트가 필요하다.
FALSE | 기존의 팔레트를 사용할 수 있다.

주의

이 함수를 사용해, 새로운 팔레트를 생성 할 필요가 있을지 어떨지를 테스트한다. 원의 타입이 팔레트를 사용하지 않고, 새로운 타입이 팔레트를 사용하는 경우 (또는 그 역의 경우), 이 메소드는 TRUE 를 돌려준다. 어느 포맷도 팔레트를 사용하지 않는 경우, 이 메소드는 FALSE 를 돌려준다. 양쪽 모두의 포맷이 팔레트를 사용하는 경우는 칼라가 비교되어 일치하는 경우, 이 메소드는 FALSE 를 돌려준다.


CImageSample 클래스

CImageSample 클래스의 계층

CImageSample 클래스는 CMediaSample 를 계승해, constructor　 　 을 오버라이드(override) 해,DIBDATA 구조체를 사용해 그 자체를 초기화한다. 렌더러가 독자적인 allocater를 사용하고 있는 경우, 렌더러는 그 샘플용으로 이 클래스를 사용한다. 따라서, 필요한 DIBSECTION 구조체의 정보를 취득해, 렌더링 하는 HBITMAP 데이터를 취득할 수 있다.

프로텍트 데이터 멤버

m_bInit | DIBSECTION 구조체의 정보가 초기화되고 있는지 어떤지를 판단하기 위한 플래그.
m_DibData | 샘플의 DIBSECTION 구조체에 관한 정보.

멤버 함수

CImageSample | CImageSample 오브젝트를 생성 한다.
GetDIBData | 샘플에 대해 저장 된 DIBSECTION 구조체의 정보를 취득한다.
SetDIBData | 샘플에 대해 저장 되는 DIBSECTION 정보를 설정한다.

CImageSample::CImageSample

CImageSample 클래스

CImageSample 오브젝트를 생성 한다.

구문

CImageSample(
  CBaseAllocator *pAllocator,
  TCHAR *pName,
  HRESULT *phr,
  LPBYTE pBuffer,
  LONG length
  );

파라미터

pAllocator
샘플이 속하는 베이스 allocater에의 포인터.
pName
디버그 전용의 캐릭터 라인의 기술에의 포인터.
phr
COM 귀가 코드에의 포인터.
pBuffer
이미지 버퍼에의 포인터.
length
이미지 버퍼의 길이.

반환값

반환값 없음.

주의

CImageAllocator ,CImageSample , 및 CDrawImage 클래스는, 모두 밀접하게 관련하고 있다. 이미지 allocater가 사용하는 버퍼는, Microsoft® Win32® CreateDIBSection 함수를 사용해 생성 된다. 다음에, allocater는 CImageSample 클래스에 근거해 독자적인 샘플을 생성 한다. 이미지 샘플은, 버퍼 포인터와 그 길이를 사용해 초기화된다. 샘플은,CreateDIBSection 의 호출로부터 취득된 다양한 정보를 보관 유지하는 구조체 (DIBDATA 구조체)에도 건네받는다.

이러한 샘플을 드로잉(Drawing) 오브젝트에 건네줄 수가 있다. 드로잉(Drawing) 오브젝트는, 샘플의 프라이빗 포맷, 및 샘플로부터 DIBDATA 구조체를 취득하는 방법을 인식하고 있다. 드로잉(Drawing) 오브젝트는, 이 정보를 취득한 후, 샘플에 포함되는 이미지를 드로잉(Drawing) 할 경우에,DIBDATA 구조체에 저장 된 비트 맵 핸들을 GDI 에 건네줄 수가 있다. 드로잉(Drawing)시에 버퍼 포인터 (샘플이 CImageSample 가 아닌 경우에 사용된다)는 아니고, 샘플로부터 취득한 비트 맵 핸들을 사용하는 것에 의해, 퍼포먼스가 약간 향상한다.

CImageSample::GetDIBData

CImageSample 클래스

샘플에 의해 보관 유지되고 있는 DIBDATA 구조체를 취득한다.

구문

DIBDATA *GetDIBData(void);

반환값

DIBDATA 구조체를 돌려준다.

CImageSample::SetDIBData

CImageSample 클래스

샘플이 보관 유지할 필요가 있는 DIBDATA 구조체를 설정한다.

구문

void SetDIBData(
  DIBDATA *pDibData
  );

파라미터

pDibData
새로운 DIBDATA 구조체에의 포인터.

반환값

반환값 없음.


CLoadDirectDraw 클래스

Microsoft® DirectShow® 는 복수의 플랫폼에서 기능해야 한다. 특히, DirectDraw® 기능을 가지지 않는 Microsoft Windows NT® 3.51 상에서도 실행된다. 따라서, 필터는 DirectDraw 라이브러리에 정적으로 링크할 수 없다. 이 플랫폼에의 의존을 용이하게 처리하기 위해서, 이 클래스는 라이브러리의 로드와 언로드, 및 초기 IDirectDraw 인터페이스의 생성을 관리한다.

멤버 함수

CLoadDirectDraw | CLoadDirectDraw 오브젝트를 생성 한다.
GetDirectDraw | IDirectDraw 인터페이스에의 포인터를 취득한다.
IsDirectDrawLoaded | DirectDraw 가 로드 되고 있는 것을 확인한다.
IsDirectDrawVersion1 | 현재의 시스템에 인스톨 되고 있는 DirectDraw 의 버젼을 체크한다.
LoadDirectDraw | DirectDraw 라이브러리를 로드해 초기화한다.
ReleaseDirectDraw | IDirectDraw 인터페이스를 해방한다.

CLoadDirectDraw::CLoadDirectDraw

CLoadDirectDraw 클래스

CLoadDirectDraw 오브젝트를 생성 한다.

구문

CLoadDirectDraw(void);

반환값

반환값 없음.

CLoadDirectDraw::GetDirectDraw

CLoadDirectDraw 클래스

DirectDraw 인터페이스를 취득한다.

구문

LPDIRECTDRAW GetDirectDraw(void);

반환값

IDirectDraw 인터페이스에의 포인터를 돌려준다.

주의

이 멤버 함수를 호출하기 전에 CLoadDirectDraw::LoadDirectDraw 를 호출해, 처리가 종료해 인터페이스를 해방하려면 CLoadDirectDraw::ReleaseDirectDraw 멤버 함수를 호출한다.

CLoadDirectDraw::IsDirectDrawLoaded

CLoadDirectDraw 클래스

이 오브젝트가 DirectDraw 를 로드한 것을 확인한다.

구문

HRESULT IsDirectDrawLoaded(void);

반환값

로드 되고 있는 경우는, S_OK 를 돌려준다. 그 이외의 경우는, S_FALSE 를 돌려준다.

CLoadDirectDraw::IsDirectDrawVersion1

CLoadDirectDraw 클래스

현재의 시스템에 인스톨 되고 있는 DirectDraw 의 버젼을 체크한다.

구문

BOOL IsDirectDrawVersion1(void);

반환값

인스톨 되고 있는 DirectDraw 의 버젼이 IDirectDraw2 인터페이스를 지원 하고 있지 않는 경우는 TRUE 를 돌려준다. m_pDirectDraw 데이터 멤버가 NULL 의 경우, 또는 인스톨 되고 있는 DirectDraw 의 버젼이 IDirectDraw2 를 지원 하고 있는 경우는 FALSE 를 돌려준다.

주의

비디오 렌더러는, 인스톨 되고 있는 어느 버젼의 DirectDraw 가 IDirectDraw2 인터페이스에 의해 지원 되는 풀 스크린 재생등의 특정의 태스크를 실행하는지를 인식하고 있지 않으면 안 된다.

CLoadDirectDraw::LoadDirectDraw

CLoadDirectDraw 클래스

지정된 영역에 DirectDraw 라이브러리를 로드해 초기화한다.

구문

HRESULT LoadDirectDraw(
  LPSTR szDevice
  );

파라미터

szDevice
이 파라미터는 옵션이다. 이 메소드는 베이스 드로잉(Drawing) 영역에 DirectDraw 를 로드한다.

반환값

DirectDraw 가 올바르고 로드 되었을 경우는 S_OK 를 돌려준다. 그 이외의 경우는 E_NOINTERFACE 를 돌려준다.

주의

DirectDraw 는 항상 사용할 수 있는 것은 아니기 때문에, 어플리케이션은 라이브러리에 정적으로 링크할 수 없다. 따라서, 이 멤버 함수는 라이브러리를 로드해, 함수의 엔트리 포인트 주소를 취득해, 함수를 호출해 드라이버 오브젝트를 생성 한다. 이 멤버 함수는,IDirectDraw 인터페이스를 취득하는 CLoadDirectDraw::GetDirectDraw 를 호출하기 전에 호출한다.

CLoadDirectDraw::ReleaseDirectDraw

CLoadDirectDraw 클래스

IDirectDraw 인터페이스를 해방한다.

구문

void ReleaseDirectDraw(void);

반환값

반환값 없음.

주의

이 멤버 함수는, 이전에 로드 된 IDirectDraw 인터페이스를 해방하기 위해서 불려 간다. 모든 참조 카운트가 해방되었을 경우에게만 이것을 호출한다.


CMediaControl 클래스

CMediaControl 클래스의 계층

CMediaControl 클래스는, 듀얼 인터페이스 IMediaControl 의 IDispatch 메소드의 base class의 처리를 제공한다. 이 클래스는,IMediaControl 인터페이스의 프로퍼티 및 메소드를 순수 가상대로 해 둔다.

보통,IMediaControl 인터페이스를 이행 하는 오브젝트는 필터 그래프 매니저 뿐이다. 필터는,IBaseFilter 로부터 계승한 IMediaFilter 인터페이스를 이행 해, 필터 그래프 매니저로부터의 제어 커멘드를 받는다. 따라서, 이 클래스 라이브러리를 사용하는 것은 필터 개발자로 한정된다.

CMediaControl::GetIDsOfNames ,CMediaControl::GetTypeInfo ,CMediaControl::GetTypeInfoCount , 및 CMediaControl::Invoke 멤버 함수는,IDispatch 메소드의 표준적인 이행으로,CBaseDispatch 클래스 ( 및 타입 라이브러리)를 사용해 커멘드를 해석해,IMediaControl 인터페이스의 순수 가상 메소드에 건네준다.

control.odl 로 정의되는 IMediaControl 는, 순수 가상인 채이다.

멤버 함수

CMediaControl CMediaControl 오브젝트를 생성 한다.

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingQueryInterface 지정된 참조 카운트의 인터페이스를 돌려준다.

이행 되는 IDispatch 메소드

GetIDsOfNames | 단일의 멤버 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자 (DISPID)에 맵 한다. 이 식별자는, 이후의 CMediaControl::Invoke 메소드의 호출로 사용할 수 있다.
GetTypeInfo | 타입 정보 오브젝트를 취득한다. 인터페이스의 타입 정보를 취득할 수 있다.
GetTypeInfoCount | 오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.
Invoke | 오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

CMediaControl::CMediaControl

CMediaControl 클래스

CMediaControl 오브젝트를 생성 한다.

구문

CMediaControl(
const TCHAR *pName,
LPUNKNOWN pUnk
    );

파라미터

pName
디버그를 위해서(때문에) 사용되는 오브젝트의 이름에의 포인터.
pUnk
이 오브젝트의 소유자에게로의 포인터.

반환값

반환값 없음.

주의

스태틱 메모리에 pName 파라미터를 할당한다. 이 이름은, 오브젝트의 생성 및 삭제를 실시하는 데밧깅 단말상에 나타난다.

CMediaControl::GetIDsOfNames

CMediaControl 클래스

단일의 멤버 함수 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자 (DISPID)에 맵 한다. 이 식별자는, 이후의 CMediaControl::Invoke 멤버 함수의 호출로 사용할 수 있다.

구문

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR **rgszNames,
UINT cNames,
LCID lcid,
DISPID *rgdispid
    );

파라미터

riid
참조 식별자. 장래적인 사용을 위해서(때문에) 예약되고 있다. NULL 가 아니면 안된다.
rgszNames
건네받은 맵 하는 이름의 배열에의 포인터의 주소.
cNames
맵 되는 이름의 수.
lcid
이름을 해석하는 로케일 문맥.
rgdispid
호출원 할당하고가 끝난 배열에의 포인터. 각 요소에는,rgszNames 배열에게 건네지는 이름의 1 개에 대응하는 ID 가 포함된다. 최초의 요소는 멤버의 이름을 나타내, 이후의 요소는 각 멤버의 파라미터를 나타낸다.

반환값

다음의 몇개의 값을 돌려준다.
DISP_E_UNKNOWN_CLSID | CLSID 가 인식되지 않았다.
DISP_E_UNKNOWNNAME | 1 개(살) 이상의 이름이 불명했다. 돌려주어진 DISPID 에는, 불명한 이름에 대응하는 각 엔트리의 DISPID_UNKNOWN 가 포함된다.
E_OUTOFMEMORY | 메모리 부족.
S_OK | 성공.

CMediaControl::GetTypeInfo

CMediaControl 클래스

타입 정보 오브젝트를 취득한다. 인터페이스의 타입 정보를 취득할 수 있다.

구문

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo **pptinfo
    );

파라미터

itinfo
돌려주어지는 타입 정보. 제로를 건네주어,IDispatch 이행의 타입 정보를 취득한다.
lcid
타입 정보의 로케일 ID. 로컬라이즈 된 멤버명을 지원 하는 클래스의 경우, 오브젝트는 다른 언어가 다른 타입 정보를 돌려줄 수가 있는 경우가 있다. 로컬라이즈 된 멤버명을 지원 하지 않는 클래스의 경우, 이 파라미터는 무시할 수가 있다.
pptinfo
요구된 타입 정보 오브젝트에의 포인터의 주소.

반환값

pptinfo 가 무효인 경우는, E_POINTER 를 돌려준다. itinfo 가 제로 이외의 경우는, TYPE_E_ELEMENTNOTFOUND 를 돌려준다. 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 타입을 취득하기 위한 호출의 1 개로부터 HRESULT 를 돌려준다. HRESULT 는 에러를 나타내, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
S_OK 또는 NOERROR | 성공.

CMediaControl::GetTypeInfoCount

CMediaControl 클래스

오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.

구문

HRESULT GetTypeInfoCount(
UINT *pctinfo
    );

파라미터

pctinfo
오브젝트가 제공하는 타입 정보 인터페이스의 수에의 포인터. 오브젝트가 타입 정보를 제공했을 경우, 이 수는 1 이다. 그 이외의 경우는, 0 이다.

반환값

pctinfo 가 무효인 경우는, E_POINTER 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

CMediaControl::Invoke

CMediaControl 클래스

오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

구문

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS *pdispparams,
VARIANT *pvarResult,
EXCEPINFO *pexcepinfo,
UINT *puArgErr
    );

파라미터

dispidMember
멤버의 식별자. 디스팟치 식별자를 취득하려면 ,CMediaControl::GetIDsOfNames 또는 오브젝트의 문서를 사용한다.
riid
장래적인 사용을 위해서(때문에) 예약되고 있다. IID_NULL 가 아니면 안된다.
lcid
인수를 해석하는 로케일 문맥.
wFlags
CMediaControl::Invoke 호출의 문맥을 기술하는 플래그.
pdispparams
인수의 배열, 이름 첨부 인수의 인수 디스팟치 ID 의 배열, 및 배열내의 요소의 수를 포함한 구조체에의 포인터.
pvarResult
결과가 저장 되는 포인터, 또는 호출해 원이 결과를 요구하지 않은 경우는 NULL.
pexcepinfo
예외 정보를 포함한 구조체에의 포인터.
puArgErr
DISPPARAMS 구조체의 rgvarg 배열내에서, 에러가 있는 최초의 인수의 인덱스에의 포인터. DISPPARAMS 의 상세한 것에 대하여는, Platform SDK 를 참조할것.

반환값

riid 가 IID_NULL 이외의 경우는, DISP_E_UNKNOWNINTERFACE 를 돌려준다. 호출이 실패했을 경우는,CMediaControl::GetTypeInfo 로부터 에러 코드의 1 개를 돌려준다. 그 이외의 경우는,IDispatch::Invoke 에의 호출로부터 HRESULT 를 돌려준다.

CMediaControl::NonDelegatingQueryInterface

CMediaControl 클래스

지정된 참조 카운트의 인터페이스를 취득한다.

구문

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

디폴트에서는,IMediaControl 및 IUnknown 인터페이스에의 포인터를 돌려준다. 이 멤버 함수를 오버라이드(override) 해, 상속 클래스로 이행 된 추가의 인터페이스를 공개한다.

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 한다.


CMediaEvent 클래스

CMediaEvent 클래스의 계층

CMediaEvent 클래스는, 듀얼 인터페이스 IMediaEvent 의 IDispatch 메소드의 base class의 이행을 제공한다. 이 클래스는,IMediaEvent 인터페이스의 프로퍼티 및 메소드를 순수 가상대로 해 둔다.

CMediaEvent 클래스는,IMediaEvent 로부터 파생한 IMediaEventEx 인터페이스의 base class의 이행도 제공한다.

CMediaEvent::GetIDsOfNames ,CMediaEvent::GetTypeInfo ,CMediaEvent::GetTypeInfoCount , 및 CMediaEvent::Invoke 멤버 함수는,IDispatch 인터페이스의 표준적인 이행으로,CBaseDispatch 클래스 ( 및 타입 라이브러리)를 사용해 커멘드를 해석해,IMediaEvent 인터페이스의 순수 가상 메소드에 건네준다.

멤버 함수

CMediaEvent CMediaEvent 오브젝트를 생성 한다.

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingQueryInterface 지정된 참조 카운트의 인터페이스를 돌려준다.

이행 되는 IDispatch 메소드

GetIDsOfNames | 단일의 멤버 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자에 맵 한다. 이 식별자는, 이후의 IDispatch::Invoke 메소드의 호출로 사용할 수 있다.
GetTypeInfo | 타입 정보 오브젝트를 취득한다. 이 오브젝트는 인터페이스의 타입 정보를 취득한다.
GetTypeInfoCount | 오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.
Invoke | 오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

CMediaEvent::CMediaEvent

CMediaEvent 클래스

CMediaEvent 오브젝트를 생성 한다.

구문

CMediaEvent(
const TCHAR *pName,
LPUNKNOWN pUnk
    );

파라미터

pName
디버그를 위해서(때문에) 사용되는 오브젝트의 이름에의 포인터.
pUnk
이 오브젝트의 소유자에게로의 포인터.

반환값

반환값 없음.

주의

스태틱 메모리에 pName 파라미터를 할당한다. 이 이름은, 오브젝트의 생성 및 삭제를 실시하는 데밧깅 단말상에 나타난다.

CMediaEvent::GetIDsOfNames

CMediaEvent 클래스

단일의 멤버 함수 및 옵션의 파라미터세트를, 대응하는 정수의 디스팟치 식별자에 맵 한다. 이 식별자는, 이후의 CMediaEvent::Invoke 멤버 함수의 호출로 사용할 수 있다.

구문

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR **rgszNames,
UINT cNames,
LCID lcid,
DISPID *rgdispid
    );

파라미터

riid
참조 식별자. 장래적인 사용을 위해서(때문에) 예약되고 있다. NULL 가 아니면 안된다.
rgszNames
건네받은 맵 하는 이름의 배열에의 포인터의 주소.
cNames
맵 되는 이름의 수.
lcid
이름을 해석하는 로케일 문맥.
rgdispid
호출원 할당하고가 끝난 배열에의 포인터. 각 요소에는,rgszNames 배열에게 건네지는 이름의 1 개에 대응하는 ID 가 포함된다. 최초의 요소는 멤버의 이름을 나타내, 이후의 요소는 각 멤버의 파라미터를 나타낸다.

반환값

다음의 몇개의 값을 돌려준다.
DISP_E_UNKNOWN_CLSID | CLSID 가 인식되지 않았다.
DISP_E_UNKNOWNNAME | 1 개(살) 이상의 이름이 불명했다. 돌려주어진 DISPID 에는, 불명한 이름에 대응하는 각 엔트리의 DISPID_UNKNOWN 가 포함된다.
E_OUTOFMEMORY | 메모리 부족.
S_OK | 성공.

CMediaEvent::GetTypeInfo

CMediaEvent 클래스

타입 정보 오브젝트를 취득한다. 인터페이스의 타입 정보를 취득할 수 있다.

구문

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo **pptinfo
    );

파라미터

itinfo
돌려주어지는 타입 정보. 제로를 건네주어,IDispatch 이행의 타입 정보를 취득한다.
lcid
타입 정보의 로케일 ID. 로컬라이즈 된 멤버명을 지원 하는 클래스의 경우, 오브젝트는 다른 언어가 다른 타입 정보를 돌려줄 수가 있는 경우가 있다. 로컬라이즈 된 멤버명을 지원 하지 않는 클래스의 경우, 이 파라미터는 무시할 수가 있다.
pptinfo
요구된 타입 정보 오브젝트에의 포인터의 주소.

반환값

pptinfo 가 무효인 경우는, E_POINTER 를 돌려준다. itinfo 가 제로 이외의 경우는, TYPE_E_ELEMENTNOTFOUND 를 돌려준다. 성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 타입을 취득하기 위한 호출의 1 개로부터 HRESULT 를 돌려준다. HRESULT 는 에러를 나타내, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
S_OK 또는 NOERROR | 성공.

CMediaEvent::GetTypeInfoCount

CMediaEvent 클래스

오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 취득한다.

구문

HRESULT GetTypeInfoCount(
UINT *pctinfo
    );

파라미터

pctinfo
오브젝트가 제공하는 타입 정보 인터페이스의 수에의 포인터. 오브젝트가 타입 정보를 제공했을 경우, 이 수는 1 이다. 그 이외의 경우는, 0 이다.

반환값

pctinfo 가 무효인 경우는, E_POINTER 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

CMediaEvent::Invoke

CMediaEvent 클래스

오브젝트에 의해 공개되는 프로퍼티 및 메소드에의 액세스를 제공한다.

구문

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS *pdispparams,
VARIANT *pvarResult,
EXCEPINFO *pexcepinfo,
UINT *puArgErr
    );

파라미터

dispidMember
멤버의 식별자. 디스팟치 식별자를 취득하려면 ,CMediaEvent::GetIDsOfNames 또는 오브젝트의 문서를 사용한다.
riid
장래적인 사용을 위해서(때문에) 예약되고 있다. IID_NULL 가 아니면 안된다.
lcid
인수를 해석하는 로케일 문맥.
wFlags
CMediaEvent::Invoke 호출의 문맥을 기술하는 플래그.
pdispparams
인수의 배열, 이름 첨부 인수의 인수 디스팟치 ID 의 배열, 및 배열내의 요소의 수를 포함한 구조체에의 포인터.
pvarResult
결과가 저장 되는 포인터, 또는 호출해 원이 결과를 요구하지 않은 경우는 NULL.
pexcepinfo
예외 정보를 포함한 구조체에의 포인터.
puArgErr
DISPPARAMS 구조체의 rgvarg 배열내에서, 에러가 있는 최초의 인수의 인덱스에의 포인터. DISPPARAMS 의 상세한 것에 대하여는, Platform SDK 를 참조할것.

반환값

riid 가 IID_NULL 이외의 경우는, DISP_E_UNKNOWNINTERFACE 를 돌려준다. 호출이 실패했을 경우는,CMediaEvent::GetTypeInfo 로부터 에러 코드의 1 개를 돌려준다. 그 이외의 경우는,IDispatch::Invoke 에의 호출로부터 HRESULT 를 돌려준다.

CMediaEvent::NonDelegatingQueryInterface

CMediaEvent 클래스

지정된 참조 카운트의 인터페이스를 돌려준다.

구문

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

디폴트에서는,IMediaEvent 및 IUnknown 인터페이스에의 포인터를 돌려준다. 이 멤버 함수를 오버라이드(override) 해, 상속 클래스로 추가된 인터페이스를 공개한다.

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 한다.


CMediaPosition 클래스

CMediaPosition 클래스의 계층

IMediaPosition 듀얼 인터페이스의 IDispatch 메소드 처리한다.

이 클래스는 IMediaPosition 인터페이스를 계승하지만, 그것을 이행 해서는 안 된다. CBaseDispatch 클래스와 Microsoft® DirectShow® 타입 라이브러리를 통해 IDispatch 를 이행 한다. 이 클래스를 직접 사용해서는 안 된다. 그렇지 않고, 이하의 1 개를 사용하는 것 :

  • 소스 필터 : CSourceSeeking base class를 사용해 시크를 이행 한다.
  • 변환 필터 : CPosPassThru 클래스를 사용해 시크 커멘드를 업 스트림에 건네준다.
  • 렌더러 : CRendererPosPassThru 클래스를 사용해 시크 커멘드를 업 스트림에 건네준다.
Public 메소드
CMediaPosition | constructor 메소드.
IDispatch 메소드
GetIDsOfNames | 이름세트를 대응하는 DISPID 세트에 맵 한다.
GetTypeInfo | 오브젝트의 타입 정보를 취득하는, 그것은 다음에 인터페이스의 타입 정보를 취득하기 위해서 사용된다.
GetTypeInfoCount | 오브젝트가 제공하는 타입 정보 인터페이스의 수를 취득한다.
Invoke | 오브젝트가 공개하는 프로퍼티와 메소드에의 액세스를 제공한다.

CMediaPosition::CMediaPosition

CMediaPosition 클래스

constructor　 　 메소드.

구문

CMediaPosition(
    const TCHAR *pName,
    LPUNKNOWN pUnk
);

CMediaPosition(
    const TCHAR *pName,
    LPUNKNOWN pUnk
    HRESULT *phr
);

파라미터

pName
오브젝트의 이름에의 포인터, 디버그용. 이 파라미터는 스태틱 메모리에 할당할 수 있다.
pUnk
이 오브젝트의 소유자에게로의 포인터, 혹은 오브젝트가 집성 되고 있다면 NULL .
phr
무시된다.

CMediaPosition::GetIDsOfNames

CMediaPosition 클래스

이름세트를 대응하는 DISPID 세트에 맵 한다.

구문

HRESULT GetIDsOfNames(
    REFIID riid,
    OLECHAR **rgszNames,
    UINT cNames,
    LCID lcid,
    DISPID *rgdispid
);

파라미터

riid
예약이 끝난 상태. IID_NULL 를 사용.
rgszNames
맵 되는 이름이 들어가는 와이드 캐릭터 캐릭터 라인의 배열의 주소.
cNames
rgszNames 파라미터에 의해 주어지는 배열의 사이즈.
lcid
이름을 해석하는 로케일 문맥. NULL 가 가능.
rgdispid
DISPID 를 받는 배열에의 포인터. 받은 각 요소는 rgszNames 파라미터에게 건네진 이름의 1 개 1 개(살)에 대응하는 ID 이다.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
DISP_E_UNKNOWNNAME | 1 개(살) 혹은 그 이상의 이름이 불명했다.

CMediaPosition::GetTypeInfo

CMediaPosition 클래스

오브젝트의 타입 정보를 취득하는, 그것은 다음에 인터페이스의 타입 정보를 취득하기 위해서 사용된다.

구문

HRESULT GetTypeInfo(
    UINT itinfo,
    LCID lcid,
    ITypeInfo **pptinfo
);

파라미터

itinfo
돌려주어야 할 타입 정보. 제로가 아니면 안된다.
lcid
로케일 식별자.
pptinfo
ITypeInfo 포인터를 받는 변수의 주소.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
TYPE_E_ELEMENTNOTFOUND | itinfo 파라미터는 제로여서는 안 된다.

CMediaPosition::GetTypeInfoCount

CMediaPosition 클래스

오브젝트가 제공하는 타입 정보 인터페이스의 수를 취득한다.

구문

HRESULT GetTypeInfoCount(
    UINT *pctinfo
);

파라미터

pctinfo
오브젝트에 의해 제공되는 타입 정보 인터페이스의 수를 받는 변수에의 포인터. 메소드가 돌아갈 때, 값은 1 .

반환값

다음의 값의 1 개를 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

CMediaPosition::Invoke

CMediaPosition 클래스

오브젝트가 공개하는 프로퍼티와 메소드에의 액세스를 제공한다.

구문

HRESULT Invoke(
    DISPID dispidMember,
    REFIID riid,
    LCID lcid,
    WORD wFlags,
    DISPPARAMS *pdispparams,
    VARIANT *pvarResult,
    EXCEPINFO *pexcepinfo,
    UINT *puArgErr
);

파라미터

dispidMember
멤버의 ID . 디스팟치 식별자를 취득하려면 ,CMediaPosition::GetIDsOfNames 를 사용한다.
riid
장래적인 사용을 위해서(때문에) 예약되고 있다. IID_NULL 가 아니면 안된다.
lcid
인수를 해석하는 로케일 문맥.
wFlags
호출의 문맥을 기술하는 플래그.
pdispparams
인수를 넣는 DIPPARAMS 구조체에의 포인터.
pvarResult
결과를 받는 VARIANT 에의 포인터, 혹은 호출해 원이 결과를 필요로 하지 않으면 NULL .
pexcepinfo
예외 정보를 받는 구조체에의 포인터.
puArgErr
에러를 일으키는 최초의 인수의 인덱스를 받는 변수에의 포인터.

반환값

HRESULT 를 돌려준다. 이하의 몇개의 값을 포함한다.

S_OK | 성공.
DISP_E_UNKNOWNINTERFACE | riid 파라미터가 IID_NULL 는 아니다.


CMediaSample 클래스

CMediaSample 클래스의 계층

IMediaSample2 인터페이스를 지원 하는 미디어 샘플을 정의한다. 미디어 샘플은 메모리 버퍼에의 포인터와 프로텍트 멤버 변수에 스토어 되고 있는 몇개의 프로퍼티를 가진다.

선언 : Amfilter.h

미디어 샘플은 CBaseAllocator 클래스로부터 파생되는 allocater에 의해 생성 된다. CMediaSample constructor　 　 은 버퍼 사이즈와 함께 allocater 버퍼에의 포인터를 받는다. 다른 프로퍼티는 보통 IMediaSample 인터페이스 메소드를 통해 세트 되는 혹은 수취된다.

미디어 샘플의 라이프 사이클은 대부분의 COM 오브젝트의 그것과는 다르다 :

  • allocater는 프리 샘플의 리스트를 보관 유지한다. 필터가 새로운 샘플을 필요로 할 때, allocater의 IMemAllocator::GetBuffer 메소드를 호출한다. allocater는 그 면세표로부터 샘플을 취득해, 그 샘플의 참조 카운트를 인크리먼트(increment) 해, 그 샘플의 포인터를 돌려준다.
  • 필터가 샘플에서의 처리를 종료했을 때, 샘플의 IUnknown::Release 메소드를 호출한다. 대부분의 오브젝트는 달라, 참조 카운트가 제로가 되어도 샘플은 자신을 삭제하지 않는다. 그렇지 않고, allocater의 IMemAllocator::ReleaseBuffer 메소드를 호출해, allocater는 면세표에 그 샘플을 돌려준다.
  • allocater는 IMemAllocator::Decommit 가 불려 갈 때까지 샘플을 삭제하지 않는다.
Protected 멤버 변수
m_dwFlags | 샘플 프로퍼티 플래그.
m_dwTypeSpecificFlags | 타입 고유의 플래그.
m_pBuffer | 미디어 데이터가 들어가는 메모리 버퍼에의 포인터.
m_lActual | 버퍼내의 유효한 데이터의 길이, 바이트 단위.
m_cbBuffer | 버퍼의 사이즈, 바이트 단위.
m_pAllocator | 샘플을 생성 한 allocater에의 포인터.
m_pNext | allocater의 샘플 리스트에 있는 다음의 샘플에의 포인터.
m_Start | 샘플 시작 타임.
m_End | 샘플 종료 타임.
m_MediaStart | 미디어 시작 타임.
m_MediaEnd | 미디어 종료 타임.
m_pMediaType | 미디어 타입이 그 데이터 스트림의 전의 샘플로부터 변경되고 있다면, 미디어 타입에의 포인터.
m_dwStreamId | 스트림 식별자.
Public 멤버 변수
m_cRef | 참조 카운트.
Public 메소드
CMediaSample | constructor 메소드.
~CMediaSample | 소멸자 메소드. 가상.
SetPointer | 메모리 버퍼에의 포인터를 설정한다.
IMediaSample 메소드
GetPointer | 버퍼의 읽어들여/기입 포인터를 취득한다.
GetSize | 버퍼의 사이즈를 취득한다.
GetTime | 샘플이 시작·종료하는 스트림 타임을 취득한다.
SetTime | 샘플이 시작·종료하는 스트림 타임을 설정한다.
IsSyncPoint | 샘플의 시작이 동기 포인트인가 어떤가를 확인한다.
SetSyncPoint | 샘플의 시작이 동기 포인트인가 어떤가를 설정한다.
IsPreroll | 샘플이 프리로르산풀인가 어떤가를 확인한다.
SetPreroll | 샘플이 프리로르산풀인가 어떤가를 설정한다.
GetActualDataLength | 버퍼내의 유효한 데이터의 길이를 취득한다.
SetActualDataLength | 버퍼내의 유효한 데이터의 길이를 설정한다.
GetMediaType | 미디어 타입이 전의 샘플과 다르다면, 미디어 타입을 취득한다.
SetMediaType | 샘플의 미디어 타입을 설정한다.
IsDiscontinuity | 샘플이 데이터 스트림내에 브레이크를 표시하는(불연속) 화도인지를 확인한다.
SetDiscontinuity | 샘플이 데이터 스트림내에서 브레이크를 표시하는(불연속) 화도인지를 설정한다.
GetMediaTime | 샘플의 미디어 타임을 취득한다.
SetMediaTime | 샘플의 미디어 타임을 설정한다.
IMediaSample2 메소드
GetProperties | 샘플의 프로퍼티를 취득한다.
SetProperties | 샘플의 프로퍼티를 설정한다.

CMediaSample.m_dwFlags

CMediaSample 클래스

샘플 프로퍼티 플래그. AM_SAMPLE_PROPERTY_FLAGS 열거형 플래그의 비트의 편성.

구문

DWORD m_dwFlags;

CMediaSample.m_dwTypeSpecificFlags

CMediaSample 클래스

타입 고유의 플래그. 이 멤버 변수의 의미는 샘플의 미디어 타입에 의존한다.

구문

DWORD m_dwTypeSpecificFlags;

CMediaSample.m_pBuffer

CMediaSample 클래스

미디어 데이터가 들어가는 메모리 버퍼에의 포인터.

구문

LPBYTE m_pBuffer;

CMediaSample.m_lActual

CMediaSample 클래스

버퍼내의 유효한 데이터의 길이, 바이트 단위. 이 값은 (m_cbBuffer ) 버퍼의 사이즈 이하가 아니면 안된다.

구문

LONG m_lActual;

CMediaSample.m_cbBuffer

CMediaSample 클래스

버퍼의 사이즈, 바이트 단위.

구문

LONG m_cbBuffer;

CMediaSample.m_pAllocator

CMediaSample 클래스

샘플을 생성 한 allocater에의 포인터.

구문

CBaseAllocator *m_pAllocator;

주의

샘플은 allocater에의 포인터를 보관 유지하지만, 참조 카운트는 보관 유지하지 않는다. 그 대신, allocater는 그것 자신의 참조 카운트를 IMemAllocator::GetBuffer 메소드로 인크리먼트(increment) 해, 그것 자신을 IMemAllocator::ReleaseBuffer 메소드로 해방한다. 이것은 allocater는 다른 오브젝트가 그 샘플을 사용하고 있는 한은 유효한 것을 보증하고 있다.

CMediaSample.m_pNext

CMediaSample 클래스

allocater의 샘플 리스트에 있는 다음의 샘플에의 포인터.

구문

CMediaSample *m_pNext;

CMediaSample.m_Start

CMediaSample 클래스

샘플 시작 타임. 이 값은 m_dwFlags 멤버 변수가 AM_SAMPLE_TIMEVALID 플래그를 포함할 때 마셔 유효.

구문

REFERENCE_TIME m_Start;

CMediaSample.m_End

CMediaSample 클래스

샘플 종료 타임. 이 값은 m_dwFlags 멤버 변수가 AM_SAMPLE_STOPVALID 플래그를 포함할 때 마셔 유효.

구문

REFERENCE_TIME m_End;

CMediaSample.m_MediaStart

CMediaSample 클래스

미디어 시작 타임.

구문

LONGLONG m_MediaStart;

CMediaSample.m_MediaEnd

CMediaSample 클래스

미디어 종료 타임. 이 값은 미디어 시작 타임 (m_MediaStart )부터의 오프셋(offset)로서 계산된다.

구문

LONG m_MediaEnd;

CMediaSample.m_pMediaType

CMediaSample 클래스

미디어 타입이 그 데이터 스트림의 전의 샘플로부터 변경되고 있다면, 미디어 타입에의 포인터. 그렇지 않으면 NULL.

구문

AM_MEDIA_TYPE *m_pMediaType;

CMediaSample.m_dwStreamId

CMediaSample 클래스

스트림 식별자. 상세한 것에 대하여는, 「AM_SAMPLE2_PROPERTIES 」를 참조할것.

구문

DWORD m_dwStreamId;

CMediaSample.m_cRef

CMediaSample 클래스

참조 카운트.

구문

LONG m_cRef;

CMediaSample::CMediaSample

CMediaSample 클래스

constructor　 　 메소드.

구문

CMediaSample(
    TCHAR *pName,
    CBaseAllocator *pAllocator,
    HRESULT *phr,
    LPBYTE pBuffer = NULL,
    LONG length = 0
);

파라미터

pName
미디어 샘플의 이름을 넣는 캐릭터 라인에의 포인터.
pAllocator
이 샘플을 생성 한 CBaseAllocator 오브젝트에의 포인터.
phr
메소드의 성공·실패를 나타내는 HRESULT 값을 받는 변수에의 포인터.
pBuffer
호출 바탕으로야는 할당할 수 있었던 length 사이즈의 메모리 버퍼에의 포인터.
length
메모리 버퍼의 길이.

주의

base class는 phr 파라미터에게 건네진 HRESULT 값을 수정하지 않는다.

CMediaSample::~CMediaSample

CMediaSample 클래스

소멸자 메소드.

구문

~CMediaSample(void);

CMediaSample::GetActualDataLength

CMediaSample 클래스

버퍼내의 유효한 데이터의 길이를 취득한다. IMediaSample::GetActualDataLength 메소드의 이행.

구문

LONG GetActualDataLength(void);

반환값

유효한 데이터의 길이, 바이트 단위.

주의

이 프로퍼티를 지정하는 m_lActual 멤버 변수.

CMediaSample::GetMediaTime

CMediaSample 클래스

샘플의 미디어 타임을 취득한다. IMediaSample::GetMediaTime 메소드의 이행.

구문

HRESULT GetMediaTime(
    LONGLONG *pStart,
    LONGLONG *pEnd
);

파라미터

pStart
미디어 시작 타임을 받는 변수에의 포인터.
pEnd
미디어 종료 타임을 받는 변수에의 포인터.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
VFW_E_MEDIA_TIME_NOT_SET | 이 샘플에는 미디어 타임이 세트되어 있지 않다.

주의

m_MediaEnd 멤버 변수는 m_MediaStart 로부터의 오프셋(offset)를 나타내지만,pEnd 파라미터가 받는 값은 m_MediaStart + m_MediaEnd 로 계산되는 절대 미디어 타임이다.

미디어 타임의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

CMediaSample::GetMediaType

CMediaSample 클래스

미디어 타입이 전의 샘플과 다르다면, 미디어 타입을 취득한다. IMediaSample::GetMediaType 메소드의 이행.

구문

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

파라미터

ppMediaType
AM_MEDIA_TYPE 구조체에의 포인터를 받는 변수의 주소. 미디어 타입이 전의 샘플로부터 변경으로 되어 있지 않으면,*ppMediaType 에는 NULL 가 세트 된다.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_FALSE | 전의 샘플로부터 미디어 타입은 변경되어 있지 않다.
S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.

주의

미디어 타입의 작업이 종료하면(자),DeleteMediaType 유틸리티 함수를 호출해 메모리 블록을 프리로 하는 것.

m_pMediaType 멤버 변수는 미디어 타입을 나타낸다. m_dwFlags 멤버 변수는 미디어 타입이 변경되었는지 어떠했는지를 나타낸다.

CMediaSample::GetPointer

CMediaSample 클래스

버퍼의 읽어들여/기입 포인터를 취득한다. IMediaSample::GetPointer 메소드의 이행.

구문

HRESULT GetPointer(
    BYTE **ppBuffer
);

파라미터

ppBuffer
버퍼에의 포인터를 받는 변수에의 포인터.

반환값

S_OK 를 돌려준다.

CMediaSample::GetProperties

CMediaSample 클래스

샘플의 프로퍼티를 취득한다. IMediaSample2::GetProperties 메소드의 이행.

구문

HRESULT GetProperties(
    DWORD cbProperties,
    BYTE *pbProperties
);

파라미터

cbProperties
받는 프로퍼티 데이터의 길이, 바이트 단위.
pbProperties
cbProperties 사이즈의 버퍼에의 포인터.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

CMediaSample::GetSize

CMediaSample 클래스

버퍼의 사이즈를 취득한다. IMediaSample::GetSize 메소드의 이행.

구문

LONG GetSize(void);

반환값

버퍼의 사이즈를 돌려주는, 바이트 단위.

CMediaSample::GetTime

CMediaSample 클래스

샘플이 시작·종료하는 스트림 타임을 취득한다. IMediaSample::GetTime 메소드의 이행.

구문

HRESULT GetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

파라미터

pTimeStart
시작 스트림 타임을 받는 변수에의 포인터, 100 나노초단위.
pTimeEnd
종료 스트림 타임을 받는 변수에의 포인터, 100 나노초단위. 샘플이 종료 타임을 가지고 있지 않으면, 이 값에는 시작 타임 플러스 1 이 세트 된다.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
VFW_S_NO_STOP_TIME | 샘플은 유효한 시작 타임을 가지고 있지만, 종료 타임을 가지고 있지 않다.
VFW_E_SAMPLE_TIME_NOT_SET | 샘플은 유효한 타임 스탬프를 가지고 있지 않다.

주의

m_Start 와 m_End 멤버 변수는 타임 스탬프를 나타낸다. m_dwFlags 멤버 변수는 타임 스탬프가 유효한가 어떤가를 나타낸다.

타임 스탬프의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

CMediaSample::IsDiscontinuity

CMediaSample 클래스

샘플이 데이터 스트림내에 브레이크를 표시하는 제발을 확인한다. IMediaSample::IsDiscontinuity 의 이행.

구문

HRESULT IsDiscontinuity(void);

반환값

샘플의 데이터 스트림내에 브레이크가 있으면 S_OK 를 돌려주는, 그렇지 않으면 S_FALSE 를 돌려준다.

주의

m_dwFlags 멤버 변수는 이 프로퍼티를 나타낸다.

CMediaSample::IsPreroll

CMediaSample 클래스

샘플이 프리로르산풀인가 어떤가를 확인한다. IMediaSample::IsPreroll 메소드의 이행.

구문

HRESULT IsPreroll(void);

반환값

샘플이 프리로르산풀이라면 S_OK 를 돌려주어, 그 이외라면 S_FALSE 를 돌려준다.

주의

m_dwFlags 멤버 변수는 이 프로퍼티를 나타낸다.

CMediaSample::IsSyncPoint

CMediaSample 클래스

샘플의 시작이 동기 포인트인가 어떤가 확인한다. IMediaSample::IsSyncPoint 메소드의 이행.

구문

HRESULT IsSyncPoint(void);

반환값

샘플이 동기 포인트라면 S_OK 를 돌려주는, 그 이외라면 S_FALSE 를 돌려준다.

주의

m_dwFlags 멤버 변수는 이 프로퍼티를 나타낸다.

CMediaSample::SetActualDataLength

CMediaSample 클래스

버퍼내의 유효한 데이터의 길이를 설정한다. IMediaSample::SetActualDataLength 메소드의 이행.

구문

HRESULT SetActualDataLength(
    long lLen
);

파라미터

lLen
유효한 데이터의 길이, 바이트 단위.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
VFW_E_BUFFER_OVERFLOW | lLen 는 할당할 수 있었던 버퍼 사이즈보다 크다.

주의

이 메소드는 m_lActual 멤버 변수를 설정한다.

CMediaSample::SetDiscontinuity

CMediaSample 클래스

샘플이 데이터 스트림내에서 브레이크를 표시할지 어떨지를 설정한다. IMediaSample::SetDiscontinuity 메소드의 이행.

구문

HRESULT SetDiscontinuity(
    BOOL bDiscont
);

파라미터

bDiscont
이 샘플이 불연속인가 어떤가를 나타내는 불리언 값. TURE 라면 미디어 샘플은 전의 샘플과 불연속.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 불연속 프로퍼티를 나타내는 m_dwFlags 멤버 변수를 업데이트 한다.

CMediaSample::SetMediaTime

CMediaSample 클래스

샘플의 미디어 타임을 설정한다. IMediaSample::SetMediaTime 메소드의 이행.

구문

HRESULT SetMediaTime(
    LONGLONG *pStart,
    LONGLONG *pEnd
);

파라미터

pStart
미디어 시작 타임에의 포인터, 혹은 NULL .
pEnd
미디어 종료 타임에의 포인터, 혹은 NULL .

반환값

S_OK 를 돌려준다.

주의

미디어 종료 타임은 미디어 시작 타임보다 크지 않으면 안 된다. 부적절한 미디어 타임에는 NULL 를 사용하는 것.

pEnd 파라미터는 절대 미디어 타임을 나타내지만,m_MediaEnd 멤버 변수는 pStart 로부터의 오프셋(offset)로서 계산된다. 즉,m_MediaEnd = *pTimeEnd – *pTimeStart .

미디어 타임의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

CMediaSample::SetMediaType

CMediaSample 클래스

샘플의 미디어 타입을 설정한다. IMediaSample::SetMediaType 메소드의 이행.

구문

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pMediaType
);

파라미터

pMediaType
AM_MEDIA_TYPE 구조체에의 포인터.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공
E_OUTOFMEMORY | 메모리 부족

주의

이 메소드는 미디어 타입을 나타내는 m_pMediaType 미디어 변수와 미디어 타입이 변경되었는지 어떠했는지를 나타내는 m_dwFlags 멤버 변수 설정한다.

이 메소드는 AM_MEDIA_TYPE 구조체의 카피를 만든다.

CMediaSample::SetPointer

CMediaSample 클래스

메모리 버퍼에의 포인터를 설정한다.

구문

HRESULT SetPointer(
    BYTE *ptr,
    LONG cBytes
);

파라미터

ptr
호출원이 할당한 사이즈 cBytes 의 메모리 버퍼에의 포인터.
cBytes
버퍼의 사이즈, 바이트 단위.

반환값

S_OK 를 돌려준다.

주의

이 메소드에 의해 allocater는 샘플에 새로운 포인터를 세트 할 수 있다.

이 메소드는 IMediaSample 인터페이스를 통해 사용할 수 없다. 샘플을 생성 한 오브젝트는 (CMediaSample 를 통해) 이 메소드에 액세스 할 수 있지만, 다른 오브젝트는 액세스 할 수 없다.

CMediaSample::SetPreroll

CMediaSample 클래스

샘플이 프리로르산풀인가 어떤가를 설정한다. 프리로르산풀은 표시되어서는 안된다. IMediaSample::SetPreroll 메소드의 이행.

구문

HRESULT SetPreroll(
    BOOL bIsPreroll
);

파라미터

bIsPreroll
이것이 프리로르산풀인가 어떤가를 나타내는 불리언 값. TRUE 라면 이것은 프리로르산풀.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 프리로르프로파티를 나타내는 m_dwFlags 멤버 변수를 업데이트 한다.

CMediaSample::SetProperties

CMediaSample 클래스

샘플의 프로퍼티를 설정한다. 이 메소드는 IMediaSample2::SetProperties 를 이행 한다.

구문

HRESULT SetProperties(
    DWORD cbProperties,
    const BYTE *pbProperties
);

파라미터

cbProperties
세트 해야 할 프로퍼티 데이터의 길이, 바이트 단위.
pbProperties
사이즈 cbProperties 의 버퍼에의 포인터.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공
E_INVALIDARG | 부적절한 인수
E_OUTOFMEMORY | 메모리 부족
E_POINTER | NULL 포인터 인수

CMediaSample::SetSyncPoint

CMediaSample 클래스

샘플의 시작이 동기 포인트인가 어떤가를 설정한다. 이 메소드는 IMediaSample::SetSyncPoint 메소드를 이행 한다.

구문

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

파라미터

bIsSyncPoint
이것이 동기 포인트인가 어떤가를 나타내는 불리언 값. TRUE 라면 이것은 동기 포인트.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 동기 포인트 프로퍼티를 나타내는 m_dwFlags 멤버 변수를 업데이트 한다.

CMediaSample::SetTime

CMediaSample 클래스

샘플이 시작·종료하는 스트림 타임을 설정한다. IMediaSample::SetTime 메소드의 이행.

구문

HRESULT SetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

파라미터

pTimeStart
샘플이 시작 하는 스트림 타임에의 포인터, 100 나노초단위.
pTimeEnd
샘플이 시작 하는 스트림 타임에의 포인터, 100 나노초단위, 혹은 NULL .

반환값

S_OK 를 돌려준다.

주의

이 메소드는 타임 스탬프를 나타내는 m_Start 와 m_End 멤버 변수를 설정한다. 그것은 또 타임 스탬프가 유효한가 어떤가를 나타내는 m_dwFlags 멤버 변수도 업데이트 한다.

타임 스탬프의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.


CMediaType 클래스

CMediaType 클래스의 계층

미디어 타입을 관리하기 위한 클래스. 이 클래스는 AM_MEDIA_TYPE 구조체를 계승한다. 그것은 AM_MEDIA_TYPE 타입의 변수에 캐스트 될 수 있다.

선언 : Mtype.h

Public 메소드
CMediaType | constructor 메소드
~CMediaType | 소멸자 메소드
IsValid | 메이저 타입이 이 오브젝트에 할당 되고 있는지 어떤지를 확인한다.
Type | 메이저 타입을 취득한다.
SetType | 메이저 타입을 지정한다.
Subtype | 서브 타입을 취득한다.
SetSubtype | 서브 타입을 지정한다.
IsFixedSize | 샘플이 고정 사이즈나 가변 사이즈인지를 확인한다.
IsTemporalCompressed | 스트림이 시계열 압축을 사용하고 있을지 어떨지를 확인한다.
GetSampleSize | 샘플 사이즈를 취득한다.
SetSampleSize | 고정 샘플 사이즈를 지정한다, 혹은 샘플이 가변 사이즈를 가지는 것을 지정한다.
SetVariableSize | 샘플이 고정 사이즈를 가지지 않는 것을 지정한다.
SetTemporalCompression | 샘플이 시계열 압축을 사용해 압축되었는지 어떠했는지를 지정한다.
Format | 포맷 블록에의 포인터를 취득한다.
FormatLength | 포맷 블록의 길이를 취득한다.
SetFormatType | 포맷 타입을 지정한다.
FormatType | 포맷 타입을 취득한다.
SetFormat | 포맷 블록을 지정한다.
ResetFormatBuffer | 포맷 블록을 삭제한다.
AllocFormatBuffer | 포맷 블록의 메모리를 할당한다.
ReallocFormatBuffer | 포맷 블록에 새로운 사이즈를 재할인 맞히고 한다.
InitMediaType | 미디어 타입을 초기화한다.
MatchesPartial | 이 미디어 타입이 부분적으로 지정한 미디어 타입과 일치할지 어떨지를 확인한다.
IsPartiallySpecified | 미디어 타입이 부분적으로 지정되었는지 어떠했는지를 확인한다.
연산자
operator = | 미디어 타입을 카피하는 할당 연산자를 overload 한다.
operator == | 2 개의 CMediaType 오브젝트가 동일한 일을 테스트한다.
operator ! = | 2 개의CMediaType 오브젝트가 동일하지 않은 것을 테스트한다.

CMediaType::AllocFormatBuffer

CMediaType 클래스

포맷 블록의 메모리를 할당한다.

구문

BYTE* AllocFormatBuffer(
    ULONG length
);

파라미터

length
포맷 블록에 요구되는 사이즈, 바이트 단위.

반환값

성공이라면 새로운 블록에의 포인터를 돌려준다. 그렇지 않으면 NULL 를 돌려준다.

주의

메소드가 새로운 포맷 블록의 할당에 성공하면(자), 기존의 포맷 블록을 프리로 한다.

CMediaType::CMediaType

CMediaType 클래스

constructor　 　 메소드.

구문

CMediaType(void);

CMediaType(
    const GUID *majortype
);

CMediaType(
    const AM_MEDIA_TYPE& mtype
);

CMediaType(
    const CMediaType& cmtype
);

파라미터

majortype
메이저 타입 GUID 에의 포인터.
mtype
AM_MEDIA_TYPE 구조체에의 참조.
cmtype
CMediaType 오브젝트에의 참조.

주의

constructor　 　 은 InitMediaType 함수를 호출해, 미디어 타입을 초기화한다. majortype 파라미터가 지정되면(자), constructor　 　 은 메이저 타입을 GUID 로 초기화한다. mtype 나 cmtype 파라미터가 지정되면(자), constructor　 　 은 (포맷 블록을 포함한다) 미디어 타입 정보를 새로운 오브젝트에 카피한다.

CMediaType::~CMediaType

CMediaType 클래스

소멸자 메소드.

구문

~CMediaType(void);

주의

소멸자는 FreeMediaType 함수를 자기 자신으로 호출한다.

CMediaType::Format

CMediaType 클래스

포맷 블록에의 포인터를 취득한다.

구문

BYTE* Format(void) const;

반환값

pbFormat 멤버를 돌려준다.

CMediaType::FormatLength

CMediaType 클래스

포맷 블록의 길이를 취득한다.

구문

ULONG FormatLength(void) const;

반환값

cbFormat 멤버를 돌려준다.

CMediaType::FormatType

CMediaType 클래스

포맷 타입을 취득한다.

구문

const GUID *FormatType(void) const;

반환값

formattype 멤버에의 포인터를 돌려준다.

CMediaType::GetSampleSize

CMediaType 클래스

샘플 사이즈를 취득한다.

구문

ULONG GetSampleSize(void) const;

반환값

샘플 사이즈가 고정이라면, 바이트 단위의 샘플 사이즈를 돌려준다. 그렇지 않으면 제로를 돌려준다.

CMediaType::InitMediaType

CMediaType 클래스

미디어 타입을 초기화한다.

구문

void InitMediaType(void);

주의

이 메소드는 오브젝트의 메모리를 제로로 해, 고정 샘플 사이즈 프로퍼티를 TRUE 로 해, 샘플 사이즈를 1 으로 설정한다.

CMediaType::IsFixedSize

CMediaType 클래스

샘플이 고정 사이즈나 가변 사이즈인지를 확인한다.

구문

BOOL IsFixedSize(void) const;

반환값

bFixedSizeSamples 멤버의 값을 돌려준다.

CMediaType::IsPartiallySpecified

CMediaType 클래스

미디어 타입이 부분적으로 지정되었는지 어떠했는지를 확인한다. 메이저 타입, 서브 타입, 포맷 타입이 GUID_NILL 라면, 미디어 타입은 부분적 이다.

구문

BOOL IsPartiallySpecified(void) const;

반환값

미디어 타입이 부분적으로 지정되고 있다면 TRUE 를 돌려준다. 그렇지 않으면 FALSE 를 돌려준다.

주의

IPin::Connect 메소드는 부분적 미디어 타입을 허용 할 수 있다.

그 이행은 실제로는 서브 타입의 테스트는 아니다. 지정한 포맷 타입이 있으면, 비록 서브 타입이 GUID_NULL 여도, 미디어 타입은 부분적과는 해석되지 않는다.

CMediaType::IsTemporalCompressed

CMediaType 클래스

스트림이 시계열 압축을 사용하고 있을지 어떨지를 확인한다.

구문

BOOL IsTemporalCompressed(void) const;

반환값

bTemporalCompression 멤버의 값을 돌려준다.

CMediaType::IsValid

CMediaType 클래스

메이저 타입이 이 오브젝트에 할당 되고 있는지 어떤지를 확인한다.

구문

BOOL IsValid(void) const;

반환값

메이저 타입이 이 오브젝트에 할당 되고 있다면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

주의

디폴트에서는 CMediaType 오브젝트는 GUID_NULL 의 메이저 타입으로 초기화된다. 이 메소드를 호출해, 오브젝트가 올바르게 초기화되었는지 어떠했는지를 확인하는 것.

CMediaType::MatchesPartial

CMediaType 클래스

이 미디어 타입이 부분적으로 지정한 미디어 타입과 일치할지 어떨지를 확인한다.

구문

BOOL MatchesPartial(
    const CMediaType *ppartial
    ) const;

파라미터

ppartial
일치해야 할 미디어 타입에의 포인터.

반환값

미디어 타입이 일치하면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

주의

ppartial 에 의해 지정되는 미디어 타입은 메이저 타입, 서브 타입, 포맷 타입에 GUID_NULL 값을 취할 수 있다. GUID_NULL 값의 멤버는 테스트되지 않는다. (기본적으로는, GUID_NULL 는 와일드 카드로서 일한다. ) GUID_NULL 이외의 값을 가지는 멤버는 일치해야 할 미디어 타입과 일치해야 한다.

CMediaType::ReallocFormatBuffer

CMediaType 클래스

포맷 블록에 새로운 사이즈를 재할인 맞히고 한다.

구문

BYTE* ReallocFormatBuffer(
    ULONG length
);

파라미터

length
포맷 블록에 요구되는 새로운 사이즈, 바이트 단위. 제로보다 큰 값이 아니면 안된다.

반환값

성공하면 새로운 블록에의 포인터를 돌려준다. 그렇지 않으면, 낡은 포맷 블록에의 포인터나 NULL 를 돌려준다.

주의

이 메소드는 새로운 포맷 블록을 할당한다. 그것은 기존의 포맷 블록을 새로운 포맷 블록으로 할 수 있을 뿐(만큼) 카피한다. 새로운 블록이 기존의 블록보다 작으면, 기존의 블록은 절약할 수 있다. 새로운 블록이 보다 크면, 미정도리의 추가 스페이스를 가진다. 그곳에서는 명시적으로 제로가 세트 되고 있는 것은 아니다.

CMediaType::ResetFormatBuffer

CMediaType 클래스

포맷 블록을 삭제한다.

구문

void ResetFormatBuffer(void);

CMediaType::SetFormat

CMediaType 클래스

포맷 블록을 지정한다

구문

BOOL SetFormat(
    BYTE *pFormat,
    ULONG length
);

파라미터

pFormat
포맷 블록이 들어가는 메모리의 블록에의 포인터.
length
포맷 블록의 사이즈, 바이트 단위.

반환값

성공이라면 TRUE, 에러가 일어났다면 FALSE 를 돌려준다.

주의

이 메소드는 pFormat 에 의해 지정된 포맷 블록을 카피한다. 포맷 타입을 설정하려면 SetFormatType 메소드를 호출하는 것.

CMediaType::SetFormatType

CMediaType 클래스

포맷 타입을 지정한다.

구문

void SetFormatType(
    const GUID *pformattype
);

파라미터

pformattype
포맷 타입을 지정하는 GUID 에의 포인터.

주의

이 메소드는 formattype 멤버를 설정한다. 포맷 타입은 포맷 블록의 레이아웃을 정의한다. 예를 들어, 포맷 타입이 FORMAT_VideoInfo 라면, 포맷 블록에는 VIDEOINFOHEADER 가 들어가야 하는 것이다. 포맷 블록을 설정하려면 ,SetFormat 를 호출하는 것. 호출원래는 포맷 블록이 포맷 타입과 일치하는 것을 보증할 책임이 있다.

CMediaType::SetSampleSize

CMediaType 클래스

고정 샘플 사이즈를 지정한다, 혹은 샘플이 가변 사이즈를 가지는 것을 지정한다.

구문

void SetSampleSize(
    ULONG sz
);

파라미터

sz
샘플 사이즈 (바이트 단위), 혹은 제로.

주의

sz 가 제로라면, 미디어 타입은 가변의 샘플 사이즈를 사용한다. 그렇지 않으면, 샘플 사이즈는 sz 바이트 고정이다.

CMediaType::SetSubtype

CMediaType 클래스

서브 타입을 지정한다.

구문

void SetSubtype(
    const GUID *psubtype
);

파라미터

psubtype
서브 타입을 지정하는 GUID 에의 포인터.

CMediaType::SetTemporalCompression

CMediaType 클래스

스트림이 시계열 압축을 사용하고 있을지 어떨지를 확인한다.

구문

void SetTemporalCompression(
    BOOL bCompressed
);

파라미터

bCompressed
스트림이 시계열 압축을 사용하고 있을지 어떨지를 지정하는 불리언 값. 스트림이 시계열 압축을 사용하고 있다면 TRUE 값이 세트 된다.

주의

이 메소드는 bTemporalCompression 멤버를 설정한다.

CMediaType::SetType

CMediaType 클래스

메이저 타입을 지정한다.

구문

void SetType(
    const GUID *ptype
);

파라미터

ptype
메이저 타입을 지정하는 GUID 에의 포인터.

CMediaType::SetVariableSize

CMediaType 클래스

샘플이 고정 사이즈를 가지지 않는 것을 지정한다.

구문

void SetVariableSize(void);

주의

이 메소드는 bFixedSizeSamples 멤버를 FALSE 로 설정한다. 이 다음에 CMediaType::GetSampleSize 메소드를 호출하면 제로를 돌려준다.

CMediaType::Subtype

CMediaType 클래스

서브 타입을 취득한다.

구문

const GUID *Type(void) const;

반환값

subtype 멤버에의 포인터를 돌려준다.

CMediaType::Type

CMediaType 클래스

메이저 타입을 취득한다.

구문

const GUID *Type(void) const;

반환값

majortype 멤버에의 포인터를 돌려준다.

CMediaType::operator =

CMediaType 클래스

미디어 타입을 카피하는 할당 연산자를 overload 한다.

구문

CMediaType& operator=(
    const CMediaType& cmtype
);

CMediaType& operator=(
    const AM_MEDIA_TYPE& mtype
);

파라미터

cmtype
CMediaType 오브젝트에의 참조.
mtype
AM_MEDIA_TYPE 구조체에의 참조.

반환값

오브젝트에의 참조를 돌려준다.

CMediaType::operator ==

CMediaType 클래스

2 개의 CMediaType 오브젝트가 동일한 일을 테스트한다.

구문

inline BOOL operator==(
    const CMediaType& rt
) const;

파라미터

rt
비교하는 CMediaType 오브젝트에의 참조.

반환값

rt 가 이 오브젝트와 동일하면 TRUE 를 돌려준다. 그렇지 않으면 FALSE 를 돌려준다.

CMediaType::operator ! =

CMediaType 클래스

2 개의CMediaType 오브젝트가 동일하지 않은 것을 테스트한다.

구문

BOOL operator! =(
    const CMediaType& rt
) const;

파라미터

rt
비교하는 CMediaType 오브젝트에의 참조.

반환값

rt 가 이 오브젝트와 등 구 없으면 TRUE 를 돌려준다. 그렇지 않으면 FALSE 를 돌려준다.


CMemAllocator 클래스

CMemAllocator class hierarchy

IMemAllocator 인터페이스를 지원 하는 allocater를 이행 한다.

선언 : Amfilter.h

이 클래스는 CBaseAllocator 로부터 파생한다. allocater의 상세한 것에 대하여는,CBaseAllocator 의 문서를 참조할것.

Protected 멤버 변수
m_pBuffer | 버퍼가 들어가는 메모리 블록에의 포인터.
Protected 메소드
Free | 데코밋트 조작동안에 불려 간다.
ReallyFree | 버퍼의 메모리를 해방한다.
Alloc | 버퍼에 메모리를 할당한다.
Public 메소드
CMemAllocator | constructor 메소드.
~CMemAllocator | 소멸자 메소드.
CreateInstance | CMemAllocator 클래스의 새로운 인스턴스를 생성 한다.
IMemAllocator 메소드
SetProperties | 할당해야 할 버퍼의 수와 각 버퍼의 사이즈를 지정한다.

CMemAllocator.m_pBuffer

CMemAllocator 클래스

버퍼가 들어가는 메모리 블록에의 포인터.

구문

LPBYTE m_pBuffer;

주의

샘플 버퍼는 이 포인터로부터의 오프셋(offset)로서 계산된다.

CMemAllocator::Alloc

CMemAllocator 클래스

버퍼에 메모리를 할당한다.

구문

HRESULT Alloc(void);

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_SIZENOTSET | 버퍼 요구가 세트 되지 않았다.

주의

이 메소드는 CBaseAllocator::Commit 메소드로부터 불려 간다. 그것은 SetProperties 메소드로 주어진 버퍼 요구에 충분한 연속적인 메모리 블록을 할당한다.

CMemAllocator::CMemAllocator

CMemAllocator 클래스

constructor　 　 메소드.

구문

CMemAllocator(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
);

파라미터

pName
allocater의 이름이 들어가는 캐릭터 라인에의 포인터.
pUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되고 있다면, 집성 하고 있는 오브젝트의 IUnknown 인터페이스에의 포인터를 건네준다. 그렇지 않으면, 이 파라미터에는 NULL 를 설정한다.
phr
메소드의 성공·실패를 나타내는 HRESULT 값을 받는 변수에의 포인터.

CMemAllocator::~CMemAllocator

CMemAllocator 클래스

소멸자 메소드.

구문

~CMemAllocator(void);

구문

이 메소드는 base class 소멸자를 오버라이드(override) 해,Decommit 와 ReallyFree 를 호출한다.

CMemAllocator::CreateInstance

CMemAllocator 클래스

CMemAllocator 클래스의 새로운 인스턴스를 생성 한다.

구문

static CUnknown *CreateInstance(
    LPUNKNOWN pUnk,
    HRESULT *phr
);

파라미터

pUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되고 있다면, 집성 하고 있는 오브젝트의 IUnknown 인터페이스에의 포인터를 건네준다. 그렇지 않으면, 이 파라미터에는 NULL 를 설정한다.
phr
메소드의 성공·실패를 나타내는 HRESULT 값을 받는 변수에의 포인터.

반환값

CUnknown 오브젝트로서 타입 되는 새로운 CMemAllocator 오브젝트에의 포인터를 돌려준다.

CMemAllocator::Free

CMemAllocator 클래스

데코밋트 조작동안에 호출한다.

구문

void Free(void);

주의

이 메소드는 데코밋트 조작동안에 불려 가는 순수 가상 메소드 CBaseAllocator::Free 를 오버라이드(override) 한다. CMemAllocator 클래스에서는, 이 메소드는 아무것도 하지 않는다. 메모리는 소멸자 메소드로 ReallyFree 메소드를 호출하는 것으로 프리가 된다.

CMemAllocator::ReallyFree

CMemAllocator 클래스

버퍼의 메모리를 해방한다

구문

void ReallyFree (void);

주의

CMemAllocator 클래스는 이 오브젝트가 삭제될 때까지 메모리를 보관 유지한다.

CMemAllocator::SetProperties

CMemAllocator 클래스

할당해야 할 버퍼의 수와 각 버퍼의 사이즈를 지정한다.

구문

HRESULT SetProperties(
    ALLOCATOR_PROPERTIES *pRequest,
    ALLOCATOR_PROPERTIES *pActual
);

파라미터

pRequest
버퍼 요구를 넣는 ALLOCATOR_PROPERTIES 구조체에의 포인터.
pActual
실제의 버퍼 프로퍼티를 받는 ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_ALREADY_COMMITTED | 필터가 액티브한 동안은 할당할 수 있었던 메모리를 변경할 수 없다.
VFW_E_BADALIGN | 부적절한 인수가 지정되었다.
VFW_E_BUFFERS_OUTSTANDING | 1 개(살) 혹은 그 이상의 버퍼가 아직 액티브.

주의

이 메소드는 CBaseAllocator::SetProperties 메소드를 오버라이드(override) 한다.

ALLOCATOR_PROPERTIES 구조체의 cbAlign 멤버에 의해 지정되는 버퍼의 alignment는 2 의 거듭제곱이 아니면 안된다.


CMsg 클래스

CMsgThread 클래스는, 요구를 직접 송신하는 대신에, 비동기적으로 송신할 수 있는 워커 thread의 지원을 제공한다. CAMThread 클래스는, 단일의 요구를 송신할 수 있는 워커 thread를 제공한다. 한 번에 요구를 실시할 수가 있는 클라이언트는 1 개 뿐이므로, 클라이언트는 워커 thread가 요구의 처리를 완료할 때까지 블록 한다. 대조적으로, CMsgThread 클래스는, 임의의 수의 요구를 송신할 수 있는 워커 thread를 제공한다. CMsg 오브젝트의 포맷의 요구는, 큐에 넣어져 차례로, 비동기적으로 실행된다. 응답이나 반환값은 수신되지 않는다.

데이터 멤버

dwFlags | 요구 코드에의 플래그 파라미터.
lpParam | 파라미터 또는 반환값으로서 워커 thread가 필요로 하는 데이터. 이 데이터는, 큐에 넣는 처리가 완료한 다음에도 참조되므로, 스택 베이스여서는 안 된다.
pEvent | 워커 thread가 처리의 완료를 통지하기 위해서 송신할 수 있는 이벤트 오브젝트.
uMsg | thread 클래스의 클라이언트에 의해 정의되어 오버라이드(override) 된 워커 thread 함수에 의해 인식되는 요구 코드.

멤버 함수

CMsg CMsg 오브젝트를 생성 한다.

CMsg::CMsg

CMsg 클래스

CMsg 오브젝트를 생성 한다.

구문

CMsg(

  UINT u,

  DWORD dw,

  LPVOID lp,

  CAMEvent *pEvent

  );

파라미터

u
thread 클래스의 클라이언트에 의해 정의되어 오버라이드(override) 된 워커 thread 함수에 의해 인식되는 요구 코드.
dw
요구 코드에의 플래그 파라미터.
lp
파라미터 또는 반환값으로서 워커 thread가 필요로 하는 데이터에의 포인터. 이 데이터는, 큐에 넣는 처리가 완료한 다음에도 참조되므로, 스택 베이스여서는 안 된다.
pEvent
워커 thread가 처리의 완료를 통지하기 위해서 송신할 수 있는 이벤트 오브젝트에의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는,CMsgThread 워커 thread가 처리의 대상으로 하는 요구를 저장 한다. 모든 파라미터는, 이 메세지가 처리될 때, 파라미터로서 워커 thread 함수에게 건네진다. 파라미터의 의미는, 워커 thread를 호출하는 클라이언트 함수와 워커 thread의 실행 함수를 제공하는 상속 클래스로 정의된다.


CMsgThread 클래스

CMsgThread 클래스는, 요구를 비동기적으로 완료하기 위해서, 큐를 처리하는 thread의 큐에 넣는 워커 thread 클래스이다. 이 클래스를 사용하려면 , 이 클래스에서 클래스를 파생시켜,CMsgThread::ThreadMessageProc 멤버 함수를 오버라이드(override) 한다. ThreadMessageProc 멤버 함수는 각 요구를 실행한다. 클라이언트 함수와 ThreadMessageProc 멤버 함수는,CMsg 오브젝트의 파라미터에 대해 공통의 정의를 공유해야 한다.

네고시에이트메카니즘에 의해, 워커 thread에 종료가 지시받는다. 보통, 이것은 CMsg 클래스의 uMsg 메세지 코드의 값이다.

상속 클래스의 소멸자로부터 이 메세지를 송신해, 상속 클래스의 파기가 완료하기 전에 CMsgThread::WaitForThreadExit 멤버 함수를 호출하는 것을 추천 한다.

Protected 데이터 멤버

m_hSem | 통지에 사용하는 핸들을 나타낸다.
m_Lock | 리스트에의 액세스를 보호한다.
m_lWaiting | 빈thread를 대기하는 것을 나타낸다.
m_ThreadQueue | CMsgThread::GetThreadMsg 멤버 함수를 오버라이드(override) 해, 이 큐 이외를 블록 한다.

멤버 함수

CMsgThread | CMsgThread 오브젝트를 생성 한다.
CreateThread | thread를 생성 한다.
GetThreadHandle | thread 핸들을 취득한다.
GetThreadID | thread의 식별자를 취득한다.
GetThreadPriority | 현재의 thread의 우선도를 취득한다.
PutThreadMsg | 워커 thread에 의해 실행되는 요구를 큐에 넣는다.
ResumeThread | 워커 thread의 처리를 속행한다.
SetThreadPriority | thread의 우선도를 새로운 값으로 설정한다.
SuspendThread | 실행중의 thread의 처리를 포즈 한다.
WaitForThreadExit | CMsgThread::SuspendThread 멤버 함수를 호출한 후, thread가 종료할 때까지 블록 한다.

오버라이드(override) 가능한 멤버 함수

GetThreadMsg | 요구를 저장 하는 큐에 넣어진 CMsg 오브젝트를 취득한다.
OnThreadInit | thread에 대한 초기화를 제공한다.
ThreadMessageProc | 요구를 처리한다. 이것은 순수 가상 멤버 함수이다.

CMsgThread::CMsgThread

CMsgThread 클래스

CMsgThread 오브젝트를 생성 한다.

구문

CMsgThread(void);

반환값

반환값 없음.

주의

메세지 thread 오브젝트를 생성 해도, thread는 자동적으로 생성 되지 않는다. thread를 생성 하려면 ,CMsgThread::CreateThread 멤버 함수를 호출할 필요가 있다.

CMsgThread::CreateThread

CMsgThread 클래스

thread를 생성 한다.

구문

BOOL CreateThread(void);

반환값

다음의 몇개의 값을 돌려준다.
TRUE | thread가 올바르고 생성 되었다.
FALSE | thread가 올바르고 생성 되지 않았다.

주의

thread는 루프 처리를 실행해, 요구가 CMsgThread::PutThreadMsg 멤버 함수에 의해 큐에 넣어질 때까지 블록 한 후, 각 메세지에 대해 CMsgThread::ThreadMessageProc 멤버 함수를 호출한다.

CMsgThread::GetThreadHandle

CMsgThread 클래스

CMsgThread 오브젝트내의 thread의 핸들을 취득한다.

구문

HANDLE GetThreadHandle(void);

반환값

thread 핸들을 돌려준다.

주의

thread 핸들은,WaitForMultipleObjects 등의 Microsoft® Win32® 어플리케이션 프로그래밍 인터페이스 (API) 함수에 건네줄 수가 있다. thread 핸들은, thread가 종료 하면 통지제가 된다.

CMsgThread::GetThreadID

CMsgThread 클래스

thread의 식별자를 취득한다.

구문

DWORD GetThreadID(void);

반환값

프라이빗 데이터 멤버 m_ThreadId 를 돌려준다.

주의

이 함수는, 워커 thread의 Microsoft Win32 식별자를 돌려준다. 워커 thread 또는 클라이언트 thread의 어느 쪽인가에 붙어, 이 멤버 함수를 호출할 수가 있다.

CMsgThread::GetThreadMsg

CMsgThread 클래스

요구를 저장 하는 큐에 넣어진 CMsg 오브젝트를 취득한다.

구문

void virtual GetThreadMsg(
CMsg *msg
    );

파라미터

msg
할당할 수 있었던 CMsg 오브젝트에의 포인터.

주의

이 멤버 함수는, 워커 thread의 프라이빗 함수 ThreadProc 로부터 불려 가, 다음의 멤버 함수를 취득한다. msg 파라미터는, 큐내의 다음의 요구에의 파라미터가 저장 되는, 할당할 수 있었던 CMsg 오브젝트를 가리킬 필요가 있다. 큐에 넣어진 요구가 없는 경우, 이 멤버 함수는 CMsgThread::PutThreadMsg 를 호출해, 다음의 요구가 큐에 넣어질 때까지 블록 한다.

CMsgThread::GetThreadPriority

CMsgThread 클래스

Microsoft Win32 GetThreadPriority 함수를 사용해, 현재의 워커 thread의 우선도를 취득한다.

구문

int GetThreadPriority(void);

반환값

thread의 우선도를 정수로서 돌려준다.

CMsgThread::OnThreadInit

CMsgThread 클래스

thread에 대한 초기화를 제공한다.

구문

virtual void OnThreadInit(void);

반환값

반환값 없음.

주의

thread의 기동시에 독자적인 초기화를 실행하는 경우는, 이 함수를 오버라이드(override) 한다.

CMsgThread::PutThreadMsg

CMsgThread 클래스

워커 thread에 의해 실행되는 요구를 큐에 넣는다.

구문

void PutThreadMsg(
UINT uMsg,
DWORD dwMsgFlags,
LPVOID lpMsgParam,
CAMEvent *pEvent = NULL
    );

파라미터

uMsg
요구 코드.
dwMsgFlags
옵션의 플래그 파라미터.
lpMsgParam
추가의 파라미터 또는 반환값을 저장 하는 데이터 블록에의 옵션의 포인터. 정적 또는 heap에 의해 할당할 수 있지 않으면 안되어, 자동적이고 있어서는 안된다.
pEvent
완료시에 통지제가 되는 이벤트 오브젝트에의 옵션의 포인터.

반환값

반환값 없음.

주의

이 멤버 함수는, 워커 thread에 의해 실행되는 요구를 큐에 넣는다. 이 멤버 함수의 파라미터는 CMsg 오브젝트로서 큐에 넣어져 워커 thread의 CMsgThread::ThreadMessageProc 멤버 함수에게 건네진다. 이 멤버 함수는 요구를 큐에 넣은 후, 즉시 돌아와, thread가 요구를 실행할 때까지 대기하지 않는다. 상속 클래스의 CMsgThread::ThreadMessageProc 멤버 함수로 4 개의 파라미터를 정의한다.

이 멤버 함수는 multi-thread로 안전한 리스트를 사용하므로, 다른 thread로부터 이 멤버 함수를 안전하게 복수 호출할 수가 있다.

CMsgThread::ResumeThread

CMsgThread 클래스

Microsoft Win32 ResumeThread 함수를 사용해, 이전에 CMsgThread::SuspendThread 멤버 함수를 호출한 후의 워커 thread의 처리를 속행한다.

구문

DWORD ResumeThread(void);

반환값

이 멤버 함수가 성공했을 경우, 반환값은 이전의 thread의 포즈 카운트이다. 이 멤버 함수가 실패했을 경우, 반환값은 0xFFFFFFFF 이다. 확장 에러 정보를 취득하려면 , Microsoft Win32 GetLastError 함수를 호출한다.

CMsgThread::SetThreadPriority

CMsgThread 클래스

Microsoft Win32 SetThreadPriority 함수를 사용해, thread의 우선도를 새로운 값으로 설정한다.

구문

BOOL SetThreadPriority(
int nPriority
    );

파라미터

nPriority
thread의 우선도.

반환값

다음의 몇개의 값을 돌려준다.
TRUE | 우선도가 올바르게 설정되었다.
FALSE | 우선도가 설정되지 않았다.

주의

클라이언트 및 워커 thread는 이 멤버 함수를 호출할 수가 있다.

CMsgThread::SuspendThread

CMsgThread 클래스

Microsoft Win32 SuspendThread 함수를 사용해, 실행중의 thread의 처리를 포즈 한다.

구문

DWORD SuspendThread(void);

반환값

이 멤버 함수가 성공했을 경우, 반환값은 이전의 thread의 포즈 카운트이다. 이 멤버 함수가 실패했을 경우, 반환값은 0xFFFFFFFF 이다. 확장 에러 정보를 취득하려면 , Microsoft Win32 GetLastError 함수를 호출한다.

주의

클라이언트는 이 멤버 함수를 호출해, 워커 thread의 처리를 포즈 한다. 워커 thread는 포즈 되어CMsgThread::ResumeThread 멤버 함수가 다음에 불려 갈 때까지 실행되지 않는다.

CMsgThread::ThreadMessageProc

CMsgThread 클래스

요구를 처리한다. 이것은 순수 가상 멤버 함수이다.

구문

virtual LRESULT ThreadMessageProc(
UINT uMsg,
DWORD dwFlags,
LPVOID lpParam,
CAMEvent *pEvent
    );

파라미터

uMsg
요구 코드.
dwFlags
요구에 대한 옵션의 플래그 파라미터.
lpParam
추가의 데이터 또는 돌아와 데이터 블록에의 옵션의 포인터.
pEvent
이벤트 오브젝트에의 옵션의 포인터.

반환값

반환값이 0 이외의 경우, thread는 종료한다. 종료 요구가 최근 처리되었던 바로 직후인 경우 이외는, 0 을 돌려준다.

주의

이 순수 가상 함수는 상속 클래스로 오버라이드(override) 해야 한다. 이 멤버 함수는,CMsgThread::PutThreadMsg 멤버 함수의 호출에 의해 큐에 넣어진 각 요구에 대해 1 회 불려 간다.

이 멤버 함수는 4 개의 파라미터를 정의한다. 보통,uMsg 파라미터를 사용해 요구를 지정해, 다른 3 개의 파라미터는 옵션의 추가 파라미터이다. 호출원어플리케이션으로 필요한 경우는,pEvent 파라미터로 CAMEvent 오브젝트에의 포인터를 지정할 수 있다. 이 이벤트는, 이벤트를 처리한 다음에, 다음과 같은 식을 사용해 설정할 수 있다.

pEvent->SetEvent

워커 thread에 종료를 지시하기 위해서, 1 개의 요구 코드를 별로 설정해야 한다. 이 요구를 수신하면(자), 이 멤버 함수로부터 1 을 돌려준다. 워커 thread를 종료하지 않는 경우는 0 을 돌려준다.

CMsgThread::WaitForThreadExit

CMsgThread 클래스

thread가 종료할 때까지 블록 한다.

구문

BOOL WaitForThreadExit(
LPDWORD lpdwExitCode
    );

파라미터

lpdwExitCode
thread에 의해 돌려주어진 종료 코드에의 포인터.

반환값

TRUE 또는 FALSE 의 어느쪽이든을 돌려준다. 이러한 의미는 오버라이드(override) 된 CMsgThread::ThreadMessageProc 멤버 함수를 제공하는 클래스 및 호출해 원의 멤버 함수에 의해 정해진다.

주의

상속 클래스의 파기를 완료하기 전에, 워커 thread가 완전하게 종료하고 있는 것을 확인한다. 그렇게 하지 않으면 동적 링크 라이브러리 (DLL)가 프로세스의 address 공간으로부터 언로드된 후도 thread가 실행되게 된다. 종료하지 않고 남은 명령이 반환값 1 개의 명령이어도, 이것은 예외를 발생시킨다. thread가 종료하고 있는 것을 확인하는 확실한 방법은, ( CMsgThread::PutThreadMsg 멤버 함수에 송신되는, 프라이빗에 네고시에이트 한 CMsg 오브젝트를 사용해) thread에 종료하도록(듯이) 통지한 후, 이 멤버 함수를 호출하는 방법 뿐이다. 상속 클래스의 소멸자로 이 처리를 실시할 필요가 있다.


COARefTime 클래스

COARefTime 클래스의 계층

초와 100 나노초의 사이에 기준 시간의 단위를 변환한다.

선언 : Ctlutil.h

이 클래스는 오토메이션 호환의 기준 타임과 C/C++ 호환의 기준 타임의 변환을 실시한다. 오토메이션 호환의 인터페이스는 double 값을 사용해 초에 시간을 표현한다. 다른 인터페이스는 64 비트 LONGLONG 값을 사용해 100 나노초단위로 시간을 표현한다. 이러한 값에는 다음의 타입이 정의되고 있다 :

typedef LONGLONG  REFERENCE_TIME;
typedef double    REFTIME;

필터는 COARefTime 클래스를 사용해 이 2 개의 포맷간의 변환이 가능하다. 이 클래스는 CRefTime 클래스로부터 파생한다.

멤버 함수

Public Methods
COARefTime | constructor 메소드.
연산자
double | 기준 타임을 double 값으로 변환한다.
REFERENCE_TIME | 기준 타임을 REFERENCE_TIME 값으로 취득한다.
Operator = | 새로운 기준 타임을 할당 한다.
Operator == | 2 개의 기준 타임이 동일한 일을 테스트한다.
Operator ! = | 2 개의 기준 타임이 동일하지 않은 것을 테스트한다.
Operator < | 1 개의 기준 타임이 이제(벌써) 1 개(살)보다 작은지 어떤지를 테스트한다.
Operator > | 1 개의 기준 타임이 이제(벌써) 1 개(살)보다 큰지 어떤지를 테스트한다.
Operator <= | 1 개의 기준 타임이 이제(벌써) 1 개의 기준 타임 이하인가 어떤가를 테스트한다.
Operator >= | 1 개의 기준 타임이 이제(벌써) 1 개의 기준 타임 이상인가 어떤가를 테스트한다.
Operator + | 2 개의 기준 타임을 가산한다.
Operator – | 1 개의 기준 타임부터 이제(벌써) 1 개의 기준 타임을 감산한다.
Operator += | 2 개의 기준 타임을 가산해, 이 오브젝트에 그 결과를 설정한다.
Operator –= | 1 개의 기준 타임부터 이제(벌써) 1 개의 기준 타임을 감산해, 이 오브젝트에 그 결과를 설정한다.
Operator * | 기준 타임을 곱셈한다.
Operator / | 기준 타임을 나눗셈 한다.

COARefTime::COARefTime

COARefTime 클래스

constructor　 　 메소드.

구문

COARefTime(void);

COARefTime(
    CRefTime crt
);

COARefTime(
    REFERENCE_TIME t
);

COARefTime(
    double d
);

파라미터

crt
기준 타임을 나타내는 CRefTime 오브젝트.
t
100 나노초단위에서의 기준 타임을 나타내는 REFERENCE_TIME 값.
d
초단위에서의 기준 타임을 나타내는 double 값

주의

디폴트에서는 기준 타임은 제로.

COARefTime::double

COARefTime 클래스

기준 타임을 double 값으로 변환한다.

구문

operator double();

반환값

기준 타임을 초단위로 돌려준다.

COARefTime::REFERENCE_TIME

COARefTime 클래스

기준 타임을 REFERENCE_TIME 값으로 취득한다

구문

operator REFERENCE_TIME();

반환값

기준 타임을 100 나노초단위로 돌려준다.

COARefTime::Operator =

COARefTime 클래스

새로운 기준 타임을 할당 한다.

구문

COARefTime& operator=(
    const double& rd
);

COARefTime& operator=(
    const REFERENCE_TIME& rt
);

파라미터

rd
초단위의 새로운 기준 타임을 나타내는 double 값에의 참조.
rt
100 나노초단위의 새로운 기준 타임을 나타내는 REFERENCE_TIME 값에의 참조

반환값

오브젝트에의 참조를 돌려준다.

COARefTime::Operator ==

COARefTime 클래스

2 개의 기준 타임이 동일한 일을 테스트한다.

구문

BOOL operator==(
    const COARefTime& rt
);

파라미터

rt
비교하는 COARefTime 오브젝트에의 참조.

반환값

2 개의 오브젝트가 동일하면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

COARefTime::Operator ! =

COARefTime 클래스

2 개의 기준 타임이 동일하지 않은 것을 테스트한다.

구문

BOOL operator! =(
    const COARefTime& rt
);

파라미터

rt
비교하는 COARefTime 오브젝트에의 참조.

반환값

2 개의 오브젝트가 동일하지 않으면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

COARefTime::Operator <

COARefTime 클래스

1 개의 기준 타임이 이제(벌써) 1 개(살)보다 작은지 어떤지를 테스트한다.

구문

BOOL operator < (
    const COARefTime& rt
);

파라미터

rt
비교하는 COARefTime 오브젝트에의 참조.

반환값

이 오브젝트가 엄밀하게 rt 보다 작으면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

COARefTime::Operator >

COARefTime 클래스

1 개의 기준 타임이 이제(벌써) 1 개(살)보다 큰지 어떤지를 테스트한다.

구문

BOOL operator > (
    const COARefTime& rt
);

파라미터

rt
비교하는 COARefTime 오브젝트에의 참조.

반환값

이 오브젝트가 엄밀하게 rt 보다 크면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

COARefTime::Operator >=

COARefTime 클래스

1 개의 기준 타임이 이제(벌써) 1 개의 기준 타임 이상인가 어떤가를 테스트한다.

구문

BOOL operator >= (
    const COARefTime& rt
);

파라미터

rt
비교하는 COARefTime 오브젝트에의 참조.

반환값

이 오브젝트가 rt 이상이라면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

COARefTime::Operator <=

COARefTime 클래스

1 개의 기준 타임이 이제(벌써) 1 개의 기준 타임 이하인가 어떤가를 테스트한다.

구문

BOOL operator <= (
    const COARefTime& rt
);

파라미터

rt
비교하는 COARefTime 오브젝트에의 참조.

반환값

이 오브젝트가 rt 이하라면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

COARefTime::Operator +

COARefTime 클래스

2 개의 기준 타임을 가산한다.

구문

COARefTime operator+(
    const COARefTime& rt
);

파라미터

rt
가산하는 COARefTime 오브젝트에의 참조.

반환값

기준 타임의 가산 결과와 동일한 COARefTime 오브젝트를 돌려준다.

COARefTime::Operator –

COARefTime 클래스

1 개의 기준 타임부터 이제(벌써) 1 개의 기준 타임을 감산한다.

구문

COARefTime operator-(
    const COARefTime& rt
);

파라미터

rt
감산하는 COARefTime 오브젝트에의 참조.

반환값

기준 타임의 차이와 동일한 COARefTime 오브젝트를 돌려준다.

COARefTime::Operator +=

COARefTime 클래스

2 개의 기준 타임을 가산해, 이 오브젝트에 그 결과를 설정한다.

구문

COARefTime& operator+=(
    const COARefTime& rt
);

파라미터

rt
가산하는 COARefTime 오브젝트에의 참조.

반환값

오브젝트에의 참조를 돌려준다.

COARefTime::Operator –=

COARefTime 클래스

1 개의 기준 타임부터 이제(벌써) 1 개의 기준 타임을 감산해, 이 오브젝트에 그 결과를 설정한다.

구문

COARefTime& operator-=(
    const COARefTime& rt
);

파라미터

rt
감산하는 COARefTime 오브젝트에의 참조.

반환값

오브젝트에의 참조를 돌려준다.

COARefTime::Operator *

COARefTime 클래스

기준 타임을 곱셈한다.

구문

COARefTime operator*(
    LONG l
);

파라미터

l
곱셈하는 값

반환값

이 오브젝트와 l 의 곱셈 결과와 동일한 새로운 COARefTime 오브젝트를 돌려준다.

COARefTime::Operator /

COARefTime 클래스

기준 타임을 나눗셈 한다.

구문

COARefTime operator/(
    LONG l
    );

파라미터

l
나눗셈 하는 값

반환값

이 오브젝트와 l 의 나눗셈 결과와 동일한 새로운 COARefTime 오브젝트를 돌려준다.


COutputQueue 클래스

COutputQueue 클래스의 계층

미디어 샘플을 출력하는 큐를 이행 한다.

선언 : Outputq.h

이 클래스에 의해 출력 핀은 샘플을 비동기에게 출력할 수가 있다. 샘플은 큐에 놓여져 워커 thread는 그것을 입력 핀에 출력한다. 큐는 새로운 세그먼트(segment), 엔드 오브 스트림 통지, 혹은 플래시 처리를 나타내는 컨트롤 메세지도 보관 유지한다.

이 클래스를 사용하려면 , 필터의 출력 핀 마다 COutputQueue 오브젝트를 생성 하는 것. constructor　 　 메소드로 그 출력 핀에 접속하는 입력 핀을 지정하는 것. 이 클래스의 사용중은, 출력 핀은 직접 입력 핀을 호출할 수가 없다. 대신에, 이하의 겉(표)에 나타나고 있도록(듯이) COutputQueue 의 대응하는 메소드를 호출한다 :

Pin 메소드 | COutputQueue 메소드
IPin::BeginFlush | BeginFlush
IPin::EndFlush | EndFlush
IPin::EndOfStream | EOS
IPin::NewSegment | NewSegment
MemInputPin::Receive | Receive
MemInputPin::ReceiveMultiple | ReceiveMultiple

옵션으로서 COutputQueue 오브젝트를 구성해, 워커 thread를 사용하지 않고 동기를 취해 샘플을 출력할 수가 있다. 오브젝트는 런타임시에, 입력 핀 상태를 기본으로 워커 thread를 사용할지 어떨지를 결정할 수도 있다. 상세한 것에 대하여는, 「COutputQueue::COutputQueue 」를 참조할것.

Protected 멤버 변수
m_pPin | 입력 핀의 IPin 인터페이스에의 포인터.
m_pInputPin | 입력 핀의 IMemInputPin 인터페이스에의 포인터.
m_bBatchExact | 오브젝트가 정확한 배치로 샘플을 출력할지 어떨지를 나타내는 플래그.
m_lBatchSize | 배치 사이즈.
m_List | 미디어 샘플 큐.
m_hSem | semaphore에의 핸들, 샘플을 기다리는 thread에 의해 사용된다.
m_evFlushComplete | 플래시 처리가 종료했을 때 통지하는 이벤트.
m_hThread | 워커 thread에의 핸들.
m_ppSamples | m_lBatchSize 사이즈의 샘플의 배열.
m_nBatched | 현재 배치 되고 처리를 기다리고 있는 샘플의 수.
m_lWaiting | thread가 샘플을 기다리고 있을 때 제로 이외의 값을 가지는 플래그.
m_bFlushing | 오브젝트가 플래시 처리를 실행중인가 어떤가를 나타내는 플래그.
m_bTerminate | thread가 종료해야할 것인가 제발을 나타내는 플래그.
m_bSendAnyway | 배치 프로세스를 오버라이드(override) 하는 플래그.
m_hr | 오브젝트가 샘플을 받아들일지 어떨지를 나타내는 HRESULT 값.
m_hEventPop | 오브젝트가 큐로부터 샘플을 삭제할 때마다 통지하는 이벤트.
Protected 메소드
InitialThreadProc | thread가 생성 되었을 때 ThreadProc 메소드를 호출한다.
ThreadProc | 샘플을 큐로부터 취득해, 그것을 입력 핀에 출력한다.
IsQueued | 오브젝트가 워커 thread를 사용해 샘플을 출력하고 있을지 어떨지를 확인한다.
QueueSample | 미디어 샘플 혹은 컨트롤 메세지를 큐에 넣는다.
IsSpecialSample | 큐에 넣어진 데이터가 컨트롤 메세지인가 어떤가를 확인한다.
FreeSamples | 모든 미처리의 샘플을 프리로 한다.
NotifyThread | thread에 큐에 데이터가 들어가 있는 것을 알린다.
Public 메소드
COutputQueue | constructor 메소드.
~COutputQueue | 소멸자 메소드.
BeginFlush | 플래시 처리의 시작.
EndFlush | 플래시 처리의 종료.
EOS | 입력 핀에 엔드 오브 스트림 호출을 출력한다.
SendAnyway | 미처리의 모든 샘플을 출력한다.
NewSegment | 입력 핀에 새로운 세그먼트(segment)를 출력한다.
Receive | 입력 핀에 미디어 샘플을 출력한다.
ReceiveMultiple | 미디어 샘플의 배치를 입력 핀에 출력한다.
Reset | 오브젝트를 리셋 해, 다시 데이터를 받아들이도록(듯이) 한다.
IsIdle | 오브젝트가 데이터를 기다리고 있는지 어떤지를 확인한다.
SetPopEvent | 오브젝트가 큐로부터 샘플을 삭제했는지 어떠했는지를 통지하는 이벤트를 지정한다.

COutputQueue.m_pPin

COutputQueue 클래스

입력 핀의 IPin 인터페이스에의 포인터.

구문

IPin * const m_pPin;

COutputQueue.m_pInputPin

COutputQueue 클래스

입력 핀의 IMemInputPin 인터페이스에의 포인터.

구문

IMemInputPin *m_pInputPin;

COutputQueue.m_bBatchExact

COutputQueue 클래스

오브젝트가 정확한 배치로 샘플을 출력할지 어떨지를 나타내는 플래그.

구문

BOOL const m_bBatchExact;

주의

이 값이 TRUE 라면, 오브젝트는 출력전에 미디어 샘플의 배치가 완성할 때까지 기다린다. 그 이외라면, 샘플을 받자마자 그것을 출력한다. m_lBatchSize 멤버 변수는 배치의 사이즈를 정의한다.

COutputQueue.m_lBatchSize

COutputQueue 클래스

배치 사이즈.

구문

LONG const m_lBatchSize;

COutputQueue.m_List

COutputQueue 클래스

미디어 샘플 큐.

구문

typedef CGenericList<IMediaSample> CSampleList;
CSampleList *m_List;

주의

IMediaSample 포인터를 보관 유지하기 위해서 특수화 된 CGenericList 클래스 템플릿에의 포인터.

COutputQueue.m_hSem

COutputQueue 클래스

semaphore에의 핸들, 샘플을 기다리는 thread에 의해 사용된다.

구문

HANDLE m_hSem;

COutputQueue.m_evFlushComplete

COutputQueue 클래스

플래시 처리가 종료했을 때 통지하는 이벤트.

구문

CAMEvent m_evFlushComplete;

COutputQueue.m_hThread

COutputQueue 클래스

워커 thread에의 핸들.

구문

HANDLE m_hThread;

COutputQueue.m_ppSamples

COutputQueue 클래스

m_lBatchSize 사이즈의 샘플의 배열.

구문

IMediaSample  **m_ppSamples;

주의

워커 thread는 샘플을 큐 (m_List )로부터 뽑아 내, 그것을 이 배열에 넣는다. 그것은 배열을 IMemInputPin::ReceiveMultiple 메소드에 건네준다. 오브젝트가 워커 thread를 사용하지 않으면, 오브젝트는 샘플을 이 배열에 직접 넣는다.

COutputQueue.m_nBatched

COutputQueue 클래스

현재 배치 되고 처리를 기다리고 있는 샘플의 수.

구문

LONG m_nBatched;

COutputQueue.m_lWaiting

COutputQueue 클래스

thread가 샘플을 기다리고 있을 때 제로 이외의 값을 가지는 플래그.

구문

LONG m_lWaiting;

COutputQueue.m_bFlushing

COutputQueue 클래스

오브젝트가 플래시 처리를 실행중인가 어떤가를 나타내는 플래그. TRUE 라면 오브젝트는 플래시를 시작 하고 있다.

구문

BOOL m_bFlushing;

COutputQueue.m_bTerminate

COutputQueue 클래스

thread가 종료해야할 것인가 제발을 나타내는 플래그. TRUE 라면 thread는 종료한다.

구문

BOOL m_bTerminate;

COutputQueue.m_bSendAnyway

COutputQueue 클래스

배치 프로세스를 오버라이드(override) 하는 플래그. 이 플래그를 TRUE 로 하면(자),m_bBatchExact 플래그를 오버라이드(override) 해, 모든 미처리 샘플을 출력한다.

구문

BOOL m_bSendAnyway;

COutputQueue.m_hr

COutputQueue 클래스

오브젝트가 샘플을 받아들일지 어떨지를 나타내는 HRESULT 값. 이 값이 S_OK 라면, 오브젝트는 샘플을 받아들인다. 그 이외라면, 샘플을 거부한다.

구문

BOOL volatile m_hr;

주의

이 멤버 변수는 thread간의 동작을 조정한다. 입력 핀에의 다운 스트림이 샘플을 거부한다, 혹은 오브젝트가 플래시를 시작 한다면, 이 값에는 S_FALSE 나 에러 코드가 세트 된다. 오브젝트는 플래시가 완료한다, 혹은 Reset 메소드가 종료할 때까지, 그 이후의 샘플을 출력하지 않는다.

COutputQueue.m_hEventPop

COutputQueue 클래스

오브젝트가 큐로부터 샘플을 삭제할 때마다 통지제가 되는 옵션 이벤트. 이 값은 NULL 로 초기화된다. SetPopEvent 메소드를 호출해, 이벤트 핸들을 지정하는 것.

구문

HANDLE m_hEventPop;

COutputQueue::BeginFlush

COutputQueue 클래스

플래시 처리의 시작.

구문

void BeginFlush(void);

주의

이 메소드는 m_bFlushing 멤버 변수를 TRUE 로 설정한다. 오브젝트가 thread를 사용하고 있다면, 그 thread는 FreeSamples 메소드를 호출해 미처리의 샘플을 프리로 한다. thread를 사용하지 않으면, 오브젝트는 COutputQueue::EndFlush 메소드의 사이에 FreeSamples 를 호출한다. 이 메소드는 또 m_hr 멤버 변수를 S_FALSE 에 세트 해, 오브젝트에 모든 새로운 샘플을 방폐시킨다.

오브젝트는 입력 핀의 IPin::BeginFlush 메소드를 호출하는 것으로 다운 스트림에 플래시 통지를 건네준다.

COutputQueue::COutputQueue

COutputQueue 클래스

constructor　 　 메소드.

구문

COutputQueue(
    IPin *pInputPin,
    HRESULT *phr,
    BOOL bAuto = TRUE,
    BOOL bQueue = TRUE,
    LONG lBatchSize = 1,
    BOOL bBatchExact = FALSE,
    LONG lListSize = DEFAULTCACHE,
    DWORD dwPriority = THREAD_PRIORITY_NORMAL
);

파라미터

pInputPin
입력 핀의 IPin 인터페이스에의 포인터. 오브젝트는 이 핀에 샘플을 출력한다.
phr
HRESULT 반환값에의 포인터. 이 메소드를 호출하기 전에 이 값을 S_OK 로 설정하는 것. 돌아갔을 때 phr 는 메소드의 성공/실패를 나타내는 값을 돌려준다.
bAuto
큐를 만들 때라고 오브젝트가 결정했는지 어떠했는지를 지정하는 플래그. TRUE 라면, 입력 핀이 블록 하지 않는 경우에게만 오브젝트는 큐를 생성 한다. FALSE 라면,bQueue 파라미터가 큐를 생성 할지 어떨지를 지정한다.
bQueue
bAuto 가 TRUE라면, 이 파라미터는 무시된다. bAuto 가 FALSE 라면 이 플래그는 큐를 만들지 어떨지를 지정한다.
lBatchSize
1 개의 배치에 출력되는 샘플의 최대수.
bBatchExact
정확한 배치 사이즈를 사용할지 어떨지를 지정하는 플래그. TRUE 라면, 오브젝트는 입력 핀에 그것들을 출력하기 전에 lBatchSize 까지 샘플을 기다린다. FALSE 라면, 오브젝트는 샘플을 받자마자 출력한다.
lListSize
큐의 캐쉬 사이즈. 디폴트값 DEFAULTCACHE 는 CBaseList 클래스에서 정의되는 정수이다.
dwPriority
샘플을 출력하는 thread의 우선도.

주의

bAuto 가 TRUE 라면, 오브젝트는 다운 스트림 핀의 IMemInputPin::ReceiveCanBlock 메소드를 호출한다. ReceiveCanBlock 이 S_OK 를 돌려준다면 (핀이 Receive 호출로 블록 할지도 모르는 것을 의미한다), 오브젝트는 샘플을 출력하는 thread를 생성 한다. 그렇지 않으면, 오브젝트는 thread를 생성 하지 않는다.

bAuto 가 FALSE 라면,bQueue 의 값이 thread를 생성 할지 어떨지를 결정한다.

오브젝트가 thread를 생성 한다면, 오브젝트는 thread 핸들을 m_hThread 멤버 변수에 할당 한다. thread 프로시저는 InitialThreadProc 이며, thread 파라미터는 this 에의 포인터이다. 오브젝트는 또 샘플을 보관 유지하는 큐를 생성 하는, 그것은 m_List 멤버 변수에 의해 주어진다.

COutputQueue::~COutputQueue

COutputQueue 클래스

소멸자 메소드.

구문

~COutputQueue(void);

COutputQueue::EndFlush

COutputQueue 클래스

플래시 처리의 종료.

구문

void EndFlush(void);

주의

오브젝트가 thread를 사용하고 있다면, 이 메소드는 m_evFlushComplete 이벤트를 기다린다. 메소드는 미처리의 샘플을 프리로 한 다음에 이 이벤트를 통지한다. 오브젝트가 thread를 사용하지 않으면, 이 메소드는 FreeSamples 메소드를 호출한다.

다음에 EndFlush 메소드는 입력 핀의 IPin::EndFlush 를 호출한다.

COutputQueue::EOS

COutputQueue 클래스

입력 핀에 엔드 오브 스트림 호출을 출력한다.

구문

void EOS(void);

주의

오브젝트가 thread를 사용하고 있다면, EOS_PACKET 컨트롤 메세지를 큐에 넣는다. thread는 모든 미처리의 샘플을 출력해, 입력 핀의 IPin::EndOfStream 메소드를 호출한다.

오브젝트가 thread를 사용하지 않으면,SendAnyway 메소드를 호출해 미처리의 샘플을 출력한다. 다음에 오브젝트는 입력 핀의 IPin::EndOfStream 를 호출한다.

COutputQueue::FreeSamples

COutputQueue 클래스

모든 미처리의 샘플을 프리로 한다.

구문

void FreeSamples(void);

주의

이 메소드는 큐와 샘플 배열 (m_ppSamples )로부터 모든 미처리의 샘플을 삭제한다.

COutputQueue::InitialThreadProc

COutputQueue 클래스

thread가 생성 되었을 때 ThreadProc 메소드를 호출한다.

구문

static DWORD WINAPI InitialThreadProc(
    LPVOID pv
);

파라미터

pv
this 포인터.

반환값

ThreadProc 가 돌려준 값을 돌려준다.

주의

이 메소드는 오브젝트의 워커 thread의 thread 프로시저이다. 오브젝트의 this 포인터는 thread 파라미터이다. 메소드는 this 에의 참조를 해제해,ThreadProc 메소드를 호출한다.

COutputQueue::IsIdle

COutputQueue 클래스

오브젝트가 데이터를 기다리고 있는지 어떤지를 확인한다.

구문

BOOL IsIdle(void);

반환값

thread가 기다리고 있어, 샘플 배열이 컬러라면 TRUE 를 돌려준다. 그 이외라면 FALSE 를 돌려준다.

COutputQueue::IsQueued

COutputQueue 클래스

오브젝트가 워커 thread를 사용해 샘플을 출력하고 있을지 어떨지를 확인한다.

구문

BOOL IsQueued(void);

반환값

오브젝트가 워커 thread를 사용하고 있다면 TRUE 를 돌려주는, 그렇지 않으면 FALSE 를 돌려준다.

COutputQueue::IsSpecialSample

COutputQueue 클래스

큐에 넣어진 데이터가 컨트롤 메세지인가 어떤가를 확인한다.

구문

BOOL IsSpecialSample(
    IMediaSample *pSample
);

파라미터

pSample
큐내의 항목에의 포인터.

반환값

pSample 가 컨트롤 메세지라면 TRUE 를 돌려주는, 그렇지 않으면 FALSE 를 돌려준다.

주의

QueueSample 메소드는 미디어 샘플에 가세해 컨트롤 메세지를 받아들일 수가 있다. 컨트롤 메세지는 thread에 있는 동작을 지시하는 (LONG_PTR 타입에 캐스트 된다) 정의 끝난 정수이다. 컨트롤 메세지는 미디어 데이터를 포함하지 않는다. 상세한 것에 대하여는, 「QueueSample 」를 참조할것.

COutputQueue::NewSegment

COutputQueue 클래스

입력 핀에 새로운 세그먼트(segment)를 출력한다.

구문

HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

파라미터

tStart
[in] 세그먼트(segment)의 시작 미디어 위치, 100 나노초단위.
tStop
[in] 세그먼트(segment)의 종료 미디어 위치, 100 나노초단위.
dRate
[in] 이 세그먼트(segment)가 처리되어야 할 레이트, 오리지날 레이트의 퍼센티지.

반환값

Returns an HRESULT value.

주의

오브젝트가 thread를 사용하고 있다면, 그것은 다음의 항목을 차례로 큐에 넣는다 :

  • NEW_SEGMENT 컨트롤 메세지
  • 세그먼트(segment) 데이터.

The NEW_SEGMENT 메세지는 thread에 큐의 다음의 항목에 세그먼트(segment) 데이터가 들어가 있는 것을 알린다. 세그먼트(segment) 데이터는 다음에 선언되는 구조체에 저장 되고 있다 :

struct NewSegmentPacket {
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    double dRate;
};

thread는 이 구조체로 주어진 데이터를 사용해, 입력 핀의 IPin::NewSegment 메소드를 호출한다.

오브젝트가 thread를 사용하지 않으면,SendAnyway 메소드를 호출해 모든 미처리의 샘플을 출력한다. 다음에 오브젝트는 입력 핀의 IPin::NewSegment 를 호출한다.

COutputQueue::NotifyThread

COutputQueue 클래스

thread에 큐에 데이터가 들어가 있는 것을 알린다.

구문

void NotifyThread(void);

주의

이 메소드를 호출하기 전에 크리티컬 섹션을 보관 유지하는 것.

COutputQueue::QueueSample

COutputQueue 클래스

샘플을 큐에 넣는다.

구문

void QueueSample(
    IMediaSample *pSample
);

파라미터

pSample
샘플의 IMediaSample 인터페이스에의 포인터.

주의

이 메소드는 샘플을 큐의 말미 (m_List )에 추가한다. 이 메소드를 호출하기 전에 크리티컬 섹션을 보관 유지하는 것, 그리고 오브젝트가 thread를 사용해 샘플을 출력하고 있을 때는 그것을 호출하는 것. 오브젝트가 thread를 사용하고 있는지 어떤지를 확인하려면 ,IsQueued 메소드를 호출하는 것.

이 메소드는 컨트롤 메세지를 큐에 두기 위해서(때문에) 이용할 수도 있다. 컨트롤 메세지는 thread에 있는 동작을 지시하는 (LONG_PTR 타입에 캐스트 된다) 정의 끝난 정수이다. COutputQueue 클래스는 다음 표에 나타나는 컨트롤 메세지를 정의한다 :

메세지 | 동작
EOS_PACKET | 엔드 오브 스트림 통지를 출력한다.
NEW_SEGMENT | 새로운 세그먼트(segment)를 출력한다.
RESET_PACKET | 큐 상태를 리셋 한다.
SEND_PACKET | 샘플의 부분적 배치를 보낸다.

이것은 COutputQueue 클래스가 최초로 사용하는 프로텍트 메소드이다.

COutputQueue::Receive

COutputQueue 클래스

입력 핀에 미디어 샘플을 출력한다.

구문

HRESULT Receive(
    IMediaSample *pSample
);

파라미터

pSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값을.

S_FALSE | 이 샘플을 처리하기 전에 엔드 오브 스트림 통지를 받았다.
S_OK | 성공.

주의

이 메소드는 COutputQueue::ReceiveMultiple 메소드를 호출한다.

COutputQueue::ReceiveMultiple

COutputQueue 클래스

미디어 샘플의 배치를 입력 핀에 출력한다.

구문

HRESULT ReceiveMultiple (
    IMediaSample **ppSamples,
    long nSamples,
    long *nSamplesProcessed
);

파라미터

ppSamples
샘플 배열에의 포인터의 주소.
nSamples
배열내의 샘플의 수.
nSamplesProcessed
출력에 성공한 샘플의 수를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 이 샘플을 처리하기 전에 엔드 오브 스트림 통지를 받았다.
S_OK | 성공.

주의

오브젝트가 thread를 사용하고 있다면, 이 메소드는 배열내에서 미처리의 모든 샘플을 큐에 넣는다. 그렇지 않으면, 이 메소드는 입력 핀의 IMemInputPin::ReceiveMultiple 메소드를 호출한다.

COutputQueue::Reset

COutputQueue 클래스

오브젝트를 리셋 해, 다시 데이터를 받아들이도록(듯이) 한다.

구문

void Reset(void);

반환값

반환값 없음.

주의

이 메소드는 m_hr 멤버 변수를 S_OK 에 리셋 한다. 오브젝트는 미디어 샘플을 다시 받을 수가 있다, 예를 들어 플래시 처리의 뒤.

COutputQueue::SendAnyway

COutputQueue 클래스

미처리의 모든 샘플을 출력한다.

구문

void SendAnyway(void);

주의

If the m_bBatchExact 멤버 변수가 TRUE 라면, 오브젝트는 샘플의 배치를 출력하기 전에 m_ppSamples 배열에 오브젝트를 넣는다. 예를 들어,EOS 메소드는 SendAnyway 를 호출해 엔드 오브 스트림 메세지를 처리한다.

COutputQueue::SetPopEvent

COutputQueue 클래스

오브젝트가 큐로부터 샘플을 삭제했는지 어떠했는지를 통지하는 이벤트를 지정한다.

구문

void COutputQueue::SetPopEvent(
    HANDLE hEvent
);

구문

hEvent
호출 바탕으로야는 생성 된 이벤트에의 핸들.

COutputQueue::ThreadProc

COutputQueue 클래스

샘플을 큐로부터 취득해, 그것을 입력 핀에 출력한다.

구문

DWORD ThreadProc(void);

반환값

제로를 돌려준다.

주의

InitialThreadProc 메소드는 이 메소드를 호출해, 메인의 thread 루프를 이행 한다. 그 루프 중(안)에서, 메소드는 다음의 스텝을 실시한다 :

  1. 큐 (m_List )의 샘플을 취득한다.
  2. 샘플이 컨트롤 메세지라면, thread는 컨트롤 동작을 실행한다. 그렇지 않으면, 샘플을 m_ppSamples 배열에 넣는다.
  3. 그 배열이 가득하면 (혹은 m_bBatchExact 가 FALSE 라면) thread는 IMemInputPin::ReceiveMultiple 메소드를 호출해 샘플을 출력한다.
  4. 큐내에 샘플이 없으면, thread는 m_hSem semaphore로 기다린다.

thread는 m_bTerminate 멤버 변수가 TRUE 가 되면(자) 종료한다.


CPersistStream 클래스

CPersistStream 클래스의 계층

CPersistStream 는, 필터의 영속적인 프로퍼티 (보존된 그래프의 필터 프로퍼티)의 base class이다.

CPersistStream 를 사용하는 간단한 방법은 다음과 같다.

  1. 필터가 이 클래스를 계승하도록(듯이) 한다.
  2. 클래스에 WriteToStream 및 ReadFromStream 를 이행 한다. 이러한 방법은 여기서 나타나고 있는, 플레이스홀더로서의 보고 기능하는 함수를 오버라이드(override) 한다.
  3. NonDelegatingQueryInterface 를,IPersistStream 를 처리하도록(듯이) 변경한다.
  4. 보존하는 데이터의 바이트수의 상한을 돌려주는 SizeMax 를 이행 한다.

    Unicode™ 의 데이터를 보존하는 경우는, WCHAR 가 2 바이트인 것에 유의한다.

  5. 데이터가 변경되었을 때에,SetDirty 를 호출한다.

버젼 번호

어떤 시점으로, 데이터의 포맷을 변경 또는 확장하고 싶은 경우가 있다. 이 경우, 이전에 보존한 모든 스트림에 버젼 번호를 붙여, 스트림을 읽어냈을 때에, 스트림이 낡은 포맷인지, 새로운 포맷인지를 구별할 수 있도록(듯이) 할 필요가 있다. 이것을 실시하기 위해서(때문에), 이 클래스는 버젼 번호의 읽고 쓰기를 실시한다. 기입시에는, 이 클래스는 GetSoftwareVersion 를 호출해, 그 때에 사용되고 있는 소프트웨어의 버젼을 문의한다. 실질적으로, 이것이 파일내의 데이터 레이아웃의 버젼 번호가 된다. 이 클래스는, 데이터내의 최초의 항목으로서 이것을 기입한다. 버젼 번호를 변경하는 경우는,GetSoftwareVersion 를 이행 (오버라이드(override)) 한다. 이 클래스는,ReadFromStream 를 호출하기 전에, 파일로부터 mPS_dwFileVersion 에 버젼 번호를 읽어내므로,ReadFromStream 로 mPS_dwFileVersion 를 체크해, 낡은 버젼의 파일을 읽어내고 있는지 어떤지를 확인할 수 있다. 보통, 파일을 읽어내는 소프트웨어의 버젼 이전의 버젼의 파일을 받아들일 필요가 있다.

프로텍트 데이터 멤버

mPS_dwFileVersion | 파일의 버젼 번호.
mPS_fDirty | 이 스트림의 데이터를 보존해야 한다.

멤버 함수

CPersistStream | CPersistStream 오브젝트를 생성 한다.
SetDirty | 오브젝트를 스트림에 보존해야 하는 것을 지정한다.

오버라이드(override) 가능한 멤버 함수

GetClassID | 이 스트림의 클래스 식별자를 취득한다.
GetSoftwareVersion | 이 파일 포맷의 버젼 번호를 취득한다.
ReadFromStream | 스트림으로부터 필터의 데이터를 읽어낸다.
SizeMax | 데이터로 필요한 바이트수 (버젼 번호를 포함하지 않는다)를 취득한다.
WriteToStream | 스트림에 필터의 데이터를 기입한다.

CPersistStream 는 IPersistStream 를 이행 한다. 이행의 상세한 것에 대하여는, Microsoft Platform SDK 의 「COM 레퍼런스」를 참조할것.

이행 되는 IPersistStream 메소드

GetSizeMax | 데이터로 필요한 바이트수 (버젼 번호를 포함한다)를 취득한다.
IsDirty | 오브젝트를 보존해야 하는지 어떤지를 체크한다.
Load | 데이터를 스트림으로부터 메모리에 로드한다.
Save | 데이터를 메모리로부터 스트림에 보존한다.

CPersistStream::CPersistStream

CPersistStream 클래스

CPersistStream 오브젝트를 생성 한다.

구문

CPersistStream(
IUnknown *pUnk,
HRESULT *phr
);

파라미터

pUnk
위임 오브젝트의 IUnknown 인터페이스에의 포인터.
phr
일반적인 COM 반환값에의 포인터. 이 값은, 이 함수가 실패했을 경우에게만 변경된다.

반환값

반환값 없음.

CPersistStream::GetClassID

CPersistStream 클래스

이 필터의 클래스 식별자를 취득한다.

구문

HRESULT GetClassID(
CLSID *pClsID
);

파라미터

pClsID
CLSID 구조체에의 포인터. 클래스 ID 를 여기에 카피한다.

반환값

HRESULT 값을 돌려준다.

CPersistStream::GetSizeMax

CPersistStream 클래스

버젼 번호를 포함한, 현재의 스트림에 필요한 최대 바이트 사이즈를 취득한다.

구문

HRESULT GetSizeMax(
ULARGE_INTEGER *pcbSize
);

파라미터

pcbSize
버젼 번호를 포함해, 이 스트림을 보존하기 위해서 필요한 바이트 단위의 사이즈에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IPersistStream::GetSizeMax 메소드를 이행 한다.

CPersistStream::GetSoftwareVersion

CPersistStream 클래스

이 스트림의 소프트웨어 버젼을 취득한다.

구문

virtual DWORD GetSoftwareVersion(void);

반환값

버젼 번호를 저장 하는 DWORD 형의 값을 돌려준다. 스트림의 포맷이 변경될 때마다, 이 함수를 변경해 이전보다 큰 수치를 돌려주도록(듯이) 할 필요가 있다.

주의

파일 포맷의 버젼 번호를 사용하는 이유에 대해서는, 「버젼 번호」를 참조할것.

CPersistStream::IsDirty

CPersistStream 클래스

오브젝트가 현재의 스트림에 마지막에 보존된 후, 변경되었는지 어떠했는지를 나타낸다.

구문

HRESULT IsDirty(void);

반환값

필터를 보존할 필요가 있는 경우는 S_OK 를 돌려준다. 보존의 필요가 없는 경우는 S_FALSE 를 돌려준다.

주의

이 멤버 함수는,IPersistStream::IsDirty 메소드를 이행 한다.

CPersistStream::Load

CPersistStream 클래스

지정된 스트림으로부터 필터의 데이터를 로드한다.

구문

HRESULT Load(
LPSTREAM pStm
);

파라미터

pStm
로드원의 스트림에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IPersistStream::Load 메소드를 이행 한다.

CPersistStream::ReadFromStream

CPersistStream 클래스

지정된 스트림으로부터 필터의 데이터를 읽어낸다.

구문

virtual HRESULT ReadFromStream(
IStream *pStream
);

파라미터

pStream
데이터가 읽어내지는 IStream 인터페이스에의 포인터.

반환값

디폴트에서는 NOERROR 를 돌려준다. 오버라이드(override) 하는 멤버 함수는, 유효한 HRESULT 값을 돌려준다.

주의

디폴트의 버젼은 아무것도 읽어내지 않는다. 이것을 오버라이드(override) 해, 클래스에 고유의 데이터를 읽어낼 수가 있다.

CPersistStream::Save

CPersistStream 클래스

지정된 스트림에 필터의 데이터를 보존한다.

구문

HRESULT Save(
LPSTREAM pStm,
BOOL fClearDirty
);

파라미터

pStm
데이터가 보존되는 스트림에의 포인터.
fClearDirty
현재의 스트림의 더티 플래그를 리셋 할지 어떨지를 지정하는 플래그. TRUE 는 더티 플래그를 리셋 하는 것을 의미한다. Save 처리 중(안)에서 이 메소드를 호출하는 경우, 보통, 이 값은 TRUE 이다. Save As 처리 중(안)에서 호출하는 경우, 보통, 이 값은 FALSE 이다.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IPersistStream::Save 메소드를 이행 한다. 이 멤버 함수는, 소프트웨어 버젼을 지정해 WriteInt 를 호출해,pStm 로 스트림을 지정해 CPersistStream::WriteToStream 를 호출해,mPS_fDirty 을 리셋 한다.

CPersistStream::SetDirty

CPersistStream 클래스

현재의 스트림의 더티 플래그를 변경한다.

구문

HRESULT SetDirty(
BOOL fDirty
);

파라미터

fDirty
이 스트림의 새로운 더티 플래그. TRUE 는 데이터가 보존되어 있지 않은 것을 의미한다.

반환값

HRESULT 값을 돌려준다.

CPersistStream::SizeMax

CPersistStream 클래스

버젼 번호를 포함하지 않는, 현재의 스트림에 필요한 최대 바이트 사이즈를 취득한다.

구문

virtual int SizeMax(void);

반환값

버젼 번호를 포함하지 않는, 데이터로 필요한 바이트수를 돌려준다.

주의

디폴트의 버젼은 0 을 돌려준다. 다른 적절한 값을 돌려주려면 , 이것을 오버라이드(override) 할 필요가 있다.

CPersistStream::WriteToStream

CPersistStream 클래스

지정된 스트림에 필터의 데이터를 기입한다.

구문

virtual HRESULT WriteToStream(
IStream *pStream
);

파라미터

pStream
필터 데이터의 전송처 스트림을 지정하는 IStream 인터페이스에의 포인터.

반환값

디폴트에서는 NOERROR 를 돌려준다. 오버라이드(override) 하는 멤버 함수는, 유효한 HRESULT 값을 돌려준다.

주의

디폴트의 버젼은 아무것도 기입하지 않는다. 이것을 오버라이드(override) 해, 클래스에 고유의 데이터를 기입할 수가 있다.


CPosPassThru 클래스

CPosPassThru 클래스의 계층

자기 자신에서는 시크를 실시하지 않는 입력 핀을 가지는 필터의 시크 커멘드를 취급한다.

선언: Ctlutil.h

이 헬퍼 클래스는 시크 커멘드를 업 스트림에 보내는 필터로 IMediaPosition 와 IMediaSeeking 인터페이스를 이행 한다. 필터 그래프 매니저가 시크 커멘드를 어플리케이션으로부터 받았을 때, 그 커멘드를 그래프의 렌더링 필터에 보낸다. 그 커멘드는 다음에, (만약 있으면) 그것을 실행할 수 있는 필터에 도달할 때까지, 각 필터의 출력 핀을 통해 업 스트림에 보내진다. 보통, 시크는 소스 필터나 퍼서 필터로 이행 된다.

CPosPassThru 클래스는 필터의 입력 핀에의 포인터를 보관 유지한다. 이하의 다이어그램에 있도록(듯이), 그것은 시크 커멘드가 접속되고 있는 업 스트림 필터의 출력 핀에 보낸다.

변환 필터로 CPosPassThru 를 사용해, 렌더링 필터로 CRendererPosPassThru 클래스를 파생하는 것.

이 클래스를 필터로 사용하려면 , 클래스의 인터페이스를 생성 해,CPosPassThru constructor　 　 메소드의 필터의 입력 핀을 지정하는 것. 다음에 모든 IMediaPosition 와 IMediaSeeking 호출을 CPosPassThru 오브젝트에 위임하는 것.

시크 커멘드를 위임하는 가장 심플한 방법은 CPosPassThru 오브젝트의 IMediaPosition 와 IMediaSeeking 인터페이스를 공개하는 것이다. 필터나 핀이 이러한 인터페이스의 1 개를 문의했을 때, 그 인터페이스의 CPosPassThru 이행에의 포인터가 돌아간다. 다음의 코드는 이 방법을 나타낸다. 그것은 CTransformOutputPin 클래스로부터 적응되고 있다. CreatePosPassThru 함수는 CPosPassThru 오브젝트를 생성 하는 헬퍼 함수이다.

// 다음의 멤버 변수가 가정되고 있다 :
// CPosPassThru *m_pPos;
// IPin *m_pPin;

if (riid == IID_IMediaPosition || riid == IID_IMediaSeeking)
{
    if (m_pPos == NULL)
    {
        HRESULT hr;
        hr = CreatePosPassThru(GetOwner(), FALSE, m_pPin, &m_pPos);
        if (FAILED(hr))
            return hr;
    }
    return m_pPosition->QueryInterface(riid, ppv);
}
else
{
    // 이 핀의 다른 인터페이스에의 포인터를 돌려준다.
}

여기서 설명하고 있는 것 외에, 이 클래스의 모든 IMediaPosition 와 IMediaSeeking 메소드는 접속하고 있는 핀의 대응하는 메소드를 호출해, 그 결과를 돌려준다.

Public 메소드
CPosPassThru | constructor 메소드.
ForceRefresh | 사용되지 않았다.
GetMediaTime | 현재의 샘플의 타임 스탬프를 취득한다. 가상.
IMediaPosition 메소드
get_Duration | 스트림의 시간폭을 취득한다.
put_CurrentPosition | 현재의 위치를 설정하는, 스트림의 전시간폭으로부터의 상대값.
get_StopTime | 재생의 종료 타임을 취득하는, 스트림의 전시간폭으로부터의 상대값.
put_StopTime | 재생의 종료 타임을 설정하는, 스트림의 전시간폭으로부터의 상대값.
get_PrerollTime | 시작 위치전에 큐에 들어가는 데이터량 (프리로르타임)을 취득한다.
put_PrerollTime | 시작 위치전에 큐에 들어가는 데이터량 (프리로르타임)을 설정한다.
get_Rate | 재생 레이트를 취득한다.
put_Rate | 재생 레이트를 설정한다.
get_CurrentPosition | 현재 위치를 취득하는, 스트림의 전시간폭으로부터의 상대값.
CanSeekForward | 스트림이 순서 방향으로 시크 할 수 있을지 어떨지를 확인한다.
CanSeekBackward | 스트림이 역방향으로 시크 할 수 있을지 어떨지를 확인한다.
IMediaSeeking 메소드
CheckCapabilities | 스트림으로 지정된 시크 능력을 가질지 어떨지를 문의한다.
ConvertTimeFormat | 있는 타임 포맷화등별의 포맷에 변환한다.
GetAvailable | 시크가 효율적인 시간폭을 취득한다.
GetCapabilities | 스트림의 모든 시크 능력을 취득한다.
GetCurrentPosition | 현재 위치를 취득하는, 스트림의 전시간폭으로부터의 상대값.
GetDuration | 스트림의 시간폭을 취득한다.
GetPositions | 현재 위치와 정지 위치를 취득하는, 스트림의 전시간폭으로부터의 상대값.
GetPreroll | 시작 위치전에 큐에 들어가는 데이터량 (프리로르타임)을 취득한다.
GetRate | 재생 레이트를 취득한다.
GetStopPosition | 재생의 종료 타임을 취득하는, 스트림의 전시간폭으로부터의 상대값.
GetTimeFormat | 현재의 타임 포맷을 취득한다.
IsFormatSupported | 지정한 타임 포맷이 지원 되고 있는지 어떤지를 확인한다.
IsUsingTimeFormat | 지정한 타임 포맷이 현재 사용되고 있는 포맷화 제발을 확인한다.
QueryPreferredFormat | 스트림으로 허용 되는 타임 포맷을 취득한다.
SetPositions | 현재 위치와 정지 위치를 설정한다.
SetRate | 재생 레이트를 설정한다.
SetTimeFormat | 타임 포맷을 설정한다.
헬퍼 함수
CreatePosPassThru | CPosPassThru 오브젝트 또는 CRendererPosPassThru 오브젝트를 생성 한다.

CPosPassThru::CanSeekBackward

CPosPassThru 클래스

스트림이 역방향으로 시크 할 수 있을지 어떨지를 확인한다. IMediaPosition::CanSeekBackward 메소드의 이행.

구문

HRESULT CanSeekBackward(
    LONG *pCanSeekBackward
);

파라미터

pCanSeekBackward
필터가 역방향으로 시크 가능하면 OATRUE 값을 받는 변수의 포인터를 돌려주는, 그렇지 않으면 OAFALSE 를 돌려준다.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::CanSeekForward

CPosPassThru 클래스

스트림이 순서 방향으로 시크 할 수 있을지 어떨지를 확인한다. IMediaPosition::CanSeekForward 메소드의 이행.

구문

HRESULT CanSeekForward(
    LONG *pCanSeekForward
);

파라미터

pCanSeekForward
필터가 순서 방향으로 시크 가능하면 OATRUE 값을 받는 변수의 포인터를 돌려주는, 그렇지 않으면 OAFALSE 를 돌려준다.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::CheckCapabilities

CPosPassThru 클래스

스트림으로 지정된 시크 능력을 가질지 어떨지를 문의한다. IMediaSeeking::CheckCapabilities 메소드의 이행.

구문

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

파라미터

pCapabilities
AM_SEEKING_SEEKING_CAPABILITIES 속성의 1 개 혹은 복수의 비트 합성에의 포인터. 메소드가 돌아갈 때, 이 값은 그러한 속성이 유효한 것을 나타낸다.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::ConvertTimeFormat

CPosPassThru 클래스

어느 타임 포맷화등별의 포맷에 변환한다. IMediaSeeking::ConvertTimeFormat 메소드의 이행.

구문

HRESULT ConvertTimeFormat(
    LONGLONG *pTarget,
    const GUID *pTargetFormat,
    LONGLONG Source,
    const GUID *pSourceFormat
);

파라미터

pTarget
변환된 타임값을 받는 변수에의 포인터.
pTargetFormat
타겟 포맷의타임 포맷 GUID 에의 포인터. NULL 라면 현재의 포맷이 사용된다.
Source
변환되는 타임값.
pSourceFormat
변환하는 포맷의 타임 포맷 GUID 에의 포인터. NULL 라면 현재의 포맷이 사용된다.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::CPosPassThru

CPosPassThru 클래스

constructor　 　 메소드.

구문

CPosPassThru(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
    IPin *pPin
);

파라미터

pName
오브젝트의 이름에의 포인터, 디버그용. 이 파라미터는 스태틱 메모리에 할당하는 것.
pUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되고 있다면, 집성 된 오브젝트의 IUnknown 인터페이스에의 포인터를 건네준다. 그렇지 않으면, 이 파라미터에 NULL 를 설정한다.
phr
HRESULT 값에의 포인터. 무시된다.
pPin
필터의 입력 핀의 IPin 인터페이스에의 포인터.

CPosPassThru::ForceRefresh

CPosPassThru 클래스

사용되지 않았다.

구문

HRESULT ForceRefresh(void);

반환값

S_OK 를 돌려준다.

주의

당초 이 클래스는 접속되고 있는 핀의 IMediaPosition 와 IMediaSeeking 인터페이스에의 포인터를 캐쉬하기 위해서 설계되었다. ForceRefresh 메소드는 이러한 인터페이스를 해방했다.

현재의 이행에서는, 이 클래스는 이러한 인터페이스를 캐쉬하지 않는다. 호환성을 위해서(때문에) ForceRefresh 메소드는 인클루드 되고 있지만, 아무것도 하지 않고 S_OK 를 돌려주는 것만으로 있다.

CPosPassThru::GetAvailable

CPosPassThru 클래스

시크가 효율적인 시간폭을 취득한다. IMediaSeeking::GetAvailable 메소드의 이행.

구문

HRESULT GetAvailable(
    LONGLONG *pEarliest,
    LONGLONG *pLatest
);

파라미터

pEarliest
시크가 효율적인 가장 빠른 타임값을 받는 변수에의 포인터.
pLatest
시크가 효율적인 가장 늦은 타임값을 받는 변수에의 포인터.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::GetCapabilities

CPosPassThru 클래스

스트림의 모든 시크 능력을 취득한다. IMediaSeeking::GetCapabilities 메소드의 이행.

구문

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

파라미터

pCapabilities
AM_SEEKING_SEEKING_CAPABILITIES 플래그의 비트 합성에의 포인터.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::GetCurrentPosition

CPosPassThru 클래스

현재 위치를 취득하는, 스트림의 전시간폭으로부터의 상대값. IMediaSeeking::GetCurrentPosition 메소드의 이행.

구문

HRESULT GetCurrentPosition(
    LONGLONG *pCurrent
);

파라미터

pCurrent
현재의 위치를 받는 변수에의 포인터, 현재의 타임 포맷의 단위.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 메소드는 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는 CPosPassThru::GetMediaTime 메소드를 호출해, 가장 최근의 위치를 취득한다. GetMediaTime 가 실패 하면, 이 메소드는 접속되고 있는 핀의 IMediaSeeking::GetCurrentPosition 를 호출한다.

GetMediaTime 메소드는 base class의 디폴트에서는 실패한다. 필터로 현재 위치를 캐쉬한다면, 캐쉬값을 돌려주는 GetMediaTime 를 오버라이드(override) 하는 것.

CPosPassThru::get_CurrentPosition

CPosPassThru 클래스

현재 위치를 취득하는, 스트림의 전시간폭으로부터의 상대값. IMediaPosition::get_CurrentPosition 메소드의 이행.

구문

HRESULT get_CurrentPosition(
    REFTIME *pllTime
);

파라미터

pllTime
현재 위치를 받는 변수에의 포인터, 초단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::GetDuration

CPosPassThru 클래스

스트림의 시간폭을 취득한다. IMediaSeeking::GetDuration 메소드의 이행.

구문

HRESULT GetDuration(
    LONGLONG *pDuration
);

파라미터

pDuration
시간폭을 받는 변수에의 포인터, 현재의 타임 포맷 단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::get_Duration

CPosPassThru 클래스

스트림의 시간폭을 취득한다. IMediaPosition::get_Duration 메소드의 이행.

구문

HRESULT get_Duration(
    REFTIME *plength
);

파라미터

plength
전스트림장을 받는 변수에의 포인터, 초단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::GetMediaTime

CPosPassThru 클래스

현재의 샘플의 타임 스탬프를 취득한다.

구문

virtual HRESULT GetMediaTime(
    LONGLONG *pStartTime,
    LONGLONG *pEndTime
);

파라미터

pStartTime
시작 타임을 받는 변수에의 포인터, 현재의 타임 포맷의 단위.
pEndTime
종료 타임을 받는 변수에의 포인터, 현재의 타임 포맷의 단위.

반환값

Returns E_FAIL.

주의

필터로 받은 샘플의 타임 스탬프를 캐쉬한다면 이 메소드를 오버라이드(override) 하는 것.

CPosPassThru::GetPositions

CPosPassThru 클래스

현재 위치와 정지 위치를 취득하는, 스트림의 전시간폭으로부터의 상대값. IMediaSeeking::GetPositions 메소드의 이행.

구문

HRESULT GetPositions(
    LONGLONG *pCurrent,
    LONGLONG *pStop
);

파라미터

pCurrent
현재 위치를 받는 변수에의 포인터, 현재의 타임 포맷의 단위.
pStop
정지 위치를 받는 변수에의 포인터, 현재의 타임 포맷의 단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::GetPreroll

CPosPassThru 클래스

시작 위치전에 큐에 들어가는 데이터의 양을 취득한다. IMediaSeeking::GetPreroll 메소드의 이행.

구문

HRESULT GetPreroll(
    LONGLONG *pllPreroll
);

파라미터

pllPreroll
프리로르타임 을 받는 변수에의 포인터, 현재의 타임 포맷의 단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::get_PrerollTime

CPosPassThru 클래스

시작 위치전에 큐에 들어가는 데이터량 (프리로르타임)을 취득한다. IMediaPosition::get_PrerollTime 메소드의 이행.

구문

HRESULT get_PrerollTime(
    REFTIME *pllTime
);

파라미터

pllTime
프리로르타임을 받는 변수에의 포인터. 초단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::GetRate

CPosPassThru 클래스

재생 레이트를 취득한다. IMediaSeeking::GetRate 메소드의 이행.

구문

HRESULT GetRate(
    double *pdRate
);

파라미터

pdRate
재생 레이트를 받는 변수에의 포인터.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::get_Rate

CPosPassThru 클래스

재생 레이트를 취득한다. IMediaPosition::get_Rate 메소드의 이행.

구문

HRESULT get_Rate(
    double *pdRate
);

파라미터

pdRate
재생 레이트를 받는 변수에의 포인터.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::GetStopPosition

CPosPassThru 클래스

재생 종료 타임을 취득하는, 스트림의 전시간폭으로부터의 상대값. IMediaSeeking::GetStopPosition 메소드의 이행.

구문

HRESULT GetStopPosition(
    LONGLONG *pStop
);

파라미터

pStop
종료 타임을 받는 변수에의 포인터, 현재의 타임 포맷의 단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::get_StopTime

CPosPassThru 클래스

재생의 종료 타임을 취득하는, 스트림의 전시간폭으로부터의 상대값. IMediaPosition::get_StopTime 메소드의 이행.

구문

HRESULT get_StopTime(
    REFTIME *pllTime
);

파라미터

pllTime
종료 타임을 받는 변수에의 포인터, 초단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::GetTimeFormat

CPosPassThru 클래스

현재의 타임 포맷을 취득한다. IMediaSeeking::GetTimeFormat 메소드의 이행.

구문

HRESULT GetTimeFormat(
    const GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 를 받는 변수에의 포인터.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::IsFormatSupported

CPosPassThru 클래스

지정한 타임 포맷이 지원 되고 있는지 어떤지를 확인한다. IMediaSeeking::IsFormatSupported 메소드의 이행.

구문

HRESULT IsFormatSupported(
    const GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 에의 포인터.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::IsUsingTimeFormat

CPosPassThru 클래스

지정한 타임 포맷이 현재 사용되고 있는 포맷화 제발을 확인한다. IMediaSeeking::IsUsingTimeFormat 메소드의 이행.

구문

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 에의 포인터.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::put_CurrentPosition

CPosPassThru 클래스

현재의 위치를 설정하는, 스트림의 전시간폭으로부터의 상대값. IMediaPosition::put_CurrentPosition 메소드의 이행.

구문

HRESULT put_CurrentPosition(
    REFTIME llTime
);

파라미터

llTime
새로운 위치, 초단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::put_PrerollTime

CPosPassThru 클래스

시작 위치전에 큐에 들어가는 데이터의 양을 설정한다. IMediaPosition::put_PrerollTime 메소드의 이행.

구문

HRESULT put_PrerollTime(
    REFTIME llTime
);

파라미터

llTime
프리로르타임, 초단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

주의

이 멤버 함수는 그 호출을 업 스트림에 건네주지만,IMediaPosition::put_PrerollTime 메소드는 모든 DirectShow 소스 필터로 지원 되고 있는 것은 아니다.

CPosPassThru::put_Rate

CPosPassThru 클래스

재생 레이트를 설정한다. IMediaPosition::put_Rate 메소드의 이행.

구문

HRESULT put_Rate(
    double dRate
);

파라미터

dRate
재생 레이트. 제로여서는 안 된다.

반환값

dRate 가 제로라면 E_INVALIDARG 를 돌려준다. 그 이외라면, 접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

주의

마이너스값은 리버스 재생을 나타낸다. 모든 미디어가 리버스 재생을 지원 하고 있는 것은 아니다.

CPosPassThru::put_StopTime

CPosPassThru 클래스

재생의 종료 타임을 설정하는, 스트림의 전시간폭으로부터의 상대값. IMediaPosition::put_StopTime 메소드의 이행.

구문

HRESULT put_StopTime(
    REFTIME llTime
);

파라미터

llTime
정지 타임의 double 값, 초단위.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::QueryPreferredFormat

CPosPassThru 클래스

스트림으로 허용 되는 타임 포맷을 취득한다. IMediaSeeking::QueryPreferredFormat 메소드의 이행.

구문

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 를 받는 변수에의 포인터.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::SetPositions

CPosPassThru 클래스

현재 위치와 정지 위치를 설정한다. IMediaSeeking::SetPositions 메소드의 이행.

구문

HRESULT SetPositions(
    LONGLONG *pCurrent,
    DWORD dwCurrentFlags,
    LONGLONG *pStop,
    DWORD dwStopFlags
);

파라미터

pCurrent
현재 위치를 지정하는 변수에의 포인터, 현재의 타임 포맷의 단위.
dwCurrentFlags
플래그의 비트의 편성. 상세한 것에 대하여는, 「IMediaSeeking::SetPositions 」를 참조할것.
pStop
정지 위치를 지정하는 변수에의 포인터, 현재의 타임 포맷의 단위.
dwStopFlags
플래그의 비트의 편성. 상세한 것에 대하여는,IMediaSeeking::SetPositions 」를 참조할것.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::SetRate

CPosPassThru 클래스

재생 레이트를 설정한다. IMediaSeeking::SetRate 메소드의 이행.

구문

HRESULT SetRate(
    double dRate
);

파라미터

dRate
재생 레이트. 제로여서는 안 된다.

반환값

dRate 가 제로라면 E_INVALIDARG 를 돌려준다. 그 이외라면, 접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CPosPassThru::SetTimeFormat

CPosPassThru 클래스

타임 포맷을 설정한다. IMediaSeeking::SetTimeFormat 메소드의 이행.

구문

HRESULT SetTimeFormat(
    const GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 에의 포인터.

반환값

접속되고 있는 핀으로부터 HRESULT 값을 돌려준다.

CreatePosPassThru 함수

CPosPassThru 클래스

CPosPassThru 오브젝트 또는 CRendererPosPassThru 오브젝트를 생성 한다.

구문

STDAPI CreatePosPassThru(
    LPUNKNOWN pAgg,
    BOOL bRenderer,
    IPin *pPin,
    IUnknown **ppPassThru
);

파라미터

pAgg
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되었을 경우는, 집성 오브젝트의 IUnknown 인터페이스에 포인터를 건네준다. 그 이외의 경우는, 이 파라미터에 NULL 를 설정한다.
bRenderer
파일이 렌더러일지 어떨지를 나타내는 불리언 값. 필터가 렌더러인 경우는 값 TRUE 를 사용해, 렌더러가 아닌 경우는 값 FALSE 를 사용한다.
pPin
필터의 입력 핀의 IPin 에의 포인터.
ppPassThru
오브젝트의 IUnknown 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공의 경우는 S_OK 를 돌려준다. 그 이외의 경우는 HRESULT 값을 돌려주어, 에러의 원인을 나타낸다.

주의

bSupportRendering 의 값이 TRUE 의 경우, 이 메소드는 CRendererPosPassThru 클래스의 인스턴스를 생성 한다. 그 이외의 경우는,CPosPassThru 클래스의 인스턴스를 생성 한다. 상세한 것에 대하여는, 「CSeekingPassThru 」를 참조할것.


CPullPin 클래스

CPullPin 클래스의 계층

CPullPin 클래스는, 소스로부터 다운 스트림을 받는 필터가 thread를 생성 해,IAsyncReader 인터페이스를 지원 하는 비동기소스 필터로부터 미디어 스트림을 꺼내기 위해서(때문에) 준비되어 있다. 보통, 이 클래스는,퍼서 필터의입력 핀으로 이행 된다. 이것은, Microsoft® DirectShow® 비동기 리더 필터가, 파일로부터 미디어 스트림을 읽어내는 것만으로, 해석을 실시하지 않기 때문에이다.

프로텍트 데이터 멤버

m_pAlloc 접속으로 사용되는 IMemAllocator 인터페이스에의 포인터.

멤버 함수

Active | 비동기 리더로부터 데이터를 꺼내기 시작하도록(듯이) 핀에 지시한다.
AlignDown | LONGLONG 형의 값을 바로 아래의 LONG 경계에 갖춘다.
AlignUp | LONGLONG 형의 값을 곧 위에의 LONG 경계에 갖춘다.
Connect | 이 핀으로부터 비동기 리더에게로의 접속을 시작 한다.
CPullPin | CPullPin 오브젝트를 생성 한다.
Disconnect | 비동기 리더에게로의 접속을 절단 한다.
Duration | 미디어 스트림의 시간폭을 취득한다.
GetReader | 비동기 리더 인터페이스를 취득한다.
Inactive | 비동기 리더로부터 데이터를 인출을 종료하도록(듯이) 핀에 지시한다.
Seek | 미디어 스트림의 시작 및 종료 타임을 설정한다.

오버라이드(override) 가능한 멤버 함수

BeginFlush | 이 핀 및 모든 다운 스트림 핀을 플래시 한다.
DecideAllocator | 비동기 리더로 사용하는 allocater를 지정한다.
EndFlush | 플래시 처리의 종료를 통지한다.
EndOfStream | 엔드 오브 스트림 통지를 다운 스트림에 송신한다.
OnError | 인출을 정지시키는 실행시 에러를 처리한다.
Receive | 비동기 리더로부터의 데이터의 수신을 처리한다.

CPullPin::Active

CPullPin 클래스

비동기 리더로부터 데이터를 꺼내기 시작하도록(듯이) 핀에 지시한다.

구문

HRESULT Active(void);

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수를 호출하기 전에, 리더 인터페이스를 취득해, allocater를 결정하지 않으면 안 된다. 이 처리는 CPullPin::Connect 멤버 함수에 의해 행해진다.

CPullPin::AlignDown

CPullPin 클래스

LONGLONG 형의 값을 바로 아래의 LONG 경계에 갖춘다.

구문

LONGLONG AlignDown(
LONGLONG ll,
LONG lAlign
    );

파라미터

ll
갖추는 요소.
lAlign
alignment 경계.

반환값

lAlign 에 갖춘 ll 값을 돌려준다.

주의

하위에의 정렬은 잘라서 버림 처리이다.

CPullPin::AlignUp

CPullPin 클래스

LONGLONG 형의 값을 곧 위에의 LONG 경계에 갖춘다.

구문

LONGLONG AlignUp(
LONGLONG ll,
LONG lAlign
    );

파라미터

ll
갖추는 요소.
lAlign
alignment 경계.

반환값

HRESULT 값을 돌려준다.

CPullPin::BeginFlush

CPullPin 클래스

오버라이드(override) 해 이 핀 및 모든 다운 스트림 핀을 플래시 한다.

구문

virtual HRESULT BeginFlush(void);

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 시크 처리에 앞서 thread를 포즈 하기 전에 CPullPin::Seek 멤버 함수에 의해 불려 간다. 이 멤버 함수를 이행 해, 접속된 다운 스트림 핀에 대해 IPin::BeginFlush 메소드를 호출할 필요가 있다.

CPullPin::Connect

CPullPin 클래스

이 핀으로부터 비동기 리더에게로의 접속을 시작 한다.

구문

HRESULT Connect(
IUnknown *pUnk,
IMemAllocator *pAlloc,
BOOL bSync
    );

파라미터

pUnk
비동기 리더 (IAsyncReader )의 존재를 문의하는 오브젝트에의 포인터.
pAlloc
필요에 따라서, 우선 allocater로서 지정하는 옵션의 allocater에의 포인터.
bSync
리더가 비동기 리더는 아니고, 동기 리더를 사용하는 경우는 TRUE 로 설정한다.

반환값

pUnk 로 지정된 오브젝트로부터 IAsyncReader 인터페이스에 정상적으로 접속되었을 경우는 S_OK 를 돌려준다.

CPullPin::CPullPin

CPullPin 클래스

CPullPin 오브젝트를 생성 한다.

구문

CPullPin(void);

반환값

반환값 없음.

CPullPin::DecideAllocator

CPullPin 클래스

비동기 리더와 사용하는 allocater를 네고시에이트 한다.

구문

virtual HRESULT DecideAllocator(
IMemAllocator *pAlloc,
ALLOCATOR_PROPERTIES *pProps
    );

파라미터

pAlloc
우선 allocater로서 지정하는 allocater에의 포인터 (옵션). allocater를 지정하지 않는 경우는, NULL 를 건네준다.
pProps
allocater의 사이즈, 카운트, 및 alignment에의 포인터 (옵션). allocater의 프로퍼티를 요구하지 않는 경우는 0 을 건네준다.

반환값

성공했을 경우는 S_OK 를 돌려준다. eProps 에 무효인 alignment 프로퍼티가 포함되어 있는 경우는 VFW_E_BADALIGN 를 돌려준다. allocater를 생성 하기 위해서 충분한 메모리가 없는 경우는 E_OUTOFMEMORY 를 돌려준다. 생성 한 IMemAllocator 인터페이스가 무효인 경우는 E_NOINTERFACE 를 돌려준다.

주의

이 멤버 함수는,IAsyncReader::RequestAllocator 메소드를 호출해 allocater를 네고시에이트 한다.

CPullPin::Disconnect

CPullPin 클래스

비동기 리더에게로의 접속을 절단 한다.

구문

HRESULT Disconnect(void);

반환값

접속이 없는 경우는 NOERROR 를 돌려준다.

주의

이 멤버 함수는,CPullPin::Connect 메소드로 생성 된 비동기 파일 리더에게로의 접속을 절단 한다.

CPullPin::Duration

CPullPin 클래스

미디어 스트림의 시간폭을 취득한다.

구문

HRESULT Duration(
REFERENCE_TIME *ptDuration
    );

파라미터

ptDuration
UNIT (10,000,000)를 곱셈한 바이트 단위의 시간폭에의 포인터.

반환값

HRESULT 값을 돌려준다.

CPullPin::EndFlush

CPullPin 클래스

오버라이드(override) 해 플래시 처리의 종료를 통지한다.

구문

virtual HRESULT EndFlush(void) PURE;

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 시크 처리에 앞서 thread를 포즈 한 후에 CPullPin::Seek 멤버 함수에 의해 불려 간다. 이 멤버 함수를 이행 해, 접속된 다운 스트림 핀에 대해 IPin::EndFlush 메소드를 호출할 필요가 있다.

CPullPin::EndOfStream

CPullPin 클래스

오버라이드(override) 해 엔드 오브 스트림 통지를 다운 스트림에 송신한다.

구문

virtual HRESULT EndOfStream(void) PURE;

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 수신한 샘플의 처리중에, 스트림의 마지막에 도달했을 경우에 불려 간다. 이 멤버 함수를 이행 해, 접속된 다운 스트림 핀에 대해 IPin::EndOfStream 메소드를 호출할 필요가 있다.

CPullPin::GetReader

CPullPin 클래스

비동기 리더를 취득한다.

구문

IAsyncReader* GetReader(void);

반환값

참조 카운트 된 IAsyncReader 인터페이스를 돌려준다.

CPullPin::Inactive

CPullPin 클래스

비동기 리더로부터 데이터를 인출을 종료하도록(듯이) 핀에 지시한다.

구문

HRESULT Inactive(void);

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,IAsyncReader::BeginFlush 메소드를 호출해, thread를 종료해,IAsyncReader::EndFlush 메소드를 호출해, allocater를 데코밋트 한다.

CPullPin::OnError

CPullPin 클래스

오버라이드(override) 해 인출을 정지시키는 실행시 에러를 처리한다.

구문

virtual void OnError(
HRESULT hr
) PURE;

파라미터

hr
트랩 된 에러의 HRESULT 값.

반환값

반환값 없음.

주의

이러한 에러는업 스트림 필터 (비동기 리더)로부터 돌려주어진다. 업 스트림 필터는 이미 에러를 필터 그래프 매니저에 리포트가 끝난 상태이다. 이 멤버 함수는, 에러를 트랩 할 경우에 복수의 CPullPin 멤버 함수로부터 불려 가므로, 이행 해야 한다.

CPullPin::Receive

CPullPin 클래스

이 멤버 함수를 오버라이드(override) 해, 비동기 리더로부터의 데이터의 수신을 처리한다.

구문

virtual HRESULT Receive(
IMediaSample *pSample
) PURE;

파라미터

pSample
[in] 미디어 샘플에의 포인터.

반환값

HRESULT 값을 돌려준다. S_OK 이외의 값을 돌려주면(자), 데이터는 종료한다.

주의

상속 클래스로 이 멤버 함수를 이행 해야 한다. 이 멤버 함수는, 샘플 스트림의 처리중에 새로운 샘플을 수신했을 때에 반드시 불려 간다. 입력 핀의 IMemInputPin::Receive 메소드와 같은 방법으로 기술할 필요가 있다.

CPullPin::Seek

CPullPin 클래스

미디어 스트림의 시작 및 종료 타임을 설정한다.

구문

HRESULT Seek(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop
    );

파라미터

tStart
시작 타임 (디폴트는 0).
tStop
종료 타임 (디폴트는 CPullPin::Duration 의 값).

반환값

HRESULT 값을 돌려준다.

주의

필터 그래프가 실행중 (액티브)인 경우, 미디어 렌더링은 tStart 에 의해 정의된 새로운 위치로부터 즉시 시작 된다.


CQueue 클래스

단순하고 정적으로 사이즈를 할당한 큐를 이행 하는 템플릿.

선언 : Wxutil.h

클래스 constructor　 　 은 큐의 사이즈를 지정한다. PutQueueObject 메소드는 있는 오브젝트를 큐에 넣어GetQueueObject 메소드는 오브젝트로부터 큐를 꺼낸다. 새로운 오브젝트에 대해서 큐내에 스페이스가 생길 때까지,PutQueueObject 메소드는 블록 한다. 큐내에 받는 오브젝트가 올 때까지,GetQueueObject 메소드는 블록 한다.

이 클래스 템플릿은 2 개의 semaphore를 사용해 큐 조작을 컨트롤 하는, 1개는 「get」semaphore, 이제(벌써) 1 개(살)은 「put」semaphore이다. GetQueueObject 메소드는 (WaitForSingleObject 함수를 사용해) 「get」semaphore로 기다려, (ReleaseSemaphore 함수를 사용해) 「put」semaphore를 해방한다. PutQueueObject 메소드는 「put」semaphore로 기다려, 「get」semaphore를 해방한다. 이 클래스는 또 크리티컬 섹션을 사용해 복수 thread에서의 큐 조작을 처리한다.

Public 메소드
CQueue | constructor 메소드.
~CQueue | 소멸자 메소드.
GetQueueObject | 큐로부터 다음의 오브젝트를 취득한다.
PutQueueObject | 큐에 오브젝트를 넣는다.

CQueue::CQueue

CQueue 클래스

constructor　 　 메소드.

구문

CQueue(
    int n
);

CQueue(void);

파라미터

n
생성 하는 큐의 사이즈.

주의

파라미터없이 생성 하면, 큐의 사이즈는 DEFAULT_QUEUESIZE 에 세트 된다.

CQueue::~CQueue

CQueue 클래스

소멸자 메소드.

구문

~CQueue(void);

CQueue::GetQueueObject

CQueue 클래스

큐로부터 다음의 오브젝트를 취득한다.

구문

T GetQueueObject(void);

반환값

T 타입 (템플릿 타입)의 오브젝트를 돌려준다.

주의

이 메소드는 큐의 오브젝트가 유효하게 될 때까지 블록 한다.

CQueue::PutQueueObject

CQueue 클래스

큐에 오브젝트를 넣는다.

구문

void PutQueueObject(
    T object
);

파라미터

object
T 타입 (템플릿 타입)의 오브젝트.

주의

이 메소드는 큐내에 오브젝트의 스페이스가 생길 때까지 블록 한다.


CRefTime 클래스

CRefTime 클래스의 계층

기준 타임을 관리하는 헬퍼 클래스.

선언 : Reftime.h

기준 타임 은 100 나노초에 표현되는 시간의 단위이다. 이 클래스는 REFERENCE_TIME 데이터 타입과 같은 데이터 레이아웃을 공유하지만, 어느 메소드와 연산자가 추가되고 있는, 그것은 비교나 변환이나 수식 함수를 제공한다. 기준 타임의 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

Public 멤버 변수
m_time | REFERENCE_TIME 값.
Public 메소드
CRefTime | constructor 메소드.
GetUnits | 기준 타임을 취득하는, 100 나노초단위.
Millisecs | 기준 타임을 밀리 세컨드로 변환한다.
연산자
operator REFERENCE_TIME() | 오브젝트를 REFERENCE_TIME 데이터 타입에 캐스트 한다.
operator = | 새로운 기준 타임을 할당 한다.
operator += | 2 개의 기준 타임을 더한다.
operator –= | 있는 기준 타임부터 이제(벌써) 1 개의 기준 타임을 당긴다.

CRefTime.m_time

CRefTime 클래스

REFERENCE_TIME 값.

구문

REFERENCE_TIME m_time;

CRefTime::CRefTime

CRefTime 클래스

constructor　 　 메소드.

구문

CRefTime(void);

CRefTime(
    LONG msecs
);

CRefTime(
    REFERENCE_TIME rt
);

파라미터

msecs
밀리 세컨드 단위의 기준 타임.

rt
100 나노초단위의 기준 타임.

주의

기준 타임은 디폴트에서는 제로.

CRefTime::GetUnits

CRefTime 클래스

기준 타임을 취득하는, 100 나노초단위.

구문

LONGLONG GetUnits(void);

반환값

m_time 의 값을 돌려준다.

CRefTime::Millisecs

CRefTime 클래스

기준 타임을 밀리 세컨드로 변환한다.

구문

LONG Millisecs(void);

반환값

밀리 세컨드로 기준 타임을 돌려준다.

CRefTime::operator (REFERENCE_TIME)

CRefTime 클래스

오브젝트를 REFERENCE_TIME 데이터 타입에 캐스트 한다.

구문

operator REFERENCE_TIME() const;

반환값

m_time 의 값을 돌려준다.

주의

다음의 예는 이 캐스트 연산자의 사용법을 나타낸다.

CRefTime cRT(1000);
REFERENCE_TIME rt = (REFERENCE_TIME) cRT;

CRefTime::operator =

CRefTime 클래스

새로운 기준 타임을 할당 한다.

구문

CRefTime& operator=(
    const CRefTime& rt
);

CRefTime& operator=(
    const LONGLONG ll
);

파라미터

rt
새로운 기준 타임을 지정하는 CRefTime 오브젝트에의 참조.
ll
새로운 기준 타임, 100 나노초단위.

반환값

오브젝트에의 참조를 돌려준다.

CRefTime::operator +=

CRefTime 클래스

2 개의 기준 타임을 더한다.

구문

CRefTime& operator+=(
    const CRefTime& rt
);

파라미터

rt
CRefTime 오브젝트에의 참조.

반환값

오브젝트에의 참조를 돌려준다.

CRefTime::operator –=

CRefTime 클래스

어느 기준 타임부터 이제(벌써) 1 개의 기준 타임을 당긴다.

구문

CRefTime& operator-=(
    const CRefTime& rt
);

파라미터

rt
CRefTime 오브젝트에의 참조.

반환값

오브젝트에의 참조를 돌려준다.


CRenderedInputPin 클래스

CRenderedInputPin 클래스의 계층

The CRenderedInputPin 클래스는,입력 핀으로부터 보내진 스트림을 렌더링 하는렌더러 필터 (즉, 데이터를 건네주기 위한출력 핀을 가지지 않는다)를 위해서(때문에) 제공된다. 이 클래스는 CBaseInputPin 를 오버라이드(override) 해 엔드 오브 스트림 통지를 처리한다. 이 클래스는, 이 렌더러를 사용해 복수의 스트림을 취급할 수 있도록(듯이) 하기 위해서 이행 된다 ( 각 핀은 엔드 오브 스트림을 개별적으로 처리할 필요가 있다).

Protected 데이터 멤버

m_bAtEndOfStream | 엔드 오브 스트림 통지가 수취되면(자) TRUE 로 설정된다.
m_bCompleteNotified | EC_COMPLETE 통지가 필터 그래프 매니저에 송신되면(자) TRUE 로 설정된다.

멤버 함수

CRenderedInputPin CRenderedInputPin 오브젝트를 생성 한다.

오버라이드(override) 가능한 멤버 함수

Active | 필터 상태가 정지로부터 포즈에 변화한 것을 핀에 통지한다.
EndFlush | 플래시 처리를 종료하도록(듯이) 핀에 통지한다.
EndOfStream | 새롭게 실행 커멘드가 발행될 때까지, 추가의 데이터가 없는 것을 핀에 통지한다.
Run | 필터 상태가 포즈로부터 실행중에 변화한 것을 핀에 통지한다.

CRenderedInputPin::Active

CRenderedInputPin 클래스

필터 상태가 정지로부터 포즈 또는 실행중에 변화한 것을 핀에 통지한다.

구문

HRESULT Active(void);

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는 CBasePin::Active 를 오버라이드(override) 한다. base class 이행을 호출하기 전에,m_bAtEndOfStream 및 m_bCompleteNotified 의 양쪽 모두를 FALSE 로 설정한다.

CRenderedInputPin::CRenderedInputPin

CRenderedInputPin 클래스

CRenderedInputPin 오브젝트를 생성 한다.

구문

CRenderedInputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pName
    );

파라미터

pObjectName
오브젝트의 이름에의 포인터 (디버그용).
pFilter
핀을 소유하는 필터에의 포인터.
pLock
핀의 크리티컬 섹션에의 포인터.
phr
HRESULT 값에의 포인터.
pName
핀명에의 포인터.

반환값

반환값 없음.

CRenderedInputPin::EndFlush

CRenderedInputPin 클래스

플래시 처리를 종료하도록(듯이) 핀에 통지한다.

구문

HRESULT EndFlush(void);

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는 CBaseInputPin::EndFlush 를 오버라이드(override) 한다. base class 이행을 호출하기 전에,m_bAtEndOfStream 및 m_bCompleteNotified 의 양쪽 모두를 FALSE 로 설정한다.

CRenderedInputPin::EndOfStream

CRenderedInputPin 클래스

새롭게 실행 커멘드가 발행될 때까지, 추가의 데이터가 없는 것을 핀에 통지한다.

구문

HRESULT EndOfStream(void);

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는 IPin::EndOfStream 메소드를 이행 한다. 이 멤버 함수는,CheckStreaming 를 호출해 필터가 스트리밍 상태에 있을지 어떨지를 조사해m_bAtEndOfStream 를 TRUE 로 설정해, EC_COMPLETE 통지를 필터 그래프 매니저에 송신한다.

EC_COMPLETE 필터 그래프 통지의 발행은, 이 멤버 함수 호출 이전에 핀에 배송된 모든 데이터가 처리된 다음이 아니면 안 된다. 필터가 처리를 비동기에게 실행하는 경우는,CRenderedInputPin::EndOfStream 를 오버라이드(override) 해, 모든 입력 데이터의 처리가 완료할 때까지 EC_COMPLETE 통지의 송신을 늦춘다.

CRenderedInputPin::Run

CRenderedInputPin 클래스

필터 상태가 정지로부터 포즈에 변화한 것을 핀에 통지한다.

구문

HRESULT Run(
    REFERENCE_TIME tStart
    );

파라미터

tStart
시작 타임. 이 클래스로부터는 참조되지 않는다. 상속 클래스로부터 사용되는 일이 있다.

반환값

HRESULT 값을 돌려준다 (디폴트에서는 S_OK).

주의

이 멤버 함수는,CBasePin::Run 멤버 함수를 오버라이드(override) 한다. m_bAtEndOfStream 가 TRUE 의 경우, 이 멤버 함수는, EC_COMPLETE 통지를 필터 그래프 매니저에 송신한다.


CRendererInputPin 클래스

CRendererInputPin 클래스의 계층

CBaseRenderer 클래스의 입력 핀. 특히 주기가 있는 경우를 엿보여, 이 클래스의 메소드는,CBaseRenderer 클래스의 해당 메소드에 위임된다.

선언 : Renbase.h

프로텍트 멤버 변수
m_pRenderer | 필터에의 포인터.
Public 메소드
CRendererInputPin | constructor 메소드.
BreakConnect | 접속의 절단시에 커스터마이즈 한 코드를 추가한다.
CompleteConnect | 접속을 완료한다.
CheckMediaType | 핀이 특정의 미디어 타입을 지원 할지 어떨지를 판정한다.
Active | 핀을 액티브 (포즈 또는 실행중) 모드로 전환한다.
Inactive | 핀을 비액티브 상태로 전환해 allocater의 메모리를 해방한다.
SetMediaType | 핀의 미디어 타입을 설정한다.
Allocator | 디폴트 메모리 allocater에의 포인터를 취득한다.
IPin Methods
QueryId | 핀의 식별자를 취득한다.
EndOfStream | 새롭게 실행 커멘드가 발행될 때까지, 추가의 데이터가 없는 것을 핀에 통지한다.
BeginFlush | 플래시 처리를 시작 하도록(듯이) 핀에 통지한다.
EndFlush | 플래시 처리를 종료하도록(듯이) 핀에 통지한다.
IMemInputPin Methods
Receive | 스트림으로부터 다음의 데이터 블록을 취득한다.

CRendererInputPin.m_pRenderer

CRendererInputPin 클래스

필터에의 포인터.

구문

CBaseRenderer *m_pRenderer;

CRendererInputPin::Active

CRendererInputPin 클래스

필터가 액티브하게 된 것을 핀에 통지한다. CBasePin::Active 메소드를 오버라이드(override) 한다.

구문

HRESULTActive(void);

반환값

HRESULT 값을 돌려준다.

CRendererInputPin::Allocator

CRendererInputPin 클래스

메모리 allocater에의 포인터를 취득한다.

구문

IMemAllocator* Allocator(void) const;

반환값

allocater의 IMemAllocator 인터페이스에의 포인터 또는 NULL 를 돌려준다.

주의

이 메소드는,CBaseInputPin::m_pAllocator 멤버 변수를 돌려준다. 이 메소드는, 인터페이스의 참조 카운트를 인크리먼트(increment)하지 않는다. 또, 엄밀하게 아크셋사메솟드이다.

CRendererInputPin::BeginFlush

CRendererInputPin 클래스

플래시 처리를 시작 한다. CBaseInputPin::BeginFlush 메소드를 오버라이드(override) 한다.

구문

HRESULT BeginFlush(void);

반환값

HRESULT 값을 돌려준다.

CRendererInputPin::BreakConnect

CRendererInputPin 클래스

접속으로부터 핀을 해방한다. CBaseInputPin::BreakConnect 메소드를 오버라이드(override) 한다.

구문

HRESULT BreakConnect(void);

반환값

HRESULT 값을 돌려준다.

CRendererInputPin::CheckMediaType

CRendererInputPin 클래스

핀이 특정의 미디어 타입을 받아들일지 어떨지를 판정한다. CBasePin::CheckMediaType 메소드를 오버라이드(override) 한다.

구문

HRESULT CheckMediaType(
    const CMediaType *pmt
    );

파라미터

pmt
지정된 미디어 타입을 저장 하고 있는 미디어 타입 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다.

CRendererInputPin::CompleteConnect

CRendererInputPin 클래스

출력 핀에의 접속을 완료한다. CBasePin::CompleteConnect 메소드를 오버라이드(override) 한다.

구문

HRESULT CompleteConnect(
    IPin *pReceivePin
    );

파라미터

pReceivePin
출력 핀의 IPin 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다.

CRendererInputPin::CRendererInputPin

CRendererInputPin 클래스

constructor　 　 메소드.

구문

CRendererInputPin(
    CBaseRenderer *pRenderer,
    HRESULT *phr,
    LPCWSTR Name
    );

파라미터

pRenderer
필터를 이행 하는 CBaseRenderer 오브젝트에의 포인터.
phr
HRESULT 값을 받는 변수에의 포인터.
Name
핀 식별자가 포함된 Unicode&153; 캐릭터 라인에의 포인터.

CRendererInputPin::EndFlush

CRendererInputPin 클래스

플래시 처리를 종료한다. CBaseInputPin::EndFlush 메소드를 오버라이드(override) 한다.

구문

HRESULT EndFlush(void);

반환값

HRESULT 값을 돌려준다.

CRendererInputPin::EndOfStream

CRendererInputPin 클래스

추가의 데이터가 없는 것을 핀에 통지한다. CBasePin::EndOfStream 메소드를 오버라이드(override) 한다.

구문

HRESULT EndOfStream(void);

반환값

HRESULT 값을 돌려준다.

CRendererInputPin::Inactive

CRendererInputPin 클래스

필터가 액티브한 것은 없어진 것을 핀에 통지한다. CBaseInputPin::Inactive 메소드를 오버라이드(override) 한다.

구문

HRESULT Inactive(void);

반환값

HRESULT 값을 돌려준다.

CRendererInputPin::QueryId

CRendererInputPin 클래스

핀의 식별자를 취득한다. CBasePin::QueryId 메소드를 오버라이드(override) 한다.

구문

HRESULT QueryId(
    LPWSTR *Id
    );

파라미터

Id
핀의 식별자가 포함된 캐릭터 라인을 받는, 변수의 주소.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는, 와이드 캐릭터 라인 "In" 를 할당해Id 파라미터에 할당한다. 호출원래는,CoTaskMemFree 함수를 사용해, 할당할 수 있었던 메모리를 해방해야 한다.

CRendererInputPin::Receive

CRendererInputPin 클래스

스트림의 다음의 미디어 샘플을 받는다. CBaseInputPin::Receive 메소드를 오버라이드(override) 한다.

구문

HRESULT Receive(
    IMediaSample *pMediaSample
    );

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다.

CRendererInputPin::SetMediaType

CRendererInputPin 클래스

접속의 미디어 타입을 설정한다. CBasePin::SetMediaType 메소드를 오버라이드(override) 한다.

구문

HRESULT SetMediaType(
    const CMediaType *pmt
    );

파라미터

pmt
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다.


CRendererPosPassThru 클래스

CRendererPosPassThru 클래스의 계층

렌더링 필터의 시크 커멘드를 처리한다.

선언 : Ctlutil.h

이 클래스는,CPosPassThru 클래스로부터 파생한다. 샘플이 닿았을 때 샘플로부터 타임 스탬프를 캐쉬하는 지원이 추가되고 있다.

CPosPassThru 클래스와 같은 방식으로 이 클래스를 사용한다. 상세한 것에 대하여는, 「CPosPassThru 」를 참조할것. 게다가 렌더링 필터는, 캐쉬된 오브젝트의 타임 스탬프를 갱신해야 한다.

  • 필터가 받은 각 샘플에 대해서,RegisterMediaTime 메소드를 호출하는 것.
  • 필터가 정지 혹은 EndFlush 호출을 받았을 때,ResetMediaTime 메소드를 호출하는 것.
  • 필터가 엔드 오브 스트림 (End-Of-Stream) 통지를 받았을 때,EOS 메소드를 호출하는 것.

이 클래스의 사용법에 대해서는,CBaseRenderer 원시 코드를 참조할것.

Public 메소드
CRendererPosPassThru | constructor 메소드.
GetMediaTime | 현재의 샘플의 타임 스탬프를 취득한다.
RegisterMediaTime | 현재의 샘플로부터 타임 스탬프를 캐쉬한다.
ResetMediaTime | 캐쉬된 타임 스탬프를 제로에 리셋 한다.
EOS | 엔드 오브 스트림 통지의 후에 캐쉬된 타임 스탬프를 업데이트 한다.

CRendererPosPassThru::CRendererPosPassThru

CRendererPosPassThru 클래스

constructor　 　 메소드.

구문

CRendererPosPassThru(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
    IPin *pPin
);

파라미터

pName
오브젝트의 이름에의 포인터, 디버그용. 이 파라미터를 스태틱 메모리에 할당하는 것.
pUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되고 있다면, 집성 된 오브젝트의 IUnknown 인터페이스에의 포인터를 건네주는 것. 그 이외의 경우, 이 파라미터는 제로로 설정한다.
phr
HRESULT 값에의 포인터. 무시된다.
pPin
필터의 입력 핀의IPin 인터페이스에의 포인터

CRendererPosPassThru::EOS

CRendererPosPassThru 클래스

엔드 오브 스트림 통지의 후에 캐쉬된 타임 스탬프를 업데이트 한다.

구문

HRESULT EOS(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_FAIL | 실패. 아마 필터가 스트리밍 하고 있지 않다.

주의

필터가 엔드 오브 스트림 통지 (IPin::EndOfStream )를 받았을 때, 이 메소드를 호출해야 한다. 이 메소드는 스톱 위치와 동일한 2 개의 캐쉬된 타임 스탬프를 세트 해,IMediaStream::GetCurrentPosition 메소드에 올바른 스트림의 끝의 값을 돌려주게 한다.

CRendererPosPassThru::GetMediaTime

CRendererPosPassThru 클래스

현재의 샘플의 타임 스탬프를 취득한다.

구문

HRESULT GetMediaTime(
    LONGLONG *pStartTime,
    LONGLONG *pEndTime
);

파라미터

pStartTime
시작 타임을 받는 변수에의 포인터, 현재의 타임 포맷의 단위.
pEndTime
종료 타임을 받는 변수에의 포인터, 현재의 타임 포맷의 단위. NULL 도 가능.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_INVALIDARG | 이 포맷에의 변환은 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

이 메소드는 CPosPassThru::GetMediaTime 메소드를 오버라이드(override) 한다. CPosPassThru::ConvertTimeFormat 메소드를 호출하는 것으로, 타임 스탬프값은 현재의 타임 포맷에 변환된다.

CRendererPosPassThru::RegisterMediaTime

CRendererPosPassThru 클래스

현재의 샘플로부터 타임 스탬프를 캐쉬한다.

구문

HRESULT RegisterMediaTime(
    IMediaSample *pMediaSample
);

HRESULT RegisterMediaTime(
    LONGLONG StartTime,
    LONGLONG EndTime
);

파라미터

pMediaSample
샘플의 IMediaSample 인터페이스에의 포인터.
StartTime
샘플 시작 타임, 100 나노초단위.
EndTime
샘플 종료 타임, 100 나노초단위.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_MEDIA_TIME_NOT_SET | 샘플은 타임 스탬프되어 있지 않다.

주의

이 메소드는 현재의 샘플로부터 타임 스탬프를 스토어 한다. GetMediaTime 메소드는 같은 값을 취득한다.

필터는 받은 각 샘플에 대해 이 메소드를 호출해야 한다. 이 메소드는 샘플에의 포인터나 타임 샘플 그것 자신의 어느 쪽인지를 받기 위해서(때문에) overload 된다.

CRendererPosPassThru::ResetMediaTime

CRendererPosPassThru 클래스

캐쉬된 타임 스탬프를 제로에 리셋 한다.

구문

HRESULT ResetMediaTime(void);

반환값

S_OK 를 돌려준다.

주의

RegisterMediaTime 가 캐쉬한 타임 스탬프가 무효가 될 때마다, 필터는 이 메소드를 호출해야 한다. 특히,IPin::EndFlush 와 IMediaFilter::Stop 메소드에 대응할 때에 이 메소드를 호출해야 한다.

이 메소드가 불려 간 후,GetMediaTime 메소드는 시작 타임과 종료 타임에 제로를 돌려준다.


CSeekingPassThru 클래스

CPosPassThru 오브젝트 및 CRendererPosPassThru 오브젝트를 생성 하는 헬퍼 오브젝트.

선언 : Seekpt.h

CPosPassThru 클래스 및 CRendererPosPassThru 클래스는, 시크 커멘드를 업 스트림에 건네주는 헬퍼 오브젝트이다. CSeekingPassThru 클래스는, 이러한 헬퍼 오브젝트를 생성 하는 헬퍼 오브젝트이다. DirectShow 에서는, 이 클래스를 COM 컴퍼넌트로서 패키지화하는 것으로, 지원을 추가하고 있다. 상세한 것에 대하여는, 「SeekingPassThru 」를 참조할것.

이 클래스는,ISeekingPassThru 인터페이스를 공개한다. ISeekingPassThru::Init 메소드는, 오브젝트를 초기화한다. 오브젝트가 초기화되면(자), 필터는 IMediaSeeking 인터페이스 및 IMediaPosition 인터페이스에 대해 오브젝트에 조회할 수 있다.

필터는,CreatePosPassThru 헬퍼 함수를 호출해, 이 오브젝트의 인스턴스를 생성, 초기화할 수 있다. 다음의 샘플 코드는, 필터의 QueryInterface 메소드로부터의 것이다. 이 코드에서는, 헬퍼 오브젝트를 생성 해, 시크 인터페이스에 대해 조회하고 있다.

if (riid == IID_IMediaPosition || riid == IID_IMediaSeeking) {
    if (m_pPosition == NULL)
    {
        HRESULT hr = CreatePosPassThru(GetOwner(), FALSE,
                        m_pFilter->m_pPin, &m_pPosition);
        if (FAILED(hr))
            return hr;
    }
    return m_pPosition->QueryInterface(riid, ppv);
}

Public 메소드
CSeekingPassThru | constructor 메소드.
~CSeekingPassThru | 소멸자 메소드.
CreateInstance | 오브젝트의 인스턴스를 생성 한다.
ISeekingPassThru 메소드
Init | 오브젝트를 초기화한다.

CSeekingPassThru::CSeekingPassThru

CSeekingPassThru 클래스

constructor　 　 메소드.

구문

CPosPassThru(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
);

파라미터

pName
오브젝트의 이름이 포함된 캐릭터 라인. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되었을 경우는, 집성 오브젝트의 IUnknown 인터페이스에 포인터를 건네준다. 그 이외의 경우는, 이 파라미터에 NULL 를 설정한다.
phr
HRESULT 값에의 포인터. 무시된다.

CSeekingPassThru::~CSeekingPassThru

CSeekingPassThru 클래스

소멸자 메소드.

구문

~CPosPassThru(void);

CSeekingPassThru::CreateInstance

CSeekingPassThru 클래스

오브젝트의 인스턴스를 생성 한다. 이 메소드는, 클래스 팩토리를 통해서 오브젝트의 생성을 지원 한다. 상세한 것에 대하여는, 「CFactoryTemplate 」를 참조할것.

구문

static CUnknown *CreateInstance(
    LPUNKNOWN pUnk,
    HRESULT *phr
);

파라미터

pUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되었을 경우는, 오브젝트의 IUnknown 인터페이스에 포인터를 건네준다. 그 이외의 경우는, 이 파라미터에 NULL 를 설정한다.
phr
HRESULT 값에의 포인터. 무시된다.

반환값

새로운 CSeekingPassThru 오브젝트에의 포인터를 돌려준다.

CSeekingPassThru::Init

CSeekingPassThru 클래스

오브젝트를 초기화한다.

구문

HRESULT Init(
    BOOL bSupportRendering,
    IPin *pPin
);

파라미터

bSupportRendering
[in] 파일이 렌더러인가 어떤가를 지정하는 불리언 값. 필터가 렌더러의 경우는 값 TRUE 를 사용한다. 렌더러가 아닌 경우는 FALSE 를 사용한다.
pPin
필터의 입력 핀 위에의 IPin 인터페이스에의 포인터.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_FAIL | 오브젝트는 이미 초기화되고 있다.
E_OUTOFMEMORY | 오브젝트를 생성하기 위한 충분한 메모리가 없다.

주의

bSupportRendering 의 값이 TRUE 의 경우, 이 메소드는 CRendererPosPassThru 클래스의 인스턴스를 생성 한다. TRUE 가 아닌 경우는,CPosPassThru 클래스의 인스턴스를 생성 한다.


CSource 클래스

CSource 클래스의 계층

소스 필터 이행의 base class.

선언: Source.h

CSource 로부터 파생한 필터에는,CSourceStream 클래스로부터 파생한 1 개(살) 또는 복수의 출력 핀이 포함된다. 각각의 출력 핀은, 미디어 샘플을 다운 스트림에 푸쉬 하는 워커 thread를 생성 한다.

출력 핀을 이행 하려면 , 다음의 조작을 실시한다.

  • CSourceStream 로부터 클래스를 파생한다.
  • CSourceStream::GetMediaType 메소드를 오버라이드(override) 해, 가능한 경우는 핀의 미디어 타입을 검증하는 CSourceStream::CheckMediaType 메소드도 오버라이드(override) 한다.
  • 핀의 버퍼 조건을 돌려주는 CBaseOutputPin::DecideBufferSize 메소드를 이행 한다.
  • 미디어 샘플 버퍼에 데이터를 묻는 CSourceStream::FillBuffer 메소드를 이행 한다.

필터를 이행 하려면 , 다음의 조작을 실시한다.

  • CSource 로부터 클래스를 파생한다.
  • constructor　 　 으로,CSourceStream 로부터 파생한 1 개(살) 또는 복수의 핀을 생성 한다. 핀은, constructor　 　 메소드로 자동적으로 필터에 추가되어 소멸자 메소드로 삭제된다.

복수의 thread간에 필터 상태를 동기 하려면 ,CSource::pStateLock 메소드를 호출한다. 이 메소드는, 필터 상태의 크리티컬 섹션에의 포인터를 돌려준다. CAutoLock 클래스를 사용해, 크리티컬 섹션을 보관 유지한다. 다음에 나타내도록(듯이), 핀으로부터는 핀의 CBasePin.m_pFilter 멤버 변수로부터 pStateLock 에 액세스 할 수 있다.

CAutoLock lock(m_pFilter->pStateLock());

주 : CSource 클래스는, 데이터 플로우의 푸쉬 모델을 지원 하도록(듯이) 설계되고 있다. 이 클래스는, 파일 리더 필터의 생성에는 추천 되지 않는다. 파일 리더는,IAsyncReader 인터페이스를 개입시켜, 프르모델을 지원 할 필요가 있다. 상세한 것에 대하여는, 「필터 개발자가 사용하는 데이터 플로우」를 참조할것.

프로텍트 멤버 변수
m_iPins | 필터 위에의 핀수.
m_paStreams | 핀의 배열.
m_cStateLock | 필터 상태를 보호하는 크리티컬 섹션 오브젝트.
Public 메소드
CSource | constructor 메소드.
~CSource | 소멸자 메소드.
GetPinCount | 필터 위에의 핀수를 취득한다.
GetPin | 핀을 취득한다.
pStateLock | 필터의 크리티컬 섹션 오브젝트에의 포인터를 취득한다.
AddPin | 필터에 새로운 출력 핀을 추가한다.
RemovePin | 필터로부터 지정된 핀을 없앤다.
FindPinNumber | 필터상으로부터, 지정된 수의 핀을 취득한다.
IBaseFilter Methods
FindPin | 지정된 식별자를 가지는 핀을 취득한다.

CSource.m_iPins

CSource 클래스

필터 위에의 핀수.

구문

int m_iPins;

CSource.m_paStreams

CSource 클래스

핀의 배열.

구문

CSourceStream **m_paStreams;

CSource.m_cStateLock

CSource 클래스

필터 상태를 보호하는 크리티컬 섹션 오브젝트. pStateLock 헬퍼 메소드는, 이 멤버 변수에의 포인터를 돌려준다.

구문

CCritSec m_cStateLock;

CSource::AddPin

CSource 클래스

새로운 출력 핀을 필터에 추가한다.

구문

HRESULT AddPin(
    CSourceStream *pStream
    );

파라미터

pStream
핀을 이행 하는 CSourceStream 오브젝트에의 포인터.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.

주의

CSourceStream constructor　 　 은 이 메소드를 호출해, 출력 핀을 필터에 추가한다.

CSource::CSource

CSource 클래스

constructor　 　 메소드.

구문

CSource(
    TCHAR *pName,
    LPUNKNOWN lpunk,
    CLSID clsid
    );

파라미터

pName
오브젝트의 이름이 포함된 캐릭터 라인에의 포인터. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
lpunk
이 오브젝트의 소유자에게로의 포인터. 이 오브젝트가 집성 되었을 경우는, 상속 클래스의 CreateInstance 함수에게 건네진 집성 오브젝트의 IUnknown 인터페이스에, 포인터를 건네준다. 그 이외의 경우는, 이 파라미터에 NULL 를 설정한다.
clsid
필터의 클래스 식별자.

CSource::~CSource

CSource 클래스

소멸자 메소드.

구문

~CSource(void);

CSource::FindPin

CSource 클래스

지정된 식별자를 가지는 핀을 취득한다. IBaseFilter::FindPin 메소드를 이행 한다.

구문

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

파라미터

Id
핀을 식별하는, NULL 로 종료하는 캐릭터 라인에의 포인터.
ppPin
핀의 IPin 인터페이스에의 포인터를 받는 변수의 주소. 메소드가 실패 하면,*ppPin 는 NULL 로 설정된다.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.
VFW_E_NOT_FOUND | 이 식별자를 가지는 핀은 발견되지 않았다.

주의

최초의 핀은,"1", 2 번째의 핀은 "2", 이후 같이이다. 상세한 것에 대하여는, 「CSourceStream::QueryId 」를 참조할것.

CSource::FindPinNumber

CSource 클래스

필터 위에의 핀을 지정한다.

구문

int FindPinNumber(
    IPin *iPin
    );

파라미터

iPin
핀의 IPin 인터페이스에의 포인터.

반환값

핀 번호를 돌려준다. 필터상에 핀이 발견되지 않았던 경우는 -1 을 돌려준다. 최초의 핀의 번호는 0 이다.

CSource::GetPin

CSource 클래스

핀을 취득한다. 순수 가상 메소드 CBaseFilter::GetPin 를 이행 한다.

구문

CBasePin *GetPin(
    int n
    );

파라미터

n
지정된 핀의 수.

반환값

핀을 이행 하는 CBasePin 오브젝트에의 포인터를 돌려준다. 인덱스가 범위외의 경우는 NULL 를 돌려준다.

CSource::GetPinCount

CSource 클래스

필터 위에의 핀의 수를 취득한다. 순수 가상 메소드 CBaseFilter::GetPinCount 를 이행 한다.

구문

int GetPinCount(void);

반환값

필터 위에의 핀의 수를 돌려준다.

CSource::pStateLock

CSource 클래스

필터의 크리티컬 섹션 오브젝트에의 포인터를 취득한다.

구문

CCritSec* pStateLock(void);

반환값

m_cStateLock 멤버 변수에의 포인터를 돌려준다.

CSource::RemovePin

CSource 클래스

필터로부터 지정된 핀을 없앤다. 이 메소드는 핀을 삭제하지 않는다.

구문

HRESULT RemovePin(
    CSourceStream *pStream
    );

파라미터

pStream
핀을 이행 하는 CSourceStream 오브젝트에의 포인터.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
S_FALSE | 필터에는, 이 핀은 포함되지 않았다.

주의

CSourceStream 소멸자는 이 메소드를 호출해, 필터로부터 출력 핀을 없앤다.


CSourcePosition 클래스

CSourcePosition 클래스의 계층

CSourcePosition 는, 소스 필터에 IMediaPosition 인터페이스를 이행하기 위한 추상 클래스이다.

이 클래스는 사용하지 않는다. 소스 필터가 시크 가능하면,IMediaPosition 대신에 IMediaSeeking 인터페이스를 공개해야 한다. 이 목적으로 CSourceSeeking base class를 사용할 수가 있다.

CSourcePosition::put_CurrentPosition ,CSourcePosition::put_StopTime , 또는 CSourcePosition::put_Rate 가 불려 가면(자),CSourcePosition 는 순수 가상 멤버 함수 CSourcePosition::ChangeStart ,CSourcePosition::ChangeStop , 또는 CSourcePosition::ChangeRate 를 각각 호출한다. 상속 클래스내에서 이러한 함수를 오버라이드(override) 한다.

Protected 데이터 멤버

m_Duration | 스트림의 시간폭.
m_pLock | 락을 위한 CCritSec 오브젝트에의 포인터.
m_Rate | 샘플 레이트.
m_Start | 시작 타임.
m_Stop | 종료 타임.

멤버 함수

CSourcePosition CSourcePosition 오브젝트를 생성 한다.

오버라이드(override) 가능한 멤버 함수

ChangeRate | 이 순수 가상 함수를 오버라이드(override) 해, 레이트 프로퍼티가 변경된 통지를 처리한다.
ChangeStart | 이 순수 가상 함수를 오버라이드(override) 해, 시작 위치 프로퍼티가 변경된 통지를 처리한다.
ChangeStop | 이 순수 가상 함수를 오버라이드(override) 해, 종료 위치 프로퍼티가 변경된 통지를 처리한다.

이행 되는 IMediaPosition 메소드

get_CurrentPosition | 현재는 이행되어 있지 않다.
get_Duration | 미디어의 합계 시간폭을 취득한다.
get_PrerollTime | 현재는 이행되어 있지 않다.
get_Rate | 미디어의 보통 재생을 기준으로 한 재생 레이트를 취득한다.
get_StopTime | 재생이 정지해야 할 미디어내의 위치를 취득한다.
put_CurrentPosition | 재생이 시작 해야 할 미디어내의 위치를 설정한다.
put_PrerollTime | 현재는 이행되어 있지 않다.
put_Rate | 미디어의 보통 재생을 기준으로 한 재생 레이트를 설정한다.
put_StopTime | 재생이 정지해야 할 미디어내의 위치를 설정한다.

CSourcePosition::ChangeRate

CSourcePosition 클래스

이 멤버 함수를 오버라이드(override) 해, 샘플 레이트의 변경 통지를 처리한다.

구문

virtual HRESULT ChangeRate(void) PURE;

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 멤버 함수는,IMediaPosition::put_Rate 의 호출에 의해 레이트가 변경되면(자) 불려 간다. 이 함수를 오버라이드(override) 해 송신된 데이터의 레이트를 변경한다. 보통은,CBaseInputPin::BeginFlush 및 CBaseInputPin::EndFlush 의 호출의 후에, 새로운타임 스탬프가 마크 된 샘플을 송신한다.

CSourcePosition::ChangeStart

CSourcePosition 클래스

이 멤버 함수를 오버라이드(override) 해, 시작 타임의 변경 통지를 처리한다.

구문

virtual HRESULT ChangeStart(void) PURE;

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 멤버 함수는,IMediaPosition::put_CurrentPosition 의 호출에 의해 새로운 시작 위치가 요구되면(자) 불려 간다. 이 함수를 오버라이드(override) 해 송신된 데이터를 변경한다. 보통은,CBaseInputPin::BeginFlush 및 CBaseInputPin::EndFlush 의 호출의 후에, 새로운 타임 스탬프가 마크 된 샘플을 송신한다.

CSourcePosition::ChangeStop

CSourcePosition 클래스

이 멤버 함수를 오버라이드(override) 해, 종료 타임의 변경 통지를 처리한다.

구문

virtual HRESULT ChangeStop(void) PURE;

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 멤버 함수는,IMediaPosition::put_StopTime 의 호출에 의해 정지 위치가 변경되면(자) 불려 간다. 이 함수를 오버라이드(override) 해, 올바른 종료 타임이 설정되어 있는 것을 확인한다. 보통은,CBaseInputPin::BeginFlush 및 CBaseInputPin::EndFlush 의 호출의 후에 데이터를 재발송신 한다.

CSourcePosition::CSourcePosition

CSourcePosition 클래스

CSourcePosition 오브젝트를 생성 한다.

구문

CSourcePosition(

  const TCHAR *pName,

  LPUNKNOWN pUnk,

  HRESULT *phr,

  CCritSec *pLock

  );

파라미터

pName
데밧깅 목적으로 CSourcePosition constructor　 　 으로 사용되는 오브젝트의 이름에의 포인터.
pUnk
이 오브젝트의 소유자에게로의 포인터.
phr
결과 정보를 돌려주는 HRESULT 값에의 포인터.
pLock
락을 위한 CCritSec 오브젝트에의 포인터.

반환값

반환값 없음.

주의

스태틱 메모리에 pName 파라미터를 할당한다. 이 이름은, 오브젝트의 생성 및 삭제를 실시하는 데밧깅 단말상에 나타난다.

CSourcePosition::get_CurrentPosition

CSourcePosition 클래스

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT get_CurrentPosition(
  REFTIME *pllTime
);

파라미터

pllTime
돌려주어진 시작 타임에의 포인터 (초단위로 나타난 double 값).

반환값

E_NOTIMPL 를 돌려준다.

주의

실제로 조작하고 있는 데이터를 돌려줄 수가 있는 경우는 이 메소드를 오버라이드(override) 한다. 시작 위치는, 레이트의 전에 적용된다. 따라서, 보통의 재생 속도에서의 위치가 된다.

CSourcePosition::get_Duration

CSourcePosition 클래스

미디어 스트림의 시간폭을 취득한다.

구문

HRESULT get_Duration(

  REFTIME *plength

  );

파라미터

plength
돌려주어진 미디어 스트림의 길이에의 포인터.

반환값

pLength 가 무효인 경우는, E_POINTER 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

주의

시간폭은 보통의 재생 속도를 상정하고 있다. 따라서, 레이트의 영향을 받지 않는다.

CSourcePosition::get_PrerollTime

CSourcePosition 클래스

포인터를 유효하게 하지만,프리로르의 취득은 현재 이행되어 있지 않다.

구문

HRESULT get_PrerollTime(

  REFTIME *pllTime

  );

파라미터

pllTime
돌려주어진프리로르타임에의 포인터 (초단위로 나타난 double 값).

반환값

pllTime 가 무효인 경우는, E_POINTER 를 돌려준다. 그 이외의 경우는, E_NOTIMPL 를 돌려준다.

주의

프리로르타임이란, 테이프 플레이어등의 랜덤이 아닌 액세스 디바이스가 롤링을 시작 해야 할 시작 위치보다 전의 시간.

CSourcePosition::get_Rate

CSourcePosition 클래스

보통의 재생 속도를 기준으로 한 재생 레이트를 취득한다.

구문

HRESULT get_Rate(

  double *pdRate

  );

파라미터

pdRate
돌려주어진 레이트에의 포인터.

반환값

pdRate 가 무효인 경우는, E_POINTER 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

주의

레이트 1.0 은 보통의 재생 속도를 나타낸다. 레이트 0.5 는, 반의 속도를 나타낸다. 레이트 -1. 0 은 역방향의 보통 속도를 나타낸다.

CSourcePosition::get_StopTime

CSourcePosition 클래스

미디어 스트림이 정지하는 시간을 취득한다.

구문

HRESULT get_StopTime(

  REFTIME *pllTime

  );

파라미터

pllTime
돌려주어진 종료 타임에의 포인터 (초단위로 나타난 double 값).

반환값

pllTime 가 무효인 경우는, E_POINTER 를 돌려준다. 그 이외의 경우는, S_OK 를 돌려준다.

주의

종료 타임은, 제로와 재생이 정지하는 미디어의 시간폭과의 사이의 위치이다.

정지 위치는, 레이트의 전에 적용된다. 따라서, 보통의 재생 속도에서의 위치가 된다.

CSourcePosition::put_CurrentPosition

CSourcePosition 클래스

재생이 시작 해야 할 미디어 스트림내의 타임을 설정한다.

구문

HRESULT put_CurrentPosition(
  REFTIME llTime
  );

파라미터

llTime
시작 타임은, 초단위의 double 값으로서 나타내진다.

반환값

CSourcePosition::ChangeStart 의 호출로부터의 HRESULT 값을 돌려준다.

주의

시작 타임이란, 제로와 시간폭과의 사이의, 다음의 실행 커멘드가 발행되었을 때에 재생이 시작 해야 할 미디어의 위치이다.

포즈 상태로 시작 위치를 설정했을 경우, 실행 커멘드가 발행되면(자) 새로운 시작 위치로부터 재생이 재개된다.

시작 위치는, 레이트의 전에 적용된다. 따라서, 보통의 재생 속도에서의 위치가 된다.

CSourcePosition::put_PrerollTime

CSourcePosition 클래스

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT put_PrerollTime(
   REFTIME llTime
);

파라미터

llTime
설정하는 프리로르타임.

반환값

E_NOTIMPL 를 돌려준다.

주의

프리로르타임이란, 테이프 플레이어등의 랜덤이 아닌 액세스 디바이스가 롤링을 시작 해야 할 시작 위치보다 전의 시간.

CSourcePosition::put_Rate

CSourcePosition 클래스

보통의 속도를 기준으로 한 재생 레이트를 설정한다.

구문

HRESULT put_Rate(
  double dRate
  );

파라미터

dRate
설정하는 레이트.

반환값

CSourcePosition::ChangeRate 의 호출로부터의 HRESULT 값을 돌려준다.

주의

이 프로퍼티를 사용 하면, 어플리케이션은 보통의 디폴트 재생 속도를 기준에 재생을 가속화 또는 저속화할 수가 있다. 레이트 1.0 은 보통의 재생 속도를 나타낸다. 2.0 을 지정 하면, 보통 레이트의 2 배로 재생을 한다. 매초 10 프레임 (fps)으로 생성 된 비디오는, 리소스가 허락하면 20 fps 로 재생된다. 오디오 스트림을 보통 이상의 속도로 재생 하면, 프레임이 드롭 되는 대신에 피치가 높아진다.

부의 값의 레이트는, 역방향의 재생을 나타낸다. 모든 미디어로 역방향 재생이 지원 된다고는 할 수 없다.

CSourcePosition::put_StopTime

CSourcePosition 클래스

미디어 스트림이 정지하는 시간을 설정한다.

구문

HRESULT put_StopTime(
  REFTIME llTime
  );

파라미터

llTime
종료 타임은, 초단위의 double 값으로서 나타내진다.

반환값

CSourcePosition::ChangeStop 의 호출로부터의 HRESULT 값을 돌려준다.

주의

종료 타임은, 제로와 재생이 정지하는 미디어의 시간폭과의 사이의 위치이다.

정지 위치는, 레이트의 전에 적용된다. 따라서, 보통의 재생 속도에서의 위치가 된다.


CSourceSeeking 클래스

CSourceSeeking 클래스의 계층

1 개의 출력 핀을 가지는 소스 필터로, 시크를 이행 하는 추상 클래스.

선언 : Ctlutil.h

이 클래스는,IMediaSeeking 인터페이스를 지원 해, 모든 IMediaSeeking 메소드에 디폴트의 이행을 제공한다. 프로텍트 멤버 변수는, 시작 타임, 종료 타임, 및 현재의 레이트를 저장 한다. 디폴트에서는, 이 클래스에 의해 지원 되는 유일한 타임 포맷은,TIME_FORMAT_MEDIA_TIME (100 나노초단위)이다.

CSourceSeeking 오브젝트는, 시작 위치, 정지 위치, 또는 재생 레이트가 변경될 때마다, 다음과 같이 대응하는 순수 가상 메소드를 호출한다.

  • 시작 위치 : ChangeStart
  • 정지 위치 : ChangeStop
  • 재생 레이트 : ChangeRate

상속 클래스는, 이러한 메소드를 이행 해야 한다. 시크 처리 후, 필터는 다음 일을 실시할 필요가 있다.

  1. 다운 스트림의 입력 핀으로 IPin::BeginFlush 메소드를 호출한다.
  2. 데이터를 제공하는 워커 thread를 정지한다.
  3. 입력 핀으로 IPin::EndFlush 메소드를 호출한다.
  4. 워커 thread를 재기동한다.
  5. 입력 핀으로 IPin::NewSegment 메소드를 호출한다.
  6. 최초의 샘플로 비계속 프로퍼티를 설정한다. IMediaSample::SetDiscontinuity 메소드를 호출한다.

워커 thread가 블록 되어 샘플 출력의 대기 상태가 되어 있는 경우는,BeginFlush 를 호출해 워커 thread를 해방한다.

스텝 2 로, thread에 의한 데이터의 송신이 정지한 것을 확인한다. 이행에 따라서는, thread가 종료하는 것을 기다리는지, 또는 thread가 하등의 응답을 나타낼 때까지 기다릴 필요가 있다. 필터로 CSourceStream 클래스를 사용하고 있는 경우,CSourceStream::Stop 메소드는, 워커 thread가 응답할 때까지 대기 상태가 된다.

이상적이게는, 새로운 세그먼트(segment) (스텝 5)가 워커 thread로부터 제공되는 것이 바람직하다. 이것은, 필터가 샘플을 사용해 계속해 처리하는 한,CSourceSeeking 오브젝트에 의해도 실행할 수 있다.

다음의 예는, 가능한 이행을 나타내고 있다. 여기에서는, 소스 필터의 출력 핀이 CSourceSeeking 와 CSourceStream 로부터 파생하는 것을 상정하고 있다. 이 예에서는, 스텝 1 ~ 4 를 실행하는 헬퍼 메소드 UpdateFromSeek 를 정의하고 있다. CSourceStream::OnThreadStartPlay 메소드는 오버라이드(override) 되어 새로운 세그먼트(segment)를 보내는 것과 동시에, 비연속을 나타내는 플래그를 설정한다. 워커 thread는 이 플래그를 픽업 해,IMediaSample::SetDiscontinuity 를 호출한다.

void CMyStream::UpdateFromSeek()
{
    if (ThreadExists())
    {
        DeliverBeginFlush();
        Stop();
        DeliverEndFlush();
        Run();
    }
}

HRESULT CMyStream::OnThreadStartPlay()
{
    m_bDiscontinuity = TRUE;
    return DeliverNewSegment(m_rtStart, m_rtStop, m_dRateSeeking);
}

프로텍트 멤버 변수
m_rtDuration | 스트림이 재생되는 시간.
m_rtStart | 시작 타임.
m_rtStop | 종료 타임.
m_dRateSeeking | 재생 레이트.
m_dwSeekingCaps | 시크 능력.
m_pLock | 락을 위한 크리티컬 섹션 오브젝트에의 포인터.
프로텍트 메소드
CSourceSeeking | constructor 메소드.
순수 가상 메소드
ChangeRate | 재생 레이트가 변경되었을 때에 불려 간다.
ChangeStart | 시작 위치가 변경되었을 때에 불려 간다.
ChangeStop | 정지 위치가 변경되었을 때에 불려 간다.
IMediaSeeking 메소드
IsFormatSupported | 지정된 타임 포맷이 지원 되고 있는지 어떤지를 판정한다.
QueryPreferredFormat | 오브젝트의 우선 타임 포맷을 취득한다.
SetTimeFormat | 타임 포맷을 설정한다.
IsUsingTimeFormat | 지정된 타임 포맷이, 현재 사용되고 있는 포맷화 제발을 판정한다.
GetTimeFormat | 현재의 타임 포맷을 취득한다.
GetDuration | 스트림의 시간폭을 취득한다.
GetStopPosition | 스트림의 시간폭에 대해서, 재생이 정지하는 타임을 취득한다.
GetCurrentPosition | 스트림의 합계 시간폭에 대한, 현재의 위치를 취득한다.
GetCapabilities | 스트림의 모든 시크 능력을 취득한다.
CheckCapabilities | 스트림으로 지정된 시크 능력이 있을지 어떨지를 조회한다.
ConvertTimeFormat | 1 개의 타임 포맷화등별의 타임 포맷으로 변환한다.
SetPositions | 현재의 위치와 정지 위치를 설정한다.
GetPositions | 현재의 위치와 정지 위치를 취득한다.
GetAvailable | 시크가 유효한 타임의 범위를 취득한다.
SetRate | 재생 레이트를 설정한다.
GetRate | 재생 레이트를 취득한다.
GetPreroll | 프리로르타임을 취득한다.

CSourceSeeking.m_rtDuration

CSourceSeeking 클래스

스트림의 시간폭. 디폴트에서는, 이 값은 m_rtStop 멤버 변수의 값으로 설정된다.

구문

CRefTime m_rtDuration;

CSourceSeeking.m_rtStart

CSourceSeeking 클래스

시작 타임. 디폴트에서는, 이 값은 제로로 설정된다.

구문

CRefTime m_rtStart;

CSourceSeeking.m_rtStop

CSourceSeeking 클래스

종료 타임. 디폴트에서는, 이 값은 매우 큰 수치로 설정된다. 상속 클래스는, constructor　 　 에 대해, 또는 필터가 초기화되었을 때에, 이 값을 리셋 할 수 있다.

구문

CRefTime m_rtStop;

CSourceSeeking.m_dRateSeeking

CSourceSeeking 클래스

재생 레이트. 디폴트에서는, 이 값은 1.0 으로 설정된다.

구문

double m_dRateSeeking;

CSourceSeeking.m_dwSeekingCaps

CSourceSeeking 클래스

시크 능력.

구문

DWORD m_dwSeekingCaps;

주의

디폴트에서는, 이 값은 다음의 플래그의 비트마다의 편성으로 설정된다.

  • AM_SEEKING_CanSeekForwards
  • AM_SEEKING_CanSeekBackwards
  • AM_SEEKING_CanSeekAbsolute
  • AM_SEEKING_CanGetStopPos
  • AM_SEEKING_CanGetDuration

필터가 다른 능력의 모임을 지원 하고 있는 경우, 이 값을 오버라이드(override) 할 필요가 있다.

CSourceSeeking.m_pLock

CSourceSeeking 클래스

락을 위한 크리티컬 섹션 오브젝트에의 포인터.

구문

CCritSec *m_pLock;

CSourceSeeking::ChangeRate

CSourceSeeking 클래스

재생 레이트가 변경되었을 때에 불려 간다.

구문

virtual HRESULT ChangeRate(void) PURE;

반환값

HRESULT 값을 돌려준다.

주의

SetRate 메소드는, 이 클래스를 호출한다. 이 클래스는, 상속 클래스가 이행 해야 한다. SetRate 메소드는,m_dRateSeeking 멤버 변수를 갱신하지만, 새로운 값을 확인하지 않는다. 레이트 0 은, 항상 거부된다. 제로 이하의 레이트는, 역재생을 나타낸다. 대부분의 필터는, 부의 레이트를 지원 하고 있지 않다.

다음의 예는, 가능한 이행을 나타내고 있다.

HRESULT CMyStream::ChangeRate( )
{
    {
        CAutoLock cAutoLockSeeking(CSourceSeeking::m_pLock);
        if( m_dRateSeeking <= 0 ) {
            m_dRateSeeking = 1.0;  // 타당한 값에 리셋 한다.
            return E_FAIL;
        }
    }
    UpdateFromSeek();
    return S_OK;
}

CSourceSeeking::ChangeStart

CSourceSeeking 클래스

시작 위치가 변경되었을 때에 불려 간다.

구문

virtual HRESULT ChangeStart(void) PURE;

반환값

HRESULT 값을 돌려준다.

주의

SetPositions 메소드는, 시작 위치가 변경되었을 경우에 이 메소드를 호출한다. 이것은, 순수 가상 메소드이며, 상속 클래스는 이 메소드를 이행 해야 한다. 시크 처리 후는, 타임 스탬프는 제로로부터 한번 더 시작 할 필요가 있다. 또, 미디어 타임은, 새로운 시작 타임을 반영할 필요가 있다. 다음의 예는, 가능한 이행을 나타내고 있다.

HRESULT CMyStream::ChangeStart( )
{
    m_rtSampleTime = 0;          // 타임 스탬프를 리셋 한다.
    m_rtMediaTime = m_rtStart;   // 미디어 타임을 리셋 한다.
    UpdateFromSeek();
    return S_OK;
}

CSourceSeeking::ChangeStop

CSourceSeeking 클래스

정지 위치가 변경되었을 때에 불려 간다.

구문

virtual HRESULT ChangeStop(void) PURE;

반환값

HRESULT 값을 돌려준다.

주의

SetPositions 메소드는, 정지 위치가 변경되었을 경우에 이 메소드를 호출한다. 이것은 순수 가상 메소드이며, 상속 클래스는 이 메소드를 이행 해야 한다. 다음의 예는, 가능한 이행을 나타내고 있다.

HRESULT CMyStream::ChangeStop( )
{
    UpdateFromSeek();
    return S_OK;
}

CSourceSeeking::CheckCapabilities

CSourceSeeking 클래스

지정된 시크 능력이 있을지 어떨지를 스트림에 조회한다. IMediaSeeking::CheckCapabilities 메소드를 이행 한다.

구문

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

파라미터

pCapabilities
1 개(살) 또는 복수의 AM_SEEKING_SEEKING_CAPABILITIES 속성의, 비트마다의 편성에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_FALSE | pCapabilities 의 모든 능력은 존재하지 않는다.
S_OK | pCapabilities 의 모든 능력이 존재한다.
E_POINTER | NULL 포인터 인수.

주의

이행 되고 있도록(듯이), 이 메소드는 m_dwSeekingCaps 멤버 변수에 대한 *pCapabilities 의 값을 체크한다. 그러나,IMediaSeeking::CheckCapabilities 메소드로 설명하고 있도록(듯이), 이 메소드는 *pCapabilities 을 m_dwSeekingCaps 와 동일하게 설정하지 않는다. 또, 지정된 능력의 모두 존재하지 않는 경우, 이 메소드는 E_FAIL 를 돌려주지 않는다. 다음에 나타내는 것은, 보다 완전한 이행이다.

DWORD dwCaps;
HRESULT hr = GetCapabilities(&dwCaps);
if (SUCCEEDED(hr))
{
    dwCaps &= *pCapabilities;
    hr =  dwCaps ?  ( dwCaps == *pCapabilities ?  S_OK : S_FALSE ) : E_FAIL;
    *pCapabilities = dwCaps;
}
else *pCapabilities = 0;
return hr;

CSourceSeeking::ConvertTimeFormat

CSourceSeeking 클래스

1 개의 포맷을 다른 포맷으로 변환한다. IMediaSeeking::ConvertTimeFormat 메소드를 이행 한다.

구문

HRESULT ConvertTimeFormat(
    LONGLONG *pTarget,
    const GUID *pTargetFormat,
    LONGLONG Source,
    const GUID *pSourceFormat
);

파라미터

pTarget
변환된 타임을 받는 변수에의 포인터.
pTargetFormat
목적의 포맷의타임 포맷 GUID 에의 포인터. NULL 의 경우는, 현재의 포맷이 사용된다.
Source
변환되는 타임값.
pSourceFormat
변환하는 포맷의 타임 포맷 GUID 에의 포인터. NULL 의 경우는, 현재의 포맷이 사용된다.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

base class에 의해 지원 되는 유일한 타임 포맷은, TIME_FORMAT_MEDIA_TIME (100 나노초단위)이다. pTargetFormat 와 pSourceFormat 의 양쪽 모두가 TIME_FORMAT_MEDIA_TIME 를 지정하는 단순한 경우를 엿보여, 이 메소드는, E_INVALIDARG 를 돌려준다.

CSourceSeeking::CSourceSeeking

CSourceSeeking 클래스

constructor　 　 메소드.

구문

CSourceSeeking(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
    CCritSec *pLock
);

파라미터

pName
오브젝트의 이름이 포함된 캐릭터 라인에의 포인터. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pUnk
이 오브젝트의 소유자에게로의 포인터. 이 오브젝트가 집성 되는 경우, 집성 오브젝트의 IUnknown 인터페이스에 포인터를 건네준다. 그 이외의 경우는, 이 파라미터에 NULL 를 설정한다.
phr
HRESULT 값에의 포인터. 무시된다.
pLock
이 클래스에 의해 사용되는 공유 데이터를 보호하는,CCritSec 오브젝트에의 포인터.

CSourceSeeking::GetAvailable

CSourceSeeking 클래스

시크가 유효한 타임의 범위를 취득한다. IMediaSeeking::GetAvailable 메소드를 이행 한다.

구문

HRESULT GetAvailable(
    LONGLONG *pEarliest,
    LONGLONG *pLatest
);

파라미터

pEarliest
유효한 시크이기 때문에 가장 낡은 타임을 받는 변수에의 포인터. 이 변수는 제로로 설정된다.
pLatest
유효한 시크를 위해서(때문에) 가장 새로운 타임을 받는 변수에의 포인터. 이 변수는,m_rtDuration 멤버 변수의 값으로 설정된다.

반환값

S_OK 를 돌려준다.

CSourceSeeking::GetCapabilities

CSourceSeeking 클래스

스트림의 모든 시크 능력을 취득한다. IMediaSeeking::GetCapabilities 메소드를 이행 한다.

구문

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

파라미터

pCapabilities
AM_SEEKING_SEEKING_CAPABILITIES 플래그의 비트마다의 편성을 받는 변수에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터값.

주의

시크 능력은,m_dwSeekingCaps 멤버 변수에 의해 지정된다.

CSourceSeeking::GetCurrentPosition

CSourceSeeking 클래스

스트림의 합계 시간폭에 대한, 현재의 위치를 취득한다. 이행되어 있지 않다.

구문

HRESULT GetCurrentPosition(
  LONGLONG *pCurrent
);

파라미터

pCurrent
현재의 위치를 받는 변수에의 포인터. 현재의 타임 포맷 단위로 나타난다.

반환값

E_NOTIMPL 를 돌려준다.

주의

보통, 소스 필터는 이 메소드를 지원 하고 있지 않다. 그 대신해, 렌더링 필터가 CRendererPosPassThru 클래스를 사용해 현재의 위치를 보고한다.

CSourceSeeking::GetDuration

CSourceSeeking 클래스

스트림의 시간폭을 취득한다. IMediaSeeking::GetDuration 메소드를 이행 한다.

구문

HRESULT GetDuration(
    LONGLONG *pDuration
);

파라미터

pDuration
시간폭을 현재의 타임 포맷 단위로 받는 변수에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터값.

주의

이 시간폭은,m_rtDuration 멤버 변수에 의해 지정된다.

CSourceSeeking::GetPositions

CSourceSeeking 클래스

현재의 위치 및 정지 위치를 취득한다. IMediaSeeking::GetPositions 메소드를 이행 한다.

구문

HRESULT GetPositions(
    LONGLONG *pCurrent,
    LONGLONG *pStop
);

파라미터

pCurrent
시작 위치를 받는 변수에의 포인터.
pStop
정지 위치를 받는 변수에의 포인터.

반환값

S_OK 를 돌려준다.

주의

이 메소드는,pCurrent 파라미터용으로 m_rtStart 멤버 변수의 값을 돌려준다. 이 변수는, 현재의 스트리밍 위치는 아닌 마지막 탐색 시간을 나타낸다. 그러나, 어플리케이션이 필터 그래프 매니저를 사용해 IMediaSeeking::GetPositions 를 호출하면, 보통 이 값은 소스 필터는 아니고, 렌더링 필터로부터 제공된다.

CSourceSeeking::GetPreroll

CSourceSeeking 클래스

프리로르 타임을 취득한다. IMediaSeeking::GetPreroll 메소드를 이행 한다.

구문

HRESULT GetPreroll(
    LONGLONG *pPreroll
);

파라미터

pPreroll
프리로르타임을 받는 변수에의 포인터. 이 값은 제로로 설정된다.

반환값

다음 표에 나타낸다, 몇개의 값을 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터값.

CSourceSeeking::GetRate

CSourceSeeking 클래스

재생 레이트를 취득한다. IMediaSeeking::GetRate 메소드를 이행 한다.

구문

HRESULT GetRate(
    double *pdRate
);

파라미터

pdRate
재생 레이트를 받는 변수에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터값.

주의

재생 레이트는,m_dRateSeeking 멤버 변수에 의해 지정된다.

CSourceSeeking::GetStopPosition

CSourceSeeking 클래스

스트림의 시간폭에 대해서, 재생이 정지하는 타임을 취득한다. IMediaSeeking::GetStopPosition 메소드를 이행 한다.

구문

HRESULT GetStopPosition(
    LONGLONG *pStop
);

파라미터

pStop
종료 타임을 현재의 타임 포맷 단위로 받는 변수에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터값.

주의

종료 타임은,m_rtStop 멤버 함수에 의해 지정된다.

CSourceSeeking::GetTimeFormat

CSourceSeeking 클래스

현재의 타임 포맷을 취득한다. IMediaSeeking::GetTimeFormat 메소드를 이행 한다.

구문

HRESULT GetTimeFormat(
    const GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 를 받는 변수에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터값.

주의

base class에 의해 지원 되는 유일한 타임 포맷은, TIME_FORMAT_MEDIA_TIME (100 나노초단위)이다.

CSourceSeeking::IsFormatSupported

CSourceSeeking 클래스

특정의 타임 포맷이 지원 되고 있는지 어떤지를 판정한다. IMediaSeeking::IsFormatSupported 메소드를 이행 한다.

구문

HRESULT IsFormatSupported(
    const GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 포맷은 지원되어 있지 않다.
S_OK | 포맷은 지원 되고 있다.
E_POINTER | NULL 포인터 인수.

주의

base class에 의해 지원 되고 있는 유일한 타임 포맷은, TIME_FORMAT_MEDIA_TIME (100 나노초)이다.

CSourceSeeking::IsUsingTimeFormat

CSourceSeeking 클래스

특정의 타임 포맷이 현재 사용되고 있는 포맷화 제발을 판정한다.

구문

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_FALSE | 지정된 포맷은, 현재의 포맷은 아니다.
S_OK | 지정된 포맷은, 현재의 포맷이다.
E_POINTER | NULL 포인터 인수.

주의

base class에 의해 지원 되고 있는 유일한 타임 포맷은, TIME_FORMAT_MEDIA_TIME (100 나노초단위)이다.

CSourceSeeking::QueryPreferredFormat

CSourceSeeking 클래스

오브젝트의 우선 타임 포맷을 취득한다. IMediaSeeking::QueryPreferredFormat 메소드를 이행 한다.

구문

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 를 받는 변수에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_POINTER | NULL 포인터값.

주의

base class에 의해 지원 되고 있는 유일한 타임 포맷은, TIME_FORMAT_MEDIA_TIME (100 나노초단위)이다.

CSourceSeeking::SetPositions

CSourceSeeking 클래스

현재의 위치와 정지 위치를 설정한다. IMediaSeeking::SetPositions 메소드를 이행 한다.

구문

HRESULT SetPositions(
    LONGLONG *pCurrent,
    DWORD CurrentFlags,
    LONGLONG *pStop,
    DWORD StopFlags
);

파라미터

pCurrent
현재의 위치를 지정하는 변수에의 포인터.
CurrentFlags
플래그의 비트마다의 편성. 「주의」를 참조할것.
pStop
종료 타임을 현재의 타임 포맷으로 지정하는 변수에의 포인터.
StopFlags
플래그의 비트마다의 편성. 「주의」를 참조할것.

반환값

HRESULT 값을 돌려준다. 다음의 가능한 값이 있다.

S_OK | 성공.
E_INVALIDARG | 무효인 플래그.
E_POINTER | NULL 포인터 인수.

주의

다음의 플래그가 지원 된다.

  • AM_SEEKING_NoPositioning
  • AM_SEEKING_AbsolutePositioning
  • AM_SEEKING_RelativePositioning
  • AM_SEEKING_IncrementalPositioning (pStop 마셔)

상세한 것에 대하여는, 「IMediaSeeking::SetPositions 」를 참조할것.

이 메소드는,m_rtStart 멤버 변수 및 m_rtStop 멤버 변수의 값을 갱신해, 순수 가상 메소드 ChangeStart 및 ChangeStop 를 호출한다.

CSourceSeeking::SetRate

CSourceSeeking 클래스

재생 레이트를 설정한다. IMediaSeeking::SetRate 메소드를 이행 한다.

구문

HRESULT SetRate(
    double dRate
);

파라미터

dRate
재생 레이트.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는,m_dRateSeeking 멤버 변수의 값을 갱신해, 순수 가상 메소드 ChangeRate 를 호출한다. 이 메소드는,dRate 파라미터를 확인하지 않는다.

CSourceSeeking::SetTimeFormat

CSourceSeeking 클래스

타임 포맷을 설정한다. IMediaSeeking::SetTimeFormat 메소드를 이행 한다.

구문

HRESULT SetTimeFormat(
    const GUID *pFormat
);

파라미터

pFormat
타임 포맷 GUID 에의 포인터.

반환값

다음 표에 나타낸다, 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_INVALIDARG | 지정된 포맷은 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

base class에 의해 지원 되고 있는 유일한 포맷은, TIME_FORMAT_MEDIA_TIME (100 나노초단위)이다.


CSourceStream 클래스

CSourceStream 클래스의 계층

CSource 필터 클래스의 출력 핀.

선언: Source.h

이 클래스의 사용의 상세한 것에 대하여는, 「CSource 」를 참조할것. 이 클래스는, 핀으로부터의 스트리밍 데이터에 워커 thread를 제공하는 CAMThread 클래스를 계승한다. CSourceStream 클래스는, 다음의 헬퍼 메소드를 이행 해, thread에 요구를 보낸다.

  • Exit
  • Init
  • Pause
  • Run
  • Stop

thread에의 최초의 요구는,Init 가 아니면 안 된다. Exit 요구에 의해, thread가 종료된다. 실제로는, 이러한 어느 메소드도 직접 호출할 필요는 없다. 이것은, 핀의 Active 메소드와 Inactive 메소드가, 필요에 따라서 메소드를 호출하기 때문에 있다.

이 클래스는, 다음에 나타내는 몇개의 "핸들러" 메소드도 제공한다.

  • OnThreadCreate
  • OnThreadDestroy
  • OnThreadStartPlay

이러한 메소드는, base class에서는 아무것도 처리를 실시하지 않지만, 상속 클래스는 그것들에 오버라이드(override) 할 수 있다.

프로텍트 멤버 변수
m_pFilter | 이 핀이 포함되어 있는 필터에의 포인터.
프로텍트 메소드
OnThreadCreate | 스트리밍 thread가 초기화되었을 때에 불려 간다. 가상.
OnThreadDestroy | 스트리밍 thread가 곧 종료할 경우에 불려 간다. 가상.
OnThreadStartPlay | DoBufferProcessingLoop 메소드의 처리가 시작 되었을 때에 불려 간다. 가상.
Active | 필터가 액티브하게 된 것을 핀에 통지한다.
Inactive | 필터가 액티브하지 않게 된 것을 핀에 통지한다.
GetRequest | 다음의 thread 요구를 기다린다.
CheckRequest | 블록 하지 않고 , thread 요구가 있을지 어떨지를 조사한다.
ThreadProc | thread 프로시저. 가상.
DoBufferProcessingLoop | 미디어 샘플을 생성해, 다운 스트림의 입력 핀에 제공한다. 가상.
CheckMediaType | 핀이 특정의 미디어 타입을 받아들일 수가 있을지 어떨지를 판정한다. 가상.
GetMediaType | 우선 미디어 타입을 취득한다. 가상.
Public 메소드
CSourceStream | constructor 메소드.
~CSourceStream | 소멸자 메소드. 가상.
Init | 스트리밍 thread를 초기화한다.
Exit | 스트리밍에 종료하도록(듯이) 통지한다.
Run | 스트리밍에 실행하도록(듯이) 통지한다.
Pause | 스트리밍 thread에 액티브하게 되도록(듯이) 통지한다.
Stop | 스트리밍 thread에 정지하도록(듯이) 통지한다.
순수 가상 메소드
FillBuffer | 미디어 타입에 데이터를 묻는다.
IPin 메소드
QueryId | 핀의 식별자를 취득한다.

CSourceStream.m_pFilter

CSourceStream 클래스

이 핀이 포함되어 있는 필터에의 포인터.

구문

CSource *m_pFilter;

CSourceStream::Active

CSourceStream 클래스

필터가 액티브하게 된 것을 핀에 통지한다. CBasePin::Active 메소드를 오버라이드(override) 한다. 핀이 접속되면(자), 이 메소드는 스트리밍 thread를 시작 한다.

구문

HRESULT Active(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 핀은 이미 액티브하다.
S_OK | 성공.
E_FAIL | thread를 시작 할 수 없었다.

CSourceStream::CheckMediaType

CSourceStream 클래스

핀이 특정의 미디어 타입을 받아들일 수가 있을지 어떨지를 판정한다. 순수 가상 메소드 CBasePin::CheckMediaType 를 이행 한다.

구문

virtual HRESULT CheckMediaType(
    CMediaType *pMediaType
);

파라미터

pMediaType
조회된 미디어 타입이 포함된 CMediaType 오브젝트에의 포인터.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.

S_OK | 핀은, 이 미디어 타입을 지원 하고 있다.
E_FAIL | 핀은, 이 미디어 타입을 지원 하고 있지 않다.

주의

디폴트에서는, 이 핀은 1 개의 미디어 타입을 지원 한다. 이 메소드는, 1 개의 파라미터판의 GetMediaType 메소드를 호출해, 지원 되고 있는 타입을 취득해, 조회된 타입과 비교한다. 핀이 2 개 이상의 미디어 타입을 지원 하고 있는 경우는, 이 메소드를 오버라이드(override) 한다.

CSourceStream::CheckRequest

CSourceStream 클래스

블록 하지 않고 , thread 요구가 있을지 어떨지를 조사한다.

구문

BOOL CheckRequest(
    Command *pCom
);

파라미터

pCom
마지막 호출로 CAMThread::CallWorker 메소드에게 건네진 값을 받는 변수에의 포인터.

반환값

보류중의 요구가 있는 경우는 TRUE 를 돌려주어, 없는 경우는 FALSE 를 돌려준다.

주의

이 메소드는,CAMThread::CheckRequest 메소드를 오버라이드(override) 해, 타입 체크를 실행한다. CSourceStream 클래스는,pCom 파라미터용의 다음의 열거형을 정의한다.

enum Command {CMD_INIT, CMD_PAUSE, CMD_RUN, CMD_STOP, CMD_EXIT};

CSourceStream::CSourceStream

CSourceStream 클래스

constructor　 　 메소드.

구문

CSourceStream(
    TCHAR *pObjectName,
    HRESULT *phr,
    CSource *pms,
    LPCWSTR pName
);

파라미터

pObjectName
핀의 디버그명이 포함된 캐릭터 라인에의 포인터.
phr
메소드의 성공 또는 실패를 나타내는,HRESULT 값을 받는 변수에의 포인터. 값을 S_OK 에 초기화하고 나서, 오브젝트를 생성 한다. 이 값은, 에러가 발생했을 때만 변경된다.
pms
이 핀을 생성 한 CSource 필터에의 포인터.
pName
핀의 이름이 포함된 캐릭터 라인에의 포인터.

주의

pObjectName 파라미터로 지정된 캐릭터 라인은, 디버그의 목적인 만큼 사용된다. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.

pName 파라미터로 지정된 캐릭터 라인은,IPin::QueryPinInfo 메소드에 의해 돌려주어지는 이름이다. 이 이름은,QueryId 메소드가 돌려주는 핀 식별에는 사용되지 않는다. 그 대신해,QueryId 는 핀 번호에 근거해 핀 식별자를 계산한다. 핀 식별자는, 그래프의 영속성을 지원 하고 있다. 상세한 것에 대하여는, 「IPin::QueryId 」를 참조할것.

CSourceStream::~CSourceStream

CSourceStream 클래스

소멸자 메소드.

구문

~CSourceStream(void);

CSourceStream::DoBufferProcessingLoop

CSourceStream 클래스

미디어 타입을 생성해, 다운 스트림의 입력 핀에 제공한다.

구문

virtual HRESULT DoBufferProcessingLoop(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | thread는 정지 요구를 받아들였다.
S_OK | 스트림이 종료했는지, 또는 다운 스트림 필터는 샘플을 받아들이지 않았다.

주의

이 메소드는, 데이터를 처리하는 메인 루프를 이행 해, 다운 스트림에 그 루프를 제공한다. 메소드는, 매회 루프를 통해서 allocater로부터 하늘의 미디어 샘플을 취득해, 이 샘플을 FillBuffer 메소드에 건네준다. FillBuffer 메소드 (상속 클래스가 이행 해야 한다)는, 다음에 미디어 데이터를 생성해, 샘플 버퍼에 그 데이터를 이동한다.

다음의 몇개의 경우에, 루프는 종료한다.

  • 입력 핀의 IMemInputPin::Receive 메소드가 샘플을 거부했다.
  • FillBuffer 메소드가 S_FALSE 를 돌려주어, 스트림의 종료를 나타내는지, 또는 에러 코드를 돌려주었다.
  • thread가 Stop 요구를 받아들였다.

DoBufferProcessingLoop 메소드는, 엔드 오브 스트림 통지를 처리한다. 에러가 발생 하면, 이 메소드는 EC_ERRORABORT 이벤트를 필터 그래프 매니저에 보낸다.

CSourceStream::Exit

CSourceStream 클래스

스트리밍 thread에 종료하도록(듯이) 통지한다.

구문

HRESULT Exit(void);

반환값

S_OK 또는 E_UNEXPECTED 를 돌려준다.

주의

Inactive 메소드는, 이 메소드를 호출한다.

CSourceStream::FillBuffer

CSourceStream 클래스

미디어 샘플에 데이터를 묻는다.

구문

virtual HRESULT FillBuffer(
    IMediaSample *pSample
) PURE;

파라미터

pSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 스트림의 종료
S_OK | 성공

주의

상속 클래스는, 이 메소드를 이행 해야 한다.

이 메소드에 제공된 미디어 샘플에는, 타임 스탬프가 없다. 상속 클래스는,IMediaSample::SetTime 메소드를 호출해, 타임 스탬프를 설정할 필요가 있다. 미디어 샘플에 대해서 적절한 경우, 상속 클래스는 IMediaSample::SetMediaTime 메소드를 호출해, 미디어 타임도 설정할 필요가 있다. 상세한 것에 대하여는, 「DirectShow 의 타임과 클락」을 참조할것.

CSourceStream::GetMediaType

CSourceStream 클래스

우선 미디어 타입을 취득한다.

구문

virtual HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

virtual HRESULT GetMediaType(
    CMediaType *pMediaType
);

파라미터

iPosition
제로 베이스의 인덱스값.
pMediaType
미디어 타입을 받는 CMediaType 오브젝트에의 포인터.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.
S_OK | 성공.
VFW_S_NO_MORE_ITEMS | 인덱스가 범위외이다.
E_INVALIDARG | 인덱스가 제로 이하이다.
E_UNEXPECTED | 예기치 않은 에러.

주의

이 메소드에는, 2 개의 판이 있다. 1 개의 판은 CBasePin::GetMediaType 메소드에 오버라이드(override) 해, 인덱스값을 파라미터로서 취한다. 이제(벌써) 1 개의 판은 1 개의 미디어 타입을 취득하도록(듯이) 설계되고 있으므로, 인덱스 파라미터는 없다.

1 개의 파라미터판의 메소드는, E_UNEXPECTED 을 돌려준다. 2 개의 파라미터판의 메소드는,iPosition 파라미터가 1 인 것을 확인해, 1 개의 파라미터판의 메소드를 호출한다. 핀이 지원 하는 미디어 타입수에 응해, 이러한 몇개의 메소드를 오버라이드(override) 해야 한다.

  • 핀이 확실히 1 개의 미디어 타입을 지원 하고 있는 경우는, 1 개의 파라미터판에 오버라이드(override) 한다. 핀이 지원 하는 미디어 타입을 묻는다.
  • 핀이 2 개 이상의 미디어 타입을 지원 하고 있는 경우는, 2 개의 파라미터판을 오버라이드(override) 한다. CheckMediaType 메소드도 오버라이드(override) 한다.

CSourceStream::GetRequest

CSourceStream 클래스

다음의 thread 요구를 기다린다.

구문

Command GetRequest(void);

반환값

다음의 thread 요구를 돌려준다.

주의

이 메소드는,CAMThread::GetRequest 메소드를 오버라이드(override) 한다. 반환값은, 다음의 열거형에 캐스트 된다.

enum Command {CMD_INIT, CMD_PAUSE, CMD_RUN, CMD_STOP, CMD_EXIT};

CSourceStream::Inactive

CSourceStream 클래스

필터가 액티브한 것은 없어진 것을 핀에 통지해,CBasePin::Inactive 메소드를 오버라이드(override) 한다. 스트리밍 thread가 액티브한 경우, 이 메소드는 스트리밍 thread를 정지해, thread가 종료하는 것을 기다린다.

구문

HRESULT Inactive(void);

반환값

S_OK 또는 다른 HRESULT 값을 돌려준다.

CSourceStream::Init

CSourceStream 클래스

스트리밍 thread를 초기화한다.

구문

HRESULT Init(void);

반환값

S_OK 또는 다른 HRESULT 값을 돌려준다.

주의

이 메소드는,ThreadProc 메소드에 보내지는 최초의 thread 요구가 아니면 안 된다. Active 메소드는, 이 메소드를 호출한다.

CSourceStream::OnThreadCreate

CSourceStream 클래스

스트리밍 thread가 초기화되었을 때에 불려 간다.

구문

virtual HRESULT OnThreadCreate(void);

반환값

S_OK 를 돌려준다.

주의

thread 프로시저 ThreadProc 는, 최초로 Init 요구를 받아들였을 때에 이 메소드를 호출한다. 이 메소드는, base class에서는 아무것도 처리를 실시하지 않는다. 상속 클래스는, 이 메소드를 오버라이드(override) 해, thread를 초기화할 수 있다. 상속 클래스가 에러 코드를 돌려주었을 경우, thread로 에러가 발생해, thread는 종료된다.

CSourceStream::OnThreadDestroy

CSourceStream 클래스

스트리밍 thread가 곧 종료할 경우에 불려 간다.

구문

virtual HRESULT OnThreadDestroy(void);

반환값

S_OK 를 돌려준다.

주의

thread 프로시저 ThreadProc 는, 이 메소드를 호출하고 나서 종료한다. 이 메소드는, base class에서는 굳이 처리를 실시하고두, 상속 클래스가 오버라이드(override) 하기 위해서 이용 가능해진다. 상속 클래스가 에러 코드를 돌려주면(자), thread로 에러가 발생해, thread는 종료된다.

CSourceStream::OnThreadStartPlay

CSourceStream 클래스

DoBufferProcessingLoop 메소드의 처리가 시작 되었을 때에 불려 간다.

구문

virtual HRESULT OnThreadStartPlay(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는, base class에서는 아무것도 처리를 실시하지 않고, 상속 클래스가 오버라이드(override) 하기 위해서 이용 가능해진다.

CSourceStream::Pause

CSourceStream 클래스

스트리밍 thread에 액티브하게 되도록(듯이) 통지한다.

구문

HRESULT Pause(void);

반환값

S_OK 또는 E_UNEXPECTED 를 돌려준다.

주의

Active 메소드는, 이 메소드를 호출한다. ThreadProc 메소드가 이 요구를 받아들이면(자),DoBufferProcessingLoop 메소드를 호출한다.

CSourceStream::QueryId

CSourceStream 클래스

핀의 식별자를 취득한다.

구문

HRESULT QueryId(
    LPWSTR *Id
);

파라미터

Id
핀 ID 가 들어가는 캐릭터 라인을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
VFW_E_NOT_FOUND | 핀은 필터로 발견되지 않았다.

주의

이 메소드는,IPin::QueryId 메소드를 이행 한다. 식별자 캐릭터 라인을 구축하기 위해(때문에), 핀은 그것 자신을 파라미터로서CSource::FindPinNumber 메소드를 호출한다. FindPinNumber 메소드는, 제로로부터 인덱스 설정되는 핀 번호를 돌려준다. QueryId 는, 1 개(살)씩 반환값을 인크리먼트(increment) 해, 결과를 캐릭터 라인으로 변환한다. 예를 들어, 최초의 핀은 "1" 이 되어, 2 번째의 핀은 "2"가 되어, 이후도 마찬가지된다.

이 메소드가 VFW_E_NOT_FOUND 를 돌려주는 경우는, 필터의 핀 배열이 무효라는 점을 나타낸다. 이 원인은, 필터의 버그일 가능성이 높다.

CSourceStream::Run

CSourceStream 클래스

스트리밍 thread에 실행하도록(듯이) 통지한다.

구문

HRESULT Run(void);

반환값

S_OK 또는 E_UNEXPECTED 를 돌려준다.

주의

base class에서는, 이 메소드는 Pause 요구와 같은 효과가 있어, 사용되지 않는다.

CSourceStream::Stop

CSourceStream 클래스

스트리밍 thread에 정지하도록(듯이) 통지한다.

구문

HRESULT Stop(void);

반환값

S_OK 또는 E_UNEXPECTED 를 돌려준다.

주의

Inactive 메소드는, 이 메소드를 호출한다.

CSourceStream::ThreadProc

CSourceStream 클래스

thread 프로시저. 순수 가상 메소드 CAMThread::ThreadProc 를 이행 한다.

구문

virtual DWORD ThreadProc(void);

반환값

thread가 정상적으로 완료되었을 경우는 0 을 돌려주어, 그 이외의 경우는 1 을 돌려준다. 반환값이 1 의 경우, thread의 리소스는 할당할 수 있던 채로 있을 가능성이 있다.

주의

이 메소드는,CAMThread::GetRequest 메소드를 호출해, thread 요구를 무한하게 기다린다. Run 또는 Pause 요구를 받아들이면(자),DoBufferProcessingLoop 메소드를 호출한다. DoBufferProcessingLoop 메소드는,Stop 요구를 받아들일 때까지 데이터를 푸쉬 한다. thread 프로시저는,Exit 요구를 받아들였을 때에 종료한다.


CSystemClock 클래스

CSystemClock 클래스의 계층

CSystemClock 클래스는, 타임 정보와 타이밍 신호를 어플리케이션에 제공하는 시스템 클록을 이행 한다. 이 클래스는,CBaseReferenceClock base class를 사용해, 지속성을 추가한 그 기능의 대부분을 제공한다.

CSystemClock 는 IPersist 인터페이스를 이행 한다. 이행에 대해서는, 「OLE Programmers Reference (Vol. 1): Structured Storage Overview」를 참조할것.

멤버 함수

CreateInstance | 시스템 클록의 인스턴스를 생성 한다.
CSystemClock | CSystemClock 오브젝트를 생성 한다.

이행 되는 IPersist 메소드

GetClassID 이 클락의 클래스 식별자를 취득한다 (CLSID_SystemClock).

이행 되는 INonDelegatingUnknown 메소드

NonDelegatingQueryInterface IID_IPersist 에의 포인터를 건네주어, 다른 인터페이스 쿼리를 위한 베이스 클락을 호출한다.

CSystemClock::CreateInstance

CSystemClock 클래스

팩토리 템플릿 테이블내에 배치되었을 때에 새로운 인스턴스를 생성 한다.

구문

static CUnknown * WINAPI CreateInstance(
    LPUNKNOWN pUnk,
    HRESULT *phr
);

파라미터

pUnk
제어하는 IUnknown 인터페이스에의 포인터.
phr
결과 정보를 돌려주는 HRESULT 값에의 포인터.

반환값

새로운 Component Object Model (COM) 오브젝트에의 포인터를 돌려준다.

주의

이 멤버 함수는,클래스 팩토리를 사용해 오브젝트를 생성 하는 경우에 필요하다. 이 멤버 함수는 클래스 constructor　 　 을 호출한다.

phr 파라미터는, 에러가 발생했을 경우에게만 변경된다. 입력의 에러 코드의 경우, 생성을 종료할 수가 있다. 다만, 어쨌든 HRESULT 에러가 검출되면(자) 생성자에 의해 소멸자가 불려 간다.

CSystemClock::CSystemClock

CSystemClock 클래스

CSystemClock 오브젝트를 생성 한다.

구문

CSystemClock(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr
);

파라미터

pName
이 오브젝트의 이름에의 포인터 (디버그 목적만).
pUnk
제어하는 IUnknown 인터페이스에의 포인터.
phr
에러가 발생했을 경우로 설정되는 HRESULT 값에의 포인터.

반환값

반환값 없음.

주의

phr 가 엔트리시에 S_OK 이외의 값을 포인트 하는 경우, 오브젝트는 생성 되지 않는다. 생성중에 에러가 발생 하면, 이 변수가 설정된다. 그 이외의 경우, 그 내용은 변경되지 않는다.

CSystemClock::GetClassID

CSystemClock 클래스

이 클락의 클래스 식별자를 취득한다.

구문

HRESULT GetClassID(
    CLSID *pClsID
);

파라미터

pClsID
CLSID_SystemClock 가 입력되는 CLSID 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다.

CSystemClock::NonDelegatingQueryInterface

CSystemClock 클래스

인터페이스를 취득해, 참조 카운트를 인크리먼트(increment) 한다.

구문

HRESULT NonDelegatingQueryInterface(
    REFIID riid,
    void **ppv
);

파라미터

riid
참조 식별자.
ppv
인터페이스에의 포인터의 주소.

반환값

ppv 가 무효인 경우는, E_POINTER 를 돌려준다. 쿼리가 성공했을 경우는 NOERROR, 실패했을 경우는 E_NOINTERFACE 를 돌려준다.

주의

이 멤버 함수는,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 해,IReferenceClock ,IPersist , 및 IUnknown 인터페이스에의 참조를 건네준다.


CTransformFilter 클래스

CTransformFilter 클래스의 계층

변환 필터를 이행 하는 base class.

선언 : Transfrm.h

이 클래스는 1 개의 입력 핀트 1 개의 출력 핀을 가지는 변환 필터를 이행 하기 위해서 설계되고 있다. 입력 핀트 출력 핀에 다른 allocater를 사용한다. 바뀌어 데이터를 처리하는 필터를 생성 하려면 ,CTransInPlaceFilter 클래스를 사용하는 것.

이 필터는 입력 핀에 CTransformInputPin 클래스를 사용해, 출력 핀에 CTransformOutputPin 클래스를 사용한다. 보통, 이러한 핑크 라스를 오버라이드(override) 할 필요는 없다. 대부분의 핀 메소드는 CTransformFilter 클래스에 대응하는 메소드를 호출하므로, 필요하면 그 필터 메소드를 오버라이드(override) 할 수 있다. 필터는 GetPin 메소드내에서 양쪽 모두의 핀을 생성 한다. 핑크 라스를 오버라이드(override) 한다면,GetPin 를 오버라이드(override) 해 커스텀 핀을 생성 해야 한다.

디폴트에서는, 입력 핀은 접속 프로세스중에 미디어 타입을 제안하지 않는다. 그러므로, 입력 핀 접속은 업 스트림 필터 (이용 가능하다라고 가정)가 제안한 미디어 타입을 사용해 생성 된다. 필터를 등록 하면나무 입력 미디어 타입을 등록해야 하는 것이다, 그러면필터 맵퍼는 그것을 찾아낼 수가 있다. 상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

출력 핀은 필터의 GetMediaType 메소드를 통해 미디어 타입을 제안한다. 출력 핀은 그 필터의 입력 핀이 접속될 때까지, 접속을 거부한다.

이 클래스는 출력 데이터를 큐에 넣지 않는다. 각 출력 샘플은 IMemInputPin::Receive 내부로부터 출력된다.

이 클래스를 사용하려면 , 새로운 클래스를 CTransformFilter 로부터 파생해, 이하의 메소드를 이행 한다 :

  • CheckInputType
  • CheckTransform
  • DecideBufferSize
  • GetMediaType
  • Transform

필터의 요구에 의해, 다른 메소드를과 같이 오버라이드(override) 할 필요가 있는 경우도 있다.

Protected 멤버 변수
m_bEOSDelivered | 필터가 엔드 오브 스트림 (EOS) 통지를 보냈는지 어떠했는지를 나타내는 플래그.
m_bSampleSkipped | 최신의 샘플이 떨어뜨려졌는지 어떠했는지를 나타내는 플래그.
m_bQualityChanged | 품질이 변경되었는지 어떠했는지를 나타내는 플래그.
m_csFilter | 필터 상태를 보호하는 크리티컬 섹션.
m_csReceive | 스트리밍 상태를 보호하는 크리티컬 섹션.
m_pInput | 입력 핀에의 포인터.
m_pOutput | 출력 핀에의 포인터.
Public 메소드
CTransformFilter | constructor 메소드.
~CTransformFilter | 소멸자 메소드.
GetPinCount | 필터 위에의 핀의 수를 취득한다. 가상.
GetPin | 핀을 취득한다. 가상.
Transform | 입력 샘플을 변환해 출력 샘플을 생성 한다. 가상.
StartStreaming | 필터가 포즈 상태에 스윗치 했을 때 불려 간다. 가상.
StopStreaming | 필터가 정지상태태에 스윗치 했을 때 불려 간다. 가상.
AlterQuality | 품질 변경이 요구된 것을 필터에 통지한다. 가상.
SetMediaType | 미디어 타입이 필터의 핀의 1 개에 세트 되었을 때 불려 간다. 가상.
CheckConnect | 핀 접속이 적절한가 어떤가를 확인한다. 가상.
BreakConnect | 핀 접속을 해제한다. 가상.
CompleteConnect | 핀 접속을 완료한다. 가상.
Receive | 미디어 샘플을 취득해, 그것을 처리해, 다운 스트림 필터에 출력 샘플을 출력한다. 가상.
InitializeOutputSample | 새로운 출력 샘플을 취득해, 그것을 초기화한다.
EndOfStream | 입력 핀으로부터 추가의 데이터는 오지 않는 것을 필터에 통지한다. 가상.
BeginFlush | 플래시 처리를 시작 한다. 가상.
EndFlush | 플래시 처리를 종료한다. 가상.
NewSegment | 이 소환말에 받아들인 미디어 샘플이 세그먼트(segment)로서 그룹화 되고 있는 것을 필터에 통지한다. 가상.
Pure Virtual 메소드
CheckInputType | 지정된 미디어 타입이 입력으로서 허용 될지 어떨지 체크한다.
CheckTransform | 입력 미디어 타입이 출력 미디어 타입과 호환성이 있을지 어떨지 체크한다.
DecideBufferSize | 출력 핀의 버퍼 요구를 설정한다.
GetMediaType | 출력 핀의 우선 미디어 타입을 취득한다.
IMediaFilter 메소드
Stop | 필터를 정지한다.
Pause | 필터를 포즈 한다.
IBaseFilter 메소드
FindPin | 지정한 ID 로 핀을 취득한다.

CTransformFilter.m_bEOSDelivered

CTransformFilter 클래스

필터가 엔드 오브 스트림 (EOS) 통지를 보냈는지 어떠했는지를 나타내는 플래그.

구문

BOOL m_bEOSDelivered;

주의

입력 접속을 가지고 있지 않을 때, 필터가 포즈라면, 필터는 엔드 오브 스트림 (EOS) 통지를 다운 스트림에 보내, 이 플래그를 TRUE 로 설정한다. 엔드 오브 스트림 (EOS) 통지에 의해 다운 스트림 필터는 샘플을 기다리지 않게 된다. 필터의 EndOfStream 메소드는 이 플래그를 세트 하지 않는 것으로 주의.

CTransformFilter.m_bSampleSkipped

CTransformFilter 클래스

최신의 샘플이 떨어뜨려졌는지 어떠했는지를 나타내는 플래그. 만약 Receive 가 샘플을 떨어뜨렸다면, 그것은 이 값을 TRUE 로 설정한다.

구문

BOOL m_bSampleSkipped;

CTransformFilter.m_bQualityChanged

CTransformFilter 클래스

품질이 변경되었는지 어떠했는지를 나타내는 플래그. 필터가 샘플을 떨어뜨리면(자), 최초로 EC_QUALITY_CHANGE 이벤트를 필터 그래프 매니저에 보내, 이 플래그를 TRUE 로 설정한다. 비록 샘플의 드롭이 계속되어도, 필터가 정지해 재스타트 할 때까지, 이 이벤트는 재발송신 되지 않는다.

구문

BOOL m_bQualityChanged;

CTransformFilter.m_csFilter

CTransformFilter 클래스

필터 상태를 보호하는 크리티컬 섹션. 상세한 것에 대하여는, 「필터 개발자가 사용하는 데이터 플로우」를 참조할것.

구문

CCritSec m_csFilter;

CTransformFilter.m_csReceive

CTransformFilter 클래스

스트리밍 상태를 보호하는 크리티컬 섹션. 상세한 것에 대하여는, 「필터 개발자가 사용하는 데이터 플로우」를 참조할것.

구문

CCritSec m_csReceive;

CTransformFilter.m_pInput

CTransformFilter 클래스

입력 핀에의 포인터.

구문

CTransformInputPin *m_pInput;

CTransformFilter.m_pOutput

CTransformFilter 클래스

출력 핀에의 포인터.

구문

CTransformOutputPin *m_pOutput;

CTransformFilter::AlterQuality

CTransformFilter 클래스

품질 변경이 요구된 것을 필터에 통지한다.

구문

virtual HRESULT AlterQuality(
    Quality q
);

파라미터

q
품질관리 메세지가 들어가는 Quality 구조체.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 품질 메세지를 처리할 수 없었다. 메세지는 업 스트림에게 건네져야 한다.
S_OK | 품질 메세지를 처리했다. 더 이상의 작업은 불필요하다.

base class는 S_FALSE 를 돌려준다.

주의

필터가 품질 컨트롤을 처리할 수 있다면, 이 메소드를 오버라이드(override) 하는 것. 상세한 것에 대하여는, 「품질 컨트롤의 관리」를 참조할것.

CTransformFilter::BeginFlush

CTransformFilter 클래스

플래시 처리를 시작 한다.

구문

virtual HRESULT BeginFlush(void);

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

플래시 처리 시작시에 입력 핀의 CTransformInputPin::BeginFlush 메소드는 이 메소드를 호출한다. 이 메소드는 BeginFlush 호출을 다운 스트림에 건네준다.

상속 클래스가 샘플의 출력에 워커 thread를 사용하고 있다면, 플래시 처리중에 큐에 들어가 있는 데이터를 파기해야 한다. 그것은 BeginFlush 메소드내인가,EndFlush 메소드내에서 실시할 수가 있다. 그러나, BeginFlush 에의 호출은 스트리밍 thread와는 동기 하고 있지 않는 것에 주의. 만약 BeginFlush 메소드가 큐에 들어가 있는 데이터를 파기한다면, 필터는 BeginFlush 호출과 EndFlush 호출동안에 데이터의 처리를 하지 않는 것에 주의하지 않으면 안 된다. 상세한 것에 대하여는, 「필터 개발자가 사용하는 데이터 플로우」를 참조할것.

CTransformFilter::BreakConnect

CTransformFilter 클래스

핀 접속을 해제한다.

구문

virtual HRESULT BreakConnect(
    PIN_DIRECTION dir
);

파라미터

dir
PIN_DIRECTION 열거형의 멤버, (입력 핀 혹은 출력 핀의) 핀 접속이 떨어졌는지 어떠했는지를 나타낸다.

반환값

S_OK 를 돌려준다.

주의

CTransformInputPin::BreakConnect 과 CTransformOutputPin::BreakConnect 메소드는 핀 접속을 해제 하면 군령의 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않는다. CheckConnect 메소드를 오버라이드(override) 한다면, 이 메소드를 오버라이드(override) 해 CheckConnect 메소드로 취득한 인터페이스의 포인터를 포함한 리소스를 릴리스 한다.

CTransformFilter::CheckConnect

CTransformFilter 클래스

핀 접속이 적절한가 어떤가를 확인한다.

구문

virtual HRESULT CheckConnect(
    PIN_DIRECTION dir,
    IPin *pPin
);

파라미터

dir
PIN_DIRECTION 열거형의 멤버, 필터의 어느 핀이 접속을 생성 하는지를 나타낸다.
pPin
이 접속을 시도하고 있는 상대의 IPin 인터페이스에의 포인터.

반환값

S_OK 를 돌려준다.

주의

CTransformInputPin::CheckConnect 과 CTransformOutputPin::CheckConnect 메소드는 핀 접속 프로세스중에 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않는다. 상속 클래스는 그것을 오버라이드(override) 할 수 있다. 예를 들어, 상속 클래스는 개별의 인터페이스로 다른 핀을 쿼리 하는 경우가 있다.

CTransformFilter::CheckInputType

CTransformFilter 클래스

지정된 미디어 타입이 입력으로서 허용 될지 어떨지 체크한다.

구문

virtual HRESULT CheckInputType(
    const CMediaType *mtIn
) PURE;

파라미터

mtIn
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 미디어 타입은 허용 되었다.
VFW_E_TYPE_NOT_ACCEPTED | 미디어 타입은 허용 되지 않는다.

주의

상속 클래스는 이 메소드를 이행 해야 한다. 제안된 입력 포맷이 허용 가능하면 S_OK 가 돌아가는, 그렇지 않으면 에러 코드가 돌아간다.

이 메소드는 (필요하다고 해도) 입력 포맷이 출력 포맷과 호환성이 있는지를 검증하지 않는다. 입력 핀은 CheckTransform 메소드를 호출해 그것을 검증한다.

CTransformFilter::CheckTransform

CTransformFilter 클래스

입력 미디어 타입이 출력 미디어 타입과 호환성이 있을지 어떨지 체크한다.

구문

virtual HRESULT CheckTransform(
    const CMediaType *mtIn,
    const CMediaType *mtOut
) PURE;

파라미터

mtIn
입력 타입을 지정하는 CMediaType 오브젝트에의 포인터.
mtOut
출력 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 미디어 타입은 호환성이 있다.
VFW_E_TYPE_NOT_ACCEPTED | 미디어 타입은 호환성이 없다.

주의

상속 클래스는 이 메소드를 이행 해야 한다. 제안된 입력 포맷이 허용 가능하면 S_OK 가 돌아가는, 그렇지 않으면 에러 코드가 돌아간다.

CTransformFilter::CompleteConnect

CTransformFilter 클래스

핀 접속을 완료한다.

구문

virtual HRESULT CompleteConnect(
    PIN_DIRECTION direction,
    IPin *pReceivePin
);

파라미터

direction
PIN_DIRECTION 열거형의 멤버, 필터의 어느 핀이 접속을 생성 하는지를 나타낸다.
pReceivePin
이 접속을 시도하고 있는 상대의 IPin 인터페이스에의 포인터.

반환값

S_OK 를 돌려준다.

주의

CTransformInputPin::CompleteConnect 과 CTransformOutputPin::CompleteConnect 메소드는 핀 접속 프로세스중에 이 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스는 그것을 오버라이드(override) 할 수 있다.

CTransformFilter::CTransformFilter

CTransformFilter 클래스

constructor　 　 메소드.

구문

CTransformFilter(
    TCHAR *pObjectName,
    LPUNKNOWN lpUnk,
    CLSID clsid
);

파라미터

pObjectName
필터의 디버그명이 들어가는 캐릭터 라인. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
lpUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되고 있다면, 집성 오브젝트의 IUnknown 인터페이스에의 포인터를 건네주어, 이 파라미터를 NULL 로 한다.
clsid
필터의 클래스 ID.

주의

constructor　 　 은 필터의 핀을 생성 하지 않는다. 그것은 GetPin 메소드를 최초로 호출하는 동안에 행해진다. constructor　 　 은 m_pInput 와 m_pOutput 멤버 변수를 NULL 에 초기화한다.

CTransformFilter::~CTransformFilter

CTransformFilter 클래스

소멸자 메소드.

구문

~CTransformFilter(void);

CTransformFilter::DecideBufferSize

CTransformFilter 클래스

출력 핀의 버퍼 요구를 설정한다.

구문

virtual HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *ppropInputRequest
) PURE;

파라미터

pAlloc
출력 핀의 allocater의 IMemAllocator 인터페이스에의 포인터.
ppropInputRequest
다운 스트림 입력 핀으로부터의 버퍼 요구가 들어가는 ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

출력 핀의 CTransformOutputPin::DecideBufferSize 메소드는 이 메소드를 호출한다. 상속 클래스는 이 메소드를 이행 해야 한다. 상세한 것에 대하여는, 「CBaseOutputPin::DecideBufferSize 」를 참조할것.

CTransformFilter::EndFlush

CTransformFilter 클래스

플래시 처리를 종료한다.

구문

virtual HRESULT EndFlush(void);

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

플래시 처리의 끝에, 입력 핀의 CTransformInputPin::EndFlush 메소드는 안녕 메소드를 호출한다. 이 메소드는 EndFlush 호출을 다운 스트림에 건네준다.

상속 클래스가 워커 thread를 사용해 샘플을 출력한다면,EndFlush 호출을 다운 스트림에 보내기 전에 큐내의 데이터를 파기해야 한다. 상세한 것에 대하여는, 「필터 개발자가 사용하는 데이터 플로우」를 참조할것.

CTransformFilter::EndOfStream

CTransformFilter 클래스

입력 핀으로부터 추가의 데이터는 오지 않는 것을 필터에 통지한다.

구문

virtual HRESULT EndOfStream(void);

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

입력 핀의 CTransformInputPin::EndOfStream 메소드는 이 메소드를 호출한다. 이 메소드는 엔드 오브 스트림 (EOS) 통지를 다운 스트림에 출력한다. 상속 클래스가 워커 thread를 사용해 미디어 샘플을 출력한다면, 이 메소드를 오버라이드(override) 해 엔드 오브 스트림 (EOS) 통지를 큐에 넣어야 하는 것이다.

CTransformFilter::FindPin

CTransformFilter 클래스

지정한 ID 로 핀을 취득한다. IBaseFilter::FindPin 메소드의 이행.

구문

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

파라미터

Id
핀 ID 가 들어가는 와이드 캐릭터 라인.
ppPin
핀의 IPin 인터페이스에의 포인터를 받는 변수의 주소. 메소드가 실패 하면,*ppPin 는 NULL 에 세트 된다.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
VFW_E_NOT_FOUND | 이 ID 로 핀을 찾아낼 수 없었다.

주의

입력 핀의 ID 는 In 이며, 출력 핀의 ID 는 Out 이다.

CTransformFilter::GetMediaType

CTransformFilter 클래스

출력 핀의 우선 미디어 타입을 취득한다.

구문

virtual HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
) PURE;

파라미터

iPosition
제로로부터 시작되는 인덱스값
pMediaType
미디어 타입을 받는 CMediaType 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_S_NO_MORE_ITEMS | 인덱스가 허용폭을 넘었다.
E_INVALIDARG | 인덱스가 제로보다 작다.

주의

출력 핀의 CTransformOutputPin::GetMediaType 메소드는 이 메소드를 호출한다. 상속 클래스는 이 메소드를 이행 해야 한다. 상세한 것에 대하여는, 「CBasePin::GetMediaType 를 참조할것.

CTransformFilter::GetPin

CTransformFilter 클래스

핀을 취득한다.

구문

virtual CBasePin *GetPin(
    int n
);

파라미터

n
지정된 핀의 수, 제로로부터 시작되는 인덱스. 이 필터에서는, 핀 0 은 입력 핀으로, 핀 1 은 출력 핀.

반환값

핀을 이행 하는 CBasePin 오브젝트에의 포인터를 돌려주는, 메소드가 실패 하면 NULL 를 돌려준다.

주의

이 메소드는 순수 가상 CBaseFilter::GetPin 메소드를 이행 한다. 처음으로 메소드가 불려 가면(자), 양쪽 모두의 핀을 생성 한다.

이 메소드는 돌아간 핀의 참조 카운트를 인크리먼트(increment) 하지 않기 때문에, 돌아간 핀은 미처리의 참조 카운트를 가지지 않는다. 호출원이 핀에의 참조를 보관 유지할 필요가 있다면, 그 핀으로 IUnknown::AddRef 를 호출해야 하는 것이다.

필터가 디폴트CTransformInputPin 핀과 CTransformOutputPin 핀을 사용한다면, 이 메소드를 오버라이드(override) 할 필요는 없다. 그러나 필터가 클래스를 확장한 핀을 사용한다면. 이 메소드를 오버라이드(override) 해 그 타입의 핀을 생성 해야 한다.

CTransformFilter::GetPinCount

CTransformFilter 클래스

필터 위에의 핀의 수를 취득한다.

구문

virtual int GetPinCount(void);

반환값

2 를 돌려준다.

주의

이 메소드는 CBaseFilter::GetPinCount 메소드를 오버라이드(override) 한다. 실제로는 이 클래스는 입력 핀 1 개(살)과 출력 핀 1 개(살)을 지원 한다.

CTransformFilter::InitializeOutputSample

CTransformFilter 클래스

새로운 출력 샘플을 취득해, 그것을 초기화한다.

구문

HRESULT InitializeOutputSample(
    IMediaSample *pSample,
    IMediaSample **ppOutSample
);

파라미터

pSample
입력 샘플의 IMediaSample 인터페이스에의 포인터.
ppOutSample
출력 샘플의 IMediaSample 인터페이스에의 포인터를 받는 변수의 주소.

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

이 메소드는 새로운 샘플을 출력 핀의 allocater로부터 취득하는, 다음에 입력 샘플로부터 출력 샘플에 샘플 프로퍼티를 카피한다.

CTransformFilter::NewSegment

CTransformFilter 클래스

이 소환말에 받아들인 미디어 샘플이 세그먼트(segment)로서 그룹화 되고 있는 것을 필터에 통지한다.

구문

virtual HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

파라미터

tStart
세그먼트(segment)의 시작 타임, 오리지날 소스로부터의 상대값.
tStop
세그먼트(segment)의 스톱 타임, 오리지날 소스로부터의 상대값.
dRate
세그먼트(segment)가 처리되어야 할 레이트.

반환값

S_OK 를 돌려준다.

주의

입력 핀의 CTransformInputPin::NewSegment 메소드는 이 메소드를 호출한다. 이 메소드는 NewSegment 호출을 다운 스트림의 입력 핀에 출력한다.

CTransformFilter::Pause

CTransformFilter 클래스

필터를 포즈 한다. IMediaFilter::Pause 를 이행.

구문

HRESULT Pause(void);

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

이 메소드는 StartStreaming 메소드를 호출한다. StartStreaming 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스는 그것을 오버라이드(override) 할 수 있다.

CTransformFilter::Receive

CTransformFilter 클래스

미디어 샘플을 취득해, 그것을 처리해, 다운 스트림 필터에 출력 샘플을 출력한다.

구문

HRESULT Receive(
    IMediaSample *pSample
);

파라미터

pSample
입력 샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

필터의 입력 핀은 샘플을 취득했을 때 이 메소드를 호출한다. 이 메소드는 InitializeOutputSample 메소드를 호출하는, 그것은 새로운 출력 샘플을 준비한다. 다음에 그것은 Transform 메소드를 호출하는, 이것은 상속 클래스가 이행 해야 한다. Transform 메소드는 입력 데이터를 처리해, 출력 데이터를 생성 한다.

Transform 메소드가 S_FALSE 를 돌려주면(자),Receive 메소드는 이 샘플을 드롭 한다. 최초의 드롭 샘플로, 필터는 EC_QUALITY_CHANGE 이벤트를 필터 그래프 매니저에 보낸다. 한편,Transform 가 S_OK 를 돌려준다면, 필터는 출력 샘플을 출력한다. 그 때문에(위해),IMemInputPin::Receive 메소드를 다운 스트림 입력 핀으로 호출한다.

CTransformFilter::SetMediaType

CTransformFilter 클래스

미디어 타입이 필터의 핀의 1 개에 세트 되었을 때 불려 간다.

구문

virtual HRESULT SetMediaType(
    PIN_DIRECTION direction,
    const CMediaType *pmt
);

파라미터

direction
PIN_DIRECTION 열거형의 멤버, 필터의 핀(입력 핀 혹은 출력 핀)을 지정한다.
pmt
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

S_OK 를 돌려준다.

주의

CTransformInputPin::SetMediaType 메소드와 CTransformOutputPin::SetMediaType 메소드는 핀의 미디어 타입을 설정 하면 군령의 메소드를 호출한다. 이 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스는 그것을 오버라이드(override) 할 수 있다.

CTransformFilter::StartStreaming

CTransformFilter 클래스

필터가 포즈 상태에 스윗치 했을 때 불려 간다.

구문

virtual HRESULT StartStreaming(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스는 그것을 오버라이드(override) 할 수 있다.

CTransformFilter::Stop

CTransformFilter 클래스

필터를 정지한다. IMediaFilter::Stop 메소드의 이행.

구문

HRESULT Stop(void);

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

이 메소드는 양쪽 모두의 allocater를 데코밋트로 한 다음에,StopStreaming 메소드를 호출한다. StopStreaming 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스는 그것을 오버라이드(override) 할 수 있다.

CTransformFilter::StopStreaming

CTransformFilter 클래스

필터가 정지상태태에 스윗치 했을 때 불려 간다.

구문

virtual HRESULT StopStreaming(void);

반환값

S_OK 를 돌려준다.

주의

이 메소드는 base class에서는 아무것도 하지 않지만, 상속 클래스는 그것을 오버라이드(override) 할 수 있다.

CTransformFilter::Transform

CTransformFilter 클래스

입력 샘플을 변환해 출력 샘플을 생성 한다.

구문

virtual HRESULT Transform(
    IMediaSample *pIn,
    IMediaSample *pOut
)

파라미터

pIn
입력 샘플의 IMediaSample 인터페이스에의 포인터.
pOut
출력 샘플의 IMediaSample 인터페이스에의 포인터.

반환값

base class는 E_UNEXPECTED 를 돌려준다.

상속 클래스는 성공 실패를 나타내는 HRESULT 값을 돌려주어야 하는 것이다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 이 샘플을 출력하지 않는다.
S_OK | 성공.

주의

출력 데이터를 생성 하려면 이 메소드를 오버라이드(override) 하는 것. 입력 데이터를 pIn 파라미터로 지정된 샘플로부터 읽어들여. 새로운 데이터를 pOut 파라미터로 지정된 샘플에 기입한다.

필터가 이 메소드를 호출하기 전에, 그것은 입력 샘플로부터 출력 샘플에 프로퍼티를 카피한다. Transform 메소드는 2 개의 샘플간에 다른 프로퍼티를 세트 해야 한다, 거기에는 IMediaSample 메소드를 사용하든가, 혹은 (만약 이용 가능하면) IMediaSample2 인터페이스를 사용한다.

필터가 이 샘플을 출력해서는 안되면 (예를 들어, 품질관리를 컨트롤 하기 위한(해)), 이 메소드는 S_FALSE 를 돌려주어야 하는 것이다.


CTransformInputPin 클래스

CTransformInputPin 클래스의 계층

CTransformFilter 클래스가 사용하는 입력 핀.

선언 : Transfrm.h

보통, 이 클래스를 파생시킬 필요는 없다. 이 클래스의 대부분의 메소드는 오버라이드(override) 가능한 CTransformFilter 클래스의 대응하는 메소드를 호출하고 있다. 이 클래스로부터 파생시킨다면, 필터의 CTransformFilter::GetPin 메소드를 오버라이드(override) 해, 그 상속 클래스의 인스턴스를 생성 해야 한다.

Protected 멤버 변수
m_pTransformFilter | 소유자 필터에의 포인터.
Public 메소드
CTransformInputPin | constructor 메소드.
CheckConnect | 핀 접속이 적절한가 어떤가를 확인한다.
BreakConnect | 핀의 접속을 해제한다.
CompleteConnect | 별의 핀에의 접속을 완료한다.
CheckMediaType | 핀이 지정한 미디어 타입을 허용 할지 어떨지를 확인한다.
SetMediaType | 접속때의 미디어 타입을 설정한다.
CheckStreaming | 핀이 샘플을 허용 할지 어떨지를 확인한다. 가상.
CurrentMediaType | 현재의 핀 접속의 미디어 타입을 취득한다.
IPin 메소드
QueryId | 핀의 ID 를 취득한다.
EndOfStream | 추가 데이터가 없는 것을 핀에 통지한다.
BeginFlush | 플래시 처리를 시작 한다.
EndFlush | 플래시 처리를 종료한다.
NewSegment | 이 호출 후에 받은 미디어 샘플이 세그먼트(segment)로서 그룹화 된 것을 핀에 통지한다.
IMemInputPin 메소드
Receive | 스트림내의 다음의 미디어 샘플을 취득한다.

CTransformInputPin.m_pTransformFilter

CTransformInputPin 클래스

소유자 필터에의 포인터.

구문

CTransformFilter *m_pTransformFilter;

CTransformInputPin::BeginFlush

CTransformInputPin 클래스

플래시 처리를 시작 한다. IPin::BeginFlush 메소드의 이행.

구문

HRESULT BeginFlush(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 출력 핀이 접속되어 있지 않다.

주의

이 메소드는 핀의 CBaseInputPin::BeginFlush 메소드를 호출한다. 다음에 그것은 필터의 CTransformFilter::BeginFlush 메소드를 호출해, 데이터 스트림 호출을 출력한다.

CTransformInputPin::BreakConnect

CTransformInputPin 클래스

핀의 접속을 해제한다.

구문

HRESULT BreakConnect(void);

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

이 메소드는 CBaseInputPin::BreakConnect 메소드를 오버라이드(override) 한다. 그것은 base class에서는 S_OK 를 돌려주는, 필터의 CTransformFilter::BreakConnect 메소드를 호출한다. 상속 클래스는 CTransformFilter::BreakConnect 메소드를 오버라이드(override) 할 수가 있다.

CTransformInputPin::CheckConnect

CTransformInputPin 클래스

핀 접속이 적절한가 어떤가를 확인한다.

구문

HRESULT CheckConnect(
    IPin *pPin
);

파라미터

pPin
출력 핀의 IPin 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_INVALID_DIRECTION | 핀의 방향이 올바르지 않다.

주의

이 메소드는 CBasePin::CheckConnect 메소드를 오버라이드(override) 한다. 그것은 base class에서는 S_OK 를 돌려주는 필터의 CTransformFilter::CheckConnect 메소드를 호출한다. 상속 클래스는 CTransformFilter::CheckConnect 메소드를 오버라이드(override) 해, 추가의 체크를 실시할 수가 있다.

CTransformInputPin::CheckMediaType

CTransformInputPin 클래스

핀이 지정한 미디어 타입을 허용 할지 어떨지를 확인한다.

구문

HRESULT CheckMediaType(
    const CMediaType *mtIn
);

파라미터

mtIn
제안된 미디어 타입이 들어가는 CMediaType 오브젝트에의 포인터.

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

이 메소드는 순수 가상 CBasePin::CheckMediaType 메소드를 이행 한다. 그것은 필터의 CTransformFilter::CheckInputType 메소드를 호출하는, 그것도 또 순수 가상이다. 필터의 상속 클래스는 CheckInputType 를 이행 해, 주어진 입력 타입이 허용 될지 어떨지를 확인해야 한다.

필터의 출력 핀이 접속되고 있다면, 지금 메소드는 또 필터의 CTransformFilter::CheckTransform 메소드를 호출해, 입력 타입이 출력 타입과 호환성이 있을지 어떨지도 확인한다. CheckTransform 메소드는과 같이 순수 가상이다.

CTransformInputPin::CheckStreaming

CTransformInputPin 클래스

핀이 샘플을 허용 할지 어떨지를 확인한다.

구문

HRESULT CheckStreaming(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
S_FALSE | 핀은 현재 플래시중이다.
VFW_E_NOT_CONNECTED | 출력 핀이 접속되어 있지 않다.
VFW_E_RUNTIME_ERROR | 런타임 에러가 발생했다.
VFW_E_WRONG_STATE | 핀이 정지하고 있다.

주의

이 메소드는 CBaseInputPin::CheckStreaming 메소드를 오버라이드(override) 한다.

CTransformInputPin::CompleteConnect

CTransformInputPin 클래스

다른 핀에의 접속을 완료한다.

구문

HRESULT CompleteConnect(
    IPin *pReceivePin
);

파라미터

pReceivePin
다른 핀의 IPin 인터페이스에의 포인터.

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

이 메소드는 CBasePin::CompleteConnect 메소드를 오버라이드(override) 한다. 그것은 base class에서는 S_OK 를 돌려주는 필터의 CTransformFilter::CompleteConnect 메소드를 호출한다. 상속 클래스는 CTransformFilter::CompleteConnect 메소드를 오버라이드(override) 해 추가 체크를 실시할 수가 있다.

CTransformInputPin::CTransformInputPin

CTransformInputPin 클래스

constructor　 　 메소드.

구문

CTransformInputPin(
    TCHAR *pObjectName,
    CTransformFilter *pTransformFilter,
    HRESULT *phr,
    LPCWSTR pName
);

파라미터

pObjectName
오브젝트의 디버그명이 들어가는 캐릭터 라인. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pTransformFilter
이 핀을 생성 한 필터에의 포인터, 그것은 CTransformFilter 오브젝트가 아니면 안된다.
phr
메소드의 성공 실패를 나타내는 HRESULT 값을 받는 변수에의 포인터. 오브젝트를 생성 하기 전에 S_OK 로 그 값을 초기화하는 것. 이 값은 에러가 일어났을 경우만 변경된다.
pName
접속하고 있는 핀명이 들어가는 Unicode™ 캐릭터 라인.

주의

pName 파라미터는 IPin::QueryPinInfo 메소드가 돌려주는 핀명을 지정한다. 그러나, 이 캐릭터 라인은 핀 ID 로서는 사용되지 않았다. 이 클래스에서는 핀 ID 는 반드시 In 이다. 상세한 것에 대하여는, 「QueryId 」를 참조할것.

CTransformInputPin::CurrentMediaType

CTransformInputPin 클래스

현재의 핀 접속의 미디어 타입을 취득한다.

구문

CMediaType& CurrentMediaType(void);

반환값

CBasePin::m_mt 멤버 변수에의 참조를 돌려준다.

CTransformInputPin::EndFlush

CTransformInputPin 클래스

플래시 처리를 종료한다. IPin::EndFlush 메소드의 이행.

구문

HRESULT EndFlush(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_NOT_CONNECTED | 출력 핀이 접속되어 있지 않다.

주의

이 메소드는 필터의 CTransformFilter::EndFlush 메소드를 호출해, 다운 스트림 호출을 출력한다. 다음에 그것은 핀의 CBaseInputPin::EndFlush 메소드를 호출한다.

CTransformInputPin::EndOfStream

CTransformInputPin 클래스

추가 데이터가 없는 것을 핀에 통지한다. IPin::EndOfStream 메소드의 이행.

구문

HRESULT EndOfStream(void);

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
S_FALSE | 핀은 현재 플래시중이다.
VFW_E_NOT_CONNECTED | 출력 핀이 접속되어 있지 않다.
VFW_E_RUNTIME_ERROR | 런타임 에러가 발생.
VFW_E_WRONG_STATE | 핀은 정지중이다.

주의

이 메소드는 필터의 CTransformFilter::EndOfStream 메소드를 호출해, 엔드 오브 스트림 (EOS) 통지를 다운 스트림에 출력한다.

CTransformInputPin::NewSegment

CTransformInputPin 클래스

이 호출 후에 받은 미디어 샘플이 세그먼트(segment)로서 그룹화 된 것을 핀에 통지한다. IPin::NewSegment 메소드의 이행.

구문

HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

파라미터

tStart
세그먼트(segment)의 시작 타임.
tStop
세그먼트(segment)의 스톱 타임.
dRate
세그먼트(segment)의 레이트.

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

이 메소드는 CBasePin::NewSegment 메소드를 오버라이드(override) 한다. 그것은 필터의 CTransformFilter::NewSegment 메소드를 호출해, 다운 스트림 호출을 출력한다.

CTransformInputPin::QueryId

CTransformInputPin 클래스

핀의 ID 를 취득한다. IPin::QueryId 메소드의 이행.

구문

HRESULT QueryId(
    LPWSTR *Id
);

파라미터

Id
핀 ID 가 들어가는 캐릭터 라인을 받는 변수의 주소.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

핀 ID 는 그래프로 이용된다. 이 클래스의 핀 ID 는 In 이다. 이 클래스는 CBasePin 클래스의 행동을 오버라이드(override) 한다. CBasePin 클래스에서는, 핀 ID 는 클래스 constructor　 　 으로 지정된 핀명과 같다. CTransformInputPin 클래스에서는, 핀 ID 와 핀명은 같지 않다.

CTransformInputPin::Receive

CTransformInputPin 클래스

스트림내의 다음의 미디어 샘플을 취득한다. IMemInputPin::Receive 메소드의 이행.

구문

HRESULT Receive(
    IMediaSample *pSample
);

파라미터

pSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_FALSE | 핀은 현재 플래시중인, 샘플은 거부되었다.
S_OK | 성공.

주의

이 메소드는 핀의 CBaseInputPin::Receive 메소드를 호출하는, 그것은 핀의 스트리밍 상태를 체크해, 미디어 타입의 포맷 변경을 체크한다. 다음에 필터의 CTransformFilter::Receive 메소드를 호출하는, 그것은 샘플을 처리해, 다운 스트림에 출력한다.

이 메소드가 돌아간 다음에 필터가 샘플에 액세스 할 필요가 있다면, 샘플로 IUnknown::AddRef 메소드를 호출해, 참조 카운트를 보관 유지해야 한다. 예를 들어, 어느 디코더 필터는 다음의 샘플을로 코드 하기 위해서 현재의 샘플을 필요로 한다.

CTransformInputPin::SetMediaType

CTransformInputPin 클래스

접속때의 미디어 타입을 설정한다.

구문

HRESULT SetMediaType(
    const CMediaType *mt
);

파라미터

mt
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 CBasePin::SetMediaType 메소드를 오버라이드(override) 한다. 그것은 필터의 CTransformFilter::SetMediaType 메소드를 호출해, 필터에 정보를 준다.

핀은 미디어 타입이 이 메소드를 호출하기 전에 액세스 가능한 것을 검증해야 한다.


CTransformOutputPin 클래스

CTransformOutputPin 클래스의 계층

CTransformFilter 클래스가 사용하는 출력 핀.

선언: Transfrm.h

보통, 이 클래스를 파생시킬 필요는 없다. 이 클래스의 대부분의 메소드는 오버라이드(override) 가능한 CTransformFilter 클래스의 대응하는 메소드를 호출하고 있다. 이 클래스로부터 파생시킨다면, 필터의 CTransformFilter::GetPin 메소드를 오버라이드(override) 해, 그 상속 클래스의 인스턴스를 생성 해야 한다.

Protected 멤버 변수
m_pTransformFilter | 소유자 필터에의 포인터.
Public Member Variables
m_pPosition | 시크 커멘드를 업 스트림에 건네주는 헬퍼 오브젝트.
Public 메소드
CTransformOutputPin | constructor 메소드.
~CTransformOutputPin | 소멸자 메소드.
CheckConnect | 핀 접속이 적절한가 어떤가를 확인한다.
BreakConnect | 핀의 접속을 해제한다.
CompleteConnect | 별의 핀에의 접속을 완료한다.
CheckMediaType | 핀이 지정한 미디어 타입을 허용 할지 어떨지를 확인한다.
SetMediaType | 접속때의 미디어 타입을 설정한다.
DecideBufferSize | 버퍼 요구를 설정한다.
GetMediaType | 인덱스값으로 우선 미디어 타입을 취득한다.
CurrentMediaType | 현재의 핀 접속의 미디어 타입을 취득한다.
IPin Methods
QueryId | 핀의 ID 를 취득한다.
IQualityControl Methods
Notify | 품질 변경이 요구된 일을 핀에 통지한다.

CTransformOutputPin.m_pTransformFilter

CTransformOutputPin 클래스

소유자 필터에의 포인터.

구문

CTransformOutputPin *m_pTransformFilter;

CTransformOutputPin.m_pPosition

CTransformOutputPin 클래스

시크 커멘드를 업 스트림에 건네주는 헬퍼 오브젝트.

구문

IUnknown *m_pPosition;

주의

핀이 최초로 IMediaPosition 인터페이스 혹은 IMediaSeeking 인터페이스로 쿼리 될 때, 그것은 CPosPassThru 오브젝트를 생성, 집성 한다.

CTransformOutputPin::BreakConnect

CTransformOutputPin 클래스

핀의 접속을 해제한다.

구문

HRESULT BreakConnect(void);

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

이 메소드는 CBaseOutputPin::BreakConnect 메소드를 오버라이드(override) 한다. 그것은 base class에서는 S_OK 를 돌려주는, 필터의 CTransformFilter::BreakConnect 메소드를 호출한다. 상속 클래스는 CTransformFilter::BreakConnect 메소드를 오버라이드(override) 할 수가 있다.

CTransformOutputPin::CheckConnect

CTransformOutputPin 클래스

핀 접속이 적절한가 어떤가를 확인한다.

구문

HRESULT CheckConnect(
    IPin *pPin
);

파라미터

pPin
출력 핀의 IPin 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_UNEXPECTED | 필터의 입력 핀이 접속되어 있지 않다.

주의

이 메소드는 CBaseOutputPin::CheckConnect 메소드를 오버라이드(override) 한다. 그것은 base class에서는 S_OK 를 돌려주는 필터의 CTransformFilter::CheckConnect 메소드를 호출한다. 상속 클래스는 CTransformFilter::CheckConnect 메소드를 오버라이드(override) 해, 추가의 체크를 실시할 수가 있다.

CTransformOutputPin::CheckMediaType

CTransformOutputPin 클래스

핀이 지정한 미디어 타입을 허용 할지 어떨지를 확인한다.

구문

HRESULT CheckMediaType(
    const CMediaType *mtIn
);

파라미터

mtIn
제안된 미디어 타입이 들어가는 CMediaType 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_INVALIDARG | 필터의 입력 핀이 접속되어 있지 않다.

주의

이 메소드는 순수 가상 CBasePin::CheckMediaType 메소드를 이행 한다. 이 메소드는 필터의 입력 핀이 접속되어 있지 않으면 실패한다. 그렇지 않으면, 그것은 필터의 CTransformFilter::CheckTransform 메소드를 호출하는, 그것도 또 순수 가상이다. 필터의 상속 클래스는 CheckTransform 를 이행 해, 제안된 출력 미디어 타입이 입력 미디어 타입과 호환성이 있을지 어떨지를 확인한다.

CTransformOutputPin::CompleteConnect

CTransformOutputPin 클래스

다른 핀에의 접속을 완료한다.

구문

HRESULT CompleteConnect(
    IPin *pReceivePin
);

파라미터

pReceivePin
다른 핀의 IPin 인터페이스에의 포인터.

반환값

S_OK 를 돌려준다, 혹은 다른 HRESULT 값을 돌려준다.

주의

이 메소드는 CBaseOutputPin::CompleteConnect 메소드를 오버라이드(override) 한다. 그것은 base class에서는 S_OK 를 돌려주는 필터의 CTransformFilter::CompleteConnect 메소드를 호출한다. 상속 클래스는 CTransformFilter::CompleteConnect 메소드를 오버라이드(override) 해 추가 체크를 실시할 수가 있다.

CTransformOutputPin::CTransformOutputPin

CTransformOutputPin 클래스

constructor　 　 메소드.

구문

CTransformOutputPin(
    TCHAR *pObjectName,
    CTransformFilter *pTransformFilter,
    HRESULT *phr,
    LPCWSTR pName
);

파라미터

pObjectName
오브젝트의 디버그명이 들어가는 캐릭터 라인. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pTransformFilter
이 핀을 생성 한 필터에의 포인터, 그것은 CTransformFilter 오브젝트가 아니면 안된다.
phr
메소드의 성공 실패를 나타내는 HRESULT 값을 받는 변수에의 포인터. 오브젝트를 생성 하기 전에 S_OK 로 그 값을 초기화하는 것. 이 값은 에러가 일어났을 경우만 변경된다.
pName
접속하고 있는 핀명이 들어가는 Unicode™ 캐릭터 라인.

주의

pName 파라미터는 IPin::QueryPinInfo 메소드가 돌려주는 핀명을 지정한다. 그러나, 이 캐릭터 라인은 핀 ID 로서는 사용되지 않았다. 이 클래스에서는 핀 ID 는 반드시 Out 이다. 상세한 것에 대하여는, 「QueryId 」를 참조할것.

CTransformOutputPin::~CTransformOutputPin

CTransformOutputPin 클래스

소멸자 메소드.

구문

~CTransformOutputPin(void);

CTransformOutputPin::CurrentMediaType

CTransformOutputPin 클래스

현재의 핀 접속의 미디어 타입을 취득한다.

구문

CMediaType& CurrentMediaType(void);

반환값

CBasePin::m_mt 멤버 변수에의 참조를 돌려준다.

CTransformOutputPin::DecideBufferSize

CTransformOutputPin 클래스

버퍼 요구를 설정한다.

구문

HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *ppropInputRequest
);

파라미터

pAlloc
allocater의 IMemAllocator 인터페이스에의 포인터.
ppropInputRequest
입력 핀의 버퍼 요구가 들어가는 ALLOCATOR_PROPERTIES 구조체의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는 CBaseOutputPin::DecideBufferSize 메소드를 오버라이드(override) 한다. 필터의 순수 가상 CTransformFilter::DecideBufferSize 메소드를 호출하는, 필터의 상속 클래스는 그것을 이행 해야 한다.

CTransformOutputPin::GetMediaType

CTransformOutputPin 클래스

인덱스값으로 우선 미디어 타입을 취득한다

구문

HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

파라미터

iPosition
제로로부터 시작되는 인덱스 데이터.
pMediaType
미디어 타입을 받는 CMediaType 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_S_NO_MORE_ITEMS | 인덱스가 제한폭을 넘었다.

주의

이 메소드는 CBasePin::GetMediaType 메소드를 오버라이드(override) 한다. 필터의 입력 핀이 접속되어 있지 않으면 그 메소드는 VFW_S_NO_MORE_ITEMS 를 돌려준다. 그렇지 않으면, 필터의 CTransformFilter::GetMediaType 메소드를 호출해, 미디어 타입을 취득한다. CTransformFilter::GetMediaType 메소드는 순수 가상인, 필터의 상속 클래스는 그것을 오버라이드(override) 해야 한다.

CTransformOutputPin::Notify

CTransformOutputPin 클래스

품질 변경이 요구된 것을 핀에 통지한다. IQualityControl::Notify 메소드의 이행.

구문

HRESULT Notify(
    IBaseFilter *pSelf,
    Quality q
);

파라미터

pSelf
품질관리 메세지를 출력하는 필터의 IBaseFilter 인터페이스에의 포인터.
q
품질관리 메세지가 들어가는 Quality 구조체.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_NOT_FOUND | 메세지를 허용 하는 오브젝트를 찾아낼 수 없었다.

주의

이 메소드는 필터의 CTransformFilter::AlterQuality 메소드를 호출한다. 필터가 품질 메세지를 처리하지 않으면, 이 메소드는 CBaseInputPin::PassNotify 메소드를 필터의 입력 핀으로 호출한다. PassNotify 메소드는 품질 메세지를 업 스트림에 건네준다 (혹은, 인스톨 되고 있다면, 커스텀 품질 매니저에 건네준다).

CTransformOutputPin::QueryId

CTransformOutputPin 클래스

핀의 ID 를 취득한다. IPin::QueryId 메소드의 이행

구문

HRESULT QueryId(
    LPWSTR *Id
);

파라미터

Id
핀 ID 가 들어가는 캐릭터 라인을 받는 변수의 주소.

반환값

이하의 겉(표)에 나타나는 HRESULT 값의 1 개를 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

핀 ID 는 그래프로 이용된다. 이 클래스의 핀 ID 는 Out 이다. 이 클래스는 CBasePin 클래스의 행동을 오버라이드(override) 한다. CBasePin 클래스에서는, 핀 ID 는 클래스 constructor　 　 으로 지정된 핀명과 같다. CTransformInputPin 클래스에서는, 핀 ID 와 핀명은 같지 않다.

CTransformOutputPin::SetMediaType

CTransformOutputPin 클래스

접속때의 미디어 타입을 설정한다.

구문

HRESULT SetMediaType(
    const CMediaType *mt
);

파라미터

mt
미디어 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 CBasePin::SetMediaType 메소드를 오버라이드(override) 한다. 그것은 필터의 CTransformFilter::SetMediaType 메소드를 호출해, 필터에 정보를 준다.

핀은 미디어 타입이 이 메소드를 호출하기 전에 액세스 가능한 것을 검증해야 한다.


CTransInPlaceFilter 클래스

CTransInPlaceFilter 클래스의 계층

인플레이션 의자 변환 필터를 이행 하는 base class.

선언 : Transfrm.h

CTransInPlaceFilter 클래스는 데이터 변환을, 버퍼간의 데이터 카피를 하지 않고 , 인플레이션 의자로 실시하는 필터용으로 설계되고 있다.

가능한 한, 필터는 1 개의 allocater를 사용한다. 상세한 것에 대하여는,CompleteConnect 」를 참조할것.

이 클래스를 사용하려면 ,CTransInPlaceFilter 로부터 새로운 클래스를 파생해. 이하의 메소드를 이행 하는 것 :

  • CTransformFilter::CheckInputType
  • Transform

이 필터는 입력 핀에 CTransInPlaceInputPin 클래스를 사용해, 출력 핀에 CTransInPlaceOutputPin 클래스를 사용한다. 보통, 이러한 핑크 라스를 오버라이드(override) 할 필요는 없다. 필터는 양핀을 GetPin 메소드로 생성 한다. 핑크 라스를 오버라이드(override) 한다면, 커스텀 핀을 만드는 GetPin 를 오버라이드(override) 해야 한다.

Protected 메소드
Copy | 미디어 샘플을 카피한다.
InputPin | 필터의 입력 핀에의 포인터를 취득한다.
OutputPin | 필터의 출력 핀에의 포인터를 취득한다.
TypesMatch | 입력 미디어 타입이 출력 미디어 타입과 일치할지 어떨지 확인한다.
UsingDifferentAllocators | 입력 핀과 출력 핀이 다른 allocater를 사용하고 있는지 어떤지를 확인한다.
Public 메소드
CTransInPlaceFilter | constructor 메소드.
GetPin | 핀을 취득한다.
GetMediaType | 출력 핀용의 우선 미디어 타입을 취득한다.
DecideBufferSize | 출력 핀의 버퍼 요구를 설정한다.
CheckTransform | 입력 미디어 타입이 출력 미디어 타입과 호환성이 있을지 어떨지를 체크한다.
CompleteConnect | 핀 접속을 완료한다.
Receive | 미디어 샘플을 받아, 그것을 처리해, 다운 스트림 필터에 출력한다.
Pure Virtual 메소드
Transform | 샘플을 인플레이션 의자로 변환한다.

CTransInPlaceFilter::CheckTransform

CTransInPlaceFilter 클래스

입력 미디어 타입이 출력 미디어 타입과 호환성이 있을지 어떨지를 체크한다.

구문

HRESULT CheckTransform(
    const CMediaType *mtIn,
    const CMediaType *mtOut
);

파라미터

mtIn
입력 타입을 지정하는 CMediaType 오브젝트에의 포인터.
mtOut
출력 타입을 지정하는 CMediaType 오브젝트에의 포인터.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 CTransformFilter::CheckTransform 메소드를 오버라이드(override) 한다. CTransInPlace 내의 메소드는, 입력 타입과 출력 타입이 같다라고 가정해,CheckTransform 대신에,CTransformFilter::CheckInputType 메소드를 호출한다.

CTransInPlaceFilter::CompleteConnect

CTransInPlaceFilter 클래스

핀 접속을 완료한다.

구문

HRESULT CompleteConnect(
    PIN_DIRECTION direction,
    IPin *pReceivePin
);

파라미터

direction
필터의 어느 핀이 접속을 생성 하고 있는지를 지정하는 PIN_DIRECTION 열거형의 멤버.
pReceivePin
이 접속을 시도하고 있는 다른 핀의 IPin 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 테이블에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_NOT_IN_GRAPH | 필터가 필터 그래프에 없다.

주의

이 메소드는 CTransformFilter::CompleteConnect 메소드를 오버라이드(override) 한다.

필터의 행동은 핀 접속의 차례로 의존한다 :

  • 입력 핀이 최초로 접속되면(자), 접속은 텐포라리로케이타를 사용한다. 출력 핀이 접속될 때, 필터는 입력 핀을 재접속한다. 입력 핀의 재접속에 의해 업 스트림 필터는 allocater와 재차 네고시에이션 한다. 그 때에, 입력 핀은 데이터 스트림 필터의 allocater를 사용하려고 한다. 상세한 것에 대하여는, 「CTransInPlaceInputPin::GetAllocator 」를 참조할것.
  • 출력 핀이 최초로 접속되면(자), 출력 핀은 allocater를 선택하지 않는다. 입력 핀이 접속될 때, 양쪽 모두의 접속에 1 개의 allocater를 네고시에이션 한다. 입력 미디어 타입과 출력 미디어 타입이 같지 않는 경우, 필터는 입력 타입을 사용해 출력 핀과 재접속한다.

필터는 CBaseFilter::ReconnectPin 메소드를 호출하는 것에 의해, 모든 핀의 재접속을 실시한다. ReconnectPin 메소드는 필터 그래프 매니저의 IFilterGraph2::ReconnectEx 메소드를 차례차례로 호출한다.

CTransInPlaceFilter::Copy

CTransInPlaceFilter 클래스

미디어 샘플을 카피한다.

구문

IMediaSample *CTransInPlaceFilter::Copy(
    IMediaSample *pSource
);

파라미터

pSource
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

새로운 샘플의 IMediaSample 인터페이스에의 포인터를 돌려준다.

주의

이 메소드는 다운 스트림 allocater로부터 하늘의 버퍼를 취득한다. 그것은 샘플내의 실제의 데이터와 함께,pSource 로부터 모든 샘플 프로퍼티를 새로운 샘플에 카피한다. 필터가 2 개의 allocater를 사용하고 있다면, 이 메소드를 호출해, 버퍼간에 데이터를 카피한다.

CTransInPlaceFilter::CTransInPlaceFilter

CTransInPlaceFilter 클래스

constructor　 　 메소드.

구문

CTransInPlaceFilter(
    TCHAR *pObjectName,
    LPUNKNOWN lpUnk,
    REFCLSID clsid,
    HRESULT *phr,
    bool bModifiesData = true
);

파라미터

pObjectName
필터의 디버그명이 들어가는 캐릭터 라인. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
lpUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되고 있다면, 집성 오브젝트의 IUnknown 에의 포인터를 건네준다. 그렇지 않으면, 이 파라미터를 NULL 로 설정한다.
clsid
필터의 클래스 ID.
phr
무시된다.
bModifiesData
필터가 입력 데이터를 수정할지 어떨지를 지정하는 불리언 값. TRUE 라면, 필터는 데이터를 수정한다. 그 이외라면, 필터는 데이터를 변경하지 않고 다운 스트림에 건네준다.

CTransInPlaceFilter::DecideBufferSize

CTransInPlaceFilter 클래스

출력 핀의 버퍼 요구를 설정한다.

구문

HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *pProperties
);

파라미터

pAlloc
출력 핀이 사용하는 IMemAllocator 오브젝트에의 포인터.
pProperties
요구된 allocater 프로퍼티에의 포인터, 그것은 ALLOCATOR_PROPERTIES 로 지정되고 있는 카운트, 사이즈, alignment이다.

반환값

HRESULT 값을 돌려준다. 이하의 테이블에 나타나는 몇개의 값.

S_OK | 성공.
E_FAIL | 실패.

주의

이 메소드는 CTransformFilter::DecideBufferSize 메소드를 오버라이드(override) 한다. 그것은 이전의 버젼의 CTransInPlaceFilter 산다라는 호환성을 위해서(때문에) 존재한다. 현재의 버젼에서는, 업 스트림 출력 핀은 allocater의 다운 스트림 입력 핀과 직접 네고시에이션 한다. 필터의 출력 핀은 이것에 관련되지 않는다.

CTransInPlaceFilter::GetMediaType

CTransInPlaceFilter 클래스

출력 핀용의 우선 미디어 타입을 취득한다.

구문

HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

파라미터

iPosition
제로로부터 시작되는 인덱스값.
pMediaType
미디어 타입을 받는 CMediaType 오브젝트에의 포인터.

반환값

E_UNEXPECTED 를 돌려준다.

주의

이 메소드는 CTransformFilter::GetMediaType 메소드를 오버라이드(override) 한다. CTransInPlaceFilter 클래스에서는, 각 핀은 정면의 접속 핀을 호출해, 우선 미디어 타입을 열거한다. 입력 핀은 다운 스트림 필터의 입력 핀을 호출해, 출력 핀은 업 스트림 필터의 출력 핀을 업 스트림을 호출한다. 그러므로, 필터의 GetMediaType 메소드는 결코 불려 가지 않는다.

CTransInPlaceFilter::GetPin

CTransInPlaceFilter 클래스

핀을 취득한다.

구문

virtual CBasePin *GetPin(
    int n
);

파라미터

n
지정한 핀의 수, 제로로부터 시작되는 인덱스. 이 필터에서는, 핀 0 은 입력 핀으로, 핀 1 은 출력 핀이다.

반환값

핀을 이행 하는 CBasePin 오브젝트에의 포인터를 돌려주는, 메소드가 실패 하면 NULL 를 돌려준다.

주의

이 메소드는 CTransformFilter::GetPin 메소드를 오버라이드(override) 한다. 최초로 이 메소드가 불려 갔을 때, 양쪽 모두의 핀을 생성 한다.

이 메소드는 되돌아 온 핀의 참조 카운트를 인크리먼트(increment) 하지 않기 때문에, 돌아간 핀은 참조 카운트를 남기지 않는다. 호출원이 그 핀의 참조 카운트를 보관 유지할 필요가 있다면, 그 핀의 IUnknown::AddRef 메소드를 호출해야 하는 것이다.

필터가 디폴트의 CTransInPlaceInputPin 핀과 CTransInPlaceOutputPin 핀을 사용한다면, 이 메소드를 오버라이드(override) 할 필요는 없다. 그러나, 필터가 이러한 클래스를 확장한 핀을 사용한다면, 이 메소드를 오버라이드(override) 해 그 타입의 핀을 생성 해야 한다.

CTransInPlaceFilter::InputPin

CTransInPlaceFilter 클래스

필터의 입력 핀에의 포인터를 취득한다.

구문

CTransInPlaceInputPin *InputPin(void);

반환값

CTransformFilter.m_pInput 멤버 변수를 돌려준다.

CTransInPlaceFilter::OutputPin

CTransInPlaceFilter 클래스

필터의 출력 핀에의 포인터를 취득한다.

구문

CTransInPlaceOutputPin *OutputPin(void);

반환값

CTransformFilter.m_pOutput 멤버 변수를 돌려준다.

CTransInPlaceFilter::Receive

CTransInPlaceFilter 클래스

미디어 샘플을 받아, 그것을 처리해, 다운 스트림 필터에 출력한다.

구문

HRESULT Receive(
    IMediaSample *pSample
);

파라미터

pSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 테이블에 나타나는 몇개의 값.

S_OK | 성공.
E_UNEXPECTED | 예기치 못한 에러.

주의

필터의 입력 핀은 샘플을 취득 하면 와, 이 메소드를 호출한다. 필터는 Transform 메소드를 호출하는, 상속 클래스는 그것을 이행 해야 한다. Transform 메소드는 데이터를 처리한다. 필터가 1 개의 allocater만을 사용하고 있다면,pSample 를 직접 Tranform 메소드에 건네준다. 그 이외라면,pSample 를 카피해, 그 카피를 건네준다.

Transform 메소드가 S_FALSE 를 돌려주면(자),Receive 메소드는 샘플을 드롭 한다. 최초로 드롭 된 샘플에서는, 필터는 EC_QUALITY_CHANGE 이벤트를 필터 그래프 매니저에 보낸다. 한편,Transform 메소드가 S_OK 를 돌려주면(자), 필터는 출력 샘플을 출력한다. 그것을 실시하기 (위해)때문에, 다운 스트림 입력 핀의 IMemInputPin::Receive 메소드를 호출한다.

CTransInPlaceFilter::Transform

CTransInPlaceFilter 클래스

샘플을 인플레이션 의자로 변환한다.

구문

virtual HRESULT Transform(
    IMediaSample *pSample
) PURE;

파라미터

pSample
샘플의 IMediaSample 인터페이스에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 테이블에 나타나는 몇개의 값.

S_FALSE | 이 샘플을 출력할 수 없다.
S_OK | 성공.

주의

상속 클래스는 이 메소드를 이행 해야 한다. 샘플 데이터를 인플레이션 의자로 변환하는 것. 필터가 2 개의 allocater를 사용하고 있다면, 입력 샘플로부터 새로운 샘플에 데이터를 카피해, 그 카피를 이 메소드에 건네준다.

(예를 들어, 품질관리를 지원 하기 위해서) 필터가 이 샘플을 출력해야 하는 것이 아니면, 메소드는 S_FALSE 를 돌려주어야 하는 것이다.

CTransInPlaceFilter::TypesMatch

CTransInPlaceFilter 클래스

입력 미디어 타입이 출력 미디어 타입과 일치할지 어떨지 확인한다.

구문

BOOL TypesMatch(void);

반환값

입력 미디어 타입과 출력 미디어 타입이 같으면 TRUE 를 돌려주어, 그 이외라면 FALSE 를 돌려준다.

CTransInPlaceFilter::UsingDifferentAllocators

CTransInPlaceFilter 클래스

입력 핀과 출력 핀이 다른 allocater를 사용하고 있는지 어떤지를 확인한다.

구문

BOOL UsingDifferentAllocators(void) const;

반환값

입력 핀과 출력 핀이 다른 allocater를 사용하고 있다면 TRUE 를 돌려주어, 그 이외라면 FALSE 를 돌려준다.


CTransInPlaceInputPin 클래스

CTransInPlaceInputPin 클래스의 계층

CTransInPlaceFilter 클래스가 사용하는 입력 핀.

선언 : Transip.h

보통, 이 클래스로부터 파생시킬 필요는 없다. 파생시킨다면, 필터의 CTransInPlaceFilter::GetPin 메소드를 오버라이드(override) 해, 상속 클래스의 인스턴스를 생성 해야 한다.

Protected Member 변수
m_bReadOnly | 입력 스트림이 읽어들여 전용인가 어떤가를 지정하는 플래그.
m_pTIPFilter | 이 핀을 생성 한 필터에의 포인터.
Public 메소드
CTransInPlaceInputPin | constructor 메소드.
CheckMediaType | 지정한 미디어 타입이 허용 되는 것을 확인한다.
PeekAllocator | 핀의 allocater에의 포인터를 취득한다.
ReadOnly | 입력 스트림이 읽어들여 전용인가 어떤가를 확인한다.
IPin 메소드
EnumMediaTypes | 핀의 우선 미디어 타입을 열거한다.
IMemInputPin 메소드
GetAllocator | 이 핀이 제안한 메모리 allocater를 취득한다.
NotifyAllocator | 접속의 allocater를 지정한다.
GetAllocatorRequirements | 핀이 요구한 allocater를 취득한다.

CTransInPlaceInputPin.m_bReadOnly

CTransInPlaceInputPin 클래스

입력 스트림이 읽어들여 전용인가 어떤가를 지정하는 플래그. 업 스트림 필터가 NotifyAllocator 메소드를 호출했을 때, 이 정보를 지정한다. 디폴트에서는 이 값은 FALSE 이다.

구문

BOOL m_bReadOnly;

CTransInPlaceInputPin.m_pTIPFilter

CTransInPlaceInputPin 클래스

이 핀을 생성 한 필터에의 포인터.

구문

CTransInPlaceFilter * const m_pTIPFilter;

CTransInPlaceInputPin::CheckMediaType

CTransInPlaceInputPin 클래스

지정한 미디어 타입이 허용 되는 것을 확인한다.

구문

HRESULT CheckMediaType(
    const CMediaType *pmt
);

파라미터

pmt
제안된 미디어 타입이 들어가는 CMediaType 오브젝트에의 포인터.

반환값

미디어 타입이 허용 된다면 S_OK 가 돌아간다. 그 이외라면, S_FLASE 나 에러 코드가 돌아간다.

주의

이 메소드는 CTransformInputPin::CheckMediaType 메소드를 오버라이드(override) 한다. 그것은 필터의 CTransformFilter::CheckInputType 메소드를 호출해, 입력 타입을 체크한다. 출력 핀이 접속되고 있으면, 이 메소드는 다운 스트림 입력 핀의 IPin::QueryAccept 메소드도 호출해.

CTransInPlaceInputPin::CTransInPlaceInputPin

CTransInPlaceInputPin 클래스

constructor　 　 메소드.

구문

CTransInPlaceInputPin(
    TCHAR *pObjectName,
    CTransInPlaceFilter *pFilter,
    HRESULT *phr,
    LPCWSTR pName
);

파라미터

pObjectName
오브젝트의 디버그명이 들어가는 캐릭터 라인. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pFilter
이 핀을 생성 한 필터에의 포인터, 이것은 CTransformFilter 오브젝트가 아니면 안된다.
phr
메소드의 성공 실패를 나타내는 HRESULT 값을 받는 변수에의 포인터. 이 값은 오브젝트를 생성 하기 전에 S_OK 로 초기화된다. 값은 에러가 일어났을 경우만 변경된다.
pName
핀명이 들어가는 Unicode™ 캐릭터 라인.

주의

pName 파라미터는 IPin::QueryPinInfo 메소드가 돌려주는 핀명을 지정한다. 그러나, 이 캐릭터 라인은 핀 ID 로서는 사용되지 않았다. 이 클래스에서는 핀 ID 는 반드시 In 이다. 상세한 것에 대하여는, 「QueryId 」를 참조할것.

CTransInPlaceInputPin::EnumMediaTypes

CTransInPlaceInputPin 클래스

핀의 우선 미디어 타입을 열거한다. IPin::EnumMediaTypes 메소드의 이행.

구문

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

파라미터

ppEnum
IEnumMediaTypes 인터페이스에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터.
VFW_E_NOT_CONNECTED | 출력 핀이 접속되어 있지 않다.

주의

이 메소드는 다운 스트림 입력 핀으로부터 IEnumMediaTypes 인터페이스를 돌려준다.

CTransInPlaceInputPin::GetAllocator

CTransInPlaceInputPin 클래스

이 핀이 제안한 메모리 allocater를 취득한다. IMemInputPin::GetAllocator 메소드의 이행.

구문

HRESULT GetAllocator(
    IMemAllocator **ppAllocator
);

파라미터

ppAllocator
allocater의 IMemAllocator 인터페이스에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 테이블에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_NO_ALLOCATOR | 이용 가능한 allocater가 없다.

주의

필터의 출력 핀이 접속되고 있다면, 이 메소드는 다운 스트림 필터의 입력 핀을 요구한다.

필터의 출력 핀이 접속되어 있지 않으면, 이 메소드는 텐포라리아로케이타를 생성 한다. 다음에, 출력 핀이 접속되었을 때, 필터는 입력 핀과 재접속해, allocater를 재네고시에이션 한다.

CTransInPlaceInputPin::GetAllocatorRequirements

CTransInPlaceInputPin 클래스

핀이 요구한 allocater를 취득한다. IMemInputPin::GetAllocatorRequirements 메소드의 이행.

구문

HRESULT GetAllocatorRequirements(
    ALLOCATOR_PROPERTIES *pProps
);

파라미터

pProps
요구가 기입해지는 ALLOCATOR_PROPERTIES 구조체에의 포인터

반환값

HRESULT 값을 돌려준다. 이하의 테이블에 나타나는 몇개의 값.

S_OK | 성공.
E_NOTIMPL | 출력 핀이 접속되어 있지 않은, 혹은 다운 스트림 핀이 메소드를 지원 하고 있지 않다.
E_POINTER | Null 포인터 인수.

주의

출력 핀이 접속되고 있으면, 이 메소드는 호출을 다운 스트림 입력 핀에 건네준다. 그 이외라면 E_NOTIMPL 를 돌려준다.

CTransInPlaceInputPin::NotifyAllocator

CTransInPlaceInputPin 클래스

접속의 allocater를 지정한다. IMemInputPin::NotifyAllocator 메소드의 이행.

구문

HRESULT NotifyAllocator(
    IMemAllocator *pAllocator,
    BOOL bReadOnly
);

파라미터

pAllocator
allocater의 IMemAllocator 인터페이스에의 포인터.
bReadOnly
이 allocater로부터의 샘플이 읽어들여 전용인가 어떤가를 나타내는 플래그. TRUE 라면 샘플은 읽어들여 전용.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_FAIL | 실패.
E_POINTER | NULL 포인터 인수.

주의

필터는 양쪽 모두의 핀 접속에 같은 allocater를 사용하려고 한다.

  • 출력 핀이 접속되어 있지 않으면, 입력 핀은 자동적으로 allocater를 승인한다. 출력 핀이 접속되고 있으면(자), 필터는 입력 핀을 재접속한다. 그 때, 필터는 다시 1 개의 allocater를 사용하려고 한다.
  • 출력 핀이 접속되고 있으면(자), 입력 핀은 allocater를 허용 한다. 출력 핀도 같은 allocater를 사용한다. 그것은 다운 스트림 입력 핀의 NotifyAllocator 를 호출한다.

위의 케이스에는 다음의 예외가 있다 :

  • 제안된 allocater가 읽어들여 전용 (이것은 bReadOnly 가 TRUE) 한편, 필터가 샘플을 집성 할 필요가 있는 경우, 필터는 2 개가 다른 allocater 사용할 필요가 있다. 이 경우, 업 스트림 필터는 다운 스트림 필터의 allocater의 사용을 제안하면, 메소드는 E_FAIL 를 돌려준다.

CTransInPlaceInputPin::PeekAllocator

CTransInPlaceInputPin 클래스

핀의 allocater에의 포인터를 취득한다. 이 메소드는 인터페이스의 참조 카운트를 인크리먼트(increment) 하지 않는다.

구문

IMemAllocator *PeekAllocator(void)

반환값

CBaseInputPin.m_pAllocator 멤버 변수를 돌려준다.

CTransInPlaceInputPin::ReadOnly

CTransInPlaceInputPin 클래스

입력 스트림이 읽어들여 전용인가 어떤가를 확인한다.

구문

const BOOL ReadOnly(void);

반환값

m_bReadOnly 멤버 변수의 값을 돌려준다.


CTransInPlaceOutputPin 클래스

CTransInPlaceOutputPin 클래스의 계층

CTransInPlaceFilter 클래스가 사용하는 출력 핀.

선언 : Transip.h

보통, 이 클래스로부터 파생시킬 필요는 없다. 파생시킨다면, 필터의 CTransInPlaceFilter::GetPin 메소드를 오버라이드(override) 해, 상속 클래스의 인스턴스를 생성 해야 한다.

Protected Member 변수
m_pTIPFilter | 이 핀을 생성 한 필터에의 포인터.
Public 메소드
CTransInPlaceOutputPin | constructor 메소드.
DecideAllocator | 메모리 allocater를 선택한다.
CheckMediaType | 지정한 미디어 타입을 핀이 허용 하는 것을 확인한다.
SetAllocator | 접속때의 allocater를 지정한다.
ConnectedIMemInputPin | 다운 스트림 입력 핀에의 포인터를 취득한다.
PeekAllocator | 핀의 allocater에의 포인터를 취득한다.
IPin 메소드
EnumMediaTypes | 핀의 우선 미디어 타입을 열거한다.

CTransInPlaceOutputPin.m_pTIPFilter

CTransInPlaceOutputPin 클래스

이 핀을 생성 한 필터에의 포인터.

구문

CTransInPlaceFilter * const m_pTIPFilter;

CTransInPlaceOutputPin::CheckMediaType

CTransInPlaceOutputPin 클래스

지정한 미디어 타입을 핀이 허용 하는 것을 확인한다.

구문

HRESULT CheckMediaType(
    const CMediaType *pmt
);

파라미터

pmt
제안된 미디어 타입을 넣는 CMediaType 오브젝트에의 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 테이블에 나타나는 몇개의 값.

S_OK | 성공.
VFW_E_TYPE_NOT_ACCEPTED | 미디어 타입은 허용 되지 않았다.

주의

이 메소드는 CTransformOutputPin::CheckMediaType 메소드를 오버라이드(override) 한다.

필터가 이미 스트리밍을 흘려, 2 개의 allocater를 사용하고 있다면, 이 메소드는 모든 포맷 변경을 거부한다. 그 이외라면, 이 메소드는 필터의 CTransformFilter::CheckInputType 메소드를 호출해, 미디어 타입을 체크한다. 입력 핀이 접속되고 있다면, 업 스트림 출력 핀의 IPin::QueryAccept 메소드도 호출한다.

CTransInPlaceOutputPin::ConnectedIMemInputPin

CTransInPlaceOutputPin 클래스

다운 스트림 입력 핀에의 포인터를 취득한다. 이 메소드는 CBaseOutputPin.m_pInputPin 멤버 변수를 돌려준다.

구문

IMemInputPin *ConnectedIMemInputPin(void);

반환값

다운 스트림 입력 핀의 IMemInputPin 인터페이스에의 포인터를 돌려준다.

CTransInPlaceOutputPin::CTransInPlaceOutputPin

CTransInPlaceOutputPin 클래스

constructor　 　 메소드.

구문

CTransInPlaceOutputPin(
    TCHAR *pObjectName,
    CTransInPlaceFilter *pFilter,
    HRESULT *phr,
    LPCWSTR pName
);

파라미터

pObjectName
오브젝트의 디버그명이 들어가는 캐릭터 라인. 상세한 것에 대하여는, 「CBaseObject 」를 참조할것.
pFilter
이 핀을 생성 한 필터에의 포인터, 이것은 CTransInPlaceFilter 오브젝트가 아니면 안된다.
phr
메소드의 성공 실패를 나타내는 HRESULT 값을 받는 변수에의 포인터. 이 값은 오브젝트를 생성 하기 전에 S_OK 로 초기화된다. 값은 에러가 일어났을 경우만 변경된다.
pName
핀명이 들어가는 Unicode™ 캐릭터 라인.

주의

pName 파라미터는 IPin::QueryPinInfo 메소드가 돌려주는 핀명을 지정한다. 그러나, 이 캐릭터 라인은 핀 ID 로서는 사용되지 않았다. 이 클래스에서는 핀 ID 는 반드시 Out 이다. 상세한 것에 대하여는, 「QueryId 」를 참조할것.

CTransInPlaceOutputPin::DecideAllocator

CTransInPlaceOutputPin 클래스

메모리 allocater를 선택한다.

구문

HRESULT DecideAllocator(
    IMemInputPin *pPin,
    IMemAllocator **ppAlloc
);

파라미터

pPin
입력 핀의 IMemInputPin 인터페이스에의 포인터.
ppAlloc
allocater의 IMemAllocator 인터페이스의 포인터를 받는 변수의 주소.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 CBaseOutputPin::DecideAllocator 메소드를 오버라이드(override) 한다.

이것은 아무것도 하지 않는 더미 메소드이다, 왜냐하면 이 필터의 출력 핀은 allocater를 제공하지 않기 때문에이다. 그 대신, allocater는 입력 핀의 접속 프로세스중으로 결정된다. 입력 핀의 CTransInPlaceInputPin::NotifyAllocator 메소드는 다운 스트림 입력 핀의 NotifyAllocator 를 호출한다.

CTransInPlaceOutputPin::EnumMediaTypes

CTransInPlaceOutputPin 클래스

핀의 우선 미디어 타입을 열거한다. IPin::EnumMediaTypes 메소드의 이행.

구문

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

파라미터

ppEnum
IEnumMediaTypes 인터페이스에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 겉(표)에 나타나는 몇개의 값.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터.
VFW_E_NOT_CONNECTED | 필터의 입력 핀이 접속되어 있지 않다.

주의

이 메소드는 업 스트림 출력 핀으로부터 IEnumMediaTypes 인터페이스를 돌려준다.

CTransInPlaceOutputPin::PeekAllocator

CTransInPlaceOutputPin 클래스

핀의 allocater에의 포인터를 취득한다. 이 메소드는 인터페이스의 참조 카운트를 인크리먼트(increment) 하지 않는다.

구문

IMemAllocator *PeekAllocator(void)

반환값

CBaseOutputPin.m_pAllocator 멤버 변수를 돌려준다.

CTransInPlaceOutputPin::SetAllocator

CTransInPlaceOutputPin 클래스

접속때의 allocater를 지정한다.

구문

void SetAllocator(
    IMemAllocator *pAllocator
);

파라미터

pAllocator
allocater의 IMemAllocator 인터페이스에의 포인터.

주의

이 필터의 출력 핀은 allocater를 제공하지 않는다. 이 메소드는 출력 핀용의 allocater를 지정한다. 그것은 CBaseOutputPin.m_pAllocator 멤버 변수의 값을 설정한다.


CUnknown 클래스

CUnknown 클래스의 계층

IUnknown 인터페이스를 이행 한다. Microsoft® DirectShow® 의 대부분의 Component Object Model (COM) 오브젝트는 CUnknown 로부터 파생한다.

선언 : Cobmase.h

오브젝트를 이행 하는 경우,CUnknown 로부터 파생시키고 싶은 경우도 있다. CUknown 로부터 파생시키면(자), thread 대응의 이행이 제공되는 것 외에IUnknown 를 이행 하는 귀찮음이 없어진다.

이 base class의 사용법에 대해서는, 「IUnknown 의 이행 방법」을 참조할것. 이하에 그 요약을 나타낸다.

  • 클래스 정의의 public 섹션에 DECLARE_IUNKNOWN 매크로를 인클루드 한다. 이 매크로는,IUnknown 인터페이스의 3 개의 메소드를 선언한다.
  • NonDelegatingQueryInterface 메소드를 오버라이드(override) 해,IUnknown 이외의 인터페이스를 지원 한다. 이 메소드내에서 GetInterface 함수를 호출해, 인터페이스 포인터를 취득한다.
  • 클래스 constructor　 　 내에서 CUnknown constructor　 　 메소드를 호출한다.
Protected 멤버 변수
m_cRef | 참조 카운트.
Public 메소드
CUnknown | constructor　 　 메소드.
~CUnknown | 소멸자 메소드.
GetOwner | 제어하는 IUnknown 에의 포인터를 취득한다.
INonDelegatingUnknown 메소드
NonDelegatingAddRef | 참조 카운트를 인크리먼트(increment) 한다.
NonDelegatingQueryInterface | 인터페이스 포인터를 취득해, 참조 카운트를 인크리먼트(increment) 한다.
NonDelegatingRelease | 참조 카운트를 감소 한다.

CUnknown.m_cRef

CUnknown 클래스

참조 카운트.

구문

volatile LONG m_cRef;

주의

NonDelegatingAddRef 또는 NonDelegatingRelease 메소드를 오버라이드(override) 하는 경우는 이 멤버 변수를 사용한다.

CUnknown::CUnknown

CUnknown 클래스

constructor　 　 메소드.

구문

CUnknown(
    const TCHAR *pName,
    LPUNKNOWN pUnk
);

파라미터

pName
오브젝트의 이름을 저장 하고 있는 캐릭터 라인. 데밧깅을 위해서(때문에) CBaseObject constructor　 　 으로 사용된다.
pUnk
이 오브젝트의 소유자에게로의 포인터. 오브젝트가 집성 되고 있는 경우는, 집성 오브젝트의 IUnknown 인터페이스에 포인터를 건네준다. 그 이외의 경우는, 이 파라미터를 NULL 로 설정한다.

주의

오브젝트는 참조 카운트가 제로로서 초기화된다.

CUnknown::~CUnknown

CUnknown 클래스

소멸자 메소드.

구문

virtual ~CUnknown(void);

CUnknown::GetOwner

CUnknown 클래스

소유 컴퍼넌트의 IUnknown 인터페이스에의 포인터를 취득한다. 집성 한 컴퍼넌트의 경우, 그 소유자는 외부 컴퍼넌트이다. 그 이외의 경우, 컴퍼넌트는 그 자체를 소유한다.

구문

LPUNKNOWN GetOwner(void);

반환값

제어하는 IUnknown 인터페이스에의 포인터를 돌려준다.

CUnknown::NonDelegatingAddRef

CUnknown 클래스

오브젝트의 참조 카운트를 인크리먼트(increment) 한다. INonDelegatingUnknown::NonDelegatingAddRef 메소드를 이행 한다.

구문

ULONG NonDelegatingAddRef(void);

반환값

참조 카운트를 돌려준다.

CUnknown::NonDelegatingQueryInterface

CUnknown 클래스

인터페이스 포인터를 취득해, 참조 카운트를 인크리먼트(increment) 한다. INonDelegatingUnknown::NonDelegatingQueryInterface 메소드를 이행 한다.

구문

HRESULT NonDelegatingQueryInterface(
    REFIID riid,
    void **ppv
);

파라미터

riid
인터페이스의 식별자.
ppv
인터페이스를 받는 포인터의 주소.

반환값

다음 표에 나타나는 몇개의 HRESULT 값을 돌려준다.
S_OK | 성공.
E_NOINTERFACE | 오브젝트는 이 인터페이스를 지원 하고 있지 않다.
E_POINTER | NULL 포인터 인수.

주의

CUnknown 클래스는 IUknown 인터페이스만을 공개한다. 이 메소드의 오버라이드(override) 방법에 대해서는, 「IUnknown 의 이행 방법」을 참조할것.

CUnknown::NonDelegatingRelease

CUnknown 클래스

오브젝트의 참조 카운트를 감소 한다. INonDelegatingUnknown::NonDelegatingRelease 메소드를 이행 한다.

구문

ULONG NonDelegatingRelease(void);

반환값

참조 카운트를 돌려준다.

주의

참조 카운트가 제로가 되면(자), 오브젝트는 그 자체를 삭제한다.


CVideoTransformFilter 클래스

CVideoTransformFilter 클래스의 계층

CVideoTransformFilter 클래스는, 기본적으로는 AVI 데콘프렛사피르타의 base class로서 설계되고 있다. 이 클래스는, "카피 " 변환 클래스에 근거하고 있어 출력 버퍼로서 비디오 버퍼 또는 Microsoft® DirectDraw® 버퍼를 상정하고 있다. 이 클래스는, 다른 타입의변환 필터의 base class라고 해도 사용할 수 있다. 이 클래스의 주된 기능은, 변환 필터에서의 품질 컨트롤을 가능하게 하는 것에 있다. 즉, 이 클래스는, 처리중의 미디어 스트림에 관한 다른 요소나 필터의 동작을 고려하면서,렌더러로부터 받은 품질 통지에 근거해 프레임을 드롭 하는 것을 결정한다.

CVideoTransformFilter::Receive 멤버 함수가 불려 갈 때 마다, 이 함수는 CVideoTransformFilter::ShouldSkipFrame 를 호출해, 프레임의 스킵을 시작, 속행, 또는 정지할지 어떨지를 결정한다. 이 멤버 함수는, 이하의 조건이 모두 채워지는 경우에게만, 샘플의 스킵을 시작 한다.

  • 디코드의 평균 타임이 프레임 타임의 것 1/4 을 넘고 있다.
  • 필터가 적어도 1 프레임 늦어 실행되고 있다.
  • 다음의 키 프레임이 불과 1 프레임 먼저 있다고 예상된다.
  • 키 프레임이 충분한 빈도로 나타난다.

프레임의 스킵을 시작 하면, 이 클래스는 키 프레임이 나타날 때까지 프레임을 스킵 한다. 이 때,m_bSkipping 플래그를 리셋 해 샘플을 처리한다.

키 프레임은, AVI 키 프레임 또는 MPEG I 프레임으로서 정의된다. 이것들은 디코드하는 역사를 필요로 하지 않고, 이것들이 스킵 되었을 경우는, 다음의 키 프레임까지 다른 프레임을 디코드할 수가 없게 된다. 비키 프레임에는, AVI 비키 프레임, MPEG P 프레임, 및 MPEG B 프레임이 있다. MPEG B 프레임은, 다른 비키 프레임과 같이 이 클래스에서 다루어진다. (MPEG B 프레임은, 프레임을 스킵 할 필요없고, 드롭 할 수가 있다. 다만, 이 클래스는 주로 AVI 데콘프렛사를 대상으로 하고 있으므로, 그러한 조작은 용서되지 않는다. 몇개의 프레임이 스킵 되면(자), 다음의 키 프레임까지의 모든 프레임이 스킵 된다. )

Protected 데이터 멤버

m_bNoSkip | 다음의 키 프레임까지의 스킵을 실시하지 않는 경우는, TRUE 로 설정한다 (필터를 디버그 하는 경우).
m_bQualityChanged | 스트림이 저하하고 있는지 어떤지를 나타내는 상태 플래그. 상속 클래스의 Transform 멤버 함수 호출이 실패했을 경우는 CVideoTransformFilter::Receive 내에서 TRUE 로 설정된다. (S_FALSE 는 엔드 오브 스트림에 도달한 것을 나타내므로, 이 경우,Receive 는 NOERROR 를 돌려준다. )
m_bSkipping | 필터가 다음의 키 프레임까지 스킵 하고 있는 경우는 TRUE 로 설정된다.
m_idFrameType | 퍼포먼스 측정 프레임 타입 식별자.
m_idLate | 지연을 측정하기 위한 퍼포먼스 식별자 (PERF 가 정의되고 있는 경우에 이용 가능).
m_idSkip | 프레임의 스킵을 측정하기 위한 퍼포먼스 식별자.
m_idTimeTillKey | 다음의 키 프레임이 올 때까지의 예상 시간 (밀리 세컨드 단위)을 나타내는 퍼포먼스 식별자.
m_itrAvgDecode | 샘플의 디코드 (변환)에 필요로 하는 평균 타임. 이 값이 프레임 타임의 것 1/4 보다 작은 경우는, 이 필터에서는 품질에 관한 문제가 발생하고 있지 않고, 프레임의 드롭도 발생하고 있지 않으면 상정된다.
m_itrLate | 현재의 프레임이 늦는 타임. 본래 이 값은, 렌더링 필터로부터 건네받은 품질 컨트롤 메세지내의 Quality 구조체의 Late 멤버의 값으로 설정된다. 이 값은, 스킵 된 각 프레임의 프레임 타임부터 요구된다.
m_nFramesSinceKeyFrame | 전회의 키 프레임 이후의 프레임수를 카운트 하기 위해서 사용한다.
m_nKeyFramePeriod | 키 프레임간의 간격의 최대치.
m_nWaitForKey | 최초의 키 프레임을 취득하기 전에, 포맷 변경 후의 출력을 보증하기 위해서 사용한다. 제로 이외의 값의 경우, 프레임은 렌더러에게 건네지지 않는다. 포맷이 변경되어 각각의 비키 프레임으로 감소 되는 경우는, 30 으로 설정된다.
m_tDecodeStart | 디코딩의 시작시 이후의 타임.

멤버 함수

AlterQuality | 출력 핀으로부터 품질 컨트롤 통지를 받아, 미디어 스트림의 품질을 변경할 기회를 제공한다.
CVideoTransformFilter | CVideoTransformFilter 오브젝트를 생성 한다.
ShouldSkipFrame | 필터가 프레임의 스킵을 시작, 속행, 또는 정지해야할 것인가 제발을 판정한다.

오버라이드(override) 가능한 멤버 함수

EndFlush | flushing 상태를 종료한 취지의 통지를 받아, 그것을 다운 스트림에 건네준다.
Receive | 미디어 샘플을 받아, 샘플을 스킵 하는지, 또는 미디어 샘플을 변환해 배송한다.
RegisterPerfId | 퍼포먼스 계측 식별자를 등록한다.
StartStreaming | CTransformFilter::StartStreaming 를 오버라이드(override) 해, 스트리밍 또는 flushing의 시작시에 품질 컨트롤 정보를 리셋 한다.

CVideoTransformFilter::AlterQuality

CVideoTransformFilter 클래스

품질 컨트롤 통지를 받아, 미디어 스트림의 품질을 변경할 기회를 제공한다.

구문

virtual HRESULT AlterQuality(
    Quality q
);

파라미터

q
품질 컨트롤 통지 메세지.

반환값

디폴트에서는 E_FAIL 를 돌려준다.

주의

이 멤버 함수는,CTransformFilter::AlterQuality 멤버 함수를 오버라이드(override) 한다. 이 멤버 함수는, 품질 컨트롤 메세지를 업 스트림에 건네주기 위해서(때문에) CBaseInputPin::PassNotify 멤버 함수를 호출하기 전에,CTransformOutputPin::Notify 멤버 함수로부터 불려 간다. 이 함수는,CVideoTransformFilter::m_itrLate 데이터 멤버를 Quality 구조체의 Late 멤버의 값으로 설정해, 필터가 프레임을 스킵 할지 어떨지를 판정할 수 있도록(듯이) 한다. 이 함수는 E_FAIL 를 돌려주므로, 렌더러의 다운 스트림은 품질 컨트롤을 속행한다.

CVideoTransformFilter::CVideoTransformFilter

CVideoTransformFilter 클래스

CVideoTransformFilter 오브젝트를 생성 한다.

구문

CVideoTransformFilter(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    REFCLSID clsid
);

파라미터

pName
CVideoTransformFilter 오브젝트의 이름에의 포인터.
pUnk
제어하는 IUnknown 인터페이스에의 포인터.
clsid
CVideoTransformFilter 클래스의 클래스 식별자.

반환값

반환값 없음.

CVideoTransformFilter::EndFlush

CVideoTransformFilter 클래스

필터가 flushing 상태를 종료한 취지의 통지를 받아, 그것을 다운 스트림에 건네준다.

구문

HRESULT EndFlush(void);

반환값

필터로입력 핀이 검출되지 않았던 경우는,VFW_E_NOT_CONNECTED 를 돌려준다. 그 이외의 경우는,IPin::EndFlush 메소드가 돌려주는 값을 돌려준다.

주의

이 멤버 함수는,CTransformFilter::EndFlush 멤버 함수를 오버라이드(override) 해 품질관리 정보를 리셋 한다.

CVideoTransformFilter::Receive

CVideoTransformFilter 클래스

미디어 샘플을 받아, 샘플을 스킵 하는지, 또는 미디어 샘플을 변환해 배송한다.

구문

HRESULT Receive(
    IMediaSample *pSample
);

파라미터

pSample
배송하는 샘플에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는,CTransformFilter::Receive 멤버 함수를 오버라이드(override) 한다. 프로세스를 한층 더 상세하게 제어하고 싶은 경우에게만 오버라이드(override) 한다.

CVideoTransformFilter::RegisterPerfId

CVideoTransformFilter 클래스

퍼포먼스 계측 식별자를 등록한다.

구문

virtual void RegisterPerfId(void);

반환값

반환값 없음.

주의

디폴트에서는, 이 멤버 함수는 이하의 퍼포먼스 식별자를 등록한다.
퍼포먼스 식별자 | 등록되는 캐릭터 라인
m_idSkip | 비디오 변환 스킵 프레임.
m_idFrameType | 비디오 변환 프레임 타입.
m_idLate | 비디오 변환의 지연.
m_idTimeTillKey | 다음의 키까지의 비디오 변환의 예상 타임.

상속 클래스로 퍼포먼스 계측 식별자를 등록하고 싶으면, 이 멤버를 오버라이드(override) 하는 것. 그 경우, 똑같이 등록하는 것에 주의 해야 한다.

CVideoTransformFilter::ShouldSkipFrame

CVideoTransformFilter 클래스

필터가 프레임의 스킵을 시작, 속행, 또는 정지해야할 것인가 제발을 판정한다.

구문

BOOL ShouldSkipFrame(
    IMediaSample *pIn
);

파라미터

pIn
변환 또는 스킵 한다, 받은 샘플에의 포인터.

반환값

필터가 이 샘플을 스킵 해야 할 경우는 TRUE 를 돌려주어, 그 이외의 경우는 FALSE 를 돌려준다.

주의

이 멤버 함수는, 샘플이 키 프레임 (sync 포인트)의 경우에 m_bSkipping 멤버 변수를 FALSE 로 설정해, FALSE 를 돌려준다. 이것에 의해, 이미 시작 되고 있는 스킵 처리가 정지된다. 이 멤버 함수는, 이하의 조건이 모두 채워지는 경우에게만, 샘플의 스킵을 시작 한다 (m_bSkipping 를 TRUE 로 설정해, TRUE 를 돌려준다).

  • 디코드의 평균 타임이 프레임 타임의 것 1/4 을 넘고 있다.
  • 필터가 적어도 1 프레임 늦어 실행되고 있다.
  • 다음의 키 프레임이 불과 1 프레임 먼저 있다고 예상된다.
  • 키 프레임이 충분한 빈도로 나타난다.

이 멤버 함수는, 샘플의 스킵이 시작 되면(자) EC_QUALITY_CHANGE 통지를 송신한다. 스킵이 시작 되면(자), 다음의 키 프레임이 올 때까지의 모든 샘플이 스킵 된다.

CVideoTransformFilter::StartStreaming

CVideoTransformFilter 클래스

CTransformFilter::StartStreaming 를 오버라이드(override) 해, 스트리밍 또는 flushing의 시작시에 품질 컨트롤 정보를 리셋 한다.

구문

virtual HRESULT StartStreaming(void);

반환값

NOERROR 를 돌려준다.

주의

이 멤버 함수는, 몇개의 품질 컨트롤 멤버 변수 (m_itrLate ,m_nKeyFramePeriod ,m_nFramesSinceKeyFrame ,m_bSkipping ,m_tDecodeStart )를 0 으로 설정한다. 이 멤버 함수는,m_itrAvgDecode 을 3000 으로 설정해,m_bQualityChanged 및 m_bSampleSkipped 를 FALSE 로 설정한다.


FOURCCMap 클래스

FOURCCMap 클래스의 계층

FOURCCMap 클래스는,GUID 미디어 서브 타입과 낡은 포맷의 FOURCC 32 비트 미디어 태그와의 사이의 변환을 제공한다. 오리지날의 Microsoft® Windows® 멀티미디어 API 에서는, 미디어 타입은 4 개의 8 비트 문자로부터 생성 된 32 비트값의 태그를 붙일 수 있고 있어,FOURCC 로 불리고 있었다. Microsoft DirectShow® 미디어 타입에서는, 서브 타입으로서 GUID 가 사용된다. 이것에는, 이러한 생성이 용이하다라고 말하는 1 개의 이유가 있다 (새로운 FOURCC 의 생성에는 Microsoft 에의 등록이 필요하다). FOURCC 는 일의이므로,FOURCC 를 나타내는 40 억개의 GUID 의 범위를 할당하는 것에 의해 1 대 1 의 관계가 가능했다. 이 범위는, 모두 이하의 포맷의 GUID 이다.

XXXXXXXX-0000-0010-8000-00AA00389B71

이 클래스는 GUID 와 FOURCC 와의 사이의 변환을 용이하게 한다. 이 클래스는, 호환성을 유지하는 목적에서만 제공된다. 모든 새로운 미디어 서브 타입은,FOURCC 를 매핑 하는 것이 아니라, Guidgen.exe 또는 같은 툴로 생성 한 GUID 로 나타내는 것이 추천 된다.

오브젝트는, 추가의 데이터 멤버를 가지지 않고 GUID 로부터 파생해,GUID 에 캐스트 할 수가 있다. 오브젝트는, 생성시에 FOURCC 에 건네줄 수가 있다. 디폴트의 constructor　 　 은,FOURCC 를 제로에 초기화한다.

GetFOURCC 및 SetFOURCC 메소드는,GUID 의 고정 부분이 FOURCC 범위에 대응할지 어떨지를 체크하지 않는다. 따라서,GUID 에의 포인터를 FOURCC 에의 포인터에 캐스트 해 FOURCC 필드를 설정 또는 취득하는 경우는,GUID 가 FOURCC 범위내에 들어가고 있는 것을 별개에 확인할 필요가 있다.

멤버 함수

FOURCCMap | FOURCCMap 오브젝트를 생성 한다.
GetFOURCC | FOURCCMap 오브젝트로부터 FOURCC 를 취득한다.
SetFOURCC | FOURCCMap 오브젝트의 FOURCC 부분을 설정한다.

FOURCCMap::FOURCCMap

FOURCCMap 클래스

FOURCCMap 오브젝트를 생성 한다. 낡은 포맷의 멀티미디어 포맷의 DWORD 타입과 새로운 포맷의 GUID 타입의 사이의 매핑을 제공한다.

구문

FOURCCMap( );

FOURCCMap(

  DWORD Fourcc

  );

FOURCCMap(

  const GUID *pguid

  );

파라미터

Fourcc
이전에 Microsoft 멀티미디어 타입으로서 사용되고 있던 DWORD 미디어 태그.
pguid
GUID (글로벌 유니크 식별자)에의 포인터.

반환값

반환값 없음.

주의

이 오브젝트가 FOURCC 코드를 사용해 생성 되는 경우, 거기에 대응하는 GUID 가 생성 된다. 이 오브젝트가 기존의 GUID 를 사용해 생성 되는 경우, 오브젝트의 FOURCC 값이 제로로 설정된다. 그 FOURCC 값은,SetFOURCC 또는 GetFOURCC 멤버 함수를 사용해 각각 설정 또는 취득할 수 있다.

FOURCCMap::GetFOURCC

FOURCCMap 클래스

FOURCCMap 오브젝트로부터 FOURCC DWORD 를 취득한다.

구문

DWORD GetFOURCC(void);

반환값

FOURCC DWORD 값을 돌려준다. FOURCC 로부터 파생하고 있지 않는 GUID 를 생성 했을 경우, 반환값은 기본적으로 랜덤이 된다.

FOURCCMap::SetFOURCC

FOURCCMap 클래스

FOURCCMap 오브젝트의 FOURCC 부분을 설정한다.

구문

void SetFOURCC(

  const GUID *pguid

  );

파라미터

pguid
FOURCCMap 오브젝트가 돌려주어진 GUID (글로벌 유니크 식별자) 부분에의 포인터.

반환값

반환값 없음.


유틸리티 함수

이 주제에는, Microsoft® DirectShow® 의 유틸리티 함수 및 매크로에 관한 설명이 포함되어 있다.

  • COM 헬퍼 함수
  • DLL 셋업 함수
  • 미디어 타입 함수
  • 그 외의 헬퍼 함수
  • 프로퍼티 페이지 헬퍼 함수
  • 캐릭터 라인 함수
  • 비디오 함수와 이미지 함수


COM 헬퍼 함수

선언 : Combase.h

DECLARE_IUNKNOWN | 새로운 인터페이스의 기본 인터페이스의 3 개의 메소드를 선언한다.
GetInterface | 요구된 클라이언트에의 인터페이스 포인터를 취득한다.
INonDelegatingUnknown | IUnknown 인터페이스의 비위임판.
LoadOLEAut32 | Automation DLL (OleAut32.dll)를 읽어들인다.

DECLARE_IUNKNOWN

COM 헬퍼 함수

새로운 인터페이스의 기본 인터페이스의 3 개의 메소드를 선언한다.

구문

#define DECLARE_IUNKNOWN                                        \
    STDMETHODIMP QueryInterface(REFIID riid, void **ppv) {      \
        return GetOwner()->QueryInterface(riid, ppv);            \
    };                                                          \
    STDMETHODIMP_(ULONG) AddRef() {                             \
        return GetOwner()->AddRef();                            \
    };                                                          \
    STDMETHODIMP_(ULONG) Release() {                            \
        return GetOwner()->Release();                           \
    };

주의

새로운 인터페이스를 생성 할 때는,IUnknown 로부터 파생해야 한다. 이것에는,QueryInterface ,AddRef , 및 Release 의 3 개의 메소드가 있다. 이 매크로는, 새로운 인터페이스용으로 이러한 각 메소드를 선언해, 선언 프로세스를 간략화한다.

GetInterface

COM 헬퍼 함수

인터페이스 포인터를 취득한다.

구문

HRESULT GetInterface(
    LPUNKNOWN pUnk,
    void **ppv
);

파라미터

pUnk
IUnknown 인터페이스에의 포인터.
ppv
취득된 인터페이스에의 포인터의 주소.

반환값

HRESULT 값을 돌려준다.

주의

이 멤버 함수는, 참조 카운트의 thread 세이프 인크리먼트(increment)를 실행한다. 인터페이스를 취득해, 참조를 추가하려면 ,INonDelegatingUnknown::NonDelegatingQueryInterface 메소드에 오버라이드(override) 하는 이행으로부터, 이 함수를 호출하는 것.

INonDelegatingUnknown

COM 헬퍼 함수

같은 COM 오브젝트의 비위임 및 위임 IUnknown 인터페이스의 양쪽 모두를 지원 하는 클래스를 유효하게 하기 위해서, 이름을 변경한 IUnknown 의 판. 이 인터페이스는, vtable 순서에 다음의 3 개의 메소드를 지원 하고 있다.

구문

interface INonDelegatingUnknown
{
    virtual HRESULT NonDelegatingQueryInterface) (REFIID riid, LPVOID *ppv) PURE;
    virtual ULONG NonDelegatingAddRef)(void) PURE;
    virtual ULONG NonDelegatingRelease)(void) PURE;
};

주의

복수의 계승에 대해서 INonDelegatingUnknown 를 사용하려면 , 다음의 스텝을 실행한다.

  1. 인터페이스 (IMyInterface 등)로부터 클래스를 파생한다.
  2. 클래스 정의에 DECLARE_IUNKNOWN 를 인클루드 해, 외부 unknown 를 호출하는 QueryInterface,AddRef, 및 Release 의 이행을 선언한다.
  3. NonDelegatingQueryInterface 에 오버라이드(override) 해, 다음과 같은 코드를 사용해 IMyInterface 를 공개한다.
         if (riid == IID_IMyInterface) {
         return GetInterface((IMyInterface *) this, ppv);
     } else {
         return CUnknown::NonDelegatingQueryInterface(riid, ppv);
     }
  4. MyInterface 의 멤버 함수를 선언해, 이행 한다.

네스트 한 인터페이스로 INonDelegatingUnknown 를 사용하려면 , 다음의 스텝을 실행한다.

  1. CUnknown 로부터 파생한 클래스를 선언한다.
  2. 클래스 정의에 DECLARE_IUNKNOWN 를 인클루드 한다.
  3. NonDelegatingQueryInterface 를 오버라이드(override) 해, 다음과 같은 코드를 사용해 IMyInterface 를 공개한다.
         if (riid == IID_IMyInterface) {
         return GetInterface((IMyInterface *) this, ppv);
     } else {
         return CUnknown::NonDelegatingQueryInterface(riid, ppv);
     }
  4. IMyInterface 의 멤버 함수를 이행 한다. CUnknown::GetOwner 를 사용해, COM 오브젝트 클래스에 액세스 한다.
  5. COM 오브젝트 클래스에서, 네스트 한 클래스를 COM 오브젝트 클래스의 프렌드로 해, 네스트 한 클래스의 인스턴스를 COM 오브젝트 클래스의 멤버로서 선언한다.

    외부 unknown 와 HRESULT 는 반드시 CUnknown constructor　 　 에 건네주지 않으면 안 되기 때문에, 디폴트의 constructor　 　 은 사용할 수 없다. 멤버 변수를 클래스에의 포인터로 해, constructor　 　 으로 새로운 호출을 실시해, 실제로 생성 할 필요가 있다.

  6. 다음과 같은 코드를 사용해,NonDelegatingQueryInterface 를 오버라이드(override) 한다.

     if (riid == IID_IMyInterface) {
         return m_pImplFilter->
            NonDelegatingQueryInterface(IID_IMyInterface, ppv);
     } else {
         return CUnknown::NonDelegatingQueryInterface(riid, ppv);
     }

복수의 계승 및 네스트 한 클래스에 의해, 일부의 인터페이스를 지원 하는 혼합 클래스를 가질 수가 있다.

LoadOLEAut32

COM 헬퍼 함수

Automation 동적 링크 라이브러리 (OleAut32.dll)를 읽어들인다.

구문

HINSTANCE LoadOLEAut32( );

반환값

Automation DLL 인스턴스에의 핸들을 돌려준다.

주의

CBaseObject 소멸자가 OleAut32.dll 를 읽어들인 오브젝트를 파괴할 때에, 라이브러리가 읽히고 있으면(자), 그 라이브러리는 언로드된다.


DLL 셋업 함수

선언 : Dllsetup.h

AMovieDllRegisterServer | 사용하지 않는다.
AMovieDllRegisterServer2 | 필터를 등록 및 등록 해제한다.
AMovieDllUnregisterServer | 사용하지 않는다.
AMovieSetupRegisterFilter | 사용하지 않는다.
AMovieSetupRegisterFilter2 | 필터의 메리트, 핀, 및 미디어 타입을 등록한다.

AMovieDllRegisterServer

DLL 셋업 함수

사용하지 않는다. 대신에 AMovieDllRegisterServer2 를 사용한다.

구문

HRESULT AMovieDllRegisterServer(void);

AMovieDllRegisterServer2

DLL 셋업 함수

필터를 등록 및 등록 해제한다.

구문

HRESULT AMovieDllRegisterServer2(
    BOOL bRegister
);

파라미터

bRegister
TRUE 는 필터를 등록하는 것을 나타내, FALSE 는 필터의 등록을 해제하는 것을 나타낸다.

반환값

성공했을 경우는 HRESULT 값 NOERROR 를 돌려준다. 그 이외의 경우는 에러 코드를 돌려준다.

주의

이 함수는 필터를 설정하기 위해서 사용한다. 상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」 및 SDK 에 포함되는 샘플 필터를 참조할것.

주 : 필터 등록 프로세스에서는, 카테고리별에 의한 필터의 등록이 가능하게 되어 있다. 예를 들어, 캡춰 필터와압축 필터를 각각 대응하는 카테고리에 정리해 열거할 수가 있다. 이하의 함수는, 필터의 카테고리별의 등록 및 등록 해제가 어떻게 행해지는지를 나타낸다. 이하의 함수에서는,IFilterMapper2 인터페이스를 사용하고 있다.

static const WCHAR *g_wszName = L"Sample Compressor Filter" ;

// 샘플 압력 필터를 등록한다.
STDAPI
DllRegisterServer( void )
{

    // 서버를 등록한다.
    HRESULT hr = AMovieDllRegisterServer2( TRUE );
    if( FAILED(hr) )
        return hr;

    IFilterMapper2 *pFm2 = 0;

    hr = CoCreateInstance( CLSID_FilterMapper2
                           , NULL
                           , CLSCTX_INPROC_SERVER
                           , IID_IFilterMapper2
                           , (void **) &pFm2 );

    if(FAILED(hr))
        return hr;

    static const AMOVIESETUP_MEDIATYPE sudAVICoTypeOut =  {
        &MEDIATYPE_Video,
        &MEDIASUBTYPE_SampleVideoType };

    static const AMOVIESETUP_MEDIATYPE sudAVICoTypeIn =  {
        &MEDIATYPE_Video,
        &GUID_NULL };

    static const AMOVIESETUP_PIN psudAVICoPins[] =
    {
        {
            L"Input"        // strName
            , FALSE         // bRendered
            , FALSE         // bOutput
            , FALSE         // bZero
            , FALSE         // bMany
            , &CLSID_NULL   // clsConnectsToFilter
            , 0             // strConnectsToPin
            , 1             // nTypes
            , &sudAVICoTypeIn } // lpTypes
        , { L"Output"       // strName
            , FALSE         // bRendered
            , TRUE          // bOutput
            , FALSE         // bZero
            , FALSE         // bMany
            , &CLSID_NULL   // clsConnectsToFilter
            , 0             // strConnectsToPin
            , 1             // nTypes
            , &sudAVICoTypeOut
        }
    };   // lpTypes

    REGFILTER2 rf2;
    rf2.dwVersion = 1;
    rf2.dwMerit = MERIT_DO_NOT_USE;
    rf2.cPins = NUMELMS(psudAVICoPins);
    rf2.rgPins = psudAVICoPins;

    hr = pFm2->RegisterFilter(
        CLSID_SampleCompressorFilter,
        g_wszName,              // 유저에게 표시하는 이름
        0,                      // 데바이스모니카
        &CLSID_VideoCompressorCategory,
        g_wszName,              // 일의인 인스턴스명
        &rf2);

    pFm2->Release();

    return hr;

}

// 샘플 압력 필터의 등록을 해제한다.
STDAPI
DllUnregisterServer( void )
{

    HRESULT hr = AMovieDllRegisterServer2( FALSE );
    if( FAILED(hr) )
        return hr;

    IFilterMapper2 *pFm2 = 0;

    hr = CoCreateInstance( CLSID_FilterMapper2
                           , NULL
                           , CLSCTX_INPROC_SERVER
                           , IID_IFilterMapper2
                           , (void **) &pFm2       );

    if(FAILED(hr))
        return hr;

    hr = pFm2->UnregisterFilter(
        &CLSID_VideoCompressorCategory,
        g_wszName,
        CLSID_SampleCompressorFilter);

    pFm2->Release();

    return hr;
}

AMovieDllUnregisterServer

DLL 셋업 함수

사용하지 않는다. 대신에 AMovieDllRegisterServer2 를 사용한다.

구문

HRESULT AMovieDllUnregisterServer(void);

AMovieSetupRegisterFilter

DLL 셋업 함수

사용하지 않는다. 대신에 AMovieSetupRegisterFilter2 를 사용한다.

구문

HRESULT AMovieSetupRegisterFilter(
    const AMOVIESETUP_FILTER const *psetupdata,
    IFilterMapper *pIFM,
    BOOL bRegister
);

AMovieSetupRegisterFilter2

DLL 셋업 함수

IFilterMapper2 를 사용해, 필터의 메리트, 핀, 및 미디어 타입을 레지스트리에 등록한다.

구문

HRESULT AMovieSetupRegisterFilter2(
    const AMOVIESETUP_FILTER const *psetupdata,
    IFilterMapper2 *pIFM2,
    BOOL bRegister
);

파라미터

psetupdata
AMOVIESETUP_FILTER 데이터에의 포인터.
pIFM
IFilterMapper2 인터페이스에의 포인터.
bRegister
필터를 등록할지 어떨지를 나타내는 값. TRUE 는 필터를 등록하는 것을 나타내, FALSE 는 필터의 등록을 해제하는 것을 나타낸다.

반환값

성공했을 경우는 HRESULT 값 NOERROR 를 돌려준다. 그 이외의 경우는 에러 코드를 돌려준다.

주의

AMovieDllRegisterServer2 는, COM 서버가 등록된 후에, 이 헬퍼 함수를 사용해 필터를 등록한다.

보통, 필터는 AMovieDllRegisterServer2 를 사용해, 이 함수는 직접 호출하지 않는다.


미디어 타입 함수

선언 : Mtype.h

Microsoft® DirectShow® base class의 Mtype.h 헤더 파일은, 미디어 타입을 처리하기 위한 헬퍼 함수를 제공한다. 이러한 범용 함수는, 태스크 할당 AM_MEDIA_TYPE 구조체를, 생성, 카피, 및 삭제한다. 이러한 함수는,IEnumMediaTypes 인터페이스를 사용하는 경우에 편리하다. 왜냐하면, 다음에 삭제해야 하는 구조체를 이행에 의해 할당할 수 있기 때문이다.

함수는 다음과 같이 대가 되어 있다.

  • CreateMediaType 는 DeleteMediaType 와 역의 동작을 실시한다.
  • FreeMediaType 는 CopyMediaType 와 역의 동작을 실시한다.
AreEqualVideoTypes | 2 개의 비디오 소스의 포맷, 높이, 및 폭을 비교한다.
CopyMediaType | 태스크 할당 AM_MEDIA_TYPE 구조체를 카피한다.
CreateAudioMediaType | 웨이브 포맷 구조체가 지정된 미디어 타입 구조체를 초기화한다.
CreateMediaType | AM_MEDIA_TYPE 구조체의 할당과 초기화를 실시한다.
DeleteMediaType | 태스크 할당 AM_MEDIA_TYPE 구조체를 삭제한다.
FreeMediaType | 태스크 할당 AM_MEDIA_TYPE 구조체를 메모리로부터 해방한다.

AreEqualVideoTypes

미디어 타입 함수

2 개의 미디어 타입의 비디오 포맷, 폭, 및 높이가 같은가 어떤가를 판정한다.

구문

BOOL WINAPI AreEqualVideoTypes (
    CMediaType *pmt1,
    CMediaType *pmt2
    );

파라미터

pmt1
비교하는 1 번째의 미디어 타입에의 포인터.
pmt2
비교하는 2 번째의 미디어 타입에의 포인터.

반환값

pmt1 와 pmt2 의 비디오 포맷, 폭, 및 높이가 같은 경우는 TRUE 를 돌려주어, 그 이외의 경우는 FALSE 를 돌려준다.

CopyMediaType

미디어 타입 함수

태스크 할당 AM_MEDIA_TYPE 구조체를 카피한다.

구문

void WINAPI CopyMediaType(
    AM_MEDIA_TYPE *pmtTarget,
    const AM_MEDIA_TYPE *pmtSource
    );

파라미터

pmtTarget
구조체의 새로운 카피를 배치하는 메모리 영역에의 포인터.
pmtSource
카피하는 소스 구조체에의 포인터.

반환값

반환값 없음.

주의

구조체의 처리가 끝나면(자),FreeMediaType 를 호출해 pmtTarget 구조 체내의 리소스를 해방하는 것.

CreateAudioMediaType

미디어 타입 함수

웨이브 포맷 구조체가 지정된 미디어 타입 구조체를 초기화한다.

구문

STDAPI CreateAudioMediaType(
    const WAVEFORMATEX *pwfx,
    AM_MEDIA_TYPE *pmt,
    BOOL bSetFormat
    );

파라미터

pwfx
제공된 WAVEFORMATEX 구조체에의 포인터.
pmt
초기화하는 AM_MEDIA_TYPE 구조체에의 포인터.
bSetFormat
AM_MEDIA_TYPE 구조체의 포맷 섹션, 즉,cbFormat 및 pbFormat 멤버를 초기화할지 어떨지를 나타내는 플래그. 포맷 섹션을 초기화하려면 TRUE 를, 그 이외의 경우는 FALSE 를 지정한다.

반환값

포맷 데이터의 메모리를 할당할 수 없었던 경우는 E_OUTOFMEMORY 를 돌려주어, 그 이외의 경우는 S_OK 를 돌려준다.

CreateMediaType

미디어 타입 함수

태스크 할당 AM_MEDIA_TYPE 구조체를 생성 한다.

구문

AM_MEDIA_TYPE * WINAPI CreateMediaType(
    AM_MEDIA_TYPE const *pSrc
    );

파라미터

pSrc
AM_MEDIA_TYPE 소스 구조체에의 포인터.

반환값

새로운 AM_MEDIA_TYPE 구조체를 돌려준다. 에러가 발생했을 경우는, NULL 를 돌려준다.

주의

구조체의 처리가 끝나면(자),DeleteMediaType 를 호출해, 이 루틴에 의해 할당할 수 있었던 구조체 및 리소스를 해방하는 것.

DeleteMediaType

미디어 타입 함수

태스크 할당 AM_MEDIA_TYPE 구조체를 삭제한다.

구문

void WINAPI DeleteMediaType(
    AM_MEDIA_TYPE *pmt
    );

파라미터

pmt
AM_MEDIA_TYPE 구조체에의 포인터.

반환값

반환값 없음.

주의

구조체는,CreateMediaType 호출에 의해 생성되어 있지 않으면 안 된다.

FreeMediaType

미디어 타입 함수

태스크 할당 AM_MEDIA_TYPE 구조체를 메모리로부터 해방한다.

구문

void WINAPI FreeMediaType(
    AM_MEDIA_TYPE& mt
    );

파라미터

mt
구조체에의 포인터.

반환값

반환값 없음.

주의

구조체는,CopyMediaType 호출에 의해 초기화되어 있지 않으면 안 된다.


그 외의 헬퍼 함수

선언 : Wxutil.h

EqualPins | 같은 오브젝트상에 2 개의 핀이 있을지 어떨지를 확인한다.
Int64x32Div32 | a 의 64 비트값에 ((a*b) +rnd) /c 를 이행 한다.
IsEqualObject | 같은 오브젝트상에 2 개의 인터페이스가 있을지 어떨지를 확인한다.
llMulDiv | a 의 32 비트값에 ((a*b) +rnd) /c 를 이행 한다.
WaitDispatchingMessages | 윈도우 메세지를 디스팟치중에, 오브젝트가 통지제가 될 때까지 기다린다.

EqualPins

그 외의 헬퍼 함수

같은 오브젝트상에 2 개의 핀이 있을지 어떨지를 확인한다.

구문

BOOL EqualPins(
    IUnknown *pPin1,
    IUnknown *pPin2
);

파라미터

pPin1
1 개의 핀에의 포인터.
pPin2
이제(벌써) 1 개의 핀에의 포인터.

반환값

같은 오브젝트상에 양쪽 모두의 핀이 있는 경우는 TRUE 를 돌려주어, 없는 경우는 FALSE 를 돌려준다.

Int64x32Div32

그 외의 헬퍼 함수

a 에 b 를 걸어 96 비트의 결과에 rnd 를 더해,c 로 나눈다.

구문

LONGLONG WINAPI Int64x32Div32(
  LONGLONG a,
  LONG b,
  LONG c,
  LONG rnd
  );

반환값

(a * b + rnd) /c 계산, 또는 다음의 값을 돌려준다.

0x7FFFFFFFFFFFFFFF | 결과가 매우 큰 (정) 모아 두어 오버플로우가 발생했다.
0x8000000000000000 | 결과가 매우 큰 (부) 모아 두어 오버플로우가 발생했다.

주의

나눗셈의 둥근은, 제로로 한다. 제로의 나눗셈은, 오버플로우 상태로서 다루어진다.

IsEqualObject

그 외의 헬퍼 함수

같은 오브젝트상에 2 개의 인터페이스가 있을지 어떨지를 확인한다.

구문

BOOL WINAPI IsEqualObject(
    IUnknown *pFirst,
    IUnknown *pSecond
);

파라미터

pFirst
1 개의 인터페이스에의 포인터.
pSecond
이제(벌써) 1 개의 인터페이스에의 포인터.

반환값

같은 오브젝트상에 양쪽 모두의 인터페이스가 있는 경우는 TRUE 를 돌려주어, 없는 경우는 FALSE 를 돌려준다.

llMulDiv

그 외의 헬퍼 함수

a 에 b 를 걸어 128 비트의 결과에 rnd 를 더해,c 로 나눈다.

구문

LONGLONG WINAPI llMulDiv(
  LONGLONG a,
  LONGLONG b,
  LONGLONG c,
  LONGLONG rnd
  );

반환값

(a * b + rnd) /c 계산, 또는 다음의 값을 돌려준다.

0x7FFFFFFFFFFFFFFF | 결과가 매우 큰 (정) 모아 두어 오버플로우가 발생했다.
0x8000000000000000 | 결과가 매우 큰 (부) 모아 두어 오버플로우가 발생했다.

주의

나눗셈의 둥근은, 제로로 한다. 제로의 나눗셈은, 오버플로우 상태로서 다루어진다.

WaitDispatchingMessages

그 외의 헬퍼 함수

윈도우 메세지를 디스팟치중에, 오브젝트가 통지제가 될 때까지 기다린다.

구문

DWORD WINAPI WaitDispatchingMessages(
    HANDLE hObject,
    DWORD dwWait,
    HWND hwnd = NULL,
    UINT uMsg = 0
    HANDLE hEvent = NULL;
);

파라미터

hObject
대기하는 오브젝트의 핸들.
dwWait
타임 아웃의 간격 (밀리 세컨드 단위).
hwnd
윈도우에의 옵션 핸들.
uMsg
옵션의 윈도우 메세지. 디스팟치 하는 메세지를 지정한다.
hEvent
대기하는 이벤트에의 옵션 핸들.

반환값

WaitForMultipleObjects 함수로부터의 값을 돌려준다.

주의

오브젝트가 윈도우를 소유하고 있는 경우, 대기중에 윈도우 메세지를 디스팟치 할 필요가 있다. 이 함수에 의해, 오브젝트는 메세지의 디스팟치중에, 이벤트, semaphore, 또는 다른 상호 배타 오브젝트를 기다릴 수가 있다.


프로퍼티 페이지 헬퍼 함수

Microsoft® DirectShow® base class의 Videoctl.h 헤더 파일은, 프로퍼티 페이지의 이행에 도움이 되는 함수를 제공한다.

GetDialogSize | 리소스 다이알로그 박스의 사이즈를 화면 픽셀 단위로 취득한다.
StringFromResource | 지정된 리소스 식별자를 가지는 리소스 파일로부터 캐릭터 라인을 로드한다.
WideStringFromResource | 지정된 리소스 식별자를 가지는 리소스 파일로부터 Unicode™ 캐릭터 라인을 로드한다.

GetDialogSize

프로퍼티 페이지 헬퍼 함수

리소스 다이알로그 박스의 사이즈를 취득한다.

구문

BOOL WINAPI GetDialogSize(
    int iResourceID,
    DLGPROC pDlgProc,
    LPARAM lParam,
    SIZE *pResult
);

파라미터

iResourceID
다이알로그 박스 리소스 식별자.
pDlgProc
다이알로그 박스 프로시저에의 포인터.
lParam
일시 다이알로그 박스가 생성 된 직후에 그 일시 다이알로그 박스에 송신되는 WM_INITDIALOG 메세지로 건네받는 값.
pResult
다이알로그 박스의 치수 (화면 픽셀 단위)를 받는 SIZE 구조체에의 포인터.

반환값

다이알로그 박스 리소스가 검출되었을 경우는 TRUE 를 돌려주어, 그 이외의 경우는 FALSE 를 돌려준다.

주의

이 함수를 사용해, 프로퍼티 페이지는 필요한 실제의 표시 사이즈를 돌려줄 수가 있다. 대부분의 프로퍼티 페이지는 다이알로그 박스로, 리소스 파일에 저장 된 다이알로그 박스 템플릿을 가진다. 템플릿은, 화면 픽셀에 직접 매핑 되지 않는 다이알로그 박스 단위를 사용한다. 다만, 프로퍼티 페이지의 GetPageInfo 함수는 실제의 표시 사이즈를 픽셀 단위로 돌려주지 않으면 안 된다. 프로퍼티 페이지는,GetDialogSize 를 호출해 표시 사이즈를 계산할 수가 있다.

이 함수는, 다이알로그 박스의 일시 인스턴스를 생성 한다. 다이알로그 박스가 화면에 표시되지 않게 하기 위해서는, 리소스 파일내의 다이알로그 박스 템플릿에 WS_VISIBLE 프로퍼티가 설정되어 있어서는 안 된다.

StringFromResource

프로퍼티 페이지 헬퍼 함수

지정된 리소스 식별자를 가지는 리소스 파일로부터 캐릭터 라인을 로드한다.

구문

TCHAR * WINAPI StringFromResource(
    TCHAR *pBuffer,
    int iResourceID
);

파라미터

pBuffer
iResourceID 에 대응하는 캐릭터 라인에의 포인터.
iResourceID
취득하는 캐릭터 라인의 리소스 식별자.

반환값

pBuffer 와 같은 캐릭터 라인을 돌려준다. 함수가 성공하지 않았던 경우는 NULL 캐릭터 라인을 돌려준다.

주의

pBuffer 버퍼는, STR_MAX_LENGTH 바이트 이상이 아니면 안된다.

WideStringFromResource

프로퍼티 페이지 헬퍼 함수

지정된 리소스 식별자를 가지는 리소스 파일로부터 Unicode™ 캐릭터 라인을 로드한다.

구문

WCHAR * WINAPI WideStringFromResource(
    WCHAR *pBuffer,
    int iResourceID
);

파라미터

pBuffer
iResourceID 에 대응하는 캐릭터 라인에의 포인터.
iResourceID
취득하는 캐릭터 라인의 리소스 식별자.

반환값

pBuffer 와 같은 캐릭터 라인을 돌려준다. 함수가 성공하지 않았던 경우는 NULL 캐릭터 라인을 돌려준다.

주의

보통, 프로퍼티 페이지는, 바이너리의 생성 방법으로 관계없이 Unicode™ 캐릭터 라인을 사용하는 COM 인터페이스를 개입시켜 불려 간다. 이 함수를 사용 하면, 리소스의 캐릭터 라인을 Unicode 캐릭터 라인으로 변환할 수가 있다. 이 함수는, 리소스를 로드해, 그것이 Unicode 가 아닌 경우에 Unicode 캐릭터 라인으로 변환한다.


캐릭터 라인 함수

선언 : Wxutil.h

AMGetWideString | 기존의 비와이드 캐릭터 라인의 와이드 캐릭터 라인 버젼을 할당 및 생성 한다.
atoi | 캐릭터 라인을 정수로 변환한다.
FreeBSTR | 태스크가 할당한 BSTR 캐릭터 라인을 해방한다.
IntToWstr | 정수를 와이드 캐릭터 라인으로 변환한다.
lstrcmpiW | 대문자/소문자를 무시해 2 개의 와이드 캐릭터 라인을 비교한다.
lstrcmpW | 2 개의 와이드 캐릭터 라인을 비교한다.
lstrcpynW | 와이드 캐릭터 라인을 최대장까지 카피한다.
lstrcpyW | 와이드 캐릭터 라인을 카피한다.
lstrlenW | 와이드 문자에서의 와이드 캐릭터 라인의 길이를 취득한다.
WriteBSTR | 태스크가 할당한 메모리를 할당해 와이드 캐릭터 라인을 메모리에 카피해, 태스크가 할당한 BSTR 캐릭터 라인을 생성 한다.
WstrToInt | 와이드 캐릭터 라인을 정수로 변환한다.

AMGetWideString

캐릭터 라인 함수

기존의 비 Unicode™ 캐릭터 라인의 Unicode 버젼을 할당 및 생성 한다.

구문

STDAPI AMGetWideString(
    LPCWSTR pszString,
    LPWSTR *ppszReturn
    );

파라미터

pszString
비 Unicode 소스 캐릭터 라인에의 포인터.
ppszReturn
pszString 를 저장 하는 Unicode™ 캐릭터 라인에의 포인터의 주소.

반환값

성공했을 경우는 S_OK 를 돌려준다. ppszReturn 가 NULL 의 경우는 E_POINTER 를, 이용 가능한 메모리가 부족한 경우는 E_OUTOFMEMORY 를 돌려준다.

atoi

캐릭터 라인 함수

캐릭터 라인을 정수로 변환한다.

구문

int WINAPI atoi(
    const TCHAR *sz
    );

파라미터

sz
소스 캐릭터 라인에의 포인터.

반환값

캐릭터 라인의 정수값을 돌려준다.

주의

이 판의 atoi 는, 10 진수만을 지원 해, 선두에 있는 스페이스 또는 기호는 허가되지 않는다. Unicode™ 캐릭터 라인과 ANSI 캐릭터 라인의 양쪽 모두를 지원 한다. 다른 판에서는 다른 일이 있다.

FreeBSTR

캐릭터 라인 함수

태스크가 할당한 BSTR 캐릭터 라인을 메모리로부터 해방한다

구문

STDAPI FreeBSTR(
    BSTR *pstr
    );

파라미터

pstr
해방하는 BSTR 에의 포인터.

반환값

성공의 경우는 S_OK 를 돌려주어,pstr 가 NULL 의 경우는 S_FALSE 를 돌려준다.

주의

메모리는,CoTaskMemAlloc 를 호출하는 것에 의해, 인터페이스에 걸친 오브젝트간의 수수를 위해서(때문에) 할당할 수 있다. 또,CoTaskMemFree 의 호출에 의해 해방된다. 집중 메모리 allocater를 사용하면(자), 다른 프로그램 언어로 생성 된 오브젝트간으로, 메모리의 할당, 주고 받아, 및 해방을 안전하게 실시할 수가 있다.

IntToWstr

캐릭터 라인 함수

정수값을 와이드 캐릭터 라인으로 변환한다.

구문

void IntToWstr(
    int i,
    LPWSTR wstrDest
    );

파라미터

i
변환하는 정수값.
wstrDest
변환된 캐릭터 라인이 포함되는 와이드 캐릭터 라인에의 포인터.

반환값

반환값은 없다.

lstrcmpiW

캐릭터 라인 함수

2 개의 와이드 캐릭터 라인을 비교한다. 대문자와/소문자는 구별되지 않는다.

구문

int lstrcmpiW(
    LPCWSTR lpszString1,
    LPCWSTR lpszString2
    );

파라미터

lpszString1
비교 대상의 NULL 로 종료하는 1 번째의 와이드 캐릭터 라인에의 포인터.
lpszString2
비교 대상의 NULL 로 종료하는 2 번째의 와이드 캐릭터 라인에의 포인터.

반환값

함수가 성공했을 경우, 및 lpszString1 에 의해 나타나는 캐릭터 라인이 lpszString2 에 의해 나타나는 캐릭터 라인보다 작은 경우는, 부의 값을 돌려준다. lpszString1 에 의해 나타나는 캐릭터 라인이 lpszString2 에 의해 나타나는 캐릭터 라인보다 큰 경우는, 정의 값을 돌려준다. 2 개의 캐릭터 라인이 동일한 경우는 제로를 돌려준다.

주의

lstrcmpiW 함수는, 2 개의 와이드 캐릭터 라인의 같은 위치에 있는 문자 끼리 (예를 들어 1번째의 문자, 2 번째의 문자,...)(을)를 불일치가 검출되든가 또는 캐릭터 라인의 끝나에 도달할 때까지 조합해 비교한다.

이 함수는, 최초로 검출한 불일치 문자의 값의 차이를 돌려준다. 예를 들어 lstrcmpiW 는 L"abcz" 를 L"abcdefg" 보다 크다고 판단해, L'z'와 L'd'의 차이를 돌려준다.

언어 (로케일)는 항상 영어로서 다루어진다.

lstrcmpW

캐릭터 라인 함수

2 개의 와이드 캐릭터 라인을 비교한다. 대문자와 소문자가 구별된다.

구문

int lstrcmpW(
    LPCWSTR lpszString1,
    LPCWSTR lpszString2
    );

파라미터

lpszString1
비교 대상의 NULL 로 종료하는 1 번째의 와이드 캐릭터 라인에의 포인터.
lpszString2
비교 대상의 NULL 로 종료하는 2 번째의 와이드 캐릭터 라인에의 포인터.

반환값

함수가 성공했을 경우, 및 lpszString1 에 의해 나타나는 캐릭터 라인이 lpszString2 에 의해 나타나는 캐릭터 라인보다 작은 경우는, 부의 값을 돌려준다. lpszString1 에 의해 나타나는 캐릭터 라인이 lpszString2 에 의해 나타나는 캐릭터 라인보다 큰 경우는, 정의 값을 돌려준다. 2 개의 캐릭터 라인이 동일한 경우는 제로를 돌려준다.

주의

lstrcmpW 함수는, 2 개의 와이드 캐릭터 라인의 같은 위치에 있는 문자 끼리 (예를 들어 1번째의 문자, 2 번째의 문자,...)(을)를 불일치가 검출되든가 또는 캐릭터 라인의 끝나에 도달할 때까지 조합해 비교한다.

이 함수는, 최초로 검출한 불일치 문자의 값의 차이를 돌려준다. 예를 들어 lstrcmpW 는 L"abcz" 를 L"abcdefg" 보다 크다고 판단해, L'z'와 L'd'의 차이를 돌려준다.

언어 (로케일)는 항상 영어로서 다루어진다.

lstrcpyW

캐릭터 라인 함수

와이드 캐릭터 라인을 버퍼에 카피한다.

구문

LPWSTR lstrcpyW(
    LPWSTR lpszString1,
    LPCWSTR lpszString2
    );

파라미터

lpszString1
lpszString2 파라미터에 의해 지시해지는 캐릭터 라인의 내용을 받는 버퍼에의 포인터. 버퍼는, 종단의 와이드 NULL 문자를 포함한 캐릭터 라인을 저장 하는데 충분한 크기를 가지지 않으면 안 된다.
lpszString2
카피 대상의 NULL 로 종료하는 와이드 캐릭터 라인에의 포인터.

반환값

버퍼에의 포인터를 돌려준다.

lstrcpynW

캐릭터 라인 함수

지정된 와이드 문자수까지의 와이드 캐릭터 라인을 버퍼에 카피한다.

구문

LPWSTR lstrcpynW(
    LPWSTR lpszString1,
    LPCWSTR lpszString2,
    int iMaxLength
    );

파라미터

lpszString1
lpszString2 에 의해 지시해지는 캐릭터 라인의 내용을 받는 버퍼에의 포인터. 버퍼는, 종단의 와이드 NULL 문자를 포함한 캐릭터 라인을 저장 하는데 충분한 크기를 가지지 않으면 안 된다.
lpszString2
카피 대상의 NULL 로 종료하는 와이드 캐릭터 라인에의 포인터.
iMaxLength
종단 NULL 문자를 포함한, 카피하는 와이드 문자의 최대수.

반환값

버퍼에의 포인터를 돌려준다.

주의

iMaxLength 가 제로 이외의 값의 경우,lstrcpynW 는 반드시 카피처의 캐릭터 라인에 종단 NULL 와이드 문자를 삽입한다. 이것에 의해, 소스 캐릭터 라인을 잘라 버릴 수 있는 일이 있다.

lstrlenW

캐릭터 라인 함수

지정된 와이드 캐릭터 라인의 길이를 취득한다.

구문

int lstrlenW(
    LPCWSTR lpszString
    );

파라미터

lpszString
NULL 로 종료하는 와이드 캐릭터 라인에의 포인터.

반환값

함수가 성공했을 경우, 반환값은 캐릭터 라인의 와이드 문자에서의 길이를 나타낸다.

WriteBSTR

캐릭터 라인 함수

태스크가 할당한 BSTR 캐릭터 라인의 할당과 매입을 실시한다.

구문

STDAPI WriteBSTR(
    BSTR *pstrDest,
    LPCWSTR szSrc
    );

파라미터

pstrDest
할당할 수 있었던 BSTR 의 저장처에의 포인터.
szSrc
새롭게 할당할 수 있었던 BSTR 캐릭터 라인에 카피되는 와이드 (Unicode™) 캐릭터 라인에의 포인터.

반환값

HRESULT 값을 돌려준다.

주의

메모리는,CoTaskMemAlloc 를 호출하는 것에 의해, 인터페이스에 걸친 오브젝트간의 수수를 위해서(때문에) 할당할 수 있다. 또,CoTaskMemFree 의 호출에 의해 해방된다. 집중 메모리 allocater를 사용하면(자), 다른 프로그램 언어로 생성 된 오브젝트간으로, 메모리의 할당, 주고 받아, 및 해방을 안전하게 실시할 수가 있다.

WstrToInt

캐릭터 라인 함수

와이드 캐릭터 라인을 정수로 변환한다.

구문

int WstrToInt(
    LPCWSTR wstrSrc
    );

파라미터

wstrSrc
소스의 와이드 캐릭터 라인에의 포인터.

반환값

캐릭터 라인의 정수값을 돌려준다.


비디오 함수와 이미지 함수

선언 : Wxutil.h

Microsoft® DirectShow® base class의 Wxutil.h 헤더 파일은,VIDEOINFOHEADER 구조체와 BITMAPINFO 구조체와의 사이에 변환을 실시하는데 도움이 되는 함수 및 매크로를 제공한다.

BIT_MASKS_MATCH | 2 개의 비디오 이미지의 마스크를 비교한다.
BITMASKS | 지정된 VIDEOINFOHEADER 구조체의 비트 마스크의 배열에의 포인터를 취득한다.
COLORS | 지정된 VIDEOINFOHEADER 구조체의 칼라 팔레트를 기술하는 RGBQUAD 에의 포인터를 취득한다.
ContainsPalette | 비디오 이미지에 칼라 팔레트가 포함되어 있는지 어떤지를 체크한다.
ConvertVideoInfoToVideoInfo2 | VIDEOINFO 스트림 포맷을 VIDEOINFOHEADER2 포맷으로 변환한다.
DIBSIZE | 지정된 비트 맵의 바이트 사이즈를 계산한다.
GetBitCount | 픽셀 근처의 비트수를 조사한다.
GetBitmapFormatSize | VIDEOINFOHEADER 구조체와 그 관련 데이터를 생성 하는데 필요한 사이즈 (바이트 단위)를 조사한다.
GetBitmapPalette | VIDEOINFOHEADER 구조체의 최초의 팔레트 엔트리를 취득한다.
GetBitmapSize | 이미지를 보관 유지하는데 필요한 사이즈 (바이트 단위)를 조사한다.
GetBitmapSubtype | 임의의 비트 맵 정보 헤더 구조체의 GUID 서브 타입을 조사한다.
GetSubtypeName | 임의의 GUID 서브 타입의 (디버그) 이름을 조사한다.
GetTrueColorType | 임의의 비트 맵 헤더의 GUID 서브 타입을 조사한다.
HEADER | 지정된 비디오 이미지로부터 이미지 데이터에의 포인터를 취득한다.
MPEG1_SEQUENCE_INFO | 지정된 MPEG-1 비디오 이미지의 순서 헤더를 취득한다.
PALETTISED | 비디오 이미지의 칼라 팔레트가 8 비트 이하일지 어떨지를 체크한다.
PALETTE_ENTRIES | 비디오 이미지의 팔레트의 색 가지수를 돌려준다.
RESET_MASKS | 지정된 비디오 이미지의 비트 마스크를 클리어 한다.
RESET_HEADER | 지정된 비디오 이미지를 클리어 한다.
RESET_PALETTE | 지정된 비디오 이미지의 칼라 팔레트를 클리어 한다.
SIZE_EGA_PALETTE | EGA (4 비트) 칼라 팔레트의 사이즈를 계산한다.
SIZE_MASKS | 마스크의 칼라 팔레트의 사이즈를 계산한다.
SIZE_MPEG1VIDEOINFO | 지정된 MPEG-1 비디오 이미지의 사이즈를 계산한다.
SIZE_PALETTE | 8 비트 칼라 팔레트의 사이즈를 계산한다.
SIZE_PREHEADER | 비디오 이미지의 비트 맵 정보의 바이트 오프셋(offset)를 계산한다.
SIZE_VIDEOHEADER | 비디오 이미지의 사이즈를 계산한다.
TRUECOLORINFO | 지정된 VIDEOINFOHEADER 구조체의 비트 마스크 및 칼라 팔레트를 기술하는 TRUECOLORINFO 구조체의 배열에의 포인터를 취득한다.

이러한 함수는, 비디오 데이터 스트림을 기술하기 위해서 DirectShow 전반으로 사용되는 VIDEOINFOHEADER 구조체의 관리에 도움이 된다. Microsoft® Win32® 및 기존의 멀티미디어로 사용되는 BITMAPINFO 구조체를 닮아 있지만,VIDEOINFOHEADER 에는 몇개의 새로운 비디오 고유의필드가 추가되고 있다.

글로벌 데이터 | 설명
bits555 | RGB 555 비트 맵의 칼라 비트 마스크의 배열
bits565 | RGB 565 비트 맵의 칼라 비트 마스크의 배열
bits888 | RGB 24 비트 비트 맵의 칼라 비트 마스크의 배열

BIT_MASKS_MATCH

비디오 함수와 이미지 함수

지정된 비디오 이미지의 비트 마스크를 취득한다.

구문

BIT_MASKS_MATCH(
  pbmi1,
  pbmi2
  )

파라미터

pbmi1
최초의 비디오 이미지를 포함한 Win32 VIDEOINFOHEADER 구조체에의 포인터.
pbmi2
2 번째의 비디오 이미지를 포함한 Win32 VIDEOINFOHEADER 구조체에의 포인터.

반환값

양쪽 모두의 비디오 이미지의 비트 마스크가 같은 경우는 제로 이외의 값을 돌려주어, 그 이외의 경우는 제로를 돌려준다.

BITMASKS

비디오 함수와 이미지 함수

지정된 비디오 이미지의 비트 마스크를 취득한다.

구문

BITMASKS(
  pbmi
  )

파라미터

pbmi
비디오 이미지를 포함한 Win32 VIDEOINFOHEADER 구조체에의 포인터.

반환값

지정된 VIDEOINFOHEADER 구조체의 비트 마스크의 배열에의 포인터를 돌려준다.

COLORS

비디오 함수와 이미지 함수

지정된 비디오 이미지의 칼라 팔레트를 취득한다.

구문

COLORS(
  pbmi
  )

파라미터

pbmi
비디오 이미지를 포함한 Win32 VIDEOINFOHEADER 구조체에의 포인터.

반환값

지정된 VIDEOINFOHEADER 구조체의 칼라 팔레트를 기술하는 RGBQUAD 구조체의 배열에의 포인터를 돌려준다.

ContainsPalette

비디오 함수와 이미지 함수

비디오 이미지에 칼라 팔레트가 포함되어 있는지 어떤지를 체크한다.

구문

BOOL ContainsPalette(
  const VIDEOINFOHEADER *pVideoInfo
  );

파라미터

pVideoInfo
VIDEOINFOHEADER 구조체에의 포인터.

반환값

VIDEOINFOHEADER 구조체가 칼라 팔레트를 포함하고 있는 경우는 TRUE 를 돌려주어, 그 이외의 경우는 FALSE 를 돌려준다.

ConvertVideoInfoToVideoInfo2

비디오 함수와 이미지 함수

VIDEOINFO 스트림 포맷을 VIDEOINFOHEADER2 포맷으로 변환한다.

구문

STDAPI ConvertVideoInfoToVideoInfo2(
    AM_MEDIA_TYPE *pmt
    );

파라미터

pmt
[in/out] AM_MEDIA_TYPE 열거형에의 포인터.

반환값

인터페이스의 이행에 의존하는 HRESULT 값을 돌려준다. HRESULT 에는, 다음의 몇개의 표준 정수, 또는 일람에 없는 것 외의 값이 포함된다.

E_OUTOFMEMORY | 처리로 메모리 부족이 발생했다.
S_OK | 성공.

주의

성공했을 경우, 이 함수는 AM_MEDIA_TYPE 의 formattype 멤버를 변경해, 등록된 GUID 를 VIDEOINFO 형으로부터 VIDEOINFOHEADER2 형으로 변경한다.

DIBSIZE

비디오 함수와 이미지 함수

지정된 (디바이스에 의존하지 않는다) 비트 맵의 바이트 사이즈를 계산한다.

구문

DIBSIZE(
  bi
  )

파라미터

bi
소스 비트 맵을 지정하는 Win32 BITMAPINFOHEADER 구조체.

반환값

bi 파라미터의 바이트 사이즈를 돌려준다.

GetBitCount

비디오 함수와 이미지 함수

픽셀 근처의 비트수를 조사한다.

구문

WORD GetBitCount(
  const GUID *pSubtype
  );

파라미터

pSubtype
임의의 비디오 서브 타입의 GUID 에의 포인터.

반환값

이 서브 타입의 픽셀 근처의 비트수를 돌려준다. 에러가 발생했을 경우는, USHRT_MAX 를 돌려준다.

GetBitmapFormatSize

비디오 함수와 이미지 함수

VIDEOINFOHEADER 구조체와 그 관련 데이터를 생성 하는데 필요한 사이즈 (바이트 단위)를 조사한다.

구문

LONG GetBitmapFormatSize(
  const BITMAPINFOHEADER *pHeader
  );

파라미터

pHeader
Win32 BITMAPINFOHEADER 구조체에의 포인터.

반환값

이 BITMAPINFOHEADER 에 의해 기술된 VIDEOINFOHEADER 구조체의 바이트수를 돌려준다 (프레픽스 정보,BITMAPINFOHEADER 필드, 및 그 외의 색정보를 포함한다).

GetBitmapPalette

비디오 함수와 이미지 함수

VIDEOINFOHEADER 구조체의 최초의 팔레트를 취득한다.

구문

const RGBQUAD * GetBitmapPalette(
  const VIDEOINFOHEADER *pVideoInfo
  );

파라미터

pVideoInfo
VIDEOINFOHEADER 구조체에의 포인터.

반환값

팔레트의 최초의 엔트리에의 포인터.

GetBitmapSize

비디오 함수와 이미지 함수

이미지를 보관 유지하는데 필요한 바이트수를 조사한다.

구문

DWORD GetBitmapSize(
  const BITMAPINFOHEADER *pHeader
  );

파라미터

pHeader
Win32 BITMAPINFOHEADER 구조체에의 포인터.

반환값

이미지를 보관 유지하는데 필요한 바이트수를 돌려준다.

GetBitmapSubtype

비디오 함수와 이미지 함수

지정된 비트 맵의 서브 타입을 조사한다.

구문

const GUID GetBitmapSubtype(
  const BITMAPINFOHEADER *pHeader
  );

파라미터

pHeader
Win32 BITMAPINFOHEADER 구조체에의 포인터.

반환값

pHeader 에 의해 지정된 비트 맵의 비디오 서브 타입 GUID 를 돌려준다. pHeader 가 NULL 의 경우는, GUID_NULL 를 돌려준다.

GetSubtypeName

비디오 함수와 이미지 함수

임의의 GUID 서브 타입의 이름을 취득한다.

구문

TCHAR * GetSubtypeName(
  const GUID *pSubtype
  );

파라미터

pSubtype
임의의 비디오 서브 타입의 GUID 에의 포인터.

반환값

이 GUID 의 디버그명을 돌려준다. 이름이 불명의 경우는, UNKNOWN 를 돌려준다.

GetTrueColorType

비디오 함수와 이미지 함수

지정된 16 비트색비트 맵의 서브 타입을 조사한다.

구문

const GUID GetTrueColorType(
  const BITMAPINFOHEADER *pHeader
  );

파라미터

pHeader
Win32 BITMAPINFOHEADER 구조체에의 포인터.

반환값

pHeader 에 의해 지정된 16 비트색비트 맵의 비디오 서브 타입 GUID 를 돌려준다. pHeader 가 NULL 의 경우는, GUID_NULL 를 돌려준다.

HEADER

비디오 함수와 이미지 함수

지정된 비디오 이미지로부터 이미지 데이터에의 포인터를 취득한다.

구문

HEADER(
  pVideoInfo
  )

파라미터

pVideoInfo
비디오 이미지를 지정하는 VIDEOINFOHEADER 구조체에의 포인터.

반환값

VIDEOINFOHEADER 구조체의 bmiHeader 데이터 멤버에 포함되는 Win32 BITMAPINFOHEADER 구조체에의 포인터를 돌려준다.

MPEG1_SEQUENCE_INFO

비디오 함수와 이미지 함수

지정된 MPEG-1 비디오 이미지의 순서 헤더를 취득한다.

구문

MPEG1_SEQUENCE_INFO(
  pv
  )

파라미터

pv
MPEG1VIDEOINFO 구조체에의 포인터.

반환값

지정된 MPEG1VIDEOINFO 구조체의 bSequenceHeader 데이터 멤버를 돌려준다.

PALETTISED

비디오 함수와 이미지 함수

비디오 이미지의 칼라 팔레트가 8 비트 이하일지 어떨지를 체크한다.

구문

PALETTISED(
  pbmi
  )

파라미터

pbmi
비디오 이미지를 지정하는 Win32 BITMAPINFOHEADER 구조체에의 포인터.

반환값

비디오 이미지의 팔레트가 256 색이하의 색을 포함하고 있는 경우는 제로 이외의 값을 돌려주어, 그 이외의 경우는 제로를 돌려준다.

PALETTE_ENTRIES

비디오 함수와 이미지 함수

비디오 이미지의 팔레트의 색의 수를 취득한다.

구문

PALETTE_ENTRIES(
  pbmi
  )

파라미터

pbmi
비디오 이미지를 지정하는 Win32 BITMAPINFOHEADER 구조체에의 포인터.

반환값

비디오 이미지의 팔레트의 색의 수를 돌려준다.

RESET_MASKS

지정된 비디오 이미지의 비트 마스크를 클리어 한다.

구문

RESET_MASKS(
  pbmi
  )

파라미터

pbmi
비디오 이미지를 지정하는 Win32 BITMAPINFOHEADER 구조체에의 포인터.

반환값

반환값 없음.

RESET_HEADER

비디오 함수와 이미지 함수

지정된 비디오 이미지를 클리어 한다.

구문

RESET_HEADER(
  pbmi
  )

파라미터

pbmi
비디오 이미지를 지정하는 Win32 BITMAPINFOHEADER 구조체에의 포인터.

반환값

반환값 없음.

RESET_PALETTE

비디오 함수와 이미지 함수

지정된 비디오 이미지의 칼라 팔레트를 클리어 한다.

구문

RESET_PALETTE(
  pbmi
  )

파라미터

pbmi
비디오 이미지를 지정하는 Win32 BITMAPINFOHEADER 구조체에의 포인터.

반환값

반환값 없음.

SIZE_EGA_PALETTE

비디오 함수와 이미지 함수

4 비트 칼라 팔레트의 사이즈를 계산한다.

구문

SIZE_EGA_PALETTE

반환값

16 색팔레트의 사이즈를 바이트 단위로 돌려준다.

SIZE_MASKS

비디오 함수와 이미지 함수

비트 마스크의 칼라 팔레트의 사이즈를 계산한다.

구문

SIZE_MASKS

반환값

3 색을 가지는 비트 맵 마스크의 칼라 팔레트의 사이즈를 바이트 단위로 돌려준다.

SIZE_MPEG1VIDEOINFO

비디오 함수와 이미지 함수

지정된 MPEG-1 비디오 이미지의 사이즈를 계산한다.

구문

SIZE_MPEG1VIDEOINFO(
  pv
  )

파라미터

pv
비디오 이미지를 지정하는 MPEG1VIDEOINFO 구조체에의 포인터.

반환값

지정된 MPEG1VIDEOINFO 구조체의 바이트 사이즈를 돌려준다.

SIZE_PALETTE

비디오 함수와 이미지 함수

8 비트 칼라 팔레트의 사이즈를 계산한다.

구문

SIZE_PALETTE

반환값

256 색팔레트의 사이즈를 돌려준다.

SIZE_PREHEADER

비디오 함수와 이미지 함수

비디오 이미지의 비트 맵 정보의 바이트 오프셋(offset)를 계산한다.

구문

SIZE_PREHEADER

반환값

VIDEOINFOHEADER 구조체의 bmiHeader 데이터 멤버의 바이트 오프셋(offset)를 돌려준다.

SIZE_VIDEOHEADER

비디오 함수와 이미지 함수

비디오 이미지의 사이즈를 계산한다.

구문

SIZE_VIDEOHEADER

반환값

VIDEOINFOHEADER 구조체의 모든 데이터 멤버의 합계 사이즈를 돌려준다.

TRUECOLORINFO

비디오 함수와 이미지 함수

지정된 비디오 이미지의 칼라 팔레트 및 비트 마스크를 취득한다.

구문

TRUECOLORINFO(
  pbmi
  )

파라미터

pbmi
비디오 이미지를 포함한 Win32 VIDEOINFOHEADER 구조체에의 포인터.

반환값

지정된 VIDEOINFOHEADER 구조체의 비트 마스크 및 칼라 팔레트를 기술하는 TRUECOLORINFO 구조체의 배열에의 포인터를 취득한다.


디버그 유틸리티

이 섹션에는 Microsoft® DirectShow® 가 디버그 원조를 위해서(때문에) 제공하는 매크로나 함수의 참조 엔트리가 있다. 이러한 함수를 사용하려면 ,base class 라이브러리를 빌드 해야 한다. 상세한 것에 대하여는, 「DirectShow 에서의 디버그」를 참조할것.

  • Assert 매크로와 breakpoint 매크로
  • 크리티컬 섹션 디버그 함수
  • 디버그 출력 함수
  • 포인터 유효 매크로
  • 대기 디버그 함수


Assert 매크로와 breakpoint 매크로

Microsoft® DirectShow® base class는 Assert를 실시하거나 breakpoint를 발생시키는 몇개의 매크로를 제공한다.

선언 : Wxdebug.h

매크로 | 설명
ASSERT | 조건식을 평가해, 그 조건이 FALSE 라면 진단 메세지를 표시한다.
DbgAssertAligned | 포인터가 지정된 범위에 있을지 어떨지를 테스트한다.
DbgBreak | 지정한 캐릭터 라인, 원시 파일명, 라인 넘버로 메시지 박스를 표시한다.
EXECUTE_ASSERT | 디버그 빌드와 리테일 빌드의 조건식을 평가한다. 디버그 빌드에서는, 조건이 FALSE 라면 진단 메세지를 표시한다.
KASSERT | 조건식을 평가해, 조건이 FALSE 라면 breakpoint 예외를 발생시킨다.
KDbgBreak | 보레이크포인트 예외를 발생시켜, 지정한 캐릭터 라인을 로그 한다.

ASSERT

Assert 매크로와 breakpoint 매크로

조건식을 평가해, 그 조건이 FALSE 라면 진단 메세지를 표시한다. 리테일 빌드에서는 무시된다.

구문

ASSERT(
    cond
);

파라미터

cond
평가하는 조건식.

주의

디버그 빌드에서는, 조건식이 FALSE 라면, 이 매크로는 메시지 박스에 조건의 텍스트와 원시 파일의 이름과 라인 넘버를 표시한다. 유저는 Assert를 무시하는 일도, 디버거에 들어가는 일도, 어플리케이션을 종료시킬 수도 있다.

례

ASSERT(rtStartTime <= rtEndTime);

DbgAssertAligned

Assert 매크로와 breakpoint 매크로

포인터가 지정된 범위에 있을지 어떨지를 테스트한다. 범위외라면, 이 매크로는 ASSERT 매크로를 동작시킨다. 리테일 빌드에서는 무시된다.

구문

DbgAssertAligned(
    ptr,
    alignment
);

파라미터

ptr
포인터 변수.
alignment
요구된 alignment.

DbgBreak

Assert 매크로와 breakpoint 매크로

메시지 박스로 지정한 캐릭터 라인과 원시 파일의 이름과 라인 넘버를 표시한다. 유저는 Assert를 무시하는 일도, 디버거에 들어가는 일도, 어플리케이션을 종료시킬 수도 있다. 리테일 빌드에서는 무시된다.

구문

DbgBreak(
    strLiteral
);

파라미터

strLiteral
텍스트 캐릭터 라인.

례

DbgBreak("Unrecoverable error occurred. ");

EXECUTE_ASSERT

Assert 매크로와 breakpoint 매크로

디버그 빌드와 리테일 빌드의 조건식을 평가한다. 디버그 빌드에서는, 조건이 FALSE 라면 진단 메세지를 표시한다.

구문

EXECUTE_ASSERT(
    cond
);

파라미터

cond
평가하는 조건식.

주의

ASSERT 매크로와 달리, 이 매크로는 리테일 빌드로 조건식을 평가한다. 디버그 빌드에서는, 조건식이 FALSE 라면, 매크로는 조건의 텍스트와 원시 파일의 이름과 라인 넘버를 표시한다. 유저는 Assert를 무시하는 일도, 디버거에 들어가는 일도, 어플리케이션을 종료시킬 수도 있다.

KASSERT

Assert 매크로와 breakpoint 매크로

조건식을 평가해, 조건이 FALSE 라면 breakpoint 예외를 발생시킨다. 조건의 텍스트와 원시 파일의 이름과 라인 넘버가 DbgLog 매크로를 사용해 로그 된다. 리테일 빌드에서는 무시된다.

구문

KASSERT(
    cond
);

파라미터

cond
평가하는 조건식.

주의

ASSERT and EXECUTE_ASSERT 매크로와 달리, 이 매크로는 유저에게 알리는 메시지 박스를 표시시키지 않다. 디버그 빌드에서는, 조건이 FALSE 라면, 매크로는 자동적으로 breakpoint 예외를 발생시킨다.

KDbgBreak

Assert 매크로와 breakpoint 매크로

breakpoint 냉해를 발생시켜,DbgLog 매크로를 사용해 지정한 캐릭터 라인을 로그 한다. 리테일 빌드에서는 무시된다.

구문

KDbgBreak(
    strLiteral
);

파라미터

strLiteral
텍스트 캐릭터 라인.

주의

DbgBreak 매크로와 달리, 이 매크로는 유저에게 알리는 메시지 박스를 표시하지 않는다. 디버그 빌드에서는, 자동적으로 breakpoint 예외를 발생시킨다.


크리티컬 섹션 디버그 함수

이러한 함수는 코드내의 크리티컬 섹션의 디버그의 도움이 되어, 데드 록의 원인의 발견이 용이하게 된다. 이러한 함수는CCritSec 헬퍼 클래스를 사용하고 있다

선언 : Wxutil.h

CritCheckIn | 현재의 thread가 특정의 크리티컬 섹션을 소유하고 있는 것을 체크한다.
CritCheckOut | 현재의 thread가 특정의 크리티컬 섹션을 소유하고 있는 것을 체크한다.
DbgLockTrace | 특정의 크리티컬 섹션의 디버그 로깅을 유효 또는 무효로 한다.

CritCheckIn

크리티컬 섹션 디버그 함수

현재의 thread가 지정한 크리티컬 섹션의 소유자라면 TRUE 를 돌려준다.

구문

BOOL WINAPI CritCheckIn(

  CCritSec *pcCrit

  );

파라미터

pcCrit
CCritSec 크리티컬 섹션에의 포인터.

반환값

디버그 빌드 때, 현재의 thread가 이 크리티컬 섹션의 소유자인 경우는 TRUE 를 돌려주어, 그 이외의 경우는 FALSE 를 돌려준다. 리테일 빌드 때, 항상 TRUE 를 돌려준다.

주의

이 함수는 ASSERT 매크로와 동시에 사용하면(자), thread가 주어진 락을 소유하고 있을지 어떨지를 테스트하는데 매우 편리합니다.

다음의 코드예는 이 함수의 사용법을 나타낸다 :

{
    CCritSec MyLock;  // 크리티컬 섹션은 아직 잠그지 않았다

    ASSERT(CritCheckIn(&MyLock)); // 이 assert 는 메세지를 보낸다

    // 크리티컬 섹션을 잠근다
    CAutoLock cObjectLock(&MyLock);

    ASSERT(CritCheckIn(&MyLock)); // 이 assert 는 메세지를 보내지 않는다

} // 락의 디버그는 여기까지

CritCheckOut

크리티컬 섹션 디버그 함수

현재의 thread가 지정한 크리티컬 섹션의 소유자 때 FALSE 를 돌려준다

구문

BOOL WINAPI CritCheckOut(

  CCritSec *pcCrit

  );

파라미터

pcCrit
CCritSec 크리티컬 섹션에의 포인터.

반환값

디버그 빌드 때, 현재의 thread가 이 크리티컬 섹션의 소유자의 경우는 FALSE 를 돌려주어, 그 이외의 경우는 TRUE 를 돌려준다. 리테일 빌드 때, 항상 TRUE 를 돌려준다.

주의

이 함수는 CritCheckIn 함수의 역이다. CritCheckIn 가 TRUE 때,CritCheckOut 는 FALSE 를 돌려주어, 반대라면 TRUE 를 돌려준다.

DbgLockTrace

크리티컬 섹션 디버그 함수

특정의 크리티컬 섹션의 디버그 로깅을 유효 또는 무효로 한다.

구문

void WINAPI DbgLockTrace(

  CCritSec *pcCrit,

  BOOL fTrace

  );

파라미터

pcCrit
CCritSec 크리티컬 섹션에의 포인터.
fTrace
로깅을 유효하게 할지 어떨지를 지정하는 값. 로깅을 유효하게 하려면 TRUE 를 사용해, 로깅을 무효로 하려면 FALSE 를 사용한다.

주의

이 함수를 사용해 지정한 크리티컬 섹션을 트레이스 한다. 디폴트에서는 크리티컬 섹션으로 디버그 로깅은 무효입니다, 왜냐하면 크리티컬 섹션의 수가 매우 많기 때문입니다.

크리티컬 섹션을 트레이스 하려면 , 다음의 스텝을 실시한다:

  1. DirectShow 헤더를 인클루드 하기 전에 DEBUG 를 정의한다.
  2. DbgSetModuleLevel 를 LOG_LOCKING 플래그로 호출해 크리티컬 섹션의 디버그 로깅을 유효하게 한다.
  3. 트레이스 하고 싶은 크리티컬 섹션으로 DbgLockTrace 를 호출한다.

다음의 코드예는 크리티컬 섹션의 트레이스 방법을 나타낸다 :

DbgInitialise(g_hInst);
DbgSetModuleLevel(LOG_LOCKING, 3);

{
    CCritSec MyLock;
    DbgLockTrace(&MyLock, TRUE);

    CAutoLock cObjectLock(&MyLock);

    // 코드의 보호된 부분
    DbgOutString("This code is inside a critical section. \n");

} // 락의 디버그는 여기까지

DbgTerminate();

디버그 출력은 이하와 같이 볼 수가 있다 :

Example.exe(tid 360)     2012 : Thread 864 now owns lock 12fc2c
This code is inside a critical section.
Example.exe(tid 360)     4887 : Thread 864 releasing lock 12fc2c

DirectShow 헤더를 인클루드 하면 와, DEBUG 가 정의되어 있지 않으면DbgLockTrace 함수는 유효하게 안 된다.


디버그 출력 함수

Microsoft® DirectShow® base class는 디버그 정보 표시용의 몇개의 매크로를 제공한다.

선언 : Wxdebug.h

DirectShow 의 디버그 환경은 특정의 타입의 디버그 정보를, 다른 사람을 무시해, 파인츄 할 수가 있다. 이 기능으로, 코드내의 특정의 범위에 문제를 핀 포인트 시킬 수가 있다. DirectShow 는 이하의 겉(표)에 나타나는 몇개의 메세지 타입을 정의한다.

LOG_ERROR | 에러 통지.
LOG_LOCKING | 크리티컬 섹션의 락과 언락.
LOG_MEMORY | 메모리 할당과 오브젝트의 생성 및 파기.
LOG_TIMING | 타이밍과 퍼포먼스의 측정.
LOG_TRACE | 일반적인 호출 트레이스.

모든 모듈은 각 메세지 타입에 대해 자신의 디버그 레벨을 설정할 수가 있다. (모듈 은 DLL 혹은 실행 모듈이며, Microsoft® Win32® LoadLibrary 함수를 사용해 로드 된다. ) 모듈이 주어진 메세지 타입에 대한 로깅 레벨은 레지스트리내의 다음의 키로 볼 수가 있다 :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\<Message Type>

<Message Type> 는 메세지 타입으로부터 머리의 "LOG_" 를 취한 것이다. 예를 들어,LOCKING 는 LOG_LOCKING 메세지.

모듈이 로드 되면(자), 디버그 라이브러리는 모듈의 로깅 레벨을 레지스트리로부터 읽어들인다. 레지스트리 키가 없으면 디버그 라이브러리는 그것을 생성 한다. 메세지 타입의 글로벌 로깅 레벨은 다음의 키로 지정된다 :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\GLOBAL\<Message Type>

디버그 라이브러리는 큰 (분)편의 레벨을 사용한다. 모듈은 DbgSetModuleLevel 함수를 사용해, 자신의 레벨을 런타임시로 설정할 수도 있다. 디버그 출력에 메세지를 보내려면 ,DbgLog 매크로를 호출하는 것. 다음의 예는 타입 LOG_TRACE 의 레벨 3 메세지를 생성 하고 있다 :

DbgLog((LOG_TRACE, 3, "This is a debug message. "));

디버그 빌드에서는, 현재의 LOG_TRACE 메세지의 로깅 레벨이 3 혹은 그 이상이라면, 메세지는 디버그 출력을 보낸다. 그 이외라면 무시된다. 디버그 빌드는 스트림 클래스 헤더 파일 Streams.h 에 포함되어 있는 프리프로세서 심볼 DEBUG 를 정의해야 한다.

디버그 출력 위치는 다른 레지스트리 키에 의해 정의되고 있다 :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\LogToFile

이 값이 Console 라면, 출력은 콘솔 윈도우가 된다. 이 값이 Deb,Debug,Debugger 혹은 공백 캐릭터 라인이라면, 출력은 디버거 윈도우가 된다. 그 이외라면, 출력은 레지스트리 키로 지정된 파일에 기입해진다.

실행 모듈이 DirectShow 디버그 라이브러리를 사용하기 전에,DbgInitialise 함수를 호출하지 않으면 안 된다. 마지막으로,DbgTerminate 함수 호출하지 않으면 안 된다. 이러한 함수를 호출하는데 DLL 는 필요없다.

함수 | 설명
DbgCheckModuleLevel | 주어진 메세지 타입과 레벨로 로깅이 가능한가 어떤가를 체크한다.
DbgDumpObjectRegister | 액티브한 오브젝트에 대한 정보를 표시한다.
DbgInitialise | 디버그 라이브러리를 초기화한다.
DbgLog | 지정한 타입과 레벨로 로깅 가능하면, 디버그 출력 위치에 캐릭터 라인을 보낸다.
DbgOutString | 디버그 출력 위치에 캐릭터 라인을 보낸다.
DbgSetModuleLevel | 1 개(살) 이상의 메세지 타입의 로깅 레벨을 설정한다.
DbgTerminate | 디버그 라이브러리를 클린 업 한다.
DisplayType | 미디어 타입에 대한 정보를 디버그 출력 위치에 보낸다.
DumpGraph | 필터 그래프에 대한 정보를 디버그 출력 위치에 보낸다.
NAME | 디버그 전용 캐릭터 라인을 생성한다.
NOTE | 디버그 출력 위치에 캐릭터 라인을 보낸다.
REMIND | 컴파일시에 주의를 생성한다.

DbgCheckModuleLevel

디버그 출력 함수

주어진 메세지 타입과 레벨로 로깅이 가능한가 어떤가를 체크한다. 리테일 빌드에서는 무시된다.

구문

BOOL DbgCheckModuleLevel(
    DWORD Types,
    DWORD Level
);

파라미터

Types
1 개(살) 이상의 메세지 타입의 비트의 편성.
Level
로깅 레벨

반환값

만약 지정한 메세지 타입에 대한 로깅이 지정한 레벨 혹은 그 이상으로 세트 되고 있으면(자), TRUE 를 돌려준다. 그 이외라면, FALSE 를 돌려준다.

DbgDumpObjectRegister

디버그 출력 함수

액티브한 오브젝트에 대한 정보를 표시한다. 리테일 빌드에서는 무시된다.

구문

void DbgDumpObjectRegister(void);

주의

디버그 빌드에서는, 디버그 라이브러리는 액티브한 오브젝트의 리스트를 보관 유지한다. CBaseObject 로부터 파생한 모든 오브젝트를 포함한 리스트는, 현재의 모듈에 의해 생성 되어 삭제되지 않는다. CBaseObject constructor　 　 과 소멸자 메소드가 이 리스트를 업데이트 한다.

이 함수는 몇개의 LOG_MEMORY 메세지를 생성한다. 로깅 레벨 1 에서는, 이 함수는 오브젝트의 전수만을 표시한다. 로깅 레벨 2 이상에서는, 오브젝트의 리스트를 표시한다.

DbgInitialise

디버그 출력 함수

디버그 라이브러리를 초기화한다. 리테일 빌드에서는 무시된다.

구문

void DbgInitialise(
    HINSTANCE hInst
);

파라미터

hInst
모듈 인스턴스에의 핸들.

주의

실행 모듈에서는, DirectShow 디버그 환경을 사용하기 전에 이 메소드를 호출하는 것. 실행 모듈이 종료하기 전에,DbgTerminate 함수를 호출해, 디버그 라이브러리를 클린 업 하는 것.

base class 라이브러리 (Strmbase.lib)에 링크하고 있는 DLL 에서는, 이 함수를 호출할 필요는 없다. 이 함수는 DLL 가 로드 될 때, 자동적으로 불려 간다.

DbgLog

디버그 출력 함수

지정한 타입과 레벨로 로깅 가능하면, 디버그 출력 위치에 캐릭터 라인을 보낸다. 리테일 빌드에서는 무시된다.

구문

void DbgLog((
    DWORD Types,
    DWORD Level,
    const TCHAR *pFormat,
    ...
));

파라미터

Types
1 개(살) 이상의 메세지 타입의 비트의 편성.
Level
이 메세지의 로깅 레벨
pFormat
printf스타일의 포맷 캐릭터 라인.
...
포맷 캐릭터 라인의 추가 인수.

주의

임의의 메세지 타입의 디버그 로깅이 지정한 레벨 이상으로 설정되어 있으면, 디버그 출력 위치에 캐릭터 라인을 보낸다

례

DbgLog((LOG_TRACE, 3, TEXT("Connected input pin %d"), nPinNumber));

외모를 추가 하면나무는 매크로 파라미터로 싸지 않으면 안 되는 것에 주의.

DbgOutString

디버그 출력 함수

디버그 출력 위치에 캐릭터 라인을 보낸다. 리테일 빌드에서는 무시된다.

구문

void DbgOutString(
    LPCTSTR psz
);

파라미터

psz
출력하는 캐릭터 라인.

주의

디버그 빌드에서는, 현재의 디버그 출력 레벨과 관계없이, 이 함수는 반드시 캐릭터 라인을 출력한다. 출력에 관해서보다 섬세한 컨트롤을 하려면 ,DbgLog 매크로를 사용하는 것.

례

DbgOutString("Creating the filter graph...\n");

DbgSetModuleLevel

디버그 출력 함수

1 개(살) 이상의 메세지 타입의 로깅 레벨을 설정한다. 리테일 빌드에서는 무시된다.

구문

void DbgSetModuleLevel(
    DWORD Types,
    DWORD Level
);

파라미터

Types
1 개(살) 이상의 메세지 타입의 비트의 편성.
Level
지정한 메세지 타입의 로깅 레벨

DbgTerminate

디버그 출력 함수

디버그 라이브러리를 클린 업 한다. 리테일 빌드에서는 무시된다.

구문

void DbgTerminate(void);

주의

DbgInitialise 함수를 호출했다면, 이 함수를 호출하는 것.

DisplayType

디버그 출력 함수

미디어 타입에 대한 정보를 디버그 출력 위치에 보낸다. 리테일 빌드에서는 무시된다.

구문

void DisplayType(
    LPSTR label,
    const AM_MEDIA_TYPE *pmtIn
);

파라미터

label
미디어 타입 정보를 표시하는 메세지가 들어가는 캐릭터 라인.
pmtIn
미디어 타입이 들어가는 AM_MEDIA_TYPE 구조체에의 포인터.

주의

이 함수는 몇개의 LOG_TRACE 메세지를 생성한다. 로깅 레벨 2 이상에서는, 이 함수는 메이저 타입, 마이너 타입, 포맷 타입, 포맷 블록으로부터의 데이터를 표시한다. 로깅 레벨 5 이상에서는, 이 함수는 비디오 타입의 전송원직사각형이나 타겟 직사각형과 같은 추가 정보를 표시한다.

DumpGraph

디버그 출력 함수

필터 그래프에 대한 정보를 디버그 출력 위치에 보낸다. 리테일 빌드에서는 무시된다.

구문

void DumpGraph(
    IFilterGraph *pGraph,
    DWORD dwLevel
)

파라미터

pGraph
필터 그래프 매니저의 IFilterGraph 인터페이스에의 포인터.
dwLevel
로깅 레벨. 함수는 지정한 로깅 레벨로 LOG_TRACE 메세지를 생성한다.

NAME

디버그 출력 함수

디버그 전용 캐릭터 라인을 생성한다.

구문

NAME(
    strLiteral
);

파라미터

strLiteral
텍스트 캐릭터 라인.

주의

디버그 빌드에서는, 이 매크로는 TEXT 매크로와 같다. 리테일 빌드에서는,(TCHAR*) NULL 를 해결한다. 이 매크로는 CBaseObject 클래스로부터 파생한 오브젝트의 이름을 선언 하면나무 편리하다.

례

pObject = new CBaseObject(NAME("My Object"));

NOTE, NOTE1, NOTE2, NOTE3, NOTE4, NOTE5

디버그 출력 함수

디버그 출력 위치에 캐릭터 라인을 보낸다. 리테일 빌드에서는 무시된다.

구문

NOTE(
    pFormat
);

NOTEn(
    pFormat,
    arg1 ... arg5
);

파라미터

pFormat
printf스타일의 포맷 캐릭터 라인.
arg1 – arg5
포맷 캐릭터 라인의 추가 인수. 인수의 수는 매크로의 이름과 일치해야 한다. 예를 들어, NOTE1 는 1 개의 인수를 가져, NOTE5 는 5 개의 인수를 가진다.

주의

이러한 매크로는 DbgLog 매크로의 변형이다. 그것들은 레벨 5 LOG_TRACE 메세지를 생성한다.

례

NOTE("Warning, failed to created graph. ");

NOTE2("Width: %d, Height: %d", width, height);

REMIND

디버그 출력 함수

컴파일시에 주의를 생성한다. 이 매크로는 파라미터 캐릭터 라인, 원시 파일명, 라인 넘버를 포함한 캐릭터 라인을 생성한다.

구문

REMIND(
    strLiteral
);

파라미터

strLiteral
텍스트 캐릭터 라인.

례

이 매크로는 컴파일시의 warning를 생성할 때에 편리하다 :

#pragma message (REMIND("TO DO: Add support for IDispatch. "))


포인터 유효 매크로

Microsoft® DirectShow® 는 포인터의 유효성을 확인하는 몇개의 매크로를 제공한다.

선언 : Wxdebug.h

매크로 | 설명
CheckPointer | 포인터가 NULL 화도나 체크한다.
ValidateReadPtr | 호출 프로세스가 메모리 블록에의 읽어들여 액세스를 가지고 있는 일을 검증한다.
ValidateReadWritePtr | 호출 프로세스가 메모리 블록에의 read와 기입의 액세스를 가지고 있는 일을 검증한다.
ValidateStringPtr | 호출 프로세스가 캐릭터 라인에의 읽어들여 액세스를 가지고 있는 일을 검증한다.
ValidateStringPtrA | 호출 프로세스가 ANSI 캐릭터 라인에의 읽어들여 액세스를 가지고 있는 일을 검증한다.
ValidateStringPtrW | 호출 프로세스가 와이드 캐릭터 캐릭터 라인에의 읽어들여 액세스를 가지고 있는 일을 검증한다.
ValidateWritePtr | 호출 프로세스가 메모리 블록에의 기입해 액세스를 가지고 있는 일을 검증한다.

CheckPointer

포인터 유효 매크로

포인터가 NULL 화도나 체크한다. 포인터가 NULL 라면, 매크로가 있는 그 함수 혹은 메소드는 지정한 값을 돌려준다.

구문

CheckPointer(
    p,
    ret
);

파라미터

p
체크하는 포인터.
ret
p 가 NULL 때, 이 함수 혹은 메소드가 돌려주는 값.

례

HRESULT MyFunction(VOID *pSomeParameter)
{
    CheckPointer(pSomeParameter, E_INVALIDARG)

    // 함수의 나머지 (생략).
}

ValidateReadPtr

포인터 유효 매크로

호출 프로세스가 메모리 블록에의 읽어들여 액세스를 가지고 있는 일을 검증한다. 가지고 있지 않은 경우, 이 매크로는 DbgBreak 매크로를 호출한다.

구문

ValidateReadPtr(
    const void *p,
    UINT cb
);

파라미터

p
메모리 블록에의 포인터.
cb
메모리 블록의 사이즈, 바이트 단위.

주의

DirectShow base class 헤더 파일이 인클루드 되었을 때, DEBUG 혹은 VFWROBUST 가 정의될 때까지, 이 매크로는 무시된다. 이 매크로는 퍼포먼스에 큰 영향을 준다.

ValidateReadWritePtr

포인터 유효 매크로

호출 프로세스가 메모리 블록에의 read와 기입의 액세스를 가지고 있는 일을 검증한다. 가지고 있지 않은 경우, 이 매크로는 DbgBreak 를 호출한다.

구문

ValidateReadWritePtr(
    const void *p,
    UINT cb
);

파라미터

p
메모리 블록에의 포인터.
cb
메모리 블록의 사이즈, 바이트 단위.

주의

DirectShow base class 헤더 파일이 인클루드 되었을 때, DEBUG 혹은 VFWROBUST 가 정의될 때까지, 이 매크로는 무시된다. 이 매크로는 퍼포먼스에 큰 영향을 준다.

ValidateStringPtr

포인터 유효 매크로

호출 프로세스가 캐릭터 라인에의 읽어들여 액세스를 가지고 있는 일을 검증한다. 가지고 있지 않은 경우, 이 매크로는 DbgBreak 를 호출한다.

구문

ValidateStringPtr(
    LPCTSTR p
);

파라미터

p
NULL 로 끝나는 TCHAR 캐릭터 라인에의 포인터.

주의

DirectShow base class 헤더 파일이 인클루드 되었을 때, DEBUG 혹은 VFWROBUST 가 정의될 때까지, 이 매크로는 무시된다. 이 매크로는 퍼포먼스에 큰 영향을 준다.

ValidateStringPtrA

포인터 유효 매크로

호출 프로세스가 ANSI 캐릭터 라인에의 읽어들여 액세스를 가지고 있는 일을 검증한다. 가지고 있지 않은 경우, 이 매크로는 DbgBreak 를 호출한다.

구문

ValidateStringPtrA(
    LPCSTR p
);

파라미터

p
NULL 로 끝나는 ANSI 캐릭터 라인에의 포인터.

주의

DirectShow base class 헤더 파일이 인클루드 되었을 때, DEBUG 혹은 VFWROBUST 가 정의될 때까지, 이 매크로는 무시된다

ValidateStringPtrW

포인터 유효 매크로

호출 프로세스가 와이드 캐릭터 캐릭터 라인에의 읽어들여 액세스를 가지고 있는 일을 검증한다. 가지고 있지 않은 경우, 이 매크로는 DbgBreak 를 호출한다.

구문

ValidateStringPtrW(
    LPCWSTR p
);

파라미터

p
NULL 출 끝나는 와이드 캐릭터 캐릭터 라인에의 포인터.

주의

DirectShow base class 헤더 파일이 인클루드 되었을 때, DEBUG 혹은 VFWROBUST 가 정의될 때까지, 이 매크로는 무시된다. 이 매크로는 퍼포먼스에 큰 영향을 준다.

ValidateWritePtr

포인터 유효 매크로

호출 프로세스가 메모리 블록에의 기입해 액세스를 가지고 있는 일을 검증한다. 가지고 있지 않은 경우, 이 매크로는 DbgBreak 를 호출한다.

구문

ValidateWritePtr(
    const void *p,
    UINT cb
);

파라미터

p
메모리 블록에의 포인터.
cb
메모리 블록의 사이즈, 바이트 단위.

주의

DirectShow base class 헤더 파일이 인클루드 되었을 때, DEBUG 혹은 VFWROBUST 가 정의될 때까지, 이 매크로는 무시된다. 이 매크로는 퍼포먼스에 큰 영향을 준다.


대기 디버그 함수

Microsoft® DirectShow® 는 몇개의 무한하게 대기하는 디버그 함수를 제공한다.

선언 : Wxdebug.h

리테일 빌드에서는,DbgWaitForMultipleObjects 함수와 DbgWaitForSingleObject 함수는 타임 아웃 간격이 무한해, Microsoft® Win32® 의 카운터 파트 WaitForMultipleObjects 와 WaitForSingleObject 와 같이 동작한다.

디버그 빌드에서는, 이러한 함수는 글로벌인 타임 아웃값을 사용한다. 타임 아웃이 마감 시간이 되면(자), 이 함수는 Assert를 기동한다. 다음의 레지스트리 키가 밀리 세컨드로 타임 아웃값을 지정한다 :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\TIMEOUT

이 키가 없는 경우, 타임 아웃값은 디폴트의 INFINITE 가 된다. DbgSetWaitTimeout 함수를 사용해 레지스트리의 값을 오버라이드(override) 할 수가 있다.

함수 | 설명
DbgSetWaitTimeout | 디버그 타임 아웃값을 설정한다.
DbgWaitForMultipleObjects | 지정된 임의의(혹은 모든) 오브젝트가 통지제가 될 때까지 기다린다.
DbgWaitForSingleObject | 어느 오브젝트가 통지제가 될 때까지 기다린다.

DbgSetWaitTimeout

대기 디버그 함수

디버그 타임 아웃값을 설정한다. 리테일 빌드에서는 무시된다.

구문

void DbgSetWaitTimeout(
    DWORD dwTimeout
);

파라미터

dwTimeout
밀리 세컨드 단위의 타임 아웃값, 혹은 무한하게 기다리는 INFINITE .

주의

디버그 빌드에서는,DbgWaitForMultipleObjects 함수와 DbgWaitForSingleObject 함수는 이 값을 타임 아웃 간격으로서 사용한다.

DbgWaitForMultipleObjects

대기 디버그 함수

지정된 임의의(혹은 모든) 오브젝트가 통지제가 될 때까지 기다린다.

디버그 빌드에서는, 오브젝트가 통지제가 되기 전에 타임 아웃 간격이 마감 시간이 되면(자), 이 함수는 Assert를 기동한다. 타임 아웃 간격을 설정하려면 ,DbgSetWaitTimeout 함수를 호출하는 것.

리테일 빌드에서는, 이 함수는 INFINITE 의 타임 아웃 간격으로 WaitForMultipleObjects 함수와 같다.

구문

DWORD DbgWaitForMultipleObjects(
    DWORD nCount,
    CONST HANDLE *lpHandles,
    BOOL bWaitAll
);

파라미터

nCount
오브젝트의 수.
lpHandles
오브젝트의 핸들의 배열,nCount 사이즈
bWaitAll
모든 오브젝트를 기다릴지 어떨지를 지정하는 불리언 값. TRUE 라면, 이 함수는 모든 오브젝트가 통지제가 될 때까지 기다린다. 그 이외라면, 적어도 1 개의 오브젝트 통지제가 될 때까지 기다린다.

DbgWaitForSingleObject

대기 디버그 함수

어느 오브젝트가 통지제가 될 때까지 기다린다.

디버그 빌드에서는, 오브젝트가 통지제가 되기 전에 타임 아웃 간격이 마감 시간이 되면(자), 이 함수는 Assert를 기동한다. 타임 아웃 간격을 설정하려면 ,DbgSetWaitTimeout 함수를 호출하는 것.

리테일 빌드에서는, 이 함수는 INFINITE 의 타임 아웃 간격으로 WaitForMSingleObject 함수와 같다.

구문

DWORD DbgWaitForSingleObject(
    HANDLE h
);

파라미터

h
오브젝트의 핸들.


DirectShow 샘플

Microsoft® DirectShow® SDK 샘플은, 기능에 응해 이하의 카테고리로 나눌 수 있다.

  • base class
  • BDA 샘플 어플리케이션
  • 샘플 캡춰 어플리케이션
  • DMO 샘플
  • 샘플 DVD 어플리케이션
  • 샘플 DirectShow 필터
  • DirectShow 의 그 외의 샘플
  • 샘플 플레이어 어플리케이션
  • 샘플 비디오 편집 어플리케이션

base class는, 필터의 생성이나 미디어 타입의 조작 등 DirectShow 의 작업을 실행하는데 편리한 C++ 클래스세트이다.

주

많은 DirectShow 샘플은 이 base class 라이브러리를 링크해, 필터의 생성, 미디어 타입의 조작, 그 이외의 DirectShow 태스크를 실행한다.

샘플을 생성 하는 가장 간단한 방법은, DirectShow 샘플 루트 디렉토리에 있는 워크 스페이스 파일 DShow.dsw 를 사용하는 방법이다. 이 워크 스페이스에는, 모든 샘플 프로젝트 파일에 대한 참조가 포함된다.

  • 모든 프로젝트를 생성 하려면 ,[빌드] 메뉴의 [배치 빌드] 를 선택한다.
  • 특정의 샘플 (의존을 포함한다)을 생성 하려면 ,[FileView] 페인의 프로젝트명을 오른쪽 클릭해, 표시된 pop-up menu로 [빌드] 를 클릭한다.

또, 각 샘플에 대한 프로젝트 파일도 포함되어 있어 샘플의 생성, 변경, 디버그에 사용할 수 있다. DShow.dsw 워크 스페이스를 사용하지 않고 , 이 방법으로 샘플을 생성 하는 경우는, 반드시, 최초로 base class 라이브러리를 생성 하는 것.

참조

빌드 환경의 설정


base class

설명

Microsoft® DirectShow® 의 base class는 C++ 클래스세트이며, DirectShow 필터를 이행 하기 위해서 사용할 수 있는 유틸리티 함수이다. base class의 상세한 것에 대하여는, 「DirectShow base class」를 참조할것.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\BaseClasses


BDA 샘플 어플리케이션

설명

새로운 Microsoft® Broadcast Driver Architecture (BDA)를 지원 하는 디지털 TV 튜너 카드를 베이스로 한 필터 그래프를 구축하는 방법을 데먼스트레이션 한다. 이 샘플은 새로운 Microsoft® Tuning Model 를 베이스로 한 튜닝의 방법도 가리킨다. 이 샘플은 디지털 TV 어플리케이션을 쓰는 중(안)에서 보다 상세하게 설명되고 있다.

패스

소스: (SDK root)\Samples\Multimedia\DirectShow\BDA\BDASample

실행 가능 파일 : (SDK root)\Samples\Multimedia\DirectShow\Bin\Bdasample.exe

주: 이 샘플을 빌드 하려면 시스템에 있는 strmbasd.lib 이나 strmbase.lib 가 없으면 안 된다. 이 라이브러리는 DirectShow base class를 빌드 하면 생성 된다. 상세한 것에 대하여는, 「DirectShow base class의 사용법」을 참조할것.


샘플 캡춰 어플리케이션

Microsoft® DirectShow® SDK 에는, 이하의 샘플 캡춰 어플리케이션이 포함되어 있다.

C++ 어플리케이션

  • AmCap 샘플
  • DVApp 샘플
  • PlayCap 샘플


AmCap 샘플

설명

비디오 캡춰 어플리케이션

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Capture\AMCap

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DirectShow\Bin\AMCap.exe

유저 가이드

이 샘플 어플리케이션은, 오디오 및 비디오 캡춰에 관련하는 이하의 태스크를 데먼스트레이션 한다.

  • 파일에의 캡춰
  • 라이브 프리뷰
  • 캡춰 파일의 할당
  • 디바이스 프로퍼티 페이지의 표시
  • 디바이스의 열거
  • 스트림 컨트롤

참조

비디오 캡춰


DVApp 샘플

설명

디지털 비디오 (DV) 캡춰 어플리케이션.

이 샘플은 DV 캠 코다를 제어하는 여러가지 타입의 필터 그래프를 구축하는 방법을 데먼스트레이션 한다. DV 캠 코다를 사용한 캡춰, 프리뷰, 전송, 디바이스 제어의 방법도 가리킨다.

패스

소스: (SDK 루트)\Samples\Multimedia\DirectShow\Capture\DVApp

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DirectShow\Bin\DVApp.exe

유저 가이드

DVApp 어플리케이션은 이하의 모드를 지원 한다 :

  • Preview: 캠 코다로부터 비디오 윈도우에 DV 를 렌더링 한다.
  • DV to type-1 file: 캠 코다로부터 Type-1 DV 파일에 DV 데이터를 캡춰 한다.
  • Type-1 file to DV: Type-1 DV 파일로부터 캠 코다에 데이터를 전송 한다.
  • DV to type-2 file: 캠 코다로부터 Type-2 DV 파일에 DV 데이터를 캡춰 한다.
  • Type-2 file to DV: Type-2 DV 파일로부터 캠 코다에 데이터를 전송 한다.

캡춰 모드와 전송 모드에서는 프리뷰도 행해진다. 이러한 각 모드는 프리뷰를 불가로 하는 No Preview 옵션도 이와 같이 가지고 있다. 프리뷰없이의 캡춰 링은 보다 효율적으로, 드롭 프레임을 줄일 수가 있다. Type-1 파일과 Type-2 파일에 대한 정보는, 「DirectShow 에서의 디지털 비디오」를 참조할것.

어플리케이션은 프리뷰 모드로 시작 한다. 다른 모드를 선택하려면 ,Graph Mode 메뉴로부터 선택하는 것. 각 모드에 대해서, DVApp 는 그 모드의 기능을 지원 하는 필터 그래프를 구축한다. GraphEdit (. grf) 파일로서 그 그래프를 보존하려면 ,File 메뉴로부터 Save Graph to File 를 선택하는 것. GraphEdit 로 파일을 열기 전에, DVApp 를 종료시키는 것.

파일에 캡춰 하려면 :

  1. Graph Mode 메뉴로부터, (type 1 이나 type 2, with preview 나 without preview 로) DV to File 모드를 선택한다.
  2. File 메뉴로부터,Set Output File 를 선택해, 파일명을 입력한다.
  3. Record 를 클릭한다.
  4. 캠 코다가 VTR 라면,Play 를 클릭한다.
  5. 캡춰를 정지하려면 ,Stop 를 클릭한다.

파일로부터 캠 코다에 전송 하려면 :

  1. Graph Mode 메뉴로부터, (type 1 이나 type 2, with preview 나 without preview 로) File to DV 모드를 선택한다.
  2. File 메뉴로부터,Set Input File 를 클릭해 DV 파일을 선택한다. 파일은 선택된 모드 (Type-1 나 Type-2)와 일치해야 한다.
  3. Play 를 클릭.
  4. 데이터를 테이프에 녹화하려면 ,Record 를 클릭한다.
  5. 전송을 정지하려면 ,Stop 를 클릭한다.

캠 코다가 VTR 모드라면, 유저는 어플리케이션의 VCR-style 버튼을 통해 전송 메카니즘을 제어할 수 있다. 테이프를 시크 하려면 , 타겟 타임 코드를 입력해 시크 버튼을 누른다.

어플리케이션이 캡춰 하는 데이터량을 제한하려면 ,File 메뉴로부터 Capture Size 를 선택한다.

테이프 포맷 (NTSC 나 PAL)을 체크하려면 ,Options 메뉴로부터 Check Tape 를 선택한다.

프리뷰 윈도우의 사이즈를 변경하려면 ,Options 메뉴로부터 Change Decode Size 를 선택한다.

프로그래밍의 주의

이 어플리케이션의 주목적은 여러가지 DV 캡춰와 DV 전송 그래프의 구축 방법을 나타내는 것이다. 어플리케이션은 ICaptureGraphBuilder2 인터페이스를 사용해 프리뷰 그래프와 Type-1 캡춰 그래프를 구축할 수가 있다. 다른 타입의 DV 그래프는 한 번에 1개의 필터 밖에 구축할 수 없다. DVApp 샘플은 프리뷰 그래프의 구축에 ICaptureGraphBuilder2 만을 사용하고 있다.

다음의 다이어그램은 Type-1 파일을 캡춰 하는 필터 그래프를 나타낸다 :

Type-1 DV 파일 캡춰 그래프

인터리브 된 오디오 비디오 데이터는 MSDV 로부터 스마트티 필터에 보내진다. 스마트티피르타의 캡춰 핀으로부터의 데이터는 파일에 기입해지는, 한편 프리뷰 핀으로부터의 데이터는 비디오 렌더러와 오디오 렌더러에 보내진다.

다음의 다이어그램은 Type-2 파일로부터 캠 코다에의 전송을 하는 필터 그래프를 나타낸다 :

Type-2 DV 파일 전송 그래프

AVI 스플리터 필터는 AVI 파일을 퍼스 해,DV Muxer 필터는 2 개의 스트림을 멀티플렉스 해, 인터리브 오디오 비디오 스트림을 생성 한다. 인피닛트핀티 필터는 그 스트림을 2 개의 같은 스트림에 분할한다. 1 개의 스트림은 MSDV 에 가, 한편 이제(벌써) 1 개(살)은 DV 스플리터 필터를 통해 프리뷰에 간다. 이것과 등가인 다른 그래프 구성도 가능하다.

디바이스의 착탈

어플리케이션은 2 개가 다른 테크닉을 사용해 디바이스의 착탈을 처리한다. 디바이스가 장착되었을 때, 어플리케이션의 메시지 루프는 WM_DEVICECHANGE 메세지에 대응한다. 디바이스가 떼어졌을 때, 어플리케이션은 필터 그래프 매니저로부터의 EC_DEVICE_LOST 이벤트를 처리한다. 어느 쪽의 어프로치도 동작한다, 그러나 EC_DEVICE_LOST 이벤트는 필터 그래프에 디바이스의 존재하는 것이 필요하다.

어플리케이션은 1 번에 1 개의 디바이스만을 처리한다. 현재의 디바이스가 떼어지면(자), 어플리케이션은 시스템 위에의별의 DV 디바이스를 찾는다.

몇개의 DV 캠 코다에서는, 카메라 모드와 VTR 모드간에 스윗치 했을 때 디바이스 로스트 메세지를 발생하기 위해(때문에), 유저가 디바이스를 상트오후 해야 한다. 어플리케이션은 적절한 메뉴 커멘드를 이용가능, 이용 불가로 하는 것으로 이것에 대응한다. 그러나, 유저가 모드간을 재빠르게 바꾸면(자), 캠 코다는 디바이스 로스트 메세지를 생성하지 않는 경우가 있다. Options 메뉴로부터 Refresh Mode 를 선택하는 것에 의해 메뉴를 업데이트 시킬 수가 있다. 상트오프없이 모드를 바꿀 수가 있지만, VTR 모드에 스윗치 되었을 때만 디바이스 로스트 메세지를 보내는 DV 캠 코다도 있다.

주 Microsoft® Windows® 95 and Microsoft® Windows NT® 4.0 이전으로는 디바이스 장착에 이용되는 디바이스 타입을 지원 하지 않는다. 이러한 플랫폼에 대해서, 어플리케이션을 컴파일 하기 위해서, WINVER 가 0x500 보다 작은 경우 데이터 타입은 조건적으로 인클루드 된다. 그러나, 어플리케이션은 이러한 플랫폼에서 디바이스 검지를 지원 하지 않는다.

디바이스 제어

어플리케이션의 Play 와 Record 버튼은 현재의 모드에 의존한다 :

  • Preview: 필터 그래프는 자동적으로 실행한다. Play 버튼은 전송을 시작 한다.
  • Capture to file: Record 버튼은 그래프를 실행해,Play 버튼은 전송을 시작 한다.
  • Transmit to device: Play 버튼은 그래프를 실행해,Record 버튼은 전송을 시작 한다.

샘플 어플리케이션은 프레임 정밀도의 캡춰는 실시하지 않는다. 몇개의 포인트로, 어플리케이션은 Sleep 함수를 호출해 디바이스의 반응을 기다린다. 디바이스 변경 상태시에는 DV 캠 코다는 절대로 통지를 보내지 않는다. 이전의 디바이스는 통지를 지원 하고 있지 않는 경우가 있는, 샘플의 목적으로부터는,Sleep 호출이 심플한 해결 방법이다. 자세한 것은 「DV 캠 코다의 제어」를 참조할것.


PlayCap 샘플

설명

단순한 캡춰 어플리케이션.

이 어플리케이션에서는, 유저의 시스템으로 발견된 최초의 비디오 캡춰 디바이스 (있는 경우)의 프리뷰 윈도우가 생성 된다. 또,ICaptureGraphBuilder2 인터페이스 및 ICreateDevEnum 인터페이스를 사용해 캡춰 그래프를 구축하는 단순한 예가 나타난다.

한층 더 많은 기능을 지원 하는 샘플 캡춰 어플리케이션에 대해서는, 「AmCap 」를 참조할것.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Capture\PlayCap

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DirectShow\Bin\PlayCap.exe

참조

비디오 캡춰


DMO 샘플

Microsoft® DirectShow® SDK 에는, 다음의 Microsoft® DirectX® 미디어 오브젝트 (DMO) 샘플이 포함되어 있다.

  • DMO 데모
  • DMO 샘플
  • 가굴 DMO 샘플


DMO 데모

설명

이 샘플 어플리케이션은, Microsoft® DirectX® 미디어 오브젝트 (DMO)의 사용법에 대해 가리키고 있다. WAV 파일로부터 오디오 이펙트 DMO 를 통해서, 오디오 데이터를 Microsoft® DirectSound® 버퍼에 스트리밍 한다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\DMO\DMODemo

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DirectShow\Bin\DMODemo.exe

유저 가이드

사운드 파일을 읽어들이려면 ,[Sound File] 를 클릭한다. 드롭 다운 combobox를 사용해 오디오 이펙트 DMO 를 선택한다. 다음에,[Play] 를 클릭해, 오디오 이펙트가 설정된 사운드 파일을 재생한다.


DMO 샘플

설명

DMO 샘플은, Microsoft® DirectX® 미디어 오브젝트 (DMO)의 샘플이다. MPEG-1 비디오 패킷을 입력으로 해, 출력 스트림을 2 개 생성한다. 최초의 출력 스트림에는, RGB 565 포맷의 비디오 프레임이 포함되어 있다. 각 프레임은 MPEG-1 비디오로부터 취득한 타임 코드를 표시해, 그것이 없는 경우는 아무것도 표시하지 않는다. 2 개째의 출력 스트림은, 타임 코드가 붙은, 옵션의 텍스트 스트림이다.

DMO 샘플은,IMediaObjectImpl base class 템플릿을 사용해,IMediaObject 인터페이스를 이행 한다. 이 템플릿의 사용법의 상세한 것에 대하여는, 「DMO base class의 사용법」을 참조할것. Active Template Library (ATL)는, 등록, 집합,IUnknown , DLL 엔트리 포인트 등, 다양한 COM 의 상세를 처리한다.

패스

소스 :(SDK 루트)\samples\Multimedia\DirectShow\DMO\DMOSample

유저 가이드

이 프로젝트 워크 스페이스에서는, Dmosample.dll 라는 이름의 DLL 를 생성 한다. Regsvr32 유틸리티를 사용해 DLL 를 생성 한다. 이 DMO 의 동작을 보려면 , Microsoft® DirectShow® GraphEdit 유틸리티를 사용한다. 다만, MPEG-1 비디오 파일이 필요하다. 다음의 순서에 따라 실행한다.

  1. GraphEdit 를 실행한다.
  2. MPEG-1 파일을 렌더링 한다.
    • [File] 메뉴로 [Render Media File] 를 클릭한다.
    • MPEG-1 비디오 파일을 선택해,[Open] 를 클릭한다.
  3. 필터 그래프로부터 MPEG-1 비디오 디코더 필터를 선택해, Del 키를 누른다.
  4. 그래프에 DMO 샘플을 삽입한다.
    • [Graph] 메뉴로,[Insert Filters] 를 클릭한다.
    • [DirectShow Filters] 리스트를 전개한다.
    • [DMO Sample] 를 선택해,[Insert Filters] 를 클릭한다.
    • [Close] 를 클릭한다.
  5. MPEG-1 스트림 스플리터 위에의 [Video] 라고 하는 라벨이 붙은 작은 박스로부터, DMO 샘플 위에의 [in0] 라고 하는 박스까지 마우스를 드러그 해,MPEG-1 스트림 스플리터를 DMO 샘플에 접속한다. (그림을 참조할것)
  6. DMO 샘플을비디오 렌더러에 접속한다.
    • DMO 샘플 위에의 [out0] 라고 하는 라벨이 붙은 박스로부터, 비디오 렌더러 위에의 [Input] 라고 하는 라벨이 붙은 박스까지 마우스를 드러그 한다.
    • GraphEdit 에 의해, RGB 타입간의 변환을 실시하는칼라 스페이스 변환 필터가 자동적으로 삽입된다.
  7. [GraphEdit] 툴바의 [Play] 버튼을 누르는지, 또는 [Graph] 메뉴로 [Play] 를 클릭한다.

그래프를 실행 하면, 타임 코드를 표시하는 [Video] 윈도우가 나타난다.

DMO 샘플 필터의 접속

프로그래밍 위에의 주의

DMO 샘플에는, 이하의 소스 및 헤더 파일이 포함되어 있다.

  • Dmosample.cpp: 기본적인 COM 기능을 ATL 에 이행하기 위한 코드.
  • Resource.h: 리소스 정수.
  • Sample.h, Sample.cpp DMO 를 이행 하는 CSample 클래스.
  • State.h, State.cpp MPEG 데이터로부터 타임 스탬프를 생성하는 헤르파크라스인, CStreamState 클래스.
  • Stdafx.h, Stdafx.cpp ATL 가 필요로 하는 기본 기능.
  • Util.h, Util.cpp 출력 이미지를 초가하기 위한 유틸리티 기능.

DMO 샘플은, 이하의 리소스 파일도 사용한다.

  • Dmosample.rc: 버젼 정보를 사용해 리소스를 정의해, Sample.rgs 파일에 링크한다.
  • Sample.rgs: 레지스트리 정보를 사용해 텍스트 리소스를 정의한다. ATL 는 이 리소스를 사용해, DLL 의 등록시에 레지스트리 엔트리를 생성 한다.

다음의 주의는, 이행에 대해 상세하게 설명하고 있다.

Dmosample.cpp

이 파일에는, ATL 가 DMO 오브젝트를 생성 해 등록하는데 사용하는 오브젝트 맵이 포함된다. 또, export 되는 DLL 함수도 포함된다. 이러한 함수에는, 엔트리 포인트 함수 (DllMain), 및 COM 에 필요한 함수 (DllCanUnloadNow,DllGetClassObject,DllRegisterServer, 및 DllUnregisterServer)가 있다.

ATL COM AppWizard 는, 이 파일에 포함되는 코드의 대부분을 자동 생성한다. 다음의 2 개가 추가된다.

  • DllRegisterServer 함수는,DMORegister 를 호출해, DMO 에 관한 레지스트리 정보를 추가한다. DMO 는 DMOCATEGORY_VIDEO_DECODER 카테고리에 등록된다.
  • DllUnregisterServer 함수는 DMOUnregister 를 호출한다.

Resource.h

이 헤더 파일로 선언되는 1 개의 정수 IDR_SAMPLE 는, ATL 의 자동 등록 메카니즘으로 사용된다. 정수 IDR_SAMPLE 는, 텍스트 리소스를 식별한다. 이것은 리소스 파일 Sample.rgs 로 정의되어 리소스 파일 Dmosample.rc 에 의해 임포트 된다. 헤더 파일 Sample.h 에는, 다음의 행이 있다.

DECLARE_REGISTRY_RESOURCEID(IDR_SAMPLE)

이것에 의해, ATL 는 IDR_SAMPLE 리소스에 선언된 등록 정보를 사용할 수 있다.

Sample.h

DEFINE_GUID 매크로는, DMO 의 클래스 식별자 (CLSID)를 선언한다.

CSample 클래스는 다음의 클래스로부터 파생한다.

  • IMediaObjectImpl . DMO base class. 템플릿 파라미터는, DMO 가 1 개의 입력 스트림과 2 개의 출력 스트림을 가지는 것을 지정한다.
  • CComObjectRootEx. thread 모델을 선언하는 ATL 클래스. 템플릿 파라미터 CComMultiThreadModel 는, thread 대응 오브젝트를 생성 해,Lock 메소드와 Unlock 메소드를 제공한다.
  • CComCoClass. 표준 COM 오브젝트를 선언하는 ATL 클래스.

CSample 는, 커스텀 마샬링을 실행하는 후리스렛드마샤라오브제크트를 모은다. COM 라이브러리가, 샘플 프로세스내의 복수의 thread에 걸쳐 CSample 포인터를 마샬링 하는 경우, 완전히 같은 포인터가 돌려주어진다. COM 라이브러리가 복수의 프로세스 또는 복수의 머신에 걸쳐 오브젝트를 마샬링 하려고 하면(자), 에러가 발생한다. ATL 는, 후리스렛드마샤라를 집성 하기 위해서 필요한 모든 코드를 추가한다. 이 코드는,FinalConstruct 메소드와 FinalRelease 메소드에 나타난다. COM 맵내의 COM_INTERFACE_ENTRY_AGGREGATE 엔트리는, 후리스렛드마샤라에 IMarshal 인터페이스를 위임한다.

CSample 클래스는, 다음의 멤버 변수를 선언한다.

m_pUnkMarshaler | 후리스렛드마샤라오브제크트에의 포인터.
m_pBuffer | 입력 버퍼에의 포인터. DMO 는 모든 입력을 처리할 때까지, 버퍼의 참조 카운트를 보관 유지한다.
m_pbData | 입력 버퍼내의 다음의 바이트에의 포인터.
m_cbData | 미처리의 바이트수.
m_rtFrame | 마지막 출력 프레임의 타임 스탬프.
m_StreamState | MPEG 데이터를 해석하는, CStreamState 헤르파크라스의 인스턴스.
m_bPicture | DMO 가 출력하는 픽쳐 정보를 가지고 있을지 어떨지를 나타내는, 불형 플래그.

Sample.cpp

이 파일은, CSample 클래스에 메소드를 이행 한다.

InternalGetInputStreamInfo

DMO 는, 임의의 바운다리에 정렬된 임의의 바이트수를 처리할 수 있으므로, 이 메소드는 제로 플래그를 돌려준다.

InternalGetOutputStreamInfo

최초의 출력 스트림은, 고정 사이즈의 샘플 전체를 한 번에 생성 한다. 이것은, 비디오 디코더로 자주(잘) 행해진다. 2 번째의 출력 스트림은 옵션이다. 돌려주어지는 플래그는, 이러한 속성을 나타낸다.

InternalCheckInputType

입력 타입은, FORMAT_MPEGVide 포맷 타입의 MPEG-1 비디오 유료 하중이 아니면 안된다. 입력 타입의 설정 후, 메소드는 포맷의 변경을 받아들이지 않는다.

InternalCheckOutputType

이 메소드는, 출력 포맷을 검증한다. 출력 스트림은 다음의 2 개이다.

  • 스트림 0. 이 스트림으로 지원 되는 유일한 미디어 타입은 RGB-565 이다. 실제의 비디오 디코더는 보통, 복수의 포맷을 지원 한다. 또, 출력의 frame size는, 입력의 frame size와 일치해야 한다. 이것은, 실제의 비디오 디코더가 많게 들어맞는다. 이 스트림은, 입력 타입이 설정되지 않으면 설정할 수 없다.
  • 스트림 1. 미디어 타입은 MEDIATYPE_Text 가 아니면 안된다.

타입의 설정 후, 새로운 타입이 현재의 타입에 일치하지 않는 경우, 메소드는 실패한다. DMO 가 스트리밍중으로 포맷 변경을 처리할 수 없는 경우는, 같은 코드를 포함할 필요가 있다. 실제, 샘플 DMO 는, 1 번에 1 개의 출력 프레임을 생성하므로, 포맷 변경을 용이하게 받아들일 수가 있다.

InternalGetInputType

이 메소드는, 타입을 돌려주지 않는다. 이 때문에, 모든 인덱스값이 범위외가 되어, 반환값은 DMO_E_NO_MORE_ITEMS 이다. 상세한 것에 대하여는, 「IMediaObject::GetInputType 」를 참조할것.

InternalGetOutputType

입력 타입이 설정되어 있지 않은 경우, 이 메소드는 타입을 돌려주지 않는다. 설정되어 있는 경우, 각 스트림에 1 개의 타입이 돌려주어진다. 스트림 0 의 경우, 입력 사이즈에 동일한 frame size의 RGB-565 가 돌려주어진다. 스트림 1 의 경우, MEDIATYPE_Text 가 돌려주어진다.

InternalGetInputSizeInfo

입력 스트림의 최소 버퍼 사이즈는 1 바이트이며, 정렬 요건은 없다. 스트림은룩 어해드를 실행하지 않는다.

InternalGetOutputSizeInfo

스트림 0 의 경우, 버퍼는 출력 샘플을 보관 유지할 수 있는 사이즈가 필요하다. 스트림 1 의 경우, 버퍼는 타임 스탬프 첨부의 텍스트 캐릭터 라인을 보관 유지할 수 있는 사이즈가 필요하다.

InternalFlush

이 메소드는, m_pBuffer (ATL 스마트 포인터)를 NULL 로 설정하는 것으로, 입력 버퍼를 해방한다. 또, CStreamState 오브젝트를 리셋 하는 InternalDiscontinuity 메소드도 호출한다.

InternalProcessInput

이 메소드는, 가능한 한 많은 입력 데이터를 처리한다. 처리는 다음의 순서로 실행된다.

  • Calls IMediaBuffer::GetBufferAndLength 메소드를 호출해, 입력 데이터에의 포인터와 입력 데이터의 사이즈를 취득한다.
  • 입력 버퍼에의 참조 카운트를 보관 유지한다. m_pBuffer 변수는, ATL 스마트 포인터이므로, 이 변수에 값을 설정 하면,IUnknown::AddRef 메소드를 호출하는 효과를 가진다.
  • 타임 스탬프를 CStreamState 오브젝트에 건네준다. 샘플에 타임 스탬프가 없는 경우는, 값 INVALID_TIME 를 사용한다.
  • 프로세스헤르파메솟드를 호출해, 데이터를 처리한다.

InternalProcessOutput

출력하는 데이터가 없는 경우, 이 메소드는 S_FALSE 를 돌려준다. 데이터가 있는 경우, 출력 데이터를 생성한다. 스트림 0 의 경우, 다음의 순서로 실행된다.

  • 출력 버퍼가 출력 데이터를 보관 유지하는데 충분한 사이즈인 것을 확인한다. 없는 경우, 메소드는 에러를 돌려준다.
  • OurFillRect 메소드를 호출해, 배경을 드로잉(Drawing) 해, DrawOurText 메소드를 호출해, 텍스트를 드로잉(Drawing) 한다.
  • 타임 스탬프를 설정한다. 이 프레임에 유효한 타임 스탬프가 있는 경우는, 그것을 사용한다. 없는 경우는, 전의 타임 스탬프를 평균 frame rate로 인크리먼트(increment) 한다.
  • Process 메소드를 다시 호출해, 입력 버퍼에 남아 있으면 모든 데이터를 처리한다. 이것에 의해 출력 데이터가 증가했을 경우, DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE 플래그를 설정한다.

스트림 1 은 옵션이므로, 호출측은 스트림 1 용의 버퍼를 할당하지 않은 것이 있다. 스트림 1 에 출력 버퍼가 없다고 해도, DMO 는 타임 코드를 텍스트 캐릭터 라인으로서 기입한다. 타임 스탬프와 처리 플래그는 스트림 0 의 것을 참조한다.

InternalAcceptingInput

DMO 에 전의 입력 버퍼의 참조 카운트가 아직 있는 경우, DMO 는 그 이상의 입력을 받아들이지 않는다.

Process

이 프라이빗 메소드는, CStreamState 오브젝트를 갱신하면서, 입력 데이터를 1 번에 1 바이트씩 순서에 처리한다. 입력 데이터를 처리 끝마치기까지 CStreamState 오브젝트가 피크체바운다리를 찾아내면(자), Process 메소드는 S_OK 를 돌려준다. 피크체바운다리가 없는 경우는, S_FALSE 를 돌려준다.


가굴 DMO 샘플

설명

이 샘플은 Microsoft® DirectShow® 가그르피르타 샘플과 같은 가그르에페크트를 생성하는 Microsoft® DirectX® Media Object (DMO)의 샘플이다.

이 샘플은 다음의 인터페이스의 이행 방법을 데먼스트레이션 한다 :

  • IMediaObject
  • IMediaObjectInPlace
  • IMediaParamInfo
  • IMediaParams

패스

소스: (SDK 루트)\Samples\Multimedia\DirectShow\DMO\GargleDMO

유저 가이드

이 DMO 를 사용하려면 , Gargle.dll 를 빌드 해 등록하는 것. 샘플 프로젝트는 몇개의 내부 라이브러리를 빌드 한다. Microsoft® Visual Studio® 로 DLL 를 빌드 하려면 ,[빌드] 메뉴로부터 [배치 빌드] 를 선택하는 것.

DMO 데모 샘플 어플리케이션의 DMO 를 사용할 수 있다, 혹은 DirectShow GraphEdit 유틸리티를 사용해 DMO 를 사용할 수도 있다. GraphEdit 는 자동적으로 DMO 를 DMO 래퍼 필터로 랩 한다.

SDK 에 들어가 있는 Microsoft® DirectMusic® Producer 어플리케이션을 포함한 Microsoft® DirectMusic® 어플리케이션으로 DMO 를 사용할 수도 있다. DirectMusic Producer 에서는, Audiopath 데자이나를 사용해 DMO 를 오디오 패스에 삽입한다. 미디어 파라미터를 컨트롤 하려면 , Parameter Control 트럭을 사용한다. 트럭에 커브를 삽입해, 그것을 할당 해 DMO 의 임의의 파라미터를 컨트롤 한다. 자세한 것은, DirectMusic Producer 어플리케이션 헬프의 Audiopath Designer 와 Parameter Control Track 를 참조할것.

가굴 DMO 는 조작하고 있는 파형의 형상 (직사각형파 혹은 삼각파)과 주파수를 유저가 설정한다. 그러한 프로퍼티를 설정하는 커스텀 인터페이스 IGargleDMOSample 도 지원 한다.

프로그래밍의 주의

가굴 DMO 샘플은 Active Template Library (ATL)로 빌드 된다. 원시 코드는 3 개의 라이브러리에 정리되고 있다 :

ControlBase 라이브러리

  • Controlhelp.h, Controlhelp.cpp: 유저 인터페이스 컨트롤용의 헬퍼 라이브러리, 프로퍼티 페이지에 의해 사용된다.

GargleDMO 라이브러리

  • Gargle.h, Gargle.cpp: 가굴 DMO 의 이행,IMediaObjectInPlace 인터페이스와 커스텀 IGargleDMOSample 인터페이스를 포함한다.
  • GargleDMO.cpp: DllGetClassObject 와 같은 COM 라이브러리에 필요한 DLL 엔트리 포인트 함수와 DLL 함수.
  • GargleDMO.def: COM 라이브러리에 필요한 DLL 함수를 공개.
  • GargleDMOProp.h, GargleDMOProp.cpp: 프로퍼티 페이지의 이행. 프로퍼티 페이지는 ATL 의 IPropertyPageImpl 클래스 템플릿을 사용한다.
  • IGargle.h: IGargleDMOSample 인터페이스를 선언한다.
  • Resource.h: 리소스 정수.
  • Stdafx.h, Stdafx.cpp: ATL 가 요구하는 기본 함수.

MedParamBase 라이브러리

  • Alist.h, Alist.cpp: 단순한 링크 리스트 클래스.
  • Param.h, Param.cpp: CParamsManager 클래스가 들어가는, 이것은 미디어 파라미터의 IMediaParams 인터페이스와 IMediaParamInfo 인터페이스를 이행 한다.

가굴 DMO 는 IMediaObjectImpl base class를 사용하지 않는다. IMediaObjectImpl 가 옮겨진 낡은 DMO base class를 사용한다.

IMediaObjectImpl 클래스에서는 다음의 개선이 되고 있다 :

  • 보다 좋은 파라미터 체크의 이행.
  • 보다 엄격한 calling sequence.
  • IMediaObject::AllocateStreamingResources 메소드내의 스트리밍 리소스 초기화에, 보다 심플한 모델을 제공.

장래의 릴리스에서는, 가굴 DMO 는 IMediaObjectImpl 를 사용해 고쳐 써진다.


샘플 DVD 어플리케이션

Microsoft® DirectShow® SDK 에는 이하의 샘플 DVD 어플리케이션이 포함되어 있다.

C++ 어플리케이션

  • DVD 샘플

Microsoft® Visual Basic® 어플리케이션

  • WebDVD 샘플


DVD 샘플

설명

DVDSample 는, C++ DVD 어플리케이션이다. 이 샘플에서는, 기본적인 모든 재생 기능과 네비게이션 기능을 시작해 페어 렌탈 락 레벨, 북마크, 가라오케, 커멘드의 동기 등, 고도의 기능에 대해서도 나타난다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\DVD\DVDSample

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DirectShow\Bin\DVDSample.exe


WebDVD 샘플

설명

단순한 Microsoft® Visual Basic® DVD 어플리케이션.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DirectShow\WebDVD

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DirectShow\Bin\VB_WebDVDSample.exe

유저 가이드

WebDVD 샘플에서는,MSWebDVD Active X® 컨트롤을 사용해, DVD 비디오 재생과 네비게이션의 모든 기능을 실행할 방법이 나타난다.

Play 메소드를 호출해 재생을 시작 할 수 있다. 재생 후는, 다음의 메소드를 사용해 재생의 패스 또는 동작을 변경할 수 있다.

  • Stop Stop : 재생을 정지한다.
  • Eject : 드라이브로부터 DVD 디스크를 꺼낸다.
  • Pause : 목적의 시간만 재생을 포즈 한다.
  • ActivateButton : 현재 선택된 버튼을 유효하게 한다. 버튼은, 다음의 방법으로 선택할 수 있다.
    • 버튼 위에 마우스를 이동해, 반전 표시되는 것을 기다린다. 그 때문에(위해)는,DisableAutoMouseProcessing 프로퍼티를 FALSE (디폴트)로 설정할 필요가 있다.
    • SelectAtPosition ,SelectLeftButton ,SelectRightButton ,SelectLowerButton , 혹은 SelectUpperButton 를 호출한다.
  • PlayNextChapter : 현재의 타이틀내의 다음의 쳅터를 재생한다.
  • PlayPrevChapter : 현재의 타이틀내의 앞의 장을 재생한다.

ShowMenu 메소드를 사용하면(자), DVD 디스크에 존재할 가능성이 있는, 다음의 6 개의 메뉴를 표시할 수 있다.

  • 타이틀
  • 루트
  • 서브 픽쳐
  • 오디오
  • 앵글
  • 쳅터

메뉴가 존재하지 않는 경우는, 지정된 메뉴가 존재하지 않는 것을 나타내는 에러가 표시된다.

클립 된 비디오 디스플레이의 사이즈는 GetClipVideoRect 메소드를 통해 변경 가능하다. 네이티브 비디오의 사이즈는 변경할 수 없다.


샘플 DirectShow 필터

Microsoft® DirectShow® SDK 에는, 이하의 샘플 필터가 포함되어 있다.

  • Async 필터 샘플
  • 볼 필터 샘플
  • 콘트라스트 필터 샘플
  • 덤프 필터 샘플
  • EZRGB24 필터 샘플
  • 가그르피르타산풀
  • InfTee 필터 샘플
  • NullIP 필터 샘플
  • NullNull 필터 샘플
  • SampVid 필터 샘플
  • 스코프 필터 샘플
  • Synth 필터 샘플
  • TextOut 필터 샘플
  • WavDest 필터 샘플


Async 필터 샘플

설명

단계적인 다운로드를 지원 하는 파일 리더 필터. 이 샘플 필터는,IAsyncReader 및 IFileSourceFilter 인터페이스를 이행 한다. MPEG 파일은 지원 하고 있지만, AVI 파일은 지원 하고 있지 않다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\Async

유저 가이드

이 샘플에는, 필터의 데모를 실시하는 작은 커멘드 라인 어플리케이션 Memfile.exe 가 포함되어 있다. 커멘드 라인의 인수로서 미디어 파일 및 bit rate (단위는 Kbps)를 지정한다. 어플리케이션은, 지정된 레이트로 메모리에 파일을 읽어들여 재생한다. 이 작업을 실시하기 위해서(때문에), 어플리케이션은 필터의 인스턴스를 생성 해, 필터 그래프에 필터를 추가해, 필터의 출력 핀을 렌더링 한다.

사용법 :

Memfile 파일명 bit rate

Async 샘플 필터는,AVI 스플리터 필터에 접속할 수 없기 때문에, AVI 파일을 지원 하고 있지 않다. Async 필터의 출력 핀은, MEDIATYPE_Stream 과 그 미디어 타입의 MEDIASUBTYPE_NULL 를 조회한다. AVI 스플리터 필터의 입력 핀은, MEDIASUBTYPE_NULL 를 받아들이지 못하고, 어느 타입도 출력하지 않는다. 그 때문에, 핀의 접속은 실패한다. Async 필터는, 필요한 경우에 MEDIASUBTYPE_Avi 를 제공하도록(듯이) 강화할 수 있다. 예를 들어, 파일 포맷을 조사하거나 파일 확장을 사용하는 등이다.


볼 필터 샘플

설명

(은)는 두응으로 있는 볼의 이미지를 생성하는 비디오 소스 필터. 이 샘플은, 포맷 네고시에이션, 및 소스 필터 base class의 CSource 와 CSourceStream 의 사용법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\Ball

유저 가이드

Fball.h 및 Fball.cpp 의 코드는, 필터 인터페이스를 관리한다. 이것들 2 개의 파일에는, 소스 필터에 필요한 거의 최소한의 코드가 포함되어 있다. Ball.h 및 Ball.cpp 파일에는, 볼을 다투는 코드가 포함되어 있다.

이 필터에는 출력 핀이 1 개 있어, 프레임내에서는도는 볼을 표시하는 비디오 스트림을 출력한다. 볼 필터는, 다운 스트림 그래프로부터의 품질관리 요구의 수락도 실시하지만, 이것은 단순한 품질관리의 방법을 나타내는 것이다. 이 필터는, 품질관리를 위한 IQualityControl 인터페이스를 이행 한다.


콘트라스트 필터 샘플

설명

콘트라스트 이펙트를 이행 하는 비디오 변환 필터. 이 샘플은, 간단한 커스텀 인터페이스의 정의 및 이행의 방법을 나타낸다. 또,CTransformFilter 클래스를 사용해 간단한 이펙트 필터를 이행 하는 방법의 데모도 실시한다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\Contrast

유저 가이드

콘트라스트 필터는, 간단한 변환 필터이며, 필터를 통과하는 비디오 스트림의 콘트라스트를 조정한다. 이 필터는, 콘트라스트를 조정하기 위한 커스텀 인터페이스를 제공한다. 또, 콘트라스트 필터는 CBasePropertyPage 클래스를 사용해, 유저 인터페이스를 가지지 않는 어플리케이션을 위한 프로퍼티 페이지도 제공한다.

콘트라스트 필터는, 팔레트에 의한 트릭으로 콘트라스트를 조정한다. 이미지의 칼라 팔레트에 의해, 이미지가 어떻게 표시될까를 효과적으로 결정할 수 있다. 팔레트를 변경하는 것으로써, 필터는 이미지 픽셀 자체를 변경하지 않고 로 콘트라스트를 변경할 수 있다.


덤프 필터 샘플

설명

받은 미디어 샘플을 텍스트 파일에 기입하는 렌더링 필터

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\Dump

유저 가이드

이 샘플은, 베이스 필터 클래스 CBaseFilter 및 렌더링 된 입력 핑크 라스 CRenderedInputPin 의 사용법을 나타낸다. 또,IFileSinkFilter 인터페이스도 사용한다. 덤프 필터는, 렌더링 된 입력 핑크 라스의 Receive 메소드를 오버라이드(override) 해 실제의 미디어 샘플을 처리하는 방법의 데모를 실시한다. 덤프 필터는, 그 입력 핀에 대한 CDumpInputPin::EndOfStream 의 호출을 받으면(자), 필터 그래프에 EC_COMPLETE 통지를 보낸다.

이 필터는, 편리한 디버그 툴이다. 예를 들어, 변환 필터의 결과를 비트 마다 확인할 수 있다. GraphEdit 를 사용해 수동으로 그래프를 생성 해, 변환 필터의 출력이나 그 외의 출력 핀에 덤프 필터를 접속할 수가 있다. 티피르타의 접속에서는, 티피르타의 1 개의 핀에 덤프 필터를 접속해, 이제(벌써) 1 개의 핀에 표준적인 출력을 접속해, 리얼타임 시나리오에 있어서의 결과를 감시할 수도 있다.

덤프 필터에는 입력 핀이 1 개 있어, 이것은 파일에 덤프 된다. 덤프 필터는, 인스턴스화 될 때 유저에게 파일명의 입력을 요구해 해방되면(자) 파일을 닫는다.


EZRGB24 필터 샘플

설명

이미지 처리 필터. 이 필터는, 적, 록, 청, 암색화, XOR, 애매하게 해, 회색, 앰보스 등, 개별의 비디오 이펙트를 다수 생성 한다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\EZRGB24

유저 가이드

이 샘플은,CTransformFilter ,CPersistStream ,CBasePropertyPage 등, Microsoft® DirectShow® 클래스의 사용법을 몇개인가 가리킨다.


가그르피르타산풀

설명

오디오 이펙트 필터.

가그르피르타는, 필터를 통과하는 파형에 필터내에서 수학적으로 생성되는 파형을 거는 것으로, 통과하는 파형을 변조한다. 디폴트의 변조파형은 삼각파이다. 프로퍼티 시트에는, 방형파라고 하는 선택사항도 있다. 변조파형의 주파수는, 필터의 프로퍼티 시트에 대해 설정할 수 있다. 주파수가 낮은 경우, 이펙트는 트레몰로와 같은 소리가 된다. 주파수가 높은 경우, 필터는 원의 사운드에 추가의 주파수를 생성해, 이펙트는 뒤틀림과 같은 소리가 된다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\Gargle


InfTee 필터 샘플

설명

인피닛트핀티피르타. 이 필터에는 입력 핀이 1 개로 수가 동적인 출력 핀이 포함되어 있다. 필터에 보내지는 데이터 샘플은 모두, 모든 패스에 동시에 전달된다. 이것에 의해, 입력은 복수의 출력 스트림에 접속된다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\InfTee

유저 가이드

필터는, 모든 출력 핀에 같은 데이터를 보낸다. 따라서, 출력 핀은 접속중에 같은 미디어 타입에 네고시에이트 하고 있지 않으면 안 된다. 인피닛트핀티피르타는, 같은 미디어 타입을 사용했을 경우에 입력 핀과 양쪽 모두의 출력 핀이 집합하도록(듯이) 이 네고시에이션을 처리한다. 적절한 미디어 타입이 발견되지 않는 경우, 접속은 거부된다.

필터는 항상, 지정된 allocater를 사용한다. allocater를 지정하는 것은, 데이터를 제공하는 필터이다. 입력 핀에 도착하는 데이터는, 출력 핀에 보내질 때까지 카피되지 않는다. 또, 필터는, 데이터가 다운 스트림 필터에 확실히 출력되도록(듯이) 해, 양쪽 모두의 출력이 적시에 서비스를 받는 것을 보증한다. 특히, 출력의 1 개가 COutputQueue::Receive 멤버 함수에 대해 블록 될 가능성이 있는 경우, 티는 샘플을 송신하는 thread를 스핀오프 한다. 샘플을 송신하는 thread가 없는 경우는, 티 입력 핀에 샘플을 송신하는 thread가 다운 스트림 필터에 데이터를 건네준다. 그 시점에서 블록 되면(자), 한편의 다운 스트림 필터에는 장시간에 걸쳐서 데이터가 송신되지 않는다.


NullIP 필터 샘플

설명

Null 인플레이션 의자 변환 필터. 이 샘플 변환 필터는, 데이터를 변경하지 않고 , 입력 핀으로부터의 데이터를 모두 출력 핀에 건네준다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\NullIP


NullNull 필터 샘플

설명

최소 Null 필터. 이 샘플 변환 필터는, 가능한 한 가장 간단한 필터를 나타낸다. 이 필터가 지원 하는 기능은 없다.

패스

소스 :(SDK 루트)\Samples\Multimedia\DirectShow\Filters\NullNull


SampVid 필터 샘플

설명

샘플 비디오 렌더링 필터

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\SampVid


스코프 필터 샘플

설명

사운드 데이터를 파형으로 표시하는 렌더링 필터

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\Scope

유저 가이드

이 필터를 사용하려면 , GraphEdit 를 열어 오디오 파일 (또는, 오디오 스트림을 포함한 비디오 파일)을 렌더링 한다. 오디오 렌더러의 접속을 일시적으로 해제해, 인피닛트핀티 (InfTee ) 샘플 필터를 삽입하면(자), 오디오 렌더러를 재차 접속한다. 계속되어, 인피닛트핀티피르타의 2 개째의 출력 핀을 스코프 필터에 접속한다. 이 상태로, 그래프를 실행한다.

스코프 윈도우는, 실제의 윈도우는 아니고 다이알로그 박스로서 이행 된다. 필터 파라미터를 리얼타임에 변경하기 위한 컨트롤 패널을 생성 하는 개발자는, 프로퍼티 페이지 대신에 이러한 기술을 이용할 수 있다.

스코프 필터는, 데이터 처리용으로별 thread를 설정하는 방법을 나타낸다. 이 경우, 데이터는 단지 IMemInputPin::Receive 메소드의 버퍼에 카피된 후, 별thread의 스코프 윈도우상에 표시된다.

스코프 필터로 오디오 출력을 감시해, 클리핑이 일어나고 있는지 어떤지를 확인해, 게인을 조정할 수도 있다.

이 필터는, GraphEdit 에 "오실로스코프(oscilloscope) " 로서 표시된다.


Synth 필터 샘플

설명

오디오 파형을 생성하는 소스 필터.

이 필터는 동적 그래프 생성 을 데먼스트레이션 한다. 비압축 PCM 오디오와 압축 MS_ADPCM (Microsoft Adaptive Delta Pulse Code Modulation) 포맷간에 스윗치 가능하다.

이 필터는 GraphEdit 내에서 "Audio Synthesizer Filter" 로서 표시된다.

패스

소스: (SDK root)\Samples\Multimedia\DirectShow\Filters\Synth

유저 가이드

Synth 필터를 사용하면(자), 유저는 파형, 주파수, 채널수, 그 외의 프로퍼티를 프로퍼티 페이지를 통해 설정할 수가 있다. 스위프 주파수 레인지의 상하의 엔드 포인트를 설정하려면 , 쉬프트를 눌러 주파수 슬라이더를 조정하는 것. 이 필터는 이러한 프로퍼티 설정에 커스텀 인터페이스 ISynth2 도 지원 한다.

동적 그래프 생성 기능을 데먼스트레이션 하려면 , 다음과 같이 하는 것 :

  1. 필터를 구축해, 그것을 Regsvr32 유틸리티로 등록한다.
  2. GraphEdit 를 시작 한다.
  3. Audio Synthesizer 필터를 삽입한다. 그것은 DirectShow 필터 카테고리를 표시한다.
  4. 필터의 출력 핀을 렌더링 한다.
  5. Play 버튼을 클릭한다.
  6. 필터의 프로퍼티 페이지를 연다.
  7. Output Format 에리어에서,PCM 나 Microsoft ADPCM 를 선택한다.

프로그래밍의 주의

이 샘플은 이하의 파일을 포함한다 :

  • Dynsrc.h, Dynsrc.cpp: 동적 그래프 생성을 지원 하는 소스 필터의 2 개의 base class CDynamicSource 와 CDynamicSourceStream 가 들어간다.
  • ISynth.h: 필터로 프로퍼티를 설정하는 커스텀 ISynth2 인터페이스의 선언.
  • Resource.h: 리소스 정수가 들어간다.
  • Synth.def: COM 라이브러리가 필요로 하는 DLL 함수를 공개한다.
  • Synth.h, Synth.cpp: 오디오 데이터를 생성하는 CAudioSynth 클래스와 필터를 이행 하는 CSynthFilter 클래스가 들어간다.
  • Synth.rc: 필터가 사용하는 리소스가 들어간다.
  • Synthprp.h, Synthprp.cpp: 필터의 프로퍼티 페이지의 이행.

CDynamicSource 클래스는 CSource base class로부터 적용되고 있다. 그것은 CDynamicSourceStream 로부터 파생된 1 개(살) 이상의 출력 핀을 사용한다. CDynamicSourceStream 클래스는 CSourceStream 로부터 적용되고 있지만,CBaseOutputPin 클래스는 아니고,CDynamicOutputPin 클래스로부터 파생한다.

CDynamicSource 클래스는 CSource 에는 없는 이하의 메소드를 가진다 :

  • Stop: 스톱 이벤트 (CDynamicOutputPin.m_hStopEvent )를 알려 접속되어 있지 않은 모든 핀의 워커 thread를 슛다운 한다. 접속되고 있는 핀에서는, 핀의 비액티브한 메소드가 그 워커 thread를 슛다운 한다.
  • Pause: 스톱 이벤트의 리셋.
  • JoinFilterGraph: 각 핀으로 CDynamicOutputPin::SetConfigInfo 메소드를 호출한다.

CDynamicSourceStream 클래스는 CSourceStream 에는 없는 다음의 메소드를 가진다 :

  • DestroySourceThread: 워커 thread를 슛다운 한다.
  • FatalError: 필터 그래프 매니저에 에러를 알린다.
  • OutputPinNeedsToBeReconnected: 출력 핀이 재접속해야 하는 것이다고 알린다. 이 메소드가 불려 가면(자), 워커 thread는 CDynamicOutputPin::DynamicReconnect 메소드를 호출해 핀을 재접속한다.


TextOut 필터 샘플

설명

텍스트 데이터를 표시하는 렌더링 필터

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\TextOut


WavDest 필터 샘플

설명

WAV 파일에 오디오 스트림을 기입한다. 입력으로서 오디오 스트림을 1 개 취득한다. 또, 출력 핀은 파일 라이터 필터에 접속해야 한다. 이 샘플 필터는,CTransformFilter 클래스에 근거하고 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Filters\WavDest


DirectShow 의 그 외의 샘플

Microsoft® DirectShow® SDK 에는, 그 밖에도 다음의 샘플이 포함되어 있다.

C++ 어플리케이션

  • ASFCopy 샘플
  • SysEnum 샘플

Microsoft® Visual Basic® 어플리케이션

  • 빌더 샘플


ASFCopy 샘플

설명

1 개(살) 이상의 파일을 1 개의 ASF 파일로 한다.

패스

소스: (SDK root)\Samples\Multimedia\DirectShow\Misc\ASFCopy

유저 가이드

이 샘플을 빌드 하려면 , Microsoft® Windows Media™ Format SDK 를 인스톨 해 소프트웨어 인증을 받지 않으면 안 된다. 소프트웨어 인증을 받은 다음에, 2 개의 추가 라이브러리 (WMStub.lib 와 WMVCore.lib)를 링크해, 샘플을 빌드 하는 것.

사용 방법:

ASFCopy [/v] /p profile file1 [file2 ...] target

다음의 커멘드 라인 스윗치가 지원 되고 있다.

스윗치 | 설명
/p | 프로파일수를 지정한다.
/v | 장황 모드.

/p 스윗치를 사용해 ASF 프로파일을 지정하는 것. 이 스윗치를 생략 하면, ASFCopy 는 표준 시스템 프로파일의 리스트를 표시한다.

1 개(살) 이상의 원시 파일과 타겟 파일명을 지정하는 것. 1 개(살) 위에의 원시 파일을 지정 하면, 어플리케이션은 모든 원시 파일을 멀티플렉스 한다. 원시 파일에 포함되어 있는 스트림에 성냥 하는 프로파일을 지정해야 하는, 그렇게 하지 않으면 어플리케이션은 올바르게 동작하지 않는다. 예를 들어, Video for Web Servers (56 Kbps)를 지정하면(자), 결합되는 원시 파일은 실제로 1 개의 비디오 스트림과 1 개의 오디오 스트림을 가지고 있지 않으면 안 된다.

참조

Windows Media 어플리케이션


SysEnum 샘플

설명

디바이스의 열거를 위해서(때문에),시스템 디바이스 열거자의 사용법을 나타낸다. 상세한 것에 대하여는, 「디바이스와 필터의 열거」를 참조할것.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Misc\SysEnum

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DirectShow\Bin\SysEnum.exe


빌더 샘플

설명

Microsoft® Visual Basic® 의 그래프 빌더 어플리케이션.

이 샘플 어플리케이션은 Visual Basic 로 커스텀 필터 그래프를 구축하는 방법을 데먼스트레이션 한다.

패스

소스: (SDK root)Samples\Multimedia\VBSamples\DirectShow\Builder


샘플 플레이어 어플리케이션

Microsoft® DirectShow® SDK 에는, 이하의 샘플 플레이어 어플리케이션이 포함된다.

  • BGMusic 샘플
  • CutScene 샘플
  • Jukebox 샘플
  • PlayWnd 샘플
  • 텍스쳐 3D 샘플

Microsoft® Visual Basic® Applications

  • VBDemo 샘플


BGMusic 샘플

설명

일련의 오디오 파일을 차례로 재생하는 재생 어플리케이션.

이 샘플은, 필터 그래프내에서 소스 필터를 바꿔 넣는 방법을 나타낸다. 어플리케이션이 기동 하면, 순서의 선두에 위치하는 오디오 파일이 렌더링 되어 타이머가 설정된다. 타이머가 끊어지면(자), 어플리케이션은 소스 필터를 삭제해, 다음의 파일에 대한 소스 필터로 옮겨놓는다. 이러한 파일은 모두 같은 타입이기 (위해)때문에, 그래프 전체를 재생성 할 필요는 없다.

패스

소스 : (SDK root)\Samples\Multimedia\DirectShow\Players\BGMusic

실행 가능 파일 : (SDK root)\Samples\Multimedia\DirectShow\Bin\BGNusic.exe


CutScene 샘플

설명

유저가 ESC 키, ENTER 키, 또는 SPACE 키를 누를 때까지, 풀 스크린 모드로 비디오 파일을 재생한다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Players\CutScene

유저 가이드

이 샘플은 커멘드 라인으로부터 실행해, 인수로서 비디오 파일의 이름을 지정한다.


Jukebox 샘플

설명

비디오 쥬크박스 어플리케이션.

이 어플리케이션은, 디렉토리에서 미디어 파일을 주사 해, 파일명의 일람을 표시한다. 유저는 개별의 파일을 재생하거나 모든 파일을 순서에 재생하거나 할 수 있다. Jukebox 에는, 생성 하는 필터 그래프에 관한 정보도 표시된다. 이것에는, 필터의 이름, 핀의 이름, 및 생성되는 이벤트 코드가 포함된다.

주 이 샘플에는 Microsoft Foundation Class Library 4.2 (Mfc42.dll)가 필요하다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Players\Jukebox

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DirectShow\Bin\Jukebox.exe

유저 가이드

디렉토리명이 커멘드 라인 인수로서 지정되면(자), Jukebox 는 기동시에 그 디렉토리를 주사 한다. 그 이외의 경우는, SDK 루트 디렉토리 이하의 Samples\Multimedia\Media 에 있는, 디폴트의 SDK 미디어 디렉토리를 주사 한다. Jukebox 에서는, 디렉토리의 모든 미디어 파일 일람이 표시되므로, 유저는 일람으로부터 재생하는 파일을 선택할 수 있다.

Jukebox 에서는, 다음의 유저 인터페이스 요소가 제공된다.

  • [Play],[Stop],[Pause], 및 [FrameStep] 버튼 : 이러한 버튼을 사용해, 그래프의 재생을 제어한다. 그래프가 IVideoFrameStep 를 지원 하지 않는 경우,[FrameStep] 버튼은 무효가 되어 있는 일이 있다.
  • [Thru] 및 [Loop] 버튼 : [Thru] 를 클릭 하면, 현재 선택되고 있는 파일로부터, 파일의 일람 전체가 재생된다. [Loop] 를 클릭 하면, 같은 파일이 반복해 재생된다. 이러한 2 개의 버튼은, 상호 배타적이다.
  • [Mute] 버튼 : 오디오를 뮤트 한다.
  • [Filters],[Input Pins], 및 [Output Pins] : Jukebox 가 그래프를 생성 할 때에, 그래프의 필터 일람을 표시한다. 유저가 필터명의 어느쪽이든을 선택 하면, 필터의 입력 핀과 출력 핀의 일람이 표시된다.
  • [Display Events] : 이 체크 박스를 온으로 하면(자), Jukebox 가 받는 이벤트 코드가 표시된다. 일람을 소거하려면 ,[Clear] 를 클릭한다.
  • [Properties] 버튼 : 필터의 프로퍼티 페이지를 표시하려면 , 필터명을 선택해,[Properties] 를 클릭한다. 필터가 프로퍼티 페이지를 지원 하고 있지 않는 경우, 이 버튼은 무효가 된다.


PlayWnd 샘플

설명

간단한 미디어 플레이어 어플리케이션

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Players\PlayWnd

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DirectShow\Bin\PlayWnd.exe

유저 가이드

재생 파일은, 커멘드 라인의 인수로서 지정할 수 있다. 지정되어 있지 않은 경우, 어플리케이션은 기동시에 Open Media File 다이얼로그를 표시한다. 선택된 파일의 재생이 자동적으로 시작 된다.


텍스쳐 3D 샘플

설명

Microsoft® DirectX® 8.0 의 텍스쳐 표면상에 비디오를 드로잉(Drawing) 한다.

주 : 이 샘플은, 샘플 실행중의 모니터의 표시 프로퍼티의 변경은 지원 하고 있지 않다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Players\Texture3D

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DirectShow\Bin\Texture3D.exe


VBDemo 샘플

설명

Microsoft® Visual Basic® 의 심플한 미디어 플레이어.

패스

소스: (SDK root)Samples\Multimedia\VBSamples\DirectShow\VBDemo


샘플 비디오 편집 어플리케이션

Microsoft® DirectShow® SDK 에는, 비디오 편집에 관련한, 다음의 샘플 어플리케이션이 포함되어 있다 :

C++ 어플리케이션

  • SampGrabCB 샘플
  • StillCap 샘플
  • TimeLine 테스트 샘플
  • XTLTest 샘플

Microsoft® Visual Basic® 어플리케이션

  • DexterVB 샘플
  • SlideShowVB 샘플
  • TrimmerVB 샘플
  • XTLTestVB 샘플


SampGrabCB 샘플

설명

필터 그래프를 통과할 때에, 미디어 샘플에 관한 정보를 표시한다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Editing\SampGrabCB

유저 가이드

이 콘솔 프로그램은,IMediaDet 인터페이스를 사용해,샘플 grabber 필터가 포함된 필터 그래프를 생성 한다. 어플리케이션은, 콜백 함수를 사용해 비디오 파일로부터 샘플을 취득한다.

사용법

SampGrabCB 파일명

다음에 나타내는 것은, 어플리케이션으로부터의 출력예이다.

Sample received = 00000  Clock = 4464847
Sample received = 00001  Clock = 4464848
Sample received = 00002  Clock = 4464849
Sample received = 00003  Clock = 4464850
Sample received = 00004  Clock = 4464853


StillCap 샘플

설명

스티르이메이지를 비트 맵 파일에 기입하는, 비디오 캡춰 어플리케이션.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Editing\StillCap

유저 가이드

이 어플리케이션은,ISampleGrabber 인터페이스를 사용해, 라이브 캡춰 스트림으로부터 비트 맵 파일에 스티르이메이지를 캡춰 한다. 또,샘플 grabber 필터를 필터 그래프에 배치하는 방법과 콜백 함수를 사용해 리얼타임에 샘플 데이터를 취득하는 방법에 대해 가리키고 있다.

이 어플리케이션은, 발견된 최초의 비디오 캡춰 디바이스를 사용해, 캡춰 그래프를 구축한다. 스티르이메이지를 캡춰 하려면 ,[Snap Still] 를 클릭한다. 디폴트에서는, 비트 맵은 StillCap0000.bmp 라고 하는 파일명으로 보존된다. [Increment filename after each capture? ] 체크 박스를 온으로 하면(자), 각 이미지는 새로운 파일명으로 보존된다. 그 이외의 경우는, 새로운 이미지를 캡춰 하면, 이전의 이미지에 오버라이드(override) 된다.

이 어플리케이션은, 비디오 파일도 캡춰 할 수 있다. [Capture Type] 에리어의 [Video Capture] 를 클릭 하면, 비디오 캡춰가 자동적으로 시작 된다. 캡춰 세션을 종료하려면 ,[Start Playback] 를 클릭한다. 기록된 파일은, 자동적으로 재생된다.

간단하게 하기 위한(해), 이 샘플에서는 24 비트 RGB 포맷이 사용된다. 비디오 드라이버가 16 비트색으로 설정되어 있는 경우는, 어플리케이션의 실행중에 플릭커가 발생하는 일이 있다. 이 문제를 해결하려면 , 디스플레이의 비트수를 24 비트 또는 32 비트로 설정한다.


Timeline Test 샘플

설명

이 샘플 어플리케이션은 트란지션을 사용해 타임 라인을 구축한다. Microsoft® DirectShow® 편집 서비스 의 이하의 태스크를 데먼스트레이션 한다 :

  • 타임 라인을 생성 한다.
  • 트럭, 소스, 트란지션, 이펙트를 타임 라인에 추가한다.
  • SMPTE 와이프 트란지션을 생성 한다.
  • 볼륨 포락선 이펙트를 사용해 오디오 크로스페이드를 생성 한다.
  • 타임 라인 오브젝트의 프로퍼티를 설정한다.
  • 타임 라인을 수정해, 필터 그래프를 재차 렌더링 한다.

패스

소스: (SDK 루트)\Samples\Multimedia\DirectShow\Editing\TimelineTest


XTLTest 샘플

설명

비디오 편집 프로젝트의 렌더링과 프리뷰를 위한 커멘드 라인 툴. 이 툴은, Microsoft® DirectShow® 편집 서비스 (DES)의 프로젝트 파일을 렌더링 한다.

이 어플리케이션으로 ASF 지원을 유효하게 하려면 , 프로젝트를 Microsoft® Windows Media™ Format (WMF) SDK 인증에 링크해, 어플리케이션을 컴파일 할 때에 USE_WMF_CERT 를 정의하는 것. 인증의 입수방법에 대해서는, WMF SDK 의 문서를 참조할것.

주 이 어플리케이션에는 Internet Explorer 4.0 이후가 필요하다. 그것이 없으면 어플리케이션은 다음의 에러 메세지를 표시하는 : Unexpected error = Dshow not installed correctly 상세한 것에 대하여는 「IXml2Dex 」를 참조할것.

패스

소스 : (SDK 루트)\Samples\Multimedia\DirectShow\Editing\Xtltest

유저 가이드

이 샘플 어플리케이션에서는, 비디오 편집에 관련하는 다음의 태스크가 나타난다.

  • 타임 라인의 프리뷰와 렌더링 된 출력의 파일에의 기입해
  • 타임 라인을 렌더링 할 때의 타임 라인 옵션의 설정

사용법

xtltest.exe [스윗치] input.xtl

디폴트에서는, 프로젝트는 프리뷰 된다. 다음의 커멘드 라인 스윗치가 지원 되고 있다.

스윗치 | 설명
/C | 클락 없음. 오디오와 비디오를 동기 하지 않고 , 할 수 있는 한 빠르게 프로젝트를 렌더링 한다.
/D | 원시 파일을 동적으로 읽어들인다. 상세한 것에 대하여는, 「IRenderEngine::SetDynamicReconnectLevel 」를 참조할것.
/[double-double] | 렌더링의 시작 타임과 종료 타임을 설정한다. 예를 들어,/[3-4] 라고 지정 하면, 프로젝트의 3 초째부터 시작 해, 타임 라인의 1 초간이 렌더링 된다.
/G filename.grf | GraphEdit 파일을 . grf 포맷으로 출력한다.
/N | 렌더링 없음. 이 프로젝트는 프리뷰 또는 파일에의 렌더링은 행해지지 않는다. 이 옵션은, 입력 파일을 확인하거나 /G 스윗치를 사용할 때에 도움이 된다.
/P [number] | ASF 압축 프로파일을 선택한다. 어플리케이션이 WMF SDK 증명서를 사용해 컴파일 되었을 경우에만 이용할 수 있다.
/P | 이용 가능한 ASF 프로파일을 일람으로 한다. 어플리케이션이 WMF SDK 증명서를 사용해 컴파일 되었을 경우에만 이용할 수 있다.
/R | 스마트재압축을 유효하게 한다. 어플리케이션은, 압축 포맷용으로 타임 라인의 최초의 클립을 사용한다. 이 옵션은, /W 스윗치와 함께 사용한다. 상세한 것에 대하여는, 「렌더링 엔진에 대하며」를 참조할것.
/W filename | 타임 라인을 파일에 렌더링 한다. 이 파일 타입은, 파일의 확장자(extension)에 의해 결정된다. 어플리케이션은, AVI 파일 및 WAV 파일을 지원 한다. 어플리케이션이 WMF SDK 증명서를 사용해 컴파일 되는 경우는, ASF 파일도 지원 한다. 이 옵션에서는, 프리뷰는 억제된다.
/X filename.xtl | 프로젝트를 XML 파일로서 보존한다. 새로운 파일은, 입력 파일과 기능적으로는 같게 되지만, XML 태그가 다른 일이 있다.

프로그래밍의 주의

이 샘플에서는, XML 프로젝트 파일의 독해를 시작해 그 프리뷰 또는 파일에의 출력에 필요한 모든 스텝이 나타난다.

스마트재압축에서는, 어플리케이션은 타임 라인으로 뮤트되어 있지 않은 최초의 소스의 포맷을 사용한다. 최초의 소스가 오디오 파일이라고 실패한다. GetFirstSourceOnTimeline 함수는, 뮤트되어 있지 않은 최초의 소스를 취득한다. 이 함수는, 타임 라인으로 오브젝트를 주사 하는 방법을 나타낸다. GetSourceVideoType 함수는, 소스의 최초의 비디오 소스의 미디어 타입을 취득한다. 어플리케이션은,IAMTimelineGroup::SetSmartRecompressFormat 를 호출해 재압축 포맷을 설정할 때에, 이 미디어 타입을 사용한다. 상세한 것에 대하여는, 「프로젝트의 렌더링」을 참조할것.

에러 로그를 처리하기 위해서, 어플리케이션은 커스텀 클래스 CErrorReporter 를 정의한다. 이 클래스는,IAMErrorLog 인터페이스를 공개한다. 그러나, 참조 카운트를 올바르게 처리하지 않기 때문에, 이것은 진정한 COM 오브젝트는 아니다. 그 때문에, 어플리케이션은 정적으로 COM 오브젝트를 생성 해야 한다. 상세한 것에 대하여는, 「에러의 로그」를 참조할것.

USE_WMF_CERT 가 정의되었을 경우, 어플리케이션은 WMF 파일의 기입 지원을 포함한다. CKeyProvider 클래스는,IServiceProvider 인터페이스를 이행 한다. 이 클래스는 WMCreateCertificate 함수를 호출해, WMF 증명서를 생성 한다. 헬퍼 함수 ListWMSDKProfiles 는, WMK SDK 로 제공되는 표준 프로파일을 일람으로 한다. 상세한 것에 대하여는, 「Windows Media 어플리케이션」 및 Windows Media Format SDK 를 참조할것.


DexterVB 샘플

설명

Microsoft® Visual Basic® 의 비디오 편집 어플리케이션.

이 샘플 어플리케이션은 Microsoft® DirectShow® 편집 서비스 타임 라인을 생성 하는 그래피컬 툴이다. 이하의 태스크를 데먼스트레이션 한다 :

  • Loading and saving XTL 프로젝트 파일의 로드와 세이브
  • 타임 라인 오브젝트의 추가, 편집, 삭제
  • 타임 라인의 프리뷰

패스

소스: (SDK root)\Samples\Multimedia\VBSamples\DirectShow\Editing\DexterVB

유저 가이드

다음의 그림은 VexterVB 어플리케이션 윈도우를 나타낸다.

DexterVB 유저 인터페이스

왼쪽의 페인은 타임 라인을 가지는 트리 뷰 컨트롤을 표시한다. 오른쪽의 페인은 타임 라인에 대한 정보를 표시하는, 타임 라인내의 오브젝트에 대한 정보를 보려면 , 트리 뷰내의 오브젝트의 아이콘을 선택하는 것.

새로운 타임 라인을 생성 하려면File 메뉴로부터 New 를 선택하는 것. 프로젝트 파일을 열려면File 메뉴로부터 Open 를 선택하는 것. 현재의 타임 라인을 프로젝트 파일에 보존하려면 File 메뉴로부터 Save As 를 선택하는 것.

타임 라인 혹은 타임 라인의 오브젝트의 어느쪽이든을 변경하려면 , 왼쪽의 페인으로 대응하는 아이콘을 오른쪽 클릭하는 것. DexterVB 는 그 오브젝트의 pop-up menu를 표시한다. 다음의 그림은 타임 라인의 pop-up menu을 나타낸다.

타임 라인의 pop-up 메뉴

각 오브젝트에 대해, pop-up menu는 그 오브젝트에 대해서 적용하는 커멘드만을 가진다. 다음의 커멘드가 지원 되고 있다 :

  • Add (오브젝트 타입): 지정한 타입의 새로운 아이 오브젝트를 삽입한다.
  • Collapse: 이 오브젝트의 트리 뷰 노드를 꺾어 접는다.
  • Delete: 타임 라인으로부터 오브젝트를 삭제한다.
  • Edit: 오브젝트의 프로퍼티를 유저로부터 편집 가능하게 한다.
  • Expand: 이 오브젝트의 트리 뷰 노드를 전개한다.

다음의 커멘드는 타임 라인 자신에게 고유의 것이다 :

  • Clear Render Engine: 필터 그래프를 삭제한다.
  • Insert Group: 타임 라인에 새로운 그룹을 삽입한다.
  • Play: 프로젝트의 프리뷰. 유저는 타임 라인을 최초로 렌더링 해야 한다.
  • Pause: 프리뷰의 포즈.
  • Render Timeline: 이 타임 라인으로부터 프리뷰 그래프를 구축한다.
  • Stop: 프리뷰의 정지.


SlideShowVB 샘플

설명

일련의 비디오 클립이나(복수의) 이미지 파일로부터 슬라이드를 보이는 Microsoft® Visual Basic® 어플리케이션.

패스

소스: (SDK root)\Samples\Multimedia\VBSamples\DirectShow\Editing\SlideShowVB

유저 가이드

이 샘플 어플리케이션은 이하의 태스크를 데먼스트레이션 한다 :

  • Using the MediaDet 오브젝트를 사용해, 소스 클립으로부터 포스터 프레임을 취득한다.
  • 타임 라인을 XTL 파일에 보존한다.
  • 타임 라인을 AVI 파일에 기입한다.
  • 미디어 클립을 읽어들인다.

이 어플리케이션을 사용하려면 , 다음과 같이 한다 :

  • 비디오 파일이나(복수의) 이미지 파일을 어플리케이션 윈도우의 셀에 드러그 해, 맨 왼쪽 위쪽의 셀로부터 시작 한다.
  • 각 클립이 재생되는 시간폭을 초단위로 입력한다.
  • combobox를 사용해 트란지션을 선택한다. 트란지션은 2 초의 시간폭으로 고정되고 있다.
  • 슬라이드 쇼를 프리뷰 하려면 ,Play 를 클릭한다.
  • XTL 프로젝트로서 슬라이드 쇼를 보존하려면 ,Write XTL 를 클릭한다.
  • AVI 파일로서 슬라이드 쇼를 보존하려면 ,Write AVI 를 클릭한다.


TrimmerVB 샘플

설명

소스 클립을 트림 해, 트림 된 클립을 새로운 파일에 기입하는 Microsoft® Visual Basic® 어플리케이션.

패스

소스: (SDK 루트)\Samples\Multimedia\VBSamples\DirectShow\Editing\TrimmerVB

유저 가이드

이 어플리케이션을 사용하면(자) 유저는 비디오 원시 파일을 열어, 시작점과 종료점으로부터 희망하는 분만큼 클립을 트림 해, 다음에 남은 부분을 새로운 파일에 보존한다.

이 어플리케이션을 사용하려면 이하와 같이 한다 :

  1. 원시 파일을 선택하려면 ,Browse 버튼을 클릭한다. 클립의 최초의 프레임이 3 개의 프리뷰 에리어에 표시된다.
  2. 시작 위치를 선택하려면 , 슬라이더를 움직일까 프레임 스톱 버튼을 클릭한다. Current Video Frame 에리어의 프리뷰 프레임이 업데이트 된다.
  3. 시작 위치를 설정하려면 ,Set Trim Preview Start Position 버튼을 클릭한다. Video Start Frame 에리어의 포스터 프레임이 업데이트 된다.
  4. 정지 위치를 선택하려면 , 슬라이더를 움직일까 프레임 스톱 버튼을 클릭한다.
  5. 정지 위치를 설정하려면 ,Set Trim Preview Stop Position 버튼을 클릭한다. Video Stop Frame 에리어의 포스터 프레임이 업데이트 된다.
  6. 새로운 파일에 기입하려면 ,Write 버튼을 클릭한다. 진행 인디케이터(indicator)가 완료할 때까지 기다린다.
  7. 새로운 파일을 보려면 ,Playback 버튼을 클릭한다.


XTLTestVB 샘플

설명

비디오 편집 프로젝트 파일을 프리뷰 하는 Microsoft® Visual Basic® 어플리케이션.

이 어플리케이션을 사용하려면 , Microsoft® DirectShow® 편집 서비스 XTL 파일을 어플리케이션의 윈도우에 드러그 한다.

패스

소스: (SDK root)Samples\Multimedia\VBSamples\DirectShow\Editing\XTLTestVB


DirectX Media Object

여기에서는, Microsoft® DirectX® Media Object (DMO)에 대해 설명한다.

  • DirectX Media Object 의 개요
  • DirectX Media Object 의 사용
  • DMO 와 미디어 타입
  • DirectShow 어플리케이션에서의 DMO 의 사용
  • DMO 의 관련 정보


DirectX Media Object 의 개요

Microsoft® DirectX® Media Object (DMO)는, 데이터 스트리밍 컴퍼넌트를 생성하기 위한 새로운 수단이다. DMO 와 Microsoft® DirectShow® 필터에는 몇개의 공통점이 있다. DirectShow 필터와 같게, DMO 도 입력 데이터를 받아, 그것을 사용해 출력 데이터를 생성한다. 다만, DMO 의 어플리케이션 프로그래밍 인터페이스 (API)는, DirectShow 의 동등의 API 보다 훨씬 단순하다. 따라서, DMO 는, 보다 간단하게 생성 할 수 있어 테스트할 수 있어 사용할 수 있다.

DMO 는 DirectShow 와 완전한 호환성을 가지고 있지만, 어플리케이션은 DirectShow 를 사용하지 않고 DMO 를 사용할 수 있다. DMO 는, DirectShow 어플리케이션의 내부에서 DMO 래퍼 필터라고 하는 DirectShow 필터에 의해 랩 된다. 필터와 DMO 의 구별은 어플리케이션에 대해서는 투과적이고, 어플리케이션이 DMO API 를 사용할 필요는 없다. 한편, DirectShow 에 근거하지 않은 어플리케이션은, DMO 를 직접 사용할 수 있다. 따라서, DMO 를 생성 하면, 광범위의 어플리케이션으로 사용할 수 있는 컴퍼넌트를 생성 할 수 있다.

  • DMO 와 DirectShow 필터의 차이
  • DMO 를 사용하는 이유
  • DMO 테스트 어플리케이션

DMO 와 DirectShow 필터의 차이

DirectShow 필터는 DirectShow 필터 그래프내에서만 기능한다. 필터 그래프 매니저가 어플리케이션과 그래프내의 필터를 중개한다. DMO 에서는 그 필요가 없다. 어플리케이션은 단독으로 DMO 를 사용할 수 있다.

DirectShow 에서는, 필터가, 데이터의 스트리밍에 필요한 대부분의 작업을 실행한다. 그 작업은 이하대로이다.

  • 버퍼를 할당한다.
  • 미디어 타입 및 다른 필터와의 접속을 네고시에이트 한다.
  • 데이터를 필터 그래프에 보내, 통과시킨다.
  • 필터 그래프 매니저에 이벤트를 송신한다.
  • 복수의 thread를 동기 시킨다.

이것과 대조적으로, DMO 는 이러한 작업을 전혀 실시하지 않는다. 이런 종류의 작업을 실행하는 역할은, DMO 를 사용하는 클라이언트가 담당한다. 클라이언트는, 버퍼를 할당하고 할당한 버퍼에 데이터를 저장 한다. 그 후, 클라이언트는 버퍼를 DMO 에 배포해, DMO 는 그것을 처리한다. 클라이언트는 출력 버퍼를 꺼낸다.

DirectShow 의 내부에서는 DMO 래퍼 필터가 DMO 의 클라이언트이기 (위해)때문에, DMO 래퍼 필터가 이것들 모든 작업을 처리한다. 다른 어플리케이션은, 독자적인 이행을 제공할 수 있다.

DMO 를 사용하는 이유

DMO 의 이점

  • 일반적으로, DMO 는 지원 하는 기능이 적기 때문에, DirectShow 필터보다 작고, 단순하다.
  • DMO 는 필터 그래프를 필요로 하지 않기 때문에, DirectShow 필터보다 순응성이 있다. 그래프의 동기, 인텔리전트 접속, 데이터 플로우의 자동 처리, thread 관리 등, DirectShow 의 서비스가 필요한 때는, DMO 를 DirectShow 와 조합해 사용할 수 있다. 이러한 서비스가 필요없을 때는, DMO 에 직접 액세스 할 수 있다.
  • DMO 는 항상 동기 데이터 처리를 실행한다. 그 때문에, 필터 개발자는, thread에 관한 다양한 문제를 고려할 필요가 없다.
  • ACM CODEC 나 VCM CODEC 와 달리, DMO 는 Component Object Model (COM)에 근거하고 있기 (위해)때문에,QueryInterface 를 사용해 확장할 수 있다.
  • DMO 가 지원 하는 스트리밍 모델은, ACM CODEC 나 VCM CODEC 의 지원 하는 모델보다 범용성이 높다. DirectShow 필터와 같게, DMO 는 복수의 입력과 복수의 출력을 지원 할 수 있다.

이러한 이유에 의해, 할 수 있는 한, DirectShow 필터보다 DMO 를 이행 하는 것이 좋다. 다만, 예를 들어 이하와 같이 DMO 가 적합하지 않는 상황도 있다.

  • 특수한 전송 요건이 있는 경우. DMO 래퍼 필터는,IMemInputPin 전송을 사용한다. DirectShow 어플리케이션내에서, 다른 전송 메카니즘이 필요한 경우는, 필터를 생성 해야 한다.
  • 동적 그래프 생성을 실시하는 경우. 어플리케이션이동적 그래프 생성을 실행하는 경우는, 독자적인 필터의 생성이 필요하게 되는 일이 있다. 예를 들어, allocater를 생성 하는 방법을 제어할 필요가 생기는 일이 있다.

DMO 테스트 어플리케이션

DirectX 8.0 SDK 에는, DMOTest 라는 이름의 DMO 테스트 어플리케이션이 포함되어 있다. 이 테스트 어플리케이션은, DMO 가 DMO 사양에 일치하고 있을지 어떨지를 검증하는 도움이 된다. 이 어플리케이션은, SDK 루트 디렉토리 이하의 Bin\DXUtils 디렉토리에 인스톨 되고 있다. DMO 를 개발하는 경우는, 테스트의 일부로서 DMO 테스트 어플리케이션을 포함할 필요가 있다.

DMOTest 를 사용하기 위해서(때문에)는, DMO 용의 테스트 데이터를 생성해야 한다. SDK 에는, 그 때문에(위해) DirectShow 필터가 포함되어 있다. 이 필터는, DLL 파일 DMODump.dll 에 존재한다. 또, Regsvr32 유틸리티를 사용해 등록할 필요가 있다.

테스트 어플리케이션의 자세한 것은, DMOTest 어플리케이션의 헬프에 설명되고 있다. 어플리케이션으로,[Help] 메뉴의 [Contents] 를 클릭한다. 이 헬프에는, 테스트 데이터의 생성과 테스트 어플리케이션의 실행에 관한 상세한 지시가 포함되어 있다.


DirectX Media Object 의 사용법

여기에서는, 어플리케이션으로 Microsoft® DirectX® Media Object (DMO)를 사용하는 방법을 설명한다. 이 주제의 설명은, DMO 에 직접 액세스 하는 어플리케이션 에 대해서만 들어맞는다. Microsoft® DirectShow® 필터 그래프로 DMO 를 사용하는 경우는,DMO 래퍼 필터를 사용한다.

이하의 항목에 대해 설명한다.

  • 스트림과 버퍼
  • 데이터의 흐름
  • 데이터를 처리하는 방법
  • 파기 가능 스트림과 옵션 스트림
  • 인플레이션 의자 DMO

스트림과 버퍼

개념적으로 말하면, DMO 는,m 개의 입력을 받아,n 개의 출력을 생성하는 오브젝트이다. 입력과 출력은 "스트림" 으로 불린다. 모든 DMO 에는 적어도 1 개의 스트림이 있다. 입력 스트림이 없는 DMO 나 출력 스트림이 없는 DMO 도 있지만, 보통의 DMO 에는 입력과 출력의 양쪽 모두가 있다.

주 DirectShow 의 핀과 달리, 스트림은 개별의 COM 오브젝트는 아니다. 스트림은 DMO 오브젝트 자체로부터 제로 베이스 인덱스를 사용해 참조된다.

DMO 는 입력 스트림을 통해서 데이터를 받는다. DMO 는 데이터를 처리해, 출력 스트림을 통해서 출력을 생성한다. 모든 데이터는 "미디어 타입" 에 의해 분류된다. 미디어 타입은, 데이터의 내용을 해석하는 방법을 정의한다. 예를 들어, 320 x 240 24 비트 RGB 는 1 개의 타입이며, 44.1KHz 16 비트 스테레오 PCM 오디오는 다른 타입이다. 미디어 타입은,DMO_MEDIA_TYPE 구조체를 사용해 기술된다.

DMO 의 각 스트림은, 특정의 범위의 미디어 타입을 받아들일 수가 있다. DMO 에 의해, 받아들이는 타입의 범위가 넓은 일도 (예를 들어 임의의 비트 깊이의 비디오), 좁은 일도 있다 (예를 들어 16 비트 비디오만). 또, 특정의 입력과 출력의 편성으로 한정된 DMO 도 있다. 예를 들어, 입력 스트림이 16 비트 비디오로 설정되어 있는 경우는, 출력 스트림의 비트 깊이를 같게 해야 하는 것이 있다. 어플리케이션은, 각 스트림의 우선 타입을 열거한 후, 특정의 편성을 테스트할 수가 있다.

례:

  • 비디오용과 오디오용의 2 개의 입력 스트림을 가지는, AVI 데이터를 생성 하는 DMO. 이 DMO 는, 인터리브 된 오디오 비디오 데이터용의 1 개의 출력 스트림을 생성한다.
  • RGB 화면의 포스타리제이션을 실시하는, 입력이 24 비트 RGB 비디오, 출력이 8 비트 RGB 비디오의 DMO.

어플리케이션은, 메모리 블록 마다 그룹 나누고 된 입력 데이터를 배포한다. 개개의 메모리 블록은,IMediaBuffer 인터페이스를 지원 하는 "버퍼" 로 불리는 COM 오브젝트에 의해 캡슐화된다. 이 인터페이스는, 버퍼내의 데이터 길이를 설정하는 메소드, 데이터를 가리키는 포인터를 취득하는 메소드, 및 할당할 수 있었던 버퍼의 사이즈를 취득하는 메소드를 갖추고 있다. 어플리케이션은, DMO 가 입력과 출력의 양쪽 모두에 사용하는 모든 버퍼를 할당하는 역할을 담당한다.

데이터의 흐름

여기에서는, 데이터가 어플리케이션과 DMO 의 사이로, 어떻게 이동하는지를 설명한다.

어플리케이션은, 입력 버퍼의 배포와 출력의 요구를 교대로 실시한다. 어플리케이션은, DMO 에 대해서 IMediaObject::ProcessInput 메소드를 호출하는 것에 의해 입력 버퍼를 배포해,IMediaObject::ProcessOutput 메소드를 호출하는 것에 의해 출력을 요구한다.

입력 데이터의 흐름을 멈추려면 2 개의 방법이 있다.

  • 중단되고 (discontinuity): 어플리케이션이 입력 데이터의 말미에 도달하는지, 데이터에 중단되고가 있으면(자), 어플리케이션은 "중단되고 (discontinuity)" 를 통지한다. 중단되고는, 그 이상 입력이 없는 것을 DMO 에 알린다. 그 시점에서, 처리하는 데이터가 DMO 에 남아 있는 일이 있기 (위해)때문에, 데이터가 없어진 것을 DMO 가 통지할 때까지, 어플리케이션은 출력의 요구를 계속할 필요가 있다.
  • 플래시: 어플리케이션은,"플래시 하는" 것에 의해 데이터의 흐름을 중단할 수가 있다. DMO 가 내부에서 데이터를 버퍼링 하고 있는 경우, DMO 는 데이터를 해방한다.

스트리밍은, 어플리케이션이 최초로 DMO 에 대해서 IMediaObject::ProcessInput 를 호출했을 때에 시작된다. DMO 는, 어플리케이션이 모든 스트림의 미디어 타입을 설정할 때까지, 스트리밍을 시작 하지 않는다. (옵션 스트림은 예외이다. 「파기 가능 스트림과 옵션 스트림」을 참조할것. ) 어플리케이션이 DMO 를 플래시 하는지, 모든 입력 스트림이 중단되고를 통지한 후, 모든 출력을 처리 하면, 스트리밍이 정지한다. 이러한 동작에 의해 DMO 는 비스트리밍 상태에 돌아온다. DMO 는 모든 미디어 타입의 설정을 보관 유지하지만, 모든 IMediaBuffer 포인터를 해방한다. 그 이후, 어플리케이션이 적어도 1 회 ProcessInput 를 호출할 때까지, DMO 는 출력을 생성할 수 없다.

데이터를 스트리밍 하려면 , 이하의 순서를 실행한다.

  1. DMO 가 지원 하는 스트림의 수와 각 스트림의 우선 미디어 타입을 DMO 에 문의한다.
  2. 모든 스트림의 미디어 타입을 설정한다.
  3. 입력 버퍼와 출력 버퍼를 할당한다.
  4. 입력 버퍼에 데이터를 저장 해,ProcessInput 를 호출한다.
  5. ProcessOutput 를 호출해, 출력 데이터를 취득한다. 모든 입력 데이터가 처리될 때까지, 순서 4 ~ 5 를 반복한다.
  6. 중단되고를 통지해, 잔라고 모든 출력을 처리한다.

데이터를 플래시 하는 것에 의해 순서 4 ~ 5 를 중단할 수 있다.

데이터를 처리하는 방법

여기에서는, 전의 섹션으로 가리킨 순서를 자세하게 설명한다.

순서 1: DMO 에 대한 문의

우선, DMO 가 지원 하는 스트림의 수와 각 스트림의 우선 미디어 타입을 DMO 에 문의한다. 입력 스트림과 출력 스트림의 수를 취득하려면 ,IMediaObject::GetStreamCount 메소드를 호출한다.

각 스트림에 대해, DMO 는 우선 순위에 따라 우선 미디어 타입의 순위매김을 실시해, 각 타입에 제로로부터 시작되는 인덱스를 할당한다. 특정의 스트림의 우선 미디어 타입을 취득하려면 ,IMediaObject::GetInputType 메소드 또는 IMediaObject::GetOutputType 메소드를 호출한다. 스트림 번호와 미디어 타입 인덱스를 지정한다. 스트림의 모든 미디어 타입을 열거하려면 , 이하의 유사 코드에 나타내도록(듯이), 메소드가 DMO_E_NO_MORE_ITEMS 를 돌려줄 때까지, 미디어 타입 인덱스를 인크리먼트(increment) 하는 루프를 사용한다.

DWORD cInputs, cOutputs, type = 0
DMO_MEDIA_TYPE mt

pDMO->GetStreamCount(&cInputs, &cOutputs)

for (DWORD i = 0; i < cInputs; i++)
{
    while (pDMO->GetInputType(i, type, &mt) ! = DMO_E_NO_MORE_ITEMS)
    {
        if ( this media type is one you want )
            break
        MoFreeMediaType(&mt)
        type++
    }
}

GetInputType 메소드와 GetOutputType 메소드는, 미디어 타입과 함께 DMO_MEDIA_TYPE 구조체를 돌려준다. 이하의 구조체 멤버가 관계한다.

  • majortype: 스트림의 "메이저 타입" 을 지정하는 글로벌하게 일의인 식별자 (GUID). 메이저 타입은, 비디오나 오디오등이 대범한 분류이다. 메이저 타입의 일람에 대해서는, 「메이저 타입」을 참조할것.
  • subtype: 스트림의 "서브 타입" 을 지정하는 GUID. 서브 타입은, 타입을 한층 더 세세하게 분류한다. 예를 들어, MEDIASUBTYPE_RGB24 는 24 비트 RGB 비디오를 나타낸다. 서브 타입의 일람에 대해서는, 「미디어 타입」을 참조할것.
  • pbFormat: 포맷을 자세하게 기술하는 구조체를 가리키는 포인터. 포맷 구조체는, 비디오 화면의 폭과 높이나 오디오 샘플의 샘플링 레이트등의 정보를 지정한다. 미디어 타입이 다르면, 사용하는 포맷 구조체도 다르다. 대부분의 비디오 데이터는,VIDEOINFOHEADER 구조체를 사용한다. 오디오 데이터는,WAVEFORMATEX 구조체를 사용한다.
  • formattype: pbFormat 에 저장 되고 있는 포맷 구조체를 지정한다.

미디어 타입은,formattype 멤버의 값 GUID_NULL 에 의해 나타내지는 NULL 포맷 구조체를 가지고 있는 일이 있다. NULL 포맷은, DMO 가, 지정된 미디어 타입의 일정한 범위내의 포맷을 받아들여지는 것을 나타낸다. 예를 들어, PCM 오디오를 필요로 하는 스트림은, 일정한 범위의 샘플링 레이트를 받아들이는 일이 있다. 따라서, 그 스트림은, 메이저 타입을 MEDIATYPE_Audio 에, 서브 타입을 MEDIASUBTYPE_PCMAudio 로 해, NULL 포맷을 돌려준다.

어플리케이션은,MoFreeMediaType 함수를 호출해 pbFormat 멤버를 해방할 필요가 있다.

순서 2: 미디어 타입의 설정

DMO 의 우선 미디어 타입을 알 수 있으면(자),IMediaObject::SetInputType 메소드와 IMediaObject::SetOutputType 메소드를 호출해, 각 스트림의 미디어 타입을 설정한다.

DMO 가 보고하는 모든 미디어 타입의 편성이 유효하다라고는 한정되지 않는다. 예를 들어, 출력 타입을 입력 타입에 맞추지 않으면 안 되는 것이 있다. DMO_SET_TYPEF_TEST_ONLY 플래그를 설정해 SetInputType 또는 SetOutputType 를 호출하는 것으로, 미디어 타입을 테스트할 수 있다. 디코더의 경우는, 보통, 우선 입력 타입을 설정해, 다음에 출력 타입을 선택한다. 엔코더의 경우는, 우선 출력 타입을 설정해, 다음에 입력 타입을 선택한다.

1 개의 스트림의 설정이 다른 스트림에 영향을 미치는 일이 있기 (위해)때문에, 전으로 설정한 미디어 타입을 소거할 필요가 생기는 일이 있다. 이것을 실시하려면 , DMO_SET_TYPEF_CLEAR 플래그를 설정해 SetInputType 또는 SetOutputType 를 호출한다.

순서 3: 버퍼의 할당

미디어 타입을 설정하면(자), 각 스트림의 버퍼 요건을 DMO 에 문의한다. 버퍼 요건은 미디어 타입에 따라서 다른 일이 있다. 각 스트림에 대해,IMediaObject::GetInputSizeInfo 메소드 또는 IMediaObject::GetOutputSizeInfo 메소드를 호출한다. 이러한 메소드는, 이하의 3 개의 값을 돌려준다.

  • 바이트 단위의 최소 버퍼 사이즈.
  • 설정되어 있으면, alignment 요건. 시작 주소가, 지정된 특정의 정수의 배수가 되어 있으면, 버퍼는 "아라인" 되고 있다.
  • 입력 버퍼의 경우는, DMO 가룩 어해드용으로 보관 유지하는 데이터의 최대량. 일부의 DMO 는, 데이터를 처리하기 위해서 복수의 입력 버퍼를 보관 유지할 필요가 있다. 룩 어해드값은, 이 요건을 지정한다.

이러한 요건을 채우는데 충분한 버퍼를 할당할 필요가 있다.

사이즈 요건 외에, 입력 스트림에서는, 각 버퍼에 샘플 전체 또는 1 개의 샘플만이 포함되어 있는 것이나, 각 버퍼가 일정한 샘플 사이즈를 사용하는 것이 필요하게 되는 일이 있다. 이러한 요건을 조사하려면 ,IMediaObject::GetInputStreamInfo 메소드를 호출한다.

순서 4: 입력의 처리

이 시점에서, 입력 버퍼를 DMO 에 배포할 수 있다.

각 입력 스트림에 대해, 1 개(살) 이상의 버퍼에 미디어 데이터를 저장 한다. 데이터를 직접 버퍼에 기입하는 일도, 다른 DMO 의 출력 버퍼를 사용할 수도 있다. ProcessInput 메소드를 호출해, 각 버퍼를 배포한다. 보통, DMO 는 버퍼의 참조 카운트를 보관 유지한다. DMO 는, 생성할 수 있는 모든 출력을 생성했을 때, 또는 어플리케이션이 DMO 를 플래시 했을 때에, 버퍼를 해방한다. DMO 가 버퍼를 해방할 때까지, 버퍼를 재이용하지 않는 것.

입력 스트림이 데이터를 더 이상 받아들여질지 어떨지를 판별하려면 ,IMediaObject::GetInputStatus 메소드를 호출한다. 스트림이 데이터를 더 이상 받아들여지는 경우, 메소드는 DMO_INPUT_STATUSF_ACCEPT_DATA 플래그를 돌려준다.

순서 5: 출력의 처리

ProcessInput 는 한 번에 1 개(살)씩 입력 버퍼를 배포하지만,ProcessOutput 는 한번에 모든 출력 스트림의 출력을 생성한다. 어플리케이션은, 각 출력 스트림에 1 개의 구조체를 할당해,DMO_OUTPUT_DATA_BUFFER 구조체의 배열을 건네준다. 구조체에는, 어플리케이션이 할당한 출력 버퍼 및 DMO 가 데이터를 저장 하는 다양한 필드가 포함되어 있다.

ProcessOutput 메소드에 의해, DMO 는, 지정된 출력 버퍼의 사이즈의 범위내에서, 가능한 한 많은 데이터를 생성한다. 모든 데이터를 처리하기 전에 출력 버퍼가 가득 되었을 경우, DMO 는 구조체의 dwStatus 멤버의 DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE 플래그를 설정한다. 메소드가 종료하면(자), 각 구조체에 이 플래그가 있을지 어떨지를 확인한다. 플래그가 있는 경우는, 한번 더 ProcessOutput 를 호출한다.

스트리밍이 시작되면(자), DMO 는 항상 입력을 받아들이는지, 출력을 생성하는지, 그 양쪽 모두를 실시할 수가 있다. 따라서,GetInputStatus 가 DMO_INPUT_STATUSF_ACCEPT_DATA 플래그를 돌려주는지,ProcessOutput 가 DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE 플래그를 돌려준다. 어플리케이션은, 이러한 플래그의 유무를 테스트해,ProcessInput 또는 ProcessOutput 를 호출하는 것에 의해, 데이터의 흐름을 유지한다.

순서 6: 중단되고 (discontinuity)의 통지

사용할 수 있는 모든 입력 데이터를 특정의 입력 스트림에 배포하면(자),IMediaObject::Discontinuity 메소드를 호출한다. DMO 는, 남아 있는 출력의 처리가 끝날 때까지, 그 스트림에 대한 입력을 그 이상 받아들이지 않는다.

파기 가능 스트림과 옵션 스트림

DMO 는, 출력 스트림의 일부를 파기 가능 또는 옵션 스트림으로서 지정할 수 있다.

  • "파기 가능" 스트림에는, 어플리케이션이 완전하게 파기할 수 있다, 또는 일부의 샘플에 대해 파기할 수 있는 데이터가 포함되어 있다.
  • "옵션" 스트림은, 일부의 어플리케이션 밖에 필요로 하지 않는, 또는, 주스트림에 관한 추가 정보가 포함된 이차적인 스트림이다.

스트림이 파기 가능 또는 옵션일지 어떨지를 문의하려면 ,IMediaObject::GetOutputStreamInfo 메소드를 호출해,pdwFlags 파라미터를 체크한다. DMO_OUTPUT_STREAMF_DISCARDABLE 플래그는 스트림이 파기 가능한 것을 나타내, DMO_OUTPUT_STREAMF_OPTIONAL 플래그는 스트림이 옵션 스트림인 것을 나타낸다. 일반적으로, 적어도 1 개의 스트림은, 옵션 스트림 이외의 스트림이 아니면 안된다.

IMediaObject::ProcessOutput 메소드를 호출하면나무는,dwFlags 파라미터의 DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER 플래그를 설정하는 것에 의해, 1 개(살) 이상의 스트림의 데이터를 파기할 수 있다. 파기하고 싶은 개개의 스트림에 대해,DMO_OUTPUT_DATA_BUFFER 구조체의 pBuffer 멤버를 NULL 로 설정한다. DMO 는, 이하의 조작에 의해, 이러한 스트림의 데이터의 파기를 시도한다.

  • 스트림이 파기 가능 또는 옵션의 경우는, DMO 가 데이터를 파기하는 것이 보증된다.
  • 그 이외의 경우, DMO 는, 가능하면 데이터를 파기한다. 다만, DMO 가 데이터를 파기하는 것은 보증되지 않는다.

pBuffer 멤버는 NULL 이지만, DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER 플래그를 설정하지 않았던 경우, DMO 는, 스트림이 파기 가능 또는 옵션이어도, 데이터를 파기하지 않는다. pBuffer 는 NULL 이지만, 데이터가 파기되지 않았던 경우, DMO 는, 스트림에 데이터가 남아 있는 것을 나타내는 DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE 플래그를 보낸다. 출력 스트림을 처리한 후, 그 출력 스트림을 파기하지 않으면 DMO 가 다른 출력 스트림의 데이터를 생성할 수 없게 되는 일이 있다.

옵션 스트림을 절대로 사용하지 않는 경우는, 옵션 스트림의 미디어 타입을 설정할 필요는 없다. 파기 가능한 스트림의 경우는, 이것과 다르다. 파기 가능한 스트림의 미디어 타입은, 반드시 설정할 필요가 있다. 옵션 스트림과 파기 가능 스트림의 기능상의 상위는, 이 점 뿐이다.

인플레이션 의자 DMO

일부의 데이터 변환은, 데이터를 직접 변경하는 것에 의해 행해진다. 이것은,"인플레이션 의자" 처리로 불린다. 많은 오디오 이펙트나 비디오 이펙트는, 인플레이션 의자로 실시할 수가 있다. 인플레이션 의자 처리는, 다른 버퍼에 데이터를 카피하는 방법보다 효율이 좋다. 데이터를 인플레이션 의자로 처리하려면 ,ProcessInput 와 ProcessOutput 를 따로 따로 호출하는 대신에,IMediaObjectInPlace::Process 메소드만을 호출한다. 입력 데이터가 포함된 바이트의 배열을 건네준다. 메소드가 종료 하면, 바이트 배열에는 출력 데이터가 저장 된다.

IMediaObjectInPlace 를 지원 하는 DMO 는, 모든 IMediaObject 메소드도 지원 할 필요가 있다. 인플레이션 의자 처리를 사용하는지, 다른 입력 버퍼와 출력 버퍼를 생성 할까는, 선택할 수 있다. 다만, 2 개의 종류의 처리를 혼재시키지 않는 것. Process 를 호출하면나무는,ProcessInput 또는 ProcessOutput 를 호출해선 안 되고, 그 역을 실시해선 안 된다.

인플레이션 의자 DMO 는, 입력이 정지한 다음에, 추가의 출력을 생성하는 일이 있다. 이것은,"이펙트 테일" 로 불린다. 예를 들어, 잔향 이펙트는, 입력이 무음이 된 후도 계속한다. DMO 가 이펙트 테일을 생성하는 경우, 어플리케이션은, 테일이 완전하게 처리될 때까지, 입력 버퍼를 제로로 해 Process 메소드를 호출할 필요가 있다. 상세한 것에 대하여는, 「IMediaObjectInPlace::Process 」를 참조할것.


DMO 와 미디어 타입

미디어 타입이란, 미디어 데이터의 스트림에 관련지을 수 있었던 포맷의 설명이다. 여기에서는, Microsoft® DirectX® Media Objects (DMO)에 의한 미디어 타입의 처리 방법에 대해 설명한다. 이것은 주로 커스텀 DMO 를 생성 하는 개발자전용의 내용이다. DMO 를 사용하는 어플리케이션에 대해서는, 「DirectX Media Object 의 사용」을 참조할것.

여기에서는, 이하의 항목에 대해 설명한다.

  • 개요
  • 레지스트리내의 미디어 타입
  • 우선되는 미디어 타입
  • 미디어 타입의 설정
  • 사용예

개요

미디어 타입을 기술하는 정보는 크게 나누어 다음의 3 개이다.

  • 메이저 타입:오디오, 비디오 등, 데이터의 대범한 분류를 정의하는 글로벌 일의 식별자 (GUID).
  • 서브 타입:비디오 데이터용 24 비트 RGB 등, 미디어 타입의 것보다 상세한 부분을 정의하는 GUID.
  • 포맷 블록:포맷을 상세하게 지정하는, 타입 고유의 구조체.

상세한 것에 대하여는,DMO_MEDIA_TYPE 구조체를 참조할것.

어플리케이션이 우선 DMO 의 인스턴스를 생성 하는 시점에서는, DMO 내의 스트림에는 특정의 미디어 타입이 지정되어 있지 않다. 어플리케이션이 DMO 를 사용해 데이터를 처리할 수 있게 되려면 , 스트림 전체에 대해서 미디어 타입을 지정할 필요가 있다(옵션의 스트림은 예외이다. 「파기 가능 스트림과 옵션 스트림」을 참조할것).

특정의 스트림에 적합하는 미디어 타입을 찾아내기 위해서(때문에), 어플리케이션은 DMO 에 문의한다. DMO 는 이용할 수 있는 타입을 열거해, 어플리케이션은 그 중에서 1 개(살)을 선택한다. 어느 스트림에 미디어 타입을 설정 하면, 다른 스트림으로 이용할 수 있는 타입을 변경할 수 있다. 예를 들어, 오디오 이펙트 DMO 는 일정한 범위의 샘플링 레이트를 지원 하지만, 출력 레이트를 입력 레이트에 일치시킬 필요가 있다. 이 경우, 입력 타입을 설정 하면, 사용할 수 있는 출력 타입이 한정된다.

레지스트리내의 미디어 타입

DMORegister 함수는, 입력용 및 출력용의 미디어 타입의 일람 등, DMO 에 관한 정보를 레지스트리에 추가한다. 어플리케이션은 이 정보를 사용해, 요건에 합치하는 DMO 를 검색한다. 이 정보는 포괄적인 것이다고는 할 수 없다. 많은 경우, DMO 가 지원 하는 주된 타입만을 포함하게 된다.

레지스트리 정보에는 입력 타입과 출력 타입의 일람이 설정되지만, 개별의 스트림은 구별되지 않는다. 예를 들어, DMO 가 오디오와 비디오로 별개의 입력 스트림을 가지는 경우, 레지스트리 정보에는, 입력 타입으로서 그 양쪽 모두가 설정되게 된다.

DMORegister 함수의 경우, 미디어 타입은 DMO_PARTIAL_MEDIATYPE 구조체로 지정된다. 이 점으로써,DMO_MEDIA_TYPE 를 사용하는 IMediaObject 인터페이스와는 다르다. DMO_PARTIAL_MEDIATYPE 구조체에는, 메이저 타입과 서브 타입을 나타내는 2 개의 필드만이 포함된다. 포맷 블록용의 필드는 없다. 많은 경우, 포맷에는, 비디오 이미지의 높이와 폭 등, 레지스트리에 저장 하려면 향하지 않는 상세한 정보가 포함된다.

우선되는 미디어 타입

지원 되는 타입을 DMO 에 문의하기 위해서(때문에), 어플리케이션은 IMediaObject::GetInputType 메소드와 IMediaObject::GetOutputType 메소드를 호출한다. 이것들 2 개의 메소드는, 지정된 스트림으로 우선되는 타입을 우선순서에 열거한다. 스트림으로 우선되는 타입은, 어플리케이션이 다른 스트림에 미디어 타입을 설정할 경우에 동적으로 변경할 수 있다. 예를 들어, 우선되는 출력 타입을 입력 타입에 응해 변경할 수 있다 (또는 그 역도가능). 스트림은 다른 스트림에 타입이 지정될 때까지 우선 타입을 가지지 않는 것도 있다. 다만, DMO 는 우선 타입을 이 방법으로 갱신할 필요는 없다. 어플리케이션은, 받는 타입이 모두 유효하다라고는 가정할 수 없다. 이 때문에,SetInputType 메소드와 SetOutputType 메소드는 특정의 타입을 검사하기 위한 플래그를 지원 하고 있다.

상세하게 지정된 미디어 타입은, 너무 상세해 우선 타입으로서 사용하기 어려운 일이 있다. 보다 일반적인 타입을 나타내기 위해서(때문에), DMO 는불완전인 타입을 돌려줄 수가 있다. 미디어 타입의 메이저 타입, 서브 타입, 또는 포맷 타입에 값 GUID_NULL 가 설정되어 있는 경우, 미디어 타입은 불완전하다. GetInputType 메소드와 GetOutputType 메소드에서는 보통, 포맷 타입을 GUID_NULL 로 설정한다.

어플리케이션이 모든 입력 타입을 설정한 다음에도, DMO 는 보통, 각 출력 스트림에 대해서 1 개 이상의 완전한 타입을 돌려줄 필요가 있다. 완전한 타입을 설정 하면, 기능의 검사나 어플리케이션에서는, 그 타입을 타당한 기정값으로서 사용할 수 있다(일부의 미디어 타입은 포맷 타입이 없어도 완전한 것으로 주의). SDK 에 부속되는 DMO 테스트 어플리케이션은, 이 방법으로 동작하는 DMO 에 의존하고 있다 ( 「DMO 테스트 어플리케이션」을 참조할것).

미디어 타입의 설정

스트림에 대해서 타입을 테스트, 설정, 또는 소거하기 위해서, 어플리케이션은 IMediaObject::SetInputType 메소드와 IMediaObject::SetOutputType 메소드를 사용한다. DMO 가 데이터를 올바르게 처리할 수 있도록(듯이), 타입은 상세하게 지정할 필요가 있다. DMO 는 각 스트림에 대해, 제안된 타입이 다른 스트림과의 호환성을 갖추고 있는 것을 검증할 필요가 있다. DMO_SET_TYPEF_CLEAR 플래그를 사용해 스트림의 타입을 소거 하면, 어플리케이션은 원 상태에 돌아와 다른 편성을 시험할 수가 있다.

사용예

다음의 예에서는, 몇개의 전형적인 시나리오를 이용해, 지금까지의 설명을 구체적으로 가리킨다.

디코더

일반적인 비디오 디코더에서는, 출력 포맷은 입력 포맷에 의해 부분적으로 결정된다. 예를 들어, 출력 스트림은 보통, 입력 스트림과 같은 frame rate 및 비디오 사이즈를 가질 필요가 있다. 디코더용이 있는 옵션은, 입력 타입이 설정될 때까지 출력 타입을 돌려주지 않게 되어 있다. 다른 옵션은, 포맷 블록을 가지지 않는 불완전한 타입세트를 열거하게 되어 있다. 그 경우, 서브 타입을 사용해, 16 비트 RGB, 24 비트 RGB 등, 지원 되는 비압축 타입을 지정한다.

또, 비디오 디코더는 보통, 입력 타입을 설정하기 전에 출력 타입을 설정하는 어플리케이션은 지원 하지 않는다. 많은 경우, 기존의 입력 포맷화등 디코드하게 되므로, 이 제한은 타당하다.

오디오 레코더에서는, 지원 하는 출력 포맷군이 고정되고 있는 일이 있다. 이러한 경우, 어플리케이션이 입력 포맷을 설정하기 전에, 출력 포맷을 열거할 수 있다.

압력

보통, 비디오 압력은, 어플리케이션이 입력 포맷을 설정할 때까지, 우선되는 출력 포맷을 상세하게 지정할 수 없다 (그 역도 마찬가지). 그 대신에, 포맷 블록을 가지지 않는 불완전한 타입을 돌려주게 된다. 오디오 압축과 비디오 압축의 양쪽 모두로, 어플리케이션은, 출력 bit rate 등 다양한 포맷 파라미터를 제어할 필요가 있다. 다만, 입력 타입이 설정되어 있는 경우는, 전에 설명한 이유로부터, 압력은 완전한 출력 타입을 1 개 이상 열거하게 된다.


DirectShow 어플리케이션에서의 DMO 의 사용법

여기에서는, Microsoft® DirectShow® 어플리케이션으로 Microsoft® DirectX® Media Object (DMO)를 사용하는 방법을 설명한다. DirectShow 의 밖에서 DMO 를 사용하는 방법에 대해서는, 「DirectX Media Object 의 사용」을 참조할것.

다음의 트픽스가 있다.

  • DirectShow 에서의 DMO 의 개요
  • DMO 래퍼 필터의 사용법
  • 시스템 디바이스 열거자를 사용한 DMO 의 검색

DirectShow 에서의 DMO 의 개요

DMO 래퍼 필터를 이용하면, DirectShow 어플리케이션은, 필터 그래프내에서 DMO 를 사용할 수 있다. 이 필터는, DMO 를 랩 해, DMO 와의 데이터의 수수 등, DMO 를 사용할 때의 모든 세세한 작업을 처리한다. 또, 이 필터는 DMO 를 집성 하기 위한(해), 어플리케이션은 DMO 가 공개하는 모든 COM 인터페이스를 필터에 문의할 수가 있다.

다만, 모든 스트림 제어는, 어플리케이션과 필터의 사이, 또는 어플리케이션과 필터 그래프 매니저의 사이에 실시할 필요가 있다. DMO 상태를 변경할 가능성이 있는 DMO 인터페이스의 메소드를 호출해선 안 된다. 예를 들어, 스트림의 미디어 타입의 설정, 버퍼의 처리, DMO 의 플래시, DMO 의 락, 품질 컨트롤의 유효화 또는 무효화, 또는 비디오 최적화의 설정을 실시해선 안 된다. DMO 래퍼 필터는 DMO 의 모든 스트리밍을 처리하기 위해(때문에), 이러한 메소드를 직접 호출하면 에러가 발생하는 일이 있다.

DMO 를 필터 그래프에 추가하려면 2 개의 방법이 있다.

  • 사용하는 특정의 DMO 의 클래스 식별자 (CLSID)를 알 수 있고 있으면, 그 DMO 로 DMO 래퍼 필터를 초기화할 수가 있다.
  • 그 이외의 경우는, 시스템 디바이스 열거자를 사용해, DMO 및 DirectShow 필터를 포함한 디바이스의 카테고리 전체를 열거할 수가 있다.

이하에서는, 각각의 방법에 대해 설명한다.

DMO 래퍼 필터의 사용법

우선, DMO 래퍼 필터의 인스턴스를 생성 한다. DMO 래퍼 필터에 IDMOWrapperFilter 인터페이스를 문의한다. 다음에,IDMOWrapperFilter::Init 메소드를 호출한다. 이 메소드는, DMO 의 CLSID 및 DMO 의 카테고리의 GUID 를 받는다.

DMOEnum 함수를 사용해, 유저의 시스템에 등록되어 있는 DMO 를 열거할 수 있다. DMO 는, DirectShow 필터에 사용되는 카테고리 GUID 와는 다른 카테고리 GUID 를 사용해 등록된다. DMO 카테고리의 일람에 대해서는, 「카테고리 GUID 」를 참조할것.

다음의 코드는,IDMOWrapperFilter 인터페이스의 사용법을 나타내고 있다.

// IMediaObject

// DMO 래퍼 필터를 생성 한다.
IBaseFilter *pFilter;
HRESULT hr = CoCreateInstance(CLSID_DMOWrapperFilter, NULL,
    CLSCTX_INPROC, IID_IBaseFilter, (void **) &pFilter);

if (SUCCEEDED(hr))
{
    IDMOWrapperFilter *pWrap;
    hr = pFilter->QueryInterface(IID_IDMOWrapperFilter, (void **) &pWrap);

    if (SUCCEEDED(hr)) {     // 필터를 초기화.
        hr = pWrap->Init(CLSID_MyDMO, CLSID_MyDMOCategory);
        pWrap->Release();
    }

    if (SUCCEEDED(hr)) {     // 필터를 그래프에 추가.
        hr = pGraph->AddFilter(pFilter, L"My DMO");
    }
    pFilter->Release();
}

시스템 디바이스 열거자를 사용한 DMO 의 검색

시스템 디바이스 열거자는, 일부의 DirectShow 디바이스 카테고리를 열거할 경우에 DMO 도 열거한다. 시스템 디바이스 열거자는, 이하의 DMO 카테고리를 동등의 DirectShow 카테고리에 맵 한다.

DMO 카테고리 | 동등의 DirectShow 카테고리
DMOCATEGORY_AUDIO_ENCODER | CLSID_AudioCompressorCategory
DMOCATEGORY_AUDIO_DECODER | CLSID_LegacyAmFilterCategory
DMOCATEGORY_VIDEO_ENCODER | CLSID_VideoCompressorCategory
DMOCATEGORY_VIDEO_DECODER | CLSID_LegacyAmFilterCategory

게다가 시스템 디바이스 열거자를 사용해, DMOCATEGORY_AUDIO_EFFECT 및 DMOCATEGORY_VIDEO_EFFECT 를 포함한 모든 DMO 카테고리를 열거할 수 있다. 시스템 디바이스 열거자의 사용법의 상세한 것에 대하여는, 「시스템 디바이스 열거자의 사용」을 참조할것. IMoniker::BindToObject 메소드는, DMO 를 DMO 래퍼 필터로 자동적으로 랩 한다.


DMO 의 관련 정보

여기에는, Microsoft® DirectX® Media Object (DMO)에 관련하는 모든 정보가 기재되어 있다.

  • 인터페이스
  • 구조체
  • 열거형
  • 함수
  • DMO 에러 코드
  • 글로벌하게 일의인 식별자 (GUID)
  • DMO base class 레퍼런스


인터페이스

여기에서는, 모든 Microsoft® DirectX® Media Object (DMO) COM 인터페이스 및 각 인터페이스가 갖추는 메소드의 참조 엔트리를 나타낸다.

  • IDMOQualityControl
  • IDMOVideoOutputOptimizations
  • IEnumDMO
  • IMediaBuffer
  • IMediaObject
  • IMediaObjectInPlace


IDMOQualityControl 인터페이스

Microsoft® DirectX® Media Object (DMO)의품질 컨트롤을 지원 한다.

DMO 가 지연 샘플에 대응할 수 있는 경우, DMO 는 이 인터페이스를 공개한다. 품질 컨트롤이 유효하게 되어 있으면(자), DMO 는, 필요에 따라서 지연 샘플을 파기해, 샘플을 예정대로에 처리하려고 한다. 품질 컨트롤이 무효가 되어 있으면(자), DMO 는 모든 샘플을 처리한다. 디폴트에서는, 품질 컨트롤은 무효가 되어 있다.

어플리케이션은, 이 인터페이스를 사용해 품질 컨트롤을 유효 또는 무효로 한다. 미디어 데이터를 리얼타임에 표시하고 있을 때는, 품질 컨트롤을 사용하는 것이 좋다. 품질 컨트롤을 유효하게 하면 DMO 가 샘플을 파기할 가능성이 있기 (위해)때문에, 데이터를 파일에 캡춰 하고 있는 경우는, 품질 컨트롤을 유효하게 하지 않는 것. 샘플의 지연은 파일 캡춰에서는 문제가 되지 않고, 데이터의 결손을 피하는 것이 좋다.

품질 컨트롤을 사용하려면 , 다음의 순서를 실행한다.

  1. 처리의 대상이 되는 가장 빠른 샘플을 기준 시간으로 해,SetNow 메소드를 호출한다.
  2. DMO_QUALITY_STATUS_ENABLED 플래그를 설정해 SetStatus 메소드를 호출한다.

품질 컨트롤을 무효로 하려면 , 플래그를 설정하지 않고 SetStatus 를 호출한다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스를 가리키는 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDMOQualityControl 메소드 | 설명
SetNow | DMO 가 데이터를 배포할 필요가 있는 가장 빠른 타임 스탬프를 지정한다.
SetStatus | 품질 컨트롤을 유효 또는 무효로 한다.
GetStatus | 품질 컨트롤이 액티브한가 어떤가를 판별한다.

IDMOQualityControl::SetNow

IDMOQualityControl 인터페이스

DMO 가 배포하는 가장 빠른 타임 스탬프를 지정한다.

구문

HRESULT SetNow(
    REFERENCE_TIME rtNow
);

파라미터

rtNow
[in] 배포하는 가장 빠른 타임 스탬프를 지정하는 기준 시간.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_FAIL | 실패

주의

품질 컨트롤이 유효하게 되어 있으면(자), DMO 는, 타임 스탬프가 rtNow 미만의 모든 샘플을 파기한다. 타임 스탬프가 rtNow 이후의 샘플은, 할 수 있는 한 효율적으로 처리된다. 이행에 따라서는, 페이스를 유지하기 위해서(때문에) DMO 가 일부의 샘플을 드롭 하는 일이 있다.

품질 컨트롤이 무효가 되어 있으면(자), 이 메소드는 즉시는 효과를 미치지 않는다. 다만, DMO 는 지정된 기준 시간을 보존해 둔다. 다음에 품질 컨트롤이 유효하게 되었을 경우, DMO 는 이 값을 사용한다. 품질 컨트롤을 유효하게 하려면 ,SetNow 메소드를 호출한다.

입력되는 샘플에 타임 스탬프가 없는 경우, DMO 는 품질 컨트롤을 실행하지 않는다. 어플리케이션은,IMediaObject::ProcessInput 메소드로 타임 스탬프를 설정한다.

IDMOQualityControl::SetStatus

IDMOQualityControl 인터페이스

품질 컨트롤을 유효 또는 무효로 한다.

구문

HRESULT SetStatus(
DWORD dwFlags
);

파라미터

dwFlags
[in] 품질 컨트롤을 유효하게 하는지, 무효로 하는지를 지정하는 값. 품질 컨트롤을 유효하게 하려면 DMO_QUALITY_STATUS_ENABLED 를 지정해, 품질 컨트롤을 무효로 하려면 제로를 지정한다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공.
E_INVALIDARG | 무효인 인수.

주의

품질 컨트롤이 유효하게 되어 있는 경우, DMO 는 샘플을 예정대로에 배포하려고 한다. 필요한 경우, DMO 는 지연 샘플을 스킵 할 수가 있다. 품질 컨트롤이 무효가 되어 있으면(자), DMO 는 모든 샘플을 배포한다. 품질 컨트롤을 유효하게 하는 경우는,SetNow 메소드를 호출해, DMO 가 처리할 필요가 있는 가장 빠른 타임 스탬프를 지정하는 것. 그렇게 하지 않으면SetStatus 의 호출은 성공하지만, DMO 는 품질 컨트롤을 실행하지 않는다.

디폴트에서는, 품질 컨트롤은 무효가 되어 있다.

IDMOQualityControl::GetStatus

IDMOQualityControl 인터페이스

품질 컨트롤이 액티브한가 어떤가를 판별한다.

구문

HRESULT GetStatus(
DWORD *pdwFlags
);

파라미터

pdwFlags
[out] 품질 컨트롤 상태를 받는 변수를 가리키는 포인터. 품질 컨트롤이 무효가 되어 있는 경우의 값은 제로이다. 품질 컨트롤이 유효하게 되어 있는 경우의 값은 DMO_QUALITY_STATUS_ENABLED 이다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공.
E_POINTER | NULL 포인터값.


IDMOVideoOutputOptimizations 인터페이스

Microsoft® DirectX® Media Object (DMO)의 비디오 최적화를 지원 한다.

어플리케이션은, 이 인터페이스를 사용해, DMO 와의 사이에 비디오 출력 최적화를 네고시에이트 할 수 있다. DMO 는, 어플리케이션으로부터의 지원을 필요로 하는 최적화를 실행할 수 있을 때, 이 인터페이스를 공개한다. 어플리케이션은, DMO 의 우선 기능을 DMO 에 조회해, 그 기능을 제공하는 것을 승낙 또는 거부할 수가 있다. DMO 는, 어플리케이션이 최적화를 거부했을 경우에서도 출력을 처리할 필요가 있다.

예를 들어, 비디오 디코더는, 전의 출력 프레임에 델타를 적용하는 것에 의해 출력 프레임을 생성하는 일이 있다. 조회를 받으면(자), 비디오 디코더는, 출력 버퍼를 사용해 전의 프레임을 공급하도록(듯이) 어플리케이션에 요구한다. 어플리케이션은 이 요구를 승낙하는 일도 거부할 수도 있다.

비디오 최적화는, 출력 스트림 마다 개별적으로 네고시에이트 된다.

이하의 유사 코드는 어플리케이션이 DMO 와 네고시에이트 하는 방법을 나타내고 있다.

IDMOVideoOutputOptimizations *pVidOpt;
// DMO 에 대해서 IDMOVideoOutputOptimizations 를 조회한다 (표시되어 있지 않다) .

BOOL  bWantsPreviousBuffer = FALSE;
DWORD wFlags;
pVidOpt->QueryOperationModePreferences(0, &dwFlags);

if (dwFlags & DMO_VOSF_NEEDS_PREVIOUS_SAMPLE)
{
    // 요구를 승낙한다.
    pVidOpt->SetOperationMode(0, DMO_VOSF_NEEDS_PREVIOUS_SAMPLE);
    bWantsPreviousBuffer = TRUE;
}

// 루프 처리
while (there is input)
{
    ProcessInput(0, ...);
    if (bWantsPreviousBuffer)
pDMO->ProcessOutput(0, ...) // 전회와 같은 버퍼를 사용한다.
    else
pDMO->ProcessOutput(0, ...) // 새로운 버퍼를 사용해도 괜찮다.
}

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스를 가리키는 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDMOVideoOutputOptimizations 메소드 | 설명
QueryOperationModePreferences | DMO 의 우선 최적화 기능을 취득한다.
SetOperationMode | 현재 유효한 최적화 기능을 DMO 에 통지한다.
GetCurrentOperationMode | 현재 유효한 최적화 기능을 취득한다.
GetCurrentSampleRequirements | 어플리케이션이 이미 승낙한 기능이 있는 경우에, 다음의 샘플을 처리하는데 필요한 최적화 기능을 취득한다.

IDMOVideoOutputOptimizations::QueryOperationModePreferences

IDMOVideoOutputOptimizations 인터페이스

DMO 의 우선 최적화 기능을 취득한다.

구문

HRESULT QueryOperationModePreferences(
ULONG ulOutputStreamIndex,
    DWORD *pdwRequestedCapabilities
);

파라미터

ulOutputStreamIndex
DMO 의 출력 스트림의 제로 베이스의 인덱스.
pdwRequestedCapabilities
요구되고 있는 DMO 의 기능을 받는 변수를 가리키는 포인터. 돌려주어지는 값은,DMO_VIDEO_OUTPUT_STREAM_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합이다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스
E_POINTER | NULL 포인터 인수

IDMOVideoOutputOptimizations::SetOperationMode

IDMOVideoOutputOptimizations 인터페이스

현재 유효한 최적화 기능을 DMO 에 통지한다.

구문

HRESULT SetOperationMode(
ULONG ulOutputStreamIndex,
    DWORD dwEnabledFeatures
);

파라미터

ulOutputStreamIndex
DMO 의 출력 스트림의 제로 베이스의 인덱스.
dwEnabledFeatures
DMO_VIDEO_OUTPUT_STREAM_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스
E_INVALIDARG | 무효인 인수

주의

이 메소드를 호출하기 전에,QueryOperationModePreferences 메소드를 호출해, DMO 가 요구하고 있는 기능을 조사한다. 그 후, 이 메소드를 호출해, 어느 기능을 제공할까를 DMO 에 통지한다. 어느 기능도 제공하지 않는 경우는, 이 메소드를 호출할 필요는 없다. DMO 는, 몇개의 기능이 제공되는 것이라고는 보지 않는다.

어플리케이션은, 승낙한 기능을 모두 제공할 필요가 있다. 다만, 일부의 기능에 대해서는, DMO 가 모든 샘플에 대해 기능을 요구하지 않는 것이 있다. DMO 가 다음의 샘플에 대해 생략 할 수 있는 기능이 있을지 어떨지를 조사하려면 ,GetCurrentSampleRequirements 메소드를 호출한다. 이것에 의해, DMO 는, 1 개의 샘플에 대해서, 승낙 끝난 기능을 방폐할 수가 있다.

스트리밍이 시작되기 전에, 한층 더 이 메소드를 호출하면, 전의 호출은 오버라이드(override) 된다. 복수의 기능을 설정하려면 , 1 회의 메소드 호출로 기능을 설정할 필요가 있다. 스트리밍이 시작되면(자), 이 메소드는 에러를 돌려준다. 스트리밍은, 어플리케이션이 적어도 1 개의 입력 스트림에 대해서 IMediaObject::ProcessInput 를 호출했을 때에 시작된다.

스트리밍이 종료하면, 어플리케이션은 기능을 네고시에이트 할 수 있다. 스트리밍은, 어플리케이션이 IMediaObject::Flush 메소드를 호출했을 때, 또는, 모든 입력 스트림에 대해서 IMediaObject::Discontinuity 를 호출한 후, 잔라고 모든 출력을 처리했을 때에 종료한다.

IDMOVideoOutputOptimizations::GetCurrentOperationMode

IDMOVideoOutputOptimizations 인터페이스

현재 유효한 최적화 기능을 취득한다.

구문

HRESULT GetCurrentOperationMode(
ULONG ulOutputStreamIndex,
    DWORD *pdwEnabledFeatures
);

파라미터

ulOutputStreamIndex
DMO 의 출력 스트림의 제로 베이스의 인덱스.
pdwEnabledFeatures
현재의 기능을 받는 변수를 가리키는 포인터. 돌려주어지는 값은,DMO_VIDEO_OUTPUT_STREAM_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합이다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스
E_POINTER | NULL 포인터 인수

IDMOVideoOutputOptimizations::GetCurrentSampleRequirements

IDMOVideoOutputOptimizations 인터페이스

어플리케이션이 이미 승낙한 기능이 있는 경우에, 다음의 샘플을 처리하는데 필요한 최적화 기능을 취득한다.

구문

HRESULT GetCurrentSampleRequirements(
ULONG ulOutputStreamIndex,
    DWORD *pdwRequestedFeatures
);

파라미터

ulOutputStreamIndex
DMO 의 출력 스트림의 제로 베이스의 인덱스.
pdwRequestedFeatures
필요한 기능을 받는 변수를 가리키는 포인터. 돌려주어지는 값은,DMO_VIDEO_OUTPUT_STREAM_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합이다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스
E_POINTER | NULL 포인터 인수

주의

어플리케이션은,SetOperationMode 메소드를 호출한 후, 승낙한 모든 기능을 제공할 필요가 있다. 다만, 일부의 기능에 대해서는, DMO 가 모든 샘플에 대해서 필요로 하지 않는 것이 있다. DMO 는, 이 메소드를 이용해, 1 개의 샘플에 대해서, 승낙 끝난 기능을 방폐할 수가 있다.

어플리케이션은, 샘플을 처리하기 전에 이 메소드를 호출한다. DMO 는, 다음의 샘플을 처리하기 위해서 특정의 기능을 필요로 하지 않는 경우, 그 기능에 대응하는 플래그를 pdwRequestedFeatures 파라미터로부터 삭제한다. 다음의 샘플에 한해서, 어플리케이션은, 그 기능을 무시할 수 있다. 이 메소드의 결과는,IMediaObject::ProcessOutput 메소드에 대한 다음의 호출해 에 대해서만 유효하다.

DMO 는,SetOperationMode 메소드로 승낙된 플래그만을 돌려준다. 즉, 이 메소드를 사용해 새로운 기능을 동적으로 유효하게 할 수 없다.


IEnumDMO 인터페이스

이 인터페이스는, Microsoft® DirectX® Media Object (DMO)를 열거하기 위한 메소드를 제공한다. 이 인터페이스는, OLE 열거 인터페이스에 근거하고 있다. 상세한 것에 대하여는, Platform SDK 의 「IEnumXXXX」를 참조할것.

등록되어 있는 DMO 를 열거하려면 ,DMOEnum 함수를 호출한다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스를 가리키는 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IEnumDMO 메소드 | 설명
Next | 열거 순서내의 지정된 수의 아이템을 취득한다.
Skip | 열거 순서내의 지정된 수의 아이템을 스킵 한다.
Reset | 열거 순서를 선두에 리셋 한다.
Clone | 이행되어 있지 않다.

IEnumDMO::Next

IEnumDMO 인터페이스

열거 순서내의 지정된 수의 아이템을 취득한다.

구문

HRESULT Next(
    DWORD cItemsToFetch,
    CLSID *pCLSID,
    WCHAR **Names,
    DWORD *pcItemsFetched
);

파라미터

cItemsToFetch
취득하는 아이템의 수.
pCLSID
[out] 열거된 DMO 의 CLSID 가 저장 되는, 사이즈가 cItemsToFetch 의 배열.
Names
[out] 열거된 DMO 의 프렌들리명이 저장 되는, 사이즈가 cItemsToFetch 의 배열.
pcItemsFetched
[out] 실제로 취득된 아이템의 수를 받는 변수를 가리키는 포인터. cItemsToFetch 가 1 의 경우는, NULL 를 지정할 수 있다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_FALSE | 취득한 아이템의 수가 요구된 아이템의 수보다 적다.
S_OK | 요구된 수의 아이템을 취득했다.
E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

이 메소드가 성공하면(자),pCLSID 파라미터와 Names 파라미터에 의해 돌려주어진 배열에는, CLSID 와 와이드 문자의 캐릭터 라인이 저장 된다. *pcItemsFetched 의 값은, 이러한 배열에 의해 돌려주어진 아이템의 수를 나타낸다.

이 메소드는, 요구된 수의 아이템을 취득 하면, 즉,*pcItemsFetched 가 cItemsToFetch 와 동일하면, S_OK 를 돌려준다. 그 이외의 경우, 메소드는 S_FALSE 또는 에러 코드를 돌려준다.

호출원래는,Names 파라미터에 의해 돌려주어진 개개의 캐릭터 라인에 할당할 수 있었던 메모리를,CoTaskMemFree 함수를 사용해 해방할 필요가 있다.

IEnumDMO::Skip

IEnumDMO 인터페이스

열거 순서내의 지정된 수의 아이템을 스킵 한다.

구문

HRESULT Skip(
    DWORD cItemsToSkip
);

파라미터

cItemsToSkip
스킵 하는 아이템의 수.

반환값

스킵 된 아이템의 수가 cItemsToSkip 와 일치하면, S_OK 를 돌려준다. 그 이외의 경우는, S_FALSE 를 돌려준다.

IEnumDMO::Reset

IEnumDMO 인터페이스

열거 순서를 선두에 리셋 한다.

구문

HRESULT Reset(void);

반환값

S_OK 를 돌려준다.

IEnumDMO::Clone

IEnumDMO 인터페이스

이 메소드는 이행되어 있지 않다.

구문

HRESULT Clone(
IEnumDMO **ppEnum
);

반환값

E_NOTIMPL 를 돌려준다.


IMediaBuffer 인터페이스

이 인터페이스는, 데이터 버퍼를 조작하기 위한 메소드를 갖추고 있다. Microsoft® DirectX® Media Object (DMO)에게 건네지는 모든 버퍼는, 이 인터페이스를 이행 할 필요가 있다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스를 가리키는 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaBuffer 메소드 | 설명
SetLength | 현재 버퍼내에 있는 데이터의 길이를 지정한다.
GetMaxLength | 이 버퍼에 저장 할 수 있는 최대 바이트수를 취득한다.
GetBufferAndLength | 버퍼와 버퍼내의 유효한 데이터의 사이즈를 취득한다.

IMediaBuffer::SetLength

IMediaBuffer 인터페이스

현재 버퍼내에 있는 데이터의 길이를 지정한다.

구문

HRESULT SetLength(
   DWORD cbLength
);

파라미터

cbLength
바이트 단위로 나타내는 데이터의 사이즈. 값은 버퍼의 최대 사이즈를 넘어선 안 된다. 최대 사이즈를 취득하려면 ,GetMaxLength 메소드를 호출한다.

반환값

성공하면 S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는, 버퍼에 할당할 수 있었던 사이즈는 아니고, 현재 버퍼내에 있는 유효한 데이터의 사이즈를 설정한다.

IMediaBuffer::GetMaxLength

IMediaBuffer 인터페이스

이 버퍼에 저장 할 수 있는 최대 바이트수를 취득한다.

구문

HRESULT GetMaxLength(
    DWORD *pcbMaxLength
);

파라미터

pcbMaxLength
[out] 버퍼의 최대 사이즈를 바이트 단위로 받는 변수를 가리키는 포인터.

반환값

성공하면 S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

IMediaBuffer::GetBufferAndLength

IMediaBuffer 인터페이스

버퍼와 버퍼내의 유효한 데이터의 사이즈를 취득한다.

구문

HRESULT GetBufferAndLength(
    BYTE **ppBuffer,
    DWORD *pcbLength
);

파라미터

ppBuffer
[out] 버퍼 배열을 받는 포인터의 주소. pcbLength 가 NULL 가 아니면, NULL 를 지정할 수 있다.
pcbLength
[out] 유효한 데이터의 사이즈를 바이트 단위로 받는 변수를 가리키는 포인터. ppBuffer 가 NULL 나오는거야 k, NULL 를 지정할 수 있다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_POINTER | NULL 포인터 인수

주의

어느 쪽인지 한편의 파라미터를 NULL 로 할 수 있다. 그 경우, NULL 로 한 파라미터는, 값을 받지 않는다. 적어도 1 개의 파라미터는, NULL 가 아닌 값으로 할 필요가 있다. 양쪽 모두의 파라미터가 NULL 의 경우, 메소드는 E_POINTER 를 돌려준다.

pcbLength 파라미터에 의해 돌려주어지는 값은, 버퍼에 할당할 수 있었던 사이즈는 아니고, 버퍼내의 유효한 데이터의 사이즈이다. 버퍼에 할당할 수 있었던 사이즈를 취득하려면 ,GetMaxLength 메소드를 호출한다.


IMediaObject 인터페이스

이 인터페이스는, Microsoft® DirectX® Media Object (DMO)를 조작하기 위한 메소드를 갖추고 있다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스를 가리키는 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaObject 메소드 | 설명
GetStreamCount | 입력 스트림과 출력 스트림의 수를 취득한다.
GetInputStreamInfo | 지정된 입력 스트림에 관한 정보를 취득한다.
GetOutputStreamInfo | 지정된 출력 스트림에 관한 정보를 취득한다.
GetInputType | 지정된 입력 스트림의 우선 미디어 타입을 취득한다.
GetOutputType | 지정된 출력 스트림의 우선 미디어 타입을 취득한다.
SetInputType | 입력 스트림의 미디어 타입을 설정한다, 또는 특정의 미디어 타입이 사용 가능한가 어떤가를 테스트한다.
SetOutputType | 출력 스트림의 미디어 타입을 설정한다, 또는 특정의 미디어 타입이 사용 가능한가 어떤가를 테스트한다.
GetInputCurrentType | 전으로 설정된 입력 스트림의 미디어 타입이 있으면, 그것을 취득한다.
GetOutputCurrentType | 전으로 설정된 출력 스트림의 미디어 타입이 있으면, 그것을 취득한다.
GetInputSizeInfo | 지정된 입력 스트림의 버퍼 요건을 취득한다.
GetOutputSizeInfo | 지정된 출력 스트림의 버퍼 요건을 취득한다.
GetInputMaxLatency | 지정된 입력 스트림의 최대 대기 시간을 취득한다.
SetInputMaxLatency | 지정된 입력 스트림의 최대 대기 시간을 설정한다.
Flush | 내부에서 버퍼링 된 모든 데이터를 플래시 한다.
Discontinuity | 지정된 입력 스트림이 중단되고를 알린다.
AllocateStreamingResources | DMO 가 필요로 하는 모든 리소스를 할당한다.
FreeStreamingResources | DMO 가 할당한 리소스를 해방한다.
GetInputStatus | 지정된 입력 스트림이 입력 데이터를 더 이상 받아들여질지 어떨지를 문의한다.
ProcessInput | 지정된 입력 스트림에 버퍼를 배포한다.
ProcessOutput | 현재의 입력 데이터로부터 출력을 생성한다.
Lock | DMO 의 락을 취득 또는 해제한다.

IMediaObject::GetStreamCount

IMediaObject 인터페이스

입력 스트림과 출력 스트림의 수를 취득한다.

구문

HRESULT GetStreamCount(
    DWORD *pcInputStreams,
    DWORD *pcOutputStreams
);

파라미터

pcInputStreams
[out] 입력 스트림의 수를 받는 변수를 가리키는 포인터. NULL 는 지정할 수 없다.
pcOutputStreams
[out] 출력 스트림의 수를 받는 변수를 가리키는 포인터. NULL 는 지정할 수 없다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_POINTER | NULL 포인터 인수

주의

DMO 는 입력 스트림 또는 출력 스트림을 전혀 가지고 있지 않은 것이 있다. 스트림의 수는 변함없다. DMO 는 스트림을 동적으로 추가 또는 삭제할 수 없다.

IMediaObject::GetInputStreamInfo

IMediaObject 인터페이스

버퍼 근처의 샘플수에 관한 제한, 스트림이 입력 데이터에 대해서룩 어해드를 실행할지 어떨지 등, 입력 스트림에 관한 정보를 취득한다. 이 정보가 바뀔 것은 없다.

구문

HRESULT GetInputStreamInfo(
DWORD dwInputStreamIndex,
DWORD *pdwFlags
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.
pdwFlags
[out] 0 개 이상의 DMO_INPUT_STREAM_INFO_FLAGS 플래그의 비트 단위의 논리합을 받는 변수를 가리키는 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스
E_POINTER | NULL 포인터 인수

주의

DMO_INPUT_STREAMF_HOLDS_BUFFERS 플래그는, DMO 가 입력 데이터에 대해서 룩 어해드를 실행하는 것을 나타낸다.

어플리케이션은, DMO 가 입력을 처리하는데 충분한 버퍼를 할당할 필요가 있다. 버퍼 요건을 조사하려면 ,GetInputSizeInfo 메소드를 호출한다.

IMediaObject::GetOutputStreamInfo

IMediaObject 인터페이스

스트림을 파기할 수 있을지 어떨지, 스트림이 고정 샘플 사이즈를 사용할지 어떨지 등, 출력 스트림에 관한 정보를 취득한다. 이 정보가 바뀔 것은 없다.

구문

HRESULT GetOutputStreamInfo(
DWORD dwOutputStreamIndex,
DWORD *pdwFlags
);

파라미터

dwOutputStreamIndex
DMO 의 출력 스트림의 제로 베이스의 인덱스.
pdwFlags
[out] 0 개 이상의 DMO_OUTPUT_STREAM_INFO_FLAGS 플래그의 비트 단위의 논리합을 받는 변수를 가리키는 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스
E_POINTER | NULL 포인터 인수

IMediaObject::GetInputType

IMediaObject 인터페이스

지정된 입력 스트림의 우선 미디어 타입을 취득한다.

구문

HRESULT GetInputType(
DWORD dwInputStreamIndex,
DWORD dwTypeIndex,
DMO_MEDIA_TYPE *pmt
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.
dwTypeIndex
사용 가능한 미디어 타입세트의 제로 베이스의 인덱스.
pmt
[out] 호출 바탕으로야는 할당할 수 있었던 DMO_MEDIA_TYPE 구조체를 가리키는 포인터. 메소드는 구조체에 미디어 타입을 저장 한다. 포맷 블록은 NULL 가 되는 일이 있다. 그 경우의 포맷 타입 GUID 는 GUID_NULL 이다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
DMO_E_NO_MORE_ITEMS | 타입 인덱스가 범위외이다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

이 메소드를 호출해, 입력 스트림의 우선 미디어 타입을 열거한다. DMO 는, 우선 순위에 따라, 개개의 미디어 타입에 인덱스값을 할당한다. 최우선 타입의 인덱스는 0 이 된다. 모든 타입을 열거하려면 , 메소드가 DMO_E_NO_MORE_ITEMS 를 돌려줄 때까지, 타입 인덱스를 인크리먼트(increment) 하면서, 호출을 반복한다.

메소드가 성공하면(자),MoFreeMediaType 를 호출해 포맷 블록을 해방한다.

미디어 타입을 설정하려면 ,SetInputType 메소드를 호출한다. 1 개의 스트림의 미디어 타입을 설정 하면, 다른 스트림의 우선 타입이 바뀌는 일이 있다. 실제, 스트림은, 다른 스트림의 타입이 설정될 때까지, 우선 타입을 가지지 않는 것이 있다. 예를 들어, 디코더는, 입력 타입이 설정될 때까지 우선 출력 타입을 가지지 않는 것이 있다. 다만, DMO 는, 이 방법으로 동적으로 우선 타입을 갱신할 필요는 없다. 따라서, 이 메소드에 의해 돌려주어지는 타입이 유효하다 (일)것은 보증되지 않는다. 돌려주어지는 타입을 SetInputType 메소드로 사용 하면, 실패하는 일이 있다. 반대로, DMO 가, 지원 하는 모든 미디어 타입을 열거하는 일도 보증되지 않는다. 특정의 미디어 타입이 사용 가능한가 어떤가를 테스트하려면 , DMO_SET_TYPEF_TEST_ONLY 플래그를 설정해 SetInputType 를 호출한다.

pmt 파라미터는 NULL 를 취할 수 있다. 이 경우, 타입 인덱스가 범위내라면, 메소드는 S_OK 를 돌려준다. 그 이외라면, DMO_E_NO_MORE_ITEMS 화원인가의 에러 코드를 돌려준다.

IMediaObject::GetOutputType

IMediaObject 인터페이스

지정된 출력 스트림의 우선 미디어 타입을 취득한다.

구문

HRESULT GetOutputType(
DWORD dwOutputStreamIndex,
DWORD dwTypeIndex,
DMO_MEDIA_TYPE *pmt
);

파라미터

dwOutputStreamIndex
DMO 의 출력 스트림의 제로 베이스의 인덱스.
dwTypeIndex
사용 가능한 미디어 타입세트의 제로 베이스의 인덱스.
pmt
[out] 호출 바탕으로야는 할당할 수 있었던 DMO_MEDIA_TYPE 구조체를 가리키는 포인터. 메소드는 구조체에 미디어 타입을 저장 한다. 포맷 블록은 NULL 가 되는 일이 있다. 그 경우의 포맷 타입 GUID 는 GUID_NULL 이다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
DMO_E_NO_MORE_ITEMS | 타입 인덱스가 범위외이다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

이 메소드를 호출해, 출력 스트림의 우선 미디어 타입을 열거한다. DMO 는, 우선 순위에 따라, 개개의 미디어 타입에 인덱스값을 할당한다. 최우선 타입의 인덱스는 0 이 된다. 모든 타입을 열거하려면 , 메소드가 DMO_E_NO_MORE_ITEMS 를 돌려줄 때까지, 타입 인덱스를 인크리먼트(increment) 하면서, 호출을 반복한다.

메소드가 성공하면(자),MoFreeMediaType 를 호출해 포맷 블록을 해방한다.

미디어 타입을 설정하려면 ,SetOutputType 메소드를 호출한다. 1 개의 스트림의 미디어 타입을 설정 하면, 다른 스트림의 우선 타입이 바뀌는 일이 있다. 실제, 스트림은, 다른 스트림의 타입이 설정될 때까지, 우선 타입을 가지지 않는 것이 있다. 예를 들어, 디코더는, 입력 타입이 설정될 때까지 우선 출력 타입을 가지지 않는 것이 있다. 다만, DMO 는, 이 방법으로 동적으로 우선 타입을 갱신할 필요는 없다. 따라서, 이 메소드에 의해 돌려주어지는 타입이 유효하다 (일)것은 보증되지 않는다. 돌려주어지는 타입을 SetOutputType 메소드로 사용 하면, 실패하는 일이 있다. 반대로, DMO 가, 지원 하는 모든 미디어 타입을 열거하는 일도 보증되지 않는다. 특정의 미디어 타입이 사용 가능한가 어떤가를 테스트하려면 , DMO_SET_TYPEF_TEST_ONLY 플래그를 설정해 SetOutputType 를 호출한다.

pmt 파라미터는 NULL 를 취할 수 있다. 이 경우, 타입 인덱스가 범위내라면, 메소드는 S_OK 를 돌려준다. 그 이외라면, DMO_E_NO_MORE_ITEMS 화원인가의 에러 코드를 돌려준다.

IMediaObject::SetInputType

IMediaObject 인터페이스

입력 스트림의 미디어 타입을 설정한다, 또는 미디어 타입이 사용 가능한가 어떤가를 테스트한다.

구문

HRESULT SetInputType(
DWORD dwInputStreamIndex,
const DMO_MEDIA_TYPE *pmt,
DWORD dwFlags
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.
pmt
[in] 미디어 타입을 지정하는 DMO_MEDIA_TYPE 구조체를 가리키는 포인터.
dwFlags
DMO_SET_TYPE_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 미디어 타입이 올바르게 설정된, 또는 사용 가능하다.
S_FALSE | 미디어 타입을 사용할 수 없다.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
DMO_E_TYPE_NOT_ACCEPTED | 미디어 타입이 받아들여지지 않았다.

주의

이 메소드를 호출해, 입력 스트림의 미디어 타입을 테스트, 설정 또는 소거한다.

  • 미디어 타입을 설정하지 않고 테스트하려면 , DMO_SET_TYPEF_TEST_ONLY 플래그를 사용한다. 미디어 타입을 사용할 수 없으면, 메소드는 S_FALSE 를 돌려준다.
  • 미디어 타입을 설정하려면 ,dwFlags 를 제로로 설정한다. 미디어 타입이 사용 불능이면, 메소드는 DMO_E_TYPE_NOT_ACCEPTED 를 돌려준다.
  • 현재 설정되어 있는 미디어 타입을 소거하려면 , DMO_SET_TYPEF_CLEAR 플래그를 사용해,pmt 를 NULL 로 설정한다. 메소드가 종료 하면, 스트림으로 설정되어 있는 미디어 타입은 없어진다. DMO 는, 어플리케이션이 새로운 미디어 타입을 설정할 때까지, 샘플을 처리할 수 없다.

현재 다른 스트림에 대해서 설정되어 있는 미디어 타입에 의해, 미디어 타입이 사용 가능한가 어떤가가 영향을 받는 일이 있다.

IMediaObject::SetOutputType

IMediaObject 인터페이스

출력 스트림의 미디어 타입을 설정한다, 또는 미디어 타입이 사용 가능한가 어떤가를 테스트한다.

구문

HRESULT SetOutputType(
DWORD dwOutputStreamIndex,
const DMO_MEDIA_TYPE *pmt,
DWORD dwFlags
);

파라미터

dwOutputStreamIndex
DMO 의 출력 스트림의 제로 베이스의 인덱스.
pmt
[in] 미디어 타입을 지정하는 DMO_MEDIA_TYPE 구조체를 가리키는 포인터.
dwFlags
DMO_SET_TYPE_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 미디어 타입이 올바르게 설정된, 또는 사용 가능하다.
S_FALSE | 미디어 타입을 사용할 수 없다.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
DMO_E_TYPE_NOT_ACCEPTED | 미디어 타입이 받아들여지지 않았다.

주의

이 메소드를 호출해, 출력 스트림의 미디어 타입을 테스트, 설정 또는 소거한다.

  • 미디어 타입을 설정하지 않고 테스트하려면 , DMO_SET_TYPEF_TEST_ONLY 플래그를 사용한다. 미디어 타입을 사용할 수 없으면, 메소드는 S_FALSE 를 돌려준다.
  • 미디어 타입을 설정하려면 ,dwFlags 를 제로로 설정한다. 미디어 타입이 사용 불능이면, 메소드는 DMO_E_TYPE_NOT_ACCEPTED 를 돌려준다.
  • 현재 설정되어 있는 미디어 타입을 소거하려면 , DMO_SET_TYPEF_CLEAR 플래그를 사용해,pmt 를 NULL 로 설정한다. 메소드가 종료 하면, 스트림으로 설정되어 있는 미디어 타입은 없어진다. 스트림이 옵션 스트림이 아닌 한, DMO 는 어플리케이션이 새로운 미디어 타입을 설정할 때까지, 샘플을 처리할 수 없다.

현재 다른 스트림에 대해서 설정되어 있는 미디어 타입에 의해, 미디어 타입이 사용 가능한가 어떤가가 영향을 받는 일이 있다.

IMediaObject::GetInputCurrentType

IMediaObject 인터페이스

설정된 입력 스트림의 미디어 타입이 있으면, 그것을 취득한다.

구문

HRESULT GetInputCurrentType(
DWORD dwInputStreamIndex,
DMO_MEDIA_TYPE *pmt
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.
pmt
[out] 호출 바탕으로야는 할당할 수 있었던 DMO_MEDIA_TYPE 구조체를 가리키는 포인터. 메소드는 구조체에 미디어 타입을 저장 한다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
DMO_E_TYPE_NOT_SET | 미디어 타입이 설정되지 않았다.
E_OUTOFMEMORY | 메모리 부족.

주의

호출원래는, 이 메소드를 호출하기 전에, 스트림의 미디어 타입을 설정할 필요가 있다. 미디어 타입을 설정하려면 ,SetInputType 메소드를 호출한다.

메소드가 성공하면(자),MoFreeMediaType 를 호출해 포맷 블록을 해방한다.

IMediaObject::GetOutputCurrentType

IMediaObject 인터페이스

설정된 출력 스트림의 미디어 타입이 있으면, 그것을 취득한다.

구문

HRESULT GetOutputCurrentType(
DWORD dwOutputStreamIndex,
DMO_MEDIA_TYPE *pmt
);

파라미터

dwOutputStreamIndex
DMO 의 출력 스트림의 제로 베이스의 인덱스.
pmt
[out] 호출 바탕으로야는 할당할 수 있었던 DMO_MEDIA_TYPE 구조체를 가리키는 포인터. 메소드는 구조체에 미디어 타입을 저장 한다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
DMO_E_TYPE_NOT_SET | 미디어 타입이 설정되지 않았다.
E_OUTOFMEMORY | 메모리 부족.

주의

호출원래는, 이 메소드를 호출하기 전에, 스트림의 미디어 타입을 설정할 필요가 있다. 미디어 타입을 설정하려면 ,SetOutputType 메소드를 호출한다.

메소드가 성공하면(자),MoFreeMediaType 를 호출해 포맷 블록을 해방한다.

IMediaObject::GetInputSizeInfo

IMediaObject 인터페이스

지정된 입력 스트림의 버퍼 요건을 취득한다.

구문

HRESULT GetInputSizeInfo(
DWORD dwInputStreamIndex,
DWORD *pcbSize,
    DWORD *pcbMaxLookahead,
DWORD *pcbAlignment
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.
pcbSize
[out] 이 스트림의 입력 버퍼의 최소 사이즈를 바이트 단위로 받는 변수를 가리키는 포인터.
pcbMaxLookahead
[out] DMO 가룩 어해드용으로 보관 유지하는 최대 데이터량을 바이트 단위로 받는 변수를 가리키는 포인터. DMO 가 스트림에 대해서 룩 어해드를 실행하지 않는 경우의 값은 0 이다.
pcbAlignment
[out] 필요한 버퍼 alignment를 바이트 단위로 받는 변수를 가리키는 포인터. 입력 스트림에 alignment 요건이 없는 경우의 값은 1 이다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
DMO_E_TYPE_NOT_SET | 미디어 타입이 설정되지 않았다.

주의

버퍼 요건은, 다양한 스트림의 미디어 타입에 따라서 다른 일이 있다. 이 메소드를 호출하기 전에,SetInputType 메소드와 SetOutputType 메소드를 호출하는 것에 의해, 각 스트림의 미디어 타입을 설정한다. 미디어 타입이 설정되어 있지 않은 경우, 이 메소드는 에러를 돌려주는 일이 있다.

DMO 가 입력 스트림에 대해서 룩 어해드를 실행하는 경우, DMO 는 GetInputStreamInfo 메소드로 DMO_INPUT_STREAMF_HOLDS_BUFFERS 플래그를 돌려준다. DMO 는, 처리중에,pcbMaxLookahead 파라미터가 가리키는 수를 최대 바이트 수라고 하는 데이터를 보관 유지한다. 어플리케이션은, DMO 가 그 만큼의 양의 데이터를 보관 유지하는데 충분한 버퍼를 할당할 필요가 있다.

버퍼의 시작 주소가 *pcbAlignment 의 배수이면, 버퍼는 "아라인" 되고 있다. alignment는, 2 의 거듭제곱이 아니면 안된다. 마이크로 프로세서에 따라서는, 아라인 되고 있는 버퍼에 대한 독해, 기입이, 아라인되어 있지 않은 버퍼에 대한 독해, 기입보다 빠르다. 또, 일부의 마이크로 프로세서는, 아라인되어 있지 않은 독해와 기입을 지원 하고 있지 않다.

IMediaObject::GetOutputSizeInfo

IMediaObject 인터페이스

지정된 출력 스트림의 버퍼 요건을 취득한다.

구문

HRESULT GetOutputSizeInfo(
DWORD dwOutputStreamIndex,
DWORD *pcbSize,
DWORD *pcbAlignment
);

파라미터

dwOutputStreamIndex
DMO 의 출력 스트림의 제로 베이스의 인덱스.
pcbSize
[out] 이 스트림의 출력 버퍼의 최소 사이즈를 바이트 단위로 받는 변수를 가리키는 포인터.
pcbAlignment
[out] 필요한 버퍼 alignment를 바이트 단위로 받는 변수를 가리키는 포인터. 출력 스트림에 alignment 요건이 없는 경우의 값은 1 이다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
DMO_E_TYPE_NOT_SET | 미디어 타입이 설정되지 않았다.

주의

버퍼 요건은, 각 스트림에 대해서 설정되어 있는 미디어 타입에 따라서 다른 일이 있다.

이 메소드를 호출하기 전에,SetInputType 메소드와 SetOutputType 메소드를 호출하는 것에 의해, 각 스트림의 미디어 타입을 설정한다. 미디어 타입이 설정되어 있지 않은 경우, 이 메소드는 에러를 돌려주는 일이 있다. 다만, 스트림이 옵션 스트림이면, 어플리케이션은 스트림을 사용하지 않고, 스트림의 미디어 타입을 설정할 필요도 없다.

버퍼의 시작 주소가 *pcbAlignment 의 배수이면, 버퍼는 "아라인" 되고 있다. 마이크로 프로세서의 아키텍쳐에 따라서는, 아라인 된 버퍼에 대한 독해, 기입이, 아라인되어 있지 않은 버퍼에 대한 독해, 기입보다 빠르다. 일부의 마이크로 프로세서에서는, 아라인되어 있지 않은 버퍼에 대한 독해, 기입이 지원되어 있지 않기 때문에, 이것을 실행 하면 프로그램이 크래쉬 하는 일이 있다. 0 은 유효한 alignment는 아니다.

IMediaObject::GetInputMaxLatency

IMediaObject 인터페이스

지정된 입력 스트림의 최대 대기 시간을 취득한다.

구문

HRESULT GetInputMaxLatency(
DWORD dwInputStreamIndex,
    REFERENCE_TIME *prtMaxLatency
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.
prtMaxLatency
[out] 최대 대기 시간을 받는 변수를 가리키는 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
E_FAIL | 실패.
E_NOTIMPL | 이행되어 있지 않다. 대기 시간 제로로 본다.

대기 시간이란, 입력 스트림 위에의 타임 스탬프와 거기에 대응하는 출력 스트림 위에의 타임 스탬프와의 차이이다. 최대 대기 시간은, 2 개의 타임 스탬프간에 생길 가능성이 있는 최대의 차이이다. DMO 의 경우는, 다음과 같이 해 최대 대기 시간을 조사한다.

  • DMO 가 출력을 생성할 수 있게 될 때까지, 입력 버퍼를 처리한다.
  • 가능한 한 많은 출력 버퍼를 처리한다.
  • 최대 대기 시간은, 입력 타임 스탬프와 출력 타임 스탬프의 사이의 최대 증분 (절대치)이다.

이 정의에 의하면, 대기 시간에는 샘플을 처리하는 시간은 포함되지 않는다. 또, 입력 버퍼의 사이즈가 요인이 되는 대기 시간도 포함되지 않는다.

DMO 가 한 번에 1 개의 샘플만을 처리하는 특수한 경우의 최대 대기 시간은, 단지 타임 스탬프간의 차이이다.

대기 시간은, 샘플이 타임 스탬프를 가지고 있어 타임 스탬프가 단조 증가 혹은 단조 감소하는 경우에게만 정의된다. 최대 대기 시간은, 입력 스트림 및 출력 스트림의 미디어 타입에 따라서 다른 일이 있다.

IMediaObject::SetInputMaxLatency

IMediaObject 인터페이스

지정된 입력 스트림의 최대 대기 시간을 설정한다. 최대 대기 시간의 정의에 대해서는, 「GetInputMaxLatency 」를 참조할것.

구문

HRESULT SetInputMaxLatency(
DWORD dwInputStreamIndex,
    REFERENCE_TIME rtMaxLatency
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.
rtMaxLatency
최대 대기 시간.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스
E_FAIL | 실패
E_NOTIMPL | 이행되어 있지 않다

IMediaObject::Flush

IMediaObject 인터페이스

내부에서 버퍼링 된 모든 데이터를 플래시 한다.

구문

HRESULT Flush(void);

반환값

성공하면 S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드가 불려 가면(자), DMO 는 이하의 조작을 실시한다.

  • 보관 유지하고 있는 모든 IMediaBuffer 참조를 해방한다.
  • 미디어 버퍼의 타임 스탬프 또는 샘플장을 지정하는 모든 값을 파기한다.
  • 미디어 샘플의 내용에 의존하는 모든 내부 상태를 재초기화한다.

미디어 타입, 최대 대기 시간, 및 락 상태는 변함없다.

메소드가 종료 하면, 모든 입력 스트림은 데이터를 받아들인다. 출력 스트림은, 어플리케이션이 적어도 1 개의 입력 스트림에 대해서 ProcessInput 메소드를 호출할 때까지, 데이터를 생성할 수 없다.

IMediaObject::Discontinuity

IMediaObject 인터페이스

지정된 입력 스트림이 중단되고를 알린다.

구문

HRESULT Discontinuity(
    DWORD dwInputStreamIndex
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스

주의

중단되고는 입력의 중단에 상당한다. 중단되고는, 입력 데이터가 없어진, 포맷이 변경된, 데이터에 갭이 있는, 등의 이유로써 발생한다. 중단되고가 발생 하면, DMO 는, 보류 떠날 수 있어 모든 데이터가 처리될 때까지, 그 스트림의 입력을 그 이상 받아들이지 않게 된다. 어플리케이션은, DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE 플래그를 돌려주는 스트림이 없어질 때까지,ProcessOutput 메소드를 호출할 필요가 있다.

IMediaObject::AllocateStreamingResources

IMediaObject 인터페이스

DMO 가 필요로 하는 모든 리소스를 할당한다. 이 메소드의 호출은, 항상 생략 할 수 있다.

구문

HRESULT AllocateStreamingResources(void);

반환값

성공하면 S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

어플리케이션은, 스트리밍 최적화로서 이 메소드를 호출할 수가 있다. 이 메소드를 이용해, DMO 는, 스트리밍이 시작되기 전에, 시간이 걸리는 모든 초기화를 실행할 수 있다. 이 메소드를 호출하는 경우는, DMO 의 미디어 타입을 설정한 후, 최초로 ProcessInput 또는 ProcessOutput 를 호출하기 전에, 메소드를 호출하는 것.

이 메소드는, 다음의 의미로 옵션이다.

  • DMO 가 이 메소드를 지원 하지 않는 경우, 메소드는 S_OK 를 돌려준다.
  • 어플리케이션이 이 메소드를 호출하지 않는 경우, DMO 는 ProcessInput 또는 ProcessOutput 에 대한 호출 중(안)에서 리소스를 할당한다.

DMO 가 이 메소드를 지원 하는 경우, 그 DMO 는 FreeStreamingResources 메소드도 지원 할 필요가 있다.

IMediaObject::FreeStreamingResources

IMediaObject 인터페이스

DMO 가 할당한 리소스를 해방한다. 이 메소드의 호출은, 항상 생략 할 수 있다.

구문

HRESULT FreeStreamingResources(void);

반환값

성공하면 S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는,AllocateStreamingResources 메소드가 초기화하는 모든 리소스를 해방한다.

DMO 가 이 메소드를 지원 하지 않는 경우, 메소드는 S_OK 를 돌려준다. 스트리밍의 한중간에 이 메소드를 호출하면, 메소드는 실패해, DMO 네차이의 리소스도 해방하지 않는다.

메소드가 성공하는지, 실패할까에 관계없이, 어플리케이션은, DMO 에 대하는 것 외의 메소드의 호출을 계속할 수가 있다. DMO 가 전에 해방된 리소스를 재초기화하는 것이 필요하게 될 수도 있다.

IMediaObject::GetInputStatus

IMediaObject 인터페이스

입력 스트림이 입력 데이터를 더 이상 받아들여질지 어떨지를 문의한다.

구문

HRESULT GetInputStatus(
DWORD dwInputStreamIndex,
    DWORD *dwFlags
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.
dwFlags
[out] 제로 또는 DMO_INPUT_STATUSF_ACCEPT_DATA 를 받는 변수를 가리키는 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스

주의

입력 스트림이 데이터를 더 이상 받아들이는 경우, 메소드는,dwFlags 파라미터에 의해 DMO_INPUT_STATUSF_ACCEPT_DATA 플래그를 돌려준다. 그 이외의 경우, 메소드는 이 파라미터를 제로로 설정한다. 스트림이 데이터를 더 이상 받아들이는 경우, 어플리케이션은 ProcessInput 메소드를 호출할 수가 있다.

입력 스트림 상태가 바뀌는 것은, 이하의 몇개의 메소드를 호출했을 때에 한정된다.

  • Discontinuity
  • Flush
  • ProcessInput
  • ProcessOutput

IMediaObject::ProcessInput

IMediaObject 인터페이스

지정된 입력 스트림에 버퍼를 배포한다.

구문

HRESULT ProcessInput(
DWORD dwInputStreamIndex,
    IMediaBuffer *pBuffer,
DWORD dwFlags,
    REFERENCE_TIME rtTimestamp,
    REFERENCE_TIME rtTimelength
);

파라미터

dwInputStreamIndex
DMO 의 입력 스트림의 제로 베이스의 인덱스.
pBuffer
버퍼의 IMediaBuffer 인터페이스를 가리키는 포인터.
dwFlags
DMO_INPUT_DATA_BUFFER_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합.
rtTimestamp
버퍼내의 데이터의 시작 타임을 지정하는 타임 스탬프. 버퍼가 유효한 타임 스탬프를 가지고 있는 경우는,dwFlags 파라미터로 DMO_INPUT_DATA_BUFFERF_TIME 플래그를 설정한다. 그 이외의 경우, DMO 는 이 값을 무시한다.
rtTimelength
버퍼내의 데이터의 시간폭을 지정하는 기준 시간. 이 값이 유효한 경우는,dwFlags 파라미터로 DMO_INPUT_DATA_BUFFERF_TIMELENGTH 플래그를 설정한다. 그 이외의 경우, DMO 는 이 값을 무시한다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_FALSE | 처리하는 출력이 없다
S_OK | 성공.
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스.
DMO_E_NOTACCEPTING | 데이터를 받아들여지지 않는다.

주의

DMO 가 버퍼내의 모든 데이터를 처리하지 않는 경우, 그 DMO 는 버퍼의 참조 카운트를 보관 유지한다. DMO 는, 데이터에 대해서 룩 어해드를 실행할 필요가 있는 경우를 제외해, 모든 출력을 생성한 후, 버퍼를 해방한다. DMO 가 룩 어해드를 실행할지 어떨지를 조사하려면 ,GetInputStreamInfo 메소드를 호출한다.

이 메소드가 DMO_E_NOTACCEPTING 를 돌려주었을 경우는, 입력 스트림이 데이터를 더 이상 받아들이게 될 때까지,ProcessOutput 메소드를 호출한다. 스트림이 데이터를 더 이상 받아들여질지 어떨지를 조사하려면 ,GetInputStatus 메소드를 호출한다.

메소드가 S_FALSE 를 돌려주었을 경우, 이 입력으로부터 출력은 생성되어 있지 않다. 그 경우, 어플리케이션은 ProcessOutput 를 호출할 필요는 없다. 다만, 이 경우, DMO 는 S_FALSE 를 돌려줄 필요는 없다. DMO 는 S_OK 를 돌려주는 일이 있다.

IMediaObject::ProcessOutput

IMediaObject 인터페이스

현재의 입력 데이터로부터 출력을 생성한다.

구문

HRESULT ProcessOutput(
DWORD dwFlags,
    DWORD cOutputBufferCount,
    DMO_OUTPUT_DATA_BUFFER *pOutputBuffers,
    DWORD *pdwStatus
);

파라미터

dwFlags
DMO_PROCESS_OUTPUT_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합.
cOutputBufferCount
출력 버퍼의 수.
pOutputBuffers
[in, out] 출력 버퍼가 저장 된 DMO_OUTPUT_DATA_BUFFER 구조체의 배열을 가리키는 포인터. cOutputBufferCount 파라미터로 배열의 사이즈를 지정한다.
pdwStatus
[out] 예약 끝난 값 (제로)을 받는 변수를 가리키는 포인터. 어플리케이션은 이 값을 무시할 필요가 있다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_FALSE | 출력이 생성되지 않았다.
S_OK | 성공.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수.
E_POINTER | NULL 포인터 인수.

주의

pOutputBuffers 파라미터는, DMO_OUTPUT_DATA_BUFFER 구조체의 배열을 가리킨다. 어플리케이션은, 각 출력 스트림에 대해서 1 개의 구조체를 할당할 필요가 있다. GetStreamCount 메소드를 호출해, 출력 스트림의 수를 조사한다. cOutputBufferCount 파라미터를 그 수로 설정한다.

개개의 DMO_OUTPUT_DATA_BUFFER 구조체에는, 버퍼의 IMediaBuffer 인터페이스를 가리키는 포인터가 저장 되고 있다. 어플리케이션은 이러한 버퍼를 할당한다. 구조체외의 멤버는, 상태 필드이다. 메소드가 성공하면(자), DMO 는 이러한 필드를 설정한다. 메소드가 실패 하면, 이러한 값은 확정하지 않는다.

어플리케이션이 ProcessOutput 를 호출하면, DMO 는 가능한 한 많은 입력 데이터를 처리한다. DMO 는, 각 버퍼내의 데이터의 말미로부터 순서에 출력 데이터를 출력 버퍼에 기입한다. 데이터의 말미를 찾아내려면 ,IMediaBuffer::GetBufferAndLength 메소드를 호출한다. DMO 가 출력 버퍼의 참조 카운트를 보관 유지할 것은 없다.

DMO 가 저장 한 데이터로 출력 버퍼가 가득 된 상태로, 아직 처리하는 입력 데이터가 있는 경우, DMO 는 DMO_OUTPUT_DATA_BUFFER 구조체에 의해 DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE 플래그를 돌려준다. 어플리케이션은, 각 구조체의 dwStatus 멤버를 테스트하는 것에 의해, 이 플래그의 유무를 체크할 필요가 있다.

메소드가 S_FALSE 를 돌려주었을 경우, 출력은 생성되어 있지 않다. 다만, 이 경우, DMO 는 S_FALSE 를 돌려줄 필요는 없다. DMO 는 S_OK 를 돌려주는 일이 있다.

데이터의 파기

dwFlags 파라미터로 DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER 플래그를 설정하는 것으로써, 스트림의 데이터를 파기할 수가 있다. 파기하는 각 스트림에 대해서, DMO_OUTPUT_DATA_BUFFER 구조체의 pBuffer 멤버를 NULL 로 설정한다.

pBuffer 가 NULL 인 개개의 스트림은, 이하와 같이 처리된다.

  • DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER 플래그가 설정되어 있어 한편, 스트림이 파기 가능 또는 옵션 스트림이면, DMO 는 데이터를 파기한다.
  • 플래그는 설정되어 있지만, 스트림이 파기 가능해도 옵션 스트림도 아닌 경우, DMO 는 가능하면 데이터를 파기한다. DMO 가 데이터를 파기하는 것은 보증되지 않는다.
  • 플래그가 설정되어 있지 않은 경우, DMO 는 그 스트림의 출력 데이터를 생성하지 않지만, 데이터는 파기하지 않는다.

스트림이 파기 가능 또는 옵션 스트림일지 어떨지를 확인하려면 ,GetOutputStreamInfo 메소드를 호출한다.

IMediaObject::Lock

IMediaObject 인터페이스

DMO 의 락을 취득 또는 해제한다. 복수의 조작을 실행할 경우에, 이 메소드를 호출해, DMO 를 계속해 처리된 상태에 유지한다.

구문

HRESULT Lock(
    LONG bLock
);

파라미터

bLock
락을 취득하는지 해제하는지를 지정하는 값. 값이 0 이외의 경우는 락이 취득된다. 값이 0 의 경우는 락이 해제된다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_FAIL | 실패

주의

이 메소드는, 다른 thread가 DMO 에 대한 메소드를 호출하지 않게 한다. 다른 thread가 DMO 에 대한 메소드를 호출하면, 그 thread는 락이 해제될 때까지 동작을 정지한다.


IMediaObjectInPlace 인터페이스

이 인터페이스는, 데이터가 존재하는 장소에서 데이터를 처리하기 위한 메소드를 갖추고 있다. 이하의 조건이 채워지고 있으면, Microsoft® DirectX® Media Object (DMO)는 이 인터페이스를 공개할 수 있다.

  • DMO 가 1 개의 입력 스트림과 1 개의 출력 스트림을 가지고 있다.
  • 양쪽 모두의 스트림이 같은 미디어 타입을 사용하고 있다.
  • 출력이, 입력 데이터의 존재하는 버퍼상에서, 즉 데이터를 카피하는 일 없이, 생성된다.

이 인터페이스는, 최적화된 데이터 처리 수단을 제공한다. 어플리케이션은,IMediaObject::ProcessInput 메소드와 IMediaObject::ProcessOutput 메소드를 호출하는 대신에, 1 개의 Process 메소드를 호출한다. 다만, 이 인터페이스를 이행 하는 DMO 는, 반드시 IMediaObject 인터페이스도 이행 할 필요가 있다. 따라서, 어플리케이션에는 이 인터페이스를 사용할 의무는 없고, DMO 가 이 인터페이스를 이행 하는 일도 보증되지 않는다.

Vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스를 가리키는 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaObjectInPlace 메소드 | 설명
Process | 데이터의 블록을 처리한다.
Clone | 현재 상태의 DMO 의 카피를 생성 한다.
GetLatency | 이 DMO 에 의해 생기는 대기 시간을 취득한다.

IMediaObjectInPlace::Process

IMediaObjectInPlace 인터페이스

데이터의 블록을 처리한다. 어플리케이션은 입력 데이터의 블록을 가리키는 포인터를 공급한다. DMO 는 지정된 장소에서 데이터를 처리한다.

구문

HRESULT Process(
    ULONG ulSize,
    BYTE *pData
    REFERENCE_TIME refTimeStart,
    DWORD dwFlags
);

파라미터

ulSize
[in] 바이트 단위로 나타내는 데이터의 사이즈.
pData
[in, out] 사이즈가 ulSize 의 버퍼를 가리키는 포인터. 입력시에는 버퍼에 입력 데이터가 저장 된다. 메소드가 정상적으로 종료 하면, 버퍼에는 출력 데이터가 저장 된다.
refTimeStart
[in] 데이터의 시작 타임.
dwFlags
[in] DMO_INPLACE_NORMAL 또는 DMO_INPLACE_ZERO 의 언젠가. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_FALSE | 성공. 처리하는 데이터가 아직 있다.
S_TRUE | 성공. 처리하는 데이터가 남지 않았다.
E_FAIL | 실패.

주의

메소드가 실패 하면, 버퍼에 불요 데이터가 남는 일이 있다. 어플리케이션은 버퍼의 내용을 이용해서는 안된다.

DMO 는, 입력 데이터의 길이를 넘는 출력 데이터를 생성하는 일이 있다. 이 현상은 "이펙트 테일" 로 불린다. 예를 들어, 잔향 이펙트는, 입력이 무음이 된 후도 계속한다. DMO 로 이펙트 테일이 발생 하면, 이 메소드는 S_FALSE 를 돌려준다.

어플리케이션에 처리하는 입력 데이터가 있는 동안은,dwFlags 파라미터를 DMO_INPLACE_NORMAL 로 설정해 Process 메소드를 호출한다. 이 호출이 S_FALSE 를 돌려주면(자), 입력 버퍼를 제로로 해, DMO_INPLACE_ZERO 플래그를 설정해,Process 를 다시 호출한다. DMO 는 제로 된 버퍼에 이펙트 테일을 저장 한다. 반환값이, DMO 가 이펙트 테일의 처리를 종료한 것을 나타내는 S_TRUE 가 될 때까지, 이 방법으로 Process 의 호출을 반복한다.

DMO 로 이펙트 테일이 발생하지 않으면, 이 메소드는 항상 S_TRUE (또는 에러 코드)를 돌려준다.

IMediaObjectInPlace::Clone

IMediaObjectInPlace 인터페이스

현재 상태의 DMO 의 카피를 생성 한다.

구문

HRESULT Clone(
    IMediaObjectInPlace **ppMediaObject
);

파라미터

ppMediaObject
[out] 새로운 DMO 의 IMediaObjectInPlace 인터페이스를 받는 포인터의 주소.

반환값

성공하면 S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

메소드가 성공하면(자), 메소드가 돌려주는 IMediaObjectInPlace 인터페이스에는 미처리의 참조 카운트가 남는다. 인터페이스를 다 사용했으면 , 반드시 인터페이스를 해방하는 것.

IMediaObjectInPlace::GetLatency

IMediaObjectInPlace 인터페이스

이 DMO 에 의해 생기는 대기 시간을 취득한다.

구문

HRESULT GetLatency(
    REFERENCE_TIME *pLatencyTime
);

파라미터

pLatencyTime
[out] 대기 시간을 100 나노초단위로 받는 변수를 가리키는 포인터.

반환값

성공하면 S_OK 를 돌려준다. 그 이외의 경우는, 에러의 원인을 나타내는 HRESULT 값을 돌려준다.

주의

이 메소드는, 각 버퍼를 처리하는데 필요한 평균 시간을 돌려준다. 보통, 이 값은, 프로세서 속도 및 CPU 부하등의 실행시 환경의 요인으로 의존한다. 이 메소드를 이행 하는 방법의 1 개는, DMO 가 이력 데이터에 근거해 가동 평균치를 기록하는 방법이다.


구조체

여기에서는, Microsoft® DirectX® Media Object (DMO) 구조체에 대해 설명한다.

구조체 | 설명
DMO_MEDIA_TYPE | DMO 의 스트림이 사용하는 데이터의 포맷을 기술한다.
DMO_OUTPUT_DATA_BUFFER | DMO 가 사용하는 출력 버퍼를 기술한다.
DMO_PARTIAL_MEDIATYPE | DMO 가 사용하는 미디어 타입을 부분적으로 기술한다.


DMO_MEDIA_TYPE 구조체

구조체

Microsoft® DirectX® Media Object (DMO)의 스트림에 의해 사용되는 데이터의 포맷을 기술한다.

주 : 이 구조체는, Microsoft® DirectShow® AM_MEDIA_TYPE 구조체와 같다.

구문

typedef struct _DMOMediaType {
    GUID     majortype;
    GUID     subtype;
    BOOL     bFixedSizeSamples;
    BOOL     bTemporalCompression;
    ULONG    lSampleSize;
    GUID     formattype;
    IUnknown *pUnk;
    ULONG    cbFormat;
    [size_is(cbFormat)] BYTE * pbFormat;
} DMO_MEDIA_TYPE;

멤버

majortype
스트림의메이저 타입 GUID .
subtype
스트림의 서브 타입 GUID.
bFixedSizeSamples
TRUE 이면, 샘플은 고정 사이즈이다. 이 필드는 정보 제공 전용이다. 오디오의 경우는, 보통, TRUE 로 설정된다. 비디오의 경우는, 보통, 비압축 비디오는 TRUE, 압축 비디오는 FALSE 로 설정된다.
bTemporalCompression
TRUE 이면, 샘플은 시간 (프레임간) 압축을 사용해 압축되고 있다. (TRUE 는 일부의 프레임이 키 프레임이 아닌 것을 나타낸다. ) 이 필드는 정보 제공 전용이다.
lSampleSize
바이트 단위로 나타내는 샘플의 사이즈. 압축 데이터의 경우, 값은 0 이 된다.
formattype
포맷 타입을 지정하는 GUID. pbFormat 멤버는, 대응하는 포맷 구조체를 가리킨다. 포맷 타입에는 이하가 포함되어 있다.
포맷 타입 | 포맷 구조체
FORMAT_None | 포맷 타입 없음
FORMAT_MPEGVideo | MPEG1VIDEOINFO
FORMAT_MPEG2Video | MPEG2VIDEOINFO
FORMAT_VideoInfo | VIDEOINFOHEADER
FORMAT_VideoInfo2 | VIDEOINFOHEADER2
FORMAT_WaveFormatEx | WAVEFORMATEX
pUnk
사용되지 않았다.
cbFormat
미디어 타입의 포맷 블록의 사이즈.
pbFormat
포맷 구조체를 가리키는 포인터. 구조체의 타입은,formattype 멤버에 의해 지정된다. formattype 가 GUID_NULL 또는 FORMAT_None 가 아닌 한, 포맷 구조체가 없으면 안 된다.

주의

bFixedSizeSamples 멤버,bTemporalCompression 멤버 및 lSampleSize 멤버는, Microsoft® DirectShow® 와의 호환성을 유지하기 위해서(때문에) 준비되어 있다. 다른 DMO 클라이언트는, 이것들을 사용할 필요는 없다.


DMO_OUTPUT_DATA_BUFFER 구조체

구조체

Microsoft® DirectX® Media Object (DMO)가 사용하는 출력 버퍼를 기술한다.

구문

typedef struct _DMO_OUTPUT_DATA_BUFFER {
    IMediaBuffer *pBuffer;
    DWORD dwStatus;
    REFERENCE_TIME rtTimestamp;
    REFERENCE_TIME rtTimelength;
} DMO_OUTPUT_DATA_BUFFER, *PDMO_OUTPUT_DATA_BUFFER;

멤버

pBuffer
[in] 어플리케이션에 의해 할당할 수 있었던 버퍼의 IMediaBuffer 인터페이스를 가리키는 포인터.
dwStatus
[out] 상태 플래그. DMO 는, 출력을 처리한 후, 이 멤버를 0 개 이상의 DMO_OUTPUT_DATA_BUFFER_FLAGS 플래그의 비트 단위의 논리합으로 설정한다.
rtTimestamp
[out] 버퍼내의 데이터의 시작 타임을 지정하는 타임 스탬프. 버퍼가 유효한 타임 스탬프를 가지고 있으면, DMO 는 이 멤버를 설정해,dwStatus 멤버의 DMO_OUTPUT_DATA_BUFFERF_TIME 플래그도 설정한다. 그 이외의 경우는 이 멤버를 무시한다.
rtTimelength
[out] 버퍼내의 데이터의 길이를 지정하는 기준 시간. DMO 가 이 멤버를 유효한 값으로 설정하는 경우는,dwStatus 멤버의 DMO_OUTPUT_DATA_BUFFERF_TIMELENGTH 플래그도 설정한다. 그 이외의 경우는 이 멤버를 무시한다.

참조

IMediaObject::ProcessOutput


DMO_PARTIAL_MEDIATYPE 구조체

구조체

Microsoft® DirectX® Media Object (DMO)가 사용하는 미디어 타입을 부분적으로 기술한다. DMO 등록 함수는, 이 구조체를 사용해, 지원 되고 있는 미디어 타입을 지정한다.

구문

typedef struct _DMO_PARTIAL_MEDIATYPE {
    GUID type;
    GUID subtype;
} DMO_PARTIAL_MEDIATYPE, *PDMO_PARTIAL_MEDIATYPE;

멤버

type
메이저 타입 GUID . 모든 메이저 타입을 적합시키려면 GUID_NULL 를 사용한다.
subtype
서브 타입 GUID. 모든 서브 타입을 적합시키려면 GUID_NULL 를 사용한다.


열거형

여기에서는, Microsoft® DirectX® Media Object (DMO) 열거형에 대해 설명한다.

열거형 | 설명
DMO_ENUM_FLAGS | DMO 를 열거 하면나무의 검색 조건을 지정하는 플래그를 정의한다.
DMO_INPUT_DATA_BUFFER_FLAGS | 입력 버퍼를 설명하는 플래그를 정의한다.
DMO_INPUT_STREAM_INFO_FLAGS | 입력 스트림을 설명하는 플래그를 정의한다.
DMO_OUTPUT_DATA_BUFFER_FLAGS | 출력 버퍼를 설명하는 플래그를 정의한다.
DMO_OUTPUT_STREAM_INFO_FLAGS | 출력 스트림을 설명하는 플래그를 정의한다.
DMO_PROCESS_OUTPUT_FLAGS | 출력 처리 요구를 지정하는 플래그를 정의한다.
DMO_REGISTER_FLAGS | DMO 의 레지스트리 정보를 지정하는 플래그를 정의한다.
DMO_SET_TYPE_FLAGS | 스트림의 미디어 타입을 설정하기 위한 플래그를 정의한다.
DMO_VIDEO_OUTPUT_STREAM_FLAGS | 비디오 최적화에 대해서 요구하는 기능을 설명하는 플래그를 정의한다.


DMO_ENUM_FLAGS 열거

열거형

Microsoft® DirectX® Media Object (DMO)를 열거 하면나무의 검색 조건을 지정하는 플래그를 정의한다.

구문

enum DMO_ENUM_FLAGS {
    DMO_ENUMF_INCLUDE_KEYED = 0x00000001
};

요소

DMO_ENUMF_INCLUDE_KEYED
열거에는, 소프트웨어 키에 의해 사용이 제한되고 있는 DMO 를 포함한다. 이 플래그가 없는 경우, 키로 보호된 DMO 는 열거로부터 제외된다.

주의

DMO 의 개발자는, 소프트웨어 키를 사용해 DMO 의 이용자를 제한할 수 있다. 소프트웨어 키로 보호된 DMO 를 사용하는 경우, 어플리케이션은 DMO 의 락을 해제할 필요가 있다. DMO 의 락을 해제하는 방법은, 이행에 따라서 다르다. 개개의 DMO 의 문서를 참조할것.

참조

DMOEnum


DMO_INPUT_DATA_BUFFER_FLAGS 열거

열거형

입력 버퍼를 설명하는 플래그를 정의한다.

구문

enum _DMO_INPUT_DATA_BUFFER_FLAGS {
    DMO_INPUT_DATA_BUFFERF_SYNCPOINT       = 0x00000001,
    DMO_INPUT_DATA_BUFFERF_TIME            = 0x00000002,
    DMO_INPUT_DATA_BUFFERF_TIMELENGTH      = 0x00000004
};

요소

DMO_INPUT_DATA_BUFFERF_SYNCPOINT
데이터의 선두가동기 포인트이다.
DMO_INPUT_DATA_BUFFERF_TIME
버퍼의 타임 스탬프가 유효하다.
DMO_INPUT_DATA_BUFFERF_TIMELENGTH
버퍼가 가리키는 시간의 길이가 유효하다.

참조

IMediaObject::ProcessInput


DMO_INPUT_STREAM_INFO_FLAGS 열거

열거형

입력 스트림을 설명하는 플래그를 정의한다.

구문

enum _DMO_INPUT_STREAM_INFO_FLAGS {
    DMO_INPUT_STREAMF_WHOLE_SAMPLES            = 0x00000001,
    DMO_INPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER = 0x00000002,
    DMO_INPUT_STREAMF_FIXED_SAMPLE_SIZE        = 0x00000004,
    DMO_INPUT_STREAMF_HOLDS_BUFFERS            = 0x00000008
};

요소

DMO_INPUT_STREAMF_WHOLE_SAMPLES
스트림이 샘플 전체를 필요로 한다. 샘플이 복수의 버퍼에 걸쳐 있거나, 버퍼에 샘플의 일부가 포함되어 있거나 해선 안 된다.
DMO_INPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER
개개의 버퍼에 1 개만 샘플이 포함되어 있을 필요가 있다.
DMO_INPUT_STREAMF_FIXED_SAMPLE_SIZE
이 스트림의 모든 샘플의 사이즈를 같게 할 필요가 있다.
DMO_INPUT_STREAMF_HOLDS_BUFFERS
DMO 가 입력 데이터의룩 어해드를 실행한다. DMO 는 이 스트림용의 복수의 입력 버퍼를 보관 유지할 수가 있다.

참조

IMediaObject::GetInputStreamInfo


DMO_OUTPUT_DATA_BUFFER_FLAGS 열거

열거형

출력 버퍼를 설명하는 플래그를 정의한다.

구문

enum _DMO_OUTPUT_DATA_BUFFER_FLAGS {
    DMO_OUTPUT_DATA_BUFFERF_SYNCPOINT       = 0x00000001,
    DMO_OUTPUT_DATA_BUFFERF_TIME            = 0x00000002,
    DMO_OUTPUT_DATA_BUFFERF_TIMELENGTH      = 0x00000004,
    DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE      = 0x01000000
};

요소

DMO_OUTPUT_DATA_BUFFERF_SYNCPOINT
데이터의 선두가 동기 포인트이다.
DMO_OUTPUT_DATA_BUFFERF_TIME
버퍼의 타임 스탬프가 유효하다.
DMO_OUTPUT_DATA_BUFFERF_TIMELENGTH
버퍼가 가리키는 시간의 길이가 유효하다.
DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE
처리할 수 있는 입력 데이터가 아직 있지만, 출력 버퍼가 가득해 있다.

참조

IMediaObject::ProcessOutput


DMO_OUTPUT_STREAM_INFO_FLAGS 열거

열거형

출력 스트림을 설명하는 플래그를 정의한다.

구문

enum _DMO_OUTPUT_STREAM_INFO_FLAGS {
    DMO_OUTPUT_STREAMF_WHOLE_SAMPLES            = 0x00000001,
    DMO_OUTPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER = 0x00000002,
    DMO_OUTPUT_STREAMF_FIXED_SAMPLE_SIZE        = 0x00000004,
    DMO_OUTPUT_STREAMF_DISCARDABLE              = 0x00000008,
    DMO_OUTPUT_STREAMF_OPTIONAL                 = 0x00000010
};

요소

DMO_OUTPUT_STREAMF_WHOLE_SAMPLES
스트림에 샘플 전체가 포함되어 있다. 샘플은 복수의 버퍼에 걸치지 않고, 버퍼에 샘플의 일부가 포함되어 있을 것도 않다.
DMO_OUTPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER
각 버퍼에 1 개만 샘플이 포함되어 있다.
DMO_OUTPUT_STREAMF_FIXED_SAMPLE_SIZE
이 스트림안의 모든 샘플은 사이즈가 같다.
DMO_OUTPUT_STREAMF_DISCARDABLE
이 스트림은 파기할 수 있다. DMO 는,IMediaObject::ProcessOutput 에 대한 호출 중(안)에서, 출력 버퍼에 데이터를 카피하지 않고 , 이 스트림의 데이터를 파기할 수가 있다.
DMO_OUTPUT_STREAMF_OPTIONAL
이 스트림은 옵션이다. 옵션의 스트림은 파기할 수 있다. 또, 어플리케이션은 이 스트림 전체를 무시할 수 있다. 어플리케이션은 이 스트림의 미디어 타입을 설정할 필요는 없다. 일반적으로, 옵션의 스트림에는, 추가 정보나 일부의 어플리케이션만이 필요로 하는 데이터가 포함되어 있다.

주의

DMO_OUTPUT_STREAMF_DISCARDABLE 플래그와 DMO_OUTPUT_STREAMF_OPTIONAL 플래그는 양립하지 않는다. DMO 는 이러한 플래그의 어느쪽이든을 설정할 수 있는 (어느 쪽의 플래그도 설정 하지 않아도 되다)가, 양쪽 모두를 설정할 수 없다.

참조

IMediaObject::GetOutputStreamInfo


DMO_PROCESS_OUTPUT_FLAGS 열거

열거형

출력 처리 요구를 지정하는 플래그를 정의한다.

구문

enum _DMO_PROCESS_OUTPUT_FLAGS {
    DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER = 0x00000001
};

요소

DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER
출력 버퍼를 가리키는 포인터가 NULL 의 경우에 출력을 파기한다.

참조

IMediaObject::ProcessOutput


DMO_REGISTER_FLAGS 열거

열거형

Microsoft® DirectX® Media Object (DMO)의 레지스트리 정보를 지정하는 플래그를 정의한다.

구문

enum DMO_REGISTER_FLAGS {
    DMO_REGISTERF_IS_KEYED = 0x00000001
};

요소

DMO_REGISTERF_IS_KEYED
소프트웨어 키에 의해 DMO 의 사용이 제한되고 있다.

주의

DMO 의 개발자는, 소프트웨어 키를 사용해 DMO 의 이용자를 제한할 수 있다. 소프트웨어 키로 보호된 DMO 를 사용하는 경우, 어플리케이션은 DMO 의 락을 해제할 필요가 있다. DMO 의 락을 해제하는 방법은, 이행에 따라서 다르다. 개개의 DMO 의 문서를 참조할것.

참조

DMORegister


DMO_SET_TYPE_FLAGS 열거

열거형

스트림의 미디어 타입을 설정하기 위한 플래그를 정의한다.

구문

enum _DMO_SET_TYPE_FLAGS {
    DMO_SET_TYPEF_TEST_ONLY = 0x00000001,
    DMO_SET_TYPEF_CLEAR     = 0x00000002
};

요소

DMO_SET_TYPEF_TEST_ONLY
미디어 타입을 테스트하지만, 설정은 하지 않는다.
DMO_SET_TYPEF_CLEAR
스트림에 대해서 설정된 미디어 타입을 소거한다.

주의

DMO_SET_TYPEF_TEST_ONLY 플래그와 DMO_SET_TYPEF_CLEAR 플래그는 양립하지 않는다. 양쪽 모두의 플래그를 설정하지 않는 것.

참조

IMediaObject::SetInputType ,IMediaObject::SetOutputType


DMO_VIDEO_OUTPUT_STREAM_FLAGS 열거

열거형

비디오 최적화에 대해서 요구하는 기능을 설명하는 플래그를 정의한다.

구문

enum _DMO_VIDEO_OUTPUT_STREAM_FLAGS {
    DMO_VOSF_NEEDS_PREVIOUS_SAMPLE = 0x00000001
};

요소

DMO_VOSF_NEEDS_PREVIOUS_SAMPLE
DMO 에게 건네지는 모든 출력 버퍼에, 생성된 전의 데이터를 포함하는 것을 요구한다.

참조

IDMOVideoOutputOptimizations


함수

여기에서는, Microsoft® DirectX® Media Object (DMO) 함수에 대해 설명한다.

  • DMO 등록 함수
  • 미디어 타입 헬퍼 함수


DMO 등록 함수

어플리케이션은 DMO 등록 함수를 이용해, Microsoft® DirectX® Media Object (DMO)의 등록과 열거를 실시할 수가 있다. 이러한 함수는, Dmoreg.h 파일로 선언된다.

DMORegister | DMO 를 등록한다.
DMOUnregister | DMO 의 등록을 해제한다.
DMOEnum | 등록되어 있는 DMO 를 열거한다.
DMOGetTypes | DMO 가 등록되어 있는 미디어 타입을 취득한다.
DMOGetName | DMO 의 등록명을 취득한다.

DMORegister

DMO 등록 함수

DMO 를 등록한다.

구문

HRESULT DMORegister(
   LPCWSTR szName,
   REFCLSID clsidDMO,
   REFGUID guidCategory,
   DWORD dwFlags,
   DWORD cInTypes,
   const DMO_PARTIAL_MEDIATYPE *pInTypes,
   DWORD cOutTypes,
   const DMO_PARTIAL_MEDIATYPE *pOutTypes
);

파라미터

szName
DMO 의 알기 쉬운 이름이 저장 된, NULL 로 끝나는 캐릭터 라인. 79 문자를 넘는 이름은 절약할 수 있는 일이 있다.
clsidDMO
DMO 의 클래스 식별자 (CLSID).
guidCategory
DMO 의 카테고리를 지정하는카테고리 GUID .
dwFlags
DMO_REGISTER_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합.
cInTypes
등록하는 입력 미디어 타입의 수. 0 도 지정할 수 있다.
pInTypes
입력 미디어 타입을 지정하는 DMO_PARTIAL_MEDIATYPE 구조체의 배열을 가리키는 포인터. 배열의 사이즈는 cInTypes 파라미터에 의해 지정한다.
cOutTypes
등록하는 출력 미디어 타입의 수.
pOutTypes
출력 미디어 타입을 지정하는 DMO_PARTIAL_MEDIATYPE 구조체의 배열을 가리키는 포인터. 배열의 사이즈는 cOutTypes 파라미터에 의해 지정한다. 0 도 지정할 수 있다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_FAIL | 실패
E_INVALIDARG | 무효인 인수

주의

이 함수는, DMO 에 관한 정보를 레지스트리에 추가한다. 어플리케이션 또는 소프트웨어 컴퍼넌트는,DMOEnum 함수를 호출하는 것으로, 이 정보를 사용해, 사용할 필요가 있는 DMO 를 찾아낸다. 예를 들어, 비디오 스트림을 encode 하려면 , DMOCATEGORY_VIDEO_ENCODER 카테고리로, 조건에 일치한 미디어 타입의 DMO 를 검색한다.

이 함수에 의해 등록되는 미디어 타입은, DMO 의 검색만을 목적으로 하고 있다. IMediaObject::GetInputType 메소드 및 IMediaObject::GetOutputType 메소드에 의해 돌려주어지는 타입에, 반드시 일치하지 않는다. 예를 들어, 디코더는, 주요한 입력 타입만을 등록하는 일이 있다. DMO 가 생성 되어 입력 타입을 설정 하면,GetOutputType 메소드는 생성 가능한 모든 압축 해제 타입을 돌려준다.

DMOUnregister

DMO 등록 함수

DMO 의 등록을 해제한다.

구문

HRESULT DMOUnregister(
   REFCLSID clsidDMO,
   REFGUID guidCategory
);

파라미터

clsidDMO
DMO 의 클래스 식별자 (CLSID).
guidCategory
삭제하는 DMO 가 속하는 카테고리를 지정하는 카테고리 GUID . 모든 카테고리로 DMO 의 등록을 해제하는데는 GUID_NULL 를 사용한다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_FALSE | 이 CLSID 는 지정된 카테고리에 등록되지 않았다.
S_OK | 성공.
E_INVALIDARG | 무효인 인수.

DMOEnum

DMO 등록 함수

등록되어 있는 DMO 를 열거한다. 호출원래는 카테고리, 미디어 타입, 또는 그 양쪽 모두를 기준으로 해 검색할 수 있다.

구문

HRESULT DMOEnum(
    REFGUID guidCategory,
    DWORD dwFlags,
    DWORD cInTypes,
    const DMO_PARTIAL_MEDIATYPE *pInTypes,
    DWORD cOutTypes,
    const DMO_PARTIAL_MEDIATYPE *pOutTypes,
    IEnumDMO **ppEnum
);

파라미터

guidCategory
검색하는 DMO 의 카테고리를 지정하는 카테고리 GUID . 모든 카테고리를 검색하려면 GUID_NULL 를 사용한다.
dwFlags
DMO_ENUM_FLAGS 열거의 0 개 이상의 플래그의 비트 단위의 논리합.
cInTypes
검색 조건으로서 사용하는 입력 미디어 타입의 수. 모든 입력 타입을 조건으로 적합시키려면 0 을 사용한다.
pInTypes
입력 미디어 타입이 저장 된 DMO_PARTIAL_MEDIATYPE 구조체의 배열을 가리키는 포인터. cInTypes 파라미터로 배열의 사이즈를 지정한다.
cOutTypes
검색 조건으로서 사용하는 출력 미디어 타입의 수. 모든 출력 타입을 조건으로 적합시키려면 0 을 사용한다.
pOutTypes
출력 미디어 타입이 저장 된 DMO_PARTIAL_MEDIATYPE 구조체의 배열을 가리키는 포인터. cOutTypes 파라미터로 배열의 사이즈를 지정한다.
ppEnum
열거자의 IEnumDMO 인터페이스를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_FAIL | 실패
E_OUTOFMEMORY | 메모리 부족

주의

이 메소드는,IEnumDMO 인터페이스를 지원 하는 열거자 오브젝트를 가리키는 포인터를 돌려준다. 어플리케이션은 IEnumDMO 인터페이스를 사용해, 검색 조건에 적합하는 DMO 세트를 열거한다.

DMOGetTypes

DMO 등록 함수

DMO 에 대해서 등록되어 있는 미디어 타입을 취득한다.

구문

HRESULT DMOGetTypes(
    REFCLSID clsidDMO,
    unsigned long ulInputTypesRequested,
    unsigned long *pulInputTypesSupplied,
    DMO_PARTIAL_MEDIATYPE *pInputTypes,
    unsigned long ulOutputTypesRequested,
    unsigned long *pulOutputTypesSupplied,
    DMO_PARTIAL_MEDIATYPE *pOutputTypes
);

파라미터

clsidDMO
DMO 의 클래스 식별자 (CLSID).
ulInputTypesRequested
pInputTypes 파라미터에 의해 건네받는 배열의 사이즈.
pulInputTypesSupplied
함수가 데이터를 저장 하는 pInputTypes 의 DMO_PARTIAL_MEDIATYPE 구조체의 수를 받는 변수를 가리키는 포인터.
pInputTypes
호출 바탕으로야는 할당할 수 있었던 DMO_PARTIAL_MEDIATYPE 구조체의 배열을 가리키는 포인터. 배열의 사이즈는 ulInputTypesRequested 파라미터에 의해 취득된다. 함수는, DMO 에 대해서 등록되어 있는 입력 타입을 배열에 저장 한다.
ulOutputTypesRequested
pOutputTypes 파라미터에 의해 건네받는 배열의 사이즈.
pulOutputTypesSupplied
함수가 데이터를 저장 하는 pOutputTypes 의 DMO_PARTIAL_MEDIATYPE 구조체의 수를 받는 변수를 가리키는 포인터.
pOutputTypes
호출 바탕으로야는 할당할 수 있었던 DMO_PARTIAL_MEDIATYPE 구조체의 배열을 가리키는 포인터. 배열의 사이즈는 ulOutputTypesRequested 파라미터에 의해 취득된다. 함수는, DMO 에 대해서 등록되어 있는 DMO 출력 타입을 배열에 저장 한다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_FALSE | 배열이 너무 작다
S_OK | 성공
E_FAIL | 실패

주의

배열중 한쪽이, 등록되어 모든 타입을 저장 하기에는 너무 작은 경우, 함수는 배열에 데이터를 저장 하지만, S_FALSE 를 돌려준다.

DMO 가 미디어 타입을 등록하지 않았던 경우, 함수는 S_OK 를 돌려주어,*pulInputTypesSupplied 와 *pulOutputTypesSupplied 를 0 으로 설정한다.

DMOGetName

DMO 등록 함수

DMO 의 등록명을 취득한다.

구문

HRESULT DMOGetName(
   REFCLSID clsidDMO,
   WCHAR szName[]
);

파라미터

clsidDMO
DMO 의 클래스 식별자 (CLSID).
szName
DMO 의 이름을 받는 80 개의 Unicode 문자의 배열. 호출원래는 배열을 할당할 필요가 있다. 이름은 NULL 로 끝나는 캐릭터 라인이다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_FALSE | 이 DMO 에 대해서 이름이 등록되지 않은, 또는 이름의 길이가 0 이다.
S_OK | 성공.
E_FAIL | 실패.

주의

메소드가 S_FALSE 를 돌려주면(자),szName 가 '\0'로 설정된다.


미디어 타입 헬퍼 함수

이러한 함수는,DMO_MEDIA_TYPE 구조체를 조작한다. 이러한 함수는 Dmort.h 파일로 선언된다.

MoInitMediaType | 미디어 타입 구조체를 초기화한다.
MoFreeMediaType | 미디어 타입 구조체의 할당 끝난 멤버를 해방한다.
MoCopyMediaType | 1 개의 미디어 타입 구조체의 멤버를 다른 미디어 타입 구조체에 카피한다.
MoCreateMediaType | 새로운 미디어 타입 구조체를 할당한다.
MoDeleteMediaType | 전에 할당할 수 있었던 미디어 타입 구조체를 삭제한다.
MoDuplicateMediaType | 미디어 타입 구조체를 복제한다.

MoInitMediaType

DMO 등록 함수

미디어 타입 구조체를 초기화한다.

구문

HRESULT MoInitMediaType(
    DMO_MEDIA_TYPE *pmt,
    DWORD cbFormat
);

파라미터

pmt
호출 바탕으로야는 할당할 수 있고 있어 초기화되어 있지 않은 DMO_MEDIA_TYPE 구조체를 가리키는 포인터.
cbFormat
포맷 블록에 할당하는 바이트의 수. 0 도 지정할 수 있다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_OUTOFMEMORY | 메모리 부족
E_POINTER | NULL 포인터 인수

주의

이 함수는 포맷 블록을 할당해, DMO_MEDIA_TYPE 구조체의 cbFormat 멤버와 pbFormat 멤버를 설정한다.

호출원래는,MoFreeMediaType 함수를 호출하는 것에 의해 미디어 타입을 해방할 필요가 있다.

MoFreeMediaType

DMO 등록 함수

미디어 타입 구조체의 할당 끝난 멤버를 해방한다.

구문

HRESULT MoFreeMediaType(
    DMO_MEDIA_TYPE *pmt
);

파라미터

pmt
초기화된 DMO_MEDIA_TYPE 구조체를 가리키는 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_POINTER | NULL 포인터 인수

주의

이 함수는, DMO_MEDIA_TYPE 구조체의 pbFormat 멤버가 가리키는 포맷 블록을 해방한다.

MoCopyMediaType

DMO 등록 함수

1 개의 미디어 타입 구조체의 멤버를 다른 미디어 타입 구조체에 카피한다.

구문

HRESULT MoCopyMediaType(
    DMO_MEDIA_TYPE *pmtDest,
    const DMO_MEDIA_TYPE *pmtSrc
);

파라미터

pmtDest
카피처의 DMO_MEDIA_TYPE 구조체를 가리키는 포인터. 호출원래는 이 구조체를 할당할 필요가 있지만, 초기화해선 안 된다.
pmtSrc
카피원의 DMO_MEDIA_TYPE 구조체를 가리키는 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_OUTOFMEMORY | 메모리 부족
E_POINTER | NULL 포인터 인수

주의

이 함수는,*pmtSrc 의 모든 멤버를 *pmtDest 에 카피해, 포맷 블록을 카피한다.

호출원래는,MoFreeMediaType 함수를 호출하는 것에 의해 카피처 미디어 타입을 해방할 필요가 있다.

MoCreateMediaType

DMO 등록 함수

새로운 미디어 타입 구조체를 할당한다.

구문

HRESULT MoCreateMediaType(
    DMO_MEDIA_TYPE **ppmt,
    DWORD cbFormat
);

파라미터

ppmt
할당할 수 있었던 구조체를 받는 DMO_MEDIA_TYPE 구조체를 가리키는 포인터의 주소.
cbFormat
포맷 블록에 할당하는 바이트의 수. 0 도 지정할 수 있다.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_OUTOFMEMORY | 메모리 부족
E_POINTER | NULL 포인터 인수

주의

이 함수는 새로운 DMO_MEDIA_TYPE 구조체를 할당해,MoInitMediaType 함수를 호출하는 것에 의해, 그 구조체를 초기화한다.

호출원래는,MoDeleteMediaType 함수를 호출하는 것에 의해 미디어 타입 구조체를 삭제할 필요가 있다.

MoDeleteMediaType

DMO 등록 함수

전에 할당할 수 있었던 미디어 타입 구조체를 삭제한다.

구문

HRESULT MoDeleteMediaType(
    DMO_MEDIA_TYPE *pmt
);

파라미터

pmt
초기화된 DMO_MEDIA_TYPE 구조체를 가리키는 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_POINTER | NULL 포인터 인수

주의

이 함수는,MoFreeMediaType 를 호출하는 것에 의해, 미디어 타입 구조체의 할당 끝난 멤버를 해방한다. 다음에, 이 함수는, 미디어 타입 구조체 그 자체를 해방한다.

MoDuplicateMediaType

DMO 등록 함수

미디어 타입 구조체를 복제한다.

구문

HRESULT MoDuplicateMediaType(
    DMO_MEDIA_TYPE **ppmtDest,
    const DMO_MEDIA_TYPE *pmtSrc
);

파라미터

ppmtDest
복제된 구조체를 받는 DMO_MEDIA_TYPE 구조체를 가리키는 포인터의 주소.
pmtSrc
복제하는 미디어 타입 구조체를 가리키는 포인터.

반환값

HRESULT 값을 돌려준다. 이하의 값을 취한다.

S_OK | 성공
E_OUTOFMEMORY | 메모리 부족
E_POINTER | NULL 포인터 인수

주의

이 메소드를 실행하는 것은,MoCreateMediaType 와 MoCopyMediaType 를 호출하는 것에 동일하다.

호출원래는,MoDeleteMediaType 함수를 호출하는 것에 의해, 돌려주어진 미디어 타입 구조체를 삭제할 필요가 있다.


DMO 에러 코드

다음의 표는, Microsoft® DirectX® 미디어 오브젝트 (DMO)에 관련한 에러 코드를 나타낸다. 이러한 에러 코드는, 헤더 파일 Mediaerr.h 에 정의되고 있다.

귀가 코드 | 설명 | 16 진수값
DMO_E_INVALIDSTREAMINDEX | 무효인 스트림 인덱스. | 0x80040201
DMO_E_INVALIDTYPE | 무효인 미디어 타입. | 0x80040202
DMO_E_TYPE_NOT_SET | 설정되지 않았던 미디어 타입. 1 개(살) 또는 복수의 스트림은, 이 조작을 실행하기 전에 미디어 타입을 필요로 한다. | 0x80040203
DMO_E_NOTACCEPTING | 이 스트림에서는 데이터는 받아들여지지 않는다. 보다 많은 출력 데이터를 처리해야 하는 것도 있다. 상세한 것에 대하여는, 「IMediaObject::ProcessInput 」를 참조할것. | 0x80040204
DMO_E_TYPE_NOT_ACCEPTED | 미디어 타입이 받아들여지지 않았다. | 0x80040205
DMO_E_NO_MORE_ITEMS | 미디어 타입 인덱스가 범위외이다. | 0x80040206


DMO 의 GUID

여기에서는, Microsoft® DirectX® Media Object (DMO)로 정의되고 있는 글로벌하게 일의인 식별자 (GUID)의 일부를 나타낸다.

  • 카테고리 GUID

카테고리 GUID

다음의 표는, DMO 카테고리의 GUID 를 나타내고 있다. 카테고리에 등록되어 있는 DMO 를 열거하려면 , 카테고리에 대응하는 GUID 를 DMOEnum 함수에 건네준다.

GUID | 설명
DMOCATEGORY_AUDIO_DECODER | 오디오 디코더
DMOCATEGORY_AUDIO_EFFECT | 오디오 이펙트
DMOCATEGORY_AUDIO_ENCODER | 오디오 엔코더
DMOCATEGORY_VIDEO_DECODER | 비디오 디코더
DMOCATEGORY_VIDEO_EFFECT | 비디오 이펙트
DMOCATEGORY_VIDEO_ENCODER | 비디오 엔코더
DMOCATEGORY_AUDIO_CAPTURE_EFFECT | 오디오 캡춰 이펙트


DMO base class 레퍼런스

Microsoft® DirectX® 8.0 에는, DirectX Media Object (DMO)를 생성하기 위한 base class 템플릿이 포함되어 있다. DMO 의 생성에 템플릿을 사용할 필요는 없다. 다만, 템플릿은 모든 DMO 에 공통되는 각종의 처리를 실시하게 되어 있다. 템플릿을 사용하면, 그 DMO 고유의 기능에만 전념할 수 있다. 게다가 템플릿은 견뢰한 이행을 생성 하는 도움으로도 된다.

이 항은, 이하의 주제로부터 구성된다.

  • DMO base class의 사용법
  • IMediaObjectImpl 클래스 템플릿


DMO base class의 사용법

Microsoft® DirectX® 8.0 SDK 에는, DMO 생성을 위한 base class 템플릿 IMediaObjectImpl 가 포함되어 있다. DMO 가 IUnknown 인터페이스와 IMediaObject 인터페이스를 완전하게 지원 하고 있으면, DMO 생성시에 이 클래스 템플릿을 사용할 필요는 없다. 다만, Microsoft 제공의 클래스 템플릿은, 입력 파라미터의 확인등의 "정평 " 처리의 대부분을 실시하게 되어 있다. 템플릿을 사용하면, 그 DMO 고유의 기능에만 전념할 수 있다. 게다가 템플릿은 견뢰한 이행을 생성 하는 도움으로도 된다.

여기에서는, 이하의 토픽에 대해 설명한다.

  • IMediaObjectImpl 의 개요
  • 상속 클래스의 선언
  • DMO 메소드의 이행

IMediaObjectImpl 의 개요

IMediaObjectImpl 템플릿은,IMediaObject 인터페이스를 계승하는 클래스 템플릿이다. 이 템플릿을 사용해 DMO 를 생성 하려면 ,IMediaObjectImpl 로부터 파생하는 새로운 클래스를 정의한다. 템플릿은 IMediaObject 의 메소드를 모두 이행 한다. 많은 경우, 템플릿 메소드는 대응하는 내부 메소드를 호출해, 이러한 내부 메소드를 상속 클래스로부터 제공한다. 이와 같이, 템플릿은 파라미터 체크등의 범용 기능을 제공해, 상속 클래스는 DMO 의 핵이 되는 기능을 제공한다.

템플릿은 이하의 기능을 제공한다.

  • 기본적인 파라미터 체크. 템플릿 메소드는, 필수 파라미터가 NULL 가 아니고, 스트림의 인덱스가 범위내이며, 플래그가 유효한 것을 검사한다.
  • 락. 템플릿 메소드는,Lock 와 Unlock 의 2 개의 내부 메소드를 호출해, DMO 에 관한 처리를 순서대로화한다. 이 기능에 의해, DMO 를 thread 세이프로 할 수 있다.
  • 미디어 타입. 템플릿은, DMO 내의 스트림에 대해서 설정된 미디어 타입을 보관 유지한다. 또, 템플릿은 미디어 타입에 액세스 하는 메소드도 제공한다.
  • 스트리밍. 템플릿은, 클라이언트가 모든 필수 스트림의 미디어 타입을 설정할 때까지, 스트리밍을 실행하지 않는다. 또,ProcessInput 메소드와 ProcessOutput 메소드는, 자동적으로 AllocateStreamingResources 를 호출한다.

IUnknown 인터페이스는, 템플릿으로부터 제공되지 않기 때문에, 상속 클래스로 이행 하는 것. IUnknown 는, ATL (Active Template Library)를 사용해 이행 할 수 있지만, 다른 이행을 제공해도 괜찮다.

또, 템플릿에는 락 메카니즘이 이행 되지 않는다. 이 때문에,Lock 메소드와 Unlock 메소드는 상속 클래스측에서 이행 할 필요가 있다. 다만, ATL 를 사용해 클래스를 생성 하는 경우에는, ATL 에 의한 이러한 메소드의 디폴트 이행으로 충분한 것이 많다.

상속 클래스의 선언

IMediaObjectImpl 템플릿은, SDK 의 인클루드 디렉토리에 있는 헤더 파일 Dmoimpl.h 로 이하와 같이 선언된다.

template <class _DERIVED_, int NUMBEROFINPUTS, int NUMBEROFOUTPUTS>
class IMediaObjectImpl : public IMediaObject

템플릿에는 이하의 겉(표)에 나타내는 3 개의 파라미터가 있다.

_DERIVED_ | 상속 클래스형
NUMBEROFINPUTS | 입력 스트림수
NUMBEROFOUTPUTS | 출력 스트림수

예를 들어, 입력 스트림과 출력 스트림 각각 1 개(살)을 지원 하는 CMyDmoClass 라고 하는 상속 클래스를 생성 하려면 , 다음과 같이 선언한다.

class CMyDmoClass :
    public IMediaObjectImpl<CMyDmoClass, 1, 1>  // 입력이 1 개, 출력이 1 개

DMO 는 스트림을 동적으로 생성 또는 파기할 수 없기 때문에, 스트림수는 정수이다.

DMO 메소드의 이행

템플릿은, 이하의 IMediaObject 메소드의 부분적인 이행을 제공한다. IMediaObject 의 메소드는 내부적으로 대응하는 메소드를 호출하므로, 그러한 내부 메소드를 상속 클래스측에서 제공할 필요가 있다. 내부 메소드명에는,Internal- 라고 하는 프레픽스가 붙는다. 내부 메소드에서는, 인터페이스 메소드와 같은 파라미터가 사용된다.

IMediaObject 메소드 | 상속 클래스의 메소드
AllocateStreamingResources | InternalAllocateStreamingResources
Discontinuity | InternalDiscontinuity
Flush | InternalFlush
FreeStreamingResources | InternalFreeStreamingResources
GetInputMaxLatency | InternalGetInputMaxLatency
GetInputSizeInfo | InternalGetInputSizeInfo
GetInputStreamInfo | InternalGetInputStreamInfo
GetInputType | InternalGetInputType
GetOutputSizeInfo | InternalGetOutputSizeInfo
GetOutputStreamInfo | InternalGetOutputStreamInfo
GetOutputType | InternalGetOutputType
ProcessInput | InternalProcessInput
ProcessOutput | InternalProcessOutput
SetInputMaxLatency | InternalSetInputMaxLatency

IMediaObject 의 나머지의 메소드에서는, 인터페이스 메소드와 내부 메소드가 1 대 1 에 대응하고 있지 않다. 다음의 일람은, 템플릿으로 완전하게 이행 되는 메소드와 상속 클래스 제공의 헬퍼 메소드를 호출하는 메소드를 집계한 것이다.

IMediaObject 메소드 | IMediaObjectImpl 에서의 이행
GetInputCurrentType | 완전하게 이행 된다.
GetOutputCurrentType | 완전하게 이행 된다.
GetStreamCount | 완전하게 이행 된다.
GetInputStatus | InternalAcceptingInput 를 호출한다.
Lock | DMOLock 로서 이행 된다. Lock 또는 Unlock 를 호출한다.
SetInputType | InternalCheckInputType 를 호출한다.
SetOutputType | InternalCheckOutputType 를 호출한다.

상세한 것에 대하여는, 「IMediaObjectImpl 」를 참조할것.


IMediaObjectImpl 클래스 템플릿

IMediaObject 인터페이스의 기본적인 이행을 제공한다.

이 템플릿 사용의 상세한 것에 대하여는, 「DMO base class의 사용법」을 참조할것.

헬퍼 클래스
LockIt | 락과 그 해제를 처리하는 내부 헬퍼 클래스.
IMediaObjectImpl 메소드
CheckTypesSet | 모든 필수 스트림에 미디어 타입이 설정되어 있는지 어떤지를 판단한다.
InputType | 입력 스트림의 미디어 타입을 취득한다.
InputTypeSet | 입력 스트림에 미디어 타입이 설정되어 있는지 어떤지를 조회한다.
OutputType | 출력 스트림의 미디어 타입을 취득한다.
OutputTypeSet | 출력 스트림에 미디어 타입이 설정되어 있는지 어떤지를 조회한다.
IMediaObject 메소드 | IMediaObject 인터페이스를 이행 하는 메소드.
상속 클래스의 메소드
InternalAcceptingInput | 입력 스트림이 한층 더 입력을 받아들일지 어떨지를 조회한다.
InternalCheckInputType | 입력 스트림이 소정의 미디어 타입을 받아들일지 어떨지를 조회한다.
InternalCheckOutputType | 출력 스트림이 소정의 미디어 타입을 받아들일지 어떨지를 조회한다.
Lock | 오브젝트를 잠근다.
Unlock | 오브젝트의 락을 해제한다.

LockIt 내부 클래스

락과 그 해제를 처리하는 내부 헬퍼 클래스.

구문

LockIt(
    _DERIVED_ *p
);

파라미터

p
파생 오브젝트에의 포인터.

주의

constructor　 　 메소드가 오브젝트를 잠그어, 소멸자 메소드가 오브젝트의 락을 해제한다. 상속 클래스의 내부로부터 오브젝트를 잠그려면 , 다음과 같이 LockIt 형의 로컬 변수를 선언한다.

{
    LockIt lck(static_cast<_DERIVED_ *>(this)); // 오브젝트를 잠근다.

} // lck 가 스코프외에 나와, 오브젝트의 락이 해제된다.

IMediaObjectImpl 의 메소드에서는 락이 처리되기 (위해)때문에, 많은 경우, 상속 클래스로 오브젝트를 잠글 필요는 없다.

IMediaObjectImpl::CheckTypesSet

모든 필수 스트림에 미디어 타입이 설정되어 있는지 어떤지를 판단한다.

구문

bool CheckTypesSet(void);

반환값

오브젝트의 필수 스트림 모두에게 미디어 타입이 설정되어 있는 경우는, TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

주의

스트림의 미디어 타입을 변경하는 조작을 했을 경우에는, 그 후에 이 메소드를 호출한다. 이 메소드는, 클래스 내부의 사적인 플래그를 설정한다. IMediaObjectImpl 의 일부 메소드에서는, 일정한 처리를 실행해도 좋은지 어떤지를 판단하기 위해서(때문에), 이 플래그를 테스트한다. 플래그가 FALSE 의 경우는, 보통, DMO_E_TYPE_NOT_SET 가 돌려주어진다.

스트림의 미디어 타입을 변경하는 IMediaObject 메소드는,SetInputType 과 SetOutputType 의 2 개뿐이다. 클래스 템플릿은, 이러한 메소드의 양쪽 모두를 이행 한다.

IMediaObjectImpl::InputType

입력 스트림의 미디어 타입을 취득한다.

구문

const DMO_MEDIA_TYPE *InputType(
DWORD ulInputStreamIndex
);

파라미터

ulInputStreamIndex
입력 스트림의 인덱스.

반환값

미디어 타입을 기술하는 DMO_MEDIA_TYPE 구조체에의 포인터를 돌려준다. 타입이 설정되어 있지 않은 경우에는, NULL 를 돌려준다.

IMediaObjectImpl::InputTypeSet

입력 스트림에 미디어 타입이 설정되어 있는지 어떤지를 조회한다.

구문

bool InputTypeSet(
DWORD ulInputStreamIndex
);

파라미터

ulInputStreamIndex
입력 스트림의 인덱스.

반환값

이 스트림에 미디어 타입이 설정되어 있는 경우는, TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

IMediaObjectImpl::OutputType

출력 스트림의 미디어 타입을 취득한다.

구문

const DMO_MEDIA_TYPE *OutputType(
DWORD ulOutputStreamIndex
);

파라미터

ulOutputStreamIndex
출력 스트림의 인덱스.

반환값

미디어 타입을 기술하는 DMO_MEDIA_TYPE 구조체에의 포인터를 돌려준다. 타입이 설정되어 있지 않은 경우에는, NULL 를 돌려준다.

IMediaObjectImpl::OutputTypeSet

출력 스트림에 미디어 타입이 설정되어 있는지 어떤지를 조회한다.

구문

bool OutputTypeSet(
DWORD ulOutputStreamIndex
);

파라미터

ulOutputStreamIndex
출력 스트림의 인덱스.

반환값

이 스트림에 미디어 타입이 설정되어 있는 경우는, TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

_DERIVED_::InternalAcceptingInput

입력 스트림이 한층 더 입력을 받아들일지 어떨지를 조회한다. 상속 클래스는, 이 메소드를 선언 및 이행 할 필요가 있다.

구문

HRESULT InternalAcceptingInput(
    DWORD dwInputStreamIndex
);

파라미터

dwInputStreamIndex
입력 스트림의 인덱스.

반환값

입력 스트림이 입력을 받아들이는 경우는, S_OK 를 돌려준다. 그 이외의 경우는, S_FALSE 를 돌려준다.

_DERIVED_::InternalCheckInputType

입력 스트림이 소정의 미디어 타입을 받아들일지 어떨지를 조회한다. 상속 클래스는, 이 메소드를 선언 및 이행 할 필요가 있다.

구문

HRESULT InternalCheckInputType(
    DWORD dwInputStreamIndex,
    const DMO_MEDIA_TYPE *pmt
);

파라미터

dwInputStreamIndex
입력 스트림의 인덱스.
pmt
미디어 타입을 기술하는 DMO_MEDIA_TYPE 구조체에의 포인터.

반환값

미디어 타입이 유효한 경우는, S_OK 를 돌려준다. 그 이외의 경우는, DMO_E_INVALIDTYPE 를 돌려준다.

_DERIVED_::InternalCheckOutputType

출력 스트림이 소정의 미디어 타입을 받아들일지 어떨지를 조회한다. 상속 클래스는, 이 메소드를 선언 및 이행 할 필요가 있다.

구문

HRESULT InternalCheckOutputType(
    DWORD dwOutputStreamIndex,
    const DMO_MEDIA_TYPE *pmt
);

파라미터

dwOutputStreamIndex
출력 스트림의 인덱스.
pmt
미디어 타입을 기술하는 DMO_MEDIA_TYPE 구조체에의 포인터.

반환값

미디어 타입이 유효한 경우는, S_OK 를 돌려준다. 그 이외의 경우는, DMO_E_INVALIDTYPE 를 돌려준다.

_DERIVED_::Lock

오브젝트를 잠근다. 상속 클래스는, 이 메소드를 선언 및 이행 할 필요가 있다.

구문

void Lock(void);

주의

ATL (Active Template Library)를 사용해 상속 클래스를 이행 하면, ATL 에 의한 이 메소드의 디폴트 이행을 사용할 수 있다.

_DERIVED_::Unlock

오브젝트의 락을 해제한다. 상속 클래스는, 이 메소드를 선언 및 이행 할 필요가 있다.

구문

void Unlock(void);

주의

ATL (Active Template Library)를 사용해 상속 클래스를 이행 하면, ATL 에 의한 이 메소드의 디폴트 이행을 사용할 수 있다.

IMediaObject 메소드

IMediaObject 의 메소드의 대부분은, 같은 메소드의 내부 버젼을 호출하는 래퍼이다. 상속 클래스는,Internal- 라고 하는 프레픽스를 가지는 내부 버젼을 이행 할 필요가 있다.

상속 클래스로 이행 해야 할 메소드의 일람에 대해서는, 「DMO base class의 사용법」을 참조할것. 여기에서는, 몇개의 이행의 상세한 것에 대하여 설명한다.

AllocateStreamingResources

템플릿은, 이 메소드가 불려 갔는지 어떠했는지를 나타내는 사적인 플래그를 보관 유지한다. 이 플래그가 이미 TRUE 가 되어 있을 때 메소드가 불려 가면(자),InternalAllocateStreamingResources 메소드를 호출하지 않고 S_OK 를 돌려준다. FreeStreamingResources 메소드는 이 플래그를 FALSE 에 리셋 한다.

DMOLock

이 메소드는 IMediaObject::Lock 메소드를 이행 한다. ATL 와의 이름의 경합을 피하기 (위해)때문에,IMediaObjectImpl 에서는 메소드명이 DMOLock 로 변경되고 있다.

주 : 상속 클래스를 구축할 경우에는, DMO 헤더 파일을 인클루드 하기 전에 FIX_LOCK_NAME 를 정의한다. FIX_LOCK_NAME 유사 명령이 있으면(자), 프리프로세서는,IMediaObject 인터페이스의 선언에 있는 Lock 를 DMOLock 에 바꾼다. 다만, vtable 순서는 변함없기 때문에, 어플리케이션에서는 Lock 라는 이름을 사용해 메소드를 기동할 수 있다.

#define FIX_LOCK_NAME
#include <dmo.h>

이 메소드는, 파라미터가 TRUE 라면 Lock 를 호출해, 파라미터가 FALSE 라면 Unlock 를 호출한다. 상속 클래스는,Lock 메소드와 Unlock 메소드를 이행 할 필요가 있다.

Flush

템플릿은, 오브젝트가 플래시 되었는지 어떠했는지를 나타내는 사적인 플래그를 보관 유지한다. Flush 메소드는 이 플래그를 TRUE 에 세트 해,ProcessInput 메소드는 FALSE 에 리셋 한다. 플래그가 이미 TRUE 가 되어 있을 때 Flush 가 불려 가면(자),InternalFlush 메소드를 호출하지 않고 S_OK 를 돌려준다.

GetInputSizeInfo, GetOutputSizeInfo

미디어 타입이 설정되어 있지 않은 필수 스트림이 있는 경우, 이 2 개의 메소드는 DMO_E_TYPE_NOT_SET 를 돌려준다. 따라서, 상속 클래스의 내부 메소드에서는, 모든 필수 스트림에 미디어 타입이 설정되어 있는 것을 전제로 처리할 수 있다.

GetInputStatus

이 메소드는, 상속 클래스가 이행 하는 InternalAcceptingInput 메소드를 호출한다. InternalAcceptingInput 메소드는, 지정된 입력 스트림이 입력을 받아들이는 경우에는 S_OK 를 돌려준다. 그 이외의 경우에는, S_FALSE 를 돌려준다.

미디어 타입이 설정되어 있지 않은 필수 스트림이 있는 경우,GetInputStatus 메소드는 DMO_E_TYPE_NOT_SET 를 돌려준다. 따라서,InternalAcceptingInput 의 이행으로 이 조건을 확인할 필요는 없다.

ProcessInput

이 메소드는,InternalProcessInput 를 호출하기 전에 AllocateStreamingResources 와 InternalAcceptingInput 를 호출한다. 따라서,InternalProcessInput 의 이행에서는, 이하의 조건을 전제로 처리를 할 수 있다.

  • 리소스는 모두 할당할 수 있고 있다.
  • 입력 스트림은 데이터를 받아들인다.

ProcessOutput

이 메소드는,InternalProcessOutput 를 호출하기 전에 AllocateStreamingResources 를 호출한다. 따라서,InternalProcessOutput 의 이행에서는, 리소스를 모두 할당할 수 있고 있는 것을 전제로 처리할 수 있다.

SetInputType

이 메소드는, 입력 스트림의 미디어 타입을 테스트, 설정, 또는 소거한다. 이 메소드는, 상속 클래스가 이행 하는 InternalCheckInputType 메소드를 호출한다. InternalCheckInputType 메소드는, 미디어 타입이 받아들이고 가능한 경우에는 S_OK 를 돌려주어, 그 이외의 경우에는 에러 코드를 돌려준다. 나머지의 기능은 SetInputType 메소드가 실현된다.

이 메소드는 리소스의 할당을 실시하지 않는다. DMO 가 스트림 상태에 바뀌면(자),AllocateStreamingResources 메소드가 불려 간다. 상속 클래스에서는,InternalAllocateStreamingResources 메소드를 사용해, 메모리 버퍼등이 필요한 리소스를 할당하지 않으면 안 된다.

SetOutputType

이 메소드는, 출력 스트림의 미디어 타입을 테스트, 설정, 또는 소거한다. 이 메소드는, 상속 클래스가 이행 하는 InternalCheckOutputType 메소드를 호출한다. InternalCheckOutputType 메소드는, 미디어 타입이 받아들이고 가능한 경우에는 S_OK 를 돌려주어, 그 이외의 경우에는 에러 코드를 돌려준다. 나머지의 기능은 SetOutputType 메소드가 이행 한다.

이 메소드는 리소스의 할당을 실시하지 않는다. DMO 가 스트림 상태에 바뀌면(자),AllocateStreamingResources 메소드가 불려 간다. 상속 클래스에서는,InternalAllocateStreamingResources 메소드를 사용해 메모리 버퍼등이 필요한 리소스를 할당하지 않으면 안 된다.


미디어 파라미터

미디어 파라미터는, 오브젝트의 프로퍼티에 대한 실행시의 변경을 지원 하는 새로운 API 세트이다. 급속히 변화해, 높은 퍼포먼스와 반복성의 양쪽 모두가 요구되는 프로퍼티를 정확하게 제어할 수 있다. 미디어 파라미터를 사용 하면, 프로퍼티에 의해 정현파나 역직사각형 곡선등이 엄밀한 곡선을 리얼타임에 보충할 수 있다.

데이터 변환 오브젝트는, 미디어 파라미터를 사용해, 실행시의 동작을 제어하는 표준 인터페이스를 지원 할 수 있다. 미디어 파라미터를 Microsoft® DirectX® Media Objects (DMO)와 조합해 사용 하면, 오디오 이펙트의 생성으로 특히 편리하다. 예를 들어, 메아리 이펙트에서는, 드라이 (미처리의) 신호에 대한 웨트 (처리필 보고) 신호의 비율이 순조로운 곡선을 보충하도록(듯이) 할 수가 있다. 이러한 동작은, 오디오 엔지니어링에 있어 레코딩에 부자연스러운 효과가 도입되는 것을 막기 위해서(때문에) 중요하다.

여기에서는, 다음의 내용에 대해 설명한다.

  • 미디어 파라미터의 레퍼런스


미디어 파라미터의 레퍼런스

여기에서는, 모든 미디어 파라미터의 레퍼런스 정보를 나타낸다.

  • 인터페이스
  • 구조체
  • 열거형
  • 정수
  • 글로벌 일의 식별자 (GUID)


인터페이스

여기에서는, 모든 Microsoft® DirectX® 미디어 파라미터 COM 인터페이스 및 각 인터페이스의 메소드의 레퍼런스 항목을 나타낸다.

  • IMediaParamInfo
  • IMediaParams


IMediaParamInfo 인터페이스

오브젝트가 지원 하는 파라미터에 관한 정보를 취득한다. 어플리케이션의 실행중, 오브젝트가 지원 하는 파라미터의 집합은 변함없다. 파라미터값을 설정하려면 ,IMediaParams 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트의 값을 늘린다.
Release | 참조 카운트의 값을 줄인다.
IMediaParamInfo 메소드 | 설명
GetParamCount | 오브젝트가 지원 하는 파라미터의 수를 취득한다.
GetParamInfo | 지정된 파라미터에 관한 정보를 취득한다.
GetParamText | 파라미터를 설명하는 캐릭터 라인의 배열을 취득한다.
GetNumTimeFormats | 오브젝트가 지원 하는 타임 포맷의 수를 취득한다.
GetSupportedTimeFormat | 지원 되고 있는 타임 포맷을 취득한다.
GetCurrentTimeFormat | 현재의 타임 포맷을 취득한다.

IMediaParamInfo::GetParamCount

IMediaParamInfo 인터페이스

오브젝트가 지원 하는 파라미터의 수를 취득한다.

구문

HRESULT GetParamCount(
    DWORD *pdwParams
);

파라미터

pdwParams
[out] 파라미터의 수를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

IMediaParamInfo::GetParamInfo

IMediaParamInfo 인터페이스

지정된 파라미터에 관한 정보를 취득한다.

구문

HRESULT GetParamInfo(
    DWORD dwParamIndex,
    MP_PARAMINFO *pInfo
);

파라미터

dwParamIndex
[in] 파라미터의 제로 베이스의 인덱스.
pInfo
[out] 파라미터 정보가 삽입되는 MP_PARAMINFO 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_INVALIDARG | 범위외의 인덱스.
E_POINTER | NULL 포인터 인수.

주의

오브젝트가 지원 하는 파라미터의 수를 취득하려면 ,GetParamCount 메소드를 호출하는 것.

IMediaParamInfo::GetParamText

IMediaParamInfo 인터페이스

파라미터를 설명하는 일련의 캐릭터 라인을 취득한다.

구문

HRESULT GetParamText(
    DWORD dwParamIndex,
    WCHAR **ppwchText
);

파라미터

dwParamIndex
[in] 파라미터의 제로 베이스의 인덱스.
ppwchText
[out] 일련의 Unicode? 캐릭터 라인에의 포인터를 받는 변수의 주소.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_INVALIDARG | 범위외의 인덱스.
E_POINTER | NULL 포인터 인수.

반환값

메소드가 성공했을 경우,*ppwchText 는 다음의 서식을 가지는 캐릭터 라인을 가리킨다.

Name\0Unit\0Enum1\0Enum2\0...EnumN\0\0

각 항목은 다음대로.

  • Name 는, 파라미터의 이름이다.
  • Unit 는, 단위의 이름이다. 예를 들어 milliseconds 등.
  • Enum1 ~ EnumN 는, 파라미터의 열거값을 나타내요 셋집 들이마셔 이름이다. MPT_ENUM 형의 파라미터인 만큼 적용된다.

어플리케이션은 유저 인터페이스내에 이러한 값을 표시할 수 있다. 이러한 값은 반드시 일관성이 있는 명명 규칙에 따르지 않았다. 유저의 컴퓨터로 국제 code page가 사용되고 있는 경우는, 이 메소드는, 그 code page에 대응하는 로컬라이즈 된 캐릭터 라인을 돌려주는 일이 있다.

오브젝트는 CoTaskMemAlloc 함수를 사용해 캐릭터 라인의 메모리를 할당한다. 이 메소드를 호출한 후,CoTaskMemFree 를 호출해 버퍼를 해방하는 것.

IMediaParamInfo::GetNumTimeFormats

IMediaParamInfo 인터페이스

오브젝트가 지원 하는 타임 포맷의 수를 취득한다.

구문

HRESULT GetNumTimeFormats(
    DWORD *pdwNumTimeFormats
);

파라미터

pdwNumTimeFormats
[out] 지원 되고 있는 타임 포맷의 수를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

IMediaParamInfo::GetSupportedTimeFormat

IMediaParamInfo 인터페이스

지원 되고 있는 타임 포맷을 취득한다.

구문

HRESULT GetSupportedTimeFormat(
    DWORD dwFormatIndex,
    GUID *pguidTimeFormat
);

파라미터

dwFormatIndex
[in] 취득하는 타임 포맷의 인덱스.
pguidTimeFormat
[out] 타임 포맷 GUID 를 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_INVALIDARG | 범위외의 인덱스.
E_POINTER | NULL 포인터 인수.

주의

오브젝트가 지원 하는 타임 포맷의 수를 취득하려면 ,GetNumTimeFormats 메소드를 호출하는 것.

IMediaParamInfo::GetCurrentTimeFormat

IMediaParamInfo 인터페이스

현재의 타임 포맷을 취득한다.

구문

HRESULT GetCurrentTimeFormat(
    GUID *pguidTimeFormat,
    MP_TIMEDATA *pTimeData
);

파라미터

pguidTimeFormat
[out] 타임 포맷 GUID 를 받는 변수에의 포인터.
pTimeData
[out] 새로운 포맷의 단위를 지정하는 MP_TIMEDATA 값을 받는 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_POINTER | NULL 포인터 인수.

주의

pTimeData 파라미터에 돌려주어지는 값의 의미는, 타임 포맷 GUID 에 따라서 다르다. 상세한 것에 대하여는, 「IMediaParams::SetTimeFormat 」를 참조할것.


IMediaParams 인터페이스

오브젝트의 포락선 보충 파라미터를 취득한다.

오버헤드를 줄이기 위해서(때문에), 파라미터는 인덱스값에 의해 참조되어 모든 파라미터값은 MP_DATA 형으로서 정의되는 32 비트이다. 지정된 파라미터가 정수, 부동 소수점값, 불리언 값, 또는 열거형의 멤버의 머지않아인지를 확인하려면 ,IMediaParamInfo 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트의 값을 늘린다.
Release | 참조 카운트의 값을 줄인다.
IMediaParams 메소드 | 설명
GetParam | 지정된 파라미터의 최신의 값을 취득한다.
SetParam | 파라미터의 값을 설정한다.
AddEnvelope | 파라미터에 포락선을 추가한다.
FlushEnvelope | 지정된 파라미터의 포락선 데이터가 지정된 시간의 범위에서 플래시 한다.
SetTimeFormat | 오브젝트의 타임 포맷을 지정한다.

IMediaParams::GetParam

IMediaParams 인터페이스

지정된 파라미터의 현재의 값을 취득한다. 파라미터가 현재 포락선 세그먼트(segment)내에 있는 경우는, 반환값은 마지막에 처리된 샘플의 값이다.

구문

HRESULT GetParam(
    DWORD dwParamIndex,
    MP_DATA *pValue
);

파라미터

dwParamIndex
[in] 파라미터의 제로 베이스의 인덱스.
pValue
[out] 파라미터값을 받는 MP_DATA 형의 변수에의 포인터.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_INVALIDARG | 범위외의 인덱스.
E_POINTER | NULL 포인터 인수.

주의

이 오브젝트에 의해 지원 되는 파라미터를 인덱스값과 함께 열거하려면 ,IMediaParamInfo 인터페이스를 사용하는 것.

IMediaParams::SetParam

IMediaParams 인터페이스

파라미터의 값을 설정한다.

구문

HRESULT SetParam(
    DWORD dwParamIndex,
    MP_DATA value
);

파라미터

dwParamIndex
[in] 파라미터의 제로 베이스의 인덱스, 또는 모든 파라미터에 값을 적용하는 DWORD_ALLPARAMS.
value
[in] 파라미터의 새로운 값.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_INVALIDARG | 범위외의 인덱스, 또는 파라미터값이 무효.

주의

파라미터가 현재 포락선 세그먼트(segment)내에 있는 경우, 포락선 세그먼트(segment)는 새로운 값을 오버라이드(override) 한다. 포락선 세그먼트(segment)를 삭제하려면 ,FlushEnvelope 메소드를 호출하는 것.

이 오브젝트에 의해 지원 되는 파라미터를 인덱스값과 함께 열거하려면 ,IMediaParamInfo 인터페이스를 사용하는 것.

IMediaParams::AddEnvelope

IMediaParams 인터페이스

파라미터에 포락선을 추가한다.

구문

HRESULT AddEnvelope(
    DWORD dwParamIndex,
    DWORD cPoints,
    MP_ENVELOPE *pEnvelope,
);

파라미터

dwParamIndex
[in] 인덱스의 제로 베이스의 인덱스, 또는 모든 파라미터에 포락선을 추가하는 DWORD_ALLPARAMS.
cPoints
[in] 포락선내의 세그먼트(segment)의 수.
pEnvelope
[in] 포락선 세그먼트(segment)을 정의하는 MP_ENVELOPE 구조체의 배열. 배열의 사이즈는 cPoints 파라미터로 지정한다.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_INVALIDARG | 범위외의 인덱스.
E_OUTOFMEMEORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.

주의

포락선이 기존의 포락선과 오버랩 하면나무는, 새로운 포락선이 우선된다.

이 오브젝트에 의해 지원 되는 파라미터를 인덱스값과 함께 열거하려면 ,IMediaParamInfo 인터페이스를 사용하는 것.

IMediaParams::FlushEnvelope

IMediaParams 인터페이스

지정된 파라미터의 포락선 데이터가 지정된 시간의 범위에서 플래시 한다.

구문

HRESULT FlushEnvelope(
    DWORD dwParamIndex,
    REFERENCE_TIME refTimeStart,
    REFERENCE_TIME refTimeEnd
);

파라미터

dwParamIndex
[in] 파라미터의 제로 베이스의 인덱스, 또는 모든 파라미터의 포락선 데이터를 플래시 하는 DWORD_ALLPARAMS.
refTimeStart
[in] 포락선 데이터의 플래시를 시작 할 시간.
refTimeEnd
[in] 포락선 데이터의 플래시를 정지하는 시간.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_INVALIDARG | 범위외의 인덱스.

주의

refTimeStart 와 refTimeEnd 에 의해 지정된 시간의 범위가 포락선 세그먼트(segment)로 오버랩 하는 경우는, 세그먼트(segment) 전체가 플래시 된다. 한편, 포락선 세그먼트(segment)의경계에 해당하는 경우는, 세그먼트(segment) 전체가보관 유지된다. 즉, 다음과 같이 된다.

  • 시작 타임이 포락선 세그먼트(segment)의 안쪽인 경우는, 세그먼트(segment)는 플래시 된다.
  • 종료 타임이 포락선 세그먼트(segment)의 안쪽인 경우는, 세그먼트(segment)는 플래시 된다.
  • 시작 타임이 포락선 세그먼트(segment)의 종료 타임에 동일한 경우는, 세그먼트(segment)는 보관 유지된다.
  • 종료 타임이 포락선 세그먼트(segment)의 시작 타임에 동일한 경우는, 세그먼트(segment)는 보관 유지된다.

이 오브젝트에 의해 지원 되는 파라미터를 인덱스값과 함께 열거하려면 ,IMediaParamInfo 인터페이스를 사용하는 것.

IMediaParams::SetTimeFormat

IMediaParams 인터페이스

오브젝트의 타임 포맷을 지정한다.

구문

HRESULT SetTimeFormat(
    GUID guidTimeFormat,
    MP_TIMEDATA mpTimeData
);

파라미터

guidTimeFormat
[in] 타임 포맷을 지정하는타임 포맷 GUID .
mpTimeData
[in] 새로운 포맷의 단위를 지정하는 MP_TIMEDATA 형의 값.

반환값

HRESULT 값을 돌려준다. 돌려주어지는 값은 다음대로.

S_OK | 성공.
E_DMOTIMESTAMPFORMAT | 오브젝트는 이 타임 포맷을 지원 하고 있지 않다.

주의

오브젝트는 복수의 타임 포맷을 지원 할 수 있다. 모든 오브젝트는, 100 나노초 (ns) 단위의기준타임을 지원 할 필요가 있다. 그 외의 포맷은 옵션이다. 어플리케이션은, 입력 버퍼의 타임 스탬프가, 이 메소드를 사용해 설정된 타임 포맷에 일치하는 것을 보증해야 한다.

mpTimeData 파라미터의 값은,guidTimeFormat 파라미터의 값에 따라서 다르다.

타임 포맷 | 타임 데이터의 의미
GUID_TIME_REFERENCE | 무시된다.
GUID_TIME_MUSIC | 사분 음표 1 개 당의 파트수.
GUID_TIME_SAMPLES | 1 초 쯤의 샘플수.

이 메소드를 호출하는 경우는,FlushEnvelope 메소드도 호출해, 전의 타임 포맷을 사용해 설정된 포락선을 플래시 한다.

오브젝트가 어느 타임 포맷을 지원 하고 있는지를 확인하려면 ,IMediaParamInfo::GetSupportedTimeFormat 메소드를 호출한다. 현재의 포맷을 취득하려면 ,IMediaParamInfo::GetCurrentTimeFormat 메소드를 호출한다.


구조체

여기에서는, Microsoft® DirectX® 의 미디어 파라미터 구조체에 대해 설명한다.

구조체 | 설명
MP_ENVELOPE | 포락선 보충 파라미터에 의해 사용되는 포락선 세그먼트(segment)를 정의한다.
MP_PARAMINFO | 파라미터에 관한 정보를 포함한다.


MP_ENVELOPE 구조체

구조체

포락선 보충 파라미터에 의해 사용되는 포락선 세그먼트(segment)를 정의한다.

구문

typedef struct _MP_ENVELOPE {
    REFERENCE_TIME   rtStart;
    REFERENCE_TIME   rtEnd;
    MP_DATA          valStart;
    MP_DATA          valEnd;
    MP_CURVE_TYPE    iCurve;
    MP_FLAGS         flags;
} MP_ENVELOPE;

멤버

rtStart
세그먼트(segment)의 시작 타임. 최초의 버퍼의 타임 스탬프에 대해서 상대적으로, 100 나노초단위로 나타낸다.
rtEnd
세그먼트(segment)의 종료 타임. 최초의 버퍼의 타임 스탬프에 대해서 상대적으로, 100 나노초단위로 나타낸다.
valStart
세그먼트(segment) 시작 시점에서의 파라미터의 초기값.
valEnd
세그먼트(segment) 종료시점에서의 파라미터의 최종값.
iCurve
파라미터가 보충하는 곡선을 지정하는 MP_CURVE_TYPE 열거형의 멤버.
플래그
포락선 플래그의 비트 단위의 편성.


MP_PARAMINFO 구조체

구조체

파라미터에 관한 정보를 포함한다.

구문

typedef struct _MP_PARAMINFO {
    MP_TYPE    mpType;
    MP_CAPS    mopCaps;
    MP_DATA    mpdMinValue;
    MP_DATA    mpdMaxValue;
    MP_DATA    mpdNeutralValue;
    WCHAR      szUnitText[32];
    WCHAR      szLabel[32];
} MP_PARAMINFO;

멤버

mpType
이 파라미터의 유효한 데이터형을 지정하는 MP_TYPE 열거형의 멤버.
mopCaps
어느 포락선 곡선이 지원 되는지를 지정하는 1 개(살) 이상의능력 플래그의 비트 단위의 편성. 불형 및 열거형 파라미터에서는 MP_CAPS_CURVE_JUMP 만이 유효하다.
mpdMinValue
파라미터의 최소 값. 수치를 가지는 파라미터인 만큼 사용한다.
mpdMaxValue
파라미터의 최대치. 수치를 가지는 파라미터인 만큼 사용한다.
mpdNeutralValue
파라미터의 디폴트 또는 "중간 " 값.
szUnitText
파라미터의 단위의 이름을 포함한 NULL 종단 Unicode™ 캐릭터 라인.
szLabel
파라미터의 이름을 포함한 NULL 종단 Unicode™ 캐릭터 라인.

멤버

szUnitText 및 szLabel 멤버는, 항상 영어의 캐릭터 라인을 포함한다. 다언어 지원이 필요한 경우는,IMediaParamInfo::GetParamText 메소드를 사용하는 것.


열거형

여기에서는, Microsoft® DirectX® 의 미디어 파라미터 열거형에 대해 설명한다.

열거형 | 설명
MP_CURVE_TYPE | 포락선 세그먼트(segment)내에서 미디어 파라미터가 보충하는 곡선을 정의한다.
MP_TYPE | 파라미터의 데이터형을 지정한다.


MP_CURVE_TYPE 열거

열거형

포락선 세그먼트(segment)내에서 미디어 파라미터가 보충하는 곡선을 정의한다.

구문

typedef enum _MP_CURVE_TYPE {
    MP_CURVE_JUMP       = 0x0001,
    MP_CURVE_LINEAR     = 0x0002,
    MP_CURVE_SQUARE     = 0x0004,
    MP_CURVE_INVSQUARE  = 0x0008,
    MP_CURVE_SINE       = 0x0010,
    MP_CURVE_CURRENTVAL = 0x8000,
} MP_CURVE_TYPE;

요소

MP_CURVE_JUMP
보간 없음. 다음의 포인트에 점프.
MP_CURVE_LINEAR
리니어 보간.
MP_CURVE_SQUARE
포물선 곡선.
MP_CURVE_INVSQUARE
역직사각형 곡선.
MP_CURVE_SINE
사인 곡선.
MP_CURVE_CURRENTVAL
이 세그먼트(segment)에 대해서 지정된 시작값을 무시한다. 직전의 세그먼트(segment)의 최종값으로부터 시작 한다.

주의

다음의 표는, 미리 정의되고 있는 곡선과 각 곡선의 수학적 표현의 일람이다.

값 | 적합하는 곡선 | 범위
MP_CURVE_LINEAR | y = x | 0.0 – 1. 0
MP_CURVE_SQUARE | y = x2 | 0.0 – 1. 0
MP_CURVE_INVSQUARE | y = 1 – x2 | 0.0 – 1. 0
MP_CURVE_SINE | y = sin(x) | –π/2 – π/2

불형 또는 열거형 파라미터에서는 MP_CURVE_JUMP 만이 유효하다.

참조

MP_ENVELOPE


MP_TYPE 열거

열거형

파라미터의 데이터형을 지정한다.

구문

typedef enum _MP_Type {
    MPT_INT,
    MPT_FLOAT,
    MPT_BOOL,
    MPT_ENUM,
    MPT_MAX,
} MP_TYPE;

요소

MPT_INT
값은 32 비트의 부호 첨부 정수이다.
MPT_FLOAT
값은 32 비트의 IEEE 부동 소수점값이다.
MPT_BOOL
값은 불리언 값이다. 불형 파라미터에는 다음의 정수를 사용하는 것.
정수 | 설명
MP_DATA MPBOOL_TRUE | TRUE
MP_DATA MPBOOL_FALSE | FALSE
MPT_ENUM
값은 연속하는 정수의 조로부터 취득된다.
MPT_MAX
예약이 끝난 상태.

주의

실행시의 형태 변환을 줄이기 위해서(때문에), 모든 파라미터는,MP_DATA 로서 정의되는 32 비트의 부동 소수점값을 가진다. 이 열거의 멤버는, 지정된 파라미터를 어떻게 해석하는지를 지정한다.

참조

MP_PARAMINFO


정수

Microsoft® DirectX® 미디어 파라미터로서 다음의 정수가 정의되고 있다.

  • 파라미터 능력 플래그
  • 포락선 플래그

파라미터 능력 플래그

파라미터 능력 플래그는, 지원 되고 있는 포락선 곡선을 지정한다.

정수 | 설명
MP_CAPS_CURVE_JUMP | 보간을 실시하지 않고 다음의 포인트에 점프 한다. 「MP_CURVE_JUMP 」를 참조할것.
MP_CAPS_CURVE_LINEAR | 리니어 보간. 「MP_CURVE_LINEAR 」를 참조할것.
MP_CAPS_CURVE_SQUARE | 포물선 곡선. 「MP_CURVE_SQUARE 」를 참조할것.
MP_CAPS_CURVE_INVSQUARE | 역직사각형 곡선. 「MP_CURVE_INVSQUARE 」를 참조할것.
MP_CAPS_CURVE_SINE | 사인 곡선. 「MP_CURVE_SINE 」를 참조할것.

포락선 플래그

포락선 플래그는, 포락선 세그먼트(segment)에 관한 정보를 지정한다.

정수 | 설명
MPF_ENVLP_STANDARD | 포락선 세그먼트(segment)로 제공되는 모든 정보를 사용한다.
MPF_ENVLP_BEGIN_CURRENTVAL | 지정된 시작값을 무시한다. 현재의 값으로부터 시작 한다.
MPF_ENVLP_BEGIN_NEUTRALVAL | 지정된 시작값을 무시한다. 중간값으로부터 시작 한다. 「MP_PARAMINFO 」를 참조할것.

참조

MP_ENVELOPE


미디어 파라미터 GUID

여기에서는, Microsoft® DirectX® 의 미디어 파라미터용으로 정의되고 있는 글로벌 일의 식별자 (GUID)를 나타낸다.

  • 타임 포맷 GUID

타임 포맷 GUID

다음의 표는, 미디어 파라미터의 타임 포맷으로 사용하는 GUID 의 일람이다.

GUID | 설명
GUID_TIME_REFERENCE | 100 나노초단위의 기준 타임.
GUID_TIME_MUSIC | 사분 음표 1 개 당의 파트수로 나타낸 뮤직 타임.
GUID_TIME_SAMPLES | 1 초 쯤의 샘플수.


부록

  • C 에 의한 필터 그래프의 제어
  • 사용이 금지되고 있는 인터페이스
  • DirectShow 그래프 파일 포맷
  • Filter Graph Markup Language (XGR)
  • 국제 아날로그 TV의 튜닝
  • 멀티미디어 스트리밍
  • SMPTE 타임 코드
  • Visual Basic 에서의 DirectShow 의 사용법
  • 관련 정보


C 에 의한 필터 그래프의 제어

Microsoft® DirectShow® 어플리케이션을 (C++ 는 아니고) C 로 쓰고 있다면, 메소드를 호출할 때에 vtable 를 사용해야 한다. 이하의 예는 IUnknown::QueryInterface 메소드를 C 로 쓰여진 어플리케이션으로부터 호출하는 방법을 나타낸다 :

pGraph->lpVtbl->QueryInterface(pGraph, &IID_IMediaEvent, (void **) &pEvent);

이하는 상기와 동일한 C++ 의 호출이다 :

pGraph->QueryInterface(IID_IMediaEvent, (void **) &pEvent);

C 에서는 인터페이스는 구조체로서 정의되고 있다. lpVtbl 멤버는 인터페이스 메소드의 겉(표) (vtable)에의 포인터이다. 모든 메소드는 인터페이스에의 포인터인 추가 파라미터를 가지고 있다.


사용이 금지되고 있는 인터페이스

다음의 인터페이스는 사용이 금지되고 있다. 이러한 인터페이스는, 기존의 어플리케이션과의 호환성을 유지하기 위해서(때문에) 계속 지원 되지만, 새로운 어플리케이션에서는 이러한 인터페이스를 사용해서는 안된다.

  • IAMovieSetup
  • IAMDevMemoryAllocator
  • IAMDevMemoryControl
  • IAMPhysicalPinInfo
  • ICaptureGraphBuilder
  • IDirectDrawFactory
  • IDirectDraw3
  • IDvdControl
  • IDvdInfo
  • IEnumRegFilters
  • IFilterMapper


IAMovieSetup 인터페이스

주 : 이 인터페이스의 사용은 피하는 것. 이 인터페이스는, 이전의 버젼에 있어서의 AMovieDllRegisterServer 및 AMovieDllUnregisterServer 라고 하는 2 개의 함수로 사용되고 있었다. 이러한 함수에 대신해 현재는 AMovieDllRegisterServer2 가 사용되고 있어 이 함수는 IAMovieSetup 를 필요로 하지 않는다. 다만,IAMovieSetup 는, 기존의 어플리케이션과의 후방 호환성을 유지하기 위해서(때문에), 계속해 지원 된다.

Microsoft® ActiveMovie® 1.0 에서는, 필터는 다음에 나타내는 자기 레지스트리 등록을 이행 하고 있었다.

  • DllRegisterServer 함수의 내부에서, 필터의 DLL 가 AMovieDllRegisterServer 함수를 호출하고 있었다. 이 함수는, 각 필터의 IAMovie 인터페이스에 대해 조회해,IAMovieSetup::Register 메소드를 호출한다.
  • DllUnregisterServer 함수의 내부에서, 필터의 DLL 가 AMovieDllUnregisterServer 함수를 호출하고 있었다. 이 함수도 각 필터의 IAMovie 인터페이스를 조회하지만,IAMovieSetup::Unregister 메소드를 호출한다.

위에 나타낸 것처럼, 현재는 AMovieDllRegisterServer2 함수를 사용해야 한다. 이 함수로 등록되는 필터는,IAMovieSetup 를 이행 할 필요는 없다. 상세한 것에 대하여는, 「DirectShow 오브젝트의 등록 방법」을 참조할것.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMovieSetup 메소드 | 설명
Register | 레지스트리에 필터를 추가한다.
Unregister | 레지스트리로부터 필터를 삭제한다.

IAMovieSetup::Register

IAMovieSetup 인터페이스

레지스트리에 필터를 추가한다.

구문

HRESULT Register(void);

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드는, 필터, 그 핀, 및 핀에 관련지을 수 있고 있는 미디어 타입을 등록한다. 이것을 실시하기 위해서(때문에)는,IFilterMapper 메소드를 사용하도록(듯이) 이행 할 필요가 있다. 그 이행에 대해서는, 「CBaseFilter::Register 」멤버 함수를 참조할것.

IAMovieSetup::Unregister

IAMovieSetup 인터페이스

레지스트리로부터 필터를 삭제한다.

구문

HRESULT Unregister(void);

반환값

이행에 응한 HRESULT 값을 돌려준다. HRESULT 는, 다음의 표준적인 정수의 1 개인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
E_FAIL | 실패.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK 또는 NOERROR | 성공.

주의

이 메소드로 레지스트리로부터 필터를 삭제하려면 ,IFilterMapper::UnregisterFilter 메소드를 사용하도록(듯이) 이 메소드를 이행 할 필요가 있다. 이 메소드는, 핀과 미디어 타입도 효율적으로 삭제한다.


IAMDevMemoryAllocator 인터페이스

주 이 인터페이스는 낡아지고 있다. 그것은 AVI 파일의 하드웨어 메모리에의 직접 읽기입을 요구하는 있는 낡은 하드웨어 디코더를 지원 하기 위해서 정의되었다. 이 인터페이스에 의해 PVI 퍼서는 다운 스트림 필터로부터 메모리를 할당할 수가 있지만, 그것 자신의 allocater를 여전히 제공한다. 새로운 디바이스가 이 인터페이스를 지원 할 필요는 없다.

IAMDevMemoryAllocator 인터페이스에 의해, 온보드 메모리 매니저 오브젝트를 사용해 써드파티의 메모리 allocater를 생성 할 수 있다. 많은 CODEC 하드웨어 메이커에서는, CODEC 에 온보드 맵 메모리를 장비 하는 것으로, 버퍼 조작의 효율을 높이고 있다. 이 인터페이스에서는 그 메모리를 할당해GetDevMemoryObject 메소드를 사용해,IAMDevMemoryControl 인터페이스를 지원 하는 디바이스 메모리 제어 오브젝트를 취득한다. 같은 디바이스 ID 를 공유하는 디바이스가 메모리를 사용할 수 있다.

글로벌 메모리 매니저 오브젝트는, 이 인터페이스를 이용하는 것으로, 특정의 디바이스 위에의 메모리로부터 메모리를 할당한다.

핀에 대해 온보드 메모리 allocater의 생성을 지원 할 필요가 있는 경우는, 이 인터페이스를 이행 한다. 소스 필터가, 온보드 메모리를 인식해, 독자적인 allocater를 생성 할 필요가 있는 경우는, 이 인터페이스를 조회해, 메모리를 요구해, 디바이스 메모리 제어 오브젝트를 집성 하는 allocater를 생성 한다. 독자적인 allocater를 생성 할 필요가 없는소스 필터의 경우는, 다운 스트림의 핀의 allocater를 그대로 사용한다. 덧붙여 이 allocater도, 디바이스 메모리 제어 오브젝트를 집성 한다. 하드웨어 베이스의 필터는, 집성 된 allocater의 메소드를 호출하는 것에 의해, 자신의 온보드 메모리의 사용을 확인할 수 있다.

이 인터페이스는, 온보드 메모리를 장비 한 CODEC 의 메모리를 어플리케이션으로 제어할 필요가 있는 경우에 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMDevMemoryAllocator 메소드 | 설명
GetInfo | 메모리 기능에 관한 정보를 취득한다.
CheckMemory | allocater의 특정의 디바이스가 메모리 포인터를 할당하고 있는지 어떤지를 조사한다.
Alloc | 메모리 버퍼를 할당한다.
Free | 할당하고 끝난 메모리를 해방한다.
GetDevMemoryObject | 커스텀 allocater로 집성 할 수 있는 디바이스 메모리 제어 오브젝트에의 IUnknown 인터페이스 포인터를 취득한다.

IAMDevMemoryAllocator::Alloc

IAMDevMemoryAllocator 인터페이스

메모리 버퍼를 할당한다.

구문

HRESULT Alloc(
    BYTE **ppBuffer,
    DWORD *pdwcbBuffer
);

파라미터

ppBuffer
[out] 할당할 수 있었던 메모리 버퍼의 주소를 받는 포인터.
pdwcbBuffer
[in, out] DWORD 에의 포인터. 입력값은 할당하는 바이트수로, 출력값은 실제로 할당할 수 있었던 바이트수이다.

반환값

목적의 메모리량을 할당할 수 있었을 경우는 S_OK 를 돌려준다. 메모리를 사용할 수 없는 경우는 S_FALSE 를 돌려준다.

주의

이용 가능한 풀로부터 메모리의 블록을 할당하려면 , 이 메소드를 호출한다.

참조

IAMDevMemoryAllocator::Free

IAMDevMemoryAllocator::CheckMemory

IAMDevMemoryAllocator 인터페이스

allocater의 특정의 인스턴스 (디바이스)가 메모리 포인터를 할당하고 있는지 어떤지를 조사한다.

구문

HRESULT CheckMemory(
    const BYTE *pBuffer
);

파라미터

pBuffer
[in] 할당하고 끝난 메모리 버퍼의 주소에의 포인터.

반환값

온보드 allocater가 메모리를 할당하고 있는 경우는 S_OK 를 돌려준다. 할당하지 않은 경우는 S_FALSE 를 돌려준다. 특정의 디바이스상에 메모리가 있지만 할당할 수 있지 않은 경우도 S_FALSE 를 돌려준다.

주의

보통, 하드웨어 필터는 이 메소드를 사용해, 포인터가 실제로 온보드 메모리를 가리키고 있는지 어떤지를 조사한다.

IAMDevMemoryAllocator::Free

IAMDevMemoryAllocator 인터페이스

할당하고 끝난 메모리를 해방한다.

구문

HRESULT Free(
    BYTE *pBuffer
);

파라미터

pBuffer
[in] 할당하고 끝난 메모리에의 포인터.

반환값

지정의 allocater가 메모리를 할당하지 않은 경우, 즉,CheckMemory 를 실행 하면 실패하는 경우는, E_INVALIDARG 를 돌려준다.

주의

이 메소드는, 풀로부터 메모리 블록을 해방한다.

IAMDevMemoryAllocator::GetDevMemoryObject

IAMDevMemoryAllocator 인터페이스

커스텀 allocater로 집성 할 수 있는 디바이스 메모리 제어 오브젝트에의 IUnknown 인터페이스 포인터를 취득한다.

구문

HRESULT GetDevMemoryObject(
    IUnknown **ppUnkInner,
    IUnknown *pUnkOuter
);

파라미터

ppUnkInner
[out] 새롭고 생성 되는 제어 오브젝트의 IUnknown 에의 포인터의 주소. 이 내부 IUnknown 인터페이스는, 외측의 오브젝트가 파기될 때 해방된다. 커스텀 allocater는, 이 포인터에 대해 QueryInterface 메소드를 호출해,IAMDevMemoryControl 인터페이스를 취득한다.
pUnkOuter
[in] 커스텀 allocater의 IUnknown 인터페이스에의 포인터. 이 인터페이스는, 커스텀 allocater 내부의 디바이스 메모리 제어 오브젝트를 집성 한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

디바이스 메모리 제어 오브젝트는, 커스텀 allocater로 집성 할 필요가 있다. 이것은, 온보드 메모리를 사용하는렌더러가, 새로운 allocater를 받으면(자) IAMDevMemoryControl 를 조회해, 메모리가 같은 디바이스에 근거하는 것을 확인하기 때문이다. 하드웨어 필터가 받는 IMemAllocator 오브젝트는, 온보드 메모리를 사용하는 경우도 사용하지 않는 경우도 있으므로, 이러한 상태가 발생한다. 호환성이 있는 allocater인가 어떤가를 판별하려면 ,IAMDevMemoryControl 인터페이스를 조회해, 특정의 메소드에 액세스 한다. IAMDevMemoryControl 은,IAMDevMemoryControl 의 메소드를 이행 하는 집성 오브젝트를 생성 한다. 덧붙여 이 메소드는, 하드웨어에 의해 자주 다르다.

외측의 오브젝트가 집성화를 이행 할 때의 규칙에 대해서는, COM 의 문서를 참조할것.

IAMDevMemoryAllocator::GetInfo

IAMDevMemoryAllocator 인터페이스

메모리 기능에 관한 정보를 취득한다.

구문

HRESULT GetInfo(
    DWORD *pdwcbTotalFree,
    DWORD *pdwcbLargestFree,
    DWORD *pdwcbTotalMemory,
    DWORD *pdwcbMinimumChunk
);

파라미터

pdwcbTotalFree
[out] 빈메모리의 합계 사이즈에의 포인터.
pdwcbLargestFree
[out] 돌려주어진 중에서 제일 큰 빈메모리 사이즈에의 포인터.
pdwcbTotalMemory
[out] 돌려주어진 메모리의 합계 사이즈에의 포인터.
pdwcbMinimumChunk
[out] 돌려주어진 중에서 최소의 체크사이즈에의 포인터. 이것에 의해, 세분도와 alignment의 규칙이 정해진다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드를 사용 하면, 이용 가능한 메모리의 합계량을 검출할 수 있다. 이 메소드는, 디바이스로 이용 가능한 온보드 메모리 전체의 값을 돌려준다. 복수의 필터 (디바이스)가 메모리를 공유하고 있는 경우는, 그 특정의 디바이스로 이용 가능한 양이 돌려주어진다. 경우에 의해 이 값은, 온보드 메모리의 전체량의 일부이다. 이 값은, 이행에 의해 각각 다르다. 예를 들어, CODEC 위에의 온보드 메모리 매니저는, 카드 위에의 온보드 메모리의 32 MB 모두에게 액세스 할 수 있다. 그러나,IAMDevMemoryAllocator 를 개별적으로 이행 하고 있는 핀에서는, 이 메모리의 일부 밖에 보고되지 않는다.


IAMDevMemoryControl 인터페이스

주 이 인터페이스는 낡아지고 있다. 그것은 AVI 파일의 하드웨어 메모리에의 직접 읽기입을 요구하는 있는 낡은 하드웨어 디코더를 지원 하기 위해서 정의되었다. 이 인터페이스에 의해 PVI 퍼서는 다운 스트림 필터로부터 메모리를 할당할 수가 있지만, 그것 자신의 allocater를 여전히 제공한다. 새로운 디바이스가 이 인터페이스를 지원 할 필요는 없다.

디바이스 메모리 제어 오브젝트는 IAMDevMemoryControl 를 지원 한다. 이 오브젝트는 접속에 사용되는 IMemAllocator 오브젝트로 집성 되고 있다. 보통, 필터는 IAMDevMemoryAllocator::GetDevMemoryObject 메소드를 호출해, 이 인터페이스에의 포인터를 취득한다.

핀에 대해 메모리의 할당을 상세하게 제어할 필요가 있는 경우는,IAMDevMemoryAllocator 인터페이스와 함께 이 인터페이스를 이행 한다.

이 인터페이스를 사용 하면, 메모리 allocater에의 데이터의 기입 종료의 동기를 잡아, 온보드 메모리 allocater의 디바이스 ID 를 취득할 수 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMDevMemoryControl 메소드 | 설명
QueryWriteSync | allocater가 지원 하고 있는 메모리가,WriteSync 메소드의 사용을 필요로 할지 어떨지를 확인한다.
WriteSync | 지정의 allocater 리젼에 기입해지고 있는 데이터가 메모리에 완전하게 기입해지면(자) 돌아가는 것에 의해, 기입 처리의 종료의 동기를 잡는다.
GetDevId | 온보드 메모리 allocater의 디바이스 ID 를 취득한다.

IAMDevMemoryControl::GetDevId

IAMDevMemoryControl 인터페이스

온보드 메모리 allocater의 디바이스 ID 를 취득한다.

구문

HRESULT GetDevId(
  DWORD *pdwDevId
  );

파라미터

pdwDevId
[out] 디바이스 ID 에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드는, 일의인 ID 를 취득한다. 하드웨어 필터는 이 ID 를 사용해, 건네받은 지정의 allocater가 자신의 온보드 메모리를 사용하고 있는 것을 확인할 수 있다. 이러한 확인을 하는 것은, 복수의 온보드 메모리가 존재하기 때문이다. ID 는,CoCreateInstance 를 사용해 allocater 오브젝트를 생성 할 경우에 사용된 ID 와 같은 것이다. 다른 필터가 온보드 메모리를 사용하려면 , 온보드 메모리 allocater와 같은 디바이스 ID 를 가질 필요가 있다.

IAMDevMemoryControl::QueryWriteSync

IAMDevMemoryControl 인터페이스

allocater가 지원 하고 있는 메모리가,IAMDevMemoryControl::WriteSync 메소드의 사용을 필요로 할지 어떨지를 조사한다.

구문

HRESULT QueryWriteSync(void);

반환값

메소드가 필요한 경우는 S_OK 를 돌려준다. 그 이외의 경우는 S_FALSE 를 돌려준다.

주의

WriteSync 를 호출해 기입 종료의 동기를 잡을 필요가 없는 온보드 메모리도 있다. 이 메소드는, 그 호출이 필요한가 어떤가를 조사하기 위해서(때문에) 사용한다.

IAMDevMemoryControl::WriteSync

IAMDevMemoryControl 인터페이스

기입 종료의 동기를 잡기 위해서(때문에) 사용한다. 이 메소드는, 특정의 allocater 리젼에 기입해지고 있는 데이터가, 메모리에 완전하게 기입해지면(자) 돌려주어진다.

구문

HRESULT WriteSync(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 일반적인 반환값은 다음과 같다.
E_FAIL | 데이터가 기입해진 것을 이 메소드가 확인하기 전에 타임 아웃이 발생했다.
S_OK | 데이터가 메모리에 기입해졌다.
VFW_E_NOT_COMMITTED | allocater가 IMemAllocator::Commit 메소드를 호출하지 않았다.

주의

이 메소드에서는, 할당하고 끝난 메모리에의 지금까지의 모든 기입 처리가, 정상적으로 종료하고 있는 것이 전제이다. 이후의 메모리 기입 처리에서는,WriteSync 를 새롭게 호출할 필요가 있다.

이 메소드는 이행에 의해 각각 달라, 메모리에의 기입해 처리의 동기를 잡기 위해서(때문에), 필요에 따라서 사용된다. 온보드 메모리의 드라이버가 이행을 제공한다.

IAMDevMemoryControl 인터페이스는, 보통, PCI (Peripheral Component Interconnect) 브릿지를 개입시켜 액세스 되는 메모리상에 있다. PCI 는 퍼스널 컴퓨터용의 로컬 버스로, 프로세서와 주변기기와의 사이의 고속의 데이터 패스를 제공한다. PCI 브릿지에 접속하고 있는 메모리는, 역시 PCI 브릿지에 접속하고 있는 다른 디바이스가 메모리에 액세스 해 오는 경우, 메모리 기입 처리의 종료후에 동기를 잡을 필요가 있다. 이것은, 메모리에 액세스 하는 호스트는 PCI 브릿지의 FIFO (선입처 방편) 포맷으로 버퍼링 되어 기입이 완료하고 나서 브릿지가 실제로 데이터를 기입하는 것을 전제로 하고 있기 때문에 있다. IAMDevMemoryControl::WriteSync 메소드가 불려 가지 않는 경우는, SCSI 콘트롤러 등, 브릿지에 접속하고 있는 디바이스가, 기입이 완료하기 전에 메모리를 읽어내는 일이 있다.


IAMPhysicalPinInfo 인터페이스

주 : 이 인터페이스의 사용은 피하는 것. 기존의 어플리케이션과의 후방 호환성을 유지하기 (위해)때문에, 계속해 지원 되지만, 새로운 어플리케이션 및 필터에서는, 이것을 사용해서는 안 된다.

이 인터페이스에 의해, 어플리케이션 또는 필터는, 물리 핀의 타입과 이름을 취득할 수 있다. 이 인터페이스는, 물리적인 하드웨어 접속에 상당하는 핀으로 이행 된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMPhysicalPinInfo 메소드 | 설명
GetPhysicalType | 물리 핀의 타입과 이름을 취득한다.

IAMPhysicalPinInfo::GetPhysicalType

IAMPhysicalPinInfo 인터페이스

물리 핀의 타입과 이름을 취득한다.

구문

HRESULT GetPhysicalType(
    long *pType
     LPOLESTR *ppszType
);

파라미터

pType
[out] 핀의 타입을 나타내는 값을 받는 변수에의 포인터. 핀의 타입값은,PhysicalConnectorType 열거형으로 정의된다.
ppszType
[out] 핀의 타입을 알기 쉽게 가리킨 캐릭터 라인을 받는 버퍼에의 포인터의 주소.

반환값

유효한 핀의 값이 발견되었을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, VFW_E_NO_ACCEPTABLE_TYPES 를 돌려준다.


ICaptureGraphBuilder 인터페이스

주 : 이 인터페이스의 사용은 피하는 것. 기존의 어플리케이션과의 후방 호환성을 유지하기 (위해)때문에, 계속해 지원 되지만, 새로운 어플리케이션에서는 ICaptureGraphBuilder2 인터페이스를 사용하는 것.

ICaptureGraphBuilder 인터페이스를 이용 하면, 캡춰 그래프, 프리뷰 그래프, 파일재압축 그래프, 또는 특수한 커스텀 그래프까지 간단하게 생성 할 수 있다.

이 인터페이스를 사용해, WDM 필터를 사용하는 캡춰 그래프를 생성 하면나무는,TV 튜너 필터나아날로그 비디오 크로스바 필터 등, 특별한업 스트림 필터를 그래프에 추가할 필요가 있다. 이러한 필터는,RenderStream 메소드나 FindInterface 를 호출해, 캡춰 필터의 핀을 렌더링 했을 때, 필터 그래프에 짜넣어진다.

이 인터페이스를 이행 하지 않는 것. 이 인터페이스는 Microsoft® DirectShow® 가 자동적으로 이행 한다.

캡춰 어플리케이션 및 재압축 어플리케이션으로 이 인터페이스를 사용해, 필터 그래프의 생성을 간이화 한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
ICaptureGraphBuilder 메소드 | 설명
SetFiltergraph | 사용하는 필터 그래프를 그래프 빌더 오브젝트에 통지한다.
GetFiltergraph | 빌더가 사용하고 있는 필터 그래프를 취득한다.
SetOutputFileName | 지정된 파일명으로 비트를 디스크에 보존하는 필터 그래프의 렌더링 섹션을 생성 한다.
FindInterface | 지정된 인터페이스를 필터, 필터의 업 스트림 및 다운 스트림으로 검색한다. 또, 옵션으로, 지정된 인터페이스를 특정의 카테고리의출력 핀에서만 검색한다.
RenderStream | 옵션으로 지정되는 카테고리의소스 필터의 핀을, 옵션으로 다른 필터를 경유해, 렌더링 필터에 접속한다.
ControlStream | 그래프내의 1 개 이상의 캡춰 필터 위에의 지정된 카테고리의 핀에 스트림 컨트롤 메세지를 보낸다.
AllocCapFile | 캡춰 파일이 지정된 사이즈에 미리 할당한다.
CopyCaptureFile | 미리 할당할 수 있었던 캡춰 파일로부터 유효한 미디어 데이터를 카피한다.

ICaptureGraphBuilder::AllocCapFile

ICaptureGraphBuilder 인터페이스

캡춰 파일이 지정된 사이즈에 미리 할당한다.

구문

HRESULT AllocCapFile(
    LPCOLESTR lpwstr,
    DWORDLONG dwlSize
);

파라미터

lpwstr
[in] 생성 한다, 또는 사이즈를 변경하는 파일의 이름이 저장 된 Unicode™ 캐릭터 라인에의 포인터.
dwSize
[in] 할당할 수 있는 파일의 사이즈 (바이트 단위).

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

파일이 읽어내 전용의 경우, 이 호출은 실패한다. 캡춰로 최선의 결과를 얻으려면 , 항상, 캡춰 데이터보다 사이즈가 크고, 최적화되어 미리 할당할 수 있었던 캡춰 파일에 캡춰 한다.

이 인터페이스의 현재의 DirectShow 이행 환경에서는, Windows NT® 4. x 플랫폼상 또는 Windows 2000 플랫폼상에서(보다), Windows 9x 플랫폼 위에의(분)편이 이 메소드의 호출이 쭉 고속으로 있는 점에 주의 해야 한다.

ICaptureGraphBuilder::ControlStream

ICaptureGraphBuilder 인터페이스

그래프내의 1 개 이상의 캡춰 필터 위에의 지정된 카테고리의 핀에 스트림 컨트롤 메세지를 보낸다.

구문

HRESULT ControlStream(
    const GUID *pCategory,
    IBaseFilter *pFilter,
    REFERENCE_TIME *pstart,
    REFERENCE_TIME *pstop,
    WORD wStartCookie,
    WORD wStopCookie
);

파라미터

pCategory
[in] 출력 핀 카테고리를 지정하는 GUID 에의 포인터. 보통은, 다음의 값이 포함된다. 모든 핀 카테고리의 일람에 대해서는, 「AMPROPERTY_PIN_CATEGORY 」를 참조할것. 이 값을 NULL 로 하는 것은 할 수 없다.
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
pFilter
[in] 제어하는 필터의 IBaseFilter 인터페이스에의 포인터. NULL 를 지정 하면, 그래프내의 모든 캡춰 필터가 제어된다. 각 캡춰 필터에 대해 1 개의 통지가 취득된다.
pstart
[in] 캡춰의 시작 타임에의 포인터. NULL 는 금방 시작 하는 것을 의미한다. MAX_TIME 는 전의 요구를 캔슬하는지, 전의 요구가 없는 경우는, 아무것도 하지 않는 것을 의미한다.
pstop
[in] 캡춰의 종료 타임에의 포인터. NULL 는 금방 종료하는 것을 의미한다. MAX_TIME 는 전의 요구를 캔슬하는지, 전의 요구가 없는 경우는, 아무것도 하지 않는 것을 의미한다.
wStartCookie
[in] 시작 동작이 일어났을 때에 보내는 특정의 값을 지정한다.
wStopCookie
[in] 종료 동작이 일어났을 때에 보내는 특정의 값을 지정한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 현재 이행 되고 있는 DirectShow 는, 캡춰 필터로부터 보내진 마지막 샘플이 렌더링 되기 전에 종료 통지가 보내지면(자) S_FALSE 를 돌려주어, 그 이외의 경우는 S_OK 를 돌려준다.

이 메소드가 S_FALSE 를 돌려주었을 경우, 어플리케이션은, 모든 샘플이 그래프를 통과해 렌더링 될 때까지, 필터 그래프의 종료를 대기하는 것이 좋다. 그렇게 하지 않으면 샘플이 없어지는 일이 있다.

지정한 설명에 일치하는 핀이 없는 경우, 또는 지정된 핀의 일부가 스트림 컨트롤을 지원 할 수 없는 경우, 이 함수는 실패 코드를 돌려준다.

주의

이 메소드는, 프레임 단위의 정밀도가 요구되는 캡춰나, 개별의 캡춰 동작 및 프리뷰 동작의 제어에 사용한다. 예를 들어, 캡춰 화면의 프리뷰만을 실시할 때는, 디스크에의 캡춰 화면의 기입을 오프로 할 수 있다.

이 메소드는, 핀의 IAMStreamControl 인터페이스를 호출한다.

이 메소드는, 지정된 카테고리의 핀으로 발견된 각 필터에 대해 1 개의 통지를 보낸다.

ICaptureGraphBuilder::CopyCaptureFile

ICaptureGraphBuilder 인터페이스

미리 할당할 수 있었던 캡춰 파일로부터 유효한 미디어 데이터를 카피한다.

구문

HRESULT CopyCaptureFile(
    LPOLESTR lpwstrOld,
    LPOLESTR lpwstrNew,
    int fAllowEscAbort,
    IAMCopyCaptureFileProgress *pCallback
);

파라미터

lpwstrOld
[in] 카피원파일명이 저장 된 Unicode™ 캐릭터 라인에의 포인터.
lpwstrNew
[in] 카피처 파일명이 저장 된 Unicode™ 캐릭터 라인에의 포인터. 이 파일에 유효한 데이터가 카피된다.
fAllowEscAbort
[in] Esc 키를 누르면(자) 카피 조작이 중단될지 어떨지를 나타내는 값. TRUE 는 중단되는 것을 나타내, FALSE 는 이 메소드가 Esc 키 조작을 무시하는 것을 나타낸다.
pCallback
[in] 카피 조작의 진행 상황 (퍼센트 단위의 달성율)을 표시하기 위해서 이행 하는 IAMCopyCaptureFileProgress 인터페이스에의 옵션의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

새로운 파일에는 유효한 데이터만이 저장 되기 (위해)때문에, 카피원파일보다 새로운 파일이 훨씬 작아지는 일이 있다. 보통은, 항상, 미리 할당할 수 있던 같은 사이즈의 큰 파일에 캡춰 해, 이 메소드를 사용해, 각 캡춰로부터 보존하고 싶은 데이터만을 새로운 파일에 카피한다.

pCallback 를 지정했을 경우는, 퍼센트 단위의 달성율에 상당하는 0 에서 100 의 사이의 정수를 지정해 IAMCopyCaptureFileProgress 인터페이스의 Progress 메소드를 정기적으로 호출한다.

ICaptureGraphBuilder::FindInterface

ICaptureGraphBuilder 인터페이스

지정된 인터페이스를 필터, 필터의 업 스트림 및 다운 스트림으로 검색한다. 또, 옵션으로, 지정된 인터페이스를 특정의 카테고리의 출력 핀에서만 검색한다.

구문

HRESULT FindInterface(
    const GUID *pCategory,
    IBaseFilter *pf,
    REFIID riid,
    void **ppint
);

파라미터

pCategory
[in] 출력 핀 카테고리를 지정하는 GUID 에의 포인터. 보통은, 다음의 값이 포함된다. 모든 핀 카테고리의 일람에 대해서는, 「AMPROPERTY_PIN_CATEGORY 」를 참조할것. NULL 는, 카테고리에 관계없이, 모든 출력 핀을 검색하는 것을 나타낸다.
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • NULL
pf
[in] 필터의 IBaseFilter 인터페이스에의 포인터.
riid
[in] 목적의 인터페이스의 참조 식별자.
ppint
[out] 하늘의 포인터의 주소. 인터페이스가 발견되었을 경우, 이 메소드는 ppint 를 초기화해, 발견된 인터페이스에의 포인터의 주소를 ppint 에 저장 할 수 있도록(듯이) 한다. 인터페이스를 사용한 후는,Release 메소드를 호출해 참조 카운트를 감소 한다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드는, 카테고리가 지정되어 있지 않은 한, 필터, 필터의 업 스트림 및 다운 스트림으로 인터페이스를 검색한다. 카테고리가 지정되고 있는 경우, 이 메소드는, 그 카테고리의 출력 핀의 다운 스트림만을 검색의 대상으로 한다. 이 메소드를 사용해,렌더러, 멀티플렉서,TV 튜너, 크로스바등을 대상으로 해 인터페이스를 검색할 수 있다.

pCategory == &LOOK_UPSTREAM_ONLY 인 경우, 그래프 빌더는,pf 파라미터로 지정되고 있는 필터의 업 스트림을 검색의 대상으로 하지만, 필터 자체나 필터의 다운 스트림은 검색의 대상으로 하지 않는다.

pCategory == &LOOK_DOWNSTREAM_ONLY 인 경우, 그래프 빌더는,pf 파라미터로 지정되고 있는 필터의 다운 스트림을 검색의 대상으로 하지만, 필터 자체나 필터의 업 스트림은 검색의 대상으로 하지 않는다

예를 들어, 캡춰 그래프는, 비디오 크로스바 (비디오 캡춰 필터의 업 스트림)와 오디오 크로스바 (비디오 크로스바의 업 스트림)의 2 개의 크로스바를 갖추고 있는 일이 있다. 다음에 나타내는 코드에 의해,IAMCrossbar 인터페이스를 이행 하는 비디오 크로스바 필터를 검색할 수 있다.

IAMCrossbar *pVideoCrossbar;
FindInterface(NULL, pVideoCaptureFilter, IID_IAMCrossbar, (void **) &pVideoCrossbar);

게다가 다음에 나타내는 코드에 의해, 오디오 크로스바의 IAMCrossbar 필터를 검색할 수 있다.

IBaseFilter *pBaseFilter;
IAMCrossbar *pAudioCrossbar;
pVideoCrossbar->QueryInterface(IID_IBaseFilter, (void **) pBaseFilter);
FindInterface(
    &LOOK_UPSTREAM_ONLY, pBaseFilter, IID_IAMCrossbar, (void **) &pAudioCrossbar);
pBaseFilter->Release();

ICaptureGraphBuilder::GetFiltergraph

ICaptureGraphBuilder 인터페이스

빌더가 사용하고 있는 필터 그래프를 취득한다.

구문

HRESULT GetFiltergraph(
    IGraphBuilder **ppfg
);

파라미터

ppfg
[out] IGraphBuilder 인터페이스에의 포인터의 주소.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드는 IGraphBuilder 인터페이스의 참조 카운트를 인크리먼트(increment) 한다. 반드시 Release 메소드를 호출해,IGraphBuilder 의 참조 카운트를 감소 하는 것.

ICaptureGraphBuilder::RenderStream

ICaptureGraphBuilder 인터페이스

옵션으로 지정되는 카테고리의 소스 필터의 핀을, 옵션으로 다른 필터를 경유해, 렌더링 필터에 접속한다.

구문

HRESULT RenderStream(
    const GUID *pCategory,
    IUnknown *pSource,
    IBaseFilter *pfCompressor,
    IBaseFilter *pfRenderer
);

파라미터

pCategory
[in] 소스 필터의 어느 출력 핀을 접속하는지를 지정하는 GUID 에의 포인터. 보통은, 다음의 값이 포함된다. 모든 핀 카테고리의 일람에 대해서는, 「AMPROPERTY_PIN_CATEGORY 」를 참조할것. NULL 는, 카테고리에 관계없이, 출력 핀만을 렌더링 하는 것을 나타낸다.
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • NULL
pSource
[in] 소스 필터 또는 출력 핀에 상당하는 IBaseFilter 인터페이스 또는 IPin 인터페이스에의 포인터. 소스 필터는, 보통, AVI 파일 소스 필터나 캡춰 필터등의 파일 소스 필터이다.
pfCompressor
[in] 옵션의압축 필터에 상당하는 IBaseFilter 인터페이스에의 포인터.
pfRenderer
[in] 렌더러에 상당하는 IBaseFilter 인터페이스에의 포인터. ICaptureGraphBuilder::SetOutputFileName 의 ppf (멀티플렉서) 파라미터를 사용해, 이 값을 건네줄 수가 있다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 캡춰 필터에 캡춰 핀은 있지만, 프리뷰 핀이 없는 경우, 캡춰 핀에 대해서 &PIN_CATEGORY_PREVIEW 카테고리를 지정해 RenderStream 를 호출하면, VFW_S_NOPREVIEWPIN 가 돌려주어진다. 그 경우,RenderStream 는스마트티 필터의 프리뷰 핀을 렌더링 한다. 상세한 것에 대하여는, 「주의」를 참조할것.

주의

pCategory 로서 NULL 이외의 AMPROPERTY_PIN_CATEGORY 를 지정해,pSource 로서 캡춰 필터를 지정했을 경우, 이 메소드는, TV 튜너나 크로스바 등, 필요하게 되는 추가의 업 스트림 필터의 인스턴스를 생성해, 그러한 필터를 접속한다. 다음에, 이 메소드는,pSource 의 캡춰 핀을 렌더링 한다.

pSource 가 핀의 경우는,pCategory 로서 NULL 를 지정 하면, 이 메소드는, 그 핀의 스트림을 렌더링 한다.

소스 필터에 출력 핀이 1 개 밖에 없는 경우는,pCategory 로서 NULL 를 지정한다.

파라미터로서 지정된 pSource 필터,pfCompressor 필터 및 pfRenderer 필터는, 이 메소드가 불려 가기 전에 그래프내에 존재하고 있을 필요가 있다.

WDM 캡춰 필터를 사용하는 캡춰 그래프를 생성 하는 경우, 이 메소드는, 모든 필요한 업 스트림 필터 및다운 스트림 필터를 생성 한다.

새로운 WDM VPE (비디오 포토 extension) 비디오 캡춰 하드웨어를 사용하는 일부의 캡춰 필터는, 프리뷰용으로서 PREVIEW 핀 대신에 VIDEO PORT 핀을 갖추고 있다. 이러한 VIDEO PORT 핀은, 비디오 렌더러에 직접 접속되지 않고,오버레이 믹서로 불리는 특수한 필터에 접속된다. 어플리케이션은, 이 점을 고려에 넣을 필요는 없다. &PIN_CATEGORY_PREVIEW 를 지정해 RenderStream 를 호출하면, 필요한 경우에는, 캡춰 그래프 빌더가 오버레이 믹서를 통해서 VIDEO PORT 핀을 올바르게 렌더링 한다.

&PIN_CATEGORY_CAPTURE 카테고리 또는 &PIN_CATEGORY_PREVIEW 카테고리를 지정해 RenderStream 를 사용해, 비디오 캡춰 필터의 캡춰 핀 또는 프리뷰 핀을 렌더링 하는 경우로, 캡춰 필터에 캡춰 핀은 있지만, 프리뷰 핀이 없는 경우는,스마트티 필터 (Qcap.dll)가 자동적으로 사용되어 캡춰와 프리뷰가 동시에 행해진다. 예를 들어,&PIN_CATEGORY_CAPTURE 카테고리를 지정해 RenderStream 를 호출하면, 필터의 캡춰 핀에 스마트티피르타가 실제로 접속되어 스마트티의 캡춰 핀이 렌더링 된다. 다음에,&PIN_CATEGORY_PREVIEW 카테고리를 지정해 RenderStream 를 호출하면, 실제로 스마트티의 프리뷰 핀이 렌더링 된다. &PIN_CATEGORY_PREVIEW 를 지정해 RenderStream 를 호출한 결과, 캡춰 핀과 스마트티피르타가 사용되었을 경우,RenderStream 는 VFW_S_NOPREVIEWPIN 를 돌려주는 것에 의해 그것을 나타낸다. 따라서,FindInterface 가 프리뷰 인터페이스를 찾아낼 수 없는 경우는, 캡춰 필터의 캡춰 핀의 다운 스트림으로 프리뷰 인터페이스가 발견되는 일이 있기 (위해)때문에,&PIN_CATEGORY_PREVIEW 카테고리와 &PIN_CATEGORY_CAPTURE 카테고리를 지정해 FindInterface 를 호출할 필요가 생기는 일이 있다.

ICaptureGraphBuilder::SetFiltergraph

ICaptureGraphBuilder 인터페이스

사용하는 필터 그래프를 그래프 빌더 오브젝트에 통지한다.

구문

HRESULT SetFiltergraph(
    IGraphBuilder *pfg
);

파라미터

pfg
[in] 이 이후의 IFilterGraph::AddFilter 메소드의 호출로 사용하는 필터 그래프를 지정하는 IGraphBuilder 인터페이스에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다.

주의

이 메소드를 호출하지 않는 경우는, 그래프 빌더가 자동적으로 필터 그래프를 생성 한다. 그래프 빌더가 독자적인 필터 그래프를 생성 한 다음에, 이 메소드를 호출하면, 호출은 실패한다.

ICaptureGraphBuilder::SetOutputFileName

ICaptureGraphBuilder 인터페이스

지정된 파일명으로 비트를 디스크에 보존하는 필터 그래프의 렌더링 섹션을 생성 한다.

구문

HRESULT SetOutputFileName(
    const GUID *pType,
    LPCOLESTR lpwstrFile,
    IBaseFilter **ppf,
    IFileSinkFilter **pSink
);

파라미터

pType
[in] 미디어 서브 타입을 나타내는 GUID 에의 포인터. 현재 지원 되고 있는 유일한 출력 포맷은 AVI 이기 (위해)때문에, 이것은 &MEDIASUBTYPE_Avi 가 아니면 안된다.
lpwstrFile
[in] 출력 파일명이 저장 되고 있는 Unicode™ 캐릭터 라인에의 포인터.
ppf
[out] 멀티플렉서 필터에 상당하는 IBaseFilter 인터페이스에의 포인터의 주소. 이 메소드는 IBaseFilter 인터페이스의 참조 카운트를 인크리먼트(increment) 모아 두어 필터를 사용한 후는, 이 파라미터에 대해서 Release 메소드를 사용하는 것에 의해, 참조 카운트를 감소 할 필요가 있다.
pSink
[out] 필터 라이터에 상당하는 IFileSinkFilter 인터페이스에의 포인터의 주소. 이 메소드는 IFileSinkFilter 인터페이스의 참조 카운트를 인크리먼트(increment) 하기 위한(해), 필터를 사용한 후는, 이 파라미터에 대해서 Release 메소드를 사용하는 것에 의해, 참조 카운트를 감소 할 필요가 있다.

반환값

조작 상태를 나타내는 HRESULT 값을 돌려준다.
E_FAIL | 실패.
E_INVALIDARG | 무효인 인수. 지원 되고 있는 출력 포맷은 AVI (Audio-Video Interleaved) 뿐인다.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | Null 포인터 인수.
E_UNEXPECTED | 예기치 않은 에러가 발생했다.
NOERROR | 성공.
S_OK | AVI 멀티플렉서 필터의 인스턴스가 올바르고 생성 되었다.

주의

이 메소드는, 멀티플렉서와 파일 라이터를 필터 그래프에 삽입해,IFileSinkFilter::SetFileName 를 호출해 출력 파일명을 설정한다.

이 메소드로부터 돌려주어지는 ppf 파라미터를 RenderStream 의 호출로 pfRenderer 파라미터로서 사용할 수 있다.

이 메소드의 pSink 파라미터를 SetFileName 의 호출로 사용해,ICaptureGraphBuilder::SetOutputFileName 에 의해 설정된 파일명을 변경할 수 있다.


IDirectDrawFactory 인터페이스

주 : 이 인터페이스의 사용은 피하는 것. 새로운 어플리케이션으로 사용해서는 안 된다.

IDirectDrawFactory 인터페이스는, 확장 기능을 지원 하는 DirectDraw 오브젝트를 생성 및 열거하기 위해서 사용된다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDirectDrawFactory 메소드 | 설명
CreateDirectDraw | DirectDraw 오브젝트를 생성 해,IUnknown 인터페이스와 IDirectDraw 인터페이스에의 포인터를 취득한다.
DirectDrawEnumerate | 시스템에 인스톨 되고 있는 DirectDraw 표면을 열거한다.

IDirectDrawFactory::CreateDirectDraw

IDirectDrawFactory 인터페이스

DirectDraw 오브젝트를 생성 해, 그 IDirectDraw 인터페이스에의 포인터를 취득한다.

구문

STDMETHOD CreateDirectDraw(
    GUID *pGUID,
    HWND hWnd,
    DWORD dwCoopLevelFlags,
    DWORD dwReserved,
    IUnknown *pUnkOuter,
    IDirectDraw **ppDirectDraw
) PURE;

파라미터

pGUID
[out] 생성 하는 드라이버를 나타내는 글로벌 유니크 식별자 (GUID )에의 포인터. 액티브한 디스플레이 드라이버를 지정하려면 , NULL 를 설정한다. 또, 디버그를 위해서(때문에) 액티브한 디스플레이 드라이버의 동작을 제한하려면 , 다음의 플래그의 1 개를 건네준다.
DDCREATE_EMULATIONONLY | 모든 기능을 DirectDraw 오브젝트로 에뮤레이트 한다. 하드웨어가 지원 하는 기능은 이용하지 않는다.
DDCREATE_HARDWAREONLY | 하드웨어가 지원 하지 않는 기능을 DirectDraw 오브젝트로 에뮤레이트 하지 않는다. 지원되어 있지 않은 기능이 필요한 메소드를 호출하면, 실패해, DDERR_UNSUPPORTED (조작이 지원되어 있지 않다)가 돌려주어진다.
hWnd
[in] 어플리케이션의 윈도우 핸들.
dwCoopLevelFlags
[in] 어플리케이션의 최상정도 동작. 이하의 플래그를 1 개 이상 지정한다.
DDSCL_ALLOWMODEX | 모드 X 디스플레이 모드를 사용 가능하게 한다. 이 플래그는, DDSCL_EXCLUSIVE 플래그 및 DDSCL_FULLSCREEN 플래그와 함께 사용해야 한다.
DDSCL_ALLOWREBOOT | 어플리케이션이 풀 스크린 모드 또한 배타 모드 때에, 유저가 Ctrl + Alt + Del 키를 눌러 재기동할 수 있도록(듯이) 한다.
DDSCL_EXCLUSIVE | 배타 레벨을 요구한다. 이 플래그는, DDSCL_FULLSCREEN 플래그와 함께 사용해야 한다. 풀 스크린 또한 배타 협조 레벨에서는, 하드웨어를 최대한 이용할 수 있다. 이 모드에서는, 커스텀 팔레트나 동적 팔레트의 설정, 디스플레이 해상도의 변경, 메모리의 압축, 및 페이지후립핑의 실현을 할 수 있다. 배타 (풀 스크린) 모드에서는, 다른 어플리케이션으로부터, 표면을 할당할 수도 있고, DirectDraw 나 GDI 를 사용할 수도 있다. 다만, 배타 모드에서는, 그 때 배타 액세스를 가지고 있는 어플리케이션 이외의 어플리케이션으로부터, 디스플레이 모드나 팔레트를 변경할 수 없다.
DDSCL_FULLSCREEN | 배타 모드의 소유자가프라이머리 표면 전체를 제어하는 것을 나타낸다. 이 플래그는, DDSCL_EXCLUSIVE 플래그와 함께 사용해야 한다.
DDSCL_NORMAL | 어플리케이션이 보통의 Microsoft® Windows® 어플리케이션으로서 동작하는 것을 나타낸다. 이 플래그를 DDSCL_ALLOWMODEX, DDSCL_EXCLUSIVE, 또는 DDSCL_FULLSCREEN 플래그와 함께 사용할 수 없다.
DDSCL_NOWINDOWCHANGES | 어플리케이션이 액티브하게 되었을 때에, DirectDraw 가 어플리케이션 윈도우를 최소화 또는 복원할 수 없는 것을 나타낸다.
dwReserved
[in] 장래의 사용에 대비해 예약되고 있다. NULL 가 아니면 안된다.
pUnkOuter
[in] NULL 가 아니면 안된다. 장래의 COM 집약 기능과의 호환성을 위해서(때문에) 준비되어 있다. 현시점에서는, 이 파라미터가 NULL 가 아닌 경우,CreateDirectDraw 는 에러를 돌려준다.
ppDirectDraw
[out] IDirectDraw 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, DD_OK 를 돌려준다. 그 이외의 경우는, 다음의 몇개의 에러값을 돌려준다.

E_OUTOFMEMORY | 메모리 부족을 위해, DirectDraw 오브젝트를 생성 할 수 없다.
DDERR_GENERIC | 미정도리의 에러 상태이다.
DDERR_UNSUPPORTED | 처리가 DirectDraw 로 지원되어 있지 않다.
DDERR_DIRECTDRAWALREADYCREATED | 이 드라이버를 나타내는 DirectDrawEx 오브젝트가, 이 프로세스로 이미 생성 되고 있는 것을 나타낸다.
DDERR_INVALIDDIRECTDRAWGUID | 이 메소드에게 건네진 GUID 가, DirectDrawEx 드라이버의 유효한 식별자가 아니다.
DDERR_INVALIDPARAMS | 메소드에게 건네진 1 개 이상의 파라미터가 부정하다.
DDERR_NODIRECTDRAWHW | 하드웨어 전용 DirectDrawEx 오브젝트를 생성 할 수 없다. 드라이버는 하드웨어를 지원 하지 않는다.

주의

이 메소드는, DirectDraw 의 DirectDrawCreate 함수를 사용해 DirectDraw 오브젝트를 생성 하는 것과 같은 방법으로, DirectDraw 오브젝트를 생성 한다. 게다가IDirectDraw2::SetCooperativeLevel 메소드가 협조 레벨을 설정하는 것과 같은 방법으로, 협조 레벨을 설정한다. 다만,IDirectDrawFactory::CreateDirectDraw 메소드의 호출이 성공하면(자), DirectDraw 오브젝트가 생성 될 뿐만 아니라, DirectDraw 오브젝트가 공개하는 IUnknown 인터페이스와 IDirectDraw 인터페이스에의 포인터를 얻을 수 있다. 현재는, 어플리케이션으로부터 DirectDraw 오브젝트에 조회하는 것에 의해,IDirectDraw3 인터페이스에의 포인터의 주소를 취득할 수 있다.

IDirectDrawFactory::DirectDrawEnumerate

IDirectDrawFactory 인터페이스

시스템내의 이용 가능한 DirectDraw 호환 디바이스를 열거한다.

구문

STDMETHOD DirectDrawEnumerate(
    LPDDENUMCALLBACK lpCallback,
    LPVOID lpContext
) PURE;

파라미터

lpCallback
[in] 시스템내의 DirectDrawEx 로 유효한 하드웨어 추상 계층 (HAL) 각각의 기술로 불려 가는 DDEnumCallback 함수에의 포인터.
lpContext
[in] 함수를 호출할 때마다 콜백 함수에게 건네지는 어플리케이션 정의 구조체의 주소.

반환값

실패했을 경우는, DD_OK를 돌려준다. 그 이외의 경우는, DDERR_INVALIDPARAMS 를 돌려준다.

주의

이 메소드는, DirectX SDK 로 정의되고 있는 DirectDraw 의 DirectDrawEnumerate 함수를 닮은 역할을 한다.


IDirectDraw3 인터페이스

주 : 이 인터페이스의 사용은 피하는 것. 새로운 어플리케이션으로 사용해서는 안 된다.

IDirectDraw3 인터페이스는,IDirectDrawFactory::CreateDirectDraw 메소드를 통해서 DirectDraw 오브젝트를 생성 한 어플리케이션으로부터 이용할 수 있다. 이 메소드는,IDirectDraw 인터페이스에의 포인터의 주소를 취득한다. 어플리케이션에서는, 이것을 사용해 IDirectDraw3 인터페이스를 조회할 수가 있다.

IDirectDraw3 인터페이스는,IDirectDraw3::GetSurfaceFromDC 메소드를 추가해,IDirectDraw3::CreateSurface 메소드로 다른 동작을 제공하는 것으로써,IDirectDraw 인터페이스와 IDirectDraw2 인터페이스를 확장한 것이다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDirectDraw3 메소드 | 설명
CreateSurface | DirectDraw 오브젝트로부터 DirectDrawSurface 오브젝트를 생성 한다.
GetSurfaceFromDC | 디바이스 콘텍스트의 핸들로부터 IDirectDrawSurface 인터페이스에의 포인터를 취득한다.

IDirectDraw3::CreateSurface

IDirectDraw3 인터페이스

DirectDraw 오브젝트로부터 DirectDrawSurface 오브젝트를 생성 한다.

구문

STDMETHOD CreateSurface(
    LPDDSURFACEDESC lpDDSurfaceDesc,
    LPDIRECTDRAWSURFACE FAR *lplpDDSurface,
    IUnknown FAR *pUnkOuter
) PURE;

파라미터

lpDDSurfaceDesc
[in] 요구하는 표면을 기술하는 DDSURFACEDESC 구조체에의 포인터. 이 메소드를 호출하기 전에, 사용하지 않는 DDSURFACEDESC 멤버 모든 것을 0 으로 설정해야 한다. DDSCAPS 구조체는 DDSURFACEDESC 의 멤버이다.
lplpDDSurface
[out] 유효한 DirectDrawSurface 포인터로 초기화하는 포인터의 주소 (호출이 성공했을 경우).
pUnkOuter
[in] 안쪽의 오브젝트의 IUnknown 인터페이스와 집성 되는 외측의 오브젝트의 IUnknown 인터페이스에의 포인터.

반환값

성공했을 경우는, DD_OK 를 돌려준다. 그 이외의 경우는, 다음의 몇개의 에러값을 돌려준다.

DDERR_INCOMPATIBLEPRIMARY | 프라이머리 표면의 생성 요구가 기존의 프라이머리 표면과 일치하고 있지 않다.
DDERR_INVALIDCAPS | 콜백 함수에게 건네진 1 개 이상의 능력 비트가 부정하다.
DDERR_INVALIDOBJECT | DirectDraw 가 무효인 DirectDraw 오브젝트에의 포인터를 받았다.
DDERR_INVALIDPARAMS | 메소드에게 건네진 1 개 이상의 파라미터가 부정하다.
DDERR_INVALIDPIXELFORMAT | 지정된 픽셀 포맷이 무효이다.
DDERR_NOALPHAHW | 알파 가속화 하드웨어가 존재하지 않는지, 이용할 수 없기 때문에, 요구된 처리가 실패했다.
DDERR_NOCOOPERATIVELEVELSET | 표면의 생성전에 IDirectDraw2::SetCooperativeLevel 메소드가 불려 가지 않았다.
DDERR_NODIRECTDRAWHW | 하드웨어 전용 DirectDraw 오브젝트를 생성 할 수 없다. 드라이버는 하드웨어를 지원 하지 않는다.
DDERR_NOEMULATION | 소프트웨어 에뮬레이션을 이용할 수 없다.
DDERR_NOEXCLUSIVEMODE | 어플리케이션에 대해서 배타 모드가 요구되었지만, 어플리케이션에 배타 모드가 없다.
DDERR_NOFLIPHW | 표시되는 표면을 후립핑 할 수 없다.
DDERR_NOMIPMAPHW | 밉맵 텍스쳐를 매핑 하는 하드웨어가 존재하지 않는지, 이용할 수 없기 때문에, 처리를 실행할 수 없다.
DDERR_NOOVERLAYHW | 오버레이 하드웨어가 존재하지 않는지, 이용할 수 없기 때문에, 처리를 실행할 수 없다.
DDERR_NOZBUFFERHW | Z 버퍼에 대한 하드웨어 지원이 없기 때문에, 디스플레이 메모리에서의 Z 버퍼 생성, 혹은 Z 버퍼를 사용한소총탄을 실행할 수 없다.
DDERR_OUTOFMEMORY | DirectDraw 를 이용할 수 있는 메모리가 부족하기 때문에, 처리를 실행할 수 없다.
DDERR_OUTOFVIDEOMEMORY | DirectDraw 를 이용할 수 있는 디스플레이 메모리가 부족하기 때문에, 처리를 실행할 수 없다.
DDERR_PRIMARYSURFACEALREADYEXISTS | 어플리케이션은 이미 프라이머리 표면을 생성 하고 있다.
DDERR_UNSUPPORTEDMODE | 처리가 지원되어 있지 않다.

주의

pUnkOuter 파라미터에 NULL 를 건네주면(자),lplpDDSurface 파라미터에 DirectDraw 표면의 주소가 돌려주어진다. 또, 안쪽의 인터페이스와 집성 하는 외측의 인터페이스에의 포인터를 건네주면(자),lplpDDSurface 파라미터에 대응하는 IUnknown 포인터가 돌려주어진다.

현재의 DirectDrawEx 는,DDSCAPS 구조체의 dwcaps 멤버에 대응하는 DDSCAPS_DATAEXCHANGE 플래그도 제공한다. 이 플래그는, Ddrawex.h 에 DDSCAPS_SYSTEMMEMORY 와 DDSCAPS_VIDEOMEMORY 의 편성으로서 정의되고 있다. DDSCAPS_DATAEXCHANGE 플래그를 사용해 표면을 생성 했을 경우, 충분한 비디오 메모리를 이용할 수 없으면 표면이 자동적으로 비디오 메모리에 옮겨진다. 그 이외의 경우에는, 시스템 메모리 표면이 생성 된다. 또, 이 플래그를 DDSCAPS_OWNDC 플래그와 함께 설정 하면, 어플리케이션으로부터 IDirectDrawSurface::GetDC 메소드를 호출하는 것으로, 표면의 락을 보관 유지하지 않고 , 디바이스 콘텍스트를 불필요하게 될 때까지 잠글 수 있다.

이 메소드는,IDirectDraw::CreateSurface 메소드와 IDirectDraw2::CreateSurface 메소드를 호출한다.

IDirectDraw3::GetSurfaceFromDC

IDirectDraw3 인터페이스

디바이스 콘텍스트의 핸들로부터 IDirectDrawSurface 인터페이스에의 포인터를 취득한다.

구문

STDMETHOD GetSurfaceFromDC(
  HDC hdc,
  IDirectDrawSurface **ppSurface
  ) PURE;

파라미터

hdc
[in] 디바이스 콘텍스트 (DC)의 핸들.
ppSurface
[out] IDirectDrawSurface 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는, 다음의 몇개의 값을 돌려준다.

E_POINTER | IDirectDrawSurface 에의 포인터가 무효.
DDERR_NOTFOUND | 요구된 항목이 발견되지 않는다.


IDvdControl 인터페이스

주 : 이 인터페이스의 사용은 피하는 것. 기존의 어플리케이션과의 후방 호환성을 유지하기 (위해)때문에, 계속해 지원 되지만, 새로운 어플리케이션에서는 IDvdControl2 를 사용하는 것.

IDvdControl 인터페이스에서는, 1 개(살) 이상의 비디오 무비로부터 구성되는 DVD 타이틀의 재생과 서치의 메카니즘을 제어한다.

DVD 파일 시스템은, 생성자가 간단하게 커스터마이즈 할 수 없는 연속적인 트럭으로부터 구성되는 CD-ROM 등의 포맷과는 크게 다르다. DVD 포맷의 미디어 파일의 생성자는, 미디어 파일 자체가 갖추는 많은 원가요소와 제어 메카니즘을 이용해, 필요에 따라서 재생 순서를 변경할 수 있기 (위해)때문에, 트럭의 레이아웃과 네비게이션을 종래의 미디어보다 아득하게 정확하게 제어할 수 있다. 또, 시간 (시, 분, 초, 프레임) 또는 쳅터값을 기준으로 해 파일의 특정의 부분을 검색할 수 있다.

미디어 파일은 프로그램 체인 (PGC)의 리스트로부터 구성되어 있다. 개개의 프로그램 체인은 프로그램의 리스트로부터 구성되어 있어 개개의 프로그램은 셀의 리스트로부터 구성되어 있어 개개의 셀은 비디오 오브젝트 유니트 (VOBU)의 리스트로부터 구성되어 있어 개개의 비디오 오브젝트 유니트는 팩의 리스트로부터 구성되어 있어 개개의 팩은 실제의 MPEG 데이터로부터 구성되어 있다.

이 인터페이스는, DVD 의 재생에 대응하기 위해서 Microsoft® DirectShow® DVD 네비게이터에 의해 이행 된다.

이 인터페이스를 사용해, 재생을 제어하거나 (루트 드라이브의 설정, 재생, 정지 등), DVD-Video 파일의 재생시에 메뉴나 버튼 등, DVD 고유의 기능을 이용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDvdControl methods | 설명
TitlePlay | 지정된 타이틀 인덱스를 가지는 미디어 파일을 검색해, 그것을 재생한다.
ChapterPlay | 지정된 타이틀 인덱스와 쳅터값을 가지는 미디어 파일을 재생한다.
TimePlay | 지정된 타이틀 인덱스를 가지는 미디어 파일의 지정된 시간부터 재생을 시작 한다.
StopForResume | 재개 정보를 보존한 후, 재생을 DVD_DOMAIN_Stop 상태에 이행 시킨다.
GoUp | 현재의 미디어 파일의 재생을 정지해, 지정된 전의 프로그램 체인 (PGC)의 재생을 시작 한다.
TimeSearch | 현재의 쳅터의 재생을 정지해, 같은 미디어 파일의 지정된 시간부터 재생을 시작 한다.
ChapterSearch | 현재의 쳅터의 재생을 정지해, 같은 미디어 파일의 지정된 쳅터값으로부터 재생을 시작 한다.
PrevPGSearch | 현재의 프로그램의 재생을 정지해, 프로그램 체인 (PGC) 내의 앞의 프로그램으로부터 재생을 시작 한다.
TopPGSearch | 현재의 프로그램의 재생을 정지해, 프로그램 체인내의 현재의 프로그램의 재생을 다시 시작 한다.
NextPGSearch | 현재의 프로그램의 재생을 정지해, 프로그램 체인 (PGC) 내의 다음의 프로그램으로부터 재생을 시작 한다.
ForwardScan | 지정된 속도로 현재의 디스크를 순서 방향으로 서치 한다.
BackwardScan | 지정된 속도로 현재의 디스크를 역방향으로 서치 한다.
MenuCall | 지정된 메뉴를 화면상에 표시한다.
Resume | 메뉴를 사용한 타이틀의 재생하러 돌아온다.
UpperButtonSelect | 표시된 메뉴로부터 윗방향 버튼을 선택한다.
LowerButtonSelect | 표시된 메뉴로부터 아래방향 버튼을 선택한다.
LeftButtonSelect | 표시된 메뉴로부터 좌방향 버튼을 선택한다.
RightButtonSelect | 표시된 메뉴로부터 우측향버튼을 선택한다.
ButtonActivate | 선택되고 있는 버튼을 액티브하게 한다.
ButtonSelectAndActivate | 지정된 버튼을 선택해, 액티브하게 한다.
StillOff | 재생을 재개해, 정지 모드를 캔슬한다.
PauseOn | 현재의 미디어 파일의 재생을 포즈 한다.
PauseOff | 현재의 미디어 파일의 재생 포즈를 해제한다.
MenuLanguageSelect | 네비게이션 메뉴에 표시되는 언어를 설정한다.
AudioStreamChange | 현재의 오디오 스트림을 설정한다.
SubpictureStreamChange | 새로운 서브 픽쳐 스트림을 선택해, 그 표시를 유효 또는 무효로 한다.
AngleChange | 새로운 표시 앵글을 설정한다.
ParentalLevelSelect | 현재의 미디어 파일의 페어 렌탈 락 액세스 레벨을 설정한다.
ParentalCountrySelect | 페어 렌탈 락 액세스 레벨을 제어 하면나무의 기준이 되는 현재의 나라를 설정한다.
KaraokeAudioPresentationModeChange | 오디오 재생 모드를 가라오케로 설정한다.
VideoModePreferrence | 유저의 취향의 비디오 표시 모드를 설정한다.
SetRoot | DVD-Video 볼륨이 저장 되고 있는 루트 디렉토리를 설정한다.
MouseActivate | 마우스의 클릭에 응해 DVD 버튼을 선택해, 액티브하게 한다.
MouseSelect | 마우스의 이동에 응해 DVD 버튼을 선택한다.
ChapterPlayAutoStop | 지정된 타이틀내의 지정된 쳅터로부터 재생을 시작 해, 지정된 수의 쳅터를 재생한다.

IDvdControl::AngleChange

IDvdControl 인터페이스

새로운 표시 앵글을 설정한다.

구문

HRESULT AngleChange(
    ULONG ulAngle
);

파라미터

ulAngle
[in] 새로운 앵글의 값. 1 에서 9 의 사이가 아니면 안된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, DVD_DOMAIN_Title, 또는 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::AudioStreamChange

IDvdControl 인터페이스

현재의 오디오 스트림을 설정한다.

구문

HRESULT AudioStreamChange(
    ULONG nAudio
);

파라미터

nAudio
[in] 사용하는 오디오 트럭을 지정하는 값. 0 에서 7 의 사이가 아니면 안된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, DVD_DOMAIN_Title, 또는 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

AudioStreamChange 는 현재의 비디오 타이틀 세트 (VTS)를 대상으로 한다. 메뉴내로부터 이 메소드를 호출했을 경우는, 메뉴를 호출한 타이틀의 오디오 스트림이 설정된다.

IDvdControl::BackwardScan

IDvdControl 인터페이스

지정된 속도로 현재의 디스크를 역방향으로 서치 한다.

구문

HRESULT BackwardScan(
    double dwSpeed
);

파라미터

dwSpeed
[in] DirectShow 로 미디어 파일을 서치 하면나무의 속도를 지정하는 값. 이 값은, 생성 되었을 때의 속도를 1.0 으로 하는 승수이다. 따라서, 2.5 를 지정 하면, 생성 속도의 2.5 배의 속도로 역방향의 서치를 해 0.5 를 지정 하면 생성 속도의 반의 속도로 역방향의 서치를 한다. 실제의 재생 속도는, 비디오 디코더의 기능에 따라서 달라, 지정된 속도와 다른 일이 있다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::ButtonActivate

IDvdControl 인터페이스

선택되고 있는 버튼을 액티브하게 한다.

구문

HRESULT ButtonActivate(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

DVD 버튼을 "선택 " 해도, 버튼이 강조 표시되는 것만으로 "액티브 " 는 되지 않는다. 선택 하면은, Microsoft® Windows® 로 말하면,Tab 키로 버튼을 선택해,Space 키 또는 Enter 키를 누르지 않는 것과 같다. 액티브하다고는, Windows 의 경우에, 버튼을 (Tab 키로) 선택한 후에 Space 키 또는 Enter 키를 누르는 것과 같다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

참조

IDvdControl::ButtonSelectAndActivate

IDvdControl::ButtonSelectAndActivate

IDvdControl 인터페이스

지정된 버튼을 선택해, 액티브하게 한다.

구문

HRESULT ButtonSelectAndActivate(
    ULONG uiButton
);

파라미터

uiButton
[in] 선택해, 액티브하게 하는 버튼을 지정하는 값. 1 에서 36 의 사이가 아니면 안된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

전자적인 리모트 콘트롤 디바이스는, 보통, DVD 재생장치의 다양한 기능을 액티브하게하기 위한 수많은 버튼을 갖추고 있다. 이 메소드는, 보통, 유저가 컨트롤 디바이스의 버튼을 클릭했을 때에 불려 간다. 이 메소드가 불려 가면(자), DirectShow 는, 예를 들어, 소리를 울리거나 화면을 변경하거나 하는 것에 의해 버튼이 선택된 것을 나타내, 선택되고 있는 버튼에 대응하는 ButtonActivate 등의 메소드를 호출한다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::ChapterPlay

IDvdControl 인터페이스

지정된 타이틀 인덱스와 쳅터값을 가지는 미디어 파일을 재생한다.

구문

HRESULT ChapterPlay(
    ULONG uiTitle,
    ULONG uiChapter
);

파라미터

uiTitle
[in] DirectShow 가 재생하는 타이틀 번호를 지정하는 값. 1 에서 99 의 사이가 아니면 안된다.
uiChapter
[in] 지정된 타이틀내의 DirectShow 가 재생을 시작 하는 쳅터를 지정하는 값. 1 에서 999 의 사이가 아니면 안된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, DVD_DOMAIN_Title, 또는 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::ChapterPlayAutoStop

IDvdControl 인터페이스

지정된 타이틀내의 지정된 쳅터로부터 재생을 시작 해, 지정된 수의 쳅터를 재생하도록(듯이) DVD 플레이어에게 지시한다.

구문

HRESULT ChapterPlayAutoStop(
    ULONG ulTitle,
    ULONG ulChapter,
    ULONG ulChaptersToPlay
);

파라미터

ulTitle
[in] 재생하는 타이틀 번호.
ulChapter
[in] 재생을 시작 하는 쳅터 번호.
ulChaptersToPlay
[in] 시작 쳅터로부터 재생하는 쳅터의 수.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

쳅터는 1 에서 999 의 범위이다. 상세한 것에 대하여는 「EC_DVD_CHAPTER_AUTOSTOP 」를 참조할것.

IDvdControl::ChapterSearch

IDvdControl 인터페이스

현재의 쳅터의 재생을 정지해, 같은 타이틀내의 지정된 쳅터로부터 재생을 시작 한다.

구문

HRESULT ChapterSearch(
    ULONG Chapter
);

파라미터

Chapter
재생의 시작 위치를 지정하는 쳅터값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::ForwardScan

IDvdControl 인터페이스

지정된 속도로 현재의 디스크를 순서 방향으로 서치 한다.

구문

HRESULT ForwardScan(
    double dwSpeed
);

파라미터

dwSpeed
[in] DirectShow 로 미디어 파일을 서치 하면나무의 속도를 지정하는 값. 이 값은, 생성 되었을 때의 속도를 1.0 으로 하는 승수이다. 따라서, 2.5 를 지정 하면, 생성 속도의 2.5 배의 속도로 순서 방향의 서치를 해 0.5 를 지정 하면 생성 속도의 반의 속도로 순서 방향의 서치를 한다. 실제의 재생 속도는, 비디오 디코더의 기능에 따라서 달라, 지정된 속도와 다른 일이 있다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::GoUp

IDvdControl 인터페이스

현재의 미디어 파일의 재생을 정지해, 지정된 전의 프로그램 체인 (PGC)의 재생을 시작 한다.

구문

HRESULT GoUp(void);

반환값

HRESULT 값을 돌려준다.

주의

개개의 PGC 는 생성시에 전의 PGC 에 관련지을 수 있다. 이 메소드는, 관련지을 수 있었던 전의 PGC 를 새로운 재생 파일로서 설정한다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::KaraokeAudioPresentationModeChange

IDvdControl 인터페이스

오디오 재생 모드를 가라오케로 설정한다.

구문

HRESULT KaraokeAudioPresentationModeChange(
    ULONG ulMode
);

파라미터

ulMode
[in] 요구되고 있는 오디오 재생 모드.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

현재, 가라오케의 지원은 이행되어 있지 않다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, DVD_DOMAIN_Title, 또는 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::LeftButtonSelect

IDvdControl 인터페이스

표시된 메뉴로부터 좌방향 버튼을 선택한다.

구문

HRESULT LeftButtonSelect(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

많은 경우, 물리적 또는 전자적인 리모트 콘트롤 디바이스에는, 메뉴의 선택 등, 특정의 종류의 조작에 사용되는 4 개의 방향 버튼이 부속되어 있다. 이 메소드는, 무엇인가 (많은 경우는 유저)에 의해, 좌방향 버튼이 방아쇠 된 것을 DirectShow 에 알린다.

DVD 버튼을 "선택 " 해도, 버튼이 강조 표시되는 것만으로 "액티브 " 는 되지 않는다. 선택 하면은, Windows 로 말하면,Tab 키로 버튼을 선택해,Space 키 또는 Enter 키를 누르지 않는 것과 같다. 액티브하다고는, Windows 의 경우에, 버튼을 (Tab 키로) 선택한 후에 Space 키 또는 Enter 키를 누르는 것과 같다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::LowerButtonSelect

IDvdControl 인터페이스

표시된 메뉴로부터 아래방향 버튼을 선택한다.

구문

HRESULT LowerButtonSelect(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

많은 경우, 물리적 또는 전자적인 리모트 콘트롤 디바이스에는, 메뉴의 선택 등, 특정의 종류의 조작에 사용되는 4 개의 방향 버튼이 부속되어 있다. 이 메소드는, 무엇인가 (많은 경우는 유저)에 의해, 아래방향 버튼이 방아쇠 된 것을 DirectShow 에 알린다.

DVD 버튼을 "선택 " 해도, 버튼이 강조 표시되는 것만으로 "액티브 " 는 되지 않는다. 선택 하면은, Windows 로 말하면,Tab 키로 버튼을 선택해,Space 키 또는 Enter 키를 누르지 않는 것과 같다. 액티브하다고는, Windows 의 경우에, 버튼을 (Tab 키로) 선택한 후에 Space 키 또는 Enter 키를 누르는 것과 같다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::MenuCall

IDvdControl 인터페이스

지정된 메뉴를 화면상에 표시한다.

구문

HRESULT MenuCall(
    DVD_MENU_ID MenuID
);

파라미터

MenuID
[in] 표시하는 메뉴를 지정하는 값. DVD_MENU_ID 열거형의 멤버이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, DVD_DOMAIN_Title, 또는 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::MenuLanguageSelect

IDvdControl 인터페이스

네비게이션 메뉴에 표시되는 언어를 설정한다.

구문

HRESULT MenuLanguageSelect(
    LCID LanguageCode
);

파라미터

LanguageCode
새로운 언어를 지정하는 값.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 메뉴의 디폴트의 언어를 선택한다.

이 메소드는, 도메인이 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

어플리케이션은 표준 Windows LCID 를 사용해 언어를 지정한다.

IDvdControl::MouseActivate

IDvdControl 인터페이스

마우스의 클릭에 응해 DVD 버튼을 선택해, 액티브하게 한다.

구문

HRESULT MouseActivate(
    POINT point );

파라미터

point
[in] 표시 윈도우내의 지정된 위치.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 표시 윈도우내의 지정된 위치가 현재의 DVD 버튼의 네모진 강조 표시 영역내에 있을지 어떨지를 확인한다. 지정된 위치가 강조 표시 영역내에 있는 경우, 이 메소드는 그 버튼을 선택해, 액티브하게 한다.

DVD 버튼안에는, 강조 표시 영역이 없는 것도 있다. 버튼의 강조 표시 영역 끼리는 겹치는 일이 있어, 강조 표시 영역이 DVD 버튼의 외관과 일치하지 않는 것도 있다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::MouseSelect

IDvdControl 인터페이스

마우스의 이동에 응해 DVD 버튼을 선택한다.

구문

HRESULT MouseSelect(
    POINT point );

파라미터

point
[in] 표시 윈도우내의 지정된 위치.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

이 메소드는, 표시 윈도우내의 지정된 위치가 현재의 DVD 버튼의 네모진 강조 표시 영역내에 있을지 어떨지를 확인한다. 지정된 위치가 강조 표시 영역내에 있는 경우, 이 메소드는 그 버튼을 선택해, 액티브하게 한다.

DVD 버튼안에는, 강조 표시 영역이 없는 것도 있다. 버튼의 강조 표시 영역 끼리는 겹치는 일이 있어, 강조 표시 영역이 DVD 버튼의 외관과 일치하지 않는 것도 있다.

IDvdControl::NextPGSearch

IDvdControl 인터페이스

현재의 프로그램의 재생을 정지해, 프로그램 체인 (PGC) 내의 다음의 프로그램으로부터 재생을 시작 한다.

구문

HRESULT NextPGSearch(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

보통, 1 개의 프로그램은 1 개의 쳅터에 상당해, 1 개의 PGC 는 1 개의 타이틀에 상당한다. One_Sequential_PGC_Title 의 경우, 각 프로그램은 1 개의 쳅터에 상당할 필요가 있어, 각 타이틀에는 PGC 가 1 개만 포함되지만, 그 이외의 경우, 특히 랜덤/상훌 PGC 및 페어 렌탈 블록의 경우는, 쳅터간에 복수의 프로그램을 포함하거나 1 개의 타이틀에 복수의 PGC 를 포함할 수가 있다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::ParentalCountrySelect

IDvdControl 인터페이스

페어 렌탈 락 액세스 레벨을 제어 하면나무의 기준이 되는 현재의 나라를 설정한다.

구문

HRESULT ParentalCountrySelect(
    WORD wCountry
);

파라미터

wCountry
[in] ISO3166 로 정의되고 있는 Alpha-2 Code 에 따라 현재의 나라를 지정하는 값. 「주의」를 참조할것.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

wCountry 파라미터의 ISO3166 의 2 문자국 코드는, 이 메소드에 WORD 로서 건네줄 필요가 있다. 이하의 코드는, 미국 (US)의 경우의 변환의 예를 나타내고 있다.

WORD wCountry  =  ( WORD( 'U' ) << 8 ) | 'S';

참조

IDVDControl::ParentalLevelSelect

IDvdControl::ParentalLevelSelect

IDvdControl 인터페이스

현재의 미디어 파일의 페어 렌탈 락 액세스 레벨을 설정한다.

구문

HRESULT ParentalLevelSelect(
    ULONG ulParentalLevel
);

파라미터

ulParentalLevel
현재의 미디어 파일의 페어 렌탈 락 액세스 레벨을 지정하는 값. 1 이상, 8 이하의 값이 아니면 안된다. 이하는 정의 끝난 페어 렌탈 락 레벨이다.
1 | 등급은 일반용의 G 이다.
3 | 등급은 보호자의 지도가 바람직한 PG 이다.
4 | 등급은 보호자의 지도가 바람직하고, 13 세 미만의 아이에게는 추천 할 수 없는 PG-13 이다.
6 | 등급은 제한부의 R 이다.
7 | 등급은 NC-17 이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

이 메소드는, 현재의 유저의 액세스 레벨을 설정한다. 액세스 레벨에 의해, 유저가 재생할 수 있는 미디어 파일이 정해진다. 높은 레벨은 낮은 레벨의 컨텐츠를 재생할 수 있지만, 낮은 레벨은 높은 레벨의 컨텐츠를 재생할 수 없다. 예를 들어, 성인은 어린이용의 컨텐츠를 볼 수가 있지만, 아이는 성인전용의 컨텐츠를 볼 수 없다.

DVD 네비게이터 필터에는, 페어 렌탈 락 레벨의 설정을 제한하는 기능은 없다. DVD 플레이어 어플리케이션에서는, 현재의 페어 렌탈 락 레벨을 올리는 조작을 패스워드에 의해 보호하는 등, 페어 렌탈 락 레벨의 설정을 강제적으로 제한할 수가 있다. DVD 네비게이터의 디폴트의 설정에서는, 페어 렌탈 락이 무효가 되어 있다.

페어 렌탈 락을 무효로 하려면 ,ulParentalLevel 로서 0xffffffff 를 건네준다. 페어 렌탈 락이 무효가 되어 있으면, 플레이어는, 페어 렌탈 ID 에 관계없이, 페어 렌탈 블록내의 최초의 프로그램 체인 (PGC)을 재생한다.

참조

IDVDControl::ParentalCountrySelect

IDvdControl::PauseOff

IDvdControl 인터페이스

포즈 후, 현재의 미디어 파일의 재생을 재개한다.

구문

HRESULT PauseOff(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

미디어 파일의 재생이 포즈로 되어 있지 않은 경우, 이 메소드는 아무것도 하지 않는다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

참조

IDvdControl::PauseOn

IDvdControl::PauseOn

IDvdControl 인터페이스

현재의 미디어 파일의 재생을 포즈 한다.

구문

HRESULT PauseOn(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

IMediaControl::Pause 와 같게, 이 메소드는 재생과 모든 내부 타이머를 정지시킨다. 미디어 파일이 동작하고 있지 않는 경우, 이 메소드는 아무것도 하지 않는다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

참조

IDvdControl::PauseOff

IDvdControl::PrevPGSearch

IDvdControl 인터페이스

현재의 프로그램의 재생을 정지해, 프로그램 체인 (PGC) 내의 앞의 프로그램으로부터 재생을 시작 한다.

구문

HRESULT PrevPGSearch(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

보통, 1 개의 프로그램은 1 개의 쳅터에 상당해, 1 개의 PGC 는 1 개의 타이틀에 상당한다. One_Sequential_PGC_Title 의 경우, 각 프로그램은 1 개의 쳅터에 상당할 필요가 있어, 각 타이틀에는 PGC 가 1 개만 포함되지만, 그 이외의 경우, 특히 랜덤/상훌 PGC 및 페어 렌탈 블록의 경우는, 쳅터간에 복수의 프로그램을 포함하거나 1 개의 타이틀에 복수의 PGC 를 포함할 수가 있다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::Resume

IDvdControl 인터페이스

메뉴를 사용한 타이틀의 재생하러 돌아온다.

구문

HRESULT Resume(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

파일의 재생이 정지하고 있는 경우, 또는 파일이 이미 동작하고 있는 경우, 이 메소드는 아무것도 하지 않는다.

이 메소드는, 동작을 DVD_DOMAIN_Title 의 타이틀 재생에 되돌린다. 보통, 어플리케이션은, DVD 네비게이터를 DVD_DOMAIN_VideoTitleSetMenu 또는 DVD_DOMAIN_VideoManagerMenu 에 이행 시키는 MenuCall 를 호출한 다음에 이 메소드를 호출한다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu 또는 DVD_DOMAIN_VideoTitleSetMenu 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::RightButtonSelect

IDvdControl 인터페이스

표시된 메뉴로부터 우측향버튼을 선택한다.

구문

HRESULT RightButtonSelect(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

많은 경우, 물리적 또는 전자적인 리모트 콘트롤 디바이스에는, 메뉴의 선택 등, 특정의 종류의 조작에 사용되는 4 개의 방향 버튼이 부속되어 있다. 이 메소드는, 무엇인가 (많은 경우는 유저)에 의해, 우측향버튼이 방아쇠 된 것을 DirectShow 에 알린다.

DVD 버튼을 "선택 " 해도, 버튼이 강조 표시되는 것만으로 "액티브 " 는 되지 않는다. 선택 하면은, Windows 로 말하면,Tab 키로 버튼을 선택해,Space 키 또는 Enter 키를 누르지 않는 것과 같다. 액티브하다고는, Windows 의 경우에, 버튼을 (Tab 키로) 선택한 후에 Space 키 또는 Enter 키를 누르는 것과 같다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::SetRoot

IDvdControl 인터페이스

DVD-Video 볼륨이 저장 되고 있는 루트 디렉토리를 설정한다.

구문

HRESULT SetRoot(
    LPCWSTR pszPath
);

파라미터

pszPath
[in] 루트 디렉토리로서 설정하는 디렉토리명에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_POINTER | NULL 포인터 인수.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::TitlePlay 를 호출하기 전에 루트 디렉토리를 설정하지 않았던 경우는, 최상정도 레벨의 디렉토리에 VIDEO_TS 디렉토리가 포함되어 있는 C: 이후의 최초의 드라이브가 루트로서 사용된다.

IDvdControl::StillOff

IDvdControl 인터페이스

재생을 재개해, 정지 모드를 캔슬한다.

구문

HRESULT StillOff(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

표시 화면이 정지화면 보관 유지 모드로 되어 있지 않은 경우, 이 메소드는 아무것도 하지 않는다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::StopForResume

IDvdControl 인터페이스

재개 정보를 보존한 후, 재생을 DVD_DOMAIN_Stop 상태에 이행 시킨다.

구문

HRESULT StopForResume(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

재생되고 있는 파일 또는 포즈 하고 있는 파일이 없는 경우, 이 메소드는 아무것도 하지 않는다.

DVD 네비게이터 필터는 정지상태태로 이행하지만, 필터의 그래프는 DirectShow 실행 상태에 머무른다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::SubpictureStreamChange

IDvdControl 인터페이스

새로운 서브 픽쳐 스트림을 선택해, 그 표시를 유효 또는 무효로 한다.

구문

HRESULT SubpictureStreamChange(
    ULONG nSubPicture,
    BOOL bDisplay
);

파라미터

nSubPicture
서브 픽쳐의 소스를 지정하는 값. 0 에서 32 의 사이 또는 63 이 아니면 안된다.
0-31 | 스트림이 유효한 것을 나타낸다.
32 | 현재의 스트림을 변경하지 않고 표시를 온, 오프 할 수 있다. 즉, 현재의 스트림을 변경하지 않고 로 bDisplay 를 변경할 수 있다.
63 | 스트림이 더미 스트림인 것을 나타낸다.
bDisplay
서브 픽쳐가 유효한지 어떤지를 지정하는 값. TRUE 로 설정 하면, 서브 픽쳐가 표시되어 FALSE 로 설정 하면 서브 픽쳐가 표시되지 않는다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, DVD_DOMAIN_Title, 또는 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::TimePlay

IDvdControl 인터페이스

지정된 타이틀 인덱스를 가지는 미디어 파일의 지정된 시간부터 재생을 시작 한다.

구문

HRESULT TimePlay(
    ULONG uiTitle,
    ULONG bcdTime
);

파라미터

uiTitle
DirectShow 로 재생하는 타이틀 번호를 지정하는 값. 이 값은 1 에서 99 의 사이가 아니면 안된다.
bcdTime
DirectShow 가 재생을 시작 하는 DVD_TIMECODE 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, DVD_DOMAIN_Title, 또는 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::TimeSearch

IDvdControl 인터페이스

현재의 쳅터의 재생을 정지해, 같은 미디어 파일의 지정된 시간부터 재생을 시작 한다.

구문

HRESULT TimeSearch(
    ULONG bcdTime
);

파라미터

bcdTime
DirectShow 가 재생을 시작 하는 DVD_TIMECODE 구조체에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::TitlePlay

IDvdControl 인터페이스

지정된 타이틀 인덱스를 가지는 미디어 파일을 검색해, 그것을 재생한다.

구문

HRESULT TitlePlay(
    ULONG uiTitle
);

파라미터

uiTitle
DirectShow 로 재생하는 타이틀 번호를 지정하는 값. 이 값은 1 에서 99 의 사이가 아니면 안된다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, DVD_DOMAIN_Title, 또는 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::TopPGSearch

IDvdControl 인터페이스

현재의 프로그램의 재생을 정지해, 프로그램 체인 (PGC) 내의 현재의 프로그램의 재생을 다시 시작 한다.

구문

HRESULT TopPGSearch(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_UNEXPECTED | DVD 가 초기화되어 있지 않다.
S_OK | 성공.

주의

보통, 1 개의 프로그램은 1 개의 쳅터에 상당해, 1 개의 PGC 는 1 개의 타이틀에 상당한다. One_Sequential_PGC_Title 의 경우, 각 프로그램은 1 개의 쳅터에 상당할 필요가 있어, 각 타이틀에는 PGC 가 1 개만 포함되지만, 그 이외의 경우, 특히 랜덤/상훌 PGC 및 페어 렌탈 블록의 경우는, 쳅터간에 복수의 프로그램을 포함하거나 1 개의 타이틀에 복수의 PGC 를 포함할 수가 있다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::UpperButtonSelect

IDvdControl 인터페이스

표시된 메뉴로부터 윗방향 버튼을 선택한다.

구문

HRESULT UpperButtonSelect(void);

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK | 성공.

주의

많은 경우, 물리적 또는 전자적인 리모트 콘트롤 디바이스에는, 메뉴의 선택 등, 특정의 종류의 조작에 사용되는 4 개의 방향 버튼이 부속되어 있다. 이 메소드는, 무엇인가 (많은 경우는 유저)에 의해, 윗방향 버튼이 방아쇠 된 것을 DirectShow 에 알린다.

DVD 버튼을 "선택 " 해도, 버튼이 강조 표시되는 것만으로 "액티브 " 는 되지 않는다. 선택 하면은, Windows 로 말하면,Tab 키로 버튼을 선택해,Space 키 또는 Enter 키를 누르지 않는 것과 같다. 액티브하다고는, Windows 의 경우에, 버튼을 (Tab 키로) 선택한 후에 Space 키 또는 Enter 키를 누르는 것과 같다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdControl::VideoModePreferrence

IDvdControl 인터페이스

유저의 취향의 비디오 표시 모드를 설정한다.

구문

HRESULT VideoModePreferrence(
    ULONG ulPreferredDisplayMode
);

파라미터

ulPreferredDisplayMode
[in] DVD 컨텐츠의 새로운 표시 모드를 지정하는 값. DVD_PREFERRED_DISPLAY_MODE 열거형의 멤버이다.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
S_OK | 성공.

주의

이 메소드는, 디폴트의 비디오 윈도우의 어스펙트비(가로세로 비율)을 변경한다. 이 메소드에 의해 디폴트의 어스펙트비(가로세로 비율) 변환 메카니즘을 지정할 수도 있다.

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, DVD_DOMAIN_Title, 또는 DVD_DOMAIN_Stop 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.


IDvdInfo 인터페이스

주 : 이 인터페이스의 사용은 피하는 것. 기존의 어플리케이션과의 후방 호환성을 유지하기 (위해)때문에, 계속해 지원 되지만, 새로운 어플리케이션에서는 IDvdInfo2 인터페이스를 사용하는 것.

어플리케이션은 IDvdInfo 인터페이스를 사용해, 이용 가능한 DVD 타이틀의 속성 및 DVD 플레이어 상태를 문의할 수가 있다. 또, DVD 의 사양의 Annex J 의 범위를 넘어 DVD 플레이어를 제어할 수도 있다.

이 인터페이스를 이행 하지 않는 것. 이 인터페이스는 Microsoft® DirectShow® 가 자동적으로 이행 한다.

어플리케이션으로 이 인터페이스를 사용해, DVD-Video 또는 DVD 플레이어 필터 그래프의 현재 상태에 관한 상세 정보를 취득한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDvdInfo 메소드 | 설명
GetCurrentDomain | DVD 플레이어의 현재의 DVD 도메인을 취득한다.
GetCurrentLocation | 현재의 재생 위치를 취득한다.
GetTotalTitleTime | 현재의 타이틀의 총재생 시간을 취득한다.
GetCurrentButton | 이용 가능한 버튼의 수와 현재 선택되고 있는 버튼 번호를 취득한다.
GetCurrentAngle | 이용 가능한 앵글의 수와 현재 선택되고 있는 앵글 번호를 취득한다.
GetCurrentAudio | 이용 가능한 오디오 스트림의 수와 현재 선택되고 있는 오디오 스트림의 번호를 취득한다.
GetCurrentSubpicture | 이용 가능한 서브 픽쳐 스트림의 수, 현재 선택되고 있는 서브 픽쳐 스트림 번호, 및 서브 픽쳐의 표시가 무효가 되어 있는지 어떤지를 나타내는 값을 취득한다.
GetCurrentUOPS | 유효한 IDvdControl 메소드를 취득한다.
GetAllSPRMs | 모든 시스템 파라미터 레지스터 (SPRM)의 현재의 내용을 취득한다.
GetAllGPRMs | 모든 범용 파라미터 레지스터 (GPRM)의 현재의 내용을 취득한다.
GetAudioLanguage | 현재의 타이틀내의 지정된 오디오 스트림의 언어를 취득한다.
GetSubpictureLanguage | 현재의 타이틀내의 지정된 서브 픽쳐 스트림의 언어를 취득한다.
GetTitleAttributes | 메뉴를 포함한 지정된 타이틀의 모든 비디오 스트림, 오디오 스트림, 및 서브 픽쳐 스트림의 속성을 취득한다.
GetVMGAttributes | 비디오 매니저 (VMG) 메뉴의 모든 비디오 스트림, 오디오 스트림, 및 서브 픽쳐 스트림의 속성을 취득한다.
GetCurrentVideoAttributes | 현재의 타이틀 또는 메뉴의 현재의 비디오 속성을 취득한다.
GetCurrentAudioAttributes | 현재의 타이틀 또는 메뉴의 현재의 오디오 스트림의 속성을 취득한다.
GetCurrentSubpictureAttributes | 현재의 타이틀 또는 메뉴의 현재의 서브 픽쳐 스트림의 속성을 취득한다.
GetCurrentVolumeInfo | 현재의 DVD 볼륨 정보를 취득한다.
GetDVDTextInfo | 다양한 언어의 타이틀명, 볼륨명, 프로듀서명, 가수명등의 설명 텍스트가 저장 되는 TXTDT_MG 구조체를 취득한다.
GetPlayerParentalLevel | DVD 플레이어의 현재의 페어 렌탈 락 레벨과 나라 코드의 설정을 취득한다.
GetNumberOfChapters | 특정의 타이틀에 대해서 정의되고 있는 쳅터의 수를 취득한다.
GetTitleParentalLevels | 특정의 타이틀에 대해서 정의되고 있는 페어 렌탈 락 레벨을 취득한다.
GetRoot | 플레이어로 설정되어 있는 루트 디렉토리를 취득한다.

IDvdInfo::GetAllGPRMs

IDvdInfo 인터페이스

모든 범용 파라미터 레지스터 (GPRM)의 현재의 내용을 취득한다.

구문

HRESULT GetAllGPRMs(
    GPRMARRAY *pRegisterArray
    );

파라미터

pRegisterArray
[out] 취득된 범용 파라미터 레지스터의 배열에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

GPRM 는 각 타이틀에 고유의 용도로 사용된다. GPRM 는 범용 파라미터 레지스터이다. GPRM 에 대해서는, DVD 의 사양을 참조할것.

IDvdInfo::GetAllSPRMs

IDvdInfo 인터페이스

모든 시스템 파라미터 레지스터 (SPRM)의 현재의 내용을 취득한다.

구문

HRESULT GetAllSPRMs(
    SPRMARRAY *pRegisterArray
    );

파라미터

pRegisterArray
[out] 취득된 시스템 파라미터 레지스터의 배열에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

개개의 레지스터의 사용법에 대해서는, 「DVD 비디오의 사양」을 참조할것.

IDvdInfo::GetAudioLanguage

IDvdInfo 인터페이스

현재의 타이틀내의 지정된 오디오 스트림의 언어를 취득한다.

구문

HRESULT GetAudioLanguage(
    ULONG nStream,
    LCID *pLanguage
    );

파라미터

nStream
[in] 스트림 번호.
pLanguage
[out] 취득된 언어에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 도메인이 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

이 메소드는 메뉴의 언어는 돌려주지 않는다. 스트림에 언어가 포함되지 않은 경우, 이 메소드는,pLanguage 가 가리키는 값을 제로로 설정한다. pLanguage 로부터 읽어내 가능한 캐릭터 라인명을 생성 하려면 , 다음과 같이 Win32 GetLocaleInfo 함수를 호출한다. LOCALE_SENGLANGUAGE 는 로케일 정보형이며, pszString 는 요구된 데이터를 받는 버퍼에의 포인터이며, cbSize 는 pszString 의 사이즈를 지정한다.

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

IDvdInfo::GetCurrentAngle

IDvdInfo 인터페이스

이용 가능한 앵글의 수와 현재 선택되고 있는 앵글 번호를 취득한다.

구문

HRESULT GetCurrentAngle(
    ULONG *pnAnglesAvailable,
    ULONG *pnCurrentAngle
    );

파라미터

pnAnglesAvailable
[out] 취득된 이용 가능한 앵글의 수에의 포인터. 가리키고 있는 값이 1 인 경우, 현재의 비디오에는 복수의 앵글이 포함되지 않았다.
pnCurrentAngle
[out] 취득된 현재의 앵글 번호에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

앵글과는, 거듭해 기록되고 있는 비디오 스트림으로, 그 중에는, 다른 카메라 앵글로부터 촬영된 같은 장면이 수록되고 있다.

이 메소드는, 도메인이 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetCurrentAudio

IDvdInfo 인터페이스

이용 가능한 오디오 스트림의 수와 현재 선택되고 있는 오디오 스트림의 번호를 취득한다.

구문

HRESULT GetCurrentAudio(
    ULONG *pnStreamsAvailable,
    ULONG *pnCurrentStream
    );

파라미터

pnStreamsAvailable
[out] 취득된 이용 가능한 오디오 스트림의 수에의 포인터.
pnCurrentStream
[out] 현재의 스트림 번호에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 도메인이 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetCurrentAudioAttributes

IDvdInfo 인터페이스

현재의 타이틀 또는 메뉴의 현재의 오디오 스트림의 속성을 취득한다.

구문

HRESULT GetCurrentAudioAttributes(
    DVD_AudioATR *pATR
    );

파라미터

pATR
[out] 취득된 오디오 속성에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

DVD_AudioATR 데이터형에 대해서는, 「DVD-Video 사양」을 참조할것.

IDvdInfo::GetCurrentButton

IDvdInfo 인터페이스

이용 가능한 버튼의 수와 현재 선택되고 있는 버튼 번호를 취득한다.

구문

HRESULT GetCurrentButton(
    ULONG *pnButtonsAvailable,
    ULONG *pnCurrentButton
    );

파라미터

pnButtonsAvailable
[out] 이용 가능한 버튼의 수에의 포인터.
pnCurrentButton
[out] 현재의 버튼 번호에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

버튼이 없는 경우, 이 메소드는 pnButtonsAvailable 와 pnCurrentButton 의 양쪽 모두를 제로로 해 돌려준다.

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetCurrentDomain

IDvdInfo 인터페이스

DVD 플레이어의 현재의 DVD 도메인을 취득한다.

구문

HRESULT GetCurrentDomain(
    DVD_DOMAIN *pDomain
    );

파라미터

pDomain
[out] DVD_DOMAIN 열거형의 멤버인 현재의 도메인에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetCurrentLocation

IDvdInfo 인터페이스

현재의 재생 위치를 취득한다.

구문

HRESULT GetCurrentLocation(
    DVD_PLAYBACK_LOCATION *pLocation
    );

파라미터

pLocation
[out] DVD_PLAYBACK_LOCATION 구조 체내의 취득된 재생 위치 정보에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

이 메소드의 디폴트의 이행은, 현재의 도메인이 DVD_DOMAIN_Title 가 아닌 경우, E_UNEXPECTED 를 돌려준다.

주의

이 메소드는, 현재의 위치의 시크를 명시적으로 금지하고 있지 않는 타이틀의 현재의 재생 위치로부터 비디오의 재생을 재개하는데 충분한 정보를 취득한다.

이 메소드는, 도메인이 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetCurrentSubpicture

IDvdInfo 인터페이스

이용 가능한 서브 픽쳐 스트림의 수, 현재 선택되고 있는 서브 픽쳐 스트림 번호, 및 서브 픽쳐의 표시가 무효가 되어 있는지 어떤지를 나타내는 값을 취득한다.

구문

HRESULT GetCurrentSubpicture(
    ULONG *pnStreamsAvailable,
    ULONG *pnCurrentStream,
    BOOL *pIsDisabled
    );

파라미터

pnStreamsAvailable
[out] 취득된 이용 가능한 서브 픽쳐 스트림의 수에의 포인터.
pnCurrentStream
[out] 취득된 현재 선택되고 있는 서브 픽쳐 스트림 번호에의 포인터.
pIsDisabled
[out] 서브 픽쳐의 표시가 무효가 되어 있는지 어떤지를 나타내는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

강제적으로 액티브하게 하는 스트림으로서 생성 된 서브 픽쳐 스트림은, 어플리케이션이 IDvdControl::SubpictureStreamChange 메소드로 서브 픽쳐의 표시를 무효로 하고 있어도 표시된다.

이 메소드는, 도메인이 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetCurrentSubpictureAttributes

IDvdInfo 인터페이스

현재의 타이틀 또는 메뉴의 현재의 서브 픽쳐 스트림의 속성을 취득한다.

구문

HRESULT GetCurrentSubpictureAttributes(
    DVD_SubpictureATR *pATR
    );

파라미터

pATR
[out] 취득된 서브 픽쳐 속성에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_FAIL | 지정된 서브 픽쳐가 속성을 가지고 있지 않다.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

DVD_SubpictureATR 에 대해서는, 「DVD 비디오의 사양」을 참조할것.

IDvdInfo::GetCurrentUOPS

IDvdInfo 인터페이스

현재 유효하게 되어 있는 IDvdControl 메소드를 취득한다.

구문

HRESULT GetCurrentUOPS(
    VALID_UOP_SOMTHING_OR_OTHER *pUOP
    );

파라미터

pUOP
[out] 모든 유저 조작 (UOP)의 비트가 저장 되고 있는 DWORD 값에의 포인터. DWORD 내의 각 비트는, 개개의 유저 조작 상태 (유효 또는 무효)를 나타낸다. 어느 유저 조작에 대응하는 비트가 세트 되고 있으면, 그 유저 조작은 금지되고 있다. 상세한 것에 대하여는, 「주의」를 참조할것.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

pUOP 의 값은, 다음과 같이 정의된 비트 필드이다.

비트 | 플래그 | 유저 함수
0 | UOP_FLAG_Title_Or_Time_Play | TitlePlay ,TimePlay
1 | UOP_FLAG_Chapter_Search_Or_Play | ChapterSearch ,ChapterPlay
2 | UOP_FLAG_Title_Play | TitlePlay
3 | UOP_FLAG_Stop | StopForResume
4 | UOP_FLAG_GoUp | GoUp
5 | UOP_FLAG_Time_Or_Chapter_Search | TimeSearch ,ChapterSearch
6 | UOP_FLAG_Prev_Or_Top_PG_Search | PrevPGSearch ,TopPGSearch
7 | UOP_FLAG_Next_PG_Search | NextPGSearch
8 | UOP_FLAG_Forward_Scan | ForwardScan
9 | UOP_FLAG_Backward_Scan | BackwardScan
10 | UOP_FLAG_Title_Menu_Call | 파라미터값 2 (DVD_MENU_Title)의 MenuCall
11 | UOP_FLAG_Root_Menu_Call | 파라미터값 3 (DVD_MENU_Root)의 MenuCall
12 | UOP_FLAG_SubPic_Menu_Call | 파라미터값 4 (DVD_MENU_Subpicture)의 MenuCall
13 | UOP_FLAG_Audio_Menu_Call | 파라미터값 5 (DVD_MENU_Audio)의 MenuCall
14 | UOP_FLAG_Angle_Menu_Call | 파라미터값 6 (DVD_MENU_Angle)의 MenuCall
15 | UOP_FLAG_Chapter_Menu_Call | 파라미터값 7 (DVD_MENU_Chapter)의 MenuCall
16 | UOP_FLAG_Resume | Resume
17 | UOP_FLAG_Button_Select_Or_Activate | UpperButtonSelect , LowerButtonSelect , LeftButtonSelect ,RightButtonSelect ,ButtonActivate ,ButtonSelectAndActivate
18 | UOP_FLAG_Still_Off | StillOff
19 | UOP_FLAG_Pause_On | PauseOn ,MenuLanguageSelect
20 | UOP_FLAG_Audio_Stream_Change | AudioStreamChange
21 | UOP_FLAG_SubPic_Stream_Change | SubpictureStreamChange
22 | UOP_FLAG_Angle_Change | AngleChange ,ParentalLevelSelect
23 | UOP_FLAG_Karaoke_Audio_Pres_Mode_Change | KaraokeAudioPresentationModeChange
24 | UOP_FLAG_Video_Pres_Mode_Change | VideoModePreferrence

DVD 타이틀에서는, 재생중에 거의 임의의 위치에서 개개의 유저 조작을 허가 또는 금지할 수 있기 (위해)때문에, 이 메소드는 유용하다.

IDvdInfo::GetCurrentVideoAttributes

IDvdInfo 인터페이스

현재의 타이틀 또는 메뉴의 현재의 비디오 속성을 취득한다.

구문

HRESULT GetCurrentVideoAttributes(
    DVD_VideoATR *pATR
    );

파라미터

pATR
[out] 취득된 비디오 속성에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 도메인이 DVD_DOMAIN_VideoManagerMenu, DVD_DOMAIN_VideoTitleSetMenu, 또는 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

DVD_VideoATR 에 대해서는, 「DVD 비디오의 사양」을 참조할것.

IDvdInfo::GetCurrentVolumeInfo

IDvdInfo 인터페이스

현재의 DVD 볼륨 정보를 취득한다.

구문

HRESULT GetCurrentVolumeInfo(
    ULONG *pNumOfVol,
    ULONG *pThisVolNum,
    DVD_DISC_SIDE *pSide,
    ULONG *pNumOfTitles
    );

파라미터

pNumOfVol
[out] 취득된 볼륨 세트내의 볼륨의 수에의 포인터.
pThisVolNum
[out] 취득된 이 루트 디렉토리의 볼륨 번호에의 포인터.
pSide
[out] 취득된 현재의 디스크면 (DVD_DISC_SIDE )에의 포인터.
pNumOfTitles
[out] 취득된 이 볼륨으로 이용 가능한 타이틀의 수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetDVDTextInfo

IDvdInfo 인터페이스

다양한 언어의 타이틀명, 볼륨명, 프로듀서명, 가수명등의 설명 텍스트가 저장 되는 TXTDT_MG 구조체를 취득한다.

구문

HRESULT GetDVDTextInfo(
    BYTE *pTextManager,
    ULONG cbBufSize,
    ULONG *pcbActualSize
    );

파라미터

pTextManager
[out, size_is(cbBufSize)] 취득된 텍스트 매니저에의 포인터.
cbBufSize
[in] pTextManager 의 버퍼 사이즈 (바이트 단위).
pcbActualSize
[out] 돌려주어진 데이터의 바이트수가 저장 되고 있는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

cbBufSize 로 건네받은 버퍼 사이즈가 데이터에 비해 너무 작은 경우 (예를 들어,cbBufSize 가 제로의 경우), 이 메소드는 E_OUTOFMEMORY 를 돌려주어,pcbActualSize 가 가리키는 값을 필요한 사이즈로 설정한다.

상세한 것에 대하여는, 「DVD 비디오의 사양」의 Section 4.1. 6 및 Annex A 를 참조할것.

IDvdInfo::GetNumberOfChapters

IDvdInfo 인터페이스

특정의 타이틀에 대해서 정의되고 있는 쳅터의 수를 취득한다.

구문

HRESULT GetNumberOfChapters(
    ULONG ulTitle,
    ULONG *pNumberOfChapters
    );

파라미터

ulTitle
[in] 쳅터수를 취득하는 타이틀.
pNumberOfChapters
[out] 지정된 타이틀의 취득된 쳅터수에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetPlayerParentalLevel

IDvdInfo 인터페이스

DVD 플레이어의 현재의 페어 렌탈 락 레벨과 나라 코드의 설정을 취득한다.

구문

HRESULT GetPlayerParentalLevel(
    ULONG *pParentalLevel,
    ULONG *pCountryCode
    );

파라미터

pParentalLevel
[out] 현재의 페어 렌탈 락 레벨을 나타내는 값에의 포인터.
pCountryCode
[out] 현재의 나라 코드를 나타내는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

정의되고 있는 페어 렌탈 락 레벨에 대해서는, 「DVD 비디오의 사양」의 표 3.3. 4-1 (을)를 참조할것.

유효한 페어 렌탈 락 레벨은, 페어 렌탈 락이 유효하게 되어 있는 경우는 1 에서 8 의 사이이며, 페어 렌탈 락이 무효가 되어 있는 경우는 0xffffffff 이다.

나라 코드에 대해서는, ISO3166 : Alpha-2 코드를 참조할것.

IDvdInfo::GetRoot

IDvdInfo 인터페이스

플레이어로 설정되어 있는 루트 디렉토리를 취득한다.

구문

HRESULT GetRoot(
    LPSTR pRoot,
    ULONG cbBufSize,
    ULONG *pcbActualSize
    );

파라미터

pRoot
[out, size_is(cbBufSize)] 루트 캐릭터 라인을 받는 버퍼에의 포인터. Unicode 스타일의 캐릭터 라인을 건네준다고 하는 COM 규칙에 반해, 루트 캐릭터 라인에서는 ANSI 문자를 사용하는 점에 주의 해야 한다.
cbBufSize
[in] 건네받은 버퍼의 사이즈 (바이트 단위).
pcbActualSize
[out] 돌려주어진 실제의 데이터의 사이즈가 저장 되고 있는 값에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

유효한 루트가 발견되면(자), 이 메소드는 루트 캐릭터 라인을 돌려준다. 그 이외의 경우는,pcbActualSize 를 제로로 해 돌려주어, 유효한 루트 디렉토리가 발견되지 않는, 또는 초기화되어 있지 않은 것을 나타낸다.

IDvdInfo::GetSubpictureLanguage

IDvdInfo 인터페이스

현재의 타이틀내의 지정된 서브 픽쳐 스트림의 언어를 취득한다.

구문

HRESULT GetSubpictureLanguage(
    ULONG nStream,
    LCID *pLanguage );

파라미터

nStream
[in] 스트림 번호.
pLanguage
[out] 취득된 언어에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 도메인이 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

이 메소드는 메뉴의 언어는 돌려주지 않는다. 스트림에 언어가 포함되지 않은 경우, 이 메소드는,pLanguage 가 가리키는 값을 제로로 설정한다. pLanguage 로부터 읽어내 가능한 캐릭터 라인명을 생성 하려면 , 다음과 같이 Win32 GetLocaleInfo 함수를 호출한다. LOCALE_SENGLANGUAGE 는 로케일 정보형이며, pszString 는 요구된 데이터를 받는 버퍼에의 포인터이며, cbSize 는 pszString 의 사이즈를 지정한다.

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

IDvdInfo::GetTitleAttributes

IDvdInfo 인터페이스

메뉴를 포함한 지정된 타이틀의 모든 비디오 스트림, 오디오 스트림, 및 서브 픽쳐 스트림의 속성을 취득한다.

구문

HRESULT GetTitleAttributes(
    ULONG nTitle,
    DVD_ATR *pATR );

파라미터

nTitle
[in] 요구되고 있는 타이틀 번호. 현재의 타이틀의 경우는 0xFFFFFFFF 를 지정한다.
pATR
[out] 취득된 속성 구조체 (DVD_ATR )에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetTitleParentalLevels

IDvdInfo 인터페이스

특정의 타이틀에 대해서 정의되고 있는 페어 렌탈 락 레벨을 취득한다.

구문

HRESULT GetTitleParentalLevels(
    ULONG ulTitle,
    ULONG *pParentalLevels
    );

파라미터

ulTitle
[in] 페어 렌탈 락 레벨이 요구되고 있는 타이틀.
pParentalLevels
[out] 타이틀에 대해서 정의되고 있는 페어 렌탈 락 레벨의 논리 OR 의 편성에의 포인터. 설정 레벨이 높아질수록, 재생되지 않는 컨텐츠가 많아진다. 유효한 페어 렌탈 락 레벨은 이하대로이다.
  • DVD_PARENTAL_LEVEL_8
  • DVD_PARENTAL_LEVEL_7
  • DVD_PARENTAL_LEVEL_6
  • DVD_PARENTAL_LEVEL_5
  • DVD_PARENTAL_LEVEL_4
  • DVD_PARENTAL_LEVEL_3
  • DVD_PARENTAL_LEVEL_2
  • DVD_PARENTAL_LEVEL_1

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

IDvdInfo::GetTotalTitleTime

IDvdInfo 인터페이스

현재의 타이틀의 총재생 시간을 취득한다.

구문

HRESULT GetTotalTitleTime(
    ULONG *pTotalTime
    );

파라미터

pTotalTime
[out] 시, 분, 초, 프레임으로부터 구성되는 DVD_TIMECODE 포맷으로 나타내는 총시간에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 도메인이 DVD_DOMAIN_Title 가 아닌 한 에러를 돌려준다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

이 메소드의 용도는, 의도적으로, 분기 구조를 가지지 않는 단순한 무비로 한정되고 있다.

IDvdInfo::GetVMGAttributes

IDvdInfo 인터페이스

비디오 매니저 (VMG) 메뉴의 모든 비디오 스트림, 오디오 스트림, 및 서브 픽쳐 스트림의 속성을 취득한다.

구문

HRESULT GetVMGAttributes(
    DVD_ATR *pATR
    );

파라미터

pATR
[out] 취득된 속성 구조체 (DVD_ATR )에의 포인터.

반환값

인터페이스의 이행에 응한 HRESULT 값을 돌려준다. 보통의 반환값은 다음의 언젠가이다.
E_FAIL | 실패.
E_INVALIDARG | 입력 인수가 무효.
E_NOTIMPL | 메소드가 지원되어 있지 않다.
E_OUTOFMEMORY | 메모리 부족 (버퍼 스페이스 부족).
E_POINTER | NULL 포인터 인수.
E_UNEXPECTED | DVD 가 초기화되어 있지 않은지, 또는 도메인이 DVD_DOMAIN_Title 는 아니다.
VFW_E_DVD_OPERATION_INHIBITED | 현재의 DVD 비디오의 디스크를 생성 하고 있기 (위해)때문에, 현시점에서는 요구된 액션을 무비로 실행할 수 없다.
S_OK | 성공.
VFW_E_DVD_INVALIDDOMAIN | 요구된 액션은 이 도메인에서는 지원되어 있지 않다 (DVD_DOMAIN ).

주의

이 메소드는, 어느 도메인에서도 유효하다. 상세한 것에 대하여는, 「DVD_DOMAIN 」를 참조할것.

비디오 매니저에는,DVD_MENU_Title 메뉴 등, 복수의 스트림의 그룹이 포함되어 있어 스트림은 특정의 타이틀 번호와 관련지을 수 있지 않았다.


IEnumRegFilters 인터페이스

주 : 이 인터페이스의 사용은 피하는 것. 새로운 어플리케이션에서는, 모니카를 열거해,IEnumMoniker 인터페이스에의 포인터를 돌려주는 IFilterMapper2::EnumMatchingFilters 를 사용하는 것.

이 인터페이스는, 등록이 끝난 필터를 열거하는 메소드를 갖추고 있다. IFilterMapper::EnumMatchingFilters 메소드가, 이 인터페이스에의 포인터를 돌려준다. 다만,IFilterMapper 에 대신해,IFilterMapper2 가 사용되게 되었다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IEnumRegFilters 메소드 | 설명
Next | 조건을 채우는 다음의 필터를 배열로 설정한다.
Skip | 현재는 이행되어 있지 않다.
Reset | 1 번째의 필터를 선두에,Next 메소드를 다시 시작 한다.
Clone | 현재는 이행되어 있지 않다.

IEnumRegFilters::Clone

IEnumRegFilters 인터페이스

현재의 열거자 상태와 같은 상태의, 다른 열거자를 생성 한다.

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT Clone(
    IEnumRegFilters **ppEnum
);

파라미터

ppEnum
[out] 중복 하는 열거자 인터페이스에의 포인터의 주소.

반환값

E_NOTIMPL 를 돌려준다.

IEnumRegFilters::Next

IEnumRegFilters 인터페이스

열거자의 생성시로 지정한 조건을 채우는,cFilters 파라미터로 지정되는 다음의 필터 세트의 기술을 배열로 설정한다.

구문

HRESULT Next(
    ULONG cFilters,
    REGFILTER **apRegFilter,
    ULONG *pcFetched
);

파라미터

cFilters
[in] 필터수.
apRegFilter
[out] REGFILTER 포인터로 구성되는 배열에의 포인터의 주소.
pcFetched
[out] 실제로 건네받은 필터수에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.
E_POINTER | Null 포인터 인수.
E_UNEXPECTED | 예기치 못한 에러.
S_FALSE | 취득된 필터수가, 요구된 수보다 적다.
S_OK | 성공.
VFW_E_ENUM_OUT_OF_SYNC | 열거 자식이 무효가 되었다. 상세한 것에 대하여는, 「주의」를 참조할것.

주의

호출측의 어플리케이션은, Microsoft Win32 CoTaskMemFree 함수를 사용해, 배열에 돌려주어진 각 REGFILTER 포인터를 해방할 필요가 있다. REGFILTER 구조체의 Name 멤버를 개별적으로 해방해서는 안 된다. IEnumRegFilters::Next 는,REGFILTER 구조체의 일부로서 이 캐릭터 라인에 대해서 메모리를 할당하고 있기 때문이다.

등록이 끝난 필터수가 변경을 받으면(자), 열거자 상태와 레지스트리 상태의 일관성이 없어진다. 이 결과, VFW_E_ENUM_OUT_OF_SYNC 가 돌려주어진다. 데이터가 무효의 가능성이 있기 (위해)때문에, 열거자에게로의 전의 호출로부터 취득한 데이터는 모두 파기해,Reset 메소드를 호출해 열거자를 갱신할 필요가 있다. 이 다음에 있으면,Next 메소드를 올바르게 호출할 수가 있다.

IEnumRegFilters::Reset

IEnumRegFilters 인터페이스

열거자를 리셋 한다. 이것에 의해,IEnumRegFilters::Next 메소드의 다음번의 호출은, 다시 선두의 필터 (있는 경우)로부터 시작 한다.

구문

HRESULT Reset(void);

반환값

성공을 나타내는 S_OK 를 돌려준다.

IEnumRegFilters::Skip

IEnumRegFilters 인터페이스

열거 순서 중(안)에서 지정의 항목수를 스킵 한다.

이 메소드는 현재 이행되어 있지 않다. E_NOTIMPL 를 돌려준다.

구문

HRESULT Skip(
  ULONG celt
);

파라미터

celt
[in] 스킵 하는 항목수.

반환값

E_NOTIMPL 를 돌려준다.


IFilterMapper 인터페이스

주 : 이 인터페이스의 사용은 피하는 것. 기존의 어플리케이션과의 후방 호환성을 유지하기 (위해)때문에, 계속해 지원 되지만, 새로운 어플리케이션에서는 IFilterMapper2 인터페이스를 사용하는 것.

이 인터페이스는, 필터를 등록 및 등록 해제하는 메소드와 특성에 근거해 필터를 검색하는 메소드를 제공한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IFilterMapper 메소드 | 설명
RegisterFilter | 레지스트리에 필터의 상세를 기록한다.
RegisterFilterInstance | 필터의 식별 가능한 인스턴스를 등록한다.
RegisterPin | 레지스트리에 핀의 상세를 기록한다.
RegisterPinType | 레지스트리에 핀의 타입을 추가한다.
UnregisterFilter | 레지스트리로부터 필터를 삭제한다.
UnregisterFilterInstance | 필터의 식별 가능한 인스턴스를 삭제한다.
UnregisterPin | 레지스트리로부터 핀을 삭제한다.
EnumMatchingFilters | 특정의 요건을 채우는 필터를 모두 검색한다.

IFilterMapper::EnumMatchingFilters

IFilterMapper 인터페이스

지정된 요건을 채우는 등록이 끝난 필터를 열거하는 열거자를 제공한다.

구문

HRESULT EnumMatchingFilters(
    IEnumRegFilters **ppEnum,
    DWORD dwMerit,
    BOOL bInputNeeded,
    CLSID clsInMaj,
    CLSID clsInSub,
    BOOL bRender,
    BOOL bOutputNeeded,
    CLSID clsOutMaj,
    CLSID clsOutSub
);

파라미터

ppEnum
[out] 돌려주어진 열거자에게로의 포인터의 주소.
dwMerit
[in] 열거하는 필터의 최소메리트값.
bInputNeeded
입력 핀이 적어도 1 개(살) 필요한가 어떤가를 나타내는 값. TRUE 는, 필요한 것을 나타낸다.
clsInMaj
[in] 필요한 입력메이저 타입 . 불요의 경우는, GUID_NULL 를 설정한다.
clsInSub
[in] 필요한 입력 서브 타입. 불요의 경우는, GUID_NULL 를 설정한다.
bRender
[in] 필터가 입력을 렌더링 할 필요가 있을지 어떨지를 지정하는 플래그. TRUE 는, 렌더링 할 필요가 있는 것을 나타낸다.
bOutputNeeded
출력 핀이 적어도 1 개(살) 필요한가 어떤가를 나타내는 값. TRUE 는, 필요한 것을 나타낸다.
clsOutMaj
[in] 필요한 출력 메이저 타입. 불요의 경우는, GUID_NULL 를 설정한다.
clsOutSub
[in] 필요한 출력 서브 타입. 불요의 경우는, GUID_NULL 를 설정한다.

반환값

HRESULT 값을 돌려준다.

주의

ppEnum 파라미터에, 요건을 채우는 필터를 열거하는 열거 자식이 설정된다. dwMerit 파라미터의 메리트값의 상세한 것에 대하여는, 「IFilterMapper::RegisterFilter 」를 참조할것.

IFilterMapper::RegisterFilter

IFilterMapper 인터페이스

레지스트리에 필터를 추가한다. 이 필터는 열거할 수 있다.

구문

HRESULT RegisterFilter(
    CLSID clsid,
    LPCWSTR Name,
    DWORD dwMerit
);

파라미터

clsid
[in] 필터의 글로벌 유니크 식별자 (GUID ).
Name
[in] 필터의 내용을 나타내요 셋집 들이마셔 이름.
dwMerit
[in] 열거에서의 우선 순위. 메리트값이 높은 필터(정도)만큼 먼저 열거된다.

반환값

HRESULT 값을 돌려준다.

주의

메리트 (dwMerit 파라미터로 정의한다)는,IGraphBuilder::Connect ,IGraphBuilder::Render , 또는 IGraphBuilder::RenderFile 의 호출에 의해 필터 그래프 매니저가 조작을 실행할 경우에, 필터를 시험하는 순서를 제어한다. 필터 그래프 매니저는, 올바른 미디어 타입으로 등록되어 있는 필터를 모두 검색한 데다가, 가장 메리트의 높은 것을 시험한다. 이 때, 메리트가 동일한 필터가 다수 있으면, 등록되어 있는 그 외의 조건에 근거해 선택한다.

dwMerit 파라미터에서는, 사전에 정의된 이하의 값을 사용할 수 있다. 그 외의 값 (MERIT_NORMAL+1 등)도 사용할 수 있지만, 그 경우에는 (MERIT_NORMAL+MERIT_UNLIKELY)/2 과 같은 식을 사용해 계산 하면이야 있고. 이렇게 하면(자) 하위 비트가 남아, 그 비트를 사용해 한층 더 세세하게 구별할 수 있기 때문이다.
0x900000 | 하드웨어 렌더러 필터. 이 메리트값을 가지는 필터는 최초로 시험 받는다.
MERIT_PREFERRED (0x800000) | 조작을 직접 실행하는 것이 많은 필터 (렌더러 등).
0x680000 | MPEG 데콘프렛사피르타. 필터 그래프내에서 기능할지 어떨지의 판단에 시간이 걸리는 AVI 데콘프렛사피르타보다 먼저 검색된다.
MERIT_NORMAL (0x600000) | 접속의 확립에 관여할 가능성이 높은 필터. AVI 데콘프렛사피르타 및 스플리터 변환 필터는, 이 값으로 등록된다.
MERIT_UNLIKELY (0x400000) | 접속의 확립에 관여할 가능성이 있는 필터 (칼라 스페이스 변환 필터 등). 필터 그래프 매니저는, 다른 옵션에 실패했을 경우에게만, 이 필터를 사용한다. 소스 필터는 이 값으로 등록한다.
MERIT_DO_NOT_USE (0x200000) | 접속의 확립에 관여하지 않는 필터. 필터 그래프 매니저는, 필터 그래프를 자동 구축 하면 와, 이것 이하의 값으로 등록된 필터를 시험하지 않는다. 명시적으로 추가할 필요가 있는 필터를, 사전에 정의된 필터 그래프의 일부로서 등록하는지, 또는 IFilterGraph::AddFilter 를 사용해 추가할 경우에는, 이 값을 사용한다. 예로서는, 티피르타 또는 이펙트 필터를 들 수 있다.
MERIT_HW_COMPRESSOR (0x100050) | 하드웨어 압력 필터. 필터 그래프 매니저는, 필터 그래프를 자동 구축 하면 와, 이 값으로 등록된 필터를 시험하지 않는다.
MERIT_SW_COMPRESSOR (0x100000) | 소프트웨어 압력 필터. 필터 그래프 매니저는, 필터 그래프를 자동 구축 하면 와, 이 값으로 등록된 필터를 시험하지 않는다.

IFilterMapper::RegisterFilterInstance

IFilterMapper 인터페이스

필터의 식별 가능한 인스턴스를 등록한다.

구문

HRESULT RegisterFilterInstance(
    CLSID clsid,
    LPCWSTR Name,
    CLSID *MRId
);

파라미터

clsid
[in] 필터의 GUID.
Name
[in] 인스턴스의 내용을 나타내요 셋집 들이마셔 이름.
MRId
[out] 돌려주어진 미디어 리소스 ID 에의 포인터. 이 파라미터는, 이 필터의 이 인스턴스에 붙일 수 있었던 로컬 일의 식별자이다.

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는, 같은 드라이버로 제어하는 유사한 사운드 카드가 2 개 이용 가능해, 소리를 울리는 사운드 카드를 선택할 필요가 있는 것 같은 경우에 사용한다. 필터의 인스턴스가 1 개 밖에 없는 경우 (컴퓨터에 있는 사운드 카드가 1 개만의 경우 등), 또는 필터의 인스턴스가 모두 동등한 경우, 이 메소드는 필요없다.

필터 자체는 이미 등록되지 않으면 안 된다.

IFilterMapper::RegisterPin

IFilterMapper 인터페이스

레지스트리에 핀의 상세를 기록한다.

구문

HRESULT RegisterPin(
    CLSID Filter,
    LPCWSTR Name,
    BOOL bRendered,
    BOOL bOutput,
    BOOL bZero,
    BOOL bMany,
    CLSID ConnectsToFilter,
    LPWSTR ConnectsToPin
);

파라미터

Filter
[in] 필터의 GUID.
Name
[in] 핀의 이름. 필터내에서 일의가 아니면 안된다. 타입 정보를 나타내는 것 외에 의미는 없다. 필터의 열거로 문제가 발생하기 위해(때문에), 핀에 99 문자를 넘는 이름을 사용해서는 안 된다.
bRendered
[in] 필터가 이 입력을 렌더링 할지 어떨지를 지정하는 값. 렌더링 하는 경우는, TRUE 를 설정한다. 그 이외의 경우는, FALSE 를 설정한다.
bOutput
[in] 출력 핀인가 어떤가를 지정하는 값. 출력 핀의 경우는, TRUE 를 설정한다. 그 이외의 경우는, FALSE 를 설정한다.
bZero
[in] 이 핀의 인스턴스를 1 개도 가지지 않는 필터를 허락할지 어떨지를 지정하는 값. 허락하는 경우는, TRUE 를 설정한다. 그 이외의 경우는, FALSE 를 설정한다. 예를 들어, 사운드 트랙이 없는 무비의 경우, 데콘프렛사피르타로 사운드 출력 핀을 생성 할 필요는 없다.
bMany
[in] 이 핀의 인스턴스를 복수 가지는 필터를 허락할지 어떨지를 지정하는 값. 허락하는 경우는, TRUE 를 설정한다. 그 이외의 경우는, FALSE 를 설정한다. 예를 들어, 믹서에는 입력 핀의 인스턴스가 복수 필요하게 된다.
ConnectsToFilter
[in] 예약이 끝난 상태. NULL 가 아니면 안된다. 이 파라미터는, 필터 그래프 외부에의 접속을 가지는 시스템 규모의 믹서와 같은 필터에서의 사용을 목적으로 하고 있다. 다만, 아직 이행은 되지 않는다.
ConnectsToPin
[in] 예약이 끝난 상태. NULL 가 아니면 안된다.

반환값

HRESULT 값을 돌려준다.

IFilterMapper::RegisterPinType

IFilterMapper 인터페이스

핀의 타입을 등록한다.

구문

HRESULT RegisterPinType(
    CLSID clsFilter,
    LPCWSTR strName,
    CLSID clsMajorType,
    CCLSID clsSubType
);

파라미터

clsFilter
핀이 속하는 필터의 클래스 식별자 (CLSID).
strName
핀의 이름.
clsMajorType
이 핑크 라스로 지원 되는 미디어 샘플의 메이저 타입.
clsSubType
이 핑크 라스로 지원 되는 미디어 샘플의 서브 타입.

반환값

HRESULT 값을 돌려준다.

주의

clsMajorType 파라미터 및 clsSubType 파라미터는, 핀의 미디어 타입을 지정하는 것이어, 각각 AM_MEDIA_TYPE 구조체의 majortype 멤버 및 subtype 멤버에 대응한다.

IFilterMapper::UnregisterFilter

IFilterMapper 인터페이스

레지스트리로부터 필터를 삭제한다.

구문

HRESULT UnregisterFilter(
    CLSID Filter
);

파라미터

Filter
[in] 필터의 GUID.

반환값

HRESULT 값을 돌려준다.

IFilterMapper::UnregisterFilterInstance

IFilterMapper 인터페이스

레지스트리로부터 필터의 인스턴스를 삭제한다.

구문

HRESULT UnregisterFilterInstance(
    CLSID MRId
);

파라미터

MRId
[in] 이 인스턴스의 미디어 리소스 ID.

반환값

HRESULT 값을 돌려준다.

IFilterMapper::UnregisterPin

IFilterMapper 인터페이스

레지스트리로부터 핀을 삭제한다.

구문

HRESULT UnregisterPin(
    CLSID Filter,
    LPCWSTR Name
);

파라미터

Filter
[in] 이 핀이 속하는 필터의 GUID.
Name
[in] 핀의 이름.

반환값

HRESULT 값을 돌려준다.


DirectShow 그래프 파일 포맷

여기에서는, GraphEdit 에 의해 생성 되어 보존된 Microsoft® DirectShow® 그래프 파일 (. grf)의 포맷에 대해 설명한다.

docfile (보존 파일)는, ActiveMovieGraph 라는 이름의 스트림을 저장 하고 있다. 이 단독의 스트림안에, 모든 필터, 필터명, 파일명, 접속등이 포함되어 있다.

그래프를 로드하려면 :

  • 보존 파일명을 RenderFile 에 건네준다. RenderFile 는 그것이 미디어 파일은 아니고 보존된 그래프이다고 인식해, 그래프를 복원한다.

또는,

  1. (StgOpenStorage 를 사용해) 보존 파일을 연다.
  2. 필터 그래프 매니저에 대해서 IPersistStream 를 조회한다.
  3. (IStorage::OpenStream 를 사용해) L"ActiveMovieGraph" 스트림을 연다.
  4. (IPersistStream::Load 을 사용해) 스트림을 필터 그래프에 건네준다.

스트림내의 그래프의 구문을 이하에 나타낸다.

<graph> ::= <version3><filters><connections><clock>END | <version2><filters><connections>END
<version3> ::= 0003\r\n
<version2> ::= 0002\r\n
<clock> ::= CLOCK <b> <required><b><clockid>\r\n
<required> ::= 1|0
<clockid> ::= <n>|<class id>
<filters ::= FILTERS <b>[<filter list><b>]
<connections> ::= CONNECTIONS [<b> <connection list>]
<filter list> ::= [<filter> <b>] <filter list>
<connection list> ::= [<connection><b>]<connection list>
<filter> ::= <n><b>"<name>"<b><class id><b>[<file>]<length><b1><filter data>
<file> ::= SOURCE "<name>"<b> | SINK "<name>"<b>
<class id> ::= 표준 캐릭터 라인 포맷의 필터의 클래스 ID.
<name> ::= " 를 포함하지 않는 임의의 문자 순서.
<length> ::= 부호 없음 10 진수 (예를 들어 23)를 나타내는 캐릭터 라인.
이것은, 공백을 끼워 후에 계속되는 데이터의 바이트수이다.
<b> ::= 공백, \t, \r, 또는 \n 의 임의의 편성.
<b1> ::= 1 개의 공백 문자.
<n> ::= 정수 (예를 들어 0001, 0002, 0003)의 식별자.
<connection> ::= <n1><b>"<pin1 id>"<b><n2><b>"<pin2 id>" <media type>
<n1> ::= 1 번째의 필터의 식별자.
<n2> ::= 2 번째의 필터의 식별자.
<pin1 id> ::= <name>
<pin2 id> ::= <name>
<media type> ::= <major type><b><sub type><b><flags><length><b1><format>
<major type> ::= <class id>
<sub type> ::= <class id>
<flags> ::= <FixedSizeSamples><b><TemporalCompression><b>
<FixedSizeSamples> ::= 1|0
<TemporalCompression> ::= 1|0
<Format> ::= <SampleSize><b><FormatType><b><FormatLength><b1><FormatData>
<FormatType> ::= 표준 캐릭터 라인 포맷의 포맷의 클래스 ID.
<FormatLength> ::= 부호 없음 10 진수 (예를 들어 23)를 나타내는 캐릭터 라인.
이것은, 공백을 끼워 후에 계속되는 데이터의 바이트수이다.
<FormatData> ::= 바이너리 데이터.

출력으로는, 필터마다, 접속마다, 및 키워드 FILTERS 와 CONNECTIONS 마다 복귀 개행 (\r\n)이 삽입된다. 그 이외의 <B> 는 1 개의 공백이다. 키워드 FILTERS, CONNECTIONS, 및 END 는 로컬라이즈 가능하지 않다. 필터 데이터와 포맷 데이터는 바이너리이므로, 부적절한 개행이나 NULL 값등을 포함하는 일이 있다.

이하에, 출력의 예를 나타낸다 (접속행은 길기 때문에 여기에서는 분할하고 있다. 코멘트는, <코멘트 > 의 포맷으로 가리켜 있다).

0002
<구문의 버젼 2>
FILTERS
0001 "Source" {00000000-0000-0000-0000-000000000001} SOURCE "MyFile.mpg" 0000000000
<ID   이름 필터의 GUID (로드에 필요)
         원시 파일명 프라이빗 데이터 없음 >
0002 "another filter" {00000000-0000-0000-0000-000000000002} 0000000008 XXXXXXXX
<ID   이름   GUID   (이것은 파일 소스 또는 세면대가 아니다)   8 바이트 프라이빗 데이터 >
CONNECTIONS
0001 "Output pin" 0002 "In"   <여기에는 개행 없음 >
<필터 ID 핀 ID   필터 ID 핀 ID  (출력 핀이 앞으로 그 다음에 입력 핀) >
    0000000172 {00000000-0000-0000-0000-000000000003}   <여기에는 개행 없음 >
<샘플 사이즈, 미디어 타입 메이저 타입 >
    {00000000-0000-0000-0000-000000000004} 1 0   <여기에는 개행 없음 >
<미디어 타입 서브 타입, 고정 사이즈 샘플, 시계열 압축 없음 >
    0000000093 {00000000-0000-0000-0000-000000000005} 18 YYYYYYYYYYYYYYYYYY
<포맷의 길이 포맷 타입   18 바이트의 바이너리 포맷 데이터 >
END

여기서,

  • XXX... 필터 데이터를 나타낸다.
  • YYY... 포맷 데이터를 나타낸다.

파일내의 캐릭터 라인 및 문자는 항상 Unicode™ 로 나타내진다.


Filter Graph Markup Language (XGR)

DirectShow 그래프 빌더의 XML 인터페이스는, DirectShow 그래프의 새로운 영속성 포맷을 제공한다. 이 포맷은, 그래프의 영속성을 읽어내 가능한 형태로 해 디버그를 실시하는 것만을 목적으로 하고 있어, 어플리케이션으로 사용하는 것은 목적으로 하지 않았다.

GraphEdit 로 그래프를 XGR 포맷으로 보존하려면 ,[File] 메뉴의 [Save As XML] 를 선택한다.

목차

  • FGML 의 규칙과 규약
  • 이름부의 경합
  • XGR 용의 XML 태그
    • GRAPH
    • FILTER
    • PARAM
    • CONNECT
    • RENDER
    • FILESOURCE
    • INCLUDE
    • VIDEOCOMPRESS
    • AUDIOCOMPRESS
    • SUBGRAPH
    • FRAGMENT
  • FGML schema

FGML 의 규칙과 규약

FGML 파일의 디폴트의 파일 확장자(extension)는 . XGR 이다. 이 문서에서는, XGR 와 FGML 가 동의어로서 사용되고 있다.

FGML 의 파일 포맷, 토큰화, 및 해석은 XML 1.0 규격에 준거하고 있다.

게다가 DirectShow 필터 그래프에 고유의 문제에 대처하기 위해(때문에), 이하의 규칙이 추가되고 있다.

이름부의 경합

XGR 파일의 각각의 필터 정의 및 핀 정의에서는, 일의인 식별자를 정의할 필요가 있다. 일의인 식별자가 정의되어 있지 않은 경우는, XGR 리더가 자동적으로 경합을 해결한다. XGR 파일이 읽히면(자), 필터의 인스턴스가 생성되어 문서의 지정에 따라 핀이 명명된다. 경합이 발생했을 경우는, 같은 이름을 사용하려고 한 2 번째의 필터 또는 핀에 다른 이름을 붙일 수 있다. 이 이름은, 요구된 이름을 기본으로 해, 일의성을 갖게하기 위해서(때문에) 사픽스를 추가한 이름이 된다. XGR 리더는 이러한 이름의 변경이 발생한 것을 클라이언트 코드에 통지하지 않기 때문에, 클라이언트는, XGR 파일이 로드 된 후, 그러한 이름이 올바른 이름을 사용해 오브젝트를 참조하도록(듯이) 처리할 필요가 있다.

이름부의 경합을 회피하기 위해(때문에), XGR 사양에는 스코프 연산자가 추가되고 있다. 스코프 연산자는, <SUBGRAPH> 태그를 사용해 정의된다. 서브 그래프내에서 정의된 모든 필터는, 복합명 "subgraph_name.child_filter_name" 를 사용해 참조할 수 있다. DirectShow 의 현재의 릴리스는, 네이티브에서는 서브 그래프를 지원 하고 있지 않지만, 장래의 릴리스에서는 이것이 바뀔 가능성이 있다. 그 경우는, 네이티브의 DirectShow 서브 그래프에 대해서도 같은 이름부 규약이 적용되어'. ＇ 연산자가, 아이 필터를 포함 하는 서브 그래프 필터와 아이 필터의 이름을 단락짓는 수단이 된다.

XGR 용의 XML 태그

GRAPH 요소

GRAPH 요소는, 그래프 빌더 문서의 루트 요소이다. 이 요소의 파라미터는 정의되어 있지 않다. XGR 파일내에서는 GRAPH 태그를 네스트 할 수 없다.

구문:

<GRAPH version=”{number} >
...
</GRAPH>

속성 | 필수인가 어떤가 | 설명
version | 필수는 아니다 | 이 파일이 따르는 XGR 파일 사양의 버젼을 지정한다. 특히 지정이 없는 경우, 이 값은, 현재 유일한 유효한 버젼인 "1" 이 된다.

관련하는 태그

친요소 | 아이 요소
없음 | FILTER
 | CONNECT
 | SUBGRAPH

례

<GRAPH>

<FILTER id=”videocompress” clsid=”{…}” />

</GRAPH>

FILTER 요소

설명

FILTER 요소는, 그래프내의 필터를 정의하기 위해서 사용한다. 그래프 빌더는, 이 요소로 정의되고 있는 정보를 이용해, 적절한 필터를 선택해, 생성 한다. 이 요소는, 필터에 대해서 설정되는 프로퍼티도 정의한다. FILTER 요소를 유효하게 하려면 , 'category'속성 또는 'clsid'속성의 어느쪽이든을 지정할 필요가 있지만, 양쪽 모두를 지정할 수 없다. 양쪽 모두의 속성이 지정되었을 경우는, 'clsid'가 사용되어'category'속성 및 'instance'속성은 무시된다.

구문:

<FILTER
id=”filter_name”
clsid=”{GUID}”
category=”category_name”
instance=”instance name”
/>

속성 | 필수인가 어떤가 | 설명
id | 필수 | 그래프내의 필터의 인스턴스의 이름을 지정한다.
clsid | 필수는 아니다 | 필터의 클래스 ID 를 지정한다. 그래프 빌더는, 이것을 이용해 필터의 인스턴스를 생성 한다. clsid 가 지정되고 있는 경우, category 속성과 instance 속성은 사용할 수 없다.
category | 필수는 아니다 | 그래프 빌더가 사용하는 필터의 카테고리를 지정한다. 그래프 빌더는 이것을 사용해, 필터를 검색한다. 'instance'가 지정되어 있지 않은 경우는, 이 카테고리의 디폴트의 필터의 인스턴스가 생성된다. clsid 가 지정되고 있으면(자), 이 속성은 무시된다.
instance | 필수는 아니다 | 카테고리가 지정되고 있는 경우는, 'Instance'속성을 사용해, 그 카테고리의 어느 필터의 인스턴스를 생성하는지를 지정한다. clsid 가 지정되고 있으면(자), 이 속성은 무시된다.

주의

친요소 | 아이 요소
GRAPH | PARAM

례

<FILTER id=”asfmux” clsid=”{…. } />

<FILTER id=”capture” category=”{Video Capture Sources}” instance=”winnov” />

<FILTER id=”videocompress” clsid=”{? c}”>

<PARAM name=”bitrate” value=”24000” />

</FILTER>

PARAM 요소

설명

PARAM 요소는, 필터의 프로퍼티를 설정하는 일반적인 방법을 정의한다. 이 요소는, 필터에게 건네지는 이름과 값의 편성을 정의한다. 이름과 값의 편성은, PARAM 요소의 속성으로서 정의된다.

구문:

<PARAM name=”fps” value=”15” />

속성 | 필수인가 어떤가 | 설명
name | 필수 | name 프로퍼티를 지정한다.
Value | 필수 | 프로퍼티의 값을 지정한다.

주의

친요소 | 아이 요소
FILTER | 없음

례

<FILTER id=”videocompress” clsid=”{? c}”>

<PARAM name=”bitrate” value=”24000” />

<PARAM name=”fps” value=”15” />

</FILTER>

CONNECT 요소

설명

CONNECT 요소는, 2 개의 필터간의 접속을 정의하기 위해서 사용한다. 사용하는 핀이 지정되어 있지 않은 경우, CONNECT 는, 방향이 올바르고, 접속되어 있지 않은 필터 위에의 핀을 검색해, 그 중의 1 개를 선택한다. 그 경우, 그 이후에 XGR 로부터 생성되는 그래프의 인스턴스에서도 같은 핀이 선택되는 보증은 없기 때문에, 특정의 핀이 필요한 때는, 절대 패스명으로 지정할 필요가 있다.

구문:

<CONNECT
src=”src_filter_name”
srcpin=”src_pin_name”
dest=”dest_filter_name”
destpin=”dest_pin_name”
CONNECT/>

속성 | 필수인가 어떤가 | 설명
src | 필수 | 접속의 데이터 소스로서 사용하는 필터의 절대 패스명.
srcpin | 필수는 아니다 | 데이터 소스의 접속 상대가 되는 특정의 핀의 이름.
dest | 필수 | 접속의 데이터 세면대로서 사용하는 필터의 절대 패스명.
destpin | 필수는 아니다 | 데이터 세면대의 접속 상대가 되는 특정의 핀의 이름.

주의

친요소 | 아이 요소
GRAPH | 없음

례

<CONNECT src=”vidcap.video” srcpin=’pin1’ dest=’renderer’ destpin=’pin3’ />

RENDER 요소

설명

RENDER 요소는, 그래프 빌더에 대해서, 지정된 필터와 핀을 렌더링 할 필요가 있는 것을 통지한다.

구문:

<RENDER id=”filter_name” pin=”pin_name />

속성 | 필수인가 어떤가 | 설명
Id | 필수 | 렌더링에 사용하는 필터의 이름.
pin | 필수 | 사용하는 핀의 이름.

주의

친요소 | 아이 요소
GRAPH | 없음

례

<FILTER id=”waveout” clsid=”{…. } />

<RENDER id=”waveout”>

FILESOURCE 요소

설명

FILESOURCE 요소는, 재생하는 파일의 URL 를 지정한다. 이 URL 의 미디어 타입에 근거해, 지정된 id 의 소스 필터의 인스턴스가 생성된다.

문제 – 이것은 1 개의 필터를 생성 하는지, 입력 서브 그래프를 생성 하는 것인가.

구문:

<FILESOURCE id=”source_filter_name” url=”file url” />

속성 | 필수인가 어떤가 | 설명
id | 필수 | 인스턴스가 생성된 소스 필터로 사용되는 이름.
url | 필수 | 소스 필터가 열리는 미디어 파일을 식별하는 URL.

주의

친요소 | 아이 요소
GRAPH | 없음

례

<FILESOURCE id="ASF1" url="http://example.microsoft.com/"/>

INCLUDE 요소

설명

INCLUDE 요소는, 다른 XGR 파일 또는 FRAGMENT 를 현재의 XGR 스트림에 포함하기 위해서(때문에) 사용한다. 이것에 의해, 공통의 소스의 코드를 사용해, 작은 코드로부터 복잡한 그래프를 생성 할 수 있다. GRAPH 요소의 네스트를 금지하고 있는 규칙에 위반하기 (위해)때문에, INCLUDE 된 파일에 GRAPH 요소를 포함할 수 없다. "url" 속성이 설정되어 있는 경우,"fragment" 속성은 모두 무시된다. 이러한 속성은 양립하지 않는다. 지정된 url 또는 fragment 가 존재하지 않는 경우, INCLUDE 요소는 무시된다.

구문:

< INCLUDE
url=”url_for_file”
fragment=”fragment_name”
subgraph=”subgraph_name”
/>

속성 | 필수인가 어떤가 | 설명
url | 필수는 아니다 | 그래프에 포함하는 XGR 파일을 가리키는 URL. fragment 속성이 설정되어 있지 않은 경우는, 이것을 지정할 필요가 있다.
fragment | 필수는 아니다 | 포함하는 XGR FRAGMENT 요소의 이름. url 속성이 설정되어 있지 않은 경우는, 이것을 지정할 필요가 있다. url 가 설정되어 있는 경우, 이것은 무시된다.
subgraph | 필수는 아니다 | 서브 그래프가 지정되고 있는 경우는, 파일 fragment가 그래프내에 다른 서브 그래프를 생성 하는 것이라고 보여진다. 이것은, SUBGRAPH 요소안에 INCLUDE 요소를 랩 하는 것에 동일하다. subgraph 속성이 사용되어 있지 않은 경우, 파일은 디폴트의 이름 공간에 로드 된다.

주의

친요소 | 아이 요소
GRAPH | 없음

례

<INCLUDE url="http://example.microsoft.com/" subgraph="capture"/>

VIDEOCOMPRESS 요소

설명

VIDEOCOMPRESS 요소는, 어느 포맷의 입력 비디오 스트림을 받아, 그것을, 필요하게 되는 출력 포맷으로 변환하는 필터의 표준적인 세트의 인스턴스를 생성하기 위해서 사용한다. 이것은, 이 태스크를 실행하기 위해서 필요한 필터의 완전한 세트의 인스턴스를 생성하는데 대신하는 방법이다. 사용하는 핀이 지정되어 있지 않은 경우는, 필터 위에의 이용 가능한 최초의 핀이 사용된다. 그 이후에, XGR 로부터 생성되는 그래프의 인스턴스에서도 같은 핀이 디폴트로 사용되는 보증은 없기 때문에, 특정의 핀이 필요한 경우는, 절대 패스명으로 지정할 필요가 있다.

구문:

< VIDEOCOMPRESS
src=”src_filter_name”
srcpin=”src_filter_pin_name”
dest=”dest_filter”
destpin=”dest_filter_pin_name”
width="{number}"
size="{number}"
codec=”codec_name”
datarate=”{number}”
keyframespacing=”{number}”
frametime=”{number}”
subgraph=”subgraph_name”
/>

속성 | 필수인가 어떤가 | 설명
src | 필수 | 접속의 데이터 소스로서 사용하는 필터의 절대 패스명.
srcpin | 필수는 아니다 | 데이터 소스의 접속 상대가 되는 특정의 핀의 이름.
dest | 필수 | 접속의 데이터 세면대로서 사용하는 필터의 절대 패스명.
destpin | 필수는 아니다 | 데이터 세면대의 접속 상대가 되는 특정의 핀의 이름.
width | 필수 | 픽셀 단위로 나타내는 출력 스트림의 폭.
height | 필수 | 픽셀 단위로 나타내는 출력 스트림의 높이.
CODEC | 필수 | 비디오 변환을 실시할 때 사용하는 CODEC.
datarate | 필수 | kb/초단위로 나타내는 출력 스트림의 데이터 속도.
keyframespacing | 필수 | keyframespacing 를 정의한다.
frametime | 필수 | frametime 를 정의한다.
subgraph | 필수는 아니다 | subgraph 가 지정되고 있는 경우, 비디오 압축 필터는, 그래프내의 다른 서브 그래프내에 있는 것이라고 보여진다. 이것은, VIDEOCOMPRESS 요소를 SUBGRAPH 요소안에 랩 하는 것에 동일하다. subgraph 속성이 사용되어 있지 않은 경우, 파일은 디폴트의 이름 공간에 로드 된다.

주의

친요소 | 아이 요소
GRAPH | 없음

례

AUDIOCOMPRESS 요소

설명

AUDIOCOMPRESS 요소는, 어느 포맷의 입력 오디오 스트림을 받아, 그것을, 필요하게 되는 출력 포맷으로 변환하는 필터의 표준적인 세트의 인스턴스를 생성하기 위해서 사용한다. 이것은, 이 태스크를 실행하기 위해서 필요한 필터의 완전한 세트의 인스턴스를 생성하는데 대신하는 방법이다. 사용하는 핀이 지정되어 있지 않은 경우는, 필터 위에의 이용 가능한 최초의 핀이 사용된다. 그 이후에 XGR 로부터 생성되는 그래프의 인스턴스에서도 같은 핀이 디폴트로 사용되는 보증은 없기 때문에, 특정의 핀이 필요한 경우는, 절대 패스명으로 지정할 필요가 있다.

구문:

< AUDIOCOMPRESS
src=”src_filter_name”
srcpin=”src_filter_pin_name”
dest=”dest_filter”
destpin=”dest_filter_pin_name”
samplerate="{number}"
sampledepth=”{number}”
channels=”{number}”
subgraph=”subgraph_name”
/>

속성 | 필수인가 어떤가 | 설명
src | 필수 | 접속의 데이터 소스로서 사용하는 필터의 절대 패스명.
srcpin | 필수는 아니다 | 데이터 소스의 접속 상대가 되는 특정의 핀의 이름.
dest | 필수 | 접속의 데이터 세면대로서 사용하는 필터의 절대 패스명.
destpin | 필수는 아니다 | 데이터 세면대의 접속 상대가 되는 특정의 핀의 이름.
samplerate | 필수 | k/초에 나타내는 출력 스트림의 샘플 속도.
sampledepth | 필수 | 비트 단위로 나타내는 각 오디오 샘플의 샘플 사이즈.
channels | 필수는 아니다 | 출력 스트림내의 다른 오디오 채널의 수. 지정되어 있지 않은 경우의 디폴트는,"1" 이 된다.
subgraph | 필수는 아니다 | subgraph 가 지정되고 있는 경우, 비디오 압축 필터는, 그래프내의 다른 서브 그래프내에 있는 것이라고 보여진다. 이것은, VIDEOCOMPRESS 요소를 SUBGRAPH 요소안에 랩 하는 것에 동일하다. subgraph 속성이 사용되어 있지 않은 경우, 파일은 디폴트의 이름 공간에 로드 된다.

주의

친요소 | 아이 요소
GRAPH | 없음

례

SUBGRAPH 요소

설명

SUBGRAPH 요소는, 필터 그래프내에서 이름 공간과 분할 동작을 생성 하기 위해서 사용한다. SUBGRAPH 요소내에서 정의된 모든 필터는, 필터 태그내에서 서브 그래프명을 프리픽스로서 추가한 이름을 사용해 참조할 수 있다. 예를 들어, 서브 그래프 "SG1" 내의 "Filter" 라는 이름의 필터는,"SG1.Filter" 라는 이름에 의해 참조된다.

구문:

< SUBGRAPH name=”subgraph_name”> ... </SUBGRAPH>

속성 | 필수인가 어떤가 | 설명
subgraph_name | 필수 | 이 서브 그래프로 사용되는 이름.

주의

친요소 | 아이 요소
GRAPH | 없음

FRAGMENT 요소

설명

FRAGMENT 요소는, 그래프내의 다양한 장소에 포함할 수가 있는 XGR 코드의 재이용 가능한 섹션을 생성 한다. FRAGMENT 요소가 있으면(자), 태그내의 그 이후의 모든 요소는 필터 그래프에 추가되지 않는다. 이 FRAGMENT 를 참조하는 INCLUDE 태그가 있으면(자), fragment의 요소는, INCLUDE 요소의 위치에 있는 XGR 파일내에 있는것 같이, XGR 스트림에 삽입된다. XGR 파일내에는 몇회에서도 FRAGMENT 를 INCLUDE 할 수가 있다. FRAGMENT 에는, GRAPH 이외이면, 어떠한 요소에서도 포함할 수가 있다.

구문:

< FRAGMENT name=”fragment_name”>
...
</FRAGMENT>

속성 | 필수인가 어떤가 | 설명
fragment _name | 필수 | 이 fragment로 사용되는 이름

주의

친요소 | 아이 요소
GRAPH | 없음

례

FGML schema

<? xml version="1. 0"? >

<Schema xmlns="urn:schemas-microsoft-com:xml-data"

xmlns:dt="urn:schemas-microsoft-com:datatypes">

<! -- Define standard attribute types -->

<AttributeType name="category" dt:type="string" />

<AttributeType name="clsid" dt:type="string" />

<AttributeType name="dest" dt:type="string" />

<AttributeType name="destpin" dt:type="string" />

<AttributeType name="id" dt:type="string" />

<AttributeType name="instance" dt:type="string" />

<AttributeType name="name" dt:type="string" />

<AttributeType name="pin" dt:type="string" />

<AttributeType name="src" dt:type="string" />

<AttributeType name="srcpin" dt:type="string" />

<AttributeType name="url" dt:type="string" />

<AttributeType name="value" dt:type="string" />

<! -- GRAPH element definition -->

<ElementType name="GRAPH" content="eltOnly" model="closed" order="many">

<! -- decide if a version attribute is required -->

<element type="FILTER" />

<element type="CONNECT" />

<element type="SUBGRAPH" />

<element type="PARAM" />

<element type="FILESOURCE" />

</ElementType>

<! -- FILTER element definition -->

<ElementType name="FILTER" content="eltOnly" model="closed" order="many">

<attribute type="id" required="yes" />

<attribute type="clsid" required="no" />

<attribute type="category" required="no" />

<attribute type="instance" required="no" />

<element type="PARAM" />

</ElementType>

<! -- PARAM element definition -->

<ElementType name="PARAM" content="empty" model="closed" order="many">

<attribute type="name" required="yes" />

<attribute type="value" required="yes" />

</ElementType>

<! -- CONNECT element definition -->

<ElementType name="CONNECT" content="empty" model="closed">

<attribute type="src" required="yes" />

<attribute type="srcpin" required="no" />

<attribute type="dest" required="yes" />

<attribute type="destpin" required="no" />

</ElementType>

<! -- RENDER element definition -->

<ElementType name="RENDER" content="empty" model="closed">

<attribute type="id" required="yes" />

<attribute type="pin" required="yes" />

</ElementType>

<! -- FILESOURCE element definition -->

<ElementType name="FILESOURCE" content="empty" model="closed">

<attribute type="id" required="yes" />

<attribute type="url" required="yes" />

</ElementType>

<! -- VIDEOCOMPRESS element definition -->

<! -- AUDIOCOMPRESS element definition -->

<! -- INCLUDE element definition -->

<! -- FRAGMENT element definition -->

<! -- SUBGRAPH element definition -->

</Schema>


국제 아날로그 TV의 튜닝

  • 1 처음에
  • 2 채널 번호 대신에 사용되는 주파수 인덱스
  • 3 주파수의 오버라이드(override)
  • 3.1 레지스트리를 사용한 주파수의 오버라이드(override)
  • 3.2 레지스트리의 변환
  • 4 TV 튜너 필터의 사용
  • 4.1 미조정 정보의 수집
  • 4.2 주파수 테이블과 튜닝 공간이 관련짓고
  • 5 테이블과 할당
  • 5.1 주파수 테이블
  • 5.1. 1 오스트레일리아
  • 5.1. 2 중국
  • 5.1. 3 체코 공화국
  • 5.1. 4 동유럽
  • 5.1. 5 프랑스
  • 5.1. 6 해외 프랑스령국
  • 5.1. 7 아일랜드
  • 5.1. 8 이탈리아
  • 5.1. 9 일본
  • 5.1. 10 뉴질랜드
  • 5.1. 11 NTSC (아메리카 합중국)
  • 5.1. 12 영국
  • 5.1. 13 서유럽
  • 5.1. 14 Unicable
  • 5.2 국 할당

1 처음에

Windows 98 operating system 및 Microsoft® Windows® 98 SE operating system에 부속의 TV 튜너 지원은, 미국 시장의 텔레비젼 선국인 만큼 적합하고 있었다. 국제적인 선국에 관한 대범한 골조는 제정되고 있었지만, 몇개의 문제가 있었기 때문에, 그 골조는 미국 국외에서는 사용할 수 없었다.

채널 번호

TV 튜너 필터 (kstvtune.ax)에는, 채널 번호로부터 주파수에의 매핑용의 내부 테이블이 포함되어 있다. 모든 시장에서 고정 채널 번호가 통용되는 것은 아니다. 예를 들어, 유럽의 소비자는, 실제로는 채널 번호를 사용하고 있지 않다. 유럽의 소비자는, 스스로 채널 번호를 선택해, 방송국이나 케이블 테레비 업자가 각지역에서 사용하고 있는 주파수에 할당하고 있는 것만으로 있다.

이 문제에 대처하기 위해서, 채널 번호로부터 주파수 인덱스에 방식이 변경되었다. 주파수의 선택에는 변함 없이 순위 번호가 사용되고 있지만, 이 경우의 순위 번호는, 채널 번호라고 하는 것보다는 주파수 테이블의 인덱스로서 다루어지고 있다. 특히 미국 시장이나 미국과 같은 채널 구성이 사용되고 있는 시장 등, 채널 번호가 통용되는 지역에서는, 지금도 인덱스가 채널 번호에 직접 대응하고 있다.

고정 주파수 할당

주파수 테이블이 TV 튜너 필터에 짜넣어지고 있었기 때문에, 주파수가 잘못되어 있었을 경우나 폐지되었을 경우에서도, 주파수를 갱신하는 것은 불가능했다. 새로운 주파수를 추가하는 일도 할 수 없었다. 테이블의 실수를 수정하기에는 새로운 바이노리필드의 출하가 필요했지만, 이러한 부적당은 방송국용의 주파수에서는 그다지 문제가 되지 않았다. 그러나, 케이블 테레비의 주파수에서는, 이것이 매우 큰 문제가 된다. 미국외의 케이블 테레비 업자는, 스스로 선택한 주파수로 자유롭게 방송할 수 있기 (위해)때문에, 많은 경우, 같은 채널 구성에 다른 규격의 주파수가 혼재하게 되었다. 이 문제에는, 2 개의 대처 방법이 사용되었다. 1 개(살)은, 케이블 채널 규격 제정 기관이 없는 모든 나라에 대해서 "Unicable" 주파수 테이블을 공급하는 방법이며, 이제(벌써) 1 개(살)은, 1 개(살) 이상의 주파수를 오버라이드(override)하기 위한 Windows 레지스트리 베이스의 메카니즘을 제공하는 방법이다.

잘못한 데이터

TV 튜너 필터에 의해 캡슐화되고 있는 데이터에는, 주파수 테이블, 컬러 텔레비전 방식, 및 국별의 주파수와 컬러 텔레비전 방식의 할당이 포함되어 있다. 종래는, 이러한 테이블의 실수를 수정하려면 , 새로운 TV 튜너 필터를 출하 할 수 밖에 없었다. 이 문제에 대처하기 위해(때문에), 위의 방법의 편성이 사용되는 것과 동시에, 철저한 조사의 결과, 내부의 테이블 및 할당이 갱신되었다. 모든 나라의 방송 주파수 및 컬러 텔레비전 방식의 할당이 올바른 것을 확인하기 위해서, 다대한 노력이 지불해졌다.

이 문서에서는, 새로운 기능에 대해 설명해, 주파수 테이블과 국별의 할당을 나타낸다. 새로운 기능은 Microsoft Windows ME 에 도입된다.

2 채널 번호 대신에 사용되는 주파수 인덱스

새로운 국제 선국 지원의 가장 중요한 점은, 이행이 매우 간단한 일이었다. 실제, 코드의 변경은 완전히 필요없었다. 생각을 "채널 번호 " 로부터 "주파수 인덱스 " 로 바꾸는 것만으로 끝난다. 이것은, 텔레비젼 수신 어플리케이션이, 주파수 인덱스 번호를 최종 사용자에 보여선 안 되는 것을 의미하고 있다. 그 대신에, 유저로 보이는 채널 번호로부터 어플리케이션이 특정의 주파수를 선국할 경우에 사용하는 주파수 인덱스에의 내부 매핑을 마련할 필요가 있다. 미국을 시작해로 하는 일부의 나라에서는, 어플리케이션이 채널 번호로부터 주파수 인덱스에의 일대일의 매핑을 실시할 수가 있다. 그러나, 국제 선국에 대응한 어플리케이션에서는, 최종 사용자 (또는 최종 사용자를 대표하는 대리인)가 각 주파수 (인덱스)에 사용하는 채널 번호를 선택할 수 있도록(듯이) 한다.

주파수 테이블은 조사의 산물이다고 할 뿐(만큼)의 이유에 의해, TV 튜너 필터에서는, 종래 대로, 주파수 테이블을 사용한다. 이 책임을 텔레비젼 수신 어플리케이션에 억누르는 것에는 의미가 없다.

3 주파수의 오버라이드(override)

3.1 레지스트리를 사용한 주파수의 오버라이드(override)

세심의 주위를 기울여도, 주파수 테이블이 충분하지 않기도 하고, 주파수 테이블에 실수가 있거나 주파수 테이블이 낡아지는 일이 있다. 이 문제에 대처하기 위해(때문에), TV 튜너 필터의 주파수 테이블에 포함되어 있는 주파수는, 레지스트리를 이용해 선택식에서 오버라이드(override) 할 수 있게 되어 있다.

도 1:

[HKEY_LOCAL_MACHINE\Software\Microsoft\TV System Services\TVAutoTune\TS0-1]
"12"=dword:04022750
"AutoTune"=hex:00, 00,00,00,50,0c, 4b, 03, d0, 99, a6, 03,50,27,02,04, d0, bd, 9a, 04,50,\
4b, f6, 04,50,1a, 72,0a, 00,00,00,00,50,35,29,0b, d0, c2, 84,0b, 50,50, e0, 0b, d0, dd,\
3b, 0c, 50,6b, 97,0c, d0, 20,3a, 07,50, ae, 95,07, d0, 3b, f1, 07,50, c9, 4c, 08, d0, 56, a8,\
08,50, e4, 03,09, d0, 71,5f, 09,50, ff, ba, 09, d0, 8c, 16,0a, d0, f8, f2, 0c, 50,86,4e, 0d,\
d0, 13, aa, 0d, 50, a1, 05,0e, d0, 2e, 61,0e, 50, bc, bc, 0e, d0, 49,18,0f, 50, d7, 73,0f, d0,\
64, cf, 0f, 50, f2, 2a, 10, d0, 7f, 86,10,50,0d, e2, 10, d0, 9a, 3d, 11,50,28,99,11, d0, b5,\
f4, 11,50,43,50,12, d0, d0, ab, 12,50,5e, 07,13, d0, eb, 62,13,74,6d, bf, 13,00,00,00,\
00,00,00,00,00, d0, 21, d1, 14,50, af, 2c, 15, d0, 3c, 88,15,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00, d0, 8d, ad, 17,50,1b, 09,18, d0, a8, 64,18,50,\
36, c0, 18,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00, f4, e0, fa, 20,50,7a, 55,21,00,\
00,00,00,00,00,00,00, d0, 22,68,22,00,00,00,00,00,00,00,00,50, cb, 7a, 23,00,00,\
00,00,50, e6, 31,24, d0, 73,8d, 24,00,00,00,00, d0, 8e, 44,25,50,1c, a0, 25, d0, a9, fb,\
25,50,37,57,26,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,74,87, df, 06,\
d0, c4, b2, 26,50,52,0e, 27,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00

그림 1 및 위의 텍스트 버젼은, 미조정 정보 및 주파수 오버라이드(override) 정보가 저장 되고 있는 레지스트리 패스를 나타내고 있다. 이 그림의 "TS0-1" 는, 케이블 테레비 주파수의 튜닝 공간 0 을 나타내고 있다. 튜닝 공간 0 에는 방송 주파수용의 TS0-0 도 있다. 이러한 레지스트리의 구조는, 새로운 주파수 오버라이드(override) 메카니즘을 지원 하기 위한(해), 전의 버젼으로부터 변경되고 있다. 이전의 TS*-* 키는, 미조정을 하는 시점에서 유효한 주파수 테이블의 미조정 정보로부터 구성되는 바이너리값이었다. 새로운 포맷에서는, 미조정 정보가 "AutoTune" 서브 키로 이동하고 있다. 그 외의 서브 키는, 모두 주파수 오버라이드(override) 정보의 후보이다. 주파수 오버라이드(override)값에 적절한 값으로 하려면 , 키명을, 현재 유효한 주파수 테이블의 최소 인덱스값과 최대 인덱스값의 사이의 유효한 수치로 할 필요가 있다. 게다가 서브 키의 값은, DWORD 타입일 필요가 있어, Hz 단위로 주파수를 지정할 필요가 있다. 주파수 오버라이드(override)값으로서 적격이 아닌 엔트리는 단지 무시된다. 그림 1 의 예에서는, 인덱스 12 의 주파수를 67.25MHz 로 오버라이드(override) 하고 있다.

주파수 인덱스의 수부터 오버라이드(override)값의 수를 많이 하는 것에 그다지 의미는 없지만, 특정의 튜닝 공간에 주파수 오버라이드(override)값을 몇개에서도 할당할 수가 있다. 같은 키명을 가지는 복수의 인덱스안의 어떤 것이 오버라이드(override)값으로서 선택되는지를 보증할 수 없다.

어플리케이션은, IAMTVTuner::put_TuningSpace 메소드를 이용해, 사용하는 오버라이드(override) 정보와 미조정 정보세트를 선택할 수 있다. 튜닝 공간과 주파수 테이블의 사이의 관계를 유지하는 역할은 어플리케이션이 담당한다.

3.2 레지스트리의 변환

레지스트리에 주파수 오버라이드(override)값정보를 추가하는 어플리케이션은, 튜닝 공간용의 레지스트리의 장소가 새로운 포맷에 따르고 있는 것을 확인할 필요가 있다. TV 튜너 필터를 사용해 변환을 실시할 수가 있다. IAMTVTuner::StoreAutoTune 메소드가 불려 갈 때마다, 낡은 레지스트리 포맷은 새로운 포맷에 변환된다. StoreAutoTune 메소드를 호출하기 전에 미조정 정보를 수집할 필요는 없다. 미조정을 실행하기 위해서, 혹은 단지 변환을 실시하기 위해서(때문에), 셋업의 일부로서 TV 튜너 필터의 인스턴스를 생성하는 것에 문제는 없다.

4 TV 튜너 필터의 사용

이하의 섹션에서는, 추천 되고 있는 TV 튜너 필터 (kstvtune.ax)의 사용법에 대해 설명한다.

4.1 미조정 정보의 수집

미조정 정보의 수집은, 방송 주파수 에 대해서만 추천 되고 있다. 케이블 테레비의 주파수는 일반적으로 정확해요에 대해서, 방송 주파수의 경우는, 인접 채널과의 간섭의 가능성을 경감시키기 (위해)때문에, 방송국이 수킬로헤르츠 단위로 올리거나 내리거나 하는 일이 있다. 어플리케이션은, 종래 대로, IAMTVTuner::AutoTune 메소드를 사용해, 방송 주파수에 맞추어 미조정을 실시할 수가 있다. 이 메소드를 이용 하면, 어플리케이션은, 1 회의 조작으로, 인덱스를 이용해 현재 유효한 테이블에서 주파수를 선택해, 선국 조작을 실행해, 선국 조작의 결과 (수평 락을 달성되었는지 어떠했는지)를 보고할 수가 있다. 이 메소드는, 주파수 오버라이드(override) 정보를 무시하기 위해(때문에), TV 튜너 필터의 주파수 테이블의 주파수가 잘못되어 있는 것이 판명되었을 경우에서도, AutoTune 는, 그 주파수 인덱스에 적절한 결과를 생성하지 않는다.

어플리케이션은, IAMTVTuner::ChannelMinMax 에 의해 보고된 범위내의 각 주파수 인덱스에 대해 1 회 AutoTune 를 호출한다. 어플리케이션이 종료한 후는, IAMTVTuner::StoreAutoTune 를 호출해, 미조정 정보를 레지스트리에 보존할 필요가 있다. AutoTune 메소드는 주파수 오버라이드(override) 정보를 올바르게 처리할 수 없기 때문에, StoreAutoTune 의 다음에 IAMTVTuner::put_TuningSpace 를 호출해, 한번 더 오버라이드(override) 정보를 취득할 필요가 있다.

이것에 대신하는 방법은, IAMTVTuner::put_Channel 메소드와 IAMTuner::SignalPresent 메소드를 사용해 AutoTune 메소드의 동작을 모방하는 방법이다. put_Channel 메소드와 AutoTune 메소드는 같은 이행을 공유하기 위해(때문에), IAMTVTuner::StoreAutoTune 에서도 put_Channel 에 대한 호출의 결과를 이용해, 그것을 레지스트리에 보존할 수가 있다. 이하의 동작은, IAMTVTuner::AutoTune 와 같다.

HRESULT
MyAutoTune(IAMTVTuner *pTuner, long lIndex, long *plFoundSignal)
{
long SignalStrength = AMTUNER_NOSIGNAL;
HRESULT hr;

hr = pTuner->put_Channel(lIndex, AMTUNER_SUBCHAN_DEFAULT, AMTUNER_SUBCHAN_DEFAULT);
if (NOERROR == hr)
pTuner->SignalPresent(&SignalStrength);

// Assume AMTUNER_HASNOSIGNALSTRENGTH means tuned
*plFoundSignal = (SignalStrength ! = AMTUNER_NOSIGNAL);

return hr;
}

방송 수신의 신뢰성의 낮음을 보상하기 위해(때문에), put_Channel 메소드와 AutoTune 메소드로부터 얻을 수 있는 반환값이 조금 확장되고 있다. 방송의 수신에서는, 영상이 보이고 있어도, 수평 락을 취득할 수 없는 것이 있다. 그 경우, 튜너의 하드웨어는 주파수 락을 취득하고 있지만, 디코더는 수평 락을 취득하고 있지 않다. 이 상태는, put_Channel 또는 AutoTune 를 사용할때에, 반환값을 조사하는 것에 의해 검출할 수 있다.

S_OK (or NOERROR)

선국 조작이 성공해, 튜너가 주파수 락을 취득했다 (AutoTune 의 FoundSignal 파라미터가, 수평 락을 달성되었는지 어떠했는지를 나타내는 디코더 상태에 의해 갱신되었다). 방송 주파수에 대해서 AutoTune 를 실행하는 경우, 어플리케이션은, 튜너가 주파수 락을 보고하고 있으면, FoundSignal 파라미터를 무시하도록(듯이) 설정할 수도 있다. 노이즈에 대해서 주파수가 잠그고 있을 가능성이 있지만, 그 가능성을 수신 가능 채널이 스킵 될 가능성이라고 비교 검토할 필요가 있다.

S_FALSE

선국 조작중에 에러는 발생하지 않았지만, 튜너는 주파수 락을 취득할 수 없었다. 이 조작에 의해 수신 가능 채널을 취득할 수 있을 가능성은 극히 낮다.

E_*

다른 모든 반환값은, 어떠한 에러가 발생한 것을 나타낸다.

4.2 주파수 테이블과 튜닝 공간이 관련짓고

어플리케이션은, IAMTVTuner::put_CountryCode 메소드를 사용해 해당하는 나라 코드를 선택하는 것에 의해, 주파수 테이블과 컬러 텔레비전 방식을 선택한다. 나라 코드 및 거기에 대응하는 주파수 테이블과 컬러 텔레비전 방식의 할당은, 후의 섹션 5 에 기재되어 있다.

주파수 오버라이드(override)의 사용을 올바르게 지원 하려면 , 어플리케이션이, 일의인 튜닝 공간 번호를, 선택될 가능성이 있는 각각의 나라 코드에 관련지을 방법이 추천 된다. 적절한 방법은, 나라 코드값을 튜닝 공간값으로서 사용하는 방법이다. 그렇다면, 어플리케이션이 새로운 나라 코드에 바뀔 때마다, 그 나라 코드에 대응하는 튜닝 공간에의 변환도 행해진다 (나라 코드, 튜닝 공간의 순서에 바뀐다). 이것에 의해, 새롭고 유효하게 된 주파수 테이블이 주파수 오버라이드(override) 정보와 미조정 정보에 올바르게 반영되는 것이 보증된다.

5 테이블과 할당

5.1 주파수 테이블

전세계에는 일정수의 기존의 방송 주파수 규격세트가 존재한다. 이러한 규격은, 각국이 제정되어 있는 것이지만, 많은 경우, 복수의 나라가 같은 규격을 채용하고 있다. TV 튜너 필터 (kstvtune.ax)에서는, 각각의 규격의 테이블을 정의하고 있다.

유감스럽지만, 케이블 테레비 주파수 규격의 경우는 사정이 다르다. 일부의 나라의 케이블 테레비 업자는, 자사가 선택한 주파수로 자유롭게 프로그램을 방송할 수 있다. 이 경우는, 복수의 규격의 주파수가 혼재하고 있는 것이 많다. 대부분의 경우, 이 관례는 각각의 주파수 규격이 제정된 나라와 직접 관련하고 있다. TV 튜너 필터에서는, 신뢰성이 있는 케이블 테레비 주파수 할당이 포함되어 따분한가의 케이블 테레비 규격 ( 및 나라)의 테이블을 정의하고 있다. 그 외 모든 경우는,Unicable 주파수 테이블을 사용할 필요가 있다.

이하에 나타내는 주파수 테이블은, TV 튜너 필터로 테이블을 구축할 경우에 사용되는 리소스 파일 정의로부터 추출된 것이다. 각 테이블은, 각각의 리소스 ID 로부터 시작된다. 이러한 리소스 ID 를 사용해, 이하의 섹션 5.2 에 기재된 나라 코드 할당으로부터 상호 참조를 실시해, 각각의 나라 또는 로케일로 사용되고 있는 테이블을 판별할 수가 있다.

5.1. 1 오스트레일리아

오스트레일리아의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다. 채널 3, 4, 5, 및 5A 는 단계적으로 폐지되어 다른 용도에 돌릴 수 있는 점에도 주의할 필요가 있다.

5.1. 1.1 오스트레일리아의 방송 할당

F_OZ__BROAD RCDATA
BEGIN
1L,             // 최소 인덱스
53L,            // 최대 인덱스

46250000L,      // 0    (1) VHF 대 1
57250000L,      // 1    (2)
64250000L,      // 2    (3) VHF 대 2
86250000L,      // 3    (4)
95250000L,      // 4    (5)
102250000L,     // 5    (6)
138250000L,     // 5a   (7) VHF 대 3
175250000L,     // 6    (8)
182250000L,     // 7    (9)
189250000L,     // 8    (10)
196250000L,     // 9    (11)
209250000L,     // 10   (12)
216250000L,     // 11   (13)
223250000L,     // 12   (14)
527250000L,     // 28   (15) UHF 대 4
534250000L,     // 29   (16)
541250000L,     // 30   (17)
548250000L,     // 31   (18)
555250000L,     // 32   (19)
562250000L,     // 33   (20)
569250000L,     // 34   (21)
576250000L,     // 35   (22)
604250000L,     // 39   (23) UHF 대 5
611250000L,     // 40   (24)
618250000L,     // 41   (25)
625250000L,     // 42   (26)
632250000L,     // 43   (27)
639250000L,     // 44   (28)
646250000L,     // 45   (29)
653250000L,     // 46   (30)
660250000L,     // 47   (31)
667250000L,     // 48   (32)
674250000L,     // 49   (33)
681250000L,     // 50   (34)
688250000L,     // 51   (35)
695250000L,     // 52   (36)
702250000L,     // 53   (37)
709250000L,     // 54   (38)
716250000L,     // 55   (39)
723250000L,     // 56   (40)
730250000L,     // 57   (41)
737250000L,     // 58   (42)
744250000L,     // 59   (43)
751250000L,     // 60   (44)
758250000L,     // 61   (45)
765250000L,     // 62   (46)
772250000L,     // 63   (47)
779250000L,     // 64   (48)
786250000L,     // 65   (49)
793250000L,     // 66   (50)
800250000L,     // 67   (51)
807250000L,     // 68   (52)
814250000L,     // 69   (53)
END

5.1. 1.2 오스트레일리아의 케이블 테레비 할당

표준화 된 케이블 테레비 구성에 대응하는 데이터가 없기 때문에,Unicable 주파수 테이블이 사용된다.

5.1. 2 중국

중국의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하고 있다.

5.1. 2.1 중국의 방송 할당

F_CHN_BROAD RCDATA
BEGIN
1L,             // 최소 채널
36L,            // 최대 채널

49750000L,      // 1
57750000L,      // 2
65750000L,      // 3
77250000L,      // 4
85250000L,      // 5
168250000L,     // 6
176250000L,     // 7
184250000L,     // 8
192250000L,     // 9
200250000L,     // 10
208250000L,     // 11
216250000L,     // 12
471250000L,     // 13
479250000L,     // 14
487250000L,     // 15
495250000L,     // 16
503250000L,     // 17
511250000L,     // 18
519250000L,     // 19
527250000L,     // 20
535250000L,     // 21
543250000L,     // 22
551250000L,     // 23
559250000L,     // 24
605250000L,     // 25
613250000L,     // 26
621250000L,     // 27
629250000L,     // 28
637250000L,     // 29
645250000L,     // 30
653250000L,     // 31
661250000L,     // 32
669250000L,     // 33
677250000L,     // 34
685250000L,     // 35
693250000L,     // 36
END

5.1. 2.2 중국의 케이블 테레비 할당

F_CHN_CABLE RCDATA
BEGIN
1L,             // 최소 채널
52L,            // 최대 채널

49750000L,      // 1
57750000L,      // 2
65750000L,      // 3
77250000L,      // 4
85250000L,      // 5
112250000L,     // 6
120250000L,     // 7
128250000L,     // 8
136250000L,     // 9
144250000L,     // 10
152250000L,     // 11
160250000L,     // 12
168250000L,     // 13
176250000L,     // 14
184250000L,     // 15
192250000L,     // 16
200250000L,     // 17
208250000L,     // 18
216250000L,     // 19
224250000L,     // 20
232250000L,     // 21
240250000L,     // 22
248250000L,     // 23
256250000L,     // 24
264250000L,     // 25
272250000L,     // 26
280250000L,     // 27
288250000L,     // 28
471250000L,     // 29
479250000L,     // 30
487250000L,     // 31
495250000L,     // 32
503250000L,     // 33
511250000L,     // 34
519250000L,     // 35
527250000L,     // 36
535250000L,     // 37
543250000L,     // 38
551250000L,     // 39
559250000L,     // 40
567250000L,     // 41
575250000L,     // 42
583250000L,     // 43
591250000L,     // 44
599250000L,     // 45
607250000L,     // 46
615250000L,     // 47
623250000L,     // 48
631250000L,     // 49
639250000L,     // 50
647250000L,     // 51
655250000L,     // 52
END

5.1. 3 체코 공화국

체코 공화국의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다.

5.1. 3.1 체코 공화국의 방송 할당

F_CZE_BROAD RCDATA
BEGIN
1L,             // 최소 인덱스
69L,            // 최대 인덱스

49750000L,      // 1
57750000L,      // 2
59250000L,      // 3
65750000L,      // 4
77250000L,      // 5
85250000L,      // 6
93250000L,      // 7
175250000L,     // 8
183250000L,     // 9
191250000L,     // 10
199250000L,     // 11
207250000L,     // 12
215250000L,     // 13
223250000L,     // 14

0L,             // 15 미사용
0L,             // 16 미사용
0L,             // 17 미사용
0L,             // 18 미사용
0L,             // 19 미사용
0L,             // 20 미사용

471250000L,     // 21
479250000L,     // 22
487250000L,     // 23
495250000L,     // 24
503250000L,     // 25
511250000L,     // 26
519250000L,     // 27
527250000L,     // 28
535250000L,     // 29
543250000L,     // 30
551250000L,     // 31
559250000L,     // 32
567250000L,     // 33
575250000L,     // 34
583250000L,     // 35
591250000L,     // 36
599250000L,     // 37
607250000L,     // 38
615250000L,     // 39
623250000L,     // 40
631250000L,     // 41
639250000L,     // 42
647250000L,     // 43
655250000L,     // 44
663250000L,     // 45
671250000L,     // 46
679250000L,     // 47
687250000L,     // 48
695250000L,     // 49
703250000L,     // 50
711250000L,     // 51
719250000L,     // 52
727250000L,     // 53
735250000L,     // 54
743250000L,     // 55
751250000L,     // 56
759250000L,     // 57
767250000L,     // 58
775250000L,     // 59
783250000L,     // 60
791250000L,     // 61
799250000L,     // 62
807250000L,     // 63
815250000L,     // 64
823250000L,     // 65
831250000L,     // 66
839250000L,     // 67
847250000L,     // 68
855250000L,     // 69

END

5.1. 3.2 체코 공화국의 케이블 테레비 할당

표준화 된 케이블 테레비 구성에 대응하는 데이터가 없기 때문에,Unicable 주파수 테이블이 사용된다.

5.1. 4 동유럽

동유럽의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다.

5.1. 4.1 동유럽의 방송 할당

F_EEU_BROAD RCDATA
BEGIN
1L,             // 최소 인덱스
69L,            // 최대 인덱스

49750000L,      // 1
59250000L,      // 2
77250000L,      // 3
85250000L,      // 4
93250000L,      // 5
175250000L,     // 6
183250000L,     // 7
191250000L,     // 8
199250000L,     // 9
207250000L,     // 10
215250000L,     // 11
223250000L,     // 12

0L,             // 13 미사용
0L,             // 14 미사용
0L,             // 15 미사용
0L,             // 16 미사용
0L,             // 17 미사용
0L,             // 18 미사용
0L,             // 19 미사용
0L,             // 20 미사용

471250000L,     // 21
479250000L,     // 22
487250000L,     // 23
495250000L,     // 24
503250000L,     // 25
511250000L,     // 26
519250000L,     // 27
527250000L,     // 28
535250000L,     // 29
543250000L,     // 30
551250000L,     // 31
559250000L,     // 32
567250000L,     // 33
575250000L,     // 34
583250000L,     // 35
591250000L,     // 36
599250000L,     // 37
607250000L,     // 38
615250000L,     // 39
623250000L,     // 40
631250000L,     // 41
639250000L,     // 42
647250000L,     // 43
655250000L,     // 44
663250000L,     // 45
671250000L,     // 46
679250000L,     // 47
687250000L,     // 48
695250000L,     // 49
703250000L,     // 50
711250000L,     // 51
719250000L,     // 52
727250000L,     // 53
735250000L,     // 54
743250000L,     // 55
751250000L,     // 56
759250000L,     // 57
767250000L,     // 58
775250000L,     // 59
783250000L,     // 60
791250000L,     // 61
799250000L,     // 62
807250000L,     // 63
815250000L,     // 64
823250000L,     // 65
831250000L,     // 66
839250000L,     // 67
847250000L,     // 68
855250000L,     // 69

END

5.1. 4.2 동유럽의 케이블 테레비 할당

표준화 된 케이블 테레비 구성에 대응하는 데이터가 없기 때문에,Unicable 주파수 테이블 (아래를 참조)이 사용된다.

5.1. 5 프랑스

프랑스의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다.

5.1. 5.1 프랑스의 방송 할당

F_FRA_BROAD RCDATA
BEGIN
2L,              // 최소 인덱스
69L,             // 최대 인덱스

55750000L,       // 2
60500000L,       // 3
63750000L,       // 4
176000000L,      // 5
184000000L,      // 6
192000000L,      // 7
200000000L,      // 8
208000000L,      // 9
216000000L,      // 10
0L,              // 11 미사용
0L,              // 12 미사용
0L,              // 13 미사용
0L,              // 14 미사용
0L,              // 15 미사용
0L,              // 16 미사용
0L,              // 17 미사용
0L,              // 18 미사용
0L,              // 19 미사용
0L,              // 20 미사용
471250000L,      // 21
479250000L,      // 22
487250000L,      // 23
495250000L,      // 24
503250000L,      // 25
511250000L,      // 26
519250000L,      // 27
527250000L,      // 28
535250000L,      // 29
543250000L,      // 30
551250000L,      // 31
559250000L,      // 32
567250000L,      // 33
575250000L,      // 34
583250000L,      // 35
591250000L,      // 36
599250000L,      // 37
607250000L,      // 38
615250000L,      // 39
623250000L,      // 40
631250000L,      // 41
639250000L,      // 42
647250000L,      // 43
655250000L,      // 44
663250000L,      // 45
671250000L,      // 46
679250000L,      // 47
687250000L,      // 48
695250000L,      // 49
703250000L,      // 50
711250000L,      // 51
719250000L,      // 52
727250000L,      // 53
735250000L,      // 54
743250000L,      // 55
751250000L,      // 56
759250000L,      // 57
767250000L,      // 58
775250000L,      // 59
783250000L,      // 60
791250000L,      // 61
799250000L,      // 62
807250000L,      // 63
815250000L,      // 64
823250000L,      // 65
831250000L,      // 66
839250000L,      // 67
847250000L,      // 68
855250000L,      // 69

END

5.1. 5.2 프랑스의 케이블 테레비 할당

표준화 된 케이블 테레비 구성에 대응하는 데이터가 없기 때문에,Unicable 주파수 테이블 (아래를 참조)이 사용된다.

5.1. 6 해외 프랑스령국

해외 프랑스령국의 방송 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다. 또, 케이블 테레비 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다.

5.1. 6.1 해외 프랑스령국의 방송 할당

F_FOT_BROAD RCDATA
BEGIN
4L,              // 최소 채널
9L,              // 최대 채널

175250000L,      // 4
183250000L,      // 5
191250000L,      // 6
199250000L,      // 7
207250000L,      // 8
215250000L,      // 9
END

5.1. 6.2 해외 프랑스령국의 케이블 테레비 할당

표준화 된 케이블 테레비 구성에 대응하는 데이터가 없기 때문에,Unicable 주파수 테이블 (아래를 참조)이 사용된다.

5.1. 7 아일랜드

아일랜드의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다.

5.1. 7.1 아일랜드의 방송 할당

F_IRE_BROAD RCDATA
BEGIN
1L,              // 최소 인덱스
10L,             // 최대 인덱스

45750000L,       // A
53750000L,       // B
61750000L,       // C
175250000L,      // D
183750000L,      // E
191250000L,      // F
199250000L,      // G
207250000L,      // H
215250000L,      // I
223250000L,      // J
END

5.1. 7.2 아일랜드의 케이블 테레비 할당

표준화 된 케이블 테레비 구성에 대응하는 데이터가 없기 때문에,Unicable 주파수 테이블 (아래를 참조)이 사용된다.

5.1. 8 이탈리아

이탈리아의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다.

5.1. 8.1. 이탈리아의 방송 할당

F_ITA_BROAD RCDATA
BEGIN
1L,             // 최소 인덱스
10L,            // 최대 인덱스

53750000L,      // 1    A
59750000L,      // 2    B
82750000L,      // 3    C
175250000L,     // 4    D
183750000L,     // 5    E
192250000L,     // 6    F
201250000L,     // 7    G
210250000L,     // 8    H
217250000L,     // 9    H1
224250000L,     // 10   H2

END

5.1. 8.2 이탈리아의 케이블 테레비 할당

표준화 된 케이블 테레비 구성에 대응하는 데이터가 없기 때문에,Unicable 주파수 테이블 (아래를 참조)이 사용된다.

5.1. 9 일본

일본의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하고 있다.

5.1. 9.1 일본의 방송 할당

F_JAP_BROAD RCDATA
BEGIN
1L,             // 최소 채널
62L,            // 최대 채널

91250000L,      // 1
97250000L,      // 2
103250000L,     // 3
171250000L,     // 4
177250000L,     // 5
183250000L,     // 6
189250000L,     // 7
193250000L,     // 8
199250000L,     // 9
205250000L,     // 10
211250000L,     // 11
217250000L,     // 12
471250000L,     // 13
477250000L,     // 14
483250000L,     // 15
489250000L,     // 16
495250000L,     // 17
501250000L,     // 18
507250000L,     // 19
513250000L,     // 20
519250000L,     // 21
525250000L,     // 22
531250000L,     // 23
537250000L,     // 24
543250000L,     // 25
549250000L,     // 26
555250000L,     // 27
561250000L,     // 28
567250000L,     // 29
573250000L,     // 30
579250000L,     // 31
585250000L,     // 32
591250000L,     // 33
597250000L,     // 34
603250000L,     // 35
609250000L,     // 36
615250000L,     // 37
621250000L,     // 38
627250000L,     // 39
633250000L,     // 40
639250000L,     // 41
645250000L,     // 42
651250000L,     // 43
657250000L,     // 44
663250000L,     // 45
669250000L,     // 46
675250000L,     // 47
681250000L,     // 48
687250000L,     // 49
693250000L,     // 50
699250000L,     // 51
705250000L,     // 52
711250000L,     // 53
717250000L,     // 54
723250000L,     // 55
729250000L,     // 56
735250000L,     // 57
741250000L,     // 58
747250000L,     // 59
753250000L,     // 60
759250000L,     // 61
765250000L,     // 62
END

5.1. 9.2 일본의 케이블 테레비 할당

F_JAP_CABLE RCDATA
BEGIN
1L,             // 최소 채널
113L,           // 최대 채널

91250000L,      // 1
97250000L,      // 2
103250000L,     // 3
109250000L,     // 4
115250000L,     // 5
121250000L,     // 6
127250000L,     // 7
133250000L,     // 8
139250000L,     // 9
145250000L,     // 10
151250000L,     // 11
157250000L,     // 12
165250000L,     // 13
171250000L,     // 14
177250000L,     // 15
183250000L,     // 16
189250000L,     // 17
193250000L,     // 18
199250000L,     // 19
205250000L,     // 20
211250000L,     // 21
217250000L,     // 22
223250000L,     // 23
231250000L,     // 24
237250000L,     // 25
243250000L,     // 26
249250000L,     // 27
253250000L,     // 28
259250000L,     // 29
265250000L,     // 30
271250000L,     // 31
277250000L,     // 32
283250000L,     // 33
289250000L,     // 34
295250000L,     // 35
301250000L,     // 36
307250000L,     // 37
313250000L,     // 38
319250000L,     // 39
325250000L,     // 40
331250000L,     // 41
337250000L,     // 42
343250000L,     // 43
349250000L,     // 44
355250000L,     // 45
361250000L,     // 46
367250000L,     // 47
373250000L,     // 48
379250000L,     // 49
385250000L,     // 50
391250000L,     // 51
397250000L,     // 52
403250000L,     // 53
409250000L,     // 54
415250000L,     // 55
421250000L,     // 56
427250000L,     // 57
433250000L,     // 58
439250000L,     // 59
445250000L,     // 60
451250000L,     // 61
457250000L,     // 62
463250000L,     // 63

471250000L,     // 테스트
477250000L,     // 테스트
483250000L,     // 테스트
489250000L,     // 테스트
495250000L,     // 테스트
501250000L,     // 테스트
507250000L,     // 테스트
513250000L,     // 테스트
519250000L,     // 테스트
525250000L,     // 테스트
531250000L,     // 테스트
537250000L,     // 테스트
543250000L,     // 테스트
549250000L,     // 테스트
555250000L,     // 테스트
561250000L,     // 테스트
567250000L,     // 테스트
573250000L,     // 테스트
579250000L,     // 테스트
585250000L,     // 테스트
591250000L,     // 테스트
597250000L,     // 테스트
603250000L,     // 테스트
609250000L,     // 테스트
615250000L,     // 테스트
621250000L,     // 테스트
627250000L,     // 테스트
633250000L,     // 테스트
639250000L,     // 테스트
645250000L,     // 테스트
651250000L,     // 테스트
657250000L,     // 테스트
663250000L,     // 테스트
669250000L,     // 테스트
675250000L,     // 테스트
681250000L,     // 테스트
687250000L,     // 테스트
693250000L,     // 테스트
699250000L,     // 테스트
705250000L,     // 테스트
711250000L,     // 테스트
717250000L,     // 테스트
723250000L,     // 테스트
729250000L,     // 테스트
735250000L,     // 테스트
741250000L,     // 테스트
747250000L,     // 테스트
753250000L,     // 테스트
759250000L,     // 테스트
765250000L,     // 테스트
END

5.1. 10 뉴질랜드

뉴질랜드의 방송의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하고 있다. 케이블 테레비의 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다.

5.1. 10.1 뉴질랜드의 방송 할당

F_NZ__BROAD RCDATA
BEGIN
1L,              // 최소 채널
11L,             // 최대 채널

45250000L,       // 1
55250000L,       // 2
62250000L,       // 3
175250000L,      // 4
182250000L,      // 5
189250000L,      // 6
196250000L,      // 7
203250000L,      // 8
210250000L,      // 9
217250000L,      // 10
224250000L,      // 11
END

5.1. 10.2 뉴질랜드의 케이블 테레비 할당

표준화 된 케이블 테레비 구성에 대응하는 데이터가 없기 때문에,Unicable 주파수 테이블 (아래를 참조)이 사용된다.

5.1. 11 NTSC (아메리카 합중국)

NTSC 의 테이블은, NTSC 방식의 채널 구성을 사용하고 있는 모든 로케일에 해당한다. 방송 및 케이블 테레비의 양쪽 모두의 구성이 표준화 되고 있어, 안정되어 있다. 또, 주파수 인덱스는, 채널 번호의 용도에 적절하고 있다.

5.1. 11.1 NTSC 의 방송 할당

F_USA_BROAD RCDATA
BEGIN
2L,              // 최소 채널
69L,             // 최대 채널

55250000L,       // 2
61250000L,       // 3
67250000L,       // 4
77250000L,       // 5
83250000L,       // 6
175250000L,      // 7
181250000L,      // 8
187250000L,      // 9
193250000L,      // 10
199250000L,      // 11
205250000L,      // 12
211250000L,      // 13
471250000L,      // 14
477250000L,      // 15
483250000L,      // 16
489250000L,      // 17
495250000L,      // 18
501250000L,      // 19
507250000L,      // 20
513250000L,      // 21
519250000L,      // 22
525250000L,      // 23
531250000L,      // 24
537250000L,      // 25
543250000L,      // 26
549250000L,      // 27
555250000L,      // 28
561250000L,      // 29
567250000L,      // 30
573250000L,      // 31
579250000L,      // 32
585250000L,      // 33
591250000L,      // 34
597250000L,      // 35
603250000L,      // 36
609250000L,      // 37
615250000L,      // 38
621250000L,      // 39
627250000L,      // 40
633250000L,      // 41
639250000L,      // 42
645250000L,      // 43
651250000L,      // 44
657250000L,      // 45
663250000L,      // 46
669250000L,      // 47
675250000L,      // 48
681250000L,      // 49
687250000L,      // 50
693250000L,      // 51
699250000L,      // 52
705250000L,      // 53
711250000L,      // 54
717250000L,      // 55
723250000L,      // 56
729250000L,      // 57
735250000L,      // 58
741250000L,      // 59
747250000L,      // 60
753250000L,      // 61
759250000L,      // 62
765250000L,      // 63
771250000L,      // 64
777250000L,      // 65
783250000L,      // 66
789250000L,      // 67
795250000L,      // 68
801250000L,      // 69
END

5.1. 11.2 NTSC 의 케이블 테레비 할당

F_USA_CABLE RCDATA
BEGIN
1L,              // 최소 채널
158L,            // 최대 채널

73250000L,       // 1
55250000L,       // 2
61250000L,       // 3
67250000L,       // 4
77250000L,       // 5
83250000L,       // 6
175250000L,      // 7
181250000L,      // 8
187250000L,      // 9
193250000L,      // 10
199250000L,      // 11
205250000L,      // 12
211250000L,      // 13
121250000L,      // 14
127250000L,      // 15
133250000L,      // 16
139250000L,      // 17
145250000L,      // 18
151250000L,      // 19
157250000L,      // 20
163250000L,      // 21
169250000L,      // 22
217250000L,      // 23
223250000L,      // 24
229250000L,      // 25
235250000L,      // 26
241250000L,      // 27
247250000L,      // 28
253250000L,      // 29
259250000L,      // 30
265250000L,      // 31
271250000L,      // 32
277250000L,      // 33
283250000L,      // 34
289250000L,      // 35
295250000L,      // 36
301250000L,      // 37
307250000L,      // 38
313250000L,      // 39
319250000L,      // 40
325250000L,      // 41
331250000L,      // 42
337250000L,      // 43
343250000L,      // 44
349250000L,      // 45
355250000L,      // 46
361250000L,      // 47
367250000L,      // 48
373250000L,      // 49
379250000L,      // 50
385250000L,      // 51
391250000L,      // 52
397250000L,      // 53
403250000L,      // 54
409250000L,      // 55
415250000L,      // 56
421250000L,      // 57
427250000L,      // 58
433250000L,      // 59
439250000L,      // 60
445250000L,      // 61
451250000L,      // 62
457250000L,      // 63
463250000L,      // 64
469250000L,      // 65
475250000L,      // 66
481250000L,      // 67
487250000L,      // 68
493250000L,      // 69
499250000L,      // 70
505250000L,      // 71
511250000L,      // 72
517250000L,      // 73
523250000L,      // 74
529250000L,      // 75
535250000L,      // 76
541250000L,      // 77
547250000L,      // 78
553250000L,      // 79
559250000L,      // 80
565250000L,      // 81
571250000L,      // 82
577250000L,      // 83
583250000L,      // 84
589250000L,      // 85
595250000L,      // 86
601250000L,      // 87
607250000L,      // 88
613250000L,      // 89
619250000L,      // 90
625250000L,      // 91
631250000L,      // 92
637250000L,      // 93
643250000L,      // 94
91250000L,       // 95
97250000L,       // 96
103250000L,      // 97
109250000L,      // 98
115250000L,      // 99
649250000L,      // 100
655250000L,      // 101
661250000L,      // 102
667250000L,      // 103
673250000L,      // 104
679250000L,      // 105
685250000L,      // 106
691250000L,      // 107
697250000L,      // 108
703250000L,      // 109
709250000L,      // 110
715250000L,      // 111
721250000L,      // 112
727250000L,      // 113
733250000L,      // 114
739250000L,      // 115
745250000L,      // 116
751250000L,      // 117
757250000L,      // 118
763250000L,      // 119
769250000L,      // 120
775250000L,      // 121
781250000L,      // 122
787250000L,      // 123
793250000L,      // 124
799250000L,      // 125
805250000L,      // 126
811250000L,      // 127
817250000L,      // 128
823250000L,      // 129
829250000L,      // 130
835250000L,      // 131
841250000L,      // 132
847250000L,      // 133
853250000L,      // 134
859250000L,      // 135
865250000L,      // 136
871250000L,      // 137
877250000L,      // 138
883250000L,      // 139
889250000L,      // 140
895250000L,      // 141
901250000L,      // 142
907250000L,      // 143
913250000L,      // 144
919250000L,      // 145
925250000L,      // 146
931250000L,      // 147
937250000L,      // 148
943250000L,      // 149
949250000L,      // 150
955250000L,      // 151
961250000L,      // 152
967250000L,      // 153
973250000L,      // 154
979250000L,      // 155
985250000L,      // 156
991250000L,      // 157
997250000L,      // 158
END

5.1. 12 영국

영국의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다.

5.1. 12.1 영국의 방송 할당

F_UK__BROAD RCDATA
BEGIN
1L,              // 최소 인덱스
69L,             // 최대 인덱스

45750000L,       // 1
53750000L,       // 2
61750000L,       // 3
175250000L,      // 4
183250000L,      // 5
191250000L,      // 6
199250000L,      // 7
207250000L,      // 8
215250000L,      // 9
223250000L,      // 10
231250000L,      // 11

0L,              // 12  미사용
0L,              // 13  미사용
0L,              // 14  미사용
0L,              // 15  미사용
0L,              // 16  미사용
0L,              // 17  미사용
0L,              // 18  미사용
0L,              // 19  미사용
0L,              // 20  미사용

471250000L,      // 21
479250000L,      // 22
487250000L,      // 23
495250000L,      // 24
503250000L,      // 25
511250000L,      // 26
519250000L,      // 27
527250000L,      // 28
535250000L,      // 29
543250000L,      // 30
551250000L,      // 31
559250000L,      // 32
567250000L,      // 33
575250000L,      // 34
583250000L,      // 35
591250000L,      // 36
599250000L,      // 37
607250000L,      // 38
615250000L,      // 39
623250000L,      // 40
631250000L,      // 41
639250000L,      // 42
647250000L,      // 43
655250000L,      // 44
663250000L,      // 45
671250000L,      // 46
679250000L,      // 47
687250000L,      // 48
695250000L,      // 49
703250000L,      // 50
711250000L,      // 51
719250000L,      // 52
727250000L,      // 53
735250000L,      // 54
743250000L,      // 55
751250000L,      // 56
759250000L,      // 57
767250000L,      // 58
775250000L,      // 59
783250000L,      // 60
791250000L,      // 61
799250000L,      // 62
807250000L,      // 63
815250000L,      // 64
823250000L,      // 65
831250000L,      // 66
839250000L,      // 67
847250000L,      // 68
855250000L,      // 69

END

영국의 케이블 테레비 할당

F_UK__CABLE RCDATA
BEGIN
1L,              // 최소 인덱스
107L,            // 최대 인덱스

48250000L,       // 1    E2
49750000L,       // 2    E2A
55250000L,       // 3    E3
62250000L,       // 4    E4
69250000L,       // 5    S01
76250000L,       // 6    S02
83250000L,       // 7    S03
90250000L,       // 8    S04
97250000L,       // 9    S05
105250000L,      // 10   S1
112250000L,      // 11   S2
119250000L,      // 12   S3
126250000L,      // 13   S4
133250000L,      // 14   S5
140250000L,      // 15   S6
147250000L,      // 16   S7
154250000L,      // 17   S8
161250000L,      // 18   S9
168250000L,      // 19   S10
175250000L,      // 20   E5
182250000L,      // 21   E6
189250000L,      // 22   E7
196250000L,      // 23   E8
203250000L,      // 24   E9
210250000L,      // 25   E10
217250000L,      // 26   E11
224250000L,      // 27   E12
231250000L,      // 28   S11
238250000L,      // 29   S12
245250000L,      // 30   S13
252250000L,      // 31   S14
259250000L,      // 32   S15
266250000L,      // 33   S16
273250000L,      // 34   S17
280250000L,      // 35   S18
287250000L,      // 36   S19
294250000L,      // 37   S20
303250000L,      // 38   S21
311250000L,      // 39   S22
319250000L,      // 40   S23
327250000L,      // 41   S24
335250000L,      // 42   S25
343250000L,      // 43   S26
351250000L,      // 44   S27
359250000L,      // 45   S28
367250000L,      // 46   S29
375250000L,      // 47   S30
383250000L,      // 48   S31
391250000L,      // 49   S32
399250000L,      // 50   S33
407250000L,      // 51   S34
415250000L,      // 52   S35
423250000L,      // 53   S36
431250000L,      // 54   S37
439250000L,      // 55   S38
447250000L,      // 56   S39
455250000L,      // 57   S40
463250000L,      // 58   S41

471250000L,      // 59
479250000L,      // 60
487250000L,      // 61
495250000L,      // 62
503250000L,      // 63
511250000L,      // 64
519250000L,      // 65
527250000L,      // 66
535250000L,      // 67
543250000L,      // 68
551250000L,      // 69
559250000L,      // 70
567250000L,      // 71
575250000L,      // 72
583250000L,      // 73
591250000L,      // 74
599250000L,      // 75
607250000L,      // 76
615250000L,      // 77
623250000L,      // 78
631250000L,      // 79
639250000L,      // 80
647250000L,      // 81
655250000L,      // 82
663250000L,      // 83
671250000L,      // 84
679250000L,      // 85
687250000L,      // 86
695250000L,      // 87
703250000L,      // 88
711250000L,      // 89
719250000L,      // 90
727250000L,      // 91
735250000L,      // 92
743250000L,      // 93
751250000L,      // 94
759250000L,      // 95
767250000L,      // 96
775250000L,      // 97
783250000L,      // 98
791250000L,      // 99
799250000L,      // 100
807250000L,      // 101
815250000L,      // 102
823250000L,      // 103
831250000L,      // 104
839250000L,      // 105
847250000L,      // 106
855250000L,      // 107

END

5.1. 13 서유럽

서유럽의 테이블에 포함되어 있는 주파수 인덱스는, 채널 번호의 용도에 적절하지 않았다.

5.1. 13.1 서유럽의 방송 할당

F_WEU_BROAD RCDATA
BEGIN
1L,              // 최소 인덱스
69L,             // 최대 인덱스

48250000L,       // 2
49750000L,       // 2A
55250000L,       // 3
62250000L,       // 4
175250000L,      // 5
182250000L,      // 6
189250000L,      // 7
196250000L,      // 8
203250000L,      // 9
210250000L,      // 10
217250000L,      // 11
224250000L,      // 12

0L,              // 13 미사용
0L,              // 14 미사용
0L,              // 15 미사용
0L,              // 16 미사용
0L,              // 17 미사용
0L,              // 18 미사용
0L,              // 19 미사용
0L,              // 20 미사용

471250000L,      // 21
479250000L,      // 22
487250000L,      // 23
495250000L,      // 24
503250000L,      // 25
511250000L,      // 26
519250000L,      // 27
527250000L,      // 28
535250000L,      // 29
543250000L,      // 30
551250000L,      // 31
559250000L,      // 32
567250000L,      // 33
575250000L,      // 34
583250000L,      // 35
591250000L,      // 36
599250000L,      // 37
607250000L,      // 38
615250000L,      // 39
623250000L,      // 40
631250000L,      // 41
639250000L,      // 42
647250000L,      // 43
655250000L,      // 44
663250000L,      // 45
671250000L,      // 46
679250000L,      // 47
687250000L,      // 48
695250000L,      // 49
703250000L,      // 50
711250000L,      // 51
719250000L,      // 52
727250000L,      // 53
735250000L,      // 54
743250000L,      // 55
751250000L,      // 56
759250000L,      // 57
767250000L,      // 58
775250000L,      // 59
783250000L,      // 60
791250000L,      // 61
799250000L,      // 62
807250000L,      // 63
815250000L,      // 64
823250000L,      // 65
831250000L,      // 66
839250000L,      // 67
847250000L,      // 68
855250000L,      // 69

END

5.1. 13.2 서유럽의 케이블 테레비 할당

일부의 나라에 대해서는, 표준화 된 케이블 테레비 구성에 대응하는 데이터가 있다. 채널 구성 데이터가 보고되어 있지 않은 나라에서는,Unicable 주파수 테이블 (아래를 참조)이 사용된다.

F_WEU_CABLE RCDATA
BEGIN
1L,              // 최소 인덱스
107L,            // 최대 인덱스

48250000L,       // 1    E2
49750000L,       // 2    E2A
55250000L,       // 3    E3
62250000L,       // 4    E4
69250000L,       // 5    S01
76250000L,       // 6    S02
83250000L,       // 7    S03
90250000L,       // 8    S04
97250000L,       // 9    S05
105250000L,      // 10   S1
112250000L,      // 11   S2
119250000L,      // 12   S3
126250000L,      // 13   S4
133250000L,      // 14   S5
140250000L,      // 15   S6
147250000L,      // 16   S7
154250000L,      // 17   S8
161250000L,      // 18   S9
168250000L,      // 19   S10
175250000L,      // 20   E5
182250000L,      // 21   E6
189250000L,      // 22   E7
196250000L,      // 23   E8
203250000L,      // 24   E9
210250000L,      // 25   E10
217250000L,      // 26   E11
224250000L,      // 27   E12
231250000L,      // 28   S11
238250000L,      // 29   S12
245250000L,      // 30   S13
252250000L,      // 31   S14
259250000L,      // 32   S15
266250000L,      // 33   S16
273250000L,      // 34   S17
280250000L,      // 35   S18
287250000L,      // 36   S19
294250000L,      // 37   S20
303250000L,      // 38   S21
311250000L,      // 39   S22
319250000L,      // 40   S23
327250000L,      // 41   S24
335250000L,      // 42   S25
343250000L,      // 43   S26
351250000L,      // 44   S27
359250000L,      // 45   S28
367250000L,      // 46   S29
375250000L,      // 47   S30
383250000L,      // 48   S31
391250000L,      // 49   S32
399250000L,      // 50   S33
407250000L,      // 51   S34
415250000L,      // 52   S35
423250000L,      // 53   S36
431250000L,      // 54   S37
439250000L,      // 55   S38
447250000L,      // 56   S39
455250000L,      // 57   S40
463250000L,      // 58   S41

471250000L,      // 59
479250000L,      // 60
487250000L,      // 61
495250000L,      // 62
503250000L,      // 63
511250000L,      // 64
519250000L,      // 65
527250000L,      // 66
535250000L,      // 67
543250000L,      // 68
551250000L,      // 69
559250000L,      // 70
567250000L,      // 71
575250000L,      // 72
583250000L,      // 73
591250000L,      // 74
599250000L,      // 75
607250000L,      // 76
615250000L,      // 77
623250000L,      // 78
631250000L,      // 79
639250000L,      // 80
647250000L,      // 81
655250000L,      // 82
663250000L,      // 83
671250000L,      // 84
679250000L,      // 85
687250000L,      // 86
695250000L,      // 87
703250000L,      // 88
711250000L,      // 89
719250000L,      // 90
727250000L,      // 91
735250000L,      // 92
743250000L,      // 93
751250000L,      // 94
759250000L,      // 95
767250000L,      // 96
775250000L,      // 97
783250000L,      // 98
791250000L,      // 99
799250000L,      // 100
807250000L,      // 101
815250000L,      // 102
823250000L,      // 103
831250000L,      // 104
839250000L,      // 105
847250000L,      // 106
855250000L,      // 107
END

5.1. 14 Unicable

양이 많기 때문에, Unicable 테이블은 여기에 기재되지 않았다. Unicable 테이블의 목표는, 1 개의 테이블에 주파수의 포괄적인 집합, 즉, 다른 모든 테이블과 실제의 조사에 근거하는 데이터를 포함하는 것으로, 주파수 스펙트럼 전체에 걸쳐서 직선적인 검색을 실시하지 않아도, 자동적으로 채널 스캔을 실시할 수 있도록(듯이) 하는 것이다. 이 테이블에 포함되지 않은 주파수에 대해서는, 소비자가 독자적인 유저 인터페이스를 사용해 입력할 필요가 있어, 그 결과는, 레지스트리에 주파수 오버라이드(override) 엔트리로서 등록된다 (전의 섹션 0 을 참조).

5.2 국 할당

1 번째의 수치는, 국제전화 다이얼 규격으로 정해져 있는 나라 코드이다. 이 나라 코드 번호를 IAMTVTuner::put_CountryCode 메소드에 건네주는 것에 의해, 컬러 텔레비전 방식 및 디폴트의 주파수 매핑을 선택할 수가 있다.

RCDATA_COUNTRYLIST RCDATA

BEGIN

1,   F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,
// 아메리카 합중국
// 앙이라
// 안티그아
// 바하마
// 발바도스
// 버뮤다스
// 영령 버진제도
// 캐나다
// 케이만 제도
// 도미니카
// 도미니카 공화국
// 그라나다
// 자메이카
// 몬트세라트
// 네비스
// 센트킷트
// 센트빈센토그레나딘
// 트리니다드 토바고
// 타크스안드케이코스 제도
// 바르브다
// 푸에르 토르코
// 센트 루시아
// 미 령 버진제도

2,   F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 캐나다 (WIN.INI 는 이 일국용의 더미이다)

20,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 이집트
212, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_B,     // 모로코
213, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 알제리아
216, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 튀니지
218, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 리비아
220, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 감비아
221, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 세네갈 공화국
222, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_B,     // 모리타니아
223, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // 마리
224, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // 기니
225, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_K,     // 코트디부아르
226, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // 부르키나파소
227, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 니제르
228, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 토고
229, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 베냉
230, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 모리셔스
231, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 리베리아
232, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 시에라레오네
233, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 가나
234, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 나이지리아
235, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 차드
236, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 중앙아프리카 공화국
237, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 카메룬
238, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_FIX___,      // 카보베르데 제도
239, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 산토메이프린시페
240, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_B,     // 적도 기니아
241, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 가봉
242, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_D,     // 콩고
243, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 콩고 민주공화국
244, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_PAL_I,       // 앙골라
245, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_FIX___,      // 기니아비사우
246, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 디에고 갈시아
247, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 아센션섬
248, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 세이셸 제도
249, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 수단
250, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B, ,      // 르완다
251, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 에치오피아
252, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 소말리아
253, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 지부티
254, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 케냐
255, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 탄자니아
256, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 우간다
257, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_K,     // 부룬디
258, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_PAL_B,       // 모잔비크
260, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 잠비아
261, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 마다가스카르
262, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 레유니온섬
263, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 진바브웨
264, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_I,       // 나미비아
265, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Malawi
266, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_I,       // 레소토
267, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // 보츠와나
268, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 스와질란드
269, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // 마욧트섬
269, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 코모로
27,  F_UNI_CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // 남아프리카
290, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // St Helena
291, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 에리트레아
297, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 아르바
298, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 파로에 제도
299, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 그린 랜드
30,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 그리스
31,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 네델란드
32,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 벨기에
33,  F_UNI_CABLE, F_FRA_BROAD, AnalogVideo_SECAM_L,     // 프랑스
34,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 스페인
350, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 지브랄타
351, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 포르투갈
352, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 룩셈부르크
353, F_UNI_CABLE, F_IRE_BROAD, AnalogVideo_PAL_I,       // 아일랜드
354, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 아이슬랜드
355, F_UNI_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // 알바니아
356, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 몰타
357, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 사이프러스
358, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 핀란드
359, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 불가리아
36,  F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 헝가리
370, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 리투아니아
371, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_D,     // 라트비아
372, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 에스토니아
373, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Moldavia
374, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 아르메니아
375, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 벨라루스
376, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 안도라
377, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_G,     // 모나코
378, F_UNI_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // 산마리노
380, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 우크라이나
381, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 유고슬라비아
385, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 크로아티아
386, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 슬로베니아
387, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 보스니아-헤르체고비나
389, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 마케도니아· 구유고스라비아 공화국
39,  F_UNI_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // 이탈리아
39,  F_UNI_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // 바티칸시국
40,  F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_PAL_D,       // 루마니아
41,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 스위스
41,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 리히텐슈타인
420, F_UNI_CABLE, F_CZE_BROAD, AnalogVideo_PAL_D,       // 체코 공화국
421, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 슬로바키아 공화국
43,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 오스트리아
44,  F_UK__CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // 영국
45,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 덴마크
46,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 스웨덴
47,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 노르웨이
48,  F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_PAL_B,       // 폴란드
49,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 독일
500, F_UNI_CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // 포크랜드 제도
501, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 벨리즈
502, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 과테말라
503, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 엘살바도르
504, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 온두라스
505, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 니카라과
506, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 코스타리카
507, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 파나마
508, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 산피에르섬·미크론섬
509, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 하이티
51,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 페루
52,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 멕시코
53,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 쿠바
53,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 그안타나모만
54,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // 아르헨티나
55,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_M,       // 브라질
56,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 칠레
57,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 콜롬비아
58,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 베네주엘라
590, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 그아드르프
590, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 불령 안티르 제도
591, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // 볼리비아
592, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 가이아나
593, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 에콰도르
594, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 불령 기아나
595, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // 파라과이
596, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 마르치니크
597, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Suriname
598, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // 우루과이
599, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 오란다쀌안티르
60,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 말레이지아
61,  F_UNI_CABLE, F_OZ__BROAD, AnalogVideo_PAL_B,       // 오스트레일리아
61,  F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 코코스키링 제도
62,  F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 인도네시아
63,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 필리핀
64,  F_UNI_CABLE, F_NZ__BROAD, AnalogVideo_PAL_B,       // 뉴질랜드
65,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 싱가폴
66,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 타이
670, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 사이판섬
670, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 로타섬
670, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 티니안섬
671, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 괌
672, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 크리스마스섬
672, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 남극 오스트레일리아령
672, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 노우 포크섬
673, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 브루나이
674, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Nauru
675, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 파푸아뉴기니
676, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 통가
677, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 솔로몬 제도
678, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 바누아뜨
679, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 피지
680, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 팔라우
681, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // 와리스·후테나 제도
682, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 쿡제도
683, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 니웨
684, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 미 령 사모아
685, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 서사모아
686, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 키리바시 공화국
687, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // New Caledonia
688, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 트발
689, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 불령 폴리네시아
690, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 트케라우
691, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 미크로네시아
692, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 마셜 제도
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 러시아
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 카자흐스탄
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 키르기스스탄
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 타지키스탄
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 트르크메니스탄
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 우즈베키스탄

81,  F_JAP_CABLE, F_JAP_BROAD, AnalogVideo_NTSC_M_J,    // 일본

82,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 한국
84,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 베트남
850, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 북한
852, F_UNI_CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // 홍콩
853, F_UNI_CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // 마카오
855, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 캄보디아
856, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 라오스
86,  F_CHN_CABLE, F_CHN_BROAD, AnalogVideo_PAL_D,       // 중국
871, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (동경대학 서양)
872, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (태평양)
873, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (인도양)
874, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (서대서양)
880, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 방글라데시
886, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 대만, 중화 민국
90,  F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 터키
91,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 인도
92,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 파키스탄
93,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 아프가니스탄
94,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 스리랑카
95,  F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 미얀마
960, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 몰디브
961, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 레바논
962, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 요르단
963, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 시리아
964, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 이라크
965, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 쿠웨이트
966, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 사우디아라비아
967, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 예멘
968, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 오만
971, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 아랍 수장국 연방
972, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 이스라엘
973, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 바레인
974, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 카타르
975, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 부탄
976, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 몽고
977, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 네팔
98,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // 이란
994, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 아제르바이잔
995, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 그루지야

0,   0,           0,           0  // 제로는 리스트의 말미를 나타낸다

END


멀티미디어 스트리밍

이 항에서는, 소스로부터 어플리케이션에게 건네지는 데이터의 전송과 변환을 자동적으로 네고시에이트 하는, 멀티미디어 스트리밍 인터페이스에 대해 설명한다. 멀티미디어 스트리밍의 데이터 타입, 인터페이스, 및 인터페이스 메소드의 레퍼런스 엔트리를 기재한다. 또, 샘플 코드를 소개해, 각 멀티미디어 스트리밍 컴퍼넌트 오브젝트에 대해, 설명, CLSID, 및 지원 하는 인터페이스를 기재한다.

  • 멀티미디어 스트리밍 아키텍쳐에 대해
  • 멀티미디어 스트리밍 인터페이스의 일람
  • 멀티미디어 스트리밍 레퍼런스
  • 멀티미디어 스트리밍 컴퍼넌트 오브젝트
  • 멀티미디어 스트리밍의 샘플 코드


멀티미디어 스트리밍 아키텍쳐에 대해

여기에서는, 멀티미디어 스트리밍의 아키텍쳐와 소프트웨어 개발자가 툴 또는 어플리케이션으로 스트림을 사용할때의 표준적인 사용법에 대해 설명한다. 또, 데이터 전송의 기반으로서의 스트리밍의 이점, 및 멀티미디어 프로그래밍의 요점 (스트리밍 어플리케이션에서의 데이터 전송, 퍼포먼스의 최적화, 타임 스탬프 처리등)에 대해서도 설명한다. 멀티미디어 스트리밍을 사용하는 프로그래머는, COM 프로그래밍의 개념을 충분히 이해하고 있을 필요가 있다.

이하의 항으로 구성된다.

  • 멀티미디어 스트리밍의 이점
  • 오브젝트의 계층 구조
  • 멀티미디어 스트림 오브젝트와 스트림 샘플의 생성
  • 어플리케이션에서의 멀티미디어 스트림의 사용법
  • 스트림간의 데이터 공유

멀티미디어 스트리밍의 이점

멀티미디어 스트리밍을 사용 하면, 포맷 고유의 프로그램량을 큰폭으로 삭감할 수 있다. 보통, 어플리케이션으로부터 파일이나 하드웨어의 미디어 데이터를 취득하려면 , 데이터 포맷 및 하드웨어 디바이스에 대해 모르는 일이 있어서는 안된다. 접속, 데이터 전송, 필요한 데이터 변환, 및 실제의 데이터 렌더링이나 파일 저장을, 모두 처리할 필요가 있기 때문이다. 포맷 및 디바이스는 그것 그것 미묘하게 다르기 (위해)때문에, 이 처리는 복잡해 번잡한 것이 되는 것이 많다. 대조적으로, 멀티미디어 스트리밍을 사용 하면, 소스로부터 어플리케이션에게 건네지는 데이터의 전송과 변환이 자동적으로 네고시에이트 된다. 스트리밍 인터페이스는, 데이터의 액세스와 제어를 위한 균일하고 알기 쉬운 메소드를 제공한다. 어플리케이션에서는, 이러한 메소드를 사용하는 것에 의해, 소스나 포맷 에 관계없이, 데이터를 간단하게 재생할 수가 있다.

이하의 스텝은, 하드웨어 디바이스로부터 렌더링 재생에의 스트리밍의 이행 방법을 나타낸다.

  1. 비디오 데이터의 소스 (Microsoft® DirectShow® 등)가, 스트리밍 인터페이스를 공개한다.
  2. 어플리케이션 개발자가, 멀티미디어 스트리밍 인터페이스를 사용해, 데이터 포맷을 변환한다.
  3. 어플리케이션 개발자가, Microsoft DirectDraw® 인터페이스를 사용해, 얻을 수 있던 데이터를 렌더링 한다.

멀티미디어 스트림의 사양은, 복수의 인터페이스로부터 구성되어 각 인터페이스는, 스트림 처리의 특정의 성질을 제어하는 메소드나, 특정의 종류의 데이터를 처리하는 메소드로부터 구성된다. 상세한 것에 대하여는, 「멀티미디어 스트리밍 인터페이스의 일람」을 참조할것.

오브젝트의 계층 구조

다음의 그림은, 멀티미디어 스트리밍에 사용하는 기본적인 오브젝트의 계층 구조를 나타낸다.

오브젝트의 계층 구조

멀티미디어 스트리밍 아키텍쳐에는, 이하의 3 종류의 기본 오브젝트가 정의되고 있다.

  1. IMultiMediaStream 인터페이스를 지원 하는 멀티미디어 스트림.
  2. IMediaStream 인터페이스를 지원 하는 데이터 고유의 미디어 스트림. 모든 멀티미디어 스트림에는, 이 미디어 스트림이 적어도 1 개(살) 포함된다.
  3. 미디어 스트림에 의해 생성 되어IStreamSample 인터페이스를 지원 하는 스트림 샘플. 이 오브젝트는 스트림의 기본적인 처리 단위이다.

멀티미디어 스트림 오브젝트와 스트림 샘플의 생성

IMultiMediaStream 인터페이스를 지원 하는 오브젝트는, 멀티미디어 데이터 스트림을 위한 기본적인 컨테이너이다. IMultiMediaStream 인터페이스에는, 오브젝트의 데이터 스트림을 열거하는 메소드가 포함된다. 이러한 스트림에는, 보통, 비디오 데이터 및 오디오 데이터가 포함되지만, 자막 방송, plaintext, SMPTE 타임 코드등의 임의의 포맷의 데이터를 포함할 수가 있다. IMultiMediaStream 인터페이스는 범용 컨테이너이지만, 개발자는 이 인터페이스로부터 특정의 데이터 포맷을 지원 하는 별버젼의 인터페이스를 생성 할 수 있다. 예를 들어,IAMMultiMediaStream 인터페이스를 이행 하는 오브젝트는, DirectShow 의 임의의 데이터 포맷을 가지는 스트림을 열거 및 제어할 수 있다. 개개의 데이터 스트림은 포맷 고유해서, 이러한 오브젝트는, 다른 인터페이스를 적어도 2 개(살) (범용 인터페이스와 데이터 고유의 인터페이스) 지원 한다. 모든 스트림은, 그 포맷과 스트림 자체에의 포인터를 취득하는 메소드를 제공하는 IMediaStream 인터페이스를 지원 한다. 한편,IDirectDrawMediaStream 인터페이스에는, 비디오 데이터의 렌더링을 전문에 처리하는 메소드가 포함된다. IMultiMediaStream 로부터 파생하는 모든 인터페이스는, 스트림 샘플 (데이터 스트리밍의 기본 단위)의 생성도 지원 한다.

멀티미디어 샘플은, 미디어 데이터가 저장 된 오브젝트에의 참조이다. 비디오 이미지에서는, 이것이 DirectDraw 표면이 된다. 샘플의 정확한 내용은, 미디어의 종류 (사운드나 텍스트등)에 따라서 다르다. 샘플은 데이터 오브젝트에의 단순한 참조이므로, 임의의 수의 스트림 샘플로부터 1 개의 샘플 오브젝트를 참조할것이 생긴다. IStreamSample 인터페이스는, 샘플의 특성 (시작 타임, 종료 타임, 상태, 및 스트림과의 관련)을 취득 및 설정하는 메소드를 제공한다. IStreamSample::Update 메소드는, 스트림이 읽어내 가능하면, 샘플의 데이터에 최신 상태를 반영한다. 또, 스트림이 기입해 가능하면, 샘플의 데이터를 스트림에 기입한다. 보통,Update 메소드는, 스트리밍 데이터를 렌더링, 전송, 또는 저장 하는 루프로 사용한다.

어플리케이션에서의 멀티미디어 스트림의 사용법

멀티미디어 스트리밍 인터페이스는, 하드웨어 소스 또는 소프트웨어 소스의 특정의 특성에의 의존성을 배제해, Microsoft DirectX® 의 전미디어 포맷의 지원을 제공하는 것으로써, 멀티미디어 데이터의 처리를 큰폭으로 단순화 한다. 스트림에 의해 데이터가 매우 높은 레벨까지 추상화 되기 (위해)때문에, 어플리케이션에서는, 포맷을 전혀 의식하지 않고 , 데이터를 다른 스트림으로 이동할 수 있다.

멀티미디어 스트림을 생성 하려면 , 이하의 스텝을 실행한다.

  1. 멀티미디어 스트림을 생성 한다. 스트림을 생성 및 초기화하는 메소드는, 아키텍쳐 고유하다. DirectShow 은, 스트림의 초기화에 사용하는 IAMMultiMediaStream 인터페이스를 지원 한다. IMultiMediaStream 의 그 외의 인 프로세스 서버 이행은, 다른 메카니즘을 사용해 생성 및 초기화된다.
  2. 멀티미디어 스트림 오브젝트를 초기화한 후, 어플리케이션에서는,QueryInterface 를 사용해 그 오브젝트에 대응하는 IMultiMediaStream 인터페이스를 취득한다. 이 인터페이스를 사용해, 스트림의 프로퍼티를 판단해, 스트림 자체를 열거한다. 개개의 스트림을 취득하려면 , 목적 ID 를 지정해 IMultiMediaStream::GetMediaStream 메소드를 호출한다. 비디오의 프라이머리 스트림을 나타내는 MSPID_PrimaryVideo 와 오디오의 프라이머리 스트림을 나타내는 MSPID_PrimaryAudio 는, 가장 자주(잘) 사용되는 목적 ID 이다.
  3. IUnknown::QueryInterface 를 호출해, 스트림의 미디어 타입에 고유의 인터페이스를 조회한다. 예를 들어, 비디오 스트림을 렌더링 하려면 , 그 IDirectDrawMediaStream 인터페이스를 취득한다. 미디어 고유의 인터페이스에는, 포맷의 능력을 충분히 꺼내기 위해서(때문에) 필요한 추가 메소드가 정의되고 있다.
  4. 스트림 데이터로부터 1 개 이상의 샘플을 생성 한다. 모든 미디어 스트림은, 샘플을 생성 하는 IMediaStream::CreateSharedSample 메소드를 지원 한다. 생성 된 샘플은, 샘플과 그 특성의 제어를 제공하는 IStreamSample 인터페이스를 지원 한다. 보통, 미디어 스트림에서는, 이 IStreamSample 메소드보다 강력한 포맷 고유의 샘플 생성 메소드가 지원 된다. 예를 들어,IDirectDrawMediaStream 에서는, 희망의 DirectDraw 표면 및 클리핑 직사각형에 어태치 된 샘플을 생성 할 수 있다. 다만, 상황에 따라서는, 데이터의 포맷을 알지 못하고 데이터를 처리해야 하는 것이 있다. 포맷에 의존하지 않는 방법으로 데이터를 스트림 하려면 ,IMediaStream::CreateSharedSample 메소드를 사용해 데이터 샘플을 생성 한다.
  5. 희망의 스트림 샘플을 모두 생성 한 후, 파라미터에 STREAMSTATE_RUN 플래그를 지정해 IMultiMediaStream::SetState 메소드를 호출하는 것으로, 스트림을 시작 한다.
  6. IStreamSample::Update 를 호출해 스트림 샘플을 갱신한다. IStreamSample::Update 메소드가 종료 하면, 샘플의 데이터에 액세스 할 수 있다. 갱신으로부터 돌아왔을 때에 특정의 이벤트를 발행하는지, 또는 특정의 함수를 호출하려면 ,IStreamSample::Update 메소드에 적절한 포인터를 건네준다.

멀티미디어 스트리밍 인터페이스의 상세한 것에 대하여는, 「멀티미디어 스트리밍」을 참조할것.

스트림간의 데이터 공유

멀티미디어 데이터의 처리에는, 보통, 대량의 system resource가 필요하게 된다. 따라서, 데이터의 카피는 할 수 있는 한 피하지 않으면 안 된다. 스트리밍 아키텍쳐는, 데이터를 카피에 다른 스트림으로 이동하기 위한 메카니즘인, 공유 스트림 샘플을 지원 한다. 이 버퍼를 사용 하면, 기반이 되는 데이터 포맷이 전송처 스트림으로 명확하게 지원되어 있지 않아도, 2 개의 스트림간에 효율적으로 데이터를 전송 할 수 있다.

예를 들어, 3 개의 데이터 스트림 (비디오, 오디오, 및 비디오 컨텐츠에 대응하는 타임 스탬프가 들어간 URL 데이터)을 가지는 멀티미디어 스트림이 있어, 비디오 프레임 모두에게 저작권 표기를 추가해, 보존을 위해서(때문에) 데이터를 다른 스트림에 기입하는 어플리케이션을 생성 하고 싶지만, 어플리케이션이 비디오 스트림 이외의 데이터 포맷을 이해할 수 없는 것과 상정한다. 비디오 스트림에 대해, 희망의 DirectDraw 표면에 어태치 된 샘플을 생성 한다. 다음에, 같은 표면에의 포인터를 지정해 IDirectDrawMediaStream::CreateSample 메소드를 호출하는지, 또는 IMediaStream::CreateSharedSample 를 호출해, 출력 스트림을 생성 한다. 어느 쪽의 경우도, 입력 스트림과 출력 스트림은 DirectDraw 표면을 공유한다. 비디오 포맷은 이해할 수 있으므로, 이 표면에는 필요에 따라서 액세스 할 수가 있다.

그 외의 소스 스트림 포인터 (오디오 및 URL)를 취득하려면 , 소스 컨테이너 스트림을 열거해, 비디오 이외의 스트림에의 포인터를 파악한다. 이러한 각 소스 스트림에는, 출력 스트림 컨테이너내의 출력 스트림을 관련지을 수 있고 있다. 소스 스트림 포인터 각각 붙어, 출력 컨테이너 위에의 IMultiMediaStream::GetMediaStream 메소드를 호출해 이러한 출력 포인터를 취득한다. 이 처리는 이하의 스텝에서 행해진다.

  1. IMultiMediaStream::EnumMediaStreams 를 호출해 소스 스트림에의 포인터를 취득한다. 비디오 스트림의 포맷은 이미 이해하고 있으므로, 비디오 스트림이 아닌 것을 확인한다.
  2. 스텝 1 으로 얻을 수 있던 포인터를 지정해 출력 컨테이너 스트림 위에의 IMultiMediaStream::GetMediaStream 를 호출한다. 목적의 출력 스트림에의 포인터가 돌려주어진다.
  3. 소스 스트림 위에의 AllocateSample 를 호출한다.
  4. 출력 스트림 위에의 CreateSharedSample 를 호출한다.
  5. 소스 스트림 위에의 Update 를 호출해 데이터를 읽어낸다.
  6. 출력 스트림 위에의 Update 를 호출해 데이터를 기입한다.

포맷을 지원 하지 않는 스트림 각각 붙어, 이러한 스텝을 반복한다. 양쪽 모두의 샘플이 갱신을 종료 하면, 소스 스트림의 데이터가 모두 출력 스트림에게 건네져 처리가 완료한다.


멀티미디어 스트리밍 인터페이스의 일람

멀티미디어 스트리밍은, 다수의 인터페이스로부터 성립되고 있다. 여기에서는, 개개의 인터페이스에 대해 간단하게 설명한다. 멀티미디어 스트리밍의 상세한 것에 대하여는, 「멀티미디어 스트리밍 아키텍쳐에 대하며」를 참조할것.

이하의 항으로 구성된다.

  • 기본의 멀티미디어 스트리밍 인터페이스
  • DirectDraw 스트리밍 인터페이스
  • 오디오 스트리밍 인터페이스
  • DirectShow 멀티미디어 스트리밍 인터페이스

기본의 멀티미디어 스트리밍 인터페이스

기본의 멀티미디어 스트리밍 인터페이스는, 멀티미디어 스트림에 액세스하기 위한 1 개의 프로그램 수단이다. 다만, 기본 인터페이스를 사용해 특정 타입의 데이터에 액세스 하는 경우, 데이터를 제어할 수 있는 범위가 어느 정도 제한될 가능성이 있다. 따라서, 미디어 개발자는, 미디어 타입 고유의 능력을 보다 강력하게 제어하기 위해(때문에), 이러한 인터페이스를 기본으로, 파생 인터페이스를 생성 해야 한다.

IMultiMediaStream
최상정도 레벨의 멀티미디어 스트림 오브젝트에의 액세스 방법을 정의한다. 이 오브젝트는, 다른 스트림 오브젝트를 포함해, 그러한 오브젝트에의 액세스를 제공한다. IMultiMediaStream 에는, 스트림의 총시간폭을 확인해, 스트림내의 시크를 실시하는 메소드 뿐만이 아니라, 개개의 스트림을 열거 또는 취득하는 메소드도 준비되어 있다.
IMediaStream
범용의 스트림 오브젝트를 정의한다. 이 인터페이스의 메소드를 사용해, 스트림에의 포인터를 취득해, 스트림에 관한 정보를 취득해, 스트림 데이터로부터 샘플을 생성 한다. 또, 공유 스트림 샘플을 생성 할 수도 있다. 공유 스트림 샘플이란, 샘플의 데이터를 복제하지 않고 복수의 스트림으로부터 액세스 할 수 있는 샘플이다.
IStreamSample
개개의 스트림 샘플의 동작을 제어한다. 샘플을 생성 한 스트림을 취득해, 샘플의 시작 타임, 종료 타임, 및 완료 상태를 확인해, (Update 메소드를 통해서) 샘플 자체에 유저 정의 함수를 실행할 수가 있다. 보통,Update 메소드에서는, 비디오 데이터이면 렌더링 해, 오디오 데이터이면 재생하는 등, 적절한 방법으로 샘플 데이터가 처리된다.

DirectDraw 스트리밍 인터페이스

스트림내에서 Microsoft® DirectDraw® 가 지원 하는 비디오 포맷을 사용하는 경우에는, 이하의 인터페이스를 사용 하면, 범용의 기본 인터페이스보다 강력하게 데이터를 제어할 수 있다.

IDirectDrawMediaStream
미디어 스트림에 관련지을 수 있었던 스트림 포맷 및 DirectDraw 오브젝트를 설정 및 취득한다. 이 인터페이스는 IMediaStream 로부터 파생한다. 이 인터페이스를 사용해, 비디오 샘플을 생성 할 수도 있다.
IDirectDrawStreamSample
이 인터페이스를 사용 하면, DirectDraw 표면에 비디오 샘플을 어태치 할 수 있다. 이 인터페이스는 IStreamSample 인터페이스로부터 파생한다. 렌더링 하기 쉽게하기 위해(때문에), 어태치 된 표면 각각 클리핑 직사각형이 포함된다.

오디오 스트리밍 인터페이스

IAudioMediaStream
오디오 미디어 스트림을 제어한다. 이 인터페이스는,IMediaStream 인터페이스를 계승해, 1 개(살) 이상의 IAudioStreamSample 오브젝트를 생성 하기 위해서 사용된다. 또, 스트림 데이터의 현재의 포맷을 설정 및 취득하기 위해서도 사용된다.
IAudioStreamSample
기반이 되는 IAudioData 데이터 오브젝트로부터 정보를 취득한다.
IMemoryData
오디오 데이터 오브젝트 위에의 메모리 데이터를 설정 및 취득하는 메소드가 포함된다. 오디오 데이터 오브젝트는, 스트림 샘플이 액세스 하는, 기반이 되는 데이터를 제공하는 것이다. 이 인터페이스는, 메모리 버퍼를 초기화해, 실제로 오브젝트내에 있는 오디오 데이터의 양을 설정하는 수단을 제공한다. 또,IMemoryData::GetInfo 메소드를 사용 하면, 오디오 메모리 데이터를 취득할 수 있다.
IAudioData
어플리케이션으로부터, 오디오 스트림으로부터 참조되는, 기반이 되는 오디오 데이터를 설정 및 취득하기 위한 메소드를 제공한다. 오디오 데이터의 포맷은,WAVEFORMATEX 구조체로 설정된다.

DirectShow 멀티미디어 스트리밍 인터페이스

이하의 인터페이스는, 멀티미디어 스트림 개발자에게 Microsoft® DirectShow® 의 기능을 공개한다. 어플리케이션 개발자는, 어플리케이션내에서 IAMMultiMediaStream 인터페이스만을 이행 해야 한다. 다른 2 개의 인터페이스는, DirectShow 가 내부적으로 사용한다.

IAMMultiMediaStream
스트림 및 DirectShow 필터 그래프간의 접속을 제어한다. 이 인터페이스는, 필터 그래프를 인스턴스화해, DirectShow 가 지원 하는 미디어 파일을 열어, 재생용의 적절한 필터 그래프를 생성하는 메소드를 제공한다. 클래스 식별자 CLSID_ActiveMovieMMStream 는, 이 인터페이스를 지원 한다.
IAMMediaStream
멀티미디어 스트림 및 DirectShow 필터 그래프간의 접속의 내부적인 네고시에이션을 처리한다. 이 인터페이스는,IMediaStream 인터페이스로부터 파생한 DirectShow 고유의 인터페이스이다. 어플리케이션으로부터 이 인터페이스를 사용 또는 이행 해서는 안 된다.


멀티미디어 스트리밍 레퍼런스

이 항에는, 모든 멀티미디어 스트리밍 인터페이스 및 그 메소드의 레퍼런스 엔트리를, Microsoft® DirectShow® 가 지원 하는 것도 포함해 기재한다. 또, 인터페이스가 사용하는 멀티미디어 스트리밍 데이터 타입의 일람, 및 메소드가 돌려주는 에러 코드와 성공 코드의 일람도 기재한다.

멀티미디어 스트리밍 인터페이스

  • IAMMediaStream
  • IAMMediaTypeSample
  • IAMMediaTypeStream
  • IAMMultiMediaStream
  • IAudioData
  • IAudioMediaStream
  • IAudioStreamSample
  • IDirectDrawMediaStream
  • IDirectDrawStreamSample
  • IMediaStream
  • IMemoryData
  • IMultiMediaStream
  • IStreamSample

데이터 타입과 return code

  • 멀티미디어 스트리밍 데이터 타입
  • 멀티미디어 스트리밍의 에러 코드와 성공 코드


IAMMediaStream 인터페이스

IAMMediaStream 인터페이스는, 멀티미디어 스트리밍을 사용하는 어플리케이션에서의 Microsoft® DirectShow® 필터와 필터 그래프와의 내부적인 접속을 처리한다. 이 인터페이스를 사용 하면, 소스로부터 어플리케이션에게 건네지는 데이터의 전송과 변환이 자동적으로 네고시에이트 되어 데이터 전송, 데이터 변환, 및 실제의 데이터 렌더링이나 파일 저장을 처리하는 코드를 생성 하지 않고 , 간단하게 데이터를 재생할 수 있다. 이 인터페이스는, 데이터의 액세스와 제어를 위해서(때문에), 균일해 이해하기 쉬운 수단을 제공한다.

이 인터페이스는, 어플리케이션 개발자에 의한 이행 또는 사용을 목적으로 한 것은 아니다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMMediaStream 메소드 | 설명
Initialize | 지정된 스트림 타입 및 목적 ID 를 가지는 새로운 미디어 스트림을 생성 및 초기화한다.
SetState | 필터 상태를 설정한다.
JoinAMMultiMediaStream | 지정된 미디어 스트림을 현재의 멀티미디어 스트림에 추가한다. IAMMultiMediaStream::AddMediaStream 메소드는 이 메소드를 호출한다.
JoinFilter | 기반이 되는 필터 그래프내의 미디어 스트림 필터에 미디어 스트림을 접속한다.
JoinFilterGraph | 미디어 스트림 필터를 필터 그래프에 접속한다.

IAMMediaStream::Initialize

IAMMediaStream 인터페이스

지정된 스트림 타입 및 목적 ID 를 가지는 새로운 미디어 스트림을 생성 및 초기화한다.

구문

HRESULT Initialize(
    IUnknown *pSourceObject,
    DWORD dwFlags,
    REFMSPID PurposeID,
    STREAM_TYPE StreamType
    );

파라미터

pSourceObject
[in] IUnknown 소스 오브젝트에의 포인터.
dwFlags
[in] 미디어 스트림의 동작을 수정하는, 이하의 값을 1 개 이상 조합한 값.
AMMSF_ADDDEFAULTRENDERER | 디폴트의렌더러를 추가한다.
AMMSF_CREATEPEER | pStreamObject 와 같은 오브젝트에 근거하는 피아스트림을 생성 한다.
AMMSF_STOPIFNOSAMPLES | 샘플이 1 개나 생성되어 있지 않은 경우, 또는 마지막 샘플이 삭제되었을 경우에는, 스트림을 종료한다.
AMMSF_NOSTALL | Update 가 불려 가지 않아도 스트림을 실행한다.
PurposeID
[in] 새로운 미디어 스트림의 목적 ID.
StreamType
[in] 새로운 미디어 스트림의 미디어 타입을 지정하는 STREAM_TYPE 열거값.

반환값

성공했을 경우는, S_OK 를 돌려준다. 무효인 필수 파라미터가 있는 경우는, E_POINTER 를 돌려준다.

주의

dwFlags 에 AMMSF_ADDDEFAULTRENDERER 를 지정 하면, 지정된 목적 ID 의 디폴트 렌더러가 생성 된다 (가능한 경우). 현시점에서는, Microsoft® DirectSound® 를 사용하는 오디오의 디폴트 렌더러만이 지원 된다. 이 경우,pStreamObject 파라미터는 NULL 일 필요가 있어,IMultiMediaStream::GetMediaStream 메소드 또는 IMultiMediaStream::EnumMediaStreams 메소드의 호출에서는 스트림이 인식되지 않는다.

dwFlags 에 AMMSF_CREATEPEER 를 지정 하면,pStreamObject 를 사용해 미디어 스트림이 생성 되어 그 미디어 스트림이 현재의 멀티미디어 스트림에 추가된다. pStreamObject 파라미터는 스트림 타입에 따라서 다르다. 보통,pStreamObject 에는 IMediaStream 오브젝트에의 포인터를 지정할 수 있다. 이 경우, 샘플과 같은 목적 ID 및 포맷을 가지는 스트림이 생성 된다. IDirectDraw 스트림의 경우에는,IDirectDraw 오브젝트에의 포인터도 지정할 수 있다.

dwFlags 에 AMMSF_STOPIFNOSAMPLES 를 지정 하면, 스트림이 종료된다.

플래그가 1 개나 세트되어 있지 않은 경우,pStreamObject 는 다음의 몇개의 값을 취한다.
IAMMediaStream 오브젝트 | 이 경우, 이 스트림은 멀티미디어 스트림내의 스트림에 추가된다.
NULL | 이 경우, 디폴트의 IMediaStream 오브젝트가, 기반이 되는 디폴트의 오브젝트를 가지는 스트림에 추가된다 (필요한 경우).
기반이 되는 오브젝트에의 포인터 | 이 포인터를 사용해, 디폴트 스트림이 구축된다. 비디오 스트림의 경우에는,IDirectDraw 포인터의 가능성이 있다.

IAMMediaStream::JoinAMMultiMediaStream

IAMMediaStream 인터페이스

지정된 미디어 스트림을 현재의 멀티미디어 스트림에 추가한다. IAMMultiMediaStream::AddMediaStream 메소드는 이 메소드를 호출한다.

구문

HRESULT JoinAMMultiMediaStream(
    IAMMultiMediaStream *pAMMultiMediaStream
    );

파라미터

pAMMultiMediaStream
[in] 현재의 미디어 스트림을 추가하는 IAMMultiMediaStream 오브젝트에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 미디어 스트림에 이미 할당하고 끝난 스트림 샘플이 있는 경우는, MS_E_SAMPLEALLOC 를 돌려준다.

주의

제공하는 멀티미디어 스트림의 참조 카운트는, 생성시에 처리되고 있으므로, 인크리먼트(increment) 하지 않는 것.

어플리케이션으로부터 이 메소드를 호출하지 않는 것.

IAMMediaStream::JoinFilter

IAMMediaStream 인터페이스

기반이 되는 필터 그래프내의 미디어 스트림 필터에 미디어 스트림을 접속한다.

구문

HRESULT JoinFilter( );

반환값

성공했을 경우는, S_OK 를 돌려준다.

주의

지정하는 미디어 스트림 필터의 참조 카운트는 인크리먼트(increment) 하지 않는 것.

어플리케이션으로부터 이 메소드를 호출하지 않는 것.

IAMMediaStream::JoinFilterGraph

IAMMediaStream 인터페이스

미디어 스트림 필터를 필터 그래프에 접속한다.

구문

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph
    );

파라미터

pGraph
[in] 지정된 필터 그래프에 추가하는 현재의 미디어 스트림 필터에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. pGraph 가 NULL 의 경우는, E_POINTER 를 돌려준다.

주의

지정하는 필터 그래프의 참조 카운트는 인크리먼트(increment) 하지 않는 것.

어플리케이션으로부터 이 메소드를 호출하지 않는 것.

IAMMediaStream::SetState

IAMMediaStream 인터페이스

필터 상태를 설정한다.

구문

HRESULT SetState(
    FILTER_STATE State
    );

파라미터

State
[in] 필터 상태를 설정한다. 상태는 FILTER_STATE 열거형으로 지정된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. State 파라미터가 무효인 경우는, E_INVALIDARG 를 돌려준다.

주의

어플리케이션으로부터 이 메소드를 호출하지 않는 것.


IAMMediaTypeSample 인터페이스

이 인터페이스는, 임의의 미디어 타입의 스트림 샘플을 조작하는 메소드를 제공한다. 이 인터페이스를 공개하는 샘플을 생성 하려면 ,IAMMediaTypeStream::CreateSample 메소드를 호출한다.

이 인터페이스는,IStreamSample 인터페이스를 계승한다.

이 인터페이스의 메소드는,IMediaSample 인터페이스의 메소드에 상당한다. 다만,IAMMediaTypeSample 에는 SetPointer 메소드와 GetPointer 메소드가 더해지고 있다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IStreamSample 메소드 | 설명
GetMediaStream | 현재의 샘플을 생성 한 미디어 스트림 오브젝트에의 포인터를 취득한다.
GetSampleTimes | 현재의 샘플의 시작 타임과 종료 타임을 취득한다.
SetSampleTimes | 현재의 샘플의 시작 타임과 종료 타임을 설정한다.
Update | 현재의 샘플을 동기 또는 비동기에게 갱신한다.
CompletionStatus | 현재의 샘플에 행해진 마지막 비동기 갱신 상태를 취득한다. 갱신이 완료하고 있지 않는 경우에는 강제 종료할 수 있다.
IAMMediaTypeSample 메소드 | 설명
SetPointer | 미디어 샘플의 메모리 버퍼에의 포인터를 설정한다.
GetPointer | 버퍼의 메모리에의 읽어내/기입 포인터를 취득한다.
GetSize | 버퍼의 데이터 영역의 사이즈 (바이트 단위)를 취득한다.
GetTime | 이 샘플이 시작 및 정지해야 할 스트림 타임을 취득한다.
SetTime | 이 샘플이 시작 및 정지해야 할 스트림 타임을 설정한다.
IsSyncPoint | 샘플의 시작이 동기 포인트인가 어떤가를 판단한다.
SetSyncPoint | 이 샘플의 시작이 동기 포인트인가 어떤가를 지정한다.
IsPreroll | 이 샘플이프리로르의 일부인가 어떤가를 판단한다.
SetPreroll | 이것이 프리로르산풀인가 어떤가를 지정한다.
GetActualDataLength | 샘플의 데이터 길이 (바이트 단위)를 취득한다.
SetActualDataLength | 샘플의 데이터 길이를 설정한다.
GetMediaType | 샘플의 미디어 타입을 취득한다.
SetMediaType | 샘플의 미디어 타입을 설정한다.
IsDiscontinuity | 이 샘플이 데이터 스트림의 불연속성을 나타내고 있는지 어떤지를 판단한다.
SetDiscontinuity | 불연속성의 프로퍼티를 설정한다.
GetMediaTime | 이 샘플의 미디어 타임 스탬프를 취득한다.
SetMediaTime | 이 샘플의 미디어 타임 스탬프를 설정한다.

IAMMediaTypeSample::GetActualDataLength

IAMMediaTypeSample 인터페이스

샘플의 데이터 길이 (바이트 단위)를 취득한다.

구문

long GetActualDataLength(void);

반환값

샘플의 데이터 길이 (바이트 단위)를 돌려준다.

IAMMediaTypeSample::GetMediaTime

IAMMediaTypeSample 인터페이스

샘플의 미디어 타임 스탬프를 취득한다.

구문

HRESULT GetMediaTime(
LONGLONG *pTimeStart,
LONGLONG *pTimeEnd
);

파라미터

pTimeEnd
[out] 미디어의 시작 타임을 받는 변수에의 포인터.
pTimeStart
[out] 미디어의 종료 타임을 받는 변수에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_MEDIA_TIME_NOT_SET | 이 샘플에는 미디어 타임 스탬프가 설정되어 있지 않다.

IAMMediaTypeSample::GetMediaType

IAMMediaTypeSample 인터페이스

샘플의 미디어 타입을 취득한다. 포맷이 직전의 샘플로부터 변함없는 경우에는, 샘플에 미디어 타입이 붙지 않을 가능성이 있다.

구문

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

파라미터

ppMediaType
AM_MEDIA_TYPE 구조체를 받는 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

E_OUTOFMEMORY | 메모리 부족.
S_FALSE | 포맷이 직전의 샘플로부터 변함없다.
S_OK | 성공.

IAMMediaTypeSample::GetPointer

IAMMediaTypeSample 인터페이스

버퍼의 메모리에의 읽어내/기입 포인터를 취득한다.

구문

HRESULT GetPointer(
    BYTE **ppBuffer
);

파라미터

ppBuffer
[out] 버퍼에의 포인터의 주소.

반환값

S_OK 를 돌려준다.

IAMMediaTypeSample::GetSize

IAMMediaTypeSample 인터페이스

버퍼의 데이터 영역의 사이즈 (바이트 단위)를 취득한다.

구문

long GetSize(void);

반환값

버퍼의 데이터 영역의 사이즈 (바이트 단위)를 돌려준다.

IAMMediaTypeSample::GetTime

IAMMediaTypeSample 인터페이스

샘플이 시작 및 정지해야 할 스트림 타임을 취득한다.

구문

HRESULT GetTime(
REFERENCE_TIME *pTimeStart,
REFERENCE_TIME *pTimeEnd
);

파라미터

pTimeStart
[out] 시작 타임을 받는 변수에의 포인터.
pTimeEnd
[out] 종료 타임을 받는 변수에의 포인터. 샘플에 종료 타임이 없는 경우, 이 값에는 시작 타임에 1 더한 값이 설정된다.

반환값

다음의 몇개의 값을 돌려준다.

S_OK | 성공.
VFW_E_SAMPLE_TIME_NOT_SET | 샘플에 타임 스탬프가 없다.
VFW_S_NO_STOP_TIME | 샘플에는 유효한 시작 타임이 있지만, 종료 타임이 없다.

IAMMediaTypeSample::IsDiscontinuity

IAMMediaTypeSample 인터페이스

이 샘플이 데이터 스트림의 불연속성을 나타내고 있는지 어떤지를 판단한다.

구문

HRESULT IsDiscontinuity(void);

반환값

샘플이 불연속인 경우는, S_OK 를 돌려준다. 그 이외의 경우는, S_FALSE 를 돌려준다.

IAMMediaTypeSample::IsPreroll

IAMMediaTypeSample 인터페이스

이 샘플이 프리로르의 일부인가 어떤가를 판단한다. 프리로르산풀을 표시해서는 안 된다.

구문

HRESULT IsPreroll(void);

반환값

샘플이 프리로르산풀인 경우는, S_OK 를 돌려준다. 그 이외의 경우는, S_FALSE 를 돌려준다.

IAMMediaTypeSample::IsSyncPoint

IAMMediaTypeSample 인터페이스

샘플의 시작이 동기 포인트인가 어떤가를 판단한다.

구문

HRESULT IsSyncPoint(void);

반환값

샘플의 시작이 동기 포인트인 경우는, S_OK 를 돌려준다. 그 이외의 경우는, S_FALSE 를 돌려준다.

IAMMediaTypeSample::SetActualDataLength

IAMMediaTypeSample 인터페이스

샘플의 데이터 길이를 설정한다.

구문

HRESULT SetActualDataLength(
    long lActual
);

파라미터

lActual
미디어 샘플의 데이터 길이 (바이트 단위).

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 성공.
VFW_E_BUFFER_OVERFLOW | 버퍼의 크기가 부족하다.

IAMMediaTypeSample::SetDiscontinuity

IAMMediaTypeSample 인터페이스

불연속성의 프로퍼티를 설정한다.

구문

HRESULT SetDiscontinuity(
    BOOL bDiscontinuity
);

파라미터

bDiscontinuity
이 샘플이 불연속인가 어떤가를 지정하는 값. 샘플이 직전의 샘플과 불연속인 경우에는 이 값을 TRUE 로 설정해, 그 이외의 경우는 FALSE 로 설정한다.

반환값

S_OK 를 돌려준다.

IAMMediaTypeSample::SetMediaTime

IAMMediaTypeSample 인터페이스

이 샘플의 미디어 타임 스탬프를 설정한다.

구문

HRESULT SetMediaTime(
LONGLONG *pTimeStart,
LONGLONG *pTimeEnd
);

파라미터

pTimeEnd
[in] 미디어의 시작 타임이 저장 된 변수에의 포인터.
pTimeStart
[in] 미디어의 종료 타임이 저장 된 변수에의 포인터.

반환값

S_OK 를 돌려준다.

IAMMediaTypeSample::SetMediaType

IAMMediaTypeSample 인터페이스

샘플의 미디어 타입을 설정한다.

구문

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pMediaType
);

파라미터

pMediaType
미디어 타입을 기술하는 AM_MEDIA_TYPE 구조체에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.

E_OUTOFMEMORY | 메모리 부족.
S_OK | 성공.

IAMMediaTypeSample::SetPointer

IAMMediaTypeSample 인터페이스

미디어 샘플의 메모리 버퍼에의 포인터를 설정한다.

구문

HRESULT SetPointer(
    BYTE *pBuffer,
    long lSize
);

파라미터

pBuffer
[in] 호출원으로 할당할 수 있었던 메모리 버퍼에의 포인터, 또는 NULL.
lSize
[in] 버퍼의 사이즈 (바이트 단위).

반환값

다음의 몇개의 HRESULT 값을 돌려준다.

S_OK | 성공.
E_OUTOFMEMORY | 메모리 부족.

주의

pBuffer 파라미터의 값이 NULL 의 경우, 메소드는 lSize 파라미터의 값과 동일한 사이즈 (바이트 단위)의 메모리 블록을 할당한다. 메모리가 초기화되고 있다고 하는 보장은 없다.

IAMMediaTypeSample::SetPreroll

IAMMediaTypeSample 인터페이스

이것이 프리로르산풀인가 어떤가를 지정한다. 프리로르산풀을 표시해서는 안 된다.

구문

HRESULT SetPreroll(
    BOOL bIsPreroll
);

파라미터

bIsPreroll
샘플이 프리로르산풀인가 어떤가를 지정하는 불리언 값. TRUE 의 경우, 이 샘플은 프리로르용이며, 표시해서는 안 된다.

반환값

S_OK 를 돌려준다.

IAMMediaTypeSample::SetSyncPoint

IAMMediaTypeSample 인터페이스

이 샘플의 시작이 동기 포인트인가 어떤가를 지정한다.

구문

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

파라미터

bIsSyncPoint
이 샘플의 시작이 동기 포인트인가 어떤가를 지정하는 불리언 값. TRUE 의 경우, 샘플의 시작은 동기 포인트이다.

반환값

S_OK 를 돌려준다.

IAMMediaTypeSample::SetTime

IAMMediaTypeSample 인터페이스

샘플이 시작 및 정지해야 할 스트림 타임을 설정한다.

구문

HRESULT SetTime(
REFERENCE_TIME *pTimeStart,
REFERENCE_TIME *pTimeEnd
);

파라미터

pTimeStart
[in] 시작 타임이 저장 된 변수에의 포인터.
pTimeEnd
[in] 종료 타임이 저장 된 변수에의 포인터.

반환값

S_OK 를 돌려준다.


IAMMediaTypeStream 인터페이스

이 인터페이스는, 임의의 미디어 타입의 멀티미디어 스트림을 생성 하는 메소드를 제공한다. 생성 하는 멀티미디어 스트림의 포맷이, 다른 Microsoft® DirectShow® 멀티미디어 스트리밍 인터페이스로 지원되어 있지 않은 경우는, 이 인터페이스를 사용한다.

이 인터페이스는,IMediaStream 인터페이스를 계승한다.

주의 : 비디오 스트림에는, 이 인터페이스 대신에 IDirectDrawMediaStream 인터페이스를 사용한다. 오디오 스트림에는,IAudioMediaStream 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaStream 메소드 | 설명
GetMultiMediaStream | 지정된 미디어 스트림이 저장 된 멀티미디어 스트림에의 포인터를 취득한다.
GetInformation | 스트림의 목적 ID 와 미디어 타입을 취득한다.
SetSameFormat | 미디어 스트림을 직전의 스트림과 같은 포맷으로 설정한다.
AllocateSample | 현재의 미디어 스트림에 새로운 스트림 샘플 오브젝트를 할당한다.
CreateSharedSample | 기존 샘플과 같은배킹 오브젝트를 공유하는 새로운 스트림 샘플을 생성 한다.
SendEndOfStream | 현재의 스트림을 강제 종료한다. 현재의 스트림이 기입해 가능하지 않은 경우, 이 메소드의 호출은 효과가 없다.
IAMMediaTypeStream 메소드 | 설명
GetFormat | 스트림의 포맷을 취득한다.
SetFormat | 스트림의 포맷을 설정한다.
CreateSample | 스트림 샘플을 생성 해, 옵션으로 샘플 버퍼를 지정한다.
GetStreamAllocatorRequirements | 스트림의 allocater 요건을 취득한다. 현재, 이 메소드는 이행되어 있지 않다.
SetStreamAllocatorRequirements | 스트림의 allocater 요건을 설정한다. 현재, 이 메소드는 이행되어 있지 않다.

IAMMediaTypeStream::CreateSample

IAMMediaTypeStream 인터페이스

스트림 샘플을 생성 해, 옵션으로 샘플 버퍼를 지정한다.

구문

HRESULT CreateSample(
    long lSampleSize,
    BYTE *pbBuffer,
    DWORD dwFlags,
    IUnknown *pUnkOuter,
    IAMMediaTypeSample **ppAMMediaTypeSample
);

파라미터

lSampleSize
[in] 샘플의 사이즈.
pbBuffer
[in] [optional] 샘플 데이터가 저장 된 바이트 배열에의 포인터, 또는 NULL.
dwFlags
[in] 예약이 끝난 상태.
pUnkOuter
[in] [optional] 스트림 샘플을 집성 하는 오브젝트의 IUnknown 인터페이스에의 포인터.
ppAMMediaTypeSample
[in] 생성 된 샘플에의 포인터를 받는 IAMMediaTypeSample 인터페이스 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.

E_OUTOFMEMORY | 메모리 부족.
E_POINTER | NULL 포인터 인수.
S_OK | 성공.

주의

pUnkOuter 가 NULL 가 아닌 경우, 새로운 스트림 샘플은 지정된 오브젝트에 집성 된다. 샘플을 받는 필터는, 집성 한 오브젝트로 지원 되는 인터페이스를, 그 샘플에 조회할 수 있다.

IAMMediaTypeStream::GetFormat

IAMMediaTypeStream 인터페이스

스트림의 포맷을 취득한다.

구문

HRESULT GetFormat(
AM_MEDIA_TYPE *pMediaType,
DWORD dwFlags
);

파라미터

pMediaType
[out] 스트림의 포맷을 받는 AM_MEDIA_TYPE 구조체에의 포인터.
dwFlags
[in] 예약이 끝난 상태.

반환값

다음의 몇개의 값을 돌려준다.

MS_E_NOSTREAM | 이 오브젝트에는 스트림을 관련지을 수 있지 않았다.
S_OK | 성공.

IAMMediaTypeStream::GetStreamAllocatorRequirements

IAMMediaTypeStream 인터페이스

스트림의 allocater 요건을 취득한다. 현재, 이 메소드는 이행되어 있지 않다.

구문

HRESULT GetStreamAllocatorRequirements(
ALLOCATOR_PROPERTIES *pProps
);

파라미터

pProps
[out] 스트림의 allocater 요건을 받는 ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

E_FAIL 를 돌려준다.

IAMMediaTypeStream::SetFormat

IAMMediaTypeStream 인터페이스

스트림의 포맷을 설정한다.

구문

HRESULT SetFormat(
AM_MEDIA_TYPE *pMediaType,
DWORD dwFlags
);

파라미터

pMediaType
[in] 스트림의 포맷이 저장 된 AM_MEDIA_TYPE 구조체에의 포인터.
dwFlags
[in] 예약이 끝난 상태.

반환값

다음의 몇개의 값을 돌려준다.

MS_E_SAMPLEALLOC | 스트림이 이미 다른 미디어 타입의 샘플을 할당했다.
S_OK | 성공.

IAMMediaTypeStream::SetStreamAllocatorRequirements

IAMMediaTypeStream 인터페이스

스트림의 allocater 요건을 설정한다. 현재, 이 메소드는 이행되어 있지 않다.

구문

HRESULT SetStreamAllocatorRequirements(
ALLOCATOR_PROPERTIES *pProps
);

파라미터

pProps
[in] 스트림의 allocater 요건이 저장 된 ALLOCATOR_PROPERTIES 구조체에의 포인터.

반환값

E_FAIL 를 돌려준다.


IAMMultiMediaStream 인터페이스

IAMMultiMediaStream 인터페이스는, 멀티미디어 스트림 개발자에게 Microsoft® DirectShow® 의 기능을 공개한다. 이 인터페이스의 메소드를 사용 하면, 필터 그래프를 자동 생성해, 수신 데이터를 재생 또는 캡춰 하기 위해서 파일 또는모니카를 열어, 소정의 필터 그래프를 렌더링 할 수가 있다.

어플리케이션으로 DirectShow 의 미디어 타입에 대응하는 멀티미디어 스트림 베이스의 지원을 제공하려면 , 이 인터페이스를 이행 한다.

멀티미디어 스트리밍 어플리케이션으로, DirectShow 가 지원 하는 미디어 재생을 제어하려면 , 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAMMultiMediaStream 메소드 | 설명
Initialize | 스트림 타입을 설정한다. pFilterGraph 파라미터가 NULL 가 아닌 경우에는, 건네받은 필터 그래프를 스트림에 사용한다.
GetFilterGraph | 관련지을 수 있었던 필터 그래프의 IGraphBuilder 인터페이스를 취득한다.
GetFilter | 현재의 필터 그래프로부터 지정된 필터를 취득한다.
AddMediaStream | 현재의 필터 그래프로 지정된 미디어 스트림을 추가한다.
OpenFile | 지정된 미디어 파일에 대응하는 필터 그래프를 열어, 자동 생성 한다. 파일 포맷이 DirectShow 로 지원되어 있지 않은 경우, 메소드는 아무것도 실행하지 않는다.
OpenMoniker | 파이르모니카 또는 데바이스모니카를 연다. 미디어 타입이 DirectShow 로 지원 되고 있으면, 이 모니카로부터 미디어 데이터를 읽어낼 수가 있다.
Render | 현재의 필터 그래프를 렌더링 한다.

IAMMultiMediaStream::AddMediaStream

IAMMultiMediaStream 인터페이스

현재의 필터 그래프로 지정된 미디어 스트림을 추가한다.

구문

HRESULT AddMediaStream(
    IUnknown *pStreamObject,
    const MSPID *pPurposeID,
    DWORD dwFlags,
    IMediaStream **ppNewStream
    );

파라미터

pStreamObject
[in] 현재의 필터 그래프에 추가하는 미디어 스트림 또는 기반이 되는 스트림 오브젝트를 가리키는 IUnknown 인터페이스에의 포인터.
pPurposeID
[in] 새롭게 추가하는 미디어 스트림의 목적 ID 에의 포인터.
dwFlags
[in] 미디어 스트림의 동작을 수정하는, 이하의 값을 1 개 이상 조합한 값.
AMMSF_ADDDEFAULTRENDERER | 디폴트의렌더러를 추가한다.
AMMSF_CREATEPEER | pStreamObject 와 같은 오브젝트에 근거하는 피아스트림을 생성 한다.
AMMSF_STOPIFNOSAMPLES | 샘플이 1 개나 생성되어 있지 않은 경우, 또는 마지막 샘플이 삭제되었을 경우에는, 스트림을 종료한다.
AMMSF_NOSTALL | Update 가 불려 가지 않아도 스트림을 실행한다.
ppNewStream
[out] IMediaStream 인터페이스에의 포인터의 주소. 이 포인터에, 새롭게 추가된 미디어 스트림의 주소를 받는다. 이 파라미터는 생략 가능.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.
MS_E_PURPOSEID | 추가하는 스트림이 가지는 목적 ID 가 지정된 ID 와 다르고 있는지, 또는 지정된 목적 ID 를 가지는 스트림이 이미 존재한다.
E_POINTER | Null 포인터 인수.
S_OK | 성공.

주의

dwFlags 에 AMMSF_ADDDEFAULTRENDERER 를 지정 하면, 지정된 목적 ID 에 대응하는 디폴트 렌더러가 생성 된다 (가능한 경우). 현시점에서는, DirectSound 를 사용하는 오디오에 대응하는 디폴트 렌더러만이 지원 된다. 이 경우,pStreamObject 파라미터는 NULL 가 아니면 안된다. 또,IMultiMediaStream::GetMediaStream 메소드 또는 IMultiMediaStream::EnumMediaStreams 메소드의 호출에서는, 스트림이 인식되지 않는다.

dwFlags 에 AMMSF_CREATEPEER 를 지정 하면,pStreamObject 를 사용해 미디어 스트림이 생성 되어 그 미디어 스트림이 현재의 멀티미디어 스트림에 추가된다. pStreamObject 파라미터는 스트림 타입에 따라서 다르다. 보통,pStreamObject 에는 IMediaStream 오브젝트에의 포인터를 지정할 수 있다. 이 경우, 샘플과 같은 목적 ID 및 포맷을 가지는 스트림이 생성 된다. IDirectDraw 스트림의 경우에는,IDirectDraw 오브젝트에의 포인터도 지정할 수 있다.

dwFlags 에 AMMSF_STOPIFNOSAMPLES 를 지정 하면, 스트림이 종료된다.

플래그가 1 개나 세트되어 있지 않은 경우,pStreamObject 는 다음의 몇개의 값을 취한다.
IAMMediaStream 오브젝트 | 이 경우, 이 스트림은 멀티미디어 스트림내의 스트림에 추가된다.
NULL | 이 경우, 디폴트의 IMediaStream 오브젝트가, 기반이 되는 디폴트의 오브젝트를 가지는 스트림에 추가된다 (필요한 경우).
기반이 되는 오브젝트에의 포인터 | 이 포인터를 사용해, 디폴트 스트림이 구축된다. 비디오 스트림의 경우에는,IDirectDraw 포인터의 가능성이 있다.

IAMMultiMediaStream::GetFilter

IAMMultiMediaStream 인터페이스

현재의 필터 그래프로부터 지정된 필터를 취득한다.

구문

HRESULT GetFilter(
    IMediaStreamFilter **ppFilter
    );

파라미터

ppFilter
[out] IMediaStreamFilter 인터페이스에의 포인터의 주소. 이 포인터에, 현재의 필터의 주소를 받는다.

반환값

성공했을 경우는, S_OK 를 돌려준다. NULL 의 필수 파라미터가 있는 경우는, E_POINTER 를 돌려준다.

IAMMultiMediaStream::GetFilterGraph

IAMMultiMediaStream 인터페이스

관련지을 수 있었던 필터 그래프의 IGraphBuilder 인터페이스를 취득한다.

구문

HRESULT GetFilterGraph(
    IGraphBuilder **ppGraphBuilder
    );

파라미터

ppGraphBuilder
[out] IGraphBuilder 인터페이스에의 포인터의 주소. 이 포인터에, 현재의 필터 그래프의 주소를 받는다.

반환값

성공했을 경우는, S_OK 를 돌려준다. NULL 의 필수 파라미터가 있는 경우는, E_POINTER 를 돌려준다.

IAMMultiMediaStream::Initialize

IAMMultiMediaStream 인터페이스

스트림 타입을 설정한다. pFilterGraph 파라미터가 NULL 가 아닌 경우에는, 건네받은 필터 그래프를 스트림에 사용한다.

구문

HRESULT Initialize(
    STREAM_TYPE StreamType,
    DWORD dwFlags,
    IGraphBuilder *pFilterGraph
    );

파라미터

StreamType
[in] 새로운 필터 그래프의 스트림 타입을 지정하는 STREAM_TYPE 열거값.
dwFlags
[in] AMMSF_NOGRAPHTHREAD 플래그 또는 0. AMMSF_NOGRAPHTHREAD 플래그는, 현재의 thread로 필터 그래프 오브젝트를 생성 하는 것을 나타낸다.
pFilterGraph
[in] [optional] 새로운 필터 그래프의 주소를 받는 IGraphBuilder 인터페이스에의 포인터. 이 파라미터는 생략 가능. 나중에 필터 그래프에 액세스 할 필요가 있는 경우에게만, 유효한 포인터를 건네준다.

반환값

성공했을 경우는, S_OK 를 돌려준다. NULL 의 필수 파라미터가 있는 경우는, E_POINTER 를 돌려준다.

주의

AMMSF_NOGRAPHTHREAD 플래그를 안전하게 사용하려면 , 현재의 thread가 종료할 때까지 어플리케이션이 스트림 오브젝트를 해방하지 않고, 윈도우 메세지가 현재의 thread로 처리되지 않으면 안 된다.

IAMMultiMediaStream::OpenFile

IAMMultiMediaStream 인터페이스

지정된 미디어 파일에 대응하는 필터 그래프를 열어, 자동 생성 한다. 파일 포맷이 DirectShow 로 지원되어 있지 않은 경우, 메소드는 아무것도 실행하지 않는다.

구문

HRESULT OpenFile(
    LPCWSTR pszFileName,
    DWORD dwFlags
    );

파라미터

pszFileName
[in] 여는 파일의 이름에의 포인터.
dwFlags
[in] 필터 그래프가 지정된 파일을 렌더링 하는 방법을 수정하는 값. 이 값은, 이하의 플래그를 1 개 이상 조합한 것이다.
AMMSF_RENDERTOEXISTING | 기존의 스트림인 만큼 렌더링 한다.
AMMSF_RENDERALLSTREAMS | 기존의 미디어 스트림을 가지지 않는 스트림을 포함해, 모든 스트림을 렌더링 한다.
AMMSF_NORENDER | 파일을 열지만, 스트림의 렌더링은 하지 않는다. 이 플래그는 항상 AMMSF_RUN 플래그와 함께 지정해야 한다.
AMMSF_NOCLOCK | 클락이 없는 스트림을 실행한다.
AMMSF_RUN | 스트림을 실행 상태로 전환한다.

반환값

다음의 몇개의 값을 돌려준다.
E_INVALIDARG | dwFlags 파라미터가 무효.
E_POINTER | 이 메소드가 무효인 포인터에 액세스 하려고 했다.
S_OK | 성공.

주의

AMMSF_RENDERALLSTREAMS 플래그가 온의 경우, 비디오 및 오디오용의 디폴트 렌더링 필터가 없으면 생성 한다. 다만, 이러한 디폴트 필터는,IStreamSample::GetMediaStream 메소드로 액세스 할 수가 없다.

IAMMultiMediaStream::OpenMoniker

IAMMultiMediaStream 인터페이스

파이르모니카 또는 데바이스모니카를 연다. 모니카가 DirectShow 로 지원 되고 있으면, 이 모니카로부터 미디어 데이터를 읽어낼 수가 있다.

구문

HRESULT OpenMoniker(
    IBindCtx *pCtx,
    IMoniker *pMoniker,
    DWORD dwFlags
    );

파라미터

pCtx
[in] 모니카에 관련지을 수 있었던 바인드콘테키스트에의 포인터.
pMoniker
[in] 여는 모니카를 지정하는 IMoniker 인터페이스에의 포인터.
dwFlags
[in] 필터 그래프가 지정된 파일을 렌더링 하는 방법을 수정하는 값. 이 값은, 이하의 플래그를 1 개 이상 조합한 것이다.
AMMSF_RENDERTOEXISTING | 기존의 스트림인 만큼 렌더링 한다.
AMMSF_RENDERALLSTREAMS | 기존의 미디어 스트림을 가지지 않는 스트림을 포함해, 모든 스트림을 렌더링 한다.
AMMSF_NORENDER | 파일을 열지만, 스트림의 렌더링은 하지 않는다. 이 플래그는 항상 AMMSF_RUN 플래그와 함께 지정해야 한다.
AMMSF_NOCLOCK | 클락이 없는 스트림을 실행한다.
AMMSF_RUN | 스트림을 실행 상태로 전환한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. dwFlags 파라미터가 무효인 경우는, E_INVALIDARG 을 돌려준다.

IAMMultiMediaStream::Render

IAMMultiMediaStream 인터페이스

현재의 필터 그래프를 렌더링 한다.

구문

HRESULT Render(
DWORD dwFlags
    );

파라미터

dwFlags
[in] 필터 그래프가 현재의 멀티미디어 스트림을 렌더링 하는 방법을 지정하는 값. 현재, 이 값은 AMMSF_NOCLOCK 가 아니면 안된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. dwFlags 파라미터가 무효인 경우는, E_INVALIDARG 를 돌려준다.

주의

이 메소드는, 각 소스 스트림을 STREAMTYPE_WRITE 타입의 스트림에 렌더링 한다. 이 메소드는 반복해 호출할 수가 있다 (예를 들어 소스 스트림이 추가될 때마다 호출하는 등). 스트림은 실행 상태에 바뀌지 않는다. 스트림을 실행 상태로 전환하려면 , 이 메소드의 호출 후에 IMultiMediaStream::SetState 메소드를 사용한다.

AMMSF_RENDERALLSTREAMS 플래그가 온의 경우, 비디오 및 오디오용의 디폴트 렌더링 스트림이 없으면 생성 된다.


IAudioData 인터페이스

IAudioData 인터페이스는, 어플리케이션으로부터, 오디오 스트림으로부터 참조되는, 기반이 되는 오디오 데이터를 설정 및 취득하기 위한 메소드를 제공한다. 오디오 데이터의 포맷은,WAVEFORMATEX 구조체로 설정된다.

이 인터페이스는, 오디오 스트림 샘플 오브젝트로부터 액세스 되는, 기반이 되는 오디오 데이터 오브젝트상에 이행 한다.

오디오 스트림이 참조하는 기반이 되는 데이터 오브젝트에 관한 정보를, 어플리케이션으로부터 설정 및 취득하려면 , 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAudioData 메소드 | 설명
GetFormat | 현재의 데이터 포맷을 취득한다.
SetFormat | 현재의 데이터 포맷을 설정한다.

IAudioData::GetFormat

IAudioData 인터페이스

현재의 데이터 포맷을 취득한다.

구문

HRESULT GetFormat(
    WAVEFORMATEX *pWaveFormatCurrent
    );

파라미터

pWaveFormatCurrent
[out] 현재의 데이터 포맷이 저장 된 WAVEFORMATEX 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 포인터가 무효인 경우는, E_POINTER 를 돌려준다.

주의

현재, Microsoft® DirectShow® 는 PCM 웨이브 데이터만을 지원 한다.

참조

IAudioData::SetFormat

IAudioData::SetFormat

IAudioData 인터페이스

현재의 데이터 포맷을 설정한다.

구문

HRESULT SetFormat(
    const WAVEFORMATEX *lpWaveFormat
    );

파라미터

lpWaveFormat
[in] 현재의 데이터 포맷을 저장 하는 WAVEFORMATEX 구조체에의 포인터.

반환값

다음의 몇개의 HRESULT 값을 돌려준다.
E_POINTER | 무효인 포인터 인수.
E_INVALIDARG | 무효인 포맷.
S_OK | 성공.

참조

IAudioData::GetFormat


IAudioMediaStream 인터페이스

IAudioMediaStream 인터페이스는, 스트림의 포맷을 설정 및 취득하는 메소드를 제공하는 것으로써, 오디오 미디어 스트림을 제어한다. 이 인터페이스는,IMediaStream 인터페이스를 계승해, 1 개(살) 이상의 IAudioStreamSample 오브젝트를 생성 하기 위해서 사용된다. 또, 스트림 데이터의 현재의 포맷을 설정 및 취득할 수도 있다.

현재, 이 인터페이스는 PCM 포맷의 오디오 데이터용에만 정의되고 있다.

오디오 스트리밍 인터페이스를 이행 하는 샘플 코드에 대해서는, 「멀티미디어 스트리밍의 샘플 코드」를 참조할것.

비디오 같이, 오디오는 그 내용을 기술하는 컨테이너 오브젝트에 저장 된다. 오브젝트로부터 오디오의 스트리밍을 제어할 필요가 있는 경우는, 이 인터페이스를 이행 한다.

어플리케이션으로 오디오를 생성하려면 , 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAudioMediaStream 메소드 | 설명
GetFormat | 스트림 데이터의 현재의 포맷을 취득한다.
SetFormat | 스트림의 포맷을 설정한다.
CreateSample | 이 스트림으로 사용하는 오디오 스트림 샘플을 생성 한다.

IAudioMediaStream::CreateSample

IAudioMediaStream 인터페이스

지정된 스트림으로 사용하는 오디오 스트림 샘플을 생성 한다.

구문

HRESULT CreateSample(
    IAudioData *pAudioData,
    DWORD dwFlags,
    IAudioStreamSample **ppSample
    );

파라미터

pAudioData
[in] IAudioData 컨테이너에의 포인터. IAudioData 오브젝트는 복수의 스트림의 샘플로부터 참조할 수 있다.
dwFlags
[in] 플래그 데이터용으로 예약되고 있다. 제로가 아니면 안 된다.
ppSample
[out] 새로운 IAudioStreamSample 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. NULL 의 필수 파라미터가 있는 경우는, E_POINTER 를 돌려준다.

주의

pAudioData 오브젝트로 데이터의 포맷을 정의한다.

IAudioMediaStream::GetFormat

IAudioMediaStream 인터페이스

스트림 데이터의 현재의 포맷을 취득한다.

구문

HRESULT GetFormat(
    WAVEFORMATEX *pWaveFormatCurrent );

파라미터

pWaveFormatCurrent
[out] 스트림 데이터의 현재의 포맷이 저장 된 WAVEFORMATEX 구조체에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 필수 파라미터가 NULL 의 경우는, E_POINTER 를 돌려준다.

주의

현재, Microsoft® DirectShow® 는 PCM 웨이브 데이터만을 지원 한다.

IAudioMediaStream::SetFormat

IAudioMediaStream 인터페이스

스트림의 포맷을 설정한다.

구문

HRESULT SetFormat(
const WAVEFORMATEX *lpWaveFormat
    );

파라미터

lpWaveFormat
[in] 스트림 포맷 정보가 저장 된 WAVEFORMATEX 구조체에의 포인터.

반환값

HRESULT 값을 돌려준다. 이 값은, 이하의 값인가, 또는 일람에 나타나지 않은 그 외의 값이 된다.
MS_E_INCOMPATIBLE | IAudioData 오브젝트의 포맷이 스트림과 호환이 아니다.
E_POINTER | Null 포인터 인수.
E_INVALIDARG | 무효인 인수.
S_OK | 성공.


IAudioStreamSample 인터페이스

IAudioStreamSample 인터페이스는, 기반이 되는 IAudioData 데이터 오브젝트로부터 정보를 취득한다.

오디오 스트리밍 인터페이스를 이행 하는 샘플 코드에 대해서는, 「멀티미디어 스트리밍의 샘플 코드」를 참조할것.

IAudioData 오브젝트의 데이터에 액세스 할 필요가 있는 오디오 스트림 샘플 오브젝트에는, 이 인터페이스를 이행 한다.

어플리케이션으로부터 그 오디오 스트림에 대응하는 IAudioData 오브젝트의 데이터에 액세스 하려면 , 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IAudioStreamSample 메소드 | 설명
GetAudioData | 샘플에 관련지을 수 있었던 IAudioData 오브젝트에의 포인터의 주소를 취득한다.

IAudioStreamSample::GetAudioData

IAudioStreamSample 인터페이스

샘플에 관련지을 수 있었던 IAudioData 오브젝트에의 포인터의 주소를 취득한다.

구문

HRESULT GetAudioData(
  IAudioData **ppAudio );

파라미터

ppAudio
[out] IAudioData 오브젝트에의 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 파라미터가 NULL 의 경우는, E_POINTER 를 돌려준다.


IDirectDrawMediaStream 인터페이스

IDirectDrawMediaStream 인터페이스는, Microsoft® DirectDraw® 표면에 표시되는 미디어 스트림을 제어한다. DirectDraw 표면에 스트림 하려면 , DirectDraw 가 비디오 스트림 포맷을 지원 하고 있을 필요가 있다.

멀티미디어 스트리밍 인터페이스를 이행 하는 샘플 코드에 대해서는, 「멀티미디어 스트리밍의 샘플 코드」를 참조할것.

이 인터페이스는, 어플리케이션 개발자에 의한 이행을 목적으로 한 것은 아니다. Microsoft® DirectShow® 멀티미디어 스트림에 추가할 수 있는 DirectDraw 미디어 스트림상에서 공개된다.

DirectDraw 표면에 비디오 스트림을 보내려면 , 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDirectDrawMediaStream 메소드 | 설명
GetFormat | 현재의 미디어 스트림의 포맷을 취득해, 옵션으로 그 바람직한 포맷도 취득한다.
SetFormat | 현재의 미디어 스트림의 포맷을 설정한다. 스트림에 이미 할당하고 끝난 샘플이 있어, 그 샘플의 포맷과 지정된 포맷이 일치하지 않는 경우, 이 메소드는 실패한다.
GetDirectDraw | 현재의 미디어 스트림으로 사용되는 DirectDraw 오브젝트에의 포인터를 취득한다.
SetDirectDraw | 현재의 미디어 스트림의 DirectDraw 오브젝트를 설정한다.
CreateSample | 지정된 DirectDraw 표면 오브젝트를 사용하는 스트림 샘플을 생성 한다.
GetTimePerFrame | 비디오 스트림으로부터 얻을 수 있는 1 초 쯤의 평균 프레임수를 취득한다.

IDirectDrawMediaStream::CreateSample

IDirectDrawMediaStream 인터페이스

지정된 DirectDraw 표면 오브젝트를 사용하는 스트림 샘플을 생성 한다.

구문

HRESULT CreateSample(
    IDirectDrawSurface *pSurface,
    const RECT *pRect,
    DWORD dwFlags,
    IDirectDrawStreamSample **ppSample
    );

파라미터

pSurface
[in] 기존의 DirectDraw 표면에의 포인터.
pRect
[in] 지정한 표면에 사용하는 클리핑 직사각형에의 포인터. 표면 전체를 사용하려면 , 이 파라미터를 NULL 로 설정한다.
dwFlags
[in] 렌더링 방식이 프로그래시브인가 어떤가를 지정하는 플래그. 프로그래시브 렌더링을 실행하려면 , 이 값을 DDSFF_PROGRESSIVERENDER 로 설정한다. 이 플래그를 세트 했을 경우, 샘플을 갱신 하면, 샘플 데이터가 표면에 카피된다.
ppSample
[out] IDirectDrawStreamSample 인터페이스에의 포인터의 주소. 이 포인터에, 새롭고 생성 된 샘플의 주소를 받는다.

반환값

다음의 몇개의 값을 돌려준다.
DDERR_INVALIDPIXELFORMAT | 지정된 픽셀 포맷이 스트림 포맷과 호환이 아니다.
DDERR_INVALIDRECT | 지정된 클리핑 직사각형이 무효.
DDERR_INVALIDSURFACETYPE | 지정된 표면이 스트림 포맷과 호환이 아니다.
E_POINTER | 무효인 필수 파라미터가 있다.
MS_E_SAMPLEALLOC | 스트림에 이미 할당하고가 끝난 샘플이 있어, 샘플의 포맷이 표면과 일치하지 않는다.
S_OK | 성공.

주의

이 메소드는, 현재의 스트림으로부터 샘플을 생성 해, 그 샘플을 이 표면에 어태치 한다.

스트림에 할당하고 끝난 표면이 없고, 지정된 표면이 스트림의 포맷과 일치하지 않는 경우, 이 메소드는 스트림의 IDirectDrawMediaStream::SetFormat 메소드를 호출해 2 개의 포맷을 일치시킨다.

프로그래시브 렌더링을 실행하려면 , 샘플을 1 개 생성 해, 그 샘플을 그 이후의 비디오 프레임에 반복해 사용한다. 비데오데콘프렛사피르타는, 직전의 프레임을 부분적으로 갱신하기 위해서 이 테크닉을 사용한다.

pRect 파라미터는, 스트림의 포맷과 일치하고 있지 않으면 안 된다 ( 「IDirectDrawMediaStream::GetFormat 」를 참조). 오 기다린 클리핑 직사각형을 설정했는지, 또는 클리핑 직사각형을 설정하고 있지 않는 경우, 표면과 사이즈가 다른 무비는 재생되지 않을 가능성이 있다. 프라이머리 표면이 사용되는 경우에는, 유저가 디스플레이 설정을 변경 하면 프라이머리 표면의 사이즈가 바뀔 가능성이 있기 (위해)때문에, 클리핑 직사각형의 사용을 추천 한다.

IDirectDrawMediaStream::GetDirectDraw

IDirectDrawMediaStream 인터페이스

현재의 미디어 스트림으로 사용되는 DirectDraw 오브젝트에의 포인터를 취득한다.

구문

HRESULT GetDirectDraw(
    IDirectDraw **ppDirectDraw
    );

파라미터

ppDirectDraw
[out] 현재의 미디어 스트림에 관련지을 수 있었던 DirectDraw 오브젝트가 저장 되는 IDirectDraw 인터페이스에의 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 파라미터가 무효인 경우는, E_POINTER 를 돌려준다.

주의

스트림을 아직 초기화하고 있지 않는 경우, 취득되는 포인터는 NULL 가 되어, 메소드는 S_OK 를 돌려준다. 스트림이 초기화되고 있는 경우, 메소드는 취득된 포인터의 참조 카운트를 인크리먼트(increment) 한다.

IDirectDrawMediaStream::GetFormat

IDirectDrawMediaStream 인터페이스

현재의 미디어 스트림의 포맷을 취득해, 옵션으로 그 바람직한 포맷도 취득한다.

구문

HRESULT GetFormat(
    DDSURFACEDESC *pDDSDCurrent,
    IDirectDrawPalette **ppDirectDrawPalette,
    DDSURFACEDESC *pDDSDDesired,
    DWORD *pdwFlags
    );

파라미터

pDDSDCurrent
[out] 현재의 미디어 스트림의 포맷이 저장 되는 DirectDraw 표면 기술에의 포인터.
ppDirectDrawPalette
[out] IDirectDrawPalette 인터페이스에의 포인터의 주소 (있는 경우).
pDDSDDesired
[out] 현재의 미디어 스트림의 바람직한 포맷이 저장 되는 DirectDraw 표면 기술에의 포인터.
pdwFlags
[out] DDSURFACEDESC 구조체에 세트 되는 플래그에의 포인터. 유효한 필드에는 이하의 것이 있다.
DDSD_HEIGHT | 구조체의 높이의 멤버가 유효한 일을 나타낸다.
DDSD_WIDTH | 구조체의 폭의 멤버가 유효한 일을 나타낸다.
DDSD_PIXELFORMAT | 구조체의 픽셀 포맷의 멤버가 유효한 일을 나타낸다.
DDSD_CAPS | 구조체의 표면 능력의 멤버가 유효한 일을 나타낸다.

반환값

다음의 몇개의 값을 돌려준다.
DDERR_INVALIDPARAMS | DirectDraw 표면 파라미터의 1 개가 무효.
E_POINTER | 무효인 필수 파라미터가 있다.
S_OK | 성공.

주의

이 메소드를 호출한 후, 현재의 포맷에 따르는지, 또는 IDirectDrawMediaStream::SetFormat 메소드를 호출해 포맷의 변경을 시도한다.

이 메소드의 파라미터는 모두 생략 가능하다. 취득하지 않아도 좋은 정보가 있는 경우는, 그 파라미터를 NULL 로 설정한다.

프로그래시브 렌더링을 실행하려면 , 샘플을 1 개 생성 해, 그 샘플을 그 이후의 비디오 프레임에 반복해 사용한다. 비데오데콘프렛사피르타는, 직전의 프레임을 부분적으로 갱신하기 위해서 이 테크닉을 사용한다.

이 메소드를 호출하기 전에,DDSURFACEDESC 구조체의 dwSize 멤버를 초기화할 필요가 있다.

DDSD_CAPS 플래그가 온의 경우,DDSCAPS 구조체에 포함되는 값의 1 개, 또는 DDSCAPS_DATAEXCHANGE 를 돌려준다. DDSCAPS_DATAEXCHANGE 는, Ddrawex.h 에 DDSCAPS_SYSTEMMEMORY|DDSCAPS_VIDEOMEMORY 로서 정의되고 있다.

IDirectDrawMediaStream::GetTimePerFrame

IDirectDrawMediaStream 인터페이스

비디오 스트림으로부터 얻을 수 있는 1 초 쯤의 평균 프레임수를 취득한다.

구문

HRESULT GetTimePerFrame(
    STREAM_TIME *pFrameTime
    );

파라미터

pFrameTime
[out] 프레임 근처의 평균 시간 (100 나노초단위)을 나타내는 STREAM_TIME 값에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 포인터가 무효인 경우는, E_POINTER 를 돌려준다.

IDirectDrawMediaStream::SetDirectDraw

IDirectDrawMediaStream 인터페이스

현재의 미디어 스트림의 DirectDraw 오브젝트를 설정한다.

구문

HRESULT SetDirectDraw(
    IDirectDraw *pDirectDraw
    );

파라미터

pDirectDraw
[in] 미디어 스트림의 새로운 DirectDraw 오브젝트가 저장 된 IDirectDraw 인터페이스에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 포인터가 무효인 경우는, E_POINTER 를 돌려준다.

주의

현재의 스트림에 이미 할당하고 끝난 샘플이 있어, 그 DirectDraw 오브젝트와 지정된 오브젝트가 일치하지 않는 경우, 이 메소드는 실패한다. 지정된 DirectDraw 오브젝트가 스트림의 현재의 오브젝트와 일치하는 경우에는, 반드시 성공한다.

이 스트림에 할당하고 끝난 샘플이 없는 경우,pDirectDraw 를 NULL 로 설정할 수가 있다. 이렇게 하면(자), 스트림으로부터 현재의 DirectDraw 오브젝트의 참조가 강제적으로 해방된다.

IDirectDrawMediaStream::SetFormat

IDirectDrawMediaStream 인터페이스

현재의 미디어 스트림의 포맷을 설정한다.

구문

HRESULT SetFormat(
    const DDSURFACEDESC *pDDSurfaceDesc,
    IDirectDrawPalette *pDirectDrawPalette
    );

파라미터

pDDSurfaceDesc
[in] 새로운 포맷이 저장 된 DirectDraw 표면 기술에의 포인터.
pDirectDrawPalette
[in] IDirectDrawPalette 인터페이스에의 포인터 (생략 가능).

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 성공.
DDERR_INVALIDSURFACETYPE | 지정된 포맷이 현재의 스트림과 호환이 아니다.
MS_E_SAMPLEALLOC | 이 스트림에는 이미 할당하고 끝난 스트림 샘플이 있기 (위해)때문에, 포맷을 변경할 수 없다.

주의

스트림에 이미 할당하고 끝난 샘플이 있어, 그 샘플의 포맷과 지정된 포맷이 일치하지 않는 경우, 이 메소드는 실패한다. 지정된 포맷이 현재의 포맷과 일치하고 있는 경우, 이 메소드는 반드시 성공한다.


IDirectDrawStreamSample 인터페이스

IDirectDrawStreamSample 인터페이스는, 현재의 스트림 샘플에 관련지을 수 있었던 Microsoft® DirectDraw® 표면에의 포인터를 설정 및 취득하는 메소드를 제공한다.

이 인터페이스는, 어플리케이션 개발자에 의한 이행을 목적으로 한 것은 아니다. DirectDraw 스트림에 의해 생성 된 샘플 오브젝트로 공개된다.

어플리케이션으로부터, 클리핑 직사각형을 설정해, DirectDraw 스트림 샘플용의 렌더링 표면을 취득하려면 , 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IDirectDrawStreamSample 메소드 | 설명
GetSurface | 현재의 샘플의 DirectDraw 표면에의 포인터, 및 관련지을 수 있었던 직사각형에의 포인터를 취득한다.
SetRect | 샘플의 클리핑 직사각형을 변경한다.

IDirectDrawStreamSample::GetSurface

IDirectDrawStreamSample 인터페이스

현재의 샘플의 DirectDraw 표면에의 포인터, 및 관련지을 수 있었던 직사각형에의 포인터를 취득한다.

구문

HRESULT GetSurface(

  IDirectDrawSurface **ppDirectDrawSurface,

  RECT *pRect

  );

파라미터

ppDirectDrawSurface
[out] 샘플의 새로운 표면을 지정하는 IDirectDrawSurface 인터페이스에의 포인터의 주소. 새로운 표면을 지정하지 않는 경우는, 이 파라미터를 NULL 로 설정한다.
pRect
[out] 현재의 샘플의 클리핑 직사각형이 저장 되는 RECT 구조체에의 포인터. 클리핑 직사각형을 취득하지 않는 경우는, 이 파라미터를 NULL 로 설정한다.

반환값

HRESULT 값을 돌려준다.

주의

어느 쪽의 파라미터도 생략 가능하다. 이 인터페이스의 이행은 모두, NULL 를 유효한 파라미터라고 볼 필요가 있다. 표면 포인터를 취득하는 경우, 메소드측에서 그 참조 카운트가 인크리먼트(increment) 되므로, 호출원으로 참조를 해방하는 것.

IDirectDrawStreamSample::SetRect

IDirectDrawStreamSample 인터페이스

샘플의 클리핑 직사각형을 변경한다.

구문

HRESULT SetRect (

  const RECT *pRect

  );

파라미터

pRect
[in] 스트림의 새로운 클리핑 직사각형을 지정하는 RECT 구조체에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.
DDERR_INVALIDPIXELFORMAT | 스트림이 픽셀 포맷과 호환이 아니다.
DDERR_INVALIDRECT | 지정된 직사각형이 무효.
DDERR_INVALIDSURFACETYPE | 스트림이 표면과 호환이 아니다.
E_POINTER | 포인터의 1 개가 무효.
MS_E_SAMPLEALLOC | 스트림 포맷이 표면과 일치하지 않고, 현재, 스트림에 샘플을 할당할 수 있고 있다.
S_OK | 성공.

주의

파라미터는 생략 가능하다. 값을 변경하지 않는 경우에는, 그 파라미터를 NULL 로 설정한다. 표면 포맷이 스트림 포맷과 일치하지 않는 경우, 이 메소드는 실패한다.

새로운 직사각형과 현재의 직사각형의 사이즈가 다른 경우, 이 메소드의 호출은 실패한다.


IMediaStream 인터페이스

IMediaStream 인터페이스는, 미디어 스트림의 특성 (스트림의 미디어 타입, 목적 ID 등)에의 액세스를 제공한다. 또, 데이터 샘플을 생성 하는 메소드도 준비되어 있다.

멀티미디어 스트리밍 인터페이스를 이행 하는 샘플 코드에 대해서는, 「멀티미디어 스트리밍의 샘플 코드」를 참조할것.

미디어 스트림에 미디어 타입 고유의 기능을 추가하려면 , 이 인터페이스를 이행 한다. 이 인터페이스는, 멀티미디어 스트림 오브젝트상에 이행 된다. IMediaStream 에는 범용의 샘플 생성 메소드가 있지만, 보통은, 미디어 타입의 개개의 특성을 충분히 꺼내기 위해서(때문에), 이러한 메소드를 보다 강력하게 고쳐 쓸 필요가 있다.

어플리케이션으로부터, 스트림의 미디어 타입 정보에 액세스 해, 데이터 샘플을 생성 하려면 , 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMediaStream 메소드 | 설명
GetMultiMediaStream | 지정된 미디어 스트림이 저장 된 멀티미디어 스트림에의 포인터를 취득한다.
GetInformation | 스트림의 목적 ID 와 미디어 타입을 취득한다.
SetSameFormat | 미디어 스트림을 직전의 스트림과 같은 포맷으로 설정한다.
AllocateSample | 현재의 미디어 스트림에 새로운 스트림 샘플 오브젝트를 할당한다.
CreateSharedSample | 기존 샘플과 같은배킹 오브젝트를 공유하는 새로운 스트림 샘플을 생성 한다.
SendEndOfStream | 현재의 스트림을 강제 종료한다. 현재의 스트림이 기입해 가능하지 않은 경우, 이 메소드는 아무것도 실행하지 않는다.

IMediaStream::AllocateSample

IMediaStream 인터페이스

현재의 미디어 스트림에 새로운 스트림 샘플 오브젝트를 할당한다.

구문

HRESULT AllocateSample(
  DWORD dwFlags,
  IStreamSample **ppSample
  );

파라미터

dwFlags
[in] 플래그. 제로가 아니면 안 된다.
ppSample
[out] 새롭고 생성 된 스트림 샘플의 IStreamSample 인터페이스에의 포인터의 주소.

반환값

다음의 몇개의 값을 돌려준다.
E_OUTOFMEMORY | 메모리 부족을 위해, 스트림 샘플을 생성 할 수 없다.
E_POINTER | 파라미터가 무효.
S_OK | 성공.

주의

이 메소드는, 샘플과 그 배킹 오브젝트 또는 버퍼를 할당한다. 배킹 오브젝트는, 비디오용의 DirectDraw 표면인가, 또는 오디오용의 IAudioData 오브젝트의 어느 쪽인지이다.

IMediaStream::CreateSharedSample

IMediaStream 인터페이스

기존 샘플과 같은배킹 오브젝트를 공유하는 새로운 스트림 샘플을 생성 한다.

구문

HRESULT CreateSharedSample(

  IStreamSample *pExistingSample,

  DWORD dwFlags ,

  IStreamSample **ppNewSample

  );

파라미터

pExistingSample
[in] 기존의 샘플에의 포인터.
dwFlags
[in] 플래그 데이터용으로 예약되고 있다. 제로가 아니면 안 된다.
ppNewSample
[out] IStreamSample 인터페이스에의 포인터의 주소. 이 포인터에, 새롭고 생성 된 공유 샘플의 주소를 받는다.

반환값

다음의 몇개의 값을 돌려준다.
E_OUTOFMEMORY | 메모리 부족을 위해, 샘플을 생성 할 수 없다.
E_POINTER | 파라미터의 1 개가 무효.
MS_E_INCOMPATIBLE | 기존의 샘플이 지정된 미디어 스트림과 호환이 아니다.
S_OK | 성공. ppNewSample 는 새롭고 생성 된 샘플을 가리킨다.

주의

이 메소드는, 기존의 샘플 위에의 IUnknown::QueryInterface 를 호출해 미디어 타입 고유의 정보를 취득해, 그 정보를 사용해 공유 샘플을 생성 한다.

IMediaStream::GetInformation

IMediaStream 인터페이스

스트림의 목적 ID 와 미디어 타입을 취득한다.

구문

HRESULT GetInformation(

  MSPID *pPurposeId,

  STREAM_TYPE *pType

  );

파라미터

pPurposeId
[out] 스트림의 목적 ID 가 저장 되는 MSPID 값에의 포인터. 이 파라미터에 NULL 를 건네주었을 경우, 메소드는 목적 ID 를 취득하지 않는다.
pType
[out] 스트림의 미디어 타입이 저장 되는 STREAM_TYPE 열거형값에의 포인터. 이 파라미터에 NULL 를 건네주었을 경우, 메소드는 미디어 타입을 취득하지 않는다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 파라미터의 1 개가 무효인 경우는, E_POINTER 를 돌려준다.

주의

pPurposeId 파라미터에 취득되는 값은, 보통, 프라이머리 비디오 스트림을 식별하는 MSPID_PrimaryVideo 인가, 또는 프라이머리 오디오 스트림을 식별하는 MSPID_PrimaryAudio 의 어느 쪽인지이다. 다만, 필요에 따라서 다른 값을 정의할 수도 있다.

IMediaStream::GetMultiMediaStream

IMediaStream 인터페이스

지정된 미디어 스트림이 저장 된 멀티미디어 스트림에의 포인터를 취득한다.

구문

HRESULT GetMultiMediaStream(

  IMultiMediaStream **ppMultiMediaStream

  );

파라미터

ppMultiMediaStream
[out] IMultiMediaStream 인터페이스 오브젝트에의 포인터의 주소. 이 포인터에, 현재의 미디어 스트림을 생성 할 때에 기본으로 된 미디어 스트림의 주소를 받는다.

반환값

성공했을 경우는, S_OK 를 돌려준다. ppMultiMediaStream 가 무효인 경우는, E_POINTER 를 돌려준다.

주의

이 메소드는, 취득된 오브젝트 포인터의 참조 카운트를 인크리먼트(increment) 한다.

IMediaStream::SendEndOfStream

IMediaStream 인터페이스

현재의 스트림을 강제 종료한다. 현재의 스트림이 기입해 가능하지 않은 경우, 이 메소드는 아무것도 실행하지 않는다.

구문

HRESULT SendEndOfStream(

  DWORD dwFlags

  );

파라미터

dwFlags
[in] 플래그 데이터용으로 예약되고 있다. 제로가 아니면 안 된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 기존의 샘플이 현재의 미디어 스트림과 호환이 아닌 경우는, MS_E_INCOMPATIBLE 를 돌려준다.

주의

어플리케이션으로부터 이 내부 메소드를 호출할 것은 없다.

IMediaStream::SetSameFormat

IMediaStream 인터페이스

미디어 스트림을 직전의 스트림과 같은 포맷으로 설정한다.

구문

HRESULT SetSameFormat(

  IMediaStream *pStreamThatHasDesiredFormat,

  DWORD dwFlags

  );

파라미터

pStreamThatHasDesiredFormat
[in] 같은 포맷을 가지는 미디어 스트림 오브젝트에의 포인터.
dwFlags
[in] 플래그 데이터용으로 예약되고 있다. 제로가 아니면 안 된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 파라미터의 1 개가 무효인 경우는, E_POINTER 를 돌려준다.


IMemoryData 인터페이스

IMemoryData 인터페이스에는, 오디오 데이터 오브젝트 위에의 메모리 데이터를 설정 및 취득하는 메소드가 포함된다. 오디오 데이터 오브젝트는, 스트림 샘플이 액세스 하는, 기반이 되는 데이터를 제공하는 것이다. 이 인터페이스는, 메모리 버퍼를 초기화해, 실제로 오브젝트내에 있는 오디오 데이터의 양을 설정하는 수단을 제공한다. 또,GetInfo 메소드를 사용 하면, 오디오 메모리 데이터를 취득할 수 있다.

이 인터페이스는, 오디오 스트림 샘플 오브젝트로부터 액세스 되는, 기반이 되는 오디오 데이터 오브젝트상에 이행 한다.

보통, 이러한 메소드는, 어플리케이션은 아니고,IAudioMediaStream 오브젝트 또는 IAudioStreamSample 오브젝트로부터 불려 간다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMemoryData 메소드 | 설명
SetBuffer | 메모리에의 포인터와 길이를 지정해 메모리 버퍼를 초기화한다.
GetInfo | 오디오 데이터 오브젝트를 기술하는 정보를 취득한다.
SetActual | 현재 오브젝트내에 있는 오디오 데이터의 양 (바이트 단위)을 설정한다.

IMemoryData::GetInfo

IMemoryData 인터페이스

오디오 데이터 오브젝트를 기술하는 정보를 취득한다.

구문

HRESULT GetInfo(
  DWORD *pdwLength,
  BYTE **ppbData,
  DWORD *pcbActualData );

파라미터

pdwLength
[out] 바이트 단위로 나타낸 메모리의 길이 (NULL 가 아닌 경우).
ppbData
[out] 메모리에의 포인터 (NULL 가 아닌 경우).
pcbActualData
[out] 바이트 단위로 나타낸 데이터 길이 (NULL 가 아닌 경우).

반환값

HRESULT 값을 돌려준다.

주의

이 메소드는,SetActual 에 의해 마지막에 설정된, 현재 오브젝트내에 있는 데이터의 수를 판단한다.

IMemoryData::SetActual

IMemoryData 인터페이스

현재 오브젝트내에 있는 오디오 데이터의 양을 설정한다.

구문

HRESULT SetActual(
  DWORD cbDataValid
  );

파라미터

cbDataValid
[in] 데이터의 양 (바이트 단위).

반환값

성공했을 경우는, S_OK 를 돌려준다. 필수 파라미터가 NULL 의 경우는, E_POINTER 를 돌려준다.

주의

이러한 메소드는, 보통, 어플리케이션은 아니고,IAudioMediaStream 오브젝트 또는 IAudioStreamSample 오브젝트로부터 불려 간다.

IMemoryData::SetBuffer

IMemoryData 인터페이스

메모리에의 포인터와 길이를 지정해 메모리 버퍼를 초기화한다.

구문

HRESULT SetBuffer(
  DWORD cbSize,
  BYTE *pbData,
  DWORD dwFlags );

파라미터

cbSize
[in] pbData 가 가리키는 메모리의 사이즈 (바이트 단위).
pbData
[in] 이 오브젝트가 사용하는 메모리에의 포인터.
dwFlags
[in] 플래그 데이터용으로 예약되고 있다. 제로가 아니면 안 된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. cbSize 가 0 의 경우, 또는 pbData 가 NULL 의 경우는, E_INVALIDARG 를 돌려준다.

주의

이 메소드는 필요한 만큼 반복해 호출할 수가 있다. IStreamSample::Update 을 사용해 샘플을 비동기에게 갱신할 경우에는, 샘플의 갱신이 완료하기 전에 SetBuffer 가 불려 가지 않게 주의한다.


IMultiMediaStream 인터페이스

IMultiMediaStream 인터페이스는, 멀티미디어 스트림을 제어해, 그 기반이 되는 미디어 스트림에 액세스 하는 메소드를 제공한다. 멀티미디어 스트림은, 최상정도 레벨의 스트리밍 오브젝트이며, 1 개(살) 이상의 미디어 스트림을 저장 할 수가 있다. 개개의 미디어 스트림이 미디어 타입 고유 (오디오, 비디오등)인데 대해, 멀티미디어 스트림은, 미디어 타입이 다른 다수의 스트림에의 액세스를 제공할 필요가 있기 (위해)때문에, 모든 타입에 공통이다. IMultiMediaStream 인터페이스의 메소드를 사용 하면, 특정의 스트림에의 포인터를 열거 및 취득할 수 있다. 또,IMediaStream 인터페이스의 메소드를 사용 하면, 미디어 스트림의 동작을 개별적으로 제어할 수 있다.

멀티미디어 스트리밍 인터페이스를 이행 하는 샘플 코드에 대해서는, 「멀티미디어 스트리밍의 샘플 코드」를 참조할것.

특정의 타입의 미디어 스트림에 사용하는 컨테이너를 생성 하려면 , 이 인터페이스를 이행 한다.

어플리케이션으로 멀티미디어 스트림의 기반이 되는 타입 고유의 스트림을 열거 및 제어하려면 , 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IMultiMediaStream 메소드 | 설명
GetInformation | 멀티미디어 스트림의 능력 및 스트림 타입을 취득한다.
GetMediaStream | 지정된 목적 ID 를 가지는 미디어 스트림을 취득한다.
EnumMediaStreams | 0 으로부터 시작되는 인덱스를 지정해, 멀티미디어 스트림으로부터 미디어 스트림을 취득한다.
GetState | 멀티미디어 스트림의 현재 상태를 취득한다.
SetState | 미디어 스트림을 실행 상태 또는 정지상태태로 전환한다.
GetTime | 멀티미디어 스트림의 클락에서 현재의 시간을 취득한다 (클락이 있는 경우).
GetDuration | 미디어 스트림의 시간폭을 취득한다.
Seek | 파생 미디어 스트림 모든 시크 위치를, 지정된 시간으로 설정한다.
GetEndOfStreamEventHandle | 스트림이 재생을 완료했을 때에 발행되는 이벤트의 핸들을 취득한다.

IMultiMediaStream::EnumMediaStreams

IMultiMediaStream 인터페이스

0 으로부터 시작되는 인덱스를 지정해, 멀티미디어 스트림으로부터 미디어 스트림을 취득한다.

구문

HRESULT EnumMediaStreams(

  long Index,

  IMediaStream **ppMediaStream

  );

파라미터

Index
[in] 확인하는 스트림 배열의 인덱스.
ppMediaStream
[out] IMediaStream 인터페이스 오브젝트에의 포인터의 주소. 메소드 종료시에는, 지정된 인덱스 위치에 있는 스트림에의 포인터가 저장 된다.

반환값

다음의 몇개의 값을 돌려준다.
E_POINTER | ppMediaStream 포인터가 무효.
S_FALSE | Index 가 범위외. 열거하는 스트림이 남지 않았다. 이 값이 돌려주어지는 경우,ppMediaStream 는 NULL 로 설정된다.
S_OK | 성공.

주의

이 메소드는, 스트림의 열거가 완료한 것을 나타내는 S_FALSE 가 돌려주어질 때까지, 호출하지 않으면 안 된다.

IMultiMediaStream::GetDuration

IMultiMediaStream 인터페이스

미디어 스트림의 시간폭을 돌려준다.

구문

HRESULT GetDuration(
  STREAM_TIME *pDuration
  );

파라미터

pDuration
[out] 미디어의 시간폭이 저장 되는 STREAM_TIME 값에의 포인터.

반환값

다음의 몇개의 값을 돌려준다.
E_POINTER | pDuration 의 값이 무효.
MS_E_WRITESTREAM | 기입해 가능한 미디어 스트림이므로, 시간폭이 없다.
S_FALSE | 스트림에 라이브 데이터가 포함되어 있는지, 또는 이 메소드가 시간폭을 판단할 수 없다. 메소드 종료시에는,pDuration 가 0 으로 설정된다.
S_OK | 스트림에 기록이 끝난 미디어가 포함되어 있다. 메소드 종료시에는,pDuration 에 미디어의 시간폭이 저장 된다.

IMultiMediaStream::GetEndOfStreamEventHandle

IMultiMediaStream 인터페이스

스트림이 재생을 완료했을 때에 발행되는 이벤트의 핸들을 취득한다.

구문

HRESULT GetEndOfStreamEventHandle(

  HANDLE *phEOS

  );

파라미터

phEOS
[out] 재생을 완료했을 때에 현재의 오브젝트로부터 돌려주어진 이벤트 HANDLE 에의 포인터. 오브젝트에 HANDLE 를 관련지을 수 있지 않은 경우, 이 값은 NULL 가 된다.

반환값

성공했을 경우는, S_OK 를 돌려준다. NULL 의 필수 파라미터가 있는 경우는, E_POINTER 를 돌려준다.

주의

Microsoft® Win32® 의 WaitForSingleObject 함수와 WaitForMultipleObjects 함수는, 취득된 핸들을 사용해 재생의 완료를 기다린다.

IMultiMediaStream::GetInformation

IMultiMediaStream 인터페이스

지정된 미디어 타입과 일치하는 미디어 스트림의 능력을 취득한다.

구문

HRESULT GetInformation(
  DWORD *pdwFlags,
  STREAM_TYPE *pStreamType

  );

파라미터

pdwFlags
[out] 이하의 플래그를 1 개 이상 조합한 것이 저장 되는 값에의 포인터. NULL 의 경우가 있다.
MMSSF_ASYNCHRONOUS | 스트림이 샘플의 동기 갱신을 지원 한다. IMultiMediaStream 의 이행에서는 모두 동기 갱신이 지원 된다. 이 플래그는 그것을 확인하는 것이다.
MMSSF_HASCLOCK | 스트림에 클락이 있다.
MMSSF_SUPPORTSEEK | 스트림이 시크를 지원 하고 있다.
pStreamType
[out] 파생 미디어 스트림에 대응하는 미디어 타입 정보가 저장 되는 STREAM_TYPE 열거형에의 포인터. NULL 의 경우가 있다.

반환값

HRESULT 값을 돌려준다.

주의

스트림의 능력에는, 클락의 유무, 시크를 지원 할지 어떨지, 및 비동기 갱신을 지원 할지 어떨지가 포함된다.

IMultiMediaStream::GetMediaStream

IMultiMediaStream 인터페이스

지정된 목적 ID 를 가지는 미디어 스트림을 취득한다.

구문

HRESULT GetMediaStream(
  REFMSPID idPurpose,
  IMediaStream **ppMediaStream

  );

파라미터

idPurpose
목적의 스트림을 지정하는 값.
ppMediaStream
IMediaStream 인터페이스에의 포인터의 주소. 이 포인터에, 목적의 미디어 스트림의 주소를 받는다.

반환값

다음의 몇개의 값을 돌려준다.
E_POINTER | ppMediaStream 포인터가 무효.
MS_E_NOSTREAM | 지정된 목적 ID 를 가지는 스트림이 없다.
S_OK | 성공.

주의

idPurpose 의 목적 ID 와 일치하는 스트림이 존재하는 경우에는,ppMediaStream 파라미터는 스트림을 가리켜, 그 참조 카운트가 인크리먼트(increment) 된다.

MSPID_PrimaryVideo 및 MSPID_PrimaryAudio 는, 각각 프라이머리 비디오 스트림 및 프라이머리 비디오 스트림을 나타낸다. 이것들은 가장 자주(잘) 사용되는 목적 ID 이다.

IMultiMediaStream::GetState

IMultiMediaStream 인터페이스

멀티미디어 스트림의 현재 상태를 취득한다.

구문

HRESULT GetState(

  STREAM_STATE *pCurrentState

  );

파라미터

pCurrentState
[out] 현재의 멀티미디어 스트림 상태가 저장 되는 STREAM_STATE 열거형에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. pCurrentState 가 무효인 경우는, E_POINTER 를 돌려준다.

IMultiMediaStream::GetTime

IMultiMediaStream 인터페이스

멀티미디어 스트림의 클락에서 현재의 시간을 취득한다 (클락이 있는 경우).

구문

HRESULT GetTime(

  STREAM_TIME *pCurrentTime

  );

파라미터

pCurrentTime
[out] 현재의 시간이 저장 되는 STREAM_TIME 값에의 포인터 (미디어 스트림에 클락이 있는 경우).

반환값

다음의 몇개의 값을 돌려준다.
E_POINTER | pCurrentTime 포인터가 무효.
S_FALSE | 스트림에 클락이 없다. *pCurrentTime 는 0 이 된다.
S_OK | 스트림에 클락이 있어, 메소드는 성공했다. pCurrentTime 에는 현재의 시간이 저장 된다.

주의

스트림에 클락이 없는 경우, 이 메소드는,*pCurrentTime 에 0 을 설정해, S_FALSE 를 돌려준다. 스트림에 클락이 있는 경우, 스트림 샘플의 시간은, 스트림의 클락에 대한 상대 시간이 된다.

STREAM_TIME 는 LONGLONG 값으로서 정의되고 있다.

IMultiMediaStream::Seek

IMultiMediaStream 인터페이스

포함되는 미디어 스트림 모든 시크 위치를, 지정된 시간으로 설정한다.

구문

HRESULT Seek(
  STREAM_TIME SeekTime
  );

파라미터

SeekTime
[in] 시크 시간을 지정하는 STREAM_TIME 값.

반환값

다음의 몇개의 값을 돌려준다.
E_POINTER | 포인터의 1 개가 무효.
MS_E_NOSEEKING | 시크를 지원 하지 않는 미디어 스트림이 있다.
MS_E_WRITESTREAM | 기입해 가능한 스트림이므로, 시크를 지원 하지 않는다.
S_OK | 성공.

주의

이 메소드는, 시크를 지원 하지 않는 스트림에는 기능하지 않는다. 이 메소드를 호출하기 전에,IMultiMediaStream::GetInformation 를 호출해 스트림의 능력을 취득한다. 취득된 값에 MMSSF_SUPPORTSEEK 플래그가 포함되면, 이 메소드를 호출할 수가 있다.

클락이 있는 스트림을 시크 하는 것으로써, 현재의 시간이 예측 불가능한 값 (예를 들어 목적의 시크 시간보다 전의 시간등)으로 바뀔 가능성이 있다. 그 결과, 메소드는 실패한다.

이 메소드는, 멀티미디어 스트림 오브젝트로부터 파생한 모든 미디어 스트림내의 지정된 시간까지 시크 한다.

IMultiMediaStream::SetState

IMultiMediaStream 인터페이스

미디어 스트림을 실행 상태 또는 정지상태태로 전환한다.

구문

HRESULT SetState(
  STREAM_STATE NewState
  );

파라미터

NewState
[in] 미디어 스트림의 새로운 상태를 지정하는 STREAM_STATE 열거값.

반환값

S_OK 를 돌려준다.

주의

스트림을 STREAMSTATE_STOP 로 전환하면(자), 이 메소드는 보류되고 있는 데이터를 모두 삭제한다.


IStreamSample 인터페이스

IStreamSample 인터페이스는, 스트림 샘플의 동작을 제어하는 것이다. 샘플을 생성 한 미디어 스트림을 취득해, 샘플의 시작 타임과 종료 타임을 설정 또는 취득해, 샘플의 완료 상태를 확인해, 샘플 자체에 개발자가 지정한 함수를 실행할 수가 있다.

새로운 미디어 타입의 미디어 스트림을 이행 할 경우에는, 이 인터페이스를 이행 한다. 이 인터페이스는, 미디어 스트림이 생성 한 샘플 오브젝트상에서 공개된다.

IMediaStream 가 생성 한 데이터 샘플 또는 그 파생 인터페이스를 제어하려면 , 이 인터페이스를 사용한다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IStreamSample 메소드 | 설명
GetMediaStream | 현재의 샘플을 생성 한 미디어 스트림 오브젝트에의 포인터를 취득한다.
GetSampleTimes | 현재의 샘플의 시작 타임과 종료 타임을 취득한다.
SetSampleTimes | 현재의 샘플의 시작 타임과 종료 타임을 설정한다.
Update | 현재의 샘플을 동기 또는 비동기에게 갱신한다.
CompletionStatus | 현재의 샘플에 행해진 마지막 비동기 갱신 상태를 취득한다. 갱신이 완료하고 있지 않는 경우에는 강제 종료할 수 있다.

IStreamSample::CompletionStatus

IStreamSample 인터페이스

현재의 샘플에 행해진 마지막 비동기 갱신 상태를 취득한다. 갱신이 완료하고 있지 않는 경우에는 강제 종료할 수 있다.

구문

HRESULT CompletionStatus(
  DWORD dwFlags,
  DWORD dwMilliseconds
  );

파라미터

dwFlags
[in] 갱신을 강제 종료할지 어떨지를 지정하는 값. 이 값은, 이하의 플래그를 1 개 이상 조합한 것이다.
COMPSTAT_NOUPDATEOK (0x01) | 샘플 갱신이 완료하고 있지 않는 경우도 포함해 갱신을 할 수 있는 한 빨리 강제 종료한다. 샘플이 갱신중으로, COMPSTAT_WAIT 플래그가 설정되어 있지 않은 경우, 메소드는 MS_S_PENDING 를 돌려준다. 샘플이 갱신 기다리는 경우, 메소드는 샘플을 큐로부터 삭제해, MS_S_NOTUPDATED 를 돌려준다.
COMPSTAT_WAIT (0x02) | 샘플 갱신의 종료를 기다린 데다가, 메소드로부터 돌아온다.
COMPSTAT_ABORT (0x04) | 샘플이 현재 갱신중의 경우도 포함해 갱신을 강제 종료한다. 이 방법에서는, 샘플 데이터 상태가 부정이 된다. 갱신을 확실히 캔슬하려면 , COMPSTAT_WAITFORCOMPLETION 플래그와 조합한다.
dwMilliseconds
[in] dwFlags 파라미터가 COMPSTAT_WAIT 의 경우, 이 값은 갱신 완료를 기다리는 대기 시간 (밀리 세컨드 단위)이 된다. 샘플 갱신이 완료할 때까지 기다리고 나서 메소드가 돌아오도록(듯이) 하려면 , INFINITE 를 지정한다.

반환값

다음의 몇개의 값을 돌려준다.
E_ABORT | 갱신이 중지되었다.
MS_S_ENDOFSTREAM | 스트림의 종단에 이르렀기 때문에, 샘플이 갱신되지 않았다.
MS_S_NOUPDATE | 갱신이 강제 종료되어 샘플이 스트림에 의해 갱신되지 않았다.
MS_S_PENDING | 비동기 갱신이 보류되고 있다.
S_OK | 성공.

IStreamSample::GetMediaStream

IStreamSample 인터페이스

현재의 샘플을 생성 한 미디어 스트림 오브젝트에의 포인터를 취득한다.

구문

HRESULT GetMediaStream(

  IMediaStream **ppMediaStream

  );

파라미터

ppMediaStream
[in] IMediaStream 인터페이스에의 포인터의 주소. 이 포인터에, 현재의 샘플을 생성 한 미디어 스트림의 주소를 받는다.

반환값

성공했을 경우는, S_OK 를 돌려준다. ppMediaStream 가 무효인 경우는, E_POINTER 를 돌려준다.

주의

성공했을 경우, 이 메소드는 ppMediaStream 로 지정된 미디어 스트림의 참조 카운트를 인크리먼트(increment) 한다.

IStreamSample::GetSampleTimes

IStreamSample 인터페이스

현재의 샘플의 시작 타임과 종료 타임을 취득한다. 샘플이 갱신중의 경우, 이 메소드는 갱신 완료 후의 시간을 돌려준다.

구문

HRESULT GetSampleTimes(

  STREAM_TIME *pStartTime,

  STREAM_TIME *pEndTime,

  STREAM_TIME *pCurrentTime

  );

파라미터

pStartTime
[out] 샘플의 시작 타임이 저장 되는 STREAM_TIME 값에의 포인터.
pEndTime
[out] 샘플의 종료 타임이 저장 되는 STREAM_TIME 값에의 포인터.
pCurrentTime
[out] 미디어 스트림의 현재의미디어 타임이 저장 되는 STREAM_TIME 값에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 파라미터의 1 개가 무효인 경우는, E_POINTER 를 돌려준다.

주의

스트림에 클락이 있는 경우, 시작 타임과 종료 타임은 스트림의 현재 시간에 대한 상대 시간이 된다. 스트림에 클락이 없는 경우, 시작 타임과 종료 타임은 미디어에 대한 상대 시간이며, 현재 시간은 0 이 된다.

pCurrentTime 파라미터를 사용 하면, 미디어 스트림의 현재 시간을 간단하게 추적할 수 있기 (위해)때문에,IMultiMediaStream::GetTime 를 호출하지 않고 끝난다. 다만, 스트림에 클락이 없는 경우,GetTime 는 S_FALSE 를 돌려주지만, 이 메소드는 S_OK 를 돌려준다. pCurrentTime 에 할당할 수 있는 값은, 다음의 코드로 생성되는 값과 같다.

pSample->GetMediaStream(&pMediaStream);
pMediaStream->GetMultiMediaStream(&pMultiMediaStream);
pMediaStream->Release();
pMultiMediaStream->GetTime(&pCurrentTime);
pMultiMediaStream->Release();

IStreamSample::SetSampleTimes

IStreamSample 인터페이스

현재의 샘플의 시작 타임과 종료 타임을 설정한다. 이 메소드는, 샘플을 갱신하기 전에 호출할 수가 있다.

구문

HRESULT SetSampleTimes(

  const STREAM_TIME *pStartTime,

  const STREAM_TIME *pEndTime

  );

파라미터

pStartTime
[in] 샘플의 새로운 시작 타임이 저장 된 STREAM_TIME 값에의 포인터.
pEndTime
[in] 샘플의 새로운 종료 타임이 저장 된 STREAM_TIME 값에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 파라미터의 1 개가 NULL 의 경우는, E_POINTER 를 돌려준다.

주의

스트림에 클락이 있는 경우, 시작 타임과 종료 타임은 스트림의 현재 시간에 대한 상대로 지정한다. 스트림에 클락이 없는 경우, 시작 타임과 종료 타임은 미디어에 대한 상대로 지정한다.

이 메소드는, 기입해 가능한 스트림에게만 적용된다.

IStreamSample::Update

IStreamSample 인터페이스

현재의 샘플을 동기 또는 비동기에게 갱신한다.

구문

HRESULT Update(
  DWORD dwFlags,
  HANDLE hEvent,
  PAPCFUNC pfnAPC,
  DWORD dwAPCData
  );

파라미터

dwFlags
[in] 갱신이 동기나 비동기인지를 지정하는 플래그. SSUPDATE_ASYNC 플래그는, 비동기의 갱신을 나타내,hEvent 와 pfnAPC 의 양쪽 모두가 NULL 의 경우로 설정할 수가 있다. IStreamSample::CompletionStatus 메소드를 호출할 때까지 샘플을 연속적으로 갱신하려면 , SSUPDATE_CONTINUOUS 를 지정한다.
hEvent
[in] 갱신 완료시에 이 메소드가 발행하는 이벤트에의 핸들.
pfnAPC
[in] 갱신 완료시에 이 메소드가 호출하는 Win32 비동기 프로시저 호출 (APC) 함수에의 포인터.
dwAPCData
[in] pfnAPC 파라미터로 지정된 함수에 이 메소드가 건네주는 값.

반환값

다음의 몇개의 값을 돌려준다.
E_ABORT | 갱신이 중지되었다.
E_INVALIDARG | 파라미터의 1 개가 무효.
E_POINTER | 파라미터의 1 개가 무효.
MS_E_BUSY | 이 샘플에는 이미 보류중의 갱신이 있다.
MS_S_ENDOFSTREAM | 스트림 종단에 이르렀다. 샘플은 갱신되지 않는다.
MS_S_PENDING | 비동기 갱신이 보류되고 있다.
S_OK | 성공.

주의

이 메소드를 사용 하면, 샘플의 동기 갱신 또는 비동기 갱신을 실행할 수 있다. hEvent 와 pfnAPC 의 양쪽 모두가 NULL 의 경우, SSUPDATE_ASYNC 플래그와 SSUPDATE_CONTINUOUS 플래그의 어느 쪽인지를 지정하지 않는 한, 갱신은 동기가 된다. 동기 갱신으로부터 돌아왔을 때에는, 함수의 결과에 I/O 의 완료 상태가 저장 되고 있다.

hEvent 와 pfnAPC 의 양쪽 모두에 값을 지정할 수 없다. 지정했을 경우, 메소드는 실패한다.

비동기 갱신은, 갱신으로부터 돌아오기 전에 완료할 가능성이 있다. 이 경우, 반환값은 S_OK 가 된다. 이벤트를 지정했을 경우, 갱신으로부터 S_OK 가 돌려주어지면(자), 이 메소드는 종료시에 이벤트를 설정한다. APC 함수를 지정했을 경우, 갱신으로부터 S_OK 가 돌려주어졌을 때에는, APC 가 큐에 넣어지는 일도, 함수가 불려 갈 것도 없다.

돌아오기 전에 완료하지 않는 비동기 갱신은, 값 MS_S_PENDING 를 돌려준다.

어플리케이션이 복수의 스트림을 생성 하는 경우, 각각의 스트림으로 비동기 갱신을 실행해야 한다. WaitForMultipleObjects 를 호출해, 각각의 스트림의 갱신이 완료하는 것을 기다리고 나서, 다음의 갱신을 실시한다. 이와 같이 하지 않으면 어플리케이션이 블록 할 가능성이 있다.


멀티미디어 스트리밍 데이터 타입

여기에서는, Microsoft® DirectShow® 멀티미디어 스트리밍의 데이터 타입에 대해 설명한다.
데이터 타입 | 설명
MSPID | 미디어 스트림의 목적을 정의하는 목적 ID. 목적 ID 는 typedef 로 GUID 로서 선언할 수 있다.
STREAM_STATE | 스트림 상태를 기술한다.
STREAM_TIME | 100 나노초단위의스트림 타임 . 이 데이터 타입은 64 비트 정수 (LONGLONG)로서 정의된다.
STREAM_TYPE | 스트림의 데이터가 흐를 방향을 정의한다.

STREAM_STATE

멀티미디어 스트리밍 데이터 타입

스트림 상태를 기술한다.

구문

typedef enum {
    STREAMSTATE_STOP        = 0,
    STREAMSTATE_RUN         = 1
} STREAM_STATE;

요소

STREAMSTATE_STOP
정지상태태.
STREAMSTATE_RUN
실행 상태.

주의

IMultiMediaStream::SetState 메소드를 호출해 상태를 변경한다.

STREAM_TYPE

멀티미디어 스트리밍 데이터 타입

스트림의 데이터가 흐를 방향을 정의한다.

구문

typedef enum {
    STREAMTYPE_READ         = 0,
    STREAMTYPE_WRITE        = 1,
    STREAMTYPE_TRANSFORM    = 2
} STREAM_TYPE;

요소

STREAMTYPE_READ
어플리케이션으로부터 스트림을 읽어낼 수가 있다.
STREAMTYPE_WRITE
어플리케이션으로부터 스트림에 기입할 수가 있다.
STREAMTYPE_TRANSFORM
어플리케이션으로부터 스트림을 읽고 쓰기할 수 있다.

주의

변환 스트림은 읽고 쓰기 가능하고, 샘플이 같은 위치에 써 되돌려진다.


멀티미디어 스트리밍의 에러 코드와 성공 코드

다음의 일람은, 멀티미디어 스트리밍 인터페이스를 사용하는 어플리케이션에게 건네지는 에러 메세지와 성공 통지이다. 다만, 가능한 에러에는 이 일람에 없는 것도 있다. 이러한 에러는, Microsoft® DirectShow® 에 의한 멀티미디어 스트리밍 인터페이스의 이행에 고유의 에러에만 적용된다. 성공 코드는, MS_S 로 시작되어, SUCCEEDED 매크로로부터의 TRUE 를 돌려주는지, 또는 FAILED 매크로로부터의 FALSE 를 돌려준다.
메세지 | 16 진코드 | 의미
MS_S_PENDING | 0x00040001 | 샘플의 갱신이 아직 완료하고 있지 않다.
MS_S_NOUPDATE | 0x00040002 | 강제 종료후에 샘플이 갱신되지 않았다.
MS_S_ENDOFSTREAM | 0x00040003 | 스트림 종료. 샘플은 갱신되어 있지 않다.
MS_E_SAMPLEALLOC | 0x80040401 | 할당하고 끝난 샘플이 적어도 1 개(살) 포함되어 있기 (위해)때문에,IMediaStream 오브젝트를 IMultiMediaStream 오브젝트로부터 삭제할 수 없다.
MS_E_PURPOSEID | 0x80040402 | 지정된 목적 ID 는 호출에 사용할 수 없다.
MS_E_NOSTREAM | 0x80040403 | 지정된 속성을 가지는 스트림이 발견되지 않는다.
MS_E_NOSEEKING | 0x80040404 | 이 IMultiMediaStream 오브젝트에서는 시크가 지원 되지 않는다.
MS_E_INCOMPATIBLE | 0x80040405 | 스트림 포맷이 호환이 아니다.
MS_E_BUSY | 0x80040406 | 샘플이 사용중.
MS_E_NOTINIT | 0x80040407 | 초기화 함수 또는 거기에 상당하는 것이 불려 가지 않기 때문에, 오브젝트가 호출을 받아들일 수 없다.
MS_E_SOURCEALREADYDEFINED | 0x80040408 | 소스가 이미 정의되고 있다.
MS_E_INVALIDSTREAMTYPE | 0x80040409 | 스트림 타입이 이 조작에 유효하지 않다.
MS_E_NOTRUNNING | 0x8004040A | IMultiMediaStream 오브젝트가 실행 상태에 없다.


멀티미디어 스트리밍 컴퍼넌트 오브젝트

여기에서는, Microsoft® DirectShow® 가 지원 하는 각종 컴퍼넌트의 일람을 기재한다. 이러한 오브젝트는, 멀티미디어 스트리밍 인터페이스를 지원 한다. 또, 컴퍼넌트 오브젝트의 계층 구조도도 기재한다.

이하의 항으로 구성된다.

  • 컴퍼넌트 오브젝트의 일람
  • 오브젝트 참조도

컴퍼넌트 오브젝트의 일람

이 항에서는, DirectShow 가 지원 하는 각종 컴퍼넌트에 대해 설명한다.
오브젝트 | 설명 | 지원 되는 인터페이스
CLSID_AMMultiMediaStream | DirectShow 에 의한 멀티미디어 스트림의 이행 | IAMMultiMediaStream ,IMultiMediaStream
CLSID_MediaStreamFilter | IAMMultiMediaStream 인터페이스를 통해서, CLSID_AMMultiMediaStream 오브젝트에 대응하는 멀티미디어 스트리밍 기능을 제공한다 | IBaseFilter
CLSID_AMDirectDrawStream | DirectShow 멀티미디어 스트림에 추가할 수 있는 Microsoft® DirectDraw® 미디어 스트림 | IAMMediaStream ,IMediaStream ,IDirectDrawMediaStream ,IPin ,IMemInputPin
DirectDraw 스트림에 의해 생성 된 샘플 |  | IStreamSample ,IDirectDrawStreamSample ,IMediaSample
CLSID_ AMMediaTypeStream | DirectShow 로 지원 되는 임의의 데이터 타입에 대응하는 미디어 샘플을 생성 할 수 있다 | IAMMediaStream ,IMediaStream ,IPin ,IMemInputPin
CLSID_ AMMediaTypeStream 오브젝트에 의해 생성 된 샘플 |  | IStreamSample ,IMediaSample ,IMediaSample2
CLSID_AMAudioData | IAudioData 오디오 컨테이너 오브젝트의 이행 | IAudioData

오브젝트 참조도

오브젝트의 계층 구조에는, DirectShow 오브젝트간에 관심이 많은 순환 참조가 몇개인가 존재한다. 다음의 그림은, 모든 오브젝트와 그 참조를 나타낸다. 실선은 강한 참조 (참조되는 오브젝트를 인크리먼트(increment) 하는 것), 점선은 약한 참조 (참조되는 오브젝트에 대해서 AddRef 를 실행하지 않는 것)를 나타내고 있다.

샘플은 멀티미디어 스트림 오브젝트에의 강한 참조를 보관 유지하지만, 미디어 스트림은 보관 유지하지 않는다.


멀티미디어 스트리밍의 샘플 코드

여기에는, 멀티미디어 스트리밍 인터페이스를 이행 하는 샘플 코드를 기재한다. 비디오 스트리밍의 샘플 코드는, 파일을 읽어내, 그것을 프라이머리 Microsoft® DirectDraw® 표면에 렌더링 하는 방법을 나타낸다. 이 코드에서는 간결함 때문에, 에러 체크가 생략 되고 있다.

2 번째의 샘플 코드는, 오디오 스트리밍 인터페이스를 사용해 오디오 데이터를 스트림 하는 방법을 나타낸다.

이하의 항으로 구성된다.

  • 비디오 스트리밍의 샘플 코드
  • 오디오 스트리밍의 샘플 코드

비디오 스트리밍의 샘플 코드

이 샘플 코드에서는, 파일을 읽어내, 그것을 프라이머리 DirectDraw 표면에 렌더링 한다.

#include <stdio.h>
#include "ddraw.h"       // DirectDraw 인터페이스
#include "mmstream.h"    // 멀티미디어 스트림 인터페이스
#include "amstream.h"    // DirectShow 멀티미디어 스트림 인터페이스
#include "ddstream.h"    // DirectDraw 멀티미디어 스트림 인터페이스

void RenderStreamToSurface(IDirectDrawSurface *pSurface,
    IMultiMediaStream *pMMStream)
{
    IMediaStream *pPrimaryVidStream;
    IDirectDrawMediaStream *pDDStream;
    IDirectDrawStreamSample *pSample;
    RECT rect;
    DDSURFACEDESC ddsd;

    pMMStream->GetMediaStream(MSPID_PrimaryVideo, &pPrimaryVidStream);
    pPrimaryVidStream->QueryInterface(IID_IDirectDrawMediaStream, (void **) &pDDStream);
    ddsd.dwSize = sizeof(ddsd);
    pDDStream->GetFormat(&ddsd, NULL, NULL, NULL);
    rect.top = rect.left = 0;
    rect.bottom = ddsd.dwHeight;
    rect.right = ddsd.dwWidth;
    pDDStream->CreateSample(pSurface, &rect, 0, &pSample);

    pMMStream->SetState(STREAMSTATE_RUN);
    while (pSample->Update(0, NULL, NULL, NULL) == S_OK);
    pMMStream->SetState(STREAMSTATE_STOP);

    pSample->Release();
    pDDStream->Release();
    pPrimaryVidStream->Release();
}

void RenderFileToMMStream(const char * szFileName,
    IMultiMediaStream **ppMMStream,
    IDirectDraw *pDD)
{
IAMMultiMediaStream *pAMStream;
CoCreateInstance(CLSID_AMMultiMediaStream, NULL, CLSCTX_INPROC_SERVER,
    IID_IAMMultiMediaStream, (void **) &pAMStream);
    WCHAR    wPath[MAX_PATH];        // 와이드 (32 비트) 캐릭터 라인명
    MultiByteToWideChar(CP_ACP, 0, szFileName, -1, wPath,
        sizeof(wPath) /sizeof(wPath[0]));

    pAMStream->Initialize(STREAMTYPE_READ, AMMSF_NOGRAPHTHREAD, NULL);
    pAMStream->AddMediaStream(pDD, &MSPID_PrimaryVideo, 0, NULL);
    pAMStream->AddMediaStream(NULL, &MSPID_PrimaryAudio, AMMSF_ADDDEFAULTRENDERER, NULL);
    pAMStream->OpenFile(wPath, 0);
    *ppMMStream = pAMStream;
}

int _CRTAPI1 main(int argc, char *argv[])
{
    if (argc < 2) {
    printf("Usage : showstrm movie.ext\n");
    exit(0);}

    DDSURFACEDESC ddsd;
    IDirectDraw *pDD;
    IDirectDrawSurface *pPrimarySurface;
    IMultiMediaStream *pMMStream;

    CoInitialize(NULL);

    DirectDrawCreate(NULL, &pDD, NULL);
    pDD->SetCooperativeLevel(GetDesktopWindow(), DDSCL_NORMAL);
    ddsd.dwSize = sizeof(ddsd);
    ddsd.dwFlags = DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
    pDD->CreateSurface(&ddsd, &pPrimarySurface, NULL);
    RenderFileToMMStream(argv[1], &pMMStream, pDD);
    RenderStreamToSurface(pPrimarySurface, pMMStream);
    pMMStream->Release();
    pPrimarySurface->Release();
    pDD->Release();

CoUninitialize();
return 0;
}

오디오 스트리밍의 샘플 코드

다음의 샘플 코드는,IAudioMediaStream ,IAudioStreamSample ,IMemoryData , 및 IAudioData 의 4 개의 인터페이스를 사용해 오디오 데이터를 스트림 하는 방법을 나타낸다.

#include <windows.h>
#include <mmsystem.h>
#include <amstream.h>

/********************************************************************

   간단한 웨이브 플레이어 처리

 ********************************************************************/

class CWaveBuffer;

class CWaveBuffer {
public:
        CWaveBuffer();
        ~CWaveBuffer();
        BOOL Init(HWAVEOUT hWave, int Size);
        void Done();
        BOOL Write(PBYTE pData, int nBytes, int& BytesWritten);
void Flush();

private:
        WAVEHDR      m_Hdr;
        HWAVEOUT     m_hWave;
        int          m_nBytes;
};

class CWaveOut {
public:
        CWaveOut(LPCWAVEFORMATEX Format, int nBuffers, int BufferSize);
        ~CWaveOut();
        void Write(PBYTE Data, int nBytes);
void Flush();
        void Wait();
        void Reset();
private:
        const HANDLE   m_hSem;
        const int      m_nBuffers;
        int            m_CurrentBuffer;
        BOOL           m_NoBuffer;
        CWaveBuffer   *m_Hdrs;
        HWAVEOUT     m_hWave;
};

/*
    CWaveBuffer
*/

CWaveBuffer::CWaveBuffer()
{
}

BOOL CWaveBuffer::Init(HWAVEOUT hWave, int Size)
{
    m_hWave  = hWave;
    m_nBytes = 0;

    /*  버퍼를 할당해 헤더를 초기화한다.  */
    m_Hdr.lpData = (LPSTR) LocalAlloc(LMEM_FIXED, Size);
    if (m_Hdr.lpData == NULL) {
return FALSE;
    }
    m_Hdr.dwBufferLength  = Size;
    m_Hdr.dwBytesRecorded = 0;
    m_Hdr.dwUser = 0;
    m_Hdr.dwFlags = 0;
    m_Hdr.dwLoops = 0;
    m_Hdr.lpNext = 0;
    m_Hdr.reserved = 0;

    /*  준비를 한다.  */
    waveOutPrepareHeader(hWave, &m_Hdr, sizeof(WAVEHDR));

return TRUE;
}

CWaveBuffer::~CWaveBuffer() {
    if (m_Hdr.lpData) {
        waveOutUnprepareHeader(m_hWave, &m_Hdr, sizeof(WAVEHDR));
        LocalFree(m_Hdr.lpData);
    }
}

void CWaveBuffer::Flush()
{
    // ASSERT(m_nBytes ! = 0);
m_nBytes = 0;
waveOutWrite(m_hWave, &m_Hdr, sizeof(WAVEHDR));
}

BOOL CWaveBuffer::Write(PBYTE pData, int nBytes, int& BytesWritten)
{
    // ASSERT((DWORD) m_nBytes ! = m_Hdr.dwBufferLength);
    BytesWritten = min((int) m_Hdr.dwBufferLength - m_nBytes, nBytes);
    CopyMemory((PVOID)(m_Hdr.lpData + m_nBytes), (PVOID) pData, BytesWritten);
    m_nBytes += BytesWritten;
    if (m_nBytes == (int) m_Hdr.dwBufferLength) {
        /*  기입한다.  */
m_nBytes = 0;
waveOutWrite(m_hWave, &m_Hdr, sizeof(WAVEHDR));
return TRUE;
    }
return FALSE;
}

void CALLBACK WaveCallback(HWAVEOUT hWave, UINT uMsg, DWORD dwUser,
                           DWORD dw1, DWORD dw2)
{
    if (uMsg == WOM_DONE) {
        ReleaseSemaphore((HANDLE) dwUser, 1, NULL);
    }
}

/*
    CWaveOut
*/

CWaveOut::CWaveOut(LPCWAVEFORMATEX Format, int nBuffers, int BufferSize) :
    m_nBuffers(nBuffers),
    m_CurrentBuffer(0),
    m_NoBuffer(TRUE),
    m_hSem(CreateSemaphore(NULL, nBuffers, nBuffers, NULL)),
    m_Hdrs(new CWaveBuffer[nBuffers]),
    m_hWave(NULL)
{
    /*  웨이브 디바이스를 생성 한다.  */
    waveOutOpen(&m_hWave,
                WAVE_MAPPER,
                Format,
                (DWORD) WaveCallback,
                (DWORD) m_hSem,
                CALLBACK_FUNCTION);

    /*  웨이브 버퍼를 초기화한다.  */
    for (int i = 0; i < nBuffers; i++) {
        m_Hdrs[i]. Init(m_hWave, BufferSize);
    }
}

CWaveOut::~CWaveOut()
{
    /*  우선, 버퍼를 리셋 한다.  */
    waveOutReset(m_hWave);

    /*  버퍼를 해방한다.  */
    delete [] m_Hdrs;

    /*  웨이브 디바이스를 닫는다.  */
    waveOutClose(m_hWave);

    /*  semaphore를 해방한다.  */
    CloseHandle(m_hSem);
}

void CWaveOut::Flush()
{
    if (! m_NoBuffer) {
        m_Hdrs[m_CurrentBuffer]. Flush();
        m_NoBuffer = TRUE;
        m_CurrentBuffer = (m_CurrentBuffer + 1) % m_nBuffers;
    }
}

void CWaveOut::Reset()
{
waveOutReset(m_hWave);
}

void CWaveOut::Write(PBYTE pData, int nBytes)
{
    while (nBytes ! = 0) {
        /*  필요하면 버퍼를 취득한다.  */
        if (m_NoBuffer) {
WaitForSingleObject(m_hSem, INFINITE);
            m_NoBuffer = FALSE;
        }

        /*  버퍼에 기입한다.  */
        int nWritten;
        if (m_Hdrs[m_CurrentBuffer]. Write(pData, nBytes, nWritten)) {
            m_NoBuffer = TRUE;
            m_CurrentBuffer = (m_CurrentBuffer + 1) % m_nBuffers;
            nBytes -= nWritten;
            pData += nWritten;
        } else {
            // ASSERT(nWritten == nBytes);
break;
        }
    }
}

void CWaveOut::Wait()
{
    /*  남아 있는 버퍼를 모두 보낸다.  */
    Flush();

    /*  버퍼가 돌아올 때까지 기다린다.  */
    for (int i = 0; i < m_nBuffers; i++) {
        WaitForSingleObject(m_hSem, INFINITE);
    }
    LONG lPrevCount;
    ReleaseSemaphore(m_hSem, m_nBuffers, &lPrevCount);
}

/************************************************************

  웨이브 플레이어 처리는 여기까지

 ************************************************************/

HRESULT RenderStreamToDevice(IMultiMediaStream *pMMStream)
{
    WAVEFORMATEX wfx;
    #define DATA_SIZE 5000
    PBYTE pBuffer = (PBYTE) LocalAlloc(LMEM_FIXED, DATA_SIZE);

    IMediaStream *pStream;
    IAudioStreamSample *pSample;
    IAudioMediaStream *pAudioStream;
    IAudioData *pAudioData;

    pMMStream->GetMediaStream(MSPID_PrimaryAudio, &pStream);
    pStream->QueryInterface(IID_IAudioMediaStream, (void **) &pAudioStream);
    pAudioStream->GetFormat(&wfx);
    CoCreateInstance(CLSID_AMAudioData, NULL, CLSCTX_INPROC_SERVER,
                                    IID_IAudioData, (void **) &pAudioData);
    pAudioData->SetBuffer(DATA_SIZE, pBuffer, 0);
    pAudioData->SetFormat(&wfx);
    pAudioStream->CreateSample(pAudioData, 0, &pSample);
    HANDLE hEvent = CreateEvent(FALSE, NULL, NULL, FALSE);
    CWaveOut WaveOut(&wfx, 4, 2048);
    int iTimes;
    for (iTimes = 0; iTimes < 3; iTimes++) {
        DWORD dwStart = timeGetTime();
        for (; ; ) {
            HRESULT hr = pSample->Update(0, hEvent, NULL, 0);
            if (FAILED(hr) || MS_S_ENDOFSTREAM == hr) {
break;
            }
            WaitForSingleObject(hEvent, INFINITE);
            DWORD dwTimeDiff = timeGetTime() - dwStart;
            // 10 초 이내로 한정한다
            if (dwTimeDiff > 10000) {
break;
            }
            DWORD dwLength;
            pAudioData->GetInfo(NULL, NULL, &dwLength);
            WaveOut.Write(pBuffer, dwLength);
        }
        pMMStream->Seek(0);
    }

    pAudioData->Release();
    pSample->Release();
    pStream->Release();
    pAudioStream->Release();
    LocalFree((HLOCAL) pBuffer);

return S_OK;
}

HRESULT RenderFileToMMStream(
    WCHAR * pszFileName, IMultiMediaStream **ppMMStream)
{
IAMMultiMediaStream *pAMStream;
CoCreateInstance(CLSID_AMMultiMediaStream, NULL, CLSCTX_INPROC_SERVER,
IID_IAMMultiMediaStream, (void **) &pAMStream);
pAMStream->Initialize(STREAMTYPE_READ, AMMSF_NOGRAPHTHREAD, NULL);
    pAMStream->AddMediaStream(NULL, &MSPID_PrimaryAudio, 0, NULL);
    pAMStream->OpenFile(pszFileName, AMMSF_RUN);
*ppMMStream = pAMStream;
return S_OK;
}

int _CRTAPI1 main(int argc, char *argv[])
{
IMultiMediaStream *pMMStream;
CoInitialize(NULL);
    WCHAR wszName[1000];
    MultiByteToWideChar(CP_ACP, 0, argv[1], -1, wszName,
        sizeof(wszName) / sizeof(wszName[0]));
    RenderFileToMMStream(wszName, &pMMStream);
    RenderStreamToDevice(pMMStream);
pMMStream->Release();
CoUninitialize();
return 0;
}


SMPTE 타임 코드

이 주제에서는, SMPTE (Society of Motion Picture and Television Engineers) 타임 코드에 대해 해설한다. 프로덕션 환경에서의 타임 코드의 사용 방법에 대해서도 설명해, 외부 디바이스에 의존하는 어플리케이션으로 대표적인 것을 몇개인가 가리킨다. 마지막으로, Microsoft® DirectShow® 에 외부 디바이스 제어를 이행 하는 방법을 해설해, DirectShow 로 VCR 제어와 타임 코드에 대응한 필터를 생성 하기 위해서 사용할 수 있는 인터페이스에의 링크를 준다.

이 주제는, 이하의 섹션으로 구성된다.

  • SMPTE 타임 코드에 대해
  • 타임 코드의 전형적인 사용 방법
  • 타임 코드의 캡춰
  • 외부 디바이스 제어
  • 참고서와 보충 자료

SMPTE 타임 코드에 대해

SMPTE 타임 코드는, 포스트프로덕션 처리를 이어 맞추는 접착제이다. 비디오 및 오디오의 소스를 식별해, 트럭의 자동 동기를 가능하게 해, 프로덕션에 관련하는 보조 데이터의 컨테이너를 제공한다. 이 데이터 스트림을 이해 함과 동시에, 미디어 프로덕션, 툴 개발, 또는 시스템 설계에의 응용에 대해 이해하는 것이 필요하게 된다.

SMPTE 타임 코드는, 정확하게는 SMPTE 타임 및 제어 코드로서 알려져 ANSI/SMPTE 12-1986 로 정의되고 있다. SMPTE 타임 코드는, 비디오 또는 오디오 스트림에 적용되는 디지털 프레임의 주소값, 플래그, 및 그 외의 일련의 데이터이다. SMPTE 타임 코드의 목적은, 머신이 판독 가능한 비디오 또는 오디오의 주소를 제공하는 것이다.

SMPTE 타임 코드 데이터 구조체의 가장 일반적인 포맷은, 이하의 정보가 포함되는 80 비트의 프레임이다.

  • hh:mm:ss:ff (시간:분:초:프레임) 포맷에서의타임 스탬프 .
  • 일반적으로 유저 비트로서 알려진 8 개의 4 비트 바이너리 그룹.
  • 다양한 flag bit.
  • 동기 순서.
  • 체크 섬.

DirectShow 의 TIMECODE_SAMPLE 구조체는, 비디오 데이터나 오디오 데이터의 타임 코드 정보가 포함되는 타임 코드 데이터 구조체의 예이다.

SMPTE 타임 코드에는 2 개의 타입이 있다. 아날로그 오디오 트럭에바이페즈마크로 encode 된 신호로서 기록되는 타임 코드는,LTC (Linear TimeCode, 이전에는 Longitudinal TimeCode)로 불린다. 타임 코드의 각 프레임은, 시간폭내의 1 개의 비디오 프레임 타임이다. 타임 코드의 이제(벌써) 1 개(살)의 일반적인 타입은, VITC (Vertical TimeCode)로 불린다. 보통, VITC 는 비디오 신호의수직 동기 간격의 라인 10 ~ 20 안의 2 라인에 저장 된다.

LTC 타임 코드는, 독립한 오디오 신호에 encode 되므로, 녹화 끝난 테이프에 간단하게 추가할 수 있다. 그러나, 테이프가 포즈 하고 있거나 초저속 또는 초고속으로 움직이고 있을 때는 읽어낼 수가 없다. 또, 프로 사양이 아닌 VCR 에서는 1 개의 오디오 채널을 소비한다.

한편, VITC 타임 코드는, 보통 속도의 0 ~ 15 배의 속도로 읽어낼 수가 있다. 필드에 의존하는 데이터를 포함할 수가 있어 비디오 캡쳐 카드로부터 읽어낼 수도 있다. 그러나, 녹화 끝난 테이프에 추가하는 것은 간단하지 않고, 고가의 하드웨어가 필요하게 되는 것이 많다.

SMPTE 타임 코드에는 2 개의 모드가 있다. 논드롭후레임과 드롭 프레임이다. 논드롭후레임은, 일관해 증가하고 있는 시퀀셜인 타임 코드이다. 리얼타임 클락의 역할을 완수할 수가 있어 정확히 30 프레임/초의 frame rate로 재생되는 흑백 비디오의 경우에 잘 기능한다.

다만,NTSC 칼라 비디오는 흑백 TV와의 호환성의 문제를 위해서(때문에), 실제로는 29.97 Hz (프레임/초)의 frame rate로 재생된다. 이것에 의해, 1 시간당 108 프레임 (3.6 초)의 비율로 실제의 시간으로 일치하지 않게 되어, 논드롭후레임타임코드에서는 문제가 발생한다. 즉, 시작점을 00:00:00:00 과 하면, 1 시간의 재생 후에 타임 코드는 00:59:56:12 이 된다고 하는 것이다. 이 때문에, 표시 시간폭을 계산하거나"시각 " 를 참조하거나 하면 문제가 발생한다.

이 문제의 해결책은, 오차를 허용 할 수 있는 레벨이 되는 정도로 프레임을 날리는 것이다. 이 보정법을 "드롭 프레임 " 라고 불러, 00, 10, 20, 30, 40, 및 50 분을 제외해, 1 분 마다 최초의 2 개의 프레임을 날리는 것으로 이행 한다. 최종적으로, 에러는 1 프레임/시간 미만이 되어, 24 시간당 3 프레임 정도가 된다.

어떠한 이행으로 양모드의 혼합을 지원 해야 하지만, 현재의 프로덕션에서는 드롭 프레임의 사용이 한층 더 일반적으로 되어 있다.

타임 코드의 전형적인 사용 방법

보통, 비디오 캡춰와 편집 기능을 제공하는 어플리케이션은, 외부 디바이스의 제어를 필요로 한다. 이러한 어플리케이션은, SMPTE 타임 코드를 참조해, 비디오 및 오디오의 프레임을 식별해, 인덱스부를 할 필요가 있다. 리니어 편집 시스템 컴퓨터는, 일반적으로 3 대 이상의 테이프 장치와 비디오 전환기를 제어해, 경우에 따라서는 디지털 디스크 레코더도 제어한다. 제어 컴퓨터는, 정확한 시기에 커멘드를 발행해야 하기 때문에, 비디오 테잎을 특정의 시점에서 특정의 장소에 삽입해야 한다.

어플리케이션은 이하와 같이 다양한 방법으로 타임 코드를 사용하지만, 방법은 이것들로 한정되는 것은 아니다.

  • 어카이브(archive) 또는 다른 시스템에의 export용으로 EDL (Edit Decision List) 를 생성 할 수 있도록(듯이)하기 위한 편집 프로세스를 통한 비디오 및 오디오 소스의 추적. EDL 는 이하의 순서로 생성 한다.
    1. 비디오를 촬영한다.
    2. 프레임내만의 압축 (MJPEG, DV 등)을 사용하는 논리니아오후라인시스템에 캡춰 한다.
    3. 소재를 편집해, EDL 와 오프 라인으로 편집한 마스터를 생성 한다.
    4. EDL 를 온라인 시스템에 임포트 해, 오리지날의 소스를 사용해 "자동결점 편집 " 를 실시해, 필요한 장소에 타이틀과 이펙트를 추가해 최종적인 마스터를 생성 한다.
  • 오디오의 비디오에의 동기. 보통, 후의 필름 프로덕션에서, 오디오는 타임 코드와 함께 다른 테이프 레코더에 녹음된다. 특별 장비의 필름 카메라도, 필름 위에의 보내 구멍의 사이에 타임 코드를 기록할 수 있다. 촬영된 화면이 전자적으로 비디오 테잎에 전송 된 후, "러쉬의 동기 " 로 불리는 프로세스로, 오디오를 영상과 가지런히 하기 위해서(때문에) 타임 코드가 사용된다. 오디오와 비디오의 타임 코드가 다른 경우, VITC 와 LTC 를 병용 할 수 있는 일이 있다. 한편을 비디오의 타임 코드용으로, 한편을 오디오의 타임 코드용으로 사용한다.
  • ATR , 디지털 디스크 레코더 또는 플레이어, VCR 등의 복수의 디바이스의 동기와 기동. 이것은, 전에 설명한 것보다 넓은 클래스의 동기이며, 리니어 및 논리니아 편집 시스템, 자막 방송 시스템, 또는 자막 시스템으로 매우 일반적으로 볼 수 있다.
  • 타임 코드내의"유저 비트">로 불리는 미정도리 비트의 사용. 유저 비트에는, 일자, ASCII 코드, 무비 업계의 정보등이 자주(잘) 넣을 수 있지만, 유저 비트의 사용은 유저의 궁리인 만큼 한정된다.

타임 코드를 올바르게 취급하면 많은 일이 가능하게 되지만, 유감스럽지만, 기술의 빈약함이나 하드웨어의 고장을 위해서(때문에) 나빠지는 일도 많다. 타임 코드가 포함되는 테이프에 대해서는, 이하와 같은 일로 조심하지 않으면 안 된다.

  • 비디오 또는 오디오에 관해서 안정되지 않는, 또는 드리프트 하는 타임 코드.
  • 타임 코드 필드의 정합성의 낮음. 이것은, LTC 워드가 프레임의 시작부는 아니고 중앙으로부터 시작되거나 실제의 프레임 경계상에서 VITC 가 갱신되지 않거나 하는 것을 의미한다. 결과적으로, 애매한 참조가 생긴다.
  • 의도하지 않는 VITC/LTC 의 어긋나는 점.
  • 단속적인 탈락.
  • 타임 코드의 결핍.
  • 타임 코드의 신호 품질의 나쁨.
  • 부적절한 카피에 의한 프레임 오프셋(offset)의 증가.

타임 코드의 캡춰

타임 코드는, 외부의 타임 코드 제네레이터나, 타임 코드를 생성할 수 있는 캡춰 카드, 디바이스 제어 필터 자체, 또는 타임 코드 리더가 짜넣어지고 있는 VCR 등의 디바이스에 의해 생성할 수 있다. 외부 디바이스가 타임 코드를 호스트에게 송신하는 경우, 보통은 RS-422 접속이 필요하다.

타임 코드가 생성되면(자), 다음에 편집중에 액세스 할 수 있도록(듯이), 비디오 또는 오디오와 함께 테이블 또는 스트림 포맷으로 타임 코드를 캡춰 할 필요가 있다. 이것을 처리하려면 , 이하의 2 통과해 방법이 있다.

1. 스트림내의 프레임 위치에 인덱스 붙이고 된, 타임 코드의 불연속성의 리스트를 나타내는 테이블을 생성 해, 캡춰가 완료한 다음에, 그 테이블을 파일의 마지막에 기입한다. 이 리스트는, 이하와 같은 구조체의 배열이 될 것이다 (이 구조체는, DirectShow 의 TIMECODE_SAMPLE 구조체를 간략화한 것으로, 예로서 가리키는 것만으로 있는 것에 주의하면 좋겠다).

struct    {
        DWORD dwOffset;   // 프레임내의 스트림에의 오프셋(offset)
        char[11] szTC;    // 오프셋(offset) 위치에 있어서의 hh:mm:ss:ff 포맷에서의 타임 코드의 값
                          // 논드롭의 경우는 hh:mm:ss. ff 는 드롭 프레임용
        } TIMECODE;

예를 들어, 타임 코드 브레이크가 1 개 들어간 비디오 스트림을 캡춰 했다고 하면, 리스트는 이하와 같이 된다고 생각된다.

{0, 02:00:00:02},
{16305, 15:21:13:29}        // 타임 코드는 프레임 16305 로 점프 한다

이 테이블을 사용하면, 임의의 프레임의 타임 코드를 간단하게 계산할 수 있다.

2. 데이터를 스트림으로서 취급해, 비디오나 오디오를 기입하도록(듯이) 데이터를 파일에 기입한다. 이것은, 급속히 변화하는 데이터의 경우에 편리해, 자막 방송 데이터 등, 수직 동기 간격 (VBI) 내의 타임 코드가 없는 데이터의 경우에도 편리하다.

타임 코드 데이터가 거기에 관련하는 프레임 데이터와 함께 올바르게 저장 되면(자), 편집, 합성, 동기, 또는 기동하는 어플리케이션은, 잘 알려진 표준의 인덱스 시스템에 액세스 해 그것을 사용할 수가 있다.

외부 디바이스 제어

디바이스 제어 필터를 이행 하면, DirectShow 로 외부 디바이스를 제어할 수가 있다. 이러한 필터는, 완전하게 컴퓨터의 외부에 있어,IAMExtDevice ,IAMExtTransport ,IAMTimecodeGenerator ,IAMTimecodeReader 등의 인터페이스를 공개하고 있는 디바이스나 데이터 스트림을 제어한다. 보통, 외부 디바이스 제어 필터는 핀을 공개할 필요는 없지만, 핀을 공개하는 외부 디바이스 제어 필터의 예로서 VCR 등의 데이터의 소스를 나타내는 필터가 있다. VCR 로부터 캡춰 보드에 흐르는 데이터를 나타내는 핀간의 접속에 의해, 디바이스 제어 필터와 비디오 캡춰 필터가, 서로 통신해 데이터형을 교섭하는 것이 가능하게 된다. 다만, 이것들은 표준의전송을 사용하지 않고, 필터간에 제어 정보 이외의 데이터는 흐르지 않는다. 어플리케이션은, 외부 디바이스 필터의 인스턴스를 생성해 직접 제어할 수가 있지만, 필터 그래프의 문맥내에서는, 그래프내의 유일한 필터인 경우에서도 필터를 항상 인스턴스화해 두는 것을 강하게 추천한다.

외부 디바이스에는, VCR, 비디오 편집 스테이션, 오디오 테이프 레코더 (ATR), 믹서, 또는 비디오의 캡춰나 편집으로 사용하는 그 외의 디바이스가 있다. 캡춰나 편집에서는, DirectShow 의 외부 디바이스 제어 필터로 오디오와 비디오의 동기를 잡아, 정확하게 제어할 필요가 있다. 재생, 편집, 및 캡춰의 사이, external clock나 SMPTE 타임 코드에 의해 오디오와 비디오의 동기를 잡을 수가 있다.

외부 디바이스 제어를 이해하려면 , 타임 코드를 이해할 필요가 있다. 타임 코드에 대해서는, 기본 사항으로서 이하를 기억해 두지 않으면 안 된다.

  • SMPTE 타임 코드는, 비디오 및 오디오 프레임을 식별하기 위한 프레임 애드레싱 시스템이다. 이것에는, LTC, VITC, 드롭 프레임, 논드롭후레임등이 많은 타입과 모드가 있어, 24, 25, 29.97, 30 프레임/초라고 한 다양한 frame rate로 기능한다.
  • SMPTE 타임 코드는 EDL 로 사용된다. EDL 는, 하드웨어 디바이스를 동기하기 위한 타이밍 기준으로서 또 프로덕션 소스나 필름 참조 정보등의 추가 데이터의 매체로서 오프 라인 및 온라인 편집용으로 생성된다.
  • SMPTE 타임 코드는, 스트림 또는 불연속성의 테이블로서 저장 할 수 있다.
  • 타임 라인은 동기를 위해서(때문에) 필요하고, 제어 컴퓨터, 외부 동기 장치, 또는 피제어 디바이스 자체에 로컬인 것이어도 괜찮다.

이러한 일을 생각하면(자), 디바이스 제어에는 2 개의 근본적인 문제가 있다. 제 1 에, 다양한 메이커의 다양한 디바이스용으로, 몇백 종류의 통신 프로토콜이 존재한다. VCR 나 레이저 디스크 플레이어와 같이, 다른 디바이스보다 넓게 사용되고 있는 것도 있지만, 거의 모든 디바이스가 다른 리모트 콘트롤 인터페이스를 가지고 있다. 한층 더 세련된 프로 사양의 비디오 및 오디오 어플리케이션이 소형화하는 것에 따라, 이 문제는 더욱 더 커지고 있다. 이것들 무수한 프로토콜을 위해서(때문에), 제어하는 외부 디바이스 마다 다른 DirectShow 필터를 이행 해야 한다.

제 2 에, 프로 사양의 비디오 및 오디오 시스템의 설계에서는, 이벤트가 정확한 시점에서 발생해야 한다고 하는 문제가 있다. 이 문제의 개요를 보기 위해서(때문에), 다음의 타이밍도를 생각해 보자.

비디오 프로덕션 시스템의 기본적인 타이밍도

수평축은 비디오 필드내의 시간을 나타낸다. NTSC 비디오의 경우, 이것은 약 1/60 초이다. 여기서 중요한 것은, 모든 신호가 시간순서에 줄지어 있는 것, 즉 타임 코드는 프레임의 선두로부터 시작 되는 점이다 (시스템 프레임 펄스). 테이프 장치등의 외부 디바이스는, AVI 대응 어플리케이션으로부터 실행된 AVI 파일등의 디지털 비디오 재생과 함께, 시스템 기준에 의해 늘어놓을 수 있다.

이 타이밍 요건에 적합시키기에는 다양한 방법이 있지만, 가장 일반적인 것은, 시스템내의 모든 컴퍼넌트에 마스터 기준 신호를 배포하는 방법이다. 이 기준은, 비디오의 세계에서는"블랙 burst"로서 알려져 블랙 레벨을 넘는 액티브한 비디오가 포함되지 않는 복합 영상 신호인 것으로부터 이렇게 불린다. 이름의 "burst " 의 부분은, 비디오 신호의 칼라버스트 부분을 가리키고 있다. 이 기준에 접속된 각 디바이스는, 자신의 동기를 유지해야 한다. 즉, 디지털 비디오 플레이어는 수직 동기 간격간에 프레임을 새로 바꾸지 않으면 안되어, 테이프 장치는 수직 동기 간격간은 녹화 모드에 새로 바꾸지 않으면 안되어, 시리얼 포트를 통해서 외부 디바이스에 송신되는 커멘드는 프레임 펄스에 맞추지 않으면 안 된다. 그리고, 이것들 모두그 외의 동기 이벤트는, SMPTE 타임 코드에 정의 끝난 값이 나타났을 때에 발생해야 한다. 이러한 규칙에 적합 시킬 수 없으면, 비디오 화면에테아링이 발생하거나 상태가 나쁠 때에 편집이 발생하거나 한다.

프로 사양의 비디오의 세계에서 이것을 실현하는 것은 비교적 간단하지만, 혼성 된 데스크탑 비디오의 세계에서는 실현은 매우 어렵다.

지금까지 준 생각에 근거해, 다음의 2 개의 설계예에 외부 디바이스의 설정을 나타낸다.

단일 VCR 디지털 비디오 편집 시스템의 기본 블럭도

복수 VCR 디지털 비디오 편집 시스템의 기본 블럭도

이러한 블럭도를 보면, 모든 박스에 기준 신호를 배포하는 것은 비교적 간단하다라고 하는 것이 안다. 예를 들어, 타임 코드 리더와 디지털 비디오 플레이어의 사이 등, 컴퓨터 내부에서 행해지는 동기를 취급하려면 , operating system의 전용 서비스인 "수직 구동 " 의 하드웨어 인터럽트, 또는 그 외의 커스텀 솔루션을 사용하는 것을 추천한다.

마지막으로, 외부 디바이스를 제어하는 필터를 쓰는 경우는,IAMExtDevice 및 IAMExtTransport 인터페이스를 이행 해야 한다. 필터가 타임 코드를 읽어들이거나 생성하거나 하는 경우는, DirectShow 가 제공하는 인터페이스,IAMTimecodeReader ,IAMTimecodeGenerator , 및 IAMTimecodeDisplay 도 이행 해야 한다. 게다가 외부 디바이스의 마이크로 프로세서용의 실행 모듈 코드를 다운로드해 실행하는 경우와 같이, 외부 디바이스와의 사이에 바이너리 메세지를 교환하는 것이 필요한 경우는, COM IDataObject 인터페이스를 이행 하는 것으로 그것을 실시하지 않으면 안 된다. 이 인터페이스에는, 바이너리 데이터의 전송을 취급하기 위한 메소드가 모두 갖추어져 있다. 필터에 필요한 독자적인 데이터 전송에는, 이 인터페이스를 사용한다.

참고서와 보충 자료

SMPTE 타임 코드와 외부 디바이스 제어의 보충 자료로서는, 이하와 같은 문서가 있다.

  • Proposed revision to ANSI/SMPTE 12M-1986, SMPTE Standard for Television, Audio and Film Time and Control Code, SMPTE Journal, February 1995.
  • SMPTE RP 135-1990 "Use of Binary User Groups in Motion-Picture Time and Control Codes"
  • SMPTE RP 169 "Television, Audio and Film Time and Control Code—Auxiliary Time Address Data in Binary Groups—Dialect Specification of Directory Index Locations"
  • SMPTE RP 179-1994 "Dialect Specification of Page-Line Directory Index for Television, Audio and Film Time and Control Code for Video-Assisted Film Editing"
  • "Touring the Vertical Interval", Warner Johnston, TV Technology, August 1991
  • "Closed Captioning in Real Time", Marc Oakrand, SMPTE Journal, June 1991
  • Timecode Handbook, 3rd. Edition, Cipher Digital, Inc. (available from Mix Bookshelf)
  • Timecode: A User's Guide, John Ratcliffe (available from Mix Bookshelf)
  • SMPTE RP 138—Control Message Architecture
  • SMPTE RP 139—Tributary Interconnection
  • SMPTE RP 163—System Service Messages
  • SMPTE RP 170—Video Tape Recorder Type Specific Messages for Digital Control Interface
  • SMPTE RP 171—Type-Specific Messages for Digital Control Interface of Analog Audio Tape Recorders
  • SMPTE RP 172—Common Messages for Digital Control Interface
  • SMPTE 275M—ESlan-1 Remote Control System

SMPTE 의 규격과 리프린트는, (914) 761-1100 (미국)에 전화 하면 SMPTE 로부터 입수할 수 있다.


Visual Basic 에서의 DirectShow 의 사용법

여기에서는, Microsoft® Visual Basic® 를 사용해 Microsoft® DirectShow® 어플리케이션을 생성 하는 방법에 대해 설명한다. 내용은 다음과 같다.

  • Visual Basic 를 사용한 필터 그래프의 생성
  • Visual Basic 를 사용한 필터 그래프의 제어
  • Visual Basic 오브젝트


Visual Basic 를 사용한 필터 그래프의 생성 방법

여기에서는, Microsoft® Visual Basic® 를 사용해 필터 그래프의 컴퍼넌트를 관리하는 방법에 대해 설명한다.

이 내용은, Microsoft® Windows® 에서의 어플리케이션 프로그래밍, Windows 베이스의 멀티미디어 프로그래밍, 및 Visual Basic 프로그래밍 시스템의 Automation 기능에 대해 이미 이해하고 있는 Visual Basic 의 개발자를 대상으로 하고 있다.

여기에서는 다음의 내용에 대해 설명한다.

  • DirectShow Quartz.dll 오브젝트에 대해
  • 필터 그래프의 생성
  • 완전한 필터 그래프의 생성
  • 새로운 필터 그래프의 생성과 필터의 추가
  • 필터 핀의 접속
  • 핀 접속 정보의 표시
  • 통계

DirectShow Quartz.dll 오브젝트에 대해

Quartz.dll 는, Visual Basic 베이스의 어플리케이션으로 필터 및 핀을 관리하는 오브젝트를 제공한다. 그러한 오브젝트간에는 암묵적인 계층이 존재한다. 즉, 많은 경우, 오브젝트를 취득하려면 다른 오브젝트의 프로퍼티에 액세스 할 필요가 있다. 다음의 예로, 오브젝트아래에 다른 오브젝트가 인덴트 해 나타나고 있는 경우, 그 하위 레벨 오브젝트는, 상위 레벨 오브젝트의 프로퍼티 또는 메소드로부터 취득할 필요가 있다.

Filter graph object (IMediaControl)
  Filter collection (RegFilterCollection, FilterCollection properties)
    Filter Info object (IFilterInfo or IRegFilterInfo in filter collection)
      Pin collection (Pins property)
        Pin Info object (IPinInfo item in pins collection)

계층의 최상정도 레벨 오브젝트는, 필터 그래프 오브젝트 즉 IMediaControl 오브젝트이며, 필터 그래프 전체를 나타낸다. IMediaControl 오브젝트의 2 개의 프로퍼티에 액세스 하는 것에 의해, 필터 오브젝트의 콜렉션을 취득할 수 있다. RegFilterCollection 프로퍼티는, 시스템에 등록되어 있는 필터를 나타낸다. FilterCollection 프로퍼티는, 필터 그래프의 일부인 필터를 나타낸다.

Visual Basic 로 액세스 가능한 다른 콜렉션과 같게, Visual Basic 의 for each...next 스테이트먼트를 사용해 콜렉션내의 개개의 항목에 액세스 할 수 있다. 콜렉션내의 항목의 수는, 콜렉션의 Count 프로퍼티에 의해 나타난다.

필터 콜렉션에는,IFilterInfo 오브젝트가 포함되어 있다. 각 IFilterInfo 오브젝트는, 그 필터에 대해서 정의되고 있는 핀의 콜렉션을 나타내는 Pins 프로퍼티를 가진다.

핀 콜렉션에는,IPinInfo 오브젝트가 포함되어 있다. 각 IPinInfo 오브젝트는, 미디어 타입이나 다른 핀에의 접속 등, 그 핀에 관한 상세 정보를 포함한다.

필터 그래프내의 필터의 특정의 핀에 대해 조사하려면 , 다음의 순서를 실행한다.

  1. 필터 그래프 오브젝트를 취득한다.
  2. 필터 그래프 오브젝트의 IMediaControl.FilterCollection 프로퍼티를 사용해, 필터 그래프내에 존재하는 필터의 콜렉션을 취득한다.
  3. 필터 콜렉션내의 특정의 필터를 검색한다.
  4. 필터 오브젝트의 IFilterInfo.Pins 프로퍼티를 사용해, 그 필터에 대해서 정의되고 있는 핀의 콜렉션을 취득한다.
  5. 핀 콜렉션내의 특정의 핀을 검색한다.
  6. 핀 오브젝트의 프로퍼티를 조사해, 핀의 접속 정보 및 그 외의 정보를 찾아낸다.

필터 그래프의 생성

Quartz.dll 를 사용해 필터 그래프를 생성 하려면 , 다른 3 개의 방법이 있다. 각각의 방법으로 필터 그래프에 대한 제어의 정도가 달라, 필터 그래프 전체를 자동 생성하는 것으로부터, 모든 필터와 핀 접속을 지정하는 것까지 가능하다. 3 개의 방법을 다음에 나타낸다.

  • 자동 : 멀티미디어 소스 또는 보존되고 있는 필터 그래프의 파일로부터 완전한 필터 그래프를 생성한다.
  • 반자동 : 새로운 (하늘의) 필터 그래프를 생성 해 1 개(살) 이상의 필터를 추가해, 특정의 핀을 렌더링 하기 위해서 필요한 모든 필터와 접속을 자동적으로 생성한다.
  • 수동 : 새로운 (하늘의) 필터 그래프를 생성 해, 그래프에 개개의 필터를 추가해, 핀의 사이의 접속을 명시적으로 추가한다.

완전한 필터 그래프의 생성

다음의 예는, 코드의 일부분이며, 멀티미디어 소스 또는 보존되고 있는 필터 그래프에 근거해 완전한 필터 그래프를 생성하는 방법을 나타내고 있다. 어플리케이션에서는,IMediaControl 오브젝트 (처음은 "하늘 ")를 생성 한 후,IMediaControl.RenderFile 메소드를 호출해 완전한 그래프를 구축한다.

'최초로 새로운 하늘의 필터 그래프를 생성 한다
Dim g_objMC as IMediaControl       '범용 선언 섹션으로부터
...
Set g_objMC = New FilgraphManager  '새로운 필터 그래프를 생성 한다
...
'공통의 파일을 여는 다이알로그 박스를 사용해 유저에게 입력 파일을 선택시킨다
CommonDialog1.ShowOpen             '유저가 소스 또는 필터 그래프를 선택한다
' IMediaControl.RenderFile 를 호출해 모든 필터를 추가해, 모든 핀을 접속한다
g_objMC.RenderFile CommonDialog1.filename  '완전한 그래프를 생성한다

새로운 필터 그래프의 생성과 필터의 추가

다음의 예는, 코드의 일부분이며, 새로운 (하늘의) 필터 그래프 오브젝트를 생성 하는 방법을 나타내고 있다.

Dim g_objMC as IMediaControl  '범용 선언 섹션으로부터
    ...
Set g_objMC = New FilgraphManager  '새로운 필터 그래프를 생성 한다

하늘의 필터 그래프를 생성 해 개개의 필터를 추가하는 경우는, 필터 타입을 알 수 있고 있을 필요가 있다. 보통, 필터에는 3 개의 카테고리가 있다. 소스 필터, 변환 필터, 및 렌더링 필터의 3 개이다. 소스 필터를 추가하는 순서에서는, 변환 필터 및 렌더링 필터를 추가하는 순서와는 다른 메소드를 사용한다.

필터 그래프에 소스 필터를 추가한다. 그 때문에(위해)는,IMediaControl.AddSourceFilter 메소드를 호출해, 지정의 소스 타입 또는 보존되고 있는 필터 그래프의 파일의 이름을 지정한다.

Dim objFilter As Object  '유효한 구문용의 일시 오브젝트; 사용하지 않는다

CommonDialog1.ShowOpen  '소스 또는 필터 그래프 파일의 이름을 취득한다
g_objMC.AddSourceFilter CommonDialog1.filename, objFilter

IRegFilterInfo.Filter 메소드를 호출해, 필터 그래프에 변환 필터 및 렌더링 필터를 추가한다. IRegFilterInfo 오브젝트는,IMediaControl.RegFilterCollection 프로퍼티로부터 취득할 수 있다. 이 프로퍼티는, 시스템에 등록되어 있어 이용 가능한 필터 오브젝트의 콜렉션을 나타낸다.

필터 그래프를 생성 해 IMediaControl 오브젝트를 취득한 후, 다음의 순서에 따라 필터를 추가한다.

  1. 등록이 끝난 필터의 일람을 취득하기 위해서,IMediaControl.RegFilterCollection 프로퍼티를 취득한다.
  2. 콜렉션으로 목적의 필터를 검색한다. 콜렉션내의 각 요소는 IRegFilterInfo 오브젝트이다.
  3. 필터 그래프에 필터를 추가하기 위해서,IRegFilterInfo.Filter 메소드를 호출한다.

다음의 예는, 코드의 일부분으로, 이 순서의 1 으로 2 에 대응한다.

'등록한 필터 리스트 박스에 데이터를 삽입하는 코드의 일부분
'글로벌 변수 g_objRegFilters 에 IMediaControl.RegFilterCollection 를 설정한다
' g_objRegFilters = g_objMC.RegFilterCollection 와 설정한다
Dim filter As IRegFilterInfo
    listRegFilters.Clear
    If Not g_objRegFilters Is Nothing Then
        For Each filter In g_objRegFilters  '콜렉션내의 필터 마다
            listRegFilters.AddItem filter.Name '이름을 리스트 박스에 추가한다
Next filter
End If

다음의 예는, 코드의 일부분으로, 순서 3 에 대응한다.

Dim filter As IRegFilterInfo
'선택한 필터를 검색해 그래프에 추가한다
' g_objRegFilters 는 IMediaControl 오브젝트의 RegFilterCollection 프로퍼티
For Each filter In g_objRegFilters
    If filter.Name = listRegFilters.Text Then  '선택한 필터인가?
        Dim f As IFilterInfo  '대답이 yes 라면
        filter.filter f  '필터 그래프에 추가, IFilterInfo f 를 돌려준다
        If f.IsFileSource Then
            CommonDialog1.ShowOpen
            f.filename = CommonDialog1.filename
End If
        Exit For
End If
Next filter

필터 핀의 접속

필터 그래프에 개개의 필터를 추가한 후, 각 핀을 명시적으로 접속하는지, 특정의 핀으로부터 다운 스트림에 필요한 모든 접속을 자동적으로 생성해, 필터간의 접속을 확립할 수 있다.

어느 경우도, Microsoft® DirectShow® 오브젝트의 계층을 주사 해, 필터 오브젝트의 핀을 나타내는 IPinInfo 오브젝트를 취득할 필요가 있다. 그 때문에(위해)는, 필터 그래프 오브젝트의 필터 콜렉션내에서 목적의 필터를 찾아내 다음에 필터 오브젝트의 핀 콜렉션내에서 목적의 핀을 찾아낸다.

여기에서는 다음의 내용에 대해 설명한다.

  • 필터 그래프의 필터의 일람표시
  • 필터에 대해서 정의되고 있는 핀의 일람표시
  • 2 개의 핀의 명시적인 접속
  • 핀의 자동 접속

필터 그래프의 필터의 일람표시

필터 그래프내의 모든 필터는,IMediaControl.FilterCollection 프로퍼티를 사용해 액세스 할 수 있는 콜렉션내의 필터로서 이용 가능하다.

'그래프내의 현재의 필터를 포함한 리스트 박스를 최신 상태에 갱신한다
listFilters.Clear
For Each objFI In g_objMC.FilterCollection
    listFilters.AddItem objFI.Name '리스트 박스에 추가한다
Next objFI

필터에 대해서 정의되고 있는 핀의 일람표시

필터 오브젝트에 대해서 정의되고 있는 핀은,IFilterInfo.Pins 프로퍼티를 사용해 액세스 할 수 있다. Pins 프로퍼티는, 개개의 IPinInfo 오브젝트의 콜렉션이다.

콜렉션으로부터 개개의 IPinInfo 오브젝트를 취득한 후, 오브젝트의 프로퍼티에 액세스 해, 오브젝트의 메소드를 호출할 수가 있다. 다음의 예는, 이것을 나타내는 코드의 일부분이다.

For Each objPin In g_objSelFilter.Pins
If objPin.Name = listPins.Text Then  '선택한 핀인가?
    Set g_objSelPin = objPin '대답이 yes 라면, 정보를 갱신한다
    ' ... 그 핀을 사용해 조작을 실행한다
End If
Next objPin

핀 오브젝트를 취득한 후, 이제(벌써) 1 개의 핀에 명시적으로 접속하는지, 핀을 렌더링 하기 위해서 필요한 나머지의 핀 접속 모든 것을 자동적으로 생성할 수 있다.

2 개의 핀의 명시적인 접속

IPinInfo 오브젝트는, 핀을 접속하는 3 개의 메소드를 제공한다. Connect ,ConnectDirect , 및 ConnectWithType 이다. Connect 는, 필요에 따라서 다른 변환 필터를 추가한다. ConnectDirect 는 변환 필터를 추가하지 않는다. ConnectWithType 는, 지정된 핀이 지정된 미디어 타입에 일치하는 경우에게만, 접속을 실행한다.

frmSelectPin.OtherDir = g_objSelPin.Direction
Set frmSelectPin.Graph = g_objMC             '그 폼에 그래프의 카피와
Set frmSelectPin.SelFilter = g_objSelFilter  '현재의 필터를 건네준다
frmSelectPin.RefreshFilters                  '접속할 수 있는 필터를 표시한다
frmSelectPin.Show 1                          '폼을 표시한다
If frmSelectPin.bOK Then        '유저가 폼을 선택--OK 버튼이 사용되었다
    Dim objPI As IPinInfo
    Set objPI = frmSelectPin.SelPin          '폼으로부터 새로운 핀을 취득한다
    g_objSelPin.Connect objPI                ' 2 개의 핀을 접속한다
    RefreshFilters                           '핀의 최신 정보를 표시한다
End If

핀의 자동 접속

핀의 다운 스트림에 필요한 필터 그래프의 모든 부분을 자동적으로 생성하려면 ,IPinInfo.Render 메소드를 호출한다.

다운 스트림이라고 하는 용어는, 그 핀으로부터 렌더링 필터까지의 완전한 패스를 구축하기 위해서 필요한 모든 접속을 의미한다. 예를 들어, GraphEdit 유틸리티에 의한 필터 그래프의 표현을 생각한다. 이것은, 좌측의 소스 필터로부터 우측의 렌더링 필터까지 이동하는 접속을 나타낸다. Render 메소드는, 지정된 핀의 오른쪽으로 필요한 모든 필터와 접속을 추가한다.

' IPinInfo.Render 를 호출한다
'이 핀으로부터 다운 스트림에 그래프를 완성한다
' g_objSelPin 는 'Pins'와 라벨 붙이고 된 리스트 박스로 선택된 핀을 참조한다
    g_objSelPin.Render

핀 접속 정보의 표시

필터 오브젝트의 IFilterInfo.Pins 프로퍼티로부터 액세스 가능한 콜렉션의 핀 오브젝트를 취득한 후, 접속 및 그 외의 정보를 일람표시 할 수 있다.

  Dim strTemp As String
  On Error Resume Next
  Dim objPin As IPinInfo
For Each objPin In g_objSelFilter.Pins
    If objPin.Name = listPins.Text Then    '리스트 박스로 선택되었는지?
      Set g_objSelPin = objPin             '대답이 yes 라면, 모든 정보를 취득한다
      strTemp = ""               '기존의 표시되고 있는 핀의 정보를 소거한다
      Dim objPinOther As IPinInfo
      Set objPinOther = objPin.ConnectedTo
      If Err.Number = 0 Then               ' yes, 접속이 있다
        strTemp = "Connected to pin: " + objPinOther.Name + " "
        Dim objPeer As IFilterInfo
        Set objPeer = objPinOther.FilterInfo
        strTemp = strTemp + " on filter: " + objPeer.Name + " "
        Dim objMTI As IMediaTypeInfo
        Set objMTI = objPin.ConnectionMediaType
        strTemp = strTemp + vbCrLf + "Media Type: " + objMTI.Type
End If
      If objPin.Direction = 0 Then
strTemp = strTemp + " " + vbCrLf + "Direction: Input"
      Else
strTemp = strTemp + " " + vbCrLf + "Direction: Output"
End If
    txtPinInfo.Text = strTemp
End If
Next objPin

통계

여기서 설명한 DirectShow 오브젝트, 프로퍼티, 및 메소드의 사용법을 다음에 정리해 가리킨다.
태스크 | DirectShow 의 프로퍼티 또는 메소드
새로운 하늘의 필터 그래프를 생성 한다. | objMediaControl = New FilgraphManager 를 설정한다.
특정의 파일의 완전한 필터 그래프를 생성한다. | IMediaControl.RenderFile 메소드를 호출한다.
소스 필터를 추가한다. | IMediaControl.AddSourceFilter 메소드를 호출한다.
렌더링 필터 또는 변환 필터를 추가한다. | IMediaControl.RegFilterCollection 프로퍼티를 사용해 IRegFilterInfo 오브젝트를 취득한다. IRegFilterInfo.Filter 메소드를 호출한다.
필터 오브젝트의 핀을 일람표시 한다. | IFilterInfo.Pins 프로퍼티를 사용해 IPinInfo 오브젝트를 취득한다.
2 개의 핀을 명시적으로 접속한다. | IPinInfo.Connect 메소드를 호출한다.
핀으로부터 렌더링 필터까지의 모든 접속을 생성 한다. | IPinInfo.Render 메소드를 호출한다.


Visual Basic 를 사용한 필터 그래프의 제어 방법

여기에서는, Microsoft® DirectShow® 의 동적 링크 라이브러리인 Quartz.dll 에 의해 공개되고 있는 메소드, 이벤트, 및 프로퍼티를 사용해, Microsoft® Visual Basic® 베이스의 어플리케이션으로 타임 스탬프 첨부의 비디오 데이터의 스트림을 렌더링 하는 방법을 설명한다. 이 내용은, Microsoft® Windows® 베이스의 어플리케이션 프로그래밍, Windows 베이스의 멀티미디어 프로그래밍, 및 Visual Basic 프로그래밍 시스템 버젼 5. x 의 Automation 기능에 대해 이미 이해하고 있는 개발자가 대상이다.

여기에서는 다음의 내용에 대해 설명한다.

  • DirectShow 의 필터와 필터 그래프
  • DirectShow 인터페이스에 액세스 하기 위해서 Quartz.dll 를 등록하는 방법
  • Visual Basic 에서의 필터 그래프의 제어

DirectShow 의 필터와 필터 그래프

어플리케이션으로 Quartz.dll 를 사용해 멀티미디어를 표시하려면 , 필터로 불리는 오브젝트의 콜렉션을 사용한다. 이 콜렉션은 필터 그래프라고도 불린다. 다음의 그림은, AVI (Audio-Video Interleaved) 파일을 렌더링 하는 필터 그래프를 나타내고 있다.

AVI 필터 그래프

이 그림에서는, AVI 소스 필터가 디스크로부터 파일을 읽어낸다. AVI 데콘프렛사피르타 (CODEC )는, 소스 필터로부터 건네받은 비디오 데이터를 압축 해제한다. 다음에, CODEC 필터는 이 데이터를 비디오 렌더러에 건네준다. 그 다음에, 비디오 렌더러는 디바이스를 인식할 수 있는 포맷의 데이터를 디바이스에 건네준다. AVI 소스 필터는 오디오 렌더러에 직접 오디오 데이터를 건네주어, 오디오 렌더러는 오디오 디바이스에 데이터를 건네준다.

DirectShow 는, 필터 외에도, 필터 그래프 매니저로 불리는 Automation 오브젝트를 지원 하고 있다. 이 오브젝트는, 이용 가능한 필터에 대해 알고 있다. 또, 어느 파일 포맷을 렌더링 하기 위해서 어느 필터 타입이 필요한가를 인식하고 있다. 필터 그래프 매니저는, 특정의 그래프내의 필터가 지원 하고 있는 메소드, 이벤트, 및 프로퍼티를 공개한다. 게다가 독자적인 메소드, 이벤트, 및 프로퍼티세트를, 인터페이스를 사용해 공개한다. 인터페이스는, 관련한 메소드, 이벤트, 및 프로퍼티의 콜렉션이다.

다음 표에서는, Visual Basic 베이스의 어플리케이션으로 사용하는, Quartz.dll 에 제공되고 있는 DirectShow 의 인터페이스를 나타내, 각 인터페이스의 목적을 설명한다.
인터페이스 | 설명
IAMCollection | 핀 콜렉션 및 필터 콜렉션에 액세스 한다.
IBasicAudio | 현재의 볼륨 설정을 제어해, 취득한다.
IBasicVideo | 범용 비디오 렌더러를 제어한다.
IFilterInfo | 필터에 관한 정보, 및 필터내의 핀 오브젝트에 관한 정보를 취득한다.
IMediaControl | 필터 그래프를 인스턴스화해, 미디어 플로우 (실행, 포즈, 정지)를 제어한다.
IMediaEvent | 재페인트, 유저 종료, 완료등의 이벤트에 대한 커스터마이즈 한 이벤트 처리를 가능하게 한다.
IMediaPosition | 시작 타임, 종료 타임, 레이트, 및 현재 위치를 제어해, 취득한다.
IMediaTypeInfo | 미디어 타입과 서브 타입을 취득한다.
IPinInfo | 핀의 방향이나 미디어 타입등의 핀 정보에 액세스 해, 핀의 접속, 절단, 및 렌더링을 제어한다.
IRegFilterInfo | 등록을 마친 (변환 및 렌더링) 필터에 관한 정보를 포함한다.
IVideoWindow | 비디오 렌더러의 윈도우 어스펙트를 제어한다.

DirectShow 인터페이스에 액세스 하기 위해서 Quartz.dll 를 등록하는 방법

Microsoft Visual Basic 베이스의 어플리케이션으로 DirectShow 의 인터페이스를 사용하려면 , Visual Basic 프로젝트로 Microsoft® ActiveMovie® 컨트롤 타입 라이브러리를 등록할 필요가 있다. 그 때문에(위해)는,[프로젝트] 메뉴의 [참조 설정] 을 클릭해, 다음에 [ActiveMovie control type library] 의 왼쪽의 체크 박스를 온으로 한다.

Visual Basic 의 [참조 설정] 다이알로그 박스를 사용해 ActiveMovie 컨트롤 타입 라이브러리를 등록하는 것에 의해, Visual Basic 에 필요한 Automation 정보를 포함한 타입 라이브러리를 특정한다. 다음의 그림에 [참조 설정] 다이알로그 박스를 나타낸다.

Visual Basic 의 [참조 설정] 다이얼로그 박스

타입 라이브러리를 등록한 후,[오브젝트 브라우저] 다이알로그 박스를 사용해, 특정의 인터페이스에 관련한 메소드, 이벤트, 및 프로퍼티의 일람을 표시할 수 있다. [표시] 메뉴의 [오브젝트 브라우저] 를 클릭해, 다음에,[오브젝트 브라우저] 다이알로그 박스의 좌상에 있는 라이브러리의 드롭 다운 리스트로부터 [QuartzTypeLib] 를 선택한다.

주 : QuartzTypeLib 내의 타입 정보는, 오브젝트별로는 않고 인터페이스별로 편성되고 있다.

Visual Basic 에서의 필터 그래프의 제어

여기에서는 다음의 내용에 대해 설명한다.

  • 파일의 인스톨
  • Visual Basic 에의 Quartz.dll 의 등록
  • DirectShow 의 오브젝트를 사용하기 위한 준비
  • 필터 그래프의 인스턴스화
  • 비디오의 렌더링
  • 오디오의 제어
  • 비디오 출력의 스케일링과 이동
  • 상태의 추적
  • 시작 위치의 취득과 설정
  • 레이트의 취득과 설정
  • 클린 업

파일의 인스톨

Visual Basic 베이스의 어플리케이션으로 DirectShow 오브젝트를 사용하려면 , Windows\System 디렉토리에 Quartz.dll 를 인스톨 해, 시스템의 레지스트리 데이타베이스에 적절한 항목이 생성 된 것을 확인할 필요가 있다. 현재, 이 프로세스는 Microsoft® DirectX® Software Development Kit (SDK) 셋업 프로그램에 의해 자동화되고 있다. 인스톨 하려면 , Setup.exe 를 기동해, Runtime 옵션을 선택한다. 동적 링크 라이브러리 (DLL)가 올바른 장소에 카피되어 레지스트리가 자동적으로 갱신된다.

Visual Basic 에의 Quartz.dll 의 등록

파일이 올바르고 인스톨 된 것을 확인하려면 , Visual Basic 어플리케이션을 열어,[표시] 메뉴의 [참조 설정] 커멘드를 클릭한다. 기동시에 Visual Basic 에 의해 레지스트리 데이타베이스의 등록이 끝난 Automation 컨트롤이 확인되어 이 다이알로그 박스에 표시되는 일람에 컨트롤의 이름이 추가된다. 필터 그래프 매니저를 사용하려면 ,[ActiveMovie control type library] 를 클릭한다.

Visual Basic 에 타입 정보가 등록되면(자), 어플리케이션으로 필터 그래프 매니저 및 관련하는 인터페이스를 사용할 수 있다.

DirectShow 의 오브젝트를 사용하기 위한 준비

Visual Basic 는, FilgraphManager 오브젝트를 사용해 모든 오브젝트를 초기화한다. FilgraphManager 오브젝트는 다음의 인터페이스를 이행 한다.

  • IBasicAudio
  • IBasicVideo
  • IMediaControl
  • IMediaEvent
  • IMediaPosition
  • IVideoWindow

각 인터페이스에는, 그 인터페이스 타입으로서 정의한 Visual Basic 의 프로그램 가능한 오브젝트로부터 액세스 한다. 오브젝트는, 다음의 예에 나타내도록(듯이), 범용 선언 섹션으로 글로벌 변수로서 정의할 수 있다.

Dim g_objVideoWindow As IVideoWindow            ' VideoWindow 오브젝트
Dim g_objMediaControl As IMediaControl          ' MediaControl 오브젝트
Dim g_objMediaPosition As IMediaPosition        ' MediaPosition 오브젝트
Dim g_objBasicAudio  As IBasicAudio             ' Basic Audio 오브젝트
Dim g_objBasicVideo As IBasicVideo              ' Basic Video 오브젝트

다음의 예에 나타내도록(듯이), FilgraphManager 를 사용해 모든 프로그램 가능한 오브젝트를 초기화한다.

Set g_objMediaControl = New FilgraphManager
g_objMediaControl.RenderFile (g_strFileName)    '입력 파일의 이름
...
Set g_objBasicAudio = g_objMediaControl
Set g_objVideoWindow = g_objMediaControl
Set g_objMediaEvent = g_objMediaControl
Set g_objMediaPosition = g_objMediaControl

목적의 인터페이스를 명시적으로 돌려주는 메소드를 호출하는 것에 의해, 다른 인터페이스를 취득한다. 다음의 표는, 이러한 인터페이스의 취득 방법을 나타내고 있다.
인터페이스 | 인터페이스 포인터를 돌려주는 메소드
IAMCollection | IPinInfo.MediaTypes ,IFilterInfo.Pins ,IMediaControl.FilterCollection ,IMediaControl.RegFilterCollection
IFilterInfo | 최초로 IMediaControl.FilterCollection , 다음에 IAMCollection.Item 또는 IPinInfo.FilterInfo
IMediaTypeInfo | IPinInfo.ConnectionMediaType
IPinInfo | IFilterInfo.FindPin ,IAMCollection.Item
IRegFilterInfo | 최초로 IMediaControl.RegFilterCollection , 다음에 IAMCollection.Item

이러한 필터 인터페이스 및 핀인타페이스의 조작 방법을 나타내는 예에 대해서는, 「Visual Basic 를 사용한 필터 그래프의 생성」을 참조할것.

필터 그래프의 인스턴스화

필터 그래프 매니저를 사용해, 다음의 타입의 기존 파일을 렌더링 할 수 있다.

  • . avi (Audio-Video Interleaved)
  • . mov (Apple® QuickTime®)
  • . mpg (Motion Picture Experts Group)

게다가 필터 그래프 매니저를 사용해 기존의 필터 그래프를 렌더링 할 수 있다. 그 때문에(위해)는, 그 그래프를 포함한 파일을 RenderFile 메소드의 파라미터로서 지정한다.

필터 그래프내의 필터는 렌더링 하는 파일의 타입에 의존하기 위해(때문에), 유저가 파일을 선택하고 나서 필터 그래프를 인스턴스화하는 것. 필터 그래프 매니저는, Visual Basic 의 키워드 New 를 사용해 AUTOMATION 오브젝트를 생성 할 경우에 인스턴스화 된다. 필터 그래프 오브젝트는, 다음의 예에 나타내도록(듯이),IMediaControl::RenderFile 메소드를 호출했을 때에 생성 된다.

    '요구된 파일 포맷의 필터 그래프를
    '인스턴스화한다

    Set g_objMediaControl = New FileGraphManager
    g_objMediaControl.RenderFile (g_strFileName)

비디오의 렌더링

IMediaControl 인터페이스는 3 개의 메소드를 지원 하고 있다 (Run ,Pause , 및 Stop ). 어플리케이션에서는, 이러한 메소드를 호출해 비디오 스트림을 렌더링, 포즈, 또는 정지할 수가 있다. 필터 그래프 오브젝트가 인스턴스화 된 후, 어플리케이션으로 이러한 메소드를 호출할 수가 있다.

다음의 코드예는, 유저가 버튼을 클릭했을 때, 거기에 응답해 Run ,Pause , 및 Stop 메소드를 기동한다.

Private Sub Toolbar1_ButtonClick(ByVal Button As Button)
'툴바의 버튼을 처리한다

    '오브젝트가 정의되어 있지 않은 경우는 에러를 회피한다
    If g_objMediaControl Is Nothing Then
Exit Sub
End If

    If Button.Index = 1 Then 'PLAY
        'MediaControl Run() 메소드를 호출해
        '비디오를 재생한다 (미리 정의되었다
        '필터 그래프를 사용)

        g_objMediaControl.Run
        g_fVideoRun = True

    ElseIf Button.Index = 2 Then 'PAUSE
        'MediaControl Pause() 메소드를 호출해
        '표시중의 비디오를 포즈 한다 (비디오의 표시에는
        '미리 정의된 필터 그래프를 사용)

        g_objMediaControl.Pause
        g_fVideoRun = False

    ElseIf Button.Index = 3 Then 'STOP

        'MediaControl Stop() 메소드를 호출해
        '표시중의 비디오를 정지한다 (비디오의 표시에는
        '미리 정의된 필터 그래프를 사용)

        g_objMediaControl.Stop
        g_fVideoRun = False
        '비디오의 선두에 리셋 한다
        g_objMediaPosition.CurrentPosition = 0
        txtElapsed.Text = "0. 0"

오디오의 제어

IBasicAudio 인터페이스는,Volume 프로퍼티와 Balance 프로퍼티라고 하는 2 개의 프로퍼티를 지원 하고 있다. Volume 프로퍼티는 볼륨을 취득 또는 설정한다. 샘플 어플리케이션에서는, 이 프로퍼티는 슬라이더 컨트롤 slVolume 에 바인드 되고 있다. Balance 프로퍼티는 스테레오의 밸런스를 취득 또는 설정한다. 샘플 어플리케이션에서는, 이 프로퍼티는 슬라이더 컨트롤 slBalance 에 바인드 되고 있다.

주 : 볼륨은 리니어 볼륨 스케일이기 (위해)때문에, 유용한 것은 슬라이더의 우단 뿐이다.

다음의 예에서는,g_objBasicAudio.Volume 프로퍼티를 설정해 볼륨을 조정하고 있다.

Private Sub slVolume_Change()
'슬라이더의 볼륨을 설정한다

    If Not g_objMediaControl Is Nothing Then
    'g_objMediaControl 를 할당할 수 있고 있는 경우

       g_objBasicAudio.Volume = slVolume.Value

End If

End Sub

비디오 출력의 스케일링과 이동

IVideoWindow 인터페이스는, 전송처 윈도우의 사이즈, 상태, 소유자, 팔레트, 가시성등을 변경하는 메소드와 프로퍼티를 지원 하고 있다. 전송처 윈도우의 위치 또는 외관을 고려할 필요가 없는 경우는, 이러한 메소드와 프로퍼티를 호출하지 않고, 디폴트의 윈도우 (데스크탑의 좌상에 표시된다)에 출력을 렌더링 할 수가 있다.

캡션, 경계, 및 다이알로그 박스의 테두리를 이동해 윈도우의 스타일을 변경할 수도 있다. 그 때문에(위해)는,g_objVideoWindow.WindowStyle 프로퍼티를 0x06000000 로 설정한다. 이것은, 값 WS_DLGFRAME (0x04000000)와 WS_VSCROLL (0x02000000)의 논리 OR 에 상당한다. 윈도우의 스타일 및 대응하는 값 모든 일람에 대해서는, Microsoft® Platform SDK 의 Winuser.h 파일을 참조할것.

전송처 윈도우를 폼 위로 이동하는 경우, 새로운 위치를 지정하려면 , g_objVideoWindow 의 Top 및 Left 프로퍼티를 설정한다. Top 및 Left 프로퍼티는, 직사각형을 한 하늘의 컨트롤의 좌상구석에 대응하도록(듯이) 설정한다. 이것은 폼에 표시되는 어떤 종류의 플레이스홀더이다. 폼의 ScaleMode 프로퍼티는 3 으로 설정되어 있다. 이것은 픽셀의 단위를 지정한다. 이것으로 폼의 프로퍼티와 DirectShow 오브젝트의 프로퍼티를 변환하는 일 없이 사용할 수 있다. DirectShow 오브젝트의 프로퍼티도 픽셀로 나타내진다. Visual Basic 폼의 디폴트의 단위는 twip 이다.

소스 비디오의 폭과 높이를 취득해 필요한 직사각형의 사이즈를 결정한다. 이러한 값은,IBasicVideo 오브젝트의 VideoWidth 및 VideoHeight 프로퍼티에 대응한다.

Top 및 Left 프로퍼티를 설정하는 것에 가세해, 어플리케이션의 폼을 새로운 부모 윈도우로서 식별할 필요가 있다. 그 때문에(위해)는, 폼의 윈도우 핸들인 hWnd 를 오브젝트의 Owner 프로퍼티에 건네준다. 핸들을 건네주지 않는 경우, 전송처 윈도우는 폼은 아니고 데스크탑에 대해서 상대적인 위치에 표시된다.

다음에 예는, 이러한 태스크를 나타내고 있다.

    Set g_objVideoWindow = g_objMediaControl
    g_objVideoWindow.WindowStyle = CLng(&H6000000)   ' WS_DLGFRAME | WS_VSCROLL
    g_objVideoWindow.Left = CLng(Shape1.Left)   ' shape 는 폼의 플레이스홀더
    g_objVideoWindow.Top = CLng(Shape1.Top)
    Shape1.Width = g_objVideoWindow.Width       '입력 비디오에 응해 shape 를 사이즈 변경한다
    Shape1.Height = g_objVideoWindow.Height
    g_objVideoWindow.Owner = frmMain.hWnd       '폼을 부모로서 설정한다

다음의 예는,ScaleMode 프로퍼티를 초기화하는 방법을 나타내고 있다.

' ...
    frmMain.ScaleMode = 3    '픽셀
' ...

퍼포먼스에 크게 영향을 주기 (위해)때문에,IVideoWindow 오브젝트의 Width 및 Height 프로퍼티를 설정해 전송처 윈도우의 스케일을 변경하지 않는 것.

상태의 추적

IMediaPosition 오브젝트에 의해 공개되고 있는 다수의 프로파테이를 사용해, 현재 위치, 정지 위치, 시간폭, 및 레이트를 취득 또는 설정할 수 있다. 다음의 코드예는, 그방법을 나타내고 있다.

    Set g_objMediaPosition = g_objMediaControl
    g_dblRunLength = g_objMediaPosition.Duration
    txtDuration.Text = CStr(g_dblRunLength)    '시간폭을 표시한다
    g_dblStartPosition = 0.0
    txtStart.Text = CDbl(g_dblStartPosition)   '시작 타임을 표시한다
    g_dblRate = g_objMediaPosition.Rate
    txtRate.Text = CStr(g_dblRate)

시작 위치의 취득과 설정

IMediaPosition.CurrentPosition 프로퍼티를 사용 하면, 유저가 비디오의 렌더링 시작 위치를 조정할 수 있다. 다음의 코드예에서는, 유저가 키를 누르면(자), 거기에 응해 현재의 위치를 변경한다.

Private Sub txtStart_KeyDown(KeyCode As Integer, Shift As Integer)
'유저 입력을 처리해 시작 위치를 변경한다
If KeyCode = vbKeyReturn Then
If g_objMediaPosition Is Nothing Then
Exit Sub
    ElseIf CDbl(txtStart.Text) > g_dblRunLength Then
MsgBox "Specified position invalid:re-enter new position. "
    ElseIf CDbl(txtStart.Text) < 0 Then
MsgBox "Specified position invalid:re-enter new position. "
    ElseIf CDbl(txtStart.Text) <> "" Then
        g_dblStartPosition = CDbl(txtStart.Text)
        g_objMediaPosition.CurrentPosition = g_dblStartPosition
End If
End If
End Sub

레이트의 취득과 설정

IMediaPosition.Rate 프로퍼티를 사용 하면, 유저가 비디오의 렌더링 레이트를 조정할 수 있다. 이 레이트는, 표준 재생 속도를 기준으로 하고 있다. 예를 들어, 레이트가 0.5 의 경우, 비디오는 표준 속도의 2 분의 1 의 속도로 렌더링 되어 레이트가 2.0 의 경우는 표준 레이트의 2 배의 속도로 렌더링 된다.

CurrentPosition 프로퍼티는 비디오의 렌더링중으로 설정할 수 있지만,Rate 프로퍼티는 렌더링의 전에 미리 설정해 둘 필요가 있다.

주 : 레이트가 1.0 미만 때는 사운드 트랙을 무효로 할 수 있는 비디오도 있다.

다음의 코드예에서는, 유저가 키를 누르면(자), 거기에 응해 레이트를 변경한다.

Private Sub txtRate_KeyDown(KeyCode As Integer, Shift As Integer)
' DirectShow VB 샘플
' Rate 값에 대한 유저에 의한 갱신을 처리한다
If KeyCode = vbKeyReturn Then
If g_objMediaPosition Is Nothing Then
Exit Sub
    ElseIf CDbl(txtRate.Text) < 0# Then
        MsgBox "Negative values invalid: re-enter value between 0 and 2.0"
    ElseIf CStr(txtRate.Text) <> "" Then
        g_dblRate = CDbl(txtRate.Text)
        g_objMediaPosition.Rate = g_dblRate
End If
End If
End Sub

클린 업

어플리케이션에서는, Visual Basic 의 Set 스테이트먼트를 사용해 새로운 DirectShow 오브젝트의 인스턴스를 생성 할 때마다, 다음의 코드예에 나타내도록(듯이), 대응하는 Set 스테이트먼트로 그 오브젝트 ( 및 관련하는 리소스)를 메모리로부터 삭제하고 나서 슛다운 할 필요가 있다.

Set g_objBasicAudio = Nothing


Visual Basic 오브젝트

Microsoft® DirectShow® 는, 그 기능의 서브 세트를 Microsoft® Visual Basic® 어플리케이션에 공개한다.

필터 그래프의 생성과 제어에는, 다음의 오브젝트를 사용한다.

  • IAMCollection 오브젝트
  • IBasicAudio 오브젝트
  • IBasicVideo 오브젝트
  • IFilterInfo 오브젝트
  • IMediaControl 오브젝트
  • IMediaEvent 오브젝트
  • IMediaPosition 오브젝트
  • IMediaTypeInfo 오브젝트
  • IPinInfo 오브젝트
  • IRegFilterInfo 오브젝트
  • IVideoWindow 오브젝트

DirectShow 편집 서비스 (DES)는, 비디오 편집을 위해서(때문에) 다음의 오브젝트를 지원 하고 있다.

  • AMTimeline
  • AMTimelineComp
  • AMTimelineEffect
  • AMTimelineGroup
  • AMTimelineObj
  • AMTimelineSrc
  • AMTimelineTrack
  • AMTimelineTrans
  • IAMTimelineEffectable
  • IAMTimelineSplittable
  • IAMTimelineTransable
  • IAMTimelineVirtualTrack
  • MediaDet
  • MediaLocator
  • RenderEngine
  • Xml2Dex


AMTimeline 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)의 중심적 오브젝트인타임 라인을 조작하는 메소드를 제공한다. 타임 라인은, 비디오 클립, 오디오 클립, 이펙트, 및 클립간의 트란지션 등, 시간순서의 요소의 콜렉션이다. 렌더링 엔진은, 타임 라인을 사용해 필터 그래프를 생성 한다. 어플리케이션은, 필터 그래프로부터 렌더링 된 출력을 생성할 수 있다.

AMTimeline 오브젝트는, 3 개의 기본적인 서비스를 제공한다.

  • 타임 라인내에 오브젝트를 생성 한다.
  • 생성 된 오브젝트의 컨테이너로서 기능한다.
  • 타임 라인의 일반적 파라미터의 설정과 취득을 실시한다.

메소드

AddGroup | 타임 라인에 그룹을 추가한다.
ClearAllGroups | 타임 라인내의 모든 그룹, 및 그것들에 포함되는 모든 오브젝트를 삭제한다.
CreateEmptyNode | 새로운 타임 라인 오브젝트를 생성 한다.
EffectsEnabled | 이펙트가 유효한가 어떤가를 조사한다.
EnableEffects | 타임 라인내의 모든 이펙트를 유효 또는 무효로 한다.
EnableTransitions | 타임 라인내의 모든 트란지션을 유효 또는 무효로 한다.
GetCountOfType | 지정된 그룹과 그 모든 아이에게 포함되는, 지정된 타입의 오브젝트의 개수를 취득한다.
GetDefaultEffect | Visual Basic 에서는 지원되어 있지 않다.
GetDefaultEffectB | 디폴트의 이펙트를 취득한다.
GetDefaultFPS | 디폴트의 출력 frame rate (매초의 프레임수)를 취득한다.
GetDefaultTransition | Visual Basic 에서는 지원되어 있지 않다.
GetDefaultTransitionB | 디폴트의 트란지션을 취득한다.
GetDirtyRange | Visual Basic 에서는 지원되어 있지 않다.
GetDuration | Visual Basic 에서는 지원되어 있지 않다.
GetDuration2 | 타임 라인의 시간폭을 취득한다.
GetGroup | 지정된 그룹을 취득한다.
GetGroupCount | 타임 라인에 포함되는 그룹의 개수를 취득한다.
GetInsertMode | Visual Basic 에서는 지원되어 있지 않다.
IsDirty | Visual Basic 에서는 지원되어 있지 않다.
RemGroupFromList | Visual Basic 에서는 지원되어 있지 않다.
SetDefaultEffect | Visual Basic 에서는 지원되어 있지 않다.
SetDefaultEffectB | 디폴트의 이펙트를 설정한다.
SetDefaultFPS | 디폴트의 출력 frame rate (매초의 프레임수)를 설정한다.
SetDefaultTransition | Visual Basic 에서는 지원되어 있지 않다.
SetDefaultTransitionB | 디폴트의 트란지션을 설정한다.
SetInsertMode | Visual Basic 에서는 지원되어 있지 않다.
SetInterestRange | Visual Basic 에서는 지원되어 있지 않다.
TransitionsEnabled | 트란지션이 유효한가 어떤가를 조사한다.
ValidateSourceNames | 타임 라인내의 소스명을 검증한다.

AddGroup 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

타임 라인에그룹을 추가한다.

구문

object. AddGroup(
pGroup As IAMTimelineObj
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
pGroup
그룹을 지정하는 AMTimelineObj 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG | 그룹의 최대수를 넘었다.
E_NOINTERFACE | 이 오브젝트는 그룹은 아니다.

주의

현재, 타임 라인이 지원 하는 그룹의 최대수는 32 이다.

ClearAllGroups 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

타임 라인내의 모든 그룹, 및 그것들에 포함되는 모든 오브젝트를 삭제한다.

구문

object. ClearAllGroups()

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

CreateEmptyNode 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

새로운 타임 라인 오브젝트를 생성 한다.

이 메소드는 중요한 초기화 루틴을 실행하므로, 타임 라인의 생성에는 이 메소드를 사용해,New 키워드는 사용하지 않는다.

구문

object. CreateEmptyNode(
ppObj As AMTimelineObj,
Type As TIMELINE_MAJOR_TYPE
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
ppObj
새로운 오브젝트를 받는 AMTimelineObj 오브젝트.
Type
생성 하는 오브젝트의 타입을 지정하는 TIMELINE_MAJOR_TYPE 열거형의 멤버.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 오브젝트 타입이 유효하지 않다.
E_OUTOFMEMORY | 메모리 부족.

EffectsEnabled 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

이펙트가 유효한가 어떤가를 조사한다. 이펙트가 무효의 경우, 이펙트는 타임 라인내에 존재한 채로이지만, 렌더링은 되지 않는다.

구문

object. EffectsEnabled(
pfEnabled As Long
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
pfEnabled
이펙트가 유효한가 어떤가를 나타내는 값을 받는 변수. 값이 제로의 경우는, 이펙트는 무효이다. 값이 제로 이외의 경우는, 이펙트는 유효하다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

EnableEffects 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

타임 라인내의 모든 이펙트를 유효 또는 무효로 한다. 이펙트가 무효의 경우, 이펙트는 타임 라인내에 존재한 채로이지만, 렌더링은 되지 않는다.

구문

object. EnableEffects(
fEnabled As Long
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
fEnabled
이펙트를 유효 또는 무효의 어느 쪽으로 설정하는지를 나타내는 값. 제로의 경우는, 이펙트는 무효가 된다. 제로 이외의 경우는, 이펙트는 유효하게 된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

EnableTransitions 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

타임 라인내의 모든 트란지션을 유효 또는 무효로 한다. 트란지션이 무효의 경우, 렌더링 엔진은 트란지션을 컷 (직접 바꾸고)으로서 취급한다. 즉, 렌더링 된 출력으로는,트럭으로부터 다음의 트럭에 즉석에서 바뀐다. 디폴트의 컷 포인트는, 트란지션의 시간폭의 중간점이다. 트란지션에 대해서 IAMTimelineTrans.SetCutPoint 메소드를 호출하는 것으로, 컷 포인트를 변경할 수 있다. 트란지션은, 무효가 되어도 타임 라인에 남아 있다.

구문

object. EnableTransitions(
fEnabled As Long
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
fEnabled
트란지션을 유효 또는 무효의 어느 쪽으로 설정하는지를 나타내는 값. 제로의 경우는, 트란지션은 무효가 된다. 제로 이외의 경우는, 트란지션은 유효하게 된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetCountOfType 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

지정된 그룹과 그 모든 아이에게 포함되는, 지정된 타입의 오브젝트의 개수를 취득한다.

구문

object. GetCountOfType(
Group As Long,
pVal As Long,
pValWithComps As Long,
MajorType As TIMELINE_MAJOR_TYPE
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
Group
오브젝트의 개수를 취득하는 그룹의 인덱스 번호.
pVal
그룹 및 그 모든가상 트럭에 포함되는 (재귀적으로 내부에 포함되는 오브젝트도 포함한다), 지정된 타입의 오브젝트의 개수를 받는 변수.
pValWithComps
pVal 에 돌려주어진 개수에, 이것 자체도 포함해 검색된 합성의 개수를 더한 수를 받는 변수.
MajorType
TIMELINE_MAJOR_TYPE 열거형의 멤버. 개수를 세는 오브젝트의 타입을 지정한다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 무효인 그룹 번호.

주의

이 메소드의 호출은, 지정한 그룹에 대한 AMTimelineComp.GetCountOfType 의 호출해에 상당한다. 상세한 것에 대하여는, 그 메소드의 「주의」를 참조할것.

보통, 어플리케이션에서는 이 메소드를 호출하지 않는다. 렌더링 엔진에 의해 내부적으로 불려 간다.

GetDefaultEffect 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetDefaultEffect(
pGuid As GUID
)

GetDefaultEffectB 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

디폴트의 이펙트를 취득한다. 렌더링 엔진이 이펙트를 렌더링 할 수 없는 경우, 디폴트의 이펙트가 대용된다.

구문

object. GetDefaultEffectB() As String

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.

반환값

디폴트 이펙트의 GUID 를 나타내는 캐릭터 라인을 돌려준다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_OUTOFMEMORY 메모리 부족.

GetDefaultFPS 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

디폴트의 출력 frame rate (매초의 프레임수, FPS)를 취득한다. 그룹은, 이 값을 디폴트의 frame rate로서 사용한다. 그룹의 frame rate를 설정하려면 , 그룹에 대해서 AMTimelineGroup.SetOutputFPS 메소드를 호출한다.

구문

object. GetDefaultFPS(
pFPS As Double
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
pFPS
디폴트의 frame rate (매초의 프레임수)를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetDefaultTransition 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetDefaultTransition(
pGuid As GUID
)

GetDefaultTransitionB 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

디폴트의 트란지션을 취득한다. 렌더링 엔진이 트란지션을 렌더링 할 수 없는 경우는, 디폴트의 트란지션이 대용된다.

구문

object. GetDefaultTransitionB() As *pGuid

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.

반환값

디폴트의 트란지션의 GUID 를 나타내는 캐릭터 라인을 돌려준다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_OUTOFMEMORY 메모리 부족.

GetDirtyRange 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetDirtyRange(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

GetDuration 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetDuration(
pDuration As <Unsupported variant type>
)

GetDuration2 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

타임 라인의 시간폭을 취득한다.

구문

object. GetDuration2(
pDuration As Double
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
pDuration
타임 라인의 시간폭 (초수)을 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetGroup 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

지정된 그룹을 취득한다.

구문

object. GetGroup(
ppGroup As AMTimelineObj,
WhichGroup As Long
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
ppGroup
지정한 그룹을 받는 AMTimelineObj 오브젝트.
WhichGroup
취득하는 그룹의 인덱스. 이 인덱스는, 그룹이 타임 라인에 추가된 순서에 근거한다. 타임 라인에 최초로 추가된 그룹의 인덱스는 0 이 된다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 무효인 인수.

GetGroupCount 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

타임 라인에 포함되는 그룹의 개수를 취득한다.

구문

object. GetGroupCount(
pCount As Long
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
pCount
타임 라인내의 그룹의 개수를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetInsertMode 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetInsertMode(
pMode As Long
)

IsDirty 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. IsDirty(
pDirty As Long
);

RemGroupFromList 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. RemGroupFromList(
pGroup As AMTimelineObj
);

SetDefaultEffect 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetDefaultEffect(
pGuid As GUID
)

SetDefaultEffectB 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

디폴트의 이펙트를 설정한다. 렌더링 엔진이 이펙트를 렌더링 할 수 없는 경우는, 디폴트의 이펙트가 대용된다.

구문

object. SetDefaultEffectB(
pGuid As String
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
pGuid
디폴트 이펙트의 GUID 를 나타내는 캐릭터 라인.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_OUTOFMEMORY 메모리 부족.

주의

디폴트 이펙트를 설정하고 있지 않는 경우, 또는 디폴트로 지정한 이펙트로 에러가 발생했을 경우는, DES 자체의 디폴트 이펙트가 사용된다.

SetDefaultFPS 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

디폴트의 출력 frame rate (매초의 프레임수)를 설정한다. 그룹은, 이 값을 디폴트의 frame rate로서 사용한다. 그룹의 frame rate를 설정하려면 , 그룹에 대해서 AMTimelineGroup.SetOutputFPS 메소드를 호출한다.

구문

object. SetDefaultFPS(
FPS As Double
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
FPS
디폴트의 frame rate (매초의 프레임수).

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SetDefaultTransition 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetDefaultTransition(
pGuid As GUID
)

SetDefaultTransitionB 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

디폴트의 트란지션을 설정한다. 렌더링 엔진이 트란지션을 렌더링 할 수 없는 경우는, 디폴트의 트란지션이 대용된다.

구문

object. SetDefaultTransitionB(
pGuid As String
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
pGuid
디폴트의 트란지션의 GUID 를 나타내는 캐릭터 라인.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_OUTOFMEMORY 메모리 부족.

주의

디폴트의 트란지션을 설정하고 있지 않는 경우, 또는 디폴트로 지정한 트란지션으로 에러가 발생했을 경우는, DES 자체의 디폴트의 트란지션이 사용된다.

SetInsertMode 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetInsertMode(
Mode As Long
)

SetInterestRange 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetInterestRange(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

TransitionsEnabled 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

트란지션이 유효한가 어떤가를 조사한다.

구문

object. TransitionsEnabled(
pfEnabled As Long
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
pfEnabled
트란지션이 유효한가 어떤가를 지정하는 값. 제로의 경우는, 트란지션은 무효이다. 제로 이외의 경우는, 트란지션은 유효하다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

참조

EnableTransitions

ValidateSourceNames 메소드 (AMTimeline 오브젝트)

AMTimeline 오브젝트

미디어 locator를 사용해, 타임 라인내의 소스명을 검증한다. 옵션으로, 이 메소드는 발견된 파일의 소스 오브젝트를 갱신한다.

구문

object. ValidateSourceNames(
ValidateFlags As Long,
pOverride As MediaLocator,
NotifyEventHandle As LONG_PTR
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
ValidateFlags
미디어 locator의 동작을 지정하는,검증 플래그 의 비트마다의 편성. SFN_VALIDATEF_REPLACE 플래그와 SFN_VALIDATEF_CHECK 플래그는, 반드시 지정해야 한다. 지정하지 않으면 메소드로부터 E_INVALIDARG 가 돌아간다.
pOverride
생략 가능. 디폴트 대신에 사용하는 MediaLocator 오브젝트. 디폴트의 미디어 locator를 사용하려면 , 이 파라미터의 값을 Nothing 로 설정한다.
NotifyEventHandle
LONG_PTR 타입의 변수. 이 파라미터는 무시되므로, 제로로 상관없다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 무효인 인수.


AMTimelineComp 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)로,합성 위에의가상 트럭을 삽입 또는 취득한다.

합성은, 합성된트럭으로서 기능하는, 계층의 콜렉션이다. 예를 들어, 2 개의 트럭과 그러한 사이의 트란지션으로부터 되는 합성은, 그 트란지션이 미리 합성되고 있는 단일의 트럭으로서 기능한다. 합성에는, 같은 타입 (오디오 또는 비디오)의 미디어만을 넣도록(듯이) 할 필요가 있지만, 이 제한은 강제당하지 않는다. 가상 트럭은, 합성내에 배치할 수 있는, 트럭 및 다른 합성도 포함한 임의의 오브젝트이다.

타임 라인의 최상정도의 노드는그룹이다. 그룹은,AMTimelineComp 와 AMTimelineGroup 의 양쪽 모두를 지원 한다.

상세한 것에 대하여는, 「타임 라인 모델」을 참조할것.

메소드

GetCountOfType | 이 합성 및 그 모든 가상 트럭에 포함되는 (재귀적으로 내부에 포함되는 오브젝트도 포함한다), 지정된 타입의 오브젝트의 개수를 취득한다.
GetNextVTrack | 지정된 가상 트럭의 다음의 가상 트럭을 취득한다.
GetRecursiveLayerOfType | 이 합성에 포함되는 가상 트럭을 깊이의 깊은 순서에 순서 붙여 그 순서로 n 번째의 가상 트럭을 취득한다.
GetRecursiveLayerOfTypeI | Visual Basic 에서는 지원되어 있지 않다.
GetVTrack | 지정된 우선 순위의 가상 트럭을 취득한다.
VTrackGetCount | 합성에 포함되는 가상 트럭의 개수를 취득한다.
VTrackInsBefore | 합성으로 지정의 우선 순위로 가상 트럭을 삽입한다.
VTrackSwapPriorities | 2 개의 트럭의 우선 순위 레벨을 바꿔 넣는다.

GetCountOfType 메소드 (AMTimelineComp 오브젝트)

AMTimelineComp 오브젝트

이 합성 및 그 모든 가상 트럭에 포함되는 (재귀적으로 내부에 포함되는 오브젝트도 포함한다), 지정된 타입의 오브젝트의 개수를 취득한다.

구문

object. GetCountOfType(
pVal As Long,
pValWithComps As Long,
MajorType As TIMELINE_MAJOR_TYPE
)

파라미터

object
결과가 AMTimelineComp 오브젝트가 되는 오브젝트식.
pVal
이 합성 및 그 모든 가상 트럭에 포함되는 (재귀적으로 내부에 포함되는 오브젝트도 포함한다), 지정된 타입의 오브젝트의 개수를 받는 변수.
pValWithComps
pVal 에 돌려주어진 개수와 이것 자체도 포함해 검색된 합성의 개수를 더한 수를 받는 변수.
MajorType
TIMELINE_MAJOR_TYPE 열거형의 멤버. 개수를 세는 오브젝트의 타입을 지정한다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

보통, 어플리케이션에서는 이 메소드를 호출하지 않는다. 이 메소드는, 렌더링 엔진에 의해 불려 간다.

합성의 개수를 조사했을 경우,pVal 에 돌려주어지는 값은 제로로,pValWithComps 에 돌려주어지는 값이 합성의 개수이다. pValWithComps 의 값에는, 메소드를 호출한 합성도 포함된다. 예를 들어, 하늘의 합성으로 이 메소드를 호출했을 경우,pValWithComps 는 1 이 된다.

그룹은 합성안에 배치할 수 없기 때문에, 이 메소드로 그룹의 수를 조사할 수 없다 (돌려주어지는 수는 항상 제로가 된다). 그룹의 수를 조사하려면 ,AMTimeline.GetGroupCount 메소드를 호출한다.

GetNextVTrack 메소드 (AMTimelineComp 오브젝트)

AMTimelineComp 오브젝트

지정된 가상 트럭의 다음의 가상 트럭을 취득한다.

구문

object. GetNextVTrack(
pVirtualTrack As AMTimelineObj,
ppNextVirtualTrack As AMTimelineObj
)

파라미터

object
결과가 AMTimelineComp 오브젝트가 되는 오브젝트식.
pVirtualTrack
전의 가상 트럭을 지정하는 AMTimelineObj 오브젝트. 합성내의 최초의 가상 트럭을 취득하는 경우는 Nothing.
ppNextVirtualTrack
다음의 우선 순위의 가상 트럭을 받는 AMTimelineObj 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetRecursiveLayerOfType 메소드 (AMTimelineComp 오브젝트)

AMTimelineComp 오브젝트

이 합성에 포함되는 가상 트럭을 깊이의 깊은 순서에 순서 붙여 그 순서로 n 번째의 가상 트럭을 취득한다.

구문

object. GetRecursiveLayerOfType(
ppVirtualTrack As AMTimelineObj,
WhichLayer As Long,
Type As TIMELINE_MAJOR_TYPE
)

파라미터

object
결과가 AMTimelineComp 오브젝트가 되는 오브젝트식.
ppVirtualTrack
가상 트럭을 받는 AMTimelineObj 오브젝트.
WhichLayer
취득하는 가상 트럭을 지정하는, 제로로부터 시작되는 인덱스의 값.
Type
TIMELINE_MAJOR_TYPE 열거형의 멤버. 검색에 트럭을 포함할지 어떨지를 지정한다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 지정된 타입의 오브젝트가 없다.

주의

보통, 어플리케이션으로 이 메소드를 호출할 필요는 없다.

Type 파라미터가 TIMELINE_MAJOR_TYPE_TRACK 의 경우는, 깊이의 순서부에 트럭도 포함된다. 그 이외의 경우는, 합성과 그룹만이 포함된다. 그 오브젝트 자체도 순서부에 포함된다.

예를 들어, 합성 A 로부터 시작되는 다음과 같은 배치에서는, 순서는 B, C, F, D, E, A 가 된다.

GetRecursiveLayerOfTypeI 메소드 (AMTimelineComp 오브젝트)

AMTimelineComp 오브젝트

Visual Basic 에서는 지원되어 있지 않다. 대신에,GetRecursiveLayerOfType 메소드를 사용한다.

구문

object. GetRecursiveLayerOfTypeI(
ppVirtualTrack As AMTimelineObj,
pWhichLayer As Long,
Type As TIMELINE_MAJOR_TYPE
)

GetVTrack 메소드 (AMTimelineComp 오브젝트)

AMTimelineComp 오브젝트

지정된 우선 순위의 가상 트럭을 취득한다.

구문

object. GetVTrack(
ppVirtualTrack As AMTimelineObj,
Which As Long
)

파라미터

object
결과가 AMTimelineComp 오브젝트가 되는 오브젝트식.
ppVirtualTrack
가상 트럭을 받는 AMTimelineObj 오브젝트.
Which
취득하는 가상 트럭의 우선 순위.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 지정된 우선 순위의 가상 트럭이 없다.

VTrackGetCount 메소드 (AMTimelineComp 오브젝트)

AMTimelineComp 오브젝트

합성에 포함되는 가상 트럭의 개수를 취득한다.

구문

object. VTrackGetCount(
pVal As Long
)

파라미터

object
결과가 AMTimelineComp 오브젝트가 되는 오브젝트식.
pVal
가상 트럭의 수를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

VTrackInsBefore 메소드 (AMTimelineComp 오브젝트)

AMTimelineComp 오브젝트

합성으로 지정의 우선 순위로 가상 트럭을 삽입한다.

구문

object. VTrackInsBefore(
pVirtualTrack As AMTimelineObj,
Priority As Long
)

파라미터

object
결과가 AMTimelineComp 오브젝트가 되는 오브젝트식.
pVirtualTrack
가상 트럭을 지정하는 AMTimelineObj 오브젝트.
Priority
가상 트럭을 삽입하는 우선 순위. 우선 순위 리스트의 마지막에 가상 트럭을 삽입하는 경우는 -1.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 무효인 인수.
E_NOINTERFACE | pVirtualTrack 로 지정되고 있는 오브젝트가, 가상 트럭은 아니다.

주의

우선 순위 레벨은 제로로부터 시작된다. 타임 라인에, 지정된 우선 순위 레벨의 가상 트럭이 이미 존재하는 경우, 우선 순위 리스트의 그 위치 이하의 모든 것이 1 레벨씩 뒤로 돌릴 수 있어 삽입되는 트럭의 장소가 확보된다. 현재의 트럭의 개수보다 큰 값을 우선 순위로 지정했을 경우, 이 메소드는 실패한다.

VTrackSwapPriorities 메소드 (AMTimelineComp 오브젝트)

AMTimelineComp 오브젝트

2 개의 트럭의 우선 순위 레벨을 바꿔 넣는다.

이 메소드는, 지정된 2 개의 우선 순위 레벨을 가지는 각각의 가상 트럭의 우선 순위를 바꿔 넣는다. 이 메소드로부터 돌아온 시점에서, 최초로 지정된 우선 순위에 있던 트럭의 우선 순위는, 2 번째로 지정된 우선 순위 레벨이 되어, 2 번째로 지정된 우선 순위에 있던 트럭의 우선 순위는, 최초로 지정된 우선 순위 레벨이 되어 있다.

구문

object. VTrackSwapPriorities(
VirtualTrackA As Long,
VirtualTrackB As Long
)

파라미터

object
결과가 AMTimelineComp 오브젝트가 되는 오브젝트식.
VirtualTrackA
가상 트럭을 바꿔 넣는 최초의 우선 순위 레벨.
VirtualTrackB
가상 트럭을 바꿔 넣는 2 번째의 우선 순위 레벨.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 무효인 인수.


AMTimelineEffect 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)로 이펙트를 조작하기 위한 메소드를 제공한다.

AMTimelineEffect 오브젝트는, DES 가 지원 하는 모든 타입의 단일 입력 이펙트의 래퍼 오브젝트이다. 사용하는 이펙트를 지정하려면 , 목적의 이펙트에 대해서 AMTimelineObj.SetSubObjectGUID 메소드를 호출한다.

메소드

EffectGetPriority 이펙트의 우선 순위 레벨을 취득한다.

EffectGetPriority 메소드 (AMTimelineEffect 오브젝트)

AMTimelineEffect 오브젝트

이펙트의 우선 순위 레벨을 취득한다. 이펙트를 가지는 각 타임 라인 오브젝트에 대해, 렌더링 엔진은, 우선 순위 레벨 0 으로부터 시작해 우선 순위의 순서에, 그 오브젝트의 이펙트를 적용한다.

구문

object. EffectGetPriority(
pVal As Long
)

파라미터

object
결과가 AMTimelineEffect 오브젝트가 되는 오브젝트식.
pVal
우선 순위 레벨을 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.


AMTimelineGroup 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)로그룹의 프로퍼티를 설정 및 취득한다.

그룹은 1 개 이상의트럭과 경우에 의해 1 개 이상의합성을 가져, 트럭은 동일 타입 (비디오나 오디오등)의 소스 클립을 가진다. 그룹은,타임 라인의 최상정도의 합성이며, 또 AMTimelineComp 오브젝트를 지원 한다. 타임 라인은, 복수의 그룹을 가질 수가 있다.

각 그룹에는 이하의 속성이 있다.

  • 관련지을 수 있었던 미디어 타입.
  • 그룹이 렌더링 되는 frame rate (매초의 프레임수, FPS). 모든 편집이 시작되는 시간은, 그룹의 FPS 설정에 의해 정의되는 가장 가까운 프레임 경계에 말 수 있다.
  • 우선 순위 레벨. 같은 미디어 타입의 복수의 스트림을 가지는 파일 (예를 들어, 2 개의 비디오 스트림을 가지는 AVI 파일)을 기입할 때에 사용된다.

메소드

ClearRecompressFormatDirty | Visual Basic 에서는 지원되어 있지 않다.
GetGroupName | 어플리케이션으로 정의되고 있는 그룹의 이름을 취득한다.
GetMediaType | Visual Basic 에서는 지원되어 있지 않다.
GetOutputBuffering | 프리뷰시에 선행해 렌더링 되는 프레임수를 취득한다.
GetOutputFPS | 이 그룹의 출력 frame rate를 취득한다.
GetPreviewMode | 그룹의 프리뷰 모드를 취득한다.
GetPriority | 그룹의 우선 순위를 취득한다.
GetSmartRecompressFormat | Visual Basic 에서는 지원되어 있지 않다.
GetTimeline | 이 그룹이 소속하는 타임 라인을 취득한다.
IsRecompressFormatDirty | Visual Basic 에서는 지원되어 있지 않다.
IsSmartRecompressFormatSet | Visual Basic 에서는 지원되어 있지 않다.
SetGroupName | 어플리케이션으로 정의되고 있는 그룹의 이름을 설정한다.
SetMediaType | Visual Basic 에서는 지원되어 있지 않다.
SetMediaTypeForVB | 그룹의 미디어 타입을 지정한다.
SetOutputBuffering | 프리뷰시에 선행해 렌더링 되는 프레임수를 지정한다.
SetOutputFPS | 이 그룹의 비압축 출력 frame rate를 설정한다.
SetPreviewMode | 그룹의 프리뷰 모드를 설정한다.
SetRecompFormatFromSource | 원시 파일의 압축 포맷을 사용해 비디오재압축 포맷을 설정한다.
SetSmartRecompressFormat | Visual Basic 에서는 지원되어 있지 않다.
SetTimeline | Visual Basic 에서는 지원되어 있지 않다.

ClearRecompressFormatDirty 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. ClearRecompressFormatDirty()

GetGroupName 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

어플리케이션으로 정의되고 있는 그룹의 이름을 취득한다.

구문

object. GetGroupName() As String

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.

반환값

어플리케이션으로 정의되고 있는 그룹의 이름을 돌려준다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetMediaType 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetMediaType(
pmt As _AMMediaType
)

GetOutputBuffering 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

프리뷰시에 선행해 렌더링 되는 프레임수를 취득한다.

구문

object. GetOutputBuffering(
pnBuffer As Long
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
pnBuffer
버퍼링 되는 프레임의 수를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetOutputFPS 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

이 그룹의 출력 frame rate를 취득한다.

구문

object. GetOutputFPS(
pFPS As Double
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
pFPS
출력 frame rate (매초의 프레임수)를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetPreviewMode 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

그룹의 프리뷰 모드를 취득한다.

구문

object. GetPreviewMode(
pfPreview As Long
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
pfPreview
프리뷰 모드를 나타내는 값을 받는 변수. 제로의 경우, 그룹은 오쏘링 모드이다. 제로 이외의 경우, 그룹은 프리뷰 모드이다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

프리뷰 모드에서는, 비디오와 오디오의 동기를 유지하기 위해서, 시간이 걸리는 이펙트 또는 트란지션에서는 프레임 빠짐이 생긴다. 그 때문에, 비디오의 움직임 그림의 기법 여기 없어지는 일이 있다. 오쏘링 모드에서는, 모든 프레임이 렌더링 된다. 오쏘링 모드는 파일에의 기입에 적절하고 있다. 오쏘링 모드로 화면에 프리뷰를 실시하면, 비디오와 오디오의 동기 금액 빗나가는 경우가 있다.

GetPriority 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

그룹의 우선 순위를 취득한다.

구문

object. GetPriority(
pPriority As Long
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
pPriority
그룹의 우선 순위를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetSmartRecompressFormat 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetSmartRecompressFormat(
ppFormat As Long
)

GetTimeline 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

이 그룹이 소속하는 타임 라인을 취득한다.

구문

object. GetTimeline(
ppTimeline As AMTimeline
)

파라미터

object
결과가 AMTimeline 오브젝트가 되는 오브젝트식.
ppTimeline
타임 라인을 받는 AMTimeline 오브젝트. 그룹이 타임 라인이 일부에서 없는 경우, 오브젝트는 Nothing 로 설정된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

IsRecompressFormatDirty 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. IsRecompressFormatDirty(
pVal As Long
)

IsSmartRecompressFormatSet 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. IsSmartRecompressFormatSet(
pVal As Long
)

SetGroupName 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

어플리케이션으로 정의되고 있는 그룹의 이름을 설정한다.

구문

object. SetGroupName(
pGroupName As String
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
pGroupName
그룹의 이름.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SetMediaType 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

Visual Basic 에서는 지원되어 있지 않다. 대신에,SetMediaTypeForVB 메소드를 사용한다.

구문

object. SetMediaType(
pmt As _AMMediaType
)

SetMediaTypeForVB 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

그룹의 미디어 타입을 지정한다.

구문

object. SetMediaTypeForVB(
Val As Long
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
Val
미디어 타입을 지정하는 값.
제로 | 비디오
제로 이외 | 오디오

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

이 메소드는, 다음의 포맷을 지원 하고 있다.

  • 비디오:320 × 240 16 비트 RGB, 555 포맷 (MEDIASUBTYPE_RGB555).
  • 오디오:44. 1kHz 스테레오 PCM, 1 샘플 16 비트 (MEDIASUBTYPE_PCM)

SetOutputBuffering 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

프리뷰시에 선행해 렌더링 되는 프레임수를 지정한다.

구문

object. SetOutputBuffering(
nBuffer As Long
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
nBuffer
프리뷰시에 버퍼링 되는 프레임수. 2 이상이 아니면 안된다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 무효인 인수.

주의

버퍼가 커지면, 필요한 메모리량도 커지지만, 프리뷰는 보다 스무스하게 된다. 특히, 렌더링에 시간이 걸리는 이펙트 또는 트란지션으로, 그것이 현저하다. 디폴트의 버퍼는 30 프레임이다.

SetOutputFPS 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

이 그룹의 비압축 출력 frame rate를 설정한다.

구문

object. SetOutputFPS(
FPS As Double
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
FPS
이 그룹의 출력 frame rate (매초의 프레임수). 이 값은, 제로로 하지 못하고, 소수점 이하를 8 자리수 이상 지정할 수 없다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 무효인 인수.

주의

이 그룹으로부터 렌더링 된 출력은, 지정된 frame rate로 실행되어 소스 소재 위에의 모든 편집은, frame rate에 의해 정의되는 가장 가까운 프레임 경계에 말 수 있다.

SetPreviewMode 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

그룹의 프리뷰 모드를 설정한다.

구문

object. SetPreviewMode(
fPreview As Long
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
fPreview
프리뷰 모드를 지정하는 값. 제로를 지정 하면, 그룹은 오쏘링 모드가 된다. 제로 이외를 지정 하면, 그룹은 프리뷰 모드가 된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

프리뷰 모드에서는, 비디오와 오디오의 동기를 유지하기 위해서, 시간이 걸리는 이펙트 또는 트란지션에서는 프레임 빠짐이 생긴다. 그 때문에, 비디오의 움직임 그림의 기법 여기 없어지는 일이 있다. 오쏘링 모드에서는, 모든 프레임이 렌더링 된다. 오쏘링 모드는 파일에의 기입에 적절하고 있다. 오쏘링 모드로 화면에 프리뷰를 실시하면, 비디오와 오디오의 동기 금액 빗나가는 경우가 있다.

SetRecompFormatFromSource 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

원시 파일의 압축 포맷을 사용해 비디오재압축 포맷을 설정한다.

구문

object. SetRecompFormatFromSource(
pSource As AMTimelineSrc
)

파라미터

object
결과가 AMTimelineGroup 오브젝트가 되는 오브젝트식.
pSource
IAMTimelineSrc 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_NO_TIMELINE | 그룹이 타임 라인내에 없다.
E_OUTOFMEMORY | 메모리 부족.
VFW_E_INVALIDMEDIATYPE | 원시 파일에 비디오 스트림이 없다.

주의

이 메소드는,pSource 에 관련지을 수 있었던 원시 파일을 찾아, 파일의 최초의 비디오 스트림의 미디어 타입을 취득한다. 다음에, 그 타입을 사용해 그룹의 압축 포맷을 설정한다.

SetSmartRecompressFormat 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetSmartRecompressFormat(
pFormat As Long
)

SetTimeline 메소드 (AMTimelineGroup 오브젝트)

AMTimelineGroup 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetTimeline(
pTimeline As AMTimeline
)


AMTimelineObj 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)의타임 라인 오브젝트를 조작하는 메소드를 제공한다. 소스, 이펙트, 트란지션, 트럭, 그룹, 및 합성을 포함한 모든 타임 라인 오브젝트는,AMTimelienObj 를 지원 한다. AMTimeline.CreateEmptyNode 메소드를 호출해, 타임 라인 오브젝트를 생성 해야 한다.

메소드

ClearDirty | Visual Basic 에서는 지원되어 있지 않다.
FixTimes | Visual Basic 에서는 지원되어 있지 않다.
FixTimes2 | 지정된 시작 타임과 종료 타임을, 친그룹의 frame rate 설정에 의해 정의되는 가장 가까운 프레임 경계에 말다.
GetDirtyRange | Visual Basic 에서는 지원되어 있지 않다.
GetDirtyRange2 | Visual Basic 에서는 지원되어 있지 않다.
GetEmbedDepth | Visual Basic 에서는 지원되어 있지 않다.
GetGenID | 오브젝트의 생성된 식별자를 취득한다.
GetGroupIBelongTo | Visual Basic 에서는 지원되어 있지 않다.
GetLocked | 오브젝트의 편집 상태 (락 또는 락 해제)를 취득한다.
GetMuted | 오브젝트의 뮤트 상태를 취득한다.
GetPropertySetter | Visual Basic 에서는 지원되어 있지 않다.
GetStartStop | Visual Basic 에서는 지원되어 있지 않다.
GetStartStop2 | 오브젝트의 부모를 기준으로 하는, 오브젝트의 시작 타임과 종료 타임을 취득한다.
GetSubObject | Visual Basic 에서는 지원되어 있지 않다.
GetSubObjectGUID | Visual Basic 에서는 지원되어 있지 않다.
GetSubObjectGUIDB | 이 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 GUID 를 취득한다.
GetSubObjectLoaded | 오브젝트에 서브 오브젝트가 생성 되고 있는지 어떤지를 조사한다.
GetTimelineNoRef | Visual Basic 에서는 지원되어 있지 않다.
GetTimelineType | 오브젝트의 타입을 취득한다.
GetUserData | 어플리케이션 정의의 지속적 데이터를 취득한다.
GetUserID | 오브젝트의 어플리케이션 정의의 식별자를 취득한다.
GetUserName | 오브젝트의 어플리케이션 정의의 이름을 취득한다.
Remove | 이 오브젝트를 타임 라인으로부터 삭제해, 다른 장소에 재삽입할 수 있도록(듯이) 한다.
RemoveAll | 이 오브젝트를, 서브 오브젝트와 아이를 포함해, 타임 라인으로부터 영속적으로 삭제한다.
SetDirtyRange | Visual Basic 에서는 지원되어 있지 않다.
SetDirtyRange2 | Visual Basic 에서는 지원되어 있지 않다.
SetLocked | 오브젝트의 편집 상태를 락 또는 락 해제로 설정한다.
SetMuted | 오브젝트의 뮤트 상태를 설정한다.
SetPropertySetter | Visual Basic 에서는 지원되어 있지 않다.
SetStartStop | Visual Basic 에서는 지원되어 있지 않다.
SetStartStop2 | 오브젝트의 부모를 기준으로서 오브젝트의 시작 타임과 종료 타임을 설정한다.
SetSubObject | Visual Basic 에서는 지원되어 있지 않다.
SetSubObjectGUID | Visual Basic 에서는 지원되어 있지 않다.
SetSubObjectGUIDB | 이 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 GUID 를 지정한다.
SetTimelineType | Visual Basic 에서는 지원되어 있지 않다.
SetUserData | 어플리케이션 정의의 지속적 데이터를 설정한다.
SetUserID | 오브젝트에 대한 어플리케이션 정의의 식별자를 설정한다.
SetUserName | 오브젝트에 대한 어플리케이션 정의의 이름을 설정한다.

ClearDirty 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. ClearDirty()

FixTimes 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. FixTimes(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

FixTimes2 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

지정된 시작 타임과 종료 타임을, 친그룹의 frame rate 설정에 의해 정의되는 가장 가까운 프레임 경계에 말다.

구문

object. FixTimes2(
pStart As Double,
REFTIME As Double*pStop
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pStart
시작 타임 (초단위)이 설정되어 있는 변수. 호출이 성공했을 경우는, 말 수 있었던 시간이 설정된다.
pStop
종료 타임 (초단위)이 설정되어 있는 변수. 호출이 성공했을 경우는, 말 수 있었던 시간이 설정된다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_NOTINTREE 오브젝트가 타임 라인내에 없다.

주의

렌더링시에, DES 는 오브젝트의 시작 타임과 종료 타임을, 가장 가까운 프레임 경계에 말다. 다만, DES 는 오브젝트의 시간은 고쳐 쓰지 않는다. 그룹의 frame rate를 변경했을 경우, 말 수 있었던 시간은 반드시 원의 시간부터 계산된다. 상세한 것에 대하여는, 「frame rate」를 참조할것.

이 메소드를 사용해, 렌더링 된 오브젝트내에서의 정확한 시작 타임과 종료 타임을 특정할 수 있다. 예를 들어, 프로젝트내에서 시크 하는 경우는, 원의 시간은 아니고 말 수 있었던 시간을 시크 해야 한다. GetStartStop2 를 호출해 원의 시간을 취득해, 그 값을 FixTimes2 에 건네준다.

GetDirtyRange 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetDirtyRange(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

GetDirtyRange2 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetDirtyRange2(
pStart As Double,
pStop As Double
)

GetEmbedDepth 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetEmbedDepth(
pVal As Long
)

GetGenID 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 생성된 식별자를 취득한다. 식별자는 예약된 번호이다. 어플리케이션으로 사용해서는 안 된다.

구문

object. GetGenID(
pVal As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pVal
생성된 식별자를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetGroupIBelongTo 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetGroupIBelongTo(
ppGroup As AMTimelineGroup
)

GetLocked 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 편집 상태 (락 또는 락 해제)를 취득한다. 락 상태는 오브젝트를 편집해서는 안 되는 것을 나타내, 락 해제 상태는 오브젝트를 편집할 수 있는 것을 나타낸다. 타임 라인측에서는, 락을 강제하지 않는다. 락 상태의 설정은, 어플리케이션측의 편리성을 위해서(때문에) 마셔 존재한다.

구문

GetLocked(
pVal As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pVal
오브젝트의 편집 상태를 받는 변수. 값이 제로의 경우는, 오브젝트는 락 해제되고 있으므로 편집할 수 있다. 값이 제로 이외의 경우는, 오브젝트는 락 되고 있으므로, 편집해서는 안 된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetMuted 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 뮤트 상태를 취득한다. 뮤트 된 오브젝트는 렌더링 되지 않지만, 타임 라인내에는 존재한 채로된다.

구문

object. GetMuted(
pVal As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pVal
뮤트 상태를 나타내는 값을 받는 변수. 값이 제로의 경우는, 오브젝트는 뮤트되어 있지 않다. 값이 제로 이외의 경우는, 오브젝트와 그 아이는 뮤트 되고 있다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

오브젝트의 부모가 뮤트 되고 있는 경우, 뮤트 상태 (와)는 관계없는 것으로, 그 오브젝트도 뮤트 된다. 부모의 뮤트가 해제되었을 때는, 그 오브젝트의 전의 뮤트 상태가 복원된다.

GetPropertySetter 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetPropertySetter() As PropertySetter

GetStartStop 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetStartStop(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

GetStartStop2 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 부모를 기준으로 하는, 오브젝트의 시작 타임과 종료 타임을 취득한다.

구문

object. GetStartStop2(
pStart As Double,
pStop As Double
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pStart
시작 타임 (초단위)을 받는 변수.
pStop
종료 타임 (초단위)을 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

합성, 그룹, 및 트럭의 시작 타임은 항상 0 이다.

렌더링시에, DES 는 오브젝트의 시작 타임과 종료 타임을, 가장 가까운 프레임 경계에 말다. 다만, DES 는 오브젝트의 시간은 고쳐 쓰지 않는다. 그룹의 frame rate를 변경했을 경우, 말 수 있었던 시간은 반드시 원의 시간부터 계산된다. 상세한 것에 대하여는, 「frame rate」를 참조할것. 렌더링 된 프로젝트내에서의 시작 타임을 종료 타임을 조사하려면 ,GetStartStop2 가 돌려주는 값을 FixTimes2 메소드에 건네준다.

GetSubObject 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetSubObject(
pVal As Unknown
)

GetSubObjectGUID 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetSubObjectGUID(
pVal As GUID
)

GetSubObjectGUIDB 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

이 타임 라인 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 GUID 를 취득한다.

구문

object. GetSubObjectGUIDB() As String

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.

반환값

서브 오브젝트의 GUID 를 나타내는 캐릭터 라인을 돌려준다. 오브젝트에 서브 오브젝트가 없는 경우는, 반환값은 {00000000-0000-0000-0000-000000000000} 이다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_OUTOFMEMORY 메모리 부족.

GetSubObjectLoaded 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트에 서브 오브젝트가 생성 되고 있는지 어떤지를 조사한다.

구문

object. GetSubObjectLoaded(
pVal As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pVal
서브 오브젝트가 생성 되고 있는지 어떤지를 나타내는 값을 받는 변수. 제로의 경우는, 서브 오브젝트는 생성되어 있지 않다. 제로 이외의 경우는, 서브 오브젝트는 생성 되고 있다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetTimelineNoRef 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetTimelineNoRef(
ppResult As AMTimeline
)

GetTimelineType 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 타입을 취득한다.

구문

object. GetTimelineType(
pVal As TIMELINE_MAJOR_TYPE
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pVal
오브젝트의 타입을 나타내는,TIMELINE_MAJOR_TYPE 열거형의 멤버를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetUserData 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetUserData(
pData As Byte,
pSize As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pData
데이터를 보관 유지하는 바이트 배열에의 참조.
pSize
배열의 사이즈 (바이트 단위). 메소드로부터 돌아온 시점에서는, 필요한 사이즈가 설정되어 있다. 「주의」를 참조할것.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

이 메소드는, 유저 데이터에 필요한 배열 사이즈를 pSize 의 값으로 설정한다. ReDim 문을 사용해 배열의 사이즈를 변경해, 메소드를 한번 더 호출한다. 배열의 최초의 요소를 파라미터의 값으로서 사용해,pData 파라미터를 참조로서 건네준다.

Dim UserData(0) As Byte
Dim Size As Long

'필요한 사이즈를 조사한다
ReDim UserData(1)
objTimelineObject.GetUserData UserData(0), Size

'배열의 사이즈를 변경해, 모든 데이터를 취득한다
If Size <> 0 Then
ReDim UserData(Size)
objTimelineObject.GetUserData UserData(0), Size
End If

GetUserID 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 어플리케이션 정의의 식별자를 취득한다.

구문

object. GetUserID(
pVal As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pVal
어플리케이션 정의의 식별자를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetUserName 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 어플리케이션 정의의 이름을 취득한다.

구문

object. GetUserName() As String

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.

반환값

어플리케이션 정의의 이름을 나타내는 캐릭터 라인을 돌려준다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_OUTOFMEMORY 메모리 부족.

Remove 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

이 오브젝트를 (서브 오브젝트는 포함하지만, 아이는 포함하지 않는다), 다른 장소에 재삽입할 수 있도록(듯이), 타임 라인으로부터 삭제한다.

구문

object. Remove()

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

이 메소드는, 어플리케이션이 즉석에서 그 오브젝트를 타임 라인에 삽입하는 경우에게만 호출한다. 이 메소드의 호출에 이어 오브젝트를 재삽입하지 않는 것은, 무효인 조작이다. 오브젝트를 영속적으로 삭제하려면 ,RemoveAll 를 사용한다.

RemoveAll 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

이 오브젝트를, 서브 오브젝트와 아이를 포함해, 타임 라인으로부터 영속적으로 삭제한다.

구문

object. RemoveAll()

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

오브젝트를 타임 라인의 다른 장소에 재삽입하는 목적으로 삭제하려면 ,Remove 를 사용한다.

SetDirtyRange 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetDirtyRange(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetDirtyRange2 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetDirtyRange2(
Start As Double,
Stop As Double
)

SetLocked 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 편집 상태를 락 또는 락 해제로 설정한다. 락 상태는 오브젝트를 편집해서는 안 되는 것을 나타내, 락 해제 상태는 오브젝트를 편집할 수 있는 것을 나타낸다. 타임 라인측에서는, 락을 강제하지 않는다. 락 상태의 설정은, 어플리케이션측의 편리성을 위해서(때문에) 마셔 존재한다.

구문

object. SetLocked(
newVal As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
newVal
오브젝트의 편집 상태를 지정하는 값. 제로의 경우는, 오브젝트는 락 해제되어, 편집할 수 있게 된다. 제로 이외의 경우는, 오브젝트는 락 되어, 편집할 수 없게 된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SetMuted 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 뮤트 상태를 설정한다. 뮤트 된 오브젝트는 렌더링 되지 않지만, 타임 라인내에는 존재한 채로된다.

구문

object. SetMuted(
newVal As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
newVal
뮤트 상태를 지정하는 값. 제로의 경우는, 오브젝트는 뮤트 되지 않는다. 제로 이외의 경우는, 오브젝트와 그 모든 아이는 뮤트 된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

오브젝트를 뮤트 하면, 그 오브젝트가 가지는 아이도 모두 뮤트 된다. 예를 들어, 어느 트럭을 뮤트 하면, 그 트럭내의 트란지션, 소스, 및 이펙트도 모두 뮤트 된다. 오브젝트의 뮤트가 해제되면(자), 그 아이는 각각의 전 상태 (뮤트 또는 뮤트 해제)에 돌아온다.

SetPropertySetter 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetPropertySetter(
newVal As PropertySetter
)

SetStartStop 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetStartStop(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetStartStop2 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트의 부모를 기준으로서 오브젝트의 시작 타임과 종료 타임을 설정한다.

구문

object. SetStartStop2(
Start As Double,
Stop As Double
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
Start
새로운 시작 타임 (초단위). 기존의 시작 타임을 유지하는 경우는 -1.
Stop
새로운 종료 타임 (초단위). 기존의 종료 타임을 유지하는 경우는 -1.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 무효인 인수.
E_NOTIMPL | 이행되어 있지 않다.

주의

트럭, 합성, 및 그룹은, 이 메소드를 이행 하지 않는다. 이러한 오브젝트에서는, 시작 타임은 항상 제로이며, 종료 타임은 포함되는 오브젝트의 최대의 종료 타임이다.

같은 트럭내의 소스 오브젝트로 서로 겹치는 시간을 설정해서는 안 된다. 그러한 설정을 실시하면, 미정도리의 동작이 발생하는 경우가 있다.

소스 오브젝트의 경우, 시작 타임과 종료 타임은, 미디어 시작 타임 및 미디어 종료 타임부터 독립하고 있다. 이러한 한편의 조를 변경해도, 이제 한편에 영향은 없다. 미디어의 시작 타임과 종료 타임을 설정하려면 ,AMTimelineSrc.SetMediaTimes2 메소드를 사용한다. 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

SetSubObject 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetSubObject(
newVal As Unknown
)

SetSubObjectGUID 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetSubObjectGUID(
newVal As GUID
)

SetSubObjectGUIDB 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

이 오브젝트에 관련지을 수 있고 있는 서브 오브젝트의 GUID 를 지정한다.

구문

object. SetSubObjectGUIDB(
newVal As String
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
newVal
서브 오브젝트의 GUID 를 나타내는 캐릭터 라인.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

렌더링 엔진은, 필요에 따라서 서브 오브젝트의 인스턴스를 생성 한다.

SetTimelineType 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

Visual Basic 에서는 지원되어 있지 않다. 새로운 타임 라인 오브젝트를 생성 하려면 ,AMTimeline.CreateEmptyNode 메소드를 사용한다. 오브젝트를 생성 한 다음에는, 그 타입은 변경할 수 없다.

구문

object. SetTimelineType(
newVal As TIMELINE_MAJOR_TYPE
)

SetUserData 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

어플리케이션 정의의 지속적 데이터를 설정한다.

구문

object. SetUserData(
pData As Byte,
Size As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
pData
데이터를 보관 유지하는 바이트 배열에의 참조.
Size
배열의 사이즈 (바이트 단위).

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_OUTOFMEMORY 메모리 부족.

주의

배열의 최초의 요소를 파라미터의 값으로서 사용해,pData 파라미터를 참조로서 건네준다.

Dim UserData(100) As Byte
'배열을 초기화한다 (생략)
objTimelineObject.SetUserData UserData(0), 100

SetUserID 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트에 대한 어플리케이션 정의의 식별자를 설정한다.

구문

object. SetUserID(
newVal As Long
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
newVal
식별자를 지정하는 값. 이 식별자는, 어플리케이션에 의해서만 사용되어 어떠한 값에서도 상관없다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SetUserName 메소드 (AMTimelineObj 오브젝트)

AMTimelineObj 오브젝트

오브젝트에 대한 어플리케이션 정의의 이름을 설정한다.

구문

object. SetUserName(
newVal As String
)

파라미터

object
결과가 AMTimelineObj 오브젝트가 되는 오브젝트식.
newVal
이름을 나타내는 캐릭터 라인. 256 문자를 넘는 캐릭터 라인은, 절약할 수 있는 일이 있다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.


AMTimelineSrc 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)의 소스의 조작과 프로퍼티의 설정을 실시하는 메소드를 제공한다. AMTimelineSrc 오브젝트는, 미디어 소스의 1 개의 스트림으로부터 취득된 클립을 나타내고 있다.

미디어 시작 타임과 미디어 종료 타임을 설정하는 것으로써, 원시 파일내의 데이터의 일부분을 사용할 수 있다. 이 2 개의 값은, 원의 미디어 소스를 기준으로서AMTimelineSrc 오브젝트의 시작과 마지막을 지정한다. 미디어 타임은,타임 라인상에서의 오브젝트의 시작 타임 및 종료 타임과는 다른 경우가 있어, 속도를 바꾼 재생 (오디오 소스에서는 피치 쉬프트)이 가능하다.

메소드

FixMediaTimes | Visual Basic 에서는 지원되어 있지 않다.
FixMediaTimes2 | 지정된 타임값을, 출력 frame rate에 의해 정의되는 가장 가까운 프레임 경계에 말다.
GetDefaultFPS | 소스 오브젝트의 디폴트의 frame rate를 취득한다.
GetMediaLength | Visual Basic 에서는 지원되어 있지 않다.
GetMediaLength2 | 이 오브젝트의 미디어장을 취득한다.
GetMediaName | 이 오브젝트가 나타내는 원시 파일의 이름을 취득한다.
GetMediaTimes | Visual Basic 에서는 지원되어 있지 않다.
GetMediaTimes2 | 미디어의 시작 타임과 종료 타임을 취득한다.
GetStreamNumber | 소스 오브젝트의 현재의 스트림 번호를 취득한다.
GetStretchMode | 신축 모드를 취득한다.
IsNormalRate | 클립이 생성시의 재생 레이트로 재생될지 어떨지를 나타낸다.
ModifyStopTime | Visual Basic 에서는 지원되어 있지 않다.
ModifyStopTime2 | 종료 타임을 설정한다.
SetDefaultFPS | 소스 오브젝트의 디폴트의 frame rate를 설정한다.
SetMediaLength | Visual Basic 에서는 지원되어 있지 않다.
SetMediaLength2 | 원시 파일의 시간폭을 지정한다.
SetMediaName | 원시 파일의 이름을 지정한다.
SetMediaTimes | Visual Basic 에서는 지원되어 있지 않다.
SetMediaTimes2 | 미디어의 종료 타임과 시작 타임을 설정한다.
SetStretchMode | 신축 모드를 설정한다.
SetStreamNumber | 원시 파일로부터 읽어내는 스트림을 지정한다.
SpliceWithNext | AMTimelineSrc 오브젝트를 다른 AMTimelineSrc 오브젝트에 결합한다.

FixMediaTimes 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. FixMediaTimes(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

FixMediaTimes2 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

지정된 타임값을, 출력 frame rate에 의해 정의되는 가장 가까운 프레임 경계에 말다. 보통, 어플리케이션으로 이 메소드를 호출할 필요는 없다.

구문

object. FixMediaTimes2(
pStart As Double,
pStop As Double
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
pStart
시작 타임 (초단위). 호출이 성공했을 경우, 이 변수에는 말 수 있었던 시간이 설정된다.
pStop
종료 타임 (초단위). 호출이 성공했을 경우, 이 변수에는 말 수 있었던 시간이 설정된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

이 메소드는 AMTimelineObj.FixTimes2 메소드와 닮아 있지만, 이 메소드에서는 미디어 타임과 타임 라인 타임의 원의 비율이 유지된다. 가장 가까운 프레임 경계에 시간을 마는 것으로, 이 비가 변화하는 일이 있다.

GetDefaultFPS 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

소스 오브젝트의 디폴트의 frame rate을 취득한다. 렌더링 엔진이 원의 소스로부터 frame rate를 특정할 수 없는 경우, 이 값이 사용된다.

구문

object. GetDefaultFPS(
pFPS As Double
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
pFPS
디폴트의 frame rate (매초의 프레임수)를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

파일 포맷으로 frame rate이 지정되고 있는 경우는, 디폴트의 frame rate는 필요없다. 이것은, 오디오 및 비디오의 포맷의 경우에 들어맞는다.

소스가 비트 맵 또는 JPEG 이미지의 경우, 렌더링 엔진은 그것을디바이스에 의존하지 않는 비트 맵 (DIB) 순서의 최초의 이미지로서 사용해, frame rate은 디폴트의 frame rate를 사용한다. DIB 순서는 아니고 스태틱 이미지를 렌더링 하려면 , 디폴트의 frame rate를 0 으로 설정한다.

소스가 GIF 의 경우는, frame rate를 설정해서는 안 된다. 애니메이션 GIF 의 경우는, GIF 파일이 각 이미지간의 지연을 지정한다.

GetMediaLength 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetMediaLength(
pLength As <Unsupported variant type>
)

GetMediaLength2 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

이 오브젝트의 미디어장을 취득한다.

구문

object. GetMediaLength2(
pLength As Double
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
pLength
미디어장 (초단위)을 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_NOTDETERMINED 이 오브젝트에 미디어 시간은 설정되어 있지 않다.

참조

SetMediaLength2

GetMediaName 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

이 오브젝트가 나타내는 원시 파일의 이름을 취득한다.

구문

object. GetMediaName() As String

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.

반환값

원시 파일의 이름을 돌려준다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_OUTOFMEMORY 메모리 부족.

GetMediaTimes 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetMediaTimes(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

GetMediaTimes2 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

미디어의 시작 타임과 종료 타임을 취득한다.

구문

object. GetMediaTimes2(
pStart As Double,
pStop As Double
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
pStart
미디어의 시작 타임 (초단위)을 받는 변수.
pStop
미디어의 종료 타임 (초단위)을 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

미디어의 시간은, 원의 미디어 파일을 기준으로 한다. 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

GetStreamNumber 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

소스 오브젝트의 현재의 스트림 번호를 취득한다.

구문

object. GetStreamNumber(
pVal As Long
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
pVal
스트림 번호를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetStretchMode 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

신축 모드를 취득한다. 신축 모드는, 비디오 소스의 사이즈가 출력 넓이와 일치하지 않는 경우의, 비디오 소스의 렌더링 방법을 지정한다.

구문

object. GetStretchMode(
pnStretchMode As Long
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
pnStretchMode
다음의 몇개의 값을 받는 변수.
  • RESIZEF_STRETCH
  • RESIZEF_CROP
  • RESIZEF_PRESERVEASPECTRATIO
  • RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

IsNormalRate 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

클립이 생성시의 재생 레이트로 재생될지 어떨지를 나타낸다.

구문

object. IsNormalRate(
pVal As Long
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
pVal
클립의 렌더링 방법을 나타내는 값을 받는 변수. 제로 이외의 경우는, 클립은 보통의 레이트로 재생된다. 제로의 경우는, 보통과는 다른 속도로 재생된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

클립의 재생 레이트는, 타임 라인 타임을 기준으로 하는 미디어의 시작 타임과 종료 타임에 의해 정해진다.

재생 레이트 = (미디어 종료 타임 - 미디어 시작 타임) / (타임 라인 종료 타임 - 타임 라인 시작 타임)

이 비가 1 에 동일한 경우, 클립은 생성시의 속도로 재생된다. 그렇지 않은 경우는, 보통과는 다른 속도로 재생된다. 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

ModifyStopTime 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. ModifyStopTime(
Stop As <Unsupported variant type>
)

ModifyStopTime2 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

종료 타임을 설정한다.

구문

object. ModifyStopTime2(
Stop As Double
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
Stop
새로운 종료 타임 (초단위).

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 지정된 시간이 무효이다.

SetDefaultFPS 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

소스 오브젝트의 디폴트 frame rate를 설정한다.

구문

object. SetDefaultFPS(
FPS As Double
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
FPS
디폴트의 frame rate (매초의 프레임수).

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 지정된 frame rate가, 제로보다 작다.

주의

렌더링 엔진이 원의 원시 파일로부터 frame rate를 특정할 수 없는 경우, 이 값이 사용된다.

이 메소드는, 정의 끝난 frame rate를 가지지 않는 원시 파일 에 대해서만 호출한다. 비트 맵 및 JPEG 파일의 경우, 디폴트 frame rate는 제로이며, 그것에 의해 소스는 스티르이메이지로서 렌더링 된다. 이미지를 DIB 순서의 최초의 프레임으로서 사용하려면 , frame rate를 제로보다 큰 값으로 설정한다.

SetMediaLength 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetMediaLength(
Length As <Unsupported variant type>
)

SetMediaLength2 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

원시 파일의 시간폭을 지정한다. 이 메소드는 SetMediaLength 메소드와 같은 기능이지만, 파라미터로서 REFTIME 의 값을 취한다.

구문

object. SetMediaLength2(
Length As Double
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
Length
미디어장 (초단위).

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

미디어 종료 타임을 설정하기 전에 미디어장을 설정하는 것으로써, 잠재적인 렌더링 에러를 회피할 수 있다. 미디어 종료 타임을 설정 하면, DES 는 그것을 미디어장과 교제하게 해 체크한다.

이 메소드는 Length 파라미터를 검증하지 않지만, 그 값은 원시 파일의 실제의 시간폭과 동일하지 않으면 안 된다. 원시 파일의 시간폭은,IMediaDet.StreamLength 프로퍼티로부터 취득한다.

SetMediaName 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

원시 파일의 이름을 지정한다.

구문

object. SetMediaName(
newVal As String
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
newVal
미디어 파일의 이름을 지정하는 캐릭터 라인.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SetMediaTimes 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetMediaTimes(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetMediaTimes2 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

미디어의 종료 타임과 시작 타임을 설정한다.

구문

object. SetMediaTimes2(
Start As Double,
Stop As Double
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
Start
미디어 시작 타임 (초단위).
Stop
미디어 종료 타임 (초단위).

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

미디어 타임은, 원의 미디어 파일을 기준으로 하는 미디어 종료 타임과 미디어 시작 타임이다. 비디오 소스 또는 오디오 소스를 타임 라인에 추가 하면나무는, 반드시 미디어 타임을 설정한다. 설정하지 않으면 렌더링으로 문제가 발생하는 경우가 있다. 종료 타임은, 시작 타임보다 큰 값이 아니면 안된다.

비디오 소스로부터 스티르후레임을 사용하려면 , 시작 타임부터 소수점 이하의 값 (예를 들어 100 나노초)만 큰 종료 타임을 설정한다. 시작 타임과 종료 타임을 같은 값으로 설정 하면, 렌더링 에러가 발생한다.

타임 라인의 시간폭이 미디어의 시간폭과 일치하지 않는 경우는, 거기에 맞추어 소스가 신축한다. 이것에 의해, 클립의 재생은, 생성시와는 다른 레이트로 행해지게 된다 (오디오 소스에서는, 피치 쉬프트가 발생한다). 상세한 것에 대하여는, 「DirectShow 편집 서비스에 있어서의 시간」을 참조할것.

원시 파일의 시간폭은,SetMediaLength 메소드를 호출하는 것으로 지정할 수 있다. 미디어 종료 타임이 시간폭을 넘는 경우, DES 는 종료 타임을 앞당긴다.

SetStreamNumber 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

원시 파일로부터 읽어내는 스트림을 지정한다.

구문

object. SetStreamNumber(
Val As Long
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
Val
스트림 번호. 친그룹의, 일치하는 미디어 타입의 스트림세트로부터 지정한다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG Val 파라미터의 값이 제로보다 작다.

주의

Val 파라미터는, 친그룹의 미디어 타입에 일치하는 스트림세트에 있어서의 스트림 번호를 지정한다. 이것은, 원시 파일의 스트림세트 전체에 있어서의 번호는 아니다. 예를 들어, 2 개의 비디오 스트림과 2 개의 오디오 스트림이 파일에 있는 것과 내버려AMTimelineSrc 오브젝트가 비디오 그룹안에 있는 경우는,Val 에 0 을 설정 하면, 최초의 비디오 스트림이 선택된다. 호출원이 유효한 스트림 번호를 지정해야 한다.

스트림 번호의 디폴트는 제로이다.

SetStretchMode 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

신축 모드를 설정한다. 신축 모드는, 비디오 소스의 사이즈가 출력 넓이와 일치하지 않는 경우의, 비디오 소스의 렌더링 방법을 지정한다.

구문

object. SetStretchMode(
nStretchMode As Long
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
nStretchMode
현재의 신축 모드를 나타내는 플래그. 다음의 몇개의 값이 아니면 안된다.
  • RESIZEF_STRETCH
  • RESIZEF_CROP
  • RESIZEF_PRESERVEASPECTRATIO
  • RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SpliceWithNext 메소드 (AMTimelineSrc 오브젝트)

AMTimelineSrc 오브젝트

AMTimelineSrc 오브젝트를 다른 AMTimelineSrc 오브젝트에 결합한다.

구문

object. SpliceWithNext(
pNext As AMTimelineObj
)

파라미터

object
결과가 AMTimelineSrc 오브젝트가 되는 오브젝트식.
pNext
현재의 소스에 결합하는 AMTimelineObj 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 무효인 인수.
E_NOINTERFACE | pNext 파라미터에 의해 지정된 오브젝트가 소스 오브젝트는 아니다.

주의

현재의 이행에서는, 이 메소드는 pNext 위에의 이펙트는 파기한다.

이 메소드를 올바르게 동작시키려면 ,pNext 는 현재의 소스 오브젝트의 프레임에 일치하고 있지 않으면 안 된다.

  • 같은 원시 파일을 공유하고 있지 않으면 안 된다.
  • 미디어 시작 타임이, 현재의 소스의 미디어 종료 타임과 동일하지 않으면 안 된다.
  • 재생 레이트가 동일하지 않으면 안 된다. 재생 레이트는, 미디어 시간폭을 타임 라인 시간폭으로 나눈 값이다.


AMTimelineTrack 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)의트럭 을 조작하는 메소드를 제공한다.

트럭에는, 최종 출력으로 렌더링 되는 소스의 리스트가 들어간다. 같은 트럭내의 소스는, 오버랩 할 수 없다. 비디오 트럭은, 이펙트와 트란지션의 양쪽 모두를 가질 수가 있다. 렌더링 엔진은, 트란지션을 적용하기 전에 이펙트를 적용한다. 오디오 트럭은, 이펙트를 가질 수 있지만, 트란지션을 가질 수 없다.

상세한 것에 대하여는, 「타임 라인 모델」을 참조할것.

메소드

AreYouBlank | 트럭이 공백 (소스 오브젝트가 들어가 있지 않다) 화도인지를 조사한다.
GetNextSrc | Visual Basic 에서는 지원되어 있지 않다.
GetNextSrc2 | 트럭으로, 지정된 시간 이후에 출현하는 다음의 소스를 검색한다.
GetNextSrcEx | 지정된 소스에 계속되는 다음의 소스를 취득한다.
GetSourcesCount | 트럭내의 소스의 개수를 취득한다.
GetSrcAtTime | Visual Basic 에서는 지원되어 있지 않다.
GetSrcAtTime2 | 지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 소스 오브젝트를 취득한다.
InsertSpace | Visual Basic 에서는 지원되어 있지 않다.
InsertSpace2 | 지정된 시간에 존재하는 모든 오브젝트를 분할해, 그 사이에 스페이스를 삽입한다.
MoveEverythingBy | Visual Basic 에서는 지원되어 있지 않다.
MoveEverythingBy2 | 트럭의 오브젝트중 지정된 시간에 시작 하는 것을 모두, 타임 라인에 따라 지정된 거리만 이동한다.
SrcAdd | 트럭에 소스를 추가한다.
ZeroBetween | Visual Basic 에서는 지원되어 있지 않다.
ZeroBetween2 | 트럭으로부터, 지정된 시간의 사이에 있는 것을 모두 삭제한다.

AreYouBlank 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

트럭이 공백 (소스 오브젝트가 들어가 있지 않다) 화도인지를 조사한다.

구문

object. AreYouBlank(
pVal As Long
)

파라미터

object
결과가 AMTimelineTrack 오브젝트가 되는 오브젝트식.
pVal
트럭이 공백인가 어떤가를 지정하는 값을 받는 변수. 제로 이외의 경우는, 오브젝트는 공백이며, 소스 오브젝트는 들어가 있지 않다. 제로의 경우는, 트럭은 공백은 아니다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetNextSrc 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetNextSrc(
ppSrc AMTimelineObj,
pInOut As <Unsupported variant type>
)

GetNextSrc2 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

트럭으로, 지정된 시간 이후에 출현하는 다음의 소스를 검색한다.

구문

object. GetNextSrc2(
ppSrc As AMTimelineObj,
pInOut As Double
)

파라미터

object
결과가 AMTimelineTrack 오브젝트가 되는 오브젝트식.
ppSrc
소스 오브젝트를 받는 AMTimelineObj 오브젝트.
pInOut
검색을 시작 할 시간 (초단위). 소스가 취득되었을 경우, 이 변수에는 그 소스의 종료 타임이 설정된다. 소스가 취득되지 않았던 경우, 이 값은 무효가 되므로, 어플리케이션으로 사용해서는 안 된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

pInOut 로 지정된 값이 소스의 시작 타임과 종료 타임의 사이에 있는 경우, 메소드는 그 소스를 취득한다.

GetNextSrcEx 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

지정된 소스에 계속되는 다음의 소스를 취득한다.

구문

object. GetNextSrcEx(
pLast As AMTimelineObj,
ppNext As AMTimelineObj
)

파라미터

object
결과가 AMTimelineTrack 오브젝트가 되는 오브젝트식.
pLast
전의 AMTimelineObj 오브젝트. 트럭내의 최초의 소스를 취득하는 경우는 Nothing.
ppNext
다음의 소스를 받는 AMTimelineObj 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetSourcesCount 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

트럭내의 소스의 개수를 취득한다.

구문

object. GetSourcesCount(
pVal As Long
)

파라미터

object
결과가 AMTimelineTrack 오브젝트가 되는 오브젝트식.
pVal
트럭내의 소스의 개수를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

GetSrcAtTime 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetSrcAtTime(
ppSrc As AMTimelineObj,
Time As <Unsupported variant type>,
SearchDirection As Long
)

GetSrcAtTime2 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 소스 오브젝트를 취득한다.

구문

object. GetSrcAtTime2(
ppSrc As AMTimelineObj,
Time As Double,
SearchDirection As Long
)

파라미터

object
결과가 AMTimelineTrack 오브젝트가 되는 오브젝트식.
ppSrc
소스를 받는 AMTimelineObj 오브젝트.
Time
검색을 시작 할 시간 (초단위).
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 열거형의 멤버. 검색의 경계 조건을 지정한다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 무효인 인수.

InsertSpace 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. InsertSpace(
rtStart As <Unsupported variant type>,
rtEnd As <Unsupported variant type>
)

InsertSpace2 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

지정된 시간에 존재하는 모든 오브젝트를 분할해, 그 사이에 스페이스를 삽입한다.

구문

object. InsertSpace2(
rtStart As Double,
rtEnd As Double
)

파라미터

object
결과가 AMTimelineTrack 오브젝트가 되는 오브젝트식.
rtStart
분할을 실시하는 시간, 또 삽입되는 스페이스의 시점 (초단위).
rtEnd
삽입되는 스페이스의 종점 (초단위).

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 무효인 인수.

MoveEverythingBy 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. MoveEverythingBy(
Start As <Unsupported variant type>,
MoveBy As <Unsupported variant type>
)

MoveEverythingBy2 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

트럭의 오브젝트중 지정된 시간에 시작 하는 것을 모두, 타임 라인에 따라 지정된 거리만 이동한다.

구문

object. MoveEverythingBy2(
Start As Double,
MoveBy As Double
)

파라미터

object
결과가 AMTimelineTrack 오브젝트가 되는 오브젝트식.
Start
이동의 시작 타임 (초단위). 이 시간 이후에 시작 하는 오브젝트만이 이동된다.
MoveBy
타임 라인상에서 오브젝트를 이동하는 시간의 양 (초단위).

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SrcAdd 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

트럭에 소스를 추가한다.

구문

object. SrcAdd(
pSrc As AMTimelineObj
)

파라미터

object
결과가 AMTimelineTrack 오브젝트가 되는 오브젝트식.
pSrc
추가하는 AMTimelineObj 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_NOINTERFACE pSrc 로 지정되고 있는 오브젝트가, 소스 오브젝트는 아니다.

주의

이 메소드를 호출하기 전에, 소스의 시작 타임과 종료 타임을 설정할 필요가 있다 (AMTimelineObj.SetStartStop 메소드를 호출한다).

현재 DES 는, 비디오 압축 매니저 (VCM) CODEC로 압축된 소스는, 동시에 75 개까지 밖에 렌더링 할 수 없다. 또, 그러한 소스가 프로젝트 전체로 75 개를 넘는 경우는, 동적인 재접속을 사용하지 않으면, DES 는 프로젝트를 프리뷰 할 수 없다. 상세한 것에 대하여는, 「RenderEngine.SetDynamicReconnectLevel 」를 참조할것.

ZeroBetween 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. ZeroBetween(
rtStart As <Unsupported variant type>,
rtEnd As <Unsupported variant type>
)

ZeroBetween2 메소드 (AMTimelineTrack 오브젝트)

AMTimelineTrack 오브젝트

트럭으로부터, 지정된 시간의 사이에 있는 것을 모두 삭제한다. 이 메소드는, 지정된 시간 범위인가는 모든 오브젝트를 분할해, 그 범위내에 있는 부분을 삭제한다.

구문

object. ZeroBetween2(
rtStart As Double,
rtEnd As Double
)

파라미터

object
결과가 AMTimelineTrack 오브젝트가 되는 오브젝트식.
rtStart
클리어 하는 범위의 시점 (초단위).
rtEnd
클리어 하는 범위의 종점 (초단위).

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.


AMTimelineTrans 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)로 트란지션을 조작하기 위한 메소드를 제공한다.

트란지션은, 1 개의 계층과 그것보다 낮은 우선 순위의 모든 계층의 렌더링 된 합성과의 사이에 진행한다. AMTimelineTrans 오브젝트는, 2 개의 입력을 가지는 Microsoft® DirectX® 변환 오브젝트에 대한 래퍼이다. DirectX Transform 오브젝트를 지정하려면 ,AMTimelineObj.SetSubObjectGUID 메소드를 호출한다.

트란지션을 가질 수 있는 타임 라인 오브젝트는,IAMTimelineTransable 오브젝트를 지원 한다.

메소드

GetCutPoint | Visual Basic 에서는 지원되어 있지 않다.
GetCutPoint2 | 컷 포인트를 취득한다.
GetCutsOnly | 트란지션이 컷으로서 렌더링 될지 어떨지를 조사한다.
GetSwapInputs | 트란지션의 입력이 스왑 될지 어떨지를 조사한다.
SetCutPoint | Visual Basic 에서는 지원되어 있지 않다.
SetCutPoint2 | 컷 포인트를 설정한다.
SetCutsOnly | 트란지션이 컷으로서 렌더링 될지 어떨지를 지정한다.
SetSwapInputs | 트란지션의 입력이 스왑 될지 어떨지를 지정한다.

GetCutPoint 메소드 (AMTimelineTrans 오브젝트)

AMTimelineTrans 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetCutPoint(
pTLTime As <Unsupported variant type>
)

GetCutPoint2 메소드 (AMTimelineTrans 오브젝트)

AMTimelineTrans 오브젝트

컷 포인트를 취득한다. 트란지션을 컷 (직접 바꾸고)으로서 렌더링 하는 경우, 컷 포인트는 트란지션이 한편의 소스로부터 다음의 소스에 바뀌는 시간이다. 디폴트에서는, 이 값은 트란지션의 중간점이다. 예를 들어, 2 초간의 트란지션에서는, 디폴트의 컷 포인트는 트란지션의 1 초의 위치이다.

구문

object. GetCutPoint2(
pTLTime As Double
)

파라미터

object
결과가 AMTimelineTrans 오브젝트가 되는 오브젝트식.
pTLTime
트란지션의 시작 타임을 기준으로 하는 컷 포인트의 값을 받는 변수. 단위는 초.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

참조

SetCutPoint2 ,GetCutsOnly ,AMTimeline.TransitionsEnabled

GetCutsOnly 메소드 (AMTimelineTrans 오브젝트)

AMTimelineTrans 오브젝트

트란지션이 컷으로서 렌더링 될지 어떨지를 조사한다. 컷으로서 렌더링 되는 경우, 트란지션은 컷 포인트로 즉석에서 행해진다.

구문

object. GetCutsOnly(
pVal As Long
)

파라미터

object
결과가 AMTimelineTrans 오브젝트가 되는 오브젝트식.
pVal
트란지션이 컷으로서 렌더링 될지 어떨지를 나타내는 값을 받는 변수. 제로 이외의 경우, 트란지션은 즉시 컷이다. 제로의 경우, 트란지션은 보통의 시간폭으로 행해진다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

참조

SetCutsOnly ,GetCutPoint ,AMTimeline.TransitionsEnabled

GetSwapInputs 메소드 (AMTimelineTrans 오브젝트)

AMTimelineTrans 오브젝트

트란지션의 입력이 스왑 될지 어떨지를 조사한다.

디폴트에서는, 트란지션은 우선 순위의 낮은 계층의 합성으로부터, 트란지션이 존재하는 계층으로 향해 행해진다. 이 진행 방향을 반대로 할 수가 있어 그 경우, 트란지션은 트란지션이 존재하는 계층으로부터, 우선 순위의 낮은 계층의 합성으로 향해 행해진다.

구문

object. GetSwapInputs(
pVal As Long
)

파라미터

object
결과가 AMTimelineTrans 오브젝트가 되는 오브젝트식.
pVal
입력이 스왑 될지 어떨지를 나타내는 값을 받는 변수. 이 값이 제로의 경우, 트란지션은 우선 순위의 낮은 모든 계층의 합성으로부터, 그 트란지션이 존재하는 계층으로 향해 행해진다. 이 값이 제로 이외의 경우, 트란지션은 역의 방향으로 행해진다. 디폴트값은 제로.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SetCutPoint 메소드 (AMTimelineTrans 오브젝트)

AMTimelineTrans 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetCutPoint(
TLTime As <Unsupported variant type>
)

SetCutPoint2 메소드 (AMTimelineTrans 오브젝트)

AMTimelineTrans 오브젝트

컷 포인트를 설정한다. 트란지션을 컷 (직접 바꾸고)으로서 렌더링 하는 경우, 컷 포인트는 트란지션이 한편의 소스로부터 다음의 소스에 바뀌는 시간이다. 디폴트에서는, 컷 포인트는 트란지션의 중간점이다. 예를 들어, 2 초간의 트란지션에서는, 디폴트의 컷 포인트는 트란지션의 1 초의 위치이다.

구문

object. SetCutPoint2(
TLTime As Double
)

파라미터

object
결과가 AMTimelineTrans 오브젝트가 되는 오브젝트식.
TLTime
트란지션의 시점을 기준으로 하는 컷 포인트 (초단위).

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SetCutsOnly 메소드 (AMTimelineTrans 오브젝트)

AMTimelineTrans 오브젝트

트란지션이 컷으로서 렌더링 될지 어떨지를 지정한다. 컷으로서 렌더링 되는 경우, 트란지션은 컷 포인트로 즉석에서 행해진다. 트란지션의 렌더링에 시간이 걸리는 경우, 컷으로서 렌더링 해 프리뷰의 시간을 단축할 수 있다.

구문

object. SetCutsOnly(
Val As Long
)

파라미터

object
결과가 AMTimelineTrans 오브젝트가 되는 오브젝트식.
Val
트란지션을 컷으로서 렌더링 할지 어떨지를 나타내는 값. 제로를 지정 하면, 트란지션은 즉시 컷으로서 렌더링 된다. 제로 이외를 지정 하면, 트란지션은 보통의 시간폭으로 렌더링 된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

SetSwapInputs 메소드 (AMTimelineTrans 오브젝트)

AMTimelineTrans 오브젝트

트란지션의 입력이 스왑 될지 어떨지를 지정한다.

디폴트에서는, 트란지션은 우선 순위의 낮은 계층의 합성으로부터, 트란지션이 존재하는 계층으로 향해 행해진다. 이 진행 방향을 반대로 할 수가 있어 그 경우, 트란지션은 트란지션이 존재하는 계층으로부터, 우선 순위의 낮은 계층의 합성으로 향해 행해진다.

구문

object. SetSwapInputs(
Val As Long
)

파라미터

object
결과가 AMTimelineTrans 오브젝트가 되는 오브젝트식.
Val
트란지션의 입력이 스왑 될지 어떨지를 지정하는 값. 제로를 지정 하면, 트란지션은 우선 순위의 낮은 모든 계층의 합성으로부터, 그 트란지션이 존재하는 계층으로 향해 행해진다. 제로 이외를 지정 하면, 트란지션은 역의 방향으로 행해진다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

이 메소드는, 비주얼 이펙트의 방향은 변경하지 않는다. 예를 들어, 왼쪽에서 오른쪽에의 와이프는, 왼쪽에서 오른쪽에 행해진다.


IAMTimelineEffectable 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)의 타임 라인 오브젝트에 이펙트를 추가하기 위한 메소드, 및 오브젝트의 이펙트를 조작하는 메소드를 제공한다. 소스,트럭,합성 등, 적용하는 이펙트를 가질 수 있는 타임 라인 오브젝트에 적용된다.

메소드

EffectGetCount | 이 오브젝트에 적용되는 이펙트의 수를 취득한다.
EffectInsBefore | 지정된 우선 순위의 오브젝트에 이펙트를 삽입한다.
EffectSwapPriorities | 2 개의 이펙트의 우선 순위 레벨을 바꿔 넣는다.
GetEffect | 지정된 우선 순위 레벨의 이펙트를 취득한다.

EffectGetCount 메소드 (IAMTimelineEffectable 오브젝트)

IAMTimelineEffectable 오브젝트

이 오브젝트에 적용되는 이펙트의 수를 취득한다.

구문

object. EffectGetCount(
pCount As Long
)

파라미터

object
결과가 IAMTimelineEffectable 오브젝트가 되는 오브젝트식.
pCount
이펙트의 수를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

IAMTimelineEffectable::EffectInsBefore 메소드 (IAMTimelineEffectable 오브젝트)

IAMTimelineEffectable 인터페이스

지정된 우선 순위의 오브젝트에 이펙트를 삽입한다.

구문

object. EffectInsBefore(
pFX As AMTimelineObj,
Priority As Long
)

파라미터

object
결과가 IAMTimelineEffectable 오브젝트가 되는 오브젝트식.
pFX
이펙트를 지정하는 AMTimelineObj 오브젝트.
Priority
이펙트를 삽입하는 우선 순위 레벨. 이펙트를 우선 순위 리스트의 마지막에 삽입하는 경우는, 값으로서 -1 를 사용한다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_NOTIMPL pFX 로 지정되고 있는 오브젝트가 이펙트는 아니다.

주의

이펙트의 시작 타임과 종료 타임은, 필요에 따라서, 오브젝트의 시간 범위의 경계내에 넣을 수 있다.

지정된 우선 순위 레벨의 이펙트가 이미 존재하는 경우, 우선 순위 리스트의 그 위치 이하의 이펙트가 모두 1 레벨씩 뒤로 돌릴 수 있어 새로운 이펙트의 장소가 확보된다.

IAMTimelineEffectable::EffectSwapPriorities 메소드 (IAMTimelineEffectable 오브젝트)

IAMTimelineEffectable 인터페이스

2 개의 이펙트의 우선 순위 레벨을 바꿔 넣는다.

이 메소드는, 지정된 2 개의 우선 순위 레벨을 가지는 각각의 이펙트의 우선 순위를 바꿔 넣는다. 이 메소드로부터 돌아온 시점에서는, 최초로 지정된 우선 순위에 있던 이펙트의 우선 순위는, 2 번째로 지정된 우선 순위 레벨이 되어, 2 번째로 지정된 우선 순위에 있던 이펙트의 우선 순위는, 최초로 지정된 우선 순위 레벨이 되어 있다.

구문

object. EffectSwapPriorities(
PriorityA As Long,
PriorityB As Long
)

파라미터

object
결과가 IAMTimelineEffectable 오브젝트가 되는 오브젝트식.
PriorityA
이펙트를 바꿔 넣는 최초의 우선 순위 레벨.
PriorityB
이펙트를 바꿔 넣는 2 번째의 우선 순위 레벨.

에러 코드

메소드가 실패 하면, 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_INVALIDARG 무효인 인수.

IAMTimelineEffectable::GetEffect 메소드 (IAMTimelineEffectable 오브젝트)

IAMTimelineEffectable 인터페이스

지정된 우선 순위 레벨의 이펙트를 취득한다.

구문

object. GetEffect(
ppFx As AMTimelineObj,
Which As Long
)

파라미터

object
결과가 IAMTimelineEffectable 오브젝트가 되는 오브젝트식.
ppFX
이펙트를 받는 AMTimelineObj 오브젝트.
Which
취득하는 이펙트의 우선 순위 레벨.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.


IAMTimelineSplittable 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)의 타임 라인 오브젝트를 분할한다. 소스, 이펙트, 트란지션, 및 트럭은 이 오브젝트를 지원 한다.

메소드

SplitAt | Visual Basic 에서는 지원되어 있지 않다.
SplitAt2 | 지정된 시간에 오브젝트를 분할한다.

SplitAt 메소드 (IAMTimelineSplittable 오브젝트)

IAMTimelineSplittable 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SplitAt(
Time As <Unsupported variant type>
)

SplitAt2 메소드 (IAMTimelineSplittable 오브젝트)

IAMTimelineSplittable 오브젝트

지정된 시간에 오브젝트를 분할한다.

구문

object. SplitAt2(
Time As Double
)

파라미터

object
결과가 IAMTimelineSplittable 오브젝트가 되는 오브젝트식.
Time
오브젝트를 분할하는 시간. 오브젝트의 시작을 기준으로 해, 단위는 초.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.

주의

소스, 이펙트, 또는 트란지션을 분할하는 경우, 이 메소드는 같은 타입의 2 번째의 오브젝트를 생성 한다. 원의 오브젝트는, 분할이 지정된 시간까지 절약할 수 있고 절약할 수 있었던 부분이 새로운 오브젝트가 된다. 새로운 오브젝트는, 같은 프로퍼티를 모두 계승한다. 소스 오브젝트에서는, 이 메소드는 분할 시간에 걸리는 이펙트도 분할한다.

트럭으로 이 메소드를 호출하면, 지정된 만큼 비율 시간에 트럭내에 있는 모든 소스, 이펙트, 및 트란지션이 분할된다. 이 경우, 2 번째의 트럭은 생성 되지 않는다 (트럭은, 시간 제로로부터 시작되어, 무한하게 신장한다). 분할 시간이 트럭내의 모든 것보다 나중이 되는 경우, 이 메소드는 오브젝트에 대해서 어떠한 영향도 미치지 않는다.


IAMTimelineTransable 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)의 오브젝트에 트란지션을 추가한다. 트럭,합성,그룹 등, 적용하는 트란지션을 가질 수 있는 오브젝트에 적용된다. 트란지션을 지원 하고 있는 오브젝트는 트란지션을 몇개에서도 가질 수가 있지만, 그 시간을 오버랩 시킬 수 없다.

주 : 오디오는 트란지션을 지원 하고 있지 않다.

메소드

GetNextTrans | Visual Basic 에서는 지원되어 있지 않다.
GetNextTrans2 | 지정된 시간 이후에 시작하는 최초의 트란지션을 취득한다.
GetTransAtTime | Visual Basic 에서는 지원되어 있지 않다.
GetTransAtTime2 | 지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 트란지션을 취득한다.
TransAdd | 오브젝트에 트란지션을 추가한다.
TransGetCount | 이 오브젝트의 트란지션의 개수를 취득한다.

GetNextTrans 메소드 (IAMTimelineTransable 오브젝트)

IAMTimelineTransable 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetNextTrans(
ppTrans As AMTimelineObj,
pInOut As <Unsupported variant type>
)

GetNextTrans2 메소드 (IAMTimelineTransable 오브젝트)

IAMTimelineTransable 오브젝트

지정된 시간 이후에 출현하는 최초의 트란지션을 취득한다.

구문

object. GetNextTrans2(
ppTrans As IAMTimelineObj,
pInOut As Double
)

파라미터

object
결과가 IAMTimelineTransable 오브젝트가 되는 오브젝트식.
ppTrans
트란지션을 받는 AMTimelineObj 오브젝트.
pInOut
입력으로는, 이 파라미터는 트란지션의 검색을 시작 할 시간을 지정한다. 출력으로는, 트란지션이 취득되었을 경우, 이 파라미터는 그 트란지션의 종료 타임으로 설정된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

트란지션이 지정된 시간을 넘는 경우, 트란지션의 시작 타임은 pInOut 로 지정되고 있는 시간부터 소구 되는 일이 있다.

GetTransAtTime 메소드 (IAMTimelineTransable 오브젝트)

IAMTimelineTransable 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetTransAtTime(
ppObj As AMTimelineObj,
Time As <Unsupported variant type>,
SearchDirection As Long
)

GetTransAtTime2 메소드 (IAMTimelineTransable 오브젝트)

IAMTimelineTransable 오브젝트

지정된 경계 조건에 따라, 지정된 시간에 가장 가까운 트란지션을 취득한다.

구문

object. GetTransAtTime2(
ppObj As AMTimelineObj,
Time As Double,
SearchDirection As Long
)

파라미터

object
결과가 IAMTimelineTransable 오브젝트가 되는 오브젝트식.
ppObj
트란지션을 받는 IAMTimelineObj 오브젝트.
Time
검색을 시작 할 시간 (초단위).
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 열거형의 멤버. 검색의 경계 조건을 지정한다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정된다.

E_INVALIDARG 무효인 인수.

TransAdd 메소드 (IAMTimelineTransable 오브젝트)

IAMTimelineTransable 오브젝트

오브젝트에 트란지션을 추가한다. 오브젝트는 복수의 트란지션을 가질 수가 있지만, 그 시간이 오버랩 해서는 안 된다. 트란지션은, 오브젝트의 시간 경계내에 들어가지 않으면 안 된다.

구문

object. TransAdd(
pTrans As AMTimelineObj
)

파라미터

object
결과가 IAMTimelineTransable 오브젝트가 되는 오브젝트식.
pTrans
추가하는 트란지션을 지정하는 AMTimelineObj 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 트란지션을 삽입할 수 없다.
E_NOINTERFACE | pTrans 가 트란지션은 아니다.

주의

삽입하는 트란지션이 기존의 트란지션에 오버랩 하는 경우, 이 메소드에서는 E_INVALIDARG 에러가 발생한다.

TransGetCount 메소드 (IAMTimelineTransable 오브젝트)

IAMTimelineTransable 오브젝트

이 오브젝트의 트란지션의 개수를 취득한다.

구문

object. TransGetCount(
pCount As Long
)

파라미터

object
결과가 IAMTimelineTransable 오브젝트가 되는 오브젝트식.
pCount
트란지션의 수를 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.


IAMTimelineVirtualTrack 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)의가상 트럭을 조작하는 메소드를 제공한다. 합성 및트럭은, 이 오브젝트를 지원 한다.

메소드

SetTrackDirty | Visual Basic 에서는 지원되어 있지 않다.
TrackGetPriority | 오브젝트의 우선 순위 레벨을 취득한다.

SetTrackDirty 메소드 (IAMTimelineVirtualTrack 오브젝트)

IAMTimelineVirtualTrack 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetTrackDirty()

TrackGetPriority 메소드 (IAMTimelineVirtualTrack 오브젝트)

IAMTimelineVirtualTrack 오브젝트

오브젝트의 우선 순위 레벨을 취득한다.

구문

object. TrackGetPriority(
pPriority As Long
)

파라미터

object
결과가 IAMTimelineVirtualTrack 오브젝트가 되는 오브젝트식.
pPriority
우선 순위 레벨을 받는 변수에의 포인터. 오브젝트가 타임 라인이 일부에서 없는 경우, 값은 -1 으로 설정된다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.


IAMCollection 오브젝트

필터 그래프 매니저는 IAMCollection 오브젝트를 공개한다. 이 오브젝트를 이용 하면, 오브젝트 콜렉션에 액세스 할 수 있다. 이러한 콜렉션에는,IPinInfo ,IFilterInfo , 또는 IMediaTypeInfo 오브젝트가 포함된다.

프로퍼티

Count 콜렉션내의 아이템의 수를 돌려준다.

메소드

Item 콜렉션의 지정된 멤버를 취득한다.

Count 프로퍼티 (IAMCollection 오브젝트)

IAMCollection 오브젝트

콜렉션내의 아이템의 수를 돌려준다.

구문

objCollection. Count

지정 항목

objCollection
평가 결과가 IAMCollection 가 되는 오브젝트식.

Item 메소드 (IAMCollection 오브젝트)

IAMCollection 오브젝트

지정된 콜렉션 멤버를 취득해, 건네받은 오브젝트에 그것을 저장 한다.

구문

 objCollection. Item lItem, objNew

지정 항목

objCollection
평가 결과가 IAMCollection 가 되는 오브젝트식.
lItem
취득하는 아이템의 인덱스.
objNew
콜렉션의 종류에 응해, 평가 결과가 IFilterInfo ,IPinInfo , 또는 IMediaTypeInfo 오브젝트가 되는 오브젝트식. 이 인수에는, 취득된 아이템이 저장 된다.

주의

인덱스값은, 0 으로부터 (Count – 1)의 범위내가 된다.


IBasicAudio 오브젝트

IBasicAudio 오브젝트는, 필터 그래프의 오디오 컴퍼넌트를 지원 한다. 이 오브젝트를 이용해, 볼륨 기능과 밸런스 기능에 액세스 할 수 있다.

Volume 프로퍼티는, 선형적인 단계의 집합을 나타내는 –10, 000 에서 0 의 사이의 값이다. 식별 가능한 10,000 단계를 지원 하지 않는 디바이스도 있다.

Balance 프로퍼티는, –10, 000 에서 10,000 의 사이의 값이다. 값 –10, 000 은, 오른쪽 스피커가 무효가 되어 있어, 왼쪽 스피커인 만큼 오디오 신호가 입력되고 있는 것을 나타낸다. 값 0 은, 양쪽 모두의 스피커에 같은 볼륨의 오디오 신호가 입력되고 있는 것을 나타낸다. 값 10,000 은, 왼쪽 스피커가 무효가 되어 있어, 오른쪽 스피커인 만큼 오디오 신호가 입력되고 있는 것을 나타낸다.

프로퍼티

Balance | 오디오 신호의 밸런스를 설정한다, 또는 돌려준다.
Volume | 오디오 신호의 볼륨 (크기)을 설정한다, 또는 돌려준다.

Balance 프로퍼티 (IBasicAudio 오브젝트)

IBasicAudio 오브젝트

오디오 채널의 밸런스를 설정한다, 또는 돌려준다.

구문

objAudio. Balance [= lValue ]

지정 항목

objAudio
평가 결과가 IBasicAudio 오브젝트가 되는 오브젝트식.
lValue
Balance 프로퍼티의 새로운 값.

주의

Balance 프로퍼티는, –10, 000 에서 10,000 의 사이의 값이다. 값 –10, 000 은, 오른쪽 스피커가 무효가 되어 있어, 왼쪽 스피커인 만큼 오디오 신호가 입력되고 있는 것을 나타낸다. 값 0 은, 양쪽 모두의 스피커에 같은 볼륨의 오디오 신호가 입력되고 있는 것을 나타낸다. 값 10,000 은, 왼쪽 스피커가 무효가 되어 있어, 오른쪽 스피커인 만큼 오디오 신호가 입력되고 있는 것을 나타낸다.

식별 가능한 10,000 단계를 지원 하지 않는 디바이스도 있는 점에 주의 해야 한다.

Balance 프로퍼티를 이 범위외의 값으로 설정하려고 하면(자),IBasicAudio 오브젝트는 실행시 에러 5 를 생성한다.

Volume 프로퍼티 (IBasicAudio 오브젝트)

IBasicAudio 오브젝트

오디오 채널의 볼륨을 설정한다, 또는 돌려준다.

구문

objAudio. Volume [= lValue]

지정 항목

objAudio
평가 결과가 IBasicAudio 오브젝트가 되는 오브젝트식.
lValue
Volume 프로퍼티의 새로운 값.

주의

–10, 000 에서 0 의 사이의 값을 입력할 수 있다.

풀 볼륨은 0 이며, –10, 000 은 무음이다. 눈금은 선형이다. 이 범위외의 값을 지정 하면, 실행시 에러 5 가 돌려주어진다.

식별 가능한 10,000 단계를 지원 하지 않는 디바이스도 있는 점에 주의 해야 한다.


IBasicVideo 오브젝트

필터 그래프 매니저는, 범용 비디오 윈도우의 비디오 프로퍼티를 지원 하는 IBasicVideo 오브젝트를 공개한다. 일반적으로, 이것은, 디스플레이상의 윈도우내에서 비디오를 드로잉(Drawing) 하는 비디오 렌더러이다.

IBasicVideo 오브젝트의 메소드를 사용하려면 , 비디오 렌더러가 접속되고 있을 필요가 있다. 비디오 렌더러가 접속되어 있지 않은 경우, 모든 메소드는 실행시 에러 521 을 돌려준다. 비디오 렌더러로 설정되어 있는 프로퍼티는, 보통, 접속과 절단을 반복해도 변함없다. 모든 어플리케이션은, 비디오의 표시를 시작 하기 전에, 렌더러의 프로퍼티가 리셋 되고 있는 것을 확인할 필요가 있다.

어플리케이션은, 비디오를 사용할때에, 사용하는 비디오의 일부를 선택할 수가 있다. 선택되는 부분은,IBasicVideo 오브젝트가 제어하는 전송원직사각형이다. IBasicVideo 를 사용해, 전송원직사각형을 설정하거나 취득하거나 할 수가 있다. 모든 IBasicVideo 직사각형은, 상, 좌, 폭, 높이의 프로퍼티를 가지고 있다. 전송원직사각형이 설정되어 있지 않은 경우, 전송원직사각형의 프로퍼티는, 본래의 비디오의 풀 사이즈를 돌려준다.

프로퍼티

AvgTimePerFrame | 연속하는 프레임간의 평균 시간을 100 나노초단위로 취득한다.
BitErrorRate | 비디오 스트림의 대체로의 비트 에러 레이트를 취득한다.
BitRate | 비디오 스트림의 대체로의 bit rate를 취득한다.
DestinationLeft | 비디오의 전송처 직사각형의 x 축의 좌표를 설정 또는 취득한다.
DestinationHeight | 비디오의 전송처 직사각형의 높이를 설정 또는 취득한다.
DestinationTop | 비디오의 전송처 직사각형의 y 축의 좌표를 설정 또는 취득한다.
DestinationWidth | 비디오의 전송처 직사각형의 폭을 설정 또는 취득한다.
SourceHeight | 비디오의 전송원직사각형의 높이를 설정 또는 취득한다.
SourceLeft | 비디오의 전송원직사각형의 x 축의 좌표를 설정 또는 취득한다.
SourceTop | 비디오의 전송원직사각형의 y 축의 좌표를 설정 또는 취득한다.
SourceWidth | 비디오의 전송원직사각형의 폭을 설정 또는 취득한다.
VideoHeight | 현재의 비디오의 높이를 취득한다.
VideoWidth | 현재의 비디오의 폭을 취득한다.

메소드

GetCurrentImage | 현재 렌더러로 대기중의 화면의 카피를 돌려준다.
GetDestinationPosition | 윈도우의 전송처 직사각형을 취득한다.
GetSourcePosition | 비디오의 전송원직사각형을 취득한다.
GetVideoPaletteEntries | 비디오가 필요로 하는 칼라 팔레트 엔트리를 취득한다.
GetVideoSize | 본래의 비디오의 크기를 취득한다.
IsUsingDefaultSource | 디폴트의 전송원이 사용되고 있는지 어떤지를 나타낸다.
SetDefaultDestinationPosition | 윈도우의 디폴트의 전송처 위치를 설정한다.
SetDefaultSourcePosition | 렌더러에 대해서, 디폴트의 전송원직사각형을 사용하도록(듯이) 통지한다.
SetDestinationPosition | 윈도우의 전송처 직사각형을 설정한다.
SetSourcePosition | 비디오의 전송원직사각형을 설정한다.

AvgTimePerFrame 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

연속하는 프레임간의 평균 시간을 100 나노초단위로 취득한다.

구문

objVideo. AvgTimePerFrame

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.

BitErrorRate 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

비디오 스트림의 비트 에러 레이트 (대체로 무엇 비트 마다 1 회 에러가 발생하는지를 나타내는 값)를 취득한다.

구문

objVideo. BitErrorRate

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.

BitRate 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

비디오 스트림의 대체로의 bit rate를 1 초 쯤의 비트수단위로 취득한다.

구문

objVideo. BitRate

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.

DestinationHeight 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

전송처 직사각형의 높이를 취득 또는 설정한다.

구문

objVideo. DestinationHeight [= lValue]

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
lValue
전송처 직사각형의 높이의 새로운 값.

주의

이 좌표를 설정해도, 전송처 직사각형의 y 축의 원점은 영향을 받지 않는다.

DestinationLeft 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

전송처의 x 축의 원점의 좌표를 취득 또는 설정한다.

구문

objVideo. DestinationLeft [= lValue]

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
lValue
전송처의 x 축의 원점의 새로운 값.

주의

이 좌표를 설정해도, 전송처 직사각형의 폭은 영향을 받지 않는다.

DestinationTop 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

전송처의 y 축의 원점의 좌표를 취득 또는 설정한다.

구문

objVideo. DestinationTop [= lValue]

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
lValue
y 축의 원점의 새로운 값.

주의

이 좌표를 설정해도, 전송처 직사각형의 높이는 영향을 받지 않는다.

DestinationWidth 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

전송처 직사각형의 폭을 취득 또는 설정한다.

구문

objVideo. DestinationWidth [= lValue]

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
lValue
새로운 폭의 값.

주의

이 좌표를 설정해도, 전송처 직사각형의 x 축의 원점은 영향을 받지 않는다.

GetCurrentImage 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

현재, 렌더러로 대기중의 화면을 취득한다.

구문

objVideo. GetCurrentImage BufferSize, DIBImage

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
BufferSize
호출원이 건네주는 버퍼의 사이즈를 지정하는 Long 형의 값. GetCurrentImage 는, 종료전에, 이 값을 버퍼내의 실제의 바이트수로 설정한다.
DIBImage
화면 전체가 DIB (디바이스에 의존하지 않는 비트 맵) 포맷으로 저장 되는 버퍼가 포함되어 있는 Long 형의 값. 버퍼는 참조에 의해 건네줄 필요가 있다.

주의

이 메소드를 호출하기 전에 비디오 렌더러를 포즈 시키는 것. 비디오 렌더러가 다른 상태에 있을 때 이 메소드를 호출하면, 실행시 에러 549 가 돌려주어진다. 소스 필터로 이용 가능한 데이터의 종류에 따라서는, 비디오 렌더러가 이 요구에 응하지 않는 것도 있다.

DIBImage 를 Nothing 로 설정해, 이 메소드를 호출하는 것으로, 어플리케이션은 이 메소드를 이용해, 포즈 하고 있는 비디오 렌더러에 저장 되고 있는 현재의 화면의 카피를 취득할 수 있다.

GetDestinationPosition 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

전송처 직사각형의 윈도우 좌표 위에의 위치를 취득한다.

구문

objVideo. GetDestinationPosition Left, Top, Width, Height

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
Left
전송처 윈도우의 x 축의 원점이 저장 되고 있는 Long 형의 정수값.
Top
전송처 윈도우의 y 축의 원점이 저장 되고 있는 Long 형의 정수값.
Width
전송처 윈도우의 폭이 저장 되고 있는 Long 형의 정수값.
Height
전송처 윈도우의 높이가 저장 되고 있는 Long 형의 정수값.

주의

이 메소드에는,DestinationLeft 프로퍼티,DestinationTop 프로퍼티,DestinationWidth 프로퍼티, 및 DestinationHeight 프로퍼티를 개별적으로 취득하는 것과 같은 효과가 있다.

GetSourcePosition 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

이용 가능한 비디오에 클립 되는 전송원래의 위치를 취득한다.

구문

objVideo. GetSourcePosition Left, Top, Width, Height

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
Left
전송원윈도우의 x 축의 원점이 저장 되는 Long 형의 정수값.
Top
전송원윈도우의 y 축의 원점이 저장 되는 Long 형의 정수값.
Width
전송원윈도우의 폭이 저장 되는 Long 형의 정수값.
Height
전송원윈도우의 높이가 저장 되는 Long 형의 정수값.

주의

이 메소드에는,SourceLeft 프로퍼티,SourceTop 프로퍼티,SourceWidth 프로퍼티, 및 SourceHeight 프로퍼티를 개별적으로 취득하는 것과 같은 효과가 있다.

GetVideoPaletteEntries 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

비디오의 팔레트 칼라를 취득한다.

구문

objVideo. GetVideoPaletteEntries StartIndex, Entries, Retrieved, Palette

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
StartIndex
팔레트의 시작 인덱스를 지정하는 Long 형의 정수값.
Entries
필요한 팔레트 엔트리의 수를 지정하는 Long 형의 정수값.
Retrieved
Palette 에 의해 실제로 돌려주어지는 엔트리의 수가 저장 되는 Long 형의 정수값.
Palette
Microsoft® Win32® PALETTEENTRY 구조체의 배열을 가리키는 포인터가 저장 되는 Long 형의 정수값.

GetVideoSize 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

본래의 비디오의 크기를 취득한다.

구문

objVideo. GetVideoSize Width, Height

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
Width
비디오 윈도우의 폭이 저장 되는 Long 형의 정수값.
Height
비디오 윈도우의 높이가 저장 되는 Long 형의 정수값.

주의

설정되어 있을 가능성이 있는 전송원직사각형은 모두 무시해, 본래의 비디오의 폭과 높이를 취득한다. ActiveX 컨트롤 또는 그 외의 어플리케이션은, 이 정보를 사용해, 복합 문서내의 스페이스를 확보할 수가 있다.

IsUsingDefaultSource 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

이 오브젝트가 디폴트의 전송원을 사용하고 있을지 어떨지의 정보를 취득한다.

구문

objVideo. IsUsingDefaultSource

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.

반환값

TRUE 는 IBasicVideo 오브젝트가 디폴트의 전송원을 사용하고 있는 것을 나타내, FALSE 는 사용하지 않은 것을 나타낸다.

SetDefaultDestinationPosition 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

렌더러가 재생에 윈도우 전체를 사용하도록(듯이), 비디오 윈도우의 디폴트의 전송처 위치를 설정한다.

구문

objVideo. SetDefaultDestinationPosition

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.

SetDefaultSourcePosition 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

렌더러에 대해서, 디폴트의 전송원직사각형을 사용하도록(듯이) 통지한다.

구문

objVideo. SetDefaultSourcePosition

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.

SetDestinationPosition 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

윈도우 좌표상에서 전송처 직사각형을 설정한다.

구문

objVideo. SetDestinationPosition Left, Top, Width, Height

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
Left
전송처 윈도우의 x 축의 원점을 픽셀 단위로 지정하는 Long 형의 정수값.
Top
전송처 윈도우의 y 축의 원점을 픽셀 단위로 지정하는 Long 형의 정수값.
Width
전송처 윈도우의 폭을 픽셀 단위로 지정하는 Long 형의 정수값.
Height
전송처 윈도우의 높이를 픽셀 단위로 지정하는 Long 형의 정수값.

주의

이 메소드에는,DestinationLeft 프로퍼티,DestinationTop 프로퍼티,DestinationWidth 프로퍼티, 및 DestinationHeight 프로퍼티를 개별적으로 설정하는 것과 같은 효과가 있다.

SetSourcePosition 메소드 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

이용 가능한 비디오에 클립 되는 전송원직사각형을 설정한다.

구문

objVideo. SetSourcePosition Left, Top, Width, Height

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
Left
전송원윈도우의 x 축의 원점을 지정하는 Long 형의 값.
Top
전송원윈도우의 y 축의 원점을 지정하는 Long 형의 값.
Width
전송원윈도우의 폭을 지정하는 Long 형의 값.
Height
전송원윈도우의 높이를 지정하는 Long 형의 값.

주의

이 메소드에는,SourceLeft 프로퍼티,SourceTop 프로퍼티,SourceWidth 프로퍼티, 및 SourceHeight 프로퍼티를 개별적으로 설정하는 것과 같은 효과가 있다.

SourceHeight 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

전송원직사각형의 높이를 취득 또는 설정한다.

구문

objVideo. SourceHeight [= lValue]

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
lValue
현재의 직사각형의 높이를 픽셀 단위로 지정하는 Long 형의 값.

주의

전송원직사각형의 높이를 설정해도, 전송원의 폭등의 값은 영향을 받지 않는다.

SourceLeft 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

전송원직사각형의 x 좌표를 취득 또는 설정한다.

구문

objVideo. SourceLeft [= lValue]

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
lValue
전송원직사각형의 x 축의 원점의 새로운 값.

주의

이 프로퍼티를 변경해도, 전송원의 폭 및 그 외의 값은 영향을 받지 않는다.

SourceTop 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

전송원직사각형의 y 축의 원점의 좌표를 취득 또는 설정한다.

구문

objVideo. SourceTop [= lValue]

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
lValue
디스플레이의 상단으로부터 현재의 윈도우의 상단까지의 거리를 픽셀 단위로 지정하는 Long 형의 값.

주의

이 메소드를 설정해도, 전송원직사각형의 높이는 영향을 받지 않는다.

SourceWidth 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

전송원직사각형의 폭을 취득 또는 설정한다.

구문

objVideo. SourceWidth [= lValue]

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.
lValue
현재의 폭을 픽셀 단위로 지정하는 Long 형의 값.

주의

이 메소드에, 전송원직사각형의 x 축좌표를 변경하는 효과는 없다.

VideoHeight 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

본래의 비디오의 높이를 취득한다.

구문

objVideo. VideoHeight

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.

주의

이 메소드는, 렌더러에 공급되는 비디오의 실제의 높이를 돌려준다. 이 메소드는, 설정되어 있는 전송원직사각형은 무시해, 본래의 수직 방향의 길이만을 돌려준다. 어플리케이션은, 이것을 사용해, 매입처 컨테이너 문서와의 사이에 사이즈 요건을 네고시에이트 할 수 있다.

VideoWidth 프로퍼티 (IBasicVideo 오브젝트)

IBasicVideo 오브젝트

비디오의 본래의 폭을 취득한다.

구문

objVideo. VideoWidth

지정 항목

objVideo
평가 결과가 IBasicVideo 오브젝트가 되는 오브젝트식.

주의

이 메소드는, 렌더러에 공급되는 비디오의 실제의 폭을 돌려준다. 이 메소드는, 설정되어 있는 전송원직사각형은 무시해, 본래의 수평 방향의 길이만을 돌려준다. 어플리케이션은, 이것을 사용해, 매입처 컨테이너 문서와의 사이에 사이즈 요건을 네고시에이트 할 수 있다.


IFilterInfo 오브젝트

IFilterInfo 는, 필터에 관한 정보를 관리하는 오브젝트로, 이것을 이용해, 필터 오브젝트 및 IPinInfo 오브젝트에 액세스 할 수 있다.

프로퍼티

Filename | 소스 필터에 관련지을 수 있었던 파일명을 취득 또는 설정한다.
Filter | 실제의 필터 오브젝트를 취득한다.
IsFileSource | 필터가 파일 소스 필터일지 어떨지를 나타낸다.
Name | 필터명을 취득한다.
Pins | 이 필터의 IPinInfo 오브젝트가 포함되어 있는 IAMCollection 오브젝트를 취득한다.
VendorInfo | 지정된 필터에 관해서 vender가 제공하고 있는 옵션의 정보가 저장 된 캐릭터 라인을 취득한다.

메소드

FindPin 지정된 식별자에 근거해 핀을 검색해,IPinInfo 를 지원 하는 오브젝트를 돌려준다.

Filename 프로퍼티 (IFilterInfo 오브젝트)

IFilterInfo 오브젝트

필터가 저장 되고 있는 파일의 이름을 취득 또는 설정한다.

구문

objFilterInfo. Filename [= string]

지정 항목

objFilterInfo
평가 결과가 IFilterInfo 오브젝트가 되는 오브젝트식.
string
새로운 파일명을 지정하는 캐릭터 라인식.

Filter 프로퍼티 (IFilterInfo 오브젝트)

IFilterInfo 오브젝트

필터 오브젝트를 취득한다.

구문

Set objFilter = objFilterInfo. Filter

지정 항목

objFilter
평가 결과가 IBaseFilter 오브젝트가 되는 오브젝트식.
objFilterInfo
평가 결과가 IFilterInfo 오브젝트가 되는 오브젝트식.

주의

IBaseFilter 인터페이스에 대해서 프로그래밍 가능한 오브젝트 인터페이스는 제공되어 있지 않다. 다만, Visual Basic® 프로그래머는, 돌려주어진 오브젝트를,IBaseFilter 인터페이스 포인터를 파라미터로서 취하는 함수에 대한 호출로 파라미터로서 사용할 수 있다.

FindPin 메소드 (IFilterInfo 오브젝트)

IFilterInfo 오브젝트

지정된 식별자에 근거해 핀을 검색해,IPinInfo 오브젝트를 돌려준다.

구문

objFilterInfo. FindPin string, objPin

지정 항목

objFilterInfo
평가 결과가 IFilterInfo 오브젝트가 되는 오브젝트식.
string
검색하는 핀의 이름이 저장 된 캐릭터 라인.
objPin
핀이 발견되었을 경우에, 지정된 핀이 저장 되는 IPinInfo 오브젝트.

주의

IPin 인터페이스에 대해서 프로그래밍 가능한 오브젝트 인터페이스는 제공되어 있지 않다. 다만, Visual Basic 프로그래머는, 돌려주어진 오브젝트를,IPin 인터페이스 포인터를 파라미터로서 취하는 함수에 대한 호출로 파라미터로서 사용할 수 있다.

IsFileSource 프로퍼티 (IFilterInfo 오브젝트)

IFilterInfo 오브젝트

파일에 소스 비디오가 저장 되고 있는지 어떤지를 판별한다.

구문

objFilterInfo. IsFileSource

지정 항목

objFilterInfo
평가 결과가 IFilterInfo 오브젝트가 되는 오브젝트식.

반환값

TRUE 는 파일에 소스 비디오가 저장 되고 있는 것을 나타내, FALSE 는 파일에 소스 비디오가 저장되어 있지 않은 것을 나타낸다.

Name 프로퍼티 (IFilterInfo 오브젝트)

IFilterInfo 오브젝트

필터명을 취득한다.

구문

objFilterInfo. Name

지정 항목

objFilterInfo
평가 결과가 IFilterInfo 오브젝트가 되는 오브젝트식.

주의

vender가 필터명을 지정한다.

Pins 프로퍼티 (IFilterInfo 오브젝트)

IFilterInfo 오브젝트

이 필터의 IPinInfo 오브젝트가 포함되어 있는 IAMCollection 오브젝트를 취득한다.

구문

Set objPinCollection = objFilterInfo. Pins

지정 항목

objPinCollection
특정의 필터의 핀이 저장 되는 IAMCollection 오브젝트.
objFilterInfo
핀을 취득하는 필터를 지정하는 IFilterInfo 오브젝트.

주의

Count 프로퍼티와 Item 메소드를 사용해, 콜렉션내의 각각의 핀 오브젝트에 대해 반복 처리를 실시할 수가 있다.

VendorInfo 프로퍼티 (IFilterInfo 오브젝트)

IFilterInfo 오브젝트

지정된 필터에 관해서 vender가 제공하고 있는 옵션의 정보가 저장 된 캐릭터 라인을 취득한다.

구문

objFilterInfo. VendorInfo

지정 항목

objFilterInfo
평가 결과가 IFilterInfo 오브젝트가 되는 오브젝트식.

주의

이 프로퍼티에는, vender가 제공하는 정보가 저장 된다. 보통, 그 정보는, 필터에 관한 설명이다.


IMediaControl 오브젝트

필터 그래프는 IMediaControl 오브젝트를 공개해, 어플리케이션이 그래프내의 필터를 사용해 미디어의 스트리밍을 제어할 수 있도록(듯이) 한다. 인터페이스는, 데이터의 스트리밍의 트랜스폴트, 포즈, 및 정지를 처리하는 메소드를 갖추고 있다. 또, 인터페이스는, 미디어 파일을 재생하는 그래프를 생성하기 위한 간단한 메소드를 어플리케이션에 제공한다.

프로퍼티

FilterCollection | 그래프내의 현재의 필터를 나타내는 IFilterInfo 오브젝트의 콜렉션을 취득한다.
RegFilterCollection | 레지스트리내의 이용 가능한 필터를 나타내는 IRegFilterInfo 오브젝트의 콜렉션을 취득한다.

메소드

AddSourceFilter | 지정된 파일명을 읽어낼 수 있는소스 필터를 그래프에 추가한다.
GetState | 필터 그래프 상태를 취득한다.
Pause | 필터 그래프내의 모든 필터를 포즈 시킨다.
RenderFile | 특정의 파일의 재생에 필요한 모든 필터를 추가해, 접속한다.
Run | 필터 그래프 전체를 실행 모드로 전환한다.
Stop | 필터 그래프내의 모든 필터를 정지상태태로 전환한다.

AddSourceFilter 메소드 (IMediaControl 오브젝트)

IMediaControl 오브젝트

지정된 파일명을 읽어낼 수 있는 소스 필터를 그래프에 추가해, 생성 된 IFilterInfo 오브젝트를 돌려준다.

구문

objMediaControl. AddSourceFilter string, objFilterInfo

지정 항목

objMediaControl
평가 결과가 IMediaControl 오브젝트가 되는 오브젝트식.
string
소스 미디어가 저장 되고 있는 파일의 이름.
objFilterInfo
지정된 원시 파일에 대해서 생성 된 소스 필터인 IFilterInfo 오브젝트.

FilterCollection 프로퍼티 (IMediaControl 오브젝트)

IMediaControl 오브젝트

그래프내의 필터를 나타내는 IFilterInfo 오브젝트의 콜렉션을 취득한다. IAMCollection 오브젝트를 돌려준다.

구문

Set objCollection = objMediaControl. FilterCollection

지정 항목

objCollection
필터 그래프내에 현재 있는 필터의 콜렉션을 나타내는 IAMCollection 오브젝트.
objMediaControl
평가 결과가 IMediaControl 오브젝트가 되는 오브젝트식.

GetState 메소드 (IMediaControl 오브젝트)

IMediaControl 오브젝트

현재 상태값을 나타내는 Long 형의 정수를 돌려준다.

구문

objMediaControl. GetState msTimeout, State

지정 항목

objMediaControl
평가 결과가 IMediaControl 오브젝트가 되는 오브젝트식.
msTimeout
밀리 세컨드 단위로 나타내는 타임 아웃의 시간폭.
State
현재 상태가 저장 되는 Long 형의 값. 이 인수는, 다음의 어느 쪽인가에 된다.
State_Paused | 미디어 소스가 포즈 하고 있다.
State_Running | 미디어 소스가 트랜스폴트 하고 있다.
State_Stopped | 미디어 소스가 정지하고 있다.

반환값

상태의 이행이 완료하고 있지 않는 경우는 실행시 에러 567 을 돌려주어, 상태의 이행이 완료하고 있으면 0 을 돌려준다.

주의

모든 상태 이행은, 동기를 취해 행해지는 것은 아니다. 예를 들어, 보통 Pause 메소드가 곧바로 돌려주어졌을 경우에서도,렌더러로 데이터를 준비할 수 있을 때까지, 그래프는 포즈 모드에의 이행을 완료하지 않는다. 이 메소드는, 상태 이행이 완료할 때까지 제로를 돌려주지 않는다.

제로 이외의 타임 아웃을 지정 하면, 이 메소드는 그래프가 중간 상태로부터 이행 할 때까지, 그래프로 지정된 밀리 세컨드까지 기다린다. 상태 이행이 완료하기 전에 타임 아웃의 기한이 지나면(자), 귀가 코드는 567 이 되어, 돌려주어지는 상태는 그래프의 이행처 상태 (State_Stopped, State_Paused, 또는 State_Running)가 된다.

RegFilterCollection 프로퍼티 (IMediaControl 오브젝트)

IMediaControl 오브젝트

레지스트리내의 이용 가능한 필터를 나타내는 IRegFilterInfo 오브젝트의 콜렉션을 취득한다.

구문

Set objCollection = objMediaControl. RegFilterCollection

지정 항목

objCollection
IAMCollection object that contains IRegFilterInfo objects.
objMediaControl
평가 결과가 IMediaControl 오브젝트가 되는 오브젝트식.

반환값

IAMCollection 오브젝트를 돌려준다.

Pause 메소드 (IMediaControl 오브젝트)

IMediaControl 오브젝트

필터 그래프내의 모든 필터를 포즈 시킨다.

구문

objMediaControl. Pause

지정 항목

objMediaControl
평가 결과가 IMediaControl 오브젝트가 되는 오브젝트식.

주의

포즈 상태에서는, 필터는 데이터를 처리하지만, 렌더링은 실시하지 않는다. 데이터는 필터 그래프에 푸쉬 다운 되어 버퍼링으로 허가되는 한,변환 필터에 의해 처리된다. 비디오 등, 정적으로 렌더링 가능한 미디어 타입에, 포즈 모드로 렌더링 되는 정적인 포스터 프레임이 있는 경우를 제외해, 데이터는 렌더링 되지 않는다. 그 때문에, 필터 그래프를 포즈 상태로 하면(자), 실행 상태가 되었을 때에 곧바로 렌더링 되는 큐에 넣어진다.

RenderFile 메소드 (IMediaControl 오브젝트)

IMediaControl 오브젝트

지정된 파일을 재생하기 위해서 필요한 필터를 추가, 접속한다.

구문

objMediaControl. RenderFile string

지정 항목

objMediaControl
평가 결과가 IMediaControl 오브젝트가 되는 오브젝트식.
string
렌더링 하는 파일의 이름.

주의

이 메소드를 사용하면(자), 어플리케이션은 렌더링 하는 미디어 파일의 이름을 그래프 매니저에 건네줄 수가 있다. 필터 그래프 매니저는, 이 파일을 재생하기 위해서 필요한 필터의 그래프를 구축한다.

Run 메소드 (IMediaControl 오브젝트)

IMediaControl 오브젝트

필터 그래프 전체를 실행 상태로 전환한다.

구문

objMediaControl. Run

지정 항목

objMediaControl
평가 결과가 IMediaControl 오브젝트가 되는 오브젝트식.

주의

필터 그래프가 정지상태태에 있는 경우, 이 메소드는 최초로 그래프를 포즈 하고 나서 실행한다.

에러값이 돌려주어졌을 경우, 그래프내의 일부의 필터는, 올바르게 실행 상태가 되어 있을 가능성이 있다. 멀티 스트림 그래프에서는, 스트림 전체가 올바르게 재생되고 있을 가능성이 있다. 어플리케이션은, 실행을 정지할지 어떨지를 판정해야 한다.

Stop 메소드 (IMediaControl 오브젝트)

IMediaControl 오브젝트

필터 그래프내의 모든 필터를 정지상태태로 전환한다.

구문

objMediaControl. Stop

지정 항목

objMediaControl
평가 결과가 IMediaControl 오브젝트가 되는 오브젝트식.

주의

이 모드에서는, 필터는 리소스를 해방해, 데이터는 처리되지 않는다. 필터가 실행 상태의 경우, 이 메소드는 필터를 포즈 하고 나서 정지한다. 이것에 의해, 비디오 렌더러는, 정지중에 포스터 프레임을 표시하기 위해서, 현재의 프레임을 카피할 수 있다.


IMediaEvent 오브젝트

이 오브젝트는, 필터 그래프 및 필터 그래프내의 필터로부터 어플리케이션에의이벤트 통지를 지원 한다.

1 개의 이벤트 코드와 2 개의 파라미터로 통지 정보를 나타낸다. 이것을 이용해, 비동기 동작의 완료, 비동기 동작의 한중간에 발생한 에러, 또는, 유저에 의한 핫 스포트의 클릭등의 유저 조작 이벤트를 통지할 수 있다.

필터 그래프내의 필터 및 필터 그래프 자체가 이벤트 통지를 생성한다. 통지할 수 있는 이벤트에는, 재생의 완료 또는 비동기 재생의 에러가 포함된다. 또, 필터 그래프는, 특정의기준 클락 시간에 이벤트를 생성하는 메소드를 갖추고 있다.

이벤트 통지는 큐에 넣어진다. 어플리케이션은 IMediaEvent 오브젝트의 GetEvent 메소드를 호출해, 다음의 통지를 큐로부터 꺼낸다. 이 메소드는, 돌려주는 이벤트가 큐에 들어갈 때까지 동작을 정지한다. GetEvent 메소드의 타임 아웃 파라미터를 이용해, 어플리케이션은, 이벤트를 대기하는 시간을 밀리 세컨드 단위로 지정할 수가 있다. 제로 (대기하지 않는다) 및 무한대 (항상 대기)도 지정할 수 있다.

게다가 어플리케이션은 이벤트 핸들을 취득할 수 있다. GetEventHandle 는, Microsoft® Win32® CreateEvent 함수에 의해 생성 된 수동 리셋 이벤트의 핸들을 돌려준다. 이 이벤트는, 수집하는 이벤트 통지가 존재하는 한, 통지제상태에 놓여진다. 수집하는 이벤트 통지가 없어지면(자),GetEvent 메소드는 이벤트를 소거한다. 이 기능에 의해, 어플리케이션은,MsgWaitForMultipleObjects 등의 API (어플리케이션 프로그래밍 인터페이스)를 이용해, 이벤트와 그 외의 대상을 동시에 기다릴 수가 있다. 이 이벤트 핸들은, 필터 그래프가 해방되었을 때에 닫는다. 따라서, 어플리케이션은, 그 시점 이후에 이벤트 핸들을 사용하지 않게 주의할 필요가 있다.

필터 그래프는, 필터에 의해 생성되어 어플리케이션에게 건네지지 않는 일부의 이벤트를 처리한다. EC_REPAINT 이벤트 통지가 그 예이다. 이 이벤트의 디폴트의 처리는, 필터 그래프를 포즈 시키는 것에 의해, 비디오 렌더러의 정지화면상을 재드로잉(Drawing) 하는 것이다. 어플리케이션은, 이벤트값을 파라미터로서 CancelDefaultHandling 메소드를 호출하는 것으로, 특정의 이벤트의 디폴트 처리를 오버라이드(override) 할 수가 있다. RestoreDefaultHandling 메소드는, 지정된 이벤트값의 디폴트 처리를 바탕으로 되돌린다. 이러한 메소드는, 디폴트 처리가 없는 이벤트에는 영향을 주지 않는다.

트랜스폴트 상태에의 이행중에 필터상에서 에러가 발생했을 경우는,Run 메소드가 에러값을 돌려준다. 이 경우, 필터 그래프내의 일부의 필터는 문제 없고 트랜스폴트 하고 있을 가능성이 있다. 필터 그래프는, 에러가 발생했을 때에 그래프를 정지할지 어떨지의 판단을 어플리케이션에 맡긴다. Run 메소드가 종료한 후, 이벤트 통지는, 그 외의 에러를 보고한다. EC_ERRORABORT 이벤트 통지와 EC_USERABORT 이벤트 통지는, 그래프로 (게다가 에러가 보고된 필터로) 재생이 정지한 가능성이 있는 것을 나타낸다. 그 외의 에러 및 이벤트는, 그래프가 아직 트랜스폴트중인 것을 나타낸다. 다만, 어떤 경우라도, 어플리케이션이 명시적으로 그래프를 정지 모드 또는 포즈 모드에 이행 시킬 때까지, 그래프는 트랜스폴트 모드에 머무르는 점에 주의 해야 한다.

필터 그래프내의 스트림이 스트림의 말미를 검출 하면, 스트림은,EC_COMPLETE 이벤트 통지를 사용해 그것을 보고한다. 필터 그래프는,"시크 가능한 렌더러 " 경유로 EC_COMPLETE 를 보고할 수 있을지 어떨지를 필터에 문의한다.

시크 가능한 렌더러는, 필터상에서 IMediaPosition 오브젝트를 지원 해,입력 핀만을 가지는 렌더러, 또는, 그 시점에서 렌더링이 종료한 것을 보고하는 입력 핀을 가지는 렌더러이다. 필터 그래프는 시크 가능한 렌더러를 검출한다. 시크 가능한 렌더러는, 그 필터 위에의 모든 시크 가능한 스트림이 스트림의 말미에 이르면(자) EC_COMPLETE 를 보고한다.

필터 그래프 매니저는, 각 스트림으로부터 EC_COMPLETE 이벤트 통지를 받을 때까지,EC_COMPLETE 를 어플리케이션에 건네주지 않는다. 예를 들어, 파일 재생 비디오의 백그라운드로서 라이브 카메라의 스트림이 재생되고 있는 경우, 어플리케이션은, 파일의 비디오 스트림과 오디오 스트림이 스트림의 말미에 이르면(자), 라이브 소스가 아직 재생중에서 만나도 EC_COMPLETE 의 통지를 받는다. 이 경우도, 필터 그래프는, 어플리케이션이 명시적으로 Pause 메소드 또는 Stop 메소드를 호출할 때까지, 트랜스폴트 상태에 머무른다.

EC_COMPLETE 를 파라미터로서 CancelDefaultHandling 를 호출하는 것으로,EC_COMPLETE 메세지의 집합을 무효로 할 수 있다. 이 경우, 필터에 의해 생성된 모든 EC_COMPLETE 이벤트는 직접 어플리케이션에게 건네진다.

시스템 정의의 이벤트 통지의 일람에 대해서는,GetEvent 메소드를 참조할것.

메소드

CancelDefaultHandling | 지정된 이벤트의 필터 그래프에 의한 디폴트 처리를 캔슬한다.
GetEvent | 다음의 통지 이벤트를 취득한다.
GetEventHandle | 통지제가 되는 수동 리셋 이벤트의 핸들을 취득한다.
RestoreDefaultHandling | 이 이벤트의 디폴트 처리를 복원한다.
WaitForCompletion | 필터 그래프의 동작이 완료할 때까지 대기한다.

CancelDefaultHandling 메소드 (IMediaEvent 오브젝트)

IMediaEvent 오브젝트

지정된 이벤트의 필터 그래프에 의한 디폴트 처리를 캔슬해, 이벤트가 어플리케이션에게 건네지도록(듯이) 한다.

구문

objMediaEvent. CancelDefaultHandling lEvCode

지정 항목

objMediaEvent
평가 결과가 IMediaEvent 오브젝트가 되는 오브젝트식.
lEvCode
디폴트 처리를 캔슬하는 이벤트 코드를 지정하는 Long 형의 값. 다음의 값이 유효하다.
  • EC_COMPLETE
  • EC_ERRORABORT
  • EC_PALETTE_CHANGED
  • EC_REPAINT
  • EC_USERABORT

반환값

이 메소드는, 이벤트에 디폴트 처리가 없는 경우에 에러를 생성한다.

주의

현재, 필터 그래프 매니저는,EC_COMPLETE 와 EC_REPAINT 에만 디폴트 처리를 적용한다.

GetEvent 메소드 (IMediaEvent 오브젝트)

IMediaEvent 오브젝트

다음의 통지제이벤트를 취득한다.

구문

objMediaEvent. GetEvent lEventCode, lParam1, lParam2, msTimeout

지정 항목

objMediaEvent
평가 결과가 IMediaEvent 오브젝트가 되는 오브젝트식.
IEventCode
다음의 이벤트 통지를 돌려준다. 이하의 값이 유효하다.
  • EC_COMPLETE
  • EC_ERRORABORT
  • EC_PALETTE_CHANGED
  • EC_REPAINT
  • EC_USERABORT
lParam1
이벤트의 제 1 파라미터를 지정하는 Long 형의 값.
lParam2
이벤트의 제 2 파라미터를 지정하는 Long 형의 값.
msTimeout
이벤트가 없다고 볼 때까지의 밀리 세컨드 단위의 시간. 즉시 종료하려면 , 타임 아웃값을 0 으로 한다.

주의

이 메소드는, 큐의 선두로부터 다음의 이벤트 통지를 삭제해, 그 이벤트 통지를 돌려준다. 이벤트가 없는 경우, 이 메소드는 msTimeout 밀리 세컨드가 경과할 때까지 대기한다.

GetEventHandle 메소드 (IMediaEvent 오브젝트)

IMediaEvent 오브젝트

건네주는 이벤트 통지가 있는 한 통지제가 되는, 수동 리셋 이벤트의 핸들을 돌려준다.

구문

objMediaEvent. GetEventHandle hEvent

지정 항목

objMediaEvent
평가 결과가 IMediaEvent 오브젝트가 되는 오브젝트식.
hEvent
이벤트 핸들이 저장 되는 Long 형의 값.

주의

이벤트를 Win32 WaitForMultipleObjects 함수 또는 MsgWaitForMultipleObjects 함수에 건네주어, 1 개의 thread상에서, 다른 메세지나 이벤트와 동시에, 이벤트 통지를 기다릴 수가 있다.

RestoreDefaultHandling 메소드 (IMediaEvent 오브젝트)

IMediaEvent 오브젝트

지정된 이벤트의 필터 그래프에 의한 보통의 디폴트 처리가 있으면, 그것을 복원한다.

구문

objMediaEvent. RestoreDefaultHandling lEvCode

지정 항목

objMediaEvent
평가 결과가 IMediaEvent 오브젝트가 되는 오브젝트식.
lEvCode
복원하는 이벤트. 다음의 일람은, 시스템 정의 이벤트 통지를 나타내고 있다.
  • EC_COMPLETE
  • EC_ERRORABORT
  • EC_PALETTE_CHANGED
  • EC_REPAINT
  • EC_USERABORT

주의

EC_REPAINT 등과 같이 디폴트 처리가 지정되고 있는 이벤트는, 보통, 어플리케이션에게 건네지지 않는다.

WaitForCompletion 메소드 (IMediaEvent 오브젝트)

IMediaEvent 오브젝트

필터 그래프의 동작이 완료할 때까지 대기한다.

구문

objMediaEvent. WaitForCompletion msTimeout, EvCode

지정 항목

objMediaEvent
평가 결과가 IMediaEvent 오브젝트가 되는 오브젝트식.
msTimeout
타임 아웃의 시간폭을 밀리 세컨드 단위로 지정하는 Long 형의 값. 무기한에 동작을 정지시키려면 , –1 를 건네준다. 즉시 종료시키려면 , 제로를 건네준다.
EvCode
EC_COMPLETE 등의 이벤트 종료 코드의 값이 저장 된 Long 형의 값. 제로는, 동작이 완료하지 않았던 것을 나타낸다.

주의

이 메소드는, 메소드가 EC_COMPLETE 이벤트 통지,EC_ERRORABORT 이벤트 통지, 또는 EC_USERABORT 이벤트 통지를 받는지, 타임 아웃의 기한이 지나는지, 어느 쪽인지가 최초로 일어날 때까지 GetEvent 를 반복해 호출하는 것에 의해, 동작 정지상태태에 머무른다.

타임 아웃의 값에 이르렀을 경우, 메소드는, 종료 코드값 0 을 돌려주어, 「어플리케이션 정의 에러 또는 오브젝트 정의 에러」를 나타내는 실행시 에러 287 을 생성한다. msTimeOut 파라미터를 –1 (무한대) 이외의 값으로 설정 하면, 이 실행시 에러가 발생할 가능성이 있다. On Error Resume Next 스테이트먼트로 이 에러를 처리해,EvCode 의 값을 체크할 수가 있다. 0 은 타임 아웃이 일어난 것을 나타내, 1 (EC_COMPLETE ) 이상의 값은, 동작이 완료하고 있는 것을 나타낸다. 다음의 예는, 타임 아웃을 0 으로 해 이 메소드를 사용하는 것을 나타내고 있다.

Dim pME As IMediaEvent
Dim EventCode As Long
Set pME = pMC

    On Error Resume Next

pME.WaitForCompletion 0, EventCode	'WaitForCompletion 로부터 즉시 돌아온다

    Set pME = Nothing

If EventCode = 0 Then Exit Sub

무기한의 타임 아웃을 사용하려면 , 다음의 예의 같게, 귀가 이벤트 코드 1 을 체크한다.

Dim pME As IMediaEvent
Dim EventCode As Long
Set pME = pMC

pME.WaitForCompletion -1, EventCode	'EC_COMPLETE 까지 대기

If EventCode = 1 Then Exit Sub

메소드가 종료한 시점에서, 필터 그래프는 아직 트랜스폴트 상태가 되어 있다. 이 메소드에서는, 어플리케이션이 IMediaEvent 에의 다른 호출을 실시하지 않은 것과 상정하고 있다. 그래프가 트랜스폴트 상태로 되어 있지 않은 경우, 또는 트랜스폴트 상태에 이행중이 아닌 경우, 이 메소드는 실패한다.


IMediaPosition 오브젝트

필터 그래프는, 그래프내의 몇개의 필터가 시크 가능하면 (스트림내의 임의의 위치를 시크 할 수 있으면),IMediaPosition 오브젝트를 공개한다. 필터가 필터의 데이터를 시크 할 수 있는 경우, 또는, 시크 가능한 스트림을 나타내는출력 핀에 접속되는 경우, 필터는 IMediaPosition 을 공개한다.

필터 그래프와 통신하는 어플리케이션은, 이 인터페이스의 메소드를 호출해, 스트림의 시간폭, 시작 타임과 종료 타임,프리로르타임, 속도, 현재 위치등의 프로퍼티를 설정 또는 취득할 수 있다. 필터 그래프는, 시크 가능한 필터상에서 이러한 프로퍼티를 사용해, 그래프내의 스트림의 재생을 제어한다. 복수의 스트림이 있는 경우, 필터 그래프는, 그것들 모든 것이 같은 위치를 시작 위치로서 병행해 재생되도록(듯이) 설정해, 가장 긴 스트림의 시간폭을 시간폭으로서 보고한다. 이 인터페이스로 사용되는 파라미터는, 소수점값의 초를 나타내는 double 형의 값이다. 필터는, 내부적으로는, 시간을 100 나노초의 정밀도로 저장 한다.

프로퍼티

CurrentPosition | 미디어 스트림 전체의 길이에 대한 현재의 위치를 취득 또는 설정한다.
Duration | 미디어 스트림의 총시간폭을 취득한다.
PrerollTime | 비랜덤 억세스 디바이스가 회전을 시작 할 필요가 있는, 시작 위치보다 전의 위치로부터 시작 위치까지의 시간을 취득 또는 설정한다.
Rate | 미디어 스트림의 표준 재생 속도에 대한 상대적인 재생 속도를 취득 또는 설정한다.
StopTime | 재생을 정지할 필요가 있는 미디어 스트림내의 위치를 취득 또는 설정한다.

메소드

CanSeekBackward | 현재의 스트림을 역방향으로 시크 할 수 있을지 어떨지를 나타내는 값을 취득한다.
CanSeekForward | 현재의 스트림을 순서 방향으로 시크 할 수 있을지 어떨지를 나타내는 값을 취득한다.

CurrentPosition 프로퍼티 (IMediaPosition 오브젝트)

IMediaPosition 오브젝트

미디어 스트림 전체의 길이에 대한 현재의 위치를 취득 또는 설정한다.

구문

objMediaPosition. CurrentPosition [=dblValue]

지정 항목

objMediaPosition
평가 결과가 IMediaPosition 오브젝트가 되는 오브젝트식.
dblValue
새로운 현재 위치를 지정하는 Double 형의 값.

주의

CurrentPosition 프로퍼티는, 현재까지 재생이 달한 위치를 나타낸다. 이 프로퍼티는, 제로와 시간폭의 사이의 값 (속도와 시작 타임에 의해 조정된 값)이 된다. 그래프가 포즈 하고 있는 경우, 이 프로퍼티는, 그래프가 동작을 재개하는 위치를 나타낸다.

이 프로퍼티를 사용해, 시작 타임을 설정할 수도 있다. 그 경우의 현재 위치는,Run 메소드가 불려 갔을 때에 재생을 시작 하는, 제로와 시간폭의 사이의 위치를 나타낸다.

필터 그래프가 정지 또는 포즈 하고 있는 경우, 이 프로퍼티는, 재생을 재개하는 위치를 돌려준다. 필터 그래프가 트랜스폴트 하고 있는 경우, 필터 그래프 매니저는,기준 클락에 따라 위치를 돌려준다. 각각의 필터가 이것을 이행 하는 경우, 필터는, 포즈 또는 트랜스폴트 하고 있을 때, 현재 처리하고 있는 샘플의스트림 타임 (시작 위치로부터의 오프셋(offset) 시간)을 돌려줄 필요가 있다.

정지 또는 포즈 한 후, run 커멘드를 실행 하면, 재생이 현재의 위치로부터 시작 된다. 어플리케이션이 CurrentPosition 호출을 변경하지 않는 한, 이 정도치는, 재생이 정지 또는 포즈 한 위치가 된다.

필터 그래프 매니저가 동작하고 있는 동안에 이 메소드가 불려 가면(자), 필터 그래프 매니저는 그래프를 포즈시켜, 메소드를 실행해, 새로운 run 커멘드를 실행한다.

포즈중 또는 정지중에 현재 위치를 설정 하면, run 커멘드를 실행했을 때에, 새로운 시작 위치로부터 재생이 재개된다.

현재 위치는 속도의 전에 적용되기 (위해)때문에, 보통의 재생 속도에서의 위치가 된다.

Duration 프로퍼티 (IMediaPosition 오브젝트)

IMediaPosition 오브젝트

미디어 스트림의 총시간폭을 취득한다.

구문

objMediaPosition. Duration

지정 항목

objMediaPosition
평가 결과가 IMediaPosition 오브젝트가 되는 오브젝트식.

주의

시간폭은 표준 재생 속도를 전제로 하고 있기 (위해)때문에, 속도의 영향을 받지 않는다.

PrerollTime 프로퍼티 (IMediaPosition 오브젝트)

IMediaPosition 오브젝트

디바이스가 회전을 시작 할 필요가 있는, 시작 위치보다 전의 위치로부터 시작 위치까지의 시간을 취득 또는 설정한다.

구문

objMediaPosition. PrerollTime [=dblValue]

지정 항목

objMediaPosition
평가 결과가 IMediaPosition 오브젝트가 되는 오브젝트식.
dblValue
PrerollTime 프로퍼티를 나타내는 Double 형의 값.

주의

프리로르 시간이란, 테이프 플레이어등의 비랜덤 억세스 디바이스가 회전을 시작 할 필요가 있는, 시작 위치보다 전의 위치로부터 시작 위치까지의 시간의 일로이다.

Rate 프로퍼티 (IMediaPosition 오브젝트)

IMediaPosition 오브젝트

표준 재생 속도에 대한 상대적인 재생 속도를 취득 또는 설정한다.

구문

objMediaPosition. Rate [= dblValue]

지정 항목

objMediaPosition
평가 결과가 IMediaPosition 오브젝트가 되는 오브젝트식.
dblValue
속도의 새로운 값. Double 형.

주의

이 프로퍼티를 이용해, 어플리케이션은, 재생 속도를 표준의 디폴트 재생 속도보다 빠르게 하거나 늦게 하거나 할 수가 있다. 속도 1.0 은 표준 재생 속도를 나타내, 속도 0.5 는 반의 속도를 나타낸다. 또,–1. 0 은, 표준의 역재생 속도를 나타낸다. 2.0 을 지정 하면, 재생 속도는 표준 속도의 2 배가 되어, 리소스가 충분히 있으면, 1 초 쯤 10 프레임 (fps)으로 생성 된 비디오가 20 fps 로 재생된다. 표준 속도보다 빠른 속도로 오디오 스트림을 재생 하면, 샘플은 드롭 되지 않고, 피치가 높아진다. 속도 0.5 는, 반의 속도를 나타낸다.

StopTime 프로퍼티 (IMediaPosition 오브젝트)

IMediaPosition 오브젝트

미디어 스트림이 정지하는 시간을 취득 또는 설정한다.

구문

objMediaPosition. StopTime [ = dblValue]

지정 항목

objMediaPosition
평가 결과가 IMediaPosition 오브젝트가 되는 오브젝트식.
dblValue
종료 타임의 새로운 값.

주의

종료 타임은, 재생이 정지하는, 제로와 미디어의 시간폭의 사이의 위치이다.

정지 위치는 속도의 전에 적용되기 (위해)때문에, 표준 재생 속도에서의 위치가 된다.

CanSeekBackward 메소드 (IMediaPosition 오브젝트)

IMediaPosition 오브젝트

현재의 스트림을 역방향으로 시크 할 수 있을지 어떨지를 나타내는 값을 취득한다.

구문

objMediaPosition. CanSeekBackward

지정 항목

objMediaPosition
평가 결과가 IMediaPosition 오브젝트가 되는 오브젝트식.

주의

반환값은 정수형의 값이다. 값이 0 의 경우, 현재의 스트림은 시크 할 수 없다. 값이 –1 이면, 시크 할 수 있다. 스트림을 시크 할 수 없는 경우에서도,CurrentPosition 로 스트림의 현재 위치를 설정할 수 있다.

이 메소드는, WAV 파일이나 비디오만의 MPEG 파일 등, 미디어 스트림이 1 개의 미디어 타입으로부터 구성되어 있는 경우에게만 –1 (TRUE)를 돌려줄 수가 있다.

CanSeekForward 메소드 (IMediaPosition 오브젝트)

IMediaPosition 오브젝트

현재의 스트림을 순서 방향으로 시크 할 수 있을지 어떨지를 나타내는 값을 취득한다.

구문

objMediaPosition. CanSeekForward

지정 항목

objMediaPosition
평가 결과가 IMediaPosition 오브젝트가 되는 오브젝트식.

주의

반환값은 정수형의 값이다. 값이 0 의 경우, 현재의 스트림은 시크 할 수 없다. 값이 –1 이면, 시크 할 수 있다. 스트림을 시크 할 수 없는 경우에서도,CurrentPosition 로 스트림의 현재 위치를 설정할 수 있다.

이 메소드는, WAV 파일이나 비디오만의 MPEG 파일 등, 미디어 스트림이 1 개의 미디어 타입으로부터 구성되어 있는 경우에게만 –1 (TRUE)를 돌려줄 수가 있다.


IMediaTypeInfo 오브젝트

필터 그래프 매니저는, 메이저 GUID (글로벌하게 일의인 식별자)등의 미디어 타입 정보에의 액세스에 이용할 수 있는 IMediaTypeInfo 를 공개한다.

프로퍼티

Subtype | 서브 타입 GUID 를 캐릭터 라인으로서 취득한다.
Type | 메이저 타입 GUID 를 캐릭터 라인으로서 취득한다.

Subtype 프로퍼티 (IMediaTypeInfo 오브젝트)

IMediaTypeInfo 오브젝트

서브 타입 GUID 를 캐릭터 라인으로서 취득한다.

구문

objMediaTypeInfo. Subtype

지정 항목

objMediaTypeInfo
평가 결과가 IMediaTypeInfo 오브젝트가 되는 오브젝트식.

반환값

서브 타입 GUID 가 저장 된 캐릭터 라인을 돌려준다.

Type 프로퍼티 (IMediaTypeInfo 오브젝트)

IMediaTypeInfo 오브젝트

메이저 타입 GUID 를 캐릭터 라인으로서 취득한다.

구문

objMediaTypeInfo. Type

지정 항목

objMediaTypeInfo
평가 결과가 IMediaTypeInfo 오브젝트가 되는 오브젝트식.

반환값

메이저 타입 GUID 가 저장 된 캐릭터 라인을 돌려준다.


IPinInfo 오브젝트

필터 그래프 매니저는, 미디어 타입, 핀 방향등의 핀 정보에의 액세스에 사용할 수 있는 IPinInfo 오브젝트를 공개한다. 이 오브젝트를 사용해, 접속, 절단, 렌더링등의 핀의 제어를 실시할 수도 있다.

프로퍼티

ConnectedTo | 필터가 접속되고 있는 핀의 IPinInfo 오브젝트를 취득한다.
ConnectionMediaType | 이 접속의 미디어 타입을 취득한다.
Direction | 핀 방향을 취득한다.
FilterInfo | 이 핀이 속하는 필터의 IFilterInfo 오브젝트를 취득한다.
MediaTypes | 우선 미디어 타입의 IAMCollection 오브젝트를 취득한다.
Name | 이 핀의 이름을 취득한다.
Pin | 이 IPinInfo 오브젝트에 관련지을 수 있고 있는 핀을 취득한다.
PinID | 핀 식별자를 취득한다.

메소드

Connect | 다음에 계속되는 핀에 접속한다.
ConnectDirect | 지정된 핀에 직접 접속한다.
ConnectWithType | 지정된 미디어 타입만을 사용해 지정된 핀에 직접 접속한다.
Disconnect | 이 핀과 접속 상대의 핀과의 상호 접속을 절단 한다.
Render | 이 핀의 다운 스트림의 필터 그래프를 생성 한다. 즉, 이 핀으로부터렌더러 필터의 사이에 그래프를 생성하기 위해서 필요하게 되는 모든 필터와 접속을 생성한다.

Connect 메소드 (IPinInfo 오브젝트)

IPinInfo 오브젝트

필요에 따라서변환 필터를 사용해,2 개의 핀을 접속한다.

구문

objPinInfo. Connect objPin

지정 항목

objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.
objPin
접속 상대의 핀을 지정하는 IPinInfo 오브젝트.

ConnectDirect 메소드 (IPinInfo 오브젝트)

IPinInfo 오브젝트

변환 필터를 사용하지 않고 , 2 개의 핀을 직접 접속한다.

구문

objPinInfo. ConnectDirect objPin

지정 항목

objPinInfo
접속 상대의 핀을 지정하는 IPinInfo 오브젝트.
objPin
접속 상대의 핀을 지정하는 IPinInfo 오브젝트.

ConnectedTo 프로퍼티 (IPinInfo 오브젝트)

IPinInfo 오브젝트

필터가 접속되고 있는 핀의 IPinInfo 오브젝트를 취득한다.

구문

Set objConnectedPinInfo = objPinInfo. ConnectedTo

지정 항목

objConnectedPinInfo
핀의 IPinInfo 오브젝트.
objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.

ConnectionMediaType 프로퍼티 (IPinInfo 오브젝트)

IPinInfo 오브젝트

이 접속의 IMediaTypeInfo 오브젝트를 취득한다.

구문

Set objMediaTypeInfo = objPinInfo. ConnectionMediaType

지정 항목

objMediaTypeInfo
새로운 미디어 타입이 저장 되는 IMediaTypeInfo 오브젝트.
objPinInfo
소스 핀을 지정하는 IPinInfo 오브젝트. objMediaTypeInfo 오브젝트는, 이 핀의 미디어 타입을 카피한다.

주의

IMediaTypeInfo 오브젝트에는, 이 핀이 지원 하고 있는메이저 타입과 서브 타입에 관한 정보가 저장 되고 있다.

ConnectWithType 메소드 (IPinInfo 오브젝트)

IPinInfo 오브젝트

지정된 미디어 타입을 사용해 지정된 핀에 직접 접속한다.

구문

objPinInfo. ConnectWithType objPin, objMediaType

지정 항목

objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.
objPin
접속 상대의 핀을 지정하는 IPinInfo 오브젝트.
objMediaType
접속에 사용되는 미디어 타입을 지정하는 값. objMediaType 오브젝트는,IPinInfo 를 지원 할 필요가 있다.

주의

Connect 메소드와 ConnectDirect 메소드를 사용해 핀을 접속할 수도 있다.

Direction 프로퍼티 (IPinInfo 오브젝트)

IPinInfo 오브젝트

핀 방향을 취득한다.

구문

objPinInfo. Direction

지정 항목

objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.

주의

값 0 은 입력을 나타내, 값 1 은 출력을 나타낸다.

Disconnect 메소드 (IPinInfo 오브젝트)

IPinInfo 오브젝트

이 핀과 접속 상대의 핀과의 상호의 접속을 절단 한다.

구문

objPinInfo. Disconnect

지정 항목

objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.

주의

각 핀은, 각각이 대응하는 핀과의 접속을 가지고 있다. 이 메소드는, 양쪽 모두의 핀의 접속을 절단 한다.

FilterInfo 프로퍼티 (IPinInfo 오브젝트)

IPinInfo 오브젝트

현재의 핀이 포함되어 있는 필터의 IFilterInfo 오브젝트를 취득한다.

구문

Set objFilterInfo = objPinInfo. FilterInfo

지정 항목

objFilterInfo
평가 결과가 IFilterInfo 오브젝트가 되는 오브젝트식.
objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.

주의

상세한 것에 대하여는, 「IFilterInfo 」의 참조 항목을 참조할것.

MediaTypes 프로퍼티 (IPinInfo 오브젝트)

IPinInfo 오브젝트

현재의 핀의 우선 미디어 타입을 지정하는 IAMCollection 오브젝트를 취득한다.

구문

Set objCollection = objPinInfo. MediaTypes

지정 항목

objCollection
돌려주어지는 IAMCollection 오브젝트.
objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.

Name 프로퍼티 (IPinInfo 오브젝트)

IPinInfo 오브젝트

이 핀의 이름을 취득한다.

구문

objPinInfo. Name

지정 항목

objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.

Pin 프로퍼티 (IPinInfo 오브젝트)

IPinInfo 오브젝트

IPin 오브젝트를 돌려준다.

구문

Set objPin = objPinInfo. Pin

지정 항목

objPin
취득된 핀이 저장 되는 IPinInfo 오브젝트.
objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.

주의

Visual Basic® 프로그래머가 이용할 수 있는 IPin 의 프로그래밍 가능한 오브젝트 인터페이스는 제공되어 있지 않다. 이 프로퍼티는,IPin 파라미터를 취하는 DLL 로 사용하기 위해(때문에), 및,IPinInfo 오브젝트의 Connect 메소드,ConnectDirect 메소드, 라고 ConnectWithType 메소드에의 호출의 파라미터로서 사용하기 위해서 준비되어 있다.

PinID 프로퍼티 (IPinInfo 오브젝트)

IPinInfo 오브젝트

핀 식별자를 취득한다.

구문

objPinInfo. PinID

지정 항목

objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.

주의

PinID 를 IFilterInfo 오브젝트의 FindPin 메소드에 파라미터로서 건네줄 수가 있다.

Render 메소드 (IPinInfo 오브젝트)

IPinInfo 오브젝트

모든 변환 필터 및 렌더링 필터를 추가해, 필요하게 되는 모든 접속을 확립해, 이소스 필터의출력 핀에 속하는 미디어 타입을 렌더링 할 수 있는 필터 그래프를 생성 한다.

구문

objPinInfo. Render

지정 항목

objPinInfo
평가 결과가 IPinInfo 오브젝트가 되는 오브젝트식.

주의

이 메소드는, 지정된 핀의 다운 스트림으로, 즉 렌더링 필터로 향할 방향으로 필요하게 되는 접속만을 확립한다. 이 메소드는, 모든 핀용의 완전한 필터 그래프를 확립하는 RenderFile 메소드와는 다르다.


IRegFilterInfo 오브젝트

IRegFilterInfo 오브젝트는, 이 컴퓨터에 등록되어 있는 필터에 관한 정보를 제공한다.

프로퍼티

Name 필터의 이름을 취득한다.

메소드

Filter 이 필터의 인스턴스를 생성 해, 그것을 그래프에 추가해, 새롭게 추가된 필터의 IFilterInfo 오브젝트를 돌려준다.

Filter 메소드 (IRegFilterInfo 오브젝트)

IRegFilterInfo 오브젝트

이 필터의 인스턴스를 생성 해, 그것을 그래프에 추가한다.

구문

objRegFilterInfo. Filter objFilterInfo

지정 항목

objRegFilterInfo
평가 결과가 IRegFilterInfo 오브젝트가 되는 오브젝트식.
objFilterInfo
추가하는 필터를 지정하는 IFilterInfo 오브젝트.

Name 프로퍼티 (IRegFilterInfo 오브젝트)

IRegFilterInfo 오브젝트

필터의 이름을 취득한다.

구문

objRegFilterInfo. Name

지정 항목

objRegFilterInfo
평가 결과가 IRegFilterInfo 오브젝트가 되는 오브젝트식.

반환값

등록되어 있는 필터 오브젝트의 이름을 돌려준다.

주의

vender가 필터명을 지정한다.


IVideoWindow 오브젝트

IVideoWindow 오브젝트는, 비디오 렌더러의 비디오 윈도우의 프로퍼티를 지원 한다. 이 오브젝트는, Microsoft® Visual Basic® 및 Microsoft® Visual C++® 를 통해서 액세스 할 수 있는 듀얼 인터페이스이며, 범용 비디오 윈도우를 제어한다. 일반적으로 이 오브젝트는, 디스플레이상의 윈도우내에서 비디오를 드로잉(Drawing) 하는 비디오 렌더러이다.

IVideoWindow 오브젝트는 프로퍼티와 메소드의 양쪽 모두를 지원 한다. 복수의 프로퍼티를 동시에 변경할 필요가 있는 조작에서는, 관련하는 다수의 프로퍼티를 동시에 변경하는 메소드를 이용할 수 있다. 예를 들어, 윈도우의 위치와 사이즈를 설정 하면나무는, 4 개의 다른 프로퍼티를 호출해도 괜찮고,SetWindowPosition 라고 하는 1 개의 메소드를 호출해도 괜찮다.

IVideoWindow 의 프로퍼티와 메소드를 사용하려면 , 비디오 렌더러를 접속할 필요가 있다.

프로퍼티

AutoShow | 최초로 상태가 변화했을 때에 윈도우를 자동적으로 표시할지 어떨지를 지정하는 플래그를 취득 또는 설정한다.
BackgroundPalette | 렌더러가 팔레트를 백그라운드에서 적용할지 어떨지를 나타내는 플래그를 취득 또는 설정한다.
BorderColor | 비디오 윈도우의 경계선의 색을 취득 또는 설정한다.
Caption | 재생 윈도우의 텍스트 캡션을 취득 또는 설정한다.
FullScreenMode | 풀 스크린 모드의 종류를 취득 또는 설정한다.
Height | 비디오 윈도우의 높이를 취득 또는 설정한다.
Left | 비디오 윈도우의 x 축좌표를 취득 또는 설정한다.
MessageDrain | 비디오 윈도우가 메세지의 수신 또는 포스트에 사용하는 윈도우 핸들을 취득 또는 설정한다.
NotifyOwnerMessage | 부모 윈도우가 수신한 메세지를, 필터의 소유하는 자식 윈도우에 전송 한다.
Owner | 비디오 재생 윈도우를 소유하는 부모 윈도우를 취득 또는 설정한다.
Top | 비디오 윈도우의 y 축좌표를 취득 또는 설정한다.
Visible | 윈도우의 표시/비표시 상태를 취득 또는 설정한다.
Width | 비디오 윈도우의 폭을 취득 또는 설정한다.
WindowState | 표시/비표시, 최소화 등, 현재의 윈도우 상태를 취득 또는 설정한다.
WindowStyle | 재생 윈도우의 스타일을 취득 또는 설정한다.
WindowStyleEx | 재생 윈도우의 확장 스타일 비트를 취득 또는 설정한다.

메소드

GetMaxIdealImageSize | 비디오 화면 재생 (클라이언트) 영역의 이상 최대 화면 사이즈를 취득한다.
GetMinIdealImageSize | 비디오 화면 재생 (클라이언트) 영역의 이상 최소 화면 사이즈를 취득한다.
GetRestorePosition | 최대화 및 최소화를 실시할 때, 원의 비디오 윈도우 사이즈를 취득한다.
GetWindowPosition | 비디오 윈도우의 위치를 취득한다.
HideCursor | 커서를 비표시로 한다.
IsCursorHidden | 커서의 표시/비표시 상태를 취득한다.
NotifyOwnerMessage | 필터 그래프의 팔레트 및 색의 변경 메세지를 건네준다.
SetWindowForeground | 비디오 윈도우를 foreground 윈도우로 설정해, 옵션으로 비디오 윈도우에 포커스를 옮긴다.
SetWindowPosition | 디스플레이상의 비디오 윈도우의 위치를 설정한다.

AutoShow 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

윈도우를 자동적으로 표시할지 어떨지의 정보를 취득 또는 설정한다.

구문

objVideoWindow. AutoShow [= boolean]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
boolean
TRUE 는, 상태가 바뀌었을 때에 윈도우가 표시되는 것을 나타낸다.

주의

많은 간단한 어플리케이션에서는, 필터 그래프가 트랜스폴트 상태로 설정되었을 때에 윈도우를 표시할 필요가 있다. 이 프로퍼티는 디폴트로 온 (–1)으로 설정되어 있기 (위해)때문에, 그래프가 포즈 상태로부터 트랜스폴트 상태로 이행하면(자), 윈도우가 표시된다. 윈도우는 동시에 foreground 윈도우로 설정된다. 윈도우를 닫지 않는 이상 그 이후는, 포즈 상태 또는 트랜스폴트 상태로 이행할 때마다 윈도우가 표시된다. 윈도우를 닫았을 경우는, 렌더러가 일단 정지상태태가 될 때까지 윈도우는 표시되지 않는다. 이 프로퍼티를 오프 (0)로 설정 하면, 윈도우를 명시적으로 표시하지 않는 한, 윈도우는 비표시 상태에 머무른다. 윈도우를 명시적으로 표시하려면 Visible 프로퍼티를 설정한다.

BackgroundPalette 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

필요한 팔레트가 백그라운드에서 적용될지 어떨지를 결정한다.

구문

objVideoWindow. BackgroundPalette [= boolean]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
boolean
팔레트가 적용될지 어떨지를 나타내는 플래그.

주의

이 프로퍼티가 TRUE (–1)의 경우, 렌더러는, 필요하게 되는 모든 비디오 팔레트를 백그라운드에서 적용한다. 이것은, 팔레트가 사용하는 모든 색이, 드로잉(Drawing)를 실시하기 전에, 디스플레이 팔레트의 가장 가까운 색으로 변경되는 것을 의미한다. 이것에 의해, 비디오를 재생할 경우에 어플리케이션의 팔레트가 흐트러지지 않는 것이 보증된다. 다만, 이 조작은 비디오에 걸리는 퍼포먼스의 부담이 크기 때문에, 절대로 필요하지 않은 한, 사용하지 않는 것. 이 프로퍼티의 디폴트값은 FALSE (0)이다.

BorderColor 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 경계선의 색을 취득 또는 설정한다.

구문

objVideoWindow. BorderColor [= Color]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
Color
새로운 경계선의 색.

주의

설정되어 있는 전송처 직사각형이 윈도우의 표시 클라이언트 영역과 다른 경우는, 주변부에 경계선이 표시된다. 이 프로퍼티를 이용해, 어플리케이션은, 경계선의 색을 변경할 수 있다. 색은 디폴트에서는 흑으로 설정되어 있다. 시스템 칼라 이외의 색을 건네주면(자), 건네받은 색은, 색을 사용하기 전에, 현재의 팔레트에 따라, 가장 가까운 색에 변환된다. True Color 디바이스에서는 그 필요는 없다. 이 프로퍼티를 설정 하면, 윈도우의 경계선은, 자동적으로 새로운 색으로 재드로잉(Drawing) 된다.

Caption 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 텍스트의 타이틀 캐릭터 라인을 취득 또는 설정한다.

구문

objVideoWindow. Caption [= string]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
string
윈도우의 타이틀 캡션의 새로운 값.

FullScreenMode 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우로 풀 스크린 모드를 사용할지 어떨지를 나타내는 플래그를 취득 또는 설정한다.

구문

objVideoWindow. FullScreenMode [= boolean]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
boolean
새로운 플래그의 값. TRUE 는 풀 스크린 모드를 나타내, FALSE 는 풀 스크린 모드를 사용하지 않는 것을 나타낸다.

GetMaxIdealImageSize 메소드 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 화면 재생 (클라이언트) 영역의 이상 최대 화면 사이즈를 취득한다.

구문

objVideoWindow. GetMaxIdealImageSize Width, Height

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
Width
화면의 폭이 저장 되는 Long 형의 값.
Height
화면의 높이가 저장 되는 Long 형의 값.

GetMinIdealImageSize 메소드 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 화면 재생 (클라이언트) 영역의 이상 최소 화면 사이즈를 취득한다.

구문

objVideoWindow. GetMinIdealImageSize Width, Height

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
Width
화면의 폭이 저장 되는 Long 형의 값.
Height
화면의 높이가 저장 되는 Long 형의 값.

GetRestorePosition 메소드 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

윈도우를 최소화한 후, 바탕으로 되돌리는 경우에, 윈도우의 사이즈와 위치를 취득한다.

구문

objVideoWindow. GetRestorePosition Left, Top, Width, Height

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
Left
비디오 윈도우의 x 축의 원점을 돌려준다.
Top
비디오 윈도우의 y 축의 원점을 돌려준다.
Width
비디오 윈도우의 폭을 돌려준다.
Height
비디오 윈도우의 높이를 돌려준다.

GetWindowPosition 메소드 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

현재의 윈도우 직사각형 (클라이언트 영역은 아니다)을 디바이스의 좌표로 취득한다.

구문

objVideoWindow. GetWindowPosition Left, Top, Width, Height

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
Left
윈도우의 x 축의 원점을 돌려준다.
Top
윈도우의 y 축의 원점을 돌려준다.
Width
윈도우의 폭을 돌려준다.
Height
윈도우의 높이를 돌려준다.

주의

이 메소드에는,Left 프로퍼티,Top 프로퍼티,Width 프로퍼티, 및 Height 프로퍼티를 개별적으로 설정하는 것과 같은 효과가 있다.

Height 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 높이를 취득 또는 설정한다.

구문

objVideoWindow. Height [= lValue]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
lValue
비디오 윈도우의 세로의 길이가 새로운 값.

주의

Height 프로퍼티를 변경해도,Width 프로퍼티 (비디오 윈도우의 y 좌표)는 영향을 받지 않는다.

HideCursor 메소드 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

커서가 비디오 재생 윈도우 위를 통과했을 때에, 커서를 표시할지 어떨지를 지정한다.

구문

objVideoWindow. HideCursor bValue

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
bValue
커서를 표시할지 어떨지를 나타내는불형의 값. TRUE 는 커서를 표시하지 않고, FALSE 는 커서를 표시한다.

주의

보통, 풀 스크린 재생을 사용하는 경우는, 유저가 마음이 산란해지지 않게 커서를 표시하지 않는다.

다음의 코드는, 이 메소드의 사용법을 나타내고 있다.

    Dim o_objVideoWindow As IVideoWindow	'IVideoWindow 오브젝트를 초기화
    Dim g_objMediaControl As IMediaControl	'IMediaControl 오브젝트를 초기화

    Set g_objVideoWindow = g_objMediaControl	'재생 윈도우를
                    '필터 그래프에 할당한다
    g_objVideoWindow.HideCursor (True)	'커서를 비표시로 한다

IsCursorHidden 메소드 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

커서의 표시/비표시 상태를 취득한다.

구문

objVideoWindow. IsCursorHidden bValue

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
bValue
커서의 표시/비표시 상태가 저장 되는불형의 값. 커서가 비표시 상태이면 TRUE, 표시 상태이면 FALSE 가 된다.

주의

보통, 풀 스크린 재생을 사용하는 경우는, 유저가 마음이 산란해지지 않게 커서를 표시하지 않는다.

다음의 코드는, 이 메소드의 사용법을 나타내고 있다.

    Dim o_objVideoWindow As IVideoWindow	'IVideoWindow 오브젝트를 초기화
    Dim g_objMediaControl As IMediaControl	'IMediaControl 오브젝트를 초기화
    Dim bTest As Boolean			'스토리지 변수를 초기화

    Set g_objVideoWindow = g_objMediaControl	'재생 윈도우를
                    '필터 그래프에 할당한다
    g_objVideoWindow.IsCursorHidden (bTest)	'커서가 비표시인가 어떤가를 체크한다

Left 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 x 좌표를 취득 또는 설정한다.

구문

objVideoWindow. Left [= lValue]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
lValue
x 축좌표의 새로운 값.

주의

이 프로퍼티를 호출해도, 비디오 윈도우의 폭은 영향을 받지 않는다.

MessageDrain 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우 앞으로 포스트된 메세지를 받아들이는 윈도우의 윈도우 핸들을 취득 또는 설정한다.

구문

objVideoWindow. MessageDrain [= handle]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
handle
윈도우 핸들의 새로운 값.

NotifyOwnerMessage 메소드 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

부모 윈도우가 수신한 메세지를, 필터가 소유하는 자식 윈도우에 전송 한다.

구문

objVideoWindow. NotifyOwnerMessage hwnd, uMsg, wParam, lParam

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
hwnd
윈도우 핸들.
uMsg
보내지는 메세지.
wParam
메세지의 wParam.
lParam
메세지의 lParam.

Owner 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우를 소유하는 부모를 취득 또는 설정한다.

구문

objVideoWindow. Owner [= handle]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
handle
윈도우 핸들의 새로운 값.

주의

이 프로퍼티를 이용해, 어플리케이션은 비디오 윈도우의 소유자를 설정할 수 있다. 이 기능은, 복합 문서로 비디오를 재생할 경우에 자주(잘) 사용된다.

SetWindowForeground 메소드 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우를 foreground 윈도우로 설정해, 옵션으로 비디오 윈도우에 포커스를 옮긴다.

구문

objVideoWindow. SetWindowForeground Focus

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
Focus
비디오 윈도우에 포커스를 옮길지 어떨지를 지정하는 Long 형의 값. 값 –1 는, 윈도우에 포커스를 옮긴다. 0 은 윈도우에 포커스를 옮기지 않는다.

SetWindowPosition 메소드 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 위치 (클라이언트 직사각형의 위치는 아니다)를 디바이스의 좌표로 설정한다.

구문

objVideoWindow. SetWindowPosition Left, Top, Width, Height

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
Left
윈도우의 x 축의 원점을 지정한다.
Top
윈도우의 y 축의 원점을 지정한다.
Width
윈도우의 폭을 지정한다.
Height
윈도우의 높이를 지정한다.

주의

비디오를 표시하는 위치를 윈도우의 좌표로 지정한다. 예를 들어, 전송처를 (100,50,200,400)로 설정 하면, 비디오 재생 화면은, 클라이언트 영역의 좌단으로부터 100 픽셀, 상단으로부터 50 픽셀의 위치에 원점을 가져, 전체의 사이즈가 200 x 400 픽셀이 된다. 비디오가 이것보다 작은 경우, 또는 비디오보다 작은 전송원직사각형이 지정되고 있는 경우는, 비디오 화면이 표시 영역에 맞추어 확대된다. 같이 비디오가 전송처 직사각형보다 큰 경우, 비디오는 직사각형의 표시 영역에 맞추어 축소된다. 어플리케이션측에서 전송원과 전송처의 직사각형을 같은 사이즈로 하지 않으면 퍼포먼스에 큰 부담이 간다.

전송처 직사각형이 설정되어 있지 않은 표준적인 환경에서는, 유저가 윈도우를 얼마나 확대해도, 비디오는 표시 클라이언트 윈도우 영역 전체를 채운다. 또, 전송처 직사각형의 프로퍼티는, 비디오 윈도우 클라이언트 영역의 사이즈를 올바르게 돌려준다.

이 메소드에는,Left 프로퍼티,Top 프로퍼티,Width 프로퍼티, 및 Height 프로퍼티를 개별적으로 설정하는 것과 같은 효과가 있다.

Top 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 y 축좌표를 취득 또는 설정한다.

구문

objVideoWindow. Top [= lValue]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
lValue
y 축의 원점의 새로운 값.

주의

이 프로퍼티를 호출해도, 비디오 윈도우의 높이는 영향을 받지 않는다.

Visible 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 표시/비표시 상태를 취득 또는 설정한다.

구문

objVideoWindow. Visible [= boolean]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
boolean
TRUE 로 설정되어 있으면(자) 윈도우가 표시된다. FALSE 의 경우, 윈도우는 표시되지 않는다.

Width 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 폭을 취득 또는 설정한다.

구문

objVideoWindow. Width [= lValue]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
lValue
폭의 새로운 값.

주의

Width 프로퍼티는, 비디오 윈도우의 Height 프로퍼티 (x 좌표)와는 무관계하다.

WindowState 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우 상태를 취득 또는 설정한다.

구문

objVideoWindow. WindowState [= lValue]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
lValue
WindowState 프로퍼티의 새로운 값.

WindowStyle 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 스타일 파라미터를 취득 또는 설정한다.

구문

objVideoWindow. WindowStyle [= lValue]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
lValue
WindowStyle 프로퍼티의 새로운 값.

주의

모든 윈도우 스타일의 일람에 대해서는, Microsoft® Platform Software Development Kit (SDK)의 「CreateWindow 함수」를 참조할것.

WindowStyleEx 프로퍼티 (IVideoWindow 오브젝트)

IVideoWindow 오브젝트

비디오 윈도우의 스타일 파라미터를 변경한다.

구문

objVideoWindow. WindowStyleEx [= lValue]

지정 항목

objVideoWindow
평가 결과가 IVideoWindow 오브젝트가 되는 오브젝트식.
lValue
플래그의 새로운 값. 유효한 값은, Microsoft Win32 GetWindowLong 함수의 GWL_STYLE 값에 의해 설정할 수 있는 플래그에 한정된다.


MediaDet 오브젝트

미디어 파일에 관해서, 스트림의 수와 타입, 시간폭, 각 스트림의 frame rate등의 정보를 취득한다. 이 인터페이스에는, 비디오 스트림으로부터 포스터 프레임을 취득하는 메소드도 포함되어 있다.

파일에 관한 정보를 취득하려면 , 이하의 순서를 실행한다.

  1. MediaDet 오브젝트의 새로운 인스턴스를 생성 한다.
  2. Filename 프로퍼티에 원시 파일의 이름을 설정한다.
  3. OutputStreams 프로퍼티로부터, 소스내의 출력 스트림의 수를 취득한다.
  4. CurrentStream 프로퍼티에, 특정의 스트림을 설정한다.
  5. 다음의 프로퍼티의 어느쪽이든을 취득하는 : StreamType ,StreamMediaType ,StreamLength , 또는 FrameRate .

포스터 프레임을 취득하려면 ,WriteBitmapBits 를 호출한다. 이 메소드를 호출하면,MediaDet 오브젝트는비트 맵 글로브 모드라고 하는 새로운 모드로 설정된다. 전술의 정보 취득 메소드는, 이 모드에서는 동작하지 않는다. 그 때문에, 정보의 취득은 포스터 프레임의 취득전에 실시할 필요가 있다. 또는, 스트림 마다 MediaDet 오브젝트의 새로운 인스턴스를 생성 한다.

다음의 코드는, 이 오브젝트의 사용 방법의 예이다.

Dim Det As New MediaDet
Const VideoGUID As String = "{73646976-0000-0010-8000-00AA00389B71}"
bFoundVidStream = False

Det.FileName = "C:\Media\Example.avi"

'비디오 스트림을 검색한다
For i = 0 To Det.OutputStreams - 1
Det.CurrentStream = i
StreamType = Det.StreamTypeB
If StrComp(StreamType, VideoGUID, vbTextCompare) = 0 Then
bFoundVidStream = True
Exit For
End If
Next

If bFoundVidStream Then
'시간폭을 사용해 라벨을 갱신한다
VideoInfo.Caption = Det.FileName + ":" + Str(Det.StreamLength) + " seconds"

'포스터 프레임을 로드한다
TempFile = "C:\Temp.bmp"
Preview.ScaleMode = vbPixels  ' Scale twips to pixels.
Det.WriteBitmapBits 0, Preview.ScaleWidth, Preview.ScaleHeight, TempFile
Preview.Picture = LoadPicture(TempFile)
End If

프로퍼티

CurrentStream | MediaDet 오브젝트가 현재 사용하고 있는 스트림의 수.
Filename | MediaDet 오브젝트가 현재 사용하고 있는 원시 파일의 이름.
Filter | Visual Basic 에서는 지원되어 있지 않다.
OutputStreams | 미디어 소스에 포함되는 출력 스트림의 수.
FrameRate | 현재의 스트림의 frame rate (1 초 쯤의 프레임수).
StreamLength | 현재의 스트림의 시간폭, 단위는 초.
StreamMediaType | Visual Basic 에서는 지원되어 있지 않다.
StreamType | Visual Basic 에서는 지원되어 있지 않다.
StreamTypeB | 현재의 스트림의 미디어 타입의 GUID 를 나타내는 캐릭터 라인.

메소드

EnterBitmapGrabMode | MediaDet 오브젝트를 비트 맵 글로브 모드로 전환해 필터 그래프의 지정의 시간을 시크 한다.
GetBitmapBits | Visual Basic 에서는 지원되어 있지 않다.
GetSampleGrabber | Visual Basic 에서는 지원되어 있지 않다.
WriteBitmapBits | 지정된 미디어 타임의 포스터 프레임을 취득해, 그것을 파일에 기입한다.

CurrentStream 프로퍼티 (MediaDet 오브젝트)

MediaDet 오브젝트

MediaDet 오브젝트가 현재 사용하고 있는 스트림의 수. 읽어내/기입.

구문

object. CurrentStream As Long

파라미터

object
결과가 MediaDet 오브젝트가 되는 오브젝트식.

Filename 프로퍼티 (MediaDet 오브젝트)

MediaDet 오브젝트

MediaDet 오브젝트가 현재 사용하고 있는 원시 파일의 이름. 읽어내/기입.

구문

object. Filename As String

파라미터

object
결과가 MediaDet 오브젝트가 되는 오브젝트식.

Filter 프로퍼티 (MediaDet 오브젝트)

MediaDet 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. Filter As Unknown

FrameRate 프로퍼티 (MediaDet 오브젝트)

MediaDet 오브젝트

현재의 스트림의 frame rate (1 초 쯤의 프레임수). 독해 전용.

구문

object. FrameRate As Double

파라미터

object
결과가 MediaDet 오브젝트가 되는 오브젝트식.

주의

이 스트림은, 비디오 스트림이 아니면 안된다. 이 프로퍼티는, ASF 파일에 대해서는 무효이다. MediaDet 오브젝트가 비트 맵 글로브 모드의 경우, 이 프로퍼티는 무효이다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

이 프로퍼티를 취득하려면 , 먼저 Filename 프로퍼티와 CurrentStream 프로퍼티를 설정해 두지 않으면 안 된다.

OutputStreams 프로퍼티 (MediaDet 오브젝트)

MediaDet 오브젝트

미디어 소스에 포함되는 출력 스트림의 수. 독해 전용.

구문

object. OutputStreams As Long

파라미터

object
결과가 MediaDet 오브젝트가 되는 오브젝트식.

주의

이 프로퍼티를 취득하려면 , 먼저 Filename 프로퍼티를 설정해 두지 않으면 안 된다

MediaDet 오브젝트가 비트 맵 글로브 모드의 경우, 이 프로퍼티는 무효이다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

StreamLength 프로퍼티 (MediaDet 오브젝트)

MediaDet 오브젝트

현재의 스트림의 시간폭, 단위는 초.

구문

object. StreamLength As Double

파라미터

object
결과가 MediaDet 오브젝트가 되는 오브젝트식.

주의

이 프로퍼티를 취득하려면 , 먼저 Filename 프로퍼티와 CurrentStream 프로퍼티를 설정해 두지 않으면 안 된다.

MediaDet 오브젝트가 비트 맵 글로브 모드의 경우, 이 프로퍼티는 무효이다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

StreamMediaType 프로퍼티 (MediaDet 오브젝트)

MediaDet 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. get_StreamMediaType As _AMMediaType

StreamType 프로퍼티 (MediaDet 오브젝트)

MediaDet 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. StreamType As GUID

StreamTypeB 프로퍼티 (MediaDet 오브젝트)

MediaDet 오브젝트

현재의 스트림의 미디어 타입의 GUID 를 나타내는 캐릭터 라인. 독해 전용.

구문

object. StreamTypeB As String

파라미터

object
결과가 MediaDet 오브젝트가 되는 오브젝트식.

주의

캐릭터 라인의 서식은 다음과 같이 설정되어 있는: {73647561-0000-0010-8000-00AA00389B71}.

이 프로퍼티를 취득하려면 , 먼저 Filename 프로퍼티와 CurrentStream 프로퍼티를 설정해 두지 않으면 안 된다. MediaDet 오브젝트가 비트 맵 글로브 모드의 경우, 이 프로퍼티는 무효이다. 상세한 것에 대하여는, 「EnterBitmapGrabMode 」를 참조할것.

EnterBitmapGrabMode 메소드 (MediaDet 오브젝트)

MediaDet 오브젝트

MediaDet 오브젝트를 비트 맵 글로브 모드로 전환해 필터 그래프의 지정의 시간을 시크 한다.

구문

object. EnterBitmapGrabMode(
SeekTime As Double
)

파라미터

object
결과가 MediaDet 오브젝트가 되는 오브젝트식.
SeekTime
그래프를 시크 할 시간 (초단위).

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 무효인 인수.
VFW_E_INVALIDMEDIATYPE | 파일은 비디오 스트림을 가지고 있지 않다.
VFW_E_TIME_EXPIRED | 시크 할 수 없었다.

주의

이 메소드를 호출하려면 , 먼저 Filename 프로퍼티와 CurrentStream 프로퍼티를 설정해 두지 않으면 안 된다.

이 메소드는,샘플 grabber 필터를 필터 그래프에 삽입한다. MediaDet 오브젝트가 비트 맵 글로브 모드가 되었다면,MediaDet 의 각종의 정보 취득 메소드는 기능하지 않는다.

GetBitmapBits 메소드 및 WriteBitmapBits 메소드도, 오브젝트를 비트 맵 글로브 모드로 설정한다.

GetBitmapBits 메소드 (Media 오브젝트)

MediaDet 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetBitmapBits(
StreamTime As Double,
pBufferSize As Long,
pBuffer As Byte,
Width As Long,
Height As Long
)

GetSampleGrabber 메소드 (MediaDet 오브젝트)

MediaDet 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetSampleGrabber(
ppVal As SampleGrabber
)

WriteBitmapBits 메소드 (MediaDet 오브젝트)

MediaDet 오브젝트

지정된 미디어 타임의 포스터 프레임을 취득해, 그것을 파일에 기입한다.

구문

object. WriteBitmapBits(
StreamTime As Double,
Width As Long,
Height As Long,
Filename As String
)

파라미터

object
결과가 MediaDet 오브젝트가 되는 오브젝트식.
StreamTime
포스터 프레임을 취득하는 시간 (초단위).
Width
포스터 프레임 이미지의 폭 (픽셀 단위).
Height
포스터 프레임 이미지의 높이 (픽셀 단위).
Filename
포스터 프레임을 보존하는 파일의 패스. 파일이 이미 존재하는 경우, 이 메소드는 그 파일에 오버라이드(override) 한다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_NOINTERFACE | 샘플 grabber 필터를 그래프에 추가할 수 없었다.
E_FAIL | 실패.
E_OUTOFMEMORY | 메모리 부족.
E_UNEXPECTED | 예기치 않은 에러.
STG_E_ACCESSDENIED | 파일을 오버라이드(override) 할 수 없다.
VFW_E_INVALIDMEDIATYPE | 무효인 미디어 타입.

주의

이 메소드를 호출하려면 , 먼저 Filename 프로퍼티와 CurrentStream 프로퍼티를 설정해 두지 않으면 안 된다.

이 메소드는,MediaDet 오브젝트를 비트 맵 글로브 모드로 설정한다. 이 메소드가 불려 간 후는, 오브젝트의 새로운 인스턴스를 생성 하지 않으면,IMediaDet 의 각종의 스트림 정보 취득 메소드는 기능하지 않는다.


MediaLocator 오브젝트

Microsoft® DirectShow 편집 서비스 (DES)로 파일명의 타당성을 검증하기 위한 메소드를 제공한다. MediaLocator 오브젝트를 사용하면(자), 특정의 파일명과 패스가 기존의 파일에 대응하는 것을 확인할 수 있다. 이 오브젝트는, 다른 장소에 있는 파일을 검색하는 수단, 및 [여는] 다이알로그 박스를 표시해 유저가 파일을 찾을 수 있도록(듯이) 하는 수단도 제공한다.

타임 라인 및 렌더링 엔진도, 다음의 메소드를 통해 파일명의 타당성 검사를 지원 한다.

  • AMTimeline.ValidateSourceNames : 타임 라인내의 파일명을 검증 및 갱신한다.
  • RenderEngine.SetSourceNameValidation : 렌더링 엔진이 렌더링시에 파일명을 검증하는 방법을 지정한다.

보통, DES 어플리케이션은,MediaLocator 오브젝트의 인스턴스를 직접 생성 하는 것이 아니라, 다음의 메소드를 호출한다.

메소드

FindMediaFile | 파일을 검색해, 성공했을 경우는, 그 파일에의 패스를 취득한다.
AddFoundLocation | 디렉토리 캐쉬에 디렉토리를 추가한다.

AddFoundLocation 메소드 (MediaLocator 오브젝트)

MediaLocator 오브젝트

디렉토리 캐쉬에 디렉토리를 추가한다.

구문

object. AddFoundLocation(
DirectoryName As String
)

파라미터

object
결과가 MediaLocator 오브젝트가 되는 오브젝트식.
DirectoryName
캐쉬에 추가하는 디렉토리 패스.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

MediaLocator 오브젝트는, 과거의 검색으로 파일이 발견된 디렉토리 패스의 캐쉬를 유지한다. 파일이 발견되었을 경우는, 그 디렉토리를 캐쉬에 추가한다.

FindMediaFile (MediaLocator 오브젝트)

MediaLocator 오브젝트

파일을 검색해, 성공했을 경우는, 그 파일에의 패스를 취득한다.

구문

object. FindMediaFile(
Input As String,
FilterString As String,
pOutput As String,
Flags As Long
)

파라미터

object
결과가 MediaLocator 오브젝트가 되는 오브젝트식.
Input
파일명. 그 파일이 마지막에 존재하고 있던 것을 알 수 있고 있는 패스도 포함한다. 타임 라인내의 소스 오브젝트의 경우는, 현재의 미디어명을 사용한다.
FilterString
Microsoft® Win32® 의 OPENFILENAME 구조체의 lpstrFilter 멤버로 필요한 서식으로 설정된 필터 캐릭터 라인의 페어를 포함한 캐릭터 라인. 미디어 locator는,[여는] 다이알로그 박스를 표시하는 경우에, 이 필터를 사용한다.
pOutput
파일에의 실제의 패스가 Input 내의 값과 다른 경우, 및 메소드를 파일을 찾아낼 수 있었을 경우, 파일의 실제의 패스를 받는 변수.
Flags
다음의 플래그의 0 개 이상을 비트 마다 조합한 것.
  • SFN_VALIDATEF_NOFIND
  • SFN_VALIDATEF_POPUP
  • SFN_VALIDATEF_TELLME
  • SFN_VALIDATEF_USELOCAL

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_FAIL | 실패.
E_INVALIDARG | 인수가 무효.
E_POINTER | NULL 포인터 인수.

주의

SFN_VALIDATEF_POPUP 플래그가 지정되고 있어, 미디어 locator가 파일을 찾아낼 수 없는 경우, 이 메소드는, 유저가 파일을 찾아낼 수 있도록(듯이) [여는] 다이알로그 박스를 표시한다. 유저가 다이알로그 박스를 캔슬 하면, 메소드에서는 E_FAIL 에러가 발생한다. 어플리케이션에서는,On Error 스테이트먼트를 사용해 이 에러를 획득할 필요가 있다.

If Err.Number = &H80004005 Then
' Did not locate the file.
End If

SFN_VALIDATEF_POPUP 플래그가 지정되지않아서, 미디어 locator가 파일을 찾아낼 수 없는 경우는, 메소드는 다이알로그 박스를 표시하지 않고 E_FAIL 에러를 생성한다.

FilterString 파라미터에 의해 지정되는,[여는] 다이알로그 박스의 필터 캐릭터 라인에는, 내부적인 NULL 캐릭터 라인이 포함된다 (예 : Video\0*.avi\0\0). Chr(0)를 사용해 Null 문자를 지정할 수 있다.

sNullStr = Chr(0)
sFilterStr = "Video" + sNullStr + "*.avi" + sNullStr + sNullStr


RenderEngine 오브젝트

타임 라인으로부터 필터 그래프를 구축하는 것으로써,Microsoft® DirectShow 편집 서비스 (DES) 프로젝트를 렌더링 한다.

DES 에서는, 타임 라인을 렌더링 하는 2 개의 오브젝트가 제공되고 있다.

  • RenderEngine 는, 비압축 포맷의 출력을 생성 한다. 이 출력은, 프리뷰에 사용할 수 있어 또 압축 필터를 경유해 최종 출력 파일의 기입에도 사용할 수 있다.
  • SmartRenderEngine 오브젝트는,스마트재압축을 사용해, 압축된 출력을 생성 한다. 스마트재압축을 사용 하면, 원시 파일의 포맷이 출력 포맷과 다른 경우에게만, 원시 파일이 재압축된다. 소스의 포맷이 일치하고 있을 때는, 출력 파일에 직접 기입해진다. 상황에 따라서는, 스마트재압축을 사용하는 것으로 렌더링 시간을 큰폭으로 개선할 수 있다.

어플리케이션으로 필터 그래프를 생성 해 렌더링 엔진에 건네줄 수도 있지만, 보통의 상황에서는, 렌더링 엔진에 필터 그래프를 생성 시킨다. 그래프의 생성은, 2 단계의 처리로 행해진다. 우선,ConnectFrontEnd 메소드를 호출해 프론트엔드를 구축한다. 다음에, 프론트엔드의 출력 핀을 목적의 렌더링 필터에 접속한다.

  • 프리뷰용의 비디오 렌더러 및 오디오 렌더러, 또는
  • 압력,멀티플렉서, 및 최종 출력을 생성하는 파일 라이터.

메소드

Commit | Visual Basic 에서는 지원되어 있지 않다.
ConnectFrontEnd | 현재의 타임 라인으로부터 필터 그래프의 프론트엔드를 구축한다.
Decommit | Visual Basic 에서는 지원되어 있지 않다.
DoSmartRecompression | Visual Basic 에서는 지원되어 있지 않다.
GetCaps | Visual Basic 에서는 지원되어 있지 않다.
GetFilterGraph | 렌더링 엔진이 구축한 필터 그래프 (있는 경우)를 취득한다.
GetGroupOutputPin | 지정된 그룹의 출력 핀을 취득한다.
GetTimelineObject | 렌더링 엔진이 현재 사용하고 있는 타임 라인을 취득한다.
GetVendorString | 벤더 캐릭터 라인을 취득한다.
RenderOutputPins | 필터 그래프의 프리뷰 부분을 생성 한다.
SetDynamicReconnectLevel | 렌더링시의 동적재접속의 레벨을 설정한다.
SetFilterGraph | 사용하는 렌더링 엔진용의 필터 그래프를 지정한다.
SetInterestRange | Visual Basic 에서는 지원되어 있지 않다.
SetInterestRange2 | Visual Basic 에서는 지원되어 있지 않다.
SetRenderRange | Visual Basic 에서는 지원되어 있지 않다.
SetRenderRange2 | 타임 라인 위에의, 렌더링 되는 시간의 범위를 설정한다.
SetSourceConnectCallback | Visual Basic 에서는 지원되어 있지 않다.
SetSourceNameValidation | 렌더링 엔진이 파일명을 검증하는 방법을 지정한다.
SetTimelineObject | 사용하는 렌더링 엔진용의 타임 라인을 설정한다.
ScrapIt | 렌더링 엔진의 필터 그래프 및 관련 붙일 수 있어 모든 오브젝트를 파기한다.
UseInSmartRecompressionGraph | Visual Basic 에서는 지원되어 있지 않다.

Commit 메소드 (RenderEngine 오브젝트)

RenderEngine 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. Commit()

ConnectFrontEnd (RenderEngine 오브젝트)

RenderEngine 오브젝트

현재의 타임 라인으로부터 필터 그래프의 프론트엔드를 구축한다.

구문

object. ConnectFrontEnd()

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 이 렌더링 엔진에는 타임 라인이 설정되어 있지 않다.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.
E_RENDER_ENGINE_IS_BROKEN | 프로젝트가 올바르고 렌더링 되지 않았기 (위해)때문에, 처리가 실패했다.
E_UNEXPECTED | 예기치 않은 에러.
VFW_E_INVALIDMEDIATYPE | 무효인 미디어 타입.

주의

이 메소드는, 필터 그래프의 렌더링 부분을 구축하지 않는다. 어플리케이션에서는, 프론트엔드의 출력 핀을 목적의 렌더링 필터에 접속해야 한다.

  • 프리뷰를 실시하려면 ,RenderOutputPins 메소드를 호출한다.
  • 파일에 출력하려면 ,GetGroupOutputPin 를 호출해 그룹마다의 출력 핀을 취득하고 나서, 그 핀을 멀티플렉서 필터에 접속한다.

RenderEngine 오브젝트를 사용하고 있는 경우는, 프론트엔드 위에의 출력 핀은 비압축 데이터를 생성한다. SmartRenderEngine 오브젝트를 사용하고 있는 경우는, 출력 핀은 압축 데이터를 출력한다.

필터 그래프를 구축한 다음에 타임 라인을 변경했을 경우는,ConnectFrontEnd 를 한번 더 호출해 프론트엔드를 재구축 해야 한다. 이 메소드는, 가능하면 그래프의 렌더링 부분을 유지한다. 다만, 그룹을 추가 또는 삭제했을 경우, 또는 그룹의 순서를 변경했을 경우는,ConnectFrontEnd 는 렌더링 부분을 삭제하기 위해(때문에), 어플리케이션으로 렌더링 부분을 재구축 해야 한다.

Decommit (RenderEngine 오브젝트)

RenderEngine 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. Decommit()

DoSmartRecompression (RenderEngine 오브젝트)

RenderEngine 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. DoSmartRecompression()

GetCaps (RenderEngine 오브젝트)

RenderEngine 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. GetCaps(
Index As Long,
pReturn As Long
)

GetFilterGraph (RenderEngine 오브젝트)

RenderEngine 오브젝트

렌더링 엔진이 구축한 필터 그래프 (있는 경우)를 취득한다.

구문

object. GetFilterGraph(
ppFG As IGraphBuilder
)

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.
ppFG
필터 그래프를 받는 FilgraphManager 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_MUST_INIT_RENDERER 렌더링 엔진이 초기화에 실패했다.

GetGroupOutputPin (RenderEngine 오브젝트)

RenderEngine 오브젝트

지정된그룹의 출력 핀을 취득한다.

구문

object. GetGroupOutputPin(
Group As Long,
ppRenderPin As IPin
)

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.
Group
그룹을 지정하는, 제로로부터 시작되는 인덱스.
ppRenderPin
출력 핀을 받는 IPin 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 무효인 인수.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.
E_RENDER_ENGINE_IS_BROKEN | 프로젝트가 올바르고 렌더링 되지 않았기 (위해)때문에, 처리가 실패했다.
E_UNEXPECTED | 예기치 않은 에러.

주의

이 메소드를 호출하기 전에,ConnectFrontEnd 를 호출해 그래프의 프론트엔드를 구축한다. 각 그룹은 단일의 미디어 스트림을 나타내, 프론트엔드에는 대응하는 출력 핀이 있다.

이 메소드를 사용해, 파일 기입 그래프의 렌더링 부분을 생성 할 수 있다. 출력 핀을 멀티플렉서 필터 및 파일 라이터 필터에 접속한다. 상세한 것에 대하여는, 「프로젝트의 렌더링」을 참조할것.

프리뷰의 경우는, 이 메소드를 호출할 필요는 없다. 단순하게,ConnectFrontEnd 의 뒤에 RenderOutputPins 를 호출하면 좋다.

GetTimelineObject (RenderEngine 오브젝트)

RenderEngine 오브젝트

렌더링 엔진이 현재 사용하고 있는 타임 라인을 취득한다.

구문

object. GetTimelineObject(
ppTimeline As AMTimeline
)

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.
ppTimeline
타임 라인을 받는 AMTimeline 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_MUST_INIT_RENDERER 렌더링 엔진이 초기화에 실패했다.

GetVendorString (RenderEngine 오브젝트)

RenderEngine 오브젝트

벤더 캐릭터 라인을 취득한다.

구문

object. GetVendorString() As String

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.

반환값

벤더명을 포함한 캐릭터 라인을 돌려준다.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

RenderOutputPins (RenderEngine 오브젝트)

RenderEngine 오브젝트

필터 그래프의 프리뷰 부분을 생성 한다.

구문

object. RenderOutputPins()

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 무효인 인수.
E_RENDER_ENGINE_IS_BROKEN | 프로젝트가 올바르고 렌더링 되지 않았기 (위해)때문에, 처리가 실패했다.
E_UNEXPECTED | 예기치 않은 에러.

주의

이 메소드를 호출하기 전에,ConnectFrontEnd 를 호출해 그래프의 프론트엔드를 구축한다. 프리뷰 이외의 처리를 실시하는 경우는, 이 메소드를 호출해서는 안 된다. 대신에,GetGroupOutputPin 를 호출해 출력 핀에의 포인터를 취득한다.

ScrapIt (RenderEngine 오브젝트)

RenderEngine 오브젝트

렌더링 엔진의 필터 그래프 및 관련 붙일 수 있어 모든 오브젝트를 파기한다.

구문

object. ScrapIt()

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_MUST_INIT_RENDERER 렌더링 엔진이 초기화에 실패했다.

SetDynamicReconnectLevel (RenderEngine 오브젝트)

RenderEngine 오브젝트

렌더링시의 동적재접속의 레벨을 설정한다.

구문

object. SetDynamicReconnectLevel(
Level As Long
)

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.
Level
0 개 이상의동적재접속 플래그의 비트마다의 편성. 동적재접속의 레벨을 지정한다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_NOTIMPL 이행되어 있지 않다.

주의

디폴트에서는,RenderEngine 오브젝트는 프로젝트를 렌더링 하기 전에 모든 소스를 로드한다. 이 때문에, 기동 시간이 길어지는 일이 있다. 동적재접속을 사용 하면, 소스는 필요한 때에게만 로드 된다. 이것에 의해 기동 시간은 짧아지지만, 스무스한 재생을 방해할 수 있는 일이 있다. 일반적으로, 프로젝트로 사용하는 소스 클립이 많을 정도(수록), 동적재접속을 사용하는 메리트는 크다.

SmartRenderEngine 오브젝트는, 이 메소드를 이행 하고 있지 않다.

SetFilterGraph (RenderEngine 오브젝트)

RenderEngine 오브젝트

사용하는 렌더링 엔진용의 필터 그래프를 지정한다.

구문

object. SetFilterGraph(
pFG As IGraphBuilder
)

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.
pFG
필터 그래프를 지정하는 FilgraphManager 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 무효인 인수.
E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.

주의

대부분의 어플리케이션에서는 이 메소드를 호출할 필요는 없다. 보다 일반적인 방법은,ConnectFrontEnd 메소드를 호출하는 것으로, 렌더링 엔진에 그래프를 구축시키는 것이다.

렌더링 엔진에 이미 필터 그래프가 있는 경우, 이 메소드는 실패한다.

렌더링 엔진이 생성 한 필터 그래프를 취득해, 그것을 파라미터로서 다른 렌더링 엔진으로 이 메소드를 호출해서는 안 된다. 그것을 실시하면, 예측할 수 없는 결과가 된다.

SetInterestRange (RenderEngine 오브젝트)

RenderEngine 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetInterestRange(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetInterestRange2 (RenderEngine 오브젝트)

RenderEngine 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetInterestRange2(
double Start As Double,
double Stop As Double
)

SetRenderRange (RenderEngine 오브젝트)

RenderEngine 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetRenderRange(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetRenderRange2 (RenderEngine 오브젝트)

RenderEngine 오브젝트

타임 라인 위에의, 렌더링 되는 시간의 범위를 설정한다. 지정된 범위의 밖에 있는 오브젝트는 렌더링 되지 않고, 그것들에 대해서 리소스는 할당할 수 없다.

구문

object. SetRenderRange2(
Start As Double,
Stop As Double
)

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.
Start
시작 타임 (초단위).
Stop
종료 타임 (초단위).

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_MUST_INIT_RENDERER 렌더링 엔진이 초기화에 실패했다.

SetSourceConnectCallback (RenderEngine 오브젝트)

RenderEngine 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. SetSourceConnectCallback(
pCallback As IGrfCache
)

SetSourceNameValidation (RenderEngine 오브젝트)

RenderEngine 오브젝트

렌더링 엔진이 파일명을 검증하는 방법을 지정한다.

구문

object. SetSourceNameValidation(
FilterString As String,
pOverride As MediaLocator,
Flags As Long
)

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.
FilterString
Microsoft® Win32® 의 OPENFILENAME 구조체의 lpstrFilter 멤버로 필요한 서식으로 설정된 필터 캐릭터 라인의 페어를 포함한 캐릭터 라인. 미디어 locator는,[여는] 다이알로그 박스를 표시하는 경우에, 이 필터를 사용한다.
pOverride
생략 가능. 디폴트 대신에 사용하는 MediaLocator 오브젝트. 디폴트의 미디어 locator를 사용하는 경우는, 이 파라미터를 NULL 로 설정한다. 상세한 것에 대하여는, 「주의」를 참조할것.
Flags
MediaLocator 오브젝트의 동작을 지정하는플래그의 비트마다의 편성. SFN_VALIDATEF_CHECK 플래그는, 반드시 설정되어 있지 않으면 안 된다. SFN_VALIDATEF_IGNOREMUTED 플래그는, 이 메소드에서는 의미를 가지지 않는다.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_MUST_INIT_RENDERER 렌더링 엔진이 초기화에 실패했다.

주의

pOverride 파라미터를 사용 하면,MediaLocator 오브젝트의 독자적인 커스텀 이행을 사용할 수 있다.

현재, 이 메소드는 동적으로 로드 된 소스를 검증하지 않는다. 상세한 것에 대하여는, 「SetDynamicReconnectLevel 」를 참조할것.

SetTimelineObject (RenderEngine 오브젝트)

RenderEngine 오브젝트

사용하는 렌더링 엔진용의 타임 라인을 설정한다.

구문

object. SetTimelineObject(
pTimeline As AMTimeline
)

파라미터

object
결과가 RenderEngine 오브젝트가 되는 오브젝트식.
pTimeline
타임 라인을 지정하는 AMTimeline 오브젝트.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_MUST_INIT_RENDERER | 렌더링 엔진이 초기화에 실패했다.
E_OUTOFMEMORY | 메모리 부족.

UseInSmartRecompressionGraph (RenderEngine 오브젝트)

RenderEngine 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. UseInSmartRecompressionGraph()


Xml2Dex 오브젝트

Microsoft® DirectShow® 편집 서비스 (DES)의, 확장 가능 마크업 언어 (XML)로 기술된 프로젝트 파일의 보존과 로드를 실시한다.

필요 사항

Internet Explore 4.0 이후가 필요.

메소드

CopyXML | Visual Basic 에서는 지원되어 있지 않다.
CreateGraphFromFile | Visual Basic 에서는 지원되어 있지 않다.
Delete | Visual Basic 에서는 지원되어 있지 않다.
PasteXML | Visual Basic 에서는 지원되어 있지 않다.
PasteXMLFile | Visual Basic 에서는 지원되어 있지 않다.
ReadXML | Visual Basic 에서는 지원되어 있지 않다.
ReadXMLFile | XML 프로젝트 파일을 로드한다.
Reset | Visual Basic 에서는 지원되어 있지 않다.
WriteGrfFile | 필터 그래프를 . grf 포맷으로 파일에 기입한다.
WriteXML | 타임 라인을 XML 캐릭터 라인으로 변환한다.
WriteXMLFile | 타임 라인을 XML 로 변환해, XML 데이터를 파일에 기입한다.
WriteXMLPart | Visual Basic 에서는 지원되어 있지 않다.

CopyXML 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. CopyXML(
pTimeline As Unknown,
dStart As Double,
dEnd As Double
)

CreateGraphFromFile 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. CreateGraphFromFile(
ppGraph As Unknown,
pTimeline As Unknown,
FileName As String
)

Delete 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. Delete(
pTimeline As Unknown,
dStart As Double,
dEnd As Double
)

PasteXML 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. PasteXML(
pTimeline As Unknown,
dStart As Double
)

PasteXMLFile 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. PasteXMLFile(
pTimeline As Unknown,
dStart As Double,
FileName As String
)

ReadXML 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. ReadXML(
pXML As Unknown
)

ReadXMLFile 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

XML 프로젝트 파일을 로드한다. 이 메소드는, XML 파일로 표현 떠날 수 있어 모든 오브젝트의 인스턴스를 생성 해, 타임 라인에 삽입한다. 또, frame rate나 디폴트 이펙트 등, 타임 라인에 대해서 지정되고 있는 속성을 적용한다.

구문

object. ReadXMLFile(
pTimeline As Unknown,
XMLName As String
)

파라미터

object
결과가 Xml2Dex 오브젝트가 되는 오브젝트식.
pTimeline
타임 라인을 받는 AMTimeline 오브젝트.
XMLName
로드하는 파일의 이름을 지정하는 캐릭터 라인.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

VFW_E_INVALID_FILE_FORMAT 무효인 파일 포맷.

주의

pTimeline 파라미터는, Microsoft® Visual Basic® 의 오브젝트 브라우저에서는 Unknown 타입으로서 표시된다. 다만, 실제로는, 이 파라미터는 AMTimeline 오브젝트를 나타내고 있다. 다음의 코드는, 이 메소드의 호출 방법의 예이다.

Dim objTimeline as New AMTimeline
Dim objXmlParse as New Xml2Dex
objXmlParse.ReadXMLFile objTimeline, "C:\XTL\Example.xtl"

이 메소드는, XML 파일로 정의되고 있는 새로운 오브젝트를 타임 라인에 삽입하기 전에, 타임 라인으로부터 기존의 오브젝트를 클리어 하지 않는다. 기존의 타임 라인을 갱신할 필요가 있는 경우는, 먼저 IAMTimeline.ClearAllGroups 를 호출한다.

Reset 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. Reset()

WriteGrfFile 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

필터 그래프를 . grf 포맷으로 파일에 기입한다.

구문

object. WriteGrfFile(
pGraph As Unknown,
FileName As String
)

파라미터

object
결과가 Xml2Dex 오브젝트가 되는 오브젝트식.
pGraph
필터 그래프를 지정하는 FilgraphManager 오브젝트.
FileName
기입하는 파일의 이름을 지정하는 캐릭터 라인.

에러 코드

메소드에서의 처리가 실패 하면, 에러가 발생한다.

주의

pGraph 파라미터는, Microsoft® Visual Basic® 의 오브젝트 브라우저에서는 Unknown 타입으로서 표시된다. 다만, 실제로는, 이 파라미터는 FilgraphManager 오브젝트를 나타내고 있다. GraphEdit 파일은, 디버그에서의 사용만을 목적으로 한 것이다. 상세한 것에 대하여는, 「GraphEdit 에 의한 그래프 구축의 시뮬레이션」을 참조할것.

WriteXML 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

타임 라인을 XML 캐릭터 라인으로 변환한다.

구문

object. WriteXML(
pTimeline As Unknown,
pbstrXML As String
)

파라미터

object
결과가 Xml2Dex 오브젝트가 되는 오브젝트식.
pTimeline
타임 라인을 지정하는 AMTimeline 오브젝트.
pbstrXML
변환된 XML 캐릭터 라인을 받는 변수.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 값이 설정되는 경우가 있다.

E_OUTOFMEMORY 메모리 부족.

주의

pTimeline 파라미터는, Microsoft® Visual Basic® 의 오브젝트 브라우저에서는 Unknown 타입으로서 표시된다. 다만, 실제로는, 이 파라미터는 AMTimeline 오브젝트를 나타내고 있다. 다음의 코드는, 이 메소드의 호출 방법의 예이다.

Dim objTimeline As New AMTimeline
'타임 라인을 생성 한다 (생략)

Dim objXmlParser As New Xml2Dex
Dim sXml As String
objXmlParser.WriteXml objTimeline, sXml

WriteXMLFile 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

타임 라인을 XML 로 변환해, XML 데이터를 파일에 기입한다.

구문

object. WriteXMLFile(
pTimeline As Unknown,
FileName As String
)

파라미터

object
결과가 Xml2Dex 오브젝트가 되는 오브젝트식.
pTimeline
타임 라인을 지정하는 AMTimeline 오브젝트.
FileName
기입하는 파일의 이름을 지정하는 캐릭터 라인.

에러 코드

메소드에서의 처리가 실패 하면 에러가 발생해,Err.Number 에는 다음의 몇개의 값이 설정되는 경우가 있다.

E_INVALIDARG | 무효인 인수.
E_OUTOFMEMORY | 메모리 부족.

주의

이 메소드는, 타임 라인내의 모든 컴퍼넌트를 나타내는 XML 파일을 생성한다.

pTimeline 파라미터는, Microsoft® Visual Basic® 의 오브젝트 브라우저에서는 Unknown 타입으로서 표시된다. 다만, 실제로는, 이 파라미터는 AMTimeline 오브젝트를 나타내고 있다. 다음의 코드는, 이 메소드의 호출 방법의 예이다.

Dim objTimeline As New AMTimeline
'타임 라인을 생성 한다 (생략)

Dim objXmlParser As New Xml2Dex
objXmlParser.WriteXmlFile objTimeline, "C:\XTL\Example.xtl"

WriteXMLPart 메소드 (Xml2Dex 오브젝트)

Xml2Dex 오브젝트

Visual Basic 에서는 지원되어 있지 않다.

구문

object. WriteXMLPart(
pTimeline As Unknown,
dStart As Double,
dEnd As Double,
FileName As String
)


관련 정보

_CrtSetDbgFlag
_crtDbgFlag 플래그 상태를 취득 또는 변경해, 디버그 heap 매니저의 할당 동작을 제어한다 (디버그 버젼만). 상세한 것에 대하여는, Microsoft® Visual C++® 의 문서를 참조할것.
BitBlt
BitBlt 함수는, 지정된 전송원디바이스 콘텍스트로부터 전송처 디바이스 콘텍스트에, 픽셀의 직사각형을 나타내는 칼라 데이터의 비트 블록 전송을 실시한다. 상세한 것에 대하여는, Microsoft Platform SDK 의 문서를 참조할것.
biHeight
픽셀 단위로 비트 맵의 높이를 지정하는 BITMAPINFOHEADER 구조체의 데이터 멤버. biHeight 가 정의 값이면, 비트 맵은, 왼쪽 하단 모서리에 원점을 가지는 보텀 업 DIB (디바이스에 의존하지 않는 비트 맵)이다. biHeight 가 부의 값이면, 비트 맵은, 좌상구석에 원점을 가지는 탑 다운 DIB 이다.
biWidth
픽셀 단위로 비트 맵의 폭을 지정하는 BITMAPINFOHEADER 구조체의 데이터 멤버.
CAUUID
UUID 타입 또는 GUID 타입의 카운트 배열을 정의하는 구조체. 배열의 크기를 지정하는 cElems 멤버와 배열을 가리키는 포인터가 저장 되고 있는 pElems 멤버의 2 개의 멤버를 가진다. 상세한 것에 대하여는, Platform SDK 를 참조할것.
CClassFactory
IClassFactory 인터페이스를 이행 하는 클래스. IClassFactory 인터페이스에는, 오브젝트의 클래스 전체를 처리하기 위한 2 개의 메소드가 포함되어 있기 (위해)때문에, 이 인터페이스는, CLSID 에 의해 식별되는 오브젝트의 특정의 클래스에 대응하는 클래스 오브젝트에 이행 된다. 최초의 메소드 CreateInstance 는, 지정된 CLSID 의 초기화되어 있지 않은 오브젝트를 생성 해, 2 번째의 LockServer 는, 메모리내의 오브젝트의 서버를 잠그어, 새로운 오브젝트를 재빠르게 생성 할 수 있도록(듯이) 한다. 상세한 것에 대하여는, Platform SDK 의 IClassFactory 인터페이스의 문서를 참조할것.
클래스 팩토리
IClassFactory 인터페이스를 이행 해, 특정의 CLSID (클래스 식별자)에 의해 식별되는 오브젝트의 1 개 이상의 인스턴스를 생성 하는 COM 오브젝트. 상세한 것에 대하여는, 「CClassFactory 」 및 「IClassFactory 」를 참조할것.
CoCreateInstance
지정된 CLSID 에 관련지을 수 있었던 클래스의 초기화되지 않은 1 개의 오브젝트를 생성 한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CoGetClassObject
지정된 CLSID 에 관련지을 수 있었던 클래스 오브젝트의 인터페이스에의 포인터를 제공한다. CoGetClassObject 는, 이것을 실시하기 위해서(때문에) 필요한 실행 모듈 코드를 검색해, 필요에 따라서, 그 코드를 동적으로 로드한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CoInitialize
COM (Component Object Model) 라이브러리를 초기화한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
COLORREF
RGB 칼라를 지정할 경우에 사용하는 32 비트값. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CoTaskMemAlloc
IMalloc::Alloc 와 같은 방법으로 태스크 메모리의 블록을 할당한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CoTaskMemFree
CoTaskMemAlloc 함수 또는 CoTaskMemRealloc 함수에의 호출에 의해 이전 할당할 수 있었던 태스크 메모리의 블록을 해방한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CreateDIBSection
어플리케이션이 직접 기입할 수 있는 DIB (디바이스에 의존하지 않는 비트 맵)를 생성 한다. 이 함수는, 비트 맵의 비트값의 장소를 가리키는 포인터를 제공한다. 함수가 비트 맵의 생성에 사용하는 파일 매핑 오브젝트에의 핸들을 건네주어도 괜찮고, 비트 맵용의 메모리의 할당을 operating system에 맡겨도 괜찮다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CreateEvent
이름 첨부 이벤트 오브젝트 또는 이름이 없는 이벤트 오브젝트를 생성 한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CreateFile
다양한 오브젝트를 생성 또는 오픈해, 오브젝트에의 액세스에 사용할 수 있는 핸들을 돌려준다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CreateWindow
겹치는 윈도우, pop-up 윈도우, 또는 자식 윈도우를 생성 한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CreateWindowEx
확장 스타일을 가지는, 겹치는 윈도우, pop-up 윈도우, 또는 자식 윈도우를 생성 한다. 그 이외의 점에 대해서는, 이 함수는 CreateWindow 함수와 같다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
CRITICAL_SECTION
1 개의 프로세스의 thread를 동기 시킬 때 사용하는 오브젝트인 크리티컬 섹션 오브젝트. 동시에 1 개의 thread만이 크리티컬 섹션 오브젝트를 소유할 수 있다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
DDCOLORCONTROL
DirectDrawVideoPort 오브젝트, 오버레이 표면, 또는프라이머리 표면에 관련지을 수 있었던 칼라 컨트롤을 정의하는 구조체. 상세한 것에 대하여는, DirectX SDK 의 문서를 참조할것.
DDPIXELFORMAT
IDirectDrawSurface3::GetPixelFormat 메소드용으로 DirectDrawSurface 오브젝트의 픽셀 포맷을 기술하는 구조체. 상세한 것에 대하여는, DirectX SDK 의 DirectShow 의 문서를 참조할것.
DDSCAPS
DirectDrawSurface 오브젝트의 기능을 정의하는 구조체. 이 구조체는, DirectDraw 오브젝트의 기능의 정의에 사용되는 DDCAPS 구조체의 일부이다. 상세한 것에 대하여는, DirectX SDK 의 DirectShow 의 문서를 참조할것.
DDSURFACEDESC
생성 되는 표면에 관한 기술이 포함되어 있는 구조체. 이 구조체는 IDirectDraw2::CreateSurface 메소드에게 건네진다. 표면을 사용 가능한 종류에 의해 관련 멤버는 다르다. 상세한 것에 대하여는, DirectX SDK 의 DirectShow 의 문서를 참조할것.
DDVIDEOPORTCONNECT
비디오 포토 접속을 기술하는 구조체. 상세한 것에 대하여는, DirectX SDK 의 문서를 참조할것.
DefWindowProc
어플리케이션이 처리하지 않는 모든 윈도우 메세지의 디폴트 처리를 실시하기 위해서(때문에) 디폴트의 윈도우 프로시저를 호출하는 멤버 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
DIBSECTION
CreateDIBSection 함수를 호출하는 것에 의해 생성 된, 디바이스에 의존하지 않는 비트 맵에 관한 정보가 포함되어 있는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
DirectDrawSurface
화면이 다른 표면으로 이동할 때 모니터에 표시되는 데이터가 저장 되고 있는 메모리내의 영역을 나타내는 오브젝트. 상세한 것에 대하여는, DirectX SDK 의 「DirectDraw Essentials」섹션의 「Surfaces」를 참조할것.
DISPPARAMS
IDispatch::Invoke 및 CBasicAudio::Invoke 가, 메소드 또는 프로퍼티에게 건네지는 파라미터를 저장 하기 위해서 사용하는 구조체. CDispParams 클래스는 이 구조체를 이행 한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
DllCanUnloadNow
이 함수를 이행 하는 DLL 가 사용중일지 어떨지를 판별하는 함수. 사용중이 아닌 경우, 호출원래는, DLL 를 안전하게 메모리로부터 언로드할 수 있다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
DllGetClassObject
C++ 파일 및 스트림 핸들이 핸들러의 인스턴스를 생성 할 경우에 사용하는 엔트리 포인트가 되는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
DllRegisterServer
이 서버 모듈로 지원 떠날 수 있어 모든 클래스에 대응하는 인 프로세스 서버의 레지스트리 엔트리를 생성 하도록(듯이) 인 프로세스 서버에 지시하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
DllUnregisterServer
DllRegisterServer 를 사용해 생성 된 엔트리만을 삭제하도록(듯이) 인 프로세스 서버에 지시하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
Err 오브젝트
실행시 에러에 관한 정보가 저장 되는 Visual Basic 오브젝트. 실행시 에러가 발생 하면, 에러를 식별하는 정보가 Err 오브젝트의 프로퍼티에 저장 된다. Visual Basic 코드로 실행시 에러를 생성하려면 ,Raise 메소드를 사용한다. 상세한 것에 대하여는, Microsoft® Visual Basic® 의 문서를 참조할것.
FILETIME
파일의 부호 없음 64 비트 일자 시각값이 저장 되는 구조체. 이 값은, 1601 년 1 월 1일을 기점으로 하는 100 나노초단위의 수에 상당한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
FOURCC
RIFF (Resource Interchange File Format) 체크를 식별하기 위해서 사용되는 4 문자의 코드. FOURCC 는, 연속하는 1 개에서 4 개의 ASCII 영문자의 우측의 자리수를 공백 몬지에서 묻은 32 비트의 수량이다. RIFF 는, 멀티미디어 파일의 표준 포맷을 정의할 경우에 사용하는 표준이며, 파일 포맷의 정의가 때와 함께 변화할 경우에 자주(잘) 일어나는 호환성의 문제를 방지하는 역할을 담당한다. 파일내의 각각의 데이터는 표준 헤더에 의해 식별되기 (위해)때문에, 특정의 데이터 요소를 인식하지 않는 어플리케이션은, 미지의 정보를 스킵 할 수 있다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
GdiFlush
호출원thread의 현재의 배치를 플래시 하는 함수. 일괄처리를 실시하는 것으로, 불리언 값을 돌려주는 GDI 드로잉(Drawing) 함수의 호출에 필요한 시간이 최소한으로 억제 당해 드로잉(Drawing) 퍼포먼스가 향상한다.
GetClassFile
특정의 파일명에 관련지을 수 있었던 CLSID 를 공급하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
GetClientRect
윈도우의 클라이언트 영역의 좌표를 취득하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
GetLastError
호출원thread의 최신의 에러 코드값을 돌려주는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
GetSystemPaletteEntries
지정된 디바이스 콘텍스트에 관련지을 수 있었던 시스템 팔레트로부터, 어느 범위의 팔레트 엔트리를 취득하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
GetWindowLong
지정된 윈도우에 관한 정보를 취득하는 함수. 또, 윈도우의 여분의 윈도우 메모리내의 지정된 오프셋(offset)에 있는 32 비트 (long 형) 값도 취득한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
GUID
인터페이스나 PID 등의 오브젝트를 일의에 식별하기 위해서 사용되는 글로벌하게 일의인 식별자. 클래스 식별자 (CLSID) 및 인터페이스 식별자 (IID)는 GUID 이다. Platform SDK 에 부속의 커멘드 라인 유틸리티 UUIDGEN 를 사용해, 또는 Microsoft Visual C++® 에 부속의 Microsoft Foundation Class 라이브러리 (MFC)의 샘플 어플리케이션 GUIDGEN 를 사용해, GUID 를 생성할 수 있다.
HBITMAP
비트 맵의 핸들. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
Win32 HRESULT
인터페이스에의 함수 호출로부터 돌려주어지는 값으로, 중대도 코드, 문맥 정보, 퍼실리티 코드, 및 결과를 설명하는 상태 코드로부터 구성된다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IBindCtx
특정의 moniker 바인드 조작에 관한 정보가 저장 되는 오브젝트인 바인드콘테키스트에의 액세스를 제공하는 인터페이스. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
ICAbout
비디오 압축 드라이버에, 드라이버의 버젼 정보를 표시하도록(듯이) 통지하는 매크로. 상세한 것에 대하여는, 「Video for Windows Development Kit Version 1.1」을 참조할것.
ICConfigure
비디오 압축 드라이버에, 드라이버의 구성 다이알로그 박스를 표시하도록(듯이) 통지하는 매크로. 상세한 것에 대하여는, 「Video for Windows Development Kit Version 1.1」을 참조할것.
IClassFactory
오브젝트의 클래스 전체를 처리하기 위한 2 개의 메소드가 포함된 인터페이스. 따라서, 이 인터페이스는, CLSID 에 의해 식별되는 오브젝트의 특정의 클래스에 대응하는 클래스 오브젝트에 이행 된다. 최초의 메소드 CreateInstance 는, 지정된 CLSID 의 초기화되어 있지 않은 오브젝트를 생성 해, 2 번째의 LockServer 는, 메모리내의 오브젝트의 서버를 잠그어, 새로운 오브젝트를 재빠르게 생성 할 수 있도록(듯이) 한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IClassFactory::CreateInstance
초기화되어 있지 않은 오브젝트를 생성 하는 메소드. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
ICSendMessage
압력에 메세지를 보내는 함수. 상세한 것에 대하여는, 「Video for Windows Development Kit Version 1.1」을 참조할것.
ICGetState
비디오 압축 드라이버를 조회해, 메모리 블록내의 현재의 드라이버의 구성을 돌려주도록(듯이) 요구하는 매크로. 이 매크로를 사용하는 일도, 명시적으로 ICM_GETSTATE 메세지를 호출할 수도 있다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IDirectDraw
어플리케이션은, 이 인터페이스의 메소드를 사용해 DirectDraw 오브젝트를 생성 해, 시스템 레벨의 변수를 조작한다. 상세한 것에 대하여는, DirectX SDK 를 참조할것.
IDirectDraw2
어플리케이션은, 이 인터페이스의 메소드를 사용해 DirectDraw 오브젝트를 생성 해, 시스템 레벨의 변수를 조작한다. 상세한 것에 대하여는, DirectX SDK 를 참조할것.
IDirectSound
어플리케이션은 이 인터페이스의 메소드를 사용해 DirectSound 오브젝트를 생성 해, 환경을 설정한다. 상세한 것에 대하여는, DirectX SDK 를 참조할것.
IDirectSoundBuffer
어플리케이션은 이 인터페이스의 메소드를 사용해 DirectSoundBuffer 오브젝트를 생성 해, 환경을 설정한다. 상세한 것에 대하여는, DirectX SDK 를 참조할것.
IDispatch
Automation 프로그래밍 툴 및 그 외의 어플리케이션에 대해서 오브젝트, 메소드, 및 프로퍼티를 공개하는 인터페이스. IDispatch 로부터 파생하는 듀얼 인터페이스는, Automation 대응 타입만을 사용한다. IDispatch 인터페이스와 같게, 듀얼 인터페이스는, 사전 바인딩 및 실행시 바인딩을 지원 한다. 다만, 듀얼 인터페이스는, 함수 테이블 바인딩도 지원 하는 점이 다르다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IEnumMoniker
모니카의 컴퍼넌트를 열거하기 위해(때문에), 또는 모니카의 테이블내의 모니카를 열거하기 위해서 사용하는 인터페이스. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IEnumVARIANT
콜렉션 오브젝트에 대한 반복의 수단을 제공하는 디스팟치인타페이스. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IEnumXXXX
열거 인터페이스세트. 이것을 이용해, 오브젝트가 관리하는 특정의 타입의 아이템의 수를 열거할 수가 있다. 아이템의 타입 마다 1 개의 인터페이스가 있다. 이러한 인터페이스를 사용할 때는, 클라이언트가, 아이템의 콜렉션을 관리하는 오브젝트에 대해서 열거자 오브젝트를 생성 하도록(듯이) 요구한다. 열거 오브젝트의 인터페이스는, 열거 인터페이스의 1 개이며, 모든 것이 IEnumItem_name 라고 하는 포맷의 이름을 가진다. 각각의 열거 인터페이스간에 다른 것은, 열거의 대상 뿐이다. 모든 열거 인터페이스는 같은 메소드세트를 가져, 같은 방법으로 사용된다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IMoniker
COM 오브젝트를 일의에 식별하는 정보가 저장 되고 있는 모니카오브제크트를 사용할 수 있도록(듯이) 하는 메소드가 포함된 인터페이스. 모니카오브제크트의 IMoniker 인터페이스에의 포인터를 가지는 오브젝트는, 오브젝트가 실제로 분산 시스템 위에의 어디에 있을까에 관한 특정의 정보가 그 밖에 전혀 없는 경우에서도, 식별된 오브젝트를 검색해, 액티브하게 해, 그 오브젝트에 액세스 할 수가 있다. 상세한 것에 대하여는, Platform SDK 의 COM 의 문서를 참조할것.
IMoniker::BindToStorage
모니카에 의해 식별되는 오브젝트가 저장 되고 있는 기억 영역을 가리키는 인터페이스 포인터를 취득하는 메소드. IMoniker::BindToObject 와 달리, 이 메소드는 모니카에 의해 식별되는 오브젝트를 액티브하게 할 것은 없다. 상세한 것에 대하여는, Platform SDK 의 COM 의 문서를 참조할것.
IMoniker::BindToObject
모니카를 사용해, 모니카가 식별하는 오브젝트에 바인드 하는 메소드. 바인드 처리에서는, 오브젝트를 검색해, 필요하면 오브젝트를 실행 상태로 해, 식별된 오브젝트의 지정된 인터페이스를 가리키는 포인터를 호출해 바탕으로 건네준다. 상세한 것에 대하여는, Platform SDK 의 COM 의 문서를 참조할것.
IPersist
시스템에 영속적으로 저장 할 수 있는 오브젝트의 CLSID 를 공급하기 위한 GetClassID 라고 하는 단일의 메소드를 가지는 인터페이스. 다른 영속성 인터페이스 IPersistStorage,IPersistStream, 또는 IPersistFile 의 어느쪽이든을 이행 하면나무는,IPersist 가 갖추는 단일의 메소드를 이행 할 필요가 있다. 마샬링으로 사용하는 경우와 같이, 영속적 오브젝트의 CLSID 를 취득하는 것만이 목적의 경우는,IPersist 를 사용할 수 있다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IPersistFile
오브젝트의 로드 또는 보존을, 스토리지 오브젝트나 스트림은 아니고, 디스크 파일로 실시할 수 있도록(듯이) 하는 메소드를 갖춘 인터페이스. 보통은, 예를 들어, 링크 오브젝트에 IPersistFile 를 이행 한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IPersistPropertyBag
IPropertyBag 및 IErrorLog 와 제휴해 기능해, 각각의 프로퍼티 베이스의 영속성 메카니즘을 정의하는 인터페이스. 상세한 것에 대하여는, Platform SDK 의 COM 의 문서를 참조할것.
IPersistStream
단순한 시리얼 스트림을 사용해 저장을 실시하는 오브젝트를 보존해, 로드하기 위한 메소드를 갖춘 인터페이스. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IPropertyBag
오브젝트에 프로퍼티 가방을 제공하는 인터페이스. 오브젝트는 프로퍼티 가방에 오브젝트의 프로퍼티를 영속적으로 보존할 수 있다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IPropertyPage
프로퍼티 시트내의 특정의 페이지를 관리하는 프로퍼티 페이지 오브젝트의 주된 기능을 제공하는 인터페이스. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IPropertyPageSite
프로퍼티 페이지 사이트 오브젝트의 주된 기능을 제공하는 인터페이스. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IsBadReadPtr
호출원프로세스가 지정된 범위의 메모리의 독해 권한을 가지고 있는 것을 확인하는 Win32 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
ISpecifyPropertyPages
오브젝트가 프로퍼티 페이지를 지원 하고 있는 것을 나타내는 인터페이스. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IStorage::OpenStream
grfMode 파라미터로 지정된 액세스권한을 사용해, 이 스토리지 오브젝트내의 기존의 스트림 오브젝트를 오픈하는 메소드. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
IStream
스트림 오브젝트에 대한 데이터의 독해 및 기입을 지원 하는 인터페이스. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
ITypeInfo
보통, 오브젝트에 관한 정보의 독해에 사용되는 인터페이스. 예를 들어, 오브젝트 브라우저 툴은,ITypeInfo 를 사용해, 오브젝트의 특성 및 기능에 관한 정보를 타입 라이브러리로부터 취득할 수 있다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
LoadLibrary
지정된 실행 모듈을 호출해 원프로세스의 address 공간에 맵 하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
LONGLONG
64 비트의 부호 첨부 정수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
LRESULT
윈도우 프로시저 또는 콜백 함수로부터 돌려주어지는 32 비트값. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
MainAVIHeader
AVI 파일 전체에 관한 글로벌 정보가 저장 되고 있는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
moniker
IMoniker 인터페이스를 이행 하는 오브젝트. 모니카는, COM 오브젝트를 일의에 식별하는 이름으로서 기능한다. 패스가 파일 시스템내의 파일을 식별하는 것과 같게, 모니카는 디렉토리 이름 공간내의 COM 오브젝트를 식별한다.
MoveWindow
지정된 윈도우의 위치와 크기를 변경하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
MSG
thread의 메시지 큐에 있는 메세지 정보가 저장 되고 있는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
MsgWaitForMultipleObjects
대기 조건이 채워졌는지 어떠했는지를 판별하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
MultiByteToWideChar
캐릭터 라인을 와이드 캐릭터 라인 (Unicode)에 맵 하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
OleCreatePropertyFrame
새로운 프로퍼티 프레임을 기동하는 함수. 새로운 프로퍼티 프레임과는, 부모가 "hwndOwner" 이며, 부모 윈도우내의 포인트 (x, y)에 다이얼로그가 있어, 캡션이 "lpszCaption" 의 프로퍼티 시트 다이알로그 박스이다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
OPENFILENAME
GetOpenFileName 함수 및 GetSaveFileName 함수가,[여는] common dialog 박스 또는 [이름을 붙여 보존] common dialog 박스를 초기화할 경우에 사용하는 정보가 저장 되고 있는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
OutputDebugString
현재의 어플리케이션의 디버거에 캐릭터 라인을 보내는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
PALETTEENTRY
논리 칼라 팔레트내의 엔트리의 색과 용도를 지정하는 구조체. 논리 팔레트는,LOGPALETTE 구조체에 의해 정의된다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
PCMWAVEFORMAT
PCM waveform 오디오 데이터의 데이터 포맷을 기술하는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
PeekMessage
thread 메시지 큐에 메세지가 있을지 어떨지를 체크해, 메세지가 있으면, 그 메세지가 지정된 구조체에 저장 하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
PostMessage
지정된 윈도우를 생성 한 thread에 관련지을 수 있고 있는 메시지 큐에 메세지를 저장 (포스트) 해, thread가 메세지를 처리하는 것을 기다리지 않고 종료하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
프로퍼티 가방
IPropertyBag 인터페이스를 이행 하는, 영속적 오브젝트의 기술용의 컨테이너.
PROPPAGEINFO
프로퍼티 프레임에 대해서 프로퍼티 페이지를 설명하는데 사용하는 파라미터가 저장 되고 있는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
RECT
직사각형의 좌상구석과 우하구석의 좌표를 정의하는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
ReleaseSemaphore
지정된 semaphore 오브젝트의 카운트가 지정된 양만 증가시키는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
RGBQUAD
적, 초록, 및 파랑의 상대적인 농도로부터 구성되는 색을 기술하는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
SendMessage
지정된 메세지를 1 개 이상의 윈도우에 보내는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
SetDIBColorTable
지정된 디바이스 콘텍스트로 선택되고 있는 DIB (디바이스에 의존하지 않는 비트 맵)의 칼라 테이블에 포함되는 일정한 범위의 엔트리의 RGB (적, 초록, 파랑) 값을 설정하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
SetDIBitsToDevice
DIB (디바이스에 의존하지 않는 비트 맵)의 칼라 데이터를 사용해, 전송처 디바이스 콘텍스트에 관련지을 수 있고 있는 디바이스 위에의 지정된 직사각형내의 픽셀을 설정하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
SetDlgItemText
다이알로그 박스의 타이틀 또는 컨트롤의 텍스트를 설정하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
SetParent
지정된 자식 윈도우의 부모 윈도우를 변경하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
SetWindowLong
지정된 윈도우의 속성을 변경하는 함수. 이 함수는, 윈도우의 여분의 윈도우 메모리내의 지정된 오프셋(offset)에 있는 32 비트 (long 형)의 값도 설정한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
ShowWindow
지정된 윈도우의 표시 상태를 설정하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
SIZE
직사각형의 폭과 높이를 지정하는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
StretchBlt
카피원직사각형으로부터 카피처 직사각형에 비트 맵을 카피해, 필요한 경우는, 카피처 직사각형의 크기에 맞추어 비트 맵을 확장 또는 압축하는 함수. Windows 는, 카피처 디바이스 콘텍스트로 현재 설정되어 있는 확장 모드에 따라 비트 맵을 확장 또는 압축한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
StretchDIBits
디바이스에 의존하지 않는 비트 맵 (DIB) 내의 픽셀의 직사각형의 칼라 데이터를, 지정된 카피처 직사각형에 카피하는 함수. 카피처 직사각형이 카피원직사각형보다 큰 경우, 이 함수는, 카피처 직사각형에 맞추어 칼라 데이터의 행과 열을 확장한다. 카피처 직사각형이 카피원직사각형보다 작은 경우, 이 함수는, 지정된 라스터 조작을 실시해, 행과 열을 압축한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
SysAllocString
새로운 캐릭터 라인을 할당해, 건네받은 캐릭터 라인을 그 캐릭터 라인에 카피하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
SysFreeString
전에 할당할 수 있었던 캐릭터 라인을 해방하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
timeBeginPeriod
어플리케이션 또는 디바이스 드라이버의 최소 타이머 해상도를 설정하는 함수. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
timeGetTime
시스템 시간을 밀리 세컨드 단위로 취득하는 함수. 시스템 시간이란, Windows 가 기동하고 나서 경과한 시간이다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
timeSetEvent
지정된 바다거북 겨이삭띠를 시작 하는 함수. 멀티미디어 타이머는, 타이머 자체의 thread로 실행된다. 이벤트가 액티브하게 되면(자), 타이머는 지정된 콜백 함수를 호출한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
TXTDT_MG
비디오에 관한 텍스트의 기술을 저장 할 수 있는 구조체. 상세한 것에 대하여는, 「DVD-Video 사양」의 「섹션 4.1. 6」 및 「Annex A」를 참조할것. 사양의 카피를 입수하려면 ,(우)105-01 토쿄도 미나토구 시바우라 1 쵸메 1-1, 전화 03-5444-9580, 팩스 03-5444-9430 의 토시바에 연락하는 것.
videoDialog
비디오 캡춰 디바이스 드라이버의 구성 파라미터를 설정할 경우에 사용하는 다이알로그 박스를 표시하는 함수. 상세한 것에 대하여는, 「Video for Windows Development Kit Version 1.1」을 참조할것.
videoMessage
비디오 캡춰 디바이스 드라이버에 메세지를 보내는 함수. 상세한 것에 대하여는, 「Video for Windows Development Kit Version 1.1」을 참조할것.
WaitForMultipleObjects
대기 조건이 채워졌는지 어떠했는지를 판별하는 Win32 함수. 조건이 채워지지 않으면, 호출원thread는 대기 상태가 된다. 이 함수는, 지정된 오브젝트의 1 개 또는 모든 것이 통지제상태가 되었을 때, 또는, 타임 아웃 간격이 경과했을 때에 종료한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
WaitForSingleObject
지정된 오브젝트의 현재 상태를 체크하는 Win32 함수. 오브젝트가 미통지 상태가 되어 있으면, 호출원thread는 대기 상태가 된다. 이 함수는, 지정된 오브젝트가 통지제상태가 되었을 때, 또는 타임 아웃 간격이 경과했을 때에 종료한다. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.
WAVEFORMAT
waveform 오디오 데이터의 포맷을 기술하는 구조체. 상세한 것에 대하여는, Platform SDK 의 문서를 참조할것.


DirectSetup

여기에서는, Platform Software Development Kit (SDK) 또는 standalone DirectX SDK 에 있어서의 Microsoft® DirectX® 어플리케이션 프로그래밍 인터페이스 (API)의 Microsoft® DirectSetup® 컴퍼넌트에 대해 설명한다. 여기서 설명하는 내용의 대부분은, C++ 개발자전용의 것이다. Visual Basic® 에서의 셋업에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것. 여기에서는 다음의 주제로 나누어 설명한다.

  • DirectSetup 에 대해
  • DirectSetup 의 요점
  • DirectX for Visual Basic 어플리케이션의 인스톨
  • DirectSetup 레퍼런스
  • DirectSetup 샘플


DirectSetup 에 대해

Microsoft® DirectSetup 는, Microsoft DirectX® 의 모든 컴퍼넌트를 한 번의 호출로 인스톨하기 위한 심플한 API 이다. 이 API 의 의의는, 단지 편리라고 하는 만큼 머물지 않는다. DirectX 는 복잡한 구성이 되어 있기 (위해)때문에, 인스톨도 복잡한 태스크가 된다. 그 때문에, DirectX 의 인스톨은 수동으로 실시해서는 안된다.

DirectSetup 에는, 몇개의 API 함수와 구조체가 포함된다. 그 외 , 인스톨 프로세스용의 유저 인터페이스를 어플리케이션측에서 커스터마이즈하기 위한 prototype로서DirectXSetupCallbackFunction 도 준비되어 있다. DirectX SDK 에는, 이 콜백 함수의 사용예를 나타내는 샘플 어플리케이션이 수록되고 있다. 상세한 것에 대하여는, 「Dinstall 샘플」을 참조할것.


DirectSetup 의 요점

여기에서는, Microsoft® DirectSetup® 컴퍼넌트의 개요에 대해 설명한다. 설명하는 내용은 이하대로이다.

  • DirectSetup 의 셋업의 개요
  • 셋업 폴더의 준비
  • 셋업의 커스터마이즈
  • 셋업 프로그램의 테스트
  • AutoPlay 의 사용


DirectSetup 의 셋업의 개요

Microsoft® DirectX® 를 베이스로 하는 어플리케이션 및 게임은,DirectXSetup 함수를 사용해, 이미 인스톨 되고 있는 Microsoft Windows® 시스템에 필요한 시스템 컴퍼넌트를 인스톨 할 수가 있다. 이 함수에서는, 디스플레이나 오디오 디바이스로 적절히 DirectX 가 지원 되도록, 드라이버의 업데이트도 실시할 수가 있다. DirectXSetup 는, 보통, 어플리케이션 파일의 인스톨에 사용하는 프로그램으로부터 호출한다.

주 : DirectXSetup 함수는, 구버젼의 DirectX 시스템 컴퍼넌트를 덧쓰기한다. 예를 들어, 이미 DirectX 7.0 의 컴퍼넌트가 존재하는 시스템에 DirectX 8.0 을 인스톨 하면, DirectX 7.0 의 컴퍼넌트 모든 것이 덧쓰기된다. 다만, DirectX 의 컴퍼넌트는 모두 컴퍼넌트 오브젝트 모델 (COM)의 하위 호환성 규칙에 준거하고 있으므로, DirectX 7.0 용으로 기술한 소프트웨어도 계속해 정상적으로 기능한다.

DirectXSetup 함수는, DirectX 컴퍼넌트, 디스플레이 드라이버, 오디오 드라이버의 업그레이드가 필요한 일을 알릴 수가 있다. 또, 이러한 컴퍼넌트를, Windows operating system에 악영향을 주는 것 없이 업그레이드 할 수 있을지 어떨지도 판단할 수 있다. 이것이 이른바 세이프 업그레이드이다. 업그레이드때는, 컴퓨터상에서 동작하고 있는 어플리케이션 뿐만이 아니라, operating system에 대한 안전성도 고려한다. 또, Windows 에 있어서는 안전해도, 일부의 하드웨어 의존 어플리케이션에 악영향을 주어 버리는 경우도 있다.

디폴트에서는,DirectXSetup 함수는 안전한 업그레이드만을 실행한다. 디바이스 드라이버의 업그레이드에 의해 Windows 의 동작에 악영향이 미칠 가능성이 있는 경우, 업그레이드는 행해지지 않는다.

셋업 처리중, DirectSetup 는 옮겨놓는 시스템 컴퍼넌트와 드라이버의 백업 카피를 생성 한다. 이러한 카피는, 문제가 발생했을 경우에 복원하기 위한 것이다.

디스플레이 드라이버 또는 오디오 드라이버를 업그레이드 하면 와,DirectXSetup 함수는, Microsoft 사가 생성 한 데이타베이스를 이용해 업그레이드 프로세스를 관리한다. 이 데이타베이스에는, Microsoft 사, 하드웨어의 제조원, 또는 하드웨어의 판매원으로부터 제공되고 있는 기존의 드라이버에 대한 정보가 포함되어 있다. 또, Microsoft 사나 그 외의 사이트에서 행해진 테스트 기초를 두는 각각의 드라이버의 업그레이드 상황도 기록되고 있다.

DirectXSetup 함수를 실행하면(자), 반환값을 체크한다. 반환값이 DSETUPERR_SUCCESS_RESTART 의 경우는, 재기동할 때까지 변경 내용이 유효하게 안 되는 것을 유저에게 알려 곧바로 재기동할지 어떨지 선택시킨다. 이 방법에 대해서는,Dinstall 샘플 어플리케이션의 Dinstall.c 의 예를 참조할것.


셋업 폴더의 준비

DirectXSetup 함수는, 인스톨의 루트 디렉토리를 나타내는 파라미터 lpszRootPath 를 취한다. 이 파라미터를 NULL 로 해, 현재의 디렉토리 (즉, 셋업 프로그램이 보존되고 있는 디렉토리)를 루트 패스로 할 수도 있다.

루트 디렉토리에는, dsetup.dll 와 dsetup32.dll 를 보존할 필요가 있다. 또, 이 안에는 「DirectX」 (대문자 소문자의 구별 없음)이라는 이름의 폴더를 준비해, 재배포 가능한 모든 파일 및 드라이버를 보존한다. 올바른 구조의 어플리케이션 셋업 디스크는, Microsoft® DirectX SDK 디스크의 Dxf\Redist\DirectX8 폴더의 내용 모든 것을 셋업 프로그램의 루트 패스에 카피 하면 생성 할 수 있다. 이 폴더는, SDK 의 인스톨시에 개발용의 컴퓨터에 카피되지 않기 때문에, 오리지날 디스크로부터 별도 카피할 필요가 있다.


셋업의 커스터마이즈

Microsoft® DirectSetup® 에서는, Microsoft DirectX® 셋업 프로세스를 커스터마이즈하기 위한 콜백 함수를 정의할 수가 있다. 이 콜백 함수는, DirectSetup 문서 중(안)에서는 DirectXSetupCallbackFunction 로 불리고 있지만, 실제로는 임의의 이름을 할당할 수가 있다.

셋업 프로그램으로 콜백 함수를 사용하지 않는 경우,DirectXSetup 함수는, Microsoft Win32® MessageBox 함수를 호출해, 다이알로그 박스내에 스테이터스 정보나 에러 정보를 표시해, 유저 입력의 취득을 실시한다. 콜백 함수를 사용하는 경우, 이 스테이터스 다이얼로그 또는 메시지 박스의 생성에 사용되어야할 정보는, 대신에 콜백 함수에게 건네진다. 콜백 함수는, 인스톨 또는 업그레이드 가능한 DirectX 컴퍼넌트 및 디바이스 드라이버 마다 한 번 두개 불려 간다.

콜백 함수는, 이하의 용도에 사용할 수 있다.

  • 커스텀 인터페이스의 사용 - MessageBox 나 Microsoft Windows® 의 표준 다이알로그 박스 이외 방법으로, 셋업 프로그램의 메세지를 표시할 수 있다. 콜백 함수를 사용하는 것으로, DirectX 컴퍼넌트의 인스톨용 메세지를, 독자적인 인터페이스에 통합할 수 있다.
  • 진행 인디케이터(indicator)의 갱신
  • 스테이터스 메세지 및 에러 메세지의 표시 제어 - 초심자전용의 프로그램을 개발하는 경우에는, 에러 메세지를 제어해, 셋업 프로그램에 에러의 처리나 업그레이드의 선택을 자동적으로 처리시키고 싶은 경우가 있다. 이러한 셋업 프로그램의 개발에는 시간이 들지만, 대상 유저층을 생각하면(자) 적절한 조치라고 할 수 있다.

셋업의 커스터마이즈에 해당해서는, 다음의 각 주제를 참고로 하는 것.

  • DirectSetup 콜백 함수의 생성
  • 콜백 함수의 설정
  • 콜백 함수에서의 업그레이드 플래그의 사용법
  • 콜백 함수에 의한 디폴트 동작의 무효화


DirectSetup 콜백 함수의 생성

셋업 프로세스를 커스터마이즈 하려면 , 우선 다음의 선언으로 가리킨 DirectXSetupCallbackFunction prototype에 적합하는 콜백 함수를 생성 한다.

DWORD WINAPI DirectXSetupCallbackFunction(
        DWORD dwReason,
        DWORD dwMsgType,
        LPSTR szMessage,
        LPSTR szName,
        void *pInfo);

이 예 (Dinstall 를 수정한 것)에서는, 함수명이 prototype와 같게 되어 있지만, 이것은 변경 가능하다. 파라미터명은, dsetup.h 헤더 파일로 선언되고 있는 prototype와 약간 다르지만, 이하의 설명에서는 이러한 이름을 사용한다.

파라미터

dwReason 는, 콜백 함수가 불려 간 이유를 나타내는 파라미터이다. 유효값의 일람 및 각 유효값의 설명에 대해서는,DirectXSetupCallbackFunction 의 레퍼런스를 참조할것.

dwMsgType 파라미터는, Microsoft® DirectSetup® 가 디폴트로 MessageBox 에 건네주는 플래그 (표시하는 버튼이나 아이콘을 제어하는 플래그등)와 동등의 플래그를 받는다. 그 중에서, 버튼 플래그는, 필요한 반환값의 지정에 사용할 수 있다. 이 값이 0 의 경우, 이벤트는 유저 입력을 요구하지 않기 때문에, DirectSetup 는 보통 스테이터스 메세지를 표시한다.

szMessage 파라미터는, 콜백 함수를 사용하지 않는 경우에 DirectSetup 가 스테이터스 다이알로그 박스 또는 MessageBox 에 건네주는 것과 같은 텍스트를 받는다.

드라이버가 업그레이드 대상의 경우,szName 파라미터에 드라이버명이 건네받아pInfo 는 업그레이드의 처리 방법 (기존의 드라이버의 사용을 추천 하는, 업그레이드를 추천 하는 등)에 관한 정보를 나타낸다. 상세한 것에 대하여는, 「콜백 함수에서의 업그레이드 플래그의 사용법」을 참조할것.

콜백 함수가 각 파라미터를 어떻게 해석할까에 대해서는, 개발자의 재량으로 결정한다. 보통은, 표시하는 메세지 (dwReason 에 근거한다)와 유저에게 선택사항을 제시하는 타이밍을 선택해, 거기에 응해 인터페이스를 변경한다.

반환값

콜백 함수로부터의 반환값은, 다음의 규칙에 따를 필요가 있다.

  • dwMsgType 가 0 의 경우, 반환값은 IDOK 가 아니면 안된다. 이 경우, 유저에 대한 선택사항은 없다. (입력이 필요없는 경우에서도, 어플리케이션은 스테이터스 메세지를 표시해 상관없다. )
  • dwMsgType 가 0 이외의 경우의 반환값은,MessageBox 를 사용했을 경우에 유저가 같은 선택을 했을 때에 돌려주어지는 값과 같은 값이 아니면 안된다.

dwMsgType 가 0 이외의 경우의 적절한 반환값을 확인하려면 , 보통이라면 어떠한 버튼이 메시지 박스에 표시될까 실제로 테스트해 본다. 다음의 예 (Dinstall 의 GetReply 함수로부터는, 이 테스트 방법을 나타낸 것이다.

/* 글로벌 g_wReply 는, 유저가 선택한 커스텀
다이얼로그 버튼을 나타낸다.  */

switch (dwMsgType & 0x0000000F)
{
   / * 보통,[OK] 버튼과 [캔슬] 버튼이 배치된다.
       IDBUT1 는 [OK] 버튼에 대응한다. 유저가 [OK] 버튼을 클릭하지 않았던 경우는,
       [캔슬] 버튼이 클릭되었다고 판정된다. */
    case MB_OKCANCEL:
        wDefaultButton = (g_wReply == IDBUT1) ?  IDOK : IDCANCEL;
        break;

    / * 상기 이외의 버튼의 편성의 경우는, 이하와 같이 된다. */
    case MB_OK:
        wDefaultButton = IDOK;
        break;
    case MB_RETRYCANCEL:
        wDefaultButton = (g_wReply == IDBUT1) ?  IDRETRY : IDCANCEL;
        break;
    case MB_ABORTRETRYIGNORE:
        if (g_wReply == IDBUT1)
            wDefaultButton = IDABORT;
        else if (g_wReply == IDBUT2)
            wDefaultButton = IDRETRY;
        else
            wDefaultButton = IDIGNORE;
        break;
    case MB_YESNOCANCEL:
        if (g_wReply == IDBUT1)
            wDefaultButton = IDYES;
        else if (g_wReply == IDBUT2)
            wDefaultButton = IDNO;
        else
            wDefaultButton = IDCANCEL;
        break;
    case MB_YESNO:
        wDefaultButton = (g_wReply == IDBUT1) ?  IDYES : IDNO;
        break;
    default:
        wDefaultButton = IDOK;
}

이 루틴은, 커스텀 인터페이스로부터의 버튼 클릭을, 콜백 함수 없음의 경우에 DirectSetup 가 생성 하는 표준 다이알로그 박스내의 대응하는 박스 식별자에 평행이동 한다. wDefaultButton 변수는, 대응하는 표준 다이알로그 박스 버튼의 식별자로 설정된다. 콜백 함수로부터 돌려주어지는 것은, 이 값이다.

dwMsgType 가 0 이외의 값의 경우에서도, 반드시 유저에게 선택사항을 줄 필요는 없다. 예를 들어, DirectSetup 가 보통 유저에게 확인을 요구하는 것 같은 경우에서도, 자동적으로 드라이버를 업그레이드 하는 일도 가능하다. 샘플의 Dinstall 는, 문제가 있는 경우만 메세지를 표시하도록(듯이) 유저가 선택하고 있는 경우로, 게다가 드라이버를 업그레이드 해도 안전이라고 생각될 때, 다음과 같이 자동 업그레이드를 실시하게 되어 있다.

case DSETUP_CB_UPGRADE_SAFE:
    switch (dwMsgType & 0x0000000F)
    {
        case MB_YESNO:
        case MB_YESNOCANCEL:
            return IDYES;
        case MB_OKCANCEL:
        case MB_OK:
        default:
            return IDOK;
    }
    break;

콜백 함수는, 유저에게 업그레이드를 속행할지 어떨지 확인하는 다이알로그 박스로 긍정을 나타내는 버튼에 응해, IDYES 또는 IDOK 를 돌려준다.


콜백 함수의 설정

콜백 함수를 사용하는 경우는,DirectXSetup 를 호출하기 전에 시스템에 알려 둘 필요가 있다. 이것에는, 콜백에의 포인터를 파라미터로서 건네주어 DirectXSetupSetCallback 함수를 호출한다. 다음의 예를 참조할것.

DirectXSetupSetCallback(
        (DSETUP_CALLBACK) DirectXSetupCallbackFunction);


콜백 함수에서의 업그레이드 플래그의 사용법

어플리케이션으로 정의된 콜백 함수 DirectXSetupCallbackFunction 가 DirectXSetup 함수로 불려 가면(자), 콜백 함수에 호출해 이유를 나타내는 파라미터가 건네받는다. 이유가 DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE 의 경우,pInfo 파라미터는,DirextXSetup 함수가 추천 하는 Microsoft® DirectX® 컴퍼넌트 및 드라이버의 업그레이드 방법을 정리한 플래그를 보관 유지하는 DSETUP_CB_UPGRADEINFO 구조체를 나타낸다. 이러한 플래그를 저장 하는 구조체 멤버는,UpgradeFlags 로 불린다.

UpgradeFlags 에는 다음과 같은 카테고리가 있다.

프라이머리 업그레이드 플래그
이러한 플래그는 서로 배타적이다. 구조체 멤버 UpgradeFlags 에는 항상 어느쪽이든 1 개의 플래그가 존재한다. 플래그를 추출하려면 , DSETUP_CB_UPGRADE_TYPE_MASK 와의 비트마다의 AND 처리를 취한다.

DSETUP_CB_UPGRADE_FORCE

DSETUP_CB_UPGRADE_KEEP

DSETUP_CB_UPGRADE_SAFE

DSETUP_CB_UPGRADE_UNKNOWN

세칸다리압그레이드후라그
이러한 플래그의 1 개 또는 양쪽 모두를 지정할 수가 있다.

DSETUP_CB_UPGRADE_CANTBACKUP

DSETUP_CB_UPGRADE_HASWARNINGS

디바이스 액티브 플래그
드라이버를 업그레이드중의 디바이스가 액티브한 경우에 존재하는 플래그. 다른 플래그와 조합해 사용할 수 있다.

DSETUP_CB_UPGRADE_DEVICE_ACTIVE

디바이스 클래스 플래그
이러한 플래그는 서로 배타적이다. 어느 쪽인가의 플래그가 반드시 존재한다.

DSETUP_CB_UPGRADE_DISPLAY

DSETUP_CB_UPGRADE_MEDIA

즉,Reason 파라미터의 값이 DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE 이면,pInfo 로 지정되는 구조체 멤버 UpgradeFlags 에는, 항상 1 개의 일차 업그레이드 플래그, 0 개 이상의 2차 업그레이드 플래그, 0 개 또는 1 개의 디바이스 액티브 플래그, 및 1 개의 디바이스 클래스 플래그가 포함된다.

UpgradeFlags 의 멤버에 DSETUP_CB_UPGRADE_KEEP 가 설정되어 있는 경우는, Windows® 가 정상적으로 기능하지 않게 될 우려가 있기 때문에, DirectX 컴퍼넌트나 디바이스 드라이버를 업그레이드 할 수 없다. DirectXSetup 함수에 의한 컴퍼넌트 또는 드라이버의 업그레이드는 행해지지 않는다.

UpgradeFlags 에 DSETUP_CB_UPGRADE_FORCE 라고 하는 값이 있는 경우는, Windows 를 정상적으로 기능시키기 (위해)때문에, 컴퍼넌트 또는 드라이버의 업그레이드가 필요하다. 이 때문에,DirectXSetup 함수는, 드라이버 또는 컴퍼넌트의 업그레이드를 실시한다. 다만, 업그레이드에 의해, 시스템 위에의 일부의 프로그램에 악영향이 미칠 가능성이 있다. DirectXSetup 함수가 이 상태를 검출 하면,UpgradeFlags 의 멤버는 (DSETUP_CB_UPGRADE_FORCE | DSETUP_CB_UPGRADE_HAS_WARNINGS)으로 설정된다. 이 경우,DirectXSetup 함수는, 업그레이드를 실행하는 한편으로, 유저에게 경고를 발표한다.

컴퍼넌트 및 드라이버를 인스톨 해도 Windows 의 동작에 악영향이 미치지 않은 경우, 그 컴퍼넌트나 드라이버는 안전하게 업그레이드 할 수 있다고 보여진다. 이 경우,UpgradeFlags 의 멤버에는 DSETUP_CB_UPGRADE_SAFE 가 설정된다. 다만, Windows 에 대해서는 안전해도, 시스템에 인스톨 되고 있는 프로그램에 문제가 발생할 가능성은 있다. DirectXSetup 함수가 이 상태를 검출 하면,UpgradeFlags 의 멤버에는, 값 (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS)이 저장 된다. 이 경우,DirectXSetup 함수의 디폴트 동작에서는, 업그레이드는 실행되지 않는다.


콜백 함수에 의한 디폴트 동작의 무효화

어플리케이션으로 정의된 함수 DirectXSetupCallbackFunction 의 반환값을 사용해,DirectXSetup 함수의 디폴트 동작의 일부를 무효화할 수가 있다.

예를 들어,DirectXSetup 의 디폴트 동작에서는,pInfo 파라미터가 가리키는 구조 체내의 업그레이드 타입이 (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS)로 설정되어 있으면(자) 컴퍼넌트는 인스톨 되지 않는다. 이 경우, 콜백 함수의 MsgType 파라미터는 (MB_YESNO | MB_DEFBUTTON2)으로 설정된다. 콜백 함수를 사용하지 않는 경우는,[No] 가 디폴트 버튼이 된 다이알로그 박스가 유저에게 표시된다. 유저 입력을 조사하지 않고 디폴트를 받아들이는 경우, 콜백 함수는 IDNO 를 돌려준다. 디폴트를 무효로 하는 경우는, IDYES 를 돌려준다. 디폴트를 무효로 하는 경우,DirectXSetup 함수는 유저에게 통지한다.


셋업 프로그램의 테스트

생성 한 셋업 프로그램의 Microsoft® DirectSetup® 컴퍼넌트를 테스트하려면 ,DirectXSetup 함수에 DSETUP_TESTINSTALL 플래그를 건네준 버젼을 컴파일 한다. 그리고, 「셋업 폴더의 준비」로 설명한 인스톨 디렉토리를 셋업 한다.

셋업 프로그램을 실행 하면, DirectSetup 는, 실제로는 컴퍼넌트를 인스톨 하지 않고 , Microsoft DirectX® 인스톨시의 모의 동작을 실시한다. 콜백 함수를 설정해 있는 경우는, 콜백 함수의 동작도 조사할 수 있다.


AutoPlay 의 사용

AutoPlay 대응의 CD 타이틀을 생성 하려면 , Microsoft® DirectX® SDK CD 의 루트 디렉토리중의 Autorun.inf 파일을, 어플리케이션 디렉토리의 루트에 카피한다. Autorun.inf 는, 이하의 정보를 저장 하는 텍스트 파일이다.

[autorun]
OPEN=SETUP.EXE

어플리케이션의 셋업 프로그램명이 Setup.exe 의 경우, 이 파일을 변경할 필요는 없다. 그 이외의 이름이 붙어 있는 경우는, 실제의 셋업 프로그램명에 맞추어 이 파일을 편집해야 한다.


DirectX for Visual Basic 어플리케이션의 인스톨

모듈내에서 함수에 참조를 선언 하면, Microsoft Visual Basic 어플리케이션으로 Microsoft® DirectSetup® 함수를 사용할 수 있지만, 추천 방법은 어플리케이션 위저드의 사용이다. CD-ROM 로 어플리케이션을 배포하려면 , 이하의 조작을 실행한다.

Visual Basic 어플리케이션의 배포

  1. 어플리케이션 위저드를 기동한다.
  2. 의존 리스트로부터 DxVBLib.dll 를 삭제한다.
  3. Microsoft Direct® SDK CD 의 Redist 폴더 (리테일용 \Dxf\Redist\Directx7, 디버그용 \Dxf\Debug)의 모든 파일을 추가한다.
  4. [Finish] 버튼을 클릭해, 어플리케이션 위저드를 종료한다.
  5. DirectX SDK CD 의 support 폴더에 있는 Setup1.exe 를 (어플리케이션 위저드로 생성 된) Setup1.exe 에 덧쓰기한다.
  6. Visual Basic 5.0 을 사용하고 있는 경우는, 압축 유틸리티를 사용해 Setup1.exe 를 Setup1.ex_ 에 압축한다. Visual Basic 6.0 으로 개발하고 있는 경우는, 어플리케이션 위저드로 생성 된 배치파일을 실행한다.

이것으로, CD 로 파일을 배포할 준비가 갖추어진다.


DirectSetup 레퍼런스

여기에서는, Microsoft® DirectSetup® 의 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 함수
  • 구조체
  • 반환값

이 레퍼런스는 주로, C++ 로 프로그래밍을 실시할 때 사용한다. Microsoft® DirectX® for Microsoft Visual Basic® 의 셋업 정보에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.


함수

여기에서는, Microsoft® DirectSetup® 로 사용하는 이하의 글로벌 함수에 대해 설명한다.

  • DirectXRegisterApplication
  • DirectXSetup
  • DirectXSetupCallbackFunction
  • DirectXSetupGetVersion
  • DirectXSetupSetCallback
  • DirectXUnRegisterApplication


DirectXRegisterApplication

어플리케이션을 DirectPlayLobby 대응 어플리케이션으로서 등록한다.

int WINAPI DirectXRegisterApplication(
  HWND hWnd,
  LPDIRECTXREGISTERAPP lpDXRegApp
);

파라미터

hWnd
부모 윈도우의 핸들. 이 파라미터가 NULL 의 경우는, 데스크탑이 부모 윈도우가 된다.
lpDXRegApp
DirectPlayLobby 로 올바르게 어플리케이션을 동작시키기 위해서(때문에) 필요한 레지스트리 엔트리를 포함한 DIRECTXREGISTERAPP 구조체의 주소.

반환값

성공했을 경우는, TRUE 를 돌려준다.

실패했을 경우는, FALSE 를 돌려준다. GetLastError 함수를 사용 하면, 확장 에러 정보를 취득할 수 있다.

주의

DirectXRegisterApplication 함수에서는, Dsetup.dll 와 Dsetup32.dll 의 양쪽 모두가 필요하다. 이러한 파일은 시스템에 인스톨되어 있지 않지만, SDK 에 포함되어 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.

참조

DirectXUnRegisterApplication


DirectXSetup

1 개(살) 또는 복수의 Microsoft® DirectX® 컴퍼넌트를 인스톨 한다.

int WINAPI DirectXSetup(
  HWND  hWnd,
  LPSTR lpszRootPath,
  DWORD dwFlags
);

파라미터

hWnd
셋업 다이알로그 박스의 부모 윈도우의 핸들.
lpszRootPath
DirectX 컴퍼넌트 파일의 루트 패스를 포함한 캐릭터 라인의 주소. 이 캐릭터 라인에는, 파일 Dsetup.dll 및 Dsetup32.dll 와 재배포 가능 파일을 저장 한 「DirectX」 (대문자 소문자의 구별 없음) 디렉토리가 있는 디렉토리에의 풀 패스를 지정해야 한다. 이 값이 NULL 의 경우는, 현재의 작업 디렉토리가 사용된다.
dwFlags
인스톨 대상이 되는 DirectX 컴퍼넌트를 나타내는 1 개(살) 또는 복수의 플래그. 추천은, 풀 인스톨 (DSETUP_DIRECTX).
DSETUP_D3D | 사용하지 않는다. 이 플래그를 사용하는 DirectX 프로그램은, DirectX 컴퍼넌트를 모두 인스톨 한다.
DSETUP_DDRAW | 사용하지 않는다. 이 플래그를 사용하는 DirectX 프로그램은, DirectX 컴퍼넌트를 모두 인스톨 한다.
DSETUP_DDRAWDRV | DirectX 8.0 에서는 사용하지 않는다.
DSETUP_DINPUT | 사용하지 않는다. 이 플래그를 사용하는 DirectX 프로그램은, DirectX 컴퍼넌트를 모두 인스톨 한다.
DSETUP_DIRECTX | DirectX 와 호환성이 있는 디스플레이 드라이버 및 오디오 드라이버에 가세해 DirectX 런타임 컴퍼넌트를 인스톨 한다.
DSETUP_DIRECTXSETUP | 사용하지 않는다. 이 플래그를 사용하는 DirectX 프로그램은, DirectX 컴퍼넌트를 모두 인스톨 한다.
DSETUP_DPLAY | 사용하지 않는다. 이 플래그를 사용하는 DirectX 프로그램은, DirectX 컴퍼넌트를 모두 인스톨 한다.
DSETUP_DPLAYSP | 사용하지 않는다. 이 플래그를 사용하는 DirectX 프로그램은, DirectX 컴퍼넌트를 모두 인스톨 한다.
DSETUP_DSOUND | 사용하지 않는다. 이 플래그를 사용하는 DirectX 프로그램은, DirectX 컴퍼넌트를 모두 인스톨 한다.
DSETUP_DSOUNDDRV | DirectX 8.0 에서는 사용하지 않는다.
DSETUP_DXCORE | DirectX 런타임 컴퍼넌트를 인스톨 한다. DirectX 와 호환성이 있는 디스플레이 드라이버와 오디오 드라이버는 인스톨 하지 않는다.
DSETUP_TESTINSTALL | 인스톨 내용을 테스트한다. 새로운 컴퍼넌트를 인스톨 할 것은 없다.
DSETUP_USEROLDERFLAG | -14 (을)를 돌려줄 수 있다. 이것은, 인스톨 되고 있는 DirectX 의 버젼이 인스톨 하는 버젼보다 새로운 일을 의미한다.

반환값

이 함수가 성공했을 경우, 이하의 성공 코드 가운데 1 개를 돌려준다.

DSETUPERR_SUCCESS | 인스톨이 성공했다.
DSETUPERR_SUCCESS_RESTART | 인스톨이 성공했지만, 변경 내용을 유효하게 하기 위해서 시스템을 재기동할 필요가 있다.

실패했을 경우는, 에러 코드를 돌려준다. 반환값에 대해서는, 「반환값」을 참조할것.

주의

셋업 프로그램으로 DirectXSetup 함수를 사용하기 전에, 시스템에 최저 15 MB 의 빈디스크 영역이 있는 것을 확인하는 것. 이것은 적절한 파일을 셋업 하기 위해서 DirectX 가 필요로 하는 최대 영역이다. 다만, 시스템에 DirectX 파일이 이미 존재하는 경우는 필요없다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.


DirectXSetupCallbackFunction

옵션으로 셋업 프로그램으로 설정하는 콜백 함수의 플레이스홀더명이다. 설정된 콜백 함수는, 셋업 프로세스의 각 스텝 마다 한 번 두개 불려 간다.

DWORD DirectXSetupCallbackFunction(
  DWORD  Reason,
  DWORD  MsgType,
  char  *szMessage,
  char  *szName,
  void  *pInfo
);

파라미터

Reason
콜백의 이유. 다음의 몇개의 값을 취한다.
DSETUP_CB_MSG_BEGIN_INSTALL
DirectXSetup 가 Microsoft® DirectX® 컴퍼넌트와 디바이스 드라이버의 인스톨을 시작하려 하고 있다.
DSETUP_CB_MSG_BEGIN_INSTALL_DRIVERS
DirectXSetup 가 디바이스 드라이버의 인스톨을 시작하려 하고 있다.
DSETUP_CB_MSG_BEGIN_INSTALL_RUNTIME
DirectXSetup 가 DirectX 컴퍼넌트의 인스톨을 시작하려 하고 있다.
DSETUP_CB_MSG_BEGIN_RESTORE_DRIVERS
DirectXSetup 가 이전의 드라이버의 복원을 시작하려 하고 있다.
DSETUP_CB_MSG_CANTINSTALL_BETA
Microsoft Windows® 95 operating system의 베타 버젼이 검출되었다. DirectX 컴퍼넌트 또는 디바이스 드라이버를 인스톨 할 수 없다.
DSETUP_CB_MSG_CANTINSTALL_NOTWIN32
Windows 32 비트 이외의 operating system가 검출되었다. DirectX 는 Windows3.x 와 호환성은 없다.
DSETUP_CB_MSG_CANTINSTALL_NT
DirectX 컴퍼넌트 또는 디바이스 드라이버는, 버젼 4.0 보다 전의 Microsoft Windows NT® operating system에는 인스톨 할 수 없다.
DSETUP_CB_MSG_CANTINSTALL_UNKNOWNOS
operating system가 기존의 것은 아니다. DirectX 컴퍼넌트 또는 디바이스 드라이버를 인스톨 할 수 없다.
DSETUP_CB_MSG_CANTINSTALL_WRONGLANGUAGE
DirectX 컴퍼넌트 또는 디바이스 드라이버를, Windows 로 사용되고 있는 언어에 로컬라이즈 할 수가 없다.
DSETUP_CB_MSG_CANTINSTALL_WRONGPLATFORM
DirectX 컴퍼넌트 또는 디바이스 드라이버가 다른 종류의 컴퓨터용의 것이다.
DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE
드라이버의 업그레이드를 필요라고 생각된다. 유저측의 확인을 추천 한다.
DSETUP_CB_MSG_FILECOPYERROR
DirectX 컴퍼넌트 또는 디바이스 드라이버 파일의 셋업이 카피 프로세스중에 실패했다.
DSETUP_CB_MSG_INTERNAL_ERROR
내부 에러가 발생했다. DirectX 컴퍼넌트 또는 디바이스 드라이버의 셋업이 실패했다.
DSETUP_CB_MSG_NOMESSAGE
표시하는 메세지가 없다. 콜백 함수는 돌아오지 않으면 안 된다.
DSETUP_CB_MSG_NOTPREINSTALLEDONNT
사용하고 있는 Microsoft Windows NT 또는 Microsoft Windows 2000 의 버젼에 DirectX 컴퍼넌트 또는 디바이스 드라이버가 인스톨 할 수 없다.
DSETUP_CB_MSG_OUTOFDISKSPACE
DirectX 컴퍼넌트의 셋업이 디스크 영역 부족을 위해서(때문에) 실패했다.
DSETUP_CB_MSG_PREINSTALL_NT
사용하고 있는 Windows NT 또는 Windows 2000 의 버젼에 이미 DirectX 가 인스톨 되고 있다.
DSETUP_CB_MSG_SETUP_INIT_FAILED
DirectX 컴퍼넌트 또는 디바이스 드라이버의 셋업이 실패했다.
MsgType
메시지 박스의 표시를 제어하는 플래그. 이러한 플래그는,MessageBox 함수에 건네줄 수가 있다. MsgType 가 0 때는 예외로, 셋업 프로그램은 스테이터스 정보를 표시할 수 있지만, 유저로부터의 입력 대기를 해선 안 된다.
szMessage
에러 메세지 또는 스테이터스 정보를 포함한 로컬라이즈 캐릭터 라인에의 포인터. 이러한 캐릭터 라인은,MessageBox 함수로 생성 되는 다이알로그 박스에 표시할 수 있다.
szName
Reason 파라미터가 DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE 가 아닌 한 NULL 이다. 이 경우,szName 에는 업그레이드 하는 드라이버의 이름에의 포인터가 들어간다.
pInfo
업그레이드 정보를 포함한 구조체의 주소에의 포인터. Reason 가 DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE 의 경우는, 셋업 프로그램이 드라이버의 업그레이드중에서, 유저에게 업그레이드를 실시해야할 것인가 어떤가를 문의하고 있다. 이 경우,pInfo 는, 업그레이드에 관한 정보를 저장 하는 DSETUP_CB_UPGRADEINFO 구조체를 나타낸다.

반환값

1 개의 예외를 제외해, 반환값은 MessageBox 함수로부터 돌려주어지는 반환값과 같지 않으면 안 된다. 이 함수가 0 을 돌려주었을 경우,DirectXSetup 함수는 디폴트의 동작으로 DirectX 컴퍼넌트 또는 드라이버의 업그레이드를 실행한다.

주의

DirectXSetupCallbackFunction 의 이름은 셋업 프로그램으로부터 주어진다. DirectXSetupSetCallback 함수는, DirectSetup 에 콜백 함수의 주소를 건네줄 때에 사용된다.

MsgType 가 0 의 경우, 셋업 프로그램으로 스테이터스 정보를 표시할 수 있지만, 유저로부터의 입력 대기를 해선 안 된다. 이 경우, 함수는 IDOK 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : 유저 정의.

참조

MessageBox,DirectXSetupSetCallback ,셋업의 커스터마이즈


DirectXSetupGetVersion

현재 인스톨 되고 있는 Microsoft® DirectX® 컴퍼넌트의 버젼 번호를 취득한다.

INT WINAPI DirectXSetupGetVersion(
  DWORD  *pdwVersion,
  DWORD  *pdwRevision
);

파라미터

pdwVersion
버젼 번호를 받는 변수의 주소에의 포인터. 버젼 번호가 불요의 경우는 NULL 에서도 가능.
pdwRevision
리버젼 번호를 받는 변수의 주소에의 포인터. 리버젼 번호가 불요의 경우는 NULL 에서도 가능.

반환값

성공했을 경우는, 0 이외의 값을 돌려준다.

실패했을 경우는, 0 을 돌려준다.

주의

DirectXSetupGetVersion 함수는,DirectXSetup 함수를 호출하는 전후에 버젼 번호와 리버젼 번호를 취득하기 위해서 사용한다. DirectXSetup 의 호출전에 이 함수를 호출했을 경우는, 현재 인스톨 되고 있는 DirectX 컴퍼넌트의 버젼 번호와 리버젼 번호가 주어진다. DirectXSetup 의 호출해 다음에, 게다가 컴퓨터를 재기동하기 전에 이 함수를 호출했을 경우는, 컴퓨터를 재기동한 후에 유효하게 되는 DirectX 컴퍼넌트의 버젼 번호와 리버젼 번호가 주어진다.

pdwVersion 파라미터에 저장 되는 버젼 번호는, 메이저 버젼 번호와 마이너 버젼 번호로부터 완성된다. 함수로부터 돌려주어진 메이저 버젼 번호는,DWORD 의 상위 16 비트에 저장 된다. 함수로부터 돌려주어진 마이너 버젼 번호는,DWORD 의 하위 16 비트에 저장 된다. 버젼 번호와 실제의 버젼은 다음과 같이 대응하고 있다.

DirectX 의 버젼 | pdwVersion 에 의해 포인트 되는 값
DirectX 1 | 0x00000000
DirectX 2 | 0x00000000
DirectX 3 | 0x00000000
DirectX 5.0 | 0x00040005
DirectX 6.0 | 0x00040006
DirectX 7.0 | 0x00040007
DirectX 8.0 | 0x00040008

DirectX 의 버젼 4 는 존재하지 않는다.

pdwRevision 파라미터에 저장 되는 버젼 번호는, 릴리스 번호와 빌드 번호로부터 완성된다. 함수로부터 돌려주어진 릴리스 번호는,DWORD 의 상위 16 비트에 저장 된다. 함수로부터 돌려주어진 빌드 번호는,DWORD 의 하위 16 비트에 저장 된다.

다음의 샘플 코드는,DirectXSetupGetVersion 로부터 돌려주어진 정보를 꺼내 사용하는 방법을 나타낸 것이다.

DWORD dwVersion;
DWORD dwRevision;
if (DirectXSetupGetVersion(&dwVersion, &dwRevision))
{
    printf("DirectX version is %d. %d. %d. %d\n",
           HIWORD(dwVersion), LOWORD(dwVersion),
           HIWORD(dwRevision), LOWORD(dwRevision));
}

버젼 번호와 리버젼 번호는, 64 비트 데이터에 결합해 비교할 수가 있다. 이 때, 버젼 번호는 상위 32 비트에, 리버젼 번호는 하위 32 비트에 각각 저장 된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.

참조

DirectXSetup


DirectXSetupSetCallback

DirectXSetup 로부터 주기적으로 불려 가는 콜백 함수에 포인터를 세트 한다. 콜백 함수는, 셋업의 진행 상황의 통지와 어플리케이션의 셋업 프로그램용의 커스텀 유저 인터페이스의 이행에 사용할 수가 있다. 상세한 것에 대하여는,DirectXSetupCallbackFunction 를 참조할것. 셋업 프로그램이 콜백 함수를 주지 않는 경우,DirectXSetupSetCallback 는 불려 가지 않는다.

INT WINAPI DirectXSetupSetCallback(
  DSETUP_CALLBACK  Callback
);

파라미터

Callback
콜백 함수의 주소.

반환값

현재 상태로서는 0 을 돌려준다.

주의

콜백 함수를 설정하려면 ,DirectXSetup 를 호출하기 전에 DirectXSetupSetCallback 를 호출하지 않으면 안 된다.

DirectXSetupSetCallback 에게 건네지는 콜백 함수의 이름은, 셋업 프로그램에 의해 주어진다. 다만,DirectXSetupCallbackFunction 로 주어지는 prototype에 적합하는 것이 아니면 안된다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.

참조

DirectXSetupCallbackFunction ,DirectXSetup


DirectXUnRegisterApplication

DirectPlayLobby 대응 어플리케이션의 등록을 삭제한다.

int WINAPI DirectXUnRegisterApplication(
  HWND   hWnd,
  LPGUID lpGUID
);

파라미터

hWnd
부모 윈도우의 핸들. 데스크탑이 부모 윈도우 때는, 이 파라미터에 NULL 를 설정한다.
lpGUID
삭제 대상이 되는 Microsoft® DirectPlay 어플리케이션의 GUID 의 주소.

반환값

성공했을 경우는, TRUE 를 돌려준다. 이것은 등록의 삭제에 성공한 것을 나타낸다.

실패했을 경우는, FALSE 를 돌려준다.

주의

DirectXUnRegisterApplication 함수에서는, Dsetup.dll 와 Dsetup32.dll 의 양쪽 모두가 필요하다. 이것들 2 개의 파일은 시스템에 인스톨되어 있지 않지만, SDK 에 포함되어 있다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.

참조

DirectXRegisterApplication


구조체

여기에서는, Microsoft® DirectSetup® 로 사용되는 이하의 구조체에 대해 설명한다.

  • DIRECTXREGISTERAPP
  • DSETUP_CB_UPGRADEINFO

주 : Microsoft DirectX® 구조체의 메모리는 모두, 사용전에 0 에 초기화해야 한다. 또,dwSize 멤버를 가지는 모든 구조체는, 사용전에 이 멤버를 구조체의 사이즈 (바이트 단위)로 설정해야 한다.


DIRECTXREGISTERAPP

DirectPlayLobby 대응 어플리케이션에 필요한 레지스트리 엔트리를 저장 한다.

typedef struct _DIRECTXREGISTERAPP {
    DWORD  dwSize;
    DWORD  dwFlags;
    LPSTR  lpszApplicationName;
    LPGUID lpGUID;
    LPSTR  lpszFilename;
    LPSTR  lpszCommandLine;
    LPSTR  lpszPath;
    LPSTR  lpszCurrentDirectory;
} DIRECTXREGISTERAPP, *PDIRECTXREGISTERAPP, *LPDIRECTXREGISTERAPP;

멤버

dwSize
구조체의 크기. DIRECTXREGISTERAPP 구조체의 크기에 초기화되지 않으면 안 된다.
dwFlags
예약 비트.
lpszApplicationName
어플리케이션의 명칭.
lpGUID
어플리케이션의 글로벌 유니크 식별자 (GUID).
lpszFilename
불려 가는 실행 파일명.
lpszCommandLine
실행 파일의 커멘드 라인 인수.
lpszPath
실행 파일의 패스.
lpszCurrentDirectory
커런트 디렉토리. 보통은 lpszPath 와 같다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dsetup.h 로 선언.


DSETUP_CB_UPGRADEINFO

파라미터로서 어플리케이션으로 정의한 DirectXSetupCallbackFunction 에 건네받는다. 이 구조체에는,Reason 파라미터가 DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE 때만, 유효한 정보가 저장 된다. 콜백 함수는, 이 구조체를 사용해, 실행하는 업그레이드에 관한 스테이터스 정보를 취득할 수가 있다.

typedef struct _DSETUP_CB_UPGRADEINFO {
    DWORD UpgradeFlags;
} DSETUP_CB_UPGRADEINFO;

멤버

UpgradeFlags
업그레이드 스테이터스는 1 개 이상의 플래그로 나타난다. 다음의 각 값이 정의되고 있다.
DSETUP_CB_UPGRADE_CANTBACKUP
낡은 시스템 컴퍼넌트를 백업 할 수 없다. 업그레이드는 실행 가능하지만, 업그레이드 후의 컴퍼넌트나 드라이버의 복원은 할 수 없다.
DSETUP_CB_UPGRADE_DEVICE_ACTIVE
디바이스는 현재 사용중이다.
DSETUP_CB_UPGRADE_DEVICE_DISPLAY
업그레이드 대상의 디바이스 드라이버는, 디스플레이 디바이스용의 드라이버이다.
DSETUP_CB_UPGRADE_DEVICE_MEDIA
업그레이드 대상의 디바이스 드라이버는, 미디어 디바이스용의 드라이버이다.
DSETUP_CB_UPGRADE_FORCE
컴퍼넌트가 업그레이드 되지 않으면, Microsoft® Windows® 가 정상적으로 기능하지 않을 우려가 있다. 업그레이드는 실행된다.
DSETUP_CB_UPGRADE_HASWARNINGS
Microsoft DirectSetup® 로 이 디바이스의 드라이버를 업그레이드 할 수 있지만, 시스템 위에의 1 개(살) 이상의 프로그램에 영향을 줄 우려가 있다. 영향을 받는다고 보여지는 프로그램의 이름은 szMessage 에 저장 된다. 업그레이드는 추천 되지 않는다.
DSETUP_CB_UPGRADE_KEEP
이 디바이스 드라이버를 업그레이드 하면, 시스템에 장해가 발생할 우려가 있다. 업그레이드는 허가되지 않는다.
DSETUP_CB_UPGRADE_SAFE
DirectSetup 는 이 디바이스 드라이버를 안전하게 업그레이드 할 수 있다. 업그레이드가 추천 된다. 안전한 업그레이드란, Windows 의 동작에 악영향을 주지 않는 것을 나타낸다. 하드웨어에 의존하는 일부의 프로그램에 대해서는, 악영향이 미칠 가능성이 있다.
DSETUP_CB_UPGRADE_UNKNOWN
이 디바이스의 기존의 드라이버를 인식할 수 없다. 이 값의 상황은 빈번하게 발생한다. 업그레이드 하는 것으로써, 이 디바이스의 사용에 악영향을 줄 가능성이 있다. 업그레이드를 실행하지 않게 강하게 추천 한다.

주의

UpgradeFlags 로부터 업그레이드 타입 (FORCE, KEEP, SAFE, 또는 UNKNOWN)을 취득하려면 , 값 DSETUP_CB_UPGRADE_TYPE_MASK 를 사용한다.

동작환경

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
헤더 : dsetup.h 로 선언.

참조

DirectXSetupCallbackFunction


반환값

DirectXSetup 함수는 이하의 값을 돌려준다. 이 함수에서는 표준 COM 에러를 돌려줄 수도 있다.

DSETUPERR_SUCCESS
셋업이 성공했다. 재기동의 필요는 없다.
DSETUPERR_SUCCESS_RESTART
셋업이 성공했다. 재기동할 필요가 있다.
DSETUPERR_BADSOURCESIZE
파일 사이즈를 검증할 수 없었는지, 잘못이었다.
DSETUPERR_BADSOURCETIME
파일의 일자 및 타임을 검증할 수 없었는지, 잘못이었다.
DSETUPERR_BADWINDOWSVERSION
시스템으로 실행중의 Microsoft Windows® 는, Microsoft® DirectX® 에서는 지원 되지 않는다.
DSETUPERR_CANTFINDDIR
셋업 프로그램으로 작업 디렉토리가 발견되지 않았다.
DSETUPERR_CANTFINDINF
필요한 . inf 파일이 발견되지 않았다.
DSETUPERR_INTERNAL
내부 에러가 발생했다.
DSETUPERR_NEWERVERSION
DirectX 의 상위 버젼이 이미 인스톨 되고 있다. 상위 버젼이 덧쓰기될 것은 없고, 이전의 버젼용으로 기술된 어플리케이션과도 완전하게 호환성이 있기 (위해)때문에, 어플리케이션은 안전하게 이 에러를 무시할 수 있다.
DSETUPERR_NOTADMIN
커런트 유저가 관리자 권한을 가지고 있지 않다. Windows 2000 시스템에서는, 셋업 시에 관리자 권한이 필요한 경우가 있다.
DSETUPERR_NOCOPY
파일의 버젼을 검증할 수 없었는지, 잘못이었다.
DSETUPERR_NOTPREINSTALLEDONNT
시스템의 Windows NT® 또는 Windows 2000 의 버젼에, DirectX 의 최신 버젼이 포함되지 않았다. DirectX 의 낡은 버젼이 존재하는지, DirectX 목의 버젼도 존재하지 않는지, 어느 쪽인가의 가능성이 있다.
DSETUPERR_OUTOFDISKSPACE
셋업 프로그램에 의한 인스톨중에 디스크 영역이 부족하게 되었다.
DSETUPERR_SOURCEFILENOTFOUND
필요한 원시 파일 가운데중 한쪽이 발견되지 않았다.
DSETUPERR_UNKNOWNOS
지원되어 있지 않은 버젼의 operating system이다.
DSETUPERR_UNSUPPORTEDPROCESSOR
지원되어 있지 않은 프로세서 타입이다. DirectX 8 에서는, Pentium 또는 K6 호환 프로세서 및 이것들 이후의 프로세서만을 지원 하고 있다.
DSETUPERR_USERHITCANCEL
어플리케이션의 인스톨이 완료하기 전에,[Cancel] 버튼이 밀렸다.


DirectSetup 샘플

Microsoft® DirectSetup® 의 사용 방법 및 기능을 설명하는 샘플로서 다음의 프로그램이 제공되고 있다.

  • Dinstall 샘플 (C/C++)
  • DXVBSetup 샘플 (Microsoft Visual Basic)

DirectX 샘플에는 Microsoft Visual C++® 의 프로젝트 워크 스페이스 파일이 포함되어 있지만, 각자의 개발 환경에서 올바르게 컴파일 할 수 있도록(듯이) 다른 설정을 확인할 필요가 있는 경우가 있다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.


Dinstall 샘플

설명

Dinstall 는, Microsoft® DirectSetup® 함수를 사용해 Microsoft DirectX® 서브 시스템을 인스톨 하는 샘플이다. 여기에서는, 콜백 함수를 사용해, 커스텀 인터페이스 (이 경우는 신풀궶드레스다이아로그복스) 경유로 메세지의 표시와 유저 입력의 취득을 실시하는 예를 나타내고 있다.

패스

원시 파일 :(SDK 루트)\Samples\Multimedia\Misc\DXInstall

유저즈 가이드

  1. DirectX SDK CD 의 \Redist\DirectX8 폴더의 내용을 모두 Dinstall.exe 와 같은 폴더에 카피한다.
  2. 개발 환경의 작업 디렉토리도 이 폴더로 설정한다. (Microsoft Visual C++® 에서는,[Project Settings] 다이알로그 박스의 [Debug] 페이지에 이 설정이 있다).
  3. 프로그램을 실행해,[File] 메뉴의 [Start Install] 를 클릭한다. DirectSetup 는, DirectX 의 모의 인스톨을 실행해 ( 「프로그래밍 위에의 주의」를 참조), 모드레스다이아로그복스에 진척 상황을 표시한다. [Options] 메뉴에서는, 표시하는 메세지 레벨을 변경할 수 있다. 다만, 모의 인스톨만을 실시하는 경우는, 문제 발생 메세지나 업데이트 메세지는 표시되지 않는다.
  4. [File] 메뉴의 [Get Version] 를 클릭한다. 시스템에 현재 인스톨 되고 있는 DirectX 의 버젼 번호 및 리버젼 번호가 표시된다.

프로그래밍 위에의 주의

디폴트에서는, 프로그램은 DirectXSetup 함수에 DSETUP_TESTINSTALL 를 건네준다. 이것은, 실제로 파일은 카피되지 않고, 레지스트리의 변경도 행해지지 않는 것을 나타낸다. 실제로 인스톨을 실시하려면 , 이 플래그를 함수 호출로부터 삭제한다.

Dinstall 에서는, 인스톨 진척 상황의 감시나 메세지의 인터셉트에 콜백 함수를 사용하고 있다. 유저가 지정한 경고 레벨 (g_fStatus 로 추적)에 응해, 메세지를 무시하거나 모드레스다이아로그복스에 메세지를 표시하거나 할 수 있다. 유저 입력이 필요한 경우는 적절한 버튼이 표시되어 몇개의 버튼이 밀릴 때까지 GetReply 함수가 메시지 큐를 감시한다.


DXVBSetup 샘플

여기에서는, Microsoft® Visual Basic® 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Dinstall 샘플」을 참조할것.


용어집

여기에서는, Microsoft® DirectX® SDK 의 문서로 사용되는 기술 용어를 해설한다.

A , B , C , D , E , F , G , H , I , J, K, L , M , N , O , P , Q , R , S , T , U , V , W , X, Y, Z


A

알파 채널 (alpha channel)
알파값에 의해 정의되는, 화면의 불투명도. 불투명도를 정의하는 알파값은, 픽셀 단위에 다른 색성분과 함께 주어지는지 (ARGB 등의 경우), 독립한 알파 표면내에서 픽셀 단위에게 줄 수 있는지, 또는 표면 전체에 고정의 값으로 주어진다.
알파색성분 (alpha color component)
32 비트 칼라의 불투명도를 결정하는 부분. 32 비트 칼라의 경우, 알파값은, 픽셀 단위에 다른 색성분과 함께 주어진다 (ARGB 등). 보기 드물게, 독립한 알파 표면내에 픽셀 단위의 알파값이 저장 되고 있는 화면의 알파값을 가리켜 매A르파 성분� 이라고 하는 경우도 있다.
알파 정수 (alpha constant)
표면 전체에 적용되는 불투명도 (알파값).
알파 엣지 브렌드 (alpha edge blend)
알파 블렌딩 ( 및알파 채널 정보)의 용법의 1 개. 픽셀의 적용 범위에 근거해 엣지를 혼합색 하는 것으로써, 앨리어싱(aliasing)를 감소시키는 방법이다.
앰비언트 속성 (ambient property)
환경광속성, 라이트로부터의 각도에 의존하지 않고 반사하는 머트리얼 속성. 오브젝트의 향해, 위치, 표면 특성 등에 관계없이, 장면의 모든 것을 비추는 광원 및 머트리얼 속성. 장면의 모든 장소를 같은 광원에서 비추기 (위해)때문에, 앰비언트 광원에 놓여진 프레임의 위치나 방향은 중요하지 않다. 복수의 앰비언트 광원이 장면내에서 짜 합쳐진다.
이방성 필터 링 (anisotropic filtering)
이방성의 일그러짐을 보정하는밉맵 필터 링 모드의 1 개.
이방성 (anisotropy)
표면이 표시면에 대해서 각도를 가져 위치하는 3D 오브젝트의 이미지에 생기는, 눈에 보이는 일그러짐. 이방성은 텍스쳐 공간에 역맵 된 스크린 픽셀의 성장 (길이÷폭)으로서 계측 할 수 있다.
배열 오브젝트 (array object)
1 개의 배열에 정리된 오브젝트군. 배열 오브젝트를 사용 하면, 일련의 오브젝트 모두에게 어떠한 처리를 실시하는 경우의 조작이 간단하게 된다. 배열 오브젝트를 취급할 수가 있는 COM 인터페이스에는,GetElement 와 GetSize 라고 하는 메소드가 준비되어 있다. 이 2 개의 메소드는 각각, 배열 요소에의 포인터의 취득, 및 배열 사이즈의 취득을 실시한다.
어태치 (attach)
복수의 DirectDrawSurface 오브젝트를 접속해, Z 버퍼 첨부의 3D 페이지프립핑을 지원 하는 경우 등에 필요한 복합 구조체로 하는 것. 어태치는 쌍방향적인 것은 아니다. 표면을 그 표면 자신에게 어태치 할 수 없다. 또, (시스템 메모리내에서) 에뮤레이트 되고 있는 표면을, 에뮤레이트에 의하지 않는 표면에 어태치 하는 일도 할 수 없다. 2 개의 표면을 어태치 하는 경우, 다른 한쪽의 표면이 텍스쳐 맵이 아닌 한, 어태치 되는 표면 끼리는 동일 사이즈가 아니면 안된다.
어태치 상태 (attached)
시스템에 물리적으로 접속되고 있는 상태. 디바이스는, 인스톨 되고 있어도, 어태치 상태에는 없는 경우도 있다.
어택 (attack)
매그니튜드가 기본 레벨 (유지 기간 레벨)에 이르러 force feedback 이펙트가 시작될 때의 초기 기간.


B

백 버퍼 (back buffer)
화면에 표시되어 있지 않은 표면. 어플리케이션은, 프런트 버퍼의 이미지가 화면에 표시되고 있는 동안에, 비트 맵이나 그 외의 이미지를 백 버퍼에 그려 넣을 수가 있다.
후방 클립면 (back clipping plane)
시추대의 깊이의 한계. 이 저쪽 편에 있는 오브젝트는 렌더링 되지 않는다. 「전방 클립면」을 참조할것.
뱅크 셀렉트 (bank select)
MIDI 의 컨트롤 체인지. 다른 그룹 (뱅크)으로부터의 음색 선택을 가능하게 한다. 각 뱅크의 식별에는, 2 바이트 코드가 사용된다.
빌보드 (billboard)
1 개의 면이 뷰아에 향하는 것 같은 방향으로 3D 신에 삽입된 프리미티브. 텍스쳐 (보통은, 애니메이션 된 스프라이트)를 빌보드에 적용 하면, 3D 오브젝트가 장면상에 나타난다.
빌딩 승선 (billboarding)
장면 위에의 3D 오브젝트의 외관을 시뮬레이트 하는 2D 기법. 어플리케이션은, 프리미티브 (보통은 직사각형)를 1 개의 면이 뷰아에 향하는 것 같은 방향으로 장면에 삽입해, 1 개의 텍스쳐 또는 일련의 텍스쳐를 거기에 적용한다. 적용된 텍스쳐는, 애니메이션 된 3D 오브젝트로 보인다.
블렌딩 계수 (blend factor)
텍스쳐 블렌딩에 대해, 각 색성분이 어떻게 혼합색 되는지를 나타내는 계수.
블렌딩 모드 (blend mode)
텍스쳐가 적용처의 표면의 색과 어떻게 혼합색 될까를 결정하는 알고리즘.
블렌딩 스테이지 (blending stage)
텍스쳐 cascade의 1 스텝. 블렌딩 스테이지는, 1 개의 텍스쳐와 복수의 텍스쳐를 혼합색 할 때에 사용되는 일련의 텍스쳐 블렌딩 처리로부터 완성된다.
소총탄 (blit)
비트의 블록 전송.
경계 체크 (bounds checking)
화면상의 이미지가 화면의 경계내에 표시되고 있는지 어떤지를 체크하는 처리.
범프 맵핑 (bump mapping)
3D 신으로 표면이 요철 한 외관을 시뮬레이트 하는 기법. 깊이의 변화가 텍스쳐내에 저장 되어 표준의 텍스쳐 블렌딩 기술을 사용해 원시적으로 적용된다.


C

카메라 (camera)
표시 위치와 방향을 정의하기 위해(때문에), 뷰 포토가 이용하는 Direct3DRMFrame 오브젝트. 뷰 포토는, 카메라 프레임의 정의 z 축상에 있는 가시 오브젝트만을, y 축위에의 정방향에 렌더링 한다.
카메라 공간 (camera space)
시점이 원점에 위치해, 거기로부터 z 축의 정의 방향을 보고 있는 기준 프레임. 오브젝트의 좌표는, 뷰 트랜스 폼에 의해월드 공간으로부터 카메라 공간으로 트랜스 폼 된다.
클라이언트/서버 세션 (client/server session)
서버만이 세션의 완전한 상태를 저장 하는 Microsoft® DirectPlay® 세션. 각 클라이언트는 세션 상태의 서브 세트만을 보관 유지한다. 각 클라이언트는, 서버로부터 그 컴퓨터에 관한 정보만을 받는다. 어느 컴퓨터로 무엇인가를 변경했을 경우는, 서버에 그 변경을 전한다. 그 후, 서버는 변경에 대해 어느 클라이언트에 통지해야할 것인가를 판단한다. 「피어 투 피어 세션」을 참조할것.
클립 리스트 (clip list)
표면의 가시 영역을 나타내는 직사각형의 리스트. 이미 DirectDrawClipper 오브젝트에 윈도우 핸들을 연결시킬 수 있고 있는 경우는, 클립 리스트를 설정할 수 없다.
클리퍼- (clipper)
DirectDrawClipper 오브젝트.
CODEC
압축 신장 시스템 (COmpressor and DECompressor)을 나타내는 약어.
충돌 검출 (collision detection)
2 개의 이미지에 화면상의 같은 위치를 공유하는 픽셀이 없는가 판단하는 처리. 「히트 검출」을 참조할것.
칼라 키 (color key)
투명 이펙트나 반투명 이펙트에 사용되는 색을 나타내는 값. 예를 들어,하드웨어의 소총탄 기능을 사용했을 경우, 직사각형 영역내의 칼라 키로서 설정된 값을 가지는 픽셀 이외의 모든 픽셀이 소총탄 된다. 이것은, 직사각형이 아닌 스프라이트를 표면상에 생성 한다.
색공간(color space) (color space)
3 개(살) 이상의 좌표값으로 색을 나타내는 모델. 색공간(color space) 모델은, 색의 각 성분을, 3 차원 이상의 데카르트 좌표계에 매핑 한다. 색공간(color space)는, 색의 코드화와 가시화에 복수의 방법을 이용하는 경우도 있다. 가장 일반적인 색공간(color space) 모델은, RGB 와 YUV 의 2 개이다.
색공간(color space)의 변환 (color-space conversion)
다른색공간(color space)간에 색을 변환하는 것. 보통은, 비디오 소스의 YUV 칼라로부터 표시용의 RGB 색에의 변환을 말한다.
칼라 테이블 (color table)
n 색의 칼라값의 배열 (보통은 RGB 삼원색).
복합 표면 (complex surface)
루트 표면에 어태치 되고 있는 복수의 DirectDrawSurface 오브젝트를 정리해 가리키는 용어. 복합 표면 구조체는, 루트를 파기하는 것에 의해서 밖에 파기할 수 없다.
제어 세그먼트(segment) (control segment)
재생의 일정 국면을 제어하는 뮤지컬 세그먼트(segment). 보통은 프라이머리 세그먼트(segment)이지만, 제어 세그먼트(segment)로서 세칸다리세그먼트를 지정할 수가 있다.
카링 (culling)
렌더링 처리로 3D 프리미티브의 배면등을 생략하는 것.
커브 (curve)
Microsoft® DirectMusic® 로, 시작과 종료의 값을 가지는 일련의 이벤트. 볼륨의 페이드 등.


D

암색빛 (dark light)
장면으로부터 라이트를 제거하는 광원. 암색빛은, 라이트의 색에 부의 값을 지정하는 것으로써 생성 할 수 있다.
DCI
Display Control Interface (디스플레이 컨트롤 인터페이스)의 약어. DCI 는, Intel 및 Microsoft® 에 의해 정의된 인터페이스로, 비디오 메모리에 직접 액세스 하는 것에 의해, 보다 높은 그래픽스 퍼포먼스를 제공한다.
데드 밴드 (deadband)
force feedback축의 오프셋(offset)의 주위에 있는, 조건이 작용하지 않는 영역.
데드 존 (dead zone)
축의 물리적인 동작 범위내에서, 축이 중심에 위치하고 있다고 보여지는 영역.
디칼 (decal)
비주얼 오브젝트로서 직접 렌더링 되는 텍스쳐. 뷰 포토에 위치를 맞춘 직사각형에 렌더링 된다.
전송처 칼라 키 (destination color key)
소총탄의 경우는 옮겨놓을 수 있는 색, 오버레이의 경우는 전송처의 표면상에서 덮어 가려지는 색.
디바이스 윈도우 (device window)
Microsoft® DirectDraw® 가 표시용으로 사용하는 어플리케이션 윈도우. 어플리케이션은, 주어진 컴퓨터에 어태치 되고 있는 각 표시 디바이스에 1 개씩 디바이스 윈도우를 가질 수가 있다. 「포커스 윈도우」를 참조할것.
디레크쇼날 (directional)
프레임에 어태치 되지만, 모든 오브젝트를 같은 휘도로 비추는 광원의 기술. 마치 광원이 오브젝트로부터 무한의 거리에 위치할 것 같은 이펙트를 준다. 디레크쇼나르라이트는, 방향은 가지지만 위치를 가지지 않고, 일반적으로, 태양과 같이 멀게 멀어진 광원을 시뮬레이트 하기 위해서 이용된다.
DirectPlay 주소 (DirectPlay address)
Microsoft® DirectPlay® 가 로비 서버, 어플리케이션, DirectPlay, 및 서비스 프로바이더의 사이에 주소 정보를 건네주기 위해서(때문에) 사용하는 데이터 형식. DirectPlay 주소는, 글로벌 유니크 식별자 (GUID)로 태그 붙이고 된 일련의 가변장의 데이타체크이다. GUID 는, DirectPlay 에 필요한 주소 정보를 모두 제공한다. 주소 정보의 예로서 서버의 네트워크 주소, 플레이어의 네트워크 주소, 플레이어의 전자 메일명, 세션의 네트워크 주소등을 들 수 있다.
DLS
DownLoadable Sounds (다운로드 가능한 사운드)의 약어. 소프트웨어에 저장 되고 있는 디지털 샘플로부터 웨이브 사운드를 합성하는 기능에 대한 표준. MIDI Manufacturers Association 로부터 DLS 레벨 1 및 레벨 2 의 표준이 발표되고 있다.
DMO
Microsoft® DirectX® Media Object (Microsoft® DirectX® 미디어 오브젝트)의 약어. 클라이언트에 의해 할당할 수 있었던 버퍼로부터의 멀티미디어 데이터 스트림을 처리하는 COM 오브젝트.


E

에미션(emission) 속성 (emissive property)
자기 발색 속성, 머트리얼 (소재)의 라이트로 의존하지 않는 색속성을 나타내는 머트리얼 속성, 발광 또는 발색. 머트리얼의 반사 및 발광을 결정하는 속성은 4 개 있지만, 에미션(emission) 속성은 그 중의 1 개(살)이다. 「앰비언트 속성」, 「디퓨즈 속성」, 및 「스펙큐러 속성」을 참조할것.
에미션(emission) 설정 (emissive setting)
「에미션(emission) 속성」을 참조할것.
유효 프레임 (enable frame)
광원을 적용할 수가 있는 프레임.
포락선 (envelope)
force feedback로, 초기 (어택)와 종기 (페이드)에서의 매그니튜드를 변경하는 것으로써, 이펙트의 형상을 정의하는 일련의 값.

오디오에서는, 사운드의 진폭 또는 피치의 형상을 정의하는 일련의 값. DLS 레벨 1 에서는, 어택, 디케이, sustain, 릴리스 (ADSR)의 4 세그먼트(segment) 포락선이 정의되고 있다. DLS 레벨 2 에서는, 지연, 어택, hold, 디케이, sustain, 릴리스 (DAHDSR)의 6 세그먼트(segment)가 정의되고 있다.

짝수 필드 (even field)
비디오 프레임을 구성하는 홀수/짝수의 필드 세트의 2 번째의필드 . 필드 2 라고도 불린다.
실행 버퍼 (execute buffer)
3D 신을 기술하는, 모든 정보가 저장 되고 있어 독립한 정보 패킷. 실행 버퍼에는, 버텍스의 리스트가 저장 되어 거기에 계속되어 명령 스트림이 저장 된다. 명령 스트림은, 오퍼레이션 코드 (작동코드)와 그 작동코드에 의한 처리의 대상이 되는 데이터로부터 완성된다.


F

면 (face)
메쉬내의 단일의 다각형.
페이드 (fade)
force feedback 이펙트의 중앙 부분 (유지 기간)으로부터 force feedback 이펙트가 끝날 때까지의 기간.
폴 오프 (falloff)
spotlight의 안쪽의 원추면과 외측의 원추면과의 사이의 빛의 감쇠.
필드 (field)
비디오 스트림내의 단일의비디오 프레임의 반에 상당하는 데이터. 각 필드에는, 1 개(살) 간격의 주사선의 데이터가 저장 된다. 필드의 송수신은,홀수 필드,짝수 필드의 순서로 행해진다.
필드극성 (field polarity)
필드가짝수 필드와홀수 필드의 어디에서 있는지를 나타내는 특성. 홀수 필드에서는, 주사선중에 VREF 의 하강 모서리는 발생하지 않는다. 짝수 필드에서는, 주사선중에 VREF 의 하강 모서리가 발생한다.
후리마링 (flimmering)
z 값의 분리가 불완전하기 때문에, 전사시에 3D 프리미티브상에 발생하는 표시후들 붙어 있는. 배면의 텍스쳐의 일부의 픽셀이 전면의 텍스쳐상에 렌더링 되거나 그 역이 일어나거나 한다.
플립 (flip)
백 버퍼와프런트 버퍼의 주소를 스왑 (교환) 하는 것. 이것에 의해,백 버퍼내의 이미지를 프런트 버퍼에 카피 또는 소총탄 할 필요가 없다. 그 결과, 백 버퍼내에 있던 이미지를 효율적으로 화면에 표시할 수 있다.
후립핑체 (flipping chain)
서로 접속되고 있어 플립 가능한 일련의 표면. 「플립」을 참조할것.
후립핑서페스 (flipping surface)
후립핑 가능한 메모리. 「플립」을 참조할것.
포커스 윈도우 (focus window)
Microsoft® DirectDraw® 가 윈도우 메세지를 받아들이기 위해서(때문에) 사용하는 어플리케이션 윈도우. 실제로 화면에 표시되는 경우도, 표시되지 않는 경우도 있다. 포커스 윈도우의 메세지 핸들러는, DirectDraw 에 의해 전송 된 입력 메세지를 받아들인다. 어플리케이션이 가질 수 있는 포커스 윈도우는 1 개 뿐이다. 「디바이스 윈도우」를 참조할것.
프레임 (frame)
장면 위에의 오브젝트의 배치의 기본으로 되는 비표시의 박스. 장면상에서의 오브젝트의 위치는, 적절한 기준 프레임에 대한 공간적인 관계를 지정하는 것에 의해 결정할 수가 있다. 비주얼 오브젝트는, 그 위치나 방향을 프레임으로부터 취득한다.

동영상이나 애니메이션내의 단일의 이미지도 마찬가지이다.

프런트 버퍼 (front buffer)
그래픽스 어댑터에 의해 변환되어 모니터 또는 다른 출력 디바이스에 표시되는 메모리의 직사각형.
전방 클립면 (front clipping plane)
시추대의 전면의 한계. 전방 클립면보다카메라 집합에 있는 오브젝트는 렌더링 되지 않는다. 전방 클립면의 높이에 의해, 시야가 정해진다. 「후방 클립면」을 참조할것.


G

겐록킹 (genlocking)
2 개의 비디오 신호의 동기를 취하는 처리. 겐록킹 된 신호는 원의 신호와 동기가 잡히고 있기 (위해)때문에, 원의 신호와 믹싱 할 수가 있어 디조르브, 와이프등의 트란지션에페크트가 가능해진다.
구라두 (grid)
박 (비트)의 소분할. 비트마다의 구라두수는, Microsoft® DirectMusic® 의 박자 기호의 일부이다.
홈 레벨 (groove level)
스타일의 재생중에 뮤직으로 지정되는 값. 홈 레벨에 의해, 지정된 시간에 선택할 수 있는 패턴이 결정된다. 작가는, 광범위의 홈 레벨을 각 패턴에 할당한다.
그룹 (group)
플레이어의 논리적인 모임. Microsoft® DirectPlay® 는, 세션내에서 그룹을 지원 한다. 플레이어의 그룹을 생성 하는 것으로써, 어플리케이션은 그룹에 단일의 메세지를 송신할 수 있어 그룹내의 모든 플레이어가 그 메세지를 수신할 수 있다. 그룹은, 네트워크의 멀티 캐스트 기능을 어플리케이션에 공개하는 수단이 된다.

그룹은, 세션내의 플레이어를 정리하기 위해서(때문에) 사용할 수 있다. 플레이어는, 1 개(살) 이상의 그룹에 속할 수가 있다. DirectPlay 에서는, 그룹이나 그 멘바십을 관리할 수가 있다.


H

HAL
Hardware Abstraction Layer (하드웨어 추상 계층)의 약어. HAL 는, 하드웨어 및 디바이스 드라이버의 메카니즘에 의해 구성되어 개개의 디바이스 고유의 이행의 상세를 어플리케이션으로부터 숨기는 기능을 담당한다. 사용하고 있는 하드웨어가, 어플리케이션으로부터 요구된 기능을 이행 하고 있지 않았던 경우는, 그 기능을 소프트웨어에 의해 에뮤레이트 한다.
하드웨어 소총탄 (블록 전송) (hardware blitter)
디스플레이 어댑터에 짜넣어지고 있어 효과적인 소총탄 처리를 실시하는 하드웨어 컴퍼넌트.
HEL
Hardware Emulation Layer (하드웨어 에뮬레이션 계층)의 약어. HEL 는, 하드웨어가 지원 하고 있지 않는 기능을 소프트웨어에 의해 에뮤레이트 한다.
HID
Human Interface Device (휴먼 인터페이스 디바이스)의 약어. 인간이 컴퓨터를 제어할 수 있는 디바이스를 나타내는 USB 클래스.
히트 검출 (hit detection)
「충돌 검출」을 참조할것.
호스트 (host)
Microsoft® DirectPlay® 로, DPID_SYSMSG 라고 하는 ID 를 가지는 가상 플레이어. 호스트는, 시스템 메세지나 세션내의 모든 플레이어에게 보내지는 메세지를 관리한다.
HREF
Horizontal REFresh (수평 리프레쉬)의 약어. HREF 신호는, 비디오 스트림내에서, 디스플레이가 새로운 주사선을 시작 하려고 하고 있는 것을 알릴 때 액티브하게 된다. 「VREF 」를 참조할것.
HRTF
Head-Related Transfer Function (머리 부분 전달 함수)의 약어. 다를 방향으로부터 오는 소리의 피치나 타이밍에 대해서 청취자의 생리 기능이 미치는 영향의 수학적 표현.


I, J, K

인덱스 팔레트 (index palette)
다른 팔레트 오브젝트의 인덱스가 되는 엔트리를 가지는 DirectDrawPalette 오브젝트.
IPX 서비스 프로바이더 (IPX service provider)
Internetwork Packet Exchange (IPX) 프로토콜을 사용해 근거리 통신망 (LAN) 상에서 통신을 실시하기 위해서(때문에) Windows Sockets 를 사용하는 서비스 프로바이더. 이 서비스 프로바이더는, 비보증의 메시지 교환만을 지원 한다. 1 대의 컴퓨터는, IPX 를 사용해 1 개의 Microsoft® DirectPlay® 세션만의 호스트로서 기능한다.
IRE 율 (IRE scale)
International Radio Engineers 의 비율. IRE 는, 어느 요소를 전요소에 카피하는 비디오 신호의 휘도를 정의하는 0 ~ 100 까지의 범위의 값. IRE 값이 높아지면(자), 비디오 신호의 휘도가 증가한다. 7.5 IRE 의 휘도 유니트 (National Television System Committee (NTSC) 신호의 흑에 의한 절단의 해 귀의값)에서는, NTSC 디스플레이 디바이스의 전자총은 절단 되어 화면에는 이미지가 표시되지 않는다.


L

지연 시간 (latency)
응답 지연 시간. 예를 들어 Microsoft® DirectSound® 에서는,사운드 버퍼가 재생되고 나서 실제로 사운드가 스피커로부터 나올 때까지 의 시간이다. Microsoft DirectPlay® 에서는, 패킷이 지정된 행선지에 도달할 때까지의 시간이다.
라이트 맵 (light map)
3D 신의 라이팅 정보가 들어간 텍스쳐.
로비아웨아아프리케이션 (lobby-aware application)
로비로부터의 기동을 최소한 지원 하는 어플리케이션.
로비 클라이언트 (lobby client)
유저의 컴퓨터상에서 실행되는 로비 관리 루틴. 어플리케이션의 기동, 유저 인터페이스의 갱신,로비 서버와의 통신을 실시한다.
로비 프로바이더 (lobby provider)
로비 서버의 개발자가 제공하는 클라이언트 컴퍼넌트 (동적 링크 라이브러리). 이것에는, Microsoft® DirectPlay® 의 요구에 응해 로비 서버와의 통신 기능이 이행 된다.
로비 서버 (lobby server)
리모트 서버-위에서 실행되는 로비 관리 루틴. 로비 서버는, 관리 대상의 어플리케이션에 접속해 온 유저에 관한 모든 정보를 조정한다.
로비 세션 (lobby session)
클라이언트와 서버가 상호 운용하도록(듯이) 특별히 기술되어 있지 않았던 로비 서버에의 접속.


M

마하 밴드 (Mach bands)
3D 프리미티브의 블렌딩이 순조롭게 행해지지 않는 색범위.
머트리얼 (material)
표면이 어떻게 빛을 반사 및 발색할까를 결정하는 속성. 머트리얼 (소재)에는,에미션(emission) 속성 (라이트로 의존하지 않고 발색), 앰비언트 속성, 디퓨즈 속성, 및스펙큐러 속성의 4 개의 원가요소가 있다. 반사의 밝음은, 강도의 설정에 의해 결정된다.
메쉬 (mesh)
단순한 다각형으로 표현되는 면이 모인 것.
밉맵 (mipmap)
MIP 맵이라고도 불린다. MIP 는, 영어의 "much in little" 를 의미하는 라틴어 �multium in parvo� 의 약어. 동일 이미지가 서서히 저해상도가 되어 가는 일련의 텍스쳐로, 1 개의 이미지에 몇 종류의 필터를 걸치는 것으로 생성 된다. 오브젝트가 근처에 표시될 때는 고해상도의 이미지가 사용되어 오브젝트가 멀어지는에 따라 (즉 화면에서의 표시가 작아지는에 따라) 저해상도의 이미지가 사용된다.
믹싱 (mixing)
Microsoft® DirectSound® 로, 재생중의 복수의사운드 버퍼를 합성해, 생성된 사운드를프라이머리 사운드 버퍼 (사운드 하드웨어에 오디오 데이터를 출력하는 버퍼)에 기입하는 처리. 처리 시간이 범위내에 들어갈지 어떨지를 고려하지 않으면, 믹싱 할 수 있는 버퍼의 수에 제한은 없다.
모드 X (Mode X)
표준 VGA 의 모드 13 으로부터 파생한 하이브리드(hybrid) 디스플레이 모드. 이 모드에서는, VGA 디스플레이 어댑터의 EGA 멀티 비디오 평면 시스템을 사용하는 것으로써, 최대 256 KB 의 디스플레이 메모리가 사용 가능해지고 있다 (모드 13 으로 사용 가능한 디스플레이 메모리량은 64 KB).
모델 좌표 (model coordinates)
로컬 원점에 대한 상대 좌표. 「모델 공간」 및 「월드 좌표」를 참조할것.
모델 공간 (model space)
단일의 3D 모델용의 로컬 원점에 대한 상대적인 버텍스를 사용하는 (모델 좌표를 위한) 기준 프레임.
멀티 패스 텍스쳐 블렌딩 (multipass texture blending)
각 패스 마다 한 번 두개텍스쳐상에 블렌딩 해, 3D 프리미티브를 반복해 렌더링 하는 방법. 이 방법은, 다양한 특수 효과를 얻기 위해서(때문에) 폭넓게 사용되고 있다.


N

나그링 (nagling)
TCP/IP 서비스 프로바이더에, 작은 데이터 패킷을 버퍼에 넣어 큰 데이터 패킷으로 하고 나서 송신시키도록(듯이) 하는 알고리즘. 나그링은, 작은 데이터 패킷을 1 개의 큰 패킷에 결합할 수 있을 때까지 축적하는지, 사전의 패킷의 확인을 받아들일 때까지 서버에 대기하도록(듯이) 요구하는 것으로써, TCP/IP 서버가 많은 매우 작은 패킷을 송신하지 않게 한다. 나그링은 메세지 송신의 오버헤드 ( 및 필요한 대역폭)를 삭감할 수 있지만, 작은 데이터 패킷을 송신하기 전에 늦고가 생긴다 (지연 시간이 증가한다).
법선 벡터 (normal vector)
표면으로부터 수직에 성장하는 가공의 레이로, 면의 방향의 정의에 사용된다.
NRPN
NonRegistered Parameter Number (비등록 파라미터 번호)의 약어. 비등록 파라미터는 다른 메이커에 의한 다른 기능에 대해서 사용할 수가 있어 파라미터에는 MIDI 콘트롤러를 통해 액세스 한다. 상세한 것에 대하여는, MIDI 의 사양을 참조할것.


O

홀수 필드 (odd field)
비디오 프레임을 구성하는 홀수/짝수의 필드 세트의 1 번째의필드 .
오프 스크린 표면 (off-screen surface)
메모리 위에의 개념적인 직사각형 영역. 일반적으로, 표시하기 전에백 버퍼에 소총탄 하는 비트 맵을 저장 하기 위해서 사용한다. 보통, 스프라이트가 저장 된다.
작동코드 (opcode)
실행 버퍼내의 버텍스를 해석하는 방법이나 시스템 상태를 변경하는 방법을 정의하는 오퍼레이션 코드.
오바드로 (overdraw)
스크린 픽셀이 드로잉(Drawing) 되는 평균 회수.
오버레이 표면 (overlay surface)
메모리 위에의 개념적인 직사각형 영역. 오버레이 표면에 저장 된 이미지 정보는, 그 오버레이 표면이 적용되는프라이머리 표면의 이미지 정보 위에 씌울 수 있다. 오버레이는, 그 외의 모든 스크린 요소보다 위에 있는 것으로서 처리된다.
오버레이 Z 오더 (overlay z-order)
오버레이 끼리의 클리핑의 차례를 결정한다. 이것에 의해, 하드웨어 스프라이트 시스템을 Microsoft® DirectDraw® 에 이행 하는 것이 가능하게 된다.


P

페이지후립핑 (page flipping)
「플립」을 참조할것.
팔레트 (palette)
오브젝트나 어플리케이션이 사용하는 색세트. Microsoft® DirectX® 에서는, DirectDrawPalette 오브젝트를 가리킨다.
팔레트 인덱스 (palette index)
색을 선택할 경우에 사용되는 팔레트 테이블 배열의 인덱스가 되는 정수.
팔레트화 된 표면 (palettized surface)
어태치 된 팔레트를 색정보의 저장 장소로서 사용하는 DirectDrawSurface 오브젝트.
빵값 (pan value)
좌우의 오디오 채널의 상대 음량. 100 분의 1 데시벨 단위로 나타내진다.
패러렐 포인트 (parallel point)
평행한 광선으로 오브젝트를 비추지만, 빛의 방향은 그 위치로부터 결정되는 것 같은 광원의 기술. 예를 들어, 패러렐 포인트 광원의 양측으로 놓여진 2 개의 메쉬가 있는 경우, 각 메쉬는 광원에 접하고 있는 (분)편의 면이 비추어진다.
P 채널 (PChannel)
Performance channel (퍼포먼스 채널)의 약어. 특정의 포토상에 있는 특정의 채널 그룹내의 MIDI 채널.
PCM
Pulse Code Modulation (펄스부호변조)의 약어. 비압축 형식의 웨이브 데이터 형식에서, 각 값은 샘플링시의 신호의 진폭을 나타내고 있다.
피어 투 피어 세션 (peer-to-peer session)
세션의 완전한 상태가 그 세션내의 모든 컴퓨터상에 복제되는 Microsoft® DirectPlay® 세션. 세션 기술 데이터 (플레이어와 그룹의 리스트, 및 각 세션에 관한 이름과 리모트 데이터)는, 모든 컴퓨터에 복제된다. 1 대의 컴퓨터로 무엇인가 변경했을 경우는, 다른 모든 컴퓨터에 즉석에서 통지된다. 이것은, DirectPlay 의 통신의 디폴트 모드이다. 「클라이언트/서버 세션」을 참조할것.
퍼스펙티브 보정 (perspective correction)
원근 보정. 카메라로부터 각도를 이루어 떨어져 가는 다각형에 텍스쳐 맵을 적용할 때에, 다각형의 깊이를 알 수 있도록(듯이) 텍스쳐를 다각형상에 넓히는 기법. Microsoft® Direct3D® 에서는, 퍼스펙티브 보정은 자동적으로 행해진다.
피킹 (pick)
뷰 포토의 2D 좌표로 주어진 장소에 있는 비주얼 오브젝트를 장면내에서 찾는 것.
PID
Physical Interface Device (물리 인터페이스 디바이스)의 약어. 인간이 컴퓨터로부터 force feedback를 느낄 수 있는 USB 클래스.
피치 (pitch)
비트 맵 라인의 선두를 나타내는 주소와 다음의 라인의 선두를 나타내는 주소의 사이의 거리. 바이트 단위로 나타내진다. 모든 디스플레이 메모리가 1 개의 선형 블록으로서 배치되고 있다고는 할 수 없기 때문에, 메모리 피치와 메모리폭을 혼동 하지 않는 것. 예를 들어, 직사각형 메모리와 같이, 비트 맵의 폭과 캐쉬 부분이 더해진 것이 디스플레이 메모리의 피치가 되고 있는 경우도 있다. 「폭」 및 「보폭」을 참조할것.
플레이어 (player)
Microsoft® DirectPlay® 세션의 참가자. 각 플레이어에게는, 플레이어 사이에서의 메시지 교환을 가능하게 하기 위해서플레이어 ID 가 주어진다.
플레이어 ID (player ID)
Microsoft® DirectPlay® 세션의 참가자의 생성시에 참가자에게 줄 수 있는, 그 참가자 고유의 번호. 어플리케이션은, 플레이어 ID 를 사용해 참가자 끼리에게 메시지 교환을 실시하게 한다. 호스트에게는, 항상 DPID_SYSMSG 라고 하는 플레이어 ID 가 주어진다.
PNG
Portable Network Graphics (휴대용 네트워크 그래픽스)의 약어. 열화가 없는 압축 방식을 사용하는 비트 맵 포맷. 특정의 메이커의 소유물은 아니다.
포인트 라이트 (point light)
그 기점으로부터 모든 방향에 균등하게 빛을 조사하는 광원.
포인트 리스트 (point list)
가장 단순한 3D 프리미티브. 3D 공간내의 서로 접속되어 있지 않은 점의 모임이다.
강도 (power)
머트리얼의스펙큐러 속성으로, 스펙큐러 하이라이트의 선명도를 결정하는 값. 이 값이 5 때는 금속적인 외관이 되어, 값이 좀 더 높아지면(자)보다 플라스틱적인 외관이 된다.
프라이머리 사운드 버퍼 (primary sound buffer)
최종적인 오디오 출력을 믹싱 해 재생하는 오브젝트. 일반적으로는 세칸다리밧파의 사운드를 믹싱 한 결과의 출력처로 여겨지지만, 커스텀 믹싱이나 그 외의 특별 처리를 실시하기 위해서(때문에) 직접 액세스 할 수도 있다.
프라이머리 표면 (primary surface)
디스플레이에 표시되는 이미지가 저장 되는 메모리 영역.
투영 공간 (projection space)
투영 트랜스 폼에 의해월드 공간의 위치로부터 트랜스 폼 된 버텍스가 들어간 기준 프레임. 투영 공간은, 장면 위에의 모든 버텍스가,－ 1.0 ~ 1.0 의 범위내의 x 좌표와 y 좌표, 및 0.0 ~ 1.0 의 범위내의 z 좌표를 가지는 동차 입방체 공간이다. 원근 보정 후 동차 공간으로 불리는 경우도 있다.
투영 트랜스 폼 (projection transformation)
버텍스에 행렬을 적용해, 버텍스를카메라 공간으로부터투영 공간에 변경하는 트랜스 폼.


Q

쿠오타니온 (quaternion)
벡터를 정의하는 [x, y, z] 값에 추가되는 4 번째의 요소. 3D 축과 그 회전의 회전을 정의한다.


R

참조 카운트 (reference count)
컴퍼넌트 오브젝트 모델 (COM) 오브젝트를 컨트롤하기 위한 카운터. 참조 카운트는, 오브젝트가 생성 되었을 때에 1 으로 설정된다. 그 후, 인터페이스를 오브젝트에 연결시킬 수 있을 때마다 인크리먼트(increment) 되어 인터페이스 접속이 절단 되면(자) 감소 된다. 참조 카운트가 0 이 되면(자), 오브젝트는 파기된다. 파기된 오브젝트에의 인터페이스는 모두 무효가 된다.
리젼 (region)
DLS 에서는, 악기의 음색을 합성할 때에, 그 디지털 샘플이 사용되는 음색의 범위.
루트 프레임 (root frame)
Microsoft® Direct3D® 에서의, 친프레임을 가지지 않는 (즉, 프레임의 계층 구조의 최상정도에 위치한다) 프레임. 루트 프레임에는, 장면을 구성하는 일련의 오브젝트 모든 것이 저장 된다. 「장면」을 참조할것.
PRN
Registered Parameter Number (등록 파라미터 번호)의 약어. 등록 파라미터 번호는 MMA (MIDI Manufacturers Association)에 의해 기능에 할당할 수 있고 있어 콘트롤러를 통해 액세스 할 수 있다. 상세한 것에 대하여는, MIDI 의 사양을 참조할것.


S

포화 (saturation)
입력 및 force feedback에 대해, 축이 물리적인 극한에 이르기 전에 최소 값 또는 최대치가 취득 또는 설정되도록(듯이) 하기 위해서 실시하는, 축의 범위에 대한 조정. 범위내의 최대치가 1,000 으로, 최대 포화 포인트가 900 으로 설정되어 있는 경우, 축이 그 방향으로 90% 이동 하면, 최대치에 이른다.
장면 (scene)
가상 환경을 구성하는 일련의 오브젝트 모든 것을 가리킨다. 가시 오브젝트, 사운드, 라이트, 프레임이 포함된다. Microsoft® Direct3D® 에서는,루트 프레임내의 오브젝트 전체를 가리킨다.
스크린 공간 (screen space)
좌표가 frame buffer내의 2D (2 차원)의 위치에 직접 매핑 되고 있는 기준 프레임. 디스플레이나 그 외의 표시 디바이스에 표시하기 위한 프레임이다. 스크린 공간의 좌표는, 뷰 포토의 파라미터로부터 생성 한 트랜스 폼 행렬을 사용해 투영 공간의 좌표를 트랜스 폼 하는 것으로써 얻을 수 있다.
세칸다리사운드밧파 (secondary sound buffer)
1 개의 사운드 또는 오디오 스트림을 관리해, 그것을 프라이머리 사운드 버퍼에 대해서 재생하는 오브젝트.
시큐어 세션 (secure session)
세션에 참가하기 전에, 기존의 유저의 데이타베이스에 대해서 모든 유저가 인증된 세션. 시큐어 세션에서는, Microsoft® DirectPlay® 의 시스템 메세지는 모두 디지털 서명 되어 송신원의 신원이 확인된다. 기밀성의 높은 정보를 송신하는 특정의 시스템 메세지는 암호화된다. 1 명의 플레이어로부터 발생해, 세션내외의 모든 플레이어에게 있는 요소를 전요소에 카피해야 하는 시스템 메세지는, 우선 최초로 서버에 송신된다. 그 후, 서버는 메세지에 서명해, 세션내외의 모든 컴퓨터에 메세지를 전송 한다. 디폴트에서는, 플레이어로부터 플레이어에게로의 메세지는 서명되지 않고, 서버 경유로 루팅 되지 않는다.
센드 (send)
(명사) 세컨드 버퍼에 사운드 데이터를 송신하는 것으로 적용되는, 버퍼에 대한 사운드 이펙트.
서비스 프로바이더 (service provider)
Microsoft® DirectPlay® 가 네트워크를 개입시킨 통신을 실시하기 위해서(때문에) 사용하는 동적 링크 라이브러리. 서비스 프로바이더에는, 메세지를 송수신 하기 위해서 필요한 네트워크 고유의 코드가 모두 포함되어 있다. 각종 온라인 서비스나 네트워크 오퍼레이터는, 서비스 프로바이더를 제공하는 것으로써, 하드웨어, 프로토콜, 통신 매체, 네트워크 자원 등에 특수한 것을 사용할 수가 있다.
세션 (session)
Microsoft® DirectPlay® 로, 리모트 컴퓨터상에서 실행되고 서로 통신하고 있는 몇개의 어플리케이션의 인스턴스. 어플리케이션이 다른 컴퓨터와의 통신을 시작 하는 경우, 어플리케이션은 몇개의 세션에 속하고 있을 필요가 있다. 어플리케이션은 네트워크 위에의 기존의 세션 모든 것을 열거해, 그러한 1 개(살)에 참가하거나 새로운 세션을 생성 해, 생성 한 세션에 다른 컴퓨터가 참가하는 것을 대기하거나 할 수가 있다. 어플리케이션이 세션의 일부가 되면(자), 플레이어를 생성 해, 세션내외의 모든 플레이어와 메세지를 교환할 수 있다.
사운드 버퍼 (sound buffer)
Microsoft® DirectSound® 의 오디오 데이터를 관리하는 오브젝트.
전송원칼라 키 (source color key)
소총탄의 경우는 전송으로 카피되지 않는 색, 오버레이의 경우는 출력처에서 표시되지 않는 색.
스펙큐러 속성 (specular property)
스펙큐러 반사 속성, 라이트로부터의 입사빛의 각도와 시점에의 반사광의 각도의 양쪽 모두에 의존한 머트리얼 속성. 머트리얼의 빛의 반사 및 발색을 결정하는 속성은 4 개 있지만, 스펙큐러 속성은 그 중의 1 개(살)이다. 「앰비언트 속성」, 「디퓨즈 속성」, 및 「에미션(emission) 속성」을 참조할것.
spotlight (spotlight)
원추형의 미츠루를 추방하는 광원. 원추안에 있는 오브젝트만이 비추어진다. 원추는 2 개의 휘도를 생성한다. 중앙의 밝은 부분은 포인트 라이트와 같은 기능을 해, 주위의 어슴푸레한 부분은 주변의 어두운 그림자와 머지 된다.
스태틱 버퍼 (static buffer)
사운드 전체를 보관 유지하는세칸다리사운드밧파 . 보통, 데이터는 1 회만 기입해진다. 「스트리밍 버퍼」라고 비교하는 것.
스티키포카스 (sticky focus)
Microsoft® DirectSound® 로, 버퍼를 소유하는 어플리케이션이 입력초점을 가지고 있지 않을 때에도사운드 버퍼를 재생할 수 있는 능력. 예를 들어, 유저가 다른 어플리케이션으로 작업하고 있는 동안에도, DirectSound 어플리케이션은 사운드 버퍼를 계속 재생할 수가 있다.
스트리밍 버퍼 (streaming buffer)
사운드의 일부만을 보관 유지하는세칸다리사운드밧파 . 스트리밍 버퍼의 데이터는, 재생에 맞추어 리프레쉬 되지 않으면 안 된다. 「스태틱 버퍼」라고 비교하는 것.
신축 (stretching)
사이즈가 다른 전송 먼저 이미지를 소총탄 하는 것. 이 처리를 직접 지원 하는 하드웨어도 있다.
보폭 (stride)
피치 의 동의어. 「폭」을 참조할것.
표면 (surface)
비주얼 이미지가 저장 되는 메모리. 대부분의 경우는 디스플레이 메모리내에 놓여지지만, 시스템 메모리에 둘 수도 있다. 「복합 표면」, 「오프 스크린 표면」, 「오버레이 표면」 및 「프라이머리 표면」을 참조할것.
유지 기간 (sustain)
force feedback 이펙트의 기본 매그니튜드가 도달되고 있는 기간. 어택으로부터페이드까지의 사이.
시스템 메세지 (system message)
Microsoft® DirectPlay® 에서는, 플레이어 ID 의 DPID_SYSMSG 로부터의 메세지. 모든 시스템 메세지는 DWORD 값으로 시작된다.


T

TCP/IP 서비스 프로바이더 (TCP/IP service provider)
TCP/IP 프로토콜을 사용해 인터넷이나 근거리 통신망 (LAN) 상에서 통신을 실시하기 위해서(때문에) Windows Sockets 를 사용하는 서비스 프로바이더. 비보증 메세지에 User Datagram Protocol (UDP) 패킷을 사용해, 보증 첨부 메세지에 TCP 를 사용한다. TCP/IP 를 사용해, 1 대의 컴퓨터는, 복수의 Microsoft® DirectPlay® 세션으로서 기능할 수 있다.
테아링 (tearing)
스크린의 refresh rate가 어플리케이션의 frame rate와 동기 하고 있지 않을 때에 발생한다, 표시가 꾸불꾸불하는 것처럼 보이는 현상. 1 개의 프레임의 상부가 다른 프레임의 하부와 동시에 표시되어 2 개의 이미지의 사이에 갈라진 곳이 생긴다.
테셀레이션 (tessellation)
3D 그래픽스로 오브젝트의 표면을 삼각형 다각형에 세분화하는 것.
텍셀 (texel)
텍스쳐내의 단일의 요소. 텍스쳐가 오브젝트에 적용되었을 때, 텍셀이 스크린 위에의 픽셀에 대응하는 것은 좀처럼 없다. 어플리케이션은, 텍스쳐 필터 링을 사용해, 장면내에 픽셀을 생성 하기 위해서 시스템이 텍셀간을 보간 하는 방법을 제어할 수 있다.
텍스쳐 (texture)
Microsoft® Direct3D® 로 비주얼 오브젝트에 적용되는, 픽셀이 직사각형에 줄선 배열.
텍스쳐 블렌딩 (texture blending)
텍스쳐의 색을 맵처의 표면의 색과 조합하는 기법.
텍스쳐 좌표 (texture coordinates)
각 텍스쳐의 어느텍셀이 오브젝트의 각 버텍스에 할당할 수 있을까를 결정하는 좌표.
텍스쳐 필터 링 (texture filtering)
1 개(살) 또는 복수의 텍스쳐로부터 얻은 텍셀의 색을, 3D 프리미티브의 이미지를 구성하는 픽셀에 맵 하는 처리.
텍스쳐 매핑 (texture mapping)
텍스쳐를 오브젝트에 적용하는 것. 텍스쳐는 플랫인 이미지인데 대해, 많은 경우 오브젝트는 입방체이기 (위해)때문에, 텍스쳐는,텍스쳐 좌표와 랩핑 플래그를 사용해, 오브젝트의 표면에 맵 되지 않으면 안 된다. 「텍스쳐 좌표」 및 「랩」을 참조할것.
스래싱 (thrashing)
다음의 프레임으로 텍스쳐 메모리를 재이용하도록, 현재의 프레임으로 사용한 텍스쳐를 삭제하는 것.
슬롯 링 (throttling)
원의 전송 형태보다 메세지를 빨리 송신하지 않게, 메세지수를 제한하는 것.


U

단위벡터 (unit vector)
매그니튜드 (길이) 1.0 의 벡터.
USB
Universal Serial Bus (USB)의 약어.


V

VBI
Vertical Blanking Interval (수직귀선소거 간격)의 약어. 어느 요소를 전요소에 카피하는 비디오에서는, 비디오 프레임간에 짧은 시간이 있다. 이전에, 디스플레이 디바이스는 다음의 프레임을 위해서(때문에) 디스플레이를 리프레쉬 한다.
velocity (velocity)
뮤직에서는, MIDI 키가 밀리는 속도. 이 속도는, 몇개의 음색의 틴바로 노트가 재생되는 동적 레벨과 대충 같다.

3D 사운드에서는, 돕라시후트를 계산하기 위해서 사용되는, 음원 또는 청취자가 이동하고 있다고 보여지는 경우의 속도.

버텍스 (vertex)
3D 공간의 포인트.
비디오 프레임 (video frame)
비디오 스트림내의 단일의 이미지. 1 개의 홀수 필드와 1 개의 짝수 필드로부터 완성된다. 「필드」를 참조할것.
뷰 공간 (view space)
「카메라 공간」을 참조할것.
뷰 트랜스 폼 (view transformation)
모델의 버텍스에 행렬을 적용해, 모델의 방향을월드 공간으로부터뷰 공간에 바꾸는 트랜스 폼.
시추대 (viewing frustum)
뷰 포토의카메라에 대해서 상대적으로 배치된 장면내의 3D 볼륨. 시추대안에 있는 오브젝트는, 화면에 표시된다. 원근 뷰에서는,전방 클립면과후방 클립면의 사이에 있는 가상적인 피라미드형의 볼륨이 된다. 정 쏘아 맞히고 뷰에서는, 입방체가 된다.
뷰 포토 (viewport)
3D 신이 어떻게 2D 윈도우에 렌더링 될까를 결정하는 직사각형. 뷰 포토는, 디바이스상에서의, 오브젝트가 렌더링 되는 영역도 결정한다.
VREF
Vertical REFresh (수직 리프레쉬)의 약어. VREF 는, 비디오 스트림내에서, 디스플레이가 새로운 화면을 시작 하려고 하고 있는 것을 알릴 때 액티브하게 된다. 「HREF 」를 참조할것.


W

폭 (width)
메모리내에 저장 되고 있는 비트 맵의 1 개의 라인의 시점을 나타내는 주소와 그 라인의 종점을 나타내는 주소의 거리. 이 거리는, 메모리내에서의 비트 맵의 폭만을 나타내는 것이다. 직사각형 메모리내의 캐쉬 등, 비트 맵의 다음의 라인의 시점에 이르기까지 필요한 것 같은 여분의 메모리는, 이 거리에는 포함되지 않는다.
월드 좌표 (world coordinates)
장면의 버텍스에 이르는 상대 좌표. 「모델 좌표」 및 「월드 공간」을 참조할것.
월드 공간 (world space)
월드 좌표 (3D 신내의 단일의 원점에 대한 상대적인 버텍스를 나타낸다)에 의해 사용되는 기준 프레임.
월드 트랜스 폼 (world transformation)
모델의 버텍스에 행렬을 적용해, 모델의 방향을모델 공간에서월드 공간에 바꾸는 트랜스 폼.
랩 (wrap)
면이나 메쉬의텍스쳐 좌표의 계산에 사용되는 프로시저. 기본적인 랩핑 타입에는, 플랫, 원기둥(실린더), 구(공)장, 크롬이 있다.


X, Y, Z

Z 버퍼 (z-buffer)
장면 위에의 각 픽셀의 깊이를 저장 한 버퍼. z 값의 작은 픽셀은 z 값의 큰 픽셀을 덧쓰기한다.
Z 화이팅 (z fighting)
「후리마링」을 참조할것.


Locator 오브젝트

Locator 오브젝트에는 튜닝 공간의 정보가 들어간다. Locator 오브젝트는 보통 네트워크 프로바이더에 의해 사용되어 튜너에 의한 전송 스트림의 발견과 취득을 돕는다. 어플리케이션은 디버그의 목적 이외에는 Locator 오브젝트를 아마 사용하지 말고 있을것이다.

메소드명 또는 프로퍼티명 | 설명
CarrierFrequency | 캐리어 주파수 (십 Hz)의 설정 혹은 취득.
Clone | locator를 카피한다.
InnerFEC | 내부 FEC 타입의 설정 혹은 취득.
InnerFECRate | 내부 FEC 레이트의 설정 혹은 취득.
Modulation | 변조 타입의 설정 혹은 취득.
OuterFEC | 외부 FEC 타입의 설정 혹은 취득.
OuterFECRate | 외부 FEC 레이트의 설정 혹은 취득.
SymbolRate | QPSK 심볼 레이트의 설정 혹은 취득.

Locator.CarrierFrequency 프로퍼티

Locator 오브젝트

캐리어 주파수 (십 Hz).

구문

Locator. CarrierFrequency

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조

Locator.Clone 메소드

Locator 오브젝트

locator를 카피한다.

구문

Locator. Clone(NewLocator);

파라미터

NewLocator paramDesc

반환값

주의

참조

Locator.InnerFEC 프로퍼티

Locator 오브젝트

내부 FEC 타입.

구문

Locator. InnerFEC

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조

Locator.InnerFECRate 프로퍼티

Locator 오브젝트

내부 FEC 레이트.

구문

Locator. InnerFECRate

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조

Locator.Modulation 프로퍼티

Locator 오브젝트

변조 타입.

구문

Locator. Modulation

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조

Locator.OuterFEC 프로퍼티

Locator 오브젝트

외부 FEC 타입.

구문

Locator. OuterFEC

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

참조

Locator.OuterFECRate 프로퍼티

Locator 오브젝트

외부 FEC 레이트.

구문

Locator. OuterFECRate

주의

이 프로퍼티는, 읽고 쓰기 가능한 프로퍼티이다.

Locator.SymbolRate 프로퍼티

Locator 오브젝트

QPSK 심볼 레이트를 설정 혹은 취득한다.

구문

Locator. SymbolRate

주의

이 프로퍼티는 읽고 쓰기 가능한 프로퍼티이다. QPSK 는 RF 신호에 심볼을 변조한다. 이러한 심볼은 원상회복기에 의해 검출되어 비트 스트림을 재구축 하는데 사용된다. OPSK 는 변경을 위해서(때문에) 변조/복조되는 레이트를 허가한다.

참조


기준 타임

Microsoft® DirectShow® 편집 서비스 (DES)는, 2 개의 포맷을 사용해 기준 타임 (REFERENCE_TIME 값 및 REFTIME 값)을 지정한다.

  • REFERENCE_TIME : 거의 100 나노초를 나타내는 LONGLONG (64 비트 부호 없음 정수) 값 (1 나노초는 1 X 10-9 초이며, 따라 1 초는 1 X 107, 또는 10,0000,000 기준 타임이다).
  • REFTIME : 초수를 나타내는 소수를 나타내는 배정밀도 부동 소수점수(실수).

메소드에 의해,REFERENCE_TIME 파라미터를 취하는 것과 REFTIME 파라미터를 취하는 것이 있다. 또, 기준 타임의 2 개의 타입 마다 다른 버젼을 가지는 메소드도 있다.


DirectShow 에 의한 DVD 어플리케이션의 개발

Microsoft® DirectShow® 는, DVD 의 조작에 있어서의 저레벨의 복잡한 처리를 DVD 네비게이터 소스 필터로 불리는 컴퍼넌트에 캡슐화한다. DVD 네비게이터에게는, 본격적인 스탠드얼론 DVD 플레이어가 갖추는 모든 기능에 가세해, PC상에서 DVD 를 재생하기 위한 추가 기능이 포함되어 있다. DVD 네비게이터와 C++ 및 스크립트 기능을 사용하는 것으로, 개발자는 DVD 의 사양을 참조하는 필요없음에 완전한 기능을 가지는 DVD 플레이어를 생성 할 수 있다.

C++ 를 사용하는 개발자는, DVD 네비게이터가 공개하는 Component Object Model (COM) 인터페이스를 통해서, DVD 네비게이터를 직접 제어할 수 있다. 스크립트 언어 또는 Microsoft® Visual Basic® 를 사용하는 개발자는, MSWebDVD ActiveX® 컨트롤을 통해서 간접적으로 DVD 네비게이터를 제어할 수 있다.

주 : DirectShow 는, DVD-Video 의 조작과 재생에 필요한 필터를 모두 갖추고 있지만, MPEG-2 디코더는 포함되지 않았다. DirectShow 에 근거한 어플리케이션을 사용해 DVD 를 재생하려면 , 유저의 시스템상에 DirectShow 에 대응한 써드파티제의 하드웨어 디코더 또는 소프트웨어 디코더를 인스톨 할 필요가 있다.

여기에는, 이하의 주제가 포함된다.

  • DVD 플레이어 어플리케이션의 개발에 필요한 배경 지식
  • DVD 의 조작에 관한 주제
  • C++ 에 의한 DVD 플레이어 어플리케이션의 개발
  • C++ 어플리케이션용 DVD API 레퍼런스
  • 스크립트에 근거한 DVD 플레이어 어플리케이션의 개발
  • MSWebDVD ActiveX 컨트롤 API 레퍼런스


A

아드바이즈 (advise)
일정시간이 경과하고 있는 비동기 통지에 대한 요구.
알파 (alpha)
픽셀의 불투명도를 나타낸다. 픽셀이 최대 알파값의 경우는 불투명, 알파값 0 의 경우는 투명, 중간의 값의 경우는 반투명이다.
어플리케이션 통지 (application notification)
어플리케이션이 이벤트 통지 큐로부터 취득하는 이벤트.
비동기 리더 필터 (asynchronous reader filter)
독자적으로 해석은 실시하지 않고, 미디어 파일로부터 단지 데이터를 읽어들이는 파일 소스 필터.
ATR
오디오 테이프 레코더.


B

배킹 오브젝트 (backing object)
멀티미디어 스트리밍에서는, 비디오용의 Microsoft® DirectDraw® 표면 또는 오디오용의 IAudioData 오브젝트의 어느 쪽인지이다.
바이페즈마크 (bi-phase mark)
직사각형파에 encode 되는 클락 타이밍 및 비트 스트림 데이터등의 디지털 데이타를 encode 하는 방법. 광범위한 연주 속도로 읽어들여 가능하기 때문에, (원래는 Manchester-1 코드로서 알려진다) LTC 신호용으로 사용된다.
블랙 burst (blackburst)
복수의 비디오 소스의 동기에게 사용할 수 있는 비디오 신호. 블랙 burst에는, 수직 동기, 수평 동기, 및 크로마바스트의 정보가 포함되지만, 액티브한 화면 정보는 포함되지 않는다.
소총탄 (blit)
비트의 블록 전송. 메모리나 스크린등의 소스로부터 전비트 맵 또는 비트 맵의 일부를, 다른 메모리나 디스플레이 표면등의 송신지에 전송 하기 위해서 사용된다.
Bob
인터레이스 비디오 필드를 프로그래시브 모니터상에 표시하는 방법. Bob 모드에서는, 1 개의 필드가 한 번에 표시되어 짝수의 선과 홀수의 선이 교대로 된다. 선은, 디스플레이 영역 전체에 적합하도록(듯이) 2 배에 늘려진다.


C

체이스 모드 (chase mode)
비디오 테잎 레코더 및 그 외의 전송에 있어서의 처리 모드. 이 모드로, 1 개(살) 또는 복수의 디바이스가 마스터 디바이스에 동기 된다.
크로마바스트 (chroma burst)
비디오의 액티브한 라인에 관한 색정보를 칼라 디코더에 제공한다.
CODEC
압력/데콘프렛사.
칼라 키 (color key)
투명 이펙트나 반투명 이펙트에 사용되는 색을 나타내는 값. 예를 들어, 하드웨어의 소총탄 기능을 사용했을 경우, 직사각형 영역내의 칼라 키로서 설정된 값을 가지는 픽셀 이외의 모든 픽셀이 소총탄 된다. 이것은, 직사각형이 아닌 스프라이트를 표면상에 생성 한다.
합성 (composition)
트럭 및 (옵션으로서) 그 외의 합성의 콜렉션. 렌더링시, 합성의 소스는 1 개의 이미지에 합성된다.
압축 필터 (compression filter)
데이터를 받아, 압축 스킴을 사용해 데이터를 변환해, 압축된 데이터 다운 스트림을 건네주는 변환 필터의 특수한 타입.


D

디버그 빌드 (debug build)
가장 크고, 속도의 늦은 타입의 빌드. 다만, 새로운 코드의 디버그 및 문제의 추적에 대해서 충실한 기능을 제공한다.
디버그 레벨 (debug level)
디버그의 출력에 대해서 상대적인 중요성을 나타내는 DWORD 값. 값제로 (0)는 가장 중요한 레벨.
DIB 순서 (DIB sequence)
비디오내가 연속하는 프레임일 것 같은, 순서내에서 렌더링 되는 일련의 DIB (device-independent bitmap) 이미지.
다운 샘플 (downsample)
아베레이징등의 처리를 적용하는 것에 의해, 샘플 또는 픽셀의 수를 감소시킨다.
다운 스트림 필터 (downstream filter)
업 스트림 필터로부터 다음에 데이터를 취득하는 필터. 업 스트림 필터는, 출력 핀으로부터, 접속되고 있는 다운 스트림 필터의 입력 핀에 데이터를 송신한다.


E

EDL (Edit Decision List)
이벤트로 불리는 항목의 리스트. 이 리스트에는, 비디오 및 오디오의 소재 (소스 머트리얼)를 식별하는 SMPTE 타임 코드를 사용해, 비디오 순서, 오디오 순서 또는 그 양쪽 모두가 나타난다.
이펙트 필터 (effect filter)
미디어의 종류는 변경하지 않고 , 이펙트를 미디어 데이터에 적용하는 필터.
엔드 오브 스트림 프로토콜 (end-of-stream protocol)
필터가 엔드 오브 스트림 정보를 생성해 처리하는 방법, 및 필터 그래프 매니저에 통지되는 방법을 정의하는 프로토콜.
에러 검출 및 에러 보고 프로토콜 (error detection and reporting protocol)
필터로 에러가 처리되는 방법 및 필터 그래프 매니저에 에러가 통지되는 방법을 정의하는 프로토콜.
이벤트 통지 (event notification)
필터로부터 필터 그래프 매니저에 송신되는 시스템 정의의 이벤트.


F

필드 (field)
인터레이스 비디오 프레임의 일부. 인터레이스 비디오에서는, 짝수 필드의 주사선은, 홀수 필드의 주사선간의 중간에 존재한다.
파일 라이터 (file writer)
멀티플렉서와 파일 라이터 필터로부터 완성되는 필터 그래프의 섹션.
flushing 프로토콜 (flushing protocol)
필터가 필터 그래프를 통해 데이터를 플래시 하는 방법을 정의하는 프로토콜.
포맷 타입 (format type)
포맷 블록의 컨텐츠를 나타내는 GUID.
프레임 소총탄 (frame blitting)
미디어 데이터를 프라이머리 표면 위에의 어플리케이션 윈도우의 클라이언트 영역에 소총탄 (비트 블록 전송) 하는 것.


G

감마 (gamma)
전압 레벨의 변화를 형광체 디스플레이 화면상의 휘도 레벨의 변화에 맵 하는 기능의 곡선. 휘도에 특정의 변화를 주기 위해서(때문에) 필요한 전압 레벨의 변화는, 전압 레벨에 따라서 다른 경우가 있다.
그룹 (group)
합성 및 트럭의 최상정도 레벨의 콜렉션. 모두 같은 미디어 타입을 나타내고 있다. 각각의 그룹은, 렌더링 프로젝트내에 개별의 스트림을 생성한다.


H

색상 (hue)
가시광선에 의해 생성되는 색. 록,빨강,오렌지등이 일반적인 색의 용어는 색상을 나타낸다.


I

입력 핀 (input pin)
필터에의 데이터를 받는 핀.
인텔리전트 접속
IGraphBuilder Connect,Render 와 RenderFile 를 포함한 메소드 호출내에서, 필터 그래프 매니저에 의해 이행 되는 논리. 이 논리는 다음의 어느쪽이든을 결정하는 것으로 그래프 생성의 프로세스를 자동화하는, 1 개(살)은 어느 필터가 주어진 파일 혹은 출력 핀에의 렌더링이 요구되고 있는지, 이제(벌써) 1 개(살)은 어느 중간 필터가 지정된 2 개의 핀을 접속하도록(듯이) 요구되고 있는 것인가.
미디어 타입을 변환하는 소스와 렌더러간에 필터 세트를 삽입하도록(듯이) DirectShow 에 가르친다.
인터레이스 (interlace)
2 개의 필드로 구성되는 프레임을 포함한 라스터 스캔.
인터리브 (interleaving)
파일내에서의 대응하는 비디오 프레임과 오디오 샘플의 배열. 보통, 비디오 데이터의 1 개 이상의 프레임이 오디오 데이터의 특정의 수의 샘플과 함께 파일내에 혼재한다. 인터리브는, 연주 효율 및 파일을 스트림 하는 능력에 영향을 미친다.
보간 (interpolation)
순서내의 2 개의 인식되고 있는 값간의 중간값을 추측하는 것에 의해, 분실한 정보 또는 필요한 정보를 생성하는 수학적인 방법.


K

커넬 모드 (kernel mode)
시스템에의 풀 액세스 및 비보호 액세스가 가능한 프로세서 모드. 커넬 모드로 동작하고 있는 드라이버나 thread는, 시스템 메모리 및 하드웨어에의 액세스권을 가지고 있다.
키 프레임 (key frame)
프레임의 생성에 필요한 모든 데이터를 포함한 비디오 데이터의 프레임. 대조적으로, 델타 프레임에는 마지막 키 프레임으로부터의 변경에 관한 데이터가 포함되어 있어 완전한 프레임을 생성하기 위한 충분한 정보는 포함되지 않았다.


L

지연 시간 (latency)
필터로 샘플의 처리에 걸리는 총시간.
레터박스 (letterbox)
크로핑 또는 신축을 실시하지 않고 표시 윈도우내에서 비디오를 가능한 한 큰 사이즈로 표시하는 비디오 디스플레이 포맷.
락 된 오디오 (locked audio)
특정의 배포의 뒤에 1 프레임의 오디오 샘플수가 계속되는 디지털 비디오 포맷. 예를 들어, NTSC 48kHz 의 락 된 오디오에서는, 프레임 1 에 1600 개의 샘플이 포함되어 프레임 2 ~ 5 에는 각각 1602 개의 샘플이 포함된다. 락 되지 않는 오디오에서는, 샘플수는 변경할 수 있다. 다만, 그 평균은 소정의 샘플 레이트와 동일하지 않으면 안 된다.
룩 어해드 (lookahead)
스트림의 후속의 데이터를 사용해, 현재의 데이터를 처리하는 것. 예를 들어, 다음의 키 프레임을 사용해 델타 프레임을 계산한다.
LTC
Linear Timecode (리니어 타임 코드)의 약어. 이전에는 Longitudinal Timecode 로 불리고 있었다. 타임 코드는 개별의 오디오 트럭상에 보존되어 시간폭내의 1 개의 비디오 프레임 타임이다.


M

메이저 타입 (major type)
데이터 스트림용의 미디어 데이터의 모든 클래스를 나타내는 GUID 값.
메리트 (merit)
필터 그래프 매니저가 필터에 접속하는 차례를 제어하는 값.
미디어 샘플 프로토콜 (media sample protocol)
미디어 샘플을 할당해 필터 사이에 건네주는 방법을 정의하는 프로토콜.
미디어 타임 (media time)
시크 가능한 미디어내의 위치를 나타내기 위해서(때문에) 사용되는 용어. 미디어 타임은 다양한 단위로 나타낼 수가 있어 파일의 데이터내의 위치를 나타낸다.
미디엄 (medium)
미디엄은 호스트 시스템의 디바이스간의 하드웨어 데이터 패스를 나타낸다. 이 패스는 같은 내부 카드의 2 개의 디바이스인 경우도 있다, 예를 들어, TV 카드의 크로스바와 튜너, 혹은 2 개(살)의 다른 카드간이거나 외부 디바이스간인 경우도 있다. Windows® 드라이버 모델로 커넬 모드 필터의 핀을 접속 하면 와, 그 접속이 하드웨어로 제공되고 있는 고유의 데이터 패스를 베이스로 하고 있다면 미디엄은 미디어 타입 대신에 사용된다.
단조 증가 혹은 단조 감소 (monotonic)
결코 증가 또는 감소하지 않는 순서를 나타낸다. 단조 증가하는 순서에서는, 각 요소는 전의 요소와 동일한지, 또는 크다. 단조 감소하는 순서에서는, 각 요소는 전의 요소와 동일한지, 또는 작다.
멀티플렉서 (MUX)
복수의 입력 스트림을 1 개의 출력 스트림에 결합하는 필터.


N

신세그먼트(segment) 프로토콜 (new segment protocol)
데이터에 앞서 시작 타임과 종료 타임, 및 데이터 레이트 정보를 필터에 나타내는 방법을 정의하는 프로토콜. 이것에 의해, 필터는 상황에 따라 처리를 조절할 수 있다.
NTSC
국제 텔레비젼 시스템 위원회 (National TV Systems Committee) 아날로그 합성 컬러 텔레비전 존 규격. 속도는 29.97 프레임/초, 59.94 필드/초. 북아메리카, 일본, 및 그 외 많은 나라에서 NTSC 를 채용하고 있다.


O

출력 핀 (output pin)
데이터를 그 외의 필터에 건네주는 핀.


P

PAL
아날로그 합성 컬러 텔레비전 존 규격. 속도는 25 프레임/초, 50 필드/초. 주로 유럽, 오스트레일리아, 및 그 외의 지역의 일부에서 채용되고 있다.
빵-스캔 (pan-scan)
비디오의 제작자가 정의한 파라미터를 사용해, 16 × 9 의 비디오 화면을 잘라, 4 × 3 의 윈도우에 표시하는 DVD 의 비디오 디스플레이 포맷.
퍼서 필터 (parser filter)
비동기 파일 리더 필터를 사용해 디스크로부터 정보를 추출하는 필터. 또는, URL 모니카피르타를 사용해 인터넷으로부터 정보를 추출하는 필터.
주기적 아드바이즈 (periodic advise)
일련의 일반적인 아드바이즈의 호출.
피크세르다브링 (pixel doubling)
이미지를 2 배에 스케일링 하는 것.
PID
필터 그래프의 필터를 열거하는 것에 의해, 컨트롤 인터페이스를 공개해, 이행 하는 오브젝트. 같은 인터페이스를 공개하는 필터를 검색해, 그러한 필터 끼리가 직접 교환한다.
프리로르 (preroll)
목적의 재생 시간 또는 재생 위치에 앞서는 데이터의 기다리는 행렬.
프리로르타임 (preroll time)
랜덤이 아닌 액세스 디바이스가 롤링을 시작 해야 할 시작 위치보다 전의 시간.
프레젠테이션 시간 (presentation time)
필터가 취득하는 데이터 패킷이 다운 스트림 되어 렌더링 되는 스트림 타임.
프리뷰 섹션 (preview section)
캡춰 필터의 프리뷰 핀 다운 스트림으로부터 비디오 렌더러를 포함한 필터 그래프의 일부.
프라이머리 표면 (primary surface)
모니터에 표시되는 이미지가 저장 되는 메모리 영역. Microsoft® DirectX® 에서는, 프라이머리 표면은, 프라이머리 DirectDrawSurface 오브젝트에 의해 나타내진다.


Q

품질 컨트롤 (quality control)
실행시의 조건에 맞추어 데이터 플로우의 속도를 조정하는 메카니즘.
품질 세면대 (quality sink)
품질 컨트롤 메세지를 받아들이기 위해서(때문에) 지정되는 오브젝트.


R

기준 클락 (reference clock)
클락을 제공해, 필터 그래프내에서 이벤트의 스케줄링을 지원 하는 오브젝트.
기준 타임 (reference time)
필터 그래프의 기준 클락에 의해 생성 되는 절대 시간.
REFTIME
초수를 나타내는 double 타입의 부동 소수점값.
렌더러 (renderer)
미디어 데이터를 컴퓨터 모니터, 사운드 카드, 파일등의 장소에 렌더링 하는 필터.
리테일 빌드 (retail build)
가장 작고, 속도의 빠른 타입의 빌드. 일반적으로 디버그 빌드에 비해 견뢰성이 부족하다.


S

채도 (saturation)
색의 순도. 완전에 섞여 가 없는 색은 포화도 100 퍼센트로서 나타내진다. 포화도가 낮아질수록, 색은 그레이에 근처 된다.
SECAM
아날로그 합성 컬러 텔레비전 존 규격. 속도는 25 프레임/초, 50 필드/초. 유럽이 많은 나라, 오스트레일리아, 및 그 외의 지역에서 채용되고 있다.
시크 가능한 렌더러 (seekable renderer)
필터 위에의 시크 가능한 스트림이 스트림의 종단에 도착했을 경우에 EC_COMPLETE 를 보고하는 렌더러.
서보 (servo)
VCR 의 비디오 헤드의 적절한 속도와 국면 및 테이프 전송을 유지하는 전자 시스템.
세면대 파일 (sink file)
미디어 샘플이 기입해지는 현재의 파일.
소스 필터 (source filter)
하드 드라이브, 네트워크, 인터넷등의 소스로부터 데이터를 받아, 필터 그래프에 건네주는 필터.
스마트재압축 (smart recompression)
포맷이 출력 포맷과 적합하지 않는 경우만, 원시 파일을 압축 및 재압축하는 것.
스트림 통지 (stream notification)
미디어 스트림으로 발생해, 1 개의 필터로부터 다음의 필터에게 건네지는 이벤트.
스트림 타임 (stream time)
필터 그래프가 마지막에 시작 되고 나서의 시간. 정의에서는, 스트림 타임은, 기준 타임부터 전의 시작 타임을 당긴 값과 동일하다. 스트림 타임은, 실행하고 있는 필터 그래프에만 관계가 있다.
서브 타입 (subtype)
데이터 스트림용의 미디어 데이터의 특정의 포맷을 기술하는 GUID 값. 마이너 타입이라고도 불린다.
동기 포인트 (synchronization point)
그 외의 샘플을 검증하지 않고 디코드할 수 있는 미디어 샘플. 예를 들어, 키 프레임 등.


T

테아링 (tearing)
표시되고 있는 1 개의 비디오 프레임에 2 개가 다른 소스의 비디오 프레임의 일부가가 포함되어 있는 경우에 발생하는, 갈라진 곳이 보이는 현상. 보통, 비디오의 렌더링이 그래픽스의 표시와 적절히 동기되어 있지 않을 때에 생긴다.
타임 스탬프 (time stamp)
기록된 시간과 재생 시간을 나타내는 미디어 샘플의 시간. 타임 스탬프는, 100 나노초단위 (REFERENCE_TIME)로 측정되어 정규화된다. 제로 (0)는 그래프가 실행될 때를 나타낸다.
타임 코드 (timecode)
비디오나 오디오 스트림에 적용되는 디지털 프레임의 주소 (번지) 값, 플래그, 및 부가적인 데이터. ANSI/SMPTE 12-1986 로 정의된다. 비디오 및 오디오용으로 머신으로 읽어들여 가능한 주소를 제공하는 것이 목적. SMPTE 타임 코드라고도 불린다.
타임 라인 (timeline)
비디오 편집 프로젝트의 루트 노드. 프로젝트내의 그 외 모든 오브젝트의 컨테이너.
트럭 (track)
한결같은 미디어 (오디오 또는 비디오)를 사용한 오버랩 하지 않는 소스의 콜렉션.
변환 필터 (transform filter)
데이터를 취득해 처리해, 필터 그래프의 다음의 필터에 건네주는 필터.
변환 인플레이션 의자 필터 (transform-inplace filter)
데이터의 카피나 데이터의 미디어 타입의 변경을 실시하지 않고 , 그 자리에서 처리를 실행할 수 있는 변환 필터.
전송 (transport)
오디오 데이터, 비디오 데이터, 또는 그 양쪽 모두를 외부 디바이스로부터 컴퓨터, 및 컴퓨터로부터 외부 디바이스에 건네주는 메카니즘.


U

업 샘플 (upsample)
보간등의 처리에 의해, 샘플 또는 픽셀의 수가 증가하는 것.
업 스트림 필터 (upstream filter)
데이터를 출력 핀으로부터, 필터 그래프의 다음의 필터의 접속되고 있는 입력 핀에 건네주는 필터.
URL 모니카피르타 (URL moniker filter)
인터넷 서버-로부터 읽어들이는 소스 필터.
유저 비트 (userbits)
SMPTE 타임 코드로 정의되어 있지 않은 비트. 이러한 비트는, 유저가 encode 하고 싶은 임의의 정보에 사용할 수 있기 (위해)때문에, 포스트프로덕션 처리중 소스 머트리얼과 함께 이동한다. 유저 비트에는, 오리지날 필름 및 오디오 테이프 정보가 포함되는 경우가 있다.


V

VITC
Vertical Interval Timecode 의 약어. 비디오 신호의 수직 동기 간격에 저장 되는 타임 코드 정보. 보통, 라인 10 에서 20 의 1 개 또는 2 개의 라인상에 배치되고 있다.
수직 동기 간격 (vertical blanking interval)
액티브한 화면 정보가 전송 되지 않을 때의 비디오 신호의 동기 기간.
가상 트럭 (virtual track)
합성내에서 트럭으로서 동작할 수 있는 오브젝트. 합성 및 트럭은 가상 트럭.
VPE
비디오 포토 extension. VGA 메모리의 문맥내에서 비디오 포토로부터 비디오 스트림을 제어하는 Microsoft® DirectDraw® API (어플리케이션 프로그래밍 인터페이스)의 extension.
VTR
비디오 테잎 레코더.


W

Weave
인터레이스 비디오 필드를 프로그래시브 모니터상에 표시하는 방법. Weave 모드에서는, 2 개(살)이 연속하는 필드가 한 번에 표시된다. 수평의 주사선이 2 개의 필드간에서 교대로 반복해진다.
화이트 밸런스 (white balance)
오리지날 이미지의 흰 영역이 흰색으로서 올바르게 표시되도록(듯이), 이미지의 칼라 레벨을 조정하는 것.


GLOSSARY HEAD

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


CDisp 클래스

CDisp 클래스의 계층

CDisp 클래스는, 디버그용의 다양한 데이터형을 표시하는 메소드를 제공한다. 이 클래스는, 각 형의 constructor　 　 을 제공해, 디버그문의 캐릭터 라인으로서 사용하기 위한 LPCTSTR 형에 캐스트 할 수 있다.

예를 들어, 다음과 같은 코드를 생각해 본다.

int MyFunc(REFERENCE_TIME rt, IPin *pPin)
{
DbgLog((LOG_TRACE, 2, TEXT("MyFunc(%s, %s)"),
(LPCTSTR) CDisp(CRefTime(rt)),
(LPCTSTR) CDisp(pPin)));
...
}

이 코드는, 다음과 같은기준 타임 및 핀 정보를 디버그 로그에 출력한다.

Quartz.dll(tid d7) :MyFunc(1.003 sec,
CLSID_AudioRender(Audio Input pin (rendered)))

멤버 함수

CDisp CDisp 오브젝트를 생성 한다.

연산자

LPCTSTR 디버그 캐릭터 라인으로 사용하기 위해서 LPCTSTR 형에 캐스트 한다.

CDisp::CDisp

CDisp 클래스

CDisp 오브젝트를 생성 한다.

구문

CDisp(
LONGLONG ll,
int Format = CDISP_HEX
    );
CDisp(
REFCLSID clsid
    );
CDisp(
double d
    );
CDisp(
CRefTime t
    );
CDisp(
IPin *pPin
    );

파라미터

ll
표시용의 LONGLONG 형의 값.
Format
값을 10 진법 (CDISP_DEC)으로 표시하는지, 16 신법 (CDISP_HEX) (디폴트)로 표시하는지를 나타내는 값.
clsid
표시하는 클래스 식별자.
d
표시하는 double 형의 값.
t
표시하는 기준 타임. REFERENCE_TIME 형의 값의 수수에서는, LONGLONG constructor　 　 을 사용한다.
pPin
핀을 "CLSID of the filter(Pin name)" 의 포맷으로, CLSID_AudioRenderer(Audio 입력 핀)와 같이 표시하는 IPin 인터페이스에의 포인터.

반환값

반환값 없음.

주의

정보를 최적인 방법으로 표시할 수 있도록(듯이)하기 위한 다양한 constructor　 　 이 준비되어 있다.

CDisp::LPCTSTR

CDisp 클래스

디버그 캐릭터 라인으로 사용하기 위해서 CDisp 오브젝트를 LPCTSTR 값에 캐스트 한다.

구문

operator LPCTSTR();

반환값

constructor　 　 으로 사용되는 변수의 캐릭터 라인 표현을 돌려준다.


CDispBasic

CDispBasic 클래스의 계층

CDispBasic 는 CDisp 클래스를 이행 하기 위해서 사용되는 내부 클래스이다.

프로텍트 데이터 멤버

m_PString | 표시되는 캐릭터 라인을 나타낸다. 이것은, 처음은 m_String 를 가리키지만, 캐릭터 라인이 큰 경우는 동적으로 할당할 수 있는 기억 영역을 가리키도록(듯이) 갱신되는 경우도 있다.
m_String [50] | 이 오브젝트의 초기 버퍼 영역.

멤버 함수

CDispBasic CDispBasic 클래스의 constructor　 　.

CDispBasic::CDispBasic

CDispBasic

이 클래스의 오브젝트를 인스턴스화한다.

구문

CDispBasic( );


DirectShow 파일 라이터 필터

비디오의 캡춰시 또는 파일의 오쏘링시에 파일을 디스크에 기입한다.

필터 인터페이스 | IAMFilterMiscFlags ,IBaseFilter ,IFileSinkFilter ,IFileSinkFilter2 ,IMediaSeeking ,IPersistStream
입력 핀 미디어 타입 | MEDIATYPE_Stream
입력 핀인타페이스 | IMemInputPin ,IPin ,IQualityControl ,IStream
출력 핀 미디어 타입 | 이용할 수 없다.
출력 핀인타페이스 | 이용할 수 없다.
필터 CLSID | CLSID_FileWriter
프로퍼티 페이지 CLSID | 프로퍼티 페이지 없음.
실행 모듈 | quartz.dll
메리트 | MERIT_DO_NOT_USE
카테고리 | CLSID_LegacyAmFilterCategory

주의

DirectShow 를 사용해 오디오/비디오 스트림을 디스크에 캡춰 하는 비디오 캡춰 디바이스는, DirectShow 파일 라이터 필터를 사용해 디스크에의 기입을 실시한다.


IConfigAsfWriter 인터페이스

IConfigAsfWriter 인터페이스는, DirectShow ASF 라이터 필터에 의해 이행 되어 필터가 파일을 기입할 때 사용하는 ASF (Advanced Streaming Format) 프로파일의 취득이나 설정을 실시하는 메소드를 갖추고 있다.

생성 된 ASF 라이터 필터에는, 입력되는 스트림에 근거해, 자동적으로 디폴트의 ASF 시청각 프로파일이 설정된다. profile 에는, bit rate, 스트림의 수와 종류, 압축 품질 등, ASF 파일의 다양한 속성이 기술되고 있다. 필터는 프로파일을 사용해, 어느 종류의 ASF 파일을 기입하는지, 몇개(살)의 입력 핀을 설정할 필요가 있는지, 어느 미디어 타입이 받아들여질까를 판단한다. 대부분의 경우는 디폴트의 프로파일을 사용할 수 있지만, 사용할 수 없는 경우, 어플리케이션은, 필터의 IConfigAsfWriter 인터페이스 메소드를 사용해 프로파일을 변경할 수 있다. ASF 프로파일의 상세한 것에 대하여는, 「Microsoft® Windows Media™ Software Development Kit (SDK)」를 참조할것. ASF 파일의 쓰는 법에 대해서는, 「DirectShow 에서의 ASF 파일의 생성」을 참조할것.

요건

Dshowasf.h, Windows Media Format SDK 가 필요하다.

vtable 순서의 메소드

IUnknown 메소드 | 설명
QueryInterface | 지원 되고 있는 인터페이스에의 포인터를 취득한다.
AddRef | 참조 카운트를 인크리먼트(increment) 한다.
Release | 참조 카운트를 감소 한다.
IConfigAsfWriter 메소드 | 설명
ConfigureFilterUsingProfileId | 시스템 프로파일 리스트의 프로파일 식별자 (ID) 인덱스를 붙여 ASF 파일을 기입하도록(듯이) 필터를 설정한다 (Windows Media Format 4.0 프로파일만).
GetCurrentProfileId | 현재의 ASF 프로파일 ID 를 취득한다 (Windows Media Format 4.0 프로파일만).
ConfigureFilterUsingProfileGuid | 지정된 정의 끝난 Windows Media Format SDK 프로파일 GUID 에 근거해 ASF 파일을 기입하도록(듯이) 필터를 설정한다.
GetCurrentProfileGuid | Windows Media Format SDK 에 의해 정의되고 있는 현재의 ASF 프로파일 GUID 를 취득한다.
ConfigureFilterUsingProfile | 지정된 어플리케이션 정의의 프로파일에 근거해 ASF 파일을 기입하도록(듯이) 필터를 설정한다.
GetCurrentProfile | 어플리케이션 정의의 ASF 프로파일을 취득한다.
SetIndexMode | 파일에 인덱스를 붙여, 파일을 시크 할 수 있도록(듯이) 할지 어떨지를 어플리케이션을 제어할 수 있도록(듯이) 한다.
GetIndexMode | 현재의 인덱스 모드를 취득한다.

IConfigAsfWriter::ConfigureFilterUsingProfile

IConfigAsfWriter 인터페이스

지정된 어플리케이션 정의의 프로파일에 근거해 ASF 파일을 기입하도록(듯이) 필터를 설정한다.

구문

HRESULT ConfigureFilterUsingProfile(
  IWMProfile *pProfile
);

파라미터

pProfile
[in] 어플리케이션 정의의 프로파일에의 IWMProfile 인터페이스 포인터.

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 성공.
VFW_E_WRONG_STATE | 그래프가 정지하고 있다.
E_POINTER | IWMProfile 인터페이스 포인터가 무효이다.

주의

IWMProfile 는 Windows Media Format SDK 로 정의되고 있다.

성공하면(자), 이 메소드는, 어플리케이션에 EC_GRAPH_CHANGED 이벤트 통지가 보내지도록(듯이) 한다.

IConfigAsfWriter::ConfigureFilterUsingProfileGuid

IConfigAsfWriter 인터페이스

지정된 정의 끝난 프로파일에 근거해 ASF 파일을 기입하도록(듯이) 필터를 설정한다.

구문

HRESULT ConfigureFilterUsingProfileGuid(
  REFGUID guidProfile
);

파라미터

guidProfile
[in] Windows Media Format SDK 헤더 파일 Wmsysprf.h 로 정의되고 있는 프로파일 GUID.

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 성공.
E_FAIL | 프로파일이 무효이다.
VFW_E_WRONG_STATE | 필터 그래프가 정지하고 있다.

IConfigAsfWriter::ConfigureFilterUsingProfileId

IConfigAsfWriter 인터페이스

시스템 프로파일 리스트의 프로파일 식별자 (ID) 인덱스를 붙여 ASF 파일을 기입하도록(듯이) 필터를 설정한다 (Windows Media Format 4.0 프로파일만).

구문

HRESULT ConfigureFilterUsingProfileId(
  DWORD dwProfileId
);

파라미터

dwProfileId
[in] Windows Media Format SDK 로 정의되고 있는 프로파일 ID.

반환값

다음의 몇개의 값을 돌려준다.
S_OK | 성공.
E_FAIL | 프로파일이 무효이다.
VFW_E_WRONG_STATE | 필터 그래프가 정지하고 있다.

주의

이 메소드는, version 4.0 의 Windows Media Format SDK 프로파일을 상정하고 있기 (위해)때문에, 사용하지 않는다. version 7.0 이후의 필터를 설정하기 위해서는,ConfigureFilterUsingProfile 또는 ConfigureFilterUsingProfileGuid 를 사용한다.

IConfigAsfWriter::GetCurrentProfile

IConfigAsfWriter 인터페이스

어플리케이션 정의의 ASF 프로파일을 취득한다.

구문

HRESULT GetCurrentProfile(
  IWMProfile **ppProfile
);

파라미터

ppProfile
[out] 어플리케이션 정의의 프로파일에의 IWMProfile 인터페이스 포인터를 받는 포인터의 주소.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는,HRESULT 에러 코드를 돌려준다.

주의

메소드가 성공하면(자), 돌려주어지는 IWMProfile 포인터가 참조 카운트를 남긴다. 사용 수렵시에 인터페이스의 해방에 주의 해야 한다.

IConfigAsfWriter::GetCurrentProfileGuid

IConfigAsfWriter 인터페이스

현재의 ASF 프로파일 ID 를 취득한다.

구문

HRESULT GetCurrentProfileGuid(
  GUID *pProfileGuid
);

파라미터

pProfileGuid
[out] 프로파일 ID 를 받는 GUID 형의 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는,HRESULT 에러 코드를 돌려준다.

IConfigAsfWriter::GetCurrentProfileId

IConfigAsfWriter 인터페이스

현재의 ASF 프로파일 ID 를 취득한다 (Windows Media Format 4.0 프로파일만).

구문

HRESULT GetCurrentProfileId(
  DWORD *pdwProfileId
);

파라미터

pdwProfileId
[out] 현재의 프로파일 ID 를 받는 DWORD 형의 변수에의 포인터.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는,HRESULT 에러 코드를 돌려준다.

주의

이 메소드는, version 4.0 의 Windows Media Format SDK 프로파일을 상정하고 있기 (위해)때문에, 사용하지 않는다. version 4.0 및 7.0 이후의 프로파일을 올바르게 식별하기 위해서는,GetCurrentProfile 또는 GetCurrentProfileGuid 를 사용한다.

IConfigAsfWriter::GetIndexMode

IConfigAsfWriter 인터페이스

현재의 인덱스 모드를 취득한다.

구문

HRESULT GetIndexMode(
  BOOL *pbIndexFile
  );

파라미터

pbIndexFile
[out] 인덱스 모드의 설정을 받는 BOOL 형의 변수에의 포인터. TRUE 는, ASF 라이터가, 인덱스가 붙은 파일을 기입하도록(듯이) 설정되어 있는 것을 나타낸다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는,HRESULT 에러 코드를 돌려준다.

주의

이 메소드를 사용해, ASF 라이터가, 현재, 인덱스 첨부의 ASF 파일을 기입하도록(듯이) 설정되어 있는지 어떤지를 판별한다. 상세한 것에 대하여는, 「SetIndexMode 」의 「주의」를 참조할것.

IConfigAsfWriter::SetIndexMode

IConfigAsfWriter 인터페이스

파일에 인덱스를 붙여, 파일을 시크 할 수 있도록(듯이) 할지 어떨지를 어플리케이션을 제어할 수 있도록(듯이) 한다.

구문

HRESULT SetIndexMode(
  BOOL bIndexFile
);

파라미터

bIndexFile
[in] BOOL 형의 변수. TRUE 는 파일에 인덱스를 붙이도록(듯이) 지정한다.

반환값

성공했을 경우는, S_OK 를 돌려준다. 그 이외의 경우는,HRESULT 에러 코드를 돌려준다.

주의

ASF 라이터는, 디폴트로, 인덱스 첨부의 ASF 파일을 생성 한다. 인덱스부는, 그래프가 정지했을 때에 행해진다. 처리 후의 조작으로 독자적으로 인덱스부를 실시하는 경우는, 이 동작을 무효로 할 수 있다.


DVD_AudioAttributes 구조체

구조체

DVD_AudioAttributes 구조체는, 디스크의 각종 오디오 속성을 받기 위해서(때문에),IDvdInfo2::GetAudioAttributes 내에서 사용된다.

구문

typedef struct tagDVD_AudioAttributes
{
    DVD_AUDIO_APPMODE   AppMode;
    DVD_AUDIO_FORMAT    AudioFormat;
    LCID                Language;
    DVD_AUDIO_LANG_EXT  LanguageExtension;
    BOOL                fHasMultichannelInfo;
    DWORD               dwFrequency;
    BYTE                bQuantization;  0 is unknown
    BYTE                bNumberOfChannels;
    DWORD               dwReserved[2];
} DVD_AudioAttributes;

멤버

AppMode
현재의 오디오 모드를 나타낸다. 모드 DVD_AudioMode_Karaoke 가 돌려주어지는 경우는, IDvdInfo2::GetKaraokeAttributes 를 호출해 상세 정보를 취득한다.
AudioFormat
오디오 스트림의 포맷 (encode 방식)을 기술한다.
Language
오디오 스트림의 언어를 나타내는 LCID 값. 언어가 존재하지 않는 경우는 0.
LanguageExtension
디스크에 이용 가능한 정보가 있는 경우로 설정되는 DVD_AUDIO_LANG_EXT 열거형.
fHasMultichannelInfo
멀티 채널 속성이 존재할지 어떨지를 나타낸다. TRUE 는 SurroundSound 등의 추가의 믹싱 정보가 이용 가능한 일을 의미한다. 멀티 채널 정보를 취득하려면 ,IDvdInfo2::GetTitleAttributes 를 호출한다.
dwFrequency
오디오 스트림의 주파수 (48 k, 96k). 단위는 Hz.
bQuantization
오디오 스트림의 해상도 (16, 20, 24 비트 등). 0 은 해상도가 불명한 것을 나타낸다.
bNumberOfChannels
채널수. 예를 들어, 5.1 Dolby AC-3 에는 채널이 3 개 있다.
dwReserved
현재는 사용되지 않는다.


퍼포먼스 매크로

Microsoft® DirectShow® base class의 Measure.h 헤더 파일은, 특정의 이벤트의 시작 타임 및 종료 타임의 순환 로그를 유지하는 것에 의해 퍼포먼스 데이터를 기록하는 매크로를 제공한다.

MSR_START | 이벤트의 시작 타임을 기록한다.
MSR_STOP | 이벤트의 종료 타임을 기록한다.

MSR_START

퍼포먼스 매크로

순환 로그에 시작 타임을 추가해 그 타임을 StatBuffer 에 기록하는 것으로써, 특정의 등록이 끝난 ID 를 가지는 이벤트의 시작 타임을 기록한다.

구문

#define MSR_START(
  int Id
  )

파라미터

Id
시작 타임을 기록하는 이벤트의 등록이 끝난 ID.

주의

이 매크로는 통계 정보를 갱신하지 않는다. 통계 정보의 갱신은,MSR_STOP 의 호출에 의해 행해진다.

MSR_STOP

퍼포먼스 매크로

순환 로그에 종료 타임을 추가해 StopTime-StartTime 엔트리를 통계 레코드 StatBuffer 에 기록하는 것으로써, 특정의 등록이 끝난 ID 를 가지는 이벤트의 종료 타임을 기록한다.

구문

#define MSR_STOP(
  int Id
  )

파라미터

Id
종료 타임을 기록하는 이벤트의 등록이 끝난 ID.


스트림 정수 함수

Microsoft® DirectShow® base class의 Pstream.h 헤더 파일은, 일식의 스트림 정수 함수를 포함한다. 이러한 함수는, 스트림 오브젝트내의 정수를, 뒤로 Unicode 의 공백이 계속되는 11 개의 Unicode™ 문자에 encode 한다. 이러한 함수에의 인터페이스는, 32 비트에의 잘라서 버림을 실시한다. (부호 없음) 0x80000000 와 같은 값은 -2147483648 과 기술되지만,ReadInt 를 사용 하면 역시 0x80000000 로서 로드 된다.

ReadInt | Unicode 캐릭터 라인에 encode 된 정수를 스트림으로부터 읽어들인다.
WriteInt | 정수를 Unicode 캐릭터 라인에 encode 된 캐릭터 라인으로서 스트림에 기입한다.

ReadInt

스트림 정수 함수

IStream 로부터 정수를 읽어들인다.

구문

STDAPI_(
  int
  )ReadInt(
  IStream *pIStream,
  HRESULT &hr
  );

파라미터

pIStream
encode 된 정수를 읽어들이는 앞의 IStream 에의 포인터.
hr
HRESULT 값 (출력)에의 참조.

반환값

(32 비트에 잘라 버릴 수 있었던) 정수값을 돌려준다. 에러가 발생했을 경우는, 제로를 돌려준다.

주의

이 함수는 sscanf 의 기능을 축소한 서브 세트로, 완전한 C 런 타임 라이브러리의 오버헤드는 없다.

ReadInt 함수는,WriteInt 에 의해 기입해진 값을 읽어내기 위해서(때문에) 사용한다.

WriteInt

스트림 정수 함수

스트림 정수 함수로 encode 된 IStream 에 정수를 기입한다.

구문

STDAPI WriteInt(
  IStream *pIStream,
  int n
  );

파라미터

pIStream
encode 된 정수를 기입하는 앞의 IStream 에의 포인터.
n
기입하는 정수값.

반환값

HRESULT 값을 돌려준다.

주의

ReadInt 함수는,WriteInt 에 의해 기입해진 값을 읽어내기 위해서(때문에) 사용한다.


Microsoft DirectX 8.0

동작환경

API 요소의 구문을 소개하는 각 주제에는, 이러한 요소를 사용할 때에 필요한, 빌드 및 실행시의 동작환경에 대한 정보가 포함되어 있다. 동작환경의 서식은, 다음과 같다.

Windows NT/2000 : Windows 2000 이후에 대한 재배포 가능 파일로서 제공.
Windows 95/98 : Windows 95 이후에 대한 재배포 가능 파일로서 제공.
Windows CE : 버젼 1.0 이후가 필요.
헤더 : winuser.h 로 선언.
임포트 라이브러리 : user32.lib 를 사용.
Unicode : Windows NT/2000 위에의 Unicode 및 ANSI 버젼으로서 이행 된다.

1 행 째로는, API 요소를 지원 하고 있는 Windows NT 의 버젼에 대한 정보가 기술되고 있다. 이 정보에는, 필요하게 되는 서비스 팩, 옵션 팩, 또는 Internet Explorer 등의 컴퍼넌트에 대한 정보가 포함된다. Windows NT 또는 Windows 2000 으로 API 요소가 지원되어 있지 않은 경우는,"Windows NT/2000 : 미대응. " 그렇다고 하는 서식에서 나타내진다.

2 행 째로는, API 요소가 Windows 95 또는 Windows 98 상에서 지원 되고 있는지 어떤지에 대한 정보가 기술되고 있다. 이 정보에는, 필요하게 되는 OEM 서비스 릴리스, 재배포 가능한가 어떤가 또는 Internet Explorer 등의 컴퍼넌트에 대한 정보가 포함된다. Windows 95 또는 Windows 98 으로 API 요소가 지원되어 있지 않은 경우는,"Windows 95/98 : 미대응. " 그렇다고 하는 서식에서 나타내진다.

3 행 째로는, API 요소를 지원 하고 있는 Windows CE 의 버젼에 대한 정보가 기술되고 있다. Windows CE 로 API 요소가 지원되어 있지 않은 경우는,"Windows CE : 미대응. " 그렇다고 하는 서식에서 나타내진다.

4 행 째로는, API 요소가 정의되고 있는 파일에 대한 정보가 기술되고 있다. 이 정보에는,. h 파일,. idl 파일, 또는 . odl 파일에 대한 정보가 포함된다. 헤더 파일이 유저에 의해 제공되는 경우는,"헤더 : 유저 정의. " 그렇다고 하는 서식에서 나타내진다.

5 행 째로는, 함수 또는 멤버에의 호출의 해결에 사용되는 파일에 대한 정보가 기술되고 있다. 이 정보에는,. lib 파일,. dll 파일, 또는 . tlb 파일에 대한 정보가 포함된다. 임포트 라이브러리가 유저에 의해 제공되는 경우는,"임포트 라이브러리 : 유저 정의. " 그렇다고 하는 서식에서 나타내진다. 임포트 라이브러리를 필요로 하지 않는 API 요소에서는, 이 행은 생략 된다.

6 행 째로는, API 요소가 Unicode (W) 버젼 및 ANSI (A) 버젼의 양쪽 모두로 지원 되고 있는지 어떤지에 대한 정보가 기술되고 있다. API 요소가 Unicode 버젼으로 지원되어 있지 않은 경우, 이 행은 생략 된다.

Built on 2000년 11월 20일